# Cubox Obsidian 插件

[English](README.md)

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](https://mustache.github.io/)：模板渲染
- [Luxon](https://moment.github.io/luxon/#/formatting?id=table-of-tokens)：日期时间处理

## 许可证

本项目采用 [MIT License](https://choosealicense.com/licenses/mit/)。