perf(tui): child transcript 在 viewport 裁剪前扫描完整历史并可能二次配对

[tt-a1i]

问题

Direct/Workflow child transcript 每次 render 都先扫描完整历史、建立 tool call/result 配对和组件上下文，之后才按 viewport 截取可见行。普通情况渲染成本随全部历史增长；parallel tool calls 与结果分离排列时，配对搜索可退化为二次复杂度。

证据

• extensions/shared/agent-transcript.ts:247-258,332-369：遍历并配对完整 transcript；
• extensions/shared/agent-transcript.ts:394-424：缓存前仍构造 history-bound context；
• extensions/shared/agent-session-page.ts:230-260：viewport slicing 在完整渲染之后。

这会被 spinner、streaming delta、滚动和 resize 的重复 repaint 放大。

期望

• tool call/result 在 ingestion 时以 call id 增量索引，不在每次 render 搜索历史；
• viewport 先确定需要的 logical items，再只渲染可见窗口及少量 overscan；
• finalized row cache 不依赖每次重建全部前文；
• late result、legacy missing call id、compaction 和 parallel calls 语义不退化；
• benchmark：32/128/512 items，分别顺序和 64-way separated calls/results，测一次 render 与连续 100 次 repaint；证明线性且主要与 viewport 高度相关。

[liwen-aaa]

认领

[liwen-aaa]

前提修正与当前状态（来自 #327 的实测）

在实现过程中测量推翻了本 issue 中的两处前提。记录在此，避免后续接手者重复同一路径。

1. 「parallel calls 与结果分离时配对搜索可退化为二次复杂度」——前提有误

本 issue 假设并行 tool call 与结果分离会导致配对搜索二次退化。实测不成立：并行调用各自持有独立 call id，per-id 结果索引长度为 1，线性扫描首次即命中，与是否并行、结果是否延后无关
。

以 findResult 对 per-id 索引的读取次数计（确定性计数）：

┌──────────────────────┬──────────────────┬────────────┬────────────┐
│ shape │ 最长 per-id 索引 │ 线性 reads │ 二分 reads │
├──────────────────────┼──────────────────┼────────────┼────────────┤
│ sequential 512 │ 1 │ 256 │ 512 │
├──────────────────────┼──────────────────┼────────────┼────────────┤
│ separated 64-way 512 │ 1 │ 256 │ 512 │
├──────────────────────┼──────────────────┼────────────┼────────────┤
│ shared-id 512 │ 256 │ 32896 │ 2306 │
└──────────────────────┴──────────────────┴────────────┴────────────┘

二次退化的真实触发条件是同一个 call id 被复用，与并行无关。本 issue 把「并行调用与结果分离」和「per-id 索引变长」当成了同一件事，实为两回事。

那么 id 会复用吗？扫描 170 个本机 Pi session transcript，按线性化路径统计（会话是 parentId 树，按文件统计会混淆兄弟分支）：

  files with branch points  : 169
  linearized paths checked   : 394
  results per tool id        : 15280 个 id，索引长度全部为 1
  max repeats in one message : 1

零复用。compaction 记录（全库 2 条）存储 summary 与 firstKeptEntryId，是截断而非消息重放，不会重新引入 id。

但构造上可达。直接驱动 workflowTranscriptDocument：

  legacy, no ids, 3 same-name pairs      longestPerId=1
  legacy, orphan results only            longestPerId=1
  provider REPEATS one call id           longestPerId=3
  mixed ids and missing ids, same name   longestPerId=2
  retry reusing one id 40 times          longestPerId=40

合成路径（workflow-tool-${index}）按下标唯一，安全。第 4 行不需要 provider 出错：当 legacy Workflow 历史中部分条目携带 call id、同名的其他条目没有时，fallback 配对的
pending?.shift() 会混合两者并产生重复 id。

结论：call id 唯一性是由 provider 保证、而 OpenPI 从不校验的不变量（无类型、断言或测试约束）。findResult 改为二分查找的价值在于移除这项对未受守卫的外部行为的隐式依赖，而非修复一
个正在发生的性能问题。代价是索引长度为 1 时多一次数组读取（512 items 下 renderMs 4.90 vs 4.81，噪声量级）。

2. 期望 4 的风险排序与实际不符

期望 4 列出 late result、legacy missing call id、compaction、parallel calls 四种情形。实测中：

• compaction 全库仅 2 条记录，且为截断语义，不产生配对风险
• parallel calls 如上，per-id 索引恒为 1，无退化
• legacy missing call id 才是唯一真实可触发重复 id 的路径

最可能触发问题的一项在原始描述里权重最低。

3. 期望 2 / 3 的现象真实，但缺少值得投入的证据

期望 2（viewport 先确定 logical items，只渲染可见窗口）与期望 3（finalized row cache 不依赖重建全部前文）所描述的现象确实存在 —— 旧路径每帧全量渲染后再裁剪。

但本 issue 未给出该成本已构成问题的证据。在 512 项 transcript 上限下实测：

• warm repaint（spinner tick、流式增量等热路径）：0.082 ms，约占 16 ms 帧预算的 0.5%
• cold open（首次打开页面）：约 16 ms —— 这是唯一接近帧预算的路径，且不被窗口化方案改善（可滚动视图必须发布总行数，而这要求测量每个 item 一次，即一次渲染）

我在 #327 中实现了完整的 viewport/revision 缓存（约 590 行生产逻辑，引入 items/pairing identity、行高前缀和、theme generation、cwd、expanded、live tool 集合、per-tool revision、
ledger generation 等失效契约），经维护者评审后判定当前收益不足以支撑这些长期维护责任，已撤回。

需要补充的一点：我在 #327 描述中曾把两个 row-total bug 列为「修复既有问题」，这是错的并已撤回 —— 旧路径的 rowCount 取自已完成的全量渲染（agent-session-page.ts，this.rowCount =
transcript.length），结构上不可能出现总数与实际不符；那两个 bug 由我引入的窗口缓存产生，且只存在于该缓存内部。

同时验证了：干净基线下 expanded 切换（含/不含 native renderer）与 cwd 变化均不产生陈旧行，因此 #327 中新增的 cwd/expanded 缓存键也只是该架构自身的需要，不对应既有缺陷。

当前状态

• 期望 1 已由 perf(tui): index transcript tool pairing #232 完成（配对索引在文档构造期建立，subagent 按 transcriptVersion 缓存）
• 期望 5 的 benchmark 由 perf(tui): render child transcript by viewport window #327 的 benchmarks/child-transcript-pairing.ts 提供，输出含 longestPerIdIndex 字段，任何人怀疑配对成本时可先看这个数字
• 期望 4 的语义保护 由 perf(tui): render child transcript by viewport window #327 的 tests/extensions/shared/agent-transcript-pairing.test.ts 覆盖（7 项：结果先于调用不配对、重复 id 取调用之后的结果、64-way 全配对、错误结果只结算自
  身、长度 40 的 per-id 索引逐一正确配对、无结果保持 pending）
• 期望 2 / 3 推迟。重开门槛：真实 AgentSessionPage 端到端 profile 证明明显占用帧预算，或 transcript 上限（当前 Direct 512 / Workflow 200）准备显著提高。届时建议先评估「稳定
  document 的整段正文缓存 + 动态 live tail」这一更小机制，而非完整窗口化

给后续接手者的建议

先验证每条期望的前提，再动手实现。本 issue 的期望 5 指向了错误的形态，期望 2/3 描述的现象真实但未论证值得修。如果我一开始就测量 per-id 索引的真实长度和 warm repaint 的真实耗时，
可以在写 590 行缓存之前就发现这些问题。