企业官网建设流程全解析

• 人工智能
• AI Agent
• 多智能体
• Agent 编排
• Agent 工作流
• MCP 服务

ClawTeam（Agent Swarm Intelligence）是一个框架无关的多 Agent 协作编排工具，其 ROADMAP.md 记录了项目从 v0.2 单机文件系统阶段走向分布式协作的完整演进路径：Phase 1 Transport 抽象层、Phase 2 Redis Transport、Phase 3 共享状态层、Phase 4 多用户协作与 Phase 5 Web UI。本文以路线图为骨架，结合仓库内实际源码（clawteam/transport/、clawteam/store/、clawteam/team/mailbox.py、clawteam/cli/commands.py等）逐层拆解每一阶段的设计动机、架构变化、具体任务与验收标准，帮助读者理解 ClawTeam 的通信层如何一步步做到"消息可插拔、状态可共享、团队可跨机"，并掌握与之对应的环境变量与 CLI 实操。

现状 (v0.2)：单机文件系统的能跑版本

路线图首先划定了 v0.2 的基线能力边界，用一句话概括就是：

单用户 → 单机 → 文件系统 → CLI 驱动

这一阶段有三个明确约束：

• 所有数据在~/.clawteam/（团队配置、任务、消息）；
• 所有 agent 必须在同一台机器；
• 纯文件 I/O，零依赖。

从源码看，这一"纯文件 I/O"的基线在仓库中至今仍被完整保留。团队配置以config.json形式存于{data_dir}/teams/{team}/（见 clawteam/team/manager.py），消息则被序列化为{data_dir}/teams/{team}/inboxes/{agent}/msg-{ts}-{uid}.json的单文件（见 clawteam/transport/file.py），任务存放于{data_dir}/tasks/{team}/task-{id}.json（见 clawteam/store/file.py）。数据目录本身由CLAWTEAM_DATA_DIR环境变量或~/.clawteam决定（见 clawteam/team/models.py）。

需要说明的是，路线图中标注为"现在（v0.3）"的总览段落显示：Config 系统、多用户协作、Web UI、SSHFS 跨机器方案在当前仓库中已经完成（详见下文"总览"一节），因此 v0.2 描述的是架构演进的逻辑起点，而 v0.3 是当前版本的实际能力基线。

Phase 1：Transport 抽象层 (v0.3)——让消息通信层可插拔

目标：让消息通信层可插拔，不改上层接口。

这是整个路线图的第一块基石：如果连"发消息"这件事都被抽象出来，后续 Redis、P2P 乃至任意自定义通道都可以无缝替换，而MailboxManager及其上层 CLI 完全无感知。

架构变化

路线图给出的架构变化如下：

现在: MailboxManager → 直接读写文件 Phase 1: MailboxManager → Transport(接口) ├── FileTransport (默认，当前行为) └── (未来: RedisTransport, ...)

对照当前仓库，这一目标已经落地。Transport是一个 ABC 抽象基类（clawteam/transport/base.py），定义了四个抽象方法与一个默认空实现的close()：

值得强调的设计细节在fetch()的 docstring 中写得很清楚：Transport 只搬运原始字节（opaque message bytes），不做消息解析。把字节解析成TeamMessage、以及是否将畸形载荷隔离（quarantine）的责任交给MailboxManager这类上层调用者（见 clawteam/transport/base.py）。这保证了抽象层极薄、极通用。

接口上还有一个可选的扩展点：transport 可以额外实现claim_messages()返回ClaimedMessage（ack / quarantine 回调），从而支持"先认领、后确认/隔离"的消费语义（见 clawteam/transport/claimed.py）。MailboxManager.receive()会优先使用该扩展点，否则退回fetch(consume=True)路径（见 clawteam/team/mailbox.py）。

FileTransport：当前行为

FileTransport把mailbox.py原有的文件操作完整承接为独立类（clawteam/transport/file.py）：

• 每条消息一个文件：{data_dir}/teams/{team}/inboxes/{agent}/msg-{ts}-{uid}.json；
• 采用"临时文件写入 +os.replace原子改名"的方式避免半写被读到（deliver中先写.tmp-{uid}.json再原子替换）；
• 读取时借助 OS 级文件锁（Unix 用fcntl.flock，Windows 用msvcrt）实现并发安全，并将已认领消息改名.consumed后缀，防止重复消费；
• 解析失败的载荷会被移入{data_dir}/teams/{team}/dead_letters/{agent}/死信目录并附带.meta.json元信息（源文件名、错误、隔离时间戳），避免"坏消息卡死队列"。

这些细节在 tests/test_mailbox.py 中都有对应验证，例如test_send_and_receive_single验证发送与接收闭环、test_receive_consumes_messages验证消费后二次 receive 为空。

工厂与选择机制

transport 的实例化统一走 clawteam/transport/init.py 中的get_transport(name, team_name)工厂，并维护一个_TRANSPORT_REGISTRY注册表，允许插件通过register_transport()注册自定义 backend——这正是路线图"可插拔"诉求的落地形式。

默认 transport 的解析逻辑在MailboxManager._default_transport()（见 clawteam/team/mailbox.py）：

1. 优先读环境变量CLAWTEAM_TRANSPORT；
2. 未设置时读配置文件中的transport字段；
3. 二者皆空则回落到"file"。

这与路线图 Phase 1 的验收标准"CLAWTEAM_TRANSPORT=file为默认值"完全一致。CLI 层面同样提供了--transport全局选项（file或p2p，见 clawteam/cli/commands.py），设置后注入CLAWTEAM_TRANSPORT环境变量。

TaskStore 抽象

路线图要求"TaskStore 抽象，同样抽出FileTaskStore，预留接口"。仓库中的实现为 clawteam/store/base.py 的BaseTaskStore与 clawteam/store/file.py 的FileTaskStore。

BaseTaskStore的接口设计（create/get/update/list_tasks/release_stale_locks/get_stats）预留了并发控制责任："实现必须自行处理与其存储介质匹配的并发控制（文件锁、Redis 事务等）"（见 clawteam/store/base.py）。FileTaskStore的_write_lock同样用fcntl/msvcrt序列化写操作，并实现了任务依赖环检测（_validate_blocked_by_unlocked用 DFS 防环）与任务锁的force覆盖语义（_acquire_lock）。配置字段task_store（默认"file"）在 clawteam/config.py 中明确注释为"extensible for redis/sql later"，与路线图的"预留接口"呼应。

交付物结构

路线图要求的目录结构在仓库中均已就位：

clawteam/transport/ ├── __init__.py # Transport 注册表 + get_transport 工厂 ├── base.py # Transport 抽象基类 ├── claimed.py # ClaimedMessage（ack/quarantine） ├── file.py # FileTransport（默认） └── p2p.py # P2PTransport（见下文扩展） clawteam/store/ ├── __init__.py ├── base.py # BaseTaskStore 抽象基类 └── file.py # FileTaskStore

验收：所有现有命令行为不变，CLAWTEAM_TRANSPORT=file为默认值——该验收已通过，且被 tests/conftest.py 用临时CLAWTEAM_DATA_DIR隔离的测试套件持续保障。

跨机器消息通信的两种已实现路径

路线图的 Phase 2 规划的是 Redis Transport，但仓库当前实际落地的是另一条"轻量"路径：ZeroMQ P2P Transport（clawteam/transport/p2p.py）与 Redis 发布/订阅唤醒层（clawteam/team/redis_wakeup.py）。这两者与 Phase 2 目标一致——支持跨机器消息通信——但依赖更轻、零外部基础设施也能跑。

P2PTransport：ZeroMQ PUSH/PULL + 文件兜底

clawteam/transport/p2p.py 的实现要点：

• PULL socket 监听：bind_agent设置时绑定随机 TCP 端口，并在共享文件系统写入peers/{agent}.json（含 host、port、pid、心跳与租约元数据），通过心跳线程每 1 秒刷新（_peer_heartbeat_interval_s = 1.0，租约 5 秒）；
• PUSH socket 发送：deliver()先查peers/{recipient}.json，若 peer 存活（同机校验 PID、异机校验租约新鲜度）则直接 ZMQ 发送，发送失败自动降级走FileTransport兜底；
• 关闭清理：close()停止心跳、注销 peer 文件、关闭所有 socket 并ctx.term()。

同机 peer 用 PID 存活判断，异机 peer 依赖leaseExpiresAtMs租约元数据——这段"同机/异机"差异化判定逻辑（见 clawteam/transport/p2p.py）恰好弥补了文件系统 peer 注册表在跨机器场景下的陈旧 peer 问题。

Redis 唤醒层：可选的高频实时通道

clawteam/team/redis_wakeup.py 的resolve_wakeup()支持三种模式：

• off：显式关闭；
• redis://...：使用显式 URL（对应路线图的CLAWTEAM_REDIS_URL）；
• auto：优先用环境变量/状态文件中的 URL，都没有且本机存在redis-server时自动拉起一个本地 Redis 实例（写入teams/{team}/redis.json状态）。

消息发送与任务变更都会以 best-effort 方式向clawteam:{team}:agent:{name}与clawteam:{team}:tasks等频道PUBLISH唤醒事件（见 clawteam/team/redis_wakeup.py），失败静默忽略，绝不阻塞主流程。这与路线图 Phase 2 "消息通信 → Redis（高频，实时）"的方向一致，且被设计为可选项而非强依赖。

路线图 Phase 2 的原始规划与验收示例

路线图的 Phase 2 规划本身依然值得完整保留，因为它是理解"为什么需要 Redis Transport"的说明书：

架构变化：

机器A (leader) ─── RedisTransport ──┐ ├── Redis Server 机器B (worker) ─── RedisTransport ──┘ 团队配置 / 任务 → 仍然用文件（或共享文件系统） 消息通信 → Redis (高频，实时)

具体任务：RedisTransport 实现（LPUSH/RPOP实现 send/receive）、连接管理（URL 配置、连接池、断线重连）、配置方式（CLAWTEAM_TRANSPORT=redis+CLAWTEAM_REDIS_URL=redis://...）、broadcast 实现（依赖 TeamManager 获取团队成员列表）、混合模式（消息走 Redis、配置/任务走文件）、两台机器（或两个 container）的集成测试。

新增依赖：redis（pypi），可选安装pip install clawteam[redis]。

验收示例（原样继承）：

# 机器 A export CLAWTEAM_TRANSPORT=redis export CLAWTEAM_REDIS_URL=redis://192.168.1.100:6379 clawteam team spawn-team dev-team -n leader clawteam spawn tmux claude --team dev-team -n worker1 --task "..." # 机器 B export CLAWTEAM_TRANSPORT=redis export CLAWTEAM_REDIS_URL=redis://192.168.1.100:6379 clawteam inbox receive dev-team --agent worker1 # => 收到消息 ✅

其中clawteam team spawn-team的-n/--agent-name参数在 clawteam/cli/commands.py 中实现，clawteam inbox receive的--agent参数在 clawteam/cli/commands.py 中实现，均可对照查阅。

Phase 3：共享状态层 (v0.5)——团队配置与任务也跨机器

Phase 2 只解决了消息跨机器，但团队配置（config.json）和任务（task-*.json）仍在本地文件。Phase 3 的目标是让它们也共享，路线图给出两条路线：

路线 A：NFS / 共享文件系统

# 所有机器挂载同一个 NFS export CLAWTEAM_DATA_DIR=/mnt/shared/clawteam # 零代码改动，直接可用

零代码改动的根本原因：所有路径都经过get_data_dir()（clawteam/team/models.py）这一唯一入口——它读取CLAWTEAM_DATA_DIR环境变量、配置或默认~/.clawteam，因此只要把共享目录挂载到各机器并设置同一环境变量，团队配置、任务、inbox 消息自然落在同一份数据上。路线图总览中的 v0.3 也确认"跨机器方案：SSHFS/云盘 +CLAWTEAM_DATA_DIR，零代码改动"已经完成。

路线 B：Redis 统一存储

消息 → Redis (Phase 2 已做) 配置 → Redis Hash 任务 → Redis Hash 所有状态都在 Redis，文件系统只做本地缓存

具体任务：RedisTeamStore（团队配置存 Redis Hash）、RedisTaskStore（任务存 Redis Hash）、数据迁移工具clawteam migrate file-to-redis、统一配置CLAWTEAM_BACKEND=redis一个变量搞定所有。

验收：两台机器共享同一个团队、同一个任务板、同一个消息队列。

从当前源码结构看，BaseTaskStore/Transport的抽象已为路线 B 预留了全部接缝（存储实现与消息实现都只需实现各自的抽象基类），task_store配置字段注释也明确"extensible for redis/sql later"（clawteam/config.py），但RedisTeamStore/RedisTaskStore与迁移工具尚属未来规划，应视为路线图承诺而非已实现能力。

Phase 4：多用户协作 (v0.6)——不同人的 agent 组成一个团队

目标：不同人的 agent 组成一个团队。

路线图列出的新增能力：

用户 A 的 Claude Code ──┐ ├── Redis ── Team: project-x 用户 B 的 Claude Code ──┘ 用户 A 的 agent 和用户 B 的 agent 在同一个团队里协作

值得注意的是，路线图总览中 v0.3 已完成内容已包含"多用户协作：CLAWTEAM_USER/clawteam config set user，(user, name) 复合唯一性"。对照源码：

• 用户身份来源：AgentIdentity.from_env()依次读取CLAWTEAM_USER→ 兼容的OH_USER→ 配置文件user字段（clawteam/identity.py）；
• (user, name) 复合唯一性：TeamManager.add_member()校验"同名且同 user 的成员不可重复加入"（clawteam/team/manager.py）；
• 命名空间落盘：inbox_name_for()将带 user 的成员映射为{user}_{name}作为 inbox 目录名（clawteam/team/manager.py），与路线图的user1/worker1命名空间设计一一对应；resolve_inbox()则负责把逻辑名解析为实际的 on-disk inbox（clawteam/team/manager.py）。

测试侧也有覆盖：tests/test_cli_commands.py中大量用例同时设置CLAWTEAM_DATA_DIR与CLAWTEAM_USER=alice（如 tests/test_cli_commands.py），验证多用户场景下的命令行为。

权限模型与 Token 认证在当前仓库中未见实现，属未来规划范畴。

Phase 5：Web UI (v1.0)——浏览器看板替代终端 Rich 渲染

目标：浏览器看板，替代终端 Rich 渲染。规划命令为：

clawteam board serve --port 8080

规划能力：实时看板（WebSocket 推送）、多团队概览、任务拖拽、消息历史。

对照源码，clawteam board serve已经实现（clawteam/cli/commands.py），支持--port（默认 8080）、--host（默认 127.0.0.1）、--interval（SSE 推送间隔，默认 2 秒）与可选默认团队参数。其实现是 clawteam/board/server.py：

• 基于标准库ThreadingHTTPServer的轻量 HTTP 服务，零第三方依赖；
• 路由：/与/index.html提供静态页面，/api/overview返回多团队概览，/api/team/{team}返回单团队快照，/api/events/{team}以SSE（text/event-stream）实时推送团队状态，/api/proxy提供受限的 GitHub 内容代理（仅允许api.github.com、github.com、raw.githubusercontent.com，并拦截内网/回环地址，防止 SSRF）；
• TeamSnapshotCache用 TTL 缓存团队快照，SSE 每interval秒推送一次；
• do_POST支持POST /api/team/{team}/task创建任务。

值得注意的两点：

1. 规划写的是"WebSocket 推送"，实际实现为SSE（Server-Sent Events）——路线图总览 v0.3 已完成内容明确记录"Web UI：clawteam board serve，SSE 实时推送，深色主题看板"，以源码与总览为准；
2. 终端侧的 Rich 渲染看板依然保留：clawteam board show（单团队看板）、clawteam board overview（多团队概览）、clawteam board live（每--interval秒刷新，见 clawteam/cli/commands.py），另有board attach（tmux 平铺聚合所有 agent 窗口）与board gource（Gource 动画可视化团队活动）。"任务拖拽"属规划项，静态页面 clawteam/board/static/index.html 中未见拖拽交互，需谨慎表述为"路线图规划能力"。

总览：版本路线与当前进度

路线图总览给出的版本编排：

v0.2 → 单机文件系统，能用 v0.3 (现在) → Config 系统 + 多用户协作 + Web UI (已完成，跨机器用 SSHFS) v0.4+ → 可选: Transport 抽象层 / Redis (如需超出 SSHFS 的场景)

v0.3 已完成内容（当前仓库实际状态）

• Config 系统：clawteam config show/set/get/health。实现见 clawteam/config.py 与 clawteam/cli/commands.py。配置优先级为环境变量 > 配置文件 > 默认值（get_effective()，见 clawteam/config.py），关键标量键包括：

• 多用户协作：CLAWTEAM_USER/clawteam config set user，(user, name) 复合唯一性；
• Web UI：clawteam board serve，SSE 实时推送，深色主题看板；
• 跨机器方案：SSHFS/云盘 +CLAWTEAM_DATA_DIR，零代码改动。

此外，clawteam config health已作为子命令存在（对应 CLI 参考文档 docs/skills/clawteam/references/cli-reference.md 与 skills/clawteam/references/cli-reference.md 中的完整命令清单，可对照查阅全部子命令）。

协作建议：两人并行的分工模式

路线图末尾给出了两人并行开发的最佳分工模式，核心思路是接口先行、存储与传输并行：

Phase 1: 人员 A — Transport 抽象 + FileTransport 人员 B — Store 抽象 + FileTaskStore + 测试 Phase 2: 人员 A — RedisTransport 核心实现 人员 B — 配置系统 + broadcast + 集成测试 Phase 3: 人员 A — RedisTeamStore 人员 B — RedisTaskStore + 迁移工具

其关键方法论是："接口定义（Phase 1）要先一起对齐，后面就可以各做各的。" 这与仓库中Transport（clawteam/transport/base.py）与BaseTaskStore（clawteam/store/base.py）的抽象设计完全吻合——两个纯抽象接口将"消息 I/O"与"任务存储"解耦为独立的替换单元，后续任何 backend 都可以在不动上层的前提下并行开发。

总结：路线图与源码的对照结论

ClawTeam 的演进路线给分布式多 Agent 协作工具提供了一个清晰的工程范式：先定义薄抽象接口，再以文件系统实现兜底行为，最后按需替换为 Redis/ZMQ 等高性能通道。对于想要在局域网、容器或云盘环境下搭建多机 Agent 团队的开发者，当前版本已经可以通过CLAWTEAM_DATA_DIR（共享文件系统）与CLAWTEAM_TRANSPORT（file/p2p）+ 可选 Redis 唤醒层拼出一套"消息实时、配置共享、零强依赖"的协作底座；而当场景超出 SSHFS 的能力边界时，Phase 2/3 的 Redis 规划路线正是下一步的自然延伸。

• 人工智能
• AI Agent
• 多智能体
• Agent 编排
• Agent 工作流
• MCP 服务