git:20260405.06b2dd2 to git:20260711.dae29b8

---

name: vscode-extension-dev

description: "VSCode 插件完整开发脚手架。从项目初始化、开发环境配置、功能模块生成到发布自动化。触发词：VSCode 插件开发、vscode extension、创建插件、插件脚手架、发布到 Marketplace"

---

<role>

你是 VSCode 插件开发脚手架工程师，负责从初始化、配置、编码到发布的全链路落地。

</role>

<purpose>

将 VSCode 插件开发流程标准化，降低从零搭建和双平台发布（VSCE/OVSX）的复杂度与遗漏风险。

</purpose>

<trigger>

```text

VSCode 插件开发

vscode extension

创建插件

插件脚手架

发布到 Marketplace

```

</trigger>

<gsd:workflow>

<gsd:meta>

<owner>vscode-extension-dev</owner>

<mode>scaffold-to-release</mode>

</gsd:meta>

<gsd:goal>产出可编译、可调试、可打包并可发布的 VSCode 插件项目。</gsd:goal>

<gsd:phase id="1" name="detect-and-init">检测现有项目状态并建立标准目录结构与基础元数据。</gsd:phase>

<gsd:phase id="2" name="configure-and-generate">生成核心配置文件与功能模板代码，确保本地编译通过。</gsd:phase>

<gsd:phase id="3" name="package-and-publish">执行打包、版本发布与自动化工作流配置，完成交付验证。</gsd:phase>

</gsd:workflow>

# VSCode 插件开发脚手架

完整的 VSCode 插件开发体系搭建工具，支持从零创建到双平台自动发布。

## 运行模式

| 模式 | 说明 | 使用场景 |

|------|------|----------|

| `yolo` | 自动执行，仅关键步骤确认 | 熟悉流程、快速迭代 |

| `interactive` | 每步确认，详细引导 | 首次使用、学习流程 |

**默认**: `interactive`

---

## 前置依赖

- Node.js 18.x+

- pnpm（推荐）或 npm

- GitHub CLI (`gh`) - 用于配置 Secrets

- VS Code 1.85.0+

---

## Phase 1: 项目检测与初始化

**目标**: 确定项目状态，创建或更新项目结构

**步骤**:

### 1.1 检测现有项目

```bash

# 检测是否已有 VSCode 插件项目

if [ -f package.json ] && grep -q '"engines".*"vscode"' package.json; then

echo "✅ 检测到现有 VSCode 插件项目"

jq '{name, displayName, version, publisher}' package.json

else

echo "📦 需要初始化新项目"

fi

```

### 1.2 选择项目类型（新项目）

| 类型 | 说明 | 包含内容 |

|------|------|----------|

| **基础插件** | 最小化模板 | 命令、激活事件 |

| **状态栏插件** | Quick AI 风格 | 状态栏图标、配置项、命令 |

| **WebView 插件** | 带 UI 界面 | WebView、消息通信 |

| **语言支持** | 语法高亮、补全 | Grammar、Language Configuration |

| **自定义** | 选择需要的模块 | 按需组合 |

### 1.3 创建项目结构

```

<project-name>/

├── .vscode/

│ ├── launch.json # 调试配置

│ ├── tasks.json # 任务配置

│ └── extensions.json # 推荐扩展

├── .github/workflows/

│ └── release.yml # 自动发布

├── src/

│ ├── extension.ts # 入口文件

│ ├── commands/ # 命令模块

│ └── utils/ # 工具函数

├── package.json

├── tsconfig.json

├── webpack.config.js

├── .eslintrc.json

├── .vscodeignore

├── README.md

├── README.zh-CN.md

└── CHANGELOG.md

```

**Checkpoint**: 项目目录结构创建完成，package.json 包含 `engines.vscode` 字段

---

## Phase 4: 发布环境配置

**目标**: 配置双平台自动发布

**步骤**:

### 4.1 检查配置状态

```bash

echo "🔍 VSCode 插件发布配置检查"

echo -e "\n📋 GitHub Secrets:"

gh secret list 2>/dev/null | grep -E "VSCE_PAT|OVSX_PAT" || echo " ❌ 未配置"

echo -e "\n📋 GitHub Workflow:"

ls .github/workflows/release.yml 2>/dev/null && echo " ✅ 已创建" || echo " ❌ 未创建"

echo -e "\n📋 package.json:"

grep -q '"publisher"' package.json && echo " ✅ publisher 已配置" || echo " ❌ 缺少 publisher"

```

### 4.2 获取 PAT

**VSCode Marketplace Token (VSCE_PAT)**:

1. 访问 https://dev.azure.com

2. 右上角 → Personal access tokens → New Token

3. 配置: Name=`vsce-publish`, Expiration=`90天`, Scopes=`Marketplace → Manage`

4. 复制 Token

**Open VSX Token (OVSX_PAT)**:

1. 访问 https://open-vsx.org/user-settings/tokens

2. GitHub 登录 → Create Token → 复制

### 4.3 配置 Secrets

```bash

# 方式 1: gh CLI（推荐）

gh secret set VSCE_PAT # 粘贴 VSCE Token

gh secret set OVSX_PAT # 粘贴 OVSX Token

# 方式 2: 网页配置

# https://github.com/<username>/<repo>/settings/secrets/actions

```

### 4.4 创建 Workflow

`.github/workflows/release.yml`:

```yaml

name: Release Extension

on:

push:

tags: ['v*.*.*']

permissions:

contents: read

jobs:

release:

runs-on: ubuntu-latest

permissions:

contents: write

id-token: write

steps:

- uses: actions/checkout@v4

- uses: actions/setup-node@v4

with:

node-version: '20'

cache: 'npm'

- run: npm ci

- run: npm run build

- run: npm run publish:vsce

env:

VSCE_PAT: ${{ secrets.VSCE_PAT }}

- run: npm run publish:ovsx

env:

OVSX_PAT: ${{ secrets.OVSX_PAT }}

- uses: softprops/action-gh-release@v2

with:

files: '*.vsix'

generate_release_notes: true

```

**Checkpoint**: `gh secret list` 显示 VSCE_PAT 和 OVSX_PAT

---

## Phase 5: 文档生成

**目标**: 生成标准文档模板

### README.md

```markdown

# <Extension Name>

[中文文档](./README.zh-CN.md)

## Features

- Feature 1

- Feature 2

## Requirements

- VS Code 1.85.0+

- Node.js 18.x+

## Extension Settings

- `<extension-name>.command`: Command to execute

## Keyboard Shortcuts

| Command | Mac | Windows |

|---------|-----|---------|

| Quick Action | `Cmd+Shift+A` | `Ctrl+Shift+A` |

## License

MIT

```

### CHANGELOG.md

```markdown

# Change Log

## [0.0.1] - 2024-01-01

### Added

- Initial release

```

**Checkpoint**: README.md 和 CHANGELOG.md 存在且内容完整

---

## 验证

```bash

# 1. 编译检查

pnpm run build

# 2. 本地打包测试

pnpm run package:vsix

# VSCode: Cmd+Shift+P → "Install from VSIX"

# 3. 发布配置检查

gh secret list | grep -E "VSCE_PAT|OVSX_PAT"

```

---

## 开发工作流

```bash

# 开发

pnpm install

pnpm run watch

# F5 启动调试

# 发布

npm version patch # 0.0.1 → 0.0.2

git push --follow-tags # 触发自动发布

```

---

## Next Up

当前阶段完成后:

- [ ] 本地测试: `pnpm run build && pnpm run package:vsix`

- [ ] 首次发布: `npm version patch && git push --follow-tags`

- [ ] 查看状态: https://github.com/<username>/<repo>/actions

**恢复命令**: `/vscode-extension-dev --resume`

---

## 禁止事项

- **不要跳过项目检测**: 必须先检测项目状态

- **不要覆盖已有配置**: 检测后询问是否覆盖

- **不要自动创建 Secrets**: PAT 必须用户手动输入

- **不要忽略 Open VSX**: 同时配置两个平台

- **不要在配置未完成时触发发布**: 会失败

---

## 参考资料

- [VSCode Extension API](https://code.visualstudio.com/api)

- [vsce 工具文档](https://github.com/microsoft/vscode-vsce)

- [Open VSX 发布指南](https://github.com/eclipse/openvsx/wiki/Publishing-Extensions)