笔记 CLI 工具箱

把 Obsidian vault 当作可被脚本批处理的笔记数据库。基于 notesmd-cli 完成无头创建、frontmatter 治理、daily note 模板化与编辑器集成。

Vault 模型

Obsidian vault = 普通磁盘文件夹。

notesmd-cli 直接操作磁盘，Obsidian 不需要运行，适合无头服务器与 CI。

多库发现

Obsidian 桌面端记录 vault 列表于：

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

notesmd-cli 从该文件解析；vault 名通常是文件夹名。

# 已设默认
notesmd-cli print-default --path-only

# 未设默认 → 读 obsidian.json，取 "open": true 条目

多库常见（iCloud vs ~/Documents、工作 vs 个人），不要猜，读配置。

快速开始

# 1. 设默认库 + 打开方式
notesmd-cli set-default "<vault-folder-name>"
notesmd-cli set-default --open-type editor   # 用 $EDITOR 而非 Obsidian

# 2. 搜索
notesmd-cli search                           # 交互式模糊搜索
notesmd-cli search-content "query"           # 全文搜索

# 3. 创建
notesmd-cli create "Folder/New note" --content "..."

# 4. Daily note
notesmd-cli daily                             # 创建/打开今日 daily

# 5. frontmatter
notesmd-cli frontmatter "NoteName" --print
notesmd-cli frontmatter "NoteName" --edit --key "status" --value "done"

# 6. 移动/删除
notesmd-cli move "old/path/note" "new/path/note"
notesmd-cli delete "path/note"

无头模式与 CI 集成

notesmd-cli 直接操作磁盘，Obsidian 不需要运行。适合服务器与 CI/CD。

CI 集成示例：自动生成 daily note

# .github/workflows/daily-note.yml
name: Daily Note
on:
  schedule:
    - cron: "0 6 * * *"   # 每日 6 点
jobs:
  daily:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g notesmd-cli
      - run: |
          notesmd-cli set-default "vault" --open-type editor
          notesmd-cli daily
      - run: |
          git add .
          git commit -m "chore: daily note $(date +%F)" || echo "no changes"
          git push

服务器批量归档

# 在 NAS/服务器上跑，无 GUI
notesmd-cli set-default "my-vault" --open-type editor
# 把 30 天前的 daily 归档
scripts/archive-daily --days 30 --to "Archive/Daily/"

frontmatter 治理

把 frontmatter 当数据库字段操作。

单条操作

# 打印
notesmd-cli frontmatter "NoteName" --print

# 编辑（添加/修改）
notesmd-cli frontmatter "NoteName" --edit --key "status" --value "done"
notesmd-cli frontmatter "NoteName" --edit --key "tags" --value "project,urgent"

# 删除
notesmd-cli frontmatter "NoteName" --delete --key "draft"

批量模板

# 批量打标签（从 CSV：note_path,tag）
tail -n +2 tags.csv | while IFS=, read -r note tag; do
  notesmd-cli frontmatter "$note" --edit --key "tags" --value "$tag"
done

# 批量改状态：draft → published
for note in $(notesmd-cli search-content "status: draft" --paths-only); do
  notesmd-cli frontmatter "$note" --edit --key "status" --value "published"
done

# 按状态过滤并导出清单
scripts/frontmatter-query --filter "status=published" --output published.md

daily note 模板化

notesmd-cli daily 自动读 .obsidian/daily-notes.json，按配置的文件夹、格式、模板生成。

配置示例（.obsidian/daily-notes.json）

{
  "folder": "Daily",
  "format": "YYYY-MM-DD",
  "template": "Templates/Daily Template"
}

模板文件示例（Templates/Daily Template.md）

---
date: {{date}}
status: active
tags: [daily]
---

# {{date}}

## 今日任务
- [ ] 

## 笔记
- 

## 回顾
- 

批量补建缺失的 daily

# 补建过去 7 天缺失的 daily
scripts/backfill-daily --days 7
# 检查 Daily/ 目录，缺失的按模板生成

编辑器集成决策表

设默认打开方式：notesmd-cli set-default --open-type editor。

真实场景示例

场景1：CI 自动生成 daily 并推送

触发：GitHub Actions 每日 6 点
执行：
1. notesmd-cli set-default "vault" --open-type editor
2. notesmd-cli daily（按模板生成）
3. git add . && git commit && git push
4. 其他设备 pull 即可看到今日 daily

场景2：批量把草稿改发布

用户：把所有 status: draft 的笔记改成 status: published
执行：
1. search-content "status: draft" --paths-only → 列出 12 篇
2. 逐个 frontmatter --edit --key status --value published
3. 报告：更新 12 篇

场景3：服务器批量归档旧 daily

用户：把 30 天前的 daily 移到 Archive/
执行：
1. scripts/archive-daily --days 30 --to "Archive/Daily/"
2. move 每个旧 daily（自动更新链接）
3. 报告：归档 30 篇

场景4：按 frontmatter 查询

用户：列出所有 tags 含 "project" 且 status=active 的笔记
执行：
1. scripts/frontmatter-query --filter "tags~project,status=active"
2. 输出：8 篇匹配，含路径与摘要

场景5：无 GUI 服务器编辑

用户：SSH 到服务器改笔记
执行：
1. notesmd-cli set-default "vault" --open-type editor
2. notesmd-cli open "Projects/X" --editor
3. $EDITOR（vim/nano）打开，改完保存
4. Obsidian 桌面端 pull 即可同步

FAQ

Q1: 无头模式真的不需要 Obsidian 运行吗？ A: 是的。notesmd-cli 直接读写 .md 文件，读取 .obsidian/*.json 配置。Obsidian 桌面端运行时检测到文件变化会自动刷新。

Q2: frontmatter 编辑会破坏 YAML 格式吗？ A: 不会。notesmd-cli 解析 YAML 后修改再写回，保留缩进与注释。但建议编辑前备份，避免极端格式问题。

Q3: daily note 模板支持变量吗？ A: 支持。{{date}}、{{time}}、{{title}} 等标准变量。自定义变量需在模板中用 frontmatter 或脚本预处理。

Q4: --editor 用哪个编辑器？ A: 读 $EDITOR 环境变量。设为 vim、nano、code（VS Code）等均可。Windows 可设为 code --wait。

Q5: 批量操作前怎么预览？ A: 所有批量脚本支持 --dry-run，先打印将执行的命令列表，确认后再去掉 flag 实跑。

故障排查

依赖说明

运行环境

• Agent 平台: 任意支持 SKILL.md 的 AI Agent
• 操作系统: Windows / macOS / Linux（无头模式适合服务器）
• Obsidian: 桌面版（可选，无头模式不需要运行）
• 编辑器: $EDITOR 环境变量指向的编辑器（vim/nano/code 等）

第三方依赖

API Key 配置

• 无需 API Key
• CI 集成需要 Git 仓库的 Personal Access Token（用于 push）

可用性分类

• 分类: MD+EXEC（Markdown 指令 + 必须通过 exec 执行 notesmd-cli 与批量脚本）
• 说明: 基于自然语言指令驱动 Agent 批处理笔记，含无头模式、frontmatter 治理、daily 模板化