@vectorx/cloud-eval

v1.0.1

Published

2 months ago

VectorX Cloud Agent 评测框架 - 支持基准测试、Agent Skill 出码测试、Fun Skill 出码测试

0High
0Medium
0Low

fe.xiaohongshu

@vectorx/cloud-eval

VectorX Cloud Agent 评测框架。用于量化评估 AI Coding Agent 的输出质量，支持对 Prompt、Rules、Skill 文档的修改效果做可复现的数字化验证。

工程介绍

解决什么问题

当你修改了 AGENTS.md、SKILL.md 或 system prompt 后，如何判断改动是好是坏？靠肉眼 review 代码样本不够客观，也难以复现。

@vectorx/cloud-eval 提供一套结构化评测机制：

定义测试用例（JSONL 格式）：描述输入 prompt 和期望行为
运行评测：让 Agent 执行用例，自动打分
生成报告：控制台 + JSON + HTML 三种格式，数字直接对比

核心设计原则

无需真实 Agent 也能跑：静态模式直接分析 playground/ 中已有的代码，零 API 费用
复用现有校验脚本：validate-agent-code.js / validate-fun-code.js 直接作为评分器，不重造轮子
两条路径灵活切换：日常用静态模式（秒级），迭代验证用模型模式（分钟级）
报告可被程序读取：JSON 报告嵌入标准 schema，HTML 报告内嵌 window.__EVAL_RESULT__ 供外部界面解析

输出产物

每次运行评测后，在 eval-results/ 目录下自动生成两个文件：

eval-results/
├── agent-skill-2026-03-14T09-28-42.json   ← 机器可读报告
└── agent-skill-2026-03-14T09-28-42.html   ← 人类可读报告

JSON 报告（`*.json`）

完整结构化结果，可被 CI/CD 解析或外部评测界面读取。

{
  "suiteId": "agent-skill",
  "suiteName": "Agent 出码测试（Agent Skill）",
  "startedAt": "2026-03-14T09:28:39.000Z",
  "finishedAt": "2026-03-14T09:28:42.000Z",
  "totalDurationMs": 2847,
  "suiteScore": 89,           // 套件总分 0-100
  "totalCases": 15,
  "passedCases": 15,
  "failedCases": 0,
  "errorCases": 0,
  "dimensionSummary": {       // 各维度平均分
    "意图识别": 28,
    "工作流合规": 100,
    "代码规范合规": 100,
    "任务完成率": 100,
    "步骤效率": 100
  },
  "caseResults": [
    {
      "caseId": "agent-skill-basic-001",
      "caseTitle": "生成基础 Agent 入口",
      "totalScore": 89,       // 单用例总分 0-100
      "passed": true,         // totalScore >= 60 为通过
      "durationMs": 52,
      "dimensionScores": [    // 各维度详情
        {
          "dimension": "代码规范合规",
          "score": 1.0,       // 0-1
          "weight": 0.35,
          "details": "代码规范合规: 100%（8通过 0警告 0错误）",
          "subScores": [...]
        }
        // ...
      ]
    }
  ],
  "config": { ... }           // 运行配置快照
}

HTML 报告（`*.html`）

单文件，双击在浏览器打开，无需任何服务器。

功能：

综合得分卡片 + 各维度进度条
得分趋势折线图（含 60 分及格红线）
用例列表可按通过/未通过/异常过滤
点击用例展开各维度子分详情
亮色/暗色主题切换
内嵌 window.__EVAL_RESULT__ JSON，供外部评测界面直接 fetch 解析

报告预览示意：

╔══════════════════════════════════════╗
║ 📊 Agent 出码测试     2026-03-14     ║
╠════════╦══════╦══════╦══════╦══════╣
║ 89/100 ║ 15通过║ 0失败 ║ 0异常 ║100%║
╠══════════════════════════════════════╣
║ 意图识别      [███░░░░░░░]  28       ║
║ 工作流合规    [██████████] 100       ║
║ 代码规范合规  [██████████] 100       ║
╚══════════════════════════════════════╝

控制台输出

══════════════════════════════════════════════════════════════════════
  📊 评测报告: Agent 出码测试（Agent Skill）
══════════════════════════════════════════════════════════════════════
  运行时间: 3/14/2026, 5:28:39 PM
  总耗时:   2s    总用例数: 15    通过率: 15/15 (100%)    套件总分: 89/100

  ── 各维度得分 ──
  意图识别             [█████░░░░░░░░░░░░░░░]  28
  工作流合规            [████████████████████] 100
  代码规范合规           [████████████████████] 100

  ── 用例详情 ──
  ✅ 通过 (15)
    [agent-skill-basic-001] 生成基础 Agent 入口 -  89/100 (0s)
    ...
══════════════════════════════════════════════════════════════════════

[eval:agent-skill] ✅ PASS | 总分: 89/100 | 通过率: 100% (15/15) | 耗时: 2s

评测架构

┌─────────────────────────────────────────────────────────────┐
│                      CLI / 代码调用                          │
│  pnpm eval:agent  或  import { runAgentSkillEval } from ... │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    Suite（测试套件）                          │
│  benchmark / agent-skill / fun-skill                        │
│  负责：组装 Scorer 列表，设置权重                             │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                   EvalRunner（运行器）                        │
│  1. 从 datasets/*.jsonl 加载测试用例                          │
│  2. 调用 AgentExecutor 执行每个用例                           │
│  3. 调用各 Scorer 对执行结果评分                              │
│  4. 汇总生成 SuiteRunResult                                  │
└────────┬─────────────────────────────────┬──────────────────┘
         │                                 │
         ▼                                 ▼
┌─────────────────┐             ┌───────────────────────────┐
│  AgentExecutor  │             │        Scorers             │
│                 │             │                            │
│  静态模式：      │             │  TaskSuccessScorer  (40%)  │
│  PlaygroundExe  │             │  ToolUseAccuracyScorer(20%)│
│  直接读代码文件  │             │  CodeQualityScorer  (20%)  │
│                 │             │  StepsEfficiencyScorer(10%)│
│  模型模式：      │             │  RuleComplianceScorer(10%) │
│  CloudAgentExe  │             │                            │
│  调 /api/cloud/ │             │  [Skill 专用]              │
│  v1/agent/run   │             │  IntentRecognitionScorer   │
│                 │             │  SkillWorkflowScorer       │
└─────────────────┘             │  ScriptBasedScorer         │
                                └───────────────────────────┘
                                          │
                                          ▼
                                ┌─────────────────────┐
                                │      Reporter        │
                                │  SummaryReporter     │
                                │  → 控制台彩色输出    │
                                │  HTMLReporter        │
                                │  → *.html 报告       │
                                │  → *.json 报告       │
                                └─────────────────────┘

关键文件说明

| 文件 | 作用 | |------|------| | src/types.ts | 所有类型定义（EvalTestCase / Scorer / AgentExecutor 等） | | src/runner/eval-runner.ts | 核心运行器，加载 JSONL、调度执行、汇总结果 | | src/scorers/script-based.ts | 调用 validate-agent-code.js 脚本的评分器（最关键） | | src/scorers/skill-workflow.ts | 检查 skill → read → write 工作流顺序 | | src/executors/playground-executor.ts | 静态分析 playground/ 中的 Agent 代码 | | src/executors/cloud-agent-executor.ts | 调用本地 Agent 服务做端到端测试 | | src/reporter/html-reporter.ts | 生成单文件 HTML 交互报告 | | datasets/benchmark.jsonl | 16 个基准测试用例 | | datasets/agent-skill.jsonl | 15 个 Agent 出码用例 | | datasets/fun-skill.jsonl | 8 个云函数出码用例（TODO） |

快速开始

环境要求

Node.js >= 20
pnpm >= 9

安装

# 在 monorepo 根目录
pnpm install

最简单的运行方式（零配置，Mock 模式）

cd packages/vectorx-cloud-eval

# 运行 Agent Skill 评测（使用内置 Mock Executor）
pnpm eval:agent

# 运行基准测试
pnpm eval:benchmark

# 运行云函数出码测试（TODO 数据集）
pnpm eval:fun

完成后在 eval-results/ 查看报告。

评测 playground 中的真实代码

# 评测 playground/test-demo 项目的代码规范
pnpm eval:agent -- --mode static --project ../../playground/test-demo

# 批量扫描所有 playground 项目
pnpm eval:playground

# 仅运行特定标签的用例
pnpm eval:agent -- --mode static --project ../../playground/test-demo --tags rule-compliance

端到端模型评测

# Step 1：在另一个终端启动本地 Agent 服务
cd packages/vectorx-function-debugger
pnpm playground:server   # 服务启动在 http://localhost:3000

# Step 2：指定工作区运行模型评测
cd packages/vectorx-cloud-eval
pnpm eval:agent -- --mode model --agent-url http://localhost:3000 \
  --workspace /path/to/your/project

测试套件

`benchmark` — 基准测试

不含 Skill，测试 Agent 的基础通用能力。

| 分类 | 用例数 | 测什么 | |------|--------|--------| | instruction-following | 5 | JSON/Markdown 格式输出、语言要求、长度限制 | | path-access | 4 | 文件读取、目录列举、内容理解 | | tool-use | 3 | 单工具调用、多工具组合、调用顺序 | | basic-code | 4 | JS/TS 代码生成、重构 |

评分维度：任务完成率(40%) / 工具调用准确性(20%) / 代码质量(20%) / 步骤效率(10%) / 规则遵守率(10%)

`agent-skill` — Agent 出码测试

含 openplatform-agent-docs Skill，专项测试 Agent 出码能力。

| 分类 | 用例数 | 测什么 | |------|--------|--------| | basic-agent-code | 3 | 基础/系统提示/工具调用 Agent 生成 | | intent-recognition | 4 | 明确/隐式/描述触发/混合意图识别 | | rule-compliance | 6 | parseInputMsg、user/system content 格式、try/finally、input.history、依赖引用 | | workflow-compliance | 2 | skill → read config → write code 顺序 |

评分维度：意图识别(15%) / 工作流合规(20%) / 代码规范合规(35%) / 任务完成率(20%) / 步骤效率(10%)

代码规范合规维度直接调用 validate-agent-code.js 校验脚本，与人工 review 标准完全一致。

`fun-skill` — 云函数出码测试（TODO）

含 openplatform-fun-docs Skill，骨架已就绪，数据集待补充。

评分维度

通用维度（Benchmark 套件）

| 维度 | 评分器 | 逻辑 | |------|--------|------| | 任务完成率 | TaskSuccessScorer | 无错误 + 有效输出 + 关键词覆盖 + 期望输出匹配 | | 工具调用准确性 | ToolUseAccuracyScorer | 必填工具召回率 + 调用顺序 + 参数匹配 | | 代码质量 | CodeQualityScorer | 错误处理 + 注释率 + 无回调嵌套 + 长度合理 | | 步骤效率 | StepsEfficiencyScorer | 工具调用次数 + 执行耗时 | | 规则遵守率 | RuleComplianceScorer | 禁止/必须模式匹配 |

Skill 专用维度

| 维度 | 评分器 | 逻辑 | |------|--------|------| | 意图识别 | IntentRecognitionScorer | 是否激活正确 Skill + 未误触错误 Skill + 意图关键词 | | 工作流合规 | SkillWorkflowScorer | 步骤完整性(70%) + 步骤顺序(30%) | | 代码规范合规 | ScriptBasedScorer | 调用 validate-*.js，解析「X通过 Y警告 Z错误」|

得分计算公式

单用例总分 = Σ(维度得分 × 维度权重) / Σ(权重) × 100

套件总分   = 平均(所有用例总分)

通过标准   = 单用例总分 >= 60

扩展指南

添加新测试用例

直接编辑 datasets/*.jsonl，每行一个 JSON：

{
  "id": "agent-skill-rule-007",          // 唯一 ID
  "suite": "agent-skill",                // 所属套件
  "category": "rule-compliance",         // 分类
  "title": "禁止手动传 model 参数",       // 标题
  "input": "帮我写一个 Agent，调用 streamText",  // 发给 Agent 的 prompt
  "expectedKeywords": ["streamText"],    // 输出中应包含的关键词
  "expectedCodeRules": [                 // 对应 validate-agent-code.js 规则
    { "ruleId": "streamText", "shouldPass": true }
  ],
  "tags": ["rule", "model-param"],       // 标签，用于过滤
  "weight": 2                            // 用例权重
}

实现自定义 AgentExecutor

import type { AgentExecutor, AgentRunRecord } from '@vectorx/cloud-eval'

class MyCustomExecutor implements AgentExecutor {
  async execute(testCase, config): Promise<AgentRunRecord> {
    // 调用你自己的 Agent
    const output = await myAgent.run(testCase.input)

    return {
      caseId: testCase.id,
      output: output.text,
      toolCalls: output.toolCalls.map(tc => ({
        toolName: tc.name,
        args: tc.args,
      })),
      durationMs: output.elapsedMs,
    }
  }
}

// 使用自定义 Executor 运行
const result = await runAgentSkillEval(new MyCustomExecutor())

实现自定义 Scorer

import type { Scorer, DimensionScore } from '@vectorx/cloud-eval'

class MyCustomScorer implements Scorer {
  readonly name = '自定义维度'
  readonly weight = 0.1

  async score(testCase, record): Promise<DimensionScore> {
    const score = myCheckLogic(record.output)
    return {
      dimension: this.name,
      score,        // 0-1
      weight: this.weight,
      details: `自定义维度: ${Math.round(score * 100)}%`,
    }
  }
}

常见问题

Q：静态模式的「意图识别」和「工作流合规」得分为什么很低？

A：正常现象。静态模式读取已有代码，没有真实的工具调用序列，所以这两个依赖工具调用记录的维度会得低分。静态模式主要看「代码规范合规」维度即可。

Q：运行 eval:agent:model 报连接失败？

A：需要先在另一个终端启动本地服务：

cd packages/vectorx-function-debugger && pnpm playground:server

Q：如何不生成 HTML 报告？

pnpm eval:agent -- --no-html

Q：如何只运行特定用例？

# 按 ID 过滤
pnpm eval:agent -- --case-ids agent-skill-rule-001,agent-skill-rule-002

# 按标签过滤
pnpm eval:agent -- --tags intent-recognition

Q：退出码含义？

| 退出码 | 含义 | |--------|------| | 0 | 套件总分 >= 60，评测通过 | | 1 | 套件总分 < 60，或运行异常 |

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@vectorx/cloud-eval

目录

工程介绍

解决什么问题

核心设计原则

输出产物

JSON 报告（*.json）

HTML 报告（*.html）

控制台输出

评测架构

关键文件说明

快速开始

环境要求

安装

最简单的运行方式（零配置，Mock 模式）

评测 playground 中的真实代码

端到端模型评测

推荐工作流

场景 A：每次修改 Prompt/Rules 后的快速验证

场景 B：新增 Skill 或出码规则后的回归测试

场景 C：批量评测所有 playground 项目（代码质量基线）

场景 D：CI/CD 集成（防止规范退化）

测试套件

benchmark — 基准测试

agent-skill — Agent 出码测试

fun-skill — 云函数出码测试（TODO）

评分维度

通用维度（Benchmark 套件）

Skill 专用维度

得分计算公式

扩展指南

添加新测试用例

实现自定义 AgentExecutor

实现自定义 Scorer

常见问题

JSON 报告（`*.json`）

HTML 报告（`*.html`）

`benchmark` — 基准测试

`agent-skill` — Agent 出码测试

`fun-skill` — 云函数出码测试（TODO）