这两个月以来我都在深度的学习和使用Pi。
一开始只是因为单纯的好奇，为什么会有人使用一个这么简洁的Agent？直接使用Codex、Claude Code不好吗？抱着这个疑问，我就开始了我的Pi Agent学习之旅。
开头我只是把我的Pi学习过程和学习感悟分享到网上，慢慢的越来越多人关注我的学习过程。到后来就有人对我说：“能不能把你整个学习过程分享出来？”
就是这句话让我有了一个想法。我要把我的学习过程，整理成一本属于我自己的Pi 蓝皮书，而且我还要把它开源，把零散的使用心得整理成一条可以跟着学习的路线。
现在它终于可以亮相了，这本蓝皮书已经有了一条完整的初学者主线。里面包含 14 课、7 个实操案例、98 条原始学习记录、10 条长期判断，以及 10 篇经 Earendil 授权发布的中文译文。在线网址和开源地址我都已经公开了，而且使用的还是最低限度的MIT开源协议。
这篇文章会把整个过程拆开。从整理材料、选择 VitePress、调整 UI，到连接 GitHub、部署 Cloudflare Pages、绑定自己的域名，我都会给出可以照着走的步骤。中间几次推倒重来，以及我主动发邮件询问翻译授权的经历，也会完整保留下来。
如果你也有一批散落的笔记、推文和文章，可以把这篇当成一份从材料整理到网站上线的实操参考。即使没有前端开发经验，跟着做到最后，你也能做出一本可以公开访问、继续维护的开源蓝皮书。
先决定这本书要留下什么
我一开始以为，整理蓝皮书就是把过去两个月的内容搬到一个网站里。
先通过Grok帮我抓取了我最近两个月所有关于Pi学习的推文和文章，回复哪些就不需要记录了。
这部分一开始我只是保留做记录，把原文和内容直接整理进我的网站里面当做我的小记，只是当成一个学习过程的记录，但是后面发现其实我整本书最有意义的部分就是98条推文里面的内容和思想过程。
于是我就开始重新按照学习和思考顺序而不是发帖的时间顺序重新排布，还从98条推文里面总结出了10条判断。
从这里也让我明白，写好一本蓝皮书不是简单的去做数据收集，而是从数据里面挖掘出来你自己的东西，在通过一定的顺序整理成册，一定不要学我一样本末倒置，捡了西瓜丢了芝麻。
如果你也想整理一本自己的知识手册，建议你按照下面的流程走。
把原始材料完整收回来，不要急着去直接改写
记得给每条材料标注主题和来源
把明显依赖旧版本的内容单独放置
按读者的学习顺序重新编排
再从中提炼准备长期维护的判断
原始记录负责证明你的成长和思考过程，正式章节负责带读者一起走。把这两种内容分开以后，书本的结构就会清楚很多。
确定技术基调
内容方向确定以后，接下来就轮到了网站部署和技术选型了。
一开始我的目的就已经很明确了。它主体就是一套资料和文章分享页，不需要登入或者其他复杂的后台。保存的内容除了Markdown文档就是一些图片即可，所以越简洁越好，顶多增加一些自定义的主题，因为我想保留自己的风格。
一开始AI给了我三套方案。我思来想去最终选择了最成熟和剪辑的 VitePress。它的工作只是把Markdown 内容生成静态网页，默认主题已经具备导航、侧栏、目录和代码块，很适合文档与知识手册，而且整体的主题修改起来也方便。
对我来说，简单易维护比功能数量更重要。一个长期项目最怕每次写新内容前，还要去关心技术细节。VitePress带给我的就是这种低消耗式的创作，把主要内容放在 docs/ 目录就好了，文章和章节结构清晰明了，构建后生成的也只是静态文件。
这套项目最终用到的东西很少。
GitHub 账户，用来保存源码、记录版本和公开协作
Git、Node.js 和 npm，用来在电脑上运行项目
Cloudflare 账户，用来部署网站
一个独立域名，可以不买也能使用CloudFlare提供的免费
pages.dev地址
我当前开源项目锁定的是 Node.js 22 和 VitePress 1.6.4。如果你直接使用我的仓库，可以沿用这套环境。准备完全新建时，也可以按 VitePress 当前官方安装向导 选择版本。工具可能会更新，文章里的版本号也可能随时变动这部分需要自己注意。
从一个公开的 GitHub 仓库开始
先登录 GitHub，点击右上角的新建仓库入口。仓库名可以直接使用 pi-bluebook，也可以换成自己的项目名。
如果你希望别人阅读和参与，仓库选择 Public。初始化时可以创建 README.md，许可证则要根据你准备开放的内容来决定。我的项目对网站代码和原创内容使用 MIT License，获得单独授权的译文放在独立目录，并按对应授权条件说明。
公开仓库意味着任何人都能看到里面的文件。API Key、.env、私人邮件地址、账户截图和未打码的个人信息，都不能提交进去。开源的是蓝皮书内容和实现方式，不是自己的账户资料。
仓库创建好以后，在电脑的终端中执行下面这些命令。把示例中的用户名和仓库名换成自己的。
git clone https://github.com/YOUR_GITHUB_NAME/YOUR_REPO_NAME.git
cd YOUR_REPO_NAME
npm init -y
npm add -D vitepress@1.6.4
npx vitepress init
初始化向导询问配置目录和 Markdown 目录时，都可以填写 ./docs。主题先选择默认主题，配置文件选择 TypeScript，并让向导自动添加 npm scripts。完成后运行下面的命令。
npm run docs:dev
终端会显示一个本地地址，通常是 http://localhost:5173。浏览器能打开首页，修改 docs/index.md 后页面也跟着变化，说明基础项目已经跑起来了。
接着做一次正式构建。
npm run docs:build
npm run docs:preview
我的项目构建结果位于 docs/.vitepress/dist/。这个目录后面要交给 Cloudflare Pages，也是部署时最容易填错的地方。正式构建没有报错，并且预览页可以正常打开，才适合进入下一步。
最后把本地内容推回 GitHub。
git add .
git commit -m "init: create my bluebook"
git push -u origin main
刷新 GitHub 仓库，确认刚才的文件和提交已经出现。终端显示成功只能证明推送动作结束，仓库网页上的最新提交才是更直观的验收结果。
UI 只调整了两轮，方向却完全变了
建站初期我没有想太多，直接是把 Pi 官网当成视觉参考。主要是默认的极客和像素风感觉和我的蓝皮书风格很贴切，其实我也有小小的私心，就是视觉熟悉感，可以让大家一眼就和Pi绑定上。
第一版很快做了出来。它在视觉上接近 Pi 官网，也有自己的首页和资料页，但是我越看越觉得有点问题，和我的出发点有点背道而驰了。页面更像在介绍一个产品，而不是蓝皮书要的那种章节和阅读路径。
于是我把 UI 重新大改了一遍。新的版本UI主要是围绕“蓝皮书”这个特点展开，首页先回答适合谁、从哪里开始、会学到什么；侧栏跟着课程顺序走；个人学习记录和正式教程也被分到了不同区域。
这次调整没有追求更多组件。而是加强了整体的连续性和引导，读者可以在十几秒内找到下一步。颜色、卡片和装饰都服务于章节，不能影响内容的输出。最终版的序章页看起来更像一本可以连续阅读的书，正文、目录和前后章节之间的关系也更清楚。
这两版 UI 大部分通过 AI帮我辅助完成。我负责指出哪里不像一本书、哪些信息应该先出现，以及最终如何验收。AI可以快速改页面结构和样式，但“这本书到底想让谁看懂”仍然需要作者自己回答。
从 GitHub Pages 转向 Cloudflare Pages
项目最初放在 GitHub 后，我第一反应是直接使用 GitHub Pages。我的仓库本来就是公开的，但当时我以为需要开通 Pro 才能长期稳定使用，所以没有继续走这条路线。
后来核对官方说明才发现，这个理解并不准确。GitHub Pages 官方文档 写得很清楚，GitHub Free 可以给公开仓库使用 Pages，Pro、Team 等方案还支持私有仓库。我的仓库是公开的，所以免费方案本来就能用。
我最后依然选择了 Cloudflare Pages。原因很实际。域名和 DNS 可以放在同一个账户里管理，GitHub 推送后能自动构建，免费额度对这种纯静态蓝皮书也很宽松。根据 Cloudflare Pages 当前限制，免费方案每月提供 500 次构建；静态资源请求 免费且不计量。这里的数字核验于 2026 年 9 月 10 日，后续仍应以官方页面为准。
在网页里连接 GitHub
登录 Cloudflare 后进入 Workers & Pages，新建 Pages 项目，然后选择连接 GitHub。第一次使用时，Cloudflare 会要求安装 GitHub App。授权范围尽量只选准备部署的仓库，不需要把整个 GitHub 账户全部开放。
选中仓库后，填写下面四项。
如果项目使用 Node.js 22，可以在构建环境中明确版本，也可以像我的仓库一样保留 .nvmrc。配置提交后，Cloudflare 会拉取仓库、安装依赖、执行构建，再把生成目录里的静态文件发布出去。Cloudflare 的 Git 集成说明 也列出了这套流程。
我是怎么让 Codex 帮我完成的
网页操作并不复杂，不过我当时直接使用了 Codex 里的 Cloudflare MCP。完成登录和授权后，我让 AI 创建项目、连接仓库、检查构建配置，并继续处理自定义域名。
这里有一个很重要的边界。AI 返回“创建成功”，只代表请求被接受。最后还要回到 Cloudflare 项目页验收，查看生产部署是否成功、关联的提交是否正确，再分别打开 pages.dev 地址和自定义域名。
这张截图里能同时看到生产部署、main 分支对应的提交，以及 pi-bluebook.pages.dev 和 pi.xiaomovps.com 两个地址。到这里，部署才算完成。以后每次把新内容推送到 main，Cloudflare 都会重新构建和发布。
域名可以晚一点买
Cloudflare Pages 会自动提供一个 项目名.pages.dev 地址。只想先把书做出来时，这个地址已经够用，域名完全可以等内容稳定后再买。
我最初也没准备购买域名。后来考虑到蓝皮书会持续更新，希望入口长期保持独立，才购买了自己的域名，把 DNS 托管到 Cloudflare，再用自定义域名接管 Pages 项目。
如果使用子域名，例如 pi.example.com，可以在 Pages 项目的自定义域名页面添加它。域名已经托管在同一个 Cloudflare 账户时，系统通常会帮助创建所需记录。根域名和第三方 DNS 的处理略有不同，操作时可以对照 Cloudflare 自定义域名文档。
绑定以后不要只看后台状态。分别打开 pages.dev 地址和自定义域名，再随机进入两三个章节。首页能开，不代表侧栏链接、图片和子页面全部正常。
一封主动发出的邮件，改变了译文专区
在整理前面的推文材料的时候，我分享过几篇 Earendil 的文章。在我看来，那几篇内容对初学者或者想学习和了解Pi的人来说，非常的有启发和意义，所以我想着要把它汉化成中文分享出来，但是在执行过程中遇到了个小意外。
在我让AI翻译的过程中被提醒了，公开发布翻译并不是简答的引用，而且我还设置了对应的开源协议。即使注明原文链接，完整翻译和改编通常都需要作者的许可。
我没有继续等，第一时间就给 Earendil 发了一封邮件，说明蓝皮书是一个怎样的项目、准备翻译哪些文章、还有我的初衷。
我很快就收到了回复。Earendil 的合伙人兼首席执行官 Colin 亲自确认了许可。一开始的回复里面允许我发布和维护三篇文章的中文版本，也允许加入必要的适配说明，前提是保留原文标题、作者、发布日期和链接，并写明“经 Earendil 许可改编和翻译”。适配部分按双方确认的 CC BY 4.0 条件发布。
但是官网其实还有其他邮箱的文章，我又经过交流和沟通把许可扩展到更多文章。这次Colin 再次明确回复，只要满足邮件中列出的署名条件，他们愿意授予相应许可。他还推荐了一篇更适合非技术读者的文章。
assets/从零开始，开源一本属于自己的 Pi 蓝皮书/file-20260910175557436.png
现在我的Pi 蓝皮书已经把所有的文章译文都整理了出来。每一篇都保留原始标题、作者、发布日期、原文链接和授权说明。英文原文版权继续归 Earendil 所有，第三方图片和商标也增加了对应的版权说明，不会简简单单的变成我的原创内容。
这封邮件让我很开心。公司究竟有多少人，我并不清楚，但自己的询问能被 CEO 亲自回复，确实是一种鼓励。有些事情就是这样，做了才知道结果。一直不发出那封邮件，我也不会知道对方愿不愿意授权。
蓝皮书也从这里进入了新的阶段。它开始拥有经过许可的完整译文，也必须承担更明确的署名、许可和维护责任。
把许可证和贡献方式写清楚
开源不只是把仓库改成 Public。别人能不能修改、转载和分发，要看项目里的许可证；发现错误以后从哪里反馈，则要靠 README、Issues 和贡献指南。
我在仓库里分别保留了这些文件。
README.md说明蓝皮书是什么、怎样本地运行、当前包含哪些内容CONTRIBUTING.md告诉读者怎样反馈问题和提交修改LICENSE说明网站代码和原创内容的使用条件LICENSE-CONTENT.md单独解释授权译文与第三方素材的边界
如果你的项目还没想清楚许可证，不要随手复制别人的文件。先分清自己写的正文、网站代码、第三方截图、文章译文各自属于谁，再决定怎样开放。邮件授权也要保存原始记录，公开截图前先检查邮箱、讨论链接和其他私人信息。
做完第一版 Pi 蓝皮书以后
刚准备整理这本蓝皮书时，我并不知道最后会有多少人来看。那时我只是觉得，分享本来就是一件有意义的事。把这两个月学过、试过和想过的东西整理出来，本身也是对自己学习过程的一次回顾。
这两个月，我从简单使用 Pi Agent，慢慢走到研究源码、理解作者的设计，再到自己动手写插件。很多内容当时只是随手发出来的一条推文，前后有重复，也保留了理解发生变化的过程。把它们重新放在一起以后，我才第一次完整看到自己是怎样一步一步学到现在的。
最初那一版，我只是按照发布时间收集原文。等 98 条推文全部摊开，我开始注意到里面反复出现的问题和判断。于是我重新按照学习顺序整理内容，又从中总结出了 10 条判断。学习记录会留下结果，也会留下当时为什么这样想，以及后来是哪份材料改变了自己的理解。
这次Pi 蓝皮书的开源结果可能不是最重要的，我感觉最主要的反倒是中间的过程，从一个简单的知识分享到一个完整的产品，一步一个坑，只有去做去思考我们才能变得更好，学习的更多。
