ObsCli · Obsidian 命令行工作流封装
ObsCli 把 Obsidian 桌面端官方命令行（CLI，v1.12 起免费公开）封装成 AI 助手可直接驱动的统一入口：
读、写、检索、整理库内笔记，勾选任务，管理标签与属性，操作模板与工作区，甚至控制同步与插件——
共 115 个子命令；Windows / macOS / Linux / HarmonyOS 四平台通用，纯标准库脚本、零第三方依赖。
官方文档：https://obsidian.md/help/cli（命令语义以官方为准，本技能为封装层）
能力矩阵
| 能力组 | 命令数 | 典型动作 |
|---|---|---|
| 文件与目录 | 12 | 新建 / 读取 / 追加 / 插入 / 移动 / 重命名 / 删除 / 打开 / 列出 |
| 日记 | 5 | 打开今日日记、取路径、读内容、追加、顶部插入 |
| 搜索 | 3 | 全文搜索、带上下文搜索、打开搜索视图 |
| 任务 | 2 | 列出库内任务、按行号勾选任务 |
| 标签 / 属性 / 别名 | 7 | 标签统计与详情、属性读写删、别名清单 |
| 双链 | 5 | 反向链接、正向链接、未解析链接、孤儿笔记、死链笔记 |
| 模板 | 3 | 列出模板、读模板、插入当前文件 |
| Bases 数据库 | 4 | 列出 base、列视图、建条目、查询 |
| 工作区 / 标签页 / 命令 | 14 | 标签页、工作区保存载入、命令与快捷键、大纲、书签 |
| 历史与差异 | 6 | 版本列表、读旧版、还原、本地/同步差异 |
| 同步与发布 | 13 | 同步启停与版本、已删除文件、发布增删与站点 |
| 主题与插件 | 18 | 主题安装切换、CSS 快照启停、插件安装启停重载 |
| 库与杂项 | 9 | 库信息、随机笔记、唯一命名、字数、最近打开、内建浏览器 |
| 开发者 | 10 | 执行 JS、截图、DevTools、DOM / CSS 检查、CDP |
| 通用 | 4 | 帮助、版本、重载、重启 |
| 合计 | 115 | 完整清单见 references/01-commands.md |
适用人群与触发场景
- 知识管理者：让 AI 批量建笔记、补标签属性、清理孤儿与死链笔记。
- 日记 / 任务党：一句话追加今日日记、勾选待办、汇总未完成事项。
- 重度插件用户：批量装主题插件、切换外观、重载插件、管理同步与发布。
- 自动化玩家：把 Obsidian 库接进脚本、定时任务或其他 Agent 工作流。
支持的平台
| 平台 | 说明 |
|---|---|
| Windows | 自动找 %LOCALAPPDATA%\Obsidian；命令用 py -3 代替 python3 |
| macOS | 自动找 /Applications/Obsidian.app/Contents/MacOS/obsidian |
| Linux | 支持 Snap / Flatpak / AppImage 三种安装形态 |
| HarmonyOS | 无桌面端 IPC，走「零脚本模式」直接读写库内 Markdown（见 references/02-cross-platform.md） |
快速开始
python3 scripts/install.py # 安装（Windows 用 py -3）
python3 scripts/doctor.py # 环境自检：定位可执行文件 + 验证 CLI
python3 scripts/obscli.py version # 经统一启动器验证连通性
python3 scripts/install.py --uninstall # 卸载
前置条件：Obsidian 1.12+ 正在运行，且设置 → 通用 → 启用 CLI。
无需手配 PATH——启动器自动定位可执行文件，也可用环境变量 OBSIDIAN_CLI 精确指定。
语法规则
- 参数：
name=value或name="带空格的值" - 开关：只写名字，如
open、overwrite - 换行：内容字符串里用
\n - 指定库：
obscli vault="My Vault" <命令>（必须放最前） - 指定文件：
file=<名称>（维基链接式解析）或path=<目录/文件.md>（精确路径） - 复制输出：任意命令末尾追加
--copy
常用命令速查
obscli daily # 打开今日日记
obscli daily:append content="- [ ] 买牛奶" # 追加到今日日记
obscli create name="笔记" content="# 你好" # 新建笔记
obscli read file="笔记" # 读笔记
obscli append file="笔记" content="更多文字" # 追加内容
obscli search query="会议纪要" # 全文搜索
obscli tasks daily todo # 今日未完成任务
obscli task daily line=3 toggle # 切换第 3 行任务状态
obscli tags counts # 标签统计
obscli property:set name="status" value="done" file="笔记"
obscli backlinks file="笔记" # 反向链接
行为契约（必须遵守）
- 每次执行 CLI 命令后，用一行清单向用户报告本次动作：
[ObsCli] 动作=<动作名> | 目标=<文件/库> | 结果=<成功/失败+摘要> delete/move/rename/plugin:uninstall/workspace:delete等破坏性动作：
先复述目标对象并获得用户确认，再执行。- 命令失败时如实报错，绝不伪造输出；无桌面端环境（鸿蒙）转零脚本模式并留痕。
故障排查
| 现象 | 处理 |
|---|---|
| Cannot connect to Obsidian | 确认 Obsidian 正在运行，且设置 → 通用 → 启用 CLI |
| Command not found: obsidian | 无需配 PATH，直接用 scripts/obscli.py；或设 OBSIDIAN_CLI |
| File not found | file=名称 按维基链接解析（不带路径、不带 .md）；精确路径用 path=目录/文件.md |
| Windows 中文乱码 | 先执行 chcp 65001，再跑脚本 |
| 命令长时间无响应 | Obsidian 未运行时 CLI 会等 IPC，可设 OBSCLI_TIMEOUT=15 让启动器超时退出 |
更多排查细节见 references/03-troubleshooting.md；命令语义与版本差异以官方文档为准：https://obsidian.md/help/cli
English Summary
ObsCli wraps the official Obsidian desktop CLI (v1.12+, free) into a unified, cross-platform
entry point for AI workflows: 115 subcommands covering notes, daily journals, tasks, search,
tags, properties, links, templates, bases, workspaces, history, sync/publish, themes, plugins
and dev tools. It ships with a universal launcher (auto-locates the obsidian binary,
Flatpak/AppImage friendly, no manual PATH setup), a doctor self-check and a one-line installer.
Pure standard library, zero third-party dependencies, supporting
Windows / macOS / Linux / HarmonyOS (zero-script fallback). Golden rule: report every executed
action to the user in one line; confirm before any destructive action.
品牌：瑆皓科技 · 技术支持微信 vvip2u
