# Claude Composer 深度解析：多智能体编排与技能链的工程化实现 > 剖析 Claude Code 的 Agent Teams 与 Skills 机制如何重构开发工作流，涵盖 Lead/Teammate 架构、任务依赖图、SKILL.md 注入链及配置回滚策略。 ## 元数据 - 路径: /posts/2026/02/07/claude-composer-multi-agent-orchestration-skills/ - 发布时间: 2026-02-07T10:03:14+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 站点: https://blog.hotdry.top ## 正文 在处理跨模块重构、并发代码审查或复杂调试时，单一智能体常受困于上下文窗口限制与“确认偏误”——它倾向于坚持最初的理论而忽略反面证据。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](https://code.claude.com/docs/en/agent-teams) ### 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` 字段来判断是否需要激活该技能。例如： ```yaml --- 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](https://leehanchung.github.io/blogs/2025/10/26/claude-skills-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 中编排多阶段流程，例如： ```markdown 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。 ## 资料来源 * [Orchestrate teams of Claude Code sessions - Claude Code Docs](https://code.claude.com/docs/en/agent-teams) * [Claude Agent Skills: A First Principles Deep Dive - Han Lee](https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/) * [The Complete Guide to Building Skills for Claude - Anthropic](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf) ## 同分类近期文章 ### [NVIDIA PersonaPlex 双重条件提示工程与全双工架构解析](/posts/2026/04/09/nvidia-personaplex-dual-conditioning-architecture/) - 日期: 2026-04-09T03:04:25+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析 NVIDIA PersonaPlex 的双流架构设计、文本提示与语音提示的双重条件机制，以及如何在单模型中实现实时全双工对话与角色切换。 ### [ai-hedge-fund：多代理AI对冲基金的架构设计与信号聚合机制](/posts/2026/04/09/multi-agent-ai-hedge-fund-architecture/) - 日期: 2026-04-09T01:49:57+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析GitHub Trending项目ai-hedge-fund的多代理架构，探讨19个专业角色分工、信号生成管线与风控自动化的工程实现。 ### [tui-use 框架：让 AI Agent 自动化控制终端交互程序](/posts/2026/04/09/tui-use-ai-agent-terminal-automation/) - 日期: 2026-04-09T01:26:00+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 详解 tui-use 框架如何通过 PTY 与 xterm headless 实现 AI agents 对 REPL、数据库 CLI、交互式安装向导等终端程序的自动化控制与集成参数。 ### [tui-use 框架：让 AI Agent 自动化控制终端交互程序](/posts/2026/04/09/tui-use-ai-agent-terminal-automation-framework/) - 日期: 2026-04-09T01:26:00+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 详解 tui-use 框架如何通过 PTY 与 xterm headless 实现 AI agents 对 REPL、数据库 CLI、交互式安装向导等终端程序的自动化控制与集成参数。 ### [LiteRT-LM C++ 推理运行时：边缘设备的量化、算子融合与内存管理实践](/posts/2026/04/08/litert-lm-cpp-inference-runtime-quantization-fusion-memory/) - 日期: 2026-04-08T21:52:31+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析 LiteRT-LM 在边缘设备上的 C++ 推理运行时，聚焦量化策略配置、算子融合模式与内存管理的工程化实践参数。