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

Cline SDK 实战指南用 TypeScript 构建可自主行动的 AI 编码 Agent【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/clineCline 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/sdkcline/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网关构建AgentModelAgentRuntime/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 中三组恢复失败文案常量。三、有状态 Agentrun/continue与多轮会话Agent实例天然携带会话内存。README 给出的 Slack Bot 示例演示了典型用法——每个线程一个 agent首次用run之后用continue// Slack bot: each thread gets its own agent with conversation memory const agents new Mapstring, 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_00030 秒、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_updatecontentType: text文本增量适合逐字渲染content_startcontentType: tool工具调用开始携带toolNameusagetoken 用量上报inputTokens/outputTokensrun.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 命名细节公开类型名是AgentPlugin它其实是AgentExtension的对外别名——sdk/packages/core/src/index.ts 中有AgentExtension as AgentPlugin // Public-facing alias for extensions。写插件文档或代码时二者等价。hooks 契约与 hook 引擎位于cline/sharedsdk/packages/shared/src/hooks/而 hook 的文件式发现、子进程执行如外部脚本 hook位于 sdk/packages/core/src/hooks/hook-file-hooks.ts与subprocess-runner.ts。架构文档对扩展系统的设计原则是扩展注册运行时贡献register runtime contributionshooks 拦截生命周期阶段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而非裸Agentimport { 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会话、持久化、内置工具、配置发现、RPCcline/agents无状态 agent 循环工具执行与流式cline/llmsLLM 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终端里的完整 SDKCline 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 或 /startTelegram 连接器的具体行为消息解析、格式约定详见仓库内文档 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模型AnthropicClaude Opus 4.7、Sonnet 4.6、Haiku 4.5OpenAIGPT-5.5、GPT-5.3 CodexGoogleGemini 3.1 Pro Preview、Gemini 3 Flash PreviewAWS BedrockClaude、LlamaMistralMistral Large、Codestral任意 OpenAI 兼容vLLM、Together、Fireworks、Groq 等provider 执行层位于cline/llmssdk/packages/llms/src/providers/ 下按 vendor 隔离实现经 gateway 注册表统一产出 handler模型目录与能力声明在 sdk/packages/llms/src/catalog/。架构约束明确要求 provider 特有行为不得外泄到 core 层。十一、示例与配套文档索引README 指向的可运行示例相对仓库根目录的路径示例说明Plugins带工作区感知上下文、生命周期 hooks 与分支级安全策略的自定义工具Subagent Orchestrationspawn 并管理后台 agent含预设、技能与跨 agent 交接Hooks文件式与运行时 hooks日志、审查门禁、上下文注入、生命周期自动化Cron Automations定时与事件驱动的自动化 spec用于质量检查与 PR 工作流Desktop AppTauri 桌面外壳 Bun sidecar 后端 Next.js UIVS 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 参考另外如果你用编码 agentClaude 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 与脚本场景要持久化、要内置工具、要跨进程/定时上ClineCorecline/core层获得 SQLite 会话持久化、.cline/配置发现、内置工具集与 Hub 多进程支持只想要某一层按shared → llms → agents → core的单向分层按需安装避免引入不需要的运行时。分层清晰、扩展点明确config watcher、runtime builder、RuntimeHost 边界、settings 变更边界、hooks/插件是这套 SDK 能同时支撑 CLI、IDE 扩展与桌面应用的关键——理解这些设计接缝见 sdk/ARCHITECTURE.md是写出与 SDK 演进方向一致的宿主代码的前提。【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考