← Pi Agents

附录 A — 参考资料与延伸阅读

本书背后的来源:Pi 自己的文档、已发表的关于智能体循环、界面、上下文与安全的研究、演示了特定设计的生态项目,以及把这些追问推进得更远的伴生书。

本书做三类论断,并把它们分开:Pi 的文档与导出的类型声明所说的内容(有文档记载)、被运行并记录下来的内容(已观察),以及本书所推荐的内容(本书提出)。一个想核实某条论断的读者,需要知道它出自哪一堆,所以这一页说明这些材料各自住在哪里。

下面没有任何一样是关于 Pi 如何行为的证据,除非它是 Pi 自己的文档或源码。外部工作出现在这里,是因为它照亮了同样的问题,而不是因为它定义了 Pi。

如何读这里的一条引用

下面这三类来源作为证据时表现不同,而把它们混为一谈,正是一本书的参考文献表变成它最弱一章的方式。这是正文所使用的同一个区分,现在应用到来源自身上。

    flowchart TD
  Q{"这条论断是关于什么的?"}
  Q -->|"Pi 的行为"| D["docs/*.md 与 dist/*.d.ts<br/>在锁定的发布版上"]
  Q -->|"一条关于智能体的<br/>一般性结论"| R["一篇论文<br/>读全文,而不是摘要"]
  Q -->|"某个人实现了的<br/>一个设计"| E["一个仓库<br/>证明它存在,不证明它更好"]
  D --> D2["直接断言,引用对应主题<br/>声明胜过散文"]
  R --> R2["把该发现归于那篇论文<br/>数字属于它们的实验"]
  E --> E2["标记为本书提出<br/>一个分叉的理由描述的是它遇到的 Pi"]
  D2 -.->|"统摄全部三条的规则"| L["在接受任何一条之前,先核对 1.0.4 这个锁定版本"]
  R2 -.-> L
  E2 -.-> L
  

要记住的是那条虚线。一篇这个月读的论文或一个这个月读的仓库,对 Pi 1.0.4 什么都说明不了,除非它讲的就是 Pi 1.0.4;而一个无法被锁定到某个发布版的外部对比,无论你对它多有信心,它都是一条本书提出的论断。

Pi 的一手来源

本书中每一样有文档记载的内容,都是对照锁定版本的已安装包来核实的,而不是凭记忆:

pi --version
~/.pi/agent/install/<VERSION>/node_modules/@earendil-works/pi-coding-agent/

在它内部,docs/ 在 1.0.4 上放着 40 个主题文件,examples/extensions/ 放着可运行的示例,而当散文与类型不一致时,dist/ 之下导出的声明才是权威。上游仓库是 earendil-works/pi,而当某条论断不再与你观察到的相符时,每个发布版的 CHANGELOG.md 是第一个该去看的地方。

智能体循环与工具使用

  • ReAct — Yao 等人,ReAct: Synergizing Reasoning and Acting in Language Models,ICLR 2023,arXiv:2210.03629。最初的"先推理、后行动"循环。它在这里有用,因为它是第 1 章中一轮(turn)结构的祖先,也因为它提醒我们:把观察与行动交错起来,正是整个想法所在。

  • Inside the Scaffold — Inside the Scaffold: A Source-Code Taxonomy of Coding Agent Architectures,Rombaut,arXiv:2604.03515。在锁定的提交哈希上考察了十三个开源编码智能体骨架,发现其中十一个组合了多种循环原语,而不是依赖单一的控制结构。它的上下文压缩分类法横跨七种互不相同的策略,而它的工具计数从零一直到三十七。本书承重的那一点:压缩不是一种机制,而"窄运行时"是设计空间中的一个点,而不是那个已经定案的答案。未经同行评审的预印本;把它的细节当作方向性的来看。

  • Towards a Science of Scaling Agent Systems — arXiv:2512.08296。在六个智能体基准和三个 LLM 家族上运行了 260 种配置,并把工具、提示词与算力标准化。相对单一智能体的变化,从可分解的财务推理上的 +80.8% 一直到顺序规划上的 −70.0%,而那个预测模型达到了交叉验证的 R² 为 0.373(配上一个以任务为锚的能力指标时为 0.413),并为 87% 的留出配置识别出最佳架构。

    *我们的读法,不是论文的读法:*这是我们找到的最强证据,说明增加编排是一场赌博,它应当紧跟任何"去够一个更精细骨架"的建议而放置。论文自己的结论更窄,也更正面——协调在通信拓扑与任务结构相匹配的地方才有回报,而不是因为更多智能体就是更好。预印本。

智能体—计算机界面

  • SWE-agent — Yang 等人,SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering,arXiv:2405.15793,NeurIPS 2024。它把交给智能体的界面当作一个设计变量:在模型权重不变的情况下,一个专门构建的智能体—计算机界面在 SWE-bench Lite 上比默认的 Linux shell 界面高出 10.7 个百分点。这就是第 17 章把一个工具如何被呈现当作一个决定、而不是事后补救的原因。

  • CodeAct — Wang 等人,Executable Code Actions Elicit Better LLM Agents,ICML 2024,arXiv:2402.01030。把许多工具调用合并进一个可执行代码的动作空间,在 M³ToolEval 上、跨 17 个模型报告了最高 20 个百分点的成功率绝对提升,同时动作数最多减少 30%。

    收录它是作为一个反例:本书关于"一个由 schema 驱动的工具面(API surface)值得拥有"的论断是一种权衡,而不是一个证明。有两点限定让这条引用保持诚实。该提升专属于多工具组合——在 API-Bank 的单个原子 API 调用上,CodeAct 只在 17 个模型中的 8 个上是最好的格式。而这个效应也不是一个微调的副产品:同样的基础模型在三种动作格式下都被运行过,所以该比较把格式隔离开来了。论文确实承认的那一点,方向相反——它在闭源模型上体面的 JSON 分数暗示那些模型是被朝着 JSON 微调过的,这让那个由 schema 驱动的基线占了便宜。

上下文与记忆

  • MemGPT — Packer 等人,MemGPT: Towards LLMs as Operating Systems,arXiv:2310.08560。它论证长期运行的系统需要一条显式策略,来决定什么留在活动上下文中。它支持第 4 章背后的普遍原则;关于 Pi 何时压缩,它什么也没说,而那是 Pi 自己有文档记载的 contextTokens > contextWindow − reserveTokens。
  • Lost in the Middle — Liu 等人,Lost in the Middle: How Language Models Use Long Contexts,TACL 12(2024),arXiv:2307.03172。它与第 4 章的警告相关:一个大窗口并不等于可用的注意力——准确度随位置下降,在一段长输入的开头与结尾最好,在中间最差。诚实的限度:它没有确立任何可用上下文的阈值,本书也不该。(arXiv 记录里的 Comments 字段至今仍写着"TACL 2023";正式出版的卷是 2024 年,而本书用的是这个。)
  • 伴生书 Context From First Principles 与 Memory From First Principles 一般性地展开了准入、作用域、存留、剪枝与检索。本书只需要 Pi 的具体术语。

评测与可靠性

  • τ-bench — Yao 等人,τ-bench: A Benchmark for Tool-Agent-User Interaction in Real-World Domains,ICLR 2025,arXiv:2406.12045。它引入 pass^k——一个任务的 k 次独立尝试全部成功的概率,按任务取平均。它是 pass@k 的镜像,后者只要求 k 次里至少一次成功。论文自己的数字说明了这一点:带函数调用的 gpt-4o 在 τ-retail 上达到大致 61% 的 pass^1,在 τ-airline 上约 35%,而它在 τ-retail 上的 pass^8 跌到 25% 以下——每四个任务里有三个以上,它没能在全部八次尝试中都成功。一个平均 61% 的配置,在八次尝试里仍然有将近八次是不可靠的。

    对本书读者而言的实际后果:一次演示是单次抽样,而不是一个能力论断,而第 10 章关于写出一个可完成任务的建议,部分就是这个。这个附录较早的草稿把这个指标弄乱了——它把 25% 这个数字挂到了单次运行的成功率上,并颠倒了"八次里有八次不可靠"的含义;上面的数字是论文的。

  • SWE-Bench Illusion — Liang、Garg 与 Zilouchian Moghaddam,arXiv:2506.12286。它探查的是模型的知识,而不是评测智能体:仅凭 issue 描述说出哪个文件有 bug,以及仅凭文件上下文复现那个标准答案函数。最先进的模型仅凭 issue 文本就达到最高 76% 的路径准确度,而在 SWE-bench 之外的仓库上最高为 53%;逐字复现函数在 SWE-bench Verified 与 Full 上达到最高 35% 的连续 5-gram 准确度,而别处最高为 18%。论文自己的结论刻意留了余地——提升"可能部分由记忆驱动,而不是真正的问题解决"——并且它主张抗污染的基准,而不是宣布那些排行榜无效。

  • Does SWE-bench-Verified Test Agent Ability or Model Memory? — Prathifkumar、Mathews 与 Nagappan,arXiv:2512.10218。这是一项独立的研究,有独立的对照组,而它是那个使用逻辑上不可能完成的任务的研究:它只在文件定位上测试两个 Claude 模型,并扣留仓库上下文,其程度是"到该任务应当在逻辑上无法解决的程度"。对照 BeetleBox 和 SWE-rebench 中可比的 Python 项目,这些模型在 SWE-bench-Verified 上得分大约高 3 倍,而在完全没有项目上下文的情况下说出被编辑过的文件上高 6 倍——它据此论证,这把排行榜偏向那些恰好使用这些模型的智能体,而不是偏向强的智能体设计。

    两篇论文,两个发现,刻意分开归属。较早的一版草稿把它们合并成了一条,于是把记忆框架借给了其中一个,把不可能任务框架借给了另一个。任何与本书一起被引用的排行榜数字,都应当带上这条告诫,而这条告诫属于一篇具名的论文。

安全、提示词注入与权限

  • AgentDojo — Debenedetti 等人,AgentDojo: A Dynamic Environment to Evaluate Prompt Injection Attacks and Defenses for LLM Agents,NeurIPS 2024 Datasets & Benchmarks Track,arXiv:2406.13352。一个在不可信数据之上操作的工具使用型智能体是一个独特的安全对象,而攻击面是通过工具输出到达的,不只是通过用户输入。它的结果还显示出基线在任何攻击之前有多弱:被测试的最佳模型 Claude 3.5 Sonnet 在完全没有攻击的情况下也只解决了 78.2% 的良性任务,而 GPT-4o 是 69.0%。一个未设防系统已经在大约四分之一的普通任务上失败的基准,这正是第 42 章拒绝把净化当作遏制的原因。
  • Pi 自己的 docs/security.md 是 Pi 立场的权威,而第 42 章直接引用它。生态系统中存在第三方的许可系统,它们是某个决策层的好的实现;它们不是 Pi 的语义,本书也不把它们当作 Pi 的语义来呈现。

智能体运行时与架构

对于第 1 章和第 11 章的分层论证,首要证据是 Pi 自己的包依赖图。这里有一个数字是核实过的,其余的不是,所以把它们分开。

**已核实。**在 1.0.4 上,pi-agent-core 只导入 @earendil-works/pi-ai、typebox 和相对模块。它声明的两个运行时依赖就是前两个,而出现在它 dist/ 里的每一个模块标识符都是它们之一或一个相对路径:零个界面导入。传递依赖图也一并封住了这个问题——pi-ai 依赖 provider SDK、遥测和 schema 库,而不依赖任何 UI 或 TUI 包。这个数字值得被精确陈述,因为它是可数的;而它被陈述为在 1.0.4 上,这样它就不会在一个正在看更晚发布版的读者脚下悄悄漂移。

**未锁定。**下面四个对比是本书提出的——是留了余地的解读,而不是一张测量出来的依赖图。它们中任何一个的发布版或提交,都没有在这个仓库的任何地方被锁定,这意味着读者无法复现它们,而一个发布版就能让它们移动。把每一个的方向当作论断,而不要把细节当作论断。

  • pydantic-ai — 它似乎通过拆分发行版来实现一个可嵌入的运行时,在一个精简包上带按 provider 的 extras。读这个发布版的打包方式暗示那条边界是被声明的,而不是约定俗成的,但没有在锁定的版本上读过任何 pyproject.toml,所以这一点没有被确立。
  • smolagents — 它有一个强制的、非可选的 rich 依赖,以及与智能体代码位于同一源代码树里的 UI 模块,这正是第 11 章称作边界消解的形状。在所检查的版本上方向性地得到支持;未锁定。
  • opencode — 注意这个名字有歧义:它既是那个编码智能体仓库 anomalyco/opencode,又是一个通过 OpenAI-responses API 触达的 Pi provider id。该仓库的 packages/ 布局是真正分层的,而它的 LLM 包是真正隔离的,这使它成为与 Pi 最接近的结构类比。“它的智能体循环不是一个库原语"这个论断没有被确立,而有一个数据点与它相反:发布的 npm 包声明了零个运行时依赖,并只发布一个预构建的可执行文件,这是打包,而不是进程分离。因此,本段所设置的那个对比——Pi 通过导入而不是通过进程达到同样的分离——尚未解决,而上面那个已核实的零导入数字不应倚赖它。
  • LangGraph — 它是一个可嵌入的运行时,而它的智能体行为要么住在用户代码里,要么住在一个已被移出它自己依赖图的预构建包里。它是四者中最不可锁定的:数百个已发布版本,而在本书写作后几天内就有一次发布。

Pi 生态项目

一个仓库的存在证明有人实现了一个设计;它不证明那个设计更好。收录这些,是因为每一个都清晰地演示了一个想法,而不是因为流行。

下面每一个项目都可访问,而没有一个为这一版锁定到某个提交。一个仓库的存在证明有人实现了一个设计;它不证明那个设计更好,而一个未锁定的 HEAD 能改变代码所做的事。

项目 它演示了什么
earendil-works/pi-review 一个完全构建在运行时之上的完整评审工作流:零个 provider 改动、零个内核改动、零个新工具。
earendil-works/gondolin 一条真正的隔离边界。它的 Pi 示例之所以能工作,是因为 Pi 把工具的操作与工具的定义分开导出,于是内置工具可以被重定向进一个微型 VM,而智能体进程留在外面。
nicobailon/pi-boomerang 上下文坍缩作为会话树的一等操作,而不是某个插件重新推导出来的东西。
nicobailon/pi-memory-workbench 一个带显式不变式集合、以 markdown 为事实来源、并带有诚实记录的局限性的记忆系统。
MasuRii/pi-permission-system 一个构建在 Pi 公开钩子上的许可决策层,带有一个明确拒绝自称沙箱的威胁模型。第三方语义,不是 Pi 的。
svkozak/pi-acp 一个运行时被另一个 UI 协议驱动,通过 --mode rpc,并带有有文档记载的缺口。
mitsuhiko/agent-stuff 留在循环之外的子智能体:它派生出真实的子 pi 进程,而不是重新实现那个循环。
code-yeongyu/senpi 那个边界测试。一个扩展优先的分叉,它逐条变更记录为什么一个扩展无法处理它——这是关于 Pi 的接缝在哪里的、目前最清晰的说明。把它当作本书提出的证据来读:一个分叉的理由描述的是它所针对编写的那一个 Pi,而 Pi 1.0.4 拥有提示词分区、压缩钩子和溢出恢复,这些可能早于一个分叉的历史。
can1357/oh-my-pi 那个制衡:当一个最小骨架吸收了原生 FFI、遥测和运行时内压缩时,一个发行版会做什么。
thevibeworks/awesome-pi-agent 一个生态系统的发现索引。作为一份列表有用;不是任何事情上的权威。

智能体框架对比

pydantic-ai、smolagents、langgraph、mastra 和 opencode,按第 1 章的那些轴来读:provider 边界在哪里、循环住在哪里、状态住在哪里,以及运行时是否能不依赖 UI 而独立嵌入。

五个中有两个似乎达到了一个干净可嵌入的运行时,而其中一个靠的是从来就没有过一个需要分离出去的 UI。状态的摆放似乎比循环的摆放更能区分它们:大多数把持久化放在循环内部或紧邻循环,而 Pi 的运行时根本不持有任何会话。本段是本书提出的,而且比它看上去更弱——五个中没有任何一个锁定了对比用的发布版,所以把方向当作论断,而不要把计数当作发现引述。这里唯一被测量过的,是 Pi 自己那一侧:pi-agent-core 1.0.4 上零个界面导入。

伴生书

如果你想 读
一般而言,为什么要有循环 Agents From First Principles
编排、子智能体、多智能体模式 Advanced Agents From First Principles、Agent Architectures
什么进入上下文,以及什么被准入 Context From First Principles
什么被持久化、被检索,或仅仅被存储 Memory From First Principles
诊断失败、状态与观察 Debugging AI
模型为什么这样行为 Models From First Principles、Hallucination From First Principles
被工程化的系统,而不是模型 Applied AI

Applied AI 值得单独指出:它主张把运行时与模型分开,好让模型可以被替换,这就是可替换性论证。本书所做的论证是关于层次所有权——哪个层次拥有一项决策——这是一个不同的问题,它并没有重述那一个。