INTRODUCTION · 从这里开始
为什么要读这本 Pi 蓝皮书
你可能已经用过 ChatGPT、Claude 或其他聊天产品：打开窗口，提出问题，等待回答。第一次打开 Pi 时，它看起来也像一个输入文字的终端窗口，但这不是理解它的最好方式。
Pi 官方把它定义为一个极简、可扩展的 Agent Harness。模型负责理解和生成，Harness 则把模型、工具、Session、上下文和你的工作目录连接起来。它可以读取文件、修改内容、运行命令，也可以通过 Skill 和 Extension 适应你的工作方式。因此，Pi 不是“又一个聊天窗口”，而是一个可以由你掌握和改造的 Agent 底座。
它和 Claude Code、Codex 在什么位置
Claude Code、Codex 和 Pi 都能把模型带进真实工作，但产品取舍不同。学习 Pi 不是为了证明它是一个“更强的程序员角色”，也不是为了把别的工具全部替换掉。
Pi 的特点是核心保持小，把更多工作流决定留给使用者。官方默认提供可工作的基础能力，但不会把子 Agent、计划模式、权限弹窗等全部固化成唯一答案。你可以继续使用默认方式，也可以在真正遇到需求后，用 Extension、Skill、模板或 Package 补上一块能力。
这种自由有两个方向：你更容易把工具变成自己的，也要更清楚自己装了什么、开放了什么权限、最终结果怎样验收。
中文初学者真正会卡在哪里
多数人并不是先卡在 Agent 的抽象概念，而是卡在几个很现实的问题上。
- 账号与模型访问。 安装 Pi 不等于已经获得模型。你仍需使用受支持的订阅登录或 API Key。
- 费用与额度。 订阅和 API 是不同的访问方式；API 调用可能按量计费，订阅也可能有额度限制。先确认自己能用什么，再开始长任务。
- Windows 路径与终端。 macOS 命令不能不加判断地复制到 PowerShell。本站为 Windows 单独提供 Git Bash 路径，并在后续课程给出对照。
- 插件带来的不确定性。 一开始装很多插件，会让你无法判断一项能力来自 Pi、模型还是第三方扩展，失败时也很难定位原因。
所以，本书不会先给你一张功能大全。第一阶段只要求你准备独立目录、完成登录，并让 Pi 做完一件可以由你亲自检查的小事。
本版坚持的五条主张
- 先做一件小事。 学会提交任务、查看产物和独立验收，比背完全部概念更重要。
- 一次只增加一个变量。 先用默认能力；遇到明确需求时，再试一个 Skill 或 Extension，并检查它是否真的生效。
- Agent 的总结不是验收。 文件能否打开、数据是否完整、测试是否通过，需要由外部证据确认。
- 文字限制不是沙箱。 “不要访问目录外”是任务范围说明，不会取消进程在操作系统中的权限。
- 动态事实必须带日期。 模型、登录方式、命令和生态都会变化；看到动态内容时，以页内核验日期和官方文档为准。
这本书适合怎样阅读
想先动手，进入从零开始操作，按平台完成安装、认证和第一次任务，再回来理解原理。想系统阅读，可以按导论、十条判断、凡例、序章和五个模块的顺序继续。作者故事和十条判断不是安装前置条件。
已经能稳定使用 Pi 的读者，可以从蓝皮书主线选择对应模块；遇到具体概念时再查参考手册；想了解判断如何形成，可以回看小墨同学札记。官方授权译文提供原作者的完整论述，但不代替课程中的中文操作路径。
下一页会把 98 条推文里反复出现、到本版定稿时仍然成立的判断集中列出。原始推文保留当时的探索和变化，蓝皮书只承担现在的结论。