Cline Core SDK 实战：用 @cline/core 构建宿主级 Agent 会话运行时

2026-09-06 17:31:38作者：乔或婵

@cline/core 是 Cline SDK 中的有状态编排层，负责把 Agent 运行时、模型 Provider 配置、存储、默认工具与会话生命周期组装成一个可直接嵌入宿主应用的运行时。本篇基于 sdk/packages/core/README.md 的原始内容，结合仓库源码逐节展开：读完后你将掌握 ClineCore 实例的创建与配置、默认聊天工作区的机制、prepare 会话引导钩子的用法、四种 backendMode 运行时宿主的选择逻辑，以及内置工具与存储层的可复用 API。

包定位：SDK 的有状态编排层

按 README 的定义，@cline/core 的定位是 "stateful orchestration layer of the Cline SDK"，它把以下能力连接成一个 host-ready runtime：

会话生命周期与编排原语（session lifecycle and orchestration primitives）
Provider 设置与账户服务
默认运行时工具与 MCP 集成
基于存储的会话与团队状态辅助能力
面向宿主的 Node 辅助 API（统一从 @cline/core 入口导出）

从 sdk/packages/core/package.json 可以看到该包当前版本为 0.0.82，标题带有 [experimental] 前缀，且 engines 要求 node >= 22。依赖中包含 @cline/agents、@cline/llms、@cline/shared 三个 workspace 包以及 @modelcontextprotocol/sdk、OpenTelemetry 全家桶等，这解释了 README 中 "Related Packages" 一节提到的分层：

@cline/agents：无状态的 Agent 循环与工具原语（agent loop and tool primitives）
@cline/llms：Provider/模型配置与请求处理器

也就是说 @cline/agents 负责"一次无状态推理循环怎么跑"，@cline/llms 负责"怎么和模型通信"，而 @cline/core 负责"会话、工作区、存储、工具、MCP 如何组装并持久化"。架构层面的更多背景可参考 sdk/ARCHITECTURE.md。

安装与入口点

安装方式按 README 给出：

npm install @cline/core

@cline/core 是绝大多数宿主应用的起点（"Most host apps should start with @cline/core"）。除主入口外，sdk/packages/core/package.json 的 exports 字段还声明了几个子路径，供不同场景按需引入：

子路径	对应源码	用途
`.`	src/index.ts	核心契约、共享工具、Node/服务端辅助能力
`./hub`	src/hub/index.ts	Hub 服务端与 WebSocket 运行时相关能力
`./hub/daemon-entry`	src/hub/daemon/entry.ts	Hub 守护进程入口
`./telemetry`	src/services/telemetry/index.ts	OpenTelemetry 遥测适配器
`./services/feature-flags/posthog`	src/services/feature-flags/posthog.ts	PostHog 特性开关 Provider

用 ClineCore 启动第一个会话

README 给出的典型用法如下，这是宿主应用集成 @cline/core 的最小闭环：创建实例、启动一次会话、读取结果、释放资源。

import { ClineCore } from "@cline/core";

const cline = await ClineCore.create({});

const result = await cline.start({
	config: {
		providerId: "anthropic",
		modelId: "claude-sonnet-4-6",
		apiKey: process.env.ANTHROPIC_API_KEY ?? "",
		cwd: process.cwd(),
		mode: "act",
		enableTools: true,
		enableSpawnAgent: false,
		enableAgentTeams: false,
		systemPrompt: "You are a concise assistant.",
	},
	prompt: "Summarize this project.",
	interactive: false,
});

console.log(result.result?.text);
await cline.dispose();

对照源码可以补全几个关键事实：

ClineCore.create() 的工厂实现在 src/ClineCore.ts：它先解析 distinctId 与 capabilities，再调用 createRuntimeHost(...) 选出运行时宿主，最后按 automation 选项决定是否自动启动 cron 服务。
start() 的输入类型是 ClineCoreStartInput（src/cline-core/types.ts），其中 config 为 ClineCoreStartConfig。从 src/types/config.ts 的 CoreSessionConfig 可以看到示例中每个字段的归属：providerId/modelId/apiKey 属于模型配置，enableTools/enableSpawnAgent/enableAgentTeams 属于运行时特性开关（CoreRuntimeFeatures），systemPrompt 是必填项。此外还支持 baseUrl、headers、thinking、reasoningEffort、maxTokensPerTurn、temperature、checkpoint、compaction、hooks、extraTools、pluginPaths、skills 等大量可选配置。
ClineCore.start() 内部先执行 prepare 钩子（若有），再通过 normalizeClineCoreStartInput 拆分 core 配置与 localRuntime 字段，最后交给 host.startSession(...)（src/ClineCore.ts）。
result.result?.text 是一次非交互运行的文本产出；result.subscribe(...) 可用于订阅会话事件流（见下文 API 小节）。

省略 cwd 与 workspaceRoot 时的默认聊天工作区

README 特别指出：当 cwd 与 workspaceRoot 同时省略时，执行宿主会把会话放入共享聊天工作区 <cline-data-dir>/workspaces/chat（默认 ~/.cline/data/workspaces/chat），并预置一份 AGENTS.md 规则文件，告诉 Agent 把当前会话当作聊天处理，只有用户明确要求时才创建命名项目文件夹。宿主应从 result.manifest.cwd 与 result.manifest.workspace_root 读取实际解析后的路径，而不是自行猜测。

源码印证了这一机制，位于 src/services/workspace/chat-workspace.ts：

ensureChatWorkspace() 调用 resolveChatWorkspacePath()（定义于 sdk/packages/shared/src/storage/paths.ts）得到路径，以 0o700 权限创建目录，再用 flag: "wx" 写入 AGENTS.md——即规则文件只在缺失时写入，用户可自行编辑。
预置规则文本（CHAT_WORKSPACE_RULES）的核心指令是：这是多会话共享的工作区而非独立项目；若用户要求写代码，先询问项目放在哪里，无偏好时在此目录下建一个短命名文件夹并在其中完成全部工作，不要假设散落在顶层的文件属于当前会话。
路径解析在 sdk/packages/shared/src/storage/chat-workspace-paths.ts 与配套测试 sdk/packages/shared/src/storage/paths.test.ts 中得到验证：默认解析为 ~/.cline/data/workspaces/chat，且会响应 cline 数据目录的自定义环境变量。
解析发生在执行宿主边界：resolveStartSessionWorkspace() 按"显式 cwd > 显式 workspaceRoot > 共享聊天工作区"的顺序落定两个路径字段。

会话引导：prepare(input) 钩子

README 的 "Session Bootstrap" 一节说明 ClineCore.create(...) 还接受 prepare(input) 选项，适用于宿主需要在每次会话开始前准备工作区作用域运行时状态、然后通过显式 localRuntime 引导字段注入 watcher/extensions/telemetry 输入、同时不扩大共享宿主契约的场景。一个重要的时序约束是：prepare 在执行宿主解析省略工作区之前运行，因此无路径启动（pathless start）时 prepare(input) 看不到 cwd 与 workspaceRoot。

类型定义在 src/cline-core/types.ts：

export interface ClineCoreOptions {
	// ...
	prepare?: (
		input: ClineCoreStartInput,
	) =>
		| Promise<StartSessionBootstrap | undefined>
		| StartSessionBootstrap
		| undefined;
}

export interface StartSessionBootstrap {
	applyToStartSessionInput(
		input: ClineCoreStartInput,
	): Promise<ClineCoreStartInput> | ClineCoreStartInput;
	dispose?(): Promise<void> | void;
}

ClineCore.start() 中的实际调用链（src/ClineCore.ts）是：

调用 this.prepare?.(input) 拿到 StartSessionBootstrap；
若返回了 bootstrap，用 bootstrap.applyToStartSessionInput(input) 改写最终启动输入；
会话启动成功后，bootstrap 记录到 activeSessionBootstraps Map，按 sessionId 持有；
清理时机有三处：宿主发出 ended 事件、显式 stop(sessionId)、实例 dispose()（含 deleteSession 成功后）。

这套机制让宿主可以在不修改 ClineCore 公开契约的前提下，为每个会话附加自定义状态并在会话结束时释放，是嵌入复杂宿主（IDE、TUI、Hub 客户端）时的推荐扩展点。

ClineCore 实例 API：产品方法与运行时原语的映射

README 强调了一个分层设计：ClineCore 是面向应用的会话 API，而更底层的 RuntimeHost 边界使用 startSession、runTurn 这类运行时原语命名，使传输适配器与产品方法 start、send 保持区分。从 src/ClineCore.ts 可以直接看到这种一一映射：

ClineCore 方法	底层 RuntimeHost 原语	说明
`start(input)`	`host.startSession(...)`	启动新会话，先执行 `prepare` 引导
`send(...)`	`host.runTurn(...)`	向活动会话发送消息/工具响应
`abort(sessionId)`	`host.abort(...)`	中止当前工具执行但不结束会话
`stop(sessionId)`	`host.stopSession(...)`	优雅停止会话并清理 bootstrap
`get(sessionId)`	`host.getSession(...)`	读取会话元数据与状态
`list(limit)` / `listHistory(options)`	共享历史列表路径	分页列出近期会话（默认 200 条）
`delete(sessionId)`	`host.deleteSession(...)`	永久删除会话及关联数据
`update(sessionId, ...)`	`host.updateSession(...)`	更新标题等可变元数据
`readMessages(sessionId)`	`host.readSessionMessages(...)`	读取规范消息历史（供 resume/fork/compaction/回放）
`readDisplayMessages(sessionId)`	本地投影	面向 UI 的展示转录，模型侧观测性工具活动投影为普通工具块
`readLiveMessages(sessionId)`	优先活动内存会话	会话驻留本宿主时优先读内存转录，避免漏掉未落盘的进行中回合
`getAccumulatedUsage(sessionId)`	传输支持时生效	累计 token 与费用；`usage` 为根/主 Agent，`aggregateUsage` 含队友与子 Agent
`updateSessionModel(...)` / `updateSessionConnection(...)`	传输支持时生效	活动会话切换模型 / 更新 provider、模型、推理连接选项
`restore(input)`	`host.restoreSession(...)`	按 checkpointRunCount 恢复（可 fork 消息与恢复工作区）
`compareCheckpoint(input)`	`compareCheckpointToWorkspace`	对比 checkpoint 与当前工作区差异
`subscribe(listener)`	`host.subscribe(...)`	订阅会话事件，返回退订函数
`dispose()`	`host.dispose(...)`	释放宿主、连接与所有会话/自动化资源

README 还指出：待处理 prompt 编辑、累计用量查询、活动会话切模型这类"服务型"操作，只在所选传输支持时才通过 ClineCore 暴露（源码中对 getAccumulatedUsage、updateSessionModel 等的实现就是先断言 RuntimeHostServiceExtensions 再兜底 Promise.resolve(undefined)），而非最小宿主原语词汇表的一部分。

运行时宿主与 backendMode：local / hub / remote / auto

README 列出 @cline/core 用于宿主级运行时组装的 API：

ClineCore.create(...)
createRuntimeHost(...)（别名 createSessionHost）
LocalRuntimeHost
HubRuntimeHost 与 RemoteRuntimeHost
DefaultRuntimeBuilder

它们全部从 src/index.ts 导出。宿主选择逻辑集中在 src/runtime/host/host.ts 的 createRuntimeHost，与 ClineCoreOptions.backendMode 的文档说明一致：

"local"：始终使用进程内执行 + 本地 SQLite/文件存储；
"hub"：要求一个可达的 WebSocket Hub 运行时——优先使用 hub.endpoint 显式端点，否则通过 ensureCompatibleLocalHubUrl({ strategy: "require-hub" }) 发现本地兼容 Hub，找不到则抛错 No compatible hub runtime is available.；
"remote"：要求显式 remote.endpoint（否则抛 Remote runtime mode requires remote.endpoint to be configured.），构造 RemoteRuntimeHost；
"auto"（默认）：通过 resolveCompatibleLocalHubUrl({ strategy: "prefer-hub" }) 发现本地 Hub，连上则用 HubRuntimeHost，连接失败或发现不到则记录告警并回退到本地运行时。

几个源码层面的补充事实：

除显式 backendMode 外，环境变量 CLINE_SESSION_BACKEND_MODE（取值 local/hub/remote）也会参与模式解析；设置了 CLINE_VCR 时强制 local（src/runtime/host/host.ts）。
本地后端的创建（createLocalBackend）优先使用 SqliteSessionStore + CoreSessionService；SQLite 初始化失败时回退到基于文件的 FileSessionService，并通过 session_backend_fallback 遥测事件与 captureSdkError 记录降级（src/runtime/host/host.ts）。
auto 模式下若发现不到 Hub，会先 prewarmDetachedHubServer 预温一个分离式 Hub 服务，再回退本地执行，为下一次调用提前铺路。

HubOptions 与 RemoteOptions 的完整字段（endpoint、authToken、strategy: "prefer-hub" | "require-hub"、clientType、displayName、workspaceRoot、cwd）定义在 src/cline-core/types.ts。

内置工具：createBuiltinTools / createDefaultTools / createDefaultExecutors

README 指出 @cline/core 拥有内置宿主工具及其执行器：createBuiltinTools(...)、createDefaultTools(...)、createDefaultExecutors(...)。从 src/index.ts 的工具导出面可以看到这一体系的完整能力，包括：

工具构建：createBuiltinTools、createDefaultTools、createDefaultToolsWithPreset、createShellTool
执行器：createDefaultExecutors、createShellExecutor、createDefaultShellExecutor、createEditorExecutor、createApplyPatchExecutor（配套 computePatchChanges、PATCH_MARKERS、PatchActionType 等 patch 解析类型）
策略与预设：createToolPoliciesWithPreset、ToolPresets、ToolPolicyPresetName
目录与可用性：ALL_DEFAULT_TOOL_NAMES、DefaultToolNames、getCoreBuiltinToolCatalog、getCoreHeadlessToolNames、getCoreDefaultEnabledToolIds、resolveCoreSelectedToolIds、isCoreBuiltinToolAvailable
命令输出治理：truncateCommandOutput、MAX_COMMAND_OUTPUT_CHARS、CommandExitError、StructuredCommandInputSchema

这意味着宿主既可以直接使用默认工具集，也可以按 preset 裁剪、按名称解析可用工具，或替换 shell/patch 执行器实现自己的沙箱策略（包内另有 SubprocessSandbox 一类原语可配合使用）。

存储与设置辅助

README "Storage and Settings" 一节列出的导出均可在 src/index.ts 中找到对应实现：

ProviderSettingsManager：Provider 设置的持久化管理（src/services/storage/provider-settings-manager.ts），并配套 migrateLegacyProviderSettings 做旧格式迁移；
CoreSettingsService 与 createCoreSettingsService：面向核心设置项（规则、工具开关、插件禁用等）的服务（src/settings/index.ts）；
MCP 设置辅助：setMcpServerDisabled、loadMcpSettingsFile、updateMcpSettingsFile、probeMcpServerConnection、InMemoryMcpManager、authorizeMcpServerOAuth、resolveDefaultMcpSettingsPath 等（导出自 src/extensions/mcp），覆盖 MCP 设置的读取、修改、连接探测与 OAuth 状态管理；
SqliteTeamStore：基于 SQLite 的 Agent 团队状态存储（src/services/storage/team-store.ts）；
SqliteSessionStore：SQLite 会话存储，配合上文提到的文件存储回退机制。

ClineCoreOptions：创建实例时可注入什么

结合 src/cline-core/types.ts 的完整 JSDoc，ClineCore.create(options) 的常用选项包括：

选项	作用
`clientName`	客户端可读名称，用于遥测与日志中标识消费者
`distinctId`	机器/用户稳定标识；缺省取系统 machine ID，再回退到持久化在 `~/.cline/data/machine-id` 的生成值
`backendMode`	`auto`（默认）/`hub`/`remote`/`local`，控制运行时宿主选择
`hub` / `remote`	Hub 与远程 Hub 的连接选项（端点、token、策略、工作区路径等）
`capabilities`	客户端拥有的运行时能力（如交互行为处理器），core 会将其适配到所选后端，使应用只需实现一次
`telemetry`	遥测服务实例；省略时遥测为 no-op
`featureFlags`	特性开关服务；省略时使用 no-op provider 与默认值
`logger`	结构化日志，用于宿主选择与回退等运行诊断
`toolPolicies`	逐工具审批策略：自动运行 / 需用户确认 / 完全阻止
`messagesArtifactUploader`	`messages.json` 落盘后的钩子，可将转录镜像到远端存储
`automation`	开启基于文件与事件的自动化（cron），开启后通过 `cline.automation.*` 使用
`fetch`	自定义 `fetch` 注入本地会话的 AI gateway provider（代理、重试、测试桩等）；hub/remote 运行时需在 gateway 所在进程配置
`prepare`	上文详述的会话引导钩子
`sessionService`	内部选项：直接注入已构造的会话后端，用于测试或嵌入自定义持久层

automation 选项背后是 src/cron 体系：启用后 ClineCore 构造 CronService（可配置 cronSpecsDir、cronScope: global/user/workspace、dbPath、轮询与租约参数），并通过 cline.automation 暴露 start/stop/reconcileNow/ingestEvent/listSpecs/listRuns/listEvents API（src/cline-core/types.ts），支撑定时任务与事件驱动的任务编排。

检查点与压缩：会话安全与上下文治理

虽然 README 未展开这两项，但它们直接体现在 ClineCoreStartConfig（src/types/config.ts）中，是集成时经常用到的配置：

checkpoint: { enabled?: boolean; createCheckpoint?: (ctx) => ... }：git 式检查点默认关闭（opt-in），启用后每次根 Agent run 开始时捕获可回滚的工作区快照；也可用自定义 createCheckpoint 完全替换内置 git stash/ref 逻辑。cline.restore(...) 与 cline.compareCheckpoint(...) 即基于这些 checkpoint 工作。
compaction：支持 strategy: "basic" | "agentic"、preserveRecentTokens、独立 summarizer 模型配置与自定义 compact 实现，用于长会话的上下文压缩。

小结

@cline/core 的价值在于把"跑一次模型"升级为"管理一个会话"：ClineCore.create() 按 backendMode 选出 local/hub/remote 运行时宿主，start() 完成 prepare 引导、配置拆分与 workspace 解析（含默认聊天工作区），send/abort/stop/subscribe 提供完整的会话控制面，而 createDefaultTools、ProviderSettingsManager、SqliteSessionStore 等导出让宿主既能开箱即用，也能逐层替换执行器、存储与传输。理解 ClineCore（产品 API）与 RuntimeHost（startSession/runTurn 原语）的边界，以及 localRuntime 字段与 prepare 钩子的分工，是正确集成这个实验性但能力完整的编排层的关键。