superpowers-zh 1.1.8 → 1.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 🌐 **简体中文** | [English (upstream)](https://github.com/obra/superpowers)
 
-> 🦸 **superpowers（116k+ ⭐）完整汉化 + 6 个中国原创 skills** — 让 Claude Code / Copilot CLI / Hermes Agent / Cursor / Windsurf / Kiro / Gemini CLI 等 **17 款 AI 编程工具**真正会干活。从头脑风暴到代码审查，从 TDD 到调试，每个 skill 都是经过实战验证的工作方法论。
+> 🦸 **superpowers（159k+ ⭐）完整汉化 + 6 个中国原创 skills** — 让 Claude Code / Copilot CLI / Hermes Agent / Cursor / Windsurf / Kiro / Gemini CLI 等 **17 款 AI 编程工具**真正会干活。从头脑风暴到代码审查，从 TDD 到调试，每个 skill 都是经过实战验证的工作方法论。
 
 Chinese community edition of [superpowers](https://github.com/obra/superpowers) — 20 skills across 16 AI coding tools, including full translations and China-specific development skills.
 
@@ -49,10 +49,33 @@ AI：在开始实现之前，我需要了解几个关键问题：
 
 ## 这是什么？
 
-[superpowers](https://github.com/obra/superpowers) 是目前最火的 AI 编程 skills 框架（116k+ stars），为 AI 编程工具提供**系统化的工作方法论**。
+[superpowers](https://github.com/obra/superpowers) 是目前最火的 AI 编程 skills 框架（159k+ stars），为 AI 编程工具提供**系统化的工作方法论**。
 
 **superpowers-zh** 在完整翻译的基础上，新增了面向中国开发者的特色 skills。
 
+### 🆚 与英文上游的区别（老被问，一次说清）
+
+| 维度 | superpowers（英文上游） | superpowers-zh（中文增强版） |
+|------|----------------------|---------------------------|
+| ⭐ Star 数 | 159k+ | — |
+| 📦 Skills 总数 | 14 | **20**（14 翻译 + 6 国产原创） |
+| 🌐 语言 | 英文 | 中文（技术术语保留英文） |
+| 🤖 **支持工具** | **6 款**：Claude Code / Cursor / Codex / OpenCode / Copilot CLI / Gemini CLI | **17 款**：上述 6 款 + Hermes Agent / Trae / Kiro / Qwen Code（通义灵码）/ OpenClaw / Claw Code / Antigravity / DeerFlow / VS Code / Windsurf / Aider |
+| ⚡ **安装方式** | 按工具分别装（每款一条不同的 plugin marketplace 命令） | **`npx superpowers-zh` 一条命令自动识别项目里的工具并安装**；识别不出可 `--tool <name>` 显式指定 |
+| 🇨🇳 Git 平台 | GitHub 为主 | GitHub + Gitee + Coding + 极狐 GitLab + **CNB（腾讯云原生构建）** |
+| 🇨🇳 CI/CD 示例 | GitHub Actions | GitHub Actions + Gitee Go + Coding CI + 极狐 CI + `.cnb.yml` |
+| 🇨🇳 代码审查风格 | 西方直接风格 | 适配国内团队沟通文化 |
+| 🇨🇳 Git 提交规范 | 无 | Conventional Commits 中文适配 |
+| 🇨🇳 中文文档规范 | 无 | 中文排版 + 中英混排规则 + 告别机翻味 |
+| ➕ MCP 服务器构建 | 无 | 独立 `mcp-builder` skill |
+| ➕ 工作流执行器 | 无 | 独立 `workflow-runner` skill（多角色 YAML 编排） |
+| 🔄 版本跟进 | 独立迭代 | **同步上游 + 国产增量叠加** |
+| 🤝 接受新 skill PR | 一般不接受（原文：*"we don't generally accept contributions of new skills"*） | 欢迎 PR（中国开发者痛点优先） |
+| 💬 社区 | Discord | 微信公众号「AI不止语」+ 微信群 + QQ 群 |
+| 📜 License | MIT | MIT |
+
+**一句话总结：** 英文上游 = 方法论内核；中文增强版 = 方法论内核 **+** 17 款工具一键适配 **+** 国内 Git/CI 生态 **+** 中文化表达习惯。
+
 ### 🤖 支持 17 款主流 AI 编程工具
 
 | 工具 | 类型 | 一键安装 | 手动安装 |
@@ -171,21 +194,6 @@ cp -r superpowers-zh/skills /your/project/.claw/skills       # Claw Code（Rust
 
 ---
 
-## 对比上游
-
-| 特性 | superpowers (英文) | superpowers-zh (中文) |
-|------|-------------------|----------------------|
-| Skills 数量 | 14 | **20**（14 翻译 + 6 原创） |
-| 语言 | 英文 | 中文（技术术语保留英文） |
-| 代码审查规范 | 西方直接风格 | 适配国内团队沟通文化 |
-| Git 平台 | GitHub 为主 | GitHub + Gitee + Coding + 极狐 |
-| Git 提交规范 | 无 | Conventional Commits 中文适配 |
-| 文档规范 | 英文 | 中文排版规范 + 中英混排 |
-| MCP 构建 | 无 | MCP 服务器构建方法论 |
-| 社区 | Discord | 微信公众号 + 微信群 |
-
----
-
 ## 贡献
 
 欢迎参与！翻译改进、新增 skills、Bug 修复都可以。
@@ -208,20 +216,44 @@ cp -r superpowers-zh/skills /your/project/.claw/skills       # Claw Code（Rust
 
 | 渠道 | 加入方式 |
 |------|---------|
-| QQ 群 | [点击加入](https://qm.qq.com/q/EeNQA9xCxy)（群号 1071280067） |
+| QQ 2群 | [点击加入](https://qm.qq.com/q/EeNQA9xCxy)（群号 1071280067） |
 | 微信群 | 关注公众号后回复「群」获取入群方式 |
 
 ---
 
+## 🌟 相关项目生态
+
+**五个项目组合使用，覆盖 AI 编程从"方法论 → 角色 → 协作 → 教程 → 安全"的完整链路。**
+
+| 项目 | 定位 | 一句话 |
+|------|------|-------|
+| **[superpowers-zh](https://github.com/jnMetaCode/superpowers-zh)**（本项目） ![](https://img.shields.io/github/stars/jnMetaCode/superpowers-zh?style=flat&label=⭐) | 🧠 工作方法论 | 20 个 skills 教 AI 怎么干活（TDD / 调试 / 代码审查等） |
+| **[agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh)** ![](https://img.shields.io/github/stars/jnMetaCode/agency-agents-zh?style=flat&label=⭐) | 🎭 专家角色库 | 211 个**即插即用** AI 专家，含 46 中国原创（小红书 / 抖音 / 飞书 / 钉钉） |
+| **[agency-orchestrator](https://github.com/jnMetaCode/agency-orchestrator)** | 🚀 编排引擎 | 一句话 → 211 专家协作，**几分钟出方案**（9 家 LLM / 6 免费） |
+| **[ai-coding-guide](https://github.com/jnMetaCode/ai-coding-guide)** | 📖 实战教程 | 66 个 Claude Code 技巧 + 9 款工具最佳实践 + 配置模板 |
+| **[shellward](https://github.com/jnMetaCode/shellward)** | 🛡️ 安全中间件 | 8 层防御 + DLP 数据流 + 注入检测，**零依赖**（含 MCP Server） |
+
+---
+
+### 🔥 重点推荐：[agency-orchestrator](https://github.com/jnMetaCode/agency-orchestrator) — 一句话调度 211 个 AI 专家协作，几分钟交付完整方案
+
+以前写个方案：你当指挥官，把 AI 轮流扮演 5 个角色，复制粘贴 10 次，1 小时没了。
+
+**现在：** 丢一句话进去 `"做一个电商退款流程"`，**产品 → 架构 → 安全 → 测试 → DBA 自动接力**，几分钟完整方案落地。
+
+- 🎭 **211+ 专家角色**（含 46 个中国市场原创：小红书 / 抖音 / 微信 / 飞书 / 钉钉）
+- 🧩 **零代码 YAML**，一行 prompt 就能跑
+- 💰 **9 家 LLM 可选**（DeepSeek / Claude / OpenAI / Ollama 等，**6 家免费**）
+- 🔗 **与 superpowers-zh 互补**：本项目管"**怎么做**"（方法论），orchestrator 管"**谁来做**"（角色协作）
+
+👉 **[立即体验 agency-orchestrator →](https://github.com/jnMetaCode/agency-orchestrator)**
+
+---
+
 ## 致谢
 
 - 原始英文版：[obra/superpowers](https://github.com/obra/superpowers)（MIT 协议）
 - 感谢 [@obra](https://github.com/obra) 创建了这个优秀的项目
-- 姊妹项目：
-  - [ai-coding-guide](https://github.com/jnMetaCode/ai-coding-guide) — AI 编程工具实战指南 — 66 个 Claude Code 技巧 + 9 款工具最佳实践 + 可复制配置模板
-  - [agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh) — 187 个专业角色，让 AI 变成安全工程师、DBA、产品经理等
-  - [agency-orchestrator](https://github.com/jnMetaCode/agency-orchestrator) — 多智能体编排引擎 — 用 YAML 编排 187 个角色协作，支持 DeepSeek/Claude/OpenAI/Ollama，零代码
-  - [shellward](https://github.com/jnMetaCode/shellward) — AI 智能体安全中间件 — 注入检测、数据防泄露、命令安全、零依赖、MCP Server
 
 ---
 

package/bin/superpowers-zh.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync, lstatSync, realpathSync } from 'fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync, lstatSync, realpathSync, rmSync } from 'fs';
 import { resolve, dirname, join } from 'path';
 import { fileURLToPath } from 'url';
+import { homedir } from 'os';
 
 // 手动递归复制：跨 Node 版本和操作系统行为一致
 // 不使用 cpSync —— 在 Windows + npx 缓存（含 junction）+ Node 16.7-18 下不稳定
@@ -14,6 +15,7 @@ function copyDirSync(src, dest) {
   mkdirSync(dest, { recursive: true });
   const entries = readdirSync(realSrc, { withFileTypes: true });
   for (const entry of entries) {
+    if (entry.name === '.DS_Store') continue;
     const srcPath = join(realSrc, entry.name);
     const destPath = join(dest, entry.name);
     let stat;
@@ -86,6 +88,15 @@ function scanSkillEntries(skillsDir) {
   return entries;
 }
 
+// 段落哨兵：v1.2.1+ 安装时把追加内容包在两条 HTML 注释之间，
+// 让卸载可以精确切除，无需依赖标题层级猜测段尾。
+const SENTINEL_BEGIN = '<!-- superpowers-zh:begin (do not edit between these markers) -->';
+const SENTINEL_END = '<!-- superpowers-zh:end -->';
+
+function wrapWithSentinel(body) {
+  return `${SENTINEL_BEGIN}\n${body.replace(/\n+$/, '')}\n${SENTINEL_END}\n`;
+}
+
 function generateTraeBootstrapRule(projectDir) {
   const rulesDir = resolve(projectDir, '.trae', 'rules');
   mkdirSync(rulesDir, { recursive: true });
@@ -190,13 +201,13 @@ ${skillList}
   if (existsSync(convPath)) {
     const existing = readFileSync(convPath, 'utf8');
     if (!existing.includes('superpowers-zh')) {
-      writeFileSync(convPath, existing + '\n\n' + content, 'utf8');
+      writeFileSync(convPath, existing.replace(/\s+$/, '') + '\n\n' + wrapWithSentinel(content), 'utf8');
       console.log(`  ✅ Aider: 追加 skills 引用 -> ${convPath}`);
     } else {
       console.log(`  ✅ Aider: CONVENTIONS.md 已包含 superpowers-zh 引用`);
     }
   } else {
-    writeFileSync(convPath, content, 'utf8');
+    writeFileSync(convPath, wrapWithSentinel(content), 'utf8');
     console.log(`  ✅ Aider: bootstrap -> ${convPath}`);
   }
 }
@@ -232,13 +243,13 @@ ${skillList}
   if (existsSync(geminiPath)) {
     const existing = readFileSync(geminiPath, 'utf8');
     if (!existing.includes('superpowers-zh')) {
-      writeFileSync(geminiPath, existing + '\n\n' + content, 'utf8');
+      writeFileSync(geminiPath, existing.replace(/\s+$/, '') + '\n\n' + wrapWithSentinel(content), 'utf8');
       console.log(`  ✅ Gemini CLI: 追加 skills 引用 -> ${geminiPath}`);
     } else {
       console.log(`  ✅ Gemini CLI: GEMINI.md 已包含 superpowers-zh 引用`);
     }
   } else {
-    writeFileSync(geminiPath, content, 'utf8');
+    writeFileSync(geminiPath, wrapWithSentinel(content), 'utf8');
     console.log(`  ✅ Gemini CLI: bootstrap -> ${geminiPath}`);
   }
 }
@@ -288,17 +299,60 @@ ${skillList}
   if (existsSync(hermesPath)) {
     const existing = readFileSync(hermesPath, 'utf8');
     if (!existing.includes('superpowers-zh')) {
-      writeFileSync(hermesPath, existing + '\n\n' + content, 'utf8');
+      writeFileSync(hermesPath, existing.replace(/\s+$/, '') + '\n\n' + wrapWithSentinel(content), 'utf8');
       console.log(`  ✅ Hermes Agent: 追加 skills 引用 -> ${hermesPath}`);
     } else {
       console.log(`  ✅ Hermes Agent: HERMES.md 已包含 superpowers-zh 引用`);
     }
   } else {
-    writeFileSync(hermesPath, content, 'utf8');
+    writeFileSync(hermesPath, wrapWithSentinel(content), 'utf8');
     console.log(`  ✅ Hermes Agent: bootstrap -> ${hermesPath}`);
   }
 }
 
+function generateClaudeCodeBootstrap(projectDir) {
+  const skillEntries = scanSkillEntries(SKILLS_SRC);
+  const skillList = skillEntries.map(s => `- **${s.name}**: ${s.desc}`).join('\n');
+
+  const content = `# Superpowers-ZH 中文增强版
+
+本项目已安装 superpowers-zh 技能框架（${skillEntries.length} 个 skills）。
+
+## 核心规则
+
+1. **收到任务时，先检查是否有匹配的 skill** — 哪怕只有 1% 的可能性也要检查
+2. **设计先于编码** — 收到功能需求时，先用 brainstorming skill 做需求分析
+3. **测试先于实现** — 写代码前先写测试（TDD）
+4. **验证先于完成** — 声称完成前必须运行验证命令
+
+## 可用 Skills
+
+Skills 位于 \`.claude/skills/\` 目录，每个 skill 有独立的 \`SKILL.md\` 文件。
+
+${skillList}
+
+## 如何使用
+
+当任务匹配某个 skill 时，使用 \`Skill\` 工具加载对应 skill 并严格遵循其流程。绝不要用 Read 工具读取 SKILL.md 文件。
+
+如果你认为哪怕只有 1% 的可能性某个 skill 适用于你正在做的事情，你必须调用该 skill 检查。
+`;
+
+  const mdPath = resolve(projectDir, 'CLAUDE.md');
+  if (existsSync(mdPath)) {
+    const existing = readFileSync(mdPath, 'utf8');
+    if (!existing.includes('superpowers-zh')) {
+      writeFileSync(mdPath, existing.replace(/\s+$/, '') + '\n\n' + wrapWithSentinel(content), 'utf8');
+      console.log(`  ✅ Claude Code: 追加 skills 引用 -> ${mdPath}`);
+    } else {
+      console.log(`  ✅ Claude Code: CLAUDE.md 已包含 superpowers-zh 引用`);
+    }
+  } else {
+    writeFileSync(mdPath, wrapWithSentinel(content), 'utf8');
+    console.log(`  ✅ Claude Code: bootstrap -> ${mdPath}`);
+  }
+}
+
 // 工具名称别名映射（用户输入 -> TARGETS.name）
 const TOOL_ALIASES = {
   'claude':       'Claude Code',
@@ -337,6 +391,8 @@ function showHelp() {
   用法：
     npx superpowers-zh                   自动检测工具并安装
     npx superpowers-zh --tool cursor     指定工具安装（检测不到时使用）
+    npx superpowers-zh --uninstall       卸载当前目录下的 superpowers-zh
+    npx superpowers-zh --force           允许在用户主目录(~)安装（默认拒绝）
     npx superpowers-zh --help            显示帮助
     npx superpowers-zh --version         显示版本
 
@@ -349,6 +405,9 @@ function showHelp() {
       npx superpowers-zh --tool cursor
       npx superpowers-zh --tool trae
 
+    误装到主目录可以这样清理：
+      cd ~ && npx superpowers-zh --uninstall
+
   项目：https://github.com/jnMetaCode/superpowers-zh
 `);
 }
@@ -358,8 +417,8 @@ function installForTarget(target) {
   const srcCount = countDirs(SKILLS_SRC);
   mkdirSync(dest, { recursive: true });
   copyDirSync(SKILLS_SRC, dest);
-  const count = countDirs(dest);
-  if (srcCount > 0 && count === 0) {
+  const totalAfter = countDirs(dest);
+  if (srcCount > 0 && totalAfter === 0) {
     throw new Error(
       `复制 skills 失败：源目录 ${SKILLS_SRC} 有 ${srcCount} 个 skill，但目标 ${dest} 为空。` +
       `\n  这通常是 npx 缓存目录权限或路径问题。请尝试：\n` +
@@ -368,7 +427,7 @@ function installForTarget(target) {
       `    3. 或手动克隆复制: 见 https://github.com/jnMetaCode/superpowers-zh#方式二手动安装`
     );
   }
-  console.log(`  ✅ ${target.name}: ${count} 个 skills -> ${dest}`);
+  console.log(`  ✅ ${target.name}: ${srcCount} 个 skills -> ${dest}`);
 
   if (target.name === 'Trae') {
     generateTraeBootstrapRule(PROJECT_DIR);
@@ -390,14 +449,197 @@ function installForTarget(target) {
     generateHermesBootstrap(PROJECT_DIR);
   }
 
-  if (target.name === 'Claude Code' && existsSync(AGENTS_SRC)) {
-    const agentsDest = resolve(PROJECT_DIR, '.claude', 'agents');
-    mkdirSync(agentsDest, { recursive: true });
-    copyDirSync(AGENTS_SRC, agentsDest);
+  if (target.name === 'Claude Code') {
+    generateClaudeCodeBootstrap(PROJECT_DIR);
+    if (existsSync(AGENTS_SRC)) {
+      const agentsDest = resolve(PROJECT_DIR, '.claude', 'agents');
+      mkdirSync(agentsDest, { recursive: true });
+      copyDirSync(AGENTS_SRC, agentsDest);
+    }
   }
 }
 
-function install(forceToolName) {
+function isHomeDir(p) {
+  const home = homedir();
+  if (!home) return false;
+  try {
+    return realpathSync(p) === realpathSync(home);
+  } catch { return resolve(p) === resolve(home); }
+}
+
+// 卸载支持：完整删除的 bootstrap 文件、需要清理段落的 bootstrap 文件
+const BOOTSTRAP_DELETE = [
+  '.trae/rules/superpowers-zh.md',
+  '.antigravity/rules.md',
+];
+const BOOTSTRAP_CLEAN_SECTION = [
+  'CLAUDE.md',
+  'GEMINI.md',
+  'HERMES.md',
+  'CONVENTIONS.md',
+];
+const BOOTSTRAP_SECTION_MARKERS = [
+  '# Superpowers-ZH 中文增强版',
+  '# Superpowers-ZH 工作方法论',
+];
+
+// v1.1.x 安装的旧 bootstrap 没有 sentinel，只能凭模板末尾固定句子识别段尾。
+// 这些短语必须出现在 superpowers 段最后一行，且足够独特不易在用户内容里重合。
+const FALLBACK_TAIL_HINTS = [
+  '你必须调用该 skill 检查。',
+  '严格遵循其流程。',
+];
+
+function writeOrDelete(filePath, head, tail) {
+  const headTrim = head.replace(/\s+$/, '');
+  const tailTrim = tail.replace(/^\s+/, '');
+  let body = headTrim;
+  if (headTrim && tailTrim) body += '\n\n' + tailTrim;
+  else body += tailTrim;
+  body = body.replace(/\s+$/, '');
+  if (body.length === 0) {
+    rmSync(filePath);
+  } else {
+    writeFileSync(filePath, body + '\n', 'utf8');
+  }
+}
+
+function cleanBootstrapSection(filePath) {
+  if (!existsSync(filePath)) return false;
+  const content = readFileSync(filePath, 'utf8');
+
+  // 1. 哨兵模式（v1.2.1+）— 精确切除
+  const sBegin = content.indexOf(SENTINEL_BEGIN);
+  if (sBegin !== -1) {
+    const sEnd = content.indexOf(SENTINEL_END, sBegin + SENTINEL_BEGIN.length);
+    if (sEnd !== -1) {
+      writeOrDelete(filePath, content.slice(0, sBegin), content.slice(sEnd + SENTINEL_END.length));
+      return true;
+    }
+  }
+
+  // 2. 标题 marker（v1.1.x 安装的）— 找下一个 \n# 一级标题做段尾
+  let idx = -1;
+  for (const marker of BOOTSTRAP_SECTION_MARKERS) {
+    const i = content.indexOf(marker);
+    if (i !== -1 && (idx === -1 || i < idx)) idx = i;
+  }
+  if (idx === -1) return false;
+
+  let end = -1;
+  const nextHeading = content.indexOf('\n# ', idx + 1);
+  if (nextHeading !== -1) end = nextHeading + 1;
+
+  // 3. 一级标题找不到 — 用末尾固定短语做兜底
+  if (end === -1) {
+    for (const hint of FALLBACK_TAIL_HINTS) {
+      const i = content.lastIndexOf(hint);
+      if (i > idx) {
+        const nl = content.indexOf('\n', i + hint.length);
+        const after = nl !== -1 ? nl + 1 : content.length;
+        if (after > end) end = after;
+      }
+    }
+  }
+
+  // 4. 都找不到 — 数据安全，跳过 + 警告
+  if (end === -1) {
+    console.warn(`  ⚠️  ${filePath}: 无法可靠识别 superpowers-zh 段尾，已跳过以避免数据丢失。`);
+    console.warn(`     请手动编辑此文件并删除以 "${BOOTSTRAP_SECTION_MARKERS[0]}" 开头的整段。`);
+    return false;
+  }
+
+  writeOrDelete(filePath, content.slice(0, idx), content.slice(end));
+  return true;
+}
+
+function uninstallForTarget(target, srcSkillNames) {
+  const dest = resolve(PROJECT_DIR, target.dir);
+  if (!existsSync(dest)) return 0;
+  let removed = 0;
+  for (const entry of readdirSync(dest, { withFileTypes: true })) {
+    if (entry.isDirectory() && srcSkillNames.has(entry.name)) {
+      rmSync(resolve(dest, entry.name), { recursive: true, force: true });
+      removed++;
+    }
+  }
+  // 如果目录已空（或仅剩 .DS_Store），顺手清掉，避免留下空骨架
+  try {
+    if (existsSync(dest)) {
+      const left = readdirSync(dest).filter(n => n !== '.DS_Store');
+      if (left.length === 0) rmSync(dest, { recursive: true, force: true });
+    }
+  } catch {}
+  return removed;
+}
+
+function uninstall() {
+  console.log(`\n  superpowers-zh v${PKG.version} — 卸载\n`);
+  console.log(`  目标项目: ${PROJECT_DIR}\n`);
+
+  if (!existsSync(SKILLS_SRC)) {
+    console.error('  ❌ 错误：skills 源目录不存在，无法识别要卸载的 skill 名单。');
+    process.exit(1);
+  }
+
+  const srcSkillNames = new Set(
+    readdirSync(SKILLS_SRC, { withFileTypes: true })
+      .filter(e => e.isDirectory())
+      .map(e => e.name)
+  );
+
+  let totalSkills = 0;
+  for (const target of TARGETS) {
+    const removed = uninstallForTarget(target, srcSkillNames);
+    if (removed > 0) {
+      console.log(`  ✅ ${target.name}: 移除 ${removed} 个 skills <- ${resolve(PROJECT_DIR, target.dir)}`);
+      totalSkills += removed;
+    }
+  }
+
+  // 顺带清理 .claude/agents 下我们装过的 agent（agents 源是平铺的文件，例如 code-reviewer.md）
+  const agentsDest = resolve(PROJECT_DIR, '.claude', 'agents');
+  if (existsSync(AGENTS_SRC) && existsSync(agentsDest)) {
+    const srcAgentNames = new Set(readdirSync(AGENTS_SRC).filter(n => n !== '.DS_Store'));
+    let agentsRemoved = 0;
+    for (const entry of readdirSync(agentsDest)) {
+      if (srcAgentNames.has(entry)) {
+        rmSync(resolve(agentsDest, entry), { recursive: true, force: true });
+        agentsRemoved++;
+      }
+    }
+    if (agentsRemoved > 0) console.log(`  ✅ Claude Code agents: 移除 ${agentsRemoved} 个 -> ${agentsDest}`);
+    try {
+      const left = readdirSync(agentsDest).filter(n => n !== '.DS_Store');
+      if (left.length === 0) rmSync(agentsDest, { recursive: true, force: true });
+    } catch {}
+  }
+
+  let bootstrapsRemoved = 0;
+  for (const rel of BOOTSTRAP_DELETE) {
+    const full = resolve(PROJECT_DIR, rel);
+    if (existsSync(full)) {
+      rmSync(full);
+      console.log(`  ✅ 删除 bootstrap: ${full}`);
+      bootstrapsRemoved++;
+    }
+  }
+  for (const rel of BOOTSTRAP_CLEAN_SECTION) {
+    const full = resolve(PROJECT_DIR, rel);
+    if (cleanBootstrapSection(full)) {
+      console.log(`  ✅ 清理 bootstrap: ${full}`);
+      bootstrapsRemoved++;
+    }
+  }
+
+  if (totalSkills === 0 && bootstrapsRemoved === 0) {
+    console.log('  ⚠️  未在当前目录找到 superpowers-zh 安装痕迹。');
+  } else {
+    console.log(`\n  卸载完成。共移除 ${totalSkills} 个 skill 目录、${bootstrapsRemoved} 个 bootstrap 文件。\n`);
+  }
+}
+
+function install(forceToolName, force) {
  try {
   console.log(`\n  superpowers-zh v${PKG.version} — AI 编程超能力中文版\n`);
 
@@ -406,6 +648,27 @@ function install(forceToolName) {
     process.exit(1);
   }
 
+  if (!force && isHomeDir(PROJECT_DIR)) {
+    console.error(
+`  ⚠️  当前目录是用户主目录: ${PROJECT_DIR}
+
+  superpowers-zh 应该装到具体项目目录，而不是 ~/。
+  在主目录安装会把 skills 和 bootstrap 文件（CLAUDE.md / HERMES.md 等）
+  写入你的 home，污染所有项目。
+
+  请先 cd 到项目目录：
+    cd /path/to/your/project
+    npx superpowers-zh
+
+  如果你确实要在主目录安装（不推荐），加 --force：
+    npx superpowers-zh --force
+
+  如果你已经在主目录误装过，可以用 --uninstall 清理：
+    npx superpowers-zh --uninstall
+`);
+    process.exit(1);
+  }
+
   console.log(`  源: ${countDirs(SKILLS_SRC)} 个 skills`);
   console.log(`  目标项目: ${PROJECT_DIR}\n`);
 
@@ -445,6 +708,8 @@ function install(forceToolName) {
     copyDirSync(SKILLS_SRC, dest);
     console.log(`  ✅ 默认安装: ${countDirs(dest)} 个 skills -> ${dest}`);
 
+    generateClaudeCodeBootstrap(PROJECT_DIR);
+
     if (existsSync(AGENTS_SRC)) {
       const agentsDest = resolve(PROJECT_DIR, '.claude', 'agents');
       mkdirSync(agentsDest, { recursive: true });
@@ -464,11 +729,16 @@ const args = process.argv.slice(2);
 const helpIdx = args.findIndex(a => a === '--help' || a === '-h');
 const versionIdx = args.findIndex(a => a === '--version' || a === '-v');
 const toolIdx = args.findIndex(a => a === '--tool' || a === '-t');
+const uninstallIdx = args.findIndex(a => a === '--uninstall' || a === '-u');
+const forceIdx = args.findIndex(a => a === '--force' || a === '-f');
+const force = forceIdx !== -1;
 
 if (helpIdx !== -1) {
   showHelp();
 } else if (versionIdx !== -1) {
   console.log(PKG.version);
+} else if (uninstallIdx !== -1) {
+  uninstall();
 } else if (toolIdx !== -1) {
   const toolArg = args[toolIdx + 1];
   if (!toolArg) {
@@ -482,11 +752,11 @@ if (helpIdx !== -1) {
     console.error(`  支持的工具: ${Object.keys(TOOL_ALIASES).join(', ')}\n`);
     process.exit(1);
   }
-  install(toolName);
-} else if (args.length > 0 && args[0].startsWith('-')) {
+  install(toolName, force);
+} else if (args.length > 0 && args[0].startsWith('-') && forceIdx === -1) {
   console.warn(`  未知参数: ${args[0]}\n`);
   showHelp();
   process.exit(1);
 } else {
-  install();
+  install(undefined, force);
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "superpowers-zh",
-  "version": "1.1.8",
+  "version": "1.2.1",
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=20.0.0"
   },
   "description": "AI 编程超能力中文增强版 — superpowers（99k+ ⭐）完整汉化 + 6 个中国原创 skills，支持 Claude Code / Copilot CLI / Hermes Agent / Cursor / Claw Code / Windsurf / Kiro / Gemini CLI 等 17 款工具",
   "type": "module",