Cline 插件开发深度指南（中文版）

受众：面向希望为 Cline 开发插件的开发者。

内容范围：基于源码分析得出的架构事实，结合 Cline CLI 3.0.31 与 VS Code 扩展 4.0.0 的实际测试结果。本指南补充了官方插件文档未覆盖的内容。

更新日期：2026-06-28

---

核心速览

1. Cline 插件运行在 Node.js 子进程中，而非文件系统沙箱内。插件内的 fs.writeFileSync() 会直接写入宿主文件系统。
2. VS Code 扩展 4.0.0 存在缺陷：构建产物中缺失 plugin-sandbox-bootstrap.js，插件会静默加载失败。可通过对应补丁修复（见第 4 节）。
3. messageBuilder 中的 build() 方法每轮对话都会执行，并非仅在上下文压缩时调用，请保证其执行效率。
4. TypeScript 可通过 jiti 开箱即用，无需额外构建步骤。
5. 插件内的 console.log() 不会输出到 VS Code 开发者工具中，建议使用文件标记法进行调试。

---

1. 插件沙箱架构

1.1 本质是 Node 子进程

SubprocessSandbox（位于 core/src/runtime/tools/subprocess-sandbox.ts）本质就是普通的 child_process.spawn("node", [bootstrapFile])。不存在文件系统沙箱——没有 seccomp、没有 AppArmor、也没有 Windows 沙箱机制。

完整调用链路：

VS Code 扩展 / CLI
  → loadSandboxedPlugins()           ← 对应 plugin-sandbox.ts
  → SubprocessSandbox.spawn()        ← 执行 child_process.spawn("node", 启动文件)
  → plugin-sandbox-bootstrap.ts      ← 子进程入口
  → importPluginModule(插件路径)     ← 对应 plugin-module-import.ts
  → jiti.import(插件路径)            ← 实时完成 TS 到 JS 的转译
  → plugin.setup(api, ctx)           ← 你的插件代码在此执行

说明：这里的 sandbox 并非文件系统沙箱。如果在 setup() 中写文件失败，原因几乎都是目标目录不存在，而非被沙箱拦截。使用 mkdirSync({ recursive: true }) 即可解决。

1.2 启动流程

阶段	执行内容
插件发现	discoverPluginModulePaths() 扫描 ~/.cline/plugins/ 目录，查找包含 cline 字段的 package.json
沙箱启动	SubprocessSandbox 启动一个 node 子进程，加载 plugin-sandbox-bootstrap.js
模块导入	jiti 实时将你的 .ts 插件转译为 JS
初始化	调用 plugin.setup(api, ctx)——在此注册你的构建器、工具、钩子等能力

1.3 插件生命周期

会话启动 → 插件发现 → 沙箱启动 → setup() 执行
  → 每轮对话：messageBuilders.build(messages) → 安全层 → 模型提供方

关键结论：build() 在每轮对话准备阶段都会执行，并非仅在上下文压缩时触发。你的 build() 函数应当保证执行速度（建议 < 100ms）。如果需要执行重负载逻辑，请通过条件判断来控制执行时机。

---

2. 插件项目结构

2.1 最简可用插件

my-plugin/
├── package.json          # 必须包含 cline 字段
├── src/
│   └── index.ts          # 包含 setup() 的插件对象
└── README.md

2.2 package.json 配置

{
  "name": "my-cline-plugin",
  "type": "module",
  "exports": { ".": "./src/index.ts" },
  "cline": {
    "plugins": [{
      "paths": ["./src/index.ts"],
      "capabilities": ["messageBuilders"]
    }]
  },
  "peerDependencies": {
    "@cline/core": "*",
    "@cline/shared": "*"
  },
  "peerDependenciesMeta": {
    "@cline/core": { "optional": true },
    "@cline/shared": { "optional": true }
  }
}

说明：peerDependencies 设为可选——运行时由宿主环境（CLI 或扩展）提供依赖，插件自身无需执行 npm install。

2.3 能力类型

能力标识	对应 API 方法	同步/异步
tools	api.registerTool(tool)	异步执行
commands	api.registerCommand(command)	同步或异步
rules	api.registerRule(rule)	同步或异步
messageBuilders	api.registerMessageBuilder({ name, build })	同步 build
hooks	plugin.hooks 字段	异步

注意：build() 在 RPC 层会被 await 包裹，但函数本身应当编写为同步逻辑。文件 I/O 请使用 writeFileSync 等同步方法。

2.4 沙箱 RPC 通信协议

插件通过 IPC（child_process.send/on）与主进程通信：

RPC 方法	方向	用途
initialize	主进程→沙箱	加载插件
buildMessages	主进程→沙箱	执行 messageBuilder
invokeHook	主进程→沙箱	执行钩子
executeTool	主进程→沙箱	执行工具

沙箱会在进程退出或 RPC 超时后自动重新初始化，无需手动管理连接状态。

---

3. 安装方式

3.1 CLI 端（开箱即用）

cline plugin install ./my-plugin --cwd .

也可以手动复制到 ~/.cline/plugins/installed/local/my-plugin/ 目录。

3.2 VS Code 扩展端（需要补丁修复）

⚠️ VS Code 扩展 4.0.0 无法开箱即用插件功能，尽管其构建包中已经包含了插件加载的相关代码。根本原因与修复方案见第 4 节。

应用补丁（第 4 节）后，按以下步骤安装：

1. 将插件放入 ~/.cline/plugins/installed/local/my-plugin/
2. 打开自定义面板（Cline 侧边栏 → 齿轮图标）——你的插件应当出现在列表中
3. 重载 VS Code 窗口

---

4. VS Code 扩展插件功能修复补丁

4.1 问题根源

VS Code 扩展 4.0.0 的 esbuild 构建流程将所有插件加载代码（loadSandboxedPlugins、SubprocessSandbox、registerMessageBuilder）都打包进了 dist/extension.js，但没有将 plugin-sandbox-bootstrap.js 作为独立文件输出。

加载链路在 resolveBootstrap() 步骤失败——程序会在 5 个候选路径中查找启动文件，但扩展环境中这些路径全部不存在。jiti 降级方案也会失效，因为 jiti 被内联打包，无法在子进程中通过 require() 加载。

最终表现：沙箱子进程始终无法启动 → 4 秒超时 → setup() 永远不会执行。

官方文档称：“该功能目前暂不支持 VS Code 与 JetBrains 扩展端”。但实际上相关代码已经完整存在——这只是构建流程的疏漏，并非功能被刻意移除。

说明：UI 的自定义面板能识别到插件并显示“已加载”，但这只是文件发现阶段（discoverPluginModulePaths）的结果，不代表沙箱已经成功激活。两者是相互独立的代码路径。

4.2 修复方案

CLI 发行版中正确包含了 plugin-sandbox-bootstrap.js。补丁的原理就是将该文件及所需依赖复制到 VS Code 扩展目录中。

补丁执行内容：

1. 定位你的 VS Code 扩展目录（saoudrizwan.claude-dev-*）
2. 定位你的 CLI 安装路径（@cline/core）
3. 将 plugin-sandbox-bootstrap.js 复制到扩展的 dist/extensions/ 目录
4. 将 @cline/shared、@cline/core、jiti 复制到扩展的 node_modules/ 目录
5. 设置 CLINE_PLUGIN_IMPORT_TIMEOUT_MS=30000（仅 Windows；根据 Issue #11065，默认 4 秒超时在 Windows 上过短）

补丁脚本下载：

操作系统	脚本文件	下载链接
Windows	patch-vscode-plugin-support.ps1	Windows 版下载
macOS/Linux	patch-vscode-plugin-support.sh	macOS/Linux 版下载

4.3 手动修复步骤

如果你不想运行脚本，可按以下步骤手动操作：

Windows：

$ext = "$env:USERPROFILE\.vscode\extensions\saoudrizwan.claude-dev-4.0.0"
$cli = "$env:APPDATA\npm\node_modules\cline\node_modules"

# 1. 创建目标目录
New-Item -ItemType Directory -Force "$ext\dist\extensions"
New-Item -ItemType Directory -Force "$ext\node_modules\@cline"

# 2. 复制启动文件
Copy-Item "$cli\@cline\core\dist\extensions\plugin-sandbox-bootstrap.js" "$ext\dist\extensions\"

# 3. 复制依赖包
Copy-Item -Recurse "$cli\@cline\shared" "$ext\node_modules\@cline\shared"
Copy-Item -Recurse "$cli\@cline\core"   "$ext\node_modules\@cline\core"
Copy-Item -Recurse "$cli\jiti"          "$ext\node_modules\jiti"

# 4. 延长超时时间（Windows 专属，修复 Issue #11065）
[Environment]::SetEnvironmentVariable("CLINE_PLUGIN_IMPORT_TIMEOUT_MS", "30000", "User")

# 5. 重载 VS Code
# 按 Ctrl+Shift+P → 执行 "Developer: Reload Window"

macOS/Linux：

EXT="$HOME/.vscode/extensions/saoudrizwan.claude-dev-4.0.0"
# 查找 CLI 路径——如果安装路径不同请自行调整
CLI=$(dirname $(which cline))/../lib/node_modules/cline/node_modules

mkdir -p "$EXT/dist/extensions"
mkdir -p "$EXT/node_modules/@cline"

cp "$CLI/@cline/core/dist/extensions/plugin-sandbox-bootstrap.js" "$EXT/dist/extensions/"
cp -r "$CLI/@cline/shared" "$EXT/node_modules/@cline/shared"
cp -r "$CLI/@cline/core"   "$EXT/node_modules/@cline/core"
cp -r "$CLI/jiti"          "$EXT/node_modules/jiti"

4.4 验证方法

应用补丁后，安装任意插件并按以下方式验证：

1. 自定义面板：插件正常显示且状态为已加载
2. 标记文件：如果你的插件在 setup() 中会写入标记文件，检查该文件是否生成
3. 控制台输出：插件的 console.log() 不会出现在 VS Code 开发者工具中——请使用文件方式调试

说明：调试插件最可靠的方式是在 setup() 和 build() 中写入带时间戳的标记文件，而非依赖 console.log。

---

5. 开发技巧

5.1 调试方法

方法	CLI 端是否可用	VS Code 端是否可用
console.log()	✅ 输出到标准输出	❌ 被通信桥接层吞掉
ctx.logger.log()	✅	✅ 输出到 Cline 输出通道
文件标记法	✅	✅
VS Code 开发者工具控制台	不适用	❌ 插件运行在独立进程中

5.2 上下文压缩阈值

参数	默认值	含义
MAX_INPUT_TOKENS	120,000	模型最大输入 token 数
COMPACT_AT_RATIO	0.75	当 token 占用达到 75% 时触发压缩
PRESERVE_RECENT_TOKENS	24,000	保留最近的 24000 token 不压缩

你的 build() 函数会接收完整的消息数组。可以参考 shouldCompact() 的逻辑，先判断 token 数量再执行重负载操作。

5.3 插件扫描路径

Cline 会在以下位置扫描插件：

• <工作区>/.cline/plugins/（工作区本地）
• ~/.cline/plugins/（全局）
• 系统插件文件夹

会递归扫描子目录。合法的插件需要包含带 cline 字段的 package.json。

5.4 常见踩坑点

问题	现象	解决方法
启动文件缺失（VS Code 端）	setup() 永远不执行	应用第 4 节的补丁
目录不存在	writeFileSync 静默抛出 EPERM 错误	在 setup() 中使用 mkdirSync({ recursive: true })
console.log 无输出	开发者工具中看不到日志	使用文件标记或 ctx.logger
Windows 4秒超时	Windows 上插件加载超时	设置 CLINE_PLUGIN_IMPORT_TIMEOUT_MS=30000
build() 执行过慢	对话响应卡顿	通过条件判断控制重负载逻辑的执行
无错误处理	插件静默失败	所有逻辑用 try-catch 包裹

---

6. 快速开始检查清单

• 阅读官方插件文档
• 创建包含 cline.plugins[] 字段的 package.json（见 2.2 节）
• 创建 src/index.ts，实现 setup() 并注册对应能力（见 2.3 节）
• 先在 CLI 端测试：cline plugin install ./my-plugin --cwd .
• 如果要适配 VS Code：应用启动文件补丁（第 4 节）
• 使用文件标记法进行调试（见 5.1 节）
• 所有 I/O 操作用 try-catch 包裹（见 5.4 节）
• 保证 build() 为同步逻辑且执行高效（见 1.3 节）

---

附录：源码参考

组件	Cline 仓库中的路径
插件沙箱	sdk/packages/core/src/extensions/plugin/plugin-sandbox.ts
启动文件	sdk/packages/core/src/extensions/plugin/plugin-sandbox-bootstrap.ts
模块导入	sdk/packages/core/src/extensions/plugin/plugin-module-import.ts
插件加载器	sdk/packages/core/src/extensions/plugin/plugin-loader.ts
插件安装	sdk/packages/core/src/services/plugin-install.ts
插件发现	sdk/packages/shared/src/storage/paths.ts
子进程沙箱	sdk/packages/core/src/runtime/tools/subprocess-sandbox.ts
自定义压缩示例	sdk/examples/plugins/custom-compaction.ts

---

本指南基于对 Cline 4.0.0 代码库（22.5MB 压缩后包 + SDK 源码）的分析、CLI 3.0.31 实测，以及在 7 次真实压缩场景下验证的 VS Code 扩展 workaround 编写。最后更新：2026-06-28