编写可验证的 Agent 评测判定规范Rivet 仓库 react-counter 的 judge.md 设计与落地【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors本篇技术指南聚焦于 Rivetriv/actors仓库中 Agent 技能评测体系skill-evals的核心组件——scripts/skill-evals/evals/react-counter/judge.md。它定义了一个AI 评测法官judge如何通过浏览器自动化为工具验证 AI Agent 生成的应用是否真正可用从打开页面、定位计数显示与按钮、点击自增到依据四条通过标准给出结构化 JSON 判定。读完本文你将掌握评测用例中判定规范judge 文档的编写方法、它与任务提示prompt 文档的分工、判定 JSON 的结构化约束与重试机制以及如何从真实运行结果中反推规范缺陷并持续改进。一、判定文档在整个评测体系中的定位在scripts/skill-evals/目录下评测用例采用任务提示 判定规范双文件结构。每个用例目录包含两个文件prompt.md给被评测 Agent 的任务描述生成什么应用judge.md给评测法官的验证指令如何验证应用是否可用。以react-counter用例为例prompt.md 描述任务是构建一个由 RivetKit actor 支撑的 React 计数器应用单个存储 count 状态的 counter actor、incrementaction、显示计数与 按钮的 React 前端、使用 Vite 开发服务器、采用文件系统驱动file-system driver独立模式、无外部服务器并通过npm run dev在 5173 端口运行。而 judge.md 则是另一个独立角色法官的指令它不关心Agent 是如何写的只关心应用最终是否真的能跑、能交互。这种分离让评测的两端职责清晰生成端追求实现判定端追求事实验证。同目录下还有 js-counter 与react-chat两个用例其judge.md与react-counter采用完全相同的骨架打开 URL → 快照 → 记录初始值 → 点击 → 等待 → 复查验证了这套判定模板的可复用性。二、judge.md 全文解析模板变量与结构化指令react-counter/judge.md全文仅十几行但结构紧凑可划分为三个部分Verify the counter app works at {{URL}}. ## Steps 1. Open {{URL}} with agent-browser 2. Take a snapshot to find the counter display and increment button 3. Note the initial count value 4. Click the increment button 5. Wait briefly for the state to update 6. Take a new snapshot and check the count increased ## Pass criteria - The page loads without errors - There is a visible count display - There is a clickable increment button - After clicking , the count increases by 11. 模板变量{{URL}}首行的{{URL}}不是占位示例而是运行时的真实模板替换点。在 src/index.ts 中可以看到其替换逻辑const judgeInput judgeTemplate.replace(/\{\{URL\}\}/g, devUrl);即框架会启动被测应用的开发服务器后把{{URL}}全部替换为实际地址http://localhost:5173源码中const devUrl http://localhost:5173。这意味着同一个judge.md可以复用于任何运行地址实现了规范与具体环境解耦。2. Steps把验证翻译成可执行动作序列六步操作本质上是把人类的验收动作翻译成 agent-browser 可执行的指令序列每一步都有明确目的步骤动作验证意图1打开{{URL}}确认页面可访问、服务在响应2快照定位计数显示与自增按钮确认关键 UI 元素真实存在3记录初始计数值为后续变化提供对照基线4点击自增按钮触发状态变更的交互动作5短暂等待状态更新留出前端重新渲染与 actor 状态同步的时间6再次快照并核对计数增长验证状态确实发生正向变化值得注意的是步骤中使用了Take a snapshotDOM 快照而非截图因为快照是结构化的文本表示便于 LLM 判断元素是否存在、文本是否为数字从而得出可验证的结论而不是依赖模糊的视觉观察。3. Pass criteria可判定的四条通过标准四条标准构成逻辑递进关系覆盖了从加载到功能的完整验收链页面无错误加载可用性底线存在可见的计数显示关键元素存在存在可点击的自增按钮关键交互元素存在点击 后计数增加 1核心业务逻辑正确且数值增量精确为 1。这种先静态后动态、先存在后行为的层次化设计能让法官在任一步骤失败时精确定位失败层是页面挂了、元素缺失还是状态逻辑错误。三、法官系统提示词与结构化判定 JSONjudge.md本身只提供验证什么而怎么组织结论由法官的系统提示词 judge-system.md 定义。它规定法官的身份是验证 AI Agent 是否成功构建了可运行应用的评测法官并且使用 agent-browser 打开应用 URL、与之交互、按标准逐条验证验证结束后只输出一个 JSON 块不得附加其他文本输出必须严格匹配固定 schema。判定 JSON 的完整结构{ criteria: [ { name: criterion name, pass: true, reason: what you observed } ], observations: [ { summary: brief description of a problem or concern, severity: low } ], friction: [ { summary: brief description of an issue the agent likely hit, fix: recommended fix or improvement } ], pass: true, summary: One sentence overall assessment }各字段的语义约束如下criteria对应judge.md中每一条通过标准逐条给出布尔结论与观察依据pass必须为布尔值reason说明看到了什么observations通过标准之外发现的其他问题样式破损、控制台错误、可访问性、加载缓慢、布局异常等严重度取low/medium/high可为空数组friction技能文档或 API 中导致 Agent 遇到困难的点从生成的代码里找困惑、绕行、错误迹象每项包含summary问题概述与fix改进建议可为空数组pass仅当所有criteria 全部通过才为truesummary一句话总体评估。这套 schema 的设计亮点在于把结论criteria/pass与过程证据observations和改进信号friction分离让一次评测同时产出验收结论与文档改进建议两类价值。四、判定结果的校验、重试与落盘法官是 LLM输出 JSON 可能不合法。框架在 src/index.ts 中做了工程化兜底JSON 提取extractJson优先匹配 json 代码围栏否则直接尝试解析再退化为用正则/\{[\s\S]*\}/抓取最大 JSON 块Schema 校验parseVerdict用 zod 定义VerdictSchema对criterianame/pass/reason、observationssummary/severity 枚举、frictionsummary/fix、pass、summary做严格类型校验收集每个字段的校验错误失败重试MAX_JUDGE_ATTEMPTS 3首次失败后把上一轮的校验错误回传给法官并追加硬性提示——你的上次响应 JSON 无效必须严格按 schema 输出合法 JSON每个字段必填最多重试 3 次结果落盘合法的判定写入verdict.json同时把法官的原始输出在全部重试失败时也保留下来便于排查。一次评测的完整执行链路从 src/index.ts 的主流程可以还原完整链路前置断言检查技能产物website/dist/metadata/skills与 RivetKit 构建产物rivetkit-typescript/packages/rivetkit/dist/tsup/mod.js是否存在缺失则报错并提示构建命令加载全部技能SKILL.md与用例的prompt.md、judge.md按EVAL_NAME解析用例目录启动 sandbox-agent 守护进程创建生成 Agent会话默认--agent claude模型默认 opus10 分钟超时在临时目录中构建项目并收集响应与摩擦日志启动开发服务器npm run devdetached进程组stdout/stderr 分别落盘并保留最近 200 行 tail随后用 fetch 轮询http://localhost:5173等待就绪超时 60 秒用devUrl替换{{URL}}后创建法官 Agent会话执行判定如上所述做 JSON 提取、zod 校验与最多 3 次重试终止服务器、清理临时目录--keep-tmp可保留写入verdict.json与meta.json记录 agent、model、judge、judge_model、duration_s、skills 列表、临时目录、是否产生摩擦日志等元数据最后根据verdict.pass输出 PASS / FAIL / ERROR。命令行入口为 package.json 中的pnpm eval -- --eval react-counter脚本eval: tsx src/index.ts常用参数包括--agent、--model、--judge、--judge-model、--keep-tmp等。五、从真实运行结果反推规范质量仓库中保留了一次真实运行记录是理解这套判定体系的最佳素材meta.json 显示生成 Agent 为 claudesonnet、法官为 claudehaiku运行耗时 314 秒加载了 5 个技能rivetkit、client-javascript、client-react、client-swift、client-swiftui且产生了摩擦日志verdict.json 显示四条标准中三条通过页面由 Vite 正常伺服含 React refresh 注入、Counter.tsx中以 64px 大字号段落渲染{count}、按钮带onClick{increment}且文本为第四条点击后计数 1因 agent-browser 技能在当前环境不返回可读输出而无法完成浏览器交互验证最终整体pass: false。这份失败记录恰好印证了框架里 friction 与 observations 字段的价值observationhighagent-browser 的 open/snapshot/click/screenshot 全部静默执行、无文本反馈属于工具链环境问题而非应用缺陷observationmedium/lowAgent 把file-system driver 独立模式理解为把 RivetKit 嵌入 Vite 中间件而非独立后端进程并因此引入了concurrently却未实际使用——说明 prompt 表述有歧义friction 两条其一建议澄清 agent-browser 是否应向 stdout 输出文本或需要特殊配置其二建议为file-system driver 独立模式在浏览器环境中的含义补充带代码示例的文档。可见判定失败并不总意味着 Agent 交付了坏应用——judge.md验证的是可验证性而observations与friction把验证不了的原因结构化地暴露出来成为改进技能文档与评测规范的第一手依据。六、编写高质量 judge 判定规范来自本仓库的实践要点综合judge.md模板、judge-system.md约束与真实运行教训可以提炼出以下可复用的编写要点指令必须可执行每条 Step 都应是 agent-browser 能执行的原语open / snapshot / click / 等待 / 复查避免检查一下是否正常这类模糊指令通过标准要可判定每一条都应能对应到一个可观察的事实元素存在数值 1法官才能给出布尔结论并附 reason判定标准应分层加载 → 元素存在 → 交互 → 业务正确便于失败定位用模板变量解耦环境凡涉及地址、端口等运行时信息一律使用{{URL}}之类变量由框架替换保证规范可复用给法官留出附加观察通道通过observations与friction收集标准之外的异常与文档改进建议让每次评测都成为规范自身的迭代输入强制结构化输出系统提示词明确规定只输出 JSON、严格匹配 schema、字段必填并由 zod schema 加最多 3 次带错误回传的重试来兜底保证结果可机器消费。七、总结scripts/skill-evals/evals/react-counter/judge.md虽然只有十几行却是整个 skill-evals 评测体系中质量闸门的浓缩它以{{URL}}模板与 agent-browser 动作序列承载可验证的验收步骤以四条层次化通过标准界定什么才算成功再经由 judge-system.md 的结构化 JSON 约束与 src/index.ts 的校验重试机制最终产出可供 PASS/FAIL 判定的verdict.json。而仓库中保留的真实失败记录进一步说明一份好的判定规范不仅要能验证应用是否工作更要能暴露为什么无法验证——这正是 Agent 评测体系可持续改进的关键所在。【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 编写可验证的 Agent 评测判定规范：Rivet 仓库 react-counter 的 judge.md 设计与落地
编写可验证的 Agent 评测判定规范Rivet 仓库 react-counter 的 judge.md 设计与落地【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors本篇技术指南聚焦于 Rivetriv/actors仓库中 Agent 技能评测体系skill-evals的核心组件——scripts/skill-evals/evals/react-counter/judge.md。它定义了一个AI 评测法官judge如何通过浏览器自动化为工具验证 AI Agent 生成的应用是否真正可用从打开页面、定位计数显示与按钮、点击自增到依据四条通过标准给出结构化 JSON 判定。读完本文你将掌握评测用例中判定规范judge 文档的编写方法、它与任务提示prompt 文档的分工、判定 JSON 的结构化约束与重试机制以及如何从真实运行结果中反推规范缺陷并持续改进。一、判定文档在整个评测体系中的定位在scripts/skill-evals/目录下评测用例采用任务提示 判定规范双文件结构。每个用例目录包含两个文件prompt.md给被评测 Agent 的任务描述生成什么应用judge.md给评测法官的验证指令如何验证应用是否可用。以react-counter用例为例prompt.md 描述任务是构建一个由 RivetKit actor 支撑的 React 计数器应用单个存储 count 状态的 counter actor、incrementaction、显示计数与 按钮的 React 前端、使用 Vite 开发服务器、采用文件系统驱动file-system driver独立模式、无外部服务器并通过npm run dev在 5173 端口运行。而 judge.md 则是另一个独立角色法官的指令它不关心Agent 是如何写的只关心应用最终是否真的能跑、能交互。这种分离让评测的两端职责清晰生成端追求实现判定端追求事实验证。同目录下还有 js-counter 与react-chat两个用例其judge.md与react-counter采用完全相同的骨架打开 URL → 快照 → 记录初始值 → 点击 → 等待 → 复查验证了这套判定模板的可复用性。二、judge.md 全文解析模板变量与结构化指令react-counter/judge.md全文仅十几行但结构紧凑可划分为三个部分Verify the counter app works at {{URL}}. ## Steps 1. Open {{URL}} with agent-browser 2. Take a snapshot to find the counter display and increment button 3. Note the initial count value 4. Click the increment button 5. Wait briefly for the state to update 6. Take a new snapshot and check the count increased ## Pass criteria - The page loads without errors - There is a visible count display - There is a clickable increment button - After clicking , the count increases by 11. 模板变量{{URL}}首行的{{URL}}不是占位示例而是运行时的真实模板替换点。在 src/index.ts 中可以看到其替换逻辑const judgeInput judgeTemplate.replace(/\{\{URL\}\}/g, devUrl);即框架会启动被测应用的开发服务器后把{{URL}}全部替换为实际地址http://localhost:5173源码中const devUrl http://localhost:5173。这意味着同一个judge.md可以复用于任何运行地址实现了规范与具体环境解耦。2. Steps把验证翻译成可执行动作序列六步操作本质上是把人类的验收动作翻译成 agent-browser 可执行的指令序列每一步都有明确目的步骤动作验证意图1打开{{URL}}确认页面可访问、服务在响应2快照定位计数显示与自增按钮确认关键 UI 元素真实存在3记录初始计数值为后续变化提供对照基线4点击自增按钮触发状态变更的交互动作5短暂等待状态更新留出前端重新渲染与 actor 状态同步的时间6再次快照并核对计数增长验证状态确实发生正向变化值得注意的是步骤中使用了Take a snapshotDOM 快照而非截图因为快照是结构化的文本表示便于 LLM 判断元素是否存在、文本是否为数字从而得出可验证的结论而不是依赖模糊的视觉观察。3. Pass criteria可判定的四条通过标准四条标准构成逻辑递进关系覆盖了从加载到功能的完整验收链页面无错误加载可用性底线存在可见的计数显示关键元素存在存在可点击的自增按钮关键交互元素存在点击 后计数增加 1核心业务逻辑正确且数值增量精确为 1。这种先静态后动态、先存在后行为的层次化设计能让法官在任一步骤失败时精确定位失败层是页面挂了、元素缺失还是状态逻辑错误。三、法官系统提示词与结构化判定 JSONjudge.md本身只提供验证什么而怎么组织结论由法官的系统提示词 judge-system.md 定义。它规定法官的身份是验证 AI Agent 是否成功构建了可运行应用的评测法官并且使用 agent-browser 打开应用 URL、与之交互、按标准逐条验证验证结束后只输出一个 JSON 块不得附加其他文本输出必须严格匹配固定 schema。判定 JSON 的完整结构{ criteria: [ { name: criterion name, pass: true, reason: what you observed } ], observations: [ { summary: brief description of a problem or concern, severity: low } ], friction: [ { summary: brief description of an issue the agent likely hit, fix: recommended fix or improvement } ], pass: true, summary: One sentence overall assessment }各字段的语义约束如下criteria对应judge.md中每一条通过标准逐条给出布尔结论与观察依据pass必须为布尔值reason说明看到了什么observations通过标准之外发现的其他问题样式破损、控制台错误、可访问性、加载缓慢、布局异常等严重度取low/medium/high可为空数组friction技能文档或 API 中导致 Agent 遇到困难的点从生成的代码里找困惑、绕行、错误迹象每项包含summary问题概述与fix改进建议可为空数组pass仅当所有criteria 全部通过才为truesummary一句话总体评估。这套 schema 的设计亮点在于把结论criteria/pass与过程证据observations和改进信号friction分离让一次评测同时产出验收结论与文档改进建议两类价值。四、判定结果的校验、重试与落盘法官是 LLM输出 JSON 可能不合法。框架在 src/index.ts 中做了工程化兜底JSON 提取extractJson优先匹配 json 代码围栏否则直接尝试解析再退化为用正则/\{[\s\S]*\}/抓取最大 JSON 块Schema 校验parseVerdict用 zod 定义VerdictSchema对criterianame/pass/reason、observationssummary/severity 枚举、frictionsummary/fix、pass、summary做严格类型校验收集每个字段的校验错误失败重试MAX_JUDGE_ATTEMPTS 3首次失败后把上一轮的校验错误回传给法官并追加硬性提示——你的上次响应 JSON 无效必须严格按 schema 输出合法 JSON每个字段必填最多重试 3 次结果落盘合法的判定写入verdict.json同时把法官的原始输出在全部重试失败时也保留下来便于排查。一次评测的完整执行链路从 src/index.ts 的主流程可以还原完整链路前置断言检查技能产物website/dist/metadata/skills与 RivetKit 构建产物rivetkit-typescript/packages/rivetkit/dist/tsup/mod.js是否存在缺失则报错并提示构建命令加载全部技能SKILL.md与用例的prompt.md、judge.md按EVAL_NAME解析用例目录启动 sandbox-agent 守护进程创建生成 Agent会话默认--agent claude模型默认 opus10 分钟超时在临时目录中构建项目并收集响应与摩擦日志启动开发服务器npm run devdetached进程组stdout/stderr 分别落盘并保留最近 200 行 tail随后用 fetch 轮询http://localhost:5173等待就绪超时 60 秒用devUrl替换{{URL}}后创建法官 Agent会话执行判定如上所述做 JSON 提取、zod 校验与最多 3 次重试终止服务器、清理临时目录--keep-tmp可保留写入verdict.json与meta.json记录 agent、model、judge、judge_model、duration_s、skills 列表、临时目录、是否产生摩擦日志等元数据最后根据verdict.pass输出 PASS / FAIL / ERROR。命令行入口为 package.json 中的pnpm eval -- --eval react-counter脚本eval: tsx src/index.ts常用参数包括--agent、--model、--judge、--judge-model、--keep-tmp等。五、从真实运行结果反推规范质量仓库中保留了一次真实运行记录是理解这套判定体系的最佳素材meta.json 显示生成 Agent 为 claudesonnet、法官为 claudehaiku运行耗时 314 秒加载了 5 个技能rivetkit、client-javascript、client-react、client-swift、client-swiftui且产生了摩擦日志verdict.json 显示四条标准中三条通过页面由 Vite 正常伺服含 React refresh 注入、Counter.tsx中以 64px 大字号段落渲染{count}、按钮带onClick{increment}且文本为第四条点击后计数 1因 agent-browser 技能在当前环境不返回可读输出而无法完成浏览器交互验证最终整体pass: false。这份失败记录恰好印证了框架里 friction 与 observations 字段的价值observationhighagent-browser 的 open/snapshot/click/screenshot 全部静默执行、无文本反馈属于工具链环境问题而非应用缺陷observationmedium/lowAgent 把file-system driver 独立模式理解为把 RivetKit 嵌入 Vite 中间件而非独立后端进程并因此引入了concurrently却未实际使用——说明 prompt 表述有歧义friction 两条其一建议澄清 agent-browser 是否应向 stdout 输出文本或需要特殊配置其二建议为file-system driver 独立模式在浏览器环境中的含义补充带代码示例的文档。可见判定失败并不总意味着 Agent 交付了坏应用——judge.md验证的是可验证性而observations与friction把验证不了的原因结构化地暴露出来成为改进技能文档与评测规范的第一手依据。六、编写高质量 judge 判定规范来自本仓库的实践要点综合judge.md模板、judge-system.md约束与真实运行教训可以提炼出以下可复用的编写要点指令必须可执行每条 Step 都应是 agent-browser 能执行的原语open / snapshot / click / 等待 / 复查避免检查一下是否正常这类模糊指令通过标准要可判定每一条都应能对应到一个可观察的事实元素存在数值 1法官才能给出布尔结论并附 reason判定标准应分层加载 → 元素存在 → 交互 → 业务正确便于失败定位用模板变量解耦环境凡涉及地址、端口等运行时信息一律使用{{URL}}之类变量由框架替换保证规范可复用给法官留出附加观察通道通过observations与friction收集标准之外的异常与文档改进建议让每次评测都成为规范自身的迭代输入强制结构化输出系统提示词明确规定只输出 JSON、严格匹配 schema、字段必填并由 zod schema 加最多 3 次带错误回传的重试来兜底保证结果可机器消费。七、总结scripts/skill-evals/evals/react-counter/judge.md虽然只有十几行却是整个 skill-evals 评测体系中质量闸门的浓缩它以{{URL}}模板与 agent-browser 动作序列承载可验证的验收步骤以四条层次化通过标准界定什么才算成功再经由 judge-system.md 的结构化 JSON 约束与 src/index.ts 的校验重试机制最终产出可供 PASS/FAIL 判定的verdict.json。而仓库中保留的真实失败记录进一步说明一份好的判定规范不仅要能验证应用是否工作更要能暴露为什么无法验证——这正是 Agent 评测体系可持续改进的关键所在。【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考