docs: add skill evaluation workbench design

2026-07-23 16:49:53 +08:00
parent 97e1e1dd48
commit 0e4f5041f1
5 changed files with 733 additions and 0 deletions
@@ -0,0 +1,451 @@
+# 13. Skill 评测实验台设计
+
+## 1. 背景
+
+当前快慢分流优化需要完成一条完整链路：
+
+```text
+已有评测集
+  -> 使用现成 Skill 判断快慢
+  -> 支持单条和批量运行
+  -> 对比人工标签和模型判断
+  -> 查看分歧及判定依据
+  -> 更新 Skill 或切换模型
+  -> 重新评测并比较变化
+```
+
+这里讨论的是离线优化和评估场景。评测过程允许 Agent 使用完整 Agent Loop，重点是判断质量、依据可追溯和标准持续收敛。线上快慢路由的耗时、成本和部署形态属于后续独立问题。
+
+本设计假设快慢分流 Skill 已经存在。实验台负责稳定调用和评估 Skill，不负责定义 Skill 内部的分类标准。
+
+## 2. 目标
+
+实验台需要支持：
+
+- 单条输入调用指定 Skill，返回判断、理由和执行记录。
+- 上传 CSV、XLSX 或 JSONL，配置字段映射后批量运行。
+- 选择模型和不可变的 Skill 版本。
+- 后台并发执行，支持暂停、继续、取消和失败重试。
+- 自动计算总体、分类别和分垂域指标。
+- 集中查看人工与模型分歧，并进行人工复核。
+- 查看模型声明的 Skill 判定依据和实际访问记录。
+- 对比不同 Skill 版本或模型版本的修正与退化。
+- 导出原始结果、复核结果和版本对比结果。
+
+实验台不承担：
+
+- 在线请求的实时路由。
+- 快系统能力或分类原则的编写。
+- 将每个普通 Skill 自动转成页面应用。
+- 修改现有聊天 Agent 的会话和运行流程。
+
+## 3. 总体架构
+
+```mermaid
+flowchart LR
+    UI["快慢分流评测页面"] --> EXP["Evaluation Service"]
+    API["Skill Run API"] --> EXP
+
+    EXP --> MAP["Dataset Mapping"]
+    EXP --> SNAP["Skill Snapshot"]
+    EXP --> SCHED["Batch Scheduler"]
+
+    SCHED --> RUNNER["Headless Skill Runner"]
+    RUNNER --> AGENT["LocalCodingAgent"]
+    RUNNER --> MODEL["指定模型"]
+    RUNNER --> SKILL["固定 Skill 快照"]
+
+    EXP --> STORE["Evaluation Store"]
+    STORE --> RESULT["指标 / 分歧 / 复核 / 版本对比"]
+```
+
+新增能力由五个部分组成：
+
+1. `Evaluation Service`：管理数据集、实验配置、运行和结果。
+2. `Dataset Mapping`：把不同格式的数据转换为统一 case。
+3. `Skill Snapshot`：固定每次实验使用的 Skill 内容。
+4. `Headless Skill Runner`：使用现有 Agent Core 在后台执行指定 Skill。
+5. `Batch Scheduler`：拆分、并发和恢复批量任务。
+
+## 4. 与现有 Agent 的隔离
+
+现有聊天链路保持不变：
+
+```text
+/api/chat
+  -> AgentState
+  -> account/session-scoped LocalCodingAgent
+  -> 聊天 session 和活动流
+```
+
+评测链路新增独立入口：
+
+```text
+/api/evaluations
+  -> EvaluationRuntime
+  -> evaluation-scoped LocalCodingAgent
+  -> 评测任务、case 结果和内部执行记录
+```
+
+两条链路可以复用：
+
+- `LocalCodingAgent`
+- `ModelConfig`
+- Skill loader
+- Tool handler
+- `OutputSchemaConfig`
+- 模型兼容层
+
+评测链路必须独立管理：
+
+- Agent 实例。
+- Session 命名空间。
+- 数据库记录。
+- 运行队列。
+- 并发和资源配额。
+- Skill 快照。
+
+评测产生的内部 Agent session 不进入左侧聊天会话列表，也不读取聊天历史、用户记忆或当前聊天 session 状态。
+
+代码隔离只能保证功能不互相污染。批量任务仍可能争用模型服务资源，因此评测任务需要独立 worker pool、并发上限和低于聊天请求的调度优先级。有条件时可以为评测配置独立模型地址。
+
+## 5. 数据集字段映射
+
+评测文件格式由数据来源决定，不应写进 Skill，也不应要求用户临时组织成提示词。
+
+上传文件后，系统先读取表头和样本，用户把源字段映射到统一字段：
+
+| 统一字段 | 说明 | 必填 |
+|---|---|---|
+| `case_id` | case 唯一标识 | 否，可自动生成 |
+| `query` | 当前用户 query | 是 |
+| `gold_route` | 人工快慢标签 | 评测时必填 |
+| `history` | 对话历史 | 否 |
+| `context` | 设备、位置等上下文 | 否 |
+| `domain` | 垂域 | 否 |
+| `request_id` | 线上 RID | 否 |
+| `metadata` | 其他保留字段 | 否 |
+| `source_row` | 原始行 | 自动保留 |
+
+页面需要支持：
+
+- 列名自动推荐。
+- 手动选择源字段。
+- JSON path，例如 `data.query`。
+- 标签值转换，例如 `快/慢`、`0/1`、`fast/slow`。
+- 必要的字段组合和简单转换。
+- 转换后样本预览。
+- 缺失字段、非法标签和重复 ID 校验。
+
+确认后的映射保存为可复用的 `Dataset Mapping Profile`。Skill Runner 只接收统一 case，不感知原始文件的列名和格式。
+
+统一 case 示例：
+
+```json
+{
+  "case_id": "001",
+  "query": "到目的地电量够不够",
+  "gold_route": "fast",
+  "history": [],
+  "context": {},
+  "domain": "地图导航",
+  "request_id": "",
+  "metadata": {},
+  "source_row": {}
+}
+```
+
+## 6. Skill 版本与快照
+
+实验不能只记录 Skill 名称。Skill 内容会持续更新，同一个名称在不同时间可能代表不同标准。
+
+每次创建实验时生成不可变快照，并记录：
+
+```json
+{
+  "skill_name": "fast-slow-routing",
+  "repository": "zk-data-agent",
+  "git_commit": "abc1234",
+  "content_hash": "sha256:...",
+  "snapshot_id": "skill_snapshot_xxx",
+  "status": "committed"
+}
+```
+
+版本来源可以是：
+
+- 当前部署版本。
+- 指定 Git commit。
+- 指定 Git tag。
+- 尚未提交的草稿快照。
+
+快照建议存放在：
+
+```text
+.port_sessions/evaluations/skill_snapshots/
+  <skill-name>/
+    <commit-or-content-hash>/
+```
+
+运行旧版本时不能切换当前项目分支，也不能覆盖线上 Skill。对于 Git 中的历史版本，可以通过 `git archive` 提取单个 Skill 目录到快照缓存。
+
+草稿版本允许参与实验，但页面必须明确标记“未提交”，并使用内容哈希保证同一次实验可复现。
+
+评测 Agent 始终从快照加载 Skill；聊天 Agent 继续从当前部署目录加载 Skill，两者互不影响。
+
+## 7. Headless Skill Runner
+
+`Headless` 表示没有聊天页面，不表示减少 Agent 能力。
+
+Runner 接收：
+
+```json
+{
+  "skill_snapshot_id": "skill_snapshot_xxx",
+  "model_id": "model_xxx",
+  "case": {
+    "case_id": "001",
+    "query": "到目的地电量够不够"
+  }
+}
+```
+
+Runner 的执行过程：
+
+1. 从快照读取指定 Skill。
+2. 创建独立的评测 Agent 实例和 session。
+3. 直接把指定 Skill 注入当前任务，不等待模型自行召回 Skill。
+4. 把统一 case 作为任务输入。
+5. 按 Skill 约定执行完整 Agent Loop。
+6. 保存最终结果、执行事件、工具调用和用量。
+7. 将最终输出归一化为评测结果。
+
+统一评测结果至少包含：
+
+```json
+{
+  "case_id": "001",
+  "prediction": "fast",
+  "reason": "当前快系统已有对应能力",
+  "confidence": 0.95,
+  "evidence_refs": [
+    "knowledge/地图能力.md#到达电量预估"
+  ],
+  "status": "completed",
+  "raw_output": "",
+  "agent_session_id": ""
+}
+```
+
+单条判断创建一个 Agent Run。批量判断把每条 case 拆成独立 Agent Run，避免样本间上下文污染。
+
+## 8. 批量调度
+
+批量调度器负责：
+
+- 把数据集拆成独立 case 任务。
+- 使用受控并发执行。
+- 保存每条 case 的状态和重试次数。
+- 单条失败不终止整个实验。
+- 支持暂停、继续和取消。
+- 服务重启后从数据库恢复未完成任务。
+- 只重跑失败项、分歧项或用户选中的 case。
+
+任务状态：
+
+```text
+pending
+running
+completed
+failed
+cancelled
+```
+
+聊天请求和评测请求需要独立并发池。评测批量任务默认低优先级，避免影响当前在线使用者。
+
+## 9. 判定依据与可追溯性
+
+页面需要回答“模型依据 Skill 的哪部分作出判断”，但不能把完整模型思考当作可靠因果证据。
+
+实验台展示两类事实：
+
+1. **实际访问记录**：Agent 读取了哪些 Skill 文件、知识文件和章节。
+2. **模型声明的判定依据**：最终结果中的 `evidence_refs`。
+
+生成 Skill 快照时，系统为 Markdown 标题和知识文件建立稳定引用，例如：
+
+```text
+SKILL.md#判断流程
+knowledge/地图能力.md#到达电量预估
+knowledge/边界.md#开放式行程规划
+```
+
+评测 Runner 的统一任务约定要求最终结果返回引用。页面将引用解析为可点击的原文片段。
+
+如果模型没有引用明确规则，页面展示“未引用具体依据”，并允许按此条件筛选。这类 case 本身就是标准缺失或模型未正确使用 Skill 的候选问题。
+
+## 10. 页面信息架构
+
+页面采用“实验配置、结果页签、单条详情”三层结构。
+
+### 10.1 实验配置
+
+顶部配置区包含：
+
+- 数据集。
+- 字段映射。
+- Skill 和版本。
+- 模型。
+- case 数量。
+- 并发配置。
+- 开始、暂停、继续、取消、克隆实验。
+
+运行开始后配置区折叠，避免占用结果空间。
+
+### 10.2 结果页签
+
+| 页签 | 主要内容 |
+|---|---|
+| 概览 | 运行进度、总体指标、混淆矩阵、快慢分布、分垂域指标 |
+| 分歧 | 人工标签与模型判断不一致、低置信、无明确依据的 case |
+| 全部 Case | 全量结果、状态、筛选、排序和导出 |
+| 版本对比 | 不同 Skill 或模型实验之间的修正、退化和指标变化 |
+
+### 10.3 单条详情抽屉
+
+点击一条 case 后展示：
+
+1. 原始数据和统一后的输入。
+2. 人工标签、模型判断、置信度和理由。
+3. Skill 判定依据及原文片段。
+4. 实际读取文件和工具调用。
+5. 默认折叠的完整 Agent 执行记录。
+6. 人工复核结果和备注。
+
+人工复核至少支持：
+
+- 人工原标签正确。
+- 模型判断正确。
+- 分类标准存在歧义。
+- 快系统能力信息缺失。
+- 暂不确定。
+
+## 11. 实验与版本对比
+
+一个实验由以下对象共同确定：
+
+```text
+数据集版本
+ 字段映射版本
+ Skill 快照
+ 模型版本
+ 执行参数
+```
+
+同一数据集可以克隆实验并替换 Skill 或模型：
+
+```text
+实验 A：Skill abc1234 + 模型 A
+实验 B：Skill def5678 + 模型 A
+实验 C：Skill def5678 + 模型 B
+```
+
+版本对比需要展示：
+
+- 总体指标变化。
+- 各垂域指标变化。
+- 从错误变正确的 case。
+- 从正确变错误的 case。
+- 判断未变化但理由变化的 case。
+- 新增或消失的无依据结果。
+
+这样才能形成“评测、发现分歧、更新 Skill、重新评测”的优化闭环。
+
+## 12. 数据存储
+
+评测运行状态适合使用独立 SQLite 数据库，例如：
+
+```text
+.port_sessions/evaluations/evaluations.db
+```
+
+核心实体：
+
+```text
+evaluation_datasets
+dataset_mapping_profiles
+skill_snapshots
+evaluation_experiments
+evaluation_cases
+evaluation_case_runs
+evaluation_results
+evaluation_reviews
+```
+
+数据库保存可查询状态、关系和人工复核结果。上传原文件、Skill 快照、导出文件和较大的 Agent transcript 保存在实验目录，数据库记录路径和摘要。
+
+## 13. API 轮廓
+
+```text
+POST /api/evaluations/datasets
+POST /api/evaluations/datasets/{id}/mapping
+
+POST /api/evaluations/skill-snapshots
+GET  /api/evaluations/skill-snapshots
+
+POST /api/evaluations
+GET  /api/evaluations/{id}
+POST /api/evaluations/{id}/start
+POST /api/evaluations/{id}/pause
+POST /api/evaluations/{id}/resume
+POST /api/evaluations/{id}/cancel
+
+GET  /api/evaluations/{id}/results
+POST /api/evaluations/{id}/retry
+POST /api/evaluations/{id}/reviews
+GET  /api/evaluations/{id}/export
+
+POST /api/evaluations/compare
+```
+
+API 同时服务 Web 页面和外部批量调用。单条调用可以创建只包含一个 case 的轻量实验，复用相同运行与记录机制。
+
+## 14. 实施顺序
+
+### P1：后台单条运行
+
+- Skill 快照。
+- Headless Skill Runner。
+- 单条输入和统一结果。
+- 独立于聊天 session 的运行记录。
+
+### P2：数据集与批量调度
+
+- 文件上传和字段映射。
+- 批量拆分、并发、暂停、恢复和重试。
+- 基础指标和导出。
+
+### P3：评测页面
+
+- 实验配置。
+- 概览、分歧、全部 Case。
+- 单条详情和人工复核。
+- Skill 依据引用。
+
+### P4：版本对比
+
+- 克隆实验。
+- Skill 和模型版本矩阵。
+- 修正、退化和理由变化分析。
+
+## 15. 验收标准
+
+- 开启评测任务后，现有聊天 Agent 可以正常创建、继续和停止会话。
+- 600 条批量任务不会出现在聊天会话列表。
+- 不同输入格式可以通过字段映射转换为统一 case。
+- 每次实验可以确认具体 Skill commit 或内容哈希。
+- Skill 更新后，历史实验仍能读取原快照并复现配置。
+- 单条失败不会中断全量任务，服务重启后可以恢复。
+- 页面可以定位人工与模型分歧，并查看简短理由和 Skill 引用。
+- 可以比较两个实验的修正项和退化项。
+- 批量评测的并发不会明显拖慢聊天 Agent。
@@ -16,6 +16,7 @@
 9. [外部系统 Skill：ELK、SQL、模型迭代](09-external-skills.md)
 10. [Agent 记忆机制调研与对比](10-memory-research.md)
 11. [运行中输入队列与 Runtime Guidance 注入](12-runtime-guidance-queue.md)
+12. [Skill 评测实验台设计](13-skill-evaluation-workbench.md)

 ## 一句话定位