阶段三 · 集成与实践
实战与评测 —— 把机制拼成一个能验证的东西
前面十章讲机制,这一章把它们组装起来。四个离线小项目,每个训练一种工程边界;再加上测试与评测的分层,构成同一条质量链:能跑不等于可维护,功能正确、工具安全、结果质量是三件不同的事。
具体回答三个问题:怎么判断一个 Agent 是"好的"?确定性测试能证明什么、不能证明什么?评测该怎么设计才有信息量?
学习目标
- 综合运用循环、工具边界、会话、协议这几套机制解决具体问题。
- 分清三种评测维度:功能正确、工具安全、结果质量。
- 理解为什么确定性测试证明不了"模型在开放任务上永远正确"。
- 知道 Pi 自己的评测是怎么做的,以及"提升幅度"为什么比"分数"更有信息量。
一、问题:怎么判断一个 Agent 是"好的"
"能运行"是最低标准。可维护的 Agent 要回答三个不同的问题:
| 维度 | 问题 | 手段 |
|---|---|---|
| 功能正确 | 逻辑对不对 | 确定性单元测试 |
| 工具安全 | 会不会越权、会不会误伤 | 边界测试、允许列表、回归门槛 |
| 结果质量 | 产出好不好 | 固定样本集、人工复核、配对对照 |
确定性测试解决前两个;第三个需要生产级评测。确定性测试不能证明模型在开放任务上永远正确——它只能证明"机制没坏"。
二、四个项目,各练一种能力
| 项目 | 练什么 | 对应章节 |
|---|---|---|
| 会话检查器 | 只读解析记录、统计角色 | 05 章 |
| 只读审查器 | 意图白名单 + 路径边界 | 03 章 |
| 流水线汇总 | 把多项检查收敛成稳定报告 | 本章 |
| 协议控制台 | 分帧 + 方法白名单 | 10 章 |
会话检查器:只读
它逐行读会话记录,统计角色与压缩次数,返回一份不可变的报告。关键在于它不执行记录里的任何内容——会话文件里的命令输出只是数据,不是指令。它也不修改文件,不认识的记录类型直接忽略而不是报错。
只读审查器:先验意图,再验路径
检查顺序是固定的:先看"这次请求是不是只读",再看"目标路径在不在边界内"。
def review_request(policy, intent, target):
if intent not in {"read", "search", "list"}: # ① 意图白名单
return ReviewDecision(False, None, "intent is not read-only")
candidate = PurePosixPath(target)
if candidate.is_absolute() or ".." in candidate.parts: # ② 拒绝绝对路径与父目录跳转
return ReviewDecision(False, None, "target escapes the review root")
return ReviewDecision(True, str(policy.root / Path(*candidate.parts)), "allowed")
和第 03 章的权限实验是同一思路:先检查、后放行,被拒的请求不产生任何副作用。
流水线汇总:稳定报告
它把几项检查(课程契约、文档链接、单元测试)收敛成一份有序报告,失败时给可读原因而不是崩溃堆栈。为什么要专门写这个?因为 CI 要的是稳定可解析的结果,而"一堆日志里翻哪一行报错"是反模式。
协议控制台:白名单
它用课程的分帧器解析单行请求,只响应一种方法,返回 JSON——不创建子进程、不执行命令。演示三件事:标准输出只走协议、方法要有白名单、错误是数据。
三、评测为什么是独立的一层
Pi 仓库里有一个独立的评测包,不发布到包管理器,版本随仓库走。它说明"评测与运行时分离"是官方方向:评测不是测试的附属品,而是独立的一层。
它的方法论值得借鉴,因为它回答的问题比"打个分"更有价值:同一批任务,分别在"不给文档"和"给文档"两个隔离环境里跑,配平后算提升幅度,报告只给配对结果。
这就是"对照实验"的思路。它比"跑一遍看分数"多做了两件事:
- 控制了变量:两次运行除了"有没有文档"之外尽量一致。
- 给出了因果:不是"模型得了 80 分",而是"有文档比没文档高多少"。
结果落在按时间戳命名的报告里;模型通过环境变量指定,没有所谓的"评测基线文件"。
顺带纠正一个说法:模型配置写在一个文件里(不是目录),新版本还提供了一份由 schema 生成的逐字段参考。模型升级对评测的影响,靠改这个文件与重跑评测来体现。
当前 Pi 行为
- 仓库的检查入口覆盖代码风格、依赖与导入检查、类型检查;测试脚本在清空环境、隔离用户目录、不注入任何密钥的情况下跑测试,需要密钥的用例由测试自身跳过。
- 评测是独立的、不发布的内部包,有自己的一套 runner(命令行、容器、计划、报告)。
- 评测采用"配对对照"的方法:同一批任务在两种条件下各跑一遍,报告给提升幅度而不是孤立分数。
- 结果按时间戳归档;模型由环境变量指定。
- 模型配置文件是单个文件,另有 schema 生成的字段参考文档。
代码里的名字
| 通俗说法 | 代码里的名字 |
|---|---|
| 仓库检查 | npm run check |
| 隔离测试脚本 | test.sh |
| 评测包 | @earendil-works/pi-evals(private: true) |
| 评测入口 | npm run eval / eval:docs |
| 报告位置 | .eval/<时间戳>_<编号>/report.json |
| 字段参考 | models-configuration.md |
源码位置
packages/evals/:评测 runner 与方法论文档。package.json:检查与评测脚本入口。test.sh:隔离环境的测试脚本。
失败与边界实验
评测本身也会失败——而且是安静地失败。三类最常见:
- 评测过拟合。 任务样例全来自同一个 fixture,模型学会了"这个仓库的套路",评测满分,真实任务一塌糊涂。修法:按难度和错误类型分层;Pi 把评测资产放在评测目录、测试 fixture 放在各包的测试目录,就是为了让两类资产各自演进。
- 把人工评分伪装成确定性测试。 "看起来更好"不是断言。修法:人工评分单独成列,永不进 CI 门槛。
- 安全回归没有门槛。 功能全部通过,但某次改动让工具能写到边界外——评测只测了"做对了",没测"没越权"。修法:禁止越权、禁止未授权写入、工具调用必须在允许列表,这三条是硬门槛,与功能正确并列。
python3 -m unittest discover -s tests -v
python3 -m learn_pi_lab lab mini-agent
在 Pi 里怎么操作
python3 -m unittest discover -s tests -v # 全部测试
python3 scripts/check_course_contract.py # 课程契约
python3 scripts/check_markdown_links.py # 本地链接
仓库自己的检查是 npm run check 与隔离环境下的测试脚本。
Python 实验
python3 -m unittest tests.test_11_projects -v
验证方式
python3 -m unittest discover -s tests -v
python3 scripts/check_course_contract.py
python3 scripts/check_markdown_links.py
三条命令都成功即视为通过(本地 Windows 环境下会有一批与符号链接相关的失败,见仓库说明)。
边界与安全
- 确定性测试不能证明模型在开放任务上永远正确;生产评测还应包含固定样本集、人工复核、失败分类与回归门槛。
- 日志策略不得泄露敏感数据;本课程四个项目不访问网络、不调用模型、不执行 shell 命令。
- 迁移到 Pi 前,用 TypeScript 重新实现并补齐生产级边界(认证、拦截、取消、脱敏、端到端测试)。
自测三问
- 为什么"跑通测试"证明不了"模型在开放任务上做得好"?
- 为什么"有文档比没文档高 12%"比"得分 82"更有信息量?
- 三个项目里,哪一个在保护"不会误伤"而不是"能做对"?
回顾
- 三个维度:功能正确、工具安全、结果质量;确定性测试只覆盖前两个。
- 四个项目:只读解析、意图+路径双闸门、稳定报告、白名单协议。
- 评测要配对:给提升幅度,而不是孤立分数。
- 质量链:行为测试 + 文档契约 + 集成项目,缺一不可。
课程到此结束。回到 课程地图 或 源码映射,把每一章的机制放到 Pi 的真实源码里对照验证——这不是"逐行复制源码",这是"掌握真正重要的设计,然后自己重建它"。