文档：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
@@ -9,7 +9,7 @@

 ## 修改边界与顺序

-1. **领域模型（`module-runtime`）**：`src/agc_models.rs` 的 `AgcModel { model, enabled }`、`AgcModelCatalog { revision, default_model, models }`；删除写死 default，改为布尔校验 + `from_upstream_models`（去重保序、剔除空项、默认项取首个）+ `resolve`（只接受启用项）。列表上限 200，`model` 非空、无首尾空白、≤200 字节、无控制字符、唯一，`default_model` 必须指向启用项。
+1. **领域模型（`module-runtime`）**：`src/agc_models.rs` 的 `AgcModel { model, enabled }`、`AgcModelCatalog { revision, default_model, models }`；删除写死 default，改为布尔校验 + `from_upstream_models`（去重保序、剔除空项、默认项取首个）+ `resolve`（只接受启用项）。`model` 非空、无首尾空白、≤200 字节、无控制字符、唯一（不设人工条数上限），`default_model` 必须指向启用项。
 2. **SpacetimeDB procedure（`spacetime-module`）**：`read_agc_model_catalog` 缺行时返回 `AGC_MODEL_CATALOG_NOT_INITIALIZED`，不再返回内置目录；`save_agc_model_catalog` 逻辑不变（validate + revision 乐观锁 upsert）。无表结构变化，不改 `migration.rs`。
 3. **api-server 目录模块**：`src/agc_models.rs` 拆分“读原始 JSON / 解析校验 / 载入目录”，新增启动期 `ensure_agc_model_catalog_initialized`：目录已初始化直接返回；未初始化则 `GET {llm_router_base_url}/models`（Bearer 管理员 Token、30s 超时、1 MiB 上限、拒绝重定向）取 `data[].id`，用存量 revision 建目录写回；冲突按“他实例已写入”接受；其余失败返回错误。admin DTO 改为 `{revision, defaultModel, models: [{model, enabled}]}`。
 4. **api-server 接线**：`src/main.rs` 在 `try_restore_app_state_for_startup` 中按 HTTP 角色调用初始化，失败只 `error!` 记录，不阻塞启动、不返回 `DependencyUnavailable`。`src/llm/mod.rs` 的公开目录映射改为 `id`/`displayName` 取 `model`，请求侧解析改为“目录内原名透传 + `platform-default` 用默认项”。
@@ -26,7 +26,7 @@ AGC 平台模型目录在 SpacetimeDB 里没有配置时，由 `spacetime-module

 ## 合同要点

- **目录内容**：每项只有 `model`（上游原始模型名）与 `enabled`，另有目录级 `defaultModel`（必须指向启用项）与 `revision`；列表 1 至 200 项，`model` 唯一、无首尾空白、≤200 字节。
+- **目录内容**：每项只有 `model`（上游原始模型名）与 `enabled`，另有目录级 `defaultModel`（必须指向启用项）与 `revision`；不设人工条数上限，`model` 唯一、无首尾空白、≤200 字节。
 - **初始化**：api-server（API/All 角色）启动时，目录缺失、结构与当前定义不符或校验不通过时视为未初始化；此时用 Router 管理员 Token 调 `GET {Router 地址}/models`，按返回顺序取 `data[].id` 建目录，默认项为首个模型，写回时沿用存量 revision 并自增。多实例并发只有一个写入成功。
 - **失败关闭**：拉取失败、缺 Token、空列表或写回失败都只记录 error，不生成替代目录；目录未初始化期间 AGC 相关接口与后台目录接口返回 `503`“模型目录未初始化”，不回退任何内置模型名。
 - **重试口径**：只在启动期尝试；失败后下一次启动重试，直到目录里有数据。启动不因目录未初始化而失败，避免 Router 短时不可用放大成 api-server 无法启动。
@@ -44,7 +44,7 @@ AGC 平台模型目录在 SpacetimeDB 里没有配置时，由 `spacetime-module

 1. 空目录 + 上游可达：启动后目录自动填充为上游模型列表，`revision` 自增一次，`/api/llm/models` 返回的 `id`/`displayName` 即上游原始模型名，界面不出现任何内置模型名。
 2. 空目录 + 上游不可达/缺 Token：启动只记录 error，不产生替代目录；AGC 接口与后台目录接口 `503`；下一次启动同步成功后自动恢复。
-3. 目录领域校验：空列表、超过 200 项、重名、`defaultModel` 未启用都被拒绝。
+3. 目录领域校验：空列表、重名、`defaultModel` 未启用都被拒绝。
 4. 请求侧：目录外模型（含历史稳定标识）返回 `422`；`platform-default` 与未提供 model 使用目录默认项；启用项按原名透传给上游。
 5. 后台：owner 可读写目录（无别名）、revision 冲突 `409`；非 owner 拒绝。
 6. 回归：`npm run check:encoding`、`git diff --check`、Rust 定向测试、admin-web 与 AGC 客户端类型检查/定向测试通过。