文档：AGC 模型目录上游同步口径与共享记忆

- 主规范补充目录内容、启动期同步、失败关闭、存量旧结构重建与 DTO 兼容口径 - 运维文档新增「AGC 模型目录上游同步」小节与本地 Token 要求 - decision-log 记录本次目录来源变更、验证证据与残留项
2026-09-24 12:11:08 +08:00
parent 3ea9adc0d0
commit 385fbd12e5
6 changed files with 25 additions and 6 deletions
@@ -36,7 +36,7 @@

 ### 目录的来源与初始化

- 目录只描述“平台开放给 AGC 的模型白名单 + 启用状态 + 默认项”。每项只有上游原始模型名 `model` 与 `enabled`，不再有稳定标识、别名或“实际模型名”的二次映射；默认项由 `defaultModel` 指定，且必须指向启用项。列表最多 200 项。
+- 目录只描述“平台开放给 AGC 的模型白名单 + 启用状态 + 默认项”。每项只有上游原始模型名 `model` 与 `enabled`，不再有稳定标识、别名或“实际模型名”的二次映射；默认项由 `defaultModel` 指定，且必须指向启用项。目录规模不设人工条数上限，由上游列表与同步响应大小上限共同约束。
 - 目录事实源是私有 `agc_model_catalog` 单例表，使用 revision 乐观锁，多 api-server 实例共享同一事实。
 - api-server（API/All 角色）启动时检查目录：缺失、无法按当前结构解析、或校验不通过，三种情况都算“未初始化”。此时调用上游 `GET {LLM Router 地址}/models`（OpenAI 兼容列表，Bearer 使用与账号 provisioning 同一份 Router 管理员 Token），读取 `data[].id`，按上游返回顺序重建目录：每项 `enabled = true`，`defaultModel` 取第一个模型，并以存量 revision 写回（`revision` 自增）。并发启动的多个实例里只有一个写入成功，其余按冲突静默接受既有目录。
 - 同步失败（网络、鉴权、非 2xx、空列表、响应超过大小上限、缺少管理员 Token、写回失败）只记录 error 日志，不写任何替代目录、不使用任何内置模型名；本次启动保持未初始化，下一次启动继续重试，直到目录里有数据。
@@ -62,7 +62,7 @@

 - 空目录 + 上游可达：启动后目录自动填充为上游模型列表（`revision` 自增一次），`/api/llm/models` 的 `id`/`displayName` 即上游原始模型名，默认项为列表首项，界面不再出现任何内置模型名。
 - 空目录 + 上游不可达或缺少管理员 Token：启动只记录 error，不产生替代目录；AGC 相关接口与后台目录接口返回 `503`“模型目录未初始化”；下一次启动同步成功后自动恢复。
- 目录领域校验（空列表、超过 200 项、重名、默认项未启用）、未知或停用模型 `422`、客户端响应只含模型名与目录元数据。
+- 目录领域校验（空列表、重名、默认项未启用）、未知或停用模型 `422`、客户端响应只含模型名与目录元数据。
 - 后台鉴权、持久化 revision 冲突处理；客户端选择保存后重新读取，设置保存不覆盖选择。
 - 目录 `revision` 条件刷新与并发触发去重、发送前回退默认模型、刷新失败可恢复。
 - 响应体超时保留有效缓存、再次刷新重新请求、迟到响应不覆盖新目录；手动刷新进行中、同版本成功与缓存兜底失败反馈。
@@ -374,7 +374,7 @@ App 界面测试中，关闭 Agent 弹窗后的迟到读取用例先等待「刷

 ## 常用设置职责

-本地配置 `llm.customEnabled` 为 `true` 时，常用设置开放自定义 Responses 连接、端点模型发现与勾选预览；开关只允许手动修改配置文件。模型选择、直连与凭据边界以 [AGC 后台模型别名与对话选择](./【技术方案】AGC后台模型别名与对话选择-2026-09-05.md) 的“本地自定义 LLM”为准，默认仍使用官方服务。
+本地配置 `llm.customEnabled` 为 `true` 时，常用设置开放自定义 Responses 连接、端点模型发现与勾选预览；开关只允许手动修改配置文件。模型选择、直连与凭据边界以 [AGC 平台模型目录与对话选择](./【技术方案】AGC后台模型别名与对话选择-2026-09-05.md) 的“本地自定义 LLM”为准，默认仍使用官方服务。

 常用设置负责运行参数的读取、编辑和保存，配置读写独立于账号权限诊断。账号权限由登录会话与实际智能服务请求链路处理，设置面板只维护配置草稿与读写反馈。