olcubo_obsidian-cubox/README.zh-CN.md

Cubox Obsidian 插件

English

Cubox 官方 Obsidian 插件，可将 Cubox 中的收藏与标注单向同步到 Obsidian 库中。

功能

• 单向同步：仅 Cubox → Obsidian，Obsidian 中的修改不会回写到 Cubox
• 自动或手动同步：按间隔自动执行，或通过侧边栏图标 / 命令面板手动触发
• 筛选：按文件夹、类型、标签、状态过滤要同步的内容
• 模板：自定义文件名、元数据（front matter）与正文格式
• 标注同步：将 Cubox 中的高亮与笔记导出到 Obsidian

安装

从社区插件安装

1. 打开 Obsidian 设置
2. 进入 社区插件
3. 点击 浏览，搜索 Cubox
4. 点击 安装，然后 启用

手动安装

1. 下载最新的 main.js、manifest.json 和 styles.css
2. 在库中创建 .obsidian/plugins/obsidian-cubox 文件夹
3. 将上述文件复制到该文件夹
4. 在 Obsidian 设置中启用插件

配置

1. Cubox 服务器域名：选择你使用的域名（cubox.cc 或 cubox.pro）
2. Cubox API Key：填写 API Key，或粘贴 Cubox 网页端 扩展与自动化 → API 扩展 中的完整链接

快速开始

1. 选择正确的服务器域名并填写 API Key。
2. 首次同步前，必须配置全部四项筛选：
   • 文件夹筛选（Folder filter）
   • 标签筛选（Tag filter）
   • 类型筛选（Type filter）
   • 状态筛选（Status filter）
3. 设置目标文件夹，按需调整默认模板。
4. 手动同步（侧边栏图标或 Sync now 命令），或设置自动同步间隔。

重要： 任一筛选项未配置时，同步不会执行。默认四项均为空是正常状态，需要你主动选择要同步的范围。

同步机制说明

理解以下规则，可以避免大多数使用困惑：

单向、只创建不更新

• 同步方向为 Cubox → Obsidian。
• 插件只会 创建新笔记，不会更新 库中已存在的笔记。
• 某条收藏同步到 Obsidian 之后，你在 Cubox 里新增标注、修改标题或标签，不会 自动反映到已有 Obsidian 笔记中。

每条 Cubox 收藏只同步一次

• 每条同步的笔记会在 front matter 中写入 Cubox 卡片 id（用于去重，始终会写入）。
• 后续同步时，若目标路径下已存在相同 id 的笔记，该卡片会被 跳过。
• 完成提示可能显示 X new items, Y skipped。skipped 表示该卡片此前已同步，不是错误。

增量拉取

• 插件会记录上次同步进度，后续运行主要拉取 新的 Cubox 卡片。
• 修改 目标文件夹 会重置同步游标，可能再次尝试拉取历史卡片——但仍受「每条只同步一次」规则约束；旧文件夹里的笔记不会被更新。

标注是同步时刻的快照

• 导出到 Obsidian 的标注，是同步时 Cubox 返回的数据。
• 建议在 Cubox 中完成标注后再同步；使用较长间隔或手动同步，可减少「标注尚未写完就被导出」的情况。

默认模板不含文章正文

• 默认正文模板包含标题、摘要、链接和标注列表。
• 若需要同步 全文正文，请在设置的 Content template 中加入 {{content}} 或 {{content_highlighted}}。

筛选说明

只有 同时满足 各项筛选条件的内容才会被同步：

筛选项	说明
文件夹	指定 Cubox 文件夹，或选择 All items（全部）
标签	指定标签、No tags（无标签），或 All items
类型	Article、Snippet，以及 Others（Memo、Image、Audio、Video、File）
状态	All items，或限定已读 / 星标 / 有标注

提示：

• 若感觉「少同步了很多」，请逐项检查四项筛选，而不只是文件夹。
• 同时勾选多种状态（例如已读 且 星标）会进一步缩小范围。
• 若只要带标注的内容，可使用 annotated 状态筛选——但已同步过的笔记仍不会收到 Cubox 里新增的标注。

模板

可在插件设置中自定义：

• File name template — 文件名，支持 Mustache 变量，如 {{{title}}}、{{{create_time}}}
• Metadata variables — front matter 字段（Cubox id 始终会写入）
• Content template — 正文布局，含 {{#highlights}} 等块
• Date format — 模板中日期的显示格式

设置页中的 reference 链接可查看完整变量说明与示例。

常见问题

为什么在 Cubox 里新加的标注，Obsidian 里没有？

插件 不会更新 已存在的笔记。Cubox 中新增或修改的标注，不会自动写入 Obsidian，需要你在 Obsidian 中手动编辑。

目前没有内置的「重新同步并覆盖」功能。可选做法：

• 在 Obsidian 中手动更新笔记，或
• 删除 Obsidian 中的对应笔记后再次同步（请先理解去重与筛选规则）

是不是只能同步一次？还能继续同步吗？

可以持续同步：

• 自动同步 按你设置的间隔运行，拉取 新 的 Cubox 卡片。
• 手动同步（侧边栏图标或命令面板 → Sync now）随时触发，行为相同。
• 已同步过的卡片会被跳过；插件 并非 只能运行一次。

为什么完全没有任何内容被同步？

请按顺序检查：

1. API Key 与服务器域名是否正确
2. 四项筛选是否都已配置（任一项为空则不会同步）
3. Cubox 中的内容是否确实满足全部筛选条件

为什么感觉少同步了很多数据？

常见原因：

1. 筛选过严 — 例如同时限定「有标注 + 某标签 + 某文件夹」
2. 类型筛选 — 未勾选 Others，备忘录、图片、文件等类型不会被同步
3. 标签筛选 — 只选了部分标签，无标签条目会被排除
4. 默认模板 — 未包含 {{content}}，笔记看起来比预期短（仅有元数据与标注，无全文）
5. 同步过早 — 卡片首次同步时 Cubox 中的标注尚未写完

同步完成提示里的 "skipped" 是什么意思？

表示这些 Cubox 卡片此前已导出到 Obsidian（通过 id 匹配），本次被跳过，未再次写入。

Obsidian 里的修改会同步回 Cubox 吗？

不会。同步是单向的：Cubox → Obsidian。

依赖

• Mustache：模板渲染
• Luxon：日期时间处理

许可证

本项目采用 MIT License。