@meiyukichan/dsh-sandore 0.1.0-rc.6

package/packages/client/chat-flow.spec.ts

@@ -0,0 +1,357 @@
+/**
+ * chat-flow 纯逻辑单测（node 环境，无 React / 无 DSH 运行时依赖）。
+ * @module @deepseek-ai/dsh-client-ui-sandore/src/client/chat-flow.spec
+ */
+import { describe, expect, it } from 'vitest'
+import type {
+  CommandNode, ConversationNode, PartialAssistant, RunningToolCall,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { buildStepChatFlow, STEP_CHAT_MAX_NODES, type StepChatFlowRow } from './chat-flow.ts'
+
+// ── mock 工厂：构造结构合法的 ConversationNode / snapshot 输入 ─────────────
+
+function userNode(seq: number, text: string): ConversationNode {
+  return { kind: 'user', seq, time: seq * 1000, content: [{ type: 'text', text }], source: {} }
+}
+
+function steeringNode(seq: number, text: string): ConversationNode {
+  return { kind: 'steering', seq, time: seq * 1000, messageId: `m-${seq}` as never, content: [{ type: 'text', text }], source: {} } as unknown as ConversationNode
+}
+
+function assistantNode(
+  seq: number,
+  turn: number,
+  step: number,
+  text: string,
+  toolCalls: ReadonlyArray<{ callId: string; name: string; argsRaw: string }> = [],
+): ConversationNode {
+  return {
+    kind: 'assistant',
+    seq,
+    time: seq * 1000,
+    turn,
+    step,
+    blocks: [
+      ...(text === '' ? [] : [{ kind: 'text' as const, text }]),
+      ...toolCalls.map((call) => ({ kind: 'tool-call' as const, ...call })),
+    ],
+  }
+}
+
+function toolResultNode(
+  seq: number,
+  callId: string,
+  text: string,
+  opts: { isError?: boolean; call?: { name: string; argsRaw: string } | null } = {},
+): ConversationNode {
+  return {
+    kind: 'tool-result',
+    seq,
+    time: seq * 1000,
+    callId,
+    call: opts.call ?? null,
+    callTime: null,
+    content: [{ type: 'text', text }],
+    isError: opts.isError ?? false,
+    callView: null,
+    resultView: null,
+    subCalls: [],
+  }
+}
+
+function commandNode(
+  seq: number,
+  opts: {
+    name?: string | null
+    args?: string | null
+    outcome?: CommandNode['outcome']
+  } = {},
+): ConversationNode {
+  return {
+    kind: 'command',
+    seq,
+    time: seq * 1000,
+    commandId: `cmd-${seq}` as never,
+    name: opts.name ?? 'ls',
+    args: opts.args ?? '',
+    outcome: opts.outcome ?? null,
+  } as unknown as ConversationNode
+}
+
+/** 边缘节点工厂：compaction / unknown / context / model-retry / turn-error / turn-max-tokens。 */
+function edgeNode(
+  kind: 'compaction' | 'unknown' | 'context' | 'model-retry' | 'turn-error' | 'turn-max-tokens',
+  seq: number,
+): ConversationNode {
+  const base = { kind, seq, time: seq * 1000 } as object
+  switch (kind) {
+    case 'compaction':
+      return { ...base, summary: null, summaryEventSeq: null, shadowedItemCount: null, shadowedTokenCount: null } as unknown as ConversationNode
+    case 'unknown':
+      return { ...base, type: 'surface/whatever', data: {} } as unknown as ConversationNode
+    case 'context':
+      return {
+        ...base, content: [], source: {},
+        provenance: { kind: 'system', producer: 'x' },
+        form: null,
+      } as unknown as ConversationNode
+    case 'model-retry':
+      return {
+        ...base, turn: 1, step: 0, retry: 1, maxRetries: 2, mode: 'normal', delayMs: 1_000,
+        retryState: 'scheduled', failure: { message: 'boom' },
+      } as unknown as ConversationNode
+    case 'turn-error':
+      return { ...base, turn: 1, step: 0, message: 'failed' } as unknown as ConversationNode
+    case 'turn-max-tokens':
+      return { ...base, turn: 1, step: 0 } as unknown as ConversationNode
+  }
+}
+
+function snapshot(
+  nodes: readonly ConversationNode[],
+  opts: {
+    partial?: PartialAssistant | null
+    runningCalls?: readonly RunningToolCall[]
+    turnTimings?: ReadonlyMap<number, { readonly startTime: number; readonly endTime?: number }>
+  } = {},
+): { nodes: readonly ConversationNode[]; partial: PartialAssistant | null; runningCalls: readonly RunningToolCall[]; turnTimings?: ReadonlyMap<number, { readonly startTime: number; readonly endTime?: number }> } {
+  return { nodes, partial: opts.partial ?? null, runningCalls: opts.runningCalls ?? [], ...(opts.turnTimings === undefined ? {} : { turnTimings: opts.turnTimings }) }
+}
+
+/** 断言辅助：把 readonly 展示行数组收窄为可索引读的行类型。 */
+function asRows(result: readonly StepChatFlowRow[]): readonly StepChatFlowRow[] {
+  return result
+}
+
+// ── 用户/助手消息映射 ──────────────────────────────────────────────────────
+
+describe('buildStepChatFlow：用户/助手消息映射', () => {
+  it('user → 用户行（携带 node）；assistant → agent 行（blocks/非流式）', () => {
+    const rows = asRows(buildStepChatFlow(snapshot([
+      userNode(1, '你好'),
+      assistantNode(2, 1, 0, '收到'),
+    ])))
+    expect(rows).toEqual([
+      { kind: 'user', key: 'user-1', node: expect.objectContaining({ kind: 'user', content: [{ type: 'text', text: '你好' }], time: 1000 }) },
+      { kind: 'agent', key: 'assistant-2', blocks: [{ kind: 'text', text: '收到' }], streaming: false, interrupted: false },
+    ])
+  })
+
+  it('steering 节点按用户行渲染（右气泡语义）', () => {
+    const rows = asRows(buildStepChatFlow(snapshot([steeringNode(1, '插话')])))
+    expect(rows[0]).toMatchObject({ kind: 'user', key: 'steering-1' })
+    expect(rows[0]?.kind === 'user' ? rows[0].node : null).toMatchObject({ kind: 'steering', time: 1000 })
+  })
+})
+
+// ── 工具行映射与配对 ───────────────────────────────────────────────────────
+
+describe('buildStepChatFlow：工具行映射与配对', () => {
+  it('assistant 的 tool-call 块展开为工具行（RunningToolCall 数据面）', () => {
+    const rows = asRows(buildStepChatFlow(snapshot([
+      assistantNode(2, 1, 0, '', [{ callId: 'c1', name: 'bash', argsRaw: '{"cmd":"ls"}' }]),
+    ])))
+    expect(rows).toHaveLength(2)
+    expect(rows[1]).toMatchObject({ kind: 'tool', key: 'tool-c1', toolName: 'bash' })
+    expect(rows[1]?.kind === 'tool' ? rows[1].block : null).toMatchObject({ callId: 'c1', name: 'bash', argsRaw: '{"cmd":"ls"}' })
+  })
+
+  it('tool-result 与同 callId 工具行配对：同一行替换为 settled（block 变 ToolResultNode）', () => {
+    const rows = asRows(buildStepChatFlow(snapshot([
+      assistantNode(2, 1, 0, '', [{ callId: 'c1', name: 'bash', argsRaw: '{}' }]),
+      toolResultNode(3, 'c1', 'a.ts\nb.ts'),
+    ])))
+    expect(rows).toHaveLength(2)
+    expect(rows[1]).toMatchObject({ kind: 'tool', key: 'tool-c1' })
+    const block = rows[1]?.kind === 'tool' ? rows[1].block : null
+    expect(block).toMatchObject({ kind: 'tool-result', callId: 'c1', isError: false })
+  })
+
+  it('窗口截断导致 call 头不可见时 tool-result 单列（name 回退 call 回填 / callId）', () => {
+    const rows = asRows(buildStepChatFlow(snapshot([
+      toolResultNode(3, 'c1', 'ok', { call: { name: 'read', argsRaw: '{"path":"a"}' } }),
+    ])))
+    expect(rows[0]).toMatchObject({ kind: 'tool', key: 'tool-result-3', toolName: 'read' })
+  })
+
+  it('命令节点 → 命令行', () => {
+    const rows = asRows(buildStepChatFlow(snapshot([
+      commandNode(4, { name: 'permission', args: 'read', outcome: null }),
+    ])))
+    expect(rows[0]).toMatchObject({ kind: 'command', key: 'command-4' })
+    expect(rows[0]?.kind === 'command' ? rows[0].node : null).toMatchObject({ name: 'permission', outcome: null })
+  })
+})
+
+// ── 边缘节点映射（DSH conversation.chat.node 各 keyed 渲染器对应行） ───────
+
+describe('buildStepChatFlow：边缘节点映射', () => {
+  it('context/compaction/unknown/model-retry/turn-error/turn-max-tokens → 对应展示行', () => {
+    const rows = asRows(buildStepChatFlow(snapshot([
+      userNode(1, '你好'),
+      edgeNode('context', 2),
+      edgeNode('compaction', 3),
+      edgeNode('unknown', 4),
+      edgeNode('model-retry', 5),
+      edgeNode('turn-error', 6),
+      edgeNode('turn-max-tokens', 7),
+      assistantNode(8, 1, 0, '收到'),
+    ])))
+    expect(rows.map((row) => row.kind)).toEqual([
+      'user', 'context', 'compaction', 'unknown', 'retry', 'turn-error', 'turn-max-tokens', 'agent',
+    ])
+    expect(rows[1]).toMatchObject({ kind: 'context', key: 'context-2' })
+    expect(rows[2]).toMatchObject({ kind: 'compaction', key: 'compaction-3' })
+    expect(rows[3]).toMatchObject({ kind: 'unknown', key: 'unknown-4' })
+    expect(rows[4]).toMatchObject({ kind: 'retry', key: 'retry-5' })
+    expect(rows[5]).toMatchObject({ kind: 'turn-error', key: 'turn-error-6' })
+    expect(rows[6]).toMatchObject({ kind: 'turn-max-tokens', key: 'turn-max-tokens-7' })
+    // 行携带公开节点数据（渲染器直接消费）
+    expect(rows[1]?.kind === 'context' ? rows[1].node : null).toMatchObject({ kind: 'context', seq: 2 })
+    expect(rows[2]?.kind === 'compaction' ? rows[2].node : null).toMatchObject({ kind: 'compaction', seq: 3 })
+    expect(rows[3]?.kind === 'unknown' ? rows[3].node : null).toMatchObject({ kind: 'unknown', type: 'surface/whatever' })
+    expect(rows[4]?.kind === 'retry' ? rows[4].node : null).toMatchObject({ kind: 'model-retry', retryState: 'scheduled' })
+    expect(rows[5]?.kind === 'turn-error' ? rows[5].node : null).toMatchObject({ kind: 'turn-error', message: 'failed' })
+  })
+})
+
+// ── partial 流式 ───────────────────────────────────────────────────────────
+
+describe('buildStepChatFlow：partial 流式', () => {
+  it('partial 追加为流式 agent 行 + 运行中工具行', () => {
+    const rows = asRows(buildStepChatFlow(snapshot([userNode(1, '开始')], {
+      partial: {
+        turn: 1,
+        step: 0,
+        blocks: [
+          { kind: 'text', text: '正在写代码' },
+          { kind: 'tool-call', callId: 'c1', name: 'write', argsRaw: '{"path":"a.ts"}' },
+        ],
+      },
+    })))
+    expect(rows).toEqual([
+      { kind: 'user', key: 'user-1', node: expect.objectContaining({ kind: 'user', time: 1000 }) },
+      {
+        kind: 'agent', key: 'partial-agent-1-0',
+        blocks: [
+          { kind: 'text', text: '正在写代码' },
+          { kind: 'tool-call', callId: 'c1', name: 'write', argsRaw: '{"path":"a.ts"}' },
+        ],
+        streaming: true, interrupted: false,
+      },
+      { kind: 'tool', key: 'partial-tool-c1', toolName: 'write', block: expect.objectContaining({ callId: 'c1', name: 'write' }) },
+    ])
+  })
+
+  it('partial 与已结算节点共存（历史节点 + 流式尾巴）', () => {
+    const rows = asRows(buildStepChatFlow(snapshot([
+      userNode(1, 'q'),
+      assistantNode(2, 1, 0, '已完结'),
+    ], {
+      partial: { turn: 2, step: 0, blocks: [{ kind: 'text', text: '新一轮' }] },
+    })))
+    const agentRows = rows.filter((row) => row.kind === 'agent')
+    expect(agentRows).toHaveLength(2)
+    expect(agentRows[1]).toMatchObject({ key: 'partial-agent-2-0', streaming: true })
+  })
+})
+
+// ── turn-tail 派生（DSH 'turn-tail' ChatNode 语义） ────────────────────────
+
+describe('buildStepChatFlow：turn-tail 派生', () => {
+  it('已完结 turn（turnTimings 有 endTime）→ 关闭行后插入 tail 行（文本/时长/指标）', () => {
+    const nodes: ConversationNode[] = [
+      userNode(1, 'q'),
+      assistantNode(2, 1, 0, '答', undefined),
+    ]
+    const rows = asRows(buildStepChatFlow(snapshot(nodes, {
+      turnTimings: new Map([[1, { startTime: 10_000, endTime: 15_000 }]]),
+    })))
+    expect(rows).toHaveLength(3)
+    expect(rows[1]).toMatchObject({ kind: 'agent', key: 'assistant-2' })
+    expect(rows[2]).toMatchObject({ kind: 'tail', key: 'tail-1' })
+    const tail = rows[2]?.kind === 'tail' ? rows[2].data : null
+    expect(tail).toMatchObject({ turn: 1, seq: 2, time: 2000, text: '答', runMs: 5_000, branchUnavailable: false })
+  })
+
+  it('无 endTime（turn 未完结 / end 在窗口外）→ 不产出 tail', () => {
+    const nodes: ConversationNode[] = [
+      userNode(1, 'q'),
+      assistantNode(2, 1, 0, '答'),
+    ]
+    const rows = asRows(buildStepChatFlow(snapshot(nodes, {
+      turnTimings: new Map([[1, { startTime: 10_000 }]]),
+    })))
+    expect(rows.filter((row) => row.kind === 'tail')).toHaveLength(0)
+  })
+
+  it('不提供 turnTimings（旧输入面）→ 不产出 tail', () => {
+    const rows = asRows(buildStepChatFlow(snapshot([
+      userNode(1, 'q'),
+      assistantNode(2, 1, 0, '答'),
+    ])))
+    expect(rows.filter((row) => row.kind === 'tail')).toHaveLength(0)
+  })
+
+  it('关闭行后有工具结算（turn 尾部非文本）→ branchUnavailable=true', () => {
+    const nodes: ConversationNode[] = [
+      userNode(1, 'q'),
+      assistantNode(2, 1, 0, '正在处理', [{ callId: 'c1', name: 'bash', argsRaw: '{}' }]),
+      toolResultNode(3, 'c1', 'ok'),
+    ]
+    const rows = asRows(buildStepChatFlow(snapshot(nodes, {
+      turnTimings: new Map([[1, { startTime: 10_000, endTime: 20_000 }]]),
+    })))
+    const tail = rows.find((row) => row.kind === 'tail')
+    expect(tail).toBeDefined()
+    expect(tail?.kind === 'tail' ? tail.data.branchUnavailable : null).toBe(true)
+  })
+
+  it('多个已完结 turn → 每个 turn 的关闭行后各插一条 tail，顺序稳定', () => {
+    const nodes: ConversationNode[] = [
+      userNode(1, 'q1'),
+      assistantNode(2, 1, 0, '答1'),
+      userNode(3, 'q2'),
+      assistantNode(4, 2, 0, '答2'),
+    ]
+    const rows = asRows(buildStepChatFlow(snapshot(nodes, {
+      turnTimings: new Map([
+        [1, { startTime: 10_000, endTime: 11_000 }],
+        [2, { startTime: 20_000, endTime: 22_000 }],
+      ]),
+    })))
+    expect(rows.map((row) => row.kind)).toEqual(['user', 'agent', 'tail', 'user', 'agent', 'tail'])
+    expect(rows[2]).toMatchObject({ key: 'tail-1' })
+    expect(rows[5]).toMatchObject({ key: 'tail-2' })
+  })
+})
+
+// ── 截断 ───────────────────────────────────────────────────────────────────
+
+describe('buildStepChatFlow：最新 10 条节点截断', () => {
+  it(`超过 ${STEP_CHAT_MAX_NODES} 条节点时只保留最新 ${STEP_CHAT_MAX_NODES} 条`, () => {
+    const nodes: ConversationNode[] = []
+    for (let i = 1; i <= 8; i++) {
+      nodes.push(userNode(i * 2 - 1, `q${i}`))
+      nodes.push(assistantNode(i * 2, i, 0, `a${i}`))
+    }
+    const rows = asRows(buildStepChatFlow(snapshot(nodes)))
+    // 16 节点截尾 10 → 首行 user q4（seq 7）。
+    expect(rows).toHaveLength(STEP_CHAT_MAX_NODES)
+    expect(rows[0]).toMatchObject({ kind: 'user', key: 'user-7' })
+    expect(rows[rows.length - 1]).toMatchObject({ kind: 'agent', key: 'assistant-16' })
+  })
+
+  it('截断发生在节点层（assistant 展开的工具行不挤出窗口外的节点）', () => {
+    const nodes: ConversationNode[] = []
+    for (let i = 1; i <= 6; i++) {
+      nodes.push(userNode(i * 2 - 1, `q${i}`))
+      nodes.push(assistantNode(i * 2, i, 0, `a${i}`, [{ callId: `c${i}`, name: 'bash', argsRaw: '{}' }]))
+    }
+    const rows = asRows(buildStepChatFlow(snapshot(nodes)))
+    // 12 节点（q1..q6 + a1..a6）截尾 10 → q2..a6（seq 3..12）；每个 assistant
+    // 展开 1 工具行 → 5 user + 5×2 = 15 行。
+    expect(rows[0]).toMatchObject({ kind: 'user', key: 'user-3' })
+    expect(rows[rows.length - 1]).toMatchObject({ kind: 'tool', key: 'tool-c6' })
+  })
+})

package/packages/client/chat-flow.ts

@@ -0,0 +1,278 @@
+/**
+ * chat-flow：轻量子代理面板的纯逻辑层（无 React / 无 DSH 运行时依赖，vitest node
+ * 环境可跑）。对应 DSH ChatView 的「组装层→渲染行」语义：
+ *
+ * - 从 `snapshot.nodes`（公开 `ConversationNode[]`，已排序）取**最新 10 条节点**；
+ * - assistant 节点的 tool-call 块展开为独立工具行（与 DSH 把 tool-call 组装为独立
+ *   'tool-call' 行的行为一致），tool-result 节点与同 callId 的未结算工具行**配对**
+ *   （替换该行——即 DSH 的「同一行从 running 更新为 settled」），窗口截断导致 call
+ *   头不可见时单列（与 DSH 的 soft-fall 一致）；
+ * - `partial`（流式 assistant 增量）追加为流式 agent 行 + 运行中工具行；
+ * - context/compaction/model-retry/turn-error/turn-max-tokens/unknown 等边缘节点映射为
+ *   展示行（对应 DSH `conversation.chat.node` 各 keyed 渲染器）；
+ * - 已完结 turn（`turnTimings`/`turnEnds` 提供时）在其结算 assistant 行后派生
+ *   **turn-tail 行**（对应 DSH 的 'turn-tail' ChatNode：复制 + 运行时长/TTFT/吞吐 +
+ *   branch；branchUnavailable 近似为「结算行不是面板最后一行」）。
+ *
+ * 组件层（StepChatPanel）把 `StepChatFlowRow` 逐一映射为抄自 DSH 的渲染组件。
+ * @module @deepseek-ai/dsh-client-ui-sandore/src/client/chat-flow
+ */
+import type {
+  AssistantBlock, CommandNode, CompactionSummaryNode, ContextMessageNode, ConversationNode, ModelRetryNode,
+  PartialAssistant, RunningToolCall, ToolCallBlock, TurnErrorNode, TurnMaxTokensNode,
+  UnknownSurfaceNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { assistantText } from './chat/turn-assistant.ts'
+import { deriveTurnMetrics } from './chat/turn-metrics.ts'
+
+/** 面板展示的最大节点数（轻量面板：仅最新 10 条节点）。 */
+export const STEP_CHAT_MAX_NODES = 10
+
+/**
+ * `buildStepChatFlow` 的最小快照输入面（只读 nodes/partial/runningCalls；
+ * `ConversationSnapshot` 结构上满足它，单测可直接构造小对象）。
+ */
+export interface StepChatFlowInput {
+  readonly nodes: readonly ConversationNode[]
+  readonly partial: PartialAssistant | null
+  readonly runningCalls: readonly RunningToolCall[]
+  /** 已完结 turn 的时间边界（`ConversationSnapshot.turnTimings`）；缺省不派生 turn-tail。 */
+  readonly turnTimings?: ReadonlyMap<number, { readonly startTime: number; readonly endTime?: number }>
+}
+
+/** turn-tail 展示数据（对齐 DSH `TurnTailChatData` 的展示面；组件层消费）。 */
+export interface StepChatTailData {
+  /** 已完结 turn 号。 */
+  turn: number
+  /** 结算 assistant 节点 seq（分支锚点）。 */
+  seq: number
+  /** 结算时间（Unix epoch ms；时钟用）。 */
+  time: number
+  /** 结算 assistant 的拼接文本（复制按钮取文本）。 */
+  text: string
+  /** Turn 壁钟时长 ms；turn/start|end 均在窗口内时可用。 */
+  runMs?: number | undefined
+  /** Turn 首步 TTFT ms；未记录时省略。 */
+  ttftMs?: number | undefined
+  /** Turn 解码吞吐；未记录时省略。 */
+  tokensPerSecond?: number | undefined
+  /** 分支不可用（结算 assistant 非窗口尾部等）。 */
+  branchUnavailable: boolean
+}
+
+/** 一条展示行（kind 判别；key 为 React key，跨快照稳定）。 */
+export type StepChatFlowRow =
+  | {
+    readonly kind: 'user'
+    readonly key: string
+    readonly node: Extract<ConversationNode, { kind: 'user' | 'steering' }>
+  }
+  | {
+    readonly kind: 'agent'
+    readonly key: string
+    readonly blocks: readonly AssistantBlock[]
+    readonly streaming: boolean
+    readonly interrupted: boolean
+  }
+  | { readonly kind: 'tool'; readonly key: string; readonly toolName: string; readonly block: ToolCallBlock }
+  | { readonly kind: 'command'; readonly key: string; readonly node: CommandNode }
+  | { readonly kind: 'context'; readonly key: string; readonly node: ContextMessageNode }
+  | { readonly kind: 'compaction'; readonly key: string; readonly node: CompactionSummaryNode }
+  | { readonly kind: 'retry'; readonly key: string; readonly node: ModelRetryNode }
+  | { readonly kind: 'turn-error'; readonly key: string; readonly node: TurnErrorNode }
+  | { readonly kind: 'turn-max-tokens'; readonly key: string }
+  | { readonly kind: 'unknown'; readonly key: string; readonly node: UnknownSurfaceNode }
+  | { readonly kind: 'tail'; readonly key: string; readonly data: StepChatTailData }
+
+/** assistant 节点的 tool-call 块 → RunningToolCall（工具行 running 态数据面）。 */
+function runningCallOf(
+  block: Extract<AssistantBlock, { kind: 'tool-call' }>,
+  turn: number,
+  step: number,
+  time: number,
+): RunningToolCall {
+  return {
+    callId: block.callId,
+    name: block.name,
+    argsRaw: block.argsRaw,
+    turn,
+    step,
+    time,
+    callView: null,
+    subCalls: [],
+  }
+}
+
+/** 命令节点 → 展示行。 */
+function commandRow(node: CommandNode): StepChatFlowRow {
+  return { kind: 'command', key: `command-${node.seq}`, node }
+}
+
+/**
+ * tool-result 节点 → 工具行：优先与同 callId 的最后一条未结算工具行配对（原地替换，
+ * 即 DSH 的 running→settled 更新）；窗口截断导致 call 头不可见时单列（name 回退
+ * `call?.name ?? callId`）。
+ * @returns 配对成功返回 null（已原地替换）；否则返回新的单列行。
+ */
+function toolResultRow(
+  node: Extract<ConversationNode, { kind: 'tool-result' }>,
+  rows: StepChatFlowRow[],
+  toolIndexByCallId: Map<string, number>,
+): StepChatFlowRow | null {
+  const index = toolIndexByCallId.get(node.callId)
+  if (index !== undefined) {
+    const row = rows[index]
+    if (row !== undefined && row.kind === 'tool') {
+      // 配对：同一 callId 行从 running 更新为 settled（ToolResultNode ⊂ ToolCallBlock）。
+      rows[index] = { ...row, block: node }
+      return null
+    }
+  }
+  // 窗口截断：call 头不可见，退化为独立结果行（DSH soft-fall）。
+  return {
+    kind: 'tool',
+    key: `tool-result-${node.seq}`,
+    toolName: node.call?.name ?? node.callId,
+    block: node,
+  }
+}
+
+/** 关闭行文本判定（DSH `tailData.hasText`：finalNode 携带非空文本块）。 */
+function hasText(node: Extract<ConversationNode, { kind: 'assistant' }>): boolean {
+  return node.blocks.some(block => block.kind === 'text' && block.text.trim() !== '')
+}
+
+/** 已完结 turn 的关闭行 + tail 数据（在 agent 行之后插入）。 */
+interface PendingTail {
+  readonly rowIndex: number
+  readonly data: StepChatTailData
+}
+
+/**
+ * 快照 → 展示行（最新 10 条节点；assistant 展开为文本行 + 工具行；partial 追加在尾部；
+ * 已完结 turn 派生 turn-tail 行）。
+ */
+export function buildStepChatFlow(snapshot: StepChatFlowInput): readonly StepChatFlowRow[] {
+  const rows: StepChatFlowRow[] = []
+  const toolIndexByCallId = new Map<string, number>()
+  // turn → 最后一个带文本的 assistant 行索引 + 节点（tail 关闭行候选）。
+  const closingByTurn = new Map<number, { rowIndex: number; node: Extract<ConversationNode, { kind: 'assistant' }> }>()
+
+  const pushTool = (row: StepChatFlowRow): void => {
+    rows.push(row)
+    if (row.kind === 'tool') toolIndexByCallId.set(row.block.callId, rows.length - 1)
+  }
+
+  for (const node of snapshot.nodes.slice(-STEP_CHAT_MAX_NODES)) {
+    switch (node.kind) {
+      case 'user':
+        rows.push({ kind: 'user', key: `user-${node.seq}`, node })
+        break
+      case 'steering':
+        rows.push({ kind: 'user', key: `steering-${node.seq}`, node })
+        break
+      case 'assistant': {
+        rows.push({
+          kind: 'agent',
+          key: `assistant-${node.seq}`,
+          blocks: node.blocks,
+          streaming: false,
+          interrupted: node.interrupted === true,
+        })
+        if (hasText(node)) closingByTurn.set(node.turn, { rowIndex: rows.length - 1, node })
+        for (const block of node.blocks) {
+          if (block.kind !== 'tool-call') continue
+          pushTool({
+            kind: 'tool',
+            key: `tool-${block.callId}`,
+            toolName: block.name,
+            block: runningCallOf(block, node.turn, node.step, node.time),
+          })
+        }
+        break
+      }
+      case 'tool-result': {
+        const row = toolResultRow(node, rows, toolIndexByCallId)
+        if (row !== null) pushTool(row)
+        break
+      }
+      case 'command':
+        rows.push(commandRow(node))
+        break
+      case 'context':
+        rows.push({ kind: 'context', key: `context-${node.seq}`, node })
+        break
+      case 'compaction':
+        rows.push({ kind: 'compaction', key: `compaction-${node.seq}`, node })
+        break
+      case 'model-retry':
+        rows.push({ kind: 'retry', key: `retry-${node.seq}`, node })
+        break
+      case 'turn-error':
+        rows.push({ kind: 'turn-error', key: `turn-error-${node.seq}`, node })
+        break
+      case 'turn-max-tokens':
+        rows.push({ kind: 'turn-max-tokens', key: `turn-max-tokens-${node.seq}` })
+        break
+      case 'unknown':
+        rows.push({ kind: 'unknown', key: `unknown-${node.seq}`, node })
+        break
+    }
+  }
+
+  // 流式增量：assistant partial 追加为流式 agent 行 + 运行中工具行。
+  if (snapshot.partial !== null) {
+    const { turn, step, blocks } = snapshot.partial
+    rows.push({
+      kind: 'agent',
+      key: `partial-agent-${turn}-${step}`,
+      blocks,
+      streaming: true,
+      interrupted: false,
+    })
+    for (const block of blocks) {
+      if (block.kind !== 'tool-call') continue
+      pushTool({
+        kind: 'tool',
+        key: `partial-tool-${block.callId}`,
+        toolName: block.name,
+        block: runningCallOf(block, turn, step, Date.now()),
+      })
+    }
+  }
+
+  // turn-tail 派生：已完结 turn 的关闭行后插入 tail 行（DSH 'turn-tail' ChatNode 语义）。
+  if (snapshot.turnTimings !== undefined && closingByTurn.size > 0) {
+    const sliced = snapshot.nodes.slice(-STEP_CHAT_MAX_NODES)
+    const metrics = deriveTurnMetrics(sliced)
+    const tails: PendingTail[] = []
+    for (const [turn, closing] of closingByTurn) {
+      const timing = snapshot.turnTimings.get(turn)
+      // 无 turn/end：turn 未完结（或 end 在窗口外），DSH 同样不产出 tail。
+      if (timing === undefined || timing.endTime === undefined) continue
+      const turnMetrics = metrics.get(turn)
+      const data: StepChatTailData = {
+        turn,
+        seq: closing.node.seq,
+        time: closing.node.time,
+        text: assistantText(closing.node.blocks),
+        runMs: Math.max(0, timing.endTime - timing.startTime),
+        ...turnMetrics?.ttftMs === undefined ? {} : { ttftMs: turnMetrics.ttftMs },
+        ...turnMetrics?.tokensPerSecond === undefined ? {} : { tokensPerSecond: turnMetrics.tokensPerSecond },
+        // 近似（DSH 用 turn 内 tool/call|tool/result|error-end|retry 的 latest seq 比较）：
+        // 窗口内该 turn 的关闭行之后还有任何行（工具结算等）→ 分支不可用。
+        branchUnavailable: closing.rowIndex !== rows.length - 1,
+      }
+      tails.push({ rowIndex: closing.rowIndex, data })
+    }
+    // 按关闭行索引升序插入（前面已插入的 tail 使后续目标索引后移），保证多 turn 顺序稳定。
+    tails.sort((a, b) => a.rowIndex - b.rowIndex)
+    let inserted = 0
+    for (const tail of tails) {
+      rows.splice(tail.rowIndex + 1 + inserted, 0, { kind: 'tail', key: `tail-${tail.data.turn}`, data: tail.data })
+      inserted += 1
+    }
+  }
+
+  return rows
+}