superpowers-zh 1.1.1 → 1.1.2

package/docs/README.gemini-cli.md

@@ -0,0 +1,65 @@
+# Superpowers 中文版 — Gemini CLI 安装指南
+
+在 [Gemini CLI](https://github.com/google-gemini/gemini-cli) 中使用 superpowers-zh 的完整指南。
+
+## 自动安装
+
+```bash
+cd /your/project
+npx superpowers-zh
+```
+
+安装脚本会自动检测 `.gemini/` 目录并将 skills 复制到 `.gemini/skills/` 目录。
+
+## 手动安装
+
+```bash
+git clone https://github.com/jnMetaCode/superpowers-zh.git
+cp -r superpowers-zh/skills /your/project/.gemini/skills
+```
+
+或作为 Gemini 扩展安装（全局）：
+
+```bash
+mkdir -p ~/.gemini/extensions/superpowers-zh/skills
+cp -r superpowers-zh/skills/* ~/.gemini/extensions/superpowers-zh/skills/
+cp superpowers-zh/gemini-extension.json ~/.gemini/extensions/superpowers-zh/
+```
+
+## 通过 GEMINI.md 引用
+
+在项目根目录的 `GEMINI.md` 中引用 skills：
+
+```markdown
+# 工作方法论
+
+请参考 .gemini/skills/ 目录中的 SKILL.md 文件。
+遇到新功能开发时，先使用 brainstorming skill。
+编写代码时，遵循 test-driven-development skill。
+```
+
+## Skill 加载优先级
+
+| 位置 | 优先级 | 说明 |
+|------|--------|------|
+| `.gemini/skills/` | 最高 | 项目级，仅当前项目 |
+| `~/.gemini/extensions/*/skills/` | 中 | 扩展级，所有项目共享 |
+
+## 故障排查
+
+### Skills 未生效
+
+1. 确认 `.gemini/skills/` 目录存在且包含 skill 文件夹
+2. 每个 skill 需要包含有效 YAML frontmatter 的 `SKILL.md` 文件
+3. 重启 Gemini CLI
+
+### 扩展模式未加载
+
+1. 检查 `gemini-extension.json` 是否正确放在扩展目录中
+2. 确认扩展目录结构：`~/.gemini/extensions/superpowers-zh/`
+
+## 获取帮助
+
+- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
+- 项目主页：https://github.com/jnMetaCode/superpowers-zh
+- Gemini CLI 文档：https://github.com/google-gemini/gemini-cli

package/docs/README.kiro.md

@@ -0,0 +1,69 @@
+# Superpowers 中文版 — Kiro 安装指南
+
+在 [Kiro](https://kiro.dev)（Amazon AI IDE）中使用 superpowers-zh 的完整指南。
+
+## 快速安装
+
+```bash
+cd /your/project
+npx superpowers-zh
+```
+
+安装脚本会自动检测 `.kiro/` 目录并将 skills 复制到 `.kiro/steering/`。
+
+## 手动安装
+
+```bash
+git clone https://github.com/jnMetaCode/superpowers-zh.git
+cp -r superpowers-zh/skills/* /your/project/.kiro/steering/
+```
+
+## 工作原理
+
+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 中，你可以：
+- 直接提到 skill 名称：「使用头脑风暴来分析这个需求」
+- 手动引用：在聊天中输入 `#brainstorming`
+- Skills 会根据任务类型自动激活
+
+## 更新
+
+```bash
+cd /your/project
+npx superpowers-zh
+```
+
+重新运行安装命令即可更新到最新版本。
+
+## 获取帮助
+
+- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
+- Kiro 文档：https://kiro.dev/docs/steering/

package/docs/README.openclaw.md

@@ -0,0 +1,102 @@
+# Superpowers 中文版 — OpenClaw 安装指南
+
+在 [OpenClaw](https://github.com/anthropics/openclaw) 中使用 superpowers-zh 的完整指南。
+
+## 快速安装
+
+```bash
+cd /your/project
+npx superpowers-zh
+```
+
+安装脚本会自动检测 `.openclaw/` 目录并将 skills 复制到 `skills/` 目录。
+
+## 手动安装
+
+```bash
+git clone https://github.com/jnMetaCode/superpowers-zh.git
+cp -r superpowers-zh/skills/* /your/project/skills/
+```
+
+或安装到全局（所有项目共享）：
+
+```bash
+cp -r superpowers-zh/skills/* ~/.openclaw/skills/
+```
+
+## 工作原理
+
+OpenClaw 按以下优先级加载 skills：
+
+| 位置 | 优先级 | 说明 |
+|------|--------|------|
+| `<workspace>/skills/` | 最高 | 工作区级，当前项目专用 |
+| `~/.openclaw/skills/` | 中 | 用户级，所有项目共享 |
+| 内置 skills | 最低 | OpenClaw 自带 |
+
+每个 skill 是一个 `skills/{name}/SKILL.md` 文件，包含 YAML frontmatter 和指令内容。OpenClaw 会自动发现并加载。
+
+### 推荐配置方式
+
+在项目根目录的 `CLAUDE.md` 或 `AGENTS.md` 中引用：
+
+```markdown
+# CLAUDE.md
+
+本项目使用 superpowers-zh skills 框架。
+优先使用 brainstorming（头脑风暴）开始新任务。
+Skills 位于 skills/ 目录下。
+```
+
+### 工具映射
+
+OpenClaw 与 Claude Code 使用相同的工具名称，skills 无需额外适配：
+
+| 工具 | OpenClaw | Claude Code |
+|------|----------|-------------|
+| 读文件 | `Read` | `Read` |
+| 写文件 | `Write` | `Write` |
+| 编辑 | `Edit` | `Edit` |
+| 终端 | `Bash` | `Bash` |
+| Skills | `Skill` | `Skill` |
+
+## 使用
+
+安装完成后重启 OpenClaw，所有 skills 会自动生效。你可以：
+
+- 输入 `/brainstorming` 开始头脑风暴
+- 输入 `/commit` 使用中文提交规范
+- 在任何编码任务中，skills 会被自动调用
+
+## 全局 Skills
+
+如果你想让所有项目都能使用 superpowers-zh：
+
+```bash
+mkdir -p ~/.openclaw/skills
+cp -r superpowers-zh/skills/* ~/.openclaw/skills/
+```
+
+也可以通过 `~/.openclaw/openclaw.json` 配置额外 skills 目录：
+
+```json
+{
+  "skills": {
+    "load": {
+      "extraDirs": ["/path/to/superpowers-zh/skills"]
+    }
+  }
+}
+```
+
+## 更新
+
+```bash
+cd /your/project
+npx superpowers-zh
+```
+
+## 获取帮助
+
+- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
+- QQ 群：833585047

package/docs/README.opencode.md

@@ -0,0 +1,108 @@
+# Superpowers 中文版 — OpenCode 安装指南
+
+在 [OpenCode.ai](https://opencode.ai) 中使用 superpowers-zh 的完整指南。
+
+## 安装
+
+在 `opencode.json`（全局或项目级）的 `plugin` 数组中添加：
+
+```json
+{
+  "plugin": ["superpowers@git+https://github.com/jnMetaCode/superpowers-zh.git"]
+}
+```
+
+重启 OpenCode。插件通过 Bun 自动安装并注册所有 skills。
+
+验证方式：问 "告诉我你有哪些 superpowers"
+
+## 使用
+
+### 查找 Skills
+
+使用 OpenCode 原生的 `skill` 工具列出所有可用 skills：
+
+```
+use skill tool to list skills
+```
+
+### 加载 Skill
+
+```
+use skill tool to load superpowers/brainstorming
+```
+
+### 个人 Skills
+
+在 `~/.config/opencode/skills/` 中创建你自己的 skills：
+
+```bash
+mkdir -p ~/.config/opencode/skills/my-skill
+```
+
+创建 `~/.config/opencode/skills/my-skill/SKILL.md`：
+
+```markdown
+---
+name: my-skill
+description: 当 [条件] 时使用 - [功能描述]
+---
+
+# 我的 Skill
+
+[你的 skill 内容]
+```
+
+### 项目 Skills
+
+在项目的 `.opencode/skills/` 目录中创建项目级 skills。
+
+**Skill 优先级：** 项目 skills > 个人 skills > Superpowers skills
+
+## 更新
+
+重启 OpenCode 时自动更新。插件每次启动都从 git 仓库重新安装。
+
+锁定特定版本：
+
+```json
+{
+  "plugin": ["superpowers@git+https://github.com/jnMetaCode/superpowers-zh.git#v1.0.0"]
+}
+```
+
+## 工作原理
+
+插件做两件事：
+
+1. **注入引导上下文** — 通过 `experimental.chat.system.transform` hook，为每次对话添加 superpowers 意识
+2. **注册 skills 目录** — 通过 `config` hook，让 OpenCode 发现所有 skills，无需符号链接或手动配置
+
+### 工具映射
+
+为 Claude Code 编写的 skills 自动适配 OpenCode：
+
+- `TodoWrite` → `todowrite`
+- `Task`（子代理）→ OpenCode 的 `@mention` 系统
+- `Skill` 工具 → OpenCode 原生 `skill` 工具
+- 文件操作 → OpenCode 原生工具
+
+## 故障排查
+
+### 插件未加载
+
+1. 检查 OpenCode 日志：`opencode run --print-logs "hello" 2>&1 | grep -i superpowers`
+2. 确认 `opencode.json` 中的插件配置正确
+3. 确保运行的是最新版本的 OpenCode
+
+### Skills 未找到
+
+1. 使用 `skill` 工具列出可用 skills
+2. 检查插件是否正确加载（见上）
+3. 每个 skill 需要包含有效 YAML frontmatter 的 `SKILL.md` 文件
+
+## 获取帮助
+
+- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
+- 项目主页：https://github.com/jnMetaCode/superpowers-zh
+- OpenCode 文档：https://opencode.ai/docs/

package/docs/README.qwen.md

@@ -0,0 +1,61 @@
+# Superpowers 中文版 — Qwen Code 安装指南
+
+在 [Qwen Code](https://tongyi.aliyun.com/qianwen) (通义灵码) 中使用 superpowers-zh 的完整指南。
+
+## 自动安装
+
+```bash
+cd /your/project
+npx superpowers-zh
+```
+
+安装脚本会自动检测 `.qwen/` 目录并将 skills 复制到 `.qwen/skills/` 目录。
+
+## 手动安装
+
+```bash
+git clone https://github.com/jnMetaCode/superpowers-zh.git
+cp -r superpowers-zh/skills /your/project/.qwen/skills
+```
+
+或全局安装：
+
+```bash
+mkdir -p ~/.qwen/skills
+cp -r superpowers-zh/skills/* ~/.qwen/skills/
+```
+
+## Skill 加载优先级
+
+| 位置 | 优先级 | 说明 |
+|------|--------|------|
+| `.qwen/skills/` | 最高 | 项目级，仅当前项目 |
+| `~/.qwen/skills/` | 中 | 用户级，所有项目共享 |
+
+## 使用
+
+安装完成后重启 Qwen Code，skills 会自动生效。
+
+在 Qwen Code 中可以通过以下方式调用 skills：
+
+```
+请使用 brainstorming skill 来分析这个需求
+```
+
+```
+按照 test-driven-development skill 的方法来实现这个功能
+```
+
+## 故障排查
+
+### Skills 未生效
+
+1. 确认 `.qwen/skills/` 目录存在且包含 skill 文件夹
+2. 每个 skill 需要包含有效 YAML frontmatter 的 `SKILL.md` 文件
+3. 重启 Qwen Code 或刷新会话
+
+## 获取帮助
+
+- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
+- 项目主页：https://github.com/jnMetaCode/superpowers-zh
+- 通义灵码文档：https://tongyi.aliyun.com/lingma

package/docs/README.trae.md

@@ -0,0 +1,62 @@
+# Superpowers 中文版 — Trae 安装指南
+
+在 [Trae](https://www.trae.ai)（字节跳动 AI IDE）中使用 superpowers-zh 的完整指南。
+
+## 快速安装
+
+```bash
+cd /your/project
+npx superpowers-zh
+```
+
+安装脚本会自动检测 `.trae/` 目录并将 skills 复制到 `.trae/rules/`。
+
+## 手动安装
+
+```bash
+git clone https://github.com/jnMetaCode/superpowers-zh.git
+mkdir -p /your/project/.trae/rules
+cp -r superpowers-zh/skills/* /your/project/.trae/rules/
+```
+
+## 工作原理
+
+Trae 使用 `.rules` 机制管理 AI 行为：
+
+- **目录**：`.trae/rules/`
+- **格式**：Markdown + metadata（description、globs、alwaysApply、priority）
+- **规则类型**：
+  - **项目规则**（Project Rules）— 仅作用于当前项目
+  - **个人规则**（Personal Rules）— 用户级别，可被项目规则覆盖
+- **优先级**：1-4，数值越高优先级越高
+
+### Skills 适配
+
+superpowers-zh 的 SKILL.md 文件可以直接作为 Trae 的 rules 使用。Trae 会在初始化时加载 `.trae/rules/` 下的所有规则文件。
+
+### 推荐配置
+
+安装完成后，在 Trae 的 Builder Mode 或 Chat 中提到 skill 名称即可激活：
+
+```
+使用头脑风暴 skill 来分析这个需求
+```
+
+## 中文支持
+
+Trae 原生支持中文，与 superpowers-zh 完美配合：
+- 所有 skills 均为中文
+- 中文代码审查、中文 Git 工作流等国内特色 skills 开箱即用
+- 支持 MCP 协议扩展
+
+## 更新
+
+```bash
+cd /your/project
+npx superpowers-zh
+```
+
+## 获取帮助
+
+- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
+- Trae 文档：https://docs.trae.ai/ide/rules

package/docs/README.vscode.md

@@ -0,0 +1,98 @@
+# Superpowers 中文版 — VS Code (Copilot) 安装指南
+
+在 VS Code + GitHub Copilot 中使用 superpowers-zh 的完整指南。
+
+## 前置条件
+
+- VS Code（最新版本）
+- GitHub Copilot 扩展（免费版或付费版均可）
+
+## 快速安装
+
+```bash
+cd /your/project
+npx superpowers-zh
+```
+
+安装脚本会自动检测 `.github/` 目录并将 skills 复制到该目录。
+
+## 手动安装
+
+```bash
+git clone https://github.com/jnMetaCode/superpowers-zh.git
+mkdir -p /your/project/.github/superpowers
+cp -r superpowers-zh/skills/* /your/project/.github/superpowers/
+```
+
+## 工作原理
+
+VS Code Copilot 使用 `.github/copilot-instructions.md` 作为项目级自定义指令：
+
+- **位置**：项目根目录 `.github/copilot-instructions.md`
+- **格式**：Markdown
+- **生效范围**：该工作区内的所有 Copilot Chat 和内联补全
+- **自动加载**：保存文件后立即生效，无需重启
+
+### 推荐配置
+
+由于 Copilot 主要通过单个指令文件工作，建议创建 `.github/copilot-instructions.md` 引用 skills：
+
+```markdown
+# Copilot 自定义指令
+
+## 工作流方法论
+
+本项目使用 superpowers-zh skills 框架。开始新任务前，请参考以下方法论：
+
+- 新需求 → 先头脑风暴（.github/superpowers/brainstorming/SKILL.md）
+- 写代码 → TDD 驱动（.github/superpowers/test-driven-development/SKILL.md）
+- 修 Bug → 系统化调试（.github/superpowers/systematic-debugging/SKILL.md）
+- 审查代码 → 中文代码审查（.github/superpowers/chinese-code-review/SKILL.md）
+
+## 中文项目规范
+
+- 代码注释和文档使用中文
+- Git commit 遵循中文提交规范
+- 技术术语保留英文原文
+```
+
+### 使用 .instructions.md 文件（推荐）
+
+VS Code 还支持更细粒度的 `.instructions.md` 文件：
+
+```
+.github/
+  copilot-instructions.md          # 全局指令
+  .instructions/
+    typescript.instructions.md     # TypeScript 文件专用
+    testing.instructions.md        # 测试相关
+```
+
+## 使用
+
+在 VS Code 中：
+- **Copilot Chat**（`Ctrl+Shift+I`）：直接引用 skill 名称
+- **内联补全**：自动遵循 copilot-instructions.md 中的规则
+- **`/init`**：在 Chat 中输入，自动生成项目配置
+
+## 局限性
+
+VS Code Copilot 不像 Claude Code 那样支持 `Skill` 工具或子 Agent 派遣。以下 skills 需要手动参考而非自动执行：
+
+- 派遣并行 Agent（需要 Agent 框架支持）
+- 子 Agent 驱动开发（需要 Agent 框架支持）
+- Git Worktree 使用（需要终端操作）
+
+其他方法论类 skills（头脑风暴、TDD、调试、代码审查等）完全兼容。
+
+## 更新
+
+```bash
+cd /your/project
+npx superpowers-zh
+```
+
+## 获取帮助
+
+- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
+- VS Code Copilot 文档：https://code.visualstudio.com/docs/copilot/customization/custom-instructions

package/docs/README.windsurf.md

@@ -0,0 +1,56 @@
+# Superpowers 中文版 — Windsurf 安装指南
+
+在 [Windsurf](https://codeium.com/windsurf) 中使用 superpowers-zh 的完整指南。
+
+## 自动安装
+
+```bash
+cd /your/project
+npx superpowers-zh
+```
+
+安装脚本会自动检测 `.windsurf/` 目录并将 skills 复制到 `.windsurf/skills/` 目录。
+
+## 手动安装
+
+```bash
+git clone https://github.com/jnMetaCode/superpowers-zh.git
+cp -r superpowers-zh/skills /your/project/.windsurf/skills
+```
+
+或全局安装：
+
+```bash
+cp -r superpowers-zh/skills ~/.windsurf/skills
+```
+
+## Skill 加载优先级
+
+| 位置 | 优先级 | 说明 |
+|------|--------|------|
+| `.windsurf/skills/` | 最高 | 项目级，仅当前项目 |
+| `~/.windsurf/skills/` | 中 | 用户级，所有项目共享 |
+
+## 使用
+
+安装完成后重启 Windsurf，skills 会自动生效。
+
+也可以在 `.windsurfrules` 文件中引用 skills 目录：
+
+```
+请参考 .windsurf/skills/ 目录中的 SKILL.md 文件作为工作方法论。
+```
+
+## 故障排查
+
+### Skills 未生效
+
+1. 确认 `.windsurf/skills/` 目录存在且包含 skill 文件夹
+2. 每个 skill 需要包含有效 YAML frontmatter 的 `SKILL.md` 文件
+3. 重启 Windsurf
+
+## 获取帮助
+
+- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
+- 项目主页：https://github.com/jnMetaCode/superpowers-zh
+- Windsurf 文档：https://docs.codeium.com/windsurf

package/docs/assets/RECORDING-GUIDE.md

@@ -0,0 +1,47 @@
+# GIF 录制指南
+
+## 方式一：macOS 录屏（推荐，最真实）
+
+### 准备
+1. 终端字体调到 18pt+，背景用深色
+2. 准备一个测试项目目录 `~/demo-project`
+3. 确保 superpowers-zh 已安装
+
+### 录制步骤
+1. **Cmd+Shift+5** 打开录屏，选择录制区域（只录终端窗口）
+2. 执行以下操作：
+
+```bash
+# 第一步：安装（3秒）
+cd ~/demo-project
+npx superpowers-zh
+
+# 第二步：给 AI 提需求（等 AI 回复）
+claude "给用户模块加一个批量导出功能"
+```
+
+3. 等 AI 输出中文的头脑风暴内容（澄清问题 + 方案），录到这里就可以停了
+4. 停止录屏
+
+### 转 GIF
+```bash
+# mov 转 gif（用 ffmpeg）
+ffmpeg -i recording.mov -vf "fps=10,scale=700:-1:flags=lanczos" -c:v gif docs/assets/demo.gif
+
+# 如果太大（>2MB），降低 fps 或尺寸
+ffmpeg -i recording.mov -vf "fps=8,scale=600:-1:flags=lanczos" -c:v gif docs/assets/demo.gif
+```
+
+## 方式二：VHS 脚本（模拟输入，输出需要手动编排）
+
+```bash
+cd /Users/yx/work/wenzhang/superpowers-zh
+vhs docs/assets/demo.tape
+```
+
+注意：VHS 只模拟键盘输入，AI 输出需要在 tape 文件中用 Type 模拟。
+
+## 最终效果要求
+- 时长：15-20 秒
+- 文件大小：< 2MB
+- 关键帧：能看到 AI 用中文输出设计方案/澄清问题