保留唯一的thread manager作为direct project的状态来源 (#384)

说明: 在把工作交给段哥前还没有实现direct project聊天页面的迁移, 导致在 #375 里用很复杂的实现又做了一套事件流, 实测还有会话丢失的bug, 我在这里把数据获取的部分迁移到 #367 上

---------

Co-authored-by: 孔令弘 <ink29535@proton.me>
Reviewed-on: https://git.genarrative.world/git/GenarrativeAI/Genarrative/pulls/384
Reviewed-by: 孔令弘 <ink29535@proton.me>
Co-authored-by: 王德宇 <kvtodev@outlook.com>
Co-committed-by: 王德宇 <kvtodev@outlook.com>

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

@@ -18,6 +18,16 @@
 - 验证：客户端定向 Rust 测试、格式、编码和 diff 检查通过；未修改主站路由或 BgFilter。
 ## 2026-09-17 图集切分模式改为显式声明
 
+## 2026-09-17 DirectProject 首屏历史锚点只认订阅回执的 lastCompletedItemId
+
+- 背景：ADR「首屏历史由 `subscribe` 返回的 `lastCompletedItemId` 锚定，再取最近切片」只落了一半。`DirectThreadManager` 是搬运层，内存里没有「已完成条目」的锚点，`subscribe` 一律返回 `last_completed_item_id: None`；`commands.rs` 的 `subscribe_direct_project_thread` 在为空时用 `read_direct_project_last_item_id_at` 从磁盘回填，所以线上回执里的值是真的（订阅那一刻文件里最后一条可显示条目的原始 item id）。前端侧：首屏一直在 `loadProjectConversation` 里用 `beforeItemId: null` 直接取文件尾一屏，`lastCompletedItemId` 自 `1b40f030e` 起不再被任何代码读取。
+- 决策（锚点语义）：首屏切片的新端（较新一侧）边界就是这个锚点，**含锚点条目本身**；切片命令新增 `throughItemId` 参数表达「取到这条为止」。比锚点更新的条目只从运行态事件来，历史切片与实时流因此不重叠（原来的文件尾读取会把订阅回执之后才完成的条目也拉进历史，与运行态事件同 id 重叠，只靠前端合并兜住）。
+- 决策（读取时机）：订阅回执到达之前不读首屏，也不退化成「取文件尾」；锚点缺失（订阅不可用 / 失败 / 历史为空）时才按文件尾取尾屏。`/history` 手动重读保持「按当前文件尾取尾屏」的恢复语义，不锚定。
+- 决策（翻页不变）：向后翻页仍用切片返回的 `firstItemId` 作 `beforeItemId`（不含锚点），`hasMore` 与连拉口径不变。
+- 影响范围：`agent/direct_project_history.rs`（切片锚点 + `through_item_id` 参数）、`commands.rs`（`read_direct_project_history_slice` 命令参数）、AGC 前端首屏读取接线与测试骨架。**未改**：DirectRuntime 的 `turn-stream.jsonl` / `tool-calls.jsonl` 写入与进度事件、`list_game_creator_direct_active_turns`、SpacetimeDB 与 HTTP 契约。
+- 验证方式（已跑）：Rust 侧 `cargo test agent::direct_project_history`（22 passed，含「窗口取到锚点那条、排除比锚点更新的条目、`beforeItemId` 与 `throughItemId` 互斥报错」三类用例）；前端 `npx vitest run .../directHistoryAnchorGate.test.ts`（10 passed）与 appSurface 的 `anchors the first history page at the subscribe receipt instead of the file tail`（全量 475 tests / 457 passed / 17 skipped；唯一失败 `edits the published runtime config without leaking API keys into chat` 与本次改动无关，stash 掉本次前端改动后同样变红）；`tsc` / ESLint / prettier / `check:encoding` / `check:doc-index` / `git diff --check` 全绿。变异验证：闸门忽略「已消费」、首屏不等闸门两处改动各自让对应用例变红。
+- 关联文档：[ADR](../../adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md)、[里程碑](../plans/【里程碑】DirectProject聊天真相源收敛-2026-09-16.md)、[实施计划](../plans/【实施计划】DirectProject聊天真相源收敛-2026-09-16.md)。
+
 - 决策：`sliceMode` 在图标图集生成入口成为必填字段且不保留任何默认值。省略、`null` 或空字符串必须在引用解析、定价、入队和 provider / OSS 副作用之前返回 `400`（`field=sliceMode`）；`grid` 必须同时提供 `gridX`/`gridY`，`connected-components` 不得携带网格尺寸，二者矛盾同样在副作用前失败关闭。
 - 决策要求：只有用户或需求明确要求等分网格、固定槽位或指定行列数时才使用 `grid`，且行列数必须来自该需求；自由排布、数量不定或只要求一张图集时显式传 `connected-components`，需要约束素材张数时用 `sliceCount`，不得用网格参数表达张数，也不得用固定 `2×2` 表达“四类素材”。
 - 影响面：平台两个图集生成入口（`/api/editor/...` 与 `/api/external/v1/editor/...`）、OpenAPI、画板 Agent 工具、画板前端提交计划、AGC 客户端 MCP 工具说明与桥接校验、AGC 原生工具 schema 与观察器、AGC Skill 与外部编辑器 Skill。
@@ -87,6 +97,16 @@
 - 验证方式：`three_dimensional_game_request_frees_the_engine_choice`、`explicit_flat_presentation_requests_do_not_trigger_three_dimensional_selection`、`named_engine_requests_keep_the_existing_engineering_rule`、`three_dimensional_contract_reports_the_current_project_engine`、`home_three_dimensional_note_keeps_project_creation_available`、`system_prompt_is_bounded_and_declares_direct_runtime`，以及 `agent::direct_tools_mcp` 17 passed；`cargo fmt --check` 通过。本机临时目录 owner ACL 与进程用户不一致，涉及 `init_local_game_project_at` 的既有用例（含未改动模块）在本机无法执行，全量分片与真机 smoke 未在本轮取得。
 - 关联文档：[里程碑](../plans/【里程碑】Direct三维请求自选技术栈-2026-09-16.md)、[实施计划](../plans/【实施计划】Direct三维请求自选技术栈-2026-09-16.md)。
 
+## 2026-09-17 DirectProject 历史分页的「可显示」口径定为前端回合反馈，一次翻页连拉上限 5 页
+
+- 背景：ADR 与里程碑要求「一次翻页操作在前端自动连拉，直到出现可显示条目或 `hasMore=false`，上限 5 页」，但实现只落地了后端锚点与文件尾回扫，前端仍是单发一页。历史切片的 `limit` 按原始条目计，一整页全是工具卡片 / 思考文本且落进同一个已渲染回合的折叠「执行过程」时，用户点「显示更早的对话」看不到任何变化。
+- 决策（可显示 = 出现新回合）：一次翻页操作连续取页，停止判据是**合并后聊天投影的回合数增加**（出现新的用户气泡）。工具卡片与思考文本虽然能通过 `projectDirectThreadItem`，但它们可能整页落进已渲染回合的折叠过程区，不构成用户可见反馈。
+- 决策（粒度和上限）：每个用户操作最多 5 次请求，首屏那次算第 1 页、之后每次点击重新计数；每页仍是 `limit = CONVERSATION_VISIBLE_STEP`，上限只约束请求次数，不改页大小契约。
+- 决策（硬性终止）：`items` 为空、`firstItemId` 为 null 或与请求锚点相同 → 立即停止，不靠 5 页上限兜底。
+- 决策（落点）：口径与循环只在 `features/project-workspace/directHistoryPaging.ts` 一份实现里，首屏与「显示更早」共用；`DIRECT_HISTORY_MAX_PAGES_PER_ACTION` 放 `app/constants.ts`。
+- 边界：循环内只累积、结束后一次性并入聊天 state；某页失败时保留已成功页并沿用现有报错文案；切换项目时丢弃整批；不新增 loading / 禁用态与新文案，不做滚动锚定补偿；运行中回合允许连拉历史。
+- 验证：`directHistoryPaging` 单测 8 条覆盖口径、上限、`hasMore=false` 早停、锚点不前进、单页失败；`project-development.suite.ts` 新增「跨页同回合」集成用例作为真实回归网（变异验证：把判据退化成「有可渲染条目就停」后该用例变红）；`tsc` 与 `appSurface.test.ts`（470 tests / 17 skipped）全绿。
+
 ## 2026-09-16 图标图集自动拆图上限提高到 256
 
 - 背景：AGC 图标图集自动连通域识别在一次生成中识别出 86 个区域，原有 64 片上限在后处理阶段阻断了请求；该上限同时影响 api-server 自动 / 手动切片、SpacetimeDB 批量落库和统一生成结果 item 数量。
@@ -8336,6 +8356,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 
 - `.agent/conversations/project.jsonl` 中的 DirectProject 用户消息由 AGC 在 `turn/start` 前以 `direct-codex:{clientTurnId}:user` 幂等追加；写入失败时禁止发起 Codex turn，失败或中断也保留该 user item。
 - Codex app-server 回显的 `userMessage` / `role=user` item 不是第二个历史来源。AGC 只处理其观察和关联，不再把该 echo 追加到项目历史；Codex 的 assistant、tool 和其它有效 response item 仍按现有 append-only 规则落盘。
+- 2026-09-17 追加：回显过滤必须同时覆盖**运行态事件侧**（`direct_thread_visible_item`，`item/started` 与 `rawResponseItem/completed` 两条路径），不能只过滤落盘。只过滤落盘时实时聊天会多出两条没有历史对应的孤儿用户气泡，各自开出一个「耗时 0 秒」的假回合，重进页面读同一份已过滤的 `project.jsonl` 又恢复正常；判据是 `direct_project_turn_does_not_forward_codex_user_echo_as_chat_items`（回合事件里只能有一条 `direct-codex:{clientTurnId}:user` 用户条目）。
 - 本地 AGC user-item 写入必须使用允许 user item 的内部入口，Codex raw item 写入使用过滤入口，避免“过滤回显”反过来阻断预写。相同 `clientTurnId` 只能复用相同规范化 prompt，内容冲突必须失败关闭。
 
 ## 2026-08-31 AGC 错误报告与诊断上传

docs/project-memory/shared-memory/pitfalls.md

@@ -27,10 +27,6 @@ Vite 默认监听应用根下的 Rust `src-tauri/target`，构建产物较多时
 - **原因**：这个 shell 以管理员身份运行，`New-Item` / `tempfile` 新建目录的 owner 是 `BUILTIN\Administrators`，而 AGC 的校验要求 owner 等于当前用户 SID（`KDLETTERS\<user>`）。`Get-Acl <path> | Select Owner` 与 `whoami` 一比就能定性；同一台机器上由客户端自己创建的目录 owner 正确，所以「客户端自己建的项目能用、手建的不能用」。
 - **处理**：手工夹具先 `icacls <path> /setowner "<DOMAIN>\<user>" /T`；Rust 用例改用工程自带的 `crate::tests::canonical_test_tempdir(prefix)`（它会 canonicalize 并重置目录 owner），不要直接用 `tempfile::tempdir()`。判「用例失败与本改动无关」时，先确认失败信息是不是这一条。
 
-## DirectProject 历史不能按工具条目切页再按消息推进游标
-
-原始 `response_item` 历史同时含用户/助手消息、推理与工具输出。若原生每次取 20 个原始条目、前端过滤聊天消息后再找最旧 ID，纯工具页会让消息集合为空且游标不动，看起来历史丢失。聊天读取固定显式请求 `messagesOnly: true`，原生逐行过滤后按消息分页并返回 `oldestItemId`；默认原始模式留给原始条目消费者。无 ID 旧消息保留并扩展到可寻址边界，不能造 ID。前端保留项目与读取代次、单飞及 ID 去重，旧请求的成功、失败与 finally 都不能覆盖新读取；真实日志只在临时目录只读重放，不能提交正文夹具。
-
 ## JSON 卡片显示与 UI 编辑能力必须同源
 
 JSON 的文本读取分支不等于卡面应该展示原始 State 摘要。卡片、缩略图及编辑器入口共同消费受控文本预览的 `uiDesignAssetId`；只有原生复用 UI 持久化合同校验 schema、完整 State 和项目/资产身份后才设置它。普通 JSON 保留 JSON 代码预览，不按 `kind: UI/ui` 或 schema 字符串片段猜测编辑能力。已有合法 UI State 的加载/保存不依赖 kind 精确大小写，但新建初始化仍保留正式 UI 资产门禁；缓存与项目切换须保留现有身份隔离。
@@ -5695,10 +5691,17 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 
 - **现象**：在 `apps/ai-game-creator-shell/src-tauri` 跑过 `cargo test` 之后，`npm run ai-game-creator-shell:typecheck` 报 10 条类型错（`src/features/project-workspace/resourceReferences.ts:106-112` 的 `string | undefined` 不能赋给 `string | null`；同文件 134 行的对象字面量带 `type: 'message'`，而 `DirectCodexUserMessageItem` 里没有该字段），`npm run ai-game-creator-shell:build` 也死在 `beforeBuildCommand` 的同一条 typecheck 上。
 - **原因**：crate 里的 ts-rs 导出会按**本机依赖版本**重写 `src/features/project-workspace/generated/DirectCodexUser*.ts`：注释头变成 "This file was generated…"、字符串改双引号、`DirectCodexUserMessageItem` 丢掉 `type: 'message'` 判别字段、并多出一个 `DirectCodexUserMessageEnvelope.ts`。仓库里提交的那份是前端真正依赖的形状（前端按带 `type` 的判别联合写），重写后两边就对不上——错在生成器版本漂移，不在前端。
-- **处理（现行口径）**：不要把重写结果当改动提交。跑过 `cargo test` 或构建后先 `git checkout -- apps/ai-game-creator-shell/src/features/project-workspace/generated`，再删掉多出来的 `DirectCodexUserMessageEnvelope.ts`，然后才做 typecheck / 打包；绑定与前端形状冲突时以**已提交的绑定 + 前端**为基准排查。
-- **验证**：恢复提交版本后 `npm run ai-game-creator-shell:typecheck` exit 0（`[skill-pack] OK`）；保留重写结果时同一条命令 exit 2。release 构建本身还会在 `src/features/ui-editor/types/` 落下 `BindingChange.ts` / `BindingDTO.ts` 两个无人引用的未跟踪文件，属同类生成产物。
+- **处理（现行口径）**：不要把重写结果当改动提交。跑过 `cargo test` 或构建后只恢复 `apps/ai-game-creator-shell/src/features/project-workspace/generated/DirectCodexUser*.ts` 的仓库版本，再删掉多出来的 `DirectCodexUserMessageEnvelope.ts`；不要恢复整个 `generated/` 目录，以免误删 DirectThread 的现役绑定。绑定与前端形状冲突时以**已提交的 DirectCodexUser 绑定 + 前端**为基准排查。
+- **验证**：恢复仓库版本后 `npm run ai-game-creator-shell:typecheck` exit 0（`[skill-pack] OK`）；保留重写结果时同一条命令 exit 2。release 构建本身还会在 `src/features/ui-editor/types/` 落下 `BindingChange.ts` / `BindingDTO.ts` 两个无人引用的生成产物；它们不属于前端契约，发现后直接删除，不提交。
 - **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/direct_codex_user_item/`（ts-rs 导出源）、`apps/ai-game-creator-shell/src/features/project-workspace/resourceReferences.ts`、`apps/ai-game-creator-shell/scripts/build-release.mjs`（`beforeBuildCommand`）。
 
+## 2026-09-16 Node 26 下 vitest 的 jsdom 用例拿不到 window.localStorage
+
+- **现象**：只声明 `@vitest-environment jsdom` 的用例里 `window.localStorage` 是 `undefined`（典型报错 `Cannot read properties of undefined (reading 'clear')`）；而 `appSurface.test.ts` 里同样访问 `window.localStorage` 却一切正常。
+- **原因（已核对，不是推断）**：Node 26 在 `globalThis` 上定义了实验性 `localStorage` 访问器，不传 `--localstorage-file` 时它返回 `undefined`。vitest 0.34 的 jsdom 环境把 jsdom window 的描述符复制到全局时，不会覆盖 `globalThis` 上已存在的键，于是 jsdom 真正的 `Storage` 被 Node 的 `undefined` 顶掉。`appSurface` 之所以不受影响，是因为 `apps/ai-game-creator-shell/tests/appSurface/harness.ts` 自己用 `Object.defineProperty(window, 'localStorage', …)` 挂了内存实现。
+- **处理**：跑这类用例时给 Node 加 `--localstorage-file`，例如 `NODE_OPTIONS="--localstorage-file=/tmp/vitest-node-localstorage" npx vitest run <files>`；`apps/ai-game-creator-shell/tests/clientApi.test.ts` 与 `chatPromptPolish.test.tsx` 加这个开关后 26 项全绿。不要改业务代码或往测试里塞假 storage 来绕过。
+- **关联**：`vitest.config.ts`（`environment: 'node'` + 用例内 docblock 切 jsdom）、`apps/ai-game-creator-shell/tests/appSurface/harness.ts` 的内存 localStorage 垫片。
+
 ## 2026-09-17 AGC 壳首页无限 setState：effect 依赖了每次渲染都换身份的普通函数
 
 - **现象**：dev 客户端停在首页、不点任何东西也会持续刷 `WEBVIEW error webview: Maximum update depth exceeded …`（5 秒涨 ~8.5 KB 日志），对应 WebView2 renderer 工作集涨到 **4.2 GB**、CPU 持续累计（约 0.7–1.5 核）；表现上很像"模板库卡片太多/滚动卡"，实际与页面内容无关。