AI Agent技能质量如何保证：NotFair的LLM-as-Judge评估与E2E路由测试体系全解析-平芜编程栈

AI Agent技能质量如何保证：NotFair的LLM-as-Judge评估与E2E路由测试体系全解析

【免费下载链接】notfair-pluginOpen-source SEO, GEO, and marketing skills for AI agents.项目地址: https://gitcode.com/gh_mirrors/to/notfair-plugin

NotFair Plugin 是一个开源的 SEO、GEO 与营销技能插件包，为 Claude Code、Codex 等 AI Agent 提供 48 个可执行技能。它的独特之处在于：每个技能（SKILL.md）都配套了一套可量化、可复现的质量保障体系——用 LLM-as-Judge 给文档质量打分，用 E2E 路由测试验证技能会不会被正确触发。本文带你完整了解这套 Agent 技能质量评估机制。

一、为什么 AI Agent 技能需要质量评估？

普通软件测试看"功能是否跑通"，而AI Agent 技能（本质是一份给模型阅读的操作手册SKILL.md）要回答三个更难的问题：

文档够不够清楚？模型读完指令后，是否知道该调哪些脚本、传什么参数、输出长什么样？
技能会不会被错误触发？用户问"CSS 布局坏了"，SEO 审计技能是不是不该跳出来？
产出物质量如何？跑完一整轮 SEO 审计，生成的报告有没有"Quick Wins"、建议是否具体可执行？

NotFair 针对这三层问题，构建了三个测试层级：llm-judge（文档质量）、e2e（完整执行）、routing（路由触发），全部放在 test/ 目录中。

二、LLM-as-Judge：让 AI 给技能文档打分

三维评分标准：清晰度、完整度、可执行性

核心实现在 test/helpers/llm_judge.py。它用便宜的 Gemini Flash 模型（gemini-2.0-flash、temperature=0.0）充当"评审"，对技能文档的每个章节按 1-5 分打分：

维度	考察点	及格线
clarity 清晰度	Agent 能否仅凭描述理解每一步在做什么	≥ 4
completeness 完整度	命令、参数、预期行为是否都有文档记录	≥ 4
actionability 可执行性	Agent 能否不追问就直接正确执行	≥ 4

评审提示词定义在 judge() 函数，强制模型只返回 JSON，并附一句reasoning解释扣分原因——失败时一眼就能看出问题在哪。

报告质量也有专属评审

除了评"文档"，NotFair 还评"产出"。seo_report_judge()会检查 Agent 生成的 SEO 报告是否满足四项硬指标（llm_judge.py）：

✅ 包含带具体 URL 和查询词的Quick Wins区块
✅ 建议具体可执行（而非"提升你的 SEO"这类空话）
✅ 含 30 天行动计划
✅ 至少一条建议量化了预期影响（如预计点击增长）

一次完整跑 LLM-judge 套件成本仅约$0.05，门槛低到可以在每次修改文档后随手运行。

三、E2E 路由测试：技能会不会被"叫错名"

这是整套体系中最巧妙的部分。路由测试（test/test_skill_routing_e2e.py）验证的不是"技能能不能干活"，而是技能的 description 写得够不够精准——因为它决定了 Agent 何时加载这个技能。

正反两组提示词对照

测试定义了 SHOULD_TRIGGER 与 SHOULD_NOT_TRIGGER 两组真实用户话术：

应触发 ✅	不应触发 ❌
"网站流量上月掉了 40%，帮我查原因"	"CSS Grid 在移动端布局错位"
"帮我做一次 SEO 审计"	"优化一个 200 万行表的 SQL 查询"
"我想看 Google 里排名靠前的关键词"	"帮我写一篇远程团队项目管理博客"

判定方式：不靠模型自我报告

如何判断技能真的被调用了？NotFair 使用特征标记法：检查输出中是否出现phase 1、quick wins、analyze_gsc等 SEO 流程专属词汇，或 Agent 是否真的调用了analyze_gsc脚本。此外还有一个防御性设计——超时/崩溃等 harness 故障绝不允许静默通过"不应触发"用例（test_skill_routing_e2e.py），避免"测试没跑起来 = 通过"的假阳性。

四、E2E 执行测试：用 Mock 数据跑完整工作流

真正的端到端测试在 test/test_skill_e2e.py。它通过 session_runner.py 以子进程方式启动claude -p，解析stream-json输出，完整记录工具调用链、轮次、耗时与费用。

关键设计是零真实凭证：测试夹具 test/fixtures/ 提供了mock-gcloud.sh和sample_gsc_data.json，把真实的 Google 数据拉取替换为确定性的模拟数据，Agent 就能走完整 6 个阶段的 SEO 审计，且每次结果可复现。

五、省钱的巧思：基于 Git Diff 的测试选择

LLM 测试不是免费的，NotFair 用 test/helpers/touchfiles.py 实现了差异触发：每个测试声明自己依赖哪些文件（如"路由测试只依赖skills/seo-analysis/SKILL.md"），运行时对比基线分支的 diff，只有相关文件被改过才执行该测试。修改了 Ads 技能，SEO 的评估就自动跳过——测试成本与实际改动精准挂钩。

六、结果持久化：每次评估都留下"体检报告"

所有层级共用 test/helpers/eval_store.py 的结果收集器，在进程退出时把本次评估写入~/.toprank-evals/，文件名包含版本号、分支、git SHA 和时间戳，JSON 内容记录每个用例的通过状态、耗时、花费、评审分数与推理过程，并在终端打印一张汇总表格。这让"技能质量"像性能指标一样，可以随版本演进被追踪和对比。

此外，还有一层免费的静态守卫：test/unit/test_skill_descriptions.py 无需任何 API Key，直接检查全部技能的 description 是否超过 1024 字符上限、以及各模型封装层与源文档是否保持同步——描述超长的技能会挤占 Agent 的上下文，这是最便宜的质量防线。