Pi 学习蓝皮书｜Pi Coding Agent 中文学习路线
一本面向中文初学者的非官方 Pi Coding Agent（极简终端 Coding Harness）学习手册。从安装、登录和第一个可验收任务开始，逐步掌握 Session、Context、Skill、Extension、Subagent 与长期 Agent 工作流。
在线阅读 · 直接开始操作 · 系统阅读 · 反馈问题 · 繁體中文版
这是什么
- 真实学习路线：不从功能清单开始，而是先完成一件可以亲自检查结果的小任务，再逐步进入会话、上下文、扩展和长期工作流。
- 面向中文初学者：同时提供 macOS 与 Windows Git Bash 路径，命令、Pi 内部操作和任务文字分开说明。
- 强调独立验收：每一课按“场景 → 概念 → 实操 → 验收”展开，不把 Agent 自述“完成了”当作完成。
- 持续核验更新：版本、认证、模型和命令等易变化信息会标注核验日期，并以 Pi 官方文档 和 官方源码 为准。
当前内容与学习路径
2026 开放学习版的读者对象、阅读顺序、基本主张和内容边界已经确定；网站仍会持续校订错字、失效命令、链接和核验日期。当前导论、序章、五个模块、14 课、1 篇原理串联和 8 个配套案例，已经形成从理解 Pi、完成第一次任务、管理会话与上下文，到扩展、分工、长任务和安全验收的完整学习路径。需要真实系统界面的进阶效果会明确标出，不用文字或伪图代替实测。
| 顺序 | 章节 | 你会完成什么 |
|---|---|---|
| 导论 | 为什么要读这本 Pi 蓝皮书 | 理解 Pi 的位置、中文初学者的真实门槛和本版主张 |
| 长期判断 | 从 98 条推文留下的十条判断 | 区分原始学习档案与截至本版仍然成立的判断 |
| 凡例 | 2026 开放学习版说明 | 明确平台路径、核验截止、维护规则和版权边界 |
| 序章 | Pi 作者 Mario Zechner | 沿完整时间线理解 libGDX、RoboVM、Pi 与 Earendil 之间的联系 |
| 模块一 · 1 | 安装前检查 | 打开终端，准备练习目录，检查 Node.js 和 npm |
| 模块一 · 2 | 安装并启动 Pi | 安装 Pi，确认可用，并学会启动与退出 |
| Windows 路径 | Windows 中文安装路径 | 用 Git Bash 准备环境、安装 Pi，并接入第 3 课 |
| 模块一 · 3 | 登录与模型设置 | 连接可用服务，选择模型，收到一次真实回复 |
| 模块一 · 4 | 从练习目录开始 | 确认当前目录和基础设置，完成进入任务前的检查 |
| 安装后维护 | 更新、退出登录与卸载 | 管理 Pi 版本、认证、Package 和本地数据 |
| 版本档案 | Pi 版本更新记录 | 按版本号、年份、变更类型和主题检索完整官方 Changelog |
| 模块二 · 5 | 第一次任务 | 把虚构会议记录整理成行动清单，独立核对输入与输出 |
| 模块二 · 6至7 | 文件与会话 | 用工作目录和 @文件 建立清晰起点，学会会话命名、续写和分支 |
| 模块三 · 8至9 | 上下文与压缩 | 理解长对话、压缩、提示缓存和可持续产物 |
| 模块四 · 10至12 | 扩展自己的 Pi | 区分 Skill、Extension 和 Package，理解 Extension 设计与子 Agent 分工 |
| 模块五 · 13至14 | 稳定工作流 | 处理长时间任务，建立权限、隔离、恢复和验收意识 |
| Agent Loop 原理 | 从一条 Prompt 到完整 Agent Loop | 把会话、上下文、工具、技能、模型调用与压缩串成完整流程 |
| 实操案例 | 案例库 | 用 7 个单项实验和 1 个毕业项目，依次练习文件任务、压缩、扩展、分工、恢复、安全与完整 Agent 工作流 |
| 参考手册 | 主题索引 | 按问题查找核心机制、操作入口、能力边界与延伸阅读 |
| 插件推荐 | 选择地图 | 从推文实践中整理当前可核验的插件来源、适用场景和风险边界 |
| 小墨同学札记 | 写在蓝皮书之外 | 单独保留个人感悟、踩坑记录与 98 条推文档案 |
| Earendil 官方授权译文 | 译文专区 | 经 Earendil 授权发布的十四篇 Pi、Harness、会话机制、MCP、代码质量与公司愿景文章完整中文译文 |
另有内容整理和小型代码修复两项迁移练习，帮助读者把验收方法用到不同任务。
已经能够启动 Pi 并获得回复的读者，可以先检查第 4 课的前置条件，再进入第一次任务。主线以 macOS 为基础，Windows 用户可通过独立中文路径完成安装，再使用 Git Bash 继续后续课程。
当前仍未验收的是 Windows 真实界面截图，以及 Extension 桌面通知的完整系统证据；取得对应实机后再补入，不用模拟图或终端文字代替。新的个人实践只有在来源和操作重新核验后才会进入本版。
本地运行网站
本仓库使用 VitePress。预览和修改网站不需要安装 Pi，也不需要模型账号或 API Key。
先准备 Git、Node.js 和 npm。仓库的 .nvmrc 指定 Node.js 22；这里是网站开发环境，与课程中 Pi 自身的运行要求分别说明。
git clone https://github.com/xiaomoBoy/pi-bluebook.git
cd pi-bluebook
npm ci
npm run docs:dev
打开终端显示的本地地址即可预览；修改 docs/ 下的文件后，页面会自动更新。停止预览时，在该终端按 Ctrl+C。
只维护网站或预览内容不需要 Python。需要同步繁体版本时，先运行 python3 -m pip install -r requirements-dev.txt，再运行 npm run sync:zh-tw；生成结果仍需人工校对台湾常用术语和页面排版。运行 npm run check:translations 可只读检查繁体生成内容是否与当前简体和词表一致，CI 也会执行这一检查。
检查正式构建并预览构建结果：
npm run docs:check
npm run docs:preview
docs:check 会依次检查内容资源引用和双语结构、完成正式构建，并核对 SEO、页面锚点与搜索产物。构建结果生成在 docs/.vitepress/dist/，无需提交到仓库。docs:preview 预览的是上一次构建结果，内容有变化时请重新检查。
目录结构
pi-bluebook/
├── docs/
│ ├── index.md # 网站首页
│ ├── zh-TW/ # 从简体正文生成的繁体版本
│ ├── guide/ # 按学习顺序编写的课程
│ ├── cases/ # 与课程模块对应的可复现实操
│ ├── reference/ # 按主题查询的参考手册
│ ├── plugins/ # 从推文实践整理的插件选择与核验清单
│ ├── releases/ # 可检索的 Pi 官方版本更新档案
│ ├── journey/ # 蓝皮书之外的个人札记
│ ├── translations/ # Earendil 官方授权中文译文
│ ├── tweets/ # 推文与实践资料索引
│ ├── public/
│ │ ├── examples/ # 可下载的练习材料
│ │ ├── examples-tw/ # 生成的繁体练习材料
│ │ └── images/ # 教程图片
│ └── .vitepress/
│ ├── config.mts # 站点、SEO、搜索和页脚配置
│ ├── config/ # 顶部导航与各板块侧栏
│ └── theme/styles/ # 按职责拆分的页面主题样式
├── scripts/ # 内容与正式产物检查
├── .github/workflows/ # 自动化质量检查
├── MAINTENANCE.md # 工程结构与维护入口
├── CONTRIBUTING.md # 反馈与贡献说明
├── EDITORIAL_WORKFLOW.md # 文章审阅、核验与发布流程
├── LICENSE # 网站代码许可
└── LICENSE-CONTENT.md # 原创内容许可
一起完善这本书
欢迎指出看不懂的步骤、失效命令、缺少的材料或错误链接，也欢迎补充有来源的实践记录和修正文案。你不需要会写代码才能贡献：在 Issues 写清所读章节、卡住的位置和实际现象即可。
提交修改前请阅读 贡献指南。文章从原始材料到发布的分工与验收方式见 文章工作流。
这本书由小墨同学整理；写作缘起与交流入口见关于作者。
许可证
本仓库的网站代码、原创书稿、推文整理稿和原创图片统一采用 MIT License。 你可以使用、修改和分发，也可以用于商业用途；分发本项目的全部或重要部分时，需要 保留原版权声明和许可证。具体说明见内容许可。
docs/translations/中十四篇 Earendil 官方授权译文及适配部分采用 CC BY 4.0，英文原文版权归 Earendil 所有。- 第三方商标、截图、引用和其他第三方素材不自动包含在原创内容许可中，其权利归各自权利人所有；素材旁的单独说明优先。
具体权利和条件以许可文件为准。
非官方声明
本项目为社区学习项目，与 Pi 官方无隶属或授权关系。Pi 的安装方式、认证支持和版本行为可能变化；课程中的动态说明应结合所标注的核验日期及 Pi 官方文档 阅读。