01 · 版本确认与学习路线¶
1.1 为什么先锁定版本¶
Agent 框架的名称很容易混淆，API 也会变化。一个「能读写文件的 while 循环」的介绍，无法覆盖 Pi 1.0 的消息补丁、并行工具、嵌套调用、项目信任和 MCP。
本次获取时间为服务器时区 Asia/Shanghai 的 2026-10-03。官方 GitHub：https://github.com/earendil-works/pi；官方入口：https://pi.dev。
| 对象 | 固定值 | 用途 |
|---|---|---|
| 官方 1.0 tag | v1.0.0 |
课程、实验和源码链接基线 |
| 1.0 commit | a13d35a742c6ef8462812a28fbe1d8c8b7431c32 |
防止后续行号漂移 |
| 复审刷新时 main commit | 9fba660cf1caca0ade5bea72269352416e595a19 |
满足下载最新代码；含发布后修改 |
| npm 查询结果 | @earendil-works/[email protected] |
实验依赖版本 |
| 最低 Node.js | 22.19.0 |
官方 engines 要求 |
来源：1.0 发布说明、固定版本 README、Coding Agent changelog。
主分支和 release 分开保存，是因为「最新代码」不等于「最新稳定版本」。本课程不把 main 上的发布后修改描述为 1.0 已有行为。例如 MCP 同名项目配置在 main 上允许以设置型 entry 覆盖全局 enabled / exposure / toolExposure；1.0 要求完整 server entry，同名项目 entry 整体替换全局 entry。更多影响行为的差异见 复审与版本差异。升级时要重新核对。
1.2 1.0 有什么实际变化¶
1.0 发布说明直接列出的变化包括默认全屏 TUI、Code Mode 提示开销下降、Code Mode 调用图片模型、Radius 登录、Anthropic 远程机器复制授权码、MCP OAuth 加固，以及 quietStartup: "header"。
MCP、Code Mode、虚拟模型和分类模型在 0.99.0 已引入；不能说它们全部在 1.0 当天诞生。理解 1.0 需要阅读发布前的架构，但学习时不必先按历史版本顺序读 changelog。
重要的迁移差异：
- 维护包名为
@earendil-works/*。 pi-ai根入口是核心 API；provider 工厂从providers/*导入。- 旧全局模型函数在
pi-ai/compat；新应用优先创建Models实例。 Agent的streamFn是显式依赖。- SDK 的
tools是工具名称字符串列表，不是旧教程里任意工具对象数组。 - SDK 默认没有加载 CLI 的 MCP / Code Mode 内建扩展，需显式添加。
session.systemPrompt与 Core 的state.systemPrompt是只读有效值，不能随便赋值。
1.3 六阶段学习计划¶
| 阶段 | 内容 | 建议投入 | 自测 |
|---|---|---|---|
| A | 运行 Pi、选模型、读写测试项目 | 1–2 小时 | 能继续、分支、压缩一段会话 |
| B | 配置、Skills、Prompt、Extension 区别 | 2–3 小时 | 能写一个 /review 模板与 skill |
| C | 消息、Agent 状态、工具循环 | 3–5 小时 | 能手画一次两轮工具调用 |
| D | SDK、资源加载和 SessionManager | 3–5 小时 | 能解释重启后上下文来自哪里 |
| E | 自定义工具、MCP、Code Mode | 3–6 小时 | 能测试参数失败与嵌套调用 |
| F | 产品边界、评测、持久化、部署 | 按产品规模 | 能说明权限和故障恢复策略 |
时长是学习建议，不是对你的水平或实际工时的保证。最重要的检查方式是：关掉教程，自己写出「输入、状态、工具、停止条件」这四个要素。
1.4 如何跟随源码¶
git -C upstream rev-parse HEAD
git -C pi-1.0 describe --tags --exact-match
git -C upstream diff --stat v1.0.0 HEAD
每次升级都重新执行：锁版本 → 类型检查 → 离线契约测试 → 真实端到端任务 → 审核权限与状态迁移。不要只因为 npm 安装成功就认为扩展兼容。