1. 从零写一个 VSCode 代码补全插件为什么值得动手VSCode 插件开发这件事很多人卡在第一步知道它能做代码补全但不知道一个补全建议从按键到弹出面板中间经历了什么。我最初也是这么想的直到自己用 TypeScript 写了一个能跑起来的补全插件才发现核心链路其实很短——注册一个CompletionItemProvider在回调里返回CompletionItem[]VSCode 就会把候选列表渲染出来。真正难的是让补全内容“有脑子”而不是写死几个console.log。这篇要交付的东西很具体一个可运行的 VSCode 补全插件原型用 TypeScript 写能识别当前行上下文并且通过 TaoToken 的统一 API 通道接入 AI 补全能力。适合谁看有前端或 Node.js 基础、想入门 VSCode 扩展开发的人已经在写插件、但补全逻辑还停留在静态列表、想接大模型的人以及想搞清楚package.json里contributes和activationEvents到底怎么配的人。我会按真实开发顺序走先搭环境建项目再写本地补全逻辑跑通然后接 TaoToken 的 API 做 AI 补全最后讲调试和常见报错。每一步都有可复制的配置和代码你跟着敲就能得到一个能按 F5 调试、输入触发字符会弹出建议的插件。搜索“VSCode 插件开发 TypeScript 代码补全”能找到不少零散片段但把本地补全和 AI 补全串成一条完整链路的并不多这篇就补这个缺口。先说清楚一个概念VSCode 的补全提供器是“被动触发”的。你输入一个字符VSCode 调用所有注册过的 provider每个 provider 返回自己的候选列表VSCode 合并去重后展示。所以插件的职责不是“监听键盘”而是“在合适的时机返回合适的候选”。理解这一点后面的代码就顺了。2. 环境搭建与插件项目初始化避开 yo code 的坑2.1 装对工具链VSCode 插件开发依赖 Node.js 和 npm版本建议 Node 18 LTS 以上太老的版本在装types/vscode时会有类型不兼容。先确认环境node -v npm -v然后装 Yeoman 和 VSCode 官方生成器npm install -g yo generator-code这两个包一个是脚手架框架一个是 VSCode 官方模板。装完后执行yo code交互式菜单里选New Extension (TypeScript)插件名填smart-completer标识符会自动生成描述随便写是否初始化 Git 仓库按需选。生成完进入目录cd smart-completer npm install2.2 生成的项目结构长什么样smart-completer/ ├── src/ │ └── extension.ts // 插件入口activate/deactivate ├── package.json // 插件清单contributes 和 activationEvents 都在这 ├── tsconfig.json // TypeScript 编译配置 └── .vscode/ └── launch.json // F5 调试配置extension.ts里默认有一个activate函数注册了一条Hello World命令。我们要做的是把补全提供器注册进去。先别急着删保留命令注册后面调试时还能用命令面板验证插件是否激活。2.3 package.json 的关键字段这是最容易踩坑的地方。VSCode 靠package.json里的engines.vscode判断插件兼容的编辑器版本靠activationEvents决定什么时候加载插件。默认生成的是{ engines: { vscode: ^1.85.0 }, activationEvents: [], contributes: { commands: [ { command: smart-completer.helloWorld, title: Hello World } ] } }activationEvents为空数组时插件只会在命令被调用时激活。但补全提供器需要在用户打字时就生效所以要么加onLanguage:javascript要么用*不推荐启动就加载会拖慢编辑器。我建议按语言精确激活{ activationEvents: [ onLanguage:javascript, onLanguage:typescript ] }这样只有打开 JS/TS 文件时插件才加载启动开销小。改完package.json记得重启调试窗口否则激活事件不生效。3. 可复制的补全配置从静态列表到上下文感知3.1 注册补全提供器在src/extension.ts里把activate改成注册补全提供器import * as vscode from vscode; import { Completer } from ./completer; export function activate(context: vscode.ExtensionContext) { const provider vscode.languages.registerCompletionItemProvider( [javascript, typescript], new Completer(), . // 触发字符输入 . 时立即触发 ); context.subscriptions.push(provider); } export function deactivate() {}registerCompletionItemProvider第一个参数是语言选择器第二个是 provider 实例第三个是触发字符列表。触发字符的意思是用户输入这个字符时VSCode 会立刻调用 provider不用等用户继续打字。不传触发字符的话默认在用户输入任意字符后延迟触发。3.2 写补全逻辑新建src/completer.tsimport * as vscode from vscode; export class Completer implements vscode.CompletionItemProvider { provideCompletionItems( document: vscode.TextDocument, position: vscode.Position, token: vscode.CancellationToken ): vscode.ProviderResultvscode.CompletionItem[] { const linePrefix document .lineAt(position) .text.substring(0, position.character); const completions: vscode.CompletionItem[] []; if (linePrefix.includes(console)) { completions.push( this.createCompletion(log, console.log($1), 输出日志), this.createCompletion(error, console.error($1), 输出错误), this.createCompletion(warn, console.warn($1), 输出警告) ); } if (/function\s\w\(/.test(linePrefix)) { completions.push(this.createCompletion(return, return $1, 函数返回)); } return completions; } private createCompletion( label: string, insertText: string, desc: string ): vscode.CompletionItem { const item new vscode.CompletionItem( label, vscode.CompletionItemKind.Method ); item.insertText new vscode.SnippetString(insertText); item.documentation new vscode.MarkdownString(desc); return item; } }这里用SnippetString而不是普通字符串是为了支持${1}这种占位符用户按 Tab 可以跳转。CompletionItemKind.Method决定图标样式VSCode 会根据 kind 显示不同的图标。3.3 上下文感知根据变量类型给建议静态列表只能应付固定场景。真正的补全神器要能读当前文档的上下文。比如检测到用户输入了.length就提示字符串方法const wordRange document.getWordRangeAtPosition(position); const currentWord wordRange ? document.getText(wordRange) : ; if (currentWord.endsWith(.length)) { completions.push( this.createCompletion(substring, substring($1, $2), 截取字符串), this.createCompletion(toUpperCase, toUpperCase(), 转大写) ); }getWordRangeAtPosition拿到光标所在单词的范围getText取出文本。这个模式可以扩展成检测变量声明、函数参数、导入语句等。不过纯静态规则写多了会变成 if-else 地狱这时候就该上 AI 了。3.4 接入 TaoToken 的配置片段TaoToken 提供统一的 API 通道一个 Key 可以调多个模型。接入前先在官网注册拿到 Key然后配置到插件里。我建议把配置放在 VSCode 的 settings 里而不是硬编码在package.json的contributes.configuration里加{ contributes: { configuration: { title: Smart Completer, properties: { smartCompleter.apiKey: { type: string, default: , description: TaoToken API Key }, smartCompleter.baseUrl: { type: string, default: https://taotoken.net/api, description: TaoToken API 地址 }, smartCompleter.model: { type: string, default: claude-3-5-sonnet, description: 补全使用的模型 ID } } } } }然后在代码里读配置const config vscode.workspace.getConfiguration(smartCompleter); const apiKey config.getstring(apiKey); const baseUrl config.getstring(baseUrl); const model config.getstring(model);这样用户可以在 VSCode 设置界面里填 Key不用改代码。三件套——Base URL、Key、Model ID——缺一不可后面调 API 时都要用到。4. 验证请求让 AI 补全真正跑起来4.1 发一个补全请求在completer.ts里加一个异步方法把当前行前缀发给 TaoTokenprivate async fetchAICompletion( linePrefix: string, apiKey: string, baseUrl: string, model: string ): Promisestring[] { const response await fetch(${baseUrl}/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${apiKey} }, body: JSON.stringify({ model, messages: [ { role: system, content: 你是一个代码补全引擎只返回补全后的代码片段不要解释。 }, { role: user, content: linePrefix } ], max_tokens: 64, temperature: 0.2 }) }); if (!response.ok) { throw new Error(API 请求失败: ${response.status}); } const data await response.json(); const text data.choices?.[0]?.message?.content ?? ; return text.split(\n).filter((l: string) l.trim()); }注意provideCompletionItems是同步返回ProviderResult但我们可以返回 Promise。VSCode 支持异步 provider只是会有延迟。为了不阻塞用户输入建议加防抖用户停止输入 300ms 后再发请求。4.2 把 AI 结果转成补全项if (apiKey linePrefix.trim().length 3) { try { const suggestions await this.fetchAICompletion( linePrefix, apiKey, baseUrl, model ); for (const s of suggestions) { const item new vscode.CompletionItem( s.trim(), vscode.CompletionItemKind.AI ); item.insertText s.trim(); item.detail AI 补全; completions.push(item); } } catch (e) { console.error(AI 补全失败, e); } }CompletionItemKind.AI是 VSCode 专门为 AI 补全预留的类型图标和普通方法区分开。4.3 本地调试步骤按 F5 会启动一个“扩展开发宿主”窗口这是一个独立的 VSCode 实例加载了你的插件。在新窗口里新建一个.js文件输入console.应该能看到log、error、warn三个建议。如果配了 API Key输入一段有意义的代码前缀等 300ms 左右会看到 AI 补全项。调试时可以在provideCompletionItems里打断点看linePrefix和position的值。launch.json默认已经配好了不用改。4.4 成功结果长什么样输入console.触发本地补全弹出log/error/warn输入const arr [1,2,3]; arr.触发 AI 补全返回map、filter、reduce等候选。每个候选右侧显示AI 补全标签选中后插入代码。整个过程不需要离开编辑器也不需要手动复制粘贴。5. 常见报错排查401、local proxy failed 与 reading choices5.1 401 Unauthorized最常见。原因通常是 Key 没填、填错或者Authorization头格式不对。检查三点Bearer后面有没有空格Key 是不是从 TaoToken 控制台复制的完整字符串baseUrl是不是https://taotoken.net/api末尾不要多加/v1因为代码里已经拼了/v1/chat/completions。如果确认 Key 没问题还是 401去控制台看 Key 是否被禁用或额度耗尽。5.2 local proxy failed这个报错通常出现在网络层意思是请求没发出去。先确认baseUrl拼写正确没有多余斜杠。然后检查fetch是否被 VSCode 的扩展宿主环境限制——扩展宿主默认允许网络请求但如果你的package.json里没声明capabilities某些企业环境会拦截。加一行{ capabilities: { virtualWorkspaces: false, untrustedWorkspaces: { supported: true } } }另外fetch在 Node 18 以下不可用如果报fetch is not defined升级 Node 或改用https模块。5.3 reading choices 报错Cannot read properties of undefined (reading choices)说明response.json()返回的结构里没有choices。可能是 API 返回了错误对象比如{error: {message: ...}}。在解析前先判断const data await response.json(); if (!data.choices) { console.error(API 返回异常, JSON.stringify(data)); return []; }常见原因是模型 ID 写错TaoToken 返回了模型不存在的错误。去控制台确认模型 ID 拼写比如claude-3-5-sonnet不要写成claude-3.5-sonnet。5.4 OAuth 相关报错如果你在插件里用了需要 OAuth 的第三方服务可能会遇到OAuth callback failed。VSCode 插件做 OAuth 需要用vscode.env.openExternal打开浏览器再通过vscode.window.registerUriHandler接收回调。但 TaoToken 用的是 API Key 认证不涉及 OAuth所以这个报错一般不会出现在我们的链路里。如果出现了检查是不是误引入了其他认证库。5.5 补全不触发按 F5 后输入console.没反应先看“扩展开发宿主”窗口的开发者工具帮助 → 切换开发人员工具Console 里有没有报错。常见原因是activationEvents没配onLanguage:javascript或者registerCompletionItemProvider的语言选择器写成了*但插件没激活。改完package.json必须重启调试窗口。6. 继续往下走把补全插件用起来到这里你已经有了一个能跑的插件本地规则补全 TaoToken AI 补全按 F5 就能调试。接下来可以做的方向有几个。一是加缓存同样的linePrefix不要重复请求用一个Map存最近的结果减少 API 调用。二是加防抖用户连续输入时取消上一次请求用AbortController实现。三是把补全范围从 JS/TS 扩展到 Python、Go改activationEvents和语言选择器就行。如果你想把 AI 补全做得更稳建议在 TaoToken 控制台里单独建一个 Key 给插件用方便监控调用量和排查问题。模型 ID 可以按场景切换写业务代码用通用模型写算法题用推理模型。配置都在 VSCode 设置里改完即时生效不用重启。调试过程中如果遇到 API 层面的问题先去接入文档对照请求格式再用模型对话页面手动发一条同样的请求确认是插件代码问题还是 API 配置问题。这个二分法能省很多时间。