lywsvip/superpowers-zh
1
0
Fork 0
mirror of https://github.com/jnMetaCode/superpowers-zh.git synced 2026-09-03 07:23:56 +08:00
Code Issues Packages Projects Releases Wiki Activity
206 Commits 34 Branches 46 Tags
main
Commit Graph

15 Commits

Author SHA1 Message Date
AI不止语
1081cefc42 fix(docs,site): README 把 2 个上游 skill 算成「中国特色」；二维码缺 height；官网外链没人验活 
按主站逐项核对时查出的三处，都不是新引入的，是一直没人发现。

## ① README 的「中国特色 Skills（6 个）」与官网自相矛盾

三处口径本来就不一致：

| 位置 | 原来的说法 |
|---|---|
| 官网统计块 | 4 中国原创 |
| `.claude-plugin/plugin.json` | 20 个 skills（14 翻译 + 4 中国原创 + 2 上游历史保留）|
| 两版 README | **6 个中国特色 Skills** ← 只有它是 6 |

README 把 `mcp-builder` 和 `workflow-runner` 也算进了「中国特色」。用 GitHub API 核过：
**上游 obra/superpowers 现有 14 个 skill，本仓 20 个，多出的正是 4 个 `chinese-*` 加这两个。**
它们来自上游、上游后来移除、本 fork 保留继续维护 —— 跟中国特色没有任何关系，把它们
算成中国原创等于虚报了 50% 的原创量。

改：规模表列名改「中国原创 Skills」值改 4（附注另有 2 个上游历史保留）；小节标题拆成
「中国原创（4 个）· 上游历史保留（2 个）」；表格里这两行的「上游有吗？」由「无」改为
「曾有，上游已移除」——原来写「无」会被读成「我们原创的」，正是错误的来源。简繁同步。

（`using-superpowers` 正文里的「中国特色技能路由」是真实存在的小节名，不动。）

## ② 页脚三个二维码缺 height，加载时把页脚顶下去

`<img width="158">` 没有 height，浏览器算不出宽高比，图一到位就发生布局偏移（CLS）。
赞助商 banner 和 logo 都是齐的，只有二维码漏了。

没有写死数字，而是新增零依赖的 `imageSize()`（PNG 读 IHDR、JPEG 逐段找 SOFn），
构建时从文件读真实尺寸：258×258 / 1125×1680 / 316×316，与 `sips` 实测逐一吻合。
换二维码时属性自动跟随，不会悄悄退回错的比例。

顺带用同一个函数补了一条门禁：**赞助商声明的 `w`/`h` 必须与素材真实尺寸一致** ——
换了 banner 忘了改数字，页面就会按错的宽高比预留位置。

## ③ 外链验活门禁扫不到官网，三条付费展位链接一直无人看守

`verify-release` H 段只扫 `docs/*.md` 与两版 README，`site/build.mjs` 不在列。也就是
旗舰赞助商与两个常规位的推广链接挂掉了不会有任何人知道 —— 而这是要赔的。

扫描范围加上 `site/build.mjs`，并把 `compshare|cubence` 移出排除名单（原来被当噪音跳过），
正则补 `?=&` 让带 aff/referral 参数的推广链接被完整验证而不是截断到路径。
覆盖链接 45 → 52 条。

排除名单新增 `googletagmanager|google-analytics`：它们在 build.mjs 里是 **CSP 白名单条目
不是链接**，裸域 `googletagmanager.com` 实测返回 404，纳入等于凭空造一条误报 ——
这条门禁最忌讳的就是误报。

## 反向验证（三条逐一造错，必须拦下）

- 把官网的 book.aibuzhiyu.com 改成不存在的路径 -> `死链（404）`，FAIL 1
- 把 infistar banner 的 w/h 改成 800×368 -> 构建退出码 1，
  `banner 尺寸对不上：声明 800×368，实际 1269×337`
- 二维码尺寸不再有写死数字（`width="158"` 已从源码消失）

## 全量测试

官网 66 页构建 / 站内死链 0 / 无效 href="#" 0 / **缺 height 的 img 0**（原为 3）；
audit 170 pass 0 fail；verify-release 115 pass 0 fail；CI 等价 20 skills 0 错误 v1.7.11；
tests/kimi · pi · opencode · brainstorm-server 全 PASS。
 2026-09-02 21:19:58 +08:00
AI不止语
c7713cac65 fix(verify-release): 429 被判成死链 —— 外链门禁开始误报自己人 
发版前跑 verify-release，H 段报 `死链（429）: https://windsurf.com`。手工用浏览器
UA 复核了几次，稳定 429 —— 站点活着，只是对反复验活限流。

判活口径写的是 `2*|3*|403`，把「服务器答复了但不是 200/403」一律当死。而 429 恰恰
证明 URL 存在：能限流就是能路由到资源。

这条门禁自己的立项理由是「一个会误报的门禁比没有门禁更糟：人会学会忽略它」。
它现在正在做那件事：唯一的 FAIL 每次都是同一条误报，跑几次就会开始忽略整段输出。

判活口径改为 `2*|3*|401|403|405|429` —— 都属于「答复了，只是不欢迎自动化访问」：

| 码 | 含义 | 为什么不是死 |
|---|---|---|
| 401 | 要登录 | 资源存在，只是要凭证 |
| 403 | 拒爬虫 | 原本就在白名单里 |
| 405 | 不认这个请求方式 | 服务器识别了这个路径 |
| 429 | 限流 | 能限流就是能路由到资源 |

真正的死仍然只有两种：404/410，以及连不上（curl 返回空）。

双向验证：
- 往 docs/README.aider.md 塞一条 github.com/anthropics/this-repo-does-not-exist-xyz，
  门禁照报 `死链（404）`，FAIL 1 —— 没被这次放宽削弱
- 还原后 115 pass / 0 fail
 2026-08-28 22:37:33 +08:00
AI不止语
fb63548c9d fix(installer): Codex 项目级装到 Codex 从不扫描的目录；CodeArts 补 --global 
## Codex：项目级又是「装了完全不生效」

官方 skills 文档（developers.openai.com/codex/skills，现 308 跳到官方新文档站）
给出的扫描目录**完整清单**：

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

**没有 .codex/skills。** 两次分别追问确认「.codex/skills 是否曾被扫描」，答案都是
从未出现。而我们项目级正是装到 .codex/skills。

全局（~/.agents/skills）一直是对的 —— 原注释也写明了「不是 ~/.codex/skills」，
说明当初查过全局却没顺手核项目级。改为 .agents/skills，并在安装时清理旧位置
（只清我们装的那些，用户自己放在 .codex/skills 下的不动，已实测）。

与 Antigravity 共用 .agents/skills 是 Agent Skills 开放约定，不是冲突。

## 这个改动暴露出一个既有 bug：检测有顺序依赖

改完后测试立刻报「检测 .codex/ -> 得到「Antigravity,Codex CLI」，期望「Codex CLI」」。

根因：自动检测是**边装边判**的。Codex 装到 .agents/skills 会创建 .agents/，
循环走到 Antigravity（detect: '.agents'）时它就被误判为「项目里有这个工具」，
于是多装一份。这个坑在任何「装了 A 会创建 B 的检测标记」的组合上都会犯。

改为先把所有工具的检测结果一次性算完再开始装 —— 检测必须基于**安装前**的项目
状态。实测：只有 .codex 时只装 Codex；同时有 .codex 与 .agents 时两款都装且
.agents/skills 下仍是 20 个（不重复）。

## CodeArts：官方已证实用户级路径，补上 --global

原注释只写「用户在 #20 确认」，没有官方出处。已补华为云官方用户指南出处：

    项目级：项目根目录的 ./.codeartsdoer/skills/
    个人级：%USERPROFILE%/.codeartsdoer/skills   即 ~/.codeartsdoer/skills

既然已证实，--global 从拒绝名单移出并加落盘断言。实测装 20 个到
~/.codeartsdoer/skills、卸载后 HOME 零残留。仍是 skills-only —— 其 bootstrap
约定未证实，不猜。

## 顺带核实

- Cursor：官方 skills 文档确认 .cursor/skills/<name>/SKILL.md ✅
- OpenCode：官方 skills 文档确认项目级与全局都对 ✅（唯二全对的之一）
- Kimi / Pi：不在 TARGETS 里，走 plugin manifest 与扩展分发；已确认 docs 没有
  承诺 --tool kimi/pi，installer 也正确拒绝这两个名字，无虚假承诺

audit 168 pass / 0 warn / 0 fail；verify-release 115 pass / 0 fail。
 2026-08-13 05:54:52 +08:00
AI不止语
0e3fbc4830 fix(installer): VS Code 装的 20 个文件 Copilot 一个都不读（又一个纯死重） 
## 问题

官方文档（code.visualstudio.com/docs/copilot/customization/custom-instructions）
明确 Copilot 只自动读这几处：

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

而我们把 20 个 skill 拷进 `.github/superpowers/` —— **不在其中**，而且装完
**什么引导都不写**。也就是说 VS Code 用户装完，Copilot 一个字都不会读。

旧文档更说明问题：它写着「由于 Copilot 主要通过单个指令文件工作，建议创建
.github/copilot-instructions.md 引用 skills」并给了示例 —— 我们知道需要引导，
却让用户自己动手，而绝大多数人不会照做。

## 改法

自动生成 `.github/instructions/superpowers-zh.instructions.md`：

    ---
    applyTo: "**"          # 关键：省略则只能手动挂载 = 白写
    name: Superpowers-ZH
    description: …
    ---

约 4.5 KB 的索引（核心规则 + 20 个 skill 触发条件表），正文仍留在
`.github/superpowers/` 按需读取 —— 与 Cline / Kilo / Kiro 同一套思路：applyTo "**"
的文件对每个请求都生效，正文塞进去就是每轮常驻开销。

**刻意不动用户的 .github/copilot-instructions.md** —— 那是他们的文件。用我们自己
的 .instructions.md，互不干扰，卸载也能精确删除。

检测标记补上 `.github/instructions`（用了 instructions 机制的项目都有），原来只认
`.github/copilot-instructions.md`。

## 顺带核实的两款

- **Cursor**：cursor.com/docs/skills 确认 .cursor/skills/<name>/SKILL.md 启动时
  自动发现 —— 我们是对的。
- **OpenCode**：opencode.ai/docs/skills 确认 .opencode/skills/ 与
  ~/.config/opencode/skills/ —— 项目级和全局都对。它同时扫 .claude/skills 与
  .agents/skills，已在注释里写明「装过 CC 或 Antigravity 的别重复装」。

## 验证

- 装：正确识别 -> 生成 instructions（applyTo "**"，4503 字节）+ skills 到
  .github/superpowers/
- 卸载：只删我们的，用户的 my-own.instructions.md 与 copilot-instructions.md
  原样保留
- verify-release 新增 VS Code 段（文件存在 / applyTo 断言 / 20 行索引 / 指向
  .github/superpowers/），111 -> 115 pass
- audit 168 pass / 0 warn / 0 fail
 2026-08-12 21:03:40 +08:00
AI不止语
43edf34b2c fix(installer): Windsurf 全局装错目录（装了不生效）+ 两个静默失效的检查 
## Windsurf --global 一直装在 Windsurf 不读的地方

官方文档（docs.windsurf.com/windsurf/cascade/skills）写明两个路径**不同构**：

    项目级：.windsurf/skills/<skill-name>/
    用户级：~/.codeium/windsurf/skills/<skill-name>/   ← 在 .codeium 下

我们的 --global 装到 ~/.windsurf/skills —— Windsurf 不读那里。又一个 Hermes 同款
「装了完全不生效」。项目级路径是对的，只有全局错。

Cursor 一并核实：cursor.com/docs/skills 确认 .cursor/skills/<name>/SKILL.md
启动时自动发现，无需配置 —— 我们装的是对的。

## 测试为什么没抓到：只验退出码，不验落盘位置

verify-release 的 C 段对全局白名单只断言「退出码为 0」。装到错目录退出码照样是 0。
**「跑通了」不等于「装对了」。** 新增 GLOBAL_DIR 断言：10 款全局工具逐个断言
skill 真的落在官方读的那个目录，外加一条自检（GLOBAL_DIR 必须覆盖 GLOBAL_OK 全部，
以后加全局工具不能漏断言）。

双向验证：把 Windsurf 全局路径改回旧值，立刻报
「--global windsurf: .codeium/windsurf/skills 里是 0 个 skill，期望 20」。

## 两个我自己写出来的静默失效

**① `grep -P` 不可移植。** 新加的「变量后紧跟多字节字符」检查第一版用了 grep -P，
在交互 shell 里（ugrep）看着能用，进了脚本跑的是 /usr/bin/grep（BSD grep，不支持
-P），配上 2>/dev/null 就成了永远匹配不到的死检查 —— 正是我这两天一直在修的那类
bug，自己又造了一个。改用 LC_ALL=C + ERE：C locale 下多字节按单字节处理，>0x7F
的字节落在 [^ -~] 之外，BSD/GNU 都支持。

**② 同一个全角括号坑又踩一次。** `期望 $EXPECT_SKILLS（…）` 里全角括号被吞进变量
名，set -u 下脚本半途崩掉。这已经是本仓第二次（第一次是死链检查的 $code）。所以
把它固化成 audit 1e，注释行排除，双向验证过。

## 一次操作事故（记下来）

用 /tmp 备份做变异测试时，把 verify-release.sh 的未提交改动整段覆盖没了，
git diff 才发现。变异测试应该用 git 保护现场，不该用 /tmp 拷贝。

## 其它

- 外链验活跳过分支补 ok，否则 PASS 总数随网络漂移、发版记录对不上（实测连跑两次
  稳定 111）
- docs/README.windsurf.md 重写：两个路径不同构、渐进式披露（默认只给模型 name +
  description，不造成常驻开销）、跨工具发现（也扫 .agents/skills 与 .claude/skills，
  装过 Antigravity 或 CC 的不必重复装）

audit 168 pass / 0 warn / 0 fail；verify-release 111 pass / 0 fail。
 2026-08-12 20:42:21 +08:00
AI不止语
226638b969 feat(installer): Claw Code 补 bootstrap + 文档；CodeBuddy 补 --global（官方已证实） 
核查最后两款。这两款的**路径都是对的**，问题在缺失的能力和文档。

## Claw Code

路径拿到了源码级证据（ultraworkers/claw-code）：
- rust/crates/plugins/src/lib.rs 明写 "discovers skills from local roots such as
  `.claw/skills`, `.omc/skills`, `.agents/skills`, `~/.omc/skills` …"
- USAGE.md 列出根指令文件优先级 CLAUDE.md > CLAW.md > AGENTS.md

三处缺口：

**① 没写 bootstrap。** 只装 skills，CLAW.md 一个字都没写 —— 与 Qwen Code 同款
问题，skill 能被发现但不会自动触发。已补 generateClawBootstrap。

**② 一个真实的遮蔽陷阱。** 因为优先级是 CLAUDE.md > CLAW.md，项目里若已有
CLAUDE.md（不少工具都会生成它），就可能压过我们刚写的 CLAW.md，表现为「装了
不触发」。安装器现在检测到这种情况会主动提示，并给出解法（让 CLAUDE.md 也带
引导）。这种坑不说清楚，用户只会以为我们的东西不好使。

**③ 23 款工具里唯一没有安装文档的一款。** 已补 docs/README.claw.md，含上面两条
源码出处、遮蔽陷阱说明，以及一条实用提醒：claw 也扫 .agents/skills，装过
Antigravity 的项目其实已经能读到，再装会加载两份。

## CodeBuddy

路径和 bootstrap 都对（官方 codebuddy.cn/docs/cli/skills 与 /codebuddy-dir 确认
.codebuddy/skills/ + CODEBUDDY.md）。但我们的文档写着：

> 目前仅支持项目级安装。CodeBuddy 的用户级（全局）skills 加载路径尚未验证。

现已核实 —— 官方目录结构文档确认全局与项目级同构：

    skills   ~/.codebuddy/skills/       .codebuddy/skills/
    记忆文件  ~/.codebuddy/CODEBUDDY.md   项目根 CODEBUDDY.md（两处等价）
    优先级   项目级 > 用户级 > 插件级

已补 --global 支持：TARGETS 加 global、bootstrap 支持 isGlobal（全局写
~/.codebuddy/CODEBUDDY.md）、全局卸载清单加上它。文档链接一并从
copilot.tencent.com 换成官方文档域名 codebuddy.cn。

## 验证

- Claw 项目级：装 -> CLAW.md 生成 -> 卸载零残留；已有 CLAUDE.md 时正确给出提示
- CodeBuddy 全局：装到 ~/.codebuddy/skills + ~/.codebuddy/CODEBUDDY.md，
  bootstrap 内容指向 ~/.codebuddy/skills/，卸载后 HOME 零残留
- CodeBuddy 项目级不受影响，仍指向 .codebuddy/skills/
- verify-release 白名单 codebuddy 由「应拒绝」移到「应成功」，110 pass / 0 fail
- audit 167 pass / 0 warn / 0 fail（新增 docs/README.claw.md 进交叉引用检查）
 2026-08-12 19:48:14 +08:00
AI不止语
49c2e3a205 fix(installer): DeerFlow 检测标记不存在（Aider 同款）+ 文档里一个查无实据的环境变量 
## 安装路径是对的

官方文档（bytedance-deer-flow.mintlify.app/concepts/skills）确认 DeerFlow 自动
扫描两个**写死**的目录找 SKILL.md：

    for base_dir in ["skills/public", "skills/custom"]:

public 是自带的、进 git；custom 是用户装的、默认被 gitignore。无任何配置项。
我们装到 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 是同一个毛病：真实检出从来没被自动检测
到过，用户必须手动 --tool deerflow。

改认 skills/public —— 它是 skills 机制本身、随仓库版本控制，任何 DeerFlow 检出
都有；deer_flow 保留作 1.x 兼容。实测模拟真实检出（skills/public + backend +
frontend）能正确识别为 DeerFlow 并装进 skills/custom/。

## 文档里一个查无实据的环境变量

旧文档给了 `export DEERFLOW_SKILLS_DIR=...` 的写法，容易被读成「DeerFlow 认这个
环境变量」。官方文档里没有它，目录是写死的。已删除，改为直接用绝对路径。

顺带补上原文档没说的两件事：容器挂载（skill 在沙箱里跑，两个目录挂到
/mnt/skills/，附属脚本要写容器内路径），以及由此带来的限制 —— brainstorming
的可视化伴侣是宿主机 harness 用的，在 DeerFlow 容器沙箱里不可用。

## 验证

- 模拟真实 DeerFlow 检出：自动识别 -> skills/custom/
- 卸载精确：只删我们装的 20 个，skills/public/ 与用户自建的 custom skill 不动
- verify-release B 段补 skills/public 标记，109 -> 110 pass
- audit 166 pass / 0 warn / 0 fail
 2026-08-12 19:42:04 +08:00
AI不止语
033adc3768 fix(docs): 4 条死链，其中 2 条是编造的仓库地址；新增外链验活门禁 
核查 OpenClaw 时发现 docs/README.openclaw.md 链的是
github.com/anthropics/openclaw —— **那个仓库不存在（404）**，真正的是
openclaw/openclaw。顺手全仓扫了一遍外链，45 条里 4 条是死的。

## 修掉的 4 条

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

前两条是**编造出来的出处**。这比没有出处更坏：它让人以为核实过了。

## OpenClaw 本身：路径是对的

顺带核实完了。docs.openclaw.ai/tools/skills 确认 `<workspace>/skills` 为最高
优先级、`~/.openclaw/skills` 为全局，自动发现无需配置，与我们装的一致。

## 固化成检查（verify-release H 段）

编造链接不该靠人肉发现。新增外链验活，两遍制：

- 第一遍 xargs -P 10 并行快扫，只产出「嫌疑名单」，**不下结论**
- 第二遍对嫌疑名单串行复核，放宽到 25s 并让 curl 自己重试；两遍都判死才算死

两遍制不是过度设计 —— 第一版单遍串行把整个脚本拖到超时跑挂了；改并行后又实测
到 docs.codeium.com 在 8s 上限下偶发超时、误报成死链。**一个会误报的门禁比没有
门禁更糟：人会学会忽略它。** 连跑 3 次确认稳定，全绿。

无网络时整段跳过，不阻塞离线发版。

顺带修了个 bash 坑：`bad "死链（$code）: $u"` 里全角括号会被当成变量名的一部分，
报 `code�: unbound variable`。改用 ${code} 花括号界定。

双向验证：塞一条 github.com/anthropics/this-repo-does-not-exist 会被抓出并 FAIL，
移除后恢复全绿。

verify-release 108 -> 109 pass；audit 166 pass / 0 warn / 0 fail。
 2026-08-12 19:34:16 +08:00
AI不止语
b01a91c267 fix(installer): Qwen Code 缺 bootstrap（skill 是死重）+ 文档把产品搞混了 
核查第五款。路径本身是对的 —— 这是查过的几款里第一个没装错地方的。但另有
两个问题。

## ① 我们把产品搞混了

docs 标题写「Qwen Code (通义灵码)」，链接指向 tongyi.aliyun.com；README 里
把它标成「IDE 插件」。

实际：Qwen Code 是 QwenLM/qwen-code 这个**命令行工具**（Gemini CLI 的 fork），
跑在终端里。通义灵码是阿里的 IDE 插件，**是另一个产品**，配置路径完全不同。
照着我们的文档去配通义灵码是配不通的。

这跟 #119 的 Qoder 表「没标产品面」是同一类错误：把两个不同产品面的东西
混成一份说明。docs 与简繁 README 一并更正（类型也从「IDE 插件」改回 CLI）。

## ② 只装 skills、不写 bootstrap —— skill 是死重

实测装完项目里只有 .qwen/skills/，一个引导文件都没写。而 Claude 写 CLAUDE.md、
Gemini 写 GEMINI.md，Qwen Code 的对应物 QWEN.md 我们完全没用。

按上游的原则：没有 bootstrap，skill 就是死重 —— 文件在磁盘上但很少被调用。

两套机制都查了官方文档：
- skills：qwenlm.github.io/.../features/skills/ 确认 .qwen/skills/ 与
  ~/.qwen/skills/ 自动发现，无需配置
- QWEN.md：分层记忆的默认上下文文件就是 QWEN.md，从 cwd 逐层向上到项目根、
  以及全局 ~/.qwen/ 都会被扫描并拼接（可用 contextFileName 改名）

已补 generateQwenBootstrap，复用 Gemini 那套结构：项目级写 ./QWEN.md，全局写
~/.qwen/QWEN.md；已有文件则用哨兵注释追加而不覆盖。

顺带补上全局卸载的缺口：qwen 在 GLOBAL_OK 里，--global 会写 ~/.qwen/QWEN.md，
原来 GLOBAL_BOOTSTRAP_CLEAN_SECTION 只有 .claude/CLAUDE.md，装卸一轮会在用户
主目录留残留。

## 验证

- 项目级：已有 QWEN.md 时追加，卸载后逐字节恢复用户内容
- 全局：写 ~/.qwen/QWEN.md，卸载后 HOME 下残留 0 个文件
- verify-release 新增 Qwen 段（bootstrap 写入 / 不覆盖用户内容 / 指向
  .qwen/skills/ / 卸载切除干净 / 不误删用户内容 / 全局零残留），101 -> 108 pass
- audit.sh 166 pass / 0 warn / 0 fail

## 范围

installer、docs、简繁 README、verify-release 均为 fork 自有，零上游偏离。
 2026-08-12 19:17:26 +08:00
AI不止语
ad32b2546b fix(installer): Kiro 把 335 KB 塞进每一轮对话 —— 改为索引式（Aider 的反面） 
继 Aider 之后核查 Kiro。这次的错跟 Aider 正好相反：不是不加载，是**全部加载、
每一轮都加载**。

## 问题

Kiro 官方文档（kiro.dev/docs/steering）明确：`.kiro/steering/` 下的文件默认
`inclusion: always`，"loaded into every Kiro interaction automatically"。

而我们把 20 个 skill 的正文整个装进了 `.kiro/steering/`。实测：

    47 个 md 文件 / 342914 字节 ≈ 335 KB —— 每轮对话全量进上下文

这跟我们当初给 Cline / Kilo Code 修的是同一个问题（那次是 182 KB），解法当时
就设计好了，只是没意识到 Kiro 的 steering 也是常驻性质。

## 改法：照搬 Cline / Kilo 的索引式

- skills 正文改装 `.kiro/skills/`（不被自动加载）
- `.kiro/steering/superpowers-zh.md` 只放索引：核心规则 + 20 个 skill 的触发
  条件表，带 `inclusion: always`

335 KB -> 4.4 KB，76 倍。

## 升级路径（这条最要紧）

老用户通常直接重装而不会先卸载。不清旧布局的话新旧两份并存，335 KB 一点没减 ——
那这次修了等于没修。所以安装时先清 `.kiro/steering/` 下与我们 skill 同名的目录，
并打印清理了几个；卸载同样处理（LEGACY_SKILL_DIRS）。

只删同名目录，**用户自己写的 steering 文件不动** —— 已实测。

## 文档里两个编造的 frontmatter 键

docs/README.kiro.md 写着加载模式是 `alwaysApply: true` 和 `globs: "*.ts"` ——
这两个键 Kiro 文档里**根本不存在**，是 Cursor / Trae 的约定被误写成了 Kiro 的。
Kiro 实际用 inclusion / fileMatchPattern。已按官方文档重写整篇，并补上默认值
就是 always 这一条（这正是 335 KB 的成因）。

## 回归守卫

verify-release.sh 新增 Kiro 段：索引存在、带 inclusion: always、20 行表、指向
.kiro/skills/，以及两条硬守卫 ——
  - steering 下只能有 1 个 md
  - steering 常驻总字节 < 20 KB
外加升级路径断言：旧布局必须被清、用户自己的文件必须保留。
双向验证过：模拟退回旧布局后两条断言都会失败。

verify-release 93 -> 101 pass。

## 验证

- 全新装：steering 1 个文件 4437 字节，.kiro/skills/ 下 20 个 skill
- 从旧布局升级：342971 -> 4494 字节，清理 20 个旧目录，用户文件保留
- 卸载：零残留，用户 steering 文件逐字节保留
- audit.sh 166 pass / 0 warn / 0 fail、verify-release.sh 101 pass / 0 fail

## 范围

installer、docs、README 简繁、verify-release 均为 fork 自有，零上游偏离。
 2026-08-12 18:58:54 +08:00
AI不止语
be6dc8c252 fix(installer): Aider 支持有两个都会导致「装了不生效」的错（#45 同类） 
顺着 #45（Hermes 装错目录）和 #119（Qoder 映射表是编的）这条线，系统查了
我们自己那层工具支持。Aider 查出两处，都实测坐实，都是「装完看着成功、
实际不生效」。

## ① 真实 Aider 项目从来没被自动检测到过

detect 写的是 '.aider'，即要求存在一个 `.aider/` 目录 —— 而 **Aider 不创建
这个目录**。它在项目根留下的是 `.aider.` 前缀的产物：

  .aider.conf.yml / .aider.chat.history.md / .aider.tags.cache.v3/

实测：造一个含这三样的目录跑 `npx superpowers-zh`，输出「未检测到任何已知
AI 编程工具」。而 docs/README.aider.md 一直写着「会自动检测 .aider.conf.yml
文件」—— 文档描述的是意图，代码做的是另一回事。

改为认这四个标记（保留 '.aider' 兼容）。

## ② CONVENTIONS.md 不会被 Aider 自动加载

代码注释和文档都写着「Aider 原生支持自动加载此文件」。官方文档
（aider.chat/docs/usage/conventions.html）说的是反的：必须
`aider --read CONVENTIONS.md`，或在 .aider.conf.yml 里写 `read: CONVENTIONS.md`。

最糟的是 docs 的「Skills 未生效」排障第 3 条写着「Aider 会自动读取
CONVENTIONS.md，无需额外配置」—— 用户卡住时来查文档，看到的正好是让他
继续卡住的那句。

改法照搬 #45 的做法：装完打印可直接用的两种激活方式，**不替用户改
.aider.conf.yml**（那是他们的文件）。docs 开头重写，把「还需一步」放最前面，
并注明 v1.7.9 及更早的说法是错的。

## 测试的盲区

verify-release.sh 的检测测试是 `mkdir .aider` 然后断言认出 Aider —— 拿代码
测代码，真实标记一个都没测。已补三个真实标记；顺带修了 case 分支：.yml 也
要按文件建，用目录冒充文件等于测了个假场景。

verify-release 90 -> 93 pass。

## 验证

- 只有 .aider.conf.yml 的目录：正确识别为 Aider，并打印激活提示
- 已有自写 CONVENTIONS.md：追加而不覆盖；卸载后逐字节恢复原内容
- 卸载：.aider 下残留 0 项
- audit.sh 166 pass / 0 warn / 0 fail、verify-release.sh 93 pass / 0 fail

## 范围

bin/superpowers-zh.js、docs/README.aider.md、scripts/verify-release.sh 均为
fork 自有（上游没有 installer 与 docs），零上游偏离。
 2026-08-12 18:03:28 +08:00
AI不止语
441d024cd6 fix(installer): Hermes 支持一直是坏的 —— 改为全局安装并给出可粘贴配置（#45） 
## 我们装错了目录，一直没生效

#45 报告人说「项目级 .hermes/skills/ 里的 20 个 skill 全部返回 404，必须手动
复制到 ~/.hermes/skills/ 才被识别」。查官方文档核实，他是对的：

hermes-agent.nousresearch.com/docs/user-guide/features/skills 明确
Hermes 只自动加载 ~/.hermes/skills/（原文 "the primary directory and source
of truth"），项目级目录不被自动发现；外部目录必须写进 ~/.hermes/config.yaml
的 skills.external_dirs。

而我们从支持 Hermes 起就只装项目级 .hermes/skills/ —— 那个目录 Hermes 根本
不读。这不是「不好用」，是「装了完全不生效」，比不支持更糟。

## 改法

- TARGETS 给 Hermes 加 global（~/.hermes/skills），全局成为推荐装法
- 项目级仍保留（skills 可随仓库分发），但装完打印**可直接粘贴**的配置片段：
      skills:
        external_dirs:
          - <项目绝对路径>/.hermes/skills
  不替用户改 config.yaml —— 那是他们的文件。文档里也写明「配置里不存在的
  路径会被静默跳过」，所以写错不会报错、只会没生效。
- 全局模式**不写 bootstrap**：Hermes 的用户级指令文件约定没有公开文档，
  往 $HOME 根目录写 HERMES.md 是猜路径 + 污染主目录。实测确认全局装完
  $HOME 根目录 0 个文件、卸载 0 残留。

## 文档与清单

- docs/README.hermes.md 开头重写，把「必须全局」放在最前面，并注明
  v1.7.8 及更早只支持项目级 = 装了不生效，是我们的实现错误
- 简繁 README：全局支持清单加 Hermes Agent，工具表的安装命令改为 --global
- verify-release.sh 的 GLOBAL_OK 加 hermes、GLOBAL_NO 移除

## 验证

- 全局：装 20 skills 到 ~/.hermes/skills、$HOME 根目录 0 文件、卸载 0 残留
- 项目级：正确打印 A/B 两种方案与绝对路径的 config.yaml 片段
- audit.sh 166 pass / 0 warn / 0 fail、verify-release.sh 90 pass / 0 fail

注：#45 的后半部分（7 个 skill 文件里 24 处硬编码 Claude 工具名）本次未动。
那属于行为塑造内容，且 references/hermes-tools.md 已有完整映射表，
应走「强化映射表引用」而非把正文改成某个 harness 专属工具名。
 2026-08-08 14:55:21 +08:00
AI不止语
8a2f37071a feat(installer): 新增 Crush 适配（23 款工具，#40）；补齐 verify-release 覆盖盲区 
## Crush（#40）

查权威源（charmbracelet/crush repo 文档）确认：Crush 遵循 Agent Skills 开放标准，
项目级**自动发现** .crush/skills、.agents/skills、.claude/skills、.cursor/skills
四个目录，无需任何配置；用户级为 ~/.config/crush/skills。

重要副作用写进了 docs：已经为 CC / Cursor / Codex / Antigravity 装过的用户，
Crush 现在就已经能读到那些 skills，此时不要再装 --tool crush，否则同一批
skills 会有两份、被重复加载。docs 里给了确认命令。

- TARGETS 加 Crush（detect: .crush / crush.json / .crush.json），支持 --global
- CLI_PROBES 加 crush（它是 CLI，PATH 探得到）
- skills-only 适配，不需要 bootstrap；不动用户的 crush.json
- 新增 docs/README.crush.md
- 计数 22 -> 23（installer TARGETS 22 条 + Copilot CLI 单独计）

实测：装 20 skills / 二次装幂等 / 卸载零残留且正确保留用户的 crush.json；
--global 装到 ~/.config/crush/skills 并可干净卸载。

## audit Category 5 当场抓到我漏改的 5 处

加计数时忘了 site/build.mjs 的 5 个位置（三语言标语 + FAQ 枚举）。上个版本
新加的计数一致性检查直接 FAIL 拦下 —— 这是它第一次在真实改动中生效。已补
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 项。

回归：audit.sh 152 pass / 0 warn / 0 fail、verify-release.sh 90 pass / 0 fail
 2026-08-08 06:14:48 +08:00
AI不止语
1321cc65fb test(audit): 新增工具计数一致性检查；修 bash 3.2 下 CJK 报错信息乱码 
审核 v1.7.2 时发现三个问题，一并修掉。

1) 工具计数散落十几处，没有任何检查兜着（audit 新增 Category 5，+24 项）

加一款工具要同步简繁 README（各 6 处）、package.json、CLAUDE.md、
site/build.mjs（三语言 15 处）、3 份 plugin manifest —— 这次全靠人工 grep 才
没漏。现在改为从 installer 的 TARGETS 推导期望值并逐处断言。

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

除逐处计数外还加了两条结构性断言：
- README 工具表的实际表格行数必须等于宣称数（防漏加/多加行）
- Category 2 实际回归测试的工具数必须等于宣称数（宣称了就必须测）

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

2) bash 3.2 下 CJK 报错信息乱码（真 bug，只在检查失败时才暴露）

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

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

修法是给紧跟 CJK 标点的变量加花括号。全仓扫描 `$var` 紧跟非 ASCII 字节的模式，
命中 3 处：audit.sh 2 处（本次新增）、verify-release.sh 1 处（上个提交带进来的，
因为检测项一直全通过所以从没暴露）。修后报错信息可读：
  计数不一致: README.md「工具表标题」= 23，应为 22
  检测 .clinerules/ -> 得到「Cline」，期望「错误期望值」

3) .gitignore 漏了新工具的安装产物

.trae/、.qoder/ 等都在忽略列表里，但 .cline/、.clinerules/、.kilocode/ 没加 ——
在本仓库内跑安装器自测会留一堆未跟踪文件。已补上并验证 git status 干净。

验证：audit.sh 154 pass / 0 fail（原 130，+24 为 Category 5）
      verify-release.sh 82 pass / 0 fail
 2026-08-07 21:54:48 +08:00
AI不止语
da6c6b082d chore(release): v1.7.2 —— Cline / Kilo Code 适配 + 检测落空建议 + marketplace 文档 
版本号：7 份声明文件全部 1.7.1 -> 1.7.2（按 .version-bump.json 逐一核对一致）。
注：本机没装 jq，scripts/bump-version.sh 跑不了，改用等价的逐字面量替换，
只动 "version" 那一行，未重排任何 JSON（已 diff 确认）。

新增 scripts/verify-release.sh —— 发版前深度验证，82 项断言。
补 audit.sh 的盲区：audit 只看 installer 退出码，装完有没有东西落盘、卸载有没有
留垃圾它都不查。本脚本断言实际结果：
  A. 22 款工具：装 -> 断言 20 个 skill 落盘 -> 二次装幂等 -> 卸载零残留 + 无嵌套
  B. 19 个检测标记逐一验证只触发预期工具（防新增工具误触发既有工具）
  C. --global 7 款成功 / 14 款明确拒绝且退出码 1
  D. --global 拒绝信息引用的 8 份 docs 真实存在（防死链）
  E. rules 型工具索引断言：表 20 行、无空 description、Cline 无 frontmatter
  F. PATH 探测在 PATH 为空 / 畸形 / 未定义三种退化情形下的健壮性

文档
- RELEASE-NOTES.zh.md 加 v1.7.2 条目，含设计取舍与完整验证清单
- 简繁 README 更新亮点：v1.7.0 -> v1.7.2（1.7.1 时漏更新，一并修正）
- marketplace 示例里的 "Version: 1.7.1" 改为「<当前版本>」—— 写死版本号每次
  发版都会过期

发版前验证结果
- scripts/audit.sh: 130 pass / 0 fail（2 warn 为既有上游漂移，见 #19）
- scripts/verify-release.sh: 82 pass / 0 fail
- npm 包端到端：npm pack -> 包内 version 1.7.2 -> 从 tarball 安装 ->
  用打包后的二进制真实跑 Kilo Code 自动检测 -> 20 skills + 索引生成 ->
  卸载零残留
- engines >=20 与实际语法一致（仅用到 padEnd/ES2017，无 ?? 与 ?.）
- 包体 444K / 106 文件，docs/README.cline.md 与 README.kilocode.md 均已入包
 2026-08-07 20:00:51 +08:00