第 32 课：毕业项目评审

用架构审查、源码改造审查、agent benchmark、真实任务验收和产品化路线评审一个高级 coding agent 原型。

结论

毕业项目评审不是看 demo 是否顺利跑完一次，而是判断这个 agent 原型是否已经具备继续产品化的工程基础。

评审要覆盖五件事：架构是否有清晰边界，源码改造是否可维护，benchmark 是否能证明能力变化，真实任务是否能从 issue 到 PR-ready branch 闭环，产品化路线是否把可靠性、发布、配置、权限、插件生态和团队治理排进计划。一个高级 coding agent 的毕业标准不是“会改代码”，而是“能在失败、升级、多人协作和真实仓库约束下继续演进”。

入口问题

课程最终项目通常叫 ForgeCode。到第 32 课时，它可能已经具备：

CLI 和 headless SDK 两种入口。
repo context、skills、prompt templates、项目规则加载。
read-only、ask-before-edit、full-auto 权限模式。
worktree 隔离、subagent、task queue、trace replay。
自动运行 lint/test/typecheck，生成 diff、commit message、PR 描述和 review 报告。

但这些功能堆在一起不等于可交付。评审要问：

架构边界是否清楚，还是一个巨大的 task runner 文件？
改 Pi 源码时是否有最小改动面和回归测试？
benchmark 是否覆盖真实失败场景，而不只是 happy path？
真实任务验收是否有可复查证据？
下一步产品化要先补可靠性、体验、生态，还是企业治理？

心智模型

毕业评审可以用“五张表”完成。

第一张是架构表：模块、职责、输入输出、依赖、可替换点。它证明你不是靠脚本偶然串起来。

第二张是源码改造表：改了 Pi 哪些文件、为什么改、有没有 upstream 替代方案、风险是什么、测试覆盖在哪里。它证明你理解源码边界。

第三张是 benchmark 表：任务 fixture、初始仓库状态、成功标准、允许工具、期望证据、失败分类。它证明 agent 能力不是主观感受。

第四张是真实任务验收表：issue 输入、执行 trace、文件 diff、测试输出、review findings、PR-ready summary。它证明 agent 能走完工程闭环。

第五张是产品路线表：alpha、beta、internal GA 各自要补什么。它证明毕业项目不是一次演示，而是一个可继续投资的系统。

教学步骤

1. 做架构审查

架构审查先看边界，不先看代码行数。建议把项目拆成：

CLI adapter：参数解析、交互输出、命令注册。
Runtime core：task lifecycle、session、trace、recovery。
Tool gateway：工具 allowlist、审批、执行、证据收集。
Context loader：AGENTS、skills、prompt templates、repo facts。
Worktree manager：创建、隔离、清理、diff 汇总。
Agent orchestration：planner、implementer、tester、reviewer。
Evaluation harness：benchmark fixtures、run report、回归趋势。
Release layer：package、migration、extension compatibility。

每个模块都要能回答：输入是什么、输出是什么、失败怎么上报、谁拥有副作用。

2. 做源码改造审查

如果项目改了 Pi 源码，不要只展示功能。要列出：

修改文件和 commit 范围。
触碰的是 public API、runtime internals、extension API，还是工具实现。
是否能用 extension、settings、package resource 达成，而不必 fork core。
新行为是否有测试。
如果上游 Pi 升级，冲突最大的位置在哪里。

Pi 自身已有很多 extension API 和 package resource 机制。毕业项目应该优先证明“我知道什么时候不用改源码”，然后再解释“为什么这处必须改”。

3. 做 agent benchmark

agent benchmark 不等于单元测试。它更像真实任务的可重复样本集。每个任务至少要记录：

repo fixture 或真实仓库 snapshot。
用户输入，例如 issue、bug report、feature spec。
允许工具和权限模式。
成功标准，例如测试通过、特定 diff、无越权文件修改。
证据要求，例如 trace、命令输出、final diff、review report。
failure taxonomy，例如 planning failure、tool failure、test failure、context failure、permission failure。

课程项目可以先做 20 个 golden tasks。数量不重要，重要的是每个任务都能重复跑、能判定成功失败、能解释失败原因。

4. 做真实任务验收

最终现场演示不要只问 agent 一个简单问题。推荐验收链路是：

issue -> plan -> isolated worktree -> implement -> test -> review -> summary -> PR-ready branch

验收时收集：

task id 和 trace path。
worktree path 和 branch。
运行过的命令和退出码。
修改文件列表和 diff 摘要。
测试证据。
reviewer findings。
未解决风险。
PR body 草稿。

如果中途失败，也不算直接失败。只要系统留下了清晰证据、停止在安全状态、能恢复或交接，这就是可靠性能力的一部分。

5. 做产品化路线

产品化路线不要写成愿望清单。用阶段目标：

Internal alpha：少数维护者使用，重点验证 CLI、trace、worktree、可靠性恢复。
Team beta：项目级配置、package/skill 分发、extension compatibility、benchmark 趋势。
Internal GA：权限治理、企业 provider、审计日志、升级策略、文档和支持流程。

每个阶段都要有退出标准。比如 Team beta 不能只说“更多人试用”，应该说“至少 5 个真实仓库、20 个 benchmark、核心命令成功率、失败分类、无未归属写入事故”。

实践例子

本课 lab starter 是 /Users/ryanchen/codespace/pi-agent-course-lab/src/22-graduation-audit.ts。它用 GraduationArtifact 做了一个最小审计：

type GraduationArtifact = {
  name: string;
  present: boolean;
  evidence?: string;
};

这个结构已经抓住毕业评审的关键：不是口头说“有”，而是每个交付物都必须有 evidence。课堂上要把它扩展成分区审计，把架构、源码、benchmark、真实任务、产品路线分开评分。

课堂代码推演

先把 starter 的 audit() 扩展为带类别和严重级别的审查：

type Category = "architecture" | "source" | "benchmark" | "acceptance" | "product";

type GraduationArtifact = {
  category: Category;
  name: string;
  present: boolean;
  evidence?: string;
  required: boolean;
};

function audit(artifacts: GraduationArtifact[]) {
  const missingRequired = artifacts.filter((item) => item.required && !item.present);
  const missingEvidence = artifacts.filter((item) => item.present && !item.evidence);

  return {
    passed: missingRequired.length === 0 && missingEvidence.length === 0,
    missingRequired: missingRequired.map((item) => `${item.category}:${item.name}`),
    missingEvidence: missingEvidence.map((item) => `${item.category}:${item.name}`),
  };
}

变量流要这样讲：

category 让评审不是一锅粥。benchmark 不足和产品路线不足是两种问题。
present 只表示交付物存在，不表示可信。
evidence 是审查证据，可能是文件路径、命令输出、trace id、diff、测试报告。
required 决定毕业门槛。比如“working CLI”“真实任务验收”“benchmark report”应是必需项；“漂亮 TUI theme”可以是可选项。

再给一个毕业项目输入：

const artifacts: GraduationArtifact[] = [
  { category: "architecture", name: "module map", present: true, evidence: "docs/architecture.md", required: true },
  { category: "source", name: "Pi patch review", present: true, evidence: "docs/pi-patches.md", required: true },
  { category: "benchmark", name: "20 golden tasks", present: false, required: true },
  { category: "acceptance", name: "issue to PR-ready branch demo", present: true, evidence: "traces/task-42.jsonl", required: true },
  { category: "product", name: "enterprise rollout plan", present: true, required: false },
];

课堂讨论结果应该是：这个项目不能毕业，不是因为 demo 不好，而是 benchmark 缺失；另外产品路线存在但没有 evidence，下一轮评审要补具体阶段和退出标准。

源码锚点

/Users/ryanchen/codespace/pi-agent-course-lab/src/22-graduation-audit.ts：本课 lab starter，用 artifacts 和 evidence 建立毕业评审入口。
/Users/ryanchen/codespace/external-sources/pi/packages/coding-agent/src/core/agent-session-runtime.ts at 61babc2：runtime、session replacement、resume/fork/import 等架构审查锚点。
/Users/ryanchen/codespace/external-sources/pi/packages/coding-agent/src/core/agent-session-services.ts at 61babc2：cwd-bound services 和 runtime factory 的边界锚点。
/Users/ryanchen/codespace/external-sources/pi/packages/coding-agent/src/core/resource-loader.ts at 61babc2：context、skills、prompts、extensions、themes 加载边界，用于判断是否必须改源码。
/Users/ryanchen/codespace/external-sources/pi/packages/coding-agent/src/core/extensions/types.ts at 61babc2：extension API 能力边界，用于源码改造审查。
/Users/ryanchen/codespace/external-sources/pi/packages/coding-agent/src/core/tools/edit.ts at 61babc2：edit tool 的 diff evidence 和文件修改锚点。
/Users/ryanchen/codespace/external-sources/pi/packages/coding-agent/src/core/tools/file-mutation-queue.ts at 61babc2：并行工具调用下的文件写入排队锚点。
/Users/ryanchen/codespace/external-sources/pi/packages/coding-agent/src/core/export-html/index.ts at 61babc2：session / trace 导出为可审查材料的锚点。
/Users/ryanchen/codespace/external-sources/pi/packages/coding-agent/test/test-harness.ts at 61babc2：构建 faux model、事件捕获和 session 测试环境，可作为 agent benchmark harness 的参考。
/Users/ryanchen/codespace/external-sources/pi/packages/coding-agent/test/agent-session-retry.test.ts at 61babc2：把可靠性行为写成可重复测试的参考。
/Users/ryanchen/codespace/external-sources/pi/packages/coding-agent/examples/extensions/subagent/README.md at 61babc2：subagent、reviewer、worker 协作模式的示例锚点。
/Users/ryanchen/codespace/external-sources/pi/packages/coding-agent/docs/prompt-templates.md at 61babc2：review / PR prompt template 能力，用于验收 PR-ready 输出。

掌握标准

学完本课后，你应该能做到：

为自己的 coding agent 原型画出模块边界，并说明每个模块的输入、输出和副作用归属。
做一份源码改造审查表，区分必须 fork Pi core 的改动和可以用 extension/package/settings 完成的改动。
设计 20 个左右的 golden tasks，并定义成功标准、证据要求和失败分类。
组织一次真实任务验收，从 issue 输入走到 PR-ready branch，并保存 trace、diff、测试输出、review report。
判断一个毕业项目是“可以毕业”“需要补证据”“需要补架构边界”还是“只是 demo”。
写出 alpha、beta、internal GA 三阶段产品化路线和每阶段退出标准。

课后习题

实践题：扩展 /Users/ryanchen/codespace/pi-agent-course-lab/src/22-graduation-audit.ts，给 artifact 增加 category、required 和 evidence 校验，输出 missingRequired 与 missingEvidence。
思考题：为什么一次成功的现场 demo 不能替代 agent benchmark 和真实任务验收证据？