AGC 模型目录改为启动期从上游同步：规范更新与里程碑/实施计划

- 更新《AGC 平台模型目录与对话选择》主规范：目录只保留上游原始模型名与启用状态，新增启动期上游同步、失败关闭与存量旧结构重建口径
- 更新 server-rs 与 SpacetimeDB 数据契约中 agc_model_catalog 一节
- 新增里程碑《AGC 模型目录上游同步》与对应实施计划
- 更新 docs/README 索引条目

docs/README.md

@@ -119,7 +119,7 @@
 - [后台 Dashboard 运营看板方案](./technical/【后台管理】Dashboard运营看板方案-2026-06-23.md)
 - [后台多账号与 Tab 访问权限方案](./technical/【后台管理】多账号与Tab访问权限方案-2026-07-14.md)
 - [Pingora 独立网关试点](<./technical/【开发运维】Pingora独立网关试点-2026-06-11.md>)
-- [AGC 后台模型别名与对话选择](./technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md)：官方目录、本地自定义 LLM 开关、端点模型勾选与预览。
+- [AGC 平台模型目录与对话选择](./technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md)：上游模型目录同步、本地自定义 LLM 开关、端点模型勾选与预览。
 - [UI 编辑器工作流完成通知弹窗](./technical/【设计】UI编辑器工作流完成通知弹窗-2026-09-04.md)
 - [官网 SEO 地基实施约定](./technical/【SEO】官网SEO地基实施约定-2026-07-10.md)
 - [UI 编辑器拖动变换提交边界](./【UI编辑器】拖动变换提交边界-2026-09-03.md)

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

@@ -0,0 +1,38 @@
+# AGC 模型目录上游同步实施计划
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | in-progress |
+| Date | 2026-09-24 |
+| Parent Milestone | `docs/project-memory/plans/【里程碑】AGC模型目录上游同步-2026-09-24.md` |
+
+## 修改边界与顺序
+
+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` 必须指向启用项。
+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` 用默认项”。
+5. **后台页面（`admin-web`）**：`AdminAgcModelsPage.tsx` 去掉别名列，模型名可编辑，保留启用、默认、删除与新增；`adminApiTypes.ts` 同步 DTO；更新该页测试。
+6. **AGC 客户端**：`src-tauri/src/main.rs` 的 `DEFAULT_GAME_CREATOR_LLM_MODEL` 改为官方占位标识（`platform-default`），`game-creator.config.json` 的 `model` 同步；`scripts/check-config.mjs` 与 `src-tauri/src/tests/configuration.rs` 断言跟随。
+
+## 不改的部分
+
+- `GET /api/llm/models` 的 DTO 形状、客户端目录缓存/条件刷新/回退逻辑、`selectedModelId`/`selectedModelIsDefault` 语义。
+- Router 账号 provisioning、额度与计费、`/api/external/v1`、OpenAPI、SpacetimeDB 表结构。
+
+## 验证命令
+
+- `cargo test -p module-runtime agc`、`cargo test -p api-server agc`、`cargo test -p api-server llm`（定向）
+- `cargo fmt --all -- --check`、`cargo clippy -p api-server -p module-runtime -p spacetime-module -- -D warnings`（按仓库现状取舍）
+- `npm run check:encoding`、`npm run check:doc-index`、`git diff --check`
+- `npx vitest run apps/admin-web/src/pages/AdminAgcModelsPage.test.tsx`、admin-web 类型检查
+- AGC 客户端：`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml configuration`、`node scripts/check-config.mjs`
+- 运行时 smoke：本地 SpacetimeDB（`npm run dev:spacetime`）+ 本地 api-server 指向 loopback 假上游（`test` 环境允许 loopback Router 地址），确认启动后目录自动填充、`/api/llm/models` 返回上游原名；以及假上游不可用时启动只记录 error、接口 `503`。
+
+## 风险与回滚点
+
+- **上游端点与鉴权未验证**：仓库从无 `GET /models` 调用，New API 是否接受管理员 Token 需要真实环境验证；失败时目录保持未初始化，回滚点是整条初始化链路（删掉启动期调用即可回到旧的硬编码目录）。
+- **存量旧结构目录**：部署后首次启动会按未初始化重建，owner 之前的启用/默认选择丢失，需要重新设置一次（已写入里程碑与主规范）。
+- **目录未初始化期间不可用**：AGC 对话与后台目录接口 `503`，比“用一个已被上游移除的模型”更早暴露问题；首页仍可创建项目。
+- **列表规模**：上游分组模型数超过 200 或响应超过 1 MiB 时按失败处理，需要 owner 在后台维护一个子集。

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

@@ -0,0 +1,57 @@
+# AGC 模型目录上游同步
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | in-progress（实现与定向验证进行中；真实上游 Router 可达性未验证） |
+| Date | 2026-09-24 |
+| Parent Spec | `docs/technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md`（平台模型目录章节） |
+
+## 背景与触发
+
+AGC 平台模型目录在 SpacetimeDB 里没有配置时，由 `spacetime-module` 的 `read_agc_model_catalog` 兜底返回 `module_runtime::AgcModelCatalog::default()`，内容是写死的 `质量 → gpt-6-astra`、`快速 → gpt-5.6-luna`。这两个模型已经不在上游 Router 里，于是未配置目录的环境（新库、清库、后台从未保存过）会把两个不存在的模型下发给客户端：下拉里显示“高质量/快速”，选中后上游 `model_not_found`，对话不可用，必须人工在后台保存一次目录才恢复。
+
+## 目标
+
+1. 目录初始值不再写死：api-server 启动期发现目录未初始化时，从上游 LLM Router 拉取模型列表并按上游原始模型名建目录。
+2. 拉不到就报错、不写替代目录，并在下一次启动继续重试，直到目录里有数据。
+3. 退役“别名”概念：客户端与后台直接使用上游原始模型名。
+
+## 不在本里程碑内
+
+- 不做上游模型的自动跟随同步（上游增删模型不会自动改写已有目录），由 owner 在后台维护。
+- 不改 AGC 客户端的模型选择、缓存与回退逻辑（`GET /api/llm/models` 的 DTO 形状保持不变，存量客户端无需发版）。
+- 不改 Router 账号 provisioning、额度同步与计费链路。
+- 不改 `/api/external/v1`、OpenAPI 与 SpacetimeDB 表结构。
+
+## 合同要点
+
+- **目录内容**：每项只有 `model`（上游原始模型名）与 `enabled`，另有目录级 `defaultModel`（必须指向启用项）与 `revision`；列表 1 至 200 项，`model` 唯一、无首尾空白、≤200 字节。
+- **初始化**：api-server（API/All 角色）启动时，目录缺失、结构与当前定义不符或校验不通过时视为未初始化；此时用 Router 管理员 Token 调 `GET {Router 地址}/models`，按返回顺序取 `data[].id` 建目录，默认项为首个模型，写回时沿用存量 revision 并自增。多实例并发只有一个写入成功。
+- **失败关闭**：拉取失败、缺 Token、空列表或写回失败都只记录 error，不生成替代目录；目录未初始化期间 AGC 相关接口与后台目录接口返回 `503`“模型目录未初始化”，不回退任何内置模型名。
+- **重试口径**：只在启动期尝试；失败后下一次启动重试，直到目录里有数据。启动不因目录未初始化而失败，避免 Router 短时不可用放大成 api-server 无法启动。
+- **存量数据**：旧结构目录（`id`/`alias`/`modelId`）按未初始化处理并从上游重建，owner 之前的启用与默认选择需要重新设置一次。
+- **客户端展示**：`GET /api/llm/models` 的 `id` 与 `displayName` 都是上游原始模型名；请求里的 `model` 就是该模型名，`platform-default` 或未提供时使用目录默认项，目录外模型返回 `422`。
+
+## 依赖
+
+- `api-server`：新增启动期目录初始化；读取 Router 管理员 Token、`llm_router_base_url` 与既有 `save_agc_model_catalog` procedure。
+- `spacetime-module` / `module-runtime`：目录领域模型收敛为 `{model, enabled}`，缺行不再兜底默认目录。
+- `shared-contracts` / `admin-web`：后台目录 DTO 与页面去掉别名列。
+- AGC 客户端：仅清理写死的 `gpt-6-astra` 默认值（`DEFAULT_GAME_CREATOR_LLM_MODEL` 与 `game-creator.config.json` 模板），展示链路不改。
+
+## 验收标准
+
+1. 空目录 + 上游可达：启动后目录自动填充为上游模型列表，`revision` 自增一次，`/api/llm/models` 返回的 `id`/`displayName` 即上游原始模型名，界面不出现任何内置模型名。
+2. 空目录 + 上游不可达/缺 Token：启动只记录 error，不产生替代目录；AGC 接口与后台目录接口 `503`；下一次启动同步成功后自动恢复。
+3. 目录领域校验：空列表、超过 200 项、重名、`defaultModel` 未启用都被拒绝。
+4. 请求侧：目录外模型（含历史稳定标识）返回 `422`；`platform-default` 与未提供 model 使用目录默认项；启用项按原名透传给上游。
+5. 后台：owner 可读写目录（无别名）、revision 冲突 `409`；非 owner 拒绝。
+6. 回归：`npm run check:encoding`、`git diff --check`、Rust 定向测试、admin-web 与 AGC 客户端类型检查/定向测试通过。
+
+## 已决与待决
+
+- 已决：上游列表使用 OpenAI 兼容 `GET {Router 地址}/models`，Bearer 为 Router 管理员 Token（用户 2026-09-24 确认）。
+- 已决：初始化失败不阻塞启动，只在启动期尝试一次，由下一次启动重试。
+- 已决：存量旧结构目录按未初始化重建，不做白名单化兼容转换。
+- 待决：是否需要“上游自动跟随同步”（当前不做）。

docs/technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md

@@ -1,4 +1,6 @@
-# AGC 后台模型别名与对话选择
+# AGC 平台模型目录与对话选择
+
+更新时间：`2026-09-24`。本次变更退役了 2026-09-05 版写死的初始目录与“别名”概念：目录初始值改为启动期从上游 LLM Router 同步，客户端与后台直接使用上游原始模型名；本文件仍是该专题的唯一主规范。
 
 ## 本地自定义 LLM
 
@@ -30,25 +32,37 @@
 
 自定义连接固定使用 OpenAI Responses 协议（`apiKind` 只接受 `openai_responses`），设置页把协议展示为只读项；推理档沿用对话输入盒中按回合生效的选择器，设置页只读展示当前档位，不新增第二处写入入口。
 
-## 官方路由契约
+## 平台模型目录
+
+### 目录的来源与初始化
+
+- 目录只描述“平台开放给 AGC 的模型白名单 + 启用状态 + 默认项”。每项只有上游原始模型名 `model` 与 `enabled`，不再有稳定标识、别名或“实际模型名”的二次映射；默认项由 `defaultModel` 指定，且必须指向启用项。列表最多 200 项。
+- 目录事实源是私有 `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 日志，不写任何替代目录、不使用任何内置模型名；本次启动保持未初始化，下一次启动继续重试，直到目录里有数据。
+- 目录未初始化时 `GET /api/llm/models`、`/api/llm/responses`、`/api/llm/chat/completions` 与后台 `GET/PUT /admin/api/agc-models` 一律失败关闭（`503`），错误文案明确指向“模型目录未初始化”。恢复路径是修复上游可达性后重启，或由运维清空该行后再重启。
+- 存量旧结构目录（`id`/`alias`/`modelId`/`defaultModelId`）在部署后首次启动时按“未初始化”重建，owner 之前的启用与默认选择需要重新设置一次。
+- 上游变化不自动跟随：目录只在未初始化时重建；上游新增或移除模型时，由 owner 在后台增删条目或调整启用、默认项。
+- `GET/PUT /admin/api/agc-models` 仅 owner 可用，DTO 为 `{revision, defaultModel, models: [{model, enabled}]}`，`model` 必填、唯一、不含首尾空白、不超过 200 字节；PUT 携带上次读取的 revision，冲突返回 `409`。
+- `GET /api/llm/models` 保持既有 DTO 形状 `{defaultModelId, models: [{id, displayName}], revision}`，启用项的 `id` 与 `displayName` 都是上游原始模型名（因此存量客户端无需跟随发版），不返回目录凭据或上游原始数据。
+- 请求侧：AGC `POST /api/llm/responses` 与内部 chat 代理的上游 `model` 就是启用项里的上游原始模型名；目录校验通过后原样透传。`platform-default` 或未提供时使用目录默认项；不在启用项里的模型（含历史稳定标识）返回 `422`，不回退其它模型。
+
+### 客户端行为
 
-- 后台 owner 在“AGC 模型”维护列表；每项包含稳定 `id`、必填 `alias`、服务端 `modelId`、`enabled`。默认项必须启用。标识唯一，别名唯一，列表最多 32 项。
-- 配置保存到私有 `agc_model_catalog` 单例表，使用 revision 乐观锁，重启及多 api-server 实例共享同一事实。缺少配置时使用初始目录，高质量对应 `gpt-6-astra`，快速对应 `gpt-5.6-luna`。
-- `GET/PUT /admin/api/agc-models` 仅 owner 可用，返回完整配置；PUT 携带上次读取的 revision，冲突拒绝覆盖。
-- `GET /api/llm/models` 返回启用项的 `id/displayName`、`defaultModelId` 和目录 `revision`，不返回实际模型名、Router 目录、凭据或能力原始数据。
 - 客户端缓存最近 `revision`，在项目切换 / 对话表面挂载 / 下拉展开 / 窗口聚焦时条件刷新：`revision` 未变化不更新界面，同一时刻只保留一个在途请求，刷新失败保留上一次有效目录与本地选择。发起对话前用同一份快照校验所选模型仍启用，已停用或删除则回退默认模型并提示。
 - 手动刷新立即显示进行中状态；真实刷新成功后显示完成反馈，即使 `revision` 未变化也有反馈。失败沿用有效缓存时仍显示失败，不能报告刷新成功；HTTP 状态和超时使用可辨认的提示。
 - 模型目录与其它客户端 JSON API 的成功、失败响应体读取均复用 `readClientHttpResponseText` 的 15 秒上限；响应头已返回但响应体卡住时必须结束本次等待、释放目录在途请求并允许重试，迟到的响应不得覆盖新目录。
-- AGC Responses 请求的 `model` 是稳定目录标识。服务端按当前目录映射实际模型名；未知、停用项拒绝，不回退其它模型。旧客户端无 AGC 标记时使用后台默认项。
-- 输入框右下角选择模型，只显示别名；选择保存到客户端配置 `selectedModelId` 与 `selectedModelIsDefault`（当前选择是否来自平台默认项），从下一次请求生效。加载失败或选项停用时禁用提交并允许刷新，不显示实际 ID 作为兜底文案。
+- 输入框右下角选择模型，显示目录 `displayName`（即上游原始模型名）；选择保存到客户端配置 `selectedModelId` 与 `selectedModelIsDefault`（当前选择是否来自平台默认项），从下一次请求生效。加载失败或选项停用时禁用提交并允许刷新。
 - `selectedModelIsDefault` 为真表示选择由平台默认项驱动（首次进入、默认项变化、所选模型失效回退），后台默认项变化时客户端跟随切换并提示；用户手动选择后置为假，不再被默认项变化覆盖。
-- 首页聊天框架的右下角同样提供模型选择入口（与项目对话右侧一致）。首页入口与项目对话共用同一份目录缓存、挂载即加载（失败时沿用上一次成功目录），选择仅影响后续创建/发送的轮次，不阻塞「开启创作」，因此模型目录不可用时仍可创建项目并使用后台默认项。
+- 首页聊天框架的右下角同样提供模型选择入口（与项目对话右侧一致）。首页入口与项目对话共用同一份目录缓存、挂载即加载（失败时沿用上一次成功目录），选择仅影响后续创建/发送的轮次，不阻塞「开启创作」，因此模型目录不可用时仍可创建项目（真正发送对话仍要求目录可用）。
 - 项目右侧对话的模型选择器在对话进行中保持可交互：切换模型只写回客户端配置并作用于下一轮，当前回合不受影响；发送按钮仍由 `controlBusy` / `modelReady` 把关。
 - 自定义开关关闭时，设置页不包含模型管理或模型选择，使用官方代理锁定。
 
 ## 验收
 
-- 目录领域校验、未知/停用模型拒绝、客户端响应不包含实际模型名。
+- 空目录 + 上游可达：启动后目录自动填充为上游模型列表（`revision` 自增一次），`/api/llm/models` 的 `id`/`displayName` 即上游原始模型名，默认项为列表首项，界面不再出现任何内置模型名。
+- 空目录 + 上游不可达或缺少管理员 Token：启动只记录 error，不产生替代目录；AGC 相关接口与后台目录接口返回 `503`“模型目录未初始化”；下一次启动同步成功后自动恢复。
+- 目录领域校验（空列表、超过 200 项、重名、默认项未启用）、未知或停用模型 `422`、客户端响应只含模型名与目录元数据。
 - 后台鉴权、持久化 revision 冲突处理；客户端选择保存后重新读取，设置保存不覆盖选择。
 - 目录 `revision` 条件刷新与并发触发去重、发送前回退默认模型、刷新失败可恢复。
 - 响应体超时保留有效缓存、再次刷新重新请求、迟到响应不覆盖新目录；手动刷新进行中、同版本成功与缓存兜底失败反馈。

docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md

@@ -507,9 +507,11 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
 ### `agc_model_catalog`
 
 - 私有单例表，主键 `id=0`，保存 `catalog_json`、`revision`、`updated_at`；不存凭据。
-- `read_agc_model_catalog` / `save_agc_model_catalog` 只接受已登记的 runtime service identity，保存使用 revision 乐观锁。
-- 后台 owner 通过 `GET/PUT /admin/api/agc-models` 管理稳定标识、必填别名、实际模型名、启用状态和默认项；客户端 `GET /api/llm/models` 仅返回启用项的稳定标识、别名和目录 `revision`（供条件刷新，不暴露实际模型名）。
-- Responses / Chat 请求按目录解析模型；未知或停用项拒绝。AGC 的 `platform-default` 请求标识使用目录默认项。详细契约见 `technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md`。
+- `read_agc_model_catalog` / `save_agc_model_catalog` 只接受已登记的 runtime service identity，保存使用 revision 乐观锁；缺行时读取返回 `AGC_MODEL_CATALOG_NOT_INITIALIZED`，不返回内置目录。
+- 目录只描述“平台开放给 AGC 的模型白名单 + 启用状态 + 默认项”：每项只有上游原始模型名与启用状态，不再有稳定标识、别名或“实际模型名”映射。
+- api-server（API/All 角色）启动时若目录缺失、结构与当前定义不符或校验不通过，就用 Router 管理员 Token 调用上游 `GET {LLM Router 地址}/models` 按上游原始模型名重建目录；拉不到只记录错误、不写替代目录，由下一次启动重试。目录未初始化期间 AGC 目录与对话接口、后台目录接口都失败关闭（`503`）。
+- 后台 owner 通过 `GET/PUT /admin/api/agc-models` 管理模型名、启用状态和默认项；客户端 `GET /api/llm/models` 返回启用项的模型名与目录 `revision`（供条件刷新），不暴露凭据或上游原始数据。
+- Responses / Chat 请求按目录校验模型名并原样透传给上游；未知或停用项拒绝。`platform-default` 或未提供模型时使用目录默认项。详细契约见 `technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md`。
 
 ### `error_report`