obsidian

Obsidian 技能

路由策略

选择最符合用户意图的后端：

1. MCP（默认用于知识库数据操作）

   • 读取、写入、修补和搜索笔记
   • 使用 move_note 移动或重命名笔记，然后明确修复反向链接
   • 更新 frontmatter 和标签
   • 元数据和批量笔记操作

2. Obsidian CLI／应用上下文（仅在需要应用上下文时）

   • 通过 URI 在 Obsidian 中打开笔记
   • 触发 MCP 无法执行的应用／插件工作流

3. CLI git（同步／备份工作流）

   • 初始化仓库、配置远程端、提交、拉取、推送
   • 定期或手动备份／同步知识库的请求

请求含义不明确时，优先选择 MCP，除非用户明确要求执行同步／备份／git／应用相关操作。

安全的笔记重命名工作流

无论 Obsidian 是否正在运行，移动或重命名笔记时都使用 MCP move_note。不要自动调用 Obsidian CLI move 命令：延迟执行的链接重写可能会将过时的字节偏移量应用到移动开始后编辑过的笔记，进而悄无声息地破坏无关内容（#176）。只有在经过独立复测确认上游修复后，才重新考虑使用 CLI 移动笔记。

保留反向链接是明确且可验证的第二步：

1. 移动前，使用知识库相对路径和不带扩展名的文件名搜索旧的 wikilink 目标。如果 Obsidian 正在运行，其只读 backlinks 命令可以辅助发现，但不能替代 MCP 搜索。
2. 使用 MCP move_note 移动笔记。
3. 读取每篇引用笔记，仅修补完全匹配的 wikilink 目标，包括嵌入内容以及带别名或片段的链接。更改目标时保留显示文本（|alias）以及 #heading／#^block-id 后缀。
4. 再次搜索旧路径和旧文件名。报告仍然存在的引用，不要声称已成功完成。
5. search_notes 最多返回 20 条结果。如果搜索结果达到此上限，或者旧文件名存在歧义，请告知用户无法确认已穷尽修复所有反向链接，并在继续进行更广泛扫描前征求用户同意。

分别报告笔记移动和反向链接修复情况：移动了哪篇笔记、修改了多少篇引用笔记，以及仍然存在的过期引用。

注意事项

1. patch_note 默认会拒绝匹配多处的情况。 当 replaceAll: false 时，如果 oldString 出现多次，调用会失败并返回 matchCount。只有确实需要时才设置 replaceAll: true，或者添加上下文，使匹配结果唯一。

2. patch_note 会匹配 frontmatter 中的内容。 替换操作会针对整个文件执行，包括 YAML 块。像 title: 这样的通用字符串会匹配 frontmatter 字段。请提供足够的上下文，以定位正确的匹配项。

3. patch_note 不允许使用空字符串。 oldString 和 newString 都必须是非空且不全为空白字符的字符串。要删除文本，请将 newString 设为单个空格，或使用 write_note 重新整理笔记。

4. search_notes 返回的是压缩后的 JSON。 字段名称经过缩写：p（路径）、t（标题）、ex（摘录）、mc（匹配数量）、ln（行号）、uri（obsidianUri）。无论 limit 的值是多少，结果数量最多为 20。

5. search_notes 对多词查询会分别评估各个词项和完整短语的得分。 各个词项按 OR 匹配，因此只要文档匹配任意一个词项，就会出现在结果中。匹配完整短语会额外提高得分。

6. write_note 会自动创建目录。 父文件夹会递归创建。在 append/prepend 模式下，如果笔记不存在，则会创建笔记。使用 append/prepend 时，frontmatter 会合并（新键会覆盖旧键）；使用 overwrite 时，frontmatter 会被整体替换。

7. delete_note 要求确认路径完全一致。 confirmPath 必须与 path 的字符完全相同。不进行规范化，也不接受末尾斜杠差异。不匹配时会静默失败，返回 success: false。

8. move_file 需要双重确认。 confirmOldPath 和 confirmNewPath 必须分别与对应路径完全一致。重命名 Markdown 文件时请使用 move_note（能识别文本，无需确认）；仅在处理二进制文件或需要二进制安全移动时使用 move_file。

9. manage_tags 从两个来源读取，但只写入一个来源。 list 会合并 frontmatter 标签和行内 #hashtags。add/remove 只会修改 frontmatter 的 tags 数组，不会触碰行内标签。

10. read_multiple_notes 永远不会拒绝请求。 它在内部使用 allSettled。读取失败的文件会出现在 err 数组中，成功的文件会出现在 ok 数组中。务必检查两个数组。每次调用最多支持 10 个路径。

错误恢复

错误	下一步
patch_note "Found N occurrences"	在 oldString 中添加周围的行，使匹配结果唯一，或设置 replaceAll: true
delete_note / move_file 确认不匹配	使用 read_note 或 list_directory 重新读取笔记路径，然后用完全一致的字符串重试
search_notes 返回 0 个结果	尝试使用单个关键词而非短语，切换 searchFrontmatter，或使用更宽泛的部分词项
read_multiple_notes 的 err 不为空	使用 list_directory 验证失败的路径，修正拼写错误或缺失的扩展名，然后仅重试失败项

Git 同步模式

当用户要求“同步”“备份”或“用 git 存储我的库”时，请使用 CLI git，并遵循以下行为：

1. 在进行任何更改之前运行预检：

   • git 可用
   • 当前目录是 git 仓库（或提示用户初始化）
   • 已设置 git config user.name 和 git config user.email
   • 至少存在一个用于推送/拉取同步的远程仓库

2. 如果预检未完成，只提出一个有针对性的问题，并给出建议的默认选项。

   • 对于会实质性改变行为的决策，使用 askuserquestion。
   • 示例：
     • “未找到 git 仓库。现在在此库中初始化一个吗？（建议：是）”
     • “未配置远程仓库。现在通过 gh（如果可用）设置 GitHub 远程仓库，还是提供远程 URL？（建议：通过 gh 设置）”
     • “本地和远程已分叉。现在尝试 git pull --rebase 吗？（建议：是）”

3. 安全同步顺序（默认绝不强制推送）：

   • git add -A
   • git commit -m "vault sync: YYYY-MM-DD HH:mm"（没有更改时跳过提交）
   • git pull --rebase
   • git push

4. gh 为可选项：

   • 仅在用户要求时使用 gh 来初始化远程仓库（创建仓库/设置 origin）。
   • 远程仓库配置完成后，正常同步不需要 gh。

5. 遇到冲突时停止，并清楚说明后续步骤。

   • 不要悄悄自动解决合并冲突。
   • 说明失败的原因，以及用户接下来应该运行什么命令。

Obsidian CLI 模式

当用户要求执行应用上下文操作（当前文件、在编辑器中打开、使用模板的每日笔记、反向链接）时，直接通过 shell 命令使用 Obsidian CLI。

1. 首次使用 CLI 前，先运行预检：

   • 按以下候选项的优先级解析 CLI 二进制文件，使用第一个匹配项：

     优先级	macOS	Linux	Windows
     1	obsidian（PATH）	obsidian（PATH）	obsidian.exe 或 Obsidian.com（PATH）
     2	/Applications/Obsidian.app/Contents/MacOS/obsidian-cli	—	—
     3	/Applications/Obsidian.app/Contents/MacOS/Obsidian	—	—

     Obsidian 1.12.7+ 安装程序会捆绑专用的 obsidian-cli 二进制文件（速度约为旧版基于 Electron 的 CLI 的 10 倍：每次调用约 25ms，而非约 250ms）。在 macOS 上，安装 1.12.7+ 安装程序后，请在“设置”>“通用”>“高级”中先禁用 CLI，再重新启用，以更新 PATH 注册。此操作会将旧的 ~/.zprofile PATH 条目替换为指向 obsidian-cli 的 /usr/local/bin/obsidian 符号链接。

     在 Linux 上，PATH 注册会在 /usr/local/bin/obsidian 创建符号链接（或在无法创建时使用 ~/.local/bin/obsidian）。在 Windows 上，安装程序会在 Obsidian.exe 旁放置一个 Obsidian.com 终端重定向程序。

     **注意：**优先级表和过时 PATH 检查仅在 macOS 上经过验证。Linux 和 Windows 也可能随 1.12.7+ 安装程序捆绑 obsidian-cli，但尚未确认。欢迎通过 issue 或 PR 提交贡献。

   • **过时 PATH 检查（macOS）：**如果优先级 1 在 PATH 中解析到了 obsidian，请检查它指向的是快速二进制文件，还是较慢的 Electron 启动器：

     解析后的路径	含义	操作
     /usr/local/bin/obsidian → obsidian-cli	1.12.7 符号链接注册	无需操作——快速二进制文件
     /Applications/.../MacOS/obsidian	旧的 ~/.zprofile 条目（1.12.7 之前的注册，或安装 1.12.7 后未重新注册）	检查捆绑包中是否存在 obsidian-cli

     如果 obsidian 解析到 MacOS 目录（而非 /usr/local/bin），并且 /Applications/Obsidian.app/Contents/MacOS/obsidian-cli 存在，请告知用户： “已安装 Obsidian 1.12.7+，但 PATH 仍指向较慢的 Electron 二进制文件。在 Obsidian 中，前往‘设置’>‘通用’>‘高级’，先禁用 CLI，再重新启用，以更新 PATH 注册。” 继续使用匹配到的优先级——这只是提示，不会阻止操作。

   • 检查 Obsidian 是否正在运行：pgrep -xiq obsidian（macOS/Linux）或 tasklist /FI "IMAGENAME eq Obsidian.exe" /NH（Windows）

   • 如果任一检查失败，请告知用户，并回退到 MCP 工具和 obsidian:// URI

2. Vault 目标：obsidian vault="VaultName" <command>。如果设置了 OBSIDIAN_VAULT_NAME，请使用该明确值。否则运行 obsidian vaults，将 MCP vault 路径与已注册的 vault 匹配，并使用其注册名称。如果无法唯一匹配，请询问用户。切勿根据文件夹的基本名称推断注册名称。

3. 关键命令：

   # Read the currently active file
   obsidian read
   
   # Read a specific file
   obsidian read file="My Note"
   
   # Open a file in Obsidian
   obsidian open path="Notes/example.md"
   
   # Open today's daily note
   obsidian daily
   
   # Append to daily note
   obsidian daily:append content="- [ ] New task"
   
   # Search (Obsidian's own search, different from MCP's BM25)
   obsidian search query="meeting notes" limit=10
   
   # List all tags with frequency
   obsidian tags sort=count counts
   
   # Get backlinks for a note
   obsidian backlinks file="My Note"
   
   # Find unresolved links
   obsidian unresolved
   

   不要使用 obsidian move；请遵循安全笔记重命名工作流，使用 MCP move_note 并明确修复反向链接。

4. 运行 obsidian help 查看完整的命令参考。CLI 会随 Obsidian 版本更新而变化。

5. 何时使用 CLI，何时使用 MCP：

   • 对于读取、写入、搜索、标签、frontmatter，以及所有笔记移动/重命名，使用 MCP（经过沙箱隔离和验证，可在无头模式下运行）
   • 对于当前文件、使用模板的每日笔记、只读反向链接发现、在编辑器中打开，以及插件命令，使用 CLI
   • 执行 move_note 后，请遵循安全笔记重命名工作流，明确修复并验证反向链接
   • 如有疑问，优先使用 MCP

资源

仅在需要时加载，无需每次调用都加载。

• 工具模式 - 需要了解工具的响应格式、模式详情，或决定使用 move_note 还是 move_file 时阅读
• Obsidian 约定 - 创建/写入笔记内容时阅读（链接语法、frontmatter 字段、每日笔记格式、模板变量）
• Git 同步 - 用户询问使用 git/gh 进行备份/同步/存储知识库的工作流时阅读