mtfyun/nodeagent
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6b2fa297105fd4a957c50b2f0ea34dc5937812c3
nodeagent/docs/PRD.md
T
jkooe b9236dfaf1 chore(privacy): 公开仓库隐私脱敏 —— 清除可定位到个人与设备的字面量 
按 security-reports/ 的隐私审查台账逐项收口。纯脱敏与表述泛化，
不含任何业务逻辑变更；实测结论与排查步骤一字未动。

P1（可定位到具体设备/个人）
- scripts/verify-b2.mjs：NA_URL 去掉硬编码缺省值（原指向一台真实机器），改为必填。
  这是全仓库唯一「拿着就能连到某台真机」的常量。
- 测试账户名 pdverify → na-test（docs/VM-VERIFICATION.md 7 处、docs/console-plan.md 1 处）
- 虚拟机与宿主的真实网段 → RFC 5737 文档保留段 192.0.2.x（含 CLOSE_WAIT 记录）
- 跨项目名与私人称呼 → 中性表述（docs/PRD.md、docs/DEVELOPMENT.md、docs/console-plan.md 等）

P2（低风险设备指纹）
- 虚拟化产品及其 CLI / 访客工具名 → 中性表述（12 个文件 + 1 个工作流注释）
- 测试目录 C:\nodeagent-test → C:\na-test
- NAS 设备型号与系统名 → NAS 设备 / NAS 系统（docs/DEPLOY-LINUX.md、scripts/install-linux.sh、README.md）
- 真机 CPU 型号、真机物理分辨率、代理软件品牌与监听端口、杀软品牌 → 泛化
- 单元测试示例段去掉真机 IP 尾八位：acl-v11 / net-scripts 的 fixture 与断言同步更新
- .gitignore 补 config.json / agent.json（含真实密钥与节点地址，绝不入库）
- 顺带移除混入技术文档的「不构成投资建议」字样（与文档主题无关）

验证：pnpm test:unit 340/340 通过；独立扫描器对 235 个跟踪文件做 17 类模式
全量扫描，命中 0。
2026-10-13 22:35:40 +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 画面串流（远程桌面级） 属另一独立项目领域，不做

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