From 3f0f7a4ad138ec8a0ef1bfe3eb0ae8ff3d54eb7a Mon Sep 17 00:00:00 2001
From: delphi <delphi_wu@icloud.com>
Date: Mon, 25 May 2026 11:32:40 +0800
Subject: [PATCH] docs: expand sync documentation and add Chinese README

Clarify one-way sync, deduplication, filters, and common user questions to reduce support confusion.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 README.md       | 146 ++++++++++++++++++++++++++++++++++++++-----
 README.zh-CN.md | 160 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 289 insertions(+), 17 deletions(-)
 create mode 100644 README.zh-CN.md

diff --git a/README.md b/README.md
index 777334e..7a47942 100644
--- a/README.md
+++ b/README.md
@@ -1,22 +1,25 @@
 # Cubox Plugin for Obsidian
 
-The official Cubox plugin for Obsidian allows you to synchronize articles and annotations from Cubox to Obsidian.
+[中文文档](README.zh-CN.md)
+
+The official Cubox plugin for Obsidian syncs articles and annotations from Cubox into your vault.
 
 ## Features
 
-- Automatic Sync: Periodically sync articles and annotations from Cubox to Obsidian
-- Filtering: Filter content by folder, type, tags, and status
-- Templates: Customize file names, front matter, and content format
-- Annotation Sync: Sync highlighted content from Cubox to Obsidian notes
+- **One-way sync**: Cubox → Obsidian only. Changes in Obsidian are not sent back to Cubox.
+- **Automatic or manual sync**: Run on a schedule or trigger sync from the ribbon icon / command palette.
+- **Filtering**: Filter by folder, type, tags, and status.
+- **Templates**: Customize file names, front matter, and note body.
+- **Annotation sync**: Export highlights and notes from Cubox into Obsidian.
 
 ## Installation
 
 ### Install from the Community
 
 1. Open Obsidian settings
-2. Navigate to the "Community plugins" tab
-3. Click the "Browse" button and search for "Cubox"
-4. Click Install
+2. Navigate to the **Community plugins** tab
+3. Click **Browse** and search for **Cubox**
+4. Click **Install**, then **Enable**
 
 ### Manual Installation
 
@@ -27,16 +30,125 @@ The official Cubox plugin for Obsidian allows you to synchronize articles and an
 
 ## Configuration
 
-1. Cubox Server Domain: Select the Cubox server domain you use (cubox.cc or cubox.pro)
-2. Cubox API Key: Enter your Cubox API key or link (generate it in the Cubox web settings under Extensions & Automation - API Extension)
+1. **Cubox server domain**: Select the domain you use (`cubox.cc` or `cubox.pro`)
+2. **Cubox API key**: Enter your API key or paste the full key link from Cubox web settings under **Extensions & Automation → API Extension**
 
-## Usage
+## Quick Start
 
-1. Before setting up, ensure you have selected the correct server and entered the API key
-2. Only content that meets all filter conditions will be synced
-3. Refer to the settings page for reference links to template variables
-4. Each item is synced only once from Cubox, updates in Cubox will not be synced to Obsidian unless you change the target folder
-5. It is recommended to set a longer sync interval or use manual sync to prevent syncing unfinished annotations
+1. Select the correct server domain and enter your API key.
+2. Configure **all four filters** before the first sync:
+   - Folder filter
+   - Tag filter
+   - Type filter
+   - Status filter
+3. Choose a target folder and review the default templates if needed.
+4. Trigger sync manually (ribbon icon or **Sync now** command), or set an auto-sync interval.
+
+> **Important:** Sync will not run until every filter category has at least one option selected. The default empty filter state is intentional—you must choose what to sync.
+
+## How Sync Works
+
+Understanding these rules prevents most confusion:
+
+### One-way, create-only
+
+- Sync direction is **Cubox → Obsidian only**.
+- The plugin **creates new notes**. It does **not update** notes that already exist in your vault.
+- If you add new highlights, edit a title, or change tags in Cubox after a note was synced, those changes **will not appear** in the existing Obsidian note.
+
+### Each Cubox card is synced once
+
+- Every synced note stores the Cubox card `id` in front matter (always included for deduplication).
+- On later syncs, if a note with the same `id` already exists at the target path, that card is **skipped**.
+- The completion notice may show `X new items, Y skipped`. **Skipped** means the card was already synced—not an error.
+
+### Incremental fetching
+
+- The plugin remembers where the last sync stopped and only fetches **new cards** on subsequent runs.
+- Changing the **target folder** resets that cursor, so historical cards may be fetched again—but they are still subject to the one-time dedup rule above. Existing notes in the old folder are **not** updated.
+
+### Annotations are a snapshot
+
+- Highlights exported to Obsidian reflect what Cubox returned **at sync time**.
+- Sync again after you finish annotating in Cubox. A longer interval or manual sync helps avoid exporting incomplete highlights.
+
+### Default template does not include full article text
+
+- The default content template includes title, description, links, and highlights.
+- To sync the full article body, add `{{content}}` or `{{content_highlighted}}` to your **Content template** in settings.
+
+## Filters
+
+Only items that match **all** filter categories are synced:
+
+| Filter | What it does |
+|--------|----------------|
+| **Folder** | Limit to selected Cubox folders, or choose **All items** |
+| **Tag** | Limit to specific tags, **No tags**, or **All items** |
+| **Type** | Article, Snippet, and/or **Others** (Memo, Image, Audio, Video, File) |
+| **Status** | **All items**, or restrict to read / starred / annotated items |
+
+Tips:
+
+- If many items seem missing, review every filter—not just folders.
+- Selecting multiple status options (e.g. read **and** starred) narrows results further.
+- If you only need articles with highlights, use the annotated status filter—but remember that already-synced notes still will not receive new highlights later.
+
+## Templates
+
+Use plugin settings to customize:
+
+- **File name template** — Mustache variables such as `{{{title}}}` and `{{{create_time}}}`
+- **Metadata variables** — Front matter fields (the Cubox `id` is always written)
+- **Content template** — Note body layout, including `{{#highlights}}` blocks
+- **Date format** — Format used for date variables in templates
+
+See the reference links on the settings page for full variable lists and examples.
+
+## FAQ
+
+### Why don't my new highlights show up in Obsidian?
+
+The plugin does not update existing notes. New or edited highlights in Cubox stay in Cubox unless you edit the Obsidian note yourself.
+
+There is no built-in "re-sync and overwrite" option. Workarounds:
+
+- Manually update the note in Obsidian, or
+- Delete the Obsidian note and sync again (only if you understand dedup and filter behavior)
+
+### Can I sync only once, or does it keep syncing?
+
+Both are possible:
+
+- **Auto sync** runs on your chosen interval and picks up **new** Cubox cards.
+- **Manual sync** (ribbon icon or command palette → **Sync now**) does the same on demand.
+- Already-synced cards are skipped; the plugin is not limited to a single run.
+
+### Why is nothing syncing?
+
+Check these in order:
+
+1. API key and server domain are correct
+2. **All four filters** are configured (sync is blocked if any filter is empty)
+3. Your Cubox items actually match the combined filter rules
+
+### Why are many items missing?
+
+Common causes:
+
+1. **Filters too strict** — e.g. only annotated + specific tag + one folder
+2. **Type filter** — **Others** not selected, so memos/files are excluded
+3. **Tag filter** — only certain tags selected, so untagged items are excluded
+4. **Default template** — no `{{content}}`, so notes look shorter than expected (metadata + highlights only)
+5. **Synced too early** — highlights were still being edited in Cubox when the card was first exported
+
+### What does "skipped" mean in the sync notice?
+
+Those Cubox cards were already exported to Obsidian (matched by `id`). They were not synced again.
+
+### Do Obsidian edits sync back to Cubox?
+
+No. Sync is one-way: Cubox → Obsidian.
 
 ## Dependencies
 
@@ -45,4 +157,4 @@ The official Cubox plugin for Obsidian allows you to synchronize articles and an
 
 ## License
 
-This project is licensed under the [MIT License](https://choosealicense.com/licenses/mit/).
\ No newline at end of file
+This project is licensed under the [MIT License](https://choosealicense.com/licenses/mit/).
diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 0000000..ec39559
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,160 @@
+# 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/)。