1. 从零写一个 VS Code 插件为什么 Activation Events 和 LSP 是绕不开的两道坎VS Code 插件本质上就是一个带package.json的 npm 包但真正决定它「能不能用、好不好用」的是两件事插件什么时候被唤醒以及它怎么给一门语言提供智能能力。前者靠 Activation Events后者靠 LSPLanguage Server Protocol。很多人第一次写插件卡就卡在这两个点上——要么插件装上了但命令点了没反应要么语言服务启动了却收不到补全。先说 Activation Events。VS Code 为了省资源默认不会在启动时把所有插件都跑起来而是等你触发了某个事件才调用插件的activate()。这个「触发条件」就是 Activation Events。你在package.json里声明onCommand:xxx用户执行这个命令时插件才醒声明onLanguage:python打开 Python 文件时才醒。声明错了插件就像没装一样安静。再说 LSP。VS Code 不允许插件直接操作 DOM所以想给一门语言加补全、跳转定义、hover 提示正确姿势是写一个 Language Server通过 JSON-RPC 和编辑器通信。VS Code 提供vscode-languageclient帮你把客户端这层封装好你只要负责启动 server、连上通道就行。听起来简单但真正落地时会遇到进程启动失败、初始化超时、reading choices这类报错。这篇就按「能跑起来、能发布」的标准把 contribution points 声明、Activation Events 懒加载、LSP 客户端接入这三段链路串一遍。中间涉及模型调用联调的部分我用 TaoToken 统一 Key 和 API 通道省得在多个平台之间来回切。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 下面直接进配置。2. TaoToken 前置准备统一 Key 与 API 通道给插件联调留好后路写插件时经常需要调模型比如做一个「选中代码自动解释」的命令或者给语言服务加一个 AI 补全。如果每个功能都去接不同的模型平台Key 管理、Base URL 切换、额度查看会非常碎。我的做法是先用 TaoToken 把通道统一掉插件里只认一个 Base URL 和一个 Key后面换模型只改 Model ID。第一步打开 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建 API Key。建议按插件项目建一个独立的 Key命名成vscode-plugin-dev之类方便后面排查是哪个项目在调用。创建完先复制保存页面刷新后就不再完整显示了。第二步确认 Base URL。TaoToken 的 API 入口是 https://taotoken.net/api 注意这个地址不带任何查询参数直接作为 OpenAI 兼容的 base_url 使用。如果你用的是 Anthropic 风格的接口走 https://taotoken.net/api 下的对应路径即可具体以接入文档为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。第三步选一个 Model ID 用于联调。插件开发阶段我一般先用响应快的模型验证链路通不通等逻辑跑顺了再换更强的模型。Model ID 在模型对话页面能看到https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。把 Key、Base URL、Model ID 这三样记下来后面写进插件的配置里。这里有个细节要注意插件里不要把 Key 硬编码进源码。正确做法是让用户通过 VS Code 的settings.json或SecretStorage填 Key插件运行时读取。开发阶段你可以先用自己的 Key 跑通发布前一定要改成用户自填。TaoToken 的 Key 支持在控制台随时吊销万一泄露也不至于失控https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你后面要做的是长期编码类插件比如带 Agent 能力的代码助手可以考虑 Coding Plan额度模型更适合高频调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。前置准备就这些接下来进package.json。3. 可复制配置package.json 里的 contribution points 与 Activation Events 怎么写插件的package.json是整个项目的入口声明VS Code 靠它知道你的插件叫什么、什么时候激活、提供哪些能力。下面这份配置我按「一个带命令 语言服务 配置项」的插件来写你可以直接抄改。先看activationEvents和contributes的整体结构{ name: my-lsp-plugin, displayName: My LSP Plugin, version: 0.0.1, engines: { vscode: ^1.85.0 }, activationEvents: [ onLanguage:plaintext, onCommand:myLspPlugin.explainSelection ], main: ./out/extension.js, contributes: { commands: [ { command: myLspPlugin.explainSelection, title: Explain Selection with AI } ], configuration: { title: My LSP Plugin, properties: { myLspPlugin.baseUrl: { type: string, default: https://taotoken.net/api, description: OpenAI 兼容的 Base URL }, myLspPlugin.modelId: { type: string, default: gpt-4o-mini, description: 用于联调的 Model ID } } } } }这里有几个点容易踩坑。activationEvents里我写了onLanguage:plaintext意思是打开纯文本文件时激活插件这样语言服务能尽早启动。如果你只写onCommand那用户不点命令插件就一直不醒语言服务也就起不来。另一个坑是main字段必须指向编译后的 JS 文件TypeScript 项目要确认out/extension.js真的存在否则插件加载直接失败。contributes.commands声明了命令contributes.configuration声明了配置项。配置项的default我直接填了 TaoToken 的 Base URL用户装完插件不用改就能用。Model ID 留成可配置方便切换。如果你还要加菜单项比如在编辑器右键菜单里出现这个命令补一段menusmenus: { editor/context: [ { command: myLspPlugin.explainSelection, when: editorHasSelection, group: navigation } ] }when: editorHasSelection保证只有选中文本时才显示避免用户点了没反应。contribution points 的完整清单在官方文档里有但常用的就是 commands、configuration、menus、languages、grammars 这几类。声明多了不会报错但会让插件显得臃肿按需加就行。配置写完后npm install再npm run compile然后按 F5 启动 Extension Development Host新窗口里打开一个 txt 文件插件就应该被激活了。如果没反应先看「输出」面板里有没有插件日志再看activationEvents拼写对不对——onLanguage后面跟的是 language id不是文件扩展名txt 文件的 language id 是plaintext不是txt。4. LSP 客户端启动与验证从 LanguageClient 到一次成功的请求语言服务这块我用vscode-languageclient来写客户端。先装依赖npm install vscode-languageclient然后在extension.ts里启动客户端。下面这段是核心逻辑我把它拆成「创建 server 选项」和「启动客户端」两步import * as path from path; import * as vscode from vscode; import { LanguageClient, LanguageClientOptions, ServerOptions, TransportKind } from vscode-languageclient/node; let client: LanguageClient; export function activate(context: vscode.ExtensionContext) { const serverModule context.asAbsolutePath( path.join(out, server.js) ); const serverOptions: ServerOptions { run: { module: serverModule, transport: TransportKind.ipc }, debug: { module: serverModule, transport: TransportKind.ipc, options: { execArgv: [--nolazy, --inspect6009] } } }; const clientOptions: LanguageClientOptions { documentSelector: [{ scheme: file, language: plaintext }], synchronize: { fileEvents: vscode.workspace.createFileSystemWatcher(**/*.txt) } }; client new LanguageClient( myLspPlugin, My LSP Plugin, serverOptions, clientOptions ); client.start(); const disposable vscode.commands.registerCommand( myLspPlugin.explainSelection, async () { const editor vscode.window.activeTextEditor; if (!editor) { return; } const selection editor.document.getText(editor.selection); if (!selection) { vscode.window.showInformationMessage(请先选中一段文本); return; } const config vscode.workspace.getConfiguration(myLspPlugin); const baseUrl config.getstring(baseUrl); const modelId config.getstring(modelId); vscode.window.showInformationMessage( 将用 ${modelId} 通过 ${baseUrl} 解释选中内容 ); } ); context.subscriptions.push(disposable); } export function deactivate(): Thenablevoid | undefined { if (!client) { return undefined; } return client.stop(); }serverOptions里TransportKind.ipc表示客户端和 server 通过进程间通信这是最省事的模式不用自己管端口。documentSelector决定哪些文件触发这个语言服务我写的是plaintext你可以换成python、go等。client.start()之后VS Code 会去启动out/server.js。这个 server 文件需要你自己实现最简单的做法是用vscode-languageserver起一个连接import { createConnection, TextDocuments, ProposedFeatures } from vscode-languageserver/node; import { TextDocument } from vscode-languageserver-textdocument; const connection createConnection(ProposedFeatures.all); const documents new TextDocuments(TextDocument); connection.onInitialize(() { return { capabilities: { textDocumentSync: 1, hoverProvider: true } }; }); connection.onHover((params) { return { contents: { kind: markdown, value: 来自 My LSP Plugin 的 hover 提示 } }; }); documents.listen(connection); connection.listen();编译后按 F5在新窗口打开一个 txt 文件把鼠标悬停在文字上应该能看到 hover 提示。这一步成功说明 LSP 通道打通了。接下来把模型调用接进命令里用 TaoToken 的 Base URL 发一次请求验证const response await fetch(${baseUrl}/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${apiKey} }, body: JSON.stringify({ model: modelId, messages: [ { role: user, content: 解释这段代码\n${selection} } ] }) }); const data await response.json(); const text data.choices?.[0]?.message?.content ?? 无返回; vscode.window.showInformationMessage(text.slice(0, 200));apiKey从context.secrets.get(myLspPlugin.apiKey)读不要写死。跑通后你会看到通知里弹出模型返回的解释说明插件、LSP、模型调用三条链路都通了。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth 逐个拆插件开发阶段报错集中在几类我按实际遇到的频率排一下。第一类401 Unauthorized。这个基本是 Key 的问题。先确认Authorization头是不是Bearer开头中间有空格再确认 Key 有没有多余换行或引号。如果你把 Key 存在settings.json里注意 JSON 字符串不能有尾随空格。还有一种情况是 Key 被吊销了去控制台看一眼状态https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。401 不会因为 Model ID 写错而出现Model ID 错一般是 404 或 400。第二类local proxy failed或连接被拒绝。这个多半是 Base URL 写错了。TaoToken 的 API 入口是 https://taotoken.net/api 不要在后面多加/v1又重复拼一次也不要用官网首页地址去发请求。如果你在插件里让用户填 Base URL记得在读取时做一次trim()用户复制粘贴很容易带空格。另外确认你的网络环境能正常访问该地址公司内网如果有出口限制需要走允许的通道。第三类Cannot read properties of undefined (reading choices)。这个报错说明请求发出去了但返回结构里没有choices。常见原因有三个一是返回的其实是错误对象比如{error: {...}}你没判断就直接取choices二是流式返回stream: true时返回的是 SSE 分片不是完整 JSON三是 Model ID 不对服务端返回了非预期结构。排查时先把response.status和原始文本打出来const raw await response.text(); console.log(status:, response.status); console.log(raw:, raw);看到原始返回问题基本就定位了。如果是流式改用response.body逐块解析或者联调阶段先关掉stream。第四类OAuth 相关报错。如果你用的是 Claude Code 这类工具做联调可能会遇到 OAuth 过期或回调失败。这类问题通常和插件本身无关是工具侧的登录态问题。处理方式是重新走一遍授权或者改用 API Key 模式。Claude Code 的接入配置里Base URL 填 https://taotoken.net/api Key 填你创建的 KeyModel ID 填对应模型三件套对齐就不会串。相关配置说明在文档里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。第五类插件装了但命令不出现。先检查contributes.commands里的command和代码里registerCommand的字符串是否完全一致大小写敏感。再看activationEvents有没有声明onCommand虽然新版 VS Code 对命令有隐式激活但显式声明更稳。最后看「开发人员显示正在运行的扩展」里插件状态是不是激活失败。6. 把插件跑通之后Key 管理、模型切换与发布前的收尾链路跑通只是第一步真正要发布还得处理几件事。Key 不能硬编码用context.secrets存配合一个「设置 API Key」的命令让用户填。Base URL 和 Model ID 放settings.json给默认值用户想换模型自己改。这样你的插件不绑定任何一家平台用户用 TaoToken 也好用别的兼容通道也好都能跑。模型切换这块我建议在插件里做一个「测试连接」命令用户填完 Key 后点一下发一个最小请求验证三件套Base URL Key Model ID是否对齐。验证通过再让用户用正式功能能省掉大量「为什么没反应」的反馈。测试请求用模型对话页面同款的 Model ID 就行https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。发布前还要确认engines.vscode的版本号不要写太低否则用不了新的 APIactivationEvents尽量精确别图省事写*那会让插件在启动时就激活用户会感知到卡顿。LSP 的 server 进程记得在deactivate里停掉不然反复调试会残留进程。最后一步是打包。用vsce package生成.vsix本地装一遍确认没问题再传到 Marketplace。如果你做的是团队内部工具也可以直接把.vsix发给同事装。整个流程走下来从package.json到 LSP 到模型联调核心就是「声明清楚、启动可控、通道统一」。把这三件事做扎实插件就不会只是 demo而是真能用的工具。