技能测试框架使用指南

xopcbot 提供了一套完整的技能测试框架，用于验证技能的质量、安全性和功能性。

目录

• 快速开始
• 测试类型
• CLI 命令
• 测试框架 API
• 编写技能测试
• CI/CD 集成
• 最佳实践

快速开始

运行所有技能测试

# 使用 CLI 命令
pnpm run dev -- skills test

# 详细输出
pnpm run dev -- skills test --verbose

# JSON 格式
pnpm run dev -- skills test --format json

测试单个技能

# 测试特定技能
pnpm run dev -- skills test weather

# 详细输出
pnpm run dev -- skills test weather --verbose

运行单元测试

# 运行测试框架单元测试
pnpm test src/agent/skills/__tests__/test-framework.test.ts

测试类型

测试框架包含以下测试类型：

1. SKILL.md 格式验证

验证 SKILL.md 文件的格式是否正确：

• ✅ YAML frontmatter 存在
• ✅ 必需字段（name, description）存在
• ✅ 字段类型正确
• ✅ 内容长度足够

示例输出：

✓ SKILL.md format: Valid SKILL.md format

2. 依赖检查

检查技能声明的依赖是否满足：

• ✅ 必需的二进制文件存在
• ✅ anyBins 至少有一个可用
• ✅ 安装器配置正确

示例输出：

✓ Dependencies: All dependencies satisfied
  - Found binary: node
  - Found binary: curl

3. 安全扫描

扫描技能目录中的代码安全问题：

• ⚠️ 危险函数使用（exec, eval 等）
• ⚠️ 文件系统访问
• ⚠️ 网络操作
• ⚠️ 环境变量访问

示例输出：

✓ Security: No security issues
  - Critical: 0
  - Warnings: 0
  - Info: 0

4. 元数据完整性

检查技能元数据是否完整：

• ✅ Emoji 图标
• ✅ Homepage 链接
• ✅ 操作系统限制
• ✅ 安装器定义

示例输出：

⚠ Metadata: Metadata could be improved
  - Emoji: 🌤️
  - No homepage defined (recommended)

5. 示例验证

验证 SKILL.md 中的代码示例：

• ✅ 提取代码块
• ✅ 检查 Shell 语法
• ✅ 验证命令格式

示例输出：

✓ Examples: Examples validated
  - Found 5 code block(s)
  - Shell examples: 3

CLI 命令

主测试命令

# 测试所有技能
xopcbot skills test

# 测试特定技能
xopcbot skills test <skill-name>

# 指定技能目录
xopcbot skills test --skills-dir ./my-skills

# 输出格式（text/json/tap）
xopcbot skills test --format json

# 详细输出
xopcbot skills test --verbose

# 严格模式（警告也视为失败）
xopcbot skills test --strict

# 跳过特定测试
xopcbot skills test --skip-security
xopcbot skills test --skip-deps
xopcbot skills test --skip-examples

验证命令

# 验证单个 SKILL.md 文件
xopcbot skills test validate ./skills/weather/SKILL.md

# 严格模式
xopcbot skills test validate ./skills/weather/SKILL.md --strict

依赖检查命令

# 检查所有技能的依赖
xopcbot skills test check-deps

# 检查特定技能
xopcbot skills test check-deps weather

安全审计命令

# 审计所有技能
xopcbot skills test security

# 审计特定技能
xopcbot skills test security weather

# 详细输出
xopcbot skills test security --deep

测试框架 API

基本使用

import { SkillTestFramework } from './agent/skills/test-framework.js';

// 创建测试框架实例
const framework = new SkillTestFramework({
  skipSecurity: false,      // 是否跳过安全测试
  skipDeps: false,          // 是否跳过依赖测试
  skipExamples: false,      // 是否跳过示例测试
  strict: false,            // 严格模式
  exampleTimeout: 10000,    // 示例测试超时（ms）
});

// 测试单个技能
const report = await framework.testSkill('/path/to/skill');

console.log(`Passed: ${report.passed}`);
console.log(`Results: ${report.summary.passed}/${report.summary.total}`);

// 访问详细结果
for (const result of report.results) {
  console.log(`${result.name}: ${result.status} - ${result.message}`);
  if (result.details) {
    for (const detail of result.details) {
      console.log(`  - ${detail}`);
    }
  }
}

批量测试

import { SkillTestRunner } from './agent/skills/test-framework.js';

const runner = new SkillTestRunner({
  skillsDir: './skills',
  skipSecurity: false,
  skipDeps: false,
  skipExamples: true,  // 批量测试时通常跳过示例
  verbose: true,
});

const { reports, passed } = await runner.run();

console.log(`Tested ${reports.length} skills`);
console.log(`All passed: ${passed}`);

结果格式化

import { 
  formatTestResults,
  formatTestResultsJson,
  formatTestResultsTap,
} from './agent/skills/test-framework.js';

// 文本格式
const textOutput = formatTestResults(reports, true);
console.log(textOutput);

// JSON 格式
const jsonOutput = formatTestResultsJson(reports);
console.log(jsonOutput);

// TAP 格式（用于 CI/CD）
const tapOutput = formatTestResultsTap(reports);
console.log(tapOutput);

编写技能测试

单元测试示例

import { describe, it, expect } from 'vitest';
import { SkillTestFramework } from '../test-framework.js';

describe('My Skill Tests', () => {
  it('should have valid SKILL.md format', () => {
    const framework = new SkillTestFramework();
    const result = framework.testSkillMdFormat('./skills/my-skill/SKILL.md');
    
    expect(result.status).toBe('pass');
  });

  it('should have all dependencies', async () => {
    const framework = new SkillTestFramework();
    const metadata = {
      name: 'my-skill',
      description: 'My skill',
      requires: {
        bins: ['node', 'npm'],
      },
    };
    
    const result = await framework.testDependencies(metadata);
    expect(result.status).toBe('pass');
  });
});

集成测试示例

import { describe, it, expect } from 'vitest';
import { SkillTestRunner } from '../test-framework.js';

describe('Skills Integration Tests', () => {
  it('should pass all skills tests', async () => {
    const runner = new SkillTestRunner({
      skillsDir: './skills',
      skipExamples: true,  // Skip slow example tests
    });

    const { reports, passed } = await runner.run();
    
    expect(passed).toBe(true);
    expect(reports.length).toBeGreaterThan(0);
  });
});

CI/CD 集成

GitHub Actions

项目已包含预配置的 GitHub Actions workflow：

# .github/workflows/skills-test.yml
name: Skills Test

on:
  push:
    paths:
      - 'skills/**'
      - 'src/agent/skills/**'
  pull_request:
    paths:
      - 'skills/**'

jobs:
  test-skills:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: pnpm install
      - run: pnpm run build
      - run: xopcbot skills test --verbose

自定义 CI 配置

name: Custom Skills Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
      
      - name: Install dependencies
        run: pnpm install
      
      - name: Build
        run: pnpm run build
      
      - name: Run skill tests
        run: |
          xopcbot skills test \
            --format tap \
            --skip-examples \
            --strict
      
      - name: Security audit
        run: xopcbot skills test security --deep

本地回归测试

#!/bin/bash
# scripts/test-skills-local.sh

set -e

echo "Running local skill regression tests..."

# Run unit tests
pnpm test src/agent/skills/__tests__/test-framework.test.ts

# Run integration tests
xopcbot skills test --verbose

# Run security audit
xopcbot skills test security --deep

echo "All tests passed!"

最佳实践

1. 测试覆盖

确保每个技能都通过以下测试：

• ✅ SKILL.md 格式验证
• ✅ 依赖检查
• ✅ 安全扫描
• ✅ 元数据完整性

2. CI/CD 集成

在 CI/CD 流程中：

• 运行所有技能测试
• 启用严格模式
• 失败时阻止合并
• 生成测试报告

3. 本地开发

在本地开发技能时：

# 快速验证格式
xopcbot skills test validate ./skills/my-skill/SKILL.md

# 检查依赖
xopcbot skills test check-deps my-skill

# 完整测试
xopcbot skills test my-skill --verbose

4. 性能优化

对于大量技能：

# 跳过慢速测试
xopcbot skills test --skip-examples

# 只测试变更的技能（未来支持）
xopcbot skills test --changed-since HEAD~1

5. 测试报告

生成测试报告：

# JSON 格式（用于机器读取）
xopcbot skills test --format json > test-results.json

# TAP 格式（用于 CI/CD）
xopcbot skills test --format tap > test-results.tap

# 详细文本（用于人工阅读）
xopcbot skills test --verbose > test-results.txt

故障排除

测试失败

# 查看详细输出
xopcbot skills test --verbose

# 跳过特定测试
xopcbot skills test --skip-security

依赖问题

# 检查所有依赖
xopcbot skills test check-deps

# 安装缺失的依赖
xopcbot skills install <skill-name>

安全问题

# 详细安全审计
xopcbot skills test security --deep

# 查看具体发现
xopcbot skills audit <skill-name> --deep

测试输出格式

文本格式（默认）

人类可读的详细输出：

Skill Test Results
==================

✅ weather
   SKILL.md format: Valid SKILL.md format
   Dependencies: All dependencies satisfied
   Security: No security issues
   Metadata: Complete
   Examples: 5 code block(s)

Summary: 1/1 skills passed

JSON 格式

用于机器读取和 CI/CD 集成：

{
  "totalSkills": 1,
  "passedSkills": 1,
  "failedSkills": 0,
  "reports": [
    {
      "skillName": "weather",
      "skillPath": "./skills/weather",
      "passed": true,
      "results": [
        {
          "name": "SKILL.md format",
          "status": "pass",
          "message": "Valid SKILL.md format"
        }
      ]
    }
  ]
}

TAP 格式

用于 CI/CD 系统的 Test Anything Protocol：

TAP version 13
1..2
ok 1 - weather/SKILL.md format
ok 2 - weather/Dependencies

参考资料

• 技能系统使用指南
• 测试框架源码
• 测试示例

---

最后更新：2026-02-22