Cline Agent SDK

项目简介

agent-sdk 是 Cline 的核心跨平台智能体（Agent）逻辑库。它通过**依赖注入（Dependency Injection）**的设计模式，将底层宿主环境（如 Node.js CLI, Web Browser, VS Code 插件）与具体的大模型提供商（OpenAI, Anthropic 等）完全解耦。

SDK 内部纯粹专注于定义 Agent 的“思考-执行-反馈”核心工作流和解析逻辑，这使得相同的 Agent 核心代码能够无缝运行在任何平台上。

目录结构与核心模块

• src/agent/: 包含 ClineAgent 核心类，它是状态机的载体，负责维护主循环 loop() 的流转。
• src/runtime.ts: 定义 IAgentRuntime 接口，抽象了所有与宿主系统相关的能力，包括文件系统 (fs)、环境变量 (env) 和终端执行 (terminal)。并在 runtime/node 和 runtime/web 提供了部分默认实现。
• src/llm/: 定义 IApiHandler 接口，统一了不同大模型 API 的调用方式和流式（Stream）响应数据结构。
• src/prompt/: 定义 IPromptManager 和 IMemoryManager，负责基于上下文动态生成 System Prompt 以及管理对话历史（包括超长记忆的截断）。
• src/parser/: 核心解析模块。通过 parseAssistantMessageV2 将 LLM 的纯文本输出解析为结构化的 TextStreamContent、ReasoningStreamContent (思考过程) 和 ToolUse (工具调用指令)。
• src/mcp/: 定义 IMcpManager 接口，用于集成 Model Context Protocol (MCP)，从而低成本接入外部工具与资源。
• src/shared/tools.ts: 定义了 Agent 所支持的内置基础工具枚举 (AgentDefaultTool)。

核心架构与工作流

ClineAgent 是整个 SDK 的大脑，核心流转完全在 loop() 方法中完成，流程如下：

1. 上下文组装：调用 PromptManager 获取动态系统提示词，通过 MemoryManager 获取对话历史。
2. 大模型调用：将上下文传递给 ApiHandler 发起对话，并处理流式响应。
3. 指令解析：大模型回复结束后，使用 Parser 将输出解析为纯文本和工具调用指令（ToolUse）。如果没有工具调用，Agent 判定为进入等待用户输入状态。
4. 工具分发与执行：
   • Agent 顺序处理提取出的 ToolUse。
   • 首先触发 onToolCall 钩子，宿主环境可以在此拦截工具调用（例如：为了安全弹窗向用户申请执行权限，或接管某些如 browser_action 的特殊工具）。
   • 如果宿主未接管，Agent 会调用内置逻辑，利用注入的 IAgentRuntime（执行终端、读写文件）或 IMcpManager（执行外部协议工具）完成操作。
5. 结果反馈：将各工具执行的结果组合，作为 user 角色的消息追加到 Memory 中，并重新进入下一轮循环，直到遇到任务完成 (attempt) 或主动提问 (ask)。

快速集成指南

通过依赖注入，宿主应用可以极简地启动一个 Agent：

import { 
  ClineAgent, 
  IAgentRuntime, 
  IApiHandler, 
  IPromptManager, 
  IMemoryManager 
} from 'agent-sdk';

// 1. 实现或引入适用于当前宿主环境的依赖
const myRuntime: IAgentRuntime = { /* 提供 fs, env, terminal 等实现 */ };
const myApi: IApiHandler = { /* 提供大模型接口调用实现 */ };
const myPromptManager: IPromptManager = { /* ... */ };
const myMemory: IMemoryManager = { /* ... */ };

// 2. 初始化 Agent
const agent = new ClineAgent({
  runtime: myRuntime,
  api: myApi,
  promptManager: myPromptManager,
  memory: myMemory,
  // mcp: myMcpManager // 注入 MCP 管理器（可选）
});

// 3. 注册生命周期与事件监听
agent.onStateChange = (state) => {
  console.log(`Agent state changed to: ${state}`);
};

agent.onStreamChunk = (chunk) => {
  if (chunk.type === "text") process.stdout.write(chunk.text || '');
};

agent.onToolCall = async (tool) => {
  // 拦截点：可以在此处向用户确认权限
  // 若返回数据，Agent 将不再执行内置默认逻辑，直接以该数据作为工具结果
  if (tool.requires_approval) {
    const approved = await askUserForPermission(tool);
    if (!approved) return { error: "User denied" };
  }
};

// 4. 启动任务
await agent.startTask("帮我分析当前目录下的 package.json 文件并总结其依赖。");

构建与开发

# 安装依赖
npm install

# 本地开发 (Watch 模式)
npm run dev

# 构建输出
npm run build

# 类型检查
npm run typecheck