chore(wiki): wiki-init 補骨架 + system-dev-template 安裝/更新腳本

wiki 已初始化過（push 檔活躍維護），本次補從沒建的 pull 層 + arcrun 化範本： - cards/decisions/ 14 張決策原子卡（含 gloss/實體/typed-edge 三元組）：從 decisions-summary 全量改寫 13 + 新增「薄殼規則晚於實作-MCP漂移是歷史債」1 - TAXONOMY 從 PKM 範本換成 arcrun 軸（子系統零件架構/cypher/credential/recipe/kbdb/ 薄殼/部署/平台原則 + 形態架構決策/踩坑/機制說明/禁令/案例經驗） - principles 填 13 條跨全局原則（從 rules/ + mindset 蒸餾） - INDEX 真實視圖（子系統角度 + 決策角度，指向 cards） - system-dev/scripts/ + scripts/ install/update 安裝腳本（template 接入）純基建/文檔，無業務 code（功能 code 見前一 commit）。 raw source（docs/）0 異動、wiki 卡際連結無斷鏈。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-27 17:53:37 +08:00
parent 934b9265d9
commit 558e80b4da
28 changed files with 3147 additions and 0 deletions
@@ -0,0 +1,234 @@
+#!/bin/bash
+# system-dev-template updater
+# 已安裝舊版的人，一鍵更新到新版。
+#
+# 核心安全原則：只覆蓋「模板/邏輯檔」，絕不碰「使用者資料檔」。
+#   ✅ 可覆蓋：hooks/*.sh、commands/*.md、TEMPLATE-*、wiki/INDEX.md
+#              ——這些由模板維護，使用者不會手改，新版直接換掉。
+#   🔒 絕不碰：wiki/status.md、mistakes.md、decisions-summary.md、TAXONOMY.md、.wikiignore、
+#              settings.json、CLAUDE.md
+#              ——這些是使用者自己填的內容，覆蓋＝清空他的記憶與設定。
+#
+# 「第一次更新」的雞生蛋問題：
+#   舊版本機沒有 update.sh。所以第一次靠 README 那行 curl 從遠端抓這支腳本來跑。
+#   跑完它會把自己也更新進 scripts/update.sh，之後就能直接跑本機的 `bash scripts/update.sh`。
+
+set -euo pipefail
+
+# ── i18n：依 locale 選語言，預設英文（curl | bash 常為 LANG=C）──
+case "${LC_ALL:-${LC_MESSAGES:-${LANG:-}}}" in
+  zh*|*Hant*|*Hans*) IS_ZH="yes" ;;
+  *)                 IS_ZH="no" ;;
+esac
+t()  { if [ "$IS_ZH" = "yes" ]; then printf '%s\n' "$1"; else printf '%s\n' "$2"; fi; }
+tn() { if [ "$IS_ZH" = "yes" ]; then printf '%s' "$1";  else printf '%s' "$2";  fi; }
+
+REPO_RAW="https://raw.githubusercontent.com/uncle6me-web/system-dev-template/main"
+TEMPLATE_URL="$REPO_RAW/template"
+
+UPDATED=()
+KEPT=()
+NEW=()
+TEMPLATED=()
+
+# ── 版本比對：先看本機 vs 遠端，給使用者「值不值得更新」的判斷 ──
+LOCAL_VER="$(tn '(未知)' '(unknown)')"
+[ -f ".claude/VERSION" ] && LOCAL_VER="$(tr -d '[:space:]' < .claude/VERSION)"
+REMOTE_VER="$(curl -sSL "$TEMPLATE_URL/.claude/VERSION" 2>/dev/null | tr -d '[:space:]' || echo '')"
+
+echo ""
+echo "🔄 system-dev-template updater"
+echo "================================="
+t "   本機版本：${LOCAL_VER}" "   Local version:  ${LOCAL_VER}"
+t "   最新版本：${REMOTE_VER:-取不到（檢查網路）}" \
+  "   Latest version: ${REMOTE_VER:-unavailable (check network)}"
+echo ""
+
+if [ -z "$REMOTE_VER" ]; then
+  t "❌ 取不到遠端版本，可能是網路問題。請稍後再試。" \
+    "❌ Could not fetch the remote version (likely a network issue). Please try again later."
+  exit 1
+fi
+
+if [ "$LOCAL_VER" = "$REMOTE_VER" ]; then
+  t "✅ 已是最新版（${LOCAL_VER}），不需更新。" \
+    "✅ Already up to date (${LOCAL_VER}), nothing to update."
+  t "   （仍會同步模板邏輯檔，確保 hooks/commands 與最新一致。）" \
+    "   (Template logic files will still be synced to keep hooks/commands in line with the latest.)"
+  echo ""
+fi
+
+# ── 工具函式 ───────────────────────────────────────
+# 覆蓋更新：模板/邏輯檔，無條件抓最新版蓋掉。
+update_file() {
+  local dest="$1" src="$2"
+  mkdir -p "$(dirname "$dest")"
+  if [ -f "$dest" ]; then
+    if curl -sSL "$src" -o "$dest.tmp" 2>/dev/null && [ -s "$dest.tmp" ]; then
+      if cmp -s "$dest" "$dest.tmp"; then
+        rm -f "$dest.tmp"          # 內容相同，不算更新
+      else
+        mv "$dest.tmp" "$dest"
+        UPDATED+=("$dest")
+      fi
+    else
+      rm -f "$dest.tmp"
+      t "   ⚠️  抓取失敗，保留原檔：$dest" "   ⚠️  Download failed, keeping the original: $dest"
+    fi
+  else
+    if curl -sSL "$src" -o "$dest" 2>/dev/null && [ -s "$dest" ]; then
+      NEW+=("$dest")               # 新功能：舊版沒有的檔
+    else
+      rm -f "$dest"
+      t "   ⚠️  抓取失敗：$dest" "   ⚠️  Download failed: $dest"
+    fi
+  fi
+}
+
+# 保留：使用者資料檔，只記錄「有保留」，永遠不動。
+keep_file() {
+  [ -f "$1" ] && KEPT+=("$1") || true
+}
+
+# 客製檔：使用者一定會手填內容（如 pre-write-guard.sh）。
+#   - 已存在 → 絕不覆蓋，但把最新模板版抓到 <檔名>.template.sh 旁邊，供使用者自行 diff 採納。
+#   - 不存在 → 視同新檔，直接抓本體（第一次安裝才會走這條）。
+keep_with_template() {
+  local dest="$1" src="$2"
+  if [ -f "$dest" ]; then
+    KEPT+=("$dest")
+    local tmpl="${dest%.sh}.template.sh"
+    if curl -sSL "$src" -o "$tmpl.tmp" 2>/dev/null && [ -s "$tmpl.tmp" ]; then
+      if [ -f "$tmpl" ] && cmp -s "$tmpl" "$tmpl.tmp"; then
+        rm -f "$tmpl.tmp"            # 模板版沒變，不重複提示
+      else
+        mv "$tmpl.tmp" "$tmpl"
+        TEMPLATED+=("$tmpl")
+      fi
+    else
+      rm -f "$tmpl.tmp"
+    fi
+  else
+    update_file "$dest" "$src"        # 還沒裝過 → 當新檔處理
+  fi
+}
+
+# ── 偵測已安裝哪些模組（依現有檔案判斷，更新只動已裝的）──
+HAS_WIKI=false
+HAS_SDD=false
+[ -d ".claude/wiki" ] && HAS_WIKI=true
+if [ -f ".claude/hooks/sdd-guard.sh" ] || [ -d "docs/3-specs/TEMPLATE-sdd" ]; then HAS_SDD=true; fi
+
+t "📦 偵測到已安裝模組：" "📦 Detected installed modules:"
+$HAS_WIKI && echo "   • LLM Wiki"
+$HAS_SDD  && echo "   • SDD"
+{ $HAS_WIKI || $HAS_SDD; } || \
+  t "   （未偵測到任何模組——這裡可能還沒安裝，請改跑 install.sh）" \
+    "   (No modules detected — nothing installed here yet; run install.sh instead.)"
+echo ""
+
+# ── 客製檔：使用者手填的 guardrail，永不覆蓋（issue #3）──
+# pre-write-guard.sh 的定位是「空白客製模板，使用者沒配置前不提供保護」（CHANGELOG 1.2.0）。
+# 下游通常已塞滿自己的 enforcement，直接覆蓋＝無聲關掉整套 guardrail。
+# 改為：保留原檔不動，新版範本另存 pre-write-guard.template.sh，由使用者自行 diff 採納。
+keep_with_template ".claude/hooks/pre-write-guard.sh" "$TEMPLATE_URL/.claude/hooks/pre-write-guard.sh"
+
+# ── 模板/邏輯檔：覆蓋更新 ──────────────────────────
+# 共用 hook 與指引
+update_file ".claude/commands/issue-handle.md" "$TEMPLATE_URL/.claude/commands/issue-handle.md"
+update_file ".claude/VERSION"                  "$TEMPLATE_URL/.claude/VERSION"
+
+if $HAS_WIKI; then
+  # wiki 的「邏輯檔」：導航與 hooks，可覆蓋
+  update_file ".claude/wiki/INDEX.md"                    "$TEMPLATE_URL/.claude/wiki/INDEX.md"
+  update_file ".claude/hooks/session-start-recall.sh"   "$TEMPLATE_URL/.claude/hooks/session-start-recall.sh"
+  update_file ".claude/hooks/wiki-secret-scan.sh"       "$TEMPLATE_URL/.claude/hooks/wiki-secret-scan.sh"
+  update_file ".claude/commands/wiki-init.md"           "$TEMPLATE_URL/.claude/commands/wiki-init.md"
+  update_file ".claude/commands/wiki-capture.md"        "$TEMPLATE_URL/.claude/commands/wiki-capture.md"
+  update_file ".claude/commands/wiki-update.md"         "$TEMPLATE_URL/.claude/commands/wiki-update.md"
+  update_file ".claude/commands/wiki-recall.md"         "$TEMPLATE_URL/.claude/commands/wiki-recall.md"
+  # Cowork（claude.ai）的 wiki 整理 skill：規則檔，可覆蓋
+  update_file "docs/SKILL.md"                           "$TEMPLATE_URL/docs/SKILL.md"
+
+  # wiki 的「使用者資料」：絕不碰
+  keep_file ".claude/wiki/status.md"
+  keep_file ".claude/wiki/mistakes.md"
+  keep_file ".claude/wiki/decisions-summary.md"
+  keep_file ".claude/wiki/TAXONOMY.md"
+  keep_file ".claude/wiki/.wikiignore"
+fi
+
+if $HAS_SDD; then
+  # SDD 範本與 hook：可覆蓋
+  update_file "docs/3-specs/TEMPLATE-sdd/design.md"               "$TEMPLATE_URL/docs/3-specs/TEMPLATE-sdd/design.md"
+  update_file "docs/3-specs/TEMPLATE-sdd/tasks.md"                "$TEMPLATE_URL/docs/3-specs/TEMPLATE-sdd/tasks.md"
+  update_file "docs/2-architecture/decisions/TEMPLATE-adr.md"     "$TEMPLATE_URL/docs/2-architecture/decisions/TEMPLATE-adr.md"
+  update_file ".claude/commands/sdd-check.md"                     "$TEMPLATE_URL/.claude/commands/sdd-check.md"
+  update_file ".claude/hooks/sdd-guard.sh"                        "$TEMPLATE_URL/.claude/hooks/sdd-guard.sh"
+fi
+
+# ── 自我更新：把最新的 update.sh 也抓下來（含 install.sh）──
+# 這兩支在 main/scripts/ 下，不在 template/。
+update_file "scripts/update.sh"  "$REPO_RAW/scripts/update.sh"
+update_file "scripts/install.sh" "$REPO_RAW/scripts/install.sh"
+
+chmod +x .claude/hooks/*.sh scripts/*.sh 2>/dev/null || true
+
+# ── 使用者資料檔：絕不碰，但提醒「設定可能有新欄位要手動補」──
+keep_file ".claude/settings.json"
+keep_file "CLAUDE.md"
+
+# ── 結果輸出 ───────────────────────────────────────
+echo ""
+echo "─────────────────────────────────"
+if [ ${#NEW[@]} -gt 0 ]; then
+  echo ""
+  t "🆕 新功能（舊版沒有，已加入）：" "🆕 New features (absent in the old version, now added):"
+  for f in "${NEW[@]}"; do echo "   + $f"; done
+fi
+if [ ${#UPDATED[@]} -gt 0 ]; then
+  echo ""
+  t "⬆️  已更新（覆蓋成新版）：" "⬆️  Updated (overwritten with the new version):"
+  for f in "${UPDATED[@]}"; do echo "   ~ $f"; done
+fi
+if [ ${#NEW[@]} -eq 0 ] && [ ${#UPDATED[@]} -eq 0 ]; then
+  echo ""
+  t "✨ 模板邏輯檔已全部最新，無需變動。" \
+    "✨ All template logic files are already up to date — no changes needed."
+fi
+if [ ${#KEPT[@]} -gt 0 ]; then
+  echo ""
+  t "🔒 完整保留（你的內容/設定，從未碰過）：" \
+    "🔒 Fully preserved (your content/settings, never touched):"
+  for f in "${KEPT[@]}"; do echo "   = $f"; done
+fi
+if [ ${#TEMPLATED[@]} -gt 0 ]; then
+  echo ""
+  t "📋 客製檔有新版範本（你的原檔沒動，新版另存旁邊，請自行 diff 採納）：" \
+    "📋 Custom files have a new template version (your original is untouched; the new one is saved alongside — diff and adopt as you like):"
+  for f in "${TEMPLATED[@]}"; do
+    echo "   → $f"
+    t "      比對：diff \"${f%.template.sh}.sh\" \"$f\"" \
+      "      compare: diff \"${f%.template.sh}.sh\" \"$f\""
+  done
+fi
+
+# ── settings.json 提醒：新模組 hook 可能要手動補 ──
+if [ -f ".claude/settings.json" ]; then
+  MISSING=()
+  $HAS_WIKI && ! grep -q "session-start-recall.sh" .claude/settings.json && MISSING+=("SessionStart: session-start-recall.sh")
+  $HAS_WIKI && ! grep -q "wiki-secret-scan.sh"     .claude/settings.json && MISSING+=("PreToolUse(Write|Edit): wiki-secret-scan.sh")
+  $HAS_SDD  && ! grep -q "sdd-guard.sh"            .claude/settings.json && MISSING+=("PreToolUse(Write|Edit): sdd-guard.sh")
+  if [ ${#MISSING[@]} -gt 0 ]; then
+    echo ""
+    t "📌 settings.json 是你的設定（沒動），但偵測到缺以下 hook，請手動補上：" \
+      "📌 settings.json is yours (untouched), but these hooks are missing — please add them manually:"
+    for h in "${MISSING[@]}"; do echo "   • $h"; done
+  fi
+fi
+
+echo ""
+t "🚀 更新完成：${LOCAL_VER} → ${REMOTE_VER}" "🚀 Update complete: ${LOCAL_VER} → ${REMOTE_VER}"
+t "   下次更新直接跑：bash scripts/update.sh" "   Next time, just run: bash scripts/update.sh"
+t "   改了什麼看：CHANGELOG.md" "   See what changed: CHANGELOG.md"
+echo ""