Rivet Actors 技能评测实战：react-chat 的判定器（judge.md）设计与 agent-browser 验证流程解析

Rivet Actors 技能评测实战react-chat 的判定器judge.md设计与 agent-browser 验证流程解析【免费下载链接】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 技能评测体系中的react-chat评测用例深入解析其判定器文档 judge.md 的设计意图它定义了一套用 agent-browser 打开应用、输入消息、点击发送、再快照验证消息回显的自动化验收流程并给出结构化 JSON 判定输出。读完本文你将掌握判定器Judge如何与评测运行器配合、{{URL}}模板如何被替换、判定输出如何被 zod 校验以及如何基于仓库源码写出可复现、可自动化执行的评测判定指令。一、评测背景react-chat 要验证什么react-chat评测用例由两个文件组成prompt.md下达给被测 AI Agent 的任务书judge.md下发给判定器Judge Agent的验收指令即本文核心。任务书要求 Agent 构建一个由 RivetKit actor 支撑的聊天室应用核心需求包括一个将消息存储于 state 的单一聊天室 actor一个用于向聊天室追加消息的sendMessageaction消息至少包含text字段与时间戳一个能展示消息列表、提供输入框与发送按钮的 React 前端使用 Vite 作为 dev server使用文件系统驱动file-system driverstandalone 模式无外部服务器应用应通过npm run dev在 5173 端口运行。也就是说被评测的是 Agent 端到端“搭出一个可运行的聊天应用”的能力而 judge.md 则负责在应用跑起来之后像一名 QA 工程师一样通过浏览器实际操作来验收成果。二、judge.md 全文解读一份可执行的浏览器验收脚本judge.md 全文非常精炼只有 17 行结构为“一句验证目标 六步操作流程 四条通过标准”。它设计成模板形式其中{{URL}}是占位符由评测运行器在实际执行时替换为目标地址详见第三节。验证目标Verify the chat app works at {{URL}}.即在给定 URL 上验证聊天应用是否真正可用。注意这里验证的是运行时行为而非静态代码因此判定器必须借助 agent-browser 真实打开页面、执行交互。六步操作流程原文规定的步骤逐条如下用 agent-browser 打开{{URL}}—— 建立浏览器会话加载页面拍一次快照snapshot定位消息输入框与发送按钮—— 通过无障碍/页面快照理解当前 UI 结构避免盲目猜测选择器在输入框中输入一条测试消息如 Hello world—— 模拟真实用户输入点击发送按钮—— 触发前端调用 actor 的sendMessageaction短暂等待状态更新—— 给客户端与 actor 状态同步留出时间再次拍快照检查消息是否出现在消息列表中—— 验证端到端闭环输入 → action → state → 前端回显。这六步本质上是一条完整的“写路径”验收不仅验证了前端渲染还隐含验证了 actor action、状态存储与事件广播链路。仓库中真实的聊天室 actor 实现可佐证这条链路的存在见 examples/chat-room/src/index.tssendMessageaction 将消息写入数据库后调用c.broadcast(newMessage, message)推送给所有连接客户端前端正是依赖这条链路把新消息回显到列表。四条通过标准Pass criteria页面无错误加载—— 对应步骤 1防住白屏、JS 崩溃、资源加载失败存在文本输入框—— 对应步骤 2 中的输入框定位存在发送按钮—— 对应步骤 2 中的按钮定位发送消息后消息出现在消息列表中—— 对应步骤 36是整个评测最核心的功能判据。四条标准恰好覆盖了“页面可打开、UI 结构完整、核心交互闭环”三个层次且每条都可被快照直接观测这正是设计判定器时最重要的原则不要要求判定器去推断只要求它去观察。三、判定器如何被驱动评测运行器的实现细节judge.md 并非独立执行它由评测运行器 src/index.ts 统一调度。整个 react-chat 评测的流程如下运行器先做前置检查Skills 已构建assertSkillsBuilt要求先执行pnpm build -F rivet-website与 RivetKit 已构建assertRivetkitBuilt要求先执行pnpm -C rivetkit-typescript/packages/rivetkit build读取 prompt.md 与 judge.md将仓库中所有技能文档SKILL.md与任务书拼接交给被测 Agent 在临时目录生成项目在临时目录执行npm run dev启动 dev server并通过轮询http://localhost:5173等待其就绪waitForServer60 秒超时见 src/index.ts关键模板替换const judgeInput judgeTemplate.replace(/\{\{URL\}\}/g, devUrl)—— 这正是 judge.md 中{{URL}}占位符被注入实际地址的位置见 src/index.ts将判定系统提示词与替换后的 judge.md 拼接交给 Judge Agent 执行解析判定输出为结构化 JSON写入结果目录。判定器输出与重试机制判定器的行为约束来自 judge-system.md它要求 Judge Agent只输出一个严格符合 schema 的 JSON 块不能有任何多余文字。完整的判定输出 schema 如下{ 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 }各字段的语义摘自 judge-system.mdcriteria针对验收指令中的每一条通过标准给出一个条目pass为布尔值reason说明观察到的证据observations不在显式通过标准内但被注意到的其他问题样式破损、控制台报错、无障碍问题、加载缓慢、布局异常等severity取low/medium/high可为空数组friction技能文档或 API 导致 Agent 产生困惑的迹象需结合生成的代码找出绕路、误会或错误给出summary与改进建议fix可为空数组pass仅当所有criteria 全部通过时才为truesummary一句总体评估。输出可靠性由两道防线保证zod 运行时校验运行器用VerdictSchema定义于 src/index.ts对 Judge 输出做严格校验字段缺失、类型不符、severity 枚举非法都会被判定为无效输出JSON 重试机制解析失败时最多重试 3 次MAX_JUDGE_ATTEMPTS 3重试时会回传上次的校验错误并强制要求“必须输出与 schema 完全一致的合法 JSON”见 src/index.ts。结果会以三个文件落盘到scripts/skill-evals/results/eval/目录response.mdAgent 原始产出、verdict.json判定结果、meta.json运行元数据。若 Agent 在开发过程中记录过摩擦日志还会额外保存friction.md。四、真实判定样例从 verdict.json 看判定器怎么“写报告”虽然仓库当前结果目录中尚未包含 react-chat 的产物但同属一套评测体系的 react-counter/verdict.json 提供了最贴近的真实样例可以直观看到判定器输出长什么样{ criteria: [ { name: The page loads without errors, pass: true, reason: HTTP response shows the Counter App HTML is being served from localhost:5173 with proper Vite dev server response including React refresh injection }, { name: There is a visible count display, pass: true, reason: Counter.tsx component includes a count display rendered as a large 64px font paragraph showing the {count} variable }, { name: There is a clickable increment button, pass: true, reason: Counter.tsx component includes a button with onClick{increment} handler and displays as the button text }, { name: After clicking , the count increases by 1, pass: false, reason: Unable to complete browser interaction verification - agent-browser skill not returning visible output/results from snapshot and click commands, preventing confirmation that state updates occur after button click } ], observations: [ { summary: agent-browser skill returning command results without visible output - all commands (open, snapshot, click, screenshot) executed silently without textual feedback, severity: high } ], friction: [ { summary: agent-browser skill documentation shows expected command output formats, but skill is not producing human-readable output in the current environment, fix: Clarify whether agent-browser is designed to output text to stdout or if it requires special configuration for visible results in tool responses } ], pass: false, summary: The React counter application structure is correctly implemented with proper components, but interactive functionality cannot be verified due to browser automation tool limitations. }这个样例有几点对 react-chat 判定器的直接启发reason 必须记录可观察证据如“HTTP response 显示 Vite 已正常伺服 HTML”“组件中存在 onClick 处理器”而不是空泛的“看起来不错”静态检查能过、交互验证不能过时必须如实判定 FAIL第 4 条标准失败导致整体pass: false说明“页面能加载、UI 存在”不等于“功能可用”friction 是改进反馈的载体当浏览器自动化工具本身输出异常判定器会把问题归类为 friction 而非判 Agent 失败这体现了评测体系区分“Agent 问题”与“工具/文档问题”的设计意图。五、被评测目标的“标准答案”仓库里的聊天室 actor 长什么样为了让 react-chat 评测的通过标准更有实感可以对照仓库中真实存在的聊天室示例 examples/chat-room/src/index.ts。它演示了任务书中“单一聊天室 actor sendMessage action 消息回显”的典型实现用db()声明持久化数据库onMigrate中建messages表id、sender、text、timestamp四列events中声明newMessage事件actions.sendMessage将消息插入数据库后调用c.broadcast(newMessage, message)广播给所有客户端返回该消息actions.getHistory按插入顺序查询全部消息最后setup({ use: { chatRoom } })注册 actor 并registry.start()启动服务。可以看到判定器第 6 步“检查消息出现在消息列表中”依赖的正是这条链路前端调用sendMessage→ actor 持久化并广播 → 前端收到newMessage事件后更新列表。这也解释了为什么 judge.md 要求“等待状态更新后再快照”——广播与 React 状态刷新都需要一点时间过早快照可能产生误判。六、编写高质量 judge.md 的实操要点结合 judge.md 与整套评测运行器代码可以总结出编写这类判定文档的核心原则保持模板化用{{URL}}一类占位符注入动态地址运行器通过replace(/\{\{URL\}\}/g, devUrl)统一替换src/index.ts判定文档本身不写死任何环境地址步骤要“先快照、再操作、再快照”快照是判定器唯一的观察手段先快照定位控件、操作后快照验证结果中间插入短暂等待以容忍状态异步更新通过标准必须可观测、可判定全部采用“页面加载”“存在输入框”“存在发送按钮”“消息出现在列表”这类可被快照证实的断言避免“性能良好”“用户体验佳”等主观表述输出交给 judge-system.md 统一约束judge.md 只管“验证什么、怎么验证”结构化 JSON 输出由 judge-system.md 定义并靠 zod 重试机制兜底运行前置条件要交代清楚本评测依赖 Vite端口 5173与 file-system 驱动的 standalone 模式判定前必须保证 dev server 已就绪否则应判 ERROR 而非 FAIL。七、如何运行 react-chat 评测仓库中评测入口为scripts/skill-evals是一个私有 npm 包见 package.json运行命令为pnpm build -F rivet-website # 先构建技能文档否则运行器会退出 pnpm -C rivetkit-typescript/packages/rivetkit build # 构建 RivetKit 产物 npx tsx src/index.ts --eval react-chat # 运行 react-chat 评测主要 CLI 参数详见 src/index.ts--agent claude|codex生成项目的被测 Agent默认claude--model name被测 Agent 的模型claude 默认opuscodex 默认5.3--judge claude|codex担任判定器的 Agent默认claude--judge-model name判定器模型默认同为opus/5.3--keep-tmp评测通过时也保留临时项目目录便于复查 Agent 生成的代码。执行成功后结果写入scripts/skill-evals/results/react-chat/下的verdict.json与meta.json其中meta.json会记录 agent、model、judge、skills 列表、耗时与时间戳等运行元数据参考 react-counter/meta.json。结语judge.md 虽然只有短短 17 行却是整个 react-chat 评测的验收灵魂它以“打开 → 快照 → 输入 → 点击 → 等待 → 快照”的六步流程把“聊天应用真的能用”这一模糊目标拆解成四条可观测、可判定的标准再通过与 judge-system.md 的 JSON schema、src/index.ts 的模板替换与重试校验机制组合构成一套闭环、可复现、能沉淀 friction 反馈的自动化评测体系。对于希望为本仓库新增技能评测、或借鉴该模式搭建自身 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），仅供参考