AtomCode CLI 与子系统深度分析

持续分析迭代 #1 — CLI 参数完整映射、子系统状态、目录用途分析 2026-06-22

---

1. CLI 入口完整分析

顶级命令

atomcode — 终端中的 AI 编程助手

Usage: atomcode [OPTIONS] [COMMAND]

14 个子命令：

子命令	功能	详细说明
login	通过 AtomGit OAuth 登录	触发浏览器 OAuth 流程，领取 CodingPlan
logout	退出登录	删除 ~/.atomcode/auth.toml
status	查看登录状态	显示当前用户和 CodingPlan 信息
upgrade	就地升级	下载最新发布版本替换自身
rollback	回退到上一个版本	与 .bak 交换（原子操作）
fixissue	AI 修复 AtomGit Issue	获取分配的 issue → agent 自动修复
mcp	管理 MCP 服务器	add/add-github-oauth/login/logout
daemon	启动 HTTP 守护进程	用于 IDE 集成（Web UI + REST API）
webui	启动本地浏览器 webui	调用系统浏览器打开 daemon 页面
telemetry	遥测控制	status/enable/disable/dump/clear
plugin	管理技能/命令插件	marketplace/install/uninstall/list
uninstall	卸载 AtomCode	移除二进制 + PATH 编辑 + 数据
setup	安装种子文件	安装技能/命令/Hooks/MCP 到 ~/.atomcode/
hooks	管理钩子	list/test/paths
help	打印帮助	所有帮助信息

全局选项（15 个）

选项	默认值	说明
--engine	v2 (默认)	引擎选择：v2(新内核)/v1(旧版)，也支持 $ATOMCODE_ENGINE
-c, --continue	无	继续上次会话
--provider <PROVIDER>	配置默认	指定 Provider
--model <MODEL>	配置默认	指定模型
--lang <LANG>	自动检测	语言设置（en/zh-CN/zh）
--config <CONFIG>	默认路径	配置文件路径
-C, --dir <DIR>	当前目录	工作目录
-p, --prompt <PROMPT>	无	非交互模式提示
--prompt-file <PATH>	无	从文件读取提示
-v, --verbose	关闭	显示工具调用、token 用量、回合摘要
--max-turns <MAX_TURNS>	无限制	agent 循环最大 LLM 回合数
--dev	关闭	禁用本次启动的自动更新
--disable-tools <NAMES>	无	逗号分隔要排除的工具
--no-telemetry	关闭	禁用本次调用遥测
-y, --dangerously-skip-permissions	关闭	跳过所有权限提示

关键发现： --engine 选项暗示 AtomCode 有 v2 引擎架构，使用 atomcode-bridge 作为新的内核栈。这是之前未记录的重要架构信息。

---

2. Daemon 子命令详细分析

atomcode daemon [OPTIONS]

Options:
  --port <PORT>                  监听端口 (默认: 13456)
  --client <CLIENT>              Telemetry 客户端标识 (如 "vscode", "atomcode-air")
  --idle-timeout <IDLE_TIMEOUT>  空闲关闭超时秒数; 0=禁用; 默认 1800 (30 分钟)
                                 环境变量 $ATOMCODE_DAEMON_IDLE_TIMEOUT 可覆盖
  --no-telemetry                 禁用遥测

关键发现：

• Daemon 默认 30 分钟空闲超时自动关闭
• --client 选项说明 daemon 可为不同 IDE 集成定制 telemetry 标识
• 空闲超时可通过环境变量 ATOMCODE_DAEMON_IDLE_TIMEOUT 覆盖

---

3. MCP 子系统分析

atomcode mcp <COMMAND>

Commands:
  add               添加/替换 stdio MCP 服务器
  add-github-oauth  添加 GitHub 远程 MCP 服务器（使用 OAuth）
  login             完成远程 MCP 服务器的 OAuth 登录
  logout            移除远程 MCP 服务器的 OAuth 凭证

关键发现：

• 支持两种 MCP 服务器类型：stdio 和 远程 OAuth
• add-github-oauth 功能说明 AtomCode 支持 GitHub 的远程 MCP 协议（即 MCP over OAuth）
• MCP 服务器配置存储在 ~/.atomcode/mcp.json
• 当前无已配置的 MCP 服务器

---

4. 遥测子系统分析

atomcode telemetry <COMMAND>

Commands:
  status   显示遥测状态和队列统计
  enable   启用遥测
  disable  禁用遥测
  dump     打印待发送的队列事件
  clear    清空队列事件

当前状态：

属性	值
状态	disabled (env:ATOMCODE_TELEMETRY=0)
配置	enabled = default-true (config.toml)
队列	空
端点	https://acs.atomgit.com/api/v1/events
Schema 版本	v1

关键发现：

• 配置默认启用遥测（enabled = default-true），通过环境变量禁用
• 上报端点 https://acs.atomgit.com/api/v1/events
• 事件有队列机制（可 dump/clear）
• dump 命令可检查未发送的事件内容（可能包含用户操作信息）

---

5. 插件/市场子系统分析

atomcode plugin <COMMAND>

Commands:
  marketplace  Marketplace registry 操作 (add/remove/update/list)
  install      从已注册的 marketplace 安装插件
  uninstall    卸载已安装的插件
  list         列出已安装插件

当前状态：

• 无已注册的 marketplace
• 无已安装的插件

关键发现：

• 插件市场使用 URL registry 模式，可以添加多个 marketplace 源
• 安装格式: <plugin>@<marketplace>
• 市场列表存储在 ~/.atomcode/marketplaces.json
• 安装的插件列表存储在 ~/.atomcode/installed_plugins.json
• install 命令匹配斜杠命令（slash command）的格式

---

6. Hooks 子系统分析

atomcode hooks <COMMAND>

Commands:
  list   列出所有加载的钩子和状态
  test   测试指定钩子
  paths  显示钩子配置路径

当前状态：

路径	状态
Global: ~/.atomcode/hooks/	✗ 不存在
Project: ./.atomcode/hooks/	✗ 不存在
Global config: ~/.atomcode/hooks/hooks.toml	✗ 不存在
Project config: ./.atomcode/hooks/hooks.toml	✗ 不存在

关键发现：

• 钩子系统是一个 事件驱动的安全层，可在工具调用前后注入逻辑
• 支持事件：pre_tool_use, post_tool_use, session_start, session_end
• 钩子可以返回 allow/block，实现细粒度的权限控制
• 配置方式：独立的 .toml 文件 + 钩子目录（存放脚本）
• 当前无任何钩子，但系统架构已完整就绪

---

7. setup 子系统分析

atomcode setup [OPTIONS]

Options:
  --force  接管过期锁 + 强制重装种子文件

关键发现：

• setup 安装种子文件到 ~/.atomcode/
• 种子文件包括：内置 skills、commands、hooks 模板、MCP 配置模板
• 使用锁机制防止并发（--force 可接管过期锁）
• 这是 ~/.atomcode/ 中初始文件的来源

---

8. Binary 版本差异快照

当前可执行文件版本状态：

属性	主版本	备份版本 (.bak)
大小	28,447,568 字节	28,431,488 字节
MD5	2c4681c66da7a91fbe7fbdf5ed9ffeba	e8149d80ca9dff8ff53e935b40c9a836
大小差	16,080 字节	—
版本	v4.25.3	v4.25.2 (推断)
更新时间	2026-06-20 23:28	2026-06-19 13:59

关键发现：

• 版本发布频率：几乎每天一个版本
• 每次升级前后可执行文件差约 16KB
• rollback 命令设计支持原子性版本回退

---

9. 子命令系统架构总结

atomcode
├── 会话命令
│   ├── login       # OAuth 登录
│   ├── logout      # 登出
│   ├── status      # 状态查询
│   └── daemon      # HTTP 守护进程
│
├── 开发命令
│   ├── fixissue    # AI 修复 Issue
│   ├── setup       # 安装种子文件
│   └── webui       # 打开 Web UI
│
├── 生命周期命令
│   ├── upgrade     # 升级
│   ├── rollback    # 回退
│   └── uninstall   # 卸载
│
├── 配置命令
│   ├── mcp         # MCP 服务器管理
│   ├── hooks       # 钩子管理
│   ├── plugin      # 插件管理
│   └── telemetry   # 遥测控制
│
└── help            # 帮助

架构模式： 命令设计遵循 插件式架构，命令行在多个子系统之间清晰分离，每个子系统有独立的配置管理和生命周期。

---

10. Staged 目录分析

~/.atomcode/staged/ — 目录存在但 完全为空。

属性	值
路径	~/.atomcode/staged/
大小	4096 字节（目录本身）
文件数	0
创建时间	6 月 20 日 23:28

用途推断：

• staged 可能用于暂存准备提交的更改（类似 git staged 概念）
• 可能用于 auto_commit 功能的暂存区（配置中 auto_commit = false）
• 也可能是代码审查/提交功能的工作区
• 当前为空，因为 auto_commit 被禁用

---

11. 安全架构发现

特性	实现
权限系统	-y / --dangerously-skip-permissions — 粒度可配置
引擎隔离	v2 引擎通过 atomcode-bridge 实现内核栈
钩子安全	pre_tool_use 事件可 allow/block 工具调用
Telemetry	独立的启用/禁用 + 队列可查看/清空
锁机制	setup 使用文件锁防止并发操作
MCP 认证	支持 OAuth 远程 MCP 服务器
Token 管理	refresh_token 自动续期

---

12. 下一轮待探索方向

盲区	优先级	方法
fixissue 工作流分析	高	atomcode fixissue --help 和选项
engine v2 架构分析	高	查找 atomcode-bridge 二进制
Rollback 原子性分析	中	测试 rollback 行为
Web UI 子命令分析	中	atomcode webui --help
Uninstall 清理范围	中	atomcode uninstall --help
种子文件内容分析	中	atomcode setup 后检查生成的种子文件

---

本报告由持续分析循环生成 — Iteration #1

逆向命令索引

# 提取所有 CLI 子命令
strings atomcode.bin.bak | grep -E "^  [a-z]+$" | sort -u

# 提取全局选项
strings atomcode.bin.bak | grep -oP '--[a-z-]+' | sort -u | head -20