退役 DirectProject 工具调用与回合流账本

- agent/direct_tool_calls.rs、agent/direct_turn_stream.rs：整体删除，agent.rs 去掉模块声明与导出 - direct_runtime/mod.rs：删 DirectToolCallCollector、回合流节流器与全部落盘/发射调用点，observer 只回填 update_active_turn - codex_app_server/mod.rs：删 DirectCodexTurnObservation::ToolCall，AgentMessageSegment 结构体变体简化为元组变体，direct_tool_call_turn_id / direct_tool_call_now_ms 改名 - claude_code_cli.rs：删 tool_use / tool_result 采集分支与 DirectToolCall 构造 - main.rs、runtime_driver/entrypoints.rs：删 GameCreatorDirectTurnUpdateEvent 与 game-creator-direct-turn-update 事件，emit 收缩为 (status, activity) - thread_manager/wire.rs：新增 direct_now_ms，替代随 direct_tool_calls 删除的时钟函数 - docs：ADR、工具调用卡片技术方案、DirectProject 聊天真相源收敛里程碑与实施计划、pitfalls 旧路径同步到当前状态，decision-log 新增 2026-09-30 退役条目 - 未修（另开）：redact_absolute_path_tokens 的无语境绝对路径扫描仍会误伤 HTML 结束标签与嵌套 JSON 转义 - 验证：cargo test --bin genarrative-ai-game-creator-shell agent::（929 passed / 0 failed / 5 ignored）、npm run check:encoding、npm run check:doc-index、git diff --check
2026-09-30 19:32:05 +08:00
parent 9ee34809be
commit 719db293d2
18 changed files with 328 additions and 2545 deletions
@@ -10,7 +10,7 @@

 ## 背景

-AGC 项目开发聊天框当前同时从三处取数据：Direct 回合事件（实时）、`turn-stream.jsonl`（文本段与工具交替顺序）、`tool-calls.jsonl`（已脱敏工具卡片），重进页面时还要额外接管活动回合快照。同一段文本和同一张工具卡片因此存在多个来源，实时与回读会互相覆盖，恢复路径也只能靠"哪个源先到"决定。
+AGC 项目开发聊天框当前同时从多处取数据：Direct 回合事件（实时）、另一份按顺序重建的回合投影、以及按读取期另算的工具卡片，重进页面时还要额外接管活动回合快照。同一段文本和同一张工具卡片因此存在多个来源，实时与回读会互相覆盖，恢复路径也只能靠"哪个源先到"决定。

 `.agent/conversations/project.jsonl` 里的 Codex 原始条目本身已经带着顺序（`function_call` 与 `function_call_output` 按写入顺序落行），顺序信息并不是协议缺陷，而是在投影层被丢弃。

@@ -18,10 +18,10 @@ AGC 项目开发聊天框当前同时从三处取数据：Direct 回合事件（

 - AGC 项目开发对话的持久事实源只有 **项目对话历史**（`.agent/conversations/project.jsonl` 的原始条目）；消息文本、工具卡片和它们的先后顺序都从它派生。
 - 运行期间的回合状态只来自 **运行态事件**（Thread Manager 的 subscribe / consume / notify）；`notify` 只做唤醒，不携带状态。
- **聊天投影** 在读取与渲染时生成，不落盘、不成为第二事实源；DirectProject 聊天框停止读取 `turn-stream.jsonl` 与 `tool-calls.jsonl`，也不再提供供前端读取的命令。DirectRuntime 自己那套进度事件与文件写入属于运行时账本，本轮保留不动。
+- **聊天投影** 在读取与渲染时生成，不落盘、不成为第二事实源；聊天视图只由项目对话历史与运行态事件驱动，不再有供前端读取的旁路命令。
 - 页面重进的运行态只由 `subscribe` 的 bootstrap 事件重建，删除活动回合快照接管路径。
 - 可见性判断留在前端聊天投影：后端历史分页只按原始条目切片，前端自己跳过不可显示条目并推进锚点。
- 线上模型是 **ts-rs 导出的 tagged enum**（`agent/direct_thread_wire.rs`），不是"一个大结构体加一堆可空字段"：`DirectThreadItem` 用 `itemType` 区分条目，`DirectThreadEvent` 用 `type` 区分事件，前端直接消费生成的 TS 类型（改完 Rust 模型跑 `cargo test export_bindings`）。条目上的毫秒时间戳标 `#[ts(as = "f64")]`，因为 ts-rs 默认把 `u64` 映射成 `bigint`，而 Tauri 的 JSON 通道传的是 `number`。
+- 线上模型是 **ts-rs 导出的 tagged enum**（`agent/thread_manager/wire.rs`），不是"一个大结构体加一堆可空字段"：`ThreadItem` 用 `itemType` 区分条目，`ThreadEvent` 用 `type` 区分事件，前端直接消费生成的 TS 类型（改完 Rust 模型跑 `cargo test export_bindings`）。条目上的毫秒时间戳标 `#[ts(as = "f64")]`，因为 ts-rs 默认把 `u64` 映射成 `bigint`，而 Tauri 的 JSON 通道传的是 `number`。
 - 运行态事件与历史切片使用同形条目，Rust 在两侧套同一套安全过滤（脱敏、截断、路径归一），前端只有一个「原始条目 → 视图」投影函数。
 - 两侧的过滤口径必须完全一致，包含「哪些条目根本不是本项目的聊天条目」：Codex app-server 回显的用户消息（`userMessage` / 非 AGC 的 `role=user`）在落盘侧被过滤，在运行态事件侧也必须被过滤（`direct_thread_visible_item`）。少一侧就会出现「实时比历史多出两条同文本用户条目、各自开出一个耗时 0 秒的假回合，重进页面又正常」这类只有其中一侧的事实源缺陷。
 - 搬运层不生成展示形状：Thread Manager 只下发脱敏原始条目（`itemType` 原样透传），工具卡片的 `kind`、标题、折叠摘要都由前端生成。
@@ -43,7 +43,7 @@ AGC 项目开发聊天框当前同时从三处取数据：Direct 回合事件（
 - 思考正文以 `item.delta{kind:"reasoning"}` 流式下发（`item/reasoning/summaryTextDelta` 与 `item/reasoning/textDelta`）。这不放宽可见范围：同一段文本本来就已落进 `project.jsonl` 并在 `item.completed` 展示；plan 文本与命令输出仍只降级为活动状态。
 - 首屏历史由 `subscribe` 返回的 `lastCompletedItemId` 锚定，再取最近切片；删除返回整份对话的历史命令。锚点是切片**新端（较新一侧）的边界且含该条**（命令参数 `throughItemId`）：比锚点更新的条目只从运行态事件来，历史切片与实时流因此不重叠；向后翻页仍用切片返回的 `firstItemId` 作为 `beforeItemId`（不含锚点）。订阅回执到达之前不读首屏，也不退化成"取文件尾"（那会把回执之后才完成的条目也拉进历史）。
 - 生命周期锚点独立于 replay 队列保存（队列会回收 `cleanable` 事件，新订阅的游标又在队尾，回收后无法反推"最新回合是 started 还是 completed"），`subscribe` 必须返回最新的一条 `turn.started` / `turn.completed`，否则新订阅无法判定回合是否仍在运行。
- 前端工具卡片形状是 `Omit<GameCreatorDirectToolCall, 'turnId'>`：聊天卡片不再有回合身份，`tool-calls.jsonl` 的持久化形状仍保留 `turnId`（DirectRuntime 的账本没动）。
+- 前端工具卡片形状是 `Omit<GameCreatorDirectToolCall, 'turnId'>`：聊天卡片不再有回合身份。
 - 未识别 item 类型由 Rust 原样透传（只带类型与身份，Rust 侧留 TODO），当前由前端投影丢弃：哪些类型可见属于前端决策，不回 Rust 加白名单。
 - 删除范围包含前端对 `read_direct_turn_stream`、`read_direct_tool_calls`、`read_direct_project_history`（整份历史）与 `game-creator-direct-turn-update` 事件的调用；保留分页用的历史切片读取（`read_direct_project_history_slice`），且该切片从文件尾反向扫描。`list_game_creator_direct_active_turns` 有意保留：它服务首页跨页面的「运行中的项目」列表，不是聊天框读路径。
 - 前端删掉 `directTurnStream` / `directToolCalls` / 活动回合快照接管 / 瞬时应答文本这些并行状态，聊天视图只由 reducer 状态投影（含工具卡片）。
@@ -53,13 +53,12 @@ AGC 项目开发聊天框当前同时从三处取数据：Direct 回合事件（

 ## 备选方案与取舍

-1. **保留 `tool-calls.jsonl` 作为"读侧已脱敏"缓存**：省一次脱敏与截断，但它成为与项目对话历史并行的第二事实源，卡片状态与顺序会和实时事件分叉。选择按读取期投影，必要时在进程内缓存。
+1. **保留一份"读侧已脱敏"的持久缓存**：省一次脱敏与截断，但它会成为与项目对话历史并行的第二事实源，卡片状态与顺序会和实时事件分叉。选择按读取期投影，必要时在进程内缓存。
 2. **保留 Direct 回合事件作为实时传输**：迁移量小，但同一段文本仍有两条实时链路，reducer 必须处理互相覆盖，正是本次要消除的问题。
 3. **让后端分页按"可显示消息数"切片**：界面能少写循环，代价是 Rust 需要理解 UI 可见性，界面规则一变就要同步改后端。

 ## 影响

- 旧项目磁盘上遗留的 `turn-stream.jsonl` / `tool-calls.jsonl` 保留不动，不迁移、不清理、不再由 DirectProject 聊天框读取。
 - 工具卡片的脱敏与截断必须在读取期执行一次，不能因为"原始条目已在磁盘"就把未脱敏内容直接渲染到界面。
 - 回合结束语义务必由 `turn.completed` 判定（失败时同一事件带 `failure` 载荷，不新增事件类型）；缺少该事件的残留回合不得被渲染成运行中。
 - 两条已知边界，都**不**在本次补路径，且已被 [`【ADR】DirectProject命令接单化-2026-09-23`](./【ADR】DirectProject命令接单化-2026-09-23.md) 取代（§3、§2）：① 宿主进程被强杀（`kill -9`）时没有任何 `Drop` 会执行，但队列随进程消失，新进程的订阅 bootstrap 因此不会看到"有开始没结束"，界面不会卡在忙碌态；② `turn.started` 之前的失败按发生位置分流——接单**之前**的是拒单，根本不产生回合（不写用户条目、不写失败诊断），接单**之后**的由这一轮的占用对象统一收口成 `turn.completed`，不存在"有回合却没有事件解释"的路径。
@@ -69,5 +68,5 @@ AGC 项目开发聊天框当前同时从三处取数据：Direct 回合事件（
 - **调用级拒绝**（同一 `clientTurnId` 并发复用 / 项目已有另一条回合在跑 / 权限策略拒绝 / 目录锚不定 / 输入校验 / 环境与凭据未就绪）不属于回合失败：这一轮没有开始，只把原因回给命令边界（界面出运行错误横幅），不写失败诊断、不发 `failed` 事件、不进交付报告。此前它们与回合失败混在同一层、共用同一份错误文本，现在分流只认 typed 判据。
 - 「活动回合的唯一判据」约束的是**原生回合**：界面上的「本地已发出、原生还没认领」是投影的展示态（`DirectChatTurn.state = 'awaiting-start'`），由本地在途用户条目身份派生，不构成第二套原生生命周期，也不参与 `turnRunning` 的判定。
 - 三层数据流、变量归属与一次发送的时序写在代码里：`apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectChatController.ts` 的模块注释；回合三态的定义与判据真值表在 `apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directTurnPresentation.ts` 的 `DirectChatTurnState`。改判据时同步这两处与对应测试。
- 验收证据是端到端行为，不是单元测试：回合进行中杀掉应用进程后重开项目，应看到部分文本与工具卡片按原顺序出现且不显示忙碌；正常结束后重进应与实时渲染一致；文件系统不得再新增 `turn-stream.jsonl` / `tool-calls.jsonl`。
+- 验收证据是端到端行为，不是单元测试：回合进行中杀掉应用进程后重开项目，应看到部分文本与工具卡片按原顺序出现且不显示忙碌；正常结束后重进应与实时渲染一致。
 - id 空间已用源码核对：codex-rs `app-server-protocol/src/protocol/thread_history.rs` 中所有工具 item 都是 `id: payload.call_id.clone()`，而 `project.jsonl` 落盘的是原始 response item。真实 app-server 会话核对仍列为运行时验收项。