用 DeerFlow skill-creator 的 Blind Comparator Agent 进行无偏 Skill A/B 评测:完整协议与 JSON 输出规范
用 DeerFlow skill-creator 的 Blind Comparator Agent 进行无偏 Skill A/B 评测:完整协议与 JSON 输出规范
在 skill-creator 的迭代评测流程(draft → test → grade → review → improve)中,当用户提出"新版本是否真的更好"这类问题、而纯人工判断又不够有说服力时,需要一种不受 skill 身份先验干扰的对照评测手段。本文聚焦 skill-creator 内置的 Blind Comparator Agent(盲比较智能体),完整讲解其设计动机、输入参数、七步比较流程、双维度评分准则、结构化 JSON 输出协议,以及与 Grader、Post-hoc Analyzer 协同构成的无偏评测闭环,帮助你直接上手把"盲比较"接入自己的 Skill 质量评估工作流。
一、什么是 Blind Comparator:为什么"盲"是公平的前提
Blind Comparator 承担的任务是:在不知道两份输出分别由哪个 Skill 产生的前提下,判断哪一份更好地完成了评测任务(eval task)。它收到的是分别标记为 A 和 B 的两份输出,而不是"A 是旧版 Skill 的产物、B 是新版 Skill 的产物"这类带身份标签的输入。
这种"盲"设计是为了消除系统性偏差:如果裁判预先知道某份输出出自一个"被寄予厚望"的 Skill,或出自一个有历史劣迹的旧版本,就很容易下意识地迎合或贬低它。Skill Creator 的高级盲比较流程在 SKILL.md 中给出的用法,恰好命中这一场景:
当你想在两个 Skill 版本之间做更严格的比较时(比如用户问"新版本真的更好吗?"),盲比较系统把两份输出交给一个独立的智能体,不告诉它哪份是哪份,让它纯粹基于输出质量判定胜负,然后再分析获胜方赢在哪里。
其判定原则因此被严格限定为输出质量与任务完成度,与产生输出的 Skill、方法或风格偏好完全无关。从源码结构看,它属于 skill-creator 的三位评测专用子智能体之一,另两位分别是对应的 grader.md(断言评估) 与 analyzer.md(事后再揭盲并分析成因)。
需要说明的是,盲比较在 skill-creator 中属于进阶且可选的路径:它依赖子智能体能力,且如 SKILL.md 所强调,"大多数用户并不需要它,人工 review 循环通常已经足够"。在无子智能体环境的 Claude.ai 场景中该功能被明确标注为跳过项。
二、输入参数:Comparator 从 prompt 中能拿到什么
启动盲比较时,以下参数会注入 comparator 的 prompt:
| 参数 | 含义 |
|---|---|
output_a_path |
第一份输出文件或目录的路径 |
output_b_path |
第二份输出文件或目录的路径 |
eval_prompt |
被执行的原始任务/提示词 |
expectations |
需要核验的期望列表(可选,可能为空) |
注意这里 Comparator 不接收任何与 Skill 身份、路径、脚本有关的参数。输出对象既可以是单个文件,也可以是整个输出目录——当输出为目录时,需要检查其中所有相关文件。
三、七步比较流程:从读取输出到落盘结果
Comparator 的工作被拆解为七个明确步骤,每一步都有独立的产出目标:
Step 1:阅读两份输出
逐一检视输出 A 与输出 B,记录各自类型、结构与内容;若为目录则检视内部全部相关文件。此阶段只做客观盘点,不下判断。
Step 2:理解任务
仔细阅读 eval_prompt,明确三件事:
- 任务应当产出什么;
- 哪些质量维度重要(准确性、完整性、格式);
- 什么样的输出算好、什么样的算差。
Step 3:生成评估准则(Rubric)
针对任务生成双维度 Rubric(详见下一节)。Rubric 的具体判据需随任务类型适配,文档给出了三类示例:
- PDF 表单任务 → "字段对齐"、"文本可读性"、"数据摆放位置";
- 文档任务 → "章节结构"、"标题层级"、"段落流畅度";
- 数据输出任务 → "Schema 正确性"、"数据类型"、"完整性"。
Step 4:逐输出对照 Rubric 评分
对 A 与 B 分别执行:逐准则打 1–5 分 → 计算各维度小计(Content Score、Structure Score)→ 计算总分(两个维度平均后折算到 1–10 区间)。
Step 5:核验断言(若提供)
若提供了 expectations,则逐条对照输出 A、输出 B 进行核验,统计各自通过率。断言通过率只作为次要证据,不作为首要决策依据——这一点在判定优先级中会被再次强调。
Step 6:判定胜者
按优先级对比 A 与 B:
- 首要依据:Rubric 综合分(内容 + 结构);
- 次要依据:断言通过率(若适用);
- 平局裁决:若确实旗鼓相当,宣判
TIE。
文档对"果断性"有明确要求:平局应是罕见情况——即使只是微弱优势,通常也有一方更好。
Step 7:写出比较结果
将结果保存为指定路径的 JSON 文件(未指定时默认写为 comparison.json)。结合 schemas.md 的约定,其规范落盘位置为 <grading-dir>/comparison-N.json(N 为评测编号)。
四、双维度评分准则与计分换算规则
Comparator 的核心评估框架是两个正交维度。**内容维度(Content Rubric)**衡量"输出里有什么":
| 准则 | 1(差) | 3(可接受) | 5(优秀) |
|---|---|---|---|
| Correctness(正确性) | 重大错误 | 少量错误 | 完全正确 |
| Completeness(完整性) | 缺失关键要素 | 大体完整 | 全部要素齐备 |
| Accuracy(准确性) | 明显不准确 | 少量不准确 | 全程准确 |
**结构维度(Structure Rubric)**衡量"输出如何组织":
| 准则 | 1(差) | 3(可接受) | 5(优秀) |
|---|---|---|---|
| Organization(组织) | 杂乱无章 | 组织合理 | 清晰、有逻辑的结构 |
| Formatting(格式) | 不一致/损坏 | 基本一致 | 专业、精良 |
| Usability(可用性) | 难以使用 | 需费力才能用 | 开箱即用 |
两个维度都可以(且应当)针对具体任务替换或增补判据。计分与折算规则为:
- Content Score = content 三项准则分平均值(1–5);
- Structure Score = structure 三项准则分平均值(1–5);
- Overall Score = 两个维度平均值 ×2,折算到 1–10。
以文档示例校验这套换算:输出 A 的 content 为 (5+5+4)/3≈4.7,structure 为 (4+5+4)/3≈4.3,Overall=(4.7+4.3)/2×2=9.0,与示例 JSON 完全吻合;输出 B 的 content 为 (3+2+3)/3≈2.7,structure 同约为 2.7,Overall=2.7×2=5.4,同样吻合。
五、输出协议:comparison.json 的完整结构与字段语义
Comparator 的结果必须写入严格结构化的 JSON,完整范例如下:
{
"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:内容准则分(correctness、completeness、accuracy);
- structure:结构准则分(organization、formatting、usability);
- content_score:内容准则均值(1–5);
- structure_score:结构准则均值(1–5);
- overall_score:折算到 1–10 的综合分;
- output_quality:概要质量评估;
- score:1–10 评分(应当与 rubric 的 overall_score 一致);
- strengths:优点列表;
- weaknesses:缺陷列表;
- expectation_results:仅当提供了 expectations 时才出现,未提供时应整体省略该字段;
- passed:通过的断言数;total:断言总数;
- pass_rate:通过比例(0.0–1.0);
- details:逐条断言的核验明细。
该 JSON 结构同时被 references/schemas.md 收录为 skill-creator 的正式数据契约之一,与 evals.json、grading.json、benchmark.json、analysis.json 并列,说明盲比较的结果是评测管线中的一等公民数据,可供后续分析器与可视化环节直接消费。
六、从 Grader 到 Analyzer:盲比较在评测闭环中的生态位
理解 Blind Comparator 的最佳方式是看清它在整套评测数据流中的上下游关系:
- 上游——Grader(grader.md):负责逐条核验
expectations,产出grading.json(字段必须使用text/passed/evidence,viewer 依赖这些精确命名)。Grader 给出的断言通过率正是 Comparator Step 5 中"次要证据"的来源。 - 中游——Blind Comparator:对两份输出做整体质量裁决,产出
comparison.json,把"谁赢了"这一结论客观化。 - 下游——Post-hoc Analyzer(analyzer.md):Comparator 判定胜者之后,Analyzer 负责"揭盲"(unblind)——读取 winning/losing skill 的 SKILL.md 与执行 transcript,反推"胜者为何获胜、败者如何改进",输出
analysis.json(含winner_strengths、loser_weaknesses、按instructions/tools/examples/error_handling等类别组织并标注 high/medium/low 优先级的improvement_suggestions)。
这条"盲判胜负 → 揭盲找根因 → 落成改进建议"的链路是 skill-creator 对 Skill 进行严格版本验证的完整形态。同时值得注意的是,analyzer.md 中还承担另一项独立职责——benchmark 结果分析(面向 benchmark.json 的多 run 模式挖掘,如恒过/恒失败的区分度问题、高方差 eval 稳定性、时间与 token 开销),二者定位不同,不应混淆。
七、在 DeerFlow / Skill Creator 工作流中的落地姿势
要在实际评测中调用 Blind Comparator,建议遵循 SKILL.md 的既有约定:
- 阅读 agents/comparator.md 获得完整指令后,spawn 一个独立子智能体执行盲比较;
winner_skill/loser_skill身份信息只在后续给 Analyzer 时补上,绝不给 Comparator。 - 对比的两份输出来自同一评测用例(eval)下的两种配置——典型如"新版 Skill vs 旧版 Skill 快照"(基线)。SKILL.md 建议改进既有 Skill 时先
cp -r快照旧版再让基线子智能体运行,保证两份输出天然可盲比。 - 结果文件按 workspace 约定(
<skill-name>-workspace/iteration-N/eval-<ID>/...)与各 run 的grading.json、timing.json相邻存放,命名遵循<grading-dir>/comparison-N.json。 - 若运行于 DeerFlow 沙箱环境,所有 Skill 文件操作都应走
skill_manage工具(create/edit/patch/write_file 等),评测 workspace 文件则可正常落在/mnt/user-data/outputs/或/mnt/user-data/workspace/,详见 SKILL.md 的 DeerFlow Environment 一节。
八、判定纪律与边界情况:写 reasoning 前必须遵守的规则
Comparator 的行为约束集中体现了"客观、可解释、不留情面"的评测纪律:
- 保持盲态(Stay blind):绝不试图推断哪份输出出自哪个 Skill,纯粹按输出质量评判;
- 给出具体证据(Be specific):解释优缺点时必须引用具体例子,而非空泛评价;
- 果断(Be decisive):除非两份输出真正等价,否则必须选出胜者;
- 输出质量优先(Output quality first):断言得分永远次于整体任务完成度;
- 客观(Be objective):不因风格偏好偏向某方,聚焦正确性与完整性;
- 讲清理由(Explain your reasoning):reasoning 字段要让读者一眼看懂选胜者的逻辑;
- 处理边界(Handle edge cases):双方都失败时选"失败得没那么惨"的一方;双方都优秀时选"略胜一筹"的一方。
小结
Blind Comparator Agent 是 skill-creator 在"人类 review + 断言评分"之外提供的第三重质量保障:它通过屏蔽 Skill 身份来消除先验偏差,用可审计的双维度 Rubric 与结构化 JSON 把"哪份输出更好"变成可复现、可存档、可交接给下游分析器的判定结论。当你需要在两个 Skill 版本之间做出严格取舍时,按本文给出的输入约定、七步流程与 comparison.json 协议执行一次盲比较,再交给 Post-hoc Analyzer 揭盲归因,即可把一次主观的"哪个更好"升级为有据可循的 Skill 改进闭环。