skillhone-evaluation

SkillHone Evaluation 是 SkillHone 体系中的技能评估组件，用途是运行评估并诊断结果，从而为技能改进决策提供依据。

用途

该工具用于评估一个技能、运行 probe/test/PR-val、检查某个 PR 是否导致质量回退、比较两个版本等场景。它把评估器定位为一个“测试框架（harness）”，而不只是打分器：在私有任务上运行技能，并留下结构化的证据轨迹。

评估框架模型

输入：一个技能检出目录，加上一个评估仓库，其中包含数据集、验证逻辑、任务契约，以及可选的编译器/审计辅助工具。
执行：每个评估项在隔离的求解工作目录中运行。求解器可以创建文件、调用脚本并写出所需产物。
验证：评估仓库的验证器对产出的答案打分，并可调用任务本地的校验器、编译器、解析器、渲染器或审计辅助工具。
输出 JSON：聚合分数，加上脱敏的逐项轨迹摘要。
工作目录证据：trajectory.jsonl、产出的产物，以及类似 stderr 的信号，用于解释分数无法说明的失败原因。

这种分离很重要：低分可能来自技能指令薄弱，也可能来自文件缺失、工具崩溃、编译产物无效、验证规则过严或基础设施错误。评估工作的关键是把失败映射到正确的框架层级。

在 Forgejo 支持的仓库上，status.py 是 PR 验证或合并决策前的只读上下文检查：

python3 ~/.skillhone/skills/skillhone/scripts/status.py

核心能力：eval.py

Probe（快速迭代信号）：

python3 ~/.skillhone/skills/skillhone/scripts/eval.py \
  --skill-dir /path/to/skill --eval-dir /path/to/eval-repo \
  --split probe --output _data/probe_result.json

Test（最终基准，迭代期间绝不运行）：

python3 ~/.skillhone/skills/skillhone/scripts/eval.py \
  --skill-dir /path/to/skill --eval-dir /path/to/eval-repo \
  --split test --output test_result.json

输出 JSON 包含一个 "workdir" 字段，指向求解器工作目录（例如 /data/tmp/eval_agent_xyz/），其中含有 trajectory.jsonl 文件和产出的产物，便于深入诊断。

子代理

trajectory-analyzer：读取 workdir/work_<uid>/trajectory.jsonl 文件，诊断工具错误（速率限制、错误的工具调用、脚本崩溃）。输出脱敏的 _data/trajectory_diagnosis.json，可安全分享给改进器。
pr-quality-reviewer：技能 PR 的合并门禁——运行静态检查与评分量表打分，发布 PR 评论，返回 APPROVE/REQUEST_CHANGES。

轨迹诊断

probe_result.json 记录了分数和部分错误类别，但只是证据轨迹的顶层，无法完全解释运行时行为，例如：Wikipedia API 速率限制（HTTP 429/403）；代理直接调用 web_search 而不是 Bash("python3 scripts/web_search.py ...")；脚本崩溃（退出码 1 并带 traceback）；求解器从未写出所需产物；求解器把文件写到了错误位置。

trajectory-analyzer 子代理通过读取原始求解器日志来填补这一空白。它的输出区分基础设施故障（修复脚本/配置）与技能故障（修复 SKILL.md）。这一区分对避免浪费迭代至关重要。

编译器反馈诊断

有些产物任务类似编译器：Mermaid、LaTeX、TypeScript、Python 测试、SQL 解析器、JSON/YAML schema 校验器、浏览器渲染器等会产生可操作的 stderr 或诊断信息。不要把这些失败简单归为 wrong_answer。

当失败轨迹产出了产物时，从 workdir 字段检查求解器工作目录，并对该产物运行任务本地的编译器、校验器、渲染器或审计辅助工具。优先使用评估仓库自带或在其 README/契约中描述的命令与辅助工具；若不存在，则使用该产物类型的标准本地编译器。只捕获简洁、非金标准的诊断摘要：使用的编译器/解析器命令；首个错误行及位置（如有）；失败的规则名或失败的分数键（如有）；产物级模式，例如 "invalid Mermaid subgraph syntax" 或 "missing answer file"。

将其写为 _data/compiler_diagnosis.json，或并入现有诊断文件。当其中只包含错误消息、失败分数名和识别语法类别所需的产物片段时，可安全分享给改进器；不要包含金标准答案或完整评估问题。

如果任务本地验证器已暴露详细的失败分数键，请保留这些名称。它们通常比改写的自然语言摘要更好的改进信号。

解读分数

字段含义：score 为通过率（0.0–1.0）；avg_duration_s 为效率，分数持平而耗时上升意味着循环/浪费；traces[].error 为 "hard timeout"、"agent_process_error" 或空；workdir 为求解器轨迹路径，用于深入分析。

决策阈值：≥ +0.02 为真实改进；±0.02 为噪声，不要声称改进；≤ −0.04 为回退，应回滚。

分数来源

始终标注产生分数的具体框架运行。在一次完整的 SkillHone 运行中可能有多个有效分数：基线 probe、迭代 probe、PR 验证，以及主代理退出后的最终 driver 重打分。它们可能因使用不同的技能检出、重新生成的评估数据或输出路径而不同。

在撰写 issue、PR 评论、wiki 观察或用户摘要时，用文字引用分数来源：split、输出 JSON 路径（如有）、workdir（如有），以及它是内部迭代分数还是最终框架分数。不要在不说明来源的情况下把多个分数合并成一个数字。

Split 与数据可见性

probe：迭代信号，编排器可见（脱敏轨迹）。
pr_val：PR 合并门禁，编排器可见（仅聚合）。
test：最终基准，仅编排器可见，迭代期间绝不使用。

约束

迭代期间绝不运行 test——它会污染最终基准。
绝不把金标准答案或完整问题转发给改进器。
绝不把评估仓库路径传给正在迭代的代理。
trajectory_diagnosis.json 完全脱敏（仅 uid + 计数）——可安全分享。

参考

references/scoring.md——错误类别目录、匹配规则、接近但未计分的情况。