Vscode Extension Dev

gsd:workflow gsd:meta vscode-extension-dev scaffold-to-release gsd:goal产出可编译、可调试、可打包并可发布的 VSCode 插件项目。 <gsd:phase id="1" name="detect-and-init">检测现有项目状态并建立标准目录结构与基础元数据。 <gsd:phase id="2" name="configure-and-generate">生成核心配置文件与功能模板代码，确保本地编译通过。 <gsd:phase id="3" name="package-and-publish">执行打包、版本发布与自动化工作流配置，完成交付验证。

VSCode 插件开发脚手架

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

运行模式

默认: interactive

前置依赖

• Node.js 18.x+
• pnpm（推荐）或 npm
• GitHub CLI (gh) - 用于配置 Secrets
• VS Code 1.85.0+

Phase 1: 项目检测与初始化

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

步骤:

1.1 检测现有项目

# 检测是否已有 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 选择项目类型（新项目）

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 2–3：核心配置与功能模板

初始化项目或新增功能模块时，读取 references/project-templates.md，按需选用：

• package.json、tsconfig.json、webpack.config.js
• .vscode/launch.json、.vscodeignore
• 基础 extension.ts
• 状态栏插件模板
• package.json contributes 配置

只复制当前项目需要的模板，并保持项目已有配置与命名。

Phase 4: 发布环境配置

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

步骤:

4.1 检查配置状态

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

# 方式 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:

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

# <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

# Change Log

## [0.0.1] - 2024-01-01
### Added
- Initial release

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

验证

# 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"

开发工作流

# 开发
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///actions

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

禁止事项

• 不要跳过项目检测: 必须先检测项目状态
• 不要覆盖已有配置: 检测后询问是否覆盖
• 不要自动创建 Secrets: PAT 必须用户手动输入
• 不要忽略 Open VSX: 同时配置两个平台
• 不要在配置未完成时触发发布: 会失败

参考资料

• VSCode Extension API
• vsce 工具文档
• Open VSX 发布指南