ClineCore SDK 常见陷阱：@cline/core 资源生命周期、会话配置与运行模式实战指南

本文基于 Cline 仓库中 @cline/core（ClineCore SDK）的官方注意事项文档整理而成，面向将 Cline 作为编程 SDK 集成的开发者。内容覆盖 ClineCore.create() / start() / dispose() 全生命周期中最容易踩坑的 12 个问题：资源泄漏、Node 版本要求、工具策略的两级配置、内置工具开关、工作目录、Hub 启动延迟、会话存储位置、审批阻塞、插件发现路径、extensionContext、send()/result 的边界条件以及长会话压缩。读完后，你可以将 ClineCore 稳定地嵌入自动化流水线、CLI 工具或服务端应用，并避免会话挂起、工具不可用、插件加载失败等典型故障。

必须调用 dispose() 释放资源

ClineCore 实例持有多类系统资源，包括文件监视器、数据库连接以及 Hub 连接。如果不调用 dispose()，可能留下孤儿进程和残留的文件锁。标准写法是把使用过程包在 try/finally 中：

const cline = await ClineCore.create({ clientName: "my-app" });
try {
  // ... use cline
} finally {
  await cline.dispose();
}

从源码看，dispose() 的清理范围比表面更宽。在 ClineCore.ts 中，dispose 的实现依次做了三件事：

1. 先 await this.automationService?.dispose()，释放启用自动化（Cron）时创建的定时任务服务；
2. 再 await this.host.dispose(...)，关闭底层运行时宿主（local / hub / remote 三种 RuntimeHost 之一）持有的连接与会话；
3. 在 finally 中取消会话事件订阅，并对 activeSessionBootstraps 中登记的所有活跃会话 bootstrap 逐个调用 dispose()。

另外，ClineCore 构造函数里通过 this.host.subscribe(...) 订阅了会话 ended 事件，会话正常结束时会自动清理对应的 bootstrap 资源（见 ClineCore.ts），即单个会话的资源回收是自动的；但整个 SDK 实例级别的资源回收仍然必须依赖你显式调用 dispose()，且调用后该实例不可复用。

Node.js 22 是硬性要求

ClineCore 与 @cline/core 要求 Node.js 22 或更高版本，低版本下会出现运行时错误。用 node --version 确认当前版本。

这一点在包的元数据中有明确声明：sdk/packages/core/package.json 中的 engines 字段写着 "node": ">=22"。因此在 CI 容器、Serverless 运行时或老版本系统上运行前，请先确认基础镜像的 Node 大版本，而不是等到运行期报错。

工具策略：全局配置与每会话配置的两级关系

工具策略（tool policies）可以在两个层级设置：

• 全局层：在 ClineCore.create({ toolPolicies }) 中设置，对所有会话生效；
• 会话层：在 cline.start({ toolPolicies }) 中设置，仅对该会话生效，并且覆盖全局层。

每会话策略优先级更高。设计多会话服务端应用时，可以依赖这个覆盖语义实现「默认全批准 + 个别会话收紧」或反向的策略分布。会话级 toolPolicies 的处理逻辑可以在 cline-core 类型定义 与启动输入归一化代码（sdk/packages/core/src/cline-core/start-input.ts）中找到对应实现。

enableTools 必须显式开启

内置工具（bash、editor、read_files 等）默认不可用，必须在会话配置中显式设置 enableTools: true：

await cline.start({
  prompt: "Read package.json",
  config: {
    providerId: "anthropic",
    modelId: "claude-sonnet-4-6",
    enableTools: true, // required for built-in tools
  },
});

不设置时，Agent 只能访问你通过 config.tools 提供的自定义工具。这一开关在核心包的 README 与测试夹具中都是显式给出的：sdk/packages/core/README.md 与 session.json 夹具 均包含 enableTools: true，说明官方示例与自动化测试都把它当作标准配置项。

cwd 决定内置工具的操作基准目录

bash、editor、read_files 等内置工具都以 config.cwd 为相对路径基准。如果不设置，则退回使用进程工作目录（process.cwd()）。为保证行为可预测（尤其是从不同工作目录启动的服务或容器），应始终显式指定：

config: {
  cwd: "/absolute/path/to/project",
  // ...
}

这是「隐性依赖启动上下文」的典型陷阱：同样的代码在不同部署路径下操作的文件完全不同，显式 cwd 可以消除这类不确定性。

Hub 启动延迟与 backendMode 选择

当 backendMode: "auto" 时，如果本机没有现成的 Hub 守护进程，第一个会话可能需要触发 Hub 守护进程生成（spawn），表现为首次启动较慢。从源码结构看，后端选择发生在 runtime/host/host.ts 的 resolveSessionBackend 中；其测试 host.test.ts 验证了 backendMode: "auto" 时「优先选择兼容的本地 Hub」的行为，以及 local / hub / remote 模式各自的宿主构造路径。

三种应对首次延迟的策略：

• backendMode: "local"：进程内执行，启动最快，适合对延迟敏感的本地集成；
• 预热 Hub：提前执行 cline hub ensure CLI 命令把守护进程拉起来；
• 接受一次性成本：首个会话慢，后续会话复用同一个 Hub。

选择建议取决于你的 SLA：批处理任务适合 local；多应用共享状态、需要会话持久化的服务端集成适合 hub 并预热。

会话存储位置与容器化注意事项

会话数据统一存储在 ~/.cline/data/sessions/，其中包含：

• sessions.db —— 存放会话元数据的 SQLite 数据库；
• [session-id].json —— 每个会话的独立消息历史文件。

在容器或临时环境中运行时要注意：这些路径可能不会在重启后保留。如果历史会话可恢复性是你的功能前提，需要在部署层面把 ~/.cline 挂载为持久卷，或接受「重启即清空」的语义。

requestToolApproval 会阻塞执行

当某工具策略为 autoApprove: false 且你提供了 requestToolApproval 回调时，Agent 主循环会阻塞等待该回调 resolve。如果回调永不返回（例如等待一个永远不会出现的用户输入），整个会话就挂起了。

对无人值守的自动化流水线，二选一：

• 把所有工具设为 autoApprove: true；
• 在审批回调中实现超时（timeout），超时后返回拒绝或默认值。

插件发现路径与加载排查清单

ClineCore 从两个目录自动发现插件：

• 全局：~/.cline/plugins/
• 工作区：.cline/plugins/

对 SDK 使用方，也可以在会话配置中直接传入：extensions: [plugin]（直接传插件对象）或 pluginPaths: ["./path"]（传路径）。

插件加载失败时，按以下清单逐项核对：

1. 文件位于上述发现目录之一，或已通过 extensions / pluginPaths 传入；
2. 文件以默认导出（default export）提供插件对象，且 manifest.capabilities 数组非空;
3. setup() 中的每个 api.register* 调用都有对应的 capability 声明与之匹配；
4. 如果插件对象上带 hooks 字段，capabilities 中必须包含 "hooks"。

第 3、4 条是最常见的静默失败原因：注册了但没声明能力，插件会被视为无效而整体跳过。

extensionContext.workspace 是插件工作区解析的前提

如果插件使用 ctx.workspaceInfo（例如解析工作区相对路径），必须在会话配置中设置 extensionContext.workspace，否则 ctx.workspaceInfo 为 undefined：

await cline.start({
  config: {
    extensions: [myPlugin],
    extensionContext: {
      workspace: { rootPath: process.cwd(), cwd: process.cwd() },
    },
  },
});

CLI 会替用户自动设置这个字段，但 SDK 使用方必须显式提供。这是「IDE/CLI 能跑、SDK 集成就出错」类问题的一个高频来源。

send() 只作用于活跃会话；result 可能为 undefined

两个与「会话是否仍在运行」相关的边界：

1. cline.send() 只对活跃会话有效。 如果会话已经完成，send() 可能返回 undefined 或直接失败。稳妥做法是先 cline.get(sessionId) 检查会话状态再发送（get 对应 ClineCore.ts 中的 getSession 委托）。

2. session.result 可能是 undefined。 会话已启动但尚未完成时（例如非阻塞的 Hub 模式），result 尚未产生，必须做空值判断：

const session = await cline.start({ ... });
if (session.result) {
  console.log(session.result.text);
} else {
  console.log("Session started but not yet complete");
}

长会话与 Compaction（消息压缩）

长时间运行的会话中，消息历史会不断增长，最终超出模型的上下文窗口。ClineCore 通过 compaction 机制处理：把较早的消息总结压缩，腾出上下文空间。通过 compactionConfig 配置：

config: {
  compactionConfig: {
    strategy: "summarize",
    // ...
  },
}

默认策略适用于大多数场景；极长会话（如持续数小时的监控型 Agent）可能需要针对压缩阈值与摘要粒度做调优。压缩相关的实现位于 sdk/packages/core/src/extensions/context/ 目录，仓库中还有专门的压缩测试与脚本（见 sdk/packages/core/package.json 中的 test:live / test:compaction 脚本），可以作为调参时的验证手段。

相关文档

本指南是 Cline SDK 参考体系的一部分，可继续阅读：

• API 完整参考
• 常见集成模式
• 核心包 README 与运行配置
• ClineCore 主类实现
• 后端模式解析与测试

适用前提：本文所有结论以当前仓库中 @cline/core v0.0.82 的源码与文档为准，Node.js 要求、存储路径与插件发现目录均适用于该版本；升级 SDK 后建议重新核对 engines 字段与上述路径约定。