Cline SDK 实战指南：用 TypeScript 构建可自主行动的 AI 编码 Agent

Cline SDK 是 Cline 项目的引擎级能力封装：它将原本驱动 Cline IDE 扩展与 CLI 的 agent 运行时打包成一套可嵌入的 TypeScript 库，让你只需十几行代码就能构建出会编辑文件、执行 shell 命令、浏览网页并调用任意自定义工具的智能体。读完本篇，你将掌握从 Agent 最小可用循环、createTool 自定义工具、流式事件订阅，到 ClineCore 完整运行时（会话持久化、内置工具、配置发现）的完整构建路径，并能对照源码理解每一层抽象背后的实现机制。

一、Cline SDK 定位：同一引擎，三种形态

Cline 本身既是 IDE 扩展、又是 CLI 助手，而 SDK 把驱动这些形态的核心引擎开放出来。sdk/README.md 的开篇定义很直接：

The Cline SDK is a TypeScript framework for building AI agents that can edit files, run shell commands, browse the web, call APIs, and use any custom tool you give them.

也就是说，SDK 的卖点是"LLM 能采取行动（take actions），而不仅仅是生成文本"。它适合做编码 Agent、Slack Bot、定时自动化、代码审查流水线、多 Agent 团队，以及 IDE 集成。仓库中 apps/ 与 sdk/examples/ 下的示例项目即为佐证。

二、快速开始：安装与最小 Agent

安装

npm install @cline/sdk

@cline/sdk 并不是一个独立实现，而是 @cline/core 的别名：sdk/packages/sdk/src/index.ts 的全部内容只有一行 export * from "@cline/core"。因此一次安装即可拿到全量 API，这也是 README 中"install this one"的由来。

最小示例

import { Agent } from "@cline/sdk"

const agent = new Agent({
  providerId: "cline",
  modelId: "openai/gpt-5.5",
  systemPrompt: "You are a helpful coding assistant.",
  tools: [],
})

const result = await agent.run("Create a REST API with Express and TypeScript")
console.log(result.text)

如 README 所述：agent 会流式输出响应、按需调用你提供的工具，并在任务完成后返回 AgentRunResult。

源码视角：Agent 到底是什么

Agent 由 @cline/agents 包导出。从 sdk/packages/agents/src/index.ts 的导出注释可以看到，Agent 与 AgentRuntime 是同一个类的两个名字：

• Agent / createAgent：友好形态，你提供 providerId / modelId 与凭据，运行时内部通过 @cline/llms 网关构建 AgentModel；
• AgentRuntime / createAgentRuntime：高级模式，你直接传入预构建的 AgentModel，供 @cline/core 这类需要复用网关/遥测接线的场景使用。

这一区分在 sdk/packages/agents/src/agent-runtime.ts 中体现为两个配置变体 AgentRuntimeConfigWithModel 与 AgentRuntimeConfigWithProvider 的判别联合。

运行时还暴露了一组对宿主很有用的方法（见 agent-runtime.ts）：

方法	作用
run(input)	发起一轮任务（input 可为字符串或消息数组）
continue(input?)	在既有会话上继续对话
abort(reason?)	中止当前运行，并向遥测上报 task.cancelled 事件
subscribe(listener)	订阅运行时事件，返回退订函数
snapshot()	获取状态快照（iteration、usage、lastError 等）
restore(messages)	用新消息替换会话，保留工具、hooks、插件与订阅者

此外，toolExecution 配置默认为 "sequential"（顺序执行工具），运行器内置上下文窗口溢出恢复逻辑——当 provider 报告超窗且存在可压缩的历史时会自动压缩重试一次，失败时抛出带有明确提示文案的 ContextWindowOverflowError（见 agent-runtime.ts 中三组恢复失败文案常量）。

三、有状态 Agent：run / continue 与多轮会话

Agent 实例天然携带会话内存。README 给出的 Slack Bot 示例演示了典型用法——每个线程一个 agent，首次用 run，之后用 continue：

// Slack bot: each thread gets its own agent with conversation memory
const agents = new Map<string, Agent>()

async function handleMessage(threadId: string, message: string) {
  let agent = agents.get(threadId)
  if (!agent) {
    agent = new Agent({
      providerId: "gemini",
      modelId: "gemini-3.1-pro-preview",
      systemPrompt: "You are a concise Slack assistant.",
      tools: [],
    })
    agents.set(threadId, agent)
  }

  const result = agent.hasRun
    ? await agent.continue(message)
    : await agent.run(message)

  return result.text
}

从源码看，run 与 continue 内部都走同一个 execute(input) 路径（agent-runtime.ts#L536-L542），差异在于业务语义：hasRun 标记该实例是否执行过任务，据此决定走首轮还是续轮。由于对话历史保存在实例内部状态（state.messages）中，无需额外存储即可实现多轮记忆；若历史需持久化，则应升级到下一节的 ClineCore。

四、自定义工具：createTool

工具是 agent 与外界交互的方式。一个工具由名称、给模型看的描述、输入 JSON Schema 和执行函数四要素组成：

import { createTool } from "@cline/sdk"

const deploy = createTool({
  name: "deploy",
  description: "Deploy the app to staging or production.",
  inputSchema: {
    type: "object",
    properties: {
      environment: { type: "string", enum: ["staging", "production"] },
    },
    required: ["environment"],
  },
  execute: async (input) => {
    const result = await runDeployment(input.environment)
    return { url: result.url, status: "success" }
  },
})

const agent = new Agent({
  providerId: "moonshot",
  modelId: "kimi-k2.5",
  systemPrompt: "You are a deployment assistant.",
  tools: [deploy],
})

agent 依据 description 自主决定何时调用工具，看到返回值后会将其纳入后续推理。

源码视角：createTool 的默认值与校验

完整实现位于 sdk/packages/shared/src/tools/create.ts，值得注意的细节：

• 双输入形态：inputSchema 既接受原始 JSON Schema 对象，也接受 Zod schema（内部经 zodToJsonSchema 转换，并剥离会干扰严格校验器的 $schema 元键）；
• 对象形状强校验：顶层 oneOf / anyOf 的每个分支、allOf 中至少一个分支必须声明 type: "object"，否则在注册期直接抛错——把 provider 会拒绝的非法 schema 问题提前暴露到开发期；
• 执行语义默认值：timeoutMs 默认 30_000（30 秒）、retryable 默认 true、maxRetries 默认 3。这意味着你的 execute 函数默认会在失败时自动重试，写副作用工具时应知悉此行为。

内置工具（bash、read_files、apply_patch、editor 等）的 JSON Schema 定义集中在 sdk/packages/core/src/extensions/tools/definitions.ts，可作为编写自有工具时 schema 严谨度的参考。

五、流式事件：onEvent 实时可观测

执行期间的每一类事件都可实时观测。通过构造参数 onEvent 订阅：

const agent = new Agent({
  providerId: "anthropic",
  modelId: "claude-opus-4-7",
  systemPrompt: "You are a helpful assistant.",
  tools: [myTool],
  onEvent: (event) => {
    switch (event.type) {
      case "content_update":
        if (event.contentType === "text") process.stdout.write(event.text)
        break
      case "content_start":
        if (event.contentType === "tool") console.log(`\n[${event.toolName}]`)
        break
      case "usage":
        console.log(`\ntokens: ${event.inputTokens} in, ${event.outputTokens} out`)
        break
    }
  },
})

事件契约定义在 @cline/shared（如 sdk/packages/shared/src/agents/types.ts 中的 AgentRuntimeEvent 判别联合）。常用事件类型与语义：

事件	语义
content_update（contentType: "text"）	文本增量，适合逐字渲染
content_start（contentType: "tool"）	工具调用开始，携带 toolName
usage	token 用量上报（inputTokens / outputTokens）
run.started / done 类事件	运行边界，供 Hub 侧客户端可靠地关闭流式/加载状态

onEvent 与 subscribe(listener) 是两条等价的事件通道：前者在构造时静态声明，后者支持运行期动态订阅/退订，多客户端场景下更灵活。

六、插件（Extensions）：复用能力与生命周期挂钩

插件将可复用能力封装为扩展：可以注册工具、观察生命周期事件、修改 agent 行为。README 给出的度量插件示例：

const metrics: AgentPlugin = {
  name: "metrics",
  manifest: { capabilities: ["tools", "hooks"] },

  setup(api) {
    api.registerTool(myCustomTool)
  },

  hooks: {
    beforeRun() {
      console.time("agent")
    },

    beforeTool({ toolCall }) {
      console.log(`tool: ${toolCall.toolName}`)
    },

    afterRun({ result }) {
      console.timeEnd("agent")
      console.log(`${result.iterations} iterations, ${result.usage.outputTokens} tokens`)
    },
  },
}

注意两个 API 命名细节：

1. 公开类型名是 AgentPlugin，它其实是 AgentExtension 的对外别名——sdk/packages/core/src/index.ts 中有 AgentExtension as AgentPlugin // Public-facing alias for extensions。写插件文档或代码时二者等价。
2. hooks 契约与 hook 引擎位于 @cline/shared（sdk/packages/shared/src/hooks/），而 hook 的文件式发现、子进程执行（如外部脚本 hook）位于 sdk/packages/core/src/hooks/hook-file-hooks.ts 与 subprocess-runner.ts。

架构文档对扩展系统的设计原则是"扩展注册运行时贡献（register runtime contributions），hooks 拦截生命周期阶段（intercept lifecycle stages）"，增量行为应走这两个扩展点而非在宿主里写特判（见 sdk/ARCHITECTURE.md 的 Design Seam 8）。仓库提供了大量可运行插件示例：sdk/examples/plugins/（遥测、Web 搜索、环境拦截、自定义压缩策略、macOS 通知等），以及 sdk/examples/plugins/agents-squad/ 的子 agent 编队（spawn 后台 agent、技能预设、跨 agent 交接）。

七、ClineCore：完整运行时

当你需要会话持久化、内置工具、配置发现与多进程支持时，使用 ClineCore 而非裸 Agent：

import { ClineCore } from "@cline/sdk"

const cline = await ClineCore.create({ clientName: "my-app" })

const session = await cline.start({
  prompt: "Set up CI with GitHub Actions",
  config: {
    providerId: "anthropic",
    modelId: "claude-sonnet-4-6",
    apiKey: process.env.ANTHROPIC_API_KEY,
    cwd: "/path/to/project",
    enableTools: true,
  },
})

console.log(session.result?.text)

ClineCore 相比 Agent 多提供的能力（README 原文）：

• 内置工具：bash、editor、read_files、apply_patch、search、fetch_web；
• 会话持久化：SQLite 存储，支持跨进程恢复；
• 配置发现：自动发现 .cline/ 目录下的 rules、skills、plugins 等文件化配置（由 core 的 config watcher 体系加载，见 sdk/packages/core/src/extensions/config/）；
• RPC sidecar：可选连接 Hub 守护进程，实现定时 agent 与跨进程会话管理。

聊天工作区默认行为

README 特别说明了工作区路径的默认解析规则，这在嵌入 SDK 时必须知道：

• 若同时省略 cwd 与 workspaceRoot，执行宿主会把会话放入共享聊天工作区 <cline-data-dir>/workspaces/chat（默认 ~/.cline/data/workspaces/chat）；
• 该工作区会预置一个 AGENTS.md 规则文件，指示 agent 把会话当纯聊天处理，仅在用户明确要求时才创建命名项目目录；
• session.manifest 中返回的路径是权威解析后的工作区路径，客户端不应自行推断远程运行时的本地路径。

这一行为在架构文档 sdk/ARCHITECTURE.md 的"Workspace bootstrap"一节中得到印证：工作区引导由执行会话的运行时负责，Hub 客户端会原样透传被省略的 cwd/workspaceRoot，由 hub 侧执行宿主在自己文件系统上完成落位。

源码视角：RuntimeHost 执行边界

ClineCore 本身不区分本地还是 Hub 模式——它统一委托给 RuntimeHost 抽象，具体实现有三种：

实现	场景
LocalRuntimeHost	进程内执行
HubRuntimeHost	连接本机共享 Hub 守护进程
RemoteRuntimeHost	连接显式远程 Hub 端点

宿主选择逻辑集中在 sdk/packages/core/src/runtime/host.ts，而本地启动引导（bootstrap）在 sdk/packages/core/src/services/local-runtime-bootstrap.ts 中组装工具、hooks、扩展、指令 watcher 与遥测后交给 DefaultRuntimeBuilder。理解这条链路后，你就能解释"为什么 CLI、IDE 扩展、桌面应用行为一致"：三者最终都汇聚到同一套 @cline/agents 的无状态 agent 循环。

八、包分层：按需取用

SDK 是一个分层栈，可以只用其中一部分。README 的官方对照表：

包	职责
@cline/sdk	一站式入口，装这一个即可
@cline/core	会话、持久化、内置工具、配置发现、RPC
@cline/agents	无状态 agent 循环，工具执行与流式
@cline/llms	LLM provider 网关（Anthropic、OpenAI、Google、Bedrock、Mistral 等）
@cline/shared	类型、工具创建辅助、hook 引擎

@cline/sdk 作为 @cline/core 的别名从所有包再导出，一次安装拿到全量 API；若你只想控制最小依赖面，可直接安装单个包。

sdk/ARCHITECTURE.md 中的分层依赖图进一步明确了单向依赖规则：

@cline/shared  ←  @cline/llms  ←  @cline/agents  ←  @cline/core  ←  宿主应用

关键设计约束：@cline/agents 必须保持无状态（不持有会话持久化、provider 设置存储、RPC 生命周期等）；@cline/core 是面向应用的编排层；provider 特有行为必须隔离在 @cline/llms 内，不扩散到 core 或宿主应用。如果你要深入某个包，各包自带 README（如 sdk/packages/core/README.md、sdk/packages/llms/README.md）。

九、CLI：终端里的完整 SDK

Cline CLI 提供对完整 SDK 的终端访问（CLI 实现位于 apps/cli/）：

# 交互式 agent
cline

# 单条提示
cline "Refactor the auth module to use JWT"

# 创建一个每日 9 点（工作日）运行的定时 agent
cline schedule create "PR summary" --cron "0 9 * * MON-FRI" --prompt "Summarize open PRs"

# 连接通过 @BotFather 创建的 Telegram Bot
cline connect telegram -k "$TELEGRAM_BOT_TOKEN"
# 然后在 Telegram 里给 bot 发送 /help 或 /start

Telegram 连接器的具体行为（消息解析、格式约定）详见仓库内文档 apps/cli/src/connectors/adapters/telegram.md，其实现位于同目录的 telegram.ts。

定时任务在架构上由 @cline/core 的文件式自动化子系统（sdk/packages/core/src/cron/）支撑：Markdown + YAML frontmatter 的 spec 文件经 reconciler 解析入库，统一走 cron_runs 队列执行；spec 示例可参考 sdk/examples/cron/（每日代码审查、依赖检查、性能基线等）。

十、模型提供商支持

开箱即用的 provider 对照表（README 原文）：

Provider	模型
Anthropic	Claude Opus 4.7、Sonnet 4.6、Haiku 4.5
OpenAI	GPT-5.5、GPT-5.3 Codex
Google	Gemini 3.1 Pro Preview、Gemini 3 Flash Preview
AWS Bedrock	Claude、Llama
Mistral	Mistral Large、Codestral
任意 OpenAI 兼容	vLLM、Together、Fireworks、Groq 等

provider 执行层位于 @cline/llms：sdk/packages/llms/src/providers/ 下按 vendor 隔离实现，经 gateway 注册表统一产出 handler；模型目录与能力声明在 sdk/packages/llms/src/catalog/。架构约束明确要求 provider 特有行为不得外泄到 core 层。

十一、示例与配套文档索引

README 指向的可运行示例（相对仓库根目录的路径）：

示例	说明
Plugins	带工作区感知上下文、生命周期 hooks 与分支级安全策略的自定义工具
Subagent Orchestration	spawn 并管理后台 agent，含预设、技能与跨 agent 交接
Hooks	文件式与运行时 hooks：日志、审查门禁、上下文注入、生命周期自动化
Cron Automations	定时与事件驱动的自动化 spec，用于质量检查与 PR 工作流
Desktop App	Tauri 桌面外壳 + Bun sidecar 后端 + Next.js UI
VS Code Extension App	通过 RPC 运行时跑 Cline 会话的 VS Code 扩展示例

仓库内另有与本文主题对应的结构化文档（可深入阅读）：

• docs/sdk/overview.mdx — SDK 总览
• docs/sdk/clinecore.mdx — ClineCore 参考
• docs/sdk/tools.mdx — 工具体系
• docs/sdk/events.mdx — 事件参考
• docs/sdk/model-providers.mdx — 模型提供商
• docs/sdk/plugins.mdx 与 docs/sdk/plugin-examples.mdx — 插件编写与示例
• docs/sdk/architecture/overview.mdx — 架构设计
• docs/sdk/reference/agent.mdx、docs/sdk/reference/gateway.mdx — API 参考

另外，如果你用编码 agent（Claude Code、Codex、Cline 等）来搭建应用，README 推荐安装 Cline SDK skill 让 agent 获得 SDK API 与最佳实践上下文：

npx skills add cline/sdk-skill

然后可以直接让它 scaffold agent、创建自定义工具、接线插件与配置 provider。

十二、小结：选 Agent 还是选 ClineCore

• 无状态、轻依赖、单进程：直接 new Agent(...)（@cline/agents 层），会话内存由实例自持，配合 createTool 与 onEvent 即可覆盖大多数 Bot 与脚本场景；
• 要持久化、要内置工具、要跨进程/定时：上 ClineCore（@cline/core 层），获得 SQLite 会话持久化、.cline/ 配置发现、内置工具集与 Hub 多进程支持；
• 只想要某一层：按 shared → llms → agents → core 的单向分层按需安装，避免引入不需要的运行时。

分层清晰、扩展点明确（config watcher、runtime builder、RuntimeHost 边界、settings 变更边界、hooks/插件），是这套 SDK 能同时支撑 CLI、IDE 扩展与桌面应用的关键——理解这些设计接缝（见 sdk/ARCHITECTURE.md），是写出与 SDK 演进方向一致的宿主代码的前提。