代理团队
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
> **夜市技能** — 该技能源自 [claude-night-market/conjure](https://github.com/athola/claude-night-market/tree/master/plugins/conjure)。若要全面体验代理、钩子及命令的功能,请安装 Claude Code 插件。
## 目录
- [概述](#overview)
- [使用场景](#when-to-use)
- [先决条件](#prerequisites)
- [协议架构](#protocol-architecture)
- [快速入门](#quick-start)
- [协调工作流程](#coordination-workflow)
- [模块参考](#module-reference)
- [与 Conjure 的集成](#integration-with-conjure)
- [故障排除](#troubleshooting)
- [退出标准](#exit-criteria)
### 代理团队协调
## 概述
Claude Code 代理团队允许多个 Claude CLI 进程通过基于文件系统的协调协议进行协作。每个团队成员都在 tmux 窗口中运行独立的 `claude` 进程,并通过受 `fcntl` 锁保护的 JSON 文件进行通信。无需数据库、守护进程或网络层。
该技能提供了有效管理代理团队的模式。
## 使用场景
- 在多个文件或模块之间进行并行开发
- 多代理代码审查(一个代理负责审查,另一个代理负责实现修复)
- 需要在子系统间协调进行的大型重构
- 具有自然并行性的任务,可以从并发代理中受益
## 不适用场景
- 单个文件的修改或小型任务(开销大于收益)
- 需要严格顺序处理的任务(代理之间的协调较为松散)
- 当 `claude` CLI 未安装或 tmux 未安装时
## 先决条件
```bash
# Verify Claude Code CLI
claude --version
# Verify tmux (required for split-pane mode)
tmux -V
# Enable experimental feature (set by spawner automatically)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
```
## 协议架构
```
~/.claude/
teams/<team-name>/
config.json # Team metadata + member roster
inboxes/
<agent-name>.json # Per-agent message queue
.lock # fcntl exclusive lock
tasks/<team-name>/
1.json ... N.json # Auto-incrementing task files
.lock # fcntl exclusive lock
```
**设计原则:**
- **文件系统作为数据库**:使用 JSON 文件,通过 `tempfile` 和 `os.replace` 实现原子写操作
- **`fcntl` 锁定**:防止对收件箱和任务的并发读写操作导致数据损坏
- **编号任务**:使用自动递增的 ID 和顺序文件命名
- **松耦合**:代理自行轮询收件箱;不使用推送通知
## 快速入门
### 1. 创建团队
```bash
# Programmatic team setup (via MCP or direct API)
# Team config written to ~/.claude/teams/<team-name>/config.json
```
团队配置包含:
- `name`(名称)、`description`(描述)、`created_at`(毫秒级时间戳)
- `lead_agent_id`(团队负责人 ID)、`lead_session_id`(团队负责人会话 ID)
- `members`(数组)——包含 `LeadMember` 和 `TeammateMember` 对象
### 2. 创建团队成员
每个团队成员都是一个独立的 `claude` CLI 进程,启动时会携带身份标志:
```bash
claude --agent-id "backend@my-team" \
--agent-name "backend" \
--team-name "my-team" \
--agent-color "#FF6B6B" \
--parent-session-id "$SESSION_ID" \
--agent-type "general-purpose" \
--model sonnet
```
有关 tmux 窗口管理和颜色分配的详细信息,请参阅 `modules/spawning-patterns.md`。
### 3. 创建带有依赖关系的任务
```json
{
"id": "1",
"subject": "Implement API endpoints",
"description": "Create REST endpoints for user management",
"status": "pending",
"owner": null,
"blocks": ["3"],
"blocked_by": [],
"metadata": {}
}
```
有关状态机和依赖关系管理的详细信息,请参阅 `modules/task-coordination.md`。
### 4. 通过消息进行协调
```json
{
"from": "team-lead",
"text": "API endpoints are ready for integration testing",
"timestamp": "2026-02-07T22:00:00Z",
"read": false,
"summary": "API ready"
}
```
有关消息类型和收件箱操作的详细信息,请参阅 `modules/messaging-protocol.md`。
## 协调工作流程
1. **`agent-teams:team-created`** — 初始化团队配置和目录
2. **`agent-teams:teammates-spawned`** — 在 tmux 窗口中启动代理
3. **`agent-teams:tasks-assigned`** — 创建带有依赖关系的任务并分配负责人
4. **`agent-teams:coordination-active`** — 代理领取任务、交换消息并标记任务完成
5. **`agent-teams:team-shutdown`** — 通过审批协议实现优雅关闭
## 团队角色
每个团队成员都有一个角色,决定了他们的能力和任务兼容性。定义了五种角色:`implementer`(默认)、`researcher`(研究员)、`tester`(测试员)、`reviewer`(审核员)和 `architect`(架构师)。角色限制了代理可以处理的风险等级——有关完整的权限矩阵和角色-风险兼容性表,请参阅 `modules/crew-roles.md`。
## 团队组建
有关任务级别的团队规模建议,请参考 `references/team-formation.md`。其中定义了:
- **角色定义**:协调者(任务负责人)、代理(任务执行者)、审核员(提出挑战者)
- **团队规模建议**:简单(1人)、中等(2-4人)、复杂(5-7人)、关键(5-10人)
- **最大团队规模**:10个代理(协调开销限制)
- **文件所有权规则**:通过明确的所有权规则防止冲突
有关完整的团队规模建议和示例团队组建,请参阅 `references/team-formation.md`。
## 健康监控
可以通过心跳消息和任务有效期来监控团队成员的状态。团队负责人每 60 秒轮询一次团队健康状况,并使用两阶段检测机制(`health_check` 探测 + 30 秒等待)。如果代理停滞不前,其任务将被释放,并根据“替换而非等待”的原则重新分配给其他代理。有关完整协议和状态机的详细信息,请参阅 `modules/health-monitoring.md`。
## 模块参考
- **team-management.md**:团队生命周期、配置格式、成员管理
- **messaging-protocol.md**:消息类型、收件箱操作、锁定模式
- **task-coordination.md**:任务创建/读取/更新/删除(CRUD)、状态机、依赖关系检测
- **spawning-patterns.md**:tmux 窗口管理、CLI 标志、窗口管理
- **crew-roles.md**:角色分类、权限矩阵、角色-风险兼容性
- **health-monitoring.md**:心跳协议、停滞检测、自动恢复
## 与 Conjure 的集成
代理团队扩展了 Conjure 的委托模型:
| Conjure 模式 | Claude Code 代理团队的对应操作 |
|-----------------|----------------------|
| `delegation-core:task-assessed` | `agent-teams:team-created` |
| `delegation-core:handoff-planned` | `agent-teams:tasks-assigned` |
| `delegation-core:results-integrated` | `agent-teams:team-shutdown` |
| 外部 LLM 执行 | 由团队成员代理执行 |
首先使用 `Skill(conjure:delegation-core)` 来判断任务是否适合多代理协调,还是单服务委托。
## Worktree 隔离方案(Claude Code 2.1.49+)
对于修改文件的并发代理,`isolation: worktree` 提供了一种轻量级的替代方案,无需依赖基于文件系统的协调机制。每个代理都在自己的临时 Git worktree 中运行,从而避免了 `fcntl` 锁定或共享文件上的冲突。
- **何时优先使用 worktree**:代理处理重叠文件但不需要执行过程中的通信
- **何时优先使用代理团队通信**:代理需要根据彼此的进度协调发现或调整计划
- **结合使用**:使用代理团队进行协调,并为每个团队成员使用 `isolation: worktree` 以确保文件系统的安全性
## 故障排除
### 常见问题
**找不到 tmux**
通过包管理器安装:`brew install tmux` / `apt install tmux`
**锁文件失效**
如果代理在运行过程中崩溃,锁文件可能会持续存在。请手动删除 `~/.claude/teams/<team>/inboxes/` 或 `~/.claude/tasks/<team>/` 目录下的 `.lock` 文件。
**孤立任务**
被崩溃代理占用的任务会无限期地保持 `in_progress` 状态。请使用 `modules/health-monitoring.md` 中的心跳检测机制自动释放这些任务。健康监控协议会在 60 秒内检测到无响应的代理,并释放其任务以供重新分配。
**消息顺序问题**
文件系统的时间戳解析可能存在差异(HFS+ 的精度为 1 秒)。使用编号文件名或 UUID 排序的文件名以避免在快速发送消息时发生冲突。
**Bedrock/Vertex/Foundry(2.1.39 之前版本)的模型问题**
团队成员代理可能在企业级提供者上使用错误的模型标识符,导致 400 错误。请升级到 Claude Code 2.1.39+ 以确保所有提供者都能正确识别模型 ID。
**嵌套会话问题(2.1.39+)**
如果 `claude` 拒绝在现有会话中启动,请确保使用 tmux 窗口分割(而非子shell 调用)。这种设计是故意的——详情请参阅 `modules/spawning-patterns.md`。
## 退出标准
- 团队已创建并配置完成
- 团队成员已生成并注册到配置中
- 任务已创建并带有依赖关系图(无循环)
- 代理通过收件箱消息进行协调
- 优雅关闭过程已完成
---
> Source: [AgentWorkers/skills](https://github.com/AgentWorkers/skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
章节与文件索引
按说明文件中的顺序排列。
目录
概述
使用场景
不适用场景
协议架构
文件/命令 -> fcntl · tempfile · os.replace · name · description · created_at · lead_agent_id · lead_session_id
内容校验值 -> 85e25382407c
当前原文的自动摘译,尚未人工审校。
目录
概述 使用场景 先决条件 协议架构 快速入门
概述
Claude Code 代理团队允许多个 Claude CLI 进程通过基于文件系统的协调协议进行协作。每个团队成员都在 tmux 窗口中运行独立的
claude进程,并通过受fcntl锁保护的 JSON 文件进行通信。无需数据库、守护进程或网络层。 该技能提供了有效管理代理团队的模式。使用场景
在多个文件或模块之间进行并行开发 多代理代码审查(一个代理负责审查,另一个代理负责实现修复) 需要在子系统间协调进行的大型重构 具有自然并行性的任务,可以从并发代理中受益
不适用场景
单个文件的修改或小型任务(开销大于收益) 需要严格顺序处理的任务(代理之间的协调较为松散) 当
claudeCLI 未安装或 tmux 未安装时协议架构
设计原则: 文件系统作为数据库:使用 JSON 文件,通过
tempfile和os.replace实现原子写操作fcntl锁定:防止对收件箱和任务的并发读写操作导致数据损坏 编号任务:使用自动递增的 ID 和顺序文件命名 松耦合:代理自行轮询收件箱;不使用推送通知