diff --git a/docs/project-memory/plans/【里程碑】策划Agent回合模型选择生效-2026-09-20.md b/docs/project-memory/plans/【里程碑】策划Agent回合模型选择生效-2026-09-20.md new file mode 100644 index 000000000..52d81cddd --- /dev/null +++ b/docs/project-memory/plans/【里程碑】策划Agent回合模型选择生效-2026-09-20.md @@ -0,0 +1,48 @@ +# 策划 Agent 回合模型选择生效 + +| 字段 | 值 | +| --- | --- | +| Version | 1.0 | +| Status | proposed | +| Date | 2026-09-20 | +| Parent Spec | [策划 Agent 生产迁移与工作区浏览方案 §4.1](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#41-策划对话模型与推理档选择提案2026-09-20) | + +## 目标 + +策划已有会话在后续执行时真正采用控件保存的模型和推理档,执行途中保持选择稳定,恢复不破坏既有工具副作用边界。 + +## 范围 + +- 新会话、旧会话后续消息、回答澄清、阶段审批继续和用户主动重试的选择生效。 +- 同一次执行中的工具循环、自动重试固定使用开始时的选择。 +- 活动回合自动恢复所需的最小模型、推理档快照及旧会话缺字段读取。 +- 模型切换保留策划上下文、阶段、审批和产物。 + +## 不在范围内 + +- 不改变 GameAgent Runtime 或既有配置控件算法。 +- 不调整模型目录、默认档位、供应商协议、提示词和阶段规则。 +- 不建立 Agent 专属设置、通用快照框架、历史转换器或平行账本。 + +## 依赖与前置条件 + +- [控件接入里程碑](./【里程碑】策划Agent模型与推理档控件接入-2026-09-20.md) 已验收。 +- 主规范和本里程碑已评审,实施前编写仅覆盖本步的实现计划。 +- 生效时机、主动重试与自动恢复的区分遵循主规范,不通过重建会话实现切换。 + +## 验收标准 + +- [ ] 新策划会话和旧策划会话下一次执行都使用当前已保存选择;旧模型不再永久覆盖新选择。 +- [ ] 发送、澄清、审批继续与主动重试的实际 Provider 请求使用新选择。 +- [ ] 执行中改配置不影响本次后续工具请求或瞬态自动重试,下一次用户执行才生效。 +- [ ] 自动恢复优先使用已有活动回合快照;旧记录缺推理档时按主规范补齐,不重复已执行工具副作用。 +- [ ] 切换后上下文、阶段、产物和审批身份保留,纯读取不改历史模型信息。 +- [ ] 配置/Provider 失败沿用可见错误,不静默降级、换模型或清空历史。 +- [ ] GameAgent 既有选择和运行行为通过兼容回归,没有借机修正其本征不足。 + +## 证据要求 + +- 自动化:本地 Provider fixture 捕获请求模型和推理档;覆盖跨工具调用、自动重试、用户重试、审批/澄清继续及旧会话恢复;运行相关 Rust 定向测试、必要类型检查、编码和文档索引检查。 +- 运行时:在现有策划项目选择另一模型及推理档,触发下一次执行核对实际请求;真实供应商是否接受跨模型历史需按环境记录实测或未验证。 +- 边界:验证恢复幂等和凭据不进入新增快照;无需新增通用权限或供应商测试体系。 +- 全部验收后将主规范提案改为当前行为,更新稳定项目记忆并删除本次已完成临时计划。 diff --git a/docs/project-memory/plans/【里程碑】策划Agent模型与推理档控件接入-2026-09-20.md b/docs/project-memory/plans/【里程碑】策划Agent模型与推理档控件接入-2026-09-20.md new file mode 100644 index 000000000..da19d81aa --- /dev/null +++ b/docs/project-memory/plans/【里程碑】策划Agent模型与推理档控件接入-2026-09-20.md @@ -0,0 +1,47 @@ +# 策划 Agent 模型与推理档控件接入 + +| 字段 | 值 | +| --- | --- | +| Version | 1.0 | +| Status | proposed | +| Date | 2026-09-20 | +| Parent Spec | [策划 Agent 生产迁移与工作区浏览方案 §4.1](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#41-策划对话模型与推理档选择提案2026-09-20) | + +## 目标 + +策划对话复用已有模型和推理档控件,能够读取和保存全局选择,保持 GameAgent 兼容性。 + +## 范围 + +- 输入区域中控件的显隐、位置、策划面板布局与必要的宿主接线。 +- 复用原有目录、默认模型、保存和错误提示,不复制逻辑。 +- 策划发送、澄清、审批继续和主动重试中会调用 Provider 的入口,接入已有模型可用性检查;不改变原有审批和忙态含义。 +- 重新进入策划时显示保存值;执行中可以调整后续选择,但原输入与提交忙态维持不变。 + +## 不在范围内 + +- 不修改策划 Provider 的模型选择和推理档采样逻辑,不声称旧会话已能切模型。 +- 不检查、修复或重构 GameAgent 组件本征不足,不引入通用缓存、同步、保存、下拉或配置框架改造。 +- 不为策划引入队列、语音或素材引用,不更改默认推理档。 + +## 依赖与前置条件 + +- 主规范本节与本里程碑完成评审。 +- 实施前仅为本里程碑编写实现计划,确认现有 GameAgent 对应回归用例与策划宿主入口。 +- 本步作为内部接入结果;第二步完成前不单独发布为完整可切模型功能。 + +## 验收标准 + +- [ ] 策划入口显示原模型及推理档控件,没有重复实现或第二份设置。 +- [ ] 选择走原保存通道;重新进入显示已保存值;保存失败显示原有错误反馈。 +- [ ] 策划会调用 Provider 的用户入口执行已有模型可用性检查,失败时不提交。 +- [ ] 策划忙态、待审批/澄清行为保持;新增布局在宽/窄面板可操作。 +- [ ] GameAgent 原控件的显示、选择、发送校验、忙态和运行行为通过相关回归。 +- [ ] 交付明确记录旧策划会话仍沿用旧模型,留待下一里程碑解决。 + +## 证据要求 + +- 自动化:现有界面测试中增加策划入口的集成场景,复用 GameAgent 回归;运行 AGC 类型检查、文档索引、编码和 diff 检查。 +- 运行时:桌面与窄面板选择、保存、重新进入和一次策划发送 smoke;缺失环境如实标注。 +- 边界:只验证接入所需的失败和忙态,不扩展为现有组件全量审计。 +- 通过本步验收后,才准备并执行模型生效里程碑的实现计划。 diff --git a/docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md b/docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md index c2801edee..11ad233df 100644 --- a/docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md +++ b/docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md @@ -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