Obsidian 进入 Claude Agent 工作流：从资料读取、引用保留到安全回写

很多人把 Claude 放进 Obsidian 后，第一件事是让它总结当前笔记。

这一步很快就能跑通，后面的问题却会一起出现：它读的是哪一版资料？结论对应哪个来源？生成的新笔记应该放到哪里？如果 Agent 改错了原文，能不能恢复？

一套能长期使用的工作流，需要把“聊天”拆成一条可检查的数据链：资料先归档，Agent 按范围读取，结论保留出处，修改进入草稿区，确认后再回写正式笔记。

本文给出一套可以直接照着搭建的方案。你不需要一次装很多插件，也不需要先做向量数据库。先从 Obsidian 原生的 Markdown 文件和一份 CLAUDE.md 开始，就能跑出第一版。

为什么 Obsidian 适合进入 Agent 工作流

Obsidian 的 Vault 在文件系统里就是一个目录，主要内容是普通 Markdown 文件。笔记不锁在专有数据库里，Claude Code 之类能够访问本地文件的 Agent，可以按目录搜索和读取；其他客户端也能借助 MCP 或 Obsidian 社区插件访问同一批资料。

这带来三个实用条件：

1. 资料可搬迁。 Markdown 文件可以进入 Git、备份盘或其他编辑器，不依赖某个 AI 插件才能读取。
2. 规则能落到文件。 目录边界、命名规范、引用格式和写入权限，都可以写进 CLAUDE.md，每次任务重复使用。
3. 修改容易审查。 Agent 改了哪几行、增加了什么结论，可以通过文件差异或 Git 记录检查。

公开案例里已经出现两类实践。一类让 Claude Code 直接打开 Vault，把日记、项目资料和写作素材作为上下文；另一类通过 Obsidian 插件或 MCP 暴露搜索、反向链接、标签和受控写入工具。社区项目 WeSight 还把选题、内容生产、排版和复盘放进同一个本地库。它们说明这条路线已经有人在使用，但每个项目的效果和安全边界不同，不能把博主体验当成 Obsidian 或 Anthropic 的官方承诺。

三种接入方式，先选最轻的一种

方式一：让 Claude Code 直接读取 Vault

这是最适合起步的方案。

把 Vault 作为项目目录打开，或者在 Agent 的工作区中挂载需要使用的笔记目录。Claude Code 可以像处理代码仓库一样搜索 Markdown、跟随 WikiLink、创建草稿和整理目录。

它的优点是配置少、行为直观、文件变化容易检查。缺点也很明确：Agent 看到的是文件系统，不会自动理解 Obsidian 的全部插件语义；Vault 过大时，也不能每次把所有笔记塞进上下文。

适合这几类任务：

• 根据若干来源笔记整理研究简报；
• 把会议记录拆成任务和决策；
• 给旧笔记补标签、摘要和关联建议；
• 从项目资料生成周报、教程或 FAQ；
• 检查断链、重复标题和不一致的 Frontmatter。

下图是公开教程中的一个典型做法：左侧由 Claude Code 生成或读取 Vault 规则，右侧在 Obsidian 中查看最终效果。它展示了 CLAUDE.md 的位置，但规则内容仍需根据自己的目录和权限重新编写。

方式二：通过 MCP 提供专用的 Vault 工具

当你需要更稳定的“搜索笔记、读取反向链接、更新 Frontmatter、移动笔记”等操作，可以增加 MCP Server。

以开源项目 LWaetzig/obsidian-mcp 为例，它把 Vault 视为 Markdown 目录，无需 Obsidian 一直运行；配置后，Claude Code、Claude Desktop、Cursor 等 MCP 客户端可以调用专用工具。另一个 StevenStavrakis/obsidian-mcp 项目则明确提醒：服务拥有读写 Vault 的能力，使用前应做好备份，并只暴露指定目录。

MCP 适合下面这些情况：

• 多个 Agent 客户端要访问同一套笔记；
• 希望把搜索、创建、移动、标签更新变成固定工具；
• 需要比普通文件读写更清晰的参数和返回结果；
• 想把 Vault 接入更长的自动化流程。

它不会自动解决资料质量、引用和权限问题。MCP 只是连接层，Agent 可以调用哪些写工具、哪些目录允许修改，仍需要你设置。

方式三：在 Obsidian 内使用可审查的 Agent 插件

如果你希望在 Obsidian 界面里完成对话、选中笔记和审查修改，可以选择社区插件。

例如 Companion for Claude 提供 Vault 上下文、Agent 模式、可逐段接受或拒绝的差异审查，以及可选的本地 MCP Bridge。其公开说明显示，读取默认开放，创建和编辑需要确认；本地 Bridge 绑定到 127.0.0.1，并使用 Bearer Token。插件还支持自定义 Base URL。

需要说明的是，这属于独立社区插件，并非 Anthropic 或 Obsidian 的官方产品。安装前要检查维护状态、权限范围、数据会发往哪里，以及插件是否符合团队的安全要求。

三种方式可以这样选：

十分钟跑通：先用“直接读取 Vault”完成最小闭环

下面以 Windows 为例。这个版本不安装 MCP，也不依赖 Obsidian 社区插件，适合先验证工作方式。

准备工作

你需要准备：

• Obsidian 桌面版和一个测试 Vault；
• 已经能够正常运行的 Claude Code；
• 一份无敏感信息的 Markdown 测试资料；
• Vault 的备份，或者直接复制一个测试副本。

不要拿正在使用的主知识库做第一次测试。新建一个名为 Obsidian-Agent-Demo 的 Vault，放入三五篇公开资料即可。

第一步：在 Vault 中启动 Claude Code

在 PowerShell 中进入 Vault：

Set-Location -LiteralPath "D:\Notes\Obsidian-Agent-Demo"
claude

Set-Location -LiteralPath "D:\Notes\Obsidian-Agent-Demo"
claude

如果 Vault 路径包含中文或空格，保留双引号并使用 -LiteralPath。Claude Code 启动后，先让它只做读取测试：

列出当前目录下的 Markdown 文件和一级目录。
不要创建、修改、移动或删除任何文件。

列出当前目录下的 Markdown 文件和一级目录。
不要创建、修改、移动或删除任何文件。

此时应只看到文件清单，不应出现写入动作。

第二步：创建最小目录

可以手动创建，也可以让 Claude Code 生成目录。第一次建议手动创建，方便确认路径：

$folders = @(
  "00_Inbox",
  "10_Sources\Web",
  "10_Sources\Meetings",
  "20_Notes\_drafts",
  "20_Notes\Concepts",
  "30_Projects\_drafts",
  "90_Archive"
)

foreach ($folder in $folders) {
  New-Item -ItemType Directory -Force -Path $folder | Out-Null
}

$folders = @(
  "00_Inbox",
  "10_Sources\Web",
  "10_Sources\Meetings",
  "20_Notes\_drafts",
  "20_Notes\Concepts",
  "30_Projects\_drafts",
  "90_Archive"
)

foreach ($folder in $folders) {
  New-Item -ItemType Directory -Force -Path $folder | Out-Null
}

把测试文章放入 10_Sources/Web/，文件名尽量使用能看懂的主题，而不是网页下载时留下的一串随机字符。

第三步：放入 CLAUDE.md

将本文后面的规则模板保存为 Vault 根目录下的 CLAUDE.md。重新打开 Claude Code 后，先提问：

请复述当前 Vault 的读取范围、写入范围和必须人工确认的动作。
不要执行任何文件操作。

请复述当前 Vault 的读取范围、写入范围和必须人工确认的动作。
不要执行任何文件操作。

正确结果应该明确提到：来源目录只读、草稿目录可写、删除和移动要确认。如果回答缺少这些边界，先检查 CLAUDE.md 是否位于当前工作目录，目录名称是否与规则一致。

第四步：完成一次受控写入

让 Agent 读取一篇来源，只在草稿区生成笔记。完成后运行：

Get-ChildItem -LiteralPath ".\20_Notes\_drafts" -Filter "*.md"

Get-ChildItem -LiteralPath ".\20_Notes\_drafts" -Filter "*.md"

再检查来源文件的最后修改时间：

Get-ChildItem -LiteralPath ".\10_Sources" -Recurse -File |
  Select-Object FullName, LastWriteTime

Get-ChildItem -LiteralPath ".\10_Sources" -Recurse -File |
  Select-Object FullName, LastWriteTime

来源文件时间不应变化。确认这一步后，最小闭环就跑通了：Agent 能读来源、能在指定目录写草稿、不会碰原始资料。

需要专用工具时，再增加 MCP

普通文件读写无法满足反向链接、标签查询或多客户端共享时，可以增加 Obsidian MCP Server。以下命令以开源项目 obsidian-mcp 的 npx 运行方式为例，配置前先备份 Vault：

claude mcp add obsidian -- npx -y obsidian-mcp "D:\Notes\Obsidian-Agent-Demo"
claude mcp list

claude mcp add obsidian -- npx -y obsidian-mcp "D:\Notes\Obsidian-Agent-Demo"
claude mcp list

不同 MCP 项目的包名、参数和 Node.js 要求可能不同。复制命令前，应以对应仓库当前 README 为准。连接成功后先测试读操作：

使用 obsidian 工具搜索标题包含“Agent”的笔记。
只返回文件路径和匹配标题，不执行写入。

使用 obsidian 工具搜索标题包含“Agent”的笔记。
只返回文件路径和匹配标题，不执行写入。

读操作通过后，再测试向 _drafts 新建一份空白笔记。不要在首次连接时开放删除、批量移动和全库改写。

MCP 上线前要核对四项配置

如果团队里多人使用，建议给 Agent 单独准备同步后的工作副本。Agent 完成草稿后，通过 Git Pull Request、文件审核或人工移动进入正式 Vault，避免多人和 Agent 同时修改同一个文件。

先整理目录：原始资料和 Agent 草稿必须分开

下面是一份足够小的目录模板：

MyVault/
├─ 00_Inbox/                 # 临时收集，待处理
├─ 10_Sources/               # 原始来源，只读
│  ├─ Web/
│  ├─ Reports/
│  └─ Meetings/
├─ 20_Notes/                 # 已确认的长期知识
│  ├─ Concepts/
│  ├─ Cases/
│  └─ _drafts/               # Agent 草稿，只写这里
├─ 30_Projects/              # 具体项目与交付物
├─ 90_Archive/               # 归档内容
├─ Templates/
└─ CLAUDE.md

MyVault/
├─ 00_Inbox/                 # 临时收集，待处理
├─ 10_Sources/               # 原始来源，只读
│  ├─ Web/
│  ├─ Reports/
│  └─ Meetings/
├─ 20_Notes/                 # 已确认的长期知识
│  ├─ Concepts/
│  ├─ Cases/
│  └─ _drafts/               # Agent 草稿，只写这里
├─ 30_Projects/              # 具体项目与交付物
├─ 90_Archive/               # 归档内容
├─ Templates/
└─ CLAUDE.md

这里最有用的设计只有两条：

• 10_Sources 保存原始材料，Agent 只能读取；
• 新内容先进入 20_Notes/_drafts，确认后再移动到正式目录。

如果已有成熟的 PARA、Zettelkasten 或项目目录，不必整体重构。给现有目录标明“来源区、草稿区、正式区”也能达到同样目的。

给来源笔记加上最小元数据

一篇网页或公众号文章保存为 Markdown 后，建议保留这几个字段：

---
title: "文章标题"
source_url: "https://example.com/article"
author: "作者或机构"
published_at: "2026-08-20"
retrieved_at: "2026-08-22"
source_type: "web"
status: "source"
---

---
title: "文章标题"
source_url: "https://example.com/article"
author: "作者或机构"
published_at: "2026-08-20"
retrieved_at: "2026-08-22"
source_type: "web"
status: "source"
---

published_at 表示原内容什么时候发布，retrieved_at 表示你什么时候保存。两者分开后，Agent 在处理时效性内容时不容易混淆。

正文尽量保留小标题和原始链接。网页截图可以作为附件，关键结论仍要落成可搜索的文字。PDF 资料还应记录页码；如果使用 OCR，最好标记文本来自识别结果，避免把识别错误当成原文。

写一份能约束 Agent 的 CLAUDE.md

把下面模板保存到 Vault 根目录，再按自己的目录改名：

# Vault 工作规则

## 读取范围
- 可以读取：10_Sources、20_Notes、30_Projects
- 默认先搜索标题和摘要，再读取最相关的文件
- 不要一次读取整个 Vault

## 写入范围
- 只能新建或修改：20_Notes/_drafts、30_Projects/_drafts
- 不得修改、移动或删除 10_Sources 中的文件
- 不得批量重命名正式笔记

## 引用要求
- 每个外部事实保留 source_url
- 引用本地资料时写出来源笔记路径
- PDF 资料标注页码；网页资料保留标题和链接
- 找不到依据时标记“待核验”，不要补写成事实

## 输出格式
- 新笔记必须包含 title、summary、sources、status、updated
- status 默认写 draft
- 结尾列出：已确认事实、待核验信息、建议关联笔记

## 执行规则
- 修改旧笔记前先给出变更摘要
- 涉及覆盖、移动、删除时必须等待人工确认
- 一次只处理用户指定的任务范围

# Vault 工作规则

## 读取范围
- 可以读取：10_Sources、20_Notes、30_Projects
- 默认先搜索标题和摘要，再读取最相关的文件
- 不要一次读取整个 Vault

## 写入范围
- 只能新建或修改：20_Notes/_drafts、30_Projects/_drafts
- 不得修改、移动或删除 10_Sources 中的文件
- 不得批量重命名正式笔记

## 引用要求
- 每个外部事实保留 source_url
- 引用本地资料时写出来源笔记路径
- PDF 资料标注页码；网页资料保留标题和链接
- 找不到依据时标记“待核验”，不要补写成事实

## 输出格式
- 新笔记必须包含 title、summary、sources、status、updated
- status 默认写 draft
- 结尾列出：已确认事实、待核验信息、建议关联笔记

## 执行规则
- 修改旧笔记前先给出变更摘要
- 涉及覆盖、移动、删除时必须等待人工确认
- 一次只处理用户指定的任务范围

这份规则无法替代操作系统权限。如果 Agent 本身拥有整个磁盘的写权限，提示词只能降低误操作概率。对团队资料或重要 Vault，应继续使用文件权限、容器、独立副本或版本控制限制影响范围。

跑通第一个任务：从一份来源生成可核验笔记

先挑一篇已经保存到 10_Sources/Web/ 的资料，然后给 Agent 下面这段任务：

读取 10_Sources/Web/obsidian-agent-source.md。

在 20_Notes/_drafts/ 中创建一份研究笔记，要求：
1. 用 150 字说明资料讨论的问题；
2. 提取 5 条有实际信息的结论；
3. 每条结论附原文小标题、来源笔记路径和 source_url；
4. 把无法从原文确认的说法放进“待核验”；
5. 不修改来源文件，不移动任何旧笔记；
6. 完成后只报告新建文件路径和引用数量。

读取 10_Sources/Web/obsidian-agent-source.md。

在 20_Notes/_drafts/ 中创建一份研究笔记，要求：
1. 用 150 字说明资料讨论的问题；
2. 提取 5 条有实际信息的结论；
3. 每条结论附原文小标题、来源笔记路径和 source_url；
4. 把无法从原文确认的说法放进“待核验”；
5. 不修改来源文件，不移动任何旧笔记；
6. 完成后只报告新建文件路径和引用数量。

任务完成后，不要只看摘要是否顺口。按下面四项验收：

1. 随机点开两条引用，确认原文确实支持结论；
2. 检查是否把作者判断写成了客观事实；
3. 检查新笔记有没有覆盖旧文件；
4. 确认后，把草稿移动到 20_Notes/Cases/ 或项目目录。

这一轮通过后，再增加批量处理、反向链接或自动标签。先验证单篇资料，出错时更容易找到原因。

三个可以直接复用的任务模板

场景一：把网页资料整理成研究卡片

适合产品调研、行业研究和选题资料库。

任务：把 10_Sources/Web/ 下今天新增的资料整理成研究卡片。

执行要求：
- 每份来源单独生成一张卡片，保存到 20_Notes/_drafts/；
- 保留原始标题、作者、发布日期、抓取日期和 source_url；
- 摘要限制在 200 字内；
- 提取“事实”“作者判断”“可行动信息”三个部分；
- 每条事实写出对应的小标题或原文位置；
- 多篇资料说法冲突时并列记录，不要自行合并；
- 没有依据的数据标记为待核验；
- 不修改 10_Sources 中的文件。

完成后输出：生成文件清单、引用总数、待核验问题清单。

任务：把 10_Sources/Web/ 下今天新增的资料整理成研究卡片。

执行要求：
- 每份来源单独生成一张卡片，保存到 20_Notes/_drafts/；
- 保留原始标题、作者、发布日期、抓取日期和 source_url；
- 摘要限制在 200 字内；
- 提取“事实”“作者判断”“可行动信息”三个部分；
- 每条事实写出对应的小标题或原文位置；
- 多篇资料说法冲突时并列记录，不要自行合并；
- 没有依据的数据标记为待核验；
- 不修改 10_Sources 中的文件。

完成后输出：生成文件清单、引用总数、待核验问题清单。

验收时重点检查作者观点有没有被写成行业事实，以及二手报道是否保留了原始信源。

场景二：把会议记录变成决策和任务

适合周会、项目复盘和客户沟通记录。

读取 10_Sources/Meetings/2026-08-22-项目周会.md。

在 30_Projects/_drafts/ 中生成会议整理稿，包含：
1. 已达成的决策；
2. 待办任务、负责人和截止日期；
3. 尚未解决的分歧；
4. 需要补充的资料；
5. 每一项对应的原始会议记录段落。

如果会议中没有明确负责人或日期，填写“未指定”，不要猜测。
不要替任何人创建日历、发送消息或修改正式项目文档。

读取 10_Sources/Meetings/2026-08-22-项目周会.md。

在 30_Projects/_drafts/ 中生成会议整理稿，包含：
1. 已达成的决策；
2. 待办任务、负责人和截止日期；
3. 尚未解决的分歧；
4. 需要补充的资料；
5. 每一项对应的原始会议记录段落。

如果会议中没有明确负责人或日期，填写“未指定”，不要猜测。
不要替任何人创建日历、发送消息或修改正式项目文档。

会议记录最容易出现“模型替团队补全决定”的问题。提示词里明确写出“未指定”，比让模型追求表格完整更安全。

场景三：用已有笔记生成文章大纲

适合内容团队把资料库接入写作流程。

围绕“企业怎样安全地把 Obsidian 接入 Claude Agent”生成文章大纲。

资料范围：
- 10_Sources/Web/Obsidian/
- 20_Notes/Cases/Obsidian/

输出到：30_Projects/_drafts/obsidian-agent-outline.md

要求：
- 先列出实际使用的来源文件；
- 每个二级标题至少绑定一条来源；
- 区分官方资料、开源项目说明和博主体验；
- 不使用来源中无法核验的效率数字；
- 在大纲末尾列出仍缺少证据的段落；
- 暂时不要扩写正文。

围绕“企业怎样安全地把 Obsidian 接入 Claude Agent”生成文章大纲。

资料范围：
- 10_Sources/Web/Obsidian/
- 20_Notes/Cases/Obsidian/

输出到：30_Projects/_drafts/obsidian-agent-outline.md

要求：
- 先列出实际使用的来源文件；
- 每个二级标题至少绑定一条来源；
- 区分官方资料、开源项目说明和博主体验；
- 不使用来源中无法核验的效率数字；
- 在大纲末尾列出仍缺少证据的段落；
- 暂时不要扩写正文。

先生成带来源的大纲，再扩写文章，可以在写作前发现证据缺口。等正文写完才补来源，常会遇到结论已经超出资料范围的问题。

建立一份统一的草稿 Frontmatter

Agent 生成的笔记建议使用同一套字段，方便后续筛选和审核：

---
title: "Obsidian Agent 安全回写"
summary: "说明来源只读、草稿写入和人工审核的执行方法"
type: "research-note"
status: "draft"
created_by: "claude-agent"
created_at: "2026-08-22"
reviewed_by: ""
reviewed_at: ""
sources:
  - "[[10_Sources/Web/obsidian-agent-source]]"
tags:
  - obsidian
  - agent-workflow
---

---
title: "Obsidian Agent 安全回写"
summary: "说明来源只读、草稿写入和人工审核的执行方法"
type: "research-note"
status: "draft"
created_by: "claude-agent"
created_at: "2026-08-22"
reviewed_by: ""
reviewed_at: ""
sources:
  - "[[10_Sources/Web/obsidian-agent-source]]"
tags:
  - obsidian
  - agent-workflow
---

审核通过后，把 status 改为 reviewed，补上审核人和时间，再移动到正式目录。这样可以用 Obsidian Search、Dataview 或 Bases 筛出所有待审草稿，无需翻目录逐篇查找。

把“引用保留”做成固定格式

长期使用时，建议让每条知识都能回到来源。下面是一种简单格式：

## 结论

Claude Agent 接入笔记库时，应把原始来源与生成草稿分开。

**依据**
- 来源笔记：[[10_Sources/Web/obsidian-agent-source]]
- 原文位置：第 3 节“Write-back safety”
- 外部链接：https://example.com/article
- 核验状态：已核验

## 结论

Claude Agent 接入笔记库时，应把原始来源与生成草稿分开。

**依据**
- 来源笔记：[[10_Sources/Web/obsidian-agent-source]]
- 原文位置：第 3 节“Write-back safety”
- 外部链接：https://example.com/article
- 核验状态：已核验

如果要处理大量研究资料，可以进一步保存原文片段、页码、抓取时间和内容指纹。开源项目 codex-obsidian-workflow 就采用了页级或块级来源记录、行号与哈希绑定、冲突回滚等做法。个人笔记不一定需要全部实现，但“结论能回到哪段原文”值得保留。

安全回写：让 Agent 提议修改，不让它直接接管正式区

比较稳妥的写入流程分为四步：

1. 生成草稿。 新内容只进入 _drafts。
2. 显示差异。 修改已有笔记时，先查看新增、删除和替换的段落。
3. 人工确认。 接受需要的修改，拒绝错误或过度改写的部分。
4. 留下记录。 使用 Git、Obsidian Git 插件或定期快照保存历史。

如果所用插件支持逐段 diff，优先启用。直接使用 Claude Code 时，可以先要求它输出修改计划，再检查文件差异。对删除、移动、批量重命名、覆盖 Frontmatter 等动作，应始终保留人工确认。

建议一开始关闭这些权限：

• 删除文件；
• 修改 10_Sources；
• 批量移动或重命名；
• 自动发布到网站或公众号；
• 读取保存密码、合同原件、客户隐私的目录。

Vault 很大时，不要把全部笔记塞给模型

笔记超过几百篇后，直接把整个 Vault 当上下文会变慢，也会带来无关信息和额外 Token 消耗。更合适的检索顺序是：

1. 先按文件名、标签、Frontmatter 和关键词筛选；
2. 读取候选笔记的摘要与小标题；
3. 只展开与任务直接相关的正文；
4. 需要跨库语义搜索时，再增加本地索引或 MCP 工具。

摘要也不要替代原文。摘要适合导航，写结论时仍应回读相应段落。

一套省 Token 的分层读取方法

假设 Vault 有 3000 篇笔记，可以把一次研究任务拆成四轮：

1. 检索轮只返回文件路径、标题、标签和一句摘要；
2. 筛选轮从候选文件中选出 10—20 篇，读取目录和小标题；
3. 证据轮只打开能支持目标结论的具体段落；
4. 写作轮把已经确认的证据包交给模型生成草稿。

每轮都保存中间结果，失败时不用从全库检索重新开始。反复使用的项目背景、写作规范和模板可以通过提示词缓存或本地摘要复用；经常变化的网页数据仍应在任务开始时重新核验。

敏感资料怎么处理

可以先按风险给 Vault 内容分级：

接入第三方插件前，还要确认四个问题：资料是否离开本机、发送到哪个模型服务、日志保存多久、插件能否读取整个 Vault。无法回答时，先使用测试库和公开资料。

Apito 放在这套架构的哪一层

Obsidian 负责本地知识和编辑界面，Claude Agent 负责理解任务、调用工具与生成内容，MCP 或插件负责连接。Apito 位于模型访问层，用来配置 API Key、请求地址、模型选择、调用记录和成本观察。

如果使用的 Obsidian 插件或 Agent 客户端支持自定义 Anthropic 兼容 Base URL，可以把请求地址设置为 https://apito.ai，Key 和模型 ID 以 Apito 控制台当前可见配置为准。已经配置好的客户端通常只需更新请求地址，具体字段仍要以对应软件版本为准。

需要区分模型访问和本地权限：更换 Base URL 不会自动限制 Agent 能读哪些笔记，也不会替你完成写入审批。目录白名单、只读来源区、差异确认和版本备份仍要单独设置。

一份可以直接照着执行的上线清单

• [ ] 给 Vault 建立备份或 Git 版本记录；
• [ ] 标明来源区、草稿区和正式笔记区；
• [ ] 给来源笔记补 source_url、作者和日期；
• [ ] 在根目录创建 CLAUDE.md；
• [ ] 第一阶段只开放读取和草稿区写入；
• [ ] 用单篇资料测试引用是否能回到原文；
• [ ] 检查插件或 MCP 的实际权限和网络范围；
• [ ] 对移动、删除、覆盖和发布保留人工确认；
• [ ] 观察上下文长度与调用成本，再决定是否增加索引；
• [ ] 定期抽查生成笔记中的事实和失效链接。

完成这十项后，Obsidian 才从“Agent 能打开的笔记文件夹”变成一套可维护的知识工作区。

常见故障与排查方法

发布前的七项验收标准

一条 Obsidian Agent 流程达到下面七项，才适合从测试库迁入日常工作：

1. Agent 只能读取授权目录；
2. 原始来源在测试中没有被修改；
3. 新内容只写入草稿区；
4. 抽查的事实都能定位到来源段落或页码；
5. 删除、移动、覆盖和发布会等待人工确认；
6. 错误修改可以从 Git 或备份恢复；
7. 断开模型服务后，Markdown 笔记仍能正常阅读和迁移。

这七项里，任何一项失败都应继续留在测试环境。能生成漂亮摘要，只能证明模型会写；无法控制来源和写入范围，工作流仍不适合处理正式资料。

FAQ

1. Obsidian 必须一直打开吗？

不一定。Claude Code 直接读取 Markdown 目录时，Obsidian 可以关闭；依赖 Obsidian 插件或插件提供的本地 Bridge 时，通常需要 Obsidian 保持运行。MCP Server 是否依赖 Obsidian，要看具体实现。

2. 接入 Claude Agent 一定要使用 MCP 吗？

不需要。只做资料读取、生成草稿和整理 Markdown 时，直接访问 Vault 更简单。需要专用搜索、反向链接、标签管理或多客户端共享时，再增加 MCP。

3. 怎样避免 Agent 改坏原笔记？

把来源目录设为只读，只允许写入 _drafts；关闭删除和批量移动；修改正式笔记前查看 diff；给 Vault 使用 Git 或快照备份。提示词约束要和文件权限、版本记录一起使用。

4. PDF 和图片能直接进入这套流程吗？

取决于所用客户端或插件。支持 PDF/视觉输入时可以直接读取；否则需要先做文本提取或 OCR。研究笔记应保留 PDF 页码、图片文件名和 OCR 状态，方便复核。

5. Vault 太大，搜索结果不准怎么办？

先统一标题、标签和 Frontmatter，再让 Agent“先搜索、后读摘要、最后展开正文”。只有关键词检索无法满足时，才考虑语义索引。不要把整个 Vault 无差别发送给模型。

6. 可以通过 Apito 在 Obsidian 中调用 Claude 吗？

可以使用支持自定义 Anthropic 兼容 Base URL 的插件或客户端。把请求地址设置为 https://apito.ai，Key、模型 ID 和接口可用性以 Apito 控制台当前显示为准。第三方插件的兼容情况可能随版本变化，首次配置后应先做一次小请求测试。

参考资料

• Companion for Claude — Obsidian 社区插件页
• LWaetzig/obsidian-mcp — GitHub
• StevenStavrakis/obsidian-mcp — GitHub
• codex-obsidian-workflow：带来源追踪的本地知识工作流
• WeSight：Codex + Obsidian 内容工作流公开案例
• Obsidian for Claude Code: How to Use Your Vault as AI Memory
• Claude Code from the Sidebar — Obsidian Forum