Coordinator

多 Agent 会话协调系统 — 让多个 Claude Code 会话通过 MCP 协议实现跨会话通信、状态共享、任务调度。

功能

• 会话管理 — 注册/注销会话，心跳检测，状态同步
• 消息传递 — 异步点对点消息和广播，支持 TTL 和 ACK
• 任务调度 — 任务看板，支持创建/认领/更新/完成，依赖关系和自动 unblock
• 三角色协作 — 产品经理、规划师、开发人员分工协作完成需求

环境要求

• Node.js 18+
• Claude Code（支持 MCP 的版本）

下一步

• 开发前后端
• 优化上下文开销

安装

git clone <repo-url>
cd agent-coordination-mcp
npm install

一键安装（Windows PowerShell）

.\setup.ps1

该脚本会自动完成：安装依赖 → 类型检查 → 运行测试 → 安装 Skill 到 ~/.claude/skills/

手动安装 Skill

如果不使用 setup.ps1，手动将 Skill 复制到 Claude Code 目录：

# 将 .claude/skills/coordinator/ 复制到全局 skills 目录
cp -r .claude/skills/coordinator ~/.claude/skills/

配置

方式一：通过 Claude Code CLI 添加（推荐）

claude mcp add coordinator -- npx tsx /path/to/this/project/src/server.ts

将 /path/to/this/project 替换为本项目的实际路径。

方式二：手动编辑 MCP 配置文件

在 Claude Code 的 MCP 配置文件中添加：

{
  "mcpServers": {
    "coordinator": {
      "command": "npx",
      "args": ["tsx", "/path/to/this/project/src/server.ts"]
    }
  }
}

配置文件位置：

• 全局配置：~/.claude/claude_desktop_config.json
• 项目配置：项目根目录下的 .mcp.json

生产模式配置

构建后使用编译产物运行，无需 tsx：

npm run build

{
  "mcpServers": {
    "coordinator": {
      "command": "node",
      "args": ["/path/to/this/project/dist/server.js"]
    }
  }
}

使用

1. 启动协调 Skill

在 Claude Code 中输入：

/coordinator product-manager
/coordinator planner
/coordinator developer

每个会话选择一个角色，Skill 会自动引导完成注册和初始化。

2. 三角色协作流程

用户提出需求
    │
    ▼
产品经理接收需求 → 创建规划任务 → 分配给规划师
    │
    ▼
规划师分析需求 → 拆解任务 → 输出 spec → 通知产品经理
    │
    ▼
产品经理审查 spec → 通过后创建开发任务 → 分配给开发人员
    │
    ▼
开发人员认领任务 → 按 spec 实现 → 完成后通知产品经理
    │
    ▼
产品经理验收 → 向用户汇报

验收失败时：

• 规划问题（spec 不符合预期）→ 创建任务给规划师重新规划
• 开发问题（spec 正确但实现有误）→ 创建任务给开发人员修复

3. 角色职责

角色	职责	禁止行为
product-manager	接收需求、分配任务、审查 spec、验收结果	写代码、绕过规划师
planner	分析需求、拆解任务、输出 spec	写代码、直接联系开发人员
developer	接收 spec、开发实现、交付验收	创建任务、直接联系规划师

MCP Tools 参考

会话管理

Tool	参数	说明
register_session	name: string	注册会话，同名幂等
unregister_session	session_id: string	注销会话，释放任务
heartbeat	session_id: string	心跳，建议每 30 秒一次
update_status	session_id, status	更新状态（idle/working/error）
list_sessions	status?	列出会话，可按状态过滤

消息传递

Tool	参数	说明
send_message	from, to, content, type?	发送消息，to="*" 为广播
get_messages	session_id, since?, type?	获取待处理消息
ack_message	message_id	确认消息已处理

任务管理

Tool	参数	说明
create_task	title, created_by, assignee?, priority?, depends_on?	创建任务
claim_task	task_id, session_id	认领任务（原子操作）
update_task	task_id, status?, assignee?, metadata?	更新任务，完成时自动 unblock 下游
list_tasks	status?, assignee?, created_by?	查询任务
watch_task	task_id	查看任务状态和变更记录

开发

常用命令

npm run dev          # 开发模式（tsx 直接运行）
npm run build        # 编译 TypeScript
npm start            # 运行编译产物
npm test             # 运行测试（watch 模式）
npm run test:run     # 运行测试（单次）
npm run typecheck    # 类型检查
npm run lint         # ESLint 检查

项目结构

src/
├── server.ts          # MCP Server 入口，注册所有 tools
├── db.ts              # SQLite 数据库初始化和迁移
├── session.ts         # 会话管理（注册、心跳、状态）
├── message.ts         # 消息传递（发送、获取、确认）
├── task.ts            # 任务管理（创建、认领、更新、查询）
├── config.ts          # 配置管理
├── health.ts          # 健康检查
├── alert.ts           # 告警机制
├── audit.ts           # 审计日志
├── api-version.ts     # API 版本管理
├── circuit-breaker.ts # 熔断器
├── types.ts           # 共享类型定义
└── tools.ts           # 工具函数

.claude/skills/coordinator/
├── SKILL.md           # Skill 入口定义
├── workflows.md       # 三角色工作流
└── examples.md        # 工具调用示例

设计原则

• 会话身份：每个 Claude Code 会话通过 register_session 获得唯一 ID
• 消息异步：发送方不阻塞，接收方按需拉取，持久化在 SQLite 中
• 任务即真相：所有会话共享同一个任务看板，状态变更原子化
• 心跳检测：超过 1 小时无心跳的会话标记为 stale，任务自动释放
• 级联 unblock：任务完成时自动解除下游 blocked 任务

License

MIT