Chapter 58
用 VS Code 插件把团队规则放进编辑器
用 VS Code 插件把团队规则放进编辑器
你好，欢迎继续来到多平台开发这一章。
如果你每天都在 VS Code 里写代码，应该已经装过不少插件。代码补全、格式化、Git、容器、数据库和远程开发，很多原本需要切换到其他软件的操作，现在都能直接留在编辑器里完成。
企业自己做插件也是同一个思路：不是重新造一个编辑器，而是把项目模板、代码规范、安全检查、工单和发布流程放到开发者每天都打开的地方。
企业里的 VS Code 插件都在做什么
VS Code 插件并不只是代码补全。成熟产品经常把原本散落在网页、命令行和管理后台里的工作，搬到开发者正在编辑的文件旁边。
下面这些都是真实发布并持续使用的产品。它们解决的问题不同，但都没有要求开发者离开 VS Code 重新学习一套操作方式。
GitHub Pull Requests：把代码评审放回代码旁边
团队在 GitHub 上协作时，开发者通常要打开网页查看 Pull Request，再回到编辑器切换分支和修改代码。GitHub 的 Pull Requests and Issues 插件把这段流程接进了 VS Code。
安装以后，侧边栏会列出“等待我评审”“分配给我”和“我创建的”Pull Request。开发者可以检出对方的分支、查看修改文件、在差异代码旁评论、指定评审人，最后批准或合并。Issue 也能直接创建分支并进入开发状态。它同时支持 GitHub.com 和 GitHub Enterprise。
下面是 VS Code 官方文档展示的真实评审页面。左边是待评审 PR 和改动文件，右边是 PR 描述、评审人、负责人和讨论：
图片与功能说明来源：VS Code 官方 GitHub 协作指南。
这个产品没有在编辑器里重做一个完整 GitHub。它只把“当前 PR、当前分支、当前文件和当前行”连接起来，让评审意见紧挨着代码出现。
Dev Containers：把开发环境也放进项目
另一个常见问题是环境不一致：老同事的项目能启动，新同事却要花一天安装语言、数据库客户端和系统依赖；Windows、macOS 和 Linux 上的版本还可能不同。
Dev Containers 允许团队在项目里保存一份开发容器配置。开发者选择“在容器中重新打开”以后，VS Code 会连接到包含指定运行时和工具的容器，终端、代码补全、跳转和调试仍然留在熟悉的编辑器里。
下面是微软 Dev Containers 插件的真实命令面板。它没有重新设计一套窗口，而是把“在容器中重新打开项目”做成普通 VS Code 命令：
图片与功能说明来源：VS Code 官方 Dev Containers 文档。
对企业来说，这类插件解决的不是“少敲一条 Docker 命令”，而是让项目自己携带开发环境说明。新人拿到仓库后，不必依靠一份很快过期的安装文档。
Salesforce Extension Pack：把企业平台变成开发工作台
Salesforce 的例子更完整。Salesforce Extension Pack 不是单一语法插件，而是一组面向 Salesforce 平台开发的工具。
开发者可以连接开发组织、Sandbox（沙盒）或 Scratch Org（临时开发环境），在本地编写 Apex、Lightning Web Components、Aura 和 Visualforce，使用 Salesforce 的 SOQL 查询数据，运行 Apex 测试，再把代码取回或部署到 Salesforce 环境。也就是说，VS Code 在这里已经变成了 Salesforce 平台的桌面开发客户端。
下面是 Salesforce 官方文档提供的真实运行录屏。左侧是 Salesforce 项目和 Org Browser，底部可以看到 Salesforce CLI 正在读取组织中的对象定义：
图片与功能说明来源：Salesforce Extensions for Visual Studio Code。
这个案例很适合企业内部参考：插件不需要把后台系统复制一遍，只要把身份认证、对象浏览、开发命令、测试和部署入口接到编辑器里，就能形成一套完整工作流。
Red Hat Ansible：写自动化脚本时就发现问题
Ansible Playbook 是描述服务器自动化任务的配置文件，会用来安装软件、修改配置和发布服务。一个缩进、模块名或参数写错，影响的可能不只是当前文件。
Red Hat 的 Ansible VS Code Extension 提供语法高亮、自动补全、实时校验、ansible-lint 和模块文档提示，也支持多根工作区和容器化执行环境。开发者不用先切到浏览器搜索模块参数，鼠标停在模块上就能看到它的作用和注意事项。
图片来源：Ansible VS Code Extension 官方仓库；功能说明可参考 Red Hat Ansible VS Code 指南。
它说明代码检查插件不能只报“第 12 行错了”。越靠近业务和基础设施，越要把规则来源、修改建议和相关文档一起交给用户。
Container Tools：从 Dockerfile 一直看到镜像仓库
微软的 Container Tools 覆盖的是另一段流程：编写 Dockerfile 和 Compose、生成容器配置、启动调试、查看容器与日志，以及管理镜像、网络、数据卷和镜像仓库。
下面的真实界面来自 VS Code 官方文档。开发者在 Container Explorer 中找到仓库镜像以后，可以从右键菜单拉取、复制摘要、查看清单，或者部署到 Azure 服务：
图片与功能说明来源：VS Code Container Tools 文档。
它没有替代 Docker 或云平台，而是把当前项目最常用的容器动作整理成命令和树形视图。复杂能力仍在后端工具中，插件负责提供上下文和操作入口。
ESLint：功能很窄，也可以成为团队基础设施
不是每个插件都要连接一整套平台。ESLint for VS Code 会读取当前项目安装的 ESLint 和规则配置，把错误直接标在代码里，并提供“修复所有可自动修复问题”等命令。
它的价值来自一致性：规则随项目提交，编辑器按照同一份配置提醒，持续集成仍然可以在提交后再次检查。插件负责尽早反馈，CI 负责最后把关。
这些真实产品有什么共同点
看完这些产品，再回头想企业自己的插件，会发现它们大多遵循几条很朴素的做法：
- 使用命令面板、侧边栏、Problems、测试视图和状态栏等原生位置；
- 连接已有的 GitHub、Salesforce、Ansible、Docker 或内部平台，而不是重做后端；
- 根据当前仓库、文件、选中代码和登录身份提供操作；
- 成功时少打扰，失败时给出位置、原因和下一步；
- 明确说明会读取哪些文件、连接哪个系统、使用什么权限。
所以公司内部常见的插件也很具体：创建符合规范的新项目、检查依赖版本、查询当前服务负责人、打开内部文档、提交工单，或者在发布前确认代码是否满足安全规则。它们不一定需要 AI，先把重复流程做得稳定，通常就已经很有价值。
这次做什么
这一篇做一个本地代码检查插件：Engineering Guard。
它会检查当前文件里的三类问题：疑似硬编码凭证、没有超时的网络请求和字符串拼接 SQL。结果进入侧边栏和问题列表，点击以后可以回到对应代码。第一版不调用模型、不上传源码，也不需要 API Key。
这是 Engineering Guard 在 Extension Development Host 中的运行画面：
先把边界说清楚：这不是一套真正的企业安全平台，也不能替代专业的 SAST、依赖扫描和代码审查。它只是用一个容易验证的小例子，带你跑通命令、规则、侧边栏、菜单、状态栏和 VSIX 打包。
插件是怎样进入 VS Code 的
普通桌面插件运行在 Extension Host 中。VS Code 负责编辑器、命令面板、侧边栏和状态栏，插件通过 Extension API 注册自己的功能。这样一个插件出错时，不应该把整个编辑器主界面一起拖死。
package.json 负责告诉 VS Code“有哪些命令和界面入口”，插件入口负责真正执行检查，Tree View 或 Problems 面板负责把结果展示出来。
微软官方的 Tree View 示例就是这种结构。下面是真实的 References 结果视图：文件是父节点，具体命中位置是子节点，点击后回到代码。
图片来源：VS Code Tree View API。Engineering Guard 的问题列表也采用同样的原生交互，不需要为了显示几行结果就先做复杂 Web 页面。
1. 创建一个能调试的插件
电脑先安装 Node.js 当前 LTS 版本和 VS Code。新建一个空目录，用 VS Code 打开，然后对 AI 说：
请用 VS Code 官方生成器创建 TypeScript 插件，名称叫 Engineering Guard。完成后告诉我怎样按 F5 调试。
创建完成后先不要加业务功能。按 F5，VS Code 会再打开一个带有 Extension Development Host 标记的窗口。这个新窗口是插件的测试环境，原来的窗口继续显示代码和调试日志。
如果 F5 没有打开测试窗口，把错误交给 AI：
按 F5 后插件没有启动，错误是【粘贴错误】。请只修复调试配置。
看到默认 Hello World 通知以后再继续。第一步只确认项目、编译和 Extension Host 已经连通。
2. 先增加一条命令
把默认命令换成“检查当前文件”：
请增加“Engineering Guard: 检查当前文件”命令。运行后先显示当前文件名。
重新按 F5，在测试窗口中打开任意代码文件，再从命令面板运行这条命令。
这里要检查两个结果：打开文件时，通知里的文件名正确；没有打开文件时，插件提示“请先打开文件”。如果这两个状态都正常，说明插件已经能读取编辑器上下文。
3. 加入三条本地规则
命令跑通后再做扫描：
请检查疑似硬编码密钥、没有超时的网络请求和字符串拼接 SQL。只扫描当前文件，不上传代码。
准备一个专门的测试文件，每种问题只放一处。运行检查后，三条规则都应该出现；修改其中一处再检查，对应问题应该消失。
规则不要一次增加几十条。企业代码检查最怕“什么都报”，最后所有人都学会忽略。先让每一条规则都有清楚的命中条件、位置和修改建议。
4. 把结果放进侧边栏和 Problems
现在让检查结果离代码更近：
请把结果显示在 Problems 和 Engineering Guard 侧边栏。点击问题时跳到对应文件和行号。
侧边栏先处理四种状态：还没检查、没有问题、发现问题、原文件已经关闭。空状态也要告诉用户下一步做什么，不能只留一块空白。
VS Code 官方 Tree View 指南给出了独立活动栏入口的真实效果：
图片来源：VS Code Tree View API。
Engineering Guard 的实际界面中，左侧保留检查入口，右侧显示命中的规则和风险等级：
5. 增加菜单和状态栏
检查命令不应该只能从命令面板找到。继续增加两个入口：
请在编辑器右键菜单增加“检查选中代码”，没有选中内容时不显示。
再给资源管理器增加文件检查：
请在资源管理器右键菜单增加“检查这些文件”，跳过图片、依赖目录和超大文件。
VS Code 的原生菜单可以出现在视图标题、列表项和右键菜单中。官方示例把这些位置标得很清楚：
图片来源：VS Code Tree View API：View Actions。
最后增加一个安静的状态栏入口：
请在状态栏显示最近一次检查结果，点击后打开侧边栏。
状态栏只需要显示“未检查”“通过”或问题数量，不要闪烁，也不要一直弹通知。
6. 检查结果要让人看得懂
现在从测试文件触发三条规则，确认文件名、行号、严重程度和建议都正确。最终结果应该类似下面这样：
这里最重要的不是风险分数，而是每一条结果都能回答三个问题：哪里有问题、为什么有风险、下一步应该做什么。点击问题还要回到对应代码，不能让用户自己搜索行号。
7. AI 能力放到最后
本地规则完整跑通以后，才考虑让模型解释问题或生成修复建议。AI 不应该成为“能不能检查代码”的前置条件。
请增加一个可选的解释入口，只解释当前选中的检查结果。没有模型权限时，本地检查继续工作。
发送代码前要明确告诉用户会包含哪些内容。企业版本还要遵守仓库权限、组织策略和数据边界，不能默认把整个项目上传给外部服务。
8. 从头验收一次
不要只看最后一张漂亮页面。重新加载 Extension Development Host，然后依次检查：
- 命令面板可以找到“检查当前文件”；
- 无问题文件显示通过；
- 测试文件能稳定命中三条规则；
- 点击侧边栏和 Problems 结果能回到正确行；
- 编辑器右键和资源管理器多选都能运行；
- 修复代码后，旧问题会消失；
- 禁用模型能力后，本地检查仍然可用；
- 重新加载窗口后，命令、视图和状态栏仍然存在。
某一步失败时，只描述这一项：
第【几】步失败，现象是【描述】。请只修复这一项。
9. 打包成 VSIX
开发窗口里能运行，还不等于别人能安装。先补齐插件名称、版本、图标、仓库、许可证和隐私说明，然后对 AI 说：
请用 VS Code 官方 vsce 工具打包 VSIX，并排除测试数据和无关文件。
生成 VSIX 后，换一个 VS Code 配置或另一台电脑，选择“Install from VSIX”，再跑一遍命令、规则、侧边栏和定位功能。
公司内部不一定要发布到公开 Marketplace。VSIX 可以放在内部制品库，也可以通过组织的软件分发方式安装。真正准备公开发布时，再按照当前的 VS Code 发布文档创建发布者并提交。
10. 做完以后，你掌握了什么
到这里，我们已经跑通了一条完整的插件链路：
VS Code 命令 → 读取当前文件 → 本地规则 → Problems / Tree View → 菜单和状态栏 → VSIX。
它还不是企业级代码安全产品，但已经可以继续替换真实规则。以后可以接入公司的项目模板、规则服务、代码负责人、工单系统或发布门禁，同时保留最重要的原则：用户知道插件读了什么、错误能定位、离线功能不会因为模型不可用而失效。
参考资料
- VS Code Extension API
- Your First Extension
- Extension Anatomy
- Tree View API
- VS Code UX Guidelines：Views
- VS Code 官方 GitHub 协作指南
- GitHub Pull Requests and Issues
- VS Code Dev Containers
- Salesforce Extensions for Visual Studio Code
- Red Hat Ansible VS Code Extension
- VS Code Container Tools
- ESLint for VS Code
- 发布 VS Code 插件