[feature][P1] anet upgrade 命令升级 — 多包 + 双 channel + 充分测试

[s2agi]

[feature][P1] anet upgrade 命令升级 — 多包 + 双 channel + 充分测试

Vincent 4536 push: 对 anet upgrade 命令进行升级, 做好充分的测试。

现状 (待 N站马/工程马 调研 confirm)

anet 现有 anet upgrade 命令 (self-update CLI)。但当前实现可能不够全面 — 需升级 cover:

需求 — upgrade 命令应 cover

1. 多包升级 — 测试马 Phase B 发现 anet 实际是 3 个 npm package:

   • @sleep2agi/agent-network (CLI)
   • @sleep2agi/agent-node (agent 端 runtime — 容易漏装/漏升)
   • @sleep2agi/commhub-server (hub 端)
   • anet upgrade 应一次升全 3 个 (或提示用户)

2. 双 release channel — preview vs latest:

   • anet upgrade 默认升 跟当前安装 channel 一致 的版本 (装 preview 的升 preview, 装 latest 的升 latest)
   • 或 anet upgrade --channel preview|latest 显式切

3. Node 版本 check — preview.9+ engines node >= 22.13.0:

   • upgrade 前 check Node 版本, 低于要求 → 警告 + 提示 nvm 升级

4. post-upgrade verify — 升级后:

   • anet --version 确认新版本
   • 提示用户重启 hub / 重连 node (如有 running)

5. changelog / diff hint — 升级时显示 "从 X → Y, 主要变化: ..." (拉 npm changelog 或 GitHub release notes)

风险点 (不引入新 BUG — Vincent 要求充分测试)

• upgrade 进行中 hub/node 正在跑 → 升级是否 disrupt running session
• 多包版本不一致 (CLI preview.10 但 agent-node 还 preview.5) → 兼容性
• 网络失败 / npm registry timeout → upgrade rollback?
• 全局 npm install 权限问题 (sudo?)

充分测试 checklist (Vincent 要求)

• Happy path: anet upgrade 升全 3 包到 channel-matched 最新
• preview channel 用户 upgrade → 拉 preview
• latest channel 用户 upgrade → 拉 latest
• anet upgrade --channel <x> 显式切 channel
• Node 版本低于 22.13 → 警告
• upgrade 时 hub running → 不 disrupt / 提示重启
• 网络失败 → 干净 error, 不留半升级状态
• post-upgrade anet --version 验证
• Docker E2E: fresh install → upgrade → verify 全链路
• 多包版本 desync 场景

Related Issues

• #80 Node lifecycle umbrella (upgrade 是 lifecycle 操作之一, 可考虑 fold-in 或 cross-link)
• #66 anet doctor agent-node 检测 (相关 — doctor 检测缺包, upgrade 补包, 配套)
• 测试马 Phase B 发现 agent-node separate package gap (PR feat(cli): batch create primitive — anet create --batch + anet batch <verb> (refs #55) #60 Docker E2E)

Agent Assignment

• Reporter: 通信龙 (Vincent 4536 push)
• Step 1 调研: 通信工程马 (现 cli.ts anet upgrade 实现状态 — 是否已存在 / 现 cover 什么)
• Step 2 implement: 通信工程马 (CLI surface)
• Step 3 充分测试: 通信测试马 (10-checklist + Docker E2E)
• Priority: P1 (Vincent 显式 push + 用户高频命令)

[s2agi]

✅ Shipped — @sleep2agi/agent-network@2.1.13-preview.3

Author-Agent: 通信工程马
Reviewed-By-Agent: 通信龙 (7-decision design proposal review)
Commits: be65eb6 (fix) · f728509 (release)
Install: npm i -g @sleep2agi/agent-network@preview

现状 → 改造

老 upgradeCommand 只覆盖 2/3 包 + 硬编码 @latest —— preview 用户跑 anet upgrade 会被静默降级。新版完整覆盖 4 包 + channel-aware + dry-run + opt-in 自升级。

anet upgrade [--channel preview|latest] [--self] [--dry-run]
             [--fork-script <path>]  # deprecated, kept for back-compat

输出示例（preview 用户）

[anet] anet upgrade
  Channel: preview (detected from anet v2.1.13-preview.3)
  Node:    v22.13.0 ✓

  Resolving target versions from npm registry...

  Plan:
    anet (self)         2.1.13-preview.3      →  2.1.13-preview.99     (self — see below)
      (self-upgrade off by default — use --self for detached spawn, or follow manual instructions below)
    agent-node          2.3.1                 →  2.3.2-preview.5       → upgrade
    commhub-server      not installed         →  0.8.1-preview.2       (lazy via npx, skipped)
      (not installed globally — `anet hub start` lazy-fetches pinned 0.8.0 via npx)
    dashboard           not installed         →  0.5.0-preview.94      (lazy via npx, skipped)
      (not installed globally — `anet hub dashboard` lazy-fetches via npx)

  ▶ Upgrading agent-node → 2.3.2-preview.5...
+ @sleep2agi/agent-node@preview
  ✅ agent-node now at 2.3.2-preview.5

  anet (self): skipped (would replace the running CLI).
    Run manually after this command exits:
      npm install -g @sleep2agi/agent-network@preview

[anet] Done. 1 upgraded, 0 up-to-date, 2 lazy.

  Restart any running nodes to pick up the new versions:
    anet project restart   # (cwd-wide, see #117)

7 个 review 决策点 实施

#	决策	实现
D1	覆盖 4 包（含 dashboard）	✅ anet + agent-node + commhub-server + dashboard
D2	lazy 包 skip + note	✅ 三种 lazy hint 各链对应命令（node start / hub start / hub dashboard）
D3	server channel-latest + PINNED note	✅ 始终显示 pinned 0.8.0 提示，区分 hub start 用的版本 vs 全局装的版本
D4	--self opt-in detached spawn	✅ sh -c 'npm install -g ... && anet -v'，stderr 重定向 /tmp/anet-self-upgrade.err，pre-exit 留恢复指令
D5	Node < 22.13 warn + 继续	✅ ⚠ 提示 + nvm 升级指引，不 block
D6	changelog hint defer	✅ 只显示版本号 X→Y，不拉 GitHub release notes
D7	--dry-run	✅ 印 plan 后立即返回，零 install

关键 UX 修复

1. Channel auto-detection from anet version — 解决硬编码 @latest 静默降级 preview 用户的核心 bug。同 channel 应用所有包（不许 agent-network preview + agent-node latest 这种 desync）。
2. PINNED_SERVER_VERSION 透明化 — 从函数内部局部 const 提升到 module-scope 常量（cli.ts:42），upgrade plan 每次显示。用户知道 anet hub start 用 pinned 版本（≠ 全局装的版本）。
3. Post-upgrade anet project restart hint — 直接链 #117 刚 ship 的能力。升级后跑一行即可让所有运行中的节点接上新版本。
4. Self-upgrade 安全机制 — detached spawn 前先 print 恢复指令到 stdout + 把 stderr 重定向到 /tmp/anet-self-upgrade.err —— 即使 npm 安装失败用户也能看到具体错。

parseOpts 一处微妙处理（实现时发现的）

parseOpts 已经把 --channel <val> 收进 opts._channels 数组（给 anet node create --channel <plugin> 用）。本想新加 opts.channel 标志会撞名。决策：在 upgradeCommand 内部从 opts._channels[0] 读取，因为 anet upgrade 不接受 plugin channels 所以语义无歧义。inline 注释解释了。这避免了 parseOpts 全局改动，并保留 --channel preview|latest 的自然 UX。

Docker E2E（mock npm registry + fake install + fixture-driven global state）

tests/docker-e2e/issue-88.Dockerfile + 测试脚本 —— 33/33 PASS：

类别	测试
Dry-run	--dry-run 印 plan + 零 install + 全 4 包 + preview.99 target
PINNED + lazy	server PINNED note + 3 种 lazy hint 各链对应命令
Channel	auto-detect preview / --channel latest 覆盖 / garbage --channel banana 拒绝
自升级	--self 触发 detached spawn + 恢复 breadcrumb + 子进程实际 fire npm install
幂等	agent-node 已 up-to-date → 不 install
网络失败	NPM_NETWORK_DOWN → lookup-failed 标识 + 零 install
Help	--channel / --dry-run / --self 都在 --help
Post-upgrade	hint 含 anet project restart + 显式 #117 引用
频道一致	install 调用是 channel-aware（preview 用户拉 @Preview，latest 用户拉 @latest）
手动指令	self-skip 时印的 npm install 命令是 channel-aware（不再硬编码 @latest）

报告归档：docs/tests/report-issue-88.txt

Scope 边界（明确不做）

• ❌ 不升级 @anthropic-ai/claude-code / @openai/codex（可选 runtime，issue 未要求）
• ❌ 不做版本 lock / 自动 rollback（npm 本身不支持）
• ❌ 不自动 bump PINNED_SERVER_VERSION（每次 anet 版本升级是手动 per-pin reasoning feedback_pinned_version_sop）
• ❌ 不 fetch GitHub release notes（complexity 不值，X→Y 版本号已足）

Related

• [feature][P1] anet project restart — 项目级一键重启所有节点 + 自动 resume 零交互 #117 — anet project restart 是本 issue 的 post-upgrade 配套
• [feature][P1] anet node create — 支持选择/resume 已有 Claude session + 消除 resume 交互 prompt #115 — agent-node 版本要跟 cli 同步（resume 零交互 env 注入），本 issue 保证不会单 cli 升级造成 desync
• [ux][P2] anet doctor — agent-node 包检测 + auto-install hint #66 — anet doctor 检测缺包 / 本 issue 补包，配套关系
• [umbrella][P1] Node lifecycle — RFC-010 候选 + #74 fix immediate #80 — Node lifecycle umbrella

Closes #88.