superpowers-zh 1.7.8 → 1.7.10

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "superpowers-zh",
       "description": "AI 编程超能力中文增强版：20 个 skills（14 翻译 + 4 中国原创 + 2 上游历史保留），支持 Claude Code / Hermes Agent / Cursor / Claw Code / Qoder 等 23 款工具",
-      "version": "1.7.8",
+      "version": "1.7.10",
       "source": "./",
       "author": {
         "name": "jnMetaCode",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers-zh",
   "description": "AI 编程超能力中文增强版：20 个 skills（14 翻译 + 4 中国原创 + 2 上游历史保留），支持 Claude Code / Hermes Agent / Cursor / Claw Code / Qoder 等 23 款工具",
-  "version": "1.7.8",
+  "version": "1.7.10",
   "author": {
     "name": "jnMetaCode",
     "url": "https://github.com/jnMetaCode"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers-zh",
-  "version": "1.7.8",
+  "version": "1.7.10",
   "description": "AI 编程超能力中文增强版：头脑风暴、subagent 驱动开发、规划、TDD、调试、代码审查、收尾工作流，附 4 个中文 skills 沉淀。",
   "author": {
     "name": "jnMetaCode",

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "superpowers-zh",
   "displayName": "Superpowers 中文版",
   "description": "AI 编程超能力中文增强版：20 个 skills（14 翻译 + 4 中国原创 + 2 上游历史保留），支持 Cursor / Claude Code / Hermes Agent / Claw Code / Qoder 等 23 款工具",
-  "version": "1.7.8",
+  "version": "1.7.10",
   "author": {
     "name": "jnMetaCode",
     "url": "https://github.com/jnMetaCode"

package/README.md

@@ -16,7 +16,12 @@ Chinese community edition of [superpowers](https://github.com/obra/superpowers)
 >
 > 🌍 Also available in [English](https://aiolaola.com/en?utm_source=github&utm_campaign=superpowers) · [日本語](https://aiolaola.com/ja?utm_source=github&utm_campaign=superpowers) · [Español](https://aiolaola.com/es?utm_source=github&utm_campaign=superpowers) · [한국어](https://aiolaola.com/ko?utm_source=github&utm_campaign=superpowers) · [繁體中文](https://aiolaola.com/zh-Hant?utm_source=github&utm_campaign=superpowers)
 
-> 🆕 **v1.7.8 更新亮点**（[完整 Release Notes →](RELEASE-NOTES.zh.md)）
+> 🆕 **v1.7.10 更新亮点**（[完整 Release Notes →](RELEASE-NOTES.zh.md)）
+> - 🐛 **Aider 用户请重装** —— 两个错叠一起等于完全不可用：真实 Aider 项目从来没被自动检测到过（它不创建 `.aider/` 目录），且 `CONVENTIONS.md` **不会**被自动加载（官方要求 `--read`）。现在检测认真实标记，装完打印激活命令
+> - 🐛 **Kiro 用户请重装** —— `.kiro/steering/` 下的文件**每轮对话全量进上下文**，而我们把 20 个 skill 正文全塞了进去：实测 **335 KB/轮**。改为索引式后 **4.4 KB**（76 倍），重装会自动清旧布局
+> - 🐛 **Qoder 工具映射表有错** —— `Explore`/`Plan` 的 agent 名是编的（官方就是同名），且表没标适用范围（只覆盖 Qoder CLI，IDE 不同）（[#119](https://github.com/jnMetaCode/superpowers-zh/issues/119)）
+> - 🛡️ **堵上「拿代码测代码」的测试盲区** —— Aider 那个 bug 能在 90 项全绿下活着，是因为测试 `mkdir .aider` 再断言认出 Aider。已补真实标记 + Kiro 两条硬回归守卫（90 → 101 pass）
+> - 🐛 **Hermes 用户请重装** —— 之前我们只装项目级 `.hermes/skills/`，而 Hermes 根本不读那个目录，等于**装了完全不生效**。现在改用 `npx superpowers-zh --global --tool hermes` 装到 `~/.hermes/skills/`（[#45](https://github.com/jnMetaCode/superpowers-zh/issues/45)）
 > - 🔍 **定位核查** —— 逐层比对上游，修掉 5 处「不是增量」的偏离；新增 audit 检查强制 fork 增量必须显式声明
 > - 🆕 **新增 Crush**（工具数 22 → 23）—— 若你已为 CC / Cursor / Codex 装过，Crush 其实已经能读到，别重复装
 > - 🎯 **上游 v6.2.0 对齐完成** —— audit 的结构漂移告警清零；C 块盘点时发现其中 3 项不是风格改动而是实质新规则
@@ -133,10 +138,10 @@ AI：在开始实现之前，我需要了解几个关键问题：
 |------|------|:---:|:---:|
 | [Claude Code](https://claude.ai/code) | CLI | `npx superpowers-zh` | `.claude/skills/` |
 | [Copilot CLI](https://githubnext.com/projects/copilot-cli) | CLI | `npx superpowers-zh --tool copilot` | `.claude/skills/` |
-| [Hermes Agent](https://github.com/NousResearch/hermes-agent) | CLI | `npx superpowers-zh --tool hermes` | `.hermes/skills/` |
+| [Hermes Agent](https://github.com/NousResearch/hermes-agent) | CLI | `npx superpowers-zh --global --tool hermes` | `~/.hermes/skills/` |
 | [Cursor](https://cursor.sh) | IDE | `npx superpowers-zh` | `.cursor/skills/` |
 | [Windsurf](https://codeium.com/windsurf) | IDE | `npx superpowers-zh` | `.windsurf/skills/` |
-| [Kiro](https://kiro.dev) | IDE | `npx superpowers-zh` | `.kiro/steering/` |
+| [Kiro](https://kiro.dev) | IDE | `npx superpowers-zh` | `.kiro/skills/` |
 | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | CLI | `npx superpowers-zh` | `.gemini/skills/` |
 | [Codex CLI](https://github.com/openai/codex) | CLI | `npx superpowers-zh` | `.codex/skills/` |
 | [Aider](https://aider.chat) | CLI | `npx superpowers-zh` | `.aider/skills/` |
@@ -214,7 +219,7 @@ npx superpowers-zh --global --tool claude   # 或指定工具
 
 全局安装把 skills 装到工具的**用户级目录**（如 `~/.claude/skills`），一次安装所有项目自动可用，更新时也只需重装一次。**项目级优先、全局兜底**，二者可共存。
 
-支持通用全局安装的工具（均为 docs 已证实的用户级加载路径）：**Claude Code · Codex CLI · Qoder · Windsurf · Qwen Code · OpenClaw · OpenCode · Crush**。其中 **Codex CLI** 全局装到 `~/.agents/skills`（Codex 启动扫描目录）。其余工具（Cursor / Kiro / Trae / Aider / DeerFlow / VS Code / Hermes / Claw / Cline / Kilo Code）规则是项目级或存于应用内设置，`--global` 会提示改用项目级；**Gemini CLI / Antigravity** 有各自专属的全局方式（Gemini 走扩展目录），见对应 `docs/README.*.md`。
+支持通用全局安装的工具（均为 docs 已证实的用户级加载路径）：**Claude Code · Codex CLI · Qoder · Windsurf · Qwen Code · OpenClaw · OpenCode · Crush · Hermes Agent**。其中 **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`） |
 |---|---|---|
@@ -270,7 +275,7 @@ cp -r superpowers-zh/skills /your/project/.claude/skills      # Claude Code / Co
 cp -r superpowers-zh/skills /your/project/.hermes/skills      # Hermes Agent
 cp -r superpowers-zh/skills /your/project/.cursor/skills      # Cursor
 cp -r superpowers-zh/skills /your/project/.codex/skills       # Codex CLI
-cp -r superpowers-zh/skills /your/project/.kiro/steering      # Kiro
+cp -r superpowers-zh/skills /your/project/.kiro/skills        # Kiro
 cp -r superpowers-zh/skills /your/project/skills/custom       # DeerFlow 2.0
 cp -r superpowers-zh/skills /your/project/.trae/rules         # Trae
 cp -r superpowers-zh/skills /your/project/.agents        # Antigravity
@@ -294,7 +299,7 @@ cp -r superpowers-zh/skills /your/project/.qoder/skills      # Qoder（阿里 AI
 | Claude Code | `CLAUDE.md` | 项目根目录 |
 | Copilot CLI | `CLAUDE.md` | 与 Claude Code 共用插件格式 |
 | Hermes Agent | `HERMES.md` 或 `.hermes.md` | 项目根目录，安装时自动生成 |
-| Kiro | `.kiro/steering/*.md` | 支持 always/globs/手动三种模式 |
+| Kiro | `.kiro/steering/superpowers-zh.md`（索引，`inclusion: always`）+ `.kiro/skills/` | steering 每轮常驻，故只放索引 |
 | DeerFlow 2.0 | `skills/custom/*/SKILL.md` | 字节跳动开源 SuperAgent，自动发现自定义 skills |
 | Trae | `.trae/rules/project_rules.md` | 项目级规则 |
 | Antigravity | `GEMINI.md` 或 `AGENTS.md` | 项目根目录 |

package/README.zh-Hant.md

@@ -16,7 +16,12 @@ Chinese community edition of [superpowers](https://github.com/obra/superpowers)
 
 > 📖 **免費配套學習** → [從零學會 AI 編程](https://aiolaola.com/?utm_source=github&utm_campaign=superpowers)：180 節免費實操課 + 《AI 編程實戰三卷書》線上閱讀 + 實戰社群 · superpowers 裝好後配上方法論效率翻倍 · 永久免費
 
-> 🆕 **v1.7.8 更新亮點**（[完整 Release Notes →](RELEASE-NOTES.zh.md)）
+> 🆕 **v1.7.10 更新亮點**（[完整 Release Notes →](RELEASE-NOTES.zh.md)）
+> - 🐛 **Aider 使用者請重裝** —— 兩個錯疊一起等於完全不可用：真實 Aider 專案從來沒被自動偵測到過（它不建立 `.aider/` 目錄），且 `CONVENTIONS.md` **不會**被自動載入（官方要求 `--read`）。現在偵測認真實標記，裝完列印啟用命令
+> - 🐛 **Kiro 使用者請重裝** —— `.kiro/steering/` 下的檔案**每輪對話全量進上下文**，而我們把 20 個 skill 正文全塞了進去：實測 **335 KB/輪**。改為索引式後 **4.4 KB**（76 倍），重裝會自動清舊佈局
+> - 🐛 **Qoder 工具對映表有錯** —— `Explore`/`Plan` 的 agent 名是編的（官方就是同名），且表沒標適用範圍（只涵蓋 Qoder CLI，IDE 不同）（[#119](https://github.com/jnMetaCode/superpowers-zh/issues/119)）
+> - 🛡️ **堵上「拿程式碼測程式碼」的測試盲區** —— Aider 那個 bug 能在 90 項全綠下活著，是因為測試 `mkdir .aider` 再斷言認出 Aider。已補真實標記 + Kiro 兩條硬回歸守衛（90 → 101 pass）
+> - 🐛 **Hermes 使用者請重裝** —— 之前我們只裝專案級 `.hermes/skills/`，而 Hermes 根本不讀那個目錄，等於**裝了完全不生效**。現在改用 `npx superpowers-zh --global --tool hermes` 裝到 `~/.hermes/skills/`（[#45](https://github.com/jnMetaCode/superpowers-zh/issues/45)）
 > - 🔍 **定位核查** —— 逐層比對上游，修掉 5 處「不是增量」的偏離；新增 audit 檢查強制 fork 增量必須顯式聲明
 > - 🆕 **新增 Crush**（工具數 22 → 23）—— 若你已為 CC / Cursor / Codex 裝過，Crush 其實已經能讀到，別重複裝
 > - 🎯 **上游 v6.2.0 對齊完成** —— audit 的結構漂移告警清零；C 塊盤點時發現其中 3 項不是風格改動而是實質新規則
@@ -133,10 +138,10 @@ AI：在開始實作之前，我需要了解幾個關鍵問題：
 |------|------|:---:|:---:|
 | [Claude Code](https://claude.ai/code) | CLI | `npx superpowers-zh` | `.claude/skills/` |
 | [Copilot CLI](https://githubnext.com/projects/copilot-cli) | CLI | `npx superpowers-zh --tool copilot` | `.claude/skills/` |
-| [Hermes Agent](https://github.com/NousResearch/hermes-agent) | CLI | `npx superpowers-zh --tool hermes` | `.hermes/skills/` |
+| [Hermes Agent](https://github.com/NousResearch/hermes-agent) | CLI | `npx superpowers-zh --global --tool hermes` | `~/.hermes/skills/` |
 | [Cursor](https://cursor.sh) | IDE | `npx superpowers-zh` | `.cursor/skills/` |
 | [Windsurf](https://codeium.com/windsurf) | IDE | `npx superpowers-zh` | `.windsurf/skills/` |
-| [Kiro](https://kiro.dev) | IDE | `npx superpowers-zh` | `.kiro/steering/` |
+| [Kiro](https://kiro.dev) | IDE | `npx superpowers-zh` | `.kiro/skills/` |
 | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | CLI | `npx superpowers-zh` | `.gemini/skills/` |
 | [Codex CLI](https://github.com/openai/codex) | CLI | `npx superpowers-zh` | `.codex/skills/` |
 | [Aider](https://aider.chat) | CLI | `npx superpowers-zh` | `.aider/skills/` |
@@ -214,7 +219,7 @@ npx superpowers-zh --global --tool claude   # 或指定工具
 
 全域安裝把 skills 裝到工具的**使用者級目錄**（如 `~/.claude/skills`），一次安裝所有專案自動可用，更新時也只需重裝一次。**專案級優先、全域兜底**，二者可共存。
 
-支援通用全域安裝的工具（均為 docs 已證實的使用者級載入路徑）：**Claude Code · Codex CLI · Qoder · Windsurf · Qwen Code · OpenClaw · OpenCode · Crush**。其中 **Codex CLI** 全域裝到 `~/.agents/skills`（Codex 啟動掃描目錄）。其餘工具（Cursor / Kiro / Trae / Aider / DeerFlow / VS Code / Hermes / Claw / Cline / Kilo Code）規則是專案級或存於應用內設定，`--global` 會提示改用專案級；**Gemini CLI / Antigravity** 有各自專屬的全域方式（Gemini 走擴充目錄），見對應 `docs/README.*.md`。
+支援通用全域安裝的工具（均為 docs 已證實的使用者級載入路徑）：**Claude Code · Codex CLI · Qoder · Windsurf · Qwen Code · OpenClaw · OpenCode · Crush · Hermes Agent**。其中 **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`） |
 |---|---|---|
@@ -270,7 +275,7 @@ cp -r superpowers-zh/skills /your/project/.claude/skills      # Claude Code / Co
 cp -r superpowers-zh/skills /your/project/.hermes/skills      # Hermes Agent
 cp -r superpowers-zh/skills /your/project/.cursor/skills      # Cursor
 cp -r superpowers-zh/skills /your/project/.codex/skills       # Codex CLI
-cp -r superpowers-zh/skills /your/project/.kiro/steering      # Kiro
+cp -r superpowers-zh/skills /your/project/.kiro/skills        # Kiro
 cp -r superpowers-zh/skills /your/project/skills/custom       # DeerFlow 2.0
 cp -r superpowers-zh/skills /your/project/.trae/rules         # Trae
 cp -r superpowers-zh/skills /your/project/.agents        # Antigravity
@@ -294,7 +299,7 @@ cp -r superpowers-zh/skills /your/project/.qoder/skills      # Qoder（阿里 AI
 | Claude Code | `CLAUDE.md` | 專案根目錄 |
 | Copilot CLI | `CLAUDE.md` | 與 Claude Code 共用外掛格式 |
 | Hermes Agent | `HERMES.md` 或 `.hermes.md` | 專案根目錄，安裝時自動產生 |
-| Kiro | `.kiro/steering/*.md` | 支援 always/globs/手動三種模式 |
+| Kiro | `.kiro/steering/superpowers-zh.md`（索引，`inclusion: always`）+ `.kiro/skills/` | steering 每輪常駐，故只放索引 |
 | DeerFlow 2.0 | `skills/custom/*/SKILL.md` | 位元組跳動開源 SuperAgent，自動發現自訂 skills |
 | Trae | `.trae/rules/project_rules.md` | 專案級規則 |
 | Antigravity | `GEMINI.md` 或 `AGENTS.md` | 專案根目錄 |

package/RELEASE-NOTES.zh.md

@@ -6,6 +6,126 @@
 
 ---
 
+## v1.7.10 (2026-08-12)
+
+**Aider 和 Kiro 用户请重新安装。** 本版本源于一次对「我们自己那层工具支持」的系统核查 —— 起因是 v1.7.9 修 Hermes 时发现：我们从支持它起就装错了目录。既然错过一次，就该问一句**还有几个**。
+
+答案是：又查出三个，全部是我们自己写的、全部没查过官方文档。
+
+### 🐛 Aider：两个错叠在一起，等于完全不可用
+
+**① 真实的 Aider 项目从来没被自动检测到过。**
+
+检测标记写的是 `.aider`，即要求存在一个 `.aider/` **目录** —— 而 Aider 根本不创建这个目录。它在项目根留下的是 `.aider.` 前缀的产物：`.aider.conf.yml`、`.aider.chat.history.md`、`.aider.tags.cache.v3/`。
+
+实测：造一个含这三样的真实 Aider 项目跑 `npx superpowers-zh`，输出「未检测到任何已知 AI 编程工具」。而文档一直写着「会自动检测 `.aider.conf.yml` 文件」—— **文档描述的是意图，代码做的是另一回事。**
+
+已改为认这四个标记。
+
+**② `CONVENTIONS.md` 不会被 Aider 自动加载。**
+
+代码注释和文档都断言「Aider 原生支持自动加载此文件」。[官方文档](https://aider.chat/docs/usage/conventions.html)说的是反的：必须 `aider --read CONVENTIONS.md`，或在 `.aider.conf.yml` 里写 `read: CONVENTIONS.md`。
+
+最糟的是文档「Skills 未生效」排障的第 3 条写着「Aider 会自动读取 CONVENTIONS.md，无需额外配置」—— **用户卡住时来查文档，看到的正好是让他继续卡住的那句。**
+
+改法照搬 v1.7.9 的 Hermes：装完打印可直接用的两种激活方式，**不替用户改 `.aider.conf.yml`**（那是他们的文件）。
+
+### 🐛 Kiro：错的方向正好相反 —— 每一轮烧 335 KB
+
+[Kiro 官方文档](https://kiro.dev/docs/steering/)明确：`.kiro/steering/` 下的文件**默认就是 `inclusion: always`**，"loaded into every Kiro interaction automatically"。
+
+而我们把 20 个 skill 的正文整个装了进去。实测 **47 个 md、335 KB，每一轮对话全量进上下文**。
+
+讽刺的是这个问题我们早解过 —— 当初给 Cline / Kilo Code 做适配时专门设计了「常驻位置只放索引、正文按需读取」（那次是 182 KB）。只是没意识到 Kiro 的 steering 是同一性质。现在照搬：
+
+| | v1.7.9 | v1.7.10 |
+|---|---|---|
+| steering 常驻 | 47 个 md / 335 KB | **1 个索引 / 4.4 KB** |
+| skill 正文 | `.kiro/steering/<name>/` | `.kiro/skills/<name>/`（按需读取） |
+
+**76 倍。** 升级路径是这次最要紧的一块：老用户通常直接重装而不会先卸载，不清旧布局的话新旧两份并存、335 KB 一点没减 —— 那就等于没修。所以安装时先清 `.kiro/steering/` 下与我们 skill 同名的目录，并打印清理了几个。**你自己写的 steering 文件不会被动**，已实测。
+
+另外文档里写的加载模式 `alwaysApply: true` / `globs: "*.ts"` —— 这两个键 **Kiro 文档里根本不存在**，是 Cursor / Trae 的约定被误写成了 Kiro 的。Kiro 实际用 `inclusion` / `fileMatchPattern`。已按官方文档重写整篇。
+
+### 🐛 Qoder：工具映射表是编的（[#119](https://github.com/jnMetaCode/superpowers-zh/issues/119)）
+
+报告人说 Qoder IDE 里没有 `general-purpose` 子智能体，而我们的 `qoder-tools.md` 白纸黑字写着有。查该文件的引入 commit —— **没有引用任何来源**。
+
+对照 [Qoder 官方子代理文档](https://docs.qoder.com/zh/cli/subagent)，4 行错了 2 行：`Explore → explore-agent`、`Plan → plan-agent` 都是错的，文档里就是**同名**；「Qoder 有内置 `code-reviewer`」也是编的（文档里的 `api-reviewer` 是用户自建示例）。
+
+但最关键的不是这几行 —— **那张表根本没标适用范围**。官方文档只覆盖 Qoder CLI，报告人用的是 Qoder IDE，两个产品面本来就不同，而我们的表让 IDE 用户当成了权威。已补适用范围、来源链接、核对日期，和一节 IDE/CLI 差异说明。
+
+### 🛡️ 把「拿代码测代码」的盲区堵上
+
+Aider 那个 bug 能在 90 项全绿的情况下活下来，是因为测试写的是 `mkdir .aider` 然后断言认出 Aider —— **拿代码测代码，真实标记一个都没测。**
+
+已补：
+
+- Aider 的三个真实标记进检测测试；`case` 分支加 `*.yml`（`.aider.conf.yml` 是文件不是目录，用目录冒充等于测了个假场景）
+- Kiro 两条硬回归守卫：steering 下**只能有 1 个 md**、常驻总字节 **< 20 KB**；外加升级路径断言（旧布局必须清掉、用户文件必须保留）。双向验证过 —— 模拟退回旧布局，两条断言都会失败
+
+`verify-release.sh` 90 → **101 pass**。
+
+### 📋 四个工具，四种失效方式
+
+| 工具 | 错法 | 后果 |
+|---|---|---|
+| Hermes（v1.7.9 已修） | 装到不被读的目录 | 完全不生效 |
+| Aider | 检测标记不存在 + 断言文件会自动加载 | 检测不到 + 装了不生效 |
+| Kiro | 正文放进每轮常驻的目录 | 每轮烧 335 KB |
+| Qoder | 映射表照着别家约定编 | 用户按错的工具名调用 |
+
+**四个都是我们自己那层写的，四个都没查官方文档。** 这已经不是个案。剩余工具的核查还在继续，会在后续版本陆续修。
+
+### ✅ 发版前门禁
+
+- `audit.sh` 166 pass / 0 warn / 0 fail
+- `verify-release.sh` 101 pass / 0 fail
+
+---
+
+## v1.7.9 (2026-08-11)
+
+**如果你在用 Hermes Agent，请重新安装。** 本版本之前我们对 Hermes 的支持是**坏的** —— 不是"不好用"，是装完完全不生效。
+
+### 🐛 Hermes：我们一直装错了目录（[#45](https://github.com/jnMetaCode/superpowers-zh/issues/45)）
+
+报告人说「项目级 `.hermes/skills/` 里的 20 个 skill 全部返回 404，必须手动复制到 `~/.hermes/skills/` 才被识别」。查[官方文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills)核实，他是对的：
+
+> Hermes 只自动加载 `~/.hermes/skills/`（原文称其为 "the primary directory and source of truth"），**项目级目录不会被自动发现**；外部目录必须写进 `~/.hermes/config.yaml` 的 `skills.external_dirs`。
+
+而我们从支持 Hermes 起就只装项目级 `.hermes/skills/` —— **那个目录 Hermes 根本不读**。装了 20 个 skill，一个都不生效，比不支持更糟：用户以为装好了。
+
+**改法：**
+
+- **全局成为推荐装法** —— `npx superpowers-zh --global --tool hermes` 装到 `~/.hermes/skills/`，装完即生效，`skills_list` 直接能看到 20 个 skill
+- **项目级保留**（skills 可以随仓库分发），但装完打印**可直接粘贴**的配置片段，带绝对路径：
+
+  ```yaml
+  skills:
+    external_dirs:
+      - /your/project/.hermes/skills
+  ```
+
+  **我们不替你改 `config.yaml`** —— 那是你的文件。文档里特意写明「配置里不存在的路径会被静默跳过」，所以写错不会报错、只会"没生效"，这个坑值得先说。
+
+**过程中拦住了一次自己猜路径：** 第一版全局实现把 `HERMES.md` 引导文件写到了 `$HOME` 根目录。Hermes 的用户级指令文件约定**没有公开文档** —— 那是在猜路径 + 污染用户主目录。已改为全局模式不写 bootstrap，并在文档里说明理由。实测：全局装完 `$HOME` 根目录 0 个新文件、卸载 0 残留。
+
+### 🔧 发版工具：`bump-version.sh` 缺 jq 时会静默改错
+
+本次发版时踩到：机器上没有 `jq`，脚本不报错退出，而是每个文件打一行 `command not found` 后**继续往下跑**，最后以 `unbound variable` 收场 —— 版本号一个都没写进去，但输出里混着 "Done."。已加前置检查：缺 `jq` 直接退出并给出安装命令。
+
+### ℹ️ #45 的后半部分未动（说明理由）
+
+#45 还提到 7 个 skill 文件里有 24 处硬编码的 Claude 工具名（`TodoWrite` / `Read` / `Bash` 等）。**本次不动**，理由：那属于行为塑造内容，且 `references/hermes-tools.md` 已有完整映射表。正确解法是强化「查映射表」的引用，而不是把正文改成某个 harness 专属的工具名 —— 那会伤到其余 22 款工具。
+
+### ✅ 发版前门禁
+
+- `audit.sh` 166 pass / 0 warn / 0 fail
+- `verify-release.sh` 90 pass / 0 fail（`--global` 支持清单 6 → 7 款，新增 hermes）
+
+---
+
 ## v1.7.8 (2026-08-08)
 
 本版本源于一次**定位核查**：按「superpowers-zh 只是完整翻译上游 + 增加更多工具支持」这个定位，逐层比对我们与 [obra/superpowers](https://github.com/obra/superpowers) 的差异。结论是**定位基本站得住，但不完全** —— 查出 5 处偏离，全部修掉。

package/bin/superpowers-zh.js

@@ -51,7 +51,7 @@ const LEGACY_AGENT_FILENAMES = ['code-reviewer.md'];
 //   global.dir     用户级 skills 目录（相对 home）
 //   global.detect  home 下用于自动检测该工具是否安装的标记目录
 //   global.boot    可选，用户级 bootstrap 文件（相对 home）；无则仅靠 skill 自动发现
-// 无 global 的工具（Cursor/Kiro/Trae/Aider/DeerFlow/VS Code/Hermes/Claw/Cline/Kilo Code）规则是项目级、
+// 无 global 的工具（Cursor/Kiro/Trae/Aider/DeerFlow/VS Code/Claw/Cline/Kilo Code）规则是项目级、
 // 或存在于应用内设置，没有稳定的用户级 skills 加载路径 —— --global 会明确拒绝而非写无效路径。
 const TARGETS = [
   { name: 'Claude Code',   dir: '.claude/skills',           detect: '.claude',                        global: { dir: '.claude/skills',         detect: '.claude',         boot: '.claude/CLAUDE.md' } },
@@ -59,7 +59,15 @@ const TARGETS = [
   // Codex 全局：docs 确认 Codex 启动时扫描 ~/.agents/skills/（不是 ~/.codex/skills），
   // 直接把每个 skill 复制到 ~/.agents/skills/<skill>/ 正好命中它的扁平扫描。
   { name: 'Codex CLI',     dir: '.codex/skills',            detect: '.codex',                         global: { dir: '.agents/skills',         detect: '.codex' } },
-  { name: 'Kiro',          dir: '.kiro/steering',            detect: '.kiro' },
+  // Kiro 的 steering 与 Cline / Kilo 的 rules 同性质：**每轮常驻**。官方文档
+  // （kiro.dev/docs/steering）明确 `.kiro/steering/` 下的文件默认 inclusion: always，
+  // "loaded into every Kiro interaction automatically"。
+  // v1.7.9 及更早把 20 个 skill 整个装进 .kiro/steering/ —— 实测 47 个 md、335 KB，
+  // 每一轮全量进上下文。改为与 Cline / Kilo 同一套：skills 放 .kiro/skills/（不被
+  // 自动加载），只在 steering 里放一份带 inclusion: always 的小索引。
+  // 注意 Kiro 的 frontmatter 键是 inclusion / fileMatchPattern，不是 Cursor 系的
+  // alwaysApply / globs —— 我们旧文档写错过，见 docs/README.kiro.md。
+  { name: 'Kiro',          dir: '.kiro/skills',              detect: '.kiro' },
   { name: 'DeerFlow',      dir: 'skills/custom',             detect: 'deer_flow' },
   { name: 'Trae',          dir: '.trae/skills',              detect: '.trae' },
   // Antigravity 无 global：其全局 skills 加载路径未在 docs 证实（全局规则走 ~/.gemini/GEMINI.md），
@@ -71,10 +79,21 @@ const TARGETS = [
   // Gemini 无 global：其全局加载是「扩展目录」~/.gemini/extensions/*/skills/ + gemini-extension.json，
   // 不是简单复制到 ~/.gemini/skills，通用 --global 覆盖不了。见 docs/README.gemini-cli.md。
   { name: 'Gemini CLI',    dir: '.gemini/skills',            detect: 'GEMINI.md' },
-  { name: 'Aider',         dir: '.aider/skills',             detect: '.aider' },
+  // Aider 两点都跟直觉相反，都是实测确认的：
+  // 1) Aider 不创建 `.aider/` 目录，它在项目根留下的是 `.aider.` 前缀的产物
+  //    （.aider.conf.yml / .aider.chat.history.md / .aider.tags.cache.v3/）。
+  //    原来 detect 写 '.aider' 永远匹配不上 —— 真实 Aider 项目从来没被自动检测到过。
+  // 2) CONVENTIONS.md **不会**被 Aider 自动加载。官方文档（aider.chat/docs/usage/
+  //    conventions.html）明确要 `aider --read CONVENTIONS.md` 或在 .aider.conf.yml
+  //    写 `read: CONVENTIONS.md`。所以装完必须打印激活方式，否则又是「装了不生效」。
+  { name: 'Aider',         dir: '.aider/skills',             detect: ['.aider.conf.yml', '.aider.chat.history.md', '.aider.tags.cache.v3', '.aider'] },
   { name: 'OpenCode',      dir: '.opencode/skills',          detect: '.opencode',                      global: { dir: '.config/opencode/skills', detect: '.config/opencode' } },
   { name: 'Qwen Code',     dir: '.qwen/skills',             detect: '.qwen',                           global: { dir: '.qwen/skills',           detect: '.qwen' } },
-  { name: 'Hermes Agent',  dir: '.hermes/skills',            detect: ['.hermes', 'HERMES.md', '.hermes.md'] },
+  // Hermes 官方文档：只自动加载 ~/.hermes/skills/（"the primary directory and
+  // source of truth"），项目级目录不被自动发现，外部目录必须写进
+  // ~/.hermes/config.yaml 的 skills.external_dirs。所以全局才是能直接生效的装法；
+  // 项目级仍保留（便于随仓库分发），但装完会打印需要粘贴的 config.yaml 片段。
+  { name: 'Hermes Agent',  dir: '.hermes/skills',            detect: ['.hermes', 'HERMES.md', '.hermes.md'], global: { dir: '.hermes/skills',         detect: '.hermes' } },
   { name: 'Claw Code',     dir: '.claw/skills',              detect: ['.claw', 'CLAW.md'] },
   { name: 'Qoder',         dir: '.qoder/skills',             detect: '.qoder',                         global: { dir: '.qoder/skills',          detect: '.qoder' } },
   { name: 'CodeBuddy',     dir: '.codebuddy/skills',         detect: ['.codebuddy', 'CODEBUDDY.md'] },
@@ -218,6 +237,68 @@ ${skillTable}
   console.log(`  ✅ Cline: bootstrap rule -> ${rulePath}`);
 }
 
+// Kiro：steering 每轮常驻，所以这里只放索引，skill 正文放 .kiro/skills/ 按需读取。
+// frontmatter 用 Kiro 自己的 inclusion: always（不是 Cursor 系的 alwaysApply）。
+function generateKiroSteeringIndex(projectDir) {
+  const steeringDir = resolve(projectDir, '.kiro', 'steering');
+  mkdirSync(steeringDir, { recursive: true });
+
+  const skillEntries = scanSkillEntries(SKILLS_SRC);
+
+  // 先清掉旧布局：v1.7.9 及更早把 skill 正文装在 .kiro/steering/<skill>/。
+  // 升级的人通常直接重装而不会先卸载，不清的话新旧两份并存，335 KB 的常驻开销
+  // 一点没减 —— 这才是本次要修的东西。只删我们自己装过的那些 skill 同名目录。
+  const ourSkillNames = new Set(skillEntries.map(s => s.name));
+  let legacyRemoved = 0;
+  for (const entry of readdirSync(steeringDir, { withFileTypes: true })) {
+    if (entry.isDirectory() && ourSkillNames.has(entry.name)) {
+      rmSync(resolve(steeringDir, entry.name), { recursive: true, force: true });
+      legacyRemoved++;
+    }
+  }
+  if (legacyRemoved > 0) {
+    console.log(`  🧹 Kiro: 清理旧布局 ${legacyRemoved} 个 skill 目录 <- .kiro/steering/`);
+    console.log(`     （旧版把正文放在这里，而 steering 每轮常驻，会一直进 prompt）`);
+  }
+  const skillTable = skillEntries.map(s => `| ${s.name} | ${s.desc} |`).join('\n');
+
+  const rule = `---
+inclusion: always
+---
+
+# Superpowers-ZH 中文增强版
+
+你已加载 superpowers-zh 技能框架（${skillEntries.length} 个 skills）。
+
+## 核心规则
+
+1. **收到任务时，先检查是否有匹配的 skill** — 哪怕只有 1% 的可能性也要检查
+2. **设计先于编码** — 收到功能需求时，先用 brainstorming skill 做需求分析
+3. **测试先于实现** — 写代码前先写测试（TDD）
+4. **验证先于完成** — 声称完成前必须运行验证命令
+
+## 可用 Skills
+
+Skills 位于 \`.kiro/skills/\` 目录，每个 skill 有独立的 \`SKILL.md\` 文件。
+
+| Skill | 触发条件 |
+|-------|---------|
+${skillTable}
+
+## 如何使用
+
+当任务匹配某个 skill 的触发条件时，用读文件工具打开对应的
+\`.kiro/skills/<skill-name>/SKILL.md\`，并严格遵循其流程。
+
+**不要**把 skill 正文复制到本文件 —— \`.kiro/steering/\` 里的内容每轮都进 prompt，
+按需读取才能把常驻开销控制在这张索引表。
+`;
+
+  const rulePath = resolve(steeringDir, 'superpowers-zh.md');
+  writeFileSync(rulePath, rule, 'utf8');
+  console.log(`  ✅ Kiro: steering 索引 -> ${rulePath}`);
+}
+
 // Kilo Code：v7 起官方推荐 .kilo/rules/ + 在 kilo.jsonc 的 instructions 数组里显式登记，
 // 但那要改用户的 kilo.jsonc（JSONC 带注释，安全合并困难，且属于侵入用户配置）。
 // 官方同时明确 `.kilocode/rules/` 向后兼容且无需配置即生效，故走这条：零配置改动。
@@ -369,7 +450,8 @@ ${skillList}
 当任务匹配某个 skill 时，读取对应的 \`.aider/skills/<skill-name>/SKILL.md\` 并严格遵循其流程。
 `;
 
-  // 写入 CONVENTIONS.md（Aider 原生支持自动加载此文件）
+  // 写入 CONVENTIONS.md。注意：Aider **不会**自动加载这个文件（见 TARGETS 里的
+  // Aider 注释），所以写完必须告诉用户怎么激活，否则装了等于没装。
   // 如果已有 CONVENTIONS.md，追加而不覆盖
   const convPath = resolve(projectDir, 'CONVENTIONS.md');
   if (existsSync(convPath)) {
@@ -384,6 +466,18 @@ ${skillList}
     writeFileSync(convPath, wrapWithSentinel(content), 'utf8');
     console.log(`  ✅ Aider: bootstrap -> ${convPath}`);
   }
+
+  // 激活提示。不替用户改 .aider.conf.yml —— 那是他们的配置文件。
+  console.log('');
+  console.log('  ⚠️  Aider 不会自动加载 CONVENTIONS.md，还需一步才生效：');
+  console.log('');
+  console.log('     每次启动时带上：');
+  console.log('        aider --read CONVENTIONS.md');
+  console.log('');
+  console.log('     或写进 .aider.conf.yml 一劳永逸：');
+  console.log('');
+  console.log('        read: CONVENTIONS.md');
+  console.log('');
 }
 
 function generateGeminiBootstrap(baseDir, isGlobal) {
@@ -431,7 +525,17 @@ ${skillList}
   }
 }
 
-function generateHermesBootstrap(projectDir) {
+function generateHermesBootstrap(projectDir, isGlobal) {
+  // 全局模式不写 bootstrap：Hermes 的用户级指令文件约定未在 docs 证实，
+  // 往 $HOME 根目录写 HERMES.md 是猜路径 + 污染主目录。~/.hermes/skills/ 里的
+  // skill 靠 name/description 被 skills_list / skill_view 发现，本就不依赖 bootstrap。
+  if (isGlobal) {
+    console.log('  ℹ️  Hermes 全局安装不写 bootstrap 文件（其用户级指令文件约定未证实）。');
+    console.log('     skills 已在 ~/.hermes/skills/，可用 skills_list / skill_view 发现。');
+    console.log('     想让它在项目里自动触发，在该项目跑一次项目级安装以生成 HERMES.md。');
+    return;
+  }
+
   const skillEntries = scanSkillEntries(SKILLS_SRC);
   const skillList = skillEntries.map(s => `- **${s.name}**: ${s.desc}`).join('\n');
 
@@ -485,6 +589,25 @@ ${skillList}
     writeFileSync(hermesPath, wrapWithSentinel(content), 'utf8');
     console.log(`  ✅ Hermes Agent: bootstrap -> ${hermesPath}`);
   }
+
+  // 项目级安装 Hermes 认不到 —— 必须显式登记到 config.yaml。不替用户改配置
+  // （那是他们的文件），改为打印可直接粘贴的片段。见 issue #45。
+  if (!isGlobal) {
+    const abs = resolve(projectDir, '.hermes', 'skills');
+    console.log('');
+    console.log('  ⚠️  Hermes 只自动扫描 ~/.hermes/skills/，不会发现项目级目录。');
+    console.log('     二选一让它生效：');
+    console.log('');
+    console.log('     A) 改用全局安装（推荐，装完即生效）：');
+    console.log('        npx superpowers-zh --global --tool hermes');
+    console.log('');
+    console.log('     B) 保留项目级，把这段加进 ~/.hermes/config.yaml：');
+    console.log('');
+    console.log('        skills:');
+    console.log('          external_dirs:');
+    console.log(`            - ${abs}`);
+    console.log('');
+  }
 }
 
 function generateClaudeCodeBootstrap(baseDir, isGlobal) {
@@ -732,7 +855,7 @@ function installForTarget(target, baseDir, isGlobal) {
   }
 
   if (target.name === 'Hermes Agent') {
-    generateHermesBootstrap(baseDir);
+    generateHermesBootstrap(baseDir, isGlobal);
   }
 
   if (target.name === 'Claude Code') {
@@ -743,6 +866,10 @@ function installForTarget(target, baseDir, isGlobal) {
     generateCodeBuddyBootstrap(baseDir);
   }
 
+  if (target.name === 'Kiro') {
+    generateKiroSteeringIndex(baseDir);
+  }
+
   if (target.name === 'Cline') {
     generateClineBootstrapRule(baseDir);
   }
@@ -767,7 +894,13 @@ const BOOTSTRAP_DELETE = [
   '.agents/rules.md',
   '.clinerules/superpowers-zh.md',
   '.kilocode/rules/superpowers-zh.md',
+  '.kiro/steering/superpowers-zh.md',
 ];
+
+// v1.7.9 及更早把 skill 正文直接装进 .kiro/steering/<skill>/，而 steering 每轮常驻 ——
+// 那 335 KB 会一直进 prompt。升级的用户不会重跑旧版卸载，所以这里按老路径也清一遍，
+// 否则新旧两份并存，开销问题原样保留。
+const LEGACY_SKILL_DIRS = ['.kiro/steering'];
 const BOOTSTRAP_CLEAN_SECTION = [
   'CLAUDE.md',
   'GEMINI.md',
@@ -894,6 +1027,22 @@ function uninstall(isGlobal) {
       .map(e => e.name)
   );
 
+  // 旧布局清理：见 LEGACY_SKILL_DIRS 的说明。老用户跑新版卸载也应清干净。
+  if (!isGlobal) {
+    for (const rel of LEGACY_SKILL_DIRS) {
+      const legacyDir = resolve(baseDir, rel);
+      if (!existsSync(legacyDir)) continue;
+      let n = 0;
+      for (const entry of readdirSync(legacyDir, { withFileTypes: true })) {
+        if (entry.isDirectory() && srcSkillNames.has(entry.name)) {
+          rmSync(resolve(legacyDir, entry.name), { recursive: true, force: true });
+          n++;
+        }
+      }
+      if (n > 0) console.log(`  ✅ 清理旧布局: 移除 ${n} 个 skills <- ${legacyDir}`);
+    }
+  }
+
   const pool = isGlobal ? GLOBAL_TARGETS : TARGETS;
   let totalSkills = 0;
   for (const target of pool) {

package/docs/README.aider.md

@@ -2,42 +2,60 @@
 
 在 [Aider](https://aider.chat) 中使用 superpowers-zh 的完整指南。
 
-## 自动安装
+## ⚠️ 先看这一条：装完还需要一步才生效
+
+**Aider 不会自动加载 `CONVENTIONS.md`。** [官方文档](https://aider.chat/docs/usage/conventions.html)明确要求显式加载 —— 原文推荐 `aider --read CONVENTIONS.md`，或在配置里写 `read:` 项。
+
+所以装完之后，二选一：
 
 ```bash
-cd /your/project
-npx superpowers-zh
+# 每次启动时带上
+aider --read CONVENTIONS.md
+```
+
+```yaml
+# 或写进 .aider.conf.yml，一劳永逸
+read: CONVENTIONS.md
 ```
 
-安装脚本会自动检测 `.aider.conf.yml` 文件并将 skills 复制到 `.aider/skills/` 目录。
+**我们不替你改 `.aider.conf.yml`** —— 那是你的配置文件。安装器会在装完时把上面两条打印出来提醒你。
 
-## 手动安装
+> 📌 v1.7.9 及更早版本的文档写着「Aider 会自动读取 CONVENTIONS.md，无需额外配置」—— **那是错的**，会让你以为装好了其实没生效。这是我们的错误，v1.7.10 起更正。
+
+## 安装
 
 ```bash
-git clone https://github.com/jnMetaCode/superpowers-zh.git
-cp -r superpowers-zh/skills /your/project/.aider/skills
+cd /your/project
+npx superpowers-zh --tool aider
 ```
 
-## 通过 CONVENTIONS.md 引用
+会做两件事：
+
+1. 把 20 个 skill 复制到 `.aider/skills/`
+2. 生成（或追加）`CONVENTIONS.md`，里面是 skill 索引和触发规则，指向 `.aider/skills/<name>/SKILL.md`
 
-Aider 原生支持 `CONVENTIONS.md` 文件。在其中引用 skills：
+### 关于自动检测
 
-```markdown
-# 项目约定
+不带 `--tool` 时安装器会扫描项目里的工具标记。**Aider 不创建 `.aider/` 目录** —— 它在项目根留下的是 `.aider.` 前缀的产物，所以我们认这几个：
 
-## 工作方法论
+- `.aider.conf.yml`
+- `.aider.chat.history.md`
+- `.aider.tags.cache.v3/`
 
-本项目使用 superpowers-zh skills 作为工作方法论。
-Skills 位于 `.aider/skills/` 目录，每个子目录的 SKILL.md 定义一个工作流。
+> 📌 v1.7.9 及更早只认 `.aider/` 这个目录，而 Aider 从不创建它 —— 也就是说**真实的 Aider 项目从来没被自动检测到过**，必须手动 `--tool aider`。同样在 v1.7.10 修正。
 
-- 新功能开发：先使用 brainstorming skill
-- 编写代码：遵循 test-driven-development skill
-- 调试问题：使用 systematic-debugging skill
+## 手动安装
+
+```bash
+git clone https://github.com/jnMetaCode/superpowers-zh.git
+cp -r superpowers-zh/skills /your/project/.aider/skills
 ```
 
-## 通过 .aider.conf.yml 配置
+> 手动复制不会生成 `CONVENTIONS.md`，你需要自己写一份索引并按上面的方式加载它。建议优先用 `npx superpowers-zh --tool aider`。
 
-在 `.aider.conf.yml` 中添加 read 配置来加载 skills：
+## 只加载部分 skill
+
+`CONVENTIONS.md` 是一份索引（约 4 KB），由 Aider 常驻上下文，正文按需读取。如果你只想常驻少数几个 skill 的全文，也可以直接点名：
 
 ```yaml
 read:
@@ -46,16 +64,37 @@ read:
   - .aider/skills/systematic-debugging/SKILL.md
 ```
 
+注意每个 SKILL.md 都会完整进入上下文，装 20 个的全文开销很大 —— 这正是我们默认走索引式 `CONVENTIONS.md` 的原因。
+
 ## 故障排查
 
 ### Skills 未生效
 
-1. 确认 `.aider/skills/` 目录存在且包含 skill 文件夹
-2. 确保在 `CONVENTIONS.md` 或 `.aider.conf.yml` 中引用了 skills
-3. Aider 会自动读取 `CONVENTIONS.md`，无需额外配置
+按顺序查：
+
+1. **`CONVENTIONS.md` 被加载了吗？** 这是最常见的原因。Aider 启动后用 `/read` 看已加载的只读文件里有没有它。没有的话，回到本文开头那一步。
+2. `.aider/skills/` 目录是否存在且包含 skill 子目录。
+3. 如果用 `.aider.conf.yml` 的 `read:` 配置：确认 Aider 读的是你以为的那份配置。Aider 会依次找 home 目录、git 仓库根、当前目录下的 `.aider.conf.yml`。
+
+### 装完没看到激活提示
+
+说明你用的是旧版本。升级：
+
+```bash
+npx superpowers-zh@latest --tool aider
+```
+
+## 卸载
+
+```bash
+npx superpowers-zh --uninstall
+```
+
+会删除 `.aider/skills/` 下装过的 skill，并从 `CONVENTIONS.md` 中精确切除 superpowers-zh 段（保留你自己写的内容）。`.aider.conf.yml` 我们没动过，所以也不会去改 —— 如果你加过 `read: CONVENTIONS.md`，需要自己删。
 
 ## 获取帮助
 
 - 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
 - 项目主页：https://github.com/jnMetaCode/superpowers-zh
 - Aider 文档：https://aider.chat/docs/
+- Aider conventions 文档：https://aider.chat/docs/usage/conventions.html

package/docs/README.hermes.md

@@ -2,37 +2,48 @@
 
 在 [Hermes Agent](https://github.com/NousResearch/hermes-agent) 中使用 superpowers-zh 的完整指南。
 
-## 自动安装
+## ⚠️ 先看这一条：必须装到全局，否则不生效
+
+[Hermes 官方文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills)明确：Hermes **只自动加载 `~/.hermes/skills/`**（原文称其为 "the primary directory and source of truth"），**项目级目录不会被自动发现**。
+
+所以推荐的装法是全局：
 
 ```bash
-cd /your/project
-npx superpowers-zh --tool hermes
+npx superpowers-zh --global --tool hermes
 ```
 
-安装脚本会将 20 个 skills 复制到 `.hermes/skills/` 目录，并自动生成 `HERMES.md` 引导文件（含工具映射表和 skills 列表）。
+装到 `~/.hermes/skills/`，装完即生效，用 `skills_list` 就能看到 20 个 skill。
 
-如果项目中已存在 `.hermes` 目录或 `HERMES.md` 文件，也会被自动检测到：
+> 📌 v1.7.8 及更早版本只支持项目级安装（装到 `<项目>/.hermes/skills/`）—— 那个目录 Hermes 根本不读，等于装了不生效。这是我们的实现错误，v1.7.9 起修正。见 [#45](https://github.com/jnMetaCode/superpowers-zh/issues/45)。
+
+## 如果你确实要项目级安装
+
+项目级的好处是 skills 可以随仓库一起分发。但**必须显式登记**，否则 Hermes 看不见。
 
 ```bash
-npx superpowers-zh   # 自动检测
+cd /your/project
+npx superpowers-zh --tool hermes
 ```
 
-## 手动安装
+安装器会打印出你需要粘贴的配置片段，形如：
 
-```bash
-git clone https://github.com/jnMetaCode/superpowers-zh.git
-cp -r superpowers-zh/skills /your/project/.hermes/skills
+```yaml
+skills:
+  external_dirs:
+    - /your/project/.hermes/skills
 ```
 
-## 通过 HERMES.md 引导
+把它加进 `~/.hermes/config.yaml`。路径支持 `~` 展开和 `${VAR}` 环境变量替换；**配置里不存在的路径会被静默跳过**，所以写错了不会报错，只会"没生效"。
+
+**我们不替你改 `config.yaml`** —— 那是你的配置文件。
+
+项目级安装还会生成 `HERMES.md` 引导文件（含核心规则和 skills 列表），让 Hermes 在合适时机主动检查 skill。全局安装**不写**这个文件 —— Hermes 的用户级指令文件约定没有公开文档，我们不猜路径、也不往你的主目录里写东西。
 
-Hermes Agent 在会话开始时自动加载项目根目录下的 `HERMES.md`（或 `.hermes.md`）作为上下文。安装器会自动生成此文件，内容包括：
+## 同名冲突
 
-- 工具映射表（Claude Code → Hermes Agent 工具名称）
-- 所有可用 skills 的列表和描述
-- 核心规则和使用说明
+如果同一个 skill 名在 `~/.hermes/skills/` 和某个 `external_dirs` 目录里都存在，**本地（`~/.hermes/skills/`）的版本优先**。
 
-## 通过 config.yaml 配置外部 skills 目录
+## 其他 config.yaml 用法
 
 如果希望全局使用 superpowers-zh skills，可以在 `~/.hermes/config.yaml` 中配置：
 

package/docs/README.kiro.md

@@ -2,68 +2,100 @@
 
 在 [Kiro](https://kiro.dev)（Amazon AI IDE）中使用 superpowers-zh 的完整指南。
 
-## 快速安装
+## ⚠️ v1.7.9 及更早版本请重新安装
+
+旧版把 20 个 skill 的**正文**直接装进了 `.kiro/steering/`。而 [Kiro 官方文档](https://kiro.dev/docs/steering/)明确：`.kiro/steering/` 下的文件默认 `inclusion: always`，会被 "loaded into every Kiro interaction automatically"。
+
+实测那个布局是 **47 个 md、335 KB，每一轮对话全量进上下文**。不是不能用，是每轮都在烧 token。
+
+v1.7.10 起改成索引式：**4.4 KB**（76 倍差距）。重装即可，安装器会自动清掉旧布局：
 
 ```bash
 cd /your/project
-npx superpowers-zh
+npx superpowers-zh@latest --tool kiro
 ```
 
-安装脚本会自动检测 `.kiro/` 目录并将 skills 复制到 `.kiro/steering/`。
+会看到：
 
-## 手动安装
+```
+🧹 Kiro: 清理旧布局 20 个 skill 目录 <- .kiro/steering/
+✅ Kiro: steering 索引 -> .kiro/steering/superpowers-zh.md
+```
+
+**你自己写的 steering 文件不会被动** —— 只清理与我们 skill 同名的那些目录。
+
+## 快速安装
 
 ```bash
-git clone https://github.com/jnMetaCode/superpowers-zh.git
-cp -r superpowers-zh/skills/* /your/project/.kiro/steering/
+cd /your/project
+npx superpowers-zh --tool kiro
 ```
 
+装两样东西：
+
+| 位置 | 内容 | 是否每轮常驻 |
+|---|---|---|
+| `.kiro/steering/superpowers-zh.md` | 索引：核心规则 + 20 个 skill 的触发条件表（约 4.4 KB） | **是**（`inclusion: always`） |
+| `.kiro/skills/<name>/SKILL.md` | skill 正文 | 否，按需读取 |
+
 ## 工作原理
 
-Kiro 使用 **Steering** 机制管理 AI 行为规则：
+Kiro 用 **Steering** 机制管理 AI 行为规则。关键的三件事：
 
-- **目录**：`.kiro/steering/`
-- **格式**：Markdown + YAML frontmatter
-- **加载模式**：
-  - `alwaysApply: true` — 每次对话自动加载
-  - `globs: "*.ts"` — 匹配特定文件时加载
-  - 手动引用 — 在聊天中输入 `#steering-file-name`
+- **目录**：`.kiro/steering/`（项目级）、`~/.kiro/steering/`（全局）
+- **默认行为**：**没写 `inclusion` 的文件默认就是 always** —— 每次交互自动加载
+- **frontmatter 键**（这是 Kiro 自己的，别和 Cursor 系搞混）：
 
-### Skills 与 Steering 的对应
+  | 键 | 含义 |
+  |---|---|
+  | `inclusion: always` | 每次交互都加载（**默认值**） |
+  | `inclusion: fileMatch` + `fileMatchPattern` | 匹配特定文件时加载 |
+  | `inclusion: manual` | 仅在聊天里用 `#steering-file-name` 引用时加载 |
+  | `inclusion: auto` | 按 `description` 与请求匹配时自动加载 |
 
-superpowers-zh 的 SKILL.md 文件格式与 Kiro Steering 文件兼容（都是 Markdown + YAML frontmatter）。安装后，Kiro 会自动识别并加载 skills。
+> 📌 v1.7.9 及更早的本文档写着加载模式是 `alwaysApply: true` 和 `globs: "*.ts"` —— **这两个键 Kiro 文档里根本不存在**，是 Cursor / Trae 的约定被误写成了 Kiro 的。已更正。
 
-### 推荐配置
+### 为什么正文不放 steering 里
 
-在 `.kiro/steering/` 中创建 `superpowers.md`：
+因为 steering 是常驻开销。这跟我们对 Cline、Kilo Code 的处理是同一个道理：**常驻的位置只放索引，正文按需读取。**
 
-```markdown
----
-description: 加载 superpowers skills 框架
-alwaysApply: true
----
+索引里明确告诉 Kiro：任务匹配某个 skill 时，去读 `.kiro/skills/<skill-name>/SKILL.md` 并遵循其流程。
 
-使用 .kiro/steering/ 目录下的 superpowers skills 来指导工作流程。
-优先使用 brainstorming（头脑风暴）开始新任务。
+## 手动安装
+
+```bash
+git clone https://github.com/jnMetaCode/superpowers-zh.git
+mkdir -p /your/project/.kiro/skills
+cp -r superpowers-zh/skills/* /your/project/.kiro/skills/
 ```
 
+> 手动复制不会生成 `.kiro/steering/superpowers-zh.md` 索引，Kiro 不会知道这些 skill 的存在，你需要自己写一份索引。建议优先用 `npx superpowers-zh --tool kiro`。
+>
+> **不要**把正文直接拷进 `.kiro/steering/` —— 那正是本次修掉的问题。
+
 ## 使用
 
-在 Kiro 中，你可以：
-- 直接提到 skill 名称：「使用头脑风暴来分析这个需求」
-- 手动引用：在聊天中输入 `#brainstorming`
-- Skills 会根据任务类型自动激活
+装好重启 Kiro 后：
 
-## 更新
+- 直接描述任务即可，索引会引导它去匹配 skill：「帮我加一个导出功能」应触发 brainstorming
+- 也可以点名：「用 brainstorming 分析这个需求」
+- 手动引用索引本身：在聊天里输入 `#superpowers-zh`
+
+## 卸载
 
 ```bash
-cd /your/project
-npx superpowers-zh
+npx superpowers-zh --uninstall
 ```
 
-重新运行安装命令即可更新到最新版本。
+会删除 `.kiro/skills/` 下装过的 skill 和 `.kiro/steering/superpowers-zh.md`，并顺带清理旧布局残留。你自己的 steering 文件保留。
+
+## 更新
+
+```bash
+npx superpowers-zh@latest --tool kiro
+```
 
 ## 获取帮助
 
 - 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
-- Kiro 文档：https://kiro.dev/docs/steering/
+- Kiro Steering 文档：https://kiro.dev/docs/steering/

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers-zh",
   "description": "AI 编程超能力中文版 — TDD、调试、代码审查等经过实战验证的工作方法论",
-  "version": "1.7.8",
+  "version": "1.7.10",
   "contextFileName": "GEMINI.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers-zh",
-  "version": "1.7.8",
+  "version": "1.7.10",
   "engines": {
     "node": ">=20.0.0"
   },

package/skills/using-superpowers/references/qoder-tools.md

@@ -16,14 +16,23 @@ Skills 使用 Claude Code 的工具名称。Qoder（阿里 AI IDE）大部分工
 
 ## Task 子 Agent 类型
 
-| Claude Code Agent | Qoder 等价 |
-|------------------|-----------|
-| `general-purpose` | `general-purpose` |
-| `Explore` | `explore-agent` |
-| `Plan` | `plan-agent` |
-| `claude-code-guide` | `qoder-guide` |
-
-Qoder 额外有 `browser-agent`、`code-reviewer`、`design-agent` 等专用 agent，依任务匹配选用。
+> **适用范围：Qoder CLI。** 下表逐条核对自 [Qoder 官方文档 · 子代理](https://docs.qoder.com/zh/cli/subagent)（核对于 2026-08）。
+> **Qoder IDE 的内置 subagent 集合与此不同，我们尚未核实** —— 见下方「IDE 与 CLI 的差异」。
+
+| Claude Code Agent | Qoder CLI 等价 | 说明 |
+|------------------|---------------|------|
+| `general-purpose` | `general-purpose` | 通用研究型，适合复杂搜索、多文件分析、调用链追踪、多步骤任务 |
+| `Explore` | `Explore` | 同名。只读代码探索 |
+| `Plan` | `Plan` | 同名。只读设计与规划 |
+| `claude-code-guide` | `qoder-guide` | 非 SDK 模式下可用 |
+
+文档另列出 `statusline-setup`（TUI 模式）。**没有内置的 `code-reviewer`** —— 文档里出现的 `api-reviewer` 是用户自建 subagent 的示例，不是内置项。需要专职审查者时，用 `general-purpose` 配 `superpowers:requesting-code-review` 的 `code-reviewer.md` 模板。
+
+### IDE 与 CLI 的差异
+
+[#119](https://github.com/jnMetaCode/superpowers-zh/issues/119) 报告：在 **Qoder IDE** 里跑 `subagent-driven-development` 时，Qoder 说它只提供 `CodeReview` subagent、**没有** `general-purpose`，于是自行降级为「控制者直接实现 + CodeReview agent 做审查」。
+
+官方 subagent 文档只覆盖 CLI，没有说这套内置集合同样适用于 IDE。**所以上表在 Qoder IDE 上不保证成立。** 如果你在 IDE 里遇到「找不到 general-purpose」，那是预期内的差异，不是 superpowers-zh 装错了 —— Qoder 的自动降级本身是合理适配。
 
 ## Quest MCP 工具（Qoder 原生）