文档先行：定死 DirectProject 历史分页连拉的可见性口径
把「可显示」判据明确为合并后聊天投影出现新回合，并写清每操作 5 页上限与锚点不前进即停 里程碑把原第 56 条按后端锚点回扫与前端连拉拆成两条独立验收项，前端那条先留待补证据 实施计划第 6 步同步口径，并把新分页单测加入验证命令 决策记录新增 2026-09-17 条目，记下落点、上限粒度、失败与竞态边界
This commit is contained in:
@@ -19,7 +19,7 @@
|
||||
3. 删掉回合身份：`turn.started` 无载荷、`turn.completed{status}`，条目 / 增量 / 请求 / 生命周期锚点都不带 turn id；队列 `append` 直接收 `DirectThreadEvent`，`seq` 内部自算。
|
||||
4. 思考正文流式：`item/reasoning/summaryTextDelta` 与 `item/reasoning/textDelta` 产出 `item.delta{kind:"reasoning"}`；plan 文本与命令输出保持活动状态。
|
||||
5. 前端收敛为单一 reducer：`subscribe` 返回的 bootstrap 事件就是已暂存的运行态，游标已经在队尾，前端直接 reduce 这批事件即可（不需要为了拿这批事件再补一次 `consume`）；此后只由 notify 唤醒 `consume`。唯一例外是回执竞态：Rust 注册完 subscriber 就开始通知，而前端要等回执才知道 `subscriptionId`，这段时间到达的通知只能记欠账，回执到达后立刻补一次 `consume`（否则整轮最后一个事件之后可能再无通知，事件会卡死在队列里）。合并规则只保留"先到定形、后到补空白"（正文只增不减、工具状态允许从 running 升级到终态），`item.delta` 直接追加到运行态条目正文，删掉 `deltaText` 缓冲，`turn.completed` 把运行态条目并入历史再清空。
|
||||
6. 首屏与分页：以 `lastCompletedItemId` 为锚点取最近切片，历史读取改为从文件尾反向扫描；锚点按原始 item id 推进，切片无可见条目时自动连拉（上限 5 页）。
|
||||
6. 首屏与分页：以 `lastCompletedItemId` 为锚点取最近切片，历史读取改为从文件尾反向扫描；锚点按原始 item id 推进；一次翻页操作在前端连拉，直到合并后聊天投影出现新回合（新的用户气泡）或 `hasMore=false`，每个操作上限 5 页；锚点未推进（`items` 为空 / `firstItemId` 为 null / 与请求锚点相同）时立即停止。可见性口径只在 `features/project-workspace/directHistoryPaging.ts` 实现一份，首屏与「显示更早」共用。
|
||||
7. App.tsx 接线：订阅 + 立即 reduce bootstrap + notify 唤醒 consume，聊天视图改由 reducer 状态投影（含工具卡片），删除 Direct 回合事件订阅与 `directTurnStream` / `directToolCalls` 状态。
|
||||
8. 删除只服务旧读路径的命令与前端调用（`read_direct_project_history`、`read_direct_turn_stream`、`read_direct_tool_calls`），DirectRuntime 自己的写入保留。`list_game_creator_direct_active_turns` 是唯一的例外并有意保留：它服务首页跨页面的「运行中的项目」列表（`WorkspaceLauncher` / `directActiveTurns.ts`），不是聊天框读路径。
|
||||
9. 测试与文档收口：补 reducer 单测、解锁跳过的工具卡片用例、更新主规范并把冲突的实施计划与工具卡片文档改写为当前状态。
|
||||
@@ -28,7 +28,7 @@
|
||||
|
||||
1. `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml direct_thread -- --nocapture`
|
||||
2. `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml export_bindings`（生成 `src/features/project-workspace/generated/`），随后用 `prettier --write` 格式化生成目录，避免未格式化的 ts-rs 输出混进提交
|
||||
3. `npx vitest run apps/ai-game-creator-shell/tests/directThreadChat.test.ts apps/ai-game-creator-shell/tests/directTurnPresentation.test.ts`
|
||||
3. `npx vitest run apps/ai-game-creator-shell/tests/directThreadChat.test.ts apps/ai-game-creator-shell/tests/directTurnPresentation.test.ts apps/ai-game-creator-shell/tests/directHistoryPaging.test.ts`
|
||||
4. `npx vitest run apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`
|
||||
5. TypeScript 类型检查与 ESLint（范围同前次 DirectProject 迁移）。
|
||||
6. `npm run check:encoding`、`npm run check:doc-index`、`git diff --check`
|
||||
|
||||
@@ -19,7 +19,7 @@ AGC 项目开发对话的显示与恢复只依赖两项输入：**项目对话
|
||||
- 线上模型与提示词同源：条目与事件是 ts-rs 导出的 tagged enum，前端消费生成绑定（改 Rust 模型后跑 `cargo test export_bindings`）；毫秒时间戳用 `#[ts(as = "f64")]` 对齐 Tauri JSON 通道的 `number`。
|
||||
- 条目身份归一：进队列前收敛成一个 `itemId`（工具条目在 `project.jsonl` 里带调用 id 与 response item id 两个值）；历史切片另给 `firstItemId` 作为分页锚点，锚点始终是文件里的原始 item id。
|
||||
- 思考正文流式：`item/reasoning/summaryTextDelta` 与 `item/reasoning/textDelta` 以 `item.delta{kind:"reasoning"}` 下发正文；plan 文本与命令输出仍只降级为活动状态。
|
||||
- 历史读取以 `subscribe` 返回的 `lastCompletedItemId` 为首屏锚点，切片从**文件尾反向扫描**；不可显示条目由前端跳过并继续取页（上限 5 页）。
|
||||
- 历史读取以 `subscribe` 返回的 `lastCompletedItemId` 为首屏锚点，切片从**文件尾反向扫描**；后端切片只按原始条目切片，可见性判断留在前端聊天投影；一次翻页操作在前端连拉取页，直到合并后聊天投影出现新回合或 `hasMore=false`，每个操作上限 5 页。
|
||||
- 前端收敛为单一事件 reducer 与单一聊天投影；活动回合只由 `turn.started` 与 `turn.completed` 判定（事件不带 turn id，前端只有一个 `turnRunning` 布尔）；`item.delta` 直接追加到运行态条目正文，不保留增量缓冲；`turn.completed` 把该回合运行态条目并入历史再清空。
|
||||
- 删除前端对 Direct 回合事件、`turn-stream.jsonl`、`tool-calls.jsonl`、活动回合快照的读取，以及只服务这些读取的命令与状态。
|
||||
|
||||
@@ -41,6 +41,7 @@ AGC 项目开发对话的显示与恢复只依赖两项输入：**项目对话
|
||||
- 失败与中止说明只在运行期显示（不写 `project.jsonl`），页面重进后不再出现。
|
||||
- 未知 item 类型由 Rust 原样透传（只有类型与身份，Rust 侧留 TODO），当前由前端投影丢弃。
|
||||
- 前端聊天卡片的工具形状是 `Omit<GameCreatorDirectToolCall, 'turnId'>`；`tool-calls.jsonl` 的持久化形状与 DirectRuntime 的写入保持不变。
|
||||
- 「可显示」的判据取**前端回合反馈**：一次翻页操作连拉到「合并后聊天投影的回合数增加」为止。工具卡片与思考文本虽然能通过 `projectDirectThreadItem`，但可能整页落进已渲染回合的折叠「执行过程」，不构成用户可见反馈；口径只在 `directHistoryPaging.ts` 里实现一份，首屏与「显示更早」共用。
|
||||
|
||||
## 依赖与前置条件
|
||||
|
||||
@@ -53,7 +54,8 @@ AGC 项目开发对话的显示与恢复只依赖两项输入：**项目对话
|
||||
- [x] 一次回合内，实时渲染的文本段与工具卡片顺序，与回合结束后重进项目看到的顺序一致。【自动化：`project-development.suite.ts` 空对话首轮 + 历史切片工具卡片用例】
|
||||
- [ ] 回合进行中终止并重启进程后重进项目：已落盘的部分文本与工具卡片按原顺序出现，且界面不显示忙碌态。【待真实 app-server 运行时验收】
|
||||
- [ ] 进程存活期间的页面重进（含切走再切回）能恢复运行中回合，并允许终止。【待真实 app-server 运行时验收】
|
||||
- [x] 历史分页在切片内全部是不可显示条目时仍能继续向前，不出现锚点停滞。【自动化：`direct_project_history` 尾部回扫与分页锚点用例】
|
||||
- [x] 历史切片从文件尾反向回扫，锚点始终是文件里的原始 item id；切片内全部是不可显示条目时仍能继续向前，不出现锚点停滞。【自动化：`direct_project_history` 尾部回扫与分页锚点用例】
|
||||
- [ ] 前端一次翻页操作自动连拉，直到合并后聊天投影出现新回合或 `hasMore=false`，每个操作上限 5 页；锚点不前进时立即停止，不空转。【待补：`directHistoryPaging` 单测 + `project-development.suite.ts` 跨页同回合用例】
|
||||
- [x] 聊天视图不再读取 `turn-stream.jsonl` / `tool-calls.jsonl` / Direct 回合事件 / 活动回合快照；`read_direct_turn_stream` 与 `read_direct_tool_calls` 命令已删除。`list_game_creator_direct_active_turns` **有意保留**：它服务首页跨页面的「运行中的项目」列表（`WorkspaceLauncher` / `directActiveTurns.ts`），不属于聊天框读路径。
|
||||
- [x] 同一工具调用在实时与回读各只出现一张卡片（两个 id 空间按归一后的 `itemId` 对齐）。【自动化：reducer「先到定形、后到补空」合并单测 + 工具卡片渲染用例】
|
||||
- [x] 前端聊天状态里不再出现第二个 id 概念与任何回合身份字段；事件解析统一来自 ts-rs 生成绑定。【自动化：`directThreadChat` / `directTurnPresentation` 单测 + `cargo test export_bindings` 生成绑定无差异】
|
||||
|
||||
@@ -2,6 +2,16 @@
|
||||
|
||||
> 用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。
|
||||
> 当前口径：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据；如与当前代码或 `docs/README.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` 单测覆盖口径、上限、`hasMore=false` 早停、锚点不前进、单页失败；`project-development.suite.ts` 新增「跨页同回合」集成用例作为真实回归网。
|
||||
|
||||
## 2026-09-16 图标图集自动拆图上限提高到 256
|
||||
|
||||
- 背景：AGC 图标图集自动连通域识别在一次生成中识别出 86 个区域，原有 64 片上限在后处理阶段阻断了请求；该上限同时影响 api-server 自动 / 手动切片、SpacetimeDB 批量落库和统一生成结果 item 数量。
|
||||
|
||||
Reference in New Issue
Block a user