astron-eval 0.0.1

package/skills/model-evaluation/eval-init.md

@@ -0,0 +1,237 @@
+---
+name: eval-init
+description: Use when starting a new evaluation task or resuming an existing one, before any build or execute operations
+---
+
+# 初始化阶段
+
+## 目标
+
+完成Python环境检测、鉴权验证、会话目录确认后，进入构建阶段。
+
+核心原则：**缓存优先，按序执行，失败即止**。
+
+## 何时使用
+
+- 开始新的评测任务时
+- 继续历史评测任务时
+- 环境或鉴权状态不明时
+
+---
+
+## 阶段完成标志
+
+**验证顺序**（按序执行，任一失败则执行对应任务）：
+
+1. 检查 `{work-dir}/.eval/env.cfg` 存在且字段完整 → 否则执行任务1
+2. 检查 `{work-dir}/.eval/auth.json` 存在且Token有效 → 否则执行任务2
+3. 检查 `{work-dir}/.eval/{session-id}/` 目录存在 → 否则执行任务3
+
+全部通过后，进入构建阶段（加载 `eval-build.md`）。
+
+---
+
+## 任务列表
+
+### 任务1：环境及依赖检测
+
+#### 步骤1：检查环境缓存文件
+
+检查 `{work-dir}/.eval/env.cfg` 是否存在。
+
+- **文件存在** → 进入步骤2（验证缓存有效性）
+- **文件不存在** → 进入步骤3（执行环境检测）
+
+---
+
+#### 步骤2：验证缓存有效性
+
+读取 `{work-dir}/.eval/env.cfg` 文件，检查以下字段：
+
+| 字段 | 要求 |
+|------|------|
+| `python_cmd` | 非空 |
+| `python_env` | 非空 |
+| `deps_required` | 非空 |
+
+- **字段完整** → 设置 `{python-cmd}` 为 `python_cmd` 值，设置 `{python-env}` 为 `python_env` 值，完成本任务
+- **字段缺失** → 缓存无效 → 步骤3
+
+---
+
+#### 步骤3：执行环境检测
+
+调用 [Python 环境检测流程](processes/python-env-process.md)，依次执行：
+
+1. 检测 Python 命令 → 确定 `{python-cmd}`
+2. 检测依赖 → 确保必需依赖已安装
+3. 检测编码环境 → 确定 `{python-env}`
+
+**输出变量**：
+
+| 变量 | 说明 |
+|------|------|
+| `{python-cmd}` | Python 命令（`python3` 或 `python`） |
+| `{python-env}` | 环境变量前缀（Windows GBK 为 `PYTHONUTF8=1 `，其他为空） |
+
+- **检测成功** → 进入步骤4
+- **检测失败** → 根据错误提示用户安装或配置
+
+---
+
+#### 步骤4：生成环境缓存文件
+
+创建 `{work-dir}/.eval/env.cfg`：
+
+```ini
+python_cmd={python-cmd}
+python_env={python-env}
+deps_required=requests
+deps_optional={可选依赖，已安装为pandas,openpyxl，未安装为空}
+# 说明：pandas 用于数据处理，openpyxl 是 pandas 读取 Excel 的引擎
+created_at={当前时间戳}
+```
+
+完成本任务。
+
+---
+
+> **重要提示**：执行脚本时使用 `{python-env}` 前缀
+>
+> 在后续所有脚本调用中，必须使用 `{python-env}{python-cmd}` 格式执行命令：
+>
+> ```bash
+> {python-env}{python-cmd} {skill-dir}/scripts/eval_auth.py check --output {work-dir}/.eval/auth.json
+> ```
+>
+> Windows GBK终端下，`{python-env}` 为 `PYTHONUTF8=1 `，实际执行：`PYTHONUTF8=1 python scripts/eval_auth.py check --output {work-dir}/.eval/auth.json`
+
+---
+
+### 任务2：确保鉴权Token有效
+
+#### 步骤1：检查鉴权文件
+
+检查 `{work-dir}/.eval/auth.json` 是否存在。
+
+- **文件不存在** → 进入步骤2
+- **文件存在** → 进入步骤3
+
+---
+
+#### 步骤2：智能登录授权
+
+**⚠️ 不可跳过**：用户必须在浏览器完成授权后输入授权码，此流程无法绕过。
+
+执行智能登录命令：
+```bash
+{python-env}{python-cmd} {skill-dir}/scripts/eval_auth.py login --config {skill-dir}/scripts/cfg/eval-auth.cfg --output {work-dir}/.eval/auth.json
+```
+
+脚本自动检测运行环境并选择登录模式。
+
+**输出处理**：
+
+| status | 说明 | 后续动作 |
+|--------|------|----------|
+| `success` | 自动完成，Token已获取 | 完成本任务 |
+| `manual_url` | 需手动授权 | 执行下方手动授权流程 |
+
+**手动授权流程**（status=`manual_url`时执行）：
+
+1. 展示输出中的 `login_url`，提示用户访问并完成授权
+2. 等待用户返回授权码（用户主动输入，不使用 AskUserQuestion）
+3. 获取授权码后执行token命令：
+```bash
+{python-env}{python-cmd} {skill-dir}/scripts/eval_auth.py token --code {授权码} --state_token {输出中的state_token} --config {skill-dir}/scripts/cfg/eval-auth.cfg --output {work-dir}/.eval/auth.json
+```
+
+**可选参数**：`--mode auto|manual`（强制指定模式）。
+
+---
+
+#### 步骤3：验证Token有效性
+
+```bash
+{python-env}{python-cmd} {skill-dir}/scripts/eval_auth.py check --output {work-dir}/.eval/auth.json
+```
+
+| status | 说明 | 后续动作 |
+|--------|------|----------|
+| `valid` | Token有效 | 完成本任务 |
+| `invalid` | Token已失效 | 进入步骤2 |
+| `not_found` | 文件不存在 | 进入步骤2 |
+
+---
+
+### 任务3：确认会话目录
+
+#### 步骤1：分析用户意图
+
+结合分析历史对话，分析用户意图。判断如下：
+
+| 用户意图 | 判断依据 | 后续动作 |
+|----------|----------|----------|
+| 新建评测任务 | 对话中提及"新建"、"创建"、"开始新的" | → 步骤3 |
+| 继续旧任务 | 对话中提及会话ID或"继续"某任务 | → 步骤2 |
+| 无法判断 | 无历史对话或意图不明确 | → 步骤2 |
+
+---
+
+#### 步骤2：选择历史会话
+
+扫描并展示历史会话列表，格式：`| 会话ID | 评测场景 | 状态 |`。
+
+- **选择历史任务** → 使用对应的 `{session-id}`，完成本任务
+- **输入 'new'** → 进入步骤3
+
+---
+
+#### 步骤3：创建新会话目录
+
+命名规则：`session-{8位字母数字}`，示例：`session-a3c8f4ci`
+```bash
+session_id="session-$(tr -dc 'a-zA-Z0-9' < /dev/urandom | head -c 8)"
+```
+
+```bash
+mkdir -p {work-dir}/.eval/{session-id}
+```
+
+---
+
+## Red Flags
+
+| 违规行为 | 简洁理由 |
+|----------|----------|
+| 跳过缓存检测 | 缓存优先原则 |
+| 跳过重新授权 | Token失效必须重新授权 |
+| 未验证环境继续执行 | 环境验证是前置条件 |
+
+> 通用违规行为见 [SKILL.md Red Flags](./SKILL.md#red-flags---停止并检查)
+
+**常见借口**：
+
+| 借口 | 现实 |
+|------|------|
+| "评测集可以先问用户" | 评测集属于构建阶段，不可提前询问 |
+| "场景可以提前确认" | 场景属于构建阶段，不可提前询问 |
+
+> 用户明确指明跳转时，可直接进入对应阶段。
+
+## 常见错误
+
+| 错误 | 原因 | 解决方案 |
+|------|------|----------|
+| Python命令不可用 | 未安装Python 3.x | 提示安装Python 3.x |
+| Python版本不兼容 | 系统默认Python 2.x | 创建别名或使用正确命令 |
+| Token已失效 | Token过期或被撤销 | 引导用户重新授权 |
+| 浏览器打开失败 | 服务器终端无图形界面 | 用户手动访问登录链接 |
+| 非交互式终端 | 在管道或脚本中运行 | 使用 `login` 和 `token` 子命令分步执行 |
+| 跳过缓存直接检测 | 忽略步骤顺序 | 严格按步骤1→8顺序执行 |
+
+---
+
+## 变量速查
+
+变量定义见 [SKILL.md 变量速查](./SKILL.md#变量速查)

package/skills/model-evaluation/processes/dimension-process.md

@@ -0,0 +1,207 @@
+---
+name: dimension-process
+description: Use when need to configure evaluation dimensions for case-level or dimension-level evaluation
+---
+
+# 维度配置流程
+
+本文档包含两种评测方式的维度配置流程，由 eval-build.md 任务2步骤3按需调用。
+
+**调用条件**：专家模板匹配失败，需自定义评测配置。
+
+---
+
+## 流程速查
+
+| 编号 | 流程名称 | 触发条件 | 调用方 |
+|------|----------|----------|--------|
+| 流程5 | 定制用例级评测配置 | 用户选择定制用例级评测 | eval-build.md 任务2步骤3 |
+| 流程6 | 通用维度级评测配置 | 用户选择通用维度级评测 | eval-build.md 任务2步骤3 |
+
+---
+
+## 流程5：自定义用例级评测配置
+
+**触发条件**：eval-build.md 任务2步骤2确定评测方式为定制用例级。
+
+**目标**：基于内置用例级评测维度模板，输出维度配置。
+
+> ⚠️ 注意：定制用例级评测只有一个评测维度。
+
+---
+
+### 步骤1：查阅内置用例级评测维度模板
+
+参考 `{skill-dir}/references/内置模板说明.md` 第2.2节"定制用例级评测模板"，读取模板文件：
+```
+{skill-dir}/assets/dimensions/用例级评测维度模板.json
+```
+
+---
+
+### 步骤2：评估模板适配情况
+
+| 情况 | 说明 | 动作 |
+|------|------|------|
+| 完全适配 | 内置模板满足评测场景 | 直接使用内置模板 |
+| 部分适配 | 需调整部分字段内容 | 基于模板调整字段 |
+
+**可调整字段**：
+- `name`：维度名称
+- `description`：维度描述
+- `prompt.role`：评委角色设定
+- `prompt.definition`：有效性定义
+- `prompt.instruct`：通过/不通过判定标准
+
+**保持不变的字段**：
+- `type`：固定为 `llm-judge`
+- `prompt.body`：固定依赖评测要点（keypoint）、上下文（context）、历史（history）
+
+---
+
+### 步骤3：保存维度配置
+
+**参考**：维度配置结构转化规则
+
+**保存路径**：`{work-dir}/.eval/{session-id}/eval-dimension.json`
+
+---
+
+**返回**：任务2步骤4
+
+---
+
+## 流程6：自定义通用维度级评测配置
+
+**触发条件**：eval-build.md 任务2步骤2确定评测方式为通用维度级。
+
+**目标**：根据评测场景构建评测维度，确保全面覆盖。
+
+---
+
+### 步骤1：选择评测维度
+
+根据用户场景，从内置评测维度模板中选择合适的维度：
+
+1. 参考 `{skill-dir}/references/内置模板说明.md` 第2节"维度配置模板"
+2. 根据评测场景匹配适用的内置维度
+
+---
+
+### 步骤2：评估维度覆盖情况
+
+| 情况 | 说明 | 动作 |
+|------|------|------|
+| 全部内置 | 内置维度完全覆盖评测场景 | 直接使用内置维度 |
+| 部分覆盖 | 内置维度覆盖部分评测场景 | 补充生成缺失维度 |
+| 无匹配 | 无适用的内置维度 | 全部自动生成 |
+
+**自动生成维度**：参考 `{skill-dir}/references/评测维度说明.md`，重点关注第1节评测类型选择、第2节字段填充规则。
+
+---
+
+### 步骤3：保存维度配置
+
+合并维度后设置权重（总和=1.0），保存至会话目录。
+
+**参考**：维度配置结构转化规则
+
+**保存路径**：`{work-dir}/.eval/{session-id}/eval-dimension.json`
+
+---
+
+**返回**：任务2步骤4
+
+---
+
+## 通用说明
+
+### 维度配置结构转化规则
+
+维度模板文件与会话目录下的 `eval-dimension.json` 结构不同，保存前需进行转化。
+
+**转化步骤**：
+1. 提取模板的 `config` 字段内容作为维度对象
+2. 将维度对象放入 `evals` 数组
+3. 从 `eval-judge.json` 读取 `judge_id` 并填充
+
+**结构对比**：
+
+| 对比项 | 模板文件结构 | 目标文件结构 |
+|--------|-------------|-------------|
+| 根节点 | `config: {...}` | `evals: [{...}]` |
+| judge_id | 空字符串 | 需从 eval-judge.json 读取 |
+
+**单维度转化示例**（流程5）：
+
+模板文件：
+```json
+{
+    "name": "有效性（用例级）",
+    "description": "...",
+    "config": {
+        "name": "有效性",
+        "type": "llm-judge",
+        "judge_id": "",
+        ...
+    }
+}
+```
+
+目标文件：
+```json
+{
+    "name": "有效性（用例级）",
+    "description": "...",
+    "evals": [
+        {
+            "name": "有效性",
+            "type": "llm-judge",
+            "judge_id": "ID_AJ001",
+            ...
+        }
+    ]
+}
+```
+
+**多维度合并示例**（流程6）：
+
+多个模板文件的 `config` 内容合并到 `evals` 数组：
+```json
+{
+    "name": "知识问答",
+    "description": "...",
+    "evals": [
+        { "name": "准确性", "type": "llm-score", "judge_id": "", ... },
+        { "name": "完整性", "type": "llm-score", "judge_id": "", ... },
+        { "name": "格式规范", "type": "builtin", "func": "JSONFORMAT", ... }
+    ]
+}
+```
+
+**保存前检查**：
+- [ ] `evals` 为数组结构（非 `config` 嵌套）
+- [ ] `judge_id` 已填充（非空字符串，客观评测除外）
+- [ ] 多维度时权重总和为 1.0
+
+---
+
+## 对比参考
+
+| 对比项 | 通用维度级评测（流程6） | 定制用例级评测（流程5） |
+|--------|------------------------|------------------------|
+| 触发条件 | 选择通用维度级评测 | 选择定制用例级评测且未匹配到专家模板 |
+| 核心定位 | 宏观全面覆盖 | 细节偏好对齐 |
+| 维度来源 | 内置模板优先，不足则自动生成 | 内置模板优先，按需调整字段 |
+| 维度数量 | 多维度组合 | 单一维度 |
+| 后续流程 | 无 | 流程4：评测点生成 |
+
+---
+
+## 变量速查
+
+| 变量 | 说明 |
+|------|------|
+| `{work-dir}` | 当前工作目录 |
+| `{session-id}` | 会话目录名，格式 `session-{8位字母数字}` |
+| `{skill-dir}` | 技能安装目录 |

package/skills/model-evaluation/processes/evalset-create-process.md

@@ -0,0 +1,184 @@
+---
+name: evalset-create-process
+description: Use when user has no evaluation dataset and needs AI to generate one from scratch
+---
+
+# 评测集生成流程
+
+本文档定义生成评测集流程，AI 根据评测场景从零生成完整评测集。
+
+---
+
+## 触发条件
+
+用户无评测集，需AI生成。
+
+---
+
+## 目标
+
+AI 根据评测场景生成完整评测集，保存为 JSONL 格式。
+
+---
+
+## 步骤1：确认评测场景
+
+从任务1获取已确认的评测场景。
+
+- **已确认** → 输出场景名称，进入步骤2
+- **未确认** → 提示用户先完成场景确认
+
+---
+
+## 步骤2：确认评测模式
+
+**判断1**：分析历史对话意图
+
+| 用户意图 | 判断依据 | 后续动作 |
+|----------|----------|----------|
+| 单模型评测 | 对话中提及"单个模型"、"评测一个模型" | → 设置 `{eval-mode}` 为 `single`，进入步骤3 |
+| 多模型评测 | 对话中提及"多个模型"、"横评"、"对比评测" | → 设置 `{eval-mode}` 为 `multi`，进入步骤3 |
+| 无法判断 | 无相关提及 | → 判断2 |
+
+**判断2**：询问评测模式
+
+```
+请选择评测模式：
+1. 单模型评测 - 评测单个模型的表现
+2. 多模型评测 - 多个模型横向对比
+```
+
+- **选择1** → 设置 `{eval-mode}` 为 `single`，进入步骤3
+- **选择2** → 设置 `{eval-mode}` 为 `multi`，进入步骤3
+
+---
+
+## 步骤3：询问生成数量
+
+**⚠️ 必须等待用户输入**：用户未输入时才使用默认值。
+
+**单模型模式**（`{eval-mode}` = `single`）：
+
+```
+请输入要生成的问题数量（默认10条）：
+```
+
+用户未输入则使用默认值 10 条。
+
+**多模型模式**（`{eval-mode}` = `multi`）：
+
+```
+请输入要生成的问题数量（默认10条）：
+请输入模型数量，或提供模型名称列表（如：model_a, model_b）：
+```
+
+- 仅输入数量 → 使用占位符 `model_1`, `model_2` ...
+- 输入模型名称 → 使用指定名称
+
+---
+
+## 步骤4：AI 生成评测集
+
+### 字段定义
+
+| 字段 | 必填 | 含义 | 说明 |
+|------|------|------|------|
+| case_id | 是 | 用例唯一标识 | **同一问题的多模型回答共享相同 case_id** |
+| model | 是 | 模型标识 | 待评测模型的名称或标识符 |
+| question | 是 | 评测问题 | 用户输入的提示词或问题 |
+| answer | 是 | 模型输出 | 待评测模型生成的实际回答，**不可为空** |
+| reference | 否 | 参考答案 | 理想答案，用于评分对比或生成评测点 |
+| context | 否 | 上下文信息 | 问题背景，用于理解场景 |
+| category | 否 | 分类标签 | 用于结果统计分析 |
+
+**⚠️ 重要区分**：
+- `answer`：待评测模型的实际输出，是评测的核心对象
+- `reference`：参考答案，用于提炼评测要点或作为评分标准
+
+
+### 生成说明与要求
+
+根据评测场景、模式和数量生成符合上述**字段定义**格式的数据。
+
+> 注意，如果用户是用例级评测，评测点 keypoint 字段不在该阶段生成。
+
+**执行方式**：
+- 数据量 ≤50 条：主 Agent 直接生成
+- 数据量 >50 条：可选使用 SubAgent 分批生成，每批次生成同类型问题
+- 主 Agent context 满载时：必须使用 SubAgent 分批生成
+
+**生成要求**：
+- 覆盖不同难度（简单/中等/困难）
+- 覆盖不同类型（开放式/封闭式/场景化）
+- 参考内置专家模板的问题风格
+- 答案采用理想参考答案风格
+
+**单模型模式**生成格式示例：
+```jsonl
+{"case_id": "case-0001", "model": "model_a", "question": "问题内容", "answer": "答案内容", "category": "分类"}
+{"case_id": "case-0002", "model": "model_a", "question": "问题内容", "answer": "答案内容", "category": "分类"}
+```
+
+**多模型模式**生成格式示例（同一问题共享 case_id）：
+```jsonl
+{"case_id": "case-0001", "model": "model_a", "question": "问题内容", "answer": "模型A回答", "category": "分类"}
+{"case_id": "case-0001", "model": "model_b", "question": "问题内容", "answer": "模型B回答", "category": "分类"}
+{"case_id": "case-0002", "model": "model_a", "question": "问题内容", "answer": "模型A回答", "category": "分类"}
+{"case_id": "case-0002", "model": "model_b", "question": "问题内容", "answer": "模型B回答", "category": "分类"}
+```
+
+
+保存至：`{work-dir}/.eval/{session-id}/evalset/evalset-prepared.jsonl`
+
+---
+
+## 步骤5：预览与确认
+
+展示前3条数据，等待用户确认：
+
+```
+是否确认保存？(Y/n/重新生成)
+```
+
+**⚠️ 不可跳过**：此步骤必须等待用户确认。
+
+- **Y** → 返回解析流程
+- **n** → 取消生成，返回步骤3
+- **重新生成** → 返回步骤4
+
+---
+
+## 返回点
+
+流程结束后返回 **eval-build.md 任务4步骤3**（执行解析流程）。
+
+---
+
+## 常见错误
+
+| 错误 | 原因 | 解决方案 |
+|------|------|----------|
+| 生成的 case_id 不唯一 | 多模型模式同一问题使用不同 case_id | 检查多模型模式下同一问题是否共享相同 case_id |
+| JSONL 格式无效 | 每行不是独立 JSON 对象 | 确保每行是完整 JSON，无跨行结构 |
+| 答案风格不一致 | 多个 SubAgent 生成风格差异 | 主 Agent 后处理统一风格，或单 Agent 生成 |
+| 问题覆盖不均衡 | 缺少困难题或特定类型 | 检查生成要求覆盖清单，补充缺失类型 |
+| 用户确认被跳过 | ClaudeCode 直接保存 | 预览步骤标注 `⚠️ 不可跳过`，必须等待确认 |
+
+---
+
+## 产物命名规范
+
+| 产物 | 说明 |
+|------|------|
+| `evalset-prepared.jsonl` | JSONL 格式评测集（标准字段格式） |
+
+---
+
+## 变量速查
+
+| 变量 | 说明 |
+|------|------|
+| `{work-dir}` | 当前工作目录 |
+| `{session-id}` | 会话目录名，格式 `session-{8位字母数字}` |
+| `{eval-mode}` | 评测模式：`single`（单模型）或 `multi`（多模型） |
+| `{model-list}` | 模型名称列表，多模型模式使用 |