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

- 主规范补充目录内容、启动期同步、失败关闭、存量旧结构重建与 DTO 兼容口径
- 运维文档新增「AGC 模型目录上游同步」小节与本地 Token 要求
- decision-log 记录本次目录来源变更、验证证据与残留项

docs/project-memory/plans/【实施计划】AGC模型目录上游同步-2026-09-24.md

@@ -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` 用默认项”。

docs/project-memory/plans/【里程碑】AGC模型目录上游同步-2026-09-24.md

@@ -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 客户端类型检查/定向测试通过。

docs/project-memory/shared-memory/decision-log.md

@@ -9329,3 +9329,16 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 影响面：`server-rs/crates/api-server/src/{config.rs,modules/game_distribution.rs}`、`server-rs/crates/shared-contracts/src/game_distribution.rs`、`packages/shared/src/contracts/gameDistribution.ts`、`src/components/game-distribution/gameDistributionGuards.ts`（含新增测试）、`deploy/{nginx,container,env}`、`scripts/check-game-distribution-media-e2e.mjs`、`package.json`、平台与运维主规范。
 - 边界：SpacetimeDB 表结构与公开契约字段不变（`entryUrl` 仍是 string），只是取值从绝对 URL 变为相对路径；历史版本已冻结的绝对值不改写，admin 页与详情页展示口径不变。线上 dev / release 的 nginx 已按同源路径改动并 reload，`/etc/genarrative/api-server.env` 已删除模板变量；api-server 未重启，新写入要等下次重启。
 - 验证：`cargo check -p api-server --tests`、`cargo test -p api-server game_distribution`（27 passed）、`cargo fmt --all --check`、`npx vitest run src/components/game-distribution`（57 passed）、`npm run check:nginx-spa-routes`、`npm run check:encoding`（5060 文件）、`npm run check:doc-index`、`git diff --check` 全部通过；三份 nginx 模板渲染后 `nginx -t` 语法通过；dev 线上实测 `/games/game_2dcd…4955/` 与 `./assets/index-2Ws3zHlS.js` 均 200。
+
+## 2026-09-24 AGC 模型目录改为启动期从上游同步：退役写死的 gpt-6-astra/gpt-5.6-luna 与别名
+
+- 背景：`agc_model_catalog` 缺行时由 procedure 兜底返回内置目录（`质量 → gpt-6-astra`、`快速 → gpt-5.6-luna`），而这两个模型已从上游 Router 移除；未配置目录的环境（新库、清库、后台从未保存过）会把不存在的模型下发给客户端，选中后上游 `model_not_found`，必须人工在后台保存一次才恢复。
+- 决策（目录内容）：目录只描述“平台开放给 AGC 的模型白名单 + 启用状态 + 默认项”，每项只有上游原始模型名 `model` 与 `enabled`，目录级 `defaultModel` 必须指向启用项；退役稳定标识、别名与“实际模型名”二次映射，不设人工条数上限。
+- 决策（初始化）：api-server（API/All 角色）启动时若目录缺失、结构与当前定义不符或校验不通过，用 Router 管理员 Token 调上游 `GET {GENARRATIVE_LLM_ROUTER_BASE_URL}/models`，按 `data[].id` 顺序建目录（全部启用、默认项取首个），并以存量 revision 写回自增；并发启动的实例只有一个写入成功，其余接受既有目录。
+- 决策（失败关闭与重试）：拉取失败、缺 Token、空列表、响应超过 1 MiB 上限或写回失败都只记录 error，不生成任何替代目录；本次启动保持未初始化，下一次启动继续重试，直到目录里有数据。未初始化期间 `/api/llm/models`、`/api/llm/responses`、`/api/llm/chat/completions` 与后台 `GET/PUT /admin/api/agc-models` 一律 `503`“模型目录未初始化”。启动本身不因同步失败而失败，避免 Router 短时不可用放大成 api-server 无法启动。
+- 决策（契约兼容）：公开目录 DTO 形状不变，`id` 与 `displayName` 都是上游原始模型名，存量客户端无需发版即可显示原名；请求里的 `model` 就是目录中的模型名，`platform-default` 或未提供时使用目录默认项，目录外模型（含 `quality` 等历史稳定标识）返回 `422`。存量旧结构目录（`id`/`alias`/`modelId`）按未初始化处理并从上游重建，owner 之前的启用与默认选择需要重新设置一次。
+- 决策（上游不自动跟随）：目录只在未初始化时重建；上游新增或移除模型由 owner 在后台「AGC 模型」页维护（页面已去掉别名列，只保留模型名、启用、默认与增删）。
+- 影响范围：`server-rs/crates/{module-runtime,spacetime-module,api-server,shared-contracts}`（目录领域模型、`read_agc_model_catalog` 缺行语义、启动期 `ensure_agc_model_catalog_initialized`、公开目录投影与请求侧解析、admin DTO）、`apps/admin-web`、`apps/ai-game-creator-shell`（首启模板与 Rust 默认模型改为 `platform-default` 占位）、平台/后端/运维三份 docs 与专题主规范。
+- 验证：`cargo check --locked -p api-server -p module-runtime -p spacetime-module -p shared-contracts --tests`；`cargo test -p module-runtime --lib agc_models::`（3 passed）；`cargo test -p api-server --bin api-server agc`（30 passed / 1 ignored）与 `llm::`（18 passed）；`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bins configuration::`（45 passed）；两套 workspace 的 `cargo fmt -- --check`；`npm run check:spacetime-schema`、`npm run check:server-rs-ddd`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`；admin-web 页面定向 Vitest 与 typecheck；AGC 客户端 `scripts/check-config.mjs` 与 `conversationModelSelect.test.tsx`。
+- 验证（真实栈 smoke，本地隔离 SpacetimeDB 与 loopback 假上游）：空库 + 上游可达 → 启动日志 `已按上游模型列表初始化 AGC 模型目录 revision=1 model_count=2`，`GET /api/llm/models` 返回 `smoke-model-alpha/beta`（id=displayName，revision=1）；空库 + 上游不可达 → 启动 `ERROR` 打印未初始化原因，接口 `503`“模型目录未初始化”；同一库改用可达上游重启 → 同步成功（满足“下次启动重试直到有数据”）；目录已存在时重启 → 不重写（revision 保持 1）。
+- 边界（未验证/残留）：真实上游 Router 是否接受管理员 Token 调 `GET /v1/models`、以及其分组可见模型集合需要在真实环境确认；`OFFICIAL_LLM_ROUTER_MODEL = "gpt-6-astra"` 仍作为部署配置校验常量与 provisioning 元数据存在（已与目录解耦，建议单独评估是否移除）；本地开发需要 `GENARRATIVE_LLM_ROUTER_ADMIN_TOKEN` 才能自动同步目录，缺 Token 时会失败关闭而不是回退内置模型。