补充策划Agent模型与推理档两步接入方案

在主方案中明确控件复用、配置生效和恢复边界新增控件接入与回合模型生效两个里程碑限定GameAgent兼容性验证范围，不扩展已有组件改造
2026-09-20 20:34:03 +08:00
parent a2acfa9a6f
commit bdecb0c324
3 changed files with 152 additions and 1 deletions
@@ -116,7 +116,63 @@ Runtime 不维护文档版本号，不解析文档版本，不提供版本回退

 会话/回合/工具调用身份用于生产恢复和重复请求处理，与 Agent 自行写在策划文档头部的版本号无关。

-策划会话在创建时保存入口选择的 AGC 模型目录 ID（例如 `quality`、`fast`），同一会话后续回合沿用该 ID；客户端不保存或推断上游真实模型名。官方 `platform-llm` 直连 api-server 时携带 AGC 客户端标记，由 api-server 根据模型目录解析实际模型，不能在客户端硬编码某个上游模型替代目录选择。
+当前实现：策划会话在创建时保存入口选择的 AGC 模型目录 ID（例如 `quality`、`fast`），同一会话后续回合沿用该 ID；客户端不保存或推断上游真实模型名。官方 `platform-llm` 直连 api-server 时携带 AGC 客户端标记，由 api-server 根据模型目录解析实际模型，不能在客户端硬编码某个上游模型替代目录选择。下节提出按回合更新选择的变更，尚未实施，不将提案视为现行能力。
+
+### 4.1 策划对话模型与推理档选择（提案，2026-09-20）
+
+**交付结果**：策划 Agent 对话复用 GameAgent 的模型、推理档选择控件及配置通道，用户的新选择对后续策划回合实际生效，并保持 GameAgent 原有行为兼容。
+
+本节是本次变更的唯一主规范；状态为 `proposed`。现有生产迁移的“已完成”状态不代表本节已完成。拆分与验收见 [控件接入里程碑](../project-memory/plans/【里程碑】策划Agent模型与推理档控件接入-2026-09-20.md) 和 [模型生效里程碑](../project-memory/plans/【里程碑】策划Agent回合模型选择生效-2026-09-20.md)。实施前只为当前已评审里程碑编写实现计划，第一步验收后再进入第二步。
+
+#### 范围与非目标
+
+- 必须项：复用已有控件及客户端配置读写；补齐策划入口；修正旧策划会话固定使用创建时模型的行为；验证 GameAgent 兼容性。
+- 风险项：界面选择与实际请求不一致、执行中途切换配置、恢复旧会话、审批/澄清/重试绕过模型检查，以及策划窄面板新增控件的布局。
+- 可选项：无。发现与上述验收无关的问题，只记录发现，不扩展本次实现。
+- 明确不做：不评估或重构 GameAgent 已有控件的本征不足，不重做模型目录、缓存、配置同步、下拉交互、通用保存队列或错误处理；不调整 GameAgent Runtime、推理默认值、供应商适配、提示词或阶段审批规则；不新建 Agent 专属设置、模型管理页、配置框架或测试框架。
+- 优先在现有共享对话容器中复用同一组组件，不复制控件源码，不因新增一个使用方迁移整套配置型组件。若需要局部接口扩展，默认调用必须保持 GameAgent 现有行为。
+
+#### 控件和配置合同
+
+1. 策划对话输入框附近显示与 GameAgent 相同的模型和推理档控件，读取、选项、保存、错误反馈沿用已有能力；只调整策划宿主必要的显隐、布局和提交接线。
+2. 继续使用客户端全局模型选择与全局推理档，不新增第二份策划设置。它们是客户端偏好，可能影响其它后续对话；进入或重开策划界面时显示当前保存值。既有 GameAgent 配置解析保持不变，不承诺新增跨窗口实时同步。
+3. 策划运行时最终以选择器保存的全局模型和推理档作为本次用户选择；策划专属底层配置不得在这两个字段上静默覆盖选择。连接、鉴权、超时等其余字段继续按既有生产配置解析，不清理或改写用户其它配置。
+4. 模型的官方目录别名、自定义模型目录、默认项跟随及失效项处理复用已有能力；不新增供应商能力探测或模型自动降级。推理档的枚举与默认值维持现状。
+5. 可以在执行中修改后续选择；不会中断或重启正在执行的策划回合。策划保留原有输入、发送、审批和澄清忙态规则，不引入 GameAgent 的消息队列、素材引用或语音功能。
+
+#### 生效边界
+
+| 触发 | 目标行为 |
+| --- | --- |
+| 首次发送、后续普通发送 | 通过已有模型可用性检查，读取最新已保存的选择并开始新回合 |
+| 回答澄清、批准/拒绝阶段后实际继续调用 Provider | 同样使用本次继续前保存的选择；不更改审批结果和请求身份语义 |
+| 用户主动点击失败重试 | 使用最新选择开始本次执行；继续现有工具恢复规则，不重复已完成副作用 |
+| 同一执行内的工具循环、HTTP/流式瞬态自动重试 | 始终使用该次执行开始时确定的模型和推理档，不在每次 Provider 调用前重新采样这两个字段 |
+| 纯读取、展示历史、未触发 Provider 的操作 | 不创建新回合，不覆盖历史使用的模型信息 |
+| 进程中断后的自动续跑 | 优先沿用持久化的活动回合模型和推理档；不把它当成用户重新选模型后的新回合，不重复文件副作用 |
+
+“后续回合生效”按上表定义，不以底层函数是否创建新 turn ID 为判断依据。无需重建会话或清空历史才能切模型，正式策划阶段、产物和上下文继续保留。
+
+#### 失败、兼容与数据约束
+
+- 保存失败、目录不可用和模型校验失败复用现有提示和处理路径，不让策划新增提交入口绕过既有检查。只接入原有能力，不借机修复通用控件未承诺的行为。
+- Provider 不接受所选模型或历史上下文时，沿用现有可见错误和重试；不静默换模型、清历史或另建跨模型上下文转换系统。
+- 已有设计会话无需离线迁移：下次用户发起执行时采用新选择。自动恢复的旧活动回合优先保留已有模型；若尚无推理档快照，使用当次有效配置补齐一次并固定，不伪称还原了历史档位。
+- 持久化仅增加恢复必需的模型选择标识和推理档快照，旧记录缺字段可读；不保存完整配置、端点凭据、Token 或 API Key。不增加平行会话账本，不改模型目录 ID 与真实型号的边界。
+- 本次不涉及公开 HTTP API、OpenAPI 或 SpacetimeDB schema。若本地设计会话投影需要新增字段，同步其现有 Rust/TypeScript 定义和恢复用例。
+
+#### 两步交付与验收
+
+| 步骤 | 交付边界 | 完成证据 |
+| --- | --- | --- |
+| 第一步：控件接入 | 策划宿主显示并使用原控件，选择写入现有全局配置；策划发送等入口接入已有模型检查；不改策划请求的模型解析与快照逻辑 | 策划控件读写、忙态与失败提示定向测试；GameAgent 相关现有用例；宽/窄面板 smoke |
+| 第二步：模型生效 | 在策划执行边界采样并固定模型与推理档，旧会话下次执行采用新选择，自动恢复保留活动回合选择 | 本地 Provider fixture 验证真实请求字段、跨工具调用一致性、重试与恢复；界面到请求 smoke；GameAgent 兼容回归 |
+
+第一步是内部可验收的接入结果，不能宣称“策划旧会话切模型已生效”，也不能作为完整功能单独发布。第二步验收前保持这一已知限制明确。
+
+两个步骤分别形成最小闭环；检查点分别为“控件与兼容验收”和“请求与恢复验收”。实现中的新增发现只有影响本节交付判据时才扩大范围。每步先用一个工作时段完成定向实现与验证；超过时段仍未闭环时，说明剩余阻碍并重估，不以顺手改造组件扩大任务。
+
+验收至少覆盖：保存后重新进入策划显示一致；旧会话切换模型后实际请求改变；当前执行不被中途改档；下一次发送/澄清/审批继续/主动重试生效；自动恢复不重复工具副作用；GameAgent 原有选择、发送和运行行为不回归。真实 Provider 或桌面环境缺失时明确记为未验证，不用 fixture 冒充实机结果。

 ## 5. Agent Runtime