Obsidian Wolai Sync

简体中文 | English

在 Obsidian 与 Wolai（我来）之间同步 Markdown 页面、数据库记录、子页面和图片的社区插件，支持富文本格式、多种块类型和智能的同步状态管理。

本项目基于 MarswayRed/obsidian-wolai-sync 继续开发，保留原项目的版权与许可证，并由 Ricardo-Ping 维护增强版本。感谢原作者 Li Wei 和原项目提供的基础实现。

✨ 功能特性

• 🔄 完整双向同步：支持 Obsidian → Wolai 和 Wolai → Obsidian 的双向内容同步
• ⚡ 增量双向同步：基于页面版本、编辑时间、内容指纹和图片状态，自动跳过未变化内容
• 📄 普通页面同步：除数据库外，可直接配置一个或多个 Wolai 页面 URL/ID，并递归同步子页面
• 🗂️ 页面层级映射：Wolai 子页面保存为父页面同名目录下的独立 Markdown 文件
• 🖼️ 图片增量同步：图片保存到对应页面目录的 pictures/，仅更新新增或变化的图片
• 🧮 数学公式转换：Wolai 行内/块级公式与 Obsidian MathJax 的 $...$ / $$...$$ 双向转换
• 📊 整表高效读取：优先从表格详情一次取得 table_content，将完整文本表格转换为 Markdown 行列，避免逐格请求（同结构测试请求数减少约 95.3%）
• 🛡️ 原位更新与冲突保护：已有 wolai_id 的文件更新原页面；本地与远端同时变化时停止覆盖，并在 _conflicts/ 保存 Wolai 副本
• 💾 原子断点检查点：每个完成页面追加轻量日志；大页面支持页内断点，中断、限额等待或重载后可续传
• ⏳ API 配额保护：本地滚动统计一小时调用量，按 Wolai 套餐额度慢速等待并自动续传，支持 HTTP 429 退避重试
• ⏯️ 任务控制：支持暂停、继续和停止完整/增量同步
• 🧹 安全清理：仅在完整同步成功后，将插件生成且未被手动修改的过期文件移至系统废纸篓
• 📈 实时日志与进度：流式展示页面进度、API 调用、429 重试、成功和错误信息
• 🕐 自动同步与文件监听：均可选，新安装默认关闭，避免意外消耗 API 额度
• 🔒 仅同步到 Wolai：保留原有单向写入能力，不删除 Wolai 内容

📋 安装方法

方法一：手动安装（推荐）

1. 获取插件文件（main.js、manifest.json、styles.css）
2. 将整个插件文件夹复制到你的 Obsidian 库目录下的 .obsidian/plugins/obsidian-wolai-sync/
3. 重启 Obsidian
4. 在 Obsidian 设置 → 社区插件中启用 Wolai Sync

方法二：从源码构建

需要 Node.js 18 或更高版本。

git clone https://github.com/Ricardo-Ping/obsidian-wolai-sync.git
cd obsidian-wolai-sync
npm install
npm run build

然后将以下文件复制到你的 Obsidian 库：

<你的库>/.obsidian/plugins/obsidian-wolai-sync/
├── main.js
├── manifest.json
└── styles.css

🎯 适用场景

• 知识管理系统：将 Obsidian 中的笔记同步到 Wolai 进行团队协作
• 内容发布工作流：在 Obsidian 中编写文档，自动同步到 Wolai 进行发布
• 双向数据备份：确保重要内容在两个平台上都有备份
• 团队协作：Obsidian 中个人编辑，Wolai 中团队共享和讨论

⚙️ 配置说明

1. Wolai API 设置

1. 在 Wolai 开发者中心 创建应用
2. 获取 App ID 和 App Secret，并让应用拥有目标页面/数据库的访问权限
3. 在插件设置中填入 App ID 和 App Secret

2. Obsidian 设置

• 同步文件夹：指定要同步的 Obsidian 文件夹路径（例如 Notes/Wolai）

3. 同步设置

• 数据库 ID：使用数据库同步时填写
• 普通页面（可选）：每行一个，格式为 标题 | 页面 URL 或页面 ID，可递归同步子页面
• 每小时 API 额度：与当前 Wolai 套餐匹配
• 自动同步 / 同步间隔：可选，默认关闭
• 文件监听：可选，默认关闭

配置完成后点击 "测试连接" 验证。配置仅保存在本地 Obsidian 插件数据中，请勿提交 data.json、日志或状态文件。

Wolai 数据库要求

使用数据库同步时，数据库至少需要以下字段：

字段	类型	说明
标题	标题/文本	Obsidian 文件标题
同步状态	单选	使用 Pending、Synced 等状态

普通页面递归同步不要求建立数据库。

🚀 使用方法

手动同步

点击侧边栏的 Wolai Sync 图标，或在插件设置中点击"手动同步"，执行一次完整双向同步。

强制同步当前文件

1. 打开要同步的 Markdown 文件
2. 命令面板（Ctrl/Cmd + P）→ 搜索 "强制同步当前文件"
3. 插件绕过常规检查，直接将当前文件内容写入 Wolai

自动同步（可选）

在设置中启用 自动同步 并设置间隔（5–120 分钟），插件会定时执行增量同步。

文件监听（可选）

在设置中启用 文件监听 后，同步文件夹内的文件变化会自动加入同步队列。

同步状态说明

插件通过文件的 FrontMatter 管理同步状态：

---
sync_status: Synced
wolai_id: "page_id_from_wolai"
last_sync: "2024-01-15T10:30:00.000Z"
---

• Pending：新文件，待首次同步到 Wolai
• Modified：文件已修改，需要重新同步到 Wolai
• Synced：已成功同步，无需重复操作
• Wait For Syncing：Wolai 中标记需要同步到 Obsidian

同步模式

完整双向同步

重新读取配置的页面和数据库记录，写入页面及图片。只有整次成功后才提交最终状态并执行安全清理。

增量双向同步

先读取轻量元数据，未变化页面直接跳过；发生变化时再读取内容，并按图片版本分别处理新增、修改和删除。每个完成页面追加轻量检查点，整次成功后再原子合并状态；含子页面的父节点会在递归前保存。

仅同步到 Wolai

只将 Obsidian 中待同步的文件写入 Wolai，不执行 Wolai → Obsidian，也不会因为本地缺少文件而删除 Wolai 页面。有 wolai_id 时更新已有页面，没有时才创建数据库记录。

📁 文件结构

页面层级映射

Wolai 子页面保存为父页面同名目录下的独立 Markdown 文件，每个页面的图片放在该页面自己的 pictures/ 目录中。例如：

Wolai/
├── 数据库查询重写.md
└── 数据库查询重写/
    ├── pictures/
    ├── GRewriter.md
    └── GRewriter/
        └── pictures/

同名页面

同一目录出现同名页面时，插件按 Wolai 页面 ID 分配稳定路径：已有文件保持原名，另一页使用 标题--短ID.md；短 ID 冲突时自动加长，不会覆盖已属于其他页面的文件。路径映射原子保存到插件目录，重启、续传和遍历顺序变化不会交换文件名。

📊 大页面与整表优化

页内断点（大页面）

• 完整和增量同步会将成功读取的内容分页追加到插件目录的页内断点，中断、限额等待或重载后可在同一页面版本下复用已读取批次，不必重读整页；分页游标随批次保存。
• 恢复前检查页面版本，版本或账号变化会使缓存失效；页面正文及同步基线保存成功后才清除对应断点。
• 内容块按 ID 去重，循环引用、重复游标、没有新增内容的分页以及异常深度/规模会明确报错，避免无休止调用接口。
• 日志记录每次 API 请求的序号、方法、接口路径、状态和耗时，不记录认证信息、请求正文或图片签名链接。

整表读取优化

GET /blocks/{表格ID} 返回的表格详情可包含完整的 table_content。插件先核对表格版本、矩阵行列数、单元格数和内容类型；完整且受支持时只取一次详情，跳过表格及单元格的逐级读取，详情不完整时保留原逐块读取。

• 保留文本单元格、空值、前导零、小数位、百分号、换行、常见富文本和行内公式；表格中的 LaTeX 竖线使用等价的 \vert{} / \Vert{}，避免 Markdown 分列混淆。
• Markdown 不是 Wolai 的像素级复制：列宽、颜色、合并单元格和特殊嵌入不保证一致。
• 表格目前仅支持 Wolai → Obsidian 导入。 含已同步表格的页面暂时禁止回写，请在 Wolai 修改这类页面。
• 同结构测试（22 张表、564 个单元格）：请求数从 592 次降至 28 次，约减少 95.3%。

⏳ API 限制与慢速同步

插件在真正发送 Wolai API 请求前记录本地时间戳，以滚动 60 分钟窗口控制额度。达到所选套餐额度后，任务会保留并等待旧请求释放额度；等待提示本身是本地检查，不消耗 API。

Wolai 服务端仍可能返回 HTTP 429；插件会读取 Retry-After（如果存在）并退避重试。月度额度无法通过延迟绕过。

🛠️ 支持的 Markdown 语法

文本格式

• 粗体文本：**粗体** 或 __粗体__
• 斜体文本：*斜体* 或 _斜体_
• 行内代码：`代码`
• 删除线：~~删除线~~
• 链接：[链接文本](URL)

块级元素

• 标题：# 到 ######
• 无序列表：- 项目 或 * 项目
• 有序列表：1. 项目
• 代码块：```代码```
• 引用：> 引用内容
• 分割线：--- 或 ***

🛡️ 安全策略

• App Secret、插件设置、同步日志、API 计数和增量状态均已列入 .gitignore
• 自动同步和文件监听默认关闭，避免意外消耗 API 额度
• 失败或取消的完整同步不会触发过期文件清理
• 清理只处理插件清单中记录且未被用户手动修改的文件，并优先移动到系统废纸篓
• 本地与远端同时变化时不会自动覆盖；Wolai 版本会保存到 _conflicts/，解决冲突前任务会报告失败

❗ 注意事项

1. 同步前请确保重要数据已备份
2. 首次使用前请使用"测试连接"功能验证配置
3. 确保 Wolai 应用有访问目标页面/数据库的权限
4. 避免在同步过程中同时编辑文件，以免产生冲突副本
5. 某些特殊字符或复杂嵌套可能需要转义或手工处理

🐛 故障排除

1. 连接失败

• 检查 App ID 和 App Secret 是否正确
• 确认应用已连接到 Wolai 工作区并拥有目标页面权限
• 验证网络连接是否正常

2. 同步失败

• 查看 Obsidian 开发者控制台（Ctrl+Shift+I）的错误信息
• 检查 Wolai 数据库字段是否完整
• 确认文件的 FrontMatter 格式正确

3. 重复同步

• 检查文件的 sync_status 字段值
• 确认 Wolai 数据库中的同步状态设置
• 检查是否达到了每小时 API 额度

4. 冲突副本

• 本地与远端同时编辑会产生冲突副本，合并后重新标记为 Modified 即可继续同步

📋 已知限制

• Wolai 与 Markdown 的块模型不同，复杂嵌套、部分数据库属性或特殊富文本可能无法完全无损转换。
• 网络中断、服务端限流和套餐月度额度仍可能使任务暂停或失败。
• 同一页面在两端同时编辑会生成冲突副本，需要人工合并后重新标记为 Modified。
• 本项目尚未进入 Obsidian 官方社区插件市场，当前需手动安装。

🔧 开发与验证

npm install
npm run lint
npm test
npm run build
# 或一次执行全部检查
npm run check

仓库提交源代码，不提交 node_modules/、本地配置、日志、同步状态或构建产物 main.js。发布插件时需附带 main.js、manifest.json 和 styles.css。

📄 许可证

本项目是 MarswayRed/obsidian-wolai-sync 的衍生改进版本。原仓库基于 Obsidian Sample Plugin，并使用 0BSD 风格许可证文本。

版权和许可详情见 LICENSE。原项目版权声明继续保留，2026 年后的增强修改版权归 Ricardo_PING 所有。

🤝 贡献

欢迎提交 Issue 和 Pull Request。报告同步问题时，请先移除日志中的 App ID、App Secret、页面 ID、页面标题和本地路径等敏感信息。