附录
附录 · 产品层功能与机制的对应
正文十二章讲的是"机制":循环、工具、消息、提示词、会话、事件、压缩、服务商、可靠性、协议。但 Pi 还有一层东西——界面组件、快捷键、主题、提示词模板、扩展包、遥测、图像与分类模型。它们不进正文,不是因为不重要,而是因为去掉它们,机制依然成立。
这一页只回答一个问题:每个产品层功能挂在哪条机制上? 用法和字段请以官方文档为准,这里不复制。
一、为什么这些功能不进正文
判断标准很简单,一句话:去掉它,机制还成立吗?
| 类型 | 例子 | 去掉会怎样 | 放在哪 |
|---|---|---|---|
| 机制 | 循环、工具、消息、会话、压缩 | 就不再是 Agent 了 | 正文 01–11 |
| 机制的可替换实现 | 存储后端、模型路由 | 机制还在,选择变了 | 正文 12–13 |
| 机制的皮肤与外围 | 界面组件、快捷键、主题、模板、包、遥测、非聊天模型 | 机制照常运转,只是不好用或不好观测 | 本页 |
把这一层混进正文,会让"设计"和"用法"混在一起。单独成页的好处是:读正文时不必分心,回头查"这个功能到底改的是哪一层"时又有索引。
二、一张总表
| 功能 | 它依赖或复用哪条机制 | 对应章节 | 一句话 |
|---|---|---|---|
| 终端界面组件 | 事件流 + 渲染循环 | 06 | 界面只消费事件,不碰内部状态 |
| 快捷键 | 输入路由 | 06 | 命名动作到按键的映射,与机制无关 |
| 主题 | 渲染资源 + 终端能力查询 | — | 从终端取色,保证对比度 |
| 提示词模板 | 输入到用户消息之间的预处理 | 04、04b | 复用一段提示词,不引入新机制 |
| 扩展包 | 扩展加载 + 技能 + 模板 + 主题 | 04b、06 | 把四类资源打成一个分发单位 |
| 遥测 | 事件 + 用量 | 06、08 | 只观测,不参与决策 |
| 图像 / 分类模型 | 服务商抽象 | 08、12、13 | 不聊天,也是模型 |
三、界面层:组件、快捷键、主题
组件:屏幕是"一段宽度内的若干行"
Pi 的终端界面库把渲染抽象成一句话:给一个可用宽度,返回若干行文本。组件可以处理键盘、鼠标、焦点与生命周期,但渲染必须遵守三条纪律:
- 每一行都要落在给定宽度内;
- 宽度要按可见列算,而不是字符串长度——转义序列、宽字符、emoji、组合字符都会改变显示宽度;
- 样式与超链接在每行结束后会被重置,跨行要自己重新应用。
为什么强调这些?因为终端不是一个可以随便画的画布,而是一台有状态、有历史、可能通过慢速连接的设备。把"宽度"和"状态"这两件事处理好,界面才不会在别人的终端里出错。
它挂在哪条机制上:事件流(第 06 章)。界面订阅运行、轮次、消息、工具四组事件,把状态变化翻译成重绘。它不知道循环怎么运转,只知道自己收到了什么。
一个实践结论:不要在扩展里另造一个渲染器。终端的光标、滚动区、原始模式是全局资源,两个渲染器同时抢,轻则闪烁,重则把终端留在异常状态。
快捷键:把"动作"和"按键"解耦
Pi 暴露的是一批命名动作(比如"新建会话""打开会话树"),快捷键配置只是把动作映射到按键。这么设计的好处是:改键不影响行为,加行为不用改键位表。
它挂在哪条机制上:输入路由。它不进入循环,也不影响模型——按错一个键不会改变 Agent 的行为,只改变你看到什么。
主题:颜色是查询出来的,不是写死的
默认主题不是一套写死的色板,而是问终端:查询终端的前景/背景色与 16 个 ANSI 色,再按"与背景保持最低对比度"重新计算亮度。终端切换明暗时会重新查询并重建主题;终端不回答就退回 ANSI 色号,稍后拿到答案再应用。
它挂在哪条机制上:渲染资源 + 终端能力查询。这件事和 Agent 的智能无关,但它解释了一个常见困惑:为什么同一套主题在不同终端里长得不一样——因为它本来就在适配终端,而不是覆盖终端。
四、提示词模板:发生在"输入之后、消息之前"
模板是一个 Markdown 文件,文件名就是命令名,可以带参数与默认值:
---
description: Review staged git changes
argument-hint: "[focus]"
---
Review the staged changes. Focus on ${1:-correctness, security, and error handling}.
它挂在哪条机制上:输入到用户消息之间的预处理(第 04 章)。展开之后,它就是一条普通的用户消息,和手打的没有区别。
它和系统提示词的区别值得记牢:
| 系统提示词 | 提示词模板 | |
|---|---|---|
| 位置 | 每轮第一条消息 | 你这次输入的位置 |
| 生命周期 | 整个会话,按节更新 | 用一次,进一次历史 |
| 改的是 | 模型"是谁、能用什么" | 模型"这次要做什么" |
| 典型误用 | 想加规则却换了人设 | 想固化规则却写成了模板 |
最后一行是常见的误区:模板每次都会作为用户消息进上下文,它不是"永久规则"。要固化规则,应该走系统提示词(第 04b 章)。
模板的来源有四种:个人配置、项目配置、显式路径、扩展包。项目来源同样需要项目信任——理由和提示词文件一样,克隆来的仓库不该能悄悄改你的行为。
五、扩展包:把四类资源打成一个分发单位
一个包可以同时带扩展、技能、提示词模板、主题。它可以是普通目录,也可以是 npm 包或 git 仓库,还能声明自己的运行时依赖。
它挂在哪条机制上:扩展加载(第 06 章)+ 技能注入(第 04b 章)。包本身不是新机制,只是分发方式。
这里有个必须说清的信任问题:包会执行代码,技能会指示模型去跑程序。所以"装一个包"约等于"允许它在你机器上执行代码",项目里声明的包还要等你信任项目之后才加载。这和正文里反复强调的那条一致:扩展在 Pi 进程里运行,权限与 Pi 相同。
六、遥测:只观测,不参与决策
遥测包提供的是一套显式传递的契约(上下文、跨度、指标),不提供导出器,也不维护"当前跨度"这类全局状态。应用自己决定接到 OpenTelemetry、日志还是别处。
它挂在哪条机制上:事件(第 06 章)与用量(第 08 章)。它读的是"发生了什么、花了多少",而不是"该怎么走"。
这个设计取向值得学:可观测性不应该反过来影响被观测的系统。一旦埋点代码开始决定重试还是放弃,它就不再是遥测,而是业务逻辑了——那种代码最难排查,因为它在暗处做决定。
配套的现实约束是脱敏:遥测天然想记录尽可能多的上下文,而上下文里可能有密钥与用户数据。第 09 章讲过,Pi 自己在重试事件里保留原始错误文本;所以脱敏责任在宿主侧,不在框架侧。
七、图像与分类模型:不聊天,也是模型
服务商抽象里,"模型"不等于"聊天模型"。至少还有两类:
| 类型 | 输入 | 输出 | 用在哪 |
|---|---|---|---|
| 分类模型 | 一段 JSON 状态 + 若干选择题 / 是-否 / 打分 | 选项与概率 | 判定、过滤、路由 |
| 图像模型 | 提示词或参考图 | 图片块 | 生成配图、示意图 |
分类模型有个容易困惑的点:它不出现在模型选择器里。因为它不是用来对话的,模型也"看不到"它——它由脚本调用(第 12 章的脚本化调用)或代码调用。
它挂在哪条机制上:服务商抽象(第 08 章)。它和聊天模型共享同一套清单、认证与计费,区别只在输入输出的形状。
它和第 13 章的模型路由是天然搭档:路由需要"这次任务属于哪一类"的判断,而分类模型正好是那种判断的低成本实现。换句话说,非语言模型不是边角料,它是路由与过滤的判定器。
八、想继续查时去哪看
| 想知道什么 | 官方文档 | 本课程对应 |
|---|---|---|
| 界面组件与交互点 | docs/tui.md |
第 06 章 |
| 快捷键与键位表 | docs/keybindings.md |
本页 |
| 主题与终端取色 | docs/themes.md |
本页 |
| 模板语法与参数 | docs/prompt-templates.md |
第 04、04b 章 |
| 包的安装与资源声明 | docs/packages.md |
第 06 章 |
| 遥测契约 | packages/telemetry/README.md |
第 09 章 |
| 分类模型与图像模型 | docs/models.md、docs/codemode.md |
第 08、12、13 章 |
(路径相对 Pi 仓库,packages/ 开头的除外。)
边界与安全
- 装包即执行代码:第三方包会跑在 Pi 进程里,技能还可能指示模型执行程序。装之前读源码。
- 主题与快捷键是配置,不是权限:它们只改变"看到什么、按什么键",不改变"能做什么"。
- 遥测要脱敏:原始错误、路径、密钥都可能被顺手记下来;采样与过滤在宿主侧。
- 非聊天模型也要计费:分类与图像调用同样产生成本,别因为它们不出现在选择器里就忘了归因。
- 模板不是规则:固化约束走系统提示词,不要依赖模板"一直生效"。