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 自有，零上游偏离。
3.7 KiB
Superpowers 中文版 — Kiro 安装指南
在 Kiro（Amazon AI IDE）中使用 superpowers-zh 的完整指南。
⚠️ v1.7.9 及更早版本请重新安装
旧版把 20 个 skill 的正文直接装进了 .kiro/steering/。而 Kiro 官方文档明确：.kiro/steering/ 下的文件默认 inclusion: always，会被 "loaded into every Kiro interaction automatically"。
实测那个布局是 47 个 md、335 KB，每一轮对话全量进上下文。不是不能用，是每轮都在烧 token。
v1.7.10 起改成索引式：4.4 KB（76 倍差距）。重装即可，安装器会自动清掉旧布局：
cd /your/project
npx superpowers-zh@latest --tool kiro
会看到：
🧹 Kiro: 清理旧布局 20 个 skill 目录 <- .kiro/steering/
✅ Kiro: steering 索引 -> .kiro/steering/superpowers-zh.md
你自己写的 steering 文件不会被动 —— 只清理与我们 skill 同名的那些目录。
快速安装
cd /your/project
npx superpowers-zh --tool kiro
装两样东西：
| 位置 | 内容 | 是否每轮常驻 |
|---|---|---|
.kiro/steering/superpowers-zh.md |
索引：核心规则 + 20 个 skill 的触发条件表（约 4.4 KB） | 是（inclusion: always） |
.kiro/skills/<name>/SKILL.md |
skill 正文 | 否，按需读取 |
工作原理
Kiro 用 Steering 机制管理 AI 行为规则。关键的三件事：
- 目录：
.kiro/steering/（项目级）、~/.kiro/steering/（全局） - 默认行为：没写
inclusion的文件默认就是 always —— 每次交互自动加载 - frontmatter 键（这是 Kiro 自己的，别和 Cursor 系搞混）：
键 含义 inclusion: always每次交互都加载（默认值） inclusion: fileMatch+fileMatchPattern匹配特定文件时加载 inclusion: manual仅在聊天里用 #steering-file-name引用时加载inclusion: auto按 description与请求匹配时自动加载
📌 v1.7.9 及更早的本文档写着加载模式是
alwaysApply: true和globs: "*.ts"—— 这两个键 Kiro 文档里根本不存在，是 Cursor / Trae 的约定被误写成了 Kiro 的。已更正。
为什么正文不放 steering 里
因为 steering 是常驻开销。这跟我们对 Cline、Kilo Code 的处理是同一个道理：常驻的位置只放索引，正文按需读取。
索引里明确告诉 Kiro：任务匹配某个 skill 时，去读 .kiro/skills/<skill-name>/SKILL.md 并遵循其流程。
手动安装
git clone https://github.com/jnMetaCode/superpowers-zh.git
mkdir -p /your/project/.kiro/skills
cp -r superpowers-zh/skills/* /your/project/.kiro/skills/
手动复制不会生成
.kiro/steering/superpowers-zh.md索引，Kiro 不会知道这些 skill 的存在，你需要自己写一份索引。建议优先用npx superpowers-zh --tool kiro。不要把正文直接拷进
.kiro/steering/—— 那正是本次修掉的问题。
使用
装好重启 Kiro 后：
- 直接描述任务即可，索引会引导它去匹配 skill：「帮我加一个导出功能」应触发 brainstorming
- 也可以点名：「用 brainstorming 分析这个需求」
- 手动引用索引本身：在聊天里输入
#superpowers-zh
卸载
npx superpowers-zh --uninstall
会删除 .kiro/skills/ 下装过的 skill 和 .kiro/steering/superpowers-zh.md，并顺带清理旧布局残留。你自己的 steering 文件保留。
更新
npx superpowers-zh@latest --tool kiro
获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- Kiro Steering 文档：https://kiro.dev/docs/steering/