README file from
GithubinBox Sync for Obsidian
将 inBox 笔记单向同步到 Obsidian vault 的插件。
inBox 是收集箱，编辑/删除交给桌面端做。插件只读云端，不在 Obsidian 里修改云端数据。
功能
- 单向同步（云端 → Obsidian）：只下载不上传
- inBox App 是收集端，Obsidian 是工作台
- 在 Obsidian 里编辑/删除文档不会回传到云端
- 不支持在 Obsidian 里新建笔记（新笔记请在 inBox App 创建）
- 多存储后端：WebDAV / S3 兼容存储
- 智能增量同步：仅同步有变化的笔记（基于 ETag + mtime）
- 完整资源支持：图片、视频、录音、附件
- 自动标签提取：支持层级标签（
#tag/subtag） - 可配置同步间隔和文件夹结构
安装
插件尚未进入 Obsidian 官方社区目录（审核排队中），目前推荐用 BRAT 安装。
方法 1：BRAT 安装（推荐）
BRAT 可以从 GitHub 仓库直接安装插件，并自动接收更新。适合尚未进入官方目录的插件。
- 在 Obsidian 中安装并启用 BRAT 插件（社区目录可搜到）
- 打开 BRAT 设置 → Add Beta plugin → 输入仓库地址：
maoruibin/obsidian-inbox-sync - 回到 Obsidian 设置 → 社区插件，启用 inBox Sync
之后本仓库发版，BRAT 会自动拉取更新。
方法 2：手动安装
- 从 Releases 下载
main.js、manifest.json、styles.css - 把文件放到 Obsidian vault 的插件目录：
.obsidian/plugins/inbox-sync/ - 在 Obsidian 设置中启用 inBox Sync
升级时需要重复上述步骤手动替换文件，所以非开发者推荐用 BRAT。
方法 3：开发模式（贡献者）
git clone https://github.com/maoruibin/obsidian-inbox-sync.git
cd obsidian-inbox-sync
npm install
npm run dev
npm run dev 会监听文件变化自动重新构建，并把产物复制到配置的 Vault 插件目录。
配置
WebDAV 配置
- 在设置中选择存储类型为 "WebDAV"
- 填写 WebDAV 服务器地址、用户名、密码
- 设置 inBox 数据路径（默认：
/inbox/）
S3 配置
- 在设置中选择存储类型为 "S3 Compatible"
- 填写 S3 端点、Access Key、Secret Key、Bucket
- 设置 Region 和路径前缀
同步设置
- Vault 文件夹路径：笔记在 vault 中的存储位置（默认：
inBox） - 自动同步间隔：自动同步的时间间隔（分钟）
目录结构
同步后的目录结构会按盒子组织:
inBox/
├── notes/ # 无盒子笔记(根目录平铺)
│ ├── 2025-04-10 note-title.md
│ └── 2025-04-11 another.md
├── 工作/ # "工作"盒子下的笔记
│ └── project-xxx.md
├── 生活/ # "生活"盒子下的笔记
│ └── shopping-list.md
├── assets/ # 资源文件(所有盒子共享)
│ ├── images/
│ │ └── photo.jpg
│ ├── videos/
│ │ └── video.mp4
│ ├── audios/
│ │ └── recording.mp3
│ └── attachments/
│ └── file.pdf
└── .inbox-sync-meta.json # 同步元数据(含盒子文件夹映射)
盒子文件夹规则:
- 笔记的
content.box_id在云端boxes.json里查得到 → 进<盒子名>/子文件夹 - 否则(无盒子 / 盒子被删墓碑) → 根目录
inBox/平铺 - 用户没配盒子时,所有笔记自然都在根目录
- 盒子重命名时,文件夹自动 rename,frontmatter
box:字段同步更新 - 盒子删除时,文件夹内笔记移回根目录,文件夹清空
- 资源文件统一放
assets/,不按盒子分
盒子名清洗规则: / \ : * ? " < > | 替换为 -,空名 fallback 到 box_id 短码,撞名追加 box_id 后缀。
Markdown 格式
同步后的笔记包含 YAML frontmatter：
---
title: 今日记录
inbox_id: note-abc123
created: 2025-04-10T10:30:00.000Z
updated: 2025-04-10T10:30:00.000Z
box: 工作
tags:
- 日记/生活
- 心情/开心
---
#日记/生活
今天天气不错 #心情/开心
![[../assets/images/2025/04/photo.jpg]]
box字段表示笔记所属的盒子（来自云端boxes.json），无盒子的笔记不会写这一行。
删除语义
- 在 inBox App 删除笔记 → 云端
flags.is_removed=true→ 插件下次同步时移除 Obsidian 对应文件 - 在 Obsidian 里删文件 → 不影响云端（单向同步，Obsidian 是只读副本）
已知限制
- 不支持在 Obsidian 里新建笔记：新建请在 inBox App 完成，插件只同步已有 noteId 的笔记
- 不支持回传：在 Obsidian 里编辑/删除文档不会影响云端（单向同步）
- 盒子管理：盒子的创建/重命名/删除需在 inBox App 完成（插件只读 boxes.json）
开发
# 安装依赖
npm install
# 开发模式（监听文件变化）
npm run dev
# 构建生产版本
npm run build
数据格式兼容性
本插件与 inBox Android/Flutter 版本共享数据格式：
XBlock：笔记数据结构XTag：标签数据结构XResourceInfo：资源信息结构
许可证
MIT