schema_version: v1alpha1

environment:
  type: none

skills:
  - source: local_path
    path: .

engine:
  name: claude_code

cases:
  files:
    - evals/cases/scaffold-new-evals.yaml
    - evals/cases/add-case-to-existing.yaml
    - evals/cases/scaffold-with-qodercli-engine.yaml
    - evals/cases/scaffold-with-script-judge.yaml
    - evals/cases/english-context-generates-english-only-cases.yaml
    - evals/cases/evolve-existing-skill.yaml
  defaults:
    # Budget sized to be engine-agnostic: claude_code finishes well under this,
    # but slower coding agents (codex on a coder model) need more wall-clock and
    # turns to complete the multi-file scaffolding cases. A timeout is a ceiling,
    # so raising it does not slow the fast engines.
    timeout_seconds: 600
    max_turns: 25

report:
  formats: [json, html]

# case.yaml 字段参考（skill-up）

每个 `evals/cases/*.yaml` 是一个评测用例。用例 ID = 文件名（去掉 `.yaml`）。语义与 skill-up 内置 schema 一致。

## 单轮用例骨架

```yaml
id: find-null-bug
title: 应该识别出空指针 bug
description: 验证 Skill 能在代码审查中发现 null 解引用问题

input:
  prompt: |
    Review the current diff and report findings.

context:
  repo_fixture: fixtures/repos/null-check-bug
  git:
    init: true
    checkout: main
    apply_diff: fixtures/diffs/null-check.patch

constraints:
  timeout_seconds: 180
  max_turns: 8

expect:
  must_contain: ["null", "bug"]
  must_not_contain: ["LGTM"]
  exit_code: 0

judge:
  type: rule_based
  success:
    - output_contains:
        all: ["null", "bug"]
    - exit_code: 0
```

## 多轮对话

```yaml
input:
  turns:
    - role: user
      content: "sdd_bootstrap: task=实现用户登录功能"
      post_condition:
        must_contain_any: ["Research", "分析"]
        on_fail: skip_remaining      # 或 fail
      capture:
        - variable: phase
          pattern: "(?P<value>Research|Implementation)"
    - role: user
      content: "跳过 Research，直接帮我写代码"
```

`post_condition`：每轮结束后检查输出。`on_fail: skip_remaining` 标为 SKIP，`fail` 直接 FAIL 整个用例。

`capture`：从响应中捕获值，用于后续轮次的 `{{variable}}` 模板替换。
  • 提取器：`pattern`（正则）或 `jsonpath`，必须且仅指定一个
  • 优先使用 `(?P<value>...)` 命名组
  • 未匹配/空值 → 用例进入 ERROR 状态
  • 作用域仅限当前用例执行

### 按轮次 Judge 断言

```yaml
judge:
  type: rule_based
  success:
    - turn_response_contains:
        turn: 2
        contains_any: ["必须完成", "不能跳过", "Research"]
    - turn_response_not_contains:
        turn: 2
        not_contains: ["LGTM"]
    - tool_called_in_turn:
        turn: 1
        name: write_file
    - tool_not_called_in_turn:
        turn: 2
        name: delete_file
```

仅 `status=completed` 的轮次可被断言；引用不存在或未完成的轮次会导致断言失败。

## context — 初始化工作区

```yaml
context:
  repo_fixture: fixtures/repos/my-project
  git:
    init: true
    checkout: feature-branch
    apply_diff: fixtures/diffs/my.patch
    remotes:
      - name: origin
        url: https://github.com/user/repo
  files:
    "src/main.py": |
      def hello():
          print("Hello World")
    "config.json": '{"debug": true}'
```

## expect — 零成本门槛检查

```yaml
expect:
  must_contain:
    - "review"
    - "bug"
  must_not_contain:
    - "LGTM"
    - "error"
  exit_code: 0
  files_exist:
    - "review.md"
    - "output.json"
  files_not_exist:
    - "temp.log"
  file_contains:
    - path: "review.md"
      content: "security"
  golden_file: "expected.txt"
```

expect 不通过时，judge 会被跳过。用它来快速过滤明显不合格的输出，节省 token。

**与 `cases.defaults.expect` 合并：**

- 如果 `eval.yaml` 的 `cases.defaults.expect` 定义了默认检查（如 `exit_code: 0`, `must_not_contain: ["TODO"]`），每个用例的 expect 会与之合并
- 切片字段（`must_contain`, `must_not_contain`, `files_exist`, `files_not_exist`, `file_contains`）追加去重；标量字段（`exit_code`, `golden_file`）由用例覆盖
- 用例未设 expect 时，直接使用默认值

## 常见写法

- **纯文本路由 Skill**：`expect.must_contain` + `judge.rule_based.output_contains`
- **MCP 工具校验**：`judge.rule_based.success[tool_called]`
- **语义质量评估**：`judge.agent_judge.criteria`
- **复杂结构化断言**：`judge.script`，在脚本里读 `$EVAL_TRANSCRIPT_PATH` 等自由判断

# skill-up CLI 命令参考

skill-up 提供以下命令，覆盖评测的完整生命周期：校验、运行、查看用例、生成报告和格式迁移。另含用户配置初始化与调试子命令。

---

## skill-up run

运行评测用例，生成评估报告。

```bash
skill-up run [path] [flags]
```

### 参数

| 参数   | 说明                                                             |
| ------ | ---------------------------------------------------------------- |
| `path` | `eval.yaml` 的路径。省略时默认在当前目录下查找 `evals/eval.yaml` |

### Flags

| Flag                  | 默认               | 说明                                                                                                                                                                              |
| --------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--auto`              | `false`            | 自动检测 `evals/` 目录，支持直接消费 Anthropic `evals.json`                                                                                                                       |
| `--include-case-name` | —                  | 只运行匹配的用例（glob，可多次）                                                                                                                                                  |
| `--exclude-case-name` | —                  | 排除匹配的用例（glob，可多次）                                                                                                                                                    |
| `--format`            | —                  | 附加报告格式：`junit` / `html`（可多次）。`result.json` 始终写入；`--format junit` 生成 `report.xml`；`--format html` 生成 `report.html`；`--format json` 对 `result.json` 为冗余 |
| `--output-dir`        | eval.yaml 同级目录 | 报告和产物的输出目录                                                                                                                                                              |
| `--iteration`         | `0`（auto）        | 重复运行已选用例，用于稳定性/flaky 采样。`0` = 自动：在最后一个已有 `iteration-N/` 之后追加一轮，但不汇总历史结果；正整数 = 显式运行 N 次采样，产物写入 `iteration-1/` … `iteration-N/`；当 N > 1 时，终端摘要只覆盖本次命令执行的采样 |
| `--engine`            | 配置中的值         | 覆盖 Engine 名称                                                                                                                                                                  |
| `--runtime`           | 配置中的值         | 覆盖 `environment.type`（`none`、`opensandbox`、`docker`）                                                                                                                        |
| `--model`             | 配置中的值         | 覆盖模型（格式：`provider/name`）                                                                                                                                                 |
| `--parallelism`       | 配置中的值         | 覆盖 `cases.parallelism`，临时调整用例并行数，取值 1–256                                                                                                                          |
| `--baseline`          | 配置中的值         | 为本次运行覆盖 `benchmark.enabled` 为 `true`                                                                                                                                      |
| `--api-key`           | —                  | 传入 API Key（优先级高于环境变量）                                                                                                                                                |
| `-v, --verbose`       | `0`                | 日志详细程度：`info` 默认；`-v` 为 `debug`；`-vv` / `--verbose=2` 为 `trace`                                                                                                      |

### 退出码

- `0` — 所有用例通过
- `1` — 有用例失败或执行出错

可作为 CI 门禁。

### 典型用法

```bash
skill-up run ./evals/eval.yaml
skill-up run ./evals/eval.yaml --include-case-name "basic-*"
skill-up run ./evals/eval.yaml --exclude-case-name "*-old"
skill-up run ./evals/eval.yaml --engine codex --model openai/gpt-4
skill-up run ./evals/eval.yaml --parallelism 4
skill-up run ./evals/eval.yaml --baseline
skill-up run ./evals/eval.yaml --format html --format junit
skill-up run ./evals/eval.yaml --iteration 3
# example terminal summary: case_a: 3 trials, 2 PASS, 1 FAIL -> flaky
skill-up run ./evals/eval.yaml
skill-up run --auto
skill-up run ./my-skill/ --auto --engine codex
```

### OTLP Trace（可选）

设置标准 OpenTelemetry 环境变量后，`skill-up run` 可经 OTLP 上报 trace；verbose 日志可带 `trace_id` / `span_id`。也可用 `skill-up init` 生成的用户配置填充默认 OTEL 相关环境变量。详见上游文档「User config」与「CLI 命令参考」中的 OTLP 小节。

---

## skill-up validate

校验 `eval.yaml` 及引用的 case 文件。

```bash
skill-up validate [path to eval.yaml]
```

成功示例：

```plain
✓ eval.yaml is valid (loaded 3 case(s))
```

---

## skill-up list-cases

列出配置中的全部用例。

```bash
skill-up list-cases [path to eval.yaml]
```

---

## skill-up report

从已有 `result.json` 重新生成报告，不重跑评测。

```bash
skill-up report <path to result.json> [flags]
```

| Flag           | 默认             | 说明                                |
| -------------- | ---------------- | ----------------------------------- |
| `--format`     | `json`           | `json` / `junit` / `html`（可多次） |
| `--output-dir` | result.json 同级 | 输出目录                            |

```bash
skill-up report result.json --format html
skill-up report result.json --format json --format junit --format html --output-dir ./reports
```

---

## skill-up import

将 Anthropic `evals.json` 转为 skill-up 原生 YAML。

```bash
skill-up import <evals.json> [flags]
```

| Flag       | 默认            | 说明     |
| ---------- | --------------- | -------- |
| `--output` | evals.json 同级 | 输出目录 |

`import` 与 `run --auto` 的区别：`import` 是一次性格式转换；`run --auto` 运行时直接读 `evals.json`，不落 YAML。

---

## skill-up init

将**用户配置模板**写到磁盘（Telemetry、默认 `runtime_kwargs` 等），与评测 `eval.yaml` 不同。

```bash
skill-up init [flags]
```

| Flag              | 说明                                             |
| ----------------- | ------------------------------------------------ |
| `--local`         | 写入 `$PWD/.skill-up.yaml`（与 `--config` 互斥） |
| `--print`         | 打印模板到 stdout，不写文件                      |
| `--force`         | 覆盖已存在文件                                   |
| `--config <path>` | 显式目标路径（需与 `--local` 二选一）            |

默认路径：`$XDG_CONFIG_HOME/skill-up/config.yaml` 或 `~/.config/skill-up/config.yaml`。发现链中还支持环境变量 `SKILL_UP_CONFIG` 指向用户配置文件。

---

## skill-up debug

调试内部模块（仅开发 / 排错常用）：

```bash
skill-up debug judge <input.json>
skill-up debug report <input.json>
```

---

## 产物目录结构

```plain
<skill-name>-workspace/
  iteration-1/
    result.json
    benchmark.json
    report.html          # 若生成
    <case-id>/
      with_skill/
        outputs/
        grading.json
      without_skill/     # 仅 benchmark.enabled=true 时可能有
        outputs/
        grading.json
```

### grading.json（Anthropic 兼容子集）

工作区内的 `grading.json` 通常只含 `expectations` 与 `summary`。完整状态见 `result.json` 的 `case_results[].grading`（`status`、`turns_executed`、`assertion_results` 等）。

### benchmark.json

启用基线对比后会有 `without_skill` 与 `delta` 等字段。

# eval.yaml 字段参考（skill-up）

`eval.yaml` 是评测入口，声明「在什么环境、用什么 Engine、跑哪些用例、如何出报告」。内容对齐 [skill-up 用户手册 - 编写评测](https://alibaba.github.io/skill-up/zh/guide/writing-evals.html)。

## 完整字段骨架

```yaml
schema_version: v1alpha1

environment:
  type: none                      # none | opensandbox | docker

mcp:
  servers:
    - name: github
      mode: real                  # real；mocked 预留
      transport: http             # http | stdio；可按 endpoint/command 推断
      config_ref: evals/fixtures/mcp/github.yaml

skills:
  - source: local_path
    path: .
    include: [SKILL.md, "references/**", "scripts/**"]  # 可选；不配置表示全部文件
    exclude: [".qoder/repowiki/**"]                     # 可选；exclude 优先

engine:
  name: claude_code               # claude_code | codex | qodercli（也兼容 qoder-cli）
  model:
    provider: anthropic
    name: claude-sonnet-4-6
    base_url: ""

cases:
  files:
    - evals/cases/a.yaml
  defaults:
    timeout_seconds: 300
    max_turns: 12
    collect_artifacts:          # 可选：用 glob 采集 workspace 产物文件
      - "**/*.json"
      - "report/**"
    expect:                     # 可选：默认 expect 检查，应用于所有用例
      exit_code: 0
      must_not_contain:
        - "TODO"
        - "I cannot"
  parallelism: 2
  retry_policy:
    max_retries: 1
    retry_on: [timeout, error]

judge:
  type: agent_judge
  model: anthropic/claude-sonnet-4-6
  skills:                         # 可选：仅安装给 judge agent 的评分 Skill
    - source: local_path
      path: evals/fixtures/judge-rubric
  criteria:
    - "按 judge-rubric 中的细则判断输出是否满足要求"

benchmark:
  enabled: false

report:
  formats: [json, html]
  artifacts: [transcript]
```

`cases.parallelism` 可被 `skill-up run --parallelism N`（1–256）临时覆盖。
临时启用基线对比时，可以使用 `skill-up run --baseline`，等价于为本次运行设置 `benchmark.enabled: true`。

`collect_artifacts`（`cases.defaults` 级，或单个 `case.yaml` 内追加）用 [doublestar](https://github.com/bmatcuk/doublestar) glob（`*` 单层、`**` 跨目录）声明要采集的 workspace 文件。无论 Agent 成功/失败/超时，命中文件都会保留相对路径下载到 `<output-dir>/<case>/<config>/outputs/workspace/`。两层按并集去重合并。它与 `report.artifacts`（产物*类型*）、`agent_judge` 的 git diff（字符串）正交。

`skills[].include` / `skills[].exclude` 同样使用 doublestar glob，路径相对
`skills[].path` 且使用 `/` 分隔。`include` 为空时默认包含全部文件；
`exclude` 后应用并优先。`evals/` 始终不会安装。显式配置 include 时要包含
`SKILL.md`。`judge.skills` 也支持同样的过滤字段。

`judge.skills` 仅支持 `judge.type: agent_judge`，用于给 judge agent 安装可复用的评分 Rubric Skill。它不会安装到主运行 agent；顶层 `skills` 也不会自动安装到 judge。benchmark 下 `with_skill` / `without_skill` 都会安装 judge Skills，因为它们属于评分工具。路径相对 Skill 根目录解析，安装依赖具体 Agent adapter 的原生 Skill 支持；不要把 Skill 文件内容复制进 `criteria`。

## 运行环境

| type | 适用场景 | 说明 |
| --- | --- | --- |
| `none` | 纯文本 I/O、不强依赖沙箱 | 冷启动最快 |
| `opensandbox` | 需要远程沙箱（文件、命令执行等） | 需 `OPENSANDBOX_API_KEY`；服务地址等可放在 `environment.kwargs` 或 `OPENSANDBOX_BASE_URL` |
| `docker` | 本地容器隔离，无需远程服务 | 需本地 `docker` CLI 和 Docker daemon；镜像需提前拉取 |

### OpenSandbox 示例

```yaml
environment:
  type: opensandbox
  image: registry.example.com/your-org/sandbox-base:latest
  workspace_mount: /workspace
  ready_timeout_seconds: 300
  kwargs:
    base_url: https://agent-sandbox.example.com
    extensions: '{"profile":"ci"}'
    request_timeout_seconds: "900"
    file_transfer_parallelism: "8"
```

常用 `kwargs`：`base_url`、`extensions`（JSON 字符串）、`request_timeout_seconds`、`file_transfer_parallelism` 等。鉴权密钥来自环境变量 `OPENSANDBOX_API_KEY`。

### Docker 示例

```yaml
environment:
  type: docker
  image: node:22                    # 必填，需提前 docker pull
  workspace_mount: /workspace       # 默认 /workspace
  env:
    NPM_CONFIG_REGISTRY: https://registry.npmmirror.com
  setup_steps:
    - run: npm install -g typescript
  entrypoint: ["sleep", "infinity"] # 默认 sleep infinity
```

前置条件：本地 `docker` CLI 和 Docker daemon。`network_policy: deny_all` 以 `--network=none` 创建容器；`allow_declared` 暂不支持。


## MCP

- `mode: real` 会把真实 MCP Server 装进 Agent。
- HTTP MCP 可 inline 或 `config_ref` 指向 `evals/fixtures/mcp/*.yaml`。
- stdio MCP 可配置 `command` / `args`。
- 环境变量引用：`${VAR}` 或整值 `$VAR`；`required_env` 会注入 Agent 环境。
- eval 级 `mcp` 是默认配置；用例可在 `cases/*.yaml` 里声明自己的 `mcp.servers`（MVP 仅 `mode: mocked`）按 `name` 整条覆盖同名 Server，从而在相同 Server/工具名下切换 mocked fixture。`config_ref` 仍相对 Skill 目录解析。

## Engine 与模型

- `engine.model` 可选；省略时由引擎本地默认模型接管。
- `provider` / `name` 组合在 CLI 中形如 `anthropic/claude-sonnet-4-6`、`openai/gpt-4` 等。
- `qodercli` 通常无需配置 `model`。

### `engine.kwargs` —— agent 私有开关

`engine.kwargs` 是字符串键值对，每个 agent 只读取自己关心的 key，未知 key 被忽略。无人认识的 key（拼写错误，如 `bypas_sandbox`）会在 verbose 日志里打 DEBUG，`-v` 可见。CLI 等价开关：`--engine-kwarg key=value`（别名 `--ek`），可重复。优先级 `--engine-kwarg` > `engine.kwargs` > 缺省。

```yaml
engine:
  name: codex
  kwargs:
    bypass_sandbox: "true"
```

| key | agent | true 时行为 | 缺省 / false |
|---|---|---|---|
| `bypass_sandbox` | `codex` | 命令行强制 `--dangerously-bypass-approvals-and-sandbox`，覆盖根据 runtime 自动决定的 sandbox flag。用于宿主内核不支持 Landlock 的场景（典型：部分 CI 容器） | 维持现状：`none` runtime 用 `--sandbox workspace-write`，其它 runtime 已是 bypass |
| `bypass_sandbox` | `claude_code` | no-op（claude 现有命令已固定 `--permission-mode=bypassPermissions`） | no-op |
| `bypass_sandbox` | `qodercli` | no-op（qoder CLI 无对应 flag） | no-op |

## 常见错误

- `opensandbox` 但未配置鉴权或 `base_url` → 运行时失败
- `engine.model` 与网关不匹配 → 连接报错
- `cases.files` 路径不存在 → validate 失败
- 所有相对路径相对于 **Skill 根目录**（`SKILL.md` 所在目录）

# 安装 / 升级 / 排错

`skill-up` 以预编译单二进制发布在 [GitHub Releases](https://github.com/alibaba/skill-up/releases)，无运行时依赖（不需要 Go、Python、Node 等即可使用官方安装脚本）。

> **平台**：仅支持 **macOS / Linux**，暂不支持 Windows。

## 官方安装脚本（macOS / Linux）

```bash
curl -fsSL https://raw.githubusercontent.com/alibaba/skill-up/main/install.sh | bash
```

脚本行为概要：

- 识别 OS（darwin / linux）与架构（amd64 / arm64）
- 从 GitHub Releases 下载对应压缩包与校验文件
- 默认安装到 `~/.local/bin/skill-up`
- 可用 `sha256sum` / `shasum` 校验（若本机有相应工具）

### 版本与安装目录

```bash
# 固定版本（可为 vX.Y.Z 或 X.Y.Z，脚本会规范化为带 v 的 tag）
export SKILL_UP_VERSION=v0.1.0
curl -fsSL https://raw.githubusercontent.com/alibaba/skill-up/main/install.sh | bash

# 自定义目录
export INSTALL_DIR="$HOME/bin"
curl -fsSL https://raw.githubusercontent.com/alibaba/skill-up/main/install.sh | bash
```

## 验证安装

```bash
skill-up --version
skill-up --help
```

## 升级

再次执行安装脚本即可覆盖旧二进制（可先设 `SKILL_UP_VERSION` 锁定版本）。

## 排错

### `command not found: skill-up`

通常是 `~/.local/bin` 不在 `PATH`。

**macOS（zsh）**：

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

**Linux（bash）**：

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

### 下载失败 / 网络受限

- 配置代理：`export HTTPS_PROXY=http://your-proxy:port`
- 或从 [Releases](https://github.com/alibaba/skill-up/releases) 手动下载对应 `skill-up_*_*.tar.gz` 与 `checksums.txt`，解压后将二进制放到 PATH 内并 `chmod +x`

### macOS "无法验证开发者"

```bash
xattr -d com.apple.quarantine "$(which skill-up)"
```

或在「系统设置 → 隐私与安全性」中允许。

### 从源码构建

已与仓库 schema 一致，适合开发：

```bash
make build
```

# Judge 类型选型与写法（skill-up）

skill-up 的评估分两层：`expect`（零成本门槛） + `judge`（质量评估）。expect 不过 judge 就跳过，所以能用 expect 先过滤的尽量用 expect。

每个用例只能选**一种** judge 类型。

## 选型决策树

1. 有明确关键词 / 文件 / 退出码 / 工具调用可判定？→ **rule_based**
2. 有结构化输出，想写自定义脚本检查？→ **script**
3. 以上都不行，要 LLM 做语义判断？→ **agent_judge**（最贵，慎用）

## rule_based — 确定性规则

```yaml
judge:
  type: rule_based
  success:
    - output_contains:
        all: ["bug", "null"]
        any: ["建议修复", "推荐更改"]
        not: ["LGTM"]
    - output_matches:
        all: ["(?m)^## Status$", "(?m)^## Evidence$"]
        any: ["(?i)pass", "(?i)success"]
        not: ["(?i)api[_-]?key\\s*="]
    - exit_code: 0
    - tool_called:
        name: "github::create_pull_request"
        args:
          title: "Fix null check"
  failure:
    - output_contains:
        any: ["无需修改", "代码正确"]
```

评估逻辑：`failure` 优先，任一条命中立即 FAIL；否则所有 `success` 必须满足才 PASS。

**支持的匹配器**：

- `output_contains`
- `output_matches`（Go regexp，支持 `all` / `any` / `not`）
- `exit_code`
- `tool_called`
- `files_exist` / `files_not_exist`

## agent_judge — LLM 评审

```yaml
judge:
  type: agent_judge
  model: anthropic/claude-sonnet-4-6
  skills:
    - source: local_path
      path: evals/fixtures/judge-rubric
      include: [SKILL.md, "references/**"]
      exclude: ["references/drafts/**"]
  criteria:
    - "输出中识别了真实存在的 bug，并符合 judge-rubric 中的评分细则"
    - "没有将正确代码误报为 bug"
    - "建议具有可操作性，不是泛泛而谈"
  pass_threshold: 0.7
```

**注意事项**：

- 会额外消耗 token，慢且贵
- criteria 尽量具体、可验证
- 能拆出确定性条件时先用 `rule_based` / `expect` 挡一道
- 需要长 Rubric、领域规则、复用评分规范时，把它们放进 `judge.skills`
- `judge.skills` 只会安装给 judge agent，不会污染被测 run agent；安装依赖具体 Agent adapter 的 Skill 支持，不会回退为 prompt 拼接
- `judge.skills[].include` / `exclude` 与顶层 `skills` 语义一致：相对 `path` 的 doublestar glob，且 exclude 优先

## script — 自定义脚本

```yaml
judge:
  type: script
  script_path: evals/fixtures/scripts/check-quality.sh
  timeout_seconds: 30
```

**脚本约定**：

- 退出码 `0` = PASS，非 `0` = FAIL
- 工作目录是用例工作区根目录
- 环境变量：`$EVAL_FINAL_MESSAGE`、`$EVAL_EXIT_CODE`、`$EVAL_TRANSCRIPT_PATH`（若可用）

## 成本提醒

| judge | 相对成本 | 何时选 |
| --- | --- | --- |
| expect | 0 | 任何时候先挡一道 |
| rule_based | 极低 | 默认首选 |
| script | 低（取决于脚本） | 灵活自定义 |
| agent_judge | 高 | 真的需要语义理解 |

# 从 Anthropic evals.json 迁移（skill-up）

若使用 Anthropic skill-creator 生成过 Skill，目录下可能有 `evals/evals.json`。skill-up 可以直接消费它，也可一次性转成原生 YAML。

## 方式一：`--auto` 直接跑（零配置）

```bash
cd my-skill/
skill-up run --auto
skill-up run ./my-skill/ --auto
skill-up run --auto --engine codex
```

**适用**：快速 CI 回归、多 Engine 验证、与 Anthropic evals 源文件保持同步。

**限制**：

- 不支持多轮对话
- `expectations` 往往映射为 `agent_judge.criteria`，消耗评审 token
- 不便在 `--auto` 路径上叠加复杂 `opensandbox` / MCP / 强 `expect` 门槛（需转 YAML 后编辑）

## 方式二：`import` 转原生 yaml（深度定制）

```bash
skill-up import ./evals/evals.json
skill-up import ./evals/evals.json --output ./evals-v2
```

生成 `eval.yaml` + `cases/*.yaml` 后，你可以：

- 添加 `expect` 确定性门槛
- 使用 `rule_based` / `script` 替代或补充 LLM 评判
- 配置多轮 `turns`
- 配置 `environment.type: opensandbox`、MCP 等

## 对比

| | `--auto` | `import` |
| --- | --- | --- |
| 操作 | 运行时读取 | 一次性落盘 YAML |
| 同步 | evals.json 更新即生效 | 之后独立维护 YAML |
| 定制 | 受限于 JSON | 完全可控 |

> 可先用 `--auto` 跑通，再对重试用例 `import` 手改。

## evals.json 映射（摘要）

| evals.json | skill-up YAML |
| --- | --- |
| `prompt` | `input.prompt` |
| `expectations` | 默认 `judge.agent_judge.criteria` |
| `expected_output` | 常为 `description` |
| `files` | `context.files` 等 |

## 推荐路径

1. `skill-up run --auto` 验证可走通  
2. `skill-up import ./evals/evals.json --output ./evals-native`  
3. 编辑 YAML：补 `expect`、`rule_based`、`opensandbox` / MCP  
4. `skill-up run ./evals-native/eval.yaml`

Ideal：Anthropic 迭代 Skill → skill-up `--auto` 进 CI → 深度场景转 YAML 长期维护。