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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api 。它的价值在于：你不需要在插件里为每个模型厂商写一套鉴权逻辑，统一用 OpenAI 兼容格式请求即可，切换模型只改一个model字段。
适合谁用？适合正在做 VSCode 插件、想把 AI 能力嵌进侧边栏，但不想被多家 Key 管理拖住的开发者。你需要准备的东西只有两样：一个 TaoToken 的 API Key，以及一个能跑起来的插件工程骨架。
获取 Key 的路径是进入控制台创建，具体入口在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，创建后到 API Keys 页面复制，地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。如果你后面要做长期编码类或 Agent 类插件，可以了解下 Coding Plan，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
注意：Key 不要硬编码进源码提交到仓库。插件里建议通过
vscode.workspace.getConfiguration读取用户设置，或者用 SecretStorage 存储，后面第 3 节会给配置骨架。
3. 可复制配置：package.json 视图容器与菜单贡献点
这一节是核心，所有配置都写在插件根目录的package.json里。VSCode 通过contributes字段识别你要往界面里塞什么。下面这份配置可以直接抄，改掉id、title、icon路径即可。
3.1 声明视图容器 viewsContainers
viewsContainers下的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.TreeDataProvider<vscode.TreeItem> { private _onDidChangeTreeData = new vscode.EventEmitter<void>(); 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.get<string>('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+ 自带 fetch，VSCode 插件环境可直接用。
async function testApi() { const cfg = vscode.workspace.getConfiguration('taotoken'); const apiKey = cfg.get<string>('apiKey'); const baseUrl = cfg.get<string>('baseUrl'); const res = await fetch(`${baseUrl}/v1/chat/completions`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiKey}` }, body: JSON.stringify({ model: cfg.get<string>('model'), messages: [{ role: 'user', content: '回复 ok 两个字母即可' }] }) }); const data = await res.json(); vscode.window.showInformationMessage(data.choices?.[0]?.message?.content || '无返回'); }把这段挂到一个命令上，在命令面板执行，如果弹出模型返回的内容，说明通道打通。想先在网页端确认模型可用，可以到模型对话页面试一下，入口在 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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 请求 401：Key 没填或填错，或者Authorization头格式不对，必须是Bearer加空格再加 Key。如果返回 404，检查baseUrl后面拼接的路径，基址是https://taotoken.net/api，完整路径是/v1/chat/completions。
调试窗口改了代码不生效：扩展开发宿主窗口不会热重载，改完代码要在原窗口按 Ctrl+Shift+F5 重启调试，或者关掉宿主窗口重新 F5。
提示：排查时优先看「帮助 > 切换开发人员工具」里的 Console，插件抛出的错误都会打在那里，比猜快得多。
6. 把入口接进你的工作流
到这里，一个带自定义 Activity Bar 入口的插件骨架就跑通了：图标注册、侧边栏视图、标题栏菜单、配置项、API 验证，整条链路都覆盖了。接下来你可以把「模型列表」换成真实的模型拉取，把「快速开始」的 webview 做成配置引导页，让用户填完 Key 直接测试。
如果你打算把这个插件往编码辅助方向做，比如在侧边栏里放代码解释、生成注释、批量重构入口，那调用量会比偶尔测一下高很多，这时候可以看下 Coding Plan 的额度方案，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。接入细节和参数说明在接入文档里，地址是 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，遇到字段对不上时翻一下比试错快。
最后留一个实用习惯：把taotoken.apiKey用 SecretStorage 存，而不是明文写在 settings.json 里。读取时先查 SecretStorage，没有再回退到配置项。这样即使用户把 settings.json 同步到云端，Key 也不会跟着泄露。插件发布前记得在README里写清楚 Key 的获取路径，减少用户第一次使用时的困惑。
