AtomCodeReverseEngineer

Appearance

AtomCode 深度盲区分析 #8 — 自更新管道协议与细粒度卸载系统 ​

持续分析循环 — 2026-06-24 14:22
发现此前 UPDATE_ANALYSIS.md 和 AGENT_EXECUTION_ENGINE.md 中未覆盖的深层实现细节

1. 自更新管道（Self-Update Pipeline）完整协议 ​

源文件: crates/atomcode-core/src/self_update.rs

1.1 PendingUpgrade 结构体 ​

rust
struct PendingUpgrade {
    // 6 个字段
    staged_path:  PathBuf,       // staged 目录下的新 binary 路径
    sha256:       String,        // 新 binary 的 SHA-256 哈希
    released_at:  String,        // 发布时间戳
    // ... 还有 3 个未命名字段
}

1.2 核心文件清单 ​

文件说明
pending.json待应用的升级信息（序列化的 PendingUpgrade）
history.json历史升级记录
.atomcode.writable-probe可写性探测临时标记文件
notice marker升级通知标记
..atomcode-uninstall.bak卸载备份文件

1.3 更新管道完整阶段 ​

相比现有文档的简略描述，实际管道包含 5 个阶段：

Phase 0: 探测 (Probe)
  binaryself-update probe leftover
  → 检查是否有残留的未完成更新文件

Phase 1: 下载 (Download)
  binaryself-update partial download
  → 下载新 binary 到 staged 目录
  → 保存 pending.json 序列化
  → 验证下载完整性

Phase 2: 校验 (Verify)
  Verifying sha256
  hashing staged binary
  → 计算下载文件的 SHA-256
  → 与 pending.json 中的 sha256 比对

Phase 3: 重命名/替换 (Rename Slot)
  binaryself-update rename slot
  rename failed
  → 将新 binary 重命名为正式位置
  → 原子替换（减少窗口期）
  → 若失败则进入回滚

Phase 4: 清理 (Cleanup)
  binaryself-update backup
  → 备份旧 binary 到 atomcode.bak
  → 清理 staged 目录残留

1.4 升级状态持久化 ​

json
// pending.json 结构
{
  "staged_path": "~/.atomcode/staged/atomcode-v4.25.4-linux-x64",
  "sha256": "a1b2c3d4...",
  "released_at": "2026-06-23T10:00:00Z"
  // 升级状态标志
}

1.5 安全性校验 ​

rust
"staged binary size changed between sessions (expected {})"
"staged binary sha256 drifted between sessions (expected {})"
  • 会话间校验: 如果 staged binary 在会话之间大小或哈希变化，认为是篡改
  • 原子替换: 使用重命名操作而非拷贝，减少崩溃窗口
  • 回滚机制: 失败时恢复备份

1.6 /upgrade 命令完整语法 ​

/upgrade [rollback|--force]

rollback → 回滚到 atomcode.bak
--force  → 跳过版本检查，强制覆盖

1.7 自动更新启停控制 ​

rust
/dev 参数的效果:
  1. Skips applying any staged upgrade
  2. Skips the sync stage+apply on startup
  3. Skips the detached background auto-update

--dev 禁用全部 3 个更新阶段。

1.8 升级失败消息 ​

rust
"Note: pending upgrade could not be applied ({})"
"upgrade failed: {}"
"). Rollback unavailable until next upgrade."
"Re-run with elevated privileges:  sudo atomcode upgrade"

2. 细粒度卸载系统（Uninstall Group System） ​

此前的卸载文档仅描述了 normal/purge/keep-data/dry-run 四种模式，但实际系统远比此复杂。

2.1 三组卸载逻辑 ​

rust
[Group 1] Binary + PATH edit         // 二进制文件 + PATH 修改
  → 默认: yes
  → 移除: 二进制本身、PATH 中的入口、PATH 符号链接
  → 提升: sudo（回退：sudo rm $path）

[Group 2] Credentials and global config  // 凭据和全局配置
  → 默认: no
  → 移除: $ATOMCODE_HOME/config.toml, auth.toml, OAuth tokens
  → 包含: 其他全局配置文件

[Group 3] Local state and extensions     // 本地状态和扩展
  → 默认: yes
  → 移除: 会话数据、插件、MCP 配置、技能、日志、telemetry 队列
  → 注意: "anything installed via either path is visible to both"

2.2 交互式卸载流程 ​

1. -> "Uninstall AtomCode: remove the binary, PATH edit, and (interactively) data
        under ~/.atomcode/. With no flags, runs interactively and asks per-group"
2. -> "This will uninstall AtomCode from your system"
3. -> "WILL REMOVE (sudo)"  ← 提示 sudo 提权
4. -> [Group 1] Remove binary and PATH edit? [Y/n]
     → 拒绝则 "Group 1 declined; aborting (cannot keep binary while removing data)."
5. -> [Group 2] Remove credentials and global config? [y/N]
6. -> [Group 3] Remove local state and extensions? [Y/n]
7. -> Summary: "WILL REMOVE: ... Kept (use --purge to remove later): ..."

2.3 命令行标志 vs 交互式 ​

--yes         → 使用默认决策 (binary=yes, credentials=no, state=yes)
--purge       → "Wipe ~/.atomcode/ entirely"
--keep-data   → "Keep ~/.atomcode/ entirely (only remove binary + PATH edit)"
--dry-run     → "Print the plan; do nothing"

2.4 组合约束 ​

--purge 与 --keep-data 互斥:
  "atomcode uninstall: --purge conflicts with --keep-data"

--yes 使用默认值:
  "Skip prompts; use per-group default decisions (binary=yes, credentials=no, state=yes)"

2.5 卸载后清理文件 ​

..atomcode-uninstall.bak    → 卸载操作备份
# Added by AtomCode installer → 删除 shell rc 中的 PATH 添加行

3. Rollback 回滚系统深入分析 ​

3.1 回滚条件 ​

rust
"Rollback unavailable until next upgrade."
  → 只在执行过一次升级后才可用

3.2 回滚触发点 ​

/upgrade rollback       → 用户主动触发
自动更新失败回滚         → 升级管道失败时自动回退
"upgrade failed: {}"    → 显式失败后触发回滚

3.3 与 staged 目录的关系 ​

rust
"staged binary size changed between sessions (expected)"
"staged binary sha256 drifted between sessions (expected)"

staged 目录在升级管道中的作用:

  1. 新 binary 下载到 staged 目录
  2. 校验完整性
  3. 如果过期会话残留，不信任旧的 staged binary

总结 ​

#盲区此前覆盖本次补充
1自更新管道协议UPDATE_ANALYSIS.md 4 步流程✅ 5 阶段完整协议 (Probe→Download→Verify→Rename→Cleanup)
2PendingUpgrade 结构体仅提名称✅ 完整字段 + JSON 序列化格式
3三组卸载系统仅 4 种模式✅ Group 1/2/3 每个组的默认值 + 交互流程
4卸载约束无✅ --purge/--keep-data 互斥 + Group 1 拒绝 = 中止
5Rollback 条件提及存在✅ 前置条件 "Rollback unavailable until next upgrade"

本报告由持续分析循环生成 — 第 8 轮盲区挖掘

基于 VitePress 构建 · AtomCode v4.25.3 逆向工程分析文档