AtomCode v5.0.9 新子系统深度分析 — 子代理与团队系统

基于 strings / 源码路径 / 配置结构体还原的 v4→v5 新增子系统逆向分析 2026-09-09 前置报告：05-version-diff-v4.25.5-to-v5.0.9.md

---

1. 三层子代理架构总览

v5.0.9 建立了三层递进式的委派体系，每一层面向不同的任务形态：

┌─────────────────────────────────────────────────────────────────┐
│  第 3 层 · 外部 Agent 子代理（全新）                              │
│  subagent_<name> 工具 → 独立进程 Codex / Claude Code              │
│  进程隔离 · 无会话上下文 · 只交换最终文本                         │
├─────────────────────────────────────────────────────────────────┤
│  第 2 层 · 团队系统 Team Agent（全新）                            │
│  team 工具 → 持久化团队 · delegate/status/wait/result/stop        │
│  角色路由（read-only vs scoped-write）+ 快/强模型路由              │
├─────────────────────────────────────────────────────────────────┤
│  第 1 层 · 内部子代理（v4 已有，v5 强化）                          │
│  task 工具 → explore/worker 类型 · simple/hard 难度 · role 档案    │
│  并行批量 · 单 JSON payload 发出                                 │
└─────────────────────────────────────────────────────────────────┘

1.1 三层定位差异

维度	内部子代理 (task)	团队 (team)	外部 Agent (subagent_*)
进程	同进程内隔离	同进程内隔离	独立子进程
上下文	无会话上下文	无会话上下文	完全无本会话访问
生命周期	单次批量	持久化，可跨轮存活	单次执行
并发	并行批量	并行 + 状态管理	独立运行
模型路由	simple→快 / hard→强	fast vs capable	各自 Agent 自带模型
能力	explore 只读 / worker 可写	worker 有写作用域	取决于外部 Agent 权限模式

1.2 委派策略的系统提示约束

You can offload subtasks to isolated-context subagents with the `task` tool.
Delegate ONLY when the work is genuinely PARALLEL ... or a BROAD read-only sweep
across many files/locations where you just need the conclusion.
Do NOT spin up a subagent for a SINGLE quick search or read you can do yourself
in one `grep` / `read_file` / `list_directory` call.

default to the fast model otherwise. After a `worker` finishes, REVIEW its diff
before continuing: you own the final result, not the subagent.

→ 强约束模型不轻易派发；worker 产出必须由主模型复核。

---

2. 内部子代理（task 工具）— v5 参数扩展

2.1 完整工具规格（v5 新增/修订）

Dispatch one or more subtasks to isolated subagents. Each task:
  { description, prompt,
    subagent_type: 'explore'|'worker',
    difficulty:   'simple'|'hard',
    model?:        configured_model_id,
    role?:         profile }

'explore' = read-only investigation returning findings
'worker'   = edits files then stops (you review the diff afterward)

Optional roles: architect, reviewer, tester, rust, tui_ux
  → role permission must match subagent_type
'simple' runs on the fast model, 'hard' on the capable model

Subagents run in parallel and cannot themselves dispatch.
The WHOLE batch is emitted as ONE JSON payload, so keep each `prompt` concise
and dispatch in small batches: many long prompts in one call can overflow
the model's output and be rejected as invalid JSON

2.2 新参数项（vs v4）

参数	类型	说明
difficulty	simple / hard	模型档位路由（新增）
model	optional id	显式覆盖档位路由
role	architect/reviewer/tester/rust/tui_ux	角色档案（新增）
scope	string[]（worker 必填）	可写 glob 范围，读不受限

2.3 写作用域机制（新增关键约束）

Worker-only, REQUIRED for worker: working-directory-relative globs
the worker may write within (e.g. ["src/auth/**", "Cargo.toml"]).
The worker can only write files inside this scope; reads are unrestricted.
Ignored for explore.

• worker 必须声明写作用域，否则参数无效
• 写操作被限制在 glob 范围内，读操作不受限
• 配合 team child may not run bash; verification remains owned by the parent agent 的约束，形成写受限 + 无 bash + 父复核的安全三角

2.4 工作目录子代理（新增）

### WORKING DIRECTORY SUBAGENTS

证据确认 v5 引入了专门面向工作目录的子代理变体。

---

3. 团队系统 Team Agent（全新子系统）

3.1 源码模块（全新）

crates/atomcode-capabilities/src/team.rs          ← 工具定义
crates/atomcode-coding/src/team/manager.rs        ← 团队生命周期管理
crates/atomcode-coding/src/team/runner.rs         ← 子任务执行器
crates/atomcode-coding/src/team/tool.rs           ← 工具参数 schema

3.2 工具规格（完整还原）

Run and manage a persistent team of specialized child agents.
Use `delegate` with one or more independent tasks, then `status`, `wait`, or
`result` with the returned run_id; use `stop` to cancel a run.
Roles determine read-only vs scoped-write authority and fast vs capable model
routing. Worker roles require a non-empty working-directory-relative scope
and cannot run Bash.

3.3 子命令面

delegate   ← 派发一个或多个独立任务（至少一个，空则报错）
status     ← 查询运行状态
wait       ← 阻塞等待完成
result     ← 取回结果（按 run_id）
stop       ← 取消运行

辅助字符串：

• team delegate requires at least one task
• internally tagged enum TeamArgs{} → 子命令为内部标记枚举
• run_id / members / agent no report → 返回结构包含运行 id 与成员映射
• invalid team args:

3.4 角色路由矩阵

角色	权限	模型路由	Bash
(默认)	只读	fast	❌
worker	写受限（scope）	capable	❌
专业档案	匹配 subagent_type	—	❌

关键约束字符串：

• team child may not run bash; verification remains owned by the parent agent
• team child, whatever the scope. → 任何 scope 都禁 bash
• worker scope 非空校验：delegate requires at least one task

3.5 与 /team TUI 面板的整合

/team show|hide|status|clear     ← TUI 侧命令
Usage: /team [show|hide|status|clear]
Team panel shown. / Team panel hidden. / Team panel cleared.
## TEAM AGENT:   ← 系统提示注入节
Team Agent role.
Team:            ← 面板标题
SubAgents Team:  ← 进度视图分组

• TUI 提供 /team 控制面板（显隐/状态/清空）
• 面板将内部子代理与团队 Agent 分开展示：Tasks team: / SubAgents team:
• 系统提示注入 ## TEAM AGENT: 段，声明团队角色约束

---

4. 外部 Agent 子代理（最大新增功能）

4.1 源码模块（全新）

crates/atomcode-capabilities/src/subagent/claude_code.rs   ← Claude Code 驱动
crates/atomcode-capabilities/src/subagent/codex.rs         ← Codex 驱动
crates/atomcode-capabilities/src/subagent/proc.rs          ← 子进程管理
crates/atomcode-capabilities/src/subagent/tool.rs          ← subagent_<name> 工具封装
crates/atomcode-coding/src/subagent_tiers.rs               ← 子代理分层

4.2 工具系统提示（完整还原）

One or more `subagent_<name>` tools may be available: each delegates a
self-contained task to an external coding agent (e.g. Codex, Claude Code)
running in a SEPARATE process with NO access to this conversation.
Use one for a well-scoped subtask you want a second agent to handle; pass ONE
detailed, standalone `prompt` that includes all needed context (paths,
constraints, acceptance criteria). Treat the returned text as that agent's
final answer and verify it yourself before relying on it.
Prefer the in-project tools for ordinary work; reach for an external subagent
only when its distinct capability is the point.

→ 对外部 Agent 的定义：独立进程 + 无会话访问 + 返回即终稿 + 主模型复核。

4.3 外部 Agent 挂载方式

subagent.codex    subagent.claude    ← 配置开关（config.toml [subagent] 节）
subagent_<name>                        ← 工具命名规则（<name> = 外部 Agent 名）
ATOMCODE_SUBAGENT                      ← 环境变量总开关
ATOMCODE_SUBAGENT_MAX_ROUNDS           ← 最大轮次

4.4 驱动方式与产物

特征	证据
CLI 风格	Claude Code -p 风格（print 模式）→ 一次性 prompt 输出
Codex 标志	codex-cp（--cp = cwd/prompt?）、codex-out-（输出文件前缀）
输出文件	atomcode-codex-out- 前缀
权限模式	read-only / accept-edits（acceptedits）/ auto / bypass
bypass 限制	bypass permission mode is not allowed in this context（非交互/调度降级 read-only）

4.5 敏感路径防护

subagent may not touch sensitive paths (credentials / ~/.ssh / .env)

→ 外部 Agent 进程级隔离之外，再叠加路径级防护：凭证 / SSH 目录 / .env 被显式排除。

4.6 错误面

codex error:
subagent task crashed:
subagent stopped early
subagent telemetry provider factory is unavailable
subagent model resolver is unavailable
subagent provider slot filled at assemble before any turn

4.7 子代理分层（subagent_tiers.rs）

subagent.max_concurrent  ← 最大并发数
subagent.max_rounds      ← 最大轮次
subagent_tiers.rs        ← 分层路由逻辑
difficulty: simple → fast model
difficulty: hard   → capable model

证据串 subagent provider slot filled at assemble before any turn 显示子代理的模型 provider 槽位在回合组装时填充——即每个子代理回合独立分配 provider。

---

5. 权限与安全模型对比

5.1 三层权限对比

层	写权限	Bash	模型	上下文访问
task explore	❌	❌	fast	无
task worker	限 scope	❌（主模型复核）	capable	无
team worker	限 scope	❌ 硬禁	capable	无
外部 Agent	取决于 permission 模式	取决于模式	自带	无（独立进程）

5.2 主模型角色

所有委派路径共享同一原则：委派者负责最终结果，必须复核子代理产出。

After a `worker` finishes, REVIEW its diff before continuing:
you own the final result, not the subagent.
Treat the returned text as that agent's final answer and verify it yourself
before relying on it.

---

6. 逆向方法论备注

1. 三层子代理的系统提示语是完整的、未模板化的字符串块，可直接提取还原工具契约
2. Internally tagged enum 字符串暴露了 Rust 内部标记枚举（TeamArgs）
3. worker 的 scope 参数以错误信息形式暴露：$; cannot verify it is within scope.`（scope 校验逻辑）
4. 环境变量 ATOMCODE_SUBAGENT* 与 config [subagent] 节对应，构成开关双通道

---

本报告由持续分析循环生成 — v5.0.9 子代理与团队系统深度分析