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

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

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 时会失败关闭而不是回退内置模型。