1. 从零写一个 VS Code 插件，卡在 extension.ts 注册这一步
VS Code 插件系统开发流程里，最容易让人卡住的不是写业务逻辑，而是 extension.ts 注册这一环。你明明在 package.json 里声明了命令，按 F5 启动调试，命令面板里却搜不到；或者命令能搜到，点下去毫无反应，控制台也不报错。这类问题的根因，九成出在「声明」和「注册」没有对上。
VS Code 插件本质是一个 Node.js 模块，package.json 里的 contributes 只是给宿主看的静态元数据，相当于菜单上印了菜名，但后厨还没人接单。extension.ts 里的 activate 函数才是后厨开工的地方，registerCommand 就是把菜名和厨师绑定的动作。只有声明没有注册，命令就是空壳；只有注册没有声明，命令面板里根本不会出现。
这篇面向刚接触 VS Code 插件开发的同学，也适合写过几个插件但注册链路总是理不清的人。我会用一个最小可运行的 hello 命令插件，把 extension.ts 骨架、package.json 配置、F5 调试验证三步串起来，每一步都给可直接复制的代码。读完你能独立跑通「声明 → 注册 → 触发 → 看到结果」的完整闭环，并且知道每个环节出错时该去哪里找。
2. 前置准备：环境、脚手架与 TaoToken 接入
动手前先把工具链备齐。你需要 Node.js 18 以上、VS Code 1.85 以上，以及 Yeoman 脚手架。命令行执行下面三条，生成一个 TypeScript 插件模板：
npm install -g yo generator-code yo code # 交互式选择：New Extension (TypeScript) # 插件名填 vscode-hello-register生成后目录里最关键的两个文件是src/extension.ts和package.json，后面所有改动都围绕它们。
如果你在插件里要调用大模型能力，比如做一个「选中代码让模型解释」的命令，就需要一个稳定的 API 入口。我这边习惯用 TaoToken 做模型调用层，它的接口兼容 OpenAI 风格，插件里用 fetch 或 openai SDK 都能直接对接。先去控制台建一个 Key：
控制台入口：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
创建完到 API Keys 页面复制密钥，注意别提交到 Git：
Key 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
接口基址用https://taotoken.net/api，这个地址不带任何查询参数，直接写进插件配置即可。想先确认模型通不通，可以在模型对话页手动发一条消息试试：
模型对话：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
如果你打算长期做编码类插件、甚至接 Agent 工作流，Coding Plan 会比按次调用更省心：
Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
接入细节和参数说明都在文档里，遇到 401/404 先翻这里：
接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
3. 可复制配置：package.json 声明与 extension.ts 注册
3.1 package.json 里声明命令
打开 package.json，找到 contributes 字段，加入 commands 数组。命令 ID 建议用「插件名.动作」的格式，避免和其他插件撞车：
{ "contributes": { "commands": [ { "command": "vscode-hello-register.hello", "title": "Hello: 打个招呼", "category": "Hello" }, { "command": "vscode-hello-register.explainSelection", "title": "Hello: 解释选中代码", "category": "Hello" } ], "menus": { "editor/context": [ { "command": "vscode-hello-register.explainSelection", "when": "editorHasSelection", "group": "navigation" } ] } }, "activationEvents": [ "onCommand:vscode-hello-register.hello", "onCommand:vscode-hello-register.explainSelection" ] }这里有两个关键点。第一，command字段的值必须和后面 registerCommand 的第一个参数逐字符一致，大小写、连字符都不能差。第二，activationEvents 里用onCommand:前缀声明激活时机，意思是「用户执行这个命令时才加载插件」，比*全量激活更省资源。
3.2 extension.ts 骨架：activate 与 registerCommand
把src/extension.ts整个替换成下面这份骨架。它包含两个命令的注册、一个 Disposable 收集模式，以及一个调用模型的辅助函数：
import * as vscode from 'vscode'; // 模型接口配置，Key 建议从环境变量或 SecretStorage 读取 const API_BASE = 'https://taotoken.net/api'; const MODEL = 'gpt-4o-mini'; export function activate(context: vscode.ExtensionContext) { console.log('插件已激活：vscode-hello-register'); // 命令一：最简单的打招呼 const helloDisposable = vscode.commands.registerCommand( 'vscode-hello-register.hello', (uri?: vscode.Uri) => { const where = uri?.fsPath ?? '命令面板'; vscode.window.showInformationMessage(`Hello，来自 ${where}`); } ); // 命令二：读取选中代码并请求模型解释 const explainDisposable = vscode.commands.registerCommand( 'vscode-hello-register.explainSelection', async () => { const editor = vscode.window.activeTextEditor; if (!editor) { vscode.window.showWarningMessage('没有打开的编辑器'); return; } const selection = editor.document.getText(editor.selection); if (!selection) { vscode.window.showWarningMessage('请先选中一段代码'); return; } await vscode.window.withProgress( { location: vscode.ProgressLocation.Notification, title: '正在请求模型...' }, async () => { try { const result = await explainCode(selection); const doc = await vscode.workspace.openTextDocument({ content: result, language: 'markdown' }); await vscode.window.showTextDocument(doc, { preview: true }); } catch (err: any) { vscode.window.showErrorMessage(`请求失败：${err.message}`); } } ); } ); // 统一收集，插件停用时自动释放 context.subscriptions.push(helloDisposable, explainDisposable); } async function explainCode(code: string): Promise<string> { const apiKey = process.env.TAOTOKEN_API_KEY ?? ''; if (!apiKey) { throw new Error('未设置 TAOTOKEN_API_KEY 环境变量'); } const resp = await fetch(`${API_BASE}/chat/completions`, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` }, body: JSON.stringify({ model: MODEL, messages: [ { role: 'system', content: '你是代码讲解助手，用简洁中文解释代码作用。' }, { role: 'user', content: code } ] }) }); if (!resp.ok) { throw new Error(`HTTP ${resp.status}`); } const data: any = await resp.json(); return data.choices?.[0]?.message?.content ?? '模型未返回内容'; } export function deactivate() { console.log('插件已停用'); }这份骨架里有三个值得记住的设计。第一，每个 registerCommand 都返回一个 Disposable，全部 push 进context.subscriptions，插件被禁用时 VS Code 会自动调用它们的 dispose，不需要你手写清理。第二，命令回调可以是 async，VS Code 会等待 Promise 完成，配合 withProgress 就能显示进度条。第三，模型 Key 从环境变量读，避免硬编码进源码。
3.3 注册时机与生命周期
注册必须发生在 activate 内部，不能写在模块顶层。原因是模块顶层代码在插件加载时就执行，而那时 ExtensionContext 还没准备好，注册会失败或产生游离的 Disposable。activate 由 VS Code 在激活条件满足时调用一次，所有 register* 调用集中在这里，是官方推荐的做法。
4. 验证请求：F5 调试确认命令生效
配置写完，按 F5 启动扩展开发宿主。VS Code 会新开一个窗口，标题栏带[扩展开发宿主]字样，插件就装在这个临时窗口里。
第一步，打开命令面板（Ctrl+Shift+P / Cmd+Shift+P），输入Hello，你应该能看到两条命令：「Hello: 打个招呼」和「Hello: 解释选中代码」。能看到说明 package.json 的 contributes 声明生效了。
第二步，执行「Hello: 打个招呼」。右下角弹出Hello，来自 命令面板的通知，说明 registerCommand 注册成功、回调被正确触发。如果命令面板里能看到但点了没反应，问题一定在 registerCommand 这一侧。
第三步，验证带参数的场景。在资源管理器里右键任意文件，菜单里会出现「Hello: 解释选中代码」（因为我们配了 editor/context 菜单，实际应选中编辑器内文本）。更直接的验证方式：在编辑器里选中几行代码，右键执行该命令，会弹出进度通知，随后打开一个 Markdown 预览标签页显示模型返回的解释。
第四步，看调试控制台。原窗口的「调试控制台」会打印插件已激活：vscode-hello-register，这是 activate 被调用的证据。如果这行没打印，说明插件压根没激活，回去检查 activationEvents。
想单独验证模型接口是否通，可以脱离插件，直接用 curl 打一发：
curl https://taotoken.net/api/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "用一句话说明什么是 VS Code 插件"}] }'返回 JSON 里choices[0].message.content有内容，就说明 Key 和网络都没问题，插件里的失败就只可能是代码逻辑问题。
5. 本篇常见错排查
5.1 命令面板搜不到命令
先确认 package.json 的 contributes.commands 里有没有这条，再确认 activationEvents 是否包含onCommand:对应ID。两者缺一，命令都不会出现在面板里。改完 package.json 必须重启扩展开发宿主，热重载不一定生效。
5.2 命令能搜到，点击无反应
九成是 registerCommand 的 ID 和 package.json 不一致。VS Code 对命令 ID 是精确匹配，vscode-hello-register.hello和vscode-hello-register.Hello是两个命令。把两处 ID 复制出来逐字符比对，或者干脆用常量统一管理：
const CMD_HELLO = 'vscode-hello-register.hello'; // package.json 里也写同一个字符串5.3 报「command not found」
这个报错通常出现在你用vscode.commands.executeCommand手动调用一个还没注册的命令时。检查注册代码是否真的执行到了——如果注册被包在某个 if 分支或异步回调里，可能没跑到。把所有 registerCommand 放在 activate 的同步流程最前面，最稳妥。
5.4 插件禁用后命令残留
如果你没把 Disposable 加进context.subscriptions，插件停用后命令处理器还挂在宿主里，再次触发会报错。养成习惯：每个 register* 的返回值立刻 push 进 subscriptions，不要攒着最后一起加。
5.5 模型请求 401 或超时
401 一般是 Key 没读到或写错了，检查TAOTOKEN_API_KEY环境变量是否在启动扩展宿主前就设好。超时则看网络和基址，确认用的是https://taotoken.net/api，路径拼成/chat/completions。如果插件里请求一直挂起，先在终端用上面的 curl 验证接口本身是否可达，把插件问题和接口问题分开定位。
5.6 改了代码但行为没变
扩展开发宿主不会自动重载插件代码。改完 TypeScript 后，在调试窗口按 Ctrl+R 重启宿主，或者直接停掉调试再按 F5。watch 任务只负责编译，不负责重载。
6. 下一步：把注册链路用起来
跑通 hello 命令只是起点。同一套注册模式可以平移到更复杂的场景：用registerWebviewViewProvider注册侧边栏自定义视图，用registerCompletionItemProvider做代码补全，用registerTreeDataProvider做资源树。它们的共同点是——在 package.json 里声明贡献点，在 activate 里注册实现，返回值统一交给 subscriptions 管理。
如果你准备把模型能力做成插件里的常驻功能，比如代码解释、单元测试生成、提交信息撰写，建议把 Key 存进context.secrets而不是环境变量，再用 Coding Plan 承接高频调用，成本和稳定性都更好控制。注册链路本身不复杂，难的是记住「声明与注册必须成对出现」这条铁律，剩下的就是不断加命令、加视图、加 Provider 的体力活了。
