附录

附录 · 产品层功能与机制的对应

正文十二章讲的是"机制":循环、工具、消息、提示词、会话、事件、压缩、服务商、可靠性、协议。但 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 进程里,技能还可能指示模型执行程序。装之前读源码。
  • 主题与快捷键是配置,不是权限:它们只改变"看到什么、按什么键",不改变"能做什么"。
  • 遥测要脱敏:原始错误、路径、密钥都可能被顺手记下来;采样与过滤在宿主侧。
  • 非聊天模型也要计费:分类与图像调用同样产生成本,别因为它们不出现在选择器里就忘了归因。
  • 模板不是规则:固化约束走系统提示词,不要依赖模板"一直生效"。

返回 课程地图 或 源码映射。