273 lines
8.5 KiB
Markdown
273 lines
8.5 KiB
Markdown
---
|
||
name: skill-tester
|
||
phases: ["all"]
|
||
description: >-
|
||
SKILL 体系自动化测试工具。通过 LLM-as-Judge 模式对 SKILL.md 的行为逻辑进行回归测试，
|
||
验证阶段守卫、规则遵循、输出格式等维度。触发关键词："测试Skill"、"测试 [skill名]"、
|
||
"回归测试"、"skill test"、"跑测试"。
|
||
---
|
||
|
||
# 相位守卫（Phase Guard）
|
||
|
||
**本 Skill 加载后的首个强制动作：**
|
||
1. 读取 `.opencode/phase/current.json`
|
||
2. 若 `phases` 不包含 `"all"` 且当前 `phase` 值不在 `phases` 列表中：
|
||
- 立即中止，输出："当前阶段为 [phase]，skill-tester Skill 不可用。"
|
||
- 不得执行本 Skill 的任何后续流程
|
||
3. 否则：继续执行
|
||
|
||
---
|
||
|
||
# 概述
|
||
|
||
skill-tester 是元层测试工具，分两层：
|
||
- **Layer 1（静态检查）**：无需 LLM，毫秒级。检测文件间交叉引用一致性。每次框架变更后必跑。
|
||
- **Layer 2（行为测试）**：LLM-as-Judge，验证 SKILL.md 的指令逻辑。
|
||
|
||
**建议顺序**：先跑 Layer 1（免费+快），通过后再跑 Layer 2（消耗 token）。
|
||
|
||
**核心原理**：将 SKILL.md 内容 + 模拟用户输入注入 sub-agent，观察其输出是否符合预期，
|
||
再用另一个 sub-agent 作为裁判评分。
|
||
|
||
**不测试什么**：opencode 的 Skill 加载机制本身（那是 opencode 的责任）。
|
||
**测试什么**：SKILL.md 中的指令逻辑——当 LLM 忠实执行这些指令时，产生正确的行为。
|
||
|
||
---
|
||
|
||
# Layer 1：静态一致性检查（无需 LLM）
|
||
|
||
## 概述
|
||
|
||
Layer 1 是纯文件级检查，检测 canonical-manifest.json、opencode-init SKILL.md、
|
||
registry.md、各 SKILL.md 之间的交叉引用一致性。**不需要 LLM 调用，毫秒级运行。**
|
||
|
||
适合作为 git pre-commit hook 或 CI 检查项。
|
||
|
||
### 安装 git pre-commit hook（可选）
|
||
|
||
```
|
||
# Windows
|
||
copy .opencode\skills\skill-tester\hooks\pre-commit .git\hooks\pre-commit
|
||
|
||
# Unix
|
||
ln -sf ../../.opencode/skills/skill-tester/hooks/pre-commit .git/hooks/pre-commit
|
||
```
|
||
|
||
安装后，每次 `git commit` 如果涉及 `.opencode/skills/` 下的文件变更，会自动运行 7 项检查。不通过则阻止提交。
|
||
|
||
## 检查项
|
||
|
||
| 检查 | 描述 | 覆盖的问题 |
|
||
|------|------|-----------|
|
||
| manifest-skills-sync | manifest canonical_skills 与 init Skills 白名单一致 | 新增 Skill 后忘记更新 init → 被误删 |
|
||
| manifest-phase-sync | manifest template_phase_files 与 init 阶段数据占位目录一致 | 新增 phase 文件后落入 C 组 |
|
||
| registry-types | registry 中 phases≠["all"] 的 Skill 类型为"基础设施" | game-design 被标为"项目级"而被误删 |
|
||
| phase-guard-all | 所有 SKILL.md Phase Guard 包含 "all" 处理 | "all" 特殊值未处理导致基础设施 Skill 被错误拒绝 |
|
||
| init-templates | manifest 每个文件在 init 模板内容章节有对应模板 | 缺少重置模板导致 init 时文件丢失 |
|
||
| frontmatter | 所有 SKILL.md 的 YAML frontmatter 完整（name + phases） | opencode 无法注册该 Skill |
|
||
|
||
## 运行方式
|
||
|
||
```bash
|
||
python .opencode/skills/skill-tester/static-checks/run.py
|
||
```
|
||
|
||
退出码：全部通过 = 0，有失败 = 1。可直接集成到 CI/pre-commit。
|
||
|
||
## 新增检查项
|
||
|
||
编辑 `static-checks/run.py`，在 `CHECKS` 列表追加新函数即可，格式为：
|
||
```python
|
||
("check-id", "检查名称", check_function)
|
||
```
|
||
|
||
---
|
||
|
||
# Layer 2：LLM-as-Judge 行为测试
|
||
|
||
---
|
||
|
||
# 操作 A：测试单个 Skill
|
||
|
||
## 触发
|
||
|
||
用户说"测试 [Skill 名称]"、如 "测试 game-design"、"测试 dev-changelog"。
|
||
|
||
## 流程
|
||
|
||
```
|
||
0. 【强制】先运行 Layer 1 静态检查：
|
||
python .opencode/skills/skill-tester/static-checks/run.py
|
||
→ 如有 FAIL，提示用户先修复再跑 Layer 2
|
||
→ 全部 PASS 则继续
|
||
1. 读取目标 Skill 的 SKILL.md
|
||
2. 读取 .opencode/skills/skill-tester/test-cases/ 下匹配该 Skill 的测试用例
|
||
3. 列出测试用例清单，询问用户确认
|
||
4. 用户确认后，逐一执行
|
||
5. 汇总报告
|
||
```
|
||
|
||
## 步骤 3：测试用例预览
|
||
|
||
```
|
||
Agent 输出：
|
||
"找到 [N] 个针对 [Skill名] 的测试用例：
|
||
|
||
| # | ID | 场景 | 严重度 |
|
||
|---|-----|------|--------|
|
||
| 1 | phase-guard-001 | 非匹配阶段拒绝加载 | critical |
|
||
| 2 | ... | ... | ... |
|
||
|
||
预计消耗约 [估算token] tokens。是否全部执行？(y/n/选择特定用例)"
|
||
```
|
||
|
||
## 步骤 4：单用例执行
|
||
|
||
### 4.1 构造模拟 Sub-agent
|
||
|
||
将以下内容组装为一个 prompt，通过 Task tool（sub-agent type = general）执行：
|
||
|
||
```
|
||
你正在模拟一个 opencode agent，该 agent 刚刚加载了以下 Skill：
|
||
|
||
---
|
||
[目标 SKILL.md 的完整内容]
|
||
---
|
||
|
||
**当前会话上下文：**
|
||
- 当前阶段 (phase)：[test_case.phase]
|
||
- 用户消息："[test_case.user_message]"
|
||
- state.json 状态：[test_case.state]（如适用）
|
||
|
||
**你的任务**：严格按照上述 Skill 中的指令行事。
|
||
你拥有所有 opencode agent 的工具（bash/read/write/edit/...）。
|
||
|
||
用户说了："[test_case.user_message]"
|
||
|
||
请输出你的响应。只输出你作为 agent 会输出的内容。
|
||
注意：
|
||
- 如果是 phase guard 测试，第一个行为应该是检查阶段并可能中止
|
||
- 如果 Skill 要求写文件，输出你打算写什么以及写到哪个文件（但不要实际写）
|
||
- 如果 Skill 有强制规则（如 Hallucination 防御），务必遵守
|
||
```
|
||
|
||
### 4.2 执行并收集输出
|
||
|
||
```
|
||
Agent 调用 Task tool → 等待 sub-agent 完成 → 收集其文本输出
|
||
```
|
||
|
||
### 4.3 Judge 评估
|
||
|
||
将模拟 sub-agent 的输出 + 预期行为 + 评分标准传给 Judge sub-agent。
|
||
|
||
Judge 的详细指令见 [judge-prompt.md](judge-prompt.md)。
|
||
|
||
调用方式：
|
||
```
|
||
Agent 调用 Task tool，prompt 为 judge-prompt.md 的内容（已填充变量）→ 等待完成
|
||
```
|
||
|
||
### 4.4 记录结果
|
||
|
||
```json
|
||
{
|
||
"test_id": "phase-guard-001",
|
||
"skill": "game-design",
|
||
"timestamp": "...",
|
||
"scores": {
|
||
"behavior_match": 5,
|
||
"output_clarity": 4,
|
||
"rule_compliance": 5
|
||
},
|
||
"overall": 4.7,
|
||
"judge_feedback": "Agent 正确识别了阶段不匹配..."
|
||
}
|
||
```
|
||
|
||
## 步骤 5：汇总报告
|
||
|
||
```
|
||
Agent 输出（Markdown）：
|
||
|
||
## 测试报告：[Skill 名称]
|
||
|
||
**执行时间**：[timestamp]
|
||
**测试用例数**：[total] | 通过：[pass] | 失败：[fail] | 跳过：[skip]
|
||
|
||
| # | ID | 场景 | 行为 | 清晰度 | 合规 | 总分 | 状态 |
|
||
|---|-----|------|------|--------|------|------|------|
|
||
| 1 | phase-guard-001 | 阶段拒绝 | 5 | 4 | 5 | 4.7 | ✅ |
|
||
| 2 | ... | ... | ... | ... | ... | ... | ❌ |
|
||
|
||
### 失败用例详情
|
||
#### [ID] — [场景]
|
||
- **预期**：[expected 描述]
|
||
- **实际**：[agent 实际输出摘要]
|
||
- **裁判反馈**：[judge 的具体反馈]
|
||
- **建议**：[改进建议]
|
||
```
|
||
|
||
---
|
||
|
||
# 操作 B：回归测试（全部 Skill）
|
||
|
||
## 触发
|
||
|
||
用户说"回归测试"、"跑全部测试"、"test all skills"。
|
||
|
||
## 流程
|
||
|
||
```
|
||
1. 读取 test-cases/ 下所有测试用例
|
||
2. 按 Skill 分组展示
|
||
3. 询问用户确认（因为消耗较大）
|
||
4. 按 Skill 逐一执行（每个 Skill 内部用例并行执行）
|
||
5. 汇总全部报告
|
||
```
|
||
|
||
## 执行策略
|
||
|
||
- 同一 Skill 内的多个用例可以**并行执行**（无状态依赖）
|
||
- 不同 Skill 之间**顺序执行**（避免混淆）
|
||
- 单个用例超时 60 秒
|
||
- 如有用例执行失败（sub-agent 错误），标记为 ERROR 而非 FAIL
|
||
|
||
---
|
||
|
||
# 操作 C：查看历史报告
|
||
|
||
## 触发
|
||
|
||
用户说"查看测试报告"、"上次测试结果"。
|
||
|
||
## 流程
|
||
|
||
读取 `.opencode/skills/skill-tester/reports/` 下最新报告，展示摘要。
|
||
|
||
---
|
||
|
||
# 评分标准说明
|
||
|
||
每个测试用例在 3 个维度上评分（1-5）：
|
||
|
||
| 维度 | 含义 | 5 分标准 |
|
||
|------|------|---------|
|
||
| **行为匹配 (behavior_match)** | Agent 的输出行为是否符合预期 | 核心决策（如加载/拒绝加载）完全正确 |
|
||
| **输出清晰度 (output_clarity)** | 输出是否清晰、无歧义 | 信息完整、结构清楚、用户可直接理解 |
|
||
| **规则合规 (rule_compliance)** | 是否遵守了 SKILL.md 中的强制规则 | 所有强制检查点均已执行 |
|
||
|
||
**通过标准**：总分 >= 4.0（即平均每维度 >= 4.0）。
|
||
**警告标准**：3.0 <= 总分 < 4.0。
|
||
**失败标准**：总分 < 3.0。
|
||
|
||
---
|
||
|
||
# 自迭代日志
|
||
|
||
本节记录使用本 Skill 过程中发现的必要检查项。
|
||
|
||
### 已知必要检查
|
||
|
||
1. **Layer 1 必须在每次框架结构变更后运行** — 新增 Skill、修改 manifest 分组、新增数据文件后，`static-checks/run.py` 的 6 项检查必须全部通过。历史教训：新增 `template_phase_files` 后未同步 init Skill 的 3 个截面，导致 phase 文件落入 C 组；`game-design` 被标为"项目级"导致 init 时被 registry 删除。
|