vscode-extension-guide

VS Code 扩展指南

创建、开发和发布 VS Code 扩展。

对于带有管理界面的扩展，默认使用专用的活动栏图标和侧边栏，除非明确选择了其他入口。仅有 Marketplace icon 并不会创建此导航；请使用下方的 TreeView 参考。

面向用户的扩展应在主侧边栏或管理界面中提供标注清晰的错误报告／功能请求入口，并提供命令面板备用入口；仅提供 README 或 Marketplace 链接并不足够。在打开固定的反馈目的地之前，预览最少且非敏感的元数据；由用户自行提交，绝不自动附加提示词、原始日志、机密信息或私有路径。

适用场景

• VS Code 扩展、扩展开发、vscode 插件
• 从零开始创建 VS Code 扩展
• 为扩展添加命令、键绑定或设置
• 发布到 VS Code Marketplace

快速开始

# Scaffold new extension (recommended)
npm install -g yo generator-code
yo code

# Or minimal manual setup
mkdir my-extension && cd my-extension
npm init -y && npm install -D typescript @types/vscode

项目结构

my-extension/
├── package.json          # Extension manifest
├── src/extension.ts      # Entry point
├── out/                  # Compiled JS (gitignore)
├── artifacts/vsix/       # Keep local VSIX archives out of the repo root
├── images/icon.png       # 128x128 PNG for Marketplace
└── .vscodeignore         # Exclude files from VSIX

构建与打包

npm run compile      # Build once
npm run watch        # Watch mode (F5 to launch debug)
mkdir -p artifacts/vsix
npx @vscode/vsce package --out artifacts/vsix/my-extension-1.0.0.vsix

在 PowerShell 中，将 mkdir -p artifacts/vsix 替换为 New-Item -ItemType Directory -Force -Path 'artifacts\vsix'；其他构建／打包命令保持不变。根据执行环境选择 Shell 语法，而非 Agent 宿主环境。

将本地 .vsix 归档文件保存在 artifacts/vsix/ 下，而非仓库根目录，并定期清理旧的本地构建文件，避免发布产物不断堆积。

完成标准

• 打包后的 VSIX 可在隔离配置文件中安装并激活；变更后的面向用户集成可在其中完成实际工作流
• 主侧边栏入口和命令正常工作；VSIX 中包含所引用的图标
• 包大小 < 5MB（使用 .vscodeignore）
• README 链接和反馈界面可到达预期的支持目的地；使用合成数据验证从界面到表单的路径，但不要提交
• 本地 VSIX 产物存放在仓库根目录之外，并定期清理

快速故障排查

症状	解决方法
扩展未加载	检查 main/engines.vscode；已贡献的命令／视图会隐式激活（1.74+），仅对其他触发条件添加 activationEvents
找不到命令	确保 package.json/code 中的命令 ID 一致
快捷键不起作用	移除 when 子句，检查冲突

参考索引

主题	参考
AI 自定义	references/ai-customization.md
代码审查提示词	references/code-review-prompts.md
代码示例	references/ai-customization.md and references/webview.md
TreeView	references/treeview.md
Webview	references/webview.md
测试	references/testing.md
发布	references/publishing.md
故障排除	references/troubleshooting.md
通知	references/notification-normalization.md

最佳实践

Extension Host 边界

• 对于运行在 Extension Host 上的 scanner / provider / TreeView，如果能实现相同功能，应优先使用 VS Code API，而不是 Node 专有的 path / Buffer / 原始 fs。这样更容易避免 Problems 和实际构建环境之间的差异。
• 对于随自己的扩展一起打包的资源，应通过 context.extensionUri 和 vscode.Uri.joinPath 等 extension context 来解析，而不是猜测用户主目录或 VS Code 的安装路径。
• 如果需要读取随其他已安装扩展一起打包的资源，也应优先查看 resources/agents|skills|prompts|instructions|hooks|mcp 等已知 root，以及 manifest 中的 chatAgents / chatPromptFiles 声明。将其视为与 built-in resource 不同的只读资源，不要混入删除或重新安装流程。
• 不要将 Runtime 诊断日志零散地写入 console.log，应集中到基于 Output Channel 的 logger。还应通过 command / notification / README 中的某种方式，让用户能够打开日志。
• 不要在 Extension Host 线程中同步执行大型输入的解析或汇总。将有上限的 bytes 传递给 node:worker_threads，并在 cancel / opt-out 时执行 await worker.terminate() 和移除 listener；只有 generation ID 匹配的结果才能更新 cache / UI。
• 只传递专用的非 SharedArrayBuffer；传递后不要再使用发送端的 view（同一 backing store 的所有 view 都会 detach）。Buffer 可能会共享 pool，因此对于带 offset 的 view 或所有权不明确的 buffer，应只复制所需范围到另一个 buffer 后再传递。
• 不要直接缓存或显示从 worker 或其他进程接收的结果。使用 Reflect.ownKeys 检查允许的键，使用 Object.hasOwn 确认必需键存在（Object.keys 会漏掉不可枚举的 own property，而 in 或直接读取 property 会放行继承值）。
• 不要将异常的 Error.name 或 FileSystemError.code 原样输出到日志 / UI。将其规范化为已知 code 的 allowlist，未知值则统一映射到一个通用 code。这样可避免 path 或 token 混入名称。
• 对于从 cache 或共享文件（例如由其他扩展写入的 index）读取、用于显示的值，应在使用处检查类型并限制长度。非字符串会导致 replace 等操作抛出异常。规范化函数应保持幂等（截断后再 trim），并先编写可复现的失败测试，再进行修复。

Manifest / 文档 / 本地化

• 更改 package.json 中的 commands、views、configuration、menus 时，应同时检查代码中的 command ID / setting key。
• 对 Marketplace 展示内容或设置说明进行本地化的扩展，应在同一变更中更新 package.nls.json 和目标语言的 package.nls.*.json。
• 在 markdownDescription 中使用原生设置引用，例如 `#editor.wordWrap#`，而不要使用 [label](#editor.wordWrap#)：后者可能会在 Settings 的 @id: 筛选器中留下尾随井号。检查每种语言的语法，并验证解析后的目标。
• 更改设置顺序或说明时，应一并检查 README 中的设置表、manifest 一致性测试，以及是否需要更新发布说明。

语言模型工具

• 扩展提供的 LM 工具需要明确的 modelDescription 意图短语。优先使用 Use when the user asks to ...，并配合自然语言动词描述创建、更新、删除和切换路径；同时添加清单／文档检查，防止后续措辞变更悄然削弱 Agent 模式下的工具选择。
• 从 VS Code Chat 进行配置时，如果不需要外部客户端，优先使用原生 LM 工具；不要将它们称为外部 MCP 服务。与 GUI 共享经过验证的领域操作，只公开必要的操作，并使用明确的启用／禁用值，而不要使用对重试敏感的切换操作。
• 保持 prepareInvocation 无副作用，并针对变更或敏感信息披露请求确认。确认后，在加锁写入操作中重新验证输入、取消状态、信任状态和查询到的修订版本。宿主的审批界面／策略仍然适用；自定义确认文本不能绕过这些要求。绝不通过工具参数接收机密值，也不要默默扩大执行权限。
• 对查询结果分页，默认省略提示词、环境和原始输出负载。敏感详情的获取必须明确，并在披露前请求确认；说明哪些元数据会发送给模型，并将存储的字符串视为数据，而非指令。
• 从共享操作返回带类型的结果；捕获错误后不返回任何内容的 GUI 处理程序，无法证明工具已成功。若仅展示过程失败，应保留已提交的 ID／成功状态，返回经过清理的警告，并告知调用方应进行查询，而不是重复执行变更。配置已保存并不代表工作已执行。
• 绝不要仅凭名称选择工具目标：应根据精确名称和搜索／列表结果显示的 ID（例如来源和路径）进行解析；若有多个匹配项或名称不完整，应返回候选项并且不做任何更改。Schema 中的 enum 值在运行时不会强制执行，因此遇到无法识别的值时必须停止调用，而不是扩大筛选范围。若目标位置已存在文件，安装操作必须拒绝执行，除非显式传入覆盖标志；随后还要验证安装程序报告的目标位置上的文件。
• 发布包含 LM 工具的扩展前，应检查打包后的 VSIX，而不是仅信任源文件：确认 extension/package.json 中的版本符合预期，contributes.languageModelTools 数量符合预期，并且不包含 src/、测试负载或 sourcemaps，除非有意将其打包。

生成的章节

• 将由 START / END 标记包围的生成章节视为唯一的 SSOT。
• 如果发现重复的标记对，应合并内容并将标记对恢复为一个，而不是保留两个并继续追加。

命名一致性

发布前统一包名、设置键和命令名：

项目	示例
包名	copilot-scheduler
设置键	copilotScheduler.enabled
命令 ID	copilotScheduler.createTask
视图 ID	copilotSchedulerTasks

通知集中管理

将通知统一交由通用 helper 处理，并在 runtime 中将设置值规范化为已知的枚举值。有关重复抑制、与日志分离、操作、安全性以及启动时重复失败的单次通知设计，请参阅 Notification Normalization。