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 持久化排队，答案带回执，不靠聊天记录。

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

特性一览

能力	说明
🧩 MCP 原生协议	基于 `@modelcontextprotocol/sdk`，CLI 与 MCP 调用同一业务实现；十客户端并发流程有集成测试覆盖
👥 四角色治理	协调者 / 执行者 / 监督者 / 测试者；新会话默认执行者，由协调者 `session_configure` 授角并绑定监督关系
🔒 并发安全	scope 前缀重叠检查、分支与 worktree 独占、依赖完成检查、Z Code 本地会话配额（1–15，跨项目原子统计）
🧾 证据链	自测 / 审查 / 测试 / 集成四类质量记录；artifact 带 SHA-256 摘要与字节数校验；提交与需求版本必须匹配
📊 Web 协同看板	`http://127.0.0.1:7331/dashboard/`：项目/任务/会话/事件/证据全览，两级任务（项目任务→执行任务），指令与业务问题的人工确认流
🔐 本机管理员入口	Compose 默认启用：本机来源免连接码直进；受限操作走 5 分钟一次性配对码 + CSRF 会话（最长 8 小时）
🤖 托管原生运行时	常驻宿主自动发现指令并唤醒托管 Codex App Server；工具许可在看板单次审批（原协议允许/拒绝/取消），命令与文件差异完整展示
💬 持久化消息与指令	`inbox_read` 独立游标分页；指令消费跟随 `next_cursor`；人工答案不自动恢复暂停的任务
🧠 Longrun 六角色调度	bootstrap、任务树、阶段调度、进展检查点、快照与阶段关闭（见 docs/LONGRUN.md）
🗄️ 备份 / 恢复	原子备份 PG + 证据卷，manifest 带 SHA-256；恢复只允许空库，校验摘要后导入
🪟 Windows 优先	worktree 支持盘符绝对路径 / 完整 UNC / POSIX 绝对路径，路径规范化有专门测试

架构

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

工具	配置片段	使用方式
Codex	`codex.toml`	合并到用户配置或受信任项目的 `.codex/config.toml`（`bearer_token_env_var`）
Claude Code	`claude.json`	合并到项目 `.mcp.json`（`${COORD_API_TOKEN}` 环境变量展开）
Z Code 桌面端	`zcode.json`	设置 → MCP → 新建；把请求头占位符替换为 `.env` 中的令牌
Z Code CLI	`zcode-cli.json`	合并到 `~/.zcode/cli/config.json` 的 `mcp.servers`

启动客户端的同一终端先加载环境：. .\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，全部有安全默认值）

变量	默认	说明
`COORD_PORT`	`7331`	仅发布到 127.0.0.1
`POSTGRES_PASSWORD` / `COORD_API_TOKEN`	`init` 随机生成	存于 `.env`，绝不入库
`ZCODE_MAX_SESSIONS`	`15`	Z Code 本地登记上限（1–15，跨项目原子统计；非供应商并发测量）
`CODEX_MAX_SESSIONS` / `CLAUDE_MAX_SESSIONS`	`0`	0 = 未配置本地上限；供应商并发未验证
`FROZEN_HANDOFF_PROJECT_IDS`	空	逗号分隔项目 UUID，启用冻结交接
`STALE_AFTER_SECONDS` / `STALLED_AFTER_SECONDS`	`180` / `600`	失联 / 停滞阈值
`COORD_UI_LOCAL_ADMIN*`	见 `.env.example`	本机管理员入口的来源与可信 peer 白名单

诚实的边界（读我）

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

Name		Name	Last commit message	Last commit date
dashboard		dashboard
docs		docs
examples		examples
host		host
migrations		migrations
scripts		scripts
skills/local-coord		skills/local-coord
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
compose.test.yaml		compose.test.yaml
compose.yaml		compose.yaml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Navigation Menu

Repository navigation

About

Repository files navigation

local-coord

为什么需要它

特性一览

架构

快速开始

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

接入 Codex / Claude Code / Z Code

任务流与质量约束

Web 协同看板

运维

仓库结构

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

诚实的边界（读我）

文档索引

官方接入参考

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

local-coord

为什么需要它

特性一览

架构

快速开始

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

接入 Codex / Claude Code / Z Code

任务流与质量约束

Web 协同看板

运维

仓库结构

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

诚实的边界（读我）

文档索引

官方接入参考

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages