@alanwang-merit/meritdata-platform-skill-package 1.0.2 → 1.0.3

package/tools/skill-vetter/README.md

@@ -1,119 +0,0 @@
-# skill-vetter
-
-> 校验 meritdata-platform-suite 中所有 skill 的结构合规性。
-
----
-
-## 用途
-
-- CI 门禁：每次 PR 校验所有 skill 的结构
-- 人工 review 前快速检查
-- skill 新建后确认符合规范
-
-## 校验项
-
-| # | 检查项 | 严重度 |
-|---|--------|--------|
-| 1 | SKILL.md 存在 | 🔴 阻断 |
-| 2 | frontmatter 完整（第 1 行 `---`）| 🔴 阻断 |
-| 3 | 必填字段（name/description/metadata/version/layer/sub-layer/stack）| 🔴 阻断 |
-| 4 | 4 大章节（触发 / 不触发 / 前置约束 / 路由）| 🔴 阻断 |
-| 5 | SKILL.md 行数 ≤ 60 | 🟠 警告 |
-
-## 用法
-
-```bash
-# 校验全部 skill
-bash tools/skill-vetter/run.sh
-
-# 校验单个 skill
-bash tools/skill-vetter/run.sh meritdata-platform-cache
-```
-
-## 退出码
-
-| 退出码 | 含义 |
-|--------|------|
-| 0 | 全部通过 |
-| 1 | 有失败 |
-
-## 输出示例
-
-```
-========================================
-  skill-vetter: skill 合规校验
-========================================
-扫描目录: /path/to/skills
-
-✅ [meritdata-platform-cache] 通过
-✅ [meritdata-platform-nacos-config] 通过
-❌ [my-bad-skill] SKILL.md 缺少字段: sub-layer
-✅ [meritdata-platform-session] 通过
-
-========================================
-  结果: 28 通过 / 1 失败
-========================================
-```
-
-## 集成 CI
-
-### GitLab CI
-
-```yaml
-skill-vet:
-  stage: check
-  script:
-    - bash tools/skill-vetter/run.sh
-  rules:
-    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
-```
-
-### GitHub Actions
-
-```yaml
-name: Skill Vetter
-on: [pull_request]
-
-jobs:
-  vet:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - run: bash tools/skill-vetter/run.sh
-```
-
-## 校验失败的修复
-
-### 缺失 frontmatter
-
-```bash
-# 检查 SKILL.md 第一行
-head -1 skills/<skill>/SKILL.md
-# 应为: ---
-```
-
-### 缺失字段
-
-在 SKILL.md frontmatter 中补全：
-
-```yaml
----
-name: meritdata-platform-xxx
-description: 描述
-metadata:
-  version: "1.0.0"
-  risk: low|medium|high
-  layer: L1 | L2 | L3 | L4
-  sub-layer: L2-M | L2-C | L2-F | L3-C | L3-F | L4-T
-  stack: methodology | java | frontend | tool
----
-```
-
-### SKILL.md 行数过长
-
-把详细说明移到 `references/` 子文件，SKILL.md 只保留路由条目。
-
-## 关联阅读
-
-- [../skill-authoring-workflow/README.md](../skill-authoring-workflow/README.md) — skill 编写规范
-- [../skill-stocktake/README.md](../skill-stocktake/README.md) — skill 清单盘点

package/tools/skill-vetter/run.sh

@@ -1,294 +0,0 @@
-#!/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