agent-army

Agent Army

一个 2 层并行执行框架。Commander 是最高级别的模型，默认使用 Fable；如果会话模型是 Opus，则使用 Opus。它负责思考：侦察、规划、简报和验证。它会协调由下级模型组成的集群，用户可在部署时选择这些模型的级别（见 Power Level）。每个 Layer 1 Agent 都拥有自己的完整上下文窗口（而不是一部分）。每个 Agent 都会在自己之下创建 Layer 2 子 Agent。最终，许多独立的大脑可以同时运作，而不是把一个大脑拆分开来。

Commander (you — Fable or Opus, the session model)
 |
 |-- Layer 1: Team (3 to 50+, each = own 1M context, L1 tier from power level)
 |    |-- Agent A (1M) -- Sub-agent A1, A2, ...  (L2 tier)
 |    |-- Agent B (1M) -- Sub-agent B1, B2, ...  (L2 tier)
 |    |-- Agent C (1M) -- Sub-agent C1, C2, ...  (L2 tier)
 |    |-- ... (no cap)

集群与军团： 集群会把一个上下文窗口拆分给多个子 Agent，也就是一个大脑被拆开。军团则让每个 Layer 1 成员都拥有自己的窗口。这正是此技能的全部意义。

适用场景

• 涉及许多文件的大型重构
• 涉及多个文件的颜色、样式、命名或 API 迁移
• 大范围代码库审计（安全性、无障碍性、性能、死代码）
• 批量内容生成或转换
• 任何包含 6 项以上独立工作单元 且可同时运行的任务

不适用场景

• 少于 6 项独立工作单元——直接处理即可
• 存在大量顺序依赖、每一步都需要上一步输出的任务
• 单文件改动
• 需要所有输出保持统一作者风格的任务（并行 Agent 的风格会有偏差）

如果任务不明显符合上述场景，请说明这一点，并建议直接处理，而不是组建军团。

## 强制规则

1. 每个 Layer 1 Agent 都必须创建 2 个或更多子 Agent。没有例外。如果你准备部署一个没有子 Agent 的 L1 Agent，请立即停止并重新规划。
2. 绝不要悄悄缩减军团规模。必须符合用户选择的级别。如果必须偏离，请明确说明原因。 2b. 绝不要悄悄降低模型级别。每次 Agent 调用都必须显式传入用户所选算力级别对应的 model:。省略该参数会继承会话模型，这可能导致 Max Power 费用超出预期。
3. 子 Agent 的部署指示必须写在 Layer 1 简报中。若缺少这些指示，就不会创建子 Agent。
4. Agent 完成时逐一报告：[Agent N/M complete] name: X files modified, Y flags。
5. 部署前须展示军团计划并通过 Deployment Gate（Full Mode）。Quick Mode 会在内部拟定计划，但仍须通过 Gate。
6. 每轮结束后：运行构建，并进行 phantom-completion check（见 Verify）。Agent 报告成功只是声明，并非证明。
7. “继续”/“不要停”表示持续模式：一个 Agent 完成后立即启动新的 Agent。不要等待，也不要再次询问。

军团规模

开始前确认级别。展示此表：

| Tier         | L1 Agents | Total w/ Sub-agents | Est. Tokens  |
|--------------|-----------|---------------------|--------------|
| Conservative | 3         | ~9                  | ~200-500K    |
| Standard     | 5-10      | ~15-30              | ~500K-1.5M   |
| Aggressive   | 10-20     | ~30-60              | ~1.5-4M      |
| Maximum      | 20-50+    | ~60-100+            | ~4M+         |
| Custom       | you pick  | you pick            | varies       |

用户说“直接做”时，默认选择 Standard。侦察完成后（步骤 3），根据发现的情况推荐具体数量，例如：“6 个领域共 35 个文件 → Aggressive：8 个 L1 Agent，每个配 2–3 个子 Agent（总计约 22 个，约 2M tokens）。要调整吗？” Token 估算较为粗略，会随任务复杂度变化。

算力级别

规模决定 Agent 数量；算力决定使用哪些模型。在同一个问题中同时询问这两项（AskUserQuestion 很适用——一次调用中包含规模和算力两个问题）。如果用户已经指定算力级别或明确的模型，则跳过询问。

| Power Level         | Commander          | Layer 1 | Layer 2 | Best For                                        |
|---------------------|--------------------|---------|---------|-------------------------------------------------|
| Max Power           | Fable/Opus (session)| Opus   | Opus    | gnarly refactors, correctness-critical migrations|
| Heavy (recommended) | Fable/Opus (session)| Opus   | Sonnet  | most large tasks — smart orchestration, fast exec|
| Balanced            | Fable/Opus (session)| Sonnet | Sonnet  | mechanical migrations with clear patterns        |
| Economy             | Fable/Opus (session)| Sonnet | Haiku   | high-volume, dead-simple find/replace            |

规则：

• Commander 始终使用会话模型——由用户选择 Fable 或 Opus——且绝不委派。如果会话使用 Sonnet 或 Haiku，请告知用户在部署前切换模型（/model 或 claude --model fable）：Commander 的质量决定了军团质量的上限。
• 每次 Agent 调用都必须显式传入模型：团队成员使用 model: "<L1 tier>"；L1 简报须指示子 Agent 使用 model: "<L2 tier>"。
• 允许按 Agent 提升级别：对于繁重或复杂的文件（1000 行以上、逻辑复杂），可将对应的一个子 Agent 提升一级。须在军团计划中注明升级。
• 审计轮始终使用 Opus，无论算力级别如何——以全新的、更强的视角审查执行者的工作。通知轮可降至 Haiku。

协议

模式： 如果范围已经明确（文件路径、具体更改、层级），则跳到第 3 步（快速模式）。否则从第 1 步开始（完整模式）。

第 1 步：需求收集（完整模式）

如果用户已经提供了上下文，用一行确认：“目标：[X]。范围：[Y]。层级：[Z]。权限：[P]。开始。”否则询问：目标（一句话）、范围（文件/目录/“全部”）、约束（不要改动 X、与 Y 保持一致）、层级和权限级别。

第 2 步：Git 检查点

1. git status — 如果有未提交的更改，发出警告，并询问是否先暂存或提交。
2. git checkout -b agent-army/checkpoint-{timestamp}，然后切回原分支。这是回滚点。
3. 没有 Git 仓库？警告用户没有安全网，并取得明确确认。

第 3 步：侦察

1. 使用 Grep / Glob / Read 查找所有受影响的文件。
2. 统计工作单元数量。
3. 对每个文件运行 wc -l。将 500 行及以上的文件标记为重型 → 指派给单独的 Agent。
4. 按目录、导入关系图、文件类型、命名模式进行领域分类。
5. 找出共享依赖项——跨领域导入的基础文件。先处理这些文件（第 5 步）。
6. 找出构建命令（package.json、Makefile 等）。

输出：Files: N | Heavy: [list] | Domains: [list] | Shared deps: [list] | Build cmd: [cmd]

第 4 步：组建

1. 为共享依赖项安排基础 Agent——在并行批次启动前运行，以免依赖项发生冲突。
2. 第 1 层： 每个领域安排一个 Agent；将大型领域拆分给多个 Agent。
3. 第 2 层： 为每个第 1 层 Agent 安排 2 个或更多子 Agent，按加权文件负载而非文件数量分配：
   • 小型（少于 200 行）：每个子 Agent 负责 2–3 个
   • 中型（200–500 行）：每个子 Agent 负责 1–2 个
   • 重型（500 行及以上）：每个子 Agent 单独负责 1 个
4. 为每个 Agent 命名。将每个文件分配给且仅分配给一个子 Agent——不能重叠，也不能遗漏。

输出 Agent 组建计划。完整模式：暂停并等待“继续？”。快速模式：用一行概述，然后开始执行。

部署检查关卡

开始部署前，必须在回复中输出此检查清单。不要只在心里核对——要明确写出来。

DEPLOYMENT GATE:
[ ] Every L1 brief contains "You MUST spawn N sub-agents"
[ ] Every sub-agent is named with specific files assigned
[ ] Every file is owned by exactly one sub-agent (no overlap, no gap)
[ ] L1 briefs include full sub-agent deployment instructions
[ ] Tier matches the user's selection
[ ] Power level set: model: "<L1 tier>" on every L1 call; L2 tier + escalations in every brief

所有项都必须通过。任何一项未通过 → 先修正计划，再开始部署。

第 5 步：部署

1. 首先启动基础 Agent（如有），层级为第 1 层。等待其完成。
2. 并行启动所有第 1 层 Agent——在同一条消息中的每次调用都设置 run_in_background: true 和 model: "<L1 tier>"。
3. 每个第 1 层 Agent 按其任务说明并行启动第 2 层子 Agent。
4. 汇报每项任务的完成情况：[Agent N/M complete] name: results。

第 6 步：验证

1. 重新扫描——重跑第 3 步中的搜索，检查是否还有未处理的问题。
2. 虚假完成检查——运行 git diff --stat，并与 Agent 报告交叉核对。如果某个 Agent 声称“已完成，修改了 N 个文件”，但没有对应的差异，则说明它在撒谎或没有实际操作——重新指派任务。相信差异，不要只相信报告。
3. 构建——运行构建命令。记录通过或失败。
4. 处理报告中的跨团队问题。
5. 输出 Agent 组报告：

Agents: N | Files modified: N (diff-confirmed) | Skipped: N | Build: PASS/FAIL
Flags: [list] | Phantom completions caught: N | Rollback: git checkout agent-army/checkpoint-{timestamp}

波次

每个波次都是一支规模更小、专业方向不同的新团队。每次开始前都要暂停并征求用户批准。最多 4 个波次。

波次	名称	触发条件	目的
1	执行	始终	进行更改
2	审查	构建失败、仍有违规项、涉及 20 个以上文件，或标记数 > 0	由全新的 Agent 审查第 1 波的正确性和边缘情况
3	推广	更改涉及 API／类型／接口；测试或文档引用了旧模式	更新测试、文档、配置和下游调用方
4	通知	用户选择参与	起草 PR 描述、更新日志和 Slack 摘要

每个波次的报告都是下一波次的侦察依据。每轮之后都要重新运行 Verify；重新扫描无问题且构建通过后停止，或最多运行到第 4 波。

恢复／草稿

对于多波次或可中断的运行，在第 1 波之后写入 .army-state.md：记录已修改的文件（经 diff 确认）、未处理的标记、尚未解决的问题和决策。如果运行被终止，下次调用时会读取此文件，从最近一次通过检查的波次继续，而不是从头开始。单波次任务无需此步骤。

第 1 层提示词模板

这是实际提供给衍生 Agent 的内容，也是该技能中最重要的部分。

You are [AGENT_NAME], specialist on [DOMAIN].

Objective: [one sentence]
Approved patterns: [exact values — hex codes, class names, API shapes]
Forbidden patterns: [what to remove/avoid]
Your files: [absolute paths with line counts]
Rules: [constraints]. Skip files already using approved patterns (idempotency).
Flag issues outside your files in "Flags for Commander" — do NOT fix them.

CRITICAL: You MUST use the Agent tool to spawn the sub-agents listed below. Do
NOT do the work yourself. Do NOT skip spawning. Deploy ALL sub-agents in a single
message with multiple Agent tool calls, passing model: "[L2_TIER]" on every call
[note escalations: except "NAME" which gets model: "[higher tier]"].

Sub-agents:
- "[NAME]": [files with line counts]
- "[NAME]": [files with line counts]

Pass each sub-agent: objective, their files, approved/forbidden patterns, rules,
report format. After all complete, aggregate their reports and verify (by re-reading
or grepping) that no forbidden patterns remain in your domain before reporting back.

第 2 层提示词模板

You are [SUB_AGENT_NAME], working under [TEAM_MEMBER_NAME].

Objective: [one sentence]
Files you own: [absolute paths with line counts — touch only these]
Approved / Forbidden patterns: [exact values to use and remove]
Rules: [constraints]. Skip files already correct. Flag issues outside your files —
do NOT fix them.

Process: read each file fully → check idempotency → apply approved, remove forbidden
→ re-read to confirm no forbidden patterns remain.

Report: Files Modified (file: N replacements), Files Skipped (already correct),
Flags for Commander, Issues, Status (COMPLETE/PARTIAL/FAILED).

报告格式

每个 Agent 都必须返回：

## Report: [Name]
Files Modified:   [file: N replacements]
Files Skipped:    [file: reason]
Flags for Commander: [issue or "None"]
Issues:           [issue or "None"]
Status:           COMPLETE / PARTIAL / FAILED

反模式

这些是此技能旨在防止的问题模式。如果发现自己正在犯其中任何一种，请立即停下并纠正。

• 虚假分派——L1 Agent 不创建子 Agent，而是自己完成工作。这样一来，所有速度优势都会消失。通过强制规则 1 和检查门禁来确保遵守。
• 虚假完成——Agent 未做任何编辑，却报告 COMPLETE。通过 git diff --stat 交叉检查来发现，而不是盲信报告。
• 悄悄缩减规模——用户选择了 Aggressive，却悄悄只运行 3 个 Agent。任何偏离都必须明确说明。
• 模型偏移——Agent 调用时省略 model:，导致所有子 Agent 悄悄继承指挥官所用的模型。用户选择了 Economy，却按 Max Power 计费。通过强制规则 2b 和检查门禁来确保遵守。
• 所有权重叠——两个子 Agent 编辑同一个文件，导致冲突和编辑丢失。通过检查门禁中的唯一所有者规则来确保遵守。
• 跳过基础文件——共享文件尚未更新就修改依赖项，导致一连串导入错误。必须先运行基础文件 Agent。
• 小任务也动用整支团队——用 9 个 Agent 处理 4 个文件会更慢（编排开销更高），还会消耗更多 token。请参阅“何时不应使用”。

错误处理

• 子 Agent 失败 → L1 Agent 重试处理其文件，或创建替代 Agent。
• L1 Agent 失败 → 指挥官使用相同的任务说明创建替代 Agent。
• 构建失败 → 与检查点分支进行 diff，定位问题，然后运行修复波次。
• 虚假完成 → 将该 Agent 负责的文件重新分派给新的 Agent。
• 重跑时的幂等性 → Agent 会先检查相应模式是否已应用，因此重复运行整支团队也不会重复应用更改。

实例

用户：“将整个网站中所有鲜艳的 Tailwind 颜色替换为我们的沙色调色板。”

侦察：45 个文件、5 个领域、2 个共享依赖项（一个主题配置和一个共享的 <Button>）。构建命令：npm run build。建议选择激进模式：1 个基础 Agent + 5 个 L1 Agent，每个配备 2-4 个子 Agent（总计约 22 个）。用户选择了重型配置：Fable 指挥官、Opus L1、Sonnet L2。

**第 1 波（执行）：**基础 Agent 首先更新 2 个共享文件。随后 5 个 L1 Agent 并行部署，每个都分派子 Agent。报告：修改了 43 个文件，跳过 2 个（原本就正确），标记 3 个问题。

验证：git diff --stat 显示有 42 个文件发生更改——有个 Agent 报告了一个它实际并未修改的文件（虚报）。重新派发任务后，确认了 43 个文件。构建通过。仍有 3 个标记问题和 2 个边缘情况违规 → 建议进行审计波次。

**第 2 波（审计）：**3 个全新的 Agent 针对标记的问题文件和违规项开展工作。问题已修复。构建正常，重新扫描也无问题。4 个测试文件导入了已更改的 <Button> → 建议进行传播波次。

**第 3 波（传播）：**3 个 Agent 更新了 4 个测试文件和 1 篇文档。构建依然通过。

**最终结果：**3 个波次，总计约 28 个 Agent，涉及 48 个文件（经差异确认），发现 1 个虚报，剩余违规为零，构建正常。提供回滚分支。