astron-eval 0.0.1

package/skills/model-evaluation/references//350/204/232/346/234/254/345/256/232/344/271/211.md

@@ -0,0 +1,274 @@
+---
+name: script-definitions
+description: Use when needing to understand or execute evaluation scripts (eval_auth.py, eval_set.py, eval_task.py, eval_dimension.py)
+---
+
+# 脚本定义
+
+本文档定义评测脚本的使用方法和参数说明。
+
+---
+
+## 快速参考
+
+| 脚本 | 功能 | 子命令 |
+|------|------|--------|
+| `eval_auth.py` | 鉴权Token管理 | detect, login, token, check |
+| `eval_set.py` | 评测集管理 | analysis, normalize, submit |
+| `eval_task.py` | 任务管理 | submit, status, summary |
+| `eval_dimension.py` | 维度配置工具 | check, update |
+
+---
+
+## 1. 鉴权Token管理
+
+**脚本**：`eval_auth.py`
+
+### 登录模式
+
+脚本支持两种登录模式：
+
+| 模式 | 说明 | 适用场景 |
+|------|------|----------|
+| **回调模式** | 自动启动本地HTTP服务器，浏览器回调自动接收授权码 | 本地桌面环境，支持浏览器 |
+| **OOB模式** | 手动复制授权码，需要用户交互 | 服务器终端，无图形界面 |
+
+### 子命令
+
+| 子命令 | 说明 |
+|--------|------|
+| `detect` | 检测浏览器环境是否支持自动打开 |
+| `login` | 智能登录授权，自动选择最佳模式 |
+| `token` | 用授权码换取Token（OOB模式手动输入时使用） |
+| `check` | 检查Token有效性 |
+
+### 使用示例
+
+```bash
+# 检测浏览器环境
+python eval_auth.py detect --output {work-dir}/.eval/auth.json
+
+# 智能登录（自动选择最佳模式）
+python eval_auth.py login \
+  --config {skill-dir}/scripts/cfg/eval-auth.cfg \
+  --output {work-dir}/.eval/auth.json
+
+# 强制使用自动模式（回调）
+python eval_auth.py login --mode auto \
+  --config {skill-dir}/scripts/cfg/eval-auth.cfg \
+  --output {work-dir}/.eval/auth.json
+
+# 强制使用手动模式（OOB）
+python eval_auth.py login --mode manual \
+  --config {skill-dir}/scripts/cfg/eval-auth.cfg \
+  --output {work-dir}/.eval/auth.json
+
+# 指定回调端口
+python eval_auth.py login --mode auto --port 8080 \
+  --config {skill-dir}/scripts/cfg/eval-auth.cfg \
+  --output {work-dir}/.eval/auth.json
+
+# 授权码换取Token（OOB模式）
+python eval_auth.py token \
+  --code {authorization_code} \
+  --state_token {state_token} \
+  --config {skill-dir}/scripts/cfg/eval-auth.cfg \
+  --output {work-dir}/.eval/auth.json
+
+# 检查Token有效性
+python eval_auth.py check --output {work-dir}/.eval/auth.json
+```
+
+### 参数说明
+
+| 参数 | 说明 |
+|------|------|
+| `--config` | 鉴权配置文件路径 |
+| `--code` | 授权码（token 子命令必填） |
+| `--state_token` | 授权状态标识 |
+| `--output` | Token缓存文件路径 |
+| `--mode` | 登录模式：`auto` 强制使用回调模式，`manual` 强制使用手动模式，默认智能选择 |
+| `--port` | 回调模式端口（默认 51943） |
+
+### 回调模式流程
+
+1. 启动本地HTTP服务器监听 `127.0.0.1:{port}/callback`
+2. 请求登录URL，携带 loopback redirect_uri
+3. 打开浏览器访问登录URL
+4. 用户完成登录后，浏览器回调本地服务器
+5. 本地服务器接收授权码，自动换取Token
+6. 保存Token并完成认证
+
+### 服务端配置要求
+
+使用回调模式需要在服务端配置 loopback redirect_uri 白名单：
+
+```toml
+# 示例配置
+redirect_uris = ["http://127.0.0.1:51943/callback"]
+```
+
+---
+
+## 2. 评测集管理
+
+**脚本**：`eval_set.py`
+
+### 子命令
+
+| 子命令 | 说明 |
+|--------|------|
+| `analysis` | 解析评测集结构 |
+| `normalize` | 标准化评测集 |
+| `submit` | 提交评测集 |
+
+### analysis - 解析评测集结构
+
+```bash
+python eval_set.py analysis \
+  --input {work-dir}/.eval/{session-id}/evalset/evalset-prepared.csv \
+  --output {work-dir}/.eval/{session-id}/evalset/evalset-fields-mapping.json
+```
+
+**输出**：
+- 主要产物：字段映射文件（`--output` 指定）
+- 中间产物：结构文件（自动生成到同目录 `evalset-structure.json`）
+
+### normalize - 标准化评测集
+
+```bash
+python eval_set.py normalize \
+  --input {work-dir}/.eval/{session-id}/evalset/evalset-prepared.{ext} \
+  --mapping {work-dir}/.eval/{session-id}/evalset/evalset-fields-mapping.json \
+  --output {work-dir}/.eval/{session-id}/evalset/evalset-standard.jsonl
+```
+
+**支持格式**：Excel、JSON、JSONL、CSV
+
+**注意**：`{ext}` 为流程产物的文件扩展名（流程1/2为 `jsonl`，流程3为原始扩展名）。
+
+### submit - 提交评测集
+
+```bash
+python eval_set.py submit \
+  --auth {work-dir}/.eval/auth.json \
+  --config {skill-dir}/scripts/cfg/eval-server.cfg \
+  --evalset {work-dir}/.eval/{session-id}/evalset/evalset-standard.jsonl \
+  --output {work-dir}/.eval/{session-id}/evalset/evalset-meta.json
+```
+
+### 字段映射规则
+
+字段匹配关键词表见 [evalset-parse-process.md](../processes/evalset-parse-process.md#32-匹配字段)。
+
+---
+
+## 3. 任务管理
+
+**脚本**：`eval_task.py`
+
+### 子命令
+
+| 子命令 | 说明 |
+|--------|------|
+| `submit` | 提交评测任务 |
+| `status` | 查询任务状态（支持轮询） |
+| `summary` | 生成评测结果摘要 |
+
+### submit - 提交评测任务
+
+```bash
+python eval_task.py submit \
+  --config {skill-dir}/scripts/cfg/eval-server.cfg \
+  --auth {work-dir}/.eval/auth.json \
+  --eval_set {work-dir}/.eval/{session-id}/evalset/evalset-meta.json \
+  --eval_dimension {work-dir}/.eval/{session-id}/eval-dimension.json \
+  --eval_judge {work-dir}/.eval/{session-id}/eval-judge.json \
+  --output {work-dir}/.eval/{session-id}/evaltask/evaltask-meta.json
+```
+
+### status - 查询任务状态
+
+```bash
+# 轮询模式（推荐）
+python eval_task.py status \
+  --config {skill-dir}/scripts/cfg/eval-server.cfg \
+  --auth {work-dir}/.eval/auth.json \
+  --evaltask {work-dir}/.eval/{session-id}/evaltask/evaltask-meta.json \
+  --output {work-dir}/.eval/{session-id}/evaltask/evaltask-result.json \
+  --poll --interval 30 --timeout 3600
+
+# 单次查询模式（移除 --poll）
+```
+
+### summary - 生成结果摘要
+
+```bash
+python eval_task.py summary \
+  --result {work-dir}/.eval/{session-id}/evaltask/evaltask-result.json \
+  --platform_url {在线报告链接}
+```
+
+### 参数说明
+
+| 参数 | 说明 |
+|------|------|
+| `--config` | 服务配置文件（submit/status子命令参数） |
+| `--auth` | 鉴权信息文件（submit/status子命令参数） |
+| `--eval_set` | 评测集标识文件 |
+| `--eval_dimension` | 评测维度配置文件 |
+| `--eval_judge` | 评委模型配置文件 |
+| `--evaltask` | 评测任务元信息文件 |
+| `--output` | 输出文件路径 |
+| `--poll` | 启用自动轮询模式 |
+| `--interval` | 轮询间隔秒数（默认30） |
+| `--timeout` | 轮询超时秒数（默认3600） |
+| `--result` | 评测结果文件 |
+| `--platform_url` | 在线报告链接 |
+
+---
+
+## 4. 维度配置工具
+
+**脚本**：`eval_dimension.py`
+
+### 子命令
+
+| 子命令 | 说明 |
+|--------|------|
+| `check` | 校验配置文件完整性和规范性 |
+| `update` | 自动填充评委ID到主观评测维度 |
+
+### check - 校验配置
+
+```bash
+python eval_dimension.py -a check \
+  -d {work-dir}/.eval/{session-id}/eval-dimension.json
+```
+
+**校验规则**：
+
+| type | 必填字段 | 条件必填 |
+|------|----------|----------|
+| llm-score | name, type, weight | judge_id, prompt |
+| llm-judge | name, type, weight | judge_id, prompt |
+| builtin | name, type, weight | func |
+
+### update - 更新评委ID
+
+```bash
+python eval_dimension.py -a update \
+  -d {work-dir}/.eval/{session-id}/eval-dimension.json \
+  -j {work-dir}/.eval/{session-id}/eval-judge.json
+```
+
+### 参数说明
+
+| 参数 | 说明 |
+|------|------|
+| `-a, --action` | 操作类型：check/update |
+| `-d, --dimension` | 评测维度配置文件 |
+| `-j, --judge` | 评委配置文件（update时必填） |
+| `-o, --output` | 输出文件路径（默认覆盖原文件） |
+
+**更新规则**：仅更新 llm-score 和 llm-judge 类型的维度，builtin 类型不需要评委。

package/skills/model-evaluation/references//350/256/244/350/257/201/346/234/215/345/212/241/346/216/245/345/217/243/350/257/264/346/230/216.md

@@ -0,0 +1,271 @@
+---
+name: auth-service-api
+description: Use when needing to understand authentication service API for obtaining access tokens
+---
+
+# 认证服务接口说明
+
+本文档定义认证服务的 API 接口，用于获取访问令牌（access_token）。
+
+---
+
+## 快速参考
+
+| 接口 | 方法 | 路径 | 说明 |
+|------|------|------|------|
+| 登录初始化 | POST | `/astron/bifrost-heimdallr/api/auth/init` | 获取登录地址 |
+| 换取令牌 | POST | `/astron/bifrost-heimdallr/api/oauth/token` | 用授权码换取令牌 |
+| 用户信息 | GET | `/astron/bifrost-heimdallr/oauth2/api/auth/userinfo` | 查询当前用户 |
+
+---
+
+## 1. 认证流程概述
+
+```
+1. 客户端生成 state_token
+       ↓
+2. 调用登录初始化接口获取 login_url
+       ↓
+3. 用户浏览器访问 login_url 完成登录
+       ↓
+4. 用户获取授权码 code
+       ↓
+5. 客户端用 code + state_token 换取 access_token
+       ↓
+6. 后续请求携带 access_token 调用业务接口
+```
+
+---
+
+## 2. 统一响应格式
+
+```json
+{
+  "code": 0,
+  "message": "OK",
+  "data": {}
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `code` | `int` | 业务状态码（`0` 表示成功） |
+| `message` | `string` | 状态描述信息 |
+| `data` | `object` | 业务数据 |
+
+---
+
+## 3. 关键参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `state_token` | `string` | 是 | 客户端生成的随机状态串（建议UUID去除连接符） |
+| `redirect_uri` | `string` | 是 | 固定值：`urn:ietf:wg:oauth:2.0:oob` |
+| `client_id` | `string` | 是 | 客户端标识（示例：`bifrost-dev-test`） |
+| `code` | `string` | 是 | 用户登录授权后返回的授权码 |
+| `access_token` | `string` | 是 | 访问令牌，用于后续接口调用 |
+
+---
+
+## 4. 接口定义
+
+### 4.1 生成状态令牌
+
+`state_token` 由客户端本地生成，不通过接口获取。
+
+**生成示例**：
+
+```bash
+STATE_TOKEN=$(python3 -c "import uuid; print(uuid.uuid4().hex)")
+# 示例输出: 6e62ff70c88448aabbe6a60337c4ce0c
+```
+
+---
+
+### 4.2 登录初始化
+
+**接口URL**：`POST /astron/bifrost-heimdallr/api/auth/init`
+
+**完整地址**：`https://www.iflyaicloud.com/astron/bifrost-heimdallr/api/auth/init`
+
+**请求参数**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `state_token` | `string` | 是 | 客户端生成的状态串 |
+| `redirect_uri` | `string` | 是 | 固定值：`urn:ietf:wg:oauth:2.0:oob` |
+| `client_id` | `string` | 是 | 客户端标识 |
+
+**请求示例**：
+
+```json
+{
+  "state_token": "6e62ff70c88448aabbe6a60337c4ce0c",
+  "redirect_uri": "urn:ietf:wg:oauth:2.0:oob",
+  "client_id": "bifrost-dev-test"
+}
+```
+
+**响应参数**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data.login_url` | `string` | 用户登录地址 |
+
+**响应示例**：
+
+```json
+{
+  "code": 0,
+  "message": "OK",
+  "data": {
+    "login_url": "https://www.iflyaicloud.com/login?redirect=..."
+  }
+}
+```
+
+---
+
+### 4.3 获取授权码
+
+用户在浏览器中访问 `login_url` 完成登录后，将获得授权码 `code`。
+
+```bash
+# 示例
+CODE=4736ede401d4486fb1887e06a5cf7cb9
+```
+
+---
+
+### 4.4 换取访问令牌
+
+**接口URL**：`POST /astron/bifrost-heimdallr/api/oauth/token`
+
+**完整地址**：`https://www.iflyaicloud.com/astron/bifrost-heimdallr/api/oauth/token`
+
+**请求参数**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `grant_type` | `string` | 是 | 固定值：`authorization_code` |
+| `code` | `string` | 是 | 用户登录后获得的授权码 |
+| `state` | `string` | 是 | 必须与登录初始化时的 `state_token` 一致 |
+| `client_id` | `string` | 是 | 客户端标识 |
+
+**请求示例**：
+
+```json
+{
+  "grant_type": "authorization_code",
+  "code": "4736ede401d4486fb1887e06a5cf7cb9",
+  "state": "6e62ff70c88448aabbe6a60337c4ce0c",
+  "client_id": "bifrost-dev-test"
+}
+```
+
+**响应参数**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `access_token` | `string` | 访问令牌 |
+| `expires_in` | `int` | 有效期（秒） |
+| `refresh_token` | `string \| null` | 刷新令牌（当前返回 `null`） |
+| `token_type` | `string` | 令牌类型（`bearer`） |
+
+**响应示例**：
+
+```json
+{
+  "access_token": "EcRC6XuYa1AbLyFh5k1Q1za8zL7MMD33",
+  "expires_in": 7200,
+  "refresh_token": null,
+  "token_type": "bearer"
+}
+```
+
+---
+
+### 4.5 查询当前用户信息
+
+**接口URL**：`GET /astron/bifrost-heimdallr/oauth2/api/auth/userinfo`
+
+**完整地址**：`https://www.iflyaicloud.com/astron/bifrost-heimdallr/oauth2/api/auth/userinfo`
+
+**请求头**：
+
+| Header | 必填 | 说明 |
+|--------|------|------|
+| `Authorization` | 是 | `Bearer <access_token>` |
+
+**响应参数**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data.uid` | `int64` | 用户唯一标识 |
+| `data.username` | `string` | 用户名 |
+| `data.source` | `int` | 用户来源标识 |
+| `data.appInfos` | `array[AppInfo]` | 关联应用信息 |
+
+**AppInfo 定义**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `appId` | `string` | 应用ID |
+| `apiKey` | `string` | 应用访问Key |
+| `apiSecret` | `string` | 应用访问Secret |
+
+---
+
+## 5. 错误码
+
+| 错误场景 | HTTP状态码 | 说明 |
+|----------|------------|------|
+| `state mismatch` | 400 | `state_token` 与换取令牌时的 `state` 不一致 |
+| `unauthorized` | 401 | `access_token` 缺失、无效或已过期 |
+| `invalid request` | 400 | 请求参数缺失或格式不正确 |
+| `internal server error` | 500 | 服务内部错误 |
+
+---
+
+## 6. 认证流程示例
+
+```bash
+# 步骤1：生成 state_token
+STATE_TOKEN=$(python3 -c "import uuid; print(uuid.uuid4().hex)")
+
+# 步骤2：登录初始化
+curl -s 'https://www.iflyaicloud.com/astron/bifrost-heimdallr/api/auth/init' \
+  -H 'Content-Type: application/json' \
+  -d "{\"state_token\":\"$STATE_TOKEN\",\"redirect_uri\":\"urn:ietf:wg:oauth:2.0:oob\",\"client_id\":\"bifrost-dev-test\"}"
+
+# 步骤3：用户在浏览器中完成登录，获取授权码
+CODE=4736ede401d4486fb1887e06a5cf7cb9
+
+# 步骤4：换取 access_token
+curl -s -X POST 'https://www.iflyaicloud.com/astron/bifrost-heimdallr/api/oauth/token' \
+  -H 'Content-Type: application/json' \
+  -d "{\"grant_type\":\"authorization_code\",\"code\":\"$CODE\",\"state\":\"$STATE_TOKEN\",\"client_id\":\"bifrost-dev-test\"}"
+
+# 步骤5：使用 access_token 访问受保护资源
+ACCESS_TOKEN=EcRC6XuYa1AbLyFh5k1Q1za8zL7MMD33
+curl -s 'https://www.iflyaicloud.com/astron/bifrost-heimdallr/oauth2/api/auth/userinfo' \
+  -H "Authorization: Bearer $ACCESS_TOKEN"
+```
+
+---
+
+## 7. 最佳实践
+
+### 7.1 服务端集成
+
+- 由服务端统一生成并维护 `state_token`
+- 登录初始化后，将 `login_url` 返回前端跳转
+- `access_token` 应保存在服务端安全存储中
+- 在令牌过期前进行有效性检查
+
+### 7.2 安全建议
+
+- 不要在前端明文持久化 `apiSecret`、`access_token`
+- `state_token` 应一次一用，使用后立即失效
+- `code` 应视为敏感凭证，避免打印到公共日志
+- `access_token` 缓存过期时间不超过 `expires_in`