multi-agent-architecture

多 Agent 架构

在避免上下文溢出的前提下编排多个子 Agent 的设计原则。

核心理念

将 Agent 设计视同招聘：先写职位描述，再转化为架构。定位会影响每个决策。

职位描述法

在编写任何 Agent 代码之前：

1. 编写一份面向人的职位描述（JD）——你希望这个人做什么？需要具备哪些特质？如何判断成功？
2. 找出交接点——哪些时候需要有人检查或升级处理？
3. 定义入职培训——你会给新员工提供什么手册？
4. 转化为 Agent——职位描述的每个部分都对应一个架构元素

职位描述部分	架构元素
职责	Agent 工作流
所需技能	工具权限
成功指标	输出模式
升级条件	错误处理
入职材料	技能/手册

共享文件夹模式

**问题：**10 个以上子 Agent 同时返回详细报告时，编排器的上下文会不堪重负。

**解决方案：**子 Agent 写入临时文件夹 → 下游 Agent 直接读取。

.claude/workspace/
├── phase-1/
│   ├── gmail-analysis.md
│   ├── calendar-analysis.md
│   └── drive-inventory.md
├── phase-2/
│   ├── client-summary.md
│   └── action-items.md
└── manifest.yml

工作流：

1. Orchestrator spawns sub-agents
2. Each sub-agent:
   - Does work
   - Writes report to .claude/workspace/{phase}/{name}.md
   - Returns only: { status: "complete", path: "..." }
3. Downstream agents read prior phase outputs directly
4. Orchestrator reads manifest, not full reports

优点：

• 编排器上下文保持精简
• 子 Agent 能获取完整的上游上下文
• 不会因中继摘要而丢失信息

手册模式

**问题：**大量范围狭窄的技能会导致脆弱性和维护负担。

**解决方案：**使用一本按章节组织的手册，阅读基础内容和相关章节。

skills/project-manager/
├── SKILL.md              # Entry point, routes to chapters
└── references/
    ├── 01-foundation.md  # Who we are, tools, escalation, standards
    ├── 02-daily-ops.md   # Data gathering procedures
    ├── 03-dashboards.md  # Structure, quality checks
    └── 04-onboarding.md  # New client setup

章节结构：

章节	内容
基础	团队、工具、数据源、升级规则、质量标准
领域章节	各职责领域的具体流程

阅读方式：

Sub-agent reads:
1. Foundation chapter (always)
2. Relevant domain chapter(s) (based on task)

上下文预算策略

策略	适用场景
共享文件夹	5 个以上子 Agent，存在 Agent 间依赖
上下文代理	返回冗长结果的研究 Agent
清单文件	编排器只需要状态，而非详情
分块执行	并行处理会造成负担时，采用串行阶段

架构决策树

How many sub-agents?
├── 1-3 → Direct orchestration (return reports to main)
├── 4-10 → Shared folder pattern
└── 10+ → Phased execution with manifest

Do teammates need direct communication?
├── No → Sub-agents (Task tool) — report results back only
└── Yes → Agent Teams — shared task list, inter-agent messaging
    ├── See agent-teams skill for full guide
    └── Best for: parallel review, competing hypotheses, multi-module features

Do sub-agents need each other's output?
├── No → Parallel execution, merge results
└── Yes → Shared folder, dependency ordering

Is orchestrator context a concern?
├── No → Return full reports
└── Yes → Status-only returns + file paths

共享状态变更安全性

当多个 Agent 都能将同一工作项（议题、任务、标签）切换到不同状态时，静默竞态条件会导致重复工作或遗漏状态转换。

三步防护（每次写入状态前都执行）：

1. READ   — Re-fetch current state immediately before mutation (never use cached state)
2. VERIFY — Confirm state matches expected pre-condition
3. WRITE  — Apply transition in a single atomic operation

实现模式：

CURRENT_STATE = fetch_state(item_id)           # live read, not cached
If CURRENT_STATE != EXPECTED_PRE_STATE:
  ABORT — log stale-race, do not mutate
Else:
  apply_transition(item_id, NEW_STATE)         # single atomic call

针对 GitHub 标签：

CURRENT_LABELS = gh issue view {id} --json labels
If EXPECTED_LABEL not in CURRENT_LABELS:
  ABORT — another agent already transitioned this item
Else:
  gh issue edit {id} --remove-label {old} --add-label {new}  # one call

决策表：

场景	操作
状态符合预期	原子地应用转换
状态已处于目标状态	静默跳过（幂等）
状态值与预期不符	中止，记录冲突，不要重试
未找到项目	中止，记录项目缺失

**单次原子调用的重要性：**分开调用 --remove-label 和 --add-label 会产生一个时间窗口，让其他 Agent 读取到处于中间状态的项目。将两者合并到一次 gh issue edit 调用中。

反模式

模式	问题	修正方法
使用斜杠命令编排	工作开始前上下文就已耗尽	移至子 Agent
编排器中继所有上下文	形成瓶颈，丢失信息	使用共享文件夹
每个微任务配置一个技能	脆弱且难以维护	使用手册章节
子 Agent 返回完整报告	10 个以上 Agent 时上下文溢出	仅返回路径

演进路径

大多数多 Agent 系统都会经历以下演进：

1. 斜杠命令——快速起步，随后遇到上下文限制
2. 编排器 + 子 Agent——解决上下文问题，但造成中继瓶颈
3. 共享文件夹——解决中继问题，却暴露出技能碎片化
4. 整合手册——统一知识，便于维护

构建新系统时，可跳过早期阶段。

Agent Teams

当工作者需要彼此直接沟通，而不只是向协调者汇报时，请使用 Agent Teams，而不是子 Agent。Agent Teams 提供共享任务列表、Agent 间消息传递和独立的上下文窗口。

与上述子 Agent 模式的主要区别：

• 队友可以直接互相发送消息（而不只是回复调用方）
• 共享任务列表支持自行认领任务，并可自动解除依赖阻塞
• 每位队友都是拥有独立上下文的完整 Claude Code 会话

何时从子 Agent 升级到 Agent Teams：

• 子 Agent 需要在任务进行中分享发现
• 你需要对抗性辩论或相互竞争的假设
• 需要 3 位以上工作者进行自组织协作

如需完整的设置说明、操作参考和编排模式，请使用 agent-teams 技能。