clz/openclaw-notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add MCP, plugin/LSP tool, and RAG notes

Browse Source 
- notes/mcp-overview.md: MCP 协议概览,跟 tool use 的分层差异
- notes/mcp-client-internals.md: MCP client 内部实现(发现/连接/catalog)
- notes/plugin-tools.md: plugin tool 与 native/MCP 的对比
- notes/lsp-tools.md: LSP 协议科普 + OpenClaw LSP tool 包装
- notes/rag-overview.md: RAG 与向量化(向量只用来检索,prompt 用原文)
- notes/blog/mcp-101.md: 面向开发者的 MCP 科普,LSP 类比引入
- README 索引更新
This commit is contained in:
clz
2026-06-16 00:59:32 +08:00
parent bc510c269b
commit 3c0cd86352
14 changed files with 2009 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.obsidian/core-plugins.json
Vendored
+3 -1
View File
@@ -27,5 +27,7 @@
"file-recovery": true,
"publish": false,
"sync": true,
"webviewer": false
"webviewer": false,
"footnotes": false,
"bases": true
}
.obsidian/workspace.json
Vendored
+13 -5
View File
@@ -13,12 +13,12 @@
"state": {
"type": "markdown",
"state": {
"file": "blog/function-call-101.md",
"file": "blog/mcp-101.md",
"mode": "source",
"source": false
},
"icon": "lucide-file",
"title": "function-call-101"
"title": "mcp-101"
}
}
]
@@ -142,13 +142,13 @@
"state": {
"type": "outline",
"state": {
"file": "blog/function-call-101.md",
"file": "blog/mcp-101.md",
"followCursor": false,
"showSearch": false,
"searchQuery": ""
},
"icon": "lucide-list",
"title": "function-call-101 的大纲"
"title": "mcp-101 的大纲"
}
}
],
@@ -160,6 +160,7 @@
},
"left-ribbon": {
"hiddenItems": {
"bases:新建数据库": false,
"switcher:打开快速切换": false,
"graph:查看关系图谱": false,
"canvas:新建白板": false,
@@ -170,9 +171,16 @@
},
"active": "d0cf7351ba09fde6",
"lastOpenFiles": [
"llm-autoregressive-kvcache.md",
"rag-overview.md",
"mcp-overview.md",
"mcp-client-internals.md",
"lsp-tools.md",
"blog/mcp-101.md",
"plugin-tools.md",
"blog/function-call-101.md",
"README.md",
"blog/README.md",
"llm-autoregressive-kvcache.md",
"function-call-flow.md",
"blog",
"skills-management-design.md",
README.md
+31
View File
@@ -37,4 +37,35 @@
LLM 自回归生成与 KV Cache：token 逐步生成的机制、prefill vs decode 阶段、
首 token 慢的原因，以及服务端 Prompt Cache 的命中条件与 OpenClaw 中保证顺序确定性的做法。
- [mcp-overview.md](./mcp-overview.md)
MCP（Model Context Protocol）概览:协议定位、OpenClaw 作为 MCP server
与 client 的两个方向、MCP 与 tool use 的分层差异(协议层 vs 实现层、
所有权与时机两根独立轴、plugin tool 反例)。
- [mcp-client-internals.md](./mcp-client-internals.md)
OpenClaw 作为 MCP client 的内部实现:server 发现(用户 config + plugin
manifest 合并)、连接时机(三种粒度的"启动"、attempt 引爆点)、
模型视角下的扁平 tool 列表、catalog 缓存与失效、JSON Schema 兼容/
content block 收敛/stdio env 过滤/失败退避等实现细节。
- [plugin-tools.md](./plugin-tools.md)
Plugin tool:OpenClaw 插件给 agent 注册的工具——TypeScript 写、同进程跑、
归插件作者拥有。`defineToolPlugin` 的 execute / factory 两种声明、
manifest-first 发现、Plugin SDK 边界、跟 channel/provider plugin 的关系、
跟 MCP tool 的关键对比,以及它在所有权 × 时机两根轴里"用户拥有 + 编译时确定"那一格的位置。
- [rag-overview.md](./rag-overview.md)
RAG(检索增强生成)概念整理:它解决什么问题、跟 fine-tuning/超长 context/
tool use 的对比、典型离线索引 + 在线检索两阶段流程,重点澄清两个常被混淆的问题
——向量化的结果是什么、拼进 prompt 的到底是向量还是原文(答案:数据库同时存
向量和原文,向量只用来"找",原文才是发给 LLM 的内容);常见坑(检索失败、切块
策略、embedding ≠ 相关性、评估),以及跟 MCP 的关系。
- [lsp-tools.md](./lsp-tools.md)
LSP tool:先科普 Language Server Protocol 是什么(IDE 世界里 M × N 问题
的标准解、跟 MCP 同源同构的 stdio + JSON-RPC 协议),再讲 OpenClaw 怎么
把 hover/definition/references 三个 LSP 方法包装成 agent tool、跟 MCP 和
plugin tool 平行的位置、以及当前只接受 plugin bundle 声明、用户 config
还没接通的现状限制。
完整官方文档:<https://docs.openclaw.ai>
blog/.obsidian/app.json
Vendored
+1
View File
@@ -0,0 +1 @@
{}
blog/.obsidian/appearance.json
Vendored
+1
View File
@@ -0,0 +1 @@
{}
blog/.obsidian/core-plugins.json
Vendored
+33
View File
@@ -0,0 +1,33 @@
{
"file-explorer": true,
"global-search": true,
"switcher": true,
"graph": true,
"backlink": true,
"canvas": true,
"outgoing-link": true,
"tag-pane": true,
"footnotes": false,
"properties": true,
"page-preview": true,
"daily-notes": true,
"templates": true,
"note-composer": true,
"command-palette": true,
"slash-command": false,
"editor-status": true,
"bookmarks": true,
"markdown-importer": false,
"zk-prefixer": false,
"random-note": false,
"outline": true,
"word-count": true,
"slides": false,
"audio-recorder": false,
"workspaces": false,
"file-recovery": true,
"publish": false,
"sync": true,
"bases": true,
"webviewer": false
}
blog/.obsidian/workspace.json
Vendored
+181
View File
@@ -0,0 +1,181 @@
{
"main": {
"id": "c5399a9acbb77689",
"type": "split",
"children": [
{
"id": "983bb3f03ba0267b",
"type": "tabs",
"children": [
{
"id": "d73d0bfd1d682067",
"type": "leaf",
"state": {
"type": "empty",
"state": {},
"icon": "lucide-file",
"title": "新标签页"
}
}
]
}
],
"direction": "vertical"
},
"left": {
"id": "65df11f83c8b6769",
"type": "split",
"children": [
{
"id": "78cc3f055f0cbebc",
"type": "tabs",
"children": [
{
"id": "77a689742a641c6d",
"type": "leaf",
"state": {
"type": "file-explorer",
"state": {
"sortOrder": "alphabetical",
"autoReveal": false
},
"icon": "lucide-folder-closed",
"title": "文件列表"
}
},
{
"id": "bfd0dd36c851aa00",
"type": "leaf",
"state": {
"type": "search",
"state": {
"query": "",
"matchingCase": false,
"explainSearch": false,
"collapseAll": false,
"extraContext": false,
"sortOrder": "alphabetical"
},
"icon": "lucide-search",
"title": "搜索"
}
},
{
"id": "368ed5ad7ec0d3ee",
"type": "leaf",
"state": {
"type": "bookmarks",
"state": {},
"icon": "lucide-bookmark",
"title": "书签"
}
}
]
}
],
"direction": "horizontal",
"width": 300
},
"right": {
"id": "8b36ffcad1340b80",
"type": "split",
"children": [
{
"id": "cb25124ebc9d68ef",
"type": "tabs",
"children": [
{
"id": "d2956a3ad0a6ce8e",
"type": "leaf",
"state": {
"type": "backlink",
"state": {
"collapseAll": false,
"extraContext": false,
"sortOrder": "alphabetical",
"showSearch": false,
"searchQuery": "",
"backlinkCollapsed": false,
"unlinkedCollapsed": true
},
"icon": "links-coming-in",
"title": "反向链接"
}
},
{
"id": "8dcc2f42bc2674ca",
"type": "leaf",
"state": {
"type": "outgoing-link",
"state": {
"linksCollapsed": false,
"unlinkedCollapsed": true
},
"icon": "links-going-out",
"title": "出链"
}
},
{
"id": "91e1edfbd442848d",
"type": "leaf",
"state": {
"type": "tag",
"state": {
"sortOrder": "frequency",
"useHierarchy": true,
"showSearch": false,
"searchQuery": ""
},
"icon": "lucide-tags",
"title": "标签"
}
},
{
"id": "33675859567823b1",
"type": "leaf",
"state": {
"type": "all-properties",
"state": {
"sortOrder": "frequency",
"showSearch": false,
"searchQuery": ""
},
"icon": "lucide-archive",
"title": "添加笔记属性"
}
},
{
"id": "4d537f742f8042ed",
"type": "leaf",
"state": {
"type": "outline",
"state": {
"followCursor": false,
"showSearch": false,
"searchQuery": ""
},
"icon": "lucide-list",
"title": "大纲"
}
}
]
}
],
"direction": "horizontal",
"width": 300,
"collapsed": true
},
"left-ribbon": {
"hiddenItems": {
"switcher:打开快速切换": false,
"graph:查看关系图谱": false,
"canvas:新建白板": false,
"daily-notes:打开/创建今天的日记": false,
"templates:插入模板": false,
"command-palette:打开命令面板": false,
"bases:新建数据库": false
}
},
"active": "d73d0bfd1d682067",
"lastOpenFiles": []
}
blog/README.md
+6
View File
@@ -8,3 +8,9 @@
Function Call 是什么、LLM 如何学会使用工具:从一个问题入手,
解释模型不执行工具、只输出结构化调用请求的本质,
并以 OpenClaw 源码为例说明工具声明、调用、执行的完整链路。
- [mcp-101.md](./mcp-101.md)
MCP 是什么、为什么 Function Call 之后还需要它:用 LSP 解决编辑器 × 语言
M × N 问题的类比引入,说清 MCP 跟 Function Call 是不同层(模型↔应用
vs 应用↔工具),澄清三个常见误解,并用 OpenClaw 源码示意 MCP server
怎么被发现、何时连接、模型如何看到扁平 tool 列表。
blog/mcp-101.md
+370
View File
@@ -0,0 +1,370 @@
# MCP 是什么？为什么 Function Call 之后还需要它
> 本文以 [OpenClaw](https://github.com/openclaw/openclaw) 开源源码为例
> (基于 2026.6.2 版本),结合实际代码说明 MCP 的工作原理和定位。
> 涉及源码路径均可在仓库中直接查阅。
如果你看过上一篇 [Function Call 101](./function-call-101.md),应该已经
知道 LLM 怎么"用工具"了:开发者把工具的 JSON Schema 塞进请求,模型决定
调哪个、传什么参数,代码负责真正执行。
那为什么 2024 年 Anthropic 又搞了一个叫 **MCP(Model Context Protocol)**
的东西?它跟 Function Call 是同一个东西吗?还是说 Function Call 不够用?
本文回答这两个问题。
---
## 从一个老问题说起
先看一个跟 AI 没关系的故事。
2016 年微软在做 VSCode 的时候,碰到一个头疼的事:
```
编辑器(M 个) 语言(N 种)
┌────────────┐ ┌──────────┐
│ VSCode │ ↔↔↔↔ │ Python │
│ Vim │ ↔↔↔↔ │ Go │
│ Emacs │ ↔↔↔↔ │ TypeScript│
│ Sublime │ ↔↔↔↔ │ Rust │
│ JetBrains │ ↔↔↔↔ │ Java │
└────────────┘ └──────────┘
```
每个编辑器都要给每种语言写一遍"hover 显示类型"、"跳转到定义"、
"查找所有引用"、"实时报错"...M 个编辑器 × N 种语言 = M × N 份
重复实现。这显然不可持续。
微软的解法是 **LSP(Language Server Protocol)**:把语言能力抽出来
变成一个独立的服务器进程,编辑器跟服务器用一套标准协议通信:
```
┌────────┐ LSP ┌──────────────┐
│ VSCode │ ←──JSON-RPC→│ tsserver │ ← TypeScript
└────────┘ └──────────────┘
┌────────┐ ┌──────────────┐
│ Vim │ ←──────────│ rust-analyzer│ ← Rust
└────────┘ └──────────────┘
```
现在变成 M + N:每个编辑器实现一次 LSP client,每种语言实现一次
LSP server。**`rust-analyzer` 一份能给所有支持 LSP 的编辑器用。**
记住这个故事。
---
## AI 工具集成的同样问题
现在回到 2024 年。当时已经有不少 AI 应用支持 Function Call,但每个
应用都在重复造轮子:
```
AI 应用(M 个) 工具(N 种)
┌────────────────┐ ┌──────────────┐
│ Claude Desktop │ ↔↔↔│ 读文件 │
│ ChatGPT App │ ↔↔↔│ 查数据库 │
│ Cursor │ ↔↔↔│ 调 GitHub API │
│ Codex │ ↔↔↔│ 操作 Notion │
│ 你的 agent │ ↔↔↔│ 控制浏览器 │
└────────────────┘ └──────────────┘
```
每个 AI 应用都要给每种工具写一遍 Function Call 的接入代码:
读文件、调 API、解析响应、错误处理。M × N 又来了。
你想要的是这样:把"读文件"这个能力写一次,Claude Desktop、Cursor、
你的 agent 都能用。
Anthropic 给的答案就是 MCP——**它对 AI 工具集成做的事,跟 LSP 对
编辑器语言支持做的事是一模一样的**。
---
## MCP 是什么
一句话:**MCP 是一个开放协议,让任何 AI 应用都能用一套标准的方式
接入任何外部工具。**
具体来说,MCP 定义了两个角色之间怎么通信:
- **Host**(主机):跑 LLM 的那一侧——Claude Desktop、Cursor、你写的
agent 框架
- **Server**(服务器):提供工具的那一侧——可以是本地子进程
(读文件、控浏览器),也可以是远端 HTTP 服务(Notion 集成、
GitHub 集成)
通信用 JSON-RPC 2.0,跑在 stdio 或 HTTP 之上。MCP server 暴露三类能力:
- **tools**:模型可以调的函数
- **resources**:可读的数据源
- **prompts**:可被引用的预制 prompt 模板
我们今天主要讲 tools。
跟 LSP 长得很像对吧?**stdio + JSON-RPC + 服务器自报能力**——某种意义上
MCP 就是 LSP 思路在 AI 时代的延续。
---
## 但是……Function Call 不是已经能干这件事了吗?
这是新手最容易卡住的地方。我们仔细看看。
### Function Call 是什么层面
Function Call 是**模型和应用之间的约定**:模型怎么"申请"调用一个
函数,应用怎么"执行"它再把结果回传。
```
┌─────────────────────────────┐
│ LLM (Claude / GPT 等) │
│ 输出 tool_use 请求 │ ← Function Call 层
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ 你的应用 │
│ 接到请求,跑函数,回传结果 │
└─────────────────────────────┘
```
这一层只回答了"模型怎么表达调用意图"。**它没规定函数本身是怎么
来的、是谁写的、怎么真正执行**。
### MCP 是什么层面
MCP 是**应用和工具实现之间的协议**:这个函数从哪儿来,代码在哪个
进程里跑,参数怎么传过去。
```
┌─────────────────────────────┐
│ LLM │
│ 输出 tool_use 请求 │ ← Function Call 层(没变)
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ 你的应用 │
│ - 收 tool_use │
│ - 转成 MCP 调用 │
└──────────────┬──────────────┘
│ JSON-RPC over stdio/HTTP
▼
┌─────────────────────────────┐
│ MCP server (子进程/远端) │ ← MCP 层
│ 跑函数,回结果 │
└─────────────────────────────┘
```
注意:**模型完全不知道 MCP 的存在**。它看到的还是一个普通的 tool 定义,
还是按 Function Call 的方式输出 `tool_use`。MCP 是中间那一层应用代码
的事——它把 tool 的"实现"从应用进程里挪到了独立的 MCP server 里。
### 一个类比
- Function Call ≈ "我要打个电话"——这是个抽象动作
- MCP ≈ "电话怎么拨通对方公司的总机,问到分机号,再接到具体的人"
——这是个具体协议
或者:
- Function Call ≈ 函数调用这个概念本身
- MCP ≈ gRPC / OpenAPI——让函数能跨进程跨语言被发现和调用的具体协议
**MCP 不替代 Function Call,它给 Function Call 加了一个"工具供应链"。**
---
## MCP 实际带来了什么
讲了这么多概念,看看实际效果。
### 1. 工具一次写好,所有 AI 应用都能用
`@modelcontextprotocol/server-filesystem` 是社区的一个 MCP server,
让 AI 能读文件、列目录、搜文件。装一次:
```bash
npx @modelcontextprotocol/server-filesystem ~/Documents
```
然后 Claude Desktop、Cursor、OpenClaw 都能直接用上它,不用各自实现
一遍文件操作工具。**这就是 M + N 而不是 M × N。**
### 2. 工具的提供者跟 AI 应用作者解耦
Notion 想给 AI 助手提供集成?以前要等每家 AI 应用主动接入,或者发
SDK 给开发者集成。现在 Notion 自己跑一个 MCP server,任何支持 MCP
的应用都能用。
### 3. 工具能跨语言、跨进程
MCP server 可以是 Python、Go、Rust、任何能讲 JSON-RPC 的语言写的。
你的 AI 应用是 Node.js,但工具实现可以是 Python——只要双方说 MCP 就行。
### 4. 故障隔离
MCP server 跑在独立进程里(或者远端),一个 server 崩了不会拖死整个
AI 应用。可以单独重启、单独限流、单独配置超时。
---
## 看看 OpenClaw 怎么做的
OpenClaw(一个开源 AI agent 框架)的代码可以当作 MCP 的具体落地示例。
### MCP server 怎么"加进来"
OpenClaw 不去网络扫描发现 MCP server,**全靠声明式 config**。两个来源:
**1. 用户写在 `~/.openclaw/openclaw.json` 里:**
```json
{
"mcp": {
"servers": {
"filesystem": {
"command": "npx",
"args": ["@modelcontextprotocol/server-filesystem", "/home/user"]
},
"github": {
"url": "https://mcp.github.com",
"transport": "streamable-http",
"auth": "oauth"
}
}
}
}
```
**2. 插件作者预置:** 装一个 OpenClaw plugin 时,它可能自带几个
MCP server 配置(`src/plugins/bundle-mcp.ts`)。
两个来源在 `src/agents/bundle-mcp-config.ts` 里合并,**用户 config
能覆盖 plugin 默认**。
### 什么时候真的连接 MCP server?
这是个有意思的设计选择。OpenClaw 的策略:**进程启动时不连接、每次
模型轮次开始时连接**。
为什么?因为模型必须在请求里就看到全部 tool 才能决定调哪个,所以
连接不能拖到模型真的调用某个 tool 时再做(那时候 tool 列表都没
组装好)。但又没必要在 OpenClaw 启动时就把所有 MCP server 都拉起来
(可能配了 20 个,这次对话其实只用 2 个)。
折衷点是 **agent 一轮模型请求开始时**:这时候必须把所有 MCP server
都 spawn、`tools/list`、拿到工具目录,然后把工具塞进发给模型的
tool 列表里。
```ts
// 简化版,真实代码在 src/agents/embedded-agent-runner/run/attempt.ts
const mcpRuntime = await materializeBundleMcpToolsForRun({...});
// 这里 MCP server 已经 spawn 完了,tool 也都拿到了
const tools = [...nativeTools, ...mcpRuntime.tools];
// 发给模型
sendRequest({ tools, ... });
```
### 模型看到的是什么
**一个扁平的 tool 数组,跟 native tool 长得完全一样:**
```json
[
{ "name": "Read", "description": "...", "input_schema": {...} },
{ "name": "Bash", "description": "...", "input_schema": {...} },
{ "name": "filesystem__read_file", "description": "...", "input_schema": {...} },
{ "name": "github__list_issues", "description": "...", "input_schema": {...} }
]
```
注意 `filesystem__read_file` 这种 `serverName__toolName` 的命名是为了
防止重名。模型完全不知道哪些来自 MCP、哪些是 OpenClaw 写死的;它只
根据 `description` 和 schema 做语义匹配,挑一个最合适的。
### 模型调用时发生什么
模型返回 `tool_use: filesystem__read_file`,OpenClaw 在 tool 列表里
找到对应条目,它的 `execute` 函数会调 `client.callTool("read_file", input)`,
通过早就建立好的 stdio 连接发给 MCP server,server 跑完返回结果,
OpenClaw 再把结果回传给模型。
整个过程模型一无所知——它只觉得自己"调了个工具,得到了结果"。
---
## 关键澄清:几个常见误解
### 误解 1:"MCP 是给模型用的协议"
**不是。MCP 是给应用用的协议。** 模型那一侧永远是 Function Call,
看到的就是普通 tool 定义。MCP 是应用怎么"获取这些 tool 定义、怎么
真正执行 tool"的事。
### 误解 2:"用了 MCP 就不用 Function Call 了"
**Function Call 永远在用。** MCP server 提供的 tool,最终还是要包装
成 Function Call 的格式发给模型。两者不是 A 替代 B,而是 A 之上又加
了一层 B。
### 误解 3:"native tool 落后了,MCP 才是未来"
**不一定。** 跟应用深度耦合的工具(比如 OpenClaw 的 `Read`、`Bash`)
做成 native tool 启动快、故障少、能直接用 host 内部能力;MCP 的优势在
**跨应用复用** 和 **可独立分发**。两者各有适用场景。
OpenClaw 自己就同时有 native tool、plugin tool、MCP tool,模型看见
的是同一个扁平列表,不区分。
---
## 那 MCP 现在能用来干什么
一些实际的应用方向:
- **本地工具**:文件系统、Git、Docker、SQLite——`@modelcontextprotocol/server-*`
系列已经有不少现成的
- **远端 SaaS 集成**:Notion、Linear、Slack、GitHub——越来越多 SaaS
在做官方 MCP server
- **企业内部工具**:把内部数据库查询、运维脚本包装成 MCP server,
团队所有 AI 助手都能用
- **跨工具协作**:同一个 agent 同时接文件系统 + GitHub + Notion 的 MCP server,
可以读本地代码、查 issue、写文档
---
## 总结
回到开头的问题:**MCP 跟 Function Call 是什么关系?**
```
Function Call:模型 ←→ 应用 之间怎么调函数
MCP: 应用 ←→ 工具 之间怎么提供函数
```
Function Call 解决"模型怎么用工具"。MCP 解决"工具从哪儿来、怎么跨应用
复用"。两者各管一层,组合起来才是完整的故事。
LSP 当年解决了编辑器 × 语言的 M × N 问题,让 `rust-analyzer` 这种
高质量语言服务器能服务所有编辑器。MCP 试图解决 AI 应用 × 工具的同样
问题,让一个 MCP server 能服务所有 AI 助手。
它能不能像 LSP 那样成为事实标准,还要看生态——但思路是清晰的:
**把工具实现从单个应用里抽出来,变成可复用的独立组件**。
---
## 想深入了解?
- MCP 规范:<https://modelcontextprotocol.io>
- 看 OpenClaw 怎么实现 MCP client 的:
- 配置和发现机制
- 何时连接、catalog 怎么暴露给模型
- 缓存、失效、安全细节
这部分在 OpenClaw 仓库的 `src/agents/agent-bundle-mcp-*.ts`,
以及 `notes/mcp-client-internals.md`。
lsp-tools.md
+224
View File
@@ -0,0 +1,224 @@
# LSP Tool
基于 [OpenClaw](https://github.com/openclaw/openclaw) 2026.6.2 版本源码。
本文先讲 **LSP(Language Server Protocol)是什么**——它是 IDE 世界里
一个很重要的协议,但跟 AI 领域关系不大,所以单独介绍——再讲 OpenClaw
怎么把它包装成 agent 的 tool。
## LSP 是什么
### 它解决什么问题
写编辑器的人原来面临一个 M × N 问题:
```
编辑器 (M 个) 语言支持 (N 种)
┌────────────┐ ┌──────────┐
│ VSCode │ ↔↔↔↔ │ Python │
│ Vim │ ↔↔↔↔ │ Go │
│ Emacs │ ↔↔↔↔ │ TypeScript│
│ Sublime │ ↔↔↔↔ │ Rust │
│ JetBrains │ ↔↔↔↔ │ Java │
└────────────┘ └──────────┘
```
每个编辑器都得给每种语言写一遍 "hover 显示类型"、"跳转到定义"、
"查找所有引用"、"实时报错"...这些功能。M 个编辑器 × N 种语言 =
M × N 份重复实现。
LSP 是微软 2016 年提出的解法:**把"语言能力"抽出来变成一个独立的
服务器进程**,编辑器和服务器之间用一套标准协议通信。
```
编辑器 Language Server
┌────────┐ LSP ┌──────────────┐
│ VSCode │ ←─────JSON-RPC→│ tsserver │ ← TypeScript
└────────┘ └──────────────┘
┌────────┐ ┌──────────────┐
│ Vim │ ←──────────────│ gopls │ ← Go
└────────┘ └──────────────┘
┌────────┐ ┌──────────────┐
│ Emacs │ ←──────────────│ rust-analyzer│ ← Rust
└────────┘ └──────────────┘
```
现在变成 M + N:每个编辑器实现一次 LSP client,每种语言实现一次
LSP server。VSCode 装 Rust 插件 = 它在 VSCode 端走 LSP client,
背后跑一个 `rust-analyzer` 进程。
### 协议形态
LSP 用 JSON-RPC 2.0,跑在 stdio 之上(也支持其他 transport,但 stdio
是默认)。消息分帧用 HTTP 风格的 Content-Length header:
```
Content-Length: 213\r\n
\r\n
{"jsonrpc":"2.0","id":1,"method":"textDocument/hover","params":{...}}
```
典型方法名:
- `initialize` — 握手,client 告诉 server 自己支持什么,
server 回 capabilities(支不支持 hover、definition 等)
- `textDocument/didOpen` / `didChange` / `didClose` — 通知文件状态
- `textDocument/hover` — 给我光标位置的类型/文档
- `textDocument/definition` — 跳转到定义
- `textDocument/references` — 找所有引用
- `textDocument/completion` — 自动补全
- `textDocument/publishDiagnostics` — server 主动推:这里有错
每个方法的参数和返回值都在 LSP 规范里固定下来,所以一个 LSP server
可以同时被 VSCode、Vim、Emacs 用。
### 跟 MCP 的对照
| 维度 | LSP | MCP |
| ------------- | -------------------------------- | ------------------------------------ |
| 目标受众 | IDE / 编辑器 | LLM 应用 |
| 服务器干啥 | 提供代码分析(hover/跳转/补全) | 提供任意工具(读文件/查搜索/...) |
| 方法集合 | 固定一套 `textDocument/*` 等 | server 自己声明 `tools/list` |
| 协议层 | JSON-RPC 2.0 + Content-Length | JSON-RPC 2.0 |
| 提出者 | 微软 | Anthropic |
| 年份 | 2016 | 2024 |
两个协议**长得很像**(stdio + JSON-RPC),解决的是不同领域的同一种
M × N 问题——把可复用的能力(代码分析 / agent 工具)抽到独立进程。
某种意义上 MCP 是 LSP 思路在 AI 时代的延续。
## OpenClaw 怎么用 LSP
核心实现 `src/agents/agent-bundle-lsp-runtime.ts`,第一行注释:
> Minimal LSP JSON-RPC framing over stdio (Content-Length header + JSON body).
不是用现成的 LSP client 库,而是自己在 OpenClaw 里实现了 LSP 协议的
最小子集(Content-Length 分帧 + JSON-RPC),spawn 语言服务器子进程,
跑 `initialize` 握手拿能力。
### 暴露的 tool
根据语言服务器 `initialize` 返回的 capabilities 动态生成
(`agent-bundle-lsp-runtime.ts:317` `buildLspTools`):
| Tool 名 | LSP 方法 | 用途 | capability 门槛 |
| -------------------------- | ------------------------- | ----------------- | --------------------- |
| `lsp_hover_<server>` | `textDocument/hover` | 看符号的类型/文档 | `hoverProvider` |
| `lsp_definition_<server>` | `textDocument/definition` | 跳到定义 | `definitionProvider` |
| `lsp_references_<server>` | `textDocument/references` | 找所有引用 | `referencesProvider` |
如果语言服务器没声明对应 capability(比如 `hoverProvider: false`),
对应 tool 就不会被注册。
工具参数都长一样(`uri: string, line: number, character: number`),
因为 LSP 协议本身就是这套 `textDocument + position` 的形态。
**注意没有 completion**:agent 不需要交互式补全,它直接看完整文件就行。
OpenClaw 只挑了"看完整代码不能直接得到的语义信息"做工具——hover 拿
推断类型,definition/references 需要跨文件 AST 跳跃。
### 跟 MCP / plugin 平行
| 维度 | LSP tool | MCP tool | plugin tool |
| -------------- | ----------------------- | --------------------------- | --------------------------- |
| 协议 | LSP(`textDocument/*`) | MCP(`tools/call`) | OpenClaw Plugin SDK |
| 进程 | stdio 子进程 | stdio 子进程 / HTTP | 同进程 |
| Tool 名 | hardcode 三个 + server 后缀 | server 自报 `tools/list` | plugin 代码静态声明 |
| 配置来源 | bundle plugin manifest | bundle plugin + 用户 config | plugin manifest |
| 用户能加吗 | 现在不能 | 能(`openclaw mcp add`) | 装新 plugin 即可 |
| Catalog 动态性 | **静态**(三个固定 tool) | **动态**(server 决定) | 静态 |
| 模型视角 | 跟其他 tool 没区别 | 跟其他 tool 没区别 | 跟其他 tool 没区别 |
跟 MCP 最大不同:**LSP 的 tool 集是 OpenClaw 写死的**(hover/definition
/references 三个),只是是否启用看 server capability。MCP 是 server
想暴露啥就 `tools/list` 出啥,完全运行时决定。
这是 LSP 协议本身决定的——LSP 的方法集就那么固定一套,不像 MCP
让 server 自由声明工具。OpenClaw 只是把 LSP 方法**翻译**成 agent
理解的 tool。
### 在 attempt 时序里
跟 MCP 完全平行(回看 [mcp-client-internals.md](./mcp-client-internals.md)
的 "Attempt 引爆点"):
```ts
// src/agents/embedded-agent-runner/run/attempt.ts:1502-1549
const bundleMcpRuntime = bundleMcpSessionRuntime
? await materializeBundleMcpToolsForRun({...})
: undefined;
bundleLspRuntime = bundleLspEnabled
? await createBundleLspToolRuntime({...}) // ← LSP 在这里 spawn + initialize
: undefined;
const allowedBundleMcpTools = applyEmbeddedAttemptToolsAllow(bundleMcpRuntime?.tools ?? [], ...);
const allowedBundleLspTools = applyEmbeddedAttemptToolsAllow(bundleLspRuntime?.tools ?? [], ...);
const allowedBundledTools = [...allowedBundleMcpTools, ...allowedBundleLspTools];
```
每次 attempt 开始时,两条 runtime 各自独立 spawn(MCP / LSP),
各自维护 session,各自 dispose;最后合到同一个扁平 tool list 给模型。
## 典型用例
模型要回答 "把 `runEmbeddedAttempt` 的所有调用方都列出来"。可能的工具组合:
1. `Grep "runEmbeddedAttempt"` ——快,但会被注释、字符串、相似名字误伤
2. `lsp_references_typescript` ——准,基于 AST 分析,但要先定位符号的
精确 `(uri, line, character)`
3. 常见组合:先 `Grep` 找出大致位置 → `Read` 确认 → `lsp_references_typescript`
拿精确引用列表
LSP tool 的价值在于 **精确度**——code intelligence 这件事 grep 替代不了:
- `Grep` 找的是文本匹配,会把字符串字面量、注释里的同名词都算进来
- `lsp_references` 走 AST + 类型系统,能区分 `foo.runEmbeddedAttempt`
调的是哪个 `foo`,跨 import 跳得对
类似地 `lsp_hover` 拿 inferred type 是 grep / read 替代不了的——
TypeScript 的 `const x = foo()` 你想知道 `x` 是啥类型,只有 tsserver
能告诉你。
## 配置怎么写
跟 MCP server 一样,LSP server 从 plugin bundle manifest 读
(`src/plugins/bundle-lsp.ts`、`src/agents/embedded-agent-lsp.ts`),
plugin 在自己的 manifest 里声明 `lspServers`,字段形态跟 MCP 的
stdio server 几乎一样(`command`、`args`、`env`、`cwd`)。
OpenClaw 实际上**复用了 MCP 的 stdio launch config 结构**——
`agent-bundle-lsp-runtime.ts` 里直接 import 了 `resolveStdioMcpServerLaunchConfig`
和 `describeStdioMcpServerLaunchConfig`,因为两者都是 "spawn 一个本地
stdio 子进程跑 JSON-RPC",launch 部分可以共享。
## 现状的限制
`src/agents/embedded-agent-lsp.ts:22` 有一条注释:
> User-configured LSP servers could override bundle defaults here in the future.
意思是**当前只接受 plugin bundle 声明的 LSP server**,用户 config 还
没接通。MCP 已经走得更远(用户 config 可以加自己的 server),LSP 还
停在 plugin 预置的阶段。
退避逻辑也比 MCP 简化——没有 "连续 3 次失败冷却 60s" 这种保护,
失败就直接报错给 agent。
## 心智模型一句话
LSP 是把 "编辑器智能" 抽出来的协议,跟 MCP 是把 "agent 工具" 抽出来的
协议同源同构(stdio + JSON-RPC + 服务器自报能力)。OpenClaw 借了 LSP
这套现成的代码分析基础设施,把 hover/definition/references 三个最有
agent 价值的能力包装成 tool,放进 agent 的扁平 tool 列表里。模型层面
跟其他 tool 没任何区别。
## 相关
- [mcp-overview.md](./mcp-overview.md) — MCP 协议本身
- [mcp-client-internals.md](./mcp-client-internals.md) — MCP client
的内部实现,LSP 在 attempt 时序里跟它平行
- [plugin-tools.md](./plugin-tools.md) — plugin tool,LSP server 的
配置来源就是 plugin bundle
mcp-client-internals.md
+297
View File
@@ -0,0 +1,297 @@
# OpenClaw 作为 MCP client:内部实现
基于 [OpenClaw](https://github.com/openclaw/openclaw) 2026.6.2 版本源码。
本文专讲 OpenClaw 作为 MCP client 那一侧的实现:server 怎么被发现、
何时连接、tool catalog 怎么暴露给模型、怎么缓存与失效、有哪些值得注意的
安全/兼容细节。
MCP 是什么、和 tool use 的关系、`openclaw mcp serve` 那一侧的实现见
[mcp-overview.md](./mcp-overview.md)。
## 整体生命周期
```
[发现] 读 config + plugin manifest → 一份 server map
(进程启动 / session 创建时纯 JSON 读,不 spawn)
↓
[连接] attempt 开始触发 getCatalog
→ resolveMcpTransport
→ connectWithTimeout (stdio spawn / http 握手)
→ client.listTools()
↓
[暴露] buildBundleMcpToolsFromCatalog
→ MCP tool 包装成 AnyAgentTool(name 加 server 前缀)
→ 跟 native / plugin / LSP tool 合到同一个数组
→ 发给 LLM
↓
[调用] 模型返回 tool_use → 找到 AnyAgentTool
→ execute → client.callTool()
→ 走早就建立好的 transport
↓
[缓存与失效] 同 session 的后续 attempt 复用 catalog;失效条件:
idle TTL / listChanged / 连续失败冷却
```
## MCP server 的发现
简短答案:**没有"扫描发现",全靠声明式 config**。OpenClaw 从两个来源
合并出 MCP server 列表。
### 两个来源
**1. 用户 config:`openclaw.json` 的 `mcp.servers`**
类型定义在 `src/config/types.mcp.ts`:
```ts
export type McpConfig = {
servers?: Record<string, McpServerConfig>;
sessionIdleTtlMs?: number;
};
```
用户通过 CLI(`openclaw mcp add/set/configure/...`)或直接编辑文件,
往 `~/.openclaw/openclaw.json` 里写入条目。CLI 实现在
`src/cli/mcp-cli.ts`,读写在 `src/config/mcp-config.ts`。
**2. 已启用的 bundled plugin 自带的 MCP 定义**
每个 plugin 在自己的 manifest 里可以声明附带的 MCP server,加载逻辑
在 `src/plugins/bundle-mcp.ts`:
- `loadEnabledBundleMcpConfig` 遍历 `manifestRegistry` 里所有
**enabled** 的 plugin
- 对每个 plugin 调 `loadBundleMcpConfig`:
1. 读 plugin 的 manifest(`claude` / `codex` / `cursor` 三种格式之一)
2. 解析其中 `mcpServers` 字段声明的相对路径列表
3. 如果 plugin 根目录存在 `.mcp.json` 也自动加入
4. 把这些文件里的 server 定义和 manifest 里的 inline `mcpServers`
merge 起来
- 路径里的 `${CLAUDE_PLUGIN_ROOT}` 占位符会被替换成 plugin 根目录
### 合并优先级
两个来源在 `src/agents/bundle-mcp-config.ts` 的 `loadMergedBundleMcpConfig`
里合并:
```ts
mcpServers: {
...enabledBundleMcp, // plugin 自带的(底)
...enabledConfiguredMcp, // 用户 config 的(覆盖在上)
}
```
规则:
1. **同名 server**,用户 config 覆盖 plugin 默认(注释里明确说
"OpenClaw config 是 owner-managed layer")
2. 用户 config 里 `enabled: false` 不仅排除自己,还能**屏蔽掉
同名的 bundled server**(`disabledConfiguredNames` 集合)
3. 一次性的 embedded agent run 通过 `loadEmbeddedAgentMcpConfig`
(`src/agents/embedded-agent-mcp.ts`)拿到最终 merged 结果
### 发现链路
```
启动 / 每次 session
│
├─ getRuntimeConfig() ← 读 ~/.openclaw/openclaw.json
│ └─ cfg.mcp.servers ← 用户层
│
├─ PluginManifestRegistry.plugins ← 已发现的 plugin manifest
│ └─ 每个 plugin 的 .mcp.json /
│ manifest mcpServers ← plugin 层
│
└─ loadMergedBundleMcpConfig({ cfg, manifestRegistry, workspaceDir })
↓
{ mcpServers: { name → config } } ← 最终 server 列表(还没 spawn)
```
### 发现性质
1. **完全声明式**:OpenClaw 不去网络扫描、不去 ServiceDiscovery、
不去 mDNS——所有 server 必须显式写在某个 config 文件里
2. **plugin 是隐式来源**:用户装个 plugin,可能就"被"得到几个 MCP
server,这是 plugin 作者预置的
3. **Config 是 process-stable**:根 `AGENTS.md` 的架构约定——
MCP server 列表在进程启动后视为稳定,改了 config 要
`openclaw mcp reload` 或重启 agent
4. **server 列表的"发现"和 tool 的"发现"是两层**:
- server 列表:**静态**(读 config + plugin manifest)
- 每个 server 的 tool:**动态**(运行时 `tools/list`,还支持
`listChanged` 通知)
所以严格说,OpenClaw 作为 MCP client 对 **server** 是静态发现,
对 **tool** 是动态发现。
## 何时连接
关键澄清:**"懒"是相对"OpenClaw 启动"懒,不是相对"模型调用"懒**。
每次 agent attempt(模型一轮请求)开始时,MCP server 会**先全部
spawn + listTools**,然后 tool catalog 才被塞进发给模型的 tool 列表里。
### 三种粒度的"启动"
| 粒度 | 何时发生 | 状态 |
| ----------------------------- | ----------------------- | ----------------------------------------------------- |
| OpenClaw 进程启动 | `openclaw` 命令开始跑 | **不连接任何 MCP** |
| Session 创建 | 用户第一次说话 | **不连接**(只准备 runtime 壳子) |
| Attempt 开始(每轮模型请求) | 准备给模型发请求 | **必须连接 + listTools**(否则模型不知道有哪些 tool) |
| Tool 实际调用 | 模型返回 tool_use | **走已建立的连接** |
"懒到模型调用时再连接"是不行的——模型必须在请求里就看到全部 tool
才能决定调哪个。OpenClaw 的折衷点在 "attempt 开始" 这一步:对每个会话,
只在它真有 attempt 时才连(避免无对话的会话开销),但一旦要 attempt,
必须先把 catalog 凑齐。
### Attempt 引爆点
`src/agents/embedded-agent-runner/run/attempt.ts:1502` 这段是关键——
**模型还没被调用前**,这段已经把 MCP 全部 spawn 完了:
```ts
const bundleMcpSessionRuntime = bundleMcpEnabled
? await getOrCreateSessionMcpRuntime({...}) // 拿 runtime(可能复用)
: undefined;
bundleMcpRuntime = bundleMcpSessionRuntime
? await materializeBundleMcpToolsForRun({ // ← 这里触发 getCatalog
runtime: bundleMcpSessionRuntime,
reservedToolNames: [...],
})
: undefined;
```
紧接着 `attempt.ts:1535` 把 MCP tool 合到 `allowedBundledTools`,后面跟
native tool 一起发给模型。
### 完整时间线
```
进程启动 → 读 config,记下"理论上有哪些 server",不 spawn
session 创建 → runtime 壳子,sessions=空,catalog=null
attempt 开始 → getCatalog():
├─ for 每个 server:
│ - resolveMcpTransport
│ - connectWithTimeout (stdio spawn / http 握手)
│ - client.listTools()
└─ 拼成 catalog
buildBundleMcpToolsFromCatalog():
把每个 MCP tool 包装成 AnyAgentTool
(name = "serverName__toolName")
组装 LLM 请求 → tools = [...native, ...plugin, ...mcp]
LLM 收到请求 → 看到 N 个 function 定义,只看 name/description/schema
LLM 返回 → tool_use: "filesystem__read_file"
执行 → 在 tool 列表里找到对应 AnyAgentTool,
调它的 execute → runtime.callTool() → 已建立的 transport
```
## 模型视角:一个扁平的 tool 列表
**模型不知道"MCP"这个概念**。它只看到一个 tool 数组,每个 tool 形如:
```json
{
"name": "filesystem__read_file",
"description": "Read contents of a file. Returns text content...",
"input_schema": { "type": "object", "properties": { "path": {...} } }
}
```
跟 `Read`、`Bash` 这种 native tool 在请求里**完全是同一形状**。区别仅在:
- **来源不同**:native 是代码里写的,MCP 是从 `client.listTools()` 拉来的
- **名字有前缀**:`buildSafeToolName` 给 MCP tool 加 `serverName__` 前缀
避免重名,native tool 没这个前缀
- **execute 走向不同**:native 在本进程跑,MCP 走 `client.callTool()`
到子进程/HTTP
`attempt.ts:1535-1549` 那段把所有来源 concat 起来:
```ts
const allowedBundleMcpTools = applyEmbeddedAttemptToolsAllow(
bundleMcpRuntime?.tools ?? [], ...
);
const allowedBundleLspTools = applyEmbeddedAttemptToolsAllow(
bundleLspRuntime?.tools ?? [], ...
);
const allowedBundledTools = [...allowedBundleMcpTools, ...allowedBundleLspTools];
```
native tool、plugin tool、MCP tool、LSP tool 全部以 `AnyAgentTool[]`
形式 concat,经过 provider adapter(Anthropic / OpenAI / Google)翻译
成各自的 tool schema,塞进同一个请求的 `tools` 字段。
模型挑哪个工具是**纯粹基于 `description` 和 schema 跟用户意图的语义
匹配**——跟它怎么挑 `Read` 还是 `Bash` 同一个机制。
### 扁平化的几个微妙后果
1. **模型可能"搞错来源"**——装了一个 `memory__write` 的 MCP 工具,
模型在该用 native `Write` 写文件时可能调了 `memory__write`,只因
后者 description 更像当下意图。这就是为啥 MCP server 的 `description`
写得好不好直接影响 agent 效果。
2. **名字前缀是唯一的"出身标签"**——`buildSafeToolName` 加 `serverName__`
前缀(`agent-bundle-mcp-materialize.ts`),既防重名,也无意中给
模型一点"分组信号"。但模型不会被告知 `__` 前面是 server 名,它只是
把整个名字当字符串看。
3. **工具排序影响行为**——`agent-bundle-mcp-materialize.ts` 显式
`tools.sort(...)` 是为了让同一份 catalog 在不同 turn 里给模型呈现的
顺序一致(对 prompt cache 命中重要,见根 `AGENTS.md` 里
"deterministic ordering" 那条)。不排序时顺序漂移会让 prompt
字节级别变化,KV cache 失效。
4. **tool filter 是预算工具**——`toolFilter.include/exclude` 在 catalog
阶段就过滤掉,模型完全感知不到"被屏蔽"的工具存在。这是抑制模型
乱调 MCP 工具的主要手段。
一句话:**对 LLM 来说,世界是扁平的一组 function;MCP 是 OpenClaw 这
一层的实现细节,跨过 provider boundary 之后就消失了。**
## Catalog 缓存与失效
`agent-bundle-mcp-runtime.ts` 的 `getCatalog` 有缓存——同一个 session 的
后续 attempt **不再重新 listTools**,直接复用 catalog。
失效条件:
- session 空闲超过 `mcp.sessionIdleTtlMs`(默认 10 分钟)被回收,
下次 attempt 时 catalog 重新拼
- MCP server 发了 `listChanged` 通知,`onChanged` callback 里
`catalog = null` 强制下次刷新
- 某个 server 连续 3 次失败,进入 60s 冷却期(后面 "Failure 退避" 段)
这就是"server 列表静态发现 + tool 列表动态发现 + tool catalog 缓存"
三层的实际落地。
## 几个值得注意的实现细节
**JSON Schema 兼容**(`agent-bundle-mcp-runtime.ts` `createBundleMcpJsonSchemaValidator`):
MCP 用 JSON Schema draft 2020-12,而 TypeBox/Ajv 对一些 keyword 支持
不一致,OpenClaw 用 `stripJsonSchemaFormats` + `normalizeJsonSchemaForTypeBox`
做 schema 归一化后再交给 TypeBox 编译。
**Content block 收敛**(`agent-bundle-mcp-materialize.ts` `mcpContentBlockToToolResult`):
MCP 的 `CallToolResult` 可以返回 text/image/audio/resource_link/resource 等
多种 block,但 OpenClaw 的 `AgentToolResult` 只支持 text/image。多余类型
被降级成 text,避免 provider(Anthropic)拒掉无效 image block 后整个
session 历史被污染(注释里点了 issue #90710)。
**Stdio env 安全过滤**(`docs/cli/mcp.md` "Stdio env safety filter"):
`NODE_OPTIONS`、`PYTHONSTARTUP`、`LD_PRELOAD` 这类能在 RPC 之前改变
解释器行为的 env 被禁止写入 stdio server 的 `env` 字段。
**Failure 退避**(`agent-bundle-mcp-runtime.ts` 常量 `BUNDLE_MCP_FAILURE_THRESHOLD`):
同一 server 连续 3 次失败会触发 60s 冷却,防止一个坏 server 阻塞整个
agent turn。
**Tool filter**:每个 server 可配 `toolFilter.include/exclude`(支持 `*` glob),
catalog 阶段就把不想暴露给模型的工具过滤掉。
## 相关
- [mcp-overview.md](./mcp-overview.md) — MCP 协议本身、OpenClaw 的两个
方向、MCP 与 tool use 的对比
- `docs/cli/mcp.md` — 官方面向用户的 CLI 文档
mcp-overview.md
+241
View File
@@ -0,0 +1,241 @@
# MCP（Model Context Protocol）概览
基于 [OpenClaw](https://github.com/openclaw/openclaw) 2026.6.2 版本源码。
本文讲 MCP 是什么、OpenClaw 怎么用它、它和 tool use 是什么关系。
OpenClaw 作为 MCP client 的内部实现(发现、连接、catalog、缓存等)
单独写在 [mcp-client-internals.md](./mcp-client-internals.md)。
## MCP 是什么
MCP 是一个开放协议,定义了 **LLM 应用(host)与外部工具/数据源(server)
之间的通信格式**。可以理解为"AI 应用的 USB-C 接口":一个 host 通过 MCP
可以同时接入文件系统、数据库、第三方 API 等任意 server,而不需要为每个
工具单独写 adapter。
通信用 JSON-RPC 2.0,MCP server 暴露三类能力:
- **tools** — 模型可以调用的函数(`tools/list`、`tools/call`)
- **resources** — 可读的数据源(`resources/list`、`resources/read`)
- **prompts** — 可被引用的预制 prompt 模板
## OpenClaw 里 MCP 的两个方向
OpenClaw 同时扮演 MCP server 和 MCP client(见 `docs/cli/mcp.md`):
```
┌──────────────────────┐
│ External MCP client │
│ (Codex / Claude Code)│
└─────────┬────────────┘
│ stdio JSON-RPC
▼
┌──────────────────────────────────────┐
│ openclaw mcp serve │
│ (src/mcp/channel-server.ts) │ ← OpenClaw as MCP server
│ ChannelBridge → Gateway WS │
└──────────────────────────────────────┘
┌──────────────────────────────────────┐
│ OpenClaw agent runtime │
│ (src/agents/agent-bundle-mcp-*.ts) │ ← OpenClaw as MCP client
└─────────┬────────────────────────────┘
│ stdio / SSE / streamable-http
┌─────────▼──────────┐ ┌──────────────┐
│ third-party MCP │ │ remote HTTP │
│ server (filesystem,│ │ MCP server │
│ memory, ...) │ │ (OAuth) │
└────────────────────┘ └──────────────┘
```
### 方向 1:OpenClaw 当 server(`openclaw mcp serve`)
把 OpenClaw 的 channel 会话(Telegram/Discord/iMessage 等)通过 MCP
暴露给外部 client(Codex、Claude Code 等)。
入口在 `src/cli/mcp-cli.ts`,核心装配在 `src/mcp/channel-server.ts`:
```
McpServer(@modelcontextprotocol/sdk)
+ OpenClawChannelBridge (连到本地/远端 Gateway WebSocket)
+ registerChannelMcpTools(server, bridge)
```
`src/mcp/channel-tools.ts` 注册的 tool:
- `conversations_list` / `conversation_get`
- `messages_read` / `attachments_fetch`
- `events_poll` / `events_wait`
- `messages_send`
- `permissions_list_open` / `permissions_respond`
传输是 stdio:外部 client 启动 `openclaw mcp serve` 子进程,两边通过
stdin/stdout 跑 JSON-RPC。OpenClaw 内部再用 WebSocket 连到 Gateway 取
真实会话。
### 方向 2:OpenClaw 当 client
`openclaw mcp add/set/configure/probe/login/...` 把第三方 MCP server
保存到 `openclaw.json` 的 `mcp.servers` 下;OpenClaw 的 agent runtime
在跑的时候把这些 server spawn 起来,并把它们的 tool 合到模型可调用的
工具列表里。
这一侧的详细实现(server 怎么被发现、何时连接、catalog 怎么暴露给模型、
怎么缓存与失效、几个安全/兼容细节)单独写在
[mcp-client-internals.md](./mcp-client-internals.md)。
## MCP 与 tool use 的区别
这两个经常被混在一起,其实是 **不同层的概念**。
一句话:
- **Tool use(function calling)**:模型 ↔ 应用之间的**约定**——
模型怎么"申请调用一个函数"
- **MCP**:应用 ↔ 工具实现之间的**协议**——
这个函数从哪儿来、怎么真正执行
模型不知道 MCP 的存在,MCP server 也不知道是哪个模型在调它。
### 分层看
```
┌─────────────────────────────────────────┐
│ LLM (Claude / GPT / Gemini) │
│ 只认 tool_use / function_call │ ← Tool Use 层
└─────────────────────┬───────────────────┘
│ provider API
┌─────────────────────▼───────────────────┐
│ OpenClaw agent runtime │
│ - 收集所有可用 tool │
│ - 打平成 provider 期望的格式 │
│ - 收到 tool_use 后分发执行 │
└──┬───────────────┬──────────────┬───────┘
│ │ │
┌──▼──────┐ ┌─────▼─────┐ ┌─────▼──────┐
│ native │ │ plugin │ │ MCP server │ ← Tool 来源
│ Read/ │ │ tool │ │ (stdio/HTTP)│
│ Bash... │ │ │ │ │
└─────────┘ └───────────┘ └─────────────┘
```
模型那一层永远是 tool use;MCP 只是 OpenClaw 拿到工具实现的一种方式。
所有 tool 最后都被归一化成同一个类型 `AnyAgentTool`
(`src/agents/tools/common.ts`):
- **Native tool**:代码里直接定义,例如 `src/agents/tools/read.ts`
- **MCP tool**:`buildBundleMcpToolsFromCatalog` 把 `Client.listTools()`
返回的远端 catalog 包装成 `AnyAgentTool`,`execute` 里调
`client.callTool(...)`
### 关键差异表
| 维度 | Tool use(原生 function calling) | MCP |
| ------------- | -------------------------------- | ---------------------------------------------- |
| 谁定义 | 应用代码内联定义 schema | 远端 MCP server 自己声明 |
| 谁执行 | 应用代码同进程里调用 | 远端 server(子进程 stdio,或 HTTP) |
| 发现方式 | 编译时静态注册 | 运行时 `tools/list` 动态拉取 |
| 跨语言 | 绑死宿主语言 | JSON-RPC 任何语言都能写 server |
| 跨应用复用 | 每个应用各写一遍 | 同一个 server 给 Claude Code、Codex、OpenClaw 都用 |
| 协议层 | 没有协议,就是个函数 | JSON-RPC 2.0 + 标准 schema |
| 能力 | 只有 function | tools / resources / prompts / notifications |
| 生命周期 | 跟着进程 | 独立进程,需要管 spawn/health/timeout/idle reclaim |
### 类比
- **Tool use** ≈ 编程语言里"函数调用"这个概念本身
- **MCP** ≈ gRPC / OpenAPI ——一种让函数能跨进程/跨语言被发现和调用的具体协议
或者:
- Tool use ≈ "我要打个电话"
- MCP ≈ "电话怎么拨通对方公司的总机,问到分机号,再接到具体的人"
### 实际后果
1. **不用 MCP 也能 tool use**:OpenClaw 的 `Read`、`Bash`、`Edit` 这些都是
原生 tool,模型直接调,没 MCP 什么事。
2. **同一个 MCP server 给多个 host 复用**:`@modelcontextprotocol/server-filesystem`
一次装好,Claude Code 和 OpenClaw 都能用;换成原生 tool 就得在每个
host 里各实现一遍。
3. **MCP server 挂掉不影响其他 tool**:远端调用有网络/进程/超时故障模式,
OpenClaw 用失败退避隔离(见 [mcp-client-internals.md](./mcp-client-internals.md)
的 "几个实现细节")。
4. **MCP tool 对模型完全透明**:模型看到的就是 `filesystem__read_file(path)`,
跟 native tool 长得一样,`__` 前缀只是为了避免重名,不是给模型暗示
这是 MCP。
### 编译时 vs 运行时:典型用法不是协议本质
常见直觉是 "native tool use 是编译时静态、开发者固定;MCP 是运行时
动态、用户自定义"。方向对,但这是 **典型用法**,不是 **协议本质**。
实践中的分布确实如此:
| 维度 | Native tool use | MCP tool |
| ----------- | ------------------- | ---------------------------------- |
| 谁定义 | 开发者写在代码里 | 用户在 config 里加 |
| 何时确定 | 构建时 / 启动时 | 运行时 `tools/list` 拉来 |
| 变更成本 | 改代码、重发版 | 改 `openclaw.json` + `mcp reload` |
| 列表稳定性 | 一个版本里固定 | session 内可变(MCP `listChanged`)|
但严格说要分两层:
- **Tool use(协议层)** 没规定 tool 必须是静态的。应用完全可以每次请求
前动态生成 tool 列表(按用户权限、session 状态等)塞给模型。模型只看到
一个数组,不在乎是 hardcode 还是即时拼的。
- **MCP** 协议本身**强制动态**:server 自己声明 `tools/list`,host 必须
运行时去问——因为 tool 在另一个进程里,编译时无从知晓。
所以更准的说法:
- Tool use **允许**静态也**允许**动态,大多数应用选静态(因为简单)
- MCP **强制**动态(协议天然属性)
### 更本质的轴:所有权
真正的分水岭是 **谁拥有 tool 实现**:
- **Native tool** = 应用拥有 → 自然静态、自然由开发者掌控
- **MCP tool** = 第三方/用户拥有 → 必须动态发现、自然由用户配置
"编译时 vs 运行时"是这个所有权差异的**自然后果**,不是原因。
### 一个反例:plugin tool
OpenClaw 的 **plugin tool**(`extensions/*` 里那些)既不是 native 也不是
MCP,正好用来校准这两根轴:
- 像 native 一样:用 TypeScript 写,跟主进程同语言,**编译时**就在
- 像 MCP 一样:不在 core 里,由"插件作者"(广义的用户/第三方)拥有
它们走 `src/plugin-sdk/*`,跟 native tool 一样进 `AnyAgentTool`,跟 MCP tool
一起被打平。
这说明 **"动态/静态" 和 "开发者/用户" 是两个独立轴**,plugin tool 占了
"用户拥有 + 编译时确定" 那一格:
```
开发者拥有 用户/第三方拥有
┌──────────────────┬──────────────────┐
编译时确定 │ native tool │ plugin tool │
├──────────────────┼──────────────────┤
运行时发现 │ (动态生成的 │ MCP tool │
│ native tool) │ │
└──────────────────┴──────────────────┘
```
## 心智模型一句话
Tool use 是模型层的调用约定;native / plugin / MCP 是这个约定下
**tool 实现的几种供应来源**,一部分由应用开发者编译时固化,一部分由
用户或第三方运行时供应。MCP 不替代 tool use,它给 tool use 加了一个
"工具供应链":模型继续按 tool use 协议出请求,应用按 MCP 协议去远端
把工具 *供应* 回来,放到模型看到的 tool 列表里。
## 继续阅读
- [mcp-client-internals.md](./mcp-client-internals.md) — OpenClaw 作为
MCP client 的内部实现:server 发现、连接时机、catalog 暴露、缓存与
失效、安全/兼容细节
plugin-tools.md
+226
View File
@@ -0,0 +1,226 @@
# Plugin Tool
基于 [OpenClaw](https://github.com/openclaw/openclaw) 2026.6.2 版本源码。
本文讲 OpenClaw 的 **plugin tool**:跟 native tool、MCP tool 同列,
但归插件作者拥有、用 TypeScript 写、跑在 OpenClaw 同进程里的那一类工具。
## 定位
OpenClaw agent 看见的工具一共有三种来源(详见
[mcp-overview.md](./mcp-overview.md) 的 "MCP 与 tool use 的区别"):
| | 拥有者 | 在哪儿 | 进程 | 协议 |
| ------------- | ----------------- | -------------------------------- | -------------- | -------------------------- |
| **native tool** | OpenClaw core | `src/agents/tools/*` | 同进程 | 无 |
| **plugin tool** | 插件作者 | `extensions/<name>/`(可第三方) | 同进程 | OpenClaw Plugin SDK |
| **MCP tool** | 第三方/用户 | 任何 MCP server | 子进程/远端 | MCP JSON-RPC |
plugin tool 占的格子是:**用 TypeScript 写、走 OpenClaw 内部 SDK 接口、
不需要跑子进程**。介于 "core 写死的 native" 和 "完全解耦的 MCP" 之间,
专门用来做"深度集成 OpenClaw 内部能力,但又不属于 core" 的工具。
## 怎么写一个
入口 `src/plugin-sdk/tool-plugin.ts` 的 `defineToolPlugin`。最小例子
(`extensions/llm-task/index.ts`):
```ts
import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";
import { Type } from "typebox";
export default defineToolPlugin({
id: "llm-task",
name: "LLM Task",
description: "Generic JSON-only LLM tool for structured tasks.",
configSchema: Type.Object({
defaultProvider: Type.Optional(Type.String()),
defaultModel: Type.Optional(Type.String()),
// ...
}),
tools: (tool) => [
tool({
name: "llm-task",
description: "...",
parameters: Type.Object({ // TypeBox schema
prompt: Type.String(),
input: Type.Optional(Type.Unknown()),
// ...
}),
execute: async (params, config, context) => { // 直接执行
// 用 context.api 调用 host 服务(LLM 推理、存储等)
// 返回 text 或 JSON
},
// 或者:
// factory: ({ api, config, toolContext }) => createMyTool(api),
}),
],
});
```
两种声明方式(`tool-plugin.ts` `ToolPluginToolDefinition` 的两个分支):
- **`execute`**:声明完就是个完整的 tool,框架直接调
- **`factory`**:返回一个或多个 `AnyAgentTool`,适合需要根据
config / capability 动态构造工具的场景(`llm-task` 用的就是 factory)
`defineToolPlugin` 内部把每个 tool 注册到 plugin entry,在 plugin
activation 时跑 `register(api)`,把 tool 加进 agent 可用 tool 池
(`tool-plugin.ts:187-200`)。
## Manifest 让发现"不跑代码"
每个 plugin 同时有一份 `openclaw.plugin.json`
(`extensions/llm-task/openclaw.plugin.json`):
```json
{
"id": "llm-task",
"activation": { "onStartup": true },
"configSchema": { "..." },
"contracts": {
"tools": ["llm-task"]
},
"toolMetadata": {
"llm-task": { "optional": true }
}
}
```
`contracts.tools` 把 plugin 提供的工具名列出来。这样 OpenClaw 在
**还没加载 plugin 代码**时就知道"装了这个 plugin 会多哪些工具"——
`openclaw plugins list`、setup、文档生成都不用 import 真实运行时。
这条规则在 `src/plugins/CLAUDE.md` 里写明:
> Preserve manifest-first behavior: discovery, config validation, and setup
> should work from metadata before plugin runtime executes.
`defineToolPlugin` 输出的对象上挂了一个 `[toolPluginMetadataSymbol]`,
包含同样的 metadata,这样 manifest 落地后可以做 contract 校验,
保证 manifest 跟代码不漂移(`tool-plugin.ts:109-116`)。
## Plugin SDK 边界
来自根 `AGENTS.md` 的硬规则:
> 插件 prod 代码:no core `src/**`, `src/plugin-sdk-internal/**`, other
> plugin `src/**`, or relative outside package.
插件只能通过 `openclaw/plugin-sdk/*` 跟 core 交互。`defineToolPlugin`
的 `register(api)` 拿到的 `OpenClawPluginApi` 就是 plugin 看得见的所有
host 能力(LLM 推理、存储、其他 plugin 句柄等),core 内部的具体实现
对 plugin 透明。
这条边界让 plugin tool 既能用上 host 内部能力(不像 MCP server 那样
完全隔离),又不会被 core 实现变更直接打死(只要 SDK 不破坏)。
## 仓库里有哪些 plugin tool
`grep "contracts.*tools" extensions/*/openclaw.plugin.json` 找到的:
| 插件 | 提供的能力 |
| ----------------- | ----------------------------------- |
| `browser` | 浏览器自动化 |
| `canvas` | 画图 |
| `diffs` | 大文件 diff |
| `llm-task` | "调一次 LLM 跑结构化任务" |
| `memory-core` | 知识/记忆存取 |
| `memory-lancedb` | 向量记忆 |
| `memory-wiki` | wiki 风格记忆 |
| `tavily` | Web 搜索 |
| `firecrawl` | Web 抓取 |
| `feishu` | 飞书集成 |
| `qqbot` | QQ 集成 |
| `google-meet` | Google Meet 集成 |
| `file-transfer` | 文件传输 |
| `codex-supervisor` | Codex 任务编排 |
| `lobster` | (内部任务) |
`extensions/` 里**大多数其实不是 tool plugin**,而是另外两类——见下节。
## 它在更大的 plugin 生态里的位置
`extensions/` 里有三种主要 plugin,用不同的 `define*Plugin` 入口:
| 入口 | 用途 | 例子 |
| ------------------------------- | ---------------------- | ------------------------------ |
| `defineToolPlugin` | 给 agent 注册工具 | `llm-task`, `tavily`, `browser` |
| `defineChannelPluginEntry` | 接入消息渠道 | `telegram`, `discord`, `imessage` |
| `defineSingleProviderPluginEntry` | 接入 LLM provider | `anthropic`, `openai`, `google` |
| `defineSetupPluginEntry` | 安装/onboarding 流程 | 各 plugin 的 setup 部分 |
不同入口在 SDK 内部都收敛到 `definePluginEntry`(`src/plugin-sdk/plugin-entry.ts`)
拿到统一的 plugin lifecycle(activation、register、config)。
**channel / provider plugin 不直接给 agent 注册工具**——它们暴露的是
消息渠道或模型推理能力。tool plugin 是这个生态里**专门给 agent 加
function 的那一类**。
(理论上 channel plugin / provider plugin 也可以通过 `register(api)` 里
顺手注册 tool,但很少这么干;一旦这么做就既是 channel/provider plugin
又有 tool plugin 的属性。)
## 它怎么进到模型的 tool 列表
跟 MCP tool 走同一条路径(见
[mcp-client-internals.md](./mcp-client-internals.md) 的 "Attempt 引爆点"):
```
plugin 启动时(activation.onStartup 或按需)
→ tools 列表里每个 tool({...}) 被注册成 AnyAgentTool
→ 加进 agent 的可用 tool 池(在 host 进程内存里)
每次 attempt 开始
→ tools = [...native, ...plugin, ...bundleMcp, ...bundleLsp]
→ 走 provider adapter
→ 发给 LLM
```
模型看见的就是一个名字 `llm-task` 或者 `tavily_search`,没有任何
"这是 plugin"的标识。execute 时框架找到对应 tool,调它的 `execute`
函数,**这一切都在 OpenClaw 同一个 Node 进程里**,跟 MCP 走 stdio
子进程或 HTTP 完全不同。
## 跟 MCP tool 的关键对比
| 维度 | plugin tool | MCP tool |
| -------------- | ---------------------------------- | ---------------------------------- |
| 语言 | TypeScript(锁死 Node) | 任意(JSON-RPC) |
| 进程 | 同进程 | 子进程 / 远端 |
| 启动开销 | 几乎 0(import 即可) | spawn + 握手 + listTools |
| 故障隔离 | 一个 plugin 崩了可能影响整个进程 | 子进程崩了不影响别人,有失败退避 |
| 访问 host 服务 | 通过 `OpenClawPluginApi` | 完全隔离,什么都拿不到 |
| 跨应用复用 | OpenClaw 专属 | 任何 MCP host 都能用 |
| 分发 | npm package(`@openclaw/plugin-*`) | 任何二进制 / 服务 |
| 适合做什么 | 深度集成 OpenClaw 内部能力的工具 | 通用、跨应用、可独立运行的工具 |
例子:`llm-task` 必须是 plugin tool,因为它要复用 OpenClaw 的
provider/auth/catalog 体系跑一次内嵌 LLM 推理;
`@modelcontextprotocol/server-filesystem` 适合做 MCP server,因为它
跟 OpenClaw 没耦合,Claude Code 也能用。
## 在"两根轴"里的位置
回顾 [mcp-overview.md](./mcp-overview.md) 的所有权 × 时机两根轴,
**plugin tool 占了"用户/第三方拥有 + 编译时确定"那一格**:
```
开发者拥有 用户/第三方拥有
┌──────────────────┬──────────────────┐
编译时确定 │ native tool │ plugin tool ★ │
├──────────────────┼──────────────────┤
运行时发现 │ (动态 native) │ MCP tool │
└──────────────────┴──────────────────┘
```
这个反例的价值在于:它证明了 "动态/静态" 跟 "开发者/用户" 是
**两个独立的轴**——不能简单说 "用户拥有的就一定是运行时发现"。
plugin tool 是用户拥有的(插件作者写、用户装),但因为还是 npm
package 同语言同进程,完全可以编译时确定。
## 相关
- [mcp-overview.md](./mcp-overview.md) — MCP 概览、与 tool use 的关系
- [mcp-client-internals.md](./mcp-client-internals.md) — MCP client
实现细节(plugin tool 跟 MCP tool 在 attempt 里的拼装)
rag-overview.md
+382
View File
@@ -0,0 +1,382 @@
# RAG 与向量化
本文是 RAG(Retrieval-Augmented Generation)概念笔记,重点回答两个
常被混淆的问题:**向量化的结果是什么**、**拼进 prompt 的到底是
向量还是原文**。
不像本目录其他笔记基于 OpenClaw 源码,这一篇是通用概念整理。
## RAG 是什么
一句话:**让 LLM 在回答前先去外部知识库里捞一段相关资料,把资料
拼进 prompt,再让模型基于资料回答。**
它解决 LLM 的三个硬伤:
1. **知识截止** — 训练完就定死了,新事件不知道
2. **不知道私有数据** — 公司文档、产品手册、内部 wiki 它没见过
3. **会编(幻觉)** — 不知道的事会一本正经胡说
RAG 的思路是:别让模型 "凭记忆答",让它 "看着资料答"。
## 跟其他方案的对比
| 方案 | 优势 | 劣势 |
| ------------------------------- | ----------------------------------- | ------------------------------------ |
| **RAG** | 知识可实时更新,可解释,便宜 | 检索质量决定上限,prompt 会变长 |
| **Fine-tuning** | 模型"内化"知识,不用每次塞资料 | 训练贵,数据更新要重训,容易遗忘 |
| **超长 context(塞全部文档)** | 不用检索,看全部信息 | 贵,"大海捞针"问题 |
| **Tool use / MCP**(让模型自己调 search) | 灵活,按需查 | 多一轮往返,延迟高,不一定查到 |
实际系统经常组合:RAG 提供基础知识,fine-tuning 调风格,tool use
处理结构化查询。
## 最小工作流
```
用户问:"我们公司的报销额度是多少?"
↓
[1] 检索(Retrieval)
把问题向量化,在公司文档向量库里找最相关的几段
→ 拿到: "差旅报销单笔上限 2000 元,需要主管审批..."
↓
[2] 增强(Augmentation)
把检索结果拼进 prompt:
"根据以下公司文档回答问题:
差旅报销单笔上限 2000 元,需要主管审批...
问题: 我们公司的报销额度是多少?"
↓
[3] 生成(Generation)
LLM 基于 prompt 里给的资料生成回答
→ "公司差旅报销单笔上限是 2000 元,需要主管审批。"
```
## 典型架构
**离线索引阶段**(只做一次,数据更新时跑):
```
文档 → 切块(chunking) → embedding → 向量数据库
```
**在线检索阶段**(每次用户问问题时):
```
用户问题 → embedding → 向量数据库找 top-k 相似块 → 拼 prompt → LLM
```
常见 top-k = 3 ~ 10。常用向量数据库:Pinecone、Weaviate、Qdrant、
LanceDB、pgvector(Postgres 扩展)。
## 向量化:这是什么、为什么需要
### 为什么需要向量化
用户问 **"怎么退货?"**,文档库里有:
```
A. "退款政策:商品 7 天内可申请退货退款..."
B. "如何使用购物车..."
C. "我们的隐私条款..."
```
朴素的关键词匹配有问题:
- 用户问 "返货" 或 "怎么把货退回去" 时关键词对不上
- 文档里写 "退款政策",没出现 "退货" 原词
- 用户问 "我不想要这个东西了" 时,字面完全不含 "退货"
**关键词匹配是字面的,问问题是语义的**。需要一种方法,让计算机
能算 "这两段文字意思有多接近",哪怕字面完全不同。
### 向量是什么
向量就是 **一组数字**。比如:
```
"退货" → [0.21, -0.13, 0.88, 0.45, ..., 0.07] ← 1536 个数
```
这 1536 个数字不是随便定的,它们是某种 "语义坐标"。
**语义相近的词,向量在数学上也接近**:
```
"退货" → [0.21, -0.13, 0.88, ...]
"退款" → [0.23, -0.10, 0.85, ...] ← 跟 "退货" 很接近
"返货" → [0.22, -0.12, 0.87, ...] ← 也接近
"购物车" → [0.91, 0.40, -0.20, ...] ← 离 "退货" 远
"隐私" → [-0.55, 0.70, -0.10, ...] ← 完全不同方向
```
把它们想象成 1536 维空间里的点——意思相近的词,在这个空间里挨得近。
### "近" 怎么算
用 **余弦相似度(cosine similarity)**:
```
两向量方向越一致 → 越相似(值接近 1)
两向量方向越垂直 → 越无关(值接近 0)
两向量方向越相反 → 越相反(值接近 -1)
```
RAG 实际就是 "把用户问题向量和每段文档向量两两算 cosine,排序,
取 top-k"。
### 谁来 "算出" 这些向量
预训练好的 **embedding 模型**。常见:
- OpenAI 的 `text-embedding-3-small` / `text-embedding-3-large`
- 开源 `bge-large` / `gte-large` / `m3e`
- 中文向量化常用 `bge-large-zh` / `m3e-base`
- 多语言 `bge-m3` / `multilingual-e5`
训练目标大致是 "意思相近的句子输出向量接近,意思不同的句子输出向量
远"。用的时候只需要:
```python
embedding = embed_model("退货")
# → [0.21, -0.13, 0.88, ..., 0.07] (1536 个数)
```
做 RAG 时把它当**黑盒**:输入文本,输出向量,语义近的向量接近。
## 向量化的结果是什么、拼进 prompt 的是什么
**这是 RAG 最容易混淆的点。**
答案:**向量化的结果是向量(一组数字),但拼到 prompt 里的是原文,
不是向量。向量只用来"找",找到之后用的是原文。**
### 数据流
```
[索引阶段]
原文 向量(用来查) 存储
┌──────────────────┐
│ 块 #001: │
│ "退款政策:商品 │ ─embedder→ [0.21,-0.13,..] ─┐
│ 7 天内可申请退货"│ │
└──────────────────┘ │
┌──────────────────┐ │ 存进数据库:
│ 块 #002: │ │ 每条记录有两份
│ "购物车使用指南" │ ─embedder→ [0.91, 0.40,..] ─┤ 数据并存:
└──────────────────┘ │ ① 向量(索引用)
┌──────────────────┐ │ ② 原文(召回用)
│ 块 #003: │ │
│ "隐私条款..." │ ─embedder→ [-0.55,0.70,..] ─┘
└──────────────────┘
向量数据库里实际存的:
┌─────────────────────────────────────────────────────────────┐
│ id │ vector │ text │
│ #001 │ [0.21,-0.13,0.88,..]│ "退款政策:商品 7 天内可..." │
│ #002 │ [0.91, 0.40,-0.20,..]│ "购物车使用指南..." │
│ #003 │ [-0.55,0.70,-0.10,..]│ "隐私条款..." │
└─────────────────────────────────────────────────────────────┘
↑ ↑
用来 "找" 用来 "还原"
```
```
[查询阶段]
用户问题
↓
"怎么退货?"
↓
┌─embedder→ [0.20,-0.14,0.86,...] ← 问题也变成向量
│
│ 跟数据库里所有向量算 cosine 相似度
│
│ Top-1:#001 相似度 0.89
│ ↓
│ 根据 id #001 取回原文:
│ "退款政策:商品 7 天内可申请退货退款..."
│ ↓
└→ 把【原文】拼进 prompt:
"根据以下文档回答:
退款政策:商品 7 天内可申请退货退款...
问题:怎么退货?"
↓
发给 LLM
```
### 关键澄清
**1. 向量只用来检索,不参与 prompt**
LLM 完全看不到向量。它跟 embedding 模型是两个不同的模型:
- embedding 模型:**文本 → 向量**
- LLM(GPT / Claude):**文本 → 文本**
把向量塞进 LLM 的 prompt 没意义——LLM 不知道 `[0.21, -0.13, ...]`
是什么,它只懂自然语言 token。
**2. 向量数据库同时存向量和原文**
每条记录通常长这样:
```json
{
"id": "doc-001-chunk-3",
"vector": [0.21, -0.13, 0.88, ...], // 索引结构,算相似度用
"text": "退款政策:商品 7 天内可申请退货退款...", // 原文,召回后用
"metadata": {
"source": "policies/refund.md",
"chunk_index": 3,
"updated_at": "2026-05-12"
}
}
```
- `vector` 字段:用 HNSW 之类的索引结构,给 "找最近邻" 用
- `text` 字段:召回后真正塞进 prompt 的内容
- `metadata`:过滤条件(按日期、按部门筛选)
**3. 向量是有损的压缩**
`text-embedding-3-small` 输出 1536 维向量,1536 个浮点数 ≈ 6 KB,
跟几百字原文容量差不多——但**你没法从向量还原出原文**。
向量是 "这段文字的语义指纹",指纹用来匹配,看真实内容要回到原文。
数据库必须把原文也存下来。
### 类比
可以把这套机制类比图书馆:
- **向量** ≈ 图书索引卡的 "主题分类号",用来快速定位
- **原文** ≈ 书的内容,真正要读的东西
读者(LLM)读的是书,不是索引卡。索引卡只是帮你找到该读哪本书。
### 完整 prompt 长什么样
实际发给 LLM 的请求大概(简化):
```
System: You are a helpful assistant. Answer based on the provided context.
Context:
---
[Source: policies/refund.md]
退款政策:商品 7 天内可申请退货退款,需保持原包装完好,联系客服 400-xxx 办理。
---
[Source: faq/shipping.md]
订单状态查询:登录后在"我的订单"查看,异常订单 24 小时内会有客服回访。
---
Question: 怎么退货?
```
从头到尾全是自然语言文本。**向量已经在检索阶段完成了它的使命,
不会出现在最终 prompt 里。**
## 向量的几个有意思的性质
### 1. 不止短词,任意长度文本
embedding 模型能把一个 **短词** 变成向量,也能把一 **整段几百字**
变成同样维度的向量。所以 "问题向量" 和 "文档向量" 可以直接比较。
### 2. 跨语言也能用
好的多语言 embedding(`bge-m3`、`multilingual-e5`)让 "退货" 和
"return goods" 的向量接近。RAG 可以做跨语言检索:中文问题查英文文档。
### 3. 多模态
CLIP 这类模型把 **图片和文字** 映射到同一个向量空间。可以用文字
"穿红裙子的女孩" 检索图片库——文字向量和图片向量直接算 cosine。
### 4. 维度高就是为了 "细分"
为什么要 1536 维而不是 10 维?因为人类语言的语义维度太多——词性、
情感、领域、时态、正式程度...每一维捕捉一点点信息。低维度容易把
"无关的事压扁到同一处"。
## RAG 的几个常见坑
### 1. 检索失败比幻觉更糟
如果检索没拉到相关文档,模型只能瞎编。要么加 "如果资料里没有就说
不知道",要么在 retrieval 失败时直接拒绝回答。
### 2. 切块策略影响巨大
按固定长度切会切断句子,按段落切又长度不均。常见做法:
- **语义切块**:用嵌入相似度决定切点
- **重叠切块**:相邻块有 10% ~ 20% 重叠,避免边界丢上下文
- **保留层级**:把 "标题 + 段落" 一起塞进块里,保留文档结构
### 3. embedding ≠ 相关性
embedding 抓的是 "语义相似",不一定是 "对这个问题有答案"。
例子:用户问 "明天天气怎么样",文档里有:
- A. "天气预报通常由气象台发布..."
- B. "明天我们公司放假..."
embedding 可能把 A 排在前面(都讨论天气),但 A 没回答用户的问题;
B 字面不相关但其实是用户该看的(他可能想问 "明天用不用上班")。
工程上常见加强:
- **混合检索**:embedding(语义)+ BM25(关键词)双路召回合并
- **Rerank**:第一轮拉 50 个,用专门的 reranker 模型
(`cohere-rerank`、`bge-reranker`)精排到 top 5
- **HyDE**:让 LLM "假想" 一个答案,用假答案去检索——比直接用
问题更接近文档表述
### 4. 评估很难
模型说错了,是检索没拉到?还是拉到了模型没用?还是用了但理解错了?
分阶段评估:
- 检索准确率(召回的 top-k 里有没有正确答案)
- 端到端准确率(最终回答对不对)
- 引用一致性(回答有没有 hallucinate,引用的内容真的在检索结果里吗)
## RAG 跟 MCP 的关系
可以把 RAG 视作 **"一类常见的 MCP server"**——很多 MCP server 干的
事就是 "接到 query → 内部跑 RAG → 返回相关内容":
- `mcp-server-notion`:用户问问题,server 在 Notion 里搜相关页面返回
- `mcp-server-confluence`:同上,在内部 wiki 上跑 RAG
- 公司自建 MCP server:把产品文档喂进 LanceDB,模型问到产品时查它
但 RAG 也可以 **不通过 MCP**——直接在 agent 框架里写死
(LlamaIndex、LangChain 那些),或者在每次 LLM 请求前直接拼 prompt。
MCP 只是把 RAG 能力 "包装成可复用工具" 的一种方式。
详见 [mcp-overview.md](./mcp-overview.md)。
## 总结
```
LLM 不知道答案?
├─ 是公开知识但过时了 → RAG(查最新资料)或 web search tool
├─ 是你的私有数据 → RAG(查内部文档库)
├─ 是结构化数据(SQL/API) → tool use(直接查)
├─ 是需要算的(数学/代码) → tool use(让模型调 code interpreter)
└─ 是需要模型"内化"的风格/技能 → fine-tuning
```
RAG 是最常用的一格——便宜、可解释、知识能实时更新,适合 "知识问答"
和 "基于文档回答" 这类任务。
**心智模型一句话**:向量是 "导航地图"(找到正确目的地),原文是
"目的地内容"(交给 LLM 读)。embedding 模型把文本变成向量是为了
搜索;搜索完成后,LLM 看到的永远是原文。