243 lines
8.2 KiB
Markdown
243 lines
8.2 KiB
Markdown
# 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 开发者中心](https://www.wolai.com/developers) 创建应用：
|
||
|
||
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 管理同步状态：
|
||
|
||
```yaml
|
||
---
|
||
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 语法
|
||
|
||
### 文本格式
|
||
- **粗体文本**: `**粗体**` 或 `__粗体__`
|
||
- *斜体文本*: `*斜体*` 或 `_斜体_`
|
||
- `行内代码`: `` `代码` ``
|
||
- ~~删除线~~: `~~删除线~~`
|
||
- [链接](https://example.com): `[链接文本](URL)`
|
||
|
||
### 块级元素
|
||
- 标题: `#` 到 `######`
|
||
- 无序列表: `- 项目` 或 `* 项目`
|
||
- 有序列表: `1. 项目`
|
||
- 代码块: ````代码块````
|
||
- 引用: `> 引用内容`
|
||
- 分割线: `---` 或 `***`
|
||
|
||
### 富文本混合
|
||
支持在同一段落中混合多种格式：
|
||
```markdown
|
||
这是一个包含 **粗体**、*斜体*、`代码` 和 [链接](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 文档](https://www.wolai.com/developers) 获取最新信息
|
||
|
||
## 📄 许可证
|
||
|
||
本项目使用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request 来改进这个插件！
|
||
|
||
---
|
||
|
||
**开发者**: Li Wei
|
||
**主页**: https://marsway.red
|
||
**版本**: 1.0.0
|
||
**兼容性**: Obsidian 0.15.0+
|