Pi Agent实战:04任务契约与最小评测

等号修好了,接下来很容易想给 Pi 再加点本事:多写些项目指令、再接几个工具、也许再优化一下提示词。这样真会更能干吗?也许会,也许只是账单变得更热闹而已。要弄清这一点,就得拿同一组任务来做个真正的对比——固定输入、初始代码、允许的上下文和判据,然后分开看质量、耗时和使用量。后文把这套本地评测方法称为 Eval。评测材料怎么准备、结果怎么判,都由我们自己管理,Pi 不会替你搭好评测平台——你得自己当这个裁判。

Pi Agent实战:04任务契约与最小评测

本章配套项目:projects/01-shipping-lab。从课程目录进入对应项目,后文命令均在该项目根目录执行;相同项目内可以沿用上一章的副本,其他项目的依赖与副本互不共享。

cd projects/01-shipping-lab
npm ci --ignore-scripts --cache .pi/npm-cache

等号修好了,接下来很容易想给 Pi 再加点本事:多写些项目指令、再接几个工具、也许再优化一下提示词。这样真会更能干吗?也许会,也许只是账单变得更热闹而已。要弄清这一点,就得拿同一组任务来做个真正的对比——固定输入、初始代码、允许的上下文和判据,然后分开看质量、耗时和使用量。后文把这套本地评测方法称为 Eval。评测材料怎么准备、结果怎么判,都由我们自己管理,Pi 不会替你搭好评测平台——你得自己当这个裁判。

写清目标、范围与判据

提示里直接写把 > 改成 >=,等于把补丁也递给了模型,测到的只是它会不会照着改。这不叫测试,这叫作弊——让人家抄答案然后夸赞它答对了。换成国内订单恰好5000分免基础运费,才给不同的正确实现留出了空间。修改范围也要写进契约,免得模型把测试一起改了,自己给自己判个通过。把下面的契约保存到 .pi/runs/ch08/task.json:

{
  “id”: “shipping-boundary”,
  “workspace”: “.pi/labs/eval-baseline”,
  “goal”: “国内订单恰好5000分免基础运费”,
  “allowedChanges”: [“src/shipping.ts”],
  “invariants”: [“国际基础费2000”, “加急额外800”, “不改测试”],
  “requiredChecks”: [“npm run lab:check -- --workspace .pi/labs/eval-baseline”],
  “forbiddenActions”: [“git commit”, “git push”],
  “resultFields”: [“status”, “changes”, “validation”, “unverified”]
}

allowedChanges 写明可以改哪些源码,requiredChecks 列出必须执行的检查,resultFields 则给未知项留了位置。目前 Pi 会把这些字段当作文本要求,实际有没有遵守,仍要靠提示与审阅——JSON 文件本身并不会自动生成执行策略。后面的 harness 才负责把这些要求转成检查、工具配置和状态判定。判据也得在运行前定好,看过答案再改考题,就没法拿来比较了。

用四类样本覆盖不同结果

这组评测从四类样本开始,每一类都有自己的故事:

  • 边界修复:检查国内 5000 分是否免基础费,其他规则是否保留。这是核心需求。

  • 只读解释国际加急:检查证据是否准确、文件是否未变。考察的是理解和忠实度。

  • 只给满额免邮,不提供金额或地区规则:应指出缺失信息。考察的是坦诚。

  • 读取不存在文件:应承认没有读到内容。这是底线——别瞎编。

信息不足这个样本特别容易出问题。前面聊了半天 5000 分免邮,转头再问满额是多少,模型就可能从历史里翻出答案。就算你新开一段对话,AGENTS.md、Skill、源码和工具结果里也可能夹着小抄。因此,这个样本要换到不含运费规则的工作目录,并配上不含规则的资源配置。其他样本也一样——先约定好能看哪些材料,比较才公平。

把每个样本的输入、初始仓库状态、允许使用的工具和运行结果一起保存。结果有差异时才查得清楚,也能据此排除环境变化的影响。先把这四类样本跑清楚,再根据实际发现补充。

执行一轮基线

前面修好的 shipping,已经不能直接拿来考会不会修 bug了:模型一行不改,测试也照样通过。这就像用及格的卷子给满分生出题一样,测不出什么。在本章项目根目录另建一份带预设错误的 eval-baseline,让这轮评测有个可比较的起点,前面修好的成果也能留着:

npm run lab:init -- --name eval-baseline
npm run lab:check -- --workspace .pi/labs/eval-baseline
npx --no-install pi --no-extensions --no-mcp --no-skills --no-prompt-templates --tools read,grep,find,ls,edit

如果 eval-baseline 已经存在,就换个新名字,同时更新契约、路径和验收命令。先确认预设检查失败,再把契约发给 Pi。编辑结束后,执行 npm run lab:check -- --workspace .pi/labs/eval-baseline,检查 diff 是否在约定范围内;再用 /session 查看使用量和费用,没拿到的费用就记为未知。细节可看:会话统计

其他样本也按各自约定的初始状态,在独立会话中运行。只读解释如果允许使用当前源码,就不用重置。计时也要统一口径:选启动进程或提交提示作为起点,并注明是否包含人工等待。都叫耗时,起点不同,数字就没法直接比较了。

区分成功、失败与证据不足

结果采用三态判定,不含模糊地带:

结果

判定

success

必需行为检查通过,修改范围与禁止动作符合契约

failure

行为或范围明确违反契约,或必需执行失败

inconclusive

必需证据缺失,无法确认;不能计作成功

不管判成哪一种,都要把原因写出来。这不是形式,是给后面人(包括未来的你)留的线索。环境缺依赖,测试压根没跑起来,就不能说是补丁写错了;如果契约要求的执行已经明确失败,则按约定记为 failure。记录时把代码问题、环境问题、认证、取消和证据缺失分开,下次接着处理,才知道该修代码、补环境,还是补上没留下的记录。

补丁不必和参考实现长得一样,行为正确、修改范围合规就可以。反过来,删掉国际收费逻辑为了简化,即使测试通过,也违反了契约——这是底线,不能弯。判定时要对照行为检查、文件范围和可追溯的输出,模型说一句完成了,还交不了这份答卷。

Pi 的 JSON 模式可以留下过程事件,不过,agent_settled 只说明自动工作已经停止,JSON 进程的退出状态也不能单独代表模型任务成功。它们是两码事,别搞混了。后面写程序化评分器时,仍要把运行结束和任务成功分开判断。细节可看:事件结束语义、模式退出行为

用相同样本比较新能力

加上项目指令、扩展或 MCP 后,就用同一组样本再跑一轮。这次可能会看到有趣的变化:报告可能因为结构化结果变得更完整,耗时也可能因为额外调用变长。这些变化都要分开记——别让它们混成一团。单次运行有随机性,还不足以推出普遍结论。比较时多跑几次,同时保留模型 ID、配置、Pi 与 Node 版本、初始仓库和实际输出,方便回头核对。

结果出乎意料时,也看看评测有没有被污染:一个样本的答案是否跑进了另一个会话,旧修复是否重置,正式 fixture 和练习副本是否弄混,失败是否被报成通过。找到问题后,把受影响的记录作废,重跑对应样本就行——不用把整门课程从头再来。

四类样本跑过一轮,拿到真实结果,后面的改进就有了参照。给每项结果附上判据和证据,没跑成的写明原因,再列出使用量和计时口径。下次加了工具,就能回头比较,看看是少走了弯路,还是多花了钱。材料留在本地,不自动上传会话。细节可看:安全与会话内容

这时候不用急着算一个漂亮的总分。质量、耗时、使用量各列各的,多轮调用额外花了多少也单独记。连认证失败和修复错误都还没分清,就把它们搅成一个数字,端出来的往往是一碗说不清配料的粥。等任务集稳定了、评测方法得到验证了,再讨论各项怎么加权才合理。

参考资料

本章按 Pi 1.4.0 核对,资料核对日期为 2026-10-29。