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

package/tools/skill-authoring-workflow/templates/references-template.md

@@ -0,0 +1,59 @@
+# <标题>
+
+> <一句话说明本文件主题>。
+
+---
+
+## 1. <章节 1>
+
+<内容>
+
+### 1.1 <子章节>
+
+```java
+// 代码示例
+```
+
+### 1.2 <子章节>
+
+<内容>
+
+## 2. <章节 2>
+
+<内容>
+
+```java
+// 代码示例
+```
+
+## 3. <章节 3>
+
+### 3.1 <子章节>
+
+<内容>
+
+---
+
+## ❌ 反模式
+
+### ❌ <反模式 1>
+
+```java
+// ❌ 错
+```
+
+```java
+// ✅ 正确
+```
+
+### ❌ <反模式 2>
+
+<说明>
+
+---
+
+## 关联阅读
+
+- [guide.md](guide.md) — <一句话>
+- [SKILL.md](../SKILL.md)
+- [相关 rules](../../rules/<file>.md)

package/tools/skill-stocktake/README.md

@@ -0,0 +1,121 @@
+# skill-stocktake
+
+> 生成 meritdata-platform-suite 中所有 skill 的清单报告。
+
+---
+
+## 用途
+
+- 套件盘点：了解当前 skill 全貌
+- 月度同步：统计 skill 数量 / 规模变化
+- 阶段验收：交付前的清单核查
+- 报告输出：JSON / Markdown 格式
+
+## 报告内容
+
+- 总数 + references 总行数
+- Layer / Sub-Layer / Stack 分布
+- 每个 skill 的：name / layer / sub-layer / stack / version / risk / SKILL.md 行数 / references 数量 / references 行数
+
+## 用法
+
+```bash
+# 控制台输出
+bash tools/skill-stocktake/run.sh
+
+# JSON 格式
+bash tools/skill-stocktake/run.sh json stocktake.json
+
+# Markdown 格式
+bash tools/skill-stocktake/run.sh markdown stocktake.md
+```
+
+## 输出示例（console）
+
+```
+========================================
+  skill-stocktake: skill 清单盘点
+========================================
+生成时间: 2026-09-07 18:30:00
+总数: 35 个 skill
+References 总行数: 12450
+
+Layer 分布:
+  L1      1
+  L2      13
+  L3      15
+  L4      3
+  L5      3
+
+Sub-Layer 分布:
+  L2-C    6
+  L2-F    1
+  L2-M    6
+  L3-C    13
+  L3-F    2
+  L4-T    3
+
+Skill 列表:
+  Name                                         Layer Sub     Stack        Ver
+  ---------------------------------------------------------------------------------
+  meritdata-platform-backend-deploy            L3    L3-C    java         1.0.0
+  meritdata-platform-bpm                       L2    L2-C    java         1.0.0
+  meritdata-platform-cache                     L3    L3-C    java         1.0.0
+  ...
+```
+
+## 输出示例（JSON）
+
+```json
+{
+  "scanTime": "2026-09-07 18:30:00",
+  "totalSkills": 35,
+  "totalRefLines": 12450,
+  "layers": {
+    "L1": 1,
+    "L2": 13,
+    "L3": 15,
+    "L4": 3
+  },
+  "subLayers": {
+    "L2-M": 6,
+    "L2-C": 6,
+    "L2-F": 1,
+    "L3-C": 13,
+    "L3-F": 2,
+    "L4-T": 3
+  },
+  "skills": [
+    {
+      "name": "meritdata-platform-cache",
+      "layer": "L3",
+      "subLayer": "L3-C",
+      "stack": "java",
+      "version": "1.0.0",
+      "risk": "medium",
+      "skillLines": 38,
+      "refCount": 3,
+      "refLines": 720,
+      "description": "多级缓存（Caffeine + Redis + DB）"
+    }
+  ]
+}
+```
+
+## 集成 CI
+
+```yaml
+# GitLab CI
+stocktake:
+  stage: report
+  script:
+    - bash tools/skill-stocktake/run.sh markdown stocktake.md
+  artifacts:
+    paths:
+      - stocktake.md
+```
+
+## 关联阅读
+
+- [../skill-vetter/README.md](../skill-vetter/README.md) — 校验工具
+- [../skill-authoring-workflow/README.md](../skill-authoring-workflow/README.md) — 编写规范

package/tools/skill-stocktake/run.sh

@@ -0,0 +1,153 @@
+#!/bin/bash
+# skill-stocktake: 生成 meritdata-platform-suite 中所有 skill 的清单报告
+#
+# 用法: bash tools/skill-stocktake/run.sh [output-format] [output-file]
+#   output-format: console | json | markdown (默认 console)
+#   output-file: 输出文件路径（默认 stdout）
+
+set -e
+
+SUITE_DIR="${SUITE_DIR:-$(cd "$(dirname "$0")/../.." && pwd)}"
+SKILLS_DIR="$SUITE_DIR/skills"
+FORMAT="${1:-console}"
+OUTPUT="${2:-}"
+
+NOW=$(date '+%Y-%m-%d %H:%M:%S')
+
+# 收集数据
+skills_data=()
+while IFS= read -r skill_dir; do
+    skill_name=$(basename "$skill_dir")
+    skill_md="$skill_dir/SKILL.md"
+
+    if [ ! -f "$skill_md" ]; then
+        continue
+    fi
+
+    layer=$(grep -E '^[[:space:]]+layer:' "$skill_md" | head -1 | sed 's/.*layer:[[:space:]]*//')
+    sub_layer=$(grep -E '^[[:space:]]+sub-layer:' "$skill_md" | head -1 | sed 's/.*sub-layer:[[:space:]]*//')
+    [ -z "$sub_layer" ] && sub_layer="(无)"
+    stack=$(grep -E '^[[:space:]]+stack:' "$skill_md" | head -1 | sed 's/.*stack:[[:space:]]*//')
+    [ -z "$stack" ] && stack="(无)"
+    version=$(grep -E '^[[:space:]]+version:' "$skill_md" | head -1 | sed "s/.*version:[[:space:]]*[\"']//;s/[\"']//")
+    risk=$(grep -E '^[[:space:]]+risk:' "$skill_md" | head -1 | sed 's/.*risk:[[:space:]]*//')
+    desc=$(grep -E '^description:' "$skill_md" | head -1 | sed 's/description:\s*//')
+    skill_lines=$(wc -l < "$skill_md")
+    ref_count=$(find "$skill_dir/references" -type f -name '*.md' 2>/dev/null | wc -l)
+    ref_lines=$(find "$skill_dir/references" -type f -name '*.md' 2>/dev/null -exec wc -l {} + 2>/dev/null | tail -1 | awk '{print $1}')
+    ref_lines=${ref_lines:-0}
+
+    skills_data+=("$skill_name|$layer|$sub_layer|$stack|$version|$risk|$skill_lines|$ref_count|$ref_lines|$desc")
+done < <(find "$SKILLS_DIR" -mindepth 1 -maxdepth 1 -type d | sort)
+
+total_count=${#skills_data[@]}
+total_ref_lines=0
+for line in "${skills_data[@]}"; do
+    total_ref_lines=$((total_ref_lines + $(echo "$line" | cut -d'|' -f9)))
+done
+
+# 按 layer / sub-layer 统计
+declare -A layer_count
+declare -A sub_layer_count
+declare -A stack_count
+for line in "${skills_data[@]}"; do
+    IFS='|' read -r _ l sl s _ _ _ _ _ _ <<< "$line"
+    layer_count[$l]=$((${layer_count[$l]:-0} + 1))
+    [ -n "$sl" ] && sub_layer_count[$sl]=$((${sub_layer_count[$sl]:-0} + 1))
+    [ -n "$s" ] && stack_count[$s]=$((${stack_count[$s]:-0} + 1))
+done
+
+# 输出
+output_text=""
+case "$FORMAT" in
+    json)
+        output_text+="{\n"
+        output_text+="  \"scanTime\": \"$NOW\",\n"
+        output_text+="  \"totalSkills\": $total_count,\n"
+        output_text+="  \"totalRefLines\": $total_ref_lines,\n"
+        output_text+="  \"layers\": {\n"
+        first=true
+        for key in "${!layer_count[@]}"; do
+            if [ "$first" = true ]; then first=false; else output_text+=",\n"; fi
+            output_text+="    \"$key\": ${layer_count[$key]}"
+        done
+        output_text+="\n  },\n"
+        output_text+="  \"subLayers\": {\n"
+        first=true
+        for key in "${!sub_layer_count[@]}"; do
+            if [ "$first" = true ]; then first=false; else output_text+=",\n"; fi
+            output_text+="    \"$key\": ${sub_layer_count[$key]}"
+        done
+        output_text+="\n  },\n"
+        output_text+="  \"skills\": [\n"
+        first=true
+        for line in "${skills_data[@]}"; do
+            IFS='|' read -r name l sl s v r sl_l rc rl d <<< "$line"
+            if [ "$first" = true ]; then first=false; else output_text+=",\n"; fi
+            d_escaped=$(echo "$d" | sed 's/"/\\"/g')
+            output_text+="    {\"name\":\"$name\",\"layer\":\"$l\",\"subLayer\":\"$sl\",\"stack\":\"$s\",\"version\":\"$v\",\"risk\":\"$r\",\"skillLines\":$sl_l,\"refCount\":$rc,\"refLines\":$rl,\"description\":\"$d_escaped\"}"
+        done
+        output_text+="\n  ]\n"
+        output_text+="}\n"
+        ;;
+
+    markdown)
+        output_text+="# Skill 清单盘点\n\n"
+        output_text+="**生成时间**：$NOW\n\n"
+        output_text+="**总数**：$total_count 个 skill\n\n"
+        output_text+="**总 references 行数**：$total_ref_lines\n\n"
+        output_text+="## Layer 分布\n\n"
+        output_text+="| Layer | 数量 |\n|-------|------|\n"
+        for key in $(echo "${!layer_count[@]}" | tr ' ' '\n' | sort); do
+            output_text+="| $key | ${layer_count[$key]} |\n"
+        done
+        output_text+="\n## Sub-Layer 分布\n\n"
+        output_text+="| Sub-Layer | 数量 |\n|-----------|------|\n"
+        for key in $(echo "${!sub_layer_count[@]}" | tr ' ' '\n' | sort); do
+            output_text+="| $key | ${sub_layer_count[$key]} |\n"
+        done
+        output_text+="\n## Skill 列表\n\n"
+        output_text+="| Name | Layer | Sub-Layer | Stack | Ver | Risk | SKILL 行 | Refs | Ref 行 |\n"
+        output_text+="|------|-------|-----------|-------|-----|------|----------|------|--------|\n"
+        for line in "${skills_data[@]}"; do
+            IFS='|' read -r name l sl s v r sl_l rc rl _ <<< "$line"
+            output_text+="| $name | $l | $sl | $s | $v | $r | $sl_l | $rc | $rl |\n"
+        done
+        ;;
+
+    *)
+        # console
+        echo "========================================"
+        echo "  skill-stocktake: skill 清单盘点"
+        echo "========================================"
+        echo "生成时间: $NOW"
+        echo "总数: $total_count 个 skill"
+        echo "References 总行数: $total_ref_lines"
+        echo ""
+        echo "Layer 分布:"
+        for key in $(echo "${!layer_count[@]}" | tr ' ' '\n' | sort); do
+            printf "  %-8s %d\n" "$key" "${layer_count[$key]}"
+        done
+        echo ""
+        echo "Sub-Layer 分布:"
+        for key in $(echo "${!sub_layer_count[@]}" | tr ' ' '\n' | sort); do
+            printf "  %-8s %d\n" "$key" "${sub_layer_count[$key]}"
+        done
+        echo ""
+        echo "Skill 列表:"
+        printf "  %-45s %-5s %-7s %-12s %s\n" "Name" "Layer" "Sub" "Stack" "Ver"
+        echo "  ---------------------------------------------------------------------------------"
+        for line in "${skills_data[@]}"; do
+            IFS='|' read -r name l sl s v _ _ _ _ _ <<< "$line"
+            printf "  %-45s %-5s %-7s %-12s %s\n" "$name" "$l" "$sl" "$s" "$v"
+        done
+        echo ""
+        ;;
+esac
+
+if [ -n "$OUTPUT" ]; then
+    echo -e "$output_text" > "$OUTPUT"
+    echo "已写入: $OUTPUT"
+else
+    echo -e "$output_text"
+fi

package/tools/skill-vetter/README.md

@@ -0,0 +1,119 @@
+# 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 清单盘点