mtfyun/nodeagent
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
225 Commits 1 Branch 14 Tags
eebfb45f7337e8a2883642fbb234dd1ae168ec69
Commit Graph
25 Commits
Author SHA1 Message Date
jkooe 1a2d1c7825 fix(ci): 补挂安装包断言改为按架构校验 —— 修「每次必红」的漂移守卫 
v2.1.0 的 Console Release 在 publish job 红：
`安装包数量不足（3 < 4），架构可能缺失`。

根因是**守卫与实现漂移**，不是产物缺失：build 矩阵是
x64 → msi+nsis（2 个）、arm64 → 仅 nsis（1 个，WiX 的 arm64 MSI 支持面窄，
刻意不出），合计恒为 3；而断言写死「两架构各一套（exe+msi）＝ 4 个」，
于是从 arm64 去掉 msi 那天起就**每次都红** —— 红门禁等于没有门禁。

改为按架构断言（x64 ≥2 / arm64 ≥1），缺失时精确报出是哪一架构；
矩阵再变也只需改一行期望值。

附带修一个只在 CI 爆的坑：`$dir）`（变量紧贴全角括号）在 set -u 下被 bash
当成变量名的一部分 → unbound variable，本地肉眼完全正常。变量引用统一改
${var} 形式，并用抽取工作流原文的方式在本地跑通正例/反例两个分支。
 2026-10-27 00:36:09 +08:00
jkooe 3680218010 fix(ci): typecheck 前改为全量构建 —— 只建 protocol 不够 
## 上一版没修透
先只加 `pnpm --filter @nodeagent/protocol build`，CI 换了个错法：
`apps/cli` 报 `Cannot find module '@nodeagent/client'`。

依赖链是 **`protocol → client → cli / mcp / agent`**，逐层都要 dist/*.d.ts。
逐个补依赖是打地鼠，下次加包还会漏 —> 直接用 `pnpm -r build` 把整条链建出来。

## 顺带修掉一个顺序矛盾
原工作流是 `typecheck` 在前、`pnpm -r build` 在后，而后者注释写着
「单测 import 的是 dist/，必须先构建」。既然后面无论如何都要 build，
不如提前一次到位 —— 现在 build 在 typecheck 之前，只保留一份。

**注入验证（模拟 CI 全新检出）**：把 `packages/*/dist`、`apps/*/dist` 全部移走 →
`pnpm -r build` → `pnpm typecheck` **零错误**；`pnpm test:unit` **357 项全绿**。
 2026-10-17 23:24:36 +08:00
jkooe 141f479e4a fix(ci): 让质量门禁真正生效 —— 修两处「一直红所以等于没有」，并清零高危漏洞 
## 发现
今天 8 次质量门禁运行**全部失败**（从今天第一个 commit 起就没绿过）。
一道长期红的门禁等于没有门禁 —— 没人会看它，也就保护不了任何东西。
两处独立原因：

### ① SCA：audit 打到了镜像
仓库 `.npmrc` 指向 `registry.npmmirror.com`（加速用），但**镜像不实现 audit 接口**，
`pnpm audit` 必报 `ERR_PNPM_AUDIT_ENDPOINT_NOT_EXISTS`。
→ 显式加 `--registry=https://registry.npmjs.org`。

### ② typecheck：缺 build 顺序
各包 import 的是 `@nodeagent/protocol` 的**类型产物**（dist/*.d.ts）。
CI 全新检出没有 dist，直接 typecheck 集体报
`TS2307: Cannot find module '@nodeagent/protocol'` —— 而本地因为 dist 还在，看不出来
（典型「本地绿 / CI 红」）。
→ 在 typecheck 前插入 `pnpm --filter @nodeagent/protocol build`（只建这一个包，够用且快）。

**注入验证**：把 `packages/protocol/dist` 移走 → 复现 TS2307 → 执行新增的 build 步骤 →
typecheck 零错误。（先证明诊断对，再证明修复有效。）

## audit 通了以后暴露 2 个 high（之前被「假绿」掩盖）
1. **node-forge <=1.4.0**（路径 `apps/agent > selfsigned > node-forge`）
   上游**无修复版本**（patched_versions: None）→ 只能移除依赖。
   `selfsigned` 5.x 已整体改用 `@peculiar/x509` + pkijs，node-forge 被彻底删掉。
   - 升级带来两处不兼容：`generate` 改为**异步**、`days` 改为 `notAfterDate`
   - `ensureCert()` 随之改 async（唯一调用点在 async 的 `main()` 里）
2. **@modelcontextprotocol/sdk <1.31.0**（OAuth 凭据可能被发往 MCP 服务器指定的授权服务器）
   → 升到 `^1.32.1`

## 证书不能只看编译通过（权威本上一条真机教训）
用临时数据目录起真被控端实测：
- 证书 `notBefore=2026-10-17 / notAfter=2036-10-14`（10 年，换算正确）
- key.pem 权限仍为 600
- 客户端握手成功：**52 项能力**，验收 **13 通过 / 0 失败**
- 审计：`No known vulnerabilities found`

验证：`pnpm typecheck` 通过；`pnpm test:unit` **357 项全绿**；
`pnpm install --frozen-lockfile` 通过（lock 与 manifest 一致）。
 2026-10-17 23:21:51 +08:00
jkooe 9f95560268 build(ci): 控制台安装包接入 Release —— 修「修复发了但没人拿得到」 
## 问题
`scripts/release.mjs` 只产出 agent / cli / mcp，`apps/console` 从来没接进去。
后果很具体：今天修的 6 个真机缺陷（转圈、状态卡死、退出确认、复用、断管、ws/wss）
**只存在于 CI artifact**，而 artifact retention 是 7 天。
用户从 Release 页面下载到的，永远是旧控制台。

## 做法
1. `console-windows.yml` 加 `workflow_call:`，并新增 `publish` job：
   - `if: startsWith(github.ref, 'refs/tags/v')` —— 只有 tag 才发布，日常分支构建跳过
   - 下载两架构产物 → 断言安装包数 ≥ 4（exe+msi × x64/arm64），少了直接报红，
     **绝不静默少发一个架构**
   - `gh release upload --clobber` 挂到 `release.mjs` 建好的那个 Release
   - release.mjs 在本地跑、与本工作流并行，故先轮询等 Release 出现（最多 10 分钟）；
     等不到就给 `::warning::` 并跳过，不阻塞流水线
2. 新增 `console-release.yml`：只认 `push: tags: ['v*']`，`uses:` 调用上面那个工作流

## 为什么不直接把 tags 写进 console-windows.yml
它带 `paths` 过滤。`paths` 与 `tags` 并存时，tag 推送会被路径判定挡掉而**静默不触发** ——
失败形态是「什么都没发生」，最难察觉。拆成「日常验证走分支 + 发布只认 tag」最稳。

验证：PyYAML 解析通过；triggers / jobs 结构正确；shell 转义已核对。
（tag 发布路径需真打一次 tag 才能端到端验证，见下文待办）
 2026-10-17 23:12:44 +08:00
jkooe c7d596e087 fix(ci): quality-gate 补 pnpm 版本（首次运行 10 秒即失败） 
首次推送后 Quality Gate 立即失败，两个 job 都在 pnpm/action-setup 步骤报：
  Error: No pnpm version is specified.

根因：本仓库其他三个工作流（console-windows / rust / windows-e2e）
都显式写了 `with: version: 12`，臣新加的这份漏了 —— 而 package.json
里没有 `packageManager` 字段，action 无从推断版本。

修：两处 pnpm/action-setup 均补 `version: 12`，与既有工作流保持一致。

教训：新增 CI 工作流不能只照抄步骤名，**版本/参数要与既有工作流对齐**；
否则门禁自己先挂，比没有门禁更误导（看起来"有 CI"，其实从未真正跑过检查）。
 2026-10-17 19:17:39 +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 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 e616e80819 fix(ci): 取安装器退出码改用 Start-Process -Wait，& 调 GUI 程序不等待也不设退出码 
第二个 run（38152850819）两 job 仍同点红，但已是另一处原因，且同样是
「静默失效」：日志里 `msiexec /a 失败（退出码 ）` —— $LASTEXITCODE 是空的，
而整步从开始到抛错只过了 0.8 秒。

根因：msiexec.exe 与 NSIS 安装包都是 **GUI 子系统程序**，PowerShell 用 `&`
调用时**既不等待其结束、也不设置 $LASTEXITCODE**（于是 $null -ne 0 判真，
在安装器还没跑完时就当场抛错）。arm64 那条没有 MSI、直奔 NSIS，
失败形态一模一样，正是同一根因的第二个样本。

修法：
- 两处都改 Start-Process -Wait -PassThru，读 $p.ExitCode（确定性等待）。
- 参数拼成**单个字符串**传入，避免 -ArgumentList 数组被 PowerShell 自动加引号
  而破坏 NSIS `/D=` 的「必须原样、不加引号、且是最后一个参数」语义。
- 新增 Wait-PayloadRoot：安装器可能「自己先退出、由子进程继续装」，
  给最多 30 秒收敛时间再判定「找不到 node.exe」，避免竞态误报。
- 打印安装器实际退出码，便于下次一眼看出是哪一类失败。
 2026-10-12 00:05:01 +08:00
jkooe 71f2cd2597 fix(ci): 控制台 Windows 断言改为解开安装包查内容，不再用体积阈值 
首个 run（38151366534）两个 job 双双失败，且失败点完全一致：
第 14 步「断言安装包存在且体积合理」。构建链路本身全绿 ——
tauri build（msi 34.2MB / nsis 19.5~23.2MB）、产物自举
（打包内 node v22.23.3 真跑起打包内 sidecar）都成功，
是守卫自己错了。

错在哪：断言写成「安装包体积 > 50MB」，理由是「含 Node 运行时约 80MB」。
这把**未压缩的目录形态**（.app ≈ 92MB）当成了**压缩安装包的体积** ——
LZMA 下 node.exe 自身就能压到 1/3~1/4，阈值必然误杀。
更根本的是：体积阈值属于「中间逻辑自洽」式断言，包大不等于
node.exe 真在里面，且压缩率会随版本漂。

改为解开安装包、查内容（msi 走 msiexec /a 管理安装，nsis 走
/S 静默安装），一次钉死三件事：
  ① node.exe / sidecar.mjs / agent.mjs 三样随包资源必须都在；
  ② node.exe 的 PE Machine 必须等于目标架构（最终产物的架构断言，
     对治「arm64 包里装的是 x64 node.exe」那类只在真机暴露的事故）；
  ③ node.exe 解压后 > 40MB，挡住占位文件。
附带收益：真装一遍本身就是安装器冒烟。

另加 timeout-minutes: 8，避免静默安装万一卡住把 job 拖满 60 分钟。
 2026-10-11 23:48:29 +08:00
jkooe 1471708f35 ci: 新增 Windows 控制台安装包构建（x64 + arm64 双架构） 
在此之前，控制台的 Windows 侧只被验证到「prepare:node + 自举」（见 windows-e2e），
**从未真跑过 tauri build**。而 Rust 里那些 cfg!(windows) 分支（taskkill 收进程树、
PowerShell 计划任务、node.exe 路径解析）在 macOS 上只被类型检查、
从未被编译成 Windows 目标，更没有产物级验证 —— 本工作流是它们的第一道真闸。

为什么必须双架构
----------------
被控端发布包出过「arm64 包里装的是 x64 node.exe」的事故：在 ARM Windows 上
**能 listen、但 TLS 握手不完成**，且 macOS 侧 100% 复现不出。
控制台同理 —— 它内含 node 运行时，且要用它**托起本机被控端**（即 TLS 服务端）。
故 x64 / arm64 必须各出一套。

为什么用原生 ARM runner 而不是交叉编译
------------------------------------
`windows-11-arm` 是 GitHub 的 ARM64 Windows runner（公共仓库免费，本仓库为 public），
在它上面 arm64 是**原生构建**。若改走 x64 机器交叉编译，需要 VS 的 ARM64 工具链，
且 prepare-console.mjs 的自检要**真执行** node.exe（x64 机器跑不了 arm64 二进制），
会逼着引入「跳过自检」这类削弱验证的开关 —— 宁可等原生 runner。

两条断言是必需项，不是顺手检查
----------------------------
1. **构建机架构 ⇄ 目标架构**：ARM runner 镜像里确实存在 x64 模拟的组件
   （社区实测 python 即为 AMD64）。一旦 Node 也是模拟版，process.arch 会是 x64
   → 把 x64 的 node.exe 打进 arm64 安装包 → 真机上能启动、TLS 握手不完成，而 CI 全绿。
2. **随包 node.exe 的 PE Machine**：与 pack.mjs 的双架构校验同源思路 ——
   不只看「脚本跑完了」，而是直接读最终要打进那个包的二进制头。
   中间逻辑再自洽，也可能因上游给了错架构的二进制而产出错包。

另断言安装包体积 > 50MB：含 Node 运行时（约 80MB），体积过小意味着运行时没打进去
—— 那种包能装、但一启动就找不到 node。

产物：x64 出 msi + nsis（企业批量部署 + 普通双击各一），arm64 只出 nsis
（WiX 的 arm64 MSI 支持面较窄，不值得为它引入不确定性）。
 2026-10-11 23:25:16 +08:00
jkooe ad569d4e6d ci: 控制台资源断言 2→3，并补 @nodeagent/agent 构建前置 
控制台随包分发的资源由 2 份增至 3 份（sidecar.mjs / node / agent.mjs）：
- rust.yml 的资源项断言同步改为 3，且不再只数个数 ——
  改为断言目标名确实包含 sidecar.mjs 与 agent.mjs、以及 node/node.exe 二者任一。
  只数个数的话，「三份但错了一份」照样过。

顺序依赖（本地验证发现不了的一类）：
prepare:node 现在还要 esbuild 打包被控端，故 @nodeagent/agent 的 dist 成为新的
前置产物。本地验证时 dist 早就在，会把这层依赖完全掩盖 —— 故在 steps 里显式写全
构建步骤，并加注释说明为什么顺序不能调。

rust.yml 的 paths 触发器补 scripts/lib/bundle-agent.mjs 与 apps/agent/**：
改这两处同样会让控制台打包结果变化，不触发就等于零覆盖。

windows-e2e.yml 同步：Windows 分支现在也覆盖 agent.mjs 的准备与解析。
 2026-10-11 11:42:14 +08:00
jkooe f558e3e7df chore(release): 交付物架构断言 + CHANGELOG 归置 v2.0.2 
已公开发布的 nodeagent-win-arm64.zip 内装的其实是 x64 的 node.exe
（两包内 node.exe 字节完全相同，PE Machine 均为 0x8664），该包在 ARM Windows 上
能启动、能 listen，却 TLS 握手不完成 —— 被控端实际不可用，而 macOS 侧 100% 复现不出。

- 新增 scripts/lib/zip-pe-arch.mjs：纯内置 zlib 手解 zip、读 PE 头判架构。
  不依赖 unzip / Expand-Archive（Windows runner 上没有 unzip）。
  含 CLI 自检入口，已注入故障实测会红（arm64 包去要 x64 期望 → 退出码 1）。
- release.mjs：生成资产前调用之，不符即中止发版 —— 拦在 tag/push 之前，
  是「交付物本身」的断言，与 pack.mjs 的「流程内部」断言分两层。
- windows-e2e.yml：把原先内联的 PowerShell 校验实现改为复用同一模块，
  消除两套实现各自漂移的可能。
- CHANGELOG：[未发布] 归入 v2.0.2。
 2026-10-11 10:17:30 +08:00
jkooe b2404291b0 fix(pack): arm64 包内实为 x64 node —— 缓存名不含架构 + 补 PE 架构断言 
release.mjs 先打 x64 时会把运行时缓存为 node-runtime.zip（该名不含架构），
随后打 arm64 时误判「已缓存」直接复用 → arm64 包内 node.exe 实为 x86-64
（两份公开包内 node.exe 字节完全相同，sha256 同为 fdddbf45…，PE Machine=0x8664）。
该包在 ARM Windows 上能启动、能 listen，但 TLS 握手不完成（控制端只见 E_TIMEOUT），
且 macOS 侧完全复现不出。

- pack.mjs: 缓存名改为 node-runtime-<arch>.zip（按架构隔离）
- pack.mjs: 解包后断言 node.exe 的 PE Machine 与 --arch 一致（防呆 C，已注入故障实测会红）
- ci: windows-e2e 补「双架构包 PE 架构校验」，直读最终 zip 内 node.exe 的 PE 头
      （此前 CI 只打 x64 且只验 x64，arm64 打包零覆盖 —— 该 bug 必然逃过 CI）
- docs: CHANGELOG 记录 ARM64 真机对照实测

真机实测（ARM64 Windows 虚拟机，同机同参对照）：
  arm64 → TLS 握手成功 + PSK + 51 项能力两端一致 + exec/审计全通
  x64   → E_TIMEOUT（复现「能 listen 但 TLS 握手不完成」）
 2026-10-11 09:42:32 +08:00
jkooe e816c1fd39 fix(ci): Windows 上补 sidecar:build —— 新加的步骤漏了前置产物 
本轮新增的「控制台 Node 运行时（Windows 分支）与自举验证」一步在真实 runner 上失败：
  ✗ 未找到 D:\a\nodeagent\nodeagent\apps\console\sidecar\dist\sidecar.mjs
根因：prepare-console.mjs 的前置检查要求 sidecar 已构建，而该步被排在了构建 sidecar 之前
（rust.yml 里恰好已有「构建 sidecar」在前，所以那边没暴露）。

教训（本地跑过 ≠ CI 跑得过，又一例）：本地验证时 sidecar/dist 早已存在，
把「步骤之间的产物依赖」这一层完全掩盖了。**新增 CI 步骤时，应逐条核对
「该步依赖的产物由哪一步生成、顺序是否确实在其后」，而不是在已有产物的本地环境里跑一遍就认为通过。**
 2026-10-11 09:00:09 +08:00
jkooe 8664ec2926 ci: 覆盖 Node 运行时准备与「产物自举」（Linux + Windows 双覆盖） 
新增 runtime 准备脚本后，两件事此前零覆盖：脚本本身在 Windows 上的分支、
以及「打包产物能不能真跑」。补上：

- rust.yml：prepare:node 真跑（验证脚本可用 + 产物自检）→ 断言注入片段声明两份资源
  → `verify-bundle --runtime` 真 spawn 运行时跑 sidecar 走一次 JSON-RPC。
  paths 触发加上 scripts/prepare-console.mjs。
  注：Linux 上不走 strip 分支（macOS 专属），故「strip 必须 adhoc 重签」由 macOS 本机实测覆盖。
- windows-e2e.yml：新增一步跑 prepare:node + verify-bundle --runtime —— 该脚本在 Windows
  上走的是「复制 node.exe、无 strip」的另一条分支，此前从未被真实 runner 验证过。
 2026-10-11 08:55:38 +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 d065242413 docs/ci: README 数字校正 + checkout 升 v5 
- README：统计口径已过期（43 能力 · **32** MCP 工具 · **114** 单测 · **26** E2E），
  校正为实测值：43 能力 · 38 MCP 工具 · 215 单测 · 30 E2E · 11 Rust 单测。
  另补「桌面控制台」小节（架构图、页面表、构建命令、平台门控说明）与构建步骤说明
  —— 新组件入库后不同步 README，读者会以为仓库里没有它。
- CI：actions/checkout@v4 → v5，消除 runner 上的 Node.js 20 弃用告警。
  仅升被标记的这一个；setup-node / pnpm-action 未被标记，不做未验证的连带升级。
 2026-10-07 10:18:52 +08:00
jkooe 0a5fa715d4 ci/test/chore: Rust CI + e2e 契约守卫 + 发版闸门加固 
【新增 .github/workflows/rust.yml】crates/ 此前**零 CI 覆盖**（唯一工作流只在
windows-latest 跑 pnpm 那套，不碰 Rust）。新工作流走 Linux 快车道，只跑该 crate：
- clippy --all-targets -- -D warnings（告警即失败；该 crate 既定标准是零告警）
- cargo test（9 单测 + 2 E2E）
- **工具链锁死 1.98.1** 而不跟 stable 漂 —— 否则 lint 集合随工具链漂移，
  「本地全绿」与「CI 绿」会分叉（本仓库已因同类原因吃过 8 轮 Windows CI 的苦头）。
本步当场抓到一处真实 lint：discovery.rs 的 sort_by(|a,b| b.f.cmp(&a.f)) → sort_by_key(Reverse(..))。

【tests/e2e/run.mjs】新增 testContractShapes：对**真实被控端**调 7 项只读能力，
断言返回字段 ⊆ manifest returns_schema（含数组首元素）。与单测侧的 console-contract
合起来构成闭环：
    agent 实现 ──e2e──▶ 协议契约 ──unit──▶ 前端类型
只调无副作用能力（不写文件/不装软件/不动输入），避免 E2E 产生难回收的变更。
**已注入故障实测会红**：给 system.info 塞 injected_drift_field → 精确报出契约外字段。

【scripts/release.mjs】发版闸门补第二层。原闸门只查 git ls-files --others（未跟踪文件），
但紧接着的 `git add -A` 会提交**已修改的跟踪文件**，而它们不在原闸门视野里 —— 真例：
`pnpm install` 把某应用依赖写进跟踪中的根 pnpm-lock.yaml（+1401 行），发版时静默推走
且闸门不响。现补「脏文件白名单」：除脚本自己改的文件外，任何脏跟踪文件一律中止发版。
另：Tauri 的版本号不在 package.json 而另存于 src-tauri/tauri.conf.json（且它才是打进
.app 的版本），原先漏更新 → 现一并纳入版本号写入，避免「包里是旧版本号」。

【package.json】补 test:rust 与 probe 脚本（probe 需 crates/ 在库内，现已满足）。
 2026-10-07 10:14:29 +08:00
jkooe 6b2b3828a5 fix(ci): 产物包检查改为反向断言 —— 包内**不得**含 PSK.txt（原来是断言应该有） 
045e3b0 起 PSK.txt 已不再打进公开 zip（现生成给本机，打进公开资产=泄露密钥），
但 CI 的必含清单里还列着 PSK.txt → 每轮必红，且方向完全反了。
现在：必含 7 项 entries；并反向断言不含 PSK.txt / *.key / *.pem / certs ——
把「公开资产不带钥匙」这条性质变成 CI 守护项，而不是相反的束缚。
 2026-10-07 02:27:58 +08:00
jkooe 9ee75cf694 ci: 清理步骤加 continue-on-error（前置失败不应连带掩盖真实结论） 2026-10-07 02:15:05 +08:00
jkooe cd278ffda8 fix(ci): 5.1 执行的内联脚本一律 ASCII-only（同一个 BOM 坑，臣在 CI 步骤里原样复现） 
第二轮 CI 暴露：『install.ps1 安装链路』失败，报 string is missing the terminator。
根因不是被测脚本（BOM 守卫同轮通过），而是**步骤自身的 run: 块里有中文** ——
GitHub 把 run 块写成**无 BOM** 的临时 .ps1，5.1 按 GBK 读 → 中文乱码 → 引号边界崩。
这与 2026-10-04 install.ps1 无 BOM 导致的事故是同一机制，臣在 CI 里原样踩了一遍。

修正：
- 所有 shell: powershell（= 5.1）/ shell: cmd 步骤的内联脚本改为 ASCII-only
  （中文只留在步骤名，那是元数据不参与执行）
- BOM 守卫的 throw 消息也一并英文化（它上一轮是侥幸没过炸）
- 清理步骤加 continue-on-error，避免前置失败连带掩盖真实结论

保留：shell: pwsh 步骤的英文/中文不受影响（7+ 认 UTF-8 无 BOM）。
 2026-10-07 02:14:27 +08:00
jkooe 817ec3645b fix(ci): BOM 守卫步骤改用 shell: powershell（cmd 套 -Command 多行引号会全乱） 
第一轮 CI 暴露：该步骤自身写法错，不是脚本错。shell: cmd + powershell -Command "..."
带多行/内层引号，经 cmd 转义后变成：
  Missing closing '}' / '$errs' is not recognized / -and was unexpected
全是指 step 自身，与被测 .ps1 无关。

修正：直接用 shell: powershell（runner 上的 powershell 就是 5.1，正是要测的目标）+ run: | 块，
与旁边已通过的 install 冒烟步骤同一形态。
 2026-10-07 02:04:43 +08:00
jkooe af1cd39fdf ci: 补全 Windows 真机验证（单测步骤 + 5.1 BOM 守卫 + install.cmd 双击链路冒烟） 
三处改动都源自真机事故复盘：
1. **单测步骤**（并入 ci/workflow-unit-tests 分支 4d73d6e 的实质贡献 —— 该分支基于
   09-29 老 main，直接 merge 会回退上万行，故只取其提交内容手工并入）
2. **PowerShell 5.1 解析守卫**：install.ps1 无 BOM 时 5.1 按 GBK 解析 → 中文注释
   破坏字符串边界 → 整份脚本 ParseError（2026-10-04 真机踩过）。此前 CI 冒烟用
   pwsh（7+ 认无 BOM UTF-8）**所以 CI 绿、真机炸** —— 现在这道守卫只问一件事：
   5.1 能否读懂，而这就是真机的核心约束
3. **install.cmd / control.cmd 双击链路冒烟**：这是用户唯一的上手入口，
   编码或语法坏了只有真机 cmd.exe 能测出来

（workflow 作用域已于 2026-10-07 由皇上授权后推送）
 2026-10-07 01:55:14 +08:00
jkooe 9e357cf7cc Create windows-e2e.yml 2026-09-27 02:23:42 +08:00