Agent 技能与工具

Vibecape Agent 是一个强大的 AI 助手，拥有多种技能来帮助您编辑和管理文档。本文档详细介绍了 Agent 可用的所有工具及其实现方式。

工具分类概览

Agent 的工具分为以下几类：

分类	说明
🔧 通用工具	基础能力，如获取时间
📚 文档管理	创建、重命名、移动、删除文档
🎯 节点编辑	基于 Node 的精确编辑（需用户确认）
📝 前端编辑器	直接操作 Tiptap 编辑器
🔌 MCP 扩展	通过 MCP 协议扩展的第三方工具

通用工具

通用工具是所有 Hero 都可以使用的基础能力。

`getCurrentTime`

获取当前的日期和时间。

属性	值
描述	获取当前的日期和时间
参数	无
返回值	`{ date, time, timestamp, weekday }`

使用场景：

在文档中插入当前日期
基于时间生成问候语
记录操作时间

// 实现代码 (common.ts)
getCurrentTime: tool({
  description: "获取当前的日期和时间",
  inputSchema: z.object({}),
  execute: async () => {
    const now = new Date();
    return {
      date: now.toLocaleDateString("zh"),
      time: now.toLocaleTimeString("zh"),
      timestamp: now.toISOString(),
      weekday: ["周日", "周一", "周二", "周三", "周四", "周五", "周六"][now.getDay()],
    };
  },
}),

文档管理工具

文档管理工具用于操作文档的生命周期和组织结构。

`getDocumentTree`

获取当前工作区的完整文档树结构。

属性	值
描述	获取工作区文档树
参数	无
返回值	`{ success, tree }`

`getDocumentInfo`

获取指定文档的详细信息。

属性	值
描述	获取文档详细信息
参数	`docId: string` - 文档 ID
返回值	`{ success, doc }`

`createDocument`

创建新文档。

属性	值
描述	创建新文档
参数	`title: string` - 文档标题 `parentId?: string` - 父文档 ID（可选） `description?: string` - 文档描述（可选）
返回值	`{ success, docId, message }`

`renameDocument`

重命名文档（修改标题）。

此工具会同时更新文档标题和编辑器中的标题节点，确保一致性。

属性	值
描述	重命名文档
参数	`docId: string` - 文档 ID `newTitle: string` - 新标题
返回值	`{ success, message }`

`updateDocumentMetadata`

更新文档的元数据。

属性	值
描述	更新文档元数据
参数	`docId: string` - 文档 ID `metadata: object` - 元数据对象
返回值	`{ success, message, metadata }`

`moveDocument`

将文档移动到另一个父文档下。

属性	值
描述	移动文档
参数	`docId: string` - 文档 ID `newParentId?: string` - 新父文档 ID（可选，不传则移动到根级别）
返回值	`{ success, message }`

`reorderDocument`

调整文档在同级中的顺序。

属性	值
描述	调整文档顺序
参数	`activeId: string` - 要移动的文档 ID `overId: string` - 目标位置的文档 ID
返回值	`{ success, message }`

`deleteDocument`

删除文档（软删除）。

此操作会同时删除所有子文档！使用前请确认。

属性	值
描述	删除文档
参数	`docId: string` - 文档 ID `confirm: boolean` - 必须为 `true` 才会执行
返回值	`{ success, message }`

`findDocumentByTitle`

按标题搜索文档。

属性	值
描述	搜索文档
参数	`query: string` - 搜索关键词 `exact?: boolean` - 是否精确匹配
返回值	`{ success, count, results }`

节点编辑工具

节点编辑工具基于 Tiptap 的 Node 模型进行精确编辑，所有写入操作都需要用户确认。

设计原则

Node 作为基本编辑单元：不直接操作文本，而是操作文档节点
支持 Markdown 输入：自动转换为 JSONContent
用户确认机制：所有写入操作都显示 Diff 预览，需要用户点击接受或拒绝

NodeRef 引用语法

节点编辑工具使用 NodeRef 来定位文档中的节点，支持以下格式：

格式	示例	说明
ID 引用	`#nodeId` 或 `nodeId`	通过节点 ID 定位（支持带或不带 `#` 前缀）
位置引用	`@start`	正文的第一个节点（标题之后的第一个节点）
位置引用	`@end`	正文的最后一个节点

`checkNodes`

检查文档中的节点信息。

属性	值
描述	检查节点信息
参数	`docId: string` - 文档 ID `nodeRefs: string[]` - 节点引用数组
返回值	`{ success, nodes, foundCount, requestedCount }`

`getDocStructure`

获取文档的结构大纲。

属性	值
描述	获取文档结构
参数	`docId: string` - 文档 ID `maxDepth?: number` - 最大深度（默认 3）
返回值	`{ success, title, structure, nodeCount }`

`getDocText`

获取文档的纯文本和 Markdown 格式内容。

属性	值
描述	获取文档文本
参数	`docId: string` - 文档 ID
返回值	`{ success, docId, title, text, markdown, wordCount }`

`updateNodes` ⚡

更新指定节点的内容。

此操作需要用户确认！Agent 会生成 Diff 预览，用户可以选择接受或拒绝。

属性	值
描述	更新节点内容
参数	`docId: string` - 文档 ID `nodeRef: string` - 节点引用 `content: string` - 新内容（Markdown 格式）
返回值	`{ success, message, action }`

`insertNodesBefore` ⚡

在指定节点前插入新内容。

属性	值
描述	在节点前插入
参数	`docId: string` - 文档 ID `nodeRef: string` - 节点引用 `content: string` - 要插入的内容（Markdown 格式）
返回值	`{ success, message, action }`

`insertNodesAfter` ⚡

在指定节点后插入新内容。

属性	值
描述	在节点后插入
参数	`docId: string` - 文档 ID `nodeRef: string` - 节点引用 `content: string` - 要插入的内容（Markdown 格式）
返回值	`{ success, message, action }`

`deleteNodes` ⚡

删除指定的节点。

属性	值
描述	删除节点
参数	`docId: string` - 文档 ID `nodeRefs: string[]` - 要删除的节点引用数组
返回值	`{ success, message, action, deletedCount }`

`replaceNodes` ⚡

用新内容替换指定节点。

属性	值
描述	替换节点
参数	`docId: string` - 文档 ID `nodeRef: string` - 节点引用 `content: string` - 新内容（Markdown 格式）
返回值	`{ success, message, action }`

`appendContent` ⚡

在文档末尾追加内容。等同于 insertNodesAfter("@end", content) 的快捷方式。

属性	值
描述	追加内容
参数	`docId: string` - 文档 ID `content: string` - 要追加的内容（Markdown 格式）
返回值	`{ success, message, action }`

`prependContent` ⚡

在正文开头（标题之后的第一个节点之前）插入内容。等同于 insertNodesBefore("@start", content) 的快捷方式。

属性	值
描述	在开头插入
参数	`docId: string` - 文档 ID `content: string` - 要插入的内容（Markdown 格式）
返回值	`{ success, message, action }`

前端编辑器工具

前端编辑器工具通过 IPC 与 Tiptap 编辑器通信，用于获取当前文档的状态信息。

这些工具仅用于读取文档内容。所有写入操作应使用节点编辑工具，它们更可靠且支持用户确认。

`getDocumentText`

获取当前打开文档的纯文本内容和元数据。

属性	值
描述	获取文档纯文本
参数	无
返回值	`{ content, docId, title, metadata }`

`getDocumentStructure`

获取文档的结构大纲，包含标题层级。

属性	值
描述	获取文档结构大纲
参数	无
返回值	文档结构信息

MCP 扩展工具

通过 MCP（Model Context Protocol）协议，Vibecape 支持加载第三方扩展工具。

MCP 工具由外部服务提供，通过配置文件 (~/.vibecape/mcp.json) 进行管理。Agent 在运行时会自动加载所有配置的 MCP 工具。

配置示例

{
  "servers": {
    "example-server": {
      "command": "npx",
      "args": ["-y", "example-mcp-server"]
    }
  }
}

技术实现

工具注册流程

┌─────────────────┐
│   Hero 模块     │ ──定义工具──▶ tools: { ... }
└─────────────────┘
         │
         ▼
┌─────────────────┐
│  ChatStream     │ ──合并工具──▶ allTools = { hero.tools, docTools, mcpTools }
└─────────────────┘
         │
         ▼
┌─────────────────┐
│  AI SDK         │ ──调用工具──▶ streamText({ tools: allTools })
└─────────────────┘

工具调用流程

用户发送消息 - 用户在聊天面板中输入请求
AI 决定调用工具 - AI 模型分析请求，决定需要调用哪些工具
工具执行 - 主进程执行工具函数，可能涉及：
- 数据库操作（文档管理工具）
- 内容转换（内容编辑工具）
- IPC 通信（前端编辑器工具）
- 用户确认（节点编辑工具）
结果返回 - 工具执行结果返回给 AI，AI 继续处理或生成最终回复
前端刷新 - 如果文档内容发生变化，通过 docs:changed 事件通知前端刷新

用户确认机制

节点编辑工具的用户确认流程：

主进程                              渲染进程
   │                                    │
   │  agent:edit:create                 │
   │ ──────────────────────────────────▶│
   │                                    │ 显示 Diff 预览
   │                                    │ 用户点击接受/拒绝
   │  agent:edit:confirm                │
   │ ◀──────────────────────────────────│
   │                                    │
   │  应用修改 / 取消                    │
   │                                    │

工具使用最佳实践

推荐使用的工具

修改特定内容：使用 searchAndReplaceInDoc 或 replaceNodes
追加内容：使用 appendContent 或 appendToDocument
了解文档结构：使用 getDocStructure 或 getDocumentTree
精确编辑：使用节点编辑工具（updateNodes, insertNodesAfter 等）

避免使用的模式

不要依赖用户的当前选区位置
避免频繁全文替换（setDocumentFromMarkdown）
对于简单的文本替换，优先使用 searchAndReplaceInDoc