mirror of
https://github.com/jnMetaCode/superpowers-zh.git
synced 2026-09-02 22:54:06 +08:00
be6dc8c252
顺着 #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），零上游偏离。
101 lines
3.7 KiB
Markdown
101 lines
3.7 KiB
Markdown
# Superpowers 中文版 — Aider 安装指南
|
||
|
||
在 [Aider](https://aider.chat) 中使用 superpowers-zh 的完整指南。
|
||
|
||
## ⚠️ 先看这一条：装完还需要一步才生效
|
||
|
||
**Aider 不会自动加载 `CONVENTIONS.md`。** [官方文档](https://aider.chat/docs/usage/conventions.html)明确要求显式加载 —— 原文推荐 `aider --read CONVENTIONS.md`，或在配置里写 `read:` 项。
|
||
|
||
所以装完之后，二选一：
|
||
|
||
```bash
|
||
# 每次启动时带上
|
||
aider --read CONVENTIONS.md
|
||
```
|
||
|
||
```yaml
|
||
# 或写进 .aider.conf.yml，一劳永逸
|
||
read: CONVENTIONS.md
|
||
```
|
||
|
||
**我们不替你改 `.aider.conf.yml`** —— 那是你的配置文件。安装器会在装完时把上面两条打印出来提醒你。
|
||
|
||
> 📌 v1.7.9 及更早版本的文档写着「Aider 会自动读取 CONVENTIONS.md，无需额外配置」—— **那是错的**，会让你以为装好了其实没生效。这是我们的错误，v1.7.10 起更正。
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
cd /your/project
|
||
npx superpowers-zh --tool aider
|
||
```
|
||
|
||
会做两件事：
|
||
|
||
1. 把 20 个 skill 复制到 `.aider/skills/`
|
||
2. 生成（或追加）`CONVENTIONS.md`，里面是 skill 索引和触发规则，指向 `.aider/skills/<name>/SKILL.md`
|
||
|
||
### 关于自动检测
|
||
|
||
不带 `--tool` 时安装器会扫描项目里的工具标记。**Aider 不创建 `.aider/` 目录** —— 它在项目根留下的是 `.aider.` 前缀的产物，所以我们认这几个：
|
||
|
||
- `.aider.conf.yml`
|
||
- `.aider.chat.history.md`
|
||
- `.aider.tags.cache.v3/`
|
||
|
||
> 📌 v1.7.9 及更早只认 `.aider/` 这个目录，而 Aider 从不创建它 —— 也就是说**真实的 Aider 项目从来没被自动检测到过**，必须手动 `--tool aider`。同样在 v1.7.10 修正。
|
||
|
||
## 手动安装
|
||
|
||
```bash
|
||
git clone https://github.com/jnMetaCode/superpowers-zh.git
|
||
cp -r superpowers-zh/skills /your/project/.aider/skills
|
||
```
|
||
|
||
> 手动复制不会生成 `CONVENTIONS.md`，你需要自己写一份索引并按上面的方式加载它。建议优先用 `npx superpowers-zh --tool aider`。
|
||
|
||
## 只加载部分 skill
|
||
|
||
`CONVENTIONS.md` 是一份索引（约 4 KB），由 Aider 常驻上下文，正文按需读取。如果你只想常驻少数几个 skill 的全文，也可以直接点名：
|
||
|
||
```yaml
|
||
read:
|
||
- .aider/skills/brainstorming/SKILL.md
|
||
- .aider/skills/test-driven-development/SKILL.md
|
||
- .aider/skills/systematic-debugging/SKILL.md
|
||
```
|
||
|
||
注意每个 SKILL.md 都会完整进入上下文，装 20 个的全文开销很大 —— 这正是我们默认走索引式 `CONVENTIONS.md` 的原因。
|
||
|
||
## 故障排查
|
||
|
||
### Skills 未生效
|
||
|
||
按顺序查：
|
||
|
||
1. **`CONVENTIONS.md` 被加载了吗？** 这是最常见的原因。Aider 启动后用 `/read` 看已加载的只读文件里有没有它。没有的话，回到本文开头那一步。
|
||
2. `.aider/skills/` 目录是否存在且包含 skill 子目录。
|
||
3. 如果用 `.aider.conf.yml` 的 `read:` 配置：确认 Aider 读的是你以为的那份配置。Aider 会依次找 home 目录、git 仓库根、当前目录下的 `.aider.conf.yml`。
|
||
|
||
### 装完没看到激活提示
|
||
|
||
说明你用的是旧版本。升级：
|
||
|
||
```bash
|
||
npx superpowers-zh@latest --tool aider
|
||
```
|
||
|
||
## 卸载
|
||
|
||
```bash
|
||
npx superpowers-zh --uninstall
|
||
```
|
||
|
||
会删除 `.aider/skills/` 下装过的 skill，并从 `CONVENTIONS.md` 中精确切除 superpowers-zh 段（保留你自己写的内容）。`.aider.conf.yml` 我们没动过，所以也不会去改 —— 如果你加过 `read: CONVENTIONS.md`，需要自己删。
|
||
|
||
## 获取帮助
|
||
|
||
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
|
||
- 项目主页：https://github.com/jnMetaCode/superpowers-zh
|
||
- Aider 文档：https://aider.chat/docs/
|
||
- Aider conventions 文档：https://aider.chat/docs/usage/conventions.html
|