Claude Plugins 官方技能开发框架:Blind Comparator 盲比较代理实战指南

原创2026-09-30 19:11:221,866 阅读
文章标签:AI 插件AI 技能开发工具插件系统人工智能MCP 服务代码评审静态分析

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 一节:

  1. 保持盲态(Stay blind):绝不尝试推断哪个输出来自哪个技能,纯粹依据输出质量评判。
  2. 具体化(Be specific):解释优缺点时必须引用具体实例,避免空泛评价。
  3. 果断(Be decisive):除非两份输出确实等价,否则必须选出胜者。
  4. 输出质量优先(Output quality first):断言得分只作次要依据,首要关注整体任务完成度。
  5. 客观(Be objective):不因风格偏好偏向某个输出,聚焦正确性与完整性。
  6. 解释推理(Explain your reasoning):reasoning 字段必须让读者明白胜者为何胜出。
  7. 处理边界情况(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 裁决机制。若你在技能开发中遇到"改动是否有实际收益"的疑问,不妨在子代理可用时启用这一盲比较流程,让数据与质量说话,而不是让作者偏见说话。

登录后查看全文
claude-plugins-official