fix(site): 官网工具墙停在 20 款 —— Cline / Kilo Code / Crush 的用户在下拉里找不到自己的工具

起因是核对首页：统计块写着「20 支持工具」，同一屏下面的标题写着「一套 skill， 23 款工具通用」，FAQ 里又老老实实枚举了 23 款。三处自己打自己。根因：文案计数早就跟着 installer 改到了 23，但 `site/build.mjs` 的 `TOOLS` 数组从来没人补 —— audit 只校验文案里的数字，不校验列表本身。 ## 1. 工具列表补 3 款 + 修 4 处错的 `TOOLS` 20 条 -> 23 条（= TARGETS 22 条 + Copilot CLI 单独计数）。统计块的 `20` 是硬编码的，改成 `TOOLS.length`。漏的三款（installer 一直支持，官网从没有过）：Cline、Kilo Code、Crush。已有条目里查出的错（逐条实测过命令）： | 条目 | 原来 | 现在 | 依据 | |---|---|---|---| | Claw Code | `--tool claw` | 直接 `npx superpowers-zh` | detect 是 `.claw` / `CLAW.md`，实测能自动检出 | | Hermes Agent | `--tool hermes` | `--global --tool hermes` | 官方只自动加载 `~/.hermes/skills/`，项目级要手写 config.yaml，给项目级命令等于给「装了不生效」 | | Qwen Code | 类型 IDE | CLI | 它是 QwenLM/qwen-code 命令行工具，不是通义灵码 | | Antigravity | 类型 CLI | IDE | Google 的 AI IDE，docs/README.antigravity.md 里本来就这么写 | `auto: true/false` 两态不够用了（Hermes 是「能检出但项目级不生效」），换成 `mode: auto / manual / global`，三语各补一条对应说明文案。 ## 2. FAQ 的「支持全局」清单少了 4 款写着 7 款，installer 实际 11 款 —— CodeArts / Crush / Hermes / CodeBuddy 陆续拿到 `--global` 之后这句话没跟。三语同步补齐。两版 README 的同一句也少了 CodeArts（v1.7.11 补 --global 时漏改），一并修。 ## 3. skill 详情页有 6 条死链 `SKILL.md` 里指向兄弟文件的相对链接（`implementer-prompt.md`、 `../requesting-code-review/code-reviewer.md` 等）站点上根本没有这些 .md： `../` 开头的直接 404，不带 `./` 的被 md.mjs 的 scheme 白名单打成 `href="#"` —— 点了没反应，比 404 还难查。 `renderMarkdown(src, base)` 加基址参数，相对链接解析到 GitHub 源文件。 5 个目标地址逐个 curl 过，都是 200。全站扫描：死链 0、`href="#"` 0。 ## 4. 加两条门禁，堵住这次的漏法 audit 原来只数文案里的数字，这次两个问题它一个都发现不了。补： - 官网 `TOOLS` 条目数必须 = TARGETS + 1 - 官网 FAQ 全局清单必须包含 installer 里每个带 `global:` 的工具反向验证过：删掉 Crush、去掉 CodeArts，两条各自报错。 audit 170 pass / 0 fail（新增 2 条）；verify-release 114 pass / 1 fail，唯一那条是 windsurf.com 返回 429 限流，改动前的干净树上同样失败，与本次无关。
2026-09-03 07:23:56 +08:00 · 2026-08-28 21:48:01 +08:00
parent c68725b4f6
commit 1f66b091b7
7 changed files with 86 additions and 35 deletions
--- a/README.md
+++ b/README.md
@@ -143,7 +143,7 @@ AI：在开始实现之前，我需要了解几个关键问题：
 | [OpenCode](https://opencode.ai) | CLI | `npx superpowers-zh` | `.opencode/skills/` |
 | [OpenClaw](https://github.com/openclaw/openclaw) | CLI | `npx superpowers-zh` | `skills/` |
 | [Qwen Code](https://github.com/QwenLM/qwen-code) | CLI | `npx superpowers-zh` | `.qwen/skills/` + `QWEN.md` |
-| [Antigravity](https://antigravity.google) | CLI | `npx superpowers-zh` | `.agents/skills/` |
+| [Antigravity](https://antigravity.google) | IDE | `npx superpowers-zh` | `.agents/skills/` |
 | [Claw Code](https://github.com/ultraworkers/claw-code) | CLI (Rust) | `npx superpowers-zh` | `.claw/skills/` |
 | [Qoder](https://qoder.com) (阿里 AI IDE) | IDE | `npx superpowers-zh` | `.qoder/skills/` + `.qoder/rules/` |
 | [CodeBuddy](https://copilot.tencent.com) (腾讯 AI IDE) | IDE | `npx superpowers-zh` | `.codebuddy/skills/` + `CODEBUDDY.md` |
@@ -211,7 +211,7 @@ npx superpowers-zh --global --tool claude   # 或指定工具

 全局安装把 skills 装到工具的**用户级目录**（如 `~/.claude/skills`），一次安装所有项目自动可用，更新时也只需重装一次。**项目级优先、全局兜底**，二者可共存。

-支持通用全局安装的工具（均为 docs 已证实的用户级加载路径）：**Claude Code · Codex CLI · Qoder · Windsurf · Qwen Code · OpenClaw · OpenCode · Crush · Hermes Agent · CodeBuddy**。其中 **Codex CLI** 全局装到 `~/.agents/skills`（Codex 启动扫描目录）。其余工具（Cursor / Kiro / Trae / Aider / DeerFlow / VS Code / Claw / Cline / Kilo Code / CodeArts）规则是项目级或存于应用内设置，`--global` 会提示改用项目级；**Gemini CLI / Antigravity** 有各自专属的全局方式（Gemini 走扩展目录），见对应 `docs/README.*.md`。
+支持通用全局安装的工具（均为 docs 已证实的用户级加载路径）：**Claude Code · Codex CLI · Qoder · Windsurf · Qwen Code · OpenClaw · OpenCode · Crush · Hermes Agent · CodeBuddy · CodeArts**。其中 **Codex CLI** 全局装到 `~/.agents/skills`（Codex 启动扫描目录）。其余工具（Cursor / Kiro / Trae / Aider / DeerFlow / VS Code / Claw / Cline / Kilo Code）规则是项目级或存于应用内设置，`--global` 会提示改用项目级；**Gemini CLI / Antigravity** 有各自专属的全局方式（Gemini 走扩展目录），见对应 `docs/README.*.md`。

 | | 项目级（默认） | 全局（`--global`） |
 |---|---|---|
--- a/README.zh-Hant.md
+++ b/README.zh-Hant.md
@@ -143,7 +143,7 @@ AI：在開始實作之前，我需要了解幾個關鍵問題：
 | [OpenCode](https://opencode.ai) | CLI | `npx superpowers-zh` | `.opencode/skills/` |
 | [OpenClaw](https://github.com/openclaw/openclaw) | CLI | `npx superpowers-zh` | `skills/` |
 | [Qwen Code](https://github.com/QwenLM/qwen-code) | CLI | `npx superpowers-zh` | `.qwen/skills/` + `QWEN.md` |
-| [Antigravity](https://antigravity.google) | CLI | `npx superpowers-zh` | `.agents/skills/` |
+| [Antigravity](https://antigravity.google) | IDE | `npx superpowers-zh` | `.agents/skills/` |
 | [Claw Code](https://github.com/ultraworkers/claw-code) | CLI (Rust) | `npx superpowers-zh` | `.claw/skills/` |
 | [Qoder](https://qoder.com) (阿里 AI IDE) | IDE | `npx superpowers-zh` | `.qoder/skills/` + `.qoder/rules/` |
 | [CodeBuddy](https://copilot.tencent.com) (騰訊 AI IDE) | IDE | `npx superpowers-zh` | `.codebuddy/skills/` + `CODEBUDDY.md` |
@@ -211,7 +211,7 @@ npx superpowers-zh --global --tool claude   # 或指定工具

 全域安裝把 skills 裝到工具的**使用者級目錄**（如 `~/.claude/skills`），一次安裝所有專案自動可用，更新時也只需重裝一次。**專案級優先、全域兜底**，二者可共存。

-支援通用全域安裝的工具（均為 docs 已證實的使用者級載入路徑）：**Claude Code · Codex CLI · Qoder · Windsurf · Qwen Code · OpenClaw · OpenCode · Crush · Hermes Agent · CodeBuddy**。其中 **Codex CLI** 全域裝到 `~/.agents/skills`（Codex 啟動掃描目錄）。其餘工具（Cursor / Kiro / Trae / Aider / DeerFlow / VS Code / Claw / Cline / Kilo Code / CodeArts）規則是專案級或存於應用內設定，`--global` 會提示改用專案級；**Gemini CLI / Antigravity** 有各自專屬的全域方式（Gemini 走擴充目錄），見對應 `docs/README.*.md`。
+支援通用全域安裝的工具（均為 docs 已證實的使用者級載入路徑）：**Claude Code · Codex CLI · Qoder · Windsurf · Qwen Code · OpenClaw · OpenCode · Crush · Hermes Agent · CodeBuddy · CodeArts**。其中 **Codex CLI** 全域裝到 `~/.agents/skills`（Codex 啟動掃描目錄）。其餘工具（Cursor / Kiro / Trae / Aider / DeerFlow / VS Code / Claw / Cline / Kilo Code）規則是專案級或存於應用內設定，`--global` 會提示改用專案級；**Gemini CLI / Antigravity** 有各自專屬的全域方式（Gemini 走擴充目錄），見對應 `docs/README.*.md`。

 | | 專案級（預設） | 全域（`--global`） |
 |---|---|---|
--- a/scripts/audit.sh
+++ b/scripts/audit.sh
@@ -344,6 +344,30 @@ if [ "$rows" = "$EXPECTED_TOOLS" ]; then ok; else
  bad "README 工具表有 $rows 行，应为 $EXPECTED_TOOLS 行（漏加/多加了表格行）"
 fi

+# ── 结构性检查：官网工具墙 / 安装命令下拉的条目数 ──
+# 计数文案对了不代表列表对了：v1.7.10 时三处文案都写着 23，而 site/build.mjs 的
+# TOOLS 只有 20 条 —— 首页统计块显示「20 支持工具」、下拉里根本找不到
+# Cline / Kilo Code / Crush。这条专门卡列表本身。
+site_tools=$(sed -n '/^const TOOLS = \[/,/^\];/p' site/build.mjs | grep -cE "^  \{ name: '")
+if [ "$site_tools" = "$EXPECTED_TOOLS" ]; then ok; else
+  bad "官网 TOOLS 有 ${site_tools} 条，应为 ${EXPECTED_TOOLS} 条（site/build.mjs 漏加工具）"
+fi
+
+# ── 一致性检查：官网 FAQ 的「支持全局」清单必须与 installer 的 global 目标一致 ──
+# 同理：CodeArts / Crush / Hermes / CodeBuddy 陆续拿到 --global，官网 FAQ 一直停在 7 款。
+global_targets=$(sed -n '/^const TARGETS = \[/,/^\];/p' "$INSTALLER" | grep -E "^  \{ name: '" | grep 'global:' | sed -E "s/^  \{ name: '([^']+)'.*/\1/")
+global_n=$(echo "$global_targets" | grep -c .)
+faq_line=$(grep -n '支持全局的工具' site/build.mjs | head -1 | cut -d: -f2-)
+missing=""
+while IFS= read -r g; do
+  case "$faq_line" in *"$g"*) ;; *) missing="$missing $g";; esac
+done <<< "$global_targets"
+if [ -n "$missing" ]; then
+  bad "官网 FAQ 全局清单漏了：${missing}（installer 共 ${global_n} 款支持 --global）"
+else
+  ok
+fi
+
 # ── 自检：Category 2 测的工具数应等于宣称数（宣称了就必须测） ──
 tools_tested=$(grep -oE '^declare -a TOOLS=\(.*\)' "$0" | sed -E 's/^declare -a TOOLS=\(//; s/\)$//' | wc -w | tr -d ' ')
 if [ "$tools_tested" = "$EXPECTED_TOOLS" ]; then ok; else
--- a/site/README.md
+++ b/site/README.md
@@ -37,7 +37,7 @@ dist/
 | Skill 正文 / 文档内容 | **源头** `skills/<name>/SKILL.md`（改完重新 `node site/build.mjs`） |
 | Skill 中/英标题、英文简介、分组 | `site/build.mjs` 的 `SKILL_META` |
 | 首页所有文案（中/英） | `site/build.mjs` 的 `T.zh` / `T.en` |
-| 支持工具 / 安装命令 | `site/build.mjs` 的 `TOOLS`（与 `bin/superpowers-zh.js` 的 `TARGETS` 对齐） |
+| 支持工具 / 安装命令 | `site/build.mjs` 的 `TOOLS`（与 `bin/superpowers-zh.js` 的 `TARGETS` 对齐；每条的 `mode` = `auto` 自动识别 / `manual` 必须 `--tool` / `global` 只有 `--global` 才生效）。条目数由 `scripts/audit.sh` 卡死 = TARGETS 条目数 + 1（Copilot CLI 单独计数） |
 | 赞助商（logo / banner / 文案 / 链接 / 优惠码） | `site/build.mjs` 的 `SPONSORS`（`logo` 小图标 + `img` 大 banner 都放 `assets/sponsors/`，构建时自动拷进 `dist/assets/sponsors/`）——首页不放赞助内容，全部在 `sponsors.html`。**改完同步改 README.md / README.zh-Hant.md 的赞助商区块** |
 | 赞助商页文案 / 赞助权益 / 赞助 FAQ | `site/build.mjs` 的 `T.<lang>.sp` |
 | 谁上旗舰位 | `SPONSORS` 里该条的 `tier`：`'flagship'` 用大 banner 单独成块（读 `img`），其余是紧凑卡（读 `logo`，简介截 4 行）；没有 flagship 时该区块渲染成「虚位以待」招商卡 |
--- a/site/build.mjs
+++ b/site/build.mjs
@@ -26,6 +26,8 @@ const jsVer = createHash('sha256').update(readFileSync(join(TEMPLATE, 'app.js'))

 // SEO：站点根 URL（用于 canonical / hreflang / og:url / sitemap）
 const SITE_URL = 'https://sp.aiolaola.com';
+// 仓库源码基址（skill 详情页的相对链接解析到这里）
+const GH_BLOB = 'https://github.com/jnMetaCode/superpowers-zh/blob/main';

 const esc = s => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');

@@ -81,27 +83,44 @@ const GROUPS = [
 ];

 // ---- 支持的工具（与 bin/superpowers-zh.js 的 TARGETS 对齐） ----
+// mode 决定安装命令与说明文案：
+//   auto   —— installer 有该工具的检测标记，`npx superpowers-zh` 直接识别
+//   manual —— 无检测标记（或与别的工具共用目录），必须 --tool 指定
+//   global —— 项目级目录不被工具自动加载，只有 --global 装到用户级才生效（Hermes）
+// 条目数必须等于对外宣称的工具数（TARGETS 22 条 + Copilot CLI 单独计数 = 23），
+// scripts/audit.sh 会卡这一点。
 const TOOLS = [
-  { name: 'Claude Code',    type: 'CLI',    cmd: 'npx superpowers-zh',                auto: true },
-  { name: 'Cursor',         type: 'IDE',    cmd: 'npx superpowers-zh',                auto: true },
-  { name: 'Windsurf',       type: 'IDE',    cmd: 'npx superpowers-zh',                auto: true },
-  { name: 'Codex CLI',      type: 'CLI',    cmd: 'npx superpowers-zh',                auto: true },
-  { name: 'Gemini CLI',     type: 'CLI',    cmd: 'npx superpowers-zh',                auto: true },
-  { name: 'Kiro',           type: 'IDE',    cmd: 'npx superpowers-zh',                auto: true },
-  { name: 'Trae',           type: 'IDE',    cmd: 'npx superpowers-zh',                auto: true },
-  { name: 'Qoder',          type: 'IDE',    cmd: 'npx superpowers-zh',                auto: true },
-  { name: 'Aider',          type: 'CLI',    cmd: 'npx superpowers-zh',                auto: true },
-  { name: 'OpenCode',       type: 'CLI',    cmd: 'npx superpowers-zh',                auto: true },
-  { name: 'Qwen Code',      type: 'IDE',    cmd: 'npx superpowers-zh',                auto: true },
-  { name: 'Antigravity',    type: 'CLI',    cmd: 'npx superpowers-zh',                auto: true },
-  { name: 'DeerFlow 2.0',   type: 'Agent',  cmd: 'npx superpowers-zh',                auto: true },
-  { name: 'VS Code · Copilot', type: 'IDE', cmd: 'npx superpowers-zh',                auto: true },
-  { name: 'Copilot CLI',    type: 'CLI',    cmd: 'npx superpowers-zh --tool copilot', auto: false },
-  { name: 'Hermes Agent',   type: 'CLI',    cmd: 'npx superpowers-zh --tool hermes',  auto: false },
-  { name: 'Claw Code',      type: 'CLI',    cmd: 'npx superpowers-zh --tool claw',    auto: false },
-  { name: 'OpenClaw',       type: 'CLI',    cmd: 'npx superpowers-zh',                auto: true },
-  { name: 'CodeBuddy',      type: 'IDE',    cmd: 'npx superpowers-zh',                auto: true },
-  { name: 'CodeArts',       type: 'IDE',    cmd: 'npx superpowers-zh',                auto: true },
+  { name: 'Claude Code',    type: 'CLI',    cmd: 'npx superpowers-zh',                          mode: 'auto' },
+  { name: 'Cursor',         type: 'IDE',    cmd: 'npx superpowers-zh',                          mode: 'auto' },
+  { name: 'Windsurf',       type: 'IDE',    cmd: 'npx superpowers-zh',                          mode: 'auto' },
+  { name: 'Codex CLI',      type: 'CLI',    cmd: 'npx superpowers-zh',                          mode: 'auto' },
+  { name: 'Gemini CLI',     type: 'CLI',    cmd: 'npx superpowers-zh',                          mode: 'auto' },
+  { name: 'Kiro',           type: 'IDE',    cmd: 'npx superpowers-zh',                          mode: 'auto' },
+  { name: 'Trae',           type: 'IDE',    cmd: 'npx superpowers-zh',                          mode: 'auto' },
+  { name: 'Qoder',          type: 'IDE',    cmd: 'npx superpowers-zh',                          mode: 'auto' },
+  { name: 'Aider',          type: 'CLI',    cmd: 'npx superpowers-zh',                          mode: 'auto' },
+  { name: 'OpenCode',       type: 'CLI',    cmd: 'npx superpowers-zh',                          mode: 'auto' },
+  // Qwen Code = QwenLM/qwen-code 这个命令行工具（Gemini CLI 的 fork），不是通义灵码。
+  { name: 'Qwen Code',      type: 'CLI',    cmd: 'npx superpowers-zh',                          mode: 'auto' },
+  // Antigravity 是 Google 的 AI IDE（antigravity.google），见 docs/README.antigravity.md。
+  { name: 'Antigravity',    type: 'IDE',    cmd: 'npx superpowers-zh',                          mode: 'auto' },
+  { name: 'DeerFlow 2.0',   type: 'Agent',  cmd: 'npx superpowers-zh',                          mode: 'auto' },
+  { name: 'VS Code · Copilot', type: 'IDE', cmd: 'npx superpowers-zh',                          mode: 'auto' },
+  // Copilot CLI 与 Claude Code 共用 .claude/skills，别名 copilot -> Claude Code，
+  // 它自己没有检测标记，所以必须 --tool 指定。
+  { name: 'Copilot CLI',    type: 'CLI',    cmd: 'npx superpowers-zh --tool copilot',           mode: 'manual' },
+  // Hermes 官方只自动加载 ~/.hermes/skills/，项目级目录要手写 config.yaml 才被发现，
+  // 所以这里给的是 --global 的装法（与 README 的一键安装列一致）。
+  { name: 'Hermes Agent',   type: 'CLI',    cmd: 'npx superpowers-zh --global --tool hermes',   mode: 'global' },
+  { name: 'Claw Code',      type: 'CLI',    cmd: 'npx superpowers-zh',                          mode: 'auto' },
+  { name: 'OpenClaw',       type: 'CLI',    cmd: 'npx superpowers-zh',                          mode: 'auto' },
+  { name: 'CodeBuddy',      type: 'IDE',    cmd: 'npx superpowers-zh',                          mode: 'auto' },
+  { name: 'CodeArts',       type: 'IDE',    cmd: 'npx superpowers-zh',                          mode: 'auto' },
+  // Cline / Kilo Code 的检测标记是 rules 目录（.clinerules / .kilocode），没建过规则的
+  // 项目检测不到，与 README 一致给显式 --tool。
+  { name: 'Cline',          type: 'IDE',    cmd: 'npx superpowers-zh --tool cline',             mode: 'manual' },
+  { name: 'Kilo Code',      type: 'IDE',    cmd: 'npx superpowers-zh --tool kilocode',          mode: 'manual' },
+  { name: 'Crush',          type: 'CLI',    cmd: 'npx superpowers-zh',                          mode: 'auto' },
 ];

 // ---- 双语文案 ----
@@ -190,6 +209,7 @@ const T = {
    instLabel: '我用的是',
    instNoteAuto: '在你的项目根目录运行，<b>自动识别 {name}</b> 并安装。安装后重启工具即可生效。',
    instNoteManual: '{name} 无法自动识别，需用 <code>--tool</code> 显式指定。在项目根目录运行，安装后重启工具即可生效。',
+    instNoteGlobal: '{name} 只会自动加载用户级目录，项目级要手写配置才生效 —— 所以直接用 <code>--global</code> 装到用户级，在任意目录运行即可。',
    skTitle: '{n} 个 Skill，覆盖开发全流程',
    skSub: '点击任意卡片查看完整操作文档。',
    skSearch: '搜索 skill…（如 调试 / review / TDD）',
@@ -293,7 +313,7 @@ const T = {
      { q: '支持哪些 AI 编程工具？', a: '共 23 款：Claude Code、Cursor、Windsurf、Codex CLI、Gemini CLI、Kiro、Trae、Qoder、CodeBuddy（腾讯）、CodeArts（华为云码道）、Aider、OpenCode、Qwen Code、Antigravity、DeerFlow、VS Code(Copilot)、Copilot CLI、Hermes Agent、Claw Code、OpenClaw、Cline、Kilo Code、Crush。' },
      { q: 'superpowers-zh 有哪些独特价值？', a: '一套完整中文化的系统工作方法论：从头脑风暴、规划、TDD 到调试、代码审查，每个 skill 都是实战验证的工作流；并叠加 4 个面向中国开发者的原创 skill（中文代码审查 / Git 工作流 / 文档规范 / 提交规范），适配 23 款 AI 编程工具。MIT 协议开源，永久免费。' },
      { q: '安装后怎么生效？', a: 'npx 会把 skill 文件装到你项目对应工具的目录（如 .claude/skills/），重启 AI 工具后，它会在恰当时机自动触发相应 skill —— 无需你每次手动调用。' },
-      { q: '能一次装好、所有项目都用吗？（全局安装）', a: '能。npx superpowers-zh --global 装到工具的用户级目录（如 ~/.claude/skills），所有项目自动共享，更新时只需重装一次。项目级优先、全局兜底，二者可共存。支持全局的工具（均为各工具文档确认的加载路径）：Claude Code / Codex CLI / Qoder / Windsurf / Qwen Code / OpenClaw / OpenCode；其余工具（含 Gemini / Antigravity，有各自专属全局方式）请在项目内安装或参考对应文档。' },
+      { q: '能一次装好、所有项目都用吗？（全局安装）', a: '能。npx superpowers-zh --global 装到工具的用户级目录（如 ~/.claude/skills），所有项目自动共享，更新时只需重装一次。项目级优先、全局兜底，二者可共存。支持全局的工具（11 款，均为各工具文档确认的加载路径）：Claude Code / Codex CLI / Qoder / Windsurf / Qwen Code / OpenClaw / OpenCode / Hermes Agent / CodeBuddy / CodeArts / Crush；其余工具（含 Gemini / Antigravity，有各自专属全局方式）请在项目内安装或参考对应文档。' },
      { q: '会拖慢我的 AI 吗？会上传代码吗？', a: '不会。skill 是按需触发的纯 Markdown，零运行时、不联网、不上传任何代码或数据，全程在本地。' },
      { q: '怎么更新或卸载？', a: '更新：重新运行 npx superpowers-zh 覆盖即可。卸载：npx superpowers-zh --uninstall 清理当前项目；全局安装用 npx superpowers-zh --global --uninstall 清理。' },
    ],
@@ -321,6 +341,7 @@ const T = {
    instLabel: "I'm using",
    instNoteAuto: 'Run it in your project root — it <b>auto-detects {name}</b> and installs. Restart the tool to take effect.',
    instNoteManual: '{name} can\'t be auto-detected; pass <code>--tool</code> explicitly. Run in the project root, then restart the tool.',
+    instNoteGlobal: '{name} only auto-loads its user-level directory — a project-level install needs manual config. Install with <code>--global</code> instead; run it from anywhere.',
    skTitle: '{n} skills, covering the whole dev workflow',
    skSub: 'Click any card for the full operating doc.',
    skSearch: 'Search skills… (e.g. debug / review / TDD)',
@@ -424,7 +445,7 @@ const T = {
      { q: 'Which AI coding tools are supported?', a: '23 tools: Claude Code, Cursor, Windsurf, Codex CLI, Gemini CLI, Kiro, Trae, Qoder, CodeBuddy (Tencent), CodeArts (Huawei), Aider, OpenCode, Qwen Code, Antigravity, DeerFlow, VS Code (Copilot), Copilot CLI, Hermes Agent, Claw Code, OpenClaw, Cline, Kilo Code, Crush.' },
      { q: 'What makes superpowers-zh unique?', a: 'A fully localized, battle-tested methodology framework for Chinese developers: brainstorming, planning, TDD, debugging, and code-review skills, plus 4 China-native skills (code review / Git workflow / docs / commit conventions), adapted for 23 AI coding tools. MIT-licensed and free forever.' },
      { q: 'How does it take effect after install?', a: 'npx installs skill files into your tool\'s directory (e.g. .claude/skills/). After restarting your AI tool, it auto-triggers the right skill at the right moment — no manual invocation needed.' },
-      { q: 'Can I install once for all projects? (global install)', a: 'Yes. npx superpowers-zh --global installs into the tool\'s user-level directory (e.g. ~/.claude/skills), shared across all projects; you only re-install once to update. Project-level takes precedence, global is the fallback — they coexist. Tools with global support (all verified load paths per each tool\'s docs): Claude Code / Codex CLI / Qoder / Windsurf / Qwen Code / OpenClaw / OpenCode; other tools (incl. Gemini / Antigravity, which have their own global methods) should be installed per-project or via their docs.' },
+      { q: 'Can I install once for all projects? (global install)', a: 'Yes. npx superpowers-zh --global installs into the tool\'s user-level directory (e.g. ~/.claude/skills), shared across all projects; you only re-install once to update. Project-level takes precedence, global is the fallback — they coexist. Tools with global support (11 in total, all verified load paths per each tool\'s docs): Claude Code / Codex CLI / Qoder / Windsurf / Qwen Code / OpenClaw / OpenCode / Hermes Agent / CodeBuddy / CodeArts / Crush; other tools (incl. Gemini / Antigravity, which have their own global methods) should be installed per-project or via their docs.' },
      { q: 'Will it slow my AI down or upload my code?', a: 'No. Skills are on-demand Markdown: zero runtime, no network, no code or data upload — everything stays local.' },
      { q: 'How do I update or uninstall?', a: 'Update: re-run npx superpowers-zh to overwrite. Uninstall: npx superpowers-zh --uninstall for the current project; npx superpowers-zh --global --uninstall for a global install.' },
    ],
@@ -452,6 +473,7 @@ const T = {
    instLabel: '我用的是',
    instNoteAuto: '在你的專案根目錄執行，<b>自動識別 {name}</b> 並安裝。安裝後重啟工具即可生效。',
    instNoteManual: '{name} 無法自動識別，需用 <code>--tool</code> 顯式指定。在專案根目錄執行，安裝後重啟工具即可生效。',
+    instNoteGlobal: '{name} 只會自動載入使用者級目錄，專案級要手寫設定才生效 —— 所以直接用 <code>--global</code> 裝到使用者級，在任意目錄執行即可。',
    skTitle: '{n} 個 Skill，覆蓋開發全流程',
    skSub: '點擊任意卡片查看完整操作文件。',
    skSearch: '搜尋 skill…（如 除錯 / review / TDD）',
@@ -555,7 +577,7 @@ const T = {
      { q: '支援哪些 AI 編程工具？', a: '共 23 款：Claude Code、Cursor、Windsurf、Codex CLI、Gemini CLI、Kiro、Trae、Qoder、CodeBuddy（騰訊）、CodeArts（華為雲碼道）、Aider、OpenCode、Qwen Code、Antigravity、DeerFlow、VS Code(Copilot)、Copilot CLI、Hermes Agent、Claw Code、OpenClaw、Cline、Kilo Code、Crush。' },
      { q: 'superpowers-zh 有哪些獨特價值？', a: '一套完整中文化的系統工作方法論：從頭腦風暴、規劃、TDD 到除錯、程式碼審查，每個 skill 都是實戰驗證的工作流；並疊加 4 個面向中國開發者的原創 skill（中文程式碼審查 / Git 工作流 / 文件規範 / 提交規範），適配 23 款 AI 編程工具。MIT 協議開源，永久免費。' },
      { q: '安裝後怎麼生效？', a: 'npx 會把 skill 檔案裝到你專案對應工具的目錄（如 .claude/skills/），重啟 AI 工具後，它會在恰當時機自動觸發相應 skill —— 無需你每次手動呼叫。' },
-      { q: '能一次裝好、所有專案都用嗎？（全域安裝）', a: '能。npx superpowers-zh --global 裝到工具的使用者級目錄（如 ~/.claude/skills），所有專案自動共享，更新時只需重裝一次。專案級優先、全域兜底，二者可共存。支援全域的工具（均為各工具文件確認的載入路徑）：Claude Code / Codex CLI / Qoder / Windsurf / Qwen Code / OpenClaw / OpenCode；其餘工具（含 Gemini / Antigravity，有各自專屬全域方式）請在專案內安裝或參考對應文件。' },
+      { q: '能一次裝好、所有專案都用嗎？（全域安裝）', a: '能。npx superpowers-zh --global 裝到工具的使用者級目錄（如 ~/.claude/skills），所有專案自動共享，更新時只需重裝一次。專案級優先、全域兜底，二者可共存。支援全域的工具（11 款，均為各工具文件確認的載入路徑）：Claude Code / Codex CLI / Qoder / Windsurf / Qwen Code / OpenClaw / OpenCode / Hermes Agent / CodeBuddy / CodeArts / Crush；其餘工具（含 Gemini / Antigravity，有各自專屬全域方式）請在專案內安裝或參考對應文件。' },
      { q: '會拖慢我的 AI 嗎？會上傳程式碼嗎？', a: '不會。skill 是按需觸發的純 Markdown，零執行時、不連網、不上傳任何程式碼或資料，全程在本機。' },
      { q: '怎麼更新或解除安裝？', a: '更新：重新執行 npx superpowers-zh 覆蓋即可。解除安裝：npx superpowers-zh --uninstall 清理目前專案；全域安裝用 npx superpowers-zh --global --uninstall 清理。' },
    ],
@@ -693,7 +715,7 @@ function renderLanding(skills, lang) {
  const t = T[lang];
  const total = skills.length;
  const cnCount = skills.filter(s => s.china).length;
-  const toolData = JSON.stringify(TOOLS.map(x => ({ name: x.name, cmd: x.cmd, auto: x.auto })));
+  const toolData = JSON.stringify(TOOLS.map(x => ({ name: x.name, cmd: x.cmd, mode: x.mode })));
  const fill = (s, map) => s.replace(/\{(\w+)\}/g, (_, k) => map[k]);

  const cards = skills.map(s => {
@@ -710,7 +732,8 @@ function renderLanding(skills, lang) {

  const filters = GROUPS.map((g, i) =>
    `<button class="chip${i === 0 ? ' active' : ''}" data-filter="${g.id}">${lang === 'zh' ? g.zh : g.en}</button>`).join('');
-  const toolOpts = TOOLS.map((x, i) => `<option value="${i}">${esc(x.name)}${x.auto ? '' : '（--tool）'}</option>`).join('');
+  const modeTag = { auto: '', manual: '（--tool）', global: '（--global）' };
+  const toolOpts = TOOLS.map((x, i) => `<option value="${i}">${esc(x.name)}${modeTag[x.mode] || ''}</option>`).join('');
  const toolWall = TOOLS.map(x => `<div class="tool-pill"><span class="tool-name">${esc(x.name)}</span><span class="tool-type">${esc(x.type)}</span></div>`).join('');
  const feats = t.features.map(f => `<article class="feat"><div class="feat-icon">${f.icon}</div><h3>${esc(f.t)}</h3><p>${esc(f.d)}</p></article>`).join('');
  const pipe = t.pipeline.map((p, i) => `<div class="pl-step"><div class="pl-num">${i + 1}</div><div class="pl-body"><b>${esc(p.n)}</b><span>${esc(p.d)}</span></div></div>${i < t.pipeline.length - 1 ? '<div class="pl-arrow">→</div>' : ''}`).join('');
@@ -731,7 +754,7 @@ function renderLanding(skills, lang) {
    <div class="stats">
      <div><b>${total}</b><span>${t.stats[0]}</span></div>
      <div><b>${cnCount}</b><span>${t.stats[1]}</span></div>
-      <div><b>20</b><span>${t.stats[2]}</span></div>
+      <div><b>${TOOLS.length}</b><span>${t.stats[2]}</span></div>
      <div><b>v${PKG.version}</b><span>${t.stats[3]}</span></div>
    </div>
  </section>
@@ -810,7 +833,7 @@ function renderLanding(skills, lang) {
    </div>
  </div></section>
 </main>
-<script>window.__TOOLS__=${toolData};window.__I18N__={auto:${JSON.stringify(t.instNoteAuto)},manual:${JSON.stringify(t.instNoteManual)},copy:${JSON.stringify(t.copy)},copied:${JSON.stringify(t.copied)}};</script>`;
+<script>window.__TOOLS__=${toolData};window.__I18N__={auto:${JSON.stringify(t.instNoteAuto)},manual:${JSON.stringify(t.instNoteManual)},global:${JSON.stringify(t.instNoteGlobal)},copy:${JSON.stringify(t.copy)},copied:${JSON.stringify(t.copied)}};</script>`;
 }

 // ---- 赞助商独立页 ----
@@ -939,11 +962,14 @@ ${flagSection}${moreSection}
 function renderDetail(skill, lang) {
  const t = T[lang];
  const title = lang === 'en' ? skill.titleEn : skill.title;
-  const bodyHtml = renderMarkdown(skill.raw);
+  // 传入该 skill 在仓库里的目录 URL：SKILL.md 里指向兄弟文件的相对链接
+  // （implementer-prompt.md、../requesting-code-review/code-reviewer.md 等）
+  // 站点上并不存在，必须解析成 GitHub 地址，否则全是死链。
+  const bodyHtml = renderMarkdown(skill.raw, `${GH_BLOB}/skills/${skill.name}/`);
  const cnNotice = lang === 'en'
    ? '<div class="doc-notice">📖 This skill\'s content is written in Chinese — superpowers-zh is a Chinese-localized toolkit.</div>'
    : '';
-  const srcUrl = `https://github.com/jnMetaCode/superpowers-zh/blob/main/skills/${skill.name}/SKILL.md`;
+  const srcUrl = `${GH_BLOB}/skills/${skill.name}/SKILL.md`;
  return `
 <main class="doc">
  <a class="doc-back" href="../index.html#skills">${t.backToSkills}</a>
--- a/site/md.mjs
+++ b/site/md.mjs
--- a/site/template/app.js
+++ b/site/template/app.js
@@ -66,7 +66,8 @@
    if (!t) return;
    cmdText.textContent = t.cmd;
    cmdBox.setAttribute('data-copy', t.cmd);
-    var tpl = t.auto ? I18N.auto : I18N.manual;
+    // mode: auto（自动识别）/ manual（必须 --tool）/ global（只有 --global 才生效）
+    var tpl = I18N[t.mode] || I18N.manual;
    if (note && tpl) note.innerHTML = tpl.replace('{name}', escapeHtml(t.name));
  }
  if (sel && note) {