1. 从“plugins”这个词说起：它到底在解决什么问题

如果你最近在折腾 AI 编程工具，尤其是 Cursor、Codex CLI、Claude Code 这类东西，大概率会频繁撞见plugins这个词。它可能出现在一个叫plugin.json的配置文件里，也可能出现在某条报错信息里，比如harness failed to load plugins，或者你在终端敲下某个 CLI 命令后，它提示你“插件未激活”。很多人第一次看到这些，脑子里冒出来的问题是：这玩意儿到底是干嘛的？为什么我装了个编辑器，还要去理解插件系统？

我先把结论摆在前面：plugins本质上是一套“能力扩展协议”。编辑器或者 CLI 工具本身只提供最核心的功能——读写文件、调用模型、渲染界面。但真实开发场景里，你需要的东西远不止这些：代码跳转、语言高亮、Git 集成、终端复用、甚至让 AI 按照你团队的规范去生成代码。这些东西不可能全部塞进主程序里，否则主程序会变成一个几百斤的胖子，启动慢、维护难、还容易崩。所以现代工具普遍采用插件机制，把“核心”和“扩展”拆开，核心保持轻量稳定，扩展按需加载。

这个思路其实不新鲜。VS Code 就是靠插件生态活下来的，Chrome 也是。但 AI 编程工具这一波的插件系统和传统编辑器有个关键区别：它不只是扩展 UI 功能，还要扩展“模型的行为”。比如一个插件可以往 AI 的上下文里注入额外的系统提示词，可以拦截模型的输出做后处理，可以在模型调用工具之前做权限校验。这就让plugins从一个单纯的“功能模块”变成了“AI 工作流的控制层”。

所以当你看到plugin.json这个文件时，它大概率是这个插件系统的清单文件，里面声明了这个插件叫什么、版本多少、入口在哪、需要哪些权限、暴露哪些命令。而TypeScript SDK则是给开发者用的工具包，让你能用 TypeScript 写插件逻辑，调用宿主环境提供的 API。CLI 则是另一条路径——有些插件是给命令行工具用的，比如你在终端里跑codex cli或者gitlab cli，它们也支持通过插件来扩展子命令。

我见过太多人卡在第一步：装了一堆插件，结果要么不生效，要么报错说“entry did not activate”。这背后的原因往往不是插件本身有问题，而是没搞清楚插件系统的加载逻辑和激活条件。接下来我会把这套东西拆开，从设计思路到实操细节，再到踩坑记录，尽量讲透。

2. 插件系统的整体设计与核心思路拆解

2.1 为什么是 plugin.json 而不是直接写代码

很多人会问：既然插件就是一段逻辑，为什么不能直接写个.ts文件丢进去，非要搞一个plugin.json？这个问题问得好，答案涉及三个层面的考量。

第一是声明式与命令式的分离。plugin.json是声明式的，它告诉宿主“我是谁、我要什么、我能做什么”。宿主在加载插件之前，先读这个清单，判断当前环境是否满足插件的需求。如果不满足，直接跳过，不会执行任何插件代码。这比“先加载再报错”要安全得多。举个例子，某个插件声明它需要filesystem:write权限，但当前工作区是只读模式，宿主就可以在加载阶段直接拒绝，而不是等插件跑到一半才崩掉。

第二是版本与依赖管理。plugin.json里通常会写engines字段，声明这个插件兼容的宿主版本范围。这跟 npm 的package.json是一个道理。没有这个字段，宿主升级后插件行为可能完全不可预期。我实测下来，很多“插件突然失效”的案例，根源就是宿主自动更新后，插件的 API 调用方式变了，但插件本身没有声明版本约束。

第三是安全边界。插件系统本质上是在一个沙箱里运行第三方代码。plugin.json里的permissions字段就是沙箱的钥匙串。一个只做代码格式化的插件，不应该有网络访问权限；一个只读文件的插件，不应该有写入权限。这种最小权限原则，在 AI 编程工具里尤其重要，因为插件可能接触到你的整个代码库。

2.2 TypeScript SDK 的角色：让插件开发有类型可依

如果你打算自己写一个插件，TypeScript SDK是你最该先看的东西。它提供的不只是类型定义，还有一套运行时工具函数。比如definePlugin这个函数，它接收一个配置对象，返回一个符合宿主规范的插件实例。你在里面可以定义activate和deactivate两个生命周期钩子。

activate是插件被激活时调用的，通常用来注册命令、监听事件、初始化状态。deactivate是插件被卸载或宿主关闭时调用的，用来清理资源。我见过不少插件作者忘记写deactivate，结果插件反复激活后，事件监听器越积越多，最后宿主响应变慢。这个问题在 Cursor 这类长时间运行的编辑器里特别明显。

SDK 里还有一类很重要的 API 是context对象。它提供了访问宿主能力的入口，比如context.subscriptions用来收集需要释放的资源，context.workspaceState用来做轻量级持久化。这些设计跟 VS Code 的插件 API 非常相似，如果你写过 VS Code 插件，上手会很快。

2.3 CLI 场景下的插件加载：跟编辑器有什么不同

CLI 工具的插件系统和编辑器有个本质区别：CLI 是短生命周期的。你敲一条命令，进程启动、执行、退出，整个过程可能只有几百毫秒。这意味着 CLI 插件不能依赖“常驻内存”的状态，每次执行都要重新加载。

这就引出了harness failed to load plugins这类报错的常见原因。harness是宿主环境里负责加载插件的模块，它在启动时会扫描插件目录，读取每个plugin.json，然后尝试激活。如果某个插件的入口文件有语法错误，或者依赖了一个不存在的模块，harness就会报“1 entry did not activate”。注意这里的措辞——“did not activate”，不是“load failed”。这意味着清单文件读到了，但激活过程失败了。

在 CLI 场景下，我建议插件作者把初始化逻辑写得尽量轻。不要在activate里做网络请求，不要读大文件，不要做复杂计算。因为 CLI 用户对启动时间非常敏感，你多花 200 毫秒，用户就能感觉到卡顿。正确的做法是：activate里只做注册，真正的逻辑延迟到命令执行时再跑。

3. 核心细节解析与实操要点

3.1 plugin.json 的关键字段逐个拆

一个典型的plugin.json长这样：

{ "name": "my-awesome-plugin", "version": "1.0.0", "description": "A plugin that does something useful", "main": "./dist/index.js", "engines": { "host": ">=1.2.0" }, "permissions": ["filesystem:read", "workspace:write"], "activationEvents": ["onCommand:myPlugin.run"], "contributes": { "commands": [ { "command": "myPlugin.run", "title": "Run My Plugin" } ] } }

这里有几个字段值得展开说。

main指向插件的入口文件。注意，如果你用 TypeScript 写，编译后通常是dist/index.js。我踩过一个坑：本地开发时直接指向src/index.ts，结果宿主不认，因为它只加载 JavaScript。后来改成先编译再调试，问题解决。

activationEvents决定了插件什么时候被激活。常见的有onCommand:xxx（执行某个命令时激活）、onLanguage:typescript（打开某类文件时激活）、*（启动就激活）。最后这个要慎用，因为它会让你的插件拖慢整个宿主的启动速度。我建议尽量用精确的激活事件，按需加载。

contributes是插件向宿主“贡献”的功能声明。比如贡献一个命令、一个快捷键、一个配置项。宿主在启动时会读取这些声明，把它们注册到对应的系统里。注意，contributes只是声明，真正的实现逻辑还是在main指向的代码里。

permissions字段在不同宿主里的严格程度不一样。有些宿主只是记录，不做强制校验；有些宿主会真的拦截 API 调用。不管怎样，我建议你只申请真正需要的权限。这不仅是安全问题，也影响用户对你的信任。

3.2 TypeScript SDK 的初始化模板与生命周期

用 SDK 写插件，入口文件通常是这样：

import { definePlugin } from '@host/plugin-sdk'; export default definePlugin({ activate(context) { const disposable = context.commands.register('myPlugin.run', () => { context.window.showInformationMessage('Plugin is running!'); }); context.subscriptions.push(disposable); }, deactivate() { // cleanup if needed } });

这里的关键点是context.subscriptions。它是一个数组，你往里 push 的所有对象，都会在插件停用时自动调用dispose()方法。这是防止内存泄漏的标准做法。我见过有人手动管理监听器，结果漏掉一个，导致插件停用后还在响应事件，最后宿主行为诡异。

另一个容易忽略的是activate可以是异步的。如果你的插件需要读取配置文件或者初始化数据库连接，可以返回一个 Promise。宿主会等待这个 Promise resolve 之后，才认为插件激活完成。但注意，异步激活会拖慢启动，所以只在你真的需要时才用。

3.3 CLI 插件的目录结构与加载顺序

CLI 工具的插件通常放在一个约定好的目录里，比如~/.host/plugins/或者项目根目录下的.host/plugins/。宿主启动时会按顺序扫描这些目录。加载顺序一般是：全局插件先加载，项目级插件后加载。后加载的插件可以覆盖先加载的同名命令。

这个覆盖机制很有用。比如你全局装了一个代码格式化插件，但某个项目需要不同的格式化规则，你可以在项目级插件里覆盖它。但这也带来一个隐患：如果两个插件注册了同一个命令名，后加载的会静默覆盖前面的，用户可能完全不知道。所以我在写插件时，命令名都会加前缀，比如myPlugin.format，避免冲突。

还有一个细节是插件的依赖解析。如果插件 A 依赖插件 B 提供的 API，你需要确保 B 先加载。有些宿主支持在plugin.json里声明dependencies，有些则要求你在代码里做运行时检查。我建议不管宿主支不支持，都在代码里加一个防御性判断：如果依赖的 API 不存在，就优雅降级，而不是直接抛错。

4. 实操过程与核心环节实现

4.1 从零写一个最小可用插件

假设我们要给某个支持插件系统的 CLI 工具写一个插件，功能很简单：执行hello命令时，输出当前工作目录下的文件数量。整个过程分五步。

第一步，创建目录结构：

mkdir -p my-plugin/src cd my-plugin

第二步，写plugin.json：

{ "name": "file-counter", "version": "0.1.0", "main": "./dist/index.js", "engines": { "host": ">=1.0.0" }, "activationEvents": ["onCommand:fileCounter.count"], "contributes": { "commands": [ { "command": "fileCounter.count", "title": "Count files" } ] } }

第三步，写 TypeScript 源码src/index.ts：

import { definePlugin } from '@host/plugin-sdk'; import * as fs from 'fs'; import * as path from 'path'; export default definePlugin({ activate(context) { context.commands.register('fileCounter.count', async () => { const cwd = context.workspace.rootPath; const files = fs.readdirSync(cwd); context.window.showInformationMessage(`Found ${files.length} entries`); }); } });

第四步，配置tsconfig.json并编译：

{ "compilerOptions": { "target": "ES2020", "module": "CommonJS", "outDir": "./dist", "rootDir": "./src", "strict": true }, "include": ["src/**/*"] }

然后跑npx tsc，生成dist/index.js。

第五步，把整个插件目录链接到宿主的插件目录：

ln -s $(pwd) ~/.host/plugins/file-counter

重启宿主，执行host fileCounter.count，应该能看到输出。

4.2 参数计算与选择：激活事件怎么定

激活事件的选择直接影响用户体验。我拿三个场景举例说明。

场景一：插件只在用户主动执行命令时才需要。这时候用onCommand:xxx最合适。宿主启动时完全不加载你的代码，只有用户敲了命令才激活。启动开销为零。

场景二：插件需要在打开特定类型文件时自动生效，比如给.sql文件提供语法检查。这时候用onLanguage:sql。宿主会在打开这类文件时激活插件，其他时候不加载。

场景三：插件需要监听全局事件，比如文件保存。这时候可能需要onStartup或者*。但这类激活事件代价最大，因为插件会在宿主启动时就加载。我的建议是，如果非要用，就把初始化逻辑压到最简，只注册监听器，不做任何耗时操作。

有一个容易被忽略的点：激活事件可以组合。比如["onCommand:xxx", "onLanguage:typescript"]，表示满足任一条件就激活。但激活之后，插件会一直驻留，直到宿主关闭。所以如果你有多个激活事件，要确保插件在任意一个场景下被激活后，不会对其他场景产生副作用。

4.3 实操现场记录：一次真实的调试过程

我之前写过一个插件，功能是给 CLI 工具添加一个deploy子命令。本地测试一切正常，但发布后有人反馈说执行deploy时报错command not found。我远程连上去排查，发现他的宿主版本比我本地低一个小版本。

问题出在engines字段。我写的是">=1.2.0"，但他的宿主是1.1.5。按理说宿主应该拒绝加载，但它没有，而是静默跳过了contributes里的命令注册。这就导致插件看起来“加载了”，但命令不存在。

后来我做了两件事：第一，把engines改成更宽松的">=1.1.0"，因为实际用到的 API 在 1.1.0 就有了；第二，在activate里加了一个版本检查，如果宿主版本低于预期，就输出一条明确的警告信息，而不是静默失败。

这个经历告诉我，engines字段不是装饰品，宿主对它的处理方式各不相同。最稳妥的做法是：在代码里做运行时能力检测，而不是完全依赖清单声明。

5. 常见问题与排查技巧实录

5.1 harness failed to load plugins 的排查路径

这个报错信息通常后面会跟一句“N entry did not activate”。排查思路可以按以下顺序走。

先看插件目录结构对不对。宿主一般要求每个插件一个独立目录，目录里有plugin.json。如果你把多个插件塞进同一个目录，或者plugin.json放错了层级，宿主就找不到。

再看入口文件是否存在。plugin.json里的main路径是相对于插件目录的。如果你写的是./dist/index.js，但实际编译输出在./build/index.js，就会加载失败。这个错误很隐蔽，因为宿主可能只报“did not activate”，不告诉你具体原因。

然后看依赖是否完整。如果插件require了一个没有安装的 npm 包，激活时会抛MODULE_NOT_FOUND。CLI 场景下，这个错误可能被宿主吞掉，只留下“did not activate”。我的做法是在插件目录里跑一次node -e "require('./dist/index.js')"，手动触发加载，看真实报错。

最后看权限。有些宿主在权限不足时会拒绝激活，但报错信息可能很模糊。检查plugin.json里的permissions是否覆盖了插件实际用到的 API。

5.2 插件不生效但没有任何报错

这种情况比报错更让人头疼。我总结了几种常见原因。

第一种是激活事件没匹配上。比如你声明了onCommand:myPlugin.run，但用户执行的是myplugin.run（大小写不同），宿主就认为没有匹配的命令，插件永远不会激活。命令名大小写敏感这个问题，我在不同宿主上遇到过好几次。

第二种是插件被更高优先级的同名插件覆盖了。前面提过，后加载的插件会覆盖先加载的。如果你在项目级插件目录里放了一个同名插件，全局的那个就失效了。

第三种是宿主缓存了旧的插件清单。有些宿主为了加速启动，会把plugin.json的内容缓存起来。你改了清单但没重启宿主，改动不会生效。我一般会先完全退出宿主进程，再重新启动。

5.3 常见问题速查表

5.4 几个我踩过的坑和对应技巧

第一个坑：在activate里做同步文件读取。CLI 场景下，这会让启动时间从 50 毫秒涨到 300 毫秒。后来我改成在命令执行时才读文件，启动时间恢复正常。

第二个坑：用console.log调试。CLI 宿主的 stdout 可能被重定向或者被宿主自己占用，你的日志根本看不到。正确做法是用宿主提供的日志 API，比如context.logger.info()，它会写到宿主的日志文件里。

第三个坑：忘记处理 Windows 路径分隔符。我在 macOS 上写插件时用/拼接路径，到了 Windows 上就找不到文件。后来统一用path.join()，问题解决。

第四个坑：插件版本升级后，旧的配置文件格式不兼容。我现在的做法是在activate里读配置时，先检查configVersion字段，如果不匹配就做迁移或者提示用户重新配置。

6. 插件生态的扩展思路与个人体会

插件系统最吸引我的地方，是它把“工具”变成了“平台”。一个编辑器或者 CLI 工具，核心功能再强也有边界，但插件生态可以让它无限扩展。我见过有人给 CLI 工具写插件，把内部的部署流程封装成一条命令；也见过有人给编辑器写插件，让 AI 按照团队代码规范自动审查。

如果你打算深入这个方向，我的建议是从小处着手。先写一个只做一件事的插件，把它跑通，理解加载、激活、注册、执行、清理这五个环节。然后再考虑复杂场景，比如多插件协作、跨插件通信、动态配置。

另外，TypeScript SDK的类型定义是你最好的文档。遇到不确定的 API，直接看类型签名，比翻文档快得多。CLI 场景下，多关注宿主的启动性能，插件写得轻一点，用户会感谢你。

最后分享一个我最近在用的调试技巧：在插件目录里放一个debug.json，里面写{ "verbose": true }。然后在插件代码里读这个文件，如果存在就输出详细日志。这样发布时不用改代码，只需要删掉这个文件，日志就自动关闭了。实测下来很稳，推荐你也试试。