cline-sdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cline SDK Skill

Cline SDK 技能指南

Consolidated skill for building AI agents with the Cline SDK. Use the decision trees below to find the right entry point and API surface, then load detailed references.

这是一份使用Cline SDK构建AI Agent的综合技能指南。使用下方的决策树找到合适的入口点和API层面，然后查看详细参考文档。

Critical Rules

关键规则

Follow these rules in all Cline SDK code:

Install with

npm install @cline/sdk

. The

@cline/sdk

package re-exports everything from

@cline/core

@cline/agents

@cline/llms

, and

@cline/shared

Requires Node.js 22 or later.
Use
```
createTool()
```
from
```
@cline/sdk
```
(or
```
@cline/shared
```
) to define tools. Tool names must be
```
snake_case
```
.
Return errors as structured data from tool
```
execute
```
functions. Throwing counts as a "mistake" against the agent's mistake limit.
Use
```
lifecycle: { completesRun: true }
```
on tools that should end the agent loop (e.g. a "submit answer" tool).
When using
```
ClineCore
```
, always call
```
dispose()
```
when done to clean up resources.
The standalone
```
Agent
```
and
```
ClineCore
```
have different event systems. For
```
Agent
```
: use
```
agent.subscribe()
```
to get
```
AgentRuntimeEvent
```
types (text streaming is
```
"assistant-text-delta"
```
, result text is
```
result.outputText
```
). For
```
ClineCore
```
: use
```
cline.subscribe()
```
to get
```
CoreSessionEvent
```
types (text streaming is
```
"chunk"
```
with
```
payload.type === "text"
```
, result text is
```
result.text
```
). There is no top-level
```
onEvent
```
field on
```
AgentRuntimeConfig
```
-- use
```
agent.subscribe()
```
or
```
hooks.onEvent
```
instead. Do not use event types like
```
"content_update"
```
or
```
"content_start"
```
with
```
agent.subscribe()
```
-- those are internal legacy types from the ClineCore adapter layer.

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

使用

npm install @cline/sdk

进行安装。

@cline/sdk

包会重新导出

@cline/core

、

@cline/agents

、

@cline/llms

和

@cline/shared

中的所有内容。

需要Node.js 22或更高版本。
使用
```
@cline/sdk
```
（或
```
@cline/shared
```
）中的
```
createTool()
```
来定义工具。工具名称必须为
```
snake_case
```
格式。
从工具的
```
execute
```
函数中以结构化数据形式返回错误。抛出错误会被计入Agent的错误次数限制。
对于应终止Agent循环的工具（例如“提交答案”工具），请设置
```
lifecycle: { completesRun: true }
```
。
使用
```
ClineCore
```
时，使用完毕后务必调用
```
dispose()
```
来清理资源。
独立的
```
Agent
```
和
```
ClineCore
```
拥有不同的事件系统。对于
```
Agent
```
：使用
```
agent.subscribe()
```
来获取
```
AgentRuntimeEvent
```
类型（文本流为
```
"assistant-text-delta"
```
，结果文本为
```
result.outputText
```
）。对于
```
ClineCore
```
：使用
```
cline.subscribe()
```
来获取
```
CoreSessionEvent
```
类型（文本流为
```
"chunk"
```
且
```
payload.type === "text"
```
，结果文本为
```
result.text
```
）。
```
AgentRuntimeConfig
```
没有顶层的
```
onEvent
```
字段——请改用
```
agent.subscribe()
```
或
```
hooks.onEvent
```
。不要在
```
agent.subscribe()
```
中使用
```
"content_update"
```
或
```
"content_start"
```
等事件类型——这些是ClineCore适配层的内部遗留类型。

How to Use This Skill

如何使用本技能指南

Reference File Structure

参考文件结构

The two main API surfaces (

Agent

and

ClineCore

) follow a 4-file pattern. Cross-cutting concepts are single-file guides.

Each main API surface in

./references/<api>/

contains:

File	Purpose	When to Read
`REFERENCE.md`	Overview, when to use, quick start	Always read first
`api.md`	Full API: classes, methods, config, types	Writing code
`patterns.md`	Common patterns, best practices	Implementation guidance
`gotchas.md`	Pitfalls, limitations, debugging	Troubleshooting

Cross-cutting concepts in

./references/<concept>/

have

REFERENCE.md

as the entry point.

两个主要的API层面（

Agent

和

ClineCore

）遵循4文件模式。跨领域概念为单文件指南。

./references/<api>/

中的每个主要API层面包含：

文件	用途	阅读时机
`REFERENCE.md`	概述、适用场景、快速入门	务必首先阅读
`api.md`	完整API：类、方法、配置、类型	编写代码时
`patterns.md`	常见模式、最佳实践	实现指导
`gotchas.md`	陷阱、限制、调试方法	故障排查时

./references/<concept>/

中的跨领域概念以

REFERENCE.md

作为入口点。

Reading Order

阅读顺序

Start with
```
REFERENCE.md
```
for your chosen API surface
Then read additional files relevant to your task:
- Writing agent code ->
```
api.md
```
- Common patterns ->
```
patterns.md
```
- Creating tools ->
```
tools/REFERENCE.md
```
- Adding plugins/hooks ->
```
plugins/REFERENCE.md
```
- Configuring LLM providers ->
```
providers/REFERENCE.md
```
- Streaming events ->
```
events/REFERENCE.md
```
- Deploying to production ->
```
production/REFERENCE.md
```
- Scheduling agents ->
```
scheduling/REFERENCE.md
```
- Multi-agent orchestration ->
```
multi-agent/REFERENCE.md
```
- Debugging ->
```
gotchas.md
```

从所选API层面的
```
REFERENCE.md
```
开始
然后阅读与任务相关的其他文件：
- 编写Agent代码 ->
```
api.md
```
- 常见模式 ->
```
patterns.md
```
- 创建工具 ->
```
tools/REFERENCE.md
```
- 添加插件/钩子 ->
```
plugins/REFERENCE.md
```
- 配置LLM提供商 ->
```
providers/REFERENCE.md
```
- 流事件处理 ->
```
events/REFERENCE.md
```
- 生产部署 ->
```
production/REFERENCE.md
```
- Agent任务调度 ->
```
scheduling/REFERENCE.md
```
- 多Agent编排 ->
```
multi-agent/REFERENCE.md
```
- 调试 ->
```
gotchas.md
```

Example Paths

示例路径

./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

./references/agent/REFERENCE.md           # 轻量级Agent从这里开始
./references/clinecore/REFERENCE.md       # 完整运行时从这里开始
./references/agent/api.md                 # Agent类、配置、方法
./references/tools/REFERENCE.md           # 创建和使用工具
./references/plugins/REFERENCE.md         # 插件系统
./references/providers/REFERENCE.md       # LLM提供商配置

Quick Decision Trees

快速决策树

"Which API surface should I use?"

“我应该使用哪个API层面？”

Which API?
+-- I want a simple, stateless agent with custom tools
|   +-- agent/ (Agent class from @cline/agents)
+-- 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)

选择哪个API？
+-- 我想要一个带自定义工具的简单无状态Agent
|   +-- agent/（来自@cline/agents的Agent类）
+-- 我需要会话持久化、内置工具、配置发现
|   +-- clinecore/（来自@cline/core的ClineCore）
+-- 我想要内置的文件/Shell/搜索/网络工具
|   +-- clinecore/（包含内置工具；Agent没有）
+-- 我想要定时或周期性运行的Agent
|   +-- clinecore/（自动化API）
+-- 我需要多进程或多客户端会话共享
|   +-- clinecore/（基于hub的运行时）
+-- 我正在构建兼容浏览器的Agent
|   +-- agent/（无Node.js依赖）

"I need to create tools"

“我需要创建工具”

Tools?
+-- Define a custom tool with schema -> tools/REFERENCE.md
+-- Use built-in tools (bash, editor, read_files) -> 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

工具相关？
+-- 定义带Schema的自定义工具 -> tools/REFERENCE.md
+-- 使用内置工具（bash、编辑器、read_files） -> tools/REFERENCE.md（内置工具章节）
+-- 控制工具审批/策略 -> tools/REFERENCE.md（策略章节）
+-- 可终止Agent循环的工具 -> tools/REFERENCE.md（完成型工具章节）
+-- 将工具打包为可复用插件 -> plugins/REFERENCE.md

"I need to handle events"

“我需要处理事件”

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

事件相关？
+-- 实时流式传输文本/推理过程 -> events/REFERENCE.md
+-- 跟踪Token使用量和成本 -> events/REFERENCE.md
+-- 监控工具调用 -> events/REFERENCE.md
+-- 检测完成/错误 -> events/REFERENCE.md
+-- 挂钩到生命周期阶段 -> plugins/REFERENCE.md

"I need to configure a model provider"

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

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

提供商相关？
+-- 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的提供商（vLLM、Together等） -> providers/REFERENCE.md
+-- 自定义/自托管提供商 -> providers/REFERENCE.md

"I need plugins or hooks"

“我需要插件或钩子”

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
+-- Distribute via npm/git -> plugins/REFERENCE.md

插件相关？
+-- 将工具+钩子打包在一起 -> plugins/REFERENCE.md
+-- 监控工具调用（日志、指标） -> plugins/REFERENCE.md
+-- 拦截生命周期事件 -> plugins/REFERENCE.md
+-- 添加系统提示规则 -> plugins/REFERENCE.md
+-- 通过npm/git分发 -> plugins/REFERENCE.md

"I need multi-agent coordination"

“我需要多Agent协作”

Multi-agent?
+-- Spawn one-off background agents -> multi-agent/REFERENCE.md (sub-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)

多Agent相关？
+-- 生成一次性后台Agent -> multi-agent/REFERENCE.md（子Agent章节）
+-- 跨会话持久化团队 -> multi-agent/REFERENCE.md（团队章节）
+-- 父-子任务委托 -> multi-agent/REFERENCE.md（子Agent章节）
+-- 对等任务看板 -> multi-agent/REFERENCE.md（团队章节）

"I need scheduling or automation"

“我需要任务调度或自动化”

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

调度相关？
+-- 周期性Cron任务 -> scheduling/REFERENCE.md
+-- 一次性定时任务 -> scheduling/REFERENCE.md
+-- 事件驱动触发器 -> scheduling/REFERENCE.md
+-- CLI调度管理 -> scheduling/REFERENCE.md

"I need to go to production"

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

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

生产环境相关？
+-- 错误处理和状态检查 -> production/REFERENCE.md
+-- 成本控制和Token限制 -> production/REFERENCE.md
+-- 可观测性（OpenTelemetry） -> production/REFERENCE.md
+-- 安全和沙箱 -> production/REFERENCE.md
+-- 部署模式 -> production/REFERENCE.md

Troubleshooting Index

故障排查索引

Agent loop not stopping ->
```
tools/REFERENCE.md
```
(completion tools)
Tool errors crashing the agent ->
```
agent/gotchas.md
```
or
```
clinecore/gotchas.md
```
Provider auth failures ->
```
providers/REFERENCE.md
```
Session not persisting ->
```
clinecore/gotchas.md
```
Token usage too high ->
```
production/REFERENCE.md
```
(cost control)
Hub connection issues ->
```
clinecore/gotchas.md
```
Plugin not loading ->
```
plugins/REFERENCE.md
```
Events not firing ->
```
events/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
```

Product Index

产品索引

API Surfaces

API层面

API	Entry File	Description
Agent	`./references/agent/REFERENCE.md`	Lightweight stateless agent loop
ClineCore	`./references/clinecore/REFERENCE.md`	Full runtime with sessions, persistence, built-in tools

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

Cross-Cutting Concepts

跨领域概念

Concept	Entry File	Description
Tools	`./references/tools/REFERENCE.md`	Built-in and custom tool creation
Plugins	`./references/plugins/REFERENCE.md`	Extension system with hooks
Events	`./references/events/REFERENCE.md`	Real-time streaming events
Providers	`./references/providers/REFERENCE.md`	LLM provider configuration
Production	`./references/production/REFERENCE.md`	Deployment, security, observability
Scheduling	`./references/scheduling/REFERENCE.md`	Cron jobs and automation
Multi-Agent	`./references/multi-agent/REFERENCE.md`	Teams and sub-agents

概念	入口文件	描述
Tools	`./references/tools/REFERENCE.md`	内置工具和自定义工具创建
Plugins	`./references/plugins/REFERENCE.md`	带钩子的扩展系统
Events	`./references/events/REFERENCE.md`	实时流事件
Providers	`./references/providers/REFERENCE.md`	LLM提供商配置
Production	`./references/production/REFERENCE.md`	部署、安全、可观测性
Scheduling	`./references/scheduling/REFERENCE.md`	Cron任务和自动化
Multi-Agent	`./references/multi-agent/REFERENCE.md`	团队和子Agent

Package Map

包映射

Package	Purpose
`@cline/sdk`	Everything you need, install this one
`@cline/core`	Sessions, persistence, built-in tools, config, hub
`@cline/agents`	Stateless agent loop, tool orchestration, streaming
`@cline/llms`	LLM provider gateway
`@cline/shared`	Types, tool helpers, hook engine

包	用途
`@cline/sdk`	所需全部内容，安装这一个即可
`@cline/core`	会话、持久化、内置工具、配置、hub
`@cline/agents`	无状态Agent循环、工具编排、流处理
`@cline/llms`	LLM提供商网关
`@cline/shared`	类型、工具助手、钩子引擎

Resources

资源

Repository: https://github.com/cline/cline SDK Source: https://github.com/cline/cline/tree/main/sdk Documentation: https://docs.cline.bot/sdk/overview Discord: https://discord.gg/cline

代码仓库: 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