VS Code 扩展开发 — 术语表

按概念分组，而非按拼音。组内按依赖顺序排列——先读上面的，才能理解下面的。持续随课程更新。

一、核心对象：VS Code 递给你的东西

这些是你在 extension.ts 中实际创建、接收、操作的 VS Code 对象。它们是你写每一行代码时直接打交道的"实体"。

术语一句话解释首次出现
ExtensionContext VS Code 在调用 activate() 时传入的"工具箱"对象。它把扩展需要的所有系统服务打包在一起：资源管理（subscriptions）、持久化存储（globalState / workspaceState / secrets）、安装路径（extensionPath）。

参见 Lesson 0002 §1

 Lesson 0002
context.subscriptions ExtensionContext 上的 Disposable[] 数组——"自动清理清单"。你在 activate() 中把命令注册、事件监听器等 push 进去，VS Code 在停用扩展时逐一调用它们的 dispose()。push 是手动的——VS Code 刻意不自动帮你做，这样你才能选择把某个资源中途 dispose 还是随扩展一起消亡。

参见 Disposable、Lesson 0002 §1.1

 Lesson 0002
StatusBarItem VS Code 窗口底部状态栏上的一个可自定义条目。通过 vscode.window.createStatusBarItem(alignment, priority) 创建。属性包括 text（显示文字）、tooltip（悬停提示）、command（点击行为）、backgroundColor（背景色）等。修改属性即自动重绘——声明式 UI 模式。

参见 Lesson 0003、ThemeColor、Command

 Lesson 0003
ThemeColor VS Code 的语义化颜色引用，而非具体色值。new vscode.ThemeColor('statusBarItem.errorBackground') 在深色主题下解析为暗红，浅色主题下为浅红。类似 Android 的 ?attr/colorError。永远不要在 VS Code 扩展中硬编码 UI 颜色。

参见 Lesson 0003 §5

 Lesson 0003
Command VS Code 的行为调度单元。分两类：(1) 用户命令——在 package.json 的 contributes.commands 中声明，出现在命令面板（Ctrl+Shift+P），可绑定快捷键；(2) 内部命令——仅通过 registerCommand() 在代码中注册，作为 UI 组件的点击回调或程序间通信使用。claude-context-bar 的 hideSession 是内部命令。

参见 Lesson 0002 §2.1 callout

 Lesson 0002
Memento VS Code 的键值持久化存储接口。globalState 全局共享（所有工作区），workspaceState 每工作区独立。数据在 VS Code 重启后仍然存在。类比：扩展的"硬盘"。底层是 GoF 的 Memento 模式——不暴露内部结构，只暴露 save/restore。 Lesson 0002
SecretStorage VS Code 的安全存储接口，专门存放 API key、token 等敏感信息。底层调用操作系统的密钥管理（macOS Keychain / Windows Credential Store / Linux libsecret）。类比：扩展的"保险柜"，不是什么东西都塞这里，但密码必须放这里。 Lesson 0002
activationEvents package.json 中声明的一组触发条件，告诉 VS Code "什么时候加载我的扩展"。常见值：onStartupFinished（启动完成后）、onCommand:xxx（用户首次执行某命令时）。claude-context-bar 使用 onStartupFinished——它需要在状态栏中始终可见。

参见 Lesson 0001 §2.2

 Lesson 0001

二、资源管理：创建了就要清理

这组概念围绕一个核心问题：扩展创建的资源（命令、监听器、定时器、文件监听……）由谁、在什么时候、以什么方式销毁？VS Code 的答案全在这里。

概念一句话解释首次出现
Disposable VS Code 的统一清理合约：任何需要释放资源的东西，都实现一个 { dispose(): void } 接口。调用 dispose() 后对象释放所有持有的资源，此后不应再使用。VS Code API 中几乎所有 registerXxx() 和 onDidXxx() 方法都返回 Disposable。

参见 Dispose Pattern、Lesson 0002 §1.2

 Lesson 0002
Dispose Pattern 源自 .NET / RxJS 社区的编程原则：创建资源的人负责销毁它。registerCommand() 创建了命令注册，返回的 Disposable 就是"所有权转移凭证"。你可以：(1) push 到 subscriptions——委托 VS Code 在停用时清理；(2) 自己持有引用，在中途合适的时机调用 .dispose()。VS Code 不自动 push 不是因为"做不到"——而是把控制权交给你。

参见 Disposable、context.subscriptions、适配器模式

 Lesson 0002
生命周期 扩展从激活 → 运行 → 停用的完整过程。端点：activate()（出生——注册命令、创建 UI、设置监听）和 deactivate() / subscriptions dispose（死亡——清理所有资源）。生命周期管理是 VS Code 扩展编程中最容易出错的环节——创建了没清理 → 内存泄漏；销毁了还持有引用 → 崩溃。

参见 Lesson 0002 §4–5

 Lesson 0002
适配器模式 GoF 经典设计模式。在 VS Code 扩展中的标准用法：把非 VS Code 资源包装成符合 Disposable 契约的对象。例如 Node.js 的 fs.watch() 返回 FSWatcher（没有 dispose() 方法），包装成 { dispose: () => watcher.close() } 后就能 push 到 subscriptions，享受和 VS Code 资源相同的自动清理待遇。

参见 Lesson 0002 §3、Disposable

 Lesson 0002
标记-清除 一种两阶段算法：(1) 标记所有"活着"的对象；(2) 清除所有没被标记的。在 claude-context-bar 中，seenPaths 是标记阶段的产物——每次 refreshAllSessions() 遍历活跃会话时，把它们的 sessionFile 加入 Set（标记）。之后遍历 statusBarItems Map，不在 Set 中的条目被 dispose+delete（清除）。

参见 Lesson 0003 §5.3

 Lesson 0003

三、架构概念：理解系统怎么搭的

这些词不直接对应一个可以 import 的类或一个可以实例化的对象。它们描述的是系统的层次结构和设计哲学。

概念一句话解释首次出现
原语（Primitive） 系统提供的最小、不可再拆的基本操作/构件。你不能用更底层的 VS Code API 来实现 registerCommand()——它就是 VS Code 给你的"原子"。所有扩展的功能都是通过对这些原语进行组合来构建的。
类比：乐高基础砖块——可以搭出任何东西，但无法用更小的乐高零件造出这块砖。
这个词为什么让人困惑：它描述的是"这个东西在系统里的层级"而非"这个东西能做什么"。就像"原子"——它告诉你这是物质的最小单位，但不描述某个具体原子的样子。
本课程中的实例：StatusBarItem 是状态栏的 UI 原语、registerCommand() 是命令注册的原语、onDidChangeConfiguration() 是配置监听的原语、Disposable 是资源管理的原语合约。 		Lesson 0003
声明式 vs 命令式 声明式：你描述目标状态，系统负责达到它。例如 item.text = "72%"——你声明了 text 应该是 72%，VS Code 负责重绘。你不需要调用 item.render()。
命令式：你写清楚每一步怎么做。例如 fs.watch(path, callback)——你告诉 Node.js 精确的执行步骤。
VS Code 的 UI API 全部采用声明式：属性即 UI，修改即重绘。 		Lesson 0003
数据管线（Data Pipeline） 一种将原始数据经过多个串联步骤逐步加工成目标数据结构的架构模式。每一步只做一种转换：扫描 → 解码 → 解析 → 过滤 → 分组 → 编号 → 输出。优点：(1) 每一步职责单一，易于理解和测试；(2) 在尽量早的阶段丢弃不需要的数据，减少后续步骤的工作量。

参见 Lesson 0004 §2

 Lesson 0004

四、缩写速查

你在代码、日志和文档中会反复遇到的缩写。

缩写全称说明
SemVerSemantic Versioning语义化版本规范：major.minor.patch（如 1.74.0）
GoFGang of Four《设计模式》的四位作者，泛指书中 23 种经典模式
JSONLJSON Lines每行一个独立 JSON 对象的文本格式（Claude Code 会话文件格式）
mtimemodification time文件的最后修改时间戳。在 fs.statSync() 返回的 Stats 对象上以 .mtime 属性暴露。findActiveSessions 用它来判断会话是否仍在活跃
CIContinuous Integration持续集成——频繁将代码合并到主干，每次 push / PR 自动构建和测试，确保代码始终处于可工作状态
CDContinuous Delivery持续交付——CI 通过后代码自动进入可发布状态，但"发布"按钮由人按下（如打 tag 触发 publish）
CDContinuous Deployment持续部署——CI 通过后自动部署到生产环境，无需人工干预。Delivery 的更进一步
no-opno operation重复调用不会产生任何效果，也不会报错。例如对已关闭的 watcher 再次 .close()
← Lesson 0003：状态栏 UI 原语 📋 参考：VS Code 扩展 API 基础