mirror of
https://github.com/jnMetaCode/superpowers-zh.git
synced 2026-09-02 22:54:06 +08:00
chore(ci): 加 audit 脚本 + workflow 自动检测上游漂移 (#31)
防回归基建：把本轮全量质量审计的 4 类检查打包成可重复运行的脚本， 每次 PR 自动跑，发现漂移立刻拦下。 scripts/audit.sh： 1. 静态校验：JSON parse、SKILL.md frontmatter、symlink、hook 可执行性 2. Installer 功能：17 款工具装 / 重装（幂等）/ 卸载全跑一遍 3. 上游对齐：hooks 4 文件 + brainstorm scripts 3 文件 + 14 翻译 skill 结构层级（H1-H4 标题数）+ code-reviewer.md self-contained 版结构 4. 交叉引用：README → docs/ 链接、skill 间 superpowers:xxx 引用、 装完后 .claude/skills/using-superpowers/SKILL.md 路径解析 支持 --quick（跳过 installer）和 --no-upstream（跳过对齐）两个开关。 .github/workflows/audit.yml： - 触发：PR + push to main + 手动 dispatch - 步骤：checkout（fetch-depth 0）+ setup node 20 + 加 upstream remote + fetch upstream main 浅克隆 + 跑 audit.sh - FAIL > 0 → 整个 workflow 失败，PR 被卡 设计原则： - 这次"4 个 P0 缺陷漂"事件（hooks-cursor + brainstorm + code-reviewer 引用 + code-reviewer.md 整合）如果当时有这个 audit 在 CI 跑，PR 阶段就会被拦下 - 用 H 数对齐而不是行数 diff 来判断结构漂移（避免翻译造成的假阳性） - WARN（不阻塞）vs FAIL（阻塞）分级：主动扩写算 WARN， 结构性落后上游算 FAIL 本地烟测： - main 分支跑：92 PASS / 2 WARN / 8 FAIL（捕获到所有已知漂移） - chore/sync-upstream-p0-drift（PR #30）跑：97 PASS / 2 WARN / 0 FAIL（PR 修复后全绿） 后续：PR #28 + #30 merge 后，main 上 FAIL 应归零（WARN 只剩 executing-plans 主动扩写一项）。
This commit is contained in:
AI不止语
29
.github/workflows/audit.yml
vendored
Normal file
29
.github/workflows/audit.yml
vendored
Normal file
@@ -0,0 +1,29 @@
|
||||
name: Audit
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
audit:
|
||||
name: 上游对齐 + 交叉引用 + Installer 功能 全量审计
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20'
|
||||
|
||||
- name: Add upstream remote
|
||||
run: |
|
||||
git remote add upstream https://github.com/obra/superpowers.git
|
||||
git fetch upstream main --depth=50
|
||||
|
||||
- name: Run audit
|
||||
run: bash scripts/audit.sh
|
||||
254
scripts/audit.sh
Executable file
254
scripts/audit.sh
Executable file
@@ -0,0 +1,254 @@
|
||||
#!/usr/bin/env bash
|
||||
# 质量审计脚本 —— 跑 4 类检查防漂移
|
||||
#
|
||||
# 1. 静态校验：JSON parse / SKILL.md frontmatter / symlink / hook 可执行性
|
||||
# 2. Installer 功能：17 款工具装 / 卸载 / 幂等
|
||||
# 3. 上游对齐：hooks 3 文件 + brainstorm scripts 3 文件 + 14 翻译 skill 结构层级
|
||||
# 4. 交叉引用：README → docs/ 链接 + skill 间引用 + bootstrap 注入路径
|
||||
#
|
||||
# 用法：
|
||||
# bash scripts/audit.sh # 跑全部，FAIL > 0 时 exit 1
|
||||
# bash scripts/audit.sh --quick # 跳过 installer 功能测试
|
||||
# bash scripts/audit.sh --no-upstream # 跳过上游对齐（CI 没 upstream remote 时）
|
||||
#
|
||||
# CI 默认在 PR + push to main 跑，发现漂移立刻拦下。
|
||||
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
cd "$ROOT"
|
||||
|
||||
QUICK=0
|
||||
NO_UPSTREAM=0
|
||||
for arg in "$@"; do
|
||||
case "$arg" in
|
||||
--quick) QUICK=1 ;;
|
||||
--no-upstream) NO_UPSTREAM=1 ;;
|
||||
esac
|
||||
done
|
||||
|
||||
PASS=0; FAIL=0; WARN=0
|
||||
declare -a FAILURES=()
|
||||
declare -a WARNINGS=()
|
||||
INSTALLER="$ROOT/bin/superpowers-zh.js"
|
||||
|
||||
ok() { PASS=$((PASS+1)); }
|
||||
bad() { FAIL=$((FAIL+1)); FAILURES+=("$1"); echo " ❌ $1"; }
|
||||
warn() { WARN=$((WARN+1)); WARNINGS+=("$1"); echo " ⚠️ $1"; }
|
||||
hdr() { echo ""; echo "=== $1 ==="; }
|
||||
|
||||
# 确保有 upstream remote（CI 上需要 fetch）
|
||||
ensure_upstream() {
|
||||
if [ "$NO_UPSTREAM" = "1" ]; then return 1; fi
|
||||
if ! git ls-remote --exit-code upstream HEAD >/dev/null 2>&1; then
|
||||
if git remote get-url upstream >/dev/null 2>&1; then
|
||||
git fetch upstream main --depth=50 --quiet 2>/dev/null || return 1
|
||||
else
|
||||
git remote add upstream https://github.com/obra/superpowers.git 2>/dev/null
|
||||
git fetch upstream main --depth=50 --quiet 2>/dev/null || return 1
|
||||
fi
|
||||
fi
|
||||
return 0
|
||||
}
|
||||
|
||||
#==============================================================================
|
||||
hdr "Category 1: 静态校验"
|
||||
#==============================================================================
|
||||
|
||||
# 1a. JSON parse
|
||||
while IFS= read -r f; do
|
||||
if node -e "JSON.parse(require('fs').readFileSync('$f','utf8'))" 2>/dev/null; then
|
||||
ok
|
||||
else
|
||||
bad "JSON parse failure: $f"
|
||||
fi
|
||||
done < <(find . -name "*.json" \
|
||||
-not -path "./node_modules/*" \
|
||||
-not -path "./.git/*" \
|
||||
-not -path "./tests/*/node_modules/*")
|
||||
|
||||
# 1b. SKILL.md frontmatter 完整性
|
||||
for f in skills/*/SKILL.md; do
|
||||
if ! head -1 "$f" | grep -q '^---$'; then
|
||||
bad "No frontmatter: $f"
|
||||
continue
|
||||
fi
|
||||
fm=$(sed -n '/^---$/,/^---$/p' "$f" | head -20)
|
||||
for field in name description; do
|
||||
if ! echo "$fm" | grep -q "^${field}:"; then
|
||||
bad "Missing frontmatter field '$field': $f"
|
||||
fi
|
||||
done
|
||||
ok
|
||||
done
|
||||
|
||||
# 1c. Symlink 解析
|
||||
while IFS= read -r l; do
|
||||
if [ -e "$l" ]; then ok; else bad "Broken symlink: $l"; fi
|
||||
done < <(find . -type l -not -path "./node_modules/*" -not -path "./.git/*")
|
||||
|
||||
# 1d. Hook 脚本可执行权限
|
||||
for f in hooks/session-start hooks/run-hook.cmd; do
|
||||
if [ -x "$f" ]; then ok; else bad "Not executable: $f"; fi
|
||||
done
|
||||
|
||||
#==============================================================================
|
||||
if [ "$QUICK" != "1" ]; then
|
||||
hdr "Category 2: Installer 功能测试（17 款工具）"
|
||||
#==============================================================================
|
||||
|
||||
declare -a TOOLS=(claude cursor codex kiro deerflow trae antigravity vscode openclaw windsurf gemini aider opencode qwen hermes claw copilot)
|
||||
|
||||
for tool in "${TOOLS[@]}"; do
|
||||
TMP=$(mktemp -d)
|
||||
pushd "$TMP" >/dev/null
|
||||
|
||||
if ! node "$INSTALLER" --tool "$tool" >/dev/null 2>&1; then
|
||||
bad "Installer: $tool 安装失败"
|
||||
popd >/dev/null
|
||||
rm -rf "$TMP"
|
||||
continue
|
||||
fi
|
||||
|
||||
# 幂等：再装一遍不应炸
|
||||
if ! node "$INSTALLER" --tool "$tool" >/dev/null 2>&1; then
|
||||
bad "Installer: $tool 二次安装失败（幂等性破坏）"
|
||||
popd >/dev/null
|
||||
rm -rf "$TMP"
|
||||
continue
|
||||
fi
|
||||
|
||||
if ! node "$INSTALLER" --uninstall >/dev/null 2>&1; then
|
||||
bad "Installer: $tool 卸载失败"
|
||||
else
|
||||
ok
|
||||
fi
|
||||
|
||||
popd >/dev/null
|
||||
rm -rf "$TMP"
|
||||
done
|
||||
|
||||
else
|
||||
echo ""
|
||||
echo "[--quick 跳过 installer 功能测试]"
|
||||
fi
|
||||
|
||||
#==============================================================================
|
||||
hdr "Category 3: 上游对齐"
|
||||
#==============================================================================
|
||||
|
||||
if ! ensure_upstream; then
|
||||
warn "无法访问 upstream，跳过对齐检查（CI 上请确保有网络）"
|
||||
else
|
||||
# 3a. Hooks 3 文件 + cursor manifest
|
||||
for f in hooks/session-start hooks/hooks.json hooks/run-hook.cmd hooks/hooks-cursor.json; do
|
||||
d=$(diff <(git show upstream/main:$f 2>/dev/null) "$f" 2>/dev/null | wc -l | tr -d ' ')
|
||||
if [ "$d" = "0" ]; then ok; else bad "Hooks 漂移: $f ($d 行)"; fi
|
||||
done
|
||||
|
||||
# 3b. Brainstorm scripts 3 文件
|
||||
for f in skills/brainstorming/scripts/server.cjs \
|
||||
skills/brainstorming/scripts/start-server.sh \
|
||||
skills/brainstorming/scripts/stop-server.sh; do
|
||||
d=$(diff <(git show upstream/main:$f 2>/dev/null) "$f" 2>/dev/null | wc -l | tr -d ' ')
|
||||
if [ "$d" = "0" ]; then ok; else bad "Brainstorm script 漂移: $(basename $f) ($d 行)"; fi
|
||||
done
|
||||
|
||||
# 3c. 14 翻译 skill 结构层级（H1-H4 标题数）
|
||||
declare -a SKILLS=(brainstorming dispatching-parallel-agents executing-plans \
|
||||
finishing-a-development-branch receiving-code-review requesting-code-review \
|
||||
subagent-driven-development systematic-debugging test-driven-development \
|
||||
using-git-worktrees using-superpowers verification-before-completion \
|
||||
writing-plans writing-skills)
|
||||
|
||||
for s in "${SKILLS[@]}"; do
|
||||
up=$(git show upstream/main:skills/$s/SKILL.md 2>/dev/null | grep -cE '^#{1,4} ' || echo 0)
|
||||
our=$(grep -cE '^#{1,4} ' "skills/$s/SKILL.md" 2>/dev/null || echo 0)
|
||||
diff=$((up - our))
|
||||
abs=${diff#-}
|
||||
# 允许 3 个 header 差异（翻译造成的合并/拆分小幅波动）
|
||||
if [ "$abs" -le "3" ]; then
|
||||
ok
|
||||
else
|
||||
warn "Skill 结构漂移: ${s} (上游 H=${up}, 我们 H=${our}) -- 可能 v5.1.0 没跟，或主动扩写"
|
||||
fi
|
||||
done
|
||||
|
||||
# 3d. requesting-code-review/code-reviewer.md 结构（v5.1.0 self-contained）
|
||||
up=$(git show upstream/main:skills/requesting-code-review/code-reviewer.md 2>/dev/null | grep -cE '^#{1,3} ' || echo 0)
|
||||
our=$(grep -cE '^#{1,3} ' skills/requesting-code-review/code-reviewer.md)
|
||||
diff=$((up - our))
|
||||
abs=${diff#-}
|
||||
if [ "$abs" -le "2" ]; then
|
||||
ok
|
||||
else
|
||||
bad "code-reviewer.md 结构漂移 (上游 v5.1.0 self-contained, H=${up}; 我们 H=${our})"
|
||||
fi
|
||||
fi
|
||||
|
||||
#==============================================================================
|
||||
hdr "Category 4: 交叉引用完整性"
|
||||
#==============================================================================
|
||||
|
||||
# 4a. README → docs/ 链接
|
||||
BROKEN=0
|
||||
while IFS= read -r link; do
|
||||
link=${link#(}; link=${link%)}
|
||||
if [ -f "$link" ]; then ok; else
|
||||
bad "README 链接断: $link"
|
||||
BROKEN=$((BROKEN+1))
|
||||
fi
|
||||
done < <(grep -oE '\(docs/README\.[a-z-]+\.md\)' README.md)
|
||||
|
||||
# 4b. Skill 间引用（superpowers:xxx）
|
||||
while IFS= read -r line; do
|
||||
skill_file=$(echo "$line" | cut -d: -f1)
|
||||
refs=$(echo "$line" | grep -oE '\bsuperpowers:[a-z-]+\b' | sort -u)
|
||||
for ref in $refs; do
|
||||
name=${ref#superpowers:}
|
||||
if [ -d "skills/$name" ]; then ok; else
|
||||
src=$(basename $(dirname "$skill_file"))
|
||||
bad "Skill 引用断: $src 引用了不存在的 skills/$name"
|
||||
fi
|
||||
done
|
||||
done < <(grep -rln 'superpowers:' skills/*/SKILL.md 2>/dev/null | \
|
||||
xargs -I{} grep -H 'superpowers:' {} 2>/dev/null)
|
||||
|
||||
# 4c. 装完后 .claude/skills/using-superpowers/SKILL.md 路径必须存在（hook 依赖）
|
||||
TMP=$(mktemp -d)
|
||||
pushd "$TMP" >/dev/null
|
||||
if node "$INSTALLER" --tool claude >/dev/null 2>&1; then
|
||||
if [ -f "$TMP/.claude/skills/using-superpowers/SKILL.md" ]; then
|
||||
ok
|
||||
else
|
||||
bad "装完后 .claude/skills/using-superpowers/SKILL.md 不存在（hook 会找不到）"
|
||||
fi
|
||||
fi
|
||||
popd >/dev/null
|
||||
rm -rf "$TMP"
|
||||
|
||||
#==============================================================================
|
||||
echo ""
|
||||
echo "=========================================="
|
||||
echo "📊 审计结果"
|
||||
echo "=========================================="
|
||||
echo "✅ PASS: $PASS"
|
||||
echo "⚠️ WARN: $WARN"
|
||||
echo "❌ FAIL: $FAIL"
|
||||
|
||||
if [ "$WARN" -gt 0 ]; then
|
||||
echo ""
|
||||
echo "Warnings（不阻塞）："
|
||||
for w in "${WARNINGS[@]}"; do echo " ⚠️ $w"; done
|
||||
fi
|
||||
|
||||
if [ "$FAIL" -gt 0 ]; then
|
||||
echo ""
|
||||
echo "Failures（必须修）："
|
||||
for f in "${FAILURES[@]}"; do echo " ❌ $f"; done
|
||||
echo ""
|
||||
echo "❌ Audit 失败：$FAIL 个 P0 问题。看 README 「质量审计」段了解每项含义。"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "✅ Audit 通过"
|
||||
exit 0
|
||||
Reference in New Issue
Block a user