 jkooe
|
689bb8c98d
|
feat(v1.5): 快捷键控制范围扩展 —— 字符串热键 / 预设别名 / 长按 / 后台定向投递
## 背景
原 `input.key.press` 只接受数组和弦（keys/sequence），按键表也不全：
AI/MCP 调用要拼 ["ctrl","shift","esc"]，且 **win+d、ctrl++、win+. 这类
"修饰键 + OEM 符号键"的组合根本打不出来**（表里没有符号键）。
## 四类扩展
① **字符串热键**：`hotkey: "ctrl+shift+esc"`、`hotkeys: ["ctrl+c","ctrl+v"]`
—— 分隔符支持 `+ - 空格`，大小写不敏感，别名归一（command/cmd→win、del→delete…）
② **预设别名**：约 50 个语义名（copy / show_desktop / task_manager / screenshot /
volume_mute_toggle…），AI 调用免记键位；`preset` 与 `presets`（序列）均支持
③ **长按** `hold_ms`（≤5s）：按下→保持→释放，插在"按完"与"释放"之间
④ **后台定向投递** `route=post` + `target_pid`：向目标进程**全部顶层窗口**
PostMessage WM_KEYDOWN/UP —— 目标窗口被遮挡/最小化时可用
（媒体键的 WM_APPCOMMAND 机制早已验证，此为其等价物）
文档明示局限：游戏/部分输入型程序不响应后台键消息
## 按键表补齐（单测覆盖断言防漂移）
- 左右侧修饰键 lctrl/rctrl/lshift/rshift/lalt/ralt/lwin/rwin（游戏常区分左右）
- 小键盘 numpad0-9 + 四则运算，**与数字键分开**（Excel 靠 NumLock 区分）
- OEM 符号键 oem_1..oem_8 / oem_minus/plus/comma/period（解锁 win+d、ctrl++、win+.）
- 浏览器收藏夹/主页、系统键（sleep/help/select/execute/clear/separator/oem_clear）
- IME 键（kana/hangul/kanji/hanja/convert/nonconvert/accept/modechange）
- 补齐 pause/apps（重构时一度漏掉，被覆盖断言测试立刻抓到）
## 可测性重构
脚本生成抽成**纯函数** `apps/agent/src/capabilities/input-script.ts`
（VK_MAP / MEDIA_COMMANDS / toVk / build{Media,Foreground,Post}Body），
行内生成逻辑全部改为调用 —— 于是**按下顺序/逆序释放/hold 插入位置/post 路由**
这些最容易写错的部分，现在由 14 个单测逐行断言，真机只需验证最终效果。
## 参数校验
protocol `expandChords()` 统一展开六种输入形式，**混用即报错**（消除"以谁为准"歧义）；
同一和弦重复修饰键、超 4 键、空输入均拒绝。渲染返回值新增 presets/via/channel/sent_windows。
## CLI / MCP
- CLI：`nodeagent key press "ctrl+shift+esc"` / `key press copy` / 老形式 `key press ctrl c`
新增 `--hold`、`--route`；回显预设展开与后台投递命中窗口数
- MCP `na_key`：同步支持 hotkey/hotkeys/preset/presets/hold_ms/route/target_pid
## 验证
- 单测 **179 → 195**：hotkeys 解析与别名 17 例、**脚本生成逐行断言 14 例**、
按键覆盖断言（HOTKEY_KEYS ⊆ VK_MAP）、新参数 schema 校验 2 例
- e2e **29** 全绿
- ⚠️ **真机未验证**：Windows 被控端当前离线（连接超时）。待上线后需验：
`key press "win+d"`（切桌面再切回）、`key press copy` 配剪贴板、
`route=post` 定向一个最小化窗口。验证通过后再发版。
|
2026-10-07 00:59:40 +08:00 |
|
|
jkooe
|
9d32592ed1
|
feat(v1.2): input.key.press 支持媒体键（WM_APPCOMMAND 通道 + 定向投递）
远程控 QQ 音乐时发现：媒体键全部查不到，window.focus 越不过游戏全屏，
而软件热键在精简模式下未注册 —— 只能绕道 WM_APPCOMMAND 手写脚本。
现把这条通道正式纳入能力，避免每次重造轮子。
1. VK_MAP 补全（input.ts）
media_play_pause(0xB3) / media_stop(0xB2) / media_next(0xB0) / media_prev(0xB1)
media_rewind(0xB7) / media_fast_forward(0xB4) / volume_mute(0xAD) /
volume_down(0xAE) / volume_up(0xAF) / 浏览器键 / F13-F24
2. 新增 WM_APPCOMMAND 通道（关键，非仅补 VK）
媒体键不再走 SendInput，改为识别「整条序列都是媒体键」后走
PostMessage(WM_APPCOMMAND)。原因：
- SendInput 打进媒体键后，只有当前媒体会话焦点的窗口才响应
- APPCOMMAND 可定向投递到指定窗口/进程，绕开该不确定性
- 窗口最小化或被全屏游戏遮挡时依然有效（实测 QQ 音乐被 DNF 全屏压住仍可控）
3. 新增 target_pid 参数 + CLI --pid
播放器常创建 30+ 辅助顶层窗口（QQ 音乐实测 36 个），只投主窗口常常无效
→ 指定 PID 后向该进程全部顶层窗口投递。
返回值加 via:'appcommand' 与 target_pid，便于确认走的是哪条通道。
4. 音量键刻意不进 APPCOMMAND 表
APPCOMMAND 的 lParam 按位传递（低 16 位 command、位 12-15 设备类型），
裸值会撞车（APPCOMMAND_VOLUME_DOWN 与 APPCOMMAND_PAUSE 都是 1），
纳入表中会导致静音键被误当暂停。故音量键走真·VK 注入，由系统自行翻译。
5. screenshot --scale 报错信息改善（gui.ts）
协议限定 scale ∈ (0,1]，原先非法值直发只回「参数校验失败」，看不出是哪项
→ CLI 前置校验，明确提示「--scale 应在 0 到 1 之间…收到: 3」。
6. window.focus 边界写入 manifest
明确无法越过全屏独占应用：此时返回 focused:true 但视觉仍遮挡、点不到，
属预期而非失败；指引改用媒体键 / shell.exec / 请用户切出全屏。
真机验证（192.168.1.100）：单测 162 全绿；媒体键广播与定向投递均生效；
volume_up 20%→22%、volume_down×2 →18%；非法键名仍明确报错。
双端已部署，指纹 5b68faa20a3e，v1.4.3。
|
2026-10-05 15:06:24 +08:00 |
|
|
jkooe
|
e841fbb187
|
feat(v22): 第二批安全加固 —— 每客户端独立 PSK + 发现广播最小化
接着 v21 的两件 P0，补齐第二批清单里的两项（对应原建议 ③/④ 的一半）。
## ① 每客户端一把 PSK（`agent.json` 的 `keys{}`）—— 让 ACL 的身份维度真正有效
**问题**：psk 模式下 `client_id` 由客户端自报（server.ts 原注释自认），
一把共享 key 意味着**持有者可冒充任意 client_id**，ACL 的身份维度形同虚设。
**做法**：按 `client_id` 分配独立钥匙；未登记者回落到共享 `key`（旧部署行为不变）。
比 ed25519 更轻量（不用管公钥），同样是「一把一个身份」。
**实测**（五场景全对）：
| 场景 | 结果 |
|---|---|
| alice 用自己的 key | ✅ |
| **alice 的 key 冒用 bob 身份** | ❌ E_AUTH_FAILED ← 核心安全性质 |
| bob 用自己的 key | ✅ |
| 未登记 carol 用共享 key | ✅（向后兼容） |
| 已登记 alice 用共享 key | ❌ 拒绝（专属优先，不被共享 key 绕过） |
配套：`nodeagent keygen --psk --id mac_02` 生成专属 key 并打印可直接粘贴的 agent.json 片段；
鉴权日志带 `key=scoped|shared-fallback|shared`，审计区分「专属钥匙失败」与「回落共享失败」。
## ② 发现广播最小化（`discovery.detail` + `discovery.secret`）—— 收情报泄漏
**问题**：UDP 广播未认证，默认明文告知 IP/端口/认证方式/键鼠开关，等于给攻击者一份目标清单。
**做法**：
- `detail: "minimal"` → 顶层只剩 `service / version / node_id / ts`，
真实信息收进 `detail{}`（**实测顶层已无 host/port/auth_mode/input_enabled**）
- 配 `secret` → `detail` 带 HMAC 签名（`node_id|ts|JSON(detail)`），
控制端 `discover --discover-secret <同一密钥>` 验签 → 列表标 **🔒 已认证**；
未配/验签失败标 **⚠️ 明文**（明示「仅作参考、不可当凭据」）
- 配了 secret 自动启用 minimal；未配置时启动横幅**醒目告警**提示收敛
**实测**三视角：正确密钥 🔒 / 无密钥 ⚠️ / 错密钥 ⚠️（验签失败正确降级）✓
## 验证
- 单测 159 → **162**（新增签名往返一致性：错密钥/篡改详情/改时间戳均须验签失败）
- e2e **29** 全绿；本轮改动为纯加法（新增可选字段），未破坏既有行为
- 文档 `SECURITY.md` 新增 §4.5 / §4.6，并把「发现最小化」从待办划掉
## 剩余待办（SECURITY.md §5）
握手失败封禁 / 审计链签名与外部锚定 / 会话上限与空闲断开 / 安装期密钥改用文件传递 /
ed25519 仍非默认（v22 的 `keys{}` 已是更轻量的等价物）
|
2026-10-05 02:42:12 +08:00 |
|
|
jkooe
|
0d59d6032b
|
feat(v21): 第一批安全加固 —— 证书指纹钉住 + 来源网段白名单
对应审查建议的 P0 两条：这两项是**真实可利用的攻击路径**，其余（发现最小化/失败封禁等）
留待后续批次。
## ① 证书指纹钉住（TOFU）—— 挡同网段中间人
自签证书没有 CA 链，历史上客户端只能 `insecure` 接受任意证书 → 攻击者可**透明中继**：
拿不到钥匙（挑战-应答挡得住冒名），但能读到截屏/剪贴板/键入/exec 输出。
- 被控端：`install.ps1` 打印证书指纹（sha256 of DER）供**带外核对**；
`system.info.build.cert_sha256` 与 `auth_ok.build.cert_sha256` 上报
- 控制端：首次连接自动钉进 `nodes.<名>.cert_sha256`；之后**严格比对**，
不一致即 `E_CERT_MISMATCH`(-32422) 拒连，并提示 `--forget-cert` 重钉
- 额外做**交叉确认**：实际握手证书 vs auth_ok 自报，不一致同样拒绝（防自报被篡改）
- 指纹基于 **DER**（不是 PEM 字节），保证与 Windows .NET `GetRawCertData()` 同值
**踩坑记录（写进代码注释，避免后人重走）**：
1. `ws` 客户端的 `upgrade` 事件**只传 IncomingMessage**，拿不到 socket
2. socket 要在 `open` 之后从 `ws._socket` 取（TLSSocket）
3. Node ≥15 的 `getPeerCertificate()` 返回**对象**，DER 在 `.raw` 上（老版本才是 Buffer）
—— 现已双兼容
## ② 来源网段白名单 `allow_from` —— 收敛暴露面
被控端默认监听 `0.0.0.0`（远程接入所需），但**换到不可信网络就自动暴露**。
- 支持 CIDR / 单 IP / `*`；**未配置 = 放行全部**（保持向后兼容，不打断现有部署）
- 拒绝发生在**业务握手之前**（不做 TLS/挑战应答，省资源），并记 `net.deny` 审计
- 判定按**前缀比特**而非字符串相等：Node 在 IPv6 监听上把 IPv4 客户端报成
`::ffff:a.b.c.d`，已归一化（单测覆盖）
- `system.info.network.allow_from` 上报状态；`nodeagent info` 一眼看出是否已收敛
## 验证（本地真跑，非纸面）
- 白名单不含本机 → 连接被拒（agent 侧 WARN + 审计留痕）✓
- 白名单含本机 → 连上，并**自动钉住**指纹 ✓
- **换掉被控端证书后重连 → `E_CERT_MISMATCH` 拒绝**（期望 2ed4957b… / 实际 ca8dc20c…）✓
- 新增 e2e 用例（自起 TLS agent）覆盖上述四种情形 + agent 自报与实际证书一致性 ✓
- 新增单测 9 例（CIDR 前缀匹配 / IPv4-mapped 归一 / IPv6 zone / PEM≡DER / 篡改即变）
- 全量：单测 **159**（150→159）· e2e **29**（28→29）全绿
## 文档
新增 `docs/SECURITY.md`：信任模型（钥匙=root）、认证现状与**已知限制**（ACL 身份维度仅在
ed25519 有效）、本次两项加固的用法、尚未收敛的 6 项、应急处置表。
|
2026-10-05 02:25:19 +08:00 |
|
|
jkooe
|
cedc46d090
|
feat(v20): 版本纪律 + 发版自动化（对齐「做好版本功能 + GitHub 同步资产」）
## 一、版本功能（防新旧混用）
1. **单一版本源 + 构建注入**：根 package.json 的 version、git sha、构建时间经 esbuild
`--define` 注入 agent；`system.info.build` 新增 `version/commit/built_at`（原有 `hash` 指纹不变）。
开发态用 typeof 探测（未注入也不崩）。
2. **握手携带版本**：`auth_ok` 新增可选字段 `agent_version` / `build` / `protocol`（只增不减 → 旧控制端忽略即可）。
3. **能力级兼容比对**：新增纯函数 `capabilityDiff(local, remote)` ——
- `missingOnRemote`：本地有远端没有 → **远端较旧**，提示更新被控端
- `unknownLocally`：远端有本地没有 → **本控制端较旧**（不影响既有功能）
控制端不比版本号而比**能力集合**：版本号可能相同而内容不同，能力集合不会骗人。
4. **CLI 体检**：`nodeagent info` / `connect` 直接显示被控端版本与能力对齐情况，
把"调用时才炸"变成一句人话提示。
## 二、发版自动化（GitHub 资产同步）
`pnpm release <x.y.z|patch|minor|major>`：前置检查（干净/在 main/与远端同步）→ 改 7 个 package.json
→ 构建+打包 → 生成资产 → 提交打标签推送 → `gh release create` 上传。
- 资产：`agent.mjs`（**自更新载荷**）、`nodeagent-win-x64.zip`（人工安装包）、
`latest.json`（version/commit/能力数 + 两个资产的 url 与 sha256）、`SHA256SUMS`
- `--dry-run` 无副作用演练；`--no-publish` 只到本地标签
- 能力数从 dist 动态取（避免写死漂移）；刻意排除 `.github/`（缺 workflow 权限推不了）
## 三、兼容性契约文档
新增 `docs/VERSIONING.md`：semver 各位的含义、**只增不改**六条硬规则、
升级顺序建议（**先被控端**：新被控端向后兼容旧 CLI）、两条更新路径、发版流程、排查手册。
## 验证
- 单测 147 → **149**（新增 capabilityDiff 用例：远端过旧 / 本机过旧 / 完全一致 / 真实清单自比无差异）
- e2e 28 全绿；`node scripts/release.mjs 1.0.0 --dry-run` 演练通过且工作区无副作用
|
2026-10-04 23:54:51 +08:00 |
|
|
jkooe
|
aa72241080
|
fix: 真机全量测试修 5 个 bug（剪贴板假失败 / 音频后端误标 / CLI info 打印 / key press 崩溃 / Unicode 代理对）
在 192.168.1.100 真机逐项跑通 42 项能力，暴露并修复 5 个真 bug：
1. clip.set 假失败（间歇 ~20%）
Set-Clipboard 抛「所请求的剪贴板操作失败」时 exit_code 仍为 0（只写 stderr），
且内容其实已写入 —— 造成「成功却报错」。改为重试 3 次 + 退避 + 读回校验，
不再凭 exit_code 下结论。验证：修前 2/5 失败 → 修后 0/8 失败。
2. Windows 音频 backend 误标 'CoreAudio'
CoreAudio 是 macOS 的后端名；Windows 实际走 C# NAudio(CoreAudioAPI)。
抽常量并修正 manifest 描述，避免排查时误判平台。
3. CLI info 把嵌套对象打成 [object Object]
ps_helper / build 是嵌套对象，String(v) 丢失全部内容。新增 renderInfoValue()：
null→—、空串→—（未设置）、对象→key=value 紧凑摘要（180 字截断）。
4. nodeagent key press 必崩（100% 复现）
字段契约不一致：被控端返回 {pressed,chords,times}（无 keys），
CLI 读 r.keys.join() 抛 TypeError。双端对齐 —— agent 补回 keys 字段，
CLI 改为 keys ?? chords 展开 ?? 参数回显。
5. Unicode 注入拆坏代理对（emoji / 生僻字）
UnicodeChar(char) 逐字符注入，BMP 外字符被拆成两个孤立代理项，
目标应用收到非法序列渲染 U+FFFD。新增 C# UnicodeString() 按 UTF-16 码元注入。
注：KEYEVENTF_UNICODE 扫描码位仅 16 位，代理对必须各自单独发（API 固有限制）。
验证：单测 147 全绿；真机验收 15 通过 / 0 失败 / 1 跳过；双端已部署上线。
另确认中文偶发错字为 IME 上屏竞争，非注入逻辑问题（30 次对照实验全对）。
|
2026-10-04 23:40:25 +08:00 |
|
|
jkooe
|
e95a0248da
|
feat(v19): 拉取式自更新 system.agent.update（42 项）—— 回答「能否直接用 GitHub 做更新服务器」
## 结论：能，而且这是「控制端与被控端不可达」场景的正解
`deploy`（推送式）要求两者可达；本能力只要求**被控端能上网**，因此跨网段/NAT/异地都能更新。
GitHub Release / raw / 自建镜像 / 任意 http(s) 地址均可 —— 地址是参数，不写死。
## 实现（apps/agent/src/capabilities/selfupdate.ts）
下载 → **校验 sha256** → 备份 → **原子替换**（同目录 rename）→ 受控重启（复用 v7）→ CLI 复核指纹
- 出口：CLI `nodeagent update --url <u> --sha256 <h> [--dry-run]` · MCP `na_agent_update`
- 审计新增 `agent.update` 事件（记录 url / 前后指纹 / 字节数 / 备份路径）
## 安全底线（否则等于开放远程代码执行）
1. **sha256 必填**，且逐字节校验通过才替换；不符即丢弃并明确报错（未改动任何文件）
2. 只接受 http/https，拒绝 file:// 等其它 scheme
3. 大小上限 64MB + 下载超时（默认 120s）
4. **先备份再原子替换**，失败可回滚（返回 backup_path）
5. `dry_run` 只下载校验、不动文件 —— 用于「先确认能不能更」
6. 不用 fetch 的内置代理（Node 未暴露 undici）：国内访问 GitHub 不稳时，
把 url 指向**自建镜像/加速地址**即可，能力本身接受任意 http(s)
## 真机/本地验证（全程真跑，非纸面）
- e2e 新增：本地 HTTP 服务真跑下载 —— 正确哈希通过 / **错误哈希被拒** / 404 明确报错 /
非 http(s) scheme 被拒 / 缺 sha256 协议层拒绝 ✓
- 完整流程本地实测：`dry-run 预检` → `真更新`（966KB）→ 备份逐字节一致 → 重启 →
**复核到新指纹** → 能力 42 项 ✓
- 顺带修：返回值漏 `incoming_hash` 导致 CLI 复核被跳过（真机踩过）
- 单测 126 / e2e 28 全绿
## 已知约束（写进文档）
1. **首次仍要一次性安装**（install.ps1）—— 自更新能力本身得先在机器上，鸡生蛋无解
2. `node.exe`（Node 运行时）不在自更新范围，只换 agent.mjs
|
2026-10-04 23:03:37 +08:00 |
|
|
jkooe
|
e6a9a3d7ea
|
feat(v18): 更新链路可靠化 —— 构建指纹 + 备份 + 轮询校验（附 6 个真机 bug 修复）
## 皇上的问题
「这个版本如果有更新，可以在客户端上便捷的更新吗？」
答案：本来就有 `nodeagent deploy`（比最初的一键升级还早），但**它不可信**：
部署后只看「PID 变了 / 能力数对了」，证明不了真的换成了新代码（旧版可能能力数一样），
而且备份与失败判定都存在问题。本轮把这条链路做成**可信**的。
## 新增
1. **构建指纹**：agent 上报 `build.hash`（运行中脚本的 sha256 前 12 位）+ bytes/mtime/node/uptime。
部署后按指纹校验「远端真的是新代码」，而非靠 PID/能力数猜。
2. **`deploy --check`**：只比对指纹不动文件（退出码 2 = 需要更新），适合脚本/巡检。
3. **`deploy --force`**：指纹相同也强制覆盖。
4. **`pnpm update:win [设备名]`**：一条命令完成「打包 → 校验产物确实更新 → 部署」
（脚本刻意防呆：pack 后产物时间戳没变就拒绝部署，避免部署旧包 —— 真机踩过）。
5. **NODEAGENT_DEBUG=1**：CLI 打印异常堆栈（异步链问题必备）。
## 修掉的 6 个真机 bug（本轮逐个实测暴露）
1. **备份用 `Copy-Item`**（Windows 专用 shell 命令）→ macOS 被控端静默不备份。
改为协议自带 fs.read/fs.write，跨平台。
2. **备份读取漏 `encoding: 'base64'`** → 二进制被按 utf8 读（损坏），再当 base64 写回
→ 备份文件只有 33 字节垃圾（实测：`fs.read` 返回 524288 字符而非 base64）。
3. **备份循环用 fs.read 返回的 `offset` 当前进量** → 那是「本次读取的起始位置」，
于是原地打转 → 死循环 + 文件暴涨 + 部署卡死 200s。
改为自算 len（对齐 cmdPush 成熟写法）+ 无进展即跳出。
4. **轮询用 withClient → 直接退出进程**：`withClientDirect` 在连接失败且是 ClientError 时
调 `fail()` 退出 —— 轮询第一次连接必失败（agent 正在重启）→ CLI 立刻退出，
报 E_NODE_OFFLINE，而**部署其实已成功**（本轮 3 次「失败」全是这个假象）。
新增 `probeOnce()`：永不抛出的探测函数，专用于「等待上线/重启」类重试。
5. **盲等 9 秒**判定部署结果 → 改为**按墙钟**限时轮询指纹（90s），失败时报真实耗时。
6. **重启会切断连接**：该中断属预期，此前未处理会把成功误判为失败 → 显式吞掉并说明。
## 验证（本地全程真跑，非纸面）
用「起本地 agent → 造一个改动过的 bundle → 部署」的方式把整条链路跑通：
- 同版本 `--check` → 「已是最新」退出码 0 ✓
- 不同版本 `--check` → 报不一致退出码 2 ✓
- 完整部署 → 备份（979578B，`cmp` 逐字节一致）→ 上传 → 重启 → **指纹校验通过** ✓
- 防呆：文件过小/不存在被拒 ✓
- 单测 125 / e2e 27 全绿
|
2026-10-04 22:54:45 +08:00 |
|
|
jkooe
|
aaf0175e94
|
feat(v17): 音频控制能力 system.audio.get / set（40 -> 41 项）
## 动机
「远程把那台机器静音」是接管场景里的高频小事，此前只能靠 exec 拼脚本，
容易踩本项目已记录的各种坑（C# 转义 / 编码 / 引号）。做成正式能力后一条命令即可。
## 实现
- **Windows**：Core Audio COM（IMMDeviceEnumerator → IAudioEndpointVolume）
—— 可**读回真实状态**，所以是确定性的「设为静音」而不是「切换」
（切换在未知状态下可能反而打开声音）。走项目既有的常驻助手基础设施（label=audio）。
- **macOS**：osascript 原生 `output muted` / `output volume`，零互操作。
## C# 互操作的两个硬约束（已写进文件头注释）
1. **槽位顺序即 vtable 顺序**：接口方法必须按 COM 定义顺序声明，不调用的也要占位。
顺序错了不报编译错，而是调用到错误的内存地址 → 进程崩溃。
（本次：m1..m4 → SetMasterVolumeLevelScalar(5) → m6 → GetMasterVolumeLevelScalar(7)
→ m8..m11 → SetMute(12) → GetMute(13)）
2. **C# 源码必须纯 ASCII**：Add-Type 按系统 ANSI(GBK) 落盘，非 ASCII 会乱码。
## 出口
- CLI：`nodeagent audio [get]` / `nodeagent audio set [--mute on|off] [--volume 0-100]`
- MCP：na_audio_get / na_audio_set
- 参数校验：mute 必须布尔、volume 必须 0-100 整数（越界由 schema 在协议层拒绝）
## 验证
- 单测 124 → 125（新增音频 schema 用例：范围/类型/未知参数）
- e2e 26 → 27：新增音频用例，**macOS 路径已实测**（读回真实 state、写回原值走通写入路径不产生可感知变化）
- ⚠️ **Windows 侧（Core Audio COM）尚未真机验证** —— 被控端重装系统后当前离线，上线后补验
- 顺带修正 e2e 一处断言：空参数属**能力层**失败（返回 failed），越界属**协议层**（抛异常）——
正好把本项目那条契约固化进用例
|
2026-10-02 19:53:46 +08:00 |
|
|
jkooe
|
caa5b8a2c1
|
refactor(cli): 拆分 1977 行的 index.ts 为 11 个模块（纯搬移，零逻辑变更）
## 动机（审查报告 §5.5 / 阿特拉斯报告）
单文件 1977 行难维护、难 review、难以定位改动影响面。本次按职责拆分：
src/index.ts 315 行 入口：参数解析后按子命令调度
src/options.ts 155 行 命令行参数解析（parseArgs）
src/help.ts 75 行 帮助文本
src/types.ts 74 行 共享类型与常量
src/core.ts 236 行 运行时：客户端/守护进程代理/输出工具/--node 覆盖
src/cmd/conn.ts 217 行 连接与设备（connect/keygen/nodes/use/remove/discover）
src/cmd/system.ts 278 行 系统面（info/status/ps/services/exec/restart/audit/metrics/invoke/apps/install）
src/cmd/ops.ts 499 行 自动化（bg/tasks/task/fanout/record/deploy/events/macro/clip）
src/cmd/gui.ts 173 行 图形（screen/screenshot/mouse/key）
src/cmd/fs.ts 172 行 文件（ls/stat/cat/pull/push）
src/cmd/net.ts 116 行 网络两阶段提交
## 拆分中处理的真实工程问题（都不是「机械搬移」能躲过的）
1. **跨模块可变状态**：`--node` 的全局覆盖 `currentNodeOverride` 原来是模块级 let。
ESM 的 import 绑定是只读的，直接 import 后赋值编译不过 → 改为访问器
setNodeOverride()/getNodeOverride()（并把「为什么不能用变量」写进注释）。
2. **散落在函数之间的顶层常量**：CHUNK_BYTES 恰好位于两个函数之间，按函数切分会
误入别的模块 → 归入 types.ts 统一导出。DAEMON_SOCK 同理并去重。
3. 导入按模块职责补齐（parseArgs/getClientConfig 等）。
## 验证
- 构建 6 包全过；单测 124/124；e2e 26/26
- **真机 CLI 冒烟 25 条命令全通过**（CLI 不在 e2e 覆盖内，必须实测）：
info/status/ps/services/ls/metrics/audit/nodes/net status/screen/window.list/tasks/clip/apps/exec
+ push/stat/cat/pull（校验回读内容一致）/screenshot/key type/bg/record/mouse/discover
|
2026-10-01 21:04:24 +08:00 |
|