第二章：安装部署与工具适配

2.1 安装方式总览

superpowers-zh 提供三类安装方式：

一键安装： 在项目根目录执行 npx superpowers-zh，脚本自动检测当前项目使用的 AI 编程工具，并把 Skills 复制到对应目录。
指定工具安装： 当自动检测失败时，执行 npx superpowers-zh --tool <工具名>，明确告诉脚本安装到哪个工具目录。
手动安装： 获取项目内容后，按工具要求把 skills/ 复制或链接到目标目录，再配置工具的自定义指令。

推荐优先使用一键安装，因为它会同时处理部分工具的 bootstrap 配置。例如 Claude Code 会生成或追加 CLAUDE.md，Gemini CLI 会生成或追加 GEMINI.md，Trae 会写入 .trae/rules/superpowers-zh.md。

2.2 环境要求

根据 package.json，npm 包要求：

Node.js >=20.0.0
可以运行 npx
当前目录是你希望启用 superpowers-zh 的项目根目录

如果是在企业内网环境，需要确认 npm registry 可访问。国内团队可以根据网络情况使用 npm 官方源或镜像源。安装失败时先确认 Node 版本，再确认 npm 缓存和权限。

2.3 一键安装流程

在项目根目录运行：

cd /your/project
npx superpowers-zh

脚本会执行以下动作：

读取 npm 包中的 skills/ 目录，统计可用 Skill 数量。
扫描当前项目中是否存在 .claude、.cursor、.codex、.kiro、.trae、.windsurf、GEMINI.md、.github/copilot-instructions.md 等标识。
命中某个工具后，把全部 Skills 复制到该工具约定目录。
对部分工具生成引导文档，告诉 AI 如何查找和使用 Skills。
如果没有识别到任何工具，默认安装到 .claude/skills/，并生成 Claude Code 风格的引导文件。

安装完成后通常需要重启对应 AI 编程工具，或重新打开工作区，让工具重新加载自定义指令和 Skill 元数据。

2.4 指定工具安装

当项目没有明显的工具配置文件，或者一个仓库中需要给特定工具安装时，可以使用 --tool：

npx superpowers-zh --tool cursor
npx superpowers-zh --tool codex
npx superpowers-zh --tool gemini
npx superpowers-zh --tool vscode
npx superpowers-zh --tool hermes

安装脚本内置了别名映射。例如：

输入别名	目标工具
`claude`、`claude-code`、`copilot`、`copilot-cli`	Claude Code 兼容目录
`cursor`	Cursor
`codex`	Codex CLI
`kiro`	Kiro
`trae`	Trae
`gemini`、`gemini-cli`	Gemini CLI
`vscode`、`vs-code`	VS Code Copilot
`qwen`、`qwen-code`	Qwen Code
`hermes`、`hermes-agent`	Hermes Agent
`claw`、`claw-code`	Claw Code

指定工具安装适合以下场景：

项目还没有对应工具的配置目录。
工具的检测文件尚未创建。
同一项目中有多个工具，但你只想安装到其中一个。
自动检测命中了错误目标，需要显式指定。

2.5 支持工具与安装目录

一键脚本的核心是把 skills/ 复制到不同工具能够发现的位置。常见映射如下：

工具	目标目录	说明
Claude Code / Copilot CLI	`.claude/skills`	兼容 Claude Code Skill 格式
Cursor	`.cursor/skills`	项目级 Skills
Codex CLI	`.codex/skills`	项目级 Skills；文档还介绍了用户级符号链接方式
Kiro	`.kiro/steering`	Kiro 的 steering 目录
Trae	`.trae/skills`	同时生成 `.trae/rules/superpowers-zh.md`
VS Code Copilot	`.github/superpowers`	配合 `.github/copilot-instructions.md` 使用
Gemini CLI	`.gemini/skills`	同时生成或追加 `GEMINI.md`
Aider	`.aider/skills`	可配合 `CONVENTIONS.md`
OpenCode	`.opencode/skills`	OpenCode 项目级目录
Hermes Agent	`.hermes/skills`	同时生成或追加 `HERMES.md`
Qwen Code	`.qwen/skills`	通义灵码相关目录
Claw Code	`.claw/skills`	Rust 版 CLI Agent 兼容格式

因为不同工具的 Skill 支持程度不同，安装目录只是第一步。真正生效还取决于工具是否支持自动发现、是否读取自定义指令、是否支持子 Agent 和工具调用。

2.6 Claude Code / Copilot CLI 使用要点

Claude Code 是 superpowers 类 Skill 的典型目标。安装后通常会出现：

.claude/
  skills/
    brainstorming/
      SKILL.md
    test-driven-development/
      SKILL.md
    ...
  agents/
    code-reviewer.md
CLAUDE.md

CLAUDE.md 的作用是告诉 AI：本项目已安装 superpowers-zh，开始任务时要检查匹配 Skill；如果任务匹配，使用 Skill 工具加载对应 Skill，而不是直接读取文件或凭记忆执行。

Copilot CLI 在 README 中被视为 Claude Code 兼容格式，安装到 .claude/skills/。实际使用时要看当前 Copilot CLI 对 Skill 工具或自定义指令的支持情况。

2.7 Cursor 使用要点

Cursor 常通过 .cursor/ 目录和规则文件管理项目上下文。superpowers-zh 安装到 .cursor/skills/ 后，你可以在对话中显式要求：

「使用 brainstorming skill 帮我澄清这个需求」
「修复这个 Bug 前先使用 systematic-debugging」
「完成前使用 verification-before-completion」

如果 Cursor 没有原生 Skill 工具，建议在项目规则中写明：当任务匹配某个 Skill 时，读取 .cursor/skills/<name>/SKILL.md 并遵循流程。

2.8 VS Code Copilot 使用要点

VS Code Copilot 的重点是 .github/copilot-instructions.md。安装脚本会把 Skills 放到 .github/superpowers/，但 Copilot 不一定会自动逐个发现 Skill。因此需要在指令文件中建立路由规则，例如：

# Copilot 自定义指令

本项目使用 superpowers-zh：

- 新需求：先参考 `.github/superpowers/brainstorming/SKILL.md`
- 写代码：遵循 `.github/superpowers/test-driven-development/SKILL.md`
- 修 Bug：遵循 `.github/superpowers/systematic-debugging/SKILL.md`
- 完成前：遵循 `.github/superpowers/verification-before-completion/SKILL.md`
- 中文文档：遵循 `.github/superpowers/chinese-documentation/SKILL.md`

VS Code Copilot 的局限是子 Agent 和 Skill 工具支持不如专用 Agent CLI，因此并行 Agent、子 Agent 驱动开发等 Skill 可能只能作为方法论参考。

2.9 Gemini CLI 使用要点

Gemini CLI 安装后会使用 .gemini/skills/ 和 GEMINI.md。superpowers-zh 的 GEMINI.md 会列出 20 个 Skills，并强调四条核心规则：

收到任务时先检查匹配 Skill。
设计先于编码。
测试先于实现。
验证先于完成。

Gemini CLI 的工具名与 Claude Code 不完全一致，因此 superpowers-zh 还提供了工具映射引用文件。使用时要注意：当 Skill 文档提到 Read、Write、Bash、Task 等工具时，应映射到 Gemini CLI 的等价能力。

2.10 Codex CLI 使用要点

Codex 文档中推荐把仓库中的 skills/ 链接到 ~/.agents/skills/，让 Codex 启动时自动扫描 Skill frontmatter。项目级安装也可使用 .codex/skills/。

如果希望启用 dispatching-parallel-agents 和 subagent-driven-development，需要确认 Codex 是否开启多 Agent 功能。否则这两个 Skill 只能作为流程参考，不能真正并发分派实现者和审查者。

2.11 安装验证

安装后建议做三层验证：

文件层验证

确认目标目录中有 20 个 Skill 子目录，并且每个目录包含 SKILL.md：

find .claude/skills -maxdepth 2 -name SKILL.md | wc -l

如果你安装到其他工具目录，把 .claude/skills 换成对应路径。

指令层验证

检查项目根目录或工具规则中是否出现 superpowers-zh 引导内容，例如 CLAUDE.md、GEMINI.md、CONVENTIONS.md、.trae/rules/superpowers-zh.md。

行为层验证

向 AI 发一个小需求：

给这个项目新增一个简单功能，请先确认应该使用哪个 superpowers-zh skill。

理想行为是 AI 先识别 brainstorming 或 using-superpowers，而不是直接改代码。

2.12 升级与卸载

升级通常重新运行即可：

npx superpowers-zh

如果你使用用户级 clone 或符号链接方式，则进入本地副本执行 git pull 后重启工具。

卸载时删除对应安装目录和引导文件中追加的 superpowers-zh 段落即可。例如：

rm -rf .claude/skills
rm -rf .claude/agents
# 然后手动清理 CLAUDE.md 中的 superpowers-zh 说明

不要在团队共享仓库中随意删除这些文件。若它们已经成为项目规范，应通过 PR 讨论后变更。