我要投稿

从系统提示词看 Cline 和 MCP

发布日期：2025-03-22 07:41:06 浏览次数： 1783 作者：Diary of Owen

背景

最近在玩 Cline + MCP。

一个想法是接入 Etherscan 的 MCP Server，这样可以实现一些常规的链上信息查询。实际上 Ethereum GPT^[1] 就是用类似的方式实现的。然而搜索并没有发现成熟的实现，看来 Crypto 相比于 AI 还是小众太多了。

幸而找到了 openapi-mcp-server^[2]，可以将 OpenAPI spec 直接转化成对应的 MCP Server。然后又遇到一个坑是 Etherscan API 并没有 OpenAPI spec。好在继续搜索后找到了 etherscan-openapi^[3]，有人按照文档写了一份出来。

直接用 openapi-mcp-server 加载 etherscan-openapi31-bundled.yml，发现 Cline 直接报错 prompt is too long: 209582 tokens > 200000 maximum。

显然这个超长是 mcp server 相关的 prompt 导致的。接下来需要排查具体原因。

不想读代码，最直接的方式就是拦截一下与 LLM 通信的流量。在本地端口 8001启动一个 http server。同时修改 Cline 的 URL 为 http://localhost:8001

回到 Cline 随便问些什么，在 server 中可以拦截到如下请求：

POST /v1/messages?beta=prompt_caching 3317127 bytes

可以看到查询启用了 prompt_caching，并且发送了约 3MB 的超大请求数据。

Messages

查看实际的请求内容，从这个 message 请求构造中可以学到很多东西。

{
  "model": "claude-3-7-sonnet-20250219",
  "max_tokens": 8192,
  "temperature": 0,
  "system": ... // 系统提示词，非常长，后面介绍详细内容
  "messages": [ // 这是用户提示词
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          // 随便写的问题
          "text": "<task>\n查看当前的 gas price\n</task>"
        },
        {
          "type": "text",
          // VSCode 环境信息，帮助 AI理解当前问题的上下文
          "text": "<environment_details>\n
          
          # VSCode Visible Files\n 
          <VS Code 当前显示的文件路径>\n\n
          
          # VSCode Open Tabs\n
          <VSCode 打开的各种 tab 的文件路径>\n\n
          
          # Current Time\n
          <当前时间> \n\n
          
          # Current Working Directory 
          <当前文件夹>\n\n
          
          
          # Current Mode\n
          ACT MODE\n   
          # 这个是 Cline 的配置，支持 Plan / Act 两种模式，Plan 用于规划框架，Act 用于执行任务。
          
          </environment_details>"
        },
        {
          // 由于我这次任务是重试的，因此会一段提示词告诉 AI 之前任务中断过，许多状态信息可能是过时的，tool 调用也要重新运行一次。
          "type": "text",
          "text": "[TASK RESUMPTION] This task was interrupted 5 minutes ago. It may or may not be complete, so please reassess the task context. Be aware that the project state may have changed since then. The current working directory is now '<XXXX>'. If the task has not been completed, retry the last step before interruption and proceed with completing the task.\n\nNote: If you previously attempted a tool use that the user did not provide a result for, you should assume the tool use was not successful and assess whether you should retry. If the last tool was a browser_action, the browser has been closed and you must launch a new browser if needed."
        },
        {
          // 又是一遍 VSCode 环境信息 
          "type": "text",
          "text": "<environment_details>..</environment_details>",
          "cache_control": {
            "type": "ephemeral"
          }
        }
      ]
    }
  ],
  "stream": true
}

VSCode 环境信息的提供是个绝妙的主意，对用户体验提升极大。因为日常开发过程中遇到的问题及相关内容大概率都在当前已经打开的文件中。

System prompt

接下来看 system prompt。Cline 是开源的（不像 Cursor），因此可以直接在源码^[4]中读到同样的内容。

接下来一点点看

开头角色定义。

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

然后是关于 tool 的定义

# TOOL USE

You have access to a set of tools that 
are executed upon the user's approval. 
You can use one tool per message, and 
will receive the result of that tool 
use in the user's response. You use 
tools step-by-step to accomplish a 
given task, with each tool use 
informed by the result of the previous 
tool use.
# Tool Use Formatting

Tool use is formatted using XML-style 
tags. The tool name is enclosed in 
opening and closing tags, and each 
parameter is similarly enclosed within 
its own set of tags. Here's the 
structure:

<tool_name>
<parameter1_name>value1</parameter1_name>
<parameter2_name>value2</parameter2_name>
...
</tool_name>

For example:

<read_file>
<path>src/main.js</path>
</read_file>

Always adhere to this format for the 
tool use to ensure proper parsing and 
execution.

Claude 系列的提示词普遍用 xml 标签来表示结构化数据。OpenAI 的模型则对 json 格式适配更好。这可能也是 OpenAI 模型在 Cline 中表现不如 Claude 的原因之一。

接下来是 tools 具体定义

# Tools

## execute_command
Description: Request to execute a CLI 
command on the system. Use this when 
you need to perform system operations 
or run specific commands to accomplish 
any step in the user's task. You must 
tailor your command to the user's 
system and provide a clear explanation 
of what the command does. For command 
chaining, use the appropriate chaining 
syntax for the user's shell. Prefer to 
execute complex CLI commands over 
creating executable scripts, as they 
are more flexible and easier to run. 
Commands will be executed in the 
current working directory: <current 
work dir>
Parameters:
- command: (required) The CLI command 
to execute. This should be valid for 
the current operating system. Ensure 
the command is properly formatted and 
does not contain any harmful 
instructions.
- requires_approval: (required) A 
boolean indicating whether this 
command requires explicit user 
approval before execution in case the 
user has auto-approve mode enabled. 
Set to 'true' for potentially 
impactful operations like 
installing/uninstalling packages, 
deleting/overwriting files, system 
configuration changes, network 
operations, or any commands that could 
have unintended side effects. Set to 
'false' for safe operations like 
reading files/directories, running 
development servers, building 
projects, and other non-destructive 
operations.
Usage:
<execute_command>
<command>Your command here</command>
<requires_approval>true or false</requires_approval>
</execute_command>

其他 tools 细节就不列举了，只介绍一下功能：

read_file：读取文件
write_to_file：写入文件
replace_in_file：进行 patch diff（对于大文件可以节省 token，并且避免幻觉修改其他正常代码）。有时 patch 失败则会自动尝试 fallback 到 write_to_file。
search_files：根据内容查找文件
list_files：查看目录
list_code_definition_names：查看文件中定义的各种变量名，用于快速了解代码结构
browser_action：可以用 Puppeteer 启动一个 headless chrome 访问网页，并进行点击、滚动等操作。开启 --remote-debugging-port 获取浏览器渲染内容、截屏、console 中的输出等。对于编码前端代码自动调试非常有用。初次体验的时候还是蛮惊艳的。
use_mcp_tool：使用 MCP 工具
access_mcp_resource：获取 MCP 资源，这是 MCP 协议中定义的一种读取数据的方式
ask_followup_question：向用户提问。当 AI 发现自己的知识不足够解决当前问题时，会尝试让用户发问。这个 tool 其实比较关键，给了 AI 一个处理无法解决问题的出口，而不至于一本正经地胡说八道。
attempt_completion：结束当前 task，并对完成情况进行一个总结
plan_mode_response：在 plan mode 的结束时使用，给出详细的规划。

接下来是 Tool 的使用示例，这属于典型的 Few-Shot Prompting。

# Tool Use Examples

## Example 1: Requesting to execute a 
command

<execute_command>
<command>npm run dev</command>
<requires_approval>false</requires_approval>
</execute_command>

## Example 2: Requesting to create a 
new file
..
## Example 6: Another example of using 
an MCP tool (where the server name is 
a unique identifier such as a URL)

然后再补充一轮 Tool 使用的规则。

# Tool Use Guidelines

1. In <thinking> tags, assess what 
information you already have and what 
information you need to proceed with 
the task.
2. Choose the most appropriate tool 
based on the task and the tool 
descriptions provided. Assess if you 
need additional information to 
proceed, and which of the available 
tools would be most effective for 
gathering this information. For 
example using the list_files tool is 
more effective than running a command 
like `ls` in the terminal. It's 
critical that you think about each 
available tool and use the one that 
best fits the current step in the 
task.
3. If multiple actions are needed, use 
one tool at a time per message to 
accomplish the task iteratively, with 
each tool use being informed by the 
result of the previous tool use. Do 
not assume the outcome of any tool 
use. Each step must be informed by the 
previous step's result.
4. Formulate your tool use using the 
XML format specified for each tool.
5. After each tool use, the user will 
respond with the result of that tool 
use. This result will provide you with 
the necessary information to continue 
your task or make further decisions. 
This response may include:
  - Information about whether the tool 
succeeded or failed, along with any 
reasons for failure.
  - Linter errors that may have arisen 
due to the changes you made, which 
you'll need to address.
  - New terminal output in reaction to 
the changes, which you may need to 
consider or act upon.
  - Any other relevant feedback or 
information related to the tool use.
6. ALWAYS wait for user confirmation 
after each tool use before proceeding. 
Never assume the success of a tool use 
without explicit confirmation of the 
result from the user.

It is crucial to proceed step-by-step, 
waiting for the user's message after 
each tool use before moving forward 
with the task. This approach allows 
you to:
1. Confirm the success of each step 
before proceeding.
2. Address any issues or errors that 
arise immediately.
3. Adapt your approach based on new 
information or unexpected results.
4. Ensure that each action builds 
correctly on the previous ones.

By waiting for and carefully 
considering the user's response after 
each tool use, you can react 
accordingly and make informed 
decisions about how to proceed with 
the task. This iterative process helps 
ensure the overall success and 
accuracy of your work.

MCP

接下来进入 MCP Servers 的部分。所谓 MCP 全称为模型上下文协议(Model Context Protocol)，听起来比较抽象，实际上可以简单理解成 tool calling 的规范定义。使用相同规范实现的工具，可以被所有支持 MCP 的模型所调用。

下面仍是 system prompt 的内容，告诉 Cline 可以通过 use_mcp_tool 和 access_mcp_resource 访问 MCP Server。Connected MCP Servers 下会列出所有安装的 MCP Server。每个 MCP Server 下又分节 Available Tools，列出所有 MCP Server 中可以使用的 tool。目前我的 Cline 中只安装了名为 etherscan 的 MCP Server。

# MCP SERVERS

The Model Context Protocol (MCP) 
enables communication between the 
system and locally running MCP servers 
that provide additional tools and 
resources to extend your capabilities.

# Connected MCP Servers

When a server is connected, you can 
use the server's tools via the 
`use_mcp_tool` tool, and access the 
server's resources via the 
`access_mcp_resource` tool.

## etherscan (`npx openapi-mcp-server 
etherscan-mini.yml`)

### Available Tools
- API-get-ether-balance-for-a-single-address: 
Get Ether Balance for a Single Address
    Input Schema:
    { .... }

这个 etherscan mcp server 是通过 npx openapi-mcp-server etherscan-mini.yml 由 Etherscan 的 OpenAPI spec 生成的。

其中 API-get-ether-balance-for-a-single-address 就是一个 API 方法，Input Schema 中定义了这个方法的规范。由于原始的 spec 中使用了大量的引用（形如 "$ref": "#/$defs/AddressHash"），为了将每个 API 的定义独立抽取出来，openapi-mcp-server 会将所有引用在每个 API 中重复插入一遍。这导致每个 API 生成数千行的 API spec。加上 etherscan 有数十个 API 方法，直接导致 token 数量爆炸。这也是最初报错的原因。看来要解决这个问题，需要对 API Spec 进行一些精简。

除了关于如何调用 MCP Server 的 Prompt，System prompt 中还自带超长的 Creating an MCP Server 文档，用来介绍如何用 JS 写一个 MCP Server，其中甚至还包括一个完整的"获取天气信息"的 MCP Server 示例。这段 Prompt 在绝大多数非 MCP Server 开发者的开发过程中都不会用到，放在这里十分突兀。可能与 Claude 目前大力发展 MCP 生态有关。

至此 System prompt 还没有结束。它还补充介绍了一些规则、工作流程、思维方式等，包括：

EDITING FILES：重新细致介绍了如何使用 write_to_file 和 replace_in_file 两个工具。因为写文件是 AI Coder 场景下最为重要的功能。这里详细介绍了两个 tool 的差别、使用模式、选择策略等。
ACT MODE V.S. PLAN MODE：介绍两种工作模式的区别。PLAN MODE 的一个重点提示词是 deliver your response directly, rather than using <thinking> tags to analyze when to respond，告诉模型把推理过程展示给用户。
CAPABILITIES：概述性地介绍如何组合使用各种 tool 解决用户编程方面的问题。
RULES：介绍各种 tool 的使用规则；通用的回复规则等。
SYSTEM INFORMATION：当前的操作系统信息、工作目录等。
OBJECTIVE：介绍整体工作目标。