Obsidian Wolai 同步插件

一个 Obsidian 插件，用于在 Obsidian 笔记和 Wolai 我来数据库之间进行双向同步。支持富文本格式、多种块类型，并提供智能的同步状态管理。

✨ 功能特性

• 🔄 双向同步: 支持 Obsidian → Wolai 和 Wolai → Obsidian 的双向内容同步
• 📝 富文本支持: 完整支持粗体、斜体、行内代码、删除线、链接等 Markdown 格式
• 🧱 多种块类型: 支持标题、段落、列表、代码块、引用、分割线等常见 Markdown 元素
• 📊 状态管理: 基于 FrontMatter 的智能同步状态跟踪，避免重复同步
• 📈 API 统计: 实时监控 API 调用次数，防止超出 Wolai API 限制
• ⚡ 手动触发: 精确控制同步时机，避免不必要的 API 调用
• 👀 文件监听: 可选的文件变化监听功能（默认关闭）
• 🔧 灵活配置: 丰富的配置选项，适应不同使用场景

📋 安装方法

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

1. 下载插件文件到本地
2. 将整个插件文件夹复制到你的 Obsidian 库目录下的 .obsidian/plugins/obsidian-wolai-sync/
3. 重启 Obsidian
4. 在 Obsidian 设置 → 社区插件中启用 "Wolai Sync" 插件

方法二：开发者安装

1. 克隆或下载此仓库
2. 在项目目录中运行 npm install 安装依赖
3. 运行 npm run build 构建插件
4. 将生成的 main.js、manifest.json、styles.css 复制到 .obsidian/plugins/obsidian-wolai-sync/

🎯 适用场景

理想使用场景

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

Wolai 数据库要求

你的 Wolai 数据库必须包含以下字段：

字段名	类型	必需	说明
标题	文本	✅	对应 Obsidian 文件的标题
同步状态	单选	✅	值包括：Synced, Pending

同步状态字段的选项设置:

• Synced: 已成功同步
• Pending: 等待同步

⚙️ 配置说明

1. Wolai API 设置

首先需要在 Wolai 开发者中心 创建应用：

1. 访问 Wolai 开发者中心
2. 创建新应用
3. 获取 App ID 和 App Secret
4. 将应用连接到你的 Wolai 工作区

在插件设置中填入：

• 数据库 ID: 从 Wolai 数据库 URL 中获取（如 https://www.wolai.com/your-workspace/database-id 中的 database-id）
• App ID: 从开发者中心获取的应用 ID
• App Secret: 从开发者中心获取的应用密钥

2. Obsidian 设置

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

3. 同步设置

• 启用文件监听器: 默认关闭，开启后会自动监听文件变化
• 自动同步: 定时自动同步功能
• 同步间隔: 自动同步的时间间隔（5-120分钟）

🚀 使用方法

Obsidian → Wolai 同步

方法一：手动同步（推荐）

1. 在同步文件夹中创建或编辑 Markdown 文件
2. 使用命令面板（Ctrl/Cmd + P）搜索 "Wolai"
3. 选择以下命令之一：
   • "同步当前文件到 Wolai": 仅同步当前打开的文件
   • "同步所有文件到 Wolai": 同步所有待同步的文件
4. 插件会自动为文件添加 FrontMatter 并设置同步状态

方法二：文件监听（可选）

1. 在插件设置中启用 "文件监听器"
2. 文件修改保存后会自动标记为需要同步
3. 定期手动触发同步或启用自动同步

Wolai → Obsidian 同步

1. 在 Wolai 数据库中找到要同步的行
2. 将该行的 "同步状态" 字段设置为 "Wait For Syncing"
3. 在 Obsidian 中使用命令 "从 Wolai 同步到 Obsidian"
4. 插件会自动创建或更新对应的 Obsidian 文件

同步状态说明

插件通过文件的 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 API 调用限制

基于 Wolai OpenAPI 的以下限制，我们采用了手动同步的设计：

1. 频率限制

• Wolai API 对调用频率有严格限制
• 过于频繁的自动同步可能导致 API 调用被限制
• 手动触发可以精确控制同步时机

2. 批量限制

• 创建块: 单次最多创建 20 个块
• 插入数据: 单次最多插入 20 行数据
• 分页查询: 单次最多返回 200 条记录

3. Token 管理

• API Token 需要定期刷新
• 不当的频繁调用可能导致认证失败
• 手动同步降低了 Token 管理的复杂性

4. 成本考虑

• API 调用可能产生费用（根据 Wolai 的定价策略）
• 避免不必要的自动同步可以控制成本
• 用户可以选择性地同步重要内容

设计优势

1. 精确控制: 用户完全掌控何时同步什么内容
2. 避免冲突: 减少同时编辑导致的同步冲突
3. 节省配额: 避免浪费 API 调用次数
4. 稳定可靠: 减少因网络问题导致的同步失败
5. 调试友好: 便于排查同步问题和错误

📊 API 使用统计

插件内置 API 调用统计功能：

• 今日调用: 显示当天的 API 调用次数
• 总调用数: 显示累计 API 调用次数
• 重置功能: 可以手动重置统计数据
• 实时更新: 每次 API 调用后自动更新计数

建议将每日 API 调用控制在合理范围内，避免超出 Wolai 的限制。

🛠️ 支持的 Markdown 语法

文本格式

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

块级元素

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

富文本混合

支持在同一段落中混合多种格式：

这是一个包含 **粗体**、*斜体*、`代码` 和 [链接](https://example.com) 的段落。

❗ 注意事项

1. 数据备份: 同步前请确保重要数据已备份
2. 网络连接: 确保网络连接稳定，避免同步中断
3. 配置检查: 首次使用前请使用 "测试连接" 功能验证配置
4. 文件格式: 确保文件是标准的 Markdown 格式
5. 权限设置: 确保 Wolai 应用有访问目标数据库的权限
6. 并发编辑: 避免在同步过程中同时编辑文件
7. 特殊字符: 某些特殊字符可能需要转义处理

🐛 故障排除

常见问题

1. 连接失败

• 检查 App ID 和 App Secret 是否正确
• 确认应用已连接到 Wolai 工作区
• 验证网络连接是否正常

2. 同步失败

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

3. 重复同步

• 检查文件的 sync_status 字段值
• 确认 Wolai 数据库中的同步状态设置
• 重置 API 统计后重新尝试

4. 格式问题

• 确保 Markdown 文件格式标准
• 检查特殊字符是否正确转义
• 验证文件编码为 UTF-8

获取帮助

如果遇到问题：

1. 查看 Obsidian 控制台的详细错误信息
2. 检查插件设置是否正确配置
3. 尝试使用 "测试连接" 功能
4. 查看 Wolai API 文档 获取最新信息

📄 许可证

本项目使用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个插件！

---

开发者: Li Wei
主页: https://marsway.red
版本: 1.0.0
兼容性: Obsidian 0.15.0+