Grader Agent 完整指南Cherry Studio 技能评估循环中的自动化评判代理【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio在 Cherry Studio 的 skill-creator 技能体系中Grader Agent 承担着裁判角色它读取一次技能执行的完整转录transcript与产出文件逐条核对预设期望expectations最终产出结构化、可被基准聚合与可视化看板消费的grading.json。读完本文你将掌握 Grader 的八步评估流程、PASS/FAIL 判定标准、grading.json的完整字段契约以及它如何与aggregate_benchmark.py、eval viewer 等仓库组件协同构建一条执行 → 评判 → 聚合 → 人审的闭环。一、Grader 在技能评估循环中的定位skill-creator 的核心迭代循环是起草技能 → 编写测试用例 → 并行运行with-skill 与 baseline→评判grade→ 聚合基准 → 人工审阅 → 改进技能。其中评判环节由 agents/grader.md 定义的 Grader Agent 完成。从 SKILL.md 的 Step 4 可以看到 Grader 的明确用法每个运行目录run都要产出grading.json且其expectations数组必须严格使用text、passed、evidence三个字段——SKILL.md 原文强调 The grading.json expectations array must use the fieldstext,passed, andevidence(notname/met/detailsor other variants) — the viewer depends on these exact field names即视图层强依赖这套字段名写错字段将导致看板显示为空值。Grader 承担两项任务Role 部分原文一是评判产出grade the outputs二是批评评估本身critique the evals。后者尤为关键——A passing grade on a weak assertion is worse than useless — it creates false confidence一条弱断言的通过比没有更糟因为它制造虚假信心。这种裁判还兼任质检员的设计正是为了防止评估体系自我麻痹。二、输入参数与运行前置条件Grader 通过提示词接收三个核心参数参数含义说明expectations待评估的期望列表字符串数组即 evals 中定义的断言见 references/schemas.md 中evals[].expectationstranscript_path执行转录文件路径markdown记录执行提示、执行步骤与最终结果的完整过程outputs_dir执行产出文件所在目录包含执行器生成的各类输出对应的运行目录结构来自 SKILL.md 与 aggregate_benchmark.py 的文档注释大致为skill-name-workspace/ └── iteration-1/ └── eval-0/ ├── eval_metadata.json # 评估元数据prompt、断言 ├── with_skill/ │ ├── outputs/ # 产出文件 transcript.md user_notes.md metrics.json │ └── grading.json # Grader 的输出 └── without_skill/ ├── outputs/ └── grading.json其中timing.json位于 run 目录即outputs_dir的父级同级处metrics.json位于outputs_dir内这与 Grader 文档中 Step 8 的读取约定一致{outputs_dir}/metrics.json与{outputs_dir}/../timing.json。三、八步评估流程详解Grader 的评估过程被拆解为 8 个步骤每一环都对应一个明确的检查目标。Step 1通读执行转录完整读取转录文件记录三件事评估提示eval prompt是什么、执行经历了哪些步骤、最终结果如何同时留意文档化的任何问题或错误。转录是判定执行过程是否真实完成任务的首要证据来源Grader 不能跳过这一步直接看输出。Step 2检查输出文件列出outputs_dir下的所有文件逐一阅读与期望相关的文件。文档特别强调如果产出不是纯文本必须使用提示中提供的检查工具inspection tools去真实查看而不能只依赖转录里执行器自述产出了什么。这一要求直指 Agent 评估中常见的自述偏差——执行器声称生成了 PDF但 PDF 内容是否真的正确必须以检查工具实际解析的结果为准。从 eval-viewer/generate_review.py 的源码可以看到仓库对输出类型的处理方式文本类扩展名.txt/.md/.json/.csv/.py/.ts/.html/.css等以内联文本渲染图片类.png/.jpg/.gif/.svg/.webp转 base64 内联展示.pdf、.xlsx有专门的数据封装其余二进制提供下载链接。这为 Grader 提供了如何检查各类输出的实现参照——输出越多样越需要可靠的工具化检查而非肉眼臆断。Step 3逐条评估断言对每条期望执行三重动作搜索证据 → 判定裁决 → 引用证据。PASS条件存在清晰证据表明期望为真且证据反映的是真实任务完成而非表面合规surface-level compliance。FAIL条件无证据、证据与期望矛盾、或证据是浅层的例如文件名正确但内容为空或错误。引用证据引用转录或输出中的具体文本或精确描述发现。这里的真实完成 vs 表面合规区分是整个判定体系的核心张力与 Step 6 的评估批评形成呼应。Step 4提取并验证隐式声明超越预设期望从产出中提取三类声明并逐一验证声明类型含义验证方式factual事实性表单有 12 个字段对照产出或外部来源核查process过程性使用了 pypdf 填充表单从转录中核实quality质量性所有字段都正确填充评估该声明是否有依据对无法用现有信息验证的声明明确标记为不可验证unverifiable。这一步的价值在于catch issues that predefined expectations might miss——补上预设断言漏掉的问题。Step 5读取执行器用户笔记如果{outputs_dir}/user_notes.md存在阅读并记录执行器标注的不确定性、问题或变通方案并将相关担忧纳入评判输出。文档特别指出These may reveal problems even when expectations pass——即使断言全部通过执行器自己记录的疑虑例如使用了 2023 年的数据可能过时也可能暴露真实问题。这也解释了为何 schemas.md 与 aggregate_benchmark.py 中都有user_notes_summary含uncertainties、needs_review、workarounds三数组的专门结构。Step 6批评评估本身Critique the Evals完成评判后审视评估体系本身是否有改进空间但只在存在明显缺口时提出建议Only surface suggestions when theres a clear gap并抬高门槛——目标是提出评估作者会由衷认可good catch的建议而非逐条吹毛求疵。值得提出的三类问题原文列举某断言虽然通过但对明显错误的输出同样会通过例如只检查文件名存在、不检查文件内容观察到的重要结果无论好坏没有任何断言覆盖某断言根本无法从现有产出中验证。这引出一个核心概念区分度discriminating。一条好的断言passes when the skill genuinely succeeds and fails when it doesnt——技能真正成功时通过、真正失败时不通过。SKILL.md 中引用 analyzer 的分析思路与此一脉相承若某断言在 with-skill 与 without-skill 两种配置下都 100% 通过说明它不具区分度、无法体现技能价值见 agents/analyzer.md 的 per-assertion 模式分析。Step 7写入评判结果将结果保存到{outputs_dir}/../grading.json即outputs_dir的兄弟目录。这是整个流程的产物出口字段契约详见下一节。Step 8读取执行器指标与耗时若{outputs_dir}/metrics.json存在读取并纳入评判输出若{outputs_dir}/../timing.json存在读取耗时数据一并输出。metrics.json与timing.json的完整结构定义在 references/schemas.mdmetrics.json含tool_calls分类型计数、total_tool_calls、total_steps、files_created、errors_encountered、output_chars、transcript_charstiming.json含total_tokens、duration_ms、total_duration_seconds及各阶段的起止时间。SKILL.md 特别提醒timing.json的数据来自子代理任务完成通知只在通知中出现一次、不会持久化在其他地方必须及时落盘这决定了 Grader 的 Step 8 是读取已有文件而非重新采集。四、PASS / FAIL 判定标准与举证责任Grader 文档用两段清单明确了判定规则PASS 当且仅当转录或产出清晰地证明期望为真能够引用具体证据证据反映真实实质内容而非表面合规例如文件存在且内容正确而不只是文件名对。FAIL 当找不到期望的任何证据证据与期望矛盾无法从现有信息验证该期望证据是浅层的——断言技术上被满足但底层任务结果错误或不完整输出看起来是碰巧满足断言而非真正完成了工作。不确定时举证责任在期望方——The burden of proof to pass is on the expectation。即默认不信任期望必须拿出足够证据才能判 PASS这与宁可标记不可验证也不放行的保守取向一致。此外Guidelines 部分还规定了六条底线准则客观基于证据而非假设、具体引用支持裁决的确切文本、彻底转录与输出文件都要查、一致对每条期望应用同一标准、解释失败说清证据为何不足、不给部分分每条期望只有 PASS 或 FAIL没有中间地带。五、输出格式grading.json 完整字段契约Grader 的输出是grading.json其结构与 references/schemas.md 中定义的 schema 完全一致。完整示例结构如下{ 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_rate为通过比例0.01.0。execution_metrics从执行器的 metrics.json 复制而来如可用。output_chars为输出文件总字符数作为 token 的代理指标transcript_chars为转录字符数。timing来自 timing.json 的墙钟耗时。executor_duration_seconds为执行器子代理耗时total_duration_seconds为整体运行总耗时。claims从产出中提取并验证的声明。type取factual/process/quality三值verified为布尔evidence为支持或反驳证据。user_notes_summary执行器标记的问题。uncertainties为执行器不确定的事项needs_review为需人工关注项workarounds为技能未按预期工作时的变通点。eval_feedback评估改进建议仅在必要时出现。suggestions为具体建议列表每条含reason及可选的关联assertionoverall为简短总评无问题时可写 No suggestions, evals look solid。注意两个可选性约定eval_feedback仅在 Grader 识别出值得提出的问题时才存在schemas.md 标注 optionalclaims、user_notes_summary、execution_metrics、timing均以对应数据文件存在为前提。六、grader 输出如何驱动下游组件grading.json是整个评估流水线的数据中枢下游有两个明确消费者1. 基准聚合aggregate_benchmark.pyaggregate_benchmark.py 递归扫描基准目录下的eval-*/config/run-*/grading.json从中提取summary.pass_rate/passed/failed/total用于计算各配置with_skill / without_skill的 pass rate 均值与标准差timing.total_duration_seconds缺省时回退读取同级timing.json作为耗时指标execution_metrics.total_tool_calls、errors_encountered与output_chars作为工具调用数与 token 代理指标expectations数组原样透传并对每条期望做字段校验——缺少text或passed时打印告警user_notes_summary的三类数组合并为notes列表。脚本最终产出benchmark.json与人类可读的benchmark.md其中 run_summary 计算各配置的mean ± stddev及二者差值delta。2. 评估看板generate_review.py 与 viewer.htmleval-viewer/generate_review.py 构建运行记录时会尝试从 run 目录或其父目录读取grading.json第 129-138 行并将其挂载到每个 run 上viewer.html 则渲染 Formal Grades 折叠区块读取grading.expectations逐条显示text用 ✓/✗ 图标区分passed并在evidence存在时渲染为证据子块第 874-897 行Benchmark 标签页同样依赖run.expectations与exp.passed做逐断言对比展示第 1265-1292 行。这正是 SKILL.md 反复强调字段名必须是text/passed/evidence的根源——字段契约一旦偏离viewer 与聚合脚本都会静默产出空值或零值。七、实战要点与常见陷阱结合 Grader 文档与仓库实现整理几条实战建议能脚本化就不肉眼看。SKILL.md 明确建议For assertions that can be checked programmatically, write and run a script rather than eyeballing it — scripts are faster, more reliable, and can be reused across iterations. 程序化检查可复用、可复现是量化评估的可靠根基。警惕表面合规。文件名正确 ≠ 内容正确碰巧通过 ≠ 真正完成。判定时始终追问这条证据是否只证明了表面而任务底层是否真实达成期望的质量比数量重要。一条具有区分度的断言远胜十条弱断言。设计断言时以技能真正成功才通过、真正失败就不通过为标尺Grader 的 eval_feedback 就是专门用来暴露弱断言制造虚假信心问题的出口。忠实执行字段契约。expectations[].text/passed/evidence是 viewer 与聚合脚本的硬依赖summary.pass_rate必须嵌套在summary下configuration必须取值with_skill/without_skill——任何偏差都会导致看板显示异常。不确定就判 FAIL。举证责任在期望方找不到充分证据时无法验证本身就是一种有价值的结论宁可保守标记也不放行。上下文是评判的一部分。执行器的user_notes.md、metrics.json、timing.json并非可选装饰——执行器主动记录的疑虑可能暴露断言全部通过背后的真实问题而耗时与工具调用数据让通过率有了成本维度的对照例如 analyzer 模式下关注的技能显著增加执行时间这类权衡。八、延伸阅读技能总览与完整迭代循环SKILL.md全部 JSON 数据契约evals/grading/metrics/timing/benchmark 等references/schemas.md盲测对比代理A/B 输出质量评判agents/comparator.md事后分析代理解释胜负原因并给出改进建议agents/analyzer.md聚合脚本与看板实现scripts/aggregate_benchmark.py、eval-viewer/generate_review.py【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考