Hermes SkillEval

面向 AI 编程 Agent 的技能路由评测、难负样本训练与发布门禁系统。

Hermes SkillEval 解决一个具体问题：当 Claude Code、Codex、Cursor 一类 Agent 拥有越来越多相似的 SKILL.md 技能时，如何选中正确技能，同时识别“语义相关但 职责错误”的近邻技能，并在回归进入默认路由器前阻止发布。

30 秒总览 · 核心实现 · Router V2 · 结果 · 限制 · 快速开始 · 证据

30 秒理解项目

关键量化结果

Router V2 pilot-002 复用了 pilot-001 冻结的 A/B/C 模型快照，未重新训练，完成了 唯一一次预注册 held-out evaluation attempt。下面是决策所使用的 Arm A 与 Arm C 配对结果：

Recall@5、MRR、NDCG@5、Negative Hit Rate@5 与 p95 latency 的预注册门限均通过， 因此 pilot evaluation conclusion 是 ROUTER_V2_PILOT_IMPROVED。完整逐 seed 指标、paired wins/losses 与 failure slices 见 pilot-002 result report。

先看限制

• 这是 MODEL_ONLY_PILOT：human_reviewer_count=0、 independent_human_review=false、model_correlation_risk=true。两次模型审核和 模型裁决不等于独立人类标注。
• 最终评测只有 16 个 held-out positive tasks 和 9 个 supported negative labels； 这是自建 Hermes-style benchmark，不是公开标准 benchmark、排行榜或 SOTA 证据。
• Arm C 虽然 top-1 指标改善，但每个 seed 仍有 5–7/9 个 Negative Hit@5，且 各有 7/16 个任务触发至少一个诊断 flag；结果不能解释为“混淆问题已经解决”。
• pilot-002 只进行一次预注册评测，没有 best-seed selection、重跑或事后调参； blind-v2 未运行，release_eligible=false，默认决策仍为 KEEP_BASELINE。
• 冻结的 canonical pilot manifest 缺少四个 model-only truth fields；仓库保留原始 manifest，并通过自封存的 truth-erratum.json 补充事实块，而不是改写历史。
• 模型 checkpoint、embedding cache 和远端机器隐私信息不提交到仓库。本项目不是 SaaS、runtime MCP router、自动 merge/release 系统，也没有 Marketplace 发布声明。

我实现的算法与工程模块

Router V2 如何训练

数据与审核

• 冻结基础模型：sentence-transformers/all-MiniLM-L6-v2，固定 revision 1110a243fdf4706b3f48f1d95db1a4f5529b4d41。
• 训练输入：64 个 train positives + 52 个 admitted hard negatives，共 116 对。
• 混淆挖掘：在冻结的 16-skill index 上运行单线程 CPU baseline；候选满足 rank <= 5 或 gold_score - candidate_score <= 0.05 才可能进入审核。
• 审核：新候选经过两次隔离的模型 pass 与一次模型 adjudication；disputed、 ambiguous、unsupported、easy negative 和 held-out rows 全部排除在训练外。
• 数据隔离：held-out labels 在训练前单独封存，不进入 mining、sampler、训练或 hyperparameter decisions。

训练配置

flowchart LR
    source["冻结 source snapshot<br/>64 positives / 16 skills"]
    mine["MiniLM confusion mining<br/>rank-or-margin rule"]
    review["2 model passes + adjudication<br/>MODEL_ONLY_PILOT"]
    package["Fail-closed package<br/>64 positives + 52 hard negatives"]
    train["A / B / C × 3 seeds<br/>MNRL + ContrastiveLoss"]
    eval["一次预注册 held-out evaluation<br/>16 positives / 9 negatives"]
    decision["Pilot improved<br/>Release: KEEP_BASELINE"]

    source --> mine --> review --> package --> train --> eval --> decision

为什么需要发布门禁

项目不只报告“更高的 Recall”。Phase 16 的 blind-validation 捕获过一个具体回归： fine-tuned candidate 保留了 gold skill，却新增选择了错误的 negative skill。

精确 route diff 见 route-diffs.jsonl。这说明 项目的目标不是为模型改善找理由，而是让候选模型在证据不足或负样本风险变坏时 无法升级。

快速开始

git clone https://github.com/Raidriar7170/hermes-skilleval.git
cd hermes-skilleval
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

skilleval github-action-gate \
  --skill-path examples/github-action/skills \
  --benchmark-path examples/github-action/benchmark \
  --min-recall-at-k 1.0 \
  --max-negative-hit-rate 0.0 \
  --output-dir "${TMPDIR:-/tmp}/skilleval-gate"

pytest -q

示例 gate 预期返回 ALLOW_MERGE。完整 CLI 说明见 docs/usage.md。

作为 GitHub Action 使用

消费方仓库只需提供自己的 skills/ 与 benchmark/：

name: SkillEval Gate

on:
  pull_request:
  workflow_dispatch:

jobs:
  skilleval:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - uses: Raidriar7170/hermes-skilleval@v0.3.0
        with:
          skill-path: skills
          benchmark-path: benchmark
          min-recall-at-k: "1.0"
          max-negative-hit-rate: "0.0"
          upload-artifacts: "true"

该 Action 运行 skilleval github-action-gate，输出 GitHub Actions step summary、 gate report、CI summary 与结果 artifacts，不需要 GitHub API token。它只报告 ALLOW_MERGE 或 BLOCK_MERGE，不会自动批准或合并 PR。

系统架构

flowchart TD
    corpus["SKILL.md libraries<br/>gold / negative benchmark"]
    index["Parser + portable skill index"]
    routers["Router families<br/>keyword / hybrid / embedding / gated / cross-encoder"]
    verifier["Negative controls<br/>confusion mining + verification"]
    evidence["Metrics + JSONL traces<br/>Markdown + dashboard"]
    gate["CI / release gate<br/>ALLOW, BLOCK, KEEP_BASELINE"]

    corpus --> index --> routers --> verifier --> evidence --> gate

核心原则：

• Offline-first： keyword、hybrid 与 hashing embedding 默认无需 LLM API。
• Negative-aware： Recall 与 Negative Hit Rate 同时进入报告和门禁。
• Evidence-first： 关键产物记录 source hash、config、seed、模型 lineage 与 attempt 状态，避免只保留最终分数。
• Fail-closed： 数据、模型、held-out 或 gate contract 不完整时停止，而不是 用默认值继续。

Dashboard

打开已提交的静态 Dashboard 可按 run 过滤、检查失败样本、查看排名和原始 JSON 证据。

项目规模与技术栈

证据与复现入口

发布状态与边界

v0.3.0 是当前已发布版本，记录 Stage 2 real Codex pilot evidence-chain closeout；其最终状态为 REVIEW_REQUIRED / KEEP_BASELINE，不是 benchmark PASS、 性能提升或 router promotion。Router V2 pilot-002 是后续内部证据，不属于 v0.3.0 发布内容，也没有改变默认路由器。

历史实验脉络见 docs/experiment-timeline.md，当前发布 说明见 docs/release-notes/v0.3.0.md。

License

MIT License. See LICENSE.