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 自有，零上游偏离。
102 lines
3.7 KiB
Markdown
102 lines
3.7 KiB
Markdown
# Superpowers 中文版 — Kiro 安装指南
|
||
|
||
在 [Kiro](https://kiro.dev)（Amazon AI IDE）中使用 superpowers-zh 的完整指南。
|
||
|
||
## ⚠️ v1.7.9 及更早版本请重新安装
|
||
|
||
旧版把 20 个 skill 的**正文**直接装进了 `.kiro/steering/`。而 [Kiro 官方文档](https://kiro.dev/docs/steering/)明确：`.kiro/steering/` 下的文件默认 `inclusion: always`，会被 "loaded into every Kiro interaction automatically"。
|
||
|
||
实测那个布局是 **47 个 md、335 KB，每一轮对话全量进上下文**。不是不能用，是每轮都在烧 token。
|
||
|
||
v1.7.10 起改成索引式：**4.4 KB**（76 倍差距）。重装即可，安装器会自动清掉旧布局：
|
||
|
||
```bash
|
||
cd /your/project
|
||
npx superpowers-zh@latest --tool kiro
|
||
```
|
||
|
||
会看到：
|
||
|
||
```
|
||
🧹 Kiro: 清理旧布局 20 个 skill 目录 <- .kiro/steering/
|
||
✅ Kiro: steering 索引 -> .kiro/steering/superpowers-zh.md
|
||
```
|
||
|
||
**你自己写的 steering 文件不会被动** —— 只清理与我们 skill 同名的那些目录。
|
||
|
||
## 快速安装
|
||
|
||
```bash
|
||
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` 并遵循其流程。
|
||
|
||
## 手动安装
|
||
|
||
```bash
|
||
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`
|
||
|
||
## 卸载
|
||
|
||
```bash
|
||
npx superpowers-zh --uninstall
|
||
```
|
||
|
||
会删除 `.kiro/skills/` 下装过的 skill 和 `.kiro/steering/superpowers-zh.md`，并顺带清理旧布局残留。你自己的 steering 文件保留。
|
||
|
||
## 更新
|
||
|
||
```bash
|
||
npx superpowers-zh@latest --tool kiro
|
||
```
|
||
|
||
## 获取帮助
|
||
|
||
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
|
||
- Kiro Steering 文档：https://kiro.dev/docs/steering/
|