nodeagent/README.md

nodeagent

让 Mac 上的 AI 接管 Windows —— 跨机能力框架：装软件、查状态、截屏、操作键鼠、传文件，如同操作同一台电脑。

这是什么

nodeagent 把一台 Windows 机器的能力标准化成一组可授权、可审计的能力，让 Mac 上的 AI（WorkBuddy）按需调用。

它不是远程桌面，而是「能力层」：

特性	含义
结构化	每项能力都有明确的参数 schema 与返回结构，AI 无需猜命令行
可授权	零信任模式下按调用方 × 按能力精细授权，默认拒绝
可审计	谁在何时调了什么、结果如何、耗时多少，全部本地留痕
可穿透	局域网直连 / 自动发现 / 经 Hub 中转跨网段与公网
零依赖部署	被控端只需 Node.js，全部能力用原生 API 实现，无原生模块编译

能力总览

分组	能力	说明
系统	system.info · system.status · system.process.list · system.service.list · system.shell.exec · system.audit.list	信息 / 资源 / 进程 / 服务 / 命令 / 审计
软件	app.list · app.install	已装软件（注册表 + winget）、winget 静默安装
屏幕	screen.info · screen.capture	显示器信息、截屏（支持区域与缩放）
文件	fs.list · fs.stat · fs.read · fs.write	列目录 / 元信息 / 分块读 / 原子写
输入	input.mouse.move · input.mouse.click · input.mouse.scroll · input.key.type · input.key.press	键鼠控制（🔒 默认禁用）

19 项能力 · 15 个 MCP 工具 · 21 项端到端用例（CI 在真实 Windows 上验证）

快速开始

0. 构建

pnpm install
pnpm build

1. Windows 侧（被控端）

方式 A：安装包（推荐，免装 Node.js）

1. 在控制端构建安装包（需在项目目录执行）：

   cd <项目目录>            # 例如 ~/WorkBuddy/NodeAgent/nodeagent
   pnpm pack:win
   
   # 或从任意目录调用：
   node <项目目录>/scripts/pack.mjs
   

   产物：release/nodeagent-win-x64.zip（约 32MB）

2. 把 zip 拷到 Windows 并解压

3. 右键以管理员运行其中的 install.ps1

安装脚本会使用包内自带的 Node.js 运行时，自动：生成预共享密钥 → 写配置 → 放行防火墙 → 注册开机自启 → 启动 Agent，并打印密钥与连接命令。

方式 B：开发模式（本仓库）

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

2. Mac 侧（控制端）

Mac 作为控制端，不需要上面的 Windows 安装包；只需本机 Node.js 22+（brew install node）。

方式 A：装成全局命令（推荐，随处可用）

cd <项目目录>
pnpm pack:mac                        # 打包为单文件（约 1MB，免 node_modules）
bash scripts/install-macos.sh        # 安装到 ~/.local/bin 并打印 MCP 配置

装好后命令行直接可用：

nodeagent discover --wait 5          # 局域网内有哪些 Windows（免手抄 IP）
nodeagent connect 192.168.1.100 --key <密钥> --insecure --name win_a
nodeagent info

方式 B：仓库内直接调用（开发调试）

node apps/cli/dist/index.js discover --wait 5
node apps/cli/dist/index.js info

常用命令

nodeagent info | status | ps | services              # 系统与资源
nodeagent exec "Get-Service Spooler"                 # 执行命令
nodeagent install Microsoft.VisualStudioCode         # 装软件
nodeagent apps                                       # 已安装软件
nodeagent screen                                     # 显示器信息
nodeagent screenshot --out s.jpg --scale 0.5         # 截屏
nodeagent ls "C:\Users\me\Desktop" --recursive       # 列目录
nodeagent pull "C:\big.iso" --out ./big.iso          # 下载（大文件自动分块）

完整命令见下方「命令速查」。

3. 接入 AI（MCP）

在 ~/.workbuddy/mcp.json 中加入：

{
  "mcpServers": {
    "nodeagent": {
      "command": "node",
      "args": ["/绝对路径/nodeagent/apps/mcp/dist/index.js"]
    }
  }
}

之后即可用自然语言调度，例如：

• 「看看 Windows 内存够不够」
• 「Windows 上装个 VSCode」
• 「截个图看看当前画面」
• 「最近谁在操作这台 Windows」

架构

┌────────────────────┐                          ┌────────────────────┐
│  控制端 (macOS)     │ ◄──── JSON-RPC 2.0 ────► │  被控端 (Windows)   │
│  CLI · MCP Server  │        over WebSocket    │  Agent（开机自启）  │
└────────────────────┘                          └────────────────────┘
         │                                                │
         └──────────── 三种链路可选 ──────────────────────┘
          ① 局域网直连     ② UDP 广播自动发现     ③ Hub 中转（跨网段/公网）

层	内容
协议	JSON-RPC 2.0 over WebSocket，握手 hello → challenge → auth → auth_ok
鉴权	psk（HMAC 挑战-应答，默认）或 ed25519（签名挑战-应答）
授权	能力级 ACL：deny → allow → 默认拒绝
审计	JSONL 落盘 + 轮转 + 参数脱敏 + 查询能力
传输	TLS（自签证书可用 --insecure 跳过校验，鉴权另有保障）

安全模型

三层防护，逐层收窄权限：

层	机制	解决什么
认证	psk / ed25519 挑战-应答	只有持有凭据的人能接入
授权	能力级 ACL（默认拒绝）、allow_input 高危开关	接入了也不代表什么都能做
审计	操作留痕 + 调用限速	做过什么可追溯、异常频率可拦截

启用零信任（Ed25519 + ACL）

# 1. Mac 侧生成密钥对（私钥 600 权限落盘，永不外传），并打印被控端 ACL 片段
node apps/cli/dist/index.js keygen --id mac_01

# 2. 把打印的片段加入被控端 agent.json 的 acl.clients，并设 "auth_mode": "ed25519"
#    { "client_id": "mac_01", "pubkey": "...", "allow": ["system.*", "screen.*"], "deny": ["input.*"] }

# 3. 以零信任模式连接（无需预共享密钥）
node apps/cli/dist/index.js connect 192.168.1.100 --port 8765 --auth-mode ed25519 --insecure

握手后 CLI 会展示授权矩阵（🟢 已授权 / 🚫 未授权），调用未授权能力返回 E_ACL_DENIED。

其他安全默认

• input.*（键鼠控制）默认禁用，需被控端 "allow_input": true 或 install.ps1 -AllowInput
• 键盘文本经 Base64 传参、PowerShell 侧解码，杜绝内容注入；按键名走白名单映射
• 文件能力支持 fs_roots 路径白名单，越界返回 E_ACL_DENIED
• 私钥 / 预共享密钥不明文外传、不写日志；审计中敏感字段自动替换为 ***

命令速查

连接与设备

nodeagent discover --wait 5                        # 局域网发现（UDP 广播）
nodeagent connect <host> --key <K> --name win_a    # 连接并命名（自签证书加 --insecure）
nodeagent nodes                                    # 列出设备（● 标记当前）
nodeagent use win_a                                # 切换默认设备
nodeagent remove win_a                             # 移除设备
nodeagent info --node win_b                        # 临时指定目标（不改 current）

系统与软件

nodeagent info | status | ps [--limit 20] | services [--limit 20]
nodeagent exec "<命令>"                             # 执行命令，返回退出码与输出
nodeagent apps                                      # 已安装软件
nodeagent install <包名|ID>                          # winget 静默安装
nodeagent list                                      # 被控端能力清单（含授权矩阵）

图形与文件

nodeagent screen                                    # 显示器信息
nodeagent screenshot --out s.jpg [--scale 0.5] [--region x,y,w,h]
nodeagent mouse move <x> <y> [--duration 300]
nodeagent mouse click [<x> <y>] [--button left|right|middle]
nodeagent key type "<文本>" | key press ctrl c

nodeagent ls <远端路径> [--recursive] [--pattern "*.log"]
nodeagent stat <远端路径> | cat <远端路径> [--out 本地文件]
nodeagent pull <远端路径> [--out 本地文件]           # 下载（自动分块 + 原子落盘）
nodeagent push <本地文件> <远端路径> [--create-dirs]  # 上传（自动分块）

审计与密钥

nodeagent audit [--limit 20] [--type invoke|auth|acl|agent] [--client-id X] [--since <ms>]
nodeagent keygen [--id mac_01]                      # 生成 Ed25519 密钥 + ACL 配置片段

MCP 工具

工具	说明
na_system_info · na_status · na_process_list · na_service_list	系统信息与状态
na_exec · na_install · na_app_list	执行命令、装软件、列软件
na_screenshot	截屏，直接返回图片给 AI 看
na_mouse · na_key	键鼠控制（需被控端开启）
na_fs_list · na_fs_read · na_fs_write	读目录 / 读文件 / 写文件
na_audit · na_discover	查审计、发现设备

Hub 中转（跨网段 / 公网）

被控端与 Mac 不在同一局域网时，用 Hub 中转：

Mac ──► Hub（VPS / 公网）──► Windows（NAT 后也可）
           ↑ 只透传，不解密

# 1) VPS 上启动 Hub（首次启动自动生成令牌，存于 ~/.nodeagent/hub.json）
node apps/hub/dist/index.js

# 2) 被控端 agent.json 增加 —— agent 会主动外连注册，免公网 IP、免入站放行
#    "hub": { "enabled": true, "url": "wss://hub.example.com/hub/agent", "token": "<Hub 令牌>" }

# 3) Mac 侧经 Hub 接入
node apps/cli/dist/index.js connect hub.example.com --port 443 --hub-token <Hub 令牌> \
     --hub-node win_01 --key <设备密钥> --name win_01

安全边界：Hub 只做字节透传，不解析内容、不持有设备密钥 —— 控制端与被控端之间仍执行端到端握手，因此 Hub 无法窃听也无法伪造（Hub 被攻陷也不等于设备被接管）。生产环境建议在 Hub 前挂 Caddy / Nginx 终止 TLS。

开发

pnpm build        # 构建全部包
pnpm typecheck    # 类型检查
pnpm test:e2e     # 端到端测试（21 项，含 TLS / 零信任 / 发现 / 文件 / Hub）
pnpm test:windows # Windows 专属能力（服务 / 软件 / winget 真实装软件）
pnpm verify       # 对已配置的被控端跑全套验收并输出报告

三层自动化真机验证

无需手工点测：

层次	方式	覆盖
CI（推荐）	GitHub Actions windows-latest	真实 Windows 上跑协议 E2E、专属能力（Get-Service / 注册表 / winget 装软件）、install.ps1 链路、CLI 连入、MCP 工具列表
远程验收	node scripts/verify.mjs --host <IP> --key <密钥> [--insecure]	逐条验收并输出终端报告（--report report.md）
本地测试	pnpm test:e2e / pnpm test:windows	单机自举：本机起 Agent 当被控端自测

工作流见 .github/workflows/windows-e2e.yml，push 到 main 或手动触发即运行。

# 对自己真实的 Windows 机器验收（含真实装软件）
node scripts/verify.mjs --host 192.168.1.100 --port 8765 --key <密钥> --insecure \
     --with-install jqlang.jq --report verify-report.md

成本：②③ 完全免费（本机运行）；① 走 GitHub Actions 免费额度 —— 单次约 5 分钟，按 Windows 2x 计约 10 计费分钟，Free 账户每月约可跑 200 次。默认支出限额为 $0，额度用尽只会停跑、不会自动扣费。

工程结构

nodeagent/
├── packages/
│   ├── protocol/          # 协议定义：信封 / 方法 / 错误码 / 能力 schema / 校验 / HMAC / Ed25519 / ACL
│   └── client/            # 控制端库：连接、握手、调用、超时、重连、密钥、发现
├── apps/
│   ├── agent/             # Windows 被控端：监听或 Hub 外连、认证、授权、审计、能力分发
│   ├── hub/               # 中转节点：设备注册、控制端配对、字节透传（跨网段/公网）
│   ├── cli/               # macOS 控制端 CLI
│   └── mcp/               # MCP server（接入 WorkBuddy）
├── scripts/               # install.ps1 / uninstall.ps1 / verify.mjs
├── tests/e2e/             # 端到端测试
├── docs/                  # 开发文档
├── PRD.md                 # 产品需求文档
└── README.md

路线图

阶段	目标	状态
v1	命令级接管 + 装软件 + 查状态 + 基本鉴权 + CLI + MCP	✅
v2	图形接管（screen.* 截屏 + input.* 键鼠）+ 输入控制开关	✅
v3	零信任：Ed25519 身份认证 + 能力级 ACL	✅
v3+	审计日志（留痕 + 查询）+ 调用限速	✅
v4	无感体验：局域网自动发现 + 断线自动重连	✅
v5	多设备管理 + 文件传输（分块 / 大文件 / 原子写）	✅
v6	Hub 中转：跨网段 / 公网接入（被控端主动外连，穿 NAT）	✅

文档

• 产品需求文档（PRD）
• 开发文档（DEVELOPMENT） —— 协议细节、能力 schema、安全模型、各端实现指南

关键决策

决策点	结论
拓扑	局域网点对点直连为主；跨网段时经 Hub 中转（Hub 仅透传，端到端安全不受影响）
安全演进	先简化（预共享密钥 + HMAC）→ 后强化（Ed25519 + 能力级 ACL + 审计）
AI 接入	核心能力 → CLI（调试底座）→ MCP（AI 落点）
装软件	优先 winget 静默安装
Windows 部署	一键 install.ps1 + 开机自启
依赖策略	被控端零原生编译；能力全部基于系统原生 API 实现