SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场eval-agent-md

eval-agent-md

测试与质量

查看项目

更新于 10-16 03:01

技能介绍

用途

eval-agent-md 用于对 CLAUDE.md 或智能体 .md 定义文件进行行为合规性测试，验证文件中的规则是否被实际遵循。

主要能力

  • 读取 CLAUDE.md（或智能体 .md 文件）。
  • 为检测到的每条规则自动生成行为测试场景。
  • 可选生成测试多条规则交互的集成场景（--holistic），例如优先级排序、冲突解决、累积合规。
  • 每个场景通过 claude -p 运行，并采用 LLM-as-judge 评分。
  • 报告合规性得分，并给出每条规则（及集成场景）的通过/失败细分。
  • 可选运行自动化变异循环以改进未通过的规则。
  • 结果包含多维指标：每个场景的响应大小（字符数、词数），以及耗时和缓存统计，便于变异测试期间的 A/B 对比。
  • 支持场景缓存复用（--no-scenario-cache / --no-cache 可强制重新生成）、判断缓存（--no-judge-cache）与主题响应缓存（--no-subject-cache）。
  • 支持 --compare-models 跨 haiku/sonnet/opus 运行并展示对比矩阵。

使用方式

脚本须始终使用 uv run --script 运行，不使用 python、python3 或裸脚本名。脚本通过内联 # /// script 元数据声明依赖，uv run --script 会自动解析全部依赖，无需 pip install。使用 python 或 python3 运行会因依赖未安装而出现导入错误。

工作流程分步：

  1. 定位目标文件：优先级为 --self（目标为本技能的 SKILL.md）→ 用户提供的路径参数（如 /eval-agent-md ./CLAUDE.md）→ 当前工作目录的项目级 CLAUDE.md → ~/.claude/CLAUDE.md（用户全局）→ 若均未找到则询问用户。读取文件并与用户确认文件名、路径与行数，等待用户确认后再进入下一步。

  2. 生成测试场景：

uv run --script [SKILL_DIR]/scripts/generate-scenarios.py [TARGET_FILE]
# 对 SKILL.md 文件添加 --skill 生成工作流感知场景：
# uv run --script [SKILL_DIR]/scripts/generate-scenarios.py --skill [TARGET_FILE]
# 自测（隐含 --skill）：
# uv run --script [SKILL_DIR]/scripts/generate-scenarios.py --self
# 同时生成集成场景：
# uv run --script [SKILL_DIR]/scripts/generate-scenarios.py --holistic [TARGET_FILE]

脚本自动从 git 检测仓库名并保存至 /tmp/eval-agent-md-<repo>-scenarios.yaml，可用 --repo-name NAME 或 -o PATH 覆盖。生成后读取输出文件并向用户展示场景数量、各场景测试的规则、每个场景提示的简要预览，并询问是否准备运行。若输出文件缺失或包含 0 个场景，则停止并提示目标文件需具备清晰结构化的规则（标题、编号条目或带标签的段落）。

  1. 运行行为测试：
uv run --script [SKILL_DIR]/scripts/eval-behavioral.py \
  --scenarios-file /tmp/eval-agent-md-<repo>-scenarios.yaml \
  --claude-md [TARGET_FILE] \
  --runs 1 \
  --model sonnet

可控制选项：--runs N（每场景运行次数，多数投票，默认 1，建议 3）；--model MODEL（测试对象模型，默认 sonnet）；--compare-models；--workers N；--no-judge-cache；--no-subject-cache。若所有场景返回错误或 null 判定，则不打印合规性报告并提示检查错误。

  1. 报告结果：输出合规性报告，包含每规则通过情况、集成情况（仅 --holistic 显示）、合并得分以及失败规则及修复建议。

  2. 改进（可选）：用户说 "improve"、"fix" 或传入 --improve 时运行变异循环：

uv run --script [SKILL_DIR]/scripts/mutate-loop.py \
  --target [TARGET_FILE] \
  --scenarios-file /tmp/eval-agent-md-<repo>-scenarios.yaml \
  --max-iterations 3 \
  --runs 3 \
  --model sonnet

默认始终为 dry-run，展示每条建议的变异并在应用前询问用户。

常用参数

  • [path] — 目标文件（位置参数）
  • --improve — 测试后运行变异循环
  • --runs N — 每场景运行次数（默认 1，建议 3）
  • --model MODEL — 测试对象模型（默认 sonnet）
  • --self — 测试本技能自身的 SKILL.md（隐含 --skill）
  • --skill / --agent — 提示目标类型以改进场景生成
  • --holistic — 额外生成测试多规则交互的集成场景
  • --coverage — 场景生成后报告规则覆盖情况（已测试与未测试规则）
  • --effort LEVEL — 主题调用强度：low / medium / high（默认 high）
  • --gen-effort LEVEL — 场景生成强度：low / medium / high（默认 medium）
  • --save-reference PATH — 将场景保存到稳定参考目录以构建确定性测试套件
  • --neutral-strategy — delta=0 时的决策：revert（默认，丢弃）、keep（保留）、size（仅当变异响应更短时保留）
  • --no-boundary-check — 禁用三项变异安全防护

变异安全

变异循环包含三项安全防护：frontmatter 保护（拒绝针对 YAML frontmatter 的变异）、语法校验（拒绝会破坏 YAML frontmatter 解析的变异）、有界变异（拒绝替换文本超过原文 2 倍或超出 500 字符的变异）。

性能说明

脚本超时根据工作负载大小（场景数、运行次数、文件长度）动态计算，无需手动调整。作用域变异检查会复用当前内容的基线，仅对目标场景重新评估变异候选，之后再进行全量验证。

触发示例

  • 正向触发：用户要求对 CLAUDE.md 运行合规性测试以检查所有规则是否被遵循 → 直接开始定位文件并执行完整流程。
  • 非触发：用户要求向 ESLint 配置添加新的 lint 规则 → 不使用本技能。
  • 非触发：用户要求协助编写新的 CLAUDE.md 规则 → 不使用本技能（属于编写规则，而非测试现有规则是否被遵循）。

故障排查

  • 场景生成失败：可能是目标文件无可检测规则或结构化段落；确保文件包含清晰结构化的规则。
  • 规则正确但合规性得分低：单次运行模式（--runs 1）易受 LLM 波动影响，可改用 --runs 3 多数投票。
  • 找不到脚本：检查技能安装在预期路径，并对 scripts/ 目录中的脚本运行 chmod +x。

参考指南

  • references/script-reference.md — 全部标志、缓存策略、性能说明
  • references/scenario-format.md — YAML schema 与字段规则
  • assets/report-template.md — 结构化合规性报告格式与后续步骤清单

限制

目标文件需具备清晰结构化的规则（标题、编号条目或带标签的段落）才能生成场景；单次运行结果易受模型波动影响；脚本必须通过 uv run --script 运行。关于收费、价格、平台支持范围等信息暂未提供。