意图工具

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`，但空间的根项目会收缩成单个片段，所以请逐字照抄响应里的写法，别按规则自行推导。个人域不在列表中（它由令牌隐含）。

调用顺序

start_session →（需要项目？）get_my_projects → 用 list_notes/recent_activity 勘察结构 → 写入前 search/recall → create_note/remember_*/edit_note/link。

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

发现——导航

工具	用途
`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 的区别，详见智能体记忆。

写入与意图

工具	用途
`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`（按尚未创建的笔记标题做前向引用）。两条笔记须在同一空间。

写入受 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`	一次调用创建多条带类型的链接。尽力而为、幂等。

下一步

智能体记忆——remember 与 recall 的细节。
上下文集合与固定项——什么会进入 start_session。
安全与可见性——这套工具集如何打破「致命三要素」。