superpowers-zh 1.1.9 → 1.3.0

package/RELEASE-NOTES.zh.md

@@ -0,0 +1,107 @@
+# Superpowers-ZH 中文版 Release Notes
+
+> 本文档记录 `jnMetaCode/superpowers-zh` 中文 fork 自身的 release 历史。
+>
+> 上游 `obra/superpowers` 的英文 release notes 见 [`RELEASE-NOTES.md`](./RELEASE-NOTES.md)（原样保留，未翻译）。
+
+---
+
+## v1.3.0 (2026-05-10)
+
+### 跟上游对齐 (v5.1.0)
+
+- **同步上游 v5.1.0 的目录变更**：上游主动删除了 `commands/`（3 个 deprecated stub）和 `agents/code-reviewer.md`（已上升进 `requesting-code-review` skill）。中文 fork 跟随删除以与上游意图对齐。详见上游 [#1188](https://github.com/obra/superpowers/pull/1188) 与 PR #1299。
+- **`bin/superpowers-zh.js`** 移除安装时复制 `agents/` 到 `.claude/agents/` 的逻辑，**保留** uninstall 时的清理逻辑（用于已装用户清理残留 `code-reviewer.md`，防止双 source of truth）。
+- **`.github/workflows/ci.yml`** 删除 "Validate agents" 验证段（`agents/` 已删，验证空目录无意义）。
+
+### 补齐上游遗漏的根级文件
+
+- **`CLAUDE.md`** —— 上游 contributor 指南（含 anti-slop-PR 规则）的中文翻译，末尾追加中文 fork 自己的 PR 流程说明。
+- **`AGENTS.md`** —— 软链接 → `CLAUDE.md`（mode 120000，跟上游一致）。Codex CLI 等工具从 `AGENTS.md` 自动加载等同读取 CLAUDE.md。
+  - **Known limitation**：`npm pack` 默认不跟随 symlink，因此 npm publish 出来的 tarball 不包含 AGENTS.md。这不影响实际使用：AGENTS.md 是 Codex CLI 在用户自己项目目录读的文件，不是从 `superpowers-zh` 安装包读的；通过 `git clone` 拿到仓库的贡献者会正确解析 symlink。
+- **`RELEASE-NOTES.md`** —— 上游 release notes 原样保留（英文版，1180 行）。
+- **`RELEASE-NOTES.zh.md`** —— 本文件，中文 fork 自身 release 记录。
+- **`.codex-plugin/plugin.json`** —— Codex CLI plugin manifest（中文版本地化：name/description/displayName 改为中文版，URL 指向 `jnMetaCode/superpowers-zh`）。
+- **`.version-bump.json`** —— 上游版本管理配置文件。
+- **`scripts/bump-version.sh`** —— 上游版本同步脚本（含 `--check` 漂移检测、`--audit` 仓库审计）。中文版 npm version 钩子继续用 `scripts/sync-plugin-version.js`，bump-version.sh 作为补充工具引入。
+- **`assets/app-icon.png`** + **`assets/superpowers-small.svg`** —— Codex marketplace 需要的图标资产。
+- **4 个新增上游测试**：`tests/claude-code/test-requesting-code-review.sh`、`tests/claude-code/test-worktree-native-preference.sh`、`tests/opencode/test-bootstrap-caching.{mjs,sh}`。
+
+### 主动修复上游 v5.1.0 的疏忽
+
+- **`.cursor-plugin/plugin.json`** 删除 dangling 的 `"agents": "./agents/"` 和 `"commands": "./commands/"` 两行。上游 v5.1.0 删了目录但忘了同步清理 manifest（git blame 显示这两行从 2026-02-13 加入后从未更新）。中文 fork 主动修掉（向上游开 issue 是后续动作）。
+
+### 修中文版自己的老漂移（PR #23）
+
+- **`.claude-plugin/marketplace.json`** 的 `plugins[0].version` 卡在 `1.1.8` 的老漂移修复（追上其他 4 个 manifest，1.3.0 release 时统一升到 1.3.0）。原因是中文版简化版 `sync-plugin-version.js` 之前只 match 顶层 `"version":` 字段，跳过嵌套位置；导致 Claude Code marketplace 用户看到的 plugin 版本一直停在 1.1.8，跟 npm 包真实版本不同步。
+- **`scripts/sync-plugin-version.js`** 增强为支持嵌套字段路径（`plugins.0.version`）。`TARGETS` 改为对象数组 `{ path, field }`，对齐上游 `.version-bump.json` 格式。仍使用 regex 替换而非 JSON re-stringify，保留原文件格式（缩进、行内/多行数组等不被破坏）。
+
+### 不引入
+
+- 上游 `scripts/sync-to-codex-plugin.sh`（推 OpenAI Codex marketplace 用，硬编码 `prime-radiant-inc/openai-codex-plugins`，中文版用不上）
+- 配套测试 `tests/codex-plugin-sync/test-sync-to-codex-plugin.sh`
+
+### 不动（中文版叠加层全部保留）
+
+`bin/` + npx 流程、`docs/` 中文工具文档、4 个 `chinese-*` skill、`mcp-builder`、`workflow-runner`、`README.md` 主推 npx 路径、`.codex/INSTALL.md`、`.opencode/INSTALL.md`、`.gemini/`、`scripts/sync-plugin-version.js` —— 这些是符合"保持上游主流程不变 + 中文版叠加新增"原则的中文 fork 沉淀，全部保留。
+
+---
+
+## v1.2.1 (2026-05-05)
+
+### 修复
+
+- **`--uninstall` 数据丢失边界 case** —— 加哨兵注释 + 保守 fallback，杜绝在某些路径上误删用户数据。
+
+---
+
+## v1.2.0 (2026-05-05)
+
+### 新增
+
+- **`--uninstall` 子命令** —— `npx superpowers-zh --uninstall` 一条命令清理已安装的 skills（#17）。
+- **HOME 目录守护** —— uninstall 时强校验工作目录非用户 HOME，杜绝误删全局文件。
+- **计数显示修复** —— 安装后输出实际安装的 skill 数量（之前显示固定值）。
+
+---
+
+## v1.1.9 (2026-04-28)
+
+### 修复
+
+- **Claude Code bootstrap 修复** —— npx 安装到 CC 目标时自动补上 `CLAUDE.md` bootstrap，根治 skill 不触发问题（#14）。
+
+### 变更
+
+- **Node 引擎要求** 提升到 `>=20`（Node 14/16/18 均已 EOL）。
+- **README 重排**：相关项目表挪到显眼位置；姊妹项目区块独立成"相关项目生态"章节，重点推广 orchestrator。
+- **QQ 群** 标识改为 QQ 2群。
+
+---
+
+## v1.1.8 (2026-04-19)
+
+### 新增
+
+- **Claw Code 支持**（第 17 款工具，Rust 版 AI CLI）—— auto-detect `.claw/` 或 `CLAW.md`，支持 `--tool claw/claw-code/clawcode`。
+- **CNB（腾讯云原生构建）平台适配** —— `chinese-git-workflow` skill 新增 CNB 章节，含 `.cnb.yml` CI 示例（#6）。
+
+---
+
+## v1.1.0 – v1.1.7 早期开发（2026-03 ~ 2026-04）
+
+中文 fork 在这一时期完成了主要的多工具适配与中文化基建：
+
+- 第 1 款 → 第 16 款工具陆续上线：Claude Code、Cursor、Codex CLI、Gemini CLI、Trae、VS Code (Copilot)、Antigravity、Hermes Agent、Copilot CLI、Windsurf、Aider、OpenCode、Qwen Code（通义灵码）、Kiro、OpenClaw、DeerFlow 2.0
+- 4 个中国原创 skill 沉淀：`chinese-code-review`、`chinese-commit-conventions`、`chinese-documentation`、`chinese-git-workflow`
+- `mcp-builder`、`workflow-runner` 两个补充 skill
+- npx 一条命令自动检测项目工具并安装
+- 跨平台兼容性修复：Windows `cpSync` 问题、低版本 Node 兼容、Antigravity/Aider/Gemini CLI 自动生成 bootstrap
+
+---
+
+## v1.0.0 (2026-03-09)
+
+- 中文 fork 初始版本，基于上游 `obra/superpowers` v5.0.0 翻译。
+- 完整翻译 14 个上游 skill。
+- 首批支持 Claude Code 一种工具。

package/assets/superpowers-small.svg

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><svg id="Calque_1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path d="M394.28,207.8c.81,2.41,1.39,4.78,1.8,7.07,1.61,9.03-.93,17.78-5.99,21.74-22.6,17.7-49.85,29.35-75.34,38.6-.59.22-1.09.28-1.4.34-2.22.47-4.95,1.04-7.25,0-1.46-.66-2.25-1.74-2.66-2.3-1.56-2.1-1.59-4.31-1.56-5.13.1-2.67-.01-4.69,0-4.82.45-3.52.91-10.66,1.41-21.28.6-3.87,2.16-9.63,6.94-13.96,4.01-3.62,8.33-4.6,14.59-5.87,10.76-2.19,37.21-8.22,47.42-16.56,1.63-1.33,2.97-2.65,4.19-3.96,3.72-3.99,6.39-7.92,7.93-10.36,3.22,3.22,7.25,8.48,9.92,16.47Z"/><path d="M428.67,185.28c-2.33,11.99-8.91,22.32-15.88,30.38.27-5.5-.05-12.11-1.86-19.08-5.04-19.36-19.74-34.7-37.78-37.78-32.21-9.74-70.59,3.79-99.08,18.29-3.87,1.95-9.52-2.77-11.84-8.16-3.32-7.71-1.63-6.28,2.61-8.49,38.31-20.03,82.01-39.61,123.91-29.7,8.26,1.95,15.96,5.26,23.48,10.54,11.32,7.96,20.21,24.74,16.44,44Z"/><path d="M117.72,304.2c-.81-2.41-1.39-4.78-1.8-7.07-1.61-9.03.93-17.78,5.99-21.74,22.6-17.7,49.85-29.35,75.34-38.6.59-.22,1.09-.28,1.4-.34,2.22-.47,4.95-1.04,7.25,0,1.46.66,2.25,1.74,2.66,2.3,1.56,2.1,1.59,4.31,1.56,5.13-.1,2.67.01,4.69,0,4.82-.45,3.52-.91,10.66-1.41,21.28-.6,3.87-2.16,9.63-6.94,13.96-4.01,3.62-8.33,4.6-14.59,5.87-10.76,2.19-37.21,8.22-47.42,16.56-1.63,1.33-2.97,2.65-4.19,3.96-3.72,3.99-6.39,7.92-7.93,10.36-3.22-3.22-7.25-8.48-9.92-16.47Z"/><path d="M83.33,326.72c2.33-11.99,8.91-22.32,15.88-30.38-.27,5.5.05,12.11,1.86,19.08,5.04,19.36,19.74,34.7,37.78,37.78,32.21,9.74,70.59-3.79,99.08-18.29,3.87-1.95,9.52,2.77,11.84,8.16,3.32,7.71,1.63,6.28-2.61,8.49-38.31,20.03-82.01,39.61-123.91,29.7-8.26-1.95-15.96-5.26-23.48-10.54-11.32-7.96-20.21-24.74-16.44-44Z"/><ellipse cx="255.16" cy="258.86" rx="28.95" ry="28.76"/></svg>

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;
@@ -37,9 +39,13 @@ function copyDirSync(src, dest) {
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf8'));
 const SKILLS_SRC = resolve(__dirname, '..', 'skills');
-const AGENTS_SRC = resolve(__dirname, '..', 'agents');
 const PROJECT_DIR = process.cwd();
 
+// 历史遗留 agent 文件名 — 用于 --uninstall 清理已装用户机器上的残留。
+// 上游 v5.1.0 把 agents/code-reviewer.md 上升进 requesting-code-review skill，
+// agents/ 目录已删，但旧版本装过的用户机器上仍有残留文件需要清理。
+const LEGACY_AGENT_FILENAMES = ['code-reviewer.md'];
+
 const TARGETS = [
   { name: 'Claude Code',   dir: '.claude/skills',           detect: '.claude' },
   { name: 'Cursor',        dir: '.cursor/skills',           detect: ['.cursor', '.cursorrules'] },
@@ -86,6 +92,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 +205,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 +247,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,13 +303,13 @@ ${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}`);
   }
 }
@@ -331,13 +346,13 @@ ${skillList}
   if (existsSync(mdPath)) {
     const existing = readFileSync(mdPath, 'utf8');
     if (!existing.includes('superpowers-zh')) {
-      writeFileSync(mdPath, existing + '\n\n' + content, 'utf8');
+      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, content, 'utf8');
+    writeFileSync(mdPath, wrapWithSentinel(content), 'utf8');
     console.log(`  ✅ Claude Code: bootstrap -> ${mdPath}`);
   }
 }
@@ -380,6 +395,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         显示版本
 
@@ -392,6 +409,9 @@ function showHelp() {
       npx superpowers-zh --tool cursor
       npx superpowers-zh --tool trae
 
+    误装到主目录可以这样清理：
+      cd ~ && npx superpowers-zh --uninstall
+
   项目：https://github.com/jnMetaCode/superpowers-zh
 `);
 }
@@ -401,8 +421,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` +
@@ -411,7 +431,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);
@@ -435,15 +455,190 @@ function installForTarget(target) {
 
   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 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 下旧版本装过的 legacy agent（v1.2.x 及之前会装 code-reviewer.md，
+  // v1.3.0 起跟随上游 v5.1.0 移除）。即使 agents/ 源目录已删，已装用户跑 --uninstall 仍应能清干净。
+  const agentsDest = resolve(PROJECT_DIR, '.claude', 'agents');
+  if (existsSync(agentsDest)) {
+    let agentsRemoved = 0;
+    for (const entry of readdirSync(agentsDest)) {
+      if (LEGACY_AGENT_FILENAMES.includes(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) {
+function install(forceToolName, force) {
  try {
   console.log(`\n  superpowers-zh v${PKG.version} — AI 编程超能力中文版\n`);
 
@@ -452,6 +647,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`);
 
@@ -492,13 +708,6 @@ function install(forceToolName) {
     console.log(`  ✅ 默认安装: ${countDirs(dest)} 个 skills -> ${dest}`);
 
     generateClaudeCodeBootstrap(PROJECT_DIR);
-
-    if (existsSync(AGENTS_SRC)) {
-      const agentsDest = resolve(PROJECT_DIR, '.claude', 'agents');
-      mkdirSync(agentsDest, { recursive: true });
-      copyDirSync(AGENTS_SRC, agentsDest);
-      console.log(`  ✅ 默认安装: agents -> ${agentsDest}`);
-    }
   }
 
   console.log('\n  安装完成！重启你的 AI 编程工具即可生效。\n');
@@ -512,11 +721,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) {
@@ -530,11 +744,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/docs/README.trae.md

@@ -56,6 +56,17 @@ cd /your/project
 npx superpowers-zh
 ```
 
+## 卸载 / 误装清理
+
+如果不小心在主目录（`~`）误跑了 `npx superpowers-zh`，会把 skills 和 `.trae/rules/superpowers-zh.md` 写到你的 home。v1.2.1 起会主动拒绝，但老版本可能已经污染过。清理：
+
+```bash
+cd ~                                    # 或具体的项目目录
+npx superpowers-zh@latest --uninstall
+```
+
+会删除 `.trae/skills/` 下装过的 skill、`.trae/rules/superpowers-zh.md`，并清理 `CLAUDE.md` 等文件里的 superpowers-zh 段（保留你自己写的内容）。
+
 ## 获取帮助
 
 - 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers-zh",
-  "version": "1.1.9",
+  "version": "1.3.0",
   "engines": {
     "node": ">=20.0.0"
   },
@@ -10,18 +10,24 @@
   "bin": {
     "superpowers-zh": "bin/superpowers-zh.js"
   },
+  "scripts": {
+    "version": "node scripts/sync-plugin-version.js && git add .claude-plugin/plugin.json .claude-plugin/marketplace.json .cursor-plugin/plugin.json .codex-plugin/plugin.json"
+  },
   "files": [
     "bin/",
     "skills/",
-    "agents/",
-    "commands/",
     "hooks/",
+    "assets/",
     ".claude-plugin/",
     ".cursor-plugin/",
     ".codex/INSTALL.md",
+    ".codex-plugin/",
     ".opencode/INSTALL.md",
     ".opencode/plugins/",
+    "CLAUDE.md",
     "GEMINI.md",
+    "RELEASE-NOTES.md",
+    "RELEASE-NOTES.zh.md",
     "gemini-extension.json",
     "docs/",
     "README.md",

package/skills/chinese-code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: chinese-code-review
-description: 中文代码审查规范——在保持专业严谨的同时，用符合国内团队文化的方式给出有效反馈
+description: 中文 review 沟通参考——话术模板、分级标注（必须修复/建议修改/仅供参考）、国内团队常见反模式应对。仅在用户显式 /chinese-code-review 时调用，不要根据上下文自动触发。
 ---
 
 # 中文代码审查规范

package/skills/chinese-commit-conventions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: chinese-commit-conventions
-description: 中文 Git 提交规范 — 适配国内团队的 commit message 规范和 changelog 自动化
+description: 中文 commit 与 changelog 配置参考——Conventional Commits 中文适配、commitlint/husky/commitizen 中文模板、conventional-changelog 中文配置。仅在用户显式 /chinese-commit-conventions 时调用，不要根据上下文自动触发。
 ---
 
 # 中文 Git 提交规范

package/skills/chinese-documentation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: chinese-documentation
-description: 中文技术文档写作规范——排版、术语、结构一步到位，告别机翻味
+description: 中文文档排版参考——中英文空格、全半角标点、术语保留、链接格式、中文文案排版指北约定。仅在用户显式 /chinese-documentation 时调用，不要根据上下文自动触发。
 ---
 
 # 中文技术文档写作规范

package/skills/chinese-git-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: chinese-git-workflow
-description: 适配国内 Git 平台和团队习惯的工作流规范——Gitee、Coding、极狐 GitLab、CNB 全覆盖
+description: 国内 Git 平台配置参考——Gitee、Coding.net、极狐 GitLab、CNB 的 SSH/HTTPS/凭据/CI 接入差异与镜像同步配置。仅在用户显式 /chinese-git-workflow 时调用，不要根据上下文自动触发。
 ---
 
 # 国内 Git 工作流规范

package/agents/code-reviewer.md

@@ -1,48 +0,0 @@
----
-name: code-reviewer
-description: |
-  当一个主要项目步骤完成并需要根据原始计划和编码标准进行审查时使用此智能体。示例：<example>Context: 用户正在创建一个代码审查智能体，应在逻辑代码块编写完成后调用。user: "我已经按照计划第 3 步完成了用户认证系统的实现" assistant: "干得好！让我使用 code-reviewer 智能体来根据我们的计划和编码标准审查实现" <commentary>由于一个主要项目步骤已完成，使用 code-reviewer 智能体来验证工作是否符合计划并识别任何问题。</commentary></example> <example>Context: 用户完成了一个重要功能的实现。user: "任务管理系统的 API 端点现在完成了——这涵盖了我们架构文档中的第 2 步" assistant: "很好！让我用 code-reviewer 智能体检查这个实现，确保它符合我们的计划并遵循最佳实践" <commentary>规划文档中的一个编号步骤已完成，所以应该用 code-reviewer 智能体审查工作。</commentary></example>
-model: inherit
----
-
-你是一位高级代码审查员，精通软件架构、设计模式和最佳实践。你的角色是根据原始计划审查已完成的项目步骤，确保代码质量标准得到满足。
-
-审查已完成的工作时，你将：
-
-1. **计划对齐分析**：
-   - 将实现与原始规划文档或步骤描述进行对比
-   - 识别与计划的方案、架构或需求的任何偏差
-   - 评估偏差是合理的改进还是有问题的偏离
-   - 验证所有计划的功能是否都已实现
-
-2. **代码质量评估**：
-   - 审查代码是否遵循已建立的模式和约定
-   - 检查错误处理、类型安全和防御性编程是否恰当
-   - 评估代码组织、命名约定和可维护性
-   - 评估测试覆盖率和测试实现的质量
-   - 寻找潜在的安全漏洞或性能问题
-
-3. **架构和设计审查**：
-   - 确保实现遵循 SOLID 原则和已建立的架构模式
-   - 检查关注点分离和松耦合是否恰当
-   - 验证代码与现有系统的集成是否良好
-   - 评估可扩展性和可延展性的考虑
-
-4. **文档和标准**：
-   - 验证代码包含适当的注释和文档
-   - 检查文件头、函数文档和内联注释是否存在且准确
-   - 确保遵循项目特定的编码标准和约定
-
-5. **问题识别和建议**：
-   - 将问题明确分类为：关键（必须修复）、重要（应该修复）或建议（锦上添花）
-   - 对每个问题提供具体示例和可操作的建议
-   - 识别计划偏差时，解释它们是有问题的还是有益的
-   - 在有帮助时提供带有代码示例的具体改进建议
-
-6. **沟通协议**：
-   - 如果发现与计划的重大偏差，请编码智能体审查并确认更改
-   - 如果识别出原始计划本身的问题，建议更新计划
-   - 对于实现问题，提供明确的修复指导
-   - 在指出问题之前始终先肯定做得好的地方
-
-你的输出应该是结构化的、可操作的，聚焦于帮助保持高代码质量同时确保项目目标的达成。要全面但简洁，始终提供建设性的反馈，帮助改进当前实现和未来的开发实践。