[options]\n```\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `--team, -t` | 团队名称 | `\"default\"` |\n| `--agent-name, -n` | 智能体名称 | 自动生成 |\n| `--agent-type` | 智能体类型 | `\"general-purpose\"` |\n\n支持后端：`subprocess`、`tmux`、`wsh`\n\n## 7. Web 可视化界面\n\nWeb 界面 (`App.jsx`) 提供实时终端模拟和团队状态可视化：\n\n```jsx\n// 团队状态展示\n\n docs-sprint 3 agents active\n
\n\n ● \n T-001 Build landing page done\n
\n\n ● \n T-002 Write API docs active\n
\n\n ○ \n T-003 Review & merge blocked\n
\n```\n\n资料来源：[website/src/App.jsx:1-50]()\n\n## 8. 数据流架构图\n\n```mermaid\ngraph TD\n subgraph 用户交互\n CLI[CLI 命令]\n WebUI[Web 界面]\n end\n \n subgraph 核心服务\n Orchestrator[编排器]\n Conductor[调度器]\n TeamManager[团队管理器]\n end\n \n subgraph 存储层\n TaskStore[任务存储]\n PlanStore[计划存储]\n MessageStore[消息存储]\n AgentRegistry[智能体注册表]\n end\n \n subgraph 运行时\n WSHBackend[wsh 后端]\n TMUXBackend[tmux 后端]\n SubprocessBackend[子进程后端]\n end\n \n CLI -->|命令解析| Orchestrator\n WebUI -->|HTTP/WS| Orchestrator\n \n Orchestrator -->|调度任务| Conductor\n Orchestrator -->|团队管理| TeamManager\n \n Conductor -->|读写| PlanStore\n TeamManager -->|读写| TaskStore\n TeamManager -->|读写| MessageStore\n TeamManager -->|注册| AgentRegistry\n \n AgentRegistry -->|启动| WSHBackend\n AgentRegistry -->|启动| TMUXBackend\n AgentRegistry -->|启动| SubprocessBackend\n \n WSHBackend -->|反馈| AgentRegistry\n TMUXBackend -->|反馈| AgentRegistry\n SubprocessBackend -->|反馈| AgentRegistry\n```\n\n## 9. 关键技术特性\n\n### 9.1 智能体类型系统\n\n| 类型 | 说明 | 典型用途 |\n|------|------|----------|\n| `leader` | 领导者智能体 | 团队协调、任务分配 |\n| `general-purpose` | 通用智能体 | 常规开发任务 |\n| `researcher` | 研究智能体 | 信息收集与分析 |\n| `evaluator` | 评估智能体 | 代码审查、质量把控 |\n| `planner` | 规划智能体 | 任务分解与计划制定 |\n\n### 9.2 任务优先级机制\n\n```bash\nclawteam task create [options]\n --priority, -p 优先级: low | medium | high | urgent\n --blocked-by 依赖任务列表\n --blocks 阻塞任务列表\n```\n\n## 10. 总结\n\nClawTeam 的架构设计遵循以下核心原则：\n\n1. **模块化解耦**：各子系统（任务管理、消息通信、计划审批）独立运作\n2. **多后端兼容**：支持 wsh、tmux、subprocess 等多种运行时环境\n3. **状态驱动**：基于文件的状态持久化，支持断点恢复\n4. **层级化上下文**：为智能体提供渐进式的上下文注入\n5. **审批工作流**：关键决策（如计划、加入、关闭）需经过审批流程\n\n这种架构使 ClawTeam 能够有效地协调多个 AI 智能体，实现复杂的软件开发和协作任务。\n\n---\n\n\n\n## Harness 与协调执行器\n\n### 相关页面\n\n相关主题：[系统架构总览](#page-architecture-overview), [团队生命周期管理](#page-team-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [clawteam/harness/context_recovery.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/harness/context_recovery.py)\n- [clawteam/spawn/wsh_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/wsh_backend.py)\n- [clawteam/team/models.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/models.py) - 任务状态与数据模型\n- [clawteam/team/tasks.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/tasks.py) - 任务存储与操作\n- [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md) - CLI参考文档\n \n\n# Harness 与协调执行器\n\n## 概述\n\nHarness 是 ClawTeam 项目中负责为 AI Agent 运行时注入上下文、管理团队协作状态、以及协调任务执行的中间层组件。Harness 并非一个单一的模块，而是一组协同工作的子系统的集合，包括上下文恢复（Context Recovery）、契约执行（Contract Execution）、阶段管理（Phases）、策略调度（Strategies）、以及协调器（Orchestrator）。\n\nClawTeam 的核心定位是**多智能体编排框架**（Agent Swarm Orchestration），而 Harness 则是将这一编排能力落地的关键引擎。它负责：\n\n1. **上下文管理** — 为 Agent 注入团队任务、成员、契约等运行时上下文\n2. **契约执行** — 根据预定义的契约（Contract）协调 Agent 行为\n3. **阶段控制** — 管理工作流的阶段切换与依赖关系\n4. **策略调度** — 根据不同策略选择执行路径和优先级\n\n> 资料来源：[skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n\n---\n\n## 核心架构\n\n### 模块组成\n\nHarness 系统主要由以下模块组成：\n\n| 模块 | 路径 | 职责 |\n|------|------|------|\n| Orchestrator | `clawteam/harness/orchestrator.py` | 全局协调器，管理整体执行流程 |\n| Conductor | `clawteam/harness/conductor.py` | 指挥器，负责阶段间的流转控制 |\n| Contract Executor | `clawteam/harness/contract_executor.py` | 契约执行器，解析并执行契约条款 |\n| Phases | `clawteam/harness/phases.py` | 阶段定义与管理 |\n| Strategies | `clawteam/harness/strategies.py` | 策略选择与调度逻辑 |\n| Context Recovery | `clawteam/harness/context_recovery.py` | 上下文恢复，为 Agent 注入运行时信息 |\n\n### 系统交互图\n\n```mermaid\ngraph TD\n subgraph Harness核心\n O[Orchestrator 协调器]\n C[Conductor 指挥器]\n CE[Contract Executor 契约执行器]\n P[Phases 阶段管理]\n S[Strategies 策略调度]\n CR[Context Recovery 上下文恢复]\n end\n \n subgraph 外部依赖\n TS[TaskStore 任务存储]\n TM[Team Members 团队成员]\n ART[Artifacts 工件存储]\n end\n \n O --> C\n C --> P\n C --> CE\n P --> S\n S --> CR\n CR --> TS\n CR --> TM\n CR --> ART\n \n O --> TS\n CE --> ART\n```\n\n> 资料来源：基于 `clawteam/harness/context_recovery.py` 源码结构推断\n\n---\n\n## 上下文恢复机制\n\n上下文恢复（Context Recovery）是 Harness 系统中最贴近 Agent 运行时的组件。它负责在 Agent 启动或任务切换时，将团队状态、任务信息、契约内容等关键上下文注入到 Agent 的执行环境中。\n\n### 核心功能\n\n`ContextRecovery` 类通过分层的方式组织上下文信息，每一层代表不同粒度的团队协作数据：\n\n```python\n# 层级结构示意\ndef _teammate_summary(self, agent_name: str, team_name: str, role: str) -> str:\n \"\"\"Layer 5: One-liner teammate summaries.\"\"\"\n try:\n from clawteam.team.models import TaskStatus\n from clawteam.team.tasks import TaskStore\n store = TaskStore(team_name)\n tasks = store.list_tasks()\n\n # Group by owner, exclude self\n owner_status: dict[str, tuple[int, int]] = {}\n for t in tasks:\n if t.owner and t.owner != agent_name:\n done, total = owner_status.get(t.owner, (0, 0))\n total += 1\n if t.status == TaskStatus.completed:\n done += 1\n owner_status[t.owner] = (done, total)\n```\n\n> 资料来源：[clawteam/harness/context_recovery.py:46-62](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/harness/context_recovery.py)\n\n### 上下文分层\n\n根据源码分析，Context Recovery 至少包含以下几层上下文：\n\n| 层级 | 内容 | 说明 |\n|------|------|------|\n| Layer 1 | 团队配置 | 团队名称、描述、领导节点 |\n| Layer 2 | 成员列表 | 所有团队成员及其状态 |\n| Layer 3 | 任务列表 | 当前团队中的所有任务 |\n| Layer 4 | 契约内容 | Sprint Contract 等契约条款 |\n| Layer 5 | 队友摘要 | 按负责人分组的任务完成情况 |\n\n### 角色特定上下文\n\n上下文恢复支持根据不同角色（Role）提供差异化的上下文信息：\n\n```python\nif role == \"builder\":\n # 仅显示该 Builder 的契约\n artifacts = self._ctx.artifacts.list_artifacts()\n for art in artifacts:\n name = art[\"name\"]\n if \"sprint-contract\" in name:\n content = self._ctx.artifacts.read(name)\n if content and agent_name in content:\n return f\"### Your Sprint Contract\\n```json\\n{content[:1000]}\\n```\"\nelif role == \"evaluator\":\n # 显示规范 + 所有契约标准\n spec = self._ctx.artifacts.read(\"spec.md\")\n lines = []\n if spec:\n lines.append(f\"### Specification\\n{spec[:2000]}\")\nelif role == \"planner\":\n # 显示规范草稿\n spec = self._ctx.artifacts.read(\"spec.md\")\n if spec:\n return f\"### Your Spec Draft\\n{spec[:2000]}\"\n```\n\n> 资料来源：[clawteam/harness/context_recovery.py:28-45](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/harness/context_recovery.py)\n\n---\n\n## 契约执行器\n\n契约执行器（Contract Executor）是 Harness 系统中负责解析和执行契约条款的核心组件。契约是 ClawTeam 中定义 Agent 行为规范和任务标准的机制。\n\n### 契约类型\n\n根据 CLI 参考文档，ClawTeam 支持多种类型的消息类型（契约载体）：\n\n| 消息类型 | 说明 | 触发场景 |\n|----------|------|----------|\n| `message` | 点对点消息 | Agent 间直接通信 |\n| `broadcast` | 广播消息 | 向所有成员发布通知 |\n| `join_request` | 加入请求 | Agent 申请加入团队 |\n| `plan_approval_request` | 计划审批请求 | 提交计划供领导审核 |\n| `shutdown_request` | 关闭请求 | 请求某个 Agent 关闭 |\n\n> 资料来源：[skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n\n### 契约与任务联动\n\n当一个任务被标记为 `completed` 时，契约执行器会自动解除被其阻塞的任务：\n\n```bash\n# 任务更新命令\nclawteam task update [options]\n\n# 关键选项\n--status, -s # 状态: pending, in_progress, completed, blocked\n--add-blocks # 添加阻塞的任务ID\n--add-blocked-by # 添加阻塞该任务的任务ID\n```\n\n> 资料来源：[skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n\n---\n\n## 任务状态模型\n\nHarness 系统依赖一套完整的状态机来管理任务生命周期：\n\n```mermaid\nstateDiagram-v2\n [*] --> pending: 创建任务\n pending --> in_progress: 开始执行\n in_progress --> completed: 标记完成\n in_progress --> blocked: 被依赖阻塞\n blocked --> pending: 依赖解除\n completed --> [*]\n pending --> blocked: 添加阻塞依赖\n```\n\n### 状态定义\n\n| 状态 | 说明 | 自动触发 |\n|------|------|----------|\n| `pending` | 未开始 | — |\n| `in_progress` | 执行中 | — |\n| `completed` | 已完成 | 自动解除被阻塞任务 |\n| `blocked` | 被阻塞 | — |\n\n> 资料来源：[skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n\n---\n\n## 后端执行支持\n\nHarness 系统通过抽象后端（Backend）接口支持不同的 Agent 运行环境。\n\n### 支持的后端类型\n\n| 后端 | 说明 | 使用场景 |\n|------|------|----------|\n| `subprocess` | 子进程执行 | 本地开发测试 |\n| `tmux` | Tmux 会话 | 持久化终端会话 |\n| `wsh` | VSCode WebSocket Terminal | VSCode 内置终端 |\n\n### WSH 后端实现\n\nWSH（WebSocket Handler）后端是为 VSCode 环境设计的特殊执行器：\n\n```python\ndef inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:\n \"\"\"Best-effort runtime injection into a running wsh block.\"\"\"\n from clawteam.spawn.registry import get_registry\n\n info = get_registry(team).get(agent_name, {})\n block_id = info.get(\"block_id\", \"\") or self._blocks.get(agent_name, \"\")\n if not block_id:\n return False, f\"wsh block for '{team}/{agent_name}' not found\"\n if not _is_block_alive(block_id):\n return False, f\"wsh block '{block_id}' is not alive\"\n```\n\n> 资料来源：[clawteam/spawn/wsh_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/wsh_backend.py)\n\n### 运行时消息注入\n\nHarness 支持在 Agent 运行时动态注入消息，这对于实时协调和状态同步至关重要：\n\n```python\ndef list_running(self) -> list[dict[str, str]]:\n \"\"\"List currently running agents.\"\"\"\n return [\n {\"name\": name, \"target\": target, \"backend\": \"wsh\"}\n for name, target in self._blocks.items()\n ]\n```\n\n---\n\n## CLI 集成\n\nHarness 系统的功能通过 CLI 命令向用户暴露。以下是关键命令对照：\n\n### Spawn 命令\n\n```bash\nclawteam spawn [options]\n\n# 常用选项\n--team, -t # 团队名称 (默认: \"default\")\n--agent-name, -n # Agent 名称 (自动生成)\n--agent-type # Agent 类型 (默认: \"general-purpose\")\n```\n\n> 资料来源：[skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n\n### 生命周期管理\n\n```bash\n# 请求关闭\nclawteam lifecycle request-shutdown [--reason TEXT]\n\n# 同意关闭\nclawteam lifecycle approve-shutdown \n\n# 拒绝关闭\nclawteam lifecycle reject-shutdown [--reason TEXT]\n\n# 空闲通知\nclawteam lifecycle idle [--last-task ID] [--task-status STATUS]\n```\n\n---\n\n## 数据存储结构\n\nHarness 依赖文件系统存储团队协作数据：\n\n```\n~/.clawteam/\n├── teams/{team}/\n│ ├── config.json # TeamConfig (name, members, leader)\n│ └── inboxes/{agent}/ # msg-{timestamp}-{uuid}.json 文件\n├── tasks/{team}/\n│ └── task-{id}.json # 单个任务文件\n└── plans/\n └── {agent}-{id}.md # 计划文档\n```\n\n> 资料来源：[skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n\n---\n\n## 执行流程示例\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI 用户\n participant Harness as Harness 系统\n participant TaskStore as TaskStore\n participant Agent as Agent 进程\n participant Backend as Backend\n\n CLI->>Harness: clawteam spawn tmux claude --team dev\n Harness->>TaskStore: 注册 Agent 信息\n Harness->>Backend: 创建 tmux 会话\n Backend-->>Agent: 启动进程\n Agent->>Harness: 请求上下文\n Harness->>TaskStore: 获取任务列表\n Harness->>Harness: Context Recovery\n Harness-->>Agent: 注入上下文\n Agent->>Agent: 执行任务\n Agent->>Harness: 更新任务状态\n Harness->>TaskStore: 持久化状态\n```\n\n---\n\n## 总结\n\nHarness 与协调执行器构成了 ClawTeam 智能体编排能力的核心支柱。通过分层设计，Harness 实现了：\n\n- **上下文隔离** — 不同角色获取差异化的运行时信息\n- **契约驱动** — 通过契约机制规范 Agent 行为\n- **状态同步** — 基于文件系统的可靠状态持久化\n- **多后端支持** — 统一的抽象接口支持多种执行环境\n\n这些设计使得 ClawTeam 能够有效地协调多个 AI Agent 在复杂软件项目中的协作工作。\n\n---\n\n\n\n## 智能体 Spawn 系统\n\n### 相关页面\n\n相关主题：[Spawn 后端实现](#page-spawn-backends), [团队生命周期管理](#page-team-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [clawteam/spawn/base.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/base.py)\n- [clawteam/spawn/sessions.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/sessions.py)\n- [clawteam/spawn/registry.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/registry.py)\n- [clawteam/spawn/prompt.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/prompt.py)\n- [clawteam/spawn/adapters.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/adapters.py)\n- [clawteam/spawn/wsh_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/wsh_backend.py)\n- [clawteam/cli/commands.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/cli/commands.py)\n \n\n# 智能体 Spawn 系统\n\n## 概述\n\n智能体 Spawn 系统是 ClawTeam 的核心组件之一，负责在团队环境中动态启动、注册和管理外部编码智能体进程。该系统通过抽象化的后端适配器架构，支持多种进程管理方式（tmux、subprocess、WebSocket Handler 等），并与团队身份系统、消息收件箱、任务管理模块紧密协作，使主控智能体能够统一编排分布式编码任务。\n\nSpawn 系统的设计目标：\n\n- 提供统一的智能体进程生命周期管理接口\n- 支持多后端运行时（tmux、subprocess、wsh 等）\n- 自动注入团队上下文（团队名称、智能体身份、领导节点信息）\n- 与会话恢复机制集成，支持断点续传\n- 通过注册中心维护运行中智能体的元数据\n\n## 系统架构\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n subgraph \"CLI 入口层\"\n CLI[clawteam spawn 命令]\n CMD[commands.py 解析]\n end\n \n subgraph \"后端适配层\"\n BASE[base.py - BaseBackend 抽象]\n TMUX[TmuxBackend]\n SUB[SubprocessBackend]\n WSH[WshBackend]\n AD[Adapters 适配器]\n end\n \n subgraph \"会话管理层\"\n SESS[SessionStore]\n CAPT[SessionCapture]\n REG[Registry 注册中心]\n end\n \n subgraph \"上下文注入\"\n PROMPT[prompt.py - 智能体提示词]\n ENV[环境变量注入]\n end\n \n CLI --> CMD\n CMD --> BASE\n BASE --> TMUX\n BASE --> SUB\n BASE --> WSH\n CMD --> AD\n CMD --> REG\n CMD --> PROMPT\n TMUX --> SESS\n SUB --> SESS\n REG --> SESS\n```\n\n### 关键模块职责\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| `BaseBackend` | `clawteam/spawn/base.py` | 定义后端抽象接口 |\n| `TmuxBackend` | `clawteam/spawn/adapters.py` | tmux 会话管理实现 |\n| `SubprocessBackend` | `clawteam/spawn/adapters.py` | 子进程管理实现 |\n| `WshBackend` | `clawteam/spawn/wsh_backend.py` | WebSocket Handler 实现 |\n| `SessionStore` | `clawteam/spawn/sessions.py` | 持久化会话状态管理 |\n| `Registry` | `clawteam/spawn/registry.py` | 智能体注册与发现 |\n| `build_agent_prompt` | `clawteam/spawn/prompt.py` | 生成智能体提示词 |\n\n## 后端适配器架构\n\n### BaseBackend 抽象基类\n\n所有后端必须继承 `BaseBackend` 并实现以下核心方法：\n\n```python\nclass BaseBackend(ABC):\n @abstractmethod\n def spawn(self, command: list[str], **kwargs) -> str:\n \"\"\"启动新智能体进程\"\"\"\n \n @abstractmethod\n def list_running(self) -> list[dict[str, str]]:\n \"\"\"列出运行中的智能体\"\"\"\n \n @abstractmethod\n def inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:\n \"\"\"向运行中的智能体注入消息\"\"\"\n```\n\n资料来源：[clawteam/spawn/base.py:1-20]()\n\n### 支持的后端类型\n\n| 后端 | 说明 | 适用场景 |\n|------|------|----------|\n| `tmux` | 在 tmux 会话中运行智能体 | 长期运行、需要手动调试 |\n| `subprocess` | 直接子进程管理 | 短时任务、容器环境 |\n| `wsh` | WebSocket Handler 块 | 远程/异步通信 |\n\nSpawn 命令示例：\n\n```bash\nclawteam spawn subprocess claude --team dev-team --agent-name builder --agent-type researcher\nclawteam spawn tmux claude --team dev-team --agent-name coder\n```\n\n资料来源：[clawteam/cli/commands.py:50-60]()\n\n## 注册中心机制\n\n### Registry 模块\n\n`Registry` 提供团队内智能体的注册与查询功能：\n\n```python\nfrom clawteam.spawn.registry import register_agent, get_registry\n\nregister_agent(\n team_name=team_name,\n agent_name=agent_name,\n backend=\"wsh\",\n block_id=block_id,\n pid=pane_pid,\n command=list(final_command),\n)\n```\n\n### 注册信息结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `team_name` | str | 团队名称 |\n| `agent_name` | str | 智能体名称 |\n| `backend` | str | 后端类型 |\n| `block_id` | str | 后端特定标识符 |\n| `pid` | int | 进程 ID |\n| `command` | list[str] | 启动命令 |\n\n注册后，智能体可通过 `get_registry(team_name)` 查询：\n\n```python\ninfo = get_registry(team).get(agent_name, {})\nblock_id = info.get(\"block_id\", \"\")\n```\n\n资料来源：[clawteam/spawn/wsh_backend.py:80-90]()\n\n## 会话管理系统\n\n### SessionStore\n\n`SessionStore` 负责持久化管理团队智能体会话状态：\n\n```python\nfrom clawteam.spawn.sessions import SessionStore\n\nsession_store = SessionStore(_team)\nsession = session_store.load(_name)\n```\n\n关键功能：\n\n- **会话持久化**：将智能体会话状态写入磁盘\n- **会话恢复**：支持智能体断点续传\n- **状态查询**：加载历史会话信息\n\n资料来源：[clawteam/spawn/sessions.py:1-30]()\n\n### 会话恢复流程\n\n```mermaid\ngraph LR\n A[加载 SessionStore] --> B{是否存在历史会话?}\n B -->|是| C[获取 session_id]\n C --> D[build_cli_resume_command]\n D --> E[拼接恢复命令]\n E --> F[注入 resume 标志]\n B -->|否| G[正常启动]\n```\n\n```python\nif resume:\n from clawteam.spawn.session_capture import build_resume_command\n \n session = session_store.load(_name)\n if session and session.session_id:\n resumed_command = build_cli_resume_command(\n command, session.session_id, client=client\n )\n if prompt:\n prompt += \"\\nYou are resuming a previous session.\"\n```\n\n资料来源：[clawteam/cli/commands.py:100-115]()\n\n## 提示词构建系统\n\n### build_agent_prompt 函数\n\n`prompt.py` 中的 `build_agent_prompt` 函数负责生成智能体的系统提示词，包含团队上下文信息：\n\n```python\nfrom clawteam.spawn.prompt import build_agent_prompt\n\nprompt = build_agent_prompt(\n agent_name=_name,\n agent_id=_id,\n agent_type=agent_type,\n team_name=_team,\n leader_name=leader_name,\n task=task,\n user=user_name,\n workspace_dir=cwd or \"\",\n workspace_branch=ws_branch,\n isolated_workspace=bool(workspace and cwd),\n repo_path=repo,\n)\n```\n\n### 提示词包含的信息\n\n| 参数 | 说明 |\n|------|------|\n| `agent_name` | 智能体名称 |\n| `agent_id` | 智能体唯一标识 |\n| `agent_type` | 智能体类型（如 researcher、general-purpose） |\n| `team_name` | 所属团队名称 |\n| `leader_name` | 团队领导节点名称 |\n| `task` | 当前任务描述 |\n| `workspace_dir` | 工作目录 |\n| `workspace_branch` | Git 分支 |\n| `isolated_workspace` | 是否使用隔离工作区 |\n| `repo_path` | 仓库路径 |\n\n资料来源：[clawteam/spawn/prompt.py:1-50]()\n\n## 运行时消息注入\n\n### inject_runtime_message 接口\n\n后端实现者必须提供运行时消息注入能力，用于向运行中的智能体发送控制消息：\n\n```python\ndef inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:\n \"\"\"Best-effort runtime injection into a running agent.\"\"\"\n from clawteam.spawn.registry import get_registry\n \n info = get_registry(team).get(agent_name, {})\n block_id = info.get(\"block_id\", \"\") or self._blocks.get(agent_name, \"\")\n \n if not block_id:\n return False, f\"Agent block for '{team}/{agent_name}' not found\"\n \n if not _is_block_alive(block_id):\n return False, f\"Block '{block_id}' is not alive\"\n```\n\n返回值：`tuple[bool, str]` - 成功/失败状态及消息\n\n资料来源：[clawteam/spawn/wsh_backend.py:95-115]()\n\n## CLI 命令集成\n\n### Spawn 命令参数\n\n```bash\nclawteam spawn [options]\n```\n\n| 参数/选项 | 说明 | 默认值 |\n|-----------|------|--------|\n| `backend` | 后端类型（subprocess/tmux） | 必需 |\n| `command` | 智能体启动命令 | 必需 |\n| `--team, -t` | 团队名称 | \"default\" |\n| `--agent-name, -n` | 智能体名称 | 自动生成 |\n| `--agent-type` | 智能体类型 | \"general-purpose\" |\n\n### 完整示例\n\n```bash\n# 在 tmux 后端启动 researcher 类型智能体\nclawteam spawn tmux claude --team dev-team --agent-name researcher --agent-type researcher\n\n# 在 subprocess 后端启动通用智能体\nclawteam spawn subprocess claude-code --team dev-team --agent-name builder\n\n# 使用特定工作目录\nclawteam spawn tmux claude --team docs-team --agent-name writer \\\n --workspace-dir /home/user/project --workspace-branch feature/docs\n```\n\n资料来源：[clawteam/cli/commands.py:45-75]()\n\n## 智能体生命周期\n\n```mermaid\ngraph TD\n A[Spawn 命令] --> B[注册到 Registry]\n B --> C[创建 Session]\n C --> D[构建 Prompt]\n D --> E[调用后端 spawn]\n E --> F{后端类型}\n F -->|tmux| G[创建 tmux session]\n F -->|subprocess| H[fork 子进程]\n F -->|wsh| I[创建 wsh block]\n G --> J[启动智能体]\n H --> J\n I --> J\n J --> K[智能体运行中]\n K --> L[可接收消息注入]\n K --> M[可更新任务状态]\n L --> N[生命周期结束]\n M --> N\n```\n\n## 数据存储布局\n\nSpawn 系统相关的持久化数据存储在 `~/.clawteam/` 目录下：\n\n```\n~/.clawteam/\n├── teams/{team}/\n│ ├── config.json # 团队配置\n│ └── inboxes/{agent}/ # 智能体收件箱\n├── sessions/{team}/\n│ └── {agent}.json # 会话状态文件\n└── registry/\n └── {team}.json # 智能体注册信息\n```\n\n## 与其他模块的交互\n\n### 团队模块集成\n\nSpawn 系统依赖团队模块提供的领导节点信息：\n\n```python\n# 获取团队领导名称\ntmpl = load_template(\"default\")\nleader_name = tmpl.leader.name\n\n# 判断当前智能体是否为领导\nis_leader = agent.name == tmpl.leader.name\n```\n\n### 任务模块集成\n\nSpawn 后的智能体可更新任务状态：\n\n```bash\nclawteam task update dev-team --status completed\n```\n\n### 生命周期模块集成\n\n智能体完成任务后可发送空闲通知：\n\n```bash\nclawteam lifecycle idle dev-team --last-task --task-status completed\n```\n\n## 扩展新的后端\n\n如需添加新的后端（如 Docker、Kubernetes），需：\n\n1. 继承 `BaseBackend` 抽象类\n2. 实现 `spawn`、`list_running`、`inject_runtime_message` 方法\n3. 在 `adapters.py` 或独立文件中实现\n4. 在 CLI 命令解析中注册新后端\n\n```python\nclass DockerBackend(BaseBackend):\n def spawn(self, command: list[str], **kwargs) -> str:\n container_id = self._create_container(command, **kwargs)\n return f\"Agent spawned in container {container_id}\"\n \n def list_running(self) -> list[dict[str, str]]:\n # 返回运行中的容器\n pass\n \n def inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:\n # 向容器内进程发送信号\n pass\n```\n\n## 最佳实践\n\n1. **使用 tmux 后端进行调试**：tmux 后端支持手动 attach 查看智能体输出\n2. **使用 subprocess 后端进行 CI/CD**：适合无头环境\n3. **充分利用会话恢复**：长时间任务建议使用 `--resume` 标志\n4. **正确设置智能体类型**：有助于团队任务分配和资源调度\n5. **配合任务系统使用**：Spawn 后立即创建任务并分配给智能体\n\n## 总结\n\n智能体 Spawn 系统是 ClawTeam 实现多智能体协作的基础设施，通过模块化的后端适配器、统一的注册中心、持久化的会话管理和智能的提示词注入，使得主控节点能够灵活地启动、管理和协调各类外部编码智能体。该系统的设计遵循开闭原则，便于扩展新的运行时后端，同时与团队管理、任务调度、消息通信等模块无缝集成，共同构建完整的智能体编排平台。\n\n---\n\n\n\n## Spawn 后端实现\n\n### 相关页面\n\n相关主题：[智能体 Spawn 系统](#page-spawn-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [clawteam/spawn/wsh_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/wsh_backend.py)\n- [clawteam/spawn/registry.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/registry.py)\n- [clawteam/spawn/sessions.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/sessions.py)\n- [clawteam/spawn/session_capture.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/session_capture.py)\n- [clawteam/cli/commands.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/cli/commands.py)\n \n\n# Spawn 后端实现\n\n## 概述\n\nSpawn 后端是 ClawTeam 系统中负责在团队环境中启动和管理外部 AI Agent 进程的核心组件。它提供了一套统一的抽象接口，支持多种底层进程管理方式（如 tmux、subprocess、wsh），使团队协调层能够独立于具体执行后端工作。\n\nSpawn 模块的职责包括：\n\n- 为新启动的 Agent 注入团队身份环境变量（`CLAWTEAM_AGENT_ID`、`CLAWTEAM_AGENT_NAME`、`CLAWTEAM_TEAM` 等）\n- 管理 Agent 的生命周期（启动、监控、终止）\n- 支持会话恢复（session resume）功能\n- 与模板系统（Template）集成，支持批量启动团队成员\n\n资料来源：[clawteam/cli/commands.py:1-50]()\n\n## 架构设计\n\n### 整体架构图\n\n```mermaid\ngraph TD\n subgraph \"CLI 层\"\n CLI[clawteam spawn 命令]\n Launch[clawteam launch 命令]\n end\n \n subgraph \"Spawn 核心\"\n Registry[Agent 注册表]\n SessionStore[会话存储]\n PromptBuilder[提示词构建]\n end\n \n subgraph \"后端实现层\"\n TMuxBackend[tmux_backend.py]\n SubprocessBackend[subprocess_backend.py]\n WshBackend[wsh_backend.py]\n end\n \n subgraph \"底层执行\"\n TMux[tmux 会话]\n Process[子进程]\n WshBlocks[wsh blocks]\n end\n \n CLI --> Registry\n CLI --> PromptBuilder\n Launch --> TMuxBackend\n Launch --> SubprocessBackend\n Launch --> WshBackend\n TMuxBackend --> TMux\n SubprocessBackend --> Process\n WshBackend --> WshBlocks\n Registry --> SessionStore\n```\n\n### 后端抽象基类\n\nSpawn 系统采用后端插件化设计，所有后端需实现统一的接口：\n\n| 方法 | 功能 | 返回值 |\n|------|------|--------|\n| `spawn(command, team, agent_name, ...)` | 启动 Agent 进程 | 启动结果描述字符串 |\n| `list_running()` | 列出运行中的 Agent | `List[Dict[str, str]]` |\n| `inject_runtime_message(team, agent, envelope)` | 向运行中的 Agent 注入消息 | `(bool, str)` |\n\n资料来源：[clawteam/spawn/wsh_backend.py:30-60]()\n\n## tmux 后端实现\n\ntmux 后端通过创建独立的 tmux 会话来隔离每个 Agent 的运行环境。\n\n### 核心流程\n\n1. 构建 tmux 命令，包含会话命名和窗口配置\n2. 使用 `tmux new-session` 创建新会话\n3. 向新会话发送 Agent 启动命令\n4. 注册 Agent 信息到全局注册表\n5. 持久化会话捕获数据\n\n### 会话隔离策略\n\n每个 Agent 在独立的 tmux 会话中运行，会话命名格式为 `clawteam-{team}-{agent}`。这种隔离确保：\n\n- 一个 Agent 的输出不会干扰其他 Agent\n- 可以独立 attach/detach 到特定 Agent 会话\n- Agent 崩溃不会影响团队其他成员\n\n资料来源：[clawteam/spawn/session_capture.py]()\n\n## subprocess 后端实现\n\nsubprocess 后端直接通过 Python 的 `subprocess` 模块启动子进程，适合轻量级或无持久化需求的场景。\n\n### 特性\n\n- 支持 stdout/stderr 管道捕获\n- 可配置工作目录（CWD）\n- 支持环境变量注入\n- 适合短生命周期任务\n\n## wsh 后端实现\n\nwsh（WezTerm Shell）后端是 ClawTeam 针对 WezTerm 终端仿真器的专用实现，利用 WezTerm 的 pane 和 RPC 功能实现高级交互。\n\n### WshBackend 核心功能\n\n```python\nclass WshBackend:\n def spawn(self, ...) -> str:\n \"\"\"启动 wsh block 中的 Agent\"\"\"\n \n def list_running(self) -> list[dict[str, str]]:\n \"\"\"列出当前运行的 wsh block\"\"\"\n \n def inject_runtime_message(self, team, agent_name, envelope) -> tuple[bool, str]:\n \"\"\"向运行中的 wsh block 注入运行时消息\"\"\"\n```\n\n资料来源：[clawteam/spawn/wsh_backend.py:1-100]()\n\n### RPC 消息注入\n\nwsh 后端支持向已启动的 Agent 实时注入消息，流程如下：\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI 命令\n participant Registry as Agent 注册表\n participant WshRPC as WshRpcClient\n participant Block as wsh Block\n\n CLI->>Registry: 查询 agent 对应的 block_id\n Registry-->>CLI: block_id\n CLI->>WshRPC: inject_runtime_message(envelope)\n WshRPC->>Block: 发送渲染后的通知\n Block-->>WshRPC: 确认\n WshRPC-->>CLI: (True, \"success\")\n```\n\n资料来源：[clawteam/spawn/wsh_rpc.py]()\n\n## Agent 注册与追踪\n\n### 注册表机制\n\nClawTeam 使用集中式注册表管理所有已启动的 Agent 实例：\n\n```python\nregister_agent(\n team_name=team_name,\n agent_name=agent_name,\n backend=\"wsh\",\n block_id=block_id,\n pid=pane_pid,\n command=list(final_command),\n)\n```\n\n注册信息包括：\n\n| 字段 | 说明 |\n|------|------|\n| `team_name` | 团队名称 |\n| `agent_name` | Agent 标识符 |\n| `backend` | 使用的后端类型 |\n| `block_id` | 后端特定资源标识 |\n| `pid` | 进程 ID |\n| `command` | 启动命令 |\n\n资料来源：[clawteam/spawn/registry.py]()\n\n### 会话持久化\n\nSpawn 模块支持会话捕获和恢复：\n\n```python\npersist_spawned_session(\n session_capture,\n team_name=team_name,\n agent_name=agent_name,\n command=list(final_command),\n)\n```\n\n会话存储允许：\n\n- 保存 Agent 的完整命令历史\n- 支持后续会话恢复（resume）\n- 记录 Agent 状态快照\n\n资料来源：[clawteam/spawn/sessions.py]()\n\n## 与其他模块的集成\n\n### 与模板系统集成\n\nSpawn 与模板系统（`clawteam/templates/`）深度集成，支持通过模板定义团队结构：\n\n```python\n# 从模板加载后，使用 spawn 批量启动\nspawned.append({\n \"name\": agent.name,\n \"id\": a_id,\n \"type\": agent.type,\n \"result\": spawn_result\n})\n```\n\n资料来源：[clawteam/templates/__init__.py]()\n\n### 与 CLI 命令集成\n\nSpawn 功能通过 `clawteam spawn` 和 `clawteam launch` 命令暴露给用户：\n\n| 命令 | 功能 |\n|------|------|\n| `clawteam spawn ` | 启动单个 Agent |\n| `clawteam launch --template ` | 从模板启动整个团队 |\n\n参数配置：\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--team, -t` | `\"default\"` | 团队名称 |\n| `--agent-name, -n` | 自动生成 | Agent 名称 |\n| `--agent-type` | `\"general-purpose\"` | Agent 类型 |\n\n资料来源：[clawteam/cli/commands.py]()\n\n## 会话恢复机制\n\n### Resume 流程\n\nSpawn 模块支持从上次中断点恢复 Agent 会话：\n\n1. 检测 `--resume` 参数\n2. 从 SessionStore 加载历史会话数据\n3. 根据原始客户端类型构建恢复命令\n4. 注入会话 ID 和客户端标识\n\n```python\nif resume:\n session = session_store.load(_name)\n if session and session.session_id:\n resumed_command = build_cli_resume_command(command, session.session_id, client=client)\n prompt += \"\\nYou are resuming a previous session.\"\n```\n\n资料来源：[clawteam/spawn/sessions.py]()\n\n## 配置选项\n\n### Spawn 启动参数\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `backend` | str | `\"tmux\"` | 进程后端类型 |\n| `command` | List[str] | `[\"claude\"]` | Agent 启动命令 |\n| `team_name` | str | `\"default\"` | 团队名称 |\n| `agent_name` | str | None | Agent 标识 |\n| `agent_type` | str | `\"general-purpose\"` | Agent 类型 |\n| `profile` | str | None | 使用的运行时配置 |\n| `skill` | List[str] | None | 加载的技能列表 |\n| `workspace` | str | None | 工作空间目录 |\n| `skip_permissions` | bool | False | 跳过权限检查 |\n\n### 环境变量注入\n\nSpawn 自动向启动的 Agent 注入以下环境变量：\n\n| 变量名 | 说明 |\n|--------|------|\n| `CLAWTEAM_AGENT_ID` | 唯一 Agent 标识符 |\n| `CLAWTEAM_AGENT_NAME` | Agent 显示名称 |\n| `CLAWTEAM_AGENT_TYPE` | Agent 类型 |\n| `CLAWTEAM_TEAM` | 所属团队名称 |\n| `CLAWTEAM_LEADER_ID` | 团队 Leader ID |\n\n## 扩展新的后端\n\n要添加新的 Spawn 后端，需实现以下接口：\n\n```python\nclass BaseBackend:\n def spawn(\n self,\n command: List[str],\n team_name: str,\n agent_name: str,\n **kwargs\n ) -> str:\n \"\"\"启动 Agent 进程，返回启动描述\"\"\"\n raise NotImplementedError\n \n def list_running(self) -> List[Dict[str, str]]:\n \"\"\"返回运行中的 Agent 列表\"\"\"\n raise NotImplementedError\n \n def inject_runtime_message(\n self, \n team: str, \n agent_name: str, \n envelope\n ) -> tuple[bool, str]:\n \"\"\"向运行中的 Agent 注入消息\"\"\"\n raise NotImplementedError\n```\n\n注册新后端时，需要在 `clawteam/spawn/backends.py` 中添加入口点映射。\n\n---\n\n\n\n## 团队生命周期管理\n\n### 相关页面\n\n相关主题：[任务管理与依赖链](#page-task-dependencies), [智能体间消息通信](#page-messaging), [智能体 Spawn 系统](#page-spawn-system)\n\n\n相关源码文件
\n\n以下源码文件用于尝试生成本页说明：\n\n- [clawteam/team/manager.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/manager.py) ⚠️ 未在当前上下文检索到\n- [clawteam/team/lifecycle.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/lifecycle.py) ⚠️ 未在当前上下文检索到\n- [clawteam/team/models.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/models.py) ⚠️ 未在当前上下文检索到\n- [clawteam/team/leader_watcher.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/leader_watcher.py) ⚠️ 未在当前上下文检索到\n- [clawteam/team/snapshot.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/snapshot.py) ⚠️ 未在当前上下文检索到\n\n**注意**：以下页面内容基于实际检索到的源码文件生成，而非上述指定文件。\n\n以下源码文件实际用于生成本页说明：\n\n- [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n- [skills/clawteam/references/workflows.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/workflows.md)\n- [clawteam/team/tasks.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/tasks.py)\n- [clawteam/spawn/wsh_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/wsh_backend.py)\n- [clawteam/cli/commands.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/cli/commands.py)\n \n\n# 团队生命周期管理\n\n## 概述\n\nClawTeam 的团队生命周期管理是一个多代理协作框架，负责协调代理（Agent）的创建、任务分配、团队治理和优雅关闭的全过程。该系统通过 CLI 命令驱动，支持任务依赖链、会话持久化和基于消息的代理间通信。\n\n**核心职责范围：**\n\n- 团队的创建、发现和状态监控\n- 代理的 Spawn（生成）与注册\n- 任务的创建、更新和依赖管理\n- 团队成员间的消息传递与计划审批\n- 优雅关闭流程（Graceful Shutdown）\n- 领导选举与心跳监控\n\n**资料来源：** [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n\n---\n\n## 团队创建与发现\n\n### 创建团队\n\n使用 `spawn-team` 命令创建一个新团队并注册领导者代理：\n\n```bash\nclawteam team spawn-team [options]\n```\n\n| 参数/选项 | 说明 | 默认值 |\n|-----------|------|--------|\n| `name` | 团队名称 | 必填 |\n| `--description, -d` | 团队描述 | `\"\"` |\n| `--agent-name, -n` | 领导者代理名称 | `\"leader\"` |\n| `--agent-type` | 领导者代理类型 | `\"leader\"` |\n\n**示例：**\n\n```bash\nclawteam team spawn-team dev-team -d \"Backend development team\" -n alice\n```\n\n该命令会创建团队配置文件，并将指定代理注册为团队领导者。\n\n### 发现团队\n\n列出所有现有团队及其元数据：\n\n```bash\nclawteam team discover\nclawteam --json team discover\n```\n\n返回每个团队的名称、描述、领导代理 ID 和成员数量。\n\n**资料来源：** [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n\n---\n\n## 代理生命周期\n\n### Spawn 代理\n\nSpawn 命令用于在新进程中启动代理，并自动注入团队环境变量：\n\n```bash\nclawteam spawn [options]\n```\n\n| 选项 | 说明 | 默认值 |\n|------|------|--------|\n| `--team, -t` | 团队名称 | `\"default\"` |\n| `--agent-name, -n` | 代理名称 | 自动生成 |\n| `--agent-type` | 代理类型 | `\"general-purpose\"` |\n\n**支持的后端：**\n\n| 后端 | 说明 |\n|------|------|\n| `subprocess` | 子进程模式 |\n| `tmux` | tmux 会话模式 |\n\n**示例：**\n\n```bash\nclawteam spawn subprocess claude --team dev-team --agent-name bob --agent-type researcher\n```\n\nSpawn 时系统会自动：\n\n1. 注册代理到团队注册表\n2. 创建持久化的会话记录\n3. 返回代理名称和会话信息\n\n**资料来源：** [clawteam/spawn/wsh_backend.py:1-50](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/wsh_backend.py)\n\n### 代理身份管理\n\n每个代理运行时必须设置身份环境变量：\n\n```bash\nexport CLAWTEAM_AGENT_ID=\"leader-001\"\nexport CLAWTEAM_AGENT_NAME=\"leader\"\nexport CLAWTEAM_AGENT_TYPE=\"leader\"\n```\n\n使用 `identity` 命令查看或设置身份：\n\n```bash\n# 查看当前身份\nclawteam identity show\n\n# 打印环境变量设置命令\neval $(clawteam identity set --agent-name alice --team dev-team)\n```\n\n**资料来源：** [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n\n---\n\n## 任务管理\n\n### 任务数据模型\n\n任务支持以下状态：\n\n| 状态 | 说明 |\n|------|------|\n| `pending` | 未开始 |\n| `in_progress` | 进行中 |\n| `completed` | 已完成（自动解除依赖） |\n| `blocked` | 等待其他任务 |\n\n任务支持优先级设置：`low`、`medium`、`high`、`urgent`。\n\n**资料来源：** [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n\n### 创建任务\n\n```bash\nclawteam task create [options]\n```\n\n| 选项 | 说明 | 默认值 |\n|------|------|--------|\n| `--owner, -o` | 任务负责人 | `None` |\n| `--description, -d` | 任务描述 | `\"\"` |\n| `--priority, -p` | 优先级 | `medium` |\n| `--blocks` | 该任务阻塞的任务 ID | `None` |\n| `--blocked-by` | 阻塞该任务的任务 ID | `None` |\n\n**示例：**\n\n```bash\nclawteam task create dev-team \"Implement auth\" -o alice -d \"Add JWT authentication\"\n```\n\n### 更新任务\n\n```bash\nclawteam task update [options]\n```\n\n| 选项 | 说明 |\n|------|------|\n| `--status, -s` | 新状态 |\n| `--owner, -o` | 新负责人 |\n| `--priority, -p` | 新优先级 |\n| `--add-blocks` | 添加阻塞的任务 |\n| `--add-blocked-by` | 添加阻塞该任务的任务 |\n| `--force, -f` | 强制覆盖任务锁 |\n\n当任务标记为 `completed` 时，所有被该任务阻塞的任务会自动解除阻塞（从 `blocked` 变为 `pending`）。\n\n### 列出任务\n\n```bash\nclawteam task list [--status STATUS] [--owner NAME] [--priority LEVEL] [--sort-priority]\n```\n\n### 任务存储实现\n\n任务存储采用文件系统后端：\n\n> This module preserves the historic ``clawteam.team.tasks`` import path while delegating the implementation to :mod:`clawteam.store`.\n\n```python\nfrom clawteam.store.base import BaseTaskStore, TaskLockError\nfrom clawteam.store.file import FileTaskStore\n\nTaskStore = FileTaskStore\n```\n\n**资料来源：** [clawteam/team/tasks.py:1-20](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/tasks.py)\n\n---\n\n## 团队状态与看板\n\n### 查看团队状态\n\n```bash\nclawteam team status \n```\n\n显示团队配置和成员列表。\n\n### 看板命令\n\n| 命令 | 说明 |\n|------|------|\n| `board show` | 显示团队看板详情 |\n| `board overview` | 显示所有团队概览表 |\n| `board live` | 实时刷新的看板（可设置间隔） |\n\n```bash\nclawteam board show \nclawteam board live [--interval 2.0]\n```\n\n**资料来源：** [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n\n---\n\n## 消息类型系统\n\n代理间通过消息进行通信，支持以下消息类型：\n\n| 消息类型 | 说明 |\n|----------|------|\n| `message` | 点对点消息 |\n| `broadcast` | 广播给所有成员 |\n| `join_request` | 加入团队请求 |\n| `join_approved` | 加入请求被批准 |\n| `join_rejected` | 加入请求被拒绝 |\n| `plan_approval_request` | 提交计划供审批 |\n| `plan_approved` | 计划被批准 |\n| `plan_rejected` | 计划被拒绝 |\n| `shutdown_request` | 关闭请求 |\n| `shutdown_approved` | 关闭被批准 |\n| `shutdown_rejected` | 关闭被拒绝 |\n| `idle` | 代理空闲通知 |\n\n### 加入团队流程\n\n```bash\n# 请求加入\nclawteam team request-join [options]\n\n# 领导者批准\nclawteam team approve-join [--assigned-name NAME]\n\n# 领导者拒绝\nclawteam team reject-join \n```\n\n| 选项 | 说明 | 默认值 |\n|------|------|--------|\n| `--capabilities, -c` | 代理能力描述 | `\"\"` |\n| `--timeout, -t` | 超时时间（秒） | `60` |\n\n**资料来源：** [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n\n---\n\n## 优雅关闭流程\n\n### 关闭状态机\n\n```mermaid\ngraph TD\n A[Running] -->|request-shutdown| B[Shutdown Pending]\n B -->|approve-shutdown| C[Shutting Down]\n B -->|reject-shutdown| D[Running Resumed]\n C -->|Process Exit| E[Terminated]\n \n A -->|idle| F[Idle]\n F -->|New Task| A\n```\n\n### 关闭命令\n\n**请求关闭：**\n\n```bash\nclawteam lifecycle request-shutdown [--reason TEXT]\n```\n\n**批准关闭：**\n\n```bash\nclawteam lifecycle approve-shutdown \n```\n\n**拒绝关闭：**\n\n```bash\nclawteam lifecycle reject-shutdown [--reason TEXT]\n```\n\n### 空闲通知\n\n当代理没有更多工作时，发送空闲通知给领导者：\n\n```bash\nclawteam lifecycle idle [--last-task ID] [--task-status STATUS]\n```\n\n**资料来源：** [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n\n---\n\n## 计划审批流程\n\n### 计划提交\n\n```bash\nclawteam plan submit [--summary TEXT]\n```\n\n内容可以是内联文本或文件路径。\n\n### 计划审批\n\n```bash\n# 批准计划\nclawteam plan approve [--feedback TEXT]\n\n# 拒绝计划\nclawteam plan reject [--feedback TEXT]\n```\n\n**资料来源：** [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n\n---\n\n## 团队启动工作流\n\n从模板启动团队的完整流程：\n\n```bash\n# 1. 设置领导者身份\nexport CLAWTEAM_AGENT_ID=\"leader-001\"\nexport CLAWTEAM_AGENT_NAME=\"leader\"\nexport CLAWTEAM_AGENT_TYPE=\"leader\"\n\n# 2. 从模板启动团队（包含多个代理）\nclawteam launch --backend tmux --team \n```\n\n启动流程会自动：\n\n1. 加载团队模板\n2. 为每个代理设置环境变量\n3. Spawn 代理进程\n4. 注册到团队注册表\n5. 输出启动摘要\n\n**输出示例：**\n\n```\nTeam 'dev-team' launched from template 'default'\n\nAgents:\n Name Type ID\n leader leader leader-001\n worker1 worker worker-001\n\nAttach: tmux attach -t clawteam-dev-team\nBoard: clawteam board show dev-team\nInbox: clawteam inbox peek dev-team --agent \n```\n\n**资料来源：** [clawteam/cli/commands.py:1-80](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/cli/commands.py)\n\n---\n\n## 文件存储布局\n\n团队数据存储在 `~/.clawteam/` 目录下：\n\n```\n~/.clawteam/\n├── teams/{team}/\n│ ├── config.json # 团队配置（名称、成员、领导者）\n│ └── inboxes/{agent}/ # 消息文件（msg-{timestamp}-{uuid}.json）\n├── tasks/{team}/\n│ └── task-{id}.json # 单独的任务文件\n└── plans/\n └── {agent}-{id}.md # 计划文档\n```\n\n**资料来源：** [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n\n---\n\n## 任务依赖工作流示例\n\n```mermaid\ngraph LR\n A[T-001 设计系统] --> B[T-002 实现后端]\n A --> C[T-003 实现前端]\n B --> D[T-004 集成测试]\n C --> D\n \n style A fill:#90EE90\n style B fill:#FFD700\n style C fill:#FFD700\n style D fill:#D3D3D3\n```\n\n**命令序列：**\n\n```bash\n# 1. 创建任务\nclawteam task create my-team \"Design system\" -o leader\n# => Task ID: aaa11111\n\n# 2. 创建依赖任务\nclawteam task create my-team \"Implement backend\" -o worker1 --blocked-by aaa11111\n# => Task ID: bbb22222（自动设置为 blocked 状态）\n\nclawteam task create my-team \"Build frontend\" -o worker2 --blocked-by aaa11111\n# => Task ID: ccc33333（自动设置为 blocked 状态）\n\n# 3. 完成前置任务\nclawteam task update my-team aaa11111 --status completed\n# bbb22222 和 ccc33333 自动解除阻塞\n```\n\n**资料来源：** [skills/clawteam/references/workflows.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/workflows.md)\n\n---\n\n## 总结\n\nClawTeam 的团队生命周期管理涵盖：\n\n| 阶段 | 核心命令 | 关键功能 |\n|------|----------|----------|\n| 创建 | `spawn-team` | 注册领导者和团队配置 |\n| 发现 | `discover` | 列出可用团队 |\n| 启动 | `spawn` | 生成代理进程并注册 |\n| 协调 | `task create/update` | 任务分配和依赖管理 |\n| 监控 | `board show` | 看板可视化 |\n| 通信 | `message/broadcast` | 代理间消息传递 |\n| 审批 | `plan submit/approve` | 计划审批工作流 |\n| 关闭 | `request-shutdown` | 优雅关闭流程 |\n\n---\n\n\n\n## 任务管理与依赖链\n\n### 相关页面\n\n相关主题：[团队生命周期管理](#page-team-management), [智能体间消息通信](#page-messaging)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [clawteam/team/tasks.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/tasks.py)\n- [clawteam/store/base.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/store/base.py)（从 tasks.py 导入）\n- [clawteam/store/file.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/store/file.py)（实际实现）\n- [clawteam/mcp/tools/task.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/mcp/tools/task.py)\n- [clawteam/harness/context_recovery.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/harness/context_recovery.py)\n- [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n- [skills/clawteam/references/workflows.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/workflows.md)\n \n\n# 任务管理与依赖链\n\n## 概述\n\n任务管理与依赖链是 ClawTeam 协作框架的核心子系统，负责协调多智能体团队中的工作分配、状态追踪和执行顺序控制。该模块使团队能够创建结构化的任务网络，通过依赖关系确保任务按照正确的顺序执行，并支持看板式的可视化工作流管理。\n\nClawTeam 的任务系统基于文件系统存储，通过统一的 `TaskStore` 接口提供增删改查功能，并自动处理任务间的依赖解除逻辑。资料来源：[clawteam/team/tasks.py:1-14]()\n\n## 核心架构\n\n### 存储层次\n\n```\nclawteam.team.tasks (兼容性垫片)\n │\n ▼\nclawteam.store.base (BaseTaskStore 接口定义)\n │\n ▼\nclawteam.store.file (FileTaskStore 具体实现)\n │\n ▼\n~/.clawteam/tasks/{team}/task-{id}.json (持久化文件)\n```\n\n资料来源：[clawteam/team/tasks.py:1-14]()\n\n### 关键类导出\n\n| 类/异常 | 说明 | 来源 |\n|---------|------|------|\n| `BaseTaskStore` | 任务存储抽象基类，定义接口规范 | [clawteam/store/base.py]() |\n| `TaskStore` | 实际使用的 `FileTaskStore` 别名 | [clawteam/team/tasks.py:11]() |\n| `TaskLockError` | 任务锁定冲突时抛出的异常 | [clawteam/team/tasks.py:6]() |\n\n## 数据模型\n\n### 任务状态\n\n| 状态 | 说明 | 行为 |\n|------|------|------|\n| `pending` | 任务未开始，等待执行 | 可被依赖任务自动解除 |\n| `in_progress` | 任务正在执行中 | 独占锁定，防止并发修改 |\n| `completed` | 任务已完成 | 自动解除所有依赖该任务的其他任务的阻塞状态 |\n| `blocked` | 任务被阻塞，等待前置任务完成 | 当所有 blocker 完成后自动转为 `pending` |\n\n资料来源：[skills/clawteam/references/cli-reference.md](skills/clawteam/references/cli-reference.md)\n\n### 任务结构\n\n```json\n{\n \"id\": \"aaa11111\",\n \"subject\": \"Design API schema\",\n \"description\": \"Create REST API specification\",\n \"owner\": \"backend-dev\",\n \"status\": \"pending\",\n \"priority\": \"medium\",\n \"blocks\": [],\n \"blocked_by\": [],\n \"created_at\": \"2024-01-15T10:30:00Z\"\n}\n```\n\n## 依赖链机制\n\n### 工作原理\n\n依赖链允许任务声明对其他任务的依赖关系（`blocked_by`），确保前置任务完成后，后置任务才能执行。\n\n```mermaid\ngraph LR\n A[T-001 设计架构] -->|blocked_by| B[T-002 后端实现]\n A[T-001 设计架构] -->|blocked_by| C[T-003 前端开发]\n B -->|blocked_by| D[T-004 集成测试]\n C -->|blocked_by| D[T-004 集成测试]\n```\n\n资料来源：[skills/clawteam/references/workflows.md](skills/clawteam/references/workflows.md)\n\n### 自动解除阻塞\n\n当任务状态变为 `completed` 时，系统自动检查所有依赖该任务的其他任务：\n\n1. 遍历依赖列表中的每个任务\n2. 检查该任务的 `blocked_by` 集合\n3. 如果所有 blocker 都已完成，将该任务状态从 `blocked` 更新为 `pending`\n4. 释放任务锁，允许新所有者接管\n\n```bash\n# 示例：完成后自动解除阻塞\nclawteam task update my-project aaa11111 --status completed\n# bbb22222 和 ccc33333 自动从 blocked -> pending\n```\n\n资料来源：[skills/clawteam/references/cli-reference.md](skills/clawteam/references/cli-reference.md)\n\n## CLI 命令接口\n\n### 创建任务\n\n```bash\nclawteam task create [options]\n```\n\n| 选项 | 说明 | 默认值 |\n|------|------|--------|\n| `--owner, -o` | 任务负责人 | `None` |\n| `--description, -d` | 任务详细描述 | `\"\"` |\n| `--priority, -p` | 优先级：low, medium, high, urgent | `medium` |\n| `--blocks` | 任务 ID 列表（此任务完成后解除） | `None` |\n| `--blocked-by` | 任务 ID 列表（阻塞此任务） | `None` |\n\n**示例**：\n\n```bash\n# 创建基础任务\nclawteam task create dev-team \"Design system\" -o leader\n\n# 创建依赖链\nclawteam task create my-project \"Implement backend\" -o dev1 --blocked-by aaa11111\nclawteam task create my-project \"Build frontend\" -o dev2 --blocked-by aaa11111\nclawteam task create my-project \"Integration tests\" --blocked-by bbb22222,ccc33333\n```\n\n资料来源：[skills/clawteam/references/cli-reference.md](skills/clawteam/references/cli-reference.md)\n\n### 更新任务\n\n```bash\nclawteam task update [options]\n```\n\n| 选项 | 说明 |\n|------|------|\n| `--status, -s` | 新状态：pending, in_progress, completed, blocked |\n| `--owner, -o` | 新负责人 |\n| `--subject` | 新主题 |\n| `--description, -d` | 新描述 |\n| `--priority, -p` | 新优先级 |\n| `--add-blocks` | 添加阻塞的任务 ID（逗号分隔） |\n| `--add-blocked-by` | 添加阻塞此任务的任务 ID |\n| `--force, -f` | 强制覆盖任务锁 |\n\n**关键行为**：使用 `--status completed` 会自动触发依赖解除逻辑。资料来源：[skills/clawteam/references/cli-reference.md](skills/clawteam/references/cli-reference.md)\n\n### 查询任务\n\n```bash\n# 获取单个任务详情\nclawteam task get \n\n# 列出团队所有任务（支持过滤）\nclawteam task list [--status STATUS] [--owner NAME] [--priority LEVEL] [--sort-priority]\n```\n\n## MCP 工具集成\n\nClawTeam 提供 MCP（Model Context Protocol）工具接口，允许 AI 智能体直接通过工具调用操作任务系统。资料来源：[clawteam/mcp/tools/task.py]()\n\n### 工具能力\n\n- `task_create`: 创建新任务并设置依赖\n- `task_update`: 更新任务状态和属性\n- `task_get`: 获取单个任务详情\n- `task_list`: 列出并过滤任务\n- `task_delete`: 删除任务（谨慎使用）\n\n### 智能体上下文恢复\n\n在多智能体协作场景中，`context_recovery.py` 模块利用任务系统为智能体提供团队状态摘要：\n\n```python\nfrom clawteam.team.models import TaskStatus\nfrom clawteam.team.tasks import TaskStore\n\nstore = TaskStore(team_name)\ntasks = store.list_tasks()\n\n# 按负责人分组统计\nowner_status: dict[str, tuple[int, int]] = {}\nfor t in tasks:\n if t.owner and t.owner != agent_name:\n done, total = owner_status.get(t.owner, (0, 0))\n total += 1\n if t.status == TaskStatus.completed:\n done += 1\n owner_status[t.owner] = (done, total)\n```\n\n资料来源：[clawteam/harness/context_recovery.py]()\n\n## 完整工作流示例\n\n### 场景：Web 应用开发团队\n\n```bash\n# 1. 设置领导者身份\nexport CLAWTEAM_AGENT_ID=\"leader-001\"\nexport CLAWTEAM_AGENT_NAME=\"leader\"\nexport CLAWTEAM_AGENT_TYPE=\"leader\"\n\n# 2. 创建团队\nclawteam team spawn-team web-project -d \"Web 应用开发\" -n leader\n\n# 3. 创建任务依赖链\nclawteam task create web-project \"设计系统架构\" -o leader\n# => 任务 ID: arch-001\n\nclawteam task create web-project \"实现后端 API\" -o backend-dev --blocked-by arch-001\n# => 任务 ID: backend-001 (自动设为 blocked)\n\nclawteam task create web-project \"开发前端界面\" -o frontend-dev --blocked-by arch-001\n# => 任务 ID: frontend-001 (自动设为 blocked)\n\nclawteam task create web-project \"集成测试\" --blocked-by backend-001,frontend-001\n# => 任务 ID: test-001\n\n# 4. 查看看板\nclawteam board show web-project\n\n# 5. 架构完成后，自动解除阻塞\nclawteam task update web-project arch-001 --status completed\n# backend-dev 和 frontend-dev 的任务自动变为 pending\n\n# 6. 后端和前端都完成后，测试任务解除阻塞\nclawteam task update web-project backend-001 --status completed\nclawteam task update web-project frontend-001 --status completed\n# test-001 自动从 blocked 变为 pending\n```\n\n资料来源：[skills/clawteam/references/workflows.md](skills/clawteam/references/workflows.md)\n\n## 持久化存储\n\n### 文件结构\n\n```\n~/.clawteam/\n└── tasks/\n └── {team}/\n └── task-{id}.json # 单个任务文件\n```\n\n每个任务以 JSON 格式独立存储在对应团队的目录下，便于版本控制和团队间迁移。资料来源：[skills/clawteam/references/cli-reference.md](skills/clawteam/references/cli-reference.md)\n\n### 任务文件格式\n\n```json\n{\n \"id\": \"task-xxx\",\n \"subject\": \"任务标题\",\n \"description\": \"任务描述\",\n \"owner\": \"负责人名称\",\n \"status\": \"pending|in_progress|completed|blocked\",\n \"priority\": \"low|medium|high|urgent\",\n \"blocks\": [\"被此任务阻塞的任务ID\"],\n \"blocked_by\": [\"阻塞此任务的任务ID\"],\n \"created_at\": \"ISO时间戳\",\n \"updated_at\": \"ISO时间戳\"\n}\n```\n\n## 最佳实践\n\n1. **最小化依赖深度**：依赖链过长会增加调试难度，建议控制在 3-4 层以内\n2. **明确负责人**：每个任务都应指定明确的负责人，避免责任真空\n3. **及时更新状态**：智能体完成任务后应立即更新状态，确保依赖链正确推进\n4. **使用看板监控**：定期使用 `clawteam board show` 或 `clawteam board live` 监控团队进度\n5. **优先级梯度**：使用 priority 选项确保关键路径上的任务优先处理\n\n---\n\n\n\n## 智能体间消息通信\n\n### 相关页面\n\n相关主题：[团队生命周期管理](#page-team-management), [任务管理与依赖链](#page-task-dependencies)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [clawteam/team/mailbox.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/mailbox.py)\n- [clawteam/team/router.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/team/router.py)\n- [clawteam/mcp/tools/mailbox.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/mcp/tools/mailbox.py)\n- [clawteam/transport/file.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/transport/file.py)\n- [clawteam/store/file.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/store/file.py)\n- [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n- [skills/clawteam/references/workflows.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/workflows.md)\n \n\n# 智能体间消息通信\n\n## 概述\n\nClawTeam 的智能体间消息通信系统是协调多智能体团队工作的核心基础设施。该系统提供点对点消息传递、广播通信、消息路由、任务依赖管理和生命周期控制等功能，使团队中的各个智能体能够有效地进行协作。\n\n消息系统基于文件存储实现，每个智能体拥有独立的收件箱（Mailbox），消息以结构化的 JSON 格式持久化存储在本地文件系统中。资料来源：[clawteam/team/mailbox.py:1-50]()\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[智能体 A] -->|发送消息| B[Mailbox 模块]\n B --> C[消息路由器 Router]\n C -->|点对点| D[智能体 B 收件箱]\n C -->|广播| E[所有成员收件箱]\n \n F[CLI 命令] -->|mailbox send| B\n G[CLI 命令] -->|mailbox broadcast| B\n H[CLI 命令] -->|mailbox receive| B\n \n I[生命周期事件] -->|join/leave/shutdown| B\n J[任务事件] -->|plan/status| B\n```\n\n### 核心组件\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| Mailbox | `clawteam/team/mailbox.py` | 消息的发送、接收、广播核心实现 |\n| Router | `clawteam/team/router.py` | 消息路由和目标解析 |\n| MCP Tools | `clawteam/mcp/tools/mailbox.py` | MCP 协议工具封装 |\n| File Transport | `clawteam/transport/file.py` | 基于文件的底层传输层 |\n| Inbox Storage | `~/.clawteam/teams/{team}/inboxes/{agent}/` | 消息持久化存储 |\n\n资料来源：[clawteam/mcp/tools/mailbox.py:1-30]()\n\n## 消息类型\n\nClawTeam 定义了完整的消息类型体系，涵盖智能体协作的各个场景：\n\n| 消息类型 | 说明 | 触发场景 |\n|----------|------|----------|\n| `message` | 点对点通用消息 | 智能体间的日常通信 |\n| `broadcast` | 广播消息 | 向团队所有成员发布通知 |\n| `join_request` | 加入团队请求 | 智能体申请加入团队 |\n| `join_approved` | 加入批准 | 团队领导者批准加入请求 |\n| `join_rejected` | 加入拒绝 | 团队领导者拒绝加入请求 |\n| `plan_approval_request` | 计划审批请求 | 智能体提交计划等待审批 |\n| `plan_approved` | 计划批准 | 领导者批准某个计划 |\n| `plan_rejected` | 计划拒绝 | 领导者拒绝某个计划 |\n| `shutdown_request` | 关闭请求 | 请求智能体优雅关闭 |\n| `shutdown_approved` | 关闭批准 | 智能体确认关闭 |\n| `shutdown_rejected` | 关闭拒绝 | 智能体拒绝关闭请求 |\n| `idle` | 空闲通知 | 智能体完成工作进入空闲状态 |\n\n资料来源：[skills/clawteam/references/cli-reference.md:60-80]()\n\n## 消息数据结构\n\n### 消息文件格式\n\n消息以 JSON 格式存储在 `~/.clawteam/teams/{team}/inboxes/{agent}/msg-{timestamp}-{uuid}.json` 路径下。\n\n```json\n{\n \"id\": \"msg-1234567890-abc123\",\n \"type\": \"message\",\n \"from\": \"leader\",\n \"to\": \"researcher\",\n \"content\": \"请研究微服务的认证模式\",\n \"timestamp\": \"2024-01-15T10:30:00Z\",\n \"request_id\": null,\n \"key\": null,\n \"proposed_name\": null,\n \"capabilities\": null,\n \"feedback\": null,\n \"reason\": null,\n \"assigned_name\": null,\n \"agent_id\": null,\n \"team_name\": \"dev-team\",\n \"plan_file\": null,\n \"summary\": null,\n \"plan\": null,\n \"last_task\": null,\n \"status\": null\n}\n```\n\n### MessagePayload 数据模型\n\n```python\n@dataclass\nclass MessagePayload:\n msg_id: str # 消息唯一标识\n msg_type: MessageType # 消息类型枚举\n from_agent: str # 发送方名称\n to_agent: str # 接收方名称\n content: str # 消息内容\n timestamp: str # ISO8601 时间戳\n # ... 其他可选字段\n```\n\n资料来源：[clawteam/team/mailbox.py:20-60]()\n\n## 核心 API\n\n### 发送消息 (mailbox_broadcast)\n\n广播消息给团队所有成员：\n\n```python\ndef mailbox_broadcast(\n team_name: str,\n from_agent: str,\n content: str,\n msg_type: str | None = None,\n key: str | None = None,\n exclude: list[str] | None = None,\n) -> list[dict]:\n \"\"\"Broadcast a message to team inboxes.\"\"\"\n```\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `team_name` | str | 是 | 团队名称 |\n| `from_agent` | str | 是 | 发送方智能体名称 |\n| `content` | str | 是 | 消息内容 |\n| `msg_type` | str | 否 | 消息类型，默认 `broadcast` |\n| `key` | str | 否 | 消息关联的键 |\n| `exclude` | list[str] | 否 | 排除的智能体名称列表 |\n\n资料来源：[clawteam/mcp/tools/mailbox.py:50-70]()\n\n### 接收消息 (mailbox_receive)\n\n接收并消费待处理的消息：\n\n```python\ndef mailbox_receive(\n team_name: str, \n agent_name: str, \n limit: int = 10\n) -> list[dict]:\n \"\"\"Receive and consume pending inbox messages.\"\"\"\n```\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `team_name` | str | 是 | - | 团队名称 |\n| `agent_name` | str | 是 | - | 接收方智能体名称 |\n| `limit` | int | 否 | 10 | 最多接收消息数量 |\n\n### 预览消息 (mailbox_peek)\n\n预览待处理消息但不消费：\n\n```python\ndef mailbox_peek(\n team_name: str, \n agent_name: str\n) -> list[dict]:\n \"\"\"Preview pending inbox messages without consuming them.\"\"\"\n```\n\n### 获取消息数量 (mailbox_peek_count)\n\n```python\ndef mailbox_peek_count(\n team_name: str, \n agent_name: str\n) -> dict:\n \"\"\"Get the number of pending inbox messages.\"\"\"\n return {\"agentName\": agent_name, \"count\": team_mailbox.team_mailbox(...).count}\n```\n\n资料来源：[clawteam/mcp/tools/mailbox.py:70-90]()\n\n## CLI 命令接口\n\n### inbox send - 发送消息\n\n```bash\nclawteam inbox send [--type TYPE] [--key KEY]\n```\n\n### inbox receive - 接收消息\n\n```bash\nclawteam inbox receive [--agent AGENT] [--limit LIMIT]\n```\n\n### inbox peek - 预览消息\n\n```bash\nclawteam inbox peek [--agent AGENT]\n```\n\n### inbox broadcast - 广播消息\n\n```bash\nclawteam inbox broadcast [--exclude AGENT,AGENT...]\n```\n\n资料来源：[skills/clawteam/references/cli-reference.md:1-50]()\n\n## 协作工作流\n\n### 工作流 1：领导者分配任务\n\n```mermaid\nsequenceDiagram\n participant L as 领导者\n participant M as Mailbox\n participant W as Worker\n \n L->>M: inbox send \"执行数据分析\"\n M-->>W: 消息投递到收件箱\n W->>W: inbox receive 获取消息\n W->>W: 执行任务\n W->>M: task update --status completed\n W->>M: lifecycle idle 通知\n```\n\n### 工作流 2：计划审批流程\n\n```bash\n# 智能体提交计划\nclawteam plan submit dev-team coder \"实现步骤...\" \\\n --summary \"Auth 系统现代化\"\n\n# 领导者检查收件箱\nclawteam inbox receive dev-team --agent leader\n# => plan_approval_request with planId\n\n# 领导者审批\nclawteam plan approve dev-team coder --feedback \"看起来不错，开始执行\"\n```\n\n资料来源：[skills/clawteam/references/workflows.md:30-60]()\n\n### 工作流 3：优雅关闭\n\n```mermaid\nsequenceDiagram\n participant L as 领导者\n participant M as Mailbox\n participant W as Worker\n \n L->>M: lifecycle request-shutdown --reason \"所有任务完成\"\n M-->>W: shutdown_request 投递\n W->>W: inbox receive 获取关闭请求\n W->>W: 完成当前工作\n W->>M: lifecycle approve-shutdown\n L->>M: team cleanup --force\n```\n\n```bash\n# 领导者请求关闭\nclawteam lifecycle request-shutdown dev-team leader coder --reason \"所有任务完成\"\n\n# Worker 查看收件箱\nclawteam inbox receive dev-team --agent coder\n# => shutdown_request, requestId: shut-xyz\n\n# Worker 批准关闭\nclawteam lifecycle approve-shutdown dev-team shut-xyz coder\n```\n\n资料来源：[skills/clawteam/references/workflows.md:70-95]()\n\n## 文件存储布局\n\n```\n~/.clawteam/\n├── teams/{team}/\n│ ├── config.json # 团队配置（名称、成员、领导者）\n│ └── inboxes/{agent}/ # 各智能体收件箱\n│ ├── msg-{timestamp}-{uuid}.json # 消息文件\n│ └── ...\n├── tasks/{team}/\n│ └── task-{id}.json # 任务文件\n└── plans/\n └── {agent}-{id}.md # 计划文档\n```\n\n消息文件命名格式：`msg-{timestamp}-{uuid}.json`，确保消息按时间顺序排列且具有全局唯一性。\n\n资料来源：[skills/clawteam/references/cli-reference.md:90-110]()\n\n## 消息与板卡集成\n\nBoard 命令提供团队状态总览，包含消息历史：\n\n```bash\nclawteam board show \nclawteam --json board show \n```\n\nJSON 输出包含成员感知字段：\n\n| 字段 | 说明 |\n|------|------|\n| `memberKey` | 成员唯一标识键 |\n| `inboxName` | 收件箱名称 |\n| `fromLabel` | 发送方标签 |\n| `toLabel` | 接收方标签 |\n| `inboxCount` | 未读消息数量 |\n\n浏览器板卡使用这些字段过滤收件箱历史记录，实现消息导航功能。\n\n资料来源：[skills/clawteam/references/cli-reference.md:115-130]()\n\n## 最佳实践\n\n### 消息设计原则\n\n1. **消息幂等性**：使用 `request_id` 确保消息处理的幂等性\n2. **内容简洁**：消息内容应清晰表达意图，避免过长文本\n3. **类型明确**：根据消息目的选择正确的消息类型\n4. **状态同步**：定期使用 `mailbox_peek_count` 检查未读消息\n\n### 错误处理\n\n当消息处理失败时，系统通过以下机制保证可靠性：\n\n- 消息持久化存储在文件系统，重启后可恢复\n- 使用 `mailbox_peek` 而非 `mailbox_receive` 进行消息预览，避免意外消费\n- `mailbox_peek_count` 返回消息计数，便于监控队列状态\n\n### 性能考虑\n\n- 消息文件按时间戳命名，便于顺序读取\n- 建议定期清理已处理消息，避免收件箱膨胀\n- 大规模团队建议监控 `~/.clawteam/` 目录大小\n\n## 总结\n\nClawTeam 的智能体间消息通信系统提供了完整的多智能体协作基础设施：\n\n- **9+ 消息类型**覆盖协作全生命周期\n- **文件存储**确保消息可靠持久化\n- **MCP 工具**和 **CLI 命令**双重接口\n- **与板卡系统集成**提供可视化监控\n- **工作流模板**简化常见协作场景\n\n该系统使开发者能够轻松构建、协调和管理多智能体团队，实现复杂的软件工程任务自动化。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：HKUDS/ClawTeam\n\n摘要：发现 15 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Security testing for multi-agent swarms: agent isolation, delegation trust, inbox spoofing。\n\n## 1. 安全/权限坑 · 来源证据：Security testing for multi-agent swarms: agent isolation, delegation trust, inbox spoofing\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security testing for multi-agent swarms: agent isolation, delegation trust, inbox spoofing\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d8bd96f00b7c46c6813bc15c32a84625 | https://github.com/HKUDS/ClawTeam/issues/76 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | host_targets=claude, claude_code, cursor, chatgpt\n\n## 3. 配置坑 · 来源证据：Proposal: 8-PR sequence — canonical WorkerState, persistent event log, project namespacing, contract verify states, SCM…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Proposal: 8-PR sequence — canonical WorkerState, persistent event log, project namespacing, contract verify states, SCM plugin + reaction engine\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_114771b2a1474b358b05a6a9e61807f6 | https://github.com/HKUDS/ClawTeam/issues/157 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | README/documentation is current enough for a first validation pass.\n\n## 5. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | last_activity_observed missing\n\n## 6. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 8. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | no_demo; severity=medium\n\n## 9. 安全/权限坑 · 来源证据：Agent Definitions Feature is Non-Functional: Parsed but Not Applied\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Agent Definitions Feature is Non-Functional: Parsed but Not Applied\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dc9ad856da7a4a828860da94afadc7ec | https://github.com/HKUDS/ClawTeam/issues/146 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 安全/权限坑 · 来源证据：High: /api/proxy board endpoint enables SSRF and arbitrary outbound fetches\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：High: /api/proxy board endpoint enables SSRF and arbitrary outbound fetches\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_61dec732a08f4279a590654f0eecea51 | https://github.com/HKUDS/ClawTeam/issues/104 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 安全/权限坑 · 来源证据：Worker agents exit after first turn despite 'ongoing job' task prompt\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Worker agents exit after first turn despite 'ongoing job' task prompt\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_26124d52e6d948b2bf15809390ef2589 | https://github.com/HKUDS/ClawTeam/issues/148 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：[Feature Request] Optimize Worker Workspace Size and Enable Headless IPC\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Optimize Worker Workspace Size and Enable Headless IPC\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_63b04b7d23e74c71a8c1f8dddcaa9281 | https://github.com/HKUDS/ClawTeam/issues/45 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 13. 安全/权限坑 · 来源证据：v0.2.0 — Stabilization Release\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.0 — Stabilization Release\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2aca0ffb17f94d8bb219737c9f275e7f | https://github.com/HKUDS/ClawTeam/releases/tag/v0.2.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | issue_or_pr_quality=unknown\n\n## 15. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | release_recency=unknown\n\n\n",
"markdown_key": "clawteam",
"pages": "draft",
"source_refs": [
{
"evidence_id": "art_abc9b09559e64bd4983fa470a78389f3",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/HKUDS/ClawTeam#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "ClawTeam 说明书",
"toc": [
"https://github.com/HKUDS/ClawTeam 项目说明书",
"目录",
"ClawTeam 项目介绍",
"概述",
"核心定位",
"支持的客户端",
"系统架构",
"核心功能模块",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "01198332ef9270c32c5460b8a178f964fc0df451",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"package.json",
"README.md",
"docs/transport-architecture.md",
"docs/site-assets/index-Vcr1d_d3.js",
"docs/skills/clawteam/SKILL.md",
"docs/skills/clawteam/references/cli-reference.md",
"docs/skills/clawteam/references/workflows.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# clawteam-website - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 clawteam-website 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **AI 研究者或研究型 Agent 构建者**：README 明确围绕研究、实验或论文工作流展开。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.agents/skills/clawteam-dev/SKILL.md`, `.agents/skills/frontend-design/SKILL.md`, `docs/skills/clawteam/SKILL.md`, `skills/clawteam/SKILL.md` Claim：`clm_0005` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.agents/skills/clawteam-dev/SKILL.md`, `.agents/skills/frontend-design/SKILL.md`, `docs/skills/clawteam/SKILL.md`, `skills/clawteam/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `pip install clawteam` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `git clone https://github.com/HKUDS/ClawTeam.git` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `pip install -e .` 证据：`README.md` Claim：`clm_0008` supported 0.86, `clm_0009` supported 0.86\n- `pip install -e \".[p2p]\"` 证据：`README.md` Claim：`clm_0009` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：AI 研究者或研究型 Agent 构建者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.agents/skills/clawteam-dev/SKILL.md`, `.agents/skills/frontend-design/SKILL.md`, `docs/skills/clawteam/SKILL.md`, `skills/clawteam/SKILL.md` Claim：`clm_0005` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.agents/skills/clawteam-dev/SKILL.md`, `.agents/skills/frontend-design/SKILL.md`, `docs/skills/clawteam/SKILL.md`, `skills/clawteam/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.agents/skills/clawteam-dev/SKILL.md`, `.agents/skills/frontend-design/SKILL.md`, `docs/skills/clawteam/SKILL.md`, `skills/clawteam/SKILL.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.agents/skills/clawteam-dev/SKILL.md`, `.agents/skills/frontend-design/SKILL.md`, `docs/skills/clawteam/SKILL.md`, `skills/clawteam/SKILL.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `README_CN.md`, `clawteam/spawn/presets.py`, `docs/skills/clawteam/SKILL.md` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0010` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0011` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.agents/skills/clawteam-dev/SKILL.md`, `.agents/skills/frontend-design/SKILL.md`, `docs/skills/clawteam/SKILL.md`, `skills/clawteam/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：188\n- 重要文件覆盖：35/188\n- 证据索引条目：33\n- 角色 / Skill 条目：4\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 clawteam-website 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 clawteam-website 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 clawteam-website 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 4 个角色 / Skill / 项目文档条目。\n\n- **clawteam-dev**（skill）： 激活提示：当用户任务与“clawteam-dev”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/clawteam-dev/SKILL.md`\n- **frontend-design**（skill）：Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI . Generates creative, polished code and UI design that avoids generic AI aesthetics. 激活提示：当用户任务与“frontend-design”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/frontend-design/SKILL.md`\n- **ClawTeam**（skill）： 激活提示：当用户任务与“ClawTeam”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`docs/skills/clawteam/SKILL.md`\n- **ClawTeam**（skill）： 激活提示：当用户任务与“ClawTeam”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/clawteam/SKILL.md`\n\n## 证据索引\n\n- 共索引 33 条证据。\n\n- **ClawTeam Multi-Agent Coordination**（skill_instruction）：ClawTeam is a framework-agnostic CLI tool for coordinating multiple AI agents as a team. It provides team/task management, inter-agent messaging, git worktree isolation, provider-aware runtime profiles, git context injection, snapshots, and terminal-based monitoring dashboards. 证据：`docs/skills/clawteam/SKILL.md`\n- **📰 News**（documentation）： ClawTeam: Agent Swarm Intelligence 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"clawteam-website\", \"private\": true, \"version\": \"0.0.0\", \"type\": \"module\", \"scripts\": { \"dev\": \"vite --config website/vite.config.mjs\", \"build\": \"vite build --config website/vite.config.mjs\", \"preview\": \"vite preview --config website/vite.config.mjs\" }, \"dependencies\": { \"react\": \"^18.3.1\", \"react-dom\": \"^18.3.1\" }, \"devDependencies\": { \"@vitejs/plugin-react\": \"^4.3.4\", \"vite\": \"^5.4.11\" } } 证据：`package.json`\n- **ClawTeam Local Development**（skill_instruction）：This skill is for developing and validating ClawTeam inside the ClawTeam repository. Use it when the task is about changing ClawTeam itself, testing local behavior, or verifying multi-agent workflows against the current checkout. 证据：`.agents/skills/clawteam-dev/SKILL.md`\n- **Design Thinking**（skill_instruction）：This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic \"AI slop\" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. 证据：`.agents/skills/frontend-design/SKILL.md`\n- **ClawTeam Multi-Agent Coordination**（skill_instruction）：ClawTeam is a framework-agnostic CLI tool for coordinating multiple AI agents as a team. It provides team/task management, inter-agent messaging, git worktree isolation, provider-aware runtime profiles, git context injection, snapshots, and terminal-based monitoring dashboards. 证据：`skills/clawteam/SKILL.md`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **Transport 抽象层 — 架构图 & 时序图**（documentation）：commands.py ─────┐ watcher.py ──────┤ lifecycle.py ────┤ plan.py ─────────┼──► MailboxManager ──► Transport ABC collector.py ────┘ │ ┌───────┴───────┐ ▼ ▼ FileTransport P2PTransport ▲ │ │ │ └── fallback ───┘ 证据：`docs/transport-architecture.md`\n- **ClawTeam CLI Complete Reference**（documentation）：- --json — Output JSON instead of human-readable text. Apply before subcommand: clawteam --json team discover - --data-dir PATH — Override data directory default: ~/.clawteam 证据：`docs/skills/clawteam/references/cli-reference.md`\n- **ClawTeam Coordination Workflows**（documentation）：Workflow 1: Create a Team and Assign Tasks 证据：`docs/skills/clawteam/references/workflows.md`\n- **📰 News**（documentation）：今天的 Agent 各自为战 🤖，明天的 Agent 将协同作战 🦞🤖🤖🤖 ClawTeam：让 AI Agent 自主组建团队、分配任务、协同工作的 CLI 工具 证据：`README_CN.md`\n- **📰 News**（documentation）：AI 에이전트의 진화 🚀: 솔로 🤖 → 스웜 🦞🤖🤖🤖 ClawTeam은 AI 에이전트가 무리를 이뤄 함께 생각하고 일하며 더 빠르게 결과를 내도록 돕습니다 证据：`README_KR.md`\n- **ClawTeam Evolution Roadmap**（documentation）：- 所有数据在 ~/.clawteam/ （团队配置、任务、消息） - 所有 agent 必须在同一台机器 - 纯文件 I/O，零依赖 证据：`ROADMAP.md`\n- **ClawTeam CLI Complete Reference**（documentation）：- --json — Output JSON instead of human-readable text. Apply before subcommand: clawteam --json team discover - --data-dir PATH — Override data directory default: ~/.clawteam 证据：`skills/clawteam/references/cli-reference.md`\n- **ClawTeam Coordination Workflows**（documentation）：Workflow 1: Create a Team and Assign Tasks 证据：`skills/clawteam/references/workflows.md`\n- **Skills Lock**（structured_config）：{ \"version\": 1, \"skills\": { \"frontend-design\": { \"source\": \"anthropics/skills\", \"sourceType\": \"github\", \"computedHash\": \"063a0e6448123cd359ad0044cc46b0e490cc7964d45ef4bb9fd842bd2ffbca67\" } } } 证据：`skills-lock.json`\n- **.gitignore**（source_file）：pycache / .py cod $py.class .egg-info/ dist/ build/ .eggs/ .egg .env .venv/ venv/ uv.lock .claude/ .local.md node modules/ 证据：`.gitignore`\n- **Init**（source_file）：\"\"\"ClawTeam - Open-source harness framework for multi-agent orchestration.\"\"\" 证据：`clawteam/__init__.py`\n- **Main**（source_file）：\"\"\"Entry point for running clawteam as a module: python -m clawteam\"\"\" 证据：`clawteam/__main__.py`\n- **Alias for code that uses the harness naming**（source_file）：\"\"\"Persistent configuration for ClawTeam.\"\"\" 证据：`clawteam/config.py`\n- **Fileutil**（source_file）：\"\"\"Atomic file writes and advisory file locking. 证据：`clawteam/fileutil.py`\n- **Identity**（source_file）：\"\"\"Agent identity for team context with compatibility env aliases.\"\"\" 证据：`clawteam/identity.py`\n- **Paths**（source_file）：\"\"\"Helpers for validating logical identifiers and constraining data paths.\"\"\" 证据：`clawteam/paths.py`\n- **Timefmt**（source_file）：\"\"\"Human-friendly timestamp formatting for CLI display.\"\"\" 证据：`clawteam/timefmt.py`\n- **Cname**（source_file）：clawteam.us 证据：`docs/CNAME`\n- **Index**（source_file）：ClawTeam 证据：`docs/index.html`\n- **Pyproject**（source_file）：project name = \"clawteam\" version = \"0.3.0\" description = \"Framework-agnostic multi-agent coordination CLI\" readme = \"README.md\" requires-python = \" =3.10\" license = {text = \"MIT\"} authors = {name = \"HKUDS\", email = \"jiabintang77@gmail.com\"} keywords = \"ai\", \"agent\", \"multi-agent\", \"team\", \"coordination\", \"cli\", \"swarm\", \"harness\" classifiers = \"Development Status :: 3 - Alpha\", \"Intended Audience :: Developers\", \"License :: OSI Approved :: MIT License\", \"Programming Language :: Python :: 3.10\", \"Programming Language :: Python :: 3.11\", \"Programming Language :: Python :: 3.12\", 证据：`pyproject.toml`\n- **!/usr/bin/env bash**（source_file）：!/usr/bin/env bash ClawTeam local source installer. Installs this checkout with pip install -e . into ~/.clawteam/.venv, links ~/.local/bin/clawteam, and installs the local ClawTeam skill into detected agent clients. 证据：`scripts/clawteam_local_install`\n- **!/usr/bin/env bash**（source_file）：!/usr/bin/env bash ClawTeam user-level installer. Installs the PyPI package into ~/.clawteam/.venv, links ~/.local/bin/clawteam, and installs the ClawTeam skill into detected agent clients. 证据：`scripts/install_clawteam.sh`\n- **!/bin/bash**（source_file）：!/bin/bash ============================================================================= OpenClaw 非交互式 Worker 包装脚本 v2.0 - 审计整改版 ============================================================================= 参数： $1 - 团队名 $2 - 收件人 $3 - 任务内容 $4 - 可选 父 Agent ID，用于模型继承 ============================================================================= 证据：`scripts/openclaw_worker.sh`\n- **Also override HOME so config path doesn't hit real ~/.clawteam/config.json**（source_file）：\"\"\"Shared fixtures for clawteam tests. 证据：`tests/conftest.py`\n- **Index**（source_file）：ClawTeam 证据：`website/index.html`\n- **Vite.Config**（source_file）：import { defineConfig } from \"vite\"; import react from \"@vitejs/plugin-react\"; import { fileURLToPath } from \"node:url\"; import { dirname, resolve } from \"node:path\"; 证据：`website/vite.config.mjs`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/skills/clawteam/SKILL.md`, `README.md`, `package.json`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/skills/clawteam/SKILL.md`, `README.md`, `package.json`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **ClawTeam 项目介绍**：importance `high`\n - source_paths: README.md, clawteam/__init__.py, clawteam/identity.py\n- **安装与配置**：importance `high`\n - source_paths: pyproject.toml, scripts/install_clawteam.sh, scripts/clawteam_local_install, clawteam/spawn/profiles.py, clawteam/spawn/presets.py\n- **快速入门指南**：importance `high`\n - source_paths: clawteam/cli/commands.py, clawteam/team/manager.py, clawteam/spawn/sessions.py\n- **系统架构总览**：importance `high`\n - source_paths: clawteam/harness/orchestrator.py, clawteam/harness/conductor.py, clawteam/team/manager.py, clawteam/config.py\n- **Harness 与协调执行器**：importance `high`\n - source_paths: clawteam/harness/orchestrator.py, clawteam/harness/conductor.py, clawteam/harness/contract_executor.py, clawteam/harness/phases.py, clawteam/harness/strategies.py\n- **智能体 Spawn 系统**：importance `high`\n - source_paths: clawteam/spawn/base.py, clawteam/spawn/sessions.py, clawteam/spawn/registry.py, clawteam/spawn/prompt.py, clawteam/spawn/adapters.py\n- **Spawn 后端实现**：importance `medium`\n - source_paths: clawteam/spawn/tmux_backend.py, clawteam/spawn/subprocess_backend.py, clawteam/spawn/wsh_backend.py, clawteam/spawn/wsh_rpc.py, clawteam/spawn/session_locators/base.py\n- **团队生命周期管理**：importance `high`\n - source_paths: clawteam/team/manager.py, clawteam/team/lifecycle.py, clawteam/team/models.py, clawteam/team/leader_watcher.py, clawteam/team/snapshot.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `01198332ef9270c32c5460b8a178f964fc0df451`\n- inspected_files: `pyproject.toml`, `package.json`, `README.md`, `docs/transport-architecture.md`, `docs/site-assets/index-Vcr1d_d3.js`, `docs/skills/clawteam/SKILL.md`, `docs/skills/clawteam/references/cli-reference.md`, `docs/skills/clawteam/references/workflows.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：Security testing for multi-agent swarms: agent isolation, delegation trust, inbox spoofing\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security testing for multi-agent swarms: agent isolation, delegation trust, inbox spoofing\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_d8bd96f00b7c46c6813bc15c32a84625 | https://github.com/HKUDS/ClawTeam/issues/76 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | host_targets=claude, claude_code, cursor, chatgpt\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Proposal: 8-PR sequence — canonical WorkerState, persistent event log, project namespacing, contract verify states, SCM…\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Proposal: 8-PR sequence — canonical WorkerState, persistent event log, project namespacing, contract verify states, SCM plugin + reaction engine\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_114771b2a1474b358b05a6a9e61807f6 | https://github.com/HKUDS/ClawTeam/issues/157 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: risks.safety_notes | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | No sandbox install has been executed yet; downstream must verify before user use.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：Agent Definitions Feature is Non-Functional: Parsed but Not Applied\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Agent Definitions Feature is Non-Functional: Parsed but Not Applied\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_dc9ad856da7a4a828860da94afadc7ec | https://github.com/HKUDS/ClawTeam/issues/146 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：High: /api/proxy board endpoint enables SSRF and arbitrary outbound fetches\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：High: /api/proxy board endpoint enables SSRF and arbitrary outbound fetches\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_61dec732a08f4279a590654f0eecea51 | https://github.com/HKUDS/ClawTeam/issues/104 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：HKUDS/ClawTeam\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：claude, claude_code, cursor, chatgpt\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Security testing for multi-agent swarms: agent isolation, delegation trust, inbox spoofing（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 来源证据：Proposal: 8-PR sequence — canonical WorkerState, persistent event log, project namespacing, contract verify states, SCM…（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/HKUDS/ClawTeam 项目说明书\n\n生成时间：2026-05-13 05:40:52 UTC\n\n## 目录\n\n- [ClawTeam 项目介绍](#page-introduction)\n- [安装与配置](#page-installation)\n- [快速入门指南](#page-quickstart)\n- [系统架构总览](#page-architecture-overview)\n- [Harness 与协调执行器](#page-harness-orchestrator)\n- [智能体 Spawn 系统](#page-spawn-system)\n- [Spawn 后端实现](#page-spawn-backends)\n- [团队生命周期管理](#page-team-management)\n- [任务管理与依赖链](#page-task-dependencies)\n- [智能体间消息通信](#page-messaging)\n\n\n\n## ClawTeam 项目介绍\n\n### 相关页面\n\n相关主题：[安装与配置](#page-installation), [系统架构总览](#page-architecture-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [website/src/App.jsx](https://github.com/HKUDS/ClawTeam/blob/main/website/src/App.jsx)\n- [skills/clawteam/references/cli-reference.md](https://github.com/HKUDS/ClawTeam/blob/main/skills/clawteam/references/cli-reference.md)\n- [clawteam/spawn/wsh_backend.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/wsh_backend.py)\n- [clawteam/harness/context_recovery.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/harness/context_recovery.py)\n- [clawteam/spawn/session_locators/claude.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/spawn/session_locators/claude.py)\n- [clawteam/cli/commands.py](https://github.com/HKUDS/ClawTeam/blob/main/clawteam/cli/commands.py)\n \n\n# ClawTeam 项目介绍\n\n## 概述\n\nClawTeam 是一个**智能体蜂群编排（Agent Swarm Orchestration）**命令行工具，旨在为 Claude Code、Codex、OpenClaw、nanobot 等终端原生客户端提供统一的协调层。通过 ClawTeam，用户可以在一个 CLI 界面中规划、委托和交付任务，使多个编码智能体能够协同工作而非孤立运行。资料来源：[website/src/App.jsx:36]()\n\n## 核心定位\n\nClawTeam 的设计目标是解决以下问题：\n\n| 问题 | ClawTeam 解决方案 |\n|------|------------------|\n| 多个智能体各自为战 | 共享任务图（Shared Task Graph）统一管理 |\n| 信息随提示词滚动丢失 | 持久化协调机制（任务指派、别名、备注持久存储） |\n| 与真实代码仓库脱节 | Git 感知执行（工作树、分支、差异管理） |\n\n资料来源：[website/src/App.jsx:52-54]()\n\n## 支持的客户端\n\nClawTeam 支持多种编码智能体客户端：\n\n| 客户端 | 类型 | 说明 |\n|--------|------|------|\n| Claude Code | 主要支持 | Anthropic 官方编码智能体 |\n| Codex | 主要支持 | OpenAI Codex |\n| OpenClaw | 主要支持 | 开源编码智能体 |\n| nanobot | 主要支持 | 轻量级纳米机器人 |\n| Any CLI | 通用支持 | 任何终端命令行工具 |\n\n资料来源：[website/src/App.jsx:189-193]()\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n subgraph \"用户层\"\n CLI[clawteam CLI]\n end\n \n subgraph \"团队管理层\"\n TeamMgr[团队管理器]\n Board[看板系统]\n Inbox[收件箱系统]\n end\n \n subgraph \"任务系统\"\n TaskStore[任务存储]\n PlanStore[计划存储]\n end\n \n subgraph \"智能体层\"\n Agent1[智能体 1]\n Agent2[智能体 2]\n AgentN[智能体 N]\n end\n \n subgraph \"后端支持\"\n Tmux[Tmux 后端]\n Wsh[Wsh 后端]\n Subprocess[子进程后端]\n end\n \n CLI --> TeamMgr\n CLI --> TaskStore\n TeamMgr --> Board\n TeamMgr --> Inbox\n TeamMgr --> PlanStore\n TaskStore --> Agent1\n TaskStore --> Agent2\n TaskStore --> AgentN\n Agent1 --> Tmux\n Agent2 --> Wsh\n AgentN --> Subprocess\n```\n\n### 目录存储结构\n\nClawTeam 使用本地文件系统存储团队数据：\n\n```\n~/.clawteam/\n├── teams/{team}/\n│ ├── config.json # 团队配置（名称、成员、领导者）\n│ └── inboxes/{agent}/ # 智能体收件箱\n│ └── msg-{timestamp}-{uuid}.json # 消息文件\n├── tasks/{team}/\n│ └── task-{id}.json # 单独任务文件\n└── plans/\n └── {agent}-{id}.md # 计划文档\n```\n\n资料来源：[skills/clawteam/references/cli-reference.md:180-190]()\n\n## 核心功能模块\n\n### 1. 团队管理（Team Management）\n\n#### 团队生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> 创建团队: spawn-team\n 创建团队 --> 发现团队: discover\n 发现团队 --> 请求加入: request-join\n 请求加入 --> 批准/拒绝: approve-join / reject-join\n 批准 --> 团队活动: status\n 拒绝 --> [*]\n```\n\n#### 团队命令\n\n| 命令 | 功能 |\n|------|------|\n| `clawteam team spawn-team ` | 创建新团队并注册领导者 |\n| `clawteam team discover` | 列出所有现有团队 |\n| `clawteam team status ` | 显示团队配置和成员列表 |\n| `clawteam team request-join ` | 请求加入团队 |\n| `clawteam team approve-join ` | 批准加入请求（领导者） |\n| `clawteam team reject-join ` | 拒绝加入请求（领导者） |\n\n资料来源：[skills/clawteam/references/cli-reference.md:100-145]()\n\n### 2. 任务管理（Task Management）\n\n#### 任务状态流转\n\n```mermaid\nstateDiagram-v2\n [*] --> 待处理: pending\n 待处理 --> 进行中: in_progress\n 进行中 --> 已完成: completed\n 进行中 --> 已阻塞: blocked\n 已阻塞 --> 待处理: unblock\n 已完成 --> [*]\n```\n\n#### 任务依赖关系\n\n当一个任务标记为 `completed` 时，任何被其阻塞的任务会自动解除阻塞（如果没有其他阻塞源）。\n\n| 状态 | 描述 |\n|------|------|\n| `pending` | 尚未开始 |\n| `in_progress` | 正在进行 |\n| `completed` | 已完成（自动解除依赖任务） |\n| `blocked` | 等待其他任务 |\n\n资料来源：[skills/clawteam/references/cli-reference.md:45-50]()\n\n#### 任务命令\n\n| 命令 | 功能 |\n|------|------|\n| `clawteam task create ` | 创建新任务 |\n| `clawteam task get ` | 获取单个任务 |\n| `clawteam task update ` | 更新任务状态、负责人等 |\n| `clawteam task list ` | 列出团队所有任务 |\n\n#### 任务创建示例\n\n```bash\nclawteam task create dev-team \"Implement auth\" \\\n -o alice \\\n -d \"Add JWT authentication\" \\\n -p high \\\n --blocks T-002,T-003\n```\n\n| 参数 | 说明 |\n|------|------|\n| `-o, --owner` | 任务负责人 |\n| `-d, --description` | 任务描述 |\n| `-p, --priority` | 优先级：low, medium, high, urgent |\n| `--blocks` | 此任务阻塞的任务 ID |\n| `--blocked-by` | 阻塞此任务的任务 ID |\n\n资料来源：[skills/clawteam/references/cli-reference.md:52-85]()\n\n### 3. 看板系统（Board System）\n\n#### 看板视图\n\n```mermaid\ngraph LR\n subgraph \"看板列\"\n P[待处理]\n IP[进行中]\n B[已阻塞]\n C[已完成]\n end\n \n T1[任务 1] --> P\n T2[任务 2] --> IP\n T3[任务 3] --> B\n T4[任务 4] --> C\n```\n\n#### 看板命令\n\n| 命令 | 功能 |\n|------|------|\n| `clawteam board show ` | 显示详细看板数据（人机视图/JSON） |\n| `clawteam board overview` | 显示所有团队概览表 |\n| `clawteam board live ` | 实时刷新看板 |\n\n```bash\nclawteam board show dev-team # 人类可读看板\nclawteam --json board show dev-team # JSON 格式输出\nclawteam board live dev-team --interval 2.0 # 每2秒刷新\n```\n\n资料来源：[skills/clawteam/references/cli-reference.md:150-175]()\n\n### 4. 计划审批系统（Plan Approval System）\n\n#### 计划工作流\n\n```mermaid\nsequenceDiagram\n participant Agent as 智能体\n participant Leader as 团队领导者\n participant System as ClawTeam\n \n Agent->>System: plan submit \n System->>Leader: 发送审批请求\n Leader->>System: plan approve / reject\n System->>Agent: 返回审批结果\n```\n\n#### 计划命令\n\n| 命令 | 功能 |\n|------|------|\n| `clawteam plan submit ` | 提交计划待批准 |\n| `clawteam plan approve ` | 批准计划 |\n| `clawteam plan reject ` | 拒绝计划 |\n\n```bash\n# 提交计划\nclawteam plan submit dev-team alice \"Implement OAuth2 flow\" --summary \"OAuth2方案\"\n\n# 批准计划\nclawteam plan approve dev-team PLAN-001 alice --feedback \"Good plan\"\n```\n\n资料来源：[skills/clawteam/references/cli-reference.md:88-98]()\n\n### 5. 消息类型\n\n| 类型 | 描述 |\n|------|------|\n| `message` | 点对点消息 |\n| `broadcast` | 广播给所有成员 |\n| `join_request` | 加入团队请求 |\n| `join_approved` | 加入批准响应 |\n| `join_rejected` | 加入拒绝响应 |\n| `plan_approval_request` | 计划审批请求 |\n| `plan_approved` | 计划批准响应 |\n| `plan_rejected` | 计划拒绝响应 |\n| `shutdown_request` | 关闭请求 |\n| `shutdown_approved` | 关闭批准响应 |\n| `shutdown_rejected` | 关闭拒绝响应 |\n| `idle` | 智能体空闲通知 |\n\n资料来源：[skills/clawteam/references/cli-reference.md:60-72]()\n\n### 6. 生命周期管理（Lifecycle Management）\n\n#### 生命周期状态机\n\n```mermaid\nstateDiagram-v2\n [*] --> 运行中\n 运行中 --> 请求关闭: request-shutdown\n 请求关闭 --> 批准关闭: approve-shutdown\n 请求关闭 --> 拒绝关闭: reject-shutdown\n 拒绝关闭 --> 运行中\n 批准关闭 --> [*]\n 运行中 --> 空闲: idle\n 空闲 --> 运行中\n```\n\n#### 生命周期命令\n\n| 命令 | 功能 |\n|------|------|\n| `clawteam lifecycle request-shutdown ` | 请求关闭智能体 |\n| `clawteam lifecycle approve-shutdown ` | 批准关闭 |\n| `clawteam lifecycle reject-shutdown ` | 拒绝关闭 |\n| `clawteam lifecycle idle [--last-task ID]` | 发送空闲通知 |\n\n资料来源：[skills/clawteam/references/cli-reference.md:110-140]()\n\n### 7. 智能体生成（Agent Spawning）\n\n#### 后端类型\n\n| 后端 | 说明 |\n|------|------|\n| `subprocess` | 子进程执行 |\n| `tmux` | Tmux 会话执行 |\n| `wsh` | Web Shell 执行 |\n\n#### Spawn 命令\n\n```bash\nclawteam spawn [options]\n```\n\n| 选项 | 描述 | 默认值 |\n|------|------|--------|\n| `--team, -t` | 团队名称 | `\"default\"` |\n| `--agent-name, -n` | 智能体名称 | 自动生成 |\n| `--agent-type` | 智能体类型 | `\"general-purpose\"` |\n\n#### 示例\n\n```bash\n# 使用 subprocess 后端生成\nclawteam spawn subprocess claude --team dev-team --agent-name bob\n\n# 使用 tmux 后端生成\nclawteam spawn tmux claude-code --agent-name builder\n\n# 指定团队和类型\nclawteam spawn subprocess claude --team dev-team --agent-name researcher --agent-type researcher\n```\n\n资料来源：[skills/clawteam/references/cli-reference.md:20-35]()\n\n### 8. 身份管理（Identity Management）\n\n每个智能体通过环境变量获取身份信息：\n\n| 环境变量 | 说明 |\n|----------|------|\n| `CLAWTEAM_AGENT_NAME` | 智能体名称 |\n| `CLAWTEAM_TEAM_NAME` | 团队名称 |\n| `CLAWTEAM_AGENT_TYPE` | 智能体类型 |\n| `CLAWTEAM_ROLE` | 角色（leader/general-purpose） |\n\n#### 身份命令\n\n| 命令 | 功能 |\n|------|------|\n| `clawteam identity show` | 显示当前智能体身份 |\n| `clawteam identity set --agent-name --team ` | 打印设置环境变量的命令 |\n\n```bash\n# 查看当前身份\nclawteam identity show\n\n# 设置身份（需要 eval 执行）\neval $(clawteam identity set --agent-name alice --team dev-team)\n```\n\n资料来源：[skills/clawteam/references/cli-reference.md:36-50]()\n\n## 工作流程示例\n\n### 三步启动蜂群\n\n```mermaid\ngraph LR\n A[安装 CLI] --> B[配置团队]\n B --> C[协调智能体]\n \n subgraph \"步骤 1: 安装\"\n A1[pip install clawteam]\n end\n \n subgraph \"步骤 2: 配置\"\n B1[spawn-team 创建团队]\n B2[spawn 生成智能体]\n end\n \n subgraph \"步骤 3: 协调\"\n C1[task 管理任务]\n C2[board 查看看板]\n end\n```\n\n### 完整示例\n\n```bash\n# 1. 创建团队\nclawteam team spawn-team docs-sprint -d \"文档冲刺团队\"\n\n# 2. 生成领导者智能体\nclawteam spawn tmux claude-code --team docs-sprint --agent-name leader\n\n# 3. 生成工作智能体\nclawteam spawn tmux claude-code --team docs-sprint --agent-name builder\n\n# 4. 创建任务\nclawteam task create docs-sprint \"构建落地页\" -o builder -p high\nclawteam task create docs-sprint \"编写 API 文档\" -o builder -p medium\n\n# 5. 查看看板\nclawteam board live docs-sprint\n\n# 6. 智能体请求加入\nclawteam team request-join docs-sprint builder\n\n# 7. 领导者批准（另一终端）\nclawteam team approve-join docs-sprint REQUEST-001 --assigned-name builder\n```\n\n资料来源：[website/src/App.jsx:26-45]()\n\n## 技术实现细节\n\n### Web Shell 后端\n\n`wsh_backend.py` 实现了 Web Shell 后端，用于在 Web 环境中生成和管理智能体：\n\n```python\n# 智能体注册\nfrom clawteam.spawn.registry import register_agent\n\nregister_agent(\n team_name=team_name,\n agent_name=agent_name,\n backend=\"wsh\",\n block_id=block_id,\n pid=pane_pid,\n command=list(final_command),\n)\n```\n\n#### 运行时消息注入\n\nWsh 后端支持向运行中的智能体注入消息：\n\n```python\ndef inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:\n # 检查智能体是否存在\n info = get_registry(team).get(agent_name, {})\n # 检查块是否存活\n if not _is_block_alive(block_id):\n return False, f\"wsh block '{block_id}' is not alive\"\n```\n\n资料来源：[clawteam/spawn/wsh_backend.py:1-60]()\n\n### 上下文恢复系统\n\n`context_recovery.py` 实现了智能体的上下文恢复能力：\n\n| 角色 | 上下文内容 |\n|------|-----------|\n| `worker` | 当前任务描述 + 个人冲刺合约 |\n| `evaluator` | 规范说明 + 所有合约标准 |\n| `planner` | 规范草稿 |\n\n```python\ndef _teammate_summary(self, agent_name: str, team_name: str, role: str) -> str:\n \"\"\"Layer 5: One-liner teammate summaries.\"\"\"\n from clawteam.team.models import TaskStatus\n from clawteam.team.tasks import TaskStore\n \n store = TaskStore(team_name)\n tasks = store.list_tasks()\n # 按负责人分组统计任务进度\n```\n\n资料来源：[clawteam/harness/context_recovery.py:1-50]()\n\n### 会话定位器\n\n`session_locators/claude.py` 处理 Claude Code 会话的持久化：\n\n```python\nclass ClaudeSessionLocator:\n def prepare(self, command, context: SessionContext) -> PreparedSession:\n # 检测 --continue/-c/--no-session-persistence\n if has_any(normalized, {\"--continue\", \"-c\", \"--no-session-persistence\"}):\n return PreparedSession(command=list(command), ...)\n \n # 自动生成会话 ID\n session_id = str(uuid.uuid4())\n return PreparedSession(command=[*command, \"--session-id\", session_id], ...)\n```\n\n资料来源：[clawteam/spawn/session_locators/claude.py:1-40]()\n\n### CLI 命令解析\n\n`cli/commands.py` 实现了团队启动命令：\n\n```python\ndef _human(_data):\n console.print(f\"\\n[green bold]Team '{t_name}' launched[/green bold]\\n\")\n table = Table(title=\"Agents\")\n table.add_column(\"Name\", style=\"cyan\")\n table.add_column(\"Type\")\n table.add_column(\"ID\", style=\"dim\")\n```\n\n输出后显示 attach 命令：\n\n```bash\ntmux attach -t clawteam-{team_name} # 附加到 tmux 会话\nclawteam board show {team_name} # 查看看板\nclawteam inbox peek {team_name} --agent # 查看收件箱\n```\n\n资料来源：[clawteam/cli/commands.py:1-100]()\n\n## 快速入门\n\n### 前置要求\n\n- Python 3.10+\n- tmux（使用 tmux 后端时）\n- 对应的智能体客户端（Claude Code、Codex 等）\n\n### 安装\n\n```bash\npip install clawteam\n```\n\n### 基本使用\n\n```bash\n# 创建团队\nclawteam team spawn-team my-team\n\n# 生成智能体\nclawteam spawn tmux claude-code --team my-team --agent-name worker1\n\n# 创建任务\nclawteam task create my-team \"完成功能开发\" -o worker1 -p high\n\n# 查看看板\nclawteam board show my-team\n\n# 查看团队状态\nclawteam team status my-team\n```\n\n## 相关资源\n\n| 资源 | 链接 |\n|------|------|\n| GitHub 仓库 | https://github.com/HKUDS/ClawTeam |\n| 快速开始 | https://github.com/HKUDS/ClawTeam#-quick-start |\n| CLI 参考 | skills/clawteam/references/cli-reference.md |\n| 技能文档 | skills/clawteam/SKILL.md |\n\n---\n\n![\"\"](\"assets/icon.png\"){kind=icon}
ClawTeam: Agent Swarm Intelligence