用途
Obsidian Vault Manager 用于在 Obsidian 笔记库中执行涉及链接或结构的操作，例如创建每日笔记、移动笔记而不破坏链接、搜索笔记库内容等。它通过 Obsidian 桌面应用自带的 obsidian 命令行工具（CLI）来操作笔记库。
前置条件
在执行笔记库操作前，需要：
- 验证 obsidian CLI 已安装：运行
obsidian --version。该 CLI 是 Obsidian 桌面应用自带的原生 obsidian 二进制文件，不是单独的 npm 包。 - 列出可用笔记库：
obsidian vaults - 获取笔记库路径：
obsidian vault "<name>" info=path
主要能力
该技能提供以下操作能力：
- 列出笔记库：
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=<name>" daily:append content="<text>"，需要 Daily Notes 插件 - 查看当前活动或默认笔记库：
obsidian vault（不带名称时返回当前打开的笔记库）
使用方式
查找笔记库
先列出笔记库确认名称，再获取完整信息或仅路径。获取路径可用于脚本：VAULT_PATH=$(obsidian vault "<name>" info=path)。
探索结构
列出文件夹，或搜索现有笔记：obsidian "vault=<name>" search query="<topic>" path=<folder> format=json。
创建富内容笔记
使用 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 字段、索引反向链接等）：obsidian "vault=<name>" read "<existing note name>"。
移动或重组笔记
正确做法（自动更新所有链接）：obsidian "vault=<name>" move path="Random Notes/Design.md" newpath="Projects/Design.md"。
错误做法（会破坏所有指向该笔记的链接）：mv "vault/Random Notes/Design.md" "vault/Projects/Design.md"。
iCloud 同步笔记库
对于 iCloud 同步的笔记库（路径包含 Mobile Documents，可用 obsidian vault "<name>" info=path 检查），Write 工具不可靠：iCloud 路径受 TCC 保护，即使禁用沙箱，直接文件系统写入也可能被阻止，只有 Obsidian 应用（通过 CLI）能保证写入成功。创建包含大量内容（多行、frontmatter、代码块）的笔记时，使用本技能中的 scripts/write-markdown-to-vault.js，它会将大负载分块以低于 CLI 约 10KB 的 IPC 上限、过滤 banner 噪声、重试瞬时错误，并通过读回笔记来校验写入。需在非沙箱环境下运行（CLI 在命令沙箱下会挂起）。对于普通文件系统路径（非 iCloud）的笔记库，Write 工具可直接使用，对一次性笔记更简单。
何时使用标准工具
- 批量内容编辑：先用
obsidian read读取，再用 Edit。 - 复杂搜索模式：直接在笔记库路径上使用 Grep（用
obsidian vault "<name>" info=path获取路径）。
始终保留：frontmatter（--- 之间的 YAML）、Obsidian 链接语法 [[Note]]、标签语法 #tag-name、Markdown 结构。
常见错误
- 使用 obsidian-cli：那是另一个 npm 包，本工具是 obsidian。应使用 obsidian。
- 使用 --flags 语法：CLI 使用 key=value 位置参数，不是 --flags。应使用 key=value 格式。
- 在双引号字符串中使用 \n 创建：转义会被剥离，内容被截断。应使用 printf 构建 $CONTENT 变量。
- 在 iCloud 笔记库路径上使用 Write：TCC 可能静默阻止写入，即使禁用沙箱。应改用 scripts/write-markdown-to-vault.js。
- 单次 create/append 调用内容超过约 10KB：可能静默 broken pipe（退出码 0，未写入任何内容）或 NativeImage 错误。应使用 scripts/write-markdown-to-vault.js，它会自动分块。
- 使用 mv 移动笔记：会破坏所有指向该笔记的 [[wiki-links]]。应使用 obsidian move。
- 未检查现有笔记格式：每个笔记库有不同的标签/frontmatter 约定。应先读取一篇现有笔记。
- 在 wiki 链接中使用绝对路径：笔记库移动时会失效。应使用笔记库相对路径。
适用场景
适用于需要管理 Obsidian 笔记库的任务，包括创建每日笔记、移动笔记并保持链接有效、搜索笔记库内容、创建富内容笔记等。
限制
- 依赖 Obsidian 桌面应用自带的 obsidian CLI，需先安装并验证。
- iCloud 同步笔记库的写入受 TCC 保护，直接文件系统写入可能被阻止，需使用专用脚本。
- CLI 单次 create/append 调用内容上限约 10KB，超出需分块。
- 追加到每日笔记需要 Daily Notes 插件。
- 脚本需在非沙箱环境下运行，否则 CLI 会挂起。
成功标准
笔记库操作成功需满足：移动后所有 [[wiki-links]] 仍然有效；笔记创建在正确的笔记库位置且内容完整；格式与同一文件夹中的现有笔记匹配；没有损坏的链接或孤立笔记。