优化AGC客户端同步LLM配置 #292

New Issue

2026-09-07T10:09:45+08:00

suzmii commented

2026-09-07 10:09:45 +08:00

问题描述

后台管理页面发布新的LLM配置之后，客户端必须手动刷新才能同步最新配置，期望优化这个问题。

可选方案

方案 A
- GET /api/llm/models 增加返回 revision；
- 客户端记录上次 revision，在「项目切换 / 对话表面挂载 / 下拉展开 / 窗口聚焦」时做条件刷新（revision 变了才更新）；
- 每次发起对话前再校验一次所选模型是否仍启用；若已停用则自动回退默认项并提示，避免用户拿失效模型硬发。
方案 B
- 走 API Server 已有的 SSE / Tauri event 基建，广播「模型目录已更新」，在线客户端即时刷新。
- 需要新增/维护订阅链路与在线状态。

@kdletters 建议使用哪个方案？

## 问题描述后台管理页面发布新的LLM配置之后，客户端必须手动刷新才能同步最新配置，期望优化这个问题。 ## 可选方案 - 方案 A - GET /api/llm/models 增加返回 revision； - 客户端记录上次 revision，在「项目切换 / 对话表面挂载 / 下拉展开 / 窗口聚焦」时做条件刷新（revision 变了才更新）； - 每次发起对话前再校验一次所选模型是否仍启用；若已停用则自动回退默认项并提示，避免用户拿失效模型硬发。 - 方案 B - 走 API Server 已有的 SSE / Tauri event 基建，广播「模型目录已更新」，在线客户端即时刷新。 - 需要新增/维护订阅链路与在线状态。 @kdletters 建议使用哪个方案？

suzmii self-assigned this 2026-09-07 10:09:45 +08:00

kdletters added the Kind/Enhancement label 2026-09-07 14:21:29 +08:00

kdletters commented

2026-09-07 17:44:59 +08:00

This was generated by AI during triage.

建议先采用方案 A，把模型目录 revision 作为客户端同步契约；SSE 可以在条件刷新已证明不足后再引入。需要先定义 revision 的递增/不变规则、条件请求未变化时的响应，以及项目切换、对话表面挂载、下拉展开、窗口聚焦多个触发同时发生时的去重与竞态处理。

发送前校验应与目录刷新使用同一份快照：所选模型被停用或删除时回退到当前默认模型并给出明确提示；默认模型也不可用时才进入错误分支。保存选择时要保证“最后一次选择”不会被较早的异步响应覆盖，刷新失败也不能把有效的本地选择误清空。

验收建议覆盖：后台发布后各触发点的条件刷新、重复触发只产生必要请求、停用/删除当前模型的回退、并发保存的最后写入获胜，以及离线/超时情况下的可恢复行为。

> *This was generated by AI during triage.* 建议先采用方案 A，把模型目录 revision 作为客户端同步契约；SSE 可以在条件刷新已证明不足后再引入。需要先定义 revision 的递增/不变规则、条件请求未变化时的响应，以及项目切换、对话表面挂载、下拉展开、窗口聚焦多个触发同时发生时的去重与竞态处理。发送前校验应与目录刷新使用同一份快照：所选模型被停用或删除时回退到当前默认模型并给出明确提示；默认模型也不可用时才进入错误分支。保存选择时要保证“最后一次选择”不会被较早的异步响应覆盖，刷新失败也不能把有效的本地选择误清空。验收建议覆盖：后台发布后各触发点的条件刷新、重复触发只产生必要请求、停用/删除当前模型的回退、并发保存的最后写入获胜，以及离线/超时情况下的可恢复行为。

suzmii commented

2026-09-08 16:01:12 +08:00

问题原因

后台在「AGC 模型」页发布新配置后，GET /api/llm/models 只返回 models 与 defaultModelId，没有可比较的版本标识；AGC 客户端只在组件挂载或手动点「刷新模型列表」时拉取目录，所以后台改完后必须手动刷新（或重启客户端）才生效。

采用方案（方案 A）

按 @kdletters 的建议先做「revision 契约 + 条件刷新」，SSE 暂不引入：

契约：GET /api/llm/models 增加 revision，取值来自 agc_model_catalog 已有的乐观锁 revision（后台每次保存自增）；不新增其它字段，仍不返回实际模型名。
客户端条件刷新：本地缓存最近 revision，在「项目切换 / 对话表面挂载 / 下拉展开 / 窗口聚焦」时刷新；revision 未变化则不更新界面、不产生多余渲染。同一时刻只保留一次在途请求，重复触发复用结果；刷新失败保留上一次有效目录与本地选择，不误清空。
发送前校验：发起对话前用同一份目录快照校验所选模型仍启用；已停用/删除则回退当前默认模型并提示，默认模型也不可用才进入错误分支。
保存竞态：模型选择保存串行化，只有最新一次选择落盘后才恢复可发送状态。

改动范围

后端：server-rs/crates/shared-contracts/src/llm.rs 的 LlmModelsResponse 增加 revision；server-rs/crates/api-server/src/llm/mod.rs 的 public_model_catalog 透出该字段（/api/llm/models 不属于 /api/external/v1，无需改 OpenAPI）。
前端：apps/ai-game-creator-shell 的模型目录加载与发送前校验。
文档：同步 docs/technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md。

验收

后台发布后，四个触发点在 revision 变化时刷新；revision 未变时不产生请求。
多触发点并发只发必要请求；刷新失败 / 离线可恢复。
停用/删除当前模型时回退默认并提示；默认模型不可用才报错。
并发保存 last-write-wins。
Rust 定向测试、AGC typecheck 与定向测试、编码检查、git diff --check。

依赖与风险

PR #299（修复 AGC 模型选择入口、交互与默认模型回退；review 已通过、CI 全绿、待合并）与本次改动落在同一组件 ConversationModelSelect。本分支从 master 起，等 #299 合并后会 merge master 并复用其默认回退逻辑，避免重复实现。

分支：feat/agc-client-sync-llm-config（基于 master）

## 问题原因后台在「AGC 模型」页发布新配置后，`GET /api/llm/models` 只返回 `models` 与 `defaultModelId`，没有可比较的版本标识；AGC 客户端只在组件挂载或手动点「刷新模型列表」时拉取目录，所以后台改完后必须手动刷新（或重启客户端）才生效。 ## 采用方案（方案 A）按 @kdletters 的建议先做「revision 契约 + 条件刷新」，SSE 暂不引入： 1. **契约**：`GET /api/llm/models` 增加 `revision`，取值来自 `agc_model_catalog` 已有的乐观锁 revision（后台每次保存自增）；不新增其它字段，仍不返回实际模型名。 2. **客户端条件刷新**：本地缓存最近 revision，在「项目切换 / 对话表面挂载 / 下拉展开 / 窗口聚焦」时刷新；revision 未变化则不更新界面、不产生多余渲染。同一时刻只保留一次在途请求，重复触发复用结果；刷新失败保留上一次有效目录与本地选择，不误清空。 3. **发送前校验**：发起对话前用同一份目录快照校验所选模型仍启用；已停用/删除则回退当前默认模型并提示，默认模型也不可用才进入错误分支。 4. **保存竞态**：模型选择保存串行化，只有最新一次选择落盘后才恢复可发送状态。 ## 改动范围 - 后端：`server-rs/crates/shared-contracts/src/llm.rs` 的 `LlmModelsResponse` 增加 `revision`；`server-rs/crates/api-server/src/llm/mod.rs` 的 `public_model_catalog` 透出该字段（`/api/llm/models` 不属于 `/api/external/v1`，无需改 OpenAPI）。 - 前端：`apps/ai-game-creator-shell` 的模型目录加载与发送前校验。 - 文档：同步 `docs/technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md`。 ## 验收 - 后台发布后，四个触发点在 revision 变化时刷新；revision 未变时不产生请求。 - 多触发点并发只发必要请求；刷新失败 / 离线可恢复。 - 停用/删除当前模型时回退默认并提示；默认模型不可用才报错。 - 并发保存 last-write-wins。 - Rust 定向测试、AGC typecheck 与定向测试、编码检查、`git diff --check`。 ## 依赖与风险 - PR #299（修复 AGC 模型选择入口、交互与默认模型回退；review 已通过、CI 全绿、待合并）与本次改动落在同一组件 `ConversationModelSelect`。本分支从 master 起，等 #299 合并后会 merge master 并复用其默认回退逻辑，避免重复实现。分支：`feat/agc-client-sync-llm-config`（基于 master）

suzmii referenced a pull request that will close this issue

2026-09-08 16:24:58 +08:00

优化AGC客户端同步LLM配置 #306

suzmii closed this issue

2026-09-09 13:19:44 +08:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: GenarrativeAI/Genarrative#292