SkillEvaluator 架构解析:从 CLI 命令到三层评估框架的设计原理

原创2026-11-12 12:23:151,450 阅读

SkillEvaluator 架构解析:从 CLI 命令到三层评估框架的设计原理

SkillEvaluator 是一个面向 AI 智能体技能(Agent Skills)的三层评估框架,用确定性的质量门禁、语义去重检测和真实智能体实测,回答一个核心问题:你的技能到底安不安全、重不重复、有没有用。本文从 CLI 命令组织入手,带你读懂它从一条命令到三层评估流水线的完整设计原理。

🧩 架构总览:一个入口,三层流水线

SkillEvaluator 的架构可以用一句话概括:所有能力都收敛到一个 CLI,再按 Tier 1 / Tier 2 / Tier 3 三层流水线逐级深入——静态验证管"合不合格",语义去重管"重不重复",实测评估管"有没有用"。

CLI 入口基于 click 框架搭建,顶层定义为一个命令组:

命令树分两类:

类型 代表命令 适用场景
分层子命令 skillevaluator tier1 PATH 只想跑某一层
快捷命令 quality-check、security-scan、pii-scan、similarity-check、rubric-eval 单点检查,无需记忆分层
一站式命令 skillevaluator validate PATH 默认跑完全部三层

这种"分层 + 平铺"的双轨设计,让新手可以从 quality-check 快速上手,让 CI 场景可以用 validate 一条命令跑完全流程。

🔍 Tier 1 静态验证:不联网就能跑的质量门禁

Tier 1 回答的问题是:这个技能安全吗、格式规范吗? 它的全部检查都是确定性的,默认无需任何 API key 即可离线运行。

默认开启的检查项定义在 tier1/commands.py:

检查项 关注点
schema / version 目录结构与元数据是否合规
security / code-integrity 危险命令、密钥泄露、脚本完整性
pii / license 隐私信息与许可证合规
unicode / lint Unicode 走私、Markdown 卫生
quality 内容质量打分(默认通过线 70 分)

值得注意的两个设计点:

  1. LLM 是"可插拔增强"而非必需项。配置了 LLM 提供方后,Tier 1 会自动追加 LLM 评审打分(tier_workflows.py);没有配置时静态检查照常运行,只是把 LLM 阶段标记为 skipped 并写入报告,不会硬失败。
  2. 每个阶段都有独立状态。_stage 函数把结果聚合成 passed / failed / incomplete,再由 _record_scope 写入每个结果的 metadata(tier_workflows.py),保证"哪一步失败、哪一步被跳过"在报告中一目了然。

🔁 Tier 2 语义去重:用 Embedding 找出"重复劳动"

Tier 2 回答:技能内部或技能之间是否存在语义重复? 重复的指导会让智能体上下文膨胀、行为漂移,这是纯文本规则查不出的问题。

它分两个阶段(tier_workflows.py):

  • skill 内去重:context-optimization-check,对单个技能内部做 embedding 相似度分析,定位可以合并的重复段落;
  • 跨技能去重:similarity-check --catalog,把技能与一个技能目录(catalog)做对比,发现"这个技能是不是已有的翻版"。

设计上的一个细节:跨技能对比会先本地校验 catalog 的合法性(格式、链接、兼容性),通过后才发起付费的模型调用——避免用无效输入浪费配额。

🚀 Tier 3 实测评估:用"带技能 vs 不带技能"的差值说话

Tier 3 回答前三层都回答不了的问题:技能真的让智能体变得更好吗?

它的工作方式是配对实验:让真实智能体(codex、claude-code、opencode)在 Harbor 沙箱里对同一组评估任务跑两遍——装技能(with-skill arm)和不装技能(baseline arm),然后对比两次表现。核心指标有:

  • 五个维度评分:Security、Correctness、Discoverability、Effectiveness、Efficiency;
  • Skill Lift:带技能分数减去基线分数的提升值,例如"47% → 92%(+45 分)";
  • pass@k:多次尝试的可靠性,与维度分数分开报告。

Tier 3 的实现集中在 tier3/eval_core/(评估逻辑、声明式检查、LLM 评审)和 tier3/harbor/(沙箱环境、采集器、指标计算),是三层中基础设施最重的一层,也是唯一需要 Docker 或其他沙箱的一层。

🔗 三层如何被 validate 命令串起来

skillevaluator validate PATH 默认依次执行三层,但三层之间没有硬依赖——每一层都是独立入口,可以单独运行,也可以按需提供凭证。分层依赖关系大致是:

层级 必需凭证/环境 门禁角色
Tier 1 无(确定性检查);LLM 评审需 provider key 唯一能阻断 CI 的层级
Tier 2 Embedding + Chat LLM provider 建议性(advisory)
Tier 3 智能体凭证 + Docker/本地/云沙箱 建议性(advisory)

这一策略体现在 CI 集成中:Tier 1 是质量门禁,Tier 2 / Tier 3 是参考证据。配套的 CI 模板与报告发布脚本见 ci/templates/ 和 publish-skill-reports.yml。

📊 从结果到报告:CI 里长什么样

无论跑哪一层,最终都汇入统一的报告体系(CLI、JSON、HTML、Markdown),结果模型与命名规则在 models/result.py 和 reporting/naming.py 中定义。在仓库 CI 中,扫描结果会以技能质量分和门禁判定呈现:

SkillEvaluator CI 报告展示技能扫描结果、质量分与错误警告统计

上图中,skillevaluator 列是技能路径,Quality 是内容质量分,Errors/Warnings 是静态检查发现的问题数,点击 Report 可查看完整明细。

🗺️ 关键路径速查:三分钟看懂代码布局

想了解什么 看哪里
全部 CLI 命令与参数 cli.py
分层工作流编排与阶段状态 tier_workflows.py
Tier 1 检查项清单与执行 tier1/commands.py
Tier 1 各校验器实现 validators/
Tier 2 去重逻辑 tier2/commands.py、deduplication/
Tier 3 评估核心与沙箱 tier3/eval_core/、tier3/harbor/
报告生成(HTML/JSON/SARIF) reporting/
官方文档 docs/

总结

SkillEvaluator 的设计哲学很清晰:把"评估一个技能"拆成三个互不依赖的问题,用一条 CLI 统一收敛。确定性优先(Tier 1 离线可跑)、语义补充(Tier 2 用 embedding 找重复)、实测收尾(Tier 3 用差值量化价值),每层结果都以结构化状态记录并汇入同一报告体系。如果你要给自己的智能体技能加上质量保障,从一条 quality-check 开始,按需逐层加深,就是它建议的路径。

登录后查看全文
SkillEvaluator