chore(release): v2.0.0

- CHANGELOG：「未发布」→ v2.0.0（2026-10-10），补兼容性声明（完全向后兼容）
  与**已知限制**（发布时被控端离线 → v1.5 的四项与 v26 清理策略尚未真机验证）
- .gitignore：忽略 .workbuddy/（memory/automations 属本机状态，不应入库；
  此前未被忽略，会干扰 release.mjs 的干净工作区检查）

.github/workflows/rust.yml

@@ -0,0 +1,54 @@
+name: Rust Client
+
+# crates/nodeagent-client 是桌面控制台的协议客户端（Tauri 壳经 Cargo path 依赖它）。
+# 它是纯 Rust、无平台相关代码，故单开一个 Linux 快车道：
+# 比 Windows 那条 E2E 长流程反馈快得多，失败归属也一目了然。
+#
+# ⚠️ 本工作流与仓库其余部分的铁律不同：**不涉及** .ps1/.cmd 编码，无需 BOM 守卫。
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'crates/**'
+      - 'packages/protocol/**'
+      - '.github/workflows/rust.yml'
+  pull_request:
+    paths:
+      - 'crates/**'
+      - 'packages/protocol/**'
+      - '.github/workflows/rust.yml'
+  workflow_dispatch:
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  test:
+    name: Rust 客户端单测 + E2E
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v5
+
+      # 版本**锁死**而不跟 stable 漂 —— 否则「本地全绿」与「CI 绿」会因为 lint 集合随
+      # 工具链变化而分叉（本仓库已因同类原因吃过 8 轮 Windows CI 的苦头）。
+      # 当前值与 crates/ 开发环境一致：rustc/cargo 1.98.1、clippy 0.1.98。
+      # 升级时两边同改，升完先本地复跑 `cargo clippy ... -- -D warnings`。
+      - name: 安装 Rust 工具链（1.98.1，含 clippy）
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.98.1
+          components: clippy
+
+      - name: 缓存 cargo 构建产物
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: crates
+
+      # clippy 单列为一步：它拦的是「能编译但不该这么写」，与测试失败是两类问题。
+      # -D warnings 让告警即失败 —— 该 crate 的既定标准是**零告警**。
+      - name: Clippy（告警即失败）
+        run: cargo clippy --manifest-path crates/nodeagent-client/Cargo.toml --all-targets -- -D warnings
+
+      - name: 单测 + E2E
+        run: cargo test --manifest-path crates/nodeagent-client/Cargo.toml

.github/workflows/windows-e2e.yml

@@ -27,7 +27,7 @@ jobs:
 
     steps:
       - name: 检出代码
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: 安装 pnpm
         uses: pnpm/action-setup@v4
@@ -48,6 +48,10 @@ jobs:
 
       - name: 类型检查
         run: pnpm typecheck
+      - name: 单元测试 — 协议纯函数 / 清单守护 / 脚本生成
+        # 来自 ci/workflow-unit-tests 分支（4d73d6e）的实质贡献；该分支基于老 main，
+        # 直接 merge 会回退上万行，故只取其提交内容手工并入。
+        run: node --test "tests/unit/**/*.test.mjs"
 
       - name: E2E — 协议与跨平台能力
         run: node tests/e2e/run.mjs
@@ -55,25 +59,88 @@ jobs:
       - name: E2E — Windows 专属能力（服务 / 软件 / winget）
         run: node tests/e2e/windows.mjs
 
+      # ⚠️ 这一步刻意用 **powershell（Windows PowerShell 5.1）** 而非 pwsh。
+      # 5.1 读无 BOM 的 .ps1 会按 ANSI/GBK 解析，中文注释会破坏字符串边界 →
+      # 整份脚本 ParseError（真机 2026-10-04 踩过：install.ps1 报「","后面缺少表达式」）。
+      # 之前的冒烟全用 pwsh（7+ 认无 BOM UTF-8），所以 CI 绿、真机炸。
+      # 这里只做「解析 + 首行 help」检查：5.1 能否读懂，就是真机的核心约束。
+      # ⚠️ 必须用 shell: powershell（runner 上的 powershell 即 Windows PowerShell 5.1）。
+      # 不要用 shell: cmd 再套 powershell -Command "..." —— 多行带引号经 cmd 转义会全乱
+      # （实测：Missing closing '}' / '$errs' is not recognized，是步骤自身坏，不是脚本坏）。
+      - name: 冒烟 — 脚本可被 Windows PowerShell 5.1 解析（BOM 守卫）
+        shell: powershell
+        run: |
+          $ErrorActionPreference = 'Stop'
+          foreach ($f in @('scripts\install.ps1', 'scripts\uninstall.ps1', 'scripts\rescue-network.ps1')) {
+            $errs = $null
+            [void][System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path $f).Path, [ref]$null, [ref]$errs)
+            if ($errs -and $errs.Count -gt 0) { throw ('5.1 parse FAILED: ' + $f + ' -> ' + $errs[0].Message) }
+            Write-Host ('OK 5.1 parse: ' + $f)
+          }
+
       - name: 冒烟 — install.ps1 安装链路
-        shell: pwsh
+        shell: powershell
         run: |
           $ErrorActionPreference = "Stop"
           ./scripts/install.ps1 -Port 18769 -NodeId ci_win
 
           $task = Get-ScheduledTask -TaskName "nodeagent" -ErrorAction Stop
-          Write-Host "计划任务状态: $($task.State)"
+          Write-Host "Scheduled task state: $($task.State)"
 
           $cfg = Get-Content "$env:USERPROFILE\.nodeagent\agent.json" -Raw | ConvertFrom-Json
-          if ($cfg.port -ne 18769) { throw "端口配置错误: $($cfg.port)" }
-          if (-not $cfg.key)       { throw "预共享密钥缺失" }
-          if (-not $cfg.tls)       { throw "TLS 默认应开启" }
+          if ($cfg.port -ne 18769) { throw "port mismatch: $($cfg.port)" }
+          if (-not $cfg.key)       { throw "PSK missing in agent.json" }
+          if (-not $cfg.tls)       { throw "TLS should be on by default" }
 
           $rule = Get-NetFirewallRule -DisplayName "nodeagent (TCP 18769)" -ErrorAction Stop
-          if (-not $rule) { throw "防火墙规则未创建" }
+          if (-not $rule) { throw "Firewall rule" }
 
-          Write-Host "OK — 计划任务 / 配置 / 防火墙均已就位"
+          Write-Host "OK  scheduled task / config / firewallall in place"
 
+      # 一键入口冒烟：真跑 install.cmd / control.cmd。
+      # 目的不是「再装一遍」，而是证明双击路径可用 —— 这些脚本是用户唯一的
+      # 上手入口，语法或编码一旦坏了，只有真机 cmd.exe 才测得出来。
+      # 端口用 18770 避开前一步的 18770 之外的安装，便于分辨是哪一步装的。
+      - name: 冒烟 — install.cmd 双击链路（含自提权与 PSK 读取）
+        shell: cmd
+        run: call scripts\install.cmd 18770
+        env:
+          CI: "true"
+      - name: 冒烟 — control.cmd 状态查询
+        shell: cmd
+        run: scripts\control.cmd 18770 < nul
+        env:
+          CI: "true"
+      - name: 冒烟 — 产物包结构与编码
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          pnpm pack:win
+          $zip = "release/nodeagent-win-x64.zip"
+          if (-not (Test-Path $zip)) { throw "zip not produced: $zip" }
+          Add-Type -AssemblyName System.IO.Compression.FileSystem
+          $z = [IO.Compression.ZipFile]::OpenRead((Resolve-Path $zip))
+          try {
+            $names = $z.Entries.Name
+            # 必须随包分发
+            foreach ($need in @('install.cmd','control.cmd','install.ps1','control.ps1','README.txt','agent.mjs','node.exe')) {
+              if ($names -notcontains $need) { throw "missing in package: $need" }
+            }
+            # 必须**不**在包内：PSK.txt 是现生成给本机的，打进公开资产等于泄露密钥
+            # （eaca9e0 起已从 zip 剔除；此处反向断言守住该性质）
+            foreach ($forbidden in @('PSK.txt','*.key','*.pem','certs')) {
+              if ($names -contains $forbidden) { throw "package must NOT contain: $forbidden" }
+            }
+            if ($names -match 'PSK\.txt') { throw "package leaks PSK.txt" }
+            foreach ($e in $z.Entries) {
+              $s = $e.Open(); $buf = New-Object byte[] 3
+              [void]$s.Read($buf, 0, 3); $s.Close()
+              $hasBom = ($buf[0] -eq 0xEF -and $buf[1] -eq 0xBB -and $buf[2] -eq 0xBF)
+              if ($e.Name -like '*.ps1' -and -not $hasBom) { throw "$($e.Name) lost its BOM in package" }
+              if ($e.Name -like '*.cmd' -and $hasBom) { throw "$($e.Name) must not have a BOM" }
+            }
+            Write-Host "OK - package complete; .ps1 has BOM / .cmd has none; no key shipped"
+          } finally { $z.Dispose() }
       - name: 冒烟 — 被控端监听
         shell: pwsh
         run: |
@@ -108,7 +175,9 @@ jobs:
 
       - name: 清理
         if: always()
-        shell: pwsh
+        # 清理失败不掩盖真实结论（前置挂了会连带这里报错）
+        continue-on-error: true
+        shell: powershell
         run: |
           Get-Process node -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue
           ./scripts/uninstall.ps1 -Port 18769 -Purge

.gitignore

@@ -40,3 +40,17 @@ release/
 # 重装备份数据（含设备软件清单，不入库）
 ../win-backup/
 win-backup/
+
+# Rust 构建产物
+# ⚠️ 2026-10-07：crates/ 此前整体被忽略，target/ 是「顺带」没进库的；crates/ 正式入库后
+#    必须显式忽略，否则 4GB 级的 cargo target 会被 add -A 卷进提交。
+/crates/target/
+
+# 密钥材料（路线图 §6.2）：被控端数据目录 keys/、ed25519/TLS 私钥
+keys/
+*.key
+*.pem
+!*.pub
+
+# 本地 agent 工作数据（memory / automations 等，属本机状态，不入库）
+.workbuddy/

CHANGELOG.md

@@ -0,0 +1,121 @@
+# 变更日志
+
+本文件记录 nodeagent 的显著变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+---
+
+## [v2.0.0] —— 2026-10-10
+
+> 自 `v1.6.0` 起累计 37 个提交。**能力数 43 → 51**，单测 195 → 273，端到端 30。
+> 之所以直接跳 v2.0.0：两个新方向（语义可断言 / 状态可回看）+ 安全批次四连 + 五处
+> 只有真机能暴露的严重缺陷修复，量级远超一次 MINOR。
+>
+> **兼容性**：完全向后兼容 —— 未改任何既有能力的参数名或语义，未新增必填参数，
+> 返回结构只增不减（遵循 `docs/VERSIONING.md` 的四条铁律）。
+>
+> **已知限制**：本版发布时被控端整机离线，`v1.5` 的预设别名/长按/后台投递/热键序列
+> 与 `v26` 的自重启任务清理策略**尚未经真机验证**（后者已在本地单测锁定判定条件）。
+
+### 新增：语义可断言（v1.6 / v1.7）
+
+- **`gui.await`** —— 等条件成立再返回。四类条件（`window` / `control` / `process` / `file`）
+  × 两种状态（`present` / `absent`），复用既有能力，零新增平台探测代码。
+  超时是**正常返回**（`satisfied:false` + `note`），不抛异常；轮询期单次异常不视为失败。
+- **`screen.find` 返回 UIA 属性** —— `enabled` / `value` / `selected` / `toggle`。
+  每项单独 try/catch，**拿不到就留 `null` 绝不猜**（Electron、游戏 UI 常给不出值）。
+- **`where` 属性谓词** —— 如 `{"enabled":true}`「等一个可用的按钮」，
+  比「等一个叫某名字的按钮」更贴近真实意图。仅 UIA 引擎生效，
+  OCR/图像引擎会忽略并**带回 `note`**，不让调用方误以为过滤过了。
+- **`any_of` 组合** —— 任一命中即算，命中时回报是哪个子条件。
+  例：`[{window:"安装完成"},{control:"错误"}]` = 「装成功或报错，先出现的算」。
+- CLI：`nodeagent await`；MCP：`na_await`。
+
+### 新增：状态可回看（v1.8）
+
+- **`log.query`** —— 日志**在被控端侧过滤**后只回匹配行（`pattern` / `level` / `since` /
+  `offset` / `limit` / `tail`）。流式逐行读，几万行日志也不整份拉回。
+- **`monitor.start` / `report` / `stop` / `list` / `delete`** —— 定时采样并落盘。
+  四类源：`port`（连通性 + 延迟）/ `process`（存活 + PID）/ `command`（退出码 + 首行）/
+  `metric`（CPU·内存）。**摘要直接给结论**：断了几次、最长断多久、值域。
+- CLI：`nodeagent monitor` / `log`；MCP：`na_monitor` / `na_log`。
+
+### 新增：安全加固（v23 / v24 / v25）
+
+- **连接层三防护**：
+  - 握手失败封禁 —— 连续失败达阈值 → 指数退避（封顶 24h），成功即清零，支持白名单豁免
+  - 连接上限（默认 8）+ 空闲断开（默认 30 分钟；有任务或订阅在跑时保守不踢）
+  - 状态从 `WeakMap` 改 `Map`（需要 size 与遍历），关闭时手动清理
+- **安装期密钥改 stdin** —— `install.cmd` 用管道喂 `-KeyFromStdin`，密钥不再出现在命令行
+  （同机其他用户无法从进程命令行读到）。
+- **零信任优先安装** —— 侦测到 `client-acl.json`（含控制端公钥）即走 `ed25519` 并写入
+  `acl.default_effect="deny"`；否则保持 `psk` 但输出**醒目安全告警**（说明 `client_id`
+  自报的固有风险 + 三步切换指引）。
+- **审计链外部锚定** —— `system.audit.head`（链头可读）+ `system.audit.anchor`（锚点追加落盘）。
+  锚点记四元组 `{entries, head_hash, head_ts, rotated_segments}`：只记哈希会把**日志轮转
+  误判成篡改**。锚点文件只追加 —— 可覆盖的话，攻击者重写链后再刷新锚点即可抹痕。
+
+### 修复（五处只有真机能暴露的严重缺陷）
+
+- **`install.cmd` 双击首装即炸** —— `for /f` 调 PowerShell 时 `^|` 转义漏进 PS，导致
+  ParseError。**真实用户第一次安装必然踩到**（PSK.txt 已不在分发包内）。
+- **`pack.mjs` 三连** —— `spawn node_modules/.bin/esbuild` 在 pnpm 布局下 ENOENT；
+  以及 `zip` / `ls -la` / `du -sh` 在 Windows 上都不存在。已改为 esbuild JS API +
+  平台分流（Windows 用 `Compress-Archive`）+ Node 原生 API。
+- **`where` 的 PowerShell 注入语法错** —— 连修两轮：JSON 字面量 ✗ → `\"` 反斜杠转义 ✗
+  （PS 5.1 不认）→ **PS 单引号字面量** ✓。症状是「带 where 一律窗口操作失败，不带则正常」。
+- **`screen.find` 的 where-only 被自己入口校验拦下** —— 只改了一半（`gui.await` 侧放开、
+  `screen.find` 侧没动）。
+- **`parseLeadingTs` 吃掉 ISO 的 `Z` 时区标记** —— UTC 被当本地时间解析，**整体偏 8 小时**，
+  跨时区日志判断「何时断的」会错（单测抓到）。
+
+### 修复（其他）
+
+- **自重启在非管理员身份下失败** —— `-RunLevel Highest` 被系统拒绝（v7 起的既有缺陷）。
+  现改为两级降级：先试 Highest，失败则不指定 Principal（继承当前权限级别）。
+  修复后 `deploy` 首次能一次走通完整闭环。
+- **`deploy` 备份无限堆积** —— `.bak-<时间戳>` → 固定名 `.bak` + 清理历史（真机 17 → 2 个文件）。
+- **自重启任务 Running 僵尸** —— 清理条件加「`LastRunTime` 早于 1 小时」余量
+  （不能简单清所有 Running：那会连当前 agent 的宿主一起杀）。
+- Windows CI 四连：`URL.pathname` 跨平台路径、`shell: cmd` 套多行 PowerShell、
+  5.1 执行的内联脚本含中文、产物包断言方向反了（`PSK.txt` 从「必含」改「不得含」）。
+
+### 安全 / 隐私
+
+- 源码与测试里的真机常量脱敏（机器名、内网地址）—— 保留「为什么」的教训，去掉具体实况。
+- 能力调用新增审计类型 `session.idle_close`。
+
+### 文档
+
+- `README` 能力总览补三行、数字同步至 51 项能力 / 41 个 MCP 工具 / 269 单测。
+- 新增章节：`gui.await` 属性谓词与组合、状态采样、审计链外部锚定。
+- `docs/SECURITY.md` 新增 §4.7（零信任优先安装）/ §4.8（审计锚定），
+  §5「还没做的」清单**至此全部完成**。
+- `docs/DEVELOPMENT.md` 能力表补全（此前停在 19 项）。
+- `docs/RETROSPECTIVE.md` 加「短板已全部解决」对照表（保留原判断不改写）。
+- `docs/ROADMAP.md` 台账刷新，并新增「真机验证抓到的 8 个真 bug」表。
+
+---
+
+## [v1.6.0] —— 2026-10-07
+
+### 新增
+
+- `gui.await` 等待条件能力（第 43 项）。
+
+### 说明
+
+- 本版**未经真机验证**即发布（当时被控端离线）；相关验证已于 2026-10-09 ~ 10-10 补齐。
+
+## [v1.5.0] —— 2026-10-07
+
+### 新增
+
+- `input.key.press` 参数面扩展：字符串热键（`hotkey: "ctrl+shift+esc"`）、约 50 个预设别名、
+  长按 `hold_ms`、后台定向投递 `route=post` + `target_pid`。
+- 按键表补齐：左右侧修饰键、小键盘（与数字键分开）、OEM 符号键（解锁 `win+d` / `ctrl++` /
+  `win+.`）、IME 键、浏览器键、系统键。
+
+### 说明
+
+- 本版同样**未经真机验证**即发布；2026-10-10 已验证字符串热键与单键投递，其余项待被控端在线后补齐。

README.md

@@ -27,11 +27,148 @@ nodeagent 把一台 Windows 机器的能力**标准化成一组可授权、可
 | **屏幕** | `screen.info` · `screen.capture` · `screen.record` · `screen.find` | 显示器 / 截屏 / **录屏为帧序列** / **元素定位三引擎**（UIA 控件树 → OCR 文字 → **图像模板**） |
 | **窗口** | `window.list` · `window.focus` | 枚举可见窗口（精确矩形）/ 置前聚焦（**Windows + macOS**） |
 | **文件** | `fs.list` · `fs.stat` · `fs.read` · `fs.write` | 列目录 / 元信息 / 分块读 / 原子写 |
-| **输入** | `input.mouse.move` · `input.mouse.click` · `input.mouse.scroll` · `input.mouse.drag` · `input.key.type` · `input.key.press` | 键鼠控制（🔒 **默认禁用**），含**拖拽**与**按键序列/连按** |
+| **输入** | `input.mouse.move` · `input.mouse.click` · `input.mouse.scroll` · `input.mouse.drag` · `input.key.type` · `input.key.press` | 键鼠控制（🔒 **默认禁用**），含**拖拽**、**字符串热键 / 预设 / 长按 / 后台定向投递** |
 | **剪贴板** | `clip.get` · `clip.set` | 读写文本**或图片**（PNG Base64） |
 | **事件订阅** | `event.watch` · `event.unwatch` · `event.list` · `event.poll` | 文件变动 / 进程启停 / 端口开闭，**主动推送**（无需轮询） |
+| **GUI 等待** | `gui.await` | 等条件成立再返回（窗口/元素/进程/文件 × 出现/消失）；支持**属性谓词 `where`** 与 **`any_of` 组合** |
+| **状态采样** | `log.query` · `monitor.start` · `monitor.report` · `monitor.stop` · `monitor.list` · `monitor.delete` | 日志**在被控端侧过滤**（不上传整份）/ 定时采样落盘 + **摘要回看**（断几次、最长断多久、CPU/内存值域） |
+| **审计锚定** | `system.audit.head` · `system.audit.anchor` | 链头可读 + 锚点**追加**落盘，让「有 root 者整链重写」可被发现 |
 
-**36 项能力** · **32 个 MCP 工具** · **114 项单元测试** · **26 项端到端用例**（CI 在真实 Windows 上验证）
+## 快捷键（hotkey）控制 —— v1.5
+
+`input.key.press` 支持 **4 种输入形式**（一次只用一种）：
+
+```bash
+# ① 字符串热键（最常用；分隔符支持 + - 空格，大小写不敏感）
+nodeagent --node win key press "ctrl+shift+esc"
+nodeagent --node win key press "win+d"                     # 显示桌面
+nodeagent --node win key press "alt+tab"                   # 切换应用
+
+# ② 热键序列
+nodeagent --node win key press "ctrl+c"                    # 老形式也兼容：key press ctrl c
+nodeagent --node win invoke input.key.press --args '{"hotkeys":["ctrl+c","ctrl+v"]}'
+
+# ③ 预设语义名（约 50 个，免记键位）
+nodeagent --node win key press copy                        # = ctrl+c
+nodeagent --node win key press task_manager                 # = ctrl+shift+esc
+nodeagent --node win key press volume_mute_toggle           # 媒体键（走 WM_APPCOMMAND）
+
+# ④ 老数组形式
+nodeagent --node win key press ctrl c
+```
+
+**按键覆盖**：字母/数字 · F1–F24 · 左右侧修饰键（`lalt`/`rctrl`/`lwin`…）·
+小键盘（`numpad7`、`numpad_add`…，**与数字键分开**——Excel 靠 NumLock 区分）·
+OEM 符号键（`oem_plus`/`oem_comma`/`oem_period`… → 支持 `win+d`、`ctrl++`、`win+.`）·
+媒体键 · 浏览器键 · IME 键（`convert`/`kana`…）· 系统键（`sleep`/`help`…）
+
+**进阶参数**：
+
+| 参数 | 说明 |
+|---|---|
+| `hold_ms` | 长按：按下后保持 N 毫秒再释放（≤5000） |
+| `route=post` + `target_pid` | **后台定向投递**：向目标进程全部顶层窗口 PostMessage（目标窗口被遮挡/最小化时用）。⚠️ 游戏与部分输入型程序不响应后台键消息 |
+| `target_pid`（默认路由） | 媒体键定向（播放器常建 30+ 辅助窗口，指定 PID 投给该进程全部顶层窗口） |
+
+**预设速查**（完整表见 `packages/protocol/src/hotkeys.ts` 的 `HOTKEY_PRESETS`）：
+
+| 类别 | 预设名 |
+|---|---|
+| 编辑 | `copy` `cut` `paste` `paste_plain` `undo` `redo` `select_all` |
+| 文件 | `save` `save_as` `new` `open` `close_tab` `print` |
+| 窗口 | `switch_app` `task_view` `task_manager` `show_desktop` `minimize_all` `maximize` `snap_left` `snap_right` `rename` `properties` |
+| 系统 | `lock_screen` `run` `explorer` `search` `settings` `clipboard_history` `emoji_picker` `screenshot` |
+| 虚拟桌面 | `new_desktop` `desktop_left` `desktop_right` |
+| 标签/视图 | `new_tab` `next_tab` `reopen_tab` `zoom_in` `zoom_out` `fullscreen` |
+| 媒体 | `music_play_pause` `music_next` `music_prev` `volume_add` `volume_mute_toggle` |
+
+> MCP 侧同名工具为 `na_key`（`action: "press"`），支持同一套参数。
+
+## 等待条件 gui.await —— v1.6
+
+GUI 操作从「按一下→睡几秒→截图碰运气」变成**可断言**流程：
+
+```bash
+# 等界面元素出现（最多 30s）
+nodeagent --node win invoke gui.await --args '{"condition":"control","text":"完成","timeout_ms":30000}'
+# 等它消失
+nodeagent --node win invoke gui.await --args '{"condition":"control","text":"安装中","state":"absent"}'
+# 等窗口 / 进程 / 文件
+nodeagent --node win invoke gui.await --args '{"condition":"window","title":"安装程序","timeout_ms":10000}'
+nodeagent --node win invoke gui.await --args '{"condition":"process","process":"setup.exe"}'
+nodeagent --node win invoke gui.await --args '{"condition":"file","path":"C:\\log.txt"}'
+```
+
+四类条件各自复用 `window.list` / `screen.find` / `process.list` / `fs.stat`，
+平台行为（Windows UIA/OCR、macOS Vision OCR）与那些能力完全一致，**只读低危**。
+轮询期单次异常不视为失败（启动中的程序常短暂报错），超时未命中才带回 `last_error`。
+
+**典型闭环**：`await control(text:"立即安装")` → `mouse.click(x, y)` → `await control(text:"完成", timeout_ms:60000)` → `click` → `await absent(text:"安装中")`。
+
+### 属性谓词与组合（v1.7）
+
+`screen.find` 现在返回 UIA 属性，`gui.await` 可据此等**状态**而不只是「出现」：
+
+```bash
+# 等一个「可用」的按钮（不指定文字）
+nodeagent --node win await --condition control --where '{"enabled":true}'
+# 等值里含「已」的元素
+nodeagent --node win await --condition control --where '{"value":"*已*"}' --timeout 15000
+# 组合：装成功 或 报错，先出现的算
+nodeagent --node win await --any_of '[{"condition":"window","title":"安装完成"},{"condition":"control","text":"错误"}]'
+```
+
+| 属性 | 来源 | 拿不到时 |
+|---|---|---|
+| `enabled` | `IsEnabled` | — |
+| `value` | `ValuePattern` | `null`（**不猜**） |
+| `selected` | `SelectionItemPattern` | `null` |
+| `toggle` | `TogglePattern` | `null` |
+
+> 属性只在 **UIA 引擎**下可读（Windows）。走 OCR/图像模板时 `where` 被忽略并**带回 `note`**，
+> 不会让调用方误以为「按属性过滤过了」。macOS 无 UIA 等价物，`where` 不可用（会明确报错提示用 `text`）。
+
+---
+
+## 状态采样：日志过滤与定时采样 —— v1.8
+
+治**间歇性**问题（代理不通、杀软拦截、端口时开时闭）—— `system.status` 只能看当下快照，
+而 `event.watch` 只解决「有事件时通知」，没有「**持续记录并回看**」。
+
+```bash
+# 日志在被控端侧过滤，只回匹配行（几万行日志也不整份拉回）
+nodeagent --node win log --path "C:\app\app.log" --level ERROR --limit 20
+nodeagent --node win log --path "C:\app\app.log" --pattern "timeout|refused" --tail
+
+# 连续采样 5 分钟，事后回看「断过几次、最长断多久」
+nodeagent --node win invoke monitor.start --args '{"source":"port","target":"127.0.0.1:8765","interval_ms":2000,"id":"probe"}'
+nodeagent --node win monitor report probe
+nodeagent --node win monitor stop probe
+```
+
+采样源四类：`port`（连通性 + 延迟）/ `process`（存活 + PID）/ `command`（退出码 + 首行输出）/
+`metric`（CPU·内存）。样本落 `<数据目录>/monitors/<id>.jsonl`，**摘要直接给结论**。
+
+---
+
+## 审计链外部锚定 —— v25
+
+链内哈希只能发现「改一条」。**有 root 的攻击者可以整链重写** —— 从零重建一份自洽的假日志，
+`audit.verify` 照样通过。外部锚定是唯一能戳破它的手段：把链头记到**链外**。
+
+```bash
+nodeagent --node win audit head --compare           # 看链头 + 与最近锚点比对
+nodeagent --node win audit anchor --note "每日例行"   # 追加一个锚点
+```
+
+**锚点记四元组** `{entries, head_hash, head_ts, rotated_segments}`，不能只记哈希 ——
+日志轮转会丢弃最旧段使条目数下降，只比哈希会把**轮转误判成篡改**。
+锚点文件**只追加**（可覆盖的话，攻击者重写链后再刷新锚点即可抹痕）。
+
+> 真正发挥价值的前提：把锚点文件指向**另一台机器 / 网盘同步目录**。
+> 本机文件被整盘重写时，锚点也随之消失 —— 那就等于没锚。
+
+**51 项能力** · **41 个 MCP 工具** · **269 项单元测试** · **30 项端到端用例** · **9 项 Rust 单测**（CI 在真实 Windows / Linux runner 上验证）
 
 > 关键里程碑：**GUI 语义**（`window.list` + `screen.find`，UIA 找不到自动降级 OCR）
 > 让 AI 从「看得到画面但读不懂界面」变成「按名字取坐标点下去」。
@@ -42,9 +179,15 @@ nodeagent 把一台 Windows 机器的能力**标准化成一组可授权、可
 
 ```bash
 pnpm install
-pnpm build
+pnpm build          # 全部 workspace（protocol/client/agent/cli/mcp/hub + 桌面控制台前端）
+pnpm test:unit      # 单元测试（协议纯函数 / 清单守护 / 编码脚本守卫 / 契约守卫）
+pnpm test:e2e       # 端到端（起真实被控端跑全链路）
+pnpm test:rust      # Rust 控制端客户端（需 cargo）
 ```
 
+> 桌面控制台是 Tauri 应用，**打包**需另进目录：`cd apps/console && pnpm tauri build`。
+> 仅前端产物则 `pnpm build` 已覆盖。
+
 ### 1. Windows 侧（被控端）
 
 **方式 A：安装包（推荐，免装 Node.js）**
@@ -168,11 +311,17 @@ nodeagent pull "C:\big.iso" --out ./big.iso          # 下载（大文件自动
 ## 架构
 
 ```
-┌────────────────────┐                          ┌────────────────────┐
-│  控制端 (macOS)     │ ◄──── JSON-RPC 2.0 ────► │  被控端 (Windows)   │
-│  CLI · MCP Server  │        over WebSocket    │  Agent（开机自启）  │
-└────────────────────┘                          └────────────────────┘
-         │                                                │
+                    ┌──────────────────────────────────────────┐
+                    │  控制端 (macOS / Windows)                │
+                    │  ① 桌面控制台（Tauri 2）  ② CLI  ③ MCP   │
+                    └──────────────────────────────────────────┘
+                                        │
+                         JSON-RPC 2.0 over WebSocket
+                                        │
+                    ┌──────────────────────────────────────────┐
+                    │  被控端 Agent（Windows 常驻 / 开机自启）   │
+                    │  同时也是「本地被控端」，供本机控制台直连   │
+                    └──────────────────────────────────────────┘
          └──────────── 三种链路可选 ──────────────────────┘
           ① 局域网直连     ② UDP 广播自动发现     ③ Hub 中转（跨网段/公网）
 ```
@@ -185,6 +334,35 @@ nodeagent pull "C:\big.iso" --out ./big.iso          # 下载（大文件自动
 | 审计 | JSONL 落盘 + 轮转 + 参数脱敏 + 查询能力 |
 | 传输 | TLS（自签证书可用 `--insecure` 跳过校验，鉴权另有保障） |
 
+### 桌面控制台（Tauri 2）
+
+`apps/console` —— 跨端图形控制台，**主控与被控一体**：本机也可作为被控端，
+由控制台经 loopback 直连（复用同一个 Agent，不做第二套被控端实现）。
+
+技术栈 Tauri 2（Rust 壳 + 系统 WebView）+ Vue 3 + TypeScript + Pinia + Naive UI。
+协议客户端是 `crates/nodeagent-client`（Rust 复刻 `@nodeagent/client`，
+Tauri 侧经 Cargo path 依赖），**不引入第二套协议实现**。
+
+| 页面 | 能力 |
+|---|---|
+| 设备管理 | 连接/断开、保存多台设备、能力清单与握手元信息、实时日志 |
+| 状态总览 | CPU / 内存 / 磁盘 / 网卡，3s 轮询 |
+| 终端 | `system.shell.exec`（可设超时）、历史回放 |
+| 进程与服务 | 进程表（CPU/内存/已运行）+ Windows 服务表 |
+| 软件 | `app.list` / `app.install`（winget 静默安装，超时放大到 10 分钟） |
+| 文件 | 浏览 / 预览 / 写入（走分块能力，天然支持大文件） |
+| 审计 | `system.audit.list` 筛选 + `system.audit.verify` 链完整性校验 + 导出 JSONL |
+
+```bash
+pnpm -r build                       # 含 console 前端
+cd apps/console && pnpm tauri dev   # 开发态（起 Vite + Tauri 窗口）
+cd apps/console && pnpm tauri build # 打包（macOS 实测 .app ≈ 6.8 MiB）
+```
+
+⚠️ 平台差异：`app.*` 与 `system.service.list` **仅在被控端为 Windows 时可用**，
+非 Windows 被控端会返回 `E_UNSUPPORTED_PLATFORM`。控制台连接后会探测
+`system.info.os` 并**事前禁用**这些入口，而不是发出注定失败的请求。
+
 ## 安全模型
 
 三层防护，逐层收窄权限：
@@ -463,11 +641,13 @@ nodeagent/
 - [`docs/SECURITY.md`](docs/SECURITY.md) —— **安全模型与加固指南**（钥匙=root、证书指纹钉住、网段白名单、应急处置）
 - [`docs/VERSIONING.md`](docs/VERSIONING.md) —— **版本与兼容性契约**（升级顺序、什么算破坏性、发版流程、更新方式）
 - [`docs/REMOTE-LIMITS.md`](docs/REMOTE-LIMITS.md) —— 远程能力边界与真实故障案例（含杀软误拦）
+- [`CHANGELOG.md`](CHANGELOG.md) —— **变更日志**（未发布版本的内容汇总 / 历史版本）
+- [`docs/ROADMAP.md`](docs/ROADMAP.md) —— **当前进度盘点与下一步路线**（2026-10-07 基线：待办收尾 / 语义可断言 / 状态采样 / 安全残余）
 
 - [产品需求文档（PRD）](./PRD.md)
 - [开发文档（DEVELOPMENT）](./docs/DEVELOPMENT.md) —— 协议细节、能力 schema、安全模型、各端实现指南
 - [**跨机接管的边界与局限**](./docs/REMOTE-LIMITS.md) —— 哪些问题能远程修、哪些必须人工，附真实故障诊断案例
-- [**实战复盘：短板与改进优先级**](./docs/RETROSPECTIVE.md) —— 基于真机使用的短板分析（GUI 语义 / 编码 / 自愈 / 可观测性）
+- [**实战复盘：短板与改进优先级**](./docs/RETROSPECTIVE.md) —— 基于真机使用的短板分析（GUI 语义 / 编码 / 自愈 / 可观测性）。**写于 2026-09-28（19 项能力时），多数 P0/P1 已解决 —— 最新状态见 [ROADMAP](./docs/ROADMAP.md) §3 对照表**
 
 ## 关键决策
 

apps/agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodeagent/agent",
-  "version": "1.4.2",
+  "version": "2.0.0",
   "private": true,
   "type": "module",
   "main": "./dist/index.js",

apps/agent/src/audit.ts

@@ -17,7 +17,9 @@ export type AuditType =
   /** v21：来源不在 allow_from 被拒 */
   | 'net.deny'
   /** v19：agent 自更新（拉取式） */
-  | 'agent.update';
+  | 'agent.update'
+  /** v23：连接空闲被主动断开 */
+  | 'session.idle_close';
 
 /** 一条审计记录（JSONL 单行）。 */
 export interface AuditEntry {
@@ -332,3 +334,168 @@ export function readAudit(query: AuditQuery = {}): { entries: AuditEntry[]; tota
   collected.sort((a, b) => a.ts - b.ts);
   return { entries: collected.slice(-limit), total, file: p };
 }
+
+
+// ---------------- v25 审计链外部锚定 ----------------
+//
+// ## 为什么需要
+// 审计链的哈希使**链内**篡改可被发现（改一条就要重算其后全部）。但「有 root 的攻击者」
+// 可以**整链重写**：从零重建一份自洽的假日志，链校验照样通过。
+// 外部锚定就是打破这一点：定期把**链头哈希 + 条目数**记到链外的独立位置
+// （另一台机器 / 网盘 / U 盘）。事后比对时，若「当前链在某锚点之后的部分对不上」，
+// 说明这段被重写过 —— 攻击者无法回到过去改掉已经落到别处的锚点。
+//
+// ## 记什么（关键：不能只记哈希）
+// 轮转会丢弃最旧的段，所以条目数会**下降**。只记 head_hash 会导致轮转后被误判为篡改。
+// 故锚点记 {entries, head_hash, head_ts, rotated_segments} 四元组，
+// 比对时先按"轮转了几段"对齐，再判断尾部是否一致。
+
+export interface AuditHead {
+  /** 当前链可见条目数（含轮转段） */
+  entries: number;
+  /** 链头哈希（末条的 hash）—— 这是要外部留存的核心值 */
+  head_hash: string | null;
+  /** 末条时间戳 */
+  head_ts: number | null;
+  /** 存在的轮转段数（.log.1 … .log.20） */
+  rotated_segments: number;
+  file: string;
+  file_bytes: number;
+  computed_at: number;
+}
+
+/** 计算当前审计链的头部信息（只读）。 */
+export function computeAuditHead(): AuditHead {
+  const p = auditFilePath();
+  let rotated = 0;
+  for (let i = 1; i <= 20; i += 1) if (existsSync(`${p}.${i}`)) rotated += 1;
+
+  const entries = readAuditAll();
+  const last = entries.length > 0 ? entries[entries.length - 1]! : null;
+  let fileBytes = 0;
+  try {
+    fileBytes = statSync(p).size;
+  } catch {
+    /* 文件可能尚不存在（还没写过审计） */
+  }
+  return {
+    entries: entries.length,
+    head_hash: last?.hash ?? null,
+    head_ts: last?.ts ?? null,
+    rotated_segments: rotated,
+    file: p,
+    file_bytes: fileBytes,
+    computed_at: Date.now(),
+  };
+}
+
+export interface AnchorRecord {
+  ts: number;
+  entries: number;
+  head_hash: string | null;
+  head_ts: number | null;
+  rotated_segments: number;
+  note?: string;
+}
+
+/** 锚点文件路径（默认与审计同目录）。 */
+export function anchorFilePath(custom?: string): string {
+  return custom && custom.trim().length > 0 ? custom.trim() : join(agentDir(), 'audit-anchors.jsonl');
+}
+
+/** 把当前链头**追加**到锚点文件（追加式：历史锚点不可被后续覆盖）。 */
+export function anchorAudit(opts: { path?: string; note?: string } = {}): {
+  file: string;
+  record: AnchorRecord;
+  total_lines: number;
+} {
+  const head = computeAuditHead();
+  const file = anchorFilePath(opts.path);
+  const rec: AnchorRecord = {
+    ts: Date.now(),
+    entries: head.entries,
+    head_hash: head.head_hash,
+    head_ts: head.head_ts,
+    rotated_segments: head.rotated_segments,
+    ...(opts.note ? { note: opts.note } : {}),
+  };
+  appendFileSync(file, `${JSON.stringify(rec)}\n`, 'utf8');
+  let total = 0;
+  try {
+    total = readFileSync(file, 'utf8').split('\n').filter((l) => l.trim().length > 0).length;
+  } catch {
+    total = 1;
+  }
+  return { file, record: rec, total_lines: total };
+}
+
+export interface AnchorComparison {
+  ok: boolean;
+  anchors_checked: number;
+  latest?: AnchorRecord;
+  verdict: string;
+  detail?: Record<string, unknown>;
+}
+
+/**
+ * 与最近一条锚点比对，判断当前链是否与锚定时刻自洽。
+ *
+ * 判定逻辑（三条）：
+ *  - 条目数应 **≥** 锚点记录（只增不减；减少只能由轮转解释，轮转会让 rotated_segments 变大）
+ *  - 若条目数与轮转段数都没变 → 链头哈希必须**完全一致**
+ *  - 若已轮转（段数变大）→ 只校验"当前 entries ≥ 锚点 entries"，并提示需人工核对
+ */
+export function compareWithAnchors(customPath?: string): AnchorComparison {
+  const file = anchorFilePath(customPath);
+  if (!existsSync(file)) {
+    return { ok: true, anchors_checked: 0, verdict: '尚无锚点：请先调用 system.audit.anchor 建立外部锚点' };
+  }
+  let anchors: AnchorRecord[] = [];
+  try {
+    anchors = readFileSync(file, 'utf8')
+      .split('\n')
+      .filter((l) => l.trim().length > 0)
+      .map((l) => JSON.parse(l) as AnchorRecord);
+  } catch {
+    return { ok: false, anchors_checked: 0, verdict: '锚点文件损坏，无法比对' };
+  }
+  if (anchors.length === 0) {
+    return { ok: true, anchors_checked: 0, verdict: '锚点文件为空' };
+  }
+  const latest = anchors[anchors.length - 1]!;
+  const head = computeAuditHead();
+
+  if (head.entries < latest.entries && head.rotated_segments <= latest.rotated_segments) {
+    return {
+      ok: false,
+      anchors_checked: anchors.length,
+      latest,
+      verdict: '**疑似整链重写/回滚**：当前条目数少于锚点，且没有发生轮转来解释',
+      detail: { anchored_entries: latest.entries, current_entries: head.entries, anchored_hash: latest.head_hash, current_hash: head.head_hash },
+    };
+  }
+  if (head.rotated_segments === latest.rotated_segments && head.entries === latest.entries) {
+    if (head.head_hash !== latest.head_hash) {
+      return {
+        ok: false,
+        anchors_checked: anchors.length,
+        latest,
+        verdict: '**链头哈希与锚点不一致**（条目数相同却哈希不同 → 该段被重写）',
+        detail: { anchored_hash: latest.head_hash, current_hash: head.head_hash, entries: head.entries },
+      };
+    }
+    return { ok: true, anchors_checked: anchors.length, latest, verdict: '与锚点完全一致（条目数、轮转段数、链头哈希三者相符）' };
+  }
+  return {
+    ok: true,
+    anchors_checked: anchors.length,
+    latest,
+    // ⚠️ 注意：锚定动作**自身**也会被记入审计（server 层统一记录所有 invoke），
+    // 所以「刚锚定就比对」几乎必然看到"已增长"——这是正常现象，不是篡改。
+    // 想看到"完全一致"，需在同一时刻不再产生新审计（实际很难，属预期）。
+    verdict:
+      '链已增长（或发生轮转）—— 锚点仍在链上，无需人工核对到该锚点为止的部分。' +
+      '（刚锚定就比对通常显示"已增长"，因为锚定调用自身也会写一条审计。）',
+    detail: { anchored_entries: latest.entries, current_entries: head.entries, rotated_delta: head.rotated_segments - latest.rotated_segments, anchored_hash: latest.head_hash, current_hash: head.head_hash },
+  };
+}

apps/agent/src/capabilities/await.ts

@@ -0,0 +1,271 @@
+/**
+ * gui.await —— 等待条件成立（v1.6）。
+ *
+ * ## 为什么需要它（复盘三大短板之「语义」）
+ * 原来的 GUI 操作是**盲试**：按一下、截个图、看看有没有变化，不行再试。
+ * 问题不是"找不到元素"（screen.find 已解决），而是**操作之后无法断言界面到了预期状态**。
+ * 有了本能力，"点了安装 → 等待『完成』按钮出现" 从"睡 3 秒碰运气"变成**可验证的等待**：
+ *
+ *   await control(text:"完成", timeout:30s) → click(found) → await absent(text:"安装中")
+ *
+ * ## 实现要点
+ * 不写任何新的平台探测代码 —— 四个条件全部**复用既有能力**（window.list /
+ * screen.find / process.list / fs.stat），因此 Windows/macOS 行为与它们完全一致。
+ * 轮询期间异常一律视为"尚未命中"并记录 last_error，避免单次抖动整句失败；
+ * 但超时未命中时会把它带回，方便判断是"真的没有"还是"每次都在报错"。
+ */
+
+import { CapabilityError, ErrorCodes } from '@nodeagent/protocol';
+import { windowList } from './window.js';
+import { screenFind } from './window.js';
+import { processList } from './system.js';
+import { fsStat } from './fs.js';
+
+type Args = Record<string, unknown>;
+
+type Condition = 'window' | 'control' | 'process' | 'file';
+
+const CONDITIONS: readonly Condition[] = ['window', 'control', 'process', 'file'];
+
+/** 判断一次底层调用是否"命中"（兼容各能力不同的返回形态）。 */
+function isHit(result: unknown): boolean {
+  if (result === null || result === undefined) return false;
+  if (typeof result === 'boolean') return result;
+  const r = result as Record<string, unknown>;
+  if (r['found'] === true) return true;
+  if (r['exists'] === true) return true;
+  for (const key of ['windows', 'processes', 'matches', 'elements']) {
+    const arr = r[key];
+    if (Array.isArray(arr) && arr.length > 0) return true;
+  }
+  if (Array.isArray(result) && result.length > 0) return true;
+  return false;
+}
+
+/** 按条件组装底层调用的参数（只透传该条件支持的字段）。 */
+function buildInnerArgs(condition: Condition, args: Args): Args {
+  const num = (k: string): number | undefined => {
+    const v = args[k];
+    return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+  };
+  switch (condition) {
+    case 'window': {
+      const inner: Args = {};
+      const title = (args['title'] as string | undefined) ?? (args['pattern'] as string | undefined);
+      if (title) inner['title_pattern'] = title;
+      const limit = num('limit');
+      if (limit !== undefined) inner['limit'] = limit;
+      return inner;
+    }
+    case 'control': {
+      // 透传 screen.find 的全部相关参数（method=image 时也一样走轮询）
+      const inner: Args = {};
+      for (const k of ['text', 'window', 'control_type', 'method', 'template', 'limit', 'timeout_ms']) {
+        if (args[k] !== undefined) inner[k] = args[k];
+      }
+      // v1.7：属性谓词（仅 UIA 引擎生效）。有 where 时允许不传 text ——
+      // 「等一个 enabled 的按钮」比「等一个叫某名字的按钮」更贴近真实意图。
+      const where = args['where'];
+      if (where !== undefined) {
+        if (typeof where !== 'object' || where === null || Array.isArray(where)) {
+          throw new CapabilityError(ErrorCodes.PARAM_INVALID, 'where 必须是对象，如 {"enabled":true}');
+        }
+        const allowed = ['enabled', 'selected', 'value', 'toggle'];
+        const bad = Object.keys(where as Record<string, unknown>).filter((k) => !allowed.includes(k));
+        if (bad.length > 0) {
+          throw new CapabilityError(ErrorCodes.PARAM_INVALID, `where 只支持 ${allowed.join('/')}`, { got: bad });
+        }
+        inner['where'] = where;
+      }
+      if (inner['text'] === undefined && where === undefined) {
+        throw new CapabilityError(ErrorCodes.PARAM_INVALID, 'control 条件需要 text 或 where 之一');
+      }
+      return inner;
+    }
+    case 'process': {
+      const inner: Args = {};
+      const name = args['process'] as string | undefined;
+      if (name) inner['filter'] = { name_pattern: name };
+      const limit = num('limit');
+      if (limit !== undefined) inner['limit'] = limit;
+      return inner;
+    }
+    case 'file': {
+      const p = args['path'] as string | undefined;
+      if (!p) {
+        throw new CapabilityError(ErrorCodes.PARAM_INVALID, 'condition=file 需要 path', {
+          hint: '如 {"condition":"file","path":"C:\\\\Windows\\\\Temp\\\\setup.log"}',
+        });
+      }
+      return { path: p };
+    }
+  }
+}
+
+/** 条件 → 底层能力（本进程内直接调用，省去 RPC 往返开销）。 */
+function innerProbe(condition: Condition): (args: Args) => Promise<unknown> {
+  switch (condition) {
+    case 'window':
+      return (a) => windowList(a);
+    case 'control':
+      return (a) => screenFind(a);
+    case 'process':
+      return (a) => processList(a);
+    case 'file':
+      return (a) => fsStat(a);
+  }
+}
+
+/**
+ * v1.7 组合条件：`any_of: [ {...}, {...} ]`，任一命中原句即算命中。
+ *
+ * 为什么只做 any_of 不做 and/or/not  generalize：真实场景里"弹窗出现 **且**
+ * 其中某按钮 enabled"用 any_of(弹窗) + where(按钮 enabled) 两步就能表达，
+ * 而通用布尔表达式会把 schema 与求值都复杂化，收益不成比例。
+ * 若真需要"两个都必须成立"，上层连调两次 await 更直白。
+ */
+function buildAnyOf(args: Args): Array<{ condition: Condition; inner: Args; label: string }> {
+  const raw = args['any_of'];
+  if (!Array.isArray(raw) || raw.length === 0) {
+    throw new CapabilityError(ErrorCodes.PARAM_INVALID, 'any_of 需为非空数组，每项为一个条件对象');
+  }
+  if (raw.length > 8) {
+    throw new CapabilityError(ErrorCodes.PARAM_INVALID, 'any_of 最多 8 个条件', { got: raw.length });
+  }
+  return raw.map((item, i) => {
+    const obj = item as Record<string, unknown>;
+    const condition = obj['condition'] as Condition | undefined;
+    if (!condition || !CONDITIONS.includes(condition)) {
+      throw new CapabilityError(ErrorCodes.PARAM_INVALID, `any_of[${i}].condition 不支持: ${String(condition)}`, {
+        allowed: CONDITIONS,
+      });
+    }
+    // 每项复用主条件的构造逻辑（同等校验），顶层键名直接透传
+    const inner = buildInnerArgs(condition, obj);
+    const label =
+      condition === 'control' ? String(obj['text'] ?? JSON.stringify(obj['where'] ?? ''))
+      : condition === 'window' ? String(obj['title'] ?? obj['pattern'] ?? '')
+      : condition === 'process' ? String(obj['process'] ?? '')
+      : String(obj['path'] ?? '');
+    return { condition, inner, label };
+  });
+}
+
+export async function guiAwait(args: Args): Promise<unknown> {
+  // v1.7：有 any_of 时**不要求**顶层 condition（语义就是"这组条件任一命中"），
+  // 校验顺序也因此调整为 any_of 先行 —— 否则会先撞上"condition 缺失"的报错。
+  const condition = args['condition'] as Condition | undefined;
+  if (!args['any_of'] && (!condition || !CONDITIONS.includes(condition))) {
+    throw new CapabilityError(ErrorCodes.PARAM_INVALID, `不支持的 condition: ${String(condition)}`, {
+      allowed: CONDITIONS,
+      hint: 'window=等窗口出现/消失；control=等界面元素；process=等进程；file=等文件',
+    });
+  }
+  const state = (args['state'] as string | undefined) ?? 'present';
+  if (state !== 'present' && state !== 'absent') {
+    throw new CapabilityError(ErrorCodes.PARAM_INVALID, `不支持的 state: ${state}`, {
+      allowed: ['present', 'absent'],
+    });
+  }
+  const timeoutMs = Math.max(0, Math.min(60_000, (args['timeout_ms'] as number | undefined) ?? 5000));
+  const intervalMs = Math.max(50, Math.min(5000, (args['interval_ms'] as number | undefined) ?? 400));
+
+  const startedAt = Date.now();
+  let attempts = 0;
+  let lastHit = false;
+  let lastError: string | null = null;
+
+  // v1.7：组合条件走单独路径（任一命中即算），失败语义与单条完全一致
+  const anyOf = args['any_of'] !== undefined ? buildAnyOf(args) : null;
+  if (anyOf) {
+    for (;;) {
+      attempts += 1;
+      let hitLabel: string | null = null;
+      lastError = null;
+      for (const c of anyOf) {
+        try {
+          const r = await innerProbe(c.condition)(c.inner);
+          if (isHit(r)) { hitLabel = c.label; break; }
+        } catch (err) {
+          lastError = err instanceof Error ? err.message : String(err);
+        }
+      }
+      const satisfied = (state === 'present' ? hitLabel !== null : hitLabel === null) as boolean;
+      if (satisfied) {
+        return {
+          satisfied: true,
+          condition: 'any_of',
+          state,
+          elapsed_ms: Date.now() - startedAt,
+          attempts,
+          last_seen: state,
+          hit: hitLabel ?? undefined,
+          note: hitLabel ? `命中：${hitLabel}` : '所有子条件均已消失',
+        };
+      }
+      if (Date.now() - startedAt >= timeoutMs) {
+        return {
+          satisfied: false,
+          condition: 'any_of',
+          state,
+          elapsed_ms: Date.now() - startedAt,
+          attempts,
+          last_seen: lastHit ? 'present' : 'absent',
+          last_error: lastError ?? undefined,
+          note: `等待 ${timeoutMs}ms，${anyOf.length} 个条件均未${state === 'present' ? '命中' : '消失'}`,
+        };
+      }
+      await new Promise((r) => setTimeout(r, intervalMs));
+    }
+  }
+
+  // 能走到这里说明没走 any_of 分支，而进入函数时的校验已保证 condition 合法；
+  // TS 无法跨分支收窄，这里显式断言一次（buildInnerArgs / innerProbe 内部还会各自校验）。
+  const single = condition as Condition;
+  const innerArgs = buildInnerArgs(single, args);
+  const probe = innerProbe(single);
+
+  for (;;) {
+    attempts += 1;
+    try {
+      const result = await probe(innerArgs);
+      lastHit = isHit(result);
+      lastError = null;
+    } catch (err) {
+      // 轮询期异常不代表条件不成立（可能正忙于启动）——记下再试
+      lastError = err instanceof Error ? err.message : String(err);
+      lastHit = false;
+    }
+    const satisfied = state === 'present' ? lastHit : !lastHit;
+    if (satisfied) {
+      return {
+        satisfied: true,
+        condition,
+        state,
+        elapsed_ms: Date.now() - startedAt,
+        attempts,
+        last_seen: state,
+        note:
+          state === 'absent'
+            ? '条件已消失（连续一次未命中即视为消失；如需更稳可加大 interval_ms）'
+            : undefined,
+      };
+    }
+    if (Date.now() - startedAt >= timeoutMs) {
+      return {
+        satisfied: false,
+        condition,
+        state,
+        elapsed_ms: Date.now() - startedAt,
+        attempts,
+        last_seen: lastHit ? 'present' : 'absent',
+        last_error: lastError ?? undefined,
+        note:
+          state === 'present'
+            ? `等待 ${timeoutMs}ms 仍未出现${lastError ? `，期间持续报错：${lastError.slice(0, 160)}` : ''}`
+            : `等待 ${timeoutMs}ms 仍未消失${lastError ? `，期间持续报错：${lastError.slice(0, 160)}` : ''}`,
+      };
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+}

apps/agent/src/capabilities/darwin.ts

@@ -317,7 +317,15 @@ async function ensureOcrBin(): Promise<string> {
 export async function macScreenFind(args: Args): Promise<unknown> {
   assertDarwin('screen.find');
   const text = args['text'] as string;
-  if (!text) throw new CapabilityError(ErrorCodes.PARAM_INVALID, 'text 不能为空');
+  if (!text) {
+    // macOS 走 Vision OCR，**没有控件属性可读** —— where-only 无法满足，
+    // 明确说清原因，别让调用方以为是参数写错。
+    throw new CapabilityError(
+      ErrorCodes.UNSUPPORTED_PLATFORM,
+      'macOS 无 UIA 等价物：where 属性过滤不可用，请提供 text（OCR 按文字查找）',
+      { platform: 'darwin', engine: 'ocr' },
+    );
+  }
   const limit = (args['limit'] as number | undefined) ?? 20;
   const waitMs = Math.max(0, Math.min(30_000, (args['wait_ms'] as number | undefined) ?? 0));
   const intervalMs = Math.max(100, Math.min(2000, (args['interval_ms'] as number | undefined) ?? 400));

apps/agent/src/capabilities/fs.ts

@@ -29,7 +29,7 @@ export function setFsRoots(roots: string[] | undefined): void {
   allowedRoots = (roots ?? []).map((r) => resolve(r));
 }
 
-function guardPath(input: string): string {
+export function guardPath(input: string): string {
   if (typeof input !== 'string' || input.length === 0) {
     throw new CapabilityError(ErrorCodes.PARAM_INVALID, 'path 不能为空');
   }

apps/agent/src/capabilities/index.ts

@@ -1,6 +1,6 @@
 import { CapabilityNames } from '@nodeagent/protocol';
 import type { AgentConfig } from '../config.js';
-import { systemInfo, systemStatus, processList, serviceList, shellExec, auditList, auditVerify, metricsReport, agentRestart } from './system.js';
+import { systemInfo, systemStatus, processList, serviceList, shellExec, auditList, auditVerify, auditHead, auditAnchor, metricsReport, agentRestart } from './system.js';
 import { appList, appInstall } from './app.js';
 import { screenInfo, screenCapture } from './screen.js';
 import { windowList, windowFocus, screenFind } from './window.js';
@@ -13,6 +13,8 @@ import { audioGet, audioSet } from './audio.js';
 import { agentUpdate } from './selfupdate.js';
 import { mouseMove, mouseClick, mouseScroll, mouseDrag, keyType, keyPress, setInputPolicy } from './input.js';
 import { fsList, fsStat, fsRead, fsWrite, setFsRoots } from './fs.js';
+import { guiAwait } from './await.js';
+import { logQuery, monitorStart, monitorReport, monitorStop, monitorList, monitorDelete } from './monitor.js';
 
 export interface HandlerContext {
   /** 连接标识（事件订阅归属 / 断开清理） */
@@ -52,10 +54,22 @@ export function createCapabilityRegistry(cfg: AgentConfig): Record<string, Capab
     [CapabilityNames.MouseDrag]: mouseDrag,
     [CapabilityNames.KeyType]: keyType,
     [CapabilityNames.KeyPress]: keyPress,
+    // v1.6 等待条件（把盲试变为可断言）
+    [CapabilityNames.GuiAwait]: guiAwait,
+    // v1.8 状态采样（方向二）
+    [CapabilityNames.LogQuery]: logQuery,
+    [CapabilityNames.MonitorStart]: monitorStart,
+    [CapabilityNames.MonitorReport]: monitorReport,
+    [CapabilityNames.MonitorStop]: monitorStop,
+    [CapabilityNames.MonitorList]: monitorList,
+    [CapabilityNames.MonitorDelete]: monitorDelete,
     // v3+ 审计
     [CapabilityNames.AuditList]: auditList,
     // v11 审计防篡改
     [CapabilityNames.AuditVerify]: auditVerify,
+    // v25 审计链外部锚定（防整链重写）
+    [CapabilityNames.AuditHead]: auditHead,
+    [CapabilityNames.AuditAnchor]: auditAnchor,
     // v13 成功指标
     [CapabilityNames.Metrics]: metricsReport,
     // v5 文件传输

apps/agent/src/capabilities/input-script.ts

@@ -0,0 +1,200 @@
+/**
+ * 输入注入的 **PowerShell 脚本生成**（纯函数，无副作用 —— 便于单测）。
+ *
+ * 独立成模块的原因：脚本生成逻辑（顺序、逆序释放、hold 插入、PostMessage 路由）
+ * 以往只能靠真机验证；而它恰好是最容易写错（一行顺序错 → 组合键失效）的部分。
+ * 现在由单测逐行断言，真机只需验证"最终是否生效"。
+ */
+
+import { CapabilityError, ErrorCodes } from '@nodeagent/protocol';
+
+/** 键名 → 虚拟键码（字母/数字走 ASCII 映射，其余查表白名单）。 */
+export const VK_MAP: Record<string, number> = {
+  ctrl: 0x11, control: 0x11, shift: 0x10, alt: 0x12, win: 0x5b, meta: 0x5b,
+  enter: 0x0d, return: 0x0d, tab: 0x09, esc: 0x1b, escape: 0x1b, space: 0x20,
+  backspace: 0x08, delete: 0x2e, del: 0x2e, insert: 0x2d, ins: 0x2d,
+  up: 0x26, down: 0x28, left: 0x25, right: 0x27,
+  home: 0x24, end: 0x23, pageup: 0x21, pagedown: 0x22,
+  capslock: 0x14, printscreen: 0x2c,
+  // 系统/编辑键补充
+  pause: 0x13, break: 0x13,
+  apps: 0x5d, menu: 0x5d,
+  f1: 0x70, f2: 0x71, f3: 0x72, f4: 0x73, f5: 0x74, f6: 0x75,
+  f7: 0x76, f8: 0x77, f9: 0x78, f10: 0x79, f11: 0x7a, f12: 0x7b,
+  f13: 0x7c, f14: 0x7d, f15: 0x7e, f16: 0x7f, f17: 0x80, f18: 0x81,
+  f19: 0x82, f20: 0x83, f21: 0x84, f22: 0x85, f23: 0x86, f24: 0x87,
+
+  // 媒体键（0xA6-0xB7 区段）—— 2026-10-05 补
+  //
+  // 为何必要：远程控媒体播放器（音乐 / 视频 / 浏览器内视频）时，
+  // 若软件热键不可用（精简模式常不注册全局热键），系统媒体键是唯一
+  // 与「窗口是否可见/被遮挡」无关的通道 —— 窗口最小化、被游戏全屏盖住时
+  // 依然有效。实测：精简模式的播放器被全屏游戏遮挡时，媒体键仍能控制。
+  media_play: 0xb3, media_pause: 0xb3, media_play_pause: 0xb3, play_pause: 0xb3,
+  media_stop: 0xb2, stop: 0xb2,
+  media_prev: 0xb1, media_previous: 0xb1, prev_track: 0xb1, prev: 0xb1,
+  media_next: 0xb0, next_track: 0xb0, next: 0xb0,
+  media_fast_forward: 0xb4, fast_forward: 0xb4,
+  media_rewind: 0xb7, rewind: 0xb7,
+  media_eject: 0xb2,
+  volume_mute: 0xad, mute: 0xad,
+  volume_down: 0xae,
+  volume_up: 0xaf,
+
+  browser_back: 0xa6, browser_forward: 0xa7, browser_refresh: 0xa8, browser_stop: 0xa9, browser_search: 0xaa,
+  launch_mail: 0xb4, launch_media: 0xb5, launch_app1: 0xb6, launch_app2: 0xb7,
+  browser_favorites: 0xab, browser_home: 0xac,
+
+  // ---- 左右侧修饰键（v1.5）----
+  // 游戏/部分应用区分左右（如游戏中把 LAlt 设为跑步、RAlt 设为瞄准），故不能只给一个 alt。
+  lctrl: 0xa2, rctrl: 0xa3, lshift: 0xa0, rshift: 0xa1,
+  lalt: 0xa4, ralt: 0xa5, lwin: 0x5b, rwin: 0x5c,
+  super: 0x5b, cmd: 0x5b, left_cmd: 0x5b, right_cmd: 0x5c,
+
+  // ---- 小键盘（v1.5）----
+  // numpadN 与数字 N 分开：Excel 等程序靠 NumLock 状态区分二者行为，合成一个会坏掉快捷键。
+  numpad0: 0x60, numpad1: 0x61, numpad2: 0x62, numpad3: 0x63, numpad4: 0x64,
+  numpad5: 0x65, numpad6: 0x66, numpad7: 0x67, numpad8: 0x68, numpad9: 0x69,
+  numpad_multiply: 0x6a, numpad_add: 0x6b, numpad_subtract: 0x6d, numpad_decimal: 0x6e, numpad_divide: 0x6f,
+  numlock: 0x90, scrolllock: 0x91,
+  numpad_enter: 0x0d,
+
+  // ---- OEM 符号键（v1.5，美式布局 VK 码）----
+  // 必备理由：大量系统/应用快捷键就是"修饰键 + 符号键"（win+d 显示桌面、win+, 速览、
+  // ctrl++ 放大、ctrl+- 缩小、win+. 表情面板），此前只能靠字母数字，覆盖不到。
+  oem_1: 0xba,   // : ;
+  oem_2: 0xbf,   // / ?
+  oem_3: 0xc0,   // ` ~
+  oem_4: 0xdb,   // [ {
+  oem_5: 0xdc,   // \ |
+  oem_6: 0xdd,   // ] }
+  oem_7: 0xde,   // ' "
+  oem_8: 0xdf,
+  oem_minus: 0xbd, // - _
+  oem_plus: 0xbb,  // + =
+  oem_comma: 0xbc, // , <
+  oem_period: 0xbe,// . >
+
+  // ---- 系统/IME 杂项（v1.5）----
+  sleep: 0x5f, help: 0x2f, select: 0x29, execute: 0x2b, clear: 0x0c,
+  separator: 0x6c, oem_clear: 0xfe,
+  kana: 0x15, hangul: 0x15, kanji: 0x19, hanja: 0x19,
+  convert: 0x1c, nonconvert: 0x1d, accept: 0x1e, modechange: 0x1f,
+};
+
+/** 键名 → 虚拟键码。 */
+export function toVk(key: string): number {
+  const k = key.trim().toLowerCase();
+  if (VK_MAP[k] !== undefined) return VK_MAP[k]!;
+  if (/^[a-z]$/.test(k)) return k.toUpperCase().charCodeAt(0);
+  if (/^[0-9]$/.test(k)) return k.charCodeAt(0);
+  throw new CapabilityError(ErrorCodes.PARAM_INVALID, `不支持的按键: ${key}`, {
+    supported: [...Object.keys(VK_MAP), 'a-z', '0-9'],
+  });
+}
+
+/**
+ * 媒体键名 → APPCOMMAND 取值。
+ *
+ * 取值见 Windows `APPCOMMAND_*` 常量。整条序列都是媒体键时改走 WM_APPCOMMAND
+ * 投递（而非 SendInput 注入 VK）—— 前者能定向到指定进程且不受窗口遮挡影响。
+ *
+ * ⚠️ 音量键（volume_mute / volume_up / volume_down）**不在此表**：
+ * WM_APPCOMMAND 的 lParam 低 16 位按 device 段解释，VOLUME_DOWN 与 PAUSE 的裸值相同（都是 1），
+ * 放进表里会与 PAUSE 撞车。音量键走 VK 注入（0xAD-0xAF）更可靠 —— 系统会自行映射为
+ * APPCOMMAND_VOLUME_*，故此处刻意不收录音量键，避免 device-bit 歧义。
+ */
+export const MEDIA_COMMANDS: Record<string, number> = {
+  media_play: 14, play: 14,
+  media_pause: 1, pause: 1,
+  media_play_pause: 12, play_pause: 12,
+  media_stop: 15, stop: 15,
+  media_prev: 6, media_previous: 6, prev_track: 6, prev: 6,
+  media_next: 7, next_track: 7, next: 7,
+  media_fast_forward: 3, fast_forward: 3,
+  media_rewind: 4, rewind: 4,
+  media_close: 10, close: 10,
+};
+
+export interface PressBodyOptions {
+  /** 序列中相邻和弦之间的间隔毫秒 */
+  gapMs: number;
+  /** 按下后保持毫秒数（长按） */
+  holdMs: number;
+  /** route=post 时的目标进程 PID */
+  targetPid: number;
+  /** 投放路由 */
+  route: 'foreground' | 'post';
+}
+
+/** 判断整条序列是否都是媒体键。 */
+export function isAllMedia(chords: string[][]): boolean {
+  return (
+    chords.length > 0 &&
+    chords.every((ch) => ch.length === 1 && MEDIA_COMMANDS[ch[0]!.trim().toLowerCase()] !== undefined)
+  );
+}
+
+/**
+ * 生成媒体键（WM_APPCOMMAND）投放脚本。
+ * targetPid=0 → HWND_BROADCAST 广播；否则定向该进程全部顶层窗口。
+ */
+export function buildMediaBody(chords: string[][], opts: PressBodyOptions): string[] {
+  const body: string[] = [];
+  const pid = Math.max(0, Math.trunc(opts.targetPid));
+  for (let i = 0; i < chords.length; i += 1) {
+    const cmd = MEDIA_COMMANDS[chords[i]![0]!.trim().toLowerCase()]!;
+    body.push(`[NAInput]::MediaCommand(${cmd}, ${pid})`);
+    if (i < chords.length - 1 && opts.gapMs > 0) {
+      body.push(`Start-Sleep -Milliseconds ${opts.gapMs}`);
+    }
+  }
+  return body;
+}
+
+/**
+ * 生成前台注入（SendInput Vk）脚本。
+ *
+ * 顺序至关重要：按下按给定顺序、**释放逆序** —— 否则 Windows 组合键状态机会淆
+ * （例如 ctrl+c 若先释放 ctrl，绝大多数程序收不到"带 ctrl 的 c"）。
+ */
+export function buildForegroundBody(chords: string[][], opts: PressBodyOptions): string[] {
+  const body: string[] = [];
+  for (let i = 0; i < chords.length; i += 1) {
+    const chord = chords[i]!;
+    if (chord.length === 0) continue;
+    const vks = chord.map(toVk);
+    for (const vk of vks) body.push(`[NAInput]::Vk(${vk}, $false)`);
+    if (opts.holdMs > 0) body.push(`Start-Sleep -Milliseconds ${opts.holdMs}`);
+    // 逆序释放，保证组合键正确
+    for (const vk of [...vks].reverse()) body.push(`[NAInput]::Vk(${vk}, $true)`);
+    if (i < chords.length - 1 && opts.gapMs > 0) {
+      body.push(`Start-Sleep -Milliseconds ${opts.gapMs}`);
+    }
+  }
+  return body;
+}
+
+/**
+ * 生成后台定向投递（PostMessage）脚本。
+ *
+ * 与前台注入同样遵守"按下顺序 / 释放逆序"；每和弦投递给目标进程全部顶层窗口。
+ * C# 侧 PostChord(vks, targetPid, up)：up=false → WM_KEYDOWN，up=true → WM_KEYUP。
+ */
+export function buildPostBody(chords: string[][], opts: PressBodyOptions): string[] {
+  const body: string[] = [];
+  const pid = Math.max(1, Math.trunc(opts.targetPid));
+  for (let i = 0; i < chords.length; i += 1) {
+    const vks = chords[i]!.map(toVk);
+    if (vks.length === 0) continue;
+    body.push(`[NAInput]::PostChord(@(${vks.join(', ')}), ${pid}, $false)`);
+    if (opts.holdMs > 0) body.push(`Start-Sleep -Milliseconds ${opts.holdMs}`);
+    // 逆序释放
+    const rel = [...vks].reverse().join(', ');
+    body.push(`[NAInput]::PostChord(@(${rel}), ${pid}, $true)`);
+    if (i < chords.length - 1 && opts.gapMs > 0) {
+      body.push(`Start-Sleep -Milliseconds ${opts.gapMs}`);
+    }
+  }
+  return body;
+}

apps/agent/src/capabilities/input.ts

@@ -1,4 +1,10 @@
-import { CapabilityError, ErrorCodes } from '@nodeagent/protocol';
+import { CapabilityError, ErrorCodes, expandChords } from '@nodeagent/protocol';
+import {
+  isAllMedia,
+  buildMediaBody,
+  buildForegroundBody,
+  buildPostBody,
+} from './input-script.js';
 import { IS_WINDOWS, execCommand } from '../util/exec.js';
 
 type Args = Record<string, unknown>;
@@ -128,6 +134,83 @@ public static class NAInput {
         var u = new INPUT[1]; u[0].type = 0; u[0].U.mi.dwFlags = upFlag;
         SendInput(1, u, SIZE);
     }
+
+    /// <summary>
+    /// 媒体控制（2026-10-05 补）：经 WM_APPCOMMAND 广播到目标窗口。
+    ///
+    /// 为何不只靠 VK 注入：媒体键用 SendInput 打进去后，**并非所有播放器都接收**
+    /// —— 只有当前获得媒体会话焦点的窗口才会响应。而 WM_APPCOMMAND 可直接
+    /// 投递给指定 hwnd，绕开「谁是当前媒体会话焦点」这层不确定性。
+    ///
+    /// 用途：远程控制主流媒体播放器（音乐 / 视频）或浏览器视频，且**窗口最小化
+    /// 或被全屏独占应用遮挡时依然有效**（实测：精简模式的播放器被全屏游戏压住时该通道可用）。
+    /// </summary>
+    [DllImport("user32.dll", CharSet = CharSet.Auto)]
+    private static extern bool PostMessage(IntPtr hWnd, uint Msg, IntPtr wParam, IntPtr lParam);
+
+    [DllImport("user32.dll")]
+    private static extern bool EnumWindows(EnumProc cb, IntPtr p);
+    private delegate bool EnumProc(IntPtr h, IntPtr p);
+
+    [DllImport("user32.dll")]
+    private static extern uint GetWindowThreadProcessId(IntPtr h, out uint pid);
+
+    /// <summary>
+    /// 向目标窗口（或其全部顶层窗口）发媒体控制命令。
+    /// appCommand 取值：14=PLAY 15=STOP 12=PLAY_PAUSE 6=PREV 7=NEXT
+    ///                  3=FFWD 4=REWIND 10=CLOSE 0=PLAY 1=PAUSE
+    /// targetPid 非 0 时，自动找到该进程的所有顶层窗口并逐个投递
+    /// （部分播放器会创建数十个辅助窗口，只投主窗口常常无效）。
+    /// </summary>
+    public static int MediaCommand(int appCommand, int targetPid) {
+        int sent = 0;
+        if (targetPid == 0) {
+            // HWND_BROADCAST：广播给所有顶层窗口
+            if (PostMessage((IntPtr)0xFFFF, 0x0319, IntPtr.Zero, (IntPtr)appCommand)) sent++;
+            return sent;
+        }
+        var handles = new System.Collections.Generic.List<IntPtr>();
+        EnumWindows(delegate(IntPtr h, IntPtr p) {
+            uint wpid;
+            GetWindowThreadProcessId(h, out wpid);
+            if (wpid == (uint)targetPid) handles.Add(h);
+            return true;
+        }, IntPtr.Zero);
+        foreach (var h in handles) {
+            if (PostMessage(h, 0x0319, IntPtr.Zero, (IntPtr)appCommand)) sent++;
+        }
+        return sent;
+    }
+
+    /// <summary>
+    /// v1.5：向目标进程的**全部顶层窗口** PostMessage 键盘消息（后端定向快捷键投放）。
+    ///
+    /// 场景：目标窗口不在前台（被遮挡 / 最小化 / 聊天窗口在后台），又要给它发快捷键。
+    /// WM_KEYDOWN=0x0100，WM_KEYUP=0x0101；修饰键按顺序投递，调用方负责释放顺序。
+    ///
+    /// ⚠️ 已知局限（务必告知调用方）：
+    ///   - 部分程序不处理**后台**键盘消息（游戏、部分浏览器与输入型应用直接忽略）；
+    ///   - PostMessage 不带 scancode，依赖 lParam 解码按键的程序可能取不到键。
+    /// 该类目标请改用默认 route=foreground（前台注入，需目标可见）。
+    /// </summary>
+    public static int PostChord(ushort[] vks, int targetPid, bool up) {
+        int sent = 0;
+        if (vks == null || vks.Length == 0) return 0;
+        var handles = new System.Collections.Generic.List<IntPtr>();
+        EnumWindows(delegate(IntPtr h, IntPtr p) {
+            uint wpid;
+            GetWindowThreadProcessId(h, out wpid);
+            if (wpid == (uint)targetPid) handles.Add(h);
+            return true;
+        }, IntPtr.Zero);
+        uint msg = up ? 0x0101u : 0x0100u;
+        foreach (var h in handles) {
+            foreach (var vk in vks) {
+                if (PostMessage(h, msg, (IntPtr)vk, IntPtr.Zero)) sent++;
+            }
+        }
+        return sent;
+    }
 }`;
 
 /** 组装：加类型定义 + 具体操作。 */
@@ -137,13 +220,14 @@ function psScript(body: string[]): string {
   );
 }
 
-async function runPs(body: string[], timeoutMs = 30_000): Promise<void> {
+async function runPs(body: string[], timeoutMs = 30_000): Promise<string> {
   const r = await execCommand({ command: psScript(body), timeoutMs });
   if (r.exit_code !== 0) {
     throw new CapabilityError(ErrorCodes.EXECUTION_FAILED, '输入注入失败', {
       detail: (r.stderr || r.stdout).slice(0, 400),
     });
   }
+  return r.stdout ?? '';
 }
 
 // ---------------- 鼠标 ----------------
@@ -256,29 +340,6 @@ export async function mouseDrag(args: Args): Promise<unknown> {
   return { dragged: true, from: { x: x1, y: y1 }, to: { x: x2, y: y2 }, button, steps };
 }
 
-// ---------------- 键盘 ----------------
-const VK_MAP: Record<string, number> = {
-  ctrl: 0x11, control: 0x11, shift: 0x10, alt: 0x12, win: 0x5b, meta: 0x5b,
-  enter: 0x0d, return: 0x0d, tab: 0x09, esc: 0x1b, escape: 0x1b, space: 0x20,
-  backspace: 0x08, delete: 0x2e, del: 0x2e, insert: 0x2d, ins: 0x2d,
-  up: 0x26, down: 0x28, left: 0x25, right: 0x27,
-  home: 0x24, end: 0x23, pageup: 0x21, pagedown: 0x22,
-  capslock: 0x14, printscreen: 0x2c,
-  f1: 0x70, f2: 0x71, f3: 0x72, f4: 0x73, f5: 0x74, f6: 0x75,
-  f7: 0x76, f8: 0x77, f9: 0x78, f10: 0x79, f11: 0x7a, f12: 0x7b,
-};
-
-/** 键名 → 虚拟键码（字母/数字走 ASCII 映射，其余查表白名单）。 */
-function toVk(key: string): number {
-  const k = key.trim().toLowerCase();
-  if (VK_MAP[k] !== undefined) return VK_MAP[k]!;
-  if (/^[a-z]$/.test(k)) return k.toUpperCase().charCodeAt(0);
-  if (/^[0-9]$/.test(k)) return k.charCodeAt(0);
-  throw new CapabilityError(ErrorCodes.PARAM_INVALID, `不支持的按键: ${key}`, {
-    supported: [...Object.keys(VK_MAP), 'a-z', '0-9'],
-  });
-}
-
 export async function keyType(args: Args): Promise<unknown> {
   assertAllowed('input.key.type');
   requireWindows('input.key.type');
@@ -303,35 +364,96 @@ export async function keyPress(args: Args): Promise<unknown> {
   assertAllowed('input.key.press');
   requireWindows('input.key.press');
 
-  // v10.2：支持三种语义
-  //   1) keys      —— 单个和弦（如 ["ctrl","c"]）
-  //   2) repeat    —— 和弦重复 N 次（解决「连按上键 3 次」这类需求）
-  //   3) sequence  —— 任意和弦序列（如 [["ctrl","c"], ["ctrl","v"]]）
-  const sequence = args['sequence'] as string[][] | undefined;
-  const repeat = Math.max(1, Math.min(50, (args['repeat'] as number | undefined) ?? 1));
-  const keys = args['keys'] as string[] | undefined;
+  // v1.5：入参统一经 protocol 的 expandChords 展开 —— 字符串热键 / 预设名 / 老数组形式
+  // 全部收敛成「归一化和弦序列」。混用多种形式会直接报错，避免"以谁为准"的歧义。
+  let expanded;
+  try {
+    expanded = expandChords({
+      hotkey: args['hotkey'] as string | undefined,
+      hotkeys: args['hotkeys'] as string[] | undefined,
+      preset: args['preset'] as string | undefined,
+      presets: args['presets'] as string[] | undefined,
+      keys: args['keys'] as string[] | undefined,
+      sequence: args['sequence'] as string[][] | undefined,
+      repeat: args['repeat'] as number | undefined,
+    });
+  } catch (err) {
+    throw new CapabilityError(ErrorCodes.PARAM_INVALID, `快捷键参数错误: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const chords = expanded.chords;
+  const presets = expanded.presets;
 
-  const chords: string[][] = sequence?.length
-    ? sequence
-    : keys?.length
-      ? Array.from({ length: repeat }, () => keys)
-      : [];
-  if (chords.length === 0) {
-    throw new CapabilityError(ErrorCodes.PARAM_INVALID, '需提供 keys（可配 repeat）或 sequence');
+  const gap = Math.max(0, Math.min(2000, (args['interval_ms'] as number) ?? 40));
+  // v1.5：长按（按下到释放的保持时长），用于"长按音量/持续按住方向键"等场景
+  const holdMs = Math.max(0, Math.min(5000, Math.round((args['hold_ms'] as number | undefined) ?? 0)));
+  // v1.5：投放路由。foreground = SendInput 注入当前焦点（默认，旧行为）；
+  //       post = 向目标进程全部顶层窗口 PostMessage（窗口在后台时可用，但兼容性差）
+  const route = (args['route'] as string | undefined) ?? 'foreground';
+  if (route !== 'foreground' && route !== 'post') {
+    throw new CapabilityError(ErrorCodes.PARAM_INVALID, `不支持的 route: ${route}`, { allowed: ['foreground', 'post'] });
+  }
+  const pid = (args['target_pid'] as number) ?? 0;
+  if (route === 'post' && pid <= 0) {
+    throw new CapabilityError(
+      ErrorCodes.PARAM_INVALID,
+      'route=post 需要提供 target_pid（≥1）—— 后台投递必须知道投给哪个进程',
+      { hint: '用 window.list 取目标进程 PID；无目标时请用默认 route=foreground' },
+    );
   }
 
-  const body: string[] = [];
-  const gap = Math.max(0, Math.min(2000, (args['interval_ms'] as number | undefined) ?? 40));
-  for (let i = 0; i < chords.length; i += 1) {
-    const chord = chords[i]!;
-    if (chord.length === 0) continue;
-    const vks = chord.map(toVk);
-    for (const vk of vks) body.push(`[NAInput]::Vk(${vk}, $false)`);
-    // 逆序释放，保证组合键正确
-    for (const vk of [...vks].reverse()) body.push(`[NAInput]::Vk(${vk}, $true)`);
-    if (i < chords.length - 1 && gap > 0) body.push(`Start-Sleep -Milliseconds ${gap}`);
+  // 媒体键走 WM_APPCOMMAND 通道（2026-10-05 补）
+  //
+  // 仅当**整条序列都是媒体键**时启用。若混在普通按键里（如 ["ctrl","media_play_pause"]）
+  // 则回退到 VK 注入 —— 那种组合场景本就罕见，SendInput 足够。
+  const allMedia = isAllMedia(chords);
+  if (allMedia) {
+    // target_pid 非 0 时定向投递到该进程的全部顶层窗口（部分播放器会建数十个辅助窗口，
+    // 只投主窗口常常无效 —— 实测踩过）；否则广播。
+    const mediaBody = buildMediaBody(chords, { gapMs: gap, holdMs, targetPid: pid, route });
+    await runPs(mediaBody);
+    return {
+      pressed: true,
+      keys: chords.length === 1 ? chords[0] : undefined,
+      chords,
+      times: chords.length,
+      presets,
+      via: expanded.via,
+      channel: 'appcommand',
+      target_pid: pid || null,
+    };
   }
-  await runPs(body);
+
+  // v1.5：后端定向投递（route=post）—— 目标窗口不在前台时使用
+  if (route === 'post') {
+    let sent = 0;
+    const out = await runPs(buildPostBody(chords, { gapMs: gap, holdMs, targetPid: pid, route }));
+    // 累计投递成功的窗口数（C# 侧每次 PostMessage 成功计数）
+    let total = 0;
+    for (const line of out.split('\n')) {
+      const m = /(\d+)/.exec(line.trim());
+      if (m) total += Number(m[1]);
+    }
+    sent = total;
+    return {
+      pressed: true,
+      keys: chords.length === 1 ? chords[0] : undefined,
+      chords,
+      times: chords.length,
+      presets,
+      via: expanded.via,
+      channel: 'postmessage',
+      route,
+      target_pid: pid,
+      sent_windows: sent,
+      note:
+        sent === 0
+          ? '未投递到任何窗口（进程可能已退出或没有任何顶层窗口）'
+          : '后台投递兼容性有限：游戏/部分浏览器与输入型程序不响应后台键盘消息，' +
+            '无效时改用 route=foreground 并确保目标窗口可见',
+    };
+  }
+
+  await runPs(buildForegroundBody(chords, { gapMs: gap, holdMs, targetPid: pid, route }));
   // 同时回传 keys（单和弦时的回显）与 chords（完整序列）。
   // 修正 2026-10-04：此前只回 chords，控制端 CLI 读 keys.join() 直接崩溃。
   return {
@@ -339,5 +461,9 @@ export async function keyPress(args: Args): Promise<unknown> {
     keys: chords.length === 1 ? chords[0] : undefined,
     chords,
     times: chords.length,
+    presets,
+    via: expanded.via,
+    hold_ms: holdMs || undefined,
+    route,
   };
 }

apps/agent/src/capabilities/log.ts

@@ -0,0 +1,151 @@
+/**
+ * log.query（v1.8，方向二「状态」第一块）。
+ *
+ * ## 为什么必须有
+ * 治间歇性问题（代理不通、杀软拦截、端口时开时闭）要看**历史**，而被控端日志常在
+ * 几万行以上。`fs.read` 虽有 8MB 上限，但"整份拉回再筛"既慢又占带宽 ——
+ * 过滤必须发生在 **Windows 侧**。
+ *
+ * ## 实现要点
+ * - 流式逐行读（readline），**不全量载入内存**；扫到 limit 条即停
+ * - 三级过滤：`pattern`（正则，大小写不敏感）/ `level`（ERROR|WARN|INFO|DEBUG，
+ *   命中行内含 `[LEVEL]` 或 `LEVEL:` 即算）/ `since`（Unix ms，按行首时间戳或
+ *   文件 mtime 粗筛）
+ * - 路径仍走 `fs.guardPath` 的白名单（fs_roots 非空即受限）—— 不新开安全面
+ * - 单行超长保护：超过 4KB 的行截断后再匹配，避免一行巨型 JSON 拖垮内存
+ */
+
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { statSync } from 'node:fs';
+import { CapabilityError, ErrorCodes } from '@nodeagent/protocol';
+import { guardPath } from './fs.js';
+
+type Args = Record<string, unknown>;
+
+const MAX_LINE = 4096;
+const MAX_SCAN = 2_000_000; // 单次查询最多扫 200 万行，防失控文件拖死 agent
+
+export interface LogLine {
+  /** 行号（从 1 开始）—— 回看时便于对照原文件 */
+  n: number;
+  text: string;
+}
+
+export interface LogQueryResult {
+  path: string;
+  matched: LogLine[];
+  /** 实际扫描过的行数（用于判断"是扫完了还是被 limit 截住"） */
+  scanned: number;
+  /** 是否因达到 MAX_SCAN 提前结束 */
+  truncated: boolean;
+  note?: string;
+}
+
+/** 从行里推断日志级别（找不到返回 null，不猜）。 */
+function detectLevel(line: string): string | null {
+  const m = /\[(ERROR|WARN|WARNING|INFO|DEBUG|TRACE)\]|\b(ERROR|WARN|INFO|DEBUG|TRACE):/i.exec(line);
+  if (!m) return null;
+  const raw = (m[1] ?? m[2] ?? '').toUpperCase();
+  return raw === 'WARNING' ? 'WARN' : raw;
+}
+
+export async function logQuery(args: Args): Promise<LogQueryResult> {
+  const p = guardPath(args['path'] as string);
+  const limit = Math.max(1, Math.min(5000, (args['limit'] as number | undefined) ?? 100));
+  const offset = Math.max(0, (args['offset'] as number | undefined) ?? 0);
+  const patternStr = args['pattern'] as string | undefined;
+  const level = (args['level'] as string | undefined)?.toUpperCase();
+  const since = args['since'] as number | undefined;
+  const tail = (args['tail'] as boolean | undefined) ?? false;
+
+  let re: RegExp | null = null;
+  if (patternStr) {
+    try {
+      re = new RegExp(patternStr, 'i');
+    } catch (err) {
+      throw new CapabilityError(ErrorCodes.PARAM_INVALID, `pattern 不是合法正则: ${patternStr}`, {
+        detail: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+  if (level && !['ERROR', 'WARN', 'INFO', 'DEBUG', 'TRACE'].includes(level)) {
+    throw new CapabilityError(ErrorCodes.PARAM_INVALID, `不支持的 level: ${level}`, {
+      allowed: ['ERROR', 'WARN', 'INFO', 'DEBUG', 'TRACE'],
+    });
+  }
+
+  let st;
+  try {
+    st = statSync(p);
+  } catch {
+    throw new CapabilityError(ErrorCodes.PARAM_INVALID, `文件不存在或不可读: ${p}`);
+  }
+  if (!st.isFile()) {
+    throw new CapabilityError(ErrorCodes.PARAM_INVALID, `不是普通文件: ${p}`);
+  }
+  // since 粗筛：文件在 since 之前就没改过，必然没有更新的行 —— 省一次全扫
+  if (since !== undefined && st.mtimeMs < since) {
+    return { path: p, matched: [], scanned: 0, truncated: false, note: '文件 mtime 早于 since，未扫描' };
+  }
+
+  // tail 模式：保留最后 limit 条命中的环形缓冲（边扫边丢旧的）
+  const ring: LogLine[] = [];
+  let matched = 0;
+  let scanned = 0;
+  let truncated = false;
+
+  const rl = createInterface({
+    input: createReadStream(p, { encoding: 'utf8' }),
+    crlfDelay: Number.POSITIVE_INFINITY,
+  });
+
+  for await (const rawLine of rl) {
+    scanned += 1;
+    if (scanned > MAX_SCAN) {
+      truncated = true;
+      break;
+    }
+    let line = rawLine;
+    if (line.length > MAX_LINE) line = `${line.slice(0, MAX_LINE)}…[截断]`;
+    if (re && !re.test(line)) continue;
+    if (level && detectLevel(line) !== level) continue;
+    // since 精确筛：只在行首能解出时间戳时才按时间比（解不出就放行，交由调用方判断）
+    if (since !== undefined) {
+      const ts = parseLeadingTs(line);
+      if (ts !== null && ts < since) continue;
+    }
+    matched += 1;
+    if (tail) {
+      ring.push({ n: scanned, text: line });
+      if (ring.length > limit) ring.shift();
+    } else {
+      if (matched > offset && matched <= offset + limit) ring.push({ n: scanned, text: line });
+      if (matched > offset + limit) break; // 已取够，提前收工
+    }
+  }
+
+  return {
+    path: p,
+    matched: ring,
+    scanned,
+    truncated,
+    ...(truncated ? { note: `扫描超过 ${MAX_SCAN} 行上限，结果可能不完整` } : {}),
+  };
+}
+
+/**
+ * 行首时间戳 → Unix ms（支持 ISO 与常见 `[2026-10-07 12:34:56]` 形态；解不出返回 null）。
+ *
+ * ⚠️ 必须**连同时区后缀一起解析**：只截取到秒会丢掉 `Z` / `+08:00`，
+ * 让 UTC 时间被当本地时间读 —— 实测会整体偏 8 小时（真机日志跨时区时判断"何时断的"就错了）。
+ */
+export function parseLeadingTs(line: string): number | null {
+  const m = /^\[?(\d{4}[-/]\d{2}[-/]\d{2}[ T]\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:?\d{2})?)/.exec(line);
+  if (!m) return null;
+  // 无时区信息时按本地时间解析（与 `[2026-10-07 10:00:12]` 这类本地日志的语义一致）；
+  // 带 Z / ±hh:mm 时 Date.parse 自行按该时区处理 —— 关键是**别把后缀截掉**。
+  const iso = m[1]!.replace(/\//g, '-').replace(' ', 'T');
+  const t = Date.parse(iso);
+  return Number.isFinite(t) ? t : null;
+}

apps/agent/src/capabilities/monitor.ts

@@ -0,0 +1,364 @@
+/**
+ * monitor.*（v1.8，方向二「状态」第二块）—— 定时采样落盘与回看。
+ *
+ * ## 为什么需要（复盘 §四）
+ * 代理不通、杀软拦截、端口时开时闭都是**间歇性**的，而 `system.status` 只能看当下快照。
+ * `event.watch` 解决「有事件时通知」，没解决「**持续记录，事后能查**」。
+ *
+ * ## 设计
+ * - 四类采样源：`port`（连通性 + 延迟）/ `process`（存活 + PID 列表）/
+ *   `command`（退出码 + 首行输出）/ `metric`（CPU/内存）
+ * - 落盘 `<数据目录>/monitors/<id>.jsonl`（一行一样本，追加写 + 立即 flush 语义）
+ * - `monitor.report` 读回并给摘要：min/max/均值、断线次数、最长中断 —— 直接回答
+ *   「5 分钟里断过几次、最长断了多久」
+ * - 并发上限 8 个；单文件 10 万行封顶（防写满磁盘）
+ * - 采样循环 `unref()`，不阻止 agent 退出；`monitor.stop` 或进程退出即停
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { connect } from 'node:net';
+import { exec } from 'node:child_process';
+import { join } from 'node:path';
+import { homedir, totalmem, freemem, cpus } from 'node:os';
+import { CapabilityError, ErrorCodes } from '@nodeagent/protocol';
+import { logQuery, type LogLine } from './log.js';
+
+type Args = Record<string, unknown>;
+
+export type MonitorSource = 'port' | 'process' | 'command' | 'metric';
+
+interface Sample {
+  ts: number;
+  /** 各源自定义字段 */
+  [k: string]: unknown;
+}
+
+interface MonitorRecord {
+  id: string;
+  source: MonitorSource;
+  target: string;
+  intervalMs: number;
+  createdAt: number;
+  samples: number;
+  file: string;
+  timer: ReturnType<typeof setInterval>;
+  /** 首次采样失败时记下，避免每次 tick 都刷错误 */
+  lastError: string | null;
+}
+
+const monitors = new Map<string, MonitorRecord>();
+const MAX_MONITORS = 8;
+const MAX_SAMPLES_PER_FILE = 100_000;
+
+function dataDir(): string {
+  return process.env['NODEAGENT_HOME'] ?? join(homedir(), '.nodeagent');
+}
+
+function monitorDir(): string {
+  const d = join(dataDir(), 'monitors');
+  if (!existsSync(d)) mkdirSync(d, { recursive: true });
+  return d;
+}
+
+// ---------------- 采样器 ----------------
+
+/** port：TCP 连通性 + 握手耗时（跨平台，无额外依赖）。 */
+function samplePort(host: string, port: number, timeoutMs: number): Promise<Sample> {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const sock = connect({ host, port });
+    const done = (up: boolean, err?: string): void => {
+      sock.destroy();
+      resolve({ ts: Date.now(), up, ms: Date.now() - started, ...(err ? { error: err } : {}) });
+    };
+    sock.setTimeout(timeoutMs);
+    sock.once('connect', () => done(true));
+    sock.once('timeout', () => done(false, 'timeout'));
+    sock.once('error', (e) => done(false, String(e.message ?? e)));
+  });
+}
+
+/** process：按名判断存活（Windows tasklist / POSIX ps，与 events.ts 同策略）。 */
+function sampleProcess(name: string): Promise<Sample> {
+  return new Promise((resolve) => {
+    const cmd =
+      process.platform === 'win32'
+        ? `tasklist /FI "IMAGENAME eq ${name}" /NH`
+        : `ps -axo pid=,comm= | grep -i "${name}" | grep -v grep`;
+    exec(cmd, { timeout: 8000 }, (err, stdout) => {
+      const lines = stdout
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 && !/^INFO:/i.test(l));
+      const pids = lines
+        .map((l) => {
+          const m = /^(\d+)/.exec(l);
+          return m ? Number(m[1]) : null;
+        })
+        .filter((x): x is number => x !== null);
+      resolve({ ts: Date.now(), alive: pids.length > 0, pids, ...(err && pids.length === 0 ? { error: String(err.message) } : {}) });
+    });
+  });
+}
+
+/** command：退出码 + 输出首行（用于"跑个探针命令"这类自定义采样）。 */
+function sampleCommand(command: string, timeoutMs: number): Promise<Sample> {
+  return new Promise((resolve) => {
+    exec(command, { timeout: timeoutMs }, (err, stdout, stderr) => {
+      const first = (stdout || stderr || '').split('\n')[0]?.slice(0, 500) ?? '';
+      resolve({
+        ts: Date.now(),
+        exit_code: err ? (typeof err.code === 'number' ? err.code : 1) : 0,
+        first_line: first,
+      });
+    });
+  });
+}
+
+/** metric：CPU（两次采样差分）+ 内存。 */
+async function sampleMetric(): Promise<Sample> {
+  const a = cpus();
+  await new Promise((r) => setTimeout(r, 200));
+  const b = cpus();
+  const idle = (c: typeof a): number =>
+    c.reduce((s, x) => s + x.times.idle + x.times.irq, 0) / c.length;
+  const total = (c: typeof a): number =>
+    c.reduce((s, x) => s + Object.values(x.times).reduce((p, q) => p + q, 0), 0) / c.length;
+  const idleDiff = idle(b) - idle(a);
+  const totalDiff = total(b) - total(a);
+  const cpu = totalDiff > 0 ? Math.round((1 - idleDiff / totalDiff) * 10000) / 100 : 0;
+  const mem = totalmem();
+  const free = freemem();
+  return { ts: Date.now(), cpu_pct: cpu, mem_pct: Math.round(((mem - free) / mem) * 10000) / 100 };
+}
+
+async function takeSample(rec: MonitorRecord): Promise<Sample> {
+  switch (rec.source) {
+    case 'port': {
+      const [host, portStr] = rec.target.split(':');
+      return samplePort(host || '127.0.0.1', Number(portStr), Math.min(rec.intervalMs, 5000));
+    }
+    case 'process':
+      return sampleProcess(rec.target);
+    case 'command':
+      return sampleCommand(rec.target, Math.min(rec.intervalMs * 2, 20_000));
+    case 'metric':
+      return sampleMetric();
+  }
+}
+
+// ---------------- 能力实现 ----------------
+
+export async function monitorStart(args: Args): Promise<unknown> {
+  const source = args['source'] as MonitorSource | undefined;
+  if (!source || !['port', 'process', 'command', 'metric'].includes(source)) {
+    throw new CapabilityError(ErrorCodes.PARAM_INVALID, `不支持的 source: ${String(source)}`, {
+      allowed: ['port', 'process', 'command', 'metric'],
+      hint: 'port 需 target="host:port"；process 需 target=进程名；command 需 target=命令；metric 不需要 target',
+    });
+  }
+  const intervalMs = Math.max(500, Math.min(600_000, (args['interval_ms'] as number | undefined) ?? 2000));
+  const target = (args['target'] as string | undefined) ?? '';
+  if (source !== 'metric' && !target) {
+    throw new CapabilityError(ErrorCodes.PARAM_INVALID, `source=${source} 需要 target`);
+  }
+  if (source === 'port' && !/^.+:\d+$/.test(target)) {
+    throw new CapabilityError(ErrorCodes.PARAM_INVALID, 'port 采样的 target 应为 "host:port"', { got: target });
+  }
+  if (monitors.size >= MAX_MONITORS) {
+    throw new CapabilityError(ErrorCodes.RATE_LIMITED, `并发监控上限 ${MAX_MONITORS} 个`, {
+      running: [...monitors.keys()],
+    });
+  }
+
+  const id = (args['id'] as string | undefined)?.trim() || `m_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+  if (monitors.has(id)) {
+    throw new CapabilityError(ErrorCodes.PARAM_INVALID, `监控 id 已存在: ${id}`, { hint: '换个 id，或先 monitor.stop' });
+  }
+  if (!/^[\w.-]{1,64}$/.test(id)) {
+    throw new CapabilityError(ErrorCodes.PARAM_INVALID, 'id 只允许字母数字与 . _ -（≤64 字符）', { got: id });
+  }
+
+  const file = join(monitorDir(), `${id}.jsonl`);
+  const rec: MonitorRecord = {
+    id, source, target, intervalMs, createdAt: Date.now(), samples: 0, file,
+    timer: setInterval(() => { void tick(rec); }, intervalMs),
+    lastError: null,
+  };
+  monitors.set(id, rec);
+  // 立即采第一针（调用方往往想马上知道"现在通不通"），不额外等一个 interval
+  void tick(rec);
+  return { id, source, target, interval_ms: intervalMs, file, started_at: rec.createdAt };
+}
+
+async function tick(rec: MonitorRecord): Promise<void> {
+  try {
+    const s = await takeSample(rec);
+    rec.lastError = null;
+    appendFileSync(rec.file, `${JSON.stringify(s)}\n`, 'utf8');
+    rec.samples += 1;
+    // 行数封顶：超过就从头截断（保留后半），防止磁盘写满
+    if (rec.samples > MAX_SAMPLES_PER_FILE) {
+      const lines = readFileSync(rec.file, 'utf8').trim().split('\n');
+      writeFileSync(rec.file, `${lines.slice(-MAX_SAMPLES_PER_FILE).join('\n')}\n`, 'utf8');
+      rec.samples = MAX_SAMPLES_PER_FILE;
+    }
+  } catch (err) {
+    rec.lastError = err instanceof Error ? err.message : String(err);
+    // 采样失败也记一行（"查不到"本身也是信息），但不无限刷盘
+    if (rec.samples < MAX_SAMPLES_PER_FILE) {
+      appendFileSync(rec.file, `${JSON.stringify({ ts: Date.now(), error: rec.lastError })}\n`, 'utf8');
+      rec.samples += 1;
+    }
+  }
+}
+
+export async function monitorReport(args: Args): Promise<unknown> {
+  const id = args['id'] as string;
+  if (!id) throw new CapabilityError(ErrorCodes.PARAM_INVALID, '需要 id');
+  const rec = monitors.get(id);
+  const file = join(monitorDir(), `${id}.jsonl`);
+  if (!rec && !existsSync(file)) {
+    throw new CapabilityError(ErrorCodes.PARAM_INVALID, `没有这个监控: ${id}`, { running: [...monitors.keys()] });
+  }
+  const since = args['since'] as number | undefined;
+  const limit = Math.max(1, Math.min(20_000, (args['limit'] as number | undefined) ?? 5000));
+
+  const samples: Sample[] = [];
+  let truncated = false;
+  if (existsSync(file)) {
+    const lines = readFileSync(file, 'utf8').split('\n');
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const s = JSON.parse(line) as Sample;
+        if (since !== undefined && s.ts < since) continue;
+        samples.push(s);
+      } catch {
+        /* 半行（写入中断）跳过 */
+      }
+    }
+    if (samples.length > limit) {
+      samples.splice(0, samples.length - limit);
+      truncated = true;
+    }
+  }
+
+  return {
+    id,
+    running: rec !== undefined,
+    source: rec?.source ?? 'unknown',
+    target: rec?.target ?? '',
+    interval_ms: rec?.intervalMs,
+    file,
+    samples: samples.length,
+    truncated,
+    last_error: rec?.lastError ?? undefined,
+    summary: summarize(samples, rec?.source ?? 'port'),
+    series: samples,
+  };
+}
+
+/** 摘要：把样本压成"人话"—— 断几次、最长多久、值域。 */
+function summarize(samples: Sample[], source: MonitorSource): Record<string, unknown> {
+  if (samples.length === 0) return { n: 0 };
+  const base: Record<string, unknown> = { n: samples.length };
+  const ts = samples.map((s) => s.ts);
+  base.window_ms = Math.max(...ts) - Math.min(...ts);
+
+  if (source === 'port') {
+    const ups = samples.filter((s) => s.up === true);
+    base.up_count = ups.length;
+    base.down_count = samples.length - ups.length;
+    const lat = samples.map((s) => Number(s.ms ?? 0)).filter((x) => Number.isFinite(x));
+    if (lat.length) {
+      base.ms_min = Math.min(...lat);
+      base.ms_max = Math.max(...lat);
+      base.ms_avg = Math.round((lat.reduce((a, b) => a + b, 0) / lat.length) * 100) / 100;
+    }
+    // 最长连续中断
+    let run = 0;
+    let worst = 0;
+    for (const s of samples) {
+      if (s.up === true) { run = 0; } else { run += 1; worst = Math.max(worst, run); }
+    }
+    base.longest_outage_samples = worst;
+  } else if (source === 'process') {
+    base.alive_count = samples.filter((s) => s.alive === true).length;
+    base.dead_count = samples.filter((s) => s.alive !== true).length;
+    let run = 0;
+    let worst = 0;
+    for (const s of samples) {
+      if (s.alive === true) { run = 0; } else { run += 1; worst = Math.max(worst, run); }
+    }
+    base.longest_dead_samples = worst;
+  } else if (source === 'command') {
+    const codes = samples.map((s) => Number(s.exit_code ?? -1));
+    base.ok_count = codes.filter((c) => c === 0).length;
+    base.fail_count = codes.filter((c) => c !== 0).length;
+    base.exit_codes_seen = [...new Set(codes)];
+  } else {
+    const cpu = samples.map((s) => Number(s.cpu_pct ?? 0));
+    const mem = samples.map((s) => Number(s.mem_pct ?? 0));
+    if (cpu.length) {
+      base.cpu_min = Math.min(...cpu); base.cpu_max = Math.max(...cpu);
+      base.cpu_avg = Math.round((cpu.reduce((a, b) => a + b, 0) / cpu.length) * 100) / 100;
+    }
+    if (mem.length) {
+      base.mem_min = Math.min(...mem); base.mem_max = Math.max(...mem);
+      base.mem_avg = Math.round((mem.reduce((a, b) => a + b, 0) / mem.length) * 100) / 100;
+    }
+  }
+  return base;
+}
+
+export async function monitorStop(args: Args): Promise<unknown> {
+  const id = args['id'] as string;
+  if (!id) throw new CapabilityError(ErrorCodes.PARAM_INVALID, '需要 id');
+  const rec = monitors.get(id);
+  if (!rec) {
+    throw new CapabilityError(ErrorCodes.PARAM_INVALID, `没有正在运行的监控: ${id}`, { running: [...monitors.keys()] });
+  }
+  clearInterval(rec.timer);
+  monitors.delete(id);
+  const report = (await monitorReport({ id })) as { samples: number; summary: Record<string, unknown> };
+  return { id, stopped: true, samples: report.samples, summary: report.summary, file: rec.file };
+}
+
+export async function monitorList(_args: Args): Promise<unknown> {
+  const running = [...monitors.values()].map((r) => ({
+    id: r.id, source: r.source, target: r.target, interval_ms: r.intervalMs,
+    samples: r.samples, started_at: r.createdAt, file: r.file, last_error: r.lastError ?? undefined,
+  }));
+  const dir = monitorDir();
+  let files: string[] = [];
+  try {
+    files = (await import('node:fs')).readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
+  } catch {
+    /* 目录不存在即无历史 */
+  }
+  return {
+    running,
+    running_count: running.length,
+    history_files: files.map((f) => f.replace(/\.jsonl$/, '')),
+  };
+}
+
+/** 供 monitor.delete：删除历史文件（不影响运行中的实例）。 */
+export async function monitorDelete(args: Args): Promise<unknown> {
+  const id = args['id'] as string;
+  if (!id) throw new CapabilityError(ErrorCodes.PARAM_INVALID, '需要 id');
+  if (monitors.has(id)) {
+    throw new CapabilityError(ErrorCodes.PARAM_INVALID, '该监控仍在运行，请先 stop', { hint: `monitor.stop {"id":"${id}"}` });
+  }
+  const file = join(monitorDir(), `${id}.jsonl`);
+  if (!existsSync(file)) {
+    throw new CapabilityError(ErrorCodes.PARAM_INVALID, `没有历史文件: ${id}`);
+  }
+  rmSync(file, { force: true });
+  return { id, deleted: true, file };
+}
+
+// log.query 与 monitor 同属"状态"方向，放在同一能力文件里导出
+export { logQuery };
+export type { LogLine };

apps/agent/src/capabilities/network.ts

@@ -93,7 +93,7 @@ export function psLit(v: string): string {
  *
  * ⚠️ 两个真机教训都固化在这里：
  *   1) **账号名必须用 WindowsIdentity 取**，不要用 "$env:USERDOMAIN\$env:USERNAME" 拼 ——
- *      在 TS 模板串里 `\$` 会被当转义吃掉反斜杠，拼出「机器名<user>」这种不可解析的账号，
+ *      在 TS 模板串里 `\$` 会被当转义吃掉反斜杠，拼出「机器名+纯数字」这种不可解析的账号，
  *      Register-ScheduledTask 报 HRESULT 0x80070534「No mapping between account names...」。
  *   2) 复用同一实现：此前回滚/延时两处各写一份，改了一处漏了另一处（真机踩过）。
  */

apps/agent/src/capabilities/system.ts

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { guardPath } from './fs.js';
 import { readFileSync, statSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import os from 'node:os';
@@ -6,7 +7,7 @@ import { CapabilityError, ErrorCodes } from '@nodeagent/protocol';
 import { IS_WINDOWS, execCommand } from '../util/exec.js';
 import { currentCertFingerprint } from '../certs.js';
 import { loadAgentConfig } from '../config.js';
-import { readAudit, readAuditAll, verifyAudit } from '../audit.js';
+import { readAudit, readAuditAll, verifyAudit, computeAuditHead, anchorAudit, compareWithAnchors } from '../audit.js';
 import { computeMetrics } from '../metrics.js';
 import { allPsShellStats } from '../util/ps-helper.js';
 import { startTask } from './task.js';
@@ -55,7 +56,6 @@ async function isAdmin(): Promise<boolean> {
 // 故一律用 typeof 探测，绝不能直接引用（否则 dev 启动就 ReferenceError）。
 declare const __AGENT_VERSION__: string | undefined;
 declare const __BUILD_COMMIT__: string | undefined;
-declare const __BUILD_TIME__: string | undefined;
 
 /** v21：读取当前生效的来源白名单（用于 system.info 上报）。 */
 function configAllowFrom(): string[] | null {
@@ -67,10 +67,9 @@ function configAllowFrom(): string[] | null {
   }
 }
 
-function injected(name: 'version' | 'commit' | 'time'): string {
+function injected(name: 'version' | 'commit'): string {
   if (name === 'version') return typeof __AGENT_VERSION__ === 'undefined' ? 'dev' : __AGENT_VERSION__;
-  if (name === 'commit') return typeof __BUILD_COMMIT__ === 'undefined' ? 'dev' : __BUILD_COMMIT__;
-  return typeof __BUILD_TIME__ === 'undefined' ? 'dev' : __BUILD_TIME__;
+  return typeof __BUILD_COMMIT__ === 'undefined' ? 'dev' : __BUILD_COMMIT__;
 }
 
 const STARTED_AT = Date.now();
@@ -118,7 +117,9 @@ export function buildInfo(): {
     // v20：语义化版本 + 提交 + 构建时间（来自构建期注入）
     version: injected('version'),
     commit: injected('commit'),
-    built_at: injected('time'),
+    // 构建时间取入口文件的 mtime（而非构建期注入）—— 注入会让每次打包字节不同，
+    // 破坏「指纹 = 构建身份」的确定性（v22 真机踩过）
+    built_at: buildCache.mtime_ms ? new Date(buildCache.mtime_ms).toISOString() : 'unknown',
     // v21：TLS 证书指纹（控制端据此钉住被控端身份）
     cert_sha256: currentCertFingerprint(),
   };
@@ -526,15 +527,29 @@ async function scheduleWindowsRestart(p: RestartParams): Promise<unknown> {
   const TASK = `nodeagent-selfrestart-${Date.now()}`;
   const ps = [
     `$ErrorActionPreference='SilentlyContinue'`,
-    // 清理历史 selfrestart 任务（保留 Running 的 —— 那正是当前 agent 的宿主）
-    `Get-ScheduledTask -TaskName 'nodeagent-selfrestart*' | Where-Object { $_.State -ne 'Running' } | Unregister-ScheduledTask -Confirm:$false`,
+    // 清理历史 selfrestart 任务。
+    //
+    // ⚠️ 为什么不能简单清所有非 Running 的：重启任务的 cmd 会**一直持有新 agent 进程**，
+    // 所以任务长期处于 Running；若把 Running 的全清掉，会连当前 agent 的宿主一起杀
+    // （= 自杀，表现为"restart 成功但 agent 消失"）。原实现只清非 Running，
+    // 代价是真机累积了 3 个 Running 僵尸（2026-10-09 实测）。
+    //
+    // 现策略：非 Running **或** LastRunTime 早于 1 小时 → 清。
+    // 1 小时余量远大于一次重启的耗时，因此"当前宿主"绝不会被误判（它刚刚才运行）。
+    `$cut = (Get-Date).AddHours(-1)`,
+    `Get-ScheduledTask -TaskName 'nodeagent-selfrestart*' -ErrorAction SilentlyContinue | Where-Object { if ($_.State -ne 'Running') { return $true }; $ti = ($_ | Get-ScheduledTaskInfo -ErrorAction SilentlyContinue); if ($ti -and $ti.LastRunTime -and $ti.LastRunTime -lt $cut) { return $true }; return $false } | Unregister-ScheduledTask -Confirm:$false -ErrorAction SilentlyContinue`,
     `$a = New-ScheduledTaskAction -Execute 'cmd.exe' -Argument '${cmdLine.replace(/'/g, "''")}'`,
     // 不限时（默认 72h 后强制结束），保证 node 能长期运行
     `$s = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -ExecutionTimeLimit (New-TimeSpan -Seconds 0)`,
-    // ⚠️ 必须用最高权限：agent 通常以管理员运行，普通权限的 taskkill 杀不掉它，
+    // ① 先试「最高权限」：agent 通常以管理员运行，普通权限的 taskkill 杀不掉它，
     //    否则会出现「新进程起来了但端口被占（EADDRINUSE）」。
     `$p = New-ScheduledTaskPrincipal -UserId $env:USERNAME -RunLevel Highest -LogonType Interactive`,
     `Register-ScheduledTask -TaskName '${TASK}' -Action $a -Settings $s -Principal $p -Force | Out-Null`,
+    // ② 降级：**非管理员身份下 Highest 会被系统拒绝**（真机 2026-10-09 坐实：
+    //    agent 以普通用户运行时，deploy/restart 一律报"注册重启任务失败 exit=1"）。
+    //    此时不指定 -Principal —— 默认继承当前用户权限级别（Limited），
+    //    注册能成功，且同权限下 taskkill 自己完全够用。
+    `if ((Get-ScheduledTask -TaskName '${TASK}' -ErrorAction SilentlyContinue) -eq $null) { Register-ScheduledTask -TaskName '${TASK}' -Action $a -Settings $s -Force | Out-Null }`,
     // 校验注册真的成功（SilentlyContinue 会吞错，必须显式确认）
     `if ((Get-ScheduledTask -TaskName '${TASK}' -ErrorAction SilentlyContinue) -eq $null) { Write-Output 'register-failed'; exit 1 }`,
     `Start-ScheduledTask -TaskName '${TASK}'`,
@@ -600,6 +615,31 @@ export async function auditVerify(_args: Args): Promise<unknown> {
   return verifyAudit();
 }
 
+/**
+ * v25：返回审计链的链头（只读）。
+ *
+ * 用途：控制端定期拉取并存到**链外**（Mac 本地 / 另一台机器）—— 这是"外部锚定"的一半。
+ * compare=true 时附带与最近一条锚点的比对结论（另一半）。
+ */
+export async function auditHead(args: Args): Promise<unknown> {
+  const head = computeAuditHead();
+  if (args['compare'] !== true) return head;
+  return { ...head, comparison: compareWithAnchors(args['anchor_path'] as string | undefined) };
+}
+
+/**
+ * v25：把当前链头**追加**写到锚点文件（默认 <数据目录>/audit-anchors.jsonl）。
+ *
+ * 为什么是追加而不是覆盖：历史锚点一旦写成就不可被后续覆盖，否则攻击者重写链后
+ * 再"刷新"锚点即可抹掉痕迹。追加式让每次锚定都留痕。
+ * path 若指定，仍受 fs_roots 白名单约束（不新开写入面）。
+ */
+export async function auditAnchor(args: Args): Promise<unknown> {
+  const raw = args['path'] as string | undefined;
+  const path = raw ? guardPath(raw) : undefined;
+  return anchorAudit({ ...(path ? { path } : {}), ...(args['note'] ? { note: String(args['note']) } : {}) });
+}
+
 /** v13：成功指标聚合（对齐 PRD 2.2）—— 数据源为审计日志，无需额外埋点。 */
 export async function metricsReport(args: Args): Promise<unknown> {
   const since = args['since'] as number | undefined;

apps/agent/src/capabilities/task.ts

@@ -132,6 +132,13 @@ function getTask(id: string): TaskRecord {
 
 // ---------------- system.task.list ----------------
 
+/** v23：正在跑的任务数（连接层"有空闲断开但不动长任务"的判据）。 */
+export function runningTaskCount(): number {
+  let n = 0;
+  for (const t of tasks.values()) if (t.state === 'running') n += 1;
+  return n;
+}
+
 export async function taskList(_args: Args): Promise<unknown> {
   return {
     tasks: [...tasks.values()].map((t) => ({

apps/agent/src/capabilities/win-ps/body-list.ts

@@ -0,0 +1,42 @@
+/**
+ * 枚举可见顶层窗口 → JSON（**不含 prelude**，供常驻助手与一次性路径复用）
+ *
+ * 2026-10 从 window.ts 抽出（结构拆分，**内容逐字节不变**）。
+ * ⚠️ WIN_HELPER_PRELUDE 是本段与另外几段的拼接 —— 改动会直接影响常驻 PS 助手。
+ * 拆分以 tests/unit/win-prelude.test.mjs + prelude sha256 比对双重把关。
+ */
+
+/**
+ * 枚举可见顶层窗口 → JSON（**不含 prelude**，供常驻助手与一次性路径复用）。
+ * 注意：本段会被送进常驻进程执行，**严禁出现 exit**（会杀掉助手进程）。
+ */
+export const LIST_BODY = `
+$fg = [NAWin32]::GetForegroundWindow()
+$list = New-Object System.Collections.ArrayList
+$cb = [NAWin32+EnumProc]{
+  param($h, $l)
+  if (-not [NAWin32]::IsWindowVisible($h)) { return $true }
+  $sb = New-Object System.Text.StringBuilder 512
+  [void][NAWin32]::GetWindowTextW($h, $sb, 512)
+  $title = $sb.ToString()
+  if ([string]::IsNullOrWhiteSpace($title)) { return $true }
+  $r = New-Object NAWin32+RECT
+  if (-not [NAWin32]::GetWindowRect($h, [ref]$r)) { return $true }
+  $w = $r.Right - $r.Left; $ht = $r.Bottom - $r.Top
+  if ($w -le 0 -or $ht -le 0) { return $true }
+  # ⚠️ 变量名不能叫 $pid —— 它是 PowerShell 的自动变量（当前进程 ID），赋值会被忽略，
+  #    导致所有窗口都报成 powershell 进程（真机踩过）。
+  $procId = 0
+  [void][NAWin32]::GetWindowThreadProcessId($h, [ref]$procId)
+  $pn = ''
+  try { $pn = (Get-Process -Id $procId -ErrorAction Stop).ProcessName } catch {}
+  [void]$list.Add([pscustomobject]@{
+    hwnd = ('0x{0:X}' -f $h.ToInt64()); title = $title; process = $pn; pid = $procId
+    x = $r.Left; y = $r.Top; width = $w; height = $ht
+    is_foreground = ($h -eq $fg); is_minimized = [NAWin32]::IsIconic($h)
+  })
+  return $true
+}
+[void][NAWin32]::EnumWindows($cb, [IntPtr]::Zero)
+$list | ConvertTo-Json -Compress
+`;

apps/agent/src/capabilities/win-ps/prelude-image.ts

@@ -0,0 +1,226 @@
+/**
+ * 图像模板匹配预加载段（ZNCC 粗到精）
+ *
+ * 2026-10 从 window.ts 抽出（结构拆分，**内容逐字节不变**）。
+ * ⚠️ WIN_HELPER_PRELUDE 是本段与另外几段的拼接 —— 改动会直接影响常驻 PS 助手。
+ * 拆分以 tests/unit/win-prelude.test.mjs + prelude sha256 比对双重把关。
+ */
+
+/**
+ * 图像模板匹配预加载段（v15）。
+ *
+ * 动机：UIA 靠控件树、OCR 靠文字 —— **纯图标/无文字的控件**两者都抓不到（审查报告 §5.2 指出的盲区）。
+ * 做法：把模板图与屏幕区域都转灰度，做**零均值归一化互相关（ZNCC）**；
+ * 全分辨率逐像素太慢（3440×1440 屏 × 64×64 模板 ≈ 190 亿次），故**粗到精**：
+ *   ① 1/4 分辨率全图扫描（约 8000 万次）取候选
+ *   ② 对候选在全分辨率 ±10px 邻域精修
+ * 编译一次常驻（随助手预加载），运行时纯 native 循环。
+ * 亮度和对比度无关（ZNCC 归一化），故对主题/亮度变化不敏感。
+ */
+export const IMAGE_MATCH_PRELUDE = `
+Add-Type -AssemblyName System.Drawing
+# ⚠️ Add-Type 的老坑：-AssemblyName 只把程序集加载进 PowerShell 会话，
+#    编译 C# 时还必须显式 -ReferencedAssemblies，否则报「命名空间 System.Drawing
+#    中不存在 Imaging」。真机踩过：编译失败会让整个助手起不来，并伴随误导性的
+#    「找不到类型 System.Windows.Forms.SystemInformation」二次错误。
+Add-Type @"
+using System;
+using System.Collections.Generic;
+using System.Drawing;
+using System.Drawing.Imaging;
+using System.Runtime.InteropServices;
+
+public class NAImageMatch {
+  public class Hit { public int x; public int y; public int w; public int h; public double score; }
+
+  private static byte[] Gray(Bitmap src, out int w, out int h) {
+    w = src.Width; h = src.Height;
+    var dst = new byte[w * h];
+    var rect = new Rectangle(0, 0, w, h);
+    Bitmap bmp = src.PixelFormat == PixelFormat.Format24bppRgb ? src : src.Clone(rect, PixelFormat.Format24bppRgb);
+    var data = bmp.LockBits(rect, ImageLockMode.ReadOnly, PixelFormat.Format24bppRgb);
+    try {
+      int stride = data.Stride;
+      var buf = new byte[stride * h];
+      Marshal.Copy(data.Scan0, buf, 0, buf.Length);
+      for (int y = 0; y < h; y++) {
+        int row = y * stride;
+        for (int x = 0; x < w; x++) {
+          int i = row + x * 3;
+          // BGR -> luma (integer approximation of ITU-R BT.601)
+          dst[y * w + x] = (byte)((buf[i + 2] * 77 + buf[i + 1] * 150 + buf[i] * 29) >> 8);
+        }
+      }
+    } finally { bmp.UnlockBits(data); if (bmp != src) bmp.Dispose(); }
+    return dst;
+  }
+
+  // Area-average downscale (coarse search layer)
+  private static byte[] Downscale(byte[] src, int w, int h, int f, out int ow, out int oh) {
+    ow = w / f; oh = h / f;
+    var dst = new byte[ow * oh];
+    for (int y = 0; y < oh; y++) {
+      for (int x = 0; x < ow; x++) {
+        int sum = 0;
+        for (int dy = 0; dy < f; dy++) {
+          int row = (y * f + dy) * w;
+          for (int dx = 0; dx < f; dx++) sum += src[row + x * f + dx];
+        }
+        dst[y * ow + x] = (byte)(sum / (f * f));
+      }
+    }
+    return dst;
+  }
+
+  // Zero-mean normalized cross correlation; 1.0 = identical
+  private static double Zncc(byte[] S, int sw, int sx, int sy, byte[] T, int tw, int th) {
+    int n = tw * th;
+    double sumT = 0;
+    for (int i = 0; i < n; i++) sumT += T[i];
+    double meanT = sumT / n;
+
+    double sumS = 0;
+    for (int y = 0; y < th; y++) {
+      int row = (sy + y) * sw + sx;
+      for (int x = 0; x < tw; x++) sumS += S[row + x];
+    }
+    double meanS = sumS / n;
+
+    double num = 0, dS = 0, dT = 0;
+    for (int y = 0; y < th; y++) {
+      int row = (sy + y) * sw + sx;
+      int trow = y * tw;
+      for (int x = 0; x < tw; x++) {
+        double a = S[row + x] - meanS;
+        double b = T[trow + x] - meanT;
+        num += a * b; dS += a * a; dT += b * b;
+      }
+    }
+    double den = Math.Sqrt(dS * dT);
+    if (den < 1e-9) return 0;
+    return num / den;
+  }
+
+  /**
+   // (comment removed: ASCII only)
+   // (comment removed: ASCII only)
+   */
+  public static string Match(string screenPath, string templatePath, int maxResults, double threshold, int searchX, int searchY, int searchW, int searchH) {
+    var hits = new List<Hit>();
+    using (var screenBmp = new Bitmap(screenPath))
+    using (var tmplBmp = new Bitmap(templatePath)) {
+      int sw, sh, tw, th;
+      var S0 = Gray(screenBmp, out sw, out sh);
+      var T0 = Gray(tmplBmp, out tw, out th);
+      if (tw >= sw || th >= sh) return "[]";
+
+      // Guard: a flat template carries no gradient information, so correlation is
+      // undefined (ZNCC denominator ~ 0). Report it explicitly instead of silently
+      // returning no hits - a uniform crop usually means the wrong region was picked.
+      //
+      // NOTE: build all JSON/string literals with the char constant Q.
+      // Writing a backslash-quote inside a TS template literal collapses it to a bare
+      // quote and breaks the C# compile - this trap bit this file twice.
+      const char Q = '"';
+      var ci0 = System.Globalization.CultureInfo.InvariantCulture;
+      double tSum = 0, tSum2 = 0;
+      for (int i = 0; i < T0.Length; i++) { tSum += T0[i]; tSum2 += (double)T0[i] * T0[i]; }
+      double tMean = tSum / T0.Length;
+      double tVar = (tSum2 / T0.Length) - (tMean * tMean);
+      if (tVar < 4.0) {
+        return "[" + "{" + Q + "__error" + Q + ":" + Q + "template_has_no_contrast" + Q
+          + "," + Q + "variance" + Q + ":" + tVar.ToString("F2", ci0) + "}" + "]";
+      }
+
+      // Optional search window: crop a sub-image, then add the offset back to hit coords
+      int ox = 0, oy = 0;
+      if (searchW > 0 && searchH > 0) {
+        ox = Math.Max(0, Math.Min(searchX, sw - 1));
+        oy = Math.Max(0, Math.Min(searchY, sh - 1));
+        int w = Math.Min(searchW, sw - ox), h = Math.Min(searchH, sh - oy);
+        var sub = new byte[w * h];
+        for (int y = 0; y < h; y++) Array.Copy(S0, (oy + y) * sw + ox, sub, y * w, w);
+        S0 = sub; sw = w; sh = h;
+      }
+
+      const int F = 4;
+      int sw4, sh4, tw4, th4;
+      var S4 = Downscale(S0, sw, sh, F, out sw4, out sh4);
+      var T4 = Downscale(T0, tw, th, F, out tw4, out th4);
+
+      // (1) coarse scan: collect candidates.
+      // NOTE: the pre-filter must be MUCH looser than the final threshold.
+      // Downsampling lowers the correlation of the true position (typically 0.7-0.85
+      // for a 0.9+ full-res match), so a tight pre-filter discards the right answer
+      // before refinement ever runs (this exact bug made every match return empty).
+      var cands = new List<Hit>();
+      if (tw4 > 0 && th4 > 0 && tw4 <= sw4 && th4 <= sh4) {
+        double preFilter = Math.Max(0.30, threshold - 0.30);
+        double bestCoarse = -1; int bx4 = 0, by4 = 0;
+        for (int y = 0; y <= sh4 - th4; y++) {
+          for (int x = 0; x <= sw4 - tw4; x++) {
+            double sc = Zncc(S4, sw4, x, y, T4, tw4, th4);
+            if (sc > bestCoarse) { bestCoarse = sc; bx4 = x; by4 = y; }
+            if (sc >= preFilter) cands.Add(new Hit { x = x * F, y = y * F, w = tw, h = th, score = sc });
+          }
+        }
+        // Belt and braces: always keep the coarse best, even if it missed the pre-filter
+        if (bestCoarse > 0) {
+          bool seen = false;
+          foreach (var c in cands) { if (Math.Abs(c.x - bx4 * F) < F && Math.Abs(c.y - by4 * F) < F) { seen = true; break; } }
+          if (!seen) cands.Add(new Hit { x = bx4 * F, y = by4 * F, w = tw, h = th, score = bestCoarse });
+        }
+      }
+      cands.Sort((a, b) => b.score.CompareTo(a.score));
+      if (cands.Count > 40) cands.RemoveRange(40, cands.Count - 40);
+
+      // (2) refine at full resolution within a +/-F*2 neighborhood
+      foreach (var c in cands) {
+        double best = -1; int bx = c.x, by = c.y;
+        for (int dy = -F * 2; dy <= F * 2; dy++) {
+          for (int dx = -F * 2; dx <= F * 2; dx++) {
+            int x = c.x + dx, y = c.y + dy;
+            if (x < 0 || y < 0 || x + tw > sw || y + th > sh) continue;
+            double sc = Zncc(S0, sw, x, y, T0, tw, th);
+            if (sc > best) { best = sc; bx = x; by = y; }
+          }
+        }
+        if (best >= threshold) hits.Add(new Hit { x = bx + ox, y = by + oy, w = tw, h = th, score = best });
+      }
+
+      // (3) de-dup: non-maximum suppression (keep best within 8px)
+      hits.Sort((a, b) => b.score.CompareTo(a.score));
+      var final = new List<Hit>();
+      foreach (var h in hits) {
+        bool dup = false;
+        foreach (var f in final) {
+          if (Math.Abs(f.x - h.x) < 8 && Math.Abs(f.y - h.y) < 8) { dup = true; break; }
+        }
+        if (!dup) final.Add(h);
+        if (final.Count >= maxResults) break;
+      }
+
+      var parts = new List<string>();
+      foreach (var h in final) {
+        // Build JSON by concatenation; reuse the shared Q / ci0 declared above.
+        var ci = ci0;
+        parts.Add("{" + Q + "x" + Q + ":" + h.x.ToString(ci) + "," + Q + "y" + Q + ":" + h.y.ToString(ci)
+          + "," + Q + "width" + Q + ":" + h.w.ToString(ci) + "," + Q + "height" + Q + ":" + h.h.ToString(ci)
+          + "," + Q + "score" + Q + ":" + h.score.ToString("F4", ci) + "}");
+      }
+      return "[" + String.Join(",", parts.ToArray()) + "]";
+    }
+  }
+
+  // Capture a screen region to a file (avoids extra process round-trips)
+  public static string Capture(string outPath, int x, int y, int w, int h) {
+    using (var bmp = new Bitmap(w, h))
+    using (var g = Graphics.FromImage(bmp)) {
+      g.CopyFromScreen(x, y, 0, 0, new Size(w, h));
+      bmp.Save(outPath, ImageFormat.Png);
+    }
+    return outPath;
+  }
+}
+"@ -ReferencedAssemblies System.Drawing
+`;

apps/agent/src/capabilities/win-ps/prelude-ocr.ts

@@ -0,0 +1,37 @@
+/**
+ * OCR 引擎预加载段：截图 / DPI / WinRT 类型与 Await 辅助函数
+ *
+ * 2026-10 从 window.ts 抽出（结构拆分，**内容逐字节不变**）。
+ * ⚠️ WIN_HELPER_PRELUDE 是本段与另外几段的拼接 —— 改动会直接影响常驻 PS 助手。
+ * 拆分以 tests/unit/win-prelude.test.mjs + prelude sha256 比对双重把关。
+ */
+
+/**
+ * OCR 引擎预加载段（v14）：截图 / DPI / WinRT 类型与 Await 辅助函数。
+ * 注意：WinRT 类型加载用 try/catch 包住 —— 个别环境缺组件时只应让 OCR 退化，
+ * 不该让整个助手（连带 window.list/focus/UIA）起不来。
+ */
+export const OCR_PRELUDE = `
+Add-Type -AssemblyName System.Drawing
+Add-Type -AssemblyName System.Windows.Forms
+try {
+  Add-Type -AssemblyName System.Runtime.WindowsRuntime
+  Add-Type -TypeDefinition 'using System.Runtime.InteropServices; public class NADPI { [DllImport("user32.dll")] public static extern bool SetProcessDPIAware(); }'
+  [void][NADPI]::SetProcessDPIAware()
+  $null = [Windows.Media.Ocr.OcrEngine, Windows.Foundation, ContentType=WindowsRuntime]
+  $null = [Windows.Graphics.Imaging.BitmapDecoder, Windows.Foundation, ContentType=WindowsRuntime]
+  $null = [Windows.Storage.Streams.InMemoryRandomAccessStream, Windows.Foundation, ContentType=WindowsRuntime]
+  $null = [Windows.Storage.Streams.DataWriter, Windows.Foundation, ContentType=WindowsRuntime]
+  $null = [Windows.Graphics.Imaging.SoftwareBitmap, Windows.Foundation, ContentType=WindowsRuntime]
+  $script:asTaskGeneric = ([System.WindowsRuntimeSystemExtensions].GetMethods() | Where-Object { $_.Name -eq 'AsTask' -and $_.GetParameters().Count -eq 1 -and $_.GetParameters()[0].ParameterType.Name -eq 'IAsyncOperation\`1' })[0]
+  function global:Await($WinRtTask, $ResultType) {
+    $asTask = $script:asTaskGeneric.MakeGenericMethod($ResultType)
+    $netTask = $asTask.Invoke($null, @($WinRtTask))
+    $netTask.Wait(-1) | Out-Null
+    $netTask.Result
+  }
+  $script:ocrReady = $true
+} catch {
+  $script:ocrReady = $false
+}
+`;

apps/agent/src/capabilities/win-ps/prelude-uia.ts

@@ -0,0 +1,117 @@
+/**
+ * UIA 控件树预加载段（含 Where 谓词与属性读取）
+ *
+ * 2026-10 从 window.ts 抽出（结构拆分，**内容逐字节不变**）。
+ * ⚠️ WIN_HELPER_PRELUDE 是本段与另外几段的拼接 —— 改动会直接影响常驻 PS 助手。
+ * 拆分以 tests/unit/win-prelude.test.mjs + prelude sha256 比对双重把关。
+ */
+
+/**
+ * v14：常驻助手预加载段 —— 这些内容**只在助手启动时执行一次**。
+ * 过去每次调用都重新编译 C# / 加载程序集，真机实测占单次耗时的绝大部分
+ * （window.list 1267ms / window.focus 1631ms，其中「起进程+编译」是固定成本）。
+ */
+export const UIA_ASSEMBLY_PRELUDE = `
+Add-Type -AssemblyName UIAutomationClient
+Add-Type -AssemblyName UIAutomationTypes
+Add-Type -AssemblyName WindowsBase
+function Get-WinByTitle([string]$re) {
+  $root = [System.Windows.Automation.AutomationElement]::RootElement
+  $cond = New-Object System.Windows.Automation.PropertyCondition(
+    [System.Windows.Automation.AutomationElement]::ControlTypeProperty,
+    [System.Windows.Automation.ControlType]::Window)
+  $wins = $root.FindAll([System.Windows.Automation.TreeScope]::Children, $cond)
+  foreach ($w in $wins) {
+    try {
+      $t = $w.Current.Name
+      if ($t -and $t -match $re) { return $w }
+    } catch {}
+  }
+  return $null
+}
+
+# v14：按子串在给定 scope 内遍历查找（FindAll + 子串过滤）。
+# UIA 的 PropertyCondition 只能精确匹配，故必须遍历后过滤；遍历规模设上限防超大 UI 树卡死。
+# v23：读取元素的 UIA 属性（v1.7 语义属性化）。
+# 为什么逐个 try：ValuePattern / SelectionItemPattern / TogglePattern 并非所有控件
+# 都支持（不支持时 GetSupportedPattern 返回 false 或抛异常），而且**部分应用
+# （Electron / 游戏 UI）根本给不出值** —— 拿不到就留空，由上层判"未知"而非"false"。
+function Get-UiaProps($e) {
+  $enabled = $true
+  try { $enabled = [bool]$e.Current.IsEnabled } catch {}
+  $value = $null
+  try {
+    $vp = $e.GetCurrentPattern([System.Windows.Automation.ValuePattern]::Pattern)
+    if ($vp -ne $null) { $value = $vp.Current.Value }
+  } catch {}
+  $selected = $null
+  try {
+    $sp = $e.GetCurrentPattern([System.Windows.Automation.SelectionItemPattern]::Pattern)
+    if ($sp -ne $null) { $selected = [bool]$sp.Current.IsSelected }
+  } catch {}
+  $toggle = $null
+  try {
+    $tp = $e.GetCurrentPattern([System.Windows.Automation.TogglePattern]::Pattern)
+    if ($tp -ne $null) { $toggle = "$($tp.Current.ToggleState)" }
+  } catch {}
+  return @{ enabled = $enabled; value = $value; selected = $selected; toggle = $toggle }
+}
+
+function Test-UiaWhere($props, $where) {
+  if ($where -eq $null) { return $true }
+  foreach ($k in $where.Keys) {
+    $want = $where[$k]
+    switch ($k) {
+      'enabled'  { if ($props.enabled -ne [bool]$want) { return $false } }
+      'selected' { if ($null -eq $props.selected -or $props.selected -ne [bool]$want) { return $false } }
+      'value'    { if ($props.value -eq $null -or $props.value -notlike [string]$want) { return $false } }
+      default    { }   # 未知键忽略（Node 侧已白名单校验）
+      'toggle'   { if ($props.toggle -eq $null -or $props.toggle -notlike [string]$want) { return $false } }
+    }
+  }
+  return $true
+}
+
+function Find-UiaByText($scope, [string]$text, [int]$limit, [string]$ct, $where) {
+  $cond = [System.Windows.Automation.Condition]::TrueCondition
+  if ($ct -ne '') {
+    $ctObj = $null
+    try { $ctObj = [System.Windows.Automation.ControlType]::$ct } catch {}
+    if ($ctObj -ne $null) {
+      $cond = New-Object System.Windows.Automation.PropertyCondition(
+        [System.Windows.Automation.AutomitionElement]::ControlTypeProperty, $ctObj)
+    }
+  }
+  $found = $scope.FindAll([System.Windows.Automation.TreeScope]::Descendants, $cond)
+  $out = New-Object System.Collections.ArrayList
+  $scanned = 0
+  foreach ($e in $found) {
+    if ($out.Count -ge $limit) { break }
+    $scanned++
+    if ($scanned -gt 20000) { break }
+    try {
+      $nm = $e.Current.Name
+      if ([string]::IsNullOrEmpty($nm)) { continue }
+      if ($text -ne '' -and $nm.IndexOf($text, [System.StringComparison]::OrdinalIgnoreCase) -lt 0) { continue }
+      $r = $e.Current.BoundingRectangle
+      if ($r.Width -le 0 -or $r.Height -le 0) { continue }
+      $props = Get-UiaProps $e
+      if (-not (Test-UiaWhere $props $where)) { continue }
+      [void]$out.Add([pscustomobject]@{
+        name = $nm
+        control_type = ($e.Current.ControlType.ProgrammaticName -replace 'ControlType\\.','')
+        automation_id = $e.Current.AutomationId
+        x = [int]($r.Left + $r.Width / 2)
+        y = [int]($r.Top + $r.Height / 2)
+        left = [int]$r.Left; top = [int]$r.Top
+        width = [int]$r.Width; height = [int]$r.Height
+        enabled = $props.enabled
+        value = $props.value
+        selected = $props.selected
+        toggle = $props.toggle
+      })
+    } catch {}
+  }
+  return ,$out
+}
+`;

apps/agent/src/capabilities/win-ps/prelude-win32.ts

@@ -0,0 +1,30 @@
+/**
+ * Win32 窗口枚举与矩形读取（供 window.list / window.focus 复用）
+ *
+ * 2026-10 从 window.ts 抽出（结构拆分，**内容逐字节不变**）。
+ * ⚠️ WIN_HELPER_PRELUDE 是本段与另外几段的拼接 —— 改动会直接影响常驻 PS 助手。
+ * 拆分以 tests/unit/win-prelude.test.mjs + prelude sha256 比对双重把关。
+ */
+
+export const WIN32_PRELUDE = `
+Add-Type @"
+using System;
+using System.Text;
+using System.Runtime.InteropServices;
+public class NAWin32 {
+  [StructLayout(LayoutKind.Sequential)] public struct RECT { public int Left, Top, Right, Bottom; }
+  public delegate bool EnumProc(IntPtr hWnd, IntPtr lParam);
+  [DllImport("user32.dll")] public static extern bool EnumWindows(EnumProc cb, IntPtr p);
+  [DllImport("user32.dll")] public static extern bool IsWindowVisible(IntPtr h);
+  [DllImport("user32.dll")] public static extern bool IsIconic(IntPtr h);
+  [DllImport("user32.dll", CharSet=CharSet.Unicode)] public static extern int GetWindowTextW(IntPtr h, StringBuilder s, int n);
+  [DllImport("user32.dll")] public static extern bool GetWindowRect(IntPtr h, out RECT r);
+  [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
+  [DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr h);
+  [DllImport("user32.dll")] public static extern void mouse_event(uint f, int dx, int dy, uint d, UIntPtr e);
+  [DllImport("user32.dll")] public static extern bool SetCursorPos(int x, int y);
+  [DllImport("user32.dll")] public static extern bool ShowWindow(IntPtr h, int cmd);
+  [DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(IntPtr h, out uint pid);
+}
+"@
+`;

apps/agent/src/capabilities/window.ts

@@ -6,6 +6,12 @@ import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { macScreenFind, macWindowFocus, macWindowList } from './darwin.js';
 
+import { WIN32_PRELUDE } from './win-ps/prelude-win32.js';
+import { LIST_BODY } from './win-ps/body-list.js';
+import { UIA_ASSEMBLY_PRELUDE } from './win-ps/prelude-uia.js';
+import { OCR_PRELUDE } from './win-ps/prelude-ocr.js';
+import { IMAGE_MATCH_PRELUDE } from './win-ps/prelude-image.js';
+
 type Args = Record<string, unknown>;
 
 function toArray<T>(v: T | T[] | null | undefined): T[] {
@@ -80,381 +86,11 @@ function extractJson<T>(raw: string): T | null {
 }
 
 /** Win32 窗口枚举与矩形读取（供 window.list / window.focus 复用）。 */
-const WIN32_PRELUDE = `
-Add-Type @"
-using System;
-using System.Text;
-using System.Runtime.InteropServices;
-public class NAWin32 {
-  [StructLayout(LayoutKind.Sequential)] public struct RECT { public int Left, Top, Right, Bottom; }
-  public delegate bool EnumProc(IntPtr hWnd, IntPtr lParam);
-  [DllImport("user32.dll")] public static extern bool EnumWindows(EnumProc cb, IntPtr p);
-  [DllImport("user32.dll")] public static extern bool IsWindowVisible(IntPtr h);
-  [DllImport("user32.dll")] public static extern bool IsIconic(IntPtr h);
-  [DllImport("user32.dll", CharSet=CharSet.Unicode)] public static extern int GetWindowTextW(IntPtr h, StringBuilder s, int n);
-  [DllImport("user32.dll")] public static extern bool GetWindowRect(IntPtr h, out RECT r);
-  [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
-  [DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr h);
-  [DllImport("user32.dll")] public static extern void mouse_event(uint f, int dx, int dy, uint d, UIntPtr e);
-  [DllImport("user32.dll")] public static extern bool SetCursorPos(int x, int y);
-  [DllImport("user32.dll")] public static extern bool ShowWindow(IntPtr h, int cmd);
-  [DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(IntPtr h, out uint pid);
-}
-"@
-`;
 
-/**
- * 枚举可见顶层窗口 → JSON（**不含 prelude**，供常驻助手与一次性路径复用）。
- * 注意：本段会被送进常驻进程执行，**严禁出现 exit**（会杀掉助手进程）。
- */
-const LIST_BODY = `
-$fg = [NAWin32]::GetForegroundWindow()
-$list = New-Object System.Collections.ArrayList
-$cb = [NAWin32+EnumProc]{
-  param($h, $l)
-  if (-not [NAWin32]::IsWindowVisible($h)) { return $true }
-  $sb = New-Object System.Text.StringBuilder 512
-  [void][NAWin32]::GetWindowTextW($h, $sb, 512)
-  $title = $sb.ToString()
-  if ([string]::IsNullOrWhiteSpace($title)) { return $true }
-  $r = New-Object NAWin32+RECT
-  if (-not [NAWin32]::GetWindowRect($h, [ref]$r)) { return $true }
-  $w = $r.Right - $r.Left; $ht = $r.Bottom - $r.Top
-  if ($w -le 0 -or $ht -le 0) { return $true }
-  # ⚠️ 变量名不能叫 $pid —— 它是 PowerShell 的自动变量（当前进程 ID），赋值会被忽略，
-  #    导致所有窗口都报成 powershell 进程（真机踩过）。
-  $procId = 0
-  [void][NAWin32]::GetWindowThreadProcessId($h, [ref]$procId)
-  $pn = ''
-  try { $pn = (Get-Process -Id $procId -ErrorAction Stop).ProcessName } catch {}
-  [void]$list.Add([pscustomobject]@{
-    hwnd = ('0x{0:X}' -f $h.ToInt64()); title = $title; process = $pn; pid = $procId
-    x = $r.Left; y = $r.Top; width = $w; height = $ht
-    is_foreground = ($h -eq $fg); is_minimized = [NAWin32]::IsIconic($h)
-  })
-  return $true
-}
-[void][NAWin32]::EnumWindows($cb, [IntPtr]::Zero)
-$list | ConvertTo-Json -Compress
-`;
-
-/**
- * v14：常驻助手预加载段 —— 这些内容**只在助手启动时执行一次**。
- * 过去每次调用都重新编译 C# / 加载程序集，真机实测占单次耗时的绝大部分
- * （window.list 1267ms / window.focus 1631ms，其中「起进程+编译」是固定成本）。
- */
-const UIA_ASSEMBLY_PRELUDE = `
-Add-Type -AssemblyName UIAutomationClient
-Add-Type -AssemblyName UIAutomationTypes
-Add-Type -AssemblyName WindowsBase
-function Get-WinByTitle([string]$re) {
-  $root = [System.Windows.Automation.AutomationElement]::RootElement
-  $cond = New-Object System.Windows.Automation.PropertyCondition(
-    [System.Windows.Automation.AutomationElement]::ControlTypeProperty,
-    [System.Windows.Automation.ControlType]::Window)
-  $wins = $root.FindAll([System.Windows.Automation.TreeScope]::Children, $cond)
-  foreach ($w in $wins) {
-    try {
-      $t = $w.Current.Name
-      if ($t -and $t -match $re) { return $w }
-    } catch {}
-  }
-  return $null
-}
-
-# v14：按子串在给定 scope 内遍历查找（FindAll + 子串过滤）。
-# UIA 的 PropertyCondition 只能精确匹配，故必须遍历后过滤；遍历规模设上限防超大 UI 树卡死。
-function Find-UiaByText($scope, [string]$text, [int]$limit, [string]$ct) {
-  $cond = [System.Windows.Automation.Condition]::TrueCondition
-  if ($ct -ne '') {
-    $ctObj = $null
-    try { $ctObj = [System.Windows.Automation.ControlType]::$ct } catch {}
-    if ($ctObj -ne $null) {
-      $cond = New-Object System.Windows.Automation.PropertyCondition(
-        [System.Windows.Automation.AutomationElement]::ControlTypeProperty, $ctObj)
-    }
-  }
-  $found = $scope.FindAll([System.Windows.Automation.TreeScope]::Descendants, $cond)
-  $out = New-Object System.Collections.ArrayList
-  $scanned = 0
-  foreach ($e in $found) {
-    if ($out.Count -ge $limit) { break }
-    $scanned++
-    if ($scanned -gt 20000) { break }
-    try {
-      $nm = $e.Current.Name
-      if ([string]::IsNullOrEmpty($nm)) { continue }
-      if ($nm.IndexOf($text, [System.StringComparison]::OrdinalIgnoreCase) -lt 0) { continue }
-      $r = $e.Current.BoundingRectangle
-      if ($r.Width -le 0 -or $r.Height -le 0) { continue }
-      [void]$out.Add([pscustomobject]@{
-        name = $nm
-        control_type = ($e.Current.ControlType.ProgrammaticName -replace 'ControlType\\.','')
-        automation_id = $e.Current.AutomationId
-        x = [int]($r.Left + $r.Width / 2)
-        y = [int]($r.Top + $r.Height / 2)
-        left = [int]$r.Left; top = [int]$r.Top
-        width = [int]$r.Width; height = [int]$r.Height
-      })
-    } catch {}
-  }
-  return ,$out
-}
-`;
 
 /** 助手统一预加载段（window.list / window.focus / screen.find 共用同一个进程）。 */
 
 
-/**
- * OCR 引擎预加载段（v14）：截图 / DPI / WinRT 类型与 Await 辅助函数。
- * 注意：WinRT 类型加载用 try/catch 包住 —— 个别环境缺组件时只应让 OCR 退化，
- * 不该让整个助手（连带 window.list/focus/UIA）起不来。
- */
-const OCR_PRELUDE = `
-Add-Type -AssemblyName System.Drawing
-Add-Type -AssemblyName System.Windows.Forms
-try {
-  Add-Type -AssemblyName System.Runtime.WindowsRuntime
-  Add-Type -TypeDefinition 'using System.Runtime.InteropServices; public class NADPI { [DllImport("user32.dll")] public static extern bool SetProcessDPIAware(); }'
-  [void][NADPI]::SetProcessDPIAware()
-  $null = [Windows.Media.Ocr.OcrEngine, Windows.Foundation, ContentType=WindowsRuntime]
-  $null = [Windows.Graphics.Imaging.BitmapDecoder, Windows.Foundation, ContentType=WindowsRuntime]
-  $null = [Windows.Storage.Streams.InMemoryRandomAccessStream, Windows.Foundation, ContentType=WindowsRuntime]
-  $null = [Windows.Storage.Streams.DataWriter, Windows.Foundation, ContentType=WindowsRuntime]
-  $null = [Windows.Graphics.Imaging.SoftwareBitmap, Windows.Foundation, ContentType=WindowsRuntime]
-  $script:asTaskGeneric = ([System.WindowsRuntimeSystemExtensions].GetMethods() | Where-Object { $_.Name -eq 'AsTask' -and $_.GetParameters().Count -eq 1 -and $_.GetParameters()[0].ParameterType.Name -eq 'IAsyncOperation\`1' })[0]
-  function global:Await($WinRtTask, $ResultType) {
-    $asTask = $script:asTaskGeneric.MakeGenericMethod($ResultType)
-    $netTask = $asTask.Invoke($null, @($WinRtTask))
-    $netTask.Wait(-1) | Out-Null
-    $netTask.Result
-  }
-  $script:ocrReady = $true
-} catch {
-  $script:ocrReady = $false
-}
-`;
-
-
-/**
- * 图像模板匹配预加载段（v15）。
- *
- * 动机：UIA 靠控件树、OCR 靠文字 —— **纯图标/无文字的控件**两者都抓不到（审查报告 §5.2 指出的盲区）。
- * 做法：把模板图与屏幕区域都转灰度，做**零均值归一化互相关（ZNCC）**；
- * 全分辨率逐像素太慢（3440×1440 屏 × 64×64 模板 ≈ 190 亿次），故**粗到精**：
- *   ① 1/4 分辨率全图扫描（约 8000 万次）取候选
- *   ② 对候选在全分辨率 ±10px 邻域精修
- * 编译一次常驻（随助手预加载），运行时纯 native 循环。
- * 亮度和对比度无关（ZNCC 归一化），故对主题/亮度变化不敏感。
- */
-const IMAGE_MATCH_PRELUDE = `
-Add-Type -AssemblyName System.Drawing
-# ⚠️ Add-Type 的老坑：-AssemblyName 只把程序集加载进 PowerShell 会话，
-#    编译 C# 时还必须显式 -ReferencedAssemblies，否则报「命名空间 System.Drawing
-#    中不存在 Imaging」。真机踩过：编译失败会让整个助手起不来，并伴随误导性的
-#    「找不到类型 System.Windows.Forms.SystemInformation」二次错误。
-Add-Type @"
-using System;
-using System.Collections.Generic;
-using System.Drawing;
-using System.Drawing.Imaging;
-using System.Runtime.InteropServices;
-
-public class NAImageMatch {
-  public class Hit { public int x; public int y; public int w; public int h; public double score; }
-
-  private static byte[] Gray(Bitmap src, out int w, out int h) {
-    w = src.Width; h = src.Height;
-    var dst = new byte[w * h];
-    var rect = new Rectangle(0, 0, w, h);
-    Bitmap bmp = src.PixelFormat == PixelFormat.Format24bppRgb ? src : src.Clone(rect, PixelFormat.Format24bppRgb);
-    var data = bmp.LockBits(rect, ImageLockMode.ReadOnly, PixelFormat.Format24bppRgb);
-    try {
-      int stride = data.Stride;
-      var buf = new byte[stride * h];
-      Marshal.Copy(data.Scan0, buf, 0, buf.Length);
-      for (int y = 0; y < h; y++) {
-        int row = y * stride;
-        for (int x = 0; x < w; x++) {
-          int i = row + x * 3;
-          // BGR -> luma (integer approximation of ITU-R BT.601)
-          dst[y * w + x] = (byte)((buf[i + 2] * 77 + buf[i + 1] * 150 + buf[i] * 29) >> 8);
-        }
-      }
-    } finally { bmp.UnlockBits(data); if (bmp != src) bmp.Dispose(); }
-    return dst;
-  }
-
-  // Area-average downscale (coarse search layer)
-  private static byte[] Downscale(byte[] src, int w, int h, int f, out int ow, out int oh) {
-    ow = w / f; oh = h / f;
-    var dst = new byte[ow * oh];
-    for (int y = 0; y < oh; y++) {
-      for (int x = 0; x < ow; x++) {
-        int sum = 0;
-        for (int dy = 0; dy < f; dy++) {
-          int row = (y * f + dy) * w;
-          for (int dx = 0; dx < f; dx++) sum += src[row + x * f + dx];
-        }
-        dst[y * ow + x] = (byte)(sum / (f * f));
-      }
-    }
-    return dst;
-  }
-
-  // Zero-mean normalized cross correlation; 1.0 = identical
-  private static double Zncc(byte[] S, int sw, int sx, int sy, byte[] T, int tw, int th) {
-    int n = tw * th;
-    double sumT = 0;
-    for (int i = 0; i < n; i++) sumT += T[i];
-    double meanT = sumT / n;
-
-    double sumS = 0;
-    for (int y = 0; y < th; y++) {
-      int row = (sy + y) * sw + sx;
-      for (int x = 0; x < tw; x++) sumS += S[row + x];
-    }
-    double meanS = sumS / n;
-
-    double num = 0, dS = 0, dT = 0;
-    for (int y = 0; y < th; y++) {
-      int row = (sy + y) * sw + sx;
-      int trow = y * tw;
-      for (int x = 0; x < tw; x++) {
-        double a = S[row + x] - meanS;
-        double b = T[trow + x] - meanT;
-        num += a * b; dS += a * a; dT += b * b;
-      }
-    }
-    double den = Math.Sqrt(dS * dT);
-    if (den < 1e-9) return 0;
-    return num / den;
-  }
-
-  /**
-   // (comment removed: ASCII only)
-   // (comment removed: ASCII only)
-   */
-  public static string Match(string screenPath, string templatePath, int maxResults, double threshold, int searchX, int searchY, int searchW, int searchH) {
-    var hits = new List<Hit>();
-    using (var screenBmp = new Bitmap(screenPath))
-    using (var tmplBmp = new Bitmap(templatePath)) {
-      int sw, sh, tw, th;
-      var S0 = Gray(screenBmp, out sw, out sh);
-      var T0 = Gray(tmplBmp, out tw, out th);
-      if (tw >= sw || th >= sh) return "[]";
-
-      // Guard: a flat template carries no gradient information, so correlation is
-      // undefined (ZNCC denominator ~ 0). Report it explicitly instead of silently
-      // returning no hits - a uniform crop usually means the wrong region was picked.
-      //
-      // NOTE: build all JSON/string literals with the char constant Q.
-      // Writing a backslash-quote inside a TS template literal collapses it to a bare
-      // quote and breaks the C# compile - this trap bit this file twice.
-      const char Q = '"';
-      var ci0 = System.Globalization.CultureInfo.InvariantCulture;
-      double tSum = 0, tSum2 = 0;
-      for (int i = 0; i < T0.Length; i++) { tSum += T0[i]; tSum2 += (double)T0[i] * T0[i]; }
-      double tMean = tSum / T0.Length;
-      double tVar = (tSum2 / T0.Length) - (tMean * tMean);
-      if (tVar < 4.0) {
-        return "[" + "{" + Q + "__error" + Q + ":" + Q + "template_has_no_contrast" + Q
-          + "," + Q + "variance" + Q + ":" + tVar.ToString("F2", ci0) + "}" + "]";
-      }
-
-      // Optional search window: crop a sub-image, then add the offset back to hit coords
-      int ox = 0, oy = 0;
-      if (searchW > 0 && searchH > 0) {
-        ox = Math.Max(0, Math.Min(searchX, sw - 1));
-        oy = Math.Max(0, Math.Min(searchY, sh - 1));
-        int w = Math.Min(searchW, sw - ox), h = Math.Min(searchH, sh - oy);
-        var sub = new byte[w * h];
-        for (int y = 0; y < h; y++) Array.Copy(S0, (oy + y) * sw + ox, sub, y * w, w);
-        S0 = sub; sw = w; sh = h;
-      }
-
-      const int F = 4;
-      int sw4, sh4, tw4, th4;
-      var S4 = Downscale(S0, sw, sh, F, out sw4, out sh4);
-      var T4 = Downscale(T0, tw, th, F, out tw4, out th4);
-
-      // (1) coarse scan: collect candidates.
-      // NOTE: the pre-filter must be MUCH looser than the final threshold.
-      // Downsampling lowers the correlation of the true position (typically 0.7-0.85
-      // for a 0.9+ full-res match), so a tight pre-filter discards the right answer
-      // before refinement ever runs (this exact bug made every match return empty).
-      var cands = new List<Hit>();
-      if (tw4 > 0 && th4 > 0 && tw4 <= sw4 && th4 <= sh4) {
-        double preFilter = Math.Max(0.30, threshold - 0.30);
-        double bestCoarse = -1; int bx4 = 0, by4 = 0;
-        for (int y = 0; y <= sh4 - th4; y++) {
-          for (int x = 0; x <= sw4 - tw4; x++) {
-            double sc = Zncc(S4, sw4, x, y, T4, tw4, th4);
-            if (sc > bestCoarse) { bestCoarse = sc; bx4 = x; by4 = y; }
-            if (sc >= preFilter) cands.Add(new Hit { x = x * F, y = y * F, w = tw, h = th, score = sc });
-          }
-        }
-        // Belt and braces: always keep the coarse best, even if it missed the pre-filter
-        if (bestCoarse > 0) {
-          bool seen = false;
-          foreach (var c in cands) { if (Math.Abs(c.x - bx4 * F) < F && Math.Abs(c.y - by4 * F) < F) { seen = true; break; } }
-          if (!seen) cands.Add(new Hit { x = bx4 * F, y = by4 * F, w = tw, h = th, score = bestCoarse });
-        }
-      }
-      cands.Sort((a, b) => b.score.CompareTo(a.score));
-      if (cands.Count > 40) cands.RemoveRange(40, cands.Count - 40);
-
-      // (2) refine at full resolution within a +/-F*2 neighborhood
-      foreach (var c in cands) {
-        double best = -1; int bx = c.x, by = c.y;
-        for (int dy = -F * 2; dy <= F * 2; dy++) {
-          for (int dx = -F * 2; dx <= F * 2; dx++) {
-            int x = c.x + dx, y = c.y + dy;
-            if (x < 0 || y < 0 || x + tw > sw || y + th > sh) continue;
-            double sc = Zncc(S0, sw, x, y, T0, tw, th);
-            if (sc > best) { best = sc; bx = x; by = y; }
-          }
-        }
-        if (best >= threshold) hits.Add(new Hit { x = bx + ox, y = by + oy, w = tw, h = th, score = best });
-      }
-
-      // (3) de-dup: non-maximum suppression (keep best within 8px)
-      hits.Sort((a, b) => b.score.CompareTo(a.score));
-      var final = new List<Hit>();
-      foreach (var h in hits) {
-        bool dup = false;
-        foreach (var f in final) {
-          if (Math.Abs(f.x - h.x) < 8 && Math.Abs(f.y - h.y) < 8) { dup = true; break; }
-        }
-        if (!dup) final.Add(h);
-        if (final.Count >= maxResults) break;
-      }
-
-      var parts = new List<string>();
-      foreach (var h in final) {
-        // Build JSON by concatenation; reuse the shared Q / ci0 declared above.
-        var ci = ci0;
-        parts.Add("{" + Q + "x" + Q + ":" + h.x.ToString(ci) + "," + Q + "y" + Q + ":" + h.y.ToString(ci)
-          + "," + Q + "width" + Q + ":" + h.w.ToString(ci) + "," + Q + "height" + Q + ":" + h.h.ToString(ci)
-          + "," + Q + "score" + Q + ":" + h.score.ToString("F4", ci) + "}");
-      }
-      return "[" + String.Join(",", parts.ToArray()) + "]";
-    }
-  }
-
-  // Capture a screen region to a file (avoids extra process round-trips)
-  public static string Capture(string outPath, int x, int y, int w, int h) {
-    using (var bmp = new Bitmap(w, h))
-    using (var g = Graphics.FromImage(bmp)) {
-      g.CopyFromScreen(x, y, 0, 0, new Size(w, h));
-      bmp.Save(outPath, ImageFormat.Png);
-    }
-    return outPath;
-  }
-}
-"@ -ReferencedAssemblies System.Drawing
-`;
-
 /**
  * 助手统一预加载段（window.list / window.focus / screen.find 的 UIA/OCR/图像三引擎共用）。
  * ⚠️ 必须定义在四段之后（块级作用域），且**四段缺一不可** ——
@@ -664,11 +300,26 @@ export async function screenFind(args: Args): Promise<unknown> {
   }
   const text = (args['text'] as string | undefined) ?? '';
   const wantImage = (args['method'] as string | undefined) === 'image';
-  if (!wantImage && (typeof text !== 'string' || text.length === 0)) {
-    throw new CapabilityError(ErrorCodes.PARAM_INVALID, 'text 不能为空（method=image 时用 template 代替）');
+  // v1.8 修正：`where` 可单独使用（不传 text）——「找一个 enabled 的按钮」比
+  // 「找一个叫某名字的按钮」更贴近真实意图。此前只在 gui.await 侧放开了，
+  // screen.find 自身的入口校验没同步，导致直连调用（以及 await 的 where-only）
+  // 被这里的"text 不能为空"拦下（真机 2026-10-09 验证时暴露）。
+  const hasWhere = (() => {
+    const w = args['where'];
+    return typeof w === 'object' && w !== null && !Array.isArray(w) && Object.keys(w as object).length > 0;
+  })();
+  if (!wantImage && text.length === 0 && !hasWhere) {
+    throw new CapabilityError(
+      ErrorCodes.PARAM_INVALID,
+      'text 与 where 至少给一个（method=image 时用 template）',
+      { hint: 'where 仅 UIA 引擎生效，如 {"enabled":true}' },
+    );
   }
   const windowTitle = args['window'] as string | undefined;
   const controlType = args['control_type'] as string | undefined;
+  // v1.7：属性谓词。仅 UIA 引擎生效；OCR / 图像模板忽略（无属性可读），
+  // 此时在返回里带 note 说明，避免调用方误以为"按属性过滤过了"。
+  const whereArg = args['where'] as Record<string, unknown> | undefined;
   const limit = (args['limit'] as number | undefined) ?? 20;
   const method = (args['method'] as string | undefined) ?? 'auto'; // auto | uia | ocr
   // v12.2：等待语义 —— 界面常有动画/加载延迟，一次性查找极易假失败。
@@ -691,12 +342,33 @@ $text = ${JSON.stringify(text)}
 $limit = ${Number(limit)}
 $ct = ${JSON.stringify(controlType ?? '')}
 $winTitle = ${JSON.stringify(windowTitle ?? '')}
+# v1.7 属性过滤：where 只含 enabled/selected/value/toggle 四类键（白名单式）。
+#
+# ⚠️⚠️ 这里踩过**两次**同一个坑，真机 2026-10-09 连修两轮才通：
+#   ✗ 第一版：$where = {"enabled":true}          → PS 不认 JSON 字面量，ParseError
+#   ✗ 第二版：$whereJson = "{\"enabled\":true}" → PS 5.1 **不认反斜杠转义**
+#              （PS 用反引号），依然 ParseError，整份助手脚本失败
+#              （症状：带 where 一律"窗口操作失败"，不带 where 完全正常）
+#   ✓ 第三版：**PS 单引号字符串字面量**，JSON 内的单引号翻倍成 ''（本行）
+# 并在真机现场验证过：$j = '{"enabled":true}' → ConvertFrom-Json 摊平成哈希表 → OK。
+# 摊平是因为 Test-UiaWhere 依赖 .Keys 遍历，而 PSCustomObject 没有 Keys。
+$whereJson = '${(whereArg ? JSON.stringify(whereArg) : '').replace(/'/g, "''")}'
+$where = $null
+if ($whereJson -ne '') {
+  $where = @{}
+  try {
+    ($whereJson | ConvertFrom-Json).PSObject.Properties | ForEach-Object { $where[$_.Name] = $_.Value }
+  } catch {
+    $where = $null   # JSON 不合法就当没传（业务层已在 Node 侧校验过键名）
+  }
+  if ($where -ne $null -and $where.Count -eq 0) { $where = $null }
+}
 $out = New-Object System.Collections.ArrayList
 if ($winTitle -ne '') {
   # 指定窗口：直接在该窗口子树内找
   $w = Get-WinByTitle $winTitle
   if ($w -eq $null) { Write-Output '[]'; return }   # 严禁 exit：会杀掉常驻助手
-  $out = Find-UiaByText $w $text $limit $ct
+  $out = Find-UiaByText $w $text $limit $ct $where
 } else {
   # v14 优化：先在前台窗口子树内找（典型只几百个元素，快一个数量级），
   # 找不到再退回全桌面遍历（原来每次都在全桌面上跑，真机实测 3.1~3.7s）。
@@ -704,9 +376,9 @@ if ($winTitle -ne '') {
   try {
     $fgEl = [System.Windows.Automation.AutomationElement]::FromHandle([NAWin32]::GetForegroundWindow())
   } catch {}
-  if ($fgEl -ne $null) { $out = Find-UiaByText $fgEl $text $limit $ct }
+  if ($fgEl -ne $null) { $out = Find-UiaByText $fgEl $text $limit $ct $where }
   if ($out.Count -eq 0) {
-    $out = Find-UiaByText ([System.Windows.Automation.AutomationElement]::RootElement) $text $limit $ct
+    $out = Find-UiaByText ([System.Windows.Automation.AutomationElement]::RootElement) $text $limit $ct $where
   }
 }
 # ── 输出 ──（遍历与子串过滤已收敛到预加载的 Find-UiaByText，避免逻辑重复）
@@ -954,10 +626,22 @@ $out | ConvertTo-Json -Compress
     await new Promise((r) => setTimeout(r, intervalMs));
     last = await attempt();
   }
+  // v1.8：where 只在 UIA 引擎下有属性可读 —— 若最终走的是 OCR/image，
+  // 必须**明确告知**，否则调用方会以为"按属性过滤过了"而误判结果。
+  const whereIgnored = hasWhere && last.engine !== 'uia';
   return {
     matches: last.matches,
     engine: last.engine,
     waited_ms: Date.now() - startedAt,
     ...(waitMs > 0 ? { wait_ms: waitMs } : {}),
+    ...(whereIgnored
+      ? {
+          note:
+            `where 已忽略：实际引擎为 ${last.engine}（无控件属性可读）。` +
+            '属性过滤仅在 UIA 生效；text 过滤仍然有效。',
+          where_applied: false,
+        }
+      : {}),
+    ...(hasWhere && last.engine === 'uia' ? { where_applied: true } : {}),
   };
 }

apps/agent/src/config.ts

@@ -41,6 +41,19 @@ export interface AgentConfig {
    *   "allow_from": ["192.168.0.0/16", "10.0.0.0/8"]
    */
   allow_from?: string[];
+
+  /**
+   * v23 连接层防护（三项，默认值见 server.ts）。
+   * 单项缺省即启用默认策略；显式设 0 可关闭对应项。
+   */
+  security?: {
+    /** 握手失败封禁：同来源连续失败 max_attempts 次起，ban = ban_ms × 2^(N-max)，封顶 24h */
+    auth_ban?: { max_attempts?: number; ban_ms?: number; whitelist?: string[] };
+    /** 最大并发连接数（默认 8） */
+    max_connections?: number;
+    /** 空闲断开（默认 30 分钟；0 = 关闭） */
+    idle_timeout_ms?: number;
+  };
   /** v3+：审计日志配置 */
   audit?: {
     /** 是否启用（默认 true） */

apps/agent/src/events.ts

@@ -261,6 +261,11 @@ export async function eventPoll(args: Args): Promise<unknown> {
 }
 
 /** 连接断开时清理该连接创建的所有订阅（避免 watcher 泄漏）。 */
+/** v23：当前事件订阅数（空闲断开的豁免判据之一）。 */
+export function watchCount(): number {
+  return watches.size;
+}
+
 export function disposeWatchesByOwner(owner: string): number {
   let n = 0;
   for (const [id, rec] of watches) {

apps/agent/src/server.ts

@@ -30,7 +30,8 @@ import {
 import { buildInfo } from './capabilities/system.js';
 import { createCapabilityRegistry } from './capabilities/index.js';
 import { audit, describeArgs } from './audit.js';
-import { disposeWatchesByOwner } from './events.js';
+import { disposeWatchesByOwner, watchCount } from './events.js';
+import { runningTaskCount } from './capabilities/task.js';
 import type { AgentConfig } from './config.js';
 import type { TlsMaterial } from './certs.js';
 
@@ -47,6 +48,8 @@ interface ConnState {
   remote: string;
   /** v12：连接标识，用于清理该连接创建的事件订阅 */
   connId: string;
+  /** v23：末次活跃时间（任何入站消息），空闲断开的依据 */
+  lastActiveAt: number;
 }
 
 export interface AgentServer {
@@ -61,6 +64,10 @@ type LogLevel = 'debug' | 'info' | 'warn';
 export interface AgentCore {
   /** 在给定连接上提供被控端服务（连接已建立）。 */
   attach(ws: WebSocket, remote: string): void;
+  /** v23：该来源封禁剩余毫秒（0 = 不挡）。连接入口在业务握手前调用。 */
+  banRemainingMs(remote: string): number;
+  /** v23：连接表（并发上限 / 空闲清扫判据；key 为 WebSocket）。 */
+  states: Map<WebSocket, ConnState>;
 }
 
 export function createAgentCore(cfg: AgentConfig): AgentCore {
@@ -93,7 +100,9 @@ export function createAgentCore(cfg: AgentConfig): AgentCore {
     }
   };
 
-  const states = new WeakMap<WebSocket, ConnState>();
+  // v23：用 Map 而非 WeakMap —— 连接层需要 size（并发上限）与遍历（空闲清扫）。
+  // 代价是必须手动清理：close 时 delete，否则断开的连接会一直留在表里。
+  const states = new Map<WebSocket, ConnState>();
 
   const send = (ws: WebSocket, msg: unknown): void => {
     if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(msg));
@@ -122,12 +131,25 @@ export function createAgentCore(cfg: AgentConfig): AgentCore {
 
   function handleAuth(ws: WebSocket, state: ConnState, req: RpcRequest): void {
     const params = req.params as AuthParams | undefined;
+    const failOut = (msg: string, hint?: string): void => {
+      const ban = recordAuthFailure(state.remote);
+      audit({ type: 'auth.failure', client_id: params?.client_id ?? '?', remote: state.remote, reason: msg });
+      sendError(ws, req.id, ErrorCodes.AUTH_FAILED, msg, {
+        ...(hint ? { hint } : {}),
+        ...(ban.banned ? { retry_after_ms: ban.waitMs } : {}),
+      });
+      // 稍作延迟再关闭，确保错误响应先送达控制端
+      setTimeout(() => ws.close(), 100);
+    };
+
     if (!state.nonce || Date.now() > state.nonceExpiresAt) {
-      sendError(ws, req.id, ErrorCodes.AUTH_FAILED, '挑战已过期，请重新握手');
+      log('warn', '握手失败：挑战已过期');
+      failOut('挑战已过期，请重新握手');
       return;
     }
     if (params?.nonce !== state.nonce) {
-      sendError(ws, req.id, ErrorCodes.AUTH_FAILED, 'nonce 不匹配');
+      log('warn', '握手失败：nonce 不匹配');
+      failOut('nonce 不匹配', '请用 hello 返回的 nonce 计算签名');
       return;
     }
     const clientId = params.client_id ?? '?';
@@ -138,18 +160,12 @@ export function createAgentCore(cfg: AgentConfig): AgentCore {
       const client = aclPolicy.clients.find((c) => c.client_id === clientId);
       if (!client?.pubkey) {
         log('warn', `鉴权失败（调用方未注册）client_id=${clientId}`);
-        audit({ type: 'auth.failure', client_id: clientId, remote: state.remote, reason: '调用方未在 ACL 中注册' });
-        sendError(ws, req.id, ErrorCodes.AUTH_FAILED, `调用方未在 ACL 中注册: ${clientId}`, {
-          hint: '在被控端 acl.clients 中加入该 client_id 与公钥',
-        });
-        setTimeout(() => ws.close(), 100);
+        failOut(`调用方未在 ACL 中注册: ${clientId}`, '在被控端 acl.clients 中加入该 client_id 与公钥');
         return;
       }
       if (!verifyNonce(client.pubkey, state.nonce, params.signature ?? '')) {
         log('warn', `鉴权失败（Ed25519 验签不通过）client_id=${clientId}`);
-        audit({ type: 'auth.failure', client_id: clientId, remote: state.remote, reason: 'Ed25519 验签失败' });
-        sendError(ws, req.id, ErrorCodes.AUTH_FAILED, 'Ed25519 签名校验失败');
-        setTimeout(() => ws.close(), 100);
+        failOut('Ed25519 签名校验失败', '确认用的是该 client_id 对应的私钥');
         return;
       }
       authorized = authorizedCapabilities(
@@ -165,17 +181,9 @@ export function createAgentCore(cfg: AgentConfig): AgentCore {
       const keyKind = scopedKey ? 'scoped' : cfg.keys ? 'shared-fallback' : 'shared';
       if (!keyForClient || !verifyHmac(keyForClient, state.nonce, params.hmac ?? '')) {
         log('warn', `鉴权失败 client_id=${clientId} key=${keyKind}`);
-        audit({
-          type: 'auth.failure',
-          client_id: clientId,
-          remote: state.remote,
-          reason: scopedKey
-            ? '该 client_id 的专属密钥校验失败'
-            : '预共享密钥校验失败（未登记专属密钥，已回落到共享 key）',
-        });
-        sendError(ws, req.id, ErrorCodes.AUTH_FAILED, '预共享密钥校验失败');
-        // 稍作延迟再关闭，确保错误响应先送达控制端
-        setTimeout(() => ws.close(), 100);
+        failOut('预共享密钥校验失败', scopedKey
+          ? '该 client_id 有专属密钥，需用那把 key'
+          : '用错了 key，或该 client_id 应登记到 keys{}');
         return;
       }
       keyKindUsed = keyKind;
@@ -183,6 +191,7 @@ export function createAgentCore(cfg: AgentConfig): AgentCore {
 
     state.nonce = null; // 一次性，用后即废
     state.nonceExpiresAt = 0;
+    recordAuthSuccess(state.remote); // v23：握手成功即清零失败计数（避免误伤手滑的控制端）
     state.authenticated = true;
     state.clientId = clientId;
     state.authorized = authorized;
@@ -405,6 +414,49 @@ export function createAgentCore(cfg: AgentConfig): AgentCore {
     }
   }
 
+  // ---------- v23 连接层防护：握手失败封禁 ----------
+  // 状态放在 core：handleAuth 在此函数内，且 server 侧连接入口也要查它。
+  interface BanState { fails: number; bannedUntil: number }
+  const authBan = new Map<string, BanState>();
+  const banMax = Math.max(1, cfg.security?.auth_ban?.max_attempts ?? 5);
+  const banBaseMs = Math.max(1000, cfg.security?.auth_ban?.ban_ms ?? 600_000);
+  const banWhitelist = (cfg.security?.auth_ban?.whitelist ?? []).map((x) => x.trim()).filter(Boolean);
+
+  /** 归一化来源 IP：剥离 IPv4-mapped 前缀（::ffff:1.2.3.4 → 1.2.3.4），否则同一来源会被当成两个键。 */
+  const normIp = (addr: string): string => addr.replace(/^::ffff:/i, '');
+
+  /** 该来源还有多久解封（0 = 不在封禁期）。白名单来源永不封禁。 */
+  function banRemainingMs(remote: string): number {
+    const ip = normIp(remote);
+    if (banWhitelist.includes(ip)) return 0;
+    const st = authBan.get(ip);
+    if (!st) return 0;
+    const left = st.bannedUntil - Date.now();
+    return left > 0 ? left : 0; // 已过期则不挡（计数保留，继续指数退避）
+  }
+
+  /** 记录一次握手失败；返回本次是否**新触发**封禁（好让错误响应带上 retry_after_ms）。 */
+  function recordAuthFailure(remote: string): { banned: boolean; waitMs: number } {
+    const ip = normIp(remote);
+    if (banWhitelist.includes(ip)) return { banned: false, waitMs: 0 };
+    const prev = authBan.get(ip) ?? { fails: 0, bannedUntil: 0 };
+    const fails = prev.fails + 1;
+    if (fails < banMax) {
+      authBan.set(ip, { fails, bannedUntil: 0 });
+      return { banned: false, waitMs: 0 };
+    }
+    // 第 N 次失败起：ban = base × 2^(N - max)，封顶 24h
+    const power = Math.min(10, fails - banMax);
+    const waitMs = Math.min(86_400_000, banBaseMs * 2 ** power);
+    authBan.set(ip, { fails, bannedUntil: Date.now() + waitMs });
+    return { banned: true, waitMs };
+  }
+
+  function recordAuthSuccess(remote: string): void {
+    const ip = normIp(remote);
+    if (authBan.delete(ip)) log('info', `握手失败计数已清零（来源 ${ip} 本次认证成功）`);
+  }
+
   function attachConnection(ws: WebSocket, remote: string): void {
     log('info', `新连接: ${remote}`);
     const connId = `c_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
@@ -416,8 +468,12 @@ export function createAgentCore(cfg: AgentConfig): AgentCore {
       authorized: null,
       remote,
       connId,
+      lastActiveAt: Date.now(),
     });
     ws.on('message', (raw: RawData) => {
+      // v23：任何入站消息都算活跃（空闲断开以"完全静默"为准，不是"没有调用能力"）
+      const st = states.get(ws);
+      if (st) st.lastActiveAt = Date.now();
       void handleMessage(ws, raw.toString());
     });
     ws.on('close', () => {
@@ -425,11 +481,18 @@ export function createAgentCore(cfg: AgentConfig): AgentCore {
       // v12：连接断开即释放其事件订阅，避免 watcher 泄漏
       const n = disposeWatchesByOwner(connId);
       if (n > 0) log('debug', `已清理 ${n} 个事件订阅（连接 ${connId}）`);
+      states.delete(ws); // v23：Map 需手动清理（WeakMap 时代靠 GC）
     });
     ws.on('error', (err: Error) => log('warn', `连接错误: ${err.message}`));
   }
 
-  return { attach: attachConnection };
+  return {
+    attach: attachConnection,
+    /** v23：连接入口用 —— 该来源是否在封禁期（返回剩余毫秒，0=不挡）。 */
+    banRemainingMs,
+    /** v23：连接表（空闲清扫与并发上限判据）。 */
+    states,
+  };
 }
 
 /** 监听模式：被控端在本地起 HTTP(S) + WebSocket 服务。 */
@@ -449,6 +512,11 @@ export function createAgentServer(cfg: AgentConfig, tls: TlsMaterial | null): Pr
     : createHttpServer();
   const wss = new WebSocketServer({ server: httpServer });
 
+  // v23②：连接数上限（判定放在连接入口，见下方 wss.on('connection')）
+  const maxConnections = Math.max(1, cfg.security?.max_connections ?? 8);
+  // v23③：空闲断开阈值（0 = 关闭）
+  const idleTimeoutMs = Math.max(0, cfg.security?.idle_timeout_ms ?? 1_800_000);
+
   // v21 第一批加固：来源网段白名单 —— **在业务握手之前**就断开。
   // 放在这里而不是等认证失败，是因为拒绝得更早、开销更低（不必做 TLS/挑战应答）。
   wss.on('connection', (ws, req) => {
@@ -459,14 +527,42 @@ export function createAgentServer(cfg: AgentConfig, tls: TlsMaterial | null): Pr
       ws.close(1008, 'source not allowed');
       return;
     }
+    // v23①：封禁中的来源直接拒（在 TLS 之后、业务握手之前）
+    const bannedLeft = core.banRemainingMs(remote);
+    if (bannedLeft > 0) {
+      log('warn', `连接被拒绝：来源处于封禁期（remote=${remote}，剩余 ${Math.ceil(bannedLeft / 1000)}s）`);
+      audit({ type: 'net.deny', remote, reason: `auth banned, ${bannedLeft}ms left` });
+      ws.close(1008, `too many failed attempts, retry in ${Math.ceil(bannedLeft / 1000)}s`);
+      return;
+    }
+    // v23②：连接数上限
+    if (core.states.size >= maxConnections) {
+      log('warn', `连接被拒绝：已达并发上限 ${maxConnections}（current=${wss.clients.size}）`);
+      audit({ type: 'net.deny', remote, reason: `max connections reached: ${maxConnections}` });
+      ws.close(1013, 'too many connections');
+      return;
+    }
     core.attach(ws, remote);
   });
 
-  // WebSocket 层保活：30s ping，探测死连接
+  // WebSocket 层保活：30s ping，探测死连接；v23③ 同时做空闲连接清扫
   const heartbeat = setInterval(() => {
     for (const ws of wss.clients) {
       if (ws.readyState === WebSocket.OPEN) ws.ping();
     }
+    if (idleTimeoutMs <= 0) return;
+    // 保守策略：只要还有任务在跑 / 还有事件订阅，就不断任何连接 ——
+    // 宁可少断，也不能把"挂着长任务等结果"的控制端踢下线。
+    if (runningTaskCount() > 0 || watchCount() > 0) return;
+    const now = Date.now();
+    for (const [ws, st] of core.states) {
+      if (ws.readyState !== WebSocket.OPEN) continue;
+      const idleFor = now - st.lastActiveAt;
+      if (idleFor < idleTimeoutMs) continue;
+      log('info', `空闲断开：连接 ${st.connId}（${st.remote}）已静默 ${Math.round(idleFor / 1000)}s`);
+      audit({ type: 'session.idle_close', client_id: st.clientId ?? undefined, remote: st.remote, reason: `idle ${idleFor}ms` });
+      ws.close(1000, 'idle timeout');
+    }
   }, 30_000);
   heartbeat.unref();
 

apps/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodeagent/cli",
-  "version": "1.4.2",
+  "version": "2.0.0",
   "private": true,
   "type": "module",
   "main": "./dist/index.js",

apps/cli/src/cmd/gui.ts

@@ -25,6 +25,7 @@ import {
 } from '@nodeagent/client';
 import {
   CapabilityNames,
+  HOTKEY_PRESETS,
   matchPattern,
   DEFAULT_DISCOVERY_PORT,
   type CapabilityDescriptor,
@@ -61,7 +62,15 @@ export async function cmdScreen(opts: Options): Promise<void> {
 export async function cmdScreenshot(opts: Options): Promise<void> {
   const args: Record<string, unknown> = {};
   if (opts.format) args['format'] = opts.format;
-  if (opts.scale) args['scale'] = Number(opts.scale);
+  if (opts.scale) {
+    const s = Number(opts.scale);
+    // 协议限定 scale ∈ (0, 1]（缩小）。原先直接把非法值发出去，
+    // 被控端只回一句「参数校验失败」，看不出是哪一项 —— 2026-10-05 实测踩过。
+    if (!Number.isFinite(s) || s <= 0 || s > 1) {
+      fail(`--scale 应在 0 到 1 之间（1=原尺寸，0.5=半尺寸），收到: ${opts.scale}`);
+    }
+    args['scale'] = s;
+  }
   if (opts.region) {
     const nums = opts.region.split(',').map(Number);
     if (nums.length !== 4 || nums.some((n) => !Number.isFinite(n))) fail('--region 格式应为 x,y,width,height');
@@ -163,19 +172,57 @@ export async function cmdKey(action: string | undefined, positionals: string[],
       return;
     }
     case 'press': {
-      if (positionals.length === 0) fail('用法: nodeagent key press <键1> [键2] ...（如 ctrl c）');
+      // v1.5：三种用法（一次一种）
+      //   nodeagent key press "ctrl+shift+esc"     字符串热键
+      //   nodeagent key press copy                 预设名
+      //   nodeagent key press ctrl c               老形式（空格分隔的各键）
+      if (positionals.length === 0) fail('用法: nodeagent key press "<热键>" | <预设名> | <键1> [键2] ...（如 "ctrl+shift+esc" / copy / ctrl c）');
+      const args: Record<string, unknown> = {};
+      let positionalsEcho = positionals;
+      if (positionals.length === 1) {
+        const one = positionals[0]!;
+        // 含分隔符 → 字符串热键；不含但命中预设表 → 预设；都不中 → 单键（也当热键交给被控端解析）
+        const spec = HOTKEY_PRESETS[one.trim().toLowerCase()];
+        if (spec) {
+          args['preset'] = one.trim().toLowerCase();
+        } else {
+          args['hotkey'] = one;
+        }
+      } else {
+        args['keys'] = positionals;
+      }
+      // 老形式说明：位置参数以空格分隔 → 兼容"ctrl c"（无 + 号）
+      if (opts.interval) args['interval_ms'] = Number(opts.interval);
+      // v1.5 新增可选参数
+      if (opts.hold) args['hold_ms'] = Number(opts.hold);
+      if (opts.route) args['route'] = opts.route;
+      // 媒体键可定向到指定进程（播放器常建 30+ 辅助窗口，只投主窗口往往无效）
+      if (opts.pid) args['target_pid'] = Number(opts.pid);
       await withClient((c) =>
-        callAndPrint(c, CapabilityNames.KeyPress, { keys: positionals }, opts.json, (d) => {
+        callAndPrint(c, CapabilityNames.KeyPress, args, opts.json, (d) => {
           // 被控端返回 { pressed, chords, times }，**没有 keys 字段**
           // （真机 2026-10-04 实测：原先直接读 r.keys.join() 会抛
           //   "Cannot read properties of undefined (reading 'join')"）
           // 故优先用请求参数回显，缺失时再退回 chords 展开。
-          const r = d as { keys?: string[]; chords?: string[][]; times?: number };
+          const r = d as {
+            keys?: string[]; chords?: string[][]; times?: number; via?: string;
+            presets?: string[]; channel?: string; route?: string; sent_windows?: number;
+            target_pid?: number | null; note?: string;
+          };
+          const shown = (r.chords ?? []).map((ch) => ch.join('+')).join(' → ');
           const label = r.keys?.length
             ? r.keys.join('+')
-            : (r.chords ?? []).map((ch) => ch.join('+')).join(' → ') || positionals.join('+');
+            : shown || positionalsEcho.join('+');
           const times = r.times && r.times > 1 ? `（重复 ${r.times} 次）` : '';
-          console.log(`✓ 已按下 ${label}${times}`);
+          const presetEcho = r.presets?.length ? `（预设 ${r.presets.join('→')} = ${shown}）` : '';
+          const via =
+            r.channel === 'appcommand'
+              ? `（媒体通道${r.target_pid ? ` → pid ${r.target_pid}` : ' · 广播'}）`
+              : r.channel === 'postmessage'
+                ? `（后台投递 → pid ${r.target_pid}，命中 ${r.sent_windows ?? 0} 窗口）`
+                : '';
+          console.log(`✓ 已按下 ${label}${times}${presetEcho}${via}`);
+          if (r.note) console.log(`  ℹ️ ${r.note}`);
         }),
       );
       return;
@@ -185,6 +232,64 @@ export async function cmdKey(action: string | undefined, positionals: string[],
   }
 }
 
+// ---------- v1.6 等待条件（gui.await） ----------
+
+/**
+ * 等待一个条件成立再返回（只读低危）。
+ *
+ *   nodeagent await --condition control --text "完成" --timeout 30000
+ *   nodeagent await --condition window --title "安装程序"
+ *   nodeagent await --condition process --process setup.exe
+ *   nodeagent await --condition file --path "C:\\log.txt" --state absent
+ *
+ * 四类条件各自复用 window.list / screen.find / process.list / fs.stat，
+ * 平台行为与那些能力一致。超时是**正常返回**（satisfied:false + note），不抛异常。
+ */
+export async function cmdAwait(opts: Options): Promise<void> {
+  const condition = opts.condition as string | undefined;
+  if (!condition) {
+    fail('用法: nodeagent await --condition <window|control|process|file> --timeout <ms> [--text/--title/--process/--path] [--state absent]');
+  }
+  const args: Record<string, unknown> = { condition };
+  // v1.7：where / any_of 是 JSON 字符串（属性谓词与组合条件不便用命令行开关表达）
+  for (const k of ['where', 'any_of']) {
+    const raw = (opts as unknown as Record<string, string | undefined>)[k];
+    if (raw !== undefined) {
+      try {
+        args[k] = JSON.parse(raw);
+      } catch {
+        fail(`--${k} 不是合法 JSON: ${raw.slice(0, 60)}`);
+      }
+    }
+  }
+  if (opts.text !== undefined) args['text'] = opts.text;
+  if (opts.title !== undefined) args['title'] = opts.title;
+  if (opts.process !== undefined) args['process'] = opts.process;
+  if (opts.path !== undefined) args['path'] = opts.path;
+  if (opts.state !== undefined) args['state'] = opts.state;
+  if (opts.timeoutMs !== undefined) args['timeout_ms'] = Number(opts.timeoutMs);
+  if (opts.interval !== undefined) args['interval_ms'] = Number(opts.interval);
+  await withClient((c) =>
+    callAndPrint(c, CapabilityNames.GuiAwait, args, opts.json, (d) => {
+      const r = d as {
+        satisfied: boolean; condition: string; state: string;
+        elapsed_ms: number; attempts: number; last_seen: string; last_error?: string; note?: string;
+      };
+      const mark = r.satisfied ? '✓' : '✗';
+      const label = r.condition === 'control' ? String(args['text'] ?? '')
+        : r.condition === 'window' ? String(args['title'] ?? '')
+        : r.condition === 'process' ? String(args['process'] ?? '')
+        : String(args['path'] ?? '');
+      console.log(
+        `${mark} ${r.state === 'absent' ? '已消失' : '已出现'}: ${r.condition} ${label}` +
+          `（${r.elapsed_ms}ms，${r.attempts} 次轮询，末次=${r.last_seen}）`,
+      );
+      if (r.note) console.log(`  ℹ️ ${r.note}`);
+      if (r.last_error) console.log(`  ⚠️ 期间末次异常：${r.last_error.slice(0, 120)}`);
+    }),
+  );
+}
+
 // ---------- v3+ 审计 ----------
 
 /** v11：审计链完整性校验。 */

apps/cli/src/cmd/ops.ts

@@ -273,7 +273,10 @@ export async function cmdDeploy(localFile: string, opts: Options): Promise<void>
   const uploadInfo = await withClient(async (c) => {
     // 备份走协议自带的 fs 能力（而非 shell 的 Copy-Item）——
     // Copy-Item 是 Windows 专用，在 macOS 被控端上会静默失败（真机踩过：以为备份了，其实没有）。
-    const backup = `${target}.bak-${Date.now()}`;
+    // 备份用**固定名**（覆盖式）：此前用 `.bak-<时间戳>`，每部署一次就多一个文件 ——
+    // 真机 2026-10-09 发现 D:\Nodeagent 下堆了 15+ 个 bak（单文件 1MB，纯浪费）。
+    // 部署回滚只需要「上一个可用版本」，一份就够，故改为覆盖写。
+    const backup = `${target}.bak`;
     let backupPath = '';
     try {
       const st = await c.invoke<{ size?: number; exists?: boolean }>(CapabilityNames.FsStat, { path: target });
@@ -329,6 +332,23 @@ export async function cmdDeploy(localFile: string, opts: Options): Promise<void>
       offset += part.length;
     }
     console.log(`✓ 已上传 ${(buf.length / 1024).toFixed(0)} KB`);
+
+    // best-effort 清理历史的时间戳备份（老格式 `.bak-<ts>`）。
+    // 平台分流：Windows 用 PS，类 Unix 用 rm。清不掉不影响部署，只提示。
+    try {
+      const isWin = String((info as { os?: string }).os ?? '').toLowerCase().startsWith('win');
+      const cleanup = isWin
+        ? `Get-ChildItem '${target}.bak-*' -EA SilentlyContinue | Remove-Item -Force -EA SilentlyContinue; (Get-ChildItem '${target}.bak-*' -EA SilentlyContinue | Measure-Object).Count`
+        : `rm -f '${target}.bak-'* 2>/dev/null; ls '${target}.bak-'* 2>/dev/null | wc -l`;
+      const r = await c.invoke<{ stdout?: string }>(CapabilityNames.ShellExec, { command: cleanup, timeout_ms: 15_000 });
+      const left = Number((r.data?.stdout ?? '').trim());
+      if (r.status === 'ok' && Number.isFinite(left)) {
+        if (left === 0) console.log('✓ 已清理历史时间戳备份（老格式）');
+        else console.log(`⚠️ 仍有 ${left} 个历史备份未清理（可手动删除）`);
+      }
+    } catch {
+      /* 清理是附加项，失败不影响部署结果 */
+    }
     return { backupPath };
   });
 
@@ -620,3 +640,115 @@ export async function cmdClip(opts: Options): Promise<void> {
     }),
   );
 }
+
+// ---------- v1.8 状态采样（monitor / log） ----------
+
+/**
+ * 状态采样与回看。
+ *
+ *   nodeagent monitor start --source port --target 127.0.0.1:8765 --interval 2000
+ *   nodeagent monitor report <id>
+ *   nodeagent monitor stop <id>
+ *   nodeagent monitor list
+ *   nodeagent monitor delete <id>
+ */
+export async function cmdMonitor(action: string | undefined, positional: string[], opts: Options): Promise<void> {
+  switch (action) {
+    case 'start': {
+      const source = opts.source;
+      if (!source) fail('用法: nodeagent monitor start --source <port|process|command|metric> [--target X] [--interval ms] [--id name]');
+      const args: Record<string, unknown> = { source };
+      if (opts.target !== undefined) args['target'] = opts.target;
+      if (opts.interval !== undefined) args['interval_ms'] = Number(opts.interval);
+      if (positional[0]) args['id'] = positional[0];
+      await withClient((c) =>
+        callAndPrint(c, CapabilityNames.MonitorStart, args, opts.json, (d) => {
+          const r = d as { id: string; source: string; target: string; interval_ms: number; file: string };
+          console.log(`✓ 已启动监控 ${r.id}（${r.source}${r.target ? ' → ' + r.target : ''}，每 ${r.interval_ms}ms 一针）`);
+          console.log(`  样本文件：${r.file}`);
+          console.log(`  回看：nodeagent monitor report ${r.id}`);
+        }),
+      );
+      return;
+    }
+    case 'report': {
+      const id = positional[0];
+      if (!id) fail('用法: nodeagent monitor report <id> [--limit n]');
+      const args: Record<string, unknown> = { id };
+      if (opts.limit !== undefined) args['limit'] = Number(opts.limit);
+      await withClient((c) =>
+        callAndPrint(c, CapabilityNames.MonitorReport, args, opts.json, (d) => {
+          const r = d as {
+            running: boolean; source: string; target: string; samples: number;
+            summary: Record<string, number>;
+          };
+          console.log(`${r.running ? '● 运行中' : '○ 已停止'} ${r.source}${r.target ? ' → ' + r.target : ''}，共 ${r.samples} 个样本`);
+          // 摘要直接说人话（这是本能力的主要价值）
+          const sm = r.summary;
+          if (sm.down_count !== undefined) {
+            console.log(`  连通：${sm.up_count} 通 / ${sm.down_count} 断；最长连续中断 ${sm.longest_outage_samples} 针` +
+              (sm.ms_avg !== undefined ? `；延迟 min/avg/max = ${sm.ms_min}/${sm.ms_avg}/${sm.ms_max}ms` : ''));
+          }
+          if (sm.dead_count !== undefined) console.log(`  存活：${sm.alive_count} 在 / ${sm.dead_count} 不在；最长连续缺失 ${sm.longest_dead_samples} 针`);
+          if (sm.fail_count !== undefined) console.log(`  命令：${sm.ok_count} 成功 / ${sm.fail_count} 失败；退出码 ${JSON.stringify(sm.exit_codes_seen)}`);
+          if (sm.cpu_avg !== undefined) console.log(`  CPU min/avg/max = ${sm.cpu_min}/${sm.cpu_avg}/${sm.cpu_max}%；内存 avg ${sm.mem_avg}%`);
+          if (sm.window_ms !== undefined) console.log(`  时间窗：${(sm.window_ms / 1000).toFixed(1)}s`);
+        }),
+      );
+      return;
+    }
+    case 'stop': {
+      const id = positional[0];
+      if (!id) fail('用法: nodeagent monitor stop <id>');
+      await withClient((c) =>
+        callAndPrint(c, CapabilityNames.MonitorStop, { id }, opts.json, (d) => {
+          const r = d as { id: string; samples: number; file: string };
+          console.log(`✓ 已停止 ${r.id}（共 ${r.samples} 个样本）；样本留在 ${r.file}`);
+        }),
+      );
+      return;
+    }
+    case 'list': {
+      await withClient((c) =>
+        callAndPrint(c, CapabilityNames.MonitorList, {}, opts.json, (d) => {
+          const r = d as { running: Array<{ id: string; source: string; target: string; samples: number }>; running_count: number; history_files: string[] };
+          console.log(`运行中 ${r.running_count} 个：`);
+          for (const m of r.running) console.log(`  ● ${m.id}（${m.source}${m.target ? ' → ' + m.target : ''}，${m.samples} 样本）`);
+          if (r.history_files.length) console.log(`历史文件：${r.history_files.join(', ')}`);
+        }),
+      );
+      return;
+    }
+    case 'delete': {
+      const id = positional[0];
+      if (!id) fail('用法: nodeagent monitor delete <id>（运行中需先 stop）');
+      await withClient((c) =>
+        callAndPrint(c, CapabilityNames.MonitorDelete, { id }, opts.json, () => console.log(`✓ 已删除 ${id} 的历史样本`)),
+      );
+      return;
+    }
+    default:
+      fail('用法: nodeagent monitor <start|report|stop|list|delete> ...');
+  }
+}
+
+/** 在被控端侧过滤日志（v1.8）：日志常几万行，过滤必须发生在被控端。 */
+export async function cmdLog(opts: Options): Promise<void> {
+  const logPath = opts.path;
+  if (!logPath) fail('用法: nodeagent log --path <文件> [--pattern 正则] [--level ERROR] [--limit n] [--tail]');
+  const args: Record<string, unknown> = { path: logPath };
+  if (opts.pattern !== undefined) args['pattern'] = opts.pattern;
+  if (opts.level !== undefined) args['level'] = opts.level;
+  if (opts.since !== undefined) args['since'] = Number(opts.since);
+  if (opts.limit !== undefined) args['limit'] = Number(opts.limit);
+  if (opts.offset !== undefined) args['offset'] = Number(opts.offset);
+  if (opts.tail === true) args['tail'] = true;
+  await withClient((c) =>
+    callAndPrint(c, CapabilityNames.LogQuery, args, opts.json, (d) => {
+      const r = d as { matched: Array<{ n: number; text: string }>; scanned: number; truncated: boolean; note?: string };
+      console.log(`✓ 扫描 ${r.scanned} 行，命中 ${r.matched.length} 条${r.truncated ? '（结果被截断）' : ''}`);
+      for (const m of r.matched) console.log(`  ${String(m.n).padStart(6)}  ${m.text.slice(0, 160)}`);
+      if (r.note) console.log(`  ℹ️ ${r.note}`);
+    }),
+  );
+}

apps/cli/src/cmd/system.ts

@@ -183,6 +183,54 @@ export async function cmdRestart(opts: Options): Promise<void> {
   );
 }
 
+// ---------- v25 审计链外部锚定 ----------
+
+/**
+ * 打印审计链头（可选与最近锚点比对）。
+ *
+ *   nodeagent audit head [--compare]
+ */
+export async function cmdAuditHead(opts: Options): Promise<void> {
+  const args: Record<string, unknown> = {};
+  if (opts.compare === true) args['compare'] = true;
+  if (opts.anchorPath !== undefined) args['anchor_path'] = opts.anchorPath;
+  await withClient((c) =>
+    callAndPrint(c, CapabilityNames.AuditHead, args, opts.json, (data) => {
+      const d = data as {
+        entries: number; head_hash: string | null; head_ts: number | null;
+        rotated_segments: number; file_bytes: number;
+        comparison?: { ok: boolean; anchors_checked: number; verdict: string };
+      };
+      console.log(`审计链头：${d.entries} 条，轮转 ${d.rotated_segments} 段，${(d.file_bytes / 1024).toFixed(0)} KB`);
+      console.log(`  head_hash : ${d.head_hash ?? '(空链)'}`);
+      console.log(`  head_ts   : ${d.head_ts ? new Date(d.head_ts).toLocaleString() : '-'}`);
+      console.log('  💡 把 head_hash 连同 entries 存到链外（另一台机器/网盘）—— 这是外部锚定');
+      if (d.comparison) {
+        const k = d.comparison.ok ? '✓' : '✗';
+        console.log(`  ${k} 锚点比对（${d.comparison.anchors_checked} 条锚点）：${d.comparison.verdict}`);
+      }
+    }),
+  );
+}
+
+/**
+ * 追加一个锚点到锚点文件。
+ *
+ *   nodeagent audit anchor [--anchor-path <文件>] [--note "每日例行"]
+ */
+export async function cmdAuditAnchor(opts: Options): Promise<void> {
+  const args: Record<string, unknown> = {};
+  if (opts.anchorPath !== undefined) args['path'] = opts.anchorPath;
+  if (opts.note !== undefined) args['note'] = opts.note;
+  await withClient((c) =>
+    callAndPrint(c, CapabilityNames.AuditAnchor, args, opts.json, (data) => {
+      const d = data as { file: string; total_lines: number; record: { entries: number; head_hash: string | null } };
+      console.log(`✓ 已锚定：${d.record.entries} 条，链头 ${String(d.record.head_hash).slice(0, 16)}…`);
+      console.log(`  锚点文件：${d.file}（累计 ${d.total_lines} 条锚点）`);
+    }),
+  );
+}
+
 export async function cmdAuditVerify(opts: Options): Promise<void> {
   await withClient((c) =>
     callAndPrint(c, CapabilityNames.AuditVerify, {}, opts.json, (data) => {

apps/cli/src/help.ts

@@ -48,6 +48,13 @@ export const HELP = `nodeagent —— 跨机 AI 接管框架（控制端 CLI）
   nodeagent macro validate <file.json> | macro init [文件]
   nodeagent events [--kind file|process|net] [--path <路径>] [--pattern G] [--seconds 15]
                                       订阅事件并实时接收推送（无 --kind 则列出订阅）(v12)
+  nodeagent monitor start --source <port|process|command|metric> [--target X] [--interval ms] [--id 名]
+                                      启动定时采样并落盘 (v1.8)：port 验连通性/process 验存活/
+                                      command 取退出码/metric 取 CPU·内存
+  nodeagent monitor report <id>       回看样本 + 摘要（断几次、最长断多久、值域）(v1.8)
+  nodeagent monitor stop|list|delete <id>
+  nodeagent log --path <文件> [--pattern 正则] [--level ERROR] [--limit n] [--tail]
+                                      在被控端侧过滤日志，只回匹配行（日志几万行也不拖网）(v1.8)
   nodeagent record [--duration 5000] [--fps 2] [--scale 0.5] [--region x,y,w,h]
                                       录屏为帧序列（有 ffmpeg 则封装 mp4）(v11)
   nodeagent update --url <地址> --sha256 <哈希> [--dry-run]
@@ -72,6 +79,9 @@ export const HELP = `nodeagent —— 跨机 AI 接管框架（控制端 CLI）
   nodeagent mouse scroll <delta>
   nodeagent key type "<文本>" [--interval 10]
   nodeagent key press <键1> [键2] ...  （组合键，如 ctrl c）
+  nodeagent key press media_play_pause --pid 1234   （媒体键，v1.2：走 WM_APPCOMMAND，
+                                    --pid 定向到该进程的全部顶层窗口；省略则广播。
+                                    窗口被遮挡/最小化/游戏全屏时依然有效）
 
 通用选项:
   --node <设备名>  本次命令临时指定目标设备（不改变 current）

apps/cli/src/index.ts

@@ -34,13 +34,13 @@ import { HELP } from './help.js';
 import { parseOptions } from './options.js';
 import { cmdConnect, cmdDiscover, cmdKeygen, cmdNodes, cmdRemove, cmdUse } from './cmd/conn.js';
 import {
-  cmdApps, cmdAudio, cmdAudit, cmdAuditVerify, cmdExec, cmdInfo, cmdInstall, cmdInvoke, cmdList,
+  cmdApps, cmdAudio, cmdAudit, cmdAuditAnchor, cmdAuditHead, cmdAuditVerify, cmdExec, cmdInfo, cmdInstall, cmdInvoke, cmdList,
   cmdMetrics, cmdPs, cmdRestart, cmdServices, cmdStatus, cmdUpdate,
 } from './cmd/system.js';
 import {
-  cmdBg, cmdClip, cmdDeploy, cmdEvents, cmdFanout, cmdMacro, cmdRecord, cmdTask, cmdTasks,
+  cmdBg, cmdClip, cmdDeploy, cmdEvents, cmdFanout, cmdLog, cmdMacro, cmdMonitor, cmdRecord, cmdTask, cmdTasks,
 } from './cmd/ops.js';
-import { cmdKey, cmdMouse, cmdScreen, cmdScreenshot } from './cmd/gui.js';
+import { cmdAwait, cmdKey, cmdMouse, cmdScreen, cmdScreenshot } from './cmd/gui.js';
 import { cmdCat, cmdLs, cmdPull, cmdPush, cmdStat } from './cmd/fs.js';
 import { cmdNet } from './cmd/net.js';
 import { DAEMON_SOCK, fail, getClientConfig, setNodeOverride } from './core.js';
@@ -187,6 +187,14 @@ async function main(): Promise<void> {
     case 'events':
       await cmdEvents(opts);
       return;
+    case 'monitor': {
+      const [action, ...rest2] = positionals;
+      await cmdMonitor(action, rest2, opts);
+      return;
+    }
+    case 'log':
+      await cmdLog(opts);
+      return;
     case 'macro': {
       const sub = positionals[0];
       await cmdMacro(sub, positionals[1], opts);
@@ -268,6 +276,8 @@ async function main(): Promise<void> {
       return;
     case 'audit':
       if (positionals[0] === 'verify') await cmdAuditVerify(opts);
+      else if (positionals[0] === 'head') await cmdAuditHead(opts);
+      else if (positionals[0] === 'anchor') await cmdAuditAnchor(opts);
       else await cmdAudit(opts);
       return;
     case 'discover':
@@ -304,6 +314,10 @@ async function main(): Promise<void> {
       await cmdKey(action, rest2, opts);
       return;
     }
+    case 'await': {
+      await cmdAwait(opts);
+      return;
+    }
     case undefined:
     case 'help':
     case '--help':

apps/cli/src/options.ts

@@ -54,6 +54,24 @@ export function parseOptions(rest: string[]): { opts: Options; positionals: stri
       button: { type: 'string' },
       duration: { type: 'string' },
       interval: { type: 'string' },
+      tail: { type: 'boolean' },
+      compare: { type: 'boolean' },
+      'anchor-path': { type: 'string' },
+      note: { type: 'string' },
+      level: { type: 'string' },
+      target: { type: 'string' },
+      source: { type: 'string' },
+      where: { type: 'string' },
+      any_of: { type: 'string' },
+      title: { type: 'string' },
+      text: { type: 'string' },
+      process: { type: 'string' },
+      state: { type: 'string' },
+      condition: { type: 'string' },
+      // 媒体键定向投递的目标进程 PID（v1.2）
+      pid: { type: 'string' },
+      hold: { type: 'string' },
+      route: { type: 'string' },
       'auth-mode': { type: 'string' },
       since: { type: 'string' },
       type: { type: 'string' },
@@ -62,7 +80,6 @@ export function parseOptions(rest: string[]): { opts: Options; positionals: stri
       'discovery-port': { type: 'string' },
       node: { type: 'string' },
       name: { type: 'string' },
-      note: { type: 'string' },
       recursive: { type: 'boolean', default: false },
       pattern: { type: 'string' },
       'create-dirs': { type: 'boolean', default: false },
@@ -123,6 +140,23 @@ export function parseOptions(rest: string[]): { opts: Options; positionals: stri
       button: values['button'] as string | undefined,
       duration: values['duration'] as string | undefined,
       interval: values['interval'] as string | undefined,
+      tail: values['tail'] as boolean | undefined,
+      compare: values['compare'] as boolean | undefined,
+      anchorPath: values['anchor-path'] as string | undefined,
+      note: values['note'] as string | undefined,
+      level: values['level'] as string | undefined,
+      target: values['target'] as string | undefined,
+      source: values['source'] as string | undefined,
+      where: values['where'] as string | undefined,
+      any_of: values['any_of'] as string | undefined,
+      condition: values['condition'] as string | undefined,
+      state: values['state'] as string | undefined,
+      process: values['process'] as string | undefined,
+      text: values['text'] as string | undefined,
+      title: values['title'] as string | undefined,
+      pid: values['pid'] as string | undefined,
+      hold: values['hold'] as string | undefined,
+      route: values['route'] as string | undefined,
       authMode: values['auth-mode'] as string | undefined,
       since: values['since'] as string | undefined,
       type: values['type'] as string | undefined,
@@ -164,7 +198,6 @@ export function parseOptions(rest: string[]): { opts: Options; positionals: stri
       seconds: values['seconds'] as string | undefined,
       intervalMs: values['interval-ms'] as string | undefined,
       name: values['name'] as string | undefined,
-      note: values['note'] as string | undefined,
       recursive: Boolean(values['recursive']),
       pattern: values['pattern'] as string | undefined,
       createDirs: Boolean(values['create-dirs']),

apps/cli/src/types.ts

@@ -16,10 +16,38 @@ export interface Options {
   button?: string;
   duration?: string;
   interval?: string;
+  /** 媒体键定向投递的目标进程 PID（v1.2 keyPress） */
+  /** 通用选项：文本 / 标题 */
+  text?: string;
+  title?: string;
+  /** v25 审计锚定 */
+  compare?: boolean;
+  anchorPath?: string;
+  note?: string;
+  /** v1.8 状态采样 */
+  source?: string;
+  target?: string;
+  pattern?: string;
+  level?: string;
+  since?: string;
+  offset?: string;
+  tail?: boolean;
+  /** v1.7 gui.await 扩展 */
+  where?: string;
+  any_of?: string;
+  /** v1.6 gui.await */
+  condition?: string;
+  state?: string;
+  path?: string;
+  process?: string;
+  /** v1.5 快捷键扩展：长按毫秒 */
+  hold?: string;
+  /** v1.5 快捷键扩展：投递路由 foreground|post */
+  route?: string;
+  pid?: string;
   /** v3：认证模式 psk | ed25519 */
   authMode?: string;
   /** v3+ 审计查询 */
-  since?: string;
   type?: string;
   clientId?: string;
   /** v4 发现 */
@@ -28,10 +56,8 @@ export interface Options {
   /** v5 多设备 */
   node?: string;
   name?: string;
-  note?: string;
   /** v5 文件 */
   recursive?: boolean;
-  pattern?: string;
   createDirs?: boolean;
   /** v6 Hub */
   hubToken?: string;
@@ -41,7 +67,6 @@ export interface Options {
   /** v10 后台任务 / 剪贴板 */
   timeoutMs?: string;
   kill?: boolean;
-  offset?: string;
   set?: string;
   /** v11 剪贴板图片 */
   imageFile?: string;
@@ -50,7 +75,6 @@ export interface Options {
   /** v11 多设备并发 */
   nodes?: string;
   /** v11 部署目标路径 */
-  path?: string;
   /** v12 事件订阅 */
   kind?: string;
   /** v12 宏变量 */

apps/console/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

apps/console/README.md

@@ -0,0 +1,7 @@
+# Tauri + Vue + TypeScript
+
+This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
+
+## Recommended IDE Setup
+
+- [VS Code](https://code.visualstudio.com/) + [Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar) + [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) + [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)

apps/console/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Tauri + Vue + Typescript App</title>
+  </head>
+
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

apps/console/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "nodeagent-console",
+  "private": true,
+  "version": "2.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vue-tsc --noEmit && vite build",
+    "preview": "vite preview",
+    "tauri": "tauri"
+  },
+  "dependencies": {
+    "@tauri-apps/api": "^2",
+    "@tauri-apps/plugin-opener": "^2",
+    "echarts": "^6.1.0",
+    "naive-ui": "^2.45.3",
+    "pinia": "^4.0.3",
+    "vue": "^3.5.13",
+    "vue-router": "^5.3.1"
+  },
+  "devDependencies": {
+    "@tauri-apps/cli": "^2",
+    "@vitejs/plugin-vue": "^6.0.7",
+    "typescript": "~6.0.3",
+    "vite": "^8.0.16",
+    "vue-tsc": "^3.3.5"
+  }
+}

apps/console/public/tauri.svg

@@ -0,0 +1,6 @@
+<svg width="206" height="231" viewBox="0 0 206 231" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M143.143 84C143.143 96.1503 133.293 106 121.143 106C108.992 106 99.1426 96.1503 99.1426 84C99.1426 71.8497 108.992 62 121.143 62C133.293 62 143.143 71.8497 143.143 84Z" fill="#FFC131"/>
+<ellipse cx="84.1426" cy="147" rx="22" ry="22" transform="rotate(180 84.1426 147)" fill="#24C8DB"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M166.738 154.548C157.86 160.286 148.023 164.269 137.757 166.341C139.858 160.282 141 153.774 141 147C141 144.543 140.85 142.121 140.558 139.743C144.975 138.204 149.215 136.139 153.183 133.575C162.73 127.404 170.292 118.608 174.961 108.244C179.63 97.8797 181.207 86.3876 179.502 75.1487C177.798 63.9098 172.884 53.4021 165.352 44.8883C157.82 36.3744 147.99 30.2165 137.042 27.1546C126.095 24.0926 114.496 24.2568 103.64 27.6274C92.7839 30.998 83.1319 37.4317 75.8437 46.1553C74.9102 47.2727 74.0206 48.4216 73.176 49.5993C61.9292 50.8488 51.0363 54.0318 40.9629 58.9556C44.2417 48.4586 49.5653 38.6591 56.679 30.1442C67.0505 17.7298 80.7861 8.57426 96.2354 3.77762C111.685 -1.01901 128.19 -1.25267 143.769 3.10474C159.348 7.46215 173.337 16.2252 184.056 28.3411C194.775 40.457 201.767 55.4101 204.193 71.404C206.619 87.3978 204.374 103.752 197.73 118.501C191.086 133.25 180.324 145.767 166.738 154.548ZM41.9631 74.275L62.5557 76.8042C63.0459 72.813 63.9401 68.9018 65.2138 65.1274C57.0465 67.0016 49.2088 70.087 41.9631 74.275Z" fill="#FFC131"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M38.4045 76.4519C47.3493 70.6709 57.2677 66.6712 67.6171 64.6132C65.2774 70.9669 64 77.8343 64 85.0001C64 87.1434 64.1143 89.26 64.3371 91.3442C60.0093 92.8732 55.8533 94.9092 51.9599 97.4256C42.4128 103.596 34.8505 112.392 30.1816 122.756C25.5126 133.12 23.9357 144.612 25.6403 155.851C27.3449 167.09 32.2584 177.598 39.7906 186.112C47.3227 194.626 57.153 200.784 68.1003 203.846C79.0476 206.907 90.6462 206.743 101.502 203.373C112.359 200.002 122.011 193.568 129.299 184.845C130.237 183.722 131.131 182.567 131.979 181.383C143.235 180.114 154.132 176.91 164.205 171.962C160.929 182.49 155.596 192.319 148.464 200.856C138.092 213.27 124.357 222.426 108.907 227.222C93.458 232.019 76.9524 232.253 61.3736 227.895C45.7948 223.538 31.8055 214.775 21.0867 202.659C10.3679 190.543 3.37557 175.59 0.949823 159.596C-1.47592 143.602 0.768139 127.248 7.41237 112.499C14.0566 97.7497 24.8183 85.2327 38.4045 76.4519ZM163.062 156.711L163.062 156.711C162.954 156.773 162.846 156.835 162.738 156.897C162.846 156.835 162.954 156.773 163.062 156.711Z" fill="#24C8DB"/>
+</svg>

apps/console/public/vite.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>

apps/console/src-tauri/.gitignore

@@ -0,0 +1,7 @@
+# Generated by Cargo
+# will have compiled files and executables
+/target/
+
+# Generated by Tauri
+# will have schema files for capabilities auto-completion
+/gen/schemas

apps/console/src-tauri/Cargo.toml

@@ -0,0 +1,34 @@
+[package]
+name = "nodeagent-console"
+version = "0.1.0"
+description = "nodeagent 桌面控制台（主控 + 被控一体）"
+authors = ["jkooe"]
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[lib]
+# The `_lib` suffix may seem redundant but it is necessary
+# to make the lib name unique and wouldn't conflict with the bin name.
+# This seems to be only an issue on Windows, see https://github.com/rust-lang/cargo/issues/8519
+name = "nodeagent_console_lib"
+crate-type = ["staticlib", "cdylib", "rlib"]
+
+[build-dependencies]
+tauri-build = { version = "2", features = [] }
+
+[dependencies]
+tauri = { version = "2", features = [] }
+tauri-plugin-opener = "2"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+nodeagent-client = { path = "../../../crates/nodeagent-client" }
+
+
+# Read the optimization guideline for more details: https://tauri.app/concept/size/#cargo-configuration
+[profile.release]
+codegen-units = 1
+lto = true
+opt-level = 3
+panic = "abort"
+strip = true

apps/console/src-tauri/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    tauri_build::build()
+}

apps/console/src-tauri/capabilities/default.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "../gen/schemas/desktop-schema.json",
+  "identifier": "default",
+  "description": "Capability for the main window",
+  "windows": ["main"],
+  "permissions": [
+    "core:default",
+    "opener:default"
+  ]
+}

apps/console/src-tauri/src/lib.rs

@@ -0,0 +1,151 @@
+//! nodeagent 桌面控制台（主控 + 被控一体）——Tauri 后端。
+//!
+//! command 层把 `nodeagent-client`（Rust 控制端）接到前端：
+//! - `connect` / `disconnect` / `invoke_capability` / `get_capabilities` / `get_state`
+//! - client 的日志/状态/被控端事件经 Tauri `emit` 推给前端（`na-log`/`na-state`/`na-event`）。
+
+use std::sync::{Arc, Mutex};
+
+use nodeagent_client::{
+    CapabilityDescriptor, Client, ClientEvent, ClientOptions, ConnState, InvokeResult,
+};
+use serde::Serialize;
+use serde_json::Value;
+use tauri::{AppHandle, Emitter, State};
+
+/// 全局状态：持有当前连接（`None` = 未连接）。
+struct AppState {
+    client: Mutex<Option<Client>>,
+}
+
+/// 连接成功后回传给前端的元信息。
+#[derive(Serialize)]
+struct ConnectInfo {
+    capabilities: Vec<CapabilityDescriptor>,
+    agent_version: Option<String>,
+    authorized: Option<Vec<String>>,
+    peer_cert_fp: Option<String>,
+    auth_mode: String,
+    client_id: String,
+}
+
+fn conn_state_str(s: ConnState) -> &'static str {
+    match s {
+        ConnState::Connected => "connected",
+        ConnState::Reconnecting => "reconnecting",
+        ConnState::Closed => "closed",
+    }
+}
+
+/// 建立到被控端的连接并完成握手（默认 psk 模式、接受自签证书、开启自动重连）。
+#[tauri::command]
+async fn connect(
+    app: AppHandle,
+    state: State<'_, AppState>,
+    url: String,
+    key: String,
+    client_id: Option<String>,
+    insecure: Option<bool>,
+) -> Result<ConnectInfo, String> {
+    let client_id = client_id.unwrap_or_else(|| "console".to_string());
+    let client = Client::new(ClientOptions {
+        url,
+        key,
+        client_id: client_id.clone(),
+        insecure: insecure.unwrap_or(true),
+        auto_reconnect: true,
+        ..Default::default()
+    });
+
+    // 把 client 的事件桥接成 Tauri 事件，推给前端。
+    let app_events = app.clone();
+    client.set_handler(Arc::new(move |evt| match evt {
+        ClientEvent::State(s) => {
+            let _ = app_events.emit("na-state", conn_state_str(s));
+        }
+        ClientEvent::Log(msg) => {
+            let _ = app_events.emit("na-log", msg);
+        }
+        ClientEvent::Event(params) => {
+            let _ = app_events.emit("na-event", params);
+        }
+    }));
+
+    let caps = client.connect().await.map_err(|e| e.to_string())?;
+
+    let info = ConnectInfo {
+        agent_version: client.agent_version(),
+        authorized: client.list_authorized(),
+        peer_cert_fp: client.peer_cert_fingerprint(),
+        auth_mode: "psk".to_string(),
+        capabilities: caps,
+        client_id,
+    };
+
+    *state.client.lock().unwrap() = Some(client);
+    Ok(info)
+}
+
+/// 断开连接（停止自动重连）。
+#[tauri::command]
+fn disconnect(state: State<'_, AppState>) -> Result<(), String> {
+    if let Some(client) = state.client.lock().unwrap().take() {
+        client.close();
+    }
+    Ok(())
+}
+
+/// 调用一项被控端能力。`timeout_ms` 可选：长任务（装软件 / 长命令）需显式放大。
+#[tauri::command]
+async fn invoke_capability(
+    state: State<'_, AppState>,
+    capability: String,
+    args: Option<Value>,
+    timeout_ms: Option<u64>,
+) -> Result<InvokeResult, String> {
+    let client = {
+        let guard = state.client.lock().unwrap();
+        guard.as_ref().cloned().ok_or_else(|| "未连接".to_string())?
+    };
+    let args = args.unwrap_or(Value::Object(Default::default()));
+    match timeout_ms {
+        Some(ms) if ms > 0 => client.invoke_with_timeout(&capability, args, ms).await,
+        _ => client.invoke(&capability, args).await,
+    }
+    .map_err(|e| e.to_string())
+}
+
+/// 当前连接的能力清单。
+#[tauri::command]
+fn get_capabilities(state: State<'_, AppState>) -> Result<Vec<CapabilityDescriptor>, String> {
+    let guard = state.client.lock().unwrap();
+    let client = guard.as_ref().ok_or_else(|| "未连接".to_string())?;
+    Ok(client.list_capabilities())
+}
+
+/// 当前连接状态字符串（connected / reconnecting / closed / 未连接）。
+#[tauri::command]
+fn get_state(state: State<'_, AppState>) -> String {
+    match state.client.lock().unwrap().as_ref() {
+        Some(client) => conn_state_str(client.state()).to_string(),
+        None => "未连接".to_string(),
+    }
+}
+
+#[cfg_attr(mobile, tauri::mobile_entry_point)]
+pub fn run() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_opener::init())
+        .manage(AppState {
+            client: Mutex::new(None),
+        })
+        .invoke_handler(tauri::generate_handler![
+            connect,
+            disconnect,
+            invoke_capability,
+            get_capabilities,
+            get_state
+        ])
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}

apps/console/src-tauri/src/main.rs

@@ -0,0 +1,6 @@
+// Prevents additional console window on Windows in release, DO NOT REMOVE!!
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+fn main() {
+    nodeagent_console_lib::run()
+}

apps/console/src-tauri/tauri.conf.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://schema.tauri.app/config/2",
+  "productName": "nodeagent-console",
+  "version": "2.0.0",
+  "identifier": "cn.jkooe.nodeagent-console",
+  "build": {
+    "beforeDevCommand": "pnpm dev",
+    "devUrl": "http://localhost:1420",
+    "beforeBuildCommand": "pnpm build",
+    "frontendDist": "../dist"
+  },
+  "app": {
+    "windows": [
+      {
+        "title": "nodeagent 控制台",
+        "width": 1100,
+        "height": 720
+      }
+    ],
+    "security": {
+      "csp": null
+    }
+  },
+  "bundle": {
+    "active": true,
+    "targets": "all",
+    "icon": [
+      "icons/32x32.png",
+      "icons/128x128.png",
+      "icons/128x128@2x.png",
+      "icons/icon.icns",
+      "icons/icon.ico"
+    ]
+  }
+}

apps/console/src/App.vue

@@ -0,0 +1,21 @@
+<script setup lang="ts">
+import {
+  NConfigProvider,
+  NMessageProvider,
+  NDialogProvider,
+  darkTheme,
+  zhCN,
+  dateZhCN,
+} from "naive-ui";
+import AppShell from "./components/AppShell.vue";
+</script>
+
+<template>
+  <n-config-provider :theme="darkTheme" :locale="zhCN" :date-locale="dateZhCN">
+    <n-message-provider>
+      <n-dialog-provider>
+        <app-shell />
+      </n-dialog-provider>
+    </n-message-provider>
+  </n-config-provider>
+</template>

apps/console/src/api/index.ts

@@ -0,0 +1,88 @@
+/** Tauri command 调用封装（前端 → Rust 壳 → nodeagent-client）。 */
+import { invoke } from "@tauri-apps/api/core";
+import type { CapabilityDescriptor, ConnectInfo, InvokeResult } from "../types";
+
+/** 建立连接并握手。 */
+export function connect(url: string, key: string, clientId = "console", insecure = true) {
+  return invoke<ConnectInfo>("connect", { url, key, clientId, insecure });
+}
+
+/** 断开连接（停自动重连）。 */
+export function disconnect() {
+  return invoke<void>("disconnect");
+}
+
+/** 泛型能力调用（`timeoutMs` 用于长任务，如装软件 / 长命令）。 */
+export function call<T = unknown>(
+  capability: string,
+  args: Record<string, unknown> = {},
+  timeoutMs?: number,
+) {
+  return invoke<InvokeResult<T>>("invoke_capability", { capability, args, timeoutMs });
+}
+
+/** 当前连接的能力清单。 */
+export function getCapabilities() {
+  return invoke<CapabilityDescriptor[]>("get_capabilities");
+}
+
+/** 当前连接状态字符串。 */
+export function getState() {
+  return invoke<string>("get_state");
+}
+
+/**
+ * 能力调用失败（业务层失败，非传输层失败）。
+ *
+ * 协议真源 `InvokeResult.error` 只有 `{ name, message, data? }` —— **不含 code**，
+ * 所以分支判断一律走 `name`（如 `E_UNSUPPORTED_PLATFORM`）。
+ */
+export class CapabilityFailure extends Error {
+  readonly capability: string;
+  readonly errorName: string;
+  readonly data?: unknown;
+
+  constructor(capability: string, errorName: string, message: string, data?: unknown) {
+    super(message);
+    this.name = "CapabilityFailure";
+    this.capability = capability;
+    this.errorName = errorName;
+    this.data = data;
+  }
+}
+
+/** 被控端平台不支持该能力（如 macOS 被控端上的 app.* / system.service.list）。 */
+export function isUnsupportedPlatform(e: unknown): boolean {
+  return e instanceof CapabilityFailure && e.errorName === "E_UNSUPPORTED_PLATFORM";
+}
+
+/** 能力被 ACL 拒绝。 */
+export function isAclDenied(e: unknown): boolean {
+  return e instanceof CapabilityFailure && e.errorName === "E_ACL_DENIED";
+}
+
+/** 能力被调用限速拦截。 */
+export function isRateLimited(e: unknown): boolean {
+  return e instanceof CapabilityFailure && e.errorName === "E_RATE_LIMITED";
+}
+
+/**
+ * 调用并要求成功：失败时抛出 `CapabilityFailure`（携带被控端 error.name）。
+ * 便于页面里 `await ok("fs.list", { path })` 直接拿数据。
+ */
+export async function ok<T = unknown>(
+  capability: string,
+  args: Record<string, unknown> = {},
+  timeoutMs?: number,
+): Promise<T> {
+  const res = await call<T>(capability, args, timeoutMs);
+  if (res.status !== "ok") {
+    throw new CapabilityFailure(
+      capability,
+      res.error?.name ?? "E_UNKNOWN",
+      res.error?.message ?? `${capability} 执行失败`,
+      res.error?.data,
+    );
+  }
+  return res.data as T;
+}

apps/console/src/assets/vue.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="37.07" height="36" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 198"><path fill="#41B883" d="M204.8 0H256L128 220.8L0 0h97.92L128 51.2L157.44 0h47.36Z"></path><path fill="#41B883" d="m0 0l128 220.8L256 0h-51.2L128 132.48L50.56 0H0Z"></path><path fill="#35495E" d="M50.56 0L128 133.12L204.8 0h-47.36L128 51.2L97.92 0H50.56Z"></path></svg>

apps/console/src/components/AppShell.vue

@@ -0,0 +1,108 @@
+<script setup lang="ts">
+import { computed, h, onMounted } from "vue";
+import { RouterView, useRoute, useRouter } from "vue-router";
+import {
+  NLayout,
+  NLayoutSider,
+  NLayoutHeader,
+  NLayoutContent,
+  NMenu,
+  NTag,
+  NButton,
+  NSpace,
+  NText,
+  type MenuOption,
+} from "naive-ui";
+import { navRoutes } from "../router";
+import { useConnStore } from "../stores/conn";
+
+const route = useRoute();
+const router = useRouter();
+const conn = useConnStore();
+
+onMounted(() => {
+  conn.bind();
+});
+
+const menuOptions: MenuOption[] = navRoutes.map((r) => ({
+  key: r.name as string,
+  label: () => h("span", `${(r.meta as { icon: string }).icon}  ${(r.meta as { title: string }).title}`),
+}));
+
+const activeKey = computed(() => (route.name as string) ?? "nodes");
+
+function onMenu(key: string) {
+  router.push({ name: key });
+}
+
+const stateType = computed(() => {
+  if (conn.state === "connected") return "success" as const;
+  if (conn.state === "reconnecting") return "warning" as const;
+  return "error" as const;
+});
+
+const stateLabel = computed(() => {
+  if (conn.state === "connected") return "已连接";
+  if (conn.state === "reconnecting") return "重连中";
+  return "未连接";
+});
+</script>
+
+<template>
+  <n-layout has-sider style="height: 100vh">
+    <n-layout-sider bordered :width="200" :native-scrollbar="false">
+      <div class="brand">
+        <div class="brand-title">nodeagent</div>
+        <div class="brand-sub">桌面控制台</div>
+      </div>
+      <n-menu :options="menuOptions" :value="activeKey" @update:value="onMenu" />
+    </n-layout-sider>
+
+    <n-layout>
+      <n-layout-header bordered class="topbar">
+        <n-space align="center">
+          <n-tag :type="stateType" size="small" round>{{ stateLabel }}</n-tag>
+          <n-text depth="3" style="font-size: 12px">{{ conn.url }}</n-text>
+          <n-text v-if="conn.info" depth="3" style="font-size: 12px">
+            · agent {{ conn.info.agent_version ?? "?" }} · {{ conn.info.capabilities.length }} 项能力
+          </n-text>
+        </n-space>
+        <n-button size="small" :disabled="!conn.info" @click="conn.disconnect()">断开</n-button>
+      </n-layout-header>
+
+      <n-layout-content :native-scrollbar="false" content-style="padding: 20px;">
+        <router-view />
+      </n-layout-content>
+    </n-layout>
+  </n-layout>
+</template>
+
+<style>
+:root {
+  color-scheme: dark;
+}
+body {
+  margin: 0;
+}
+.brand {
+  padding: 18px 20px 10px;
+}
+.brand-title {
+  font-size: 18px;
+  font-weight: 600;
+  color: #63e2b7;
+  letter-spacing: 0.5px;
+}
+.brand-sub {
+  font-size: 12px;
+  opacity: 0.6;
+  margin-top: 2px;
+}
+.topbar {
+  height: 48px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0 16px;
+}
+</style>

apps/console/src/main.ts

@@ -0,0 +1,9 @@
+import { createApp } from "vue";
+import { createPinia } from "pinia";
+import router from "./router";
+import App from "./App.vue";
+
+const app = createApp(App);
+app.use(createPinia());
+app.use(router);
+app.mount("#app");

apps/console/src/router/index.ts

@@ -0,0 +1,60 @@
+/** 路由表（7 页）。hash history 便于 Tauri 打包后稳定工作。 */
+import { createRouter, createWebHashHistory } from "vue-router";
+
+export interface NavMeta {
+  title: string;
+  icon: string;
+}
+
+const routes = [
+  { path: "/", redirect: "/nodes" },
+  {
+    path: "/nodes",
+    name: "nodes",
+    component: () => import("../views/NodesView.vue"),
+    meta: { title: "设备管理", icon: "🖥" } satisfies NavMeta,
+  },
+  {
+    path: "/overview",
+    name: "overview",
+    component: () => import("../views/OverviewView.vue"),
+    meta: { title: "状态总览", icon: "📊" } satisfies NavMeta,
+  },
+  {
+    path: "/terminal",
+    name: "terminal",
+    component: () => import("../views/TerminalView.vue"),
+    meta: { title: "命令执行", icon: "⌨" } satisfies NavMeta,
+  },
+  {
+    path: "/processes",
+    name: "processes",
+    component: () => import("../views/ProcessesView.vue"),
+    meta: { title: "进程与服务", icon: "⚙" } satisfies NavMeta,
+  },
+  {
+    path: "/software",
+    name: "software",
+    component: () => import("../views/SoftwareView.vue"),
+    meta: { title: "软件管理", icon: "📦" } satisfies NavMeta,
+  },
+  {
+    path: "/files",
+    name: "files",
+    component: () => import("../views/FilesView.vue"),
+    meta: { title: "文件管理", icon: "📁" } satisfies NavMeta,
+  },
+  {
+    path: "/audit",
+    name: "audit",
+    component: () => import("../views/AuditView.vue"),
+    meta: { title: "审计日志", icon: "📜" } satisfies NavMeta,
+  },
+];
+
+export const navRoutes = routes.filter((r) => "name" in r);
+
+export default createRouter({
+  history: createWebHashHistory(),
+  routes,
+});

apps/console/src/stores/conn.ts

@@ -0,0 +1,170 @@
+/** 连接状态 store：连接/断开、能力清单、元信息、日志与被控端事件。 */
+import { defineStore } from "pinia";
+import { computed, ref } from "vue";
+import { listen } from "@tauri-apps/api/event";
+import * as api from "../api";
+import type { ConnectInfo, InvokeResult, SystemInfo } from "../types";
+
+export interface AgentEvent {
+  ts: number;
+  payload: unknown;
+}
+
+/**
+ * 仅在被控端为 Windows 时可用（其余平台返回 E_UNSUPPORTED_PLATFORM）。
+ * 前端据此**事前门控**，而不是发出注定失败的请求再解释错误。
+ */
+export const WINDOWS_ONLY_CAPS = ["app.list", "app.install", "system.service.list"] as const;
+
+export const useConnStore = defineStore("conn", () => {
+  const state = ref<string>("closed");
+  const url = ref(localStorage.getItem("na.url") || "ws://127.0.0.1:8765");
+  const key = ref(localStorage.getItem("na.key") || "");
+  const info = ref<ConnectInfo | null>(null);
+  const logs = ref<string[]>([]);
+  const events = ref<AgentEvent[]>([]);
+  const connecting = ref(false);
+  const bound = ref(false);
+  /** 被控端平台：'Windows' | 'macOS' | 'Linux' | ... （连接后自动探测） */
+  const nodeOs = ref<string | null>(null);
+
+  const connected = computed(() => state.value === "connected" && !!info.value);
+  const capabilities = computed(() => info.value?.capabilities ?? []);
+  /** 被控端能力名集合，便于按名判存在性。 */
+  const capabilityNames = computed(() => new Set(capabilities.value.map((c) => c.name)));
+  const isWindows = computed(() => nodeOs.value === "Windows");
+  /** 平台门控能力当前是否可用（未探测到平台时按「乐观可用」处理）。 */
+  const platformReady = computed(() => nodeOs.value === null || isWindows.value);
+
+  function pushLog(msg: string) {
+    logs.value.push(`[${new Date().toLocaleTimeString()}] ${msg}`);
+    if (logs.value.length > 500) logs.value.shift();
+  }
+
+  /** 绑定后端事件（应用启动时调用一次）。 */
+  async function bind() {
+    if (bound.value) return;
+    bound.value = true;
+    await listen<string>("na-log", (e) => pushLog(e.payload));
+    await listen<string>("na-state", (e) => {
+      state.value = e.payload;
+      pushLog(`状态 → ${e.payload}`);
+    });
+    await listen<unknown>("na-event", (e) => {
+      events.value.unshift({ ts: Date.now(), payload: e.payload });
+      if (events.value.length > 200) events.value.pop();
+      pushLog(`被控端事件：${JSON.stringify(e.payload)}`);
+    });
+    state.value = await api.getState();
+  }
+
+  /** 探测被控端平台（`system.info.os`）——决定 Windows 专属能力是否可用。 */
+  async function loadPlatform() {
+    try {
+      const i = await api.ok<SystemInfo>("system.info", { fields: ["os"] });
+      nodeOs.value = i.os ?? null;
+      pushLog(`被控端平台：${nodeOs.value ?? "未知"}`);
+      return nodeOs.value;
+    } catch (e) {
+      pushLog(`平台探测失败：${e}`);
+      return null;
+    }
+  }
+
+  async function connect(u = url.value, k = key.value) {
+    connecting.value = true;
+    url.value = u;
+    key.value = k;
+    pushLog(`正在连接 ${u} ...`);
+    try {
+      const i = await api.connect(u, k, "console");
+      info.value = i;
+      localStorage.setItem("na.url", u);
+      localStorage.setItem("na.key", k);
+      pushLog(`握手成功：${i.capabilities.length} 项能力，agent ${i.agent_version ?? "?"}`);
+      // 握手后立刻探测平台，供各页面事前门控。
+      await loadPlatform();
+      return i;
+    } catch (e) {
+      pushLog(`连接失败：${e}`);
+      throw e;
+    } finally {
+      connecting.value = false;
+    }
+  }
+
+  async function disconnect() {
+    await api.disconnect();
+    info.value = null;
+    nodeOs.value = null;
+    pushLog("已断开");
+  }
+
+  /** 泛型调用；连接断开时抛错。 */
+  async function call<T = unknown>(
+    capability: string,
+    args: Record<string, unknown> = {},
+    timeoutMs?: number,
+  ): Promise<InvokeResult<T>> {
+    if (!connected.value) throw new api.CapabilityFailure(capability, "E_NODE_OFFLINE", "未连接");
+    const t0 = performance.now();
+    const res = await api.call<T>(capability, args, timeoutMs);
+    const ms = Math.round(performance.now() - t0);
+    if (res.status === "ok") {
+      pushLog(`${capability} → ok (${ms}ms)`);
+    } else {
+      pushLog(`${capability} → 失败：[${res.error?.name}] ${res.error?.message ?? "未知错误"}`);
+    }
+    return res;
+  }
+
+  /**
+   * 调用并要求成功，直接返回 data。
+   * 失败抛 `CapabilityFailure`（携带 `errorName`），便于页面按错误名分支
+   * ——如 `isUnsupportedPlatform(e)` 判平台不支持。
+   */
+  async function ok<T = unknown>(
+    capability: string,
+    args: Record<string, unknown> = {},
+    timeoutMs?: number,
+  ): Promise<T> {
+    const res = await call<T>(capability, args, timeoutMs);
+    if (res.status !== "ok") {
+      throw new api.CapabilityFailure(
+        capability,
+        res.error?.name ?? "E_UNKNOWN",
+        res.error?.message ?? `${capability} 执行失败`,
+        res.error?.data,
+      );
+    }
+    return res.data as T;
+  }
+
+  function clearLogs() {
+    logs.value = [];
+  }
+
+  return {
+    state,
+    url,
+    key,
+    info,
+    logs,
+    events,
+    connecting,
+    connected,
+    capabilities,
+    capabilityNames,
+    nodeOs,
+    isWindows,
+    platformReady,
+    bind,
+    loadPlatform,
+    connect,
+    disconnect,
+    call,
+    ok,
+    pushLog,
+    clearLogs,
+  };
+});

apps/console/src/stores/node.ts

@@ -0,0 +1,50 @@
+/** 设备列表 store：本地保存的被控端配置（名称 / 地址 / PSK），CRUD + 持久化。 */
+import { defineStore } from "pinia";
+import { computed, ref } from "vue";
+
+export interface NodeProfile {
+  id: string;
+  name: string;
+  url: string;
+  key: string;
+}
+
+export const useNodeStore = defineStore("node", () => {
+  const nodes = ref<NodeProfile[]>(JSON.parse(localStorage.getItem("na.nodes") || "[]"));
+  const currentId = ref<string | null>(localStorage.getItem("na.current"));
+
+  const current = computed(() => nodes.value.find((n) => n.id === currentId.value) ?? null);
+
+  function persist() {
+    localStorage.setItem("na.nodes", JSON.stringify(nodes.value));
+    localStorage.setItem("na.current", currentId.value ?? "");
+  }
+
+  function add(profile: Omit<NodeProfile, "id">): NodeProfile {
+    const node: NodeProfile = { id: crypto.randomUUID(), ...profile };
+    nodes.value.push(node);
+    persist();
+    return node;
+  }
+
+  function update(id: string, patch: Partial<NodeProfile>) {
+    const idx = nodes.value.findIndex((n) => n.id === id);
+    if (idx >= 0) {
+      nodes.value[idx] = { ...nodes.value[idx], ...patch };
+      persist();
+    }
+  }
+
+  function remove(id: string) {
+    nodes.value = nodes.value.filter((n) => n.id !== id);
+    if (currentId.value === id) currentId.value = null;
+    persist();
+  }
+
+  function setCurrent(id: string | null) {
+    currentId.value = id;
+    persist();
+  }
+
+  return { nodes, currentId, current, add, update, remove, setCurrent };
+});

apps/console/src/types/index.ts

@@ -0,0 +1,249 @@
+/** 协议类型镜像（对齐 Rust 侧 `crates/nodeagent-client` 与 Tauri command 的序列化形状）。 */
+
+/** 能力描述（被控端声明的能力清单条目）。 */
+export interface CapabilityDescriptor {
+  name: string;
+  version: string;
+  description: string;
+  risk: "low" | "medium" | "high" | string;
+  params_schema: JsonSchema;
+  returns_schema?: JsonSchema;
+}
+
+/** JSON Schema 子集。 */
+export interface JsonSchema {
+  type?: string;
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  additionalProperties?: boolean;
+  enum?: unknown[];
+  default?: unknown;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  items?: JsonSchema;
+  minItems?: number;
+  maxItems?: number;
+  description?: string;
+}
+
+/** connect command 返回的连接元信息。 */
+export interface ConnectInfo {
+  capabilities: CapabilityDescriptor[];
+  agent_version: string | null;
+  authorized: string[] | null;
+  peer_cert_fp: string | null;
+  auth_mode: string;
+  client_id: string;
+}
+
+/** 能力执行失败的错误信息。 */
+export interface InvokeError {
+  name: string;
+  message: string;
+  data?: unknown;
+}
+
+/** 能力执行结果（业务层）。 */
+export interface InvokeResult<T = unknown> {
+  status: "ok" | "failed";
+  data?: T;
+  error?: InvokeError;
+}
+
+/** 连接状态。 */
+export type ConnState = "connected" | "reconnecting" | "closed";
+
+// ---------- 各能力的返回结构 ----------
+
+/** 被控端构建信息（v18 构建指纹 + 运行状态）。 */
+export interface BuildInfo {
+  version?: string;
+  hash?: string;
+  commit?: string;
+  built_at?: string;
+  /** 运行中 agent 脚本的 sha256（v21 证书/脚本交叉核对） */
+  cert_sha256?: string;
+  bytes?: number;
+  mtime_ms?: number;
+  node?: string;
+  started_at?: number;
+  uptime_ms?: number;
+}
+
+/** PowerShell 常驻助手状态（v15）。 */
+export interface PsHelperInfo {
+  spawned?: boolean;
+  hits?: number;
+  failures?: number;
+  consecutiveFailures?: number;
+  avg_ms?: number;
+  [k: string]: unknown;
+}
+
+/** v21 来源网段访问控制。 */
+export interface NetworkInfo {
+  /** null = **未配置 = 放行全部**（应尽快收敛） */
+  allow_from?: string[] | null;
+}
+
+export interface SystemInfo {
+  hostname?: string;
+  /** 被控端平台：'Windows' | 'macOS' | 'Linux' —— **平台门控能力的判断依据** */
+  os?: string;
+  os_version?: string;
+  arch?: string;
+  cpu_model?: string;
+  cpu_cores?: number;
+  memory_total?: number;
+  uptime_sec?: number;
+  is_admin?: boolean;
+  pid?: number;
+  agent_home?: string;
+  /** 被控端入口脚本路径，供一键升级定位 */
+  agent_script?: string;
+  /** 被控端 Node 可执行文件路径（字段名是 `node_path`，没有独立的 `node`） */
+  node_path?: string;
+  ps_helper?: PsHelperInfo;
+  network?: NetworkInfo;
+  build?: BuildInfo;
+}
+
+/**
+ * 磁盘（对齐 manifest system.status.disks 契约）。
+ * 注意：**没有 `used` 字段**，已用量需自行算 `total - free`。
+ */
+export interface DiskInfo {
+  drive?: string;
+  total?: number;
+  free?: number;
+  used_pct?: number;
+}
+
+/** 网络适配器（对齐 manifest system.status.net 契约）。 */
+export interface NetInfo {
+  adapter?: string;
+  ip?: string;
+  up?: boolean;
+}
+
+export interface SystemStatus {
+  cpu_pct?: number;
+  memory_used?: number;
+  memory_total?: number;
+  memory_pct?: number;
+  disks?: DiskInfo[];
+  net?: NetInfo[];
+}
+
+/** 进程项（对齐 manifest system.process.list 契约）。 */
+export interface ProcessEntry {
+  pid: number;
+  name: string;
+  /** CPU 占用百分比（非 `cpu`） */
+  cpu_pct?: number;
+  /** 常驻内存字节数（非 `memory`） */
+  memory_bytes?: number;
+  started_at?: number;
+}
+
+/** 服务项（对齐 manifest system.service.list 契约）。 */
+export interface ServiceEntry {
+  name: string;
+  display_name?: string;
+  /** 运行状态字段名是 `state`，不是 `status` */
+  state?: string;
+  start_type?: string;
+}
+
+export interface FsEntry {
+  name: string;
+  path: string;
+  type: "file" | "dir" | "other";
+  size: number;
+  mtime: number;
+}
+
+export interface FsListResult {
+  entries: FsEntry[];
+  total: number;
+  truncated: boolean;
+}
+
+export interface FsReadResult {
+  data: string;
+  encoding: string;
+  offset: number;
+  bytes: number;
+  total_bytes: number;
+  eof: boolean;
+  sha256?: string;
+}
+
+/** 已装软件项（对齐 manifest app.list 契约）。 */
+export interface AppEntry {
+  name: string;
+  version?: string;
+  publisher?: string;
+  /** 'registry' | 'uwp' | 'winget' 等来源标记 */
+  source?: string;
+}
+
+/** 审计事件类别（对齐 apps/agent/src/audit.ts 的 `AuditType`）。 */
+export type AuditType =
+  | "agent.start"
+  | "agent.stop"
+  | "auth.success"
+  | "auth.failure"
+  | "invoke"
+  | "acl.denied"
+  | "capability.disabled"
+  | "rate.limited"
+  | "net.change"
+  | "net.deny"
+  | "agent.update"
+  | "session.idle_close";
+
+export interface AuditEntry {
+  ts?: number;
+  type?: AuditType | string;
+  client_id?: string;
+  remote?: string;
+  capability?: string;
+  status?: "ok" | "failed" | "denied";
+  duration_ms?: number;
+  error?: string | null;
+  /** 参数摘要（sha256 前缀）——默认只记摘要，不记内容 */
+  args_digest?: string;
+  /** 参数预览（仅 `log_args:true` 时记录，键含敏感词自动脱敏） */
+  args_preview?: string;
+  reason?: string;
+  /** v11 防篡改：上一条哈希（首条为 "genesis"） */
+  prev?: string;
+  /** v11 防篡改：本条哈希 */
+  hash?: string;
+}
+
+export interface AuditListResult {
+  entries: AuditEntry[];
+  total: number;
+  file?: string;
+}
+
+/** 审计链首个异常位置（`ok:false` 时存在）。 */
+export interface AuditBrokenAt {
+  file?: string;
+  line?: number;
+  reason?: string;
+}
+
+export interface AuditVerifyResult {
+  ok: boolean;
+  checked: number;
+  /** 无链字段的历史条目数（跳过校验） */
+  legacy?: number;
+  /** 是**对象**而非数字 */
+  broken_at?: AuditBrokenAt | null;
+}

apps/console/src/utils/format.ts

@@ -0,0 +1,33 @@
+/** 通用格式化工具。 */
+
+export function formatBytes(n?: number | null): string {
+  if (n == null || Number.isNaN(n)) return "-";
+  const units = ["B", "KB", "MB", "GB", "TB", "PB"];
+  let v = n;
+  let i = 0;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i++;
+  }
+  return `${v.toFixed(i === 0 ? 0 : 1)} ${units[i]}`;
+}
+
+export function formatDuration(sec?: number | null): string {
+  if (sec == null || Number.isNaN(sec)) return "-";
+  const d = Math.floor(sec / 86400);
+  const h = Math.floor((sec % 86400) / 3600);
+  const m = Math.floor((sec % 3600) / 60);
+  if (d) return `${d} 天 ${h} 小时`;
+  if (h) return `${h} 小时 ${m} 分`;
+  return `${m} 分`;
+}
+
+export function formatTime(ms?: number | null): string {
+  if (!ms) return "-";
+  return new Date(ms).toLocaleString("zh-CN", { hour12: false });
+}
+
+export function formatPct(v?: number | null): string {
+  if (v == null || Number.isNaN(v)) return "-";
+  return `${v.toFixed(1)}%`;
+}

apps/console/src/views/AuditView.vue

@@ -0,0 +1,178 @@
+<script setup lang="ts">
+import { h, onMounted, ref } from "vue";
+import {
+  NCard,
+  NDataTable,
+  NButton,
+  NSpace,
+  NInputNumber,
+  NSelect,
+  NText,
+  NTag,
+  NEmpty,
+  NAlert,
+  useMessage,
+  type DataTableColumns,
+} from "naive-ui";
+import { useConnStore } from "../stores/conn";
+import type { AuditEntry, AuditListResult, AuditVerifyResult } from "../types";
+import { formatTime } from "../utils/format";
+
+const conn = useConnStore();
+const msg = useMessage();
+
+const entries = ref<AuditEntry[]>([]);
+const total = ref(0);
+const limit = ref(100);
+const typeFilter = ref<string | null>(null);
+const loading = ref(false);
+const verify = ref<AuditVerifyResult | null>(null);
+
+const typeOptions = [
+  { label: "全部", value: "" },
+  { label: "invoke", value: "invoke" },
+  { label: "auth.success", value: "auth.success" },
+  { label: "auth.failure", value: "auth.failure" },
+  { label: "acl.denied", value: "acl.denied" },
+  { label: "capability.disabled", value: "capability.disabled" },
+  { label: "rate.limited", value: "rate.limited" },
+  { label: "net.deny", value: "net.deny" },
+  { label: "net.change", value: "net.change" },
+  { label: "agent.update", value: "agent.update" },
+  { label: "agent.start", value: "agent.start" },
+  { label: "agent.stop", value: "agent.stop" },
+];
+
+const cols: DataTableColumns<AuditEntry> = [
+  { title: "时间", key: "ts", width: 180, render: (r) => formatTime(r.ts) },
+  {
+    title: "类型",
+    key: "type",
+    width: 150,
+    render: (r) => {
+      const t = r.type ?? "-";
+      const kind = t.includes("denied") || t.includes("failure") || t.includes("deny") ? "error" : "default";
+      return h(NTag, { size: "small", type: kind }, { default: () => t });
+    },
+  },
+  { title: "调用方", key: "client_id", width: 110 },
+  { title: "来源", key: "remote", width: 120 },
+  { title: "能力", key: "capability", ellipsis: { tooltip: true } },
+  {
+    title: "状态",
+    key: "status",
+    width: 90,
+    render: (r) => {
+      if (!r.status) return "-";
+      const kind = r.status === "ok" ? "success" : "error";
+      return h(NTag, { size: "small", type: kind }, { default: () => r.status });
+    },
+  },
+  { title: "耗时", key: "duration_ms", width: 90, render: (r) => (r.duration_ms != null ? `${r.duration_ms}ms` : "-") },
+  {
+    title: "参数摘要",
+    key: "args_digest",
+    width: 170,
+    ellipsis: { tooltip: true },
+    render: (r) => r.args_digest ?? "-",
+  },
+  {
+    title: "说明",
+    key: "reason",
+    ellipsis: { tooltip: true },
+    render: (r) => r.reason || r.error || "-",
+  },
+];
+
+async function load() {
+  loading.value = true;
+  try {
+    const args: Record<string, unknown> = { limit: limit.value };
+    if (typeFilter.value) args.type = typeFilter.value;
+    const r = await conn.ok<AuditListResult>("system.audit.list", args);
+    entries.value = r.entries ?? [];
+    total.value = r.total ?? entries.value.length;
+  } catch (e) {
+    msg.error(`加载审计失败：${e}`);
+  } finally {
+    loading.value = false;
+  }
+}
+
+async function runVerify() {
+  try {
+    verify.value = await conn.ok<AuditVerifyResult>("system.audit.verify", {});
+  } catch (e) {
+    msg.error(`校验失败：${e}`);
+  }
+}
+
+async function exportJsonl() {
+  const text = entries.value.map((e) => JSON.stringify(e)).join("\n");
+  try {
+    await navigator.clipboard.writeText(text);
+    msg.success(`已复制 ${entries.value.length} 条到剪贴板`);
+  } catch {
+    msg.warning("剪贴板不可用");
+  }
+}
+
+onMounted(() => {
+  if (conn.connected) load();
+});
+</script>
+
+<template>
+  <div v-if="!conn.connected">
+    <n-empty description="请先在「设备管理」页连接被控端" style="margin-top: 80px" />
+  </div>
+
+  <div v-else class="wrap">
+    <n-card size="small">
+      <template #header>
+        <n-space align="center">
+          <span>审计日志</span>
+          <n-text depth="3" style="font-size: 12px">共 {{ total }} 条</n-text>
+        </n-space>
+      </template>
+      <template #header-extra>
+        <n-space align="center">
+          <n-select
+            v-model:value="typeFilter"
+            :options="typeOptions"
+            size="small"
+            style="width: 140px"
+            @update:value="load"
+          />
+          <n-input-number v-model:value="limit" :min="10" :max="2000" :step="50" size="small" style="width: 110px" />
+          <n-button size="small" :loading="loading" @click="load">刷新</n-button>
+          <n-button size="small" @click="runVerify">完整性校验</n-button>
+          <n-button size="small" @click="exportJsonl">导出</n-button>
+        </n-space>
+      </template>
+
+      <n-alert
+        v-if="verify"
+        :type="verify.ok ? 'success' : 'error'"
+        :show-icon="true"
+        style="margin-bottom: 12px"
+      >
+        完整性校验：{{ verify.ok ? "通过" : "发现问题" }} · 已校验 {{ verify.checked }} 条
+        <template v-if="verify.legacy"> · 跳过 {{ verify.legacy }} 条历史条目</template>
+        <template v-if="verify.broken_at">
+          · 首个断点：{{ verify.broken_at.file }} 第 {{ verify.broken_at.line }} 行
+          <template v-if="verify.broken_at.reason">（{{ verify.broken_at.reason }}）</template>
+        </template>
+      </n-alert>
+
+      <n-empty v-if="!entries.length" description="暂无审计记录" size="small" />
+      <n-data-table v-else :columns="cols" :data="entries" :bordered="false" size="small" :max-height="560" />
+    </n-card>
+  </div>
+</template>
+
+<style scoped>
+.wrap {
+  max-width: 1200px;
+}
+</style>

apps/console/src/views/FilesView.vue

@@ -0,0 +1,240 @@
+<script setup lang="ts">
+import { onMounted, ref } from "vue";
+import {
+  NCard,
+  NInput,
+  NButton,
+  NSpace,
+  NText,
+  NEmpty,
+  NDataTable,
+  NModal,
+  NTag,
+  useMessage,
+  useDialog,
+  type DataTableColumns,
+} from "naive-ui";
+import { useConnStore } from "../stores/conn";
+import type { FsEntry, FsListResult, FsReadResult, SystemInfo } from "../types";
+import { formatBytes, formatTime } from "../utils/format";
+
+const conn = useConnStore();
+const msg = useMessage();
+const dialog = useDialog();
+
+const cwd = ref("");
+const entries = ref<FsEntry[]>([]);
+const loading = ref(false);
+const truncated = ref(false);
+
+const previewOpen = ref(false);
+const previewName = ref("");
+const previewText = ref("");
+const previewMeta = ref("");
+
+const writeOpen = ref(false);
+const wName = ref("");
+const wContent = ref("");
+const wAppend = ref(false);
+
+const cols: DataTableColumns<FsEntry> = [
+  {
+    title: "名称",
+    key: "name",
+    render: (r) => r.name + (r.type === "dir" ? "/" : ""),
+  },
+  { title: "类型", key: "type", width: 80 },
+  { title: "大小", key: "size", width: 110, render: (r) => (r.type === "file" ? formatBytes(r.size) : "-") },
+  { title: "修改时间", key: "mtime", width: 180, render: (r) => formatTime(r.mtime) },
+];
+
+async function list(path: string) {
+  if (!path) return;
+  loading.value = true;
+  try {
+    const r = await conn.ok<FsListResult>("fs.list", { path });
+    entries.value = (r.entries ?? []).slice().sort((a, b) => {
+      if (a.type === "dir" && b.type !== "dir") return -1;
+      if (a.type !== "dir" && b.type === "dir") return 1;
+      return a.name.localeCompare(b.name);
+    });
+    truncated.value = !!r.truncated;
+    cwd.value = path;
+  } catch (e) {
+    msg.error(`列目录失败：${e}`);
+  } finally {
+    loading.value = false;
+  }
+}
+
+function parentOf(p: string): string {
+  const s = p.replace(/[\\/]+$/, "");
+  const idx = Math.max(s.lastIndexOf("/"), s.lastIndexOf("\\"));
+  if (idx < 0) return s;
+  if (idx === 0) return s.slice(0, 1); // POSIX 根
+  const r = s.slice(0, idx);
+  return /^[A-Za-z]:$/.test(r) ? r + "\\" : r; // Windows 盘符
+}
+
+function onRowClick(row: FsEntry) {
+  if (row.type === "dir") list(row.path);
+  else preview(row);
+}
+
+async function preview(row: FsEntry) {
+  try {
+    const r = await conn.ok<FsReadResult>("fs.read", {
+      path: row.path,
+      encoding: "utf8",
+      max_bytes: 262144,
+    });
+    previewName.value = row.name;
+    previewText.value = (r.data ?? "").replace(/\u0000/g, "");
+    previewMeta.value = `${formatBytes(r.total_bytes)}${r.eof ? "" : " · 已截断预览"}${r.sha256 ? ` · sha256 ${r.sha256.slice(0, 12)}…` : ""}`;
+    previewOpen.value = true;
+  } catch (e) {
+    msg.error(`读取失败：${e}`);
+  }
+}
+
+function openWrite() {
+  wName.value = "";
+  wContent.value = "";
+  wAppend.value = false;
+  writeOpen.value = true;
+}
+
+function doWrite() {
+  if (!wName.value) return;
+  const sep = cwd.value.includes("\\") ? "\\" : "/";
+  const path = cwd.value.replace(/[\\/]+$/, "") + sep + wName.value;
+  dialog.warning({
+    title: "确认写入被控端",
+    content: `目标：${path}\n模式：${wAppend.value ? "追加" : "覆盖"}\n字节：${wContent.value.length}`,
+    positiveText: "写入",
+    negativeText: "取消",
+    onPositiveClick: () => writeTo(path),
+  });
+}
+
+async function writeTo(path: string) {
+  try {
+    await conn.ok("fs.write", { path, data: wContent.value, append: wAppend.value, create_dirs: true });
+    msg.success(`已写入 ${path}`);
+    writeOpen.value = false;
+    list(cwd.value);
+  } catch (e) {
+    msg.error(`写入失败：${e}`);
+  }
+}
+
+async function ensureStart() {
+  try {
+    const info = await conn.ok<SystemInfo>("system.info", { fields: ["agent_home", "os"] });
+    let start = info.agent_home ?? "";
+    if (!start) start = info.os === "Windows" ? "C:\\" : "/";
+    list(start);
+  } catch {
+    list(conn.info ? "/" : "");
+  }
+}
+
+onMounted(() => {
+  if (conn.connected) ensureStart();
+});
+</script>
+
+<template>
+  <div v-if="!conn.connected">
+    <n-empty description="请先在「设备管理」页连接被控端" style="margin-top: 80px" />
+  </div>
+
+  <div v-else class="wrap">
+    <n-card size="small">
+      <n-space align="center" :wrap="false">
+        <n-input
+          v-model:value="cwd"
+          size="small"
+          placeholder="输入路径，回车列目录（如 C:\ 或 /Users）"
+          style="flex: 1"
+          @keyup.enter="list(cwd)"
+        />
+        <n-button size="small" @click="list(parentOf(cwd))">上级</n-button>
+        <n-button size="small" :loading="loading" @click="list(cwd)">刷新</n-button>
+        <n-button size="small" type="primary" @click="openWrite">新建文件</n-button>
+      </n-space>
+      <div class="path">
+        <n-text depth="3" style="font-size: 12px">
+          当前：{{ cwd || "-" }} · {{ entries.length }} 项
+          <n-tag v-if="truncated" size="tiny" type="warning" style="margin-left: 6px">结果被截断</n-tag>
+        </n-text>
+      </div>
+    </n-card>
+
+    <n-card size="small" style="margin-top: 16px">
+      <n-empty v-if="!entries.length" description="目录为空或未加载" size="small" />
+      <n-data-table
+        v-else
+        :columns="cols"
+        :data="entries"
+        :bordered="false"
+        size="small"
+        :max-height="520"
+        :row-props="(row: FsEntry) => ({ style: 'cursor:pointer', onClick: () => onRowClick(row) })"
+      />
+    </n-card>
+  </div>
+
+  <!-- 预览 -->
+  <n-modal v-model:show="previewOpen" preset="card" :title="previewName" style="width: 820px; max-width: 90vw">
+    <n-text depth="3" style="font-size: 12px">{{ previewMeta }}</n-text>
+    <pre class="preview">{{ previewText || "(空文件)" }}</pre>
+  </n-modal>
+
+  <!-- 新建/写入 -->
+  <n-modal v-model:show="writeOpen" preset="card" title="写入文件" style="width: 640px; max-width: 90vw">
+    <n-space vertical>
+      <n-input v-model:value="wName" placeholder="文件名（写入当前目录）" size="small" />
+      <n-input
+        v-model:value="wContent"
+        type="textarea"
+        :autosize="{ minRows: 6, maxRows: 16 }"
+        placeholder="文件内容（utf8）"
+      />
+      <n-space align="center">
+        <n-tag
+          size="small"
+          :type="wAppend ? 'warning' : 'default'"
+          checkable
+          :checked="wAppend"
+          @update:checked="(v: boolean) => (wAppend = v)"
+        >
+          追加模式
+        </n-tag>
+        <n-button size="small" type="primary" @click="doWrite">写入</n-button>
+      </n-space>
+    </n-space>
+  </n-modal>
+</template>
+
+<style scoped>
+.wrap {
+  max-width: 1100px;
+}
+.path {
+  margin-top: 10px;
+}
+.preview {
+  margin: 12px 0 0;
+  padding: 12px;
+  border-radius: 8px;
+  background: rgba(0, 0, 0, 0.3);
+  font-family: ui-monospace, Menlo, monospace;
+  font-size: 12px;
+  line-height: 1.6;
+  white-space: pre-wrap;
+  word-break: break-all;
+  max-height: 60vh;
+  overflow: auto;
+}
+</style>

apps/console/src/views/NodesView.vue

@@ -0,0 +1,235 @@
+<script setup lang="ts">
+import { computed, ref } from "vue";
+import {
+  NCard,
+  NInput,
+  NButton,
+  NSpace,
+  NTag,
+  NEmpty,
+  NText,
+  NInputGroup,
+  NCollapse,
+  NCollapseItem,
+  NPopconfirm,
+  useMessage,
+} from "naive-ui";
+import { useConnStore } from "../stores/conn";
+import { useNodeStore } from "../stores/node";
+
+const conn = useConnStore();
+const nodeStore = useNodeStore();
+const msg = useMessage();
+
+const newName = ref("");
+const newUrl = ref("ws://127.0.0.1:8765");
+const newKey = ref("");
+
+async function doConnect() {
+  try {
+    await conn.connect();
+    msg.success("连接成功");
+  } catch (e) {
+    msg.error(`连接失败：${e}`);
+  }
+}
+
+async function connectTo(id: string) {
+  const n = nodeStore.nodes.find((x) => x.id === id);
+  if (!n) return;
+  nodeStore.setCurrent(id);
+  try {
+    await conn.connect(n.url, n.key);
+    msg.success(`已连接 ${n.name}`);
+  } catch (e) {
+    msg.error(`连接失败：${e}`);
+  }
+}
+
+function addNode() {
+  if (!newName.value || !newUrl.value) {
+    msg.warning("请填写名称与地址");
+    return;
+  }
+  nodeStore.add({ name: newName.value, url: newUrl.value, key: newKey.value });
+  newName.value = "";
+  newKey.value = "";
+  msg.success("已保存设备");
+}
+
+/** 能力按前缀分组，便于核对。 */
+const capGroups = computed(() => {
+  const groups: Record<string, string[]> = {};
+  for (const c of conn.capabilities) {
+    const prefix = c.name.split(".")[0] ?? "other";
+    (groups[prefix] ??= []).push(c.name);
+  }
+  return groups;
+});
+</script>
+
+<template>
+  <div class="grid">
+    <n-card title="连接被控端" size="small">
+      <n-space vertical>
+        <n-input-group>
+          <n-input v-model:value="conn.url" placeholder="ws://127.0.0.1:8765" style="flex: 3" />
+          <n-input
+            v-model:value="conn.key"
+            type="password"
+            show-password-on="click"
+            placeholder="PSK 预共享密钥"
+            style="flex: 2"
+          />
+          <n-button type="primary" :loading="conn.connecting" @click="doConnect">连接</n-button>
+        </n-input-group>
+        <div v-if="conn.info" class="meta">
+          <n-tag type="success" size="small" round>已连接</n-tag>
+          <n-text depth="3">agent {{ conn.info.agent_version ?? "?" }}</n-text>
+          <n-text depth="3">
+            授权 {{ conn.info.authorized ? `${conn.info.authorized.length} 项` : "全部" }}
+          </n-text>
+          <n-text depth="3" class="mono">
+            指纹 {{ (conn.info.peer_cert_fp ?? "-").slice(0, 16) }}…
+          </n-text>
+        </div>
+        <n-empty v-else description="尚未连接" size="small" />
+      </n-space>
+    </n-card>
+
+    <n-card title="已保存设备" size="small">
+      <template #header-extra>
+        <n-text depth="3" style="font-size: 12px">{{ nodeStore.nodes.length }} 台</n-text>
+      </template>
+      <div v-if="nodeStore.nodes.length" class="nodes">
+        <div
+          v-for="n in nodeStore.nodes"
+          :key="n.id"
+          class="node"
+          :class="{ active: nodeStore.currentId === n.id }"
+        >
+          <div class="node-main">
+            <div class="node-name">{{ n.name }}</div>
+            <n-text depth="3" class="mono" style="font-size: 12px">{{ n.url }}</n-text>
+          </div>
+          <n-space>
+            <n-button size="tiny" type="primary" @click="connectTo(n.id)">连接</n-button>
+            <n-popconfirm @positive-click="nodeStore.remove(n.id)">
+              <template #trigger>
+                <n-button size="tiny" quaternary>删除</n-button>
+              </template>
+              确认删除该设备？
+            </n-popconfirm>
+          </n-space>
+        </div>
+      </div>
+      <n-empty v-else description="暂无保存的设备" size="small" />
+
+      <div class="add-row">
+        <n-input v-model:value="newName" placeholder="名称" size="small" style="flex: 1" />
+        <n-input v-model:value="newUrl" placeholder="地址" size="small" style="flex: 2" />
+        <n-input v-model:value="newKey" placeholder="PSK" size="small" style="flex: 1" />
+        <n-button size="small" @click="addNode">保存</n-button>
+      </div>
+    </n-card>
+
+    <n-card title="能力清单" size="small">
+      <template #header-extra>
+        <n-text depth="3" style="font-size: 12px">{{ conn.capabilities.length }} 项</n-text>
+      </template>
+      <n-collapse v-if="conn.capabilities.length" :default-expanded-names="Object.keys(capGroups)">
+        <n-collapse-item
+          v-for="(caps, prefix) in capGroups"
+          :key="prefix"
+          :name="prefix"
+          :title="`${prefix}.*  (${caps.length})`"
+        >
+          <div class="cap-list">
+            <code v-for="c in caps" :key="c">{{ c }}</code>
+          </div>
+        </n-collapse-item>
+      </n-collapse>
+      <n-empty v-else description="连接后展示" size="small" />
+    </n-card>
+
+    <n-card title="日志" size="small">
+      <template #header-extra>
+        <n-button size="tiny" quaternary @click="conn.clearLogs()">清空</n-button>
+      </template>
+      <div class="logs">
+        <div v-for="(l, i) in conn.logs.slice().reverse()" :key="i">{{ l }}</div>
+        <div v-if="conn.logs.length === 0" class="logs-empty">暂无日志</div>
+      </div>
+    </n-card>
+  </div>
+</template>
+
+<style scoped>
+.grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 16px;
+  align-items: start;
+}
+.grid > :nth-child(3),
+.grid > :nth-child(4) {
+  grid-column: span 2;
+}
+.meta {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  flex-wrap: wrap;
+  font-size: 13px;
+}
+.mono {
+  font-family: ui-monospace, Menlo, monospace;
+}
+.nodes {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.node {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 8px 12px;
+  border: 1px solid rgba(255, 255, 255, 0.09);
+  border-radius: 8px;
+}
+.node.active {
+  border-color: #63e2b7;
+}
+.node-name {
+  font-size: 14px;
+  margin-bottom: 2px;
+}
+.add-row {
+  display: flex;
+  gap: 8px;
+  margin-top: 12px;
+}
+.cap-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+.cap-list code {
+  font-size: 12px;
+  padding: 2px 8px;
+  border-radius: 4px;
+  background: rgba(255, 255, 255, 0.06);
+}
+.logs {
+  font-family: ui-monospace, Menlo, monospace;
+  font-size: 12px;
+  line-height: 1.7;
+  opacity: 0.85;
+  max-height: 220px;
+  overflow: auto;
+}
+.logs-empty {
+  opacity: 0.4;
+}
+</style>

apps/console/src/views/OverviewView.vue

@@ -0,0 +1,200 @@
+<script setup lang="ts">
+import { onMounted, onUnmounted, ref } from "vue";
+import {
+  NCard,
+  NGrid,
+  NGridItem,
+  NProgress,
+  NStatistic,
+  NButton,
+  NSpace,
+  NEmpty,
+  NText,
+  NSwitch,
+  NTag,
+  useMessage,
+} from "naive-ui";
+import { useConnStore } from "../stores/conn";
+import type { DiskInfo, SystemInfo, SystemStatus } from "../types";
+import { formatBytes, formatDuration } from "../utils/format";
+
+const conn = useConnStore();
+const msg = useMessage();
+
+const info = ref<SystemInfo | null>(null);
+const status = ref<SystemStatus | null>(null);
+const auto = ref(true);
+let timer: number | undefined;
+
+/** 契约只给 total/free，已用量需自算。 */
+function usedOf(d: DiskInfo): number | undefined {
+  if (d.total == null || d.free == null) return undefined;
+  return Math.max(0, d.total - d.free);
+}
+
+async function refresh() {
+  if (!conn.connected) return;
+  try {
+    const [i, s] = await Promise.all([
+      conn.ok<SystemInfo>("system.info"),
+      conn.ok<SystemStatus>("system.status"),
+    ]);
+    info.value = i;
+    status.value = s;
+  } catch (e) {
+    msg.error(`刷新失败：${e}`);
+  }
+}
+
+function toggleAuto(v: boolean) {
+  auto.value = v;
+  if (v) start(); else stop();
+}
+
+function start() {
+  stop();
+  timer = window.setInterval(refresh, 3000);
+}
+function stop() {
+  if (timer) window.clearInterval(timer);
+  timer = undefined;
+}
+
+onMounted(() => {
+  if (conn.connected) refresh();
+  if (auto.value) start();
+});
+onUnmounted(stop);
+</script>
+
+<template>
+  <div v-if="!conn.connected">
+    <n-empty description="请先在「设备管理」页连接被控端" style="margin-top: 80px" />
+  </div>
+
+  <div v-else class="wrap">
+    <n-space justify="space-between" align="center" style="margin-bottom: 14px">
+      <n-space align="center">
+        <n-text depth="3">自动刷新（3s）</n-text>
+        <n-switch :value="auto" size="small" @update:value="toggleAuto" />
+      </n-space>
+      <n-button size="small" @click="refresh">手动刷新</n-button>
+    </n-space>
+
+    <n-grid :cols="4" :x-gap="16" :y-gap="16" item-responsive responsive="screen">
+      <n-grid-item span="4 s:2">
+        <n-card size="small" title="主机">
+          <n-statistic label="主机名" :value="info?.hostname ?? '-'" />
+          <div class="kv"><span>系统</span><b>{{ info?.os }} {{ info?.os_version }}</b></div>
+          <div class="kv"><span>架构</span><b>{{ info?.arch }}</b></div>
+          <div class="kv"><span>CPU</span><b>{{ info?.cpu_model }}</b></div>
+          <div class="kv"><span>核心</span><b>{{ info?.cpu_cores }}</b></div>
+          <div class="kv"><span>管理员</span><b>{{ info?.is_admin ? "是" : "否" }}</b></div>
+          <div class="kv"><span>开机</span><b>{{ formatDuration(info?.uptime_sec) }}</b></div>
+        </n-card>
+      </n-grid-item>
+
+      <n-grid-item span="4 s:2">
+        <n-card size="small" title="资源">
+          <div class="gauge">
+            <div class="gauge-label">CPU 使用率</div>
+            <n-progress
+              type="line"
+              :percentage="Math.round(status?.cpu_pct ?? 0)"
+              :height="10"
+              :color="(status?.cpu_pct ?? 0) > 80 ? '#e88080' : '#63e2b7'"
+            />
+          </div>
+          <div class="gauge">
+            <div class="gauge-label">
+              内存 {{ formatBytes(status?.memory_used) }} / {{ formatBytes(status?.memory_total) }}
+            </div>
+            <n-progress
+              type="line"
+              :percentage="Math.round(status?.memory_pct ?? 0)"
+              :height="10"
+              :color="(status?.memory_pct ?? 0) > 85 ? '#e88080' : '#63e2b7'"
+            />
+          </div>
+          <n-statistic
+            label="内存总量"
+            :value="formatBytes(info?.memory_total ?? status?.memory_total)"
+          />
+        </n-card>
+      </n-grid-item>
+
+      <n-grid-item span="4">
+        <n-card size="small" title="磁盘">
+          <div v-if="status?.disks?.length" class="disks">
+            <div v-for="(d, i) in status.disks" :key="i" class="disk">
+              <div class="gauge-label">
+                {{ d.drive ?? "-" }}
+                <span class="dim">
+                  {{ formatBytes(usedOf(d)) }} / {{ formatBytes(d.total) }} · 剩余
+                  {{ formatBytes(d.free) }}
+                </span>
+              </div>
+              <n-progress
+                type="line"
+                :percentage="Math.round(d.used_pct ?? 0)"
+                :height="8"
+                :color="(d.used_pct ?? 0) > 90 ? '#e88080' : '#63e2b7'"
+              />
+            </div>
+          </div>
+          <n-empty v-else description="无磁盘数据" size="small" />
+        </n-card>
+      </n-grid-item>
+
+      <n-grid-item span="4">
+        <n-card size="small" title="网络适配器">
+          <div v-if="status?.net?.length" class="net">
+            <div v-for="(a, i) in status.net" :key="i" class="kv">
+              <span>{{ a.adapter ?? "-" }}</span>
+              <b>
+                {{ a.ip || "-" }}
+                <n-tag :type="a.up ? 'success' : 'default'" size="tiny" style="margin-left: 6px">
+                  {{ a.up ? "已连接" : "未连接" }}
+                </n-tag>
+              </b>
+            </div>
+          </div>
+          <n-empty v-else description="无网络数据" size="small" />
+        </n-card>
+      </n-grid-item>
+    </n-grid>
+  </div>
+</template>
+
+<style scoped>
+.wrap {
+  max-width: 1100px;
+}
+.kv {
+  display: flex;
+  justify-content: space-between;
+  font-size: 13px;
+  padding: 3px 0;
+}
+.kv span {
+  opacity: 0.6;
+}
+.gauge {
+  margin-bottom: 14px;
+}
+.gauge-label {
+  font-size: 13px;
+  margin-bottom: 6px;
+  opacity: 0.8;
+}
+.dim {
+  opacity: 0.5;
+  font-size: 12px;
+  margin-left: 8px;
+}
+.disks {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+</style>

apps/console/src/views/ProcessesView.vue

@@ -0,0 +1,189 @@
+<script setup lang="ts">
+import { computed, h, onMounted, ref } from "vue";
+import {
+  NCard,
+  NTabs,
+  NTabPane,
+  NDataTable,
+  NButton,
+  NSpace,
+  NInput,
+  NEmpty,
+  NTag,
+  NAlert,
+  type DataTableColumns,
+} from "naive-ui";
+import { useConnStore } from "../stores/conn";
+import type { ProcessEntry, ServiceEntry } from "../types";
+import { formatBytes, formatDuration } from "../utils/format";
+
+const conn = useConnStore();
+
+const procs = ref<ProcessEntry[]>([]);
+const services = ref<ServiceEntry[]>([]);
+const procFilter = ref("");
+const svcFilter = ref("");
+const loading = ref(false);
+const listError = ref("");
+
+/** `system.service.list` 仅 Windows 被控端可用——事前门控。 */
+const servicesAvailable = computed(() => conn.platformReady);
+
+const procCols: DataTableColumns<ProcessEntry> = [
+  { title: "PID", key: "pid", width: 90, sorter: (a, b) => (a.pid ?? 0) - (b.pid ?? 0) },
+  { title: "名称", key: "name", ellipsis: { tooltip: true } },
+  {
+    title: "CPU",
+    key: "cpu_pct",
+    width: 100,
+    sorter: (a, b) => (a.cpu_pct ?? 0) - (b.cpu_pct ?? 0),
+    render: (r) => (r.cpu_pct != null ? `${r.cpu_pct.toFixed(1)}%` : "-"),
+  },
+  {
+    title: "内存",
+    key: "memory_bytes",
+    width: 110,
+    sorter: (a, b) => (a.memory_bytes ?? 0) - (b.memory_bytes ?? 0),
+    render: (r) => (r.memory_bytes ? formatBytes(r.memory_bytes) : "-"),
+  },
+  {
+    title: "已运行",
+    key: "started_at",
+    width: 120,
+    render: (r) =>
+      r.started_at ? formatDuration(Math.floor((Date.now() - r.started_at) / 1000)) : "-",
+  },
+];
+
+const svcCols: DataTableColumns<ServiceEntry> = [
+  { title: "名称", key: "name", ellipsis: { tooltip: true } },
+  { title: "显示名", key: "display_name", ellipsis: { tooltip: true } },
+  {
+    title: "状态",
+    key: "state",
+    width: 130,
+    render: (r) =>
+      h(
+        NTag,
+        { size: "small", type: /run/i.test(r.state ?? "") ? "success" : "default" },
+        { default: () => r.state ?? "-" },
+      ),
+  },
+  { title: "启动类型", key: "start_type", width: 130 },
+];
+
+function pick<T>(raw: unknown, key: string): T[] {
+  if (Array.isArray(raw)) return raw as T[];
+  if (raw && typeof raw === "object" && Array.isArray((raw as Record<string, unknown>)[key])) {
+    return (raw as Record<string, T[]>)[key];
+  }
+  return [];
+}
+
+async function loadProcs() {
+  loading.value = true;
+  listError.value = "";
+  try {
+    const raw = await conn.ok("system.process.list", { limit: 200, sort_by: "cpu" });
+    procs.value = pick<ProcessEntry>(raw, "processes");
+  } catch (e) {
+    listError.value = String((e as Error).message ?? e);
+  } finally {
+    loading.value = false;
+  }
+}
+
+async function loadServices() {
+  if (!servicesAvailable.value) return;
+  loading.value = true;
+  listError.value = "";
+  try {
+    const raw = await conn.ok("system.service.list", {
+      limit: 200,
+      filter: svcFilter.value ? { name_pattern: svcFilter.value } : undefined,
+    });
+    services.value = pick<ServiceEntry>(raw, "services");
+  } catch (e) {
+    listError.value = String((e as Error).message ?? e);
+  } finally {
+    loading.value = false;
+  }
+}
+
+const filteredProcs = ref<ProcessEntry[]>([]);
+function applyProcFilter() {
+  const f = procFilter.value.trim().toLowerCase();
+  filteredProcs.value = f
+    ? procs.value.filter((p) => p.name?.toLowerCase().includes(f))
+    : procs.value;
+}
+
+onMounted(() => {
+  if (conn.connected) {
+    loadProcs().then(applyProcFilter);
+    loadServices();
+  }
+});
+</script>
+
+<template>
+  <div v-if="!conn.connected">
+    <n-empty description="请先在「设备管理」页连接被控端" style="margin-top: 80px" />
+  </div>
+
+  <n-card v-else size="small">
+    <n-alert v-if="listError" type="error" :show-icon="true" style="margin-bottom: 12px">
+      {{ listError }}
+    </n-alert>
+
+    <n-tabs type="line" animated>
+      <n-tab-pane name="proc" tab="进程">
+        <n-space align="center" style="margin-bottom: 12px">
+          <n-input
+            v-model:value="procFilter"
+            placeholder="按名称筛选"
+            size="small"
+            style="width: 220px"
+            @input="applyProcFilter"
+          />
+          <n-button size="small" :loading="loading" @click="loadProcs().then(applyProcFilter)">
+            刷新
+          </n-button>
+          <n-text depth="3" style="font-size: 12px">{{ filteredProcs.length }} / {{ procs.length }}</n-text>
+        </n-space>
+        <n-empty v-if="!filteredProcs.length" description="暂无进程数据" size="small" />
+        <n-data-table
+          v-else
+          :columns="procCols"
+          :data="filteredProcs"
+          :bordered="false"
+          :max-height="520"
+          size="small"
+        />
+      </n-tab-pane>
+
+      <n-tab-pane name="svc" tab="服务">
+        <n-alert v-if="!servicesAvailable" type="warning" :show-icon="true">
+          `system.service.list` 仅在被控端为 <b>Windows</b> 时可用；当前被控端为
+          <b>{{ conn.nodeOs ?? "未知" }}</b>。
+        </n-alert>
+        <template v-else>
+          <n-space align="center" style="margin-bottom: 12px">
+            <n-input v-model:value="svcFilter" placeholder="筛选服务名" size="small" style="width: 220px" />
+            <n-button size="small" :loading="loading" @click="loadServices">刷新</n-button>
+            <n-text depth="3" style="font-size: 12px">{{ services.length }} 项</n-text>
+          </n-space>
+          <n-empty v-if="!services.length" description="暂无服务数据" size="small" />
+          <n-data-table
+            v-else
+            :columns="svcCols"
+            :data="services"
+            :bordered="false"
+            :max-height="520"
+            size="small"
+          />
+        </template>
+      </n-tab-pane>
+    </n-tabs>
+  </n-card>
+</template>

apps/console/src/views/SoftwareView.vue

@@ -0,0 +1,183 @@
+<script setup lang="ts">
+import { computed, onMounted, ref } from "vue";
+import {
+  NCard,
+  NInput,
+  NButton,
+  NSpace,
+  NText,
+  NEmpty,
+  NDataTable,
+  NAlert,
+  useMessage,
+  useDialog,
+  type DataTableColumns,
+} from "naive-ui";
+import { useConnStore } from "../stores/conn";
+import type { AppEntry } from "../types";
+
+const conn = useConnStore();
+const msg = useMessage();
+const dialog = useDialog();
+
+const apps = ref<AppEntry[]>([]);
+const filter = ref("");
+const pkg = ref("");
+const loading = ref(false);
+const installing = ref(false);
+const installResult = ref("");
+const error = ref("");
+
+/** `app.list` / `app.install` 仅 Windows 被控端可用——事前门控。 */
+const available = computed(() => conn.platformReady);
+
+const cols: DataTableColumns<AppEntry> = [
+  { title: "名称", key: "name", ellipsis: { tooltip: true } },
+  { title: "版本", key: "version", width: 150 },
+  { title: "发布者", key: "publisher", ellipsis: { tooltip: true } },
+  { title: "来源", key: "source", width: 110 },
+];
+
+function pickApps(raw: unknown): AppEntry[] {
+  if (Array.isArray(raw)) return raw as AppEntry[];
+  if (raw && typeof raw === "object") {
+    const o = raw as Record<string, unknown>;
+    if (Array.isArray(o.apps)) return o.apps as AppEntry[];
+  }
+  return [];
+}
+
+const filtered = computed(() => {
+  const f = filter.value.trim().toLowerCase();
+  if (!f) return apps.value;
+  return apps.value.filter(
+    (a) =>
+      a.name?.toLowerCase().includes(f) ||
+      a.publisher?.toLowerCase().includes(f) ||
+      a.source?.toLowerCase().includes(f),
+  );
+});
+
+async function load() {
+  if (!available.value) return;
+  loading.value = true;
+  error.value = "";
+  try {
+    apps.value = pickApps(await conn.ok("app.list", {}, 120000));
+  } catch (e) {
+    error.value = String((e as Error).message ?? e);
+  } finally {
+    loading.value = false;
+  }
+}
+
+function doInstall() {
+  const p = pkg.value.trim();
+  if (!p) return;
+  dialog.warning({
+    title: "确认安装",
+    content: `将在被控端静默安装：${p}`,
+    positiveText: "安装",
+    negativeText: "取消",
+    onPositiveClick: () => install(p),
+  });
+}
+
+async function install(p: string) {
+  installing.value = true;
+  installResult.value = "";
+  try {
+    // winget 安装可能耗时数分钟，控制端 RPC 超时放大到 10 分钟。
+    const r = await conn.ok<Record<string, unknown>>(
+      "app.install",
+      { package: p, silent: true },
+      600_000,
+    );
+    installResult.value = JSON.stringify(r, null, 2);
+    msg.success("安装完成");
+    load();
+  } catch (e) {
+    installResult.value = String(e);
+    msg.error(`安装失败：${e}`);
+  } finally {
+    installing.value = false;
+  }
+}
+
+onMounted(() => {
+  if (conn.connected) load();
+});
+</script>
+
+<template>
+  <div v-if="!conn.connected">
+    <n-empty description="请先在「设备管理」页连接被控端" style="margin-top: 80px" />
+  </div>
+
+  <div v-else class="wrap">
+    <n-alert v-if="!available" type="warning" :show-icon="true" style="margin-bottom: 14px">
+      软件能力（<code>app.list</code> / <code>app.install</code>）依赖被控端 <code>winget</code>，
+      <b>仅在被控端为 Windows 时可用</b>；当前被控端为 <b>{{ conn.nodeOs ?? "未知" }}</b>，
+      本页已禁用。
+    </n-alert>
+    <n-alert v-else type="info" :show-icon="true" style="margin-bottom: 14px">
+      软件安装依赖被控端 <code>winget</code>。安装可能耗时数分钟，已把调用超时放大到 10 分钟。
+    </n-alert>
+
+    <n-alert v-if="error" type="error" :show-icon="true" style="margin-bottom: 14px">
+      {{ error }}
+    </n-alert>
+
+    <n-card size="small" title="静默安装（app.install）">
+      <n-space align="center">
+        <n-input
+          v-model:value="pkg"
+          :disabled="!available"
+          placeholder="winget 包名或 ID，例如 Git.Git / 7zip.7zip"
+          style="width: 420px"
+        />
+        <n-button type="primary" :loading="installing" :disabled="!available" @click="doInstall">
+          安装
+        </n-button>
+      </n-space>
+      <pre v-if="installResult" class="result">{{ installResult }}</pre>
+    </n-card>
+
+    <n-card size="small" title="已装软件（app.list）" style="margin-top: 16px">
+      <template #header-extra>
+        <n-space align="center">
+          <n-input
+            v-model:value="filter"
+            :disabled="!available"
+            placeholder="筛选"
+            size="small"
+            style="width: 180px"
+          />
+          <n-button size="small" :loading="loading" :disabled="!available" @click="load">刷新</n-button>
+          <n-text depth="3" style="font-size: 12px">{{ filtered.length }}</n-text>
+        </n-space>
+      </template>
+      <n-empty
+        v-if="!apps.length && !loading"
+        :description="available ? '暂无数据（点刷新）' : '当前被控端非 Windows，不支持'"
+        size="small"
+      />
+      <n-data-table v-else :columns="cols" :data="filtered" :bordered="false" size="small" :max-height="480" />
+    </n-card>
+  </div>
+</template>
+
+<style scoped>
+.wrap {
+  max-width: 1100px;
+}
+.result {
+  margin: 12px 0 0;
+  padding: 10px;
+  border-radius: 8px;
+  background: rgba(255, 255, 255, 0.05);
+  font-size: 12px;
+  max-height: 200px;
+  overflow: auto;
+}
+</style>

apps/console/src/views/TerminalView.vue

@@ -0,0 +1,166 @@
+<script setup lang="ts">
+import { computed, ref } from "vue";
+import {
+  NCard,
+  NInput,
+  NButton,
+  NSpace,
+  NInputNumber,
+  NText,
+  NTag,
+  NEmpty,
+  NList,
+  NListItem,
+  useMessage,
+  useDialog,
+} from "naive-ui";
+import { useConnStore } from "../stores/conn";
+
+interface ExecResult {
+  exit_code: number;
+  stdout?: string;
+  stderr?: string;
+  duration_ms?: number;
+  truncated?: boolean;
+  killed?: boolean;
+}
+
+const conn = useConnStore();
+const msg = useMessage();
+const dialog = useDialog();
+
+const cmd = ref("");
+const timeoutMs = ref(30000);
+const running = ref(false);
+const result = ref<ExecResult | null>(null);
+const history = ref<string[]>([]);
+
+const output = computed(() => {
+  if (!result.value) return "";
+  const r = result.value;
+  let out = "";
+  if (r.stdout) out += r.stdout;
+  if (r.stderr) out += (out ? "\n" : "") + r.stderr;
+  return out || "(无输出)";
+});
+
+async function exec() {
+  const command = cmd.value.trim();
+  if (!command) return;
+  if (!conn.connected) {
+    msg.warning("请先连接被控端");
+    return;
+  }
+  dialog.warning({
+    title: "确认执行远程命令",
+    content: `将在被控端执行：\n${command}`,
+    positiveText: "执行",
+    negativeText: "取消",
+    onPositiveClick: () => doExec(command),
+  });
+}
+
+async function doExec(command: string) {
+  running.value = true;
+  result.value = null;
+  try {
+    const r = await conn.ok<ExecResult>("system.shell.exec", {
+      command,
+      timeout_ms: timeoutMs.value,
+    });
+    result.value = r;
+    history.value = [command, ...history.value.filter((c) => c !== command)].slice(0, 20);
+    if (r.exit_code !== 0) msg.warning(`退出码 ${r.exit_code}`);
+  } catch (e) {
+    msg.error(`执行失败：${e}`);
+  } finally {
+    running.value = false;
+  }
+}
+
+function reuse(c: string) {
+  cmd.value = c;
+}
+</script>
+
+<template>
+  <div v-if="!conn.connected">
+    <n-empty description="请先在「设备管理」页连接被控端" style="margin-top: 80px" />
+  </div>
+
+  <div v-else class="wrap">
+    <n-card size="small" title="命令执行（system.shell.exec）">
+      <template #header-extra>
+        <n-text depth="3" style="font-size: 12px">⚠ 高权限操作，请谨慎</n-text>
+      </template>
+      <n-input
+        v-model:value="cmd"
+        type="textarea"
+        :autosize="{ minRows: 2, maxRows: 6 }"
+        placeholder="输入命令，例如：Get-Process | Select-Object -First 5"
+      />
+      <n-space align="center" style="margin-top: 12px">
+        <span class="label">超时(ms)</span>
+        <n-input-number v-model:value="timeoutMs" :min="1000" :step="1000" size="small" style="width: 140px" />
+        <n-button type="primary" :loading="running" @click="exec">执行</n-button>
+      </n-space>
+    </n-card>
+
+    <n-card v-if="result" size="small" title="输出">
+      <template #header-extra>
+        <n-space align="center">
+          <n-tag :type="result.exit_code === 0 ? 'success' : 'error'" size="small">
+            退出码 {{ result.exit_code }}
+          </n-tag>
+          <n-text depth="3" style="font-size: 12px">{{ result.duration_ms }}ms</n-text>
+          <n-tag v-if="result.truncated" size="small" type="warning">已截断</n-tag>
+          <n-tag v-if="result.killed" size="small" type="error">超时终止</n-tag>
+        </n-space>
+      </template>
+      <pre class="out">{{ output }}</pre>
+    </n-card>
+
+    <n-card v-if="history.length" size="small" title="历史">
+      <n-list>
+        <n-list-item v-for="(h, i) in history" :key="i">
+          <div class="hist" @click="reuse(h)">
+            <code>{{ h }}</code>
+          </div>
+        </n-list-item>
+      </n-list>
+    </n-card>
+  </div>
+</template>
+
+<style scoped>
+.wrap {
+  max-width: 1000px;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+.label {
+  font-size: 13px;
+  opacity: 0.7;
+}
+.out {
+  margin: 0;
+  font-family: ui-monospace, Menlo, monospace;
+  font-size: 12px;
+  line-height: 1.6;
+  white-space: pre-wrap;
+  word-break: break-all;
+  max-height: 460px;
+  overflow: auto;
+}
+.hist {
+  cursor: pointer;
+}
+.hist code {
+  font-size: 12px;
+  opacity: 0.85;
+}
+.hist:hover code {
+  color: #63e2b7;
+}
+</style>

apps/console/src/vite-env.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="vite/client" />
+
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+  const component: DefineComponent<{}, {}, any>;
+  export default component;
+}

apps/console/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "preserve",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}

apps/console/tsconfig.node.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["vite.config.ts"]
+}

apps/console/vite.config.ts

@@ -0,0 +1,32 @@
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+// @ts-expect-error type error without @types/node package
+import process from "node:process";
+const host = process.env.TAURI_DEV_HOST;
+
+// https://vite.dev/config/
+export default defineConfig(() => ({
+  plugins: [vue()],
+
+  // Vite options tailored for Tauri development and only applied in `tauri dev` or `tauri build`
+  //
+  // 1. prevent Vite from obscuring rust errors
+  clearScreen: false,
+  // 2. tauri expects a fixed port, fail if that port is not available
+  server: {
+    port: 1420,
+    strictPort: true,
+    host: host || false,
+    hmr: host
+      ? {
+          protocol: "ws",
+          host,
+          port: 1421,
+        }
+      : undefined,
+    watch: {
+      // 3. tell Vite to ignore watching `src-tauri`
+      ignored: ["**/src-tauri/**"],
+    },
+  },
+}));

apps/hub/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodeagent/hub",
-  "version": "1.4.2",
+  "version": "2.0.0",
   "private": true,
   "type": "module",
   "main": "./dist/index.js",

apps/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodeagent/mcp",
-  "version": "1.4.2",
+  "version": "2.0.0",
   "private": true,
   "type": "module",
   "main": "./dist/index.js",

apps/mcp/src/index.ts

@@ -96,522 +96,9 @@ async function call(capability: string, args: Record<string, unknown>): Promise<
 }
 
 // ---------- 工具定义 ----------
+// 具体清单见 tools/defs.ts（自 index.ts 抽出，顺序即对外呈现顺序）
+import { TOOLS } from './tools/defs.js';
 
-const TOOLS = [
-  {
-    name: 'na_status',
-    description:
-      '查询被控端 Windows 的资源状态：CPU 占用率、内存使用、各磁盘容量、网络适配器。当用户问"Windows 卡不卡""内存够不够""磁盘满了吗"时使用。',
-    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
-  },
-  {
-    name: 'na_system_info',
-    description:
-      '查询被控端 Windows 的系统基本信息：主机名、操作系统版本、CPU 型号、内存总量、开机时长、是否管理员。',
-    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
-  },
-  {
-    name: 'na_exec',
-    description:
-      '在被控端 Windows 上执行 PowerShell 命令并返回退出码与输出。用于查日志、查目录、重启服务、运行脚本等任意命令场景。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        command: { type: 'string', description: '要执行的 PowerShell 命令' },
-        timeout_ms: { type: 'integer', description: '超时毫秒数，默认 30000，最大 300000' },
-      },
-      required: ['command'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_install',
-    description:
-      '在被控端 Windows 上安装软件（winget 静默安装）。当用户说"在 Windows 上装个 XX""帮我装 VSCode"时使用。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        package: { type: 'string', description: '软件名或 winget 包 ID，如 Microsoft.VisualStudioCode' },
-        id: { type: 'string', description: '精确 winget ID（可选，优先使用）' },
-      },
-      required: ['package'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_app_list',
-    description: '列出被控端 Windows 上已安装的软件及其版本。',
-    inputSchema: {
-      type: 'object',
-      properties: { name_pattern: { type: 'string', description: '可选：按名称筛选（不区分大小写）' } },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_process_list',
-    description: '列出被控端 Windows 上运行的进程，可按 CPU 或内存排序。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        sort_by: { type: 'string', enum: ['cpu', 'memory', 'pid', 'name'], description: '排序字段，默认 cpu' },
-        limit: { type: 'integer', description: '返回条数，默认 20' },
-        name_pattern: { type: 'string', description: '可选：按进程名筛选' },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_service_list',
-    description: '列出被控端 Windows 的系统服务及其运行状态。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        name_pattern: { type: 'string', description: '可选：按服务名筛选' },
-        state: { type: 'string', enum: ['running', 'stopped', 'paused'], description: '可选：按状态筛选' },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_screenshot',
-    description:
-      '截取被控端 Windows 屏幕并直接返回图片。当用户问"Windows 现在画面是什么样""帮我看下屏幕"，或需要视觉确认操作结果时使用。屏幕较大时建议 scale 设 0.5 以减小体积。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        scale: { type: 'number', description: '缩放比例 0.1~1.0，默认 1' },
-        format: { type: 'string', enum: ['png', 'jpeg'], description: '默认 jpeg' },
-        region: { type: 'string', description: '可选截取区域，格式 "x,y,width,height"' },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_mouse',
-    description:
-      '控制被控端鼠标（需被控端已开启输入控制）。action: move 移动到 (x,y)；click 点击（给了 x/y 则先移动，否则点当前位置）；scroll 滚动 delta 格。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        action: { type: 'string', enum: ['move', 'click', 'scroll'], description: '操作类型' },
-        x: { type: 'integer', description: 'X 坐标' },
-        y: { type: 'integer', description: 'Y 坐标' },
-        button: { type: 'string', enum: ['left', 'right', 'middle'], description: 'click 的按钮，默认 left' },
-        delta: { type: 'integer', description: 'scroll 的滚动格数（正数向上）' },
-        duration_ms: { type: 'integer', description: 'move 的平滑移动耗时（毫秒）' },
-      },
-      required: ['action'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_key',
-    description:
-      '控制被控端键盘（需被控端已开启输入控制）。action: type 输入一段文本；press 按下组合键（如 ["ctrl","c"]）。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        action: { type: 'string', enum: ['type', 'press'], description: '操作类型' },
-        text: { type: 'string', description: 'type 时输入的文本' },
-        keys: { type: 'array', items: { type: 'string' }, description: 'press 时的按键列表' },
-      },
-      required: ['action'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_audit',
-    description:
-      '查询被控端审计日志：谁在何时调用了什么能力、结果如何。用于安全审计与问题追溯，例如"最近谁在操作这台 Windows"。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        limit: { type: 'integer', description: '返回条数，默认 20' },
-        since: { type: 'integer', description: '仅返回该 Unix 毫秒时间戳之后的记录' },
-        client_id: { type: 'string', description: '按调用方筛选' },
-        type: { type: 'string', enum: ['invoke', 'auth', 'acl', 'agent'], description: '按事件类别筛选' },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_discover',
-    description:
-      '发现局域网内可用的 nodeagent 被控端设备（监听 UDP 广播）。当用户问"有哪些 Windows 机器可用"、或尚未配置被控端时使用。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        wait_seconds: { type: 'number', description: '监听时长（秒），默认 3，上限 15' },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_fs_list',
-    description: '列出被控端某目录下的文件与子目录。用户问"Windows 上某目录有什么文件"时使用。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        path: { type: 'string', description: '目录绝对路径，如 C:\\\\Users\\\\me\\\\Desktop' },
-        pattern: { type: 'string', description: '可选 glob 过滤，如 "*.log"' },
-        recursive: { type: 'boolean', description: '是否递归子目录' },
-      },
-      required: ['path'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_fs_read',
-    description:
-      '读取被控端文件内容（默认 UTF-8）。文件较大时会分块返回，用 offset 续读、看 eof 判断结束。适合读取日志、配置、脚本。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        path: { type: 'string', description: '文件绝对路径' },
-        encoding: { type: 'string', enum: ['utf8', 'base64'], description: '默认 utf8；二进制文件用 base64' },
-        offset: { type: 'integer', description: '起始字节偏移，默认 0' },
-        max_bytes: { type: 'integer', description: '单次读取上限，默认 1MB，最大 8MB' },
-      },
-      required: ['path'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_fs_write',
-    description:
-      '向被控端写入文件（自动原子写，不会留半截文件）。已有文件可用 append: true 追加；目录不存在时设 create_dirs: true。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        path: { type: 'string', description: '文件绝对路径' },
-        data: { type: 'string', description: '写入内容' },
-        encoding: { type: 'string', enum: ['utf8', 'base64'], description: '默认 utf8' },
-        append: { type: 'boolean', description: '是否追加（默认覆盖）' },
-        create_dirs: { type: 'boolean', description: '目录不存在时自动创建' },
-      },
-      required: ['path', 'data'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_fs_stat',
-    description: '查看被控端文件或目录的元信息（类型 / 大小 / 修改时间），用于读文件前先判断类型与大小。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        path: { type: 'string', description: '文件或目录绝对路径' },
-      },
-      required: ['path'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_nodes',
-    description: '列出已配置的 nodeagent 被控端设备（● 为当前默认设备）。多台 Windows 时使用。',
-    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
-  },
-  {
-    name: 'na_restart',
-    description:
-      '受控重启被控端（约 4 秒后生效，自动恢复原配置与端口）。配置变更后让 agent 自身生效时使用；' +
-      '重启期间连接会短暂中断，等待约 5 秒后即可继续调用其他工具。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        delay_ms: { type: 'integer', description: '延时毫秒（默认 2000）' },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_window_list',
-    description:
-      '列出被控端当前可见的顶层窗口（标题 / 进程 / 精确矩形 / 是否前台）。' +
-      'GUI 操作第一步：先拿到窗口矩形，再在其范围内定位，避免全屏猜坐标。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        title_pattern: { type: 'string', description: '可选：按标题正则过滤' },
-        limit: { type: 'integer', description: '返回上限（默认 50）' },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_window_focus',
-    description: '将被控端的指定窗口（按标题正则）置前并聚焦，返回其精确矩形。点击某窗口内容之前先调用。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        title: { type: 'string', description: '窗口标题（正则，匹配第一个）' },
-        wait_ms: { type: 'integer', description: '等待窗口出现（应用刚启动时用）' },
-      },
-      required: ['title'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_screen_find',
-    description:
-      '在被控端界面中查找 UI 元素并返回其屏幕坐标（Windows UI Automation）。' +
-      '返回中心点 (x,y)，可直接配合 na_mouse 的 click 使用。找不到时自动降级为 OCR 截图识别（支持自绘 UI）。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        text: { type: 'string', description: '要查找的文本（子串匹配，不区分大小写）' },
-        window: { type: 'string', description: '可选：限定在该窗口标题（正则）内查找' },
-        control_type: {
-          type: 'string',
-          description: '可选：控件类型，如 Button / MenuItem / Edit / ListItem（仅 UIA）',
-        },
-        method: {
-          type: 'string',
-          enum: ['auto', 'uia', 'ocr'],
-          description: 'auto=UIA 优先+OCR 兜底；uia=仅 UIA；ocr=仅截图识别',
-        },
-        limit: { type: 'integer', description: '返回上限（默认 20）' },
-        wait_ms: {
-          type: 'integer',
-          description: '等待元素出现的上限毫秒（0=只查一次）。界面有动画/加载时建议 3000~8000',
-        },
-      },
-      required: ['text'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_bg',
-    description:
-      '在被控端后台执行长命令（如下载、安装、日志采样），立即返回 task_id 不阻塞。' +
-      '之后用 na_task 查询输出或终止。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        command: { type: 'string', description: '要执行的 PowerShell 命令' },
-        timeout_ms: { type: 'integer', description: '超时毫秒（默认 300000，即 5 分钟）' },
-      },
-      required: ['command'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_task',
-    description:
-      '管理后台任务：action=list 列出；action=get 读取输出（offset 支持增量续读）；action=kill 终止。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        action: { type: 'string', enum: ['list', 'get', 'kill'], description: '默认 list' },
-        task_id: { type: 'string', description: 'get/kill 时必填' },
-        offset: { type: 'integer', description: 'get 时从第 N 字节续读（默认 0）' },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_macro_run',
-    description:
-      '回放一段 GUI 宏（步骤序列）：把一次成功操作固化后重复执行。' +
-      '步骤支持 focus/find/click/type/key/drag/sleep/exec/clip/assert/capture，' +
-      '可带 retry 重试、optional 可选、${VAR} 变量替换。返回每步结果（含失败定位）。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        steps: {
-          type: 'array',
-          description: '步骤数组',
-          items: { type: 'object', additionalProperties: true },
-        },
-        vars: { type: 'object', description: '可选：变量表（供 ${NAME} 替换）' },
-        default_delay_ms: { type: 'integer', description: '每步之间默认等待' },
-      },
-      required: ['steps'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_net_status',
-    description:
-      '查看被控端网络现状：各网卡 IP/网关、**待确认的网络变更**（含剩余秒数）、历史配置备份。' +
-      '改网络前后都应先看它。',
-    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
-  },
-  {
-    name: 'na_net_apply',
-    description:
-      '**改被控端网络**（高危）：两阶段提交 —— 先备份当前配置，再应用变更，并注册 OS 级定时回滚任务；' +
-      '你必须在 confirm_within_ms 内（可能要在新地址上重连后）用 na_net_confirm 确认，' +
-      '否则自动回滚到变更前配置。用于远程改 IP / 切 DHCP 这类「改错就失联」的操作。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        mode: { type: 'string', enum: ['static', 'dhcp', 'command'] },
-        interface: { type: 'string', description: '网卡别名；省略则用带默认网关的那块' },
-        ip: { type: 'string' },
-        mask: { type: 'string' },
-        gateway: { type: 'string' },
-        dns: { type: 'array', items: { type: 'string' } },
-        command: { type: 'string', description: 'mode=command 时执行的自定义变更命令' },
-        confirm_within_ms: { type: 'integer', description: '确认窗口毫秒（默认 60000，最小 15000）' },
-      },
-      required: ['mode'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_net_confirm',
-    description: '确认（提交）网络变更，取消自动回滚。不传 task_name 则取消全部待确认项。',
-    inputSchema: {
-      type: 'object',
-      properties: { task_name: { type: 'string' } },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_agent_update',
-    description:
-      '**被控端自更新**：让它自己从 URL 下载新版本 agent 并替换自身（校验哈希 → 备份 → 原子替换 → 重启）。' +
-      '用于控制端与被控端不可达、但被控端能上网的场景（跨网段/NAT/异地）。' +
-      'sha256 必填（安全底线）；不确定时可先 dry_run=true 只校验不改动。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        url: { type: 'string', description: '更新包地址（http/https）' },
-        sha256: { type: 'string', description: '期望哈希（12~64 位十六进制）' },
-        restart: { type: 'boolean', description: '替换后是否重启（默认 true）' },
-        dry_run: { type: 'boolean', description: '只下载校验，不改动文件' },
-      },
-      required: ['url', 'sha256'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_audio_get',
-    description: '读取被控端默认播放设备的静音状态与主音量（Windows: Core Audio / macOS: osascript）。',
-    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
-  },
-  {
-    name: 'na_audio_set',
-    description:
-      '设置被控端静音开关或主音量（可读回实际状态，故为确定性设置而非切换）。' +
-      '常用于「把远端那台机器静音」。mute 与 volume 至少给一个。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        mute: { type: 'boolean', description: 'true=静音，false=取消静音' },
-        volume: { type: 'integer', description: '主音量 0-100' },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_metrics',
-    description:
-      '按 PRD 2.2 汇总被控端成功指标（闭环成功率 / 装软件成功率 / P95 时延 / 安全拦截率）' +
-      '及达标判定与按能力细分。排查「成功率掉了没有／哪个能力最慢」时用。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        since: { type: 'integer', description: '可选：只统计该 Unix 毫秒之后的审计条目' },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_event_watch',
-    description:
-      '订阅被控端事件：file=文件变动、process=进程启停、net=监听端口开闭。' +
-      'MCP 无法接收推送，事件会进入服务端缓冲，用 na_event_poll 拉取。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        kind: { type: 'string', enum: ['file', 'process', 'net'] },
-        path: { type: 'string', description: 'file 类型：监控的目录/文件路径' },
-        pattern: { type: 'string', description: '可选：文件名或进程名 glob（如 *.log、chrome*）' },
-        recursive: { type: 'boolean', description: 'file 类型：是否递归子目录' },
-        interval_ms: { type: 'integer', description: 'process/net 采样间隔（1000~60000，默认 5000）' },
-        notify: {
-          type: 'boolean',
-          description:
-            '开启实时推送（MCP 日志通知）；宿主若不展示日志则退化为 na_event_poll 拉取，无副作用',
-        },
-      },
-      required: ['kind'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_event_poll',
-    description:
-      '拉取已缓冲的被控端事件（增量：传上次返回的 next_cursor）。' +
-      '典型用法：先 na_event_watch 订阅，稍后 na_event_poll 查看期间发生了什么。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        limit: { type: 'integer', description: '最多返回条数（默认 50）' },
-        since: { type: 'integer', description: '游标：上次返回的 next_cursor' },
-        watch_id: { type: 'string', description: '可选：只看某个订阅' },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_event_list',
-    description: '列出当前生效的事件订阅（含各自已产生的事件数）与缓冲区大小。',
-    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
-  },
-  {
-    name: 'na_event_unwatch',
-    description: '取消一个事件订阅（长时间不用的订阅应主动取消，避免浪费被控端资源）。',
-    inputSchema: {
-      type: 'object',
-      properties: { watch_id: { type: 'string' } },
-      required: ['watch_id'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_record',
-    description:
-      '录制被控端屏幕为帧序列（JPEG），检测到 ffmpeg 时额外封装 mp4。' +
-      '用于复现间歇性问题或记录 GUI 操作；产物在被控端目录，用 na_fs_read 取回。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        duration_ms: { type: 'integer', description: '时长毫秒（1000~60000，默认 5000）' },
-        fps: { type: 'integer', description: '帧率 1~10（默认 2）' },
-        scale: { type: 'number', description: '全屏缩放 0.1~1（默认 0.5）' },
-        region: { type: 'string', description: '可选 "x,y,width,height" 只录该区域' },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_clip',
-    description:
-      '读写被控端剪贴板：action=get 读取文本；action=set 写入文本。要粘贴到 GUI 输入框时先 set 再用 na_key 按 ctrl+v。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        action: { type: 'string', enum: ['get', 'set'], description: '默认 get' },
-        text: { type: 'string', description: 'set 时要写入的文本' },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'na_use',
-    description: '切换本次会话的目标设备（不影响 CLI 的默认设备）。用户说"切换到某台机器"时使用。',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        name: { type: 'string', description: '设备名（用 na_nodes 查看）' },
-      },
-      required: ['name'],
-      additionalProperties: false,
-    },
-  },
-] as const;
 
 /** MCP 工具入参 → 能力 args。 */
 function toArgs(toolName: string, input: Record<string, unknown>): Record<string, unknown> {
@@ -733,6 +220,41 @@ function resolveToolCall(toolName: string, input: Record<string, unknown>): Reso
       }
       return { error: `不支持的 action: ${String(action)}` };
     }
+    case 'na_monitor': {
+      const action = (input['action'] as string | undefined) ?? 'list';
+      if (action === 'start') {
+        if (!input['source']) return { error: 'start 需要 source' };
+        const a: Record<string, unknown> = { source: input['source'] };
+        for (const k of ['target', 'interval_ms', 'id']) if (input[k] !== undefined) a[k] = input[k];
+        return { capability: CapabilityNames.MonitorStart, args: a };
+      }
+      if (action === 'report') {
+        if (!input['id']) return { error: 'report 需要 id' };
+        const a: Record<string, unknown> = { id: input['id'] };
+        if (input['limit'] !== undefined) a['limit'] = input['limit'];
+        return { capability: CapabilityNames.MonitorReport, args: a };
+      }
+      if (action === 'stop' || action === 'delete') {
+        if (!input['id']) return { error: `${action} 需要 id` };
+        return { capability: action === 'stop' ? CapabilityNames.MonitorStop : CapabilityNames.MonitorDelete, args: { id: input['id'] } };
+      }
+      if (action === 'list') return { capability: CapabilityNames.MonitorList, args: {} };
+      return { error: `不支持的 action: ${String(action)}` };
+    }
+    case 'na_log': {
+      if (!input['path']) return { error: 'na_log 需要 path' };
+      const a: Record<string, unknown> = { path: input['path'] };
+      for (const k of ['pattern', 'level', 'since', 'offset', 'limit', 'tail']) if (input[k] !== undefined) a[k] = input[k];
+      return { capability: CapabilityNames.LogQuery, args: a };
+    }
+    case 'na_await': {
+      const args: Record<string, unknown> = {};
+      for (const k of ['condition', 'state', 'timeout_ms', 'interval_ms', 'text', 'title', 'process', 'path', 'where', 'any_of']) {
+        if (input[k] !== undefined) args[k] = input[k];
+      }
+      if (!args['condition']) return { error: 'await 需要 condition' };
+      return { capability: CapabilityNames.GuiAwait, args };
+    }
     case 'na_key': {
       const action = input['action'];
       if (action === 'type') {
@@ -740,10 +262,18 @@ function resolveToolCall(toolName: string, input: Record<string, unknown>): Reso
         return { capability: CapabilityNames.KeyType, args: { text: input['text'] } };
       }
       if (action === 'press') {
-        if (!Array.isArray(input['keys']) || input['keys'].length === 0) {
-          return { error: 'press 需要非空 keys 数组' };
+        // v1.5：四种形式一次只用一种（hotkeys > hotkey > presets > preset > keys），
+        // 其余各端会做同样的校验与展开，这里只做薄校验后原样透传。
+        const has = (k: string): boolean =>
+          input[k] !== undefined && !(Array.isArray(input[k]) && (input[k] as unknown[]).length === 0);
+        const forms = ['hotkeys', 'hotkey', 'presets', 'preset', 'keys'].filter(has);
+        if (forms.length === 0) return { error: 'press 需要 hotkey / hotkeys / preset / presets / keys 之一' };
+        if (forms.length > 1) return { error: `参数混用：${forms.join(' + ')}，一次请只用一种形式` };
+        const args: Record<string, unknown> = { [forms[0]!]: input[forms[0]!] };
+        for (const k of ['repeat', 'hold_ms', 'route', 'target_pid', 'interval_ms']) {
+          if (input[k] !== undefined) args[k] = input[k];
         }
-        return { capability: CapabilityNames.KeyPress, args: { keys: input['keys'] } };
+        return { capability: CapabilityNames.KeyPress, args };
       }
       return { error: `不支持的 action: ${String(action)}` };
     }

apps/mcp/src/tools/defs.ts

@@ -0,0 +1,618 @@
+/**
+ * MCP 工具定义清单（2026-10 从 index.ts 抽出）。
+ *
+ * ⚠️ **顺序即对外呈现顺序**：改动会改变客户端看到的工具列表次序。
+ * 拆分时用「工具名序列 sha256」做回归证据（见 tests/unit/mcp-tools.test.mjs）。
+ *
+ * 定义与实现的分工：本文件只管「暴露什么」，分发逻辑仍在 index.ts 的 resolveToolCall。
+ */
+export const TOOLS = [
+  {
+    name: 'na_status',
+    description:
+      '查询被控端 Windows 的资源状态：CPU 占用率、内存使用、各磁盘容量、网络适配器。当用户问"Windows 卡不卡""内存够不够""磁盘满了吗"时使用。',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'na_system_info',
+    description:
+      '查询被控端 Windows 的系统基本信息：主机名、操作系统版本、CPU 型号、内存总量、开机时长、是否管理员。',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'na_exec',
+    description:
+      '在被控端 Windows 上执行 PowerShell 命令并返回退出码与输出。用于查日志、查目录、重启服务、运行脚本等任意命令场景。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        command: { type: 'string', description: '要执行的 PowerShell 命令' },
+        timeout_ms: { type: 'integer', description: '超时毫秒数，默认 30000，最大 300000' },
+      },
+      required: ['command'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_install',
+    description:
+      '在被控端 Windows 上安装软件（winget 静默安装）。当用户说"在 Windows 上装个 XX""帮我装 VSCode"时使用。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        package: { type: 'string', description: '软件名或 winget 包 ID，如 Microsoft.VisualStudioCode' },
+        id: { type: 'string', description: '精确 winget ID（可选，优先使用）' },
+      },
+      required: ['package'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_app_list',
+    description: '列出被控端 Windows 上已安装的软件及其版本。',
+    inputSchema: {
+      type: 'object',
+      properties: { name_pattern: { type: 'string', description: '可选：按名称筛选（不区分大小写）' } },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_process_list',
+    description: '列出被控端 Windows 上运行的进程，可按 CPU 或内存排序。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sort_by: { type: 'string', enum: ['cpu', 'memory', 'pid', 'name'], description: '排序字段，默认 cpu' },
+        limit: { type: 'integer', description: '返回条数，默认 20' },
+        name_pattern: { type: 'string', description: '可选：按进程名筛选' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_service_list',
+    description: '列出被控端 Windows 的系统服务及其运行状态。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name_pattern: { type: 'string', description: '可选：按服务名筛选' },
+        state: { type: 'string', enum: ['running', 'stopped', 'paused'], description: '可选：按状态筛选' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_screenshot',
+    description:
+      '截取被控端 Windows 屏幕并直接返回图片。当用户问"Windows 现在画面是什么样""帮我看下屏幕"，或需要视觉确认操作结果时使用。屏幕较大时建议 scale 设 0.5 以减小体积。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        scale: { type: 'number', description: '缩放比例 0.1~1.0，默认 1' },
+        format: { type: 'string', enum: ['png', 'jpeg'], description: '默认 jpeg' },
+        region: { type: 'string', description: '可选截取区域，格式 "x,y,width,height"' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_mouse',
+    description:
+      '控制被控端鼠标（需被控端已开启输入控制）。action: move 移动到 (x,y)；click 点击（给了 x/y 则先移动，否则点当前位置）；scroll 滚动 delta 格。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['move', 'click', 'scroll'], description: '操作类型' },
+        x: { type: 'integer', description: 'X 坐标' },
+        y: { type: 'integer', description: 'Y 坐标' },
+        button: { type: 'string', enum: ['left', 'right', 'middle'], description: 'click 的按钮，默认 left' },
+        delta: { type: 'integer', description: 'scroll 的滚动格数（正数向上）' },
+        duration_ms: { type: 'integer', description: 'move 的平滑移动耗时（毫秒）' },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_key',
+    description:
+      '控制被控端键盘（需被控端已开启输入控制）。\n' +
+      'action: type = 输入一段文本；press = 按**快捷键**。\n' +
+      'press 支持四种形式（一次只用一种）：\n' +
+      '① hotkey 单条字符串，如 "ctrl+shift+esc"、"win+d"、"alt+tab"；\n' +
+      '② hotkeys 字符串序列，如 ["ctrl+c","ctrl+v"]；\n' +
+      '③ preset 预设语义名，如 copy/paste/save/show_desktop/lock_screen/screenshot/' +
+      'zoom_in/music_next/volume_mute_toggle（约 50 个）；\n' +
+      '④ keys 老形式数组，如 ["ctrl","c"]。\n' +
+      '按键覆盖：字母数字、F1-F24、左右侧修饰键（lalt/rctrl/lwin…）、小键盘（numpad7、numpad_add…）、' +
+      'OEM 符号键（oem_plus/oem_comma/oem_period…，支持 win+d、ctrl++、win+. 这类组合）、' +
+      '媒体键（media_next/music_play_pause…）、浏览器键、IME 键、系统键。\n' +
+      '可配：hold_ms 长按（≤5000）；route=foreground（默认，注入当前焦点）或 ' +
+      'route=post（向 target_pid 指定进程的全部顶层窗口 PostMessage，目标在后台时可用，' +
+      '但游戏/部分输入型程序不响应后台键消息）。\n' +
+      '媒体键整条序列会自动走 WM_APPCOMMAND（可定向 target_pid，窗口被遮挡也有效）。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['type', 'press'], description: '操作类型' },
+        text: { type: 'string', description: 'type 时输入的文本' },
+        hotkey: { type: 'string', maxLength: 64, description: '单条热键字符串，如 "ctrl+shift+esc"；支持 + - 空格分隔' },
+        hotkeys: { type: 'array', items: { type: 'string' }, maxItems: 50, description: '热键字符串序列，如 ["ctrl+c","ctrl+v"]' },
+        preset: { type: 'string', description: '预设语义名（单个），如 copy / show_desktop / task_manager' },
+        presets: { type: 'array', items: { type: 'string' }, maxItems: 50, description: '多个预设名 = 序列' },
+        keys: { type: 'array', items: { type: 'string' }, description: '（老形式）和弦按键数组，如 ["ctrl","c"]' },
+        repeat: { type: 'integer', minimum: 1, maximum: 50, description: '重复次数（默认 1）' },
+        hold_ms: { type: 'integer', minimum: 0, maximum: 5000, description: '长按保持毫秒数（按下后延时再释放）' },
+        route: { type: 'string', enum: ['foreground', 'post'], description: '投递路由，默认 foreground' },
+        target_pid: { type: 'integer', minimum: 0, description: '目标进程 PID（媒体键定向或 route=post 必填）' },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_audit',
+    description:
+      '查询被控端审计日志：谁在何时调用了什么能力、结果如何。用于安全审计与问题追溯，例如"最近谁在操作这台 Windows"。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: { type: 'integer', description: '返回条数，默认 20' },
+        since: { type: 'integer', description: '仅返回该 Unix 毫秒时间戳之后的记录' },
+        client_id: { type: 'string', description: '按调用方筛选' },
+        type: { type: 'string', enum: ['invoke', 'auth', 'acl', 'agent'], description: '按事件类别筛选' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_discover',
+    description:
+      '发现局域网内可用的 nodeagent 被控端设备（监听 UDP 广播）。当用户问"有哪些 Windows 机器可用"、或尚未配置被控端时使用。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        wait_seconds: { type: 'number', description: '监听时长（秒），默认 3，上限 15' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_fs_list',
+    description: '列出被控端某目录下的文件与子目录。用户问"Windows 上某目录有什么文件"时使用。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: '目录绝对路径，如 C:\\\\Users\\\\me\\\\Desktop' },
+        pattern: { type: 'string', description: '可选 glob 过滤，如 "*.log"' },
+        recursive: { type: 'boolean', description: '是否递归子目录' },
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_fs_read',
+    description:
+      '读取被控端文件内容（默认 UTF-8）。文件较大时会分块返回，用 offset 续读、看 eof 判断结束。适合读取日志、配置、脚本。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: '文件绝对路径' },
+        encoding: { type: 'string', enum: ['utf8', 'base64'], description: '默认 utf8；二进制文件用 base64' },
+        offset: { type: 'integer', description: '起始字节偏移，默认 0' },
+        max_bytes: { type: 'integer', description: '单次读取上限，默认 1MB，最大 8MB' },
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_fs_write',
+    description:
+      '向被控端写入文件（自动原子写，不会留半截文件）。已有文件可用 append: true 追加；目录不存在时设 create_dirs: true。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: '文件绝对路径' },
+        data: { type: 'string', description: '写入内容' },
+        encoding: { type: 'string', enum: ['utf8', 'base64'], description: '默认 utf8' },
+        append: { type: 'boolean', description: '是否追加（默认覆盖）' },
+        create_dirs: { type: 'boolean', description: '目录不存在时自动创建' },
+      },
+      required: ['path', 'data'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_fs_stat',
+    description: '查看被控端文件或目录的元信息（类型 / 大小 / 修改时间），用于读文件前先判断类型与大小。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: '文件或目录绝对路径' },
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_nodes',
+    description: '列出已配置的 nodeagent 被控端设备（● 为当前默认设备）。多台 Windows 时使用。',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'na_restart',
+    description:
+      '受控重启被控端（约 4 秒后生效，自动恢复原配置与端口）。配置变更后让 agent 自身生效时使用；' +
+      '重启期间连接会短暂中断，等待约 5 秒后即可继续调用其他工具。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        delay_ms: { type: 'integer', description: '延时毫秒（默认 2000）' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_await',
+    description:
+      '等待一个条件成立再返回（只读低危，v1.6）。\n' +
+      '四类条件：window=等窗口出现/消失；control=等界面元素出现/消失（复用 screen.find）；' +
+      'process=等进程出现/消失；file=等文件出现/消失。\n' +
+      'state=present（默认，等出现）或 absent（等消失）。\n' +
+      '用途：把 GUI 操作从「按一下→睡几秒→截图碰运气」变成**可断言**流程：\n' +
+      '  await control(text:"立即安装") → na_mouse click → await control(text:"完成", timeout:60000) → click → await absent(text:"安装中")\n' +
+      '超时是**正常返回**（satisfied:false + note，不抛异常）；轮询期单次异常不视为失败。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        condition: { type: 'string', enum: ['window', 'control', 'process', 'file'], description: '等待哪类条件' },
+        state: { type: 'string', enum: ['present', 'absent'], default: 'present', description: '等出现还是等消失' },
+        timeout_ms: { type: 'integer', minimum: 0, maximum: 60000, default: 5000, description: '总超时' },
+        interval_ms: { type: 'integer', minimum: 50, maximum: 5000, default: 400, description: '轮询间隔' },
+        text: { type: 'string', description: 'control 条件：元素文本' },
+        title: { type: 'string', description: 'window 条件：窗口标题（正则）' },
+        process: { type: 'string', description: 'process 条件：进程名（正则）' },
+        path: { type: 'string', description: 'file 条件：文件路径' },
+        where: { type: 'object', description: 'v1.7 属性谓词（仅 UIA）：{ enabled?, selected?, value?, toggle? }' },
+        any_of: { type: 'array', maxItems: 8, description: 'v1.7 组合条件：每项一个条件对象，任一命中即算' },
+      },
+      required: ['condition'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_monitor',
+    description:
+      '定时采样并落盘，事后回看（v1.8，治间歇性问题）。\n' +
+      'action=start：起一个采样。source=port（target="host:port"，测连通性与延迟）/' +
+      'process（target=进程名，测存活）/command（target=命令，取退出码）/metric（CPU·内存，无需 target）。\n' +
+      'action=report：读回样本序列与**摘要**（port/process 给「断了几次 + 最长连续中断」；' +
+      'metric 给 CPU/内存 min·avg·max；command 给成功失败数与退出码）。\n' +
+      'action=stop/list/delete。\n' +
+      '典型：先 start port 采 5 分钟，再 report 回答「这 5 分钟断过几次、最长断了多久」。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['start', 'report', 'stop', 'list', 'delete'], description: '操作' },
+        source: { type: 'string', enum: ['port', 'process', 'command', 'metric'], description: 'start 时的采样源' },
+        target: { type: 'string', description: 'port=host:port；process=进程名；command=命令' },
+        interval_ms: { type: 'integer', minimum: 500, maximum: 600000, description: '采样间隔（默认 2000）' },
+        id: { type: 'string', description: '监控 id（report/stop/delete 必需；start 可自定义）' },
+        limit: { type: 'integer', description: 'report 最多回多少样本' },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_log',
+    description:
+      '在被控端侧过滤日志，只回匹配行（v1.8，只读）。日志常几万行，整份拉回既慢又占带宽 —— ' +
+      '本工具把过滤下推到被控端（流式逐行读）。支持 pattern（正则）/level（ERROR|WARN|INFO|DEBUG）/\n' +
+      'since（Unix ms）/offset/limit/tail（取末尾 N 条）。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: '日志文件路径（受被控端 fs_roots 限制）' },
+        pattern: { type: 'string', description: '正则过滤（忽略大小写）' },
+        level: { type: 'string', enum: ['ERROR', 'WARN', 'INFO', 'DEBUG', 'TRACE'], description: '按级别过滤' },
+        since: { type: 'integer', description: '只回该 Unix ms 之后的行' },
+        offset: { type: 'integer', description: '跳过前 N 条命中' },
+        limit: { type: 'integer', description: '最多回多少条（默认 100，上限 5000）' },
+        tail: { type: 'boolean', description: '取末尾 N 条' },
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_window_list',
+    description:
+      '列出被控端当前可见的顶层窗口（标题 / 进程 / 精确矩形 / 是否前台）。' +
+      'GUI 操作第一步：先拿到窗口矩形，再在其范围内定位，避免全屏猜坐标。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title_pattern: { type: 'string', description: '可选：按标题正则过滤' },
+        limit: { type: 'integer', description: '返回上限（默认 50）' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_window_focus',
+    description: '将被控端的指定窗口（按标题正则）置前并聚焦，返回其精确矩形。点击某窗口内容之前先调用。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string', description: '窗口标题（正则，匹配第一个）' },
+        wait_ms: { type: 'integer', description: '等待窗口出现（应用刚启动时用）' },
+      },
+      required: ['title'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_screen_find',
+    description:
+      '在被控端界面中查找 UI 元素并返回其屏幕坐标（Windows UI Automation）。' +
+      '返回中心点 (x,y)，可直接配合 na_mouse 的 click 使用。找不到时自动降级为 OCR 截图识别（支持自绘 UI）。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: '要查找的文本（子串匹配，不区分大小写）' },
+        window: { type: 'string', description: '可选：限定在该窗口标题（正则）内查找' },
+        control_type: {
+          type: 'string',
+          description: '可选：控件类型，如 Button / MenuItem / Edit / ListItem（仅 UIA）',
+        },
+        method: {
+          type: 'string',
+          enum: ['auto', 'uia', 'ocr'],
+          description: 'auto=UIA 优先+OCR 兜底；uia=仅 UIA；ocr=仅截图识别',
+        },
+        limit: { type: 'integer', description: '返回上限（默认 20）' },
+        wait_ms: {
+          type: 'integer',
+          description: '等待元素出现的上限毫秒（0=只查一次）。界面有动画/加载时建议 3000~8000',
+        },
+      },
+      required: ['text'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_bg',
+    description:
+      '在被控端后台执行长命令（如下载、安装、日志采样），立即返回 task_id 不阻塞。' +
+      '之后用 na_task 查询输出或终止。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        command: { type: 'string', description: '要执行的 PowerShell 命令' },
+        timeout_ms: { type: 'integer', description: '超时毫秒（默认 300000，即 5 分钟）' },
+      },
+      required: ['command'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_task',
+    description:
+      '管理后台任务：action=list 列出；action=get 读取输出（offset 支持增量续读）；action=kill 终止。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['list', 'get', 'kill'], description: '默认 list' },
+        task_id: { type: 'string', description: 'get/kill 时必填' },
+        offset: { type: 'integer', description: 'get 时从第 N 字节续读（默认 0）' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_macro_run',
+    description:
+      '回放一段 GUI 宏（步骤序列）：把一次成功操作固化后重复执行。' +
+      '步骤支持 focus/find/click/type/key/drag/sleep/exec/clip/assert/capture，' +
+      '可带 retry 重试、optional 可选、${VAR} 变量替换。返回每步结果（含失败定位）。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        steps: {
+          type: 'array',
+          description: '步骤数组',
+          items: { type: 'object', additionalProperties: true },
+        },
+        vars: { type: 'object', description: '可选：变量表（供 ${NAME} 替换）' },
+        default_delay_ms: { type: 'integer', description: '每步之间默认等待' },
+      },
+      required: ['steps'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_net_status',
+    description:
+      '查看被控端网络现状：各网卡 IP/网关、**待确认的网络变更**（含剩余秒数）、历史配置备份。' +
+      '改网络前后都应先看它。',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'na_net_apply',
+    description:
+      '**改被控端网络**（高危）：两阶段提交 —— 先备份当前配置，再应用变更，并注册 OS 级定时回滚任务；' +
+      '你必须在 confirm_within_ms 内（可能要在新地址上重连后）用 na_net_confirm 确认，' +
+      '否则自动回滚到变更前配置。用于远程改 IP / 切 DHCP 这类「改错就失联」的操作。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        mode: { type: 'string', enum: ['static', 'dhcp', 'command'] },
+        interface: { type: 'string', description: '网卡别名；省略则用带默认网关的那块' },
+        ip: { type: 'string' },
+        mask: { type: 'string' },
+        gateway: { type: 'string' },
+        dns: { type: 'array', items: { type: 'string' } },
+        command: { type: 'string', description: 'mode=command 时执行的自定义变更命令' },
+        confirm_within_ms: { type: 'integer', description: '确认窗口毫秒（默认 60000，最小 15000）' },
+      },
+      required: ['mode'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_net_confirm',
+    description: '确认（提交）网络变更，取消自动回滚。不传 task_name 则取消全部待确认项。',
+    inputSchema: {
+      type: 'object',
+      properties: { task_name: { type: 'string' } },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_agent_update',
+    description:
+      '**被控端自更新**：让它自己从 URL 下载新版本 agent 并替换自身（校验哈希 → 备份 → 原子替换 → 重启）。' +
+      '用于控制端与被控端不可达、但被控端能上网的场景（跨网段/NAT/异地）。' +
+      'sha256 必填（安全底线）；不确定时可先 dry_run=true 只校验不改动。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: '更新包地址（http/https）' },
+        sha256: { type: 'string', description: '期望哈希（12~64 位十六进制）' },
+        restart: { type: 'boolean', description: '替换后是否重启（默认 true）' },
+        dry_run: { type: 'boolean', description: '只下载校验，不改动文件' },
+      },
+      required: ['url', 'sha256'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_audio_get',
+    description: '读取被控端默认播放设备的静音状态与主音量（Windows: Core Audio / macOS: osascript）。',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'na_audio_set',
+    description:
+      '设置被控端静音开关或主音量（可读回实际状态，故为确定性设置而非切换）。' +
+      '常用于「把远端那台机器静音」。mute 与 volume 至少给一个。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        mute: { type: 'boolean', description: 'true=静音，false=取消静音' },
+        volume: { type: 'integer', description: '主音量 0-100' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_metrics',
+    description:
+      '按 PRD 2.2 汇总被控端成功指标（闭环成功率 / 装软件成功率 / P95 时延 / 安全拦截率）' +
+      '及达标判定与按能力细分。排查「成功率掉了没有／哪个能力最慢」时用。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        since: { type: 'integer', description: '可选：只统计该 Unix 毫秒之后的审计条目' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_event_watch',
+    description:
+      '订阅被控端事件：file=文件变动、process=进程启停、net=监听端口开闭。' +
+      'MCP 无法接收推送，事件会进入服务端缓冲，用 na_event_poll 拉取。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        kind: { type: 'string', enum: ['file', 'process', 'net'] },
+        path: { type: 'string', description: 'file 类型：监控的目录/文件路径' },
+        pattern: { type: 'string', description: '可选：文件名或进程名 glob（如 *.log、chrome*）' },
+        recursive: { type: 'boolean', description: 'file 类型：是否递归子目录' },
+        interval_ms: { type: 'integer', description: 'process/net 采样间隔（1000~60000，默认 5000）' },
+        notify: {
+          type: 'boolean',
+          description:
+            '开启实时推送（MCP 日志通知）；宿主若不展示日志则退化为 na_event_poll 拉取，无副作用',
+        },
+      },
+      required: ['kind'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_event_poll',
+    description:
+      '拉取已缓冲的被控端事件（增量：传上次返回的 next_cursor）。' +
+      '典型用法：先 na_event_watch 订阅，稍后 na_event_poll 查看期间发生了什么。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: { type: 'integer', description: '最多返回条数（默认 50）' },
+        since: { type: 'integer', description: '游标：上次返回的 next_cursor' },
+        watch_id: { type: 'string', description: '可选：只看某个订阅' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_event_list',
+    description: '列出当前生效的事件订阅（含各自已产生的事件数）与缓冲区大小。',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'na_event_unwatch',
+    description: '取消一个事件订阅（长时间不用的订阅应主动取消，避免浪费被控端资源）。',
+    inputSchema: {
+      type: 'object',
+      properties: { watch_id: { type: 'string' } },
+      required: ['watch_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_record',
+    description:
+      '录制被控端屏幕为帧序列（JPEG），检测到 ffmpeg 时额外封装 mp4。' +
+      '用于复现间歇性问题或记录 GUI 操作；产物在被控端目录，用 na_fs_read 取回。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        duration_ms: { type: 'integer', description: '时长毫秒（1000~60000，默认 5000）' },
+        fps: { type: 'integer', description: '帧率 1~10（默认 2）' },
+        scale: { type: 'number', description: '全屏缩放 0.1~1（默认 0.5）' },
+        region: { type: 'string', description: '可选 "x,y,width,height" 只录该区域' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_clip',
+    description:
+      '读写被控端剪贴板：action=get 读取文本；action=set 写入文本。要粘贴到 GUI 输入框时先 set 再用 na_key 按 ctrl+v。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['get', 'set'], description: '默认 get' },
+        text: { type: 'string', description: 'set 时要写入的文本' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'na_use',
+    description: '切换本次会话的目标设备（不影响 CLI 的默认设备）。用户说"切换到某台机器"时使用。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: '设备名（用 na_nodes 查看）' },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    },
+  },
+] as const;

crates/Cargo.toml

@@ -0,0 +1,5 @@
+[workspace]
+resolver = "2"
+members = ["nodeagent-client"]
+
+[workspace.dependencies]

crates/nodeagent-client/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "nodeagent-client"
+version = "0.1.0"
+edition = "2021"
+description = "nodeagent 控制端 Rust 客户端（行为对齐 @nodeagent/client）"
+license = "MIT"
+
+[dependencies]
+base64 = "0.23.1"
+ed25519-dalek = { version = "3.0.0", features = ["pkcs8", "alloc"] }
+futures-util = "0.3.34"
+hmac = "0.13.0"
+rand = "0.10.3"
+rustls = "0.23.45"
+rustls-pemfile = "2.2.0"
+serde = { version = "1.0.229", features = ["derive"] }
+serde_json = "1.0.151"
+sha2 = "0.11.0"
+thiserror = "2.0.21"
+tokio = { version = "1.53.2", features = ["rt-multi-thread", "net", "time", "sync", "macros", "io-util"] }
+tokio-tungstenite = { version = "0.30.0", features = ["rustls-tls-webpki-roots"] }
+url = "2.5.8"
+webpki-roots = "1.0.9"

crates/nodeagent-client/examples/connect.rs

@@ -0,0 +1,53 @@
+//! 连接一个真实 nodeagent 被控端的最小示例。
+//!
+//! 用法：`cargo run --example connect -- <url> <key> [client_id]`
+//! 例如：`cargo run --example connect -- ws://127.0.0.1:8765 test-psk-key`
+
+use nodeagent_client::{Client, ClientEvent, ClientOptions};
+use serde_json::json;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let args: Vec<String> = std::env::args().collect();
+    let url = args
+        .get(1)
+        .cloned()
+        .unwrap_or_else(|| "ws://127.0.0.1:8765".to_string());
+    let key = args.get(2).cloned().unwrap_or_default();
+    let client_id = args
+        .get(3)
+        .cloned()
+        .unwrap_or_else(|| "rust-example".to_string());
+
+    let client = Client::new(ClientOptions {
+        url: url.clone(),
+        key,
+        client_id,
+        insecure: true,
+        auto_reconnect: false,
+        ..Default::default()
+    });
+
+    client.set_handler(std::sync::Arc::new(|evt| {
+        if let ClientEvent::Log(msg) = evt {
+            println!("[log] {msg}");
+        }
+    }));
+
+    let caps = client.connect().await?;
+    println!("握手成功，{} 项能力", caps.len());
+    println!("agent 版本: {:?}", client.agent_version());
+    println!("证书指纹: {:?}", client.peer_cert_fingerprint());
+    for c in caps.iter().take(12) {
+        println!("  - {}  (risk={}, v{})", c.name, c.risk, c.version);
+    }
+
+    let res = client.invoke("system.info", json!({})).await?;
+    println!("\nsystem.info → status={}", res.status);
+    if let Some(data) = &res.data {
+        println!("{}", serde_json::to_string_pretty(data)?);
+    }
+
+    client.close();
+    Ok(())
+}

crates/nodeagent-client/examples/probe.rs

@@ -0,0 +1,188 @@
+//! M3 能力探针：对真实被控端逐项调用「文件 / 审计 / 软件 / 进程服务」能力，核对契约。
+//!
+//! 输出**字段契约**而非数据预览——顶层键 + 数组首元素的键，
+//! 便于与前端 `apps/console/src/types/index.ts` 的类型声明逐项比对。
+//!
+//! 用法：`cargo run --example probe -- <url> <key> [base_dir] [--full]`
+//!   --full  额外打印完整 JSON（长字段截断到 400 字符）
+
+use nodeagent_client::{Client, ClientOptions};
+use serde_json::{json, Value};
+
+/// 一行对象 → `a, b, c` 形式的键清单。
+fn keys_of(v: &Value) -> String {
+    match v {
+        Value::Object(m) => m.keys().cloned().collect::<Vec<_>>().join(", "),
+        other => format!("<{}>", type_name(other)),
+    }
+}
+
+fn type_name(v: &Value) -> &'static str {
+    match v {
+        Value::Null => "null",
+        Value::Bool(_) => "bool",
+        Value::Number(_) => "number",
+        Value::String(_) => "string",
+        Value::Array(_) => "array",
+        Value::Object(_) => "object",
+    }
+}
+
+/// 打印「字段契约」：顶层键 + 各数组字段的首元素键。
+fn contract(v: &Value, indent: &str) {
+    if let Value::Object(map) = v {
+        for (k, val) in map {
+            match val {
+                Value::Array(items) if !items.is_empty() => {
+                    println!("{indent}{k}: array[{}] → {{ {} }}", items.len(), keys_of(&items[0]));
+                }
+                other if other.is_object() => {
+                    println!("{indent}{k}: object → {{ {} }}", keys_of(other));
+                }
+                other => {
+                    let shown = match other {
+                        Value::String(s) if s.chars().count() > 60 => {
+                            format!("string(\"{}…\")", s.chars().take(60).collect::<String>())
+                        }
+                        Value::Array(a) => format!("array[{}]", a.len()),
+                        _ => format!("{}({other})", type_name(other)),
+                    };
+                    println!("{indent}{k}: {shown}");
+                }
+            }
+        }
+    } else {
+        println!("{indent}{}", type_name(v));
+    }
+}
+
+async fn call(client: &Client, cap: &str, args: Value, full: bool) -> bool {
+    match client.invoke(cap, args).await {
+        Ok(r) if r.status == "ok" => {
+            println!("  ✓ {cap}");
+            if let Some(d) = &r.data {
+                contract(d, "      ");
+                if full {
+                    let s = serde_json::to_string_pretty(d).unwrap_or_default();
+                    let s: String = s.chars().take(400).collect();
+                    println!("      ── full ── {s}");
+                }
+            }
+            true
+        }
+        Ok(r) => {
+            let e = r.error.unwrap_or_default();
+            println!("  ✗ {cap}: [{}] {}", e.name, e.message);
+            false
+        }
+        Err(e) => {
+            println!("  ✗ {cap}: {e}");
+            false
+        }
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let argv: Vec<String> = std::env::args().skip(1).collect();
+    let full = argv.iter().any(|a| a == "--full");
+    let pos: Vec<String> = argv.into_iter().filter(|a| !a.starts_with("--")).collect();
+
+    let url = pos.first().cloned().unwrap_or_else(|| "ws://127.0.0.1:8765".to_string());
+    let key = pos.get(1).cloned().unwrap_or_default();
+    let base = pos.get(2).cloned().unwrap_or_else(|| "/tmp/nodeagent-e2e".to_string());
+
+    let client = Client::new(ClientOptions {
+        url,
+        key,
+        client_id: "probe".to_string(),
+        insecure: true,
+        ..Default::default()
+    });
+
+    let caps = client.connect().await?;
+    println!("连接成功，{} 项能力", caps.len());
+
+    // 平台探测——决定 platform-only 能力是否预期可用。
+    let info = client.invoke("system.info", json!({})).await?;
+    let os = info
+        .data
+        .as_ref()
+        .and_then(|d| d.get("os"))
+        .and_then(|v| v.as_str())
+        .unwrap_or("?")
+        .to_string();
+    let is_windows = os == "Windows";
+    println!("被控端平台：{os}（platform-only 能力{}预期可用）\n", if is_windows { "" } else { "不" });
+
+    let mut pass = 0usize;
+    let mut fail = 0usize;
+
+    println!("【文件 fs.*】");
+    for (cap, args) in [
+        ("fs.list", json!({ "path": base })),
+        ("fs.stat", json!({ "path": format!("{base}/agent.json") })),
+        ("fs.read", json!({ "path": format!("{base}/agent.json"), "max_bytes": 2048 })),
+        (
+            "fs.write",
+            json!({ "path": format!("{base}/probe.txt"), "data": "hello from rust probe", "append": false, "create_dirs": true }),
+        ),
+    ] {
+        if call(&client, cap, args, full).await {
+            pass += 1
+        } else {
+            fail += 1
+        }
+    }
+
+    println!("\n【审计 system.audit.*】");
+    for (cap, args) in [
+        ("system.audit.list", json!({ "limit": 5 })),
+        ("system.audit.verify", json!({})),
+    ] {
+        if call(&client, cap, args, full).await {
+            pass += 1
+        } else {
+            fail += 1
+        }
+    }
+
+    println!("\n【软件 / 进程 / 服务】");
+    let platform_only = ["app.list", "app.install", "system.service.list"];
+    for (cap, args) in [
+        ("app.list", json!({})),
+        ("app.install", json!({ "package": "__nonexistent_probe__", "silent": true })),
+        ("system.process.list", json!({ "limit": 5 })),
+        ("system.service.list", json!({ "limit": 5 })),
+    ] {
+        let ok = call(&client, cap, args, full).await;
+        // platform-only 能力在非 Windows 被控端上失败属**预期**，不计入失败。
+        if ok {
+            pass += 1;
+        } else if !is_windows && platform_only.contains(&cap) {
+            println!("      ↑ 非 Windows 被控端，属预期");
+        } else {
+            fail += 1;
+        }
+    }
+
+    println!("\n【其他页面依赖】");
+    for (cap, args) in [
+        ("system.info", json!({})),
+        ("system.status", json!({})),
+        ("system.shell.exec", json!({ "command": "echo probe-ok" })),
+    ] {
+        if call(&client, cap, args, full).await {
+            pass += 1
+        } else {
+            fail += 1
+        }
+    }
+
+    println!("\n═══ 通过 {pass} · 失败 {fail} ═══");
+    client.close();
+    if fail > 0 {
+        std::process::exit(1);
+    }
+    Ok(())
+}

crates/nodeagent-client/src/client.rs

@@ -0,0 +1,628 @@
+//! 控制端客户端主体（对齐 `packages/client/src/client.ts` 的 `NodeAgentClient`）。
+//!
+//! 复刻行为：连接 → 握手（hello → challenge → auth → auth_ok）→ 泛型能力调用 →
+//! 事件通知（无 id 的 `event` 方法）→ 断线指数退避重连（1s → 30s，±15% 抖动）。
+//!
+//! 并发结构（监督者模式）：
+//! - `connect()` 派生一个 `supervise` 任务，串行「建立+握手 → 等读循环断开信号 → 退避重连」。
+//! - `establish()` 负责单次连接 + 握手，并派生**读循环**与**写任务**两个子任务。
+//! - 读循环在流结束时只 `notify` 监督者、绝不回调 `establish`——从而打破
+//!   `establish → spawn(read_loop) → establish` 的类型级递归，让每个 future 都可证 `Send`。
+
+use std::collections::HashMap;
+use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
+use std::sync::{Arc, Mutex, RwLock};
+use std::time::Duration;
+
+use futures_util::stream::{SplitSink, SplitStream};
+use futures_util::{SinkExt, StreamExt};
+use serde_json::{json, Value};
+use tokio::sync::{mpsc, oneshot, Notify};
+use tokio_tungstenite::tungstenite::Message;
+
+use crate::crypto::{compute_hmac, sign_nonce};
+use crate::error::{ClientError, ErrorCodes};
+use crate::tls;
+use crate::types::*;
+use crate::ulid::ulid;
+
+/// WebSocket 流类型（TLS 下为 `MaybeTlsStream`）。
+type WsStream =
+    tokio_tungstenite::WebSocketStream<tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>>;
+type WsSink = SplitSink<WsStream, Message>;
+type WsReader = SplitStream<WsStream>;
+
+/// 控制面方法名（对齐 `protocol/src/methods.ts` 的 `Methods`）。
+const M_HELLO: &str = "hello";
+const M_AUTH: &str = "auth";
+const M_INVOKE: &str = "invoke";
+const M_EVENT: &str = "event";
+
+/// 连接状态。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ConnState {
+    Connected,
+    Reconnecting,
+    Closed,
+}
+
+/// 对外事件：连接状态变化 / 被控端主动事件 / 日志。
+#[derive(Debug, Clone)]
+pub enum ClientEvent {
+    State(ConnState),
+    Event(Value),
+    Log(String),
+}
+
+/// 事件回调（`Arc` 便于共享给读循环）。
+pub type EventHandler = Arc<dyn Fn(ClientEvent) + Send + Sync>;
+
+/// 认证模式。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AuthMode {
+    Psk,
+    Ed25519,
+}
+
+/// 客户端选项。
+#[derive(Clone)]
+pub struct ClientOptions {
+    /// `ws://` 或 `wss://` 地址。
+    pub url: String,
+    /// psk 预共享密钥。
+    pub key: String,
+    /// 控制端身份标识。
+    pub client_id: String,
+    /// 跳过自签证书校验（TLS 仍加密）。
+    pub insecure: bool,
+    /// 钉住的被控端证书指纹（sha256 hex，64 位）。
+    pub cert_sha256: Option<String>,
+    /// 认证模式。
+    pub auth_mode: AuthMode,
+    /// ed25519 模式：私钥（Base64 PKCS8 DER）。
+    pub private_key: Option<String>,
+    /// 握手超时（默认 10s）。
+    pub handshake_timeout_ms: u64,
+    /// 单次调用默认超时（默认 60s）。
+    pub default_timeout_ms: u64,
+    /// 断线后自动重连。
+    pub auto_reconnect: bool,
+    /// 重连退避上限（默认 30s）。
+    pub max_reconnect_delay_ms: u64,
+}
+
+impl Default for ClientOptions {
+    fn default() -> Self {
+        Self {
+            url: String::new(),
+            key: String::new(),
+            client_id: String::new(),
+            insecure: false,
+            cert_sha256: None,
+            auth_mode: AuthMode::Psk,
+            private_key: None,
+            handshake_timeout_ms: 10_000,
+            default_timeout_ms: 60_000,
+            auto_reconnect: false,
+            max_reconnect_delay_ms: 30_000,
+        }
+    }
+}
+
+/// 连接元信息（能力清单 / 授权 / 指纹 / 版本）。
+#[derive(Default, Clone)]
+struct Meta {
+    capabilities: Vec<CapabilityDescriptor>,
+    authorized: Option<Vec<String>>,
+    peer_cert_fp: Option<String>,
+    agent_version: Option<String>,
+    agent_build: Option<BuildInfo>,
+}
+
+/// 跨任务共享的可变状态。
+///
+/// 关键约束：`Client` 必须 `Sync`（多处 `&self` 跨 await）。这里的可变字段一律用
+/// `std` 的 `Mutex`/`RwLock`（天然 `Send + Sync`），并保证**不在持锁期间 await**：
+/// 发送半部分通过「专用写任务 + mpsc 通道」解耦，`pending` 的增删改全是同步短临界区。
+struct Shared {
+    /// 到「写任务」的通道；写任务独占 sink 并转发消息（发送不跨 await 持锁）。
+    write: RwLock<Option<mpsc::UnboundedSender<Message>>>,
+    /// 待响应映射（id → oneshot 发送端）；同步锁即可。
+    pending: Mutex<HashMap<String, oneshot::Sender<Result<Value, ClientError>>>>,
+    /// 读循环在流结束时通知监督者（「连接已断开」信号）。
+    disconnected: Notify,
+    meta: RwLock<Meta>,
+    state: RwLock<ConnState>,
+    reconnect_attempts: AtomicU32,
+    stopped: AtomicBool,
+    handler: RwLock<Option<EventHandler>>,
+}
+
+/// 控制端客户端。
+#[derive(Clone)]
+pub struct Client {
+    opts: Arc<ClientOptions>,
+    shared: Arc<Shared>,
+}
+
+impl Client {
+    pub fn new(opts: ClientOptions) -> Self {
+        Self {
+            opts: Arc::new(opts),
+            shared: Arc::new(Shared {
+                write: RwLock::new(None),
+                pending: Mutex::new(HashMap::new()),
+                disconnected: Notify::new(),
+                meta: RwLock::new(Meta::default()),
+                state: RwLock::new(ConnState::Closed),
+                reconnect_attempts: AtomicU32::new(0),
+                stopped: AtomicBool::new(false),
+                handler: RwLock::new(None),
+            }),
+        }
+    }
+
+    /// 设置事件回调。
+    pub fn set_handler(&self, handler: EventHandler) {
+        *self.shared.handler.write().unwrap() = Some(handler);
+    }
+
+    /// 建立连接并完成握手，返回能力清单。
+    /// 派生监督任务后，仅等待**首次**握手结果（失败即返回错误，不自动重连）。
+    pub async fn connect(&self) -> Result<Vec<CapabilityDescriptor>, ClientError> {
+        self.shared.stopped.store(false, Ordering::SeqCst);
+
+        let (tx, rx) = oneshot::channel();
+        let this = self.clone();
+        tokio::spawn(async move {
+            this.supervise(Some(tx)).await;
+        });
+
+        match rx.await {
+            Ok(result) => result,
+            Err(_) => Err(ClientError::offline("连接监督任务异常退出")),
+        }
+    }
+
+    /// 调用一项能力（`args` 为 JSON 对象），用默认超时。
+    pub async fn invoke(
+        &self,
+        capability: &str,
+        args: Value,
+    ) -> Result<InvokeResult, ClientError> {
+        self.invoke_with_timeout(capability, args, self.opts.default_timeout_ms)
+            .await
+    }
+
+    /// 调用一项能力并显式指定 RPC 超时（长任务如 `app.install` / 长命令用）。
+    pub async fn invoke_with_timeout(
+        &self,
+        capability: &str,
+        args: Value,
+        timeout_ms: u64,
+    ) -> Result<InvokeResult, ClientError> {
+        let params = json!({ "capability": capability, "args": args });
+        let value = self.request(M_INVOKE, params, timeout_ms).await?;
+        serde_json::from_value::<InvokeResult>(value)
+            .map_err(|e| ClientError::new(ErrorCodes::PARSE_ERROR, format!("解析调用结果失败: {e}")))
+    }
+
+    /// 已获取的能力清单。
+    pub fn list_capabilities(&self) -> Vec<CapabilityDescriptor> {
+        self.shared.meta.read().unwrap().capabilities.clone()
+    }
+
+    /// ed25519 模式下本次被授权的能力；psk 模式返回 `None`。
+    pub fn list_authorized(&self) -> Option<Vec<String>> {
+        self.shared.meta.read().unwrap().authorized.clone()
+    }
+
+    /// 本次连接观测到的对端证书指纹（sha256 hex）。
+    pub fn peer_cert_fingerprint(&self) -> Option<String> {
+        self.shared.meta.read().unwrap().peer_cert_fp.clone()
+    }
+
+    /// 被控端语义化版本。
+    pub fn agent_version(&self) -> Option<String> {
+        self.shared.meta.read().unwrap().agent_version.clone()
+    }
+
+    /// 被控端构建信息。
+    pub fn agent_build(&self) -> Option<BuildInfo> {
+        self.shared.meta.read().unwrap().agent_build.clone()
+    }
+
+    /// 当前连接状态。
+    pub fn state(&self) -> ConnState {
+        *self.shared.state.read().unwrap()
+    }
+
+    /// 主动关闭连接（停止自动重连）。
+    pub fn close(&self) {
+        self.shared.stopped.store(true, Ordering::SeqCst);
+        // 丢弃发送通道 → 写任务退出 → sink 释放 → 连接关闭；并唤醒监督者及时退出。
+        *self.shared.write.write().unwrap() = None;
+        self.shared.disconnected.notify_one();
+        self.set_state(ConnState::Closed);
+        self.emit_log("主动关闭");
+    }
+
+    // ---------- 内部 ----------
+
+    /// 监督循环：反复「建立+握手 → 等断开 → 退避重连」。
+    /// 首次握手结果经 `first_tx` 回传给 `connect()`；首次失败直接返回，不重连。
+    async fn supervise(
+        &self,
+        first_tx: Option<oneshot::Sender<Result<Vec<CapabilityDescriptor>, ClientError>>>,
+    ) {
+        let mut first_tx = first_tx;
+
+        loop {
+            let established = match self.establish().await {
+                Ok(caps) => {
+                    self.shared.reconnect_attempts.store(0, Ordering::SeqCst);
+                    self.set_state(ConnState::Connected);
+                    // 首次成功：把能力清单回传给 `connect()` 调用方。
+                    if let Some(tx) = first_tx.take() {
+                        let _ = tx.send(Ok(caps));
+                    }
+                    true
+                }
+                Err(e) => {
+                    // 首次失败：直接报错返回（不做自动重连，对齐 Node 行为）。
+                    if let Some(tx) = first_tx.take() {
+                        let _ = tx.send(Err(e));
+                        return;
+                    }
+                    self.emit_log(format!("重连失败: {e}"));
+                    false
+                }
+            };
+
+            // 本次建立成功才有读循环会发「断开」信号；失败则直接进入退避。
+            if established {
+                self.shared.disconnected.notified().await;
+            }
+
+            if self.shared.stopped.load(Ordering::SeqCst) {
+                self.set_state(ConnState::Closed);
+                return;
+            }
+            if !self.opts.auto_reconnect {
+                self.set_state(ConnState::Closed);
+                return;
+            }
+
+            let delay = self.next_backoff_delay();
+            self.set_state(ConnState::Reconnecting);
+            self.emit_log(format!("将在 {}ms 后重连", delay.as_millis()));
+            tokio::time::sleep(delay).await;
+
+            if self.shared.stopped.load(Ordering::SeqCst) {
+                self.set_state(ConnState::Closed);
+                return;
+            }
+        }
+    }
+
+    /// 建立一次连接：TCP/TLS/WS → split → 读循环 + 写任务 → 协议握手。
+    async fn establish(&self) -> Result<Vec<CapabilityDescriptor>, ClientError> {
+        // TLS 下抓取对端证书指纹（自签 + insecure 时留下的中间人空档，靠钉住兜底）。
+        let captured: Arc<Mutex<Option<String>>> = Arc::new(Mutex::new(None));
+
+        let (ws, _resp) = if self.opts.url.starts_with("wss://") {
+            let config = tls::build_client_config(
+                self.opts.insecure,
+                self.opts.cert_sha256.clone(),
+                captured.clone(),
+            )?;
+            let connector = tokio_tungstenite::Connector::Rustls(Arc::new(config));
+            tokio_tungstenite::connect_async_tls_with_config(
+                self.opts.url.as_str(),
+                None,
+                false,
+                Some(connector),
+            )
+            .await
+            .map_err(|e| self.map_connect_error(e))?
+        } else {
+            tokio_tungstenite::connect_async(self.opts.url.as_str())
+                .await
+                .map_err(|e| self.map_connect_error(e))?
+        };
+
+        let peer_fp = captured.lock().unwrap().clone();
+
+        let (sink, stream) = ws.split();
+        let (tx, rx) = mpsc::unbounded_channel();
+        *self.shared.write.write().unwrap() = Some(tx);
+
+        // 写任务独占 sink；读循环独立跑；二者都只持有局部 Send 类型。
+        tokio::spawn(async move { writer_task(sink, rx).await });
+        let this = self.clone();
+        tokio::spawn(async move {
+            this.read_loop(stream).await;
+        });
+
+        // 握手；失败则关闭连接（丢弃发送通道 → 写任务退出 → sink 释放 → 读循环结束）。
+        let result = self.handshake(peer_fp).await;
+        if result.is_err() {
+            *self.shared.write.write().unwrap() = None;
+        }
+        result
+    }
+
+    /// 握手：hello → challenge → auth → auth_ok；成功后写回元信息。
+    async fn handshake(&self, peer_fp: Option<String>) -> Result<Vec<CapabilityDescriptor>, ClientError> {
+        let challenge: ChallengeParams = {
+            let value = self
+                .request(
+                    M_HELLO,
+                    json!({ "protocol": PROTOCOL_VERSION, "client_id": self.opts.client_id }),
+                    self.opts.handshake_timeout_ms,
+                )
+                .await?;
+            serde_json::from_value(value).map_err(|e| {
+                ClientError::new(ErrorCodes::PARSE_ERROR, format!("解析 challenge 失败: {e}"))
+            })?
+        };
+
+        let auth_params = match self.opts.auth_mode {
+            AuthMode::Ed25519 => {
+                let private_key = self.opts.private_key.as_deref().ok_or_else(|| {
+                    ClientError::new(ErrorCodes::AUTH_FAILED, "ed25519 模式需要私钥，请先 keygen")
+                })?;
+                let signature = sign_nonce(private_key, &challenge.nonce).map_err(|e| {
+                    ClientError::new(ErrorCodes::AUTH_FAILED, format!("签名失败: {e}"))
+                })?;
+                json!({ "client_id": self.opts.client_id, "nonce": challenge.nonce, "signature": signature })
+            }
+            AuthMode::Psk => {
+                let hmac = compute_hmac(&self.opts.key, &challenge.nonce);
+                json!({ "client_id": self.opts.client_id, "nonce": challenge.nonce, "hmac": hmac })
+            }
+        };
+
+        let auth_ok: AuthOkParams = {
+            let value = self
+                .request(M_AUTH, auth_params, self.opts.handshake_timeout_ms)
+                .await?;
+            serde_json::from_value(value).map_err(|e| {
+                ClientError::new(ErrorCodes::PARSE_ERROR, format!("解析 auth_ok 失败: {e}"))
+            })?
+        };
+
+        // v21 交叉确认：握手抓到的实际证书 vs 服务端自报 —— 不一致说明自报被篡改/冒充。
+        if let (Some(fp), Some(self_reported)) = (
+            peer_fp.as_ref(),
+            auth_ok
+                .build
+                .as_ref()
+                .and_then(|b| b.cert_sha256.as_ref()),
+        ) {
+            if fp != self_reported {
+                return Err(ClientError::cert_mismatch(
+                    "被控端自报的证书指纹与实际握手证书不一致，拒绝使用（可能被冒充）",
+                ));
+            }
+        }
+
+        let capabilities = auth_ok.capabilities.clone();
+        let authorized_len = auth_ok.authorized.as_ref().map(|a| a.len());
+        {
+            let mut meta = self.shared.meta.write().unwrap();
+            meta.capabilities = auth_ok.capabilities.clone();
+            meta.authorized = auth_ok.authorized.clone();
+            meta.peer_cert_fp = peer_fp;
+            meta.agent_version = auth_ok.agent_version.clone();
+            meta.agent_build = auth_ok.build.clone();
+        }
+
+        let capabilities_len = capabilities.len();
+        let label = if auth_ok.auth_mode.as_deref() == Some("ed25519") {
+            format!("ed25519，授权 {}/{capabilities_len} 项能力", authorized_len.unwrap_or(0))
+        } else {
+            format!("psk，被控端声明 {capabilities_len} 项能力")
+        };
+        self.emit_log(format!("握手成功（{label}）"));
+
+        Ok(capabilities)
+    }
+
+    /// 底层请求（带超时与 id 匹配）。
+    async fn request(
+        &self,
+        method: &str,
+        params: Value,
+        timeout_ms: u64,
+    ) -> Result<Value, ClientError> {
+        let id = ulid();
+        let (tx, rx) = oneshot::channel();
+
+        self.shared.pending.lock().unwrap().insert(id.clone(), tx);
+
+        let req = RpcRequest {
+            jsonrpc: "2.0".to_string(),
+            id: id.clone(),
+            method: method.to_string(),
+            params: Some(params),
+        };
+        let payload = serde_json::to_string(&req)
+            .map_err(|e| ClientError::new(ErrorCodes::PARSE_ERROR, e.to_string()))?;
+
+        {
+            let sender = self
+                .shared
+                .write
+                .read()
+                .unwrap()
+                .as_ref()
+                .cloned()
+                .ok_or_else(|| ClientError::offline("连接未就绪"))?;
+            // 同步发送（不持锁 await）：消息经通道转交写任务。
+            sender
+                .send(Message::Text(payload.into()))
+                .map_err(|e| ClientError::offline(format!("发送失败: {e}")))?;
+        }
+
+        match tokio::time::timeout(Duration::from_millis(timeout_ms), rx).await {
+            Err(_) => {
+                self.shared.pending.lock().unwrap().remove(&id);
+                Err(ClientError::timeout(format!(
+                    "调用超时 ({timeout_ms}ms): {method}"
+                )))
+            }
+            Ok(Err(_)) => Err(ClientError::offline("连接已断开")),
+            Ok(Ok(result)) => result,
+        }
+    }
+
+    /// 读循环：分发响应与事件；流结束后清空 pending 并通知监督者。
+    async fn read_loop(&self, mut stream: WsReader) {
+        while let Some(Ok(msg)) = stream.next().await {
+            if let Err(e) = self.handle_message(msg).await {
+                self.emit_log(format!("消息处理失败: {e}"));
+            }
+        }
+        // 流结束（对端关闭 / 网络断开）→ 清空 pending，由监督者决定是否重连。
+        self.reject_all_pending();
+        self.shared.disconnected.notify_one();
+    }
+
+    /// 处理单条消息。
+    async fn handle_message(&self, msg: Message) -> Result<(), ClientError> {
+        // WebSocket ping 帧：回 pong（保持连接）。
+        if msg.is_ping() {
+            let pong = msg.into_data();
+            if let Some(sender) = self.shared.write.read().unwrap().as_ref() {
+                let _ = sender.send(Message::Pong(pong));
+            }
+            return Ok(());
+        }
+        if !msg.is_text() && !msg.is_binary() {
+            return Ok(());
+        }
+
+        let text = match msg {
+            Message::Text(t) => t.to_string(),
+            Message::Binary(b) => match String::from_utf8(b.to_vec()) {
+                Ok(s) => s,
+                Err(_) => return Ok(()),
+            },
+            _ => return Ok(()),
+        };
+
+        let value: Value = match serde_json::from_str(&text) {
+            Ok(v) => v,
+            Err(_) => {
+                self.emit_log(format!("收到无法解析的消息: {}", &text[..text.len().min(200)]));
+                return Ok(());
+            }
+        };
+
+        // 有 id → 响应；无 id → 通知（事件）。
+        if let Some(id) = value.get("id").and_then(|v| v.as_str()) {
+            if let Some(tx) = self.shared.pending.lock().unwrap().remove(id) {
+                let result = self.parse_response(&value);
+                let _ = tx.send(result);
+            }
+            return Ok(());
+        }
+
+        let method = value.get("method").and_then(|m| m.as_str()).unwrap_or("");
+        if method == M_EVENT {
+            if let Some(params) = value.get("params").cloned() {
+                self.emit_event(params);
+            }
+        }
+        Ok(())
+    }
+
+    /// 把响应消息解析为 `Result<Value, ClientError>`。
+    fn parse_response(&self, value: &Value) -> Result<Value, ClientError> {
+        if is_error_response(value) {
+            let err = value.get("error").cloned().unwrap_or(Value::Null);
+            let code = err
+                .get("code")
+                .and_then(|c| c.as_i64())
+                .unwrap_or(ErrorCodes::PARSE_ERROR);
+            let name = err
+                .get("name")
+                .and_then(|n| n.as_str())
+                .unwrap_or("E_UNKNOWN")
+                .to_string();
+            let message = err
+                .get("message")
+                .and_then(|m| m.as_str())
+                .unwrap_or("")
+                .to_string();
+            Err(ClientError {
+                code,
+                name,
+                message,
+                data: err.get("data").cloned(),
+            })
+        } else {
+            value
+                .get("result")
+                .cloned()
+                .ok_or_else(|| ClientError::new(ErrorCodes::PARSE_ERROR, "响应缺少 result 字段"))
+        }
+    }
+
+    /// 指数退避 + ±15% 抖动（1s → 30s）。
+    fn next_backoff_delay(&self) -> Duration {
+        let attempts = self.shared.reconnect_attempts.fetch_add(1, Ordering::SeqCst);
+        let base = (1000u64 << attempts).min(self.opts.max_reconnect_delay_ms);
+        let jitter = 0.85 + rand::random::<f64>() * 0.3; // 0.85..=1.15
+        Duration::from_millis((base as f64 * jitter) as u64)
+    }
+
+    fn reject_all_pending(&self) {
+        let drained: Vec<oneshot::Sender<Result<Value, ClientError>>> = {
+            let mut map = self.shared.pending.lock().unwrap();
+            map.drain().map(|(_, tx)| tx).collect()
+        };
+        for tx in drained {
+            let _ = tx.send(Err(ClientError::offline("连接已断开")));
+        }
+    }
+
+    fn map_connect_error(&self, e: tokio_tungstenite::tungstenite::Error) -> ClientError {
+        let msg = e.to_string();
+        if msg.contains("证书指纹不匹配") {
+            ClientError::cert_mismatch(msg)
+        } else {
+            ClientError::offline(format!("无法连接被控端: {msg}"))
+        }
+    }
+
+    fn set_state(&self, state: ConnState) {
+        *self.shared.state.write().unwrap() = state;
+        if let Some(h) = self.shared.handler.read().unwrap().as_ref() {
+            h(ClientEvent::State(state));
+        }
+    }
+
+    fn emit_event(&self, params: Value) {
+        if let Some(h) = self.shared.handler.read().unwrap().as_ref() {
+            h(ClientEvent::Event(params));
+        }
+    }
+
+    fn emit_log(&self, msg: impl Into<String>) {
+        if let Some(h) = self.shared.handler.read().unwrap().as_ref() {
+            h(ClientEvent::Log(msg.into()));
+        }
+    }
+}
+
+/// 写任务：独占 sink，把 mpsc 通道里的消息逐条发出去。
+/// 通道关闭（`close()` 丢弃 sender）或发送失败时退出，sink 随之释放。
+async fn writer_task(mut sink: WsSink, mut rx: mpsc::UnboundedReceiver<Message>) {
+    while let Some(msg) = rx.recv().await {
+        if sink.send(msg).await.is_err() {
+            break;
+        }
+    }
+}

crates/nodeagent-client/src/crypto.rs

@@ -0,0 +1,131 @@
+//! 密码学工具：HMAC / ed25519 签名 / 证书指纹 / nonce。
+//! 逐一对齐 `packages/protocol/src/{hmac,ed25519}.ts` 与 `net.ts`。
+
+use base64::engine::general_purpose::STANDARD;
+use base64::Engine as _;
+use hmac::{Hmac, KeyInit, Mac};
+use sha2::{Digest, Sha256};
+
+type HmacSha256 = Hmac<Sha256>;
+
+/// 计算 HMAC-SHA256，返回 Base64（对齐 hmac.ts 的 `computeHmac`）。
+/// 密钥为预共享密钥字符串，nonce 以 UTF-8 编码。
+pub fn compute_hmac(key: &str, nonce: &str) -> String {
+    // HMAC 接受任意长度 key，此处不可能失败，unwrap 仅为类型收敛。
+    let mut mac = HmacSha256::new_from_slice(key.as_bytes()).expect("HMAC 接受任意长度 key");
+    mac.update(nonce.as_bytes());
+    STANDARD.encode(mac.finalize().into_bytes())
+}
+
+/// 生成随机 nonce（32 字节，Base64），对齐 `generateNonce`。
+pub fn generate_nonce() -> String {
+    let mut bytes = [0u8; 32];
+    for b in bytes.iter_mut() {
+        *b = rand::random::<u8>();
+    }
+    STANDARD.encode(bytes)
+}
+
+/// 证书指纹：sha256(DER) 的十六进制小写 64 位（对齐 net.ts 的 `certFingerprint`）。
+pub fn cert_fingerprint(der: &[u8]) -> String {
+    let digest = Sha256::digest(der);
+    digest.iter().map(|b| format!("{b:02x}")).collect()
+}
+
+/// 对 nonce 原文做 ed25519 签名，返回 Base64（对齐 ed25519.ts 的 `signNonce`）。
+/// 私钥为 Base64(PKCS8 DER)。
+pub fn sign_nonce(private_key_b64: &str, nonce: &str) -> Result<String, String> {
+    use ed25519_dalek::pkcs8::DecodePrivateKey;
+    use ed25519_dalek::Signer;
+
+    let der = STANDARD
+        .decode(private_key_b64)
+        .map_err(|e| format!("私钥 Base64 解码失败: {e}"))?;
+    let signing_key = ed25519_dalek::SigningKey::from_pkcs8_der(&der)
+        .map_err(|e| format!("PKCS8 私钥解析失败: {e}"))?;
+    let sig = signing_key.sign(nonce.as_bytes());
+    Ok(STANDARD.encode(sig.to_bytes()))
+}
+
+/// 验签（对齐 `verifyNonce`）；任何异常均视为失败（不抛出）。
+pub fn verify_nonce(public_key_b64: &str, nonce: &str, signature_b64: &str) -> bool {
+    use ed25519_dalek::pkcs8::DecodePublicKey;
+    use ed25519_dalek::Verifier;
+
+    let Ok(pk_der) = STANDARD.decode(public_key_b64) else {
+        return false;
+    };
+    let Ok(vk) = ed25519_dalek::VerifyingKey::from_public_key_der(&pk_der) else {
+        return false;
+    };
+    let Ok(sig_bytes) = STANDARD.decode(signature_b64) else {
+        return false;
+    };
+    let Ok(sig) = ed25519_dalek::Signature::from_slice(&sig_bytes) else {
+        return false;
+    };
+    vk.verify(nonce.as_bytes(), &sig).is_ok()
+}
+
+/// 公钥指纹（SHA-256 前 16 位 hex），对齐 `keyId`。
+pub fn key_id(public_key_b64: &str) -> String {
+    let der = STANDARD.decode(public_key_b64).unwrap_or_default();
+    let digest = Sha256::digest(&der);
+    // 前 16 个 hex 字符 = 前 8 字节。
+    digest.iter().take(8).map(|b| format!("{b:02x}")).collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use base64::engine::general_purpose::STANDARD;
+    use ed25519_dalek::pkcs8::{EncodePrivateKey, EncodePublicKey};
+
+    fn gen_keypair() -> (String, String) {
+        let sk = ed25519_dalek::SigningKey::from_bytes(&[7u8; 32]);
+        let pk = sk.verifying_key();
+        (
+            STANDARD.encode(pk.to_public_key_der().expect("编码公钥").as_bytes()),
+            STANDARD.encode(sk.to_pkcs8_der().expect("编码私钥").as_bytes()),
+        )
+    }
+
+    #[test]
+    fn hmac_matches_known_vector() {
+        // 与 Node 版对拍的固定向量：HMAC-SHA256("key", "nonce")。
+        let out = compute_hmac("secret", "hello");
+        // 用独立的 hmac 重算并比对，避免自证。
+        let mut mac = HmacSha256::new_from_slice(b"secret").unwrap();
+        mac.update(b"hello");
+        let expect = STANDARD.encode(mac.finalize().into_bytes());
+        assert_eq!(out, expect);
+        // Base64(HMAC-SHA256("secret","hello")) 的已知值（由 RFC 测试向量推得，供跨端核对）。
+        assert_eq!(out, "iKqz7ejTrflNJquQ07r9SiCDBww7zOnAFO4EpEOEfAs=");
+    }
+
+    #[test]
+    fn sign_and_verify_roundtrip() {
+        let (pk, sk) = gen_keypair();
+        let nonce = generate_nonce();
+        let sig = sign_nonce(&sk, &nonce).unwrap();
+        assert!(verify_nonce(&pk, &nonce, &sig));
+        assert!(!verify_nonce(&pk, "tampered", &sig));
+    }
+
+    #[test]
+    fn key_id_is_16_hex() {
+        let (pk, _sk) = gen_keypair();
+        let id = key_id(&pk);
+        assert_eq!(id.len(), 16);
+        assert!(id.chars().all(|c| c.is_ascii_hexdigit()));
+    }
+
+    #[test]
+    fn cert_fingerprint_sha256_der() {
+        // 空 DER 的 sha256 是已知常量。
+        assert_eq!(
+            cert_fingerprint(b""),
+            "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+        );
+    }
+}

crates/nodeagent-client/src/discovery.rs

@@ -0,0 +1,145 @@
+//! 局域网发现（对齐 `packages/client/src/discovery.ts`）。
+//!
+//! 只监听被控端 UDP 广播、不发送任何数据，因此不引入额外暴露面。
+//! M1 实现基础解析；v22 最小化广播的 HMAC 验签留待后续（需对齐 JSON 序列化顺序）。
+
+use std::collections::HashMap;
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+use serde::{Deserialize, Serialize};
+use tokio::net::UdpSocket;
+
+/// 发现到的被控端。
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiscoveredNode {
+    pub node_id: String,
+    /// 可达地址：取报文来源 IP（一定可达）。
+    pub host: String,
+    /// 被控端自报地址（多网卡时可能与来源不同，仅供参考）。
+    pub advertised_host: String,
+    pub port: u16,
+    pub tls: bool,
+    pub auth_mode: String,
+    pub input_enabled: bool,
+    pub platform: String,
+    /// v22：详情是否通过 HMAC 验签。false = 明文广播，仅作展示、不可当凭据。
+    pub authenticated: bool,
+    /// 最近一次收到广播的时间（Unix 毫秒）。
+    pub last_seen: u64,
+}
+
+#[derive(Debug, Deserialize)]
+struct RawBeacon {
+    service: Option<String>,
+    node_id: Option<String>,
+    host: Option<String>,
+    port: Option<u16>,
+    tls: Option<bool>,
+    auth_mode: Option<String>,
+    input_enabled: Option<bool>,
+    platform: Option<String>,
+    minimal: Option<bool>,
+    #[serde(default)]
+    detail: Option<BeaconDetail>,
+}
+
+#[derive(Debug, Deserialize)]
+struct BeaconDetail {
+    host: Option<String>,
+    port: Option<u16>,
+    tls: Option<bool>,
+    auth_mode: Option<String>,
+    input_enabled: Option<bool>,
+    platform: Option<String>,
+}
+
+/// 默认发现端口（对齐 methods.ts 的 `DEFAULT_DISCOVERY_PORT`）。
+pub const DEFAULT_DISCOVERY_PORT: u16 = 8766;
+
+/// 默认被控端端口。
+const DEFAULT_AGENT_PORT: u16 = 8765;
+
+/// 监听一段时间后返回发现的设备（对齐 `discoverOnce`）。
+pub async fn discover_once(wait_ms: u64, port: u16) -> Result<Vec<DiscoveredNode>, String> {
+    let socket = UdpSocket::bind(("0.0.0.0", port))
+        .await
+        .map_err(|e| format!("发现监听失败（UDP {port}）: {e}"))?;
+
+    let mut nodes: HashMap<String, DiscoveredNode> = HashMap::new();
+    let deadline = tokio::time::Instant::now() + Duration::from_millis(wait_ms);
+    let mut buf = [0u8; 2048];
+
+    loop {
+        let remaining = deadline.saturating_duration_since(tokio::time::Instant::now());
+        if remaining.is_zero() {
+            break;
+        }
+        match tokio::time::timeout(remaining, socket.recv_from(&mut buf)).await {
+            Ok(Ok((len, src))) => {
+                if let Some(node) = parse_beacon(&buf[..len], src) {
+                    nodes.insert(node.node_id.clone(), node);
+                }
+            }
+            _ => break,
+        }
+    }
+
+    let now = now_ms();
+    let mut list: Vec<DiscoveredNode> = nodes.into_values().collect();
+    // 过滤 TTL 过期项（30s），按最近出现排序。
+    list.retain(|n| now - n.last_seen <= 30_000);
+    list.sort_by_key(|n| std::cmp::Reverse(n.last_seen));
+    Ok(list)
+}
+
+fn parse_beacon(data: &[u8], src: std::net::SocketAddr) -> Option<DiscoveredNode> {
+    let raw: RawBeacon = serde_json::from_slice(data).ok()?;
+    if raw.service.as_deref() != Some("nodeagent") {
+        return None;
+    }
+    let node_id = raw.node_id?;
+
+    // v22 最小化广播：顶层只剩存在性，真实信息在 detail 里。
+    let detail = raw.minimal.unwrap_or(false).then_some(raw.detail).flatten();
+
+    Some(DiscoveredNode {
+        node_id,
+        // 地址永远取「报文来源 IP」—— 一定可达。
+        host: src.ip().to_string(),
+        advertised_host: detail
+            .as_ref()
+            .and_then(|d| d.host.clone())
+            .or(raw.host)
+            .unwrap_or_else(|| src.ip().to_string()),
+        port: detail
+            .as_ref()
+            .and_then(|d| d.port)
+            .or(raw.port)
+            .unwrap_or(DEFAULT_AGENT_PORT),
+        tls: detail.as_ref().and_then(|d| d.tls).or(raw.tls).unwrap_or(true),
+        auth_mode: detail
+            .as_ref()
+            .and_then(|d| d.auth_mode.clone())
+            .or(raw.auth_mode)
+            .unwrap_or_else(|| "psk".to_string()),
+        input_enabled: detail
+            .as_ref()
+            .and_then(|d| d.input_enabled)
+            .or(raw.input_enabled)
+            .unwrap_or(false),
+        platform: detail
+            .as_ref()
+            .and_then(|d| d.platform.clone())
+            .or(raw.platform)
+            .unwrap_or_else(|| "unknown".to_string()),
+        authenticated: false,
+        last_seen: now_ms(),
+    })
+}
+
+fn now_ms() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_millis() as u64)
+        .unwrap_or(0)
+}

crates/nodeagent-client/src/error.rs

@@ -0,0 +1,96 @@
+//! 协议错误码与客户端错误类型（对齐 `packages/protocol/src/errors.ts`）。
+
+use std::fmt;
+
+/// 协议错误码常量（对齐 errors.ts 的 `ErrorCodes`）。
+#[allow(non_snake_case)]
+pub mod ErrorCodes {
+    pub const PARSE_ERROR: i64 = -32700;
+    pub const INVALID_REQUEST: i64 = -32600;
+    pub const METHOD_NOT_FOUND: i64 = -32601;
+    pub const PARAM_INVALID: i64 = -32602;
+    pub const AUTH_FAILED: i64 = -32401;
+    pub const AUTH_REQUIRED: i64 = -32402;
+    pub const CAPABILITY_NOT_FOUND: i64 = -32403;
+    pub const CAPABILITY_DISABLED: i64 = -32404;
+    pub const NODE_OFFLINE: i64 = -32405;
+    pub const ACL_DENIED: i64 = -32406;
+    pub const RATE_LIMITED: i64 = -32407;
+    pub const TIMEOUT: i64 = -32412;
+    pub const EXECUTION_FAILED: i64 = -32419;
+    pub const PROTOCOL_MISMATCH: i64 = -32420;
+    pub const UNSUPPORTED_PLATFORM: i64 = -32421;
+    /// v21：被控端证书指纹与控制端钉住的不一致（可能被冒充）。
+    pub const CERT_MISMATCH: i64 = -32422;
+}
+
+/// 错误码 → 名称。
+pub fn error_name(code: i64) -> &'static str {
+    match code {
+        ErrorCodes::PARSE_ERROR => "E_PARSE_ERROR",
+        ErrorCodes::INVALID_REQUEST => "E_INVALID_REQUEST",
+        ErrorCodes::METHOD_NOT_FOUND => "E_METHOD_NOT_FOUND",
+        ErrorCodes::PARAM_INVALID => "E_PARAM_INVALID",
+        ErrorCodes::AUTH_FAILED => "E_AUTH_FAILED",
+        ErrorCodes::AUTH_REQUIRED => "E_AUTH_REQUIRED",
+        ErrorCodes::CAPABILITY_NOT_FOUND => "E_CAPABILITY_NOT_FOUND",
+        ErrorCodes::CAPABILITY_DISABLED => "E_CAPABILITY_DISABLED",
+        ErrorCodes::NODE_OFFLINE => "E_NODE_OFFLINE",
+        ErrorCodes::ACL_DENIED => "E_ACL_DENIED",
+        ErrorCodes::RATE_LIMITED => "E_RATE_LIMITED",
+        ErrorCodes::TIMEOUT => "E_TIMEOUT",
+        ErrorCodes::EXECUTION_FAILED => "E_EXECUTION_FAILED",
+        ErrorCodes::PROTOCOL_MISMATCH => "E_PROTOCOL_MISMATCH",
+        ErrorCodes::UNSUPPORTED_PLATFORM => "E_UNSUPPORTED_PLATFORM",
+        ErrorCodes::CERT_MISMATCH => "E_CERT_MISMATCH",
+        _ => "E_UNKNOWN",
+    }
+}
+
+/// 客户端错误（携带协议错误码，对齐 client.ts 的 `ClientError`）。
+#[derive(Debug, Clone)]
+pub struct ClientError {
+    pub code: i64,
+    pub name: String,
+    pub message: String,
+    pub data: Option<serde_json::Value>,
+}
+
+impl ClientError {
+    pub fn new(code: i64, message: impl Into<String>) -> Self {
+        Self {
+            code,
+            name: error_name(code).to_string(),
+            message: message.into(),
+            data: None,
+        }
+    }
+
+    pub fn with_data(mut self, data: serde_json::Value) -> Self {
+        self.data = Some(data);
+        self
+    }
+
+    /// 被控端离线/不可达。
+    pub fn offline(message: impl Into<String>) -> Self {
+        Self::new(ErrorCodes::NODE_OFFLINE, message)
+    }
+
+    /// 调用超时。
+    pub fn timeout(message: impl Into<String>) -> Self {
+        Self::new(ErrorCodes::TIMEOUT, message)
+    }
+
+    /// 证书指纹不一致。
+    pub fn cert_mismatch(message: impl Into<String>) -> Self {
+        Self::new(ErrorCodes::CERT_MISMATCH, message)
+    }
+}
+
+impl fmt::Display for ClientError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}: {}", self.name, self.message)
+    }
+}
+
+impl std::error::Error for ClientError {}

crates/nodeagent-client/src/lib.rs

@@ -0,0 +1,34 @@
+//! nodeagent 控制端 Rust 客户端。
+//!
+//! 行为对齐 `packages/client`（Node 版），复刻：
+//! - 握手 hello → challenge → auth → auth_ok（psk HMAC / ed25519 签名）
+//! - 泛型能力调用 invoke（带超时与 id 匹配）
+//! - 事件通知（无 id 的 JSON-RPC notification，`event` 方法）
+//! - 断线指数退避重连（1s → 30s，±15% 抖动）
+//! - TLS 自签证书 + 指纹钉住（v21，E_CERT_MISMATCH）
+
+pub mod client;
+pub mod crypto;
+pub mod discovery;
+pub mod error;
+pub mod tls;
+pub mod types;
+pub mod ulid;
+
+pub use client::{Client, ClientEvent, ClientOptions, ConnState};
+pub use error::{ClientError, ErrorCodes};
+pub use types::{CapabilityDescriptor, InvokeResult};
+
+#[cfg(test)]
+mod send_sync_checks {
+    use super::*;
+
+    fn assert_send_sync<T: Send + Sync>() {}
+
+    #[test]
+    fn client_is_send_sync() {
+        assert_send_sync::<Client>();
+        assert_send_sync::<ClientOptions>();
+        assert_send_sync::<ClientError>();
+    }
+}