首页
/ Cline SDK Agent 类完全解析：配置、run/continue 生命周期与 Hook 拦截机制

Cline SDK Agent 类完全解析：配置、run/continue 生命周期与 Hook 拦截机制

2026-09-03 15:33:34作者：余洋婵Anita
cline
Autonomous coding agent as an SDK, IDE extension, or CLI assistant.
项目地址：https://gitcode.com/GitHub_Trending/cl/cline

本篇以 Cline SDK 中独立运行的 Agent 类（@cline/agents 包，经 @cline/sdk 统一导出）为对象，完整覆盖其构造函数与 AgentRuntimeConfig 两种配置形态、run/continue/abort/subscribe/snapshot/restore 全量方法、AgentRunResult/AgentMessage/AgentUsage 等结果类型，以及 AgentRuntimeHooks 七种生命周期钩子的拦截语义；并深入 agent-runtime.ts 源码，印证事件发射顺序、工具策略（toolPolicies）的合并规则、上下文窗口溢出的自动恢复流程等底层行为，读完即可独立搭建并控制一个可流式、可中止、可持久化恢复的无状态 Agent 循环。

一、Agent 定位与创建方式

Agent 类（同时以 AgentRuntime 名导出，二者是同一个类）是 @cline/agents 包提供的轻量、无状态 Agent 循环：发送消息给 LLM → 执行工具调用 → 收集结果 → 重复，直到任务完成。它不向磁盘持久化任何内容，会话历史保存在内存中，可通过 snapshot() 获取。适用于需要自定义工具、最小依赖、浏览器兼容或无状态 worker 的场景；需要内置工具（bash、editor）、会话持久化或 .cline/ 配置发现时，应改用 ClineCore（参见 Agent Runtime 概览）。

构造函数与工厂函数

import { Agent } from "@cline/sdk"

const agent = new Agent(config: AgentRuntimeConfig)

等价工厂函数两种：

import { createAgent } from "@cline/sdk"

const agent = createAgent(config)

更底层的 createAgentRuntime 返回的也是同一个 Agent 类（源码中 createAgentRuntime 与 createAgent 都只是 new AgentRuntime(config)，见 agent-runtime.ts#L2169-L2188）：

import { createAgentRuntime } from "@cline/sdk"

const runtime = createAgentRuntime(config)

从 index.ts 的导出注释可以看到命名约定：Agent 面向传入 provider/model ID 的独立调用者，AgentRuntime 面向传入预构建 AgentModel 的 @cline/core；共享类型（AgentMessage、AgentRunResult 等）应从 @cline/shared 直接导入，createTool 也从 @cline/shared 再导出。

二、AgentRuntimeConfig：两种判别联合配置

配置是判别联合（discriminated union），按“是否携带预构建 model”分两种形态（源码定义见 agent-runtime.ts#L106-L139）。

形态一：Provider ID 形式（推荐）

interface AgentRuntimeConfigWithProvider {
  providerId: string          // e.g. "anthropic", "openai", "gemini"
  modelId: string             // e.g. "claude-sonnet-4-6", "gpt-5.5"
  apiKey?: string             // provider API key
  baseUrl?: string            // custom endpoint
  headers?: Record<string, string>

  systemPrompt?: string
  tools?: AgentTool[]
  initialMessages?: AgentMessage[]
  toolPolicies?: Record<string, ToolPolicy>
  hooks?: Partial<AgentRuntimeHooks>
  plugins?: AgentPlugin[]
}

运行时收到这种配置后，resolveRuntimeConfig() 会用 @cline/llms 的 createGateway 内部构建出 AgentModel（见 agent-runtime.ts#L147-L168），同时把 messageModelInfo 默认设为 { id: modelId, provider: providerId }，用于给 assistant 消息打 modelInfo 标签（调用方显式提供的值优先）。因此大多数独立用户只需关心 providerId、modelId、apiKey 三个字段。

形态二：预构建 Model 形式

interface AgentRuntimeConfigWithModel {
  model: AgentModel            // pre-built model from gateway

  systemPrompt?: string
  tools?: AgentTool[]
  initialMessages?: AgentMessage[]
  toolPolicies?: Record<string, ToolPolicy>
  hooks?: Partial<AgentRuntimeHooks>
  plugins?: AgentPlugin[]
}

这是高级形态：调用方自建 AgentModel（通常通过 @cline/llms 的 gateway），以便复用同一个 gateway 的遥测与配置接线。典型场景是多 provider 网关：

import { Agent } from "@cline/sdk"
import { createGateway } from "@cline/llms"

const gateway = createGateway({
  providerConfigs: [
    { providerId: "anthropic", apiKey: process.env.ANTHROPIC_API_KEY },
    { providerId: "openai", apiKey: process.env.OPENAI_API_KEY },
  ],
})

const model = gateway.createAgentModel({
  providerId: "anthropic",
  modelId: "claude-opus-4-7",
})

const agent = new Agent({
  model,
  systemPrompt: "You are a helpful assistant.",
  tools: [],
})

运行时通过 hasPrebuiltModel()（即 config.model !== undefined）判断走哪条分支，因此两种形态不可混用：一旦传了 model，providerId 等字段就不再起模型构建作用。

一个容易踩的坑：配置上没有顶层 onEvent

AgentRuntimeConfig 上不存在顶层 onEvent 字段。事件订阅只有两条路：agent.subscribe()（同步回调，适合 UI 流式渲染）或 hooks.onEvent（可异步，被 await 等待，适合写外部日志服务等副作用）。hooks.onEvent 收到的 AgentRuntimeEvent 类型与 subscribe() 完全相同。完整事件目录见 事件参考。

三、核心方法逐个解析

run(input)

启动一次运行。输入可以是 string、单个 AgentMessage 或 AgentMessage[]（源码中类型别名 AgentRunInput = string | AgentMessage | readonly AgentMessage[]，见 agent-runtime.ts#L98）。字符串会被包装为 user 角色的 text 消息；消息数组则深拷贝后入栈。

const result: AgentRunResult = await agent.run("Build a REST API")

从源码的 execute() 主循环看（agent-runtime.ts#L690-L938），run() 的完整流程是：

  1. 确保完成惰性初始化（注册 hooks、工具表、插件 setup()）；若当前状态是 running 则直接抛错，防止重入；
  2. 新建 AbortController、生成新 runId，重置 iteration、usage、错误状态；
  3. 依次调用 beforeRun 钩子 → 发射 run-started 事件；
  4. 输入消息逐条入栈并各发一个 message-added 事件；
  5. 进入迭代循环：发射 turn-started → 请求模型（含上下文溢出自动恢复）→ 若模型返回 tool-call 部件则执行工具（发射 tool-started/tool-finished，工具结果作为 tool 角色消息入栈）并继续下一轮；若返回纯文本（无工具调用）则结束，发射 turn-finished 与 run-finished；
  6. 捕获任何异常后统一组装 AgentRunResult 返回（注意：异常不向外抛，而是以 status: "aborted" | "failed" 的 result 形式返回，error 字段仅 failed 时携带）。

continue(input?)

继续既有会话，输入可选（不传输入也可以，例如仅消费排队消息）。它与 run() 在源码里都委托给同一个 execute()（agent-runtime.ts#L536-L542），差异仅在于语义：continue 不重置会话历史，直接在当前 messages 之上再跑一个 run（新 runId、usage 从零累计）。

const result = await agent.continue("Now add authentication")

配合 hasRun 属性（布尔值，表示 run() 是否至少被调用过一次）做入口分派是标准写法：

if (agent.hasRun) {
  await agent.continue(input)
} else {
  await agent.run(input)
}

abort(reason?)

取消当前正在进行的运行。reason 可以是任意值：若传入的就是 AgentRuntimeAbortError 则原样使用，否则运行时包装成一个（agent-runtime.ts#L544-L560）。中止后主循环在下一个检查点抛出中止错误，run()/continue() 的 Promise 正常 resolve，返回 status: "aborted" 的 result（而非 reject），因此超时保护可以这样写：

const timeout = setTimeout(() => agent.abort("Timeout"), 30_000)

try {
  const result = await agent.run(data)
  if (result.status === "aborted") {
    console.log("Agent was aborted")
  } else {
    console.log(result.outputText)
  }
} finally {
  clearTimeout(timeout)
}

subscribe(listener)

注册流式事件监听器，返回取消函数：

const unsubscribe = agent.subscribe((event: AgentRuntimeEvent) => {
  // handle event
})

// Later: stop listening
unsubscribe()

实现上就是一个 Set<AgentEventListener>（agent-runtime.ts#L562-L567），emit() 先同步调用所有 listener，再 await 所有 hooks.onEvent。因此务必在 run() 之前注册以免错过 run-started 等早期事件；assistant-text-delta 等逐 chunk 事件频率极高，listener 应保持轻量。

snapshot() 与 restore(messages)

snapshot() 返回当前运行时状态的深拷贝（messages 经 cloneMessages 逐项浅克隆，防止外部修改污染内部状态）。AgentRuntimeStateSnapshot 的完整字段（agent.ts#L151-L165）比 API 文档简表更丰富：

interface AgentRuntimeStateSnapshot {
  agentId: string
  agentRole?: string
  parentAgentId?: string | null
  conversationId?: string
  runId?: string
  status: "idle" | "running" | "completed" | "aborted" | "failed"
  iteration: number
  messages: readonly AgentMessage[]
  pendingToolCalls: readonly string[]
  usage: AgentUsage
  lastError?: string
  lastErrorClass?: "context_window_exceeded" | "auth" | "unknown"
}

restore(messages) 用于整体替换会话历史：它会先 abort("Agent state restored") 丢弃进行中的运行与 usage 状态，然后保留 model、tools、hooks、plugins 与已注册的事件订阅者——这正好服务于“外部持久化会话、跨进程恢复”的诉求（agent-runtime.ts#L577-L595）：

// Save state
const snapshot = agent.snapshot()
const serialized = JSON.stringify(snapshot.messages)

// Later: restore
const agent2 = new Agent({ ...config })
const messages = JSON.parse(serialized)
agent2.restore(messages)
const result = await agent2.continue("Continue where we left off")

如果需要自动持久化（checkpoint、.cline/ 会话管理），应使用 ClineCore。

四、AgentRunResult：统一的结果契约

run() 与 continue() 都返回：

interface AgentRunResult {
  agentId: string
  agentRole?: string
  runId: string
  status: "completed" | "aborted" | "failed"
  iterations: number
  outputText: string
  messages: readonly AgentMessage[]
  usage: AgentUsage
  error?: Error
}

状态值语义：

  • "completed" — 正常结束。两种触发路径：模型返回无工具调用的文本；或成功调用了带 lifecycle.completesRun: true 的“终结工具”（此时 outputText 取该工具的输出文本而非 assistant 消息文本，见 finishRun 调用处 agent-runtime.ts#L850-L867）；
  • "aborted" — 经 abort() 或 hook 返回 stop: true 的受控停止（ControlledStopError）导致；
  • "failed" — 不可恢复错误，error 字段携带该 Error 实例，同时发射 run-failed 事件。

outputText 取最后一条 assistant 消息中的 text 部件拼接；iterations 即本次 run 消耗的模型轮次数。注意 messages 与 usage 都是拷贝，可安全持有。

五、AgentMessage 与 AgentUsage 数据模型

AgentMessage

interface AgentMessage {
  id: string
  role: "user" | "assistant" | "tool"
  content: AgentMessagePart[]
  createdAt: number
  metadata?: Record<string, unknown>
  modelInfo?: { id: string; provider: string; family?: string }
  metrics?: {
    inputTokens: number
    outputTokens: number
    cacheReadTokens?: number
    cacheWriteTokens?: number
    cost?: number
  }
}

补充两个源码层面的事实：消息 id 由 createUID("msg") 生成（msg_ 前缀 + nanoid）；metrics 是运行时用 usageDelta() 计算的单条消息增量（本轮模型调用前后 usage 之差，见 agent-runtime.ts#L375-L420），当所有项均为 0 时该字段省略——所以按消息统计 token 成本时应以 metrics 为准，而 usage 是 run 级累计。

content 是部件数组（AgentMessagePart），包含 text、reasoning、media、file、tool-call、tool-result 等类型；assistant 消息可能同时携带文本与多个 tool-call 部件，工具结果则单独作为 role: "tool" 的消息入栈。

AgentUsage

interface AgentUsage {
  inputTokens: number
  outputTokens: number
  cacheReadTokens: number
  cacheWriteTokens: number
  totalInputTokens: number
  totalOutputTokens: number
  totalCost?: number
}

totalInputTokens/totalOutputTokens 为跨 run 累计总量。usage 由模型流的 usage 事件增量累加（updateUsage()，agent-runtime.ts#L1610-L1628），每次更新都会发射 usage-updated 事件，因此 UI 可以实时显示成本：

agent.subscribe((event) => {
  if (event.type === "usage-updated" && event.usage.totalCost) {
    console.log(`Running cost: $${event.usage.totalCost.toFixed(4)}`)
  }
})

六、AgentRuntimeHooks：七种生命周期钩子

interface AgentRuntimeHooks {
  beforeRun?(context): AgentStopControl | undefined
  afterRun?(context): void
  beforeModel?(context): AgentBeforeModelResult | undefined
  afterModel?(context): AgentStopControl | undefined
  beforeTool?(context): AgentBeforeToolResult | undefined
  afterTool?(context): AgentAfterToolResult | undefined
  onEvent?(event: AgentRuntimeEvent): void | Promise<void>
}

钩子可以在每个阶段拦截并修改行为。结合 shared/agent.ts 中各 Result 类型的完整字段，各钩子的能力边界是：

钩子 可返回的关键字段 能力
beforeRun stop、reason 运行开始前否决整次 run
afterRun 无（void） 拿到最终 result 做收尾、上报
beforeModel stop、reason、messages、tools、options 每个模型请求前改写消息、工具集与模型选项
afterModel stop、reason 模型返回后审查 assistant 消息并终止
beforeTool skip、stop、reason、input、policy、appendContext 拦截/改写工具输入、覆盖工具策略、注入上下文
afterTool stop、reason、result、appendContext 改写工具结果、注入上下文
onEvent 无 同 subscribe() 的事件流，但会被 await，可异步

几个值得注意的源码行为：

  • 停止语义：beforeRun/afterModel/beforeTool 返回 { stop: true, reason } 时，运行时抛出内部 ControlledStopError，run 以 status: "aborted" 结束，reason 写入 snapshot().lastError（agent-runtime.ts#L2044-L2054）；
  • 钩子可叠加：registerHooks() 把 config hooks 与各插件 hooks 追加进同一个 HookBag 数组，按注册顺序逐个执行（agent-runtime.ts#L637-L648）；
  • appendContext 注入：beforeTool/afterTool 返回的 appendContext 文本会被包装为带 source/tool_name/tool_call_id 属性的 <hook_context> 块，在该轮所有工具结果之后合并为一条用户消息追加进会话（displayRole: "system"，不出现在面向用户的 transcript 中），模型在下一轮请求即可看到（agent-runtime.ts#L826-L843）；
  • subscribe 与 onEvent 的分工：subscribe() listener 同步调用、适合 UI 流式渲染；hooks.onEvent 在 emit() 中被逐个 await、适合异步副作用（如上报外部服务），但注意它会阻塞主循环推进，应保持快速。

插件形态的 hooks 写法（插件可额外通过 setup() 返回工具与 hooks）：

import { Agent } from "@cline/sdk"
import type { AgentPlugin } from "@cline/sdk"

const loggingPlugin: AgentPlugin = {
  name: "logging",
  manifest: { capabilities: ["hooks"] },
  setup() {},
  hooks: {
    beforeTool({ toolCall }) {
      console.log(`Calling tool: ${toolCall.toolName}`)
    },
    afterRun({ result }) {
      console.log(`Completed in ${result.iterations} iterations`)
    },
  },
}

const agent = new Agent({
  providerId: "anthropic",
  modelId: "claude-sonnet-4-6",
  systemPrompt: "You are a helpful assistant.",
  tools: [myTool],
  plugins: [loggingPlugin],
})

七、工具策略 toolPolicies 与审批

toolPolicies 是 Record<string, ToolPolicy>，ToolPolicy 定义在 shared/llms/tools.ts：

interface ToolPolicy {
  /** 工具是否允许执行，默认 true */
  enabled?: boolean
  /** 是否无需客户端审批即可运行，默认 true */
  autoApprove?: boolean
}

源码中 resolveToolPolicy() 的合并规则（agent-runtime.ts#L170-L178）：通配符 "*" 的策略先展开，再被同名工具的策略覆盖，因此可以写“全局默认 + 个别例外”：

const agent = new Agent({
  providerId: "anthropic",
  modelId: "claude-sonnet-4-6",
  tools: [readFile, writeFile, runShell],
  toolPolicies: {
    "*": { autoApprove: false },        // 默认全部需要审批
    read_file: { autoApprove: true },   // 只读工具放行
    run_shell: { enabled: false },      // 直接禁用
  },
})

执行链上的判定顺序（prepareToolExecution，agent-runtime.ts#L1674-L1771）：先跑 beforeTool 钩子（可改写 input、覆盖 policy、返回 skip）→ 合并 config 策略与钩子策略 → enabled === false 则记为跳过 → autoApprove === false 则调用配置的 requestToolApproval 回调请求审批，未配置回调时视为拒绝。被跳过/拒绝的工具不会抛出，而是产出 isError: true 的工具结果消息（附带 -- 拒绝后缀），让模型看到失败原因后自行调整。

八、迭代上限与上下文溢出的自动恢复

两个超出 API 文档范围、但直接影响生产可用性的运行时机制：

  • maxIterations：config.maxIterations 未设置时无上限；设置后循环条件为 iteration < maxIterations，超出即抛出 “Agent runtime exceeded maxIterations” 错误并以 status: "failed" 返回（agent-runtime.ts#L727-L730）。此外 completionPolicy.requireCompletionTool: true 时，若模型只返回文本，运行时会注入“必须调用终结完成工具”的提醒消息并继续循环，直到成功调用 completesRun: true 的工具。
  • 上下文窗口溢出恢复：当 provider 拒绝请求且错误被分类为 context_window_exceeded 时，运行时每个 run 自动尝试一次恢复：通过 prepareTurn 强制压缩（compaction）后重试，并先发射 status-notice 事件（“context window exceeded — compacting and retrying”）。若重试后消息未实际变小、或重试仍溢出，则以带可操作建议的终态消息失败（如 “there is no conversation history to compact…”），这些常量在 agent-runtime.ts#L52-L75 中定义，可直接用于错误文案匹配。

九、典型完整用法

把前述 API 组合起来的流式多轮 Agent：

import { Agent } from "@cline/sdk"

const agent = new Agent({
  providerId: "anthropic",
  modelId: "claude-sonnet-4-6",
  apiKey: process.env.ANTHROPIC_API_KEY,
  systemPrompt: "You are a helpful assistant. Keep responses concise.",
  tools: [],
  hooks: {
    onEvent: async (event) => {
      if (event.type === "run-failed") {
        await logToExternalService(event.error.message)
      }
    },
  },
})

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

const first = await agent.run("What is 2 + 2?")
const second = await agent.continue("Now multiply that by 3")
console.log(second.outputText)
console.log(first.usage, second.iterations)

更多模式（交互式 CLI、按线程维护 agent 实例的聊天机器人、completesRun 结构化工具、插件）见 patterns.md；常见陷阱与调试见 gotchas.md。

十、延伸阅读（仓库内路径）

cline
Autonomous coding agent as an SDK, IDE extension, or CLI assistant.
项目地址：https://gitcode.com/GitHub_Trending/cl/cline
登录后查看全文

相关内容推荐

1 Cline SDK Agent 运行时（@cline/agents）实战指南：状态无关 Agent 循环、工具调用与事件流2 Cline SDK 实战指南：Agent 与 ClineCore 双运行时选型、工具定义规则与生产化路径3 Cline SDK Agent 模式实战：交互式 CLI、流式 UI、结构化输出与状态恢复4 Cline 插件开发指南：从 Manifest 能力声明到七钩子运行时,构建可跨 CLI/IDE/SDK 运行的 Agent 扩展5 Cline SDK Agent 生产部署实战：错误处理、成本控制、可观测性与安全加固6 Cline SDK ClineCore 运行时：用内置工具、会话持久化与多进程 Hub 构建有状态编码智能体7 VS Code Copilot Hooks 实战：用 create-hook 技能创建确定性的 Agent 生命周期钩子8 Agno Agent Hooks 实战：pre_hooks、post_hooks 与 tool_hooks 拦截扩展机制详解9 learn-claude-code s04：Hooks——如何把扩展逻辑挂在 Agent 循环上而不侵入循环10 拒绝封号风险：基于 HermesClaw 与 OpenClaw 打造最强微信 AI 助理
热门项目推荐
相关项目推荐

热门内容推荐

1 编程实践项目探索指南：从零构建技术能力体系2 技术解构式学习：从0到1构建你的编程知识体系3 构建自己的技术世界：build-your-own-x项目的实践探索指南4 解锁编程技能的实践之旅：从零构建你的技术世界5 技术实践探索：从零开始构建核心系统的实践指南6 亲手锻造技术引擎：从0到1构建核心系统的实践指南

最新内容推荐

qBittorrent WebAPI 变更日志详解：从 2.11 到 2.16 的 API 演进、破坏性变更与源码级实现剖析Godot Engine 的 thirdparty 目录：第三方库 Vendor 化、补丁管理与更新流程全解析fuels-rs Codec 详解：基于 ABIEncoder / ABIDecoder 的类型序列化与反序列化机制Scrapling MCP Server 详解：把三级 Web 抓取能力接入 AI Agent 的完整实践zx ProcessPromise 完全指南：Promise 语义下的进程控制、管道流与输出格式化Adobe 前端面试题全解：从 front-end-interview-handbook 看 JS 算法、UI 组件与系统设计考点Khoj 自定义 Agent 实现指南：从 Admin 创建、权限模型到 API 与知识绑定机制AutoGPT 前端实战：用 useLatest 稳定回调引用，解决 React Effect 重复执行与闭包过期问题Open Notebook 本地私有化部署实战：Docker Compose + Ollama 构建 100% 离线的 NotebookLM 式研究助手MinerU 壁仞（Biren）加速卡部署指南：从镜像加载到服务启动的完整实操

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
854
1.34 K
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.12 K
2.72 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
528
588
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
906
1.83 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.53 K
1.01 K
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
989
508
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.34 K
1.45 K
docsdocs
暂无描述
Markdown
892
5.79 K
openGauss-serveropenGauss-server
openGauss kernel ~ openGauss is an open source relational database management system
C++
213
313