diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/DirectProjectChatView.tsx b/apps/ai-game-creator-shell/src/view/project-development/chat/DirectProjectChatView.tsx index 839b37053..0cd590b95 100644 --- a/apps/ai-game-creator-shell/src/view/project-development/chat/DirectProjectChatView.tsx +++ b/apps/ai-game-creator-shell/src/view/project-development/chat/DirectProjectChatView.tsx @@ -1,6 +1,12 @@ import type { UIEventHandler } from 'react'; import type { Ref } from 'react'; -import { useEffect, useImperativeHandle, useRef, useState } from 'react'; +import { + useEffect, + useImperativeHandle, + useMemo, + useRef, + useState, +} from 'react'; import { AGENT_CHAT_SCROLL_BOTTOM_THRESHOLD } from '../../../app/constants'; import { claimInitialTurnForPage } from '../../../app/initialTurnClaims'; @@ -18,6 +24,7 @@ import { useDirectProjectChatController, } from './controller/useDirectProjectChatController'; import { useDirectProjectManifest } from './controller/useDirectProjectManifest'; +import { useDirectProjectTurnStatus } from './controller/useDirectProjectTurnStatus'; import { createDirectProjectTurnId, directCodexConversationMessageId, @@ -122,6 +129,7 @@ export function DirectProjectChatView({ historyHasMore, loadEarlierHistory, localMessages, + pendingUserItemId, queuedTurns, removeAttachment, startInitialTurn, @@ -131,7 +139,27 @@ export function DirectProjectChatView({ turnCancelling, uploadFiles, } = chat; - const busy = turnBusy || directTurnRunning; + // 这份投影要参与下游 memo 的判据，必须自己先缓存：不缓存的话每次渲染都是一份新数组， + // `useDirectProjectTurnStatus` 里以 `turns` 为判据的 `useMemo` 永远命中不了，那层 memo + // 就成了死代码，读代码的人还会误以为 `turnStatus` 是引用稳定的。 + const directTurns = useMemo( + () => + buildDirectChatTurns({ + entries: directEntries, + localMessages, + turnRunning: directTurnRunning, + pendingUserItemId, + }), + [directEntries, localMessages, directTurnRunning, pendingUserItemId], + ); + // 「这一轮在跑吗」只从这一个派生入口读：原生真相 / 本地命令在飞 / 最新一轮三态。 + const turnStatus = useDirectProjectTurnStatus({ + turnRunning: directTurnRunning, + turnBusy, + turns: directTurns, + }); + const activeTurnStartedAt = + directTurns.find((turn) => turn.state === 'running')?.startedAt ?? 0; const statusText = runtimeNotice || statusNotice || @@ -144,7 +172,7 @@ export function DirectProjectChatView({ return; if (projectPath !== initialTurn.projectPath) return; // projectId 来自项目清单：清单还没到位时不能先认领，否则首轮需求会被空项目吃掉。 - if (!projectId || busy) return; + if (!projectId || turnStatus.displayBusy) return; if ( !claimInitialTurnForPage(initialTurn.projectPath, initialTurn.claimScope) ) { @@ -165,9 +193,9 @@ export function DirectProjectChatView({ : {}), userItem, }); - // 首轮需求只由入口 payload、项目身份、清单就绪和回合态驱动。 + // 首轮需求只由入口 payload、项目身份、清单就绪和回合忙态驱动。 // eslint-disable-next-line react-hooks/exhaustive-deps - }, [busy, initialTurn, projectId, projectPath]); + }, [turnStatus.displayBusy, initialTurn, projectId, projectPath]); useEffect(() => { if (!shouldFollowLatestRef.current) return; @@ -175,14 +203,6 @@ export function DirectProjectChatView({ if (list) list.scrollTop = list.scrollHeight; }, [directEntries, localMessages]); - const directTurns = buildDirectChatTurns({ - entries: directEntries, - localMessages, - turnRunning: directTurnRunning, - }); - const activeTurnStartedAt = - directTurns.find((turn) => turn.active)?.startedAt ?? 0; - useImperativeHandle(ref, () => ({ announce: (text: string) => { appendLocalMessage({ role: 'assistant', text, updatedAt: Date.now() }); @@ -206,7 +226,7 @@ export function DirectProjectChatView({ >
setSettingsOpen(true)} /> @@ -214,7 +234,7 @@ export function DirectProjectChatView({ turns={directTurns} messagesRef={messagesRef} historyHasMore={historyHasMore} - running={directTurnRunning} + nativeRunning={turnStatus.nativeRunning} activeTurnStartedAt={activeTurnStartedAt} onLoadEarlierHistory={() => void loadEarlierHistory()} onScroll={handleScroll} @@ -227,7 +247,7 @@ export function DirectProjectChatView({ attachmentNotice={attachmentNotice} queuedTurns={queuedTurns} composerNotice={composerNotice} - busy={busy} + busy={turnStatus.displayBusy} turnCancelling={turnCancelling} onCancelQueuedTurn={cancelQueuedTurn} onCancelTurn={() => void cancelTurn()} diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectConversation/DirectProjectConversation.tsx b/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectConversation/DirectProjectConversation.tsx index b982c84ae..fec7a00e4 100644 --- a/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectConversation/DirectProjectConversation.tsx +++ b/apps/ai-game-creator-shell/src/view/project-development/chat/components/DirectProjectConversation/DirectProjectConversation.tsx @@ -19,7 +19,7 @@ export function DirectProjectConversation({ turns, messagesRef, historyHasMore, - running, + nativeRunning, activeTurnStartedAt, onLoadEarlierHistory, onScroll, @@ -27,7 +27,11 @@ export function DirectProjectConversation({ turns: DirectChatTurn[]; messagesRef: RefObject; historyHasMore: boolean; - running: boolean; + /** + * 原生回合是否在跑（reducer 的 `turnRunning`）：只决定这张"正在处理"卡片。 + * 本地命令在飞但原生还没认领的窗口见 `DirectProjectTurnStatus`。 + */ + nativeRunning: boolean; activeTurnStartedAt: number; onLoadEarlierHistory: () => void; onScroll: UIEventHandler; @@ -53,7 +57,7 @@ export function DirectProjectConversation({ ))}
- {running ? ( + {nativeRunning ? ( block.kind === 'assistant') - ?.key ?? null) - : null; + const streamingKey = + turn.state === 'running' + ? ([...turn.process].reverse().find((block) => block.kind === 'assistant') + ?.key ?? null) + : null; return ( {turn.users.map((block) => @@ -48,7 +56,7 @@ function renderTurnProcess(turn: DirectChatTurn, streamingKey: string | null) { const blocks = turn.process.map((block) => renderBlock(turn, block, 'process', streamingKey), ); - if (turn.active) return blocks; + if (turn.state !== 'finished') return blocks; return (
执行过程 @@ -58,7 +66,14 @@ function renderTurnProcess(turn: DirectChatTurn, streamingKey: string | null) { } function DirectProjectTurnUsage({ turn }: { turn: DirectChatTurn }) { - if (turn.active || !turn.startedAt) return null; + // 否定式判据：未结束的回合不显示终态文案。`awaiting-start` 走这一条，所以"本地已发出、 + // 原生还没认领"的窗口里不会再出现「本轮结束于 … 耗时 0.0秒」。 + // 仍未修的另一半（A）：`finished` 但没有可证明终态时间的回合，会被下面的 `Math.max` 兜底 + // 量化成 0.0 秒，共两类——① 重进项目后读回来的历史回合（`turnEndedAt` 只活在本次会话里， + // 不会随 `project.jsonl` 持久化）；② 本地已发出却一个原生事件都没产生的回合（发送失败）。 + // 修法是只在 `turn.endedAt > 0` 时渲染终态文案、耗时改由 `turnTotalDurationMs()` 出（边界缺失 + // 就隐藏），属于产品口径变化（宁可隐藏也不编），确认后单独改；改完把这半段注释删掉。 + if (turn.state !== 'finished' || !turn.startedAt) return null; const endedAt = Math.max(turn.endedAt, turn.startedAt); return (

); diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectChatController.ts b/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectChatController.ts index d368e8bb5..58ff19116 100644 --- a/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectChatController.ts +++ b/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectChatController.ts @@ -91,6 +91,56 @@ export type DirectProjectChatControllerProps = { * * 订阅、首屏锚点与历史分页、发送与 FIFO 队列、附件、终止、草稿和本地消息都归这里； * 工作台壳只注入项目上下文与两条权限门，不再持有 Direct 专属 state/ref/effect。 + * + * ## 数据流（改判据前先读这一段） + * + * ``` + * Rust 宿主（事实的产生地） + * ├─ project.jsonl 持久化原始条目（AGC 写；app-server 回显的用户消息被过滤） + * └─ Thread Manager 事件队列（内存） per-thread 事件序列 + 每 subscriber 游标 + lifecycle_anchor + * │ append_direct_thread_event() → notify（只带 subscriptionId，纯唤醒） + * ▼ + * 传输层（三条通道，前端各拉各的） + * A 运行态：notify → invoke consume_direct_project_thread → events[]（实时） + * B 历史： invoke read_direct_project_history_slice → items[]（分页，文件尾反向扫描） + * C 本地： 前端自己造（乐观用户气泡、忙态、失败 / 终止说明） + * ▼ + * 前端 + * useDirectThreadChatSubscription reducer：A + B 进同一份 state（turnRunning / history / live） + * ▼ + * useDirectProjectChatController 本地状态：localMessages / turnBusy / pendingUserItemId / 队列 + * ▼ + * DirectProjectChatView turns = buildDirectChatTurns(...)；status = useDirectProjectTurnStatus(...) + * ▼ + * DirectProjectTurn 用户气泡 / 过程块 / 最终回复 / 本轮耗时 + * ``` + * + * 三份原始输入各自是什么、带什么、活多久： + * - 项目对话历史（`.agent/conversations/project.jsonl`）：持久，只有条目、**没有回合边界**， + * 经历史切片读取（首屏按 `lastCompletedItemId` 锚定）。 + * - 运行态事件（subscribe / consume / notify）：进程内；`turn.started` / `turn.completed` 是原生回合 + * 活跃与否的**唯一**判据；可回收事件被回收后靠 `lifecycle_anchor` 保住最新一条生命周期事件。 + * - 本地发送：只存在于本次会话，`projectPath` 变化即清空；乐观气泡与原生条目同身份 + * （`direct-codex:{clientTurnId}:user`），所以两边按**身份**合并，不按时间戳猜。 + * + * 一次发送的时序（第 2 → 3 步之间就是「本地已发出、宿主还没确认」的空窗）： + * 1. 按下发送：`localMessages += 乐观气泡`、`turnBusy=true`、`pendingUserItemId=本轮身份`（同帧）。 + * 2. `invoke('chat_with_game_creator_direct_codex')`：Rust 先落盘用户条目，再发 `turn/start`， + * **应答返回后**才 append `turn.started` 并 notify。 + * 3. notify → consume → `turn.started`：reducer 的 `turnRunning=true`、`turnStartedAt`、`turnUserItemId`。 + * 4. `item.completed`（本轮用户条目回显）：同身份条目已在历史里就合并进去，否则进 `live`；本地气泡此时被去重。 + * 5. `item.delta` / `item.started` / `item.completed`：正文追加、工具卡片 upsert（先到定形、后到只补空）。 + * 6. `turn.completed`：`live` 并入 `history` 后清空，`turnEndedAt` 冻结，边界按身份盖到本轮开口条目上。 + * 7. 命令收尾（`finally`）：刷新清单 → `endTurnCommand()` 清掉忙态与在途身份 → 出队下一轮。 + * **顺序是契约**：出队会同步开始下一轮并设上它自己的忙态，所以清忙态必须早于出队； + * 权限被拒那种「本轮从未发出但要继续出队」的情况，也只标记 `queueAdvance`、由这里统一收口。 + * + * 状态变量归属：reducer 的三个回合字段与 `history` / `live` 只由 `directThreadChat.ts` 写； + * 本文件的 `turnBusy` / `pendingUserItemId`（同生共死，唯一入口 `beginTurnCommand` / + * `endTurnCommand`）、`localMessages`、发送队列与分页 ref 只服务发送与展示；界面上的 + * 「这一轮在跑吗」只有一个派生入口 `useDirectProjectTurnStatus()`，三态判据与真值表在 + * `../conversation/directTurnPresentation.ts` 的 `DirectChatTurnState`，渲染时否定式读 + * `state !== 'finished'`、肯定式读 `state === 'running'`（见 `DirectProjectTurn.tsx`）。 */ export function useDirectProjectChatController({ assets, @@ -113,6 +163,9 @@ export function useDirectProjectChatController({ const [statusNotice, setStatusNotice] = useState(''); const [turnCancelling, setTurnCancelling] = useState(false); const [turnBusy, setTurnBusy] = useState(false); + // 本地已发出、原生还没认领的那一轮用户条目身份：只服务投影的 `awaiting-start` 展示态， + // 生命周期与 `turnBusy` 完全一致（命令在飞期间有值，收尾即清）。 + const [pendingUserItemId, setPendingUserItemId] = useState(''); const [localMessages, setLocalMessages] = useState([]); // 订阅（subscribe/consume/notify）与聊天 reducer 状态在自己的 hook 里： // controller 只读投影后的条目与回合忙态，不再直接持有线程状态。 @@ -143,6 +196,7 @@ export function useDirectProjectChatController({ setQueuedTurns([]); queuedTurnsRef.current = []; setLocalMessages([]); + setPendingUserItemId(''); setHistoryHasMore(false); historyOldestItemIdRef.current = null; }, [projectPath]); @@ -194,9 +248,21 @@ export function useDirectProjectChatController({ // eslint-disable-next-line react-hooks/exhaustive-deps }, [enabled, projectPath]); - function markTurnBusy(busy: boolean) { - turnBusyRef.current = busy; - setTurnBusy(busy); + /** + * 「本地这一轮的命令在飞」的唯一起止点：按下发送时带上本轮用户条目身份，收尾时一起清掉。 + * + * 忙态与待认领身份必须同生共死，否则投影会拿一个过期的身份去判 `awaiting-start`。 + */ + function beginTurnCommand(userItemId: string) { + turnBusyRef.current = true; + setTurnBusy(true); + setPendingUserItemId(userItemId); + } + + function endTurnCommand() { + turnBusyRef.current = false; + setTurnBusy(false); + setPendingUserItemId(''); } function appendLocalMessage(message: ChatMessage) { @@ -388,9 +454,14 @@ export function useDirectProjectChatController({ updatedAt: Date.now(), }); } - markTurnBusy(true); + beginTurnCommand( + directCodexConversationMessageId(input.clientTurnId, 'user'), + ); void (async () => { let invoked = false; + // 权限被拒也要继续出队（见下），但出队必须发生在 finally 的 endTurnCommand() 之后： + // 在这里出队的话，下一轮刚设上的忙态会被紧接着的 finally 清掉。 + let queueAdvance = false; try { onRuntimeError(''); if (!input.directPolicyChecked) { @@ -404,10 +475,9 @@ export function useDirectProjectChatController({ }); if (!allowed) { // 写权限门返回 false 且没有调用 onConfirmed（被策略拒绝、或读策略失败）， - // 说明这一轮不会重跑；它已经被 dispatchNextQueuedTurn 出队，必须自己把 - // 忙态放下并继续出队，否则后面的排队消息会永久卡住。 - markTurnBusy(false); - dispatchNextQueuedTurn(); + // 说明这一轮不会重跑；它已经被出队，必须继续出队，否则后面的排队消息会 + // 永久卡住。放忙态与出队都交给 finally 收口，这里只做标记。 + queueAdvance = true; return; } } @@ -429,8 +499,15 @@ export function useDirectProjectChatController({ if (invoked) { await refreshDirectManifest(nextProjectPath); } - markTurnBusy(false); - if (invoked && projectPathRef.current === nextProjectPath) { + // 忙态与在途身份每轮只在这里放一次，且必须早于出队：出队会同步开始下一轮并设上 + // 它自己的忙态，清在它后面就等于把下一轮的忙态抹掉（composer 会以为可以并发发送， + // 下一轮的三态也会因为身份被清空而掉回 finished）。 + endTurnCommand(); + // 出队条件保持原样：真发出过的一轮要求项目没被换掉；权限被拒的一轮从未发出， + // 不受项目切换影响，照旧出队。 + const invokedInSameProject = + invoked && projectPathRef.current === nextProjectPath; + if (queueAdvance || invokedInSameProject) { dispatchNextQueuedTurn(); } } @@ -478,6 +555,13 @@ export function useDirectProjectChatController({ }); return; } + // 真失败：这条命令返回就说明这一轮在宿主那边已经收场，但终态事件可能永远不来 + // （app-server 崩了、任务被中止、panic 都只留下一条开着的 `turn.started`）。 + // 按本轮身份放掉原生忙态，否则界面会一直显示「正在处理」、输入盒一直排队。 + // 主动终止与「正在跑的是另一轮」不走这里：前者宿主必然补终态，后者不是这一轮。 + directThread.stopCommandTurn( + directCodexConversationMessageId(input.clientTurnId, 'user'), + ); void captureAgentRuntimeError(error, DIRECT_CODEX_AGENT_ID); const message = error instanceof Error ? error.message : String(error); let persistedDetail = ''; @@ -541,7 +625,7 @@ export function useDirectProjectChatController({ const message = result?.message?.trim(); if (result?.outcome === 'released') { directThread.markTurnStopped(); - markTurnBusy(false); + endTurnCommand(); onRuntimeError(''); setComposerNotice(message ?? '已结束这一轮占用，可以直接重新发送消息'); } else if (message) { @@ -714,6 +798,7 @@ export function useDirectProjectChatController({ historyHasMore, loadEarlierHistory, localMessages, + pendingUserItemId, queuedTurns, reloadHistory, removeAttachment, diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectTurnStatus.ts b/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectTurnStatus.ts new file mode 100644 index 000000000..05c9f456e --- /dev/null +++ b/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectTurnStatus.ts @@ -0,0 +1,68 @@ +import { useMemo } from 'react'; + +import type { + DirectChatTurn, + DirectChatTurnState, +} from '../conversation/directTurnPresentation'; + +/** + * DirectProject「这一轮在跑吗」的唯一派生入口。 + * + * 同一件事此前在四层里各叫一个名字（reducer 的 `turnRunning`、controller 的 `turnBusy`、 + * 视图里手拼的 `busy`、投影里的 `active`），读代码时无法判断谁该信谁。这里把它们的语义 + * 一次讲清楚，组件只读这一个对象： + * + * - `nativeRunning`：**原生真相**。只由订阅 reducer 的 `turnRunning` 给出（`turn.started` + * 已到、`turn.completed` 未到）。它决定"陶泥儿正在处理"这类原生过程提示。 + * - `commandInFlight`：**本地真相**。本次会话的发送命令是否在飞（写权限门 → invoke → + * 收尾）；它从按下发送那一刻就为真，与原生是否已经开始无关。 + * - `displayBusy`：header / composer 该读的忙态，就是两者的并集：只要有一条成立就不能再 + * 接受新的发送。 + * - `latestTurnState`：最新一轮在界面上的三态（投影结果）；没有回合时为 null。 + * + * 约定：新增"忙/在跑"类判据一律先落进这里，不要在组件里再拼布尔。 + * `latestTurnState` 三态各自的含义、判据输入与真值表写在 + * `../conversation/directTurnPresentation.ts` 的 `DirectChatTurnState`。 + * 数据流、变量归属与一次发送的时序见 `useDirectProjectChatController.ts` 的模块注释。 + */ +export type DirectProjectTurnStatus = { + nativeRunning: boolean; + commandInFlight: boolean; + displayBusy: boolean; + latestTurnState: DirectChatTurnState | null; +}; + +export function deriveDirectProjectTurnStatus({ + turnRunning, + turnBusy, + turns, +}: { + turnRunning: boolean; + turnBusy: boolean; + turns: readonly DirectChatTurn[]; +}): DirectProjectTurnStatus { + const nativeRunning = Boolean(turnRunning); + const commandInFlight = Boolean(turnBusy); + const latest = turns.length > 0 ? turns[turns.length - 1] : null; + return { + nativeRunning, + commandInFlight, + displayBusy: nativeRunning || commandInFlight, + latestTurnState: latest ? latest.state : null, + }; +} + +export function useDirectProjectTurnStatus({ + turnRunning, + turnBusy, + turns, +}: { + turnRunning: boolean; + turnBusy: boolean; + turns: readonly DirectChatTurn[]; +}): DirectProjectTurnStatus { + return useMemo( + () => deriveDirectProjectTurnStatus({ turnRunning, turnBusy, turns }), + [turnRunning, turnBusy, turns], + ); +} diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectThreadChatSubscription.ts b/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectThreadChatSubscription.ts index 90757bdce..463954657 100644 --- a/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectThreadChatSubscription.ts +++ b/apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectThreadChatSubscription.ts @@ -19,6 +19,7 @@ import { mergeDirectHistoryItems, resolveDirectThreadBootstrap, selectDirectChatEntries, + stopDirectThreadTurn, } from '../conversation/directThreadChat'; import type { DirectThreadConsumeResult } from '../generated/DirectThreadConsumeResult'; import type { DirectThreadItem } from '../generated/DirectThreadItem'; @@ -40,6 +41,11 @@ export type DirectThreadChatSubscription = { mergeHistoryItems: (items: readonly DirectThreadItem[]) => void; /** 终止成功（`released`）时手动放掉回合占用：订阅可能要等下一个事件才知道。 */ markTurnStopped: () => void; + /** + * 本地命令失败收场时按身份放掉这一轮：宿主的终态事件可能永远不会来（进程崩了 / + * 任务被中止），不能一直挂在 `turn.started` 上显示「正在处理」。 + */ + stopCommandTurn: (userItemId: string) => void; }; /** @@ -185,6 +191,13 @@ export function useDirectThreadChatSubscription({ [], ); + const stopCommandTurn = useMemo( + () => (userItemId: string) => { + setState((current) => stopDirectThreadTurn(current, userItemId)); + }, + [], + ); + const entries = useMemo(() => selectDirectChatEntries(state), [state]); return { @@ -194,5 +207,6 @@ export function useDirectThreadChatSubscription({ anchorGateRef, mergeHistoryItems, markTurnStopped, + stopCommandTurn, }; } diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directThreadChat.ts b/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directThreadChat.ts index 4ed45d4c6..7075634a6 100644 --- a/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directThreadChat.ts +++ b/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directThreadChat.ts @@ -45,7 +45,14 @@ export type DirectChatEntry = { }; export type DirectThreadChatState = { - /** 最新回合是否还在跑；只由生命周期事件的先后决定。 */ + /** + * 最新**原生**回合是否还在跑；只由生命周期事件（`turn.started` / `turn.completed`） + * 的先后决定。 + * + * 它不等于界面上的「这一轮在跑吗」：本地已发出、宿主还没回 `turn.started` 的那一段 + * 窗口里它为假，但那一轮在界面上是"待认领"而不是"已结束"。界面侧的三态与判据见 + * `directTurnPresentation.ts` 的 `DirectChatTurnState`。 + */ turnRunning: boolean; /** 原生 `turn.started.at`：本轮用户实际发送时间缺失时的起点兜底；0 = 缺失。 */ turnStartedAt: number; @@ -58,6 +65,16 @@ export type DirectThreadChatState = { * 也不用时间戳近似。空串 = 原生没给身份（旧事件），此时不猜历史归属。 */ turnUserItemId: string; + /** + * 「本地命令已经返回、宿主却一直没给终态」的那一轮身份（见 `stopDirectThreadTurn`）。 + * + * `turn.started` 与 `turn.completed` 是原生回合唯一的开闭配对，但**进程崩了、任务被 + * 中止、panic** 这类收场不会补终态事件，只留一条永远开着的 `turn.started`：界面上就 + * 一直显示「正在处理」，输入盒也一直忙。本地那一条命令（`chat_with_game_creator_direct_codex`） + * 返回时说到底就是"这一轮在宿主那边已经收场"，这条身份就是它的记录：同身份的 + * `turn.started` 迟到 / 重放回来不再复活这一轮，避免收口之后又被拉回运行态。 + */ + commandClosedTurnUserItemId: string; /** 历史切片条目，保持文件顺序。 */ history: DirectChatEntry[]; /** 当前回合的运行态条目，保持到达顺序；回合结束即并入历史并清空。 */ @@ -70,11 +87,40 @@ export function emptyDirectThreadChatState(): DirectThreadChatState { turnStartedAt: 0, turnEndedAt: 0, turnUserItemId: '', + commandClosedTurnUserItemId: '', history: [], live: [], }; } +/** + * 本地命令失败收场：这一轮命令已经返回，宿主却还在事件流里挂着 `turn.started`。 + * + * 只放掉"是否在跑"，**不写终态时间**——命令返回不等于我们知道这一轮真正的结束时刻， + * 编一个只会让耗时变成假数。收口后同身份的 `turn.started` 迟到 / 重放回来不再复活， + * 免得刚修好的"还在处理"又被拉起来。宿主随后真发来 `turn.completed` 时照旧正常收口。 + * + * 身份不同的轮次不动：宿主同时只允许一条回合，但"正在跑的是另一轮"（`another-turn-running`） + * 这种拒绝也要能原样报给用户，不能顺手把别人那轮抹掉。空身份（宿主没能落上身份）时按 + * 本轮处理，否则这条兜底永远盖不住协议早期失败。 + */ +export function stopDirectThreadTurn( + state: DirectThreadChatState, + userItemId: string, +): DirectThreadChatState { + if (state.turnUserItemId !== '' && state.turnUserItemId !== userItemId) { + return state; + } + if (!state.turnRunning && state.commandClosedTurnUserItemId === userItemId) { + return state; + } + return { + ...state, + turnRunning: false, + commandClosedTurnUserItemId: userItemId, + }; +} + /** 时间戳合法性：缺失 / 0 / 非有限都算没有这个边界，不用它计任何耗时。 */ function validBoundaryAt(value: number | null | undefined): number { return typeof value === 'number' && Number.isFinite(value) && value > 0 @@ -295,6 +341,14 @@ export function reduceDirectThreadEvent( // 本轮的 canonical user identity 跟着事件走：新回合就换成新的；旧原生不带身份时 // 清空而不是继承上一轮，避免上一轮迟到的终态按身份匹配到这一轮。 const turnUserItemId = readDirectThreadEventUserItemId(event); + // 本地命令已经收过场的那一轮：迟到的 `turn.started` 不得把它拉回运行态（见 + // `commandClosedTurnUserItemId`）。身份按 clientTurnId 唯一，只挡它自己那一轮。 + if ( + turnUserItemId !== '' && + turnUserItemId === state.commandClosedTurnUserItemId + ) { + return state; + } return { ...state, turnRunning: true, @@ -316,7 +370,17 @@ export function reduceDirectThreadEvent( return state; } // 已经收口、而且没有新的运行态条目：重复 / 迟到的终态事件不改动时间，也不复活运行态。 - if (!state.turnRunning && state.live.length === 0) { + // 例外是"本地命令兜底收口"的那一轮（`commandClosedTurnUserItemId` 命中且还没有终态 + // 时间）：那次收口本来就没写时间，宿主这份迟到的终态要拿来补上真正的结束时刻。 + const lateTerminalForCommandClosedTurn = + eventUserItemId !== '' && + eventUserItemId === state.commandClosedTurnUserItemId && + state.turnEndedAt <= 0; + if ( + !state.turnRunning && + state.live.length === 0 && + !lateTerminalForCommandClosedTurn + ) { return state; } return finishDirectThreadTurn(state, eventAt); diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directTurnPresentation.ts b/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directTurnPresentation.ts index 1673032c9..33711fa2d 100644 --- a/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directTurnPresentation.ts +++ b/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directTurnPresentation.ts @@ -36,6 +36,57 @@ export type DirectChatBlock = | { kind: 'reasoning'; key: string; text: string } | { kind: 'tools'; key: string; calls: DirectChatToolCard[] }; +/** + * 界面上一轮的三态。它是**展示态**，不是第二套回合生命周期。 + * + * 三态各自能断言什么（渲染时按这个分两类，不要对调）： + * - `running`：**宿主已确认这一轮开始了**（订阅流里出现过 `turn.started`、还没出现 + * `turn.completed`）。它是唯一能做肯定式断言的态。 + * - `awaiting-start`：**本地已把这轮交出去、宿主还没确认**（乐观气泡已出现，`turn.started` + * 未到）。只支持否定式断言："它还没结束"，不能说"它正在跑"。 + * - `finished`：其余全部 —— 拿到终态的、身份不匹配的、不是最新一轮的，以及**拿不到边界的 + * 历史回合**（这类最容易被误判成"还在跑"，必须落在这一态）。 + * + * 判据用四个输入（下方 `buildDirectChatTurns` 里那几句 if 就是全部实现）： + * - `turn.nativeRunning` ← 入参 `turnRunning` ← reducer 的 `state.turnRunning` + * （只由 `turn.started` / `turn.completed` 决定；`if (current)` 只赋给最后一条回合， + * 所以「非最新一轮 + nativeRunning」不可达）。 + * - `pendingUserItemId` ← controller 在 `beginTurnCommand` / `endTurnCommand` 之间维护， + * 生命周期与 `turnBusy` 一致；空串 = 没有在途的本地回合。 + * - `turn.key` ← 开这一轮的条目身份：原生用户条目用 `entry.itemId`，本地乐观气泡用 + * `message.messageId` —— 两者是**同一个** `direct-codex:{clientTurnId}:user`。 + * - `stampedEnd` ← 本轮条目上盖的终态时间，只有 `turn.completed` / 终止收口才写。 + * + * 真值表： + * + * | nativeRunning | 最新一轮 && pendingUserItemId 身份命中 | stampedEnd > 0 | → state | + * | true | — | — | running | + * | false | false | 任意 | finished | + * | false | true | true | finished | + * | false | true | false | awaiting-start | + * + * 判据一律用**身份与显式事件**，不用时间戳大小：原生阶段时间是秒级精度、同一秒里可能连开 + * 两轮，回显条目的 `at` 还是宿主 ack 的观测时间（晚于用户真实发送）。这也是为什么 + * `awaiting-start` 在"原生条目已回显、`turn.started` 未到"的次窗口里同样成立。 + * + * 两个容易读错的地方： + * - `pendingUserItemId` 有值 **≠** `awaiting-start`：`invoke` 直到整轮结束才返回，所以 + * `turn.started` 之后它仍在，但那时 `nativeRunning` 已经把它接成 `running`。 + * - `endedAt === 0` **≠** 还在跑：历史回合没有边界元数据（`turnEndedAt` 只是会话内展示 + * 缓存），它们必须落 `finished`。 + * + * 三态在渲染上的映射（否定式 / 肯定式）见 `DirectProjectTurn.tsx` 顶部注释；数据流、变量归属与 + * 一次发送的时序见 `../controller/useDirectProjectChatController.ts` 的模块注释。 + * + * 已知边界（改 `finished` 判据时要连着一起看）：`finished` 只断言"不再有理由认为它在跑"， + * **不断言"拿得到终态时间"**。有两类回合没有可证明的边界时间，只被 + * `Math.max(turn.endedAt, turn.startedAt)` 兜底量化成 0.0 秒——① 重进项目后读回来的历史回合 + * （`turnEndedAt` 只是会话内展示缓存，不随 `project.jsonl` 持久化）；② 本地已发出却一个原生事件 + * 都没产生的回合（发送失败、`turn.started` 没来）。要不要把这两类的终态文案藏掉是产品口径问题 + * （宁可隐藏也不编），需要单独确认后单独改，不要顺手塞进三态判据。 + */ +export type DirectChatTurnState = 'running' | 'awaiting-start' | 'finished'; + export type DirectChatTurn = { key: string; /** 用户气泡：顺序即发出顺序。 */ @@ -44,7 +95,8 @@ export type DirectChatTurn = { process: DirectChatBlock[]; /** 最终回复，以及失败 / 终止这类只存在于运行期的说明。 */ finals: DirectChatBlock[]; - active: boolean; + /** 这一轮在界面上的状态（三态，取代原来的 `active` 布尔）。 */ + state: DirectChatTurnState; /** * 本轮起点：该轮**实际用户消息的发送时间**优先（与气泡显示的时间同源）， * 缺失时用原生 `turn.started.at`，都拿不到是 0（此时隐藏不能证明的总耗时）。 @@ -60,7 +112,8 @@ type DirectChatTurnEntries = { /** 本地乐观用户气泡：还没有任何落盘条目时的用户消息。 */ localUsers: DirectChatBlock[]; notices: ChatMessage[]; - active: boolean; + /** 原生回合是否在跑；只有一个来源——reducer 的 `turnRunning`。 */ + nativeRunning: boolean; }; function blockFromEntry( @@ -178,7 +231,7 @@ function newTurn(key: string): DirectChatTurnEntries { entries: [], localUsers: [], notices: [], - active: false, + nativeRunning: false, }; } @@ -193,6 +246,7 @@ export function buildDirectChatTurns({ localMessages = [], turnRunning = false, turnStartedAt = 0, + pendingUserItemId = '', }: { entries: readonly DirectChatEntry[]; localMessages?: readonly ChatMessage[]; @@ -202,6 +256,14 @@ export function buildDirectChatTurns({ * 不会覆盖用户实际发送时间，也不参与已完成回合。 */ turnStartedAt?: number; + /** + * 本地已发出、原生还没认领的那一轮用户条目身份（`direct-codex:{clientTurnId}:user`）。 + * + * 只服务 `awaiting-start` 这一个展示态：身份命中、且本轮还没有明确终态时，最新一轮按 + * 「待认领」而不是「已结束」呈现。原生 `turn.started` 一到，`turnRunning` 就把这一轮接 + * 过去，这个入参不再参与判定；空串 = 没有在途的本地回合。 + */ + pendingUserItemId?: string; }): DirectChatTurn[] { const turns: DirectChatTurnEntries[] = []; let current: DirectChatTurnEntries | null = null; @@ -247,10 +309,11 @@ export function buildDirectChatTurns({ } current.notices.push(message); }); - if (current) current.active = turnRunning; + if (current) current.nativeRunning = turnRunning; - return turns.map((turn) => { - const lastAssistant = turn.active + const newestTurnIndex = turns.length - 1; + return turns.map((turn, turnIndex) => { + const lastAssistant = turn.nativeRunning ? -1 : turn.entries.reduce( (found, entry, index) => @@ -301,21 +364,38 @@ export function buildDirectChatTurns({ (found, entry) => found || normalizeDirectTimestamp(entry.turnEndedAt), 0, ); - const startedAt = - userSentAt > 0 - ? userSentAt - : turn.active - ? normalizeDirectTimestamp(turnStartedAt) - : stampedStart; + // 起点优先级（逐级覆盖，不嵌套三元）：条目上盖的起点 → 运行中改读原生 + // `turn.started.at`（拿不到就是 0，不退回去用条目兜底）→ 该轮用户气泡自己的发送 + // 时间最高优先。 + let startedAt = stampedStart; + if (turn.nativeRunning) { + startedAt = normalizeDirectTimestamp(turnStartedAt); + } + if (userSentAt > 0) { + startedAt = userSentAt; + } // 终态只读**本轮条目**上盖的边界：跨轮 fallback 会把最新回合的终点填进所有 // 拿不到时间的旧历史回合，等于给未知耗时编一个值。 - const endedAt = turn.active ? 0 : stampedEnd; + const endedAt = turn.nativeRunning ? 0 : stampedEnd; + // 三态只在这里产生：原生在跑 = running；最新一轮是本地在途身份且没有终态 = + // awaiting-start；其余都是 finished。判据是身份（`itemId`）而不是时间戳大小。 + let state: DirectChatTurnState = 'finished'; + if (turn.nativeRunning) { + state = 'running'; + } else if ( + turnIndex === newestTurnIndex && + pendingUserItemId !== '' && + turn.key === pendingUserItemId && + stampedEnd <= 0 + ) { + state = 'awaiting-start'; + } return { key: turn.key, users, process: mergeToolBlocks(process), finals, - active: turn.active, + state, startedAt, endedAt, } satisfies DirectChatTurn; diff --git a/apps/ai-game-creator-shell/tests/appSurface/chat-composer.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/chat-composer.suite.ts index 1feb723ab..4de59b000 100644 --- a/apps/ai-game-creator-shell/tests/appSurface/chat-composer.suite.ts +++ b/apps/ai-game-creator-shell/tests/appSurface/chat-composer.suite.ts @@ -21,6 +21,7 @@ import { act, createGameCreationAppManifest, createProjectChatRuntimeHarness, + emptyProjectPolicy, expect, fireEvent, it, @@ -469,6 +470,134 @@ export function registerChatComposerControlTests() { }); }); + it('does not report a finished turn while the host has not acknowledged the send yet', async () => { + const pending: Array<{ resolve: (value: string) => void }> = []; + const { invoke, surface } = await openDirectCodexSurface({ + chat_with_game_creator_direct_codex: () => + new Promise((resolve) => { + pending.push({ resolve }); + }), + }); + const composer = within(surface).getByLabelText('陶泥儿对话内容'); + await submitDirectTurn(surface, composer, '窗口期的消息'); + + // 写权限门是异步的，先等命令真的发出去，否则下面的窗口期断言会在 invoke 还没发生时就 + // 通过、收尾的 `pending[0]?.resolve` 也变成空操作，用例根本没盖住它要盖的窗口。 + await waitFor(() => { + expect(invoke).toHaveBeenCalledWith( + 'chat_with_game_creator_direct_codex', + expectDirectTurnWithText('窗口期的消息'), + ); + }); + + // 本地乐观气泡立刻可见；此刻原生既没回 turn.started，也没回显用户条目， + // 这一轮属于「本地已发出、宿主未确认」，不得渲染成已结束。 + await waitFor(() => { + expect(within(surface).getByText('窗口期的消息')).not.toBeNull(); + }); + expect(within(surface).queryByText(/本轮结束于/)).toBeNull(); + expect(within(surface).queryByTestId('turn-usage')).toBeNull(); + + await act(async () => { + pending[0]?.resolve('回复'); + }); + }); + + it('stops claiming the turn is running when a failed send left turn.started open', async () => { + let harness: ReturnType | null = + null; + const { surface } = await openDirectCodexSurface( + { + chat_with_game_creator_direct_codex: ( + args: Record | undefined, + ) => { + // 宿主先认领了这一轮（turn.started），随后崩掉：没有终态事件，命令以失败返回。 + harness?.emitDirectThreadEvents({ + type: 'turn.started', + at: 5_000, + userItemId: `direct-codex:${String(args?.clientTurnId ?? '')}:user`, + }); + throw new Error('模拟宿主崩溃：turn.started 之后没有终态事件'); + }, + }, + (directHarness) => { + harness = directHarness; + }, + ); + const composer = within(surface).getByLabelText('陶泥儿对话内容'); + await submitDirectTurn(surface, composer, '崩掉的那条'); + + await waitFor(() => { + expect( + within(surface).getAllByText('陶泥儿智能创作 执行失败，请稍后重试') + .length, + ).toBeGreaterThan(0); + }); + // 命令已经收场：卡片和输入区都不能再声称"还在处理"。 + expect(within(surface).queryAllByText('陶泥儿正在处理')).toHaveLength(0); + expect(within(surface).queryByRole('button', { name: '终止' })).toBeNull(); + expect( + within(surface).getByRole('button', { name: '发送' }), + ).not.toBeNull(); + }); + + it('keeps the next queued turn busy when the write gate refuses the running one', async () => { + const pending: Array<{ resolve: (value: string) => void }> = []; + const deferredPolicies: Array<(value: unknown) => void> = []; + let policyAllowsWrite = false; + const { invoke, surface } = await openDirectCodexSurface({ + read_project_permission_policy: () => { + if (policyAllowsWrite) return Promise.resolve(emptyProjectPolicy()); + return new Promise((resolve) => { + deferredPolicies.push(resolve); + }); + }, + chat_with_game_creator_direct_codex: () => + new Promise((resolve) => { + pending.push({ resolve }); + }), + }); + const composer = within(surface).getByLabelText('陶泥儿对话内容'); + await submitDirectTurn(surface, composer, '被拒的那条'); + + // 权限门还没回，先把第二条排进队列：后面那条要等被拒的这一轮出队才会发出去。 + await setComposerText(composer, '后面那条'); + submitComposerForm(composer); + const queue = await within(surface).findByLabelText('待发送消息队列'); + expect(within(queue).getByText('后面那条')).not.toBeNull(); + + // 写权限门拒绝这一轮（策略要求确认，且此刻没有 onConfirmed）：这一轮不会重跑， + // 队列必须继续走，而它出队后那一轮仍要算「命令在飞」。 + policyAllowsWrite = true; + await act(async () => { + for (const resolve of deferredPolicies.splice(0)) { + resolve({ + path: '.agent/policy.json', + policy: { + deniedCommands: [], + confirmCommands: ['conversation.write'], + }, + }); + } + }); + + await waitFor(() => { + expect(invoke).toHaveBeenCalledWith( + 'chat_with_game_creator_direct_codex', + expectDirectTurnWithText('后面那条'), + ); + }); + // 被出队的那一轮还在飞：上一轮的收尾不得把它刚设上的忙态清掉。 + expect(within(surface).queryByRole('button', { name: '发送' })).toBeNull(); + expect( + within(surface).getByRole('button', { name: '终止' }), + ).not.toBeNull(); + + await act(async () => { + pending[0]?.resolve('回复'); + }); + }); + it('restores a running DirectProject turn, queues the next message, and dispatches it on turn.completed', async () => { const pending: Array<{ resolve: (value: string) => void }> = []; const { invoke, surface, harness } = await openDirectCodexSurface( diff --git a/apps/ai-game-creator-shell/tests/directProjectTurn.test.tsx b/apps/ai-game-creator-shell/tests/directProjectTurn.test.tsx new file mode 100644 index 000000000..1561a54e7 --- /dev/null +++ b/apps/ai-game-creator-shell/tests/directProjectTurn.test.tsx @@ -0,0 +1,61 @@ +/** @vitest-environment jsdom */ +import { render } from '@testing-library/react'; +import React from 'react'; +import { expect, it } from 'vitest'; + +import { DirectProjectTurn } from '../src/view/project-development/chat/components/DirectProjectConversation/DirectProjectTurn'; +import type { + DirectChatTurn, + DirectChatTurnState, +} from '../src/view/project-development/chat/conversation/directTurnPresentation'; + +const SENT_AT = 1_800_000_000_000; +const ENDED_AT = SENT_AT + 12_400; + +const turn = ( + state: DirectChatTurnState, + overrides: Partial = {}, +): DirectChatTurn => ({ + key: 'direct-codex:turn-1:user', + users: [{ kind: 'user', key: 'u', text: '帮我做一个跳跃动作', at: SENT_AT }], + process: [ + { kind: 'reasoning', key: 'r', text: '先看目录' }, + { kind: 'assistant', key: 'a', text: '正在写' }, + ], + finals: [{ kind: 'assistant', key: 'a-final', text: '改好了', at: ENDED_AT }], + state, + startedAt: SENT_AT, + endedAt: state === 'finished' ? ENDED_AT : 0, + ...overrides, +}); + +it('awaiting-start：本地已发出、原生还没认领时不显示终态文案，也不折叠过程', () => { + const view = render( + React.createElement(DirectProjectTurn, { + turn: turn('awaiting-start'), + }), + ); + expect(view.queryByTestId('turn-usage')).toBeNull(); + expect(view.queryByText(/本轮结束于/)).toBeNull(); + // 否定式判据：未结束的回合把过程平铺出来，不折进「执行过程」。 + expect(view.queryByTestId('turn-process')).toBeNull(); + expect(view.getByLabelText('思考过程')).not.toBeNull(); +}); + +it('running：原生回合在跑时同样不显示终态文案', () => { + const view = render( + React.createElement(DirectProjectTurn, { turn: turn('running') }), + ); + expect(view.queryByTestId('turn-usage')).toBeNull(); + expect(view.queryByTestId('turn-process')).toBeNull(); +}); + +it('finished 且有明确终态：显示结束时间与耗时，过程折叠', () => { + const view = render( + React.createElement(DirectProjectTurn, { turn: turn('finished') }), + ); + const usage = view.getByTestId('turn-usage'); + expect(usage.textContent).toContain('本轮结束于'); + expect(usage.textContent).toContain('耗时 12.4秒'); + expect(view.queryByTestId('turn-process')).not.toBeNull(); +}); diff --git a/apps/ai-game-creator-shell/tests/directProjectTurnStatus.test.ts b/apps/ai-game-creator-shell/tests/directProjectTurnStatus.test.ts new file mode 100644 index 000000000..7cab1828d --- /dev/null +++ b/apps/ai-game-creator-shell/tests/directProjectTurnStatus.test.ts @@ -0,0 +1,77 @@ +import { describe, expect, it } from 'vitest'; + +import { deriveDirectProjectTurnStatus } from '../src/view/project-development/chat/controller/useDirectProjectTurnStatus'; +import type { DirectChatTurn } from '../src/view/project-development/chat/conversation/directTurnPresentation'; + +const turn = (key: string, state: DirectChatTurn['state']): DirectChatTurn => ({ + key, + users: [], + process: [], + finals: [], + state, + startedAt: 1_800_000_000_000, + endedAt: 0, +}); + +describe('DirectProject 回合状态派生', () => { + it('displayBusy 是原生真相与本地命令在飞的并集', () => { + expect( + deriveDirectProjectTurnStatus({ + turnRunning: true, + turnBusy: false, + turns: [], + }).displayBusy, + ).toBe(true); + expect( + deriveDirectProjectTurnStatus({ + turnRunning: false, + turnBusy: true, + turns: [], + }).displayBusy, + ).toBe(true); + expect( + deriveDirectProjectTurnStatus({ + turnRunning: false, + turnBusy: false, + turns: [], + }).displayBusy, + ).toBe(false); + }); + + it('两个来源各自独立暴露，不被并集吃掉', () => { + const status = deriveDirectProjectTurnStatus({ + turnRunning: true, + turnBusy: true, + turns: [], + }); + expect(status.nativeRunning).toBe(true); + expect(status.commandInFlight).toBe(true); + }); + + it('latestTurnState 取最新一轮的三态；没有回合时为 null', () => { + expect( + deriveDirectProjectTurnStatus({ + turnRunning: false, + turnBusy: false, + turns: [turn('u1', 'finished'), turn('u2', 'awaiting-start')], + }).latestTurnState, + ).toBe('awaiting-start'); + expect( + deriveDirectProjectTurnStatus({ + turnRunning: false, + turnBusy: false, + turns: [], + }).latestTurnState, + ).toBeNull(); + }); + + it('本地命令在飞不等于原生在跑', () => { + const status = deriveDirectProjectTurnStatus({ + turnRunning: false, + turnBusy: true, + turns: [turn('u1', 'awaiting-start')], + }); + expect(status.nativeRunning).toBe(false); + expect(status.latestTurnState).toBe('awaiting-start'); + }); +}); diff --git a/apps/ai-game-creator-shell/tests/directThreadChat.test.ts b/apps/ai-game-creator-shell/tests/directThreadChat.test.ts index 55a1b05d6..98c6d397e 100644 --- a/apps/ai-game-creator-shell/tests/directThreadChat.test.ts +++ b/apps/ai-game-creator-shell/tests/directThreadChat.test.ts @@ -11,6 +11,7 @@ import { reduceDirectThreadEvents, resolveDirectThreadBootstrap, selectDirectChatEntries, + stopDirectThreadTurn, } from '../src/view/project-development/chat/conversation/directThreadChat'; import type { DirectThreadItem } from '../src/view/project-development/chat/conversation/directThreadItemProjection'; import type { DirectThreadEvent } from '../src/view/project-development/chat/generated/DirectThreadEvent'; @@ -176,6 +177,54 @@ describe('DirectProject 聊天 reducer', () => { expect(selectDirectChatEntries(done)).toHaveLength(2); }); + it('本地命令兜底收口后，迟到的同名 turn.started 不复活这一轮', () => { + const identity = 'direct-codex:client-turn-1:user'; + const running = reduceDirectThreadEvents(emptyDirectThreadChatState(), [ + event(withUserItemId({ type: 'turn.started', at: 1_000 }, identity)), + event({ type: 'item.completed', item: messageItem() }), + ]); + expect(running.turnRunning).toBe(true); + + const stopped = stopDirectThreadTurn(running, identity); + expect(stopped.turnRunning).toBe(false); + // 兜底收口不写终态时间：命令返回不等于知道这一轮真正的结束时刻。 + expect(stopped.turnEndedAt).toBe(0); + + // 同一轮迟到的 turn.started 不再把它拉回运行态，运行态条目也没丢。 + const revived = reduceDirectThreadEvents(stopped, [ + event(withUserItemId({ type: 'turn.started', at: 2_000 }, identity)), + ]); + expect(revived.turnRunning).toBe(false); + expect(selectDirectChatEntries(revived)).toHaveLength(1); + + // 宿主随后补上的真终态照旧收口，并把真正的结束时间补上。 + const late = reduceDirectThreadEvents(revived, [ + event( + withUserItemId( + { type: 'turn.completed', status: 'failed', at: 3_000 }, + identity, + ), + ), + ]); + expect(late.turnRunning).toBe(false); + expect(late.turnEndedAt).toBe(3_000); + }); + + it('本地命令兜底收口不碰身份不同的那轮', () => { + const other = reduceDirectThreadEvents(emptyDirectThreadChatState(), [ + event( + withUserItemId( + { type: 'turn.started', at: 1_000 }, + 'direct-codex:client-turn-9:user', + ), + ), + ]); + expect( + stopDirectThreadTurn(other, 'direct-codex:client-turn-1:user') + .turnRunning, + ).toBe(true); + }); + it('历史切片搬运层不合并，合并发生在前端投影', () => { const state = mergeDirectHistoryItems(emptyDirectThreadChatState(), [ toolStarted(), diff --git a/apps/ai-game-creator-shell/tests/directTurnPresentation.test.ts b/apps/ai-game-creator-shell/tests/directTurnPresentation.test.ts index 853c930cd..1b95a2c0a 100644 --- a/apps/ai-game-creator-shell/tests/directTurnPresentation.test.ts +++ b/apps/ai-game-creator-shell/tests/directTurnPresentation.test.ts @@ -184,7 +184,7 @@ describe('DirectProject 聊天分区', () => { ], turnRunning: true, }); - expect(turns[0]?.active).toBe(true); + expect(turns[0]?.state).toBe('running'); expect(turns[0]?.finals).toEqual([]); expect(turns[0]?.process.map((block) => block.kind)).toEqual([ 'assistant', @@ -293,7 +293,63 @@ describe('DirectProject 聊天分区', () => { }); expect(turns.map((turn) => turn.key)).toEqual(['u1', 'local:1']); expect(turns[1]?.users).toHaveLength(1); - expect(turns[1]?.active).toBe(true); + expect(turns[1]?.state).toBe('running'); + }); + + it('三态：本地已发出、原生还没认领的那一轮是 awaiting-start，不是已结束', () => { + const turns = buildDirectChatTurns({ + entries: [], + localMessages: [localUser('本轮提问', 'direct-codex:turn-1:user')], + pendingUserItemId: 'direct-codex:turn-1:user', + }); + expect(turns.map((turn) => turn.state)).toEqual(['awaiting-start']); + expect(turns[0]?.endedAt).toBe(0); + expect(turns[0]?.startedAt).toBe(1_800_000_002_000); + }); + + it('三态：原生用户条目先到、turn.started 还没到时仍是 awaiting-start', () => { + const turns = buildDirectChatTurns({ + // 同身份的原生条目已经到了（本地气泡被去重），但原生回合还没开始。 + entries: [userEntry('direct-codex:turn-1:user')], + localMessages: [localUser('本轮提问', 'direct-codex:turn-1:user')], + pendingUserItemId: 'direct-codex:turn-1:user', + }); + expect(turns.map((turn) => turn.state)).toEqual(['awaiting-start']); + }); + + it('三态：拿到明确终态后，在途身份不再把这一轮判成待认领', () => { + const turns = buildDirectChatTurns({ + entries: [ + { + ...userEntry('direct-codex:turn-1:user'), + turnEndedAt: 1_800_000_010_000, + }, + ], + pendingUserItemId: 'direct-codex:turn-1:user', + }); + expect(turns[0]?.state).toBe('finished'); + expect(turns[0]?.endedAt).toBe(1_800_000_010_000); + }); + + it('三态：只有最新一轮能是 awaiting-start，身份不匹配也不影响判定', () => { + const notNewest = buildDirectChatTurns({ + entries: [userEntry('direct-codex:turn-1:user')], + localMessages: [localUser('第二条', 'direct-codex:turn-2:user')], + pendingUserItemId: 'direct-codex:turn-1:user', + }); + expect(notNewest.map((turn) => turn.state)).toEqual([ + 'finished', + 'finished', + ]); + const mismatch = buildDirectChatTurns({ + entries: [userEntry('u1')], + localMessages: [localUser('第二条', 'direct-codex:turn-2:user')], + pendingUserItemId: 'direct-codex:turn-9:user', + }); + expect(mismatch.map((turn) => turn.state)).toEqual([ + 'finished', + 'finished', + ]); }); it('历史无用户条目时也保留一个回合承载正文', () => { diff --git a/docs/adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md b/docs/adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md index 0642ca205..48a2e5933 100644 --- a/docs/adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md +++ b/docs/adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md @@ -51,5 +51,7 @@ AGC 项目开发聊天框当前同时从三处取数据：Direct 回合事件（ - 旧项目磁盘上遗留的 `turn-stream.jsonl` / `tool-calls.jsonl` 保留不动，不迁移、不清理、不再由 DirectProject 聊天框读取。 - 工具卡片的脱敏与截断必须在读取期执行一次，不能因为"原始条目已在磁盘"就把未脱敏内容直接渲染到界面。 - 回合结束语义务必由 `turn.completed` 判定；缺少该事件的残留回合不得被渲染成运行中。 +- 「活动回合的唯一判据」约束的是**原生回合**：界面上的「本地已发出、原生还没认领」是投影的展示态（`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 会话核对仍列为运行时验收项。 diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 5913f4cfb..ccdb61e08 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -9312,3 +9312,30 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在 - 决策（空白口径）：`directCodexContentToPromptText` 逐字投影、不再 `trim`（前端只在整条 content 上判空）；出站提示词的收边规范化收敛成一个共享函数 `resourceCanvasAssetGenerationPromptText`，面板校验与任务落账共用，图集走 Unicode White_Space、其余走 JS 口径。 - 影响面：`apps/ai-game-creator-shell/src/features/{project-workspace/resourceReferences.ts,project-workspace/ResourceReferenceInput.tsx,resource-canvas/ResourceCanvasAssetGenerationPanelView.tsx,resource-canvas/resourceCanvasAssetGenerationTaskModel.ts,resource-canvas/resourceCanvasAssetGenerationReferenceModel.ts}`、`apps/ai-game-creator-shell/src/view/project-development/index.tsx` 与对应 6 个定向测试文件。 - 验证：定向 `resourceCanvasAssetGenerationReferences` / `resourceCanvasAssetGenerationBackgroundClose` / `resourceCanvasBottomToolbar` / `resourceCanvasGenerationFloatingPanel(Chrome)` / `resourceReferenceInput` / `resourceReferences` / `resourceCanvasAssetGenerationTasksPanel` 全绿；全量 `npm run test -- apps/ai-game-creator-shell/tests` 只剩 `clientHttp` / `clientApi` / `clientAuthStorage` / `projectCreationDirectory` / `recentProjectsHook` 五个 jsdom `localStorage` 环境用例红（与本次改动无调用关系）；TS typecheck、`check:encoding`、`git diff --check` 通过。未复核真实客户端观感。 + +## 2026-09-22 DirectProject 聊天状态显式化：回合三态 + 「在跑吗」唯一派生入口 + 数据流地图 + +- 背景：DirectProject 聊天框只有三份真相源（`project.jsonl` 历史切片、Thread Manager 运行态事件、本地乐观消息），但「这一轮在跑吗」在四层里各叫一个名字——reducer 的 `turnRunning`、controller 的 `turnBusy`、视图里手拼的 `busy`、投影里的 `active`。定位发送后空窗缺陷时，读代码无法判断某个窗口期的界面表现是否有依据，也说不清谁该信谁。 +- 决策（三态取代布尔）：`DirectChatTurn.active` 改为 `DirectChatTurn.state: 'running' | 'awaiting-start' | 'finished'`。`running` 只由 reducer 的 `turnRunning` 决定；`awaiting-start` 由「最新一轮的用户条目身份 = 本地在途的 `pendingUserItemId`（`direct-codex:{clientTurnId}:user`）、且本轮还没有明确终态」决定；其余是 `finished`。判据是身份不是时间戳，`pendingUserItemId` 由 controller 在 `beginTurnCommand()` / `endTurnCommand()` 里与 `turnBusy` 同生共死。 +- 决策（单一派生入口）：新增 `useDirectProjectTurnStatus()`，返回 `{ nativeRunning, commandInFlight, displayBusy, latestTurnState }`。header / composer 只读 `displayBusy`（两者并集，语义与原来的 `turnBusy || directTurnRunning` 完全一致），「陶泥儿正在处理」卡片只读 `nativeRunning`。约定：新增「忙 / 在跑」类判据先落进这里，不在组件里另拼布尔。 +- 决策（地图落代码）：三层数据流、三份原始输入、一次发送的时序（含空窗步骤）与状态变量归属写进 `apps/ai-game-creator-shell/src/view/project-development/chat/controller/useDirectProjectChatController.ts` 的模块注释；回合三态的定义与判据真值表写进 `.../conversation/directTurnPresentation.ts` 的 `DirectChatTurnState`。不另开技术方案文档——这套说明是给改这块代码的人看的，放代码里才不会与实现脱节。ADR 补一条「活动回合唯一判据约束的是**原生回合**」的澄清与代码指针。 +- 口径更正（2026-09-22，同日第二条）：本条记录的「`awaiting-start` 暂时与 `finished` 同渲染」已由随后的三态接入渲染改动修掉，见下面那条。 +- 边界（本次不修）：`awaiting-start` 暂时与 `finished` 同渲染，所以空窗期内仍会显示「本轮结束于 <用户发送时间> · 耗时 0.0秒」；`Math.max(turn.endedAt, turn.startedAt)` 的兜底与 `DirectProjectTurnUsage` 的渲染条件都没动。同源的第二条缺陷也记录在案：`turnEndedAt` 只是会话内展示缓存，页面重进后所有已结束回合都会走同一条兜底显示 0.0 秒（临时渲染用例实测确认，用例未入库）。修法与证据要求见下面那条（三态接入渲染）以及 `DirectProjectTurn.tsx` 里标注未修范围的注释。 +- 验证：`npx vitest run` 定向 `directTurnPresentation`（17 条，新增 4 条三态用例）、`directProjectTurnStatus`（4 条）、`directHistoryPaging`（9 条）全绿；`appSurface.test.ts` 202 passed / 13 skipped；`tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 通过。真实客户端观感与窗口期表现未在客户端复核。 + +## 2026-09-22 空窗期不再谎报「本轮结束」：DirectProject 三态接入渲染 + +- 背景：上一条只把回合三态显式化，渲染层仍按 `state === 'running'` 判断，于是「本地已发出、宿主还没回 `turn.started`」的窗口里 `awaiting-start` 被当成 `finished` 渲染，显示「本轮结束于 <用户发送时间> · 耗时 0.0秒」（用户现场反馈的现象）。 +- 决策（判据分两类，不许对调）：**否定式**判断（不要说它结束、不要折叠过程、不要显示终态文案）读 `state !== 'finished'`；**肯定式**判断（哪段正文在流式、「陶泥儿正在处理」卡片与滚动已耗时）读 `state === 'running'`。理由是 `awaiting-start` 能支持"还没结束"，但不能支持"宿主已经在跑"——后者只有 `turn.started` 能证明。 +- 决策（卡片口径取保守）：`DirectProjectConversation` 的「正在处理」卡片与 `activeTurnStartedAt` 仍只认 `turnStatus.nativeRunning`，窗口期不出现这张卡片。文案是「陶泥儿正在处理」，在 `turn.started` 之前无法断言宿主已经开始，这与空窗缺陷是同一个病根（把"本地已发出"当成"宿主已在跑"）；窗口期用户看到的是"消息已发出 + 输入框忙"，语义诚实。若将来改成窗口期也显示卡片，`running` 在渲染层就没有消费者了，那时应把投影压成 `unfinished: boolean`，不要留一个没人读的状态成员。 +- 边界（A 仍未修）：`DirectProjectTurnUsage` 的 `Math.max(turn.endedAt, turn.startedAt)` 兜底没动，所以两类 `finished` 回合仍显示「耗时 0.0秒」——① 页面重进后读回来的历史回合（`turnEndedAt` 只是会话内展示缓存）；② 发送后没有产生任何原生事件 / 发送失败的本地回合。为什么会有这两类、修法与要产品确认的口径都写在代码里（`DirectProjectTurn.tsx` 的 `DirectProjectTurnUsage` 注释与 `directTurnPresentation.ts` 的 `DirectChatTurnState` 注释），改完删掉那段注释。 +- 验证：`tests/directProjectTurn.test.tsx`（新增 3 条渲染契约：`awaiting-start` 与 `running` 不显示终态文案且不折叠、`finished` 有终态时显示结束时间与耗时）；`tests/appSurface/chat-composer.suite.ts` 新增 `does not report a finished turn while the host has not acknowledged the send yet`（invoke 挂起、无任何原生事件时断言不出现「本轮结束于」）；变异验证：把 `state !== 'finished'` 退回 `state === 'running'` 后渲染契约用例变红，恢复即绿。定向 vitest、`appSurface.test.ts`（203 passed / 13 skipped）、`tsc`、ESLint、Prettier、`check:encoding`、`check:doc-index`、`git diff --check` 通过。真实客户端观感未复核。 + +## 2026-09-22 宿主崩掉不再留下永远开着的回合：本地命令失败时按身份兜底收口 + +- 背景：`turn.started` / `turn.completed` 是原生回合唯一的开闭配对，界面上的「正在处理」卡片与输入盒忙态都读 reducer 的 `turnRunning`。但 app-server 崩了、回合任务被中止或 panic 时没人补终态事件，事件流里就留一条永远开着的 `turn.started`：界面一直显示「陶泥儿正在处理」、输入盒一直排队（用户现场反馈）。 +- 决策（本地命令返回即这一轮在宿主那边收场）：`chat_with_game_creator_direct_codex` 以真失败返回时，controller 按本轮身份调用 `stopDirectThreadTurn`，只放掉「是否在跑」，**不写终态时间**——命令返回不等于知道这一轮真正的结束时刻，编一个只会让耗时变成假数。用户主动终止与「正在跑的是另一轮」两条不适用：前者宿主必然补终态，后者不是这一轮（不能顺手抹掉别人的回合）。 +- 决策（身份作用域 + 不复活）：`stopDirectThreadTurn` 只在 reducer 里的运行身份相同或为空时生效；收口记进 `commandClosedTurnUserItemId`，同身份迟到的 `turn.started` 不再把这一轮拉回运行态（迟到的 `turn.completed` 例外放行，仍要拿它补上真正的结束时间）。身份按 clientTurnId 唯一，所以这条记忆只挡它自己那一轮。 +- 影响面：`apps/ai-game-creator-shell/src/view/project-development/chat/{conversation/directThreadChat.ts,controller/useDirectThreadChatSubscription.ts,controller/useDirectProjectChatController.ts}` 与 `apps/ai-game-creator-shell/tests/{directThreadChat.test.ts,appSurface/chat-composer.suite.ts}`。 +- 验证：reducer 新增 2 条用例（兜底收口后同名 `turn.started` 不复活且真终态仍能补上结束时间；身份不同的回合不动），appSurface 新增 `stops claiming the turn is running when a failed send left turn.started open`；变异验证：拿掉 controller 里的兜底收口调用后该用例变红（界面仍显示「陶泥儿正在处理」），恢复即绿。 +- 边界（未做）：根因仍在宿主侧——要在进程内保证开闭配对，应由 Rust 在回合函数退出（含 panic / 任务中止）时补一条终态事件（drop 守卫）；本次只做到前端不再跟着说谎。另：兜底收口的回合没有终态时间，仍会落进「`finished` 但拿不到终态时间」那个已知缺口（终态文案要不要藏，见 `DirectProjectTurn.tsx` 与 `DirectChatTurnState` 注释里的 A 项）。