# 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.

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

## 为什么需要它

单会话 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](docs/LONGRUN.md)） |
| 🗄️ **备份 / 恢复** | 原子备份 PG + 证据卷，manifest 带 SHA-256；恢复只允许空库，校验摘要后导入 |
| 🪟 **Windows 优先** | worktree 支持盘符绝对路径 / 完整 UNC / POSIX 绝对路径，路径规范化有专门测试 |

## 架构

```mermaid
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 在项目根目录执行：

```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`，不要写进任何源代码。**

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

```powershell
npm.cmd run demo
```

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

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

## 接入 Codex / Claude Code / Z Code

```powershell
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`](skills/local-coord/references/protocol.md)。凭据只返回一次，数据库仅存摘要；**只分享会话 ID，不分享 session_token**。

## 任务流与质量约束

```text
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` 构建。

![prototype dashboard](dashboard/preview.png)

## 运维

```powershell
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 秒巡检一次并持久化通知协调者。

## 仓库结构

```text
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 证据归档、现场实测记录与特定部署的运维层未随本仓库发布；发布的文档均为脱敏后的设计与契约。

## 文档索引

- 方案与契约：[一期看板契约](docs/contracts/live-phase1.md) · [原生运行时契约](docs/contracts/phase2-native-runtime.md) · [三期任务/证据/历史接口](docs/contracts/phase3-task-evidence-history.md) · [线上策略兼容](docs/contracts/phase3-live-policy-compatibility.md) · [控制台修复合同](docs/contracts/console-design-fixes.md)
- 阶段方案：[二期方案](docs/PHASE2_SOLUTION_AND_PLAN_2026-10-26.md) · [三期方案](docs/PHASE3_SOLUTION_AND_PLAN_2026-10-31.md) · [四期界面优化](docs/PHASE4_UI_OPTIMIZATION_2026-11-01.md)
- 功能说明：[本机管理员入口](docs/LOCAL_ADMIN_ENTRY_2026-10-27.md) · [原生会话启动器](docs/NATIVE_SESSIONS.md) · [Longrun 调度](docs/LONGRUN.md) · [Longrun 状态](docs/LONGRUN_STATUS.md) · [Longrun 恢复](docs/LONGRUN_RECOVERY.md) · [工作流 v1](docs/WORKFLOW_V1.md)
- 验证记录：[真实验收汇总](docs/VALIDATION.md) · [真实原生会话](docs/REAL_SESSIONS.md) · [二期集成验收](docs/PHASE2_INTEGRATION_ACCEPTANCE_2026-10-26.md) · [三期集成验收](docs/PHASE3_INTEGRATION_ACCEPTANCE_2026-10-31.md) · [服务恢复](docs/PHASE3_SERVICE_RECOVERY_2026-10-31.md) · [本地管理员对抗审查](docs/LOCAL_ADMIN_ADVERSARIAL_REVIEW_2026-10-27.md) · [控制台对抗审查](docs/CONSOLE_DESIGN_ADVERSARIAL_REVIEW_2026-10-29.md) · [导航验收](docs/CONSOLE_NAV_ACCEPTANCE_2026-10-29.md)

## 官方接入参考

[Codex MCP](https://developers.openai.com/codex/mcp/) · [Codex Skills](https://developers.openai.com/codex/skills/) · [Claude MCP](https://code.claude.com/docs/en/mcp) · [Claude Skills](https://code.claude.com/docs/en/skills) · [Z Code MCP](https://zcode.z.ai/cn/docs/mcp-services) · [Z Code Skills](https://zcode.z.ai/en/docs/skill)

## License

[MIT](LICENSE)