SkillEvaluator 架构解析:从 CLI 命令到三层评估框架的设计原理
SkillEvaluator 架构解析:从 CLI 命令到三层评估框架的设计原理
SkillEvaluator 是一个面向 AI 智能体技能(Agent Skills)的三层评估框架,用确定性的质量门禁、语义去重检测和真实智能体实测,回答一个核心问题:你的技能到底安不安全、重不重复、有没有用。本文从 CLI 命令组织入手,带你读懂它从一条命令到三层评估流水线的完整设计原理。
🧩 架构总览:一个入口,三层流水线
SkillEvaluator 的架构可以用一句话概括:所有能力都收敛到一个 CLI,再按 Tier 1 / Tier 2 / Tier 3 三层流水线逐级深入——静态验证管"合不合格",语义去重管"重不重复",实测评估管"有没有用"。
CLI 入口基于 click 框架搭建,顶层定义为一个命令组:
- 命令组与版本选项:cli.py
- 三层子命令的挂载:cli.py
- 分层工作流的编排核心:tier_workflows.py
命令树分两类:
| 类型 | 代表命令 | 适用场景 |
|---|---|---|
| 分层子命令 | 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 分) |
值得注意的两个设计点:
- LLM 是"可插拔增强"而非必需项。配置了 LLM 提供方后,Tier 1 会自动追加 LLM 评审打分(tier_workflows.py);没有配置时静态检查照常运行,只是把 LLM 阶段标记为
skipped并写入报告,不会硬失败。 - 每个阶段都有独立状态。
_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 列是技能路径,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 开始,按需逐层加深,就是它建议的路径。
