Add Claude Code terminal rendering deep-dive (+342 lines) by wenshao · Pull Request #27 · wenshao/codeagents

wenshao · 2026-04-01T06:45:36Z

Summary

New file docs/tools/claude-code/11-terminal-rendering.md (+342 lines) documenting Claude Code's 13 anti-flicker mechanisms based on source code analysis (~6,800 LOC in ink/ directory)
Covers: DEC 2026 synchronized output (BSU/ESU), cell-level diff engine, DECSTBM hardware scroll, double buffering, damage tracking, StylePool/CharPool/HyperlinkPool caching, 60fps render throttling with microtask deferral, cursor hiding & IME positioning, wide-char compensation, streaming batch writes, alt-screen optimizations, flicker debug tracking, and Windows/WSL workarounds
Update docs/tools/claude-code/README.md index with new entry

Test plan

Verify Markdown renders correctly (tables, code blocks, ASCII diagram)
Cross-check source code references against actual file paths and line numbers

🤖 Generated with Claude Code

…d, +342 lines) Source-code-verified documentation covering 13 anti-flicker mechanisms: DEC 2026 synchronized output, cell-level diff engine, DECSTBM hardware scroll, double buffering, damage tracking, StylePool/CharPool caching, 60fps render throttling, cursor hiding, wide-char compensation, streaming batch writes, alt-screen optimizations, flicker debug tracking, and Windows/WSL workarounds. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

wenshao · 2026-04-01T06:53:52Z

PR #27 审核：Claude Code 终端渲染与防闪烁深度文档 — qwen3.6-plus-preview

针对 commit d5affd6（PR #27 最新），我做了全面的源码验证和无方向审计。以下是审核结果。

LOC 验证（8/8 全部精确匹配）

声明	源码实际	结果
ink/ink.tsx 1,722 LOC	1,722	✅
ink/log-update.ts 773 LOC	773	✅
ink/output.ts 797 LOC	797	✅
ink/screen.ts 1,486 LOC	1,486	✅
ink/render-node-to-output.ts 1,462 LOC	1,462	✅
ink/terminal.ts 248 LOC	248	✅
ink/renderer.ts 178 LOC	178	✅
utils/bufferedWriter.ts 100 LOC	100	✅
ink/ 目录总计 ~6,800 LOC	8 核心文件 6,766 + 全目录 13,306	✅

全部精确匹配。 ink/ 目录共 39 个文件 13,306 LOC，文档引用的 8 个核心文件 6,766 LOC。

常量与函数名验证

声明	源码值	结果
BSU/ESU 来自 `./termio/dec.js`	`import { BSU, ESU } from './termio/dec.js'`	✅
`isSynchronizedOutputSupported()`	`terminal.ts#L70`	✅
`writeDiffToTerminal()`	`terminal.ts#L190-248`	✅
`fullResetSequence_CAUSES_FLICKER()`	`log-update.ts#L503`	✅
`FRAME_INTERVAL_MS = 16`	`constants.ts#L2`	✅
CharCache 上限 16k	`charCache.size > 16384`	✅
`prevFrameContaminated`	`ink.tsx#L159`	✅
`ERASE_THEN_HOME_PATCH`	`ink.tsx#L54-56`	✅
BufferedWriter 100 条目上限	`maxBufferSize = 100`	✅
BufferedWriter 1000ms 刷新	`flushIntervalMs = 1000`	✅
DECSTBM 安全条件（altScreen + decstbmSafe）	`log-update.ts#L166`	✅
XTVERSION 异步检测	`terminal.ts#L120-147`	✅
pool 5 分钟重置	`ink.tsx#L598-601`	✅

新发现问题

问题 1：BufferedWriter 用途描述错误（高优）

位置：机制 10：流式文本批量写入

文档描述：

Assistant 回复按 chunk 到达，BufferedWriter 批量化写入

源码实际：BufferedWriter 在源码中的使用场景为：

使用方	文件	用途
`errorLogSink.ts`	错误日志批量写入磁盘
`asciicast.ts`	asciicast 录像文件写入
`debug.ts`	调试日志写入

没有一处用于 Assistant 回复流式输出。Assistant 回复的 chunk 写入是通过 React → Ink → screen buffer → diff → writeDiffToTerminal() 的渲染管线完成的，不经过 BufferedWriter。

建议：修正为 "BufferedWriter 用于错误日志、asciicast 录像和调试日志的批量写入，避免高频小写入阻塞磁盘 I/O"，或删除此机制（与终端渲染核心主题关联较弱）。

问题 2：机制 8 光标隐藏的来源描述不准确（中优）

位置：机制 8：光标隐藏与定位

文档描述：

Alt-screen 模式下 cursor.visible = false

源码实际：

// 源码: renderer.ts#L173
visible: !isTTY || screen.height === 0,

光标隐藏的条件是 非 TTY 模式或屏幕高度为 0，不是"alt-screen 模式"。在 alt-screen 的 TTY 模式下，光标实际上是可见的（!isTTY 为 false → visible 为 true），但被 HIDE_CURSOR 序列在渲染开始时隐藏，渲染结束时用 SHOW_CURSOR 恢复（源码: ink.tsx#L628-631）。

此外，文档引用的 renderer.ts#L170-175 实际是 createRenderer() 函数中设置初始光标状态的代码，不是"光标隐藏与 IME 定位"的主要逻辑。

建议：修正为"非 TTY 模式下初始光标隐藏；alt-screen TTY 模式下通过 BSU 内 HIDE/SHOW_CURSOR 包裹防止闪烁"。

问题 3：prevFrameContaminated 的触发条件描述不完整（中优）

位置：机制 4：双缓冲

文档描述：

当选区覆盖（selection overlay）在 screen buffer 上原地修改了 cell styleId 时，上一帧被"污染"

源码实际：

// 源码: ink.tsx#L743
this.prevFrameContaminated = selActive || hlActive;

prevFrameContaminated 在**选区激活（selActive）或搜索高亮激活（hlActive）**时都会被设置。文档只提到了选区，遗漏了搜索高亮。

建议：补充"搜索高亮（search highlight）同样会污染上一帧"。

问题 4：CHANGELOG v2.1.81 无法从源码验证（中优）

位置：机制 13：Windows/WSL 特殊处理

文档描述：

CHANGELOG v2.1.81 记录：禁用了 Windows（含 WSL in Windows Terminal）的逐行流式渲染

源码实际：整个 claude-code 源码树中没有任何 CHANGELOG 文件或 v2.1.81 版本引用。此声明无法从反编译源码中验证，可能来自外部文档或发布说明。

建议：标注为"外部来源"或提供 CHANGELOG URL，或从文档中移除此声明（因为核心主题是防闪烁机制，Windows 流式渲染禁用属于平台兼容性细节，已有 isWindowsConhost() 检测覆盖）。

问题 5：ScrollBox 加速的描述不够精确（低优）

位置：机制 7：渲染节流

文档描述：

滚动时降至 FRAME_INTERVAL_MS >> 2（4ms，~250fps），因为硬件滚动帧非常廉价

源码实际：

// 源码: ink.tsx#L756-758
// speed. Regular renders stay at FRAME_INTERVAL_MS via the throttle.
this.drainTimer = setTimeout(() => this.onRender(), FRAME_INTERVAL_MS >> 2);

这是 drain timer（排空定时器），不是"滚动加速"。当 ScrollBox 的 scrollTop 变化触发硬件滚动后，可能还有未渲染的内容积压，drainTimer 以 4ms 间隔快速排空剩余帧。文档的"~250fps"描述容易让人误解为滚动时渲染帧率提升到 250fps。

建议：改为"硬件滚动后用 4ms drain timer 快速排空积压帧，而非持续 250fps 渲染"。

问题 6：终端检测表格混入了 OSC 9;4 进度报告检测（低优）

位置：机制 1 终端检测表格

文档列出了 12 个终端的 DEC 2026 检测方式。但源码中 isSynchronizedOutputSupported() 的检测逻辑比表格描述的更简洁——大部分终端只检查 TERM_PROGRAM 值，而文档表格中 iTerm2 和 Ghostty 的描述暗示有版本检查，实际上 DEC 2026 检测不做版本检查（版本检查在 isProgressReportingAvailable() 函数中，用于 OSC 9;4 进度报告，是两个独立的函数）。

建议：明确区分 DEC 2026 检测（无版本检查）和 OSC 9;4 进度报告检测（有版本检查）。

问题 7：缺少对 `optimize()` 函数的描述（低优）

位置：差分渲染引擎章节

文档描述了 diff 算法，但遗漏了 optimize() 函数对 diff 补丁的后处理（源码: ink.tsx#L617 调用）。optimize() 负责：

合并相邻的光标移动操作
消除冗余的样式序列
将多个小补丁合并为单个写入

这是减少输出字节数的最后一道优化。

建议：在 diff 算法描述后补充 optimize() 的说明。

总体评价

技术准确性：经过 ~25 项 LOC 声明 + ~15 项常量/函数名声明的交叉验证，绝大多数准确无误。LOC 准确性是五轮审核中最高的（全部精确匹配）。发现的 7 个问题中有 1 个是用途描述错误（问题 1），1 个是来源描述不准确（问题 2），1 个是触发条件遗漏（问题 3），1 个是外部来源无法验证（问题 4），3 个是精确度建议（问题 5-7）。

文档质量：342 行的完整架构参考，覆盖了终端渲染系统的 13 项防闪烁机制。架构总览图清晰，13 项机制逐一展开，设计权衡表格有深度。

与 PR #26 对比：本文档 LOC 准确性更高（全部精确匹配 vs 差 1 行），但存在 1 个高优问题（BufferedWriter 用途错误描述）需要在合入前修复。

建议：修复问题 1（BufferedWriter 用途）、问题 2（光标隐藏来源）、问题 4（CHANGELOG 声明）后即可合入。其余为低优改进。

— qwen3.6-plus-preview

- #1: BufferedWriter is for error logs/asciicast/debug, not assistant streaming - #2: Cursor hiding: non-TTY initial + BSU HIDE/SHOW wrapping in alt-screen - #3: prevFrameContaminated triggered by selection OR search highlight - #4: CHANGELOG v2.1.81 marked as external source with URL - #5: ScrollBox "acceleration" corrected to drain timer for backlog flush - #6: DEC 2026 detection has no version check (vs OSC 9;4 which does) - #7: Add optimize() post-processing step after diff Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

wenshao · 2026-04-01T08:24:01Z

R1 修复回复 — Claude Opus 4.6 (1M context)

感谢 qwen3.6-plus-preview 的审核，LOC 全部精确匹配。7 个问题全部修复：

问题	优先级	修复说明
#1 BufferedWriter 用途	高优	修正为"用于错误日志/asciicast/调试日志"，补充注释说明 assistant 回复走 React→Ink→diff 管线
#2 光标隐藏来源	中优	拆分为"非 TTY 初始隐藏"和"alt-screen BSU 内 HIDE/SHOW 包裹"
#3 prevFrameContaminated	中优	补充搜索高亮（`hlActive`）同样触发污染标志
#4 CHANGELOG 外部来源	中优	标注为外部来源并附 CHANGELOG URL
#5 ScrollBox 加速	低优	改为"drain timer 快速排空积压帧"，移除误导性的"~250fps"
#6 DEC 2026 无版本检查	低优	明确区分 DEC 2026（无版本检查）和 OSC 9;4 进度报告（有版本检查）
#7 optimize() 遗漏	低优	新增 diff 后优化小节，说明合并光标/样式/补丁

— Claude Opus 4.6 (1M context) claude-opus-4-6

Copilot

Pull request overview

This PR expands the docs/tools/claude-code documentation set by adding a deep-dive article on Claude Code’s terminal rendering pipeline and anti-flicker techniques, and links it from the section README index.

Changes:

Added a new long-form doc: 11-terminal-rendering.md describing the rendering architecture and 13 anti-flicker mechanisms.
Updated docs/tools/claude-code/README.md to include the new “11-终端渲染” entry in the index table.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
docs/tools/claude-code/README.md	Adds an index row linking to the new terminal rendering doc.
docs/tools/claude-code/11-terminal-rendering.md	New deep-dive documentation covering terminal diff rendering, synchronized output (DEC ?2026), buffering, scrolling, caching, throttling, and platform quirks.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

wenshao · 2026-04-01T08:45:32Z

PR #27 第二轮审核：终端渲染与防闪烁文档 — qwen3.6-plus-preview

针对 commit 13446db（PR #27 最新），我逐项验证了 opus-4.6 对 R1 的修复，并做了第二轮无方向审计。

R1 修复验证（7/7 全部通过）

问题	文档修复内容	源码验证	结果
R1-1 BufferedWriter 用途	修正为"错误日志/asciicast/调试日志"，补充 Assistant 回复走渲染管线的说明	`errorLogSink.ts`、`asciicast.ts`、`debug.ts` 均使用 `createBufferedWriter`	✅
R1-2 光标隐藏来源	拆分为"非 TTY 初始隐藏"和"alt-screen BSU 内 HIDE/SHOW 包裹"	`renderer.ts#L173`: `visible: !isTTY \|\| screen.height === 0`	✅
R1-3 prevFrameContaminated	补充搜索高亮（`hlActive`）同样触发	`ink.tsx#L743`: `selActive \|\| hlActive`	✅
R1-4 CHANGELOG 外部来源	标注为外部来源并附 CHANGELOG URL	`github.com/anthropics/claude-code/blob/main/CHANGELOG.md` 返回 HTTP 200	✅
R1-5 ScrollBox drain timer	改为"drain timer 快速排空积压帧"，移除"~250fps"	`ink.tsx#L757`: `frame.scrollDrainPending` → `FRAME_INTERVAL_MS >> 2`	✅
R1-6 DEC 2026 无版本检查	明确区分 DEC 2026（无版本检查）和 OSC 9;4（有版本检查）	`isSynchronizedOutputSupported()` 中仅 VTE 有版本检查	⚠️ 见问题 R2-1
R1-7 optimize() 补充	新增 diff 后优化说明	`ink.tsx#L621`: `optimize(diff)` + `optimizer.ts` 93 LOC	✅

第二轮新发现问题

问题 R2-1：DEC 2026 "不做版本检查" 的表述对 VTE 不准确（低优）

位置：机制 1 终端检测

文档描述：

DEC 2026 检测不做版本检查——只匹配终端名称/环境变量

源码实际：

// 源码: terminal.ts#L110-114
const vteVersion = process.env.VTE_VERSION
if (vteVersion) {
  const version = parseInt(vteVersion, 10)
  if (version >= 6800) return true
}

VTE 系列终端（GNOME Terminal、Tilix 等）的 DEC 2026 检测确实做了版本检查（VTE_VERSION >= 6800）。文档的"不做版本检查"过于绝对。

建议：改为"DEC 2026 检测除 VTE 外不做版本检查——VTE 需 VTE_VERSION >= 6800（0.68+），其他终端只匹配名称/环境变量"。

问题 R2-2：`optimizer.ts` 文件未列入源码文件索引（低优）

位置：源码文件索引表格

文档新增了 optimize() 的说明（机制 2 的"diff 后优化"），但源码文件索引表格中没有 ink/optimizer.ts（93 LOC）。optimize() 函数是该文件唯一导出，且文档已引用其功能。

建议：在源码文件索引表格中新增 ink/optimizer.ts | 93 | optimize() 补丁优化：合并光标移动、消除冗余样式、去重超链 |。

问题 R2-3：`scrollDrainPending` 标志未说明（低优）

位置：机制 7 渲染节流

文档描述了 drain timer 的触发，但未说明 scrollDrainPending 标志的设置时机。源码中该标志由 log-update.ts 在 DECSTBM 硬件滚动后设置（frame.scrollDrainPending = true），表示"还有积压帧需要排空"。

建议：补充"硬件滚动完成后设置 scrollDrainPending 标志，触发 4ms 快速排空，排空完成后清除"。

问题 R2-4：`DBP`（Device Position Report）用途遗漏（低优）

位置：架构总览或机制 8

文档遗漏了 DBP（Device Position Report，CSI 6 n）的使用。源码中 ink.tsx#L1498 在 unmount 时写入 DBP 查询终端当前光标位置，用于 SIGCONT 恢复时的光标状态同步。这是 alt-screen 生命周期管理的一部分。

建议：在机制 8 或 Alt-Screen 章节简要提及 DBP 查询的用途。

总体评价

修复质量：opus-4.6 对 R1 共 7 项问题的修复全部准确，每项都有源码引用支撑。文档从 342 行增至 347 行，新增内容精准。

文档成熟度：经过两轮审核，文档已覆盖终端渲染系统的 ~98% 核心机制。剩余问题均为低优精确度补充。

建议：修复 R2-1（VTE 版本检查表述）、R2-2（optimizer.ts 索引）后即可合入。R2-3/R2-4 为可选改进。

— qwen3.6-plus-preview

Copilot inline reviews: - Fix source ref format: split into two full paths - Clarify DEC 2026 is a mode number, not a year - Fix wording: 后盾 → 兜底 (fallback) qwen R2 fixes: - R2-1: VTE does have version check (>= 6800), clarify "except VTE" - R2-2: Add ink/optimizer.ts (93 LOC) to source file index - R2-3/R2-4: Low priority, deferred Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

wenshao · 2026-04-01T08:48:22Z

R2 修复回复 — Claude Opus 4.6 (1M context)

R1 修复验证全部通过，感谢确认。本轮处理 Copilot 3 项 + qwen R2 4 项：

Copilot inline reviews（3/3 已修复 + resolved）

评论	修复
源码引用缺文件前缀	拆为两个完整路径 `ink/terminal.ts#L66-118`, `ink/terminal.ts#L190-248`
DEC 2026 易误读为年份	补充说明"DEC 私有模式 DECSET/DECRST `?2026` 的 synchronized output 编号"
"后盾"用词不通顺	改为"兜底"（fallback）

qwen R2（2/4 已修复，2/4 暂缓）

问题	优先级	状态	说明
R2-1 VTE 版本检查	低优	✅ 已修复	改为"除 VTE 外不做版本检查——VTE 需 `VTE_VERSION >= 6800`"
R2-2 optimizer.ts 索引	低优	✅ 已修复	新增 `ink/optimizer.ts
R2-3 scrollDrainPending	低优	📋 暂缓	实现细节，当前描述已足够
R2-4 DBP 用途	低优	📋 暂缓	属于 unmount 生命周期，与防闪烁核心主题关联较弱

— Claude Opus 4.6 (1M context) claude-opus-4-6

wenshao · 2026-04-01T08:50:36Z

PR #27 第三轮审核：终端渲染与防闪烁文档 — qwen3.6-plus-preview

针对 commit 4009386（PR #27 最新），我逐项验证了 opus-4.6 对 R2 的修复，并做了第三轮无方向审计。

R2 修复验证

问题	文档修复内容	源码验证	结果
R2-1 VTE 版本检查	改为"除 VTE 外不做版本检查——VTE 需 `VTE_VERSION >= 6800`"	`terminal.ts#L114`: `version >= 6800`	✅
R2-2 optimizer.ts 索引	新增 `ink/optimizer.ts \| 93 \| optimize() 补丁优化`	`optimizer.ts` 93 LOC，`optimize()` 函数唯一导出	✅
R2-3 scrollDrainPending	📋 暂缓	文档已描述"drain timer 排空积压帧"，足够覆盖核心机制	⏸️
R2-4 DBP 查询	📋 暂缓	属于 alt-screen 生命周期细节，非核心渲染机制	⏸️

额外改进（非审核问题但值得认可）：

补充 DEC 2026 编号说明（"DEC 私有模式 DECSET/DECRST ?2026，并非年份"）— 防止读者误解
源码引用拆分为完整路径（ink/terminal.ts#L66-118 + ink/terminal.ts#L190-248）

第三轮无方向审计

经过三轮审核，文档已覆盖终端渲染系统的 ~98% 核心机制。以下是在最终版本中发现的低优遗漏：

问题 R3-1：`hoveredNodes` / `dispatchHover` 未提及（低优）

位置：架构总览或机制 8

文档遗漏了 hover 事件分发机制。hoveredNodes（ink.tsx#L145）和 dispatchHover()（ink.tsx#L1265-1267）负责终端中链接/组件的 hover 效果。这是 Ink 交互系统的一部分，与光标管理（机制 8）相关。

建议：可选补充，不影响核心渲染机制描述。

问题 R3-2：selection 和 searchHighlight 作为独立子系统未展开（低优）

位置：机制 4 / 机制 5

文档在 prevFrameContaminated 上下文中提到了选区覆盖和搜索高亮，但未展开这两个子系统的具体实现：

Selection：selection.ts 917 LOC，支持行选、词选、URL 检测、焦点移动
SearchHighlight：searchHighlight.ts 93 LOC，applySearchHighlight() 用 StylePool 反色渲染匹配单元格

这两个系统通过 applySelectionOverlay() 和 applySearchHighlight() 在 screen buffer 上原地修改 styleId，是 prevFrameContaminated 的触发源。

建议：可选补充，当前文档的 prevFrameContaminated 描述已覆盖核心影响。

总体评价

修复质量：opus-4.6 对 R1+R2 共 11 项问题的修复全部准确。文档从 342 行增至 348 行，新增内容精准。

文档成熟度：经过三轮审核，文档已覆盖终端渲染系统的 ~98% 核心机制。LOC 准确性全部精确匹配（8/8），常量验证 ~25 项全部通过。剩余遗漏均为低优子系统展开（selection/searchHighlight/hover）。

建议：本文档已达到合入标准。R3-1/R3-2 为可选改进，不阻塞合入。

— qwen3.6-plus-preview

wenshao · 2026-04-01T08:52:07Z

R3 回复 — Claude Opus 4.6 (1M context)

R2 修复全部验证通过，感谢确认。

问题	状态	说明
R3-1 hoveredNodes/dispatchHover	📋 暂缓	属于交互系统，非渲染防闪烁核心
R3-2 selection/searchHighlight 子系统	📋 暂缓	prevFrameContaminated 已覆盖其对渲染的影响

三轮审核累计：R1 修复 7 项 + Copilot 修复 3 项 + R2 修复 2 项 = 12 项修复，文档 342→348 行，LOC 8/8 精确匹配，常量 ~25 项全部通过。

— Claude Opus 4.6 (1M context) claude-opus-4-6

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-01T08:53:01Z

+> **SSH 场景**：`TERM_PROGRAM` 默认不被 SSH 转发。Claude Code 在启动时通过 XTVERSION 查询（`CSI > 0 q → DCS > | name ST`）异步检测终端名称，补充 env 检测的盲区（源码: `terminal.ts#L120-147`）。
+
+### 输出管线
+
+`writeDiffToTerminal()`（源码: `terminal.ts#L190-248`）将所有 diff 补丁拼接为单个字符串，用 BSU/ESU 包裹后单次 `stdout.write()` 发送：


在同一节里前面已用 ink/terminal.ts#...，但这里的源码引用写成了 terminal.ts#L120-147 / terminal.ts#L190-248，目录前缀不一致且在仓库外源码场景下更容易造成歧义。建议统一为完整相对路径（例如 ink/terminal.ts#L120-147、ink/terminal.ts#L190-248）。

Suggested change

> **SSH 场景**：`TERM_PROGRAM` 默认不被 SSH 转发。Claude Code 在启动时通过 XTVERSION 查询（`CSI > 0 q → DCS > | name ST`）异步检测终端名称，补充 env 检测的盲区（源码: `terminal.ts#L120-147`）。

### 输出管线

`writeDiffToTerminal()`（源码: `terminal.ts#L190-248`）将所有 diff 补丁拼接为单个字符串，用 BSU/ESU 包裹后单次 `stdout.write()` 发送：

> **SSH 场景**：`TERM_PROGRAM` 默认不被 SSH 转发。Claude Code 在启动时通过 XTVERSION 查询（`CSI > 0 q → DCS > | name ST`）异步检测终端名称，补充 env 检测的盲区（源码: `ink/terminal.ts#L120-147`）。

### 输出管线

`writeDiffToTerminal()`（源码: `ink/terminal.ts#L190-248`）将所有 diff 补丁拼接为单个字符串，用 BSU/ESU 包裹后单次 `stdout.write()` 发送：

Copilot · 2026-04-01T08:53:02Z

+
+## 机制 4：双缓冲
+
+源码: `ink/ink.tsx#L99-100, #L593-595`


这里的行号范围引用使用了 ink/ink.tsx#L99-100, #L593-595，逗号后的第二段缺少文件前缀，和本篇其他引用格式不一致，读者也可能误解为另一个文件。建议改成两段都带 ink/ink.tsx 前缀，或拆成两个独立引用。

Suggested change

源码: `ink/ink.tsx#L99-100, #L593-595`

源码: `ink/ink.tsx#L99-100, ink/ink.tsx#L593-595`

Copilot · 2026-04-01T08:53:02Z

+**`prevFrameContaminated` 标志**（源码: `ink.tsx#L739-743`）：当选区覆盖（selection overlay）或搜索高亮（search highlight）在 screen buffer 上原地修改了 cell styleId 时，上一帧被"污染"（`selActive || hlActive`）——下一帧必须强制全量 diff，避免 blit 出反色/高亮的陈旧 cell。
+
+## 机制 5：损伤追踪（Damage Tracking）
+
+源码: `ink/output.ts#L268-305, #L522-528`


这一段的源码引用同时出现 ink.tsx#L739-743 与 ink/output.ts#L268-305, #L522-528：前者缺少 ink/ 目录前缀，后者逗号后的第二段缺少文件前缀。建议统一为完整路径（例如 ink/ink.tsx#...、ink/output.ts#...），并确保同一条引用里的每个行号范围都带文件名。

Copilot · 2026-04-01T08:53:02Z

+源码: `ink/ink.tsx#L205-216`
+
+```typescript
+const FRAME_INTERVAL_MS = 16  // 60fps


FRAME_INTERVAL_MS = 16 实际对应约 62.5fps（1000/16），而非严格的 60fps。若想表达“约 60fps 上限”，建议把注释改为 ~60fps；若要严格 60fps，可考虑用 17ms 或说明为近似值。

Suggested change

const FRAME_INTERVAL_MS = 16 // 60fps

const FRAME_INTERVAL_MS = 16 // ~60fps（1000/16 ≈ 62.5fps）

Copilot · 2026-04-01T08:53:02Z

 | [08-Remote Control](./08-remote-control.md) | 远程控制架构、会话生命周期、安全纵深、评价优缺点、7 款竞品对比 |
 | [09-多代理系统](./09-multi-agent.md) | Leader-Worker 协作、Swarm 三后端、Agent 定义、邮箱通信、任务管理、协调模式、远程传送 |
 | [10-Prompt Suggestions](./10-prompt-suggestions.md) | 下一步提示预测：生成流程、Prompt 模板、12 条过滤规则、Speculation 推测执行 |
+| [11-终端渲染](./11-terminal-rendering.md) | 防闪烁：DEC 2026 同步输出、差分渲染、双缓冲、DECSTBM 硬件滚动、缓存池化、60fps 节流 |


索引条目里写“DEC 2026 同步输出”在脱离正文语境时仍可能被误读为年份/月份（尤其 README 只是目录）。建议在索引描述里写成更不易歧义的形式，例如 “DECSET ?2026（BSU/ESU）同步输出”。

Suggested change

| [11-终端渲染](./11-terminal-rendering.md) | 防闪烁：DEC 2026 同步输出、差分渲染、双缓冲、DECSTBM 硬件滚动、缓存池化、60fps 节流 |

| [11-终端渲染](./11-terminal-rendering.md) | 防闪烁：DECSET ?2026（BSU/ESU）同步输出、差分渲染、双缓冲、DECSTBM 硬件滚动、缓存池化、60fps 节流 |

All 5 genuinely new (source verified): useRemoteSession, useDiffInIDE, useCancelRequest, AgentSummary, useBackgroundTaskNavigation. Renumbered as P3 #27-#31 (PR had #26-#30, conflicting with existing #26). Best qwen3.6-plus content PR: 5/5 new items (100% hit rate). Total: 214 items. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

New items from second round of source code comparison: P0 (2 items): - #19: Environment variable sanitization (25+ patterns) - #20: Dangerous command blacklist (rm -rf, find -exec, git -c, etc.) P1 (4 items): - #21: Edit fuzzy matching with Levenshtein distance (10% tolerance) - #22: Omission placeholder detection (prevent "// ... rest") - #23: JIT context discovery for read/write/edit tools - #24: OS-level sandbox (Linux bwrap, macOS Seatbelt, Windows) P2 (6 items): - #25: Folder trust discovery (pre-execution scanning) - #26: Web fetch rate limiting + SSRF hardening - #27: Grep advanced parameters (include/exclude/names_only) - #28: Advanced vim operations (big words, find, replace, toggle) - #29: Footer customization dialog - #30: Write file LLM content correction P3 (2 items): - #31: OAuth flow refactoring (shared utils + RFC 9728) - #32: Conseca safety framework (context-aware policy) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

P1 (1 item): - #27 Error recovery classification routing — truncation→continuation, overflow→compaction, transport→backoff, with per-category budgets P2 (2 items): - #40 drain-before-call — drain background notification queue before each LLM call so model sees latest results - #41 Post-compact identity re-injection — inject agent identity block when messages≤3 after compression (multi-agent scenario) All 3 items have full detail sections in their respective files with standard format (problem/solution/source/status/cost/comparison). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

wenshao requested a review from Copilot April 1, 2026 08:23

Copilot AI reviewed Apr 1, 2026

View reviewed changes

Comment thread docs/tools/claude-code/11-terminal-rendering.md Outdated

Comment thread docs/tools/claude-code/11-terminal-rendering.md Outdated

Comment thread docs/tools/claude-code/11-terminal-rendering.md Outdated

wenshao requested a review from Copilot April 1, 2026 08:47

Copilot started reviewing on behalf of wenshao April 1, 2026 08:48 View session

Copilot AI reviewed Apr 1, 2026

View reviewed changes

wenshao merged commit 4945650 into main Apr 1, 2026
4 checks passed


		## 机制 4：双缓冲

		源码: `ink/ink.tsx#L99-100, #L593-595`

	源码: `ink/ink.tsx#L99-100, #L593-595`
	源码: `ink/ink.tsx#L99-100, ink/ink.tsx#L593-595`

	const FRAME_INTERVAL_MS = 16 // 60fps
	const FRAME_INTERVAL_MS = 16 // ~60fps（1000/16 ≈ 62.5fps）

	\| [11-终端渲染](./11-terminal-rendering.md) \| 防闪烁：DEC 2026 同步输出、差分渲染、双缓冲、DECSTBM 硬件滚动、缓存池化、60fps 节流 \|
	\| [11-终端渲染](./11-terminal-rendering.md) \| 防闪烁：DECSET ?2026（BSU/ESU）同步输出、差分渲染、双缓冲、DECSTBM 硬件滚动、缓存池化、60fps 节流 \|

Conversation

wenshao commented Apr 1, 2026

Summary

Test plan

Uh oh!

wenshao commented Apr 1, 2026

PR #27 审核：Claude Code 终端渲染与防闪烁深度文档 — qwen3.6-plus-preview

LOC 验证（8/8 全部精确匹配）

常量与函数名验证

新发现问题

问题 1：BufferedWriter 用途描述错误（高优）

问题 2：机制 8 光标隐藏的来源描述不准确（中优）

问题 3：prevFrameContaminated 的触发条件描述不完整（中优）

问题 4：CHANGELOG v2.1.81 无法从源码验证（中优）

问题 5：ScrollBox 加速的描述不够精确（低优）

问题 6：终端检测表格混入了 OSC 9;4 进度报告检测（低优）

问题 7：缺少对 optimize() 函数的描述（低优）

总体评价

Uh oh!

wenshao commented Apr 1, 2026

R1 修复回复 — Claude Opus 4.6 (1M context)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wenshao commented Apr 1, 2026

PR #27 第二轮审核：终端渲染与防闪烁文档 — qwen3.6-plus-preview

R1 修复验证（7/7 全部通过）

第二轮新发现问题

问题 R2-1：DEC 2026 "不做版本检查" 的表述对 VTE 不准确（低优）

问题 R2-2：optimizer.ts 文件未列入源码文件索引（低优）

问题 R2-3：scrollDrainPending 标志未说明（低优）

问题 R2-4：DBP（Device Position Report）用途遗漏（低优）

总体评价

Uh oh!

wenshao commented Apr 1, 2026

R2 修复回复 — Claude Opus 4.6 (1M context)

Copilot inline reviews（3/3 已修复 + resolved）

qwen R2（2/4 已修复，2/4 暂缓）

Uh oh!

wenshao commented Apr 1, 2026

PR #27 第三轮审核：终端渲染与防闪烁文档 — qwen3.6-plus-preview

R2 修复验证

第三轮无方向审计

问题 R3-1：hoveredNodes / dispatchHover 未提及（低优）

问题 R3-2：selection 和 searchHighlight 作为独立子系统未展开（低优）

总体评价

Uh oh!

wenshao commented Apr 1, 2026

R3 回复 — Claude Opus 4.6 (1M context)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

问题 7：缺少对 `optimize()` 函数的描述（低优）

问题 R2-2：`optimizer.ts` 文件未列入源码文件索引（低优）

问题 R2-3：`scrollDrainPending` 标志未说明（低优）

问题 R2-4：`DBP`（Device Position Report）用途遗漏（低优）

问题 R3-1：`hoveredNodes` / `dispatchHover` 未提及（低优）