jkooe
b9236dfaf1
按 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。
219 lines
10 KiB
Markdown
219 lines
10 KiB
Markdown
# 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` | 命令/安装执行失败 |
|
||
|
||
---
|
||
|
||
> 本方案为产品设计参考，具体实施请结合公司合规与法务要求确认。
|