1. 从零认识 Activity Bar它到底是什么、能做什么如果你每天都在用 VSCode左侧那条竖着的图标栏一定不陌生——资源管理器、搜索、源代码管理、运行调试、扩展这些图标都挂在同一个区域这个区域在 VSCode 里叫Activity Bar。很多开发者第一次做插件时最想实现的效果就是在这条栏里加一个自己的图标点开后在左侧弹出专属侧边栏里面放自己的功能入口。这件事听起来简单但真正动手时会卡在几个地方package.json里contributes到底怎么写、viewsContainers和views的关系是什么、activationEvents要不要手动声明、图标资源放哪、为什么注册完侧边栏不显示。我试过第一次做的时候图标死活出不来排查半天发现是id和views里的引用对不上。这篇内容面向需要在左侧侧边栏添加功能选项的开发者目标是一次跑通自定义 bar 的注册与显示。我会给出可直接复制的package.json视图容器与菜单贡献点配置、activationEvents骨架并顺带给出一个统一 Key/API 通道在插件配置中的接入示例方便你后续把 AI 能力接进自己的插件里。整个流程不需要你懂太多底层原理跟着改文件、按 F5 调试就能看到效果。先明确一个概念Activity Bar 上的每一个图标对应一个视图容器View Container点开图标后左侧展开的面板里面装的每一个区块叫视图View。一个容器可以放多个视图视图里可以再挂欢迎页、树形列表、Webview。理解这层包含关系后面写配置就不会乱。2. 前置准备TaoToken 统一 Key 与 API 通道在动手写插件之前先把后面要用到的 API 通道准备好。很多插件做到一半会想加个「AI 对话」或「代码解释」入口如果每个功能都单独去申请一家模型的 Key配置会非常散。这里用 TaoToken 做一个统一入口一个 Key 走多家模型插件里只维护一份配置就行。TaoToken 的定位是给开发者提供统一的模型调用通道官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。它的价值在于你不需要在插件里为每个模型厂商写一套鉴权逻辑统一用 OpenAI 兼容格式请求即可切换模型只改一个model字段。适合谁用适合正在做 VSCode 插件、想把 AI 能力嵌进侧边栏但不想被多家 Key 管理拖住的开发者。你需要准备的东西只有两样一个 TaoToken 的 API Key以及一个能跑起来的插件工程骨架。获取 Key 的路径是进入控制台创建具体入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建后到 API Keys 页面复制地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你后面要做长期编码类或 Agent 类插件可以了解下 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注意Key 不要硬编码进源码提交到仓库。插件里建议通过vscode.workspace.getConfiguration读取用户设置或者用 SecretStorage 存储后面第 3 节会给配置骨架。3. 可复制配置package.json 视图容器与菜单贡献点这一节是核心所有配置都写在插件根目录的package.json里。VSCode 通过contributes字段识别你要往界面里塞什么。下面这份配置可以直接抄改掉id、title、icon路径即可。3.1 声明视图容器 viewsContainersviewsContainers下的activitybar数组就是往 Activity Bar 加图标的地方。每个元素需要id、title、icon三个字段。{ contributes: { viewsContainers: { activitybar: [ { id: taotokenSidebar, title: TaoToken 工具箱, icon: resources/taotoken.svg } ] } } }id是唯一标识后面views里要靠它关联title是鼠标悬停时显示的提示文字icon是图标路径建议用 24x24 的 SVG单色填充VSCode 会自动适配主题色。图标文件放在工程根目录的resources文件夹下没有就新建一个。3.2 声明视图 views容器有了里面装什么由views决定。键名必须和上面viewsContainers里的id完全一致这是最容易写错的地方。{ contributes: { views: { taotokenSidebar: [ { id: taotokenWelcome, name: 快速开始, type: webview }, { id: taotokenModels, name: 模型列表, type: tree } ] } } }这里放了两个视图一个webview类型用来展示欢迎页或配置引导一个tree类型用来展示模型列表。type支持tree、webview等按需选。3.3 菜单贡献点与激活事件光有视图还不够通常还要在视图标题栏加个刷新按钮或者加右键菜单。这靠menus字段实现配合commands声明命令。{ contributes: { commands: [ { command: taotoken.refreshModels, title: 刷新模型列表, icon: $(refresh) } ], menus: { view/title: [ { command: taotoken.refreshModels, when: view taotokenModels, group: navigation } ] } }, activationEvents: [ onView:taotokenWelcome, onView:taotokenModels ] }view/title表示菜单出现在视图标题栏when条件限定只在taotokenModels这个视图上显示。activationEvents里用onView:声明当用户点开对应视图时才激活插件避免插件一启动就占用资源。较新的 VSCode 版本对onView有自动推断但显式写上更稳妥。3.4 插件配置项接入 TaoToken把 API 通道做成用户可配置项写在configuration里。这样用户在设置里填一次 Key插件全局可用。{ contributes: { configuration: { title: TaoToken 配置, properties: { taotoken.apiKey: { type: string, default: , description: TaoToken API Key在控制台创建后填入 }, taotoken.baseUrl: { type: string, default: https://taotoken.net/api, description: API 基址一般无需修改 }, taotoken.model: { type: string, default: gpt-4o-mini, description: 默认调用的模型名称 } } } } }读取时用vscode.workspace.getConfiguration(taotoken).get(apiKey)写入用update方法。这样插件里所有需要调模型的地方都从这一份配置取不用散落各处。4. 验证请求注册扩展、本地调试与成功结果配置写完了接下来要让它真正跑起来。这一节给出从注册到看到侧边栏的完整动作以及一个验证 API 通道是否通的请求示例。4.1 注册视图提供者package.json只是声明真正渲染内容要靠代码。在extension.ts的activate函数里注册。以 tree 视图为例import * as vscode from vscode; export function activate(context: vscode.ExtensionContext) { const modelProvider new ModelTreeProvider(); vscode.window.registerTreeDataProvider(taotokenModels, modelProvider); const refreshCmd vscode.commands.registerCommand(taotoken.refreshModels, () { modelProvider.refresh(); }); context.subscriptions.push(refreshCmd); } class ModelTreeProvider implements vscode.TreeDataProvidervscode.TreeItem { private _onDidChangeTreeData new vscode.EventEmittervoid(); readonly onDidChangeTreeData this._onDidChangeTreeData.event; refresh() { this._onDidChangeTreeData.fire(); } getTreeItem(element: vscode.TreeItem): vscode.TreeItem { return element; } getChildren(): vscode.TreeItem[] { const cfg vscode.workspace.getConfiguration(taotoken); const model cfg.getstring(model) || 未配置; return [new vscode.TreeItem(当前模型${model})]; } }registerTreeDataProvider的第一个参数必须和package.json里views的id一致否则视图是空的。4.2 本地调试动作按 F5 会启动一个「扩展开发宿主」窗口这是 VSCode 专门给插件调试用的独立实例。在新窗口里左侧 Activity Bar 应该能看到你配置的图标。点开后侧边栏展开里面显示「快速开始」和「模型列表」两个视图。点「模型列表」标题栏的刷新图标树内容会重新渲染。如果图标没出现先检查icon路径是否存在、SVG 是否合法如果图标出现但点开是空白检查views的键名和viewsContainers的id是否一致。4.3 验证 API 通道在插件里加一个命令用fetch请求 TaoToken 的接口确认 Key 和基址配置正确。Node 18 自带 fetchVSCode 插件环境可直接用。async function testApi() { const cfg vscode.workspace.getConfiguration(taotoken); const apiKey cfg.getstring(apiKey); const baseUrl cfg.getstring(baseUrl); const res await fetch(${baseUrl}/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${apiKey} }, body: JSON.stringify({ model: cfg.getstring(model), messages: [{ role: user, content: 回复 ok 两个字母即可 }] }) }); const data await res.json(); vscode.window.showInformationMessage(data.choices?.[0]?.message?.content || 无返回); }把这段挂到一个命令上在命令面板执行如果弹出模型返回的内容说明通道打通。想先在网页端确认模型可用可以到模型对话页面试一下入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。5. 本篇常见错排查做自定义 bar 时报错和「没反应」的情况集中在几个点这里按出现频率排一下。图标不显示最常见是 SVG 文件路径写错或者 SVG 里带了fill固定颜色导致在深色主题下看不见。建议 SVG 用currentColor作为填充色。另外图标尺寸建议 24x24过大过小都可能被裁切。侧边栏点开空白九成是views的键名和viewsContainers的id不一致。注意id是大小写敏感的taotokenSidebar和taotokensidebar会被当成两个东西。另一个可能是registerTreeDataProvider的 id 写错。命令找不到menus里引用的command必须在commands数组里声明过否则菜单项不渲染。同时when条件里的view xxx要和视图 id 对上。激活事件不触发如果用了onView:确认视图 id 拼写正确。老版本 VSCode 需要显式声明新版本虽然能推断但显式写不会出错。API 请求 401Key 没填或填错或者Authorization头格式不对必须是Bearer加空格再加 Key。如果返回 404检查baseUrl后面拼接的路径基址是https://taotoken.net/api完整路径是/v1/chat/completions。调试窗口改了代码不生效扩展开发宿主窗口不会热重载改完代码要在原窗口按 CtrlShiftF5 重启调试或者关掉宿主窗口重新 F5。提示排查时优先看「帮助 切换开发人员工具」里的 Console插件抛出的错误都会打在那里比猜快得多。6. 把入口接进你的工作流到这里一个带自定义 Activity Bar 入口的插件骨架就跑通了图标注册、侧边栏视图、标题栏菜单、配置项、API 验证整条链路都覆盖了。接下来你可以把「模型列表」换成真实的模型拉取把「快速开始」的 webview 做成配置引导页让用户填完 Key 直接测试。如果你打算把这个插件往编码辅助方向做比如在侧边栏里放代码解释、生成注释、批量重构入口那调用量会比偶尔测一下高很多这时候可以看下 Coding Plan 的额度方案入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入细节和参数说明在接入文档里地址是 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 遇到字段对不上时翻一下比试错快。最后留一个实用习惯把taotoken.apiKey用 SecretStorage 存而不是明文写在 settings.json 里。读取时先查 SecretStorage没有再回退到配置项。这样即使用户把 settings.json 同步到云端Key 也不会跟着泄露。插件发布前记得在README里写清楚 Key 的获取路径减少用户第一次使用时的困惑。