superpowers-zh 1.2.1 → 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

@@ -39,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'] },
@@ -451,11 +455,6 @@ 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);
-    }
   }
 }
 
@@ -597,18 +596,18 @@ function uninstall() {
     }
   }
 
-  // 顺带清理 .claude/agents 下我们装过的 agent（agents 源是平铺的文件，例如 code-reviewer.md）
+  // 清理 .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(AGENTS_SRC) && existsSync(agentsDest)) {
-    const srcAgentNames = new Set(readdirSync(AGENTS_SRC).filter(n => n !== '.DS_Store'));
+  if (existsSync(agentsDest)) {
     let agentsRemoved = 0;
     for (const entry of readdirSync(agentsDest)) {
-      if (srcAgentNames.has(entry)) {
+      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}`);
+    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 });
@@ -709,13 +708,6 @@ function install(forceToolName, force) {
     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');

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.2.1",
+  "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. **沟通协议**：
-   - 如果发现与计划的重大偏差，请编码智能体审查并确认更改
-   - 如果识别出原始计划本身的问题，建议更新计划
-   - 对于实现问题，提供明确的修复指导
-   - 在指出问题之前始终先肯定做得好的地方
-
-你的输出应该是结构化的、可操作的，聚焦于帮助保持高代码质量同时确保项目目标的达成。要全面但简洁，始终提供建设性的反馈，帮助改进当前实现和未来的开发实践。

package/commands/brainstorm.md

@@ -1,5 +0,0 @@
----
-description: "已弃用 - 请改用 superpowers:brainstorming 技能"
----
-
-告诉你的搭档这个命令已弃用，将在下个主要版本中移除。他们应该让你使用"superpowers brainstorming"技能。

package/commands/execute-plan.md

@@ -1,5 +0,0 @@
----
-description: "已弃用 - 请改用 superpowers:executing-plans 技能"
----
-
-告诉你的搭档这个命令已弃用，将在下个主要版本中移除。他们应该让你使用"superpowers executing-plans"技能。

package/commands/write-plan.md

@@ -1,5 +0,0 @@
----
-description: "已弃用 - 请改用 superpowers:writing-plans 技能"
----
-
-告诉你的搭档这个命令已弃用，将在下个主要版本中移除。他们应该让你使用"superpowers writing-plans"技能。