superpowers-zh/RELEASE-NOTES.zh.md

Superpowers-ZH 中文版 Release Notes

本文档记录 jnMetaCode/superpowers-zh 中文 fork 自身的 release 历史。

上游 obra/superpowers 的英文 release notes 见 RELEASE-NOTES.md（原样保留，未翻译）。

---

v1.7.11 (2026-08-28)

Codex CLI / VS Code / Windsurf / Qwen Code / DeerFlow / Claw Code 用户请重新安装。

v1.7.10 那次核查查出三款装错，当时的结论是「既然错过一次，就该问一句还有几个」。这一版把剩下没查过的全部查完了 —— 逐款对官方文档（拿不到文档的对源码），一款一款过。

结果：又是四款「装了完全不生效」。都是我们自己写的路径，都没查过官方文档。

🐛 Codex CLI：项目级装到了 Codex 从不扫描的目录

官方 skills 文档给出的扫描目录完整清单：

$CWD/.agents/skills、$CWD/../.agents/skills、$REPO_ROOT/.agents/skills
$HOME/.agents/skills、/etc/codex/skills、内置 skill

没有 .codex/skills。 而我们项目级正是装到那里。

讽刺的是全局（~/.agents/skills）一直是对的，原注释还专门写明「不是 ~/.codex/skills」—— 说明当初查过全局，却没顺手核一下项目级。

已改为 .agents/skills，并在安装时清理旧位置（只清我们装的，用户自己放在 .codex/skills 下的不动，已实测）。与 Antigravity 共用 .agents/skills 是 Agent Skills 开放约定，不是冲突。

这个改动还牵出一个既有 bug：自动检测有顺序依赖。 检测原来是边装边判的 —— Codex 装完会创建 .agents/，循环走到 Antigravity（detect: '.agents'）时它就被误判成「项目里有这个工具」，于是多装一份。任何「装了 A 会创建 B 的检测标记」的组合都会中招。改为先把所有工具的检测结果一次算完再开始装：检测必须基于安装前的项目状态。

🐛 VS Code (Copilot)：装的 20 个文件，Copilot 一个都不读

官方文档明确 Copilot 只自动读这几处：

.github/copilot-instructions.md / AGENTS.md / CLAUDE.md   （始终生效）
.github/instructions/*.instructions.md                    （按 applyTo 匹配）

我们把 20 个 skill 拷进 .github/superpowers/ —— 不在其中，而且装完什么引导都不写。

旧文档更说明问题：它写着「建议你创建 .github/copilot-instructions.md 引用这些 skills」并给了示例 —— 我们知道需要引导，却让用户自己动手，而绝大多数人不会照做。

现在自动生成 .github/instructions/superpowers-zh.instructions.md（applyTo: "**"，约 4.5 KB 的索引），正文仍留在 .github/superpowers/ 按需读取 —— 与 Cline / Kilo / Kiro 同一套「常驻只放索引」的思路。刻意不动用户的 copilot-instructions.md，那是他们的文件。

🐛 Windsurf：--global 装在 Windsurf 不读的地方

官方文档写明两个路径不同构：

	路径
项目级	.windsurf/skills/<name>/ ✅ 我们是对的
用户级	~/.codeium/windsurf/skills/<name>/ ❌ 我们装到了 ~/.windsurf/skills

测试为什么没抓到：只验退出码，不验落盘位置。 装到错目录退出码照样是 0 —— 「跑通了」不等于「装对了」。已补 GLOBAL_DIR 断言：每款全局工具逐个断言 skill 真落在官方读的那个目录，外加一条自检（以后加全局工具不能漏断言）。双向验证过：把路径改回旧值立刻报错。

🐛 DeerFlow：检测标记根本不存在（Aider 同款）

安装路径 skills/custom/ 是对的（官方文档确认自动扫描 ["skills/public", "skills/custom"] 两个写死的目录）。但 detect 写的是 deer_flow —— 用 GitHub API 列了 deer-flow main 分支顶层目录：

.agent .github backend contracts deploy docker docs frontend plans
pr-build scripts skills tests

没有 deer_flow。 与 Aider 的 .aider 是同一个毛病：真实检出从来没被自动检测到过。改认 skills/public（skills 机制本身、随仓库版本控制，任何检出都有），deer_flow 保留作 1.x 兼容。

顺带删掉文档里那段 export DEERFLOW_SKILLS_DIR=... —— 官方文档里没有这个环境变量，目录是写死的。

🐛 Qwen Code：缺 bootstrap（skill 是死重）+ 我们把产品搞混了

路径是对的，但两个问题：

① 产品搞混。 文档标题写「Qwen Code (通义灵码)」、链接指向 tongyi.aliyun.com。实际 Qwen Code 是 QwenLM/qwen-code 这个命令行工具（Gemini CLI 的 fork）；通义灵码是阿里的 IDE 插件，是另一个产品，路径完全不同 —— 照我们的文档去配通义灵码是配不通的。与 #119 的 Qoder 表是同一类错误：把两个产品面混成一份说明。

② 只装 skills、不写 bootstrap。 Claude 写 CLAUDE.md、Gemini 写 GEMINI.md，而 Qwen Code 的对应物 QWEN.md 我们完全没用。按上游的原则：没有 bootstrap，skill 就是死重 —— 文件在磁盘上但很少被调用。已补（项目级写 ./QWEN.md，全局写 ~/.qwen/QWEN.md，已有文件用哨兵注释追加而非覆盖），并补上全局卸载的残留缺口。

🆕 Claw Code：补 bootstrap + 补文档（23 款里唯一没有安装文档的一款）

路径拿到了源码级证据（ultraworkers/claw-code 的 rust/crates/plugins/src/lib.rs 明写发现 .claw/skills、.omc/skills、.agents/skills；USAGE.md 列出指令文件优先级 CLAUDE.md > CLAW.md > AGENTS.md）。补上 CLAW.md bootstrap 与 docs/README.claw.md，并写明一条实用提醒：claw 也扫 .agents/skills，装过 Antigravity 的项目其实已经能读到，重复装会加载两份。

🆕 CodeBuddy / CodeArts 补 --global（全局支持 9 → 11 款）

两款的用户级路径此前都写着「尚未验证」，现已拿到官方出处：

工具	用户级路径	出处
CodeBuddy（腾讯）	~/.codebuddy/skills/ + ~/.codebuddy/CODEBUDDY.md	codebuddy.cn/docs/cli/codebuddy-dir
CodeArts（华为云码道）	~/.codeartsdoer/skills/	华为云官方用户指南

支持通用全局安装的工具由 9 款增至 11 款：Claude Code · Codex CLI · Qoder · Windsurf · Qwen Code · OpenClaw · OpenCode · Crush · Hermes Agent · CodeBuddy · CodeArts。

🐛 4 条死链，其中 2 条是编造出来的仓库地址

核查 OpenClaw 时发现文档链的是 github.com/anthropics/openclaw —— 那个仓库不存在。顺手全仓扫了一遍外链，45 条里 4 条是死的：

原链接	状态	改为
github.com/anthropics/openclaw	404，仓库不存在	github.com/openclaw/openclaw
github.com/anthropics/antigravity	404，且 Antigravity 是谷歌的产品	antigravity.google
huaweicloud.com/product/codeartsdoer.html	404，产品页改版	codearts.huaweicloud.com
docs.codeium.com/windsurf	Windsurf 已迁走	docs.windsurf.com/…

前两条是编造出来的出处。这比没有出处更坏：它让人以为核实过了。已固化成外链验活门禁（两遍制：并行快扫出嫌疑名单，再串行复核，两遍都判死才算死 —— 一个会误报的门禁比没有门禁更糟，人会学会忽略它）。

🌐 官网：工具墙停在 20 款，三处文案自己打自己

首页统计块写「20 支持工具」，同一屏的标题写「23 款工具通用」，FAQ 又枚举了 23 款。根因是文案计数跟着 installer 改到了 23，而 site/build.mjs 的工具数组从来没人补 —— Cline / Kilo Code / Crush 的用户在安装命令下拉里找不到自己的工具。

• 工具列表 20 → 23，统计块改成从列表长度算，不再硬编码
• 修 4 条错的：Claw Code 已能自动检出（不必再 --tool claw）、Hermes 改给 --global（项目级给了等于给「装了不生效」）、Qwen Code 类型 IDE → CLI、Antigravity 类型 CLI → IDE
• FAQ「支持全局」清单 7 → 11 款（三语同步）
• skill 详情页 6 条死链：SKILL.md 里指向兄弟文件的相对链接（implementer-prompt.md、../requesting-code-review/code-reviewer.md 等）站点上没有这些 .md，../ 开头的 404，其余被渲染器打成 href="#" —— 点了没反应，比 404 还难查。现在解析到 GitHub 源文件
• 新增赞助商独立页，导航栏补当前页高亮

🛡️ 测试与门禁

这一版查出的问题，旧门禁一个都发现不了。逐条补上，并全部做过反向验证（把问题造回去，必须报错）：

新增门禁	堵的是
全局工具落盘位置断言	Windsurf 那类「退出码 0 但装错目录」
外链验活（两遍制）	编造出来的仓库地址
官网工具列表条目数 = TARGETS + 1	官网列表跟不上 installer
官网全局清单必须覆盖每个 global: 目标	FAQ 停在 7 款
grep -P / 全角括号吞变量名 两条 shell 坑	我自己写出来的静默失效检查

verify-release.sh 101 → 115 pass；audit.sh → 170 pass。

📋 这一轮六款，六种失效方式

工具	路径对吗	失效方式
Codex CLI	❌ 项目级	装到从不被扫描的目录
VS Code	❌	位置不在官方读取清单里，且不写引导
Windsurf	❌ 仅全局	用户级路径与项目级不同构
DeerFlow	✅	检测标记不存在，从没被自动检测到
Qwen Code	✅	无 bootstrap，skill 是死重；文档搞混产品
Claw Code	✅	无 bootstrap、无文档

共同点：全部是我们自己写的，全部没查过官方文档。 现在每条路径在代码注释里都带出处链接与核对结论 —— 下次改之前先看那行注释。

---

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 原生支持自动加载此文件」。官方文档说的是反的：必须 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 官方文档明确：.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）

报告人说 Qoder IDE 里没有 general-purpose 子智能体，而我们的 qoder-tools.md 白纸黑字写着有。查该文件的引入 commit —— 没有引用任何来源。

对照 Qoder 官方子代理文档，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）

报告人说「项目级 .hermes/skills/ 里的 20 个 skill 全部返回 404，必须手动复制到 ~/.hermes/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 可以随仓库分发），但装完打印可直接粘贴的配置片段，带绝对路径：

  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 的差异。结论是定位基本站得住，但不完全 —— 查出 5 处偏离，全部修掉。

🔍 核查方法

1. 文件级：上游 skills/ 与我们逐文件比对，分出「仅上游有」「仅我们有」
2. 内容级：14 个翻译 skill 各自比对标题数（排除代码围栏）、表格行数、列表项数
3. 溯源：每处差异追查来源 —— 是声明过的 fork 增量，还是漏译／漏同步

🐛 修掉的 5 处偏离

① antigravity-tools.md 上游有、我们没有

而 installer 里明明支持 Antigravity —— 该工具用户拿不到任何工具映射。影响是实质的：Antigravity 没有 todo 工具（manage_task 管的是后台进程），没这份映射，所有说「创建待办」的 skill 在它上面都会走偏。已翻译补入，并按上游同序列入平台适配清单。

② finishing-a-development-branch 漏同步 3 个 commit

C 块时的 commit 清单不全，漏了 fbb6dba / bcfe798 / 9dff1a9。其中 9dff1a9 是行为变更：上游把菜单从 4 个选项减为 3 个，删掉了「丢弃这份工作」，丢弃改为只在人类伙伴明确提出时才走的独立小节；基础分支判定也从盲跑 merge-base 改为「先确认，合并到错分支代价很高」。已照上游当前状态整体重译（一次拿到全部 4 个 commit），并断言 D 块的 worktree 修复完整保留。

③ writing-plans 漏译整节 —— 上游的 Task Right-Sizing（任务边界怎么划）我们完全没有。

④ writing-skills 四个问题 —— 漏译 H2 整节 Match the Form to the Failure（含「禁令在塑形类问题上会反噬」的实测结论）、漏译 H3 Micro-Test Wording Before Full Scenarios、两个连续小节都编号为 4、节名仍是过时的「Claude 搜索优化（CSO）」（上游早已改名 SDO），正文两处引用一并同步。

⑤ fork 增量插在了上游步骤序列中间

executing-plans 把「处理常见异常」插成步骤 3，于是上游的 Step 3: Complete Development 被挤成我们的「步骤 4」；Remember 也从上游的 6 条被加到 7 条。这不是「不影响上游」，是改了上游的结构编号。

改为外挂式：增量移出步骤序列、挂在「何时停下来求助」之后（它本就是那节三种情形的展开），步骤编号恢复 1/2/3，Remember 恢复 6 条。

🛡️ 让「不影响上游」成为可执行的检查

README 声明会漂移，所以新增 audit 3c-bis：

翻译 skill 的标题数必须等于「上游标题数 + 本文件里带标注的增量节数」

增量节靠正文里一行标注声明（本节是 superpowers-zh 的增量内容），标注与内容同处一文件、不会各自漂移。未标注就多出章节 = 隐性分叉，直接 FAIL。 已双向验证：偷偷加一节会被拦下并给出可操作提示，加标注后放行。

目前全仓仅 2 处带标注的增量：executing-plans 的「常见异常处理」、using-superpowers 的「中国特色技能路由」。

🐛 修掉一个让守卫从未生效的 bug

3c-bis 第一次测试没拦住。查出原因：grep -c 匹配到 0 个时输出 "0" 但退出码为 1，写成 $(grep -c ... || echo 0) 会拼出 "0\n0"，后续整数比较直接报错、检查静默失效。改用 ; true 只吞退出码。

全仓扫同一模式，测试辅助里也有 3 处（上游同样有）：test-helpers.sh 的 assert_count、test-subagent-driven-development-integration.sh 的 task_count / todo_count。后果是这些断言永远无法正常失败 —— 模式没匹配到时比较报错而非判定失败。三处一并修掉并加注释。（tests/ 不进 npm 包，仅开发使用。）

修复后 audit 由 154 升到 166 pass —— 因为 3c-bis 现在真的对 14 个 skill 都跑了。

✅ 核查后的定位现状

纯增量部分（符合定位）：

• 6 个 fork 专属 skill：chinese-* ×4 + mcp-builder + workflow-runner
• 3 个 fork 专属 references：copilot / hermes / qoder（我们支持、上游不支持或已删的 harness）
• 2 处带标注的翻译 skill 内增量

14 个翻译 skill 的上游各节现已全部逐节对应。

scripts/audit.sh 166 pass / 0 warn / 0 fail、scripts/verify-release.sh 90 pass / 0 fail。

---

v1.7.7 (2026-08-08)

🆕 新增 Crush 适配（工具数 22 → 23，关 #40）

查权威源（charmbracelet/crush repo 文档）确认：Crush 遵循 Agent Skills 开放标准，项目级自动发现四个目录，无需任何配置：

.crush/skills    .agents/skills    .claude/skills    .cursor/skills

用户级为 ~/.config/crush/skills，因此支持 --global。

⚠️ 一个重要副作用： 已经为 Claude Code / Cursor / Codex / Antigravity 装过 superpowers-zh 的用户，Crush 现在就已经能读到那些 skills —— 此时不要再装 --tool crush，否则同一批 skills 会有两份被重复加载。docs/README.crush.md 里给了确认命令。

skills-only 适配，不需要 bootstrap；不动你的 crush.json（四个自动发现目录已够用）。实测：装 20 skills / 二次装幂等 / 卸载零残留且正确保留用户的 crush.json；--global 装到 ~/.config/crush/skills 并可干净卸载。

🎯 上个版本新加的计数检查，第一次在真实改动里生效

加 Crush 时漏改了 site/build.mjs 的 5 处计数（三语言标语 + FAQ 枚举）。v1.7.3 引入的 audit Category 5 直接 FAIL 拦下：

❌ 计数不一致: site/build.mjs「官网简体标语」= 22，应为 23
❌ 计数不一致: site/build.mjs「官网 FAQ 枚举」= 22，应为 23
... 共 5 条

已补 site 18 处并重建，三语言首页 23 计数、0 残留、Crush 均已出现。

🔧 verify-release.sh 有同样的漂移问题，已修

它有自己独立的覆盖清单 —— 加新工具时不进去就静默不测。本次 Crush 就是这样：分数仍是 82，因为压根没测它。

• SPEC / DETECT / GLOBAL_OK 三处补 Crush
• 顺带发现 B 段还漏了 3 个工具的检测标记：DeerFlow（deer_flow）、VS Code（.github/copilot-instructions.md）、Gemini CLI（GEMINI.md）—— 后两个是文件而非目录，原先的 DETECT 循环一律 mkdir，现按扩展名区分创建方式
• 新增 G 段自检：SPEC 覆盖数必须等于 installer 宣称的工具数；DETECT 覆盖的工具名集合必须包含全部 TARGETS 名字（用集合比对而非数条数 —— 一个工具可以有多个检测标记，数数会误判）

覆盖从 82 项升到 90 项。

✅ 验证

scripts/audit.sh 152 pass / 0 warn / 0 fail、scripts/verify-release.sh 90 pass / 0 fail。

---

v1.7.6 (2026-08-08)

上游 v6.2.0 对齐完成 —— #19 的 C 块收尾，scripts/audit.sh 的上游结构漂移告警清零。

🧾 盘点先行：其中 3 项不是风格性改动

C 块表面上是 14 个 refactor(skills) commit（"drop social proof"、"drop The Bottom Line"、"fold into rationalization table"），看着像上游在统一自己的文风。开工前做了逐 commit 盘点，判定标准定为**「删掉的文字里有没有别处没写的规则」**——结论纠正了原本的假设：

• cfb6281 新增了一张 rationalization 表（2 行全新规则），替换掉「与工作流的集成」那份清单
• 03147d2 给 executing-plans 加了「先确保隔离工作区」作为步骤 1（SDD 那一半已随 A 块完成）
• bc86802 把「常见错误」5 个小节 + 「红线」Never/Always 双清单压成 5 行表，规则一条不少——这也是此前唯一有客观漂移证据的 skill

✂️ 其余各项逐条核实后才删

skill	删掉的	规则去哪了
receiving-code-review	「底线」	概述已有「核心原则：先验证再实施。先提问再假设」
writing-skills	「总结」	铁律节 + TDD 循环表已完整承载
writing-plans	「注意事项」	精确路径 / Run: / 预期输出 三条都内建在任务结构模板里——上游是把「告知」改成「示范」
brainstorming	「核心原则」6 条	5 条已在流程详述逐条体现；YAGNI 按上游移到「探索方案」的使用现场
systematic-debugging	「实际效果」+ 社会证明句	核心原则行保留；「相关技能」块折入第四阶段「验证修复」
dispatching-parallel-agents	「核心优势」「实际效果」	验证节保留
verification-before-completion	「为什么这很重要」「底线」	「证据先于宣称」核心原则行保留
executing-plans	质量宣称、「集成」	按上游改写为平铺平台清单

✅ 验证

结构：10 个 skill 的 H2 数与上游逐一对齐（8 个完全相同、2 个差 1）；executing-plans / using-git-worktrees / requesting-code-review 的 superpowers: 引用集与上游完全一致。

行为 eval —— 两轮共 11 题全对。 专门考被删段落里的规则是否仍生效：原生 worktree 工具 vs git worktree add（答出「第一大错误」与「幽灵状态」）、跳过 check-ignore 的后果、目录名优先级、基线失败能否继续、能否无证据宣称完成、审查建议有疑问时该照做还是反驳、能否先打补丁再查根因、能否自己读 diff 代替派审查者（命中 cfb6281 新增表行）、方案里的「以后可能用得上」怎么处理（命中 YAGNI 新落点）。

回归：scripts/audit.sh 150 pass / 0 warn / 0 fail、scripts/verify-release.sh 82 pass / 0 fail。

audit PASS 由 152 降至 150 —— 上游有意删除的两个「集成」节里各有 superpowers: 引用，Category 4b 因此少 2 项检查；引用集已核对与上游一致。

---

v1.7.5 (2026-08-07)

对齐上游 v6.2.0 的 B 块 + D 块（#19）。

🐛 worktree 清理静默空转（真 bug，我们与上游同样存在）

finishing-a-development-branch 的步骤 6 在步骤 5 已经 cd 到主仓库根之后，才用 git rev-parse --show-toplevel 重算 WORKTREE_PATH —— 于是拿到主根路径，.worktrees/ 溯源判断永远匹配不上，清理静默空转，随后分支删除还会因为 worktree 仍挂着而失败。上游记录说测试对象不得不偏离 skill 原文才能跑通。

修法：步骤 2 趁还在工作区内就捕获，步骤 6 消费该值并加显式警告说明为何不能重算；去掉步骤 6 冗余的 MAIN_ROOT 推导与 cd；选项 2 补上菜单已声称的分离 HEAD 推送变体。

已实际复现验证（临时仓库 + .worktrees/feature）：旧逻辑算得 main → 溯源未命中 → 清理空转；新逻辑捕获到 main/.worktrees/feature → 命中 → worktree remove 与 branch -D 均成功。

🐛 我们把 Gemini 的子智能体支持写错了

gemini-tools.md 原文称 Gemini CLI 没有 Task 等价物、依赖子智能体的 skill「退化为 executing-plans 单会话执行」。这是错的 —— Gemini CLI 通过 invoke_agent（agent_name: "generalist"，也可用 @generalist 聊天语法）支持子智能体，且支持同一响应内多调用并行分派。

这个错误会让 Gemini CLI 用户的 subagent-driven-development / dispatching-parallel-agents / requesting-code-review 全部瘸腿。按上游重写（33 → 62 行），补齐指令文件层级加载、~/.gemini/skills 与 ~/.agents/skills 优先级、模板填写、并行分派，以及此前缺失的 20 个工具名。已全仓扫描确认无别处重复该说法。

🔄 testing-anti-patterns.md → writing-good-tests.md

上游把 299 行的反模式枚举重写为 198 行的两条原则：

• 原则 1「点名它要抓的破坏」 —— 写测试体前先答"什么生产改动会让它失败，那是 bug 还是决定"。含镜像断言、变更探测器、测行为不测文本、测你的代码不测框架
• 原则 2「跑真东西」 —— mock 不配拥有断言、在正确层级 mock、替身要具体、完整镜像真实数据、生产类只承载生产方法
• 新增变异检查：收尾前在脑中变异生产代码，每种现实变异都应至少让一个测试失败
• 触发条件放宽到「编写或修改任何测试时」

TDD SKILL.md 同步：删掉「为什么顺序很重要」整节长散文（论点折进合理化借口表，5 行扩写）、删掉末尾已失效的「测试反模式」一节。

🔧 audit 结构漂移度量修正（此前一直在虚报欠账）

audit.sh 用 grep -cE '^#{1,4} ' 数标题，但这会把 ``` 围栏内的 shell 注释（# 运行测试）当成 markdown 标题 —— 多几行 bash 注释就能凭空造出「结构漂移」。

用正确口径（awk 逐行跟踪围栏）重算 14 个 skill，3 条告警里 2 条是假阳性：

skill	旧口径	新口径
executing-plans	9/16 WARN	9/11 pass
finishing-a-development-branch	21/31 WARN	14/17 pass
using-git-worktrees	21/28 WARN	14/21 WARN（真漂移）

双向验证：给 brainstorming 加 5 个真标题会触发告警，加 5 行围栏内 shell 注释不触发。

✅ 验证

• 两个新/改文件章节均与上游一一对应；writing-good-tests.md 指标精确一致（12 bold 要点 / 11 行表格 / 11 条危险信号 / 14 项代码记号）
• 行为 eval 8 个判断场景：8/8 全对。附带一个有价值的对照：agent 拿不到 writing-good-tests.md、只能退回 SKILL.md 四条摘要时得分 6/8 —— 错的恰好是只存在于参考文件里的两条规则（部分 mock 静默失败、琐碎转发 getter 不配有测试）。说明参考文件承载着摘要覆盖不到的承重规则。
• scripts/audit.sh 152 pass / 1 warn / 0 fail（原 150/3）、scripts/verify-release.sh 82 pass / 0 fail

---

v1.7.4 (2026-08-07)

🔄 SDD 同步上游 v6.2.0：plan 作用域工作区 + 基于唤回的修复循环（#19 A 块）

对齐上游 subagent-driven-development 的 6 个 commit。这是 #19 拆分后的 A 块 —— 注意 v1.7.1 刚对齐过 SDD，本次是那之后的新增量。

为什么脚本与文档必须整块一起改： 我们的 SKILL.md 里写的是旧签名 review-package BASE HEAD。脚本换成 plan 作用域签名后若不同步改文档，agent 会照旧签名调用直接吃 usage 错误 —— 比不同步更糟。

plan 作用域工作区（结构性修复）

原先所有计划共用 .superpowers/sdd/ 一个目录，一份过期账本被误读成当前进度会让控制者跳过整段任务序列（上游称之为观察到的最昂贵失败）。现在每个计划一个 .superpowers/sdd/<计划文件名>/，从结构上消除误读。账本新增身份行 # SDD ledger — plan: <路径>。

• sdd-workspace / review-package 在我们这边与上游 v6.1.1 字节一致（从未汉化），直接取上游版
• task-brief 只手工应用上游那两处改动，保留 fork 适配（awk 同时匹配 Task N 与 任务 N，因为本仓库 writing-plans 产出中文标题）

SKILL.md 全面重写（平铺 14 节 → 生命周期结构）

• 修复循环：一轮 = 一次修复分派 + 一次定向复审，每任务上限五轮。第 1-3 轮唤回原实现者（context 完整），第 4-5 轮换全新实现者 + 高一档模型
• 熔断：第 5 轮仍有未解决发现则停止分派，逐条裁定 —— 搁置（附裁定）或在承重项上 BLOCKED。只在上限处裁定，提早裁定等于换名字的预先定性
• Minor 发现与「计划要求的」发现两条路在循环外
• 新增「常见的合理化借口」表取代原「红线」清单
• 新增 re-review-prompt.md（106 行全文翻译）

🧹 清除 v1.7.1 遗留的生成产物

三个 SDD 文件末尾都残留着 </content> —— v1.7.1 那次重写（PR #108, d7885ca）留下的，上游没有。这些文件会整体进 agent 的 prompt，属于污染。已全部清除并全仓扫描确认无同类残留。

✅ 验证（含行为 eval）

结构性核对

• 章节结构与上游 14 节一一对应；superpowers: 引用集与上游完全一致
• 26 项关键技术记号（脚本签名、账本行格式、四种状态、ADDRESSED/NOT ADDRESSED、数值门槛）逐一确认存在，无漏译
• 两个 dot 图节点/边数与上游精确一致（6/6 与 23/28），且无幽灵节点、无孤立节点 —— 手工翻译 dot 标签最易在边里写错，会静默产生幽灵节点

脚本实测（临时 git 仓库）

• 两个计划各得独立目录；往 A 计划写 ledger 后 B 计划目录仍为空（关键回归）
• .gitignore 落在 .superpowers/sdd/ 层且 git status 干净
• 中文「任务 2」与英文「Task 3」经新路径均抽取成功
• review-package 旧签名正确报 usage 错误

行为 eval —— 新机制 7 个场景全对

考察译文是否真的传达了新规则（第 2 轮该唤回还是换新、第 4 轮模型档位、第 5 轮能否再开一轮、承重发现该搁置还是停下、Minor 走哪条路、遇到别的计划的账本怎么办、控制者能否自己修）：7/7 正确，连「运行环境无法唤回时才改派全新实现者」这个细节都答出。

集成 eval —— 真实 agent 的准备阶段

用 tests/subagent-driven-dev/go-fractals 脚手架跑真实执行的准备阶段，验证 agent 是否按新签名调脚本（旧习惯可能让它省掉 PLAN_FILE）：

• ✔ 实际调用 sdd-workspace plan.md，带上了 PLAN_FILE 参数
• ✔ 同时检查了 plan 作用域账本和旧扁平路径的游离账本
• ✔ 账本第一行为正确的身份行
• ✔ 工作区落在 .superpowers/sdd/plan/，未在旧扁平路径写账本
• ✔ 起飞前冲突扫描产出 5 条打包成一次的提问（而非逐条打断）
• ✔ 建了 10 条待办，并按指令在分派实现者前停下

回归：scripts/audit.sh 150 pass / 0 fail、scripts/verify-release.sh 82 pass / 0 fail。SDD 已从 audit 的上游漂移警告里消失（结构层级现已对齐）。

audit PASS 由 153 降至 150，是上游有意删除 Integration 一节（原列 executing-plans / test-driven-development / writing-plans 三个引用）导致 Category 4b 少 3 项引用检查，非静默跳过。

---

v1.7.3 (2026-08-07)

🐛 同步上游两处纯代码修复（对齐 v6.1.1 → v6.2.0 时挑出）

两个文件在我们这边都与上游 v6.1.1 字节一致（从未汉化改动），因此可直接取上游版 —— 无需翻译、无需 eval。

• hooks/hooks.json 加 "shell": "bash"（上游 5151e7a）：SessionStart hook 在 Windows 上原先不经 Git Bash 分发。我们的 hooks.json 与上游除这一行外完全相同。这条直接改善 Windows 用户的 bootstrap 可靠性 —— bootstrap 不加载，skill 就是死重。
• skills/systematic-debugging/find-polluter.sh（上游 6015d37、c8921b5）：修三个真 bug，已逐个实测新旧版对比：
  • pattern 带 ./ 前缀时匹配不到（find . 输出 ./ 前缀路径）：旧 1 个 → 新 2 个
  • -path 的 **/ 无法匹配零层目录，src/**/*.test.ts 漏掉 src/top.test.ts：旧 1 个 → 新 2 个
  • 完全无匹配时计数为 1 而非 0（echo 空串仍算一行）：旧 1 → 新 0

🧪 新增工具计数一致性检查（audit Category 5，+24 项）

加一款工具要同步简繁 README（各 6 处）、package.json、CLAUDE.md、site/build.mjs（三语言 15 处）、3 份 plugin manifest —— v1.7.2 全靠人工 grep 才没漏。现在从 installer 的 TARGETS 推导期望值并逐处断言，另加两条结构性检查：README 工具表行数必须等于宣称数、Category 2 实际测试的工具数必须等于宣称数（宣称了就必须测）。

已验证会拦：把标题改成 23 款、删掉一行工具表，两种漂移都被抓到。

口径写进注释：TARGETS 是「安装目标」共 21 个；Copilot CLI 与 CC 共用 .claude/skills（别名映射过去）不占独立条目，但文案里作为独立产品单独计数，所以「文案数 = TARGETS 数 + 1 = 22」。

🐛 修 bash 3.2 下 CJK 报错信息乱码

macOS 自带 bash 3.2.57 解析标识符时不识别多字节字符，$file「 会把「的首字节 0xE3 吞进变量名，导致变量展开为空且字符被截断。报错信息变成「计数不一致: <20><><EFBFBD><EFBFBD>= <20><>应为 22」—— 只在检查失败时才暴露，写检查的人看不到。

复现：bash -c 'f=README.md; echo "文件: $f「标签」结束"' → 文件: <20><>标签」结束

修法是给紧跟 CJK 标点的变量加花括号。全仓扫描 $var 紧跟非 ASCII 字节的模式，命中 3 处（audit.sh 2 处、verify-release.sh 1 处 —— 后者因为检测项一直全通过，从没暴露过）。

🧹 其他

• .gitignore 补上 .cline/、.clinerules/、.kilocode/ —— 与 .trae/、.qoder/ 一致，避免在本仓库内自测安装器留下未跟踪文件。
• 官网 site/build.mjs 工具计数 20 → 22，三语言 FAQ 枚举补入 Cline、Kilo Code（v1.7.2 发了但站点没跟）。

✅ 验证

• scripts/audit.sh：153 pass / 0 fail（3 项 warn 为上游漂移，见 #19）
• scripts/verify-release.sh：82 pass / 0 fail
• SessionStart hook 冒烟：退出码 0，输出正确的 SessionStart JSON
• npm 包端到端：pack → 从 tarball 安装 → 真实跑安装器 → 卸载零残留

⚠️ audit 的上游漂移 warn 从 2 条变 3 条（新增 using-git-worktrees），且 executing-plans / finishing-a-development-branch 的上游 H 值有变化 —— 这是本次 git fetch upstream 把对比基准从旧快照更新到 v6.2.0 导致的，不是代码改动引起。

---

v1.7.2 (2026-08-07)

🆕 新增 Cline 与 Kilo Code 适配（工具数 20 → 22，关 #112、#88）

两款都是 VS Code 扩展，加载的是 rules 而非懒加载的 skills —— rules 会并入每一轮 system prompt。照搬「把 20 个 SKILL.md 复制进规则目录」会让每轮对话背着 182 KB 常驻开销（Cline 官方也提示规则超约 300 行后遵守度下降）。

改用仓库既有的 Trae 模式：规则目录只放一份索引（核心规则 + 20 个 skill 的名称/触发条件表，实测 4.5 KB，比全量塞入小 40 倍），skills 本体放各自 skills/ 目录由 agent 按需读取。

• Cline：skills → .cline/skills/，索引 → .clinerules/superpowers-zh.md。不写 YAML frontmatter —— Cline 目前只支持 paths 一个条件字段，无 frontmatter 即始终生效。索引保持在 .clinerules/ 根层单文件（子目录是否递归扫描官方未说明）。
• Kilo Code：skills → .kilocode/skills/，索引 → .kilocode/rules/superpowers-zh.md。有意不走 v7 推荐的 .kilo/rules/ + kilo.jsonc —— 后者需把路径登记进用户的 kilo.jsonc（带注释的 JSONC，安装器安全合并容易改坏用户配置）。官方明确 .kilocode/rules/ 向后兼容且零配置生效，故选它；docs 里写明了想迁到 v7 该改哪一行，以及万一没生效如何反馈。
• 两者均无 --global：Cline 全局 rules 路径随 OS 变（~/Documents/Cline/Rules，Linux/WSL 还有 ~/Cline/Rules 回退），Kilo 全局同样要走 kilo.jsonc 登记 —— 不是通用复制机制能可靠命中的，--global 明确拒绝并指向 docs，绝不写无效路径。
• 路径依据：docs.cline.bot、kilo.ai。

🔧 检测落空时给出针对性建议（关 #48）

装了 opencode / codex 但项目里没留下标记目录时，原先只报「未检测到任何已知 AI 编程工具」，用户无从判断下一步。

• 新增 PATH 探测：检测落空时扫 PATH 找已安装的 CLI，直接打印可复制的 --tool 命令。
• 只提示、不自动安装 —— 自动装错工具正是 #33 修掉的问题：PATH 上装了不代表这个项目要用它。
• isOnPath() 只查文件是否存在，不 spawn 进程（不在用户机器上执行探测命令）；Windows 下遍历 PATHEXT。
• --global 模式只建议支持全局的工具，不推荐装不了的。
• 健壮性已测：PATH 为空 / 含空段 / 未定义三种退化情形均优雅退出 1，无未捕获异常。

📄 文档

• 补充 plugin marketplace 安装方式（关 #39）：.claude-plugin/marketplace.json 从 v1.7.x 起就存在且可用，但 README 从未写过怎么用。已实测 plugin validate / marketplace add jnMetaCode/superpowers-zh（GitHub 直连克隆）/ plugin install 全链路通过，安装缓存内含全部 20 个 SKILL.md。简繁 README 新增「方式二」，原手动安装与配置文件引用顺延为方式三 / 四。
• 修正 Copilot CLI 在 Windows 的工具面（关 #93）：copilot-tools.md 原先只记 bash + async:true 一套，但 Windows 实测（Copilot CLI 1.0.69-1）注册的是 powershell + detach，没有 bash/async 家族。现拆成两张表并注明「两套不会同时出现」，补充两个坑：.sh 需显式走 Git Bash；stop_powershell 停不掉 detach:true 的进程，需按真实 Windows PID（非 MSYS PID）Stop-Process。
• 新增 docs/README.cline.md、docs/README.kilocode.md。
• 修正 installer 报错文案里失效的章节锚点（改为指向父级 #快速开始，不再依赖会变的章节编号）。
• 计数 20 → 22 同步：简繁 README、package.json、CLAUDE.md、3 份 plugin manifest。

✅ 验证

• scripts/audit.sh：130 pass / 0 fail（2 项 warn 为既有上游漂移，见 #19）
• 发版前深度验证（比 audit 严，断言实际落盘而非只看退出码）：82 项全通过
  • 22 款工具：装 → 断言 20 个 skill 落盘 → 二次装幂等 → 卸载后零残留；无 skills/skills 嵌套
  • 19 个检测标记逐一验证只触发预期工具，既有 20 款检测结果与改动前一致
  • --global：7 款成功、14 款明确拒绝且退出码 1；拒绝信息引用的 8 份 docs 均存在
  • bootstrap 索引断言：表行数 = 20、无空 description、Cline 无 frontmatter、路径指向正确
• npm 包端到端：npm pack → 从 tarball 装 → 用打包后的二进制真实跑 Cline 自动检测 → 20 skills + 索引生成 → 卸载零残留

---

v1.7.0 (2026-07-13)

🆕 新增两款国产 IDE 工具支持（工具数 18 → 20）

• CodeBuddy（腾讯 AI IDE，关 #18 / #75）：.codebuddy/skills/ + CODEBUDDY.md bootstrap，加载机制类似 Claude Code。仅项目级（用户级加载路径未证实，暂不做全局）。
• 华为云码道 CodeArts（关 #20）：.codeartsdoer/skills/，skills-only 适配（其 bootstrap/指令文件约定未证实，靠 CodeArts 自身 skill 发现；docs 已说明，不自动触发可手动点名 skill）。
• 两者均逐一核对配置来源（owner 核实 / 用户实测），不臆造无效路径。工具计数在 README / 站点 / package / FAQ / audit 全量同步。

🌐 官网 + README 多语言（新增繁体）

• 官网（#100）重构为 LANGS 语言列表驱动，新增繁体中文站（zh-Hant）：63 页（3 语言 × (首页 + 20 skill 详情)），语言切换器 / hreflang / sitemap 齐全；以后加语言只需加一项 + 一个翻译对象。
• README（#101）加语言切换栏，新增完整 README.zh-Hant.md（353 行对齐，台港自然术语）。
• 繁体均手写（台港术语：程式碼 / 專案 / 除錯 / 全域 / 檔案 等），不引入 OpenCC 依赖。日文按定位不纳入本仓库（应作独立 superpowers-ja）。

🧹 官网下架赞助商展示

• 移除官网与 README 的赞助商板块（含 5Cookie Code 展示卡 / logo / 样式 / 资源），仅保留一行赞助联系方式；官网切自定义域名 sp.aiolaola.com。

🌍 全局安装（关 #21）

新增 npx superpowers-zh --global，一次安装、所有项目共享，解决多项目用户需要逐个项目重复安装的痛点。

• 项目级（默认）不变：装到 process.cwd() 下工具目录（如 .claude/skills），仅当前项目生效。
• 全局（--global）：装到工具的用户级目录（如 ~/.claude/skills），所有项目自动共享，更新只需重装一次。项目级优先、全局兜底，二者可共存。
• 支持全局的工具（逐一核对各工具 docs 声明的真实加载路径，不臆造）：Claude Code / Codex CLI / Qoder / Windsurf / Qwen Code / OpenClaw / OpenCode。其中 Codex 全局装到 ~/.agents/skills（docs 确认 Codex 启动扫描该目录，而非 ~/.codex/skills）；Claude Code 全局 bootstrap 写 ~/.claude/CLAUDE.md。
• Gemini CLI / Antigravity 有意不纳入通用 --global：Gemini 全局走扩展目录 ~/.gemini/extensions/*/skills/ + manifest、Antigravity 全局 skills 路径未在 docs 证实，通用复制机制覆盖不了 —— --global 会报错并指向各自 docs/README.*.md，避免「装了不生效」。
• 其余工具（Cursor / Kiro / Trae / Aider / DeerFlow / VS Code / Hermes / Claw）规则是项目级或存于应用内设置，--global 明确报错并提示改用项目级，绝不写入无效路径。
• 卸载对称支持：--global --uninstall 从用户级目录移除 skills 并按哨兵精确清理全局 bootstrap。
• home 目录护栏调整：项目级仍拒绝在 ~ 下裸装（污染所有项目），并在提示里引导改用 --global；全局模式本就写用户级目录，跳过该护栏。

📊 文案刷新

• 上游 star 数 233k+ → 250k+（站点、README、package.json description 同步，实测上游已达 252k+）。

v1.6.1 (2026-07-06)

对齐上游 v6.1.0 / v6.1.1 中与我们架构相关的部分。Gemini CLI 移除是上游这两个版本里改动面最大的一项，但它牵涉我们自己的营销文案（"18 款工具"）和安装器逻辑，评估后判定为独立决策，本版本不包含，留待单独讨论。

🔧 bootstrap 精简（using-superpowers/SKILL.md）

翻译并合并上游"更精简的每会话 bootstrap"重写：用简洁描述替换原有的 dot 流程图、去重"指令优先级"与"技能优先级"重复内容、去掉"技能类型"（刚性/灵活）分类章节。保留了我们 fork 特有的中国特色技能路由与多工具平台适配指引（Copilot CLI / Hermes Agent / Qoder 等，上游对应文档已删但我们仍维护）。

🐛 Codex 插件清单修复

• .codex-plugin/plugin.json 补 "hooks": {}：Codex 在清单缺少 hooks 字段时会自动 fallback 扫描 hooks/hooks.json（我们仓库里其实是 Claude Code 的 SessionStart hook），导致 Codex 用户安装时被错误注册一个不属于它的 hook 并弹出信任提示。声明空的内联 hooks: {} 可以阻止这个 fallback。
• category 由 "Coding" 改为 "Developer Tools"，对齐上游修正。
• references/codex-tools.md 修正过期的子 agent 结果工具名：wait → wait_agent（wait 现在专指 code-mode 的 exec/wait，不是子 agent 结果工具），并补充"implementer/reviewer 完成后应主动 close_agent"的提示。

未跟进项（有意为之）

• Codex 官方 marketplace 打包基础设施（scripts/package-codex-plugin.sh、.agents/plugins/marketplace.json、tests/codex/）——我们的分发方式是 npx superpowers-zh，不走这条上游官方安装通道。
• antigravity-tools.md / claude-code-tools.md 的裁剪——我们本来就没有这两个参考文件，无需处理。
• references/pi-tools.md 的精简（去掉 read/write/edit/bash 等自证性映射行）——验证时发现上游自己这个 v6.1.1 版本的裁剪会让他们自己的 tests/pi/test-pi-extension.mjs 断言（要求文件里出现 write/edit/bash 字样）测试失败，是上游未捕获的回归。为避免把这个 bug 一起同步进来，本版本保留了原有更完整的 pi-tools.md 内容。

v1.6.0 (2026-06-20)

本版本对齐上游 v6.0.0 的实质性 skill / 基础设施变更，并新增两款 harness 支持。

🆕 新增 harness 支持

• Kimi Code（#59，关 #37）—— 插件清单模型 .kimi-plugin/plugin.json：指向现有 skills/、sessionStart 会话开始自动加载 using-superpowers、skillInstructions 提供 Kimi 工具映射。安装：Kimi 插件管理器 /plugins install https://github.com/jnMetaCode/superpowers-zh。文档见 docs/README.kimi.md。
• Pi (oh-my-pi)（#60，关 #44）—— 扩展模型：package.json 的 pi 字段 + .pi/extensions/superpowers.ts（注册生命周期钩子，注入 using-superpowers bootstrap + Pi 工具映射）。文档见 docs/README.pi.md。

🔒 brainstorm 可视化伴侣安全模型（#58，同步上游 v6.0.0）

伴侣服务器重写为每会话密钥鉴权（?key= 或会话 cookie 门禁所有端点）+ 安全响应头（X-Frame-Options: DENY、CSP frame-ancestors 'none'、Cross-Origin-Resource-Policy: same-origin 等），修复旧版无鉴权时本地浏览器可读取屏幕/注入事件的缺口。Token 用 crypto.randomBytes(32)、timingSafeEqual 比较、token 文件 0o600。

🔧 其它 v6 同步

• using-git-worktrees / finishing-a-development-branch（#57）—— 移除已废弃的全局 worktree 目录 ~/.config/superpowers/worktrees/，对齐 v6.0.0。
• hooks/session-start（#58）—— 移除 legacy ~/.config/superpowers/skills 迁移警告，输出补 | cat。
• opencode 测试（#72）—— 修复 setup.sh 拷贝不存在的 lib/ 导致的测试飘红。

SDD（subagent-driven-development）的 v6 重写为性能/成本优化，需专门 eval 验证，故本版本暂未纳入（详见 #19）。

v1.5.0 (2026-05-21)

🆕 Qoder 适配（第 18 款工具，#26、#34）

Qoder 是阿里推出的 AI IDE，社区有多个用户提需求要求支持。本版本完成端到端适配：

• bin/superpowers-zh.js — TARGETS 加 Qoder（dir: .qoder/skills，detect: .qoder），TOOL_ALIASES 加 qoder
• generateQoderBootstrap() — 生成 .qoder/rules/superpowers-zh.md（trigger: always_on + alwaysApply: true），让"先头脑风暴 / 先 TDD / 先验证"等核心规则每个会话自动加载，不依赖模型对 description 的隐式匹配
• skills/using-superpowers/references/qoder-tools.md — 新增工具映射 reference（Qoder 大部分工具与 Claude Code 同名，只有 EnterPlanMode/ExitPlanMode → EnterSpecMode/ExitSpecMode 一个差异；附 Quest MCP 工具清单）
• docs/README.qoder.md — 完整安装/使用/卸载/故障排查指南
• scripts/audit.sh — TOOLS 数组加 qoder，CI 自动跑 18 款工具的 install/idempotent/uninstall 回归

安装方法：

cd /your/qoder-project
npx superpowers-zh --tool qoder     # 显式
# 或在有 .qoder/ 的项目里：
npx superpowers-zh                  # 自动检测

装完重启 Qoder，输入 / 即可看到 20 个 skill。

⚠️ Qoder Rules schema 来源说明

Qoder Rules 的 frontmatter schema（trigger: always_on / model_decision / manual）官方文档（docs.qoder.com/zh/user-guide/rules）目前未公开。本次实现的 schema 来自 GitHub 上 4 份真实社区样本（python-office、termiClaude、QoderTest、TelegramFileServer）的交叉验证。

如果 Qoder 后续改了 schema，生成的 rule 文件可能需要打开 Qoder Settings → Rules 重新选择"始终生效"类型。

🔧 文案对齐

• README、CLAUDE.md、package.json description：17 款 → 18 款
• 3 个 plugin manifest（.claude-plugin/{plugin,marketplace}.json、.cursor-plugin/plugin.json）description 同步

设计取舍：为什么用 always_on bootstrap 而非裸 skill

社区有用户（@Yanyz-ok）建议"按 AI 编程工具拆分/重写 skill"。我们刻意不走这条路：

1. skill 是工作方法论，不是工具实现 —— "先写测试再写代码"这个约束在 Claude Code、Qoder、Hermes 上落地工具不同，但方法论不变。重写会让 17 份 SKILL.md 维护负担 ×17 但本质增量 0。
2. 平台内置工具 vs skill 是嵌套关系，不是替代关系 —— Qoder/Quest 的 search_codebase、update_memory 解决"怎么做"，skill 解决"什么时候做"，模型不会混淆。
3. 上游 superpowers 明确禁止"无 eval 证据的工具专属重写" —— fork 守同样规矩。

工具映射写在 references/qoder-tools.md + docs/README.qoder.md 里就够了，不需要每个 skill 内部复制一遍。详见 issue #26 完整讨论。

Refs

• closes #26（建议新增 qoder 的支持）
• closes #34（建议支持 qoder，#26 重复）

---

v1.4.0 (2026-05-12)

本版本核心目标：修复全量质量审计发现的所有上游漂移 P0 缺陷。改动全部是"主站有的同步过来"性质，不引入主站没有的新功能。

🔴 上游同步：v5.0.6 brainstorm server 拆分（PR #30）

上游 v5.0.6（commit 9e3ed21）把 brainstorm server 的内容目录拆成 CONTENT_DIR + STATE_DIR peer 结构，但我们的 server 脚本还停在旧 SCREEN_DIR 单目录版本，导致 visual brainstorming 教程指向新路径但 server 用旧结构卡死。

• skills/brainstorming/scripts/server.cjs — 81 行 cherry-pick 同步
• skills/brainstorming/scripts/start-server.sh — 36 行同步
• skills/brainstorming/scripts/stop-server.sh — 29 行同步

修复后：所有 visual brainstorming 用户路径解析正常。

🔴 上游同步：v5.1.0 Code Review 整合（PR #30）

上游 v5.1.0 PR #1299 把 reviewer persona + checklist + dispatch 模板整合到单一 code-reviewer.md 实现 self-contained，并把 SKILL.md 里的 superpowers:code-reviewer 命名子代理引用改成 general-purpose Task + 模板路径形式。我们的版本停留在 v5.0.x 拆分式。

• skills/requesting-code-review/SKILL.md 改 4 处：3 处 superpowers:code-reviewer 引用清零；占位符从 5 个精简到 4 个对齐上游；"执行计划" 集成段从 "每批（3 个任务）后审查" 改为 "每个任务完成后或在自然 checkpoint 审查"（对齐上游 v5.1.0 subagent 节奏调整）
• skills/requesting-code-review/code-reviewer.md 完整重写为 v5.1.0 self-contained 版（H header 6/6 对齐上游）

修复后：所有走 review 流程的用户得到的指令指向 general-purpose Task 而非已废弃的命名子代理。

🔴 上游同步：v5.1.0 worktree 安全修复（PR #28）

上游 v5.1.0 #991 修复了两类 worktree 安全问题：subagent 嵌套创建 + cleanup 误删 harness-managed workspace。

• skills/using-git-worktrees/SKILL.md 全面重构：新增 Step 0 检测现有隔离（GIT_DIR/GIT_COMMON + submodule 守卫 + 同意流程）；Step 1 重组为 1a Native Tools + 1b Git Worktree Fallback + 沙盒回退；删除旧"示例工作流"段（含 /Users/jesse 硬编码）
• skills/finishing-a-development-branch/SKILL.md 全面重构：新增 Step 2 检测环境（三态表）；旧 Step 2-5 重编号为 3-6；Step 4 新增分离 HEAD 3 选项变体；Step 5 Option 1 重写（MAIN_ROOT cwd safety + merge→verify→cleanup→delete 严格排序）；Step 6 清理范围限定在 .worktrees/ / worktrees/ / ~/.config/superpowers/worktrees/，外部 harness-managed workspace 一律不动

修复后：subagent 不再嵌套创建 worktree；清理不会误删 harness-managed workspace。

🔴 平台兼容性修复：Windows Cursor hook 回归（PR #30）

hooks/hooks-cursor.json 的 command 之前被本地改成直接调 unix shell ./hooks/session-start，丢失上游的 polyglot wrapper ./hooks/run-hook.cmd session-start，Windows + Cursor 组合用户 hook 完全不触发。

• 1 行恢复上游 polyglot wrapper

修复后：Windows Cursor 用户 hook 正常触发。

🆕 防回归基建：CI 自动漂移检测（PR #31）

新增 scripts/audit.sh + .github/workflows/audit.yml，每次 PR 自动跑 4 类共 90+ 项检查：

1. 静态校验（JSON parse / SKILL.md frontmatter / symlink / hook 可执行性）
2. Installer 功能（17 款工具装/重装/卸载全跑）
3. 上游对齐（hooks 4 文件 + brainstorm scripts 3 文件 + 14 翻译 skill 结构层级 + code-reviewer.md self-contained 结构）
4. 交叉引用（README → docs/ 链接 + skill 间引用 + 装完后 .claude/skills/using-superpowers/SKILL.md 路径解析）

WARN（不阻塞）vs FAIL（阻塞）分级：本次"4 个 P0 漂"事件如果当时有这个 audit 在 CI 跑，PR 阶段就会被拦下。

未来意义：维护者下次手抖把 hooks-cursor.json 改坏 / 上游同步漏一项，CI 立刻拦下。

🔧 工具链小修

• scripts/sync-plugin-version.js 加入 gemini-extension.json（之前漏掉，导致 gemini extension manifest 卡在 1.1.6 老版本）
• package.json 的 version 钩子 git add 列表同步更新

安装路径方针澄清

本版本明确：有官方 plugin marketplace 的工具（Claude Code / Codex CLI / OpenCode / VS Code）首选 marketplace 路径，npx superpowers-zh 主要服务没有 marketplace 的工具（Cursor / Trae / Kiro / Gemini CLI / Hermes / Aider / Antigravity / Windsurf / Qwen / Claw / OpenClaw / DeerFlow 共 13 款）。fork 不再尝试给 marketplace 工具加 npx 路径的"完整支持"——它们走主站路径即可。

不在本版本范围

• executing-plans/SKILL.md 我们扩写了 105 行中文示例（主动选择，保留——是 fork 的中文优化，非漂移）
• using-superpowers/SKILL.md 的"中国特色技能路由"段（fork 增量，保留）
• 各 reviewer-prompt.md 翻译差异（结构对齐，纯翻译漂移，无行为 bug）
• open issues #18/#21/#26/#20（fork 增量需求，按方针延后）

Refs

• PR #28（worktree 安全修复）
• PR #30（brainstorm scripts + code-reviewer 整合 + hooks-cursor + SKILL.md 引用）
• PR #31（audit script + CI workflow）
• issue #19 跟踪上游 v5.0.6 / v5.1.0 同步 → 关键项目全部覆盖

---

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 与 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 一种工具。