Multi-Model Broker — 面向 MCP 的多模型任务代理层

它解决什么

把「用哪个模型、交给本机还是云端、怎么回收结果、怎么留痕」这些决策从客户端里抽出来，收敛到一处。客户端只按统一结构提交任务，Broker 负责路由、并发、幂等、超时与审计；读路径和写路径分开，写盘只能通过明确标注的写工具触发。它不替代任何模型，只在模型之上加一层可验证的调度与隔离。

MCP 双传输

stdio 接入本地 harness；Streamable HTTP（回环 + 共享密钥，可选 SSE 应答）供网络侧客户端使用。

确定性路由

按 requirements + 能力声明选择 worker，链式回退；显式指定 worker 永不被改写，无需 LLM 参与路由。

长任务与并发

waitMs 内阻塞返回；超时返回 taskId 用 get_task 轮询。每 worker 并发上限 + 全局上限。

幂等

idempotencyKey 去重，重复提交只等待不重跑，避免二次计费。

审计 trace

每次委派记录 goal、路由原因、provider/model、时间、工具事件、用量与错误。

读写隔离

只读工具拒绝写型 adapter；写型 worker 只能经唯一的写工具 run_agent 到达（首次必须点名 worker，之后可省略），标注 readOnlyHint: false。

公网可达不开端口

relay 子命令让本机主动外连自建中继（Cloudflare Worker + Durable Object），无需开放入站端口。

选定即记住，切换只一步

点名的 worker / model 成为该工具的默认，后续调用可省略；换一个就切换。list_workers 用 defaultFor 标出当前选择，trace 记下 choice.remembered。

本地 agent 接入

codex-sdk 与 claude-code 两种 adapter；claude-code 的后端与模型由使用者自行配置（任意 Anthropic 兼容端点），本仓库不预置默认模型。

快速开始

依赖 Node.js ≥ 22.5（使用内置 node:sqlite，无需原生模块与构建工具链）。

安装与自检

npm ci
npm run check && npm test && npm run build
node dist/cli/index.js doctor

本地 stdio 接入

node dist/cli/index.js mcp-stdio \
  --profile local-full

回环 HTTP 接入

node dist/cli/index.js mcp-http \
  --profile chatgpt-agent \
  --token-env BROKER_HTTP_TOKEN \
  --port 8789

用自己的环境跑起来

至少一个 API worker：cp .env.example .env，填入一个 *_API_KEY（DeepSeek / GLM / Gemini），在 config/providers.yaml 里启用它；只想先看看就用 config/providers.mock.yaml（纯假实现、零成本）。
可选：本地写型 agent：codex 用本机已有 Codex 登录（broker 不读也不复制凭据）；claude-code 需要 Anthropic 兼容端点与令牌 —— 直接 export ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN，或写进文件由 options.envScript 或 $CLAUDE_ENV_SCRIPT 指向（默认 ~/.config/multimodel-broker/claude-code.env，密钥从不进命令行）。
可选：公网接入：relay setup 引导部署自建中继，本机主动外连、不开入站端口。

不假设任何目录布局，也不内置任何凭据；doctor 会逐个报告还缺什么，但从不打印密钥。

工具

MCP 面共 9 个注册工具，两个 profile 各暴露 8 个（差别只在 run_agent 与 cancel_task）；只读与写型分开标注。

工具	类型	说明
ping	只读	Broker 健康探测
list_workers	只读	列出已配置 worker 及其能力与健康状态
run_worker	只读	路由到某个只读 worker 执行，拒绝写型 adapter
run_agent	写型	驱动本机 agent（worker=codex / codex-win / claude-code，首次必须点名、之后可省略），readOnlyHint: false · destructiveHint: true
delegate	只读	单任务委派，拒绝写型 adapter
delegate_batch	只读	一次最多 8 个任务并行，部分失败也保留结果
get_task	只读	按 taskId 轮询长任务结果
get_trace	只读	读取某次委派的审计 trace
cancel_task	只读	取消排队/运行中的任务（本地运维工具，默认不下发给远程客户端）

安全基线

写盘与出网默认收紧，需要本地显式开启。

密钥不进 argv — 只从环境 / .env 读取，不进配置文件；临时文件 0600、用完即删。
prompt 默认不落库 — storePrompts 默认 false，不持久化 prompt 原文。
输出脱敏 — 密钥 / token 形状的字符串一律替换后再入 trace。
写型工具独立标注 — readOnlyHint: false · destructiveHint: true，绝不混入只读工具。
绝不自动重放 — 中继断线返回 outcome_unknown，由上层 idempotencyKey 决定是否恢复。
读/写凭据分离 — 写型 worker 只能经 run_agent 到达，只读工具拒绝写型 adapter。