Roo Code Evals 评估系统架构与代码库导航实战指南【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-CodeRoo Code 在编辑器中提供了 AI 智能体开发团队的能力而支撑其能力评测的是一套独立的Evals评估子系统。本文将基于仓库内.roo/skills/evals-context/SKILL.md技能文档完整梳理这套分布式评估平台在 monorepo 中的代码布局、架构原理与日常开发操作——包括两处 evals 位置的关键辨析、Controller/Runner/Redis/PostgreSQL 协作模型、本地运行方式以及从 CHANGELOG 中可追溯的功能演进脉络。读完你就能快速定位 evals 相关代码、新增练习、修改 CLI 与 Web 界面并动手跑通一次评估。这份技能文档解决什么问题.roo/skills/evals-context/SKILL.md是一份面向 Roo Code 开发者的代码库上下文技能skill描述字段明确声明了它的触发条件当任务涉及evals、evaluation、eval runs、eval exercises或 evals 基础设施工作时才启用。它的核心价值有两点消歧monorepo 中存在多个名字里带 evals 的位置容易混淆导航给出各模块目录结构、架构图、常用开发任务的快速操作路径。佐证CHANGELOG.md 中记录了 Remember last Roo model selection in web-evals and add evals skill (PR #10470 by hannesrudolph)说明这份 skill 是随 web-evals 功能一并引入仓库的正式组成部分。何时使用 / 何时不适用适用场景修改或调试 evals 执行基础设施CLI、数据库 schema、Docker 配置新增 eval 练习或语言维护 evals Web 管理界面apps/web-evals修改 roocode.com 公开的 evals 结果展示页理解 evals 相关代码在 monorepo 中的位置。明确不适用的场景处理与 evals 无关的代码库部分extension、webview-ui 等纯 VS Code 扩展核心功能的任务不涉及 evals 的主网站页面。关键澄清monorepo 中两个 evals 位置这是本技能文档最重要的信息——该仓库存在两处功能完全不同的 evals 位置很容易造成混淆组件路径用途Evals 执行系统packages/evals/核心评估基础设施CLI、数据库 schema、Docker 配置Evals 管理 UIapps/web-evals/Next.js 应用用于创建/监控 eval 运行localhost:3446网站 Evals 展示页apps/web-roo-code/src/app/evals/roocode.com 公开页面展示评估结果外部练习仓库Roo-Code-Evals真实编码练习不在本 monorepo 内其中最容易被忽视的区别是公开展示页只是读结果并不真正执行评估——它从roo-code/evals导入类型但从不运行 evals真正的评估能力在packages/evals里。这种展示与执行分离的设计避免了把评估平台的核心逻辑暴露到公网站点中。补充说明在当前公开代码快照中packages/evals/与apps/web-evals/目录未包含在工作区内该子系统按内部工程维护/单独分发但CHANGELOG.md中有大量与之相关的演进记录下文结构描述以 SKILL.md 文档为准。目录结构参考packages/evals/— 核心评估包packages/evals/ ├── ARCHITECTURE.md # 详细架构文档 ├── ADDING-EVALS.md # 新增练习/语言的指南 ├── README.md # 安装与运行说明 ├── docker-compose.yml # 容器编排 ├── Dockerfile.runner # Runner 容器定义 ├── Dockerfile.web # Web 应用容器 ├── drizzle.config.ts # 数据库 ORM 配置 ├── src/ │ ├── index.ts # 包导出 │ ├── cli/ # 运行 evals 的 CLI 命令 │ │ ├── runEvals.ts # 编排完整的 eval 运行 │ │ ├── runTask.ts # 在容器中执行单个任务 │ │ ├── runUnitTest.ts # 通过测试验证任务完成度 │ │ └── redis.ts # Redis pub/sub 集成 │ ├── db/ │ │ ├── schema.ts # 数据库 schemaruns、tasks │ │ ├── queries/ # 数据库查询函数 │ │ └── migrations/ # SQL 迁移 │ └── exercises/ │ └── index.ts # 练习加载工具 └── scripts/ └── setup.sh # 本地 macOS 安装脚本这个包内部职责划分非常清晰src/cli/是评估的引擎室runEvals.ts负责整场评估的编排runTask.ts负责把单个任务丢进隔离容器执行runUnitTest.ts在任务执行后用单元测试判定是否完成redis.ts负责与 Redis 的事件通道集成src/db/是评估数据的持久化层schema.ts定义runs、tasks等表结构migrations 目录存放 SQL 迁移脚本顶层还有ARCHITECTURE.md、ADDING-EVALS.md两份开发者文档以及完整的 Docker 化方案docker-compose.yml、Dockerfile.runner、Dockerfile.web。apps/web-evals/— 评估管理 Web 应用apps/web-evals/ ├── src/ │ ├── app/ │ │ ├── page.tsx # 首页运行列表 │ │ ├── runs/ │ │ │ ├── new/ # 新建 eval 运行 │ │ │ └── [id]/ # 查看特定运行状态 │ │ └── api/runs/ # SSE 流式推送端点 │ ├── actions/ # Server Actions │ │ ├── runs.ts # 运行 CRUD 操作 │ │ ├── tasks.ts # 任务查询 │ │ ├── exercises.ts # 练习列表 │ │ └── heartbeat.ts # 控制器健康检查 │ ├── hooks/ # React hooksSSE、模型等 │ └── lib/ # 工具函数与 schemas它采用 Next.js 服务端动作Server ActionsSSEServer-Sent Events架构app/api/runs/提供 SSE 流式推送端点前端通过hooks/中的 React hooks 订阅实时运行状态actions/runs.ts承载创建、删除等 CRUD 操作actions/heartbeat.ts则用于对评估控制器做健康检查。apps/web-roo-code/src/app/evals/— 公开网站展示页apps/web-roo-code/src/app/evals/ ├── page.tsx # 拉取并展示公开评估结果 ├── evals.tsx # 主要展示组件 ├── plot.tsx # 可视化组件 └── types.ts # EvalRun 类型继承 packages/evals 类型该页面从roo-code/evals导入类型但不运行evals仅负责把结果以图表形式plot.tsx呈现给公众。架构总览分布式评估平台根据 SKILL.md 的架构描述evals 系统是一个在隔离的 VS Code 环境中运行 AI 编码任务的分布式评估平台┌─────────────────────────────────────────────────────────────┐ │ Web App (apps/web-evals) ──────────────────────────────── │ │ │ │ │ ▼ │ │ PostgreSQL ◄────► Controller Container │ │ │ │ │ │ ▼ ▼ │ │ Redis ◄───► Runner Containers (1-25 parallel) │ └─────────────────────────────────────────────────────────────┘四个核心组件各司其职Controller控制器编排整场 eval 运行负责派生 Runner、维护任务队列——任务队列基于p-queuePromise 队列库实现Runner执行器隔离的 Docker 容器内部包含 VS Code Roo Code 扩展 语言运行时评估任务在其中真实执行Redis承担pub/sub 实时事件分发——注意它不负责任务排队这是文档特别强调的一点任务排队由 Controller 内的 p-queue 完成PostgreSQL持久化存储 runs、tasks、metrics 等评估数据。这个架构的要点在于隔离与并行125 个 Runner 容器可以并行执行任务彼此互不干扰Controller 通过 Redis 事件通道把运行进度实时推给 Web 应用。CHANGELOG 中 Move evals into pnpm workspace, switch from SQLite to Postgres 记录了数据库从 SQLite 升级为 PostgreSQL 的演进与文档中 PostgreSQL 的定位一致。常见开发任务速查新增一个 Eval 练习将练习添加进外部练习仓库 Roo-Code-Evals不在本 monorepo 内按照packages/evals/ADDING-EVALS.md中规定的结构组织练习目录。修改 Eval CLI 行为编辑packages/evals/src/cli/下的文件runEvals.ts— 整场评估的编排逻辑runTask.ts— 单个任务的容器内执行逻辑runUnitTest.ts— 用测试校验任务完成度。修改 Evals Web 界面编辑apps/web-evals/src/下的文件app/runs/new/new-run.tsx— 新建运行表单actions/runs.ts— 运行的 Server Actions。修改公开 Evals 展示页编辑apps/web-roo-code/src/app/evals/下的文件evals.tsx— 展示组件plot.tsx— 图表可视化。数据库 Schema 变更编辑packages/evals/src/db/schema.ts生成迁移cd packages/evals pnpm drizzle-kit generate应用迁移pnpm drizzle-kit migrate。整个流程采用 drizzle-kit 的迁移工作流先改 schema再生成 SQL 迁移文件最后应用迁移——schema 与迁移文件分离保证生产环境可以安全升级数据结构。本地运行 Evals从仓库根目录执行pnpm evals该命令会拉起整套评估环境并打开 Web 管理界面地址为http://localhost:3446。默认端口一览服务端口PostgreSQL5433Redis6380Web3446三个服务使用非默认端口正是为了避免与开发者本机常见的 5432Postgres/6379Redis/3000Next.js发生冲突——CHANGELOG 中 Fix Docker port conflicts for evals services 印证了这一设计考量。测试分别对两个子项目运行测试# packages/evals 测试 cd packages/evals npx vitest run # apps/web-evals 测试 cd apps/web-evals npx vitest run两个子项目均以 Vitest 作为测试框架与仓库整体技术栈保持一致。关键类型与导出roo-code/evals包导出定义在packages/evals/src/index.ts主要包含数据库查询函数getRuns、getTasks、getTaskMetrics等Schema 类型Run、Task、TaskMetrics。这些导出被apps/web-evals管理端与apps/web-roo-code公开展示端共同使用——这也解释了为什么公开页的types.ts可以继承 packages/evals 类型两端共用同一套类型定义避免数据结构漂移。从 CHANGELOG 看 evals 子系统的能力演进CHANGELOG.md记录了 evals 子系统相当完整的功能演进史可以作为理解其能力边界的佐证运行与编排新增 CLI 运行 evals 的方式PR #10456为 evals 启用 Roo Code RouterPR #9492检测到 API 不稳定时自动重试 eval 任务PR #9365为 evals 增加可配置超时5–10 分钟任务执行出现错误时跟踪工具使用错误。Web 管理界面支持多模型同时启动multi-model launch、运行筛选、批量删除、工具分组tool groups、运行备注新增任务日志查看、失败日志导出、kill run终止运行能力优化运行日志与格式化器让运行在 Web UI 中可删除。基础设施将 evals 移入 pnpm workspace 并从 SQLite 切换为 Postgres修复 evals 服务的 Docker 端口冲突让 evals Docker 设置支持 Windows在裸机安装脚本中改用 mise-en-place 工具链确保运行 evals 前练习库保持最新。这些条目印证了文档所述架构与功能的真实性与活跃度CLI、Docker 化、Postgres、并发 Runner、实时事件推送都是在持续迭代中形成的。评估理念把 Agent 当作员工而非模型来打分仓库内apps/web-roo-code/src/content/blog/score-agents-like-employees-not-like-models.md是一篇与 evals 主题直接相关的官方博客它给出了 Roo Code 评估体系背后的理念代码正确性基准无法覆盖 Agent 的真实失败模式漂移、上下文丢失、静默失败因此建议围绕四个工作风格维度打分主动性Proactivity是否持续推进还是卡住就停下等待上下文管理Context management在多文件改动中能否不丢失需求沟通Communication执行前是否说明计划卡住时是否主动暴露测试Testing是否自行验证工作成果而不是交付未验证代码。并给出了可落地的构建方法先用真人按上述四维打分再训练LLM-as-a-judge复现真人评分两者相关后用于规模化评估同时保留人工抽查。这篇文章与 SKILL.md 描述的在隔离 VS Code 环境中运行真实编码任务的评估形态互为表里可以帮助你从为什么需要这套系统的角度理解 evals 架构。使用边界与注意事项当前公开快照未包含packages/evals/与apps/web-evals/目录若需修改这些模块的代码需在包含 evals 子系统的完整工程中操作练习内容exercises存放在外部仓库 Roo-Code-Evals新增练习时要注意遵循packages/evals/ADDING-EVALS.md的目录规范Redis 在系统中只负责 pub/sub 实时事件不要误把它当作任务队列来扩展——并发控制发生在 Controller 的 p-queue 中三个服务端口5433/6380/3446是默认值与常见服务默认端口错开排查连接问题时先确认这几个端口。至此你已经掌握了 Roo Code Evals 系统的完整代码地图从两处 evals 位置的辨析到packages/evals、apps/web-evals、apps/web-roo-code/src/app/evals三大模块的结构再到 Controller/Runner/Redis/PostgreSQL 的分布式架构与本地运行命令。后续无论是新增练习、调整 CLI 编排、改进管理界面还是修改公开展示页都可以按本文的任务速查快速定位到对应文件。【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考