local-coord

一个跑在本机的多智能体协同开发调度服务 —— 让 Codex、Claude Code、智谱 Z Code 的多个真实会话，共用同一块任务板、同一条证据链、同一套质量流程。

A local-first coordination service for multi-agent development. Multiple real sessions from Codex / Claude Code / Z Code share one task board, one evidence chain and one quality workflow over MCP + PostgreSQL — with roles, scope/branch/worktree locks, and review-gated integration enforced by the server, not by prompts.

协调者 ──拆分/分发──▶ 执行者 ──提交+自测──▶ 监督者审查 ──▶ 测试者独立验收 ──▶ 协调者集成复测
   ▲                    │                        │                │                    │
   └──────────────── 质量退回 / 暂停 / 重派 ←─────┴────────────────┴────────────────────┘

为什么需要它

单会话 AI 编码工具已经很能干，但当多个智能体（甚至多个工具）同时开工时，缺的不是模型能力，而是工程纪律的执行者：

• 谁在改哪些目录？两个任务会不会改同一个文件？—— 服务端 scope 重叠检查 + 分支/工作树锁。

• "我测试通过了" 是真的吗？—— 提交必须带完整 Git SHA、真实执行的命令与退出码、由报告者本人上传的 SHA-256 证据，服务端校验，审查者在独立 worktree 复核。

• 没写完能不能换人？—— 每执行者一个未完成 attempt，范围与负责人在阻塞期间保留，重派走新 worktree。

• 人要在什么时候介入？—— 业务问题、工具审批通过结构化 human request 持久化排队，答案带回执，不靠聊天记录。

这些规则全部由服务端在数据库事务内原子校验，不依赖智能体自觉。

Related MCP server: agent-bridge

特性一览

架构

flowchart LR
  subgraph clients["宿主机 · 真实会话"]
    C1["Codex<br/>(MCP + Skill)"]
    C2["Claude Code<br/>(MCP + Skill)"]
    C3["Z Code<br/>(MCP + Skill)"]
  end
  subgraph compose["Docker Compose（仅发布 127.0.0.1:7331）"]
    S["coord-server<br/>Express + MCP SDK<br/>+ Web 看板"]
    M["migrate"]
    PG[("PostgreSQL 18<br/>pg-data 卷")]
    EV[("evidence 卷<br/>/data/artifacts")]
  end
  H["常驻原生宿主<br/>托管 Codex App Server<br/>单次审批"]
  B["浏览器<br/>本机管理员 / 配对操作者"]

  C1 & C2 & C3 -- "HTTP + Bearer API Token" --> S
  B -- "Cookie + CSRF" --> S
  S --- PG
  S --- EV
  M --> PG
  H -- "真实工具调用与审批回写" --> S

代码、Git worktree 与测试命令都在宿主机执行；容器只承载服务与数据。src/ 为 TypeScript 单一构建产物（tsc → dist/）。

快速开始

要求：Docker Desktop（含 Compose）、Node.js ≥ 24、Git。Windows PowerShell 在项目根目录执行：

npm.cmd ci
npm.cmd run build
node dist/cli.js init        # 仅首次：生成随机 DB 密码与操作令牌到 .env（已 gitignore）
docker compose up -d --build --wait
docker compose ps
Invoke-RestMethod http://127.0.0.1:7331/readyz

两个常驻服务：coord-server、postgres；migrate 成功退出即正常。启动顺序：PG 健康 → 迁移完成 → MCP 服务。令牌只存在于本机 .env，不要写进任何源代码。

五分钟看懂全流程：跑一个真实示例

npm.cmd run demo

示例会创建隔离的真实 Git 仓库与开发/测试/集成三个 worktree，由脚本驱动四种角色完成一个加法函数：登记角色 → 领取任务 → 提交真实代码 + node --test 日志 → 监督者审查 diff → 测试者在指定提交的独立 worktree 验收 → 协调者实际合并并在集成提交上复测。结果落盘 test-results/demo-*/result.json。

示例由脚本扮演四种角色，用于验证服务端流程；真实多会话协作见下节。三款工具的 MCP 十客户端并发流程由集成测试覆盖。

接入 Codex / Claude Code / Z Code

node dist/cli.js adapters      # 生成三款工具的 MCP 配置片段（不写入真实令牌）
node dist/cli.js install-skill codex    # 安装通用 Skill 到 ~/.agents/skills
node dist/cli.js install-skill claude   # → ~/.claude/skills
node dist/cli.js install-skill zcode    # → ~/.zcode/skills

启动客户端的同一终端先加载环境：. .\scripts\env.ps1；已运行的桌面应用不会继承后来设置的变量。

之后向各会话发送角色化提示（协调者建项目发 ID → 执行者/监督者/测试者各自加入 → 协调者 session_configure 授角并绑定监督与测试关系 → 逐任务领取、提交、审查、验收、集成）。完整提示词模板与协议细节见 skills/local-coord/references/protocol.md。凭据只返回一次，数据库仅存摘要；只分享会话 ID，不分享 session_token。

任务流与质量约束

ready → running → review → testing → ready_to_integrate → done
          │          │         │
          blocked    └─退回重做─┘
任何非终态任务可暂停；另有 cancelled。同一返工周期两次质量退回后自动暂停。

• 领取检查：依赖已集成、监督绑定、指定负责人、scope 重叠、执行者无未完成批次。

• Scope 是仓库相对目录/文件前缀（非 glob），. 表示整仓；重叠比较按 Windows 场景忽略大小写。

• task_submit 必须提交完整 Git SHA、真实变更文件列表、成功自测命令与本批次证据。

• 证据必须由报告者本人上传，属同一任务与执行批次；内容摘要、提交与需求版本由服务端核对。

• 修改代码走 retry/退回重做，修改目标走 revise（需求版本 +1，旧证据不满足新验收）。

• 审查通过前可 assign_reviewers 交接监督者/测试者（执行者与提交不变）；testing 证据登记后不可交接。

• FROZEN_HANDOFF_PROJECT_IDS 可为指定项目启用冻结交接：已提交待验收的 attempt 不占写入槽，支持流水线式接力。

Web 协同看板

• 项目管理：区分各项目进展，支持两级任务（项目任务拆分为执行任务，父任务由子任务自动完成）。

• 看板泳道：按阶段子分组，卡片带状态徽章、父子任务与阻塞原因。

• 指令与业务确认：预览 → 确认 → 幂等提交，全程操作审计；有效期 5 分钟至 7 天可选；未开始投递的指令可撤回。

• 人工问题：结构化 single_choice / text 业务问题排队等待，答案带接收/应用/结果三段回执。

• 智能体动态：认领确认、系统通知与智能体消息实时展示。

• 原生审批：托管 Codex 的工具许可逐次审批，完整命令与文件差异可见。

• 交付质量检查：一键向当前阶段负责智能体发送预填指令，常驻宿主自动唤醒。

原型看板（dashboard/index.html、confirmation.html）保留演示用途，真实业务从 /dashboard/ 进入；维护源码在 dashboard/live-src/，npm.cmd run dashboard:live:build 构建。

运维

docker compose logs -f coord-server
.\scripts\backup.ps1                      # 原子备份：database.dump + evidence.tar.gz + manifest(SHA-256)
.\scripts\restore.ps1 -Source <备份目录>  # 只允许恢复到空库空证据卷（先用新项目名/端口起一套空服务）
.\scripts\test.ps1                        # 构建 + 单元测试 + 独立 PG(17332) 集成测试，显式 -p local-coord-test

升级执行 up -d --build --wait（迁移按文件序号只执行一次）；保留数据时不要 down -v。默认 180 秒未联系标记 stale、600 秒无进展标记 stalled，服务每 30 秒巡检一次并持久化通知协调者。

仓库结构

src/                  TypeScript 服务端：MCP 工具、核心域、HTTP/UI、执行与工作流服务
migrations/           PostgreSQL 迁移（按序执行一次）
skills/local-coord/   三款工具通用的协作 Skill 与协议参考
scripts/              CLI 周边、看板构建与浏览器回归、备份、longrun 调度与原生会话
host/                 被 scripts/tests 复用的通用执行/内存/工作流模块
dashboard/            Web 看板（live-src 为维护源码，原型页保留演示）
tests/                单元测试 + 集成测试（需 TEST_DATABASE_URL 指向 *_test 库）
examples/             demo.ts 全流程示例、real-sessions.mjs 真实会话控制器
docs/                 设计方案、接口契约与验收文档

配置速查（.env，全部有安全默认值）

诚实的边界（读我）

• MCP 不会自动唤醒已结束回合的聊天：首版需人工继续会话；托管 Codex 宿主支持常驻自动唤醒，其余客户端需手动。

• 会话配额只是本机登记限制，不代表任何供应商的真实模型并发、配额或计费能力。

• 服务校验报告与状态，不提供操作系统级文件隔离，也不把上传日志当作执行环境证明；独立 worktree 与真实命令由宿主工具执行。

• 原生运行时适配器当前固定验证 Codex 0.164.0-alpha.11.1；换版本需先适配协议并复测。

• 协调者凭据丢失暂无管理员重置入口，请自行妥善保存。

• 出于隐私考虑，内部开发过程的 QA 证据归档、现场实测记录与特定部署的运维层未随本仓库发布；发布的文档均为脱敏后的设计与契约。

文档索引

• 方案与契约：一期看板契约 · 原生运行时契约 · 三期任务/证据/历史接口 · 线上策略兼容 · 控制台修复合同

• 阶段方案：二期方案 · 三期方案 · 四期界面优化

• 功能说明：本机管理员入口 · 原生会话启动器 · Longrun 调度 · Longrun 状态 · Longrun 恢复 · 工作流 v1

• 验证记录：真实验收汇总 · 真实原生会话 · 二期集成验收 · 三期集成验收 · 服务恢复 · 本地管理员对抗审查 · 控制台对抗审查 · 导航验收

官方接入参考

Codex MCP · Codex Skills · Claude MCP · Claude Skills · Z Code MCP · Z Code Skills

License

MIT