附录
术语表
按主题分组的课程术语。每条给出课程内的定义,并链接到首次展开讨论的章节。带「元」字样的条目描述课程本身的约定,不是 Pi 的概念。
课程约定(元术语)
Pi 基线
课程资料所依据的 Pi 版本。所有「当前 Pi 行为」断言都锚定在这个固定版本上;基线升级必须同步更新源码映射、章节与契约测试。当前基线是 1.4.0。
当前 Pi 行为
由固定基线源码支持的行为描述;它与课堂中的简化示例分开表述。一个断言只有能在基线源码里指出对应文件或符号,才能写进「当前 Pi 行为」小节。
Python 教学模型
本仓库 learn_pi_lab 里只使用标准库的离线实验代码。它说明机制,不是 Pi 的生产实现或兼容 API。
主章节
课程地图中明确声明、并具有统一教学结构的 Markdown 章节。契约要求的五个小节见 检查脚本。
架构
harness(外壳)
模型之外的一切:工具、拦截、消息维护、会话、压缩、技能加载。智能来自模型,能力边界来自外壳,这是全书贯穿的核心判断。见 01 章。
模型 + 工具调用
核心循环的最小闭环,不是 Agent 系统的能力全集:模型只负责「决定下一步调用哪个工具」,其余由外壳供给。经典四件套里的「规划」由模型在循环内承担,「记忆」拆成消息、会话、压缩三件机制。见 01 章。
三层结构
模型无关的核心 → 产品层 → 界面。层与层靠类型化事件流解耦,不靠函数调用。见 01 章。
高级能力即工具
子代理、计划模式、外部工具服务器、脚本化调用,对模型来说都是「一个工具」:和读文件没有区别。核心只认识这一种扩展点。见 01 章。
Agent Loop
循环
驱动模型工作的机制:发请求 → 看回复 → 执行工具 → 填回结果 → 再发请求,直到该停下。见 02 章。
一次运行与一轮
一次运行包含多轮;一轮是「一次模型调用 + 这一批工具执行」。存档按运行,进度按轮。见 02 章。
停止原因
模型每次回复都会给出「我为什么停下」。常见四种:说完了、要用工具、出错/被中断、被长度截断。它不是唯一的终止信号——截断时循环还会做特殊处理。见 02 章。
插话与跟进
工作期间插入的用户指令(转向)与排队消息(跟进)。它们影响循环是否继续,而不必等本轮结束。见 02 章。
终止钩子
一轮结束时被调用的钩子,返回「结束」或「再跑一轮」。旧版本是「要不要停」的布尔值,新版本(finishTurn)改成了决定。见 02 章。
工具
说明书 + 执行器
工具的两次声明:说明书告诉模型怎么调(名字、说明、参数),执行器定义外壳怎么执行。模型永远不直接执行代码。见 03 章。
注册表分发
模型给出工具名与参数后,外壳在注册表里查到执行器再执行;未知工具返回错误而不是崩溃。见 03 章。
软约束与硬闸门
软约束写进提示词(模型可以违反);硬闸门在执行前强制检查(违反即拒绝)。安全设计的关键是把重要边界放进硬闸门。Pi 没有工具级审批层,它的硬闸门是扩展的调用拦截、操作系统隔离与项目信任。见 03 章。
命令类工具
能执行任意命令的工具,因此是最高风险面。Pi 给它的内置防护是输出截断与超时;隔离必须由外部提供,内置命令工具不会拦截危险命令。见 03 章。
上下文编辑(context_edit)
会话里的一种记录:不改原消息,只追加一条「以后这样看待它」的说明——可以省略,也可以替换内容。只影响模型看到的上下文,不影响磁盘上的历史。见 05 章。
脚本化调用
模型不再逐个调用工具,而是写一段运行在沙箱里的脚本,一次调完多个工具,只把脚本输出交回上下文。好处是往返少、上下文干净;代价是沙箱能力受限、失败不回滚。见 12 章。
外部工具服务器(MCP)
按统一协议把第三方服务器上的能力接进工具池。对模型来说与本地工具无异,只是名字带来源前缀;服务器内容属不可信输入。见 12 章。
工具命名空间
外部工具的名字形如 mcp__<服务器>__<工具>。前缀保留来源,脚本里调用时再把非法字符重写为下划线。见 12 章。
消息与提示词
角色
消息的来源标记:系统、用户、助手、工具结果四种基本角色;产品层再加命令记录、自定义消息、分支摘要、压缩摘要四种。见 04 章。
成对回填
工具调用与结果必须成对出现:模型发起一次调用,外壳必须填回一条结果,否则下一次请求不合法。Pi 在请求发出前还有一层「补一条合成结果」的兜底。见 04 章。
系统提示词
每轮请求的第一条消息。新版本起它是一组分名字的段落(开场、工具、规则、文档、追加、项目上下文、技能、工作目录),除开场外每段带标签,后续只发变化的那几段。见 04b 章。
三种改写强度
换人设(会丢工具说明与规则)、只追加、整段替换(扩展返回自己的系统消息)。见 04b 章。
人设的三级来源
代码层覆盖 > 项目文件/全局文件 > 内置默认。见 04b 章。
项目信任
决定「要不要加载这个目录里的配置与扩展」的开关(询问 / 总是 / 从不)。它不限制工具能访问什么,只决定加载什么。见 04b 章 与 03 章。
技能(skill)
放在技能目录里的可发现能力,其摘要会被注入提示词。注入前提是所选工具里有能读技能文件的工具;如果这些工具被隐藏但仍可间接调用,措辞会退化成不点名。见 04b 章。
上下文文件
从工作目录向上逐级发现的约定文件,注入为项目上下文段。不创建文件即为空,不需要显式关闭。见 04b 章。
会话与状态
JSONL 会话
会话的存储格式:一行一条 JSON 记录、只追加,当前版本 v3。只追加意味着崩溃恢复简单——最多丢最后一行,不会损坏已有历史。见 05 章。
只记父节点
会话树的构建规则:每条记录只记父编号,读取时由子找父重建整棵树。这让分支成为「从某个旧点继续写」的自然结果,而不是特殊操作。见 05 章。
只追加
只往后写、不改旧记录。会话、日志都遵循这一原则;修改历史的操作(压缩、上下文编辑)实际都是追加新记录。见 05 章。
投影
读取方按当前分支把压缩与上下文编辑应用到历史上,得到的「模型看到的上下文」。投影不等于磁盘内容。见 05 章 与 07 章。
血缘
分叉与复制出的新会话在文件头记下「我从哪个会话来」,让来源可追溯。见 05 章。
事件与扩展
事件即契约
核心与界面之间不靠函数调用,而靠类型化事件流。事件名和携带的信息是公开契约,界面怎么变核心都不用改。见 06 章。
两种监听
只观察的订阅(返回值被忽略,没有决策权)与扩展钩子(返回值参与决策)。分水岭是「你的返回值算不算数」。见 06 章。
边界时刻
0.87 之后新增的两个可行动时机:一轮结束、运行结算前。扩展可以在这里追加记录、决定是否续跑。见 06 章。
会话关闭
扩展收到的关闭事件,带原因(退出、重载、新建、恢复、分叉)。注意它不是「会话结束」,也不存在「设置变更」事件。见 06 章。
上下文管理
压缩
对话超过预算时,让模型总结自己的历史,用摘要替换旧消息在投影里的位置。压缩后调用与结果必须仍然成对,否则下一次请求不合法。见 07 章。
窗口即预算
上下文窗口是硬资源。外壳的职责是估算占用、在逼近上限前触发压缩,而不是等接口报错。见 07 章。
切割点
压缩从哪里开始保留历史。铁律是「不拆开一次调用与它的结果」;可以切在一轮中间,但不可以切在工具结果上。见 07 章。
压缩前钩子
扩展介入压缩的时机(session_before_compact)。可以取消,也可以自己提供摘要,常用来在压缩前脱敏。见 07 章。
服务商与可靠性
三件事分开
模型清单(有哪些模型)、请求协议(怎么调)、认证(凭什么授权)三者独立。换模型不该改业务代码。见 08 章。
模型配置文件
models.json,一个文件而不是目录;里面以服务标识为键,是映射而不是列表。见 08 章。
认证四层
命令行临时 key → 登录凭据 → 配置文件里的 key → 环境变量/云环境身份,前面的优先。见 08 章。
虚拟模型
注册一个名字,每次请求时现场决定用哪个真实模型与思考强度,常用于按任务路由、主备切换、灰度。路由状态随分支保存,计费按真实模型。见 13 章。
存储后端
会话落盘位置的实现:内存、追加式文件、数据库、只读视图。接口一样(追加 / 读取),但换后端会换掉一致性语义。见 13 章。
先分类再重试
错误处理的顺序:先判断可不可重试,再决定策略。Pi 的「每次调用」这一层按错误文本匹配两张表,先查不可重试。见 09 章。
两层重试
外层(每次模型调用,默认开三次)与内层(单条请求,默认关,开启后会读服务端给的等待时间并加抖动)。见 09 章。
指数退避
重试间隔指数增长,并且必须有单次上限,否则一次长时间故障会把调用挂死。见 09 章。
错误隔离
一个工具或一次调用失败不该拖垮整个 Agent:错误要被捕获、分类、变成一条结果,让模型决定下一步。见 09 章。
集成
标准输出是协议
结构化与协议形态把事件写到标准输出。消费方与 Agent 的全部交互就是这个流,所以诊断必须写错误输出。见 10 章。
粘包与半包
按行读取的两个经典问题:一次读到多行(粘包)、一次只读到半行(半包)。正确做法是按行缓冲,并且只认换行符。见 10 章。
双向协议(RPC)
标准输入上发命令、标准输出上收应答与事件,让外部进程驱动 Agent。命令编号可选;结束看「结算完成」。见 10 章。
参考实现
Tau
Pi 的 Python 对照实现(tau_agent / tau_ai / tau_coding),镜像同一套设计。它是「同一架构的另一种语言」的样本,不是 Pi 的 SDK。见 01 章。
mini_agent.py
课程的单文件缩影:消息与工具、模型接入、事件类型、循环、外壳五段。文件内小节标题标注了对应 Pi/Tau 的源文件。见 01 章。
返回 课程地图。