给本地 AI 编码工作台造一块可靠的终端地基

这是一篇关于"终端到底有多难做对"的实战复盘。

Cordy 是一款本地优先的个人 AI 编码工作台。它把 Infinite Scroll 那种"终端工作区 + 键盘优先"的体验，和 Superset 那种"并行托管 Claude Code / Codex 等外部 CLI coding agent"的能力，融合成一个跑在 Windows / macOS / Linux 上、不上云、不做团队协作的桌面应用。它的核心对象模型很简单：

• Project：仓库级根对象，回答"这是哪份代码"；
• Workspace：project 之下的持久工作上下文，回答"我此刻在哪个上下文里干活"；
• CodeTarget：workspace 实际操作的代码副本，可能是 project 根，也可能是一个 Git worktree。

在这套模型里，AI 不是内置的、调云端 LLM 的聊天框，而是用户亲手拉起、跑在 workspace 终端里的 CLI agent 进程。Cordy 只负责托管和监控它们，不碰它们的 provider、prompt、context 或 approval。

这个定位有一个直接后果：终端的正确性，就是产品的地基。

为了让并行 workspace 之间的切换做到"瞬间、像所有任务都活着"，Cordy 把 terminal / TUI / agent 的生命周期从渲染进程里彻底剥离，放进一个独立的 Rust runtime（跨平台的 tmux-equivalent + CLI agent supervisor）。渲染层只是一个可以随时销毁、重连的视图：renderer reload、workspace 切换、甚至 Windows 上"关到托盘时销毁整个渲染进程"的瘦壳架构，都不能杀掉后台的 PTY。

当会话的寿命长到能跨越窗口销毁、当同一个终端要被反复 attach / detach，任何一个字节级的错误都会被放大成用户能一眼看到的糊画面、重复行、跳字。下面是这条地基上先后浮现、又被逐一了结的五桩案子。

---

第一案：重复的启动横幅

症状与那条决定性线索

每次从托盘恢复窗口、或者 reload 之后，终端顶部的 shell 启动横幅（那种 "PowerShell … took 2126ms" 的启动耗时提示）会多出来一份。看上去像是 shell 被重启了一次。

但真正破案的，是那个耗时数字：两条横幅上写的都是 took 2126ms，一毫秒不差。

决定性线索：如果 shell 真的重启了，第二次的启动耗时不可能和第一次逐字节相同。两条一模一样的 2126ms 只能说明——这不是一次新的 shell 启动，而是同一段旧字节被重放了两遍。问题不在进程，在我们对字节流的处理。

根因：把绘屏协议当成可重放日志

顺着"字节被重放"往下挖，根因浮出水面：Windows 的 inbox ConPTY 在每次 PTY resize 之后，会重绘整个视口。而当时 terminal.attach 的实现，是把 runtime 缓冲的历史字节，当作"历史日志"原样重放进一个全新的 xterm 里。

这是一个范畴错误。PTY 字节流不是面向"内容"的可重放日志，它是面向某个特定网格尺寸的绘屏协议——里面全是"把光标移到 (r,c)、清到行尾、重画这一屏"这类相对于当时网格的指令。一旦重放时的网格和录制时的网格不一致，原本"就地重绘"的一屏，就会变成追加在下面的重复行。启动横幅正是这样被复制出来的。

更糟的是，我们曾经试图在渲染层用"前缀匹配去重"来救场——检测重放进来的 ConPTY 视口重绘、把重复的部分丢掉。但这类启发式在真实时序下必然失效，有两个结构性原因：

• 8 KiB 的读块切分：runtime 按 8 KiB 分块读 PTY，一次整屏重绘经常被拦腰切成两块，落单的尾巴就被当成新行重放了出来；
• 节流合帧：为了不让 output flood 拖死 UI，输出会被节流合并，前缀被埋进合成帧的中段，任何"从帧首匹配前缀"的逻辑都对不上。

这一案最贵的一课：这个 bug 类被打了六次启发式补丁，每一次都在下一个"分屏 / 窗格几何"特性上线时原样复发。当一个修复需要靠"猜字节流长什么样"来生效，它就永远差一个时序反例。启发式跑在字节流上，迟早被时序击穿。

解法：抄 tmux / VS Code 的作业——内嵌一个 headless VT 模拟器

真正的终端（tmux、VS Code 的 pty-host）从不重放原始历史。它们在后端养一个屏幕状态：把每个 PTY 字节喂给一个 headless 的 VT 模拟器，需要恢复时，直接把"当前这块屏幕的状态"序列化出来。重绘指令在模拟器里被幂等地吸收——resize 十次，屏幕还是那一屏，不会变成十屏。

Cordy 照这个架构重写了 attach（协议版本 0.10.0，attach-as-snapshot）：

• 每个 terminal session 内嵌一个 headless VT 模拟器（avt，2000 行回滚，实测约 6.6 MB/session），在 session 状态锁下逐字节喂入 PTY 输出，并与 PTY 同步 resize——于是整屏重绘被幂等吸收；
• terminal.attach 不再返回"历史字节"，而是返回一个带判别式的状态：要么是 delta（缓冲环里的增量帧，仅当环完整覆盖了请求的 since 时——保住了"停靠式长回滚"重挂路径），要么是 snapshot（把模拟器在当前尺寸下的屏幕 + 回滚序列化出来，带 snapshotSeq）；
• 渲染层在 attach 往返期间扣住实时进来的 live 帧，拿到结果、应用完之后再按 seq 顺序放行——关掉了 bind-before-attach 窗口里的重复 / 乱序 / 丢帧三个竞态。

那些跑在渲染层的 ConPTY 重绘启发式（isConptyViewportRepaint / dropSupersededViewportRepaints）、主进程侧的镜像重放缓冲、四个从未被消费的 attach 遥测字段——全部删掉。

配套的还有一个"这个架构才做得出来"的回归测试：真 PowerShell，连做 3 次 ConPTY resize，断言快照把横幅恰好渲染一次——这是旧架构根本无法测试的接缝。

一个选型岔路：avt 还是 alacritty_terminal？

新架构立起来后，很快撞到 avt 的一堵墙：当一个全屏 TUI 占用备用屏（DEC 私有模式 ?1049h）时拍快照，会丢掉主缓冲的 scrollback——stock 的 avt::Vt facade 只暴露"活动缓冲"的行，而备用屏模式下活动缓冲就是那块零回滚的 alt buffer，进 TUI 之前的 shell 历史够不着。

摆在面前有两条路：换掉 avt，或者给 avt 打补丁。我们真的去评估了换成 alacritty_terminal——读源码 + 写行为测试，结论是它撞的是同一堵墙（grid 和 inactive_grid 都是私有、没有访问器），而代价却更高：

一个佐证：连 Zed 都是通过一个 tracked fork 消费 alacritty_terminal 的——对这一类 crate，"vendor 加补丁"本就是正常的嵌入策略，不是歪门邪道。决定：留在 avt。

于是把 avt 0.18.0 vendored 进 cordy-runtime/vendor/avt，经 [patch.crates-io] 接入、并从 workspace exclude（这样 cargo test --workspace 不会去编它的测试和 dev-deps）。补丁是纯 additive 的五个访问器，每一处都带 // CORDY-PATCH: 标记，刻意做成可以直接提交上游的形状：Terminal::primary_lines() / Vt::primary_lines() / Vt::active_buffer_type()、从 crate root re-export BufferType、以及 Line::wrapped()（给软换行 reflow 的后续留的，暂未消费）。序列化器改从 vt.primary_lines() 取主缓冲 scrollback 前缀——已从 vendored 源码核实 dump() 永远先画主缓冲的 view（从不画 scrollback）再叠 alt 内容，所以这个切分是精确的，primary 模式下的输出和从前逐字节一致。CORDY-PATCH.md 记下了 base 版本、动机，以及移除条件（上游发布等价公开 API 后删掉 vendor 目录）。

---

第二案：中文 IME 之战

"版本 pin 不是修复"

第二案是从一次回归开始的。此前 Cordy 为 xterm 的中文输入法打过一个补丁；后来某次升级 Electron 42 时，有人以"beta.220 已经修好了"为由，把那个 xterm IME 补丁、连同它的回归 harness flow 一起删掉了。

结果：agent TUI 里的中文 IME 从两条战线上同时崩了。

这一案的第一课：把一个上游依赖 pin 到"据说修好了"的版本，不等于修复。没有一个能证明"修好了"的回归门禁在，任何"升级顺手删补丁"的操作都会悄悄把老 bug 放回来——而且是在你最没防备的时候。

合成一个 TSF forge，让缺陷现原形

要把这个 bug 钉死，得先能稳定复现它。真实的微软拼音很难在自动化里驱动，于是我们合成了一个 TSF（Windows Text Services Framework）形状的事件流 forge，模拟 IME 的提交序列。证据一下子就清楚了：

在未打补丁的构建上，用 forge 连续提交 3 次"临时"，xterm 实际发射了 6 块文本。3 → 6，字被翻倍了。

根因是两个独立缺陷：

• (A) 双提交 / 吞字：_finalizeComposition 让已提交的文本在隐藏 textarea 里累积（只在 Enter / Ctrl-C / blur 时才清），并靠 substring 切片去推导"这次提交了什么"；而在 TSF 形状的事件流下，_inputEvent 会把同一段文本再同步发射一遍。累积 + 二次发射，就是 3 变 6 的来源。
• (B) 候选窗跳位：xterm 在每一帧 render 都把 IME 的 textarea 和 .composition-view 重新锚定到真实的 buffer 光标格。而全屏 TUI（比如 Claude Code）会把硬件光标停在非输入位置、还高频重绘——于是候选窗落在错误的单元格上，并随着每一帧重绘满屏乱跳（实测锚点在 80,16px 与 232,32px 之间反复横跳）。

修复：单次发射 + 冻结锚点

补丁（pnpm patch 打在 @xterm/xterm@6.1.0-beta.220 的 lib/xterm.mjs 上）对症下两刀：

• composition 期间让 _inputEvent 让位，_finalizeComposition 成为唯一发射者，每次 finalize 后清空 textarea 和记账——单次发射，3 就是 3；
• 在 compositionstart 时冻结候选窗的锚点格，composing 期间跳过逐帧重锚。哪怕 TUI 用 DECTCEM 把硬件光标藏了、或者把它停在漂移的位置，候选窗也稳稳锚在组合开始时的那一格。

这里有个诚实的边界要交代：真实的 Claude Code（v2.1.207）在输入提示符处关掉了硬件光标（DECTCEM off），还把它停在随重绘时机漂移的位置。所以我们的补丁能保证候选窗位置稳定，但它的绝对精度受制于 TUI 自己的光标纪律——这是外部程序的行为，不是我们能在终端层根治的。

把回归 flow 变成常驻门禁

补丁修好只是一半。这一案真正的产出，是工程文化上的：那个曾被删掉的 ime-composition harness flow 被复活成一条常驻门禁，里面就是那个 TSF forge + 锚点跳变场景——在未打补丁的构建上实测 FAIL（6 块发射 + 锚点跳动），打补丁后 PASS。

这一案的第二课：没有门禁的修复，等于没修。 从今往后，任何人想"升级顺手删补丁"，都会先被这条门禁拦下来。合成 TSF forge ≠ 真实微软拼音，所以真人拼音手测仍然是最终验收步骤（本轮已于 2026-07-12 实测通过：长句连打干净、无吞字无重复）——但更重要的是，静默地把补丁丢掉这条路，被焊死了。

上游跟踪有一个后来才发现的曲折：这个缺陷最初被归因到 xtermjs/xterm.js#5887 与 #5894，但深挖后发现那两个其实是 macOS WKWebView 环境的 bug，与我们这个 Windows TSF 缺陷并非同源——我们修的缺陷在上游至今没有对应的 issue，把 forge 复现提交上游是一个待办。删补丁的时机：上游某个版本经 forge 验证确实修复了 finalize 缺陷、且真实拼音在 CLI-agent TUI 内手测通过之后（回归门禁永久保留）。

---

第三案：Codex 的纯黑输入条，与 ConPTY 的真相

症状：浅色主题下，一条突兀的黑输入条

Codex CLI 在 Cordy 的浅色主题下，底部输入条渲染成了深色底——在一片浅色里格外扎眼。

Codex 靠 OSC 10/11（查询终端前景 / 背景色）来决定输入条配色。所以问题变成：这个查询，为什么没得到正确答复？

双端插桩，锁定 inbox ConPTY

我们在两端同时插桩：子进程发出 OSC 11 查询的那一刻，和 Cordy 的 PTY master 收到回包的那一刻。实证结论很干脆——Windows 的 inbox ConPTY 在查询到达 Cordy 的管线之前，就把它吞掉了：既不转发、也不作答。Codex 探测超时，按深色兜底，而且在 Windows 上不再重探测。

作为对照组，同一个 Codex 跑在 Windows Terminal 里，OSC 查询能在 1–2ms 内被应答，Codex 就正确适配了。差别不在 Codex，在谁在提供那个伪终端。

我们先做了一个能立刻见效的旁路：让终端的 COLORFGBG 随主题下发（协议 0.11.0，terminal.create 携带 appearance，浅色 spawn "0;15"、深色 "15;0"，语义和真实终端一致——只影响新建 session，不影响运行中的）。这条通道让读 COLORFGBG 的 TUI（vim / neovim 的背景自动探测、delta 等）正确判定了背景。但它对 Codex 无效——Codex 只认 OSC 探测，不读 COLORFGBG。要真正根治，得让 OSC 查询能穿透。

VS Code 的答案：直接捆一个现代 conpty

这一类问题，VS Code 早就趟过了。它的解法是随应用捆绑 Windows Terminal 的 ConPTY 构建（开关 windowsUseConptyDll，自 2026-05 起默认开启）；wezterm 也是同样的做法。而 portable-pty 恰好优先 LoadLibraryW("conpty.dll")——Windows 的 DLL 搜索顺序会先查可执行文件自己的目录——只有在这个 dll（或它那三个无前缀导出）解析不到时，才回退到 kernel32 的 inbox ConPTY。

也就是说，对我们而言，这个修复几乎是纯打包 + 可观测性的事。

我们的移植：三重防线

我们把微软签名的匹配对 conpty.dll + OpenConsole.exe（版本 1.24.260512001，取自 microsoft/terminal v1.24.11321.0 release 附带的 Microsoft.Windows.Console.ConPTY nupkg，MIT 许可）vendored 到 cordy-runtime/vendor/conpty/win-x64，配了三重防线：

1. portable-pty 原生 sideload：dev 构建把这对文件复制到 debug/release 的 cordy-runtime.exe 旁；打包构建经 electron-builder 的 extraResources 一起 ship 到 resources/runtime/win32/——不需要改一行 runtime 代码，靠的就是 DLL 搜索顺序。
2. 微软签名的成对产物：两个文件都经 Get-AuthenticodeSignature 验证为 Microsoft 签名、Valid、PE machine 0x8664，SHA256 记录在 PROVENANCE.md。
3. 静默回退的 tripwire：runtime 每进程一次在 tracing::info 记录活动后端（sideloaded conpty.dll vs inbox）。这一条是专门为一个尖角设的——conpty.dll 在、但 OpenConsole.exe 漏带时，portable-pty 会静默退回 inbox 的老坏行为，不报任何错。这条日志就是抓这种打包失误的探针。

这里有一条不能违反的匹配对纪律：conpty.dll 和 OpenConsole.exe 是一起构建的一对，conpty.dll 会把 OpenConsole.exe 作为控制台宿主拉起，版本错配会崩溃（wezterm 就踩过这个坑——新 dll 配旧 exe）。规则很硬：永远在同一个 commit 里、从同一个 nupkg 版本、成对替换两个文件。

端到端的回归门 conpty-osc-roundtrip 证明了整条链路：子进程发 OSC 11 查询 → xterm 用实时主题作答 → 回包抵达子进程 stdin——在 inbox ConPTY 下实测 FAIL（隐藏 dll 时子进程报 CORDY_OSC11_MISS），sideload 后 PASS。

意外的红利：第一案的始作俑者，从源头消失了

现代 conpty 还带来一个没预料到的红利：它发出的是一条更干净的 VT 流——不再有整屏的 ESC[2J ESC[H 视口重绘。

这正是第一案里那个"每次 resize 就整屏重绘"的元凶行为。换句话说，当初逼着我们去内嵌 VT 模拟器的那个源头，在 sideload 现代 conpty 之后，从根上消失了。VS Code 也正是把这条"更干净的流"归功于它最佳的 IME 表现。两案在此闭环。

收尾：合成的 OSC 回环 ≠ 真实 Codex 的观感，所以最终仍以真人验收为准——2026-07-12 实测通过：浅色主题下 Codex 输入条随主题正确渲染。上游脉络：openai/codex#2020、#16411、#18942（Codex 侧的探测行为）；microsoft/terminal#3718（ConPTY 不透传查询的原始 issue）→ microsoft/terminal#17729（2024-08 合入的 OSC 查询透传修复，正是捆绑版携带的能力）。

---

第四组：两桩收尾小案

主动 workspace 恢复：问题在"写侧没有路径"

从托盘恢复（或 reload）时，Cordy 总是落到最后创建的那个 workspace，而不是用户离开时正在用的那个。

顺着直觉，很容易去怀疑"读侧被覆写"。但真正的根因更根本：选择一个 workspace，这个动作从来就没有持久化路径。 activeWorkspaceId 只被生命周期操作（create / open / close）写过；点击 / 滚动激活只改了渲染层的 store，suspend 交接时也从没把它 flush 下去。所以快照里存的，永远是"最后创建的 id"。

这一案的一课："写侧没有路径"比"读侧被覆写"更根本。当一个值总是错的，先别急着查读取逻辑——先问它到底有没有被正确地写下来过。

修复让"选择"搭上既有的 debounced layout flush，作为一个顶层 active 补丁（latest-wins 合并；存在 active 就把补丁标记为非空，于是 suspend 交接的 flushNow 会把它排空，快关竞态也被覆盖）。启动 hydration 用一个不触发 flush 的路径回放持久值，避免和并发的生命周期写抢；store 在写入时重新校验陈旧 id，让迟到的 flush 也没法把指针卡死。写侧回归测试在修复前失败、修复后通过；一个端到端 store 测试覆盖了原样上报的场景（3 个 workspace，陈旧 active = 最后一个，选第一个，冷 reload → 落到第一个）。

WebGL 重取时缺了一次 refresh：光标消失了

切回一个终端窗格（workspace / tab 切回来）时，偶尔会看到一帧陈旧画面——最明显的是光标 / 插入符不见了——直到 TUI 下一次自我重绘才恢复。

两处缺口：acquireWebglAddon 加载了 addon 并做了 fit，却从没 refresh（它的 dispose 兄弟函数做了）——于是一个在隐藏期间 WebGL addon 被驱逐的窗格，重取时进了一块陈旧的 canvas；而 isActive 返回路径只重取 + focus，从不强制重绘，隐藏期间攒下的任何陈旧都活过了激活。

修复让重取路径镜像 dispose 路径、做一次全视口 refresh；激活时通过一个 disposed-guarded 的 refreshViewportRef 调度一次 frame-settled 的重绘。这里也守住了不过度设计的边界：context-loss 的顺序经核实本就正确（renderer swap 先于 refresh），之前观察到的"无恢复"其实是 SwiftShader 的假象，所以没有加任何投机的机器。两个回归测试把行为钉住：驱逐后重取会重绘、变为活动会重绘。

附带一提，同一波清理里还顺手了结了一条 dev 期噪音：reader thread exiting 的裸 WARN 每创建一个终端就响一次，读起来像"会话死了"。根因是 React StrictMode 把 bootstrap effect 挂了两遍，第一次挂载创建的 session 在 disposal 之后才 resolve、随即被杀——一个真实存在的短命 session。日志现在总是带 session_id，并按（退出原因、was_running）分级：已 Exited 会话的 EOF 和拆除属 debug，只有仍 Running 会话上的读错误才留在 warn。有意思的是，这条 ConPTY 构建从不在 master 上投递 EOF（实测：子进程退出 40s 后仍无 EOF——这正是 spawn_exit_watcher 存在的理由），所以被杀的短命 session 表现为 broken-pipe 读错误，而不是 EOF。

---

方法论：给同类构建者的可迁移经验

五桩案子背后，是一套反复起作用的方法。如果你也在给自己的工具造终端 / PTY 地基，这几条大概率能直接搬走：

1. 差分诊断——把成熟工具当对照组。 每一案都有一个"它在别处不这样"的参照：Superset 的 terminal daemon、VS Code 的 pty-host、Windows Terminal 的 OSC 应答。对照组不只是灵感来源，它是假设检验的实验对照——"同一个 Codex 在 Windows Terminal 里 1–2ms 就应答了"这一句，直接把嫌疑从 Codex 洗到了 inbox ConPTY。

2. 证据先于修复——每个根因都得有一个实验数字。 两条 2126ms、3 → 6 块、6.6 vs 9.9 MB、OSC 应答的 1–2ms 对照。这些数字不是装饰，它们是"根因确实是它"的证明。拿不到数字之前，不要动手改代码——先列出未知项，再找能证伪假设的最小反例。

3. 根治 vs 补丁的判据。 一个可操作的判据：当一个修复要靠猜字节流的形状（前缀、长度、分块边界）才能生效，它就是补丁，迟早被时序击穿。 第一案的六次启发式复发就是反面教材。根治是换一个不依赖时序假设的模型——后端养屏幕状态、拍快照，而不是在渲染层猜历史。

4. 防回归三件套。 修复交付时，配齐三样：双向的 harness 证据（未打补丁 FAIL、打补丁 PASS，两个方向都测——单测"打补丁能过"证明不了"没补丁会挂"）、后端的 tripwire 日志（每进程一次记录活动后端，抓静默回退）、成对更新纪律（匹配对文件、协议 + TS bindings 必须同 commit 动）。IME 那条被复活的门禁，就是"没有门禁的修复等于没修"的直接体现。

5. 当一类 bug 在 VS Code / wezterm 里不存在时，先看它们捆绑了什么。 这是最省时间的一条。Codex 的黑输入条、乃至第一案的整屏重绘，答案都藏在"VS Code / wezterm 随应用捆了一个现代 conpty"这件事里。成熟工具用打包解决的问题，往往不需要你去发明新算法——照着捆一份就好。

---

附：关键提交索引与上游引用

这轮攻坚落地的提交（cordy-desktop，monorepo 内含 cordy-runtime/ Rust workspace）：

上游引用（均可回溯到仓库内的 commit / PROVENANCE.md / 维护轨道）：

• xterm.js IME：我们修复的 TSF finalize 缺陷在上游尚无对应 issue（提交 forge 复现是待办）；早先误归因的 xtermjs/xterm.js #5887、#5894 实为 macOS WKWebView 问题，留此存照；
• Codex OSC 主题探测：openai/codex #2020、#16411、#18942；
• ConPTY OSC 透传：microsoft/terminal #3718（原始 issue）→ #17729（透传修复，2024-08）；VS Code 默认启用捆绑 conpty：microsoft/vscode #315951（2026-05）；捆绑的 conpty 取自 microsoft/terminal release v1.24.11321.0 的 Microsoft.Windows.Console.ConPTY nupkg（1.24.260512001，MIT）；
• xterm WebGL context-loss 回退（避免空白终端）：microsoft/vscode #263159；keep-alive 中间档提案被拒：microsoft/vscode #113507、#47653。

内部权威源：cordy-runtime/vendor/avt/CORDY-PATCH.md、cordy-runtime/vendor/conpty/PROVENANCE.md、docs/Tracking/v1.x-maintenance-tracking.zh-CN.md（已知限制表）、docs/architecture/cordy-local-agent-runtime-design.zh-CN.md、docs/architecture/workspace-keepalive-design.zh-CN.md。

---

终端很老，老到人们默认它"早就做对了"。但当你把它放进一个要跨窗口销毁存活、要托管别人家 CLI agent、要在浅色主题下正确应答一个 40 年历史的转义序列的本地工作台里，每一处"默认对"都会变成一桩要亲手侦破的案子。地基之所以是地基，正因为它得先扛住这些。