从Cline原理看AI Agent设计的一般范式

`Cline` 原理分析

大家好，我是 高小黑！今天我们来聊聊一个非常优秀的 AI 编码助手------Cline。它目前在免费、开源的 AI 编码插件里可以说是"王者"级别的存在。

更重要的是，通过分析 Cline 的 Prompt 设计，我们可以一窥当前 AI Agent 设计的一些通用范式和最佳实践。 其次就是，它的 System Prompt 本身就是一个极佳的 Agent 设计模板。

那么，我们就从拆解它的 System Prompt 开始吧~

System Prompt 拆解：构建一个高效的 AI Agent

首先，因为 Cline 采用的是在 System Prompt 提供工具，通过多轮 user & assistant 的对话来完成工具调用和任务执行的。我们重点看一下 System Prompt 的设计。

1. 人物设定 (Persona)

[source: 1] You are Cline, a highly skilled software engineer with extensive knowledge in many programming languages, frameworks, design patterns, and best practices. 

这是 Prompt 工程中最基础也最重要的一步：给 LLM 一个明确的身份。

1. 定义角色和身份：让 LLM 知道"我是谁"，以特定视角和知识储备来回应。
2. 提供上下文信息：身份本身就蕴含了大量隐性知识，帮助 LLM 理解任务背景。
3. 引导输出风格：工程师的沟通风格通常是精确、技术性的，这有助于设定输出的基调。
4. 增强可控性：角色限制了行为边界，减少不相关或不专业的输出。

在 Cline 的例子里，这个设定（高级软件工程师）直接关联到它的核心任务------编程。

2. 工具使用 (Tool Use)

[source: 2] You have access to a set of tools that are executed upon the user's approval. [source: 3] You can use one tool per message, and will receive the result of that tool use in the user's response. [source: 4] You use tools step-by-step to accomplish a given task, with each tool use informed by the result of the previous tool use. ... [source: 5] Tool use is formatted using XML-style tags. ... (XML format explanation and example) ... [source: 8-90] # Tools (Detailed list and descriptions) ... [source: 93-114] # Tool Use Guidelines (Crucial rules for interaction) 

这是 Agent 的核心机制------通过调用外部工具来与世界交互和完成任务。Cline 的 Prompt 在这里体现了几个关键设计点：

• 明确的工具列表与描述 ：Prompt 详细列出了每个工具的名称 (execute_command, read_file, write_to_file, replace_in_file, search_files, list_files, list_code_definition_names, use_mcp_tool, access_mcp_resource, ask_followup_question, attempt_completion, plan_mode_response) [sources 8-91]，以及它们的功能、参数和使用场景。这让 LLM 知道自己有哪些"武器"以及如何使用。

• 结构化的调用格式 (XML) ：

  为什么使用 XML 风格的方式？

  首先，我们解释下为什么一定要固定某种"风格"？

  目前主流的LLM 和应用程序沟通的方式有这么几种：

  XML 的好处就是：

  **

  **

  也就是说，能最大程度的避免不同业务带来的干扰，并且还能支持流式输出。

  试想一下，如果你使用 JSON 格式，要想流式的将 LLM 的输出写入到 文件里，怎么办？检查下 "write_to_file" 关键词？然后调用对应的函数？

  不是说不行，就是可能会存在意想不到的干扰。

  而且，JSON 的中的 value 内容（转义字符）一般人类读起来比较费劲儿， 换行符都写成了 "\n"。人类可读这一点确实不太行。

  举个例子，如果要流式写入文件内容：

  <content> # 这里是标题 这是一个段落... </content> 

  对比JSON：

  "content": "# 这里是标题\n这是一个段落..." 

  就像写信 vs 发电报，XML天生适合人类阅读和流式输出。当LLM生成到</content>标签时，程序就能立刻截取内容写入文件，完全不需要等整个响应结束。

• • 实现流式写文件特性。
  • 人类友好的读取方式。
• • 这是 LLM 目前和 计算机程序"交流"的主要方式，就是将语言、文本这样的非结构化数据，转换为语义明确、字段清晰的结构化数据。
• 1. JSON， 代表的比如大名鼎鼎的 function_call 和 MCP
  2. XML
  3. 自定义的协议

• 严格的交互流程 (ReAct 模式) ：

• • 单工具调用 ：You can use one tool per message [source 3]。这强制 LLM 每次只执行一个动作，简化了状态管理和错误处理。
  • 逐步执行 ：You use tools step-by-step... each tool use informed by the result of the previous tool use [source 4]。这是典型的 ReAct 模式，LLM 根据上一步工具执行的结果（由 User Message 反馈）来决定下一步行动。
  • 思考过程 (<thinking> 标签) ：In <thinking> tags, assess what information you already have... Choose the most appropriate tool... [source 93-94]。要求 LLM 在调用工具前显式地进行思考和规划，这有助于提高决策的准确性，也方便调试。
  • 等待确认 ：ALWAYS wait for user confirmation after each tool use before proceeding. [source 107] Never assume the success of a tool use without explicit confirmation... [source 108]。这是保证 Agent 可靠性的关键。LLM 必须等待系统（模拟用户）反馈工具执行结果（成功、失败、输出内容、错误信息等）后才能继续。日志中的 [write_to_file ... Result:] [source 454] 就是这个确认环节。

• 工具使用指南 (实践经验) ：Prompt 中包含大量基于实践总结出的规则 [sources 93-114]，例如：

• • 优先使用特定工具而非通用命令 (list_files vs ls [source 96])。
  • 如何处理需要用户批准的操作 (requires_approval [source 15-17])。
  • 如何处理文件编辑中的 auto-formatting 问题 [sources 225-227]。
  • 这些都是在实际应用中不断打磨出来的宝贵经验，体现了 Agent 设计的迭代性。

3. MCP 服务 (Model Context Protocol)

[source: 115-207] MCP SERVERS (Detailed explanation, connected servers, creation example) 

展示了一个非常重要的 Agent 设计模式：**可扩展性** 和 **与外部系统/协议的集成**。

• 抽象接口 ：MCP 定义了一套协议，允许 Cline 与外部服务（MCP Server）通信，调用这些服务提供的工具 (use_mcp_tool [source 52-54]) 或访问资源 (access_mcp_resource [source 55-56])。这使得 Agent 的能力可以方便地扩展，而不需要修改核心 Agent 逻辑。
• 动态能力发现：当新的 MCP Server 连接后，它的工具和资源会动态地加入到 Agent 可用的能力列表中（体现在后续 Prompt 的更新中 [source 200]）。
• Agent 自我演化 (示例) ：Prompt 甚至详细指导了 LLM 如何 创建 和 编辑 MCP Server [sources 137-204]，这展示了一种更高级的 Agent 能力------Agent 可以根据需要编写代码来扩展自身的功能集。虽然这个例子（Weather Server [source 145-202]）比较复杂，但其思路是通用的：当现有工具不足时，Agent 可以尝试构建新的工具。
• 环境依赖注入：MCP Server 的配置（如 API Key [source 151, 195]）通过环境变量注入，这是一种安全且标准化的处理敏感信息和环境配置的方式 [source 141]。

所以，MCP 不仅仅是 Cline 的特定业务，它代表了 Agent 如何通过标准化协议与外部世界交互并动态扩展能力的通用设计思想。

4. 编辑文件 (File Editing Strategy)

[source: 208-234] EDITING FILES (Guidance on write_to_file vs. replace_in_file) 

这部分着重强调了文件操作的策略，特别是 write_to_file和replace_in_file 的选择 [sources 208-225]。这反映了 Agent 设计中对**精确性**和**鲁棒性**的考量：

• write_to_file [source 22-27, 210-217] ：覆盖写。适用于创建新文件或大范围重构。风险在于可能丢失未包含在内的原有内容。要求 LLM 必须提供 完整 的最终文件内容 [source 25-26]。
• replace_in_file [source 27-37, 218-222] ：精确查找替换。适用于小范围、目标明确的修改。更安全，不易出错，但需要 LLM 精确匹配 SEARCH 块的内容 [source 29]。
• 处理副作用 (Auto-formatting) ：Prompt 明确指出了编辑后文件可能被自动格式化 [sources 225-226]，并强调 LLM 必须基于格式化后的 最终文件内容 (final_file_content [source 454-468]) 进行后续操作，特别是 replace_in_file 的 SEARCH [source 227, 469-470]。这是处理 LLM 输出与实际环境状态同步的重要细节。

这种区分体现了对不同操作场景风险和效率的权衡，是 Agent 与文件系统交互时的常见设计要点。

5. PLAN & ACTION 模式 (Mode Switching)

[source: 235-252] ACT MODE V.S. PLAN MODE 

这部分引入了**模式切换**的概念，是处理复杂任务的一种有效策略。

• ACT MODE [source 236-238] ：默认模式，专注于执行任务，使用除 plan_mode_response 外的所有工具，最终目标是调用 attempt_completion。
• PLAN MODE [source 239-242] ：规划模式，用于与用户讨论、澄清需求、制定计划。此时主要使用 plan_mode_response [source 80-91] 进行对话，也可以使用信息收集类工具（如 read_file, search_files [source 245]）。目标是与用户达成一致的计划，然后由用户切换回 ACT MODE 执行。
• 目的：将任务的规划阶段和执行阶段分开。对于不明确或复杂的需求，先在 PLAN MODE 下充分沟通和设计，避免在 ACT MODE 中频繁出错或返工。这提高了交互效率和任务成功率。Prompt 还鼓励在 PLAN MODE 中使用 Mermaid 图表 [source 247, 249, 251] 来可视化计划。

6. 功能边界与能力 (Capabilities)

[source: 253-275] CAPABILITIES 

这部分明确了 Cline Agent 的核心能力范围，重申了如何利用各种工具（文件列表、代码定义、正则搜索、文件读写、命令执行、MCP）来完成编程相关的任务。 它还提到了初始上下文的重要性（启动时提供 CWD 文件列表 [source 255]），以及如何通过工具探索更广阔的环境（如 list_files 探索 CWD 之外的目录 [source 258, 260]）。

7. 硬性限制与规则 (Rules / Guardrails)

[source: 276-332] RULES 

这部分是 Agent 设计中最具实践性的地方，充满了从实际运行中总结出的"血泪教训"，目的是约束 LLM 的行为，避免常见错误，提高可靠性。关键规则包括：

• 环境限制 ：固定工作目录 (CWD) [source 276-277]，不能 cd，路径处理要小心 [source 277-278, 280-281]。
• 命令执行：考虑操作系统 [source 279]，处理好路径问题 [source 280-281]，解释命令 [source 269]，允许交互式/长时运行命令 [source 271]。
• 工具使用细节 ：search_files 的 regex 技巧 [source 282-286]，write_to_file 创建目录 [source 288]，replace_in_file 的精确匹配和顺序要求 [source 326-330]。
• 交互约束 ：直接行动，少问问题 [source 297, 300-303]，不要假设工具成功（必须等待确认！[source 331, 107-109]），不要进行闲聊或礼貌性套话 [source 308-314]，正确处理 environment_details [source 317-321]，注意正在运行的终端 [source 322-325]。
• 完成标志 ：任务完成后必须使用 attempt_completion [source 298]，且结果不能是问句或寻求进一步对话 [source 309-310]。

这些规则就像给 Agent 带上了"紧箍咒"，确保它在既定框架内可靠运行。

8. 系统信息 (System Information)

[source: 333] SYSTEM INFORMATION (OS, Shell, Home, CWD) 

提供关于运行环境的基本静态信息，帮助 Agent（尤其是 execute_command）做出正确的判断。

9. 目标 (Objective)

[source: 334-351] OBJECTIVE 

这部分是整个 Agent 工作流程的核心纲领，再次强调了其行为模式：

1. 分析任务，设定目标 [source 334]。
2. 顺序执行，一次一个工具 [source 335]。
3. 使用 <thinking> 标签进行推理 [source 339]：分析上下文 (environment_details [source 340]) -> 选择最合适的工具 [source 341] -> 检查参数是否齐全或可推断 [source 342-343]。
4. 参数不全则提问 ：如果缺少必要参数，使用 ask_followup_question [source 345]，而不是强行调用工具。
5. 完成任务后报告 ：使用 attempt_completion [source 347]，可附带演示命令 [source 348-350]。
6. 处理反馈：根据用户反馈进行迭代 [source 351]。

这清晰地描述了一个基于 ReAct 思想的 Agent 的工作循环：思考 -> 行动 -> 观察 (接收结果) -> 思考... 直到任务完成。

---

整体流程与交互分析

以下是根据参考文章的流程图用 Mermaid 语法写的时序图代码：

ReAct 循环实例 (日志分析)

1. User Task : 用户要求解释 servers/src/everything/ 目录，并将解释写入同目录的 EXPLANATION.md 文件 [source user_message_1]。用户还通过 <folder_content> 和 <file_content> 提供了该目录的结构和部分文件内容作为上下文 [source user_message_1]。
2. Assistant Thinking (Implicit) : Agent 分析任务和上下文，确定需要理解 TypeScript 代码、package.json、Dockerfile 等，然后将分析结果整理成 Markdown 格式。目标是创建一个新文件。
3. Assistant Action : Agent 选择 write_to_file 工具，提供目标路径 servers/src/everything/EXPLANATION.md 和生成的 Markdown 内容 [source assistant_message_1]。
4. System/User Observation : 系统执行 write_to_file，成功。然后将成功信息和最终写入的文件内容 (<final_file_content>) 返回给 Agent [source user_message_2]。
5. Assistant Thinking (Mistake) : Agent 看到写入成功，认为任务完成。但它没有遵循"必须使用 attempt_completion 来结束任务"的规则 [source 68, 347]，而是直接用自然语言回复表示完成 [source assistant_message_2]。
6. System Intervention : 系统检测到 Agent 未使用工具（特别是未用 attempt_completion），发出错误提示 [ERROR] You did not use a tool... [source 472-473]，并强制要求 Agent 重试并使用工具 [source 476]。
7. Assistant Thinking (Correction) : Agent 收到错误提示，理解到必须使用 attempt_completion 来正式结束任务。
8. Assistant Action (Expected Next Step) : Agent 应该调用 <attempt_completion> 工具，其 <result> 参数内容可以是类似它之前那个自然语言回复的总结。 (日志在这里中断，但这是预期的下一步)。

user's message 中的动态上下文

<environment_details> 确实像"上帝视角" [source 317-321]，它在 *每次* 用户回合结束时自动注入，提供了动态的环境快照：

• VSCode 可见文件/打开的标签页：让 Agent 了解用户当前的工作焦点。
• 当前工作目录 (CWD) 及文件列表：提供项目结构概览 [source 255-257]。
• 系统时间。
• 运行模式 (ACT/PLAN) [source 235]。
• 活动终端 (如果有) [source 322-325]。

此外，用户也可以像日志中那样，在任务描述中通过自定义标签（如 <folder_content>, <file_content>）主动注入更具体的上下文信息。这种 **动态上下文注入** 机制，结合 System Prompt 中的静态指令，使得 Agent 能够更好地理解当前状态并做出合理决策。

错误处理与强制规范

当Assistant忘记使用工具直接回复时，系统会立即弹窗警告：

[ERROR] You did not use a tool in your previous response! Please retry... 

并强制要求使用<attempt_completion>工具。这种设计就像给LLM戴上"紧箍咒"，确保它必须按照预定路线行进。

日志结尾的 [ERROR] 消息 [source 472] 完美展示了 Agent 设计中的强制规范执行。当 Agent 偏离预设规则（如此处未使用工具结束任务）时，系统会介入，给出明确的错误提示并引导其回到正轨。这对于保证 Agent 的行为符合预期、提高可靠性至关重要。这并非简单的惩罚，而是 ReAct 循环中的一个纠错环节。

总结

Cline 的设计展示了一套成熟的 AI Agent 构建思路：

1. 清晰的角色定位 (Persona) 。
2. 基于工具的行动能力 (Tools & ReAct) ：定义工具集，通过"思考-行动-观察"循环与环境交互。
3. 结构化的交互协议 (XML) ：保证 LLM 与程序间通信的可靠性。
4. 严格的执行规则与流程 (Guidelines, Rules, Objective) ：为 LLM 带上"镣铐"，确保按规矩办事。
5. 动态上下文感知 (Environment Details & User Injection) ：让 Agent 了解当前状态。
6. 模式切换 (Plan vs Act) ：应对不同任务阶段的策略。
7. 可扩展性 (MCP) ：通过标准化协议集成外部能力。
8. 精确的操作策略 (File Editing) ：权衡不同工具的风险和效率。
9. 强制的错误处理与规范执行：保证 Agent 不"脱轨"。

这些设计原则和实践，不仅让 Cline 成为一个强大的 AI 编码助手，也为我们设计其他领域的 AI Agent 提供了宝贵的参考。