astron-eval 0.0.1

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

@@ -0,0 +1,171 @@
+---
+name: evalset-parse-process
+description: Use when user has an existing evaluation dataset file and needs to parse field mapping
+---
+
+# 评测集解析流程
+
+## 目标
+
+获取评测集文件 → 解析字段结构 → 生成映射配置 → 用户确认，完成后返回标准化转换流程。
+
+---
+
+## 何时使用
+
+- 用户已有完整评测集文件（JSONL/JSON/CSV/XLSX）
+- 需要解析字段映射关系
+- 接收生成流程或补充流程输出的评测集
+
+---
+
+## 步骤1：获取评测集文件
+
+**判断**：`evalset-prepared.{ext}` 是否存在？
+
+| 状态 | 动作 |
+|------|------|
+| 已存在 | → 步骤2 |
+| 不存在 | 执行如下命令，获取用户文件 |
+
+```bash
+cp {用户路径} {work-dir}/.eval/{session-id}/evalset/evalset-prepared.{ext}
+# 或远程下载
+curl -o {work-dir}/.eval/{session-id}/evalset/evalset-prepared.{ext} {下载链接}
+```
+
+> `{ext}` 从文件路径提取（如 `data.xlsx` → `ext=xlsx`）。
+
+---
+
+## 步骤2：解析字段结构
+
+**判断**：`evalset-structure.json` 是否存在？
+
+| 状态 | 动作 |
+|------|------|
+| 已存在 | → 步骤3 |
+| 不存在 | 执行解析 |
+
+```bash
+{python-env}{python-cmd} {skill-dir}/scripts/eval_set.py analysis \
+  --input {work-dir}/.eval/{session-id}/evalset/evalset-prepared.{ext} \
+  --output {work-dir}/.eval/{session-id}/evalset/evalset-structure.json
+```
+
+输出包含：`file`、`format`、`total_rows`、`fields`（字段名+类型）。
+
+---
+
+## 步骤3：生成字段映射
+
+**判断**：`evalset-fields-mapping.json` 是否存在？
+
+| 状态 | 动作 |
+|------|------|
+| 已存在 | → 步骤4 |
+| 不存在 | 生成映射 |
+
+读取结构文件 → 匹配字段 → 生成映射配置。
+
+### 字段匹配关键词表
+
+| 标准字段 | 含义 | 匹配关键词 |
+|----------|------|------------|
+| question | 评测输入问题 | question, prompt, input, query, 问题, 提问 |
+| answer | 模型实际回答 | answer, response, output, reply, 回答, 回复 |
+| model | 生成回答的模型标识 | model, model_name, model_id, llm, llm_name, 模型, 模型名称 |
+| case_id | 用例唯一标识，用于关联同一问题的多模型回答 | case_id, caseid, 用例id；**精确匹配**：id |
+| system | 系统提示词 | system, system_prompt, 系统提示 |
+| context | 附加上下文信息 | context, 上下文 |
+| category | 用例分类标签 | category, type, 分类, 类别 |
+| reference | 参考答案，用于评分对比 | reference, ref, gold, 参考答案, 标准答案 |
+| keypoint | 评测关键点，用于细粒度评分 | keypoint, keypoints, 关键点, 评测点 |
+
+**匹配规则**：精确匹配优先，包含匹配次之（优先更长关键词）。
+
+**必填字段**：question、answer、model、case_id。
+
+### 映射格式
+
+```json
+{
+  "question": {"source_field": "问题", "default": null},
+  "answer": {"source_field": "回答", "default": null},
+  "model": {"source_field": "模型名称", "default": null},
+  "case_id": {"source_field": "id", "default": null}
+}
+```
+
+**生成规则**：匹配到 → `source_field=源字段名`；未匹配到 → `source_field=null, default=待确认`。
+
+> `case_id` 的 `default` 不使用，有 `source_field` 用源数据值，无则自动生成。
+
+---
+
+## 步骤4：确认映射配置
+
+> 注意，如果先前评测集全部由AI助手生成，则跳过此步骤。因为评测集都是按标准格式生成，无需用户确认映射配置。
+
+**判断**：用户是否已确认映射？
+
+| 状态 | 动作 |
+|------|------|
+| 已确认 | → 保存并返回 |
+| 未确认 | 执行确认流程 |
+
+### 4.1 字段映射确认
+
+向用户说明映射目的：将评测集的原始字段映射为标准字段，标准化后便于后续统一处理（标准化转换、评测执行、评分判定等环节均基于标准字段工作）。
+
+展示映射表（含标准字段含义），等待用户确认。
+
+> **此步骤必须等待用户确认，不可跳过。**
+
+| 用户选择 | 后续动作 |
+|----------|----------|
+| Y | → 4.2 |
+| n | 调整映射，重新确认 |
+
+### 4.2 模型字段确认
+
+| model.source_field | 处理 |
+|---------------------|------|
+| 有值 | 直接使用源字段值，无需询问 |
+| null | 询问评测场景：多模型横评→提示需补充模型字段，单模型→设置default字段值 |
+
+### 4.3 case_id 字段确认
+
+| case_id.source_field | 处理 |
+|-----------------------|------|
+| 有值 | 直接使用源数据值 |
+| null | 标准化时根据 question 分组自动生成 |
+
+> 多模型横评时，同一问题的不同模型回答共享相同 case_id。
+
+### 4.4 保存
+
+保存至 `{work-dir}/.eval/{session-id}/evalset/evalset-fields-mapping.json`，返回 **eval-build.md 任务4步骤4**（标准化转换）。
+
+---
+
+## 常见错误
+
+| 错误 | 解决方案 |
+|------|----------|
+| 字段匹配失败 | 手动指定映射 |
+| 文件格式不支持 | 转换为JSONL/JSON/CSV/XLSX |
+| 结构解析报错 | 检查编码，转为UTF-8 |
+
+---
+
+## 变量速查
+
+| 变量 | 说明 |
+|------|------|
+| `{work-dir}` | 当前工作目录 |
+| `{session-id}` | 会话目录名（`session-{8位字母数字}`） |
+| `{skill-dir}` | 技能安装目录 |
+| `{ext}` | 文件扩展名 |
+| `{python-env}` | Python环境变量前缀 |
+| `{python-cmd}` | Python命令 |

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

@@ -0,0 +1,136 @@
+---
+name: evalset-supplement-process
+description: Use when user has a question-only evaluation dataset and needs AI to generate answers
+---
+
+# 评测集补充答案流程
+
+本文档定义补充答案流程，为仅有问题的评测集生成答案。
+
+---
+
+## 触发条件
+
+用户仅有问题评测集，需AI补充答案。
+
+---
+
+## 目标
+
+读取仅有问题的文件，AI 为每条问题生成答案，输出为 JSONL 格式。
+
+---
+
+## 步骤1：获取问题集
+
+支持格式：JSONL、JSON、CSV、Excel（xlsx）
+
+```
+请提供仅有问题的评测集文件：
+```
+
+复制文件至：`{work-dir}/.eval/{session-id}/evalset/evalset-questions.{ext}`
+
+**注意**：Excel 格式仅作为输入，输出统一转为 JSONL。
+
+---
+
+## 步骤2：验证文件格式
+
+执行脚本验证文件结构：
+
+```bash
+{python-env}{python-cmd} {skill-dir}/scripts/eval_set.py analysis \
+  --input {work-dir}/.eval/{session-id}/evalset/evalset-questions.{ext} \
+  --output {work-dir}/.eval/{session-id}/evalset/evalset-structure.json
+```
+
+验证结果：
+- 文件格式有效（JSONL/JSON/CSV/Excel）
+- 包含 `question` 字段
+- 缺少或为空 `answer` 字段
+
+- **验证通过** → 进入步骤3
+- **验证失败** → 提示错误，返回步骤1
+
+---
+
+## 步骤3：AI 生成答案
+
+遍历每条问题，生成理想参考答案。
+
+**主 Agent 职责**（格式处理）：
+- JSONL 格式：直接读取问题列表
+- 其他格式：读取文件 → 转换为问题列表 → 准备接收答案
+- 答案生成后：添加 `answer` 字段 → 输出 JSONL
+
+**SubAgent 职责**（仅答案生成，大批量时启用）：
+- 输入：问题文本列表
+- 输出：答案文本列表
+- 不涉及：文件读取、格式转换、文件写入
+
+**执行方式**：
+- 数据量 ≤50 条：主 Agent 直接生成
+- 数据量 >50 条：可选使用 SubAgent 分批生成答案
+- 主 Agent context 满载时：必须使用 SubAgent 分批生成
+
+**生成要求**：
+- 答案完整、准确、符合问题要求
+- 作为评测基准
+- 保留原始字段，仅补充 `answer` 字段
+
+保存至：`{work-dir}/.eval/{session-id}/evalset/evalset-prepared.jsonl`
+
+---
+
+## 步骤4：预览与确认
+
+展示前3条数据，等待用户确认：
+
+```
+是否确认保存？(Y/n/重新生成)
+```
+
+**⚠️ 不可跳过**：此步骤必须等待用户确认。
+
+- **Y** → 返回解析流程
+- **n** → 取消补充，返回步骤1
+- **重新生成** → 返回步骤3
+
+---
+
+## 返回点
+
+流程结束后返回 **eval-build.md 任务4步骤3**（执行解析流程）。
+
+---
+
+## 常见错误
+
+| 错误 | 原因 | 解决方案 |
+|------|------|----------|
+| 文件格式不支持 | 文件不是 JSONL/JSON/CSV/Excel 格式 | 转换为支持的格式后重试 |
+| 缺少 question 字段 | 文件不包含问题字段 | 确保文件包含 `question` 字段 |
+| 答案风格不一致 | 多个 SubAgent 生成风格差异 | 主 Agent 后处理统一风格，或单 Agent 生成 |
+| 用户确认被跳过 | ClaudeCode 直接保存 | 预览步骤标注 `⚠️ 不可跳过`，必须等待确认 |
+
+---
+
+## 产物命名规范
+
+| 产物 | 说明 |
+|------|------|
+| `evalset-prepared.jsonl` | JSONL 格式评测集（含答案） |
+
+---
+
+## 变量速查
+
+| 变量 | 说明 |
+|------|------|
+| `{work-dir}` | 当前工作目录 |
+| `{session-id}` | 会话目录名，格式 `session-{8位字母数字}` |
+| `{ext}` | 文件扩展名（jsonl/json/csv/xlsx） |
+| `{skill-dir}` | 技能安装目录 |
+| `{python-env}` | Python环境变量前缀 |
+| `{python-cmd}` | Python命令（`python` 或 `python3`） |

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

@@ -0,0 +1,148 @@
+---
+name: keypoint-process
+description: Use when case-level evaluation requires generating keypoints for evaluation items
+---
+
+# 评测点生成流程
+
+**触发条件**：定制用例级评测且标准化评测集无 keypoint 字段。
+
+**目标**：根据问题、参考答案、上下文字段自动生成 1-3 个评测点，覆盖原 evalset-standard.jsonl 文件。
+
+---
+
+## 步骤1：场景判断
+
+根据标准化评测集字段组合识别场景类型。
+
+**字段说明**
+
+| 字段 | 字母代表 | 说明 | 用途 |
+|------|------|------|------|
+| `question` | Q | 用户问题 | 评测的核心输入 |
+| `answer` | - |模型输出的回答 | 待评测内容，**不是参考答案** |
+| `reference` | R | 参考答案/理想答案 | 用于提炼评测要点 |
+| `context` | C | 上下文信息 | 用于理解问题背景 |
+
+**重要区分**：
+- `answer` 是待评测的模型输出，不属于场景判断的依据
+- `reference` 才是参考答案，用于场景判断和评测点生成
+
+| 场景 | 包含字段 | 评估点来源 | 典型用途 |
+|------|----------|------------|----------|
+| Q | 仅 `question` | 基于问题推断 | 通用数据集（质量一般） |
+| QR | `question` + `reference` | 从参考答案提炼关键信息点 | 通用数据集（推荐） |
+| QC | `question` + `context` | 从上下文推导应提取的要点 | 私域数据集 |
+| QRC | `question` + `reference` + `context` | 最佳效果 | 私域数据集（推荐） |
+
+**判断逻辑**（忽略 `answer` 字段）：
+```
+if reference AND context: scene = "QRC"
+elif reference: scene = "QR"
+elif context: scene = "QC"
+else: scene = "Q"
+```
+
+---
+
+## 步骤2：生成评测点
+
+调用 `{skill-dir}/scripts/utils/keypoint_prompts.py` 生成提示词：
+
+- **系统提示词**：使用 `SYSTEM_PROMPT`（包含四步思考法和7条质量标准）
+- **用户提示词**：使用 `build_user_prompt(question, answer, context)` 构建
+
+### 执行方式：
+
+1. **准备提示词**：
+   - 读取 `keypoint_prompts.py` 中的 `SYSTEM_PROMPT` 作为系统提示词
+   - 使用 `build_user_prompt(question, reference, context)` 构建用户提示词
+
+2. **调用内置模型**：
+   - 使用 Agent 工具（subagent_type=general-purpose）批量生成评测点
+   - 每条数据独立生成，确保评测点质量
+
+3. **执行示例**：
+```python
+# 构建提示词
+from keypoint_prompts import SYSTEM_PROMPT, build_user_prompt
+
+user_prompt = build_user_prompt(question, reference, context)
+
+# 通过 Agent 工具调用内置模型生成
+# Agent prompt 示例：
+# f"{SYSTEM_PROMPT}\n\n{user_prompt}"
+```
+
+4. **批量处理建议**：
+   - 数据量 ≤ 50 条：主 Agent 直接生成
+   - 数据量 > 50 条：使用 Agent 工具分批执行
+   - 主 Agent context 满载时：必须使用 SubAgent 分批生成
+
+**⚠️ 禁止行为**：
+- ❌ 不调用模型直接"编造"评测点
+- ❌ 跳过 SYSTEM_PROMPT 中的思考步骤
+- ❌ 忽略质量标准要求
+
+### 输出格式：
+```json
+["是否提及xxx", "是否包含xxx"]
+```
+
+### 失败处理
+- 评测点生成失败时重试一次
+- 仍失败则跳过该条数据，继续处理下一条
+- 记录跳过的数据条目，最后汇总报告
+
+---
+
+## 步骤3：预览与确认
+
+展示**前3条**数据的评测点预览：
+
+| 序号 | 问题 | 生成的评测点 |
+|------|------|--------------|
+| 1 | 什么是机器学习？ | ["是否定义了机器学习", "是否提及与人工智能的关系"] |
+| 2 | 如何评估模型性能？ | ["是否列举评估指标", "是否说明各指标适用场景"] |
+| 3 | 深度学习有哪些应用？ | ["是否列举应用领域", "是否给出具体案例"] |
+
+预览展示后，询问用户：
+
+```
+是否确认保存以上评测点？
+- Y：保存并覆盖原文件
+- n：取消生成，不修改文件
+- 调整：描述调整需求，重新生成
+- 查看更多：展示更多数据的评测点
+```
+
+**⚠️ 必须遵守**：
+- 严格展示前3条数据，不得跳过
+- 必须等待用户确认，不可自动继续
+
+---
+
+## 步骤4：保存结果
+
+将 keypoint 字段添加到原 `{work-dir}/.eval/{session-id}/evalset/evalset-standard.jsonl`文件：
+
+**字段格式**：字符串数组转为 JSON 字符串存储。
+- 示例：`["是否...", "是否..."]` 存储为 `"[\"是否...\", \"是否...\"]"`
+
+**注意**：覆盖原文件，不创建新文件。
+
+---
+
+## 返回点
+
+流程结束后返回 **任务4步骤6**（上传评测集）。
+
+---
+
+## 变量速查
+
+| 变量 | 说明 |
+|------|------|
+| `{work-dir}` | 当前工作目录 |
+| `{session-id}` | 会话目录名，格式 `session-{8位字母数字}` |
+| `{skill-dir}` | 技能安装目录 |

package/skills/model-evaluation/processes/python-env-process.md

@@ -0,0 +1,113 @@
+# Python 环境检测流程
+
+## 适用场景
+
+- 初始化阶段检测 Python 环境
+- 环境缓存失效时重新检测
+
+## 输出
+
+| 变量 | 说明 |
+|------|------|
+| `{python-cmd}` | Python 命令（`python3` 或 `python`） |
+| `{python-env}` | 环境变量前缀（Windows GBK 为 `PYTHONUTF8=1 `，其他为空） |
+
+---
+
+## 流程步骤
+
+### 步骤1：检测 Python 命令
+
+依次尝试 `python3` 和 `python` 命令：
+
+```bash
+python3 --version
+```
+
+- **返回版本信息** → 设置 `{python-cmd}` 为 `python3` → 进入步骤2
+- **命令不存在** → 尝试备用命令：
+
+```bash
+python --version
+```
+
+- **返回 Python 3.x** → 设置 `{python-cmd}` 为 `python`（注意，不是 `python3`） → 进入步骤2
+- **返回 Python 2.x** → 查找 Python 3 路径或提示用户安装
+- **命令不存在** → 提示用户安装 Python 3
+
+---
+
+### 步骤2：检测依赖
+
+执行一次命令检测所有依赖：
+
+```bash
+{python-cmd} -c "
+deps = [
+    ('requests', '必需'),
+    ('pandas', '可选'),
+    ('openpyxl', '可选')
+]
+installed = []
+missing = []
+for name, category in deps:
+    try:
+        __import__(name)
+        installed.append(name)
+    except ImportError:
+        missing.append(f'{name}({category})')
+print('OK' if not missing else 'MISSING')
+print('已安装:', ', '.join(installed))
+print('缺失:', ', '.join(missing) if missing else '无')
+"
+```
+
+**输出示例**：
+
+| 情况 | 输出 |
+|------|------|
+| 全部已安装 | `OK`<br>`已安装: requests, pandas, openpyxl`<br>`缺失: 无` |
+| 部分缺失 | `MISSING`<br>`已安装: requests`<br>`缺失: pandas(可选), openpyxl(可选)` |
+
+**后续动作**：
+
+- **输出 OK**（无缺失） → 进入步骤3
+- **输出 MISSING**（有缺失） → 根据缺失项提示安装：
+  - 缺失 `requests`：`pip install requests`
+  - 缺失 `pandas` 或 `openpyxl`：`pip install pandas openpyxl`
+
+> **说明**：`requests` 用于 HTTP 请求，是必需依赖；`pandas` 用于数据处理，`openpyxl` 是 pandas 读取 Excel 的引擎，两者为可选依赖
+
+---
+
+### 步骤3：检测编码环境
+
+```bash
+{python-cmd} -c "import sys; print(sys.platform)"
+```
+
+根据检测结果设置 `{python-env}` 变量：
+
+| sys.platform | 终端编码页 | `{python-env}` 值 |
+|--------------|-----------|------------------|
+| `win32` | 非65001 | `PYTHONUTF8=1 ` |
+| `win32` | 65001 | 空 |
+| 其他 | - | 空 |
+
+检测终端编码页（仅 Windows）：`chcp`，输出包含 `65001` 则为 UTF-8 模式。
+
+---
+
+## 使用示例
+
+在调用脚本时使用 `{python-env}` 前缀：
+
+```bash
+{python-env}{python-cmd} scripts/eval_auth.py check --output {work-dir}/.eval/auth.json
+```
+
+Windows GBK 终端下，`{python-env}` 为 `PYTHONUTF8=1 `，实际执行：
+
+```bash
+PYTHONUTF8=1 python scripts/eval_auth.py check --output {work-dir}/.eval/auth.json
+```