企业官网建设流程全解析

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 通过提示词接收三个核心参数：

对应的运行目录结构（来自 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：提取并验证隐式声明

超越预设期望，从产出中提取三类声明并逐一验证：

对无法用现有信息验证的声明，明确标记为不可验证（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 there's a clear gap"），并抬高门槛——目标是提出评估作者会由衷认可"good catch"的建议，而非逐条吹毛求疵。

值得提出的三类问题（原文列举）：

• 某断言虽然通过，但对明显错误的输出同样会通过（例如只检查文件名存在、不检查文件内容）；
• 观察到的重要结果（无论好坏）没有任何断言覆盖；
• 某断言根本无法从现有产出中验证。

这引出一个核心概念：区分度（discriminating）。一条好的断言"passes when the skill genuinely succeeds and fails when it doesn't"——技能真正成功时通过、真正失败时不通过。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.md：metrics.json含tool_calls分类型计数、total_tool_calls、total_steps、files_created、errors_encountered、output_chars、transcript_chars；timing.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 skill's 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.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/quality三值，verified为布尔，evidence为支持或反驳证据。
• user_notes_summary：执行器标记的问题。uncertainties为执行器不确定的事项，needs_review为需人工关注项，workarounds为技能未按预期工作时的变通点。
• eval_feedback：评估改进建议（仅在必要时出现）。suggestions为具体建议列表，每条含reason及可选的关联assertion；overall为简短总评，无问题时可写 "No suggestions, evals look solid"。

注意两个可选性约定：eval_feedback仅在 Grader 识别出值得提出的问题时才存在（schemas.md 标注 optional）；claims、user_notes_summary、execution_metrics、timing均以对应数据文件存在为前提。

六、grader 输出如何驱动下游组件

grading.json是整个评估流水线的数据中枢，下游有两个明确消费者：

1. 基准聚合：aggregate_benchmark.py

aggregate_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.html

eval-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 文档与仓库实现，整理几条实战建议：

1. 能脚本化就不肉眼看。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." 程序化检查可复用、可复现，是量化评估的可靠根基。

2. 警惕表面合规。文件名正确 ≠ 内容正确；"碰巧通过" ≠ 真正完成。判定时始终追问：这条证据是否只证明了"表面"，而任务底层是否真实达成？

3. 期望的质量比数量重要。一条具有区分度的断言远胜十条弱断言。设计断言时以"技能真正成功才通过、真正失败就不通过"为标尺；Grader 的 eval_feedback 就是专门用来暴露"弱断言制造虚假信心"问题的出口。

4. 忠实执行字段契约。expectations[].text/passed/evidence是 viewer 与聚合脚本的硬依赖，summary.pass_rate必须嵌套在summary下，configuration必须取值with_skill/without_skill——任何偏差都会导致看板显示异常。

5. 不确定就判 FAIL。举证责任在期望方：找不到充分证据时，"无法验证"本身就是一种有价值的结论，宁可保守标记也不放行。

6. 上下文是评判的一部分。执行器的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