概述

ClawTeam 是一个智能体蜂群编排（Agent Swarm Orchestration）命令行工具，旨在为 Claude Code、Codex、OpenClaw、nanobot 等终端原生客户端提供统一的协调层。通过 ClawTeam，用户可以在一个 CLI 界面中规划、委托和交付任务，使多个编码智能体能够协同工作而非孤立运行。资料来源：website/src/App.jsx:36

核心定位

ClawTeam 的设计目标是解决以下问题：

资料来源：website/src/App.jsx:52-54

支持的客户端

ClawTeam 支持多种编码智能体客户端：

资料来源：website/src/App.jsx:189-193

系统架构

整体架构图

graph TD
    subgraph "用户层"
        CLI[clawteam CLI]
    end
    
    subgraph "团队管理层"
        TeamMgr[团队管理器]
        Board[看板系统]
        Inbox[收件箱系统]
    end
    
    subgraph "任务系统"
        TaskStore[任务存储]
        PlanStore[计划存储]
    end
    
    subgraph "智能体层"
        Agent1[智能体 1]
        Agent2[智能体 2]
        AgentN[智能体 N]
    end
    
    subgraph "后端支持"
        Tmux[Tmux 后端]
        Wsh[Wsh 后端]
        Subprocess[子进程后端]
    end
    
    CLI --> TeamMgr
    CLI --> TaskStore
    TeamMgr --> Board
    TeamMgr --> Inbox
    TeamMgr --> PlanStore
    TaskStore --> Agent1
    TaskStore --> Agent2
    TaskStore --> AgentN
    Agent1 --> Tmux
    Agent2 --> Wsh
    AgentN --> Subprocess

目录存储结构

ClawTeam 使用本地文件系统存储团队数据：

~/.clawteam/
├── teams/{team}/
│   ├── config.json          # 团队配置（名称、成员、领导者）
│   └── inboxes/{agent}/     # 智能体收件箱
│       └── msg-{timestamp}-{uuid}.json  # 消息文件
├── tasks/{team}/
│   └── task-{id}.json       # 单独任务文件
└── plans/
    └── {agent}-{id}.md      # 计划文档

资料来源：skills/clawteam/references/cli-reference.md:180-190

核心功能模块

1. 团队管理（Team Management）

#### 团队生命周期

stateDiagram-v2
    [*] --> 创建团队: spawn-team
    创建团队 --> 发现团队: discover
    发现团队 --> 请求加入: request-join
    请求加入 --> 批准/拒绝: approve-join / reject-join
    批准 --> 团队活动: status
    拒绝 --> [*]

#### 团队命令

资料来源：skills/clawteam/references/cli-reference.md:100-145

2. 任务管理（Task Management）

#### 任务状态流转

stateDiagram-v2
    [*] --> 待处理: pending
    待处理 --> 进行中: in_progress
    进行中 --> 已完成: completed
    进行中 --> 已阻塞: blocked
    已阻塞 --> 待处理: unblock
    已完成 --> [*]

#### 任务依赖关系

当一个任务标记为 completed 时，任何被其阻塞的任务会自动解除阻塞（如果没有其他阻塞源）。

资料来源：skills/clawteam/references/cli-reference.md:45-50

#### 任务命令

#### 任务创建示例

clawteam task create dev-team "Implement auth" \
    -o alice \
    -d "Add JWT authentication" \
    -p high \
    --blocks T-002,T-003

资料来源：skills/clawteam/references/cli-reference.md:52-85

3. 看板系统（Board System）

#### 看板视图

graph LR
    subgraph "看板列"
        P[待处理]
        IP[进行中]
        B[已阻塞]
        C[已完成]
    end
    
    T1[任务 1] --> P
    T2[任务 2] --> IP
    T3[任务 3] --> B
    T4[任务 4] --> C

#### 看板命令

clawteam board show dev-team          # 人类可读看板
clawteam --json board show dev-team    # JSON 格式输出
clawteam board live dev-team --interval 2.0  # 每2秒刷新

资料来源：skills/clawteam/references/cli-reference.md:150-175

4. 计划审批系统（Plan Approval System）

#### 计划工作流

sequenceDiagram
    participant Agent as 智能体
    participant Leader as 团队领导者
    participant System as ClawTeam
    
    Agent->>System: plan submit <plan-content>
    System->>Leader: 发送审批请求
    Leader->>System: plan approve / reject
    System->>Agent: 返回审批结果

#### 计划命令

# 提交计划
clawteam plan submit dev-team alice "Implement OAuth2 flow" --summary "OAuth2方案"

# 批准计划
clawteam plan approve dev-team PLAN-001 alice --feedback "Good plan"

资料来源：skills/clawteam/references/cli-reference.md:88-98

5. 消息类型

资料来源：skills/clawteam/references/cli-reference.md:60-72

6. 生命周期管理（Lifecycle Management）

#### 生命周期状态机

stateDiagram-v2
    [*] --> 运行中
    运行中 --> 请求关闭: request-shutdown
    请求关闭 --> 批准关闭: approve-shutdown
    请求关闭 --> 拒绝关闭: reject-shutdown
    拒绝关闭 --> 运行中
    批准关闭 --> [*]
    运行中 --> 空闲: idle
    空闲 --> 运行中

#### 生命周期命令

资料来源：skills/clawteam/references/cli-reference.md:110-140

7. 智能体生成（Agent Spawning）

#### 后端类型

#### Spawn 命令

clawteam spawn <backend> <command...> [options]

#### 示例

# 使用 subprocess 后端生成
clawteam spawn subprocess claude --team dev-team --agent-name bob

# 使用 tmux 后端生成
clawteam spawn tmux claude-code --agent-name builder

# 指定团队和类型
clawteam spawn subprocess claude --team dev-team --agent-name researcher --agent-type researcher

资料来源：skills/clawteam/references/cli-reference.md:20-35

8. 身份管理（Identity Management）

每个智能体通过环境变量获取身份信息：

#### 身份命令

# 查看当前身份
clawteam identity show

# 设置身份（需要 eval 执行）
eval $(clawteam identity set --agent-name alice --team dev-team)

资料来源：skills/clawteam/references/cli-reference.md:36-50

工作流程示例

三步启动蜂群

graph LR
    A[安装 CLI] --> B[配置团队]
    B --> C[协调智能体]
    
    subgraph "步骤 1: 安装"
        A1[pip install clawteam]
    end
    
    subgraph "步骤 2: 配置"
        B1[spawn-team 创建团队]
        B2[spawn 生成智能体]
    end
    
    subgraph "步骤 3: 协调"
        C1[task 管理任务]
        C2[board 查看看板]
    end

完整示例

# 1. 创建团队
clawteam team spawn-team docs-sprint -d "文档冲刺团队"

# 2. 生成领导者智能体
clawteam spawn tmux claude-code --team docs-sprint --agent-name leader

# 3. 生成工作智能体
clawteam spawn tmux claude-code --team docs-sprint --agent-name builder

# 4. 创建任务
clawteam task create docs-sprint "构建落地页" -o builder -p high
clawteam task create docs-sprint "编写 API 文档" -o builder -p medium

# 5. 查看看板
clawteam board live docs-sprint

# 6. 智能体请求加入
clawteam team request-join docs-sprint builder

# 7. 领导者批准（另一终端）
clawteam team approve-join docs-sprint REQUEST-001 --assigned-name builder

资料来源：website/src/App.jsx:26-45

技术实现细节

Web Shell 后端

wsh_backend.py 实现了 Web Shell 后端，用于在 Web 环境中生成和管理智能体：

# 智能体注册
from clawteam.spawn.registry import register_agent

register_agent(
    team_name=team_name,
    agent_name=agent_name,
    backend="wsh",
    block_id=block_id,
    pid=pane_pid,
    command=list(final_command),
)

#### 运行时消息注入

Wsh 后端支持向运行中的智能体注入消息：

def inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:
    # 检查智能体是否存在
    info = get_registry(team).get(agent_name, {})
    # 检查块是否存活
    if not _is_block_alive(block_id):
        return False, f"wsh block '{block_id}' is not alive"

资料来源：clawteam/spawn/wsh_backend.py:1-60

上下文恢复系统

context_recovery.py 实现了智能体的上下文恢复能力：

def _teammate_summary(self, agent_name: str, team_name: str, role: str) -> str:
    """Layer 5: One-liner teammate summaries."""
    from clawteam.team.models import TaskStatus
    from clawteam.team.tasks import TaskStore
    
    store = TaskStore(team_name)
    tasks = store.list_tasks()
    # 按负责人分组统计任务进度

资料来源：clawteam/harness/context_recovery.py:1-50

会话定位器

session_locators/claude.py 处理 Claude Code 会话的持久化：

class ClaudeSessionLocator:
    def prepare(self, command, context: SessionContext) -> PreparedSession:
        # 检测 --continue/-c/--no-session-persistence
        if has_any(normalized, {"--continue", "-c", "--no-session-persistence"}):
            return PreparedSession(command=list(command), ...)
        
        # 自动生成会话 ID
        session_id = str(uuid.uuid4())
        return PreparedSession(command=[*command, "--session-id", session_id], ...)

资料来源：clawteam/spawn/session_locators/claude.py:1-40

CLI 命令解析

cli/commands.py 实现了团队启动命令：

def _human(_data):
    console.print(f"\n[green bold]Team '{t_name}' launched[/green bold]\n")
    table = Table(title="Agents")
    table.add_column("Name", style="cyan")
    table.add_column("Type")
    table.add_column("ID", style="dim")

输出后显示 attach 命令：

tmux attach -t clawteam-{team_name}  # 附加到 tmux 会话
clawteam board show {team_name}     # 查看看板
clawteam inbox peek {team_name} --agent <name>  # 查看收件箱

资料来源：clawteam/cli/commands.py:1-100

快速入门

前置要求

• Python 3.10+
• tmux（使用 tmux 后端时）
• 对应的智能体客户端（Claude Code、Codex 等）

安装

pip install clawteam

基本使用

# 创建团队
clawteam team spawn-team my-team

# 生成智能体
clawteam spawn tmux claude-code --team my-team --agent-name worker1

# 创建任务
clawteam task create my-team "完成功能开发" -o worker1 -p high

# 查看看板
clawteam board show my-team

# 查看团队状态
clawteam team status my-team

相关资源

系统要求

基础环境

可选依赖

客户端要求

ClawTeam 可与以下终端原生编码智能体配合使用：

• Claude Code (claude)
• Codex (codex)
• OpenClaw (openclaw)
• nanobot (nanobot)
• Gemini
• Kimi
• 任何支持 CLI 接口的智能体

安装方式

方式一：pip 安装（推荐）

使用 pip 直接安装 ClawTeam 是最简单的方式：

pip install clawteam

验证安装是否成功：

clawteam --version

方式二：安装 P2P 支持版本

如果需要使用点对点传输功能，安装带有 P2P 扩展的版本：

pip install "clawteam[p2p]"

资料来源：skills/clawteam/SKILL.md:1-20

方式三：本地脚本安装

项目提供了本地安装脚本，适合开发者或需要最新功能的用户：

bash scripts/install_clawteam.sh

或者使用交互式本地安装脚本：

bash scripts/clawteam_local_install

方式四：开发模式安装

对于需要修改源码或参与开发的用户：

git clone https://github.com/HKUDS/ClawTeam.git
cd ClawTeam
pip install -e .

配置文件架构

数据存储布局

ClawTeam 将所有数据存储在用户主目录下的 .clawteam 文件夹中：

~/.clawteam/
├── teams/{team}/
│   ├── config.json          # 团队配置（名称、成员、领导者）
│   └── inboxes/{agent}/     # 智能体收件箱（msg-{timestamp}-{uuid}.json）
├── tasks/{team}/
│   └── task-{id}.json       # 任务文件
├── plans/
│   └── {agent}-{id}.md      # 计划文档
├── profiles/                # 运行时配置文件
│   └── {profile-name}.json
├── presets/                 # 预设模板
│   └── {preset-name}.yaml
└── registry.json           # 智能体注册表

资料来源：skills/clawteam/references/cli-reference.md:1-100

Profile 配置文件

Profile 是可复用的客户端/提供商/运行时配置，被 spawn 和 launch 命令使用。

{
  "name": "my-profile",
  "client": "claude",
  "provider": "anthropic",
  "runtime": {
    "backend": "tmux",
    "environment": {
      "ANTHROPIC_API_KEY": "sk-..."
    }
  }
}

资料来源：clawteam/spawn/profiles.py

Preset 预设模板

Preset 是共享的提供商模板，用于生成一个或多个 Profile：

name: anthropic-cloud
provider: anthropic
defaults:
  model: claude-sonnet-4-20250514
  max_tokens: 8192
variants:
  - name: fast
    overrides:
      model: claude-haiku-4-20250514
  - name: powerful
    overrides:
      model: claude-opus-4-20250514
      max_tokens: 32768

资料来源：clawteam/spawn/presets.py

Profile 管理

Profile 是 ClawTeam 配置系统的核心，定义智能体的运行时环境。

创建 Profile

clawteam profile create <profile-name> [--client CLIENT] [--provider PROVIDER]

编辑 Profile

clawteam profile edit <profile-name>

列出所有 Profile

clawteam profile list

删除 Profile

clawteam profile delete <profile-name>

使用 Profile

clawteam profile use <profile-name>

Profile 向导

交互式创建 Profile：

clawteam profile wizard

该命令会启动 TUI 向导，引导用户完成 Profile 的创建过程。

Preset 管理

Preset 是预设模板，用于快速生成多个相关的 Profile。

创建 Preset

clawteam preset create <preset-name>

编辑 Preset

clawteam preset edit <preset-name>

列出所有 Preset

clawteam preset list

删除 Preset

clawteam preset delete <preset-name>

从 Preset 生成 Profile

clawteam preset generate <preset-name> [--variant VARIANT]

Spawn 生成配置

Spawn 命令用于启动新的智能体进程，配置选项如下：

clawteam spawn <backend> <command...> [options]

可用后端

Spawn 示例

# 使用 tmux 后端启动 Claude Code
clawteam spawn tmux claude --team dev-team --agent-name builder

# 使用 subprocess 后端启动
clawteam spawn subprocess codex --team dev-team --agent-name reviewer

环境变量

必需的环境变量

智能体通过以下环境变量识别身份：

会话相关变量

设置身份

使用 CLI 设置智能体身份：

eval $(clawteam identity set --agent-name alice --team dev-team)

显示当前身份：

clawteam identity show

资料来源：clawteam/spawn/session_locators/claude.py

团队配置

创建团队

clawteam team spawn-team <name> [options]

发现现有团队

clawteam team discover
clawteam --json team discover

查看团队状态

clawteam team status <team>

请求加入团队

clawteam team request-join <team> <proposed-name> [options]

上下文与 Git 配置

工作树隔离

ClawTeam 支持 Git 工作树隔离，确保不同智能体在独立的代码分支上工作：

clawteam context worktree create <team> <agent> <branch-name>

上下文注入

系统会自动将 Git 上下文注入到智能体的提示中，包括：

• 最近的文件变更
• 当前分支信息
• 未合并的更改
• 相关工作树的差异

快照功能

clawteam context snapshot <team> <agent>

创建当前状态的快照，便于回滚。

配置流程图

graph TD
    A[安装 ClawTeam] --> B{检查环境}
    B -->|缺少 tmux| C[安装 tmux]
    B -->|缺少 Python| D[安装 Python 3.10+]
    C --> E{选择安装方式}
    D --> E
    E -->|pip| F[pip install clawteam]
    E -->|本地脚本| G[运行安装脚本]
    E -->|开发模式| H[pip install -e]
    F --> I[验证安装]
    G --> I
    H --> I
    I --> J[创建 Profile]
    J --> K[配置 Preset]
    K --> L[创建团队]
    L --> M[生成智能体]

依赖配置参考

pyproject.toml 核心依赖

[project]
requires-python = ">=3.10"
dependencies = [
    "click",
    "typer",
    "pydantic>=2.0",
    "structlog",
    "rich",
    "pyyaml",
]

可选依赖：

[project.optional-dependencies]
p2p = ["libp2p", "torchao"]

资料来源：pyproject.toml

故障排除

安装失败

1. 确认 Python 版本：python --version（需要 3.10+）
2. 确认 pip 可用：pip --version
3. 尝试使用虚拟环境

无法启动智能体

1. 确认 tmux 已安装：tmux -V
2. 检查环境变量是否正确设置
3. 确认 Profile 配置有效

团队通信问题

1. 检查 ~/.clawteam/ 目录权限
2. 确认所有智能体的团队名称一致
3. 检查防火墙设置（P2P 模式需要特定端口）

后续步骤

安装配置完成后，建议按以下顺序继续：

1. 创建团队
2. 管理任务
3. 使用收件箱
4. CLI 参考手册

系统概述

ClawTeam 的核心功能包括：

• 团队管理：创建、发现、加入和退出团队
• 任务系统：支持依赖链和优先级的看板式任务管理
• Agent 生成：通过多种后端（tmux、subprocess、wsh）生成子进程 Agent
• 通信机制：支持点对点消息、广播、计划审批等多种消息类型
• 状态可视化：实时看板展示团队任务进度和消息历史

核心概念

身份与环境变量

每个 Agent 在启动时需要设置以下环境变量以标识自身身份：

资料来源：skills/clawteam/SKILL.md:1-10

团队角色

ClawTeam 中的 Agent 分为两种角色：

• Leader（领导者）：负责创建团队、审批计划、管理任务分配
• Member（成员）：执行分配的任务、向 Leader 提交计划

资料来源：clawteam/cli/commands.py:1-50

数据存储布局

ClawTeam 使用本地文件系统存储团队数据：

~/.clawteam/
├── teams/{team}/
│   ├── config.json          # 团队配置（名称、成员、领导者）
│   └── inboxes/{agent}/     # 消息收件箱
├── tasks/{team}/
│   └── task-{id}.json       # 任务文件
└── plans/
    └── {agent}-{id}.md      # 计划文档

资料来源：skills/clawteam/references/cli-reference.md:100-120

快速部署流程

第一步：设置领导者身份

在终端中设置领导者 Agent 的环境变量：

export CLAWTEAM_AGENT_ID="leader-001"
export CLAWTEAM_AGENT_NAME="leader"
export CLAWTEAM_AGENT_TYPE="leader"

资料来源：clawteam/cli/commands.py:50-80

第二步：创建团队

使用 team spawn-team 命令创建新团队：

clawteam team spawn-team my-project -d "Web app development" -n leader

参数说明：

资料来源：clawteam/team/manager.py:1-60

第三步：创建任务

使用 task create 命令创建任务，并设置任务间的依赖关系：

# 创建基础设计任务
clawteam task create my-project "Design API schema" -o leader

# 创建后端开发任务，依赖设计任务
clawteam task create my-project "Implement backend" -o backend-dev --blocked-by <design-task-id>

# 创建前端开发任务，依赖设计任务
clawteam task create my-project "Build frontend" -o frontend-dev --blocked-by <design-task-id>

# 创建集成测试任务，依赖前后端任务
clawteam task create my-project "Integration testing" --blocked-by <backend-task-id>,<frontend-task-id>

任务状态说明：

资料来源：clawteam/team/tasks.py:1-30

第四步：生成子 Agent

使用 spawn 命令在团队中生成新的 Agent 子进程：

clawteam spawn subprocess claude-code \
  --team my-project \
  --agent-name builder \
  --agent-type researcher

后端选项：

Agent 生成后，会自动注册到团队注册表中，并保持会话持久化。资料来源：clawteam/spawn/sessions.py:1-80

第五步：查看团队看板

使用 board show 命令查看团队状态：

clawteam board show my-project

看板会显示：

• 任务列表及其状态
• 团队成员
• 消息历史

如需实时刷新查看，可使用：

clawteam board live my-project --interval 2.0

资料来源：clawteam/cli/commands.py:200-250

团队生命周期管理

团队发现与加入

成员 Agent 可以发现并申请加入现有团队：

# 发现所有团队
clawteam team discover

# 申请加入团队
clawteam team request-join <team-name> <proposed-name> --capabilities "code review" --timeout 60

领导者审批加入请求：

clawteam team approve-join <team> <request-id> [--assigned-name NAME]
clawteam team reject-join <team> <request-id>

资料来源：clawteam/team/manager.py:60-120

Agent 生命周期

graph TD
    A[Agent 启动] --> B[设置环境变量]
    B --> C[request-join 申请加入团队]
    C --> D{Leader 审批}
    D -->|批准| E[join_approved 接收确认]
    D -->|拒绝| F[join_rejected 接收拒绝]
    E --> G[执行任务]
    G --> H[idle 通知完成]
    H --> I{shutdown 请求}
    I -->|批准| J[approve-shutdown 关闭]
    I -->|拒绝| G

关闭 Agent

发送关闭请求：

clawteam lifecycle request-shutdown <team> <from-agent> <to-agent> --reason "任务完成"

Agent 响应：

clawteam lifecycle approve-shutdown <team> <request-id> <agent>
# 或
clawteam lifecycle reject-shutdown <team> <request-id> <agent> --reason "仍有待处理任务"

资料来源：skills/clawteam/references/cli-reference.md:50-80

计划审批流程

成员 Agent 可以向 Leader 提交工作计划：

clawteam plan submit <team> <agent> <plan-content-or-file> --summary "实施计划"

Leader 审批计划：

clawteam plan approve <team> <plan-id> <agent> --feedback "计划可行"
# 或
clawteam plan reject <team> <plan-id> <agent> --feedback "需要补充测试用例"

graph LR
    A[成员 Agent] -->|plan_submit| B[提交计划]
    B --> C[Leader]
    C -->|plan_approve| D[批准]
    C -->|plan_reject| E[拒绝]
    D --> F[开始执行]
    E --> A

资料来源：clawteam/harness/context_recovery.py:80-150

任务更新与依赖管理

更新任务状态

# 标记任务进行中
clawteam task update <team> <task-id> --status in_progress --owner alice

# 标记任务完成
clawteam task update <team> <task-id> --status completed

# 添加阻塞关系
clawteam task update <team> <task-id> --add-blocks <other-task-id>

# 添加被阻塞关系
clawteam task update <team> <task-id> --add-blocked-by <blocking-task-id>

当任务标记为 completed 时，所有被该任务阻塞的任务会自动解除阻塞状态（从 blocked 变为 pending）。

任务列表查询

# 查看所有任务
clawteam task list <team>

# 按状态筛选
clawteam task list <team> --status in_progress

# 按负责人筛选
clawteam task list <team> --owner alice --sort-priority

资料来源：clawteam/team/tasks.py:20-60

会话持久化与恢复

ClawTeam 支持 Agent 会话的持久化和恢复功能。当 Agent 需要中断后继续工作时，系统会捕获当前会话状态并在重启时恢复：

clawteam spawn subprocess claude-code --resume

会话恢复时，系统会：

1. 从 SessionStore 加载之前的会话 ID
2. 注入原生客户端的恢复标志
3. 在提示词中添加恢复说明

资料来源：clawteam/spawn/session_locators/claude.py:30-80

后端后端选项详解

Tmux 后端

默认后端，使用 Tmux 会话运行 Agent：

clawteam spawn tmux claude-code --team my-project --agent-name worker1

Subprocess 后端

直接启动子进程：

clawteam spawn subprocess claude-code --team my-project

WebSocket Shell 后端

通过 WebSocket 方式管理 Agent：

clawteam spawn wsh claude-code --team my-project

支持运行时消息注入：

# 通过 RPC 向运行中的 Agent 注入消息
rpc_client = WshRpcClient()
rpc_client.inject_message(team, agent_name, envelope)

资料来源：clawteam/spawn/wsh_backend.py:30-100

典型工作流程示例

graph TD
    A[Leader 创建团队] --> B[Leader 创建任务]
    B --> C[生成开发者 Agent]
    C --> D[开发者 Agent 申请加入]
    D --> E[Leader 审批加入]
    E --> F[开发者 Agent 提交计划]
    F --> G[Leader 审批计划]
    G --> H[开发者执行任务]
    H --> I{任务完成?}
    I -->|否| H
    I -->|是| J[更新任务状态]
    J --> K{所有任务完成?}
    K -->|否| B
    K -->|是| L[Agent 进入 idle]
    L --> M[发送 shutdown 请求]
    M --> N[关闭团队]

详细工作流程示例请参考官方文档中的 Workflows。

常用命令速查表

下一步

• 查看 CLI 参考文档 获取完整命令列表
• 参考 工作流程示例 了解典型场景
• 配置 运行时配置文件 优化 Agent 行为

1. 项目概述

ClawTeam 是一个为 Claude Code、Codex、OpenClaw、nanobot、 Gemini 等终端原生客户端设计的智能体集群编排命令行工具。其核心目标是解决多个自主编码智能体之间的协调、任务分配、状态管理和通信问题，使多个 AI 智能体能够像人类团队一样协同规划和交付软件项目。

资料来源：website/index.html:10-15

graph TB
    subgraph 用户层
        CLI[命令行界面]
        Web[Web 控制台]
    end
    
    subgraph 核心编排层
        Orchestrator[编排器]
        Conductor[调度器]
        Manager[团队管理器]
    end
    
    subgraph 通信层
        TaskStore[任务存储]
        MessageBus[消息总线]
        PlanStore[计划存储]
    end
    
    subgraph 运行时层
        Spawner[智能体生成器]
        WSH[wsh 后端]
        TMUX[tmux 后端]
        Subprocess[子进程后端]
    end
    
    CLI --> Orchestrator
    Web --> Orchestrator
    Orchestrator --> Conductor
    Orchestrator --> Manager
    Manager --> TaskStore
    Manager --> MessageBus
    Conductor --> PlanStore
    Spawner --> WSH
    Spawner --> TMUX
    Spawner --> Subprocess

2. 核心模块架构

2.1 编排层 (Orchestration Layer)

编排层是 ClawTeam 的核心大脑，负责协调所有智能体的生命周期和交互流程。

#### 2.1.1 上下文恢复模块 (Context Recovery)

context_recovery.py 实现了智能体的上下文恢复机制，确保每个智能体在执行任务时能够获取必要的历史信息和团队状态。

# 层级化上下文注入机制
def _teammate_summary(self, agent_name: str, team_name: str, role: str) -> str:
    """Layer 5: One-liner teammate summaries."""
    from clawteam.team.models import TaskStatus
    from clawteam.team.tasks import TaskStore
    store = TaskStore(team_name)
    tasks = store.list_tasks()

该模块提供五个层级的上下文注入：

资料来源：clawteam/harness/context_recovery.py:30-60

2.2 团队管理层 (Team Management)

团队管理模块负责维护团队的配置、成员列表和通信拓扑。

#### 2.2.1 文件存储布局

~/.clawteam/
├── teams/{team}/
│   ├── config.json          # 团队配置 (名称、成员、领导者)
│   └── inboxes/{agent}/     # 消息收件箱
│       └── msg-{timestamp}-{uuid}.json
├── tasks/{team}/
│   └── task-{id}.json       # 任务文件
└── plans/
    └── {agent}-{id}.md      # 计划文档

资料来源：skills/clawteam/references/cli-reference.md:180-200

2.3 任务管理子系统

任务存储采用模块化设计，通过兼容性填充（Shim）保持向后兼容：

# clawteam/team/tasks.py
from clawteam.store.base import BaseTaskStore, TaskLockError
from clawteam.store.file import FileTaskStore

TaskStore = FileTaskStore

#### 2.3.1 任务状态模型

资料来源：skills/clawteam/references/cli-reference.md:95-105

#### 2.3.2 任务依赖机制

当任务标记为 completed 时，系统自动将所有被其阻塞的任务从未决（pending）队列中解除阻塞：

# 伪代码描述逻辑
if task.status == 'completed':
    for blocked_task in task.blocks:
        if not blocked_task.has_other_blockers:
            blocked_task.status = 'pending'

3. 智能体运行时架构

3.1 多后端支持

ClawTeam 支持多种智能体运行环境后端，实现灵活的部署策略：

graph LR
    A[spawn 命令] --> B[Backend Registry]
    B --> C[wsh]
    B --> D[tmux]
    B --> E[subprocess]
    
    C --> F[Windows Subsystem]
    D --> G[终端复用器]
    E --> H[直接子进程]

#### 3.1.1 WebShell 后端 (wsh)

wsh_backend.py 实现了 Windows Subsystem for Linux 的集成：

def spawn(self, agent_name: str, team_name: str, command: list[str]) -> str:
    block_id = self._create_block(
        session_name=agent_name,
        title=agent_name,
        command=list(final_command),
    )
    
    from clawteam.spawn.registry import register_agent
    register_agent(
        team_name=team_name,
        agent_name=agent_name,
        backend="wsh",
        block_id=block_id,
        pid=pane_pid,
    )

特性：

• 支持运行时消息注入
• 块存活状态检测
• RPC 客户端集成

资料来源：clawteam/spawn/wsh_backend.py:30-80

3.2 智能体注册机制

# 智能体注册表数据结构
registry = {
    "team-name": {
        "agent-name": {
            "backend": "wsh|tmux|subprocess",
            "block_id": "xxx",
            "pid": 12345,
            "command": ["cmd1", "cmd2"],
        }
    }
}

4. 消息与通信系统

4.1 消息类型体系

资料来源：skills/clawteam/references/cli-reference.md:110-125

4.2 生命周期管理

stateDiagram-v2
    [*] --> 创建: spawn-team
    创建 --> 运行中: approve-join
    运行中 --> 空闲: lifecycle idle
    空闲 --> 运行中: 接收新任务
    运行中 --> 关闭请求: request-shutdown
    关闭请求 --> 已关闭: approve-shutdown
    关闭请求 --> 运行中: reject-shutdown

5. 计划审批工作流

5.1 计划提交流程

Agent --> PlanStore: submit <team> <agent> <plan-content>
Leader --> 检查: 查看计划内容
Leader --> approve/reject: 决策

5.2 CLI 命令接口

# 提交计划
clawteam plan submit <team> <agent> <plan-content-or-file> [--summary TEXT]

# 审批计划
clawteam plan approve <team> <plan-id> <agent> [--feedback TEXT]

# 拒绝计划
clawteam plan reject <team> <plan-id> <agent> [--feedback TEXT]

6. 团队协作命令体系

6.1 团队管理命令

资料来源：skills/clawteam/references/cli-reference.md:130-160

6.2 spawn 命令参数

clawteam spawn <backend> <command...> [options]

支持后端：subprocess、tmux、wsh

7. Web 可视化界面

Web 界面 (App.jsx) 提供实时终端模拟和团队状态可视化：

// 团队状态展示
<div className="t-status-header">
  docs-sprint <span className="t-dim">3 agents active</span>
</div>
<div className="t-status-row">
  <span className="t-success">●</span> 
  T-001 Build landing page <span className="t-badge t-done">done</span>
</div>
<div className="t-status-row">
  <span className="t-active">●</span> 
  T-002 Write API docs <span className="t-badge t-progress">active</span>
</div>
<div className="t-status-row">
  <span className="t-dim">○</span> 
  T-003 Review & merge <span className="t-badge t-blocked">blocked</span>
</div>

资料来源：website/src/App.jsx:1-50

8. 数据流架构图

graph TD
    subgraph 用户交互
        CLI[CLI 命令]
        WebUI[Web 界面]
    end
    
    subgraph 核心服务
        Orchestrator[编排器]
        Conductor[调度器]
        TeamManager[团队管理器]
    end
    
    subgraph 存储层
        TaskStore[任务存储]
        PlanStore[计划存储]
        MessageStore[消息存储]
        AgentRegistry[智能体注册表]
    end
    
    subgraph 运行时
        WSHBackend[wsh 后端]
        TMUXBackend[tmux 后端]
        SubprocessBackend[子进程后端]
    end
    
    CLI -->|命令解析| Orchestrator
    WebUI -->|HTTP/WS| Orchestrator
    
    Orchestrator -->|调度任务| Conductor
    Orchestrator -->|团队管理| TeamManager
    
    Conductor -->|读写| PlanStore
    TeamManager -->|读写| TaskStore
    TeamManager -->|读写| MessageStore
    TeamManager -->|注册| AgentRegistry
    
    AgentRegistry -->|启动| WSHBackend
    AgentRegistry -->|启动| TMUXBackend
    AgentRegistry -->|启动| SubprocessBackend
    
    WSHBackend -->|反馈| AgentRegistry
    TMUXBackend -->|反馈| AgentRegistry
    SubprocessBackend -->|反馈| AgentRegistry

9. 关键技术特性

9.1 智能体类型系统

9.2 任务优先级机制

clawteam task create <team> <subject> [options]
  --priority, -p  优先级: low | medium | high | urgent
  --blocked-by    依赖任务列表
  --blocks        阻塞任务列表

10. 总结

ClawTeam 的架构设计遵循以下核心原则：

1. 模块化解耦：各子系统（任务管理、消息通信、计划审批）独立运作
2. 多后端兼容：支持 wsh、tmux、subprocess 等多种运行时环境
3. 状态驱动：基于文件的状态持久化，支持断点恢复
4. 层级化上下文：为智能体提供渐进式的上下文注入
5. 审批工作流：关键决策（如计划、加入、关闭）需经过审批流程

这种架构使 ClawTeam 能够有效地协调多个 AI 智能体，实现复杂的软件开发和协作任务。

概述

Harness 是 ClawTeam 项目中负责为 AI Agent 运行时注入上下文、管理团队协作状态、以及协调任务执行的中间层组件。Harness 并非一个单一的模块，而是一组协同工作的子系统的集合，包括上下文恢复（Context Recovery）、契约执行（Contract Execution）、阶段管理（Phases）、策略调度（Strategies）、以及协调器（Orchestrator）。

ClawTeam 的核心定位是多智能体编排框架（Agent Swarm Orchestration），而 Harness 则是将这一编排能力落地的关键引擎。它负责：

1. 上下文管理 — 为 Agent 注入团队任务、成员、契约等运行时上下文
2. 契约执行 — 根据预定义的契约（Contract）协调 Agent 行为
3. 阶段控制 — 管理工作流的阶段切换与依赖关系
4. 策略调度 — 根据不同策略选择执行路径和优先级

资料来源：skills/clawteam/references/cli-reference.md

概述

智能体 Spawn 系统是 ClawTeam 的核心组件之一，负责在团队环境中动态启动、注册和管理外部编码智能体进程。该系统通过抽象化的后端适配器架构，支持多种进程管理方式（tmux、subprocess、WebSocket Handler 等），并与团队身份系统、消息收件箱、任务管理模块紧密协作，使主控智能体能够统一编排分布式编码任务。

Spawn 系统的设计目标：

• 提供统一的智能体进程生命周期管理接口
• 支持多后端运行时（tmux、subprocess、wsh 等）
• 自动注入团队上下文（团队名称、智能体身份、领导节点信息）
• 与会话恢复机制集成，支持断点续传
• 通过注册中心维护运行中智能体的元数据

系统架构

核心组件关系

graph TD
    subgraph "CLI 入口层"
        CLI[clawteam spawn 命令]
        CMD[commands.py 解析]
    end
    
    subgraph "后端适配层"
        BASE[base.py - BaseBackend 抽象]
        TMUX[TmuxBackend]
        SUB[SubprocessBackend]
        WSH[WshBackend]
        AD[Adapters 适配器]
    end
    
    subgraph "会话管理层"
        SESS[SessionStore]
        CAPT[SessionCapture]
        REG[Registry 注册中心]
    end
    
    subgraph "上下文注入"
        PROMPT[prompt.py - 智能体提示词]
        ENV[环境变量注入]
    end
    
    CLI --> CMD
    CMD --> BASE
    BASE --> TMUX
    BASE --> SUB
    BASE --> WSH
    CMD --> AD
    CMD --> REG
    CMD --> PROMPT
    TMUX --> SESS
    SUB --> SESS
    REG --> SESS

关键模块职责

后端适配器架构

BaseBackend 抽象基类

所有后端必须继承 BaseBackend 并实现以下核心方法：

class BaseBackend(ABC):
    @abstractmethod
    def spawn(self, command: list[str], **kwargs) -> str:
        """启动新智能体进程"""
    
    @abstractmethod
    def list_running(self) -> list[dict[str, str]]:
        """列出运行中的智能体"""
    
    @abstractmethod
    def inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:
        """向运行中的智能体注入消息"""

资料来源：clawteam/spawn/base.py:1-20

支持的后端类型

Spawn 命令示例：

clawteam spawn subprocess claude --team dev-team --agent-name builder --agent-type researcher
clawteam spawn tmux claude --team dev-team --agent-name coder

资料来源：clawteam/cli/commands.py:50-60

注册中心机制

Registry 模块

Registry 提供团队内智能体的注册与查询功能：

from clawteam.spawn.registry import register_agent, get_registry

register_agent(
    team_name=team_name,
    agent_name=agent_name,
    backend="wsh",
    block_id=block_id,
    pid=pane_pid,
    command=list(final_command),
)

注册信息结构

注册后，智能体可通过 get_registry(team_name) 查询：

info = get_registry(team).get(agent_name, {})
block_id = info.get("block_id", "")

资料来源：clawteam/spawn/wsh_backend.py:80-90

会话管理系统

SessionStore

SessionStore 负责持久化管理团队智能体会话状态：

from clawteam.spawn.sessions import SessionStore

session_store = SessionStore(_team)
session = session_store.load(_name)

关键功能：

• 会话持久化：将智能体会话状态写入磁盘
• 会话恢复：支持智能体断点续传
• 状态查询：加载历史会话信息

资料来源：clawteam/spawn/sessions.py:1-30

会话恢复流程

graph LR
    A[加载 SessionStore] --> B{是否存在历史会话?}
    B -->|是| C[获取 session_id]
    C --> D[build_cli_resume_command]
    D --> E[拼接恢复命令]
    E --> F[注入 resume 标志]
    B -->|否| G[正常启动]

if resume:
    from clawteam.spawn.session_capture import build_resume_command
    
    session = session_store.load(_name)
    if session and session.session_id:
        resumed_command = build_cli_resume_command(
            command, session.session_id, client=client
        )
        if prompt:
            prompt += "\nYou are resuming a previous session."

资料来源：clawteam/cli/commands.py:100-115

提示词构建系统

build_agent_prompt 函数

prompt.py 中的 build_agent_prompt 函数负责生成智能体的系统提示词，包含团队上下文信息：

from clawteam.spawn.prompt import build_agent_prompt

prompt = build_agent_prompt(
    agent_name=_name,
    agent_id=_id,
    agent_type=agent_type,
    team_name=_team,
    leader_name=leader_name,
    task=task,
    user=user_name,
    workspace_dir=cwd or "",
    workspace_branch=ws_branch,
    isolated_workspace=bool(workspace and cwd),
    repo_path=repo,
)

提示词包含的信息

资料来源：clawteam/spawn/prompt.py:1-50

运行时消息注入

inject_runtime_message 接口

后端实现者必须提供运行时消息注入能力，用于向运行中的智能体发送控制消息：

def inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:
    """Best-effort runtime injection into a running agent."""
    from clawteam.spawn.registry import get_registry
    
    info = get_registry(team).get(agent_name, {})
    block_id = info.get("block_id", "") or self._blocks.get(agent_name, "")
    
    if not block_id:
        return False, f"Agent block for '{team}/{agent_name}' not found"
    
    if not _is_block_alive(block_id):
        return False, f"Block '{block_id}' is not alive"

返回值：tuple[bool, str] - 成功/失败状态及消息

资料来源：clawteam/spawn/wsh_backend.py:95-115

CLI 命令集成

Spawn 命令参数

clawteam spawn <backend> <command...> [options]

完整示例

# 在 tmux 后端启动 researcher 类型智能体
clawteam spawn tmux claude --team dev-team --agent-name researcher --agent-type researcher

# 在 subprocess 后端启动通用智能体
clawteam spawn subprocess claude-code --team dev-team --agent-name builder

# 使用特定工作目录
clawteam spawn tmux claude --team docs-team --agent-name writer \
    --workspace-dir /home/user/project --workspace-branch feature/docs

资料来源：clawteam/cli/commands.py:45-75

智能体生命周期

graph TD
    A[Spawn 命令] --> B[注册到 Registry]
    B --> C[创建 Session]
    C --> D[构建 Prompt]
    D --> E[调用后端 spawn]
    E --> F{后端类型}
    F -->|tmux| G[创建 tmux session]
    F -->|subprocess| H[fork 子进程]
    F -->|wsh| I[创建 wsh block]
    G --> J[启动智能体]
    H --> J
    I --> J
    J --> K[智能体运行中]
    K --> L[可接收消息注入]
    K --> M[可更新任务状态]
    L --> N[生命周期结束]
    M --> N

数据存储布局

Spawn 系统相关的持久化数据存储在 ~/.clawteam/ 目录下：

~/.clawteam/
├── teams/{team}/
│   ├── config.json          # 团队配置
│   └── inboxes/{agent}/     # 智能体收件箱
├── sessions/{team}/
│   └── {agent}.json         # 会话状态文件
└── registry/
    └── {team}.json          # 智能体注册信息

与其他模块的交互

团队模块集成

Spawn 系统依赖团队模块提供的领导节点信息：

# 获取团队领导名称
tmpl = load_template("default")
leader_name = tmpl.leader.name

# 判断当前智能体是否为领导
is_leader = agent.name == tmpl.leader.name

任务模块集成

Spawn 后的智能体可更新任务状态：

clawteam task update dev-team <task-id> --status completed

生命周期模块集成

智能体完成任务后可发送空闲通知：

clawteam lifecycle idle dev-team --last-task <task-id> --task-status completed

扩展新的后端

如需添加新的后端（如 Docker、Kubernetes），需：

1. 继承 BaseBackend 抽象类
2. 实现 spawn、list_running、inject_runtime_message 方法
3. 在 adapters.py 或独立文件中实现
4. 在 CLI 命令解析中注册新后端

class DockerBackend(BaseBackend):
    def spawn(self, command: list[str], **kwargs) -> str:
        container_id = self._create_container(command, **kwargs)
        return f"Agent spawned in container {container_id}"
    
    def list_running(self) -> list[dict[str, str]]:
        # 返回运行中的容器
        pass
    
    def inject_runtime_message(self, team: str, agent_name: str, envelope) -> tuple[bool, str]:
        # 向容器内进程发送信号
        pass

最佳实践

1. 使用 tmux 后端进行调试：tmux 后端支持手动 attach 查看智能体输出
2. 使用 subprocess 后端进行 CI/CD：适合无头环境
3. 充分利用会话恢复：长时间任务建议使用 --resume 标志
4. 正确设置智能体类型：有助于团队任务分配和资源调度
5. 配合任务系统使用：Spawn 后立即创建任务并分配给智能体

总结

智能体 Spawn 系统是 ClawTeam 实现多智能体协作的基础设施，通过模块化的后端适配器、统一的注册中心、持久化的会话管理和智能的提示词注入，使得主控节点能够灵活地启动、管理和协调各类外部编码智能体。该系统的设计遵循开闭原则，便于扩展新的运行时后端，同时与团队管理、任务调度、消息通信等模块无缝集成，共同构建完整的智能体编排平台。

概述

Spawn 后端是 ClawTeam 系统中负责在团队环境中启动和管理外部 AI Agent 进程的核心组件。它提供了一套统一的抽象接口，支持多种底层进程管理方式（如 tmux、subprocess、wsh），使团队协调层能够独立于具体执行后端工作。

Spawn 模块的职责包括：

• 为新启动的 Agent 注入团队身份环境变量（CLAWTEAM_AGENT_ID、CLAWTEAM_AGENT_NAME、CLAWTEAM_TEAM 等）
• 管理 Agent 的生命周期（启动、监控、终止）
• 支持会话恢复（session resume）功能
• 与模板系统（Template）集成，支持批量启动团队成员

资料来源：clawteam/cli/commands.py:1-50

架构设计

整体架构图

graph TD
    subgraph "CLI 层"
        CLI[clawteam spawn 命令]
        Launch[clawteam launch 命令]
    end
    
    subgraph "Spawn 核心"
        Registry[Agent 注册表]
        SessionStore[会话存储]
        PromptBuilder[提示词构建]
    end
    
    subgraph "后端实现层"
        TMuxBackend[tmux_backend.py]
        SubprocessBackend[subprocess_backend.py]
        WshBackend[wsh_backend.py]
    end
    
    subgraph "底层执行"
        TMux[tmux 会话]
        Process[子进程]
        WshBlocks[wsh blocks]
    end
    
    CLI --> Registry
    CLI --> PromptBuilder
    Launch --> TMuxBackend
    Launch --> SubprocessBackend
    Launch --> WshBackend
    TMuxBackend --> TMux
    SubprocessBackend --> Process
    WshBackend --> WshBlocks
    Registry --> SessionStore

后端抽象基类

Spawn 系统采用后端插件化设计，所有后端需实现统一的接口：

资料来源：clawteam/spawn/wsh_backend.py:30-60

tmux 后端实现

tmux 后端通过创建独立的 tmux 会话来隔离每个 Agent 的运行环境。

核心流程

1. 构建 tmux 命令，包含会话命名和窗口配置
2. 使用 tmux new-session 创建新会话
3. 向新会话发送 Agent 启动命令
4. 注册 Agent 信息到全局注册表
5. 持久化会话捕获数据

会话隔离策略

每个 Agent 在独立的 tmux 会话中运行，会话命名格式为 clawteam-{team}-{agent}。这种隔离确保：

• 一个 Agent 的输出不会干扰其他 Agent
• 可以独立 attach/detach 到特定 Agent 会话
• Agent 崩溃不会影响团队其他成员

资料来源：clawteam/spawn/session_capture.py

subprocess 后端实现

subprocess 后端直接通过 Python 的 subprocess 模块启动子进程，适合轻量级或无持久化需求的场景。

特性

• 支持 stdout/stderr 管道捕获
• 可配置工作目录（CWD）
• 支持环境变量注入
• 适合短生命周期任务

wsh 后端实现

wsh（WezTerm Shell）后端是 ClawTeam 针对 WezTerm 终端仿真器的专用实现，利用 WezTerm 的 pane 和 RPC 功能实现高级交互。

WshBackend 核心功能

class WshBackend:
    def spawn(self, ...) -> str:
        """启动 wsh block 中的 Agent"""
        
    def list_running(self) -> list[dict[str, str]]:
        """列出当前运行的 wsh block"""
        
    def inject_runtime_message(self, team, agent_name, envelope) -> tuple[bool, str]:
        """向运行中的 wsh block 注入运行时消息"""

资料来源：clawteam/spawn/wsh_backend.py:1-100

RPC 消息注入

wsh 后端支持向已启动的 Agent 实时注入消息，流程如下：

sequenceDiagram
    participant CLI as CLI 命令
    participant Registry as Agent 注册表
    participant WshRPC as WshRpcClient
    participant Block as wsh Block

    CLI->>Registry: 查询 agent 对应的 block_id
    Registry-->>CLI: block_id
    CLI->>WshRPC: inject_runtime_message(envelope)
    WshRPC->>Block: 发送渲染后的通知
    Block-->>WshRPC: 确认
    WshRPC-->>CLI: (True, "success")

资料来源：clawteam/spawn/wsh_rpc.py

Agent 注册与追踪

注册表机制

ClawTeam 使用集中式注册表管理所有已启动的 Agent 实例：

register_agent(
    team_name=team_name,
    agent_name=agent_name,
    backend="wsh",
    block_id=block_id,
    pid=pane_pid,
    command=list(final_command),
)

注册信息包括：

资料来源：clawteam/spawn/registry.py

会话持久化

Spawn 模块支持会话捕获和恢复：

persist_spawned_session(
    session_capture,
    team_name=team_name,
    agent_name=agent_name,
    command=list(final_command),
)

会话存储允许：

• 保存 Agent 的完整命令历史
• 支持后续会话恢复（resume）
• 记录 Agent 状态快照

资料来源：clawteam/spawn/sessions.py

与其他模块的集成

与模板系统集成

Spawn 与模板系统（clawteam/templates/）深度集成，支持通过模板定义团队结构：

# 从模板加载后，使用 spawn 批量启动
spawned.append({
    "name": agent.name,
    "id": a_id,
    "type": agent.type,
    "result": spawn_result
})

资料来源：clawteam/templates/__init__.py

与 CLI 命令集成

Spawn 功能通过 clawteam spawn 和 clawteam launch 命令暴露给用户：

参数配置：

资料来源：clawteam/cli/commands.py

会话恢复机制

Resume 流程

Spawn 模块支持从上次中断点恢复 Agent 会话：

1. 检测 --resume 参数
2. 从 SessionStore 加载历史会话数据
3. 根据原始客户端类型构建恢复命令
4. 注入会话 ID 和客户端标识

if resume:
    session = session_store.load(_name)
    if session and session.session_id:
        resumed_command = build_cli_resume_command(command, session.session_id, client=client)
        prompt += "\nYou are resuming a previous session."

资料来源：clawteam/spawn/sessions.py

配置选项

Spawn 启动参数

环境变量注入

Spawn 自动向启动的 Agent 注入以下环境变量：

扩展新的后端

要添加新的 Spawn 后端，需实现以下接口：

class BaseBackend:
    def spawn(
        self,
        command: List[str],
        team_name: str,
        agent_name: str,
        **kwargs
    ) -> str:
        """启动 Agent 进程，返回启动描述"""
        raise NotImplementedError
    
    def list_running(self) -> List[Dict[str, str]]:
        """返回运行中的 Agent 列表"""
        raise NotImplementedError
    
    def inject_runtime_message(
        self, 
        team: str, 
        agent_name: str, 
        envelope
    ) -> tuple[bool, str]:
        """向运行中的 Agent 注入消息"""
        raise NotImplementedError

注册新后端时，需要在 clawteam/spawn/backends.py 中添加入口点映射。

概述

ClawTeam 的团队生命周期管理是一个多代理协作框架，负责协调代理（Agent）的创建、任务分配、团队治理和优雅关闭的全过程。该系统通过 CLI 命令驱动，支持任务依赖链、会话持久化和基于消息的代理间通信。

核心职责范围：

• 团队的创建、发现和状态监控
• 代理的 Spawn（生成）与注册
• 任务的创建、更新和依赖管理
• 团队成员间的消息传递与计划审批
• 优雅关闭流程（Graceful Shutdown）
• 领导选举与心跳监控

资料来源： skills/clawteam/references/cli-reference.md

概述

任务管理与依赖链是 ClawTeam 协作框架的核心子系统，负责协调多智能体团队中的工作分配、状态追踪和执行顺序控制。该模块使团队能够创建结构化的任务网络，通过依赖关系确保任务按照正确的顺序执行，并支持看板式的可视化工作流管理。

ClawTeam 的任务系统基于文件系统存储，通过统一的 TaskStore 接口提供增删改查功能，并自动处理任务间的依赖解除逻辑。资料来源：clawteam/team/tasks.py:1-14

核心架构

存储层次

clawteam.team.tasks (兼容性垫片)
         │
         ▼
clawteam.store.base (BaseTaskStore 接口定义)
         │
         ▼
clawteam.store.file (FileTaskStore 具体实现)
         │
         ▼
~/.clawteam/tasks/{team}/task-{id}.json (持久化文件)

资料来源：clawteam/team/tasks.py:1-14

关键类导出

数据模型

任务状态

资料来源：skills/clawteam/references/cli-reference.md

任务结构

{
  "id": "aaa11111",
  "subject": "Design API schema",
  "description": "Create REST API specification",
  "owner": "backend-dev",
  "status": "pending",
  "priority": "medium",
  "blocks": [],
  "blocked_by": [],
  "created_at": "2024-01-15T10:30:00Z"
}

依赖链机制

工作原理

依赖链允许任务声明对其他任务的依赖关系（blocked_by），确保前置任务完成后，后置任务才能执行。

graph LR
    A[T-001 设计架构] -->|blocked_by| B[T-002 后端实现]
    A[T-001 设计架构] -->|blocked_by| C[T-003 前端开发]
    B -->|blocked_by| D[T-004 集成测试]
    C -->|blocked_by| D[T-004 集成测试]

资料来源：skills/clawteam/references/workflows.md

自动解除阻塞

当任务状态变为 completed 时，系统自动检查所有依赖该任务的其他任务：

1. 遍历依赖列表中的每个任务
2. 检查该任务的 blocked_by 集合
3. 如果所有 blocker 都已完成，将该任务状态从 blocked 更新为 pending
4. 释放任务锁，允许新所有者接管

# 示例：完成后自动解除阻塞
clawteam task update my-project aaa11111 --status completed
# bbb22222 和 ccc33333 自动从 blocked -> pending

资料来源：skills/clawteam/references/cli-reference.md

CLI 命令接口

创建任务

clawteam task create <team> <subject> [options]

示例：

# 创建基础任务
clawteam task create dev-team "Design system" -o leader

# 创建依赖链
clawteam task create my-project "Implement backend" -o dev1 --blocked-by aaa11111
clawteam task create my-project "Build frontend" -o dev2 --blocked-by aaa11111
clawteam task create my-project "Integration tests" --blocked-by bbb22222,ccc33333

资料来源：skills/clawteam/references/cli-reference.md

更新任务

clawteam task update <team> <task-id> [options]

关键行为：使用 --status completed 会自动触发依赖解除逻辑。资料来源：skills/clawteam/references/cli-reference.md

查询任务

# 获取单个任务详情
clawteam task get <team> <task-id>

# 列出团队所有任务（支持过滤）
clawteam task list <team> [--status STATUS] [--owner NAME] [--priority LEVEL] [--sort-priority]

MCP 工具集成

ClawTeam 提供 MCP（Model Context Protocol）工具接口，允许 AI 智能体直接通过工具调用操作任务系统。资料来源：clawteam/mcp/tools/task.py

工具能力

• task_create: 创建新任务并设置依赖
• task_update: 更新任务状态和属性
• task_get: 获取单个任务详情
• task_list: 列出并过滤任务
• task_delete: 删除任务（谨慎使用）

智能体上下文恢复

在多智能体协作场景中，context_recovery.py 模块利用任务系统为智能体提供团队状态摘要：

from clawteam.team.models import TaskStatus
from clawteam.team.tasks import TaskStore

store = TaskStore(team_name)
tasks = store.list_tasks()

# 按负责人分组统计
owner_status: dict[str, tuple[int, int]] = {}
for t in tasks:
    if t.owner and t.owner != agent_name:
        done, total = owner_status.get(t.owner, (0, 0))
        total += 1
        if t.status == TaskStatus.completed:
            done += 1
        owner_status[t.owner] = (done, total)

资料来源：clawteam/harness/context_recovery.py

完整工作流示例

场景：Web 应用开发团队

# 1. 设置领导者身份
export CLAWTEAM_AGENT_ID="leader-001"
export CLAWTEAM_AGENT_NAME="leader"
export CLAWTEAM_AGENT_TYPE="leader"

# 2. 创建团队
clawteam team spawn-team web-project -d "Web 应用开发" -n leader

# 3. 创建任务依赖链
clawteam task create web-project "设计系统架构" -o leader
# => 任务 ID: arch-001

clawteam task create web-project "实现后端 API" -o backend-dev --blocked-by arch-001
# => 任务 ID: backend-001 (自动设为 blocked)

clawteam task create web-project "开发前端界面" -o frontend-dev --blocked-by arch-001
# => 任务 ID: frontend-001 (自动设为 blocked)

clawteam task create web-project "集成测试" --blocked-by backend-001,frontend-001
# => 任务 ID: test-001

# 4. 查看看板
clawteam board show web-project

# 5. 架构完成后，自动解除阻塞
clawteam task update web-project arch-001 --status completed
# backend-dev 和 frontend-dev 的任务自动变为 pending

# 6. 后端和前端都完成后，测试任务解除阻塞
clawteam task update web-project backend-001 --status completed
clawteam task update web-project frontend-001 --status completed
# test-001 自动从 blocked 变为 pending

资料来源：skills/clawteam/references/workflows.md

持久化存储

文件结构

~/.clawteam/
└── tasks/
    └── {team}/
        └── task-{id}.json    # 单个任务文件

每个任务以 JSON 格式独立存储在对应团队的目录下，便于版本控制和团队间迁移。资料来源：skills/clawteam/references/cli-reference.md

任务文件格式

{
  "id": "task-xxx",
  "subject": "任务标题",
  "description": "任务描述",
  "owner": "负责人名称",
  "status": "pending|in_progress|completed|blocked",
  "priority": "low|medium|high|urgent",
  "blocks": ["被此任务阻塞的任务ID"],
  "blocked_by": ["阻塞此任务的任务ID"],
  "created_at": "ISO时间戳",
  "updated_at": "ISO时间戳"
}

最佳实践

1. 最小化依赖深度：依赖链过长会增加调试难度，建议控制在 3-4 层以内
2. 明确负责人：每个任务都应指定明确的负责人，避免责任真空
3. 及时更新状态：智能体完成任务后应立即更新状态，确保依赖链正确推进
4. 使用看板监控：定期使用 clawteam board show 或 clawteam board live 监控团队进度
5. 优先级梯度：使用 priority 选项确保关键路径上的任务优先处理

概述

ClawTeam 的智能体间消息通信系统是协调多智能体团队工作的核心基础设施。该系统提供点对点消息传递、广播通信、消息路由、任务依赖管理和生命周期控制等功能，使团队中的各个智能体能够有效地进行协作。

消息系统基于文件存储实现，每个智能体拥有独立的收件箱（Mailbox），消息以结构化的 JSON 格式持久化存储在本地文件系统中。资料来源：clawteam/team/mailbox.py:1-50

系统架构

整体架构图

graph TD
    A[智能体 A] -->|发送消息| B[Mailbox 模块]
    B --> C[消息路由器 Router]
    C -->|点对点| D[智能体 B 收件箱]
    C -->|广播| E[所有成员收件箱]
    
    F[CLI 命令] -->|mailbox send| B
    G[CLI 命令] -->|mailbox broadcast| B
    H[CLI 命令] -->|mailbox receive| B
    
    I[生命周期事件] -->|join/leave/shutdown| B
    J[任务事件] -->|plan/status| B

核心组件

资料来源：clawteam/mcp/tools/mailbox.py:1-30

消息类型

ClawTeam 定义了完整的消息类型体系，涵盖智能体协作的各个场景：

资料来源：skills/clawteam/references/cli-reference.md:60-80

消息数据结构

消息文件格式

消息以 JSON 格式存储在 ~/.clawteam/teams/{team}/inboxes/{agent}/msg-{timestamp}-{uuid}.json 路径下。

{
  "id": "msg-1234567890-abc123",
  "type": "message",
  "from": "leader",
  "to": "researcher",
  "content": "请研究微服务的认证模式",
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": null,
  "key": null,
  "proposed_name": null,
  "capabilities": null,
  "feedback": null,
  "reason": null,
  "assigned_name": null,
  "agent_id": null,
  "team_name": "dev-team",
  "plan_file": null,
  "summary": null,
  "plan": null,
  "last_task": null,
  "status": null
}

MessagePayload 数据模型

@dataclass
class MessagePayload:
    msg_id: str              # 消息唯一标识
    msg_type: MessageType    # 消息类型枚举
    from_agent: str          # 发送方名称
    to_agent: str            # 接收方名称
    content: str             # 消息内容
    timestamp: str           # ISO8601 时间戳
    # ... 其他可选字段

资料来源：clawteam/team/mailbox.py:20-60

核心 API

发送消息 (mailbox_broadcast)

广播消息给团队所有成员：

def mailbox_broadcast(
    team_name: str,
    from_agent: str,
    content: str,
    msg_type: str | None = None,
    key: str | None = None,
    exclude: list[str] | None = None,
) -> list[dict]:
    """Broadcast a message to team inboxes."""

资料来源：clawteam/mcp/tools/mailbox.py:50-70

接收消息 (mailbox_receive)

接收并消费待处理的消息：

def mailbox_receive(
    team_name: str, 
    agent_name: str, 
    limit: int = 10
) -> list[dict]:
    """Receive and consume pending inbox messages."""

预览消息 (mailbox_peek)

预览待处理消息但不消费：

def mailbox_peek(
    team_name: str, 
    agent_name: str
) -> list[dict]:
    """Preview pending inbox messages without consuming them."""

获取消息数量 (mailbox_peek_count)

def mailbox_peek_count(
    team_name: str, 
    agent_name: str
) -> dict:
    """Get the number of pending inbox messages."""
    return {"agentName": agent_name, "count": team_mailbox.team_mailbox(...).count}

资料来源：clawteam/mcp/tools/mailbox.py:70-90

CLI 命令接口

inbox send - 发送消息

clawteam inbox send <team> <to-agent> <content> [--type TYPE] [--key KEY]

inbox receive - 接收消息

clawteam inbox receive <team> [--agent AGENT] [--limit LIMIT]

inbox peek - 预览消息

clawteam inbox peek <team> [--agent AGENT]

inbox broadcast - 广播消息

clawteam inbox broadcast <team> <content> [--exclude AGENT,AGENT...]

资料来源：skills/clawteam/references/cli-reference.md:1-50

协作工作流

工作流 1：领导者分配任务

sequenceDiagram
    participant L as 领导者
    participant M as Mailbox
    participant W as Worker
    
    L->>M: inbox send "执行数据分析"
    M-->>W: 消息投递到收件箱
    W->>W: inbox receive 获取消息
    W->>W: 执行任务
    W->>M: task update --status completed
    W->>M: lifecycle idle 通知

工作流 2：计划审批流程

# 智能体提交计划
clawteam plan submit dev-team coder "实现步骤..." \
  --summary "Auth 系统现代化"

# 领导者检查收件箱
clawteam inbox receive dev-team --agent leader
# => plan_approval_request with planId

# 领导者审批
clawteam plan approve dev-team <plan-id> coder --feedback "看起来不错，开始执行"

资料来源：skills/clawteam/references/workflows.md:30-60

工作流 3：优雅关闭

sequenceDiagram
    participant L as 领导者
    participant M as Mailbox
    participant W as Worker
    
    L->>M: lifecycle request-shutdown --reason "所有任务完成"
    M-->>W: shutdown_request 投递
    W->>W: inbox receive 获取关闭请求
    W->>W: 完成当前工作
    W->>M: lifecycle approve-shutdown
    L->>M: team cleanup --force

# 领导者请求关闭
clawteam lifecycle request-shutdown dev-team leader coder --reason "所有任务完成"

# Worker 查看收件箱
clawteam inbox receive dev-team --agent coder
# => shutdown_request, requestId: shut-xyz

# Worker 批准关闭
clawteam lifecycle approve-shutdown dev-team shut-xyz coder

资料来源：skills/clawteam/references/workflows.md:70-95

文件存储布局

~/.clawteam/
├── teams/{team}/
│   ├── config.json          # 团队配置（名称、成员、领导者）
│   └── inboxes/{agent}/     # 各智能体收件箱
│       ├── msg-{timestamp}-{uuid}.json  # 消息文件
│       └── ...
├── tasks/{team}/
│   └── task-{id}.json       # 任务文件
└── plans/
    └── {agent}-{id}.md      # 计划文档

消息文件命名格式：msg-{timestamp}-{uuid}.json，确保消息按时间顺序排列且具有全局唯一性。

资料来源：skills/clawteam/references/cli-reference.md:90-110

消息与板卡集成

Board 命令提供团队状态总览，包含消息历史：

clawteam board show <team>
clawteam --json board show <team>

JSON 输出包含成员感知字段：

浏览器板卡使用这些字段过滤收件箱历史记录，实现消息导航功能。

资料来源：skills/clawteam/references/cli-reference.md:115-130

最佳实践

消息设计原则

1. 消息幂等性：使用 request_id 确保消息处理的幂等性
2. 内容简洁：消息内容应清晰表达意图，避免过长文本
3. 类型明确：根据消息目的选择正确的消息类型
4. 状态同步：定期使用 mailbox_peek_count 检查未读消息

错误处理

当消息处理失败时，系统通过以下机制保证可靠性：

• 消息持久化存储在文件系统，重启后可恢复
• 使用 mailbox_peek 而非 mailbox_receive 进行消息预览，避免意外消费
• mailbox_peek_count 返回消息计数，便于监控队列状态

性能考虑

• 消息文件按时间戳命名，便于顺序读取
• 建议定期清理已处理消息，避免收件箱膨胀
• 大规模团队建议监控 ~/.clawteam/ 目录大小

总结

ClawTeam 的智能体间消息通信系统提供了完整的多智能体协作基础设施：

• 9+ 消息类型覆盖协作全生命周期
• 文件存储确保消息可靠持久化
• MCP 工具和 CLI 命令双重接口
• 与板卡系统集成提供可视化监控
• 工作流模板简化常见协作场景

该系统使开发者能够轻松构建、协调和管理多智能体团队，实现复杂的软件工程任务自动化。

Pitfall Log / 踩坑日志

项目：HKUDS/ClawTeam

摘要：发现 15 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Security testing for multi-agent swarms: agent isolation, delegation trust, inbox spoofing。

1. 安全/权限坑 · 来源证据：Security testing for multi-agent swarms: agent isolation, delegation trust, inbox spoofing

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security testing for multi-agent swarms: agent isolation, delegation trust, inbox spoofing
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_d8bd96f00b7c46c6813bc15c32a84625 | https://github.com/HKUDS/ClawTeam/issues/76 | 来源类型 github_issue 暴露的待验证使用条件。

2. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | host_targets=claude, claude_code, cursor, chatgpt

3. 配置坑 · 来源证据：Proposal: 8-PR sequence — canonical WorkerState, persistent event log, project namespacing, contract verify states, SCM…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Proposal: 8-PR sequence — canonical WorkerState, persistent event log, project namespacing, contract verify states, SCM plugin + reaction engine
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_114771b2a1474b358b05a6a9e61807f6 | https://github.com/HKUDS/ClawTeam/issues/157 | 来源类型 github_issue 暴露的待验证使用条件。

4. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | README/documentation is current enough for a first validation pass.

5. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | last_activity_observed missing

6. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | no_demo; severity=medium

7. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 建议检查：转成明确权限清单和安全审查提示。
• 防护动作：安全注意事项必须面向用户前置展示。
• 证据：risks.safety_notes | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | No sandbox install has been executed yet; downstream must verify before user use.

8. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | no_demo; severity=medium

9. 安全/权限坑 · 来源证据：Agent Definitions Feature is Non-Functional: Parsed but Not Applied

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Agent Definitions Feature is Non-Functional: Parsed but Not Applied
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_dc9ad856da7a4a828860da94afadc7ec | https://github.com/HKUDS/ClawTeam/issues/146 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

10. 安全/权限坑 · 来源证据：High: /api/proxy board endpoint enables SSRF and arbitrary outbound fetches

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：High: /api/proxy board endpoint enables SSRF and arbitrary outbound fetches
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_61dec732a08f4279a590654f0eecea51 | https://github.com/HKUDS/ClawTeam/issues/104 | 来源类型 github_issue 暴露的待验证使用条件。

11. 安全/权限坑 · 来源证据：Worker agents exit after first turn despite 'ongoing job' task prompt

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Worker agents exit after first turn despite 'ongoing job' task prompt
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_26124d52e6d948b2bf15809390ef2589 | https://github.com/HKUDS/ClawTeam/issues/148 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

12. 安全/权限坑 · 来源证据：[Feature Request] Optimize Worker Workspace Size and Enable Headless IPC

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Optimize Worker Workspace Size and Enable Headless IPC
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_63b04b7d23e74c71a8c1f8dddcaa9281 | https://github.com/HKUDS/ClawTeam/issues/45 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

13. 安全/权限坑 · 来源证据：v0.2.0 — Stabilization Release

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.0 — Stabilization Release
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2aca0ffb17f94d8bb219737c9f275e7f | https://github.com/HKUDS/ClawTeam/releases/tag/v0.2.0 | 来源类型 github_release 暴露的待验证使用条件。

14. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | issue_or_pr_quality=unknown

15. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | art_abc9b09559e64bd4983fa470a78389f3 | https://github.com/HKUDS/ClawTeam#readme | release_recency=unknown