astron-eval 0.0.1

package/skills/skill-driven-eval/SKILL.md

@@ -0,0 +1,456 @@
+---
+name: skill-driven-eval
+description: 评估和比较不同 Claude 模型在执行技能时的表现。当用户询问哪个模型最适合执行特定技能、想要比较模型在技能任务上的表现，或需要在效果与成本之间取得平衡时，使用此技能。该技能使用不同模型运行测试用例，收集时间和 token 指标，通过盲评估对输出进行评分，并提供全面的比较报告。
+user-invocable: false
+---
+
+# 技能驱动评估
+
+一个用于评估不同 Claude 模型在执行另一个技能时表现如何的技能。
+
+## 概述
+
+当用户问"我应该在 X 技能中使用哪个模型？"或"对于 Y 任务，opus 值得多花那些成本吗？"时，此技能通过以下方式帮助回答：
+
+1. 理解目标技能的目的和要求
+2. 生成具有可验证断言的适当测试用例
+3. 使用多个模型运行每个测试用例
+4. 通过盲评估对输出进行评分（评分者不知道哪个模型产生了哪个输出）
+5. 收集时间和 token 使用指标
+6. 将结果汇总成带有数据驱动建议的比较报告
+
+## 关键：盲评估
+
+为了防止评分者偏见，评估必须是**盲**的：
+
+- **执行子智能体**不应该知道它们代表哪个模型——它们只是执行任务
+- **评分子智能体**不应该知道它们评分的输出是由哪个模型产生的
+- 只有 **MainAgent** 知道匿名标识符与实际模型名称之间的映射
+
+有关实现细节，请参阅下面的"信息隔离"部分。
+
+## 何时使用此技能
+
+在以下情况下使用此技能：
+- 用户询问哪个模型最适合执行特定技能
+- 用户想要比较模型表现（效果、速度、成本）
+- 用户提到"模型比较"、"哪个模型"、"opus vs sonnet"或类似内容
+- 用户想要评估对于特定技能，更昂贵的模型是否值得其成本
+
+---
+
+## 阶段 0：开始之前
+
+**检查现有工作区。** 如果找到，询问用户如何继续。
+
+---
+
+## 阶段 1：理解目标技能
+
+1. **阅读目标技能的 SKILL.md** 以了解：
+   - 技能做什么
+   - 它期望什么输入
+   - 它产生什么输出
+   - 任何特殊要求或约束
+
+2. **与用户确认**：
+   - 要评估哪个技能
+   - 要比较哪些模型（用户可能配置了自定义模型映射）
+   - 运行多少个测试用例（默认：3）
+   - 任何要测试的特定场景
+
+---
+
+## 阶段 2：生成测试用例
+
+生成 2-4 个测试用例，这些用例：
+- 覆盖技能功能的不同方面
+- 有清晰、可验证的成功标准
+- 是现实的（真实用户会问的内容）
+- 范围从简单到复杂
+
+对于每个测试用例，定义：
+- **prompt**：任务描述
+- **expected_output**：成功是什么样子
+- **assertions**：关于输出的具体、可验证的陈述
+
+将测试用例作为 `evals.json` 保存到工作区：
+
+```json
+{
+  "target_skill": "skill-name",
+  "target_skill_path": "/path/to/skill",
+  "models_to_compare": ["model-a", "model-b"],
+  "evals": [
+    {
+      "id": 1,
+      "name": "descriptive-name",
+      "prompt": "用户的任务提示词",
+      "expected_output": "预期结果的描述",
+      "assertions": [
+        "输出包含 X",
+        "技能完成了 Y",
+        "没有发生错误"
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## 阶段 3：执行测试用例
+
+### 信息隔离策略
+
+**MainAgent 维护一个秘密映射**（永不与子智能体共享）：
+```json
+{
+  "run-001": {"model": "opus", "eval_id": 1},
+  "run-002": {"model": "sonnet", "eval_id": 1},
+  "run-003": {"model": "opus", "eval_id": 2},
+  "run-004": {"model": "sonnet", "eval_id": 2}
+}
+```
+
+**目录结构使用匿名运行 ID**：
+```
+workspace/
+├── run-001/
+│   └── outputs/
+├── run-002/
+│   └── outputs/
+└── mapping.json  （由 MainAgent 在评分完成后创建）
+```
+
+**永远不要在以下位置包含模型名称：**
+- 目录名称
+- 文件名称
+- 传递给执行或评分子智能体的内容
+
+### 步骤 1：生成执行子智能体
+
+**重要：** 不要同时生成超过 3 个子智能体。同时生成超过 3 个子智能体可能导致稳定性问题。
+
+如果你有超过 3 次总运行（例如，3 个测试用例 × 2 个模型 = 6 次运行）：
+- 将它们分成 3 个一组
+- 等待每批完成后再生成下一批
+- 在内部映射中跟踪哪些运行在哪个批次中
+
+对于每个测试用例和每个模型，生成一个子智能体：
+
+```
+执行此任务：
+- 技能路径：<target-skill-path>
+- 任务：<eval prompt>
+- 将输出保存到：<workspace>/run-<ID>/outputs/
+```
+
+**重要：** 不要在提示词的任何地方提及模型名称。模型参数是通过子智能体的 `model` 配置设置的，而不是在任务描述中。
+
+### 步骤 2：当运行进行中时，与用户沟通
+
+不要只是静默等待。利用这段时间：
+1. 向用户解释正在发生什么
+2. 审查和完善断言
+3. 准备评分上下文
+
+### 步骤 3：为每个完成的运行提取执行记录和时间数据（必需 - 不要跳过）
+
+**这是一个阻塞门。你必须在进入阶段 4（评分）之前为每次运行完成此操作。** 没有 transcript.md，评分者无法评估执行质量。
+
+对于每个完成的运行：
+
+1. **找到会话文件** - 定位子智能体的 `.jsonl` 会话文件。如果使用 `claude -p` CLI，找到最近修改的会话：
+   ```bash
+   # 按修改时间找到最新的会话文件
+   ls -lt ~/.claude/projects/<project-name>/*.jsonl | head -1
+   ```
+   通过检查会话的第一条消息内容（它应该包含评估提示词）将 会话与运行匹配。
+
+2. **提取执行记录**（必需）：
+   ```bash
+   python <skill-driven-eval-path>/scripts/extract_transcript.py <session.jsonl> --output <workspace>/run-<ID>/transcript.md
+   ```
+
+3. **提取时间数据** - 解析会话文件以提取 `duration_ms` 和 `total_tokens`：
+   - **duration_ms**：从会话中的第一个和最后一个时间戳计算
+   - **total_tokens**：从使用字段中汇总所有 `input_tokens` 和 `output_tokens`
+
+**timing.json 格式：**
+```json
+{
+  "run_id": "run-001",
+  "total_tokens": 84852,
+  "duration_ms": 23332
+}
+```
+
+**验证：** 在生成任何评分者之前，确认每次运行都存在 `<workspace>/run-<ID>/transcript.md`。如果缺少任何执行记录，停止并先提取它。
+
+---
+
+## 阶段 4：评分输出（盲评估）
+
+### 步骤 0：验证所有执行记录存在（必需）
+
+在生成任何评分者之前，验证每次运行都有执行记录：
+
+```bash
+for dir in <workspace>/run-*/; do
+  if [ ! -f "$dir/transcript.md" ]; then
+    echo "缺少：$dir/transcript.md — 在评分前提取它！"
+    exit 1
+  fi
+done
+echo "所有执行记录已验证。"
+```
+
+**如果缺少任何 transcript.md，返回阶段 3 步骤 3 并提取它。不要在没有执行记录的情况下继续评分。**
+
+### 步骤 1：生成评分子智能体
+
+**重要：** 与执行子智能体相同的限制。对于每次运行，生成一个评分子智能体：
+
+```
+对此输出进行评分：
+- 预期：<assertions 列表>
+- 输出目录：<workspace>/run-<ID>/outputs/
+- 执行记录：<workspace>/run-<ID>/transcript.md
+- 将评分结果保存到：<workspace>/run-<ID>/grading.json
+
+不要推测是哪个模型或配置产生了此输出。
+仅根据每个预期是否被满足来进行评估。
+```
+
+**重要：** 评分者提示词不能包含：
+- 模型名称
+- 关于此运行代表哪个配置的任何提示
+- 比较性语言如"这是 opus 运行"
+
+### 步骤 2：评分输出格式
+
+每个评分者产生 `grading.json`：
+
+```json
+{
+  "run_id": "run-001",
+  "expectations": [
+    {
+      "text": "输出包含 X",
+      "passed": true,
+      "evidence": "在 output.txt 第 5 行找到 X"
+    }
+  ],
+  "summary": {
+    "passed": 3,
+    "failed": 1,
+    "total": 4,
+    "pass_rate": 0.75
+  }
+}
+```
+
+---
+
+## 阶段 5：汇总和报告
+
+**重要：脚本执行路径**
+
+此技能的脚本位于技能目录本身。执行脚本时，使用技能目录的**绝对路径**：
+
+```
+<skill-driven-eval-path>/
+├── SKILL.md
+├── scripts/
+│   └── aggregate_results.py
+└── eval-viewer/
+    └── generate_report.py
+```
+
+将 `<skill-driven-eval-path>` 替换为此技能的实际路径（例如 `~/.claude/skills/skill-driven-eval` 或技能安装的路径）。
+
+### 步骤 1：创建模型映射
+
+现在评分已完成，MainAgent 创建 `mapping.json`：
+
+```json
+{
+  "run-001": {"model": "opus", "eval_id": 1, "eval_name": "表单填写"},
+  "run-002": {"model": "sonnet", "eval_id": 1, "eval_name": "表单填写"}
+}
+```
+
+### 步骤 2：汇总结果
+
+使用**绝对路径**运行汇总脚本：
+
+```bash
+# 使用技能脚本目录的绝对路径
+python <skill-driven-eval-path>/scripts/aggregate_results.py <workspace> --mapping <workspace>/mapping.json
+```
+
+示例：
+```bash
+python /home/user/.claude/skills/skill-driven-eval/scripts/aggregate_results.py article-writing-eval-workspace --mapping article-writing-eval-workspace/mapping.json
+```
+
+这会在工作区目录中生成 `benchmark.json` 和 `benchmark.md`。
+
+### 步骤 3：分析结果
+
+阅读基准数据并展示模式：
+
+- 哪个模型整体表现最好？
+- 是否有特定测试用例中某个模型表现出色或遇到困难？
+- 质量、速度和成本之间的权衡是什么？
+- 是否有任何异常（高方差、意外结果）？
+
+### 步骤 4：生成并提供可视化报告
+
+**这是一个必需步骤。** 生成 HTML 报告并通过 HTTP 提供服务，以便用户可以查看详细结果：
+
+```bash
+# 使用绝对路径生成并提供报告
+nohup python <skill-driven-eval-path>/eval-viewer/generate_report.py <workspace> \
+  --serve \
+  --port 3118 \
+  > /dev/null 2>&1 &
+REPORT_PID=$!
+```
+
+或者如果无法提供服务，生成静态文件：
+
+```bash
+python -m eval-viewer.generate_report <workspace> --output <workspace>/report.html
+```
+
+然后告诉用户类似这样的内容：
+> "我已在你的浏览器中打开了详细比较报告。你可以查看：
+> - **摘要标签页**：整体模型表现比较
+> - **详情标签页**：每次评估的细分和单次运行输出
+>
+> 查看完成后，请回到这里告诉我你的想法。"
+
+### 步骤 5：向用户展示发现
+
+提供关键发现的**简短口头摘要**：
+
+- 哪个模型获得了最高的通过率
+- 值得注意的时间和 token 差异
+- 基于数据的关键建议
+
+**然后引导用户查看网络报告以获取完整详情：**
+
+> "如需详细统计、每次评估的细分和单次运行输出，请在浏览器中查看报告。"
+
+**重要：**
+- 不要使用预设结论
+- 客观分析实际数据
+- 建议必须来自测量结果，而不是对模型能力的假设
+- 网络报告包含完整数据——口头摘要只是重点
+
+---
+
+## 工作区结构
+
+```
+<skill-name>-eval-workspace/
+├── evals.json                    # 测试用例定义
+├── mapping.json                  # 模型映射（评分后创建）
+├── run-001/                      # 匿名运行 ID
+│   ├── outputs/                  # 模型的输出
+│   ├── transcript.md             # 人类可读的会话记录
+│   ├── grading.json              # 评分结果
+│   └── timing.json               # 时间数据
+├── run-002/
+│   └── ...
+├── benchmark.json                # 汇总结果（含模型名称）
+├── benchmark.md                  # 人类可读摘要
+└── report.html                   # 可视化比较报告
+```
+
+---
+
+## 成本分析
+
+比较模型时，考虑以下指标：
+
+1. **通过率**：越高越好（质量）
+2. **Token 使用量**：越低越好（成本）
+3. **时间**：越低越好（速度）
+4. **成本效益**：`pass_rate * 1000 / (tokens / 1000)` — 越高越好
+
+**重要：** 这些是要报告的指标，但不要假设哪个模型会在哪个指标上表现出色。让数据说话。
+
+---
+
+## 处理子智能体限制
+
+由于子智能体无法生成进一步的子智能体：
+
+1. **以 3 个为一批生成执行子智能体**（最多 3 个并行以避免稳定性问题）
+2. **等待每批完成**，然后对于每次运行：找到会话文件，提取 transcript.md，捕获时间数据
+3. **在继续之前验证所有执行记录存在**
+4. **以 3 个为一批生成评分子智能体**（在所有执行完成且执行记录准备好之后）
+5. **等待评分完成**
+6. **汇总和报告**（MainAgent 直接执行此操作）
+
+**最大并行度：** 永远不要同时生成超过 3 个子智能体。如果你有 6 次运行（3 次评估 × 2 个模型），分 2 批每批 3 个生成。
+
+---
+
+## 参考文件
+
+所有路径都相对于技能目录（`<skill-driven-eval-path>`）：
+
+- `agents/grader.md` — 如何根据输出评估断言（盲评估）
+- `references/schemas.md` — evals、grading、benchmark 的 JSON 结构
+- `scripts/aggregate_results.py` — 将结果汇总到 benchmark.json
+- `scripts/extract_transcript.py` — 从会话文件中提取人类可读的执行记录
+- `eval-viewer/generate_report.py` — 生成 HTML 报告并通过 HTTP 提供
+
+**执行脚本：**
+
+```bash
+# 为运行提取执行记录（每次运行完成后执行此操作）
+python <skill-driven-eval-path>/scripts/extract_transcript.py <session.jsonl> --output <workspace>/run-<ID>/transcript.md
+
+# 汇总结果（使用绝对路径）
+python <skill-driven-eval-path>/scripts/aggregate_results.py <workspace> --mapping <workspace>/mapping.json
+
+# 生成并提供报告（使用绝对路径）
+python <skill-driven-eval-path>/eval-viewer/generate_report.py <workspace> --serve --port 3118
+
+# 或仅生成静态 HTML
+python <skill-driven-eval-path>/eval-viewer/generate_report.py <workspace> --output <workspace>/report.html
+```
+
+---
+
+## 示例用法
+
+**用户：**"我应该在 pdf 技能中使用哪个模型？"
+
+**MainAgent：**
+1. 读取 pdf 技能的 SKILL.md
+2. 生成 3 个测试用例
+3. 以 3 个为一批生成 6 个执行子智能体（3 个测试用例 × 2 个模型），使用匿名运行 ID
+4. 向用户解释："正在运行 6 次评估..."
+5. 每批完成后：对于每次运行，找到会话 `.jsonl` 文件并提取执行记录
+6. 在继续之前验证所有 `run-<ID>/transcript.md` 文件存在
+7. 以 3 个为一批生成 6 个评分子智能体（盲评估）
+8. 评分完成后创建模型映射
+9. 汇总结果并分析模式
+10. 报告发现
+
+---
+
+## 关键原则
+
+1. **盲评估**：评分者不得知道哪个模型产生了输出
+2. **信息隔离**：模型名称永不暴露给子智能体
+3. **数据驱动**：建议来自测量结果，而非假设
+4. **客观**：展示事实和权衡，让用户决定
+5. **全面**：覆盖多个场景和指标
+6. **透明**：在建议旁边展示原始数据

package/skills/skill-driven-eval/agents/grader.md

@@ -0,0 +1,144 @@
+# 评分智能体（盲评估）
+
+根据执行记录和输出评估预期结果。
+
+## 关键：盲评估
+
+你在**不知道是哪个模型或配置产生了输出**的情况下对输出进行评分。这对于防止评估中的偏见至关重要。
+
+- 不要推测是哪个模型产生了这个输出
+- 不要根据输出的风格、长度或质量对其来源做出假设
+- 仅根据每个预期是否被满足来进行评估
+- 不要将此输出与你可能见过的其他输出进行比较
+
+## 角色
+
+评分者审查执行记录和输出文件，然后确定每个预期是通过还是失败。为每个判断提供清晰的证据。
+
+## 输入
+
+你在提示词中接收以下参数：
+
+- **expectations**：要评估的预期列表（字符串）
+- **outputs_dir**：包含执行输出文件的目录
+- **transcript_path**：执行记录文件的路径（可选）
+- **run_id**：此运行的匿名标识符（不是模型名称）
+
+## 流程
+
+### 步骤 1：阅读执行记录（如果可用）
+
+1. 如果提供了记录文件，请阅读它
+2. 注意任务提示词、执行步骤和最终结果
+3. 识别任何记录的问题或错误
+
+### 步骤 2：检查输出文件
+
+1. 列出 outputs_dir 中的文件
+2. 阅读/检查与预期相关的每个文件
+3. 注意内容、结构和质量
+
+### 步骤 3：评估每个断言
+
+对于每个预期：
+
+1. **搜索证据**：在执行记录和输出中搜索
+2. **确定结论**：
+   - **通过**：有明确证据表明预期为真，且证据反映了真正的任务完成
+   - **失败**：没有证据，或证据与预期相矛盾，或证据是表面的
+3. **引用证据**：引用具体文本或描述你的发现
+
+### 步骤 4：提取和验证声明
+
+除了预定义的预期外，从输出中提取隐含的声明：
+
+1. **提取声明**：从执行记录和输出中提取
+2. **验证每个声明**：对照可用证据进行验证
+3. **标记无法验证的声明**
+
+### 步骤 5：写入评分结果
+
+将结果保存到 `{outputs_dir}/../grading.json`（outputs_dir 的同级目录）。
+
+## 评分标准
+
+**以下情况通过**：
+- 执行记录或输出清楚地证明预期为真
+- 可以引用具体证据
+- 证据反映了真正的实质内容，而不仅仅是表面合规
+
+**以下情况失败**：
+- 没有找到预期的证据
+- 证据与预期相矛盾
+- 无法从可用信息中验证预期
+- 证据是表面的
+
+**当不确定时**：通过的责任在于预期本身。
+
+## 输出格式
+
+写入一个具有以下结构的 JSON 文件：
+
+```json
+{
+  "run_id": "run-001",
+  "expectations": [
+    {
+      "text": "输出包含名称 'John Smith'",
+      "passed": true,
+      "evidence": "在 output.txt 中找到：'提取的名称：John Smith, Sarah Johnson'"
+    },
+    {
+      "text": "电子表格在单元格 B10 中有 SUM 公式",
+      "passed": false,
+      "evidence": "没有创建电子表格。输出是一个文本文件。"
+    }
+  ],
+  "summary": {
+    "passed": 2,
+    "failed": 1,
+    "total": 3,
+    "pass_rate": 0.67
+  },
+  "execution_metrics": {
+    "tool_calls": {
+      "Read": 5,
+      "Write": 2,
+      "Bash": 8
+    },
+    "total_tool_calls": 15,
+    "total_steps": 6,
+    "errors_encountered": 0,
+    "output_chars": 12450
+  },
+  "claims": [
+    {
+      "claim": "表单有 12 个可填写字段",
+      "type": "factual",
+      "verified": true,
+      "evidence": "在 field_info.json 中统计到 12 个字段"
+    }
+  ],
+  "issues": []
+}
+```
+
+## 字段说明
+
+- **run_id**：此运行的匿名标识符（不要包含模型信息）
+- **expectations[]**：带证据的已评分预期
+  - `text`：预期文本
+  - `passed`：布尔值
+  - `evidence`：支持或反驳的证据
+- **summary**：汇总通过/失败计数
+- **execution_metrics**：工具使用和输出大小（可选）
+- **claims**：从输出中提取并验证的声明（可选）
+- **issues**：观察到的问题或值得注意的行为（可选）
+
+## 指导原则
+
+- **客观**：基于证据而非假设做出判断
+- **具体**：引用支持你判断的确切文本
+- **彻底**：检查执行记录和输出文件
+- **一致**：对每个预期应用相同的标准
+- **保持盲评**：不要试图猜测是哪个模型产生了这个输出

package/skills/skill-driven-eval/eval-viewer/__init__.py

@@ -0,0 +1 @@
+"""Eval viewer for skill-driven-eval."""