mtfyun/nodeagent
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
226 Commits 1 Branch 14 Tags
5e32d7fa554b6071b59fca77cee2d66c06e3533e
Commit Graph
32 Commits
Author SHA1 Message Date
jkooe eebfb45f73 fix(console): L2 采集参数常显 —— 不再「必须先出一次结果」才出现输入框 
「采集窗口（小时）」「条数上限」两个输入框原先嵌在 v-if="l2Rows.length" 的
容器里，于是想「先设 72 小时再采集」做不到，只能先按默认值点一次再改。

参数与结果没有生命周期关系，拆出容器常显；结果区仍由 l2Rows.length 控制。
 2026-10-27 08:04:26 +08:00
jkooe 5bacade667 chore(deps): 依赖漏洞清零 —— zod/body-parser 覆盖 + vite 升 8.3.5 
Quality Gate 的「依赖漏洞扫描（SCA）」在 451d44a 上红：`pnpm audit
--audit-level=high` 报 3 个 high，全部不是本仓直接可控的代码：

- zod <4.6.6（GHSA-mrhx-c7xc-m3w5），路径 apps/mcp → @modelcontextprotocol/sdk；
- body-parser <2.4.0（GHSA-27r3-jxmh-p828），同上经 sdk→express；
- vite <8.3.3（GHSA-587h-7wmj-h5pm），控制台 devDependency。

处置：前两者用根 pnpm-workspace.yaml 的 overrides 抬到修复版（同 major patch 级）；
vite 直接改依赖范围 ^8.3.5。实测 14 → 6 条（**0 high**），门禁转绿。

注意（真坑）：pnpm 12 已不读 package.json 的 `pnpm` 字段，overrides 写在那里会被
**静默忽略**（install 报 "Already up to date" 但审计毫无变化）—— 必须写进
pnpm-workspace.yaml，理由与命令均落在文件注释里。
 2026-10-27 00:26:55 +08:00
jkooe 5a2c5f9c55 feat: 三端暴露 L2 系统级审计（MCP na_audit_l2 + 控制台 L2 分区 + agent.l2 类型） 
决策「L2 同时暴露 MCP+控制台」。此前 system.audit.l2 只存在于
被控端实现里：MCP 无工具（模型看不到）、控制台无入口无类型
（用户点不到）、审计事件写成 agent.start（与进程生命周期混类筛不出）。

MCP（41 → 42 个工具）：
- defs.ts 在 na_audit 后新增 na_audit_l2（action: status/enable/
  collect/verify + since/limit，additionalProperties: false）
- index.ts TOOL_TO_CAPABILITY 映射 CapabilityNames.AuditL2，
  分发走 default 直通（参数名与被控端一致，无需改写）
- mcp-tools 守卫同步：41→42、BASELINE_SEQ_SHA 重算、
  新增「na_audit_l2 必须紧随 na_audit」顺序断言

控制台：
- conn.ts WINDOWS_ONLY_CAPS += system.audit.l2（非 Windows 被控端
  上按钮禁用并明示原因，不搞「点了才报错」）
- types/index.ts 新增 AuditL2Result（四 action 属性并集，对齐
  manifest returns_schema）+ AuditType += agent.l2；
  AuditEntry 同步补 args_bytes/args_truncated（A-P0-4 新字段）
- AuditView.vue 新增 L2 卡片：查状态/拉取采集/校验 L2 链/启用策略
  （NPopconfirm 二次确认 + 管理员权限提示）；信任边界如实说明
  （采集器与 agent 同权限，防篡改依赖转发出机，不夸大本地副本）

agent.l2 审计类型四端同源：
- protocol audit-types.ts AUDIT_TYPES（真源）+= agent.l2
- agent audit.ts AuditType 联合同步（AssertExact 编译期守卫兜底）
- audit-l2.ts 两处写入点 agent.start → agent.l2（L2 策略操作与
  进程生命周期无关，混类会污染两边统计与筛选）

守卫加强（console-contract 平台门控）：
- audit-l2.ts 平台门控由裸 throw 改用统一 assertWindows
  （错误信息格式统一 + 可被守卫扫到）
- 守卫扫描范围 +audit-l2.ts、模式 +assertWindows —— 覆盖面扩大；
  否则把 system.audit.l2 加进 WINDOWS_ONLY_CAPS 反而报红
- mcp-tools 正则盲区修复：原 na_[a-z_]+ 匹配不了带数字的工具名，
  na_audit_l2 会整个漏扫（新增了工具两个守卫却无觉）→ 放至 [a-z0-9_]+

新增 tests/unit/console-l2.test.mjs 5 例：前端字段 ⊆ returns_schema /
契约关键字段 ⊇ 前端渲染 / MCP 工具存在且映射 / agent.l2 四端同源 /
界面纪律（信任边界文案 + enable 二次确认 + 平台门控）
故障注入实测：审计类型退回 agent.start、WINDOWS_ONLY_CAPS 删项 → 3 处红；恢复 → 绿

单测 451/451、e2e 33/33、typecheck 全绿
 2026-10-26 00:28:44 +08:00
jkooe a75c5c9bc5 chore(release): 版本统一至 v2.1.0 + CHANGELOG 回填未发布提交 
- 经 scripts/lib/version-write.mjs 写入全部 11 处（8 package.json +
  tauri.conf.json + Cargo.toml/lock），无散点遗漏、无 skipped
- CHANGELOG [未发布] 段补入 v2.0.3..HEAD 全部提交主题：
  L2 系统级审计（7d781d1）、交付流水线（2bf45fd）、Linux 适配（00992e5）、
  质量门禁与 CI（141f479 等 4 个）、console-release（9f95560）；
  并修正「安装包尚未接入 Release」的过期记述
- version-write 单测 12/12 绿（含仓库版本号一致性守卫）
 2026-10-25 23:37:52 +08:00
jkooe 240c52c44f fix(console): 「连接本机」必失败 —— 地址硬编码 ws:// 无视 tls 
## 皇上实测
点「连接本机」→ 界面显示**连接失败**。

## 根因（协议层，不是鉴权）
`agent.rs` 里拼监听地址时**硬编码** `ws://127.0.0.1:{port}`，
完全没看同一个函数里刚解析出来的 `tls` 字段：

```rust
"url": format!("ws://127.0.0.1:{port}"),   // ← tls = true 时这是错的
```

而被控端 `agent.json` 默认 `tls: true`（只接受 TLS）。于是控制台用
**明文 WebSocket** 去连一个**只监听 TLS** 的端口：服务端在等 TLS ClientHello，
收到的却是 HTTP GET，握手当场失败。

**鉴别特征**：被控端审计里连一条记录都没有（根本没进到鉴权层），
所以「密钥对不对」根本轮不到 —— 这类故障看审计有无 `auth.success` 即可一刀切开：
- 有记录 → 问题在鉴权/ACL
- 无记录 → 问题在协议/网络层（本次就是）

## 修法
- `url` 改为按 tls 选择：`if tls { "wss" } else { "ws" }`
- 顺带修两处同类默认值（同一个坑）：
  - `stores/conn.ts` 兜底地址 → `wss://`
  - `NodesView` 远程节点输入默认值与占位 → `wss://`

## 守卫
新增单测 `连接地址应跟随tls开关而非硬编码ws`：分别写 tls=true/false 的
agent.json，断言得到 `wss://` 与 `ws://`。防止将来又被"简化"回硬编码。

验证：`cargo test --lib` **22 项全绿**；`vue-tsc --noEmit` 通过。
 2026-10-17 22:15:17 +08:00
jkooe 0782d901a3 fix(console): 消除两处同步阻塞调用 —— 修「按钮一直转圈、PID 不再更新」 
## 真机现象
被控端明明在跑，界面上「启动/停止/重启」三个按钮**同时**转圈不结束，
PID 停在旧值（显示 30160，实际已是 22948），点导航也不切页。
只能重开控制台。

## 根因一（臣上一版自己引入的）
`looks_like_agent()` 用 `std::process::Command::output()` 调 PowerShell：
**同步阻塞 + 无超时**。而这台机器上 PowerShell/CIM 本身就慢甚至偶发卡死
（实测 `Get-ScheduledTask` 2.0s、`Get-NetTCPConnection` 1.7s，
另有一次 CIM 查询直接 30s 超时）。

它在 `start()` 里被调用（复用判定），一旦卡住就**永久占住运行时线程** →
`run()` 的 finally 里的 `refresh()` 永远走不到 → `busy` 卡死、状态不再更新。
连带 sidecar 的请求也拿不到执行机会，表现为「重连中」但审计里没有任何握手记录。

改：`looks_like_agent` 改 async + `tokio::process` + **3 秒超时**。
超时/失败一律**判为「不是被控端」**（拒绝接管）—— 宁可让用户看到「端口被占用」
去手工排查，也不能误杀别人的进程。

## 根因二
`autostart::is_enabled()` 每次 `agent_status` 都会跑一次 `schtasks /Query`
（实测约 2 秒）。每刷新一次界面白等 2 秒，叠加后同样表现为转圈不结束。

改：加 5 秒 TTL 缓存（自启是低频状态），并在 `set()` 后 `invalidate_cache()`，
保证用户点完开关立刻看到新值而不是 5 秒前的旧值。

验证：`cargo build` / `cargo clippy` 干净；`cargo test --lib` **21 项全绿**。
 2026-10-17 21:55:44 +08:00
jkooe 00659165b1 fix(console): 状态永远停在「启动中」—— refresh 被 catch 跳过 
## 真机症状
被控端明明在跑（点「启动」后端答「**被控端已在运行**」、端口在听、验收 15/15 全通），
界面却一直显示「启动中」，「停止 / 重启」永久灰着 —— 用户完全无法操作。

## 根因（两条更新通道同时失效）
1. `run()` 把 `await refresh()` 写在 **try 里**：
   ```ts
   try { const r = await fn(); await refresh(); return r; }
   catch (e) { ... }        // ← 动作一抛错，refresh 就被跳过
   finally { busy = false }
   ```
   那一次 `start()` 抛了「已在运行」，于是 refresh 被跳过，界面停在旧值。
2. `na-agent-state` 推送在 **WebView 就绪前**发出，前端 `bind()` 的监听还没挂上 → 事件丢失。
3. `LocalServiceView` 的 `onMounted` 只调 `agent.bind()`，而 `bind()` 有 `bound`
   守卫 —— 第二次进页面直接 return，**不会刷新**。所以切页也救不回来。

后端状态其实是对的（`inner.state` 已是 running），纯前端未同步。

## 修法
- `run()`：`refresh()` 移入 **finally** —— 成败都同步状态。
  `refresh()` 自身已有 try/catch，不会掩盖原始错误。
- `LocalServiceView.onMounted`：显式再 `await agent.refresh()`，
  绕过 `bind()` 的 bound 守卫，每次进页面都拉一次（最便宜的状态自愈）。
- `snapshot()`：加状态自愈兜底 —— `STARTING` 且已有 PID 且超 2 秒，就按客观事实
  校正为 `RUNNING`（拿得到 PID 是进程已起的硬证据）；`STOPPING` 且无 PID 则校正为 `STOPPED`。

## 自愈的三条单测（含反向守卫）
- 已起 + 超 2 秒 → 必须 `running`
- 刚起（<2 秒）→ **不得**提前自愈（否则真实启动失败会被伪装成运行中）
- 无 PID → 不得自愈（进程根本没起来，不能装成 running）

验证：`cargo build` / `cargo test --lib`（17 项全绿）/ `vue-tsc --noEmit` 均通过。
 2026-10-17 21:09:13 +08:00
jkooe 704fb8cfc9 feat(console): 退出前确认是否保留被控端 + 下次启动复用已运行实例 
## 问题（皇上实测）
1. 退出控制台后仍有一个被控端在跑 —— 因为 `kill_on_drop(false)`，
   agent 成了孤儿继续监听端口。用户以为关了窗口就干净了。
2. 下次启动时该孤儿占着 8765，`start()` 直接报「端口已被占用」，
   明明有个健康实例却用不上。

## 需求 1：退出前确认
托盘「退出」与「关 X（未开启最小化到托盘时）」两条路都会留下孤儿，
故两条都必须问，否则从 X 走就绕过了确认。

- Rust：`quit` 不再直接 `app.exit(0)`，改为 emit `na-quit-requested` + 唤出窗口
- Rust：新增 `quit_app(keep_agent)` 命令 —— true 直接退出（保留 agent），
  false 先 `stop()` 再退出
- 前端：新增 `QuitGuard.vue`（挂在 `n-dialog-provider` 内），三选一：
  保留被控端退出 / 停止被控端退出 / 关闭弹窗即取消

为什么不加 `tauri-plugin-dialog`：前端已有 `n-dialog-provider`，
不必新增依赖，视觉也与全应用一致。

## 需求 2：复用已运行实例（adopt）
`start()` 遇到端口占用时不再一刀切报错，而是先分清占用者：

- 占用者**确实是** nodeagent 被控端（`looks_like_agent`：命令行含 `agent.mjs`）
  → **复用**：记 PID、置 RUNNING、`external=true`，返回 `adopted:true`
- 否则（用户自己的服务 / 别的应用）→ 仍报「端口已被占用，且占用者不是被控端」
  —— 绝不误接管别人的进程

配套：
- `Inner` 增 `external` 标记；`snapshot()` 暴露给前端
- `stop()` 支持外部实例（无 Child 句柄，走 `stop_pid()` → taskkill /T /F），
  并**等待端口真正释放**再返回，否则 restart 会误判「还活着」又复用同一个 PID
- `restart()` 无需改动：stop 收掉外部实例 + 600ms + start 自己 spawn
  → 天然把控制权收回本控制台
- 前端：状态栏加「已复用外部实例」标签

## 顺带修复（同一类问题）
上一提交把「检查更新」从全局 `busy` 拆出后，发现 `applyUpdate` 也占全局 `busy`
（下载 RPC 超时 330s），一并迁到 `updateBusy`。

验证：`cargo build` / `cargo clippy` 干净；`vue-tsc --noEmit` 通过。
 2026-10-17 20:18:32 +08:00
jkooe 618ebc986f fix(console): 更新检查不再锁死整页按钮（全局 busy 串台） 
真机现象：点「检查更新」后，启动/停止/重启等**所有**按钮一起转圈，
持续两分半，看起来像「点什么都卡死」。

## 根因（两个缺陷叠加）
1. **`busy` 是全页共享的**：`LocalServiceView` 里每个按钮都是 `:loading="busy"`。
2. **`check_update` 是网络操作且超时很长**：出网 120s / RPC 150s。
   而这两个值**不能缩短** —— `sidecar.rs` 的注释与编译期不变式记录了真机实测：
   跟随两次重定向的耗时出现过 2.0 / 10.0 / 39.7 / 68.6 / >109s，
   回落到 60s 会让 68.6s 那次变成「假失败」。
   故超时保持不动，**只修隔离**。

于是任何一次「检查更新」都会把全页按钮锁死 —— 更新检查本是
**只读、可等待、与启停无关**的操作，不该拖累其他按钮。

## 修法
- 新增 `updateBusy`，只服务「检查更新 / 更新被控端」
- 全局 `busy` 只留给毫秒级的启停与设置
- `applyUpdate` 同步迁移（下载 RPC 超时 330s，占用全局 busy 更糟）
- 视图里检查更新按钮与更新按钮改绑 `updateBusy`

## 刻意不改的
- `UPDATE_CHECK_TIMEOUT_MS` 保持 120s、RPC 150s —— 见上述实测，缩短会退回「假失败」
- `busy` 仍保留全局语义（启停确实应互斥）

验证：`vue-tsc --noEmit` 通过；`pnpm --filter nodeagent-console build` 通过。
 2026-10-17 19:54:04 +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 9384b64c42 fix(console): sidecar 补 CREATE_NO_WINDOW（不再弹常驻黑窗） 
真机复验 verbatim 修复时暴露的既有缺陷：点「检查更新」后屏幕上多出一个不消失的
黑窗（WindowsTerminal 承载，标题即 node.exe 路径）。

根因：控制台自身是 GUI 子系统，spawn 控制台子系统程序（node.exe）时 Windows 会
新建控制台，必须 CREATE_NO_WINDOW 抑制。AgentManager::start 早有此标志，
sidecar_command 漏了。修复 verbatim 前 sidecar 秒退、黑窗一闪而过；
sidecar 常驻后它才留在屏幕上。

修法：sidecar_command 补 creation_flags；常量提为 sidecar::CREATE_NO_WINDOW
由两处共用，避免值漂移。

本项无自动化守卫（如实记档）：creation_flags 只有 setter 没有 getter，
断言不到最终值；扫源码属源码级检查，违反铁律 1。靠真机截图对照把关。
clippy 零告警，test:rust 18/18（行为零变化的注释/常量整理 + 一处新标志）。
 2026-10-13 20:41:02 +08:00
jkooe 2437b0e863 fix(console): unverbatim 用 to_str 而非 to_string_lossy（不损坏非 UTF-8 路径） 
to_string_lossy 会把非法字节替换成 U+FFFD 再重建路径 —— 那是损坏路径，
比不净化更糟：原本只是 node 报 EISDIR，改完变成指向一个不存在的目录。

改为 to_str()：非 UTF-8 → None → 原样返回（Windows 上是含未配对代理项的路径，
Unix 上是含非法字节的文件名），绝不悄悄改写。

新增守卫 unverbatim_对非_utf8_的_verbatim_路径必须原样返回不得损坏（#[cfg(unix)]）：
构造必须同时含 \\?\ 前缀与非法字节才有区分力 —— 不带前缀时新旧实现都走
「原样返回」那一步，测不出差异。
注入故障（退回 to_string_lossy）实测该守卫如期变红；还原后 sha256 逐字节一致。
pnpm test:rust 18/18（+1），clippy 零告警。
 2026-10-13 20:21:51 +08:00
jkooe 56f64e1cc1 docs(console): 把 verbatim 路径的证据精确到「脚本参数」这一维 
真机二维四格实验（ProcessStartInfo，精确对应 Command::new(prog).arg(script)）：
  G1 plain-prog + plain-script    -> exit 0，正常
  G2 plain-prog + VERBATIM-script -> exit 1，EISDIR lstat 'C:'
  G3 VERBATIM-prog + plain-script -> exit 0，正常
  G4 VERBATIM-prog + VERBATIM     -> exit 1，EISDIR lstat 'C:'

结论：炸的是「脚本参数」带 verbatim，不是「可执行文件」带 verbatim。
旁证：真机上被控端与 sidecar 的 program 都带 \\?\ 却长期存活。

因此改准注释口径：净化 script 是关键修复，净化 node 属防御性
（守住「凡交给外部进程的路径都干净」这条单一纪律，不靠记位置）。
行为零变化（纯注释 + CHANGELOG）。
 2026-10-13 20:16:07 +08:00
jkooe eec76ed91e fix(console): 交给 node 的路径去掉 Windows verbatim 前缀（真机 sidecar 秒退根因） 
真机现象（Windows 11 ARM64，控制台 v2.0.3）：点「检查更新」立刻报
「sidecar 已退出（stdout 关闭），请重试」—— sidecar 在请求进行中真的退出了。

真机 A/B（同一个 node.exe、同一份 sidecar.mjs，只换脚本参数写法）：
  C:\…\sidecar.mjs        → 2.5 秒返回结果，进程常驻
  \\?\C:\…\sidecar.mjs    → 0.47 秒退出，exit 1，零 JS 执行

根因：Tauri 的 resource_dir() 在 Windows 上返回 canonicalize 后的 verbatim 路径，
把它当参数交给 node，node 启动期 realpathSync 把 `\\?\C:` 拆成 `C:` →
EISDIR ... lstat 'C:' → exit 1，一行 JS 都来不及执行。
本地/CI/开发模式全测不出：开发期走 CARGO_MANIFEST_DIR 的普通路径，只有打包后才暴露。

修法：
- 新增 unverbatim()：剥 \\?\UNC\ → \\、剥 \\?\ → 无前缀，纯字符串处理，全平台可调用
- 新增 sidecar_command()：唯一把路径交给 node 的地方，单测断言其最终 program/args
- resolve_node / resolve_sidecar / resolve_bundled_agent 全部出口加闸
- Sidecar::spawn 与 AgentManager::start 进程边界对 node/script/data_dir 三条路径净化
- autostart::app_exe() 净化（该路径进计划任务 -Execute）

回归：新增 3 条守卫；注入故障（去掉 sidecar_command 的 unverbatim）实测第三条如期变红，
还原后 sha256 逐字节一致。pnpm test:rust 17/17（14 → +3），clippy 零告警。
 2026-10-13 20:11:03 +08:00
jkooe 73ed06f5f1 fix(console): 修复 sidecar 退出后被复用（Windows 更新超时根因） 
现象（Win11 ARM64 真机）：点「检查更新」等满 45 秒报「check_update 超时」。
对照：同一台机器手工拉起 sidecar 跑同一请求 6.989s 成功；现场 node.exe
只有被控端一个 —— 控制台的 sidecar 进程根本不存在。

根因：ensure_sidecar 只判「缓存里有没有实例」，不判「那个实例还活着没」。
往已退出进程的管道写，在 Windows 上未必立刻报错（缓冲区吞下即返回成功），
于是请求既不报错也永远等不到响应，只能干等到 request 的超时。

修法：
- Sidecar 增 dead: Arc<AtomicBool>，三处置死（stdout EOF / 写入或 flush 失败
  / shutdown 主动关闭）；stdout 关闭时唤醒所有在等的请求，让它们立刻失败。
- 新增 is_alive()：dead / child.try_wait() / 已被 take 走，拿不准一律按不可用。
- request() 入口先判存活，不可用即秒失败。
- ensure_sidecar 取到缓存实例先判存活，已退出则丢弃重建。
- 新增 3 条单测（含「对已退出的 sidecar 发请求必须秒失败」——给 30s 超时但
  断言耗时 < 5s，因为修复前的表现正是干等到超时）。注入故障实测守卫变红。
- pnpm test:rust 14/14；test:unit 321/321。

属控制台上壳变更，不触发 release patch；但需重建控制台安装包才能让用户拿到修复。
 2026-10-13 17:59:49 +08:00
jkooe 79969e9d5d chore(release): v2.0.3 2026-10-13 17:36:54 +08:00
jkooe 530bb4fca7 fix(console): 加单实例保护，修「Windows 端起了两个被控端」 
真机现象两桩：① Windows 上同时跑着两个被控端；② 旧的服务端还在跑时控制台起不来。
根因同一个：控制台没有单实例锁，再启动一次就是第二个进程 → 第二个 AgentManager
→ 抢同一个 8765 端口 → 后起的那个起不来。另有一条陈旧的 na-gui 计划任务指向测试
部署目录，也在抢同一个端口。

- 引入 tauri-plugin-single-instance（**必须注册为第一个插件**）。
- 第二次启动**不是**静默退出，而是「聚焦既有窗口 + 发 na-second-instance 事件」让前端
  刷新状态。这是刻意的：自启动实例是**无窗口**的，若第二次启动静默退出，用户双击图标
  只会看到「什么都不发生」—— 那比缺陷本身更难排查。带自启参数（AGENT_ONLY_FLAG）时跳过显示。
- 端口占用的报错补上「怎么找出占用者」：netstat -ano | findstr :<port> /
  lsof -nP -iTCP:<port> -sTCP:LISTEN，并新增一条单测。
 2026-10-13 17:16:41 +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 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 591e44721a style(console): 界面一律不使用图标 —— 导航改纯文字，并关闭内置插画/图标 
触发原因是一次真实的渲染事故：侧栏那些 emoji 图标在非系统字体栈的渲染器里
退化成**豆腐块**（本机截图对比可见）。试过给图标指定 Apple Color Emoji、
全局字体栈加 !important、乃至 font-variant-emoji —— 分别无效或更糟
（最后一招把 ASCII 数字也拆成了 emoji 呈现）。而「哪套字体栈一定带 emoji」
跨平台并不成立，与其赌字形，不如不用。

  emoji 图标          → 路由表 meta.icon 字段整体移除，侧栏改纯文字
  n-empty 空态插画    → 16 处 :show-icon="false"（空态里的插画比图标更「图形」，
                        分布在 9 个页面，是最容易漏掉的一类）
  n-alert 类型图标    → 7 处（naive-ui 的 showIcon 默认 true，不显式关就在）
  n-popconfirm 询问图标 → 3 处
  夹在文案里的 ⚠      → TerminalView 的「高权限操作，请谨慎」保留纯文字

严重程度不靠图标也能读：n-alert 仍由 type 的底色/边框区分。

顺带清掉随包的模板残留资产：
  public/vite.svg、public/tauri.svg —— public/ 下的文件会被整体复制进产物，
  此前等于把 Vite / Tauri 的 logo 一并发出去了（且 index.html 的 favicon 正指向它）；
  src/assets/vue.svg —— 无人引用；
  index.html 的 <title> 还是模板默认的「Tauri + Vue + Typescript App」。
  原生窗口标题取自 tauri.conf.json（"nodeagent 控制台"），故此前不影响观感，
  但与 dev 态浏览器标签页不一致，一并改齐。

「不属界面图标、刻意未动」的三类写明在 CHANGELOG 里：
托盘图标（菜单栏没图标就点不到，关窗后应用无法寻回，属功能必需）、
被控端 CLI 自身打印的文本标记（⚠️/ℹ️/✅，是程序输出内容，非界面元素）、
控件的结构性部件（下拉箭头、折叠箭头、输入框清除钮、表格排序箭头）。

验证：vue-tsc 0 错 ｜ 契约守卫 6/6 ｜ 单测 280/280 ｜ 前端产物内已无任何 svg 与 logo 字样 ｜
macOS .app 重打通过（92.21 MiB，前端在无 public/ 下亦正常构建）。
 2026-10-11 13:50:49 +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 f85acad5db chore(release): v2.0.2 2026-10-11 10:18:28 +08:00
jkooe 22bc732334 feat(console): 控制台随包分发 Node 运行时（目标机器无需预装 Node） 
控制台的 sidecar 是 .mjs，此前只能在装了 Node 的机器上跑（resolve_node 会回退系统 node）。
新增 scripts/prepare-console.mjs 把 Node 运行时准备为 Tauri resource，随包分发给最终用户。

- prepare-console.mjs：复制本机 node → apps/console/src-tauri/runtime/，macOS 上 strip -x
  （108MB→86MB）**并 adhoc 重签**，再生成注入片段 tauri.bundle.gen.json；带幂等（同源跳过）
  与**产物自检**（真跑一次 node，失败即删除产物并报错，避免坏产物被静默复用）。
- apps/console/scripts/verify-bundle.mjs：验证「打包产物能否自举」——真 spawn 打包内的 node
  去跑打包内的 sidecar 并走一次真实 JSON-RPC 握手。
- package.json：新增 prepare:node / verify:bundle，bundle = sidecar:build → prepare:node →
  tauri build --config → verify:bundle（一条命令产出可分发件并自证可用）。
- src-tauri/.gitignore：忽略 /runtime/（~86MB）与生成的注入片段（生成物不入库）。

三处实测踩出来的约束（均已写进脚本注释与 console-plan.md）：

1. **macOS 上 strip 会使 Mach-O 代码签名失效 → 内核直接 SIGKILL(exit 137)**，且无任何有用报错。
   实测对照：原样复制 ✓ ／ strip 不重签 ✗(137) ／ strip + `codesign --force --sign -` ✓。
   故 strip 之后的 adhoc 重签是**必要配套**，不是可选优化。
2. **Node 运行时不得声明进默认 tauri.conf.json** —— bundle.resources 是编译期契约
   （tauri-build 校验声明的文件必须存在），声明「运行期才就绪」的资源会让 cargo check/test
   在 build.rs 阶段直接失败（2026-10-10 已踩）。故一律走 `tauri build --config` 注入。
3. **resource 映射必须与 resolve_node 对齐** —— `runtime/node → node` 使产物落在
   Contents/Resources/node，正是 src-tauri/src/sidecar.rs 里 resolve_node 查找的路径。

实测（macOS arm64）：.app **90.8 MiB**（原 6.75 MiB，增量即运行时 86MB）／
.dmg **33.78 MiB**（分发件，仍低于 40MB 目标）；应用进程实测可启动且无崩溃输出。
对照：本机实测 Electron 运行时本体（Electron Framework.framework）207MB —— 不到一半。
 2026-10-11 08:55:31 +08:00
jkooe 4f4d8913b5 chore(release): v2.0.1 2026-10-11 08:02:19 +08:00
jkooe 2fe717cb62 fix(ci): 修 clippy 的两个错误（含一个真实并发问题）+ 本地补齐 lint 验证 
## CI 失败的真实原因（上一轮我误判为 resources，实为 clippy）
`-D warnings` 下两个错误：
1. **`clippy::await_holding_lock`（sidecar.rs，真问题）**：
   `if let Some(child) = self.child.lock().unwrap().take() { child.kill().await }`
   —— MutexGuard 存活到 if 块结束，**跨 await 持有 std Mutex**：不仅触发 lint，
   真会阻塞 executor。已改为「先取出 child（锁随即释放），再 await kill」。
2. `clippy::doc_lazy_continuation`（lib.rs 文档注释）：列表与后续段落之间缺空行。

## 我的验证方式错在哪（已修正）
上一轮我本地只跑 `cargo test`，**没跑 clippy** —— 而 CI 是 `clippy -D warnings` + `test`
两道闸。本地与 CI **标准不一致**，于是"本地绿、CI 红"。
本轮起：**本地按 CI 的完整命令集验证**（clippy --all-targets -- -D warnings → cargo test）。

## 验证
- `cargo clippy --all-targets -- -D warnings` → **零警告**
- `cargo test` → **3/3 通过**
 2026-10-10 15:33:11 +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 a515eb2e63 chore(release): v2.0.0 2026-10-10 12:14:02 +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 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