 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
|
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
|
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 |
|