docs: nodeagent PRD v1.0（已认可）+ README + .gitignore

2026-09-27 00:32:50 +08:00
commit f0f4854110
@@ -0,0 +1,31 @@
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# Build output
+dist/
+build/
+out/
+*.tsbuildinfo
+
+# Logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Coverage
+coverage/
@@ -0,0 +1,218 @@
+# 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` | 命令/安装执行失败 |
+
+---
+
+> 本方案为产品设计参考，具体实施请结合公司合规与法务要求确认。
@@ -0,0 +1,32 @@
+# nodeagent
+
+> **跨机 AI 接管框架** —— 让 MacBook 上的 AI 无缝接管 Windows，装软件、查状态，如同操作同一台电脑
+
+## 这是什么
+
+nodeagent 让 Mac 上的 AI（WorkBuddy）通过统一协议接管局域网内的 Windows 机器——执行命令、装软件、查状态。
+
+## 当前状态
+
+✅ 需求已定（PRD v1.0 已认可），开发待启动。
+
+## 文档
+
+- [产品需求文档（PRD）](./PRD.md)
+
+## 分阶段路线
+
+| 阶段 | 目标 |
+|---|---|
+| v1 | 命令级接管 + 装软件 + 查状态 + 基本鉴权 + CLI + MCP |
+| v2 | 图形接管（截屏 + 键鼠模拟）+ 能力级 ACL |
+| v3 | 无感体验 + 零信任 + 多端扩展 |
+
+## 关键决策速览
+
+| 决策点 | 结论 |
+|---|---|
+| 架构拓扑 | 点对点直连（Mac ↔ Windows，无中枢） |
+| 端 | Mac + Windows 同时 |
+| 安全 | 先简化（预共享密钥）→ 后强化（零信任） |
+| AI 接入 | 核心能力 → CLI → MCP |