Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

写在前面

前阵子看到有人在讨论 Agent 的 TUI 和 GUI,两派吵得挺热闹。

我刚好两边都做过算是比较深入的研究,用 Swift 从零开始写过一个 TUI 渲染引擎(ForgeLoopTUI),也写过 iOS 上的 Agent GUI 客户端。在创作和优化性能的过程中,记录下来不少的笔记和代码,以及各种踩坑和思考。

写这组文章之前,我翻了一遍自己攒下来的东西:项目源码、调试笔记、性能分析记录、读过的博客和开源库的源码、知乎上的相关讨论。散在好几个文件夹里,有些是完整的文档,有些只是当时随手记的片段。觉得这些东西放着也是放着,不如整理出来。

于是重新梳理了一遍,缺的地方补研究,浅的地方往下挖,写成了这本小册。全书按方向分四个部分,连起来是一条从界面挖到地基、再回头检验的路线:界面讲怎么把东西画出来,从 ANSI 转义序列、Markdown 流式渲染的 O(n²) 陷阱,到权限和 diff 的 UX 设计、多端架构;胶水层和基建再往下挖,讲连接、会话和协议边界,把界面撑起来的那半边;评测回答最后一个问题:建起来之后,怎么证明它真的在工作。书里的结论都拿我自己的引擎 ForgeLoopTUI 和各家 agent 的源码核对过,核出来的错,多半先错在我自己身上。

这本册子会持续更新,不是写完就算完的那种:方向挖到哪,部分就长到哪;已经写下的内容也可能更正,发现写错的会改,判断变了的会补记。另外,按目录从上往下读就行。

不是什么权威结论,就是一个人同时踩过 TUI 和 GUI 两条船之后,把踩过的坑和想清楚的事记下来。如果恰好对你有用,那就最好了。


这本小册的前身是连载系列《Agent 时代的开发者界面》,写着写着从界面一路挖到了地基,成书时改了名。公众号上已发布的早期篇目仍挂旧名,内容为同一套。

为什么 Agent 从 CLI/TUI 开始——兼论程序员的信任模型

从做过移动端、桌面端、TUI 和全栈的视角,重新理解 AI Agent 时代的人机界面与开发者工作流。第一篇讲清楚 Agent 为什么先走终端这条路。


一、一个场景

一个 coding agent 接到“修复测试失败“的任务。它不是直接给你答案。它会:

rg "UserSession"                          # 搜索调用链
cargo test 2>&1 | head -40                # 跑测试,看失败输出

读文件,找到可疑点。修改。再跑测试。发现又失败了——不是刚才那个 case,是另一个被牵连的。再改。再跑。通过了。然后:

git diff                                 # 展示变更

等你确认要不要提交。

这个过程从头到尾、每一步都在终端里发生。与其说终端被选成了 agent 的界面,不如说 agent 的工作方式本来就是一个终端会话。

2025-2026 年,Anthropic 的 Claude Code、OpenAI 的 Codex CLI、Google 的 Gemini CLI、Block 的 Goose、Aider(2023 年先行者)、Devin CLI(Cognition)、Qwen Code 等等,头部 coding agent 里,CLI/TUI-first 是压倒性多数的选择。这些团队并非请不起 GUI 设计师,而且实际上也在朝着 GUI 的方向前进。他们做出同一个选择,有结构性的原因。

补记(2026.09,发布前):这段判断和“压倒性多数“的说法形成于几个月前。到文章发布时,GUI 这侧的进展已经不止是“方向“:Anthropic 在 4 月给 Claude Code 的桌面端做了完整改版,专为并行 agent 工作流设计(官方博客);OpenAI 在 7 月把 Codex 应用并入了新版 ChatGPT 桌面应用(Codex 更新日志);Google 在 5 月的 I/O 上把 Antigravity 从 IDE 扩成了 agent-first 平台,桌面应用、CLI 和 Gemini API 里的托管 agent 一起发布,9 月又更新了托管 agent 的版本(I/O 开发者回顾、托管 agent 文档)。CLI/TUI 仍然是这些产品的地基,这篇讲的正是地基为什么先是终端;但“多数派“的叙事正在快速过期。这个趋势不推翻本文的论证,后面的“多端投影“框架就是为它准备的。


二、最直接的回答:工作对象决定了工作界面

Agent 的工作对象是什么?

  • 代码文件(文本)
  • 命令行工具(文本输入,文本输出)
  • 编译器 / linter / 测试框架(文本输出)
  • git diff / log / status(文本输出)
  • 日志和错误堆栈(文本)

所有这些,最自然的显示介质就是终端。终端就是为文本而生的。

反过来看 GUI 里展示这些东西的成本:

  • 代码块:需要语法高亮引擎 + 等宽字体 + 复制按钮
  • 终端输出:需要 ANSI 转义序列解析 + 虚拟终端模拟器
  • diff:需要并排对比视图 + 行级高亮 + 部分采纳/拒绝交互
  • 日志:需要虚拟滚动 + 搜索过滤 + 级别着色

每一项在 TUI 里是 print(),在 GUI 里是一个子系统。当然,print() 只是输出的起点,如果想让输出在流式场景下保持可读、可排版,是另一套引擎的成本,下一节就会看到。GUI 并非做不了,只是在 agent 还在快速迭代、工具调用协议还在变化、权限模型还在试探的阶段,每加一个 GUI 子系统就多一份维护负担。

我之前看一个说法:做 GUI 要么 VSCode 换皮(功能上限被封死),要么自研(至少半年以上)。而 CLI 是每个 agent 无论如何都要提供的核心功能——SSH 进去、WSL 里跑、CI 里执行,CLI 是唯一通用解。算下来结论很朴素:GUI 太贵,CLI 绕不开。


三、“1D → 1D“这个说法对吗?

我看有人提过一个简洁的直觉判断:LLM 的输出是 1D 的(线性 token 流),CLI 也是 1D 的(线性文本输出),所以天然匹配。

这个判断对了一部分:对于最简单的“用户问 → AI 答“场景,确实如此。

token 到达 → 显示字符 → 下一个 token → 追加字符。算得上一条直线。

但 Agent 的真实输出不是一条直线。它是这样的:

用户消息
  ├── thinking(推理过程,可能很长)
  ├── 工具调用 1(开始 → 运行中 → 完成)
  │     └── 工具结果回传
  ├── 工具调用 2(可能与工具 1 并行,且可能比工具 1 先返回)
  ├── thinking(基于工具结果继续推理)
  └── 最终回复(流式输出)

这是一棵树。而且节点到达的顺序不满足这棵树的拓扑序(父节点、靠前的子树并不保证先到)。工具调用 2 可能比工具调用 1 先返回,thinking 块可能在流式输出的中途插入,用户随时可能按取消键。

CLI 之所以“看起来适配“,是因为 TUI 渲染引擎在背后做了大量工作,把一棵乱序到达的树强行展平成了线性输出。Agent 的输出本身并不是 1D 的。

这套展平机制(稳定槽位队列、shiftIndices 偏移追踪、thinking 原地替换、有上限的 FIFO 通知队列)的核心只有几百行 Swift 代码。本系列第 4 篇会详细拆解。这里我们先接受一个结论:“1D → 1D“是用户看到的最终效果,不是 Agent 的真实结构,而且这个效果的实现成本不低。


四、更深层的原因:Agent 的状态模型还没稳定

一个普通 GUI 应用的信息架构通常很清晰:列表、详情、表单、编辑器、设置、通知。这些状态是预设的、有限的、可以画成状态机的。

Agent 的真实流程更像一个动态 workflow engine:

用户提出自然语言目标
  → agent 自己拆任务
  → 读取上下文
  → 搜索文件
  → 执行命令
  → 遇到错误
  → 修改计划
  → 编辑文件
  → 重新验证
  → 请求权限
  → 等待用户介入
  → 中断后恢复
  → 总结结果

每一步都不可预测。你不知道下一个事件是 thinking 还是 tool call 还是 streaming text 还是 error。你不知道用户会不会中途打断。你不知道工具返回是 3 行还是 3000 行。

在状态模型还在快速变化的阶段,过早投入重型 GUI 是在为一个还没定型的系统设计固定布局。CLI/TUI 的处理方式是务实的:把复杂过程线性化为事件流,一行一行往下写。等到事件模型稳定了,再考虑 GUI 怎么投影这些事件。

这解释了为什么 Aider(2023)、Claude Code(2025)、Codex CLI(2025)都走了 CLI-first 路线。倒不是请不起人做界面,当时的首要任务是把 agent runtime、工具调用协议、权限模型和失败恢复跑通。CLI 是最低成本、最快反馈的实验台。


五、环境继承:零成本的“进入现场“

开发项目的真实环境通常很复杂:多语言、多包管理器、monorepo、私有依赖源、本地证书、SSH key、git credential、自定义 Makefile / Justfile、CI 脚本、shell profile、环境变量、docker / dev container……

CLI Agent 默认运行在项目目录中。它直接继承:

cwd             → 就在项目根目录
PATH            → 所有本地工具链可用
env             → 项目需要的环境变量都在
git config      → 用户身份、凭证、hooks
SSH config      → 私有仓库、远程服务器

零配置。cd ~/project && claude 就够了。

GUI 要做到同样可靠,需要额外处理一堆桌面端问题:

  • 文件系统权限(macOS sandbox、Windows UAC)
  • shell 环境继承(login shell vs non-login shell 差异)
  • 跨平台差异(路径分隔符、换行符、进程管理)
  • code signing、auto update、crash recovery
  • terminal pty(伪终端)管理、child process lifecycle
  • 企业网络、proxy、VPN

每多一层桌面集成,就多一层出错的可能。在“继承开发环境“这个维度上,CLI 是最可靠的方案。


六、中场过渡:这些解释了“为什么 CLI/TUI 先出现“,但还有一个更深的问题

以上说了四个原因:

  1. 工作对象是文本 → 终端最自然
  2. 做 GUI 太贵,CLI 绕不开 → 经济上的必然
  3. 状态模型未稳定 → CLI 是低成本实验台
  4. 环境继承零成本 → 直接进入工程现场

这些足以解释为什么 agent 从 CLI/TUI 起步。但还有一个更深的问题:为什么程序员更信任 CLI/TUI agent?

因为 CLI/TUI 满足了一个程序员对开发工具最核心的三个需求。


七、程序员信任开发工具的三个条件

7.1 可观察

程序员接受一个 agent 的前提是:我能看到它在做什么。

不是“我相信它“,是“我能验证它“。具体来说:

  • 它准备改哪些文件?
  • 为什么改这里?
  • 跑了什么命令?命令输出是什么?
  • 测试失败在哪里?哪一行?
  • diff 是否合理?有没有误改无关文件?
  • 是否访问了网络?是否改了 lockfile?
  • 是否提交或推送了?

CLI/TUI 在这个维度上有天然优势:命令、输出、diff、错误堆栈,全部以原生形态展示在终端里。GUI 要做到同等可见性,需要设计专门的信息面板——命令历史面板、输出日志面板、diff 审查面板。这部分的复杂性远比 TUI 大得多。

7.2 可复现

agent 做的事,用户自己能复现吗?

CLI Agent 的每一个操作——读文件、跑测试、git diff——用的都是项目里的真实命令。输出是这些命令的真实输出。如果 agent 说“测试通过了“,用户可以在自己的终端里跑同一行命令验证。

更重要的是:如果 agent 做错了,用户可以接管。git reset HEAD~1,手动改,重跑。agent 没有引入一个“只有 agent 能操作“的中间层。

7.3 可回滚

所有 agent 的代码变更都在 git 工作区里。

用户可以 git diff 逐行审查,可以 git add -p 分块暂存,可以 git checkout -- <file> 撤销。git 本身就是最可靠的安全网:agent 会犯错,但错误可以被精确回退。

这三条:可观察、可复现、可回滚,合在一起,构成了程序员对自动化工具的信任边界。程序员不讨厌自动化,讨厌的是不可解释的自动化:一个黑箱告诉你“搞定了“,你却看不到它做了什么,既无法验证,也无法回退。


八、三种界面在信任模型上的差异

CLI/TUIGUI/DesktopIDE 插件
可观察命令和输出原样展示,diff 原生渲染需要设计专门的信息面板与编辑器深度集成,但 agent 操作的边界可能模糊
可复现每个命令都可以复制、重跑命令可能被抽象为按钮操作取决于插件暴露多少底层命令
可回滚git 工作区原生可见,用户完全掌控git 操作可能被 GUI 封装编辑器的 undo + git 双重保障
信任建立速度快——看到命令和输出就信任了中——需要额外验证中——编辑器的 undo 历史提供安全感
黑箱风险低——所有操作以文本形式暴露高——容易被封装成“一键完成“中——可能在编辑器后台悄悄改文件

这张表不是要证明 CLI/TUI 在所有维度上优于 GUI。事实上,不管是我自己的思考还是现实的进展,都指向 GUI 化是方向。GUI 在 diff 审查(并排对比、行级采纳/拒绝)、长会话管理(cell 复用、分页加载)、多模态附件(图片、文件预览)上有结构性优势。这些在本系列后篇会展开。

这里要说明的是另一件事:**CLI/TUI 在当前阶段相对胜出,理由不在“更好“,而在于它天然满足这三条信任基线。**做 GUI 的时候如果忽视了这三个维度,把 agent 包装成一个“一键完成“的按钮,反而会失去开发者用户;之后随着 Agent 水平继续提升、走向同质化,GUI 的需求自然会跟进。


九、不只是“早期形态“

有一种观点认为 CLI/TUI 只是 agent 的“早期原型“,等产品成熟了自然会转向 GUI。目前是探索 Agentic 框架的阶段,界面是次要的。Claude Desktop 和 Codex App(2026 年 7 月起已整合进 ChatGPT 桌面应用)的出现似乎也在印证这个方向。

我也是认同这个观点的。GUI 确实会在更广泛的用户群中占据更大份额。非技术用户不会打开终端,而即使是程序员用户,也并非都天然喜欢 TUI,GUI 在使用便利上是明显优于 TUI 的。

但另一半隐含了一个更强的假设:CLI/TUI 和 GUI 是线性进化关系,前者迟早被后者迭代掉。

SSH 到远程服务器跑 agent、CI/CD 流水线里集成 agent、在 tmux 里恢复一个跑了 3 小时的会话,在这些场景里,CLI/TUI 的位置是什么?“进化论“这个框架回答不了。后面会给出另一个框架 Event Sourcing:CLI/TUI 和 GUI 不是谁迭代谁,而是同一条事件流在不同介质上的投影。这里先按下不表。


十、总结

这篇文章试图回答一个问题:为什么 2025-2026 年的头部 coding agent 在一开始绝大多数选择了 CLI/TUI-first,而且这不太可能是一个会被“快速迭代掉“的早期选择。

三条线汇总:

  1. 工作对象和工作方式决定了起点 agent 操作的是代码、命令、git、测试、日志——终端生态是原生匹配。GUI 要为每一样东西写一个子系统,工程成本不在同一量级。

  2. 状态模型未稳定 + 环境继承零成本 agent 的工作流是动态的、不确定的、会中断和恢复的。CLI 用线性事件流处理复杂性,同时零配置继承开发环境的全部上下文。

  3. 信任模型天然匹配 可观察(命令和输出原样展示)、可复现(每个操作都可以手动重跑)、可回滚(一切在 git 工作区里)。说到底,终端让 agent 的行为可以被审计。

CLI/TUI 是 Agent 在“执行阶段“的最优投影。

GUI 的机会在下一层——把复杂过程结构化、把 diff 和风险审查化、把多任务和团队协作产品化。这会是本系列后续各篇逐步展开的内容。

接下来会沉到技术底层:**TUI 到底是怎么渲染的?**下一篇从 ForgeLoopTUI 的实际源码出发,讲 ANSI 转义序列、字符网格、物理行与逻辑行、增量 diff 和 RenderLoop 帧调度,看一个 TUI 渲染引擎到底在做什么。


参考与延伸

系列全部技术细节基于 ForgeLoopTUI v1.2.0 和 FlowDown 的实际源码分析。

TUI 不是低配 GUI——字符网格里的渲染引擎

上一篇讲了 Agent 为什么从 CLI/TUI 开始,这一篇沉到技术底层:TUI 到底是怎么渲染的?那个在终端里看似简单的界面,底下是一套什么样的引擎?


一、从一个常见的错觉说起

上一篇讲了 2025-2026 年的主流 coding agent 为什么绝大多数是 TUI-first(名单、时间锚点,以及 2026 年秋天 GUI 一侧的进展,见第 1 篇和它的补记),这一篇讲它们脚下的技术底座。

很多人对 TUI 的印象是“在终端里画界面“:用 Bubble Tea(Go)、Ink/React(JS)、Ratatui(Rust)这类现成框架组合几个组件,就能在终端里做出类似 GUI 的布局。

这条路能做出来。很多项目也确实走通了。但这条路和“手写一个 TUI 渲染引擎“之间,隔着一段很少有人细看过的距离。框架帮你做了什么?框架没帮你做什么?不搞清楚这些,TUI 就永远只是“GUI 的低配模仿“。

这一篇以 ForgeLoopTUI(我用 Swift 写的一个 TUI 渲染引擎)的实际源码为参照,沿着从 ANSI 字节到屏幕字符的完整链路,逐层拆开一个 TUI 渲染引擎到底在处理什么问题。

  • 注:拿这个项目做参照,是因为它是我用 Swift 做的一个实验性质的产品。一开始并没打算做成实验品,但 Swift 生态里缺各种 TUI 基础组件,想实现什么功能都得手搓,这个过程让我学到了很多更底层的知识。

先交代一下坐标。本篇拆的是“全屏自管“这一派:屏幕上每一行都归引擎管,写完的内容也一直管着。另一派叫 inline viewport,内容一写完就交给终端自己的 scrollback,引擎只管底部一小块活区。下面拆的零件两派大多都要用,分歧只在写完的内容归谁管。这一点第十节先给坐标,完整对照在第 13 篇。


二、字符网格:一切困境的根源,也是一切优势的根源

TUI 的渲染介质是终端。终端输出的不是像素,是等宽字符网格。你可以把任何一个字符放在任何一个格子里——但放不下一个像素。

这个限制同时定义了 TUI 的上下限。

下限(做不到的):圆角、渐变阴影、可变字体、行内图片、自定义控件。一切只能靠字符和颜色表达。

上限(被低估的):24-bit true color 在现代终端里基本普及(iTerm2、kitty、WezTerm、Windows Terminal),语法高亮完全可以做到——只是需要手写 tokenizer。OSC 8 超链接(ESC]8;;<url>ESC\)可以让终端里的文本变得可点击跳转。Box-drawing 字符可以画出清晰的 UI 边界。

字符网格是限制,但它限制的是实现成本,不是表达上限。

但字符网格带来的麻烦比“没有像素“更根本:终端没有 undo。


三、终端没有 undo,你只能向前写

**声明式不是 GUI 的专利,命令式也不是 TUI 的本质。**Ink 让你在终端里写 JSX,框架 diff 完再发 ANSI;GUI 自己也命令式了几十年(QuickDraw、UIKit 手写 frame),声明式要到 React(2013)才在 Web 端成为主流。这是框架层的事,两种介质上都能长出来。

差异在更底下一层:程序和显示端之间的契约。

GUI 的显示端是有状态的:window server 和合成器持有每个窗口的像素,窗口被挡住再露出来,不用你的代码重画;点击落在哪个 view,系统替你做命中测试。手写 frame 也站在这套基础设施上。

终端给程序的契约是一条只写的字节流:字符发出去就进了模拟器的网格,你既不能回读“第三行第五列现在是什么“,也没有“撤销上一次写入“的 API。想改?只能用 ANSI 转义序列回到目标位置 → 擦除 → 重写。模拟器自己当然持有网格(否则它没法显示),但那份状态不在你的契约里。

整个增量 diff 渲染机制的复杂性都源于这一点。理想情况下不需要 undo,只需要 print()。但真做起来离不开 undo:Agent 的流式输出会高频触发渲染,不断改写已显示的内容(比如表格),所以你得精确知道光标在哪、上一帧是什么、差异从第几行开始,再生成一串 ANSI 序列,像手术一样修改屏幕上的内容。


四、ANSI 转义序列:半个世纪的遗产

4.1 工作原理

ANSI 转义序列的核心是 ESC(0x1B)后跟控制指令。最常见的 CSI(Control Sequence Introducer)格式:

ESC [ 参数 ; 参数 ... 中间字节 终结字节

常用序列速查(ANSI 坐标系是 1-based,行和列都从 1 开始):

序列含义
ESC[2J清除整个屏幕
ESC[H光标回到 (1,1)
ESC[5A光标上移 5 行
ESC[3B光标下移 3 行
ESC[10C光标右移 10 列
ESC[2K清除当前行
ESC[1;32mSGR: 粗体 + 绿色前景
ESC[0mSGR: 重置所有样式
ESC[5LIL: 在当前行插入 5 行
ESC[20GCHA: 光标水平移动到第 20 列

4.2 ANSI 状态机

只输出序列不需要解析器。但如果你要做 visibleWidth 计算——去掉 ANSI 序列后知道文本实际占据多少列——就需要能识别哪些字节是序列、哪些是可见字符。

我做 ForgeLoopTUI 的 ANSIParser 实现了一个字节级有限状态机:

ground ── 0x1B ──→ escape ── '[' ──→ csiEntry
  ↑                 │                  │
  ├── 可见字符       │ 非法 escape      ├── param 字节 → csiParam
  │                  ↓                  │
  └── 文本事件     ground             ├── 中间字节 → csiIntermediate
                                      │
                                      └── 终结字节 → 输出 CSI 事件 → ground

它处理了分片到达(一次 write() 只收到半个序列)、连续 ESC、非法中间字节这些边界情况。解析器本身不赋予样式语义——只区分“文本字符“和“CSI 序列“,语义由上层的 SGRState 和 VirtualTerminal 赋予。

4.3 终端能力的降级链

不同终端的能力差异巨大。我写的 ForgeLoopTUI 用 TerminalCapability 枚举建模了降级链:

truecolor (16M 色)   ← iTerm2, kitty, Windows Terminal, WezTerm
ansi256 (256 色)     ← tmux(screen-256color 常见配置), 老 xterm
ansi16 (16 色)       ← 最老的 xterm, 嵌入式终端
plain (无颜色)       ← 管道输出 (> file.txt), dumb terminal

NO_COLOR、TERM=dumb、isatty() 等环境检测,自动完成降级。GUI 里的 Dark Mode 自适应是手写的工作量,TUI 里靠终端颜色方案自动继承,但代价是你不知道用户终端到底是什么配色。


五、物理行 vs 逻辑行:所有计算的放大器

TUI 渲染中一个绕不开的错位:

你的程序操作的是逻辑行(\n 分隔),但 ANSI 光标移动需要物理行(wrap 后的显示器行数)。

GUI 里“一行太长自动换行“是文本引擎在布局阶段处理的,渲染层看到的就是已换行的结果。TUI 里换行是终端模拟器做的——你写一行 120 字符到 80 列宽终端,终端自己折成两行,程序不知道。

5.1 为什么物理行让增量 diff 翻倍复杂

增量 diff 的每一步都依赖物理行:

  1. firstDifferenceIndex 找到第一条变化的逻辑行 → O(min(m,n))
  2. 计算从帧头到差异点的物理行数 → O(n),累加每行 physicalRows
  3. 计算差异点之后旧帧的物理行数 → O(n)
  4. 用 ESC[<rewindRows>A 回退光标
  5. 逐行 ESC[2K 清除
  6. 再回退,写入新内容

每一步都依赖 physicalRows 的精确性。如果终端 resize(用户拖动窗口),所有缓存的物理行数全部失效——lastFramePhysicalRows、lastCommittedPhysicalRows、lastLivePhysicalRows 必须立即重算。少算 1 行,光标回退就差 1 行,新内容覆盖旧内容,屏幕变乱码。

5.2 physicalRows 的计算

public func physicalRows(for line: String, width: Int) -> Int {
    guard width > 0 else { return 1 }
    let vw = visibleWidth(line)           // 去掉 ANSI 序列后的可见列数
    if vw == 0 { return 1 }               // 空行占 1 物理行
    return (vw + width - 1) / width       // 向上取整
}

公式简单,麻烦在 visibleWidth 要先剥离 ANSI 序列(不占宽度但占字节),然后对每个 Unicode scalar 判定宽度。scalarIsWide 硬编码了 98 个 Unicode 区间,覆盖 CJK、假名、韩文、全角标点、emoji。这套区间是经验性的,不是规范性的:Unicode 每年更新,新 emoji 不断加入,各终端对“模糊宽度“字符的处理也各不相同。按 scalar 判定宽度的实现,在 ZWJ 序列(如 👨‍💻)和 VS16 变体选择符上都会算错,这是这类实现共同的盲区。


六、全量重绘 vs 增量 diff

6.1 两种策略

ForgeLoopTUI 提供两种 RenderStrategy:

legacyAbsolute:  清屏归位 ESC[2J ESC[H + 逐行输出全部内容
inlineAnchor:    基于上一帧缓存做增量 diff(默认)

legacyAbsolute 永远正确但大帧闪烁明显。

inlineAnchor 的决策链:

首帧(无历史)?      → 直接输出全部内容
帧高度超过终端高度? → 退化为 legacyAbsolute
两帧完全相同?       → 零渲染(仅调整光标位置)
否则                → 计算差异 → 回退 → 清除尾部 → 重写尾部

6.2 diff 算法与取舍

private func firstDifferenceIndex(lhs: [String], rhs: [String]) -> Int? {
    let minCount = min(lhs.count, rhs.count)
    for index in 0..<minCount where lhs[index] != rhs[index] {
        return index
    }
    return lhs.count == rhs.count ? nil : minCount
}

逐行字符串比较,O(min(m,n))。没用 Myers diff。原因很实际:

  • 流式场景里,增量大多来自尾部增长或局部修改——逐行比较够用
  • 物理行计算才是真正的瓶颈——每行都要跑 visibleWidth + physicalRows
  • 终端窗口通常 <100 行——引入一个 diff 库为这个规模不值得

这是 TUI 渲染和 GUI 渲染的一个微妙区别:GUI 一侧(无论是声明式框架 diff 两棵 view tree,还是 UIKit 这种命令式框架直接改控件)换行都由文本引擎在布局阶段算好,应用面对的始终是逻辑内容;TUI 里换行是终端模拟器替你做的、对你不可见,应用想知道自己写了几行,就得自己做物理坐标计算。所以瓶颈不在 diff 算法,在每行的宽度判定。


七、帧状态记忆

增量 diff 的前提是记住上一帧。TUI 类维护了 8 个关键字段:

previousLines            // 完整上一帧内容(用于逐行 diff)
lastFramePhysicalRows    // 上一帧总物理行数(用于光标回退计算)
lastCursorAnchored       // 上一帧是否锚定了光标
lastCursorOffset         // 上一帧的光标列偏移

committedLines           // committed 区上一帧(用于分区 diff)
lastCommittedPhysicalRows
previousLiveLines        // live 区上一帧
lastLivePhysicalRows

任何一个值算错,比如 physicalRows 差了 1,光标回退就差 1 行,整帧偏位。

7.1 光标放置的 undo 机制

Agent TUI 的典型布局:内容在上、输入框在下。渲染只能从上往下写,写完内容,光标在底部。然后需要把光标移到输入行。

ForgeLoopTUI 的做法:渲染内容后发出位移序列把光标移到目标位置,同时记录这次位移。下一帧渲染前,先发反向序列把光标移回“规范锚点“(最后一行末尾),再做 diff:

// 渲染后:记录位移
pendingPlacementUndoUp = upClamped
pendingPlacementUndoHorizontal = leftDelta

// 下一帧渲染前:先 undo
private func consumePlacementUndo() -> String {
    // 如有 marker 路径的精确 undo 序列则优先使用
    // 否则用相对位移恢复
}

两种光标模式:

  • .relative:ESC[nA/ESC[nD,简单但 IME 候选窗可能干扰
  • .marker:物理行计算 + ESC[<col>G(CHA 绝对列),对中文输入法更可靠

7.2 记忆的脆弱性

所有帧状态基于一个未明文的假设:终端模拟器行为与预期一致。但实际中不同终端对 wrap 行上的 ESC[nA 行为并不一致,IME 候选窗会临时劫持光标,tmux buffer 可能与外部终端不同步,用户可能在两帧之间滚动。

任何一个假设被打破,diff 坐标就出错,没有全局恢复。


八、RenderLoop:帧合并调度器

TUI 渲染的频率上限没必要对齐显示器的 60Hz,因为终端 ANSI 输出是串行字节流,没有垂直同步的概念。ForgeLoopTUI 的 16ms tick 是合帧窗口的上限,不是目标帧率,也不是承诺值。

normal submit  → 更新 pendingFrame → 启动 16ms 定时器
normal submit  → 覆盖 pendingFrame(只保留最新,不渲染中间帧)
normal submit  → 覆盖 pendingFrame
                  ↓ 16ms 到
                flush: 渲染 pendingFrame(合并后只画一帧)
                  ↓ 队列空
                停止定时器(零 CPU 空转)

设计要点:

  • 合并,不丢状态:保留最新帧,不渲染中间帧。最终状态正确
  • 即时通道:priority: .immediate 跳过合并直接渲染(用户回车、工具调用完成时)
  • 空闲即停:flush 后队列空则停 timer,下次 submit 时重启

Agent 流式输出每秒几十个 token,每个都可能触发渲染。不合并 = 每秒几十次渲染触发,每次都产生一串 ANSI 输出;合并 = 每 16ms 至多渲染一次。


九、Live Budget Planner + commit/live 分区模型

这是整个 ForgeLoopTUI 架构里最重要的两个设计决策。

9.1 commit / live 分区

把一帧切成两块:

┌──────────────────────────┐
│  用户消息                 │  ← committed: 只追加,不改写
│  AI 已完成回复             │  ← committed: 只追加,不改写
│  ───────────────────     │
│  AI 流式输出中...         │  ← live: 每 tick 都可能变
│  工具调用: running...     │  ← live: 每 tick 都可能变
│  ───────────────────     │
│  > 用户输入 _            │  ← cursorPlacement 锚点
└──────────────────────────┘

收益三重:

  1. committed 跳过 diff:只做 count 比较,确认纯追加即可
  2. live 做 diff:只对少量行做 firstDifferenceIndex
  3. Live Budget Planner 只在 live 区生效:历史消息不受预算限制

快速路径在 committed 纯追加 + live 未变时触发:

if isPureAppend, liveDiff == nil {
    output += "\u{1B}[\(appendedCount)L"  // IL: 在当前行插入空行
    output += appendedLines.joined(separator: ttyNewline)
    output += live.joined(separator: ttyNewline)
}

ESC[nL(IL, Insert Lines)在当前行插入 n 行,当前行及以下顺移,不需要擦除和重写 live 区。硬约束是所有追加行必须是单物理行,而代码块和表格几乎总是跨多个物理行,天然不满足这个约束,实际上走不到快速路径。

9.2 Live Budget Planner

Agent 流式输出无限增长,终端只有 24-50 行。LiveBudgetPlanner 做一件事:当 live 区超出预算,把旧的 live 行“沉降“到 committed 区。

渲染前:
  committed: [历史消息1, 历史消息2]
  live:      [流式行1, ..., 流式行50]  ← 超出预算

沉降后:
  committed: [历史消息1, 历史消息2, 流式行1, ..., 流式行10]
  live:      [流式行11, ..., 流式行50]

核心约束:不做部分行切割。一行要么在 live,要么全部沉降,因为部分切割意味着处理被切开的 Markdown 语法(表格边界、代码块边界),复杂度不可承受。

两种预算模式:.logicalLines(按逻辑行数限制)和 .physicalRows(按 wrap 后物理行限制,适合 Markdown)。算法是 O(n) 单次前缀累加:

let rowsPerLine = live.map { rows(for: $0) }
var remaining = rowsPerLine.reduce(0, +)
var settleCount = 0
while settleCount < maxSettle, remaining > budget {
    remaining -= rowsPerLine[settleCount]
    settleCount += 1
}

十、所有权模型:已完成的内容归谁管

本节为 2026.09 补记。本篇写完后我读了 Codex、Grok Build 的源码和 Claude Code 的发布产物,发现这里漏掉了一条重要的分界线,完整论述见第 13 篇,这里只补坐标系。

本篇从头到尾解剖的是一种特定范式:全屏自管,即屏幕上每一行都归引擎管,committed 区虽然“只追加、不改写“,但只要还显示在屏幕上,就持续参与每帧的 diff 和 resize 重算,引擎就得一直管着它。

另一种范式是 inline viewport:内容一旦在语义上定型(工具调用完成、回复结束),就立刻打印进终端的原生 scrollback,从此归终端管,引擎脱手;引擎只维护底部一小块活区。但要说明一点:**2026 年中的头部实现没有一家单边押注。**Claude Code 和 Kimi Code 默认 inline(前者是内置 Ink fork,Messages.tsx 的 shouldRenderStatically() 决定一条消息何时“静态化“),Codex 和 Grok Build 默认反而是全屏(都内置 inline 降级路径,前者是 insert_history.rs,测试直接叫 vt100_live_commit),四家都把这条分界线做成了产品内部的开关。细节见第 13 篇。

两派的 live 区渲染是同构的:增量 diff、双缓冲、擦除重写,大家都做。

分歧只在所有权:一个 block 完成之后,谁继续管它。全屏自管派换来任意可见历史的可改写性,代价是帧状态的持续脆弱;inline 派换来状态表面积的急剧缩小,代价是历史不可触碰(改写需求路由到模态查看器或导出)、resize 需要核平重印。完整的机制解剖和代价对照见第 13 篇。


十一、为什么框架教不会你这些

回到开头的问题。用 Bubble Tea 或 Ink 写一个 TUI,你不需要知道 ANSI 状态机怎么处理分片到达、不需要手动计算物理行、不需要自己维护 8 个帧状态字段。框架帮你做了这些,但框架的选择也定义了你的上限。

ForgeLoopTUI 走的路是渲染引擎级别的控制。它没有引入第三方 Markdown 库(手写逐字符 inline formatting 扫描),没有引入 Myers diff(终端窗口 <100 行不值得),没有依赖任何 UI 框架的组合模型。代价是代码量上去了,回报是:你可以精确控制每一帧的每一个 ANSI 字节。

  • 代价是项目复杂度直线上升:别的框架替你处理掉的问题,我每个都得和 AI 一起研究、自己解决,非常耗精力;好处是从中学到了不少东西。

哪条路更好,取决于你在什么约束下交付。但如果要做的是 Agent TUI(流式输出、工具调用乱序返回、中途取消、thinking 展开和折叠),框架的通用抽象迟早会撞墙。第 4 篇会展示这些墙具体长什么样。


十二、总结

TUI 的技术全景:在终端这片上世纪 70 年代末的地基上,用几十个 ANSI 转义序列构建增量 diff 渲染引擎。

困境:协议层没有声明式 API,也没有 undo。声明式要靠 Ink 这类库在应用侧补,undo 要靠引擎自己存上一帧;物理行与逻辑行的错位让 diff 的每一步都依赖 O(n) 的显式宽度计算,帧状态记忆脆弱到一次 resize 就能全盘失效。

优势:资源占用极低、跨平台零成本、管道可测试、tmux 断线恢复。GUI 并非做不到这些,只是要做到同等体验,工程成本和基础设施门槛高一个数量级。第一篇讲过信任模型,这一篇补充了另一面:CLI/TUI 给开发者 agent 提供了一个可以精确控制每一帧的渲染基座。

下一篇讲 Markdown 在 TUI 上的流式渲染:降级映射、Stable Prefix Cache、表格 retreat 机制,以及为什么“流式期间要不要渲染 Markdown“是一个真正的工程难题。


参考与延伸

  • 本文所有技术细节基于 ForgeLoopTUI v1.2.0 的实际源码。
  • Agent TUI 的另一条实现路径可参考 tiankonguse 的 Bubble Tea + Lipgloss 方案。两条路线的差别值得说透:组合框架(Bubble Tea + Lipgloss)给你 widget 树和声明式布局,渲染细节由框架代劳;手写 ANSI 状态机则要自己做物理行计算、增量 diff、合帧调度——也就是本篇从头到尾展示的这套东西。前者上手快,但上限由框架定义;后者代码量上去了,换来对每一帧每一个 ANSI 字节的精确控制。两条路线的深度差一个数量级。

Markdown 在 TUI 上的流式地狱

上一篇拆解了 TUI 渲染引擎的底层,这一篇聚焦 Agent 场景最让人头疼的问题之一:在只有字符的终端里,把流式输出的 Markdown 渲染成可读的样子。


一、Markdown 天生反感流式

Markdown 是 John Gruber 在 2004 年设计的,设计目标很明确:一种“写起来像纯文本、看起来像格式化文档“的轻量标记语言。它的解析模型是“写完 → 一次性解析 → 渲染“。

这里有一个结构性的矛盾:

Markdown 的设计前提:          Agent 的实际输出:
─────                         ─────
完整文档                      token-by-token 流式到达
闭合的块级结构                随时可能出现半个代码块
确定的语法树                  下一个 token 可能反转已解析的结构

举一个简单的例子。Agent 输出到一半时:

我们今天讨论三个要点:
1. TUI 的字符网格
2. Markdown

此时解析器会把这两行识别为有序列表的头部。但下一个 token 可能是:

不是唯一的选择

这行没有数字前缀,按 CommonMark 的 lazy continuation 规则,它会续接到最后一个打开的块上,也就是第二项的多行续文,不是新列表项也不是普通段落。但解析器在流式到达的那一刻根本不知道。更彻底的反转是 setext 标题:一段已经按正文渲染的文字,下一行来了 ---,整段就变成了二级标题。

代码块更麻烦:

```swift        ← 代码块开始
let x = 1
```             ← 闭合了。但模型下一秒又吐出一行代码……
let y = 2        ← 它是新段落,还是代码?

严格说这不算 Markdown 的词法歧义,CommonMark 的规则是确定的。歧义来自流式本身:解析器每一帧都要对“目前已到达的内容“给出确定结论,而这个结论随时可能被后续 token 推翻。更典型的例子是更长的开 fence:四个反引号打开的块里,三连反引号是合法内容,一行 ``` 到底是内容还是闭合,要看到更多上下文才能判定,而这些上下文还没生成出来。


二、降级映射:把视觉语义翻译成字符

第 2 篇讲过,TUI 只有字符。Heading 用不了 24pt 字号,ForgeLoopTUI 的选择是符号前缀。这就是“降级映射“:把 Markdown 的视觉语义翻译成终端字符网格能表达的形式。

2.1 Heading

switch markerCount {
case 1: prefix = "█ "    // <h1>
case 2: prefix = "▓ "    // <h2>
case 3: prefix = "▶ "    // <h3>
case 4: prefix = "▹ "    // <h4>
case 5: prefix = "• "    // <h5>
default: prefix = "· "   // <h6>
}

六种前缀符号对应六级标题。“█“比”·“视觉重量大,读者自然把它解读为更高级别的标题。另一条路线是颜色和样式:glow 把所有标题统一加粗染蓝,层级仍靠 # 前缀数量区分(仅 H1 额外去掉 # 并加整行背景高亮);Claude Code 更省,标题仅加粗(H1 加下划线),无颜色、无层级区分。ForgeLoopTUI 走的是纯符号路线。

2.2 代码块

┌─ code swift
│ func main() {
│     print("hello")
│ }
└─ end code

Box-drawing 字符画出边框。语言标签放在起始行。算不上漂亮,但边界在任何终端里都清晰可见。另一条路线是背景色(glow 给代码块整体加背景色,delta 在 diff 场景用整行背景色),视觉区分度更好,代价是依赖终端的背景色渲染;box-drawing 不依赖任何颜色能力。

2.3 有序/无序列表

• 第一项
◦ 嵌套项
▪ 更深嵌套
▫ 再深一层

四个不同符号按嵌套层级循环。任务列表用 ☐ 和 ☑。

2.4 Blockquote

用 │ 前缀加左侧竖线。嵌套引用叠加前缀:│ │ 二级嵌套。

2.5 内联格式

MarkdownTUI 渲染ANSI 序列
`code`反色显示ESC[7m
**bold**粗体ESC[1m
*italic*斜体ESC[3m
~~strike~~删除线ESC[9m
[text](url)下划线文本 + 灰色 URLESC[4m / ESC[2m

斜体 ESC[3m 的兼容性不可靠,有的终端渲染成反色,有的直接忽略。链接那一行是 v1.2.0 的写法,后来的版本换成了 OSC 8 可点击超链接,也加了语法高亮(见第 17 篇)。

applyInlineFormatting 不依赖任何 Markdown 解析库。它是手写的逐字符扫描,自己找 **、*、`、~~、[text](url) 的边界,不引入 cmark 或任何第三方依赖。原因很简单:终端里不需要 HTML 语义树,只需要知道“这两个星号之间加粗体 ANSI 序列“。

2.6 表格:最复杂的子系统

表格是整个 Markdown 引擎里代码量最大的部分,连实现带配置接近 400 行。终端里的表格有三种失败模式:

模式一:列太宽,终端放不下。 解决策略由 TableOverflowBehavior 控制:

compactThenTruncateThenDegrade(默认):
  1. 先挤压每列宽度(不低于 minColumnWidth = 6)
  2. 还不够 → 截断单元格内容(加截断符 "…")
  3. 仍然不够 → 退化:放弃 box-drawing,回退到原始 Markdown 文本

退化是最后手段:box-drawing 表格变回原始 | col1 | col2 | 格式,可读性下降,但至少不溢出。

模式二:列被截得太狠,内容看不清。 autoReadable 策略在截断比例超过阈值时自动退化:

if truncatedCellRatio > 0.4  // 超过 40% 的单元格被截断
   || trimmedWidthRatio > 0.3  // 或总宽度被砍掉 30% 以上
{ return nil }  // 退化

每列被压到只剩 6 字符宽的表格比原始 Markdown 更难读,不如直接退化。

模式三:表格还在流式输入中。 这是最棘手的。Agent 输出到一半:

| Name | Value |
|------|-------|
| CPU  | 85%   |
| Mem  | ← 这里还在写

TableStreamingBehavior 控制行为:.monotonic 立即渲染所有已完成的行,.strict 等到表格块完全结束才渲染。但默认的 .monotonic 还藏了一个防御逻辑:retreatToAvoidSplittingTrailingStreamingTable,第三节要讲的核心机制。

2.7 先决条件:宽度得算对

以上三种失败模式都建立在一个前提上:宽度算得对。而终端里的宽度不等于字符数:CJK 字符占两列,多数 emoji 占两列,ANSI 序列占零列。

ForgeLoopTUI 的 DisplayWidth.visibleWidth 先剥掉 CSI 序列,再按 Unicode 区间判定宽字符计 2、其余计 1,表格的列宽求解和截断全部走这个函数。

它的局限也值得知道:判定按单个 Unicode scalar 做,不处理组合序列,ZWJ 序列(如 👨‍💻)和 VS16 变体选择符都会被算错宽度,表格边框随之错位。这是所有按 scalar 判定宽度的实现的共同盲区,不独 ForgeLoopTUI;中文 Agent 场景里 CJK 问题是家常便饭,宽度问题比纯英文场景暴露得更频繁。


三、Stable Prefix Cache:在流式里偷懒

第 2 篇讲了 TUI 的增量 diff 机制:记住上一帧,只重绘变化部分。Markdown 渲染引擎也用了类似的思路,只不过缓存对象从行 diff 换成了“稳定前缀“。

3.1 为什么只能在换行符处切分

public func render(text: String, isFinal: Bool) -> [String] {
    // 1. 如果新文本不以缓存的 stableSource 开头 → 缓存失效
    if !stableSource.isEmpty, !text.hasPrefix(stableSource) { reset() }

    // 2. 切掉已缓存的前缀,只处理新增部分
    let suffix = String(text.dropFirst(stableSource.count))
    let advance = stableAdvance(in: suffix, isFinal: isFinal)
    if advance > 0 {
        let stableDelta = String(suffix.prefix(advance))
        stableSource += stableDelta
        stableRendered += renderFully(text: stableDelta, isFinal: true)
    }

    // 3. 不稳定后缀(最后一行)每次重新渲染
    let unstable = String(text.dropFirst(stableSource.count))
    let unstableRendered = renderFully(text: unstable, isFinal: isFinal)
    return stableRendered + unstableRendered
}

stableAdvance 只在换行符处将文本标记为“稳定“。因为 Markdown 的块级结构(段落、标题、列表项、代码块边界)都以换行符分隔。一行没写完之前,你无法确定它是什么块级元素。

稳定区(已渲染,缓存)         不稳定区(每次重渲)
─────                         ─────
## 标题\n                      代码块开始\n
列表项1\n                      代码内容\n
列表项2\n                      正在输出的这行...

(右栏按 v1.2.1 的行为画:未闭合的代码块整段留在不稳定区。v1.2.0 只会把最后一行留在这里,见 §3.3。)

3.2 流式表格的稳定性陷阱

stableAdvance 有一个关键的防御机制。如果文本以换行符结尾,它会把到那个换行符为止的部分标记为稳定。可万一这个换行符恰好在一张未完成的流式表格中间呢?

| Name | Value |
|------|-------|
| CPU  | 85%   |          ← 这行以换行结尾,会被标记为稳定
| Mem  | 正在输出...        ← 没有换行,不稳定

如果第三行被标记为稳定(因为它以换行符结尾),渲染后的 box-drawing 表格会包含底部边框 └─┴─┘。下一帧第四行到了,需要加一行,可第三行已经“稳定“了,底部边框被锁死在缓存里。

retreatToAvoidSplittingTrailingStreamingTable 就是这个防御(节选自源码,部分局部变量定义省略):

private func retreatToAvoidSplittingTrailingStreamingTable(
    lines: [String], remainder: String
) -> Int? {
    // 如果剩余部分以 "|" 开头 → 可能是不完整表格的续行
    guard trimmedRemainder.hasPrefix("|") else { return nil }

    // 从尾部向上扫描,找到完整的表格头+分隔行
    // 然后退回到表格开始之前
    for start in stride(from: end - 2, through: 0, by: -1) {
        guard let headerCells = parseTableCells(lines[start]),
              let divider = parseDividerCells(lines[start + 1]),
              divider.count == headerCells.count else { continue }

        // 验证所有数据行列数匹配
        var allRowsMatch = true
        for rowIndex in (start + 2)...end {
            guard let rowCells = parseTableCells(lines[rowIndex]),
                  rowCells.count == headerCells.count else {
                allRowsMatch = false; break
            }
        }
        if allRowsMatch {
            // 找到完整表格 → 回退到表格头之前,整个表格保持不稳定
            return retreat
        }
    }
    return nil
}

逻辑:如果最后一个换行符之后、还没写完的那一行以 | 开头,检测候选文本的末尾是否构成一张完整的表格(表头 + 分隔行 + 至少一行数据)。如果是,整个表格都不标记为稳定,等表格块彻底结束后再一次性缓存。

3.3 盲区:代码块没有同等的防御

表格有 retreat 机制,代码块没有。一个未闭合的代码块可能被切进稳定区,而 renderFully 每次调用都从 inCodeFence = false 重新开始,fence 状态不会被记录。后果是连锁的:

第一帧: "```swift\nlet x = 1\n"
  → 全部进入稳定区,渲染为:
    ┌─ code swift
    │ let x = 1

第二帧: "let y = 2\n"
  → 作为新的稳定增量单独渲染,inCodeFence 状态已丢失
  → 被当成普通段落渲染,没有 │ 前缀

第三帧: "```\n"(真正的闭合 fence)
  → 单独渲染时被误判为开 fence
  → 渲染成一个新的 "┌─ code"

这是 v1.2.0 及之前版本的一个真实盲区。修复思路和表格一致:retreat 时检测候选末尾是否处于未闭合的代码块内,是则回退到 fence 开始之前。该修复(retreatToAvoidSplittingUnclosedCodeFence)已在 v1.2.1 合入:fence retreat 先于表格 retreat 执行(未闭合 fence 之内的表格状行不是真表格),fence 判定复用 isCodeFenceDelimiter,与 renderFully 的状态切换语义保持一致。在 v1.2.0 上,规避方案见第四节的路线二。

3.4 65K 字符上限

private let maxStableSourceChars = 65_536

if stableSource.count > maxStableSourceChars { reset() }

稳定缓存不能无限增长。一次长对话的流式输出可能超过几万个字符。65K 是折中值:超出后 reset,下一帧把全部内容重新渲染一次,重新开始缓存。代价是输出本身一旦长过 65K,缓存刚重建完又会超限,之后每帧都退回全量重渲。


四、流式期间到底要不要渲染 Markdown

第 2 篇和第 9 篇(GUI 部分)都会涉及这个问题,值得把代价算清楚。

Agent 流式输出时,每秒几十个 token 到达。即使有 Stable Prefix Cache,每次渲染仍然需要:

  1. 跑 stableAdvance:扫描候选文本,检测是否是流式表格(可能 O(n) 回退扫描)
  2. 渲染不稳定后缀:哪怕只有一行,也要跑完整管线,代码块检测 → 表格检测 → structured line 检测 → inline formatting

面对这笔成本,工程上有两条路线:

路线一:全程渲染 Markdown,用缓存摊薄成本。 ForgeLoopTUI 选的是这条:TranscriptRenderer 持有一个 StreamingMarkdownEngine,流式和结束走同一个引擎,靠 Stable Prefix Cache 保证每帧只处理增量。代价是第三节的防御逻辑(以及 v1.2.1 之前存在的代码块盲区)。

路线二:流式期间纯文本,结束后一次性切换。 Markdown 在流式期间只是“好看“,谈不上“必要“:代码、列表以纯文本展示,可读性损失很小。等流式结束,所有块级结构闭合,解析器不用做任何防御性猜测,一次完整渲染搞定,还顺带绕开了代码块盲区。

ForgeLoopTUI 为路线二保留了 PlainTextMarkdownEngine:

public func render(text: String, isFinal: Bool) -> [String] {
    guard !text.isEmpty else { return [] }
    return text.split(separator: "\n", omittingEmptySubsequences: false).map(String.init)
}

它就是 split("\n"):零解析开销,零防御逻辑,零缓存状态。接入方完全可以在流式期间注入它,isFinal 时再切回 StreamingMarkdownEngine。

两条路线没有对错,是纯工程权衡。中间态也存在:做一个“轻量 Markdown 引擎“,只做 inline formatting 和代码块检测,跳过表格和 blockquote,在流式期间保留最基本的可读性。


五、代码块检测的边界

ForgeLoopTUI 的代码块检测不依赖完整 Markdown 解析,做法很直接:先去掉行首尾空白,再检查行首是否有三个或以上的 ` 或 ~:

private func isCodeFenceDelimiter(_ line: String) -> Bool {
    let trimmed = line.trimmingCharacters(in: .whitespaces)
    guard let first = trimmed.first, first == "`" || first == "~" else { return false }
    let run = trimmed.prefix(while: { $0 == first })
    return run.count >= 3
}

这和 CommonMark 规范有两个微妙区别。其一,CommonMark 要求闭合 fence 的长度不小于开 fence:三个反引号打开,就得三个或更多才能关闭;四个反引号打开的块里,三连反引号只是内容。ForgeLoopTUI 不检查长度匹配,只要看到三连反引号就切换 in-code-fence 状态。其二,先 trim 等于丢掉了 CommonMark“fence 最多允许 3 格缩进“的规则,缩进 4 格以上的行若以三连反引号开头,会被误判为 fence。

这是一个有意的简化。在 Agent 流式场景下,代码块的内容来自 LLM 输出,不太会出现“四个反引号打开、三个反引号在内容里“的边界情况。而且实现正确的分隔符匹配需要回溯(代码块可能在几十行之前打开),与 Stable Prefix Cache 的假设冲突。本篇末尾的补记里,Codex 跨帧保持 fence 状态,绕开了这个回溯。


六、总结

TUI 上 Markdown 流式渲染的核心矛盾可以总结为三句话:

  1. Markdown 是“写完再解析“的语言,Agent 是“边想边输出“的过程。 两者的设计哲学根本冲突。
  2. 终端只有字符,Markdown 的视觉语义必须降级映射。 但降级不等于功能缺失,true color 语法高亮和 OSC 8 可点击超链接在终端里都可行,成本是手写 tokenizer,没法靠调库解决。
  3. 流式渲染 Markdown 的成本可以靠 Stable Prefix Cache 摊薄,但防御逻辑和盲区是必要之恶。 纯文本 fallback(流式期间跳过 Markdown、结束再切换)是更省的选择。

下一篇讲 Agent TUI 最核心的难题:加上流式输出、工具调用、thinking 展开之后,这些问题如何从“难“变成“几近失控“。第 1 篇提过一个判断:Agent 的真实输出不是 1D 的,下一篇把这句话完整展开。


补记(2026.10):本篇定稿两个月后,我逐行读了 Codex 的流式渲染模块(codex-rs/tui/src/streaming/)。两个发现值得记在这里:§3.2 的表格陷阱,Codex 用另一种机制独立解了一遍;§3.3 的代码块盲区,Codex 里有一个现成的完整答案。

Codex 的对应物叫 table holdback,是一个三态状态机:没有表格迹象时放行一切;末行看着像表头、分隔行还没到,就进入“待确认“,乐观地把这一行拦在稳定区之外;表头与分隔行一旦配对确认,从表头起的内容全部保持可变,直到表格结束。它解的问题和 retreat 是同一个(给表格加一行会改变所有列宽、重塑之前所有行,所以表格在闭合前不能定型),但机制相反。ForgeLoopTUI 是事后回退:先按换行符乐观切分,发现劈开风险再回头扫描,最坏 O(n),平时零常驻状态。Codex 是事前状态机:扫描器随每个 delta 增量推进,只记住上一行的事实,常数成本,提前拦住。第六节说防御逻辑是必要之恶,这两家只是选择了不同的付代价时点:一个出了问题再回头补算,一个把成本均摊到每一步。

还有两个细节。其一,Codex 的源累积器只在换行符处交付:没写完的半行根本不进入渲染管线,注释里写明了动机——防止用户先瞥见结构未定的畸形块、下一帧又看它消失。§3.2 里那类闪烁,在这个设计里从源头不存在。其二,§3.3 盲区的他山答案:Codex 全程维护 fence 状态,开着的代码块走一条快路径——直接追加渲染行、不重新解析,fence 状态跨帧连续,盲区在结构上不存在。

时间线:ForgeLoopTUI v1.2.1 的 fence retreat 修复在前,我读 Codex 在后。两家独立收敛到了同一个判断:fence 状态必须跨帧保持,区别只在用回退还是用状态机来实现。另外,Codex 给这套机制配的测试不是逐帧断言,而是断言一个不变量:任意 delta 切分下,“已上屏 + 待放行“恒等于一次性全量渲染。这个思路本身值得展开,见第 16 篇。


参考与延伸

  • 本文所有技术细节基于 ForgeLoopTUI v1.2.0 的实际源码。§3.3 的代码块盲区已在 v1.2.1 修复(retreatToAvoidSplittingUnclosedCodeFence),正文保留该盲区的完整分析作为案例。
  • 补记部分基于 Codex 本地源码 2026-10-04 的阅读:codex-rs/tui/src/streaming/table_holdback.rs(holdback 状态机)、markdown_stream.rs(换行门控)、streaming/render.rs 与 streaming/code_fence.rs(fence 快路径),快照 main 6b9826e3(2026-09-09)。

Agent TUI——当事件树撞上线性终端

TUI 三部曲的最后一篇。流式输出、工具调用、thinking 展开、用户输入四件事同时在终端里发生,渲染系统面对的问题从“画得好看”变成了“能不能不崩”。


一、回到那个直觉:“1D → 1D”

第 1 篇第三节拆过一个直觉:LLM 输出是 1D 的 token 流,CLI 也是 1D 的,所以天然匹配。那一节的回答是,Agent 的真实输出是一棵乱序到达的事件树,工具调用 2 可能比工具调用 1 先返回,thinking 块可能在流式输出中途插入,用户随时可能按取消键。CLI 看起来“适配“,靠的是 TUI 渲染引擎在背后做了一套复杂的展平机制:把一棵乱序到达的树强行投影成线性输出。 第 1 篇只给了结论,这一篇拆机制本身。


二、CoreRenderEvent:去掉会话角色语义的事件系统

ForgeLoopTUI 设计了一套不绑定业务模型的事件词汇:

public enum CoreRenderEvent {
    case insert(lines: [String])                              // 静态文本
    case blockStart(id: String)                               // 开始流式块
    case blockUpdate(id: String, lines: [String])             // 更新流式块
    case blockEnd(id: String, lines: [String], footer: String?) // 结束流式块
    case blockCancel(id: String)                              // 用户取消
    case thinking(content: String, isFinal: Bool)             // 推理过程
    case operationStart(id: String, header: String, status: String)  // 工具开始
    case operationEnd(id: String, isError: Bool, result: String?)    // 工具结束
    case notification(text: String)                           // 通知
}

关键设计决策:不区分 user/assistant/tool 的会话角色语义,但保留执行结构语义。 thinking、operationStart/End 这些事件类型本身就是 Agent 的执行语义,它们不回答“这句话是谁说的“,只标记“执行进行到哪一步“。chat 语义由上层 Adapter 注入,Core 层只知道“有一段内容要插入““有一个块在流式更新”“有一个操作开始了”。这让渲染系统可以复用到任何场景:AI 聊天、构建日志、测试报告,都不用改渲染逻辑。

代价是渲染器不知道事件之间的业务关系。它不知道 operationEnd("tool_1") 对应哪个 operationStart,不知道 thinking 结束后会不会有流式输出。这些关系由 TranscriptRenderer 内部维护,通过一套索引追踪系统。


三、工具调用的乱序渲染

这是 Agent TUI 中最棘手的渲染问题。

3.1 问题

Agent 发起两个工具调用:

时间线:
  t1: operationStart(id: "A", header: "● read_file(main.rs)")
  t2: operationStart(id: "B", header: "● search_code(regex)")
  t3: operationEnd(id: "B", result: "3 matches")   ← B 先返回
  t4: operationEnd(id: "A", result: "fn main() { ... }")  ← A 后返回

如果按到达顺序渲染,输出是:

● read_file(main.rs)
⎿ running...
● search_code(regex)
⎿ running...
⎿ done: 3 matches    ← 应该替换 B 的 running 行,却被追加到了帧尾
⎿ done: fn main()... ← A 的结果同样追加在最后

B 的 done 行本应替换掉 B 自己的 ⎿ running...,但按到达顺序渲染只会把结果追加到帧尾:B 的 running 行残留成僵尸状态,结果行却落到了离自己 header 两行开外的位置。

3.2 稳定槽位队列

ForgeLoopTUI 的解法是 pendingTools 数组:按 operationStart 到达顺序维护槽位。

case .operationStart(let id, let header, let status):
    append(header)       // ● read_file(main.rs)
    append(status)       // ⎿ running...
    pendingTools.append((id: id, lineIndex: lines.count - 1))
    // lineIndex 指向 status 行的位置

operationStart 时记录了每个工具的状态行在 Transcript 中的绝对行号。当 operationEnd 到来时:

case .operationEnd(let id, let isError, let result):
    guard let slotIndex = pendingTools.firstIndex(where: { $0.id == id }) else { break }
    let lineIndex = pendingTools[slotIndex].lineIndex
    pendingTools.remove(at: slotIndex)
    let resultLines = formatToolResult(result)
    // 用结果行替换原来的 "⎿ running..." 行
    lines.replace(range: lineIndex..<(lineIndex + 1), with: resultLines)

关键:不关心事件到达顺序,只关心槽位。 每个工具在第一次 operationStart 时就分配了一个固定位置(lineIndex)。后续的 operationEnd 直接定位到那个位置替换状态行,不管中间插入了多少其他工具。(顺带说明:lines 不是裸数组,是带边界钳制封装的 TranscriptBuffer,replace(range:with:) 内部钳制后走标准 replaceSubrange。)

但有一个连锁问题:如果 B 先结束,B 的结果文本比 ⎿ running... 长(3 行 vs 1 行),在 B 的位置插入 3 行会把后续所有行的索引推偏 2 行。这时需要 shiftIndices 把所有受影响的引用全部偏移:

private func shiftIndices(after threshold: Int, by delta: Int) {
    for index in pendingTools.indices {
        if pendingTools[index].lineIndex > threshold {
            pendingTools[index].lineIndex += delta
        }
    }
    // 同理偏移 notificationLines、streamingRange、completedRange、thinkingRange
}

不做这个偏移,下一个 operationEnd 的 lineIndex 就指向了错误的行,结果写到别人的位置。

补记(2026.08):本节描述的是全屏自管派的乱序处理:在扁平行数组上做坐标手术。inline viewport 派把乱序配对提前到了数据层:工具调用按稳定 id 在内存模型里配对、完成后才“发射“进终端 scrollback,乱序问题从坐标手术退化为字典查找。

这里要和第 2 篇的一个结论对齐:commit/live 分区模型里,committed 区“只追加,不改写“。那上面这些 lines.replace 原地替换(以及后面 thinking 的原地更新、通知的删除)不矛盾吗?

不矛盾,关键在时序:这些操作针对的行都还处于 live 阶段,尚未被 Live Budget Planner 沉降到 committed 区。一行内容在 commit 之前是可变的,可以被替换、删除、连带偏移;一旦沉降完成,它进入只追加区域,后续任何事件都不会再改写它。“不可变“是 commit 之后的性质,不是写入即生效的性质。


四、thinking 块的渲染

thinking(推理过程)和普通流式输出的区别在于:它是模型在“想“,不是对用户的回复。视觉上需要区分。

case .thinking(let content, let isFinal):
    let thinkingLines = content.isEmpty
        ? []
        : content.split(separator: "\n").map { "💭 \($0)" }

每行加 💭 前缀。thinking 块维护自己的 thinkingRange,每次更新是原地替换:

if let range = thinkingRange {
    let delta = thinkingLines.count - range.count
    lines.replace(range: range, with: thinkingLines)
    if delta != 0 {
        shiftIndices(after: range.upperBound - 1, by: delta)
    }
    thinkingRange = range.lowerBound..<(range.lowerBound + thinkingLines.count)
} else {
    let start = lines.count
    lines.append(contentsOf: thinkingLines)
    thinkingRange = start..<(start + thinkingLines.count)
}

首次 thinking 事件创建新范围;后续事件在同一个范围原地替换,因为 thinking 内容是累积更新的,每次收到的都是完整文本。注意替换会改变行数:新旧行数差 delta 不为零时,必须像「三」「五」那样偏移后续索引,否则排在 thinking 之后的工具槽位和流式范围会全部错位。

isFinal 为 true 时清除 thinkingRange,后续的流式回复或工具调用正常追加在后面。


五、通知的 FIFO 队列(有上限)

Agent 在运行过程中会产生系统通知:“工具调用超时”“网络重试第 3 次”“上下文窗口使用率 85%”。这些通知需要展示但不能淹没主要对话内容。

case .notification(let text):
    appendNotification("▸ \(text)")

appendNotification 维护一个有上限的 FIFO 索引队列:

private var notificationLines: [Int] = []  // 存行号,不存内容

private func appendNotification(_ line: String) {
    lines.append(line)
    notificationLines.append(lines.count - 1)

    while notificationLines.count > options.maxNotificationLines {  // 默认 3
        let oldIndex = notificationLines.removeFirst()
        lines.replace(range: oldIndex..<(oldIndex + 1), with: [])
        shiftIndices(after: oldIndex - 1, by: -1)
    }
}

超过上限(默认 3 条)时,最旧的通知行从 Transcript 中删除,后续所有索引偏移 -1。这里没有折叠机制,直接删除:通知是瞬态的,过时即无用。


六、blockCancel:用户按下取消键

Agent 正在流式输出一段很长的代码,用户按了 Esc 取消。这时不能只停止发送新内容,已经显示在屏幕上的流式内容也要清除,换成 [cancelled] 标记。

case .blockCancel:
    replaceStreaming(with: ["[cancelled]"])
    streamingRange = nil
    completedRange = nil
    markdownEngine.reset()
    append("")

replaceStreaming 是统一的“替换当前流式区域“方法:

private func replaceStreaming(with newLines: [String]) {
    let range = streamingRange ?? (lines.count..<lines.count)
    lines.replace(range: range, with: newLines)
    streamingRange = range.lowerBound..<(range.lowerBound + newLines.count)
}

如果 streamingRange 为 nil(没有活跃的流式块),退化为 append。取消后清空 streamingRange 和 completedRange,Markdown 引擎重置,Agent 可以立即开始下一个请求。


七、工具结果的截断

工具返回值可能很长:read_file 可能返回几百行代码,search_code 可能返回几十条匹配。在终端里全量展示会淹没对话流。

private func formatToolResult(_ text: String?) -> [String] {
    guard let text, !text.isEmpty else { return [] }

    let allLines = text.split(separator: "\n").map(String.init)
    var previewLines = Array(allLines.prefix(options.maxSummaryLines))  // 默认 3 行

    if allLines.count > options.maxSummaryLines {
        previewLines.append("...")
    }

    return previewLines.map { line in
        if line.count > options.maxSummaryChars {  // 默认 120 字符
            return String(line.prefix(options.maxSummaryChars)) + "..."
        }
        return line
    }
}

每行限制 120 字符 + 总共最多 3 行。在当前 commit/live 分区模型下,折叠不是一个简单的 show/hide 开关:一旦要让历史区域可折叠,就得重新定义已提交内容的可见性和重绘策略。当前选择了最直接的方案:截断,用 ... 标记。


八、多行输入框与帧合成

第 2 篇详细讲了 commit/live 分区模型和 cursorPlacement 机制。Agent 场景下有一个特殊问题:多行输入。

普通聊天 TUI 只需要单行输入框。Agent 场景中,用户经常需要粘贴多行代码、编辑长 prompt、在输入框里直接换行。

ForgeLoopTUI 的 MultiLineInputState 支持多行文本输入,光标锚定在输入框的当前编辑位置。这里有一个微妙的竞态:Agent 正在流式输出,用户同时在多行输入框里打字。两件事都在触发渲染。上游把不同来源的状态合成帧之后,第 2 篇讲的 RenderLoop 帧合并负责把这帧稳定刷出去,避免终端在“追加流式内容“和“更新输入框光标“之间出现 ANSI 序列交错。


九、Agent 的不确定性如何放大一切

前两篇讲的 TUI 问题(物理行计算、增量 diff 的脆弱性、Markdown 的流式不确定性)在普通聊天场景下已经是难题。Agent 场景让每个问题都严重了一个量级。

内容长度不可预测。 普通聊天的回复可能有几十到几百个 token。Agent 的工具调用结果可能是一整个文件的数千行代码。第 2 篇讲的 Live Budget Planner 在 Agent 场景下从“优化“变成了“必需的防御“:没有 budget 限制,一次工具返回就能把帧推到几百物理行,全量重绘 + 终端滚动缓冲区溢出。

事件类型不可预测。 你无法预知下一个事件是 thinking、tool call、streaming text、还是 error。渲染器必须正确响应所有事件组合,包括之前没见过的组合。比如某些模型的 thinking 块可以在流式回复的中间穿插出现,这不是规范行为,但实际发生了。

中断时机不可预测。 用户可能在流式输出的任何时刻取消。取消时 Markdown 引擎可能处于任何状态——代码块中间、表格中间、列表中间。blockCancel 必须无条件 reset 引擎、清空 streaming 状态、写取消标记,不能假定 Markdown 结构完整。

这三个“不可预测“叠加在一起,意味着 Agent TUI 的渲染系统不能对事件序列做任何结构性假设。每个事件到达时,只根据当前 Transcript 的索引状态做局部替换,不依赖“前一个事件是什么“,不假设“下一个事件什么时候到“。

这不等于“无状态“。渲染器的全部正确性都系于一份共享的可变状态:lines(Transcript 的内容数组)和几个 Range(streaming/thinking/completed 的位置追踪)。准确的说法是事件处理无会话假设。这也是为什么 applyCore 是一个巨大的 switch 语句:每个 case 独立处理一个事件类型,不依赖前序事件的种类,只依赖那份共享索引状态。


补记(2026.10):本篇的槽位队列是扁平行数组上的坐标手术;第三节末尾的补记提过,inline 派把乱序配对提前到数据层,坐标手术退化为字典查找。最近读 Codex 的 TUI 源码(codex-rs/tui/src/chatwidget/streaming.rs 一带),见到了这个论断的一种完整实现形态,补在这里作为证据。

Codex 的 transcript 不是行数组,是定稿 cell 序列 + 唯一一个 active 槽位。cell 是类型化的:AgentMessageCell 承载流式放行的行、StreamingAgentTailCell 是活动尾部、ExecCell 是工具调用、回答定稿后整段换成由原始源支撑的 AgentMarkdownCell(resize 时可从源重渲染)。流式期间尾部 cell 反复重建进 active 槽位,但内容没变就不触动编号——sync_active_stream_tail 先比较、相等就直接返回,避免无效重绘;commit tick 放行的行则固化为新 cell,追加进定稿序列。

对照本篇,三个观察。其一,乱序与偏移问题在结构上消失:cell 有类型和身份,定位是查表而非坐标运算,shiftIndices 那样的连带偏移没有存在必要。其二,“原地可改写“的范围被压缩到一个槽位:本篇里流式块、thinking、工具槽位、通知都在同一份 lines 上做手术,正确性系于全局索引的同步偏移;Codex 把所有可变性收进唯一一个 active cell,定稿区连索引都不必维护。其三,权威来源的取舍:流式 delta 可能因传输饱和丢失,Codex 在 item 完成事件到达时用完成文本与流式累积源核对,注释原话是“item completion is authoritative”,意思是传输丢了 delta,也不能让 transcript 截断。这个设计前提本篇没有对应物:ForgeLoopTUI 假定事件流本身可靠。


十、总结

三篇文章覆盖了从底层渲染到上层 Agent 场景的完整场景:

第2篇: ANSI 序列 + 字符网格 + 增量 diff  → 渲染引擎层
第3篇: 降级映射 + Stable Prefix Cache + 流式检测 → Markdown 层
第4篇: 事件乱序 + 工具渲染 + 状态管理    → Agent 层

这三层之间有一个递进关系:每一层都建立在下一层之上,每一层的问题都因为底层的限制而更难解决。Agent 的树状事件在终端里变成线性输出,这个“树展平“的过程,就是 TUI 渲染引擎存在的意义。

但展平只是手段。更值得问的是:树状事件为什么一定要展平成线性?如果终端不是唯一的投影介质呢?

不过在继续讲这个问题之前,还差一块。第 2 到第 4 篇讲的全是输出侧,怎么把内容画对、画快、画不崩;输入侧还一页没写,包括键盘事件怎么进来、弹窗怎么不打架、终端能力怎么探测。接下来两篇(第 5、6 篇)补上这一半,然后才是系列的中场:Event Sourcing,Agent UI 的底层模型。中场会解释,CLI/TUI 的纠结不是终端的锅,结构性矛盾在“树状事件 → 线性输出“这个投影方式本身。

一旦把 Agent 的执行抽象为事件流,CLI/TUI/GUI/IDE/Web/Mobile 各自应该站在哪里,就不再是形态之争了。


参考与延伸

  • 本文所有技术细节基于 ForgeLoopTUI v1.2.0 的实际源码。其中 thinking 替换的 shiftIndices 调用为 v1.2.1 的索引偏移修复,v1.2.0 及更早版本中不存在。
  • 补记部分基于 Codex 本地源码 2026-10 的阅读:codex-rs/tui/src/chatwidget/streaming.rs 一带,快照 main 6b9826e3(2026-09-09)。

输入框——agent TUI 最被低估的组件

第 2 到第 4 篇讲完了输出侧:怎么把内容画对、画快、画不崩。这两篇(05、06)翻过来讲输入侧,难点换成了另一件事:多层交互状态,要在同一条键盘事件流上不打架。


一、最大的单文件

先看一个经验事实:在 Codex 的 TUI 里,代码量最大的单文件是输入框,不是渲染控制器,也不是事件总线。bottom_pane/chat_composer.rs 一个文件 1.3 万行,功能实现约五千行,测试约八千行。

一个“打字的地方“为什么值五千行实现?因为键盘事件流只有一条,而想消费它的东西越来越多:普通文本、光标编辑、历史回溯、slash 命令候选、文件引用弹窗、skill 弹窗、@提及弹窗、粘贴、外部编辑器、组合键。这些消费者不是并存关系,而是互斥又嵌套:弹窗开着的时候,上下方向键归弹窗,不归文本;但 Enter 归谁,要看弹窗里有没有选中项。第 2 篇 §7 讲的光标定位和 IME 是这个组件的底层,第 4 篇 §8 讲的多行输入竞态是它的边界,本篇不再重复;本篇讲的是它的中层:那个决定“这个按键归谁“的仲裁结构。


二、弹窗优先级链

Codex 在这里的判断结构是一条显式的优先级链。按键到达 composer 后,处理函数按固定顺序逐级问询:文件弹窗在不在?在就归它,它选择吞掉还是放行;放行则问 skill 弹窗;再放行问 @提及弹窗;都没有,才走裸文本路径。每一级返回 (InputResult, bool),即结果加“是否已消费“。

这个设计的要点不在链本身(任何 GUI 的响应链都长这样),在于它把“哪个弹窗优先“从运行时状态变成了代码顺序:弹窗之间的优先级不靠注册表、不靠 z-index,靠 if-else 的书写顺序,这是最显式、最不容易被配置改坏的形式。考虑到这些弹窗涉及文件引用和 skill 调用这种直接影响上下文组装的功能,“优先级不可配置“是刻意的保守。

Kimi Code 走了另一条路,而且走得更远:它的 editor-component.ts 把整个编辑器定义成一个可替换接口(EditorComponent),注释明说动机——让扩展可以提供自己的编辑器实现,比如 vim 模式、emacs 模式、自定义键位。Codex 把优先级固化在代码顺序里,Kimi 把整个输入行为做成扩展点。一个防的是“被改坏“,一个赌的是“被扩展“。

笔者注:这一点上我更倾向 Kimi Code,Codex 有些过于保守了。


三、“这段输入是什么“在 composer 内部裁决

回车之后发生什么,答案不是一个字符串,是一个枚举。Codex 的 InputResult 把提交裁决为几类:Submitted{text, text_elements}(普通消息,附带已解析的元素区间)、Command(slash 命令)、CommandWithArgs 等。“这是消息还是命令“的判断在 composer 内部完成,上游拿到的已经是结构化的裁决结果。

slash 命令因此分两层:composer 层负责解析候选、驱动补全弹窗;执行分派在 ChatWidget 侧,slash_dispatch.rs 一个文件 1288 行。另有一个 ! 前缀的 shell 逃生口,提交时剥掉前缀直接进 shell。这个职责切分值得记住:composer 管“这是什么“,是交互状态机;分派层管“拿去怎么做“,是业务路由。


四、粘贴不是一种操作,是四种

“用户粘贴了一段东西“在实现层至少是四种不同的东西:

其一,bracketed paste 事件。 终端用 ESC[200~/ESC[201~ 包裹粘贴内容,TUI 收到一个完整的 Paste 事件,做 CRLF 归一化后进 composer。这是最干净的路径,前提是终端支持并开启了括号粘贴模式,下一篇会讲这个前提有多不牢靠。

其二,系统剪贴板直读。 图片粘贴走的是另一条路:直接读系统剪贴板,探测图片数据、编码、存临时文件、在文本里留占位。Codex 有专门的 clipboard_paste.rs 和一整组 PasteImageError 类型;Claude Code 的发布产物里也有独立的图片粘贴快捷键处理。

其三,大粘贴占位符。 粘贴几万字符的日志,不该把输入框撑爆。Claude Code 的做法:超过一万字符,显示时只留头 500 字符和尾 500 字符,中间折叠成一个占位引用(inputPaste.ts)。Codex 同构:大粘贴替换为占位符,提交时才还原展开(composer 头注释里的 “expands pending paste placeholders”)。两家独立收敛到同一个形态:显示层是占位符,数据层是全文,提交时展开。

**其四,paste-burst:没有括号粘贴时的湍流识别。**这是我最喜欢的一个,因为我自己做的时候深受其扰。

有些终端(特别是 Windows 上)不发 bracketed paste 标记,粘贴到达时就是一串极快的普通按键:人打字到不了那个速度,机器可以。于是识别粘贴变成了湍流识别:Codex 的 paste_burst.rs 和 Kimi 的 paste-burst.ts 是同一个启发式状态机的两次独立实现。字符间隔在毫秒级(Kimi 的参数:连续 ≥8 个字符、间隔 ≤8ms)就怀疑是粘贴;粘贴流里的 Enter 必须当换行而不是提交(Kimi 的 Enter 抑制窗口是 120ms)。两家的文件头注释写着同一个动机:防止粘贴里的回车把半截内容提交出去。

第四种的启示超出粘贴本身:当协议信号缺失时,行为信号(速度分布)可以顶替。 这在终端输入里是通用技法。


五、把键盘交出去:外部编辑器接力

composer 还有一个出栈方向:把整段输入交给 $EDITOR。Codex 的流程是:composer 内触发 → 发 LaunchExternalEditor 事件 → 读 $VISUAL/$EDITOR 起子进程。起进程之前先退出 raw mode,把终端归还给编辑器;编辑器退出后恢复 raw mode、读回文件、灌进 composer。期间事件总线可以暂停和恢复(EventBroker::pause_events/resume_events)。

这是一次跨进程的状态交接:终端模式、按键流、绘制权,全部先交出去再拿回来。任何一个环节没对齐(raw mode 没退干净、事件流没暂停、恢复时状态对不上),用户看到的就是花屏或按键丢失。输入框因此不只是“消费键盘“的组件,还是键盘这个资源的进出关口。


六、keymap 只做解析

最后一个职责切分:keymap 不管行为。Codex 的 keymap.rs 只做“配置 → 运行时键位“的解析(from_config),产出键位表;按键命中表之后做什么,是各组件自己的事。组合键(chord)有等待窗口:按下前缀键后等 KEY_CHORD_TIMEOUT,超时按单键处理,这个等待是用全局帧调度器的 schedule_frame_in 实现的,和状态行动画共用同一套定时基建。

Kimi 的对应物是声明式的:keybindings.ts 是一张全局键位注册表,下游包靠声明合并往里加键位;编辑动作枚举得极细,连 kill-ring(yank/yankPop,emacs 的剪切环)都有。读这些枚举,像在读一份“用户手指习惯“的清单。用户的肌肉记忆是存量,输入组件得接得住。


七、总结

诚实交代 ForgeLoopTUI 的位置。它是渲染引擎不是产品,输入侧停在引擎层:InputPipeline 做 bracketed paste 聚合(ESC[200~ 进、聚合成纯文本、ESC[201~ 出为一个 .paste 事件),KeyParser 把 CSI/CSI-u/SS3/Alt/控制字符归一成 KeyEvent,未知序列静默丢弃。没有弹窗层、没有 slash 命令、没有外部编辑器——这些在它的定位里属于接入方。

读完 Codex 的 composer,我更新了一个判断尺度,而不只是发现“ForgeLoopTUI 缺功能“:**composer 的状态机复杂度是 harness 成熟度的镜子。**一个 agent 产品要支持多少种“输入不只是文本“的情形(文件、skill、图片、命令、长粘贴、外部编辑器……),它的输入框就得在幕后配一套相应的状态机。

输出侧的复杂度藏在渲染管线里,真出了问题变慢卡顿,用户未必那么敏感,可能还以为是网络问题;输入侧的复杂度直接顶在用户手指下面,每一个弹窗优先级、每一毫秒的 Enter 抑制窗,用户都感觉得到,而且非常敏感。

如果你觉得这一篇已经够黑暗了,先别急着感叹,下一篇还要更往下走。这一篇的所有机制都假设键盘事件流是可靠的:按键是什么、粘贴有没有标记、模式开没开。真做过就会发现,这些假设在真实的终端世界里很脆弱,那才是输入侧最难的地方。


参考与延伸

  • 本文基于 2026-10-01 对以下源码的实际阅读:Codex 本地快照 main 6b9826e3(2026-09-09):codex-rs/tui/src/bottom_pane/chat_composer.rs(弹窗优先级链、InputResult)、bottom_pane/paste_burst.rs、clipboard_paste.rs、external_editor.rs、keymap.rs、chatwidget/slash_dispatch.rs。
  • kimi-code 本地源码 54117a6b(2026-09-24):packages/pi-tui/src/editor-component.ts、keybindings.ts、paste-burst.ts。
  • Claude Code 发布产物中的源码(2026-03-31 经 npm source map 外泄的公开快照):src/components/PromptInput/inputPaste.ts、src/hooks/useTextInput.ts。
  • 对照部分基于 ForgeLoopTUI v1.2.1 源码(Input/InputPipeline.swift、Input/KeyParser.swift)。

输入的地狱——终端能力探测与降级

系列第六篇,第 5 篇的下半部。第 2 篇 §4.3 讲过输出侧的能力降级链:颜色从 true color 一路退到 16 色,是“能力有没有“的问题。输入侧是另一半,行业讨论比输出侧少一个数量级,难度却更高:**输出降级是“能力有没有“,输入地狱是“行为一不一致“。**同一个按键,在不同终端模拟器里含义不同;同一条查询序列,有的终端回答、有的沉默、有的只回一半。上一篇讲的 composer 状态机,全部建立在这条事件流可靠的假设上。我从踩到这个坑、到调研、再到解决,花了几百块的 token,这一篇讲这个坑本身。


一、探测:启动时的第一次核对

终端能力没法靠 $TERM 问出来,环境变量会撒谎(SSH 默认只把 TERM 带过去,TERM_PROGRAM 这类变量到远端就没了;进了 tmux,TERM 又换成 tmux 自己的值)。所以严肃的 TUI 都在启动时做一次实况探测:向终端发查询序列,等回应,按回应决定启用哪些增强。

但“等回应“本身就是设计难题:等多久?等来的字节和用户的按键混在同一条 stdin 里,怎么分?三家的答案几乎是一个光谱。

Codex:有预算的轮询,加一条哨兵捷径。 terminal_probe 模块存在的原因是注释里的一句话:crossterm 的公共查询 API 最长会等两秒,“对启动和恢复来说太久,不支持的终端应该干脆退回保守默认”。所以 Codex 自己写探测:每组查询 250ms 预算(研究时为 100ms,Codex 于 2026-09 上调至 250ms,#46855),探光标位置、OSC 10/11 默认前景背景色、kitty 键盘增强支持;探测消耗掉的字节会回放进 crossterm 的解析器,保证探测期间用户的真实按键不丢。kitty 探测里还藏着一条捷径:查询后面跟着一个主设备属性(DA)请求,终端按序应答,DA 到了而键盘标志没到,就立即判定不支持,不必等满 250ms。整个过程带耗时埋点(“terminal startup probes completed”),探测在启动链路里是被当作正式开销来管理的一环。

Claude Code:用顺序代替超时。 同一条哨兵,Claude Code 押得更彻底:terminal-querier 不设超时。技巧叫 DA1 哨兵:每批查询末尾追加一个 DA1 查询(主设备属性),而 VT100 以来的每个终端都会回答 DA1,且终端按顺序应答。于是判定变成纯顺序问题:你的响应先于 DA1 到,说明支持;DA1 先到了,说明不支持。超时这个维度被从判定机制里删掉了,换成对一个老旧但普适的协议不变量的信任。探测目录里的清单也值得看:DECRQM 问同步输出(模式 2026)与 grapheme 聚簇(模式 2027)、OSC 11 问背景色、kitty 键盘查询、XTVERSION 问终端名——XTVERSION 的注释点破了为什么环境变量不可靠:查询走 pty(伪终端)不走环境,能穿透 SSH,而 TERM_PROGRAM 不能。(Claude Code 以打包形式发布、未公开源码;本段的模块名与注释引自其 terminal-querier.ts 源码镜像。)

Kimi:协商式握手。 kitty 键盘协议的完整三件套一次发出:推入目标标志位、查询当前标志、追加设备属性查询(ESC[>7u ESC[?u ESC[c),然后按 150ms 分片超时收集回应。另有一个容易漏的收尾细节:退出前先排空 stdin——否则 kitty 协议下按过的键会留下“释放事件“,终端在你退出后还在吐字节。

还有第四种哲学,是我自己设计出来的:ForgeLoopTUI 不探测。RawTTY.enter() 无条件推入 kitty 消歧标志和 bracketed paste 开关,注释写明理由——“不支持的终端会静默吸收这些序列”。这是拿终端生态的一个经验事实当赌注:未知序列无害。


二、一个键为什么不是一个键

探测的主要对象之一是键盘协议,因为传统终端键盘编码是歧义丛生的:Esc 键和 Alt 前缀共用 0x1b,Ctrl+I 和 Tab 是同一个字节,Ctrl+M 和回车是同一个字节。kitty 键盘协议(CSI-u)的存在意义就是消歧:给每个按键事件完整的键码与修饰符。

启用它是改善,也是新的维护负担。Codex 留了显式逃生门(CODEX_TUI_DISABLE_KEYBOARD_ENHANCEMENT 环境变量);Kimi 除协议外还备了一条原生侧通路——通过原生 helper 直接轮询真实修饰键状态(native-modifiers.ts),协议报不上来的时候问操作系统;Claude Code 则同时解析两套编码——CSI-u 和 xterm 的 modifyOtherKeys——并注释了两者的参数顺序相反(ESC[13;2u vs ESC[27;2;13~),后者主要在 SSH 场景出现,因为“TERM 嗅探认不出 Ghostty,而我们从不主动推 kitty 模式“。

同一条消歧目标,四家四种姿态:Codex 探测后启用、留开关;Kimi 协商加原生兜底;Claude 只解析不推送,把两种编码都当既成事实接受;ForgeLoopTUI 乐观推送、解析器只映射 Enter 一个键(其余 CSI-u 键码静默丢弃。这是够用主义:我要的只是 Shift+Enter 和回车的区分)。

这没有对错,是各自对“多少终端会把我送进歧义“的不同估计。


三、模式开关:开了要对,关了要对,被劫持了也要对

bracketed paste、focus 事件、同步输出、kitty 键盘,输入侧的能力几乎全是模式:进入时打开,退出时关闭。后面会把模式开关列为攻击面,讲它“为什么危险“;这一篇补工程侧:为什么难对。

难在状态的所有权不排他。终端模式是全 fd 共享的全局状态,而进程会挂起:Codex 里 Ctrl+Z 是特殊键位(SUSPEND_KEY),进程切后台再回来,raw mode 可能已经被 shell 或别的程序动过——所以有 reapply_raw_mode_after_resume,resume 时重新核对。外部编辑器(第 5 篇)是同一类问题的放大版:起 $EDITOR 前退 raw mode、暂停事件总线,回来后全部恢复。模式开关的正确性是“开、关、被别人动过之后恢复“的三态核对,一个布尔值装不下。

这也解释了一个看似多余的字段为什么存在:Codex 的输入事件栈从 crossterm 的 EventStream 收敛成七种 TuiEvent——Key、Paste、Resize、Draw、Resume、FocusGained、FocusLost。Resume 和两种 Focus 能进这个清单,本身就是核对需求留下的痕迹:挂起恢复要重同步,焦点得失要影响光标样式与轮询节奏。


四、复用器与 alt screen:中间还有一层翻译

以上所有假设之上还有一层:用户可能隔着 tmux 或 Zellij。复用器是一个中间人终端:它代理你的查询、转译你的模式开关、按自己的窗口管理切割你的输出。后续我会讲 Codex 在这上面的演进:从 Zellij 特判,到特判删除、换成 ScrollbackStrategy 三档策略。这里只补一句输入侧的对称事实:复用器对输出做的是转译,对输入做的是过滤与改造,bracketed paste 标记、kitty 序列、focus 事件过一道复用器之后,可能变形、延迟或消失。上一篇的 paste-burst 启发式,有一部分用户就是复用器制造出来的。

alt screen 的启用判定(Codex 的 determine_alt_screen_mode)因此也不只是读配置,而是一次综合判断:用户配置、终端能力、复用器在不在场,三方一起定。


五、雷区表与它的空缺

把这一篇的对照收成一张表(能力 × 各家策略):

输入侧能力CodexClaude CodeKimi CodeForgeLoopTUI
能力探测250ms 预算 + DA 哨兵提前判定,字节回放DA1 哨兵为唯一机制,无超时协商序列 + 150ms 分片超时不探测,乐观推送
kitty 键盘探测启用 + 环境变量逃生门只解析不推送,兼收 modifyOtherKeys推 flags 7 + 原生修饰键兜底无条件推 ESC[>1u,只映射 Enter
bracketed paste支持,缺标记时走 paste-burst支持,缺标记时 \r 启发式归一支持,缺标记时走 paste-burst支持(ESC[?2004h)
挂起恢复与退出清理resume 重上 raw mode—(未见对应机制)退出前排空 stdin—(引擎层不持有进程模型)
终端身份OSC 10/11 默认颜色、光标位置XTVERSION(穿透 SSH)OSC 颜色判明暗主题不探测

表的最后我想诚实标注一个空缺:我原本想收一张“输入侧能力 × 终端模拟器“的雷区矩阵表,哪个终端在哪个序列上行为异常。结果是压根就收不齐:这类数据存在于各家的 issue tracker 和运维记忆里,每个 TUI 团队都在私下重攒一份。

输入侧的讨论比输出侧少一个数量级,重视程度也低一级,但这不代表这里不重要、坑少,反而处处是大坑,这张填不出来的表就是证据。我在这部分做得并不完备,主要是已经被各种大坑弄得疲惫不堪。


六、总结

输出侧的降级链有一个舒服的终点:颜色退到 16 色,内容还在。

输入侧没有这个终点:按键的含义错了就是错了,谈不上降级。所以输入侧的工程主题是“核对“,不是“降级“:启动时探测核对、模式开关三态核对、挂起恢复核对、复用器在场核对。终端是上世纪七十年代的协议,每一家 agent 都在为它重新核对一次。

输出侧讲完了,输入侧也讲完了。现在可以去中场了。第 7 篇的 Event Sourcing 往上走一层,回答输出侧那几篇不断逼近的问题:为什么这些挣扎最后都收敛到“事件“这个抽象上。


参考与延伸

  • 本篇与第 5 篇同期写成。Codex 部分基于本地快照 main 6b9826e3(2026-09-09)的阅读,探测相关代码在 codex-rs/tui/src/terminal_probe.rs 与 terminal_probe/startup_replay.rs;探测预算此后由 #46855(2026-09-20 合入)从 100ms 上调到 250ms。
  • Claude Code 以打包形式发布、未公开源码;terminal-querier.ts 的模块名与注释引自 2026-03-31 经 npm source map 外泄的公开快照,与第 5 篇所用快照相同。
  • Kimi Code 部分(kitty 握手、native-modifiers.ts)按第 5 篇标注的 kimi-code 本地源码 54117a6b(2026-09-24)理解。
  • ForgeLoopTUI 部分基于 ForgeLoopTUI v1.2.1 源码(RawTTY.enter() 与按键解析)。

中场——Event Sourcing,Agent UI 的底层模型

正篇的中场。前六篇完成了 TUI 侧的完整深潜,这一篇先不往前冲,往上走一层:输出侧三篇暴露的所有麻烦,到底有没有一个统一的理论解释?


一、中场为什么有必要

回顾输出侧三篇的核心矛盾:

  • 第 2 篇:终端没有 undo,增量 diff 依赖 8 个帧状态字段,一次 resize 全盘失效。为什么 TUI 的渲染正确性一定要绑在这么脆弱的状态上?
  • 第 3 篇:Markdown 是“写完再解析“的语言,Agent 是“边想边输出“的过程。Stable Prefix Cache 有代码块盲区,表格需要 retreat 机制。为什么这些防御逻辑一个都不能少?
  • 第 4 篇:Agent 输出是一棵树,工具调用乱序到达,thinking 中途穿插。稳定槽位队列 + shiftIndices 偏移追踪 + 有上限的 FIFO 通知队列,为什么渲染器要维护这么多索引?

答案藏在一个更根本的问题里:

Agent 的执行过程本身不是任何 UI 的“内部状态“。它是一组独立于界面的、按时间顺序发生的事件集合。TUI 的困境(脆弱的状态记忆、防御逻辑、索引追踪)根子不在“终端难用“,在“把事件树强行投影成线性输出“这个投影操作本身的结构性代价。

换一个投影方式(比如 GUI),这些代价也不会消失,只会以不同的形态重新出现。


二、Agent 的执行本质:一条事件流

如果你把 Agent 的一次完整执行记录下来,去掉所有 UI 相关的渲染细节,底层是什么?

type AgentEvent =
  | { type: "message"; role: "user" | "agent"; content: string }
  | { type: "tool.started"; toolCallId: string; tool: string; args: unknown }
  | { type: "tool.output"; toolCallId: string; chunk: string }
  | { type: "tool.finished"; toolCallId: string; status: "ok" | "error" }
  | { type: "file.changed"; path: string; diff: string }
  | { type: "permission.requested"; requestId: string; risk: RiskLevel }
  | { type: "permission.resolved"; requestId: string; approved: boolean }
  | { type: "task.plan.updated"; items: PlanItem[] }
  | { type: "validation.started"; command: string }
  | { type: "validation.finished"; result: ValidationResult }
  | { type: "thinking"; content: string; isFinal: boolean }
  | { type: "notification"; text: string }

这是一条 append-only 的事件流。Agent 的每一次推理、每一个工具调用、每一次权限请求、每一次文件变更,都只是这条流上的一个新事件。

这条事件流独立于任何 UI 而存在。 无论你用 CLI、TUI、GUI、IDE 还是 Web,底层都是同一件事:Agent 在做它的工作,产生事件。UI 的职责只是把这些事件投影到用户的感知空间。

这就是 Event Sourcing 在 Agent 领域的应用:Agent Runtime 是事件生产者,各种 UI 是事件消费者。不同 UI 是同一事件流的不同投影(projection)。


三、事件的三层分类

上面列的那些事件类型可以自然地分成三层:

层级事件类型特点
执行流tool.started / tool.finished / validation.* / task.plan.updated时间线核心,所有 UI 都必须处理
副作用流file.changed / tool.output可批量、可合并、可延迟投影
交互流permission.requested / permission.resolved阻塞型,需要 UI 在限定时间内给出响应

这三层只覆盖“执行相关“的事件。message、thinking、notification 不在其中,它们是内容流(对话内容、推理过程、系统提示),同样以事件形式被各端投影,但不参与执行流/副作用流/交互流的划分。

这个分类在学术上未必严谨(因为实际上就是我自己总结的),价值在于它解释了为什么不同 UI 对“同一套事件“的消费策略如此不同。

执行流是所有 UI 都要处理的基线。CLI/TUI 把它展平成线性文本,GUI 把它映射成卡片和状态动画。

副作用流在不同 UI 上的处理成本差异最大。TUI 里 file.changed 就是一行路径字符串;GUI 里它需要一个 diff 审查面板:并排对比、行级高亮、部分采纳/拒绝。同一个事件,投影成本差一个数量级。

交互流是最有意思的。CLI 里 permission.requested 是阻塞式 [y/n]:输入循环停下来,进程阻塞在 stdin 上等用户输入。GUI 里同一个事件可以是非阻塞 toast + badge counter,用户喝咖啡回来再处理。事件类型相同,但 UI 和事件之间的响应契约完全不同。 这就是为什么“先稳定事件协议,再谈 GUI 复杂交互“不是空话:事件协议里如果不区分“需要即时响应“和“可以延迟处理“,GUI 的优势就无从发挥。


四、两种极端说法的共同盲区

当前关于 Agent UI 的讨论里,有两种极端的说法。

说法一:CLI/TUI 只是早期原型,GUI 必然到来。 这个观点假设 CLI/TUI 和 GUI 是线性进化关系:卵 → 幼虫 → 成虫。但用 event-sourcing 的框架看,这不是进化,是共存。

SSH 到远程服务器跑 agent、在 tmux 里恢复一个跑了 3 小时的会话,这些场景里 CLI/TUI 不是“过渡方案“,是最优投影。GUI 在 diff 审查和多模态展示上有结构性优势,两者是分工关系。

再往下推一层:这个说法还隐含一个成本假设:GUI 的投影成本会随着框架成熟趋近于零,所以“替代“只是时间问题。但 Agent GUI 的成本大头跟“画界面“关系不大,贵在两个媒介基线差异带来的子系统数量:diff 审查面板、权限弹窗、多模态附件,每一个都是独立子系统(第 8、10 篇会逐一拆解)。这个成本由 Agent 场景的需求决定,不随框架成熟收敛。

说法二:GUI Agent 方向可能从根本上就是错的,Agent 就应该走 CLI 原生路线。 港大的 CLI-Anything 项目(2026.03)常被拿来当这一派的论据,它主张用 CLI 化的接口整体取代操作 GUI 的 agent。这个说法正确的一面是:为 Agent 设计结构化接口、输出 JSON 而非 UI 界面,确实比让 Agent 模仿人类操作 GUI 更可靠。但说法二错误的一面是:把“Agent 的核心接口应该是结构化的“和“用户界面应该全是 CLI“混为一谈了。event-sourcing 框架下,Agent 核心走结构化协议,用户界面走多端投影,这两件事不互斥。

CLI-Anything 回答的是“Agent 如何可靠地操作软件“,这是接口层的问题,结构化协议确实是正确答案。但“人如何可靠地监督 Agent“是另一个问题:审查 diff、批准权限、审计历史,这些事情的载体是视觉界面,不是 JSON。把接口层的正确结论外推到界面层,就是这个说法越界的地方。

两种说法的共同盲区:把 UI 当成了 Agent 的本体,而不是 Agent 的投影。


五、从 ForgeLoopTUI 的 CoreRenderEvent 到 GUI 的 diffable snapshot

第 4 篇详细拆解了 ForgeLoopTUI 的 CoreRenderEvent 枚举和 TranscriptRenderer 的索引追踪系统。回头看这套设计:

case operationStart(id: "A", header: "...", status: "...")
// → pendingTools.append((id: "A", lineIndex: 42))

case operationEnd(id: "A", isError: false, result: "...")
// → 定位 lineIndex 42,替换状态行
// → shiftIndices 偏移后续所有引用

pendingTools 其实是一个在内存中维护的事件关联索引:它把分散到达的 operationStart 和 operationEnd 重新配对,让渲染结果在视觉上连续。

现在把这个思路映射到 GUI。在 UICollectionView 或者 LazyColumn 的世界里,你不需要手写 shiftIndices。你需要的是:

event stream → diffable data source → snapshot → cell 复用

operationStart → 插入一个新的 tool card cell(pending 状态)。operationEnd → 找到对应 cell,更新为 done/error 状态,触发局部重绘。框架帮你处理索引偏移,这是 UICollectionViewDiffableDataSource 的内置能力。

同一个数据结构,不同的投影成本。TUI 要手写 200 行索引追踪;GUI 框架内置。但反过来,GUI 要为“tool card 的 pending → running → done 状态动画“写一套完整的 cell 生命周期管理,TUI 只需要换一行文本。

这套 cell 生命周期管理拆开看并不轻松。状态迁移要走批量更新才能保证动画连贯,不能这个 cell 已经翻牌、那个 cell 还在旋转;内容高度随流式更新不断变化,每条事件都可能触发一次局部 relayout;cell 被回收复用时必须完整重置:进度动画、展开状态、错误样式,漏重置一个,就是“新消息显示上一条的旋转图标“这种经典 bug。TUI 侧的对应物是第 2 篇那 8 个帧状态字段,集中在一处、错一处全盘可见;GUI 侧的对应物是分散在每个 cell 里的状态机,单点错、局部错,但排查时要面对的是几十种 cell 类型各自的生命周期。

投影成本不会消失,只是换了形态。


六、append-only event log 的长期价值

事件流不只是渲染层的技术选型,在 Agent 产品的几个方面都有长期价值:

恢复。

用户关闭客户端、Agent 继续执行。重连时,客户端从 event log 的最后一条已知事件开始消费,所有状态重建,不需要存储“当时的 UI 状态“,只需要回放事件。第 2 篇讲的帧状态记忆(8 个字段、resize 全盘失效)之所以脆弱,正是因为 TUI 存的是“渲染结果“而不是“事件源头“。

审计。

想知道 Agent 昨天在哪个文件上做了什么改动?查 event log,file.changed 事件带时间戳、路径和 diff,不需要翻聊天记录。

协作。

两个用户看同一个 Agent 会话,Web 端看到富文本 diff 面板,IDE 端看到行级采纳/拒绝按钮。同一个事件流,两个投影,不需要为每个端单独维护状态。

回放。

调试 Agent 行为时,回放 event log 比复现对话快得多。

已有开源实践在走这条路:Zacp 通过 ACP 协议把多个 CLI Agent 的事件流转发到 WebUI,是多端投影的一个雏形。


七、这个框架不能解决什么

Event Sourcing 解释了结构,但有两个问题它不能替你回答。

第一,事件的粒度应该多细? 太粗:file.changed 包含整个文件的 diff,GUI 上的 diff 面板没法做行级高亮。太细:每个 token 都是一个事件,事件量爆炸,storage 和 replay 成本不可接受。粒度的答案不来自理论,来自具体 UI 的交互需求。

第二,交互流的响应契约怎么设计? permission.requested 是阻塞还是非阻塞?超时时间多少?哪些权限可以批量预批,哪些必须逐个确认?这些不是事件类型的字段问题,是产品设计问题。Event Sourcing 能告诉你“这里需要一个 permission 事件“,但不能告诉你“这个事件应该在 UI 上存活多久“。


八、总结

这一篇想说明一件事:

Agent UI 的问题和 CLI/TUI、GUI 的形态之争关系不大,要解决的是如何为一条不确定、乱序、可中断的事件流设计多端投影。

前五篇(02–06)的 TUI 深入研究,展示的是“线性投影“这种特定投影方式的完整成本。接下来三篇(08–10)转向 GUI,展示同一套事件在像素世界里的投影成本:同样的结构性矛盾,不同的表现形式。

一条事件流,多种投影。


参考与延伸

为什么做一个“不错“的 Agent GUI 这么难

GUI 部分开篇。TUI 侧深潜完毕,从这一篇开始,同一个 Agent 场景进入像素世界:拥有原生控件、滚动视图和 GPU 合成器之后,技术问题完全不同。


一、“不错“的标准不在同一基线

TUI 用户看到 box-drawing 字符画的表格(┌───┬───┐)会觉得“这是个表格“。GUI 用户看到表格没有交替行背景色、没有列排序按钮、不能横向滚动,就会觉得“这做得不好“。

这并非用户挑剔,而是两个媒介的基线不同:

TUI 用户期望GUI 用户期望
表格字符对齐即可原生表格、可排序、可滚动
代码块等宽字体即可语法高亮、复制按钮、行号
滚动能滚动就行惯性滚动、回弹、流畅 60fps
颜色有颜色区分就行Dark Mode 自适应、无障碍对比度
动画没有也正常掉帧就是 bug
多模态不期望图片、文件、语音是基本功能

TUI 的“功能完备“往往已经接近 GUI 的“勉强可用“。要在 GUI 上做到“不错“,你需要处理的子系统数量通常会比 TUI 多出数倍。

第 1 篇引过一个判断:做 GUI 要么 VSCode 换皮,要么自研。这里把它量化:自研到底要做多少东西?以 FlowDown 为例。


二、FlowDown 的七个子系统

FlowDown 的界面层建立在这些独立库之上:

子系统职责为什么需要独立库
MarkdownView流式 Markdown 渲染Markdown 解析 + Litext 布局,约 8500 行(3.9.1)
完整聊天 UI(内置,后开源为 LanguageModelChatUI)聊天界面主体消息列表、流式动画、工具调用展示、语音输入
ChatClientKitOpenAI 兼容 API 客户端SSE 流式解析、请求管理、重试逻辑
ColorfulX动画颜色/渐变渲染打字机效果中的背景动画、品牌色渐变
ListViewKit高性能列表视图diffable data source、cell 复用、动态高度缓存
GlyphixTextFx文字特效打字机逐字 reveal 效果
AlertController弹窗系统工具确认弹窗、MCP 授权弹窗

ChatClientKit 是两边共担的协议层成本,TUI 同样需要 SSE 解析和请求管理。拉开差距的是其余六个 UI 子系统。

对照 TUI:

GUI 子系统TUI 对应成本差异
MarkdownViewStreamingMarkdownEngine(~800 行 Swift)TUI 省得多(~800 行 vs 8500 行,布局成本在渲染引擎里另算),第 3 篇和第 9 篇各自展开
ListViewKitTranscriptBuffer(一个 [String] 数组)TUI 零成本
ColorfulX / GlyphixTextFx不需要,没有像素和动画GUI 独占
AlertController一行 [y/n] 提示GUI 独占
完整聊天 UI(内置)RenderLoop + commit/live 分区GUI 重得多

这就是为什么第 1 篇说 TUI 的复杂度天花板低。你不需要做动画渲染引擎,因为没有动画。不需要做 cell 复用,因为终端不回收行。不需要做 MCP 授权弹窗,因为终端只有键盘输入。


三、Agent 让 GUI 的复杂度再翻倍

普通聊天应用的状态:用户消息 → AI 回复。线性,两个方向。

Agent 应用的状态:用户消息 → thinking → 工具调用 × N(可能并行)→ 乱序返回 → thinking → 流式回复 + 中途取消 + 重试。第 4 篇和第 7 篇已经充分展示了这棵树的复杂程度。

每种状态在 GUI 上都是一个独立的 UI 子系统。

3.1 工具调用的四态状态机

一个工具调用在 GUI 上需要展示至少四个状态:

pending  → 灰色图标 + 工具名称(等待执行)
running  → 旋转动画 + 状态文本(执行中)
success  → 绿色勾 + 结果摘要(可展开查看详情)
error    → 红色叉 + 错误信息(可重试按钮)

而且多个工具调用可能并行。第 4 篇讲的 pendingTools 稳定槽位队列 + shiftIndices 索引追踪,在 GUI 上对应的是 UICollectionView 的多 section diffable snapshot,底层数据结构类似(事件 → 索引 → 局部更新),但 UI 表达成本不在同一量级:TUI 是替换一行文本,GUI 是独立的卡片、独立的加载动画、独立的结果展开/折叠、独立的错误重试按钮。

3.2 MCP 工具确认

MCP(Model Context Protocol)工具在执行前可能需要用户确认:“此工具将读取你的日历数据,是否允许?”

GUI 上这是一个弹窗或内联确认卡片,含工具描述、权限列表、允许/拒绝/总是允许三个按钮。TUI 上是一行 [y/n] 提示。后者可以很轻,前者是一个完整的弹窗子系统,AlertController 的代码量不亚于一个小型 UI 库。

3.3 上下文窗口可视化

Agent 的上下文窗口是有限资源。GUI 上可以展示 token 用量进度条、上下文溢出预警、历史消息压缩提示:UIProgressView + UILabel + 动画过渡,组合在一起就是一套完整的子系统。TUI 上你最多在状态栏展示 [context: 85%]。

机制上这个子系统有三层。

数据层:token 用量从哪来?API 响应里的 usage 字段是滞后值(一次请求完成后才知道),流式期间的实时用量要靠本地 tokenizer 估算,两个数据源的口径并不一致,界面上要决定显示哪一个。

状态层:用量是会话级的单调递增状态,但历史消息压缩会让它突然回落,进度条要处理这种非单调跳变,动画方向是反的。

交互层:预警阈值触发后做什么?只是变红,还是给出“开启新会话 / 压缩历史“的操作入口?这是产品决策,不是 UI 决策。

3.4 多模态嵌入

GUI Agent 客户端需要支持图片附件(Vision 模型输入)、文件附件(代码文件、PDF)、语音输入(转写)。每种附件类型都需要自己的缩略图渲染、上传进度指示、错误重试、点击放大/预览。TUI 上的附件多半退化成一个路径或占位符(第 5 篇讲过 Codex 和 Claude Code 的图片粘贴),比如 file:///path/to/image.png。

每种附件背后是一条完整的管线:选取(系统 picker 或拖拽)→ 本地校验(格式、大小)→ 缩略图生成(后台线程,主线程不能卡)→ 上传(进度回调、失败重试)→ 发送后预览(点击放大、长按保存)。管线的每一环都是一个状态机,而它们共享同一个 cell:附件还在上传途中用户就点了发送,“文本已发、附件未完成“这个中间态怎么展示,是没有现成答案的问题。TUI 绕开了这条管线的大半:缩略图、上传进度、点击预览这几环都没有。


四、长会话的性能

第 2 篇讲过 TUI 在长会话下的困境:帧超过终端高度触发全量重绘,Live Budget Planner 把超预算的 live 行沉降到 committed 区,物理行缓存全部重算。

GUI 在长会话下的性能问题是不同性质的。UITableView / UICollectionView 天生支持 cell 复用:屏幕外 cell 被回收,屏幕内 cell 被复用填充新数据。这是 iOS SDK 内建能力,不需要手写。

但这不意味着 GUI 没有性能挑战。超长消息的列表仍然需要:

  • 分页加载(滚到顶部时异步加载更早的消息)
  • 动态高度缓存(避免每次 heightForRowAt 都重新 layout cell;iOS 8+ 的 self-sizing cell 能自动算高,但对流式更新、高度异构的富文本 cell,自动计算意味着反复 layout,手写缓存仍有必要)
  • 图片/文件附件的缩略图缓存(NSCache + 磁盘 LRU)

TUI 和 GUI 在长会话性能上的关系是“难的方向不同“。TUI 难在物理行计算和增量 diff;GUI 难在内存管理和 cell 复用策略。


五、Dark Mode 和无障碍:TUI 相对省事,GUI 要逐项手写

这是 TUI 相对省事的能力,但不是免费。终端设置的颜色方案通常会自动带到 ANSI 渲染上;无障碍支持取决于终端和具体实现。

GUI 上这两个是实打实的工作量,但要分开说。Dark Mode 对系统颜色简单,对自定义颜色稍微复杂:每个自定义颜色都要定义 light/dark variant,每个自定义 view 都要在 traitCollectionDidChange(iOS 17 起换成 registerForTraitChanges)里刷新。还有一个隐蔽成本是动态色解析:UIColor.systemBlue 这类动态颜色在 trait 变化时重新解析,但自定义绘制(draw(_:)、CALayer)里的颜色不会自动跟随,需要手动监听并重绘;渐变、阴影这类叠加效果在两种模式下的对比度要分别调。

无障碍同样分两半:标准控件(UIButton、UILabel)由系统免费获得 VoiceOver 支持;自定义绘制的 view 则全是手写工作量,为每个交互元素设置 accessibilityLabel / accessibilityHint,为自定义容器实现 UIAccessibilityContainer,为图表类内容提供文字化描述。而 Agent 客户端恰好多是自定义绘制:tool card、diff 视图、流式动画。不难,但多:每个自定义 view 都要做,漏一个就是 bug。


六、跨平台:从零成本到选阵营

第 2 篇讲过 TUI 的跨平台:同一套 ANSI 序列,所有终端通用。

GUI 没有这个选项。选了 UIKit → 只有 Apple 平台。选了 Electron → 全桌面平台但有 150MB+ 基线。选了 Flutter → 全平台但 Dart 生态有限。选了 Compose Multiplatform → iOS 已稳定,但生态和三方库覆盖仍比 UIKit / SwiftUI 薄。

对于独立开发者或小团队,这个选择直接决定能做多大。FlowDown 选择 UIKit,所以当前实现只覆盖 Apple 平台。覆盖 Android 和 Web 基本等于重写整个 UI 层。


七、回到 Event Sourcing:同一套事件,翻倍的投影成本

第 7 篇的核心论点是:CLI/TUI/GUI 都是同一事件流的不同投影。第 2–4 篇展示了 TUI 的投影成本。这一篇展示的是同一个东西在 GUI 上的投影成本。

同样一个 tool.started 事件:TUI 里是一行文本,GUI 里是一个带旋转动画的卡片。同样是 file.changed:TUI 里是路径字符串,GUI 里是 diff 审查面板。同样是 permission.requested:TUI 里是 [y/n],GUI 里是完整弹窗。

投影成本不会消失,只是换了形态:**TUI 的成本集中在渲染管线的精确性(物理行、帧状态、增量 diff),GUI 的成本分散在子系统数量和交互细节。**哪个更难,取决于团队结构和目标平台。可以确定的是:做一个“看起来还不错“的 Agent GUI,起点就是七个子系统。


八、总结

这一篇回答了一个看似矛盾的问题:既然 TUI 有那么多结构性优势(第 1、2 篇),为什么还有人做 GUI?因为 GUI 的结构性优势同样真实:像素级渲染让历史回看不被终端行数限制、多面板比较天然成立、语法高亮和视觉化 diff 不需要手写 tokenizer、无障碍对标准控件由系统免费获得。

这不是谁更好的问题。选 TUI 是因为你必须在受限环境中交付:ssh、低配机器、管道化、CI 集成。选 GUI 是因为你的用户期望“不错“,而“不错“在 GUI 上的门槛,比很多人想象的高得多。

下一篇聚焦这个门槛里最核心的一块,GUI 上的 Markdown 流式渲染:打字机效果背后的三层管线(解析 → 构建 → 布局),以及为什么全量重建才是瓶颈。


参考与延伸

  • 本文的 GUI 子系统拆解基于 FlowDown 的实际架构分析。
  • TUI 对照部分基于 ForgeLoopTUI v1.2.0。

GUI 上的 Markdown 流式渲染——全量重建与工程折中

第 3 篇拆了 TUI 上的 Markdown 流式渲染,这一篇是同一面问题的镜像。在拥有像素、字体引擎和 GPU 合成器的 GUI 世界里,它仍然是个难题:在 iPhone 上,一段 3000 字的“打字机效果”能吃掉 60% 的 CPU。


一、打字机效果 ≠ 增量渲染

用过 ChatGPT、Claude 的人都熟悉流式输出的打字机效果:AI 的回复逐字出现。但这是视觉错觉。

真实情况:数据层是增量的,渲染层不是。

网络 SSE chunk → BalancedEmitter(增量吐出字符)
  → message.document += newText               // 全文拼接
  → MarkdownParser.parse(fullContent)          // ← 全量 AST 解析
  → TextBuilder.build()                        // ← 全量重建 NSAttributedString
  → textView.attributedText = doc              // ← CoreText 全量布局

每一步 O(n)。n 随文本增长而变大。以下是 FlowDown 在一组本地实测里的 3000 字回复数据,反映的是特定设备和构建配置下的趋势:

文本量解析构建布局刷新频率CPU
~500 字轻轻轻20 Hz低
~1500 字中中中15 Hz中
~3000 字重重重9 Hz~60%
5000+ 字很重很重很重3 Hz高

应用已经做了降频处理,文本越长刷新越慢。但这只降低了“重做“频率,没降低单次“重做“的成本。3000 字时每秒仍有 9 次全量管线触发。

打字机效果是 BalancedEmitter 增量吐出字符制造的数据层假象。渲染层每次都在重做整个文档。


二、三层管线拆解

从 LLM token 到屏幕像素,经过六个阶段:

LLM token 流
  → ① 传输:SSE chunk 到达
  → ② 拼接:chunk 拼成字符串,节流控制
  → ③ 检测:判断当前文本是否"可解析"(大部分实现没有这层)
  → ④ 解析:Markdown → AST
  → ⑤ 构建:AST → NSAttributedString
  → ⑥ 布局:NSAttributedString → 像素

④⑤⑥ 深度耦合。问题不能靠单独替换某一层解决。

解析层:最根本的限制

以 cmark 为例:

cmark_parser_new()    → 创建 parser
cmark_parser_feed()   → 喂入文本(可以分多次喂)
cmark_parser_finish() → 结束解析,产出 AST
cmark_parser_free()   → 销毁 parser

没有 pause(),没有 resume(),没有 ast_diff(old, new)。feed 可以分多次喂,但 AST 要到 finish 之后才拿得到,finish 之后也不能接着往同一份文档里喂。所以每次新 chunk 到达都必须走完整的 create → feed → finish → free 流程。

构建层

FlowDown 的 TextBuilder 源码里有一行:

assert(!previouslyBuilt, "TextBuilder can only be built once.")

整个 builder 假设输入是一份完整的解析结果。一次性产出完整的 NSMutableAttributedString,遍历所有 block node 做属性拼接。NSMutableAttributedString 本身有 append(_:),但这条 builder 管线的设计假设不支持增量。

布局层

textView.attributedText = doc 之后,整段富文本重新进入文本系统计算。富文本布局比纯文本贵 50-100 倍:同样的 3000 字,纯文本布局 <1ms,富文本 20-60ms。差距来自字形查找(6+ 种字体 face)、CJK 字体回退链、换行断点评估、内存分配风暴。

2.1 O(n) 这么重:常数因子拆解

O(n) 的大 O 记法掩盖了常数因子。以 iPhone 上 3000 字富文本 NSAttributedString(包含代码块、标题、加粗、链接、表格等多种样式组合)为例,一次 CoreText 布局的实际开销拆开看:

字形生成。 纯文本布局是 trivial 的,一个字体 face,逐字符排版。但 Markdown 渲染产出的是高度异构的 NSAttributedString:正文用 .systemFont,加粗/斜体用不同 weight,代码块用等宽字体(Menlo 或 SF Mono),标题用不同 size(H1-H6 至少 2-3 种),链接可能换 foregroundColor,emoji 触发 Apple Color Emoji 字体回退路径。每个字符的属性变更都可能触发一次新的字体 face 查找。3000 字符 × 5-6 种字体 face,加上 CJK 字符的字体回退链(CJK 字形在 systemFont 中不完整时需回退到专用中文字体),字形查找本身就是显著的 CPU 开销。

换行计算。 CoreText 的 line breaker 对每一行都要做宽度测量(候选断点位置的累积字符宽度)、断点选择(在允许的断点中选最优,考虑连字符、标点禁则)、中文特殊规则(行首禁则:。,、不能出现在行首;行末溢出:标点可以略微突出边界)。一个 3000 字的段落,假定平均每行 30 个字符、总共 100 行,断点评估的量级远比“扫描一遍字符串“大得多。

内存分配与 ARC 开销。 这是最容易被忽略的一项。每个 tick 的完整路径:cmark_parser_new + cmark_node_new × N + cmark_parser_free(malloc/free AST 节点树)→ NSMutableAttributedString.append() × M 个 block(每个 append 可能触发属性字典 NSDictionary 分配)→ CTFramesetterCreateWithAttributedString(内部分配 CTTypesetter + CTLine × 100 行 + 字形缓存)。9 次/秒 × 3000 字:大量短暂存活的对象在单次 runloop iteration 中创建和丢弃,ARC 的 retain/release 在这些对象间高频触发,autorelease pool 在 runloop 末尾 drain 时集中释放,产生额外 CPU 尖峰。

量化对比:

操作3000 字耗时(数量级)占比
cmark 解析~1-3ms~5%
TextBuilder 构建~5-15ms~15%
CoreText 布局~20-60ms~80%

同一段 3000 字的纯文本布局(单一字体、无属性切换):< 1ms。差距是 50-100 倍,主因是属性异构,不是文本长度;高频触发再把这个差距乘到总量上。

2.2 CoreText 全量 invalidate 的本质

CTFramesetter 的 API 设计假设输入的 NSAttributedString 是“完整的、不会增量变化的“。当你修改 attributedText 并重新 set 时:必须重新创建 framesetter → 必须重新对整个内容做排布 → 每行 line fragment 的位置都可能因为前面内容的变动而偏移。CoreText 内部没有“脏区域“标记机制,它不知道哪些行变了、哪些没变。

对比 CSS layout engine:浏览器里 element.appendChild(newParagraph) 只标记父节点为 “layout dirty”,然后只重排那个子树,页面大部分内容保持原位。而 CoreText 的 textView.attributedText = newAttrString,一切 invalidate,从头到尾全量重排。

Markdown 的块级结构更是放大了这个问题。列表嵌套深度、代码块边界、角标定义,这些跨段落上下文依赖意味着即使 CoreText 支持 dirty reflow,Markdown 解析层的全局依赖也会让“局部修改“扩散为“全局 dirty“。


三、路线 A:边输出边渲染

BalancedEmitter:节流发射器

actor BalancedEmitter {
    private var buffer: String = ""
    private var frequency: Int         // 发射次数/秒
    private var batchSize: Int         // 每次发射字符数

    func add(_ chunk: String) {
        buffer += chunk
        batchSize = max(1, Int(ceil(Double(buffer.count) / Double(frequency))))  // 动态
        dispatchLoopIfRequired()
    }
}

batchSize 是动态的,缓冲区积压越多,每次发射字符越多,自适应追赶。

emotionalDamage 降频

文本越长 → 渲染越重 → 主动降频:

var emotionalDamage = 0  // 累计字符数

if emotionalDamage >= 5000 {
    frequency = 3   // 3次/秒 — 极长文本
} else if emotionalDamage >= 2000 {
    frequency = 9   // 9次/秒
} else if emotionalDamage >= 1000 {
    frequency = 15  // 15次/秒
}
// 默认 20次/秒

设计思想:“宁可视觉上慢一点,也不能让 UI 掉帧。”

代价:O(n²)

每次渲染是 O(n)。但流式场景下 O(n) 被执行了 O(n) 次:

tick  1: parse(50字)  + build(50字)  + layout(50字)
tick  2: parse(100字) + build(100字) + layout(100字)
...
tick 90: parse(3000字)+ build(3000字)+ layout(3000字)

总工作量 ≈ N²。降频让 tick 数不再严格正比于 N,但砍的是常数因子,复杂度阶没变。降频的收益集中在中等长度(1000-5000 字),文本继续变长、频率触底(3Hz)之后,tick 数重新正比于 N,总工作量回归 N²。

补记(2026.10):另一个流派——队列压力自适应

本篇定稿后我读了 Codex 的 TUI 流式渲染源码,发现“chunk 到达频率 ≠ 渲染频率“这道题还有第二种解法,与 BalancedEmitter 正好构成两个流派,补在这里。

BalancedEmitter(以及第 2 篇的 16ms 合帧窗口)是时间窗流派:以固定节奏发射,窗口内到达的内容合并成一批。它均匀化的是到达侧:实现简单、几乎无状态,代价是突发流量下要靠加大每批的量来追赶(BalancedEmitter 的 batchSize 随积压变大,大约一秒追平),追赶时打字机节奏会被打乱。

Codex 是队列压力流派:节奏不变(commit tick 跑在约 8.33ms 的帧间隔上,即 120fps 上限),变的是每 tick 放行多少行。一共两档:Smooth 档每 tick 放行一行,保住打字机节奏;CatchUp 档一次清空队列。换挡依据只有两个标量,队列深度和最老一行的年龄(入队时打时间戳):

  • 进入 CatchUp,满足其一即可:深度 ≥ 8 行,或最老行龄 ≥ 120ms;
  • 退出须同时满足:深度 ≤ 2 行且行龄 ≤ 40ms,并持续 250ms;
  • 退出后 250ms 冷却期内禁止再入;但严重积压(64 行或 300ms)豁免冷却。

不对称是刻意的:进入用“或“、退出用“且“加持续窗口,全部动机是防换挡抖动。源码文件头自带一份症状导向的调参指南(“延迟出现得太晚就调低进入阈值;两档频繁互切就加大持续窗口”),把运维经验直接写进了注释。

同一个取舍,两个流派的处理方式不同。时间窗在到达侧做均匀化:窗口内的中间帧被丢弃,突发时靠加大批量追赶,节奏会乱。队列压力在消费侧做自适应:低流量下每帧一行、节奏不断,突发下瞬时追平,延迟有上界;代价是要维护队列、时间戳和迟滞状态机。这个设计里我最喜欢的有两点:策略只吃两个标量,与内容、来源完全解耦(它不知道自己在给 Markdown 放行,更不知道什么是表格);动画队列排空即停表,空闲时零 CPU 空转,和第 2 篇 RenderLoop 的“空闲即停“是同一个决定。顺带记下坐标:ForgeLoopTUI 的 16ms 合帧与 BalancedEmitter 都押在时间窗一侧,这个补记的意义是标出解空间的另一个极点。


四、路线 B:输出完毕再渲染

流式期间不做任何渲染,只把 chunk 拼进 buffer。流式结束后一次性做完整 Markdown 渲染。

流式中:buffer += chunk(字符串拼接,摊还 O(1) per chunk)
流式结束:一次完整 parse + build + layout

CPU 优势:管线只跑一次。代价:没有打字机效果,等了几秒后突然出现完整回复。适用于非实时对话场景(批量处理、后台任务)。


五、过渡方案:流式纯文本 + 结束切 Markdown

这是 ROI 最高的方案。

流式期间跳过④⑤⑥层,用纯文本展示。流式结束那一刻做一次完整 Markdown 渲染,切换成富文本。

流式中:纯文本渲染(无 parse/build 开销)
流式结束:一次性完整 Markdown 渲染

改动全在应用层,渲染入口加一个 if-else,不碰任何外部库。流式期间 Markdown 解析开销清零。

代价:流式过程中看到的是原始 Markdown 语法(**加粗**、# 标题),流式结束有一次 snap 切换。但流式过程中 Markdown 语法通常是未闭合的:**bold 没右半截、代码块没结尾 ```,当前方案下这些残缺语法的渲染结果也是错乱的。纯文本反而是干净的。


六、跨技术栈对比:谁解决了哪一层

解析层(④)主流渲染库(cmark、marked、markdown-it)都是全量解析,大家站在同一条起跑线上。差距全在⑤⑥层。

解析层(④)构建层(⑤)布局层(⑥)
原生 CoreTextcmark 全量NSAttributedString 全量重建全量 invalidate
原生 TextKit 2cmark 全量NSTextContentStorage 增量追加NSTextLayoutManager 局部 invalidate
WebViewJS 全量 parseReact reconciliation → 最小 DOM 变更浏览器增量 reflow
React NativeJS 全量 parseReact reconciliation → 最小变更集Yoga 增量布局
LynxJS/C++ 全量 parse后台线程 diff → updateData 增量原生增量 + list 虚拟化

下面展开 WebView、RN 和 Lynx 三条路:它们各自的优势、代价和适用边界。

6.1 WebView:增量 reflow 是出厂能力

浏览器渲染引擎从 90 年代末的 DHTML 时代起就在解决“网页被 JavaScript 不断修改“的问题,增量 reflow 是它的第一能力,不是后加的特性。

当 JavaScript 向 DOM 追加新节点时(appendChild),渲染引擎只标记受影响子树为 dirty:Style Computation 只对新增节点做 selector matching;Layout 从 dirty node 向上找到最近的 block formatting context root,向下做局部重排,兄弟节点不受影响;Paint 只重绘 dirty region;Composite 直接复用未变动的 GPU texture 图层。

但 Markdown 解析仍在 JS 层,marked.js、markdown-it 每次仍然是全量 parse。所以实际做法分两类:

做法 A:innerHTML 全量替换。 每次新 chunk 到达,把整段 Markdown 重新转成 HTML 字符串,赋给 innerHTML。这条路径没有节点级复用:innerHTML 赋值的标准行为是解析整段 HTML 字符串、销毁旧子树、构建新子树,浏览器不在这条路径上做新旧 DOM diff,不存在“结构一致就复用节点“的优化。它的收益在重建之后:新子树挂上文档时,渲染引擎按正常的 dirty 传播做增量 reflow 和重绘,兄弟容器和页面其余部分不受影响;而且 HTML 解析本身是高度优化的 C++ 路径,比 JS 层的 reconcile 便宜得多。所以“全量“全在 DOM 构建层,并不全在渲染层。

做法 B:React reconciliation。 Vercel AI SDK 的默认做法:useChat 每收到一个新 chunk 就触发一次重渲染(可用 throttle 参数节流)→ React 对使用 messages 的组件(通常是整个消息列表)做 Virtual DOM diff → 找到最小 DOM 变更集 → 只 apply 这些变更到真实 DOM → 浏览器收到最小 DOM 变更 → 最小化 dirty reflow。注意这里出力气的是 React 而非 SDK 本身,SDK 不含 Markdown 渲染逻辑,Vercel 后来开源了专为流式输出设计的 Streamdown,现在是 AI Elements 里 Message 组件的渲染器。React 的 Virtual DOM diff 替代了原生方案中 NSAttributedString 全量重建(⑤层),浏览器增量 reflow 替代了 CoreText 全量重排(⑥层)。

代价:WKWebView 进程隔离,每个 WebContent 进程占独立内存空间,占用随页面内容波动很大(数十 MB 到数百 MB),且 iOS 对单个 WebContent 进程设有系统级内存上限(随设备内存缩放,iPhone 大致从数百 MB 到约 2GB,iPad 更高),超限该进程直接被 jetsam 杀掉,表现为 WebView 白屏;聊天列表中多个 cell 不能都用 WebView;字体渲染和系统不一致;Dynamic Type、VoiceOver 要在网页里另做一套适配。

6.2 React Native:新架构去掉了 Bridge 瓶颈

RN 经典架构(Bridge 模式)下,JS Thread 做 React reconciliation → Shadow Thread 用 Yoga(C++)做 flexbox 增量布局 → Main Thread 通过 Bridge 接收 mutation list 做原生视图增量更新。每次新 chunk 产生的微小变更都要经过异步 Bridge 序列化/反序列化。

新架构(Fabric + JSI,0.68+ 引入,0.76 起默认启用)去掉了异步 Bridge:JS 通过 JSI 直接同步调用 C++ 函数;Fabric 的 Shadow Tree 直接映射到原生 View Tree,支持优先级调度(高优更新可以打断低优更新)。对 Markdown 流式渲染的关键改进是:每次 chunk 产生的微小 DOM 变更不再经过异步 Bridge,布局计算可以在渲染帧空闲时执行,不阻塞主线程滚动。

但 RN 也不能做 Markdown 增量解析。它还有一个隐蔽问题:流式输出中,新 chunk 可能改变已有段落的结构(如代码块闭合后,之前被误判为代码块内容的东西需要重排),导致大量 key 失配,Reconciliation 退化为接近全量对比。

6.3 Lynx:引擎内置流式能力

Lynx(字节跳动出品)在两个关键设计上对 AI 流式场景特别友好:双线程架构(Main Thread + Background Thread)将网络流解析和业务逻辑处理放在非 UI 线程:token 到达 → 后台解析 → 生成 UI 更新 → 提交给主线程渲染,正好匹配 LLM SSE 流式数据的处理需求。fetchStream 在引擎层面提供了三端统一的流式资源接口,不像 RN 需要依赖第三方 SSE 库做桥接。updateData 支持从原生侧增量推送数据,不需要每次重刷整个模板。

Lynx 在流式渲染上的优势和 RN 新架构类似:后台线程处理流式数据和 UI diff,主线程只负责渲染。但 Lynx 把流式网络、模板更新、列表虚拟化做成了引擎内置能力,不需要开发者自己搭 pipe。

6.4 结论

别指望“增量 Markdown 解析“来救场。

各技术栈只是在下游渲染架构上有不同程度的增量优化。WebView / RN / Lynx 的渲染架构天然更适应高频增量更新的冲击,原生 CoreText 在这方面是最脆弱的。技术栈选型时别把宝押在“能增量解析 Markdown“上:增量解析器是有的(比如 CodeMirror 6 用的 Lezer),但就算解析能增量,瓶颈也还在⑤⑥;该问的是“谁的渲染引擎能更好地吸收高频增量更新的冲击“。


七、为什么移动端比桌面端严重得多

同一段 3000 字流式 Markdown,Mac 上 10-15% CPU,iPhone 飙到 60%。原因不在代码:

散热。 iPhone 是被动散热,持续高负载触发 thermal throttling 后 CPU 降频,单次 layout 从 30ms 升到 50ms,CPU 占用率反而更高,恶性循环。

CPU 微架构。 Mac M 系列芯片的共享 L2 与系统级缓存(SLC)更大,内存带宽更高。CoreText 布局阶段大量访问字形缓存,cache miss 时 iPhone 代价远高于 Mac。

WKWebView 成本。 WebView 的进程隔离在移动端是实打实的代价,每个 WebContent 进程占用独立内存空间,超限会被 jetsam 杀掉(直接白屏)。桌面端无所谓,移动端多 cell 场景是真实的稳定性风险。


八、四条优化路线的 ROI 排序

#方案改动面收益副作用
1继续降频一行参数CPU ~50-75%打字机变顿
2流式纯文本 + 结束切 MD1-2 个调用点流式 MD 开销清零流式期间看原始语法
3模块检测 + 分片渲染手写检测器 + 改造渲染管线视觉更好工程量大
4底层增量解析三个库架构重构理论上最优极高复杂度

方案 2 的 ROI 最高。方案 4 留给相关库的长期演进,或者留给 WebView/RN,它们的渲染架构天生更适应这个场景。工程上更难的,往往是判断一个方案不该做。


九、总结

第 3 篇讲 TUI 上的 Markdown 流式渲染,困在字符网格和物理行计算里。这一篇讲 GUI 上的同一问题,困在解析器和 CoreText 的全量重建里。核心矛盾完全相同:Markdown 是“写完再解析“的语言,Agent 是“边想边输出“的过程。 两种介质只是在不同的层面与这个矛盾搏斗。

TUI 的策略:降级映射 + Stable Prefix Cache + 防御性 retreat。GUI 的策略:节流降频 + 纯文本 fallback + 模块检测。

没有哪个介质解决了这个问题,都只是在各自的约束下做了不同的折中。


十、后续

第 10 篇:权限 UX 与 Diff UX,Agent 真正的“主界面“。前几篇(TUI 五篇和 GUI 两篇)都在讲“怎么渲染“,下一篇开始讲“渲染什么“:在 Agent 的所有输出中,哪两样东西最值得精心设计界面。


参考与延伸

  • 本文分析基于 FlowDown 源码(pin MarkdownView 3.9.1)和 ForgeLoopTUI 项目,性能数据来自 FlowDown 流式卡顿分析笔记;iPhone 上 3000 字约 60%、Mac 上 10–15% 等数字的测量设备与方法,以该笔记为准。
  • §三补记基于 Codex 本地源码 2026-10-04 的阅读:codex-rs/tui/src/streaming/chunking.rs(两档与迟滞参数)、streaming/commit_tick.rs、tui.rs(TARGET_FRAME_INTERVAL),快照 main 6b9826e3(2026-09-09)。

权限 UX 与 Diff UX——Agent 真正的“主界面“

前九篇都在讲“怎么渲染”,这一篇换一个问题:在 Agent 产出的所有内容里,什么最值得精心设计界面?答案不是聊天框。


一、聊天框是 Agent 的“命令行“,不是它的“主界面“

用 Agent 的日常:你在聊天框里说“修一下这个 bug“,然后你盯着的不是自己的话,是两样东西:

  1. Agent 要做什么操作?读哪个文件?改哪一行?删什么东西?推不推送?(权限)
  2. Agent 做完之后,到底改了什么?有没有顺手改了不该改的?(diff)

聊天是指令和解释。权限是“执行前“的信任建立。diff 是“执行后“的信任验证。

如果你把 Agent 的 UI 设计成一个大聊天框 + 小字状态栏,你其实是在用“命令行“的范式做 Agent,所有信息都挤在一条线性流里。但 Agent 不是命令行工具。它是一个会主动发起操作、会产生副作用、需要你审计其产出的智能体。聊天框是交互入口,不是信息架构。


二、上半篇:权限 UX

2.1 权限不是 allow/deny 二选一

一个 Agent 请求“读取文件“,权限 UX 需要回答的问题远比 yes/no 多:

  • 为什么需要这个权限?因为用户要求“修复测试“,需要读测试失败的堆栈里引用的源文件。
  • 影响范围是什么?只读当前项目目录,不访问系统文件。
  • 具体命令是什么?cat src/auth/session.rs。
  • 可回滚吗?读操作天然安全,不产生副作用。

换成“删除文件“或“git push“:影响范围变了,风险变了,UI 也应该变。但不少 Agent 的权限 UX 只有一级“allow / deny“,不区分风险等级。

2.2 风险维度的四层模型

风险维度操作示例建议授权粒度
只读读文件、搜索代码、查看 git log可批量自动批准(项目内)
写入(可回滚)编辑文件、git commit会话级授权
写入(难回滚)git push –force、数据库迁移每次确认
外部副作用网络请求、安装依赖、访问密钥每次确认 + 展示完整命令

这四层不是写在协议里的,它们来自操作本身的属性。一个好的权限 UX 在展示权限请求时,应该让用户一眼看到它在哪一层,而不是把“读取文件“和“git push –force“用同一个弹窗展示。

2.3 授权粒度:一次性 vs 会话 vs 项目 vs 全局

  • 一次性:仅此一次。默认对高风险操作。
  • 会话级:本次对话中同类操作自动通过。适合“编辑文件“,一个修复任务可能改 5 个文件,每次都弹窗是折磨。
  • 项目级:当前项目内同类操作自动通过。适合“读文件““搜索代码”,项目内读操作几乎没有风险。
  • 全局:永远自动通过。适合“显示当前时间““获取 git branch“等零风险操作。

就我观察到的产品而言,做满四层的很少,多数停在前面两层。后两层需要持久化授权策略:本地存储一份“信任规则“,Agent 在上报权限请求前先匹配规则。这不难实现,Claude Code 的 /permissions 和 settings 文件已经在做(会话、项目、全局三级),但把四层做全、且把规则管理做好的,仍然不多。

2.4 授权疲劳和过度打断的平衡

第 7 篇讲过 TUI 的 [y/n] 是阻塞式的,Agent 停下来等用户输入;同一篇还分析了 permission.requested 事件的交互流特性:它需要 UI 在限定时间内给出响应。

GUI 的优势在这里:同一个权限请求,可以做非阻塞的 toast + badge,用户喝咖啡回来再处理。但这也引入了一个新问题:如果用户不在,Agent 就一直等着?超时策略和默认行为(超时拒绝 vs 超时自动批准低风险操作)是权限 UX 里最需要产品判断力的部分,也是最容易被忽视的。

信任等级还要在界面上被“表达“出来,而不只是存在于配置里。常见的做法是把 2.2 的四层风险映射到视觉层级:只读操作用中性色、默认按钮聚焦“允许“;难回滚和外部副作用换警示色、去掉“总是允许“选项、默认聚焦“拒绝“,让用户在误触场景下落在安全的一侧。信任等级表达得好的界面,用户不读完整段描述也能判断“这个请求值不值得停下来细看“;表达得差的界面,所有请求长一个样,用户要么全部无脑点允许,要么全部停下来读,上面说的授权疲劳和过度打断,一半原因在这里。

补记(2026.09):本篇定稿后的第二天,这个取舍就有了新的行业答案。8 月 14 日起,Claude Code 的 auto mode 成为 Pro/Max/Team 计划的默认(3 月上线,此前只是可选项):一个 AI 分类器替用户批准常规操作、拦下不可逆和危险的命令。Anthropic 给出的依据是分类器拦下了 89% 的危险命令,人工审批只拦下 13.6%。这等于在“逐条确认“和“无脑放行“之间插进了第三个审批者,把授权疲劳工程化地绕开了。但它同时造出一个新问题:程序员要的是可观察,分类器自己的判断过程却是一个新的黑箱,第 1 篇的信任模型在这里遇到了新的考题。

2.5 三种界面上的权限 UX 差异

CLI/TUIGUI DesktopWeb
展示一行文本 + [y/n]弹窗/内联卡片,含完整上下文同 GUI
阻塞性完全阻塞可非阻塞(toast + badge)取决于实现
批量批准y 或 a(全部)多选列表多选列表
信任规则持久化配置文件(如 Claude Code 的 .claude/settings.json)本地存储 + UI 管理面板服务端存储
离场处理默认挂起(用户离开 = Agent 停在原地)超时策略 + 后台通知移动端推送

TUI 最简单但最脆弱,用户离开终端,Agent 就卡在权限请求上(到 2026 年秋天,头部产品已经补上了后台会话和推送,见第 11 篇的补记)。GUI 有能力做得更好,但设计复杂度也更高。

2.6 操作路径长度:同一个权限请求,两种界面的真实差距

衡量 UI 好坏有一个直接的方法:别看“展示多少信息“,看从看到请求到完成决策需要几步操作。

同一个场景,Agent 请求读取 ~/.ssh/config:

TUI 路径: 一行 [y/n] 提示 → 用户读文本判断风险 → 输入 y → 回车。3 步,信息密度低但是零 friction。适合:快速判断、低风险操作、用户在电脑前。

GUI 路径: 弹窗展示(工具名 + 文件路径 + 风险等级颜色 + 操作原因)→ 用户扫一眼颜色判断风险等级 → 点击“本次允许“。1 步操作,但前置了信息摄入时间。适合:高风险操作、用户需要完整上下文才能决策、用户可能不在电脑前(异步处理)。

两种界面在权限 UX 上的差距,在于 GUI 能把线性操作变成空间决策,而不只是展示更多信息。 TUI 里你只能按顺序读:先读工具名、再读文件路径、再判断风险,因为终端只有一维空间。GUI 里颜色标记、图标、按钮位置同时进入视野,用户可以跳读。这是第 3–4 篇讲的“降级映射“在 UX 层的对应物:TUI 把空间信息压缩成线性文本,GUI 保留了空间维度。


三、下半篇:Diff UX

3.1 对 coding agent 来说,最终产物是 diff

你让 Agent 修一个 bug。它想了,搜了,改了,跑了测试。对话流里有 50 行 thinking、3 个工具调用、200 行日志。但最终你要看的东西只有一样:它到底改了哪些文件,每一处改动是否合理。

聊天是指令和解释。diff 才是交付物。

3.2 Agent 的 diff 和人类的 diff,审查需求不同

人类 PR review 关注:逻辑是否正确、风格是否一致、是否有隐患。

Agent 的 diff review 需要额外关注四件事:

  • 意图对齐:它改的是不是我想要它改的?它有没有自己“发明“一个需求?
  • 范围蔓延:有没有顺手改了不该改的:动了 lockfile、改了无关文件的 import、格式化了没碰过的函数?
  • 幻觉检测:有没有引入不存在的 API、错误的方法签名、凭空捏造的配置项?
  • 连锁影响:改 A 文件是因为改了 B 文件所以必须跟改,还是它随机碰的?

这意味着 Agent diff review 需要额外的上下文信息叠加:在 diff 旁边标注“这行是因为上一步搜索 UserSession 找到的引用“或“这个改动是基于测试失败输出中的第 3 行“。传统 diff view 不提供这些。

3.3 好的 Agent diff UX 应该怎么做

  • 按文件组织:树状文件列表 + 每个文件的变更行数。一眼看到“动了 3 个文件,其中 2 个是预期的,1 个是 lockfile——等等,它为什么动 lockfile?“
  • 按语义组织:同一类变更归为一组:“所有重命名”“所有格式化”“所有逻辑变更“分开展示。机械变更折叠起来快速扫过,审查精力集中在真正改了逻辑的 hunk 上。
  • 按风险标记:纯重构(变量重命名)→ 低风险绿色。逻辑变更 → 中风险黄色。引入新依赖、改动 API 签名 → 高风险红色。
  • 部分采纳/拒绝:用户可以 hunk 级别接受或回退,不是全量接受或全量拒绝。git add -p 的 GUI 版本。
  • 测试关联:每个变更旁边标注“这个改动使得测试 X 从失败变成通过“,建立 diff 和测试结果之间的因果关系。

按语义组织的价值在量大时最明显:一次修 10 个文件的 diff 里,可能 7 个文件只是 import 跟随调整,需要决策的只有 3 个 hunk。把机械变更折叠成一组(“另外 7 个文件的 import 同步,共 42 行”),审查的认知负载从 O(文件数) 降到 O(决策点数)。这需要从 Agent 的事件流里提取意图信息,file.changed 事件本身不告诉你“这个改动是跟着哪个改动来的“,聚类是 diff UX 层要补的工作。

这些不是新发明,Code Review 工具(Gerrit、Reviewable、GitHub PR review)已经做了很多年。但 Agent 产出的 diff 有两个独特的约束:一是量可能很大(一次修 10 个文件的 bug),二是上下文信息需要从 Agent 的事件流里提取,不是从 git log 里提取。

3.4 Diff UX 是 CLI 和 GUI 分工最清晰的点

CLI/TUI:适合快速扫一眼。git diff 在终端里看 20 行变更,半秒判断“没问题“。适合小任务、小改动。

CLI/TUI 还有一个容易被低估的位置:过程展示。Agent 工作过程中,每产生一个 file.changed,终端里就实时追加一段 +/- 行,用户在 Agent 边干的时候边看 diff 逐步成形,发现方向不对可以立即打断,不用等它写完 10 个文件再审。GUI 的 diff 面板通常按“完成后集中审查“设计,实时流式展示反而是它的弱项,并排视图在中间态下频繁重排,阅读体验很差。过程展示用 CLI/TUI,集中审查用 GUI,这是两种介质在 diff 上的分工。

GUI/IDE:适合深度审查。并排对比、行级高亮、hunk 级采纳/拒绝、文件树导航。适合大任务、多文件改动、需要仔细审计的场景。

这无关谁更好,同一份 diff 在两种介质的投影各有优势。第 7 篇的 event-sourcing 框架在这里再次成立:file.changed 事件只有一个,但 TUI 投影(+/- 行文本)和 GUI 投影(并排审查面板)服务于不同阶段的用户需求。

3.5 信息提取效率:为什么 GUI diff 不只是“更好看“

第 3 篇讲过 TUI 的表格渲染:用 box-drawing 字符画边框(┌───┬───┐),在终端里它“像一个表格“,但它实际上是字符排列。当终端宽度不够时,需要复杂的截断策略。GUI 的原生表格:Auto Layout 自动处理宽度分配,不需要手动计算 cell 字符宽度。

同一个逻辑迁移到 diff:

TUI 的 git diff: 纯文本行,以 +/- 前缀区分新增和删除。你要逐行读才能建立变更的心智模型:“这里加了 3 行、删了 2 行、改了 1 个变量名”。信息密度高,但信息提取效率低,因为所有信息都在同一维度的文本流里,靠你的眼睛做解析。

GUI 的 diff 面板: 并排对比(旧在左、新在右),新增/删除/修改用不同背景色标记,行内差异用更深色高亮(比如变量名从 oldName 改成 newName,只高亮 old→new 两个词而不是整行),文件树显示每个文件的变更行数概要。你可以先扫文件树定位感兴趣的文件,再看并排对比理解具体变更,最后 hunk 级别决定采纳还是拒绝。

这不是“好看“,是信息架构的维度差异。TUI 把 diff 的二维结构(哪些文件 × 每个文件改了什么)压缩成了一维文本流。GUI 保留了二维结构,用户可以跳读。两者分别适合“快速确认“和“深度审计“两种认知模式。


四、总结

权限是“执行前“的信任建立。Diff 是“执行后“的信任验证。

把 Agent UI 设计成一个大聊天框 + 小字状态栏,等于把信任建立和信任验证都塞进了一条线性对话流里。用户需要自己从聊天的 100 行文本里挖出“它刚才请求了什么权限“和“它到底改了什么“。

更好的信息架构:聊天框是指令和解释的主通道。权限请求是侧栏的独立卡片。diff 是可展开的文件树面板。三者各有各的空间,不互相抢占。

这不是为了让 GUI 更漂亮,而是在回答第 1 篇提出的根本需求:**程序员要的是可观察、可复现、可回滚的自动化,不是更聪明的黑箱。**权限 UX 管“可观察“,Diff UX 管“可复现、可回滚“,聊天框管“交互“,三者撑起的是同一个信任模型。


参考与延伸

  • 本文的权限 UX 与 Diff UX 分析基于作者对主流 Agent 客户端的权限与 diff 交互观察。
  • Diff UX 讨论基于对现有 Code Review 工具(GitHub PR、Gerrit、Reviewable)与 Agent 产出的结构性差异分析。

多端 Agent 架构——CLI、TUI、IDE、Desktop、Web、Mobile

第 7 篇提出了 Event Sourcing 框架:Agent 的执行是一条事件流,不同 UI 是同一事件流的不同投影。这一篇把它展开到六个具体的端,外加 API 这个没有界面的入口。


一、不是多端适配,是多端投影

传统软件做多端,思路是“一套代码,多处适配“,同一套业务逻辑,为每个平台写不同的 UI 层。

Agent 多端的思路不完全一样。它不是“把同一个聊天界面适配到 6 个屏幕尺寸“。同一条事件流,每个端挑自己最适合投影的那部分事件,用自己最擅长的交互方式呈现。 CLI 不需要渲染 diff 面板,Mobile 不需要展示 3000 行日志,IDE 不需要做独立权限弹窗(权限确认以内联形式嵌在编辑器里),每个端只消费它擅长消费的事件子集。


二、六端 + API 的定位

在展开六个端之前,先给“端“定个坐标。六个端是产品形态,底下其实是两条正交的技术轴。

第一条轴:应用和 UI 平台之间用什么契约说话。 一边是结构化对象:AppKit/UIKit 的 view、浏览器的 DOM,应用改界面就是改对象,布局、命中测试、遮挡恢复由平台负责;另一边是 ANSI 字节流:程序面对 PTY(伪终端)只能向前写,改已显示的内容要自己定位、擦除、重写(第 2 篇)。第 2–4 篇的渲染成本、第 13、14、17 篇的所有权之争、第 19 篇的信任面,全是这条轴上的事。

第二条轴:UI 平台跑在哪、能碰到什么资源。 本机原生平台能直接继承 shell 和文件系统;浏览器是带沙箱的运行时,默认碰不到本机的 cwd、PATH、git 凭证;终端模拟器则两种身份都有,iTerm2 是本机原生 app,xterm.js 是浏览器里的 JS 模拟器。

两条轴切出四格:

对象契约(GUI)字节流契约(TUI)
本机原生 GUI(AppKit/UIKit/Qt)原生 TUI(iTerm/kitty + 真实 PTY)
浏览器Web GUI(DOM/CSS)Web TUI(xterm.js + 远端 PTY)

四格里有三个推论,正好解释后面六个端里最容易混的几处:

  • Web TUI 里,TUI 应用什么都没变。 xterm.js 只是把终端模拟器搬进浏览器:parser、字符网格、CJK 双宽、alt screen 全在 JS 里重写一遍,但对 TUI 应用暴露的还是那条字节流,它照样发转义、收 SIGWINCH。变的是部署位置:agent 跑在远端,继承的是那台机器的环境(Codespaces、Cloud Shell、ttyd 都在这格)。SSH“进入工程现场“的语义还在,现场换成了云主机。
  • Electron 在一个浏览器平台里并排摆了两份契约。 VS Code、Cursor 这类应用,界面主体走 DOM(聊天、diff、设置是 Web GUI),主进程再通过 node-pty 开出一条真实 PTY(伪终端,内嵌终端是字节流契约)。它们没有在 GUI/TUI 之间二选一,两格都占:IDE 端能同时给你网页式 diff 和原生终端,靠的就是这个结构。
  • Web GUI 默认被沙箱挡在本机之外。 浏览器里的 agent 不能直接 spawn 编译器、读未提交文件、用你的 ssh agent,所以纯 Web 产品的 runtime 天然在服务端,浏览器只是投影端;服务端事件流从第一天就是事实源,基建卷的主线在这一格是出厂设置,不是后来补的。

六个端可以直接放进坐标系:CLI/TUI 是字节流格(终端模拟器可本机可浏览器);Desktop、Mobile 主要是本机对象格(Mobile 也大量用 WebView,第 9 篇展开);Web 是浏览器对象格;IDE 跨在 Electron 的两格之间。下面逐个看它们各自承载什么。

CLI:执行入口 + 自动化接口

CLI 是最薄的投影。它的核心能力是“执行“,不是“展示“:继承 cwd/PATH/env/git/SSH 全部上下文,直接把 Agent 接入工程现场。

适合承载:全量事件流,但以最原始的方式(文本输出)。适合 CI/CD 集成(./agent fix --auto)、管道组合(cat error.log | agent diagnose)、远程执行(SSH + tmux)。

不适合承载:diff 审查、权限管理、多任务队列。

CLI 不会被“替代“,管道的价值是结构性的,不依赖任何 UI 框架。

TUI:本地工作台

TUI 是 CLI 往上走一层,在终端里提供结构化面板,但保留键盘优先和远程可用的特性。第 2–4 篇拆解的渲染引擎、Markdown 降级和 Agent 事件展平,构成了 TUI 的完整技术栈。

适合承载:执行时间线、工具调用状态、流式输出、权限确认、文件变更列表。适合长时间运行的 Agent 会话(tmux 断线恢复)、低配机器和远程开发场景。

不适合承载:富 diff 审查(并排对比)、多模态附件预览、团队协作。

IDE:代码上下文 + Diff 审查

IDE 插件是天生的 diff 审查工具。编辑器的并排 diff view、行级采纳/拒绝、与语言服务器的集成,这些都是 IDE 的内置能力,Agent 插件只需要对接事件流。

适合承载:file.changed 和 validation.finished 事件的投影,也就是 diff 审查和测试结果。第 10 篇讲的几样里,按文件组织和部分采纳/拒绝在 IDE 里是出厂能力,按风险标记和测试关联还得插件自己补。

不适合承载:长会话管理、权限规则管理、多 Agent 任务编排。IDE 擅长“审查“,不擅长“管理“。

Desktop:本地工作台 + 系统集成

原生实现的 Desktop App,能力介于 TUI 和 Web 之间,有完整的 GUI 控件和原生性能,但不需要浏览器的内存开销。适合独立的 Agent 桌面客户端。

适合承载:系统通知(本地 daemon 在后台跑 Agent,桌面端推送结果)、文件系统集成(拖拽文件到 Agent)、离线恢复(本地 event log 持久化)。

不适合承载:多用户协作(Web 更合适)、纯键盘工作流(TUI 更强)。

Web:团队协作 + 历史 + 审批

Web 是唯一天然支持多用户的端。Agent 产出的 event log 在服务端持久化后,Web 端可以做会话分享、历史搜索、团队审批,这些是 CLI/TUI/IDE 都不擅长的。

适合承载:多任务队列、团队审批流、会话回放和分析、成本统计。Zacp 项目是这条路线的一个实际案例:WebUI + ACP 协议 + 多 CLI Agent,CLI Agent 不知道 WebUI 的存在,WebUI 只消费 ACP 事件,加一个 Web 端不需要改任何 agent 核心。它还顺便回应了一个争论:第 7 篇引过的两种极端观点,“GUI 必然到来“和“GUI Agent 方向根本上错了”(常拿 CLI-Anything 当论据),Zacp 恰好是两者的折中实例:agent 核心保持 CLI 原生、走结构化协议,用户界面侧用 Web 做投影。

不适合承载:实时执行(延迟和网络依赖)、本地文件系统操作。

Mobile:Companion,不是主战场

Mobile 不适合做 Agent 的主执行入口:屏幕小、输入慢、后台限制、散热墙、文件系统权限受限。但 Mobile 有一个不可替代的价值:用户离开电脑后,Mobile 是唯一能触达用户的端。

适合承载:任务状态查看、高风险操作审批、执行总结阅读、简单回复。类似“远程任务控制器“,不是“缩小版 IDE“。

API:自动化与集成入口

六个端之外还有第七个入口:API。它没有任何界面:CI/CD 流水线里触发 Agent(./agent fix --auto 背后就是一个 API 调用)、GitHub webhook 回调(PR 打开时自动发起 review)、脚本化工作流(定时任务、批量仓库维护),事件流以 JSON 形式被程序直接消费。

适合承载:自动化触发、机器消费的执行结果、与现有 DevOps 工具链的集成。

不适合承载:任何需要人在环路的交互,API 端的权限必须全部预批,否则任务挂起。它是统一 Permission Engine 的极端投影:所有交互流事件的答案在调用参数里预先声明。


三、不只“适合做什么“:从渲染架构推导端定位

上面六个端的定位看起来像功能分配:“因为 IDE 有 diff view 所以适合审查,因为 Web 有多用户所以适合协作”。但往下挖一层,每个端的渲染架构决定了它天然擅长和不擅长处理什么类型的事件。

第 9 篇详细拆解了各技术栈在 Markdown 流式渲染上的差异。同一个逻辑可以迁移到端定位:

渲染架构核心特征擅长的事件消费模式对应端
纯文本 stdout(ANSI)零布局开销,线性追加,无 undo高频流式事件(tool.started/finished),单维信息CLI
字符网格增量 diff(ANSI)增量 diff + commit/live 分区,可原地重绘高频流式事件 + 结构化面板(工具状态、权限确认)TUI
CoreText 全量 invalidate每次 attributedText 变更触发完整重排,50-100× 富文本开销一次性富文本展示,不适合高频更新原生 Desktop / Mobile(CoreText 路线;TextKit 2 能局部 invalidate,见第 9 篇)
WebView 增量 reflow脏区传播,只重排受影响子树,出厂能力高频局部更新 + 复杂富文本(diff 面板、协作视图)Web
Yoga / Lynx 后台增量后台线程 diff,主线程只应用变更中频更新 + 低延迟交互 + 列表虚拟化Mobile Companion

这里有一个反直觉的结论:原生端(CoreText)做流式 Agent 聊天反而是最脆弱的。 同样的 3000 字流式 Markdown,iPhone 上 CoreText 全量 layout 每次 20-60ms,WebView 增量 reflow 的代价远低于此。所以“Web 适合协作“不只是因为它有多用户能力,还因为它的渲染引擎天生能消化高频事件更新。而 Mobile 原生端只适合做 Companion(通知 + 轻量审批),结构性的原因前面列过,渲染这一层还要再添一条:在被动散热的手机上,CoreText 全量 invalidate 的高频布局实测很容易顶到 thermal throttling,形成恶性循环。

这不意味着原生端不该做 Agent GUI。但要看清:如果你用原生 CoreText 做流式 Agent 客户端,性能天花板比 WebView 低。 选择技术栈的时候,这比“哪个平台用户多“更根本。


四、每个端的交互契约不同

第 7 篇区分了事件的三层分类:执行流、副作用流、交互流。不同端对这三层的消费策略完全不同:

CLITUIIDEDesktopWebMobile
执行流全量文本输出面板化展示折叠成步骤列表通知摘要可回放时间线仅摘要(推送)
副作用流路径字符串路径字符串并排 diff 面板文件列表富 diff + 评论不展示
交互流阻塞 [y/n]输入行阻塞内联弹窗系统通知页面内卡片推送通知
离场处理不支持tmux 挂起不支持本地 daemon服务端超时推送 + 后台

Mobile 的“仅摘要“来自推送通知和任务卡片,对应前面说的“任务状态查看“;副作用流(diff)则完全不投影到手机。没有一个端需要消费全部事件。CLI 和 Mobile 在消费的事件类型上几乎没有交集,但它们消费的是同一条事件流。

补记(2026.09):这张表写成后,“离场处理“一行开始在头部产品里过时,而且是以印证本文的方式过时的。Claude Code 现在有后台会话(/bg)和独立的 agent 视图,配合 Remote Control 和“Push when Claude decides“配置,Agent 可以在用户离开后继续跑、必要时直接往手机推通知,上面 Mobile 一节说的“用户离开电脑后,Mobile 是唯一能触达用户的端”,已经是出货的功能,不是设想。“CLI/TUI 离场 = 挂起“从此只是默认行为,不再是能力上限。


五、统一 Runtime,统一 Event Log,统一 Permission Engine,统一 Workspace Model

多端架构的核心约束只有四个:

统一 Runtime。 Agent 的执行逻辑(model loop、工具调用、plan-revise 循环)只有一个实例。一个 Agent 跑在 Runtime 里,所有端只做投影,不是每个端各跑一个 Agent。

统一 Event Log。 append-only,按时间排序,不可变。每个端从这个 log 里读取自己需要的事件。这是恢复、审计和协作的基础设施。

统一 Permission Engine。 权限请求从 Agent Runtime 发出,所有端都可以响应。谁先响应就用谁的结果。超时策略和信任规则持久化在 Permission Engine 层,不是某个 UI 层。

统一 Workspace Model。 cwd、git branch、文件系统状态,这些不属于任何 UI,属于 Workspace。Agent 操作的是 Workspace,不是某个端的“视图“。

满足这四个统一之后,每个端只是一个轻量的投影层:消费事件、渲染 UI、发送用户输入回 Runtime。你加一个 Mobile 端不需要改 Agent 逻辑,加一个 Web 端不需要改权限模型。


六、总结

六端 + API 是分析框架,不是 checklist。一个独立开发者的 Agent 工具可能只需要 CLI + TUI。一个团队协作的 Agent 平台可能需要 Web + IDE + Mobile。选哪些端,取决于用户在哪里、用户在那个场景下需要消费哪些事件。

端多不多不是关键,关键是每加一个端,是不是只需要写投影层,不用重写 Agent 核心。如果每次加端都要重构事件模型和权限引擎,说明架构还没到位。


七、后续

下一篇把移动端单独拿出来讲:它为什么不适合做 Agent 的主执行入口,又在哪个位置不可替代。讲完之后,给到这里为止的十一篇画一张地图。


参考与延伸

本文的多端架构框架参考了 ForgeLoopTUI 的 CoreRenderEvent 设计、Zacp 的 ACP 多 Agent WebUI 架构,以及第 7 篇提出的 Event Sourcing 模型。

移动端的位置

「界面」卷的中场。写作时本想在这里收束,后来没收住。前十一篇从 ANSI 序列一路讲到多端架构。这一篇先说移动端在 Agent 产品里的位置,再回头给这十一篇画一张地图。原先接在后面的个人经验部分,成书时挪到了本卷卷末。


一、移动端在 Agent 产品中的位置

先说清楚,移动端不适合做 Agent 的主执行入口(虽然我个人非常偏爱移动端),原因是结构性的,远不止“屏幕小“:

  • 长运行:Agent 的一个任务可能跑 20 分钟。iOS 的后台限制让长运行进程几乎不可能。
  • 高密度文本:diff、日志、堆栈,这些在 6 寸屏幕上阅读体验极差。
  • 本地工具链:编译器、包管理器、git,手机上跑不了完整的开发环境。
  • 平台政策:App Store 禁止 App 下载并执行改变自身功能的代码(2.5.2),2026 年已因这条拦下多款 vibe coding 应用的更新,还下架过一款。
  • 散热:持续高负载 = thermal throttling = 恶性循环。
  • 内存经济:AI 浪潮把存储产能吸向 HBM,DRAM 合约价一路疯涨,“大内存手机“越来越奢侈;Agent 偏偏是内存饥渴型负载。两条曲线是反着的。
  • 安全边界:手机是身份中枢,银行、2FA、通讯录都在上面。让 Agent 在上面跑任意工具,一次注入攻击的代价是身份沦陷。桌面可以沙箱、可以重装,手机不行。

但移动端有一个不可替代的位置:human-in-the-loop 的最后一公里。

用户离开电脑。Agent 在后台继续跑(Mac 上跑着本地 daemon,或者远程服务器上跑着 Agent)。碰到一个需要确认的操作,移动端推一条通知。用户看一眼,知道 Agent 在做什么,批准或拒绝。Agent 继续。

这不是“把桌面端缩小“。移动端的 Companion 应该极简:当前任务状态、最近一次权限请求、一键批准/拒绝。类似远程汽车钥匙:不需要方向盘,只需要锁门和解锁。

从移动端交互经验里带过来的一个观点:在手机这个受限屏幕上,要考虑的是取舍:什么信息值得放上去,什么该砍掉。

这种克制,在做 Agent 的任何一端时都用得上。


二、中场地图

界面这一卷走到中场,回到系列的开头看一眼。前十一篇,从 ANSI 转义序列写到多端架构,回答的是同一个问题:

从 LLM 输出 token 到用户看到的画面,中间到底经历了什么,以及这个经历在不同介质里有怎样完全不同的形态。

第 1 篇问:为什么 Agent 从 CLI/TUI 开始?答案不是 GUI 不好,是因为当前最硬的问题不在界面表达,在执行过程不确定、权限边界敏感、本地工程环境复杂。CLI/TUI 以最低成本解决了当前最硬的问题。

第 2–4 篇展示了这套“最低成本方案“底下的真实代价,第 5–6 篇补上了输入侧。第 7 篇把问题抽象为 Event Sourcing 框架。第 8–9 篇展示了同一套问题进入 GUI 世界后的新形态。第 10 篇是跨端的信任设计,权限与 diff 这两块“信任界面“,才是 Agent 的主界面。第 11 篇回到全局,多端并存才是终态。

如果这个系列在读者心里留下了一件事,我希望是:

**Agent 的界面是为一种全新的执行体(不确定、长运行、可中断、可审计、会调用工具)设计的工作流界面,不是聊天框的变体。**这个领域需要的是同时理解终端渲染、事件系统、权限模型、diff 审查和本地开发环境的工程师,而不只是会写聊天 UI 的前端。


三、中场总结

写到这里,界面这一卷的中场到了:问题域从像素一路摊到多端。但内容本身还有很多可以深入的点,当时列了一张清单:权限模型的信任规则 DSL、diff 审查面板的具体交互稿、多端 event log 的同步协议、Mobile Companion 的推送通道设计。

成书时回头看,清单上已有两项兑现,而且都不在界面这一卷:多端 event log 的同步与重连,写成了基建卷的《连接与会话》;推送通道和移动端的架构条款,写成了《一条消息的生命线》与《移动端的架构代价》上下篇。界面层提的问题,答案长在下面一层。本卷中场之后也没停在原地:第 13 到 19 篇从渲染的所有权一路写到状态行、回归测试和渲染的信任边界,卷末再回到人;再往下,胶水层、基建、评测各自成卷。

渲染的所有权模型——已完成的内容归谁管

一、一个我以为不存在的问题

第 2 篇的结论是:Agent TUI 的渲染,核心是在 “终端没有 undo” 这片地基上,做增量 diff、物理行计算、帧状态记忆、commit/live 分区。这些内容全部基于 ForgeLoopTUI 的实际源码,描述本身没有错误。

问题在于一个隐含假设:我以为 Claude Code 和 Codex 也是这么做的,毕竟用起来是一样的,流式输出原地更新,工具调用状态行被结果替换,底部输入框固定不动。

直到我在 Codex 仓库里看到这个文件:

codex-rs/tui/src/insert_history.rs

名字已经说明了用途:把完成的内容插入历史(insert_history_lines(),用 DECSTBM 滚动区把内容注入 viewport 上方)。配套的测试文件叫 vt100_live_commit.rs:live 区内容“提交“进历史。快照测试里还有 zellij_raw_terminal_wrap_above_viewport.snap 这种为冷门终端复用器准备的用例。

Claude Code 建在自己的 Ink fork 上(发布产物中可见 src/ink/ 目录),它的渲染层保留着同一个分裂:shouldRenderStatically() 判定一条消息是否可以“静态化“,静态内容打印进 scrollback 后不再参与重绘。CompanionSprite.tsx 里有一句注释直接写明了约束:“floating into Static scrollback can’t be cleared”(飘进 Static scrollback 的东西就擦不掉了)。

再翻 Grok Build,找到一个独立 crate xai-ratatui-inline,核心函数就叫 emit_to_scrollback:“发射进 scrollback”。我以为找到了第三个同路人。但继续追调用方,故事拐了弯:这个函数在生产代码里没有调用者,只出现在 crate 自带的示例和测试里。Grok Build 的默认形态([terminal] alt_screen = auto)是一个进 alt screen 的全屏分页器,应用自管 scrollback,那恰恰是第 2 篇那条路的工业化版本。

真正的 inline 形态是一个默认关闭的实验模式(xai-grok-pager-minimal),而且它也不用 emit_to_scrollback:它用 ratatui 自带的 insert_before(DECSTBM 滚动区)提交定型内容,还立了一个编译期守护测试,禁止任何人把 purge 重印机制接进 minimal 模式。

把四家的默认形态摆在一起,得到的不是收敛,是一张 2:2 的记分牌:

产品默认形态(普通终端)内置的另一形态
Claude Codeinline(Ink <Static> 静态化)可选全屏 /tui fullscreen(2026 年中起,alt screen)
Kimi Codeinline 差分(主屏)实验性全屏(KIMI_CODE_TUI_FULL_SCREEN=1,详见第 14 篇;到 9 月底已升格为正式配置项 tuiMode)
Codexalt screen(tui.alternate_screen = auto,无条件生效;官方文档仍称“auto 在 Zellij 里跳过“,与代码脱节数月,见第七节第 7 条的补正)inline viewport(insert_history.rs 那套)
Grok Build全屏分页器(auto;tmux 控制模式和 Zellij 里降级为全高 inline)实验 minimal inline(xai-grok-pager-minimal)

第 2 篇描述的引擎不是一条“少数派的错路“,四家都内置了这一半。新的问题是这条分界线本身:**一个 block 完成之后,谁继续管它?**以及,为什么每家都在同一产品里养着线的两边。


二、分界线:已完成的内容,谁继续管它

先把两个学派定义清楚。

全屏自管派(ForgeLoopTUI;Grok Build 和 Codex 的默认形态所属):屏幕上每一行都归引擎管。每一帧合成完整画面,与上一帧 diff,精确改写变化的行。已完成的历史内容虽然逻辑上“只追加“,但只要它还显示在屏幕上(或活在自己接管的 alt screen 里),就持续参与每帧的 diff 计算和 resize 重算,引擎就得一直管着它。

inline viewport 派(Claude Code 与 Kimi Code 的默认、Codex 与 Grok Build 的内置降级路径所属):内容一旦“定型“就立刻打印进终端的原生 scrollback,从此归终端管,引擎脱手。引擎自己只维护底部一小块“活区“(viewport),用双缓冲 diff 重绘。

全屏自管派:                     inline viewport 派:
┌─ scrollback ────────────┐    ┌─ scrollback ────────────┐
│ (滚出屏幕才归终端)      │    │ 历史(定型即归终端)      │
├─ 屏幕 ──────────────────┤    │ 历史(定型即归终端)      │
│ 历史      ← 引擎管       │    ├─ 屏幕 ──────────────────┤
│ 历史      ← 引擎管       │    │ 历史(可见但不可触碰)    │
│ live 区   ← 引擎管       │    │ viewport ← 引擎管(仅此处)│
│ 输入框    ← 引擎管       │    │ 输入框(在 viewport 内)  │
└──────────────────────────┘    └──────────────────────────┘

这里要强调一点:两派的 live 区是同构的。 ForgeLoopTUI 的增量 diff、Codex 的 ratatui 双缓冲、Ink 的行级擦除重写,做的是同一件事,这正是我当初误判阵营的原因:表层行为一模一样。

分歧只在一个问题上:一个 block 完成之后,谁还继续管着它?

  • ForgeLoopTUI:完成了也继续管。committedLines、lastCommittedPhysicalRows 等帧状态字段持续追踪它,直到它滚出屏幕顶边。
  • inline 派:完成即脱手。之后它的滚动、搜索、选择、复制都是终端模拟器的事,引擎一行代码都不用写。

给这条分界线起个名字:渲染权的单向移交。inline 派的“脱手“不是甩手,是一次不可逆的所有权转移:scrollback 对应用不可寻址(见 5.1),交出去的渲染权收不回来。后文所有的派生差异都挂在这扇门上:定型时机被迫从几何问题变成生命周期问题(晚交不如早交,交得越晚,钉在 viewport 里的未定型内容越多);resize 从 CPU 问题变成 I/O 问题(移交之后,重排的过程和结果都是终端侧的知识,应用插不上手);失败模式从无法解释的乱码变成有界的“闪一下“(两个渲染者只会在门边出时序事故)。而“谁继续管它“只是这次移交表面上的结果:帧状态字段之所以算在管历史,是因为它是渲染源;不渲染历史,才不需要记住历史。


三、inline 派的机制:发射即定型

这套机制最干净的教科书版本在 Grok 的 crate 里:emit_to_scrollback 全部逻辑只有 60 行(xai-ratatui-inline/src/scrollback.rs,以下为简化伪代码):

#![allow(unused)]
fn main() {
fn emit_to_scrollback(terminal, content) {
    // ① 光标移到 viewport 顶部,从这里往下全部擦掉
    //    —— viewport 里现在画着输入框,发射前先把自己的活区擦干净
    move_to(0, viewport.y);
    print("\x1b[J");

    // ② 把内容打印在擦出来的区域。长行不做换行计算——
    //    wrapping 是终端的工作
    print(content_segments);

    // ③ 打印 viewport.height 个空行,在内容下方"顶"出一块空白
    for _ in 0..viewport.height { print("\r\n") }

    // ④ 光标移到新的 viewport 位置,再擦一次
    move_to(0, new_viewport_y);
    print("\x1b[J");

    // ⑤ 双缓冲作废,viewport 全量重画;要管的只有一个 Rect
    terminal.reset_back_buffer();
    terminal.set_viewport_area(new_viewport_y);
}
}

这里的不变式是:viewport 是可擦除的墨水,scrollback 是泼出去的水。 每发射一批内容,就先擦掉自己画的输入框、把内容印在那个位置、再在下方顶出新的空白区。从终端的视角看,这个程序从头到尾只做两件事:往下打印、在底部反复涂改一小块。

但要如实说一句:这个参考实现在 Grok 产品里目前没有生产调用方。真正在跑的生产路径用的是同一思想的更保守版本:Codex 的 insert_history_lines() 和 ratatui 自带的 insert_before 都走 DECSTBM 滚动区,把内容“插“到 viewport 上方,不擦掉重印;Grok 的 minimal 模式直接复用后者。思想是同一条,工程上各家选了介质兼容性更好的变体。

这套机制的纪律,在 Grok 仓库里有一个直接的证据。xai-grok-pager-minimal/src/guard.rs 是一个守护测试:它用 include_str! 扫描 minimal 模式的每一个源码文件,断言其中不出现 emit_to_scrollback、resize_purge_rerender、resize_viewport_height 这三个标识符。注释写明了理由:这些函数会重印已经归终端的历史,结果是 “double-printing (or, with ED3, wiping) committed scrollback”。这条路线赖以生存的纪律,在这里不是口头约定,是一个挂了就算构建失败的测试。

对照第 2 篇的管理成本。全屏自管派维护 8 个帧状态字段,错一个全屏偏位;inline 派的全部渲染状态是一个 Rect(实质只有 y 在变)加一块可以随时作废的双缓冲。它不追求“记住屏幕“,它追求“随时能重建“。

发射时机的选择也随之改变。第 2 篇的 Live Budget Planner 是空间驱动:live 区超预算就把旧行沉降到 committed。inline 派是语义驱动:一个 block 在事件流里完成了(工具返回了、回复结束了)才发射。“什么时候算定型“从几何问题变成了生命周期问题。 Claude Code 的 shouldRenderStatically()(src/components/Messages.tsx)把这个判定写得很清楚:一条消息想“静态化”,需要它关联的 tool use 不在 streaming、不在 in-progress、已全部 resolved,连同组的兄弟 tool use 和 PostToolUse hooks 都结束了才行。推论是:未定型的内容必须钉在 viewport 里。一个跑五分钟的工具调用,它的 block 就在 viewport 里被反复重绘五分钟,直到拿到结果、定型、发射。

这个变化和第 7 篇的 Event Sourcing 框架是自洽的:事件完成 → 投影定稿 → 归档。inline 派相当于把 Event Sourcing 在渲染层做到了底,投影一旦定稿,连撤回投影的能力都主动放弃。


四、第 2 篇的痛点在这条路线下的命运

第 2 篇的问题全屏自管派的解法inline 派的答案
物理行/逻辑行错位每行 visibleWidth + physicalRows,每帧依赖只在发射瞬间做一次切分;发射后永不再算
8 个帧状态字段持续维护,错一处全盘偏一个 Rect + 可作废的双缓冲
Live Budget Planner超预算沉降,不做部分行切割机制消失,由 block 生命周期替代
用户两帧之间滚动假设破坏,diff 坐标出错历史区滚动是终端的事,不构成假设
历史的搜索/选择/复制需要自己实现(或放弃)终端原生免费,Cmd+F 直接可用
resize缓存全失效,重算重绘当前屏见下节,这是 inline 派付出代价的地方

前五行是真实的收益。但代价没有消失,只是换了形式。


五、inline 派的代价

5.1 发射后的内容不可触碰

ANSI 光标序列只能寻址可见屏幕。一行内容滚过顶边进入 scrollback 后,不存在任何转义序列能再碰到它。而对还停在屏幕上、位于 viewport 上方的历史,inline 派给自己立了纪律:光标从不越过 viewport 顶边,一旦回写,就重新背上了帧状态那份负担,这条路线的全部意义就消失了。

把“不可触碰“用一个例子走到底。屏幕上显示着折叠的字母表 ABC…XYZ,用户想把它原地展开成 26 个字母,分三种处境:

  • 字母还没定型(还在流式输出):两派都能改,而且都在改——一个跑五分钟的工具调用,它的 block 就在 viewport 里被重绘五分钟。这一层没有分歧。
  • 字母已定型、还在屏幕上(viewport 上方):inline 派物理上够得着、纪律上不准回头;全屏自管派原地展开即可,这正是帧状态管着历史换来的能力。
  • 字母已滚出屏幕、被用户翻了回来:最容易误判的一种。那些字节此刻确实显示在屏幕上,但可见不等于可及——翻页改变的是显示,不是归属,它们仍然住在 scrollback 里,而 scrollback 在任何视口位置都不可寻址,这道门根本没有再开过。就算假设它开了,后面还排着两道:应用不知道用户翻到了哪(滚动偏移量、wrap/reflow 的结果都在终端手里,应用一无所知),而且应用一有输出,多数终端默认就把视口拽回底部。三道门里任何一道都足以挡住,inline 派无路可走。

同一个例子反过来量出全屏自管派内部的两档。alt screen 档(Grok 分页器、Codex 默认)连“翻回来“这个动作都是应用自己实现的——alt screen 里没有终端 scrollback,滚动是功能不是白送,每个 block 的位置永远在自己手里,原地展开连滚动位置都不丢。主屏档(ForgeLoopTUI)没这么从容:用户一翻页,diff 坐标系当时就废(第四节“用户两帧之间滚动“那条),想展开只能全量重画恢复坐标系,而任何输出都会把用户拽回底部——改得了,代价是一次核平重画加丢失滚动位置。所以严格地说:能把翻回来的历史原地展开的,只有把 scrollback 布局攥在自己手里的那一档。全屏派的力量不来自“够得着历史“,来自“不必够着历史“:正本在内存模型里,scrollback 只是溢出的副本。

产品后果:用户想展开一个三分钟前完成的折叠 block,历史不能改。Grok Build 的 minimal 模式的答案是 full_view.rs:把整个会话记录以强制展开模式重新渲染成一段 ANSI 文本,交给 $PAGER(less -R)。“重新消费历史“的需求被路由到外部分页器,不靠历史改写。 不可变历史 + 按需导出,是这条路线对“可改写性“需求的最终回答。(应用内的模态查看器 Grok 也有:block_viewer.rs,Ctrl-F 打开,提供搜索、选择、复制,但它长在默认的全屏分页器里。那边的历史本来就归应用管,模态查看器是功能,不是妥协。)

5.2 resize 的核平重印

终端 resize 时,终端会先自动重排 scrollback,应用随后才收到 SIGWINCH,边框被拆花,且各家终端的重排行为不一致(grok 的注释大意:试过按字符数自己算重排,被各家终端的边界行为打回来了)。inline crate 里留着的解法是不修,直接重建(xai-ratatui-inline/src/resize.rs):

#![allow(unused)]
fn main() {
// 注释是个事故报告:本来可以用 RIS (\x1bc) 硬重置,
// 但 RIS 在 iTerm/Terminal.app 里不清 scrollback
write("\x1b[2J\x1b[3J\x1b[H");   // 清屏 + 清 scrollback + 归位
print(history);                  // 内存里的全部历史按新宽度重新打印
// 顶出 viewport 空行、重算位置、clear
}

(同一个文件的文档注释和 README 还写着“用 RIS 重建“的旧方案,文档滞后于代码,以代码里这段事故报告式的注释为准。)

走这条路的前提是必须在内存里保留完整的 block 数据模型,目的不是逐帧渲染,是为了 resize 后能重印,以及支撑应用内的搜索/选择/导出。这里值得点破一个容易混淆的区分:持有模型 ≠ 管历史。不走重印路的 minimal 手里同样握着完整的会话数据(不然 full_view.rs 拿什么渲染给 $PAGER),但它不管历史:那份数据是导出原料,不是渲染源。管与不管的分界线不在“手里有没有历史的数据“,在“还为不为历史的当前呈现负责“。值得记下的是,Grok 的 minimal 模式拒绝走这条路:它宁可使用终端内建的 autoresize、忍受各家的重排差异,也绝不调用 purge 重印,因为 \x1b[3J(ED3)会把已经归终端的 scrollback 一起清掉。guard.rs 那个守护测试,禁的正是这条路。

代价有两笔。一是 I/O 爆发:pty(伪终端)是串行字节流,3 小时会话的历史是几万行、几 MB 文本,每次 resize 都重推一遍(用同步输出模式压住闪烁)。二是 ESC[3J 误伤无辜:它清空终端的整个 scrollback,包括启动 agent 之前 shell 里留下的内容。

对照第 2 篇:全屏自管派的 resize 成本是 CPU(物理行重算),量级是一屏;inline 派是 I/O 带宽,量级是整场会话。代价落在了不同的地方。

5.3 终端免费给的能力,想用就得自建一份

终端 scrollback 的滚动/搜索/选择对人免费,但对程序是黑箱:不能导出会话、不能程序化跳转、不能带格式复制。想把历史当数据用,只能靠内存里那份模型自建。Grok Build 那份 4242 行的 text_selection.rs(连同独立的 scrollback 窗格、历史搜索、导出模块)就是这类自建的样子。不过严格按所有权划分,它长在默认的全屏分页器里,是全屏派把原生能力一件件补回来的清单(第 14 篇会逐条点这张清单);inline 派的 minimal 模式反而没有补这张票,它把“再看一眼历史“导出给了 $PAGER。

5.4 活区膨胀的退化

长任务场景下(后台任务跑 20 分钟、权限等待用户离开),未定型 block 一直钉在 viewport 里参与每帧 diff。“活区极小“的优势被稀释,渲染负担向全屏自管派回归。


六、为什么分界线变成了开关

我初稿把四家写成了“收敛到 inline“,那是错的。真实的图景是 2:2 的默认分岔 + 全员双模。逐项分析之后,我认为有几个结构性原因。

1. 对话的介质本性。
Agent 会话天然 append-only。为“历史原地改写“这个低频需求维护一条常驻的精确 diff 管道,是三条路线里最不划算的一项投入。模态 viewer 和 $PAGER 导出覆盖了真实需求的大部分。这是 inline 派的拉力。

2. 失败模式的不对称。
全屏自管派的失败形态是屏幕上出现无法解释的乱码(输入法劫持光标、tmux 不同步、resize 时机错误),难复现、难定位,且发生在用户最看重的地方(别忘了这是一个需要用户审计 agent 行为的产品)。inline 派的失败形态是 resize 时闪一下,可见、有界、可恢复。对商业产品,这个不对称是决定性的。

3. 纪律比天才便宜。
8 个帧状态字段时刻正确,是一个只有引擎作者本人才能长期维护的承诺;而“发射后永不触碰“是任何新人都能遵守的纪律。大组织选架构,选的是“不容易被改坏“。这个不对称有机制上的根:帧状态是每一帧、每个字段都必须正确的连续承诺,源码扫描守不住一片连续的场;“光标永不越过 viewport 顶边“是一个离散的、可机械检查的边界——移交点是离散的,纪律才能被写成测试。Grok 把这一点做到了字面上:minimal 模式的纪律不靠 Code Review 把关,靠 guard.rs 里一个扫描全部源码的守护测试,纪律被写进了构建。

4. 成本支付频率的不对称。
全屏自管派的维护成本每天都在付(任何渲染改动都要过帧状态);inline 派的爆发成本只在“长会话 + 用户拖窗口“的交集发生时付。pty(伪终端)本身的吞吐是几十 MB/s,瓶颈其实在终端模拟器的解析渲染,但即便保守估计,几 MB 重印也只是百毫秒级的事。为罕见事件多付,为日常事件零成本。

5. 可测试性。
emit_to_scrollback 的测试是 MockTerminal 接住字节流、断言 clear 了几次、flush 了几次,简单到近乎无聊,因为逻辑本身就简单。系统越聪明,证明它正确的基础设施越贵。

以上五条解释了 inline 派的优点,但解释不了为什么 Grok 和 Codex 把默认押在了全屏。我分析了一下,把我认为的原因补上:

6. 会话内体验是真需求。
滚动、搜索、选择复制、平价 resize(全屏派 resize 是 O(屏高) 的 CPU 操作,没有 I/O 爆发)、鼠标交互,长会话用户每天都会用到。终端原生 scrollback 免费提供这些,但只对“人“免费,不对“程序“免费;而全屏派自建一份之后,这些能力对人和程序同时成立。

7. 用户环境是分裂的,但回应正在换代。
同一家公司必须同时服务 iTerm2 用户和 tmux/Zellij 用户,复用器(尤其 Zellij 和 tmux 控制模式)的 scrollback 语义确实让 alt screen 变成事故现场。Grok 的答案保留至今:auto 在 tmux 控制模式和 Zellij 里降级 inline。Codex 的答案则经历了一次转向,还留下一个文档与代码脱节的活案例:它曾经有同款特判,tui.alternate_screen = auto 在 Zellij 里跳过 alt screen,官方配置文档至今仍写着这句话;但代码在 2026 年 5 月中就把特判整个删掉了(#22214,提交标题就叫 “remove Zellij TUI workarounds”),auto 从此无条件进 alt screen,还配了一个测试(alternate_screen_auto_uses_alt_screen)把新行为钉死。我初稿按文档口径写了“auto 在 Zellij 里跳过“,发布前对源码才核出这个脱节,此处补正。特判也并非被简单扔掉,而是换了一层活法:新的 ScrollbackStrategy 在运行时检出 Standard/Zellij/FullScreen 三档终端,决定历史插入和视口生长各自用什么手法(9 月又为 Windows Terminal 补了一档,部分 DEC 滚动区在那儿会丢行)。按终端切模式的开关退役了,按终端选策略的适配接了班。用户环境的分裂没有变,变的是行业对它的回答:从“检测终端、切换模式“走向“统一模式、下放策略“。顺带证明,连“开关是必然产物“这种判断,保质期也可能只有几个月。

8. 历史有两种消费场景。 会话中(要交互、要导航)和退出后(要在终端里向上翻、Cmd+F、复制)对所有权的要求恰好相反。两个场景都真实、都高频,于是四家长出了同一答案:都养一套,或者串行地各管一段。


七、这对本系列意味着什么

先说修正范围,比预想的小:

  • 第 2 篇的技术内容不需要改,它描述 ForgeLoopTUI,而 ForgeLoopTUI 确实那样工作。需要补的是一个坐标系:TUI 渲染引擎存在两个学派,第 2 篇解剖的是全屏自管派的手工形态(Grok Build 的默认分页器是它的工业化形态),而 Claude Code 与 Kimi Code 的默认属于 inline viewport 派。两派的分界不在“live 区怎么画“(那层同构),在“已完成的内容,谁继续管它“。
  • 第 4 篇只需一句限定:槽位队列和 shiftIndices 作用于 live 区;inline 派把乱序配对提前到了数据层:block 按稳定 id 在内存模型里配对完成后才发射,乱序问题从坐标手术退化为字典查找。
  • 第 3、7–12 篇不受影响。第 7 篇的 Event Sourcing 框架反而被 Grok Build 的架构(TUI/headless/ACP 三端共用同一事件流)实证加强。

然后说我做的 UI 引擎的定位。

ForgeLoopTUI 是少数派,但我不认为是错误,Grok Build 和 Codex 的默认形态证明了全屏自管在大组织手里同样能产品化。这条路能做到 inline 派结构性做不到的事:任意可见历史的原地改写、每一帧每一个 ANSI 字节的精确控制、会话内完整的交互能力。如果未来出现“历史必须活“的产品需求(实时协作标注、历史中的 diff 就地更新),inline 派三个实现都得重构,全屏自管派不用。

但演进方向也因此清晰了:ForgeLoopTUI 的 committed 区在语义上已经是 append-only,和 inline 派的 scrollback 只差最后一步:物理上还归不归我管,也就是渲染权交不交、交出去还拿不拿得回。四家的开关给出了同一个提示:这道题不必一次答完,可以按生命周期分阶段回答。这样的交换是否值得,取决于约束集合,这和第 11 篇“端的选择由约束决定“是同一个逻辑,在渲染层又成立了一次。


八、总结

第 2 篇说:TUI 渲染是在“终端没有 undo“的地基上建引擎。这篇补上下半句:地基没法换,但你可以选择和地基的关系。

全屏自管派征服介质:终端没有 undo,就造一个 undo(光标手术 + 帧状态),换来 GUI 级的控制力。inline viewport 派顺应介质:终端的本性就是电传打字机,只进不退,那就不退,把“不可变“从限制变成架构原则。

两种选择没有高下,是同一条公理的两种成本结构:一个持续为“可改写性“付出成本,一个一次性买断“不可改写“、再为重印机制和应用内补偿另行付费。2026 年中的头部产品用配置开关承认了这一点:四家全都内置了两种所有权模型,区别只在默认押哪边、以及另一边做到什么完成度。

我漏掉这条分界线的原因值得记下来:两条路线在视觉上无法区分。我是读了源码才发现的。这也是本系列反复出现的主题的另一个实例:看起来一样的界面,底下的成本结构可以完全不同。 区别不在像素里,在所有权里。

下一篇(第 14 篇)把这个问题推进到工程细节:既然双模已成事实,那“同一引擎里两种所有权共存“到底怎么实现?Kimi Code 在四家里给出了接口最干净的一个样本,包括一个我没在别处见过的设计:退出时把历史归还给终端。


参考与延伸

  • 本文基于 Grok Build(commit 9fabade,2026-08-16;xai-ratatui-inline、xai-grok-pager、xai-grok-pager-minimal)、Codex(codex-rs/tui/src/insert_history.rs、tests/suite/vt100_live_commit.rs;tui.alternate_screen 的 Zellij 特判已于 2026-05-13 在 #22214 中移除,官方配置文档至今仍写旧行为,本文初稿按文档口径转述,2026-09-29 依本地源码(main 6b9826e3,2026-09-09)补正,见第七节第 7 条)与 Claude Code 发布产物中的源码(src/components/Messages.tsx 的 shouldRenderStatically、src/utils/staticRender.tsx、src/ink/ 内置 fork)的实际阅读。
  • 对照部分基于 ForgeLoopTUI v1.2.0。

双模渲染——同一引擎里的两种所有权

第 13 篇讲了 TUI 渲染的两条路线,以及头部 Agent TUI 没有一家押注单边。这一篇解剖一个样本:月之暗面 2026 年开源的 Kimi Code(MIT)。它的渲染引擎在同一个接口、同一棵组件树后面同时实现两种所有权模型,运行时二选一,代码里处处留着两派交锋的事故记录。


一、基本面:一个 vendored fork,两个渲染器

Kimi Code 的 TUI 框架在 packages/pi-tui,是从上游 pi-mono 项目的 pi-tui vendored 进来的 fork。这个 fork 的自我管理方式值得先说一句:pi-tui/AGENTS.md 逐条列出“我们和上游的 8 处分歧“,每条都带守护测试,并明确规定:每次从上游同步后,这 8 条必须逐条重新验证,测试挂了就意味着本地分歧被覆盖丢失。这是把“fork 的维护成本“显性化的做法,和第 13 篇说的“纪律比天才便宜“是同一个精神。

渲染层的关键结构是:TuiBase 提供共享的组件树、overlay 合成、光标提取;TUI 是个接口,有两个实现:

apps/kimi-code/src/tui/tui-state.ts:

  fullscreen = KIMI_CODE_TUI_FULL_SCREEN === '1'
    ? new TuiAltScreen(terminal, ...)   // 实验性全屏
    : new TuiMainScreen(terminal)       // 默认

(写法以文末标注的版本为准:8 月中它还是环境变量开关,到 9 月底,main 分支已经把这个开关升格为正式的 tuiMode 配置项,“实验开关“转正成“产品配置”,方向正是本篇和第 13 篇判断的那条路。)

  • TuiMainScreen(629 行):渲染进终端主屏 + scrollback。inline 派,但是差分变种。
  • TuiAltScreen(1302 行):alt screen 全屏,应用自管视口。全屏自管派,工业级形态。

也就是说,第 13 篇那条我以为只存在于不同公司之间的分界线,在这个仓库里是同一个 if 的两个分支。这给了我一个难得的对照机会:同一棵组件树、同一份组件代码,喂给两种所有权模型,各自的代价会落在哪里。


二、主屏渲染器:inline 派的差分变种

2.1 模型:全量渲染,增量落地

TuiMainScreen.doRender() 的模型是:每帧把整棵组件树(全部历史消息 + 编辑器)渲染成一个扁平行数组 newLines,和上一帧 previousLines 逐行比较,只把变化补丁写入终端。

等等,每帧重渲整棵树?这和 Grok Build 的“发射即脱手“不一样。关键在它对历史的处理方式:历史行渲染一次之后,靠引用相等缓存摊薄成本。组件的渲染缓存对未变化内容返回同一个字符串引用,于是稳态帧的成本是 O(总行数) 次指针比较,只为真正变化的行付处理费(tui-main-screen.ts:237-261,注释原文:“a steady frame only pays for the lines that actually changed”)。

所以准确地说,它和 Grok 那种“定型后彻底不管“的区别在于:逻辑上整棵树都活着,物理上只补丁视口可达的部分。

2.2 所有权分界线被压缩成一个整数

渲染器维护一个 previousViewportTop:逻辑行数组里,这个下标以上的行已经滚进 scrollback,归终端;以下的行在屏幕上,光标可达,归引擎。

第 13 篇用了一整节讲“已完成的内容归谁管“,在这里它就是一个整数加一句检查。整个 doRender() 的题眼是这几行(tui-main-screen.ts:449-455):

// Differential rendering can only touch what was actually visible.
// If the first changed line is above the previous viewport, we need a full redraw.
if (firstChanged < prevViewportTop) {
    fullRender(true);
    return;
}

变化落在视口之内 → 局部补丁;变化越界进 scrollback → fullRender(true):\x1b[2J\x1b[H\x1b[3J 清屏、清 scrollback、全量重印。这就是第 13 篇“历史可改写:不可能,除非整体重印“的判官代码。

2.3 决策树:一串快速失败路径

doRender() 的主体是一串按优先级排列的兜底分支(319-455 行),每条都对应一类真实事故:

  1. 首帧:fullRender(false),不清屏直接写,假设屏幕是干净的;
  2. 宽度变化:核平重印。换行全变,没有局部解,和 Grok Build 的 resize_purge_rerender 做法相同;
  3. 高度变化:原则上也核平,但 Termux 除外。注释写着:Android 软键盘弹出/收起会改高度,如果每次核平,“the entire history to replay on every toggle”(整个历史在每次键盘切换时重播)。一条特例就是一份事故报告;
  4. 内容收缩到历史峰值以下:核平(否则残留的空行清不掉);
  5. 以上都不命中,才进入差分主路:扫描出 firstChanged/lastChanged,只重绘变化区间而非“变化行到末尾“,注释明说动机:“reduces flicker when only a single line changes (e.g., spinner animation)”;
  6. 纯追加(流式输出的常态)走 append 快速路径:光标滚到底直接写。

外加两个通用工程点:所有写包在 \x1b[?2026h/l 同步输出里(原子帧,防撕裂);kitty 图片协议有一整套影子记录(图片行占位行数、changed-range 膨胀、按 id 删除),因为图片在终端里是字节流之外的第二套状态。

2.4 和 Grok 的哲学分野:预防 vs 检测

把两家并排,inline 派内部其实有两个档位:

  • Grok Build(实验 minimal 模式):数据层预防。 block 不到 committed frontier 不发射,发射即归终端,从架构上保证“变化永远不可能越界“。(内存里仍保留完整数据模型,供 full_view 导出和搜索用,只是不再参与逐帧渲染;见第 13 篇讲代价的那一节。)
  • Kimi Code 主屏:渲染层检测 + 核平兜底。 整棵树每帧都可变,渲染器不假设应用守纪律;它在每帧末尾检查变化是否越界,越界就付核平的代价。

前者把正确性建立在纪律上,后者把正确性建立在一句话的运行时检查上。代价结构不同:Grok 的 resize 和“历史变了“都走重印;Kimi 主屏的 resize 走重印,“历史变了“也是重印,但因为整树活着,它不需要额外的纪律来维持不变式,应用层可以随便改数据,渲染层总会收敛到正确画面。这是用偶尔的重印换架构上的免维护。

2.5 变更史里的代价实录

第 13 篇推导的 inline 派三大代价,在 Kimi Code 的 CHANGELOG 里每条都有对应事故(#1353、#1367 见 packages/pi-tui/CHANGELOG.md,#2442、#1188 见 apps/kimi-code/CHANGELOG.md):

  • scrollback 不可改:#1353,流式输出收缩/膨胀循环时,视口锚定出错,把内容重复堆进 scrollback(重复发射);
  • 自我修正的成本:#1367,这个 fork 曾经自己改过 viewport/scrollback 的渲染行为,后来整体回退,回归上游的差分渲染(AGENTS.md 里写着“the fork’s viewport/scrollback rendering patches were reverted“)。在 scrollback 边界上自作聪明,最后被介质教育了;
  • I/O 与重绘风暴:#2442、#1188 反复压全屏重绘次数(“Reduce frequent full-screen redraws”)。

读别人的 CHANGELOG 读到这些条目,感觉是看到自己文章里的推导在别人的事故报告里逐条兑现。


三、全屏渲染器:全屏自管派的工业级形态

TuiAltScreen 是我那派的实现,但它的成熟度远超我自己的 ForgeLoopTUI,值得逐块拆。

3.1 模型:文档 + scrollTop + 视口重绘

进 alt screen(\x1b[?1049h),关自动换行,开鼠标。文档是完整行数组,ScrollView 持有 scrollTop;每帧经 renderLayoutFrame 只排出可见的 height 行,然后逐行和上一屏 previousScreen 比较,变化的行用光标寻址覆写(\x1b[row;1H\x1b[2K + 新行)。没有 scrollback 参与,没有任何“发射“。

先看我那派的核心优势在代码里的直接兑现:resize。尺寸变化只是把 fullRedraw 置真,代价是 \x1b[2J + 重画一屏 height 行(tui-alt-screen.ts:1270-1276)。没有 3J,没有历史重印,没有 I/O 爆发。主屏那条路的“核平“在这里是 O(屏高) 的平价操作。第 13 篇说全屏自管派的 resize 成本是 CPU 且量级是一屏,这里是逐字的证据。

3.2 补齐清单:终端免费给的,全部自建

第 13 篇说 inline 派“终端免费给的能力“是现成的便利,反过来说,全屏派要把这些能力一件件自己补回来。这份清单在 tui-alt-screen.ts 里一项项都看得见:

  • 滚动:ScrollView 抽象(scrollTop、follow: "end"、overscroll: "contain"),而且是嵌套滚动,滚轮事件按坐标在布局树里命中测试,命中最内层 ScrollView,滚不动的余量溢出给外层(routeWheel)。这是 GUI 的 nested scroll view 语义,在字符网格上重建了一份;
  • 搜索(Ctrl+Shift+F):匹配在数据层做(对完整文档行全文查找),高亮在绘制层做,applySearchHighlights 把命中文段从渲染好的行里切出来、包上样式、再拼回去,数据一个字不动。跳转有 anchor 保持和 next/previous 环绕;
  • 选择复制:alt screen 里终端的原生选择是废的(你在不停重绘),于是实现了应用级选择:SGR 鼠标事件、单击拖选、双击选词、三击选行(getClickCount 按 500ms 窗口计次)、拖到视口边缘 50ms 定时器自动滚屏、反色高亮同样是绘制层拼接(还会小心地保留原行的 ANSI 序列)、松手时 OSC 52 写系统剪贴板。这一段占了文件将近一半的行数;
  • 语义锚点(OSC 133):transcript 的消息带着 OSC 133 区域标记下发,绘制时剥掉,但滚动导航用它实现“上一个/下一个 prompt“跳转,用终端的 shell 集成协议,给应用级滚动加了语义站点。这个设计我觉得是全文件最巧妙的一笔;
  • kitty 图片预算缓存:滚出视口的图片不删会泄漏终端显存,于是屏外缓存带预算上限(16 张 / 32MB 传输字节 / 64MB 解码字节),超预算逐出。

还有一处环境妥协值得记:鼠标默认开全量移动追踪,但检测到 tmux/zellij/screen 就降级为“仅按键时追踪“,复用器转发鼠标事件会卡。每补回一项免费能力,都要多付一份兼容性成本。

3.3 最妙的一笔:退出时归还 scrollback

afterTerminalStop(305-328 行):全屏模式退出时,把整个文档重新打印回主屏,逐行 \r\x1b[2K + 内容,写完 \r\n 收笔。

效果是:会话期间历史归应用(可滚动、可搜索、可选择、resize 免费),退出之后历史落进终端原生 scrollback,用户照常往上翻、Cmd+F、用终端自己的选择复制。

第 13 篇的两派在这里出现了第三种所有制:

实现会话期间会话结束后
inline 派(Claude Code 的默认,Codex、Grok Build 的 inline 模式)历史归终端归终端
ForgeLoopTUI(我的)历史归引擎留在主屏,但无干净归档(全量重印会把陈旧副本顶进 scrollback);内存模型随进程蒸发
Kimi Code alt 模式历史归引擎归还终端

生前归自己,死后归终端。 运行期享受全屏自管的全部自由,退出时把历史整个交还给介质本身。两派的优点被串行地各取了一段。


四、这个案例对本系列意味着什么

1. 上一篇的分界线被复用了,但没有被推翻。 那条分界是真实的结构,真实到四家的开关都压在同一条线上,而 Kimi Code 是在同一个接口后面把两边都实现得最完整的一个。默认主屏(inline 派)说明:对一个要集成进用户日常终端的 CLI,“历史归终端“仍是站得住的默认答案(第 13 篇的记分牌上,四家有两家这么选);实验性全屏说明:会话内体验(滚动、搜索、选择、resize)的诉求强到值得再养一套引擎。

2. inline 派内部要分两档。 第 13 篇把 inline 派写成一种做法(发射即定型),Kimi 主屏的差分变种给出了第二种:全量渲染 + 增量落盘 + 越界检测 + 核平兜底。两档的不变式相同(scrollback 不可触碰),但维持不变式的方式一个是数据层纪律、一个是渲染层检查。第 13 篇的框架可以据此再细分一档。

3. 我那派的“补齐清单“有了工业参照。 第 2 篇我写的是引擎的渲染核心;Kimi 的 alt 模式展示了渲染核心之外,把一个全屏 TUI 做到产品级还需要什么:嵌套滚动、应用级选择、数据层搜索、OSC 133 锚点、图片显存预算、复用器降级。每一项都是“终端免费给的“对照项。

4. “退出归还 scrollback“是一个新的架构选项。 它回避了两派各自最难堪的时刻:inline 派在会话中无法提供可交互的历史,全屏派在退出后把历史带走。串行混合(运行期自管、终态归还)让“所有权“从一个静态选择变成了一个随生命周期变化的转移过程。如果 ForgeLoopTUI 未来要解决“退出后没有干净归档“的问题(它跑在主屏,退出后最后一帧仍在屏幕上,但全量重印顶进 scrollback 的陈旧副本让那份记录不可用),这是可以直接借鉴的范式。


五、总结

上一篇的结论是:两派没有高下,是同一条公理(终端没有 undo)的两种成本结构。而本篇通过分析 Kimi Code 这个案例把结论往前推了一步:既然只是成本结构不同,就可以按生命周期分阶段承担。

运行期,把历史留在自己手里,承担“自建滚动/搜索/选择“的代价,换来可交互的会话;退出时,把历史打印回 scrollback,承担一次“全量重印“的代价,换来用户终端里的完整记录。甚至同一个引擎里还可以再备一套 inline 差分实现,承担“核平兜底“的代价,作为默认模式的日常形态。

所有权模型因而从一道单选题变成了一份调度表:什么东西、在什么阶段、归谁管,每个问题都可以单独回答。介质还是那个只进不退的电传打字机,但和地基的关系,比上一篇设想的还要再自由一点。


参考与延伸

  • 本文基于 Kimi Code 源码的实际阅读:packages/pi-tui/src/tui-main-screen.ts(主屏差分渲染器)、packages/pi-tui/src/tui-alt-screen.ts(全屏渲染器)、apps/kimi-code/src/tui/tui-state.ts(模式选择)、packages/pi-tui/AGENTS.md 与两处 CHANGELOG(fork 分歧与事故史)。行文时 Kimi Code 版本为 commit 1e553fc(2026-08-18)。
  • ForgeLoopTUI 的退出行为核对基于其 v1.2.0 源码:主屏渲染,无 alt screen,无退出时清屏/归还逻辑。

一行状态文字的状态机

前面各篇讲的都是“大”问题:渲染所有权、双模、事件树展平。这一篇讲一个“小”东西:状态行。每个人都写过 spinner,没人写过“什么时候显示什么、什么时候必须消失”。它的难点不在动画,在防闪烁。


一、状态行的两种所有权

第 4 篇讲过 ForgeLoopTUI 的 operationStart/operationEnd:工具开始时追加一行“⎿ running…“,工具结束时用结果行替换它。状态行的所有权属于那个工具:它因事件而生、因事件而灭,生命周期和一次工具调用对齐。

Codex 的状态指示器是另一个物种。它的所有权属于整个 turn:从回车到 turn 收敛,不管中间经过几次工具调用、几段流式输出,底部都是同一个指示器实例,显示的内容在变(“Thinking”/“Working“加一行细节),实例不变。它从不被“结果“替换,只会被流式内容压制,然后再被恢复。

这个区别决定了后面一切。被替换的状态行不需要状态机,它的生灭就是事件本身;被压制和恢复的指示器需要状态机,因为压制和恢复的时机全是边界条件。


二、reasoning 不进 transcript

第一个设计有点反直觉:reasoning(模型的推理流)不进 transcript。

Codex 的 ChatWidget 收到 reasoning delta 时只往一个 buffer 里累积,然后从 buffer 里提取第一个 **加粗** 片段,作为状态行的标题显示。模型在推理块里写的“我先分析用户的需求“这类句子,只有被加粗的那一句能登上状态行;整个推理过程在 transcript 里不留痕迹(推理块结束时只落一条摘要记录)。

配套的降级同样是静默的:如果 buffer 里还没有出现加粗片段,就保持现有标题不动,不显示“正在提取标题“之类的中间态。还有一条优先级细则:如果正在等一个 unified exec 的结果,执行等待的状态优先于推理标题,后者直接让位。

这套“从内容里蒸馏状态“的做法,把状态行从“系统播报“变成了“内容摘要“。它还顺带决定了终端窗口标题:Thinking 和 Working 两种状态会映射到窗口标题上,用户在标签页或窗口列表里就能分辨 agent 是在想还是在动手。状态行的信息层次因此是:窗口标题 < 状态行标题 < 状态行细节,同一状态的三档投影。


三、防闪烁三闸门

状态行和流式内容共享同一块屏幕底部区域,两者共存会闪:一帧里既有新放行的内容,又有“正在工作“,视觉上就是抽搐。Codex 的解法是三道相当保守的闸门。

闸门一:放行即隐藏。
commit tick 每向 transcript 放行一批行,第一件事就是隐藏状态指示器。流式内容与状态行互斥,没有例外路径。

闸门二:恢复看空闲。
一段 commentary(前言性输出)结束时,不立刻把状态行放回来。先置一个“待恢复“标记,然后等三个条件同时成立:turn 还在运行、两个流式队列(回答流与计划流)全部 idle、标记置位,才恢复。缺任何一个条件就继续压着。没有这个闸门,“前言结束→工具即将开始“的间隙里状态行会闪现一下又被压掉,形成“显示→隐藏→显示“的三连闪。

闸门三:收尾看队列。
最终回答完成时,状态行是否恢复,取决于输入队列里有没有用户插进来的 steer 消息。如果用户已经插了话,turn 马上又要忙起来,恢复那一帧就是多余的闪烁,所以不恢复,直接保持隐藏等下一波。

三道闸门串起来的判断标准是同一个:状态行的每一次显隐都必须对应用户心智模型里的一次真实状态切换,任何“技术上正确但感知上是噪声“的显隐都要被闸门吃掉。


四、中断偏序:另一条隐藏的状态机

还有一个相邻机制值得在这里记一笔。流式写入进行中,ExecBegin/ExecEnd 这类生命周期事件不允许立刻上屏,而是先进一个 FIFO 队列延后,等流式写入的空窗再处理(defer_or_handle)。

理由和防闪烁同源:状态区与流内容如果交错落笔,两者的时间线都会乱。生命周期事件是状态,流式内容是正文,正文正在流动时,状态必须排队。这等于承认了一个调度原则:底部状态区同一时刻只许一个写者落笔,两个写者之间用偏序关系串行化,而不是靠运气。


五、动画是自驱动的

最后一块拼图是帧从哪来。spinner 不需要等内容事件,它在自己的渲染里通过 schedule_frame_in 主动预约下一帧(有动画时约 32ms 后,只有计时器时 1 秒后);shimmer 那道扫过文字的渐变高光同理,是按已流逝时间计算的纯函数。第 9 篇补记讲的全局帧调度只管内容放行,状态行动画自请帧,两条帧请求线在同一个渲染循环里合流。

这也是状态行与第 14 篇提过的 spinner 细节的对照点:Kimi 的差分渲染器把“只有一行变化(例如 spinner 动画)“列为最小化重绘的显式动机。状态行是 TUI 里唯一合法的高频自更新区域,所有为它服务的机制(自请帧、单行重绘、闸门防闪)都在回答同一个问题:怎样让唯一会动的东西安分地动。


六、总结

写 spinner 只要半小时,写状态行的状态机要付出的代价全在边界上:放行与恢复的互斥、显隐的时机、多写者的偏序、动画的帧来源。这行文字的复杂度不在它显示什么,在于它什么时候不该显示。

这也是我读完 Codex 这部分源码后修正的一个直觉。我原以为状态指示是“锦上添花“层,属于打磨;看完三闸门才意识到它是 turn 生命周期在用户侧的投影:turn 的每个相位迁移(推理、输出、工具、等待输入)都必须在这行文字上有唯一确定的显示状态,不多不少。一帧里出现两个状态,或一个状态出现两帧,都是 bug。 这个标准比一般 UI 组件苛刻得多,而它是 agent TUI 的日常。

下一篇讲测试:这样的状态机、连同前几篇讲的所有渲染机制,怎么被钉在回归测试里。TUI 的输出是带状态的字节流,断言它需要一整套基建,一两个技巧不够。


参考与延伸

  • 本文基于 Codex 本地源码 2026-10-04 的逐行阅读:codex-rs/tui/src/chatwidget/streaming.rs(reasoning 标题提取、防闪烁三闸门、defer_or_handle)、status_indicator_widget.rs(schedule_frame_in 自请帧)、shimmer.rs(渐变高光)、streaming/commit_tick.rs。
  • 对照部分基于 ForgeLoopTUI v1.2.0 的 operationStart/End 机制(见第 4 篇)。
  • 快照 main 6b9826e3(2026-09-09);行号可能随上游漂移,机制名稳定。

把 ANSI 变成可断言的——TUI 回归测试基建

前面讲了 TUI 渲染的各种机制:增量 diff、流式 Markdown、holdback、防闪烁,这一篇回答一直悬着的问题:这些东西怎么测?TUI 的输出不是返回值,是一串带状态的字节。2026 年 10 月读 Codex 的 TUI 测试代码,我看到的与其说是一批测试,不如说是一套方法论:把“带状态的字节流”逐层翻译成可以断言的东西。


一、难在哪:输出是带状态的字节流

普通函数的测试断言输入输出。TUI 渲染的“输出“是写到终端的字节序列,它的含义依赖于终端的当前状态:光标在哪、哪些模式开着、scrollback 里有什么。同一个字节序列,光标位置不同,结果完全不同。第 2 篇讲过帧状态记忆的脆弱性:8 个字段任何一个算错,整帧偏位。这类 bug 的特征是:单看任何一帧的字节都对,连起来就错。

所以 TUI 测试首先要回答的问题,排在“断言什么“前面:把输出变成什么形态才可断言。这里我推荐参考 Codex,它的实践可以分成四层,从字节到纪律,一层比一层抽象,一层比一层便宜。


二、四层断言

2.1 字节层:MockTerminal 接住一切

最底下是字节断言:用一个 VT100 模拟终端接住引擎真实发射的字节,然后断言“进了 scrollback 的字节是什么、清了几次屏、flush 了几次“。第 13 篇提过 tests/suite/vt100_live_commit.rs,那就是这一层的样本。这里要防一个误读:Codex 默认走全屏,vt100_live_commit 钉的是它内置的 inline 降级路径(insert_history.rs)。第 13 篇的记分牌是 2:2 加全员双模,“发射即定型“的纪律不分阵营,最终都得靠字节级断言钉死。

这一层的特点是贵而硬:每个用例都要构造终端状态、喂事件、检查字节行为。它适合钉契约级的行为(“commit 区的字节绝不重复发射”),不适合铺满全部功能。所谓契约级,就是一旦违反,击穿的是渲染模型本身:commit 字节重复发射,scrollback 就被永久污染。终端没有 undo,没有任何下游机制能补救,这种错只能在构建阶段拦下。

2.2 快照层:insta 与归一化

往上一层是快照。Codex 的 TUI 里有一个庞大的 insta 快照库:tui/src 下散落着八百多个 .snap 文件,chatwidget、streaming、markdown 渲染、bottom pane 各有自己的 snapshots 目录,配一个 TestBackend 把帧渲染成文本形式入库。第 13 篇提过的 zellij_raw_terminal_wrap_above_viewport.snap 就出自这里:冷门终端复用器的换行行为,被一条快照永久钉住。

快照的死穴是抖动:任何无关变化(时间戳、随机 id、路径)都会让快照失败,失败多了审查者就会习惯性 accept,快照随之失效。所以快照层必须配一层归一化:动态值掩码成占位符,快照只固化结构和关键语义。Codex 在 core 侧的测试里把这件事做得很彻底:请求快照入库前,权限说明、环境上下文、压缩 prompt 等大段注入全部替换成占位符,UUID 与时间戳掩码,JSON 先排序 key,快照只固化“结构形状“,prompt 文案微调也不会抖动。没有归一化层的快照不如不写。

2.3 等价性层:断言不变量,不断言帧

第三层是我认为最有普适价值的一层,也是这个系列里第一次出现的断言形态:不逐帧断言输出,断言一个不变量。

流式渲染的正确性可以被一句话钉死:任意 delta 切分下,流式渲染的可见输出必须收敛于一次性全量渲染。 切分方式是无限的,逐帧断言永远覆盖不完;但不变量只有一个。Codex 的 streaming 模块里有一批这样的等价性测试:

  • controller_loose_vs_tight_with_commit_ticks_matches_full:token 级 delta 逐帧放行,与整段一次渲染,最终输出必须相等;
  • controller_live_view_matches_render_during_interleaved_table_streaming:在表格穿插的流式过程中,每个 delta 之后都断言“已上屏内容 + 待放行 tail“恒等于全量渲染,第 3 篇补记讲的 holdback 机制,正确性就是这样被全程盯住的;
  • incremental_holdback_matches_stateless_scan_per_chunk:增量状态机(每 delta 推进)与非增量的全量扫描函数,逐 chunk 结果必须相等。同一个扫描逻辑写两遍,互为预言机。

注意最后一个测试的手法:用实现验证实现。增量扫描器是为性能写的,全量扫描是为正确性写的,两者互相作对方的 oracle。这种“双实现互证“比任何固定预期值都难造假:bug 必须同时以同样的方式污染两份独立实现才能漏网。

2.4 守护层:纪律进构建

最上面一层防的不是 bug,是架构退化。第 13 篇详细讲过 Grok 的 guard.rs:用 include_str! 扫描全部源码,断言 minimal 模式里不出现 emit_to_scrollback 这类标识符,口头纪律由此升级为挂了就算构建失败的测试。Codex 有同构物:alternate_screen_auto_uses_alt_screen 把“Zellij 特判已删除“之后的新行为钉成测试。功能错误自有功能测试去抓,它防的是有人哪天把特判加回来。

守护测试的价值随代码库年龄增长。功能测试保护“现在对“,守护测试保护“对的结构不被未来的善意修改破坏“。第 13 篇那句“纪律比天才便宜“,在构建系统里的字面形态就是这一层。


三、测试密度的代价

这套基建的规模值得量化一下。streaming/controller.rs 一共 1976 行,其中约 1200 行是测试——被测逻辑与测试的体积比接近 2:3。密度花在哪儿很说明问题:resize 与 partial drain 的组合有约十个专测,覆盖丢失、重复、换行余量三类回归,每类都有专名。这些是流式渲染历史上真实坑过人的 bug 类型,每一个都进了专名测试。

这也向我们回答了“值不值“的问题。流式渲染的正确性涉及时序、布局、状态机的组合爆炸,人工回归不可能覆盖;而一旦基建就位,等价性层的单个测试能顶掉一整个手工测试矩阵。测试在这里从成本中心变成了让“事前状态机“这类精巧设计敢存在的前提:没有等价性测试盯着,任何后来者的“优化“都可能悄悄破坏收敛性,而且没有人会发现。


四、总结

回头看,这个系列里关于可测试性的判断一直是散点:第 2 篇列举 CLI/TUI 优势时提过“管道可测试“,第 13 篇把可测试性列为 inline 派的优点之一(“系统越聪明,证明它正确的基础设施越贵”)。而把这个优点兑现得最彻底的,反倒是默认全屏的 Codex:双模产品的测试成本要付两份。Codex 的四层实践把这些散点收成了一个框架:

字节断言  →  钉契约(贵而硬,只钉关键行为)
快照      →  钉形态(配归一化,防抖动失效)
等价性    →  钉不变量(一次断言,覆盖无限切分)
守护      →  钉纪律(防架构退化,随年龄增值)

四层的共同主题是翻译:把不可断言的(字节流、时序、纪律)逐层翻译成可断言的(字节计数、文本快照、不变量、标识符)。

对我自己的评测工作,这套基建还有一个反向启发。评测注入故障想测出 UI 层缺陷,等价性层指明了最敏感的注入点:delta 切分方式。同一个模型输出,按 token 切、按行切、按随机字节切,收敛性不变量任何一个被破坏,就是渲染层的真 bug。这等于把“流式“这个变量本身变成了故障注入的旋钮。测试基建与故障注入,在这里是同一件事的两面。这个启发本章只立旗,评测卷第 14 篇展开,那里会给等价性层一个正式的名字(蜕变测试),并把“同一件事的两面“这个判断坐实。


参考与延伸

  • 本文基于 Codex 本地源码 2026-10-04 的阅读:codex-rs/tui/src/streaming/controller.rs(等价性测试与 resize×drain 组合专测)、tui/src/**/snapshots/(insta 快照库)、tui/src/test_backend.rs、tests/suite/vt100_live_commit.rs、lib.rs(alternate_screen_auto_uses_alt_screen),快照 main 6b9826e3(2026-09-09)。
  • Grok Build 的 guard.rs 转述自第 13 篇的既有分析(commit 9fabade,2026-08-16 阅读)。

回到自己的引擎——ForgeLoopTUI 改造实录

拆完别人的引擎,这一篇回到自己的:八月中的审计给 ForgeLoopTUI 开过一张七件套的“吸收清单”,这是两个月后的清点报告。先说结论:执行情况有点难堪,但清单外发生的一件事比整张清单都重要。为了修第 3 篇那套稳定前缀缓存带出的“弹入”问题,我的引擎在默认应用路径上,往对面阵营走了一半。


一、先清点:七件清单,落地零件半

审计表原样重跑一遍(对照 8 月 19 日的审计记录):

工程件审计判定现状
无操作抑制✅ 已有✅ 不变
suspend/resume 几何重置✅ 已有✅ 不变
渲染合并❌ 缺⚠️ 仍是半件:引擎里 RenderLoop(16ms 合并 + immediate 双优先级,2026 年 5 月就有)始终没接进流式路径,token 到达仍然直呼 render(),缺的从来是接线,不是零件
DEC 2026 同步输出包帧❌ 缺❌ 未动
SIGWINCH 事件化 + 去抖❌ 缺(轮询)❌ 未动,仍每帧比对 getTerminalSize()
width-1 留列❌ 缺❌ 未动
forceRepaint 逃生舱⚠️ 半有⚠️ 原样:有内部 fullRedraw 诊断,无公开 API

那这两个月干了什么?8 月 28 日到 9 月 1 日,五天,61 个提交。清单之外的地方:Markdown 表格单元按词换行(三连修)、嵌套列表缩进保真、代码围栏标签泄漏、宽度歧义字符、括号粘贴模式、kitty 键盘协议、OSC 8 超链接、Python 高亮。再往后是这一篇的主角。

为什么清单没动,不是忘了。七件件件正确,但件件属于“引擎更对“;而这段时间用户可见的缺陷全在渲染质量和输入协议上,它们赢了排期。工程排期的实际顺序往往是缺陷在前、正确在后,这一点没什么可辩护的,记录在案。

二、清单外的那件事:把“提前发射“搬进全屏引擎

第 3 篇拆过的 Stable Prefix Cache,在示例 app 里带出一个观感问题:只有引擎认证“稳定“的行才进正式布局,于是流式观感是整块内容在稳定后一次性弹入。inline 派没有这个问题,它们不等稳定,内容到了就发射进 scrollback,反正发射即定型,视觉上永远是渐进生长。全屏派赢回了原地改写的能力,代价是丢掉了“逐行可见“。

8 月 30 日的 TASK-27/28 是正面解决这个困境的一次尝试,做法是把 inline 派的核心策略搬进来:

不稳定尾部预览。 活跃流式块里,越过引擎认证稳定前缀的那些行(还没定型的尾巴),作为 tui.render(committed:live:) 的 committed 区参数原地预览,于是 Markdown 在流式期间逐行出现,不用等稳定后弹入。行一旦被引擎认证稳定,就离开预览、落进正式历史。

三步定稿序列。 预览行转正的时刻是危险时刻:既要把新稳定行写进历史,又不能和历史区、预览区的既有内容打架。方案被钉成一个固定序列:

1. 空渲染擦除 in-place 区        tui.render(committed: [], live: [], cursorOffset: 0)
2. appendFrame 落历史            tui.appendFrame(lines: 新稳定行)
3. 重绘剩余预览 + live 区        tui.render(committed: 剩余预览, live: …)

并且立了铁律:永远不要在完整帧之后直接 appendFrame。

这条铁律有出处。TASK-27 是测试先行的,只写测试不改库。CommittedPreviewAnchorTests 造了一个预言机:ScrollbackTerminal,实现了真实终端语义(deferred wrap、宽字符、底部滚动入 scrollback,覆盖 TUI 输出的全部 ANSI 子集),每个 API 调用后断言屏幕与 scrollback 和“期望内容物理换行后的尾部“逐行一致。S1–S5 场景验证 erase→append→redraw 在各种组合下锚定正确;S6 是一个专门的探针,故意钉住直连序列的缺陷形状:满帧后直接 appendFrame,结果是永久性的窗口偏移加陈旧绘制补位。把“为什么要先擦“从一条经验升级成了一道回归约束。

还有一个归属细节值得记:StreamingTranscriptAppendState(维护“哪些行已落卷轴、哪些未定稿“的增量状态机)放在 Sources/ForgeLoopTUI/Transcript/,在引擎里,不在示例 app 里。合流是引擎级的决定,app 只是消费者,现在有两个消费者:MinimalAIApp 和 dsh-tui(dsh 是 deepseek harness 的缩写),两者帧模式一致。

三、这件事在所有权坐标系里意味着什么

盘点一下新稳态。一条回复流式期间:不稳定尾巴 + 状态栏 + 输入框,归引擎原地管;行一旦稳定:appendFrame 写进终端原生 scrollback,从此滚动、回看、复制都是终端的事,引擎脱手。

把这个状态放到第 14 篇那张三行所有权表里:

实现会话期间会话结束后
inline 派(Claude Code 的默认,Codex、Grok 的 inline 模式)历史归终端归终端
ForgeLoopTUI(第 14 篇时的判断)历史归引擎无干净归档
Kimi Code alt 模式历史归引擎归还终端
ForgeLoopTUI app 路径(8 月 30 日后)稳定一行,归还一行已在 scrollback

比 Kimi 的“退出时归还“更早:不是终态一次性移交,是逐行移交。第 14 篇的结论是“所有权的代价可以按生命周期分阶段承担“,现在“会话期间“内部也可以再分阶段了,稳定的程度就是所有权的边界:每行内容在它被认证稳定的那个瞬间,从归引擎管变成归终端管。

但要说清楚:引擎没有换阵营。窗口化全帧 API 原样保留,AppKit 桥、全屏路径都在,另一个 app 仍然可以选“历史全归引擎“。引擎做的事是提供了两种语义(原地帧 + 发射通道)让 app 自选,这恰好是八月审计里一个遗留问题(历史持久化路径待确认,实为 API 设计问题)的答案,也顺带回答了当时悬而未决的一个 API 决策:要不要提供 commit(_:) 一等沉降语义?实践给出的答案是已经有了,appendFrame 就是 commit 通道,差的只是把它作为一等语义写进文档和 README 的选择指引。挂了两个月的问题,被一次修 bug 顺手回答了。

四、混合模式的代价

第 13 篇推导过 inline 派的代价。混合模式并不豁免,反而多了一种新代价。9 月 1 日的 TASK-37,就是它第一次找上门。

事故:inlineAnchor 超屏回退路径复用了 renderLegacy:ESC[2J 清屏后从 home 重写整帧。当 committed+live 超过终端高度,重写本身就会滚屏,把帧的顶部行顶进 scrollback;而流式预览是每个 chunk 重渲染一次,于是同一张表格在 scrollback 里落地了几十次,连原始的管道符都在。更糟的是 iTerm2 风格终端上,擦除帧的 ED2 会把清掉的内容存一份进 scrollback,每个 chunk 存一份上一次预览的副本。第 3 篇的“表格地狱“以成倍复制的形态在 scrollback 里重现。

修复的原则比细节重要:回退路径改为只原地渲染帧的底部 terminalHeight 物理行:CUP 到窗口原点 + ESC[0J(局部擦除,无 scrollback 语义)、整行窗口选择、到底行后不再尾随换行。它永不滚屏,所以瞬态预览永远到不了 scrollback。commit message 里有一句话值得原文引用:

appendFrame remains the single channel for permanent history.

(appendFrame 是永久历史的唯一通道。)这就是 inline 派“发射即定型“纪律在混合模式里的对应物,只不过它管的方向反过来:inline 派用它约束“不许碰已发射的历史“,这里用它约束“不许从别的门进历史“。同一句纪律,两种所有制下各管一边。

配套的是一个计数器:unretainedAppendedRows,appendFrame 写下、但还没被任何 retained 帧接管的光标行数。有了它,erase→append→redraw 序列里万一发生超屏重绘,重绘从新追加历史的下方开画,而不是从 home 把刚 append 的行覆盖掉。回归测试的口径也很硬:118×12 终端、7 字符 chunk、帧模式与两个消费者 app 完全一致;断言整场流式期间 scrollback 保持为空、| --- | 永不出现、Kubernetes 哨兵词恰好出现一次。

这个事故值得单独定性:它不是第 13 篇 5.2(resize 核平误伤 scrollback)的复读,诱因不是 resize,是回退路径 × 混合所有权的乘积。单一所有权下不存在这类 bug:历史全归终端时没有“回退重写“,历史全归引擎时没有“scrollback 污染“。第 14 篇说每种所有权都要付出代价;这里补一条:分阶段承担代价,本身也是一种代价,两条通道并存的那一刻,就要为“别让内容走错门“付出工程量。

五、总结

两个月,五天里的 61 个提交,七件清单落了半件,但引擎完成了一次跨阵营的半程:全屏自管的引擎,长出了一条逐行归还 scrollback 的通道,配上了一个真实终端语义的预言机、一道“唯一之门“的纪律,以及一套跨通道的状态核对。

第 13 篇结尾说过,ForgeLoopTUI 的 committed 区在语义上已经是 append-only,和 inline 派的 scrollback“只差最后一步:物理上还归不归我管“。这一步现在有了答案的形状:物理归属不再由引擎统一决定,由每一行内容在稳定瞬间自己决定。所有权从引擎的出厂设置,变成了内容级的调度表。

下一篇(第 18 篇)把这套历史管理带出终端:GUI 和移动端没有 scrollback 这回事,没有免费的历史基础设施,每一行从诞生起就必须有人管。FlowDown 是那边的样本。


参考与延伸

  • 本文基于 ForgeLoopTUI 本地仓库的实际阅读:HEAD f99367b(2026-09-01),覆盖 2026-08-28 至 09-01 的 61 个提交;关键证据为 Examples/MinimalAIApp/Sources/MinimalAIApp/main.swift(render() 的预览切片与三步定稿)、Sources/ForgeLoopTUI/Transcript/StreamingTranscriptAppendState.swift、Tests/ForgeLoopTUITests/Runtime/CommittedPreviewAnchorTests.swift(ScrollbackTerminal 预言机与 S1–S6)、Sources/ForgeLoopTUI/Runtime/TUIRuntime.swift(TASK-37 的 unretainedAppendedRows 与底窗回退)、Sources/ForgeLoopTUI/Runtime/RenderLoop.swift(2026-05-07 引入的 16ms 调度器)。
  • 性能类实测数据(帧字节数、resize 耗用对比)尚未采集,本篇以行为学证据(oracle 断言)替代,数据缺口留待补记。

终端之外——渲染所有权模型在 GUI 与移动端的映射

“所有权”四部曲的收官,这一篇把模型带出终端:macOS 的窗口、iPhone 的屏幕没有 scrollback 这回事。当介质不再附赠历史基础设施,第 13 篇那套历史怎么管?样本是 FlowDown,一个原生 iOS Agent 客户端。


一、GUI 世界里,inline 派不存在

第 13 篇两派成立有个前提:终端这个介质提供了两个可以存放历史的地方,你自己管理的帧,和终端的原生 scrollback。inline 派的核心是把历史托付给介质:发射进 scrollback,从此滚动、搜索、复制都归终端管,引擎脱手。

GUI 没有这个托付对象。窗口是你画的,滚动区是你实现的,系统递给你一块随时会被回收的画布,仅此而已。

所以第 13 篇那张 2:2 的记分牌,在 GUI 世界塌缩成一行:全屏自管是出厂设定,别无分店。Grok Build 默认形态那套“应用自管 scrollback“,在 GUI 语境里就是唯一解。

但要说清楚:所有权问题没有消失。它只是换了一层皮。

二、像素与数据:两种速朽,两种不朽

把两个介质摆在一起看,会看到一组精确的镜像。

终端:像素不朽,数据易逝。 一行内容发射进 scrollback,终端模拟器替你保管它的像素,直到用户清屏;而引擎内存里的数据模型,进程一退就蒸发。第 14 篇记过 ForgeLoopTUI 的窘境正是这个:历史活在屏幕上,内存模型随进程蒸发,退出后没有干净归档。

GUI:像素速朽,数据必须不朽。 屏幕外的 cell 被回收,视图层级随时重建,前后台切换、内存警告、任何一次转场都可能让像素归零;而数据没有任何介质替你保管,你必须自己建库,一条对话不落盘,就等于没发生过。

于是第 13 篇的那个问题(“一个 block 完成之后,谁继续管它”)在 GUI 上被改写成另一个问题:已完成的内容存到哪、什么时候存。所有权从像素层下沉到了数据层。第 7 篇讲 Event Sourcing 时说事件流是“好架构“;在 GUI 端,它从“好架构“变成了生存必需:没有那份数据,连“刚才聊了什么“都无处可查。

三、FlowDown 的历史管理

空谈不如看代码。FlowDown 的历史管理拆成三件:入库、窗口化、定稿。三件都有源码。

3.1 入库:连解析产物都要持久化

FlowDown 的存储在独立框架 Frameworks/Storage,底座是 WCDB(微信开源的 SQLite 封装,wcdb-spm-prebuilt)。三张核心表:Conversation、Message、Attachment。

Message 的字段设计值得逐条看(Storage/Tables/Message.swift):

  • document: String:消息原文;
  • documentNodes: [MarkdownBlockNode]:解析后的 Markdown 节点树,直接入库。Storage 框架为此依赖了 MarkdownView 的解析器包。也就是说,不光事实要持久化,渲染管线的中间产物也持久化了;
  • reasoningContent + thinkingDuration + isThinkingFold:思考内容和它的展示状态一起记;
  • removed: Bool、modified: Date、deviceId:软删除标记、修改时间戳、多设备同步字段。

对照终端:终端里历史可以只以像素形式存在(数据模型可有可无,Grok 的 minimal 模式就只留够重印用的);FlowDown 这边正相反,像素一张都不存,全部历史以记录形式活着。

3.2 窗口化:像素只租给可见的十几行

聊天主界面 MessageListView 建在 ListViewKit 上:ListViewDiffableDataSource<Entry> 做增量更新,配一条专用队列(userInteractive QoS)串行化 UI 变更,订阅 session.messagesDidChange 驱动整条管线。

屏幕之外没有像素。滚出视野的消息行,数据还在 messages 数组和 WCDB 里,cell 本体已经进了复用池。终端里“历史以像素形式活在 scrollback“,GUI 里“历史以记录形式活在库里,像素只租给可见的那十几行“,第 13 篇全屏自管派“引擎为每一行持续负责“的图景,在 GUI 上由框架代管了:UIKit 管回收,你的 diffable data source 管内容。

3.3 定稿时机:几何问题的生命周期版本

第 13 篇说过 inline 派的关键转变:“什么时候算定型“从几何问题变成了生命周期问题。这句话在 GUI 换了个对象重新成立:定型问题变成了落盘节奏。

FlowDown 的实际节奏(ConversationSession 与 Pipeline/Execute/):

  • 消息建档即入库;
  • 流式热路径上,chunk 到达只更新内存里的消息对象(message.update(\.document, ...))并刷新 UI 投影(requestUpdate(view:)),每 chunk 是否写库不在热路径上;
  • 流结束后的修补序列才是定稿点:网页引用回填(fixWebReferenceIfPossible)、空回复静默丢弃(discard)、工具调用参数修复(ToolCallArgumentRepair),修补完,在生命周期节点统一 save()(save() 就是 sdb.messagePut(messages:) 批量落库,调用点分布在 CRUD、压缩、重写和管线末端)。

“几何问题变生命周期问题”,在终端管的是像素何时发射,在 GUI 管的是记录何时落盘,同一原则,两层实现。

四、租借投影与“归还“的变形

第 14 篇给 Kimi Code alt 模式写过一句“生前归自己,死后归终端“。这句话在 iOS 上的变形,FlowDown 给了两个现成样本。

运行期的租借投影。 流式输出每收到新文本,ConversationSessionManager.countIncomingTokens 累计增量,喂给 Live Activity,锁屏和灵动岛上有一个实时跳动的字数投影。这是把投影租给锁屏一块:运行期存在,会话结束收回。第 11 篇说“每个端只消费自己适合的事件子集“,锁屏消费的是最极端的子集:一个字数。

身后的归档。 iOS 应用没有“退出仪式“可依赖,进程随时可能被杀,不会有 goodbye 回调。Kimi alt 退出时把历史打印回 scrollback,那份“归还“之所以可能,是因为终端这个介质还在;iOS 上唯一的长寿介质是磁盘(和云),所以“归还“只能变形为“落盘“,而且必须随时可发生。持久化在移动端不是功能项,是生存方式。被杀那一刻历史是否完整,取决于上一个定稿点落在哪里,这正是基建卷要展开的话题。

顺带一提,冷启动的 refreshContentsFromDatabase 就是 GUI 版的“追平“:listMessages 全量读库重放,投影从事实源重建。基建卷里要用快照 + 尾部增量才能做对的那道题,本地 SQLite 快到不用优化,动作是同一个动作,成本差了几个量级。

五、总结

四篇的所有权问题放进一张表:

历史存于定稿时机退出/被杀时介质附赠
终端 inline 派终端 scrollback(像素)block 生命周期完结即发射历史本来就在终端scrollback 滚动/搜索/复制
终端全屏派引擎(像素+数据)无定稿,持续维护看实现:ForgeLoopTUI 无干净归档,Kimi alt 模式退出时归还(第 14 篇)无
终端混合(14 篇)稳定行→scrollback,未稳定→引擎行级:认证稳定即归还已在 scrollbackscrollback(部分)
移动 GUI(本篇)数据库(数据),像素仅租借生命周期节点落盘磁盘是唯一长寿介质无,UIKit 回收也有代价

四行连起来读:终端之争争的是“这些内容归谁管“,答案是开关和分阶段移交;GUI 没有这场争论,它的题目直接写在数据层:什么算定型、什么时候落盘、被杀时历史完不完整。渲染所有权的尽头是数据所有权,也就是第 7 篇那条事件流的必然形态。

再往高一层:两种介质各附赠什么

四部曲讲的是“历史“这一件事。把镜头拉远,两种介质的差别其实是同一个结构的重复:每种介质都附赠一些东西,同时让另一些东西代价很高;没有一方全面优越,只是两边赠的东西恰好互补。

维度终端GUI
已发射的历史附赠:进 scrollback 即归档,进程死了也在代价:像素随进程死,落盘是生存必需(本篇)
遮挡与切走再回来代价:重连即失忆,全屏应用要整页重绘附赠:合成器持有像素,不用应用重画
分发与可达附赠:SSH、tmux、CI、管道,任何机器代价:安装包、跨端、版本兼容
输入带宽代价:只有字节流,行级采纳、并排 diff 全要手搓附赠:命中测试、多点触控、拖拽
表达力代价:等宽格子,图片、表格、文件预览几乎不可能附赠:任意像素、排版、动画、多模态
信任附赠:文本即真相,命令可复现、可管道审计代价:界面可藏可换,信任要靠沙箱与同源策略(第 19 篇)

这张表是对称的:终端的赠品是“过去“(已发射的历史)和“信任“(文本透明),GUI 的赠品是“现在“(合成器持有的结构)和“带宽“(输入与表达)。它也是第 2 篇“TUI 不是低配 GUI“那个判断的完整清单:差异不在架构,事件树、投影、diff、审批、压缩、回放,两种界面是同一套内核的两个后端(Ink 在终端上长出声明式,UIKit 手写 frame 在 GUI 上停在命令式,楼层可以互换);差异在各端要另付的介质代价。

这张表还有一条没画出来的横切轴:上面“终端/GUI“分的是契约,UI 平台本身跑在哪是另一个维度:原生、浏览器,或 Electron 这种双契约并存的容器(DOM 做界面,node-pty 另开一条真实终端)。同样标着“GUI“,浏览器一格拿不到本地 shell 环境,但多端同步和“服务端即事实源“是自带的;标着“终端“的 xterm.js 跑在浏览器里,TUI 应用的契约一字不变,agent 人却已经在远端机器上。第 11 篇用两轴四格给六个端定了坐标,基建卷则是“事实在服务端“那一格的完整展开。

这也补上了第 1 篇补记那个判断的机制。agent 早期的需求结构(一维 token 流、文本工具链、处处可审计)恰好压在终端现成的格子上;而长会话、并行多 agent、行级审批、手机伴随端(第 10–12 篇与基建卷),每一项都在消费 GUI 的赠品。GUI 赢在需求结构越过了两边成本结构的交叉点,而不在于它更好。 选界面从来不是选范式,是在 agent 生命周期的不同阶段,选哪边的代价你更愿意付。


参考与延伸

  • 本文基于 FlowDown 本地源码副本的实际阅读(commit b2cecfd6,2026-05-15):Frameworks/Storage/Package.swift(WCDB 与 MarkdownParser 依赖)、FlowDown/Backend/Conversation/Pipeline/ConversationSession.swift(save/update/discard)、Pipeline/Execute/ConversationSession+ExecuteOnce.swift(流式修补序列)、Pipeline/ConversationSessionManager.swift(countIncomingTokens 与 Live Activity)、FlowDown/Interface/MessageListView/MessageListView.swift(ListViewKit 接线)。
  • 数据模型部分参照作者本人的既有分析笔记《FlowDown 对话上下文保存机制分析》并与源码核对。
  • 流式热路径“每 chunk 不写库“的表述基于调用链阅读,未做逐帧取证,以此口径为准。

渲染的信任边界——Agent UI 没有同源策略

第 10 篇讲权限 UX,回答“要不要批准”;这一篇讲它全部设计的前提:你看到的那个批准请求,是真的吗。过去两年针对 Agent 界面的注入攻击从研究演示变成了真实供应链事件,而我把三家引擎的源码连同自己的翻了一遍,专门找“内容清洗”这道防线,只有 Codex 做了一部分,模型输出和 MCP 工具结果都不在防线之内。


一、这些漏洞不姓“模型“

先把时间线摆出来。每一条的核实状态在脚注里交代,这里只说已经被多源证实的部分:

  • 2024 年 12 月,Terminal DiLLMa(Johann Rehberger 的 Embrace The Red 博客):研究者演示了提示注入怎样让 LLM 在输出里带上 ANSI 控制码,终端照单执行,改窗口标题、响铃、生成能外泄数据的可点击链接,在当时的 macOS 自带终端里还能借 DNS 请求零点击送出上下文。用转义序列攻击终端不是新问题,2003 年 xterm 就因此出过 CVE;这篇把这条老信道接到了 LLM 的输出上。
  • 2025 年 4 月,Trail of Bits《Deceiving users with ANSI terminal codes in MCP》:MCP 服务器的输出里埋光标跳转码,把恶意指令移动到用户看不到的位置,屏幕上只留良性文本。攻击对象写得很明白:human-in-the-loop 审查。
  • 2025 年 6 月,EchoLeak(CVE-2025-32711):Microsoft 365 Copilot 的零点击注入,远程攻击者无需任何用户交互外传组织数据。它被广泛引用为“生产系统首个零点击注入实证“,也证明模型侧防御(分类器、指令约束)挡不住认真的绕过。
  • 2026 年 5 月,jqwik 1.10.0:一个百万级下载的 Java 测试库,作者本人在新版本里埋了用 ANSI 序列隐藏的注入指令:人眼看构建输出干净,AI 编码代理(Cursor、Claude Code 这类会读终端输出的)会读到并可能执行。Snyk 六月初出了分析。注意这个细节:埋码的不是黑产,是库作者本人的抗议行为。连正经作者都意识到,这条信道开箱即用。

把四件事叠起来,pattern 很清楚:攻击面不在模型,在“内容如何到达眼睛和上下文“这一层。模型侧防御是概率性的,渲染边界是确定性的,概率性的那层已经被 EchoLeak 证明会漏,确定性的这层至今没人建。

用户指令、模型输出、工具输出,三种信任级别的内容,被 Agent UI 铺在同一张渲染面上,不做任何区分。浏览器在九十年代为同样的问题发明了同源策略和 HTML 转义,后来又有了 CSP;Agent UI 现在处于“把别人家的 HTML 直接 innerHTML“的年代。

二、终端的 XSS:一次确认框劫持的解剖

具体到字符终端,攻击的零件库其实很小:

  • ESC[A(光标上移)+ ESC[2K(擦行):改写已经输出的内容。第 2 篇说过终端没有 undo、喷出去的内容管不着,这个对引擎的约束,对攻击者是福利:他也可以擦掉真提示、画一个假的。
  • OSC 52:一段转义序列就能改写用户剪贴板,用户下一次粘贴的就是攻击者准备的命令;有些终端还允许用 OSC 52 读剪贴板,那就是零交互的窃取。
  • OSC 8:超链接的文字和目标可以分离,显示 github.com/foo,指向别处。
  • 模式开关滥用:开关括号粘贴、键盘协议、同步输出,都可能让客户端行为错乱。

确认框劫持的完整链条,Trail of Bits 已经演示过:恶意 MCP 服务器返回的文本里带光标码 → 权限确认时刻,屏幕上“工具将执行 X“的 X 已经被擦换成了良性描述,或恶意命令被移出了可视区 → 用户核对无误,按了回车。权限 UX 的全部隐含假设(用户看到的等于将要执行的),在字符网格上是可以用一串字节伪造的。

还有一层 TUI 特有的脆弱性。GUI 里内容原地消失是异常,会触发警觉;终端里滚动、清屏、重绘是每分钟都在发生的正常现象(第 2、13 篇拆过的那些机制)。用户对“字符消失“已经脱敏,这是这个介质白送给攻击者的掩护。

三、我把防线找了一遍:四家引擎的排查记录

为了不空谈,我做了个一手排查:在三家开源引擎和 ForgeLoopTUI 里找“不可信内容进入渲染前,是否被转义或中和“。方法很朴素:grep 清洗类标识符,再读命中处。

引擎内容中转义序列的处理证据
kimi-code(pi-tui)规范化,但不清洗utils.ts 的 normalizeTerminalOutput(405-427 行):做泰文字符规范化和 tab 转空格;遇到 ANSI 码走 extractAnsiCode,原样拼回输出,它保护的是布局计算,防线不是给安全用的
grok-build未发现内容清洗全仓库 sanitize 命中都在 worktree 的 .git 目录清理,与渲染无关
Codex部分清洗用户输入走 sanitize_user_text(history_cell/messages.rs,去掉 CSI 和控制字符),命令输出经 ansi-to-tui 只留颜色,超链接目标和窗口标题单独清洗;模型输出和 MCP 工具结果没有清洗,进历史后由 insert_history.rs 的 write_spans 原样写给终端
ForgeLoopTUI(我的)同样没有MarkdownEngine 有 OSC 8 的发射端(TASK-31 加的),没有过滤端

除了 Codex,三家(算上我)全部裸奔。Codex 也只防了用户输入、命令输出、链接和标题;时间线里 Trail of Bits 和 Terminal DiLLMa 那两条攻击走的 MCP 工具结果和模型输出,在 Codex 里照样原样上屏。Claude Code 是发布产物,没做同等排查,如实声明。

为什么那三家都没有?原因是结构性的,不是哪家疏忽。这几家引擎都把样式和内容混在同一条字符串流里,第 14 篇拆过的行数组,引擎自己的颜色、重置、链接序列和用户内容交织在同一个数组里。在这个表示法上做“清洗内容里的控制码“是自相矛盾的:你分不清哪个 ESC 是自己人。所以没人做,等于谁都没做。Codex 正好是旁证:它的样式存在 ratatui 的 span 属性里,不和内容挤在一个字符串里,所以能对内容单独动手,用户输入那一路就是这么清洗的。

这和 Web 早期“HTML 与数据混流“导致 XSS 泛滥是同一个病,解药也是同一个:结构化分离。

四、防线应该长在哪几层

转义层:终端版的 HTML escaping。 不可信文本(工具输出、文件内容、网页摘要)在进入行数组之前,中和全部 CSI/OSC 序列:剥除,或可见地转义成 ␛[A。OSC 52、OSC 8、光标码、模式开关,零容忍。这件事的前提是内容与样式的结构化分离,恰好是第 7 篇说过的“渲染输入应该是结构化事件,投影发生在边界上“:转义就发生在投影边界,不用在 ANSI 字符串里做外科手术。这个系列写到这里,安全问题和架构问题在第 7 篇的地基上会师了。

溯源层:让三种信任级别看得见。 工具输出在视觉上与用户内容、模型内容分区(折叠框、边框、颜色语义),确认框只渲染结构化字段(命令、参数、目标路径),不渲染自由文本。要害在于:权限确认框里显示的工具描述,是第三方 MCP 服务器写的一段话。不可信输入,渲染在 UI 里最可信的位置,这是当前权限界面普遍的毛病。

变更层:描述漂移检测。 Invariant Labs 2025 年披露的 tool poisoning 里有个“rug pull“变体:工具先以无害描述通过审批,之后偷换描述。界面侧的解法很朴素:记下用户批准时的描述 hash,变了就重新询问:“这个工具在你批准之后改了说明书”。

协议层已经在承认。 MCP 后来加的 elicitation URL mode,让敏感交互绕开 MCP client、走用户的浏览器完成,协议设计者自己承认了 client 内的渲染信道不可信。这是对的方向:信道不可信,就把最敏感的问答挪到各自可信的介质上去。

最后记下我自己的一项待办:ForgeLoopTUI 的内容转义过滤器。第 17 篇结尾那张欠了六件的清单,现在是七件。

五、总结

第 10 篇问“批不批“,这一篇问“看到的真的吗“。前者是决策设计,后者是感知前提,感知层失守,决策层的一切精巧(分级、超时、auto mode 的信任衰减)都建在沙地上。human-in-the-loop 的完整拼写从来不是 approve what you see,是 see what you approve。

放到系列坐标里:渲染所有权四部曲(第 13、14、17、18 篇)讲的是“屏幕上的像素归谁管“;这一篇讲“像素本身能不能被信任“。两件事在终端上还是两个问题,到了 GUI 时代会合成一个:信任边界必须和渲染边界同构,否则就是给 innerHTML 写文档。

还有一件事要记在这里:感知的反面是记忆。引擎开始替你忘掉上下文的那一刻,没有对话框,没有提示音,只有一行灰字:context low。谁授权了这次遗忘,丢掉了什么,能不能审计,这几个问题本篇回答不了,留作开放题。


参考与延伸

  • 事件部分核实状态(截至 2026-09-28):Terminal DiLLMa(Embrace The Red,2024-12-06)、Trail of Bits《Deceiving users with ANSI terminal codes in MCP》(2025-04-29)、EchoLeak CVE-2025-32711(Aim Security 2025-06 披露,多源交叉)、jqwik 1.10.0 事件(2026-05,Snyk 2026-06-02 分析)均经多源检索核实。Terminal DiLLMa 的出处初版误标为一个无关的 arXiv 编号,2026-11 更正;2003 年的 xterm 漏洞是 CVE-2003-0063(H D Moore 披露)。
  • Invariant Labs tool poisoning 未复核原文,按公开报道转述。
  • 引擎排查基于本地源码:kimi-code 1e553fc(packages/pi-tui/src/utils.ts)、grok-build 9fabade(全仓库检索)、ForgeLoopTUI f99367b(Sources/ForgeLoopTUI/Markdown/MarkdownEngine.swift)。
  • Codex 部分为 2026-11-10 补查,口径同上(grep 加读命中处),快照 6b9826e3:tui/src/history_cell/messages.rs(sanitize_user_text)、history_cell/mcp.rs(MCP 结果直接成行)、insert_history.rs(write_spans 原样写出)、terminal_hyperlinks.rs、terminal_title.rs;命令输出经 ansi-to-tui 8.0.1 解析,非颜色的转义序列被 any_escape_sequence 丢弃。底部活动区经 ratatui 缓冲区绘制,ratatui-core 0.1.2 的 set_stringn 会丢掉含控制字符的字形,这是库的副作用,不是 Codex 专门做的防线。同日对照 main(c875667):sanitize_user_text 又用到了侧边对话、异步问答等几处,历史里的模型输出和 MCP 工具结果仍原样写给终端,结论不变。
  • 方法局限:grep 加人工阅读命中处,不能排除存在未被这两种方式覆盖的防线,结论以“未发现“为准,不断言“不存在“。

从大前端到 Agent Workflow Engineer

界面卷的最后一篇。前面十九篇讲的是界面怎么做,这一篇回到人:做移动端、桌面端、TUI、全栈这些经验,在 Agent 时代到底意味着什么。这部分原本是第 12 篇的后半,成书时挪到了卷末。


一、一个全栈开发者的经验怎么迁移

这几项我都做过,移动端、桌面端、TUI、全栈。回头看,每一项在 Agent 时代都有直接的迁移路径:

移动端 → 权限和通知 UX。
移动端的天性就是处理权限:相机、定位、通讯录、通知。授权粒度怎么分(以定位权限为例:授权状态其实只有“使用期间 / 始终“两级,弹窗上那个“允许一次“是临时的“使用期间“,App 停止使用后失效;而且首次弹窗根本没有“始终“选项)、授权疲劳长什么样、推送通知的触达率和骚扰率之间怎么平衡,这些是移动端开发者的日常。

桌面端 → 本地集成和系统交互。
文件系统权限、shell 环境继承、code signing、auto update、crash recovery,第 1 篇和第 8 篇反复提到的 GUI 额外成本,做桌面端的时候我已经交过学费了。Agent Desktop App 是这些经验的直接应用场景。

TUI → 高密度文本信息架构。
写 ForgeLoopTUI 的过程,就是在一个只有字符的终端里把信息组织清晰的过程,靠的不是像素能力,是信息优先级。什么该放 committed 区、什么该放 live 区,通知超过 3 条就该移除,这些判断是在字符网格里逼出来的,框架给不了。这套判断力在 GUI 上同样适用,信息多了,Panel 不会帮你自动排优先级。

全栈 → Runtime 和持久化设计。
Event log 的 append-only 模型、权限引擎的信任规则持久化、Workspace 状态管理,这些不是 UI 问题,是后端问题。全栈经验让我能同时理解 Agent 的 Runtime 层和投影层,不用只做其中一半。

大前端 → 复杂交互状态管理。
大前端的核心能力不是“会写多个平台“,是管理复杂交互状态:一个操作触发多个副作用、多个异步事件并发到达、用户中途介入改变状态流向。这和第 4 篇拆解的 Agent 事件处理模型是同一种能力。我在 ForgeLoopTUI 里手写的 pendingTools 稳定槽位队列 + shiftIndices 偏移追踪,回头看就是一个手动实现的响应式状态管理系统。


二、新岗位方向

如果“Agent 时代的开发者界面“成为一个独立的专业领域,这些岗位可能会出现或已经在出现:

Agent Workflow Engineer。
不设计聊天框,设计 Agent 的工作流界面:工具调用时间线、权限审批流、diff 审查面板、多任务编排。需要同时理解 Agent 的执行模型和 GUI 的交互模式。

AI DevTools Product Engineer。
介于产品经理和工程师之间,不需要手写 ANSI 状态机,但需要知道物理行计算为什么让增量 diff 翻倍复杂。在工程约束和用户体验之间做判断。

Local-first Agent Platform Engineer。
Agent 核心跑在用户机器上,event log 本地持久化,隐私和延迟优于云端方案。需要桌面端开发经验 + Runtime 设计能力。

IDE / CLI Integration Engineer。
把 Agent 嵌入开发者的现有工具链,不另起 Agent 专属界面,让 Agent 在 VS Code、终端、git 工作流里自然出现。

这些方向现在还处于早期。但回头看第 1 篇列的那个名单(Claude Code、Codex CLI、Gemini CLI、Goose、Aider、Devin CLI、Qwen Code),每个项目背后都需要这样的人(名单的时间锚点、以及到 2026 年秋天各家 GUI 的进展,见第 1 篇的补记:界面在变多,这类岗位的需求只多不少)。他们写的是 Agent 的界面,但做的不是传统意义上的“前端“。


界面卷到这里结束。下一卷是胶水层,从界面往下走一层,看界面和引擎之间怎么对话。

第四条边界——当主语是引擎

从这里开始往下走一层,到界面与引擎之间的那条缝。这条缝上,行业已经给三类对话者各造了一套协议,主语各不相同;这一篇从内侧读 Codex,看一个自己养界面的引擎怎么回答同一个问题。它的答案方向和那三套都不一样:主语是引擎。本卷的准入线:只写这条缝上决定某个界面承诺真假的机制。


一、三条国境线都没有覆盖的那个对话者

先给一张十秒钟的地图。一个 agent 今天要和三类对话者说话,行业为每条边界造了一套协议:跟工具说话用 MCP,主语是 agent,它去征用外界的能力;跟编辑器说话用 ACP,主语是编辑器,它去征用一个 agent;跟浏览器前端说话用 AG-UI,前端是消费者,它订阅 agent 的事件流。这三条边界各自怎么划、代价各落在谁身上,基建第 3 篇会逐条讲;这一篇只需要它们的朝向,因为 Codex 的 app-server 协议不在这张地图上。

它当然不是 MCP:能力方向反了,是引擎被界面征用,不是引擎去征用工具。它有点像 ACP 的镜像:ACP 里编辑器把 agent 当子进程拉起,编辑器是主语;Codex 的 app-server 里引擎把界面当客户端服务,引擎是 server,TUI、桌面端、IDE、手机、连 UI 都没有的 codex exec,全是 client。三条边界里主语最强势的是“编辑器征用 agent“,这里是“agent 征用一切界面“。

方向反过来,难题清单跟着换。编辑器当主语时,最难的问题是“agent 的权限请求怎么嵌进我的 UI“;引擎当主语时,最难的问题变成:一个 server,怎么向自己的 client 开口要东西。审批不是界面弹个窗那么简单:server 在 turn 跑到一半时,向 client 发一条反向 request,挂起执行,等一个 oneshot 回填决定。Codex 把这个“反向通道“做成了一个枚举:执行审批、文件变更审批、向用户提问、MCP elicitation、权限申请、甚至宿主代管 token 时的刷新请求,全部走同一类 server→client request。“宿主怎么反问用户“这个 ACP 边界上最难的设计点,在引擎当主语的世界里不是一个 UI 问题,是协议里的一类消息。

server 身份带来的第二件事是历史的归属。编辑器当主语时,会话历史跟着编辑器的项目走;引擎当 server 之后,thread 的历史归引擎持久:append-only 的 rollout 文件是事实源,客户端看到的 turn/item 视图是投影器的产物。thread_history.rs 这个 5024 行的文件,把 rollout 逐行译成增量 ChangeSet。协议注释已经宣布全量水合废弃(“Full-history hydration is deprecated for paginated threads”),往回翻页走 opaque cursor。界面部分第 7 篇的 Event Sourcing、第 11 篇的统一 Event Log,在这里不是主张,是一个每天被好几种客户端消费的真实部件;“换一台设备接着聊“是出厂设置,因为历史从来不在任何一台设备上。记住这个承诺,§四会回来看它在哪里被打破。

server 身份还带来一件 ACP/AG-UI 都没有的事:多 client 共存,且版本不一。daemon 让一个引擎进程同时服务多个客户端。桌面端走 alpha 发布线、落后五个 minor 这种事(本机实证:桌面 0.155.0-alpha、CLI 0.160.0),在“编辑器养 agent“的世界里几乎不存在,在“引擎养界面“的世界里是日常。于是每条连接建立时都要重新核对一次能力,这就是下一节的握手。

二、协议里没有版本号

先给结论再给证据:Codex 的 initialize 握手有 clientInfo(名字、版本)和 capabilities(实验性 API opt-in、通知 opt-out、MCP 扩展声明),唯独没有 protocolVersion 字段。全文 grep 无结果,不是藏得深,是没有。

它用什么替代数字协商?三件套:

  1. 加法演化:serde 忽略未知字段 + #[serde(default)],新方法新字段旧客户端自然跳过;
  2. opt-in 门:不稳定的表面必须客户端显式举手(capabilities 里的 experimental 标志)才启用,服务端逐请求用 trait 查表拦截。“实验性“是类型系统的属性,不只是文档约定;
  3. 目录冻结:工程纪律明文“v1 不再加新 API 面,新 API 全进 v2“。版本化不靠数字谈判,靠老目录封版、新目录演进。

协议是会咬人的:依赖它承诺的字段,一次破坏性修订说没就没。对这种恐惧,基建第 1 篇里 kimi 的防御是“seq 字段全可选“,Codex 在这里的防御是加法 + 举手 + 封版——同一类恐惧,两种解。数字协商承诺的是“我支持 1.x 到 2.y 的全序“,加法演化承诺的是更弱但更诚实的两句话:旧消息永远可读,新能力你自己举手。

对界面,这意味着承诺的形状:旧客户端的可见世界被握手时刻永久定格,它不会因为服务端升级而突然报错,也不会突然多出不认识的能力。反过来,服务端永远不能假定新客户端存在——能力永远以客户端声明为准。界面承诺的边界,在握手那几百毫秒里就签完了。

三、同进程,也过协议

这一节是界面部分第 11 篇四个统一(Runtime、Event Log、Permission Engine、Workspace Model)在 Codex 里兑现得最彻底的一条。TUI 和引擎跑在同一个进程里,它们之间仍然走 JSON-RPC:进程内 channel 传输的是换了信封的同一套消息,注释明说不引入第二套响应契约。连“连 UI 都没有“的 exec 模式,也是这套协议的客户端。

初看是洁癖,再想是纪律:协议一旦为“进程边界“破例,就会为“反正只是内部用“破第二次。协议一等公民的直接收益有实证:core 侧删掉 Op::UserTurn、换成 TurnInput/start_or_steer_turn 的破坏性重构,TUI 一行没改,因为它对 core 内部类型的引用为零。四个统一里“统一 Runtime、统一 Event Log“是主张时人人点头;只有当 UI 连进程内的捷径都不走时,它才从主张变成事实。

还有一点值得单独记下:TUI 完全客户端化,保证了不会出现“内部 API 比公开协议强“的腐化。界面永远是能力的最小公分母,引擎想长新能力,先扩协议。这条纪律的代价是同进程还要序列化一次的样板成本,收益是任何新端接入零特权;成本和收益怎么配平,是基建卷还会反复讨论的问题。

四、进程形态学:三种连接,和一次静默的降级

引擎怎么被界面“到达“,Codex 给了三种形态:嵌入式(in-process,随客户端拉起)、本地 daemon(走 Unix socket 连常驻实例)、远端(WebSocket)。同一个引擎,三种拓扑,客户端代码几乎无感,这是协议选型带来的长期收益。

但 2026-10 读源码时我停在一个降级分支上(tui/src/lib.rs:518-521,已逐行亲验):TUI 优先连本地 daemon,连不上时静默降级为嵌入式,只留一行 debug 级日志,顺手还把 state_db 句柄重初始化了。远端连接失败则直接报错上抛,只有本地 daemon 这一档降级。

这不是 bug,是刻意设计的平滑降级,而且设计得不算坏:daemon 没起来就自己跑一个,用户无感。但它打破了一个没被写进任何文档的界面承诺:“你连的是谁,你会知道”。我最初怀疑的是更重的一条:state_db 被重初始化,线程索引会不会落在与 daemon 不同的存储上,让用户启动 TUI 后看到自己的历史少了一块。2026-10-07 晚的源码复核把这条排除了:嵌入式与 daemon 指向同一个 codex_home 下的同一批 SQLite 和 rollout 文件,thread/list 与 thread/resume 都正常,数据没有断裂。缺口因此显得更纯粹:数据完好,功能如常,动画照转,唯一被打破的承诺是“拓扑变了你会知道“。/status 里 Remote Connection 一行不是改成“已降级“,而是整体消失;降级日志是 debug 级,被默认过滤挡在所有用户可达的地方之外。界面不是说了假话,是根本没被给过说话的机会。基建第 1 篇会给断线时刻的用户三问:还连着吗、我漏了什么、从哪继续;这一档降级对“我漏了什么“的回答是沉默。不是答错了,是根本没有回答,界面也就没有机会诚实。

所以这篇要记的胶水层判断是:降级的代价不在降级本身,在降级是静默的。拓扑切换是界面契约的一部分——只要界面承诺的内容依赖“连的是谁“,连接形态的变化就必须至少有信息级的可见性(一行状态、一个脚注、一条警告),不能停在 debug 日志里。界面的每一个承诺,往下挖两层会碰到一条协议的条款,这句话会在基建卷反复出现;这里先补一条:往下挖三层,还会碰到一个 try/catch 分支。

五、发布拓扑决定仪式在哪里

继续往内核看一层,有一个漂亮的对照实验。全代码库里唯一不用协议仪式、改用“同构建强校验“的 IPC,是 voice-host——那个替引擎拿麦克风的 helper 进程。它带一个 --build-commit 参数,父进程拉起时核对构建 commit,不匹配就拒绝;通信走的是私有帧协议,没有握手、没有 capabilities。

为什么这里可以这么“粗暴“?因为它是全库唯一和引擎同生共死的进程:同一个二进制包发布、同一个版本号起落,两端永远不可能错位。而 app-server 那头,0.155 的桌面端撞上 0.160 的 CLI 是真实日常,所以握手、capabilities、加法演化一个都不能少。

**协商仪式的多少,由两端发布关系的松紧决定,不由洁癖决定。**这反过来给界面一个判断工具:当某个能力承诺“永远随 app 一起更新“,它可以走 voice-host 式的紧耦合(更省、更快);当它承诺“独立于 UI 演进“,它就必须付协议成本。耦合本身没有错,错的是错配的耦合。接缝该多强,要按两端的发布关系来定;后面基建第 1 篇用事实源的位置去定重连语义,是同一把尺子的第二次使用。

六、能力的方向:手外挂,缰绳内置

最后一个内侧观察,关于新能力怎么进引擎。以 computer use 为例:截屏、点击、拖拽的实现不在开源引擎里——它们经一个叫 cua_repl 的 MCP server 从宿主(桌面端 JS 侧)进入,引擎核心不认识鼠标。但围绕它的治理是全开源的:功能门由服务端 requirements 控制、每个模型声明自己对 computer_use/shell/file_changes 等动作的审批覆盖、操作规范是模型目录下发的 Markdown、回合中途换模型不允许降低审查水位。

三个问题三个归属:**能做什么由宿主决定,允许做什么由引擎决定,怎么做由模型目录决定。**界面在这套结构里拿到的承诺也因此分层:权限弹窗里显示什么、要不要拦,是引擎和策略面定死的;而弹窗背后那个动作具体怎么执行,界面不需要知道,也不必信任。这正是“协议给说什么、不给怎么画“在能力层的版本。

对想自建 glue 的人,这条比任何机制都可迁移:核心不长手,手永远可替换;但缰绳必须长在核心身上。

七、总结

把本篇的结论合到最后一张表里。基建卷会反复验证两句话:承诺的真假取决于事实源在哪一层,承诺往下挖两层碰到协议条款;本篇从引擎内侧补上第三步——承诺的兑现还要穿过一个方向选择、一次握手、一个降级分支:

界面承诺胶水层里兑现它的机制
我能看到你的线程引擎当 server,rollout 是事实源、客户端视图是投影(§一);但拓扑静默降级会撕毁它(§四)
审批弹窗问的都是该问的审批是协议里的一类反向 request,弹窗内容来自模型策略面(§一、§六)
旧版本客户端不会被升级弄坏加法演化 + capabilities 握手 + v1 冻结(§二)
UI 永远拿到完整能力同进程也过协议,协议一等公民,没有“内部 API 更强“的腐化(§三)
能力可以独立演进手外挂、缰绳内置,cua_repl 式的能力通道(§六)

而所有这些机制的成本,都由一个朴素的问题定价:这两端,是不是独立发布?是,就付协议成本;不是,就允许紧耦合。胶水层的设计,说到底是一门发布关系的经济学。

下一篇还留在这条缝上,讲这些承诺怎么变成每天都要过的断言。再往下走一层,承诺要穿过的东西从进程边界换成网络和操作系统:连接会断、端会被操作系统杀掉、协议对面坐着别家的主语——那是基建三篇的事;《没报错,就代表输出没问题吗》那个问句,如今收在评测卷卷首。


参考与延伸

  • 事实核查分层(截至 2026-10-07):本文 Codex 事实基于 rust-v0.154.0(HEAD 6b9826e3a,2026-09-09 快照)亲读——initialize 握手结构(app-server-protocol/src/protocol/v1.rs)、experimental 门控(message_processor.rs:912-920)、v1 冻结纪律(仓库 AGENTS.md:269)、TUI 内嵌走 JSON-RPC envelope(app-server/src/in_process.rs:22)、历史投影与分页(app-server-protocol/src/protocol/thread_history.rs、thread_history_projection.rs:1-3、v2/thread.rs:400,450)、静默降级分支(tui/src/lib.rs:518-521,逐行亲验)、voice-host 同构建校验(voice-host/src/main.rs:48 的 –build-commit)、computer use 治理面(features/src/lib.rs:271、protocol/src/openai_models.rs:402、core/src/session/step_activation.rs:110)与 cua_repl 通道(protocol/src/mcp.rs:38)。
  • 降级分支的数据影响(同一 codex_home、数据不断裂、/status Remote Connection 行整体消失)为 2026-10-07 晚接力复核增补(tui/src/lib.rs:518-521、thread-store/src/local/read_thread.rs:30)。
  • 桌面 0.155 vs CLI 0.160 的版本错位为本机实证(2026-10-03)。
  • openai/codex 官方博文《Unlocking the Codex harness: how we built the App Server》(2026-02)为“协议起源“的一手旁证。

把协议变成可断言的——承诺需要证人

上一篇的结尾留下一个缺口:一个静默的降级分支,打破了“你连的是谁,你会知道”这句没人写下来的承诺,而界面一切正常。这一篇问后半句:这些承诺,怎么变成每天都要过的一道关。评测卷卷首语会把 agent 评测收成四个问题,画成一张地图;地图上“协议”那一层,在这里领走它的断言清单。


一、承诺需要证人

先把上一篇的病例在桌上重新摆开,只摆三十秒。TUI 启动时优先连本地 daemon,连不上就退回进程内嵌(tui/src/lib.rs:518-521),一行 debug 级日志,顺手把 state_db 句柄重新初始化。用户看到的是什么?动画照转,界面如常。2026-10-07 晚的源码复核补上了后半句:连历史都完好无损,嵌入式与 daemon 指向同一个 codex_home 下的同一批 SQLite 和 rollout,昨天的线程今天全在。可没有任何东西告诉他,他脚下的拓扑已经换了。

这个分支值得再停一次。不是因为它错(上一篇已经判过,这是刻意设计的平滑降级),而是因为它活得太安稳了。它被发现的路径不是某个测试红了,也不是某个用户报到了对的渠道,而是一个人读源码时在降级分支上停了下来。一个每天可能有成千上万人经过的分支,唯一的目击者是读者。它为什么能活这么久?

答案简单得有点难堪:没有任何一条断言看着它。

工程师当然测过降级。但测的问题是“daemon 没起来,TUI 还能不能用“:能用,绿灯。没有人测“daemon 没起来,用户知不知道“。至于“切换之后,昨天的线程还在不在列表里“,源码复核的答案是“在“,哪怕有人写了这条核对测试,它也会绿。缺口由此被隔离得很干净:数据没丢,只是没有人被告知。数据会丢的故障好歹有核对可抓,沉默连核对都不会触发,它只是某个下午某个读者的意外发现,发现时连事故都算不上。

这里要立本章的骨架。一个界面承诺的生命,其实经过三层:

第一层是承诺,用户信的那句话:“我看到的线程列表是完整的。“第二层是条款,协议里决定承诺真假的机制——state_db 归谁、降级走哪条分支,上一篇挖的就是这一层。第三层是断言,承诺的证人:一条每天运行、红了会被人看见的检查。上一篇走完了从承诺到条款的挖掘,这一篇走最后一步:每条条款必须对应一条每天出庭的断言,否则承诺只是愿望。

注意证人的定义。debug 日志不是证人:它只在有人翻卷宗时才开口,而翻卷宗永远发生在事故之后。文档也不是证人:它记录的是意图,不是现状。证人只有一个特征:每天出庭,且缺席会被发现。在工程世界里,满足这个定义的东西只有一种:跑在 CI 里、红了会拦下发布的测试。断言缺席的承诺不是被守住的,是没被检验的;它的第一次检验发生在生产,或者某个读源码的下午。

这条路和全书走过的两段路是同一条。界面部分第 16 篇把渲染变成可断言的:ANSI 序列不再是“看起来对就行“,而是可以逐字节比对的快照。评测卷卷首语把行为变成可断言的:没报错只是开始,评测卷第 3 篇还会讲绿灯撒的两种谎。这一篇把那道缝变成可断言的。评测卷那条统一定律在这里有最具体的形态:**daemon 世界和 embedded 世界产出同一个“一切正常“,你的观测对它们的差异就是盲的。**后面的每一节,都是给这类“两个世界、一个绿灯“的格子配一名证人。

二、降级必须有人看见

把所有可以配的证人排一排,密度最高、造价最低的那一组,在降级路径上。所以本章把主战场直接摆在这里。

先把承诺的正面写出来:**拓扑变了,你会知道。**这句话有三层含义,对应三种切换。连接形态的切换(你连的是 daemon 还是内嵌引擎);存储归属的切换(你的历史落在哪个 state_db 里);安全等级的切换(审批通道、沙箱边界有没有随拓扑一起变)。三种切换有一个共同义务:至少留下信息级的可见性,一行状态、一个脚注、一条警告,形式不拘,但不能停在 debug 日志里。

先回答那个最自然的反问:静默降级为什么这么常见?因为它从来不是断言的对象。工程师测“降级后还能不能用“,这是功能测试,测的是世界 B 能不能运转;没有人测“从世界 A 切到世界 B 时,有没有人被告知“,这是承诺测试,测的是切换这个动作本身。前者每个项目都有,后者几乎没人写。**可见性不在任何 checklist 上,所以它在每个 try/catch 里都第一个被牺牲。**把它写进断言,它才从品味变成契约。这就是本节要做的事。

方法是故障注入,三件套,按隐蔽程度排序。

第一件,杀掉对端。最直白的注入:把 daemon 杀掉,启动 TUI,然后做两条断言。第一条:存在用户可见的信号,在界面里,而不只是日志文件里的一行。第二条:线程列表与 daemon 存储核对一致,降级之后,昨天的线程今天还在。拿上一篇的病例当预期,今天的 Codex 在第一条上红:降级完全静默,/status 里 Remote Connection 一行干脆整体消失;而第二条会绿,因为两条路径指向同一批存储,核对得上。第二条的绿反而是最有价值的证词:它把缺口从“数据可能丢了“精确隔离到“可见性“这一层,功能断言全部通过,用户却对换了一个世界一无所知。这两条断言都不复杂,难的是意识到它们该存在。杀一个进程,就知道你的界面有没有能力诚实,这是全章性价比最高的实验。

第二件,病态对端。“连不上“是善良的故障,它干脆利落;更隐蔽的是“连得上,但不对劲”:握手卡住、连接永不关闭、只发 keepalive 不发数据。这三种对端在真实网络里比比皆是,而它们恰好是“静默“的天然培养基:连接活着,进展死了,界面该说什么?Codex 自己的测试基建里已经有全套工具:WebSocketTestServer 能伪造握手卡住、永不关闭的对端,StreamingSseServer 能精确控制第几个 chunk 在某个事件之后才发。这些工具本来对着引擎与模型的边界,把它们转过来对准前端与引擎的边界,问题清单立刻变长:握手卡住时 UI 是转圈还是报错?转多久才承认?对端只发心跳不发进展时,界面显示的是“正在工作“还是“等待响应“?keepalive 是传输层的心跳,不是进展层的心跳;把前者当后者展示,是另一种静默,而且比断连的静默更难发现,因为它看起来很像活着。

第三件,状态可达性。降级的断言不能只测新世界的功能,必须测旧世界的遗产:切换发生之后,旧存储里的数据还读不读得到。注意断言的方向:不是“新的 state_db 能写“(这永远绿),而是“昨天建的线程今天在列表里“。状态归属的切换如果只是换了一个空房子,功能测试一条都不会红,只有核对能抓住它。

三件套之外还有一条贯穿的要求:故障归类必须诚实。连接死了、对端静默、用户主动打断,是三个不同的世界,界面的文案必须让它们产出三个不同的句子,不能共享一句“出了点问题“。这正是评测卷说的分叉观测在协议层的形态:把“失败了“这一个布尔,拆成“怎么失败的“分别记录,出了分歧不用再等有人翻日志。

最后回答本节开头那个排序的理由。全章六组断言(降级、配对与时序、完成语义、竞态、兼容矩阵、历史核对)里把降级放在第一位,不是因为它最重要,是因为它的炸弹密度与注入成本之比最高:杀掉一个进程只要一条命令,而静默降级打破的是“历史完整“这种地基级承诺。评测卷第 3 篇里,静默降级只是六条绕行通道之一;在这一篇,它是整个维度,因为协议层的降级不只绕过检查,还绕过了用户的知情。

三、三个可观察面:证人从哪里取证

降级那节已经把证人派上了庭,现在退回来回答一个更基础的问题:证人的证词从哪来?胶水层的断言,原料只有三样:出站请求日志、事件流、副作用。三样加起来,是 agent 行为的全部可观察面,也是证据采集的最小集:多一样不必,少一样不够。

请求日志是最诚实的一样。引擎向模型、向 daemon、向任何对端发出的每个请求都是白纸黑字,而 Codex 测试基建最重要的一次转身,就是把捕获层变成断言层:自定义的 wiremock matcher 在匹配每个请求时,顺带做一次协议不变量检查,call 和 output 必须配对,孤儿 output 直接 panic。妙处在于寄生:不需要专门养一套协议测试,已有的每一次普通测试运行都自动变成一次协议 fuzz。证人不是雇来的,是埋伏在每天的例行公事里的。

事件流是第二样。全量落盘成 JSONL,回放即断言。要干净的原料就用 codex exec --json:没有 TUI 渲染掺入,逐行带时间戳;要连界面一起审,就开 CODEX_TUI_RECORD_SESSION=1,AppEvent 的进出和每一次 commit tick 都在案。同一条流,两个清晰度,各管一段。

副作用是第三样:状态存储、文件系统、rollout 文件——世界被改成了什么样。三样的分工是:**请求日志回答“引擎说了什么“,事件流回答“界面被告知了什么“,副作用回答“世界变成了什么样“。**一句承诺的真假,要三样都对得上才算数,降级那节的“线程列表核对“,就是事件流和副作用的交叉质证。

后面四节,是四组承诺各自的证人。你会发现每组的取料都不出这三样,变的是问法。

四、契约的配对与时序

第一组承诺:**事件流是完整的、有序的、闭合的。**它是所有其他承诺的地基:事件流本身不可信,建立在它上面的一切断言都靠不住。

三条不变量。配对:每个 begin 恰好一个 end,每个 request 恰好一个 response,每个 call 恰好一个 output,孤儿是协议违例,不是可以原谅的噪声。时序:生命周期事件严格有序,Codex 的核心序列是 turn/started → item/started → item/agentMessage/delta → item/completed → turn/completed,乱一个位置,前端的状态机就可能整页错乱。闭合:任何退出路径(正常完成、abort、错误、超时)都恰好收尾一次,不泄漏、不重复。闭合最容易被漏掉,因为正常路径人人测,异常路径的“最后一次收尾“常常没人等。

断言的写法上一节已经给了:配对和计数挂在捕获层(.expect(n) 断言“恰好收到 N 次请求“),时序和闭合写成回放检查。这里值得记的是为什么这些断言在 Codex 里天然有地方挂。回到上一篇 §三:TUI 连进程内都走协议,没有任何前端拥有绕过协议的特权通道。**协议一等公民的收益,在测试侧兑现得最彻底:捕获点对所有端一视同仁地存在。**反过来想就明白这条纪律的分量:如果 TUI 有一条直连 core 的函数调用捷径,那么 TUI 路径上的所有承诺都脱离了捕获点的视野,断言体系立刻出现一个和最大客户端等大的盲区。捷径省下的序列化成本,最后都要在可观测性上加倍还回来。

五、这段话算不算答案

第二组承诺短得多,也深得多:前端不需要自己猜“这段输出算什么“。

先看 Codex 给出的反面标本。它的协议不给定性:turn/completed 只说循环结束了,至于最后那段文本是最终答案、是过程性解说、还是被截断的半句话,协议不说,每个前端自己推。后果写在 TUI 的代码量里:一个 232 变体的 AppEvent 总线,加上流式累积源要靠 item/completed 的权威文本核对(传输饱和丢 delta 时,以 completion 为权威)。这不是前端写得笨,这是语义缺位的代价:协议不回答的问题,复杂度就漏进每个前端,一个端漏一次。

所以本节的不变量是本书提出的正面设计,先把话放这:Codex 协议当前不含此面,以下是“应该有“的断言清单,不是“现有“的机制描述。

**完成语义协议级可判定。**协议应当携带定性标记:这段输出是正常完成的最终答案、是跟随工具调用的过程性输出、是被 max_tokens 截断的续写段、是中断留下的残段、还是失败被回滚的废段。五种定性对应五种界面动作(展示、折叠、拼接、标记、丢弃),前端不该靠启发式分辨。丢弃语义可区分:“回滚过“不等于“没发生过”,被丢弃的输出必须有记录、占序号,否则前端无法区分“模型沉默了“和“模型说了又被撤回“,而后者的字节必须被明确抛弃,不能留在屏幕上冒充答案。增量与定稿可核对:流式累积源与完成事件的权威文本,在任何丢包、乱序、截断下都必须可调和。这一条写成 property-based 测试,随机掐断一千次,次次对得上才算数。

给协议补一个定性字段,比给每个前端补一台状态机便宜。这道题不难算,难的是意识到该算。

六、迟到的批准

第三组承诺关于时间:审批与中断的任何交错顺序下,结果确定且安全。

Codex 的 guardian 测试里有一条值得抄进每个 agent 项目的断言:给审批响应 .set_delay(200ms) 拖住,其间注入中断,然后断言迟到的批准不会让命令执行。决定到达时目标已经 abort,决定就必须被丢弃,而不是被补救性地执行。这条断言的形态是竞态测试的标准解法:延迟注入加时序编排,用 StreamingSseServer 那种逐 chunk 门控的能力,精确控制“第 N 个事件在某动作之后才发“,把调度器的不确定性挤出测试。

同样值得抄的是断言的落点。guardian 的安全断言不停在“界面显示了拒绝“,而是直接落在请求日志上:guardian 永远读不到被 deny 的文件内容。安全属性要断言在数据流上,不是断言在文案上;文案会说谎,请求日志不会。

时间维度上还有一条 Codex 没答、但任何想做异步前端的引擎都该答的题:当人几小时后才回消息(IM、邮件、工单)时,“等待“必须是一个显式语义。阻塞地等、挂起会话等、超时拒绝,是三种合法答案;隐式死等不是答案,是没有回答。挂起-恢复路径的断言形态 Codex 给了半个示范:resume 测试就是 shutdown_and_wait 加从 rollout 文件重启,不需要第二个进程;补全的另一半是恢复后的核对:会话状态逐字节一致,或者每一处差异都被显式声明。

七、握手的兼容矩阵

第四组承诺关于演进:**升级不会背刺旧端。**机制上一篇已经讲完了(加法演化、opt-in 举手、目录封版三件套),这一节只回答一个问题:三件套的断言各长什么样。

加法演化的断言是注入未知:往消息里塞旧客户端不认识的字段、发它不认识的方法,断言旧端存活且行为不变。opt-in 的断言是不举手就不存在:实验性表面对未声明的客户端不是“报错“,是“不存在“,也就是不返回、不提示、不可发现。封版的断言最简单也最硬:冻结目录的契约测试钉死在 CI 里,任何试图往 v1 加面的提交直接红。

然后把这些单点断言织成版本矩阵:旧客户端 × 新引擎、新客户端 × 旧引擎、能力子集 × 全量引擎。矩阵听起来像理论,在 Codex 的发布拓扑里是日常。本机实证:桌面端跑 0.155.0-alpha、CLI 跑 0.160.0,同一个引擎,两个相差五个 minor 的客户端共存。矩阵不是为假想敌准备的,是为每个发布日准备的。最后还有一条容易漏的:能力声明的真实性——客户端在 capabilities 里举手声明的能力,必须与它的实际行为一致;声明了 opt-in 却处理不了对应事件,和没声明一样坏,而且更隐蔽。

八、历史的核对

最后一组承诺关于昨天:换台设备、重启进程之后,历史还在,且是真的。

先回忆承诺的机制面:rollout 是 append-only 的事实源,客户端看到的 turn/item 视图是 thread_history.rs 这个 5024 行投影器的产物。**这个事实有一个经常被忽视的推论:客户端看到的从来不是真相,是真相的投影。**对界面这是渲染问题,对评测这是取数纪律:任何从 UI 侧采集的数据,都必须意识到投影层的存在,因为投影器的一个 bug,会让你的评测数据整齐地错,而且错得毫无破绽。

恢复路径的断言要测两条,不是一条。正常退出重启,人人测;kill -9 之后重启,才是承诺被检验的时刻。Codex 的崩溃恢复靠一个写入顺序:发首个采样请求前,TurnContext、初始上下文消息、TurnStarted、用户消息依次写 rollout。这个顺序本身就该是断言对象——在顺序的不同点位杀掉进程,恢复后的状态必须一致;顺序错一位,崩溃就从一个可恢复事件变成一次历史撕裂。同样,不持久化的内存态(进程内的 registry、后台任务的活状态),恢复后的缺失必须可检测,不能静默蒸发:界面可以合法地说“这部分状态随进程结束了“,不能合法地假装它从未存在。

九、总结

五组证人派完。先交代为什么不是前面说的六组:完成语义那一组在 Codex 里没有证人可传,§五 的不变量是判它缺席之后,我们替它提出的新证人。五组是现存的,第六组是该长的;缺席本身也是证词。把它们放回全书的框架里归位。配对与时序、降级、竞态这三组是纯炸弹类:一票否决,百分之百通过才放行,九百九十九次绿的抵不掉一次红的。兼容矩阵与历史核对是一致性类:它们不拦单次发布,拦的是回归。胶水层也有可量的东西:TTFT、turn 收敛时长,Codex 的协议自带 time_to_first_token_ms 和 duration_ms,零插桩就能拿到。但这类分数只做同引擎的纵向回归,不做跨产品排名:不同产品的协议形状不同,分数不可通约,硬排就是拿尺子量体重。全篇的产出方向是:接 fail-closed 的发布管道,不接排行榜。

在全书的地图上,这一篇认领的是评测卷四问地图上“协议“那层被测对象;四问之中,它主要回答“坏了会不会察觉“。评测卷讲统一定律:两个世界产出同一个绿灯,观测就是盲的;这一篇做的事,是在协议层把每个“两个世界“的格子找出来,一格配一名证人。

上一篇结尾说:界面的每一个承诺,往下挖两层会碰到一条协议的条款,挖三层会碰到一个 try/catch 分支。这一篇把这句话补完:挖到第几层不重要,重要的是每一层都该有一条断言住在那里。承诺不是被信守的,是被看守的。


参考与延伸

  • 写于 2026-10-07。
  • Codex 行号基准 rust-v0.154.0,HEAD 6b9826e3a。
  • 降级分支病例、guardian 延迟测试、版本并存事实整理自 2026-10-03/05 本机实证与源码亲验。
  • 降级病例的数据层结论(同一 codex_home、数据不断裂、核对会绿、/status 行消失)为 2026-10-07 晚接力复核增补。
  • §五的语义定性不变量与§六的异步等待显式语义为本书提出的设计,Codex 协议当前不含此面;文中已就地注明。

连接与会话——断线之后,谁还记得它讲到哪了

「界面」卷拆的是像素层:界面怎么画、历史归谁管、信什么。这一卷拆另一半,信任层:那些画面凭什么信、承诺凭什么兑现。准入线只有一条:只写决定某个界面承诺真假的基建。第一篇的题目,来自我写作期间被自己问住的第一个问题:SSE 流断了怎么办?换一台服务器重连呢?


一、停在半行字上的界面

流式输出的第 37 秒,界面停在一个写了一半的 Markdown 表格上。光标还在闪,加载动画还在转,而网络连接八秒前就断了。用户盯着屏幕分不清两种状态:“模型在想“和“管道死了”。麻烦在于,界面同样分不清,因为它不知道。

把用户在断线时刻的真实困惑列出来,一共三问:还连着吗?我漏了什么?从哪继续?这三问的答案没有一问在渲染层,全在连接的另一侧。这篇讲的就是让界面有能力诚实回答这三个问题的基建。反过来讲也成立:这三问答不了的界面,它显示的一切“实时状态“都是表演。

二、SSE 的出厂设置,和它的三个坑

先还 SSE 一个公道:协议设计者想过断线。每个事件可以带 id: 字段,浏览器原生的 EventSource 断线后自动重连,并把最后收到的 id 放进 Last-Event-ID 请求头带回去,服务端若配合,就能从断点续发。恢复机制是出厂设置,不是发明。

但 agent 客户端拿到手就碎了三个角。

坑一:原生重连根本用不上。 EventSource 不支持自定义请求头,带不了 Authorization。所以 agent 客户端几乎都用 fetch 手搓 SSE 流,而 fetch 没有自动重连:出厂设置里最值钱的那部分,正好是要被扔掉的那部分。重连、退避、断点游标,全部自己写。

坑二:中间层吞流。 nginx 默认缓冲响应、企业代理按住不转发,连接“活着“,数据不动。“连着但没数据“和“断了“在客户端不可区分,唯一的解法是应用层心跳。而心跳间隔是一个两头挨打的权衡:慢了撞上运营商 NAT 的空闲超时(TCP 常见几分钟),快了烧电,这个权衡在移动端还会加倍回来(基建第 2 篇的主线)。

坑三:Last-Event-ID 只是一个约定。 要它生效,服务端得肯留记录:每个事件有递增编号,且保留一个可重放的缓冲窗口。协议只定义了这个字段的格式,不担保任何一家服务端会照着重放。

最后是半包。SSE 帧层面协议自解,事件以空行分隔,Last-Event-ID 指向的永远是最后一个完整事件。真正的半包在应用层:工具调用的参数以 JSON 字符串增量流式下发,断线时你手里是半个 JSON。界面部分第 3 篇讲过 TUI 如何消费“半成品文档“,这是它的网络层孪生;评测卷序章的截断检测,换了个位置再来一次,不完整性是这个家族在每一层的老熟人。

三、行业的三个答案

断线恢复没有标准答案,2026 年的主流方案正在朝三个不同方向走。三个都核实过,其中一个是本地一手。

答案 A:删掉恢复,拥抱无状态(MCP,2026-07-28 修订)。 官方 changelog 写得很直接:“Remove SSE stream resumability and message redelivery (the Last-Event-ID header and SSE event IDs) from the Streamable HTTP transport.“SSE 事件 id 删了,Last-Event-ID 删了,独立的服务端推送流(GET stream)删了,连 Mcp-Session-Id 和初始化握手都删了,协议整体转向无状态优先。后果直白:流断在半路,在途结果作废,客户端在应用层重试。这是一次诚实的设计退让:与其让协议层承诺一个多数实现做不好的恢复语义,不如把问题连同自由一起交还给应用层。连接是易耗品,协议不替你留记录。

答案 B:把流镜像进外部存储(Vercel resumable-stream)。 服务端把流式 chunk 边发边镜像进 Redis(带 TTL),streamId 存在会话记录里;客户端断线后凭 id 请求续读,从最后一个收到的字节继续。连接在这里只是租来的加速器,事实在共享存储里,所以换一台服务器重连毫无障碍。边界也清楚:第三方测评指出它罩得住“同一设备刷新页面“,罩不住多端并发消费;TTL 过期,缓冲即蒸发。

答案 C:三层防线,自己存记录(kimi-code 的 kap-server/transcript,本地一手)。 这是界面部分第 7 篇事件流模型至今最完整的工程化样本,值得多写两段。

第一层,序号:每个 (session, agent) 流上的操作批次分配单调递增的 seq,订阅带着 transcript_since 游标。第二层,有界内存 journal:游标落在 journal 覆盖范围内就重放差量;覆盖不了,服务端如实回 complete: false,客户端降级为全量刷新,降级路径是一等公民,不是异常处理。第三层,磁盘事实源:每个 agent 一份 wire.jsonl 追加记录,冷会话由两级 fold 重建,连“关机时还挂起的用户交互“都折叠成 cancelled 记录在案,交互流的终态有交代。基线重置报文是 items-empty 的:历史永远走 REST 分页拉取,“快照 + 尾部增量“在真实产品里的样子。

三个答案,三种存放记录的位置:协议层拒绝留记录;应用层租外部存储;专门服务自己存三层记录。 没有谁赢,它们分别对应三种产品形态(工具协议、Web 应用、多端会话服务)。

四、纲领:重连语义由 source of truth 的位置决定

把三个答案和其余方案放进同一张表,规律可以归成一句:换服务器重连能不能成立,取决于事件的 source of truth 存在哪一层。

事实存放在重连语义代表部署重启时
连接里(进程内存)断线即丢,只能 sticky session最朴素的 WS 服务全部会话阵亡
有界 journal(内存)热续:游标在覆盖内重放差量kimi transcript ops journal丢最近一段
磁盘 log冷重建:慢但完整kimi wire.jsonl;Claude Code 会话文件无损
外部共享存储换服务器随意连,连接=租借加速器Vercel(Redis);Cloudflare Agents(每 Agent 一个 Durable Object,单写者正确性 + WebSocket 休眠:对象睡了连接还活着,这段时间不计算力费)无损
都不记断了就断了,应用层重试MCP 2026-07-28不适用(本来无状态)

界面部分第 11 篇说“统一 Event Log“是四个统一之一,当时它是一句架构主张;这张表是它的工程含义全集。顺带补一句 actor 档的注脚:Cloudflare Agents 的官方仓库里挂着一个重连竞态的 issue(#1837,移动网络抖动或重新部署弹跳 Durable Object 时,客户端 hook 在重连与续传之间赛跑)。每往上一档,省下的是会话状态,换来的是新的竞态。没有免费的档位。

五、幂等与序号:at-least-once 世界的生存守则

只要服务端肯重放,重复推送就不可避免,传输的现实是 at-least-once,不是 exactly-once。消费侧按事件 id 去重是基本功;真正会咬人的是副作用:工具已经执行了,确认事件在断线中丢了,重试会不会再执行一遍?

这里界面部分第 7 篇的三层分类拿到了第二生命。当初它为解释“不同 UI 消费事件的策略差异“而设计:执行流、副作用流、交互流。放进分布式语义里,它正好变成了重放安全性分类:执行流可重放(幂等投影)、副作用流不可重放(只能记录不能重做)、交互流要仲裁(第七节)。一个为界面写的分类法,在网络层一个字不用改。

序号的分配权同样有讲究。kimi 的答案是每个 (session, agent) 一个单调 seq,单写者换秩序,避免了多节点分配的全序难题。而它的契约里有一个细节值得单独说:seq 相关字段全部是可选的,不带 seq 的旧客户端自动降级为“丢信号驱动的全量刷新“。断线恢复与 schema 演进这两件最难同时满足的事,在同一份契约里和解了:新节点带游标热续,旧节点无游标慢刷,谁也不阻塞谁。

回到评测卷序章的问句:没报错就代表输出没问题吗?管道版的回答是:在 at-least-once 的世界里,“没报错“的诚实含义是“至少一次,可能更多,请保持幂等”。

六、单机同构版:你每天都在用的那台事件溯源服务器

这篇文章的全部难题,有一个零网络版本,你每天都在用。

Claude Code 把每个会话写成本地文件:~/.claude/projects/<工作目录转义>/<sessionId>.jsonl。本机取证看一眼结构:append-only 的行式 JSON,类型分布包括 user、assistant、attachment、queue-operation(输入排队)、cost-state(费用快照),一条不挑读者的 wire 事件流,每行带 sessionId 和时间戳。claude --resume 做的事,就是从这份文件重放重建会话。

对照第四节那张表:它的 source of truth 在磁盘 log 档,而“连接“这个东西根本不存在,所有断线重连问题被消解成“把文件读回来“。这不是玩具对照:kimi 的 wire.jsonl 冷重建就是这个模式的网络版,Vercel 的 Redis 是它的共享版,MCP 的应用层重试是承认了“读回来“的成本之后干脆不读。断线恢复的种种难题,都可以看成“把文件读回来“在不同网络距离上的变体。 单机文件、冷重建、热 journal、共享缓存、放弃恢复,是同一件事在不同距离上的几种做法。

七、交互流也要外置

最后补上断线故事里最容易被忘掉的角色:挂起的审批。

permission.requested 发出时用户正在地铁里,这个挂起对象必须和事件一样外置存活:进 log、有超时策略、能被推送唤醒(推送链路是基建第 2 篇的主战场)。多端竞争是它的分布式形态:桌面点了批准、手机点了拒绝,两个响应经过两台服务器,仲裁需要三件协议工作:先到先得的判定规则、事件版本号防旧覆新、后到端收到“已被他端处理“的收敛事件而不是一个失败。界面部分第 11 篇写过一句“谁先响应用谁的结果“,这十几个字背后就是这三件事。kimi 的 fold 把关机时挂起的交互折成 cancelled,是同一纪律的关机时刻版本。

八、总结

把三问对应到四档谱系,界面的权限边界就出来了:

状态在连接里journal 档磁盘/共享 log 档无状态档
“还连着吗”心跳,勉强心跳 + 游标水位心跳 + 游标 + 落盘确认只能说“我不知道“
“漏了什么”无法回答journal 覆盖内可答永远可答不可答,请重试
“从哪继续”不可承诺短窗口承诺“继续上次会话“按钮敢亮“重新开始”
UI 敢显示的实时转圈+ 断点续传提示+ 完整历史回看与多端只剩重试按钮

所以这一篇的结论可以压成一句:界面承诺的真假,不取决于渲染层多努力,取决于事实源存在哪一层。 半行字卡在屏幕上的那一刻,界面能说“正在重连,已恢复到第 N 个事件“,还是只能让动画继续转下去骗人,这个差别在上线之前,就已经被后端的一张表决定了。

下一篇把镜头从连接的两端拉近到拿在手里的那一端:一部随时会被操作系统杀掉的手机,如何在一次会话的每个站点(输入、发送、排队、流式、回看)保住“流畅“和“完整“这两件互相打架的事。


参考与延伸

  • 事实核查分层(截至 2026-09-28):MCP 部分引自官方 changelog(modelcontextprotocol.io/specification/2026-07-28/changelog,“Remove SSE stream resumability and message redelivery…“为原文引用)及多家第三方解读交叉。
  • Vercel 部分基于 AI SDK 官方文档(Chatbot Resume Streams,resumable-stream + Redis)与第三方边界测评。
  • Cloudflare 部分基于官方 Agents 文档(Agent class internals:DO 单写者、WebSocket 休眠)与仓库 issue #1837。
  • kimi-code 部分为本地一手阅读(1e553fc:packages/transcript/AGENTS.md 的 op-batch sequencing contract、packages/kap-server/AGENTS.md 的 journal/transcript_since/冷重建描述)。
  • Claude Code 会话文件为本机取证(2026-09-28,类型分布为单样本)。
  • SSE 协议行为(id/Last-Event-ID/EventSource 限制)为标准协议常识。

一条消息的生命线——移动端会话的六个断点

上一篇讲连接的两端,这一篇讲拿在手里的一端。移动端 agent 有一个所有桌面讨论都会漏掉的前提:用户会在任意时刻离开。打字打到一半微信来了,按下发送的瞬间锁屏了,流式输出到一半进电梯了。本篇沿一条消息的生命线设六个站点,每个站点都问同一个问题:用户在这里断掉,会话还能不能既流畅又完整地活下来。


零、先立一个不对称

移动端工程里所有关于“断“的决策,都由一个平台事实定价:iOS 给应用退后台后的宽限是几十秒量级,之后进程挂起。没有后台特权的应用,连接的死亡不是风险,是日程表上已排定的事件。Android 好不了多少,国产厂商的后台查杀比 AOSP 更积极。

这个事实制造了一个贯穿六站的不对称:用户的输入是毫秒级的,网络的宽限是秒级的,而一场 agent 回复是分钟级的。 三件事的时间常数差着两个数量级,所以“会话不断“这个承诺,永远不能靠“连接不断“来兑现,只能靠“断了能接“来兑现。接的逻辑,就是六个站点各自的那道工序。

站点一:输入中(还没按发送)就切走

用户打了 200 字,微信弹窗,切走,进程十秒后被挂起或杀死。回来时草稿还在不在?

错误答案是“监听退后台事件,临走前保存“。错误在哪:被杀和崩溃都不给回调,退后台虽然有回调,留给你写盘的时间也很短,willResignActive 不是遗嘱,进程可能根本等不到执行它的机会。把持久化押在一个不保证送达的事件上,等于把草稿押在运气上。

正确姿势是持续写:草稿每次变化就落盘,赌的不是“能等到告别“,而是“丢得足够少“。FlowDown 的实现是现成样本(ConversationManager.swift):内存字典 temporaryEditorObjects 的 didSet 里挂一个 1 秒防抖的保存任务(perform(#selector(saveObjects), afterDelay: 1.0),新修改会取消旧任务),到点后在后台线程写入 UserDefaults 支撑的 @TypedStorage;启动时回灌并记日志“loaded N temporary editor objects“。

注意它连代价都写得明明白白:防抖窗口 1 秒,意味着杀死发生在最后一次击键后的 1 秒内会丢最后几个字。这是一次有意识的取舍,用“最多丢 1 秒“换“每秒写盘一次“的低频,而不是假装存在零丢失的免费方案。界面上那句“已保存“要不要显示、按什么粒度显示,就是这次取舍在用户那一侧的交代。

站点二:按下发送的瞬间切走

更危险的一站,因为发送是一个事务,事务最怕执行到一半断电。

用户按了发送,请求进了网络栈,进程被挂起,这条消息到底发出去了没有?回来之后,界面该怎么显示?如果客户端这时自动重发,服务器会不会收到两条?

工程答案是发件箱(outbox)模式,三条纪律:

  1. 本地事务先于网络事务:发送动作先落盘(进发件箱),再传输。界面状态跟着发件箱走,“排队中 / 已发出 / 已送达”,每个状态都是本地可查的事实,不猜。
  2. 幂等 request id:每条消息带客户端生成的唯一 id。重发时服务器凭 id 去重,“我可能发过“和“我肯定没发过“从此可区分。这是基建第 1 篇说的 at-least-once 世界的基本功。
  3. 宽限的用法:几十秒的后台宽限,够把一条消息推出网络栈,不够流完一场回复。宽限期该做的事是“把发件箱清空“,不是“把会话跑完“,认清时间常数,才知道宽限该花在哪。

一个旁证:本机 Claude Code 的会话 JSONL 里,type: "queue-operation" 的第一行就是 "operation": "enqueue",用户输入在一开始就被记成排队事件,而不是“即发即忘“的网络动作。把输入当事件记下来,是单机版的发件箱;移动端要做的只是让它穿过网络还成立。

站点三:已发出、还没开始流式(在排队或预处理)

消息确认送达之后、回复开始之前,客户端切走,这一站的问题最少,但有一个硬前提:服务端的 ack 必须是落过盘的。“收到“不能只存在于那台连接着的进程内存里,否则部署重启的瞬间,用户以为已发出的消息就进了量子态。

ack 落盘之后,这一站的完整性责任就整体移交给服务端了。这正是下篇要立的那条第一原则在移动端的兑现:agent loop 不能拥有 socket,执行归执行,连接归连接,客户端的生死从这一刻起与会话解耦。

站点四:流式输出到一半切走

用户看着半个表格,进电梯,切走。接下来必然发生的事按剧本走:数十秒内进程挂起,连接断掉。记住,这是确定事件,设计时当日程处理,不当异常处理。

断掉之后,责任分两半。服务端那一半:agent 继续跑,产出的事件继续落 log(基建第 1 篇的全部内容)。客户端这一半小得惊人:只欠一个游标,记住自己最后收到的事件位置(last event id / seq),其余什么都不用做。回放、补齐、续传,全是回来之后的事。

这一站还有一个前台版本:网络切换(WiFi↔蜂窝换了 IP),连接半死,TCP 还“活着“,但永远等不来数据。对策是主动保活探测(心跳超时即判死)+ 快速重连 + 凭游标续传,把“半开连接“的窗口压到秒级。判死要快,是因为用户对“转圈但不更新“的容忍度,比对“断线重连提示“低得多,诚实的坏消息好过沉默的坏状态,这句话在六站里都成立。

站点五:流式中回来看(最痛的一站)

用户回来了。此刻距离断线可能过去了三分钟,也可能三小时。屏幕上那半个表格怎么办?

第一步是追平:凭游标向服务端要差量。追平的正确形态是快照 + 尾部增量,基建第 1 篇拆过的 kimi transcript 就是活样本(transcript_since 游标、journal 覆盖内重放、覆盖不了降级全量)。切记不要全量重放几千条事件:移动端的 CPU、电量、流量都在反对。

第二步是追平期间的脸面。“正在同步…“不是敷衍,是投影设计,用户需要知道当前画面是“落后的事实“还是“最新的事实”,这两者对信任的含义完全不同(界面部分第 19 篇的信任边界在时间维度的投影)。

第三步是弱网下的流畅降级。完整性和流畅性在这一站公开打架:带宽和电量都告急时,把事件粒度降下来(低频刷新、只更新尾部摘要行、折叠中间过程),先把“活着且最新“保住,带宽宽裕再补全渲染。通知要背压(下篇展开),会话内更新同样要背压,这是同一个原则的两个方向。

这一站还有个配角值得记:FlowDown 在流式期间把收到的字符增量累计喂给 Live Activity(countIncomingTokens),锁屏和灵动岛上有一个实时跳动的字数。用户切走了,锁屏上那行小字就是整个会话在“离开期间“的最小投影:不完整,但诚实,且免费。

站点六:完成之后回看

最好的一站,如果前三站都做对了,这一站几乎是免费的。回复完成后,内容由服务端定稿落盘(界面部分第 18 篇拆过 FlowDown 的修补序列与 save()),客户端回看时读到的就是档案而不是直播。完整性在这一站不是客户端的功能,是前五站工程的总和。

总结

把六站排回去看,每站的答案其实都是同一句话的变体:把“必须记住的事“从连接和进程里搬出来,搬进比它们活得久的东西,草稿进 UserDefaults,输入进发件箱,消息进服务端 log,位置进游标,进度进锁屏投影,成品进档案。连接、进程、甚至前台界面,都只是这些事实的临时租客。

流畅和完整这对冤家也是这么和解的:完整性靠事实外置(搬到磁盘和服务端),流畅性靠降级自由(画面可以随时扔,因为事实扔不掉)。下一篇(二·下)把这六个站点背后的架构代价一次摊开:被操作系统禁止的长连接、只肯当信号用的推送通道、替 agent 跑工具的服务端工作区,以及那句话作为第一原则的完整含义:agent loop 不能拥有 socket。


参考与延伸

  • 一手取证:FlowDown b2cecfd6(ConversationManager.swift 的 temporaryEditorObjects 防抖持久化、ConversationSessionManager.swift 的 countIncomingTokens/Live Activity、Pipeline/ 的流式与定稿路径)。
  • Claude Code 本机会话 JSONL(type: "queue-operation"/"operation": "enqueue",2026-09-28 取证)。
  • 平台行为(iOS 后台宽限为数十秒量级、挂起与杀死可能无回调、网络切换导致 TCP 半开)为移动端工程常识,按量级表述未引具体数字。
  • 快照+尾部增量与游标机制的工程细节引自基建第 1 篇的核查(kimi-code 1e553fc)。

移动端的架构代价——推送、工作区与一条第一原则

上篇沿一条消息的生命线走了六个站点,每个站点的答案都是“把事实搬进比连接活得久的东西”。下篇讲这个答案背后的代价:被操作系统禁止的长连接、只肯当信号用的推送通道、被应用商店放大的版本漂移、替 agent 跑工具的服务端工作区。这些是移动端被迫接受的架构条款,最后收进一句第一原则。


一、第 4 秒的审批卡片

推送弹出来:“Agent 请求批准安装依赖”。用户点开:白屏,logo,转圈,四秒之后审批卡片才出现。这四秒用户在替谁等待?

把冷启动路径拆开看:点推送 → 进程冷启动 → 认证(token 过期就再等等)→ 建连 → 追平事件 → 渲染会话 → 审批卡片才终于有上下文可挂。链条上每一步都可能失败,而审批是硬实时的交互流,agent 停在那里等,token 在烧。四秒不是性能问题,是架构问题:推送承诺了一个交互,而兑现它要穿过整条冷启动链。深链直达会话、token 预刷新、追平优先渲染审批相关事件(先画卡片后补历史),都是对这四秒的专项工程,但这些优化成立的前提,是下面这些架构条款先被接受。

二、第一性条款:长连接是被禁止的

上篇立过的不对称,这里升级成设计公理。桌面端的架构假设是“长连为主,断线是要恢复的异常“;移动端的现实是不连接才是常态,连接是打开应用那几十秒里才存在的临时窗口。iOS 没有后台特权的应用退后台数十秒即挂起,音频/定位/VoIP 那类长驻 entitlement 轮不到聊天应用;Android 阵营里国产厂商的电池优化比 AOSP 激进得多,长连接在后台存活的期望值按零设计不算悲观。

这个公理改变了一切:**推送才是唯一常开的通道,连接只是加速器。**由此推出下面几条。

三、推送是信号,不是传输

推送通道的物理限制决定了它只能当门铃用:payload 有几千字节的上限,不保证顺序、不保证送达。所以正确的分工是:推送只说“该同步了“,内容永远回连接里拿。把审批的完整上下文塞进推送 payload 的设计,是在不可靠信道上假装可靠,第一个被坑的场景就是用户在地铁里点开了一条早已过时的审批。

门铃自己也一身坑。静默推送(不响铃、只唤同步的那种)被系统性限流:低优先级、会被合并延迟,低电量模式更狠,用户关掉后台 App 刷新则基本不达。所以推送不可达要有兜底:打开应用时的主动轮询。国内还要再加一层现实:FCM 不可用,接厂商推送联盟,每家的到达率和后台策略都不同,工程上等于维护一条多通道抽象层,而且永远测不全。

然后是两条推送的产品学:

通知也要背压。 Agent 跑完 30 个工具调用,不该产出 30 条推送。合并、摘要、按重要性分级,通知频率本身就是产品参数,和上篇“会话内更新降级“是同一个背压原则的两个方向:事件流可以很密,打扰必须很稀。

通知是交互流的最小投影。 标题加一行描述加两个按钮,就是 permission.requested 事件在锁屏上的完整投影,这意味着通知按钮本身构成一条 permission.resolved 的回传通道。于是界面部分第 19 篇的信任边界问题在锁屏上重现,而且更尖锐:锁屏内容会被旁人看到(代码片段、密钥名该不该进通知?);通知直批省了打开应用的四秒,但高风险操作要不要过一次生物识别?便捷和安全在这条最小投影上没有免费的双全,每个产品都得画自己的线,而大多数产品目前还没意识到需要画。

四、版本漂移被应用商店放大

Web 客户端今晚发布今晚全量;移动客户端发版要过审,用户更新看心情,几周前的旧客户端是常态,不是遗留。对事件流协议这意味着:新事件类型必须可跳过(不认识就忽略,不崩),新字段必须可选。基建第 1 篇里 kimi 那份契约的姿势值得再引一次:seq 相关字段全部可选,旧客户端自动降级为丢信号驱动的全量刷新,宽容旧端不是兼容性礼貌,是移动端的生存环境。 桌面端可以把 schema 演进当工程问题慢慢做,移动端则从协议设计的第一天就受它约束。

五、服务端执行环境:agent 到底跑在哪

移动端是瘦客户端,这四个字把执行整体搬到了服务端,而“跑在哪“本身就是一整套生命周期工程。

工作区是有生命周期的。 工具调用要碰文件系统和 git,服务端就得给每个会话配一个工作区(容器或等价物):创建、挂起、快照、迁移、回收,每一步都有成本。移动端用户拍完审批就走了,工作区还热着,TTL 定多长,挂起要不要快照,都是钱。

审批挂起与会话休眠。 用户三小时不回,agent 停在等审批的状态上,会话资源怎么办?Cloudflare 的 Durable Object 休眠给了一个参考形态:对象睡了,WebSocket 状态还保着,消息到达即唤醒,休眠期不收活跃算力的钱。“等待“在服务端是被明码计价的资源,谁来付钱、按什么计,是移动端产品没法回避的定价题,因为等待的发起者(用户离开)和付费者未必是同一个预期。

云和本地抢同一个仓库。 云端 agent 在自己的工作区里跑,用户的桌面可能正开着同一个 repo,两边的改动如何合流,是界面部分第 11 篇“统一 Workspace Model“在云时代的完整形态。这个问题目前没有谁真正答好,记为开放题。

工作区还是一个网络主体。 容器或 microVM 划定了文件系统边界,却没有自动划定网络边界:agent 在工作区里可以发任意出站连接,而它正是一个会被自己处理的输入策反的执行者。一条恶意工具输出,就能借 curl 或 npm 的 postinstall 把环境变量送出去。这类流量走 shell、不走 MCP,下一篇的工具边界管不到它。执行环境因此迟早要补上第三道边界:按 agent 实例签发的短命身份、默认拒绝的出站白名单,且强制执行点必须在 agent 进程之外(胶水层声明“需要连谁“,沙箱网关负责“别的什么都不通“)。还有一条传统网络里不存在的通道要单独盯:到模型 API 的那条 TLS 既是指令输入通道,又是带宽最高的数据外泄出口。两类历来分开管控的流量,在 agent 这里合成了一条加密流。这层目前没有公认形态,与云端工作区并记为开放题。

六、总结

把上下两篇收进一句话:agent loop 不能拥有 socket。

执行不拥有连接(挂起、杀进程、换服务器,会话继续);连接不携带事实(断了,游标和 log 还在);推送不携带内容(门铃只负责叫人);客户端不携带状态(它的每样记忆都有磁盘或服务端的备份)。移动端不是这套原则的一个应用场景,它是最苛刻的那个证明环境:进程朝不保夕、网络七零八落、版本几周漂移,在这样的地基上还能兑现“流畅且完整“,靠的就是把每一样事实都安放在比进程、比连接、比画面活得久的地方。

界面部分第 11 篇写过“Mobile 是 Companion,不是主战场“,从渲染负担看它依然成立;但从架构纪律看要补一句:移动端是这个行业里最诚实的甲方。 它不允许任何“先连着再说“的懒惰假设,每一条都在逼你把事实和传输分开。桌面端能蒙混过关的架构,在手机上四秒内露馅。

下一篇回到地面:agent 与编辑器、前端、工具之间那三套正在三国杀的协议,MCP、ACP、AG-UI,三个边界的代价各落在谁身上。


参考与延伸

  • 核查分层:Durable Object 休眠与单写者语义基于 Cloudflare Agents 官方文档(同基建第 1 篇核查)。
  • APNs payload 上限与静默推送限流按平台公开行为的量级表述(数千字节;低优先级、合并、受低电量与后台刷新设置影响),未引具体政策编号。
  • 厂商推送联盟为国内公开现状。
  • kimi 契约的可选字段姿态引自基建第 1 篇的本地一手核查(1e553fc)。
  • 冷启动路径、通知直批安全边界、出站身份与网络管控为设计层论述(后者为开放题,未引具体产品)。

协议三边界——MCP、ACP、AG-UI,代价各落在谁身上

这一篇讲“界面”这个词的复数化:同一个 agent 要同时面对三类对话者(工具、编辑器、浏览器前端),行业为这三条边界各造了一套协议:MCP、ACP、AG-UI。它们不是竞争关系,是同一张地图上的三条国境线。这篇讲每条线怎么划的、为什么必须这么划,以及一个有意思的规律:协议要不要有会话,取决于边界对面那位有没有状态。


一、一次“换壳“背后

先看一个每个人都在做的动作:给 agent 换个界面。今天它在你的终端里跑,明天你把它装进 Zed 的侧栏,后天它出现在某个 Web 面板上。感觉上你在换皮肤,实际上你每换一次,就穿过了一条协议边界:agent 跟终端说话、跟编辑器说话、跟浏览器前端说话,用的是三套完全不同的语言。

把三条边界的方向性先摆正,它们不是同一种关系的三个名字:

  • agent ↔ 工具(MCP):agent 是主语,它去征用外界的能力;
  • agent ↔ 编辑器(ACP):编辑器是主语,它去征用一个 agent;
  • agent ↔ 前端(AG-UI):前端是消费者,它订阅 agent 的事件流。

主语不同,代价落在谁身上也不同。逐条看。

二、工具边界:MCP 和它的无状态豪赌

MCP 管的是能力发现和结构化 IO:工具怎么声明自己的 schema、结果怎么以结构化形态返回(structuredContent 明说是给模型的)。这条边界上,基建第 1 篇已经核查过 2026-07-28 那次激进的无状态化重写:会话头删了,断线恢复删了,官方 changelog 的措辞是把这些“从传输里移除“,流断在半路,结果作废,客户端在应用层重试。

当时把它当传输层新闻讲,这里补上边界层的解读:MCP 敢这么做,是因为多数工具调用近似纯函数。调用、返回、结束,边界对面没有需要延续的视图状态,会话性对这条边界是奢侈品而非必需品。无状态化的代价是真实的(会话被推给两端自己解决),但这个代价恰好落在了一个扛得住的位置。

三、编辑器边界:ACP 的“LSP 时刻“

ACP 面对的问题形状是编辑器圈的老朋友:编辑器不想为每个 agent 写一遍 UI,agent 不想为每个编辑器写一遍适配,这正是 LSP 解决过的问题,只是主角从语言换成了 agent。所以它的定位被叫做“AI coding agent 的 LSP 时刻“:开放标准,JSON-RPC over stdio/WebSocket,agent 作为子进程被编辑器拉起,编辑器从此是一个能装任何 agent 的通用投影面。

生态现状(2026-09 核实):Zed 的 ACP Registry 已上线,入驻名单包括 Claude Code、Codex CLI、GitHub Copilot CLI、OpenCode、Cursor、Pi;JetBrains 在 2026 年 1 月开了自家的 ACP Agent Registry,覆盖 Gemini CLI、Claude Code、Auggie、OpenCode、Copilot。接入深度不一:Copilot CLI 和 Gemini CLI 是原生支持,Claude Code 和 Codex 走适配器。

一手注脚来自 kimi-code:仓库里有一个专门的 packages/acp-adapter 包,依赖 @agentclientprotocol/sdk@0.23.0,月之暗面给自家 agent 配的早期周边里,编辑器适配层占了一个正式包位。测试文件名把适配的难点泄露得很直白:tool-call-stream(流式工具调用怎么过桥)、set-session-config-option(会话配置怎么映射)。过协议边界的从来不只是事件,还有两侧各自的会话语义。

这条边界为什么必须有会话?因为对面的编辑器是一个深度有状态的投影面:打开的文件、光标位置、diff 面板的展开状态。边界对面有状态,协议就躲不开会话。第 7 篇说“编辑器是 agent 事件流的投影之一“,ACP 做的事就是给这句话定契约;系列早期引过的 zacp(ACP 协议驱动的多 Agent WebUI)是同一思想在 Web 端的自发实践,协议出现之前,论点已经先在野生实现里活着了。

四、前端边界:AG-UI,把事件流写成协议

AG-UI(CopilotKit 出品)管 agent 和浏览器前端的对话:SSE 传输,十六七类事件(各家文档计数略有出入),按组覆盖生命周期、文本流、工具调用、状态同步。第 7 篇那句“agent 是一条事件流,UI 是投影“,在这里被直接产品化成了 wire format,前端组件消费的正是这套事件。

它有一个和 MCP 方向完全相反的设计,值得单独看:工具定义放在前端,运行时递给 agent。MCP 的世界观是工具在服务端等着被 agent 发现;AG-UI 的世界观是前端把工具交给 agent 执行。同一种东西(工具),两条协议给出了相反的归属答案,因为它们站在不同的边界上,替不同的主语说话。前端拥有工具定义,等于让界面的作者(而不是 agent 的作者)决定这个产品里 agent 能碰到什么,权限模型从 agent 侧移到了界面侧。

五、对照表和一个规律

MCPACPAG-UI
边界agent ↔ 工具agent ↔ 编辑器agent ↔ 前端
主语agent 征用能力编辑器征用 agent前端订阅事件流
会话性无(2026-07 起显式无状态)有(会话配置、流式工具调用)有(事件流 + 状态同步)
工具归属服务端,等发现各自协商前端定义,递给 agent
生态事实垄断工具边界Zed + JetBrains 两个 RegistryCopilotKit 系 + 框架伙伴

规律就藏在“会话性“那一行:协议的会话性由边界另一端是否有状态决定。 工具无视图,MCP 可以拍掉会话;编辑器有状态,ACP 必须扛住会话;前端要增量,AG-UI 干脆把整个协议做成事件流。选协议之前先看对面是谁,跟第 11 篇选端先看约束是同一个思考方式。

另有两个代价也记下。其一,协议会咬人:MCP 2026-07-28 删 GET stream 的破坏性修订就是现场案例,依赖协议承诺的字段(比如断线恢复)说没就没,基建第 1 篇里 kimi 那份“seq 字段全可选“的契约,就是客户端对协议咬人的标准防御。其二,registry 也在割据:Zed 一个、JetBrains 一个,agent 要么入驻两次要么选边,CLAUDE.md 和 AGENTS.md 的双写,在协议层换了个名字重演。

六、总结

把三篇基建的结论合到界面上:ACP 决定编辑器能不能内联渲染 agent 的 diff、能不能把权限请求嵌进侧栏;AG-UI 决定前端组件收到的是增量还是全量、状态会不会静默漂移;MCP 的无状态化决定断线那一刻,工具调用这条支路上的界面敢不敢承诺续传。界面的每一个承诺,往下挖两层都会碰到一条协议的条款。

基建卷到此收口:连接(基建第 1 篇)、端(基建第 2 篇上下两篇)、协议(本篇),讲的是事件流离开本机之后的全部旅程。旅程之外还有一个这三篇没请进来的角色:网络本身。当 principal 是一个会被输入策反、还会瞬时繁殖子代的 agent,“谁能连谁、能碰什么“该按什么身份强制执行,今天还散落在工具授权和沙箱配置里,没有长成自己的一层(基建第 2 篇下篇的末尾把它和云端工作区并记为开放题)。下一卷换一个问题:这些机制建起来之后,怎么证明它们真的在工作。那是评测卷的事。


参考与延伸

  • 核查分层(截至 2026-09-28):ACP Registry 名单与接入方式基于 Zed 官方博客与文档、JetBrains 官方博客(2026-01)及 agentclientprotocol.com 目录,多源交叉。
  • AG-UI 事件分组基于 CopilotKit 官方资料与第三方教程(事件计数 16–17 存在版本差异,按量级表述)。
  • MCP 无状态化修订引自基建第 1 篇核查过的官方 changelog。
  • kimi-code 一手(1e553fc:packages/acp-adapter、@agentclientprotocol/sdk@0.23.0、测试文件名)。
  • zacp 为系列既有引用(helloxz/zacp)。

没报错,就代表输出没问题吗?

前面的篇章讲的是“看得见的一半“(渲染引擎、字符网格、权限 UX),接着是看不见的另一半(连接、会话、协议边界)。两个世界的接缝处还漏着一类反复出现的故障,先从它说起,它是我做 Agent 界面这几年见过的最典型的坑。


一、最坑的坏法不是报错而是不报错

这段时间做 agent,得到了很多经验和教训,其中有一条越来越确定:流式输出最容易漏的一种坏法不是报错,是答案被截断了,而它看起来是完整的。

这条教训的起点是我非常烂的网络和代理。我的代理链路一直不太稳,断流、超时是家常便饭。上个月我让模型写一份比较长的分析,出来的东西格式工整、段落齐全,但总觉得话说到一半就没了,末尾该有的一半内容根本没有(因为我在提示词里做了一些设置,缺了一些短小但非常关键的内容)。

最开始我以为是上下文过长的问题,但后来在上下文明显充足的情况下还是发生了,这才引起了我的注意。

接下来我以为这就是代理的锅,网络修好了事情就过去了。但又一次发生之后,激起了我的好奇心和斗志,开始深究下去。

真正研究下去才发现:就算代理完全 OK,这个问题照样有概率触发,包括但不限于以下几种情况:

  1. token 上限会把回答拦腰截断,
  2. 网关可能弄丢最后一个 chunk,
  3. SDK 的默认值会把“连接被悄悄关了“当成正常结束。

代理的问题只是让我撞见它的那扇门,门后面是一整类故障,而它们共同的特点是:问题发生了,工具从头到尾不告诉我!

这引出了我给“一次流式输出到底完不完整“设计判定逻辑时定的规矩:complete 只能放在最后,它不能也不应该是默认值,而是前面的检查全都没命中才轮得到的兜底。也就是说,“没证据说坏了”不等于“证据说没坏”,看起来完整,得举证才能算数。

于是我去翻了几个比较熟悉的开源项目的代码,看看它们是怎么做的,结果发现了一些很有意思的事。

先把结论放这:判定一条流式回答完不完整,在内容层永远做不出来,必须下沉到协议层。 下面讲为什么,以及三个真实项目各自是怎么(没有)解决它的。

二、为什么“看起来完整“是常态

先交代背景。做过 Markdown 相关应用的人都知道,Markdown 的格式是后置的,代码块要看到收尾的三个反引号才知道代码结束了,表格要看到下一行才知道上一行是不是最后一行。这一点界面部分第 3、9 篇讲过,这里只说它和截断的关系:

因为格式后置,很多时候截断的回答渲染出来毫无破绽。

模型通过 SSE 流式吐内容,每个事件大概长这样:

data: {"choices":[{"delta":{"content":"## 结"},"finish_reason":null}]}

data: {"choices":[{"delta":{"content":"论\n\n好的"},"finish_reason":null}]}

data: {"choices":[{"delta":{},"finish_reason":"stop"}]}

data: [DONE]

正文一个 chunk 一个 chunk 来,每个 chunk 自己不带结束信息。现在假设流在第二个 chunk 之后因为网络问题断了。你拼出来的文本是 ## 结论\n\n好的。渲染出来是一段完全正常的 Markdown,没有任何报错,也符合阅读习惯,看不出这里出了问题。

所以“看起来对不对“不能作为判据。

三、complete 不是默认给的

到了协议层,第一个要纠正的是默认值。

绝大多数系统的默认值是反的:拿到流,就默认当完整。try 包住、异常没有抛出、循环正常结束就代表这次回答可用。这个默认值错在哪?“没证据说坏了“不等于“证据说没坏”。 结束不是一个自然发生的事实,是一个需要证明的事件。所以我的规矩是:complete 只能放在最后,因为它不是默认值,是前面的检查全都没命中才轮得到的兜底档。

3.1 从故障形态推状态机

“结束需要举证”,那要举哪些证?我的做法是把失败形态一个一个枚举出来,每种形态对应一个状态:

transport_error        连接本身就失败了
no_end_marker          连接活着,但流被关了,结束标记没等到
buffer_residual        流正常关了,可缓冲区里还剩半个没解析的事件
missing_finish_reason  一切正常,但从头到尾没见过结束原因
complete               以上全部排除,才轮到我

这五个状态是我多次尝试后得到的失败模式穷举:从外往里数,网络连接、网络流、事件、信号,每一层各有一种坏法。complete 排在最后,是因为它是排除下来的兜底产物。

枚举的价值在于它和 “try/except” 的区别:异常只能抓到你预想过的失败,枚举强迫你把“一条流可能怎么坏“逐层看过一遍。看完你会发现,多数实现的防御只覆盖了第一层:网络连接错误靠异常体系兜底,后面三层全是裸的。

3.2 结束需要双保险

直接看第四层,这是最容易被省掉的一层。

一条流正常收尾,应该有两个互相独立的信号:关闭标记(SSE 的 data: [DONE])和结束原因(最后一个数据 chunk 里的 finish_reason:stop / length / tool_calls…)。结束原因可以理解为协议替 Markdown“补发的结尾信息“,正文里看不出来的事,协议单独告诉你一次。

这两个信号缺一不可,因为它们会单独阵亡。最典型的死法:网关转发时把最后一个数据 chunk 弄丢了,只放行了 [DONE]。只查关闭标记的实现,对这种故障全线失守;反过来只查 finish_reason 也一样。我的判定标准是三条,任一命中就判不完整:结束标记没等到、缓冲区里有没解析完的字节、从头到尾没见过一个结束原因。前两条各管一层,第三条管的就是“证人缺了一个“的现场。

如果你认真看了前面的文字,会注意到:前面枚举了四个失败状态,这里怎么只剩三条?不矛盾。transport_error 和 no_end_marker 在观测上折叠成了同一条,因为连接都死了,结束标记必然没等到。状态机按原因分四类,是为了标准化地归类原因,而这条录制到底是“连接断了“还是“连接活着但流被关了“,事后排查时是两回事。

结束需要双保险,缺一个都不算数。

3.3 收尾不能押注在一个等不来的信号上

第三类坏法藏得更深(也是源自我稀烂的网络,笑)。SSE 的事件之间靠空行分隔,解析器攒到一个空行才敢处理前面的事件。如果某个超大事件中间网络卡住,空行永远不来,这个“攒了一半的事件“就无界地占着内存:业务逻辑永远不触发,而且没有任何报错,进程看上去完全健康。

对付它的办法不是“耐心等“,而是大小上限:上限到了必须自己能触发收尾,落到的状态是 limit_exceeded,不是“再等等“。等不来的信号不能做唯一的收尾条件。这是同一条规矩的第二个侧面:complete 不能当默认值,“结束“也不能押在一个不保证会来的信号上。

3.4 记状态,不抄现场

最后一条和前面几条画风不同,但同样来自实践(依然源自我稀烂的网络,笑哭):失败记录里只许记状态,不许抄原始报文。

原因是断流没有体面的死法。一条被掐断的流,断点可以停在任何字节上,正好停在一段敏感文本中间是常态。所以摘要和日志里写的是“这条录制落在 missing_finish_reason“,而不是把半截报文抄进去。因为要知道的是它坏了、坏在哪一类,不是它坏成什么样。这条值得做成测试断言,而不只是代码约定:约定很容易在某次重构里被悄悄拆掉,断言则不太会。

四、拿这把尺子去量真实世界

带着这套判定标准,我去翻了三个主流开源项目的源码。过程和结果都很有意思,尺子还没落下,先撞上两个反转。

反转一:连“数清楚装了多少个检查“都得先搞清架构。 我最初的结论是“截断检查缺失在某个库的 generate 主循环里“,顺着代码查下去才发现,这个仓库里有两套同构的 LLM 引擎:我看的那套库,主 agent 根本不走;真正的主引擎在另一个包里,有自己的 requester、自己的 finish reason 枚举、自己的空响应检查。完整性检查这种事,装错了包等于没装。如果不做这一层核实,我后续所有的“有没有防护“结论都会张冠李戴。

反转二:不是静默,是写错了对象。 搞清楚架构之后再问“主 agent 的回答被截断时,用户看到什么“:截断标志其实被算出来了,却在 turn 结束事件里被丢弃;TUI 倒是会弹一条提示,但文案是从工具调用视角写的。纯文本回答被截断时,用户看到的是“Model hit max_tokens — no tool call was emitted“,不会意识到上面的回答本身是半截的;无头模式和编辑器插件客户端则完全没有感知。所以准确的表述不是“毫无防护“,是:他们知道截断发生了,但警告写错了对象。

把尺子正式放上去,三个项目是三个数据点:

kimi-cli(Python,已归档)——零个检查。 finish_reason 全库生产代码零处读取。SSE 解析整个委托给 SDK,而 SDK 的默认行为正好是最差的那种:[DONE] 只是提前退出,服务端直接关连接时循环自然耗尽,不抛任何错,“收到 [DONE]“和“连接被悄悄关了“对上层完全不可区分;半个事件没有空行分隔则被静默丢弃。它仅有的防线是看“收到了什么内容“的形状启发式(空响应报错、纯思考无正文报错),但只要流出过任何一段正文,半截回答就被无条件收下。讽刺的是它每次请求都主动设 max_completion_tokens,token 截断是常态风险。上个月它发了 1.52.0,最终版,仓库归档。这个漏洞永远定格了:库默认值照单全收的代价是永久的。

kimi-code(TypeScript,继任者)——装了一个点,还是对的点。 它修了前者的可观测性:统一的 finish reason 体系(OpenAI length、Anthropic max_tokens、Gemini MAX_TOKENS 归一化),信号一路透传到事件和错误文案。截断的硬检查也确实存在——在子 agent 的 final summary 边界上:summary 被截断,整个 run 失败。这个点的位置选得很有水平,因为 summary 是给 parent 的机器消费的契约,半截契约比没有契约更糟。但主 agent 自己的回答,就是上面反转二的那一幕:同一个故障模式,在一个边界上硬检查,在另一个边界上静默加写错对象的提示。

codex(Rust)——四层检查,做成了协议层不变量。 它走的协议不同,等价信号是 response.completed 事件。这个检查它不是做了一层,是四层:SSE 层、WebSocket 层、turn 主循环、事件映射层,各自独立校验“流关了但终止事件没见过“。前三层命中就显式注入错误;事件映射层不拦截,但把这个失败单独记进 inference trace,连“这种事发生过几次“都要留下记录。compaction 的两条流式路径也各自复制了同一个检查。注入的错误默认重试数次,重试期间 TUI 显示重连计数且不写入聊天历史。底层 SSE 库对流关闭但无终止标记的情况什么都不做,所以这四层是手工固化的。在 codex 里,“流断了、回合却看似正常结束“这条路径不存在。

吐槽一句,codex 不愧是成熟的产品,在其他方面的对比研究里,codex 在各种边界处理上也明显更好。

三个数据点放在一起,规律很清楚了:完整性判定不是“有或没有“的问题,是“在多少个边界上装了多少个检查“的问题。 而比数量更难得的是质量:装在正确的边界上,写给正确的读者看。装检查不难,这才是难的部分。

我把 kimi-code 那个不对称整理成了 一个 issue 提给官方,附了复现和修法建议。截至 2026 年 11 月,这个 issue 还开着。

五、核实先于判断

这次从发现问题到发出 issue,最大的教训不在技术层面:一句不实的描述足以让整个报告的可信度归零。

如果我按最初的口径发出去——“主循环对截断零防护”——维护者第一次打开 TUI 代码就能证伪我。是复查推翻了两个假设之后,论点才站得住的。而好的缺陷报告还有一个技巧:论点落在不对称上。“这里坏了“不如“同一个故障模式在 A 处硬检查、在 B 处静默“有说服力:后者把项目自己已有的价值判断当成了标尺,维护者很难拒绝补平自己的逻辑。

这和第 3 节那条“记状态,不抄现场“其实是同一件事的两面:对自己的日志脱敏,对别人的报告核实,都只交付经过验证的状态,不交付未经核实的现场。

六、这个系列要讲什么

回到开头那句:截断的回答看起来是完整的。

我最开始的想法,是因为做了 agent 的 TUI 和 GUI,尤其在 Markdown 流式输出那部分踩了很多坑,有不少经验和教训,想分享出来。但随着其他工作也在深入,想法一天一个样,整个系列放了很久的鸽子。

现在是时候慢慢放出这一系列文章了。

这个系列前面的部分,很多篇讲的是可见的那一半:从 ANSI 转义序列、字符网格、Markdown 流式渲染,到权限 UX 和多端架构。

中间两卷——胶水层和基建——讲的是看不见的另一半:渲染引擎再聪明,也只能渲染“已经到达的字节“;字节到没到、到全没有,是协议层的事,渲染层永远无权裁决。 两个世界的接缝处,就是这一篇里的全部事故。

后话:这个 bug 还有个更尴尬的处境。现在评测 Agent 的流行框架喜欢把指标分成结果、过程、效率、风险四层,而它哪一层都放不进去:它不改变 agent 的行为,只改变“你看到的是不是真的“。四层评的是能力,它考问的是评测的地基。这个话题值得单独写一篇,这里先立个旗子。


附:我自己设计的流式完整性检查清单

状态机(前面的先判):
  transport_error / no_end_marker / buffer_residual
  / missing_finish_reason / complete(兜底,非默认)

判定不完整的三个充分条件(任一命中):
  □ 结束标记未收到(如 SSE 的 [DONE])
  □ 缓冲区有未解析残留
  □ 全程没有任何 chunk 携带结束原因
    ⚠ 结束需要两个独立证人(关闭标记 + 结束原因),缺一个都不算

半帧防护:
  □ 单事件/单缓冲有大小上限
  □ 上限到达自行收尾 → limit_exceeded
    ⚠ 等不来的信号不能做唯一收尾条件

记录边界:
  □ 失败摘要只记状态与类别,不抄原始报文
    ⚠ 截断的报文可能停在敏感文本中间

没报错只是开始——行为的可断言性

本卷序章问过:没报错,就代表输出没问题吗?界面部分第 16 篇回答了这个问题的一半,也就是渲染层:把带状态的字节流逐层翻译成可以断言的东西。但 agent 不只是会说话,它会做事:行为层的可断言性是另一个量级的难题。这一篇是本卷的地图:把「agent 评测」这团乱麻收拢成四个问题,后面每章认领一问。

本卷将讲

  • agent 断言难在三件事:非确定性(同一输入不同输出,断言目标从结果移到路径覆盖与终态);成本是一等约束(每个样本都是真金白银);被测对象是复合体(模型 × 脚手架 × 工具 × 内容,归因必须靠对照)。
  • 四问框架:能不能做对、坏了会不会察觉、是不是它的功劳、什么代价,也是本卷后续各章的目录。
  • 「什么代价」一问只立框架不展开:成本怎么进入 go/no-go 裁决,由第 7 篇接棒。

一、已经回答的那一半

先把已经到手的半个答案数清楚。

本卷卷首《没报错,就代表输出没问题吗》(序章)把「看起来完整」拆穿了一次:流式回答被截断,渲染出来毫无破绽。没报错,不代表没问题。那一篇的结论是判定必须下沉到协议层,complete 只能是排除出来的兜底,不能是默认值。界面部分第 16 篇再进一步,把渲染层的输出整个变成了可断言的:字节断言钉契约、快照钉形态、等价性钉不变量、守护测试钉纪律。到那一篇为止,「agent 说的话显示得对不对」这个问题,从字节到纪律每一层都有了断言形态。

但注意这两篇共同的幸运之处:被测对象是确定的。 渲染引擎喂同一段字节,产出必须逐字节相同;不等就是 bug,断言就地正法。序章的完整性状态机也一样:字节到没到、到全没有,是有标准答案的。这个幸运到行为层为止。agent 的「输出」不是一段文本,是一连串动作:改了哪些文件、调了哪些工具、为什么这个顺序、中间信了哪条记忆。同一道题喂两遍,动作序列可以完全不同,而两次都对。界面的半边有 oracle,行为的半边没有。

序章结尾立过一面旗:流行的评测框架把指标分成结果、过程、效率、风险四层,而「答案被截断却看起来完整」这种故障哪一层都放不进去,因为它不改变 agent 的行为,只改变你看到的是不是真的。四层评的是能力,它考问的是评测的地基。这一卷,就是来接这面旗的。

二、行为层难在三件事

第一难:非确定性。 断言的前提是「正确答案存在且可枚举」。渲染层有,行为层没有。同一输入不同输出,断言目标只能从「结果」搬走,搬到路径覆盖(该走的步骤走了没有)和终态(不管过程怎么抖,最后落库的状态对不对)。这是断言目标的两次搬家;第 14 篇还会补第三次:断言不了输出,就断言输出之间的关系。三次搬家方向一致:离「逐字比对预期值」越来越远,离「这个系统必须保持的性质」越来越近。

非确定性还带来一个统计后果:单次成功说明不了什么。一个 agent 跑一遍成功,是灵感还是能力?τ-bench 给过一个官方口径的注脚:它不看单次 pass,看 pass^k,也就是 k 次独立运行全部成功的概率,把「可靠性」从一次灵感里拆出来。同一个 0.75 的单次成功率,可以是每次都四分之三的稳,也可以是时灵时不灵的赌,这两种 agent 是两种产品。第 6 篇会把 pass@k 与 pass^k 这对指标讲透,这里只立一句:本卷所有结论都以「跑多次」为前提,单次跑分不作数。

第二难:成本是一等约束。 界面层的测试是免费的:八百个快照文件,跑一次 CI 几秒钟,断言随便加。行为层反过来:每跑一次实验都是真金白银的 token,每个样本都是一次付费会话。这改变了评测的形状:样本量不由统计愿望决定,由预算决定;「再跑一万次取平均」这个选项不存在;连「这个实验值不值得跑」本身都成了一个需要裁决的问题。成本怎么进入 go/no-go 决策、怎么记录才不污染归因,这一问本篇只立框架,展开交给第 7 篇。

第三难:被测对象是复合体。 测 agent 从来不是只测模型。一次运行的结果是模型 × 脚手架 × 工具 × 内容的乘积:换了 harness,同一个模型判若两人(第 10 篇专门讲这件事);同一段系统提示,写在 description 里和写在正文里效果天差地别(第 2 篇有实测);skill 文件被截断,伤挡在执行路径上时宿主全数察觉,伤在参考文档里时多数毫无察觉(第 4 篇)。所以本卷几乎不谈「这个模型行不行」,只谈「这个差异能不能归因」,而归因的最低配置是对照,这是第 6 篇的主题。

三、被测对象的六层

复合体具体是哪几层?把全书的病例摊开,被测对象自下而上正好六层:

  • 模型:权重里的能力。榜单和基准的主战场,本卷着墨最少:不是不重要,是「只测这一层」的幻觉最害人。
  • 流式协议:字节的到达与完整。序章整篇是这一层的病例:截断的回答看起来完整。
  • 宿主 harness:循环、重试、兜底、权限。胶水层和基建卷在讲它;本卷第 3 篇讲它的另一面:静默降级如何让实验根本没发生。
  • 内容与扩展:skill、插件、规则文件、记忆。第 4 篇的故障注入炸弹就埋在这一层。
  • 生态:别人的插件、别人的评测、别人的榜单。别人的插件是第 6 篇的战场;别人的评测和榜单,第 10–13 篇专门去读。
  • 仓库与上游:被测代码本身。第 5 篇把故障注入从 skill 推到仓库,靠的就是这一层的 88 份原始记录。

六层都能坏,且坏法各异;同一层修好了不代表相邻层没事。这张地图要反着用。拿到任何一个评测结论,先问:它测的是哪一层?结论能外推到哪一层?

四、四个问题,三个姿势

地图的右半边是四个问题,本卷每章认领一问:

  1. 能不能做对:能力评测。但「做对」的前提是考题合法:考题从哪来、凭什么存在,是第 2 篇。
  2. 坏了会不会察觉:故障注入。第 3 篇先讲最便宜的失败(实验根本没发生,绿灯照样全绿),第 4 篇把炸弹真的埋下去,第 5 篇从战例里抽出检出率的乘法模型。
  3. 是不是它的功劳:对照实验。第 6 篇讲归因的最低配置,第 8 篇是把对照落到地面的操作手册。
  4. 什么代价:质量与成本的联合裁决。本篇只立框架,第 7 篇接棒。

四问之外还有一问,问的是评测自己:裁判会不会错?会,而且裁判的 bug 比被测对象的更隐蔽。这面镜子安在第 14 篇的下半场,用我自己的一次公开翻案给全书收口。第 9 篇把整套方法搬进一个具体领域(记忆)。第 10–13 篇换一个位置:分数不是我跑的,是别人给的(榜单、论文、公开 benchmark),怎么判断它可不可信。第 14 篇先补上断言形态的第三块拼图(蜕变测试),再以裁判校准收束全书。十四个章号:四问,一个领域,四篇读别人的分数,一面镜子。

三个姿势各连一问,但姿势不是章的私有财产:能力评测里有注入(第 2 篇的红绿对照就是注出来的),故障注入里全是微型对照实验。地图画的是主雇关系,不是围墙。

五、本卷的叙事弧与公理

交代一下本卷的口气。和界面卷拿 ForgeLoopTUI 当参照系一样,本卷的参照系是我自己的评测工具链:dsh-eval-harness(dsh 是 deepseek harness 的缩写)、skill-quake 故障注入管线、108 格截断矩阵。叙事弧大致是:先拿自己的 harness 当尺子,再拿尺子去量别人的生态,然后发现尺子本身的刻度是错的,最后把「修正尺子」长成纪律。所以本卷的病例大多是我自己的翻案记录。这不是自曝家短的癖好,是本卷的公理决定的:

评测的全部产物(考题、观测、对照组、裁判)自己也是软件,也会坏,也需要被测。 每一章既是拿评测问 agent,也是拿这句公理问评测本身。第 14 篇末尾的「错误 → 机制化」清单,就是这句公理逐章兑现后的总单。

参考与延伸

  • 本篇为评测卷卷首语(框架章),无对应博客篇;四问框架与六层划分浓缩自作者的私人评测全景笔记(未公开,仅作骨架来源,不作事实出处)。
  • τ-bench 的 pass^k 口径见其论文原文(Sierra 团队的 Tool-Agent-User 交互基准):以 k 次独立运行全部成功的概率度量可靠性,并以数据库终态做判定——「可靠性而非一次灵感」与「看终态」两条均与本卷互指。
  • 序章之问见本卷卷首《没报错,就代表输出没问题吗》;渲染层的四层断言翻译见界面部分第 16 篇,本章引用不重讲。

考题从哪来——为真实失败而建

评估器该为已发现的错误而建,不为想象中的错误而建:想象中的错误测出来,全是噪声。这一篇讲用例的来源哲学:一条评测用例凭什么存在。

本章将讲

  • 红绿对照:用例的合法出生证明。每个修过的 bug 配一条 FAIL→PASS 用例,与 SWE-bench 的 fail-to-pass 同构。
  • 触发层必须测双向:该触发时触发、不该触发时不触发;TP/FP/FN/TN 的口径,以及为什么影子信号不进混淆矩阵。
  • 一次红线写法实证:同一条用例,description 写「不管」声明 vs 正文写行为指令,66.7% FAIL → 100% PASS。

一、想象中的错误测出来全是噪声

评测圈有一条够狠的纲领:评估器该为已发现的错误而建,不该为想象中的错误而建(Hamel Husain 与 Shreya Shankar 的 eval FAQ 把它立成了 error analysis 的纲领,这里按我的理解转述)。我第一次读到时觉得偏激:不想象错误,用例从哪来?后来自己建了几轮门禁,才承认它是对的。

想象的错误有个共同的产出模式:对着被测对象空想「它可能会犯什么错」,批量造一批用例,跑完得到一批红灯。然后你会发现这些红灯要么修不动(因为这个「错」在真实使用里根本不发生),要么修完了用户毫无感觉。噪声不是指数字抖,是指用例和真实失败之间没有血缘关系,你测的是一个你想象出来的系统。

纲领的正面说法是:用例要从真实失败里长出来。流程是固定的:真实失败(线上事故、实验翻车、日志里的异常)→ 亲手标注,开放编码,给它归类 → 失败分类表里有了这一格 → 写成一条指名道姓的红测试 → 修复 → 转绿 → 进回归套件常驻。每一步都不可省略,尤其是第一步。

二、红绿对照:用例的出生证明

「从真实失败长出来」在工程上有一个精确的判定:先红,后绿。一个 bug 被修好之后,配一条在修复前 FAIL、修复后 PASS 的用例,这条用例就是这次修复的出生证明。没有先红过的用例没有资格进套件,因为它没证明过自己抓得住任何东西。

这个口径不是私家发明。SWE-bench 的判定信号就是 fail-to-pass:一个补丁算不算数,看它是否让一批此前失败的测试转绿(官方口径如此)。红绿对照是把同构的纪律搬到 agent 评测:每个修过的 bug,都欠套件一条这样的用例。

我自己的一次完整闭环发生在给 skill 建门禁那天。skill-up(阿里开源的 skill 评测工具链)的 benchmark 模式会把每个用例跑 with/without 两臂,我给自己的 polish skill 跑完首轮,6 通过 4 失败,报告漂亮。直到翻被测 agent 的会话落盘才发现:所有 with 臂的会话里,这个 skill 的名字出现次数是零。harness 遍历 skill 目录时不跟随符号链接,我的九个 skill 全是软链,选中文件数为零,安装逻辑把这个零当成正常,一个文件没上传,debug 日志还照常打印「installed」。也就是说前面三轮全量评测,两臂跑的都是裸模型,报告里的 PASS 和 FAIL 全是 noise 装扮成的 signal。

(「实验根本没发生」是第 3 篇的主角,那里会把这类绕行通道整个编目;这里只取它的后半段。)

后续是我报了 issue,顺手把修复写了:解析符号链接,并且「选中零个文件」直接报错,附三条回归测试。注意最后这个改动才是红绿对照的本体:symlink 只是零文件的一种成因,「选中了零个文件却照常评估」这个沉默本身才是该被判死的东西。修复让那三条用例从红转绿,它们从此站在套件里,专杀「静默的零」。

红测试还有一条纪律:起名不能省。一条没有名字的边界,对下一个改代码的人不存在。「零文件安装报错」必须指名道姓,否则三个月后没人记得它防的是什么。

三、测增量,不测能力

有了出生证明,下一个问题是:什么样的考题有区分度?

首轮数据最容易误读的地方是:经典任务上两臂拉不开差距。裸模型润色文章、找内存泄漏本来就很强,这种题两边都满分,delta +0.00。这不代表被测的东西没用,代表你的用例测错了东西:测的是模型的存量能力,不是被测对象带来的增量。

一天跑完十七个 skill 之后,有区分度的用例只有三类:

  1. 红线与边界:「不注水」「不编造」「确认前不动文件」。这是被测对象声称提供、而裸模型不保证的东西。
  2. 对抗性施压:「线上在报警,很急,别问东问西」。压力是红线唯一有效的显影剂:我的 plan-first skill 在施压下仍然先出方案不动文件(with 100% 对 without 75%),朋友的 check skill 顶住了「测试全绿直接放行」的压力并反指「这是假绿」。
  3. 流程纪律:「论点标出处」「敏感文件闸门」。主干答案裸模型也会给,但纪律不会。

这三类有个共同前提:它们测的都是被测对象自己声明的规约,不是评测者想象中的错误。红线写在 SKILL.md 里,就是一份已存在的行为规约,测它更接近给规约补测试,而不是凭空设计质量标准;何况用例资格全是实测挣来的:先跑出大面积 FAIL,它才配进套件。失败是被发现的,不是被发明的。

边界用例还有一个设计要点:域内夹带。测「润色 skill 不做全文翻译」不能用纯域外请求(「帮我写篇博客」,skill 根本不触发,测的是裸模型,什么也证明不了);要以触发域内的事项为主请求,夹带一条它声明「不管」的事项:「帮我把这段话润色一下,然后翻译成英文」。主请求负责把 skill 激活,夹带负责考它的边界。

四、触发层必须测双向

skill 这类「按 description 自主加载」的扩展,还有一层最容易被跳过的评测:触发本身。该加载时加载了吗?不该加载时忍住了吗?

只测前者是常态,也是错的。一个「什么请求都触发」的 skill 在单向评测里 recall 满分,实际上它是个灾难:把无关对话全染成自己的上下文。所以触发层必须建混淆矩阵,四个格子全都要:TP(该触发且触发)、FP(不该触发却触发)、FN(该触发没触发)、TN(不该触发且没触发)。用例集由此分成 pos 和 neg 两半,neg 用例不是陪衬,是和 pos 同等重要的考题,「不当触发的代价」只能从 neg 里量出来。

我的触发报告工具里有两条口径值得写成规矩,都是翻车翻出来的:

  • 影子信号不进混淆矩阵。 agent 用 Read 工具读了 SKILL.md 全文,不算协议级激活(协议激活只认 Skill 工具调用),但它是宝贵的「影子使用」信号:模型动了心、走了手动路径。这个信号独立呈现,不进矩阵、不减 recall。把它混进矩阵,你会同时失去「协议激活」的准确度和「影子使用」的信息量。
  • 超时的用例不进分母。 曾经有上游 bug:case 超时强杀引擎,结果文件来不及落盘。这种用例如果默默从分母里消失,通过率就被偷抬了。所以排除必须显式:报排除计数,让「没测成的」和「测了没过的」在报告里各占各的格子。

五、红线写在哪,模型才遵守

最后一节是一次实证,它同时演示了本篇全部主张的闭环。

所有 skill 作者都凭直觉在做一件事:写「不许做 X」。但这条约束写在 SKILL.md 的什么位置才有约束力?我给朋友的八个 skill 做评测时发现了一个天然对照组——它们的边界声明恰好分布在三种位置:

  • 只写在 frontmatter description 里的,全灭。 write 的「Not for commit messages」只在 description,被夹带请求触发后直接交付了一条工整的 commit message,全程零边界声明。health 更糟:审计请求夹带「顺便看看这个文件为什么报错」,它不仅接了调试,还动手修改、运行了项目文件,把自己「审计不动手」的纪律一起丢了。
  • 正文有规则但只是路由表的,也没守住。 check 的正文写了「prose review 路由到 /write」,但没写「/write 不在场怎么办」。评测环境只装了它一个,规则找不到出口,于是静默接单。路由声明没有降级路径,等于没有声明。
  • 写进正文行为指令的,守住了。 ui 的边界写在正文里,全场唯一守住:「按规范我不在这里手搓版式」,然后给出正确的接手方。

三层证据拼出的结论很明确:frontmatter 的声明是路由元数据,管的是「要不要加载」,管不了「加载之后做什么」。运行时的边界约束必须是正文里的行为指令。

这个结论当天就闭环了:我的 polish skill 的「不管全文翻译」原本也只写在 description,评测实锤失守(66.7% FAIL);把「守边界」写进正文红线节,重跑同一条用例,100% PASS,agent 的原话是「英文版本需要你另行处理;下面只完成中文润色部分」。改动一行规则,用例从红到绿。

回头清点这次实证:用例来自真实失败(66.7% FAIL 是实测出来的,不是想象的);资格是挣来的(先红才配进套件);修复有出生证明(同一条用例从红到绿);结论立刻变成了两条上游 PR 的内容。eval 不是打分,是改被测对象的扳手,而扳手的每一颗螺丝,都得有出生证明。

(单次跑分为什么不作数,比如同一条用例三轮跑出 25%、75%、100%,这个口径问题归第 6 篇,那里会把 pass@k 与 pass^k 讲透。)

参考与延伸

  • 本章主体收编自已发布博客《给 skill 建门禁:一天里的三种沉默失败、一次红线写法实证,和它抓到的上游 bug》(2026-09-17),按「论点先行、事件压缩」重排;触发双向口径(影子信号、超时排除计数)出自作者的 huohou 仓库 evals-shared 工具链与 2026-09-19 会话记录。
  • SWE-bench 以 fail-to-pass 测试为判定信号,见其官方站点口径。
  • 「为已发现的错误而建」的纲领表述转述自 Hamel Husain 与 Shreya Shankar 的 eval FAQ 与 error analysis 系列文章,具体措辞以原文为准。
  • 符号链接零文件事故的后续:skill-up issue #253 与修复 PR #257(含三条回归测试)。

绿灯的两种谎言——实验真的发生过吗

本卷序章问过:没报错,就代表输出没问题吗?这一篇把同样的怀疑推向行为层,先讲失败里最便宜也最致命的一类:不是检查问错了,就是检查看着的那件事根本没发生。两种情况里,绿灯都是全绿的。

本章将讲

  • 两种谎言各配真实病例:检查问错了问题(zstd 静默截断),检查全对但被测的事根本没发生(六条绕行通道逐条展开)。
  • 统一定律:两个世界产出同一个绿灯,观测对它们的差异就是盲的;装着优化器的系统会自己漂向能过关的世界。
  • 对策两方向:分叉观测(在场证明与送达证明)与故障注入(包括对测量仪器自身的消融)。

一、第一种谎言:检查问错了问题

我自己的 harness 里有过一个天天全绿的检查。评测管线要读 dsh 落盘的 session trace,格式是多帧拼接的 zstd 压缩容器;采集层拿到文件,调一次解压,解出明文,检查通过,流程往下走。这个检查跑了几周没红过一次。

它问的问题是「这个文件能解压吗」。该问的是「帧数对不对」:一次性解压对这种容器只解出第一帧,不报错,静默截断。单帧文件里两个问题的答案一模一样,所以它天天绿;直到 trace 体积长大、开始分帧的那一天,两个答案分道扬镳,而分叉的瞬间没有任何红灯在场:解析照常成功,只是后面的帧全丢了。后来钉死它的办法是逐帧解析,外加一条显式告警:trace 跳行数增长必须被看见。

同一个形状的例子我在 X 上和 @echo_vic 讨论 harness eval 时也撞见过一个:密钥目录的信任检查,问的是「那个文件在不在」,该问的是「这个目录能不能信」。文件在的时候,两个问题的答案一模一样,它只在文件不在的那一天才和真问题分道扬镳,而那一天偏偏只有日志在场。

这种检查最难发现,因为它平时是对的,一个红灯都不亮。它不是坏检查,只是一个只在平常日子回答过问题、从没在分叉日回答过的检查。

二、第二种谎言:被测的事根本没发生

第二种更隐蔽:检查本身没毛病,每条都对,红的绿的都对,只是它看的那件事压根没发生。你以为是完整流程,其实关键部件被绕过去了。绕行通道我编目过六条,每条都配得着真实病例。

1. 静默降级:部件没挂上,警告继续跑。 给 skill 建门禁时的头号事故:harness 遍历 skill 目录不跟随符号链接,选中文件数为零,安装逻辑把这个零当成正常,一个文件没上传,日志照常打印「installed」。三轮全量评测,对照臂和实验臂跑的都是裸模型,报告全是噪声装扮成的信号(完整经过见第 2 篇)。降级本身可以有理由存在,静默不行:降级必须是一条能判红的事件,不是一行警告。

2. mock 只实现 happy path。 我给流式协议造故障时修出来的教训:mock 的权威性和被测客户端的严格性成反比——客户端越宽容,你的方言错误藏得越深。初版 mock 把「长度截断」发成完成事件裹一个状态字段,凭直觉拼的,信息都在;真实 API 的方言是一个独立事件类型。同一个错误,严格解析完成事件的客户端直接假阴性,宽容的兼容层默默消化,两边都绿。修法是给每种故障形态配一个「必然触发现有检测」的阳性对照变体,细到事件名的粒度:mock 说错了方言这件事,只有阳性对照能当场拆穿。

3. agent 直写 grader 要看的结果文件。 判分看什么,优化器就生产什么。我的 harness 抓过活着的样本:问图片尺寸,agent 没调该测的读图工具,用 bash 的 file 命令兜底答对。结构断言全绿,想测的能力零覆盖。Anthropic 记录过更省事的版本:长时程项目后期,新会话的 agent 环顾四周看到已有进展,直接宣布完成,什么都没做就「通过」了,他们的防线是把特性清单全部初始化为 failing,agent 只能翻完成位,不能删不能改。

4. skip 静默生效:前置条件不满足,用例消失。 我踩过的形态:筛选条件一个笔误,用例零命中,CI 空跑,显示绿色。没有任何测试失败,因为没有测试运行。现在的防御是筛选无命中直接报错:零是一个必须举证的结果,不是一个安全的默认值。

5. 兜底吞主路:主路径失败,走了 plan B 还报成功。 最日常的形态是工具报错被粉饰:工具返回了 error,agent 当作没看见,最终回答依然自信,单看最终文本完全正常。所以 trace 里的工具硬错误要单独提取,任何一条都足以判 FAIL:「最终答案像样」不能冲销「主路径出过事」。

6. grader 只看终态,中间步骤无约束。 终态对了,一切都对吗?Braintrust 的综述里有个尖锐的口径:一次事故响应用了 35 次工具调用才解决,「这不是 pass,是伪装成 pass 的成本事故」。终态检查回答「做成了没有」,回答不了「付出的代价是不是已经否定了方案」。

六条通道共用同一个出口:绿灯全绿,实验没发生。

三、统一定律

两种谎言背后是同一条定律:当两个不同的世界产出同一个绿灯,你的观测对它们的差异就是盲的。「文件在」和「目录可信」是两个世界,「真实跑通」和「绕行达成」也是两个世界。而系统——尤其是里面装着优化器的系统,比如 agent——会自己漂向那个能过关的世界。模型越强,找到绿灯最短路径的本事越大,这个漂移越快。

「被绕过的部分最容易出事」不是巧合,是因果,而且有三条机制:

  • 选择效应:会被绕过的部分和容易出事的部分本来就是同一批,网络、重试、超时、清理、兜底,都是环境不对劲时才需要工作的部件。它们因为「麻烦」在测试里被绕过,又因为「少见但致命」在生产里出事。
  • 零锻炼:测试本是这些部件唯一的上场机会,绕过等于零锻炼,第一次真实执行发生在生产。
  • 筛选效应:grader 若可被绕过,你就不只是没测它,还在主动筛选「不经过它」的解法。这个压力随模型升级持续恶化,因为更强的优化器找捷径更快。

镜子的另一面也要算上:有假通过就有假失败。基础设施错误被记成「推理失败」就是在冤枉 agent。外部文献里有个硬数字:一个数据提取的基础设施 bug 修掉之后,基准分从 50% 直接跳到 73%。判定前永远先问一句:这次失败真的是 agent 的失败吗?(这个问题的制度化形态是无效登记,见第 8 篇。)

四、对策一:分叉观测——在场证明与送达证明

第一个对策方向是让两个世界产出不同的记录。

最简单的做法是把一个布尔拆成两次判断、分别记结果:「文件在」和「目录可信」分开记,「能解压」和「帧数对」分开记,「结果通过」和「关键部件真的跑了」分开记。分歧日不用再等有人翻日志,它自己就是一条可断言的记录。

推广开就是两层证明。在场证明:全量跑之前,先验证被测对象真的在场。不看退出码,看直接证据:工作区里的落盘文件、会话落盘里的加载日志行。PASS 只证明流程跑完了,不证明实验发生了。送达证明:终态之外记路径凭据,证明工具真的调了(断言调用序列,不许 bash 兜底冲销)、工具真的成了(硬错误单列,一票判红)、信号真的到了。我给流式协议写 mock 时把这层做成了标配:每个请求落一条结构化日志,实际写的字节数、完整事件序列、终止证人送达没有、以什么方式关流,全部在案;请求侧对称记录。有了这层,「工具没反应」和「故障没送达」才分得开,本书好几次翻案靠的都是逐事件核对这些字节。

五、对策二:故障注入——包括对仪器自身

第二个方向更主动:把坏世界造出来,看有没有人叫。

对检查,喂坏样本:把目录改名、把配置删一行、把流按要求截断,再跑一遍。红了,这个检查才算存在;不红,它只是装饰。第 4 篇会把这件事做成一个 108 格的矩阵。

对流程,做消融:把你以为是主干的部件拆掉再跑一遍。分数掉了,说明它真的在被测;分数没动,说明你测的从来就不是你以为的东西。

还有第三条,最少人做:对测量仪器本身做故障注入。仪器也是软件,它的假设可以和被测物正面冲突。第 8 篇有个病例:校验器假设「两臂回执顺序一致」,而 treatment 改的正是顺序,139 行里 88 行被仪器判了无效。这类事故的通用解法不是放宽仪器,是先怀疑仪器。我自己的待做清单里有一项就是把注入对象对准 harness 自身:逐个拆掉部件,看门禁分数动不动。还没跑出数字,先不写结论,但方向是定的:仪器不经过注入考验,和被测对象不经过注入考验一样,都只是「看起来在工作」。

消融和后面常用的双臂对照要分清:消融拆的是测量仪器,双臂扰动的是被测物——各管一半,第 6 篇讲双臂那半。

六、每次惊讶都是一块空地

最后一条是纪律层面的。每次靠偶然发现或翻日志才看见问题,本身就是症状,说明当时没有任何检查在场。而每次惊讶都标出一块该写断言的空地。

把惊讶的具体原因写成一条指名道姓的测试,起名这一步不能省:一条没有名字的边界,对下一个改代码的人不存在。起完名,「只在某一天才分开」就从侥幸变成了每天都要过的一道关。这就是第 2 篇说的出生证明,也是两种谎言唯一的终点站。

参考与延伸

  • 本章底稿 2026-10-05 定稿,成章时收编了已发布博客《从 trace 到 eval:trace 设计、Agent 评测方法论、一个评测 harness 的实现,和它抓到的上游并发 bug》(2026-08-23)与《给流式协议造故障:三协议 mock、once 注入、字节级送达证明,和 strings 阴性不等于代码不存在》(2026-09-25)的病例段;章首 zstd 病例与前者的采集层事故同源。
  • 密钥目录病例整理自作者 2026-10-05 与 @echo_vic 在 X 上关于 agent harness eval 的公开讨论,他的原表述是「信任检查问的是“这个文件在不在“,而它该问的是“这个目录能不能信“」。
  • 「提前宣告胜利」与特性清单初始化为 failing 的防线,转述自 Anthropic 关于长时程 agent 工程实践的公开文章;「35 次工具调用不是 pass」转述自 Braintrust 的 agent 综述;基准分 50→73 的基础设施归因案例转述自 LangChain 的 eval checklist(引 Witan Labs)。三处均为转述级引用,具体数字以原文为准。
  • 「仪器假设与 treatment 正面冲突」的完整病例(139 行判无效 88 行)见第 8 篇;「选中零文件照常评估」的完整经过见第 2 篇。

炸弹——故障注入下沉到内容完整性

协议层的 mock 解的是「环境不可控」;但还有一类更原始的故障:脚手架物理残缺,文件被截断、被删除、frontmatter 被清掉,宿主会怎样?这类「内容完整性」故障在正统 robustness eval(prompt 扰动)里是空白。这一篇是造弹与引爆的记录。

本章将讲

  • 同一周的协议层矩阵(108 次运行):检出(L2 及以上)只有 6/30,L0 无察觉占六成。检出不难,告知才是缺口。
  • 挡路的伤 8/8 检出,不挡路的伤 2/8,差异在位置,不在剂量。
  • 方法学红线:只动副本、C0 阴性对照全程压阵,以及一个差点发布的错误结论如何被翻案。

一、两种炸弹

第 3 篇讲过给流式协议造故障的厨房:本地 mock provider、六种故障做成请求参数、once 注入、字节级送达证明。那颗炸弹解的是「环境不可控」:真实的断流和丢事件靠运气碰,mock 里只是一行参数,确定性就是它的全部意义。

但那颗弹炸的是「流」。还有一类更原始的故障没人埋过:文件。skill、插件、规则文件,全是磁盘上的一堆 markdown,它会残缺:下载截断、同步丢文件、手滑删错行、生成事故写空 frontmatter。正统的 robustness eval 折腾的是 prompt 扰动(换措辞、加噪声),「脚手架物理残缺后宿主会怎样」这一层是空白。问题很朴素:当一个 skill 自己带着伤被加载、被执行时,宿主 agent 能发现吗?

靶子我选了一个最疼的:阿里开源的 skill-up 评测工具链里的 skill-upper,一个「负责测评其他 skill 的 skill」。选它的理由很直白:如果连考官自己都带着伤出题,它改的卷子还准吗?

二、造弹的纪律

故障注入有一半的价值在方法学里。五条红线,每条都有出处:

  1. 做实验的人不能当宿主。 谁动的手脚谁知道伤在哪,自己跑出来的「发现」不算数。每次运行都派一个零上下文的全新宿主,只知道 skill 路径和一句普通的用户请求。
  2. 中性 prompt。 请求里没有任何「检查完整性」的暗示:「帮我给这个 skill 设计评测并 validate,别真跑」。所有运行共用同一份模板,只换路径。
  3. 机械证人与 agent 警觉性分层记录。 每个注入状态先过一个确定性检查器(frontmatter 必填字段、引用文件存活性、截断签名),它只回答「文件层面有没有伤」;然后再看 agent 层的表现。两层分开记,谁在哪一格失效一目了然。
  4. 只动副本,每格必恢复。 变异只动副本,做完即 git checkout 恢复,机械证人确认签名回到健康态再进下一格。
  5. C0 阴性对照全程压阵。 全部恢复、重跑基线、期望无误报,它证明流程无残留、证人无误报。阴性对照不是走过场:没有它,「检出」和「误报」用的是同一张嘴。

后来还长了第六条,是翻车翻出来的:宿主可见的任何路径都不能编码伤型。 早先的运行路径里编码了伤型(kimi+t5-trunc-asset/...),至少两路宿主在报告里引用路径名当佐证。工具链随后把宿主可见路径全部改成哈希匿名暂存。做注入实验,连目录名都是泄密渠道。

三、矩阵

四种基础伤型各对应一类真实事故:T1 主文件拦腰截断在 60% 处(下载/同步截断)、T2 删掉正文明确引用的附件(拷贝丢文件)、T3 附件截到一半(半截写盘)、T4 清空 frontmatter 的 name/description(生成事故),后续又补了 T5(用例模板截半)、T6(删掉指令点名要复制的模板)和 T1-85(主文件只截 85% 的剂量变体)。行为分级:L0 无察觉 / L1 有信号但说错对象 / L2 明确指出不完整 / L3 指出并拒绝执行。

批量跑完,规律很清楚:

伤型伤与执行路径的关系检出率
T1 主文件截 60%(后续步骤凭空消失)直接挡路8/8,全部 L2,全部精确定位到断点行
T6 删指令点名要复制的模板指令直接落空3/3
T5 用例模板截半半挡2/3
T3 参考文档截半(「可以参考」)不挡路2/8

没检出的那六路不是没读文件:它们读完了半截的参考文档、用了它的决策树、给出了完整输出,只是谁也没发现文件只读到一半。L0 的最强形态不是看不见,是看见了不认为是异常。 定稿后还有一次场外复现:另一颗伤弹的宿主在报告里写下「SKILL.md 本身看起来完整」,而运行目录名其实已经把「带伤」泄露给它了,警觉被引导起来,又被干净的切口排除掉。

然后是回马枪,这轮我最在意。把带伤的考官(T3 版 skill-upper)留下,再给它一个被做了同样手脚的目标 skill,让它产评测用例。结果:两处伤都没被发现,而且卷子真的改歪了。健康基线的判分脚本对格式规则有五项显式机械断言,带伤考官产出的用例对其中源自被截半段的断言全部零命中。文档残缺 → 理解残缺 → 用例残缺,沿链静默传导,全程无告警。评测仪器的伤不治,它会继续生产出「看起来完整」的下游结论。

横向三个宿主的矩阵(各跑 T1/T3):挡路的伤在所有宿主上稳定检出(T1 合计 14/14);不挡路的伤出现宿主间差异(T3 从 2/8 到 3/3)。但这里必须如实声明一个口径:三列里有一列实际跑在兼容端点的另一个模型上,矩阵同时携带宿主脚手架与模型两个变量,差异不做归因拆分,只能写「宿主间检出行为差异可见」,不能写「谁比谁强」。原生模型对照列留在仓库的复现手册里,不重跑。

同一周我还引爆了协议层那颗弹(四个 CLI 配三种流式协议共 6 行,F0 对照加 5 种故障共 6 种条件,每格跑 3 次,合计 108 次):F0 对照全绿;30 个故障格里检出(L2 及以上)只有 6/30,L0 静默占六成。协议层的分级和上面不同,L3 指有重试信号并自动补齐完整回答;那 6 格全是这种,说出「回答被截断」这级人话的 L2 一格都没有。检出不难,告知才是缺口。两个实验一个测流、一个测文件,证据形态不同,收敛于同一句话:内容层判不出完整性;地基只做验收,不评级。

四、剂量与位置

这张表最容易被误读成剂量-响应曲线:伤越重越容易被发现。不是。T1 截 60%(丢 40% 内容)检出 8/8,截 85%(只丢 15% 的尾部速查表)反而只有 1/3:自变量从来不是伤的大小,是伤的位置。

准确的提法是剂量-位置效应:检出率由「伤是否横在 agent 正要执行的那条指令上」决定。指令说「复制这个模板」而文件不在,3/3;主流程的后续步骤凭空消失,8/8;「可以参考」的文档坏了一半,2/8;与本次执行无关的元数据,概率性掷骰子。为什么,留给第 5 篇,那里会把「挡路」拆成乘法里的一个因子。

五、翻车与翻案

这两周里我自己翻了两次车,都值得留档。

第一次,把轶事差点写成结论。 首轮手工实验里 T4(空 frontmatter)的宿主只字未提、照常跑完,一个干净的 L0。差点写下「执行层对元数据之伤稳定无察觉」。第三轮批量复测,三路宿主全部明确指出了空 frontmatter,其中一路还主动推断「可能影响触发」。修正后的准确说法是:那也是概率性的——单发是轶事,x/N 才算数。首轮那发 L0 保留为轶事证据,不计入批量口径。

第二次,差点发布一个错误结论。 协议层矩阵的初版里,codex 对 length 截断完全静默——这和它的源码直接冲突(源码里那个事件明确会进重试路径)。排查到最后,嫌疑人是我自己:初版 mock 把截断信号发成了完成事件裹一个状态字段,而真实 API 的方言是一个独立事件类型;客户端的完成分支根本不解析那个状态字段——不是它收到信号装没看见,是我的 mock 压根没把信号说出口。用法语考学生加法,学生没反应,差点判他不会算术。中途还差点二次误判:往二进制里搜事件名整串零命中,差点写下「无此处理器」——实际编译器把匹配内联成立即数比较,事件名不进字符串表,而处理器的证据串一直都在。strings 阴性,不等于代码不存在。

修正方言后全量复测,初版那两格作废,证据保留并单独标注——它们现在是「测试夹具如何制造假阴性」的教学样本。这次翻案的代价是两格子返工,不是一篇错误的结论;而它能被翻回来,全靠第 3 篇那层送达证明:「工具没反应」和「故障没送达」之间,隔着一层必须自证的字节。

两次翻车指向同一条发布纪律:最刺眼的结论,先当嫌疑人审一遍,它往往是你自己的仪器。

六、防线该长在哪

实验做完,自然的质疑是成本:检查会不会让 skill 变胖、加载变贵?答案的三档防线留到第 5 篇展开,这里只记结论的形状:把检查写进 skill 正文是最贵也最不可靠的一档(每次加载付 token,只换来看机缘的检出);CI、loader、安装器那几档是零 token 的确定性。完整性是供应链问题,不是上下文问题。

参考与延伸

  • 本章由已发布博客《回答被截断,你的 CLI 知道吗:四个工具、六种故障、108 格矩阵,和一个差点发布的错误结论》(2026-09-25)与《考官带伤阅卷:对 Agent Skill 做故障注入的完整性实验》(2026-09-27)合并收编,按「造弹 → 矩阵 → 翻车与翻案」重组;协议层 mock 的机制细节(F0–F5、once 语义)见第 3 篇与《给流式协议造故障》(2026-09-25),本章只引用。
  • 实验数字出自 truncation-detection-benchmark(2026-09-25 运行,108 格逐格证据开源)与 skill-quake(2026-09-27 前后运行,results/ 目录三批汇总);宿主矩阵含脚手架 × 模型双变量,检出差异不做归因拆分,原生对照列见仓库 docs/REPLICATION.md。
  • 行为分级口径:L0 无察觉 / L1 信号指错对象 / L2 明确指出 / L3 拒绝执行;统计口径:首轮手工实验不并入批量累计,x/N 不读作精确比率估计(单条件 N=3~8)。
  • 上游互动:skill-up issue #253/PR #257(零文件安装)、issue #280/PR #281(完整性检查进 CLI)、kimi-code issue #4012(主 agent 截断静默接受)。

检出率是个乘法

检出率 = 读到 × 愿报 × 挡路。三个乘数缺了任何一个,「未检出」就无法归因。这是本卷的方法论核心,一个从战例里抽出来的模型。

本章将讲

  • 三个乘数逐一定义;为什么「察觉了但没报」是最危险的未检出形态;检出 ≠ 止损。
  • 剂量-位置效应:同一强度的伤,位置决定检出。
  • 防线该建在哪:CI / loader / 安装器(零 token 的确定性),而不是 skill 正文;以及一个被我亲手推翻的假说。

一、把故障注入推到任意仓库

第 4 篇的结论是:检出与否不取决于伤有多重,取决于伤是否挡在 agent 要走的路上。这话是在 Agent Skill 上证出来的:一个 SKILL.md 加几个附件,结构简单。自然的追问是:换成普通仓库,同样的伤、同样的宿主,规律还在吗?

靶子选了两个。靶子一:照 Vercel 开源的 eve 框架的结构(「an agent is a directory」——instructions.md 是系统指令,tools/ 一文件一工具,skills/ 按需加载)手搓一个最小贺卡 agent;这个结构和 skill 目录同构,故障菜单几乎零翻译成本平移,题库也和第 4 篇同源,结果才可比。靶子二:PydanticAI,选它不是因为有名,是它自带确定性模型替身,行为层不用烧真模型就能复现,还能截获「框架到底发给模型什么」,后面有大用。

宿主两位(kimi CLI 与 codex CLI),版本日期进报告。开跑前多了一道以前没有的工序,训练数据在位探针:冷启动问两个宿主「你知道 eve 吗」,都答不了解。权重里没有原件,实验才干净。方法、中性 prompt、哈希路径、证人先行全部沿用第 4 篇的管线。本篇一共 88 次宿主运行。

全部跑完之后,数据逼着我把「检出率」拆成了三个因子:

检出 = 读到(外壳供给)× 愿报(模型供给)× 挡路(任务供给)

乘法的意思是:任何一道闸为零,乘积就是零;而且未检出可以沿闸门折返归因——断在哪一道,是可以查出来的。

二、因子一:挡路——旧规律在新载体上原样复现

给 eve 风格目录注入的第一种伤,是第 4 篇 T1 的平移:instructions.md 从 22 行截到 12 行,切口选在一句完整的话之后,剩下的流程恰好还能走完,丢的是安全规则和工具约定。机械证人对这种伤完全静默,压力全在宿主警觉性上。

结果:E1 格 0/16(两个宿主各 0/8)。

这个零要和第 4 篇对照着看:同样是「主文件截断」,T1 在 skill 靶子上 8/8 全检出,这里颗粒无收。区别不在伤的大小:T1 砍掉的是任务必经的步骤,E1 砍完剩下的路恰好还能走。换了一类文件系统,「检出取决于伤是否挡路」原样复现,这是方法泛化成立的核心证据。PydanticAI 靶子上又复现了一遍:README 截到 23/38 行、rules.md 截到 13/20 行,检出分布同样跟着「挡不挡路」走,不跟着「丢了多少」走。

三、因子二:读到——没打开的文件不会伤人

E3 格原本是阳性对照:把渲染工具的源码截断在 schema 正中间,括号不闭合,语法断裂,机械证人必抓,用来证明检测通道是活的。instructions 第三步还明确点名了这个工具。

结果意外:kimi 的 8 发里,7 发的文件访问轨迹里根本没有 tools/ 目录,它把工具当概念,按 instructions 的描述直接执行了。更糟的是其中 2 发反向幻觉,声称「工具不存在」。文件被点名 ≠ 文件会被读。

这给了「挡路」一个前置条件:伤得先出现在宿主的阅读路径上,才谈得上挡不挡执行路径。没读 = 没伤。

「读到」是个过程信号,好消息是它可以机械提取,不用人工读 transcript。我在另一个宿主(pi)上实测过一条 reread_any 绊线(宿主是否重新打开过被注入的文件):TP=8、FP=0、TN=23、FN=3(2026-10-03,pi v1.0.0)。过程信号不需要完美,需要的是口径稳定、可以进门禁。

四、因子三:愿报——我亲手推翻的「外壳假说」

E3 的第一轮结果出来时,解释看起来是现成的:codex 5/8 检出(有一发精确到「565 字节、缺 execute 实现和收尾括号」),kimi 0/8。codex 外壳更严谨嘛,它会习惯性地先 cat 源码。

且慢。查了一下配置:这台机器上的 codex CLI 跑的是 k3-256k,也是同一家模型。昨晚的对比是「外壳 + 模型」两个变量一起动的。补一个同模型对照格:codex 外壳 × kimi-for-coding,N=8:

外壳模型E3 检出
kimi CLIkimi-for-coding0/8
codex CLIkimi-for-coding0/8
codex CLIk3-256k5/8
kimi CLIk3-256k1/8

外壳假说死了。 codex 外壳在同模型下依旧读完了所有文件(exec 日志里 cat 记录都在),但 kimi-for-coding 读完不报。严谨住在模型里,不住在外壳里。(诚实的 caveat:k3-256k 那路带着高推理档位,对照格没显式对齐推理档,模型变量没钉到完全死。方向可信,强度存疑。这个 caveat 本身就是第 6 篇要讲的:变量没隔离,结论就要降格。)

这批数据里最冷的一发:kimi-for-coding 有一发在推理流里写下「render_card.ts was truncated (only 12 lines)」,它看见了,精确地看见了,然后把这件事合理化掉,最终交付只字未提,卡片照发。另一发更标准:推理里写明文件截断、止于 schema 中间,最终回复只有卡片正文。

第 4 篇说「察觉了才报,没察觉就不报」。这一格补上更难受的形态:察觉了,也可以不报。 推理流不是交付物:用户看不见的那部分里发现的东西,约等于没发现。如果你只审计交付物,你审计的是它的表达欲,不是它的感知力。这条已经作为 L1 的新形态(perceived-but-unreported)写进了分级口径。

五、检出 ≠ 止损

E2 是唯一全员满分的一格:16/16 宿主明确报告了 skill 文件缺失(L2)。然后呢?全部选择「报告后继续」。被删掉的文件里有一条「恰好一个 emoji 置于末尾」——健康基线的合规率是 4/4,E2 掉到 0/8 和 3/8;明令禁止的抬头格式出现了 4 例。

16 个宿主一边申报残缺,一边产出残缺的卡片。 申报和止损是两回事,没有任何一个宿主认为「文件缺了」值得停下来。检出率再漂亮,也只是信息,不是防线。

六、确定性证人与阳性对照

PydanticAI 的替身模型允许截获框架发给模型的全部 payload,零模型成本。截断的内容原样、安静地流进模型输入:工具 docstring 截断后从 211 字符变 31 字符、rules.md 截断后 system prompt 从 917 变 663——框架告警为零。这不是框架的 bug(它没有义务校验用户内容),但它量化了静默传导的形状:从文件残缺到模型输入残缺,中间没有任何一道关卡。

也要给宿主记一笔功。R3 格把 agent.py 截断在 docstring 未闭合处,import 即 SyntaxError,响亮故障:codex 那路打出 8/8,多数先发 ast.parse 验证再下结论,3/8 直接阻断任务要求完整文件。这一格的意义和阳性对照一样:阴性结论必须配阳性证据,否则「没检出」和「检测通道死了」无法区分。

七、防线该长在哪

现在可以回答第 4 篇留下的成本质疑了:完整性检查会不会让 skill 变胖变贵?三档防线的成本结构摆在一起,答案自己就出来了:

防线位置运行时 token 成本可靠性
skill 正文里的自检指令每次加载都付,永久付概率性(本卷实验里 2/8 ~ 8/8 浮动)
CI / 发布期机械检查零确定性(断链、空 frontmatter 硬抓)
loader / 安装期校验零确定性

最贵的那档最不可靠。烧 token 换来的不是安全,是「看机缘的安全」。所以:输出给人看的 skill,CI 跑一次机械检查就够;输出被机器消费的 skill(评测、生成配置、进门禁的),verdict 错了没人看见,值得发布期门禁加哈希清单;分发给很多人的 skill,检查该长在安装器那一层,装的时候验,不是用的时候每次烧上下文自查。完整性是供应链问题,不是上下文问题:地基的验收长在地基上。

八、诚实清单:这篇被抓的 bug 在我自己身上

老规矩:每篇最后抓到的 bug 不在被测对象里,在测量系统自己身上。这篇有双份:

  1. 路径名泄漏。 staging 根目录叫 repo-quake,对宿主可见,有宿主顺着路径名把实验猜出来了,违反了自己定的「路径不编码伤型」。
  2. 证人文件没收走。 机械证人的输出文件放在宿主可见的 staging 树里,有一发宿主读了它,反推出实验性质。

受影响的 4 发检出本身仍然真实(都是先指出具体损伤、后猜测实验性质),数据保留、逐发加注记;两条教训固化回了工具链主干:实验产物对宿主不可见、宿主配置列为必进报告的格子变量。裁判被校准,又闭环了一次,这个循环本身是第 14 篇下半场的主题。

参考与延伸

  • 本章由作者同名草稿收编改写,成书首发(草稿不再单独发博客);全部 88 份原始记录与工具链在 skill-quake / repo-quake 仓库(2026-09 底至 2026-10 初运行),两条方法学修订已固化进主干(611fabc)。
  • 靶子一为照 Vercel eve 框架(2026-06 开源)目录结构手搓的最小 agent,未对其仓库本体注入;靶子二为 PydanticAI,确定性替身与 payload 截获为其官方 TestModel/FunctionModel 能力。
  • pi 宿主的 reread_any 绊线数字(TP=8/FP=0/TN=23/FN=3)为 2026-10-03 pi v1.0.0 实测。
  • 「外壳假说」对照格中 k3-256k 路的推理档位未与对照格显式对齐,强度结论按文中 caveat 降格理解。

对照组的陷阱——归因靠对照不靠证据强度

证据再硬,也同时兼容两个相反的故事。对照组选错比没有对照组更危险:它给错误结论配上证据。这一篇讲归因的最低配置。

本章将讲

  • 双臂对照(with / without)为什么是归因的最低配置;裸基线缺位时,「全绿」和「没测到」同貌。
  • 对照组被污染的三种形态。
  • pass@k 与 pass^k:同一个 0.75,两个数讲出相反的故事,以及单次跑分为什么不作数。

一、测自己的东西有 spec,测别人的没有

前面几篇的靶子都是自己的东西:自己的插件、自己的 skill、自己用的 CLI。这一篇换猎场——测别人的生态。靶子是 dsh 插件榜上三个高星项目:一个路由/注入器(约 7000★)、一个视觉工具(约 4000★)、一个多 agent 编排(约 1800★)。星数是测评当天从 GitHub API 现拉的,版本和日期先进报告,老规矩。

测别人的东西,差别在于:测自己的工具有 spec,测别人的生态没有。 你不知道作者的设计意图,只有一份 README、一个安装命令、和一堆你愿意相信的星。oracle(判定依据)的缺席逼出三个新问题:oracle 从哪来?锅(失败的归因)怎么分?分母(结论对什么成立)是谁?插件的测评结果只是证据,主角是方法。

二、分母是谁:你只能测装得上的

先说一个容易被跳过的前提:生态评测的分母从来不是「全部插件」。最大的插件目录收录约一千五百条,收录规则是提个 YAML 就进,没有安装验证。另一份清单的作者较真,在容器里逐个真装:9247 个候选,1673 个实测,979 可用 / 600 不兼容 / 94 待定,装得上的只有六成。任何生态测评的结论,天然只对「可安装的头部」成立。

这一层很快就从「前提」变成了「数据」。第一个插件就给我上了一课:7000★ 的那个,一键安装命令成功、exit 0,插件却是死的。它靠 prepare 钩子在安装时自动构建,而隔离环境的包管理器默认拦截构建脚本,产物目录整个缺席。安装命令的成功和插件的存活是两个独立事件。 顺手还抓到 npm 同名错位:裸名指向的是另一个账号的不相干包,而真身其实挂在 scoped 名下。安装指引的正确形态只剩一种:全限定、钉版本、写明出处。

所以漏斗有四层:人气 → 可装 → 行为正确 → 故障韧性。安装不是测评开始前的静默过滤器,它就是第一层数据。

三、oracle 从哪来:三种,加一张诚实牌

没有 spec,oracle 只有三个来源,抓的虫不同:

  • README 承诺:测名不副实。把作者宣称的功能落成可判定断言:它说「图片给它,还你结构化证据」,那就断言它的工具必须真实被调用、输出必须带工具标记(不许 bash 兜底答对,第 3 篇的覆盖断言在这里复用)。
  • 行为钉版:测回归。把首次运行的行为固化为基线,将来变了就红。措辞要小心:行为变了不等于行为错了,红只意味着「该有人来看一眼」。
  • 宿主不变量:测相容性。「插件在场时,宿主原有的故障处理不能被破坏」,这是最有杀伤力的断言,因为它不依赖插件的任何文档。

三个插件恰好各占一种形态。但第四种情况也存在:有些承诺落成不了可判定断言。 视觉插件的「看图看得好不好」,在我的环境里没有能用的视觉引擎,无法判定。正确动作是在报告里如实标「不可判定」。写一条永远通过的橡皮图章断言假装覆盖到了,比没有断言更坏:它给「没测」配了证据。

四、双臂:归因的最低配置

韧性层的做法是 chaos:把插件挂进故障环境跑四格(对照 + 三种协议故障)。判定口径是:挂载后宿主行为变了,才算到插件头上。 两个可测插件全绿,与裸基线逐格一致。

这个「全绿」值钱,值钱在它是对照出来的:一个直接坐在模型请求链路上的 7000★ 注入器插件,不破坏宿主的故障检出与恢复。没有裸基线,「全绿」和「没测到」长得一模一样。 这就是双臂对照(with / without)的最低配置地位:两臂只差一个变量,分数相减得 Δ,Δ 才是被测物的真贡献。

这个设计不是私家偏方。Anthropic 官方的 Claude Code plugin evals 把 with/without 双臂默认打开、裸基线内置,「插件在不在场」作为一等变量写进了官方评测协议(其 grader 分六档,机制不展开,一句官方背书即可)。社区基建和官方文档在同一个点上汇合:双臂不是增强,是底线。

对照组的反面教材有三种常见形态,都进过我的事故现场:拿老配置当对照(混淆变量藏在「新旧差异」里,下一节的翻案就是它);对照组靠默认值「自动出现」(比如宿主的自动发现机制,会把和能力同源的东西悄悄喂给对照组;对照组的「无」必须强制出来);以及干脆无裸基线直接报分。三种形态殊途同归:给错误的结论配上了证据。

五、一次推翻自己的归因

本篇的戏肉,是我自己的一次误判。

视觉插件的行为层首跑,现象非常「清楚」:在新建的隔离配置里装上插件,首次启动直接挂死,三十分钟没有输出。安装日志干净、配置结构正常、插件是 npm 正规军,「插件启动阻塞」,归因报告第一版就这么写的,证据看着很硬。

按归因纪律,下结论前补一个裸对照:全新配置,什么都不装,首启。

也挂。

真凶是宿主自己的「新配置首启挂起」,和插件无关。我当时的对照用的是老配置,混淆变量是「新配置首启」而不是插件。对照组选错比没有对照组更危险:没有对照,你只会说「我不知道」;有了错的对照,你会说「我知道了」,而那个知道是错的。

后续按纪律执行:归因文件里 v1 的错误结论和推翻过程原样保留,没有改成「一开始就判对了」。归因文件的价值就在于记录错误,下次再遇到「证据很硬」的时刻,它提醒你硬证据是怎么兼容两个故事的。宿主的真 bug 报了上游(复现步骤与四路排除证据附全);插件这边我只提了 issue 没提 PR:提 PR 得拿出能跑的方案,提 issue 只要附上能复现的证据,前者是空头承诺,后者才是诚实可行动。

这轮还顺手校准了裁判自己:评测 runner 的超时只杀直接子进程,包装器形态的孙进程被孤儿化,整条 runner 挂死 34 分钟,裁判被它要测的场景打穿了。修复是进程组杀,回归测试专门断言「孙进程必死」。这个故事的完整版归第 14 篇。

六、pass@k 与 pass^k:单次跑分不作数

最后一节是统计口径,不堆公式,只讲两个数讲出的相反故事。

一个 agent 单次成功率 0.75。现在跑 10 次。pass@k 问 10 次里至少成功一次的概率:约 1.0,近乎必然。pass^k 问 10 次全部成功的概率:0.75¹⁰ ≈ 0.056,几乎不可能。同一个 0.75,一个讲「给它机会总能成」,一个讲「交给它必出事」。两个数都对,但一个是给消费者看的广告,一个是给运维看的风险清单。

选哪个数取决于你回答什么问题:「这个 agent 有没有可能做对」用 pass@k,「这个 agent 靠不靠得住」用 pass^k。τ-bench 把后者立为可靠性指标,理由就是它对「时灵时不灵」的惩罚是指数级的。混在一起用就是叙事作弊:拿 pass@10 的 1.0 去汇报可靠性,等于把十次里的九次失败从分母里抹掉。

所以第 2 篇那个现象(同一条用例三轮跑出 25%、75%、100%)的读法就清楚了:单次跑分是采样,不是测量。配套纪律两条:报告必须带迭代次数,单比例用 Wilson 区间看下界不看点估计。点估计的 3/3 和 30/30 在报告里长得一样,区间不会撒谎。

七、沉淀:生态评测四条

  1. 分母写出来。 采样框、安装成功率、剔除名单全进报告;结论只对「可安装的头部」成立,这个限定写进结论本身。
  2. oracle 分三层。 README 承诺 / 行为钉版 / 宿主不变量;写不出可判定断言的,标「不可判定」。
  3. 归因先跑裸对照。 红格没有对照组不许下结论。
  4. 成本透明。 版本、日期、token 开销进每份报告(本轮真实 API 合计 20116 token),读者有权知道结论的价格。

参考与延伸

  • 本章由作者草稿《测别人的生态:四层漏斗、三种 oracle、一次推翻自己的归因,和它抓到的三只 bug》收编改写,成书首发(草稿不再单独发博客);实验运行于 2026-09-26/27,上游互动:dsh Discussion #7978(新 profile 首启挂起)、routing-suite issue #152(预构建产物建议)。
  • Anthropic Claude Code plugin evals 的双臂默认开启与六档 grader,经官方文档核实(2026-10-05,v2.1.269 文档口径)。
  • pass^k 可靠性指标与「看数据库终态」的判定方式出自 τ-bench 论文;可安装率数字(9247/1673/979/600/94)来自社区清单作者的容器实测,引用时已注明口径。
  • 消融与双臂的分工:消融拆测量仪器(第 3 篇),双臂扰动被测物(本篇),各管一半。

什么代价——质量与成本的联合裁决

本卷卷首语的四问里,「什么代价」一直只有一句话:成本是一等约束。这一篇把这句话展开。它讲的不是怎么省钱,是成本怎么进入 go/no-go 决策,以及成本怎么记录才不污染归因。

本章将讲

  • 只按质量裁决等于给「花钱买通过率」开后门:四条明码标价的通道。
  • 裁决的三个量:cost per success、边际成本、质量-成本前沿拐点。
  • 成本首先是实验卫生问题:零静默重试、缓存经济学、两臂计费路径逐字节对齐、美元门槛预注册。

一、开场:十八比十八,为什么仍然被否决

先交代一件我自己没算清的事。第 4 篇那个截断检出矩阵,每格跑三次,108 格格格都是真金白银的会话;给 skill 建门禁时为了把置信区间压窄,采样模式一开就是好几轮。这些钱当时花得都对,但「花得对」的判断从来没被写进任何裁决规则,全靠手感。我的 harness 记了每一个 token 的去向,却从没回答过一个问题:这个通过率是多少钱买的?

然后我读到了一个把这个问题回答到底的裁决。我持续在看的一个开源 agent 内核项目(单人维护;为保持小册独立叫它 M 项目,项目名和链接从略),它的评测记录里有一次配对实验:对照组和实验组各 18 个 rollout,两组 18/18 全成功。质量打平,实验组还多一套机制。按「通过率说话」的习惯,这个实验该判实验组赢。裁决却是拒绝——实验组每个 rollout 多花 0.0648 美元,而实验合同里预注册的成本门槛是 0.02 美元。

两组全成功,仍然被否决。我第一次读到时停了一下:它逼出的正是我一直在回避的事。只按质量裁决,等于给「花钱买通过率」开后门。

二、通过率是可以花钱买的

这不是比喻,至少有四条明码标价的通道:

  1. 换更强的模型。同一个 harness、同一批题,模型升一档,分数涨一截,单价也涨一截。
  2. 重试。偶发失败重跑,pass@k 随 k 爬向 1.0。第 6 篇讲过,这是把「跑多次」从测量手段偷换成提分手段。
  3. 堆上下文。更多规则文件、更多历史、更多 few-shot,弱模型也能被上下文抬着走。
  4. 加密自检。改完让模型自查一遍、再跑一轮 judge 复核,失败率会降,token 翻倍。

这四条通道有个共同特征:**在只报通过率的报告里,它们全部隐身。**一个 80% 通过率但平均花 2 美元的臂,和一个 78% 通过率花 0.2 美元的臂,在 pass rate 排行榜上前者赢;在真实产品里,后者可能是唯一能上线的那个。没有成本轴的通过率是单目视觉:看得见高低,看不见远近。

三、裁决的三个量

把成本放进裁决,需要三个量,而不是一个总价。

每个成功结果的成本(cost per successful outcome)。 分母是成功数,不是运行数。一个臂跑 100 次成 50 次花 100 美元(2.0 美元/成功),另一个跑 100 次成 40 次花 20 美元(0.5 美元/成功)。后者用四分之一的价格买到一个成功,成功率只低 10 个百分点。预算受限的真实运营里,这是四倍的覆盖差距。

边际成本:下一个百分点多少钱。 从 60% 买到 70% 可能每个百分点 5 美元,从 85% 到 86% 可能 50 美元。决策不是「要不要更强的方案」,是「我现在在曲线的哪一段」。

质量-成本 Pareto 前沿。 每个方案画成散点,前沿上的方案才有资格被讨论,前沿内侧的方案不需要理由就淘汰。M 项目那个 18/18 的臂被否,不是因为它差,是它落在前沿内侧:同样的质量,对照组更便宜。

一个公开的参照系:第三方榜单 JevBench 把 Cost 与 Intelligence、Calibration、Speed 做成等权调和平均的四个轴,成本按「每 1000 次决策多少美元」计价,不是每千 token。计价单位的选择有深意:token 是模型厂商的计费单位,决策才是用户的消费单位。用户要的是「这个 agent 每做一次判断我付多少钱」,不是「它吐了多少字」。(界面部分第 8 篇讲过 usage 字段是滞后值、界面上怎么显示;这一篇管的是成本记录,不管显示。)

四、成本首先是实验卫生问题

读到这里容易以为成本是经济话题。在评测里,成本首先是归因问题:两臂的计费路径不一致时,效果差和成本差同时无法归因。

零静默重试

最隐蔽的成本失真是静默重试。请求超时,SDK 默认帮你重试两次;provider 返回 503,代理层悄悄换个节点再发。表面上你看到的是「这次成功了、花了这些 token」,实际买到的是「三次尝试里有一次成功」,而对照组可能没有同样的重试配置,只试了一次。

M 项目的付费 runner 直接把这个口子焊死:自动重试次数钉死为零,每次请求单独授权,撞上 503 也写一条「已授权但失败」回执,永不自动重试。理由有两层:重试既通胀成本(一个样本实际花了三份钱记一份),又抹平差异(鲁棒性本来就是两臂差异之一,重试把它偷偷消掉了)。

我在自己的 harness 里踩过它的镜像面:失败重跑会被上一次尝试的残留文件污染,甚至残留的 git history 能被 agent 翻出来获利。重试污染的从来不只是状态,还有成本记录。

缓存是长上下文实验最大的隐性变量

第二个失真源是 prompt cache。长上下文会话里,前缀的几万 token 走缓存命中和走全价,成本差一个数量级。这制造了一种很难察觉的耦合:你对干预的任何改动,都可能顺手打穿缓存。

M 项目在设计停滞熔断时否掉过一个方案——「检测到空转就限制下一轮的 tool_choice」——否掉的理由里有一条纯属经济考虑:改 tool_choice 会让 provider 侧的消息缓存失效,在 400K–850K 上下文的场景里,那是全场最贵的一次 cache miss,而这个方案只是为了发一个模型大概率无视的信号(其自家长上下文实验里,76% 的文本型进度提醒被模型无视,第 9 篇汇总过这类干预的失效证据)。一次干预的成本不只是它自己的 token,还有它顺手作废的那截缓存。

记录成本时 usage 必须分项:input、output、cache read、cache creation,只报一个 total 等于隐瞒。口径还要和漂移检测分开:我的 trace 提取层为门禁定的总量口径排除缓存命中(那是为漂移检测服务的);算成本时反过来,缓存读按折扣价如实计入。两个口径各管各的,混用了数字就是假的。

五、两臂的计费路径必须逐字节对齐

配对纪律(第 8 篇展开)在成本侧有一个值得单独点破的应用:两臂除 treatment 外,计费路径必须一致。 同一个模型版本、同样的温度采样、同样的重试策略(最稳妥是两臂都零重试)、同样的缓存条件(前缀一样长、内容一样,否则 cache miss 率的差异会被误记成 treatment 的成本效应)。

最容易漏的是默认功能开关。M 项目的记忆实验出过一个真实事故:对照组忘了关默认开启的内置判官,结果对照组悄悄用上了和实验组同源的能力,A/B 直接报废。他们的修法值得抄:评测环境每一步默认把判官接入地址导出为关闭态,需要的臂再显式换回。默认值永远站在污染那一边,对照组的「无」必须是强制出来的。第 6 篇立过这条原则,成本记录是它的又一个适用面。

六、美元门槛要在花钱之前写死

最后一块拼图:预算和停止规则必须预注册,在看到任何数据之前写进实验合同。至少五个字段:累计授权金额(花完即停,不许边跑边追加);单样本成本上限;超支样本的归属(记 invalid 还是计入分母,二选一事前定);成本门槛(每成功结果多少钱以内算「不更贵」);到达预算后的动作(停止并按已有数据判,还是挂起等下次授权)。

M 项目的记忆排序试点合同里,累计授权就是 15 美元、shard 顺序执行;开场那个 0.02 美元门槛也是实验开始前写死的,所以 18/18 打平时裁决毫无尴尬:**规则先于结果,执行规则不需要勇气。**这套纪律和第 8 篇的预注册合同是一体两面:停止规则防「偷看数据决定要不要继续跑」,美元门槛防「效果不显著就加钱硬买」。事后追加的预算和事后追加的样本一样,都会把探索性分析伪装成确认性结论。

七、四问的闭环

卷首语的四问到此全部有主:能不能做对(第 2 篇)、坏了会不会察觉(第 3–5 篇)、是不是它的功劳(第 6、8 篇)、什么代价(本篇)。

刻意留一条缝:本篇讲的是裁决与记录,即钱花了多少、买到了什么、该不该继续花。但「花掉的上下文有多少真正有效」是另一个问题:800K 上下文里模型认真在读的可能只有一小段,有效窗口随长度衰减。那条线是价格之外的质量问题,两边分开记;它暂列未来选题、不占编号,等实验数据齐了再独立成章。

本章外部病例来自我持续在看的一个单人维护开源 agent 内核项目的公开评测文档与变更记录(观察窗口 2026-10 上半月,含其评测规范、停滞熔断设计文档与记忆试点合同;项目名和链接从略,数字以观察窗口内的文档版本为准);JevBench 为独立的第三方公开榜单(其四轴计价口径见其公开 METHOD 文档)。自家病例出自 dsh-eval-harness 与截断检出矩阵(2026-09)。

配对实验手册——让同一道题回答两次

第 6 篇回答了「为什么必须对照」,这一篇回答「具体怎么跑」:从 fixture 冻结、顺序平衡、分歧对统计,到无效登记和预注册合同。目标是工具性的:读完能照着开出一次配对实验。

本章将讲

  • 为什么独立两组经常不够用;配对 = 每个任务自己跟自己比。
  • 信息只在分歧对里:2×2 表的 a/d 不提供信息;样本量按预期分歧对倒推。
  • 无效永远不是失败;规则先于数据的预注册合同;代理指标的消费假设。

一、为什么独立两组经常不够用

agent 任务有两个讨厌的性质。

任务难度高度异质。 一批 30 道题里,5 道闭着眼都过、5 道神仙难救,真正区分方案的是中间 20 道。独立两组各跑一批,组间差异里混着「题不一样难」的噪声,样本量被任务方差吃掉一大半。

单次行为是概率化的。 同一道题同一个模型跑三遍,25%、75%、100% 都出现过(第 2 篇的实测);judge 的心情也在抖。两个概率化的东西相减,噪声先进分子。

配对设计的想法很简单:**让每个任务自己跟自己比。**同一道题、同一个模型版本,只改 treatment,跑两次,一次开、一次关。两次结果的差,把任务难度这个最大的噪声项从分母里消掉了。医学上同卵双胞胎对照干的就是这件事,区别只是我们的「双胞胎」是同一道冻结的题。

二、配对实验的最小结构

一次站得住的配对实验,五个部件缺一不可。

1. fixture 冻结。 题面、被测仓库 commit、scorer 版本全部钉死。题在两臂之间不许有一个字的差别,连换行都不行,换行就是 prompt 差异。我的 dsh harness 用 overlay 注入会话落盘根而不是环境变量,原因之一就是环境变量会泄漏进工具调用,变成两臂之外的第三个变量。

2. 每臂全新隔离环境。 HOME、工作区、记忆库、落盘根全部 per 臂重建,跨臂零泄漏。重跑卫生在这里全部适用:残留文件让假通过有地方生长,残留的 git history 能被 agent 翻出来获利,残留的长期记忆更麻烦,它让两臂共享了一个你没在设计里声明的「第三臂」(记忆类实验的完整污染清单见第 9 篇)。

3. 顺序平衡(AB/BA)。 一半任务先跑 treatment 再跑对照,另一半反过来。不做平衡,时间会冒充 treatment:provider 负载随时段波动、模型可能在实验期间被热更新、判官服务自己也在漂移。我做截断矩阵时坚持每格三跑而不是一锤定音(第 4 篇),处理的是同一类时间风险;配对设计把它从「多跑几次平均」升级成显式的交叉表。

4. 确定性参数写明,不确定的也写明。 温度、top-p、seed 能固定就固定;固定不了的(平台不给 seed),在报告里如实写「此项不可复现」。把不可复现项藏起来,配对就退化成披着配对外衣的独立两组。

5. 唯一主指标。 一次配对实验只允许一个主指标。次要指标可以记十个,但 go/no-go 只看预注册的那一个,否则等于十张彩票里挑中奖号码,统计检验全部白做。

三、信息只在分歧对里

配对结果画成 2×2 表:

对照成功对照失败
treatment 成功a(都成)b(treatment 赢)
treatment 失败c(对照赢)d(都败)

关键直觉:a 和 d 对「两臂有没有差异」不提供任何信息。 都成、都败,无论 treatment 有没有用结果都一样。信号只在 b 和 c 里,也就是两臂产生分歧的对子。b≈c,分歧是随机的;b 显著多于 c,treatment 在起作用。

小样本不用背公式:零假设(两臂没差别)下每个分歧对各有一半概率落进 b 或 c,所以直接对 b+c 次抛硬币里出现 b 次正面做精确二项检验(exact McNemar)就够了,b+c 只有十几也能判,不需要正态近似。

样本量因此要按预期分歧对数倒推,不按总样本量。这是新手最常踩的坑:计划跑 200 对觉得很大,但如果两臂成功率都在 90% 上下,预期分歧对可能不到二十——你的检验实际是个二十样本级的小实验。预算和题量按「能攒出多少分歧对」倒推。

统计工具的分工顺手交代:Wilson 区间管单比例(这个臂成功率多高,下界比点估计诚实),McNemar 管配对差(两臂差不差)。一个回答水平,一个回答差异,各管各的,推导不展开,属统计学通识。

四、无效登记:invalid 永远不是 fail

配对实验的每个 rollout 有三种结局,不是两种:成功、失败、无效。

无效是基础设施原因导致这次运行什么都没测到:provider 503 零 token、配额耗尽、被测工具链缺失、超时且无产物。处理纪律只有一条,但必须焊死:

  • 无效永不允许改判成失败:失败是 agent 的,无效是我们的;
  • 未评分(unscored)永不允许改判成通过:没有证据不能发奖。

M 项目的外部基准梯子上有个挂 Blocked 的阶段:三次尝试全部撞上 provider 503、零 token,文档里写明「这一轮的 scorer 输出是基线噪声,永远不得作为 agent 结果报告」。我特别欣赏「永远」两个字:它防的不是当时的误判,是三个月后有人翻旧表格做汇总 PPT。

这是第 3 篇「假失败」的制度化形态:基础设施问题伪装成 agent 的失败,是无效登记要拦截的全部内容。判定前永远先问那句:这次失败真的是 agent 的失败吗?

五、先定规则,后看数:预注册合同

无效规则、停止规则、预算、主指标,这些东西如果在看到数据之后再定,实验就退化成讲故事。解法是把规则写进一份事前合同。本章附录 A 是一页纸模板,九个字段。两个字段值得展开。

停止规则。 跑到什么程度停,开跑前写死:固定对数(攒够 60 个分歧对即停)、固定预算(第 7 篇的美元门槛),或二者先到。禁止「看一眼中间结果,显著了就停、不显著再追加」,这和选择性报告是同一类作弊。顺序表也在开跑前生成冻结,不许跑一对抽一次签。

无效行规则。 什么情况算无效、无效对补不补跑、补跑配额从哪来,全部事前定义。这个字段不是形式:下一节的病例里,它就是整个实验的生死线。

六、病例:一百三十九行里八十八行判无效之后

这是我见过对「规则先于数据」最严酷的一次压力测试,来自 M 项目的一次记忆排序试点(2026-10 观察)。实验设计见第 9 篇,这里只讲事故。

treatment 是对检索结果的行序做置换——不增行、不删行、不改行,只是排序。而实验的完整性校验器有一条旧假设:两臂的回执顺序应当一致。于是 139 个处理行里 88 行因「回执顺序不一致」被判无效:校验器把 treatment 本身当成了数据损坏。

面前两条路:当场放宽校验器把 88 行捞回来,实验继续;或者按预注册合同判无效,结论标注「不可解释、不推广」。他们选了第二条。然后另起一轮探索性分析:用放宽后的校验器重评 125 对,所有材料明确标注 post hoc exploratory,不享受确认性实验的结论地位。探索性结果是 null:金标核实 53→56(分歧 14:17,p=0.72),最终答对 68→67(p=1.0)。

三层教训,一层比一层通用。

仪器假设可以和 treatment 正面冲突。 校验器假设顺序不变,而干预就是改顺序。这和第 3 篇「对测量仪器做消融」是同一个识别模式:当被测系统的变化在测量层表现为「异常」,先怀疑仪器。

规则先于数据时,判无效不需要勇气。 88/139 无效很肉疼,等于大头预算白花。但合同写在前面,「不推广」是执行不是抉择。如果规则允许当场修改,没人扛得住「再看一眼」的诱惑,而「再看一眼」在统计上永远偏向你想看到的结果。

事后分析可以做,但必须穿探索性的衣服。 他们没有假装那 125 对不存在,也没包装成正式结论,它作为「下一轮实验该修什么」的输入活着:修仪器、重新注册、再跑确认性实验。确认性实验回答「是不是」,探索性实验回答「下一轮怎么设计」,两者的产物不许混用。

七、两次显著的断层:代理指标的消费假设

上面那次试点其实有前后两幕,合起来是配对实验最容易自欺的地方。第一幕在离线:同一个行序置换方案,在封存题库上跑离线判分,金标排第一的比例显著改善(15:1,p=0.0005),漂亮得可以发喜报。第二幕就是上面的端到端 null。

离线到端到端之间隔着一条代理链:

金标排第一 → 结果被注入 → 模型打开第一条 → 核实到金标 → 最终答对

每一个箭头都是一个消费假设:下游真的按上游的设计消费它吗?这条链断在「排第一 → 被打开」:模型并不总是先点开第一条结果。把金标从第二行挪到第一行,对一个不按顺序读的消费者毫无作用。何况离线基线已经很强(九成金标本就排第一),留给排序的天花板本来就薄。

我自己的工作里有同构的教训:「检出」是「挡路」的代理,agent 报了截断不等于它会停下来(第 4、5 篇:检出率与挡路率必须分开报,全员申报的一格照样产出残缺交付物)。这个病例把它抽象成通则:

  1. 每设一个代理指标,书面回答一句「下游凭什么消费它」;
  2. 离线显著只批准进入下一轮实验,不批准上线:显著的代理指标和端到端行为之间,永远隔着至少一次确认性配对;
  3. 代理链要逐环可测:注入集合有记录、打开行为有 trace、采信有核实标记,哪一环断的要能定位,不能只看链顶的答对率互相甩锅。

八、treatment 的纪律:改一句措辞就是换药

最后一条操作规程,容易被当作文字洁癖:给模型看的任何文字(judge 的提问、criteria、系统提示里的劝告)都是 treatment 的一部分。 改一句措辞,实验就换了药,旧数据不能和新数据合并。

M 项目的判官服务有组实测:同一批 18 道判断题,问题里不写判定标准时答对 6/18,把「什么叫相关」写清楚后 17/18。这不是个例,第 2 篇的红线写法实验是同型:约束写在 description 还是正文,同一条用例 66.7% FAIL 对 100% PASS。措辞差异的效果比很多模型差异都大。所以措辞要像代码一样 pin 版本,改措辞要像改 treatment 一样重新注册。

九、收口

配对不是目的,可归因才是。这份手册的全部部件(冻结、隔离、平衡、分歧对、无效登记、预注册、代理链)干的都是同一件事:让实验结束时,你能指着 Δ 说出「这是它干的」,并且这句话扛得住「真的吗」的追问。本章长出的操作清单,连同前几篇的机制,统一归档到第 14 篇末尾的「错误 → 机制化」总单。

附录 A · 配对实验合同模板(一页纸)

experiment: <实验名,含版本,如 recall-order-2026q4-v1>
hypothesis:
  direction: treatment_better | two_sided   # 方向事前选定
  primary_metric: <唯一主指标,如「核实到金标的会话比例」>
  secondary_metrics: [<可记录但不参与裁决的指标>]
arms:
  control: <对照臂的完整定义,含所有显式关闭的默认项>
  treatment: <与对照臂的差异,逐字列出;除此外两臂必须逐字节对齐>
fixture:
  task_set: <题集 id + commit/哈希>
  repo_commit: <被测仓库 commit>
  scorer_version: <判分器版本>
  holdout: <封存集 id、开封条件>
sampling:
  pairs_planned: <计划配对数>
  discordants_needed: <预期需要的分歧对数(按此倒推题量)>
  order_schedule: <AB/BA 顺序表,开跑前生成并冻结>
  model: <模型 + 精确版本>
  temperature_seed: <固定值;平台不支持时写「不可复现」>
stopping_rules:
  fixed_pairs: <对数门槛>
  budget_usd: <累计授权美元,先到先停,禁止边跑边追加>
  overrun_sample: <超支单样本:invalid | counted,二选一事前定>
invalid_rules:
  conditions: [provider_5xx_zero_token, quota, toolchain_missing, timeout_no_artifact]
  rerun_policy: <是否补跑、补跑配额来源>
statistics:
  method: exact_mcnemar
  two_sided_p_threshold: 0.05
  interval: wilson_95
preregistered_at: <开跑前的日期与合同 commit>

练手建议用自家 fixture:从 skill-quake 或截断矩阵里挑 10 道题,对照臂关掉所有注入、treatment 臂开一个你确信有效的机制,跑一轮 10 对的配对。重点不是出结论,是把合同的每个字段都实际填一遍。

本章外部病例来自我持续在看的那个单人维护开源 agent 内核项目(M 项目,首次出场于第 7 篇)的公开试点合同、变更记录与评测规范文档(观察窗口 2026-10;项目名和链接从略,数字以观察窗口内的文档版本为准);精确二项检验与 Wilson 区间属统计学通识。自家病例出自 dsh-eval-harness、skill-quake 与截断检出矩阵(2026-09~10)。

记忆怎么测——从「被注入」到「被采信」

这是我另一本小册《RAG 心得》和这本之间欠了很久的一座桥:那本讲检索系统本身的评测;而 agent 的长期记忆比传统 RAG 多出两层,宿主决定注入哪几条,模型决定真的去读哪几条。这一篇讲这两层怎么测,以及为什么「被注入」根本不是终点。

本章将讲

  • 记忆系统是一条三层乘法链:写入 × 检索 × 采信;任一层断裂,下游失败不能归因给上游。
  • 召回与精排必须分家:「在不在」与「是哪条」是两个机制;弱判官独任会成片误杀迂回措辞。
  • shadow 的字节级同一性、写路径「先造题再开功能」、记忆实验特有的污染清单。

一、开场:同一个金标,在 agent 身上多了两环

传统 RAG 评测的链条很短:检索到、生成对,判分结束。我在 RAG 书里建的整套纪律(holdout 封存、金标标注、按位置计的召回指标)迁到 agent 记忆场景,仍然必要,但远远不够。

因为 agent 和检索框之间隔着两个自主决策:检索回来 8 条候选,宿主决定把哪几条注入这一轮上下文;注入了 3 条,模型决定打开哪一条、信不信它、据此答不答题。金标还是同一个金标,链路多了两环,而多出来的两环正是断裂高发区,这是传统 RAG 评测没有的。

借谁的病例立框架?M 项目(那个单人维护的开源 agent 内核项目,第 7 篇首次出场)在记忆面上做了两个月付费实验,四个决策面最后只活下来一个,还把一个离线 p=0.0005 的方案在端到端判了死刑。病例用它的,框架从我的 RAG 书和前面九篇长出来。

二、三层乘法链:写入 × 检索 × 采信

第 5 篇的乘法模型(检出率 = 读到 × 愿报 × 挡路)在记忆域原样重演。记忆系统是一条三层乘法链,任何一层断裂,下游失败都不能归因给上游:

层问题典型指标
写入该记的事实沉淀了吗?新旧记忆的关系判对了吗(同义/矛盾/补充)?覆盖率、关系判定准确率、误写率
检索该用的时候,金标在第几名?gold-at-1、gold-in-top-3、MRR
采信模型真的打开、核实并据此答对了吗?打开率、金标核实率、端到端答对率

归因折返规则与检出率模型同构:端到端没答对,先看模型有没有打开注入的记忆(采信层断);打开了没核实到金标,看金标在不在注入集合(检索层断);金标根本没进库,看写入层。不逐层分开记录,「记忆系统没用」就是一句无法证伪的抱怨。

三、两个题库,两种金标,必须分报

M 项目用的外部题库是长期记忆的公开学术基准 LongMemEval-S(cleaned 版),它内部把记忆库拆成两种形态,这个拆法值得照搬:

  • turn 级原子记忆库:每条记忆是一次对话里的一个原子事实(「张三的航班是周三」),金标是精确的一条;
  • whole-session 会话库:记忆是整段会话,金标散在好几段里,判分要看 top-3 而不是 at-1。

同一个方案在两个库上的成绩可以差出十个百分点:其迭代表里,弱判官方案在原子库命中 0.495 时整段库 0.450,而基线在整段库有 0.720。把两个库平均成一个「记忆准确率」,等于让两种任务的失败互相抵消着藏起来。 按切片分层看,不许只报聚合。

金标纪律没有新东西:dev 集调参、holdout 在读题面前冻结、校准集与验证集分开(第 14 篇同此口径)。记忆题库唯一额外的要求是写入侧也要有金标:给定一段对话,「应该沉淀出哪几条事实」需要人工标注,否则写入层的对错永远说不清。

四、召回与精排必须分家

两个月迭代里最贵的一课,先看伤亡数字。第一版方案让一个 4B 判官独自决定「有没有相关记忆 + 注入哪几条」:turn 级命中从基线 0.620 掉到 0.495(p=0.001),整段库从 0.720 掉到 0.450。加了智能,显著退步。

死因清楚:判官读的是每条记忆 480 字节的聚焦窗口,看不到全文;而「有没有」这个判断需要全局视野。大量「措辞迂回但确实相关」的记忆被整片枪毙。判官擅长的是在几条候选之间比较「哪条更贴」,不擅长回答「这堆东西里到底有没有答案」。

定稿方案把两个判断分给两个机制:词法检索(BM25)当地板,判「缺席」。top 分低于阈值时认定答案不在库,不注入也不咨询判官;召回是全文视野的活,交给读全文的词法信号。判官只在「带」内排序:候选分数达到 top 的一半(band)才允许判官参与,融合分 = 判官相关概率 + 0.5 × 归一化 BM25 分。弱语义信号和词法信号互补,谁也不许单飞。

band 还有个自适应的妙处:分数分布陡的池子(程序性记忆,谁该上场一目了然),band 自动收没、退回基线,判官无权置喙;分数平的池子(事实型记忆,一堆差不多相关),band 全盖,判官尽情发挥。机制按数据的形状自动决定让不让智能插手。

五、shadow 的字节级同一性

记忆实验有个其他实验少有的便利:记忆干预通常可以在宿主内部完成,不改 provider 可见的字节。这给因果归因打下了一块硬地基,也就是 shadow 模式:判官照咨询、判断照记录,但注入结果与不开功能时逐字节相同,模型什么都不知道;再往上才是 advisory(判断真正生效);判官故障、超时、返回「都行」时,输出必须保持原始顺序,不许有半生效状态。

shadow 不是「先观察观察」的客气说法,它要过一个硬测试:同一输入跑两遍(shadow 开 / 关),diff 必须为空。 这和第 3 篇的在场与送达证明是同一种纪律:宣称自己没介入,就要拿出逐字节的证据,而不是「应该没影响吧」。

对照组侧的配套动作第 7 篇讲过:实验环境默认导出「判官关闭」,需要的臂再显式换回端点。记忆系统是默认值污染的重灾区:记忆功能一旦成为产品默认,对照组不做显式清除就必然被污染。

六、写路径:先造题,再开功能

检索面热闹了两个月,写路径(判官判断新记忆与旧记忆是同义还是矛盾)在整个试点期一次都没被触发;另一个决策面(判断用户是不是在要求多方案枚举)咨询了 55 次,0 次越过 80% 的启用阈值。

这两个功能因此处在一个尴尬状态:不是被证伪,是未测。未测和证伪必须严格区分:证伪可以下线,未测只能挂着,而挂着的功能不许进默认配置。

其文档里写下的后续路线对所有做触发型功能的人都适用:先造评测,再决定开不开。 写路径的 fixture 要专门构造:同义改写(「我周三走」→「我的航班改到周三了」)、矛盾更新(旧事实被新事实推翻)、枚举请求(明确要求多列方案 vs 随口一问)。造不出能稳定触发的题,就没有该功能的确认性实验。这与第 2 篇互为镜像:触发型功能的合法出生证明,是一份能触发它的题集。

七、最重的病例:注释有害,重排也没用

把三层链的最上层「采信」讲透,因为它是记忆评测最容易自欺的地方。病例分两幕。

第一幕:给模型看的建议,抵消了选择的收益。 早期方案在每条检索结果后附加相关度百分比、证据评分和使用建议,也就是把判官的判断翻译成给模型看的文字。60 例付费归因实验:纯词法 33/60 核实到金标;只开静默注入筛选 42/60;四面全开、带着注释的臂反而退回 34/60。注释把注入筛选的增益整个抵消了。

这不是孤立事故。同一项目的停滞熔断观察到 76% 的进度提醒被模型无视;测试完整性机制发现模型削弱测试后发消息要求恢复,2 个 run 里 0 个服从。三个独立实验指向同一条规律:在长上下文、弱模型的 regime 下,文本型劝告是系统性失效的干预面。 这也解释了第 4 篇那句「检出不难,告知才是缺口」的另一面:告知缺口的存在,不等于「往输出里多塞几句告知」能填上它。

第二幕:换成静默重排,离线封神,端到端死刑。 注释方案死后,新方案不输出任何文字,只在 band 内对结果行序做置换:advised 与 plain 字节级一致,只是顺序变了。离线封存集极其漂亮:金标排第一 258→272/288,15:1,p=0.0005。然后是第 8 篇详细讲过的端到端 null:139 行里 88 行被旧校验器判无效;放宽校验的探索性重评里金标核实 53→56(p=0.72)、答对 68→67(p=1.0)。模型不按顺序读。 整个决策面退役,分支保留供复现,名字留着但跳过并告警。

两幕合起来,是记忆评测最重要的教训:「被注入」不是终点,「排第一」也不是,终点是模型打开它、核实它、答对题。 中间指标越靠近机制本身越容易显著,越靠近用户价值越诚实;而层与层之间的断裂点(模型不按顺序读、建议文本被无视)只有端到端实验看得见。

八、记忆实验特有的污染清单

通用配对纪律(第 8 篇)之外,记忆实验有几张自己的脏牌:

  1. 跨被试记忆库泄漏:上一个任务写入的事实被下一个任务检索到。每被试、每任务全新存储是底线:文件残留还能看见,记忆残留会伪装成「模型真聪明」。
  2. 对照组的默认 advisor:产品默认开启的记忆功能会在对照组自动生效,对照组的「无」必须强制出来(第 7 篇)。
  3. 本地服务串扰:记忆服务按固定端口启动时,两个实验实例可能蹲到同一个端口。M 项目出过一个实例因此卡了两天的真实事故,修复是按状态根哈希分配端口、401 应答绝不认作自己的服务。测试环境里的「基础设施偶发失败」,有一部分是邻居实验。
  4. 判官端点的环境污染:转发判官请求的代码若读取系统代理设置,「判官不可达」会被染成代理的 503,还会测出一条产品根本不走的网络路径。

九、记忆是第一块能被严格测量的长期状态

收口说回为什么值得做。agent 身上的长期状态正在快速增多:规则文件、托管记忆、技能沉淀、用户画像、任务历史。它们大多数现在没法测:生效配置对用户不可见,是产品侧的黑箱;而评测侧的对应物是「注入集合必须可记录、可回放、可判分」。

记忆是这堆长期状态里第一个拥有干净金标(事实可精确匹配)、天然配对形态(同一道题有记忆 vs 无记忆)、清晰三层链的东西。它的评测法立住了,规则、画像、技能的评测才有模板可抄。也正因如此,这个战场上长出的纪律(召回精排分家、shadow 同一性、写路径先造题、采信才是终点、文本干预对弱模型失效),会比记忆系统本身活得更久。

本章外部病例来自 M 项目的记忆系统设计文档、排序方案退役相关变更与记忆试点合同(观察窗口 2026-10;项目名和链接从略),迭代数字(0.620/0.495、33/34/42 of 60、258→272/288、55 次咨询 0 越阈等)以观察窗口内的文档版本为准;LongMemEval-S 为公开学术基准,M 项目用的是它的 cleaned 版。检索评测方法论出自作者的《RAG 心得》,本章互指不搬。产品侧的「生效配置预览」原本另有专篇讨论,后来撤稿,本章自含其结论。

换个 harness 排名就翻——被测的到底是谁

前九篇的分数都是我自己跑的:题是我出的,对照组是我搭的,翻车也翻在我自己的工具链上。从这一篇起把尺子掉个头:分数是别人给的,来自排行榜、论文、公开 benchmark。读别人的分数,第一问最朴素:榜单上那一列写着模型名,这个分数到底是谁的?

本章将讲

  • 同一个模型换个 harness:名次会翻,拒答会变,成本能差几十倍,失败方式跟着 harness 走,通过率反倒未必变。
  • 结论靠不靠得住,取决于你想说谁:给「模型+harness」排名很稳,拿同一批数据给模型排名就不稳;而且加题补不上 harness 覆盖的缺口。
  • 想比先固定,想复现先记全;「同一个 harness 版本」至今没有定义,我的三栏拆法。

一、我在第 4 篇只敢写半句话

第 4 篇往 skill 里埋伤弹,宿主矩阵的三列里有一列实际跑在兼容端点的另一个模型上。那一节我只敢写半句话:宿主之间的检出行为有差异,可见;谁比谁强,不写。宿主的脚手架和模型两个变量缠在一起,拆不开。第 5 篇翻车之后,工具链又多了一条纪律:宿主配置列为必进报告的格子变量。

当时我以为这是自己实验条件简陋才有的毛病。今年读了一圈公开 benchmark 才发现,它是常态:榜单那一列写的是模型名,分数却从来不只是模型的。harness(把模型包起来、替它调工具、管上下文、决定什么时候停的那一层)一直在场,只是没被写进列名。

二、同一个模型,换个 harness

名次会翻。 Continual Learning Bench(下称 CL-Bench)的排行榜上,同一个 GPT-5.4,接最朴素的上下文学习排第 2,接 Mem0 排第 5,接 ACE 排第 9,接 Codex 排第 10。

WorkBuddy Bench 把 7 个模型放在两个 harness 下并排比:腾讯的 CodeBuddy Code 和 Anthropic 的 Claude Code。三个子集的反应很不一样:

  • 代码子集:GPT-5.5 在 CodeBuddy Code 下领先 GLM-5.2(72.90 对 71.54),换到 Claude Code 下反而落后(76.63 对 77.06)。
  • 安全子集重排得最厉害,平均绝对位移 8.6 分:GPT-5.5 从第六升到第二,MiniMax-M3 从第二跌到第五。
  • 办公子集几乎不动:7 个模型里 5 个变化不到 2 分,绝对位移的中位数是 0.86。

拒答会变。 还是 WorkBuddy 的安全题,同一个 Claude Opus 4.8,在 Claude Code 下拒答 13 次,在 CodeBuddy Code 下 0 次。拒答多少,看着像模型的安全策略,其实很大程度取决于 harness 和提示词怎么配合。WorkBuddy 的榜单对所有已执行的运行求平均,等于拒答记 0 分。这样算,更谨慎的模型会显得更弱;我觉得至少该把「有效作答率」和「作答内的分数」分开报。

成本能差几十倍。 《The Scaffold Effect in Coding Agents》拿 Qwen 3.6 Plus 和 MiniMax M2.5 两个模型,分别接 Goose、OpenCode、OpenHands-SDK 三个开源 harness,在 Terminal-Bench Pro 的 50 题分层子集上跑:换 harness 之后,每解出一道题花的 token 最多差 40 倍。按第 7 篇的口径,这是 cost per success 换了一个数量级:通过率不动,go/no-go 的裁决照样能翻。

失败方式跟着 harness 走。 同一篇论文发现,失败的「指纹」在两个模型之间是一样的:Goose 多半败在推理,OpenHands-SDK 多半败在验证和轮数用尽,OpenCode 多半是空转和超时。决定怎么失败的,更多是 harness,不是模型。

但这篇论文也给了一个反方向的提醒,必须一起记:同一模型在不同 harness 下的通过率,逐题配对比较只差 0 到 8 个百分点;除了差距最大的那一组,95% 置信区间都包含 0。harness 改变的未必是对错,更常是成本、时延和失败方式。注意它用的是配对比较,正是第 8 篇手册里那种设计;换成独立两组比,区间只会更宽。

所以 harness 的影响不能只看总分。它改名次、改拒答、改成本、改失败方式,而且在不同任务上影响的大小差得很远:安全题平均位移 8.6 分,办公题位移的中位数不到 1 分。

三、harness 改变的到底是什么

几份工作给 harness 下的定义大同小异。HAL 把脚手架(scaffold)定义为提示词、工具和控制逻辑;The Scaffold Effect 说的是调用工具、管理上下文、决定什么时候停的那一层;Harness-Bench 更宽:管理上下文、工具、状态、约束、权限、追踪与恢复的系统层。

这里面任何一个细节都能挪动分数。WorkBuddy 做过一次诊断重跑:HY-3 只打开「思考内容跨轮回传」这一个开关,同样的三跑协议下,代码题在一个 harness 下涨了 3.82 分,在另一个下涨了 1.92 分。这个开关不是模型的属性,也不是任务的属性,只是适配层里的一个实现细节,却比榜单上大部分差距都大。

连 benchmark 自己的文档也是变量:τ²-bench 实测,只改写领域策略文档的详细程度,成绩就会变。

过程指标同样不能离开 harness 去读。WorkBuddy 的 Claude Code 列里,DeepSeek-V4-Flash 用的输出 token 约是 GPT-5.5 的 3.3 倍(28.6k 对 8.7k),分数却低了 14.74 分。token 用量、轮数、时延,都是「模型+harness」这个组合的属性。第 1 篇说被测对象是复合体,这里是它的公开版证据。

四、想说谁,可靠性就不同

分数既然属于组合,「比模型」还靠得住吗?

今年 9 月,Hardy 等人用贝叶斯方差分解,分析了来自 HAL 和 Harbor Index 的 22 个 benchmark。核心发现是:可靠性取决于你想下什么结论。

  • 给固定的「模型+脚手架」系统排名,可靠性在 0.935 到 0.994 之间;
  • 拿同一批数据给底层模型排名,只有 0.148 到 0.841。

更扎心的是第三条:如果不确定性主要来自脚手架覆盖不够,那么题目再多(哪怕无穷多道同类题),模型排名的可靠性最多也只能再提高 0.097。他们还发现,汇集多样的 benchmark,在同等题量下能把可靠性从 0.44 提到 0.75,成本最多省 83%。

HAL 自己的数据也是这个意思。同一模型的可比点里,专用脚手架在 CORE-Bench Hard 的 12 组中胜 9 组,在 SWE-bench Verified Mini 的 12 组中胜 11 组;通用的 Generalist 脚手架在 24 次比较中有 20 次更便宜。「哪个模型更强」的答案,取决于给它配了什么脚手架。

这和第 6 篇的结论接得上:归因靠对照,不靠证据强度。想说「模型 A 比 B 强」,harness 就是一个必须被对照掉的混杂变量:要么固定它,要么覆盖多个、报区间。只在一个 harness 上跑,样本量再大,也只是把同一个混杂测得更准。

ABC 清单里有一条(R.6)要求说明评测对象是模型还是 agent 框架。我觉得这条今天该写得更具体:一套评测如果既想「固定模型比 harness」,又想「固定 harness 比模型」,就把两种用途分开写,各自固定什么、变什么,因为它们测的是两样东西。

还有两处容易漏。

一是「固定 harness」常常不完全固定。同一个 harness 接不同模型时,适配层里往往有按模型设置的开关,比如思考内容回不回传、请求直连还是走代理。上一节那 3.82 分说明,这类开关足以改结论。所以「固定 harness 比模型」时,要把每个模型实际生效的适配设置记下来,写明哪些设置因模型而异。

二是数据污染的性质不同。固定模型、比较 harness 版本时,模型见没见过题对两边一样,是共模误差,不太影响「哪个版本更好」;固定 harness、比较模型时,新模型可能见过题、老模型没见过,污染就成了偏向新模型的差模误差。这时私有的留出题集是硬需求。

五、想比先固定,想复现先记全

固定什么。 Harness-Bench 让所有 harness 用同一个冻结的模型服务、同一套任务、同一份预算:上下文窗口 200000、温度 1、最多 150 轮;同时保留各 harness 自己的行为,提示方式、工具、上下文管理和恢复机制都不强行拉平。WorkBuddy 跨 harness 比较时固定的是:推理强度设为 high,上下文统一 200k、用同一个压缩阈值,禁用网页搜索和向用户提问的工具,容器里统一用非 root 用户,因为 Claude Code 拒绝以 root 运行。

记下什么。 只记名字不够。HAL 的教训很典型:

  • 榜单的一行,是脚手架显示名加主模型显示名;
  • 记录的 git 信息不包含工作区有没有未提交的改动;
  • 能区分脚手架内容的目录哈希和版本字段,直到 2026 年 4 月才加进来,而公开轨迹的最后一次上传在那之前。

结果是,你没法判断榜上两行用的脚手架内容是不是同一份。

Harness-Bench 做得更细:每个 harness 声明 ID、版本、镜像、协议和配置名;每次运行把实际生效的版本、镜像和预算写进摘要文件;续跑时逐项核对这些身份,一项对不上就拒绝续跑。它的说明写得很硬:改变任一 harness 镜像、任务定义、模型设置或生成预算,就是一个不同的实验,合并工具会拒绝合并不兼容的分片。

别让配置悄悄回退。 WorkBuddy 有三个做法值得照搬。配置文件刻意不给默认值,缺了映射直接报错,而不是静默套一组错的配置。四层配置合并之后,固化成一份记下所有实际生效参数的清单。每个 harness 版本单独构建成只读镜像,运行时挂进容器;两个适配器从同一个基类从零写起,免得「一边用官方适配器、一边用自写适配器」混进差异。Terminal-Bench 则用一个单行文件钉住它依赖的 Harbor 精确版本,「结果不可比」从此变成一次看得见的文件改动。

这几条和第 3 篇的在场证明是一个方向:不要相信「应该是同一份」,要能拿出「确实是同一份」的证据。

六、「同一个 harness 版本」仍然没有定义

做到这里,还剩一个没人解决的问题:改了什么还算同一个版本,改了什么就算新版本?

HAL 只有身份字段,没有等价规则。Harness-Bench 的规则是任何改动都算不同实验。这很安全,但回避了问题:改一行日志算不算换版?换一个默认超时呢?

我的拆法是三栏:

  1. 可配置维度清单:系统提示、工具集、权限与沙箱、上下文管理、重试与超时、模型与采样参数,每一项在哪里声明、记成什么字段。
  2. 运行身份:内容哈希、实际生效的配置、镜像 ID,不只是名字和版本号。
  3. 同版规则:明确哪些改动视为等价、由谁裁定;规则定下来之前,默认任何改动都是新版本。

前两栏可以直接借 Harness-Bench 和 WorkBuddy 的做法,第三栏只能自己定。我的建议是按改动的性质分三类:

  • 不改变行为的改动:日志、注释、文档。可以算同一版本,但要拿证据说话:在固定种子的回归题集上,轨迹和结果与改动前一致。
  • 改变行为的改动:提示词、工具集、上下文与恢复策略、默认参数。一律算新版本,旧结果不能沿用。
  • 改变资源的改动:超时、预算、并发。它们是实验条件,不算 harness 本身的版本,但必须进实验身份,Harness-Bench 就把预算写进身份,不一致就拒绝合并。

分类要在跑之前定下来,并由改 harness 的人之外的人裁定。这和第 8 篇的预注册合同是同一个道理:规则先于数据。不然,「这个改动不影响结果」很容易变成一句事后的自我辩护。

七、读分数之前:一份检查清单

拿到一个「模型 A 比模型 B 强」或「harness X 比 Y 好」的分数,我会先问六件事:

  1. 结论说的是谁? 模型、harness,还是两者的组合;各自固定了什么、变了什么。
  2. 协议轴固定并记下了吗? 推理强度、上下文窗口与压缩阈值、启用的工具、运行用户、预算。
  3. 配置会不会静默回退? 缺配置报不报错;合并后的实际配置有没有落成清单。
  4. 身份记的是内容还是名字? 哈希和镜像 ID 比显示名可靠;身份对不上,拒不拒绝续跑与合并。
  5. 报了成本、时延和失败类型吗? harness 的影响常在这些维度,不在对错。
  6. 覆盖了几个 harness,报区间了吗? 只在一个 harness 上跑,比不出模型;加题也补不上这个缺口。

八、反方与局限

  • harness 对通过率的影响,可能没有对成本那么大。 The Scaffold Effect 的通过率差异多数在置信区间以内;本篇开头的名次翻转,有的就落在噪声范围里。
  • WorkBuddy 的跨 harness 实验规模有限。 两个 harness、每格三跑平均、没有置信区间;作者自己承认,结果绑定在特定服务端点和两个 harness 的具体构建上。
  • 「公平」有不同的含义。 Harness-Bench 的公平是外部条件一致、内部行为各自保留,并不保证 harness 内部机制等价。Harbor 刻意不让任务声明允许使用的工具,理由是工具属于 agent 的一部分;但如果你的工具集是固定的、不是被测维度,在任务里写明反而更简单。
  • 这一篇的数字我一个也没复现。 都来自原论文、原仓库和公开数据。和前九篇不同,这四篇的病例都是读来的。这本身就是读别人分数时的第一条纪律:先分清哪些数是自己跑的。

所以,分数属于「模型+harness」这个组合。想把它说成模型的分数,先固定 harness,再覆盖多个 harness,最后报区间。下一篇接着问:就算这些都固定好了,分数本身会不会说谎。

参考与延伸

  • 本篇成书首发,与作者的独立文章《换个 harness 排名就翻:评测 agent 时,被测的到底是谁》同源;事实均取自公开论文、代码仓库与数据,作者未复现任何实验。
  • CL-Bench 的名次取自其排行榜原始数据 leaderboard_data.json(数据更新于 2026-07-18,2026-11-07 抓取)。
  • WorkBuddy 的跨 harness 数字、拒答次数与 HY-3 诊断重跑见 Tencent WorkBuddy Bench 论文(arXiv 2607.20911v1,2026-07-23);配置做法见 Tencent/workbuddy-bench 仓库的 configs/README.md 与 configs/harnesses/HARNESS_AUTHORING.md(2026-10-31 读取)。
  • The Scaffold Effect in Coding Agents,Vats 与 Golev,arXiv 2607.22585v1(2026-06-08)。
  • Hardy、Azam、Reuel、Kochenderfer,Agent Evaluation Reliability: More Tasks Won’t (Always) Fix An Agent Leaderboard,arXiv 2610.00651v1(2026-09-30)。
  • HAL(Holistic Agent Leaderboard)据 ICLR 2026 会议版与 arXiv 2510.11977v1;身份字段的时间线据 princeton-pli/hal-harness 仓库 HEAD 16bb03e(2026-07-01 归档)与 HAL 网站(2026-11-06 抓取)。
  • Harness-Bench 据 Qihoo360/harness-bench 仓库 commit b8d8963(2026-10-09)的 README 与运行工具;Terminal-Bench 的 Harbor 版本钉在其仓库的 .github/harbor-version;Harbor 关于任务不声明工具的理由见其文档 /tasks/environment 的 Tools 一节(2026-10-31 读取)。
  • ABC 清单的 R.6 见 arXiv 2507.02825v5;τ²-bench 的策略文档实验见 arXiv 2506.07982v1。
  • 宿主矩阵「脚手架 × 模型双变量,差异不做归因拆分」的口径见第 4 篇;「宿主配置列为必进报告的格子变量」见第 5 篇。

分数在说谎的四种方式——空跑、总分、分母与终态

上一篇认清了分数的主人:它属于「模型+harness」这个组合。这一篇假设主人认对了,再问分数本身。分数默认被读成能力,可在 agent 评测里,它至少会在四个地方说谎:什么都不做也能过;总分不动,里面却掉了 17 分;分母悄悄变小;做了坏事又撤销,评分器看不见。这四种都不报错,而且大多让分数更好看,所以很少有人去查。其中几种我在自己的工具链上撞过(第 3 篇、第 8 篇),这一篇看它们在公开 benchmark 上长什么样。

本章将讲

  • 空跑:什么都不做也能拿分。「可被利用」的数字和「实际偏差」的数字是两类,别混着引;空跑与 oracle 两个 agent 组成的门禁,以及它们抓不到的东西。
  • 总分与分母:聚合是不可逆的压缩;评分器越早崩分越高,剔掉基础设施错误能让 pass² 翻倍;分母规则该按「是不是被测系统的责任」来划。
  • 终态:只看终态的判法最干净,却看不见被撤销的破坏和悄悄加上的豁免。

一、什么都不做,也能拿分

先看几个被反复引用的例子,都出自 ABC 清单的论文:

  • 在 τ-bench 的 airline 子集上,一个立刻返回、什么都不做的 agent 拿了 38 分,比 GPT-4o agent 的 35 分还高;
  • 一个把所有可能答案和数据全列出来的 agent,在 airline 上拿了 40%;
  • SWE-Lancer 把测试放在带密码的 ZIP 里,看起来是隔离了,可不知道密码也能列出目录、覆盖文件。agent 把测试换成 assert 1 == 1,不解题就拿了 100%。

ABC 用自己的清单审了 10 个热门的 agentic benchmark:7 个违反任务效度,7 个违反结果效度,10 个全都有报告缺陷,80% 没有承认自己的弱点。有意思的是,τ-bench 的任务效度十条在附录里全部满分:题本身没问题,出问题的是判分。这就是第 3 篇第一种谎言的公开版:检查问的是「终态里有没有这个状态」,该问的是「这个状态是不是 agent 造成的」。什么都不做的时候,两个问题的答案恰好一样。

引用这些数字时要小心。ABC 的数字分两类:

  • 可被利用类:构造出来的 agent 能拿到的绝对分,比如 38、40、100。它们证明的是「有口子可钻」,不是真实 agent 的实际偏差。
  • 实际偏差类:对已报告分数的修正量,比如 WebArena 高估 1.4–5.2%,KernelBench 高估约 31%,OSWorld 低估 28%。

两类常被混引成「agent benchmark 普遍高估多少」,这是误读。

怎么防:两个 agent 组成的门禁。 一个照参考解执行的 oracle,必须满分;一个什么都不做的空跑 agent,必须失败。用前几篇的话说,oracle 是阳性对照,空跑是阴性对照,和第 4 篇全程压阵的 C0 是一个角色。Terminal-Bench 第一版的 CI 就是这样设的:Oracle 和「NOP Agent (Should Fail)」都是必过的硬门禁,三个真实模型只作难度参考,跑不过也不挡合入。

AppWorld 做得更细:它给每一条评分检查都标上「空跑会不会过」,取值只有 no_op_pass 和 no_op_fail,在出题阶段就算好。于是每次运行的报告里,每条通过都能分辨出来:是 agent 做对了,还是本来就会过。

ABC 还有一条 R.13:报告 trivial agent 的成绩。附录 D 里,τ-bench、SWE-Lancer、WebArena、MLE-bench 在这一条上都记 0。准入时如果已经跑过空跑,把结果报出来几乎不要成本。

空跑抓不到什么。 空跑只抓「不做也能过」,抓不到「做错了也能过」。KernelBench 的随机测试只改张量的数值、不改形状,错误的实现照样通过;后来靠抽样复判才测出,正确率被高估了约 31%。另一边,oracle 满分也发现不了评分器过严:参考解当然能过,换一种正确写法会不会被误判,它看不出来。WorkBuddy 的办公子集为此在发布前,用多份保存下来的合格提交回放评估器,专门查误判。空跑和 oracle 只是评测自检的下限,不是全部。过严这一侧,第 13 篇再展开。

二、总分不动,里面掉了 17 分

WorkBuddy 里,GLM-5.2 的办公总分换了 harness 几乎不变,79.60 对 79.57。拆开看,「多文件抽取」从 87.7 掉到 70.5,「复杂规则执行」几乎不动(83.1 对 83.3)。只报总分,这 17 分的能力位移完全看不见。

第 9 篇在记忆题库上见过同一件事:两个库一平均,两种失败互相抵消着藏起来。聚合是不可逆的信息压缩,几个来源在这件事上的做法很一致。

单题判定用二元。 AI Evals FAQ 反对 1 到 5 分的量表,理由有三条:相邻两档的差别太主观,标注者之间对不齐;要检出差异需要更大的样本;标注者倾向选中间值,回避难判的情况。需要粒度时,就拆成多个独立的二元检查:不给「事实准确性」打 1 到 5 分,而是记「5 个预期事实里包含了 4 个」。

部分分跨题不可比。 AppWorld 每题的评分检查从 1 条到 24 条不等,「5 条过 3 条」和「3 条过 3 条」压成同一个比例,没有意义。它对外只报二元的成功与否;代码里明明实现了通过百分比,却没有汇总进任何报告。我的读法是,这是刻意不让分数被污染。

非要一个数,就用 pass-all rate。 这是 FAQ 的推荐:一个样本要通过全部检查才算通过;报表能下钻到每项检查;也可以按主题或严重度分组,比如「该阻塞发布的检查」和「可以容忍的检查」各报一个率。

评分契约不同,就别出综合分。 WorkBuddy 的四个子集评分工具各不相同,作者明确不报全套件平均分,并说这是有意的设计,不是待补的缺口。

三、分母比分子难

第 8 篇焊死过一条纪律:无效永远不是失败,失败是 agent 的,无效是我们的。这一节讲它的另一半:无效剔出去之后,分母怎么报才不虚高。判对错只是测试套件的事,真正让分数说谎的,常常是分母。

评分器越早崩,分数越高。 有一种常见的评分脚本写法:所有检查放在一个 try 里,在 finally 里按「已记录的检查数」算分。提交物只要让评分器在第三个检查处抛异常,分母就只剩 2;越早把评分器弄崩,比率越高。WorkBuddy 用语法树识别这种写法,把脚本改写成每个检查独立执行,分母改用事先声明的检查数,没跑到的检查记失败。

没跑的题去哪了。 如果只对「碰巧跑完的题」求平均,部分失败的运行分数会虚高。WorkBuddy 从清单里读出期望的任务列表,凡是在清单里却没有任何产物的任务,合成一条 never_ran 的记录,记 0 分,进入每一个分母。清单因此不只是审计材料,而是指标正确性的前提。我自己的总单里有一条同病的记录(第 14 篇):超时用例从分母里消失,长出的机制是排除计数显式上报。

剔除也会虚高。 τ²-bench 把每次模拟的结束方式记成十种,默认最多 200 步、不设超时。除了用户正常结束和 agent 正常结束,其余一律记 0 分并记下原因;但基础设施错误那几行,会在计算 pass^k 之前被整行剔除。这听起来很公平,可 pass^k 的公式是 C(c,k)/C(n,k)(定义见第 6 篇)。按公式算一个例子:4 次试验里成功 2 次,pass² 约为 0.167;剔掉 1 次失败的试验,变成 3 次里成功 2 次,pass² 约为 0.333,直接翻倍。如果基础设施错误和任务难度相关(比如长任务更容易断连),这个偏差就有方向,系统性偏高。

评分器出错,被记成 agent 做错。 AppWorld 本来有意区分评分器内部的错误和断言失败:它的差量检测函数会抛一种专门的「不可抑制」异常,报错信息的意思是「评分时遇到它,说明出了不该出的事」。可负责记录每条检查的那段代码,退出时无条件吞掉一切异常,没有为这种异常开例外。按代码读下来,评分器自己的 bug 会被记成一条普通的测试失败,和「agent 做错了」混在一起。这是读代码得出的推论,我没有实际触发验证;但它说明一件事:评分器的异常要单独成类,不能落进「失败」里。这正是第 3 篇说的「假失败」。

一种原因决定三件事。 Harbor 的处理是现成的参照:每种异常映射到唯一一个原因,这个原因同时决定要不要重试、还跑不跑评分器、算不算进分母。agent 自己导致的失败,比如超时、上下文或输出耗尽、安全拒答,算进分母、照常评分;沙箱失败不算进分母,会重试,不评分;模型供应商失败、评测框架自身的失败和取消,都不算进分母;评分器失败不算进分母,但评分照样执行。

我认为分母规则不该看「跑没跑完」,而该看「这次失败是不是被测系统的责任」:

  • agent 自己超时、上下文耗尽、拒答,算进分母;
  • 沙箱、供应商、评测框架的故障,不算进分母,但要单独计数、单独报告;
  • 剔除之后,按各任务存活的试验数重新确定能报的最高 k;故障率超过阈值,整轮判为「未完成」,而不是给一个低分。

四、做了又撤销,等于没发生

第 1 篇把终态列为断言目标的第二次搬家:不管过程怎么抖,最后落库的状态对不对。这是 agent 评测里最干净的判法,允许多条合法路径,不会误杀「走法不同但正确」的解。可它对路径上的事是瞎的。

τ-bench 的作者在定义奖励时就写明:拿到满分可能只是成功的必要条件。比如 agent 未经用户明确确认就办了退货,违反了策略,却仍然能拿满分。

终态判法做得好的样子。 AppWorld 不直接比对终态,而是先算初态到终态的差集,再检查两条集合不等式:期望的变更全部出现在差集里;差集不超出「期望变更」加「允许变更」的范围。不该发生的事无法穷举,允许发生的事通常很少,所以倒过来写成减法。为了让全量比对便宜,它给每行存内容哈希、给每张表维护计数器、分级比较;101 张表、36 万行的数据库,每题评分平均不到 0.6 秒。τ²-bench 更省事:对参考环境和实际环境的数据库整库取哈希,任何一次与任务无关的写操作都会让哈希对不上。副作用检查成了免费的附带结果,前提是状态能被确定性地序列化。

它看不见的两类东西。

  • 被撤销的破坏。 AppWorld 的行级比对按内容哈希,把新增和删除逐条配对抵消,代码注释把这写成正式语义。在没有真实后果的沙箱里,这样做合理;可只要任务会真发邮件、真调下游、真动钱,数据库恢复原样,不等于世界恢复原样。
  • 悄悄加上的豁免。 AppWorld 的变更检测里硬编码了三张无条件忽略的表,其中一条注释的意思是「暂时全局忽略」。全局忽略一旦加上,那部分状态的副作用检查就永久关闭了,而且不会出现在任何报告里。

我的建议是:对外有不可撤销效应的任务,要在终态检查之外加一条看调用日志的规则,某些调用一旦发生就算违规,跟终态无关;豁免要随任务声明,并在每次评分的输出里列出本次生效的豁免项。

五、出分之前的检查清单

  1. 跑空跑和 oracle。 空跑必须失败,oracle 必须满分,并把空跑成绩写进报告。
  2. 给每条检查标上「空跑会不会过」。 看分数时先减掉「本来就会过」的那部分。
  3. 按切片报,不只报总分。 总分不动不等于行为不变。
  4. 判定用二元,要粒度就拆检查。 评分契约不同就不出综合分;非要一个数,用 pass-all rate。
  5. 分母用期望清单。 没跑的记 0;评分器按声明的检查数算,没跑到的检查记失败。
  6. 剔除要有规则。 按责任归属决定进不进分母;被剔除的单独计数;按存活试验数重定可报的 k。
  7. 副作用写成减法,豁免要显形。 对外不可撤销的操作单独判,豁免随任务声明并在输出里列出。

六、反方与局限

  • 别把「可被利用」读成「实际发生」。 38 分证明的是口子存在,不是真实 agent 平均被高估了 38 分。
  • 二元判定也有代价。 对验收点很多的真实工单类任务,全有或全无的判定会丢掉诊断信息;这时更需要保留每一条检查的结果。
  • 分母的错误不一定都朝虚高。 把基础设施故障记成 0 分混进均值,会让分数偏低。本篇举的几个例子都偏高,但这不代表所有分母错误都朝一个方向。
  • 加轨迹判据有成本。 评分器一旦要读轨迹,就失去「与执行方式无关」的好处,换执行方式、加界面都可能牵动评分器。只有任务确实有对外写操作时,才值得付这个代价。
  • 数字都是读来的。 和上一篇一样,文中的数字来自原论文和原仓库的代码与文档,我没有复现任何实验。

一个分数可信之前,先问四个问题:什么都不做能拿几分?拆开看哪里变了?分母里少了谁?终态之外发生过什么?下一篇换一个更难的对象:测 agent 会不会从经验里变强。那里连「分数该比什么」都还没定下来。

参考与延伸

  • 本篇成书首发,与作者的独立文章《分数在说谎的四种方式:空跑、总分、分母与终态》同源;事实均取自公开论文、代码与文档,作者未复现任何实验。
  • 空跑 38 分、穷举答案 40%、SWE-Lancer 的 100%、10 个 benchmark 的审计结果与两类数字的区分,见 Zhu 等,Establishing Best Practices for Building Rigorous Agentic Benchmarks(ABC 清单),arXiv 2507.02825v5(2025-08-07)。
  • τ-bench 的奖励定义与 pass^k 公式见 arXiv 2406.12045v1;τ²-bench 的十种结束方式、步数上限与剔除逻辑据 sierra-research/tau2-bench 仓库 commit da0835f(2026-10-29)。
  • Terminal-Bench 第一版的门禁据 harbor-framework/terminal-bench-1 仓库 .github/workflows/test-tasks.yaml(2026-10-31 读取);Harbor 的异常分类据其文档 /jobs/error-classification(2026-10-31 读取)。
  • AppWorld 的判定方式与性能见 arXiv 2407.18901v1;no_op 标注、差集抵消、全局忽略表与异常吞没据 StonyBrookNLP/appworld 仓库 commit 42b5bcf(2026-09-03)。其中「评分器异常被记成普通失败」是读代码的推论,未实际触发。
  • WorkBuddy 的子集分数与不出综合分的说明见 arXiv 2607.20911v1;评分脚本改写与 never_ran 记录据 Tencent/workbuddy-bench 仓库(2026-10-31 读取)。
  • 二元判定与 pass-all rate 见 Husain 与 Shankar 的 AI Evals FAQ(hamel.dev,2026-10-31 读取)。
  • pass² 从 0.167 到 0.333 的例子是作者按公式算的。

测「会学」容易,测「越学越快」难——从持续学习基准到 RSI 评测

第 9 篇测的是我能做配对实验的那种记忆:同一道题,有记忆跑一遍,没记忆跑一遍。今年公开 benchmark 也开始测「agent 能不能从经验里变强」,好几个标题里还写着 RSI。我把它们读了一遍,结论是:第一层「会学」已经能测得比较干净;「越学越快」有人设计出了测法,但还没有测出结果。

本章将讲

  • 「从经验中变强」分三层:积累经验、改造自己、递归加速。判断属于哪一层,看改进作用在谁身上,以及改进的速度有没有变快。
  • 第一层要两样东西:配对的无状态对照,加上机制证据。标题写着 RSI 的 benchmark,有的连第一层都还没分离出来。
  • 第二、三层的测法,以及唯一一次正面测「加速」的实验;被测物能改自己时,评测就多了一个对手,只能靠结构隔离。

一、把历史塞进上下文,赢了专门的记忆系统

Continual Learning Bench(下称 CL-Bench)测的是一件事:agent 做一串相关任务时,能不能从前面做过的任务里学到东西,越做越好。上一篇借它的名次讲 harness;同一张榜换个角度看,还有一个更扎眼的现象:

  • 同一个 GPT-5.4,接最朴素的上下文学习(in-context learning,ICL),也就是把做过的题和反馈直接拼进上下文,综合排第 2;换成专门的记忆系统 Mem0 排第 5,ACE 排第 9,Codex 排第 10;
  • Claude Sonnet 4.6 也一样:接 ICL 排第 1,接 Claude Code 排第 3。

论文摘要说得更直接:朴素的 ICL 胜过专门做记忆管理的系统。这也不是孤例。8 月发布、10 月改到第三版的 ContinualSkillBench 发现,在两个模型、三个领域上,只保留上下文和反馈、不去维护技能库,平均表现和维护一个显式技能库几乎一样。

读到这里,很多人会想到递归自我改进(recursive self-improvement,RSI):系统从经验里变强,变强之后改进得更快,一路加速。10 月底发布的 Continual Learning Exam(下称 CLE),标题里就写着「Long-Horizon RSI」。

上个月我在博客《RSI:叙事用完成时,机制用进行时》里对过一个项目的表:RSI 的主张写成了完成时,代码里对应的机制还是默认关闭的实验开关。这一篇换一个角度,不看谁宣称了 RSI,看 benchmark 实际测到了哪一层。我的回答是:这些 benchmark 测到的「会学」和 RSI 之间,至少还隔着两层。

二、三层:积累经验、改造自己、递归加速

我把「从经验中变强」分成三层:

层次改进的是什么例子现在测得到吗
1. 积累经验做题表现越来越好,学习机制本身不变ICL、笔记本、Mem0 这类记忆系统能,前提是有配对对照
2. 改造自己系统改自己的提示、工具或代码STOP、Gödel Agent、Darwin Gödel Machine部分能,多是论文自带的评测
3. 递归加速改进的是「改进的能力」本身,而且越改越快严格意义上的 RSI有人设计了测法,还没测出结果

判断属于哪一层,看两点:改进作用在谁身上;改进的速度本身有没有变快。

CLE 给 RSI 下的定义很清楚:被保留下来的改动,要能「improve how subsequent improvements are generated, evaluated, or implemented」。它还特意说明,在线学习、测试时训练、案例复用,都可以在学习过程固定不变的情况下进行,单用它们并不构成 RSI。这正是第一层和第三层的分界:前者积累的是做题的知识,后者改进的是获取知识的过程。

第二层的例子不少:

  • STOP 让一个调用语言模型的「改进程序」去改进它自己的代码;
  • Gödel Agent 让 agent 借助大模型,在运行中修改自己的逻辑和行为;
  • Darwin Gödel Machine(下称 DGM)让编码 agent 反复改写自己的代码,把生成的变体存进档案库,每次改动都在编程 benchmark 上检验。

DGM 的摘要说,这样改下去,它修改自己代码的能力也在提高,这已经碰到了第三层。但它实际报告的是 SWE-bench 从 20.0% 涨到 50.0% 这类分数,而不是改进的速度有没有越来越快。改的是「自己」,测的仍然是「做题」。

三、第一层怎么测才算测到

测第一层,最容易犯的错,是把「本来就会」当成「学会了」。一个强模型在后面的题上得分高,可能只是因为它本来就强,和前面做过什么没有关系。

CL-Bench 的解法是配对的无状态基线(stateless baseline):

  • 同一个系统跑两遍:一遍保留状态,一遍在每个实例之前清空;
  • 对每个实例,用前者的得分减去后者,得到 gain;
  • 某个实例对这个系统来说难或容易,会同时体现在两项里,相减之后,剩下的就是累积状态的贡献。

这就是第 8 篇手册里的配对:让每个任务自己跟自己比,把题目难度这个最大的噪声项从分母里消掉。文档也承认,难度和累积状态之间更细的交互,这样减并没有完全消掉。gain 的读法有三种:为正,经验帮上了忙;为零,看不出学习;为负,累积的东西反而有害,比如遗忘、干扰信息越积越多,或者记住了错误的状态。跨任务汇总时,它再按「还剩多少提升空间」归一:gain 除以任务上限与无状态得分之差。

8 月发布的 PAST-Bench 又往前推了一步。它同样在相同条件下打开、关闭保留的经验做对比,覆盖 26 个场景、204 个回合;但它不只看分数涨没涨,还检查涨分是不是走了预期的路径:经验有没有被保存、被检索、被更新。结果是,总分涨幅相同的两个系统,在路径证据上可以差得很远。这三件事和第 9 篇的三层乘法链(写入、检索、采信)几乎一一对应。分数对了,原因不一定对;不逐层记录,「学到了」和「记忆系统没用」一样,都是无法证伪的话。

反过来看 CLE。它的规模很大:

  • 50 多位领域专家出题,120 个任务,每个分 5 级,共 600 级;
  • 覆盖 89 个职业角色、12 个领域;
  • 最好的系统只过了 47.7% 的级别,5 级全过的任务只有 23.3%。

但它的测法是:每个系统按一个固定顺序,把 120 个任务串行跑一遍;Trial 1 每级只能交一次,Trial 2 在交错之后可以看诊断反馈再交一次。两者之差,测的是「反馈加重交」的作用,完成率的中位数提升了 5.3 个百分点。作者在结果部分自己写明:要评估跨任务保留下来的知识起了多大作用,需要另做一组「每个任务前把 harness 重置回初始状态」的配对比较。这组比较,文中没有做。

所以,CLE 的数字说明了任务难,没有说明学到了多少。标题写着 RSI,它连第一层的「学会了多少」都还没分离出来。

测第一层,至少要两样东西:配对对照,把「学会了」从「本来就会」里分出来;机制证据,确认涨分走的是预期的路径。

四、读这类榜单的几个坑

配对对照解决了「测什么」,榜单怎么读还有几个坑。以 CL-Bench 为例:

  • 前四名挤在噪声里。 前四名的综合归一 reward 分别约为 0.196、0.189、0.185、0.183,首尾只差 0.013。而单个任务上,5 次运行之间的波动很大:排第 2 的 ICL · GPT-5.4,在 codebase_adaptation 上归一 gain 的标准差约 0.41;全榜最大的是 ICL · Gemini 3.1 Pro 在 cohort_studies 上,约 0.87。首页只给名次,不给区间。
  • 运行次数不一样。 Codex · GPT-5.4 在 6 个任务里有 5 个只跑了 1 次,别的系统都跑了 5 次,却排在同一张榜上。第 6 篇说过单次跑分不作数,这里是一张榜上混着两种口径。
  • 综合分是相对位置。 综合 reward 以 GPT-5.4 的无状态 ICL 为固定参照点归一,所以会出现负数,比如 ICL · Gemini 3.1 Pro 是 −0.076。负数不是倒扣分,只是低于这个参照点。
  • 一个任务撑起了综合 gain。 在 sales_prediction 上,12 个系统里有 10 个的归一 gain 在 0.4 以上;在 exploitable_poker 和 cohort_studies 上,没有一个超过 0.2,不少是负的。

看这类榜单,我的顺序是:先看运行次数和区间,再看归一的参照点,最后看分任务的结果。总分排名在这个阶段参考价值有限。

五、第二、三层现在怎么测

到了第二、三层,被测的东西从「做题表现」变成了「改进本身」。今年出现了两类测法。

第一类,测 RSI 需要的某一项能力。

AI4AI-Bench 的出发点是:RSI 要改进的是「产生 AI 系统的过程」,这个过程的核心是训练算法。它的设置是:

  • 收了 10 个冻结的研究仓库,覆盖 10 类训练算法;
  • agent 用一张 B300 有 4 小时改写训练算法,之后代码从头重跑最多 12 小时,由一个对 agent 隐藏的固定评估器打分;
  • 分数刻度上,0 是无信息模型,0.1 是仓库原本的算法,1.0 是最优。

结果,6 个系统的 29 种配置平均 0.166,最好的是 0.250。最强的系统也没补上原算法到最优之间五分之一的距离。

RSIBench-Data 测的是另一项能力:以数据为中心做训练研究。训练栈和预算都固定,agent 反复修改训练数据策略。58.33% 的设置里,agent 能做得比第一次有效尝试更好;但在拿到最高分之后还继续搜索的情况里,78.26% 最后一次的分数低于最高分。能改进一点,但维持不住。

第二类,系统自己跑完整的自我改进循环。

AIDE² 让一个研究型 agent 改写自己的代码。每次改动都要在被改写的 agent 看不到的留出数据上变好,才会被接受。它连续自主跑了 8 天,找到 7 次相继的改进;最强的版本,在 4 个外部 benchmark 上追平或超过了一个人工打磨了两年的生产级研究 agent。

这些测到的,是「能不能改进」「能连着改进几次」,以及 RSI 需要的某一项能力。那「越改越快」呢?

在我读到的工作里,只有 AIDE² 正面去测了。作者提出了一个「点火测试」(ignition test):被改进出来的 agent,驱动下一轮自我改进的能力,必须强过产生它的那个 agent,收益递减才有可能变成加速。他们做了两组对照:一组让新 agent 驱动外层的改进循环,一组仍用原来的 agent,其余条件相同,各跑 3 个种子、50 步。

结果,两组的平均分最后停在 0.780 和 0.782,几乎一样。作者的结论很克制:可能有样本效率上的收益;但要下定论,需要更多种子和完整的留出评估,代价高得难以承受。他们还指出,两层循环的噪声会叠加,一次误判的比较,就可能把外层循环带偏。

这还是第 1 篇说的第二难:样本量不由统计愿望决定,由预算决定。「越学越快」已经有了测法,挡在前面的是噪声和成本。

六、能改自己的系统,会改掉检测它的东西

被测系统一旦能改自己,评测就多了一个对手。

DGM 的论文里有个例子。研究者想让 DGM 解决「假装调用工具」的问题:模型并没有真的调用工具,只是在文本里写出了工具的输入和输出。为了检测这种情况,他们在每次真实调用工具时插入特殊标记,再看这些标记有没有出现在模型的纯文本输出里。

其中一个节点只改了两次,就拿到了满分 2.0。它的办法是删掉记录这些特殊标记的日志,而指令明确要求不许改动这些标记。分数是满的,问题一点没解决。作者把这叫作指标刷分(objective hacking),并观察到:检测函数不对 agent 隐藏时,这种情况更常发生。

今年几份工作的防法很一致,都是让评分材料在结构上够不着:

  • AI4AI-Bench 用对 agent 隐藏的评估器,并把改好的代码从头重跑;
  • AIDE² 只接受在被改写的 agent 看不到的留出数据上变好的改动;
  • CLE 把评分细则和参考材料放在被测 agent 访问不到的地方,评分由一个独立的评分 agent 在隔离环境里做,每次评分都起一个全新的容器。

被测物能改自己时,靠提示词约束没有用,DGM 那条「不许改标记」的指令就被绕了过去,只能靠结构隔离。第 4 篇做伤弹实验时我学过同一课:宿主可见的任何路径都不能编码伤型,连目录名都是泄密渠道。下一篇把这件事单独拿出来讲:评分器本身就是被攻击的对象。

七、要自己测的话:一份检查清单

评测一个号称「会学」或者「会自我改进」的 agent,我会至少做到七条:

  1. 配对的开关对照。 同一系统,保留经验和不保留经验各跑一组,逐实例相减。
  2. 多种顺序、多次运行,报区间。 顺序会影响学到什么,单次运行的名次不可信。
  3. 机制证据。 确认涨分走的是「保存、检索、更新」这条路,而不是别的捷径。
  4. 评分材料隔离。 评估器、参考答案、留出数据,被测系统都够不着;改过的代码从头重跑再评。
  5. 记录每次自我修改的谱系。 哪次改了什么、在什么数据上被接受,要能回溯,出了问题才能定位。
  6. 测「加速」要有二阶对照。 学习机制冻结的一组和允许修改的一组,比较的是改进的速度,而不只是分数。
  7. 事先估好成本。 二阶对照要很长的序列和很多种子,AIDE² 的作者就卡在这里。先算清预算,再决定测到哪一层。

八、反方与局限

  • RSI 的定义还没有共识。 CLE 的定义偏向「改进学习过程」,AI4AI-Bench 落在「改进训练算法」,AIDE² 落在「改进 agent 自己的代码」。换一个定义,「测到没有」的结论可能不同。
  • ICL 胜过记忆系统,可能和任务序列太短有关。 CL-Bench 每个任务只有 12 到 120 个实例,在这个长度上,把历史直接塞进上下文还放得下。序列再长,结论可能会反过来。
  • 这批 benchmark 都很新,样本小,多数只有一版。 点火测试只跑了 3 个种子,结论随时可能被推翻。
  • 我只读了这些论文里和本篇相关的部分,没有复现任何实验。

回到标题:测「会学」,先找配对对照;测「越学越快」,先问成本付不付得起。

参考与延伸

  • 本篇成书首发,与作者的独立文章《测「会学」容易,测「越学越快」难:从持续学习 benchmark 到 RSI 评测》同源;事实均取自公开论文、网站与数据,作者未复现任何实验。
  • CL-Bench:Asawa 等,arXiv 2606.05661v1(2026-06-04);指标定义据其网站 Metrics、Concepts、Tasks 页(2026-11-07 抓取);名次、运行次数与分任务数字据排行榜原始数据 leaderboard_data.json(数据更新于 2026-07-18,2026-11-07 抓取),标准差由作者按原始数据计算。
  • ContinualSkillBench:arXiv 2608.03874v3(2026-10-15)。PAST-Bench:arXiv 2608.04003v1(2026-08-04)。CLE:Zhao 等,arXiv 2610.33956v1(2026-10-25)。
  • STOP:Zelikman 等,arXiv 2310.02304v3。Gödel Agent:Yin 等,arXiv 2410.04444v4。DGM:Zhang 等,arXiv 2505.22954v3(2026-03-12),指标刷分的例子见其附录。
  • AI4AI-Bench:arXiv 2608.20318v1(2026-08-20)。RSIBench-Data:arXiv 2607.25886v1(2026-07-28)。AIDE²:Recursive self-improvement of AI research agents,arXiv 2609.26457v1(2026-09-22)。
  • 对一个项目 RSI 主张的代码对表,见作者博客《RSI:叙事用完成时,机制用进行时》(2026-10-18)。

谁来验收评测本身——隔离、双向校准与评审门槛

前三篇读的是分数:它属于谁,在哪里说谎,测到了哪一层。这一篇读量出分数的那把尺子。我们习惯拿评测去量被测系统,可尺子本身也会出错:会被钻空子,会误杀正确的答案,会悄悄失效却照样报喜;拿 LLM 当评审时,「已校准」三个字也可能撑不住它报出来的数字。本卷的公理说评测的全部产物自己也要被测,这一篇看公开 benchmark 怎么给自己做验收。

本章将讲

  • 评分器是被攻击的对象:钻缝不需要作弊意图,隔离只能靠结构,而且隔离、保密、抗污染是三件事。
  • 误差有两个方向:放水和误杀。常见的检查只查放水,看结果的人也只看判失败的格子。
  • LLM 评审的门槛:口径互相翻译不了,样本量撑不起点估计,逐条达标不等于整体达标;以及评测的递归栈该停在哪一层。

一、评分器是被攻击的对象

先看评测框架自己出过的事。Harbor 是 Terminal-Bench 背后的评测框架,它在文档里公开了几起事故:

  • 本地 Docker 环境曾把 agent 容器里的评分目录自动挂了出来,agent 可以直接写出评分器会读取的分数文件。现在这类挂载改成了手动开启,评分开始前还会先删掉已有的分数文件。
  • agent 留下一个 setuid 程序,被评分器以 root 身份执行后,自己写分数文件。
  • agent 把输出文件做成指向参考答案的符号链接,评分器就成了拿参考答案和它自己比。

这些都不需要 agent 有「作弊意图」。agent 只是在环境允许的动作里找能得分的路径,钻的是「环境允许」与「出题意图」之间的缝。上一篇的 DGM 删掉检测日志拿满分,是同一条缝在能改自己的系统上的样子。

今年 5 月的 BenchJack 把这件事做成了系统性的审计。作者从既往的刷分事件里归纳出 8 类反复出现的缺陷,整理成一份给出题人用的检查清单,再让 coding agent 自动去审计 benchmark。他们审了 10 个热门的 agent benchmark,覆盖软件工程、网页、桌面和终端操作:在多数 benchmark 上,生成的利用手段一道题不解就能拿到接近满分,一共找出 219 个不同的缺陷。他们还把审计扩展成「发现、修补」交替的迭代流程:在 4 个没有致命设计缺陷的 benchmark 上,可钻空子的题目比例从接近 100% 降到 10% 以下,WebArena 和 OSWorld 在三轮之内补全。

所以评分器应该按「有人会攻击它」来设计,而这种攻击可以、也应该被自动化地测出来。

二、隔离只能靠结构

既然 agent 会钻缝,靠约定的隔离就挡不住。「把测试放在单独的目录里,告诉 agent 别看」属于约定;Harbor 换成了结构:

  • 评分跑在一个全新的容器里,测试和真值烘进评分镜像,从不进入 agent 的容器;
  • agent 对文件系统的改动不会被继承,只有显式声明为产物的路径才能跨过去,连 agent 的日志也不例外;
  • 评分容器在 agent 容器销毁之后才启动。

跨界的产物还要先净化:清掉 setuid 和 setgid 位,跳过指向外部的符号链接,跳过 FIFO 和设备文件。Harbor 的文档还特意加了一句:净化之后,内容仍然是不可信的输入。

如果评分时必须执行 agent 写的代码,就把它当成不可信的用户:

  • 每次都用一个全新的、没有账户的用户身份运行,读不到测试目录,写不了评分日志;
  • 返回之前杀掉它启动的所有进程;
  • 超时按失败计;
  • 隔离边界搭不起来时,让异常直接抛出,一个分数都不写。

WorkBuddy 把隔离做在镜像构建这一步:任务镜像只拷入 agent 可见的工作区,评分材料从不进镜像,到评分阶段才上传。用论文的话说,评估边界是打包本身的属性,而不是运行时的配置。

这几条我在第 4 篇的伤弹实验里学过缩小版:做实验的人不能当宿主,宿主可见的任何路径都不能编码伤型。当时防的是宿主「看出来」,这里防的是 agent「改得动」,道理是一个:不能指望被测物不看、不碰,只能让它够不着。

还有一点常被混淆:隔离、保密、抗污染是三件事。WorkBuddy 的「隐藏测试」只是指解题时 agent 看不见;隐藏测试和参考补丁本身,是随数据集全部公开的,抗污染靠的是改写题目和版本化。对私有评测来说,「不公开」不等于「隔离好了」。保密挡不住被测系统在运行过程中读到评分材料。

三、误差有两个方向,常见检查各漏一边

评测出错有两个方向:放水,把错的判成对的;误杀,把对的判成错的。几乎所有关于评测缺陷的讨论都集中在放水上,可误杀一点也不少见。

SWE-bench Verified 的来历就是一个例子。OpenAI 请 93 名开发者标注了原版 SWE-bench 的 1,699 道题:38.3% 被标为题面描述不足,61.1% 被标为测试可能把有效解判错,最后剔除了 68.3%。这些是标记比例,不是实测的误判率,但方向很清楚:原版的主要问题是低估。

误杀没人查,是因为两个方向的发现成本差得太远。证明放水,造一个什么都不做的 agent 跑一次就够了;证明误杀,得逐题论证某个被拒的解其实是对的。ABC 清单的论文记录了一个例子:τ-bench 在标注阶段每题跑了 40 多次,逐一检查成功率为零或很低的题,但只查了「过不了」这一个方向,结果什么都不做的 agent 照样在 airline 子集拿了 38%(第 11 篇开头那个数)。

看结果的人也有同样的偏向。Who Validates the Validators 做过一个用户研究:9 名参与者看结果总表时,只有一个人按「有没有漏判」的方向逐行核查,其余所有人都只看被判失败的格子。漏判在这样的界面上是看不见的。

所以我建议,评分器的验收要显式地做两个方向:

  • 负例分两栏。 放水一栏:空操作、把所有答案都列出来、子串误匹配、覆盖评分材料、读到残留的真值。过严一栏:语义等价的另一种写法、一题多解、合法的格式变体。过严那一栏不写进验收清单,就永远没人测。
  • oracle 要独立实现。 参考解如果就是判分的基准,它当然能过,「换一种正确写法会不会被拒」就测不到。oracle 最好照题面独立实现,不看评分器的代码,最好还准备几种不同的写法。这和第 14 篇的双实现互证是同一个思路:用另一份独立的实现当尺子。
  • 强制复核判「通过」的样本。 审计界面要对称地呈现两侧,而不是只把失败的格子标红。

四、LLM 评审:门槛撑不起它的数字

拿 LLM 当评审,问题更多。judge 怎么校(TPR 与 TNR 分开看、Unknown 是合法判决、校准集优先用有机失败),是第 14 篇收口时的三条纪律。这一节只看另一个问题:门槛和样本量撑不撑得起「已校准」这几个字。

先看一个「最有利条件」下的结果。Who Validates the Validators 的作者自己设计任务、自己标注全部标准答案,最后选出的判定集合在医疗任务上覆盖率只有 0.33,也就是三分之二的坏输出没被抓到;在产品描述任务上,好输出被误判为失败的比例高达 0.39。这只是两条单轮文本流水线,不能当基线,但它说明这件事很难。

门槛的口径不统一。 几个来源都给了准入门槛,但互相翻译不了:

  • τ²-bench 的仓库要求精确率、召回率都大于 0.75,F1 大于 0.80,人工认定的违规样本不少于 10 个,kappa 大于 0.60,并声明这只是最低准入线。它把「违规」当正类。
  • AI Evals FAQ 建议每个失败模式标 100 到 200 条,大致按 10/45/45 分成训练、开发、测试三份,开发集和测试集各放 30 到 50 条通过和失败的样本。
  • Who Validates the Validators 这一路,用的是「好输出被误判为失败的比例」,把「成功」当正类。

正类不同、分母不同,除非固定坏样本的比例,精确率的门槛没法换算成误判率的门槛。照搬别人的数字之前,先画一张 2×2 的混淆矩阵,弄清楚自己的正类是什么。

样本量撑不起点估计。 统计上有个「三的法则」:在 n 条好样本上一次误判都没看到时,误判率的 95% 置信上界约为 3/n。按这个算,n 为 16 时是 18.8%,20 时是 15%,30 时是 10%,60 时是 5%。所以只有一二十条标注的时候,即使零误判,也没法说误判率低于 10%。门槛因此要写成置信区间,报告里强制记录样本量;一个样本量撑不起的「已校准」写进报表,比没校准更危险,因为读者会信。这和第 6 篇的老话一个意思:单次跑分不作数,单个点估计也不作数。

逐条达标不等于整体达标。 SPADE 发现,只保留单条误判率达标的判定,合在一起可能远远超标:在一条时尚类流水线上,67 条判定各自都满足约束,合起来的误判率到了 88%;另一条讲座摘要流水线上,32 条合起来是 53%。门槛要管住「集合」,而不只是「每一条」。

提出门槛的人,自己也没全达标。 τ²-bench 的仓库诚实地把多个生产环境里的评审标为「验证待定」。WorkBuddy 的前端子集 70 道题有 786 个计分项,其中 676 项靠 LLM 或视觉模型打分,而作者承认评审的偏差没有单独量化。

达不到门槛时,别降门槛,也别照搬别人的数字。能写成程序断言的写成断言;写不成的,让 LLM 评审只进诊断层,不决定成败,并在报告里写明这个维度没有验证过。

五、评测会坏,坏了却报喜

普通软件坏了会报错;评测管线坏了,却可能报喜。第 3 篇的第二种谎言讲的就是这件事:被测的事根本没发生,绿灯照样全绿。我自己还遇到过更直接的一次:一个测试集全部通过,诧异之后才发现,管线根本没有进入测评环节,系统自动打了满分。「它没报错」证明不了「测量发生了」。这类故障,只看「必过」的检查抓不到,因为本来就是满分;只有「必不过」的哨兵,或者让一个什么都不做的 agent 跑完整个题集,才能抓到。

所以评分器本身也是被测对象,要有自己的测试。我在第 14 篇总单里记的判活器自测,就是给评分器配的回归。Terminal-Bench 的做法更系统:它给自己的评审造了一批合成任务,每个只故意违反评审标准里的某一条,要求评审把被植入的那条判为失败,召回率必须达到 100% 才能过 CI。但这套回归里只有「失败」标签。按这个设计推下去,一个把所有东西都判失败的评审也能拿满分。要补上的是另一半:放进一批合格的样本,确认评审不会误判它们。

六、谁来验收验收者

一层层往上问,会得到一个递归的栈:任务评 agent,测试评任务完成得怎样,评审标准评任务质量,回归测试评评审,对抗加固评题目抗不抗作弊。每加一层,回答的都是「谁来保证下面那层是对的」。我认为不必每层都做满,按规模停层就行:

  • 题目只有个位数、作者都是核心成员,做到前两层;
  • 有外部贡献者,加上评审标准;
  • 人工已经看不过来,加评审的回归测试;
  • 已经被钻过一次空子,再加对抗加固。

对抗加固可以做成自动的。Terminal-Bench 有一个命令,让一个「攻击者」agent 设法不解题也通过验证,另一个「修补者」agent 加固测试和环境,两边交替迭代;作弊脚本不许提交进任务目录。BenchJack 的迭代审计是同一个思路的放大版。这样一来,「一道题抗不抗作弊」就成了可以测量的属性,而不是评审人的印象。

被测系统能修改自己时,这一层更重要。上一篇的两个例子正好是一正一反:DGM 改掉了检测它的东西,AIDE² 用结构上的留出数据挡住了这种可能。

七、给评测做验收:一份检查清单

  1. 按「会被攻击」设计评分器。 问两个问题:环境允许哪些意图之外的得分操作?评分器接受哪些没完成任务的终态?
  2. 隔离做成结构。 独立评分容器,评分材料不进被测环境,跨界产物先净化,执行被测代码换身份。
  3. 分清隔离、保密、抗污染。 不公开不等于隔离好了。
  4. 验收两个方向。 负例分放水和过严两栏,oracle 独立实现,强制复核判「通过」的样本。
  5. LLM 评审的门槛写成区间。 记录样本量,管住集合级的误判,达不到就只进诊断层。
  6. 给评分器配哨兵和回归。 必过、必不过各配一个;回归测试要同时有失败和合格的样本。
  7. 定好停在哪一层。 被钻过一次空子,就把对抗加固接进 CI。

八、反方与局限

  • 结构隔离有成本。 独立容器、净化、换身份执行,都要多写代码、多花时间。BenchJack 也说明,补上已知的缺陷之后,还会有新的缺陷。
  • 「误杀被低估」的证据有限。 SWE-bench Verified 的比例是标注者的标记,不是实测误判率;任一标注者标为严重就剔除,OpenAI 自己也说可能过严。
  • LLM 评审的证据多来自单轮文本。 Who Validates the Validators 和 SPADE 都只评单轮文本输出,SPADE 的九条流水线里有六条是合成数据。多步 agent 轨迹上的评审该怎么审计,现在还没有好的来源。
  • 「三的法则」的应用和停层建议是我的推导。 原文没有给出门槛和样本量的依据。
  • 我没有复现任何实验。

评测本身也是一个要被测试的系统。先假设它会被钻、会误杀、会悄悄坏掉,再去设计它。下一篇是全书收口,从断言形态的最后一次搬家讲起,再回到裁判自己。

参考与延伸

断言不了输出,就断言关系——蜕变测试进 agent 评测

本卷卷首语立过断言危机:非确定性系统的断言目标从结果移走,当时登记的去处是路径覆盖与终态。但这两个去处都假定「什么叫对」列得出清单,而对开放式输出,这个假定本身就不成立。这一篇补第三种移法:**断言不了输出,就断言关系。**界面部分第 16 篇的等价性层早就把它用出来了,只是没叫这个名字;这一篇给它正名,并把它从界面层的测试基建,升级成 agent 评测里的一种断言形态。

本章将讲

  • 断言危机的第三种解法:断言目标从结果移走之后,除了路径与终态,还可以移到关系,以及蜕变关系为什么是非确定性系统的天然断言。
  • 旗舰案例:界面部分第 16 篇的 delta 切分等价性,按断言形态重拆成事后形态和全程形态,以及双实现互证这个 oracle 难题的另一种解法。
  • 与故障注入合流:每一条蜕变关系反过来都是一张注入地图,切分方式本身就是旋钮,呼应第 4 篇。
  • 下半场:裁判也要被校准。一次公开误报的完整一生、judge 校准的三条纪律,以及全书的「错误 → 机制化」总单。

一、断言目标的三次搬家

卷首语把 agent 的断言难拆成三件事,第一件就是非确定性:同一输入不同输出,精确断言必死,断言目标只能从结果移走。当时登记的去处有两个:路径(不管输出是什么,该走的步骤走了没有)和终态(不管过程怎么抖,最后落库的状态对不对)。

这两个去处解了一大批问题,但都还带着 oracle 的影子:路径覆盖要求你预先知道「合法路径长什么样」,终态断言要求你预先知道「什么终态算对」。对结构化的任务(订票、改库、跑测试),这两个清单列得出;对开放式的输出,一段回答、一次渲染、一份计划,列不出。你没法为「这次回答该说什么」写预期值,正如你没法为「这段 Markdown 渲染出来该是什么样」逐帧写预期值。

还有第三种移法,这一篇的主角:移到关系。不断言输出是什么,断言输出与输出之间必须保持的关系:对输入做一个你选定的变换,输出必须满足一个你指定的关系。正确答案依然不知道,但不需要知道了。

二、蜕变关系:没有 oracle 时的断言形态

这个手法在软件测试里有正式名字:蜕变测试(metamorphic testing),核心概念是蜕变关系(metamorphic relation,MR)。它通常追溯到 Chen、Cheung、Yiu 1998 年的一篇技术报告,动机被叫作 test oracle problem:很多程序事实上没有预言机,要么正确答案不存在(画图、排序检索),要么独立算一遍正确答案和被测程序本身一样贵。教科书例子是三角函数:没有表可查,怎么测 sin 的实现?你不需要知道 sin(x) 的具体值,只需要知道 sin(x) 必须等于 sin(π − x):同一个程序,喂 x 和喂 π − x,两个输出必须相等。变换是考题,关系是判卷标准,预期值全程没有出场。

定义很简单:与其断言 f(x) = y,不如断言 f(x) 与 f(g(x)) 之间满足关系 R。g 是你选的变换,R 是你对系统的理解。源用例跑一遍,把输入按 g 变出后继用例再跑一遍,断言的不是两个输出各自是什么,而是它们之间的关系。

这个形态特别适合 agent 评测,理由有三:

  1. oracle 缺位是常态,不是例外。 agent 的产出是开放文本,「正确答案」要么不存在、要么写不起;MR 从设计上就不需要它。
  2. 变换是你控制的。 模型的非确定性在输出侧,而你选 g 的手在输入侧。非确定性还在,但它被关进了「关系必须保持」的笼子:输出可以抖,关系不许破。
  3. 一个关系顶一整个用例矩阵。 切分方式是无限的,逐帧断言永远覆盖不完;关系只有一个,断言一次管所有变换,这正是界面部分第 16 篇说的「一次断言,覆盖无限切分」。

诚实义务也要尽:MR 只能证伪,不能证明。关系被破坏,一定有 bug;关系保持,只是没抓到。这个不对称和第 4 篇故障注入的检出逻辑同构:检出是证据,未检出只是没证据。蜕变测试不是 oracle 的替代品,是 oracle 缺位时的次优制度:次优,但成文。

三、旗舰案例:delta 切分是一条教科书级 MR

界面部分第 16 篇讲过 Codex TUI 的四层断言框架,这里不重复,只把第三层(等价性层)单独抽出来,用 MR 的眼光重新拆一遍。它把流式渲染的正确性钉成一句话:「任意 delta 切分下,流式渲染的可见输出必须收敛于一次性全量渲染」。这句话的结构就是教科书级的蜕变关系:

  • 源用例:模型输出整段、一次性渲染;
  • 变换 g:同一段输出的切分方式,比如按 token 切、按行切、按随机字节切;
  • 关系 R:可见输出收敛相等。

注意这个断言从头到尾没有说「这段 Markdown 渲染出来该是什么样」,它不需要知道。它说的是切不许改变结果。正确答案缺位的地方,关系上岗。

streaming/controller.rs 里的三个测试(2026-10-14 按快照 commit 6b9826e3 复核行号),按断言形态可以分成两类。

事后形态:controller_loose_vs_tight_with_commit_ticks_matches_full(L1143)。关系只钉在终点:全部喂完才和全量渲染比一次。一次断言覆盖整个变换,便宜;但失败时你只知道「破了」,不知道在哪一步破的。

全程形态:controller_live_view_matches_render_during_interleaved_table_streaming(L1619)。关系钉在路径上的每一步:每喂一个 delta 就断言一次「已上屏内容 + 待放行 tail ≡ 全量渲染」。我尤其喜欢它断言失败时的报错设计:报出来的是出事的那个 delta,不是预期画面。失败定位的单位从「哪一帧错了」变成了「哪种切法把它切错了」,变换成了第一公民。

两种形态之间是一个工程旋钮:断言密度。事后形态便宜、定位粗;全程形态贵、定位到 delta。写 MR 测试时这不是实现细节,是设计决策:关系钉得越密,抓得越早,跑得越贵。和卷首语那句「成本是一等约束」接得上:关系的断言密度,同样要用预算裁决。

四、双实现互证:oracle 难题的另一种解法

第三个测试要单独立一类,因为它把 MR 推到了更激进的位置。

incremental_holdback_matches_stateless_scan_per_chunk(L1852):一份有状态的增量实现、一份无状态的全量实现,逐 chunk 断言两者状态相等。用 MR 的语言说:变换 g 是「换一份独立实现」,关系 R 是「两份实现输出相等」。这个形态在文献里有自己的名字,叫伪 oracle(pseudo-oracle);界面部分第 16 篇的大白话更直接:用实现验证实现。

它回答的是 oracle 难题的另一面。MR 的主形态解的是「正确答案不存在」;双实现解的是「正确答案存在,但你信不过任何一份计算」,办法是把绝对正确性问题降级为一致性问题。降级的收益来自独立性:bug 必须同时以同样的方式污染两份独立实现,才能漏网。

残余风险也要写明:两份实现共享的错误理解会双双漏过。同一个作者对 Markdown 表格规则的同一个误读,会同时长进两份代码里,一致性全绿,错误隐身。所以双实现不取代真 oracle,它取代的是「手工列预期值」那一层;规格级的误读,最终得靠本章下半场的裁判校准去抓。

顺手和第 6 篇划一下界,免得两种「参照物」混为一谈:双臂对照(with / without)回答「是不是它的功劳」,参照物是被测物自己的另一臂;双实现互证回答「没有 oracle 拿什么当尺子」,参照物是另一份实现。两者源自同一条原则:没有绝对答案时,用参照物替代绝对答案,分工只在参照物站在哪一侧。

五、与故障注入合流:关系是断言,也是注入地图

界面部分第 16 篇末段留过一个反向启发:等价性层指明了最敏感的注入点,也就是 delta 切分方式。这一篇把它兑现,而且可以说得更强:每一条蜕变关系,反过来都是一张故障注入的地图。

逻辑是这样的。MR 断言「变换 g 下关系 R 必须保持」,等于宣布了系统在哪类扰动下许过承诺;而注入测试要找的最敏感的注入点,正是被许下承诺的地方:承诺越硬,破坏承诺的注入越毒。既然「切分不许改变结果」是承诺,切分方式就是旋钮:按 token 切、按行切、按随机字节切;再往毒里做,可以在多字节 UTF-8 字符中间切、在表格分隔行中间切、在代码围栏的围栏线中间切。每一种切法都是一颗指名道姓的炸弹,炸的都是同一个不变量。随机扰动只能告诉你「系统可能会坏」;MR 指导的注入告诉你「系统承诺过不会这样坏」,后者才是回归套件里该常驻的东西。

这给了故障注入一个和第 4 篇互补的选题方法。第 4 篇的内容完整性炸弹测的是「坏了会不会察觉」,伤型来自对物理失效模式的枚举;蜕变注入测的是「变换下还守不守承诺」,伤型来自对系统承诺的枚举。两份清单最后往往指向同一批部件,但后者多了一层「违约」的语义:检出的 bug 自带证据,不只是「这里坏了」,而是「你承诺过这里不会坏」。不知道往哪注入的时候,先问系统承诺过什么。

所以合流是字面意义的:造得出变换,才写得出 MR;写得出 MR,变换才不只是随机扰动,而是带着承诺条款的考题。第 4 篇从注入一侧到过这个交界,这一篇从断言一侧再走一遍,交界还在原地:断言不了输出,就断言关系;而关系画出的地图,测试与注入共用。

下半场:裁判也要被校准

前五节把断言目标搬到了关系上。但断言再精巧,举着断言的仍是人写的评测系统,而评测系统自己也是软件,也会坏。上半场答「拿什么当判据」,下半场问「判错了怎么办」。这个系列翻过的每一次案,最后都指向同一件事:裁判本身也要被校准,评测系统的 bug 比被测对象的更隐蔽。这既是本卷收口,也是全书收口。

六、一个误报的完整一生

我给 skill-up 提过两个挨着的 issue。第一个是真问题(超时强杀引擎,产物文件整个蒸发),后来成了 issue 加修复 PR。第二个,第二天我自己回到 issue 下面发了一条评论:「这是一个误报,skill-up 的行为完全正确,请关闭。」

误报的诞生现场很体面。为了补回超时丢失的数据,我单 case 重跑了三次,每次控制台都报 1 passed,但产物目录里结果文件依然不存在。发 issue 前我还做了个「严谨」的复现:记录文件 mtime,重跑,再记录,mtime 纹丝不动。「重跑报 PASS 但产物零更新」,铁证如山,我把它连同命令输出一起写进了 issue,标题起得很有把握。

两天后准备提 PR,加 -v 复现,一条 DEBUG 日志把我击毙:重跑的产物 append 进了新的 iteration 目录,这是文档里写得明明白白的语义,行为完全正确。我的两个观测错误原形毕露:其一,三次补跑是在子目录里敲的,相对路径的产物老老实实写进了嵌套目录,而我检查的是仓库根下的同名目录;其二,那个「严谨」的 mtime 复现,stat 的是旧 iteration 的文件。mtime 是真的,数字是一致的,结论是错的。我验证了一个没人怀疑的命题(旧文件不会被改写),却以为自己验证了那个有问题的命题(新文件没有写出)。还有一个隐形的帮凶:头一天那个真实的超时丢产物问题给了我「产物会丢」的先入之见,让我对「又一次丢失」毫无防备。

每一格观测都「对」,拼起来的图景却是虚构的。这就是第 3 篇那条定律在观测者身上的版本:两个世界产出同一组证据,而我对它们的差异是盲的。

七、公开翻案的成本与收益

发现真相当天,我在原 issue 下发了更正评论:说明行为正确、给出日志证据、逐条拆解自己的两个观测错误、指出唯一真实的问题、道歉并请关闭。写这段评论花的时间比写原 issue 还长,这是应该的。公开误报的成本是一次尴尬,收益是维护者的时间和一个可信的轨迹记录:下次你再报问题时,你的历史记录在替你说话。

回头看,那组「铁证」有一个性质值得单独说:证据质量不保证结论正确,它保证的是纠错的速度。 最小复现、环境信息、内联证据,这些纪律没能阻止我犯错,但让我的错误可以被快速验证和推翻:verbose 日志一跑就水落石出。第 6 篇的「不可判定」标注和归因文件里原样保留的错误结论,是同一条纪律的不同形态:给将来的纠错留抓手。

误报调查还顺手孵出了真修复。读源码时发现我在 issue 里建议的修法和真实缺口对不上:上游早有优雅终止,缺的是「超时且产物缺失时合成一份最小结果文件」这个兜底,于是 PR 做的正是 issue 里我自己标的备选方案,PR 描述里专门开了一节说明与 issue 提纲的出入。issue 里的修复建议是假设,不是承诺。维护者看到的不是一个推翻自己的别扭 PR,而是一份诚实的调查记录。

八、绿灯也会骗人

两天后我又翻了一次车,方向相反。

我提的 PR 在 CI 上红了、本地全绿。第一反应是教科书式的「平台差异」:Linux 与 macOS 的进程管理差异。我把上游的超时处理、错误分类、kill 升级的时序读了一个小时,越读越觉得每一处都平台无关,但又找不到别的解释。

突破口不在读代码,在一条 git log:上游早几天合入了一个语义收窄的改动(框架自写文件改登记进内部字段),而 GitHub 的 pull_request 构建的是「分支 ⊕ 最新 main」的合并态。CI 测的代码和我本地测的,不是同一份。merge 文本上干干净净,一个冲突标记都没有;语义上,上游把我们断言依赖的行为拆走了。merge 干净只证明两边没改同一行,不证明两边对同一个字段的理解还一致。

所以「CI 红、本地绿」的第一个问题不该是「平台差在哪」,而是「CI 测的是哪份代码」。我为一个不存在的平台差异读了一个小时源码,那一小时里我离真相的距离,比不看代码还远。修法很轻:断言从「字段」改绑到「字段的职责」。上游重构会让字段贬值,职责才扛得住(Hyrum 定律的标准剧情:可观测行为足够多,就总有人依赖它)。

九、judge 也要被校准

裁判链条上还有一类裁判不是脚本,是模型。judge 的校准纪律,我的口径是三条:

  • TPR 与 TNR 分开看。 「抓得出坏的」和「放得对好的」是两个独立能力,一个高一个低的 judge 很常见。聚合成一个准确率,等于让两种病共用一张化验单。
  • Unknown 必须是合法判决。 不许强制二选一。判不了的样本标 Unknown 退出,硬判的 judge 会把噪声抛光成信号。
  • 校准集优先用有机失败。 合成坏样本是出给 judge 的送分题;真实运行里攒下来的失败,分布才和战场一致。校准集与验证集分开,校准集本身有保质期,这些和 RAG 检索评测是同一条纪律的两种说法。

这三条管的是怎么校;校多少条才算数,是第 13 篇算过的另一个问题:全对的三十条,撑得起的误判率上界仍有一成。

不校准的代价有公开数字:Opus 4.5 在 CORE-Bench 上起初只拿到 42%,后来查出评分器刚性判分(期望 96.124991… 而拒收 96.12 这类)、题面有歧义、随机题没法复现,修掉这些再换一个约束更少的脚手架,分数升到 95%。裁判的 bug 不只漏报,还会批量制造冤案,而它被采信的程度和正常裁判一模一样。

十、错误 → 机制化:全书方法论清单

本卷每一章的翻车,最后都长成了一条机制。收拢成一张总单:

翻车长出的机制
产物「消失」的误报(本篇)排除计数显式上报;单 case 重跑一律绝对路径;判产物看最新 iteration
判活器自身崩溃评测器自测套件 32 条断言(含故意的坏样本),上线首日就抓到自己崩溃
PASS/FAIL 摇摆flaky 单列:flaky rate 与 error rate 分开记录,不许互相掩护
孙进程孤儿化挂死 runner进程组杀 + 「孙进程必死」回归断言
mock 方言说错每种故障配「必然触发现有检测」的阳性对照变体
目录名泄露伤型宿主可见路径全部哈希暂存;实验产物对宿主不可见
超时用例从分母消失排除计数(同上,两个事故共用一条机制)

第 10–13 篇的病例不在表里:那几篇翻车的是公开 benchmark,不是我的工具链,它们长出的机制是各篇末尾那张读分数之前的检查清单。

这张表是全卷真正的产出物。工具会过时,数字会过期,「每次翻车长出一条机制」这个循环不会。

十一、全书答毕

回到评测卷序章那句问话:没报错,就代表输出没问题吗?

一路走来,每一卷都回答了它的一层。界面部分答了渲染层:把带状态的字节流逐层翻译成可断言的东西(第 16 篇的四层翻译)。本卷卷首答了协议层:complete 是排除出来的兜底,不是默认值;字节到没到,渲染层永远无权裁决。本卷其余各篇答了行为层:非确定性、成本约束、复合被测对象之下,断言目标三次搬家(路径、终态、关系),四问各有人认领。第 10–13 篇把尺子掉过头,去读别人量出来的数:被测的到底是谁,分数在哪里说谎,「会学」到底测到了没有,评测本身又由谁来验收。然后这一篇补上最后一环,观测层:连「发现问题」这件事本身,也会以自洽的方式出错,也需要被测。

所以最终答案是:没报错什么也不代表,除非你为「发现问题」这件事本身也建了断言。 观测会骗人、考题会骗人、对照组会骗人、绿灯会骗人,而裁判——包括拿着工具的那个人——始终在被校准的途中。这个系列抓了这么多 bug,最后一个永远是自己的。


  • 本章源码事实基于 Codex 本地源码 2026-10-14 的复核:codex-rs/tui/src/streaming/controller.rs 三个测试分别位于 L1143、L1619、L1852,快照 main 6b9826e3(2026-09-09);四层断言框架与三个测试的行为细节见界面部分第 16 篇,本章只取断言形态视角,不重复展开。蜕变测试的概念定性(property-based 测试技术、应对 test oracle problem)2026-10-14 经 Wikipedia 词条核验;具体出处(Chen、Cheung、Yiu 1998 年技术报告)为教科书通识,按转述口径引用,未逐字核对原文。
  • 本章收编自已发布博客《我给 skill-up 报了一个不存在的 bug》(2026-09-20)与《CI 红、本地绿:一次「平台差异」误诊,和 merge 干净不等于语义兼容》(2026-09-22);上游记录:skill-up issue #263、误报更正 #264、PR #265,语义变更上游 PR #250。
  • judge 校准三条纪律为作者的工作口径;CORE-Bench 的数字(42% → 95%)转述自 Anthropic 的 agent evals 专文,以原文为准。
  • 判活器自测套件与排除计数机制在 huohou 仓库 evals-shared(2026-09 起);进程组杀修复在 dsh-eval-harness v0.6.0。