4.2 仓库、版本与历史

本页分析版本earendil-works/pi@c13ffe12026-07-30

本章解决什么问题：Pi 的代码到底在哪个仓库、本书分析的是哪个版本、为什么必须锁定版本，以及仓库改名的历史。 前置知识：1.3 npm、package.json 与项目结构。 学习目标：能自己把与本书完全一致的源码 checkout 到本地。

仓库在哪里

Pi 的官方仓库（canonical repository）是：

github.com/earendil-works/pi

这是一个 monorepo（单仓库多包），包含 @earendil-works/pi-coding-agent（CLI 产品）、@earendil-works/pi-agent-core（Agent 运行时）、@earendil-works/pi-ai（统一模型接口）、@earendil-works/pi-tui（终端 UI 库）等 package——下一章会给出完整地图。

仓库改名的历史

如果你在网上搜索 Pi，会看到一个旧地址 badlogic/pi-mono。这是同一个仓库的历史名称：项目最初由 Mario Zechner（GitHub 用户名 badlogic）以 pi-mono 为名开发，后来迁移到 earendil-works 组织并更名为 pi。

这是我们实际验证过的行为（源码事实级别的验证——直接访问旧地址）：

$ curl -sI https://github.com/badlogic/pi-mono
HTTP/2 301
location: https://github.com/earendil-works/pi

旧地址返回 HTTP 301 永久重定向到新地址。因此：

• 社区文章、视频里的 badlogic/pi-mono 链接仍然能打开，只是会跳转；
• README 中作者依旧用 pi-mono 称呼自己的工作会话数据集（例如 Hugging Face 上的 badlogicgames/pi-mono 数据集）；
• 本书统一使用新名称 earendil-works/pi。

与 Pi 相关但不在本仓库里的还有：官网 pi.dev（文档与演示）、earendil-works/pi-chat（Slack/聊天自动化，README 官方说明中提及）。本书聚焦核心仓库，第三方与周边仓库只在必要处说明关系。

本书锁定的版本

源码是活的，书是静态的。如果本书写「agent-loop.ts 第 155 行是循环入口」，而你读的是三个月后的 main 分支，行号很可能已经对不上。所以本书把所有源码引用固定到同一个 commit：

项目	值
仓库	earendil-works/pi
分支	main
commit	c13ffe1877c3a47ce9f2fc98d9880447d64a0e87
commit 日期	2026-07-30
各 package 版本	0.83.0

这份信息记录在本书仓库根目录的 source-lock.json 里；书中每个源码引用块（SourceRef）生成的 GitHub 链接都指向这个固定 commit——这种链接在 GitHub 上叫 permalink（永久链接），内容永远不会变。

🌱 初学者提示commit 是什么

Git 仓库的每一次提交（commit）都有一个全局唯一的 40 位十六进制编号（commit hash）。给定 hash，你在任何时间、任何机器上 checkout 出来的代码都完全一致。这正是「可追溯源码分析」的基础。日常提到 commit 时通常只写前 7~12 位，例如 c13ffe18。

把同一份源码放到你的机器上

跟随本书阅读源码，强烈建议在本地 checkout 同一版本：

git clone https://github.com/earendil-works/pi.git

cd pi && git checkout c13ffe1877c3a47ce9f2fc98d9880447d64a0e87

checkout 固定 commit 后 git 会提示「detached HEAD」（分离头指针）状态——对于只读源码来说这完全正常，不用处理。

验证一下：

git log -1 --format="%H %ci %s"

预期输出：

c13ffe1877c3a47ce9f2fc98d9880447d64a0e87 2026-07-30 12:59:48 +0200 feat(tui): add alternate-screen renderer

🛠 实践任务checkout 本书版本的 Pi 源码

目标：本地获得与本书完全一致的 Pi 源码。

步骤：执行上面的 clone 与 checkout 命令，然后运行验证命令。

如何判断成功：git log -1 输出的 hash 与日期和上表完全一致。

常见错误：① clone 后忘记 cd pi 就执行 checkout；② 把 commit hash 抄错（建议直接复制）；③ 网络原因 clone 失败——可重试或配置代理。

版本更新策略

如果未来本书升级到新版 Pi：会更新 source-lock.json、重新运行全书源码引用校验（npm run verify:sources）并逐章核对，而不是让旧文字悄悄指向新代码。你看到的每一页引用与页面顶部的版本徽章始终一致。

本章小结

• Pi 的官方仓库是 earendil-works/pi；旧名 badlogic/pi-mono 已 301 重定向，属于同一仓库。
• 本书所有源码分析固定在 commit c13ffe18（2026-07-30，package 版本 0.83.0）。
• 你可以用 git checkout <hash> 在本地精确复现本书所读的每一行代码。
• 关键术语：canonical repository、commit hash、permalink、detached HEAD。
• 自测问题：① 为什么书里的源码链接不指向 main 分支？② 如何验证你本地的源码与本书一致？
• 下一章：4.3 monorepo 与 package 地图——看看这个仓库里到底有什么。