DeerFlow skill-creator 的 Grader Agent：一套面向技能评测的证据式评分协议

DeerFlow skill-creator 的 Grader Agent一套面向技能评测的证据式评分协议【免费下载链接】deer-flowAn open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.项目地址: https://gitcode.com/GitHub_Trending/de/deer-flowDeerFlow 仓库内置的skill-creator公共技能提供了一条起草技能 → 运行测试 → 量化评分 → 迭代改进的完整评测闭环其中skills/public/skill-creator/agents/grader.md定义了闭环里的评分器Grader Agent它负责逐条断言判分、抽取并核验执行输出中的隐含声明、并把执行指标与耗时数据汇总成结构化的grading.json。读完本文你将掌握 Grader 的完整工作流程、PASS/FAIL 判定标准、grading.json的每一类字段语义以及下游的aggregate_benchmark.py与 eval viewer 是如何消费这份评分产物的。Grader 在技能评测流水线中的位置skill-creator的核心循环由 SKILL.md 定义确定意图并起草 SKILL.md → 并行 spawn 带技能与基线两类子代理执行测试用例 → 打分Grade→ 聚合基准Aggregate→ 启动评测查看器viewer收集人工反馈 → 根据反馈改写技能并进入下一轮迭代。Grader 正是在打分这一步被调度的。SKILL.md 的 Step 4 明确要求为每次运行 spawn 一个 grader 子代理或内联评分该子代理读取 agents/grader.md把每条断言assertion对照输出逐一评估结果保存到每个运行目录run directory下的grading.jsongrading.json的expectations数组必须使用text、passed、evidence三个字段名而不是name/met/details之类的变体——评测查看器依赖这些精确的字段名。skill-creator的技能目录结构如下grader 所在的agents/目录存放的是各专职子代理的指令文档skill-creator/ ├── SKILL.md ├── agents/ │ ├── analyzer.md # 事后分析器分析盲评中赢家为何胜出 │ ├── comparator.md # 盲测对比器对两份输出做匿名 A/B 比较 │ └── grader.md # 评分器对照断言给输出判分 ├── references/ │ └── schemas.md # evals.json / grading.json 等 JSON 结构定义 ├── scripts/ │ └── aggregate_benchmark.py # 聚合 grading.json 生成 benchmark 统计 └── eval-viewer/ └── generate_review.py # 生成人工评审 HTML读取 grading.jsonGrader 与 analyzer.md、comparator.md 是三种不同角色后两者用于可选的盲测 A/B 对比场景而 grader 是每轮迭代必跑的量化评分环节。角色定义与输入参数grader.md 开篇即定义了 Grader 的双重职责The Grader reviews a transcript and output files, then determines whether each expectation passes or fails. Provide clear evidence for each judgment.You have two jobs: grade the outputs, and critique the evals themselves.第一份工作是给输出判分第二份工作是反向批判评测集本身。文档特别强调一个薄弱断言上的满分比没有分更糟——它制造虚假的信心。当发现某条断言过于容易满足trivially satisfied或某个重要结果根本没有任何断言覆盖时Grader 必须指出来。这一设计使评分产物不仅是成绩单还是评测集自身的改进信号。Grader 从 prompt 中接收三个输入参数参数类型说明expectations字符串列表待评估的断言集合来自 schemas.md 中evals.json的expectations字段transcript_path路径执行过程转录文件markdown记录了任务 prompt、执行步骤与最终结果outputs_dir目录执行器executor产出的输出文件目录八步评分流程Grader 的 Process 部分给出八个步骤按顺序执行。下面逐步说明并标注每一步的产物落点。Step 1通读转录完整读取transcript_path指向的转录文件记录三件事eval prompt原始任务、执行步骤、最终结果同时识别转录中记载的任何问题或错误。转录是执行器声称做了什么的唯一过程证据但 Grader 并不止步于此——后面会看到它对转录保持有保留的信任。Step 2检查输出文件列出outputs_dir中的全部文件读取/检查每条断言相关的文件。文档明确要求如果输出不是纯文本使用 prompt 中提供的检查工具直接查看真实文件不要只依赖转录里对产物的转述记录内容、结构与质量。这是证据式评分的关键设计断言是否成立最终由产物文件本身裁决而非由执行器的自述裁决。Step 3逐条评估断言对每一条 expectation 执行三步搜寻证据——在转录和输出文件中查找支持或反驳该断言的内容判定结论PASS有明确证据证明断言为真且证据反映的是真正的任务完成而非表面合规not just surface-level complianceFAIL没有证据、证据与断言矛盾、或证据是表面的——典型例子是文件名正确但内容为空或错误引用证据——直接引用具体文本或描述发现的内容写入evidence字段。Step 4抽取并核验隐含声明Claims在预定义断言之外Grader 还要从转录和输出中主动抽取隐含声明并逐一核验事实声明factual如该表单有 12 个字段——可对照输出文件核实过程声明process如使用 pypdf 填写了表单——可从转录中核实质量声明quality如所有字段都正确填写了——需评估该声明是否站得住脚。对于无法用现有信息核验的声明必须显式标记verified: false或标注为 unverifiable。这一步的价值在于捕获预定义断言可能漏掉的缺口——执行器输出中说了但没人查的内容正是最容易藏问题的地方。Step 5读取执行器备注如果{outputs_dir}/user_notes.md存在读取并记录执行器标记的不确定项与问题把相关关切纳入评分输出对应grading.json的user_notes_summary字段注意即使所有断言都通过执行器的自述也可能暴露问题。Step 6批判评测集Critique the Evals完成判分后评估 eval 本身是否可改进。文档对何时才值得提建议设定了高门槛——只在存在明确缺口时提出并给出了有区分度discriminating断言的定义断言应在技能真正成功时通过、在未成功时失败。值得提出的建议包括三类某条断言通过了但对一个明显错误的输出同样会通过例如只查文件是否存在、不查内容观察到一个重要结果无论好坏但没有任何断言覆盖它某条断言在现有输出下根本无法核验。原文的标准是The goal is to flag things the eval author would say good catch about, not to nitpick every assertion.目标是标出评测作者会说抓得好的问题而不是对每条断言吹毛求疵。这些建议最终落到eval_feedback字段形成对评测集的反馈回路。Step 7写出评分结果结果写入{outputs_dir}/../grading.json——即outputs目录的同级目录。在 skill-creator 的工作区布局中运行目录形如workspace/iteration-N/eval-ID/with_skill/其下outputs/存产物因此grading.json实际落在with_skill/grading.json与 SKILL.md Save results tograding.jsonin each run directory 的表述一致。Step 8读取执行器指标与耗时若{outputs_dir}/metrics.json存在读取并纳入评分输出对应execution_metrics若{outputs_dir}/../timing.json存在读取并纳入耗时数据对应timing。两个文件都是可选项缺失时相应字段留空即可评分本身不被阻断。metrics.json由执行器写入包含每次工具调用计数、total_steps、output_chars输出文件总字符数作为 token 的代理指标、transcript_chars等timing.json则由主代理在子代理任务完成时从通知里抓取total_tokens与duration_ms后落盘——SKILL.md 特别警告这是唯一的采集窗口错过通知就无法事后恢复。判定标准举证责任在断言一侧文档的 Grading Criteria 把 PASS/FAIL 边界写成了清单式规则判 PASS当且仅当转录或输出明确证明断言为真能引用具体证据证据反映的是实质内容而非表面合规例如文件存在且包含正确内容而不仅仅是文件名对。判 FAIL当未找到断言的任何证据证据与断言矛盾断言无法用现有信息核验证据是表面的——断言在技术上被满足但底层任务结果是错的或不完整的输出看起来是碰巧满足断言的而非真正完成了工作by coincidence rather than by actually doing the work。两条兜底规则存疑时通过断言的举证责任在断言一方The burden of proof to pass is on the expectation没有部分分No partial credit每条断言只有 pass 或 fail不存在折中。这一从严判定取向与 Step 6 的批判评测集互为表里对弱断言严格判 FAIL再借eval_feedback把它改强整个评测集的区分度会随迭代不断提升。输出格式grading.json 完整结构与字段说明Grader 的最终产物是一份 JSON 文件。文档给出的完整示例如下与 references/schemas.md 中的grading.json定义一致{ expectations: [ { text: The output includes the name John Smith, passed: true, evidence: Found in transcript Step 3: Extracted names: John Smith, Sarah Johnson }, { text: The spreadsheet has a SUM formula in cell B10, passed: false, evidence: No spreadsheet was created. The output was a text file. }, { text: The assistant used the skills OCR script, passed: true, evidence: Transcript Step 2 shows: Tool: Bash - python ocr_script.py image.png } ], summary: { passed: 2, failed: 1, total: 3, pass_rate: 0.67 }, execution_metrics: { tool_calls: { Read: 5, Write: 2, Bash: 8 }, total_tool_calls: 15, total_steps: 6, errors_encountered: 0, output_chars: 12450, transcript_chars: 3200 }, timing: { executor_duration_seconds: 165.0, grader_duration_seconds: 26.0, total_duration_seconds: 191.0 }, claims: [ { claim: The form has 12 fillable fields, type: factual, verified: true, evidence: Counted 12 fields in field_info.json }, { claim: All required fields were populated, type: quality, verified: false, evidence: Reference section was left blank despite data being available } ], user_notes_summary: { uncertainties: [Used 2023 data, may be stale], needs_review: [], workarounds: [Fell back to text overlay for non-fillable fields] }, eval_feedback: { suggestions: [ { assertion: The output includes the name John Smith, reason: A hallucinated document that mentions the name would also pass — consider checking it appears as the primary contact with matching phone and email from the input }, { reason: No assertion checks whether the extracted phone numbers match the input — I observed incorrect numbers in the output that went uncaught } ], overall: Assertions check presence but not correctness. Consider adding content verification. } }各字段语义继承自文档的 Field Descriptions 一节字段说明expectations[]逐条判分结果。text为原始断言文本passed为布尔值evidence为支撑判定的直接引文或描述summary汇总统计passed/failed/total计数与pass_rate0.0–1.0 的比例execution_metrics从执行器的metrics.json复制若存在。output_chars是输出文件总字符数token 的代理transcript_chars是转录字符数timing墙钟耗时来自timing.json若存在。executor_duration_seconds为执行器子代理耗时total_duration_seconds为整次运行总耗时claims[]从输出中抽取并核验的隐含声明。type取factual/process/qualityverified表示声明是否成立evidence给出支持或反驳证据user_notes_summary执行器标记的问题汇总uncertainties执行器不确定的事、needs_review需人工关注的项、workarounds技能未按预期工作、被迫绕行的地方eval_feedback可选对评测集的改进建议。suggestions每条含reason可附带其关联的assertionoverall为总评无问题时可写 No suggestions, evals look solid其中eval_feedback.suggestions的示例很有代表性第一条指出输出包含姓名 John Smith这条断言可以被一份恰好提到该名字的幻觉文档满足建议改为校验该名字作为主要联系人出现且电话、邮箱与输入匹配第二条指出没有任何断言检查抽取出的电话号码是否与输入一致而 Grader 实际观察到了未被捕获的错误号码。这正是判分 批判 eval双职责的具体落地。下游消费链grading.json 如何被仓库代码读取grading.json的字段名不是随意约定仓库中两处代码对其有硬依赖可以从源码确认这份协议的下游消费方式。1. 基准聚合脚本。scripts/aggregate_benchmark.py 从每个 run 目录读取grading.json并生成benchmark.json/benchmark.md其读取逻辑与 grader.md 的字段一一对应从summary取pass_rate、passed、failed、total见load_run_results中对grading.get(summary, {})的取值耗时优先取grading.json内timing.total_duration_seconds为 0 时回退到同目录的timing.json并同时取其中的total_tokens——这正好印证了 Step 8 先读 grading.json再读 sibling timing.json 的兜底关系从execution_metrics取total_tool_calls、errors_encountered并以output_chars作为 token 的兜底估计值把user_notes_summary的三个列表uncertainties/needs_review/workarounds合并为 benchmark 中的notes字段对expectations逐条校验必须含text与passed字段缺失时打印 Warning——即 SKILL.md 强调不要用name/met/details变体的机器侧原因。脚本支持两种目录布局eval-*/config/run-*/grading.json的直接工作区布局或带runs/子目录的旧布局配置目录名动态发现而非硬编码因此with_skill/without_skill或new_skill/old_skill等命名都能被聚合。2. 评测查看器。eval-viewer/generate_review.py 在构建每个 run 的展示数据时会依次尝试run_dir / grading.json和run_dir.parent / grading.json两个候选位置加载评分即运行目录内或其上级目录把解析结果挂到该 run 的grading字段上。这正是 Step 7 把结果放在outputs_dir同级即 run 目录内的展示层收益viewer 的 Formal Grades 折叠区可以展示每条断言的 pass/fail。3. 迭代对比。进入第 2 轮迭代后generate_review.py通过--previous-workspace参数把上一迭代的grading.json一并载入形成 Previous Output / Previous Feedback 的对照视图SKILL.md 要求聚合时把每个 with-skill 版本排在其基线对应项之前便于在 benchmark 视图中直接对比。行为准则文档结尾的 Guidelines 对评分行为本身提出六条约束客观Be objective结论基于证据而非假设具体Be specific引用支撑结论的原文彻底Be thorough转录与输出文件都要检查一致Be consistent对每条断言应用同一标准解释失败Explain failures说清楚为什么证据不足不给部分分No partial credit每条断言只有二元结论。小结grader.md 定义的评分协议有三个值得复用的设计要点其一产物优先于自述——断言由输出文件本身裁决转录只作过程证据其二从严判定——举证责任在断言一侧表面合规与碰巧通过一律判 FAIL其三评分即反馈——claims捕获断言未覆盖的隐含声明eval_feedback反向指出断言的盲区使grading.json同时充当成绩单与评测集改进清单。在 DeerFlow 的skill-creator工作流中这份产物是整条量化闭环的枢纽聚合脚本、评测查看器和下一轮迭代比较都直接建立在它的字段协议之上。【免费下载链接】deer-flowAn open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.项目地址: https://gitcode.com/GitHub_Trending/de/deer-flow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考