mtfyun/nodeagent
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e816c1fd39cd20634838f3d715f88fb7b747d836
nodeagent/docs/PRD.md
T
jkooe 5b69d6cec9 refactor: 项目结构与命名规范化（重写前的最后一次常规提交） 
## 改名
`scripts/run-temp.cmd` → `scripts/run-portable.cmd`
理由：它是**正式功能**（免安装、免管理员的便携启动方案），"temp" 易被误认成临时文件。
程序内文案同步：TEMPORARY launcher → PORTABLE launcher；
打包产物 README 的"【临时试用，不装也行】" → "【免安装试用，不装也行】"。

## 移动
`PRD.md` → `docs/PRD.md`
理由：文档统一放 docs/（README/CHANGELOG 按惯例留在根）。

## 同步的引用（共 11 处）
- scripts/pack.mjs：产物文件名校验 + 生成 README 的 3 处指引文案
- scripts/run-portable.cmd：自身用法注释 6 处
- README.md：目录树 + 文档链接
- docs/DEVELOPMENT.md：配套文档链接（`../PRD.md` → `PRD.md`，现已同目录）+ 目录树

## 验证
- 全仓 `run-temp` 残留 **0**；`./PRD.md`/`../PRD.md` 旧路径残留 **0**
- 7 包构建通过；单测 273 全绿；ps1-encoding 24 全绿
- `pack.mjs` 实跑通过，`run-portable.cmd` 已正确进入 Windows 产物
- `.cmd` 保持 ASCII + CRLF（94 行）；PRD.md 无内部相对链接需调整
2026-10-10 13:39:42 +08:00

10 KiB
Raw Blame History

nodeagent 产品需求文档（PRD）

跨机 AI 接管框架 —— 让 MacBook 上的 AI 无缝接管 Windows，装软件、查状态，如同操作同一台电脑

项 值
文档版本 v1.0（已认可）
作者 司南（产品经理 Agent）
日期 2026-09-27
客户 皇上（个人开发者）
项目名 nodeagent
状态 ✅ 已认可，进入开发
参考文件 《NodeBuddy-开发文档.zip》（仅作参考，非任务书）

1. 背景与痛点

核心痛点一句话：皇上在 MacBook 上使用 AI（WorkBuddy），AI 只能操作 Mac 本机；当需要「在 Windows 上装软件 / 查状态」时，AI 无法跨过去接管 Windows 完成。

# 痛点 具体表现
P1 跨机断点 AI Agent 跑在 Mac 上，无法触达 Windows 执行操作
P2 手动替代 装软件、查状态需皇上亲自切换到 Windows 操作，打断工作流
P3 无统一入口 每次都要用远程桌面/SSH 手动拼命令，无法被 AI 自动编排

2. 目标与成功指标

2.1 分阶段目标

阶段 目标 对应痛点
v1（本 PRD） 命令级接管：Mac 上 AI 能对 Windows 执行命令、装软件、查状态 P1/P2/P3
v2 图形接管：截屏传回 + 键鼠模拟，能操作 GUI 安装向导 P2
v3（理想态） 无感体验：如同操作同一台电脑，免配置、稳定常驻 全部

2.2 成功指标（可衡量）

指标 口径 v1 目标值
命令闭环成功率 成功执行并返回结果的命令 ÷ 发起命令数 ≥ 95%
装软件成功率 通过 winget/静默参数成功安装 ÷ 尝试安装 ≥ 90%（主流软件）
查状态响应时间 从发起命令到返回结果（内网） < 3s（P95）
鉴权拦截率 无正确密钥的调用被拒绝 100%

3. 名词术语

术语 定义
控制端 皇上的 MacBook，发起调用的 AI/CLI 所在端
被控端 Windows 机器，执行命令/装软件/查状态的端
Agent 常驻在 Windows 上的后台服务，接收并执行控制端指令
能力 一个可被调用的原子操作（执行命令、装软件、查状态）
预共享密钥 控制端与被控端预先约定的密钥，v1 鉴权依据

4. 需求范围

4.1 v1 包含（In Scope）

# 内容
1 Mac ↔ Windows 点对点直连（局域网）
2 命令级接管：执行 PowerShell 命令，返回结构化结果
3 软件安装：winget 优先 + 静默参数安装
4 状态查询：系统信息 / 服务 / 进程 / 磁盘 / 网络
5 基本鉴权：预共享密钥 + 传输加密
6 控制端 CLI 工具
7 MCP 接入 WorkBuddy
8 Windows 端 Agent 常驻（开机自启、断线重连）

4.2 v1 不包含（Out of Scope）

# 内容 归属
1 图形接管（截屏传回、键鼠模拟） v2
2 零信任 ACL / 能力级授权 / 审计 v2/v3
3 Hub 中枢（多设备注册/发现/路由） 后续（预留接口）
4 Android / Linux 端 后续
5 公网穿透 后续（v1 仅局域网）
6 画面串流（远程桌面级） 属 OnlyInOne 领域，不做

5. 关键决策记录

决策点 结论 理由
接管深度 先命令级 → 再图形 → 最终无感 分阶段降低复杂度，命令级最快验证核心价值
架构拓扑 点对点直连 仅两台设备，无中枢最简；预留 Hub 接口以备扩展
端优先级 Mac + Windows 同时 真实场景就是这两端，直接打通核心价值
AI 接入 核心能力 → CLI → MCP CLI 是调试/脚本底座，MCP 是 AI 最终落点，非二选一
安全等级 先简化（基本鉴权）→ 后强化（零信任） 快速跑通优先，安全分期演进

6. 用户角色与核心场景

角色：皇上（MacBook 用户，WorkBuddy 重度用户）

场景 描述
S1 装软件 皇上在 Mac 上对 AI 说「在 Windows 上装个 VSCode」，AI 通过框架调用 Windows 完成安装并回报结果
S2 查状态 皇上问「Windows 现在 CPU/内存/磁盘怎么样」，AI 查询并返回
S3 执行命令 皇上让 AI 在 Windows 上跑一条命令（如重启某服务、查日志）

7. 功能需求（FR）

验收标准统一采用 Given/When/Then（GWT）。

FR-01 连接建立与鉴权

  • 描述：控制端能发现并直连被控端 Agent，通过预共享密钥完成鉴权，传输加密。
  • 规则：连接失败/密钥错误给出明确错误码与提示。
  • 验收：Given 两端已配置同一密钥，When 控制端发起连接，Then 连接建立并返回被控端信息；Given 密钥错误，When 发起连接，Then 返回鉴权失败。

FR-02 命令执行

  • 描述：控制端发起命令，被控端执行 PowerShell 并返回结构化结果。
  • 规则：返回 exit_code / stdout / stderr / duration_ms；支持超时（默认 30s，可配）；超时强制终止进程。
  • 验收：Given 被控端在线且已授权，When 发送合法命令，Then 返回正确结果；When 发送超时命令，Then 返回超时且无残留进程。

FR-03 软件安装

  • 描述：支持通过 winget 或静默参数安装软件。
  • 规则：优先 winget；winget 不可用时走静默安装参数；返回安装结果（成功/失败 + 原因 + 版本）。
  • 验收：Given 目标软件可用，When 发起安装，Then 返回安装成功及版本号；When 软件不存在，Then 返回明确的失败原因。

FR-04 状态查询

  • 描述：查询 Windows 系统状态。
  • 规则：覆盖系统信息 / 服务 / 进程 / 磁盘 / 网络五类，返回结构化数据。
  • 验收：Given 被控端在线，When 发起各类状态查询，Then 返回对应结构化结果。

FR-05 结果反馈与错误处理

  • 描述：成功/失败/超时/鉴权失败/离线等状态均有明确反馈。
  • 规则：统一错误码（参考附录）；错误信息含可操作建议。
  • 验收：Given 被控端离线，When 发起调用，Then 返回离线错误并提示等待上线。

FR-06 控制端 CLI

  • 描述：Mac 端命令行工具。
  • 规则：覆盖 connect / invoke / install / status / list 等命令。
  • 验收：Given CLI 已安装，When 执行各命令，Then 均能正确交互并返回结果。

FR-07 MCP 接入 WorkBuddy

  • 描述：把能力包装为 MCP 工具，WorkBuddy 可直接用自然语言调度。
  • 规则：暴露 na_invoke / na_install / na_status 等工具；工具描述清晰可被 AI 理解。
  • 验收：Given WorkBuddy 已配置 MCP，When 用户自然语言下指令，Then AI 正确调用并返回结果。

FR-08 Windows 端 Agent 常驻

  • 描述：被控端后台服务。
  • 规则：开机自启、断线自动重连、崩溃自愈；占用资源低。
  • 验收：Given Agent 已安装为服务，When 重启 Windows，Then Agent 自动启动并上线；When 网络断开再恢复，Then 自动重连。

8. 非功能需求

类别 要求
性能 内网命令往返 P95 < 3s；Agent 空闲内存 < 100MB
安全（v1） 预共享密钥 + TLS 传输加密；密钥不明文落盘、不写日志
兼容 macOS（Apple Silicon）、Windows 10/11
可维护 monorepo 结构，控制端与被控端可独立构建测试

9. 业务流程（简化时序）

控制端(Mac)                    被控端(Windows Agent)
    │                                │
    │── 握手(带预共享密钥) ───────────►│  校验密钥
    │◄──── 认证通过 + 能力清单 ────────│
    │                                │
    │── invoke(命令/安装/查询) ───────►│  执行
    │◄──── 结构化结果 ────────────────│
    │                                │
    │════ 心跳保活 ══════════════════►│

10. 安全（简化 → 强化）

阶段 鉴权方式 传输 说明
v1 预共享密钥 TLS 快速跑通，防裸奔
v2 Ed25519 签名 + 能力级 ACL TLS 1.3 引入密钥对与授权
v3 完整零信任 + 审计 TLS 1.3 对齐参考文档安全模型

11. 版本规划

版本 内容 触发条件
v1 命令级接管 + 装软件 + 查状态 + 基本鉴权 + CLI + MCP 本 PRD 认可后启动
v2 图形接管（截屏 + 键鼠模拟）+ 能力级 ACL v1 稳定运行后
v3 无感体验 + 零信任 + 多端扩展 v2 验证后

12. 风险登记册

# 风险 概率 影响 应对
RK-01 装软件需管理员权限（UAC） 高 高 Agent 以服务账户运行，装软件走提权流程并回报
RK-02 图形接管（v2）复杂度高 中 高 明确 v2 范围，逐能力迭代
RK-03 局域网环境差异（发现/防火墙） 中 中 v1 采用固定 IP/端口直连，后续加自动发现
RK-04 简化安全 → 强化的迁移成本 中 中 协议层预留签名/ACL 字段，减少后期返工

13. 已确认事项（T1~T3 已拍板）

# 事项 结论
T1 项目正式命名 nodeagent（工程名/包名统一小写）
T2 装软件提权方式 优先 winget 静默安装（免人工点 GUI），winget 不可用再走静默参数
T3 Windows 端部署形态 一键安装脚本 + 开机自启服务（install.ps1）

14. 附录

14.1 参考文档说明

《NodeBuddy-开发文档.zip》提供了协议（JSON-RPC 2.0 over WebSocket）、安全（Ed25519 + ACL）、能力清单（30+ 能力）等成熟设计，本 PRD 仅抽取其中与「Mac 控 Windows」相关的最小子集，不照搬四端全栈架构。

14.2 错误码（v1 精简版）

错误码 名称 含义
-32401 E_AUTH_FAILED 密钥验证失败
-32405 E_NODE_OFFLINE 被控端离线
-32412 E_TIMEOUT 执行超时
-32419 E_EXECUTION_FAILED 命令/安装执行失败

本方案为产品设计参考，具体实施请结合公司合规与法务要求确认。

Reference in new issue View Git Blame Copy Permalink