Hotdry.
归档
ai-systems

Claude Composer 深度解析：多智能体编排与技能链的工程化实现

剖析 Claude Code 的 Agent Teams 与 Skills 机制如何重构开发工作流，涵盖 Lead/Teammate 架构、任务依赖图、SKILL.md 注入链及配置回滚策略。

在处理跨模块重构、并发代码审查或复杂调试时，单一智能体常受困于上下文窗口限制与 “确认偏误”—— 它倾向于坚持最初的理论而忽略反面证据。Claude Code 通过引入 Agent Teams 与 Skills 机制，构建了一个类似交响乐指挥的编排系统。本文将深入这一架构的工程细节，解析其如何实现多智能体并行、跨会话状态同步以及技能的可组合调用。

1. Agent Teams：层级化解耦的编排模型

Agent Teams 的核心设计理念是将 “协调者” 与 “执行者” 分离。与传统的 Subagent 模式（子代理仅向主代理汇报）不同，Teammates 之间可以直接通信，形成了网状协作网络。

1.1 角色定义与权限边界

一个标准的 Agent Teams 包含三类核心组件：

  1. Team Lead：这是用户直接对话的主会话。它负责接收需求、解析任务粒度、生成共享任务列表，并最终合成 Teammates 的产出。Lead 默认拥有完整权限，但在高风险场景下可被限制为Delegate Mode（委托模式）。
  2. Teammates：每个 Teammate 都是一个拥有独立上下文窗口的完整 Claude Code 实例。它们共享项目的 CLAUDE.md、MCP 配置及 Skills，但不继承 Lead 的对话历史。这种设计确保了各执行单元的认知隔离，避免了单一上下文的污染。
  3. Shared Task List：这是一个位于 ~/.claude/tasks/{team-name}/ 的持久化清单。Lead 负责创建任务，Teammates 可以自行认领（Self-claim）或被指派。关键在于任务依赖（Dependencies）：一个被标记为依赖其他任务的任务，在前置任务未完成前将处于 blocked 状态，系统自动管理这一流转过程。

参考来源：Orchestrate teams of Claude Code sessions

1.2 Delegate Mode 与 Plan Approval：防溃坝机制

在大型重构中，让 Lead 直接动手编写代码往往意味着风险集中。Delegate Mode 是一种权限过滤机制：

  • Delegate Mode：通过 Shift+Tab 切换。该模式下，Lead 仅能访问 “协调工具集”：Spawn、Message、TaskManage、Shutdown。它无法执行 Edit、Bash 或任何修改文件系统的操作，迫使其专注于分解与调度。
  • Plan Approval：这是一个显式的质量门禁。在 Spawn Teammate 时，可附加 Require plan approval before they make any changes 指令。Teammate 首先以只读模式生成实现计划，Lead（及用户）审核通过后，Teammate 才退出 Read-only 模式开始编码。这有效防止了 “AI 半夜写完代码，第二天发现全跑偏” 的场景。

2. Skills 架构：可复用的 SOP 流水线

如果说 Agent Teams 是横向的并行扩展，Skills 则是纵向的能力沉淀。它将高频的标准作业程序（SOP）封装为可插拔的模块。

2.1 SKILL.md：Prompt Injection 的载体

一个标准的 Skill 目录结构如下：

skill-name/
├── SKILL.md       # 核心定义（YAML Frontmatter + 指令）
├── scripts/       # 可执行文件（Python, Bash 等）
├── references/   # 参考文档
└── assets/        # 模板文件

YAML Frontmatter 是技能被调用的契约。Claude 通过读取 description 字段来判断是否需要激活该技能。例如：

---
name: code-refactor
description: "Use when user asks for modularizing legacy code or applying SOLID principles."
allowed-tools: "Read,Write,Edit,Glob,Bash(python:run)"
model: "sonnet"
---

当用户需求匹配描述时，Claude 会调用 Skill("code-refactor")。系统随后注入两条消息：一条可见的 Metadata（command-message），以及一条隐藏的完整 Prompt（isMeta: true）。后者包含了 SKILL.md 的全部指令，从而临时修改了 LLM 的行为上下文。

参考来源：Claude Agent Skills: A First Principles Deep Dive

2.2 渐进式披露与链式调用

Skills 的加载采用了 ** 渐进式披露（Progressive Disclosure）** 策略：

  1. Discovery Phase：仅加载 Frontmatter（Name, Description），用于 LLM 判断是否匹配意图。
  2. Invocation Phase：加载完整 SKILL.md，注入指令步骤。
  3. Execution Phase：按需加载 scripts/ 或 references/ 中的资源。

** 链式调用（Chaining）** 发生在 Prompt 层面。开发者可以在一个 SKILL.md 中编排多阶段流程，例如：

Step 1: Run `python analyze.py` to generate dependency graph.
Step 2: Read `output.json` and identify cyclic imports.
Step 3: Use `Edit` tool to decouple modules listed in `cycles.txt`.

这种链式结构不同于 API 层面的函数调用，它是上下文层面的指令拼接，使得多步骤 SOP 能够在一次对话轮次中平顺执行。

3. 跨会话状态管理：Mailbox 与文件锁

多智能体系统的核心挑战在于状态同步。Claude Code 采用了 Mailbox System 结合文件锁来解决此问题。

3.1 Mailbox：异步消息传递

Teammates 之间不共享内存，而是通过 Mailbox 传递消息。消息分为两种：

  • Direct Message：点对点通信，用于请求特定支援或数据。
  • Broadcast：一对多广播，用于同步阶段性结论或变更全局状态。

这种异步机制允许 Teammates 在等待依赖任务时进入 Idle 状态而不阻塞整个系统。当依赖任务完成时，系统会主动推送 Unblock 通知。

3.2 任务认领与文件锁

当多个 Teammates 并行处理不同模块时，极有可能出现写冲突。Task List 机制引入了文件级锁：

  1. Teammate A 认领 src/auth/user.py 的重构任务。
  2. 系统在 ~/.claude/tasks/ 目录下创建锁文件。
  3. Teammate B 尝试认领同一文件时，系统会检测到锁的存在并拒绝其请求，引导其认领其他任务。

这确保了即使在高度并行的场景下，文件系统的一致性也不会被破坏。

4. 工程化落地参数与监控建议

要稳健地在团队中推行此架构，建议关注以下配置阈值与监控点：

  1. 启用开关：Agent Teams 默认关闭，需在 settings.json 中设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。
  2. 成本控制：由于每个 Teammate 拥有独立上下文窗口，Token 消耗是线性的。建议将 Teammate 数量限制在 3-5 个以内，并启用 defaultMode: "delegate" 抑制 Lead 的直接冲动。
  3. 清理策略：每次团队协作结束后，必须执行 cleanup 命令。残留的 tmux panes 或 ~/.claude/teams/ 配置会导致资源泄漏。
  4. 恢复限制：当前 in-process 模式的 Teammates 不支持 /resume 或 /rewind。会话断开后，必须手动重新 Spawn。

资料来源

查看归档