pi 新增定制化场景的文档提升评测，量化内嵌文档的实际作用

2026 年 9 月 11 日，christianklotz 把 PR #9491 合入 pi 编码代理，为 packages/evals 评测套件带来一类新东西——文档提升（documentation lift）评测：通过对比运行，量化系统提示里内嵌的 Pi 文档究竟帮了多少忙。受测的是三个定制化场景：向现有 provider 添加模型、接入 OpenAI 兼容 provider、接入自定义流式 provider，原有的扩展编写评测也换用了同一套基线。这些改动目前都只存在于主线，将随 v0.85.1 之后的下一个版本一同放出。

每项对比评测把同一任务跑两遍：一遍用 pi 默认系统提示，一遍用只删掉内嵌 Pi 文档块的基线——靠一个新的共享辅助函数 excludePiDocumentation 依提示词的稳定分节标记完成裁剪。扩展评测此前就在做提示词对比，但旧基线把 Guidelines 一节连同文档一起删了；这次重构把差异收窄到文档本身，报告出的提升幅度因此只归因于文档，不掺别的变量。

两个新评测文件让场景落在真校验而非字符串比对上。models.eval.ts 要求代理为现有 provider 编写一个 fixture 模型条目，再审视生成的运行时：模型必须带着预期元数据被解析出来，且配置重载后原有模型一个都不能丢。providers.eval.ts 则在本地起一个 HTTP 服务器，分别扮演 OpenAI 兼容端点和手写流式 API，代理写好的配置必须真正跑通往返——探测提示词带回预期的应答标记，这次运行才算得分。

重复运行与报告是一等公民。命令行的 --repetitions 或环境变量 PI_EVAL_REPETITIONS 控制对比套件的重复次数——README 给出的经验是开发评测时跑一遍、报告提升幅度时跑五遍——每次调用最后都会输出一份复合的 Eval Comparisons 报告：以百分点计的通过率差值，加上双侧的 token、延迟与预估成本。产物落盘在 .eval/ 下：report.txt、report.json、runs.jsonl、sessions/ 里的会话转录，以及 sources/ 中的源码附件。评测框架本身也顺手做了隔离——每次运行的评测主目录与 agent 状态放进独立的临时目录，同时保留运行时重载行为与会话产物。

评测命令、带示例数值的报告格式与产物布局，都写在这份 PR 对 packages/evals/README.md 的改动里，可在 GitHub 上查阅。