vscode-extension-builder

VS Code 扩展构建器

使用恰当的架构、最佳实践和完整的工具支持，构建专业的 VS Code 扩展。

快速入门

立即创建扩展：

1. 初始化：运行 npx --package yo --package generator-code -- yo code
2. 选择类型：新建扩展（TypeScript）
3. 填写详细信息：名称、标识符、描述
4. 开发：在 VS Code 中打开，按 F5 进行调试
5. 测试：在扩展开发主机中运行命令
6. 打包：准备就绪后运行 vsce package

如需详细指导，请按照下方工作流操作。

扩展类型

选择符合需求的类型：

• 命令扩展：向命令面板添加命令（最简单、最常见）
• 语言支持：语法高亮、IntelliSense、格式化
• Webview 扩展：使用 HTML/CSS/JS 构建自定义 UI 面板
• 树视图：使用层级数据构建自定义侧边栏视图
• 调试器：为语言添加调试支持
• 主题：颜色主题、文件图标主题
• 代码片段提供程序：为语言提供代码片段

核心工作流

1. 收集需求

询问用户：

• 用途：扩展应该做什么？
• 类型：需要哪种扩展类型？（命令、语言、Webview 等）
• 功能：需要哪些具体功能？
• UI：需要命令、视图、面板、状态栏项吗？
• 激活：何时应激活？

2. 选择扩展类型和架构

根据需求选择合适的模式：

简单命令扩展（最常见）：

• 单一职责
• 集成命令面板
• 构建速度快

语言扩展：

• 语法高亮（TextMate 语法）
• 用于 IntelliSense 的语言服务器
• 复杂但功能强大

Webview 扩展：

• 需要自定义 UI
• 丰富的交互
• 状态管理更复杂

详细结构请参阅 extension-anatomy.md。

3. 初始化项目

选项 A：使用 Yeoman 生成器（推荐）

npx --package yo --package generator-code -- yo code

填写以下内容：

• 类型：新建扩展（TypeScript）
• 名称：便于用户理解的名称
• 标识符：用连字符分隔的小写名称
• 描述：清晰说明用途
• Git：是
• 打包工具：esbuild（推荐）或 webpack
• 包管理器：npm

选项 B：使用模板

对于特定模式，从 assets/templates/ 复制：

• command-extension/ - 基于命令的扩展
• language-support/ - 语言扩展起始模板
• webview-extension/ - 基于 Webview 的扩展

4. 实现核心功能

对于命令扩展：

1. 在 package.json 中定义命令：

{
  "contributes": {
    "commands": [{
      "command": "extension.commandId",
      "title": "Command Title"
    }]
  }
}

2. 在 extension.ts 中注册命令：

export function activate(context: vscode.ExtensionContext) {
  let disposable = vscode.commands.registerCommand('extension.commandId', () => {
    vscode.window.showInformationMessage('Hello from Extension!');
  });
  context.subscriptions.push(disposable);
}

对于语言扩展： 语言功能 API 请参阅 common-apis.md。

对于 Webview 扩展： Webview 创建模式请参阅 common-apis.md。

5. 配置激活和贡献项

激活事件决定扩展何时加载：

• onCommand：调用命令时
• onLanguage：打开对应文件类型时
• onView：树视图变为可见时
• *：启动时（尽可能避免）

完整参考请参阅 activation-events.md。

贡献项在 package.json 中声明扩展功能：

• commands：命令面板条目
• menus：上下文菜单项
• keybindings：键盘快捷键
• languages：语言支持
• views：树视图
• configuration：设置

6. 测试和调试

本地测试：

1. 在 VS Code 中按 F5，启动扩展开发主机
2. 测试命令和功能
3. 在调试控制台中查看日志
4. 设置断点进行调试

自动化测试：

• 单元测试：测试业务逻辑
• 集成测试：测试 VS Code API 交互
• 使用 @vscode/test-electron 进行测试

常见问题：

• 命令未显示：检查 contributes.commands 和激活事件
• 扩展未激活：检查 package.json 中的激活事件
• API 错误：检查 VS Code API 版本兼容性

7. 打包与分发

发布前准备：

1. 更新 README.md，介绍功能和用法
2. 添加扩展图标（128x128 PNG）
3. 在 package.json 中设置仓库 URL
4. 添加 LICENSE 文件
5. 充分测试

打包扩展：

npm install -g @vscode/vsce
vsce package

会创建用于分发的 .vsix 文件。

发布到 Marketplace：

vsce publish

需要 Azure DevOps 个人访问令牌。

常见模式

模式 1：简单命令

显示信息的快捷命令：

vscode.commands.registerCommand('extension.showInfo', () => {
  vscode.window.showInformationMessage('Information message');
});

模式 2：带用户输入的命令

执行前获取输入：

vscode.commands.registerCommand('extension.greet', async () => {
  const name = await vscode.window.showInputBox({
    prompt: 'Enter your name'
  });
  if (name) {
    vscode.window.showInformationMessage(`Hello, ${name}!`);
  }
});

模式 3：文件操作命令

操作活动编辑器：

vscode.commands.registerCommand('extension.processFile', () => {
  const editor = vscode.window.activeTextEditor;
  if (!editor) {
    vscode.window.showErrorMessage('No active editor');
    return;
  }
  
  const document = editor.document;
  const text = document.getText();
  // Process text...
});

模式 4：状态栏项

显示常驻状态：

const statusBarItem = vscode.window.createStatusBarItem(
  vscode.StatusBarAlignment.Right,
  100
);
statusBarItem.text = "$(check) Ready";
statusBarItem.show();
context.subscriptions.push(statusBarItem);

参考资料导航

根据需要加载以下参考资料：

• extension-anatomy.md：需要了解以下内容时：

  • 扩展结构和文件组织
  • package.json 清单字段
  • 入口点和生命周期钩子
  • 扩展上下文和可释放资源

• common-apis.md：实现以下功能时：

  • 窗口和编辑器操作
  • 工作区和文件系统访问
  • 语言功能（IntelliSense、诊断）
  • Webview 创建和消息传递
  • 树视图和自定义 UI

• activation-events.md：配置以下内容时：

  • 扩展的加载时机
  • 性能优化
  • 延迟加载策略

• best-practices.md：考虑以下内容时：

  • 用户体验指南和设计模式
  • 性能优化
  • 安全注意事项
  • 测试策略
  • 发布指南

核心原则

性能

• 延迟加载：使用特定的激活事件，而不是 *
• 异步操作：对 I/O 使用 async/await
• 释放资源：清理订阅
• 尽量缩短启动时间：推迟耗时操作

用户体验

• 清晰的命令：使用描述性标题和类别
• 反馈：为耗时操作显示进度
• 错误处理：提供有帮助的错误消息
• 界面一致：遵循 VS Code 规范

代码质量

• TypeScript：使用严格模式确保类型安全
• 错误处理：为所有操作添加 try-catch
• 日志记录：使用 console.log 进行调试
• 测试：为关键功能编写测试

故障排除

未显示扩展

• 验证 package.json 语法（有效 JSON）
• 检查 main 字段是否指向编译后的输出
• 确保激活事件设置正确
• 重新加载窗口：Developer: Reload Window

命令无法运行

• 检查 package.json 和代码中的命令 ID 是否一致
• 确认激活事件包含该命令
• 检查调试控制台中的错误
• 确保已在 activate() 中注册命令

构建错误

• 运行 npm install 安装依赖
• 检查 TypeScript 配置
• 确认与 VS Code API 版本兼容
• 如有需要，更新 @types/vscode

按使用场景分类的示例

添加代码格式化命令

1. 类型：命令扩展
2. 激活方式：onCommand
3. 实现：获取编辑器文本、格式化并替换
4. 界面：命令面板入口

添加语法高亮

1. 类型：语言扩展
2. 激活方式：onLanguage:mylang
3. 实现：使用 JSON 编写 TextMate 语法
4. 界面：打开文件时自动生效

添加自定义侧边栏视图

1. 类型：树视图扩展
2. 激活方式：onView:myView
3. 实现：TreeDataProvider 接口
4. 界面：活动栏图标和侧边栏面板

添加快速选择菜单

1. 类型：带 UI 的命令扩展
2. 激活方式：onCommand
3. 实现：使用包含选项的 showQuickPick
4. 界面：可搜索的下拉菜单

此技能中的资源

• references/：详细文档（按需加载）
• assets/templates/：常见模式的起始模板
• 官方文档：https://code.visualstudio.com/api

相关技能

用于审查扩展代码的质量和架构：

• detect-code-smells：检查扩展代码质量
• security-pattern-check：审查扩展的安全性
• suggest-performance-fix：优化扩展性能

注意事项

此技能提供 VS Code 扩展开发的完整工作流，涵盖从初步构想到发布扩展的全过程。采用渐进式披露：简单情况从快速入门开始，复杂需求则深入查阅参考资料。assets/ 中的模板可作为常见模式的复制粘贴起点。