xiaosanwan-skill-validator（小三丸技能验证器）

🧪 Skill 功能验证工具

一句话描述：验证新安装 Skill 的功能是否正常，发现潜在问题，提供完善建议。

🎯 设计思路

验证方法论

验证流程

┌─────────────────┐
│  读取 SKILL.md  │ ← 获取功能描述、依赖
└────────┬────────┘
         ▼
┌─────────────────┐
│  检查依赖项     │ ← bins、env、files
└────────┬────────┘
         ▼
┌─────────────────┐
│  举例法验证     │ ← 正常场景测试
└────────┬────────┘
         ▼
┌─────────────────┐
│  反证法验证     │ ← 边界/异常测试
└────────┬────────┘
         ▼
┌─────────────────┐
│  破解法验证     │ ← 压力/安全测试
└────────┬────────┘
         ▼
┌─────────────────┐
│  生成验证报告   │ ← 结果 + 建议
└─────────────────┘

📋 验证清单

1️⃣ 基础验证（举例法）

2️⃣ 异常验证（反证法）

3️⃣ 安全验证（破解法）

4️⃣ 质量验证（对比法）

💻 使用方法

命令行

# 验证指定 Skill（功能 + 安全 + UX）
bash ~/.openclaw/workspace/skills/skill-validator/scripts/validate.sh <skill-name>

# UX 用户体验专项验证
bash ~/.openclaw/workspace/skills/skill-validator/scripts/validate-ux.sh <skill-name>

# 验证最近安装的 Skill
bash ~/.openclaw/workspace/skills/skill-validator/scripts/validate-recent.sh

# 验证所有 Skill
bash ~/.openclaw/workspace/skills/skill-validator/scripts/validate-all.sh

对话触发

用户：验证一下我新安装的 email 技能
AI：让我帮你验证 openclaw-email 技能...
    [执行验证脚本]
    
    ✅ 基础验证通过
      - SKILL.md 存在
      - Python3 可用
    
    ⚠️ 发现问题
      - EMAIL_ADDRESS 未设置
      - EMAIL_PASSWORD 未设置
    
    📋 建议
      1. 设置环境变量: export EMAIL_ADDRESS="your@email.com"
      2. 生成应用密码并设置: export EMAIL_PASSWORD="xxx"

📊 验证报告示例

╔══════════════════════════════════════════════════════════╗
║           🧪 Skill 验证报告: openclaw-email            ║
╚══════════════════════════════════════════════════════════╝

📅 验证时间: 2026-03-19 20:00

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ 基础验证 (4/4 通过)
  ✓ SKILL.md 文件存在
  ✓ scripts/ 目录存在  
  ✓ Python3 可用
  ✓ IMAP 连接正常

⚠️ 配置验证 (2/4 通过)
  ✓ EMAIL_ADDRESS 已设置
  ✓ EMAIL_IMAP_SERVER 已设置
  ✗ EMAIL_PASSWORD 未设置
  ✗ EMAIL_SMTP_SERVER 未设置

❌ 功能验证 (0/2 通过)
  ✗ 发送邮件失败（缺少密码）
  ✗ 接收邮件失败（缺少密码）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 完善建议

1. [必须] 设置邮箱应用密码
   export EMAIL_PASSWORD="your_app_password"

2. [建议] 设置 SMTP 服务器
   export EMAIL_SMTP_SERVER="smtp.gmail.com"

3. [优化] 添加错误重试机制

4. [文档] 补充常见错误码说明

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

总体评分: 60/100
状态: ⚠️ 部分可用（需配置）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔧 验证脚本结构

skill-validator/
├── SKILL.md                    # 本文件
├── scripts/
│   ├── validate.sh             # 主验证脚本
│   ├── validate-recent.sh      # 验证最近安装
│   ├── validate-all.sh         # 验证所有 Skill
│   ├── test-basic.sh           # 基础验证
│   ├── test-edge.sh            # 边界验证
│   └── test-security.sh        # 安全验证
└── templates/
    ├── report.md               # 报告模板
    └── suggestions.md          # 建议模板

🎨 验证策略（按 Skill 类型）

API 类 Skill

• 测试 API 连接
• 验证认证流程
• 检查错误处理
• 测试限流处理

工具类 Skill

• 测试核心命令
• 验证参数解析
• 检查输出格式
• 测试异常情况

内容生成类 Skill

• 测试生成质量
• 验证格式正确
• 检查多样性
• 评估准确性

自动化类 Skill

• 测试触发条件
• 验证执行流程
• 检查状态管理
• 测试并发情况

📝 验证结果状态

🔄 与其他 Skill 配合

📈 评分标准

🎨 用户体验验证（UX Testing）

验证维度

🌍 国际化验证

时区检查

# 检查是否正确处理时区
check_timezone() {
    local skill_path=$1
    
    echo "🌍 时区处理检查..."
    
    # 检查是否使用 TZ 环境变量
    if grep -rq "TZ=" "$skill_path"; then
        echo "✅ 使用 TZ 环境变量"
    fi
    
    # 检查是否使用 UTC
    if grep -rq "UTC\|utc\|ISO 8601" "$skill_path"; then
        echo "✅ 使用 UTC 或 ISO 8601 格式"
    fi
    
    # 检查是否硬编码时区
    if grep -rqE "CST|PST|EST|GMT\+[0-9]" "$skill_path" 2>/dev/null; then
        echo "⚠️ 发现硬编码时区，建议使用用户本地时区"
    fi
    
    # 检查时间格式化
    if grep -rq "date.*format\|strftime\|moment\|dayjs" "$skill_path"; then
        echo "✅ 使用时间格式化库"
    fi
}

多语言检查

# 检查国际化支持
check_i18n() {
    local skill_path=$1
    
    echo "🗣️ 多语言支持检查..."
    
    # 检查是否有语言配置
    if [ -f "$skill_path/locales" ] || [ -d "$skill_path/i18n" ]; then
        echo "✅ 包含语言资源目录"
    fi
    
    # 检查硬编码文本
    local hardcoded=$(grep -rE "(错误|成功|失败|提示|Error|Success|Failed)" "$skill_path"/*.md 2>/dev/null | wc -l)
    if [ $hardcoded -gt 5 ]; then
        echo "⚠️ 发现 $hardcoded 处硬编码文本"
        echo "   建议：使用 i18n 函数或语言文件"
    fi
    
    # 检查字符编码
    if grep -rq "UTF-8\|utf8" "$skill_path"; then
        echo "✅ 声明 UTF-8 编码"
    fi
}

🎯 可视化验证

输出格式检查

# 检查输出可读性
check_visualization() {
    local skill_path=$1
    
    echo "🎨 可视化检查..."
    
    local scripts="$skill_path/scripts"
    local score=0
    
    # 检查颜色输出
    if grep -rq "\\033\[" "$scripts" 2>/dev/null; then
        echo "✅ 使用颜色输出"
        ((score+=20))
    else
        echo "⚠️ 无颜色输出"
    fi
    
    # 检查表格格式
    if grep -rqE "\|.*\||printf.*%|column" "$scripts" 2>/dev/null; then
        echo "✅ 使用表格格式"
        ((score+=20))
    fi
    
    # 检查图标/Emoji
    if grep -rqE "✅|❌|⚠️|🔴|🟢|📋|🔍" "$scripts" 2>/dev/null; then
        echo "✅ 使用图标/Emoji"
        ((score+=20))
    fi
    
    # 检查进度指示
    if grep -rq "spinner\|progress\|loading" "$scripts" 2>/dev/null; then
        echo "✅ 包含进度指示"
        ((score+=20))
    fi
    
    # 检查分隔线
    if grep -rqE "^[-=]{10,}|━|─" "$scripts" 2>/dev/null; then
        echo "✅ 使用分隔线"
        ((score+=20))
    fi
    
    echo ""
    echo "可视化评分: $score/100"
}

💡 最佳实践建议生成

建议规则引擎

# 根据验证结果生成建议
generate_best_practices() {
    local skill_path=$1
    local results=$2
    
    echo "💡 最佳实践建议"
    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
    
    # 时区建议
    echo ""
    echo "【时区处理】"
    if grep -rq "date" "$skill_path" 2>/dev/null; then
        echo "  ✅ 建议：所有时间使用 ISO 8601 格式 (YYYY-MM-DDTHH:mm:ssZ)"
        echo "  ✅ 建议：显示时转换为用户本地时区"
        echo "  ✅ 示例：date -u +%Y-%m-%dT%H:%M:%SZ"
    fi
    
    # 多语言建议
    echo ""
    echo "【国际化】"
    echo "  ✅ 建议：将文本提取到语言文件"
    echo "  ✅ 建议：支持环境变量 LANG 或 LOCALE"
    echo "  ✅ 示例："
    echo "     # en_US.json"
    echo '     { "error": "Configuration not found" }'
    echo "     # zh_CN.json"
    echo '     { "error": "配置未找到" }'
    
    # 用户体验建议
    echo ""
    echo "【用户体验】"
    echo "  ✅ 建议：提供 --help 参数"
    echo "  ✅ 建议：错误信息包含解决方法"
    echo "  ✅ 建议：长时间操作显示进度"
    echo "  ✅ 建议：输出使用颜色区分状态"
    
    # 安全建议
    echo ""
    echo "【安全最佳实践】"
    echo "  ✅ 建议：敏感信息使用环境变量"
    echo "  ✅ 建议：不记录密码/token 到日志"
    echo "  ✅ 建议：输入验证和过滤"
    echo "  ✅ 建议：使用 timeout 限制外部调用"
    
    echo ""
    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
}

📊 UX 验证报告示例

╔══════════════════════════════════════════════════════════╗
║           🎨 UX 验证报告: config-diagnose               ║
╚══════════════════════════════════════════════════════════╝

📅 验证时间: 2026-03-19 20:50

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ 可视化 (80/100)
  ✅ 使用颜色输出
  ✅ 使用表格格式
  ✅ 使用图标/Emoji
  ✅ 使用分隔线
  ⚠️ 无进度指示

🌍 时区处理 (60/100)
  ✅ 使用 UTC 时间
  ⚠️ 发现硬编码时区 "CST"
  建议：改用 TZ 环境变量

🗣️ 多语言 (40/100)
  ⚠️ 发现 15 处硬编码中文
  ✅ 声明 UTF-8 编码
  建议：添加英文支持

🎯 用户引导 (70/100)
  ✅ 有使用帮助
  ✅ 错误信息清晰
  ⚠️ 缺少示例输出

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 UX 综合评分: 62/100

💡 改进建议
1. [高优先] 添加英文语言支持
2. [中优先] 修复时区硬编码问题
3. [低优先] 添加进度指示器

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

👤 作者

小帽 (OpenClaw)

📅 创建时间

2026-03-19

📜 许可证

MIT