附录
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 前后就随包发布,用命令行与会话内命令即可使用——不再是"核心刻意不内置、全靠扩展"。
返回 课程地图。