DeepSeek Harness：edit/write 工具卡片的 diff 路径重复显示问题与 TUI 渲染层去重方案

本文基于 DeepSeek Harness 仓库的归档技术笔记 2026-07-27-tui-diff-card-redundant-path-header.md，完整还原一次 TUI（终端界面）渲染缺陷的发现、决策与验证过程。读完本文，你将掌握：edit/write 工具卡片中 diff 数据的产生与流转链路、单文件 diff 卡片标题与文件头之间路径冗余的成因，以及在“渲染层”而非“工具层”解决展示类冗余的设计取舍与测试加固手法。

一、问题：路径在卡片中出现了两次

Harness 的 edit 和 write 工具在执行成功后会产出一张“diff 卡片”：每个工具的 presentCall/presentResult 呈现器（presenter）返回一张卡片，其标题为 Edit <path> / Write <path>，同时卡片内唯一一个 FileDiff 条目又携带同一个 path。

TUI 侧的 diffLines 渲染函数此前无条件地把 palette.bold(diff.path) 渲染成每个文件的小节头。于是对单文件编辑，用户看到的是：

✓ Edit src/foo.ts
src/foo.ts
- old
+ new

路径 src/foo.ts 在视觉上出现了两次：一次在卡片标题行，一次在 diff 正文的文件头。

值得注意的是，原有快照夹具（snapshot fixture）反而掩盖了这个 bug：它把 edit 卡片的标题写成 Edit renderer（不含路径），并给结果放了两个 diff。由于标题与任何 diff 的路径都不匹配，文件头看起来毫无冗余，快照测试自然通过。这个细节是本文一个可复用的教训：快照夹具如果不贴近生产数据形状，就可能在“恰好不触发缺陷分支”的情况下长期隐藏问题。

在仓库中，FileDiff 数据模型的来源可以印证这一链路：diff.ts 中的 computeHunkDiffs(path, before, after) 对 before/after 文本做统一 diff（unified diff，上下文行数常量 DIFF_CONTEXT = 3），为每个 hunk 产出一个 FileDiff，并把传入的 path 打在每个 diff 上——即“每个 diff 都带路径”是数据层的既定行为，并非 TUI 的误用。edit.ts 中 edit 工具通过 output.presentationMeta 把 computeHunkDiffs(...) 的结果挂到结果元数据上，供呈现器在会话重放（replay）时重建 diff 卡片。也就是说：工具层在标题和 diff 中“双份携带路径”是有意的数据设计，非 TUI 消费者（如 web 端、快照序列化）仍然需要这份完整信息。

二、决策：showPath 开关 + 渲染层条件抑制

修复方案分两步，全部落在 TUI 渲染侧：

1. diffLines 新增一个 showPath 布尔标志，调用方决定本次渲染是否输出每文件头；
2. ToolCardComponent.renderBody 对 diff 卡片做抑制判断：当卡片内恰好只有一个 diff，且“有效卡片标题”已经包含该 diff 的路径时，抑制这个文件的文件头。

其中“有效卡片标题”的取法是 resultView?.title ?? callView.title——结果视图有标题时优先用它，否则回退到调用视图的标题。

两个边界行为是刻意设计：

• 多文件 diff 卡片保留所有文件头。多文件结果（以及任何未来的多文件 diff 卡片）确实需要每文件头来区分块归属；
• 空路径或空白路径的 diff 会在同一个 String.includes 检查下被一并抑制——笔记将其定性为“预期的噪音消除”，而不是误伤。

为什么抑制逻辑放在渲染层而不是各工具的 presenter？

这是笔记中值得单独强调的架构判断：冗余是展示问题（presentation concern），由每一个当前与未来的单文件 diff 卡片共同共享。若把去重逻辑写进 edit/write 各自的 presenter，则每个新工具都要重复一遍；而放在 TUI 渲染器里，所有 diff 卡片（包括未来新增的）自动受益。同时工具侧保持“标题与 diff 双份携带路径”的产出不变，非 TUI 消费者不受任何影响。

这个分层与仓库中呈现器的职责划分一致：从源码结构看，工具包（如 tool-fs）负责产出结构化的 FileDiff 元数据，而各 UI 表面（web 端 ui-tool 包 中的 ToolCard 相关组件等）各自决定如何呈现——本 bug 的修复正是把“呈现决策”留给了呈现层。

三、备选方案与取舍

笔记记录了两条被否决的路径，其否决理由对理解“为什么最终方案长这样”很关键：

备选方案	否决理由
从 edit/write 卡片标题中移除路径	标题是可扫读（scannable）的摘要行，去掉路径会削弱它；而且该修改需要在每个工具里重复实现
无条件移除每文件头	多文件结果 diff（及未来多文件卡片）确实需要每文件头，一刀切会造成信息缺失

最终方案是两者的折中：按“单 diff + 标题已含路径”这一条件精准抑制，既不牺牲标题的摘要能力，也不破坏多文件场景。

四、已知局限：子串匹配的启发式风险

抑制判断本质是一个子串匹配（String.includes），因此存在理论误伤：如果标题碰巧包含了某个单 diff 的路径（例如标题本身只是引用了别的上下文），文件头也会被抑制。笔记给出的定性是：对真实的卡片生产方（edit/write）而言，标题恰好就是 Verb <path> 形式，所以实践中该启发式是正确的。

这是一个典型的“在真实数据分布下成立的启发式”：文档如实记录了其失效条件（incidental match），而不是把子串匹配包装成精确匹配。阅读此类渲染层启发式时，可以把这条写进代码注释或评审 checklist：任何 includes 型判断都应明确它依赖的标题格式契约。

五、测试加固：让夹具贴近生产形状

修复的验证分两层：

1. tui.spec.ts 新增聚焦用例：断言对于标题为 Edit src/only.ts 的单 diff 卡片，该路径恰好出现一次——直接锁定“不再重复”这一行为契约，而非依赖像素级快照；
2. advanced-cards-* 无 key 快照重录（re-record）：重录后的快照显示标题行之后紧跟 diff 正文、中间没有重复的路径头。与此同时，多文件头保留的场景由 tui.spec.ts 中的 edit 夹具继续覆盖：a.txt/b.txt 两个文件位于 Edit files 标题之下，确保“抑制逻辑没有把多文件头也吞掉”。

配套的快照夹具形状也被修正以贴近生产：edit 夹具现在是“一个 diff，且标题指名了该 diff 的路径”——正是触发抑制分支的形状，从而证明文件头确实被丢弃。这与第一节的教训闭环：夹具形状从“恰好不触发缺陷分支”变为“正面覆盖决策分支”。

六、延伸：diff 卡片的数据链路（源码印证）

结合仓库源码，可以把这条 bug 涉及的数据流完整串起来：

1. 执行：edit.ts 的 execute 完成原子编辑，返回 { path, before, after }；
2. 元数据：presentationMeta 调用 computeHunkDiffs 生成 FileDiff[]（每个 hunk 一个 diff，DIFF_CONTEXT = 3 行上下文，纯插入用 oldText: null）；元数据随会话日志持久化，diffsFromMeta（diff.ts）在重放时对不透明的 meta 做防御性收窄——畸形数据返回 undefined，让呈现回退而不抛异常；
3. 呈现：工具呈现器把 FileDiff[] 组装成 DiffCallView/DiffResultView（类型定义见 presentation.ts），标题为 Edit <path>/Write <path>；
4. 渲染：TUI 的 ToolCardComponent.renderBody → diffLines 完成最终像素输出，本 bug 的抑制逻辑即位于第 4 步。

需要说明的是，diffLines、showPath 与 ToolCardComponent 为 TUI 终端渲染侧的组件，笔记归档于 2026-07-31（Status: implemented），其具体文件路径未在该笔记中列出；本文对其的描述以笔记原文为准。而第 1–3 步的数据链路可由上述仓库源码直接验证。

七、可复用的经验小结

• 展示类去重放渲染层：当冗余是“每个表面都会遇到”的展示问题时，把它收敛到共享渲染器，而不是散落到每个数据生产方；
• 快照夹具要覆盖决策分支：夹具数据形状若不触发目标分支，测试通过等于没测；修复后应让夹具“正面命中”新逻辑；
• 行为断言优先于快照：“路径恰好出现一次”这样的计数断言，比重录快照更能表达行为契约；
• 如实记录启发式边界：子串匹配的误伤条件、多文件保留策略，都写进了决策记录，后续维护者不必重新推导取舍。