CASE 08 · 毕业项目
Pi 蓝皮书毕业项目
结果
你会把一个真实 GitHub 项目交给 Pi：先读需求和仓库，再用命名 Session 制定方案；人工批准后修改文件、运行测试、保存检查点；最后让另一个只读 Session 使用 Review Skill 独立复核，再由你完成最终验收。
项目不大，但链路完整。毕业标准不是“Pi 成功写了一篇文档”，而是你能解释每一步的边界，并用项目里的真实证据判断它是否完成。
这张图有三条硬规则：主 Session 不能批准自己的计划，审阅 Session 不能修改文件，最后是否通过由人判断。
这次要改什么
练习仓库使用 Pi 学习蓝皮书。任务是在参考手册中新增“任务完成检查表”，同时接入首页与侧栏。需求刻意限制为三个简体源文件、三个对应的繁体生成文件和一个本地检查点，足以练习真实项目流程，又不会把注意力带到复杂业务代码上。
可以先预览这三份材料；正式练习会从固定版本的克隆中复制它们：
安全边界
始终在新克隆的练习仓库中操作。全程不部署，不执行 git add、git commit 或 git push，也不读取凭据。命令里的工具白名单会减少可用工具，但不是操作系统沙箱。
第 0 阶段 · 准备隔离副本
在普通终端执行。下面的激活命令用于 macOS / Linux；Windows Git Bash 将 source .venv/bin/activate 换成 source .venv/Scripts/activate：
cd ~/Downloads
git clone https://github.com/xiaomoBoy/pi-bluebook.git pi-bluebook-graduation
cd pi-bluebook-graduation
git checkout --detach ea68e5f
npm ci
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements-dev.txt
npm run check:translations
git rev-parse HEAD
git status --short如果 pi-bluebook-graduation 已存在，换一个新目录名，不要覆盖旧目录。初始 git status --short 应该没有输出。本页固定使用 ea68e5f 作为练习基线，准备阶段的 checkout 只用于切换到已验证版本；进入 Pi 以后不再执行 Git 写操作。保存 git rev-parse HEAD 的完整提交号，材料与仓库不一致时先停止。Windows Git Bash 同样可以使用 ~/Downloads，这里新克隆的仓库不放在前面课程的 pi-practice 中。python3 --version 必须可用；若只提供 python，本页和 npm 同步脚本使用的 Python 命令需要先由你统一确认，不能带着缺失环境继续。
.venv/ 是仓库已忽略的本地 Python 环境。后续另开普通终端时，也要先进入练习仓库并执行对应的激活命令，再启动 Pi 或运行同步检查。
把三份材料放在仓库旁边，而不是放进仓库：
cd ..
mkdir -p pi-bluebook-graduation-materials/bluebook-graduation-review
cp pi-bluebook-graduation/docs/public/examples/graduation-project/requirements.md \
pi-bluebook-graduation-materials/requirements.md
cp pi-bluebook-graduation/docs/public/examples/graduation-project/checkpoint-template.md \
pi-bluebook-graduation-materials/checkpoint-template.md
cp pi-bluebook-graduation/docs/public/examples/graduation-project/bluebook-graduation-review/SKILL.md \
pi-bluebook-graduation-materials/bluebook-graduation-review/SKILL.md
cd pi-bluebook-graduation本案例以仓库简体原文为需求合同，繁体读者也使用同一份源材料，不要自行翻译需求规定的页面标题；同步脚本负责生成繁体页面。
打开三份材料检查内容。需求文件是验收合同，模板规定检查点字段，Skill 只规定审阅方法；任何一份都不应包含安装或部署指令。
第 1 阶段 · 建立主 Session，只做计划
启动一个有名字的 Session：
pi --name "CASE 08 毕业项目" --no-extensions --no-skills --no-context-files \
--tools read,write,edit,grep,find,ls,bash这里先关闭自动发现的 Skill 和 Extension，避免未知资源改变主任务行为。没有安装 Extension 不是漏做一课，而是根据需求判断“现有工具已经足够”。进入 Pi 后发送：
读取 ../pi-bluebook-graduation-materials/requirements.md 和
../pi-bluebook-graduation-materials/checkpoint-template.md。
检查当前仓库的 README、package.json、参考手册首页、VitePress 导航配置，
以及需求提到的三个课程页面。
这一轮只做两件事：
1. 把你确认的目标、允许路径、项目检查命令、风险和唯一下一步写入
worklog/graduation-checkpoint.md；
2. 向我汇报实施计划。
不要修改网站文件，不要运行构建，不要部署，不要安装依赖，
不要执行 git add、git commit、git push 或其他 Git 写操作。完成后停止，等我批准。第一次人工门
不要直接回复“继续”。先退出或另开一个普通终端，检查：
git status --short
sed -n '1,220p' worklog/graduation-checkpoint.md此时只应出现 worklog/。检查点应准确列出三个简体源文件、三个繁体生成文件、一个本地记录、项目自带检查命令和禁止动作；仓库结构不一致的地方必须写成未知。范围正确后，才批准实施。
第 2 阶段 · 在同一 Session 实施
继续刚才的 Session；如果已经退出，可在仓库目录执行 pi --resume 选择“CASE 08 毕业项目”。然后发送：
计划已批准。继续读取需求和 worklog/graduation-checkpoint.md，
只实施需求允许的三个简体源文件，再运行 npm run sync:zh-tw 生成对应繁体文件。
不要手工改写繁体正文。
完成后运行 npm run check:translations、npm run docs:check、git diff --check 和 git status --short，
把真实命令结果、实际变更、失败或未知写回检查点。
如果检查失败，只做需求范围内的最小修正；如果需要扩大范围，停止并说明原因。
不要部署，不要安装依赖，不要执行 git add、git commit、git push 或其他 Git 写操作。这一步会让 Context 明显变长：需求、项目说明、被读取的文件、工具调用、命令结果和修改差异都会进入当前任务链。Session 保存完整事件，模型当前实际收到的是由活动分支重建的 Context；两者不是同一个概念。
Context 快满时怎么办
不要为了展示概念而强行压缩。只有底部提示接近模型上限，或 Pi 自动触发 Compaction 时，才这样处理：
- 先让 Pi 更新
worklog/graduation-checkpoint.md； - 需要时执行
/compact； - 压缩后要求 Pi 重新读取需求和检查点，再说明唯一下一步；
- 人工核对摘要有没有丢失允许路径、禁止动作和失败记录。
Compaction 会把较早内容整理成摘要并保留较新的消息，不会替代磁盘上的检查点。缓存命中只影响复用输入与成本，也不能当作任务完成证据。
第 3 阶段 · 启动独立只读审阅
主 Session 的“全部完成”只能当线索。另开一个普通终端，在同一个练习仓库启动第二个 Session：
pi --name "CASE 08 独立审阅" --no-extensions --no-skills --no-context-files \
--skill ../pi-bluebook-graduation-materials/bluebook-graduation-review/SKILL.md \
--tools read,grep,find,ls--no-skills 关闭自动发现，显式 --skill 仍会加载指定 Skill。审阅 Session 不开放 write、edit 或 bash，只通过内置读取和搜索工具交付发现。它不能自行运行 Git 或构建；相关检查由人在普通终端执行。这限制了工具能力，但仍不等于操作系统沙箱。发送：
使用 bluebook-graduation-review 审阅当前工作树。
需求文件是 ../pi-bluebook-graduation-materials/requirements.md。
读取需求中允许的文件，检查正文、导航和对应繁体页是否一致。
不要写文件、运行命令或安装依赖。Git 差异和构建结果由我提供；
未提供或无法独立核对的过程证据必须标为“证据不足”。
逐项给出通过、失败或证据不足，并附路径与行号。在另一个普通终端运行 git status --short、git diff --check、git diff、npm run check:translations 和 npm run docs:check，把结果交给审阅 Session。新文件不会显示在普通 git diff 中，要逐一打开新建的简繁页面核对。
一份可信审阅不应该只说“通过”。例如，它可以确认当前差异只包含允许路径，却无法仅凭最终工作树证明过去从未执行过某个禁止命令；后一项应该诚实标为“证据不足”。
第 4 阶段 · 处理发现并更新检查点
把审阅结果交回主 Session。没有发现就不要为了制造工作量而修改；有失败项时，只修正会阻塞需求的问题：
这是独立审阅结果：
（粘贴审阅结果）
重新读取需求和检查点。只处理失败项；“证据不足”不得改写成“已证明”。
修正后重新运行受影响的检查并更新检查点。若没有阻塞项，不修改网站文件。这个来回就是最小的 Sub-agent 协作闭环：主 Session 对实现负责，审阅 Session 对发现负责，人对范围和最终判断负责。
第 5 阶段 · 人工毕业验收
最后不要问 Pi“真的完成了吗”。在普通终端亲自执行：
npm run check:translations
npm run docs:check
git diff --check
git status --short
git diff -- docs/reference/index.md docs/.vitepress/config/navigation.mts \
docs/zh-TW/reference/index.md docs/.vitepress/config/navigation.zh-tw.mts
sed -n '1,200p' docs/reference/task-completion-checklist.md
sed -n '1,200p' docs/zh-TW/reference/task-completion-checklist.md逐项打开并确认：
- 新页面有 frontmatter、一个一级标题和四个指定二级标题；
- 三个课程链接在项目中都有对应页面；
- 简繁两种语言的参考手册首页和侧栏都指向本语言的新页面；
- 繁体内容由同步脚本生成，
check:translations通过； - 检查结果来自这次真实运行，不是复制的文字；
worklog/仍是本地记录，没有进入提交；- 没有构建产物、依赖目录或缓存混入 Git 状态。
如果还要检查视觉结果，执行 npm run docs:dev，打开终端显示的本地地址，再进入“参考手册 → 任务完成检查表”。本案例禁止部署，所以线上状态应该写“未部署”，不能虚构线上通过。
维护者真实复现记录
早期单语言练习在 2026 年 9 月 11 日用 Pi 0.80.10 复现过。随后仓库增加了繁体同步要求，旧的“三文件”范围已经不适用；不能用旧检查页数证明新版通过。
2026 年 9 月 12 日，维护者通过自动化操作，在 macOS 全新克隆 ea68e5f 上用 Pi 0.84.3 重跑了新版流程：计划阶段仅写检查点，批准后生成简繁页面，独立审阅只开放 read,grep,find,ls。另行运行 check:translations、docs:check 和 git diff --check 均通过；练习产物为 123 个构建页面、1654 个有效锚点，两套搜索索引通过检查。实际差异仅为需求允许的七个路径。审阅保留了“最终工作树不能证明全部历史操作”的证据边界。
这次验证的是自动化维护复现，不是 Windows 实机记录，也不代替读者自己的人工验收。复现时请在检查点记录你的 Pi 版本、仓库提交号、日期，以及每条检查命令的真实结果。
历史练习输出，展示页面形态；当前验收以简繁两套页面和当次检查结果为准。
前 14 课在这里怎样汇合
| 已学内容 | 在毕业项目中的动作 |
|---|---|
| 第 1–4 课：安装、模型、工作目录 | 检查 Pi、进入全新克隆，并确认起始状态 |
| 第 5–7 课：任务、文件、Session | 读取需求与仓库，用命名 Session 分两轮完成 |
| 第 8–9 课：Context、Compaction、Cache | 观察上下文增长，先写检查点，必要时才压缩；不把缓存当完成证据 |
| 第 10–12 课：Skill、Extension、Sub-agent | 主任务判断无需 Extension；审阅时显式加载只读 Skill，并隔离第二个 Session |
| 第 13–14 课：长任务、安全与验收 | 保存检查点、限制路径和动作、独立运行检查、保留未知 |
毕业判定
同时满足下面五项才算完成：
- 范围通过： 只出现需求允许的路径；
- 过程通过： 先计划、人工批准、再实施，检查点能支持中断恢复；
- 结果通过： 项目检查与差异检查由你亲自运行并通过；
- 审阅通过： 独立 Session 只开放读取与搜索工具，人工检查与审阅发现被逐项处理；
- 解释通过： 你能说明 Session 与 Context、Skill 与 Extension、压缩与检查点、Agent 自述与真实证据的区别。
如果你只能展示最终页面，却说不清中间的边界，这次任务完成了，但课程还没有毕业。
失败恢复
- 计划阶段出现网站文件变化：立刻停止，记录差异；不要用覆盖整个仓库的方式恢复。
- 构建失败：保留完整错误、当前差异和检查点，只修最小问题。
- Context 丢失关键约束：让 Pi 重新读取需求与检查点，不凭记忆继续。
- 审阅发现范围外变化：先查明来源；无法区分已有变化与本次变化时写“证据不足”。
- 任务中断：重新克隆不是第一选择；先用 Session、检查点和真实 Git 状态恢复现场。