Claude Plugins 官方技能开发框架:Blind Comparator 盲比较代理实战指南
Claude Plugins 官方技能开发框架:Blind Comparator 盲比较代理实战指南
导读
本文深入解析 claude-plugins-official 仓库中 skill-creator 插件的 Blind Comparator Agent(盲比较代理)。该代理是技能开发闭环中的"中立裁判":它接收两份未知来源的输出(仅标注为 A 和 B),在完全不知道各自由哪个技能版本产出的前提下,依据统一的评分标准判定谁更好地完成了评测任务,从而消除对特定技能或实现方式的偏见。读完本文,你将掌握盲比较代理的七步评估流程、双维度评分表(内容 Rubric + 结构 Rubric)的设计方法、标准化的 comparison.json 输出格式,以及它与 Grader、Post-hoc Analyzer 两个子代理如何协作形成"比较 → 分析 → 改进"的完整链路。
盲比较系统是 skill-creator 中可选的进阶能力。在 SKILL.md 的 "Advanced: Blind comparison" 一节中明确说明:当用户提出"新版本真的更好吗?"这类需要严格对照的问题时,可以将两份输出交给一个独立代理,不告知其来源,让其仅凭质量评判,之后再分析胜者获胜的原因。该机制要求子代理支持,大多数用户在日常的人工评审循环(human review loop)中并不需要它。
一、盲比较的定位:为什么需要"不知情"的裁判
在技能迭代中,最常见的问题是"改进后的技能是否真的优于旧版本"。如果让编写技能的人自己评价输出,偏见几乎不可避免:作者会天然倾向自己的实现方式、措辞风格和结构偏好。
Blind Comparator 通过信息隔离解决这个问题。根据 comparator.md 对角色(Role)的定义,代理接收两份标注为 A 和 B 的输出,但不知道哪个输出由哪个技能产生,评判完全基于输出质量与任务完成度。这种"盲法"设计借鉴了科学实验中的双盲对照思路,确保比较结果反映的是输出本身的优劣,而非实现路径的差异。
从源码结构看,盲比较是整个评测流水线中的一环:Grader(grader.md)负责逐条断言验证输出是否达标;Blind Comparator 负责在没有断言或断言不充分时,从整体质量维度裁决 A/B 优劣;Post-hoc Analyzer(analyzer.md)则负责在裁决后"解盲",分析胜者为何获胜、败者如何改进。三者输出依次衔接:比较结果 JSON 会作为 analyzer 的输入(comparison_result_path),而比较结果与评分数据最终汇入 benchmark.json 的量化汇总体系。
二、输入参数:盲比较代理收到什么
调用盲比较代理时,通过提示词传入以下四个参数:
| 参数 | 说明 |
|---|---|
output_a_path |
第一个输出文件或目录的路径 |
output_b_path |
第二个输出文件或目录的路径 |
eval_prompt |
最初执行的原始任务/提示词 |
expectations |
需要核验的期望列表(可选,可为空) |
其中 expectations 是可选的。它的作用是为比较提供"硬证据":预先定义的断言(如"输出包含姓名"、"格式为 PDF")可以给出可计数的通过率,但根据文档的定位,断言通过率是次要证据,不作为首要决策因素——因为断言再全面,也无法覆盖输出质量的全部维度(可读性、组织逻辑、专业性等),这正是需要盲比较代理从整体视角补位的原因。
三、七步评估流程
盲比较代理按照 comparator.md 中定义的七个步骤执行完整评估:
Step 1:阅读两份输出。 逐一检查输出 A 和输出 B(文件或目录),记录各自的类型、结构与内容;若输出为目录,需检查其中的所有相关文件。
Step 2:理解任务。 仔细阅读 eval_prompt,明确任务要求什么——应当产出什么?哪些质量维度重要(准确性、完整性、格式)?什么能区分好输出与差输出?
Step 3:生成评估 Rubric。 基于任务生成包含内容维度和结构维度两个方向的评分表(详见下一节),并根据任务类型适配具体标准。
Step 4:逐项评分。 对每个输出,按 Rubric 的每条标准打分(1-5 分制),计算维度总分(Content score、Structure score)与综合总分(两个维度均值换算到 1-10 分制)。
Step 5:核验断言(若提供)。 将每条期望分别对照输出 A 和输出 B,统计各自的通过率,仅作为次要证据使用。
Step 6:判定胜者。 按优先级比较:首要依据是综合 Rubric 得分(内容 + 结构);次要依据是断言通过率;若两者确实相当则宣布 TIE。文档特别强调要果断(Be decisive)——平局应当罕见,即使只是略胜一筹,通常也应该有一个胜者。
Step 7:写出比较结果。 将结果保存为 JSON 文件,保存到指定路径(未指定时默认 comparison.json)。
值得注意的是,这套流程与 grader.md 中"搜索证据 → 判定 PASS/FAIL → 引用证据"的二元裁决思路互补:Grader 给出"哪些断言过了",Blind Comparator 则回答"整体上谁更好、好在哪里"。
四、评分表设计:内容维度与结构维度
盲比较代理的核心工具是一张双维度评分表(Rubric),每个维度包含三条 1-5 分标准。以下两张表来自 comparator.md 的原始定义:
内容 Rubric(输出包含什么):
| 标准 | 1(差) | 3(可接受) | 5(优秀) |
|---|---|---|---|
| Correctness(正确性) | 重大错误 | 轻微错误 | 完全正确 |
| Completeness(完整性) | 缺少关键要素 | 大体完整 | 要素齐备 |
| Accuracy(准确性) | 严重失准 | 轻微失准 | 全程准确 |
结构 Rubric(输出如何组织):
| 标准 | 1(差) | 3(可接受) | 5(优秀) |
|---|---|---|---|
| Organization(组织性) | 杂乱无章 | 组织合理 | 结构清晰、逻辑顺畅 |
| Formatting(格式) | 不一致/损坏 | 大体一致 | 专业、精良 |
| Usability(可用性) | 难以使用 | 费点力气可用 | 易于使用 |
Rubric 不是固定的模板,而应随任务类型适配。文档给出了三种典型适配示例:
- PDF 表单任务 → "字段对齐(Field alignment)"、"文字可读性(Text readability)"、"数据放置(Data placement)"
- 文档生成任务 → "章节结构(Section structure)"、"标题层级(Heading hierarchy)"、"段落流(Paragraph flow)"
- 数据输出任务 → "Schema 正确性(Schema correctness)"、"数据类型(Data types)"、"完整性(Completeness)"
评分计算方式为:内容得分 = 三条内容标准得分的平均值(1-5);结构得分同理;综合总分 = 两个维度得分的平均值,换算到 1-10 分制。换算逻辑可以从标准中的示例值反推:例如内容 4.7、结构 4.3,综合总分为 9.0,即 (4.7 + 4.3) / 2 = 4.5,再乘以 2 映射到 10 分制得到 9.0。
五、输出格式:标准化的 comparison.json
盲比较代理的结果以 JSON 文件落盘,字段结构与 comparator.md 的 "Output Format" 一节及 schemas.md 中 comparison.json 的 schema 定义完全一致。完整结构如下:
{
"winner": "A",
"reasoning": "Output A provides a complete solution with proper formatting and all required fields. Output B is missing the date field and has formatting inconsistencies.",
"rubric": {
"A": {
"content": { "correctness": 5, "completeness": 5, "accuracy": 4 },
"structure": { "organization": 4, "formatting": 5, "usability": 4 },
"content_score": 4.7,
"structure_score": 4.3,
"overall_score": 9.0
},
"B": {
"content": { "correctness": 3, "completeness": 2, "accuracy": 3 },
"structure": { "organization": 3, "formatting": 2, "usability": 3 },
"content_score": 2.7,
"structure_score": 2.7,
"overall_score": 5.4
}
},
"output_quality": {
"A": {
"score": 9,
"strengths": ["Complete solution", "Well-formatted", "All fields present"],
"weaknesses": ["Minor style inconsistency in header"]
},
"B": {
"score": 5,
"strengths": ["Readable output", "Correct basic structure"],
"weaknesses": ["Missing date field", "Formatting inconsistencies", "Partial data extraction"]
}
},
"expectation_results": {
"A": { "passed": 4, "total": 5, "pass_rate": 0.80,
"details": [
{"text": "Output includes name", "passed": true},
{"text": "Output includes date", "passed": true},
{"text": "Format is PDF", "passed": true},
{"text": "Contains signature", "passed": false},
{"text": "Readable text", "passed": true}
]},
"B": { "passed": 3, "total": 5, "pass_rate": 0.60,
"details": [
{"text": "Output includes name", "passed": true},
{"text": "Output includes date", "passed": false},
{"text": "Format is PDF", "passed": true},
{"text": "Contains signature", "passed": false},
{"text": "Readable text", "passed": true}
]}
}
}
各字段的语义如下:
winner:"A"、"B"或"TIE"。reasoning:清晰解释胜者入选(或为何平局)的理由,应具体到可引用的细节,而非笼统表述。rubric:每个输出的结构化评分。content与structure分别记录六条标准得分;content_score/structure_score为各自维度的平均值(1-5);overall_score为换算到 1-10 的综合得分。output_quality:质量总结。score为 1-10 评分(应与rubric的overall_score一致);strengths/weaknesses分别列出优点与问题清单。expectation_results:仅当提供了期望时存在。passed/total/pass_rate(0.0-1.0)为汇总数据,details列出每条期望的单独结果。
若未提供任何期望,则整个 expectation_results 字段必须省略。 这一约定在 schemas.md 的 comparison.json 定义中被再次强调,且该文件同时指出 comparison.json 位于 <grading-dir>/comparison-N.json。
六、行为准则:如何保证裁决公正可信
盲比较代理的可靠性依赖一组明确的行为约束,这些约束直接写进了 comparator.md 的 Guidelines 一节:
- 保持盲态(Stay blind):绝不尝试推断哪个输出来自哪个技能,纯粹依据输出质量评判。
- 具体化(Be specific):解释优缺点时必须引用具体实例,避免空泛评价。
- 果断(Be decisive):除非两份输出确实等价,否则必须选出胜者。
- 输出质量优先(Output quality first):断言得分只作次要依据,首要关注整体任务完成度。
- 客观(Be objective):不因风格偏好偏向某个输出,聚焦正确性与完整性。
- 解释推理(Explain your reasoning):
reasoning字段必须让读者明白胜者为何胜出。 - 处理边界情况(Handle edge cases):两份都失败时选"失败得没那么严重"的那份;两份都优秀时选"略胜一筹"的那份。
这些准则与 Post-hoc Analyzer 的后续分析直接呼应:analyzer 在 analyzer.md 中会读取比较结果 JSON,将"盲态"解除,对比胜者与败者技能的 SKILL.md 及执行转录(transcript),找出胜者强在哪(更清晰的指令、更好的脚本、更全的示例、更好的错误处理)以及败者弱在哪,最终按 instructions / tools / examples / error_handling / structure / references 六个类别给出带优先级(high / medium / low)的改进建议。也就是说,盲比较不仅回答"谁赢了",还为"怎么让输的一方变强"提供了输入。
七、何时使用盲比较:适用场景与前提
根据 SKILL.md 的说明,盲比较是可选机制,需要满足以下前提:
- 场景:需要严格对照两个技能版本(典型提问:"新版本真的更好吗?")。
- 依赖:必须支持子代理(subagents),由独立代理执行比较;在 Claude.ai 等无子代理的环境中应跳过盲比较(SKILL.md 的 "Claude.ai-specific instructions" 一节明确标注 "Blind comparison: Requires subagents. Skip it.")。
- 定位:对大多数用户而言,人工评审循环(draft → test → 用户查看 eval viewer 反馈 → 改进 → 重跑)通常已经足够,盲比较适合追求更严谨结论的场景。
从仓库的评测基础设施看,盲比较并非孤立存在:量化一侧有 Grader 逐条断言打分,汇总一侧有 aggregate_benchmark.py 将各 run 的 grading.json 聚合成含均值、标准差与差值的 benchmark.json,盲比较则补足"整体质量与任务完成度"这一量化指标难以覆盖的维度。三者在 skill-creator 的迭代闭环中各司其职,共同支撑"创建技能 → 评测 → 改进 → 再评测"的循环。
结语
Blind Comparator Agent 用"不知情"这一设计换来了裁决的客观性:它不关心两个输出背后是哪版技能、采用了什么实现路径,只关心谁更好地完成了任务。配合双维度 Rubric、标准化 JSON 输出与明确的边界处理规则,它为技能迭代提供了一个可复现、可审计的 A/B 裁决机制。若你在技能开发中遇到"改动是否有实际收益"的疑问,不妨在子代理可用时启用这一盲比较流程,让数据与质量说话,而不是让作者偏见说话。