chore: track claude skills, tools, templates, reference code and research-wiki

- Add all claude skills (brainstorming, commit, debugging, TDD, etc.) - Add claude hooks (pre-commit-guard, post-edit-quality) - Add research templates (experiment plan, research brief, etc.) - Add claude tools (arxiv/semantic_scholar/openalex fetch, wiki, exa) - Add TRM4 reference implementation as algorithm fidelity baseline - Add research-wiki content (plans, index, graph, query_pack) - Update .gitignore to exclude .graphify_version runtime state
2026-07-06 20:59:03 -04:00
parent 0616d16956
commit 6bdb802f01
98 changed files with 19321 additions and 0 deletions
@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# ============================================================
+# post-edit-quality.sh
+# Claude Code PostToolUse hook — 每次编辑 .py 文件后自动检查
+#
+# 触发时机：Claude 每次执行 Write/Edit 后
+# 作用：对被修改的文件执行复杂度和风格检查
+# 退出码：0 = 通过，非0 = 报告问题（非阻塞，Claude 会看到反馈）
+#
+# 配置方法：在 .claude/settings.local.json 中注册：
+# "hooks": {
+#   "PostToolUse": [
+#     { "matcher": "Write|Edit", "command": "bash scripts/hooks/post-edit-quality.sh" }
+#   ]
+# }
+# ============================================================
+set -euo pipefail
+
+# <填写: 项目 Conda 环境路径>
+# PROJ_ENV="/home/<user>/miniconda3/envs/<env-name>/bin"
+# [[ -d "$PROJ_ENV" ]] && export PATH="$PROJ_ENV:$PATH"
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""')
+
+# 只检查 .py 文件
+if [[ ! "$FILE_PATH" == *.py ]]; then
+    exit 0
+fi
+
+# 只检查存在的文件
+if [[ ! -f "$FILE_PATH" ]]; then
+    exit 0
+fi
+
+ERRORS=""
+WARNINGS=""
+
+# ── 1. Ruff 格式 + lint 检查 ──
+if command -v ruff &> /dev/null; then
+    RUFF_OUTPUT=$(ruff check "$FILE_PATH" 2>&1 || true)
+    if [[ -n "$RUFF_OUTPUT" ]]; then
+        ERRORS+="[ruff] 风格/lint 问题：\n$RUFF_OUTPUT\n\n"
+    fi
+fi
+
+# ── 2. Radon 圈复杂度（只报告 C 级及以下） ──
+if command -v radon &> /dev/null; then
+    RADON_OUTPUT=$(radon cc "$FILE_PATH" -n C -s 2>&1 || true)
+    if echo "$RADON_OUTPUT" | grep -qE '^\s+[FMC]\s'; then
+        ERRORS+="[radon] 圈复杂度过高（≥C）：\n$RADON_OUTPUT\n\n"
+    fi
+fi
+
+# ── 3. 文件行数检查（warning，不阻塞）──
+LINE_COUNT=$(wc -l < "$FILE_PATH")
+if [[ "$LINE_COUNT" -gt 200 ]]; then
+    WARNINGS+="[行数] $FILE_PATH 有 ${LINE_COUNT} 行，超过 200 行建议上限。\n\n"
+fi
+
+# ── 4. 禁止裸 except ──
+if grep -nE '^\s*except\s*:\s*$|^\s*except\s+Exception\s*:\s*pass' "$FILE_PATH" 2>/dev/null; then
+    ERRORS+="[安全] 检测到裸 except 或 except Exception: pass，请捕获具体异常类型。\n\n"
+fi
+
+# ── 5. 禁止硬编码敏感信息 ──
+if grep -nEi "(api_key|secret|password|token)\s*=\s*[\"'][^\"']+[\"']" "$FILE_PATH" 2>/dev/null; then
+    ERRORS+="[安全] 疑似硬编码敏感信息，请使用环境变量或 .env 文件。\n\n"
+fi
+
+# ── 输出结果 ──
+if [[ -n "$WARNINGS" ]]; then
+    echo -e "⚠️  Warnings（$FILE_PATH，不阻塞）：\n" >&2
+    echo -e "$WARNINGS" >&2
+fi
+
+if [[ -n "$ERRORS" ]]; then
+    echo -e "❌ 代码质量检查发现问题（$FILE_PATH）：\n" >&2
+    echo -e "$ERRORS" >&2
+    exit 1
+fi
+
+exit 0
@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# ============================================================
+# pre-commit-guard.sh
+# Claude Code PreToolUse hook — 拦截 git commit，执行全量检查
+#
+# 触发时机：Claude 尝试执行 git commit 之前
+# 作用：阻塞提交直到所有质量门禁通过
+# 退出码：0 = 放行，2 = 阻塞（Claude 必须先修复问题）
+#
+# 配置方法：在 .claude/settings.local.json 中注册：
+# "hooks": {
+#   "PreToolUse": [
+#     { "matcher": "Bash", "command": "bash scripts/hooks/pre-commit-guard.sh" }
+#   ]
+# }
+# ============================================================
+set -euo pipefail
+
+# <填写: 项目 Conda 环境路径>
+# PROJ_ENV="/home/<user>/miniconda3/envs/<env-name>/bin"
+# [[ -d "$PROJ_ENV" ]] && export PATH="$PROJ_ENV:$PATH"
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
+
+# 只拦截 git commit 命令
+if ! echo "$COMMAND" | grep -qE '^\s*git\s+commit'; then
+    exit 0
+fi
+
+ERRORS=""
+WARNINGS=""
+
+# <填写: 核心代码目录，如 core/>
+CODE_DIR="core"
+
+# ── 1. 项目结构检查（按需取消注释） ──
+# 检查根目录是否有不该存在的 .py
+# for pyfile in *.py; do
+#     [[ "$pyfile" == "*.py" ]] && break
+#     if [[ "$pyfile" != "main.py" && "$pyfile" != "conftest.py" ]]; then
+#         ERRORS+="[结构] 根目录不该有: $pyfile（应移至 $CODE_DIR/）\n"
+#     fi
+# done
+
+# ── 2. 全量代码质量检查 ──
+if [[ -d "$CODE_DIR" ]] && command -v ruff &> /dev/null; then
+    RUFF_OUTPUT=$(ruff check "$CODE_DIR" 2>&1 || true)
+    if [[ -n "$RUFF_OUTPUT" ]]; then
+        ERROR_COUNT=$(echo "$RUFF_OUTPUT" | wc -l)
+        ERRORS+="[ruff] $CODE_DIR/ 中有 ${ERROR_COUNT} 个问题。运行 ruff check $CODE_DIR/ 查看详情。\n"
+    fi
+fi
+
+if [[ -d "$CODE_DIR" ]] && command -v radon &> /dev/null; then
+    RADON_OUTPUT=$(radon cc "$CODE_DIR" -n C -s 2>&1 || true)
+    if echo "$RADON_OUTPUT" | grep -qE '^\s+[FMC]\s'; then
+        ERRORS+="[radon] 存在圈复杂度 ≥ C 的函数：\n$RADON_OUTPUT\n"
+    fi
+fi
+
+# ── 3. 文件行数检查 ──
+if [[ -d "$CODE_DIR" ]]; then
+    while IFS= read -r pyfile; do
+        lines=$(wc -l < "$pyfile")
+        if [[ "$lines" -gt 200 ]]; then
+            WARNINGS+="[行数] $pyfile 有 ${lines} 行，超过 200 行建议上限。\n"
+        fi
+    done < <(find "$CODE_DIR" -name "*.py" 2>/dev/null || true)
+fi
+
+# ── 4. 测试检查 ──
+if command -v pytest &> /dev/null && [[ -d "tests" ]]; then
+    TEST_OUTPUT=$(pytest tests/ --tb=line -q 2>&1 || true)
+    if echo "$TEST_OUTPUT" | grep -qE 'failed|error'; then
+        FAILED=$(echo "$TEST_OUTPUT" | tail -1)
+        ERRORS+="[测试] 有测试未通过：$FAILED\n"
+    fi
+fi
+
+# ── 判定结果 ──
+if [[ -n "$WARNINGS" ]]; then
+    echo -e "⚠️  Warnings（不阻塞）：\n" >&2
+    echo -e "$WARNINGS" >&2
+fi
+
+if [[ -n "$ERRORS" ]]; then
+    echo -e "❌ 提交被阻塞 — 请先修复以下问题：\n" >&2
+    echo -e "$ERRORS" >&2
+    echo -e "修复完成后重新执行 git commit。" >&2
+    exit 2
+fi
+
+echo "✅ 所有检查通过，允许提交。"
+exit 0