lywsvip/superpowers-zh
1
0
Fork 0
mirror of https://github.com/jnMetaCode/superpowers-zh.git synced 2026-09-02 22:54:06 +08:00
Code Issues Packages Projects Releases Wiki Activity

fix(installer): Kiro 把 335 KB 塞进每一轮对话 —— 改为索引式（Aider 的反面）

Browse Source 
继 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 自有，零上游偏离。
This commit is contained in:
AI不止语
2026-08-12 18:58:54 +08:00
parent be6dc8c252
commit ad32b2546b
5 changed files with 200 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
docs/README.kiro.md
View File

@@ -2,68 +2,100 @@
在 [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
npx superpowers-zh --tool kiro
```
安装脚本会自动检测 `.kiro/` 目录并将 skills 复制到 `.kiro/steering/`。
装两样东西：
| 位置 | 内容 | 是否每轮常驻 |
|---|---|---|
| `.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
cp -r superpowers-zh/skills/* /your/project/.kiro/steering/
mkdir -p /your/project/.kiro/skills
cp -r superpowers-zh/skills/* /your/project/.kiro/skills/
```
## 工作原理
Kiro 使用 **Steering** 机制管理 AI 行为规则：
- **目录**：`.kiro/steering/`
- **格式**：Markdown + YAML frontmatter
- **加载模式**：
- `alwaysApply: true` — 每次对话自动加载
- `globs: "*.ts"` — 匹配特定文件时加载
- 手动引用 — 在聊天中输入 `#steering-file-name`
### Skills 与 Steering 的对应
superpowers-zh 的 SKILL.md 文件格式与 Kiro Steering 文件兼容（都是 Markdown + YAML frontmatter）。安装后，Kiro 会自动识别并加载 skills。
### 推荐配置
在 `.kiro/steering/` 中创建 `superpowers.md`：
```markdown
---
description: 加载 superpowers skills 框架
alwaysApply: true
---
使用 .kiro/steering/ 目录下的 superpowers skills 来指导工作流程。
优先使用 brainstorming（头脑风暴）开始新任务。
```
> 手动复制不会生成 `.kiro/steering/superpowers-zh.md` 索引，Kiro 不会知道这些 skill 的存在，你需要自己写一份索引。建议优先用 `npx superpowers-zh --tool kiro`。
>
> **不要**把正文直接拷进 `.kiro/steering/` —— 那正是本次修掉的问题。
## 使用
在 Kiro 中，你可以：
- 直接提到 skill 名称：「使用头脑风暴来分析这个需求」
- 手动引用：在聊天中输入 `#brainstorming`
- Skills 会根据任务类型自动激活
装好重启 Kiro 后：
- 直接描述任务即可，索引会引导它去匹配 skill：「帮我加一个导出功能」应触发 brainstorming
- 也可以点名：「用 brainstorming 分析这个需求」
- 手动引用索引本身：在聊天里输入 `#superpowers-zh`
## 卸载
```bash
npx superpowers-zh --uninstall
```
会删除 `.kiro/skills/` 下装过的 skill 和 `.kiro/steering/superpowers-zh.md`，并顺带清理旧布局残留。你自己的 steering 文件保留。
## 更新
```bash
cd /your/project
npx superpowers-zh
npx superpowers-zh@latest --tool kiro
```
重新运行安装命令即可更新到最新版本。
## 获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- Kiro 文档：https://kiro.dev/docs/steering/
- Kiro Steering 文档：https://kiro.dev/docs/steering/