feat(model-proxy): 提供基于 CLI 的模型代理模式与标准调用入口

[xiongz-c]

背景 / 动机

本次迭代的出发点是增强 Bot 的业务能力。Botmux 当前主要通过桥接 Coding CLI，让 Bot 提供编程助手能力；面向实际业务，Bot 还需要组合代码评审、监控排查等多种专业能力，逐步成为能够承担不同任务的复合型数字员工。

这些能力的提供方式各不相同：有些可以直接调用一个 CLI，有些则由完整的 Agent 框架提供。后者已经负责上下文管理、业务工具、权限和任务编排，能够自行完成“请求模型、执行工具、回填结果、继续处理”的多轮流程，接入时只需要模型能力。要让 Bot 复用这类框架，需要为它们提供模型调用入口，并保留框架自身的工具执行与流程控制。

为此，Botmux 增加模型透明代理模式（Model Proxy Mode），复用所适配 CLI 的模型调用能力与原生认证，将模型结果或工具调用建议返回给外部框架，由框架执行业务工具并决定后续步骤。同时，由 Botmux 提供统一的模型接入协议，首版支持非流式 Chat Completions 协议子集，使外部应用可通过模型 SDK 配置 endpoint、访问凭据和模型别名接入，无需为每种能力分别维护私有推理适配。这为 Bot 组合更多专业能力提供了公共接入基础。

使用场景与调用链

以下两个例子说明为什么外部应用需要保留自己的工具和任务流程，只把模型请求交给 Botmux：

1. OpenCodeReview（OCR） 代码评审：它已有评审流程和读取代码等工具，可通过模型 SDK 将评审上下文与工具定义发给 Botmux。模型返回读取文件等工具调用建议后，由 OCR 执行工具、回填结果并继续评审。这样可以复用 CLI 的模型调用能力，同时保留 OCR 的评审逻辑。本次已验证合成仓库中的 OCR + Claude 调用链；具体覆盖范围见下方“本次验证”，不代表真实模型评审质量验收。
2. 监控与故障排查系统：系统已有监控查询、日志检索工具及相应权限控制，可通过模型 SDK 将告警上下文交给 Botmux。模型建议“查询最近十分钟错误日志”后，由系统校验权限、执行查询并回填结果，再决定是否继续排查或进入审批流程。这样可以复用 CLI 的模型调用能力，同时保留原系统的工具、权限和任务状态。此例用于说明接入场景，本次未进行该类应用的集成验收。

外部应用（如 OCR、监控与故障排查系统）→ 模型 SDK → Botmux 公共 Chat Completions 适配 → 既有签名 IPC 和受约束执行层 → CLI 原生模型调用。 公共适配层负责消息和工具协议翻译；执行层负责鉴权、deadline、幂等、并发、结果记录与进程回收；CLI 保留原生认证和模型传输路径。工具调用建议沿原路径返回外部应用，由外部应用执行业务工具并回填结果；Botmux 和被调用 CLI 不执行外部业务工具。

实现与分组

实现基础：复用 CLI 已有的模型调用与工具控制能力。 Claude Code 可组合原生 print/stream-json 与空 tools；Codex 通过 app-server，组合执行环境、工具配置和临时模型目录来关闭工具。各 CLI 的接口与约束不同，需要分别适配和验证。

• 公共协议入口：新增 botmux model-proxy serve --config，固定监听 127.0.0.1，要求 Bearer 访问凭据。服务端把客户端权限和模型别名映射到专用 Bot、原生模型及 deadline；客户端不能指定身份目录、原生程序或上游 endpoint。
• 请求与响应翻译：支持非流式 Chat Completions 的文本消息、function tools、tool_choice、工具调用 ID、多轮工具结果、JSON 输出校验及稳定错误结构。保留原始参数 schema 的可选字段和开放对象含义；不支持的关键字和参数明确拒绝。
• 执行资源管理：通过已有签名 IPC 接入本 PR 新增的 InvocationService，统一处理持久幂等、断连取消、deadline、并发与进程回收，避免重复推理。一个重复等待者断连不会取消同一代理进程内其他等待者。
• Codex 原生协议组：Codex / Codex App 使用隔离 app-server 和临时线程，关闭宿主工具；不连接既有服务或实例池。
• Claude 原生协议组：空 tools、safe-mode、print/stream-json；内部 StructuredOutput 仅用于 JSON 序列化。并传递原生生成上限。
• 原生非交互与策略组：Pi / MiniMax 使用原生非交互协议；Gemini / OpenCode 使用原生策略控制。执行层共接通 7 个 CLI 标识；通过模型 SDK 的公共入口纵向验收覆盖 Codex 和 Claude。

兼容范围与部署条件

项目	本版行为 / 验证边界
公共接口	GET /v1/models、非流式 POST /v1/chat/completions；未知参数明确报错
消息与工具语义	统一序列化为 CLI 输入，再从结构化结果恢复响应；保留角色顺序与调用关联，不承诺与直接模型 API 的推理语义完全等价
输出上限	Claude 将 max_completion_tokens 传入原生生成设置，已验证 1、4096、16384；作用于原生生成请求，包含序列化开销，不是整次 CLI 调用的总费用上限。其他 CLI 明确拒绝
用量	标准 usage:null；扩展字段保留原生真实计数、来源与整次调用范围，未知值为 null，不估算或伪造单次 API 账单
身份	首版要求专用 core-only apiOnly Bot 和独立原生身份；不自动复制聊天 Bot、全局或其他 Bot 凭据
OCR + Codex	尚未打通：OCR 发布版携带输出上限参数，当前 Codex 路径没有已验证的对应生成控制
新入口的真实订阅验收	尚未完成：本次没有已核验、获准使用的专用登录；此前执行层订阅测试不等于本入口验收

完整配置、模型 SDK 调用方式与 OCR 应用接入示例、schema 子集、取消与幂等语义见公共模型协议说明；底层契约见受约束推理执行层。

CLI 适配状态

状态	CLI	验证范围 / 后续安排
已适配（7 项）	claude-code、codex、codex-app、gemini、opencode、pi、minimax	原生协议与隔离约束的验证见下方测试记录；Codex App 复用 Codex 原生通道，并通过独立 IPC 路由测试。Codex 执行层已完成 Linux 真实订阅验证；其他 CLI 的真实账号及新公共入口的真实订阅验收仍待完成。
暂未适配（24 项）	seed、relay、aiden、coco、cursor、genius、opencode2、antigravity、mtr、hermes、mira、mir、traex、copilot、oh-my-pi、ebsd、kimi、grok、kiro-cli、riff、reasonix、dsh、dsh-tui、mojo	本机暂无可用于该模式验收的完整测试环境，后续按需迭代适配。

本次验证

• bun run test -- --configLoader runner test/model-proxy.test.ts test/model-proxy-ipc.test.ts test/constrained-invocation.test.ts test/ipc-constrained-invocation.test.ts test/model-only-print.test.ts test/capabilities.test.ts test/session-command.test.ts test/headless-command.test.ts test/codex-rpc-engine.test.ts test/claude-code-cwd.test.ts test/bot-registry.test.ts：274 项通过。
• bun x vitest run --configLoader runner --project e2e test/constrained-codex.e2e.ts test/model-only-claude.e2e.ts test/model-only-print.e2e.ts test/model-only-gemini.e2e.ts test/model-only-opencode.e2e.ts test/model-proxy.e2e.ts（按文档设置原生 CLI、SDK 和 OCR 路径）：34 项通过，包含 Claude 的 1 / 4096 / 16384 预算边界。
• 原生验证样本：Codex 0.153.4、Claude Code 2.1.268、Pi 0.85.1、MiniMax CLI 1.0.25、Gemini CLI 0.60.0、OpenCode 1.18.31。旧 Gemini 0.1.18 缺少所需接口，调用失败；OpenCode 测试环境的 npm 入口未完成 postinstall，使用包内原生平台二进制后通过。版本是验证样本，不是兼容白名单。
• OpenAI JavaScript SDK 6.32.0 使用同一公共入口，在真实 Codex / Claude CLI 配合无凭证合成 provider 下完成文本与工具往返。客户端提交原始 messages/tools，验证 ID 关联、结果回填及原生宿主工具关闭。
• 未修改 OCR v1.12.3 发布源码的 macOS 构建版，经公共入口与真实 Claude CLI 完成合成仓库原生 review：规划阶段执行，文件工具结果回填，selected/completed 为 1/1，工具失败为 0，失败/豁免项为空。此次没有候选评论，未覆盖候选复核阶段，也不证明真实模型评审质量。
• 公共请求断连后真实原生进程退出；回归覆盖强制宿主工具调用拒绝、父进程退出回收、鉴权、非法参数/schema、deadline、并发隔离、重复请求与冲突、未知用量和原生用量映射。
• bun run build、git diff --check 通过；编译后 model-proxy --help 可用；Bun 1.4.2 构建模块的实际 HTTP 请求 smoke 通过。

影响范围与后续验收

新增前台公共协议服务，复用 Bot admission、签名 IPC 和执行层；普通 PTY/tmux/IM 会话保持原路径，本次已回归普通 Codex RPC、Claude、headless/session 命令与 Bot 注册。未新增依赖或修改版本号。新公共入口本次在 macOS 验证，Linux 尚未做本轮端到端验收。

剩余验收包括专用身份的真实订阅调用、OCR + Codex 的输出上限兼容，以及领域集成中的完整 MR 对比与生产切换。本次未合并、未发版、未重启既有生产服务、未发送 IM 或 MR 评论。

[github-actions]

🚀 Released in v3.26.0