mtfyun/nodeagent
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
208 Commits 1 Branch 14 Tags
560b3c44e4eb3e653a274d59b955260790f2f2b1
Commit Graph
52 Commits
Author SHA1 Message Date
jkooe 560b3c44e4 fix(agent): 限速桶 key 改能力名 + describeArgs 截断（A-P0-2 / A-P0-4） 
架构审查两个 P0：

A-P0-2 限速桶 key 用错值（server.ts:364）：
原实现 `allowByRate(clientId, limit, String(limit))` 把**限速值**
当桶名——ACL 支持按能力限速（精确 > glob > 全局），配
「screen.capture ≤5/min、app.install ≤5/min」两条同值规则时
两者 key 都是 `clientId|5` 共用一个桶：截图打满后装软件被误伤，
且两者总量仍按 5/min（漏过）。同时 rateBuckets 只增不删 +
psk 模式 client_id 自报 → 外部可枚举任意 client_id 造键 →
长期运行内存无界增长。
- 抽到 util/rate-limit.ts：key = `${认证身份 ?? 远端地址}:${能力名}`
  （未认证时退化按远端地址，不用空串把所有人混为一桶）
- 过期键清扫（滑动窗口边界与旧实现逐字节一致：now - t < 60_000
  才算窗口内）+ 容量上限淘汰最旧（Map 插入序 = 时间序）
- e2e limited 客户端改配两个同限速值能力（各 2/min），
  打满 system.info 后 system.audit.list 必须仍有完整配额

A-P0-4 describeArgs 大参数同步序列化阻塞事件循环（audit.ts:172）：
原实现每次 invoke 全量 JSON.stringify + sha256。fs.write 的 data
可达数 MB——同步序列化 + 哈希 ≈ 数十毫秒级 CPU 且阻塞事件循环，
期间 GUI 注入、事件推送、保活 ping 全部延迟。
- 超过 64KB 只哈希前 64KB（按**字节**切：多字节字符下按字符切
  会得到非确定性边界），总长记 args_bytes、截断记 args_truncated
- 口径从「全量哈希」变为「前 64KB 哈希」只影响审计摘要，
  不影响任何安全属性（摘要用途是比对与防泄密，不是完整性证明）

测试（均故障注入实测会红）：
- rate-limit 6 例：桶名是能力名 / 身份进 key / 不限速不建桶 /
  过期键清扫（59.999s 窗口内、恰好 60s 出窗）/ 容量上限 /
  同值多能力各占一桶
- audit-args-digest 6 例：小参数口径不回退 / 大参数截断口径 /
  按字节切（字符切口径必须不同）/ 尾部不进摘要 / 端到端入链
  校验通过 / logArgs 默认关不产预览
- e2e 注入验证：桶名退回 String(rateLimit) → v3 场景红；恢复 → 绿

单测 445/445、e2e 33/33、typecheck 全绿
 2026-10-26 00:14:17 +08:00
jkooe 68ea3cd20e fix(protocol): validate 拒检原型链键（A-P0-1，in → Object.hasOwn） 
架构审查 A-P0-1：validate.ts:69 用 `key in schema.properties` 判
「附加属性是否允许」，而 `in` 沿原型链查找——JSON 里写
`"constructor"` / `"toString"` / `"__proto__"` 等键会命中
Object.prototype 成员被判为「schema 已声明」从而跳过拒绝，
fail-open（与 server.ts B-03 同源复发：那个修的是 ACL clients，
这个修的是 returns_schema 校验）。

- 改为 `Object.prototype.hasOwnProperty.call(schema.properties, key)`，
  只认真实声明的属性
- 补 2 个「注入即红」用例：原型键必须被判 additional property；
  真实 manifest 能力 system.agent.update 同样拒原型键、合法调用照过
- 故障注入实测：改回 `in` → 2 例红；恢复 → 全绿

安全属性收紧（原行为是漏放），无任何放宽。
 2026-10-26 00:14:00 +08:00
jkooe cb468df7da feat(agent): 看门狗自动恢复 LKG —— 启动连续失败 N 次从 LKG 恢复（决策 R-1） 
scripts/startup-guard.mjs + scripts/lib/startup-guard-core.mjs（新增）：
- 被控端启动连续失败 N 次（默认 3）自动从 LKG 指纹匹配的备份恢复入口脚本
- 30s 启动宽限期 + 端口探活，避免计划内重启与 supervisor 重启撞车被误计数
- 无 LKG / 无指纹匹配只记日志放行，绝不擦除 install-dir
- 恢复成功或服务已就绪均归零失败计数；被控端启动成功后 resetStartupGuardState 归零
  （apps/agent/src/index.ts 为本任务对 agent 的唯一改动点）

三端 supervisor 接入：
- Windows install.ps1：计划任务包一层 guard，RestartCount 3→10（保证阈值可达）
- Linux install-linux.sh：systemd unit 的 ExecStart 包一层 guard
- macOS launchd：无安装器，docs/DEVELOPMENT.md §7.4 给出完整接法

docs：DELIVERY-PIPELINE §6 由「不做自动回滚」收窄为
「手动 rollback + 看门狗自动恢复 + 边界明示」，附录 C 同步；
DEVELOPMENT.md 新增 §7.4 三端 supervisor 接入说明。
 2026-10-26 00:09:56 +08:00
jkooe 1249c90725 feat(agent): selfupdate 代理出网 + LKG 内容指针 + L2/AgentUpdate 契约补全 
P0-1 被控端自更新境内必然失败（裸 fetch 不读代理）：
- 新增 apps/agent/src/net/proxy.ts + index.ts：sidecar 已验证出网方案的
  TS 移植（NA_PROXY → 环境变量 → 系统代理；PAC/socks 明确报错不静默降级；
  重定向链共享超时预算；CONNECT 自管 abort；TLS 默认校验证书）。
  只依赖 node 内置模块，不 import 项目内任何模块（依赖严格单向）
- selfupdate.download 改走代理；成功/失败均带回 via/proxy/proxy_source/
  outbound_notes 诊断；错误分类同款移植 sidecar main.mjs:146-165
  （ECONNRESET 不得报成「请求超时」——真机教训）
- httpGet 增 maxBytes 双闸（content-length 预检 + 流式中断），
  保住「64MB 上限」安全属性
- 回环目标恒直连（CI/dev 机 HTTP_PROXY 不得误送自建镜像进代理——
  e2e 实踩：代理另一侧的 localhost 不是本机 → 404）

A-P0-3 LKG 只有指纹没有内容指针：
- LkgRecord 只增 hash_full（64 位全量）+ backup_glob（.bak*）两字段；
  新增 lkgHashMatches（全量优先、老记录回落 12 位前缀，不猜）
- selfupdate 备份保留最近 3 个（planBackupCleanup 纯函数，最旧先删）

P1-4 system.audit.l2 returns_schema 空壳 → 四 action 属性并集补全；
AgentUpdate returns 增 via/proxy/proxy_source/outbound_notes 四个只增字段

安全属性逐条不变：sha256 强制校验 / 先校验后落盘 / 写后校验失败回滚 /
TLS 默认校验证书 / 只接受 http(s)

测试：新增 agent-proxy 17 例 + selfupdate-backup-cleanup 8 例 +
lkg 新增 4 例；单测 403/403、e2e 33/33、typecheck 全绿
 2026-10-25 23:58:30 +08:00
jkooe 6b2fa29710 feat(cli): nodeagent rollback —— 从 LKG 回滚被控端（ARCH T03 / PRD P0-2） 
- 新增 apps/cli/src/cmd/rollback.ts：读 LKG → 指纹比对定位备份 →
  覆盖写入口（同 deploy 姿势）→ 写后校验（失败用回滚源还原）→
  受控重启 → probeOnce 复核 build.hash == LKG（90s 墙钟）
- 纯函数 planRollback/pickBackupByHash/hashMatches/backupNameRegex +
  流式 hashRemoteFile（client 注入，可假测）；hash_full 全量优先、
  老记录回落 12 位前缀（A-P0-3/R-2 向后兼容）
- --dry-run 只读零写；--backup 逃生门直指备份路径；退出码 0/1/2 分明
- HELP/README 写明能力圈边界：RPC 命令需被控端可达，「完全起不来」
  走看门狗自动恢复或带外恢复；不提供自动回滚（DELIVERY-PIPELINE §6）
- 19 条单测：无 LKG 零调用 / already-lkg 零写 / 写后校验失败自动还原 /
  无匹配零写 / dry-run 只读 / 多候选 mtime 新→早 / Windows 路径与元字符
 2026-10-25 23:45:02 +08:00
jkooe 7d781d132e feat(audit): L2 系统级审计兜底 —— 三端设计 + Windows 落地 
## 它补的是 L1 结构上记不到的那块
L1 是 agent 自己记的，只看得见经过自己 RPC 的调用。攻击者绕过 agent
直接跑系统命令、或干脆把 agent 停掉 —— L1 全部盲区。L2 采集操作系统
自己的审计事件，补的正是这块。设计见 docs/AUDIT-L2.md。

## 必须先说清的信任边界（不夸大作用）
采集器与 agent 同进程同权限 —— 攻击者能停 agent 就能停采集器。
故本地 audit-l2.log 只是一份**归一化副本**，防篡改价值有限。
真正的独立性来自**把记录转发出机**（与 SECURITY.md §4.8 锚定同一思路）。
本实现不自动转发，只提供导出接口；这一点已写入文档与能力描述。

## 三端
- Windows：**落地**。选内置 auditpol 而非 Sysmon —— Sysmon 是第三方驱动，
  需单独分发、需重启生效、版本行为有差异；内置策略零依赖即可立起来。
  检测到装了 Sysmon 则并用，未装不尝试下载。
  - status：查策略是否启用，并提示两个关键开关
    * SCENoApplyLegacyAuditPolicy —— 不设它，组策略旧式类别策略会盖掉
      subcategory，表现为「auditpol 显示已启用但事件日志里没有 4688」
    * ProcessCreationIncludeCmdLine_Enabled —— 不开则 4688 只有进程名
  - enable：开启进程创建 4688 / 登录 4624,4625 / 进程终止 4689（需管理员）
  - collect：Get-WinEvent 拉取 → 归一化 → 独立落盘（带哈希链）
  - verify：L2 链完整性校验
- Linux：仅设计（auditd，需预装），未落地
- macOS：仅设计，ESF 需 Apple entitlement 且必须是签名 System Extension，
  个人自签无法启用 —— 不写假装能用的代码

## 落盘与 schema
独立文件 audit-l2.log，不与 L1 混 —— 混了就无法区分「agent 记的」与
「OS 记的」。记录含 ts（OS 事件时间）、src、event_id（保留原始便于核对）、
kind（归一化类别）、collected_at（采集时刻，与 ts 差过大说明曾离线）。

## 实测
- 新增 8 条单测，含两条故障注入：篡改内容检出「哈希不符」、
  删中间条目检出「链断裂」
- 既有契约守卫两次报红并已被修复：manifest 新增 lkg 字段 → SystemInfo 接口缺声明；
  新增 system.audit.l2 → 能力清单断言过期（51→52）
- 全量单测 349 → 357 全绿
 2026-10-17 03:24:17 +08:00
jkooe 2bf45fdf98 feat(pipeline): 交付流水线规范落地 —— 门禁 + LKG 回滚锚点 
将《代码审计 → 上线 完整交付方案》v1.0 适配到 nodeagent，产出
docs/DELIVERY-PIPELINE.md，并落地其中可执行的部分。

## 为什么要适配而不是照搬
原方案面向 Web/容器服务（有服务端、有镜像、有多环境）。nodeagent 是
跑在用户机器上的跨机接管框架，无服务端、无容器、无多环境。照搬会产生
「跑得很好但守不住任何东西」的假门禁。故每个阶段给三档判定：
适用 / 改造后适用 / 不适用（但必须给替代，不允许只写 N/A）。

关键替换：
- 容器镜像扫描 → 交付物 PE 架构断言（arm64 包误装 x64 node.exe 的真实事故）
- DAST → 协议健壮性测试（本项目对外输入面是 WebSocket RPC，非 HTTP）
- dev/staging/prod → 真机矩阵（Win x64/arm64、macOS、Linux）
- 金丝雀 → 设备分批自更新（先一台试点，latest.json 灰度）
- Prometheus → system.metrics（闭环率/P95/拦截率）+ 发布后复核清单

## 本次落地
1. 覆盖率门禁 scripts/ci/check-coverage.mjs
   - 全量**只观测不阻断**（实测基线 66.9%，照搬 80% 全量不现实）
   - 变更文件行覆盖率 ≥70% 阻断；单测 import 的是 dist/，需 src→dist 映射
   - 无覆盖数据的变更文件不阻断，单列供人工判断（算 0% 会让重构无法合入）
2. 提交信息校验 scripts/ci/check-commit-msg.mjs
   - 项目实际已在用 Conventional Commits，但无强制 → 变成会红的门禁
   - 不引 commitlint+husky：本项目只需类型白名单，几十行即可且 CI 本地都能跑
3. .github/workflows/quality-gate.yml：gitleaks + pnpm audit + typecheck + 覆盖率 + 提交规范
4. CI artifact retention-days 30 → 7（公开可下载，留存越久暴露面越大）
5. LKG（最后已知可用版本）apps/agent/src/lkg.ts
   - 只在**启动成功后**才写，不在更新写完时写（否则等于把未验证版本当已知可用）
   - 暴露为 system.info.lkg，matches=false 表示当前版本尚未被证明能启动
   - 控制端据此暂缓向其余设备放量

## 刻意不做的事：自动回滚
远程设备上无法区分「更新坏了」与「网络抖动」；自动回滚可能形成回滚循环；
被控端自作主张改自己会让控制端失去掌控。故 LKG 只提供确定的回滚目标，
决策权留给控制端。已在文档中写明取舍理由。

## 实测证据
- 覆盖率门禁三条故障注入均 exit=1（阈值100 / 全量99 / lcov缺失），正常 exit=0
- 提交规范反例 3 类均红，Merge 与无 scope 正确豁免，历史 20 条提交一次通过
- LKG 新增 8 条单测（含篡改 hash 必须检出 matches=false）
- 既有契约测试在新增 lkg 字段后立刻报红（SystemInfo 缺声明），补接口后转绿
  —— 这本身是门禁有效的实证
- 全量单测 341 → 349 全绿
 2026-10-17 03:13:18 +08:00
jkooe b34e8c73e0 fix(console): 让「检查更新」在境内真的能用 —— 自持出网 + 系统代理发现 
真机症状：控制台点「检查更新」必报 `检查更新失败：fetch failed`。
上一轮曾把此项归因为「环境网络问题」而收工；本轮按「即使环境本身不通，
代码也不该让用户无从自救」重新定位，确认为**产品缺陷**。

三条根因（均经隔离实测）
- Node 内建 fetch（undici）默认不读任何代理环境变量。`NODE_USE_ENV_PROXY=1` 可开，
  未开时 env 被**完全忽略** —— `env -i` 对照实验：带 flag 得 `fetch failed`（证明 flag 生效），
  不带得 `timeout`（证明 env 被忽略）。
- 系统代理（WinINET / macOS 网络设置）Node 亦不读；而 `fetch(url,{dispatcher})` 走不通 ——
  dispatcher 必须是 undici 的 Dispatcher 实例，Node 未把 undici 暴露为可导入模块，
  整包 vendored 会撑胖 sidecar 且其依赖 .wasm 解析器，esbuild 单文件打包有风险。
- 内部超时 20s 对真实重定向链必然失败：`latest.json` → 版本化 URL → CDN，
  实测耗时 2.0 / 10.0 / 39.7 / 68.6 / >109 秒。

修法
- 新增 `apps/console/sidecar/proxy.mjs`（自持出网，零新依赖）：https 目标走 `CONNECT host:443`
  隧道后叠 TLS（隧道返回的 socket 已是 TLS，须用 `http.request` 承载，用 `https.request` 会二次握手；
  且**不可把 URL 对象当第一参**，否则会覆盖手搭的代理字段退化成直连）；http 目标走绝对形态请求行；
  含 NO_PROXY 匹配、系统代理发现（`reg query` / `scutil --proxy`，PAC 不可解析时记 note 而非静默）、
  socks5 等看不懂的形态一律记 note。
- `check_update` / `download` 全部改走 `httpGet`，整条重定向链共享一个超时预算与 AbortController。
- 内外超时成对下发：`sidecar.rs` 新增 `UPDATE_CHECK_TIMEOUT_MS`/`_RPC_TIMEOUT_SECS` 与
  `UPDATE_DOWNLOAD_TIMEOUT_MS`/`_RPC_TIMEOUT_SECS` 两组常量 + **编译期不变式**
  （`const _: () => assert!(...)`），保证「出网超时 < RPC 超时」——否则用户只会看到
  丢掉真实原因的「check_update 超时」假失败。订正 6 处因超时改动而变陈旧的注释。
- 失败信息带 `url` + `via`/`proxy`/`proxy_source`/`timeout_ms`/`hint`；界面新增「出网」行，
  并修掉重复前缀（`检查更新失败：检查更新失败：…`）。

顺带修掉两个真机暴露的缺陷
- **隧道/TLS 阶段的 abort 无人受理**：`createConnection` 回调返回前外层请求尚未建立，
  外层 `signal`/`timeout` 无人受理 → 真机实测配 75s 超时却挂了 109s。
- **`ECONNRESET` 被归入 abort 类** → 报成「请求超时」（真机：耗时 82.9s 却报「120000ms 内未完成」）。
  改为只认真 abort，并新增网络错误翻译（ENOTFOUND/EAI_AGAIN/ECONNREFUSED/ECONNRESET/EPIPE）。

守卫与验证
- 新增 `tests/unit/sidecar-proxy.test.mjs`（16 用例，四段：纯函数 / 真发请求 / 端到端
  spawn sidecar 跑 JSON-RPC / 形态守卫）。夹具用本机真 `scutil --proxy` 与真 `reg query` 输出，
  地址改为 RFC 5737 文档段，不写内网 IP、不写工具实名。
- 守卫落在「最终下发的请求」与「产物字节」上，逐条**注入故障实测会红、还原后逐字节一致**：
  ① `check_update` 退回裸 `fetch` → 代理未收到该次请求 → 红
  ② 去掉 `isBypassed` 后缀匹配 → 红
  ③ 出网/RPC 超时改回反序 → 红 / `error[E0080]`
  ④ 去掉隧道 abort 挂载 → 红（`实际 4002ms`）
  ⑤ `ECONNRESET` 塞回 abort 类 → 红
- 全量：`unit` **341/341**、`rust` **18/18**、`clippy -D warnings` 干净、`vue-tsc` 退出码 0。

未覆盖项（如实记档）
- https 经 CONNECT 隧道叠 TLS 无离线自动化用例：`selfsigned` 只在 `apps/agent` 包内，
  测试进程解析不到 → 无法离线造受信任 TLS 站点；该路径仅真机验证。
- 真机「经代理取 GitHub 成功」的那一组未取到（宿主两条代理线路当时都取不到 GitHub），
  属环境而非产品缺陷；错误信息已可操作（含 `via`/`proxy_source`/`hint`）。
- 同类缺陷**第三处未改**：`apps/agent/src/capabilities/selfupdate.ts` 仍是裸 `fetch`
  （属被控端变更，改则需升 PATCH）。

注：本项为上壳变更，不触发 release patch；`apps/console` 至今未接入 `release.mjs`。
 2026-10-13 22:41:02 +08:00
jkooe b9236dfaf1 chore(privacy): 公开仓库隐私脱敏 —— 清除可定位到个人与设备的字面量 
按 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。
 2026-10-13 22:35:40 +08:00
jkooe 6adf11c85a fix(test): 两条守卫在 Windows 上必红（CRLF 与路径分隔符） 
CI run 38380306200（提交 73ed06f）Windows 单元测试 319/321，macOS 全绿。

① 仓库内全部版本号互一致 → 报 undefined apps/console/src-tauri/Cargo.lock
   根因：actions/checkout 在 Windows 默认 core.autocrlf=true → CRLF，
   而 Cargo.lock 的版本提取把 \n 写死。**同一隐患也在生产代码里**：
   version-write.mjs 另有一条 name…\nversion… 正则读旧值，CRLF 下返回
   undefined → 把 Cargo.lock 记入 skipped 并跳过 → 发版后滞留旧版本
   （正是本模块要消灭的分叉，且不报错）。
   修法：读旧值收敛到 readCargoTomlVersion / setCargoLockVersion().before
   单一真源，删掉重复正则；新增 splitLineEol() 拆「正文+行尾」后改写
   （不能写 ("".*)$ 兜行尾 —— JS 的 . 不匹配 \r）。

② W-01 根因守卫 → 把唯一真源自己判成违规（util\quote.ts）
   根因：file.slice(dir.length+1) 在 Windows 得到反斜杠路径，与白名单
   的 util/quote.ts 比不中 → 守卫自己错。
   修法：新增 relPosix() 归一成 /。

新增 4 条守卫：Cargo.lock / Cargo.toml 的 CRLF 纯函数用例、
CRLF 工作区上真跑 writeVersionEverywhere 再读回文件、
以及用 path.win32 形态字符串在 macOS 上直接测 Windows 分支。
注入故障实测 4 条如期变红；test:unit 325/325（321 + 4）。
 2026-10-13 18:57:04 +08:00
jkooe bce11514a9 fix(release): 发版脚本漏改 Cargo 清单导致版本号分叉 
release.mjs patch --dry-run 实测：只改 8 个 package.json + 1 个 tauri.conf.json，而
apps/console/src-tauri/{Cargo.toml,Cargo.lock} 里**同样存着 2.0.2** —— 发版后必然滞留，
与 tauri.conf.json 悄悄分叉，且**不报错**（Tauri 打包以 tauri.conf.json 为准）。

- 版本写入抽成 scripts/lib/version-write.mjs（纯函数、可测），release.mjs 调用它。
  抽出来的理由：埋在脚本里时单测只能断言「源码里出现过某个字符串」—— 那种守卫注入
  故障都不会变红（铁律：守卫要落在最终产物字节上）。
- Cargo.toml **只在 [package] 段**改（非 package 段里也可能有独占一行的 version = "…"）；
  Cargo.lock **按 [[package]] 块 + crate 名定位**（全文盲替换会改坏 thiserror 2.0.21
  这类依赖版本）。
- release.mjs 的「脏文件白名单」改为取自**实际改写结果**（changed），不再手写文件名列表 ——
  手写的那份一旦与写入逻辑漂移，要么拦下本该放行的（发版卡死），要么放过不该放行的
  （静默推走改动）。
- 新增 tests/unit/version-write.test.mjs（9 条）：在临时目录铺**真实文件**并 git init/git add
  （versionTargets 走 git ls-files，不真进索引就会假绿），跑完读回文件断言；另含一条
  **仓库版本号一致性守卫**，发版漏项会直接变红。
- 注入 4 处故障实测：编排漏 Cargo / Cargo.toml 全文盲替换 / Cargo.lock 按位置盲改 /
  仓库版本分叉 —— 全部变红，还原后全绿。
 2026-10-13 17:16:46 +08:00
jkooe ae02252a1d fix(agent): 修复 18 条实机复现缺陷（2×P0 / 5×P1 / 10×P2 / 1×P3） 
一轮「静态审查 + 真机实测」的完整普查。基线 v2.0.2 / ad90634 上 unit 291 + e2e 30
全绿 —— 也就是说 18 条**全部落在既有覆盖之外**。报告见 bug-report-2026-10-13.html。

P0 两条：
- W-01：window.focus 把 JSON.stringify(title) 插进 PowerShell **双引号**串（PS 里 `\` 不是
  转义符、双引号串还会展开 $(...)）→ 命令注入。真机实测最险的是它**静默**：接口返回的是
  「正常业务错误」E_EXECUTION_FAILED: 未找到匹配的窗口，而 payload 已经把文件创建出来了。
  新增 apps/agent/src/util/quote.ts 作 psLit/shLit 单一真源，14 处注入点收敛（window.focus /
  uiaFind / ocrFind / system.ts 计划任务参数 / ps-helper.ts 的 -File 裸拼 …）。
- A-01：ACL 省略 clients 时 aclPolicy.clients.find 抛错，而这段落在 if (hasAcl) 块**之外**
  无条件执行 → 配置少写一个字段，每条 invoke 都崩掉被控端。
  ⚠️ 静态审查当时判它是「fail-open 放行」，实测是崩溃（更严重）。

崩溃链共同根因：ws.on('message') 用 void handleMessage() 且无 .catch，全仓又没有任何
process.on('unhandledRejection') —— Node ≥22 遇未处理 rejection 直接终止进程。两条畸形报文
（hello {protocol:123} / auth {hmac:1}）就能在**认证之前**打死被控端（verifyNonce 有 try/catch，
psk 默认路径的 verifyHmac 没有）。index.ts 新增进程级兜底：日志每次打、审计按 10s 限流
（否则畸形报文可高频刷爆 audit.log），且明确不退出进程（可用性优先，取舍写在注释里）。

其余 15 条：
- clients: [] → fail-open 全放行（判据改为「对象是否存在」而非「数组长度」）
- macOS screen.find 的 text 拼 bash → $(...) 实测执行（走 shLit）
- 控制台审计筛选项与协议 enum 漂移，除 invoke 外全 E_PARAM_INVALID
  → 新增 packages/protocol/src/audit-types.ts 作唯一真源，manifest enum 由它派生 + 编译期双向守卫
- monitor.start 的 target 注入、monitor id 路径穿越（读/删）→ psLit + guardPath
- keys{} + client_id:"constructor" 崩 → hasOwnProperty（原型链取值）
- 事件订阅跨控制端可见/可删、event.watch 绕开 fs_roots → 有状态资源落 owner + 统一白名单
- screen.capture 的 region 无上界 → assertRegionSane() 且**提前到枚举显示器之前**（fail fast）
- ipMatchesCidr('8.8.8.8','10.0.0.0/') → true（空掩码被 Number('') === 0 当 /0）
- CLI --timeout 静默失效（strict:false 下未声明选项被当 boolean，值掉进 positionals）
- 拒绝类事件不写审计 → 补 request.rejected / agent.error

回归：unit 321/321（+21）、e2e 33/33（+3 组硬化用例）、rust 11/11。
e2e 新增用例的姿势：每场景**独占端口 + 独立临时 NODEAGENT_HOME**（首版复用端口，
连上了上一块的残留实例，把对照组误判成「实现有缺陷」）。
新增守卫均按铁律注入故障实测：确认会变红、还原后复核一致。
 2026-10-13 17:16:36 +08:00
jkooe ad90634a18 fix(test): 兜底守卫的片段排除在 Windows 上失效（跨平台路径分隔符） 
CI（Windows E2E，run 38166982975）在「单元测试」步骤红：

  not ok 102 - 兜底：capabilities 下命中坐标信号的新文件必须引用 PS_DPI_AWARE
    - apps\agent\src\capabilities\win-ps\prelude-image.ts（命中 "CopyFromScreen"）

而本机 macOS 全绿 —— 又是一例「本地全绿 ≠ Windows 绿」。

根因：`rel = relative(ROOT, full)` 在 Windows 返回 `apps\agent\…`，而排除规则写的是
`rel.includes('capabilities/win-ps/')`（**硬编码 "/"）→ 在 Windows 上恒为 false
→ 片段文件被误报成违规。排除本身是**对的**（prelude-* / body-* 由 WIN_HELPER_PRELUDE
在最前面统一注入 DPI 感知，其序位已由第 5 条断言），错的只是判断依赖了平台分隔符。

修法：
- 新增 `toPosix()`：把任意平台路径归一为 posix 形态（附注释说明为何必须显式归一）；
- 把「是否排除」收敛成纯函数 `isWinPsFragment(relPath, name)`，**函数内自带归一化** ——
  调用方传什么形态都正确，且可在本地直接断言；
- `walk` 内改用归一化后的 `rel` 并调用该函数。

新增守卫（第 9 条）：直接喂 Windows 反斜杠路径断言排除逻辑，把这类差异钉进
「本地可验」的范围。已用 `path.win32.relative()` 在本地**真实复现** CI 场景
（修复前 false → 误报；修复后 true → 正确排除），并注入故障实测该守卫会红。

测试：dpi 守卫 9/9；pnpm test:unit 291/291。
 2026-10-12 03:17:44 +08:00
jkooe 02887e265b fix(agent): 图形能力在高 DPI（200% 缩放）下坐标错位 
真机（Parallels 27 + Win11 ARM64，主机 200% 缩放、物理 3600×2020）暴露：
被控端 PowerShell 助手进程**默认 DPI 不感知**，同一进程里并存两套坐标系 ——

| 调用 | 不感知时 |
|---|---|
| Screen.Bounds / VirtualScreen | 逻辑 1800×1010 |
| CopyFromScreen | 按物理裁剪 → 缺省只截到屏幕左上 1/4 |
| SetCursorPos | 被系统 ×2 |
| UIA（screen.find） | 物理（与进程是否感知无关） |

净效果：screen.find 给出的物理矩形**不能**直接喂 input.mouse.*，必须人工除以 scale
（上一轮靠这个临时绕法才点中主题按钮 —— 能绕，但属用户侧的隐式约定，必须消灭）。

- 新增 apps/agent/src/util/dpi.ts：PS_DPI_AWARE（SetProcessDPIAware 前置段）。
- 注入全部坐标相关脚本：screen.ts / input.ts / window.ts（WIN_HELPER_PRELUDE，覆盖
  window.list 与 window.focus）/ record.ts；并把它从 win-ps/prelude-ocr.ts 的 try{} 里
  移出 —— 放在 try 内一旦抛错就被 catch 吞掉，助手会静默退回不感知。
- screen.ts 显式改用 $d.Bounds.Width（已是物理），scale 仅作参考。
- 新增守卫 tests/unit/dpi-awareness.test.mjs（8 项）：断言**实际下发的脚本文本**，
  而非「源码里出现过常量」—— 首版按源码扫描，注入故障实测不会变红；改为断言
  buildInputPsScript / buildListDisplaysScript / buildCaptureScript / WIN_HELPER_PRELUDE
  的脚本串后，二次注入故障精准变红。

真机终验（零换算）：
- screen.info 3600×2020，与裸 GetSystemMetrics 一致；
- input.mouse.move(x,y) 读回物理光标 == (x,y)（4 处抽样全中）；
- screen.find 物理矩形中心**直接** click → 主题单选 UIA selected 正确翻转且可逆。

文档：VM-VERIFICATION.md 新增 §10（坐标口径缺陷本体 / 复验配方 / 输入注入失效的逐条
排除与判决证据 / 两条 prlctl 通道的语义差异）；console-plan.md 补 ARM64 真机安装冒烟与
界面实点记录（含新发现 P2：控制台无单实例保护）。

⚠️ CHANGELOG 备注：本批**属被控端变更**，与上一节「本轮不升版本号」的结论不同 ——
发版必须升 PATCH（→ 2.0.3），否则 agent.mjs 会谎报一个并不包含本修复的版本。

测试：dpi 守卫 8/8；pnpm test:unit 290/290。
 2026-10-12 03:11:34 +08:00
jkooe 456e452b30 test(console): 补两条「静默失效」守卫 —— CSS 变量闭合 + 首帧底色一致 
主题改动引入了一类新的静默失效：**拼错的 CSS 变量名不报错**。
`var(--na-sunkenTypo)` 类型检查过、构建过、运行也不抛 —— 颜色只是落回继承值，
界面「看着对但就是不对」，与本项目历来吃亏的失效模式同源。故补守卫：

7. 扫 src/** 全部 var(--na-*) 使用点，与 cssVars() 的键集合比对
8. index.html 的首帧兜底色 ⇄ 调色板 bg

第 8 条是因为首帧防闪脚本是全应用**唯一允许的色值重复处**（其执行时点早于任何模块加载，
重复无法消除）；既然允许重复，就必须有东西盯着它，否则改调色板忘了同步
→ 深色用户每次启动闪一帧白。

注入故障实测两条都会红：
  var(--na-sunken) → var(--na-sunkenTypo)   第 7 条红
  var(--na-sunken) → var(--na-sunkenx)      第 7 条红
  index.html #f4f4f5 → #ffffff              第 8 条红
复原后 8/8 绿，文件逐字节还原。

第 7 条顺带暴露过一次**守卫自身漏报**：正则原写 [a-z0-9-]+，遇到 `sunkenTypo`
这种含大写的拼错会在 `T` 处停下导致整个模式不匹配 —— 写错的变量名反而逃过检查。
放宽到 [^)\s,;]+ 后才真正生效。
教训：**注入故障不只验证守卫有没有，还要验证它覆盖了目标形态**。

单测 280 → 282。
 2026-10-11 14:34:41 +08:00
jkooe 2eb6a6f8bb feat(console): 本机被控端托管 —— 启停/重启/日志/自更新/托盘/开机自启 
目标：双击应用即用，全程不碰命令行。

  要求                落点
  不再打开命令行窗口   agent.rs 的 CREATE_NO_WINDOW + 自启拉控制台而非裸 node
  启动/停止/重启       AgentManager 五态状态机 + 界面按钮 + 托盘菜单
  检查更新             check_update / download / apply_update
  日志功能             stdout/stderr 双泵 + 环形缓冲 + 实时推送 + 过滤/导出
  后台运行             托盘常驻，关窗最小化而非退出
  开机自启             macOS LaunchAgent / Windows 计划任务

新增「本机服务」页（/local，默认首页）与「服务日志」页（/logs）。
默认路由由 /nodes 改为 /local：打开应用先看到本机被控端的启停面板，
而不是先要求用户填一个连接地址。

四条实测踩出来的关键约束（均已在代码里注明原因）：

1. 退出监控用轮询 try_wait，绝不把 Child 交给 wait()
   —— wait() 会取得 Child 所有权，此后 stop() 再也拿不到它去 kill。
2. 日志游标用独立单调 seq，不用位置下标
   —— 环形缓冲淘汰旧行后位置下标会漂移，前端增量拉取静默错位（不报错）。
3. start() / restart() 的接收者必须是 self: &Arc<Self>
   —— 监控任务要持自持引用。
4. macOS gui/<uid> 的 uid 运行时 id -u 现取，不硬编码 501。

播种（seeding）防降级：只有「随包版本 > 已安装版本」才覆盖数据目录里的脚本，
且版本比较按数值逐段（2.0.10 > 2.0.9）。若写成「同版本才跳过」，
用户自更新过被控端后下次开控制台会被静默降回旧版。

「实例是否在跑」不靠单一信号：管理器状态与 TCP 端口探测交叉判定，
以区分「本控制台托管的实例」与「手工安装的非托管实例」并给出不同处置。

消灭黑窗有三条措施，第 2 条最易漏：Rust 的 std::process::Command 默认不设
CREATE_NO_WINDOW，于是「界面上点一下启动」= 屏幕上闪一个控制台窗口。

控制台现在随包分发被控端脚本（资源 2 份 → 3 份：sidecar.mjs / node / agent.mjs），
用户装完控制台本机被控端即已就绪。

新增 tests/unit/console-commands.test.mjs（6 用例）钉住三类「不报错的失效」：
invoke ⇄ generate_handler! 双向、emit ⇄ listen 双向（这类失效会让界面永不刷新且零报错）、
bundle 资源名 ⇄ Rust resolve_* 字面量、sidecar 方法名、路由表 ⇄ 实际 view 文件。
已注入故障实测会红（改命令名与事件名 → 当场 2 条失败），非空转守卫。

验证：cargo check 0 错 0 警 / cargo test --lib 10·10 通过（含真起 node 子进程）/
clippy -D warnings 通过 / vue-tsc 通过 / 单测 280·280（274 → 280）/
verify-bundle 真 spawn 打包内 node 跑通打包内 sidecar。

⚠️ 托盘、关窗最小化、开机自启、界面点按钮仍需图形环境人工实点。
 2026-10-11 11:41:56 +08:00
jkooe ab7a2b147b fix(v26): 自重启任务清理阈值改为「本 agent 启动时刻」（真机实测 1 小时粗阈值仍会累积） 
## 真机发现（Parallels Win11 ARM）
restart 两次后仍有 **2 个** selfrestart 任务（旧的 Ready 未被清）。诊断确认：
- 清理**条件**能选中它 ✓（非匹配问题）
- **手工删除**成功 ✓（非权限问题）
→ 算时间戳才明白：那是「1 小时」粗阈值的**必然结果** —— 旧任务创建于 00:44，
  第二次 restart 在 00:56（仅隔 12 分钟），清理那一刻它**仍是 Running**（cmd 还持有上一次的 agent），
  不满足「非 Running 或早于 1 小时」→ 保留。

**但规则本身是缺陷**：频繁 restart（间隔 < 1h）时旧任务照样累积 ——
v26 想治的僵尸只是从「永不清理」变成「1 小时后才清」。

## 改法（语义更精确）
```powershell
# 旧：$cut = (Get-Date).AddHours(-1)                    ← 粗略
# 新：$cut = (Get-Date).AddMilliseconds(-<agent uptime>) ← 「本 agent 的启动时刻」
```
凡在**我启动之前**就运行的任务，必然不是我的宿主（我的宿主刚刚才创建）→ 可安全删除。

## 验证（真机闭环）
1. `nodeagent deploy release/agent.mjs` → 指纹校验 + 备份 + 上传 + 重启 + 校验 ✓
   （顺带把 deploy 机制也验了）
2. `restart` → **任务只剩 1 个**（Running，当前宿主）→ **旧任务被精确清理** ✓✓
3. 单测：断言必须是「agent 启动时刻」阈值，且**禁止回退到 AddHours(-1)**；
   守卫 9/9 + 全量 274 绿；7 包构建通过
 2026-10-11 00:50:51 +08:00
jkooe c8aba83589 fix(control): control.ps1 的 $scheme: 被当 drive 引用 → 整个脚本不可用（真机踩到） 
## 现象（Parallels Win11 ARM 真机）
`control.ps1 -Action stop/start/status` 一律报：
  所在位置 control.ps1:100 字符: 36
  +  Write-Host "  协议     : $scheme://0.0.0.0:$Port"
  变量引用无效。':' 后面的变量名称字符无效。

## 根因
PowerShell 把 `$scheme:` 解析为 **drive 引用**（如 `env:`），而 `scheme` 不是 drive → 语法错误。
且这是**解析期**错误 → **整个脚本无法运行**（不是只有那一行），stop/start/status 三个子命令全废。
修法：写成 `${scheme}://`（用花括号界定变量名）。

## 改动
- `scripts/control.ps1:100`：`$scheme://` → `${scheme}://`，并加注释说明为什么必须用花括号
  （注释里刻意**不写**危险字面量 —— 否则会被新守卫命中，这点在验证时真踩到了）
- 新增守卫（`tests/unit/security-hardening.test.mjs`）：扫全部 `.ps1/.psm1`，
  禁止 `$ident:` 形式（白名单 `env`/`nuget`/`psitem`/`PSScriptRoot`）

## 验证
- 守卫 **9/9 绿**；全量单测 **274 绿**；ps1-encoding 保持通过（BOM 未被破坏）
- **注入故障实测**：把 `${scheme}` 回退成 `$scheme:` → 守卫**立即红**（失败数 1）→ 恢复后绿
  （按项目纪律：没验证过会红的守卫等于没有）
- 全仓重扫同类模式：**仅此 1 处**
 2026-10-11 00:05:42 +08:00
jkooe e23788d717 refactor(versioning): 统一版本号 —— semver 为唯一版本号，开发批次代号并入其归属版本 
## 问题（皇上指出）
项目里两套编号并行，无法判断哪个是"当前版本"：
- **发布版本**（semver）：v1.1.0 ~ v1.6.0、v2.0.0
- **开发批次代号**：v1 ~ v26（README 路线表 / 代码注释 / 文档）
时间线证据：v1.1.0 首发（09-29）时批次已推进到 v12.4 —— **二者从来不是一对一**（26 批次只发过 10 版）。

## 规则（新增 docs/VERSIONING.md §0 版本号唯一性规范）
- **唯一版本号 = semver `vX.Y.Z`**，两个来源必须永远一致：git tag 与 package.json（构建期注入 agent）
- **批次代号不是版本号**，不再单独出现；需要区分同版内多批改动时用**功能名**
- 附「批次 → 归属发布版本」映射表（按 tag 时间线与功能内容推定，并注明以 CHANGELOG 为准）

## 统一动作
1. **批次 v23 ~ v26 → v2.0.0**（22 文件 / 53 处）—— 它们确实属于 v2.0.0
2. **臣的批次号 v1.7 / v1.8 → v2.0.0**（27 文件）—— 未单独发版
3. **简写补全三段式**：v1.5 → v1.5.0、v1.6 → v1.6.0
4. **README 路线表**：`**v1**` → `**批次 1**`；表头加「批次 ≠ 版本号」说明并链到 §0；
   补齐批次 16~29 与 **v2.0.0 发布行**；删掉过时的「待办」行（提到的分支早已删除）
5. `docs/VERSIONING.md` 里**故意保留** 3 处批次号 —— 那是规范说明本身

## 保留项（真实发布版本，不动）
v1.1.0 / v1.2.1 / v1.3.0 / v1.4.0~v1.4.3 / v1.5.0 / v1.6.0 / v2.0.0（10 个 tag）

## 验证
- 版本号一致性：package.json = tag = 8 个 workspace = tauri.conf.json = **2.0.0** ✓
- v1.7/v1.8/v23~v26 全仓残留 **3 处**（均在 VERSIONING.md 规范说明中，属预期）
- 7 包构建 · 单测 273 · e2e 30 · ps1-encoding 24 全绿
 2026-10-10 14:27:12 +08:00
jkooe 865862ee7c refactor: 拆 mcp/index.ts（1139 → 530 行），工具清单独立成 tools/defs.ts 
## 拆法
`TOOLS` 数组（610 行，占原文件过半）抽到 `apps/mcp/src/tools/defs.ts` 并 export。

保留在 index.ts 的：
- 连接与调用辅助（ensureClient / call / forwardEventToHost）
- toArgs（入参特化）· TOOL_TO_CAPABILITY · resolveToolCall（分发 switch）
- MCP server 定义与 main

**分工**：defs.ts 只管「暴露什么」，index.ts 管「怎么转发」。

## 零漂移的证据
抽出的最大风险是**顺序漂移或漏搬** —— 两者都不会让构建失败，只会静默改变客户端
看到的工具表。故用「工具名序列 sha256」做证据：
  拆分前 41 个工具 / sha=69e8533c42c3…
  拆分后 41 个工具 / sha=69e8533c42c3…  ✅ 序列与顺序完全一致

## 新增回归守卫 tests/unit/mcp-tools.test.mjs（4 例）
- 工具数 41 且名称唯一
- **顺序未漂移**（序列 sha 比对；有意调整须同步更新基线并说明）
- 每个工具都有 name/description/inputSchema 三件套
- inputSchema 普遍声明 additionalProperties: false

## 验证
单测 269 → 273 全绿；e2e 30 全绿；7 包构建通过。
 2026-10-10 07:50:13 +08:00
jkooe 2cb0ed148e chore(privacy): 源码与测试里的真机常量脱敏（机器名 / 真机内网 IP） 
路线图 §七 序 7「源码真机常量注入化」的脱敏部分。

## 改了什么
- apps/agent/src/capabilities/network.ts：注释里的真机机器名 → 泛化为「机器名+纯数字」
  （保留"为什么不能拼 USERDOMAIN/USERNAME"这个教训本身，去掉具体机器名）
- scripts/rescue-network.ps1：.EXAMPLE 里的真机内网地址 → 文档示例段 192.168.1.100；
  网卡名示例由中文默认名改为 'Ethernet'（既避免像真机、又更通用）
- packages/protocol/src/acl.ts：注释里的真机 Mac 地址 → 192.168.1.100
- tests/unit×4：测试数据里的真机 IP 统一换成 192.168.1.x 示例段

## 过程中的两个教训（都记在代码注释里了）
1. **正则转义形态漏替换**：断言里写的是 `192\.168\.0\.88`（转义点），第一轮只替换了
   裸形态 `192.168.0.`，导致脚本值变了、断言没变 → 3 个测试红。
2. **机械替换会破坏「跨网段」这类语义测试**：acl 的 `/24 网段匹配` 用例里有一条
   本意是「**不同网段不匹配**」，替换后两侧变成同段 → 断言必红。已改回不同网段
   并在注释里标注原因，防止下次再被批量替换破坏。

## 验证
单测 269 全绿（复跑）；e2e 30 全绿。
 2026-10-10 00:39:28 +08:00
jkooe 32e0dd7bd5 fix(v26): 自重启任务清理加时间余量（治真机累积的 Running 僵尸） 
## 问题
重启任务的 cmd 会**一直持有新 agent 进程**，所以任务状态长期是 Running。
原清理逻辑只清「非 Running」的（怕误杀当前宿主）—— 代价是真机累积：
2026-10-09 实测 D:\\Nodeagent 上残留 3 个 nodeagent-selfrestart-* 任务（全 Ready/Running）。

## 修法（保守优先）
清理条件改为「**非 Running** 或 **LastRunTime 早于 1 小时**」：
- 1 小时余量远大于一次重启的耗时（正常 <1 分钟），所以"当前宿主"绝不会被误判 ——
  它刚刚才运行过，LastRunTime 就是几分钟前
- 清旧 Running 僵尸是安全的：它们的 cmd/node 早已退出，只剩注册表条目

用 includes 断言锁死这三条（AddHours(-1) / LastRunTime -lt $cut / Get-ScheduledTaskInfo），
并禁止回退到"只清非 Running"的老写法。

## 验证
单测 267 → **269** 全绿（新增 2 例源码断言）；e2e 30 全绿；7 包构建通过。
⚠️ **该项在 agent 内，且涉及进程清理 —— 必须真机验证后才算可交付**。
当前被控端整机离线（2026-10-10 00:15 ping 100% 丢包），故标注为待验证，未发版。
 2026-10-10 00:19:43 +08:00
jkooe bec07fc277 feat(v25): 审计链外部锚定 —— 链头可读 + 锚点落盘 + 锚点比对（方向三收尾） 
## 解决的问题
审计链的哈希只能发现**链内**篡改（改一条要重算其后全部）。但「有 root 的攻击者」
可以**整链重写**：从零重建一份自洽的假日志，verifyAudit 照样通过。
外部锚定是唯一能戳破它的手段：把链头记到**链外**（另一台机器/网盘），
攻击者改不了已经落到别处的历史记录。

## 两个新能力（能力数 49 → 51）
- system.audit.head（low）：返回 {entries, head_hash, head_ts, rotated_segments, file_bytes}；
  compare=true 时附带与最近锚点的比对结论
- system.audit.anchor（medium）：把链头**追加**写锚点文件（默认 <数据目录>/audit-anchors.jsonl，
  指定 path 时仍受 fs_roots 白名单约束）

## 一个关键设计点（最容易写错的地方）
锚点**不能只记 head_hash**：日志轮转会丢弃最旧段使条目数下降，只记哈希会把轮转误判成篡改。
故记四元组 {entries, head_hash, head_ts, rotated_segments}，比对时先按轮转对齐再判尾部。
三条判定：① 条目数减少且无轮转 → 疑似整链重写；② 条目数与段数都没变但哈希不同 → 该段被重写；
③ 条目数增长/轮转 → 锚点仍在链上，ok（附 detail 供人工核对）。

## 追加式而非覆盖式
锚点文件只追加：若可覆盖，攻击者重写链后再"刷新"锚点即可抹掉痕迹。

## 验证
- 单测 258 → **267**（新增 audit-anchor 9 例，含「整链重写」与「哈希不一致」两个关键检测、
  追加式不被覆盖、空链返回 null、无锚点时的提示语气）；e2e 30 全绿；7 包构建通过
- CLI：nodeagent audit head [--compare] / audit anchor [--note ...]
- ⚠️ 真机验证随后（需部署到被控端）
 2026-10-10 00:07:58 +08:00
jkooe 8b97fc6106 feat(v24): 零信任优先安装 —— 拿到控制端公钥就走 ed25519，否则明确告警 
## 为什么不是直接改 auth_mode 默认值
ed25519 的**私钥必须在控制端**，被控端安装时拿不到公钥。硬改默认值会让新装的控制端
连不上（还得手工改配置回退）—— 比「有条件就走零信任 + 无条件时明确告警」更糟。
所以这里的"默认"是**优先顺序**，不是死值。

## 做法
install.ps1 新增 -ClientAclFile（默认探测脚本同目录 client-acl.json，内容即
`nodeagent keygen` 打印的那一条 acl.clients JSON）：
- 有且含 client_id+pubkey → auth_mode=ed25519，写 acl{default_effect=deny, clients=[…]}，
  绿色确认 + 打印 --auth-mode ed25519 连接示例
- 无 / 缺字段 → 保持 psk，但输出**醒目黄色告警**：说明 client_id 可自报的固有风险
  + 三步切换指引（keygen → 存 client-acl.json → 重跑 install.cmd）
install.cmd 无需改动（install.ps1 自行探测）。

## 验证（真机，不是推理）
- **PowerShell 5.1 语法校验**：PARSE_OK，BOM 保留（EF BB BF）
- **等效逻辑三 CASE**：
  A 有文件 → auth_mode=ed25519 + default_effect=deny + clients 完整（allow/deny/note 保留）
  B 无文件 → auth_mode=psk 且**不写 acl 字段**
  C 缺 pubkey → WARN 并回退 psk（不写半截 ACL）
- 编码守卫：ps1-encoding 24 例全过（BOM + 无 U+FFFD）
- 新增 tests/unit/install-zerotrust.test.mjs（8 例源码断言：参数、探测路径、
  useZeroTrust 条件化、deny 兜底、字段校验、告警文案、连接示例、ConvertTo-Json -Depth 6）

## 文档
docs/SECURITY.md 新增 §4.7 并更新 §5 清单 —— 把 v23 的三项（握手封禁/会话上限/
安装期密钥）与本次 ed25519 默认化一并标为已完成，只留「审计链外部锚定」待做。

## 数据
单测 250 → **258** 全绿；7 包构建通过。
 2026-10-09 23:53:28 +08:00
jkooe 982eb9b1fa fix(v1.8): 真机验证抓到的两个 where 相关真 bug（macOS 上永远测不出） 
皇上问"能不能连上 Windows 真机"，连上后顺带做积压的真机验证，当场暴露两处：

## ① screen.find 的 where-only 被自己的入口校验拦下
v1.7 声称"control 条件可只用 where 不传 text"，但只改了 gui.await 侧，
screen.find 入口仍要求 text 非空 → 直连与 await 的 where-only 全部报
"text 不能为空"。修：text 与 where 至少给一个；macOS 侧明确说明
"无 UIA 等价物，where 不可用，请给 text"（而非笼统的参数错误）。

## ② where 的 PowerShell 注入语法错误（更关键）
原实现直接把 JSON 字面量注入 PS：$where = {"enabled":true}
—— PowerShell 不认这种语法（哈希表要 @{enabled=$true}），ParseError 让
**整份助手脚本**失败。真机现象：带 where 的调用一律"窗口操作失败"，
不带 where 的完全正常。
修：改为 JSON 字符串 + ConvertFrom-Json 摊平成哈希表（Test-UiaWhere 依赖 .Keys，
PSCustomObject 没有 Keys）。

## ③ 补上此前"只在注释里承诺"的 note
manifest 写明"OCR/image 引擎忽略 where 并带回 note"，代码里没实现。
现补 note + where_applied 字段（UIA 时 true，降级时 false 并说明）。
不补的话，调用方会以为"按属性过滤过了"而误判结果。

## 真机已确认可用的部分（无需修复）
- UIA 属性读取 ✓：QQ音乐精简窗的 Text 控件读到 enabled=true，
  value/selected/toggle 均为 null —— **"拿不到就留 null、绝不猜"的设计在真实
  第三方应用上验证成立**（Qt/Electron 类控件给不出这些属性）。
- monitor/log 能力已在被控端就绪（v1.8 构建已部署）：monitor.list 返回 ok。

## 验证
单测 250 全绿（新增 where-only 放行断言）；e2e 30 全绿；7 包构建通过。
⚠️ 两个修复都只在 Windows UIA 路径生效，**必须部署到被控端才能真机复验**。
 2026-10-09 23:24:40 +08:00
jkooe 7c6a68268b feat(v1.8): 状态采样 —— log.query 被控端侧过滤 + monitor 定时采样落盘与回看（方向二） 
## 背景：复盘 §四 那条判断仍成立
代理不通、杀软拦截、端口时开时闭都是**间歇性**的，而 system.status 只能看当下快照；
event.watch 解决「有事件时通知」，没解决「**持续记录并回看**」。

> 顺带纠正路线图一处过时判断："fs.watch 未做" 不成立 —— event.watch 的 kind=file
> 就是 fs.watch 实现（递归 + glob + 推送/拉取双出口）。本轮不重复造。

## ① log.query（新增能力，低危只读）
在被控端侧过滤，只回匹配行 —— 日志常几万行，整份拉回既慢又占带宽。
- 流式逐行读（readline），扫到 limit 即停，不全量载入
- pattern（正则）/ level（含 WARNING→WARN 归一）/ since（按行首时间戳）/ offset / limit / tail
- 单行 >4KB 截断后再匹配；单次扫描上限 200 万行防失控
- 路径复用 fs.guardPath —— **不新开安全面**（fs_roots 非空即受限）

## ② monitor.*（四项新能力，低危）
start / report / stop / list / delete。四类采样源：
- port（TCP 连通性 + 延迟）/ process（存活 + PID）/ command（退出码 + 首行）/ metric（CPU·内存）
- 样本落 <数据目录>/monitors/<id>.jsonl（一行一针），**摘要直接给结论**：
  「断了几次 + 最长连续中断样本数」「CPU/内存 min·avg·max」「成功失败数与退出码集合」
- 并发上限 8；单文件 10 万行封顶轮转；timer.unref() 不阻止 agent 退出

## 真机验证（本地，15 例全过）
port 采样造一次真实断线（关端口 1.6s 再开）→ report 给出 up=9/down=4/最长中断 4 针/延迟 avg 1.31ms；
metric 给 CPU 16.9% 内存 50.24%；落盘 13 样本可回看；stop 后 report 仍可查；
log.query 按级别/pattern+tail 过滤准确；fs_roots 白名单外的 /etc/hosts 被拒；
非法 source/target/id 字符/重复 id/不存在 id 均被拒。

## 修复一个真 bug（测试抓到）
parseLeadingTs 的正则把 ISO 的  时区标记吃掉了 —— UTC 时间被当本地时间解析，
**整体偏 8 小时**。跨时区日志判断"何时断的"会错。已保留 Z/±hh:mm 后缀。

## CLI / MCP
- nodeagent monitor start|report|stop|list|delete ...；nodeagent log --path ... --level ERROR
- MCP：na_monitor（action 分发）+ na_log

## 数据
能力数 43 → **49**；单测 231 → **247** 全绿；e2e 30 全绿；7 包构建通过。
 2026-10-09 23:08:03 +08:00
jkooe 8c41414e04 feat(v1.7): 语义属性化 —— screen.find 读 UIA 属性 + where 过滤，gui.await 支持属性条件与 any_of 组合 
## 背景（路线图方向一第二步：从「能找到」到「可断言」）
原链路是「点 → 截图 → 目测 → 再点」。gui.await 解决了「等得到出现/消失」，
但等不到「**等它变成某状态**」—— 按钮出现了却还是灰的，点了没反应。
根因是 screen.find 只回坐标，不回控件状态。

## ① screen.find 返回 UIA 属性（v1.7）
在原有 name/control_type/automation_id/坐标 之外补四个只读属性：
- enabled（是否可用）、value（ValuePattern 当前值）、selected（SelectionItemPattern）、
  toggle（TogglePattern 的 On/Off）
- 每项单独 try/catch：**拿不到就留 null**，绝不猜 —— Electron/游戏 UI 常给不出值，
  由上层判「未知」而非「false」

## ② where 属性谓词（仅 UIA 生效）
{"enabled":true} 只回可用控件；{"value":"*已完成*"} 按值模糊匹配。
- 白名单四键（enabled/selected/value/toggle），其余键直接报错
- OCR / 图像模板引擎忽略该参数并**带回 note**，避免调用方误以为按属性过滤过了

## ③ gui.await 的属性条件与 any_of 组合
- control 条件可只用 where 不传 text ——「等一个 enabled 的按钮」比「等一个叫某名字的按钮」
  更贴近真实意图；但两者全无仍报错
- any_of: [ {...}, {...} ] 任一命中即算，命中时回报具体是哪个子条件（hit 字段）
  例：[{window:安装完成},{control:错误}] =「装成功或报错，先出现的算」
- 设计取舍：**不做通用布尔表达式**。「弹窗出现且其中按钮 enabled」用
  any_of(弹窗) + where(按钮 enabled) 两步即可表达；通用 and/or/not 会把 schema
  与求值都复杂化，收益不成比例。确需两个都成立时上层连调两次更直白。

## ④ CLI / MCP 同步
- CLI：nodeagent await ... --where '{"enabled":true}' --any_of '[{...}]'（JSON 字符串，非法 JSON 即报错）
- MCP：na_await 透传 where/any_of，schema 同步

## 验证
- 单测 **227 → 231**（新增 4 例：where/any_of 过 schema、where 白名单、
  screen.find 的 where 类型校验、any_of 的 OR 语义）；e2e **30** 全绿
- **本地真机 6 场景全过**：any_of 命中并回报子条件 / absent 等到全消失 /
  where 在报错环境正常超时 / 非法 where 键被拒 / any_of 项缺 condition 被拒 / 空数组被拒
- ⚠️ 待 Windows 真机：UIA 属性的真实读取（enabled 随播放状态变化）与 where 过滤；
  macOS 侧走 OCR，where 自动忽略并带 note（已按此设计）
 2026-10-08 01:04:50 +08:00
jkooe 921ff89edf feat(v23): 连接层三项防护 + 安装期密钥改 stdin（堵住最后一条密钥暴露面） 
## ① 安装期密钥不再走命令行（路线图方向三，最后一条暴露面）
此前 install.cmd 用 -Key 传参，**同机其他用户可从 Win32_Process.CommandLine
明文读到**。现改为管道喂 stdin：
- install.ps1 新增 -KeyFromStdin：先判 [Console]::IsInputRedirected 再读
  （没管道时不阻塞）、Trim 去 CRLF、hex 16-128 校验；优先级 -Key > stdin > 复用既有 > 新生成
- install.cmd：echo %PSK%| powershell ... -KeyFromStdin（管道符前不留空格，
  否则空格会被 echo 进密钥 —— 老坑）

## ② 握手失败封禁（此前只计数，攻击者可无限重试）
- 同来源连续失败达 max_attempts（默认 5）→ 拉黑 ban_ms × 2^(N-max)，指数退避封顶 24h；
  封禁期过计数保留，继续翻倍
- 5 个失败路径统一记账（挑战过期/nonce 不匹配/未注册/Ed25519 失败/PSK 失败）；
  **认证成功即清零**（不误伤手滑的控制端）
- 白名单来源永不封禁；归一化剥离 ::ffff: 前缀（否则同来源被当两个键）
- 在连接入口挡（TLS 之后、业务握手之前），错误响应带 retry_after_ms
- 封禁状态放 core（handleAuth 在内），AgentCore 暴露 banRemainingMs/states

## ③ 连接上限 + 空闲断开
- max_connections 默认 8（超限 close 1013）；idle_timeout_ms 默认 30 分钟
- 空闲清扫**保守**：只要还有任务在跑或还有事件订阅就不断 —— 不把挂着长任务
  等结果的控制端踢下线（新增 runningTaskCount / watchCount 两个判据）
- states 由 WeakMap 改 Map（需要 size 与遍历），close 时手动 delete 防泄漏
- 新增审计类型 session.idle_close（console 的 AuditType 同步，契约测试守住）

## 验证
- 单测 **227 全绿**（新增 security-hardening 6 例：退避公式翻倍/封顶、IP 归一化、
  白名单、hex 校验、配置形状）；e2e **30** 全绿
- **本地真机三场景**：正确密钥可连 → 连续错误被拒 → 封禁期连正确密钥也被拒 ✓
- ⚠️ 待 Windows 真机：install.cmd 双击首装（改了安装入口，必须验管道喂钥）
 2026-10-07 21:23:37 +08:00
jkooe 277c5f1ba5 feat(v1.6.1): gui.await 补齐单测与 CLI/MCP 入口；源码注释脱敏；gitignore 补密钥规则 
## ① gui.await 补齐（路线图 §1 收尾清单第 2、3 项）
此前该能力只有实现、**单测 0 覆盖、CLI/MCP 0 入口**：
- 新增 tests/unit/gui-await.test.mjs（6 例）：能力登记与风险等级、四类条件 ×
  两态 schema、timeout 上限兜底、isHit 对五种返回形态的判定契约、
  CLI/MCP 入口存在性
- CLI：`nodeagent await --condition <window|control|process|file> [--text/--title/
  --process/--path] [--state absent] [--timeout ms]`，回显 satisfied/耗时/轮询次数/末次异常
- MCP：新增 na_await 工具（定义 + 分发），描述含典型编排示例

## ② 源码注释脱敏（路线图序 0.5 / §4.0）
input.ts 与 input-script.ts 里 4 处真实播放器名 / 游戏名泛化为
「主流媒体播放器」「全屏独占应用」「部分播放器会创建数十个辅助窗口」——
不再画像「哪台机器装了什么、常在什么场景下远程控它」。grep 复核零残留。

## ③ .gitignore 补密钥规则（路线图 §6.2）
此前只挡 PSK.txt，挡不住 keys/（ed25519 私钥）与 *.key / *.pem（TLS 私钥）
—— 一旦误 add 就是私钥入公开库。*.pub 显式放行。

## 验证
单测 215 → **221**（+6 全绿）；e2e **30** 全绿；7 包构建通过；
CLI await 实测到连接层（被控端当前离线，超时属预期）。
 2026-10-07 20:31:36 +08:00
jkooe dac8a0a2a7 feat(console): 入库 Tauri 2 桌面控制台（主控/被控一体） 
apps/console —— 跨端（macOS/Windows）桌面控制台，复用 ops 侧的 Node agent 作本地被控端，
不做第二套 agent。技术栈：Tauri 2（Rust 壳 + 系统 WebView，包体小）+
Vue 3 + TS + Vite + Pinia + Naive UI（暗色）+ Vue Router(hash)。

- command 层（src-tauri/src/lib.rs）：connect / disconnect / invoke_capability /
  get_capabilities / get_state；client 事件经 Emitter 桥接为 na-log / na-state / na-event 推前端。
  握手后**先 await 成功再落 state**（不持锁 await）。
- 7 页面：设备管理 / 状态总览 / 终端 / 进程与服务 / 软件 / 文件 / 审计。
- 实测：macOS .app 6.75 MiB（方案指标 <30MB；Electron 同级约 100MB+），
  直接执行二进制进程存活、无崩溃 —— `codesign --verify --deep --strict` 那条
  "code has no resources but signature indicates they must be present" 是 adhoc
  链接签名的固有噪声，实测无害（勿被误导去「修签名」）。

⚠️ 本轮用 examples/probe.rs 对真实被控端核对字段契约，抓出 9 处**静默空列**
（不报错、类型系统也抓不到，界面只显示 "-"），全部按契约修掉：
- 进程表读 r.cpu / r.memory → 真源 cpu_pct / memory_bytes（CPU、内存两列恒为 "-"）
- 服务表读 r.status → 真源 state
- 磁盘读 d.mount||d.name / d.used → 真源只有 drive + total/free，
  **没有 used**（须自算 total-free）
- 网卡读 {name,rx_bytes,tx_bytes} → 真源 {adapter,ip,up}
- 软件表读 a.id → app.list 结果**没有 id**，应为 publisher
- 审计 broken_at 当数字渲染 → 真源是 {file,line,reason} 对象
另清掉幻影字段 SystemInfo.node（契约里只有 node_path）。

配套两点设计：
- **平台门控**：连接后探测 system.info.os → isWindows/platformReady；app.* 与
  system.service.list 仅 Windows 被控端可用，故软件页与服务 Tab **事前禁用并说明原因**，
  而不是发出注定失败的请求再解释错误。
- **结构化错误**：协议真源 InvokeResult.error 只有 {name,message,data?}（**没有 code**），
  故分支一律按 name；前端 CapabilityFailure 暴露 errorName，并提供
  isUnsupportedPlatform / isAclDenied / isRateLimited。未改协议（改动会扩散 4 端）。

tests/unit/console-contract.test.mjs（20 例）：把「前端声明 ⊆ 契约」与「契约 ⊆ 前端声明」
双向钉死，另校验平台门控清单与 agent 侧 requireWindows 集合一致、AuditType 覆盖
apps/agent/src/audit.ts 全部取值。**已注入漂移实测会红**（把 cpu_pct 改回 cpu →
正/反向各挂 1 项），非空转守卫。
 2026-10-07 10:14:12 +08:00
jkooe 25f889c6d8 fix(test): ps1-encoding 守卫改用 fileURLToPath（Windows 上 URL.pathname 会多一根前导斜杠） 
**这是 Windows CI 一上线就抓到的真 bug** —— 新加的 CI 单测步骤当场回本。

根因：测试用 new URL('../../', import.meta.url).pathname 取仓库根。macOS 上得到
/Users/... 可用；Windows 上得到 /D:/a/nodeagent/...（盘符前多一根斜杠），
readdirSync 直接 ENOENT → 整个文件 22 个用例全灭。
本地（macOS）永远测不出来，只有 Windows runner 会炸。

修法：改用 fileURLToPath(new URL(...)) —— Node 官方的跨平台转换。
全仓已无同类残留。本地 195 单测 / 29 e2e 复跑全绿。
 2026-10-07 02:00:10 +08:00
jkooe 2eb33587fe feat(v1.6): 新增 gui.await 等待条件能力（复盘短板之「语义」） 
把 GUI 操作从「按一下→睡几秒→截图碰运气」变成**可断言**：四类条件
window / control / process / file，各复用 window.list / screen.find /
process.list / fs.stat（零新平台代码，平台行为与既有能力一致，只读低危）。
- present/absent 两种等待；超时正确返回 satisfied:false + note
- 轮询期单次异常**不视为失败**（启动中程序常短暂报错），超时才带回 last_error
- 参数非法分两层拒：schema 层（协议错误）与业务层（E_PARAM_INVALID）

本地真实验证（macOS，7 项全过）：present 命中（1208ms/7 次轮询）、absent 命中、
超时返回、非法参数 2+1 拒绝、process 命中、底层报错不中断轮询（last_error 带回
辅助功能权限提示）、缺省参数可用。

能力数 42 → 43（数量守卫测试同步更新）；README 补快捷键与 gui.await 用法章节。
 2026-10-07 01:21:41 +08:00
jkooe 689bb8c98d feat(v1.5): 快捷键控制范围扩展 —— 字符串热键 / 预设别名 / 长按 / 后台定向投递 
## 背景
原 `input.key.press` 只接受数组和弦（keys/sequence），按键表也不全：
AI/MCP 调用要拼 ["ctrl","shift","esc"]，且 **win+d、ctrl++、win+. 这类
"修饰键 + OEM 符号键"的组合根本打不出来**（表里没有符号键）。

## 四类扩展
① **字符串热键**：`hotkey: "ctrl+shift+esc"`、`hotkeys: ["ctrl+c","ctrl+v"]`
   —— 分隔符支持 `+ - 空格`，大小写不敏感，别名归一（command/cmd→win、del→delete…）
② **预设别名**：约 50 个语义名（copy / show_desktop / task_manager / screenshot /
   volume_mute_toggle…），AI 调用免记键位；`preset` 与 `presets`（序列）均支持
③ **长按** `hold_ms`（≤5s）：按下→保持→释放，插在"按完"与"释放"之间
④ **后台定向投递** `route=post` + `target_pid`：向目标进程**全部顶层窗口**
   PostMessage WM_KEYDOWN/UP —— 目标窗口被遮挡/最小化时可用
   （媒体键的 WM_APPCOMMAND 机制早已验证，此为其等价物）
   文档明示局限：游戏/部分输入型程序不响应后台键消息

## 按键表补齐（单测覆盖断言防漂移）
- 左右侧修饰键 lctrl/rctrl/lshift/rshift/lalt/ralt/lwin/rwin（游戏常区分左右）
- 小键盘 numpad0-9 + 四则运算，**与数字键分开**（Excel 靠 NumLock 区分）
- OEM 符号键 oem_1..oem_8 / oem_minus/plus/comma/period（解锁 win+d、ctrl++、win+.）
- 浏览器收藏夹/主页、系统键（sleep/help/select/execute/clear/separator/oem_clear）
- IME 键（kana/hangul/kanji/hanja/convert/nonconvert/accept/modechange）
- 补齐 pause/apps（重构时一度漏掉，被覆盖断言测试立刻抓到）

## 可测性重构
脚本生成抽成**纯函数** `apps/agent/src/capabilities/input-script.ts`
（VK_MAP / MEDIA_COMMANDS / toVk / build{Media,Foreground,Post}Body），
行内生成逻辑全部改为调用 —— 于是**按下顺序/逆序释放/hold 插入位置/post 路由**
这些最容易写错的部分，现在由 14 个单测逐行断言，真机只需验证最终效果。

## 参数校验
protocol `expandChords()` 统一展开六种输入形式，**混用即报错**（消除"以谁为准"歧义）；
同一和弦重复修饰键、超 4 键、空输入均拒绝。渲染返回值新增 presets/via/channel/sent_windows。

## CLI / MCP
- CLI：`nodeagent key press "ctrl+shift+esc"` / `key press copy` / 老形式 `key press ctrl c`
  新增 `--hold`、`--route`；回显预设展开与后台投递命中窗口数
- MCP `na_key`：同步支持 hotkey/hotkeys/preset/presets/hold_ms/route/target_pid

## 验证
- 单测 **179 → 195**：hotkeys 解析与别名 17 例、**脚本生成逐行断言 14 例**、
  按键覆盖断言（HOTKEY_KEYS ⊆ VK_MAP）、新参数 schema 校验 2 例
- e2e **29** 全绿
- ⚠️ **真机未验证**：Windows 被控端当前离线（连接超时）。待上线后需验：
  `key press "win+d"`（切桌面再切回）、`key press copy` 配剪贴板、
  `route=post` 定向一个最小化窗口。验证通过后再发版。
 2026-10-07 00:59:40 +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 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 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 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 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 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 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 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 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 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 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 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