Skill 测试用例生成器#

基于 Agent 语义理解，为任意遵循 Agent Skills 标准 的 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 的语义理解是主要的测试生成方法——不使用正则模式提取