AtomCode v5.0.9 新子系统深度分析 — Skill-First 强制调用与 Subagent 分层派发

基于 strings 系统提示注入 + 工具自描述 + 模块枚举的还原分析 2026-09-09 前置报告：05-version-diff-v4.25.5-to-v5.0.9.md 姊妹报告：31_Subagent_Team_System.md（三层子代理架构）、41_Todo_NextPrompt_SessionTitle.md（提示词注入族）

---

1. 源码模块（v5.0.9 全新）

crates/atomcode-coding/src/
  ├── skill_first.rs          ← Skill-First：系统提示强制 use_skill 优先
  ├── subagent_tiers.rs       ← 难度分层派发（simple/hard 路由 + 角色/写入范围）
  ├── mcp_instructions.rs     ← MCP 工具使用指令面
  └── (controllers.rs / runtime.rs / vision.rs / config.rs / team/*)  ← 同族运行时

→ skill_first.rs + subagent_tiers.rs 是 v5.0.9 在 编码时系统提示注入 层面 新增的两大治理模块（mcp_instructions.rs 为 MCP 侧指令面）。

---

2. Skill-First 强制调用（skill_first.rs）

2.1 MUST 级调用注入（v5.0.9 新增）

check if there is a dedicated skill listed under AVAILABLE SKILLS in the system
  prompt that can fetch it via API.
If this request matches a skill's description shown in that catalog, you MUST call
  `use_skill` with that exact listed name NOW and let it drive. Never infer a skill
  name ...
you MUST load its exact listed name with `use_skill` and follow it BEFORE doing
  the work. Never infer or guess a skill name from the task type or from common sense.
name from AVAILABLE SKILLS or list_skills; never invent a name

→ 三层强制：逐字 MUST +「NOW」立即执行 +「let it drive / BEFORE doing the work」 前置执行。技能名只允许来自 catalog 精确名，禁止推断/臆造。

2.2 负向约束（防误触发）

Never infer a skill name from a design, ideation, planning, or 'help me figure out'
  intent. If no listed description matches, proceed normally without `use_skill`.
Never infer a skill name merely from the task type. If no listed description matches,
  proceed normally without `use_skill`.

→ 显式排除**设计/构想/规划/'帮我理清思路'**意图与「仅凭任务类型」推断； 无匹配 → 正常前进，不调用。

2.3 兜底与失败处理

If no available skill matches, proceed normally.
If `use_skill` reports a missing skill, do not guess another name; briefly note it
  and continue with the best ...

→ 技能缺失时不再猜第二个名字，而是简要注明后继续——封死「技能名猜测循环」。

2.4 技能目录源

=== AVAILABLE SKILLS ===
under '=== AVAILABLE SKILLS ===' in the system prompt or returned by list_skills
List the available skills (name + description). Invoke one with use_skill

→ 目录双来源：系统提示内嵌块 或 list_skills 工具返回值；use_skill 为调用入口。

---

3. Subagent 分层派发（subagent_tiers.rs）

3.1 Dispatch 工具完整契约（工具自描述逐字还原）

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|worker）、难度（simple|hard）、可选模型、 可选角色。这是 v5.0.9 对子代理派发的 结构化 schema（31 号报告的升级版）。

3.2 类型语义

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

→ explore 只读调研；worker 编辑文件后停手交 diff 给主代理审阅。

3.3 难度分层路由

 'simple' runs on the fast model, 'hard' on the capable model.
mark a subtask `hard` only when it genuinely needs the stronger, slower model;
runs on the fast model, 'hard' on the capable model. Give each worker a TIGHTLY-
  specified task and non-overlapping file scopes when dispatching...

→ 难度 → 模型路由：simple → 快模型，hard → 强模型；hard 仅在真实需要时使用。 并强调 TIGHTLY-specified 任务 + 非重叠文件范围（并行写冲突防护）。

3.4 角色面与权限匹配

Optional roles include architect, reviewer, tester, rust, and tui_ux;
the role permission must match subagent_type.

→ 内置 5 角色（架构师/审查者/测试者/rust/tui_ux）；角色权限必须与类型匹配 （如 worker 需要写权限、explore 只读）。

3.5 Worker 写入范围（working directory 夹约束）

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.

→ 写入夹（write scope）：worker 只能写 glob 集内文件（['src/auth/**','Cargo.toml']）， 读取不受限，explore 忽略。这是 worker 隔离的文件级边界。

3.6 校验与覆盖

3-5 word label / The full subtask for the subagent / Optional configured model
  selection id for this subtask; overrides difficulty tier routing
model selection id is empty or contains an invalid character

→ 每条任务必修 label + 完整 prompt；model 显式给定时覆盖难度路由。

---

4. 派发成本纪律（防过度子代理化）

4.1 单次查询不派发

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

4.2 单子代理无收益

a lone subagent adds a slow extra model round for no benefit; just use the tool
  directly. Keep the cross-file reasoning and the final decisions for yourself.
Rules: (1) give each subtask a TIGHTLY-specified prompt ...

4.3 外部子代理只在本征能力时使用

reach for an external subagent only when its distinct capability is the point.
You are a focused EXECUTION subagent. Do exactly the task described ...

→ 三句成本闸：单次 grep 能完成→不派发；单子代理=多一轮模型往返→直接用工具； 外部子代理仅当其独特能力是重点。跨文件推理与最终决策由主代理保留。

---

5. 问题分诊三层（subagent_tiers 多义性）

- Classify every candidate issue into one of three tiers and handle each differently:
... difficulty tier routing ...

→ 同一模块还承载候选问题三档分诊（difficulty tier routing）， 与 3.3 模型路由共用同一 tier 概念。

---

6. 与既有系统的关系

系统	关系
DEEP_ANALYSIS_31 Subagent/Team	31 号还原三层子代理 + Team 架构；本报告为其派发 schema 与治理约束
plugin/skills（26/seed）	技能目录 AVAILABLE SKILLS + use_skill/list_skills 工具契约
DEEP_ANALYSIS_40 ExecutionPolicy	策略注入族（policy-first 强制）与 skill-first 强制同构
ACP v2（32）	subagent_type/role schema 与 ACP 子代理模型对齐
team/{manager,runner,tool}.rs	worker 写入夹正是 Team 工作树隔离的工具级实现

---

7. 逆向方法论备注

1. Dispatch one or more subtasks to isolated subagents. Each task: {description, prompt, subagent_type, difficulty, model?, role?} 一字不漏暴露派发 JSON schema
2. you MUST call \use_skill` with that exact listed name NOW... never infer a skill name` 是 skill-first 强制调用的逐字系统提示（v5.0.9 新增，旧版无）
3. 'simple' runs on the fast model, 'hard' on the capable model 给出难度→模型路由表
4. Worker-only, REQUIRED for worker: working-directory-relative globs 还原 worker 写入夹（src/auth/** 等 globs，读不受限）
5. roles include architect, reviewer, tester, rust, tui_ux 列出内置角色面
6. a lone subagent adds a slow extra model round for no benefit 是派发成本纪律硬证据
7. never invent a name / do not guess another name 封死技能名猜测循环

---

本报告由持续分析循环生成 — v5.0.9 Skill-First 强制调用与 Subagent 分层派发深度分析