cline-sdk

Cline SDK 技能

使用 Cline SDK 构建 AI Agent 的综合技能。通过以下决策树找到合适的入口和 API 范围，然后加载详细参考资料。

关键规则

在所有 Cline SDK 代码中遵循以下规则：

1. 使用 npm install @cline/sdk 安装。@cline/sdk 包重新导出的是 @cline/core，而不是每个子包。Core 会重新导出公共 SDK 接口，例如 ClineCore、Agent、createAgentRuntime、createTool、内置工具辅助函数、提供方辅助函数和 Llms 命名空间。仅当需要 Core 未重新导出的 API（例如 AgentRuntime、createAgent 或某些底层类型）时，才从 @cline/agents、@cline/llms 或 @cline/shared 导入。
2. 需要 Node.js 22 或更高版本。
3. 使用 @cline/sdk（或 @cline/shared）中的 createTool() 定义工具。工具名称必须采用 snake_case。
4. 如果 Agent 可以恢复，优先让工具的 execute 函数返回结构化错误数据。直接使用 Agent 时，抛出的工具错误会转换为错误工具结果；ClineCore 也可以将重复的工具调用失败计入其错误限制处理。
5. 对应当结束 Agent 循环的工具（例如“提交答案”工具），使用 lifecycle: { completesRun: true }。
6. 使用 ClineCore 时，完成后务必调用 dispose() 以清理资源。
7. 直接使用的 Agent 和 ClineCore 具有不同的事件系统。对于 Agent：使用 agent.subscribe() 获取 AgentRuntimeEvent 类型，文本流式事件为 "assistant-text-delta"，结果文本为 result.outputText。对于 ClineCore：使用 cline.subscribe() 获取 CoreSessionEvent 类型。从 "agent_event" 载荷（content_start、content_update、content_end、done）中渲染面向用户的文本、推理和工具活动。将 "chunk" 事件视为原始传输数据块，其格式为 { stream, chunk, ts }，而不是带类型的文本增量。ClineCore 的结果文本为 result.text。AgentRuntimeConfig 上没有顶层 onEvent 字段；请改用 agent.subscribe() 或 hooks.onEvent。不要在 agent.subscribe() 中使用 "content_update" 或 "content_start"；这些是宿主端的 AgentEvent 类型，由 ClineCore 的 agent_event 事件承载。
8. 对于直接使用的 Agent，plugins 是简单的运行时插件，其 setup(context) 会返回 { tools, hooks }。对于 ClineCore，extensions 是 AgentPlugin 对象，包含 manifest、setup(api, ctx) 和可选的 hooks。不要在直接使用的 Agent.plugins 中使用 ClineCore 插件示例。
9. 插件技能以文件形式提供，不通过注册添加。没有 registerSkill()，也没有 api.registerSkill。插件应将技能作为 SKILL.md 文件放在 <package>/skills/<name>/SKILL.md 下（必须采用此包结构）；宿主会自动发现这些文件，并将其显示为 /slash-commands——不要为技能调用 registerCommand。插件 MCP 服务使用 "mcp" 能力，通过 api.registerMcpServer() 注册。已配置的 Agent（Agent 配置文件）是 .cline/agents/ 中的 YAML 文件；当 enableSpawnAgent 为 true 时，这些文件会作为 subagent_<name> 工具加载。

如何使用此技能

参考文件结构

两个主要 API 接口（Agent 和 ClineCore）均采用 4 文件模式。跨领域概念则使用单文件指南。

./references/<api>/ 中的每个主要 API 接口都包含：

文件	用途	阅读时机
REFERENCE.md	概述、适用场景、快速入门	始终首先阅读
api.md	完整 API：类、方法、配置、类型	编写代码时
patterns.md	常见模式、最佳实践	实施参考
gotchas.md	陷阱、限制、调试	排查问题时

./references/<concept>/ 中的跨领域概念以 REFERENCE.md 作为入口。

阅读顺序

1. 先阅读所选 API 接口对应的 REFERENCE.md
2. 然后阅读与任务相关的其他文件：
   • 编写 Agent 代码 -> api.md
   • 常见模式 -> patterns.md
   • 创建工具 -> tools/REFERENCE.md
   • 添加插件/钩子 -> plugins/REFERENCE.md
   • 配置大模型提供商 -> providers/REFERENCE.md
   • 流式传输事件 -> events/REFERENCE.md
   • 部署到生产环境 -> production/REFERENCE.md
   • 调度 Agent -> scheduling/REFERENCE.md
   • 多 Agent 编排 -> multi-agent/REFERENCE.md
   • 调试 -> gotchas.md

示例路径

./references/agent/REFERENCE.md           # Start here for lightweight agents
./references/clinecore/REFERENCE.md       # Start here for full runtime
./references/agent/api.md                 # Agent class, config, methods
./references/tools/REFERENCE.md           # Creating and using tools
./references/plugins/REFERENCE.md         # Plugin system
./references/providers/REFERENCE.md       # LLM provider configuration

快速决策树

“我应该使用哪个 API 接口？”

Which API?
+-- I want a simple, in-memory agent with custom tools
|   +-- agent/ (Agent class from @cline/agents, re-exported by @cline/sdk)
+-- I need session persistence, built-in tools, config discovery
|   +-- clinecore/ (ClineCore from @cline/core)
+-- I want built-in file/shell/search/web tools
|   +-- clinecore/ (has built-in tools; Agent does not)
+-- I want scheduled or recurring agents
|   +-- clinecore/ (automation API)
+-- I need multi-process or multi-client session sharing
|   +-- clinecore/ (hub-backed runtime)
+-- I'm building a browser-compatible agent
|   +-- agent/ (no Node.js dependencies)

“我需要创建工具”

Tools?
+-- Define a custom tool with schema -> tools/REFERENCE.md
+-- Use built-in tools (read_files, search_codebase, run_commands, etc.) -> tools/REFERENCE.md (built-in section)
+-- Control tool approval/policies -> tools/REFERENCE.md (policies section)
+-- Tool that ends the agent loop -> tools/REFERENCE.md (completion tools)
+-- Package tools as a reusable plugin -> plugins/REFERENCE.md

“我需要处理事件”

Events?
+-- Stream text/reasoning in real time -> events/REFERENCE.md
+-- Track token usage and costs -> events/REFERENCE.md
+-- Watch tool calls -> events/REFERENCE.md
+-- Detect completion/errors -> events/REFERENCE.md
+-- Hook into lifecycle stages -> plugins/REFERENCE.md

“我需要配置模型提供商”

Providers?
+-- Anthropic (Claude) -> providers/REFERENCE.md
+-- OpenAI (GPT) -> providers/REFERENCE.md
+-- Google (Gemini/Vertex) -> providers/REFERENCE.md
+-- AWS Bedrock -> providers/REFERENCE.md
+-- Mistral -> providers/REFERENCE.md
+-- OpenAI-compatible (vLLM, Together, etc.) -> providers/REFERENCE.md
+-- Custom/self-hosted provider -> providers/REFERENCE.md

“我需要插件或钩子”

Plugins?
+-- Package tools + hooks together -> plugins/REFERENCE.md
+-- Observe tool calls (logging, metrics) -> plugins/REFERENCE.md
+-- Intercept lifecycle events -> plugins/REFERENCE.md
+-- Add system prompt rules -> plugins/REFERENCE.md
+-- Expose an MCP server's tools -> plugins/REFERENCE.md (MCP servers)
+-- Bundle reusable skills (SKILL.md, auto slash commands) -> plugins/REFERENCE.md (bundled skills)
+-- Distribute via npm/git -> plugins/REFERENCE.md

“我需要进行多 Agent 协作”

Multi-agent?
+-- Run one-off delegated sub-agents -> multi-agent/REFERENCE.md (sub-agents)
+-- Predefined named sub-agents from files -> multi-agent/REFERENCE.md (configured agents)
+-- Persistent cross-session teams -> multi-agent/REFERENCE.md (teams)
+-- Parent-child delegation -> multi-agent/REFERENCE.md (sub-agents)
+-- Peer-to-peer task board -> multi-agent/REFERENCE.md (teams)

“我需要调度或自动化”

Scheduling?
+-- Recurring cron jobs -> scheduling/REFERENCE.md
+-- One-off scheduled tasks -> scheduling/REFERENCE.md
+-- Event-driven triggers -> scheduling/REFERENCE.md
+-- CLI schedule management -> scheduling/REFERENCE.md

“我需要部署到生产环境”

Production?
+-- Error handling and status checks -> production/REFERENCE.md
+-- Cost control and token limits -> production/REFERENCE.md
+-- Observability (OpenTelemetry) -> production/REFERENCE.md
+-- Security and sandboxing -> production/REFERENCE.md
+-- Deployment patterns -> production/REFERENCE.md

故障排查索引

• Agent 循环未停止 -> tools/REFERENCE.md（完成工具）
• 工具错误导致 Agent 崩溃 -> agent/gotchas.md 或 clinecore/gotchas.md
• 提供商身份验证失败 -> providers/REFERENCE.md
• 会话未持久化 -> clinecore/gotchas.md
• Token 用量过高 -> production/REFERENCE.md（成本控制）
• Hub 连接问题 -> clinecore/gotchas.md
• 插件未加载 -> plugins/REFERENCE.md
• 事件未触发 -> events/REFERENCE.md

产品索引

API 接口

API	入口文件	描述
Agent	./references/agent/REFERENCE.md	轻量级内存 Agent 循环
ClineCore	./references/clinecore/REFERENCE.md	完整运行时，包含会话、持久化和内置工具

跨领域概念

概念	入口文件	描述
工具	./references/tools/REFERENCE.md	创建内置工具和自定义工具
插件	./references/plugins/REFERENCE.md	扩展系统，包含钩子、MCP 服务和捆绑技能
事件	./references/events/REFERENCE.md	实时流式事件
提供商	./references/providers/REFERENCE.md	大模型提供商配置
生产环境	./references/production/REFERENCE.md	部署、安全性、可观测性
调度	./references/scheduling/REFERENCE.md	Cron 任务和自动化
多 Agent	./references/multi-agent/REFERENCE.md	团队、子 Agent 和已配置的 Agent 配置文件

软件包一览

软件包	用途
@cline/sdk	面向用户的 @cline/core 别名；请先安装此软件包
@cline/core	会话、持久化、内置工具、配置、Hub 和精选重新导出
@cline/agents	兼容浏览器的 AgentRuntime 类和底层工厂
@cline/llms	大模型提供商网关
@cline/shared	类型、工具辅助函数、钩子引擎

资源

仓库：https://github.com/cline/cline
SDK 源码：https://github.com/cline/cline/tree/main/sdk
文档：https://docs.cline.bot/sdk/overview
Discord：https://discord.gg/cline