[options]
```
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--team, -t` | 团队名称 | `"default"` |
| `--agent-name, -n` | 智能体名称 | 自动生成 |
| `--agent-type` | 智能体类型 | `"general-purpose"` |
支持后端：`subprocess`、`tmux`、`wsh`
## 7. Web 可视化界面
Web 界面 (`App.jsx`) 提供实时终端模拟和团队状态可视化：
```jsx
// 团队状态展示
docs-sprint 3 agents active
●
T-001 Build landing page done
●
T-002 Write API docs active
○
T-003 Review & merge blocked
```
资料来源：[website/src/App.jsx:1-50]()
## 8. 数据流架构图
```mermaid
graph TD
subgraph 用户交互
CLI[CLI 命令]
WebUI[Web 界面]
end
subgraph 核心服务
Orchestrator[编排器]
Conductor[调度器]
TeamManager[团队管理器]
end
subgraph 存储层
TaskStore[任务存储]
PlanStore[计划存储]
MessageStore[消息存储]
AgentRegistry[智能体注册表]
end
subgraph 运行时
WSHBackend[wsh 后端]
TMUXBackend[tmux 后端]
SubprocessBackend[子进程后端]
end
CLI -->|命令解析| Orchestrator
WebUI -->|HTTP/WS| Orchestrator
Orchestrator -->|调度任务| Conductor
Orchestrator -->|团队管理| TeamManager
Conductor -->|读写| PlanStore
TeamManager -->|读写| TaskStore
TeamManager -->|读写| MessageStore
TeamManager -->|注册| AgentRegistry
AgentRegistry -->|启动| WSHBackend
AgentRegistry -->|启动| TMUXBackend
AgentRegistry -->|启动| SubprocessBackend
WSHBackend -->|反馈| AgentRegistry
TMUXBackend -->|反馈| AgentRegistry
SubprocessBackend -->|反馈| AgentRegistry
```
## 9. 关键技术特性
### 9.1 智能体类型系统
| 类型 | 说明 | 典型用途 |
|------|------|----------|
| `leader` | 领导者智能体 | 团队协调、任务分配 |
| `general-purpose` | 通用智能体 | 常规开发任务 |
| `researcher` | 研究智能体 | 信息收集与分析 |
| `evaluator` | 评估智能体 | 代码审查、质量把控 |
| `planner` | 规划智能体 | 任务分解与计划制定 |
### 9.2 任务优先级机制
```bash
clawteam task create [options]
--priority, -p 优先级: low | medium | high | urgent
--blocked-by 依赖任务列表
--blocks 阻塞任务列表
```
## 10. 总结
ClawTeam 的架构设计遵循以下核心原则：
1. **模块化解耦**：各子系统（任务管理、消息通信、计划审批）独立运作
2. **多后端兼容**：支持 wsh、tmux、subprocess 等多种运行时环境
3. **状态驱动**：基于文件的状态持久化，支持断点恢复
4. **层级化上下文**：为智能体提供渐进式的上下文注入
5. **审批工作流**：关键决策（如计划、加入、关闭）需经过审批流程
这种架构使 ClawTeam 能够有效地协调多个 AI 智能体，实现复杂的软件开发和协作任务。
---
## Harness 与协调执行器
### 相关页面
相关主题：[系统架构总览](#page-architecture-overview), [团队生命周期管理](#page-team-management)
相关源码文件
以下源码文件用于生成本页说明：
- [clawteam/harness/context_recovery.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/harness/context_recovery.py)
- [clawteam/spawn/wsh_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/wsh_backend.py)
- [clawteam/team/models.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/models.py) - 任务状态与数据模型
- [clawteam/team/tasks.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/tasks.py) - 任务存储与操作
- [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md) - CLI参考文档
# Harness 与协调执行器
## 概述
Harness 是 ClawTeam 项目中负责为 AI Agent 运行时注入上下文、管理团队协作状态、以及协调任务执行的中间层组件。Harness 并非一个单一的模块，而是一组协同工作的子系统的集合，包括上下文恢复（Context Recovery）、契约执行（Contract Execution）、阶段管理（Phases）、策略调度（Strategies）、以及协调器（Orchestrator）。
ClawTeam 的核心定位是**多智能体编排框架**（Agent Swarm Orchestration），而 Harness 则是将这一编排能力落地的关键引擎。它负责：
1. **上下文管理** — 为 Agent 注入团队任务、成员、契约等运行时上下文
2. **契约执行** — 根据预定义的契约（Contract）协调 Agent 行为
3. **阶段控制** — 管理工作流的阶段切换与依赖关系
4. **策略调度** — 根据不同策略选择执行路径和优先级
> 资料来源：[skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)
---
## 核心架构
### 模块组成
Harness 系统主要由以下模块组成：
| 模块 | 路径 | 职责 |
|------|------|------|
| Orchestrator | `clawteam/harness/orchestrator.py` | 全局协调器，管理整体执行流程 |
| Conductor | `clawteam/harness/conductor.py` | 指挥器，负责阶段间的流转控制 |
| Contract Executor | `clawteam/harness/contract_executor.py` | 契约执行器，解析并执行契约条款 |
| Phases | `clawteam/harness/phases.py` | 阶段定义与管理 |
| Strategies | `clawteam/harness/strategies.py` | 策略选择与调度逻辑 |
| Context Recovery | `clawteam/harness/context_recovery.py` | 上下文恢复，为 Agent 注入运行时信息 |
### 系统交互图
```mermaid
graph TD
subgraph Harness核心
O[Orchestrator 协调器]
C[Conductor 指挥器]
CE[Contract Executor 契约执行器]
P[Phases 阶段管理]
S[Strategies 策略调度]
CR[Context Recovery 上下文恢复]
end
subgraph 外部依赖
TS[TaskStore 任务存储]
TM[Team Members 团队成员]
ART[Artifacts 工件存储]
end
O --> C
C --> P
C --> CE
P --> S
S --> CR
CR --> TS
CR --> TM
CR --> ART
O --> TS
CE --> ART
```
> 资料来源：基于 `clawteam/harness/context_recovery.py` 源码结构推断
---
## 上下文恢复机制
上下文恢复（Context Recovery）是 Harness 系统中最贴近 Agent 运行时的组件。它负责在 Agent 启动或任务切换时，将团队状态、任务信息、契约内容等关键上下文注入到 Agent 的执行环境中。
### 核心功能
`ContextRecovery` 类通过分层的方式组织上下文信息，每一层代表不同粒度的团队协作数据：
```python
# 层级结构示意
def _teammate_summary(self, agent_name: str, team_name: str, role: str) -> str:
"""Layer 5: One-liner teammate summaries."""
try:
from clawteam.team.models import TaskStatus
from clawteam.team.tasks import TaskStore
store = TaskStore(team_name)
tasks = store.list_tasks()
# Group by owner, exclude self
owner_status: dict[str, tuple[int, int]] = {}
for t in tasks:
if t.owner and t.owner != agent_name:
done, total = owner_status.get(t.owner, (0, 0))
total += 1
if t.status == TaskStatus.completed:
done += 1
owner_status[t.owner] = (done, total)
```
> 资料来源：[clawteam/harness/context_recovery.py:46-62](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/harness/context_recovery.py)
### 上下文分层
根据源码分析，Context Recovery 至少包含以下几层上下文：
| 层级 | 内容 | 说明 |
|------|------|------|
| Layer 1 | 团队配置 | 团队名称、描述、领导节点 |
| Layer 2 | 成员列表 | 所有团队成员及其状态 |
| Layer 3 | 任务列表 | 当前团队中的所有任务 |
| Layer 4 | 契约内容 | Sprint Contract 等契约条款 |
| Layer 5 | 队友摘要 | 按负责人分组的任务完成情况 |
### 角色特定上下文
上下文恢复支持根据不同角色（Role）提供差异化的上下文信息：
```python
if role == "builder":
# 仅显示该 Builder 的契约
artifacts = self._ctx.artifacts.list_artifacts()
for art in artifacts:
name = art["name"]
if "sprint-contract" in name:
content = self._ctx.artifacts.read(name)
if content and agent_name in content:
return f"### Your Sprint Contract\n```json\n{content[:1000]}\n```"
elif role == "evaluator":
# 显示规范 + 所有契约标准
spec = self._ctx.artifacts.read("spec.md")
lines = []
if spec:
lines.append(f"### Specification\n{spec[:2000]}")
elif role == "planner":
# 显示规范草稿
spec = self._ctx.artifacts.read("spec.md")
if spec:
return f"### Your Spec Draft\n{spec[:2000]}"
```
> 资料来源：[clawteam/harness/context_recovery.py:28-45](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/harness/context_recovery.py)
---
## 契约执行器
契约执行器（Contract Executor）是 Harness 系统中负责解析和执行契约条款的核心组件。契约是 ClawTeam 中定义 Agent 行为规范和任务标准的机制。
### 契约类型
根据 CLI 参考文档，ClawTeam 支持多种类型的消息类型（契约载体）：
| 消息类型 | 说明 | 触发场景 |
|----------|------|----------|
| `message` | 点对点消息 | Agent 间直接通信 |
| `broadcast` | 广播消息 | 向所有成员发布通知 |
| `join_request` | 加入请求 | Agent 申请加入团队 |
| `plan_approval_request` | 计划审批请求 | 提交计划供领导审核 |
| `shutdown_request` | 关闭请求 | 请求某个 Agent 关闭 |
> 资料来源：[skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)
### 契约与任务联动
当一个任务被标记为 `completed` 时，契约执行器会自动解除被其阻塞的任务：
```bash
# 任务更新命令
clawteam task update [options]
# 关键选项
--status, -s # 状态: pending, in_progress, completed, blocked
--add-blocks # 添加阻塞的任务ID
--add-blocked-by # 添加阻塞该任务的任务ID
```
> 资料来源：[skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)
---
## 任务状态模型
Harness 系统依赖一套完整的状态机来管理任务生命周期：
```mermaid
stateDiagram-v2
[*] --> pending: 创建任务
pending --> in_progress: 开始执行
in_progress --> completed: 标记完成
in_progress --> blocked: 被依赖阻塞
blocked --> pending: 依赖解除
completed --> [*]
pending --> blocked: 添加阻塞依赖
```
### 状态定义
| 状态 | 说明 | 自动触发 |
|------|------|----------|
| `pending` | 未开始 | — |
| `in_progress` | 执行中 | — |
| `completed` | 已完成 | 自动解除被阻塞任务 |
| `blocked` | 被阻塞 | — |
> 资料来源：[skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)
---
## 后端执行支持
Harness 系统通过抽象后端（Backend）接口支持不同的 Agent 运行环境。
### 支持的后端类型
| 后端 | 说明 | 使用场景 |
|------|------|----------|
| `subprocess` | 子进程执行 | 本地开发测试 |
| `tmux` | Tmux 会话 | 持久化终端会话 |
| `wsh` | VSCode WebSocket Terminal | VSCode 内置终端 |
### WSH 后端实现
WSH（WebSocket Handler）后端是为 VSCode 环境设计的特殊执行器：
```python
def inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:
"""Best-effort runtime injection into a running wsh block."""
from clawteam.spawn.registry import get_registry
info = get_registry(team).get(agent_name, {})
block_id = info.get("block_id", "") or self._blocks.get(agent_name, "")
if not block_id:
return False, f"wsh block for '{team}/{agent_name}' not found"
if not _is_block_alive(block_id):
return False, f"wsh block '{block_id}' is not alive"
```
> 资料来源：[clawteam/spawn/wsh_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/wsh_backend.py)
### 运行时消息注入
Harness 支持在 Agent 运行时动态注入消息，这对于实时协调和状态同步至关重要：
```python
def list_running(self) -> list[dict[str, str]]:
"""List currently running agents."""
return [
{"name": name, "target": target, "backend": "wsh"}
for name, target in self._blocks.items()
]
```
---
## CLI 集成
Harness 系统的功能通过 CLI 命令向用户暴露。以下是关键命令对照：
### Spawn 命令
```bash
clawteam spawn [options]
# 常用选项
--team, -t # 团队名称 (默认: "default")
--agent-name, -n # Agent 名称 (自动生成)
--agent-type # Agent 类型 (默认: "general-purpose")
```
> 资料来源：[skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)
### 生命周期管理
```bash
# 请求关闭
clawteam lifecycle request-shutdown [--reason TEXT]
# 同意关闭
clawteam lifecycle approve-shutdown
# 拒绝关闭
clawteam lifecycle reject-shutdown [--reason TEXT]
# 空闲通知
clawteam lifecycle idle [--last-task ID] [--task-status STATUS]
```
---
## 数据存储结构
Harness 依赖文件系统存储团队协作数据：
```
~/.clawteam/
├── teams/{team}/
│ ├── config.json # TeamConfig (name, members, leader)
│ └── inboxes/{agent}/ # msg-{timestamp}-{uuid}.json 文件
├── tasks/{team}/
│ └── task-{id}.json # 单个任务文件
└── plans/
└── {agent}-{id}.md # 计划文档
```
> 资料来源：[skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)
---
## 执行流程示例
```mermaid
sequenceDiagram
participant CLI as CLI 用户
participant Harness as Harness 系统
participant TaskStore as TaskStore
participant Agent as Agent 进程
participant Backend as Backend
CLI->>Harness: clawteam spawn tmux claude --team dev
Harness->>TaskStore: 注册 Agent 信息
Harness->>Backend: 创建 tmux 会话
Backend-->>Agent: 启动进程
Agent->>Harness: 请求上下文
Harness->>TaskStore: 获取任务列表
Harness->>Harness: Context Recovery
Harness-->>Agent: 注入上下文
Agent->>Agent: 执行任务
Agent->>Harness: 更新任务状态
Harness->>TaskStore: 持久化状态
```
---
## 总结
Harness 与协调执行器构成了 ClawTeam 智能体编排能力的核心支柱。通过分层设计，Harness 实现了：
- **上下文隔离** — 不同角色获取差异化的运行时信息
- **契约驱动** — 通过契约机制规范 Agent 行为
- **状态同步** — 基于文件系统的可靠状态持久化
- **多后端支持** — 统一的抽象接口支持多种执行环境
这些设计使得 ClawTeam 能够有效地协调多个 AI Agent 在复杂软件项目中的协作工作。
---
## 智能体 Spawn 系统
### 相关页面
相关主题：[Spawn 后端实现](#page-spawn-backends), [团队生命周期管理](#page-team-management)
相关源码文件
以下源码文件用于生成本页说明：
- [clawteam/spawn/base.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/base.py)
- [clawteam/spawn/sessions.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/sessions.py)
- [clawteam/spawn/registry.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/registry.py)
- [clawteam/spawn/prompt.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/prompt.py)
- [clawteam/spawn/adapters.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/adapters.py)
- [clawteam/spawn/wsh_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/wsh_backend.py)
- [clawteam/cli/commands.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/cli/commands.py)
# 智能体 Spawn 系统
## 概述
智能体 Spawn 系统是 ClawTeam 的核心组件之一，负责在团队环境中动态启动、注册和管理外部编码智能体进程。该系统通过抽象化的后端适配器架构，支持多种进程管理方式（tmux、subprocess、WebSocket Handler 等），并与团队身份系统、消息收件箱、任务管理模块紧密协作，使主控智能体能够统一编排分布式编码任务。
Spawn 系统的设计目标：
- 提供统一的智能体进程生命周期管理接口
- 支持多后端运行时（tmux、subprocess、wsh 等）
- 自动注入团队上下文（团队名称、智能体身份、领导节点信息）
- 与会话恢复机制集成，支持断点续传
- 通过注册中心维护运行中智能体的元数据
## 系统架构
### 核心组件关系
```mermaid
graph TD
subgraph "CLI 入口层"
CLI[clawteam spawn 命令]
CMD[commands.py 解析]
end
subgraph "后端适配层"
BASE[base.py - BaseBackend 抽象]
TMUX[TmuxBackend]
SUB[SubprocessBackend]
WSH[WshBackend]
AD[Adapters 适配器]
end
subgraph "会话管理层"
SESS[SessionStore]
CAPT[SessionCapture]
REG[Registry 注册中心]
end
subgraph "上下文注入"
PROMPT[prompt.py - 智能体提示词]
ENV[环境变量注入]
end
CLI --> CMD
CMD --> BASE
BASE --> TMUX
BASE --> SUB
BASE --> WSH
CMD --> AD
CMD --> REG
CMD --> PROMPT
TMUX --> SESS
SUB --> SESS
REG --> SESS
```
### 关键模块职责
| 模块 | 文件路径 | 职责 |
|------|----------|------|
| `BaseBackend` | `clawteam/spawn/base.py` | 定义后端抽象接口 |
| `TmuxBackend` | `clawteam/spawn/adapters.py` | tmux 会话管理实现 |
| `SubprocessBackend` | `clawteam/spawn/adapters.py` | 子进程管理实现 |
| `WshBackend` | `clawteam/spawn/wsh_backend.py` | WebSocket Handler 实现 |
| `SessionStore` | `clawteam/spawn/sessions.py` | 持久化会话状态管理 |
| `Registry` | `clawteam/spawn/registry.py` | 智能体注册与发现 |
| `build_agent_prompt` | `clawteam/spawn/prompt.py` | 生成智能体提示词 |
## 后端适配器架构
### BaseBackend 抽象基类
所有后端必须继承 `BaseBackend` 并实现以下核心方法：
```python
class BaseBackend(ABC):
@abstractmethod
def spawn(self, command: list[str], **kwargs) -> str:
"""启动新智能体进程"""
@abstractmethod
def list_running(self) -> list[dict[str, str]]:
"""列出运行中的智能体"""
@abstractmethod
def inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:
"""向运行中的智能体注入消息"""
```
资料来源：[clawteam/spawn/base.py:1-20]()
### 支持的后端类型
| 后端 | 说明 | 适用场景 |
|------|------|----------|
| `tmux` | 在 tmux 会话中运行智能体 | 长期运行、需要手动调试 |
| `subprocess` | 直接子进程管理 | 短时任务、容器环境 |
| `wsh` | WebSocket Handler 块 | 远程/异步通信 |
Spawn 命令示例：
```bash
clawteam spawn subprocess claude --team dev-team --agent-name builder --agent-type researcher
clawteam spawn tmux claude --team dev-team --agent-name coder
```
资料来源：[clawteam/cli/commands.py:50-60]()
## 注册中心机制
### Registry 模块
`Registry` 提供团队内智能体的注册与查询功能：
```python
from clawteam.spawn.registry import register_agent, get_registry
register_agent(
team_name=team_name,
agent_name=agent_name,
backend="wsh",
block_id=block_id,
pid=pane_pid,
command=list(final_command),
)
```
### 注册信息结构
| 字段 | 类型 | 说明 |
|------|------|------|
| `team_name` | str | 团队名称 |
| `agent_name` | str | 智能体名称 |
| `backend` | str | 后端类型 |
| `block_id` | str | 后端特定标识符 |
| `pid` | int | 进程 ID |
| `command` | list[str] | 启动命令 |
注册后，智能体可通过 `get_registry(team_name)` 查询：
```python
info = get_registry(team).get(agent_name, {})
block_id = info.get("block_id", "")
```
资料来源：[clawteam/spawn/wsh_backend.py:80-90]()
## 会话管理系统
### SessionStore
`SessionStore` 负责持久化管理团队智能体会话状态：
```python
from clawteam.spawn.sessions import SessionStore
session_store = SessionStore(_team)
session = session_store.load(_name)
```
关键功能：
- **会话持久化**：将智能体会话状态写入磁盘
- **会话恢复**：支持智能体断点续传
- **状态查询**：加载历史会话信息
资料来源：[clawteam/spawn/sessions.py:1-30]()
### 会话恢复流程
```mermaid
graph LR
A[加载 SessionStore] --> B{是否存在历史会话?}
B -->|是| C[获取 session_id]
C --> D[build_cli_resume_command]
D --> E[拼接恢复命令]
E --> F[注入 resume 标志]
B -->|否| G[正常启动]
```
```python
if resume:
from clawteam.spawn.session_capture import build_resume_command
session = session_store.load(_name)
if session and session.session_id:
resumed_command = build_cli_resume_command(
command, session.session_id, client=client
)
if prompt:
prompt += "\nYou are resuming a previous session."
```
资料来源：[clawteam/cli/commands.py:100-115]()
## 提示词构建系统
### build_agent_prompt 函数
`prompt.py` 中的 `build_agent_prompt` 函数负责生成智能体的系统提示词，包含团队上下文信息：
```python
from clawteam.spawn.prompt import build_agent_prompt
prompt = build_agent_prompt(
agent_name=_name,
agent_id=_id,
agent_type=agent_type,
team_name=_team,
leader_name=leader_name,
task=task,
user=user_name,
workspace_dir=cwd or "",
workspace_branch=ws_branch,
isolated_workspace=bool(workspace and cwd),
repo_path=repo,
)
```
### 提示词包含的信息
| 参数 | 说明 |
|------|------|
| `agent_name` | 智能体名称 |
| `agent_id` | 智能体唯一标识 |
| `agent_type` | 智能体类型（如 researcher、general-purpose） |
| `team_name` | 所属团队名称 |
| `leader_name` | 团队领导节点名称 |
| `task` | 当前任务描述 |
| `workspace_dir` | 工作目录 |
| `workspace_branch` | Git 分支 |
| `isolated_workspace` | 是否使用隔离工作区 |
| `repo_path` | 仓库路径 |
资料来源：[clawteam/spawn/prompt.py:1-50]()
## 运行时消息注入
### inject_runtime_message 接口
后端实现者必须提供运行时消息注入能力，用于向运行中的智能体发送控制消息：
```python
def inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:
"""Best-effort runtime injection into a running agent."""
from clawteam.spawn.registry import get_registry
info = get_registry(team).get(agent_name, {})
block_id = info.get("block_id", "") or self._blocks.get(agent_name, "")
if not block_id:
return False, f"Agent block for '{team}/{agent_name}' not found"
if not _is_block_alive(block_id):
return False, f"Block '{block_id}' is not alive"
```
返回值：`tuple[bool, str]` - 成功/失败状态及消息
资料来源：[clawteam/spawn/wsh_backend.py:95-115]()
## CLI 命令集成
### Spawn 命令参数
```bash
clawteam spawn [options]
```
| 参数/选项 | 说明 | 默认值 |
|-----------|------|--------|
| `backend` | 后端类型（subprocess/tmux） | 必需 |
| `command` | 智能体启动命令 | 必需 |
| `--team, -t` | 团队名称 | "default" |
| `--agent-name, -n` | 智能体名称 | 自动生成 |
| `--agent-type` | 智能体类型 | "general-purpose" |
### 完整示例
```bash
# 在 tmux 后端启动 researcher 类型智能体
clawteam spawn tmux claude --team dev-team --agent-name researcher --agent-type researcher
# 在 subprocess 后端启动通用智能体
clawteam spawn subprocess claude-code --team dev-team --agent-name builder
# 使用特定工作目录
clawteam spawn tmux claude --team docs-team --agent-name writer \
--workspace-dir /home/user/project --workspace-branch feature/docs
```
资料来源：[clawteam/cli/commands.py:45-75]()
## 智能体生命周期
```mermaid
graph TD
A[Spawn 命令] --> B[注册到 Registry]
B --> C[创建 Session]
C --> D[构建 Prompt]
D --> E[调用后端 spawn]
E --> F{后端类型}
F -->|tmux| G[创建 tmux session]
F -->|subprocess| H[fork 子进程]
F -->|wsh| I[创建 wsh block]
G --> J[启动智能体]
H --> J
I --> J
J --> K[智能体运行中]
K --> L[可接收消息注入]
K --> M[可更新任务状态]
L --> N[生命周期结束]
M --> N
```
## 数据存储布局
Spawn 系统相关的持久化数据存储在 `~/.clawteam/` 目录下：
```
~/.clawteam/
├── teams/{team}/
│ ├── config.json # 团队配置
│ └── inboxes/{agent}/ # 智能体收件箱
├── sessions/{team}/
│ └── {agent}.json # 会话状态文件
└── registry/
└── {team}.json # 智能体注册信息
```
## 与其他模块的交互
### 团队模块集成
Spawn 系统依赖团队模块提供的领导节点信息：
```python
# 获取团队领导名称
tmpl = load_template("default")
leader_name = tmpl.leader.name
# 判断当前智能体是否为领导
is_leader = agent.name == tmpl.leader.name
```
### 任务模块集成
Spawn 后的智能体可更新任务状态：
```bash
clawteam task update dev-team --status completed
```
### 生命周期模块集成
智能体完成任务后可发送空闲通知：
```bash
clawteam lifecycle idle dev-team --last-task --task-status completed
```
## 扩展新的后端
如需添加新的后端（如 Docker、Kubernetes），需：
1. 继承 `BaseBackend` 抽象类
2. 实现 `spawn`、`list_running`、`inject_runtime_message` 方法
3. 在 `adapters.py` 或独立文件中实现
4. 在 CLI 命令解析中注册新后端
```python
class DockerBackend(BaseBackend):
def spawn(self, command: list[str], **kwargs) -> str:
container_id = self._create_container(command, **kwargs)
return f"Agent spawned in container {container_id}"
def list_running(self) -> list[dict[str, str]]:
# 返回运行中的容器
pass
def inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:
# 向容器内进程发送信号
pass
```
## 最佳实践
1. **使用 tmux 后端进行调试**：tmux 后端支持手动 attach 查看智能体输出
2. **使用 subprocess 后端进行 CI/CD**：适合无头环境
3. **充分利用会话恢复**：长时间任务建议使用 `--resume` 标志
4. **正确设置智能体类型**：有助于团队任务分配和资源调度
5. **配合任务系统使用**：Spawn 后立即创建任务并分配给智能体
## 总结
智能体 Spawn 系统是 ClawTeam 实现多智能体协作的基础设施，通过模块化的后端适配器、统一的注册中心、持久化的会话管理和智能的提示词注入，使得主控节点能够灵活地启动、管理和协调各类外部编码智能体。该系统的设计遵循开闭原则，便于扩展新的运行时后端，同时与团队管理、任务调度、消息通信等模块无缝集成，共同构建完整的智能体编排平台。
---
## Spawn 后端实现
### 相关页面
相关主题：[智能体 Spawn 系统](#page-spawn-system)
相关源码文件
以下源码文件用于生成本页说明：
- [clawteam/spawn/wsh_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/wsh_backend.py)
- [clawteam/spawn/registry.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/registry.py)
- [clawteam/spawn/sessions.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/sessions.py)
- [clawteam/spawn/session_capture.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/session_capture.py)
- [clawteam/cli/commands.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/cli/commands.py)
# Spawn 后端实现
## 概述
Spawn 后端是 ClawTeam 系统中负责在团队环境中启动和管理外部 AI Agent 进程的核心组件。它提供了一套统一的抽象接口，支持多种底层进程管理方式（如 tmux、subprocess、wsh），使团队协调层能够独立于具体执行后端工作。
Spawn 模块的职责包括：
- 为新启动的 Agent 注入团队身份环境变量（`CLAWTEAM_AGENT_ID`、`CLAWTEAM_AGENT_NAME`、`CLAWTEAM_TEAM` 等）
- 管理 Agent 的生命周期（启动、监控、终止）
- 支持会话恢复（session resume）功能
- 与模板系统（Template）集成，支持批量启动团队成员
资料来源：[clawteam/cli/commands.py:1-50]()
## 架构设计
### 整体架构图
```mermaid
graph TD
subgraph "CLI 层"
CLI[clawteam spawn 命令]
Launch[clawteam launch 命令]
end
subgraph "Spawn 核心"
Registry[Agent 注册表]
SessionStore[会话存储]
PromptBuilder[提示词构建]
end
subgraph "后端实现层"
TMuxBackend[tmux_backend.py]
SubprocessBackend[subprocess_backend.py]
WshBackend[wsh_backend.py]
end
subgraph "底层执行"
TMux[tmux 会话]
Process[子进程]
WshBlocks[wsh blocks]
end
CLI --> Registry
CLI --> PromptBuilder
Launch --> TMuxBackend
Launch --> SubprocessBackend
Launch --> WshBackend
TMuxBackend --> TMux
SubprocessBackend --> Process
WshBackend --> WshBlocks
Registry --> SessionStore
```
### 后端抽象基类
Spawn 系统采用后端插件化设计，所有后端需实现统一的接口：
| 方法 | 功能 | 返回值 |
|------|------|--------|
| `spawn(command, team, agent_name, ...)` | 启动 Agent 进程 | 启动结果描述字符串 |
| `list_running()` | 列出运行中的 Agent | `List[Dict[str, str]]` |
| `inject_runtime_message(team, agent, envelope)` | 向运行中的 Agent 注入消息 | `(bool, str)` |
资料来源：[clawteam/spawn/wsh_backend.py:30-60]()
## tmux 后端实现
tmux 后端通过创建独立的 tmux 会话来隔离每个 Agent 的运行环境。
### 核心流程
1. 构建 tmux 命令，包含会话命名和窗口配置
2. 使用 `tmux new-session` 创建新会话
3. 向新会话发送 Agent 启动命令
4. 注册 Agent 信息到全局注册表
5. 持久化会话捕获数据
### 会话隔离策略
每个 Agent 在独立的 tmux 会话中运行，会话命名格式为 `clawteam-{team}-{agent}`。这种隔离确保：
- 一个 Agent 的输出不会干扰其他 Agent
- 可以独立 attach/detach 到特定 Agent 会话
- Agent 崩溃不会影响团队其他成员
资料来源：[clawteam/spawn/session_capture.py]()
## subprocess 后端实现
subprocess 后端直接通过 Python 的 `subprocess` 模块启动子进程，适合轻量级或无持久化需求的场景。
### 特性
- 支持 stdout/stderr 管道捕获
- 可配置工作目录（CWD）
- 支持环境变量注入
- 适合短生命周期任务
## wsh 后端实现
wsh（WezTerm Shell）后端是 ClawTeam 针对 WezTerm 终端仿真器的专用实现，利用 WezTerm 的 pane 和 RPC 功能实现高级交互。
### WshBackend 核心功能
```python
class WshBackend:
def spawn(self, ...) -> str:
"""启动 wsh block 中的 Agent"""
def list_running(self) -> list[dict[str, str]]:
"""列出当前运行的 wsh block"""
def inject_runtime_message(self, team, agent_name, envelope) -> tuple[bool, str]:
"""向运行中的 wsh block 注入运行时消息"""
```
资料来源：[clawteam/spawn/wsh_backend.py:1-100]()
### RPC 消息注入
wsh 后端支持向已启动的 Agent 实时注入消息，流程如下：
```mermaid
sequenceDiagram
participant CLI as CLI 命令
participant Registry as Agent 注册表
participant WshRPC as WshRpcClient
participant Block as wsh Block
CLI->>Registry: 查询 agent 对应的 block_id
Registry-->>CLI: block_id
CLI->>WshRPC: inject_runtime_message(envelope)
WshRPC->>Block: 发送渲染后的通知
Block-->>WshRPC: 确认
WshRPC-->>CLI: (True, "success")
```
资料来源：[clawteam/spawn/wsh_rpc.py]()
## Agent 注册与追踪
### 注册表机制
ClawTeam 使用集中式注册表管理所有已启动的 Agent 实例：
```python
register_agent(
team_name=team_name,
agent_name=agent_name,
backend="wsh",
block_id=block_id,
pid=pane_pid,
command=list(final_command),
)
```
注册信息包括：
| 字段 | 说明 |
|------|------|
| `team_name` | 团队名称 |
| `agent_name` | Agent 标识符 |
| `backend` | 使用的后端类型 |
| `block_id` | 后端特定资源标识 |
| `pid` | 进程 ID |
| `command` | 启动命令 |
资料来源：[clawteam/spawn/registry.py]()
### 会话持久化
Spawn 模块支持会话捕获和恢复：
```python
persist_spawned_session(
session_capture,
team_name=team_name,
agent_name=agent_name,
command=list(final_command),
)
```
会话存储允许：
- 保存 Agent 的完整命令历史
- 支持后续会话恢复（resume）
- 记录 Agent 状态快照
资料来源：[clawteam/spawn/sessions.py]()
## 与其他模块的集成
### 与模板系统集成
Spawn 与模板系统（`clawteam/templates/`）深度集成，支持通过模板定义团队结构：
```python
# 从模板加载后，使用 spawn 批量启动
spawned.append({
"name": agent.name,
"id": a_id,
"type": agent.type,
"result": spawn_result
})
```
资料来源：[clawteam/templates/__init__.py]()
### 与 CLI 命令集成
Spawn 功能通过 `clawteam spawn` 和 `clawteam launch` 命令暴露给用户：
| 命令 | 功能 |
|------|------|
| `clawteam spawn ` | 启动单个 Agent |
| `clawteam launch --template ` | 从模板启动整个团队 |
参数配置：
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--team, -t` | `"default"` | 团队名称 |
| `--agent-name, -n` | 自动生成 | Agent 名称 |
| `--agent-type` | `"general-purpose"` | Agent 类型 |
资料来源：[clawteam/cli/commands.py]()
## 会话恢复机制
### Resume 流程
Spawn 模块支持从上次中断点恢复 Agent 会话：
1. 检测 `--resume` 参数
2. 从 SessionStore 加载历史会话数据
3. 根据原始客户端类型构建恢复命令
4. 注入会话 ID 和客户端标识
```python
if resume:
session = session_store.load(_name)
if session and session.session_id:
resumed_command = build_cli_resume_command(command, session.session_id, client=client)
prompt += "\nYou are resuming a previous session."
```
资料来源：[clawteam/spawn/sessions.py]()
## 配置选项
### Spawn 启动参数
| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `backend` | str | `"tmux"` | 进程后端类型 |
| `command` | List[str] | `["claude"]` | Agent 启动命令 |
| `team_name` | str | `"default"` | 团队名称 |
| `agent_name` | str | None | Agent 标识 |
| `agent_type` | str | `"general-purpose"` | Agent 类型 |
| `profile` | str | None | 使用的运行时配置 |
| `skill` | List[str] | None | 加载的技能列表 |
| `workspace` | str | None | 工作空间目录 |
| `skip_permissions` | bool | False | 跳过权限检查 |
### 环境变量注入
Spawn 自动向启动的 Agent 注入以下环境变量：
| 变量名 | 说明 |
|--------|------|
| `CLAWTEAM_AGENT_ID` | 唯一 Agent 标识符 |
| `CLAWTEAM_AGENT_NAME` | Agent 显示名称 |
| `CLAWTEAM_AGENT_TYPE` | Agent 类型 |
| `CLAWTEAM_TEAM` | 所属团队名称 |
| `CLAWTEAM_LEADER_ID` | 团队 Leader ID |
## 扩展新的后端
要添加新的 Spawn 后端，需实现以下接口：
```python
class BaseBackend:
def spawn(
self,
command: List[str],
team_name: str,
agent_name: str,
**kwargs
) -> str:
"""启动 Agent 进程，返回启动描述"""
raise NotImplementedError
def list_running(self) -> List[Dict[str, str]]:
"""返回运行中的 Agent 列表"""
raise NotImplementedError
def inject_runtime_message(
self,
team: str,
agent_name: str,
envelope
) -> tuple[bool, str]:
"""向运行中的 Agent 注入消息"""
raise NotImplementedError
```
注册新后端时，需要在 `clawteam/spawn/backends.py` 中添加入口点映射。
---
## 团队生命周期管理
### 相关页面
相关主题：[任务管理与依赖链](#page-task-dependencies), [智能体间消息通信](#page-messaging), [智能体 Spawn 系统](#page-spawn-system)
相关源码文件
以下源码文件用于尝试生成本页说明：
- [clawteam/team/manager.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/manager.py) ⚠️ 未在当前上下文检索到
- [clawteam/team/lifecycle.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/lifecycle.py) ⚠️ 未在当前上下文检索到
- [clawteam/team/models.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/models.py) ⚠️ 未在当前上下文检索到
- [clawteam/team/leader_watcher.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/leader_watcher.py) ⚠️ 未在当前上下文检索到
- [clawteam/team/snapshot.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/snapshot.py) ⚠️ 未在当前上下文检索到
**注意**：以下页面内容基于实际检索到的源码文件生成，而非上述指定文件。
以下源码文件实际用于生成本页说明：
- [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)
- [skills/clawteam/references/workflows.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/workflows.md)
- [clawteam/team/tasks.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/tasks.py)
- [clawteam/spawn/wsh_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/wsh_backend.py)
- [clawteam/cli/commands.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/cli/commands.py)
# 团队生命周期管理
## 概述
ClawTeam 的团队生命周期管理是一个多代理协作框架，负责协调代理（Agent）的创建、任务分配、团队治理和优雅关闭的全过程。该系统通过 CLI 命令驱动，支持任务依赖链、会话持久化和基于消息的代理间通信。
**核心职责范围：**
- 团队的创建、发现和状态监控
- 代理的 Spawn（生成）与注册
- 任务的创建、更新和依赖管理
- 团队成员间的消息传递与计划审批
- 优雅关闭流程（Graceful Shutdown）
- 领导选举与心跳监控
**资料来源：** [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)
---
## 团队创建与发现
### 创建团队
使用 `spawn-team` 命令创建一个新团队并注册领导者代理：
```bash
clawteam team spawn-team [options]
```
| 参数/选项 | 说明 | 默认值 |
|-----------|------|--------|
| `name` | 团队名称 | 必填 |
| `--description, -d` | 团队描述 | `""` |
| `--agent-name, -n` | 领导者代理名称 | `"leader"` |
| `--agent-type` | 领导者代理类型 | `"leader"` |
**示例：**
```bash
clawteam team spawn-team dev-team -d "Backend development team" -n alice
```
该命令会创建团队配置文件，并将指定代理注册为团队领导者。
### 发现团队
列出所有现有团队及其元数据：
```bash
clawteam team discover
clawteam --json team discover
```
返回每个团队的名称、描述、领导代理 ID 和成员数量。
**资料来源：** [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)
---
## 代理生命周期
### Spawn 代理
Spawn 命令用于在新进程中启动代理，并自动注入团队环境变量：
```bash
clawteam spawn [options]
```
| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--team, -t` | 团队名称 | `"default"` |
| `--agent-name, -n` | 代理名称 | 自动生成 |
| `--agent-type` | 代理类型 | `"general-purpose"` |
**支持的后端：**
| 后端 | 说明 |
|------|------|
| `subprocess` | 子进程模式 |
| `tmux` | tmux 会话模式 |
**示例：**
```bash
clawteam spawn subprocess claude --team dev-team --agent-name bob --agent-type researcher
```
Spawn 时系统会自动：
1. 注册代理到团队注册表
2. 创建持久化的会话记录
3. 返回代理名称和会话信息
**资料来源：** [clawteam/spawn/wsh_backend.py:1-50](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/wsh_backend.py)
### 代理身份管理
每个代理运行时必须设置身份环境变量：
```bash
export CLAWTEAM_AGENT_ID="leader-001"
export CLAWTEAM_AGENT_NAME="leader"
export CLAWTEAM_AGENT_TYPE="leader"
```
使用 `identity` 命令查看或设置身份：
```bash
# 查看当前身份
clawteam identity show
# 打印环境变量设置命令
eval $(clawteam identity set --agent-name alice --team dev-team)
```
**资料来源：** [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)
---
## 任务管理
### 任务数据模型
任务支持以下状态：
| 状态 | 说明 |
|------|------|
| `pending` | 未开始 |
| `in_progress` | 进行中 |
| `completed` | 已完成（自动解除依赖） |
| `blocked` | 等待其他任务 |
任务支持优先级设置：`low`、`medium`、`high`、`urgent`。
**资料来源：** [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)
### 创建任务
```bash
clawteam task create [options]
```
| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--owner, -o` | 任务负责人 | `None` |
| `--description, -d` | 任务描述 | `""` |
| `--priority, -p` | 优先级 | `medium` |
| `--blocks` | 该任务阻塞的任务 ID | `None` |
| `--blocked-by` | 阻塞该任务的任务 ID | `None` |
**示例：**
```bash
clawteam task create dev-team "Implement auth" -o alice -d "Add JWT authentication"
```
### 更新任务
```bash
clawteam task update [options]
```
| 选项 | 说明 |
|------|------|
| `--status, -s` | 新状态 |
| `--owner, -o` | 新负责人 |
| `--priority, -p` | 新优先级 |
| `--add-blocks` | 添加阻塞的任务 |
| `--add-blocked-by` | 添加阻塞该任务的任务 |
| `--force, -f` | 强制覆盖任务锁 |
当任务标记为 `completed` 时，所有被该任务阻塞的任务会自动解除阻塞（从 `blocked` 变为 `pending`）。
### 列出任务
```bash
clawteam task list [--status STATUS] [--owner NAME] [--priority LEVEL] [--sort-priority]
```
### 任务存储实现
任务存储采用文件系统后端：
> This module preserves the historic ``clawteam.team.tasks`` import path while delegating the implementation to :mod:`clawteam.store`.
```python
from clawteam.store.base import BaseTaskStore, TaskLockError
from clawteam.store.file import FileTaskStore
TaskStore = FileTaskStore
```
**资料来源：** [clawteam/team/tasks.py:1-20](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/tasks.py)
---
## 团队状态与看板
### 查看团队状态
```bash
clawteam team status
```
显示团队配置和成员列表。
### 看板命令
| 命令 | 说明 |
|------|------|
| `board show` | 显示团队看板详情 |
| `board overview` | 显示所有团队概览表 |
| `board live` | 实时刷新的看板（可设置间隔） |
```bash
clawteam board show
clawteam board live [--interval 2.0]
```
**资料来源：** [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)
---
## 消息类型系统
代理间通过消息进行通信，支持以下消息类型：
| 消息类型 | 说明 |
|----------|------|
| `message` | 点对点消息 |
| `broadcast` | 广播给所有成员 |
| `join_request` | 加入团队请求 |
| `join_approved` | 加入请求被批准 |
| `join_rejected` | 加入请求被拒绝 |
| `plan_approval_request` | 提交计划供审批 |
| `plan_approved` | 计划被批准 |
| `plan_rejected` | 计划被拒绝 |
| `shutdown_request` | 关闭请求 |
| `shutdown_approved` | 关闭被批准 |
| `shutdown_rejected` | 关闭被拒绝 |
| `idle` | 代理空闲通知 |
### 加入团队流程
```bash
# 请求加入
clawteam team request-join [options]
# 领导者批准
clawteam team approve-join [--assigned-name NAME]
# 领导者拒绝
clawteam team reject-join
```
| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--capabilities, -c` | 代理能力描述 | `""` |
| `--timeout, -t` | 超时时间（秒） | `60` |
**资料来源：** [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)
---
## 优雅关闭流程
### 关闭状态机
```mermaid
graph TD
A[Running] -->|request-shutdown| B[Shutdown Pending]
B -->|approve-shutdown| C[Shutting Down]
B -->|reject-shutdown| D[Running Resumed]
C -->|Process Exit| E[Terminated]
A -->|idle| F[Idle]
F -->|New Task| A
```
### 关闭命令
**请求关闭：**
```bash
clawteam lifecycle request-shutdown [--reason TEXT]
```
**批准关闭：**
```bash
clawteam lifecycle approve-shutdown
```
**拒绝关闭：**
```bash
clawteam lifecycle reject-shutdown [--reason TEXT]
```
### 空闲通知
当代理没有更多工作时，发送空闲通知给领导者：
```bash
clawteam lifecycle idle [--last-task ID] [--task-status STATUS]
```
**资料来源：** [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)
---
## 计划审批流程
### 计划提交
```bash
clawteam plan submit [--summary TEXT]
```
内容可以是内联文本或文件路径。
### 计划审批
```bash
# 批准计划
clawteam plan approve [--feedback TEXT]
# 拒绝计划
clawteam plan reject [--feedback TEXT]
```
**资料来源：** [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)
---
## 团队启动工作流
从模板启动团队的完整流程：
```bash
# 1. 设置领导者身份
export CLAWTEAM_AGENT_ID="leader-001"
export CLAWTEAM_AGENT_NAME="leader"
export CLAWTEAM_AGENT_TYPE="leader"
# 2. 从模板启动团队（包含多个代理）
clawteam launch --backend tmux --team
```
启动流程会自动：
1. 加载团队模板
2. 为每个代理设置环境变量
3. Spawn 代理进程
4. 注册到团队注册表
5. 输出启动摘要
**输出示例：**
```
Team 'dev-team' launched from template 'default'
Agents:
Name Type ID
leader leader leader-001
worker1 worker worker-001
Attach: tmux attach -t clawteam-dev-team
Board: clawteam board show dev-team
Inbox: clawteam inbox peek dev-team --agent
```
**资料来源：** [clawteam/cli/commands.py:1-80](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/cli/commands.py)
---
## 文件存储布局
团队数据存储在 `~/.clawteam/` 目录下：
```
~/.clawteam/
├── teams/{team}/
│ ├── config.json # 团队配置（名称、成员、领导者）
│ └── inboxes/{agent}/ # 消息文件（msg-{timestamp}-{uuid}.json）
├── tasks/{team}/
│ └── task-{id}.json # 单独的任务文件
└── plans/
└── {agent}-{id}.md # 计划文档
```
**资料来源：** [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)
---
## 任务依赖工作流示例
```mermaid
graph LR
A[T-001 设计系统] --> B[T-002 实现后端]
A --> C[T-003 实现前端]
B --> D[T-004 集成测试]
C --> D
style A fill:#90EE90
style B fill:#FFD700
style C fill:#FFD700
style D fill:#D3D3D3
```
**命令序列：**
```bash
# 1. 创建任务
clawteam task create my-team "Design system" -o leader
# => Task ID: aaa11111
# 2. 创建依赖任务
clawteam task create my-team "Implement backend" -o worker1 --blocked-by aaa11111
# => Task ID: bbb22222（自动设置为 blocked 状态）
clawteam task create my-team "Build frontend" -o worker2 --blocked-by aaa11111
# => Task ID: ccc33333（自动设置为 blocked 状态）
# 3. 完成前置任务
clawteam task update my-team aaa11111 --status completed
# bbb22222 和 ccc33333 自动解除阻塞
```
**资料来源：** [skills/clawteam/references/workflows.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/workflows.md)
---
## 总结
ClawTeam 的团队生命周期管理涵盖：
| 阶段 | 核心命令 | 关键功能 |
|------|----------|----------|
| 创建 | `spawn-team` | 注册领导者和团队配置 |
| 发现 | `discover` | 列出可用团队 |
| 启动 | `spawn` | 生成代理进程并注册 |
| 协调 | `task create/update` | 任务分配和依赖管理 |
| 监控 | `board show` | 看板可视化 |
| 通信 | `message/broadcast` | 代理间消息传递 |
| 审批 | `plan submit/approve` | 计划审批工作流 |
| 关闭 | `request-shutdown` | 优雅关闭流程 |
---
## 任务管理与依赖链
### 相关页面
相关主题：[团队生命周期管理](#page-team-management), [智能体间消息通信](#page-messaging)
相关源码文件
以下源码文件用于生成本页说明：
- [clawteam/team/tasks.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/tasks.py)
- [clawteam/store/base.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/store/base.py)（从 tasks.py 导入）
- [clawteam/store/file.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/store/file.py)（实际实现）
- [clawteam/mcp/tools/task.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/mcp/tools/task.py)
- [clawteam/harness/context_recovery.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/harness/context_recovery.py)
- [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)
- [skills/clawteam/references/workflows.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/workflows.md)
# 任务管理与依赖链
## 概述
任务管理与依赖链是 ClawTeam 协作框架的核心子系统，负责协调多智能体团队中的工作分配、状态追踪和执行顺序控制。该模块使团队能够创建结构化的任务网络，通过依赖关系确保任务按照正确的顺序执行，并支持看板式的可视化工作流管理。
ClawTeam 的任务系统基于文件系统存储，通过统一的 `TaskStore` 接口提供增删改查功能，并自动处理任务间的依赖解除逻辑。资料来源：[clawteam/team/tasks.py:1-14]()
## 核心架构
### 存储层次
```
clawteam.team.tasks (兼容性垫片)
│
▼
clawteam.store.base (BaseTaskStore 接口定义)
│
▼
clawteam.store.file (FileTaskStore 具体实现)
│
▼
~/.clawteam/tasks/{team}/task-{id}.json (持久化文件)
```
资料来源：[clawteam/team/tasks.py:1-14]()
### 关键类导出
| 类/异常 | 说明 | 来源 |
|---------|------|------|
| `BaseTaskStore` | 任务存储抽象基类，定义接口规范 | [clawteam/store/base.py]() |
| `TaskStore` | 实际使用的 `FileTaskStore` 别名 | [clawteam/team/tasks.py:11]() |
| `TaskLockError` | 任务锁定冲突时抛出的异常 | [clawteam/team/tasks.py:6]() |
## 数据模型
### 任务状态
| 状态 | 说明 | 行为 |
|------|------|------|
| `pending` | 任务未开始，等待执行 | 可被依赖任务自动解除 |
| `in_progress` | 任务正在执行中 | 独占锁定，防止并发修改 |
| `completed` | 任务已完成 | 自动解除所有依赖该任务的其他任务的阻塞状态 |
| `blocked` | 任务被阻塞，等待前置任务完成 | 当所有 blocker 完成后自动转为 `pending` |
资料来源：[skills/clawteam/references/cli-reference.md](skills/clawteam/references/cli-reference.md)
### 任务结构
```json
{
"id": "aaa11111",
"subject": "Design API schema",
"description": "Create REST API specification",
"owner": "backend-dev",
"status": "pending",
"priority": "medium",
"blocks": [],
"blocked_by": [],
"created_at": "2024-01-15T10:30:00Z"
}
```
## 依赖链机制
### 工作原理
依赖链允许任务声明对其他任务的依赖关系（`blocked_by`），确保前置任务完成后，后置任务才能执行。
```mermaid
graph LR
A[T-001 设计架构] -->|blocked_by| B[T-002 后端实现]
A[T-001 设计架构] -->|blocked_by| C[T-003 前端开发]
B -->|blocked_by| D[T-004 集成测试]
C -->|blocked_by| D[T-004 集成测试]
```
资料来源：[skills/clawteam/references/workflows.md](skills/clawteam/references/workflows.md)
### 自动解除阻塞
当任务状态变为 `completed` 时，系统自动检查所有依赖该任务的其他任务：
1. 遍历依赖列表中的每个任务
2. 检查该任务的 `blocked_by` 集合
3. 如果所有 blocker 都已完成，将该任务状态从 `blocked` 更新为 `pending`
4. 释放任务锁，允许新所有者接管
```bash
# 示例：完成后自动解除阻塞
clawteam task update my-project aaa11111 --status completed
# bbb22222 和 ccc33333 自动从 blocked -> pending
```
资料来源：[skills/clawteam/references/cli-reference.md](skills/clawteam/references/cli-reference.md)
## CLI 命令接口
### 创建任务
```bash
clawteam task create [options]
```
| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--owner, -o` | 任务负责人 | `None` |
| `--description, -d` | 任务详细描述 | `""` |
| `--priority, -p` | 优先级：low, medium, high, urgent | `medium` |
| `--blocks` | 任务 ID 列表（此任务完成后解除） | `None` |
| `--blocked-by` | 任务 ID 列表（阻塞此任务） | `None` |
**示例**：
```bash
# 创建基础任务
clawteam task create dev-team "Design system" -o leader
# 创建依赖链
clawteam task create my-project "Implement backend" -o dev1 --blocked-by aaa11111
clawteam task create my-project "Build frontend" -o dev2 --blocked-by aaa11111
clawteam task create my-project "Integration tests" --blocked-by bbb22222,ccc33333
```
资料来源：[skills/clawteam/references/cli-reference.md](skills/clawteam/references/cli-reference.md)
### 更新任务
```bash
clawteam task update [options]
```
| 选项 | 说明 |
|------|------|
| `--status, -s` | 新状态：pending, in_progress, completed, blocked |
| `--owner, -o` | 新负责人 |
| `--subject` | 新主题 |
| `--description, -d` | 新描述 |
| `--priority, -p` | 新优先级 |
| `--add-blocks` | 添加阻塞的任务 ID（逗号分隔） |
| `--add-blocked-by` | 添加阻塞此任务的任务 ID |
| `--force, -f` | 强制覆盖任务锁 |
**关键行为**：使用 `--status completed` 会自动触发依赖解除逻辑。资料来源：[skills/clawteam/references/cli-reference.md](skills/clawteam/references/cli-reference.md)
### 查询任务
```bash
# 获取单个任务详情
clawteam task get
# 列出团队所有任务（支持过滤）
clawteam task list [--status STATUS] [--owner NAME] [--priority LEVEL] [--sort-priority]
```
## MCP 工具集成
ClawTeam 提供 MCP（Model Context Protocol）工具接口，允许 AI 智能体直接通过工具调用操作任务系统。资料来源：[clawteam/mcp/tools/task.py]()
### 工具能力
- `task_create`: 创建新任务并设置依赖
- `task_update`: 更新任务状态和属性
- `task_get`: 获取单个任务详情
- `task_list`: 列出并过滤任务
- `task_delete`: 删除任务（谨慎使用）
### 智能体上下文恢复
在多智能体协作场景中，`context_recovery.py` 模块利用任务系统为智能体提供团队状态摘要：
```python
from clawteam.team.models import TaskStatus
from clawteam.team.tasks import TaskStore
store = TaskStore(team_name)
tasks = store.list_tasks()
# 按负责人分组统计
owner_status: dict[str, tuple[int, int]] = {}
for t in tasks:
if t.owner and t.owner != agent_name:
done, total = owner_status.get(t.owner, (0, 0))
total += 1
if t.status == TaskStatus.completed:
done += 1
owner_status[t.owner] = (done, total)
```
资料来源：[clawteam/harness/context_recovery.py]()
## 完整工作流示例
### 场景：Web 应用开发团队
```bash
# 1. 设置领导者身份
export CLAWTEAM_AGENT_ID="leader-001"
export CLAWTEAM_AGENT_NAME="leader"
export CLAWTEAM_AGENT_TYPE="leader"
# 2. 创建团队
clawteam team spawn-team web-project -d "Web 应用开发" -n leader
# 3. 创建任务依赖链
clawteam task create web-project "设计系统架构" -o leader
# => 任务 ID: arch-001
clawteam task create web-project "实现后端 API" -o backend-dev --blocked-by arch-001
# => 任务 ID: backend-001 (自动设为 blocked)
clawteam task create web-project "开发前端界面" -o frontend-dev --blocked-by arch-001
# => 任务 ID: frontend-001 (自动设为 blocked)
clawteam task create web-project "集成测试" --blocked-by backend-001,frontend-001
# => 任务 ID: test-001
# 4. 查看看板
clawteam board show web-project
# 5. 架构完成后，自动解除阻塞
clawteam task update web-project arch-001 --status completed
# backend-dev 和 frontend-dev 的任务自动变为 pending
# 6. 后端和前端都完成后，测试任务解除阻塞
clawteam task update web-project backend-001 --status completed
clawteam task update web-project frontend-001 --status completed
# test-001 自动从 blocked 变为 pending
```
资料来源：[skills/clawteam/references/workflows.md](skills/clawteam/references/workflows.md)
## 持久化存储
### 文件结构
```
~/.clawteam/
└── tasks/
└── {team}/
└── task-{id}.json # 单个任务文件
```
每个任务以 JSON 格式独立存储在对应团队的目录下，便于版本控制和团队间迁移。资料来源：[skills/clawteam/references/cli-reference.md](skills/clawteam/references/cli-reference.md)
### 任务文件格式
```json
{
"id": "task-xxx",
"subject": "任务标题",
"description": "任务描述",
"owner": "负责人名称",
"status": "pending|in_progress|completed|blocked",
"priority": "low|medium|high|urgent",
"blocks": ["被此任务阻塞的任务ID"],
"blocked_by": ["阻塞此任务的任务ID"],
"created_at": "ISO时间戳",
"updated_at": "ISO时间戳"
}
```
## 最佳实践
1. **最小化依赖深度**：依赖链过长会增加调试难度，建议控制在 3-4 层以内
2. **明确负责人**：每个任务都应指定明确的负责人，避免责任真空
3. **及时更新状态**：智能体完成任务后应立即更新状态，确保依赖链正确推进
4. **使用看板监控**：定期使用 `clawteam board show` 或 `clawteam board live` 监控团队进度
5. **优先级梯度**：使用 priority 选项确保关键路径上的任务优先处理
---
## 智能体间消息通信
### 相关页面
相关主题：[团队生命周期管理](#page-team-management), [任务管理与依赖链](#page-task-dependencies)
相关源码文件
以下源码文件用于生成本页说明：
- [clawteam/team/mailbox.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/mailbox.py)
- [clawteam/team/router.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/router.py)
- [clawteam/mcp/tools/mailbox.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/mcp/tools/mailbox.py)
- [clawteam/transport/file.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/transport/file.py)
- [clawteam/store/file.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/store/file.py)
- [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)
- [skills/clawteam/references/workflows.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/workflows.md)
# 智能体间消息通信
## 概述
ClawTeam 的智能体间消息通信系统是协调多智能体团队工作的核心基础设施。该系统提供点对点消息传递、广播通信、消息路由、任务依赖管理和生命周期控制等功能，使团队中的各个智能体能够有效地进行协作。
消息系统基于文件存储实现，每个智能体拥有独立的收件箱（Mailbox），消息以结构化的 JSON 格式持久化存储在本地文件系统中。资料来源：[clawteam/team/mailbox.py:1-50]()
## 系统架构
### 整体架构图
```mermaid
graph TD
A[智能体 A] -->|发送消息| B[Mailbox 模块]
B --> C[消息路由器 Router]
C -->|点对点| D[智能体 B 收件箱]
C -->|广播| E[所有成员收件箱]
F[CLI 命令] -->|mailbox send| B
G[CLI 命令] -->|mailbox broadcast| B
H[CLI 命令] -->|mailbox receive| B
I[生命周期事件] -->|join/leave/shutdown| B
J[任务事件] -->|plan/status| B
```
### 核心组件
| 组件 | 文件路径 | 职责 |
|------|----------|------|
| Mailbox | `clawteam/team/mailbox.py` | 消息的发送、接收、广播核心实现 |
| Router | `clawteam/team/router.py` | 消息路由和目标解析 |
| MCP Tools | `clawteam/mcp/tools/mailbox.py` | MCP 协议工具封装 |
| File Transport | `clawteam/transport/file.py` | 基于文件的底层传输层 |
| Inbox Storage | `~/.clawteam/teams/{team}/inboxes/{agent}/` | 消息持久化存储 |
资料来源：[clawteam/mcp/tools/mailbox.py:1-30]()
## 消息类型
ClawTeam 定义了完整的消息类型体系，涵盖智能体协作的各个场景：
| 消息类型 | 说明 | 触发场景 |
|----------|------|----------|
| `message` | 点对点通用消息 | 智能体间的日常通信 |
| `broadcast` | 广播消息 | 向团队所有成员发布通知 |
| `join_request` | 加入团队请求 | 智能体申请加入团队 |
| `join_approved` | 加入批准 | 团队领导者批准加入请求 |
| `join_rejected` | 加入拒绝 | 团队领导者拒绝加入请求 |
| `plan_approval_request` | 计划审批请求 | 智能体提交计划等待审批 |
| `plan_approved` | 计划批准 | 领导者批准某个计划 |
| `plan_rejected` | 计划拒绝 | 领导者拒绝某个计划 |
| `shutdown_request` | 关闭请求 | 请求智能体优雅关闭 |
| `shutdown_approved` | 关闭批准 | 智能体确认关闭 |
| `shutdown_rejected` | 关闭拒绝 | 智能体拒绝关闭请求 |
| `idle` | 空闲通知 | 智能体完成工作进入空闲状态 |
资料来源：[skills/clawteam/references/cli-reference.md:60-80]()
## 消息数据结构
### 消息文件格式
消息以 JSON 格式存储在 `~/.clawteam/teams/{team}/inboxes/{agent}/msg-{timestamp}-{uuid}.json` 路径下。
```json
{
"id": "msg-1234567890-abc123",
"type": "message",
"from": "leader",
"to": "researcher",
"content": "请研究微服务的认证模式",
"timestamp": "2024-01-15T10:30:00Z",
"request_id": null,
"key": null,
"proposed_name": null,
"capabilities": null,
"feedback": null,
"reason": null,
"assigned_name": null,
"agent_id": null,
"team_name": "dev-team",
"plan_file": null,
"summary": null,
"plan": null,
"last_task": null,
"status": null
}
```
### MessagePayload 数据模型
```python
@dataclass
class MessagePayload:
msg_id: str # 消息唯一标识
msg_type: MessageType # 消息类型枚举
from_agent: str # 发送方名称
to_agent: str # 接收方名称
content: str # 消息内容
timestamp: str # ISO8601 时间戳
# ... 其他可选字段
```
资料来源：[clawteam/team/mailbox.py:20-60]()
## 核心 API
### 发送消息 (mailbox_broadcast)
广播消息给团队所有成员：
```python
def mailbox_broadcast(
team_name: str,
from_agent: str,
content: str,
msg_type: str | None = None,
key: str | None = None,
exclude: list[str] | None = None,
) -> list[dict]:
"""Broadcast a message to team inboxes."""
```
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `team_name` | str | 是 | 团队名称 |
| `from_agent` | str | 是 | 发送方智能体名称 |
| `content` | str | 是 | 消息内容 |
| `msg_type` | str | 否 | 消息类型，默认 `broadcast` |
| `key` | str | 否 | 消息关联的键 |
| `exclude` | list[str] | 否 | 排除的智能体名称列表 |
资料来源：[clawteam/mcp/tools/mailbox.py:50-70]()
### 接收消息 (mailbox_receive)
接收并消费待处理的消息：
```python
def mailbox_receive(
team_name: str,
agent_name: str,
limit: int = 10
) -> list[dict]:
"""Receive and consume pending inbox messages."""
```
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `team_name` | str | 是 | - | 团队名称 |
| `agent_name` | str | 是 | - | 接收方智能体名称 |
| `limit` | int | 否 | 10 | 最多接收消息数量 |
### 预览消息 (mailbox_peek)
预览待处理消息但不消费：
```python
def mailbox_peek(
team_name: str,
agent_name: str
) -> list[dict]:
"""Preview pending inbox messages without consuming them."""
```
### 获取消息数量 (mailbox_peek_count)
```python
def mailbox_peek_count(
team_name: str,
agent_name: str
) -> dict:
"""Get the number of pending inbox messages."""
return {"agentName": agent_name, "count": team_mailbox.team_mailbox(...).count}
```
资料来源：[clawteam/mcp/tools/mailbox.py:70-90]()
## CLI 命令接口
### inbox send - 发送消息
```bash
clawteam inbox send [--type TYPE] [--key KEY]
```
### inbox receive - 接收消息
```bash
clawteam inbox receive [--agent AGENT] [--limit LIMIT]
```
### inbox peek - 预览消息
```bash
clawteam inbox peek [--agent AGENT]
```
### inbox broadcast - 广播消息
```bash
clawteam inbox broadcast [--exclude AGENT,AGENT...]
```
资料来源：[skills/clawteam/references/cli-reference.md:1-50]()
## 协作工作流
### 工作流 1：领导者分配任务
```mermaid
sequenceDiagram
participant L as 领导者
participant M as Mailbox
participant W as Worker
L->>M: inbox send "执行数据分析"
M-->>W: 消息投递到收件箱
W->>W: inbox receive 获取消息
W->>W: 执行任务
W->>M: task update --status completed
W->>M: lifecycle idle 通知
```
### 工作流 2：计划审批流程
```bash
# 智能体提交计划
clawteam plan submit dev-team coder "实现步骤..." \
--summary "Auth 系统现代化"
# 领导者检查收件箱
clawteam inbox receive dev-team --agent leader
# => plan_approval_request with planId
# 领导者审批
clawteam plan approve dev-team coder --feedback "看起来不错，开始执行"
```
资料来源：[skills/clawteam/references/workflows.md:30-60]()
### 工作流 3：优雅关闭
```mermaid
sequenceDiagram
participant L as 领导者
participant M as Mailbox
participant W as Worker
L->>M: lifecycle request-shutdown --reason "所有任务完成"
M-->>W: shutdown_request 投递
W->>W: inbox receive 获取关闭请求
W->>W: 完成当前工作
W->>M: lifecycle approve-shutdown
L->>M: team cleanup --force
```
```bash
# 领导者请求关闭
clawteam lifecycle request-shutdown dev-team leader coder --reason "所有任务完成"
# Worker 查看收件箱
clawteam inbox receive dev-team --agent coder
# => shutdown_request, requestId: shut-xyz
# Worker 批准关闭
clawteam lifecycle approve-shutdown dev-team shut-xyz coder
```
资料来源：[skills/clawteam/references/workflows.md:70-95]()
## 文件存储布局
```
~/.clawteam/
├── teams/{team}/
│ ├── config.json # 团队配置（名称、成员、领导者）
│ └── inboxes/{agent}/ # 各智能体收件箱
│ ├── msg-{timestamp}-{uuid}.json # 消息文件
│ └── ...
├── tasks/{team}/
│ └── task-{id}.json # 任务文件
└── plans/
└── {agent}-{id}.md # 计划文档
```
消息文件命名格式：`msg-{timestamp}-{uuid}.json`，确保消息按时间顺序排列且具有全局唯一性。
资料来源：[skills/clawteam/references/cli-reference.md:90-110]()
## 消息与板卡集成
Board 命令提供团队状态总览，包含消息历史：
```bash
clawteam board show
clawteam --json board show
```
JSON 输出包含成员感知字段：
| 字段 | 说明 |
|------|------|
| `memberKey` | 成员唯一标识键 |
| `inboxName` | 收件箱名称 |
| `fromLabel` | 发送方标签 |
| `toLabel` | 接收方标签 |
| `inboxCount` | 未读消息数量 |
浏览器板卡使用这些字段过滤收件箱历史记录，实现消息导航功能。
资料来源：[skills/clawteam/references/cli-reference.md:115-130]()
## 最佳实践
### 消息设计原则
1. **消息幂等性**：使用 `request_id` 确保消息处理的幂等性
2. **内容简洁**：消息内容应清晰表达意图，避免过长文本
3. **类型明确**：根据消息目的选择正确的消息类型
4. **状态同步**：定期使用 `mailbox_peek_count` 检查未读消息
### 错误处理
当消息处理失败时，系统通过以下机制保证可靠性：
- 消息持久化存储在文件系统，重启后可恢复
- 使用 `mailbox_peek` 而非 `mailbox_receive` 进行消息预览，避免意外消费
- `mailbox_peek_count` 返回消息计数，便于监控队列状态
### 性能考虑
- 消息文件按时间戳命名，便于顺序读取
- 建议定期清理已处理消息，避免收件箱膨胀
- 大规模团队建议监控 `~/.clawteam/` 目录大小
## 总结
ClawTeam 的智能体间消息通信系统提供了完整的多智能体协作基础设施：
- **9+ 消息类型**覆盖协作全生命周期
- **文件存储**确保消息可靠持久化
- **MCP 工具**和 **CLI 命令**双重接口
- **与板卡系统集成**提供可视化监控
- **工作流模板**简化常见协作场景
该系统使开发者能够轻松构建、协调和管理多智能体团队，实现复杂的软件工程任务自动化。
---
---
## Doramagic 踩坑日志
项目：HKUDS/ClawTeam
摘要：发现 15 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Security testing for multi-agent swarms: agent isolation, delegation trust, inbox spoofing。
## 1. 安全/权限坑 · 来源证据：Security testing for multi-agent swarms: agent isolation, delegation trust, inbox spoofing
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security testing for multi-agent swarms: agent isolation, delegation trust, inbox spoofing
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d8bd96f00b7c46c6813bc15c32a84625 | https://github.com/HKUDS/ClawTeam/issues/76 | 来源类型 github_issue 暴露的待验证使用条件。
## 2. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | host_targets=claude, claude_code, cursor, chatgpt
## 3. 配置坑 · 来源证据：Proposal: 8-PR sequence — canonical WorkerState, persistent event log, project namespacing, contract verify states, SCM…
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Proposal: 8-PR sequence — canonical WorkerState, persistent event log, project namespacing, contract verify states, SCM plugin + reaction engine
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_114771b2a1474b358b05a6a9e61807f6 | https://github.com/HKUDS/ClawTeam/issues/157 | 来源类型 github_issue 暴露的待验证使用条件。
## 4. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | README/documentation is current enough for a first validation pass.
## 5. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | last_activity_observed missing
## 6. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | no_demo; severity=medium
## 7. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | No sandbox install has been executed yet; downstream must verify before user use.
## 8. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | no_demo; severity=medium
## 9. 安全/权限坑 · 来源证据：Agent Definitions Feature is Non-Functional: Parsed but Not Applied
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Agent Definitions Feature is Non-Functional: Parsed but Not Applied
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_dc9ad856da7a4a828860da94afadc7ec | https://github.com/HKUDS/ClawTeam/issues/146 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 10. 安全/权限坑 · 来源证据：High: /api/proxy board endpoint enables SSRF and arbitrary outbound fetches
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：High: /api/proxy board endpoint enables SSRF and arbitrary outbound fetches
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_61dec732a08f4279a590654f0eecea51 | https://github.com/HKUDS/ClawTeam/issues/104 | 来源类型 github_issue 暴露的待验证使用条件。
## 11. 安全/权限坑 · 来源证据：Worker agents exit after first turn despite 'ongoing job' task prompt
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Worker agents exit after first turn despite 'ongoing job' task prompt
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_26124d52e6d948b2bf15809390ef2589 | https://github.com/HKUDS/ClawTeam/issues/148 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 12. 安全/权限坑 · 来源证据：[Feature Request] Optimize Worker Workspace Size and Enable Headless IPC
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Optimize Worker Workspace Size and Enable Headless IPC
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_63b04b7d23e74c71a8c1f8dddcaa9281 | https://github.com/HKUDS/ClawTeam/issues/45 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 13. 安全/权限坑 · 来源证据：v0.2.0 — Stabilization Release
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.0 — Stabilization Release
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2aca0ffb17f94d8bb219737c9f275e7f | https://github.com/HKUDS/ClawTeam/releases/tag/v0.2.0 | 来源类型 github_release 暴露的待验证使用条件。
## 14. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | issue_or_pr_quality=unknown
## 15. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | release_recency=unknown