mirror of
https://github.com/jnMetaCode/superpowers-zh.git
synced 2026-09-02 22:54:06 +08:00
ad32b2546b
继 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 自有，零上游偏离。
Superpowers 中文版 — Windsurf 安装指南
在 Windsurf 中使用 superpowers-zh 的完整指南。
自动安装
cd /your/project
npx superpowers-zh
安装脚本会自动检测 .windsurf/ 目录并将 skills 复制到 .windsurf/skills/ 目录。
手动安装
git clone https://github.com/jnMetaCode/superpowers-zh.git
cp -r superpowers-zh/skills /your/project/.windsurf/skills
或全局安装：
cp -r superpowers-zh/skills ~/.windsurf/skills
Skill 加载优先级
| 位置 | 优先级 | 说明 |
|---|---|---|
.windsurf/skills/ |
最高 | 项目级，仅当前项目 |
~/.windsurf/skills/ |
中 | 用户级，所有项目共享 |
使用
安装完成后重启 Windsurf，skills 会自动生效。
也可以在 .windsurfrules 文件中引用 skills 目录：
请参考 .windsurf/skills/ 目录中的 SKILL.md 文件作为工作方法论。
故障排查
Skills 未生效
- 确认
.windsurf/skills/目录存在且包含 skill 文件夹 - 每个 skill 需要包含有效 YAML frontmatter 的
SKILL.md文件 - 重启 Windsurf