# ObShare - Obsidian 飞书云文档同步分享插件

> 🚀 **一次配置，轻松使用** - 基于飞书云文档的 Obsidian 笔记同步与分享方案

[中文](README.md)|[English](README-EN.md)

[![Version](https://img.shields.io/badge/version-1.2.1-blue.svg)](https://github.com/your-repo/ob-share)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Obsidian](https://img.shields.io/badge/Obsidian-1.9.12+-purple.svg)](https://obsidian.md/)


## 👀版本更新进度
1.2.1(2602)
- 优化代码规范性，提升代码性能
- 修复已知 bug，改善用户体验
- 修复图片尺寸在上传时候可能无法正常识别，导致比例失调的问题

1.2.0(2601)
- 设置界面优化，功能分区更加合理
- 新增双链模式，支持将所有双链子文档一并上传
- 优化图片上传体验，修复粘贴图片无法正常上传的问题
- 新增 mermaid 语法适配，优化 mermaid 不可识别或者显示异常
- 优化代码规范和精简性，以满足 Obsidian 官方插件审核要求
- 新增 yaml 适配
- 新增对 SVG 格式图片适配
- 新增审查日志（debug 模式），上传过程全程可审计

## ✨ 核心特性

### 🔒 隐私安全第一
- **🛡️ 本地加密存储** - 所有敏感配置信息（App ID、App Secret、用户ID等）均采用 AES-GCM 256位加密算法本地存储
- **🔐 零数据收集** - 插件不收集、不分析、不共享任何用户数据，所有处理均在本地完成
- **👁️ 完全透明** - 开源代码，可审计，无监控、无追踪、无广告
- **🚫 无网络监听** - 仅在用户主动操作时才与飞书API通信

### 🎯 一键分享体验
- **📤 一键上传** - 右键菜单或命令面板快速分享当前文档成为飞书云文档
- **🎨 智能转换** - 自动转换 Obsidian 多种格式
- **🖼️ 图片处理** - 自动上传并转换本地图片链接
- **⚙️ 权限控制** - 灵活设置文档公开性、复制权限等

### 📊 便捷管理
- **📋 上传历史** - 完整的上传记录，支持重新设置权限
- **🔄 进度显示** - 实时上传进度条，清晰了解处理状态
- **📈 使用统计** - API调用次数统计，合理控制使用频率

## 🚀 快速开始

### 第一步：安装插件

1. 在 Obsidian 中打开 `设置` → `第三方插件`
2. 关闭 `安全模式`
3. 点击 `浏览` 搜索 "ObShare" 并安装
4. 启用插件

或者，您可以通过github下载本插件 ——> release最新版本
然后将文件解压到您的Obsidian库所在文件夹——>.obsidian 文件夹 ——> plugins 文件夹

### 第二步：配置飞书应用（仅需一次）

> ⏱️ **预计配置时间：5-10分钟**

#### 📋 准备清单
- [ ] 飞书账号
- [ ] 创建飞书应用
- [ ] 获取应用凭证
- [ ] 创建目标文件夹

#### 🔧 详细配置步骤

**完整配置指南：** 请查阅 [快速配置您的ObShare](https://itlueqqx8t.feishu.cn/docx/XUJmdxbf7octOFx3Vt0c3KJ3nWe)

1. **创建飞书应用**
   - 访问 [飞书开放平台](https://open.feishu.cn/)
   - 创建企业自建应用
   - 获取 `App ID` 和 `App Secret`

2. **配置应用权限**
   - 添加云文档相关权限
     
3. **获取必要信息**
   - 📱 **用户ID**：您的飞书用户标识
   - 📁 **文件夹Token**：目标上传文件夹的标识

#### ⚠️ 用户 ID 格式说明

请确保使用正确的 `user_id` 格式：

| ID 类型 | 格式示例 | 是否正确 |
|--------|---------|---------|
| `user_id` | `abc1234` | ✅ 正确 |
| `open_id` | `ou_xxxxxx` | ❌ 错误 |
| `union_id` | `on_xxxxxx` | ❌ 错误 |


#### ⚠️ 文件夹权限配置（必须）

除了配置应用 API 权限外，**还需要将目标文件夹共享给应用机器人**，否则测试连接成功但上传时会报 403 错误：

1. 在飞书开放平台 → **应用功能** → **机器人** → 启用机器人功能
2. 确保应用已**创建版本并发布上线**
3. 打开飞书客户端 → 云文档 → 找到你配置的目标文件夹
4. 右键文件夹 → **协作者** 或 **共享**
5. 搜索并添加你的**应用名称**（会显示为机器人图标）
6. 权限选择 **可编辑**

> 💡 如果跳过此步骤，会出现 403 错误（错误码 1061004：当前调用身份没有文件夹的编辑权限）

4. **插件配置**
   - 打开 Obsidian 设置 → ObShare
   - 填入上述四项必需信息
   - 点击 "测试连接" 验证配置

### 第三步：开始使用

#### 🎯 三种上传方式

1. **命令面板**：`Ctrl/Cmd + P` → 搜索 "分享当前文档到飞书"
2. **右键菜单**：在文件列表中右键 → "分享该页面"
3. **工具栏按钮**：点击左侧工具栏的分享图标
<img width="172" height="76" alt="490f534d-b252-45bb-aed1-268df370511a" src="https://github.com/user-attachments/assets/444b543b-f1ee-4633-96d9-86215ab19eaf" />
<img width="597" height="332" alt="359285e9-8279-4a67-8359-bc395703964a" src="https://github.com/user-attachments/assets/c50fc22f-9e09-49be-bc84-6529560f5764" />


#### ⚙️ 权限设置
上传完成后，可以一键轻松完成设置文档权限：
- **🌐 公开访问**：允许任何人通过链接访问
- **📋 允许复制**：允许查看者复制内容
- **📄 允许下载**：允许创建副本、打印、下载
<img width="564" height="510" alt="6b129536-f084-4887-86e9-4b1bbb0c5610" src="https://github.com/user-attachments/assets/9af947b6-dcf8-4d72-b908-cda0cef8fd62" />


#### 🖼️ 图片自动处理
- 自动上传本地图片到飞书
- 转换图片链接为飞书格式
- 支持多种图片格式

#### 📊 使用统计
- 实时显示本月API调用次数
- 上传文档数量统计
- 帮助合理控制使用频率
- 您可以在Obsidian设置页面查看所有上传记录，并直接在此管理您的文档
<img width="819" height="533" alt="b7f957a2-0c33-405a-95f9-ba61459818e6" src="https://github.com/user-attachments/assets/81f2f411-49f9-4211-a807-f6e39c00562d" />


## 🛡️ 安全与隐私

### 🔐 数据加密

- **加密算法**：AES-GCM 256位
- **密钥生成**：基于设备特征生成固定密钥
- **加密范围**：App ID、App Secret、文件夹Token、用户ID
- **存储位置**：仅在本地 `data.json` 文件中

### 🔒 数据流向

```
您的设备 ←→ 飞书API
     ↑
   仅此路径
```
**数据仅在您的设备与飞书之间传输，不经过任何第三方服务器。**

## 📋 系统要求
- **Obsidian**：1.9.12 或更高版本
- **平台**：Windows、macOS、Linux
- **网络**：需要访问飞书API（open.feishu.cn）

## 🆘 常见问题

### Q: 配置后无法上传？
**A:** 请检查：
1. 网络连接是否正常
2. 飞书应用权限是否正确配置
3. 用户ID和文件夹Token是否正确
4. 点击"测试连接"验证配置

### Q: 测试连接成功，但上传时报 403 错误？
**A:** 这是最常见的问题，通常是因为**目标文件夹没有共享给应用机器人**。请按以下步骤操作：
1. 在飞书开放平台启用应用的**机器人功能**
2. 确保应用已**发布上线**
3. 在飞书云文档中，将目标文件夹**共享给应用**（搜索应用名称，设置为可编辑权限）

另外请检查用户ID格式是否正确：应使用 `user_id` 格式（如 `abc1234`），而不是 `open_id`（以 `ou_` 开头）或 `union_id`（以 `on_` 开头）。

### Q: 上传的文档格式有问题？
**A:** 插件会自动转换主流格式，部分复杂格式或非标准Markdown文档可能需要手动调整。若您在使用中遇到问题，或者希望我们在迭代版本中专项优化，恳请你填写我们的问卷[用户体验问卷](https://f.wps.cn/g/DLUqR4jB)。

### Q: 如何删除已上传的文档？
**A:** 在插件设置的"上传历史"中可以删除，该操作会同步删除您的上传记录和飞书侧的云文档，但不会影响您本地的Obsidian文档。

### Q: 担心数据安全？
**A:** 插件完全开源，您可以审查代码。所有敏感信息都经过加密存储，不会上传到任何第三方服务器。

### Q: 本插件是否会收集我的数据
**A:** 完全不会，本插件的原理是使用您自己的飞书api接口，在本地为您转换格式、调用飞书api接口、上传到飞书服务器，一切行为均由您自行掌握，不涉及第三方服务器。

### Q: 我可以把所有内容都上传到飞书云文档吗?
**A:** 考虑到飞书空间和API调用量的限制，插件暂不支持批量上传，此外，若您开启互联网公开文档功能，你需要遵守飞书的管理规定，该功能开启后，互联网上获得链接的人都能够访问该文档。您作为文档所有者，需对其合法合规性负责，任何由此产生的纠纷与本插件无关。

## 🤝 贡献
欢迎提交 Issue 和 Pull Request！

## 📄 许可证
本项目采用 [MIT 许可证](LICENSE)。

## 🙏 致谢
- [Obsidian](https://obsidian.md/) - 最优秀的笔记软件
- [飞书开放平台](https://open.feishu.cn/) - 提供API能力，以及非常清晰易懂的文档
- 所有贡献者和用户的支持

---

**🔗 相关链接**
- [配置指南](https://itlueqqx8t.feishu.cn/docx/XUJmdxbf7octOFx3Vt0c3KJ3nWe)
- [用户体验问卷](https://f.wps.cn/g/DLUqR4jB)
**💡 如果这个插件对您有帮助，请给我们一个 ⭐ Star！**