跳转至

AI Runtime 模型调用适配层

版本：v1.3.0

更新：2026-08-18

状态：薄 Runtime 边界继续生效；阶段四至阶段八均已完成并归档；当前阶段 P9（阶段九）“后续阶段待规划”，等待新需求

一、定位

AI Runtime 是业务模型策略、任务快照和调用事件边界，不是 Provider 网关的第二实现。官方 OmniRoute 是 Provider、连接凭据、模型目录、协议转换、Combo、健康、冷却、额度、回退和调用日志的唯一权威。CLI Agent Gateway 的外部单模型通道 URL/Key 只在 Gateway 加密存储；Runtime 仅代理不含密钥的目录与固定调用 ID，不取得通用 Provider 权威。

二、当前调用架构

flowchart TD
    A[AI Boss 或逻辑 Worker] --> B[RuntimeModelGateway]
    B --> C[冻结 OmniRoute 模型策略]
    C --> D[OmniRouteAdapter]
    D --> E[官方 OmniRoute 原生服务]
    E --> F[实际 Provider]
    E --> G[脱敏 Provider model usage latency error]
    G --> H[任务快照 业务成本 事件 告警]
    B -. "显式 backend_id；runtime_redacted" .-> I[CliAgentGatewayAdapter]
    I --> J[隔离 CLI Agent Gateway]
    J --> K[Codex CLI 或 Claude Code CLI]
    K --> L[AgentRouter]

Runtime 不再实现 ProviderRouter、OpenAIAgentsProvider、Provider secret box、Provider CRUD、模型目录刷新、健康/冷却或通用回退。

GET /boss/v1/model-backends 返回所有 enabled && available 的通道，而不是只返回当前 Codex/Claude 或全局默认。Console 可将全局默认通道、BOSS/Worker 临时覆盖、Codex/Claude 当前 CLI 通道、模型、推理强度、预算档位和每日最大用量持久化为 Benson 偏好；这些“当前”标记只决定未显式选择时的默认线路，不构成调用许可，也不改变会话、已确认记忆或滚动摘要的 Runtime 权威记录。动态单模型通道在 Smoke 后固定同时具备 BOSS、Worker 与对话资格，旧数据库角色/可切换列仅为增量兼容，读取时统一投影。Codex CLI 固定为 Responses API，Claude CLI 固定为 Anthropic Messages；独立的 Codex Direct API 执行器可明确选择 Responses API 或 Chat Completions，不能将 Direct API 协议伪装成 CLI 选项。公开/私有不再是对话选择项：Runtime 保留原始会话，再为每次模型外发生成 runtime_redacted Prompt，替换可识别的密钥、Token、连接字符串、内部端点和主机路径。Gateway 拒绝其他内部数据范围。Runtime 必须拒绝未知后端和 available=false 候选。Codex Gateway 不可达、凭据未配置或 Smoke 未批准时，对话保持失败/暂停并返回真实原因，绝不自动回退。

阶段四改造后，模型目录还必须明确返回文本增量、图片、附件解析、允许受控上下文和白名单推理强度。文本 Smoke 与图片 Smoke 独立持久化：文本通过只证明最小真实对话可用，图片输入必须另经同一配置的真实图片 Smoke 才开放。上下文只由 Runtime 的 ContextPlanner 按系统约束、相关确认记忆、结构化摘要、最近对话和当前消息组装；SQLite + FTS5 + sqlite-vec 只生成候选，RRF 合并后仍由 Runtime 按确认状态、来源、版本和预算记录选入/省略理由。切换模型不能删除会话记忆。自动脱敏是有边界的基础保护，不能把它宣传为对任意敏感材料的完全识别；某后端没有通过图片真实 Smoke 时，Runtime 必须拒绝图片请求或使用用户可见的 OCR/文本提取模式，禁止静默丢弃附件。

阶段五主动循环复用同一 RuntimeModelGateway、模型目录和 Token 账本，不增加后台专用模型入口或隐藏额度池。Console 的重新运行操作必须创建新的调用与审计快照；Runtime 重启后不得自动重放未完成模型请求。

每次交互记录当时的工作台预算档位并在调用前预留 Token，完成后优先使用官方真实 usage 结算。缺失 usage 时保留估算标记，不得写为精确 0；保守、均衡、宽松的单次输入/输出和规划建议分别为 80k/10k/40、120k/20k/60、240k/40k/100。历史档位或任务字段不构成后续调用限制；默认“无限制”不施加 Runtime Token 上限。Console 的每日最大用量是唯一的可见总量设置；每日值为 0 时不设 Runtime 日总量上限。若用户显式设置有限的每日额度，调用前预留只用于确保该可见额度不被并发调用穿透。通道数量、同一通道并发和 Gateway/Runtime 人工总并发不设预设夹紧；每次调用必须保持独立运行 ID、临时 HOME、输入文件、取消范围与审计，出现可复现的上游限流、串话或资源问题后才针对性修复。

三、阶段四结构化规划与审核调用

智能规划与成果审核继续复用 RuntimeModelGateway 和现有 OmniRoute Boss Combo，不新增 Provider Router、后台模型入口或隐藏预算池。它们是两类独立、可审计的业务调用：

  • 规划调用：温度固定为 0，只提供脱敏能力目录、目标、允许数据等级和预算，要求严格 JSON 输出意图、目标、假设、澄清问题、任务、依赖、预期成果、验收标准、风险和限制。
  • 审核调用：只提供验收标准、可访问证据摘要、确定性检查结果和必要成果摘要，要求输出 accept、rework 或 insufficient_evidence，并引用真实标准 ID 和证据 ID。

每次规划和审核都生成新的 runtime_call_id，保存 Provider/模型/usage/耗时/错误事实和可展示的简短选择说明，不保存隐藏思维链。规划 JSON 第一次解析失败可进行一次修复调用；第二次失败后结束为失败或需要澄清，不执行部分结果。模型审核无法解析、引用不存在证据或调用失败时进入证据不足，不得自动完成；模型调用成功本身不等于审核通过。

Runtime 在模型调用前冻结能力、通道和审计快照，并在模型返回后使用 Pydantic、DAG、能力、数据等级、执行方式、资源、URL 安全和风险规则做确定性验证。预算档位与每日额度的唯一控制面是 AI BOSS 工作台当前设置：历史 Plan 的预算字段只用于审计展示，绝不在后续执行、审核或重试中形成隐藏 Token 上限；“无限制”不产生 Runtime 侧 Token 拒绝。调用预留仅用于用量记账。Runtime 不静默改写模型选择，最多将具体错误交给 AI BOSS 重新规划一次；仍不合法时结束为能力不足或需要澄清。必需确定性检查失败时，AI BOSS 不能覆盖通过。

规划、Worker 模型、检查分析、AI BOSS 审核、一次计划修复和返工的用量都进入统一账本，但不从历史计划或任务取得 Token 拒绝权。瞬时错误最多自动重试一次；Runtime 重启将未完成模型调用标记为 interrupted，只有显式重试才能使用新的 runtime_call_id 和调用预留，禁止自动重放。

角色只选择官方 Combo，不选择 Provider：Boss 固定使用 agentmeshos-free-quality-first，由 fill-first 按质量顺序优先消耗 GPT/Codex、Claude 和 O3 的免费额度；Worker 固定使用 agentmeshos-free-capacity-pool，由 least-used 按每个模型和账号的实际调用次数均衡容量。同等使用量时 Worker 仍沿用 Boss 的质量排序。额度、健康、冷却、失败回退和实际 Provider 继续完全由 OmniRoute 处理。

四、官方接口边界

OmniRouteAdapter 调用：

  • POST /v1/chat/completions
  • GET /v1/models
  • GET /api/monitoring/health

ToolAdapter 通过官方 /api/mcp/tools 读取工具目录，并只接受固定只读/公开研究白名单；未注册或没有已验证官方执行契约的工具返回不可用，不推测调用方法。Evals 和 Guardrails 的配置与原始运行事实由 OmniRoute 保存。Runtime 不复制 MCP Registry、Guardrail 规则库、Eval Case 或 Compression 引擎。

OmniRouteObservabilityAdapter 是与模型调用分离的固定只读适配器。它按受控间隔读取 /api/usage/analytics、/api/usage/cache-health、/api/usage/model-latency-stats、/api/telemetry/summary 和 /api/quota/pools，仅投影总量、分位延迟、错误率、缓存结论和配额池数量到 Runtime SQLite 快照。它不接受浏览器参数、不透传官方 API、不读取调用日志、不保留 Provider/模型/账号/API Key 维度，也不参与模型选择、回退或告警动作。

截图所示的用量、组合健康、利用率、缓存、压缩、搜索、评估和 Provider 统计均属于 OmniRoute 分析面。它们不是当前通用模型 Adapter 的调用入口，也不得被浏览器或模型直接代理。后续如需接入，只能使用独立的固定只读分析 Adapter，并限定为官方聚合端点、时间窗口、脱敏字段和任务关联；原始请求/搜索内容、账号、Provider 配置、缓存条目、Eval Case 和所有写接口仍留在 OmniRoute。

每次调用生成并保存 runtime_call_id。Provider、model、attempt、usage、latency 和 error 只读取官方响应；不存在的实际事实写为 unknown，禁止根据 Combo 名、模型名或历史记录推断。

五、网络与凭据

OmniRoute 原生服务监听 127.0.0.1:39180。Runtime Docker 容器通过 172.30.70.1:39181 的 systemd-socket-proxyd 访问，UFW 只允许固定容器地址 172.30.70.2。Runtime 不加入旧 OmniRoute Docker 网络，101/103 Worker 不获得 OmniRoute Key 或 Provider 凭据。

OmniRoute 管理身份与普通模型身份已经拆分。admin.env 保存管理 Key，model-client.env 保存只允许两个正式 Combo 与 chat/models 的普通模型 Key。普通 Key 已通过两个 Combo 真实调用和直接模型、管理接口拒绝验收，但官方 3.8.49 的 MCP 目录与 Streamable HTTP，以及截图中的分析聚合端点，仍要求 manage/admin。为避免已完成的搜索/抓取能力回归，runtime-call.env 当前继续使用管理 Key；该兼容状态必须在上游修复后重新评估，不能把普通模型 Key误报为已完成 Runtime 切换，也不得用它为分析页建立通用透传。

所有 Key 均只存在于主节点 root-only 配置；Provider/OAuth/API Key 只保存在 OmniRoute 数据与环境边界中。即使 Runtime 当前持有 admin/manage，也只能通过固定 Adapter 和工具白名单调用；浏览器、任务上下文、Nomad Worker、普通日志和 Git 均不得取得该 Key。

CLI Gateway 的 AgentRouter Key 和 Console 新增的外部单模型通道 Key 都只存在于 Gateway 的加密存储或 root-only 环境；Runtime 只持有独立内部调用 Key。Gateway 固定地址为 172.30.70.3:39190，不发布宿主机端口。新增通道必须先以未持久化表单按用户填写的原始 Base URL 请求 /models（禁止擅自追加 /v1；目录不可用时可手填），并使用受控 Gateway User-Agent；目录只帮助选择模型，不能证明调用可用。对选定模型必须发送最小真实对话 Reply exactly: OK 并校验真实返回；CLI 同时校验退出码和结构化结果，Direct API 同时校验协议格式与响应结构，才可取得一次性验证令牌并保存；令牌绑定提供商、执行器、协议、URL、Key 和模型，十分钟内一次有效。当前协议冻结为：系统托管 OmniRoute 使用官方 Chat Completions，Codex CLI 使用官方 Responses API，Claude Code CLI 使用 Anthropic Messages。Codex CLI 官方只支持 Responses，不得把 Chat Completions 伪装成同一通道的下拉选项；Codex Direct API 是已实现的独立执行器，允许 Responses API 或 Chat Completions，沿用独立协议契约、Smoke、审计与凭据边界。调用请求只包含固定 backend_id、runtime_call_id、数据范围、白名单 reasoning_effort 和 Prompt；不接受 cwd、任意 CLI 参数、环境变量、MCP 或工具。Prompt 经标准输入传递；Direct API 使用固定 JSON 请求体；SQLite 只保存哈希、字节数、后端、状态、错误码和耗时。

Claude Code 使用 AgentRouter 官方 Anthropic-compatible 配置：ANTHROPIC_AUTH_TOKEN 作为 Bearer Token，ANTHROPIC_BASE_URL=https://agentrouter.org 且不追加 /v1。Gateway 不注入 ANTHROPIC_API_KEY，不使用会切换认证语义的 --bare；每次 Claude 调用使用独立 /tmp/claude-* HOME，并在调用结束后清理。

实际 Provider、模型、路由 decision 和 USD 上游成本只采用官方响应/SSE 元数据；没有官方 attempt 时写 unknown。Runtime 可把官方 USD 成本写入业务调用账本，但没有明确人民币换算策略时不得把 0 标记为精确人民币成本。

六、任务与成本

任务快照只保存 route=omniroute 和角色对应的模型/Combo ID，不保存 Provider、Base URL、协议凭据、回退链或健康状态。Runtime 保留业务成本、收入和净收益；OmniRoute 保留 Provider 原始用量、组合健康、利用率、缓存/压缩、搜索、评估和路由事实。Runtime 只关联已脱敏的聚合与 runtime_call_id，不保存或重算这些官方事实。没有可靠价格依据时业务成本明确为未知或零记录，不伪算 Provider 成本。

七、失败与验证

  • Provider 可用性必须通过真实模型请求验证，健康或模型目录可达不能替代调用验证。
  • 调用失败只记录脱敏错误和告警，不在 Runtime 内执行第二套回退或修改 Provider。
  • CLI 候选只有真实生成 Smoke 通过后才能启用。当前 Codex gpt-5.6-sol、Claude claude-opus-4-8 与 claude-opus-5 均已逐模型通过生产 Gateway 和正式 Boss API Smoke，目录返回 available=true；任一后续复测失败时必须单独关闭对应开关，不能自动切换或整体放行。
  • Boss、Worker、Combo、任务快照、usage/latency、成本、告警和重启恢复必须分别回归。
  • 新增模型协议或 Provider 能力优先通过官方 OmniRoute 升级获得；不得在 Runtime 重新实现通用 Adapter。