AGC 把执行器与线协议拆成正交维度

AgcAgentMode 回退为仅 codex/cc，只表示执行器；新增 AgcModelProtocol 表示线协议协议取值 openai_responses/openai_chat/anthropic，与执行器组合封闭并在校验时失败关闭存量目录缺 protocol 时按执行器推导；历史误写的 agentMode=anthropic 读取时归一为 cc 后台 AGC 模型页拆成 Agent 模式与协议两列，新增协议下拉与对应测试公开目录 /api/llm/models 与后台 DTO 同时下发解析后的 protocol 客户端持久化 selectedModelProtocol，选模型时按执行器推导兜底协议并校验组合 Codex wire_api 按协议在 responses/chat 间切换，不再硬编码 responses 同步 appSurface 与模型选择测试断言，补 protocol 字段同步模型别名文档与后端架构文档的正交维度说明
2026-10-02 11:43:17 +08:00
parent fbd30d7c66
commit 6bf57c1e51
20 changed files with 346 additions and 35 deletions
@@ -55,8 +55,10 @@

 ## 模型绑定 Agent 执行模式

- 后台 AGC 模型目录每项新增 `agentMode`，接受 `codex`、`cc` 与 `anthropic`；缺少该字段的历史目录按 `codex` 解释，后台新增模型默认 `codex`。`anthropic` 是 2026-10-01 新增的显式 Anthropic Messages 协议值，`cc` 保留为同一 Claude 执行器的历史别名（两者都映射到 `claude_code_cli`），新目录项应直接写 `anthropic`。
- 2026-10-01 补充：`cc`/`anthropic` 一律经平台 LLM 网关的独立 Anthropic 路由 `POST /api/llm/anthropic/{*path}`，客户端 `ANTHROPIC_BASE_URL` 为 `{apiBaseUrl}/api/llm/anthropic`，不得再用配置里的 `llm.baseUrl`（那是 Router 地址，平台不会把账号 Router key 下发给客户端）。Claude Agent SDK 自己拼 `{base}/v1/messages` 并带 `authorization: bearer` 与 `anthropic-version`，网关据此转发上游 `{routerBase}/v1/messages`。
+- 后台 AGC 模型目录每项新增 `agentMode`，只接受 `codex` 与 `cc`；缺少该字段的历史目录按 `codex` 解释，后台新增模型默认 `codex`。
+- 2026-10-01 修正（原先误把协议塞进 `agentMode`）：**执行器与线协议是两个正交维度**。目录新增独立字段 `protocol`，取值 `openai_responses` / `openai_chat` / `anthropic`；`agentMode` 只表示客户端启动哪个执行器。合法组合是封闭的——`codex` 只能用 `openai_responses` 或 `openai_chat`，`cc` 只能用 `anthropic`，其余组合在后台保存与目录加载时都失败关闭。存量目录缺少 `protocol` 时按执行器推导（codex → `openai_responses`，cc → `anthropic`）；历史误写的 `agentMode: "anthropic"` 读取时归一到 `cc`。
+- 选路由协议决定：`openai_responses` → `/api/llm/v1/responses`，`openai_chat` → `/api/llm/v1/chat/completions`，`anthropic` → 独立路由 `/api/llm/anthropic/{*path}`。客户端把所选模型的协议与执行器一起持久化（`agentMode` + `selectedModelProtocol`），Codex 的 `wire_api` 按协议在 `responses` / `chat` 间切换。
+- 2026-10-01 补充：`cc` 一律经平台 LLM 网关的独立 Anthropic 路由，客户端 `ANTHROPIC_BASE_URL` 为 `{apiBaseUrl}/api/llm/anthropic`，不得再用配置里的 `llm.baseUrl`（那是 Router 地址，平台不会把账号 Router key 下发给客户端）。Claude Agent SDK 自己拼 `{base}/v1/messages` 并带 `authorization: bearer` 与 `anthropic-version`，网关据此转发上游 `{routerBase}/v1/messages`。
 - `codex` 仍表示现有 AGC Codex app-server 执行链路；`cc` 表示 AGC 客户端启动随包的 Claude Agent SDK sidecar，模型的 `modelId` 原样作为 Claude Agent SDK 的模型标识，不把 Claude 协议伪装成 OpenAI Responses。sidecar 随 AGC 安装包携带 SDK 及匹配平台的 Claude Code runtime，用户不需要预先安装 `claude` 命令。
 - `/api/llm/models` 的启用模型摘要返回 `agentMode`，后台完整目录、管理 DTO 和客户端目录保持同一绑定快照。客户端在选择模型时同时持久化模型 ID 与执行模式；默认模型变化、模型被停用或目录刷新回退时一并更新执行模式。
 - 客户端设置保存不得把后台模型绑定覆盖回 Codex。旧客户端配置缺少执行模式时继续按 Codex 运行；旧后台响应缺少 `agentMode` 时客户端按 Codex 兼容。
@@ -536,7 +536,7 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
 - 私有单例表，主键 `id=0`，保存 `catalog_json`、`revision`、`updated_at`；不存凭据。
 - `read_agc_model_catalog` / `save_agc_model_catalog` 只接受已登记的 runtime service identity，保存使用 revision 乐观锁；缺行时读取返回 `AGC_MODEL_CATALOG_NOT_INITIALIZED`，不返回任何内置目录。
 - 目录初始值来自上游同步：api-server（API/All 角色）启动时若目录缺失、结构与当前定义不符或校验不通过，就用分组定价列表 `GET {Router 控制面}/api/pricing?group=taonier`（公开只读、不带凭据）的 `data[].model_name` 生成目录（`id` 为模型名 slug，`alias`/`modelId` 为上游原名），失败只记录 error、不写替代目录，由下一次启动重试；未初始化期间 AGC 目录与对话接口、后台目录接口都失败关闭（`503`）。
- 后台 owner 通过 `GET/PUT /admin/api/agc-models` 管理稳定标识、必填别名、实际模型名、启用状态和默认项；客户端 `GET /api/llm/models` 仅返回启用项的稳定标识、别名和目录 `revision`（供条件刷新，不暴露实际模型名）。
+- 后台 owner 通过 `GET/PUT /admin/api/agc-models` 管理稳定标识、必填别名、实际模型名、启用状态、默认项，以及**执行器 `agentMode` 与线协议 `protocol` 两个正交维度**：`agentMode` 只取 `codex` / `cc`，`protocol` 只取 `openai_responses` / `openai_chat` / `anthropic`，合法组合封闭（codex ⇒ responses/chat，cc ⇒ anthropic），非法组合在保存与加载两侧都失败关闭；存量目录缺 `protocol` 时按执行器推导。客户端 `GET /api/llm/models` 返回启用项的稳定标识、别名、`agentMode`、解析后的 `protocol` 和目录 `revision`（供条件刷新，不暴露实际模型名）。
 - Responses / Chat 请求按目录解析模型；未知或停用项拒绝。AGC 的 `platform-default` 请求标识使用目录默认项。详细契约见 `technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md`。

 ### `error_report`