pp-obsidian

Obsidian — Printing Press CLI

前置条件：安装 CLI

此技能由 obsidian-pp-cli 二进制文件驱动。**调用此技能中的任何命令前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 通过 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install obsidian --cli-only
   

2. 验证：obsidian-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用直接通过 Go 安装的方式（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/productivity/obsidian/cmd/obsidian-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件目录。在验证成功之前，请勿执行此技能的命令。

何时不使用此 CLI

对于需要创建、更新、删除、发布、评论、点赞、邀请、下单、发送消息、预订、购买或更改远程状态的请求，请勿启用此 CLI。此只读 CLI 提供用于检查、导出、同步和分析的命令。

HTTP 传输

此 CLI 使用兼容 Chrome 的 HTTP 传输来访问面向浏览器的端点。常规 API 调用不需要常驻的浏览器进程。

命令参考

deadends — 管理死路笔记

• obsidian-pp-cli deadends — 列出没有出链的笔记

files — 管理文件

• obsidian-pp-cli files — 封装 obsidian files。可按文件夹或扩展名筛选。

folders — 管理文件夹

• obsidian-pp-cli folders — 封装 obsidian folders。

live-search — 管理实时搜索

• obsidian-pp-cli live-search context — 封装 obsidian search:context query=<text> — 搜索正文，并为每个匹配项返回周边行。
• obsidian-pp-cli live-search live-search — 封装 obsidian search query=<text> — 通过运行中的 Obsidian 进程搜索正文。与……不同

notes — 单条笔记的读取操作

• obsidian-pp-cli notes <name> — 封装 obsidian read file={name}（或用于精确路径的 path=）。返回原始文件内容。

tags — 管理标签

• obsidian-pp-cli tags — 封装 obsidian tags。可通过 path= 查询限定到某个文件。

tasks — 管理任务

• obsidian-pp-cli tasks — 封装 obsidian tasks。可按已完成/待办/状态筛选。（任务修改功能属于 V2。）

unresolved — 管理未解析项

• obsidian-pp-cli unresolved — 封装 obsidian unresolved。Tier-3 broken 基于此命令提供源笔记上下文。

vault — 库级清单和元数据

• obsidian-pp-cli vault — 封装 obsidian vault。info= 可将结果限定为单个字段。

查找合适的命令

知道要做什么，但不清楚该用哪个命令时，可以直接询问 CLI：

obsidian-pp-cli which "<capability in your own words>"

which 会根据自然语言功能查询，从此 CLI 精选的功能索引中匹配最合适的命令。退出码 0 表示至少有一个匹配项；退出码 2 表示没有可信的匹配项——此时请改用 --help 或尝试更具体的查询。

身份验证设置

无需身份验证。

运行 obsidian-pp-cli doctor 以验证设置。

Agent 模式

在任何命令后添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 可管道传输 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留部分字段。点分路径可深入嵌套结构；数组会逐元素遍历。对于输出冗长的 API，这对缩小上下文至关重要：

  obsidian-pp-cli deadends --agent --select id,name,status
  

• 可预览 — --dry-run 显示请求，但不会发送

• 适合离线使用 — 有本地 SQLite 存储时，同步/搜索命令可使用该存储

• 非交互式 — 从不提示，每项输入都通过标志提供

• 只读 — 请勿将此 CLI 用于创建、更新、删除、发布、评论、点赞、邀请、下单、发送或其他会修改数据的请求

响应信封

从本地存储或 API 读取数据的命令会将输出封装在溯源信封中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并查看 .meta.source 以了解数据来自实时源还是本地。仅当 stdout 是终端且未设置机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会将人类可读的 N results (live) 摘要打印到 stderr；管道/Agent 使用者和显式指定格式的运行会在 stdout 输出纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有不妥之处时，请记录下来：

obsidian-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
obsidian-pp-cli feedback --stdin < notes.txt
obsidian-pp-cli feedback list --json --limit 10

条目保存在本地的 ~/.obsidian-pp-cli/feedback.jsonl 中。除非设置了 OBSIDIAN_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 OBSIDIAN_FEEDBACK_AUTO_SEND=true，否则绝不会发送 POST 请求。默认行为仅在本地保存。

写下让你感到意外的内容，而不是 bug 报告。简短、具体，写成一行：这才是能不断积累价值的部分。

输出传递

每条命令都接受 --deliver <sink>。输出除了（或取代）stdout 外，还会发送到指定的汇；这样 Agent 就能路由命令结果，而无需手动通过管道传递。支持三种汇：

汇	效果
stdout	默认；仅写入 stdout
file:<path>	将输出原子写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到该 URL（当使用 --compact 时，内容类型为 application/json 或 application/x-ndjson）

不支持的方案会被拒绝，并返回结构化错误，说明支持的方案。Webhook 请求失败时会返回非零状态码，并在 stderr 中记录 URL 和 HTTP 状态码。

命名配置

配置档案是一组已保存的标志值，可在多次调用中重复使用。计划任务中的 Agent 每次都以相同配置调用同一命令时，可以使用它——这就是 HeyGen 的“Beacon”模式。

obsidian-pp-cli profile save briefing --json
obsidian-pp-cli --profile briefing deadends
obsidian-pp-cli profile list --json
obsidian-pp-cli profile show briefing
obsidian-pp-cli profile delete briefing --yes

显式标志始终优先于配置档案中的值；配置档案中的值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置档案，以便 Agent 在运行时发现它们。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
5	API 错误（上游问题）
7	请求过于频繁（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 obsidian-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上文的先决条件
3. 其他任何内容 → 直接使用（作为 CLI 命令执行，并带上 --agent）

安装 MCP 服务

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/productivity/obsidian/cmd/obsidian-pp-mcp@latest
   

2. 注册到 Claude Code：

   claude mcp add obsidian-pp-mcp -- obsidian-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which obsidian-pp-cli 如果未找到，请提供安装选项（参见本技能开头的先决条件）。
2. 将用户查询与上文“独特功能”和“命令参考”中的最佳命令匹配。
3. 使用 --agent 标志执行：

   obsidian-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，请查看子命令帮助：obsidian-pp-cli <command> --help。