mtfyun/nodeagent
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
229 Commits 1 Branch 14 Tags
c062d1cc8b4f1b6302892eec9ac142e674e6e96f
Commit Graph
58 Commits
Author SHA1 Message Date
jkooe b6e58dbcc4 docs(changelog): v2.1.0 定稿 + 修正历史改写后的悬空 hash 引用 
- `## [未发布]` 中已发布的 v2.1.0 段改为 `## [2.1.0] - 2026-10-26`；
  新开 [未发布] 记录发版脚本修复与依赖漏洞清零两条。
- 历史改写（脱敏）后旧提交 hash 不再可达，文档里的引用会变成死链：
  CHANGELOG `efe4744` → `a75c5c9`；ROADMAP `efe4744`/`b09ca68`/`e864486`/`d106214`
  → `a75c5c9`/`5a2c5f9`/`68ea3cd`/`560b3c4`。全仓已无旧 hash 残留。
 2026-10-27 00:27:17 +08:00
jkooe 2d5be044ee chore(privacy): 交付流水线文档去掉其他项目名 
`docs/DELIVERY-PIPELINE.md:10` 原以三个真实项目名举例说明「原方案面向 Web/容器
服务」，属审计基线的树内 PII 之一（存量，非本批次引入）。公开仓库不宜暴露项目
组合，改为中性表述「同类多项目实践」，论证语义不变。

注：该处 PII 已存在于既有历史 blob（2026-10-17 起），彻底清除需重写整段历史，
属独立决策，不在本批次范围。
 2026-10-26 21:11:43 +08:00
jkooe a7827ba986 docs: 增量 PRD / ARCH 与设计图入库（v2.1.0 全面完善） 
本轮「全面完善」的四份设计产出此前后在 git 外（untracked）——
阶段 3 实现所依据的需求/架构/类图/时序图随收口一并入库，
使「代码 ← 设计」的引用链在仓库内闭环（代码注释已按 ARCH 任务号引用）。
 2026-10-26 01:01:32 +08:00
jkooe 0074d09f08 docs: v2.1.0 收口回填（README/CHANGELOG/DEVELOPMENT/ROADMAP + 数字守卫） 
- README：数字刷新为实测（52 能力 · 42 MCP · 467 单测 · 50 e2e · 23 Rust）；
  补 na_audit_l2 工具表项、看门狗三端接入段；删「控制台安装包只作为
  CI artifact」过期行（9f95560 起已随 Release 发布）。
- CHANGELOG：[未发布] 定稿 v2.1.0 全部主题（rollback / 看门狗 /
  na-gui 清理 / e2e 与文档收口），与 A 线已回填段共存无重复。
- DEVELOPMENT：新增 §7.5 selfupdate 代理出网机制（NA_PROXY→环境变量→
  系统代理、PAC/socks5 明确报错、回环恒直连、计划任务环境变量告诫）；
  §7.4 补 rollback/看门狗双通道分工表与「为什么运行期不做自动回滚」
  三问引述。
- ROADMAP：新增第十节 —— v2.1.0 已落地项划掉、P2 登记（控制台自更新
  v2.2.0 / Linux auditd / macOS ESF / macOS 安装器 / guard 日志轮换）。
- tests/unit/docs-numbers.test.mjs（新，6 例）：README 五个数字与可
  复现实测口径钉死（manifest 条目 / defs.ts 工具 / node --test 实测 /
  e2e 源码 / Rust 属性），「增能力不改 README」即红。单测数实测经
  NODE_TEST_CONTEXT 剥离 + NA_DOCS_NUMBERS_CHILD 递归防护；注入故障
  （52→53）实测 2 处守卫变红、恢复全绿。
 2026-10-26 01:01:19 +08:00
jkooe aad137f04a fix(startup-guard): 强制向被看守进程注入 NODEAGENT_HOME = --data-dir 
全局一致性审查发现：Windows 计划任务的 New-ScheduledTaskAction 无法
携带环境变量，若安装进程持有进程级 NODEAGENT_HOME，agent 运行时的
agentDir()（LKG/状态文件所在地）会与守卫的 --data-dir 漂移 ——
守卫读不到 LKG/状态文件（安全退化为 no-lkg 放行，但看门狗白养）。

由 spawnEnv 在 spawn 时把 data-dir 显式注入被看守进程，三端行为与
supervisor 环境解耦且一致（Linux unit / macOS plist 的
EnvironmentVariables 本就是同值，双保险，幂等无害）。
新增 spawnEnv 单测；真机验证子进程可见注入值。
 2026-10-26 00:17:15 +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 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 590f62e968 docs(changelog): 回填「检查更新」修复的真机复验与守卫口径 
CHANGELOG 与 docs/console-plan.md 的该节写于「15 用例 / 248KB」时点（随后被隐私脱敏
提交一并带走），已落后于代码，且当时「经代理成功」那一组受宿主线路拥塞未取到。
本次回填三处：

- 用例数 15 → **16**，补第 15 条守卫（错误映射：连接被中途重置不得报成「请求超时」）
  及其注入验证行。
- 补记**第三个缺陷**：ECONNRESET 被误归 abort 类 → 真机耗时 82.9s 却报「请求超时
  （120000ms 内未完成）」，把「对端掐断连接」这条最有价值的信息抹掉。
- 产物 248KB → **249KB**；真机复验表补 D/E 两组（Win11 ARM64 VM，用随包 node.exe 直跑
  dist/sidecar.mjs，两侧 sha256 一致）：
  · D 对照（不配系统代理、不给任何环境变量）→ 30877ms 失败，但报真实原因 socket hang up，
    data 带 via=直连 / timeout_ms / 可操作提示；
  · E 实验（只设 WinINET 系统代理、仍不给任何环境变量）→ **成功 28883ms**，
    via_proxy=system、日志「（来源 system）」、退出码 0。
  实验组走通的正是本次新增的系统代理发现；其 28.9s 耗时同时反证旧 20s 内部超时必然失败。
  复验后 VM 的 ProxyEnable/ProxyServer 已原样还原。

无代码改动。
 2026-10-13 22:47:36 +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 00992e5c1c feat(linux): Linux 被控端适配 —— 安装器 + systemd 自启 + 平台守卫 + 部署文档 
面向「服务器型被控端」（命令/状态/文件/审计；无 GUI），实测环境 Debian 12（fnOS 底座）。

## 新增
- `scripts/install-linux.sh`：一键安装器（对齐 Windows `install.ps1` 的语义）
  · 自动获取 Node 运行时（系统无 Node 22+ 时下载 linux-<arch>，走 npmmirror）
  · **systemd 服务**（系统级 / 用户级+linger / `--no-service` 三种模式），开机自启
  · 幂等：复用既有密钥（并自动备份 agent.json）；卸载保留配置（`--purge` 才删）
  · `--node-id/--port/--allow-input` 等参数；缺 `ip`/`ifconfig` 时 IP 展示多级回退
- `apps/agent/src/util/platform.ts`：**统一平台守卫**
  · `assertPlatform(cap, ...allowed)` / `assertGuiPlatform` / `assertWindows`
  · 抛 `E_UNSUPPORTED_PLATFORM` 并带上「支持哪些平台」，让"未实现"不再伪装成"参数错/环境缺依赖"
- `docs/DEPLOY-LINUX.md`：部署指南 + **实测能力清单** + 故障排查表

## 修改
- `screen.ts` / `record.ts` / `clipboard.ts` / `audio.ts` / `input.ts`：入口接入平台守卫。
  修复前的表现是**误导性错误**（`screen.capture` 在 Linux 上报 `region 宽高必须 ≥ 1`，
  像是参数没传对），现在是 `screen.capture 未在 Linux 上实现（仅支持 Windows / macOS）`。
- `scripts/verify.mjs`：v2.1 / v2.3 补 `E_UNSUPPORTED_PLATFORM → skip`
  （v2.2 早已处理；此前把"平台不支持"记成失败）
- `README.md`：文档区链入 DEPLOY-LINUX

## 实测（Docker · Debian 12）
- 安装流程端到端：装文件 → 写配置(600) → 提取密钥 → 启动监听 → **幂等复装密钥不变** ✓
- 验收：**9 通过 / 1 失败 / 6 跳过**（对比 macOS 15/0/1）
  · 1 失败 = 容器缺 `procps`（`process.list` 返回空），非代码问题；NAS 自带该包
  · 6 跳过 = GUI 类能力（平台诚实拒绝）
- 单元测试 325 全绿；7 包构建通过

## 途中修正的三个"差点误判"
1. **Alpine 误判**：`spawn /bin/bash ENOENT` 是**镜像没 bash**，不是 Linux 不支持
2. **`set -e` 静默退出**：`LAN_IP=$(ip ...)` 在无 `ip` 的环境失败会**直接终止脚本**
   （`2>/dev/null` 把原因吞了，表现为"跑到一半就没了"）→ 已改多级回退
3. **slim 镜像缺 procps** → `process.list` 空列表，被误读为"Linux 特性"
 2026-10-13 21:15:59 +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 c20e71bddc docs: 补齐 Windows 端控制台文档（含三次 run 的失败-修复-实证全过程） 
README / CHANGELOG / docs/console-plan.md 三处同步：

- README：补 Windows 双架构安装包实测体积、第三条断言（解开安装包查内容）、
  以及实测解出的 node.exe 体积与 PE Machine。
- CHANGELOG：新增「Windows 端控制台安装包」整节，含双架构理由、
  为什么用原生 ARM runner、cfg!(windows) 分支首次被编译器看到、
  以及三次 run 的完整过程（体积断言写错 → `&` 调 GUI 程序不等待 → 双绿）。
- docs/console-plan.md：断言表 2 条 → 3 条；新增三节实测记录；
  产物形态表补实测体积；8.2 指标验收的「Win 安装包 < 40MB（待实测）」补上实测值。

另修复：`## 界面观感约定（2026-10-11）` 标题被上一轮编辑误吞
（正文直接从「两轮纯界面调整」开始），已恢复。

留下两条可迁移教训：
1. 体积阈值属于「中间逻辑自洽」式断言 —— 判据要落在产物内容上；
   且压缩容器与未压缩目录的体积不可直接比。
2. `msiexec.exe` / NSIS 安装包是 GUI 子系统程序，PowerShell `&` 调用
   既不等待也不设 $LASTEXITCODE → 必须 Start-Process -Wait -PassThru。
 2026-10-12 00:20:50 +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 4e6eb32929 style(console): 配色收敛为「简约白 / 高级灰」两套中性灰阶主题 
原配色是深色 + 品牌青绿（#63e2b7）+ naive-ui 默认绿主色 —— 颜色种类多。
改为两套**只用中性灰阶**的主题，侧栏底部一行切换，选择存 localStorage：

  简约白  页底 #f4f4f5 ／ 侧栏 #fafafa ／ 卡片 #ffffff
  高级灰  页底 #1d1f22 ／ 侧栏 #181a1d ／ 卡片 #24262a

几处刻意的选择：

1. 白主题页底**不是纯白**。卡片本身是白的，两者同色就只能靠 1px 分线撑层次，
   整页发「糊」；压一档浅灰后层次为「页底 < 侧栏 < 卡片」，且仍是白为主。
2. 主色位（naive-ui 的 primary）改**中性灰** —— 主按钮、开关激活态、进度条、
   勾选框全吃这一个值。原来它们是绿色/青绿，正是「配色不简单」的主因。
3. 语义色（成功/警告/错误/信息）**降饱和而非去掉**。这是运维工具，
   「运行中 / 出错」必须一眼可辨，全部灰化会导致误读。故它们只出现在徽章与
   告警这类**小面积**上，底色观感仍是「白 + 灰」。
4. **色值只定义一份**：src/theme/index.ts 的 Palette 既生成 naive-ui 的
   themeOverrides，又由 App.vue 运行期注入成 --na-* CSS 变量。
   若「TS 调色板」与「CSS 写死色值」各存一份，换主题时会**一半新一半旧、
   不报错、类型也抓不到** —— 正是本轮要消灭的失效模式。
   为此清掉散在 8 个文件里的 17 处写死色值（日志三流着色、代码块底色、
   节点选中边框、历史悬停…），复扫后自定义样式里硬编码色为 0。
5. 主题**只存 localStorage**，不落 Rust 侧 settings：那套 Settings 是给
   「仅服务模式」（无窗口、常驻托盘）也生效的偏好用的；主题是纯图形偏好，
   没有窗口时毫无意义 —— 为一件纯前端的事去动 Rust 命令面与契约守卫不划算。
6. index.html 内联一小段脚本做**首帧防闪**（否则深色用户每次启动闪一帧白）。
   此处**刻意重复 2 个底色值**，已在 index.html 与 theme/index.ts 两处注明
   「改底色时同步」—— 因为在它执行之前没有任何模块可依赖；
   除此之外全应用再无第二份色值。

验证：vue-tsc 0 错 ｜ 契约守卫 6/6 ｜ 单测 280/280 ｜ .app 重打通过（92.22 MiB）｜
两套主题均以真实采集数据回填渲染核对 —— 截图脚本顺带读回 --na-bg 与 body 背景，
确认主题真的切过去了，而不是「看起来像」。
 2026-10-11 14:29:50 +08:00
jkooe 2528f6b709 docs: 归档「控制台去命令行化」—— CHANGELOG / console-plan / README 
CHANGELOG：新增 [未发布] 章节，并按「刻意不升版本号」写明理由 ——
本轮新增的全是控制台功能，被控端能力集合未变；而 bundle-agent.mjs 会把根
package.json 的 version 注入 agent.mjs（__AGENT_VERSION__），
一旦为控制台功能升号，被控端就会谎报一个它并未包含的版本。故维持 2.0.2。

console-plan：新增「本机服务托管」章节，含需求逐条落点对照表、
消灭命令行窗口的三条措施、四条实测踩出来的约束、播种防降级的规则、
「不靠单一信号判实例在跑」的交叉判定、以及仍需图形环境人工实点的清单。

README：控制台页面表 7 → 9（补「本机服务」与「服务日志」），
打包命令改为 pnpm --filter nodeagent-console bundle，
体积数字修正 —— 原文写的 .app ≈ 6.8 MiB 是 Node sidecar 方案之前的旧数，
现为 .app 90.8 MiB / .dmg 33.78 MiB，并补「无需预装 Node」「自启与图形能力
要求登录用户会话」两条注意事项。
 2026-10-11 11:42:27 +08:00
jkooe 1ab9ed22c7 docs(vm): 图形能力实测归档 + §9 复验配方 
- §7 图形能力行：⏳ 待登录态 → ✅ **登录态下全通**（真实桌面截图 1800×1010 / window.list /
  screen / audit verify），并注明「会话 0 的失败是身份问题，非产品缺陷」
- 修正重复的 §7 编号（→ §8），复位一处错位的表格行
- §6 补三条排查项：x64 Node 的 Prism 现象、`screen.capture` 的会话身份、
  **微软账户不支持传统 autologon**（MSA 凭据走 CloudAP，`LogonUser` 恒返回 1326）
- 新增 §9「图形能力复验配方」：本地账户 autologon → 计划任务 Interactive 启动 →
  三件核对 → 证书指纹变更的处置 → 验证完的安全清理
 2026-10-11 10:32:48 +08:00
jkooe 87b74fd015 docs(vm): B5 按实测改写 —— arm64 包原生可用 / win-x64 包 TLS 握手不通 
原 B5 的假设是「x64 包在 ARM 上也许能跑」，本轮实测证伪：能启动、能 listen，
但 TLS 握手不完成（E_TIMEOUT），被控端实际不可用。补对照数据与复验步骤；
同步更新检测表、前置准备（③④ 改用 arm64 包）、结论标注规则与新增 §7 实测记录。
 2026-10-11 09:48:10 +08:00
jkooe a6be917637 docs: 记录控制台 Node 运行时分发与体积口径调整 
- console-plan.md：
  · §8.2 打包体积指标口径由「Mac .app < 30MB」改为「**分发件** Mac .dmg < 40MB」
    —— 原数字是 Tauri + Rust client 时代定的（当时应用内不含 JS 运行时）；
    改 sidecar 方案后应用必须自带 Node 运行时，.app 因此到 90.8MB，但用户下载的 dmg 仅 33.8MB。
    已明确标注「口径调整，待确认」。附本机 Electron 运行时本体 207MB 的实测对照。
  · 新增「Node 运行时分发」节：做法、三处实测约束（编译期契约 / strip 须重签 / 映射须对齐
    resolve_node）、验证方式（verify-bundle 真跑产物）、实测体积。
  · 「已知待办」由两条收敛为一条（剩 GUI 端到端人工验证，需图形环境）。
- CHANGELOG.md：新增 [未发布] 节，记录运行时分发功能与两处规避（SIGKILL 137、编译期契约）。
 2026-10-11 08:55:45 +08:00
jkooe 40b7db16c1 docs(roadmap): §五/§九 的 7 处历史「未做」标注实际状态（避免误导为待办） 
这些行是当时的计划快照，内容其实都已实现（screen.find 属性化、条件组合、方向二/三、ed25519 默认化
以及 v1.5 真机验证）。不改写历史结论，只更新事实以免读者误判为未完成。
 2026-10-11 07:53:10 +08:00
jkooe 765ad08ee6 docs(roadmap): §九 台账 —— v1.5/v26 真机验证标记完成（VM Win11 ARM） 2026-10-11 01:13:36 +08:00
jkooe fbcb8f8408 fix(v23): 连接保活补 pong 检测（治僵尸连接占名额）+ B2 三防护真机验证通过 
## 真机发现（Parallels Win11 ARM，B2 验证过程中撞到）
心跳只发 `ping()` 而**不检查 pong**，且 ws 库默认不会因「ping 无 pong」断开 ——
客户端进程已死（TCP 未发 FIN）时，连接会一直挂在 `states` 里占 `max_connections` 名额。
叠加「有任务/订阅时清扫保守跳过」的既有策略 → `states.size` 虚高 → **把正常控制端挡在外面**
（本次实测就把自己锁在外面了）。

## 改法
- `attachConnection` 里加 `ws.on('pong')`：**客户端回应也算活跃**（更新 lastActiveAt）
- 心跳里：若某连接静默超过 `idle_timeout_ms * 2` → `ws.terminate()`（标准 ws 保活）
  → 僵尸连接不会再永久占位

## B2 三场景真机验证（全部通过）
- ① **握手封禁**：配 `max_attempts=3` → 3 次错误密钥被拒后，**正确密钥也被拒** ✓
- ② **连接上限**：配 `max_connections=6` → 第 1~6 个成功、**第 7 个被拒** ✓
- ③ **空闲断开**：配 `idle_timeout_ms=20000` → 静默 **40 秒**被断开 ✓
  （符合 20s 阈值 + 30s 清扫周期）
- 新增 `scripts/verify-b2.mjs`（三模式：idle / maxconn / ban），全部走**真实连接**

## 验证过程中另修的两个自测问题（都记进文档）
1. 脚本默认 URL 写成了 `ws://` —— 被控端 `tls:true`，**必须 wss**（否则 socket hang up）
2. 测 `max_connections` 时值太小会**把自己锁在外面**；且被拒连接会被计入握手失败形成恶性循环
   → 结论：测试要留余量，并给自己配 `auth_ban.whitelist`

## 收尾
测试用的 `security` 段已用**备份恢复**（`agent.json.before-b2`）；pong 修复已 `deploy` 到 VM
（指纹 abca2b8168f0）。
 2026-10-11 01:13:12 +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 047cc9efd2 docs(vm): 补 ARM64 包的解决方案（pack.mjs --arch arm64） 2026-10-11 00:32:54 +08:00
jkooe 54f7f4c7ab test(vm): Parallels Win11 ARM 真机验证 —— A 组 15/0 + v1.5 四项全过 + 锚点端到端通过 
## 环境
Parallels 27 + Win11 ARM，VM 10.211.55.9（共享网络）；被控端 `-NodeId win-arm -AllowInput`。

## ⭐ B5 结论（与预期不同，但更有价值）
| 组合 | 结果 |
|---|---|
| `win-x64` 包（内含 x64 Node） | ⚠️ **能启动、能 listen 8765，但 TLS 握手 60s 不完成** → 协议层不可用（Prism 下） |
| **换 ARM64 Node（同版本 v22.20.0）** | ✅ **完全正常**：握手成功、连接、51 项能力 |

× 结论：`nodeagent-win-x64.zip` 不能在 ARM Windows 上实用；ARM 上需 ARM64 Node。

## 验证结果
- **A 组（verify.mjs 17 项）**：✅ 15 通过 / 0 失败 / 1 跳过（29.5s）
- **B1 v1.5 四项**：✅ 全过 —— 字符串热键 / 预设别名（`copy→ctrl+c` 映射正确）/ 长按 /
  后台定向投递（**explorer 命中 138 窗口**、WindowsTerminal 10 窗口）
  → **v1.5.0「未经真机就发版」的债，至此还清**
- **B4 锚点端到端**：✅ collect(62 条) → 上传云盘 → verify 判定「链已增长」+ 精确明细
- B2/B3：⏸ 阻塞（需 restart，而计划任务启动失败 —— 手工跑却完全正常）

## 本轮真机抓到的 2 个真 bug（都已修）
1. `control.ps1:100` 的 `$scheme:` 被 PowerShell 当 drive 引用 → **解析期错误 → 整个脚本不可用**
   （stop/start/status 全废）；已修 + 加守卫（扫全部 .ps1 的 `$ident:`）
2. `anchor-audit.mjs` 调用**不存在的** `audit head` 子命令 → 改为 `invoke system.audit.head`
   （这种「能力存在但 CLI 无子命令」的错配，不真跑一次发现不了）

## 文档
`docs/VM-VERIFICATION.md` 补「实际验证结果」节 + 5 条新增排查项（安装/密钥/CLI 语法/计划任务）
 2026-10-11 00:18:43 +08:00
jkooe 3b05f5b373 fix(docs): VM 标注插错位置 —— 移到 §九 台账的正确条目之后 
上一提交的锚点匹配过宽（匹配到版本台账表里的「ci: 补全 Windows 真机验证」行），
导致标注插在了错误位置。现改为精确锚点「清理策略**真机验证**」，并复核只出现一次。
 2026-10-10 23:39:48 +08:00
jkooe 7eb773099f docs(roadmap): 补上「VM 可补验证」标注（上一提交因文本未匹配而未生效） 2026-10-10 23:38:17 +08:00
jkooe ba57d99806 docs: 新增 VM 验证清单（Parallels 27 + Win11 ARM）—— 真机不可用时的替代路径 
## 背景
Windows 被控端离线导致 4 项验证卡住（v1.5 四项 / v23 三防护 / v26 清理 / 锚点端到端）。
Parallels Desktop 27 可跑 **Windows 11 ARM** 虚拟机（Apple silicon 只支持 ARM 版 Windows，
x86_64 仅 Pro/Business 的早期预览），可提前跑掉**架构无关**的验证项。

## 清单内容（docs/VM-VERIFICATION.md）
- **能补 / 不能补的矩阵**：协议层与输入层可验；**杀软交互、显示/DPI、性能指标不可替代**
- 前置准备：桥接网络（否则 UDP 广播发现测不了）、优先 ARM64 Node、run-portable/install 二选一
- **逐条命令**（均已对着源码核实参数）：
  - A 基础验收：直接复用既有 `scripts/verify.mjs`（17 项 + Markdown 报告）
  - B1 v1.5 四项：`key press "ctrl+shift+esc"` / `copy` / `--hold 800` / `--route post --pid N`
    （对应 args 的 hotkey / preset / hold_ms / route+target_pid 四个分支）
  - B2 v23 三防护：`agent.json` 的 `security.auth_ban` 与 `idle_timeout_ms` + 三场景判定
  - B3 v26 清理：`restart` 后 `schtasks /query`，**重点看"当前宿主任务必须仍在"**（否则即误杀）
  - B4 锚点端到端：`anchor-audit.mjs collect` → 云盘 → `verify`
  - B5 额外结论：**win-x64 包在 ARM Windows 上能否跑**（走 Prism；跑通则写进 README）
- **结论标注规则（强制）**：VM 验过的写「VM 已验」；杀软/显示/性能**不得**因 VM 通过就标已验；
  并注明「VM 与真机架构不同（真机 x86_64），VM 通过不自动推出真机通过」
- **已知 VM 环境差异表**（排查先看）：广播发现需桥接、坐标为逻辑验证、性能数字不可采信等

README 文档区与 ROADMAP §九 均已链入。
 2026-10-10 23:38:02 +08:00
jkooe 28ce95f045 feat(audit): 审计锚点外部化落地 —— 判定逻辑收敛为 protocol 纯函数 + 控制端工具 + 云盘链路 
## 为什么（一句话）
锚点的安全性完全来自「它在攻击者碰不到的地方」。与被审计日志同机的锚点等于没锚：
被控端一旦被 root，重写日志后顺手改掉锚点即可。

## 本次改动

### ① 判定逻辑收敛（消除「两份真相」）
把 `compareWithAnchors` 的三条判定抽到 **`packages/protocol/src/audit-anchor.ts`** 的
**纯函数 `judgeAnchors(head, anchors)`**（无 IO，不知路径）：
- agent 端 `compareWithAnchors` 改为「读文件 + 调 judgeAnchors」
- 控制端脚本同样调用它
→ 同一份日志不可能出现「被控端说一致、控制端说被改」的分歧
- 附带 `parseAnchorsFromJsonl`（坏行跳过，一行坏数据不毁整份锚点）
- agent 侧类型改为 re-export，既有导入路径不变（**9 个原有锚点单测全绿，行为零变化**）

### ② 控制端工具 `scripts/anchor-audit.mjs`
- `collect`：拉链头 → 生成一行锚点 JSONL（并打印 `ANCHOR_JSON=` 便于 automation 取用）
- `verify`：读锚点文件（可从云盘下载）+ 拉链头 → 判定，`ok:false` 时**退出码 2** + 醒目告警
- 走 CLI 而非自己实现连接（复用其多设备配置/证书钉住/daemon，避免又一份实现）
- 支持 `--head-file`：**离线也能验证判定链路**（本轮即用它做了 fixture 验证）

### ③ 云盘链路
- 建 `…/Project/NodeAgent/anchors/`（与全量备份分开目录）
- 每日 automation 更新为「拉链头 → 上传云盘（一天一个带日期的文件）→ 简报」，
  并规定每月首日额外做一次「下载历史锚点 → 链外比对」

## 验证
- **纯函数重构零行为变化**：原有 audit-anchor 单测 9/9 全绿；全仓 273 单测全绿；7 包构建
- **工具离线验证**（fixture）：一致 → 「与锚点完全一致」退出码 0；
  篡改 → 「链头哈希与锚点不一致」退出码 2；三个错误分支均给出明确提示
- 云盘：`anchors/` 目录创建成功（1/1 步），目录内容已复核
- ⚠️ 端到端（真拉链头 + 真上传）**待被控端上线**；脚本的 CLI 分支已做错误处理验证
 2026-10-10 19:14:09 +08:00
jkooe 9bba53d5c0 fix(ci): 修 Rust Shell 工作流 —— resources 只声明构建期必产出的文件 
CI 失败根因（本地已复现确认）：`tauri-build`(build.rs) 会在**编译期校验**
`tauri.conf.json` 的 `bundle.resources` 声明文件是否存在。
我之前声明了两项：`sidecar.mjs`（CI 未生成）+ `resources/node`（Node 运行时未下载）
→ build.rs 直接失败（"failed to run custom build command"）。

修复：
- `tauri.conf.json` 的 resources **只留 sidecar.mjs**，并写明为何不能声明未就绪的文件
- `rust.yml` 在 clippy/test **之前**加「构建 sidecar」步骤（`pnpm --filter nodeagent-console sidecar:build`）
- console-plan.md：⑤ 不再把 node 记为已完成（未验证的不写成做完），
  补「已知待办」（Node 运行时随包分发 + GUI 端到端人工验证）与「构建约束」说明

本地复现验证：删掉 `sidecar/dist/` → `cargo check` 复现同一错误；恢复 → 通过 ✓
 2026-10-10 15:25:12 +08:00
jkooe 53bf5a0634 feat(console)!: Rust 壳改用 Node sidecar（选项 D 完成）—— 退役 crates/nodeagent-client 
## 动机（消除「两套协议实现」）
原设计让 Rust 壳自己实现 client，与 TS 版（@nodeagent/client）并存 → 改一处漏一处时
构建过、单测过，只在真机暴露。现 Rust 壳只做**进程管理 + 消息转发**，协议实现只剩 TS 一份。

## ④ Rust 壳改造
- 新增 `src-tauri/src/sidecar.rs`（~290 行）：Sidecar 管理器 —— spawn node、
  行分隔 JSON-RPC 的请求/响应匹配（oneshot + 超时兜底）、通知回调（state/log/agent_event）、
  `resolve_node`/`resolve_sidecar` 路径解析（env → Tauri resource → 开发期系统 node）
- 重写 `lib.rs` 为薄转发层：`ensure_sidecar` 懒启动；**5 个 command 签名与 3 个 event 名
  （na-state/na-log/na-event）一律不变 → 前端零改动**；`get_capabilities`/`get_state`
  读本地缓存以**保持同步签名**；`RunEvent::Exit` 时优雅 shutdown（kill_on_drop 兜底不留孤儿）
- `Cargo.toml`：移除 nodeagent-client 依赖、加 tokio；**版本 0.1.0 → 2.0.0**
  （原先与 tauri.conf.json 的 2.0.0 不一致，属版本号统一范围）

## ⑤ 打包配置
- `tauri.conf.json`：`bundle.resources` 声明 sidecar.mjs 与 node；
  `beforeBuildCommand` 串上 `sidecar:build`（否则 resource 缺失）

## ⑥ 退役
- 删除整个 `crates/`（12 文件，含 nodeagent-client 与其 probe 示例）
- `rust.yml` 由「Rust client 单测」改为「**Rust 壳单测（真跑 sidecar）**」：
  装 Tauri 系统依赖 + Node + pnpm，跑 clippy `-D warnings` 与 `cargo test`
- `package.json`：`test:rust` 改指 console 壳；移除 `probe`
  （其「对真机逐项核对字段」的用途已由 CLI `nodeagent invoke` 覆盖）
- 引用清理：README（数字与协议客户端说明）、console 前端两处注释、
  console-plan（开头加「原方案已被取代」提示 + 补改造详情）、ROADMAP 历史描述加退役批注

## 验证
- **`cargo test` 3/3 通过**（真跑 Node sidecar 子进程：spawn/请求-响应/错误不崩）——
  这是关键：sidecar 管理器**不依赖 Tauri GUI**，故核心逻辑可在 CI 真实验证，不必等人工开窗口
- `cargo check` 零警告；clippy 标准与 CI 一致
- 273 单测 / 7 包构建 全绿
- ⚠️ **仍需人工验证**：Tauri GUI 端到端（开窗口 → 连被控端 → 点界面），沙箱跑不了图形应用
 2026-10-10 15:16:24 +08:00
jkooe 096193a8ec feat(console): 采纳 sidecar 方案（选项 D 第一步）—— Node sidecar 实现 + 8/8 真机 e2e 
## 为什么
原设计让 Rust 壳自己实现一份 client（crates/nodeagent-client），代价是**两套协议实现静默漂移**
（改一处漏一处时构建/单测都不报错，只在真机暴露）。sidecar 让 Rust 壳退化为
「进程管理 + 消息转发」，协议实现只剩 TS 一份，从根上消除漂移。

## 本次交付
1. `apps/console/sidecar/main.mjs`（190 行）：把 `@nodeagent/client` 暴露成
   **JSON-RPC 2.0 over stdio**（行分隔）。方法 connect/disconnect/invoke/state；
   onStateChange/onLog/onEvent 三个回调 → `event` 通知（kind=state/log/agent_event）
2. `apps/console/sidecar/build.mjs`：esbuild **JS API** 打成单文件（避开 pnpm `.bin` 的
   ENOENT 坑），并注入 `createRequire` shim —— 否则 `ws` 的动态 require 会报
   "Dynamic require of events is not supported"
3. `apps/console/package.json`：加 `@nodeagent/client`/`protocol` 依赖 + sidecar:dev/build 脚本
4. `docs/console-plan.md`：补「实施决策」节（决策理由、协议定义、进度表、打包方向）

## 两条协议纪律（写进注释与文档）
- **stdout 只写协议消息**，日志一律 stderr（混入非 JSON 行会让 Rust 侧解析失败）
- 任何异常都转成响应，**绝不因单个请求崩进程**

## 错误形态归一（实测中修正）
被控端对未知能力/ACL 拒绝/超时是回 JSON-RPC error → `client.invoke()` 抛异常。
若原样上抛前端要处理两种形态，故归一为 `{status:'failed',error:{name,message,data?}}`；
而「未连接/缺参数」仍走协议错误（语义不同）。

## 验证（真实链路，非 mock）
本地 agent → sidecar **8/8 全绿**：connect 回传 51 项能力与 agent_version ✓ ·
invoke system.info ✓ · state 反映已连接 ✓ · 事件通知已推送 ✓ ·
非法能力返回 failed 且不崩 ✓ · disconnect ✓ · **stdout 无日志污染** ✓
打包产物拷到仓库外**独立运行通过**（227KB 单文件自足）。

## 待办（下一批）
Rust 壳改造（command 签名不变 → 前端零改动）· tauri.conf.json 的 resource 配置 +
Node 运行时打包 · 退役 crates/nodeagent-client
 2026-10-10 15:11:39 +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 5b69d6cec9 refactor: 项目结构与命名规范化（重写前的最后一次常规提交） 
## 改名
`scripts/run-temp.cmd` → `scripts/run-portable.cmd`
理由：它是**正式功能**（免安装、免管理员的便携启动方案），"temp" 易被误认成临时文件。
程序内文案同步：TEMPORARY launcher → PORTABLE launcher；
打包产物 README 的"【临时试用，不装也行】" → "【免安装试用，不装也行】"。

## 移动
`PRD.md` → `docs/PRD.md`
理由：文档统一放 docs/（README/CHANGELOG 按惯例留在根）。

## 同步的引用（共 11 处）
- scripts/pack.mjs：产物文件名校验 + 生成 README 的 3 处指引文案
- scripts/run-portable.cmd：自身用法注释 6 处
- README.md：目录树 + 文档链接
- docs/DEVELOPMENT.md：配套文档链接（`../PRD.md` → `PRD.md`，现已同目录）+ 目录树

## 验证
- 全仓 `run-temp` 残留 **0**；`./PRD.md`/`../PRD.md` 旧路径残留 **0**
- 7 包构建通过；单测 273 全绿；ps1-encoding 24 全绿
- `pack.mjs` 实跑通过，`run-portable.cmd` 已正确进入 Windows 产物
- `.cmd` 保持 ASCII + CRLF（94 行）；PRD.md 无内部相对链接需调整
 2026-10-10 13:39:42 +08:00
jkooe 11127b1a89 chore(privacy): 杀软实名与网卡名示例泛化（安全报告第十三轮 P2 两项） 
## 甲1 杀软实名泛化（6 行）
`主流杀软 / 杀软 / 360` → 「主流杀毒软件 / 杀软」：
- docs/REMOTE-LIMITS.md：标题 + 正文 + 表格两处（保留"会拦什么"的实操信息，去掉具体厂牌）
- scripts/release.mjs:278：Release 正文模板里的信任区提示
- apps/cli/src/cmd/ops.ts:398：部署失败排查提示

## 甲2 网卡名示例泛化（13 行）
「Ethernet」→ `Ethernet`（示例）／泛化为"中文网卡名"（讲原理时）：
- docs/REMOTE-LIMITS.md 网络适配器表格、ROADMAP 该项标记为已完成
- scripts/rescue-network.ps1 参数说明、automation.ts 的 interface 描述
- apps/agent/src/capabilities/network.ts 注释：改为"脚本里的非 ASCII 字符（如中文网卡名）"
  —— **保留"为什么"的教训，去掉具体实况**
- tests/unit/net-scripts.test.mjs：8 处测试数据与正则断言同步改为 Ethernet

## 验证
工作区残留「主流杀软/杀软/Ethernet」= **0 处**；单测 273 全绿；7 包构建通过。
 2026-10-10 12:26:41 +08:00
jkooe d9e2103be7 docs(roadmap): 同步 v2.0.0 已发布状态 
- 头部基线：v2.0.0（2026-10-10 / a515eb2），单测 273，能力 51，CI 双工作流全绿
- §九 台账补「发版 v2.0.0」行 + 「v1.5 四项与 v26 清理策略真机验证仍待补」的显式标记
 2026-10-10 12:18:28 +08:00
jkooe 2e6356c7f4 docs: REMOTE-LIMITS 的「观测窗口时点性」缓解措施已落地（monitor/log/audit） 
该文原写「可让被控端持续采样并落盘……具备实现基础」—— 现已实现：
- monitor.* 定时采样落盘 + 摘要回看（断几次 / 最长断多久 / 值域）
- log.query 在被控端侧过滤日志（不必整份拉回）
- system.audit.anchor 定期锚定链头（防整链重写）

同时补一句仍未解决的：应用层内部状态（当前在等哪个请求）依旧只能从日志反推 ——
monitor 采的是外部可观测量，读不到进程内部语义。
 2026-10-10 07:38:46 +08:00
jkooe 74d878a1c5 docs: DEVELOPMENT 能力表补全至 51 项；RETROSPECTIVE 加「短板已全部解决」批注 
DEVELOPMENT.md：能力表此前停在 19 项（v5 时期）—— 补齐 20~51（32 行），
按功能分组并标注引入批次与风险图例；表末声明「权威定义以 manifest 为准，能力数由单测守卫」。

RETROSPECTIVE.md：保留 2026-09-28 的原判断（历史价值），
在末尾追加「短板已全部解决」对照表（自持/语义/状态/安全残余 → 各自解决于哪个版本），
并补一条本轮验证出的经验：真机验证不可替代（8 个 bug 只有真机能暴露）。
 2026-10-10 00:35:43 +08:00
jkooe dfd3b2349e docs: README/ROADMAP 同步至 v26（能力 51 / MCP 41 / 单测 269 / Rust 9） 
README：
- 能力总览补三行（GUI 等待 / 状态采样 / 审计锚定）
- 数字行 43→51 项能力、38→41 个 MCP 工具、215→269 单测、11→9 Rust 单测（实测）
- gui.await 章节补「属性谓词与组合」（where 四属性表 + any_of 示例 + 引擎限制说明）
- 新增两章：状态采样（log.query + monitor）、审计链外部锚定

ROADMAP：
- 头部基线刷新（269 单测 / 51 能力 / 未发版提示）
- §九 台账补 10-09~10-10 的语义 / 状态 / 安全三方向收尾（含 SECURITY §5 清单全部完成）
- 新增「真机验证抓到的 8 个真 bug」表，便于后续复盘
 2026-10-10 00:29:39 +08:00
jkooe 68546e63e8 docs+fix(v25): 审计锚定的语义说明（锚定自身也写审计 → 紧随比对应显示「已增长」）+ SECURITY §4.8 
真机验证时发现一个语义瑕疵：刚锚定就比对，永远显示链已增长 ——
原因是锚定调用自身也被 server 层记入审计（统一记录所有 invoke）。
功能正确（不误报篡改），但反直觉，故：
- compareWithAnchors 的 verdict 补上解释
- manifest 的 audit.anchor 描述补上说明
- SECURITY.md 新增 §4.8（含两个关键设计：四元组锚点防轮转误判、追加式防刷新抹痕），
  §5「还没做的」清单至此**全部完成**
 2026-10-10 00:12:02 +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 9665edf35b docs(roadmap): 据实刷新（v1.6.0 已发 + CI 全绿 + 6 个 Windows bug 已修 + 新增铁律） 2026-10-07 20:33:03 +08:00
jkooe e7da258d17 docs: 入库控制台方案与路线图 
- docs/console-plan.md：大前端方案（选型取舍、7 页面/7 store、command 表、事件名、
  验收标准 A1-A7、指标、里程碑 M1-M4）。§9.1 记录了 M3 的契约探针对账结果 ——
  9 处静默空列的漂移明细、平台门控设计、以及三段契约闭环的构成。
- docs/ROADMAP.md：能力路线图（含在建项与经验条目）。

两份文档此前因「在建工程」策略暂不入库，随本轮正式入库一并转正。
 2026-10-07 10:14:51 +08:00
jkooe 5571cf1aea chore: 取消跟踪误提交的在建工程（保持工作区文件不动） 
上一个提交（v1.6）用了 git add -A，把工作区里**不属于本任务的用户在建文件**
一起带入并推送：crates/（Rust 客户端脚手架）、docs/console-plan.md、
docs/ROADMAP.md，以及 docs/RETROSPECTIVE.md 的本地改动。

本提交将它们移出 git 跟踪（磁盘文件全部保留、回到未跟踪状态），
使公开仓库只包含 v1.6 的预期变更。如需从历史中彻底抹去，
可另行 filter-repo 重写（公开仓库，需皇上决策）。
 2026-10-07 01:22:58 +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 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 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 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 3f91e1ddc0 docs: 新增《实战复盘：短板与改进优先级》 
基于真机部署 + v2rayN 故障排查 + 重装前采集的真实使用，梳理短板：

P0（决定能不能用）
1. GUI 语义能力缺失 —— 有截屏有鼠标，但没有「界面元素 -> 坐标」的映射，
   切个节点反复点错三次，最后靠键盘导航才成功。建议引入 UIA。
2. 编码不统一 —— 三个真实事故均源于此：Set-Content 写 BOM 致 agent 起不来、
   PowerShell 管道损坏中文致清单报废、控制台 GBK 误判。
3. 自断生路 —— 重启 agent 时分离进程被自身进程树清理一起杀掉，导致失联。
   建议提供受控重启（system.agent.restart）+ 看门狗自愈 + 配置回滚。
4. exec 输出未结构化 —— 尾部附加 [退出码/耗时] 文本，污染 JSON 解析。

P1：长任务异步化、定时采样、剪贴板、窗口管理、CLI 常驻 daemon
P2：事件订阅、文件监控、录屏、拖拽/宏、多设备并行、DPAPI

一句话：能看能算能跑命令已扎实，短板在「语义」（读不懂界面）、
「状态」（只看当下）与「自持」（改不动自己）。
 2026-09-28 22:01:15 +08:00