obsidian

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Obsidian Skill

Obsidian技能

Routing Policy

路由策略

Use the backend that best matches user intent:

MCP (default for vault data operations)
- Read/write/patch/move/search notes
- Frontmatter and tag updates
- Metadata and batch note operations
Obsidian CLI/App context (only when app context is needed)
- Open a note in Obsidian from URI
- Trigger app/plugin workflows that MCP cannot perform
CLI git (sync/backup workflows)
- Initialize repo, configure remote, commit, pull, push
- Periodic or manual vault backup/sync requests

When a request is ambiguous, pick MCP first unless the user explicitly asks for sync/backup/git/app behavior.

使用最符合用户意图的后端：

MCP（知识库数据操作的默认选择）
- 读取/写入/修改/移动/搜索笔记
- Frontmatter和标签更新
- 元数据和批量笔记操作
Obsidian CLI/应用上下文（仅当需要应用上下文时使用）
- 通过URI在Obsidian中打开笔记
- 触发MCP无法执行的应用/插件工作流
CLI git（同步/备份工作流）
- 初始化仓库、配置远程地址、提交、拉取、推送
- 定期或手动的知识库备份/同步请求

当请求含义模糊时，优先选择MCP，除非用户明确要求同步/备份/git/应用相关行为。

Gotchas

注意事项

patch_note rejects multi-match by default. With
```
replaceAll: false
```
, if
```
oldString
```
appears more than once the call fails and returns
```
matchCount
```
. Set
```
replaceAll: true
```
only when you mean it, or add surrounding context to make the match unique.
patch_note matches inside frontmatter. The replacement runs against the full file including the YAML block. A generic string like
```
title:
```
will match frontmatter fields. Include enough context to target the right occurrence.
patch_note forbids empty strings. Both
```
oldString
```
and
```
newString
```
must be non-empty and non-whitespace. To delete text, use
```
newString
```
with a single space or restructure the note with
```
write_note
```
.
search_notes returns minified JSON. Fields are abbreviated:
```
p
```
(path),
```
t
```
(title),
```
ex
```
(excerpt),
```
mc
```
(matchCount),
```
ln
```
(lineNumber),
```
uri
```
(obsidianUri). Hard cap of 20 results regardless of
```
limit
```
.
search_notes multi-word queries score terms individually AND as a phrase. Each term is OR-matched, so a document matching any term appears in results. The full phrase gets an additional scoring boost.
write_note auto-creates directories. Parent folders are created recursively. In
```
append
```
/
```
prepend
```
mode, if the note doesn't exist it's created. Frontmatter is merged (new keys override) in append/prepend; replaced entirely in overwrite.
delete_note requires exact path confirmation.
```
confirmPath
```
must be character-identical to
```
path
```
. No normalization, no trailing-slash tolerance. Mismatch silently fails with
```
success: false
```
.
move_file needs double confirmation. Both
```
confirmOldPath
```
and
```
confirmNewPath
```
must exactly match their counterparts. Use
```
move_note
```
for markdown renames (text-aware, no confirmation needed); use
```
move_file
```
only for binary files or when you need binary-safe moves.
manage_tags reads from two sources but writes to one.
```
list
```
merges frontmatter tags + inline
```
#hashtags
```
.
```
add
```
/
```
remove
```
only modify the frontmatter
```
tags
```
array. Inline tags are never touched.
read_multiple_notes never rejects. Uses
```
allSettled
```
internally. Failed files appear in the
```
err
```
array; successful ones in
```
ok
```
. Always check both. Hard limit of 10 paths per call.

patch_note默认拒绝多匹配。当
```
replaceAll: false
```
时，如果
```
oldString
```
出现多次，调用会失败并返回
```
matchCount
```
。仅当你确实需要时才设置
```
replaceAll: true
```
，或者添加上下文让匹配唯一。
patch_note会匹配frontmatter内部内容。替换会对包含YAML块的完整文件生效，类似
```
title:
```
的通用字符串会匹配frontmatter字段，请包含足够的上下文来定位到正确的匹配项。
patch_note禁止空字符串。
```
oldString
```
和
```
newString
```
都必须是非空且非全空格的。要删除文本，请将
```
newString
```
设为单个空格，或者使用
```
write_note
```
重构笔记。
search_notes返回压缩后的JSON。字段会被缩写：
```
p
```
（路径）、
```
t
```
（标题）、
```
ex
```
（摘要）、
```
mc
```
（匹配次数）、
```
ln
```
（行号）、
```
uri
```
（obsidianUri）。无论
```
limit
```
设置为多少，最多返回20条结果。
search_notes多词查询会分别对单个词和短语打分。每个词是OR匹配，所以匹配任意词的文档都会出现在结果中，完整短语会获得额外的分数加成。
write_note会自动创建目录。会递归创建父文件夹。在
```
append
```
/
```
prepend
```
模式下，如果笔记不存在会自动创建。追加/前置模式下frontmatter会合并（新键覆盖旧键）；覆盖模式下会完全替换frontmatter。
delete_note需要精确的路径确认。
```
confirmPath
```
必须和
```
path
```
字符完全一致。没有标准化处理，也不兼容末尾斜杠。不匹配时会静默失败，返回
```
success: false
```
。
move_file需要双重确认。
```
confirmOldPath
```
和
```
confirmNewPath
```
都必须和对应的路径完全匹配。markdown文件重命名使用
```
move_note
```
（文本感知，无需确认）；仅当处理二进制文件或需要二进制安全移动时使用
```
move_file
```
。
manage_tags从两个源读取但只写入一个源。
```
list
```
操作会合并frontmatter标签和行内
```
#hashtags
```
。
```
add
```
/
```
remove
```
操作仅修改frontmatter的
```
tags
```
数组，永远不会修改行内标签。
read_multiple_notes永远不会抛出错误。内部使用
```
allSettled
```
处理，失败的文件会出现在
```
err
```
数组中，成功的在
```
ok
```
数组中。请始终检查两个数组，每次调用最多支持10个路径。

Error Recovery

错误恢复

Error	Next step
patch_note "Found N occurrences"	Add surrounding lines to `oldString` to make it unique, or set `replaceAll: true`
delete_note / move_file confirmation mismatch	Re-read the note path with `read_note` or `list_directory` , then retry with the exact string
search_notes returns 0 results	Try single keywords instead of phrases, toggle `searchFrontmatter` , or broaden with partial terms
read_multiple_notes partial `err`	Verify failed paths with `list_directory` , fix typos or missing extensions, retry only failed ones

错误	下一步操作
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 Sync Mode

Git同步模式

When the user asks to "sync", "backup", or "store my vault with git", use CLI git with this behavior:

Run a preflight before changing anything:
- ```
git
```
  available
- current directory is a git repo (or prompt to initialize)
- ```
git config user.name
```
  and
```
git config user.email
```
  are set
- at least one remote exists for push/pull sync
If preflight is incomplete, ask exactly one targeted question with a recommended default.
- Use askuserquestion for decisions that materially change behavior.
- Good examples:
  - "No git repo found. Initialize one in this vault now? (Recommended: Yes)"
  - "No remote configured. Set up GitHub remote now via gh if available, or provide remote URL? (Recommended: Set up via gh)"
  - "Local and remote diverged. Try
```
git pull --rebase
```
    now? (Recommended: Yes)"

Safe sync sequence (never force push by default):

```
git add -A
```

git commit -m "vault sync: YYYY-MM-DD HH:mm"

(skip commit if no changes)

```
git pull --rebase
```
```
git push
```

```
gh
```
is optional:
- Use
```
gh
```
  only for remote bootstrapping (create repo / set origin) when requested.
- Do not require
```
gh
```
  for normal sync once remote is configured.
Stop on conflicts and report clear next steps.
- Do not auto-resolve merge conflicts silently.
- Explain what failed and what user should run next.

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

做任何修改前先运行预检：
- ```
git
```
  可用
- 当前目录是git仓库（否则提示初始化）
- 已设置
```
git config user.name
```
  和
```
git config user.email
```
- 至少有一个可用于推拉同步的远程仓库
如果预检未完成，仅询问一个针对性的问题并给出推荐默认值。
- 对于会实质性改变行为的决策使用askuserquestion。
- 正面示例：
  - "未找到git仓库，是否现在在该知识库中初始化一个？（推荐：是）"
  - "未配置远程仓库，是否现在通过可用的gh设置GitHub远程仓库，或者提供远程URL？（推荐：通过gh设置）"
  - "本地和远程分支分叉，是否现在尝试
```
git pull --rebase
```
    ？（推荐：是）"
安全同步序列（默认永远不会强制推送）：
- ```
git add -A
```
- ```
git commit -m "vault sync: YYYY-MM-DD HH:mm"
```
  （如果没有变更则跳过提交）
- ```
git pull --rebase
```
- ```
git push
```
```
gh
```
是可选的：
- 仅当用户要求时使用
```
gh
```
  进行远程仓库初始化（创建仓库/设置origin）。
- 远程仓库配置完成后，正常同步不需要
```
gh
```
  。
遇到冲突时停止并报告清晰的下一步操作。
- 不要静默自动解决合并冲突。
- 说明失败原因和用户接下来应该执行的操作。

Resources

资源

Load these only when needed, not on every invocation.

Tool Patterns - read when you need a tool's response shape, mode details, or the move_note vs move_file decision
Obsidian Conventions - read when creating/writing note content (link syntax, frontmatter fields, daily note format, template variables)
Git Sync - read when user asks for backup/sync/store-vault workflows with git/gh

仅在需要时加载这些资源，不要每次调用都加载：

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