附录

Pi 源码映射

这一页回答两个问题:课程里的"当前 Pi 行为"以哪个版本为准,以及每个说法该去哪个文件核对。

使用约定

  • 课程里的「当前 Pi 行为」小节只陈述固定版本能支持的事实;写不出来的,就不写。
  • 「Python 实验」小节用的是课程自己的接口,并明确标注它不是 Pi 的生产 API。
  • 升级基线时,四件东西要一起改:源码映射、章节正文、对照代码、契约测试。
  • Python 侧的成品参考实现是 Tau(tau_agent / tau_ai / tau_coding)。它镜像同一套设计,但不是 Pi 的 SDK。

按主题找入口

下列路径相对 Pi 仓库根目录。它们是核对的起点,不是复制进本仓库的第二份文档。

想核对的机制 先读这些文件
安装、命令、上下文文件 packages/coding-agent/docs/quickstart.md、usage.md、configuration.md、settings.md
会话、记录格式、分支 docs/sessions.md、docs/session-format.md、src/core/session-manager.ts
扩展与压缩钩子 docs/extensions.md、docs/compaction.md、src/core/extensions/types.ts
技能、提示词模板、主题、扩展包 docs/skills.md、prompt-templates.md、themes.md、packages.md
模型、自定义服务商、路由 docs/models.md、models-configuration.md、providers.md、custom-provider.md、virtual-models.md、src/core/model-runtime.ts
无头形态、协议、事件流、SDK docs/cli.md、json.md、rpc.md、rpc-commands.md、rpc-extension-ui.md、sdk.md、cli-integration.md
工具创建与工作目录 src/core/tools/index.ts
安全与容器化 docs/security.md、containerization.md、environment-variables.md
系统提示词的分段拼装 src/core/system-prompt.ts
人设文件与覆盖链 src/core/resource-loader.ts
提示词模板 src/core/prompt-templates.ts
外部工具服务器(MCP) docs/mcp.md、packages/mcp/src/client.ts
脚本化工具调用 docs/codemode.md、packages/codemode/
持久化会话后端 packages/durable/

(上表路径都在 packages/coding-agent/ 下,packages/ 开头的除外。)

现在的包是怎么分的

核心四个:模型接入、Agent 核心、终端组件、编码助手产品。其中核心包现在很小——只剩 Agent、循环、代理流和类型;早期放在它里面的会话存储、压缩、技能、提示词模板、系统提示词助手,都已搬到别处。

围绕核心的产品与基础设施包:

  • 脚本化工具调用:模型写一段脚本,在沙箱里连着调多个工具。
  • 外部工具服务器客户端:pi mcp 命令与会话内斜杠命令的底座。
  • 持久化会话运行时:承接原核心里的会话存储能力。
  • 运行环境探测:与隔离相关的基础能力。
  • 组合基础设施、评测、遥测:官方标注 API 可能变化;产品包已经不再依赖其中的组合基础设施。

历史上还有一套从未发布的实验性远程会话栈(客户端 / 二进制协议 / 服务端),在 1.2 版本被整体删除。读到旧资料里"Pi 有二进制协议包"时,先确认版本。

最容易从外部带进来的误解

这一节不是本仓库的错误记录,而是读者最常从旧教程、旧 README 或生成内容里带进来的说法。每条都以固定版本为准;踩中任何一条,轻则代码不工作,重则对机制形成错误心智模型。

  • 服务商入口:老的 streamSimple() 已经挪到兼容子路径,不再是首选;现在是从扩展里注册服务商,再用 createProvider 与协议实现组合。自定义流函数拿到的上下文里,系统提示词与工具声明存在对话记录中,要用对应的读取函数取。
  • 会话关闭事件:叫"会话关闭",不叫"会话结束";也不存在"设置变更"事件。
  • 工具输入改写:在事件对象上原地改,没有"返回修改后的输入"这种协议;要拦下一次调用,返回"拦下"。
  • SDK 订阅:用会话的订阅方法,不是"on";创建编码工具时必须给工作目录。
  • 会话相关命令:树里导航、导出、分享、分叉、复制、整份复制,是六个不同操作,别混用。
  • 提示词目录:发现是非递归的;压缩的扩展边界是"压缩前"钩子。
  • 安装:需要 Node.js 22.19 以上;用 npm 全局安装并跳过安装脚本(有意为之);官方文档站是 pi.dev。
  • 技能注入:注册了不等于会注入——所选工具里必须有能读技能文件的工具;两者都被隐藏但仍可间接调用时,措辞会退化成不点名。
  • Windows 命令工具:从 0.84.3 起就有,可选的;提示词里的文件探索规则会按工具集改写措辞——"只有 bash"的旧结论已过时。
  • 项目级提示词文件:文件存在不等于生效,还需要项目被信任;全局目录下的同名文件不需要。
  • 没有工具级审批层:Pi 不会在每次工具调用前询问你。所谓"硬闸门"由三样东西提供:扩展的调用拦截、操作系统级隔离、项目信任只决定加载什么。不要写成"允许 / 询问 / 拒绝"三档裁决。
  • 系统提示词是分段的:不是一条扁平字符串。它由一组带名字的段落组成,每段包同名标签,存进对话记录,后续只发变化的那几段。
  • 终止钩子换了语义:旧的"这轮之后要不要停"(布尔)已删除,改成返回"结束 / 继续"的决定。
  • 会话记录多了一种"上下文编辑":不改原记录,只追加一条编辑说明;遍历记录类型的代码必须处理它。
  • MCP 与脚本化调用是内置的:从 1.0 前后就随包发布,用命令行与会话内命令即可使用——不再是"核心刻意不内置、全靠扩展"。

返回 课程地图。