assistant-eval

assistant-eval 设计方案 v1

1. 目标

在 xiaoyu/assistant-eval 构建基于 Spring 的智能体评测系统，用于评估 assistant-agent 在知识库场景下的能力，并支持回归对比。

2. 范围

本阶段包含：

• 评测框架设计
• 用例规范
• 评分规范
• 执行流程

本阶段不包含：

• 全量代码实现
• CI 接入
• LLM judge 细节实现

3. 核心原则

• 工程正确性与智能体能力双轨评分
• 用例与评分解耦（Case / Rubric 分离）
• 结果可追溯（保留证据与失败标签）
• 支持基线对比（Regression）

4. 系统架构

• 触发层：
  • CLI: assistant-cli eval run --suite knowledge-v1
  • HTTP: POST /api/eval/run
• 评测服务 assistant-eval:
  • EvalRunner: 执行编排
  • AgentClient: 调用 assistant-agent
  • TraceCollector: 采集 tool calls/回答/时延
  • RuleScorer: 硬规则评分
  • CapabilityScorer: 能力评分
  • ReportService: 输出 JSON/Markdown 报告
  • RegressionService: 与基线对比
• 被测系统：assistant-agent

5. 目录规划

assistant-eval/
  src/main/java/com/assistant/eval/
    config/
    controller/
    model/
    service/
      scoring/
      report/
      regression/
    runner/
  src/main/resources/
    evals/suites/
    evals/cases/
    evals/rubrics/
  reports/

6. 数据模型

• EvalCase: 单题定义（输入、期望、评分、通过条件）
• EvalSuite: 题集定义（case 引用、标签）
• EvalTrace: 执行证据（tool_calls、turn_count、latency、final_answer）
• EvalRunResult: 单题结果（分数、通过、失败标签）
• EvalSuiteResult: 整套结果（通过率、维度均分、Top failures）
• RegressionResult: 与 baseline 差异

7. 评分体系

双轨评分：

• 工程轨 40%：工具调用、参数、效率、错误处理
• 能力轨 60%：可执行性、总结质量、检索相关性、沉淀质量、交互体验

硬失败（直接 fail）：

• 编造知识
• 未确认即覆盖
• 明显不相关却声称命中

8. 评测集分布（20题）

• 基础质量 4
• 意图交互 4
• 沉淀质量 6
• 复盘复习 4
• 鲁棒安全 2

9. 执行流程

1. 加载 suite 与 case
2. 逐题执行并采集 trace
3. RuleScorer + CapabilityScorer 打分
4. 聚合 suite 结果
5. 落盘 JSON/Markdown 报告
6. 可选 baseline diff

10. API 设计

• POST /api/eval/run
• GET /api/eval/results
• GET /api/eval/results/{runId}
• GET /api/eval/results/{runId}/diff/{baselineRunId}
• GET /api/eval/cases

11. 配置项

• eval.agent.default-url
• eval.cases-dir
• eval.results-dir
• eval.default-timeout-ms
• eval.max-concurrency
• eval.judge.mode (rule-only / capability-assisted)
• eval.regression.max-score-drop

12. 分步执行计划

1. 定稿 Case/Rubric/YAML 规范（已完成）
2. 实现最小 Runner + RuleScorer（已完成）
3. 增加报告与回归比较（进行中）
4. 增加能力评分与 20 题全量运行（待开始）

12.1 第 2 步子步骤（避免遗忘）

• 2.1 EvalCase / EvalSuite 模型定义（已完成）
• 2.2 YAML 用例加载器 CaseLoaderService（已完成）
• 2.3 YAML 规范校验器（必填字段/权重/阈值）（已完成）
• 2.4 最小 EvalRunnerService（先支持单 case）（已完成）
• 2.5 RuleScorerService（先实现 must/must_not/hard constraints）（已完成）
• 2.6 本地最小可运行验证 + 单测（已完成）
• 2.7 单题执行集成测试入口 SingleCaseExecutionIT（已完成）

12.3 第 3 步子步骤（避免遗忘）

• 3.1 ReportService 单题结果落盘 JSON（已完成）
• 3.2 执行链路接入报告输出（已完成）
• 3.3 结果列表与读取接口（已完成）
• 3.4 baseline 对比模型与服务（已完成）
• 3.5 回归规则（score drop / pass rate drop）实现（已完成）

12.2 当前执行位点

• 当前正在执行：P2-2 评测集扩展至 20 题并补回归样例

13. 后续开发置顶计划（重排）

P0（立即）

• P0-1 增加执行入口：POST /api/eval/run（单 case 执行 + 报告落盘 + 返回 runId/reportPath）（已完成）
• P0-2 AgentClientService 切换流式接口 /api/chat/stream，采集 TOOL_RESULT 事件（已完成）

P1（高优）

• P1-1 扩展执行结果模型：toolCalls、turnCount、dimensionScores、evidence（已完成）
• P1-2 RuleScorerService 接入工具正确性规则（是否调用预期工具、参数关键字段）（已完成）
• P1-3 最小 CapabilityScorer 骨架落地并产出维度分（已完成）

P2（随后）

• P2-1 增加 Suite 批量执行（runSuite）与汇总报告（已完成）
• P2-2 评测集扩展至 20 题并补回归样例