ReadAware Agent Evals

模型评测运行真实 AgentThread，使用内存端口和真书 fixture；它不能代替 真实宿主、插件或 Tauri 验收。确定性测试与模型行为评测分开报告。

选择工作范围

• 先确定待验证行为、相关场景和本轮通过判据；已有工件能回答的问题直接读取工件。 普通接线、类型或文档修改不自动触发 live eval。
• 定向修复先验证受影响场景及共享路径的代表性回归。共享行为变化或失败证据表明 影响更广、或用户要求全量时，再扩大套件范围。
• 重复采样用于判断随机行为的稳定性，事先确定本轮样本数与判据。单次成功只能证明 该样本成功；结果矛盾时说明不确定性并决定必要的下一轮，不跑到偶然全绿为止。
• 判据满足后结束本轮。仅在相关实现、模型配置、fixture 改变或有未解决失败时重跑。 费用低不构成增加调用的理由，也不为了省费用省掉已确定的必要样本。
• 路由、鉴权或服务不可用属于环境阻塞。只做与错误对应的诊断/有界重试；环境没有 变化时停止 live 调用并报告，不用新增 prompt 断言冒充行为质量进展。

按需参考

• 执行评测、比较模型或选择场景：运行说明。
• 主 Agent 读取日志、定位证据、保存评审：结构化审阅。
• 用户查看结果、自由评测或修改评分：Viewer。
• 新增/修改场景或书籍：Fixtures。
• 底层格式或 runner 开发：仓库 packages/agent/EVALS.md。

.eval 工件含书文本与模型输出，不提交、不外发。模型、provider、thinking 和 fixture 配置须可追溯；配置不同的 runs 不得直接当作同条件回归结果。

统一评测原则（所有 Eval，默认执行）

按任务性质选择判定，不按 suite 名称或是否在书内划分：

• 确定性操作（主题、设置、标注写入、删除等）：程序验证实际状态、目标范围、 授权与执行回执，可以作为主要结论。明确标记 evaluation: "programmatic"，并提供 state 检查；只有工具名或回答关键词的检查不足以证明操作成功。
• 阅读与内容理解（词义、解释、引用、章节归属、人物、网页/图片解读等）：默认 evaluation: "semantic"，由主 Agent 对照原文和完整结构化日志判定。程序检查为辅助。
• 混合任务：操作部分查实际状态，内容部分仍须语义审阅，整体按 semantic 验收。 自动 judge 可初评，不能替主 Agent 验收。模型回答长本身不是失败。

旧日志未标记 evaluation 时保守按 semantic 处理。不为得到绿灯把内容任务改成 programmatic，也不为满足人工审阅流程，强迫纯设置操作等待模型打分。

Agent 直接读结构化日志；Viewer 给用户看。 不启动浏览器或遍历 Viewer 来审题、 取回答或写评语。默认用 eval:review --list / --case / --save，必要时读取原始 JSON。 如果判断依赖的信息没有被记录，补全日志及可追溯坐标，不能用 UI 截图替代缺失证据。

语义与混合任务按以下顺序执行；确定性操作核对场景的状态验证覆盖后直接使用程序结果：

1. 先定范围与读者标准：记录场景、模型/配置、采样数和预期行为。检查 fixture 是否代表真实失败边界；列出需核对的事实、原文和状态，不把关键词表当参考答案。
2. 先读证据，再看分数：逐条阅读本轮验收范围内的问题、阅读位置/选区、完整回答、 工具参数与结果、授权/取消、实际状态及对应原文。先读 eval:review --case <targetId> 或 runs/<variant>/<case>/<repetition>.review.json；需要深入时再读完整 run。 旧工件缺快照时查当时的 seed / fixture / 宿主工件，不能把当前 fixture 冒充旧现场。 长日志按 turn、tool 或源文本偏移分段读取；明确遗漏的证据补齐前保留待审。 大批套件可分批审阅；未审部分保留 pending，不以抽样替所有样本背书。
3. 给出有根据的语义结论：正确性（事实/出处/卷章号/引文）、完整性、实际帮助、 表达分寸。允许同义表达、别名和不同但有效的工具路径。回答长本身不是缺点； 必须指出怎样妨碍当前需求。真正的越权、凭据泄漏、错误写入和未授权剧透仍是失败。 标为 pass / partial / fail，并写明对应 turn / tool / 原文 / state 的证据及原因； 填写四维评分与问题标签。chapterIndex 绝不自动换算为印刷章号。
4. 再对照辅助信号并归因：区分产品缺陷、断言误报/漏报、fixture 不足、judge 误判 和环境错误。自动 --judge 只提供带依据的初评，不替主 Agent 验收；同模型自评 也不是独立证明。不得把 judge 的数字平均分当最终质量结论。
5. 保存评审并重新汇总：用 eval:review --save <review.json> 合并到现有 human-reviews.json（见 格式与命令），用户在 Viewer 看到相同评语；总体 verdict 必须有证据评语，问题用 findings 记录证据坐标及归因。 执行 bun run eval:review <bundle> --gate 更新报告。存在 pending、partial、fail、 error、未完成的计划样本或未通过的自由追问时，不能宣布本轮验收通过。
6. 验证题库之外的行为：被修改的产品能力至少补一个真实自由问题，必要时追问， 同 run 保存问题、答案、工具与评语。只改评测工具时可用历史原始日志验证误判， 不为满足数量虚构产品调用或机械重跑已解决问题。
7. 交付按证据分层：先说语义审阅发现的行为与原因、已审/待审范围和剩余问题， 再单列程序检查与自动 judge；机器全绿但回答错误仍是产品问题。用户可以继续改评语、 补问；不能拿自己的评分替用户关闭讨论。

语义任务验收是“运行 → 主 Agent 读证据 → 保存评审 → 汇总”，不是可选尾项。 eval:agent --gate 的语义新样本会因待审返回非零；完成评审后用 eval:review --gate。 确定性操作明确选择 programmatic、有完成输出及实际 state 检查时，可直接通过 gate。 CI 中确定性契约仍用 bun test，不要用无审阅的模型通过率替代它。

失败诊断

• 读失败样本的完整工具轨迹和回答，区分产品行为错误、断言问题与环境错误。
• 只修评分逻辑时用 bun run eval:rescore .eval/<suite>-<run-id> 复用输出； --judge 仍有模型调用，不能称为免费。
• 修行为后验证该场景，并按实际影响选择回归样本。发现范围外问题记录后续事项。
• 观察哨（如 santi-no-cursor-caution、crossbook synthesis）保留原有检错语义； 不通过放宽断言掩盖缺陷。修复真实行为后可以通过，不要求刻意维持红灯。