---
title: "意图工具"
description: "MCP 网关中全部 21 个意图工具，按用途分组：引导、导航、读取、写入、重组与规模化。"
---

# 意图工具

MCP 网关交给智能体的不是通用 CRUD，而是 **21 个面向意图的工具**——每一个都表达一种意图（「创建笔记」「召回上下文」「重命名项目」），而不是对某张表的操作。这样的工具集从构造上就划定了边界：智能体不选空间、也不选笔记的类别——这由工具本身规定；而哪些工具能被看见，取决于令牌的作用域。

智能体在 `tools/list` 中看到的名称和描述是静态的——笔记内容绝不会掺入其中（防范工具投毒）。

## 令牌作用域——可见性上限

`read` 令牌只看得到读取类工具；写入类工具根本不会出现在 `tools/list` 里。除此之外，每次调用都会校验对具体空间的访问。所以下面的表格是上限；实际的工具集取决于你的令牌。

## 引导

会话开始时的工具：我是谁、有哪些对我可用、发生了什么变化。

| 工具 | 用途 |
|---|---|
| `start_session` | 在新会话中**首先**调用。一次请求即得：用户资料（始终加载）、可用项目，以及——当给出 `project` 提示时——一份精简的项目索引（笔记数量 + 顶层文件夹）、自上次访问以来的变更增量，以及 `knownValues`（正在使用的类别/标签词典）。幂等；不强制调用——只是上下文会更少。 |
| `whoami` | 我是谁（主体 id）、我的权限上限（`read`/`write`）、项目成员资格，以及引擎的 `capabilities`（`vector`/`trash`/`revisions`）——这样就不必盲目试探。 |
| `get_my_projects` | 一份扁平的可用项目列表，附带现成的句柄——用于 `project` 参数。句柄通常形如 `space/slug`，但空间的根项目会收缩成单个片段，所以请逐字照抄响应里的写法，别按规则自行推导。个人域不在列表中（它由令牌隐含）。 |

> [!tip] 调用顺序
> `start_session` →（需要项目？）`get_my_projects` → 用 `list_notes`/`recent_activity` 勘察结构 → **写入前** `search`/`recall` → `create_note`/`remember_*`/`edit_note`/`link`。

这个顺序是建议，不是机制：调用哪个工具由模型自己决定。想让它自觉照做，就把这条顺序写进智能体的常驻指令里——见[智能体规则](/docs/agents/agent-files/)。

## 发现——导航

| 工具 | 用途 |
|---|---|
| `list_notes` | 知识库的 `ls`：某个文件夹的直属笔记与子文件夹（确定性、可分页）。`project` 选定空间，`path` 是文件夹（照搬响应中的原文），`tag` 用于过滤。列出的是可见笔记，而非智能体的记忆。 |
| `recent_activity` | 最近编辑过的笔记（「最近动过什么、需要复查」）。每条记录：谁（人/智能体）、如何、在哪、何时。这不是 `start_session` 给出的增量。 |

## 读取与召回

| 工具 | 用途 |
|---|---|
| `search` | 混合搜索（语义 + 词法，经 RRF 融合）；当向量不可用时，会退回到全文搜索（FTS）——不会报错。它还覆盖**智能体自己的记忆**——「写入前先搜索」也能借此去重。返回带 `score` 和 `path` 的排序片段，而非完整笔记。 |
| `get_note` | 按 ref（note-id 或维基引用）取得完整笔记：内容、frontmatter、`path`、`class`、`versionToken`（用于安全写入）以及溯源。在 `detailed` 模式下——还包括 `outline`（标题）和 `links`（图谱的边）。 |
| `recall` | 在 token 预算内，围绕某个主题组装一个上下文包：相关笔记**外加**它们的图谱邻居。比 `search` 更丰富，它同时从知识和私有记忆中拉取。`budgetTokens` 限定其大小。 |

关于 `search` 与 `recall` 的区别，详见[智能体记忆](/docs/agents/memory/)。

## 写入与意图

| 工具 | 用途 |
|---|---|
| `create_note` | 在项目中创建一条新的共享（知识库）笔记，类别为 `user-doc`。`body`（Markdown）以开头的 `# H1` 设定笔记标题；`path?` 是目标文件夹；`type?`/`tags?` 是可选的覆盖参数；`links?` 会立刻加上带类型的边。笔记类别和空间不由智能体选择。 |
| `remember_about_user` | 把关于用户的长效事实（偏好、上下文）记入其私有记忆。在某个 `category` 下追加一条 `observation`。 |
| `remember_about_project` | 把关于某个项目的事实记入智能体的私有记忆（类别 `agent-memory`，与 `remember_about_user` 对称）。这不是共享知识——共享知识请用 `create_note`。 |
| `edit_note` | 按文字锚点而非按位置增量地编辑笔记：`append`/`prepend`、`replace`（整个正文）、`replaceSection`（按标题）、`findReplace`（一个唯一片段；`content` 为空 = 删除）。需要 `versionToken`（CAS）。 |
| `delete_note` | 把笔记移入**回收站**——这是智能体唯一的破坏性操作，从设计上可逆。只有人才能还原或清空回收站。 |
| `link` | 一条带类型的链接 `from`→目标。目标是 `to`（note-id）或 `toTitle`（按尚未创建的笔记标题做前向引用）。两条笔记须在同一空间。 |

> [!important] 写入受 CAS 保护
> `edit_note` 需要一个来自新鲜 `get_note` 的 `versionToken`。并发编辑会返回 `versionConflict` 错误——工具不会悄悄覆盖别人的改动；智能体会重新读取并重试。

## 重组

重组工具的语法是 `verb_entity`。笔记以 id 寻址，文件夹以 `path` 寻址，项目以句柄寻址。

| 工具 | 用途 |
|---|---|
| `move_note` | 把笔记移到另一个文件夹，保留其名称。id 和 URL 保持稳定，入链不会断。 |
| `rename_note` | 更改笔记标题。链接安全：旧标题进入别名历史，入链 `[[链接]]` 仍能解析。 |
| `move_folder` | 把整个文件夹连同内容移到另一个父级下。其中所有笔记的 id 保持稳定。 |
| `rename_folder` | 就地重命名文件夹。若该文件夹是一个项目，其句柄不变（改句柄用 `rename_project`）。 |
| `rename_project` | 更改项目的句柄和/或其可读名称。链接安全：旧句柄进入别名。 |

## 规模化迁移

| 工具 | 用途 |
|---|---|
| `create_notes` | 一次调用在同一个项目里创建多条知识库笔记。尽力而为、非事务性：`results[]` 会把每一条标记为 `ok`/`error`——只重试失败的那些。 |
| `link_many` | 一次调用创建多条带类型的链接。尽力而为、幂等。 |

## 下一步

- [智能体记忆](/docs/agents/memory/)——remember 与 recall 的细节。
- [上下文集合与固定项](/docs/agents/context-pins/)——什么会进入 `start_session`。
- [安全与可见性](/docs/agents/security/)——这套工具集如何打破「致命三要素」。