附录 B — 终端界面详解
面向终端 UI 作为一个分层系统的参考资料:上报协议、pi-tui 组件模型、键位绑定、主题,以及逐终端的修复。从主线中移出,因为它描述的是界面,而不是智能体。
这是参考资料。第 31 章解释了为什么终端是智能体的一个界面、而不是它的一部分;如果你正在构建一个终端组件、调整一个键位绑定,或者调试一个不上报按键的终端,这个附录就是你需要的东西。如果你不是在干这些事中的一件,你可以跳过它,而不会在主线上失去任何东西。
Shift+Enter 是提交,而不是插入一行。你的自定义主题在别人的终端里没法读。一个点击处理器对你有效,对提交 bug 的那个人无效。这些中的每一个,在下面某一层里都有一个成因——知道这一点是有用的,但它不等于已经证明了这个症状不是一个缺陷。第 1 层或第 2 层上的一个症状极不可能是一个 Pi bug,因为 Pi 从没见过它从未收到的事件——但"被某一层解释"是一个关于那一层的论断,而只有针对锁定发布版做一次最小复现才能了结这个问题。下面的建议是找到那一层,而不是关掉工单。
这些层次
从底部往上:
- **终端模拟器。**解码转义序列、上报能力、转发按键事件。
- **上报协议。**扩展按键协议、Kitty 键盘协议、OSC 8 超链接、内联图片协议、truecolor。
- Pi 的终端组件系统——
@earendil-works/pi-tui。为一个宽度渲染一个由终端行组成的数组、处理输入、管理焦点。 - **Pi 的交互模式。**构建在那个系统之上的转录记录、编辑器、页脚和会话选择器。
- 你的配置——
keybindings.json、settings.json,以及主题文件。 - 你的扩展,它们通过
ctx.ui和自定义组件触达同一个系统。
每一层都有一种有文档记载的失败模式,而当某样东西坏掉时,有用的问题始终是"它是哪一层?"
flowchart TD
A["1 终端模拟器"] --> B["2 上报协议"]
B --> C["3 pi-tui 组件"]
C --> D["4 交互模式"]
D --> E["5 你的配置"]
E --> F["6 你的扩展"]
B -. "无法上报 Shift+Enter" .-> G["上面每一层都只能拿到普通 Enter"]
箭头意味着沿栈往上,而那条虚线边正是这一章的价值所在。当一个终端无法区分被修改过的 Enter 与普通的 Enter 时,第 2 层以上的任何东西都修不好它——第 3 到第 6 层都收到同一个按键,并在它的含义上与你意见相左。
第 3 层:一个组件究竟是什么
tui.md 在这件事上异常精确,而这种精确就是整个设计:
一个组件为一个可用宽度渲染一个由终端行组成的数组。它可以有选择地处理键盘与鼠标输入,并且当它的状态或与主题相关的内容改变时,它必须让缓存的输出失效。
有三个后果随之而来。
宽度以列来度量,不以字符来度量。 tui.md 要求每一条渲染出来的行都适配给定的宽度,并说要度量可见的终端列而不是字符串长度,因为 ANSI 转义、宽字符、emoji 和组合字符会改变显示宽度。这就是 visibleWidth()、truncateToWidth()、sliceByColumn() 和 wrapTextWithAnsi() 被导出、而不是留给你自己写的原因。
样式是按行的。 Pi 在每一行之后重置样式与超链接,所以样式必须在每一条渲染出来的行上重新应用。一个只设置一次样式、然后复用那个字符串的组件,会在一段长输出的中途丢失它的颜色。
失效是显式的。 改变状态之后,你让受影响的组件失效,并调用注入的 tui.requestRender()。TUI 会合并渲染请求。
这个包附带了你否则就要自己重写的那些组件:Text、Markdown、Image、TruncatedText;Container、VStack、HStack、Box、Spacer;Input 和 Editor;SelectList 和 SettingsList;ScrollView;Loader 和 CancellableLoader;MouseRegion。tui.md 对这一点很直接——优先用这些,而不是重写选择、滚动、文本编辑或宽度处理——并加上一条值得内化的规则:“不要在扩展内部创建第二个终端渲染器。”
UI 梯子,以及它的横档在哪里到头
tui.md 给了一张显式的集成表,而它就是自定义 UI 那一章所构建的同一架梯子,现在附上了每一级存在的理由:
| 需求 | 用什么 |
|---|---|
| 选择、确认、输入、多行编辑器 | ctx.ui.select()、confirm()、input()、editor() |
| 非阻塞的反馈 | ctx.ui.notify() 或 setStatus() |
| 编辑器附近常驻的内容 | ctx.ui.setWidget() |
| 替换页眉、页脚或编辑器 | 对应的 ctx.ui 组件工厂 |
| 临时的交互式屏幕或浮层 | ctx.ui.custom() |
| 为工具或会话条目做自定义渲染 | 一个扩展渲染器 |
这些 ctx.ui API 中的每一个,都会在需要的地方接收 Pi 的活动主题与键位绑定。只有当"UI 需要自己的渲染、键盘或鼠标输入、焦点、布局或生命周期"时,才构建一个自定义组件。
焦点不是装饰
tui.md 记录了两条规则,它们只在非英文输入上咬人:
- 一个显示文本光标的组件应当实现
Focusable,并把CURSOR_MARKER紧挨在它的可视光标之前放置。TUI 用那个标记来为输入法编辑器定位硬件光标。 - 包裹
Input或Editor的容器必须把它们的focused状态传播给那个子组件,否则 IME 候选窗口会出现在错误的位置。
第二种失败有一个针对 WSL 和 IntelliJ 终端的、有文档记载的逃生舱:PI_HARDWARE_CURSOR=1,或设置里的 showHardwareCursor: true。正确的修复仍然是传播 focused。
如果你替换主编辑器,就继承 Pi 的 CustomEditor——tui.md 说这保留了应用快捷键和智能体控制。把你的编辑器不拥有的按键转发给基类实现,并通过清空自定义编辑器工厂来恢复默认。
浮层拥有输入
ctx.ui.custom() 让一个组件控制交互区,并在该组件调用所提供的完成回调时 resolve。带上 overlay: true 时它画在已有内容之上,而那个句柄可以用 setHidden() 改变焦点,或隐藏和显示这个浮层。
有两条规则防止那个常见 bug。获得焦点的浮层在普通渲染之间保持输入所有权,所以如果另一个组件应当收到输入,你必须显式释放或重定向焦点。并且每一个自定义组件实例属于一次交互——再次开始那次交互时创建一个新实例。
第 5 层:键位绑定是具名动作
keybindings.md 描述了一种值得内化的间接层:Pi 暴露诸如 app.session.new 这样的具名动作,而键位绑定映射到那些名字。
{
"app.session.new": "ctrl+shift+n",
"app.session.tree": ["ctrl+shift+t", "alt+shift+t"],
"tui.altScreen.pageUp": []
}
一个配置过的值替换该动作的默认值。一个空列表完全禁用该动作的键位绑定,这就是你如何从全屏转录记录那里拿走一个键、而不丢掉编辑器绑定的办法。
有三个细节是实用的、而非显而易见的。super 绑定需要一个单独上报该修饰键的终端,通常是通过 Kitty 键盘协议,所以它们可能不是在哪里都能用。专用的历史动作 tui.editor.historyPrevious 和 historyNext“无论光标位置如何都会浏览提示词历史,并优先于使用同一个键的应用动作。“而若干默认值是平台相关的——app.suspend 是 ctrl+z,在原生 Windows 上没有默认值,tui.editor.undo 是 ctrl+-,在 Windows 上是 ctrl+z、在 WSL 上是 alt+z,而 app.message.followUp 是 alt+enter,在 Windows 和 WSL 上是 ctrl+q。
编辑 keybindings.json 之后,运行 /reload。/hotkeys 显示实际活跃的东西——而当文档与你的终端意见相左时,它才是权威。
主题是角色,不是组件
themes.md 对"主题"这个词很谨慎。Pi 自带 system、dark 和 light。system 是默认值,而它根本不带一个调色板:Pi 查询终端默认的前景与背景,加上它的 16 个 ANSI 颜色,从某一个 ANSI 颜色取每个 Pi 颜色的色相,并设置明度,好让它跨过一条最低对比度——正文文本在背景和每一个面板上至少保持 4.5:1 的 WCAG 对比度。当终端在浅色与深色之间切换时,Pi 再次查询并重建。
这就是 system 是一个保留名、而一个同名的自定义主题会被忽略的原因。它不是一个调色板;它是一个推导。
有一条有文档记载的降级阶梯。如果终端上报背景与 ANSI 颜色,Pi 用它的调色板。如果它只上报背景,Pi 用它自己的色相,按实际背景来摆放。如果它什么都不上报,Pi 回退到 ANSI 颜色索引和终端默认值,次要文本是暗淡的,而面板没有背景色。Pi 在显示启动页眉之前,最多等待终端的回答 100 ms,而如果颜色更晚到达,它就应用它们。
一个自定义主题是 <agent-dir>/themes/my-theme.json 里的一个 JSON 文件,带一个不是 system、且不含 / 的唯一 name。颜色接受六种形式——RGB 十六进制、OKLCH、OKHSL、一个 256 色索引、一个 vars 引用,或表示终端默认值的 ""。Pi 解析链式变量引用,并让缺失变量或循环引用无效。
热重载只应用于 <agent-dir>/themes/<name>.json;从任何其他来源添加主题后,运行 /reload。项目主题住在 .pi/themes/,并且只在授予项目信任之后才加载。
第 2 层:你的终端必须上报什么
terminal-setup.md 以解释了人们所报告的大部分古怪行为的那句话开篇:“Pi 使用扩展按键协议,好让终端能把诸如 Shift+Enter 和 Alt+Enter 这样的组合与普通的 Enter 区分开。“终端代理、多路复用器和内置的 IDE 终端能改变或丢弃那条信息。
有文档记载的修复是逐终端且具体的。Kitty 什么也不需要。iTerm2 需要把"Trackpad scrolls fast?“设为 No,因为在全屏模式下 Pi 拥有视口,于是 iTerm2 发送鼠标滚轮报告,而不是滚动原生历史。Ghostty 在 Alt+Backspace 失效时需要 keybind = alt+backspace=text:\x1b\x7f,并且在 Pi 捕获鼠标期间需要按住 Shift+Command 才能看到链接悬停预览。WezTerm 和 Alacritty 需要显式转发 Option+Enter / Alt+Enter,因为两者在 macOS 上都把它绑定为全屏:
config.enable_kitty_keyboard = true
config.keys = {
{ key = 'Enter', mods = 'ALT', action = wezterm.action.SendString('\x1b[13;3u') },
}
Windows Terminal 默认把 Alt+Enter 绑定为全屏,这正是为什么 Pi 为 app.message.followUp 记录在案的默认值在那里是 ctrl+q 而不是 alt+enter。
两个有文档记载的陷阱值得重复。Apple Terminal 的修饰键回退"只在 Pi 与 Terminal.app 运行在同一台 Mac 上时才有效。当 Pi 通过 SSH 运行在另一台机器上时,它无法检查本地的修饰键状态。“而 Ghostty 的 shift+enter=text:\n 映射会发送一个原始换行,Pi 无法把它与 Ctrl+J 区分开——移除它,因为 Pi 已经把 Ctrl+J 绑定为一个换行替代,而那个映射看起来有效,却仍然在破坏 Shift+Enter。
xfce4-terminal、Terminator 和 IntelliJ IDEA 的内置终端根本无法可靠地区分被修改过的 Enter 与普通的 Enter。文档的回答是用一个不同的终端或用 Ctrl+J,而不是去绕过它。
第 2b 层:覆盖检测
有三项能力被自动检测、且可以被覆盖,其中设置优先于环境变量:
| 能力 | 环境变量 | 设置 |
|---|---|---|
| 超链接 | PI_HYPERLINKS=1|0|auto |
terminal.hyperlinks |
| 内联图片 | PI_IMAGE_PROTOCOL=kitty|iterm2|none|auto |
terminal.images |
| Truecolor | PI_TRUE_COLOR=1|0|auto |
terminal.trueColor |
随表格而来的那条警告比表格更要紧:只强制启用完整终端路径都支持的能力,因为"不支持的转义序列可能破坏渲染。“通过一个会丢弃 truecolor 的代理强制启用它,产生的是垃圾,而不是一个回退。
这也就是一个主题在你的机器上看着对、在同事的机器上却不对的原因:HTML 导出把 OKHSL 值转换成十六进制,因为 CSS 不支持它们,而如果颜色与其源值不同,themes.md 告诉你要检查 truecolor 检测和对比度设置。
诚实地选一级
可复用的那个决定是:**从能力与需求相匹配的最低那一级开始。**对话框覆盖选择、确认、文本输入和多行编辑。通知与状态覆盖反馈。挂件覆盖编辑器附近常驻的内容。ctx.ui.custom() 用于一个真正需要自己的渲染、输入、焦点、布局或生命周期的屏幕或浮层——而它只在一个真实终端被接上时才存在。