fix(installer): VS Code 装的 20 个文件 Copilot 一个都不读（又一个纯死重）

## 问题官方文档（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
2026-09-02 22:54:06 +08:00 · 2026-08-12 21:03:40 +08:00
parent 43edf34b2c
commit 0e3fbc4830
5 changed files with 114 additions and 26 deletions
--- a/README.md
+++ b/README.md
@@ -146,7 +146,7 @@ AI：在开始实现之前，我需要了解几个关键问题：
 | [Codex CLI](https://github.com/openai/codex) | CLI | `npx superpowers-zh` | `.codex/skills/` |
 | [Aider](https://aider.chat) | CLI | `npx superpowers-zh` | `.aider/skills/` |
 | [Trae](https://trae.ai) | IDE | `npx superpowers-zh` | `.trae/skills/` + `.trae/rules/` |
-| [VS Code](https://code.visualstudio.com) (Copilot) | IDE 插件 | `npx superpowers-zh` | `.github/superpowers/` |
+| [VS Code](https://code.visualstudio.com) (Copilot) | IDE 插件 | `npx superpowers-zh` | `.github/superpowers/` + `.github/instructions/` |
 | [DeerFlow 2.0](https://github.com/bytedance/deer-flow) | Agent 框架 | `npx superpowers-zh` | `skills/custom/` |
 | [OpenCode](https://opencode.ai) | CLI | `npx superpowers-zh` | `.opencode/skills/` |
 | [OpenClaw](https://github.com/openclaw/openclaw) | CLI | `npx superpowers-zh` | `skills/` |
--- a/README.zh-Hant.md
+++ b/README.zh-Hant.md
@@ -146,7 +146,7 @@ AI：在開始實作之前，我需要了解幾個關鍵問題：
 | [Codex CLI](https://github.com/openai/codex) | CLI | `npx superpowers-zh` | `.codex/skills/` |
 | [Aider](https://aider.chat) | CLI | `npx superpowers-zh` | `.aider/skills/` |
 | [Trae](https://trae.ai) | IDE | `npx superpowers-zh` | `.trae/skills/` + `.trae/rules/` |
-| [VS Code](https://code.visualstudio.com) (Copilot) | IDE 外掛 | `npx superpowers-zh` | `.github/superpowers/` |
+| [VS Code](https://code.visualstudio.com) (Copilot) | IDE 外掛 | `npx superpowers-zh` | `.github/superpowers/` + `.github/instructions/` |
 | [DeerFlow 2.0](https://github.com/bytedance/deer-flow) | Agent 框架 | `npx superpowers-zh` | `skills/custom/` |
 | [OpenCode](https://opencode.ai) | CLI | `npx superpowers-zh` | `.opencode/skills/` |
 | [OpenClaw](https://github.com/openclaw/openclaw) | CLI | `npx superpowers-zh` | `skills/` |
--- a/bin/superpowers-zh.js
+++ b/bin/superpowers-zh.js
@@ -82,7 +82,17 @@ const TARGETS = [
  // Antigravity 无 global：其全局 skills 加载路径未在 docs 证实（全局规则走 ~/.gemini/GEMINI.md），
  // 不确认能生效就不写，避免「装了不生效」。用户用项目级安装。
  { name: 'Antigravity',   dir: '.agents/skills',            detect: '.agents' },
-  { name: 'VS Code',       dir: '.github/superpowers',       detect: '.github/copilot-instructions.md' },
+  // VS Code Copilot **不认识** .github/superpowers/ —— 官方（code.visualstudio.com
+  // /docs/copilot/customization/custom-instructions）只自动读这几处：
+  //   .github/copilot-instructions.md、AGENTS.md、CLAUDE.md（always-on）
+  //   .github/instructions/*.instructions.md（按 frontmatter 的 applyTo 匹配）
+  // v1.7.10 及更早只把 skills 拷进 .github/superpowers/ 且**不写任何引导** ——
+  // 20 个文件 Copilot 一个都不会读，纯死重。旧文档甚至写着「建议你自己创建
+  // copilot-instructions.md 引用它们」，等于知道需要却不做。
+  // 现在写 .github/instructions/superpowers-zh.instructions.md（applyTo: "**" 即
+  // 全局生效）—— 用我们自己的文件而不是去改用户的 copilot-instructions.md。
+  // 检测标记同时认 .github/instructions（用了 instructions 机制的项目都有）。
+  { name: 'VS Code',       dir: '.github/superpowers',       detect: ['.github/copilot-instructions.md', '.github/instructions'] },
  { name: 'OpenClaw',      dir: 'skills',                     detect: '.openclaw',                     global: { dir: '.openclaw/skills',       detect: '.openclaw' } },
  // Windsurf 全局路径与项目级**不同构**，这点反直觉：官方文档（docs.windsurf.com
  // /windsurf/cascade/skills，现 307 跳 docs.devin.ai/desktop/cascade/skills）写明
@@ -102,6 +112,10 @@ const TARGETS = [
  //    conventions.html）明确要 `aider --read CONVENTIONS.md` 或在 .aider.conf.yml
  //    写 `read: CONVENTIONS.md`。所以装完必须打印激活方式，否则又是「装了不生效」。
  { name: 'Aider',         dir: '.aider/skills',             detect: ['.aider.conf.yml', '.aider.chat.history.md', '.aider.tags.cache.v3', '.aider'] },
+  // OpenCode 经官方文档核实（opencode.ai/docs/skills）：项目 .opencode/skills/<name>/SKILL.md、
+  // 全局 ~/.config/opencode/skills/<name>/SKILL.md，自动发现（项目级会从 cwd 向上走到
+  // git worktree 根）。它同时扫 .claude/skills 与 .agents/skills —— 装过 CC 或
+  // Antigravity 的项目它已经能读到，别重复装。
  { name: 'OpenCode',      dir: '.opencode/skills',          detect: '.opencode',                      global: { dir: '.config/opencode/skills', detect: '.config/opencode' } },
  // Qwen Code = QwenLM/qwen-code 这个 CLI（Gemini CLI 的 fork），**不是**通义灵码
  // （通义灵码是阿里的 IDE 插件，另一个产品，路径完全不同）。旧文档写混过。
@@ -607,6 +621,55 @@ ${skillList}

 // Claw Code：根指令文件是 CLAW.md（优先级 CLAUDE.md > CLAW.md > AGENTS.md，
 // 见 ultraworkers/claw-code 的 USAGE.md）。v1.7.10 及更早只装 skills、不写 bootstrap。
+// VS Code Copilot：写 .github/instructions/superpowers-zh.instructions.md。
+// applyTo: "**" 表示对所有请求生效（省略该字段则只能手动挂载，等于白写）。
+// 刻意不动用户的 .github/copilot-instructions.md —— 那是他们的文件。
+function generateVSCodeBootstrap(projectDir) {
+  const instrDir = resolve(projectDir, '.github', 'instructions');
+  mkdirSync(instrDir, { recursive: true });
+
+  const skillEntries = scanSkillEntries(SKILLS_SRC);
+  const skillTable = skillEntries.map(s => `| ${s.name} | ${s.desc} |`).join('\n');
+
+  const rule = `---
+applyTo: "**"
+name: Superpowers-ZH
+description: superpowers-zh 技能框架的索引与触发规则
+---
+
+# Superpowers-ZH 中文增强版
+
+本项目已安装 superpowers-zh 技能框架（${skillEntries.length} 个 skills）。
+
+## 核心规则
+
+1. **收到任务时，先检查是否有匹配的 skill** — 哪怕只有 1% 的可能性也要检查
+2. **设计先于编码** — 收到功能需求时，先用 brainstorming skill 做需求分析
+3. **测试先于实现** — 写代码前先写测试（TDD）
+4. **验证先于完成** — 声称完成前必须运行验证命令
+
+## 可用 Skills
+
+Skills 位于 \`.github/superpowers/\` 目录，每个 skill 有独立的 \`SKILL.md\` 文件。
+
+| Skill | 触发条件 |
+|-------|---------|
+${skillTable}
+
+## 如何使用
+
+当任务匹配某个 skill 的触发条件时，读取对应的
+\`.github/superpowers/<skill-name>/SKILL.md\` 并严格遵循其流程。
+
+**不要**把 skill 正文复制到本文件 —— 本文件对每个请求都生效，按需读取才能把
+常驻开销控制在这张索引表。
+`;
+
+  const rulePath = resolve(instrDir, 'superpowers-zh.instructions.md');
+  writeFileSync(rulePath, rule, 'utf8');
+  console.log(`  ✅ VS Code: instructions -> ${rulePath}`);
+}
+
 function generateClawBootstrap(projectDir) {
  const skillEntries = scanSkillEntries(SKILLS_SRC);
  const skillList = skillEntries.map(s => `- **${s.name}**: ${s.desc}`).join('\n');
@@ -995,6 +1058,10 @@ function installForTarget(target, baseDir, isGlobal) {
    generateQwenBootstrap(baseDir, isGlobal);
  }

+  if (target.name === 'VS Code') {
+    generateVSCodeBootstrap(baseDir);
+  }
+
  if (target.name === 'Claw Code') {
    generateClawBootstrap(baseDir);
  }
@@ -1034,6 +1101,7 @@ function isHomeDir(p) {

 // 卸载支持：完整删除的 bootstrap 文件、需要清理段落的 bootstrap 文件
 const BOOTSTRAP_DELETE = [
+  '.github/instructions/superpowers-zh.instructions.md',
  '.trae/rules/superpowers-zh.md',
  '.qoder/rules/superpowers-zh.md',
  '.agents/rules.md',
--- a/docs/README.vscode.md
+++ b/docs/README.vscode.md
@@ -24,38 +24,47 @@ 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
+```
+
 ## 工作原理

-VS Code Copilot 使用 `.github/copilot-instructions.md` 作为项目级自定义指令：
+装两样东西：

- **位置**：项目根目录 `.github/copilot-instructions.md`
- **格式**：Markdown
- **生效范围**：该工作区内的所有 Copilot Chat 和内联补全
- **自动加载**：保存文件后立即生效，无需重启
+| 位置 | 内容 | Copilot 是否自动读 |
+|---|---|---|
+| `.github/instructions/superpowers-zh.instructions.md` | 索引：核心规则 + 20 个 skill 的触发条件表 | **是**（`applyTo: "**"`） |
+| `.github/superpowers/<name>/SKILL.md` | skill 正文 | 否，由索引引导按需读取 |

-### 推荐配置
+**为什么不直接改 `.github/copilot-instructions.md`：** 那是你的文件。我们用自己的 `.instructions.md`，两者互不干扰，卸载时也能精确删掉而不碰你的内容。

-由于 Copilot 主要通过单个指令文件工作，建议创建 `.github/copilot-instructions.md` 引用 skills：
+**为什么正文不放进索引：** `applyTo: "**"` 的文件对每个请求都生效，正文塞进去就是每轮常驻开销。索引 4.5 KB，正文按需读。

-```markdown
-# Copilot 自定义指令
+### frontmatter 说明

-## 工作流方法论
-
-本项目使用 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 遵循中文提交规范
- 技术术语保留英文原文
+```yaml
+---
+applyTo: "**"      # 对所有文件/请求生效；省略此字段则只能在对话里手动挂载
+name: Superpowers-ZH
+description: superpowers-zh 技能框架的索引与触发规则
+---
 ```

+`applyTo` 是关键 —— 官方文档原文：省略它，「instructions 不会自动应用，但你仍可手动加进某次聊天请求」。也就是说不写就等于白写。
+
 ### 使用 .instructions.md 文件（推荐）

 VS Code 还支持更细粒度的 `.instructions.md` 文件：
--- a/scripts/verify-release.sh
+++ b/scripts/verify-release.sh
@@ -177,6 +177,17 @@ rows=$(grep -cE '^\| [a-z][a-z0-9-]+ \|' "$R")
 grep -q '\.kilocode/skills/' "$R" && ok || bad "Kilo 索引未指向 .kilocode/skills/"
 cd /; rm -rf "$T"

+# VS Code：Copilot 不认识 .github/superpowers/，必须靠 instructions 文件引导。
+# applyTo 缺失的话该文件只能手动挂载 = 白写，所以这条要硬断言。
+T=$(mktemp -d); cd "$T"; node "$INS" --tool vscode >/dev/null 2>&1
+R="$T/.github/instructions/superpowers-zh.instructions.md"
+[ -f "$R" ] && ok || bad "VS Code instructions 文件未生成 —— skills 会成为 Copilot 读不到的死重"
+grep -q '^applyTo: "\*\*"' "$R" && ok || bad "VS Code instructions 缺 applyTo: \"**\"（不写就只能手动挂载）"
+rows=$(grep -cE '^\| [a-z][a-z0-9-]+ \|' "$R")
+[ "$rows" = "$EXPECT_SKILLS" ] && ok || bad "VS Code 索引表 $rows 行，期望 $EXPECT_SKILLS"
+grep -q '\.github/superpowers/' "$R" && ok || bad "VS Code 索引未指向 .github/superpowers/"
+cd /; rm -rf "$T"
+
 T=$(mktemp -d); cd "$T"; node "$INS" --tool kiro >/dev/null 2>&1
 R="$T/.kiro/steering/superpowers-zh.md"
 [ -f "$R" ] && ok || bad "Kiro steering 索引未生成"