人人都在谈 AI Agent：看看 Vault Operator 的内部工作方式
英文标题：🔶 Everyone talks about AI agents. This is what one looks from the inside
Vault Operator 是一款嵌入 Obsidian 知识库的开源 AI Agent，可读取笔记、理解链接图谱、调用插件并代表用户执行任务。它覆盖内联聊天、带块级溯源的资料摄取、网页剪藏、跨会话记忆、语义搜索、Office 文档生成、知识库健康检查及多 Agent 协作等能力。该工具通过审批、快照撤销、操作日志和网络防护链控制风险，并可通过 MCP 与 Claude Desktop、ChatGPT 等客户端连接。开发者和知识工作者可自行选择云端或本地模型；其成本优化机制称，可将简单检索与摘要任务的 token 消耗从约 63.4 万降至约 6 万。
892 B
4.3 KB
128.7 KB
中文
Vault Operator 能做什么
大多数 AI 工具都位于你的知识库之外，等待你复制和粘贴内容。Vault Operator 则运行在知识库内部：它读取你的笔记，沿着将笔记连接起来的图谱进行探索，学习你的习惯，并代表你执行操作。
本页提供简要导览。每个章节都链接到更深入的指南。
更喜欢观看视频？这段 7 分钟的动画讲解会从内部剖析这个 Agent：循环机制、包含五道关卡的执行框架、工具、技能和 MCP，以及一项贯穿所有层级的真实任务。
编辑器中的内联 AI 聊天
自 v3.0.0 起可用。
你可以直接在正在阅读的笔记中发起聊天。选中文本后，按 Cmd+Shift+I（Windows 和 Linux 上为 Ctrl+Shift+I），或右键选择“Inline AI chat”，编辑器上方会打开一个浮动面板。你可以在此询问有关所选内容的问题、查找资料、改写、翻译、总结，或提取行动项，无需离开当前笔记。
当面板提出对文件的修改时，会先打开检查模态框。你可以逐项审阅编辑内容，只应用需要的部分；随后，Agent 会在聊天中写入一个检查点标记，使你之后能够通过 Vault Operator 其他地方使用的同一检查点系统撤销这项修改。
通过块级溯源捕获资料来源
将 PDF、网页剪藏内容或 Office 文件拖入聊天窗口。Vault Operator 会根据你的知识库本体进行快速分类；如果你选择摄取，它会在写入任何内容之前引导你完成一个简短对话流程。
生成的意义梳理笔记会在每条主张末尾附带一个 ↗ 链接。该链接会跳转回来源中的精确内容块。你不再会遇到“我记得在某处有一条关于此事的笔记”，却无法追溯该主张来源的问题。
你可以通过自然语言在聊天中驱动这一过程：“Ingest this PDF”会执行快速的单次资料捕获；“Do a deep ingest of this paper”则会启动深度流程（分类、选择主题、标注来源、生成意义梳理笔记、添加反向链接）。五步深度流程会在每个问题处暂停并等待你的确认。
示例提示词：“Deep-ingest this research paper. Focus on the methodology section.”
快速摄取教程 | 深度摄取教程 | 知识摄取指南 | 块级溯源
将网页剪藏为永久笔记
自 v3.3.6 起可用。
要求 Agent 剪藏一篇文章后，它会像 Obsidian Web Clipper 一样归档该页面：将完整正文转换为 Markdown，将图片下载到你的知识库并把链接改写为本地嵌入链接，同时在顶部写入一个页头（frontmatter 加上 Agent 自己生成的摘要）。这比 web_fetch 更进一步：后者只会将页面读入对话，将图片保留为远程 URL，并截断较长文本。页面 URL 和每个图片 URL 都会经过与 web_fetch 相同的网络防护链。
示例提示词：“Clip this article into Sources/ and write a short summary into the header: https://example.com/article”
跨会话的三层记忆
Vault Operator 会在不同聊天之间记住重要内容，而不仅限于单次聊天内部。
- Soul 保存长期偏好（写作风格、项目约定、重复出现的选择）。
- Facts 保存关于人物、项目和主题的结构化陈述。
- History 是可搜索的历史对话记录。
Agent 会在新聊天开始时从这三层中检索信息；你也可以将任意笔记标记为记忆来源，使其内容持续保留在上下文范围内。
示例提示词：“Summarize this meeting note like last time.”（它会记住你偏好的格式。）
按语义查找笔记
当你询问“我对 X 了解什么？”时，Vault Operator 不会只用 grep 搜索文件名。它会在本地语义索引中按含义搜索，遍历 wikilink 和 frontmatter，并呈现你可能遗漏的关联。
语义索引采用自愿启用机制。你只需开启一次，并选择构建时机：从不（默认）、启动时，或切换 Agent 时。此后，搜索就像一位读过每一篇笔记的图书管理员。
示例提示词：“Find all notes related to behavioral economics and show me how they connect.”
创建 Word、Excel 和 PowerPoint 文件（PPTX 为 Beta 版）
Vault Operator 可基于你的知识库内容生成 .docx、.xlsx 和 .pptx 文件。
DOCX 和 XLSX 输出干净、可靠，适合日常使用。PPTX 采用单一流水线：Agent 首先调用 plan_presentation，将源笔记转换为受约束的大纲，然后由 create_pptx 构建演示文稿。PPTX 目前处于 Beta 阶段，应将其输出视为草稿；面向客户的演示文稿仍建议手动完成最后润色。
示例提示词：“Turn this note into a Word document with proper headings and a table of contents.” “Build a five-slide internal status presentation from my meeting notes.”
Office 文档指南（Beta 细节） | Office 流水线工作原理
通过 Vault Health 保持知识库可导航
知识库会逐渐失序。笔记堆积在不同文件夹中，相关想法不再彼此链接，标签也会分叉。
Vault Operator 会在后台执行隐式关联分析，并找出语义相近但没有 wikilink 的笔记对。知识库健康检查则更进一步：它会标记孤立笔记、失效链接、不一致的标签、缺失的反向链接，以及“上帝节点”（连接过多，以至于成为瓶颈而非有用枢纽的笔记）。它还会将你的文件夹和标签结构，与其在知识图谱中识别出的主题聚类进行对比。
示例提示词：“Run a health check on my vault and tell me what needs fixing.”
Vault Operator 内置 MCP 服务器。Claude Desktop、ChatGPT、Perplexity、Claude Code 以及任何兼容 MCP 的客户端，都可以读取你的知识库、从记忆层检索信息，并追加到你的对话历史中。
每次外部调用都会携带 source_interface 标签，因此可以按接入界面区分记忆和历史记录。严格来源隔离默认关闭。如果你希望某个界面与其他界面隔离，可在 Settings > Vault Operator > Agents > Memory 下按界面启用。
当你需要额外工具时，也可以将 Vault Operator 指向外部 MCP 服务器。
**示例提示词：**在 ChatGPT 中：“Recall what my Vault Operator memory says about pricing strategy.”
发现并使用已安装的插件
Vault Operator 会在启动时扫描已安装插件，并为每个插件生成一个技能文件。它可以运行 Obsidian 命令、调用插件 API，并将多个插件串联为一个工作流。
Dataview 查询、Kanban 看板、Templater 模板、Tasks、Excalidraw：只要你安装了相应插件，Agent 就能使用它。
示例提示词：“Create a Kanban board from the open tasks in my project notes.”
通过自动审批界面保持控制权
每次文件修改都会征求你的批准。每次编辑都会创建一个可一键撤销的快照。操作日志会记录每一步。
在 Settings > Vault Operator > Agents > Auto-approve 下，你可以决定哪些类别可静默执行，哪些类别需要持续询问：读取、写入、网页、知识库、插件 API 读取、插件 API 写入、配方和 MCP 调用。若希望每项操作都显示出来，也可以将所有类别都设为“每次询问”。
你可以选择 AI 模型，也可以决定哪些内容会被发送到云端。如果希望完全不依赖云端，可通过 Ollama 或 LM Studio 在本地运行所有内容。
**不会有意外：**Vault Operator 不会在未先向你展示 diff 的情况下修改文件。
它会学习你的工作方式
当 Agent 成功完成一项任务后，它会记住所使用的工具序列。经过数次重复后，辅助模型会根据匹配的配方规划一次确定性的执行过程，并跳过大部分迭代推理。相同任务所需的 LLM 调用可从八次降至两次，token 消耗可从数十万降至数十个。
它会委派复杂工作
对于跨越多个主题的任务，Vault Operator 可以生成子 Agent。一个子 Agent 可以研究会议笔记，另一个可以搜索网页，第三个则将两者整合为文档。子 Agent 在隔离环境中运行，各自拥有独立的对话上下文；主 Agent 会收集并组合它们的结果。
示例提示词：“Compare what my vault says about pricing strategy with the latest market research online, then write a recommendation note.”
在合适的时机运行合适的模型
你只需配置一次提供商。Vault Operator 会发现其模型，将它们分类为 Budget、Main 和 Frontier，并默认使用 Main 运行聊天循环。当 Agent 遇到困难时，consult_flagship 工具会将一次综合步骤升级至 Frontier；每项任务最多三次调用，输出 token 上限为 3000。低成本后台工作（上下文压缩、快速路径规划、演示文稿规划、配方晋升）则会路由到你一次选定的独立辅助模型。
使用成本
Vault Operator 本身免费且开源。你只需为所使用的 AI 模型付费。
| 选项 | 每月成本 |
|---|---|
| Google Gemini（免费层） | 免费 |
| Ollama / LM Studio（本地） | 免费（使用你的硬件） |
| OpenRouter（云端） | 按 token 计费，通常每天 0.50 至 5 美元 |
| Anthropic / OpenAI（直连） | 按 token 计费，通常每天 1 至 10 美元 |
| GitHub Copilot（订阅） | 包含在 Copilot 订阅中 |
| ChatGPT Plus / Pro（OAuth） | 包含在现有订阅中 |
成本感知循环（顾问模式、辅助模型路由、KV-cache 对齐、上下文外部化、提示词精简）可将 token 使用量维持在较低水平。对于简单的搜索与摘要任务，相同工作负载的 token 消耗可从约 63.4 万降至约 6 万。
English / 原文
What Vault Operator can do
Most AI tools sit outside your knowledge base and wait for you to copy and paste. Vault Operator lives inside it. It reads your notes, follows the graph that ties them together, picks up your habits, and acts on your behalf.
This page is the short tour. Each section links out to the guide that goes deep.
Prefer to watch? This 7-minute animated explainer walks through the agent from the inside: the loop, the harness with its five gates, tools, skills, and MCP, then one real job crossing every layer.
Your browser does not support embedded video. Download the explainer instead.
Inline AI chat in the editor
Available since v3.0.0.
You can run a chat directly on the note you are reading. Select text, press Cmd+Shift+I (Ctrl+Shift+I on Windows and Linux) or right-click and pick "Inline AI chat", and a floating panel opens over the editor. From there you ask a question about the selection, look something up, rewrite, translate, summarize, or extract action items without leaving the note.
When the panel proposes a change to the file, the check modal opens first. You review each edit, apply only the ones you want, and the agent writes a checkpoint marker into the chat so you can undo the change later through the same checkpoint system used elsewhere in Vault Operator.
Inline chat guide | Chat interface | Safety and control
Capture sources with block-level provenance
Drop a PDF, web clip, or Office file into the chat. Vault Operator runs a fast triage against your vault's ontology and, if you choose to ingest, walks you through a short dialog before it writes anything.
The resulting sense-making note carries a ↗ link at the end of every claim. The link jumps back to the exact block in the source. No more "I have a note about this somewhere" without a path back to where the claim came from.
You drive this from chat in plain language: "Ingest this PDF" runs the quick single-pass capture, "Do a deep ingest of this paper" starts the deep path (triage, topic pick, source markup, sense-making note, backlinks). The five-step deep flow stops at each question and waits for you.
Example prompt: "Deep-ingest this research paper. Focus on the methodology section."
Quick ingest tutorial | Deep ingest tutorial | Knowledge ingest guide | Block-level provenance
Clip web pages into permanent notes
Available since v3.3.6.
Ask the agent to clip an article and it archives the page the way the Obsidian Web Clipper does: the full text converted to Markdown, the images downloaded into your vault with the links rewritten to local embeds, and a header the agent writes on top (frontmatter plus its own summary). This goes further than web_fetch, which reads a page into the conversation, keeps images as remote URLs, and truncates long text. The page URL and every image URL pass the same network guard chain as web_fetch.
Example prompt: "Clip this article into Sources/ and write a short summary into the header: https://example.com/article"
Vault operations | Safety and control
Three-layer memory across sessions
Vault Operator remembers what matters across chats, not only inside one chat.
- Soul holds long-lived preferences (writing style, project conventions, recurring choices).
- Facts hold structured statements about people, projects, and topics.
- History is a searchable transcript of past conversations.
The agent retrieves from all three layers when a new chat starts, and you can mark any note as a memory source so its content stays in scope.
Example prompt: "Summarize this meeting note like last time." (It remembers your preferred format.)
Memory and personalization | How memory works | Mastery and recipes
Find notes by meaning
When you ask "what do I know about X?", Vault Operator does not grep filenames. It searches by meaning over a local semantic index, walks wikilinks and frontmatter, and surfaces connections you may have missed.
The semantic index is opt-in. Turn it on once and pick when it builds: never (default), on startup, or on agent switch. After that, search behaves like a librarian who has read every note.
Example prompt: "Find all notes related to behavioral economics and show me how they connect."
Search by meaning tutorial | Knowledge discovery | How the knowledge layer works
Build Word, Excel, and PowerPoint files (PPTX in beta)
Vault Operator writes .docx, .xlsx, and .pptx files from your vault content.
DOCX and XLSX output is clean and reliable for everyday use. PPTX runs as a single pipeline: the agent first calls plan_presentation to turn your source notes into a constrained outline, then create_pptx builds the deck. PPTX is in beta, treat the output as a draft you finish manually for client-facing decks.
Example prompts: "Turn this note into a Word document with proper headings and a table of contents." "Build a five-slide internal status presentation from my meeting notes."
Office documents guide (beta details) | How the office pipeline works
Keep the vault navigable with Vault Health
Vaults drift. Notes pile up in different folders, related ideas stop linking to each other, tags fork.
Vault Operator runs implicit connection analysis in the background and surfaces note pairs that are semantically close but have no wikilink. The vault health check goes further: it flags orphaned notes, broken links, inconsistent tags, missing backlinks, and "god nodes" (notes with so many connections they become bottlenecks instead of useful hubs). It also compares your folder and tag structure against the topic clusters it detects in the knowledge graph.
Example prompt: "Run a health check on my vault and tell me what needs fixing."
Vault health check | Knowledge discovery
Vault Operator ships an MCP server. Claude Desktop, ChatGPT, Perplexity, Claude Code, and any MCP-compatible client can read your vault, retrieve from the memory layer, and append to your conversation history.
Every external call carries a source_interface tag, so memory and history stay separable per surface. Strict source isolation is off by default. You opt in per surface under Settings > Vault Operator > Agents > Memory if you want a surface walled off from the rest.
You can also point Vault Operator at external MCP servers when you need extra tools.
Example prompt: In ChatGPT: "Recall what my Vault Operator memory says about pricing strategy."
Connectors guide | Unified chat memory | MCP architecture
Discover and use your installed plugins
Vault Operator scans your installed plugins at startup and generates a skill file for each one. It can run Obsidian commands, call plugin APIs, and stitch multiple plugins into one workflow.
Dataview queries, Kanban boards, Templater templates, Tasks, Excalidraw: if you have the plugin installed, the agent can use it.
Example prompt: "Create a Kanban board from the open tasks in my project notes."
Skills, rules, and workflows | How plugin discovery works
Stay in control via the auto-approval surface
Every file change asks for your approval. Every edit creates a snapshot you can undo with one click. The operation log records every step.
Under Settings > Vault Operator > Agents > Auto-approve you decide which categories run silently and which keep asking: read, write, web, vault, plugin API reads, plugin API writes, recipes, and MCP calls. You can also keep "ask every time" everywhere if you want every action to surface.
You pick the AI model. You decide what gets sent to the cloud. If you want zero cloud dependency, run everything locally with Ollama or LM Studio.
No surprises: Vault Operator cannot change a file without showing you the diff first.
Safety and control | How governance works
It learns how you work
When the agent completes a task successfully, it remembers the tool sequence. After a few repetitions, the helper model plans a single deterministic execution from the matching recipe and skips most of the iterative reasoning. The same task drops from eight LLM calls to two, and from hundreds of thousands of tokens to tens.
It delegates complex work
For tasks that span multiple topics, Vault Operator can spawn sub-agents. One can research meeting notes while another searches the web. A third stitches both into a document. Sub-agents run in isolation, each with their own conversation context. The main agent collects and combines their results.
Example prompt: "Compare what my vault says about pricing strategy with the latest market research online, then write a recommendation note."
It runs the right model at the right time
You configure a provider once. Vault Operator discovers its models, sorts them into Budget, Main, and Frontier, and runs the chat loop on Main by default. The consult_flagship tool escalates one synthesis step to Frontier when the agent struggles, capped at three calls per task and 3000 output tokens. Cheap background work (context condensing, fast-path planning, presentation planning, recipe promotion) routes to a separate helper model you pick once.
Choosing a model | Providers reference
What it costs
Vault Operator itself is free and open source. You pay only for the AI model you use.
| Option | Monthly cost |
|---|---|
| Google Gemini (free tier) | Free |
| Ollama / LM Studio (local) | Free (your hardware) |
| OpenRouter (cloud) | Pay per token, typically $0.50 to $5 per day |
| Anthropic / OpenAI (direct) | Pay per token, typically $1 to $10 per day |
| GitHub Copilot (subscription) | Included with Copilot subscription |
| ChatGPT Plus / Pro (OAuth) | Included with the existing subscription |
The cost-aware loop (advisor pattern, helper-model routing, KV-cache alignment, context externalization, prompt slim-down) keeps token use low. On simple search-and-summarize tasks the same workload drops from around 634K tokens to around 60K.