eval-run

name	eval-run
description	运行 CLI 评测任务，遍历数据集中的用例，通过 subAgent 执行所有已安装的 CLI 工具插件并评分
context	fork

Eval Run — 评测执行

运行评测任务。每个测试用例通过独立的 subAgent 执行，每个评分也通过独立的 subAgent 完成，确保用例间隔离。

⚠️ 重要规则：

• 每个测试用例的执行必须通过独立的 subAgent（Agent tool）完成
• 每个 CLI 的评分也必须通过独立的 subAgent 完成
• 不要在当前上下文中直接执行用例或评分

🔴 核心规则：每个 case 必须运行「所有已安装的 CLI 工具插件」（不可只跑其中一个）

• 本框架用于对比多个 CLI 工具在同一任务上的表现。参与对比的 CLI 不再硬编码，而是取自当前已安装并注册的 CLI 工具插件集合。
• 查看当前可用的 CLI 工具插件：

  evals plugin list --type cli-tool
  

• prepare 会把已安装的 CLI 工具写入 manifest 的 clis 字段（动态列表）。每个 case 必须对 clis 中的每一个 CLI 都执行，缺任何一个都视为对比不完整。
• 用例的 products 字段（如 doc）只描述任务类型，绝不代表只用某一个 CLI。例如「创建文档」任务必须由 clis 中的每个 CLI 各自创建文档后再对比。

✅ 开始前先建立待办清单（防止步骤遗漏）

运行评测前，先用 TodoWrite 建立下列完整待办清单并逐项推进（每完成一项才能勾销，不可提前标完成）：

1. prepare 准备环境与用例清单（确认 manifest.clis 覆盖所有已安装 CLI）
2. 逐个用例执行：每个 case 对 manifest.clis 中的每个 CLI 各起一个 subAgent（一个都不能少）
3. 每个 CLI 截图（doc-screenshot）
4. 每个 CLI 评分（score-case + 两步打分）
5. finalize 收尾
6. 生成 HTML 报告并 在浏览器打开（report open）
7. 推送报告到 Langfuse / storage backend（report push）

每个 CLI 命令成功后会在输出末尾打印 “👉 下一步” 提示，请以它为准同步更新待办清单，确保不遗漏任何环节。

前置条件

执行评测前必须完成以下检查：

1. 检查已安装的 CLI 工具插件

evals plugin list --type cli-tool

• 至少需要安装一个 CLI 工具插件（否则 prepare 会报 “No CLI tool plugins installed”）。
• 如果对比所需的插件尚未安装，先安装：

  evals plugin install <package-name>
  # 例如：
  evals plugin install @tengxiaohtx/plugin-cli-dws
  evals plugin install @tengxiaohtx/plugin-cli-feishu
  

2. 通过准入校验

evals run validate

校验项（对 evals plugin list --type cli-tool 中的每个 CLI 逐一检查）：

• CLI 已安装（二进制存在，否则 evals auth login <cli_name> 会自动下载）
• CLI 已认证（checkAuth 通过）

其他前置条件：

• 平台已声明：Agent 已根据当前运行环境执行 evals config set-platform <claude|codex|qoder|qoderwork>（配置与上报依赖正确的平台，不可靠文件猜测）
• /eval-config 已执行（storage backend 已配置）
• /eval-auth 已执行（所有 CLI 已认证）
• /eval-case pull <dataset> 已执行（数据集已拉取）

SubAgent 执行要求

• 所有评测 CLI 命令必须通过 subAgent 执行
• subAgent 执行时不使用沙箱（平台 settings 中沙箱应禁用）
• 所有 CLI 必须使用框架下载的二进制（通过 subAgent 内 export PATH 指向 {data_dir}/bin/{cli}），禁止使用系统已安装的同名 CLI

截图流程（确定性截图）

使用 evals run doc-screenshot --work-dir <dir> 执行截图。命令内部自动从 status.json 读取文档标识、由对应 CLI 插件解析文档 URL 并执行截图。

前置条件：subAgent 通过 save-status --node-id/--doc-id/--doc-url 将文档标识写入 status.json。

截图要求（强制）：

• 截图 必须且只能 使用 evals run doc-screenshot 命令
• 严禁 使用 Agent 内置浏览器（如 Claude 的 computer_use、Qoder 的 browser MCP）
• 严禁 使用 puppeteer、playwright 或任何其他浏览器自动化库
• 严禁 回退使用 MCP browser-use、系统浏览器或其他任何浏览器控制工具
• 每个 case 下 manifest.clis 中的每个 CLI 都必须执行截图步骤
• 截图是必要步骤，不可跳过（除非登录重试后仍然失败）
• 不能因为一个 CLI 截图成功就跳过另一个 CLI 的截图
• 缺少任何 CLI 的截图将阻塞该 case 的进度
• 如果命令失败，报错退出而不是尝试替代方案

命令

/eval-run start <dataset_name> [options]

启动评测运行。

Options:

Option	Default	Description
--case <pattern>	全部用例	按名称或 input.name 模式过滤测试用例

评测始终对所有已安装的 CLI 工具插件运行，不提供只跑单个 CLI 的选项。如需限定参与对比的 CLI，请通过安装/卸载 CLI 工具插件来控制。

第 1 步：准备环境

执行 pre-flight 检查并输出用例清单：

evals run prepare "$@"

prepare 会动态读取已安装的 CLI 工具插件，并把它们写入 manifest 的 clis 字段。

解析输出的 JSON 用例清单（---MANIFEST--- 与 ---END-MANIFEST--- 之间），获取 runId、runDir、dataDir、datasetDir、skillsDir、clis 和 cases 列表。

manifest 字段说明：

• {run_id} = manifest.runId
• {run_dir} = manifest.runDir
• {data_dir} = manifest.dataDir — 全局数据根目录（CLI 二进制在 {data_dir}/bin/{cli}，CLI skills 在 {data_dir}/skills/{cli}）
• {dataset_dir} = manifest.datasetDir — 数据集目录（test cases 在此目录下）
• {skills_dir} = manifest.skillsDir — skills 目录
• manifest.clis — 本次参与对比的 CLI 名称列表（动态，来自已安装的 CLI 工具插件）

第 2 步：遍历执行每个用例

对于每个用例的每个 CLI（遍历 manifest.clis），启动一个 subAgent（使用 Agent tool）执行：

subAgent prompt 模板：

你是一个评测执行 Agent。请完成以下任务：

环境初始化（必须作为第一条 Bash 命令执行）：

export PATH="{data_dir}/bin/{cli}:$PATH"
export EVALS_CASE_NAME="{case_name}"
export EVALS_USERNAME="$(whoami)"

此后当前 CLI 的可执行文件可直接调用，无需指定完整路径。 EVALS_CASE_NAME 和 EVALS_USERNAME 用于 trace 上报时的 tags 筛选。

轨迹边界标记 begin（必须作为初始化后的第一条 evals 命令执行）：

evals run trace-marker --work-dir {work_dir} --phase begin

该标记会落入本 subAgent 自己的会话轨迹，是 trace ingest 判定 (runId, case, cli) 归属的确定性锚点（不依赖 hook 启发式）。缺少它会导致该 CLI 的 trace 丢失或并入主会话。

命令区分规则：

• {cli} ...（当前 CLI 的可执行名）— 产品 CLI 命令（通过 PATH 解析到框架下载的二进制）
• evals ... — 评测框架命令（直接调用，不要加任何前缀）

CLI Skills 引用（关键）：

• 当前 CLI ({cli}) 的 skills 文件在 {data_dir}/skills/{cli}/ 目录下

• 执行 CLI 命令前，必须先读取 该目录下的 skill 文件了解命令详细用法与参数（不同 CLI 的子命令/参数各不相同，绝不假设）

• 只使用当前 CLI 的 skills，不要访问其他 CLI 的 skills 目录

1. 读取数据集文件：{case_file}
2. 提取 input.prompt 字段
3. 读取当前 CLI 的 skills 获取命令参考：

   find {data_dir}/skills/{cli}/ -name "*.md" | head -5
   

   注意：只读取 {data_dir}/skills/{cli}/ 目录，不要访问其他 CLI 的 skills。

   如果该目录不存在或为空，使用当前 CLI 的 --help 获取帮助。

4. 使用当前 CLI 工具执行 prompt 中的任务：
   • 所有 CLI 命令尽量带 --format json（若该 CLI 支持）
   • 将 CLI 输出保存到 {work_dir}/output.log
   • 具体的创建/读取子命令与参数以该 CLI 的 skills 为准，不要照搬其他 CLI 的写法
5. 获取文档内容（如果任务涉及文档创建）：
   • 从 output.log 中解析文档标识（如 nodeId / document_id / url，字段名以该 CLI 输出为准）

其中：

• {case_name} — 当前用例名称
• {case_file} — 用例 JSON 文件路径（{dataset_dir}/{case_name}.json）
• {cli} — CLI 名称（取自 manifest.clis 的当前遍历项）
• {work_dir} — 执行目录 {run_dir}/{case_name}/{cli}

每个 subAgent 独立执行，完成后自动进入下一个 CLI / 用例。

第 2.5 步：截图验证（评分前置条件）

在每个 case/CLI 执行完成后、启动评分 subAgent 之前，验证截图文件是否存在：

1. 检查 {work_dir}/screenshots/ 目录是否存在且包含至少一个 .png 文件
2. 对当前 case 的所有 CLI（manifest.clis）进行截图检查：
   • 如果所有 CLI 的截图都缺失 → 阻塞该 case 的评分，不启动评分 subAgent
   • 输出：❌ Case {case_name}: All CLI screenshots missing. Scoring blocked.
   • 如果部分 CLI 有截图 → 允许评分，但缺失截图的 CLI 的 visual 评分项为 0 分

第 3 步：每个 CLI 执行完成后立即评分（两步工作流）

该 CLI 的 subAgent 完成后，启动一个评分 subAgent（使用 Agent tool）执行两步评分工作流：

评分 subAgent prompt 模板：

你是一个评测评分 Agent。请按照以下两步工作流完成评分：

准备：生成评分上下文

evals run score-case --work-dir {work_dir}

该命令会自动从路径推导 run_dir、case_name，并读取 manifest.json 获取数据集信息，生成：

• {case_dir}/raw-rubrics.json — 原始评分标准（Case 级公共文件）
• {work_dir}/scoring-prompt.txt — 执行上下文（CLI 特有）

其中：

• {case_dir} = dirname({work_dir})（如 {run_dir}/doc-create）

---

Step 1：细化 Rubrics（幂等，Case 级公共）

⚠️ 此步骤不能查看执行结果（不读 output.log、doc-content.md、screenshots）

1. 检查 {case_dir}/shared-refined-rubrics.json 是否已存在：
   • 如果文件存在且 JSON 可解析 → 跳过 Step 1，直接进入 Step 2
   • 如果不存在或 JSON 解析失败 → 继续执行下方细化流程
2. 读取 {case_dir}/raw-rubrics.json
3. 读取 {work_dir}/scoring-prompt.txt 中的 "## Test Case" 部分（仅 prompt，不看执行结果）
4. 对每条评分标准，细化为具体的 0-5 分描述：

   {
     "explicit": {
       "criteria_description": {
         "description": "原始标准描述",
         "standards": {
           "0": "得 0 分的具体表现",
           "1": "得 1 分的具体表现",
           "2": "得 2 分的具体表现",
           "3": 
            
            
         
       
     
   
   

第 4 步：收尾

截图完整性验证（在 finalize 之前执行）：

• 遍历所有 case/CLI 组合（CLI 取自 manifest.clis）
• 检查每个组合是否有截图
• 如果存在截图缺失的 case/CLI，在 meta.json 中标记
• 输出截图完整性报告

全部用例完成后，更新运行元数据：

evals run finalize --run-dir {run_dir}

输出运行摘要，提示运行 /eval-report {run_id} 生成报告。

第 5 步：生成并打开评测报告（必须完成，不可跳过）

⚠️ evals report data 只把 JSON 数据输出到 stdout，它本身不会生成 HTML。 必须由本 skill 读模板、填数据生成 report.html，再用浏览器打开。不可只跑 report data 就跳过。

1. 输出运行数据 JSON（先确保 {run_dir}/report/ 目录存在）：

   mkdir -p {run_dir}/report
   evals report data {run_id} > {run_dir}/report/report-data.json
   

2. 读取 HTML 模板：{skills_dir}/eval-report/references/report-template.html
3. 用 report-data.json 填充模板占位符（{{RUN_ID}}、{{CASE_SECTIONS}} 等），保存为 {run_dir}/report/report.html
4. 在浏览器中打开报告（强制步骤，不可跳过）：

   evals report open {run_id}
   

   该命令会用系统默认浏览器打开 {run_dir}/report/report.html。若提示报告不存在，说明步骤 2-3 未生成 HTML，需返回重新生成后再打开。

第 6 步：推送报告到 storage backend

evals report push {run_id}

调用 /eval-report push {run_id} 将报告、截图和得分推送到已配置的 storage backend（如 Langfuse）。

说明：步骤 5 和 6 是完整评测流程的必要环节，确保结果可视化并归档。

/eval-run list

列出所有运行：

evals run list

/eval-run delete <run_id>

删除指定运行：

evals run delete "$1"

CLI 命令参考

本框架不硬编码任何具体 CLI 的命令。每个 CLI 工具插件随包分发自己的 skills，subAgent 执行时必须先读取 {data_dir}/skills/{cli}/ 下的 skill 文件获取该 CLI 的准确子命令与参数。

查看当前可用 CLI：

evals plugin list --type cli-tool

目录结构

评测产物默认在 ~/.doc-cli-evals/eval-runs/（可用 EVALS_RUNS_DIR 环境变量或 --run-dir 覆盖）：

eval-runs/
├── .traces/          ← storage 格式 JSONL 文件，记录 LLM 调用过程
└── <run_id>/
    ├── meta.json
    ├── manifest.json                     ← 含动态 clis 列表
    └── <case_name>/
        ├── raw-rubrics.json              ← Case 级公共（evals run score-case 生成）
        ├── shared-refined-rubrics.json   ← Case 级公共（Step 1 生成，所有 CLI 共用）
        └── <cli>/                        ← manifest.clis 中的每个 CLI 各一个目录
            ├── output.log
            ├── status.json
            ├── doc-content.md
            ├── screenshots/
            ├── scoring-prompt.txt
            └── rubric-scores.json

注意：本地 trace 信息是 storage 格式的 JSONL 文件，位于 eval-runs/.traces/ 目录下，记录 LLM 完成调用过程。

下一步推荐

• /eval-progress - 查看运行进度
• /eval-report - 生成报告

参考 Skills

• eval-config - 配置管理
• eval-auth - CLI 认证
• eval-case - 测试用例管理

Troubleshooting

没有可用的 CLI 工具插件

• 报错 “No CLI tool plugins installed” → 先安装：evals plugin install <package-name>
• 查看已安装 CLI：evals plugin list --type cli-tool

CLI 执行失败

• 确认 CLI 已安装并认证：evals run validate
• 确认 PATH 已设置：subAgent 内 which {cli} 应返回 {data_dir}/bin/{cli} 下的路径
• 沙箱已禁用：检查当前平台 settings 中沙箱为关闭状态

storage 连接失败

• 检查配置：evals config show
• 测试连接：evals config test

截图显示登录页面

• 先执行浏览器登录：evals auth browser-login <cli_name>（需要浏览器能力插件）
• Cookie 过期需重新登录

JSON 解析失败

• 确保评分输出使用 JSON.stringify
• 避免在 reason 字段中使用未转义的双引号
• 使用「」替代双引号

运行目录找不到

• 使用 --run-dir 指定路径：evals report data <id> --run-dir <path>
• 或设置环境变量：export EVALS_RUNS_DIR=<path>