解决platform-llm和策划agent reasoning问题，并修复若干bug (#350)

Reviewed-on: #350

docs/project-memory/plans/【里程碑】Provider推理与正文分离及策划Agent展示-2026-09-14.md

@@ -0,0 +1,214 @@
+# 【里程碑】Provider 推理与正文分离及策划 Agent 展示
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | in-progress |
+| Date | 2026-09-14 |
+| Parent Spec | `docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md` |
+| Related Issue | `GenarrativeAI/Genarrative#331` |
+
+## 一句话交付结果
+
+让策划 Agent 能在流式回合中单独收到 Provider reasoning，并在 UI 中以默认折叠的思考过程展示；用户可见正文、工具调用和 GameAgent 现有行为保持不变。
+
+## 当前实现进度（2026-09-14）
+
+- 已完成共享 reasoning 字段、Provider 解析、策划事件映射以及正文流式收尾的前两轮提交。
+- 当前第三轮聚焦策划 Agent 前端 reasoning 生命周期：按 `projectPath + clientTurnId` 绑定事件，回合结束后保留本轮 reasoning，下一轮或项目切换时清理。
+- 现有 `<details>` 展示保持默认收起，并提供明确的展开/收起入口；不新增持久化字段，也不改动 GameAgent、Direct/Codex、supervisor 或已退役链路。
+- 已核对实际会话产物：Responses 原生 `history` 已持久化 `reasoning` / `reasoning_text`，当前修复补齐 `reasoning_text` 提取，并在策划会话恢复时回填最近一轮 reasoning。
+
+## 背景与现状
+
+- `platform-llm` 当前只向上层提供正文累计值、正文增量和结束状态。
+- Chat 兼容响应中的 `reasoning`、`reasoning_content` 以及 reasoning content part 会被正文提取器过滤。
+- Responses 响应中的 reasoning 类型 output item 也不会进入独立的上层字段。
+- 策划 Agent 已经预留 `DesignEvent.reasoningText`、`planningV2Reasoning` 和默认折叠 UI，但 Provider 解析链没有产出数据，因此折叠区通常不出现。
+- GameAgent 当前只消费 `delta_text`、`accumulated_text` 和 `finish_reason`，没有消费策划 Agent 的 `reasoningText`。
+
+## 目标
+
+1. 为 Provider 流式响应增加独立 reasoning 增量和累计通道。
+2. 为非流式终态响应提供独立 reasoning 字段。
+3. 支持 Responses 和 Chat 兼容协议的 reasoning 解析。
+4. 仅由策划 Agent 显式启用 reasoning 捕获和 UI 转发。
+5. 保证 reasoning 不进入用户可见正文、工具调用参数或 GameAgent 消息流。
+6. 在无 reasoning、reasoning 解析异常、重试和工具调用共存场景下保持可恢复行为。
+
+## 非目标
+
+- 不改变 GameAgent 的正文展示、工具调用、`<think>` 过滤和运行时状态语义。
+- 不把 reasoning 自动拼接到 `delta_text`、`accumulated_text` 或正式 assistant 消息。
+- 不把 reasoning 作为新的业务消息类型写入策划会话历史。
+- 不新增通用 reasoning UI，不改造 Direct/Codex 的过程卡展示。
+- 不修改 Provider 请求模型、推理档位或 token 预算。
+- 不为 reasoning 增加新的 SpacetimeDB 表、公开 API 或持久化 schema。
+
+## 受影响模块与边界
+
+### Provider 共享层
+
+`server-rs/crates/platform-llm` 负责协议解析和流式累计：
+
+- `LlmStreamDelta` 增加 `reasoning_delta` 与 `accumulated_reasoning`。
+- `LlmRunResponse` 增加终态 reasoning 字段。
+- `LlmRunRequest` 增加默认关闭的 reasoning 捕获开关。
+- 正文提取继续排除隐藏 reasoning part；reasoning 进入旁路字段。
+- reasoning 解析失败只丢弃 reasoning，不影响正文和工具调用。
+
+### 策划 Runtime
+
+`apps/ai-game-creator-shell/src-tauri/src/agent/design_runtime.rs` 仅在策划专用请求中打开 reasoning 捕获：
+
+- 流式 reasoning 更新映射到已有 `DesignEvent.reasoningText`。
+- 正文继续使用已有 `text` 事件。
+- 新回合、重试、项目切换和请求失败时清理旧 reasoning。
+- debug 记录与正文记录分开，内容受现有 debug 开关和长度限制约束。
+
+### 其它调用方
+
+GameAgent、Agent Interaction、Direct/Codex 适配层和通用 runtime 继续只读取正文字段。新增 reasoning 字段默认为空，不改变这些调用方的业务判断。
+
+### 前端
+
+复用现有 `ProjectSupervisorView` 的 `designReasoning` 和默认折叠 `<details>` 展示。只补事件生命周期和状态清理，不新建平行组件或平行状态协议。
+
+## 分步实施方案
+
+### 第一步：冻结共享契约与兼容开关
+
+明确字段语义、空值语义和捕获开关：
+
+- reasoning 字段只表示 Provider 返回的内部推理内容，不代表用户正文。
+- 捕获开关默认关闭；未启用时新增字段为空。
+- 正文、工具调用、finish reason 和 Responses 原生 output 的现有语义保持不变。
+- 该步只更新规范、类型定义和构造点，不接入策划 UI。
+
+验收重点：所有现有 Rust 构造点可编译，GameAgent 现有调用仍只依赖正文字段。
+
+### 第二步：实现 `platform-llm` 协议解析
+
+分别补齐：
+
+- Responses reasoning 增量事件；
+- Responses 终态 reasoning output item / summary；
+- Chat `reasoning`、`reasoning_content` 和 reasoning content part；
+- 正文与 reasoning 的独立累计；
+- reasoning 与正文、工具调用同时出现时的顺序和去重；
+- reasoning 解析失败时的降级行为。
+
+Responses 的原生 output 仍按当前方式保留，用于后续 Responses 会话回放；新增 reasoning 字段只用于上层展示和调试消费。
+
+验收重点：正文永远不含 reasoning；无 reasoning 的响应与当前行为一致。
+
+### 第三步：补齐共享适配层并锁定 GameAgent 不变
+
+更新 `LlmStreamDelta` 构造点、适配器和测试辅助函数，使它们为新增字段提供空值。检查并锁定：
+
+- GameAgent 正文流不读取 reasoning；
+- 工具调用判断不读取 reasoning；
+- Direct/Codex 过程卡不显示 reasoning；
+- 通用 response stream 过滤逻辑不因新增字段改变。
+
+验收重点：现有工具调用、正文流式、Direct 和 Agent Interaction 测试无行为回归。
+
+### 第四步：接通策划 Runtime 与现有 UI
+
+仅在策划 Agent Provider 请求中启用捕获开关：
+
+- 收到 reasoning 增量时发出独立 `reasoningText`；
+- 收到正文增量时继续发出原有 `text`；
+- 重试时替换同一回合的临时 reasoning，不残留上一 attempt；
+- 正式回合结束后保留本回合展示，下一回合开始时清理；
+- UI 默认折叠，展开后显示累计 reasoning，不影响正文滚动和输入。
+
+验收重点：策划 Agent 能看到独立 reasoning，正文气泡不重复、不混入推理文本。
+
+### 第五步：完成回归、文档和验收证据
+
+形成逐条证据矩阵，至少覆盖：
+
+- Responses reasoning 增量和终态；
+- Chat reasoning 字段和 content part；
+- 正文与 reasoning 分离；
+- reasoning 与工具调用并存；
+- reasoning 解析失败降级；
+- 无 reasoning 兼容行为；
+- 策划 Runtime 事件映射和 UI 生命周期；
+- GameAgent 正文与工具调用回归。
+
+## 第五轮验收证据
+
+| 验收面 | 证据 | 结果 |
+| --- | --- | --- |
+| Chat / Responses reasoning 解析 | `cargo test --manifest-path server-rs/Cargo.toml -p platform-llm` | PASS，152 个单元测试；含字段、content part、SSE 增量、终态快照和正文隔离 |
+| reasoning 与工具调用共存 | `responses_response_captures_reasoning_alongside_tool_call`、既有 Chat/Responses 流式工具测试 | PASS |
+| 默认关闭与请求兼容 | `run_request_defaults_to_openai_responses_api_kind`、`reasoning_capture_switch_does_not_change_provider_request_body` | PASS |
+| 策划 Runtime 生命周期 | `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell design_runtime` | PASS，10 个测试；含事件映射、history 隔离、重试清理和失败清理 |
+| GameAgent / Direct/Codex 正文回归 | `cargo check --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --tests` 与现有 response stream / direct tests 编译 | PASS；新增字段未进入正文消费路径 |
+| 前端与文档门禁 | `npx tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` | PASS |
+| 格式门禁 | `cargo fmt --all --manifest-path server-rs/Cargo.toml -- --check`、AGC Tauri 同命令 | PASS |
+
+真实 Provider、浏览器运行时 smoke 和 `check-config.mjs` 的 Windows 私有 DACL 路径本轮未验证；前者需要凭据和运行环境，后者受当前沙箱权限限制，不能据此扩大验收结论。
+
+## 契约与持久化策略
+
+- 不修改 HTTP API、OpenAPI、SpacetimeDB schema 或生成绑定。
+- 不新增正式持久化字段；策划会话仍保存既有对话和 Responses 原生 output。
+- reasoning 捕获开关属于 Provider 请求的内部调用语义，默认关闭，不改变已有请求的默认指纹和展示行为。
+- reasoning 不作为下一轮普通用户可见正文回灌；Responses 原生 output 的恢复语义保持现状。
+
+## 失败、重试与恢复
+
+- reasoning 解析失败：保留正文和工具调用，reasoning 字段置空或保留已累计部分。
+- Provider 瞬态重试：reasoning 与正文使用同一回合、同一响应槽，新的 attempt 替换临时值。
+- 流中断：沿用现有 Provider 错误和策划会话恢复规则，不把未完成 reasoning 误判为正式消息。
+- UI 刷新或项目恢复：只从当前事件/状态恢复 reasoning，不隐式唤醒 Provider。
+
+## 风险与回滚点
+
+| 风险 | 控制措施 | 回滚点 |
+| --- | --- | --- |
+| 共享结构体新增字段导致构造点遗漏 | 先补齐所有构造点和编译检查 | 回退共享字段提交 |
+| Provider 把 reasoning 混入正文 | 保留独立提取器和正文过滤测试 | 关闭 reasoning 捕获开关 |
+| Responses summary 事件重复累计 | 以增量事件为主，终态仅做快照/兜底 | 关闭对应事件解析 |
+| GameAgent 意外展示 reasoning | 捕获默认关闭，调用方只读正文字段 | 回退策划开关，不影响共享解析 |
+| 重试残留旧 reasoning | 按回合和响应槽清理/替换 | 回退 UI 事件消费 |
+
+## 验收命令
+
+代码实现阶段按里程碑执行，不在本计划阶段运行业务测试。预计命令：
+
+```text
+cargo test -p platform-llm
+cargo test -p ai-game-creator-shell
+npm run typecheck
+npm run check:encoding
+git diff --check
+```
+
+文档阶段已要求补充运行：
+
+```text
+npm run check:doc-index
+npm run check:encoding
+git diff --check
+```
+
+## 第六轮定位：历史 reasoning 位置修复
+
+持久化 Responses history 中，reasoning 不一定紧邻可见 `message`：一次 Provider 响应可能先产生 reasoning 和多个 `function_call`，下一次响应才产生正文。原实现遇到下一段 reasoning 就提前结束上一段，无法绑定到 `session.messages` 中的正确 assistant 响应，前端遂把无 `messageId` 的条目统一追加到列表底部。
+
+修复方式是按每个用户回合分别收集：
+
+- `session.history` 中 reasoning 的响应顺序；
+- `session.messages` 中 assistant 消息的响应顺序。
+
+两者按顺序绑定，允许 reasoning 跨越 tool-only Responses；同一正文对应多段 reasoning 时前端合并显示，仍使用默认折叠的单个思考区域。只有没有任何可见 assistant 消息的异常历史才保留为底部 orphan。
+
+验证：新增 tool-only Responses 顺序回归测试，策划 Runtime 定向测试 11/11 通过；前端聚合逻辑保留历史多段 reasoning 的顺序。
+
+## 当前状态与下一步
+
+当前已完成 Provider 解析、策划 Runtime 生命周期、历史 reasoning 恢复及响应顺序归属修复；待本轮提交后继续按定向回归结果推进后续验收。字段语义、默认关闭策略、Responses 事件覆盖范围和 reasoning 不进入普通上下文的约束保持不变。

docs/project-memory/shared-memory/decision-log.md

@@ -206,6 +206,7 @@
 
 - 背景：#211 要求 sidecar 满足当前用户独占、禁止继承的 DACL。新建文件会先继承父目录 ACE，生产路径把这种短暂不合格送进 UAC；`project.lock` 还在独占句柄上 harden。含空格项目路径上提权 ArgumentList 被拆开，修复以 exit 1 失败。GDD 审批改意见因此弹权限，V1 锁创建不会。
 - 决策：`harden_new_game_creator_private_path` 只在本进程收紧 owner/DACL，失败则删除刚创建的对象，不 UAC 接管。项目锁先写再释放句柄再 harden，并用内容回读防换绑；UAC 仍只用于允许范围内的已有外人本对象。提权 helper 的 ArgumentList 改为一条按 Windows 规则加引号的字符串。
+- 补充：逐级创建 `.agent`、`runtime`、`locks` 等目录时，即使祖先已有 `manifest.json`，刚由本进程创建的目录也必须直接走 owner/DACL 初始化，不能因 managed-path 判定进入 UAC；自动项目根目录同样在创建成功后立即本地加固。
 - 影响范围：`config.rs` 的新建 harden 与提权命令行、`project/write_lock.rs` 的项目锁创建；不改变锁竞争、失效回收、Drop 删除，也不放宽 symlink / reparse / 外人本 fail-closed。
 - 验证方式：Windows 定向测试覆盖 `Genarrative GameAgent\gameagent-*` 取锁与私有 DACL，以及带空格路径的 quoted ArgumentList。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/pitfalls.md`。
@@ -357,6 +358,7 @@
 
 - 背景：立项策划 GDD 批准后需要给用户一个进入做游戏的自然出口，产品决策改为点击按钮后直接开始建造。
 - 决策：批准态 GDD 交付行提供“做成游戏”按钮。点击后读取当前项目的权威 `game/fast_gdd.md`，直接创建自动游戏工作区、导入 `text/markdown` 参考附件，并以固定建造指令自动启动 Direct Codex；不再回首页等待用户二次提交。该动作不复制原项目的 `approvedGddRef`、planning sidecar 或 approval receipt。
+- 补充：策划项目切换到 GameAgent 时，`design_artifacts` 的新增或登记信息实际变化必须与一次项目 revision 推进配对；重复切换不重复推进，避免 manifest 已变化而 revision 仍停留在旧值，触发前端同 revision 清单冲突提示。
 - 影响范围：AGC 前端 GDD 交付行与现有自动建项/附件导入/Direct Codex 链路；移除首页 RichInputArea 的 GDD 一次性预填链路；不新增 HTTP API、SpacetimeDB schema、迁移、OpenAPI 或正式构建绑定。
 - 验证方式：批准态按钮直接创建工作区、导入附件、携带固定首条指令进入项目工作台且重复点击不重复创建的 appSurface 回归；类型检查、编码检查和 `git diff --check` 通过。
 - 关联文档：`docs/technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md`。

docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md

@@ -342,12 +342,12 @@ UI 使用“批准”和“继续修改”两个文字按钮，分别配 Lucide
 
 ## 14. 开发调试入口
 
-项目运行模式通过 `.agent/runtime-mode.json` 持久化。新建策划项目在进入工作台前写入 `design`；“做成游戏”写入 `game`。重新打开项目时通过 `get_design_agent_runtime_mode` 读取模式，完成后一次性挂载对应工作台，不能先挂载 GameAgent 再切回策划。旧项目缺少模式文件但存在策划会话时按 `design` 恢复；明确的 `game` 标记优先于残留策划会话。无模式也无策划会话的项目仍使用游戏工作台。
+项目运行模式通过 `.agent/runtime-mode.json` 持久化。新建策划项目在进入工作台前写入 `design`；“做成游戏”先登记 `design_artifacts` 中尚未登记或登记信息已变化的策划产物，若 manifest 实际发生变化则在同一项目写锁范围内推进一次项目 revision，再写入 `game`。重复切换不重复登记或推进 revision。重新打开项目时通过 `get_design_agent_runtime_mode` 读取模式，完成后一次性挂载对应工作台，不能先挂载 GameAgent 再切回策划。旧项目缺少模式文件但存在策划会话时按 `design` 恢复；明确的 `game` 标记优先于残留策划会话。无模式也无策划会话的项目仍使用游戏工作台。
 
 开发构建的策划工作区页头在“刷新”旁提供“快速准备做成游戏测试”按钮。该入口与策划 Debug 日志共用 `GENARRATIVE_AGC_DESIGN_DEBUG=1` 开关：开关未启用时按钮不显示，命令也不可执行。入口仅进行本地 fixture 和会话状态写入，不调用 Provider；完成后自动刷新文件树与阶段，通过 `design-agent-update` 状态事件同步右侧审批/阶段操作区。随后仍需点击正常的“做成游戏”按钮执行资产登记与运行时切换。
 
-## 15. 策划 Agent reasoning 展示现状
+## 15. 策划 Agent reasoning 展示
 
-右侧栏已预留策划 Agent 的 `reasoningText` 事件字段和默认折叠的展示样式，但当前 Provider 解析链仍会过滤 reasoning 内容，尚未向策划 Runtime 产出该字段。因此现阶段只展示用户可见正文和工具状态；reasoning 折叠区在没有数据时不会出现。
+策划 Agent 的 Provider 请求显式开启 `capture_reasoning`，共享 `platform-llm` 将 Chat / Responses 的 reasoning 通过独立字段旁路传递，策划 Runtime 映射为已有 `DesignEvent.reasoningText`，前端复用右侧栏默认折叠的思考过程展示。正文、工具调用参数、正式 assistant message 和会话 history 继续使用原有字段；GameAgent、Direct/Codex 与通用 response stream 保持只消费正文的行为。
 
-后续若补充 reasoning，需要在策划 Agent 专用 Provider 解析层接入，不能直接修改共享 Provider 以免影响 GameAgent。
+reasoning 捕获默认关闭。新回合和 Provider 重试会先清空同一响应槽的临时 reasoning，失败路径也会清理，避免旧内容残留。该能力不新增公开 API、SpacetimeDB 字段或独立 UI 组件。