astron-eval 0.0.1

package/skills/skill-driven-eval/references/schemas.md

@@ -0,0 +1,282 @@
+# JSON 模式
+
+本文档定义了 skill-driven-eval 使用的 JSON 模式。
+
+---
+
+## evals.json
+
+定义用于跨模型评估技能的测试用例。
+
+```json
+{
+  "target_skill": "example-skill",
+  "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"
+      ]
+    }
+  ]
+}
+```
+
+**字段：**
+- `target_skill`：被评估的技能名称
+- `target_skill_path`：技能目录的绝对路径
+- `models_to_compare`：要比较的模型标识符列表（例如 "opus"、"sonnet"、"haiku" 或自定义模型 ID）
+- `evals[].id`：唯一的整数标识符
+- `evals[].name`：测试用例的描述性名称
+- `evals[].prompt`：要执行的任务
+- `evals[].expected_output`：成功的人类可读描述
+- `evals[].assertions`：可验证的语句列表
+
+---
+
+## mapping.json
+
+**对盲评估至关重要。** 将匿名运行 ID 映射到实际模型名称。由 MainAgent 在评分完成后创建，以防止评分者偏见。
+
+位于 `<workspace>/mapping.json`。
+
+```json
+{
+  "run-001": {
+    "model": "opus",
+    "eval_id": 1,
+    "eval_name": "表单填写"
+  },
+  "run-002": {
+    "model": "sonnet",
+    "eval_id": 1,
+    "eval_name": "表单填写"
+  },
+  "run-003": {
+    "model": "opus",
+    "eval_id": 2,
+    "eval_name": "文本提取"
+  },
+  "run-004": {
+    "model": "sonnet",
+    "eval_id": 2,
+    "eval_name": "文本提取"
+  }
+}
+```
+
+**字段：**
+- 键：匿名运行 ID（例如 "run-001"）
+- `model`：实际的模型标识符
+- `eval_id`：此运行所属的评估 ID
+- `eval_name`：人类可读的评估名称
+
+**重要：** 此文件必须在评分完成后才能创建。评分子智能体不能访问此信息。
+
+---
+
+## timing.json
+
+单次运行的时间数据。位于 `<workspace>/run-<ID>/timing.json`。
+
+```json
+{
+  "run_id": "run-001",
+  "total_tokens": 84852,
+  "duration_ms": 23332,
+  "total_duration_seconds": 23.3,
+  "start_time": "2026-03-19T10:30:00Z",
+  "end_time": "2026-03-19T10:32:45Z"
+}
+```
+
+**字段：**
+- `run_id`：匿名运行标识符（不是模型名称）
+- `total_tokens`：消耗的总 token 数（来自任务通知）
+- `duration_ms`：持续时间（毫秒）
+- `total_duration_seconds`：持续时间（秒）
+
+---
+
+## grading.json
+
+评分智能体的输出。位于 `<workspace>/run-<ID>/grading.json`。
+
+**关键：** 不能包含模型名称或任何关于哪个模型产生了输出的识别信息。
+
+```json
+{
+  "run_id": "run-001",
+  "expectations": [
+    {
+      "text": "输出包含名称 'John Smith'",
+      "passed": true,
+      "evidence": "在 output.txt 中找到：'提取的名称：John Smith'"
+    },
+    {
+      "text": "电子表格有 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,
+    "errors_encountered": 0
+  },
+  "issues": []
+}
+```
+
+**字段：**
+- `run_id`：匿名运行标识符（不要包含模型）
+- `expectations[]`：带证据的已评分预期
+  - `text`：预期文本
+  - `passed`：布尔值
+  - `evidence`：支持或反驳的证据
+- `summary`：汇总统计数据
+- `execution_metrics`：工具使用（可选）
+- `issues`：观察到的问题（可选）
+
+---
+
+## benchmark.json
+
+汇总比较结果。位于 `<workspace>/benchmark.json`。
+
+由 MainAgent 在结合 grading.json 与 mapping.json 后生成。
+
+```json
+{
+  "metadata": {
+    "target_skill": "pdf",
+    "target_skill_path": "/path/to/pdf",
+    "models_compared": ["opus", "sonnet"],
+    "timestamp": "2026-03-19T10:30:00Z",
+    "evals_run": [1, 2, 3],
+    "note": "结果基于盲评估"
+  },
+
+  "runs": [
+    {
+      "run_id": "run-001",
+      "eval_id": 1,
+      "eval_name": "表单填写",
+      "model": "opus",
+      "result": {
+        "pass_rate": 0.85,
+        "passed": 6,
+        "failed": 1,
+        "total": 7,
+        "time_seconds": 42.5,
+        "tokens": 38000,
+        "tool_calls": 18,
+        "errors": 0
+      },
+      "expectations": [
+        {"text": "...", "passed": true, "evidence": "..."}
+      ],
+      "issues": []
+    }
+  ],
+
+  "model_summary": {
+    "opus": {
+      "pass_rate": {"mean": 0.85, "stddev": 0.05, "min": 0.80, "max": 0.90},
+      "time_seconds": {"mean": 45.0, "stddev": 12.0, "min": 32.0, "max": 58.0},
+      "tokens": {"mean": 42000, "stddev": 4000, "min": 36000, "max": 48000}
+    },
+    "sonnet": {
+      "pass_rate": {"mean": 0.72, "stddev": 0.08, "min": 0.65, "max": 0.80},
+      "time_seconds": {"mean": 32.0, "stddev": 8.0, "min": 24.0, "max": 42.0},
+      "tokens": {"mean": 28000, "stddev": 3000, "min": 24000, "max": 32000}
+    }
+  },
+
+  "comparison": {
+    "pass_rate_delta": "+0.13",
+    "time_delta": "+13.0s",
+    "token_delta": "+14000",
+    "cost_efficiency": {
+      "opus": 20.2,
+      "sonnet": 25.7
+    }
+  },
+
+  "recommendations": [
+    {
+      "scenario": "高风险任务",
+      "recommended_model": "opus",
+      "reason": "13% 更高的通过率证明了关键操作的成本合理性"
+    },
+    {
+      "scenario": "大批量任务",
+      "recommended_model": "sonnet",
+      "reason": "批量操作具有更好的成本效益"
+    }
+  ],
+
+  "notes": [
+    "Opus 达到 85% 通过率，而 Sonnet 为 72%",
+    "Sonnet 平均快 30%"
+  ]
+}
+```
+
+**字段：**
+- `metadata`：关于评估运行的信息
+- `runs[]`：单次运行结果（映射后现在包含模型名称）
+- `model_summary`：每个模型的统计汇总
+- `comparison`：模型之间的差异和成本效益分数
+- `recommendations`：数据驱动的建议（非预设）
+- `notes`：分析者观察
+
+---
+
+## 成本效益分数
+
+成本效益计算公式：`pass_rate * 1000 / (tokens / 1000)`
+
+越高越好。这表示"每千 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. MainAgent 生成执行子智能体 → 输出到 `run-XXX/outputs/`
+2. MainAgent 生成评分子智能体 → 评分到 `run-XXX/grading.json`
+3. MainAgent 创建 `mapping.json`（所有评分完成后）
+4. MainAgent 运行聚合 → 结合评分 + 映射 → `benchmark.json`

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

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

package/skills/skill-driven-eval/scripts/__main__.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Main entry point for skill-driven-eval scripts.
+
+Usage:
+    python -m scripts aggregate <workspace>
+    python -m scripts test
+"""
+
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python -m scripts <command> [args]")
+        print("Commands:")
+        print("  aggregate <workspace>  - Aggregate results into benchmark.json")
+        print("  test                   - Run test with sample data")
+        sys.exit(1)
+
+    command = sys.argv[1]
+
+    if command == "aggregate":
+        if len(sys.argv) < 3:
+            print("Usage: python -m scripts aggregate <workspace>")
+            sys.exit(1)
+
+        from aggregate_results import generate_benchmark, generate_markdown
+        import json
+
+        workspace = Path(sys.argv[2])
+        if not workspace.exists():
+            print(f"Error: Directory not found: {workspace}")
+            sys.exit(1)
+
+        benchmark = generate_benchmark(workspace)
+
+        # Write benchmark.json
+        output_json = workspace / "benchmark.json"
+        with open(output_json, "w") as f:
+            json.dump(benchmark, f, indent=2)
+        print(f"Generated: {output_json}")
+
+        # Write benchmark.md
+        output_md = workspace / "benchmark.md"
+        markdown = generate_markdown(benchmark)
+        with open(output_md, "w") as f:
+            f.write(markdown)
+        print(f"Generated: {output_md}")
+
+        # Print summary
+        print(f"\nSummary:")
+        for model, summary in benchmark["model_summary"].items():
+            pr = summary["pass_rate"]["mean"]
+            print(f"  {model}: {pr*100:.1f}% pass rate")
+
+    elif command == "test":
+        from test_aggregate import main as test_main
+        test_main()
+
+    else:
+        print(f"Unknown command: {command}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()