superpowers-zh 1.7.0 → 1.7.2

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）规则是项目级、
+// 无 global 的工具（Cursor/Kiro/Trae/Aider/DeerFlow/VS Code/Hermes/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' } },
@@ -82,6 +82,13 @@ const TARGETS = [
   // 仅 skills-only —— 其 bootstrap/指令文件约定未证实，靠 CodeArts 自身 skill 发现；
   // 若不自动触发需在对话里手动点名 skill（docs 已说明）。
   { name: 'CodeArts',      dir: '.codeartsdoer/skills',      detect: '.codeartsdoer' },
+  // Cline / Kilo Code 是 VS Code 扩展，加载的是「rules」而非 skills，且 rules 每轮常驻
+  // system prompt。因此 skills 放各自的 skills/ 目录（不被自动加载），只在 rules 目录里
+  // 放一份小索引 —— 见 generateClineBootstrapRule / generateKiloCodeBootstrapRule。
+  // 均无 global：Cline 全局 rules 在 ~/Documents/Cline/Rules（随 OS 变，Linux/WSL 还有
+  // ~/Cline/Rules 回退），不是通用 --global 能可靠覆盖的路径；Kilo 全局需改 kilo.jsonc。
+  { name: 'Cline',         dir: '.cline/skills',             detect: '.clinerules' },
+  { name: 'Kilo Code',     dir: '.kilocode/skills',          detect: ['.kilocode', '.kilo', 'kilo.jsonc'] },
 ];
 
 function countDirs(dir) {
@@ -160,6 +167,95 @@ ${skillTable}
   console.log(`  ✅ Trae: bootstrap rule -> ${rulePath}`);
 }
 
+// Cline：`.clinerules/` 下所有 .md / .txt 都会被合并进 system prompt（docs.cline.bot
+// /customization/cline-rules 明确），是常驻开销 —— 所以 20 个 SKILL.md 绝不能放进去，
+// 只放一份小的索引 rule，skills 本体放 .cline/skills/ 由 agent 按需读。
+// 不写 YAML frontmatter：Cline 目前只支持 `paths` 一个条件字段，无 frontmatter 即始终生效。
+// 子目录是否递归扫描官方没写，因此索引 rule 保持在 .clinerules/ 根层、单文件。
+function generateClineBootstrapRule(projectDir) {
+  const rulesDir = resolve(projectDir, '.clinerules');
+  mkdirSync(rulesDir, { recursive: true });
+
+  const skillEntries = scanSkillEntries(SKILLS_SRC);
+  const skillTable = skillEntries.map(s => `| ${s.name} | ${s.desc} |`).join('\n');
+
+  const rule = `# Superpowers-ZH 中文增强版
+
+你已加载 superpowers-zh 技能框架（${skillEntries.length} 个 skills）。
+
+## 核心规则
+
+1. **收到任务时，先检查是否有匹配的 skill** — 哪怕只有 1% 的可能性也要检查
+2. **设计先于编码** — 收到功能需求时，先用 brainstorming skill 做需求分析
+3. **测试先于实现** — 写代码前先写测试（TDD）
+4. **验证先于完成** — 声称完成前必须运行验证命令
+
+## 可用 Skills
+
+Skills 位于 \`.cline/skills/\` 目录，每个 skill 有独立的 \`SKILL.md\` 文件。
+
+| Skill | 触发条件 |
+|-------|---------|
+${skillTable}
+
+## 如何使用
+
+当任务匹配某个 skill 的触发条件时，用读文件工具打开对应的
+\`.cline/skills/<skill-name>/SKILL.md\`，并严格遵循其流程。
+
+**不要**把 skill 正文复制到本文件 —— \`.clinerules/\` 里的内容每轮都进 prompt，
+按需读取才能把常驻开销控制在这张索引表。
+`;
+
+  const rulePath = resolve(rulesDir, 'superpowers-zh.md');
+  writeFileSync(rulePath, rule, 'utf8');
+  console.log(`  ✅ Cline: bootstrap rule -> ${rulePath}`);
+}
+
+// Kilo Code：v7 起官方推荐 .kilo/rules/ + 在 kilo.jsonc 的 instructions 数组里显式登记，
+// 但那要改用户的 kilo.jsonc（JSONC 带注释，安全合并困难，且属于侵入用户配置）。
+// 官方同时明确 `.kilocode/rules/` 向后兼容且无需配置即生效，故走这条：零配置改动。
+// 与 Cline 同理 —— rules 是常驻开销，只放索引，skills 本体放 .kilocode/skills/。
+function generateKiloCodeBootstrapRule(projectDir) {
+  const rulesDir = resolve(projectDir, '.kilocode', 'rules');
+  mkdirSync(rulesDir, { recursive: true });
+
+  const skillEntries = scanSkillEntries(SKILLS_SRC);
+  const skillTable = skillEntries.map(s => `| ${s.name} | ${s.desc} |`).join('\n');
+
+  const rule = `# Superpowers-ZH 中文增强版
+
+你已加载 superpowers-zh 技能框架（${skillEntries.length} 个 skills）。
+
+## 核心规则
+
+1. **收到任务时，先检查是否有匹配的 skill** — 哪怕只有 1% 的可能性也要检查
+2. **设计先于编码** — 收到功能需求时，先用 brainstorming skill 做需求分析
+3. **测试先于实现** — 写代码前先写测试（TDD）
+4. **验证先于完成** — 声称完成前必须运行验证命令
+
+## 可用 Skills
+
+Skills 位于 \`.kilocode/skills/\` 目录，每个 skill 有独立的 \`SKILL.md\` 文件。
+
+| Skill | 触发条件 |
+|-------|---------|
+${skillTable}
+
+## 如何使用
+
+当任务匹配某个 skill 的触发条件时，用读文件工具打开对应的
+\`.kilocode/skills/<skill-name>/SKILL.md\`，并严格遵循其流程。
+
+**不要**把 skill 正文复制到本文件 —— rules 每轮都进 prompt，按需读取才能把
+常驻开销控制在这张索引表。
+`;
+
+  const rulePath = resolve(rulesDir, 'superpowers-zh.md');
+  writeFileSync(rulePath, rule, 'utf8');
+  console.log(`  ✅ Kilo Code: bootstrap rule -> ${rulePath}`);
+}
+
 function generateQoderBootstrap(baseDir, isGlobal) {
   const rulesDir = resolve(baseDir, '.qoder', 'rules');
   mkdirSync(rulesDir, { recursive: true });
@@ -474,6 +570,43 @@ ${skillList}
   }
 }
 
+// CLI 工具的可执行文件名 —— 用于检测落空时扫 PATH 给出针对性建议（issue #48）。
+// 只列 CLI：IDE（Cursor/Trae/Qoder 等）装在应用目录里，PATH 上探不到。
+const CLI_PROBES = {
+  'Claude Code':  ['claude', 'copilot'],
+  'Codex CLI':    ['codex'],
+  'Gemini CLI':   ['gemini'],
+  'OpenCode':     ['opencode'],
+  'Aider':        ['aider'],
+  'Qwen Code':    ['qwen'],
+  'OpenClaw':     ['openclaw'],
+  'Claw Code':    ['claw'],
+  'Hermes Agent': ['hermes'],
+};
+
+// 在 PATH 里找可执行文件。只查文件是否存在，不 spawn 进程 ——
+// 绝不在用户机器上执行探测命令（既慢又有副作用风险）。
+function isOnPath(bin) {
+  const sep = process.platform === 'win32' ? ';' : ':';
+  const dirs = (process.env.PATH || '').split(sep).filter(Boolean);
+  const exts = process.platform === 'win32'
+    ? ['', ...(process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)]
+    : [''];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      try { if (existsSync(join(dir, bin + ext))) return true; } catch {}
+    }
+  }
+  return false;
+}
+
+// 反查 TARGETS.name -> 最短别名，用于给用户拼出可直接复制的 --tool 命令
+function shortestAlias(toolName) {
+  return Object.keys(TOOL_ALIASES)
+    .filter(a => TOOL_ALIASES[a] === toolName)
+    .sort((a, b) => a.length - b.length)[0];
+}
+
 // 工具名称别名映射（用户输入 -> TARGETS.name）
 const TOOL_ALIASES = {
   'claude':       'Claude Code',
@@ -511,6 +644,10 @@ const TOOL_ALIASES = {
   'codeartsdoer': 'CodeArts',
   'codearts-doer': 'CodeArts',
   'huawei':       'CodeArts',
+  'cline':        'Cline',
+  'kilocode':     'Kilo Code',
+  'kilo':         'Kilo Code',
+  'kilo-code':    'Kilo Code',
 };
 
 function showHelp() {
@@ -560,7 +697,7 @@ function installForTarget(target, baseDir, isGlobal) {
       `\n  这通常是 npx 缓存目录权限或路径问题。请尝试：\n` +
       `    1. 清理缓存后重试: npm cache clean --force && npx superpowers-zh\n` +
       `    2. 或全局安装: npm i -g superpowers-zh && superpowers-zh\n` +
-      `    3. 或手动克隆复制: 见 https://github.com/jnMetaCode/superpowers-zh#方式二手动安装`
+      `    3. 或手动克隆复制: 见 https://github.com/jnMetaCode/superpowers-zh#快速开始`
     );
   }
   const scopeTag = isGlobal ? '[全局]' : '[项目]';
@@ -597,6 +734,14 @@ function installForTarget(target, baseDir, isGlobal) {
   if (target.name === 'CodeBuddy') {
     generateCodeBuddyBootstrap(baseDir);
   }
+
+  if (target.name === 'Cline') {
+    generateClineBootstrapRule(baseDir);
+  }
+
+  if (target.name === 'Kilo Code') {
+    generateKiloCodeBootstrapRule(baseDir);
+  }
 }
 
 function isHomeDir(p) {
@@ -612,6 +757,8 @@ const BOOTSTRAP_DELETE = [
   '.trae/rules/superpowers-zh.md',
   '.qoder/rules/superpowers-zh.md',
   '.agents/rules.md',
+  '.clinerules/superpowers-zh.md',
+  '.kilocode/rules/superpowers-zh.md',
 ];
 const BOOTSTRAP_CLEAN_SECTION = [
   'CLAUDE.md',
@@ -845,7 +992,7 @@ function install(forceToolName, force, isGlobal) {
     if (isGlobal && !target.global) {
       // 部分工具（如 Gemini CLI 的扩展目录）有专属全局方式，但与通用 --global 复制机制不同，
       // 指向对应 docs；其余工具规则为项目级或存于应用内设置，无稳定用户级路径。
-      const docSlug = { 'Gemini CLI': 'gemini-cli', 'Antigravity': 'antigravity', 'Trae': 'trae', 'Aider': 'aider', 'Hermes Agent': 'hermes', 'Kiro': 'kiro' }[target.name];
+      const docSlug = { 'Gemini CLI': 'gemini-cli', 'Antigravity': 'antigravity', 'Trae': 'trae', 'Aider': 'aider', 'Hermes Agent': 'hermes', 'Kiro': 'kiro', 'Cline': 'cline', 'Kilo Code': 'kilocode' }[target.name];
       console.error(
 `  ❌ ${target.name} 不支持通用全局安装（--global）。
 
@@ -883,16 +1030,39 @@ function install(forceToolName, force, isGlobal) {
     const where = isGlobal ? '你的用户主目录(~)' : '当前目录';
     const flag = isGlobal ? '--global ' : '';
     console.log(`  ⚠️  未在${where}检测到任何已知 AI 编程工具的标记。\n`);
-    console.log('  为避免装错工具，未做任何安装。请用 --tool 显式指定你的工具，例如：\n');
-    console.log(`    npx superpowers-zh ${flag}--tool claude        # Claude Code / Copilot CLI`);
+
+    // issue #48：用户明明装了 opencode / codex，但项目里没留下标记目录（没跑过、
+    // 或配置在别处），只报「未检测到」很让人懵。扫 PATH 找已装的 CLI，直接给出
+    // 可复制的命令。注意：只提示，绝不自动安装 —— 自动装错工具正是 issue #33。
+    const onPath = Object.entries(CLI_PROBES)
+      .filter(([toolName]) => !isGlobal || pool.some(t => t.name === toolName))
+      .filter(([, bins]) => bins.some(isOnPath));
+
+    if (onPath.length) {
+      // 探到了具体工具就不再列通用示例 —— 直接给可复制的命令，别让用户在一堆
+      // 无关工具名里自己挑。
+      console.log('  不过在 PATH 里找到了这些已安装的 CLI，你要装的应该是其中之一：\n');
+      for (const [toolName] of onPath) {
+        console.log(`    npx superpowers-zh ${flag}--tool ${shortestAlias(toolName).padEnd(13)}# ${toolName}`);
+      }
+      console.log('\n  为避免装错，未自动安装 —— PATH 上装了不代表这个项目要用它。');
+      console.log('  用上面任一条命令显式指定即可。\n');
+    } else {
+      console.log('  为避免装错工具，未做任何安装。请用 --tool 显式指定你的工具，例如：\n');
+      console.log(`    npx superpowers-zh ${flag}--tool claude        # Claude Code / Copilot CLI`);
+      if (isGlobal) {
+        console.log(`    npx superpowers-zh ${flag}--tool codex         # Codex CLI`);
+        console.log(`    npx superpowers-zh ${flag}--tool qoder         # Qoder\n`);
+      } else {
+        console.log(`    npx superpowers-zh ${flag}--tool antigravity   # Google Antigravity`);
+        console.log(`    npx superpowers-zh ${flag}--tool trae          # Trae`);
+        console.log(`    npx superpowers-zh ${flag}--tool cursor        # Cursor\n`);
+      }
+    }
+
     if (isGlobal) {
-      console.log(`    npx superpowers-zh ${flag}--tool codex         # Codex CLI`);
-      console.log(`    npx superpowers-zh ${flag}--tool qoder         # Qoder\n`);
       console.log(`  支持全局安装的工具：${GLOBAL_TARGETS.map(t => t.name).join('、')}\n`);
     } else {
-      console.log(`    npx superpowers-zh ${flag}--tool antigravity   # Google Antigravity`);
-      console.log(`    npx superpowers-zh ${flag}--tool trae          # Trae`);
-      console.log(`    npx superpowers-zh ${flag}--tool cursor        # Cursor\n`);
       console.log(`  全部可用别名：${Object.keys(TOOL_ALIASES).join(', ')}\n`);
     }
     process.exit(1);

package/docs/README.cline.md

@@ -0,0 +1,78 @@
+# Superpowers 中文版 — Cline 安装指南
+
+在 [Cline](https://cline.bot)（VS Code AI 编程扩展）中使用 superpowers-zh 的完整指南。
+
+## 快速安装
+
+```bash
+cd /your/project
+npx superpowers-zh --tool cline
+```
+
+自动检测：安装脚本发现项目里有 `.clinerules/` 目录时也会自动装 Cline。**如果你还没建过 rules，就用上面的 `--tool cline` 显式指定。**
+
+装完会得到两样东西：
+
+```
+.cline/skills/            # 20 个 skill 本体，按需读取
+.clinerules/
+└── superpowers-zh.md     # 一份小索引，常驻 system prompt
+```
+
+## 工作原理（和其他工具不一样，值得读一下）
+
+Cline 没有「skills」概念，它加载的是 **Rules**：`.clinerules/` 目录下所有 `.md` / `.txt` 会被**合并进每一轮的 system prompt**。
+
+这跟 skills 的懒加载完全不同 —— 所以**绝不能把 20 个 SKILL.md 直接放进 `.clinerules/`**，那会让每轮对话都背着几万字的常驻开销，Cline 官方也提示规则超过约 300 行后遵守度会下降。
+
+superpowers-zh 的做法：
+
+| 放哪 | 内容 | 何时进 prompt |
+|------|------|--------------|
+| `.clinerules/superpowers-zh.md` | 核心规则 + 20 个 skill 的名称/触发条件索引表 | 每轮常驻（很小） |
+| `.cline/skills/<name>/SKILL.md` | skill 完整流程正文 | 仅当任务匹配、Cline 主动读取时 |
+
+索引 rule 里明确告诉 Cline：匹配到触发条件就去读对应的 `SKILL.md`，**不要**把正文抄进 rules。
+
+### 为什么不写 YAML frontmatter
+
+Cline 目前只支持 `paths`（glob 数组）一个条件字段。不写 frontmatter 就是「始终生效」，正是我们要的效果，所以索引 rule 是纯 Markdown。
+
+## 手动安装
+
+```bash
+git clone https://github.com/jnMetaCode/superpowers-zh.git
+mkdir -p /your/project/.cline/skills /your/project/.clinerules
+cp -r superpowers-zh/skills/* /your/project/.cline/skills/
+```
+
+然后在 `.clinerules/superpowers-zh.md` 里手写一份索引（内容参考 `npx` 装出来的那份）。**推荐直接用 `npx`** —— 索引表是根据 skills 的 frontmatter 自动生成的，手写容易漏。
+
+## 关于全局安装
+
+`--global` 对 Cline **不支持**。Cline 的全局 rules 目录随操作系统变化：
+
+- macOS / Linux：`~/Documents/Cline/Rules`
+- Windows：`Documents\Cline\Rules`
+- Linux / WSL 有时是 `~/Cline/Rules`
+
+没有一条稳定路径能让通用 `--global` 可靠命中，写错等于「装了不生效」，所以宁可不做。请用项目级安装。想全局用的话，把 `npx` 生成的那份 `superpowers-zh.md` 手动拷进你系统上实际的 Cline 全局 rules 目录即可。
+
+## 使用
+
+装好后新开一个 Cline 会话（rules 在会话开始时加载）。然后正常提需求即可：
+
+- 「给用户模块加个批量导出功能」→ 应当先触发 brainstorming 做需求澄清，而不是直接写代码
+- 也可以手动点名：「用 test-driven-development skill 做这个」
+
+## 更新 / 卸载
+
+```bash
+npx superpowers-zh --tool cline      # 更新（覆盖式，幂等）
+npx superpowers-zh --uninstall       # 卸载，同时清掉 .clinerules/superpowers-zh.md
+```
+
+## 获取帮助
+
+- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
+- Cline Rules 文档：https://docs.cline.bot/customization/cline-rules

package/docs/README.kilocode.md

@@ -0,0 +1,86 @@
+# Superpowers 中文版 — Kilo Code 安装指南
+
+在 [Kilo Code](https://kilo.ai)（VS Code AI 编程扩展 / CLI）中使用 superpowers-zh 的完整指南。
+
+## 快速安装
+
+```bash
+cd /your/project
+npx superpowers-zh --tool kilocode
+```
+
+自动检测：项目里存在 `.kilocode/`、`.kilo/` 或 `kilo.jsonc` 任一时会自动装 Kilo Code。
+
+装完会得到：
+
+```
+.kilocode/skills/         # 20 个 skill 本体，按需读取
+.kilocode/rules/
+└── superpowers-zh.md     # 一份小索引，自动生效
+```
+
+## 工作原理
+
+Kilo Code 加载的是 **Rules**（规则会并入 system prompt），不是懒加载的 skills。所以和 Cline 同理：**不能把 20 个 SKILL.md 直接塞进 rules 目录**，否则每轮对话都背着巨大的常驻开销。
+
+superpowers-zh 的做法：
+
+| 放哪 | 内容 | 何时进 prompt |
+|------|------|--------------|
+| `.kilocode/rules/superpowers-zh.md` | 核心规则 + 20 个 skill 的索引表 | 常驻（很小） |
+| `.kilocode/skills/<name>/SKILL.md` | skill 完整流程正文 | 仅当任务匹配、Kilo 主动读取时 |
+
+## 为什么用 `.kilocode/rules/` 而不是新版的 `kilo.jsonc`
+
+Kilo Code 从 Roo 衍生的 v5 迁到了基于 OpenCode 的 v7，配置方式变了：
+
+| | 旧（v5 及兼容路径） | 新（v7 推荐） |
+|---|---|---|
+| 规则目录 | `.kilocode/rules/` | `.kilo/rules/` |
+| 是否需要登记 | **不需要，自动生效** | **需要**，要把路径写进 `kilo.jsonc` 的 `instructions` 数组 |
+
+我们选 `.kilocode/rules/`，原因是**不改你的 `kilo.jsonc`**：
+
+1. 官方明确 `.kilocode/rules/` 向后兼容，无需任何配置即生效；
+2. `kilo.jsonc` 是带注释的 JSONC，安装脚本要安全合并它很容易把你的配置改坏；
+3. 那是你的配置文件，装个 skills 框架不该动它。
+
+### 如果你想迁到 v7 的方式
+
+手动加一行即可（把现有规则文件挪到 `.kilo/rules/` 并登记）：
+
+```jsonc
+{
+  "instructions": [".kilo/rules/superpowers-zh.md"]
+}
+```
+
+改完 `kilo.jsonc` 后**新开一个会话**才会生效。
+
+> ⚠️ 需要说明的是：`.kilocode/rules/` 的兼容性来自官方文档中「现有规则会继续工作」的表述。若你在 v7 上装完发现索引 rule 没被加载，按上面的方式迁到 `.kilo/rules/` + `kilo.jsonc`，并欢迎来 issue 里反馈，我们会据此调整默认路径。
+
+## 手动安装
+
+```bash
+git clone https://github.com/jnMetaCode/superpowers-zh.git
+mkdir -p /your/project/.kilocode/skills /your/project/.kilocode/rules
+cp -r superpowers-zh/skills/* /your/project/.kilocode/skills/
+```
+
+索引 rule 建议交给 `npx` 生成 —— 它是按 skills 的 frontmatter 自动拼的，手写容易漏。
+
+## 关于全局安装
+
+`--global` 对 Kilo Code **不支持**：它的全局规则同样要走 `kilo.jsonc` 登记，没有「复制到某个用户级目录就生效」的通用路径。请用项目级安装。
+
+## 更新 / 卸载
+
+```bash
+npx superpowers-zh --tool kilocode   # 更新（覆盖式，幂等）
+npx superpowers-zh --uninstall       # 卸载，同时清掉 .kilocode/rules/superpowers-zh.md
+```
+
+## 获取帮助
+
+- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
+- Kilo Code 自定义规则文档：https://kilo.ai/docs/customize/custom-rules

package/gemini-extension.json

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

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "superpowers-zh",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "engines": {
     "node": ">=20.0.0"
   },
-  "description": "AI 编程超能力中文增强版 — superpowers（250k+ ⭐）完整汉化 + 4 个中国原创 skills，支持 Claude Code / Copilot CLI / Hermes Agent / Cursor / Claw Code / Windsurf / Kiro / Gemini CLI / Qoder 等 20 款工具",
+  "description": "AI 编程超能力中文增强版 — superpowers（250k+ ⭐）完整汉化 + 4 个中国原创 skills，支持 Claude Code / Copilot CLI / Hermes Agent / Cursor / Claw Code / Windsurf / Kiro / Gemini CLI / Qoder 等 22 款工具",
   "type": "module",
   "main": ".opencode/plugins/superpowers.js",
   "bin": {