AI 原生开放教材

外观

superpowers-zh（AI 编程超能力 · 中文增强版）技能与配置库·中文原文 ↗仓库 ↗

Superpowers 中文版 — Aider 安装指南 ​

在 Aider 中使用 superpowers-zh 的完整指南。

⚠️ 先看这一条：装完还需要一步才生效 ​

Aider 不会自动加载 CONVENTIONS.md。 官方文档明确要求显式加载 —— 原文推荐 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，需要自己删。