AGC 新增本地自定义 LLM 配置与展示模型勾选

- 本地配置新增 llm.customEnabled 与 llm.visibleModels，显式开启后保留自定义连接和勾选列表，官方路由下仍清空凭据 - 配置迁移始终写出 customEnabled、visibleModels、apiKey、baseUrl、model、apiKind、reasoningEffort，便于手写自定义连接 - 新增 discover_game_creator_llm_models 命令，直连自定义端点 GET /models，限制超时与响应大小并脱敏错误 - codex_app_server 自定义模式改用配置里的地址与 Key 走本地凭据代理，不再经过平台 /api/llm，也不回退官方路由 - 模型目录按官方与自定义来源隔离缓存，自定义模式只展示勾选模型，选项失效时回退第一项 - 设置页在自定义模式展示 API 地址、API Key、协议与推理档，并提供模型读取、搜索、勾选与已勾选预览 - 补齐固定项排版与读取按钮样式，同步 AGC 模型选择规范、实施计划与共享概览
2026-09-16 16:39:15 +08:00
parent 9663bbf911
commit c36a5170f8
21 changed files with 1301 additions and 57 deletions
@@ -1,6 +1,36 @@
 # AGC 后台模型别名与对话选择

-## 契约
+## 本地自定义 LLM
+
+- 本地 `game-creator.config.json` 的 `llm.customEnabled` 默认 `false`；显式设为 `true` 后，常用设置展示 API 地址、API Key、读取模型列表与勾选区域。DirectProject 沿用 OpenAI Responses 协议，地址填写 API 根地址（例如 `https://provider.example/v1`）。开关只由配置文件控制。
+- 点击读取后，客户端原生侧直接请求该地址下的 `GET /models`，使用自定义 Bearer Key，读取 OpenAI 兼容的 `data[].id`。请求有超时与响应大小上限，禁止携带平台登录凭据、禁止重定向；错误仅展示安全状态，不回显上游响应体或 Key。
+- 模型支持搜索、逐项勾选和独立的已勾选列表预览。`llm.visibleModels` 按勾选顺序保存模型 ID，第一项作为默认项。至少勾选一项才可保存；读取失败保留草稿和已勾选列表，不替用户清空或新增选择。
+- 首页与项目对话复用现有模型选择器；自定义模式只读取本地勾选目录，不请求平台模型目录。模型 ID 原样用于上游请求（允许 `/`、`.`、`:`），所选项被取消勾选时回退第一项。保存后刷新目录，下一回合使用新连接与模型，活动回合继续使用原快照。
+- 开启后，Codex 客户端凭据代理和 Rust LLM 调用均直连自定义端点，不走平台 `/api/llm` 或内置中转；配置缺失或请求失败明确报错，不回退官方路由。真实 Key 留在客户端，不进入 Codex 子进程环境、参数或模型上下文。平台图片、音频、账户和计费契约不变。
+- 配置加载、迁移和覆盖文件写入保留显式开启的连接和勾选列表；关闭时仍使用官方模型目录与官方路由。缓存不能跨自定义/官方目录或不同自定义连接复用。旧配置缺少新字段时保持官方行为。
+- 验收覆盖开关默认值、配置合并/保存/重载、直连凭据与模型传递、模型发现成功/失败/超时、勾选预览、仅显示勾选模型、目录切换、无平台目录请求和设置保存失败。自动化本地 HTTP 验证与真实供应商 smoke 分开报告。
+
+在设置页显示的本地配置文件路径中，手动把现有 `llm` 对象的 `customEnabled` 设为 `true`（保留其它字段），重新打开常用设置即可配置连接和读取模型。界面没有开启开关，保存设置也不能把关闭状态改为开启。配置文件也支持直接填写以下字段：
+
+```json
+{
+  "llm": {
+    "customEnabled": true,
+    "baseUrl": "https://provider.example/v1",
+    "apiKey": "填写自己的密钥",
+    "apiKind": "openai_responses",
+    "visibleModels": ["provider/model-name", "another-model"]
+  }
+}
+```
+
+`visibleModels` 可先留空，再从端点读取并勾选；未完成勾选前不能发起自定义 LLM 对话。关闭时手动改回 `false`，后续回合使用官方目录和路由。
+
+本地配置文件始终保留 `customEnabled`、`visibleModels`、`apiKey`、`baseUrl`、`model`、`apiKind`、`reasoningEffort` 七个键：官方路由下连接字段写官方地址与空 Key、协议写 `openai_responses`，便于手写自定义连接时对照；切换为自定义后这些值原样保留而不被启动清理。
+
+自定义连接固定使用 OpenAI Responses 协议（`apiKind` 只接受 `openai_responses`），设置页把协议展示为只读项；推理档沿用对话输入盒中按回合生效的选择器，设置页只读展示当前档位，不新增第二处写入入口。
+
+## 官方路由契约

 - 后台 owner 在“AGC 模型”维护列表；每项包含稳定 `id`、必填 `alias`、服务端 `modelId`、`enabled`。默认项必须启用。标识唯一，别名唯一，列表最多 32 项。
 - 配置保存到私有 `agc_model_catalog` 单例表，使用 revision 乐观锁，重启及多 api-server 实例共享同一事实。缺少配置时使用初始目录，高质量对应 `gpt-6-astra`，快速对应 `gpt-5.6-luna`。
@@ -14,7 +44,7 @@
 - `selectedModelIsDefault` 为真表示选择由平台默认项驱动（首次进入、默认项变化、所选模型失效回退），后台默认项变化时客户端跟随切换并提示；用户手动选择后置为假，不再被默认项变化覆盖。
 - 首页聊天框架的右下角同样提供模型选择入口（与项目对话右侧一致）。首页入口与项目对话共用同一份目录缓存、挂载即加载（失败时沿用上一次成功目录），选择仅影响后续创建/发送的轮次，不阻塞「开启创作」，因此模型目录不可用时仍可创建项目并使用后台默认项。
 - 项目右侧对话的模型选择器在对话进行中保持可交互：切换模型只写回客户端配置并作用于下一轮，当前回合不受影响；发送按钮仍由 `controlBusy` / `modelReady` 把关。
- 设置页恢复到布局改版前的官方代理版本，不包含模型管理或模型选择，保留配置安全清理和官方代理锁定。
+- 自定义开关关闭时，设置页不包含模型管理或模型选择，使用官方代理锁定。

 ## 验收

@@ -58,9 +58,11 @@ DirectProject 自身的 `read_direct_project_conversation` 也必须在 blocking

 ## 常用设置职责

+本地配置 `llm.customEnabled` 为 `true` 时，常用设置开放自定义 Responses 连接、端点模型发现与勾选预览；开关只允许手动修改配置文件。模型选择、直连与凭据边界以 [AGC 后台模型别名与对话选择](./【技术方案】AGC后台模型别名与对话选择-2026-09-05.md) 的“本地自定义 LLM”为准，默认仍使用官方服务。
+
 常用设置负责运行参数的读取、编辑和保存，配置读写独立于账号权限诊断。账号权限由登录会话与实际智能服务请求链路处理，设置面板只维护配置草稿与读写反馈。

-保存配置复用写入前读取的高优先级本地覆盖内容：常用设置同步覆盖文件中已有的对应配置项，并保留当前模型 ID 和默认模型标记；模型选择仅同步 `selectedModelId` 与 `selectedModelIsDefault`；无冲突时不写覆盖文件。所有内容先完成序列化，多文件写入前保存原始内容，任一写入失败时逆序恢复已变更文件，回滚失败须明确报告。各文件沿用现有原子写入，不提供断电或进程崩溃下的多文件事务保证。全部成功后直接返回规范化配置，不执行保存后回读或外部诊断；单文件保存保持原路径。
+保存配置复用写入前读取的高优先级本地覆盖内容：常用设置同步覆盖文件中已有的对应配置项，并保留当前模型 ID 和默认模型标记；自定义模式取消勾选当前模型时回退第一项，并同步覆盖文件中的选择。模型选择仅同步 `selectedModelId` 与 `selectedModelIsDefault`；无冲突时不写覆盖文件。所有内容先完成序列化，多文件写入前保存原始内容，任一写入失败时逆序恢复已变更文件，回滚失败须明确报告。各文件沿用现有原子写入，不提供断电或进程崩溃下的多文件事务保证。全部成功后直接返回规范化配置，不执行保存后回读或外部诊断；单文件保存保持原路径。

 ## 2026-09-09 manifest 资源功能分类与自定义标签（UI 与写入）