mirror of
https://github.com/jnMetaCode/superpowers-zh.git
synced 2026-09-02 22:54:06 +08:00
0e3fbc4830
## 问题
官方文档（code.visualstudio.com/docs/copilot/customization/custom-instructions）
明确 Copilot 只自动读这几处：
.github/copilot-instructions.md / AGENTS.md / CLAUDE.md （始终生效）
.github/instructions/*.instructions.md （按 applyTo 匹配）
而我们把 20 个 skill 拷进 `.github/superpowers/` —— **不在其中**，而且装完
**什么引导都不写**。也就是说 VS Code 用户装完，Copilot 一个字都不会读。
旧文档更说明问题：它写着「由于 Copilot 主要通过单个指令文件工作，建议创建
.github/copilot-instructions.md 引用 skills」并给了示例 —— 我们知道需要引导，
却让用户自己动手，而绝大多数人不会照做。
## 改法
自动生成 `.github/instructions/superpowers-zh.instructions.md`：
---
applyTo: "**" # 关键：省略则只能手动挂载 = 白写
name: Superpowers-ZH
description: …
---
约 4.5 KB 的索引（核心规则 + 20 个 skill 触发条件表），正文仍留在
`.github/superpowers/` 按需读取 —— 与 Cline / Kilo / Kiro 同一套思路：applyTo "**"
的文件对每个请求都生效，正文塞进去就是每轮常驻开销。
**刻意不动用户的 .github/copilot-instructions.md** —— 那是他们的文件。用我们自己
的 .instructions.md，互不干扰，卸载也能精确删除。
检测标记补上 `.github/instructions`（用了 instructions 机制的项目都有），原来只认
`.github/copilot-instructions.md`。
## 顺带核实的两款
- **Cursor**：cursor.com/docs/skills 确认 .cursor/skills/<name>/SKILL.md 启动时
自动发现 —— 我们是对的。
- **OpenCode**：opencode.ai/docs/skills 确认 .opencode/skills/ 与
~/.config/opencode/skills/ —— 项目级和全局都对。它同时扫 .claude/skills 与
.agents/skills，已在注释里写明「装过 CC 或 Antigravity 的别重复装」。
## 验证
- 装：正确识别 -> 生成 instructions（applyTo "**"，4503 字节）+ skills 到
.github/superpowers/
- 卸载：只删我们的，用户的 my-own.instructions.md 与 copilot-instructions.md
原样保留
- verify-release 新增 VS Code 段（文件存在 / applyTo 断言 / 20 行索引 / 指向
.github/superpowers/），111 -> 115 pass
- audit 168 pass / 0 warn / 0 fail
108 lines
3.7 KiB
Markdown
108 lines
3.7 KiB
Markdown
# 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/
|
||
```
|
||
|
||
## ⚠️ v1.7.10 及更早版本请重新安装
|
||
|
||
旧版把 20 个 skill 拷进 `.github/superpowers/`，然后**什么引导都不写** —— 而 [VS Code 官方文档](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)明确 Copilot 只自动读这几处：
|
||
|
||
- `.github/copilot-instructions.md`、`AGENTS.md`、`CLAUDE.md`（始终生效）
|
||
- `.github/instructions/*.instructions.md`（按 frontmatter 的 `applyTo` 匹配）
|
||
|
||
**`.github/superpowers/` 不在其中，Copilot 一个字都不会读。** 旧文档还写着「建议你自己创建 `copilot-instructions.md` 引用它们」—— 等于我们知道需要引导，却让用户自己动手。
|
||
|
||
v1.7.11 起自动生成 `.github/instructions/superpowers-zh.instructions.md`（约 4.5 KB 索引，`applyTo: "**"` 对所有请求生效）。重装即可：
|
||
|
||
```bash
|
||
cd /your/project
|
||
npx superpowers-zh --tool vscode
|
||
```
|
||
|
||
## 工作原理
|
||
|
||
装两样东西：
|
||
|
||
| 位置 | 内容 | Copilot 是否自动读 |
|
||
|---|---|---|
|
||
| `.github/instructions/superpowers-zh.instructions.md` | 索引：核心规则 + 20 个 skill 的触发条件表 | **是**（`applyTo: "**"`） |
|
||
| `.github/superpowers/<name>/SKILL.md` | skill 正文 | 否，由索引引导按需读取 |
|
||
|
||
**为什么不直接改 `.github/copilot-instructions.md`：** 那是你的文件。我们用自己的 `.instructions.md`，两者互不干扰，卸载时也能精确删掉而不碰你的内容。
|
||
|
||
**为什么正文不放进索引：** `applyTo: "**"` 的文件对每个请求都生效，正文塞进去就是每轮常驻开销。索引 4.5 KB，正文按需读。
|
||
|
||
### frontmatter 说明
|
||
|
||
```yaml
|
||
---
|
||
applyTo: "**" # 对所有文件/请求生效；省略此字段则只能在对话里手动挂载
|
||
name: Superpowers-ZH
|
||
description: superpowers-zh 技能框架的索引与触发规则
|
||
---
|
||
```
|
||
|
||
`applyTo` 是关键 —— 官方文档原文：省略它，「instructions 不会自动应用，但你仍可手动加进某次聊天请求」。也就是说不写就等于白写。
|
||
|
||
### 使用 .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
|