知识库大师

知识库大师

把 Obsidian vault 当作一个长期演进的知识系统来管，而非散乱文件夹。基于 obsidian-cli 完成多库管理、安全重构、附件治理与跨库搜索。

Vault 模型

Obsidian vault = 普通磁盘文件夹。典型结构：

多库发现与切换

Obsidian 桌面端在以下位置记录所有 vault（真相源）：

• macOS: ~/Library/Application Support/obsidian/obsidian.json
• Windows: %APPDATA%/obsidian/obsidian.json
• Linux: ~/.config/obsidian/obsidian.json

obsidian-cli 从该文件解析，vault 名通常是文件夹名（路径后缀）。

多库发现（不要猜，读配置）：

# 已设默认库
obsidian-cli print-default --path-only

# 未设默认 → 读 obsidian.json，取 "open": true 的条目
# 多库常见：iCloud vs ~/Documents、工作 vs 个人

切换默认库：

obsidian-cli set-default ""
obsidian-cli print-default            # 确认当前默认

禁止把库路径硬编码进脚本；优先读配置或用 print-default。

快速开始

# 1. 发现库
obsidian-cli print-default --path-only

# 2. 切到目标库（如需要）
obsidian-cli set-default "my-knowledge"

# 3. 搜索
obsidian-cli search "项目管理"
obsidian-cli search-content "OKR"

# 4. 创建
obsidian-cli create "Projects/新项目" --content "# 新项目" --open

# 5. 安全移动（自动更新双链）
obsidian-cli move "old/path/note" "new/path/note"

# 6. 删除
obsidian-cli delete "path/note"

简单编辑可直接改 .md 文件，Obsidian 会自动同步。

安全重构（移动/改名不断链）

obsidian-cli move 是相对 mv 的核心优势：自动更新 vault 内所有 [[wikilinks]] 与 Markdown 链接。

重构前安全检查清单

• 已备份 vault（或用 Git）
• 当前无其他编辑器打开目标笔记（避免冲突）
• 记录原路径与新路径（便于回滚）
• 全文搜索确认无硬编码路径引用

批量重构模板

# 把 Notes/ 下所有笔记移到 Inbox/，自动更新链接
for note in Notes/*.md; do
  name=$(basename "$note" .md)
  obsidian-cli move "Notes/$name" "Inbox/$name"
done

# 批量改名：旧名 → 新名（从 CSV）
# rename.csv: old_name,new_name
tail -n +2 rename.csv | while IFS=, read -r old new; do
  obsidian-cli move "$old" "$new"
done

附件治理

附件散落是长期使用 vault 的头号痛点。提供三步治理：

1. 扫描游离附件

# 列出未被任何笔记引用的附件
scripts/orphan-scan --vault "" --attachments "Attachments"
# 输出：orphan-attachments.csv，含文件路径、大小、最后修改时间

2. 按规则归位

# 把图片归到 Attachments/Images/，PDF 归到 Attachments/PDF/
scripts/organize-attachments --vault "" \
  --rule "image:Attachments/Images" \
  --rule "pdf:Attachments/PDF" \
  --rule "audio:Attachments/Audio"

3. 清理孤儿

# 删除连续 90 天未被引用的附件（先 dry-run）
scripts/clean-orphans --vault "" --days 90 --dry-run
scripts/clean-orphans --vault "" --days 90   # 实删

跨库搜索

跨库搜索示例：

scripts/cross-vault-search "OKR" --vaults work,personal
# 输出：每个 vault 的命中笔记 + 片段

创建笔记

obsidian-cli create "Folder/New note" --content "..." --open

注意：

• 依赖 Obsidian URI handler（obsidian://...），需 Obsidian 已安装
• 避免在隐藏 dot-folder 下创建（如 .something/...），Obsidian 可能拒绝
• 复杂内容建议先写文件再用 --content-file（若 CLI 支持）或直接写 .md

真实场景示例

场景1：季度知识库整理

用户：把上季度的项目笔记归档到 Archive/
执行：
1. 全文搜索"Q3 项目"
2. 批量 move 命中笔记到 Archive/2025-Q3/
3. 附件治理：扫描游离附件 → 归位 → 清理 90 天孤儿
4. 报告：归档 23 篇，整理附件 47 个，清理孤儿 8 个

场景2：重命名核心概念

用户：把所有"双钻模型"改成"Double Diamond"
执行：
1. search-content "双钻模型" → 列出所有命中笔记
2. 逐个 move（如有以概念命名的笔记）+ 全文替换
3. 验证双链未断：search "双钻模型" 应返回 0
4. 报告：改名 12 篇，更新链接 34 处

场景3：工作/个人库切换

用户：从个人库切到工作库
执行：
1. set-default "work-vault"
2. print-default 确认
3. search "本周会议"

场景4：附件大扫除

用户：vault 越来越大，清理无用附件
执行：
1. orphan-scan → 发现 156 个游离附件（占 1.2GB）
2. organize-attachments 按类型归位
3. clean-orphans --days 90 --dry-run → 预览删除 89 个
4. 用户确认后 clean-orphans --days 90
5. 报告：释放 780MB，保留 67 个近期附件

FAQ

Q1: 移动笔记后双链断了怎么办？ A: obsidian-cli move 应自动更新。若仍断：检查是否有"硬编码路径"引用（如 [[folder/note]] 全路径）；用 search-content 找残留引用并手动修复。

Q2: 多库切换会丢配置吗？ A: 不会。每个 vault 的 .obsidian/ 独立，切换只改默认指向。插件、主题、工作区都保留。

Q3: 附件扫描误报怎么办？ A: orphan-scan 可能漏判被 ![[image]] 嵌入的附件。先 --dry-run 预览，对可疑项手动确认。可在脚本中加白名单。

Q4: 跨库搜索慢吗？ A: 取决于库大小。万级笔记约 5-10 秒。建议加 --limit 限制每库返回数。

Q5: 可以在 Obsidian 未运行时操作吗？ A: move/delete/search 直接操作磁盘，不需要 Obsidian 运行。create --open 需要 URI handler，需 Obsidian 运行。建议操作时关闭 Obsidian 避免冲突，操作完再打开。

故障排查

依赖说明

运行环境

• Agent 平台: 任意支持 SKILL.md 的 AI Agent
• 操作系统: Windows / macOS / Linux
• Obsidian: 桌面版（用于 URI handler 与配置文件）

第三方依赖

API Key 配置

• 无需 API Key
• 自定义脚本（orphan-scan、cross-vault-search）需要文件系统读写权限

可用性分类

• 分类: MD+EXEC（Markdown 指令 + 必须通过 exec 执行 obsidian-cli 与自定义脚本）
• 说明: 基于自然语言指令驱动 Agent 管理知识库，含多库切换、安全重构、附件治理