sync-vault-cli

Sync Vault CLI

本技能用于让大模型在需要“通过 Sync Vault CLI 查询/检索/读取云端文件、获取账号信息、诊断同步状态、查看配置或设备列表”时，能稳定、正确地调用本项目提供的 CLI 命令。

适用范围与前提

• 适用：Obsidian Sync Vault 插件已加载且已注册 CLI handler（Obsidian 版本需要支持 registerCliHandler）。
• 命令形式：obsidian sync-vault:<subcommand> key=value key2=value2（所有子命令都支持 help=true）。
• 输出形式：
  • list/search/info/doctor：输出为 JSON 字符串（可直接解析）。
  • read：输出为文本（可能被套餐截断；PDF 在 Free 下会拒绝）。
• 套餐限制（重要）：
  • search：Free 通常仅返回前 5 条；Basic/Pro 支持分页。
  • list：Free 通常最多返回 20 条；Basic/Pro 支持 limit/offset 分页。
  • read：Free 文本读取通常最多 10KB 且会追加截断提示；PDF 读取是 Pro 功能。

快速自检工作流（推荐顺序）

1. obsidian sync-vault：列出可用命令（确认 CLI 已可用）
2. obsidian sync-vault:info cloud=<cloud>：确认账号可用/容量健康
3. 文件发现优先：
   • 有关键词：obsidian sync-vault:search ...
   • Provider 不支持 search 或想要稳定遍历：obsidian sync-vault:list ...
4. 内容读取：obsidian sync-vault:read path=<filePath> cloud=<cloud>

如遇异常或用户反馈“同步失败/打不开/很慢”：

• obsidian sync-vault:doctor cloud=<cloud> 获取诊断报告（JSON）

云类型（cloud 参数）

• 常用：baidu | aliyun | quark | onedrive | onelife
• 其他（视实际接入与登录状态）：cos | infinicloud | nutstore
• 建议：cloud 统一使用小写字符串；若用户未指定 cloud，部分命令会使用当前选择的云盘（例如 info/doctor 的内部逻辑）。

命令参考

1) 帮助

• 主帮助：obsidian sync-vault
• 子命令帮助：obsidian sync-vault:list help=true（任意子命令都支持）

2) list：列出目录文件（支持过滤/递归/分页）

obsidian sync-vault:list path=<path> cloud=<cloud> limit=<n> offset=<n> type=<type> minSize=<bytes> modifiedAfter=<iso|ms> recursive=true|false

• path：默认 /
• type：markdown|md|pdf|image|video|audio|folder|text...
• recursive=true：会触发递归列举（可能较慢）

输出 JSON 结构（核心字段）：

• files[]: { id, path, name, type, isFolder, size, modified }
• pagination: { total, returned, limit, offset, hasMore, nextOffset }

分页策略：

• 如果 pagination.hasMore=true，用 offset=pagination.nextOffset 继续取下一页。

3) search：关键词检索（文件级，不读内容）

obsidian sync-vault:search query=<keyword> cloud=<cloud> limit=<n> offset=<n> path=<prefix> type=<type>

• 约束：至少提供 query/type/path 之一，否则会返回结构化错误。
• Provider 不支持 search 时：通常会返回 isError=true，并给出建议改用 list。