vscode-extension-builder-lawvable

VS Code 扩展

从头开始构建 VS Code 扩展，或将现有 Web 应用转换为可移植、可分享的扩展。

架构

VS Code 扩展运行在两种上下文中：

1. 扩展宿主（Node.js） — 后端逻辑、文件访问、VS Code API
2. Webview（浏览器沙箱） — 使用 HTML/CSS/JS 构建的自定义 UI（React、Vue、原生）

构建技术栈：TypeScript + esbuild（扩展）+ Vite（Webview）

快速开始

1. 根据需求从 assets/ 中选择模板（参见下方决策树）
2. 将模板复制到项目目录
3. 更新 package.json：name、displayName、publisher、description
4. 运行 npm install，然后运行 npm run build
5. 在 VS Code 中按 F5，启动扩展开发宿主

模板决策树

需求	模板
简单命令/操作	assets/basic-command/
自定义 UI 面板（React）	assets/webview-react/
侧边栏文件树	assets/tree-view/
自定义文件编辑器	assets/custom-editor/
AI Agent 集成	assets/file-bridge/

扩展类型

命令

注册可通过命令面板、键盘快捷键或菜单触发的操作。

vscode.commands.registerCommand('myExt.doSomething', () => {
  vscode.window.showInformationMessage('Done!');
});

常用 API 请参阅 references/api-reference.md。

Webview

在面板或侧边栏中显示完整的 HTML/CSS/JS UI。复杂界面可使用 React。

const panel = vscode.window.createWebviewPanel(
  'myView', 'My Panel', vscode.ViewColumn.One,
  { enableScripts: true }
);
panel.webview.html = getWebviewContent();

React 设置、消息传递和 CSP 请参阅 references/webview-patterns.md。

树视图

在侧边栏中显示分层数据（文件浏览器、大纲、列表）。

vscode.window.registerTreeDataProvider('myTreeView', new MyTreeProvider());

TreeDataProvider 模式请参阅 references/tree-view-patterns.md。

自定义编辑器

为特定文件类型替换默认编辑器。

vscode.window.registerCustomEditorProvider('myExt.myEditor', new MyEditorProvider());

文档同步和撤销/重做请参阅 references/custom-editor-patterns.md。

转换现有应用

将 JS/React/Vue 应用转换为扩展：

1. 评估 — 应用的功能是什么？需要哪些 VS Code 特性？
2. 映射 API — 将 Web API 替换为对应的 VS Code API
3. 重构 — 将 UI 移入 Webview，将逻辑移入扩展宿主
4. 连接 — 配置 postMessage 通信

Web API	VS Code 对应项
localStorage	context.globalState / context.workspaceState
fetch()	vscode.workspace.fs，或保留 fetch 用于外部 API
路由器	多个 Webview 面板或侧边栏视图
alert()	vscode.window.showInformationMessage()
prompt()	vscode.window.showInputBox()
confirm()	带选项的 vscode.window.showWarningMessage()

详细的分步流程请参阅 references/conversion-guide.md。

构建系统

扩展代码 — 使用 esbuild（快速、简单）：

// esbuild.js
esbuild.build({
  entryPoints: ['src/extension.ts'],
  bundle: true,
  outfile: 'dist/extension.js',
  external: ['vscode'],
  format: 'cjs',
  platform: 'node',
});

Webview 代码 — 使用 Vite（HMR、支持 React）：

// vite.config.ts
export default defineConfig({
  build: {
    outDir: '../dist/webview',
    rollupOptions: { output: { entryFileNames: '[name].js' } }
  }
});

完整配置请参阅 references/build-config.md。

package.json 清单

必需字段：

{
  "name": "my-extension",
  "displayName": "My Extension",
  "publisher": "your-publisher-id",
  "version": "0.0.1",
  "engines": { "vscode": "^1.85.0" },
  "main": "./dist/extension.js",
  "activationEvents": [],
  "contributes": {
    "commands": [{ "command": "myExt.hello", "title": "Hello" }]
  }
}

contributes 部分用于定义命令、菜单、视图、设置、键绑定等。

所有贡献点类型请参阅 references/contribution-points.md。

IPC 模式

扩展 ↔ Webview

使用 postMessage 进行双向通信：

// Extension → Webview
panel.webview.postMessage({ type: 'update', data: {...} });

// Webview → Extension
panel.webview.onDidReceiveMessage(msg => {
  if (msg.type === 'save') { /* handle */ }
});

扩展 ↔ 外部工具（AI Agent）

使用基于文件的 IPC 与 Claude Code 或其他 Agent 通信：

// Watch for command files
fs.watch(commandDir, (event, filename) => {
  if (filename.endsWith('.json')) {
    const command = JSON.parse(fs.readFileSync(path.join(commandDir, filename)));
    processCommand(command);
  }
});

文件桥接模式请参阅 references/ai-integration.md。

打包与分发

打包为 .vsix

npm install -g @vscode/vsce
vsce package

这会创建 my-extension-0.0.1.vsix。

.vscodeignore

排除不必要的文件：

.vscode/**
node_modules/**
src/**
*.ts
tsconfig.json
esbuild.js
vite.config.ts

分发选项

1. 直接分享 — 发送 .vsix 文件，通过 code --install-extension file.vsix 安装
2. VS Marketplace — 使用 vsce publish 发布（需要 Microsoft 账户）
3. Open VSX — 面向开源扩展的替代注册表

特定平台的构建

对于包含原生依赖项的扩展：

vsce package --target win32-x64
vsce package --target darwin-arm64
vsce package --target linux-x64

参考文件

文件	阅读时机
api-reference.md	实现扩展功能
contribution-points.md	配置 package.json 的 contributes
webview-patterns.md	构建 React Webview
tree-view-patterns.md	实现树视图
custom-editor-patterns.md	构建自定义文件编辑器
build-config.md	配置 esbuild/Vite
conversion-guide.md	转换 Web 应用
ai-integration.md	与 AI Agent 集成

资源模板

模板	描述
basic-command/	仅包含一个命令的最小扩展
webview-react/	带消息传递功能的 React Webview 面板
tree-view/	带提供程序的侧边栏树视图
custom-editor/	用于特定文件类型的自定义编辑器
file-bridge/	面向 AI Agent 的基于文件的 IPC