commit f0f48541106f35eec72d3d24c98b1b43a19f7fb8 Author: jkooe <62494645+jkooe@users.noreply.github.com> Date: Sun Sep 27 00:32:50 2026 +0800 docs: nodeagent PRD v1.0（已认可）+ README + .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3c2a54d --- /dev/null +++ b/.gitignore @@ -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/ diff --git a/PRD.md b/PRD.md new file mode 100644 index 0000000..a890bc3 --- /dev/null +++ b/PRD.md @@ -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` | 命令/安装执行失败 | + +--- + +> 本方案为产品设计参考，具体实施请结合公司合规与法务要求确认。 diff --git a/README.md b/README.md new file mode 100644 index 0000000..4df9be7 --- /dev/null +++ b/README.md @@ -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 |