AtomCode 子代理(Sub-Agent)系统分析
持续深度分析 — 并行文件编辑、子代理调度、合并协议 2026-06-23
1. 子代理系统概览
AtomCode 内置了完整的子代理(Sub-Agent)编排系统，支持将任务分解为并行子任务，每个子代理在隔离上下文中工作。
1.1 SubAgentConfig
rust
struct SubAgentConfig {
initial_turns: u64, // 初始允许回合数
max_turns: u64, // 最大回合数上限
max_concurrent: u64, // 最大并行子代理数
min_duration_secs: u64, // 最小运行时间（秒）
background_only: bool, // 仅在后台运行（焦点感知终端协议）
}TOML 配置形式：
toml
[sub_agent]
initial_turns = 8
max_turns = 16
max_concurrent = 4
min_duration_secs = 10
# background_only 是尽力而为的：焦点感知终端协议尊重它，
# 但传统终端会忽略。2. 子代理工作流
主代理 识别并行文件编辑机会
│
▼
[sub-agent] dispatching <N> sub-agents in parallel...
│
├──── 创建 N 个子代理 ────┤
│ │
▼ ▼
Sub-Agent #1 Sub-Agent #2
assigned file: assigned file:
src/a.rs src/b.rs
instruction: "Add ..." instruction: "Fix ..."
contract: shared types contract: shared types
│ │
▼ ▼
编辑文件 编辑文件
│ │
└────────┬───────────────┘
▼
[sub-agent] dispatch complete
│
▼
构建探测 (build probe)
cargo check / npm run build / mvn compile
│
▼
报告编译错误 → 主代理修复跨文件间隙3. 子代理隔离规则
## SUB-AGENT RULES
- Sub-agents cannot see each other's edits
- Each sub-agent sees only its assigned file content + the contract
- Cross-file changes that aren't expressed in `contract` will be missed
- After all sub-agents settle, the framework runs a build probe
- Build probe surfaces compile errors for cross-file repair3.1 指令格式
javascript
{
"file": "src/agent/mod.rs", // 文件路径
// instruction: 具体的编辑描述
// sub-agent 只看到此指令 + 文件内容 + contract
}
规则:
instruction 不可为空:
"].instruction is empty. Each file needs a concrete edit
description; a sub-agent with no instruction will either
fake an edit or burn its budget."3.2 Contract 机制
Cross-file invariants every sub-agent must honour:
- shared traits
- type signatures
- interface contracts
- naming conventions
Empty if files are fully independent.4. 终止条件
| 条件 | 说明 |
|---|---|
StreamTimeoutAfterRetry | 流超时重试后 |
HallucinationLoop | 检测到幻觉循环 |
ReadsNoProgress | 只读操作无进展 |
idle_turns | 空闲回合超限 |
BudgetExhausted | Token 预算耗尽 |
NoEdits | 未产生任何编辑 |
SubAgentTimeout | 子代理超时（默认 5 分钟） |
ProviderError | 提供商错误 |
JoinError | 子代理合并错误 |
5. 子代理状态跟踪
rust
struct BrokerResponse { // 5 个字段
// 从 broker 系统返回的子代理结果
}
struct ClaimResponse { // 3 个字段
// 子代理任务申领响应
}6. 后台子代理
background_only 配置:
- 当 terminal 支持焦点事件时 → 子代理在后台运行
- 传统终端 → 忽略此设置，在前台运行
子代理后台运行期间:
- 不阻塞主对话
- 完成后通知合并结果
- 用户可继续与主代理交互7. 与 /bg 和 /worktree 的关系
| 特性 | 子代理 (Sub-Agent) | /bg | /worktree |
|---|---|---|---|
| 用途 | 并行文件编辑 | 后台独立任务 | 文件系统隔离 |
| 隔离级别 | 文件可见性 | 会话 | Git worktree |
| 并行度 | max_concurrent(默认4) | 用户控制 | 1 |
| 自动合并 | ✅ 构建探测 | ❌ | ❌ |
| 超时 | SubAgentTimeout(5min) | 无 | 无 |
| 工具集 | 受限(仅编辑指定文件) | 只读-ish | 完全 |
8. 构建探测 (Build Probe)
所有子代理完成后:
1. 探测项目类型:
- cargo check (Rust)
- npm run build (Node.js)
- mvn compile -q (Java)
- go build ./... (Go)
2. 收集编译错误
3. 报告到主代理
4. 主代理修复跨文件问题9. 新覆盖的盲区
| # | 之前未覆盖的领域 | 状态 | 发现 |
|---|---|---|---|
| 1 | SubAgentConfig 完整字段 | ✅ | 5 个配置字段 |
| 2 | 子代理调度与隔离 | ✅ | 文件可见性隔离 + contract 机制 |
| 3 | 9 种终止条件 | ✅ | SubAgentTimeout(5min), BudgetExhausted 等 |
| 4 | 构建探测流程 | ✅ | cargo/npm/mvn/go 自动检测 |
| 5 | BrokerResponse 结构 | ✅ | 5 字段的子代理结果通信 |
| 6 | background_only 行为 | ✅ | 焦点感知终端协议 |
| 7 | 并行编辑指令格式 | ✅ | file + instruction + contract |
本报告由持续分析循环生成
逆向命令索引
bash
# 提取 SubAgentConfig
strings atomcode.bin.bak | grep -iE "SubAgentConfig|initial_turns|max_turns|max_concurrent|min_duration_secs|background_only" | sort -u
# 提取并行编辑结构体
strings atomcode.bin.bak | grep -E "struct ParallelEditArgs|struct ParallelEditFile" | sort -u
# 输出: struct ParallelEditArgs with 2 elements struct ParallelEditFile with 2 elements