Skill Test Generate

SKILL.md

---
name: skill-test-generate
description: 为任意 Agent Skill 自动生成 SFT 级别的功能测试用例，JSON 格式结构化输出。适用于生成测试用例、测试Skill、SFT测试、功能验证、技能测试、测试生成等场景。
---

# Skill 测试用例生成器

基于 **Agent 语义理解**，为任意遵循 [Agent Skills 标准](https://agentskills.io/specification) 的 Skill 自动生成 **SFT（功能测试）** 级别的测试用例，以 JSON 格式结构化输出。

## 设计理念

- **使用者视角**：测试粒度是 Skill 使用者（LLM Agent）能够理解和操作的功能层面，不拆到字段级或行级的单元测试
- **通用兼容**：不绑定特定平台，兼容有 handler（可执行型）和纯 prompt（指令型）两种 Skill 形态
- **语义驱动**：由 Agent 读取 Skill 文件并理解其语义，据此生成测试用例，不依赖正则匹配
- **精简输出**：测试用例只提供核心字段（case_id、title、scenario、user_input、source_refs），期望行为、严重度、标签等由测试 Agent 自行判断

## 输入：指定目标 Skill

用户必须指定要生成测试的目标 Skill，支持以下形式：

| 用户说 | 目标参数 |
|-------|---------|
| "为已安装的 `pdf` skill 生成测试" | `installed:pdf` |
| "为 `/path/to/my-skill` 目录生成测试" | `/path/to/my-skill` |
| "为这个 zip 生成测试：`/tmp/my-skill.zip`" | `/tmp/my-skill.zip` |

## 输出：结构化 JSON

输出 JSON 的完整 Schema 定义见 `references/test-schema.md`。核心结构概要：

```json
{
  "schema_version": "1.0",
  "generated_at": "<ISO 8601 UTC 时间戳>",
  "skill": {
    "name": "...",
    "description": "...",
    "source_path": "...",
    "capabilities": ["能力1", "能力2"]
  },
  "test_suites": [
    {
      "suite_id": "TS-01",
      "name": "技能激活与路由",
      "description": "...",
      "cases": [
        {
          "case_id": "TC-01-001",
          "title": "...",
          "scenario": "...",
          "user_input": "...",
          "source_refs": [
            { "file": "SKILL.md", "lines": [1, 10] }
          ]
        }
      ]
    }
  ],
  "summary": { ... }
}
```

> **注意**：`summary` 字段**不要手动添加**——由 `validate` 子命令根据 `test_suites` 自动统计生成。

## 5 大测试维度

从 Skill 使用者视角出发，按以下 5 大维度生成测试用例。每个维度对应一个或多个 test_suite：

### 1. 技能激活与路由（suite_id 前缀: TS-01）

验证 Agent 能否根据用户意图正确识别何时该/不该激活此 Skill。

**典型用例**：
- ✅ 用户意图匹配 Skill 核心能力 → 应激活
- ✅ 用户意图与 Skill 无关 → 不应激活
- ✅ 用户意图模糊，处于边界 → 应能合理处理

### 2. 核心功能（suite_id 前缀: TS-02 起，每项能力一个 suite）

对 Skill 声称的**每项能力**分别生成测试。从 SKILL.md 的 description、body、handler 的 input_schema 或正文描述中提取能力列表，每项能力对应一个 test_suite。

**典型用例**：
- ✅ 正常输入 → 功能按预期工作
- ✅ 空输入或缺少必要参数 → 优雅处理
- ✅ 特殊/边界输入 → 不崩溃，合理响应

### 3. 多步工作流（suite_id 前缀: 倒数第二个 suite）

验证 Skill 是否支持连续/组合调用完成组合任务。

**典型用例**：
- ✅ 先调用能力 A，再调用能力 B → 两步均成功
- ✅ 同一 Skill 被连续调用 → 不出现状态残留或冲突

### 4. 指令可理解性（suite_id: 倒数第二个+1）

验证 SKILL.md 正文中的指令对 Agent 是否清晰可执行。

**典型用例**：
- ✅ 正文引用的脚本/参考文档是否存在
- ✅ 指令步骤是否完整，是否有歧义或矛盾
- ✅ 缺少必要信息时 Agent 是否能判断

### 5. 异常与安全（最后一个 suite）

验证面对异常/恶意输入时是否安全处理。

**典型用例**：
- ✅ 超长输入 → 不崩溃
- ✅ 特殊字符/注入尝试 → 安全处理
- ✅ 无效参数组合 → 不崩溃，返回有意义的错误

## Agent 工作流

### 步骤 1 — 收集目标与输出路径

向用户询问（或从上下文推断）：
1. **目标 Skill**：已安装名称、目录路径或 zip 文件路径
2. **输出路径**：JSON 结果写入位置（如 `./my-skill-tests.json`）

如果都未指定，提示用户。

### 步骤 2 — 准备 Skill 文件

使用辅助脚本解析 Skill 路径并列出所有文件：

```bash
python scripts/generate.py prepare --skill <target>
```

其中 `scripts/generate.py` 位于：
`~/.workbuddy/skills/skill-test-generate/scripts/generate.py`

此命令会：
- 解析 `installed:<name>`、目录或 zip 路径
- 输出 JSON：`skill_name`、`skill_path`、`files`（`{path, size, line_count}` 列表）、`file_index`（path → {size, line_count} 映射）、`frontmatter`（name, description 等元数据）
- `line_count` 可帮助你为 `source_refs` 填写准确的行号范围

如果目标是 zip，会解压到临时目录（路径包含在输出中）。

### 步骤 3 — 阅读全部 Skill 文件

**⛔ 必须阅读目标 Skill 中的所有文件**，不要只看 SKILL.md。脚本、参考文档中可能包含 SKILL.md 未提到的能力或约束。

**首先阅读 SKILL.md**，获取：
- Skill 的用途和声称的能力
- 使用方式和触发条件
- 工作流步骤和脚本调用约定

**然后逐一阅读** `scripts/` 和 `references/` 下的所有文件，理解：
- 脚本的实际行为和参数
- 参考文档中的额外约束或能力
- 代码中的边界处理和错误处理逻辑

### 步骤 4 — 提取能力列表并规划测试

基于对 Skill 的完整理解，提取能力列表。能力来源优先级：
1. SKILL.md 正文明确描述的能力
2. handler 的 input_schema 中定义的 action/功能
3. 脚本的子命令或主要功能

然后按 5 大维度规划 test_suite 结构：
- **TS-01**：技能激活与路由（1 个 suite，2-4 个 cases）
- **TS-02 ~ TS-N**：核心功能（每项能力 1 个 suite，每个 suite 2-5 个 cases）
- **TS-N+1**：多步工作流（1 个 suite，1-3 个 cases；若 Skill 仅有一项能力可省略）
- **TS-N+2**：指令可理解性（1 个 suite，2-4 个 cases）
- **TS-N+3**：异常与安全（1 个 suite，2-4 个 cases）

### 步骤 5 — 生成测试用例 JSON

按 `references/test-schema.md` 中定义的格式组装完整 JSON。

**用例编写原则**：
- 每个 case 的 `user_input` 必须是**用户视角的自然语言**，不是 API 调用
- `scenario` 要说明这个测试场景在验证什么
- `source_refs` 要指向目标 Skill 中与该用例直接相关的源代码位置

**⚠️ 不要手动添加 `summary` 字段**——由 validate 脚本自动生成。

#### 🎯 边界用例覆盖指引

生成测试用例时，**不仅要覆盖 happy_path，还要系统性地挖掘边界和异常场景**。以下清单帮助确保覆盖面足够广：

**输入边界**：
- 空输入 / 缺少必要参数
- 超长输入（文本、列表、嵌套结构）
- 特殊字符输入（Unicode、表情符号、控制字符、HTML/JS 代码）
- 负数、零、极大值等数值边界
- 格式错误的输入（如期望 JSON 但给了纯文本）

**功能边界**：
- 同一能力的不同参数组合（最小参数集 vs 全参数集）
- 能力的可选参数省略时的行为
- 参数间的依赖关系和互斥关系
- 幂等性：同一请求多次执行是否结果一致

**路由边界**：
- 与 Skill 能力**部分相关**的模糊意图
- 多个 Skill 都可能匹配的意图（歧义场景）
- 用户使用了 Skill 能力的**同义词/俗称**

**状态与上下文边界**：
- Skill 连续调用后是否有状态残留
- 前一次调用失败后再次调用的恢复行为
- 并发请求（如果 Skill 设计支持）

**指令完整性**：
- SKILL.md 中引用的脚本/文件是否实际存在
- 工作流步骤是否有缺失或顺序矛盾
- 参考文档中的约束是否在正文中也有说明

#### 📍 source_refs 填写要求

每个测试用例**必须**填写 `source_refs`，指向目标 Skill 中与该用例直接相关的源代码位置：

- **纯描述型功能**：`file` 为 `"SKILL.md"`，`lines` 指向描述该功能的段落
- **脚本实现型功能**：`file` 为脚本相对路径（如 `"scripts/analyze.py"`），`lines` 指向实现该功能的函数/代码块
- **跨文件功能**：可引用多个文件，如同时引用 SKILL.md 的描述段落和脚本中的实现代码
- **行号范围**：使用 `[start, end]` 格式，尽量精确定位到相关代码段落，不要过大也不要过小
- **路径格式**：使用 POSIX 风格（正斜杠 `/`），与 `prepare` 命令输出一致

**填写策略**：在步骤 3 阅读 Skill 文件时，同时记录每个功能对应的文件和行号范围，这样在步骤 5 生成用例时可以直接引用。

### 步骤 6 — ⛔ 强制验证输出（必须执行）

**在写入 JSON 文件后、向用户展示结果前，必须调用验证脚本校验输出格式：**

```bash
python scripts/generate.py validate --file <输出 JSON 文件路径> --skill <目标 Skill 路径>
```

> `--skill` 参数可选。如果提供，validate 会校验 `source_refs` 中引用的文件是否存在、行号是否超出实际行数。强烈建议提供此参数以确保溯源信息准确。如果省略，则从 JSON 的 `skill.source_path` 推断。

验证脚本会检查：
- 顶层结构完整性（`schema_version`、`generated_at`、`skill`、`test_suites`）
- 每个 suite 的必填字段和字段类型
- 每个 case 的必填字段（`case_id`、`title`、`scenario`、`user_input`、`source_refs`）
- `case_id` 全局唯一性
- `source_refs` 格式正确性（`file` 非空字符串、`lines` 为 2 个正整数且 start ≤ end）
- `source_refs` 文件存在性（如果提供了 `--skill` 参数）
- `source_refs` 行号不超出文件实际行数（如果提供了 `--skill` 参数）

**验证不通过时**：脚本会输出详细的错误列表。你必须根据错误修正 JSON 文件，然后重新运行验证，直到通过。

**验证通过时**：脚本会自动从 `test_suites` 生成 `summary`（各项计数），并在 JSON 文件中添加 `"verified": true` 字段。

**⛔ 跳过此步骤的输出结果视为无效，不可作为最终交付。**

### 步骤 7 — 展示结果

读取 JSON 输出，以人类可读的摘要呈现：
- Skill 概览（名称、能力列表）
- 各测试套件的用例数和覆盖范围
- 总用例数统计

## 辅助脚本命令

`scripts/generate.py` 辅助脚本提供以下子命令：

| 命令 | 用途 |
|------|------|
| `prepare --skill <target>` | 解析路径、列出文件（含行数）、提取 SKILL.md 元数据 |
| `validate --file <json路径> [--skill <skill路径>]` | ⛔ 验证输出 JSON 格式，校验 source_refs，自动生成 `summary`，通过后添加 `verified: true` |

## 纯 prompt 型 Skill 的处理

对于没有 handler、没有 scripts，仅通过 SKILL.md 正文向 Agent 提供指令的 Skill：
- **核心功能**测试关注 Agent 能否根据正文指令正确执行
- **多步工作流**关注 Agent 是否按正文步骤顺序执行
- 不生成涉及脚本/参数的测试用例，改为生成指令理解类用例

## 注意事项

- 辅助脚本仅使用 Python 标准库，无需安装第三方依赖
- 在 **Windows** 上注意路径分隔符和临时目录差异
- 始终阅读**所有**文件，而非仅 SKILL.md，以捕获隐藏的能力和约束
- 测试用例粒度保持**功能级**：一个 case 验证一个用户可感知的功能场景，不要拆成字段级的单元测试
- Agent 的语义理解是主要的测试生成方法——不使用正则模式提取