企业官网建设流程全解析

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

【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline

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）：

此外，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判别联合）。常用事件类型与语义：

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抽象，具体实现有三种：

宿主选择逻辑集中在 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的别名从所有包再导出，一次安装拿到全量 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 执行层位于@cline/llms：sdk/packages/llms/src/providers/ 下按 vendor 隔离实现，经 gateway 注册表统一产出 handler；模型目录与能力声明在 sdk/packages/llms/src/catalog/。架构约束明确要求 provider 特有行为不得外泄到 core 层。

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

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

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

• 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 演进方向一致的宿主代码的前提。

【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline