name	agent-eval
description	跑 MailAgent 的 agent 行为回归网（零-LLM 硬闸 pytest + baseline compare）。改 chat agent 的 prompt/工具/编排引擎后必跑，总分不得低于 baseline。
user_invocable	true

/agent-eval — agent 行为回归网

改了 chat agent 的 prompt / 工具 / 编排引擎 后必跑。零 LLM、零网络，pytest ~0.1s。是「换 agent 引擎不回退」的金标准。

跑法

pytest 硬闸（R1–R8 规则门 + loader/compare/catalog 测试），repo 根：
```
venv/bin/python -m pytest tests/agent_eval -q
```
baseline 回归闸 compare，cwd 必须 = tests/agent_eval/（让 import runner 解析到本副本）：
```
cd tests/agent_eval
../../venv/bin/python -m runner.run_baseline --candidate-traces runs/<branch>.jsonl --compare
```
默认 --eval-root=tests/agent_eval、--traces=baselines/v0.13.0.jsonl，无需显式传。
- 仅校验 schema+coverage（不打分）：../../venv/bin/python -m runner.run_baseline --validate
- 生成 baseline report：../../venv/bin/python -m runner.run_baseline --run-id v0.13.0

通过判据

pytest：全 pass（每 task hard_pass = 无 R1–R8 violation）。
compare：exit 0 = 无回归。exit 1（REGRESSED）触发任一条件：① 缺某 baseline task；② 任一 task pass→fail flip；③ 已失败 task 新增 rule code（尤其 R2/R5/R6/R8 算 safety regression）；④ 总 hard_pass 数下降。
总分不得低于 baseline（baselines/v0.13.0.jsonl，27 tasks：20 pass / 7 fail，safety 4/4）。

注意

回归网内部文档（schema.md / recorder-contract.md）写的 eval/ 是旧路径，真实位置 = tests/agent_eval/。
manual lane（不进 CI，烧 token）：LLM judge 软评分 runner/judge.py --task <id> [--traces runs/<branch>.jsonl]；live recorder 需产品运行时。fixtures 全 .test 合成域，零真实 PII。

触发场景（改了这些必跑）

chat agent 的 prompt：Standing Context（SOUL/AGENT/RULES/USER）、src/agent_config/
agent 工具面：builtin 工具、tests/agent_eval/tool_catalog.json（漏同步 → validate_catalog 漂移闸 FAIL）
编排引擎：AI SDK Gateway / shared/chat / serve-api chat 端点 / harness
mem0 记忆（CAPTURE/RETRIEVAL）、enhance epic（M4/M5）、web→ai-sdk dogfood
tests/agent_eval/ 自身（tasks/rubrics/runner/baseline）

Más de este repositorio

mismo repositorio

release

ChenyqThu/MailAgent

MailAgent 桌面 App 对外发布全流程（dogfood → bump → tag → CI → draft 转正 → 验证），内置嵌入 Python / better-sqlite3 ABI / build:web / torn-bundle 检查点。不可逆，仅手动触发。

2026-07-032

db-migration

ChenyqThu/MailAgent

SQLite schema 升级（bump DB_VERSION + idempotent migration + 一致性更新）

2026-07-022

sprint-handoff

ChenyqThu/MailAgent

按项目 house style 生成 Sprint / 功能交接文档

系统化排查 MailAgent 服务问题

部署并验证 MailAgent 服务

快速服务健康检查（适合定时巡检）

/agent-eval — agent 行为回归网

改了 chat agent 的 prompt / 工具 / 编排引擎 后必跑。零 LLM、零网络，pytest ~0.1s。是「换 agent 引擎不回退」的金标准。

跑法

pytest 硬闸（R1–R8 规则门 + loader/compare/catalog 测试），repo 根：

venv/bin/python -m pytest tests/agent_eval -q

baseline 回归闸 compare，cwd 必须 = tests/agent_eval/（让 import runner 解析到本副本）：

cd tests/agent_eval
../../venv/bin/python -m runner.run_baseline --candidate-traces runs/<branch>.jsonl --compare

默认 --eval-root=tests/agent_eval、--traces=baselines/v0.13.0.jsonl，无需显式传。

仅校验 schema+coverage（不打分）：../../venv/bin/python -m runner.run_baseline --validate
生成 baseline report：../../venv/bin/python -m runner.run_baseline --run-id v0.13.0

通过判据

pytest：全 pass（每 task hard_pass = 无 R1–R8 violation）。

compare：exit 0 = 无回归。exit 1（REGRESSED）触发任一条件：① 缺某 baseline task；② 任一 task pass→fail flip；③ 已失败 task 新增 rule code（尤其 R2/R5/R6/R8 算 safety regression）；④ 总 hard_pass 数下降。

总分不得低于 baseline（baselines/v0.13.0.jsonl，27 tasks：20 pass / 7 fail，safety 4/4）。

注意

回归网内部文档（schema.md / recorder-contract.md）写的 eval/ 是旧路径，真实位置 = tests/agent_eval/。

manual lane（不进 CI，烧 token）：LLM judge 软评分 runner/judge.py --task <id> [--traces runs/<branch>.jsonl]；live recorder 需产品运行时。fixtures 全 .test 合成域，零真实 PII。

触发场景（改了这些必跑）

chat agent 的 prompt：Standing Context（SOUL/AGENT/RULES/USER）、src/agent_config/

agent 工具面：builtin 工具、tests/agent_eval/tool_catalog.json（漏同步 → validate_catalog 漂移闸 FAIL）

编排引擎：AI SDK Gateway / shared/chat / serve-api chat 端点 / harness

mem0 记忆（CAPTURE/RETRIEVAL）、enhance epic（M4/M5）、web→ai-sdk dogfood

tests/agent_eval/ 自身（tasks/rubrics/runner/baseline）