@alanwang-merit/meritdata-platform-skill-package 1.0.0

package/tools/skill-vetter/run.sh

@@ -0,0 +1,294 @@
+#!/bin/bash
+# skill-vetter: 校验 meritdata-platform-suite 中所有 skill 的结构合规性（v2.6.1）
+#
+# 用法:
+#   bash tools/skill-vetter/run.sh              # 校验全部 skill
+#   bash tools/skill-vetter/run.sh <skill-name> # 校验单个 skill
+#   bash tools/skill-vetter/run.sh --json       # 校验全部 + 输出 JSON 报告
+#
+# 退出码:
+#   0 - 全部通过（无 errors）
+#   1 - 有 errors
+#   2 - 仅 warnings
+#
+# v2.6.1 增强项（运维优化）:
+#   1. 死链扫描（references 内 [text](path) 链接是否解析）
+#   2. 敏感信息扫描（password/appSecret/keytab/appToken/apiKey/accessToken/privateKey）
+#   3. TODO/FIXME 残留扫描
+#   4. 重复 skill name 扫描
+#   5. JSON 报告输出（--json）
+#   6. Summary 表格（行数 TOP-10 + 统计汇总）
+
+SUITE_DIR="${SUITE_DIR:-$(cd "$(dirname "$0")/../.." && pwd)}"
+SKILLS_DIR="$SUITE_DIR/skills"
+TARGET=""
+JSON_OUTPUT=0
+for arg in "$@"; do
+    if [ "$arg" = "--json" ]; then
+        JSON_OUTPUT=1
+    else
+        TARGET="$arg"
+    fi
+done
+
+EXIT_CODE=0
+PASS_COUNT=0
+FAIL_COUNT=0
+WARN_COUNT=0
+TOTAL_SKILLS=0
+JSON_RESULTS=()
+TMP_LOG=/tmp/vetterlog.$$
+
+echo "========================================"
+echo "  skill-vetter v2.6.1: skill 合规校验"
+echo "========================================"
+echo "扫描目录: $SKILLS_DIR"
+echo ""
+
+# 死链检测：传入 md 文件路径 + 链接路径，echo DEADLINK if not exists
+check_link() {
+    local src_md="$1"
+    local link="$2"
+    # 跳过 http/https/mailto/$ 锚点
+    case "$link" in
+        http*|https*|mailto:*|\$*) return 1 ;;
+        \#*) return 1 ;;
+    esac
+    # 去掉 anchor
+    local clean="${link%%#*}"
+    [ -z "$clean" ] && return 1
+    # 处理 ./ 开头
+    clean="${clean#./}"
+    local src_dir
+    src_dir=$(dirname "$src_md")
+    local resolved=""
+    # 绝对路径（以 / 开头）相对于 suite 根目录
+    case "$clean" in
+        /*) resolved="$SUITE_DIR$clean" ;;
+        *)  resolved="$src_dir/$clean" ;;
+    esac
+    # 如果包含 ../ 跳出 src_dir，允许跨 skill 引用（向上 3 层即达 suite 根）
+    if [[ "$resolved" == *"/../"* ]] || [[ "$resolved" == *"../../.."* ]]; then
+        # 跳过跨多层的复杂相对路径（已迁出范围）
+        return 1
+    fi
+    [ ! -e "$resolved" ] && echo "DEADLINK:$src_md:$link"
+    return 0
+}
+
+check_skill() {
+    local skill_dir="$1"
+    local skill_name
+    skill_name=$(basename "$skill_dir")
+    local skill_md="$skill_dir/SKILL.md"
+    local errors=0
+    local warnings=0
+    local errs_json=""
+    local warns_json=""
+
+    add_err() { echo "  ERR [$skill_name] $1"; errs_json="${errs_json}\"$1\","; errors=$((errors + 1)); }
+    add_warn() { echo "  WARN [$skill_name] $1"; warns_json="${warns_json}\"$1\","; warnings=$((warnings + 1)); }
+
+    # 1. SKILL.md 存在
+    if [ ! -f "$skill_md" ]; then
+        echo "FAIL [$skill_name] SKILL.md 缺失"
+        FAIL_COUNT=$((FAIL_COUNT + 1))
+        return
+    fi
+
+    # 2. frontmatter
+    head -1 "$skill_md" | grep -q '^---$' || add_err "missing frontmatter"
+
+    # 3. 必填字段（允许 0+ 前导空格）
+    for f in name description metadata version layer; do
+        grep -qE "^[[:space:]]*$f:" "$skill_md" || add_err "missing field: $f:"
+    done
+    local cur_layer
+    cur_layer=$(grep -E "^[[:space:]]*layer:" "$skill_md" | head -1 | grep -oE 'L[0-9]+' | head -1)
+    if [ "$cur_layer" != "L1" ]; then
+        for f in sub-layer stack; do
+            grep -qE "^[[:space:]]*$f:" "$skill_md" || add_err "missing field: $f:"
+        done
+    fi
+
+    # 4. 4 大章节
+    for s in "## 触发" "## 不触发" "## 前置约束" "## 路由"; do
+        grep -q "^$s" "$skill_md" || add_err "missing section: $s"
+    done
+
+    # 5. 行数
+    local lines
+    lines=$(wc -l < "$skill_md")
+    [ "$lines" -gt 60 ] && add_warn "SKILL.md $lines lines >60"
+
+    # 6. 死链扫描（排除 .bak / dev-docs 归档目录）
+    rm -f "$TMP_LOG"
+    while IFS= read -r md_file; do
+        [ -z "$md_file" ] && continue
+        while IFS= read -r link; do
+            [ -z "$link" ] && continue
+            check_link "$md_file" "$link" >> "$TMP_LOG" 2>/dev/null || true
+        done < <(grep -oE '\[[^]]+\]\([^)]+\)' "$md_file" 2>/dev/null \
+                  | grep -oE '\([^)]+\)$' \
+                  | sed -e 's/^(//' -e 's/)$//')
+    done < <(find "$skill_dir" -name "*.md" -type f -not -path "*/.bak/*" -not -path "*/.bak" -not -path "*/references/dev-docs/*" 2>/dev/null)
+    if [ -f "$TMP_LOG" ] && [ -s "$TMP_LOG" ]; then
+        while IFS= read -r line; do
+            echo "  ERR [$skill_name] $line"
+            errs_json="${errs_json}\"$line\","
+            errors=$((errors + 1))
+        done < "$TMP_LOG"
+    fi
+    rm -f "$TMP_LOG"
+
+    # 7. 敏感信息扫描（降级为 WARN：教学文档必然提及敏感关键词，仅作提示）
+    # 排除: description 字段 / 安全规则文档 / `${...}` 环境变量 / ✅❌ 教学标记 /
+    #       注释行（# 开头）/ 占位符（null/~/<...>/xxx/your-...）/ docker -e / .bak 归档 / dev-docs 归档
+    rm -f "$TMP_LOG"
+    while IFS= read -r md_file; do
+        [ -z "$md_file" ] && continue
+        grep -niE "(password|appSecret|appToken|keytab|api[_-]?key|access[_-]?token|private[_-]?key)" "$md_file" 2>/dev/null \
+            | grep -vE '^[[:space:]]*description:' \
+            | grep -vE '(禁止|脱敏|不要|避免|切勿|切记|严禁)' \
+            | grep -vE '\$\{[A-Za-z_][A-Za-z0-9_]*(:[^}]*)?\}' \
+            | grep -vE '(✅|❌|✓|✗)' \
+            | grep -vE '#.*(提交到 git|示例|演示|反例|样例|默认值|占位)' \
+            | grep -vE '^[[:digit:]]+:[[:space:]]*-e[[:space:]]+[A-Z_]*(PASSWORD|SECRET|KEY|TOKEN)' \
+            | grep -vE '^[[:digit:]]+:#' \
+            | grep -vE '=(null|~|xxx|XXX|your-|placeholder|<[^>]+>|xxx\.\.\.)\s*$' \
+            | grep -vE '=[^=]*\.\.\.\s*$' \
+            >> "$TMP_LOG" 2>/dev/null || true
+    done < <(find "$skill_dir" -name "*.md" -type f -not -path "*/.bak/*" -not -path "*/.bak" -not -path "*/references/dev-docs/*" 2>/dev/null)
+    if [ -f "$TMP_LOG" ] && [ -s "$TMP_LOG" ]; then
+        SENS_COUNT=$(wc -l < "$TMP_LOG")
+        echo "  WARN [$skill_name] sensitive-keyword $SENS_COUNT hits（教学文档，建议人工 review）"
+        warns_json="${warns_json}\"sensitive:$SENS_COUNT hits\","
+        warnings=$((warnings + 1))
+    fi
+    rm -f "$TMP_LOG"
+
+    # 8. TODO/FIXME 残留扫描（排除 .bak）
+    rm -f "$TMP_LOG"
+    while IFS= read -r md_file; do
+        [ -z "$md_file" ] && continue
+        grep -nE "(TODO|FIXME|XXX|HACK|TBD)" "$md_file" 2>/dev/null >> "$TMP_LOG" || true
+    done < <(find "$skill_dir" -name "*.md" -type f -not -path "*/.bak/*" -not -path "*/.bak" 2>/dev/null)
+    if [ -f "$TMP_LOG" ] && [ -s "$TMP_LOG" ]; then
+        while IFS= read -r line; do
+            add_warn "TODO: $line"
+        done < "$TMP_LOG"
+    fi
+    rm -f "$TMP_LOG"
+
+    # 输出汇总
+    if [ "$errors" -gt 0 ]; then
+        echo "FAIL [$skill_name] ($errors errors / $warnings warnings)"
+        FAIL_COUNT=$((FAIL_COUNT + 1))
+        [ "$EXIT_CODE" = "0" ] && EXIT_CODE=1
+    elif [ "$warnings" -gt 0 ]; then
+        echo "WARN [$skill_name] ($warnings warnings)"
+        PASS_COUNT=$((PASS_COUNT + 1))
+        WARN_COUNT=$((WARN_COUNT + 1))
+        [ "$EXIT_CODE" = "0" ] && EXIT_CODE=2
+    else
+        echo "OK [$skill_name]"
+        PASS_COUNT=$((PASS_COUNT + 1))
+    fi
+    TOTAL_SKILLS=$((TOTAL_SKILLS + 1))
+
+    # JSON 记录
+    errs_json=$(echo "$errs_json" | sed 's/,$//')
+    warns_json=$(echo "$warns_json" | sed 's/,$//')
+    JSON_RESULTS+=("{\"skill\":\"$skill_name\",\"lines\":$lines,\"errors\":$errors,\"warnings\":$warnings,\"errs\":[$errs_json],\"warns\":[$warns_json]}")
+}
+
+# 主流程
+if [ -n "$TARGET" ]; then
+    if [ ! -d "$SKILLS_DIR/$TARGET" ]; then
+        echo "FAIL skill 不存在: $TARGET"
+        exit 1
+    fi
+    check_skill "$SKILLS_DIR/$TARGET"
+else
+    for skill_dir in "$SKILLS_DIR"/*/; do
+        [ -d "$skill_dir" ] || continue
+        check_skill "$skill_dir"
+    done
+fi
+
+# 9. 重复 skill name
+echo ""
+echo "========================================"
+echo "  重复 skill name 检查"
+echo "========================================"
+dup_count=0
+dup_names=$(grep -hE '^[[:space:]]*name:' "$SKILLS_DIR"/*/SKILL.md 2>/dev/null \
+    | sed -E 's/.*name:[[:space:]]*"?([^"]+)"?.*//' \
+    | sort | uniq -d)
+if [ -n "$dup_names" ]; then
+    echo "$dup_names" | while read dup; do
+        [ -z "$dup" ] && continue
+        echo "FAIL 重复 name: $dup"
+        dup_count=$((dup_count + 1))
+    done
+    FAIL_COUNT=$((FAIL_COUNT + 1))
+    [ "$EXIT_CODE" = "0" ] && EXIT_CODE=1
+else
+    echo "OK 0 个重复 name"
+fi
+
+echo ""
+echo "========================================"
+echo "  结果: $PASS_COUNT 通过 / $FAIL_COUNT 失败 (总计 $TOTAL_SKILLS)"
+echo "========================================"
+
+# 行数 TOP-10
+echo ""
+echo "========================================"
+echo "  SKILL.md 行数 TOP-10（最长）"
+echo "========================================"
+printf "%-45s %8s\n" "Skill" "Lines"
+printf "%-45s %8s\n" "-----------------------------------------------" "--------"
+for skill_dir in "$SKILLS_DIR"/*/; do
+    [ -d "$skill_dir" ] || continue
+    sn=$(basename "$skill_dir")
+    if [ -f "$skill_dir/SKILL.md" ]; then
+        printf "%-45s %8d\n" "$sn" "$(wc -l < "$skill_dir/SKILL.md")"
+    fi
+done | sort -k2 -n -r | head -10
+
+echo ""
+echo "========================================"
+echo "  统计汇总"
+echo "========================================"
+echo "skill 总数：   $TOTAL_SKILLS"
+echo "通过：        $PASS_COUNT"
+echo "失败：        $FAIL_COUNT"
+echo "仅警告：      $WARN_COUNT"
+
+# JSON 报告
+if [ "$JSON_OUTPUT" = "1" ]; then
+    REPORT="$SUITE_DIR/vetter-report.json"
+    {
+        echo "{"
+        echo "  \"version\": \"2.6.1\","
+        echo "  \"timestamp\": \"$(date -Iseconds 2>/dev/null || date)\","
+        echo "  \"suite_dir\": \"$SUITE_DIR\","
+        echo "  \"total\": $TOTAL_SKILLS,"
+        echo "  \"passed\": $PASS_COUNT,"
+        echo "  \"failed\": $FAIL_COUNT,"
+        echo "  \"warning_only\": $WARN_COUNT,"
+        echo "  \"results\": ["
+        csep=""
+        for r in "${JSON_RESULTS[@]}"; do
+            echo "    $csep$r"
+            csep=","
+        done
+        echo "  ]"
+        echo "}"
+    } > "$REPORT"
+    echo ""
+    echo "JSON 报告: $REPORT"
+fi
+
+exit $EXIT_CODE