mtfyun/nodeagent
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
78 Commits 1 Branch 14 Tags
v1.4.2
Commit Graph
78 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
jkooe 6c650244bf chore(release): v1.4.2 v1.4.2 2026-10-05 02:51:31 +08:00
jkooe a56d67c012 fix(v22): 自更新在 Windows 上必须**就地覆写**而非 rename（真机暴露的平台差异） 
## 现象（真机 192.168.1.100 上拉取式更新）
`✗ E_EXECUTION_FAILED: 替换脚本失败` —— 下载与哈希校验都过了，挂在最后一步「替换」。

## 根因
Windows **不允许重命名/替换正被运行进程打开的文件**（EPERM/EBUSY），而 node.exe
正持有 agent.mjs。POSIX 可以 unlink 打开中的文件，所以本地（macOS）测不出来。
这也解释了为什么推送式 `deploy` 一直没问题：它走**就地覆写**，而覆写打开中的文件
在 Windows 上是允许的（只有删除/重命名被禁）。

## 修复
- 改为 `writeFileSync(scriptPath, buf)` 就地覆写（先备份 + 已校验的暂存内容）
- **写后校验**：重算入口文件 sha256，与刚校验过的下载比对；不一致立即从备份回滚
- 清理暂存文件；错误信息带上 backup_path / staged_path 便于人工兜底

## 顺带的真机结论（都已在 192.168.1.100 上验证）
- **被控端访问不了 github.com**（`fetch failed`）→ 国内网络现实；改用局域网/自建镜像即可
  （本轮用 `http://192.168.1.100:8081/...` 拉取成功 ✓）→ 故 URL 参数化是必需的，不是花活
- **拉取式更新在 Windows 上可用**（内容确实变化：构建哈希 4833b0b5 → 216328d5 ✓，
  重启后复核通过 ✓）
- **Windows 音频能力真机跑通**（Core Audio COM）：🔇 静音 · 音量 77%，可读回真实状态
- **证书指纹钉住**：普通 agent 更新不影响钉住（证书未变 → 仍一致 ✓）；只有证书重建才触发
  `E_CERT_MISMATCH` —— 符合设计意图
 2026-10-05 02:50:48 +08:00
jkooe 4106ada876 chore(release): v1.4.1 v1.4.1 2026-10-05 02:46:37 +08:00
jkooe f88738d36d fix(v22): 修正构建期注入的版本号带多余引号（真机暴露） 
## 现象
真机 `nodeagent info` 显示 `被控端版本 : v"1.4.0" @ "e841fbb"` —— 值里带了引号。

## 根因
esbuild 的 `--define:K=V` 中 **V 是按 JS 表达式解析的**。原先写成
`--define:__AGENT_VERSION__='"1.4.0"'`（单引号包裹），单引号被当成**字符串内容**，
于是运行时值变成 `"1.4.0"`（含引号）。产物内联可见：
`return false ? "dev" : '"e841fbb"';`

## 修复
改用 `JSON.stringify(v)`（纯双引号）→ 产物内联为 `return false ? "dev" : "1.4.0";` ✓
真机复核：`被控端版本 : v1.4.0 @ 50ac4b9  构建 05abbbc79abf` ✓

## 附带真机确认（v1.4.0 部署）
- 推送式部署 + **指纹校验通过**（能力 42 项、PID 16664）
- **证书指纹 TOFU 钉住生效**，且普通 agent 更新**不影响**钉住（证书未变 → 仍一致 ✓）——
  这正是设计意图：只有证书重建才会触发 E_CERT_MISMATCH
- **Windows 音频能力真机跑通**（Core Audio COM 路径）：`✓ 已应用：🔇 静音 · 音量 77%`，
  且能**读回真实状态**（确定性设置而非切换）—— 这补上了此前只在 macOS 验证的空缺
 2026-10-05 02:45:51 +08:00
jkooe 50ac4b9646 chore(release): v1.4.0 v1.4.0 2026-10-05 02:42:56 +08:00
jkooe e841fbb187 feat(v22): 第二批安全加固 —— 每客户端独立 PSK + 发现广播最小化 
接着 v21 的两件 P0，补齐第二批清单里的两项（对应原建议 ③/④ 的一半）。

## ① 每客户端一把 PSK（`agent.json` 的 `keys{}`）—— 让 ACL 的身份维度真正有效
**问题**：psk 模式下 `client_id` 由客户端自报（server.ts 原注释自认），
一把共享 key 意味着**持有者可冒充任意 client_id**，ACL 的身份维度形同虚设。

**做法**：按 `client_id` 分配独立钥匙；未登记者回落到共享 `key`（旧部署行为不变）。
比 ed25519 更轻量（不用管公钥），同样是「一把一个身份」。

**实测**（五场景全对）：
| 场景 | 结果 |
|---|---|
| alice 用自己的 key | ✅ |
| **alice 的 key 冒用 bob 身份** | ❌ E_AUTH_FAILED ← 核心安全性质 |
| bob 用自己的 key | ✅ |
| 未登记 carol 用共享 key | ✅（向后兼容） |
| 已登记 alice 用共享 key | ❌ 拒绝（专属优先，不被共享 key 绕过） |

配套：`nodeagent keygen --psk --id mac_02` 生成专属 key 并打印可直接粘贴的 agent.json 片段；
鉴权日志带 `key=scoped|shared-fallback|shared`，审计区分「专属钥匙失败」与「回落共享失败」。

## ② 发现广播最小化（`discovery.detail` + `discovery.secret`）—— 收情报泄漏
**问题**：UDP 广播未认证，默认明文告知 IP/端口/认证方式/键鼠开关，等于给攻击者一份目标清单。

**做法**：
- `detail: "minimal"` → 顶层只剩 `service / version / node_id / ts`，
  真实信息收进 `detail{}`（**实测顶层已无 host/port/auth_mode/input_enabled**）
- 配 `secret` → `detail` 带 HMAC 签名（`node_id|ts|JSON(detail)`），
  控制端 `discover --discover-secret <同一密钥>` 验签 → 列表标 **🔒 已认证**；
  未配/验签失败标 **⚠️ 明文**（明示「仅作参考、不可当凭据」）
- 配了 secret 自动启用 minimal；未配置时启动横幅**醒目告警**提示收敛

**实测**三视角：正确密钥 🔒 / 无密钥 ⚠️ / 错密钥 ⚠️（验签失败正确降级）✓

## 验证
- 单测 159 → **162**（新增签名往返一致性：错密钥/篡改详情/改时间戳均须验签失败）
- e2e **29** 全绿；本轮改动为纯加法（新增可选字段），未破坏既有行为
- 文档 `SECURITY.md` 新增 §4.5 / §4.6，并把「发现最小化」从待办划掉

## 剩余待办（SECURITY.md §5）
握手失败封禁 / 审计链签名与外部锚定 / 会话上限与空闲断开 / 安装期密钥改用文件传递 /
ed25519 仍非默认（v22 的 `keys{}` 已是更轻量的等价物）
 2026-10-05 02:42:12 +08:00
jkooe 159ae2bf6f chore(release): v1.3.0 v1.3.0 2026-10-05 02:26:21 +08:00
jkooe 0d59d6032b feat(v21): 第一批安全加固 —— 证书指纹钉住 + 来源网段白名单 
对应审查建议的 P0 两条：这两项是**真实可利用的攻击路径**，其余（发现最小化/失败封禁等）
留待后续批次。

## ① 证书指纹钉住（TOFU）—— 挡同网段中间人
自签证书没有 CA 链，历史上客户端只能 `insecure` 接受任意证书 → 攻击者可**透明中继**：
拿不到钥匙（挑战-应答挡得住冒名），但能读到截屏/剪贴板/键入/exec 输出。

- 被控端：`install.ps1` 打印证书指纹（sha256 of DER）供**带外核对**；
  `system.info.build.cert_sha256` 与 `auth_ok.build.cert_sha256` 上报
- 控制端：首次连接自动钉进 `nodes.<名>.cert_sha256`；之后**严格比对**，
  不一致即 `E_CERT_MISMATCH`(-32422) 拒连，并提示 `--forget-cert` 重钉
- 额外做**交叉确认**：实际握手证书 vs auth_ok 自报，不一致同样拒绝（防自报被篡改）
- 指纹基于 **DER**（不是 PEM 字节），保证与 Windows .NET `GetRawCertData()` 同值

**踩坑记录（写进代码注释，避免后人重走）**：
1. `ws` 客户端的 `upgrade` 事件**只传 IncomingMessage**，拿不到 socket
2. socket 要在 `open` 之后从 `ws._socket` 取（TLSSocket）
3. Node ≥15 的 `getPeerCertificate()` 返回**对象**，DER 在 `.raw` 上（老版本才是 Buffer）
   —— 现已双兼容

## ② 来源网段白名单 `allow_from` —— 收敛暴露面
被控端默认监听 `0.0.0.0`（远程接入所需），但**换到不可信网络就自动暴露**。

- 支持 CIDR / 单 IP / `*`；**未配置 = 放行全部**（保持向后兼容，不打断现有部署）
- 拒绝发生在**业务握手之前**（不做 TLS/挑战应答，省资源），并记 `net.deny` 审计
- 判定按**前缀比特**而非字符串相等：Node 在 IPv6 监听上把 IPv4 客户端报成
  `::ffff:a.b.c.d`，已归一化（单测覆盖）
- `system.info.network.allow_from` 上报状态；`nodeagent info` 一眼看出是否已收敛

## 验证（本地真跑，非纸面）
- 白名单不含本机 → 连接被拒（agent 侧 WARN + 审计留痕）✓
- 白名单含本机 → 连上，并**自动钉住**指纹 ✓
- **换掉被控端证书后重连 → `E_CERT_MISMATCH` 拒绝**（期望 2ed4957b… / 实际 ca8dc20c…）✓
- 新增 e2e 用例（自起 TLS agent）覆盖上述四种情形 + agent 自报与实际证书一致性 ✓
- 新增单测 9 例（CIDR 前缀匹配 / IPv4-mapped 归一 / IPv6 zone / PEM≡DER / 篡改即变）
- 全量：单测 **159**（150→159）· e2e **29**（28→29）全绿

## 文档
新增 `docs/SECURITY.md`：信任模型（钥匙=root）、认证现状与**已知限制**（ACL 身份维度仅在
ed25519 有效）、本次两项加固的用法、尚未收敛的 6 项、应急处置表。
 2026-10-05 02:25:19 +08:00
jkooe 3cbac53308 chore(release): v1.2.1 v1.2.1 2026-10-05 00:26:36 +08:00
jkooe 045e3b08b1 fix(sec): 安装包不再打包 PSK.txt（该 zip 会作为公开 Release 资产发布） 
## 问题
`nodeagent-win-x64.zip` 里含 `PSK.txt`（64 位预共享密钥）。而这个 zip 正是 GitHub
Release 的公开资产 —— 等于**把被控端的预共享密钥公开**。若谁用该 Release 包安装，
其密钥即为公开值，同网段的任何人都能凭此接入。

## 修复
- `pack.mjs` 打 zip 时用 `-x "PSK.txt"` 排除（并注明原因，防日后被加回）
- 不影响安装：`install.cmd` 在 PSK.txt 缺失时**本地自动生成**密钥（只留在被控端安装目录），
  这正是它头注释里既有的行为
- 新增单测守卫：断言打 zip 命令必须带 `-x PSK.txt`（防止回归）

## 兼容性
PATCH 级：仅打包内容变化，不涉及协议/能力/参数。已安装的机器不受影响。
 2026-10-05 00:25:44 +08:00
jkooe 303cbc7436 chore(release): v1.2.0 2026-10-05 00:19:29 +08:00
jkooe 1c26dc4e3f fix(release): sh() 容错 stdio:'inherit' 的 null 返回（发版首跑即炸） 2026-10-05 00:13:45 +08:00
jkooe 6faf807108 chore(release): fetch/push 统一走重试（本机 GitHub 连接间歇抖动） 2026-10-05 00:02:48 +08:00
jkooe 21d568d90d chore(release): 发版脚本加 push 重试（本机到 GitHub 连接会间歇抖动） 2026-10-04 23:57:35 +08:00
jkooe cedc46d090 feat(v20): 版本纪律 + 发版自动化（对齐「做好版本功能 + GitHub 同步资产」） 
## 一、版本功能（防新旧混用）
1. **单一版本源 + 构建注入**：根 package.json 的 version、git sha、构建时间经 esbuild
   `--define` 注入 agent；`system.info.build` 新增 `version/commit/built_at`（原有 `hash` 指纹不变）。
   开发态用 typeof 探测（未注入也不崩）。
2. **握手携带版本**：`auth_ok` 新增可选字段 `agent_version` / `build` / `protocol`（只增不减 → 旧控制端忽略即可）。
3. **能力级兼容比对**：新增纯函数 `capabilityDiff(local, remote)` ——
   - `missingOnRemote`：本地有远端没有 → **远端较旧**，提示更新被控端
   - `unknownLocally`：远端有本地没有 → **本控制端较旧**（不影响既有功能）
   控制端不比版本号而比**能力集合**：版本号可能相同而内容不同，能力集合不会骗人。
4. **CLI 体检**：`nodeagent info` / `connect` 直接显示被控端版本与能力对齐情况，
   把"调用时才炸"变成一句人话提示。

## 二、发版自动化（GitHub 资产同步）
`pnpm release <x.y.z|patch|minor|major>`：前置检查（干净/在 main/与远端同步）→ 改 7 个 package.json
→ 构建+打包 → 生成资产 → 提交打标签推送 → `gh release create` 上传。
- 资产：`agent.mjs`（**自更新载荷**）、`nodeagent-win-x64.zip`（人工安装包）、
  `latest.json`（version/commit/能力数 + 两个资产的 url 与 sha256）、`SHA256SUMS`
- `--dry-run` 无副作用演练；`--no-publish` 只到本地标签
- 能力数从 dist 动态取（避免写死漂移）；刻意排除 `.github/`（缺 workflow 权限推不了）

## 三、兼容性契约文档
新增 `docs/VERSIONING.md`：semver 各位的含义、**只增不改**六条硬规则、
升级顺序建议（**先被控端**：新被控端向后兼容旧 CLI）、两条更新路径、发版流程、排查手册。

## 验证
- 单测 147 → **149**（新增 capabilityDiff 用例：远端过旧 / 本机过旧 / 完全一致 / 真实清单自比无差异）
- e2e 28 全绿；`node scripts/release.mjs 1.0.0 --dry-run` 演练通过且工作区无副作用
 2026-10-04 23:54:51 +08:00
jkooe aa72241080 fix: 真机全量测试修 5 个 bug（剪贴板假失败 / 音频后端误标 / CLI info 打印 / key press 崩溃 / Unicode 代理对） 
在 192.168.1.100 真机逐项跑通 42 项能力，暴露并修复 5 个真 bug：

1. clip.set 假失败（间歇 ~20%）
   Set-Clipboard 抛「所请求的剪贴板操作失败」时 exit_code 仍为 0（只写 stderr），
   且内容其实已写入 —— 造成「成功却报错」。改为重试 3 次 + 退避 + 读回校验，
   不再凭 exit_code 下结论。验证：修前 2/5 失败 → 修后 0/8 失败。

2. Windows 音频 backend 误标 'CoreAudio'
   CoreAudio 是 macOS 的后端名；Windows 实际走 C# NAudio(CoreAudioAPI)。
   抽常量并修正 manifest 描述，避免排查时误判平台。

3. CLI info 把嵌套对象打成 [object Object]
   ps_helper / build 是嵌套对象，String(v) 丢失全部内容。新增 renderInfoValue()：
   null→—、空串→—（未设置）、对象→key=value 紧凑摘要（180 字截断）。

4. nodeagent key press 必崩（100% 复现）
   字段契约不一致：被控端返回 {pressed,chords,times}（无 keys），
   CLI 读 r.keys.join() 抛 TypeError。双端对齐 —— agent 补回 keys 字段，
   CLI 改为 keys ?? chords 展开 ?? 参数回显。

5. Unicode 注入拆坏代理对（emoji / 生僻字）
   UnicodeChar(char) 逐字符注入，BMP 外字符被拆成两个孤立代理项，
   目标应用收到非法序列渲染 U+FFFD。新增 C# UnicodeString() 按 UTF-16 码元注入。
   注：KEYEVENTF_UNICODE 扫描码位仅 16 位，代理对必须各自单独发（API 固有限制）。

验证：单测 147 全绿；真机验收 15 通过 / 0 失败 / 1 跳过；双端已部署上线。
另确认中文偶发错字为 IME 上屏竞争，非注入逻辑问题（30 次对照实验全对）。
 2026-10-04 23:40:25 +08:00
jkooe e95a0248da feat(v19): 拉取式自更新 system.agent.update（42 项）—— 回答「能否直接用 GitHub 做更新服务器」 
## 结论：能，而且这是「控制端与被控端不可达」场景的正解
`deploy`（推送式）要求两者可达；本能力只要求**被控端能上网**，因此跨网段/NAT/异地都能更新。
GitHub Release / raw / 自建镜像 / 任意 http(s) 地址均可 —— 地址是参数，不写死。

## 实现（apps/agent/src/capabilities/selfupdate.ts）
下载 → **校验 sha256** → 备份 → **原子替换**（同目录 rename）→ 受控重启（复用 v7）→ CLI 复核指纹
- 出口：CLI `nodeagent update --url <u> --sha256 <h> [--dry-run]` · MCP `na_agent_update`
- 审计新增 `agent.update` 事件（记录 url / 前后指纹 / 字节数 / 备份路径）

## 安全底线（否则等于开放远程代码执行）
1. **sha256 必填**，且逐字节校验通过才替换；不符即丢弃并明确报错（未改动任何文件）
2. 只接受 http/https，拒绝 file:// 等其它 scheme
3. 大小上限 64MB + 下载超时（默认 120s）
4. **先备份再原子替换**，失败可回滚（返回 backup_path）
5. `dry_run` 只下载校验、不动文件 —— 用于「先确认能不能更」
6. 不用 fetch 的内置代理（Node 未暴露 undici）：国内访问 GitHub 不稳时，
   把 url 指向**自建镜像/加速地址**即可，能力本身接受任意 http(s)

## 真机/本地验证（全程真跑，非纸面）
- e2e 新增：本地 HTTP 服务真跑下载 —— 正确哈希通过 / **错误哈希被拒** / 404 明确报错 /
  非 http(s) scheme 被拒 / 缺 sha256 协议层拒绝 ✓
- 完整流程本地实测：`dry-run 预检` → `真更新`（966KB）→ 备份逐字节一致 → 重启 →
  **复核到新指纹** → 能力 42 项 ✓
- 顺带修：返回值漏 `incoming_hash` 导致 CLI 复核被跳过（真机踩过）
- 单测 126 / e2e 28 全绿

## 已知约束（写进文档）
1. **首次仍要一次性安装**（install.ps1）—— 自更新能力本身得先在机器上，鸡生蛋无解
2. `node.exe`（Node 运行时）不在自更新范围，只换 agent.mjs
 2026-10-04 23:03:37 +08:00
jkooe e6a9a3d7ea feat(v18): 更新链路可靠化 —— 构建指纹 + 备份 + 轮询校验（附 6 个真机 bug 修复） 
## 皇上的问题
「这个版本如果有更新，可以在客户端上便捷的更新吗？」
答案：本来就有 `nodeagent deploy`（比最初的一键升级还早），但**它不可信**：
部署后只看「PID 变了 / 能力数对了」，证明不了真的换成了新代码（旧版可能能力数一样），
而且备份与失败判定都存在问题。本轮把这条链路做成**可信**的。

## 新增
1. **构建指纹**：agent 上报 `build.hash`（运行中脚本的 sha256 前 12 位）+ bytes/mtime/node/uptime。
   部署后按指纹校验「远端真的是新代码」，而非靠 PID/能力数猜。
2. **`deploy --check`**：只比对指纹不动文件（退出码 2 = 需要更新），适合脚本/巡检。
3. **`deploy --force`**：指纹相同也强制覆盖。
4. **`pnpm update:win [设备名]`**：一条命令完成「打包 → 校验产物确实更新 → 部署」
   （脚本刻意防呆：pack 后产物时间戳没变就拒绝部署，避免部署旧包 —— 真机踩过）。
5. **NODEAGENT_DEBUG=1**：CLI 打印异常堆栈（异步链问题必备）。

## 修掉的 6 个真机 bug（本轮逐个实测暴露）
1. **备份用 `Copy-Item`**（Windows 专用 shell 命令）→ macOS 被控端静默不备份。
   改为协议自带 fs.read/fs.write，跨平台。
2. **备份读取漏 `encoding: 'base64'`** → 二进制被按 utf8 读（损坏），再当 base64 写回
   → 备份文件只有 33 字节垃圾（实测：`fs.read` 返回 524288 字符而非 base64）。
3. **备份循环用 fs.read 返回的 `offset` 当前进量** → 那是「本次读取的起始位置」，
   于是原地打转 → 死循环 + 文件暴涨 + 部署卡死 200s。
   改为自算 len（对齐 cmdPush 成熟写法）+ 无进展即跳出。
4. **轮询用 withClient → 直接退出进程**：`withClientDirect` 在连接失败且是 ClientError 时
   调 `fail()` 退出 —— 轮询第一次连接必失败（agent 正在重启）→ CLI 立刻退出，
   报 E_NODE_OFFLINE，而**部署其实已成功**（本轮 3 次「失败」全是这个假象）。
   新增 `probeOnce()`：永不抛出的探测函数，专用于「等待上线/重启」类重试。
5. **盲等 9 秒**判定部署结果 → 改为**按墙钟**限时轮询指纹（90s），失败时报真实耗时。
6. **重启会切断连接**：该中断属预期，此前未处理会把成功误判为失败 → 显式吞掉并说明。

## 验证（本地全程真跑，非纸面）
用「起本地 agent → 造一个改动过的 bundle → 部署」的方式把整条链路跑通：
- 同版本 `--check` → 「已是最新」退出码 0 ✓
- 不同版本 `--check` → 报不一致退出码 2 ✓
- 完整部署 → 备份（979578B，`cmp` 逐字节一致）→ 上传 → 重启 → **指纹校验通过** ✓
- 防呆：文件过小/不存在被拒 ✓
- 单测 125 / e2e 27 全绿
 2026-10-04 22:54:45 +08:00
jkooe 9853ee8cdb docs: 增补「杀软误拦（主流杀软 / 杀软 / 360）」排查章节 
真机实证：远程接管类工具的特征（未知 exe + 建计划任务 + 开防火墙 + 常驻监听 + 注入键鼠）
必然触发杀软拦截。主流杀软会拦 install.ps1 执行 / 计划任务注册，或直接处置 node.exe，
表现为「下载成功但装不上」或「装上后 agent 起不来」。

新增内容：
- 逐项放行清单（安装目录 / node.exe / agent.mjs / nodeagent 计划任务 / 入站 8765 / PowerShell 执行 / 键鼠截屏）
- 自检命令（任务状态 + 进程 + 端口三连查）
- 排查顺序：任务与进程 → 端口 → **确认两台机器在同一网络**
- 特别标注最后一个坑：控制端换 Wi-Fi（酒店/热点）后仍在扫旧网段，会误判为「失联」
 2026-10-03 03:07:23 +08:00
jkooe aaf0175e94 feat(v17): 音频控制能力 system.audio.get / set（40 -> 41 项） 
## 动机
「远程把那台机器静音」是接管场景里的高频小事，此前只能靠 exec 拼脚本，
容易踩本项目已记录的各种坑（C# 转义 / 编码 / 引号）。做成正式能力后一条命令即可。

## 实现
- **Windows**：Core Audio COM（IMMDeviceEnumerator → IAudioEndpointVolume）
  —— 可**读回真实状态**，所以是确定性的「设为静音」而不是「切换」
  （切换在未知状态下可能反而打开声音）。走项目既有的常驻助手基础设施（label=audio）。
- **macOS**：osascript 原生 `output muted` / `output volume`，零互操作。

## C# 互操作的两个硬约束（已写进文件头注释）
1. **槽位顺序即 vtable 顺序**：接口方法必须按 COM 定义顺序声明，不调用的也要占位。
   顺序错了不报编译错，而是调用到错误的内存地址 → 进程崩溃。
   （本次：m1..m4 → SetMasterVolumeLevelScalar(5) → m6 → GetMasterVolumeLevelScalar(7)
     → m8..m11 → SetMute(12) → GetMute(13)）
2. **C# 源码必须纯 ASCII**：Add-Type 按系统 ANSI(GBK) 落盘，非 ASCII 会乱码。

## 出口
- CLI：`nodeagent audio [get]` / `nodeagent audio set [--mute on|off] [--volume 0-100]`
- MCP：na_audio_get / na_audio_set
- 参数校验：mute 必须布尔、volume 必须 0-100 整数（越界由 schema 在协议层拒绝）

## 验证
- 单测 124 → 125（新增音频 schema 用例：范围/类型/未知参数）
- e2e 26 → 27：新增音频用例，**macOS 路径已实测**（读回真实 state、写回原值走通写入路径不产生可感知变化）
- ⚠️ **Windows 侧（Core Audio COM）尚未真机验证** —— 被控端重装系统后当前离线，上线后补验
- 顺带修正 e2e 一处断言：空参数属**能力层**失败（返回 failed），越界属**协议层**（抛异常）——
  正好把本项目那条契约固化进用例
 2026-10-02 19:53:46 +08:00
jkooe edc184037b perf(v16): 常驻助手启动后台预热 —— 首调用不再承担 1-3s 启动成本 
## 动机（由指标发现）
真机指标显示 window.list 的 P95 被抬到 2775ms，与实测稳态 42~75ms 矛盾。
排查：助手是**懒启动**的，每个 agent 进程的「第一次调用」要付启动 + 类型预加载的固定
成本（~1-3s）；今天为验证反复重启了数十次，这笔成本就落进了 P95 的统计里。
这既是测量噪声，也是真实体验问题 —— 首个用户调用不该等 3 秒。

## 做法
agent 启动、打印完横幅后，后台预热一次助手（延时 1.5s、不阻塞、不 throw、失败无副作用）：
把固定成本挪到无人等待的时刻。

## 真机验证
部署（agent 重启）→ 等 6s → **重启后首次** window.list：**0.57s**（此前 1.5~2.5s）；
system.info 的 ps_helper 显示 hits=2（预热 1 + 调用 1）、spawned=1、failures=0 ✓

## 顺带说明（指标口径）
本轮 P95 3140ms 的另一部分噪声来自本人当日的开发流量（数十次重启 + 图像匹配调试的
失败样本，screen.find 成功率 77.6% 就是调试期数据）。测稳态请用 --since 限定窗口。
 2026-10-01 21:16:11 +08:00
jkooe 4c6190285c refactor(protocol): 拆分 1281 行的 capabilities.ts（纯搬移，公共 API 不变） 
## 结果
    capabilities.ts                     1281 → 12 行（仅门面：re-export + findCapability）
    capabilities/names.ts                 55 行  标准能力名 CapabilityNames + 类型
    capabilities/schemas.ts               11 行  通用 schema 片段（filterSchema）
    capabilities/manifest/system.ts      303 行  系统面 9 项
    capabilities/manifest/graphics.ts    413 行  图形 12 项（screen/window/input）
    capabilities/manifest/files.ts       121 行  文件 4 项
    capabilities/manifest/software.ts     62 行  软件 2 项
    capabilities/manifest/automation.ts  329 行  自动化 12 项（task/clip/event/net/macro/group）
    capabilities/manifest/index.ts        20 行  聚合为单一 CAPABILITY_MANIFEST

## 做法（可复用的纯搬移流程）
1. 先扫「清单数组区间内是否夹带顶层声明」→ 无 ✓（否则按函数切分会漏）
2. 用花括号配对切出 39 个描述符（断言数量必须一致，避免静默丢项）
3. 按**能力名字符串前缀**分组（不是枚举成员名——成员名与字符串前缀并不一致，
   例如 AuditList→system.audit.list、AgentRestart→system.agent.restart）
4. 聚合文件保持对外单一 CAPABILITY_MANIFEST；facade 保持全部导出不变

## 副作用（正面）
清单顺序由「历史上陆续追加的混杂顺序」变为**按域分组**（系统→软件→图形→文件→自动化），
CLI/MCP 的能力展示更易读。已真机确认无功能影响。

## 验证
- 构建 6 包全过；单测 124/124（含清单守护：数量=39、逐项 name/schema 校验）；e2e 26/26
- 真机：部署后能力 39 项 ✓、CLI 能力矩阵正常打印（含风险图标）✓
 2026-10-01 21:11:59 +08:00
jkooe caa5b8a2c1 refactor(cli): 拆分 1977 行的 index.ts 为 11 个模块（纯搬移，零逻辑变更） 
## 动机（审查报告 §5.5 / 阿特拉斯报告）
单文件 1977 行难维护、难 review、难以定位改动影响面。本次按职责拆分：

    src/index.ts   315 行  入口：参数解析后按子命令调度
    src/options.ts 155 行  命令行参数解析（parseArgs）
    src/help.ts     75 行  帮助文本
    src/types.ts    74 行  共享类型与常量
    src/core.ts    236 行  运行时：客户端/守护进程代理/输出工具/--node 覆盖
    src/cmd/conn.ts   217 行  连接与设备（connect/keygen/nodes/use/remove/discover）
    src/cmd/system.ts 278 行  系统面（info/status/ps/services/exec/restart/audit/metrics/invoke/apps/install）
    src/cmd/ops.ts    499 行  自动化（bg/tasks/task/fanout/record/deploy/events/macro/clip）
    src/cmd/gui.ts    173 行  图形（screen/screenshot/mouse/key）
    src/cmd/fs.ts     172 行  文件（ls/stat/cat/pull/push）
    src/cmd/net.ts    116 行  网络两阶段提交

## 拆分中处理的真实工程问题（都不是「机械搬移」能躲过的）
1. **跨模块可变状态**：`--node` 的全局覆盖 `currentNodeOverride` 原来是模块级 let。
   ESM 的 import 绑定是只读的，直接 import 后赋值编译不过 → 改为访问器
   setNodeOverride()/getNodeOverride()（并把「为什么不能用变量」写进注释）。
2. **散落在函数之间的顶层常量**：CHUNK_BYTES 恰好位于两个函数之间，按函数切分会
   误入别的模块 → 归入 types.ts 统一导出。DAEMON_SOCK 同理并去重。
3. 导入按模块职责补齐（parseArgs/getClientConfig 等）。

## 验证
- 构建 6 包全过；单测 124/124；e2e 26/26
- **真机 CLI 冒烟 25 条命令全通过**（CLI 不在 e2e 覆盖内，必须实测）：
  info/status/ps/services/ls/metrics/audit/nodes/net status/screen/window.list/tasks/clip/apps/exec
  + push/stat/cat/pull（校验回读内容一致）/screenshot/key type/bg/record/mouse/discover
 2026-10-01 21:04:24 +08:00
jkooe 411a483c76 fix(v16): 修复网络两阶段提交的 4 个真机缺陷（事故复盘后全部实测通过） 
真机实测暴露并修复：
1. **生成的 .ps1 缺 UTF-8 BOM** → PowerShell 5.1 按 ANSI(GBK) 解析，脚本里的中文
   （网卡名「Ethernet」）会吃掉后面的闭合引号，报 "The string is missing the terminator"
   → 计划任务退出码 1 且不留任何日志。现已统一 withBom() 落盘（对照实验：纯 ASCII 正常、
   含中文失败，定位明确）。
2. **路径字面量被多余转义**：单引号内本是字面量，之前却把反斜杠翻倍 → 生成
   `C:\\Users\\...` 非法路径 → Out-File 失败。新增 psLit() 统一处理。
3. **账号名拼法错误**：`"$env:USERDOMAIN\$env:USERNAME"` 在 TS 模板串里 `\$` 被当转义吃掉
   反斜杠 → 拼出「机器名<user>」→ Register-ScheduledTask 报 HRESULT 0x80070534
   「No mapping between account names and security IDs」。改用 WindowsIdentity 权威名称。
4. **注册脚本重复实现导致漏改**：回滚/延时两处各写一份，改了一处漏另一处（本轮回滚改好了、
   apply 没改 → 继续报错）。抽出唯一实现 buildTaskRegistration()，并把注册类调用统一改为
   **临时脚本 + -File**（真机实测 -EncodedCommand 下进度流会污染 stderr 且 stdout 拿不到
   预期输出，导致「明明成功却被判失败」）。

顺带：
- 错误详情统一剥离 CLIXML 噪声（extractPsError），并带上 exit code 与 stdout —— 本轮就是靠它
  才看到真实报错（此前只有「启动失败(code=1)」）
- net confirm 顺带清理已执行完的 netapply 任务，保持任务计划程序干净

真机验证（全部通过）：
- apply(command) → 返回 apply_scheduled + 两个任务名 ✓
- apply 脚本执行 → 日志出现 "apply ok" ✓
- 不确认 → 自动回滚 → 日志 "restored: static" ✓（事故路径已修复）且网络完好 ✓
- confirm → 任务被取消（netrollback 计数 0）✓
- net status 剩余秒数正确 ✓
 2026-10-01 20:58:19 +08:00
jkooe 9ef8978b92 feat(scripts): 网络救援脚本 rescue-network.ps1（网络变更失联后的本地恢复） 
## 为什么需要它
`system.net.apply` 是两阶段提交（未确认自动回滚），但**万一回滚本身也失败**
（本次真机事故就是：变更脚本把地址删了却没加上），机器会落到 APIPA(169.254.x.x) 而彻底失联。
那时远程已无路可走，只能本地恢复 —— 这个脚本就是为那一天准备的。

## 能力
- `-ListOnly`：先看清各网卡状态/地址/默认路由（含「已连接但无地址」的失联特征标注）
- 自动识别失联网卡（已连接但无有效 IPv4），也可 -Interface 指定
- 带 -Ip/-PrefixLength/-Gateway/-Dns 恢复静态；不带 -Ip 则切回 DHCP
- **安全顺序**（与 agent 内实现一致）：先加新地址 → 清旧地址与残留默认路由 → 补默认路由
- 自检并给出下一步命令（含可直接复制的 Mac 侧 connect 命令）

## 用法
    powershell -ExecutionPolicy Bypass -File rescue-network.ps1 -ListOnly
    powershell -ExecutionPolicy Bypass -File rescue-network.ps1 -Interface 'Ethernet' `
        -Ip 192.168.1.100 -PrefixLength 24 -Gateway 192.168.0.1
    powershell -ExecutionPolicy Bypass -File rescue-network.ps1 -Interface 'Ethernet'   # 切回 DHCP
 2026-09-30 11:10:23 +08:00
jkooe e955b6a2f7 test(v16): 网络脚本回归断言 8 条（把事故根因变成防线） 
针对本次真机事故（机器掉 APIPA 失联）逐条设防：
- apply 必须先 New-NetIPAddress 再 Remove-NetIPAddress（顺序颠倒 → already exists → 无地址）
- 建默认路由前必须先 Remove-NetRoute（否则 New-NetRoute 报实例已存在）
- 断言脚本里**不得出现** netsh set address / set dnsservers（Win11 上会挂起）
- 自检片段必须校验目标地址并在失败时执行回滚（自愈）
- 回滚脚本同样受「先加后清 / 先清路由」约束，且必须恢复原地址/网关/DNS
- DHCP 快照的回滚走 -Dhcp Enabled，不得写静态地址
- 掩码→前缀换算边界（含非法输入回退）

单测 116 -> 124
 2026-09-30 10:20:02 +08:00
jkooe 6afec163f3 feat(v16): 网络变更两阶段提交（commit-confirm）—— 解决审查报告 §5.4「自断生路」 
## 能力（39 项）
- system.net.apply   备份 → 快照 → 武装回滚任务 → **延时执行变更** → 自检失败即自愈
- system.net.confirm 取消回滚任务 = 提交（可指定 task_name 或取消全部）
- system.net.status  网络现状 + 待确认变更（含剩余秒数）+ 历史备份
- 出口：CLI `nodeagent net [status|apply|confirm]` + MCP na_net_apply/confirm/status
- 审计新增 net.change 事件类型（含 mode/接口/时间点/备份路径/快照）

## 设计要点
1. **OS 级回滚**：用 S4U 计划任务触发回滚（注销/重启/agent 崩溃都照样回滚），
   不依赖 agent 进程存活 —— 这是与「先删后加」类操作并存的前提
2. **先武装后开火**：回滚任务注册成功才执行变更；注册失败直接中止（宁可不改）
3. **延时执行 + 先应答**：改地址必然切断控制端连接，同步执行调用方永远收不到返回
   （真机实测 200s 超时，而变更其实已生效）。改为排程 3s 后执行，先交出凭据
4. **结构化快照**：不用 `netsh -f 备份` 回滚（备份里是 `set address`，该命令在 Win11 会挂起）
   —— 按 JSON 快照用原生 cmdlet 重建

## 真机踩坑（含一次真实事故，全部已修 + 注释固化）
- **netsh set address 在 Win11 挂起**（>60s 无响应），原生 Set/New-NetIPAddress <1s
- **netsh dump 经 PowerShell 重定向会被转码破坏** → 备份不可用（改走 cmd 原始重定向）
- **嵌套 -Command "..." 时内层 $_ 被外层展开** → 静默返回空（统一改 -EncodedCommand）
- **杀手机制**：先 Remove 旧地址再 New 新地址 → Windows 残留默认路由使 New-NetIPAddress
  报 already exists → 新地址没加上 → **机器回落到 APIPA 彻底失联（真机事故）**。
  修法：① 先加新地址再清旧地址（过渡期链路不断）② 先 Remove-NetRoute 再建地址
  ③ 变更后自检，未生效则立即执行回滚脚本自愈
- 单网卡机器 ConvertTo-Json 输出对象而非数组 → 解析要兼容（否则网卡列表永远为空）
- 任务名应编码「回滚时间」而非创建时间（否则剩余秒数算不对）
 2026-09-30 10:19:20 +08:00
jkooe 553b16f595 docs: 口径更新到 v15（图像模板匹配 / 助手提速）+ 三条腿定位说明 2026-09-30 01:27:55 +08:00
jkooe 8ee8dc7f41 feat(v15): screen.find 图像模板匹配（补齐自绘 UI 盲区）+ 一串真机根因修复 
## 新能力：method=image 图像模板匹配
审查报告 §5.2 指出「screen.find(image) 图像模板匹配未做，纯图标/无文字的控件是定位盲区」。
UIA 靠控件树、OCR 靠文字，两者对纯图标都无能为力；本版补上第三条腿。

实现（随常驻助手预加载，C# + System.Drawing，零新依赖）：
- 灰度化（LockBits + ITU-R BT.601 整数近似）
- 零均值归一化互相关 ZNCC（对亮度/对比度变化不敏感）
- **粗到精**：1/4 分辨率全图扫描 → 候选在全分辨率 ±8px 精修
  （全分辨率逐像素在 3440x1440 上约 190 亿次，不可行）
- 非极大值抑制去重；返回中心坐标 + score，可直接喂 input.mouse.click
- 参数：template（被控端图片路径）、threshold（默认 0.85）；支持 region 限定搜索区
- 出口：screen.find(method=image) + CLI/MCP 同步暴露

真机实测：3440x1440 全屏搜索 **~580ms**，score 0.9745 命中可用坐标；
对「模板纯色/低对比」会显式报错（E_PARAM_INVALID + variance），而不是静默返回空。

## 本轮为打通它而修掉的 7 个真机根因（都值得记档）
1. **预加载段拼接静默失败**：WIN_HELPER_PRELUDE 是多行模板串，替换串写成单行 \n 不匹配且
   无 assert → OCR/图像两段从未拼入 → 被 esbuild tree-shake → 运行时才报「找不到类型」。
   现已导出并加回归断言（四段齐全 + 顺序）。
2. **助手启动超命令行上限**：bootstrap 含内嵌 C#（编码后 ~36KB）超过 Windows ~32KB 限制，
   spawn 直接 ENAMETOOLONG → 每次静默降级到慢路径。改为落地临时脚本 + -File。
3. **一次性降级路径同样超限**：ENAMETOOLONG。同样改为临时脚本 + -File（UTF-8 BOM）。
4. **统计记账掩盖根因**：ensureStarted 在 try 之外，spawn 失败不计入 failures，
   表现为「spawned 一直涨、calls 恒为 0」。现已纳入 try，并暴露 ps_helper 状态
   （enabled/calls/hits/failures/spawned/avg_ms/lastError）到 system.info。
5. **Add-Type 在中文系统上乱码**：C# 源码按系统 ANSI(GBK) 落盘，中文注释必乱码 → 编译失败。
   已把内嵌 C# 全部改为纯 ASCII，并加断言「C# 块不得含非 ASCII」。
6. **Add-Type 缺 -ReferencedAssemblies**：只 Add-Type -AssemblyName System.Drawing 不够，
   编译期仍报「命名空间 System.Drawing 中不存在 Imaging」。已补 -ReferencedAssemblies。
7. **TS 模板串吃掉 \" 转义**：在模板字符串里写 \" 会得到裸引号 → C# 编译失败（踩了两次）。
   统一改用 C# 字符常量 Q 拼 JSON，并加断言（不得残留裸引号 JSON 形态 / Q 不得重复声明）。
另外把「粗层预筛」从 threshold-0.05 放宽到 threshold-0.30 并始终保留最优候选 ——
降采样会拉低真位置的分数，过严的预筛会让正确答案在精修前就被丢弃（这曾让所有匹配返回空）。

## 单测 105 -> 114
新增 win-prelude 回归 9 例：四段齐全与顺序 / C# 纯 ASCII / 无裸引号 JSON / Q 不重复声明 /
Win32+UIA+OCR+图像 各段关键标记（含 -ReferencedAssemblies）。
这些断言的价值在真机验证过：3 个 bug 都是先被断言抓住、才避免了再次上线静默坏掉。
 2026-09-30 01:27:37 +08:00
jkooe 92df08eb20 test(v7~v13): 新能力补齐 e2e 覆盖（21 -> 26 用例）—— 审查报告 §5.1-3 
## 背景
报告指出「v7/v8 新能力零自动化测试，只有提交说明里的真机手验」。此前 e2e 覆盖止于 v6。

## 新增 5 个用例（tests/e2e/run.mjs）
1. **v8 GUI 语义契约** —— 不断言「屏幕上一定有什么」（CI 无桌面会话时不可靠），
   而断言对外契约：window.list 结构 + 前台窗口排最前（否则会被 limit 截掉）；
   window.focus 目标不存在时是干净错误；screen.find 无命中返回空数组 + engine + waited_ms；
   参数越界必须被拒
2. **v10 剪贴板与后台任务** —— clip.set/get 往返；异步 exec → task_id →
   续读输出 → 任务列表 → 终止长任务并断言 state=killed / exit_code=124
3. **v12 事件订阅** —— 文件监控：制造变动后**同时验证两条通路**
   （onEvent 推送 + event.poll 增量游标），并验证 unwatch 生效
4. **v12 GUI 宏引擎** —— 不依赖 GUI 的步骤组合（exec+clip+assert+sleep）回放；
   断言失败必须中止并给出 failed_at 定位；optional 失败不中断
5. **v13 成功指标与审计链** —— 指标字段齐全、分层时延存在、拦截率恒 1、
   无样本时装软件成功率为 null（而非 0）；audit.verify 链完整

## 写用例时踩到并固化的契约（重要，已写入测试注释）
**协议层错误会抛异常，能力层失败才返回 {status:'failed'}**：
  - 能力层失败（输入未开启 / 窗口未找到）→ 返回 { status:'failed', error:{name} }
  - 协议层失败（参数校验 / 鉴权 / ACL / 限速）→ invoke() **抛 ClientError**（err.name = 错误码）
新增 expectProtocolError() 辅助函数统一断言后者，避免后续再写错。
另修正：任务终态是 `done`（不是 exited），运行中为 `running`。

单测 105/105、e2e 26/26 全绿
 2026-09-30 00:56:49 +08:00
jkooe 0dcf01ad4e perf(v14): PowerShell 常驻助手 —— GUI 能力提速 4~25 倍（审查报告 §5.5 P1） 
## 问题（审查报告 5.5 指出，真机实测确认）
window.list / window.focus / screen.find 每次调用都起一个 powershell.exe 现编译 C#
（Add-Type @"..."@）+ 重新加载 UIA 程序集。实测 agent 侧中位：
  window.list 1267ms · window.focus 1631ms · screen.find 3140~3736ms
固定成本（起进程 + 编译类型）与「本次要做的活」无关，纯浪费。

## 方案（apps/agent/src/util/ps-helper.ts）
常驻 PowerShell 进程：启动时把 prelude（Win32 C# 类型 + UIA 程序集 + WinRT/OCR 段）
**只加载一次**，之后每请求只发「本次逻辑」（base64 一行），进程内直接执行回传。
- 协议：stdin 收 base64 脚本行；stdout 回 `@@R <b64>` / `@@E <b64>`；stderr 只走就绪信号
- 请求 FIFO 串行（单进程单 stdin），逐请求超时
- **可用性不倒退**：助手不可用/超时/进程退出 → 自动回退到原一次性脚本路径；
  连续失败 3 次熔断，本进程不再重试（避免每次白等一次超时）
- 自愈：进程退出后在下次请求重建；空闲 10 分钟自动回收；agent 退出统一回收
- 预加载段带 sha256 指纹：**prelude 变化自动换新助手**（否则会用到旧进程里已加载的定义）
- 逃生开关：环境变量 NODEAGENT_NO_PS_HELPER=1 可强制走一次性路径

## 关键工程细节：exit
脚本体会被送进常驻进程执行，**其中的 exit 会杀掉助手进程**。
已将 focusOnce 的 `exit 0`、UIA 的 `exit 0`、OCR 的 2 处 `exit 0` 全部改为 return。

## 顺带优化 UIA 扫描策略（本轮第二个瓶颈）
UIA 只能「FindAll(Descendants) + 子串过滤」（PropertyCondition 是精确匹配）。
原来**每次都遍历整棵桌面 UI 树**。改为：
  指定 window → 该窗口子树；否则**先在前台窗口子树内找**，未命中再退回全桌面兜底。
遍历逻辑收敛为预加载函数 Find-UiaByText，两处复用不再重复。

## 真机实测（agent 侧耗时，同一台机器同一会话）
| 能力 | 改造前 | 改造后 |
|---|---|---|
| window.list  | 1267 / 1216 / 1260 / 980 ms | **52 / 52 / 52 / 73 / 42 ms**（约 25x） |
| window.focus | 1576 / 1568 / 1600 ms        | **411~443 ms**（约 4x；余量为刻意的等待与激活校验） |
| screen.find  | 3140 / 3736 / 1302 / 1393 ms | **19 / 26 / 72 / 103 / 176 ms**（约 20x，前台命中路径） |
端到端（CLI 视角）window.list 由 1.34s → **0.16s**。
另注：全桌面无命中路径的耗时随 UI 树规模变化，非固定值。

## 单测
101 -> 105（新增助手协议 4 例：UTF-16LE 编码可逆 / bootstrap 含 prelude+READY+循环+exit 协议
且必须 try-catch 兜异常 / 协议行解析（含 Add-Type 噪声必须忽略）/ 中文多行往返无损）
 2026-09-30 00:51:56 +08:00
jkooe 87d7f3fbcc docs: 口径更新到 v13（36 能力 / 32 MCP 工具 / 101 单测）+ 指标命令 2026-09-30 00:23:16 +08:00
jkooe 8743bd1237 feat(v13): 成功指标聚合（对齐 PRD 2.2 四项验收指标）+ 依据真实数据修正口径 
## 背景（审查报告 P0-2）
审查报告指出：PRD 2.2 的成功指标「无任何采集与统计落点，指标空转」，并给出
已验证原型（30 行脚本在 598 条真实审计日志上算出三项指标）。本版将其产品化。

## 实现（apps/agent/src/metrics.ts，纯函数 + 可单测）
数据源就是审计日志，无需额外埋点：
- 闭环成功率 = invoke ok / 总数
- 装软件成功率 = app.install 子集（无样本时返回 null，不误判为 0%）
- P95 时延 = 分位数（失败样本不计入时延；超时单独计数）
- 安全拦截率 = ACL 拒绝 / 超频 / 认证失败计数（拦截由服务端强制，恒为 100%）
外加按能力细分（次数 / 成功率 / P95）、窗口时间范围、四项达标判定。

出口：能力 system.metrics（36 项）+ CLI `nodeagent metrics [--since ms]` + MCP `na_metrics`。
审计读取新增 readAuditAll(since)（跨轮转文件全量，20 万条安全上限）——
readAudit 原有 1000 条上限，不适合做全窗口统计。

## 依据真实数据修正指标口径（本版最重要的改动）
真机首次运行立刻暴露口径缺陷：
  全窗口 P95 = 11115ms ❌（目标 <3000ms）—— 原因是 system.shell.exec P95 27.5s
  近 6 小时窗口 P95 = 9575ms ❌ —— 8 个样本里仅 1 次「故意重启」9.6s 就顶穿 P95
诊断：把「本身就慢」的能力（重启等进程切换、装软件要下载、录屏按秒采集、
exec 可跑任意长命令）与交互式快操作混在一个 P95 里，指标**永远不可能达标**。

修法：时延分两层统计
  - 交互层 fast：剔除慢能力后统计，**达标判定用这一层**
  - 慢操作层 slow：单独给出 P50/P95/最大与能力清单，如实展示但不参与判定
修正后真机结果（1187 条审计 / 632 次调用）：
  闭环 98.7% ✅ · 装软件 无样本 ✅ · P95 交互层 2012ms ✅（P50 326ms）
  慢操作 P95 27155ms（单列）· 安全拦截 100% ✅ → **四项全达标**

## 单测
89 -> 101（新增指标 12 例：空样本不误判 / 成功率边界 90% / P95 分位 /
分层口径（慢能力不拖累、真机场景复现）/ 超时单列 / 自定义阈值 / 窗口 / 摘要格式）
 2026-09-30 00:19:10 +08:00
jkooe 0f8b878de0 docs: 路线图补 v12.4（事件直达 MCP）+ 验证脚本说明 2026-09-29 15:47:49 +08:00
jkooe 4d1aeada07 feat(v12.4): 事件直达 MCP 宿主（实时推送）+ 修两个真 bug 
## 背景
v12 的事件订阅对 MCP 只走「被控端缓冲 + na_event_poll 拉取」。MCP 协议本身支持
服务端 -> 客户端通知，故补上实时推送：na_event_watch 的 notify=true 开启，
事件经 MCP 标准日志通知（notifications/message）即时送达宿主。

## 两条通路并存（互相兜底）
1) 推送：onEvent -> server.notification(notifications/message, logger=nodeagent.event)
   —— 宿主若不展示日志通知，则自动退化为拉取，无副作用
2) 拉取：na_event_poll（增量游标）
na_event_list 额外返回推送开关与已转发条数，便于判断该用哪条通路。

## 真机修掉的两个 bug
1. **notify 参数泄漏到能力侧**：notify 是 MCP 层开关，原样透传被被控端
   additionalProperties:false 拒绝（E_PARAM_INVALID）。改为在 toArgs 里显式构造，
   只带能力真正接受的字段。
2. **通知未声明 logging 能力导致 MCP 进程崩溃**：SDK 的 notification() 在未声明
   logging 能力时抛错，且因返回 Promise 未 catch -> 未处理拒绝直接终止进程
   （真机实测：watch 成功后一有事件，整个 MCP 服务就退出）。
   修法：capabilities 声明 logging + 通知调用补 catch（失败静默降级为拉取）。

## 端到端验证（scripts/verify-mcp-events.mjs，已收进仓库）
真实 MCP stdio 客户端驱动，对生产被控端实测：
- initialize ok；tools/list 31 个工具、事件类 4 个
- na_event_watch(notify=true) -> watch_id
- 制造 创建/修改/删除 -> **收到 3 条推送通知**（file created_or_removed / modified / ...）
- na_event_poll 返回缓冲事件（seq/watch_id/ts/action/target）
- na_event_list 显示「推送已开启（已转发 3 条）」
结论：推送 ✅ 生效；拉取 ✅ 生效

单测 89/89、e2e 21/21 全绿
 2026-09-29 15:47:34 +08:00
jkooe 82a44bb13f docs: 路线图补 v12.1~v12.3（Hub 授权 / 等待语义 / macOS GUI 对齐） 2026-09-29 14:56:35 +08:00
jkooe d56556d3c3 feat(v12.3): macOS 端 GUI 能力对齐 —— window.list / window.focus / screen.find 
## 动机
此前 window.* 与 screen.find 只在 Windows 可用（UNSUPPORTED_PLATFORM）。本版让
macOS 也能作为被控端被 GUI 操作，兑现「Mac 与 Windows 双向接管」。

## 实现（apps/agent/src/capabilities/darwin.ts）
| 能力        | Windows                 | macOS                                     |
|-------------|-------------------------|-------------------------------------------|
| window.list | Win32 EnumWindows       | AppleScript System Events（需辅助功能权限） |
| window.focus| SetForegroundWindow+兜底 | AppleScript frontmost + AXRaise           |
| screen.find | UIA → OCR(WinRT)        | 无 UIA 等价物 → 截图 + **Vision OCR**      |

要点：
- AppleScript 经 stdin 传入（base64 解码），彻底规避引号/换行转义
- Vision OCR 用 Swift 源码 + `swiftc -O` 按需编译，二进制缓存在数据目录 bin/naocr；
  源码变化时自动重编（首编约 15s，之后毫秒级）
- 权限错误翻译成可执行指引：实测 -10004「发生权限违例」→ 提示去「辅助功能」授权；
  -1743 → 「自动化」授权

## 真机踩坑（本轮最重要的一条）
**Retina 屏上 screencapture 产出 2x 像素图**，而窗口坐标为逻辑点 —— 直接返回会让
点击偏移一倍。修法：解析 PNG 的 IHDR 取像素尺寸，除以请求区域点数得到缩放比，
换算后再叠加区域偏移（返回体注明已换算）。

## 顺带修掉一个参数缺口
screen.find 的实现读 region 但 schema 未声明 → 带 region 的调用被参数校验拒绝
（E_PARAM_INVALID）。已补 region 到 manifest，并让 Windows 的 OCR 路径同样支持
「显式区域优先 > 指定窗口 > 整屏」（区域越小 OCR 越快越准）。

## 真机验证（本机 macOS 27.2，M3 Max）
- window.list：AppleScript 生效，但本机未授予辅助功能权限 -> 返回可执行提示（预期路径）
- screen.capture：984KB 有效 JPEG（3024x1964）
- Vision OCR 独立验证：对含中文/英文的真实截图识别出「WorkBuddy 编辑 查看 窗口 帮助」等
- screen.find（全屏）：命中 3 处，坐标稳定
- screen.find（区域 0,0,1600,120）：命中且坐标全部落在区域内 —— 证明 Retina 换算正确
- 等待语义（wait_ms）在 macOS 路径同样生效

单测 89/89、e2e 21/21 全绿
 2026-09-29 14:55:13 +08:00
jkooe a892b113ca feat(v12.2): GUI 等待/重试语义 —— 结束「点下去就不管」的假失败 
## 动机
GUI 自动化最常见的失败不是「找不到」，而是「还没出来」：应用启动、页面切换、动画
都有延迟，一次性查找必然假失败。之前调用方只能自己在外面 sleep+重试（浪费往返）。

## 实现（agent 侧内联轮询，避免多次往返）
- screen.find 新增 wait_ms（0~30000，默认 0）与 interval_ms（100~2000，默认 400）：
  轮询到命中或超时；无论成败都返回 waited_ms，让调用方知道是否命中等待窗口
- window.focus 新增 wait_ms：窗口未出现时每 500ms 重试，直到超时（仅 title 模式）
- 宏步骤 find/assert 透传 wait_ms/interval_ms（写宏时可直接声明等待）
- MCP na_screen_find 暴露 wait_ms

## 真机验证（决定性）
调用 window.focus(title=Notepad, wait_ms=15000) 时**记事本尚未运行**；
4 秒后才启动 -> 等待轮询捕获并成功聚焦：
  { title: "*install.ps1 - Notepad", focused: true, activated_by: "click" }
注意 activated_by=click：本次 SetForegroundWindow 又被系统静默否决，
点击兜底自动接管 —— 两个加固协同生效（等待 + 激活兜底）。

单测 89/89、e2e 21/21 全绿
 2026-09-29 14:43:27 +08:00
jkooe cd774ae0a6 feat(E3c): Hub 侧按控制端授权（多令牌 + 按设备白/黑名单 + 注册准入） 
## 背景
Hub 原先只有**一个**令牌：任何持有者都能接入任意设备，无法区分「谁在控制哪台机器」。
E3 的权限隔离因此只做到能力级（被控端 ACL），Hub 侧仍是全通。

## 实现（apps/hub/src/authz.ts，纯函数便于单测）
- 多令牌：每个令牌 = 一个控制端身份，可独立指定 allow_nodes / deny_nodes（glob）
- 判定顺序 deny -> allow -> 默认拒绝；未配置 allow_nodes 时默认放行（兼容）
- 顶层 token 视为主令牌（放行全部），旧配置零改动
- 前缀式滚动令牌：value 以 * 结尾时按前缀匹配（轮换期间可灰度）
- 注册准入：node_allowlist 非空时只有匹配的 node_id 能注册，防止他人借令牌挂靠节点
- 列表按身份过滤：控制端只看得到自己被授权的设备
- 越权接入返回新错误码 E_NODE_FORBIDDEN

## 职责边界（重要）
Hub 只做「能否连到某设备」的接入过滤；连上之后的**能力级**授权仍由被控端 ACL
按 client_id 裁决。两层各自独立，Hub 不参与能力决策 —— 保持 Hub 不可信假设。

## 测试
- 单测 79 -> 89（新增 Hub 授权 10 例：主令牌兼容 / 未知令牌 / 前缀轮换 /
  deny 优先 / glob 白名单 / 默认放行 / 注册准入 / 旧配置兼容 / 列表过滤 / glob 转义）
- e2e：Hub 用例新增受限令牌访问未授权设备 -> 断言 E_NODE_FORBIDDEN 且错误信息含授权原因
 2026-09-29 14:38:53 +08:00
jkooe 66c44f6822 feat(E3): Hub 并发多控制端 + 设备分组（阶段 E 全部完成） 
## E3a 并发多控制端（Hub 槽位池）
过去：一个被控端只有一条 Hub 连接 -> 同时只能一个控制端（否则 E_NODE_BUSY）。
现在：
- Hub 侧 agents 表改为「node_id -> 槽位池」，每个槽位服务一个控制端：
  有空闲槽位直接配对；不足且未达上限则向被控端请求扩容（need_slot，3s 超时）；
  仍不满足才返回 E_NODE_BUSY。新增配置 max_slots_per_node（默认 3，设 1 即退回独占语义）
- 被控端侧 hub-mode 重写为槽位池：常备 2 条连接（warm_slots 可调），
  并在某槽位被占用（收到 hello）时预热下一条直到 max_slots
  —— 复用既有协议信号，不新增控制消息；每条槽位独立重连与退避
- Hub 列表视图聚合为「一节点一行」并带 slots / paired_slots
- e2e 新增并发用例：两个控制端同时握手 + 交替并发调用，均成功（旧版会失败）

## E3b 设备分组
- 客户端配置新增 groups（组名 -> 设备名数组；成员可写 @其它组名，最多展开 3 层防环）
- CLI：nodeagent group add|remove|list；fanout --nodes @组名 按组并发下发
- 真机验证：group add 本机 win -> fanout system.info --nodes @本机 正常

## E3c 权限隔离（部分完成）
- 能力级隔离沿用被控端 ACL（按 client_id，已含 allow/deny/glob/生效时段/IP 白黑名单/按能力限速）
- Hub 侧「按设备/按控制端授权」尚未实现（当前 Hub 视角为单一令牌），已记入路线图待办

## 测试
- 单测 73 -> 79（新增设备分组 6 例：展开 / 嵌套 / 去重 / 未知 / 兼容旧配置 / 环引用收敛）
- e2e 21/21（含扩展后的 Hub 并发双控制端用例）
 2026-09-29 14:33:01 +08:00
jkooe 3ed117770b feat(E4): GUI 宏（步骤序列回放）+ 窗口聚焦加固（能力 35 稳定） 
## E4 宏引擎（packages/client/src/macro.ts，CLI 与 MCP 共用）
- 步骤类型：focus / find / click / type / key / drag / sleep / exec / clip / assert / capture
- 通用能力：retry（失败重试）、interval_ms、optional|continue_on_error、${VAR} 与 ${VAR:-默认值} 替换
- 断言内置在步骤里：exec 的 expect_exit/expect_stdout、clip 的 expect、
  assert 支持 kind=screen|window|clip（屏幕断言自动走 UIA→OCR）
- 返回逐步结果（含 ms 与失败定位 failed_at），失败即中止并给出可读原因
- CLI: macro run <file> [--var k=v] [--out 目录] / macro validate / macro init（生成示例）
- MCP: na_macro_run（inline steps + vars）

## 真机验证（记事本全流程）
宏 init 生成示例 -> 启动记事本 -> 回放 9 步：
focus ✓ / key ctrl+a ✓ / delete ✓ / type ✓ / sleep ✓ / key ctrl+a ✓ / key ctrl+c ✓ /
clip 断言「宏回放演示 回放测试」✓ / window 断言 ✓ -> 全部通过（10.1s）

## 顺带修复两个真机踩出的问题
1. **window.focus 可能被静默否决**：SetForegroundWindow 受 Windows 前台锁定限制，
   调用后前台窗口可能仍是别人（实测被系统防火墙对话框抢焦点，导致宏的输入全进了对话框）。
   现改为：调用后**校验当前前台窗口**；未生效则在该窗口标题栏做一次真实点击兜底，
   并返回 activated_by=api|click 让调用方知情。
2. **window.list 会被 limit 截掉真正的前台窗口**：现按 is_foreground 排序置顶并返回 total。
3. 宏引擎：变量缺失原先会在 try 之外抛出、导致整个宏崩掉；现改为「记为该步失败」，
   optional 时继续执行（单测覆盖）。

单测 63 -> 73（新增宏引擎 10 个用例：变量/默认值/缺失、retry、optional、失败中止、
expect_exit/stdout、clip 断言、未知步骤、find→click 坐标透传、坏文件拒绝）；e2e 21/21
 2026-09-29 14:25:35 +08:00
jkooe 0a47c5a92d feat(E1+E2): 事件订阅与监控 —— agent 主动推送（能力 31 -> 35） 
## 协议
- 新增 Methods.Event = 'event'：协议中唯一的**无 id 通知**（JSON-RPC notification），
  被控端 → 控制端主动推送，控制端不回复
- 4 项能力：event.watch / event.unwatch / event.list / event.poll
- 能力处理器签名扩展为 (args, ctx?)：ctx 携带 owner（连接标识）与 emit（推送出口）

## 被控端（apps/agent/src/events.ts）
三类 watcher：
- file    —— fs.watch（支持 recursive + glob 过滤），报 created_or_removed / modified
- process —— 轮询 tasklist(win)/ps(posix) 做差分，报 process_started / process_exited
- net     —— 轮询 netstat 提取 LISTEN 端口做差分，报 port_opened / port_closed
两条出口并存：
1) **推送**：通过 event 通知实时发给创建订阅的连接
2) **环形缓冲 + 游标**：500 条上限、seq 游标增量拉取（适配无法收推送的 MCP）
其它：首次采样只建基线（避免开订阅就刷出几百条）；连接断开自动清理该连接的订阅（防泄漏）

## 控制端
- NodeAgentClient 新增 onEvent 回调；handleMessage 把无 id 的 event 通知分发过去
- CLI: nodeagent events [--kind file|process|net] [--path/--pattern/--recursive/--seconds]
       无 --kind 则列出当前订阅
- MCP: na_event_watch / na_event_poll / na_event_list / na_event_unwatch

## 真机验证（三类全部实测）
- 文件：创建/修改/删除 t1.txt -> 3 个事件实时推送（14:16:33/34/35）
- 进程：启动并关闭 Notepad.exe -> process_started / process_exited
- 端口：开-关 8899 -> port_opened / port_closed（基线 45 个监听端口）
全部**零轮询**到达控制端（由被控端主动推）。

单测 61 -> 63（补 event.watch 枚举/边界与 event.poll 游标校验）、e2e 21/21 全绿
 2026-09-29 14:19:09 +08:00
jkooe 7efe717cf8 fix(gui): window.list 进程名错乱 + screen.find UIA 只支持精确匹配 
## bug 1：所有窗口的进程名都报成 powershell
根因：C# 回调里用 $pid 接 GetWindowThreadProcessId 的输出 —— 但 $pid 是 PowerShell
**自动变量**（当前进程 ID），赋值被静默忽略，于是每个窗口都取到 powershell 的 PID。
改为 $procId。真机验证：cmd / hexin(同花顺) / SearchPictureTool / TextInputHost / explorer
均正确归属。

## bug 2：UIA 路径实际是精确匹配，与文档「子串匹配」不符
根因：用 PropertyCondition(NameProperty, text, IgnoreCase) —— IgnoreCase 只影响大小写，
仍是精确相等。实测「管理员: C:\WINDOWS\system32\cmd.exe」用 '管理员' 永远匹配不到。
改为：FindAll(Descendants, [控制类型条件]) 后按 IndexOf(OrdinalIgnoreCase) 子串过滤，
并加 20000 元素扫描上限防止超大 UI 树卡住。
真机验证：
  '管理员' -> 命中 '管理员: C:\WINDOWS\system32\cmd.exe' @ (548,312)
  '同花顺' -> 命中窗口标题 + 内部文本元素

## 顺带明确一个语义（写入文档）
is_foreground = 「持有键盘焦点」，不等于「视觉上在最上层」。
实测 cmd 持有焦点（is_foreground=true）但画面被全屏的「同花顺」覆盖 ——
此时按 UIA 返回的坐标点击会打到覆盖它的窗口上。
因此：**几何信息可信，视觉遮挡需另行确认**（点击前截屏复核）。

单测 61/61、e2e 21/21 全绿
 2026-09-29 13:30:23 +08:00
jkooe 2dccec9a5c feat(D): 生产化 —— 无人值守模式 / 一键升级 / 文档口径更新 
## D1 无人值守（install.ps1）
- 新增 -Unattended（S4U 登录类型）：**无需保存密码，注销/重启后仍自动运行**
- 新增 -AtStartup：追加开机触发器；任务设置补 StartWhenAvailable（错过触发后补跑）
- **诚实标注能力边界**：S4U 运行在非交互会话，GUI 能力（截屏/UIA/键鼠）不可用；
  -Unattended 与 -AllowInput 冲突时自动关闭输入控制并回写配置
- 说明文档给出两种模式的对照表（交互模式支持 GUI，但注销即停）

## D2 一键升级（nodeagent deploy）
- system.info 新增自描述字段：pid / agent_script / agent_home / node_path
- deploy 流程：读取被控端入口路径 → 备份旧文件 → 分块上传新 agent.mjs
  → 调 system.agent.restart 受控重启 → 等待恢复并复验能力数
- 真机验证：
  * 首次（旧版 agent 无自描述）：--path 指定 → 上传 853KB → PID 16492 / 31 项能力
  * 二次：自动识别路径 + 自动备份 → PID 34120 / 31 项能力（免 --path）

## D3 CI（待推送）
- windows-e2e.yml 增加单元测试步骤（3 行）；因 OAuth token 缺 workflow scope，
  该改动暂留本地未推送，需用户授权后推送

## D4 文档口径更新（README）
- 能力总览补齐 31 项（新增：自持/异步任务/窗口/录屏/剪贴板/拖拽/审计校验）
- 统计数字更正：19 项能力 -> 31，15 个 MCP 工具 -> 26，补 61 项单元测试
- 路线图补 v7~v11+；安全章节补密钥库/Audit 链/ACL 细化
- 命令速查新增：restart / deploy / daemon / fanout / bg / tasks / clip / record /
  window.* / screen.find / mouse drag
- MCP 工具表按新工具重排；安装章节新增两种运行模式对照表

单测 61/61、e2e 21/21 全绿
v1.1.0 		2026-09-29 11:47:15 +08:00
jkooe ad88e0bb87 feat(C): 操作面补完 —— 拖拽 / 录屏 / 剪贴板图片 / 多设备并发（能力 29 -> 31） 
## C1 鼠标拖拽（input.mouse.drag）
- C# SendInput 新增 Drag()：按下 → 分步插值移动 → 抬起，整段在一次进程内完成
  （避免每步一个 PS 进程的抖动），步数按距离自适应（8~60），步间延时默认 12ms
- CLI: nodeagent mouse drag <x1> <y1> <x2> <y2>；MCP: na_mouse action=drag
- 同时给 key.press 增加 interval_ms（按键序列间隔可调）
- 真机端到端验证：记事本输入 DRAGTEST_1234 -> 拖选 -> Ctrl+C
  -> 剪贴板由 'CLIPBOARD_EMPTY_MARKER' 变为 'DRAGTEST_1234'（证明拖拽真实生效）

## C2 录屏（screen.record）
- 帧循环在一次 PS 调用内完成；有 ffmpeg 则自动封装 mp4
- 产物留在被控端目录，由调用方 fs.read / pull 取回（不把大视频塞进单条 RPC 响应）
- CLI: nodeagent record --duration/--fps/--scale/--region；MCP: na_record
- 真机验证：3s@2fps 区域录制 -> 6 帧（3087ms），pull 回帧并目检内容正确

## C3 剪贴板图片（clip.get/set 1.1）
- format=auto/text/image；图片经临时文件双向传递（规避 Windows 命令行 ~32KB 上限与 stdout 截断）
- CLI: clip --image-file <路径> / clip --out <路径>；MCP: na_clip format/image_base64
- 真机验证：写入 14592 字节 -> 读回 PNG 400x200，目检图像正确

## C5 多设备并发（fanout）
- nodeagent fanout <能力> [--nodes a,b] [--args JSON]：allSettled 并发，任一失败不影响其他
- 真机验证：并发下发 system.info / system.status 正常

单测 59 -> 61、e2e 21/21 全绿
注：C4（macOS window.*/screen.find 对齐）暂缓，需 macOS 辅助功能/录屏权限，留待 Mac 作被控端时实现
 2026-09-29 11:41:48 +08:00
jkooe eb54c60c7c feat(B): 安全加固 —— 密钥库保护 + 审计防篡改 + ACL 细化（能力 28 -> 29） 
## B1 私钥不再明文落盘
- 新增 packages/client/src/secret.ts：macOS Keychain / Windows DPAPI（CurrentUser）
- keys.ts：落盘文件只留 secret 描述符（backend/label/protected），不含 privateKey；
  老格式明文密钥**首次加载自动迁移**；后端不可用时回退明文 + 告警（绝不因保护而不可用）
- 真机验证（隔离目录）：
  * keygen -> '✓ 私钥已存入系统密钥库（keychain）'，文件中无 privateKey，钥匙串有条目
  * loadKeys 回读私钥成功（64 字符）
  * 老格式明文文件 -> 自动迁移、文件清理、二次回读正常
  * Windows DPAPI 往返一致（ROUNDTRIP_OK=True，密文不含明文）

## B2 审计链式哈希（防篡改）
- 每条审计记录加 prev/hash（prev+规范化正文 sha256 前 32 位）；轮转跨文件连续
- agent 重启从日志尾部恢复锚点，链不断
- 新能力 system.audit.verify + CLI 'nodeagent audit verify'
- 真机：'✓ 审计链完整（校验 21 条，跳过历史条目 857 条）'
- 单测覆盖：篡改检出、删除中间条目检出（链断裂）、历史条目 legacy 跳过、重启续链

## B3 ACL 细化
- 协议层新增纯函数：normalizeIp / ipMatchesCidr / ipAllowed / inTimeWindow / rateLimitFor
- AclClient 扩展：allow_cidr / deny_cidr / allow_window(days+from/to，支持跨零点) / rate_limits
- server.ts：IP 白黑名单与生效时段校验（命中即 audit acl.denied）；限速改为按能力
  （rate_limits 精确优先、其次 glob、回退 max_calls_per_min），窗口按限速档位分桶

### 真机踩坑（已修复并回归）
Node 的 socket.remoteAddress 在双栈监听下是 **IPv4-mapped IPv6**（::ffff:192.168.1.100），
原用 split(':')[0] 取到空串 -> CIDR 永不匹配。新增 normalizeIp() 归一，单测覆盖该场景。
真机复测：'✗ E_ACL_DENIED: 来源 IP 不被允许'；移除黑名单后 fs.list 连调 3 次 ->
第 3 次 '✗ E_RATE_LIMITED: 调用频率超限（fs.list 上限 2/分钟）'

单测 37 -> 59、e2e 21/21 全绿
 2026-09-29 11:27:52 +08:00
jkooe 9bf330d228 fix(A): 阶段 A 稳定性清账 —— 单测 26 -> 37、按键序列、日志上限 
A1 后台任务环境统一
- 抽出 childEnv() 并由 execCommand / task.ts 共用（PYTHONIOENCODING/LANG/LC_ALL）
  实测：后台任务中文正常（PowerShell 的 UTF-8 前缀本就生效，本次补齐子进程 env）

A2 按键语义扩展（input.key.press 1.1）
- keys + repeat=N：同一和弦连按 N 次（解决「连按上键 3 次」）
- sequence=[[...],[...]]：任意和弦序列
- 真机验证：repeat=3 -> times 3；sequence 2 段 -> times 2；和弦向后兼容
- manifest 补 minimum/maximum 约束

A3 重启日志保留上限
- 每次重启仅保留最近 5 个 nodeagent-restart-*.log（PowerShell 排序后 Skip 5 删除）
- 实测：日志数由累积多份收敛为 2 份，重启链路仍正常

A4 新能力单测（tests/unit/capabilities.test.mjs，+11 用例）
- 清单守护：能力名与 manifest 一一对应、无重复、字段合法、schema 封闭、共 28 项
- 参数校验：task.get/clip.set/screen.find(method 枚举)/key.press(repeat+sequence)/restart/exec(async)
- 默认值：screen.find.method=auto、task.get.offset=0、exec.async=false
- 顺带发现并修复：restart.delay_ms 缺 minimum 约束（0 被接受）
 2026-09-29 11:13:53 +08:00
jkooe fac51046cf feat(v10.1): CLI 常驻 daemon（nodeagentd）—— 连接池复用，批量调用提速 
## 机制
- nodeagentd 常驻进程监听 UDS（$TMPDIR/nodeagentd.sock），持有与被控端的
  长连接池（autoReconnect，每设备一条，LRU 上限 8，空闲 5min 释放）
- CLI withClient 检测 socket 存活 → 经 daemon JSON-lines 转发 invoke（虚拟 client）；
  daemon 自身错误静默回退直连，业务错误原样透传 —— 零行为变化，纯加速层
- CLI 新命令: nodeagent daemon start|stop|status；打包新增 nodeagentd 产物

## 实测（真机）
- 轻调用（info）: 752ms -> 527ms（省 TLS+hello/challenge/auth，约 30%）
- 轻调用 5 连发（clip.get）: 2.58s -> 2.41s
- 重调用（ps 远端 CPU 采样 1.4s）提速不显著 —— 瓶颈在远端执行而非握手，符合预期
- unit 26/26、e2e 21/21 全绿
 2026-09-29 10:55:38 +08:00
jkooe e50e805383 feat(v10): 长任务异步化（system.task.*）+ 剪贴板（clip.*），能力 23 -> 28 
## 长任务异步化（P1）
- system.shell.exec 增加 async:true -> 立即返回 task_id（wait_forever 可不设超时）
- system.task.list / get / kill：任务表（Map 内存态，完成态保留 30min / 上限 50 条），
  输出 Buffer 累积（上限 10MB），get 支持 offset 增量续读
- kill 走 killTree（整棵进程树）；超时自动标记 killed/exit=124（与 timeout(1) 惯例一致）
- 命令只记 sha256 前 8 位摘要（与审计脱敏策略一致）
- CLI：bg / tasks / task <id> [--offset N] [--kill]

## 剪贴板（P1）
- clip.get / clip.set（Windows: Get/Set-Clipboard；macOS: pbpaste/pbcopy）
- set 走 base64 传输规避命令行参数编码问题（中文/emoji 安全）

## MCP 同步
- na_bg / na_task（list|get|kill 多动作）/ na_clip（get|set 多动作）

真机验证（全生命周期）：
- bg 20 秒长任务 -> 立即返回 task_id；tasks 列表 running；
  task 增量读 tick 10~12 -> 14~15；--kill 后 killed/exit=124
- clip --set 中文+emoji -> 18 字符；读回逐字一致
- 28 项能力在线；unit 26/26、e2e 21/21 全绿；Mac 端 CLI/MCP 已重装
 2026-09-29 01:19:10 +08:00
jkooe e4cc1c20b6 feat(v9): screen.find OCR 兜底 + MCP 同步 4 项新工具 
## screen.find OCR 引擎（自绘 UI 兜底）
- method 参数：auto（UIA 优先，空结果自动 OCR）/ uia / ocr；返回 engine 字段
- OCR 实现：CopyFromScreen 截区域（可限定窗口矩形）→ WinRT BitmapDecoder →
  Windows.Media.Ocr（zh-Hans-CN）→ 行/词矩形 → 屏幕坐标
- 两个真机坑（均已实证修复）：
  1) Windows OCR 会在中文字符间插空格（「我的加速」识别为「我 的 加 速」），
     子串匹配永远失败 → 匹配一律在去空格文本上进行，
     并用「最小词窗口并集」精确定位目标词段的矩形
  2) 重启任务的 cmd 用 >> nodeagent-restart.log 启动新 agent，新 agent 长期持有
     该文件句柄 → 下次重启任务所有带该重定向的命令被整体跳过（包括 taskkill！），
     表现为 restart 返回 ok 但什么都没发生 → 日志文件改为时间戳唯一 + 清理历史
- 真机验证（加速器自绘界面）：「网络监控」@(2174,568)、「STEAM」@(1590,582)、
  「我的加速」@(1365,434)，截图目检坐标全部精确吻合

## MCP 同步（能力 19 -> 23 对 AI 可用）
- 新增 na_restart / na_window_list / na_window_focus / na_screen_find
- unit 26/26、e2e 21/21 全绿
 2026-09-29 00:59:15 +08:00