Cline SDK 快速上手：从零跑通 quickstart 最小 Agent 示例并读懂其事件流实现

本文以 Cline 仓库中的 quickstart 示例（apps/examples/quickstart/README.md）为主体，完整继承其环境要求、安装步骤与运行命令，并结合仓库内 sdk/packages/agents/src/agent-runtime.ts 的运行时源码，深入剖析 Agent 的构造参数、assistant-text-delta 事件订阅机制与 agent.run() 的返回结果。读完本篇，你将能够独立搭建一个可流式输出、可统计 token 用量的最小 Cline Agent 程序，并理解其背后的迭代控制与事件模型。

示例定位：Cline SDK 最简入门工程

quickstart 是 Cline 仓库官方给出的“最简 SDK 示例”：它只创建一个 Agent、发送一条提示词，并将响应流式打印到 stdout。示例的原始定义见 apps/examples/quickstart/README.md，全部业务逻辑仅由一个入口文件 apps/examples/quickstart/src/index.ts 承载。

这个示例的价值在于把 SDK 的核心用法压缩到可一屏读完的规模：构造 Agent、订阅事件、调用 run()、读取 result。它是理解 Cline SDK「SDK 作为独立编程接口」这一产品形态的起点——Cline 既是 IDE 扩展和 CLI 助手，也可以以 SDK 形式嵌入你自己的 Node.js 程序。

环境要求与工程配置

运行时版本

README 明确要求使用 Node.js 22 或更新版本。这一点在工程配置中同样得到印证：apps/examples/quickstart/package.json 声明了 "engines": { "node": ">=22" }，依赖项仅有一个工作区依赖 "@cline/sdk": "workspace:*"，说明示例依赖的是仓库内本地构建的 SDK 包，而非 npm 上的独立发行版。

安装与构建 SDK

README 给出的标准流程是两条命令：

bun install
bun run build:sdk

对应到 apps/examples/quickstart/package.json 的 scripts 定义，build:sdk 的实际含义是跳转到仓库根目录执行同名脚本：

"build:sdk": "bun run --cwd ../../.. build:sdk"

也就是说，bun run build:sdk 会在仓库根目录触发 SDK 的构建流程（@cline/sdk 的入口 sdk/packages/sdk/src/index.ts 仅一行 export * from "@cline/core"，即 SDK 包是对核心包的再导出层）。示例本身还提供：

• dev：bun run src/index.ts，用 Bun 直接执行 TypeScript 源码；
• build：tsc，按 apps/examples/quickstart/tsconfig.json 编译到 dist（target: ES2022、module: ESNext、moduleResolution: bundler、strict: true）；
• start：node dist/index.js，以纯 Node.js 方式运行编译产物。

因此该示例同时验证了 Bun 开发链路和 Node 22 生产链路。

API Key 配置

运行前需要设置 Cline 的 API 密钥环境变量：

export CLINE_API_KEY="cline_..."

源码中通过 process.env.CLINE_API_KEY 读取该值并传入 Agent 配置（见 apps/examples/quickstart/src/index.ts）。

完整代码逐行解析

示例入口 apps/examples/quickstart/src/index.ts 全文如下：

import { Agent } from "@cline/sdk";

const agent = new Agent({
	providerId: "cline",
	modelId: "anthropic/claude-sonnet-4.6",
	apiKey: process.env.CLINE_API_KEY,
	maxIterations: 1,
});

agent.subscribe((event) => {
	if (event.type === "assistant-text-delta") {
		process.stdout.write(event.text);
	}
});

const result = await agent.run("Explain what an SDK is in two sentences.");
console.log(
	`\n\nDone (${result.iterations} iteration, ${result.usage.outputTokens} output tokens)`,
);

它完成了 README「What it does」一节描述的四个步骤：

1. 用 provider 与 model 创建一个 Agent；
2. 订阅 assistant-text-delta 事件以流式输出；
3. 调用 agent.run() 传入提示词；
4. 结束后打印 token 用量。

Agent 构造参数

示例采用的是「友好形态」配置。从 sdk/packages/agents/src/agent-runtime.ts 的类型定义可以看到，这种形态（AgentRuntimeConfigWithProvider）支持以下字段：

字段	示例取值	说明
providerId	"cline"	供应商 ID，例如 "anthropic"、"openai"
modelId	"anthropic/claude-sonnet-4.6"	使用的模型 ID
apiKey	process.env.CLINE_API_KEY	供应商/平台的 API 密钥
baseUrl	（示例未用）	自定义 API 地址
headers	（示例未用）	附加请求头
options	（示例未用）	供应商相关的网关选项

源码注释明确指出：该形态「调用方只提供 provider/model ID 与凭据，运行时内部通过 @cline/llms 构建 AgentModel，这是大多数独立用户想要的入口」（见 sdk/packages/agents/src/agent-runtime.ts）。另一条「高级形态」是传入预先构造好的 model 对象（AgentRuntimeConfigWithModel），供 @cline/core 内部复用网关与遥测接线时使用，示例代码无需关心。

maxIterations: 1 控制 Agent 的迭代轮数上限。从 sdk/packages/agents/src/agent-runtime.ts 的主循环可以确认其语义：每一轮迭代会发出 turn-started 事件后推进；当 maxIterations 未设置时视为无限制（测试用例 sdk/packages/agents/src/agent-runtime.test.ts 即断言“未设置的 maxIterations 视为无限”），超限则抛出「Agent runtime exceeded maxIterations」错误（sdk/packages/agents/src/agent-runtime.ts）。quickstart 将其设为 1，意味着模型只允许一次完整往返、禁止工具调用后的多轮推进，从而保证示例只产生一段纯文本回答，行为可预期。

事件订阅：assistant-text-delta

agent.subscribe() 接受一个事件监听回调，回调参数是 AgentRuntimeEvent。示例只拦截 assistant-text-delta 这一种事件类型，把增量文本 event.text 直接写入 stdout，实现打字机式的流式输出。事件类型体系定义在 sdk/packages/shared/src/agent.ts 中；运行时的其他事件（如 turn-started）由 sdk/packages/agents/src/agent-runtime.ts 在每轮迭代开始时发出。若要做终端交互界面，可以基于同样的订阅机制扩展对更多事件类型的处理。

run() 与结果对象

agent.run(prompt) 接受字符串（或消息对象/消息数组，见 sdk/packages/agents/src/agent-runtime.ts 中 AgentRunInput = string | AgentMessage | readonly AgentMessage[] 的定义），返回一个 result 对象。示例打印了其中两个字段：

• result.iterations：本次运行实际消耗的迭代轮数；
• result.usage.outputTokens：输出 token 用量。

这两项正是 quickstart 用来做运行后校验的最小可观测指标。

运行示例

在示例目录下执行：

bun dev

预期行为：终端先流式打印模型对 “Explain what an SDK is in two sentences.” 的回答，结束后另起两行输出形如 Done (1 iteration, N output tokens) 的统计信息。若要验证纯 Node 链路，可执行 bun run build 后再执行 bun start。

后续学习路径

README 的「Notes」一节给出了两条进阶指引，对应仓库中的其他官方示例：

• 交互式终端聊天：apps/examples/cli-agent；
• 自定义工具与结构化工作流：apps/examples/code-review-bot。

小结

quickstart 示例用约 20 行 TypeScript 覆盖了 Cline SDK 的完整调用闭环：new Agent({ providerId, modelId, apiKey, maxIterations }) 构造运行时、subscribe() 消费 assistant-text-delta 流式事件、agent.run() 执行提示词、result.iterations / result.usage 获取运行统计。其工程配置（engines.node >= 22、workspace:* 本地 SDK 依赖、build:sdk 跨目录构建脚本）则展示了该 SDK 示例与 monorepo 源码构建的关系。以这份示例为基线，再逐步叠加工具定义与事件处理，即可成长为可投产的 Cline Agent 程序。