# orchestrator-mcp

面向主 Agent 的多模型 **Review Hub MCP**：按角色提供 UI 审查、代码审查、通用审查能力，返回可追踪的结构化审查结果。

它不是软件交付流水线，也不负责 plan → code → deliver。它不会实现修复、修改工作区、提交 commit、push 或创建 PR；最终如何处理审查结果，由调用它的主 Agent 决定。

调用方必须提供本次审查的目标和真实证据。MCP 负责把请求路由给一个配置好的 review 角色，保存本次 run 的 handoff，并将结果交还给主 Agent。Review verdict 只是审查意见，不会自动成为其他任务的事实依据。

- **Review handoff schema 固定**（`schemas/`）
- **Provider 按厂商**（deepseek / moonshot / zhipu / openai / codex-lb），**model 按 role 配置**
- **别名**：`glm` → zhipu，`gpt` → openai
- **凭证**：环境变量 → WebUI 本地 JSON → `~/Desktop/服务器.md`
- **Web 配置界面**：编辑 Provider Key / Base URL / 默认模型，以及各 Profile 的 Role 模型

---

## 给 AI Agent 的安装指令

> 若你是 Cursor / Codex 等 AI Agent，帮用户安装 orchestrator-mcp 时，**按顺序执行以下命令**，不要跳过检测步骤。

```bash
# 1. 进入仓库（clone 后或用户已有目录）
cd /path/to/orchestrator-mcp

# 2. 一键安装（创建 venv、装依赖、离线自测、生成 Cursor 配置）
./install.sh

# 3. 确认依赖与健康状态（必须 exit 0）
./install.sh --check-only
./scripts/orchestrator-doctor.sh

# 4. 可选：跑单元测试
PYTHONPATH=src .venv/bin/python -m unittest discover -s tests
```

**安装成功标志：**

- `./install.sh` 末尾输出 `PASS (self-test)`
- `./install.sh --check-only` 输出 `"ok": true`
- `./scripts/orchestrator-doctor.sh` 输出 `"ok": true`
- Cursor 中 **Settings → Tools & MCP** 出现 `orchestrator-mcp` 且为绿点

**安装后告诉用户：**

1. 在 Cursor 打开本仓库（或把 `.cursor/mcp.json.example` 路径改成实际 clone 目录）
2. 配置 API Key：环境变量（见「凭证环境变量」）或 `./start-webui.sh` 打开 WebUI
3. MCP 工具以 `orchestrate_*` 开头；先 `orchestrate_run_start`，再 `orchestrate_dispatch`

**macOS + Codex 额外步骤：**

```bash
./install.sh --launchd
./scripts/orchestrator-doctor.sh
# 新建 Codex 任务或重启 Codex App
```

---

## 安装与使用指南

### 前置要求

| 依赖 | 版本/说明 |
|------|-----------|
| Python | **3.10+**（推荐 3.11 / 3.12） |
| git | 必需 |
| lsof | 可选，用于端口检测与 doctor |
| macOS launchctl | 仅 `--launchd` 时需要 |

Python 包（由 `install.sh` 自动安装，见 `requirements.txt`）：

- `mcp>=1.9.0`
- `PyYAML>=6.0.1`
- `fastapi>=0.115.0`
- `uvicorn[standard]>=0.32.0`

### 一键安装（推荐）

```bash
git clone <repo-url> orchestrator-mcp
cd orchestrator-mcp
./install.sh
```

`./install.sh` 会自动完成：

1. 检测系统命令（`git`）
2. 调用 `ensure-venv.sh` 创建 `.venv` 并 `pip install -r requirements.txt`
3. 调用 `scripts/check_deps.py` 校验 Python 包与仓库文件
4. 赋予启动脚本可执行权限
5. 生成本地 `.cursor/mcp.json`（含本机绝对路径，**不进 git**）
6. 运行离线自测 `orchestrator_mcp.self_test`

### 脚本速查

| 脚本 | 用途 | 典型场景 |
|------|------|----------|
| **`./install.sh`** | 一键安装入口 | 首次 clone、换机器、依赖变更后 |
| `./install.sh --check-only` | 仅检测依赖，不改环境 | 排查「装好了吗」 |
| `./install.sh --skip-verify` | 安装但跳过自测 | 快速重建 venv |
| `./install.sh --codex` | 额外写 `~/.codex/config.toml` | macOS Codex 用户 |
| `./install.sh --launchd` | Codex + launchd 后台 HTTP 服务 | macOS 长期运行 |
| `./ensure-venv.sh` | 只创建/更新 venv | 被其他脚本调用，也可单独跑 |
| `./verify.sh` | venv + 离线自测 | CI / 手动验收 |
| `./start.sh` | 启动 MCP HTTP 服务 `:18067` | URL 模式客户端 |
| `./start-webui.sh` | 启动配置 WebUI `:18068` | 图形化配 Key / Model |
| `./codex-stdio-wrapper.sh` | Codex stdio 启动包装 | 由 Codex 自动调用 |
| `./scripts/check_deps.py` | JSON 格式依赖报告 | 被 install.sh 调用 |
| `./scripts/orchestrator-doctor.sh` | 健康检查（配置/端口/进程） | 安装后验收、排错 |
| `./scripts/install-local.sh` | macOS Codex + launchd 安装 | `--codex-only` 或 `--launchd` |

### 安装后验证

```bash
# 依赖是否齐全（应输出 "ok": true）
./install.sh --check-only

# 健康检查（应输出 "ok": true）
./scripts/orchestrator-doctor.sh

# 离线功能自测
./verify.sh

# 单元测试（35 项）
PYTHONPATH=src .venv/bin/python -m unittest discover -s tests -v

# 可选：真实 LLM 调用冒烟（需要已配置 API Key）
ORCHESTRATOR_LIVE_TEST=1 ./verify.sh
```

### 使用场景

#### 场景 A：Cursor（stdio，推荐）

无需手动 `./start.sh`，Cursor 会自动拉起 MCP 进程。

```bash
./install.sh                                    # 生成本仓库 .cursor/mcp.json
# Cursor → 打开本仓库 → Settings → Tools & MCP → 启用 orchestrator-mcp
```

若要在**其他项目**使用，复制模板并改路径：

```bash
cp .cursor/mcp.json.example /your-project/.cursor/mcp.json
# 编辑 mcp.json，把 /ABSOLUTE/PATH/TO/orchestrator-mcp 改成实际路径
```

#### 场景 B：HTTP 模式（任意 MCP Client）

```bash
./install.sh
./start.sh
# MCP 地址：http://127.0.0.1:18067/mcp
# 终端需保持运行；或使用 --launchd 后台运行
```

#### 场景 C：WebUI 配置 Provider

```bash
./install.sh
./start-webui.sh
# 浏览器打开 http://127.0.0.1:18068
# 配置写入 data/providers.local.json、data/roles.local.json（不进 git）
```

#### 场景 D：macOS Codex + 后台服务

```bash
./install.sh --launchd
./scripts/orchestrator-doctor.sh
# 新建 Codex 任务或重启 Codex App（已有任务不会热加载 MCP）
```

### 故障排查

| 现象 | 处理 |
|------|------|
| `missing .venv/bin/python` | 运行 `./ensure-venv.sh` 或 `./install.sh` |
| `Python x.x is below required 3.10` | 安装 Python 3.10+，macOS 可用 `brew install python@3.12` |
| `package import failed: mcp` | `./install.sh` 重建 venv；确认网络可访问 PyPI |
| `port 18067 already in use` | 已有 MCP 在跑；kill 旧进程或改 `ORCHESTRATOR_MCP_PORT` |
| Cursor 看不到 MCP 工具 | 确认 `.cursor/mcp.json` 路径正确 → Refresh → 重启 Cursor |
| Codex 看不到 MCP 工具 | 运行 `./scripts/install-local.sh --codex-only`，**新建任务** |
| `ModuleNotFoundError: orchestrator_mcp` | 客户端 env 缺少 `PYTHONPATH=<repo>/src` |
| review 返回无 key / 401 | 配置 `DEEPSEEK_API_KEY` 等环境变量，或 WebUI 填写 Provider |
| doctor `"ok": false` | 看 JSON 里 `checks` / `plists` / `listeners` 哪项不匹配 |

**重新安装（干净重建 venv）：**

```bash
rm -rf .venv
./install.sh
```

---

## 快速开始

```bash
cd orchestrator-mcp
./install.sh               # 首次安装（推荐）
./start.sh                 # 可选：HTTP MCP :18067
./start-webui.sh           # 可选：配置 WebUI :18068
```

## 本机可靠部署（Codex + launchd，macOS）

```bash
cd orchestrator-mcp
./install.sh --launchd     # venv + Codex stdio 配置 + launchd HTTP MCP/WebUI
./scripts/orchestrator-doctor.sh
```

也可分步：

```bash
./install.sh               # 基础安装
./scripts/install-local.sh --codex-only   # 仅写 ~/.codex/config.toml
./scripts/install-local.sh --launchd      # 含 launchd 后台服务
```

安装器会：

- 修复/准备可迁移 venv，并始终通过 `python -m pip` 安装依赖；
- 将 Codex 配置为 per-session stdio；若客户端转发 `CODEX_THREAD_ID` 就按线程隔离，否则 wrapper 使用进程级 session id，避免因客户端未转发该变量而无法启动；
- 将 launchd HTTP MCP 固定到 18067，WebUI 固定到 18068；
- 备份现有 Codex 配置和 launchd plist；
- 等待 launchd job 完成卸载、重新加载并真正开始监听后才返回成功。

`doctor` 同时检查配置路径、transport、plist、监听数量和进程 cwd。安装后需要新建
Codex 任务或重启 Codex/ChatGPT App，已有任务不会热注册新的 MCP 工具。

评审调用必须提供真实可审查证据。`code_review` 在传入 `workspace` 时会按 `diff_scope`
（默认 `branch_changes`）自动注入 **unified diff**；也可在 `extra_context` 中直接附 patch/代码。
无 diff/代码证据时 `code_review` 会返回 `verdict=evidence_insufficient`，不会假审。
可选结构化字段：`requirements` / `verification` / `known_risks` / `custom_instructions` /
`base_sha` / `head_sha`（`diff_scope=sha_range` 时）。
handoff 为 `review.v1`：`verdict` + `findings[{severity,location,what,why,fix}]` + `blocking` + `suggestions`。
一致性：`pass` 不得含 Critical/Important；`revise` 至少一条 Critical/Important finding。
模型 JSON 不合 schema 时自动重试修复一轮。自动 diff 会排除 lockfile / 二进制 / `node_modules` 等噪音路径。
主 Agent 调用约定见仓库 `.cursor/skills/orchestrator-code-review/SKILL.md`。

## 主 Agent 与 Review Hub 的交接

推荐交接内容是一个明确的 review request：目标、变更文件、diff 或代码范围、证据、已执行验证和已知风险。Review Hub 将同一份请求上下文交给对应角色，并返回独立的 review handoff；不要依赖隐藏聊天记录补全审查范围。

基本关系如下：

```text
主 Agent -- review request + evidence --> Review Hub
Review Hub -- 同一请求上下文 + 角色规则 --> UI / Code / General Reviewer
Reviewer -- structured findings + blockers + evidence --> Review Hub
Review Hub -- independent handoffs --> 主 Agent
```

## 启动入口

| 入口 | 命令 | 地址 | 说明 |
|------|------|------|------|
| MCP（HTTP） | `./start.sh` | `http://127.0.0.1:18067/mcp` | 需保持进程；或用 `--launchd` 后台 |
| MCP（stdio） | Cursor / Codex 自动拉起 | — | 推荐；运行 `./install.sh` 即可 |
| WebUI | `./start-webui.sh` | `http://127.0.0.1:18068` | 配置 Provider / Role |

安装与排错详见上方 **[安装与使用指南](#安装与使用指南)**。

说明：

- WebUI 不是 MCP tool，本身不会出现在工具列表里
- WebUI 只是本地配置界面；真正暴露给 MCP Client 的是 `orchestrate_*` 这些工具
- 默认端口可通过 `ORCHESTRATOR_WEBUI_HOST`、`ORCHESTRATOR_WEBUI_PORT`、`ORCHESTRATOR_MCP_HOST`、`ORCHESTRATOR_MCP_PORT` 覆盖

## Web 配置界面

| 功能 | 说明 |
|------|------|
| Providers | 编辑 `api_key`、`base_url`、`default_model`；写入 `data/providers.local.json` |
| Roles | 按 Profile 覆盖 `ui_review` / `code_review` / `general_review` 的 provider + model；写入 `data/roles.local.json` |

本地配置文件**不进 git**。环境变量仍优先于 WebUI 写入的值。

## 安全说明

- `data/providers.local.json`、`data/roles.local.json` 等 WebUI 写入的本地配置文件**包含明文 API key**。每次写入后会自动 `chmod 600`（仅文件属主可读写），请勿手动放宽权限或把这些文件提交到 git。
- WebUI 默认监听 `127.0.0.1:18068`，仅在本地访问。如需把 WebUI 暴露到非本机网络，务必设置环境变量 `ORCHESTRATOR_WEBUI_TOKEN` 加锁：设置后所有请求必须携带该 token，否则返回 401。未设置时不强制认证，保持向后兼容。
- 访问 token 的传递方式：HTTP 头 `Authorization: Bearer <token>`，或查询参数 `?token=<token>`。
- 环境变量注入的密钥（`*_API_KEY`）不会落盘，优先级高于本地 JSON；能用环境变量时优先用环境变量。

## Profile

| Profile | 用途 |
|---------|------|
| `daily-dev-stub` | 离线三角色审查自测，不调 API |
| `daily-dev` | 日常三角色审查 |
| `example-kimi-review` | 多模型审查示例，不同角色用不同模型 |

同一厂商下切换模型：只改 YAML 或 WebUI Roles 里的 `model`，**不用**建两个 provider。

```yaml
roles:
  ui_review:
    provider: codex-lb
    model: gpt-5.4
  code_review:
    provider: codex-lb
    model: gpt-5.4
  general_review:
    provider: deepseek
    model: deepseek-v4-flash
```

## 凭证环境变量

| Provider | Env | 默认 Base URL |
|----------|-----|---------------|
| deepseek | `DEEPSEEK_API_KEY` | https://api.deepseek.com/v1 |
| moonshot | `MOONSHOT_API_KEY` | https://api.moonshot.cn/v1 |
| zhipu/glm | `ZHIPU_API_KEY` | https://open.bigmodel.cn/api/paas/v4 |
| openai/gpt | `OPENAI_API_KEY` | https://api.openai.com/v1 · `wire_api=chat` |
| codex-lb/codex | `CODEX_LB_API_KEY` | https://codex-lb.vvicat.dev/backend-api/codex · `wire_api=responses` |

### Codex 中转（Responses API）

与 Codex CLI 配置对应关系：

```toml
model = "gpt-5.4"
model_reasoning_effort = "medium"
model_provider = "codex-lb"
env_key = "CODEX_LB_API_KEY"

[model_providers.codex-lb]
base_url = "https://codex-lb.vvicat.dev/backend-api/codex"
wire_api = "responses"
```

在 WebUI **Providers → Codex 中转** 填写：

| 字段 | 值 |
|------|-----|
| API 密钥 | 同 `CODEX_LB_API_KEY` |
| Base URL | `https://codex-lb.vvicat.dev/backend-api/codex`（不要写成 `/code`） |
| 默认模型 | `gpt-5.4` |
| Wire API | `responses` |
| Reasoning Effort | `medium` |

Role 里可把 `ui_review` / `code_review` 的 provider 选 **codex-lb**（或别名 **codex**），model 填 `gpt-5.4`。

**注意**：`/chat/completions` 在该中转上返回 405；必须用 Responses 协议。

可选覆盖：`CODEX_LB_BASE_URL`、`DEEPSEEK_BASE_URL`、`MOONSHOT_BASE_URL`、`ZHIPU_BASE_URL`、`OPENAI_BASE_URL`

`服务器.md` 标签（下一行或同行）：`deepseekApiKey`、`moonshotApiKey`、`zhipuApiKey`、`openaiApiKey`

## Workspace 项目上下文（与 IDE 共用源文件）

MCP **不单独维护**记忆文件。传入 `workspace`（或设置 `ORCHESTRATOR_WORKSPACE`）后，每个 role **直接从磁盘读取**与 Cursor/Codex 相同的源文件并注入 prompt：

| 路径 | 说明 |
|------|------|
| `AGENTS.md` / `CLAUDE.md` / `agent.md` | 项目级 agent 说明 |
| `.cursor/rules/*` | Cursor 规则 |
| `.learnings/*.md` | self-improving 沉淀 |
| profile `skills:` | 加载对应 `SKILL.md` 全文 |
| git | branch、dirty files、diff --stat |

- `orchestrate_run_start`：`role`、`workspace`、`extra_context`（仅本次 run）
- `orchestrate_workspace_context`：预览将读取哪些文件

## MCP 工具

| 工具 | 说明 |
|------|------|
| `orchestrate_list_providers` | 各 provider 是否已配置 key |
| `orchestrate_provider_check` | 检查单个 provider |
| `orchestrate_effective_config` | 不调用模型，查看 MCP 当前实际会用的 profile / role / provider / model |
| `orchestrate_workspace_context` | 预览 workspace 项目上下文 |
| `orchestrate_run_start` | 创建一个只绑定单个 Review 角色的审查 run（支持 `workspace`） |
| `orchestrate_dispatch` | 执行 run 创建时绑定的唯一 Review 角色 |
| `orchestrate_status` / `orchestrate_handoff` | 查询单角色审查状态和 handoff |
| `orchestrate_role_override` | 运行时更换当前 run 角色的 provider/model |

### Provider 选择规则

- Providers 页只表示“这个厂商已配置 key / base_url / 默认模型”。
- 真正决定 MCP 执行使用哪个 provider 的是 Roles 页；保存后写入 `data/roles.local.json`。
- 调用前可先跑 `orchestrate_effective_config(role="ui_review")`，确认有效配置，避免误跑到 YAML 默认值。
- 先调用 `orchestrate_run_start(goal="...", role="ui_review")` 创建单角色 run，再调用 `orchestrate_dispatch(run_id)` 执行该角色。
- 每个 run 只能绑定一个 Review 角色；MCP 不提供串联或并联多个 Review 角色的入口。
- `role_overrides_json` 支持短写：`{"provider":"codex-lb","model":"gpt-5.4"}` 或 `{"code_review":{"model":"codex/gpt-5.4"}}`。
- 兼容旧入参：`review` 会映射到 `general_review`。

## Cursor 配置

> 完整安装流程见 **[安装与使用指南 → 场景 A](#场景-a-cursorstdio推荐)**。

运行 `./install.sh` 会在本仓库生成 **`.cursor/mcp.json`**（已 gitignore，含本机绝对路径）。

也可参考 **`.cursor/mcp.json.example`**，把路径改成你的 clone 目录后放到**任意项目**根目录。

1. 用 Cursor 打开目标仓库根目录  
2. **Settings → Tools & MCP**，确认 **orchestrator-mcp** 已启用（绿点）  
3. 若没有，点 **Refresh** 或重启 Cursor  

若仍看不到：Settings → MCP → **Edit Config**，确认项目级 `.cursor/mcp.json` 已加载。

验收：`./scripts/orchestrator-doctor.sh` 应返回 `"ok": true`。

**方式 A（推荐，已写入项目）**：Cursor 自动拉起进程

```json
{
  "mcpServers": {
    "orchestrator-mcp": {
      "command": ".../orchestrator-mcp/.venv/bin/python",
      "args": ["-m", "orchestrator_mcp"],
      "env": {
        "PYTHONPATH": ".../orchestrator-mcp/src",
        "ORCHESTRATOR_MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

**方式 B**：先 `./start.sh`，再用 URL（需保持终端进程运行）

```json
{
  "mcpServers": {
    "orchestrator-mcp": {
      "url": "http://127.0.0.1:18067/mcp"
    }
  }
}
```