obsidian-vault-manager

Obsidian Vault Manager

前置条件

执行知识库操作前：

1. 确认已安装 obsidian CLI：

   obsidian --version
   

   CLI 是随 Obsidian 桌面应用附带的原生 obsidian 二进制文件，并非独立的 npm 包。

2. 列出可用知识库：

   obsidian vaults
   

3. 获取知识库路径：

   obsidian vault "<name>" info=path
   

概览

涉及链接或结构的知识库操作请使用 obsidian。 对于由 iCloud 同步的知识库（路径中包含 Mobile Documents——使用 obsidian vault "<name>" info=path 检查），Write 工具并不可靠：iCloud 路径受 TCC 保护，因此即使禁用了沙箱，直接写入文件系统也可能被阻止；只有通过 CLI 使用 Obsidian 应用才能确保写入成功。若要创建内容较多的笔记（多行内容、frontmatter、代码块），请使用此技能中的 scripts/write-markdown-to-vault.js：它会将较大的载荷拆分为低于 CLI 约 10KB IPC 上限的区块、过滤横幅噪声、重试暂时性错误，并通过回读笔记验证写入结果。请在无沙箱环境中运行（CLI 在命令沙箱下会挂起）。对于位于普通文件系统路径（非 iCloud）上的知识库，Write 工具可直接使用，更适合创建单次笔记。

快速参考

任务	命令	备注
列出知识库	obsidian vaults	始终先运行
知识库信息	obsidian vault "<name>"	名称、路径、文件数
知识库路径	obsidian vault "<name>" info=path	仅返回路径，适合脚本使用
列出文件夹	obsidian "vault=<name>" folders	知识库名称包含空格时请加引号
读取笔记	obsidian "vault=<name>" read "<note name>"	按名称读取（模糊匹配）
创建笔记（大型／iCloud）	node scripts/write-markdown-to-vault.js --vault <name> --path <path> --input <file>	分块、重试并验证——请在无沙箱环境中运行
创建笔记（小型、非 iCloud）	obsidian "vault=<name>" create path="folder/name.md" content="$CONTENT"	多行内容请使用 printf 构建 $CONTENT
覆盖笔记	obsidian "vault=<name>" create path="..." content="$CONTENT" overwrite
追加到笔记	obsidian "vault=<name>" append path="<path>" content="<text>"
移动笔记	obsidian "vault=<name>" move path="old.md" newpath="new.md"	自动更新所有链接
搜索内容	obsidian "vault=<name>" search query="<term>" [path=<folder>] [format=json]
每日笔记	obsidian "vault=<name>" daily	创建／打开今天的笔记
当前／默认知识库	obsidian vault	不指定名称 → 当前打开的知识库
追加到每日笔记	obsidian "vault=<name>" daily:append content="<text>"	当前知识库；需要 Daily Notes 插件

另请参阅：

• 完整的 obsidian 命令参考 - 所有命令及其标志和高级用法
• Obsidian 语法参考 - Wiki 链接、标签、frontmatter 和 Markdown 语法
• 笔记模板 - 每日笔记、项目和会议模板

核心工作流

第 1 步 — 查找知识库

# List vaults to confirm the name
obsidian vaults

# Get full info (name, path, file count)
obsidian vault "<name>"

# Get just the path (useful for scripting)
VAULT_PATH=$(obsidian vault "<name>" info=path)

第 2 步 — 探索结构

# List folders
obsidian "vault=<name>" folders

# Search for existing notes
obsidian "vault=<name>" search query="<topic>" path=<folder> format=json

第 3 步 — 创建包含丰富内容的笔记

使用 printf 构建内容变量——这样可以正确处理换行和包含 frontmatter 的多行内容：

CONTENT=$(printf '---\ntags:\n  - til\nindex: "[[Today I learned]]"\n---\n## Heading\n\nContent here.')
obsidian "vault=<name>" create path="til/2026-04-27 My Note.md" content="$CONTENT"

先查看现有笔记，以匹配本地格式约定（标签名称、frontmatter 字段、index 反向链接等）：

obsidian "vault=<name>" read "<existing note name>"

移动／重新整理笔记

# ✅ CORRECT: Auto-updates all links
obsidian "vault=<name>" move path="Random Notes/Design.md" newpath="Projects/Design.md"

# ❌ WRONG: Breaks all links to this note
mv "vault/Random Notes/Design.md" "vault/Projects/Design.md"

常见错误

错误	错误原因	修正方法
使用 obsidian-cli	那是另一个 npm 包——此工具是 obsidian	使用 obsidian
使用 --flags 语法	此 CLI 使用 key=value 位置参数，而不是 --flags	使用 key=value 格式
在双引号字符串中使用带有 \n 的 create	转义字符会被去掉，导致内容被截断	使用 printf 构建 $CONTENT 变量
在 iCloud 库路径上使用 Write	即使禁用了沙盒，TCC 也可能静默阻止写入	改用 scripts/write-markdown-to-vault.js
单次 create/append 调用的内容超过约 10KB	会出现静默的管道断开错误（退出码为 0，但未写入任何内容）或 NativeImage 错误	使用 scripts/write-markdown-to-vault.js——它会自动分块
使用 mv 移动笔记	会破坏所有指向该笔记的 [[wiki-links]]	使用 obsidian move
未检查现有笔记格式	每个库的标签和 frontmatter 约定都不同	先读取一篇现有笔记
在 wiki 链接中使用绝对路径	库移动后链接会失效	使用相对于库的路径

何时使用标准工具

• 批量编辑内容：使用 obsidian read 读取后，再使用 Edit
• 复杂搜索模式：直接在库路径上使用 Grep（使用 obsidian vault "<name>" info=path 获取路径）

始终保留：

• Frontmatter（--- 之间的 YAML）
• Obsidian 链接语法 [[Note]]
• 标签语法 #tag-name
• Markdown 结构

成功标准

满足以下条件时，库操作才算成功：

• 移动后，所有 [[wiki-links]] 仍然有效
• 笔记创建在正确的库位置，且内容完整无损
• 格式与同一文件夹中的现有笔记一致
• 没有失效链接或孤立笔记