obsidian

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Obsidian Skill

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:
```
这样的通用字符串会匹配前置元数据字段。请包含足够的上下文以定位到正确的匹配项。
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
```
模式下，如果笔记不存在则会创建该笔记。在追加/前置模式下，前置元数据会合并（新键覆盖旧键）；在覆盖模式下则会完全替换。
delete_note需要精确路径确认。
```
confirmPath
```
必须与
```
path
```
完全一致。不进行路径标准化，也不允许尾部斜杠差异。不匹配时会静默失败，返回
```
success: false
```
。
move_file需要双重确认。
```
confirmOldPath
```
和
```
confirmNewPath
```
都必须与对应路径完全匹配。对于Markdown文件重命名，请使用
```
move_note
```
（文本感知，无需确认）；仅在处理二进制文件或需要二进制安全移动时使用
```
move_file
```
。
manage_tags从两个源读取但仅写入一个源。
```
list
```
操作会合并前置元数据标签 + 内联
```
#hashtags
```
。
```
add
```
/
```
remove
```
操作仅修改前置元数据的
```
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 "找到N个匹配项"	为 `oldString` 添加上下文行以使其唯一，或设置 `replaceAll: true`
delete_note / move_file 确认不匹配	使用 `read_note` 或 `list_directory` 重新读取笔记路径，然后使用精确字符串重试
search_notes 返回0条结果	尝试使用单个关键词而非短语，切换 `searchFrontmatter` 选项，或使用部分关键词扩大范围
read_multiple_notes 部分 `err`	使用 `list_directory` 验证失败的路径，修正拼写错误或缺失的扩展名，仅重试失败的路径

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)

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

工具模式 - 当你需要了解工具的响应格式、模式细节，或需要决定使用move_note还是move_file时阅读
Obsidian 约定 - 当你创建/编写笔记内容时阅读（链接语法、前置元数据字段、每日笔记格式、模板变量）