docs: add skill evaluation workbench design

docs/assets/planning-data-driven-loop-v1.svg

@@ -0,0 +1,148 @@
+<svg width="1600" height="900" viewBox="0 0 1600 900" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <marker id="arrow" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto">
+      <path d="M2,2 L10,6 L2,10 Z" fill="#64748b"/>
+    </marker>
+    <marker id="arrowBlue" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto">
+      <path d="M2,2 L10,6 L2,10 Z" fill="#2563eb"/>
+    </marker>
+    <filter id="softShadow" x="-10%" y="-10%" width="120%" height="130%">
+      <feDropShadow dx="0" dy="8" stdDeviation="10" flood-color="#0f172a" flood-opacity="0.10"/>
+    </filter>
+    <style>
+      .title { font: 700 38px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #0f172a; }
+      .subtitle { font: 400 20px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #475569; }
+      .sectionTitle { font: 700 22px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #0f172a; }
+      .stepNo { font: 700 17px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #64748b; }
+      .stepTitle { font: 700 19px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #0f172a; }
+      .stepText { font: 400 14px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #475569; }
+      .badge { font: 700 13px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #9a3412; }
+      .baseTitle { font: 700 24px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #0f172a; }
+      .baseMain { font: 700 28px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #1e293b; }
+      .baseSub { font: 400 18px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #475569; }
+      .chip { font: 600 15px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #334155; }
+      .loopLabel { font: 600 17px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #2563eb; }
+    </style>
+  </defs>
+
+  <rect width="1600" height="900" fill="#f8fafc"/>
+
+  <text x="800" y="72" text-anchor="middle" class="title">planning 模型数据驱动迭代链路</text>
+  <text x="800" y="108" text-anchor="middle" class="subtitle">从问题发现到模型改进：数据开发 + AutoResearch + Agent 平台底座的全流程提效</text>
+
+  <!-- Main entry: problem discovery -->
+  <g filter="url(#softShadow)">
+    <rect x="68" y="220" width="190" height="130" rx="18" fill="#ffffff" stroke="#dbeafe" stroke-width="2"/>
+    <text x="95" y="253" class="stepNo">1</text>
+    <text x="163" y="283" text-anchor="middle" class="stepTitle">问题发现</text>
+    <text x="163" y="314" text-anchor="middle" class="stepText">线上 badcase</text>
+    <text x="163" y="337" text-anchor="middle" class="stepText">评测错误 / 指标异常</text>
+  </g>
+
+  <!-- Data development module -->
+  <g filter="url(#softShadow)">
+    <rect x="300" y="170" width="690" height="230" rx="24" fill="#eef6ff" stroke="#bfdbfe" stroke-width="2"/>
+    <text x="645" y="205" text-anchor="middle" class="sectionTitle">数据开发提效</text>
+    <text x="645" y="232" text-anchor="middle" class="stepText">把问题转成可训练、可评测的数据资产</text>
+  </g>
+
+  <!-- AutoResearch module -->
+  <g filter="url(#softShadow)">
+    <rect x="1040" y="170" width="455" height="230" rx="24" fill="#f5f3ff" stroke="#ddd6fe" stroke-width="2"/>
+    <text x="1267" y="205" text-anchor="middle" class="sectionTitle">AutoResearch</text>
+    <text x="1267" y="232" text-anchor="middle" class="stepText">planning 模型迭代与结构分析</text>
+  </g>
+
+  <!-- Step boxes: data development -->
+  <g>
+    <rect x="330" y="265" width="140" height="95" rx="16" fill="#ffffff" stroke="#bfdbfe" stroke-width="1.5"/>
+    <text x="350" y="292" class="stepNo">2</text>
+    <text x="400" y="316" text-anchor="middle" class="stepTitle">线上数据挖掘</text>
+    <text x="400" y="342" text-anchor="middle" class="stepText">rid / session</text>
+    <text x="400" y="362" text-anchor="middle" class="stepText">prompt / output</text>
+  </g>
+
+  <g>
+    <rect x="500" y="265" width="150" height="95" rx="16" fill="#fff7ed" stroke="#fed7aa" stroke-width="1.8"/>
+    <text x="520" y="292" class="stepNo">3</text>
+    <text x="575" y="316" text-anchor="middle" class="stepTitle">问题分析</text>
+    <text x="575" y="342" text-anchor="middle" class="stepText">归因 / 标签边界</text>
+    <rect x="536" y="352" width="78" height="24" rx="12" fill="#ffedd5" stroke="#fdba74"/>
+    <text x="575" y="369" text-anchor="middle" class="badge">人工 Review</text>
+  </g>
+
+  <g>
+    <rect x="680" y="265" width="140" height="95" rx="16" fill="#ffffff" stroke="#bfdbfe" stroke-width="1.5"/>
+    <text x="700" y="292" class="stepNo">4</text>
+    <text x="750" y="316" text-anchor="middle" class="stepTitle">数据构造</text>
+    <text x="750" y="342" text-anchor="middle" class="stepText">训练样本</text>
+    <text x="750" y="362" text-anchor="middle" class="stepText">评测样本 / 边界样例</text>
+  </g>
+
+  <g>
+    <rect x="850" y="265" width="115" height="95" rx="16" fill="#ffffff" stroke="#bfdbfe" stroke-width="1.5"/>
+    <text x="868" y="292" class="stepNo">5</text>
+    <text x="907" y="316" text-anchor="middle" class="stepTitle">格式转换</text>
+    <text x="907" y="342" text-anchor="middle" class="stepText">CSV / JSONL</text>
+    <text x="907" y="362" text-anchor="middle" class="stepText">eval set</text>
+  </g>
+
+  <!-- Step boxes: autoresearch -->
+  <g>
+    <rect x="1072" y="265" width="155" height="95" rx="16" fill="#ffffff" stroke="#ddd6fe" stroke-width="1.5"/>
+    <text x="1092" y="292" class="stepNo">6</text>
+    <text x="1149" y="316" text-anchor="middle" class="stepTitle">planning 模型迭代</text>
+    <text x="1149" y="342" text-anchor="middle" class="stepText">训练 / 评测</text>
+    <text x="1149" y="362" text-anchor="middle" class="stepText">配置实验</text>
+  </g>
+
+  <g>
+    <rect x="1262" y="265" width="200" height="95" rx="16" fill="#fff7ed" stroke="#fed7aa" stroke-width="1.8"/>
+    <text x="1282" y="292" class="stepNo">7</text>
+    <text x="1362" y="316" text-anchor="middle" class="stepTitle">结构分析 / 结果分析</text>
+    <text x="1362" y="342" text-anchor="middle" class="stepText">指标拆解 / 回归验证</text>
+    <rect x="1323" y="352" width="78" height="24" rx="12" fill="#ffedd5" stroke="#fdba74"/>
+    <text x="1362" y="369" text-anchor="middle" class="badge">人工 Review</text>
+  </g>
+
+  <!-- Straight arrows -->
+  <path d="M258 285 L318 285" stroke="#64748b" stroke-width="3" fill="none" marker-end="url(#arrow)"/>
+  <path d="M470 312 L492 312" stroke="#64748b" stroke-width="3" fill="none" marker-end="url(#arrow)"/>
+  <path d="M650 312 L672 312" stroke="#64748b" stroke-width="3" fill="none" marker-end="url(#arrow)"/>
+  <path d="M820 312 L842 312" stroke="#64748b" stroke-width="3" fill="none" marker-end="url(#arrow)"/>
+  <path d="M965 312 L1064 312" stroke="#64748b" stroke-width="3" fill="none" marker-end="url(#arrow)"/>
+  <path d="M1227 312 L1254 312" stroke="#64748b" stroke-width="3" fill="none" marker-end="url(#arrow)"/>
+
+  <!-- Feedback loop -->
+  <path d="M1362 402 C1362 500 1070 505 820 505 C465 505 163 485 163 365" stroke="#2563eb" stroke-width="3" stroke-dasharray="8 8" fill="none" marker-end="url(#arrowBlue)"/>
+  <text x="760" y="486" text-anchor="middle" class="loopLabel">新 badcase / 新边界 / 新样本 / 新策略回流</text>
+
+  <!-- Platform base -->
+  <g filter="url(#softShadow)">
+    <rect x="90" y="570" width="1410" height="210" rx="28" fill="#ffffff" stroke="#cbd5e1" stroke-width="2"/>
+    <text x="795" y="615" text-anchor="middle" class="baseTitle">ZK Data Agent 平台底座</text>
+    <text x="795" y="663" text-anchor="middle" class="baseMain">Agent Loop + Skill + 工具链 + 记忆 + Jupyter 工作区</text>
+    <text x="795" y="699" text-anchor="middle" class="baseSub">通过 Agent Loop 调度 Skill 和工具，连接线上数据、执行环境与产物沉淀</text>
+
+    <g>
+      <rect x="205" y="725" width="140" height="34" rx="17" fill="#f1f5f9"/>
+      <text x="275" y="748" text-anchor="middle" class="chip">线上日志工具</text>
+      <rect x="375" y="725" width="120" height="34" rx="17" fill="#f1f5f9"/>
+      <text x="435" y="748" text-anchor="middle" class="chip">标签知识</text>
+      <rect x="525" y="725" width="150" height="34" rx="17" fill="#f1f5f9"/>
+      <text x="600" y="748" text-anchor="middle" class="chip">数据格式转换</text>
+      <rect x="705" y="725" width="120" height="34" rx="17" fill="#f1f5f9"/>
+      <text x="765" y="748" text-anchor="middle" class="chip">会话沉淀</text>
+      <rect x="855" y="725" width="130" height="34" rx="17" fill="#f1f5f9"/>
+      <text x="920" y="748" text-anchor="middle" class="chip">运行态观测</text>
+      <rect x="1015" y="725" width="155" height="34" rx="17" fill="#f1f5f9"/>
+      <text x="1092" y="748" text-anchor="middle" class="chip">账号 / 工作区隔离</text>
+      <rect x="1200" y="725" width="160" height="34" rx="17" fill="#f1f5f9"/>
+      <text x="1280" y="748" text-anchor="middle" class="chip">训练评测工具链</text>
+    </g>
+  </g>
+
+  <!-- Thin connector from business flow to base -->
+  <path d="M795 526 L795 565" stroke="#94a3b8" stroke-width="2" stroke-dasharray="5 6"/>
+  <text x="825" y="548" class="stepText">平台能力支撑全链路</text>
+</svg>

docs/assets/planning-data-driven-loop-v2.svg

@@ -0,0 +1,133 @@
+<svg width="1600" height="900" viewBox="0 0 1600 900" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <marker id="arrow" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto">
+      <path d="M2,2 L10,6 L2,10 Z" fill="#64748b"/>
+    </marker>
+    <marker id="arrowBlue" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto">
+      <path d="M2,2 L10,6 L2,10 Z" fill="#2563eb"/>
+    </marker>
+    <marker id="arrowPurple" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto">
+      <path d="M2,2 L10,6 L2,10 Z" fill="#7c3aed"/>
+    </marker>
+    <filter id="softShadow" x="-10%" y="-10%" width="120%" height="130%">
+      <feDropShadow dx="0" dy="8" stdDeviation="10" flood-color="#0f172a" flood-opacity="0.10"/>
+    </filter>
+    <style>
+      .title { font: 700 38px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #0f172a; }
+      .subtitle { font: 400 20px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #475569; }
+      .sectionTitle { font: 700 22px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #0f172a; }
+      .sectionSub { font: 400 14px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #64748b; }
+      .stepNo { font: 700 17px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #64748b; }
+      .stepTitle { font: 700 19px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #0f172a; }
+      .stepText { font: 400 14px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #475569; }
+      .badge { font: 700 13px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #9a3412; }
+      .loopLabel { font: 600 17px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #2563eb; }
+      .iterLabel { font: 700 16px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #6d28d9; }
+      .base { font: 600 18px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif; fill: #475569; }
+    </style>
+  </defs>
+
+  <rect width="1600" height="900" fill="#f8fafc"/>
+
+  <text x="800" y="76" text-anchor="middle" class="title">planning 模型数据驱动迭代链路</text>
+  <text x="800" y="112" text-anchor="middle" class="subtitle">从问题发现到模型改进：数据开发 + AutoResearch 的全流程提效</text>
+
+  <!-- Step 1 -->
+  <g filter="url(#softShadow)">
+    <rect x="70" y="265" width="185" height="120" rx="18" fill="#ffffff" stroke="#dbeafe" stroke-width="2"/>
+    <text x="94" y="297" class="stepNo">1</text>
+    <text x="162" y="323" text-anchor="middle" class="stepTitle">问题发现</text>
+    <text x="162" y="351" text-anchor="middle" class="stepText">线上 badcase</text>
+    <text x="162" y="373" text-anchor="middle" class="stepText">评测错误 / 指标异常</text>
+  </g>
+
+  <!-- Data development module -->
+  <g filter="url(#softShadow)">
+    <rect x="300" y="190" width="640" height="250" rx="24" fill="#eef6ff" stroke="#bfdbfe" stroke-width="2"/>
+    <text x="620" y="226" text-anchor="middle" class="sectionTitle">数据开发提效</text>
+    <text x="620" y="252" text-anchor="middle" class="sectionSub">把问题转成可训练、可评测的数据资产</text>
+  </g>
+
+  <!-- Data development steps -->
+  <g>
+    <rect x="335" y="300" width="150" height="105" rx="16" fill="#ffffff" stroke="#bfdbfe" stroke-width="1.5"/>
+    <text x="358" y="329" class="stepNo">2</text>
+    <text x="410" y="352" text-anchor="middle" class="stepTitle">线上数据挖掘</text>
+    <text x="410" y="379" text-anchor="middle" class="stepText">rid / session</text>
+    <text x="410" y="399" text-anchor="middle" class="stepText">prompt / output</text>
+  </g>
+
+  <g>
+    <rect x="535" y="300" width="155" height="105" rx="16" fill="#fff7ed" stroke="#fed7aa" stroke-width="1.8"/>
+    <text x="558" y="329" class="stepNo">3</text>
+    <text x="612" y="352" text-anchor="middle" class="stepTitle">问题分析</text>
+    <text x="612" y="379" text-anchor="middle" class="stepText">归因 / 标签边界</text>
+    <rect x="573" y="389" width="78" height="24" rx="12" fill="#ffedd5" stroke="#fdba74"/>
+    <text x="612" y="406" text-anchor="middle" class="badge">人工 Review</text>
+  </g>
+
+  <g>
+    <rect x="740" y="300" width="165" height="105" rx="16" fill="#ffffff" stroke="#bfdbfe" stroke-width="1.5"/>
+    <text x="763" y="329" class="stepNo">4</text>
+    <text x="822" y="352" text-anchor="middle" class="stepTitle">数据构造</text>
+    <text x="822" y="379" text-anchor="middle" class="stepText">样本生成 / 格式转换</text>
+    <text x="822" y="399" text-anchor="middle" class="stepText">训练集 / 评测集</text>
+  </g>
+
+  <!-- AutoResearch module -->
+  <g filter="url(#softShadow)">
+    <rect x="990" y="190" width="450" height="250" rx="24" fill="#f5f3ff" stroke="#ddd6fe" stroke-width="2"/>
+    <text x="1215" y="226" text-anchor="middle" class="sectionTitle">AutoResearch</text>
+    <text x="1215" y="252" text-anchor="middle" class="sectionSub">planning 模型迭代与结构分析</text>
+  </g>
+
+  <!-- AutoResearch steps -->
+  <g>
+    <rect x="1028" y="300" width="165" height="105" rx="16" fill="#ffffff" stroke="#ddd6fe" stroke-width="1.5"/>
+    <text x="1051" y="329" class="stepNo">5</text>
+    <text x="1110" y="352" text-anchor="middle" class="stepTitle">planning 模型迭代</text>
+    <text x="1110" y="379" text-anchor="middle" class="stepText">训练 / 评测</text>
+    <text x="1110" y="399" text-anchor="middle" class="stepText">配置实验</text>
+  </g>
+
+  <g>
+    <rect x="1248" y="300" width="160" height="105" rx="16" fill="#fff7ed" stroke="#fed7aa" stroke-width="1.8"/>
+    <text x="1271" y="329" class="stepNo">6</text>
+    <text x="1328" y="352" text-anchor="middle" class="stepTitle">结构分析 / 结果分析</text>
+    <text x="1328" y="379" text-anchor="middle" class="stepText">指标拆解 / 回归验证</text>
+    <rect x="1289" y="389" width="78" height="24" rx="12" fill="#ffedd5" stroke="#fdba74"/>
+    <text x="1328" y="406" text-anchor="middle" class="badge">人工 Review</text>
+  </g>
+
+  <!-- Step 7 online -->
+  <g filter="url(#softShadow)">
+    <rect x="1128" y="520" width="175" height="100" rx="18" fill="#ffffff" stroke="#cbd5e1" stroke-width="2"/>
+    <text x="1152" y="550" class="stepNo">7</text>
+    <text x="1215" y="576" text-anchor="middle" class="stepTitle">模型上线</text>
+    <text x="1215" y="604" text-anchor="middle" class="stepText">发布 / 观察 / 回流</text>
+  </g>
+
+  <!-- Main arrows -->
+  <path d="M255 325 L326 325" stroke="#64748b" stroke-width="3" fill="none" marker-end="url(#arrow)"/>
+  <path d="M485 352 L526 352" stroke="#64748b" stroke-width="3" fill="none" marker-end="url(#arrow)"/>
+  <path d="M690 352 L731 352" stroke="#64748b" stroke-width="3" fill="none" marker-end="url(#arrow)"/>
+  <path d="M905 352 L1019 352" stroke="#64748b" stroke-width="3" fill="none" marker-end="url(#arrow)"/>
+
+  <!-- Iteration loop between 5 and 6 -->
+  <path d="M1195 325 C1222 292 1250 292 1275 319" stroke="#7c3aed" stroke-width="3" fill="none" marker-end="url(#arrowPurple)"/>
+  <path d="M1276 385 C1248 424 1218 424 1194 391" stroke="#7c3aed" stroke-width="3" fill="none" marker-end="url(#arrowPurple)"/>
+  <text x="1218" y="286" text-anchor="middle" class="iterLabel">循环迭代</text>
+
+  <!-- From 6 to 7 -->
+  <path d="M1328 405 C1328 480 1260 498 1225 514" stroke="#64748b" stroke-width="3" fill="none" marker-end="url(#arrow)"/>
+
+  <!-- Feedback loop from 7 to 1 -->
+  <path d="M1128 570 C920 690 520 690 270 585 C175 545 142 470 154 395" stroke="#2563eb" stroke-width="3" stroke-dasharray="8 8" fill="none" marker-end="url(#arrowBlue)"/>
+  <text x="650" y="660" text-anchor="middle" class="loopLabel">新 badcase / 新边界 / 新样本 / 新策略回流</text>
+
+  <!-- Light platform support bar -->
+  <g>
+    <rect x="140" y="752" width="1320" height="58" rx="18" fill="#f1f5f9" stroke="#e2e8f0" stroke-width="1"/>
+    <text x="800" y="788" text-anchor="middle" class="base">ZK Data Agent 支撑：通过 Agent Loop 调度 Skill 和工具，连接线上数据、执行环境与产物沉淀</text>
+  </g>
+</svg>

docs/technical-architecture/13-skill-evaluation-workbench.md

@@ -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。

docs/technical-architecture/README.md

@@ -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)
 
 ## 一句话定位