qingniao

青鸟 (Qingniao) - 书签同步助手

“青鸟不传云外信，丁香空结雨中愁。” —— 李璟

青鸟，神话中西王母的信使，专司传递消息。本项目取名「青鸟」，旨在成为你的知识信使，在浏览器与飞书多维表格之间，为你双向传递、永久归藏每一枚珍贵的书签。

核心特性

• 双向同步：支持将浏览器书签实时推送到飞书多维表格，也可一键将飞书中的整理结果同步回浏览器
• 自动字段创建：验证连接时自动检测并创建所需字段，无需手动配置表格结构
• 智能清理：自动删除飞书多维表格默认的示例数据
• 实时同步：后台监听书签变动（新增、修改、删除、移动），实时同步到飞书
• 多端兼容：基于 Manifest V3 标准开发，完美兼容 Chrome、Edge 等 Chromium 浏览器
• 智能冲突处理：当两端数据不一致时，默认以最后修改时间较新者为准，确保数据不丢失
• 极简体验：打开即用，一眼看懂，一键完成同步

安装说明

开发者模式安装

1. 下载或克隆本项目代码到本地
2. 打开 Chrome 或 Edge 浏览器，进入扩展管理页面（chrome://extensions/ 或 edge://extensions/）
3. 开启右上角的「开发者模式」
4. 点击「加载已解压的扩展程序」，选择本项目的 src 目录
5. 安装完成后，点击浏览器工具栏的 🧩 图标，将「青鸟」固定到工具栏

快速开始

第一步：创建飞书应用

1. 访问 飞书开放平台
2. 点击「创建企业自建应用」
3. 填写应用名称（如「青鸟同步」），选择应用类型为「企业自建应用」
4. 创建完成后，进入应用详情页，复制 App ID 和 App Secret

第二步：配置应用权限

1. 在应用详情页，点击左侧「权限管理」
2. 搜索并添加以下权限：
   • bitable:app（多维表格）
   • auth:user（获取用户身份）
3. 点击左侧「安全设置」
4. 在「重定向 URL」中添加：https://<扩展ID>.chromiumapp.org/（扩展安装后会自动生成）

第三步：配置扩展

1. 点击浏览器工具栏的「青鸟」图标，进入设置页
2. 填写飞书 App ID 和 App Secret
3. 点击「连接飞书账号」，完成授权
4. 点击「→ 创建新表格」跳转到飞书创建多维表格
5. 将表格 URL 粘贴到「多维表格 URL」输入框
6. 点击「验证连接」，系统会自动：
   • 检测并创建所需字段
   • 删除示例数据
   • 验证连接是否成功

第四步：开始同步

1. 配置完成后，点击「立即同步」完成首次全量同步
2. 后续书签变动会自动同步到飞书
3. 随时点击青鸟图标查看同步状态

多维表格字段结构

验证连接时会自动创建以下字段：

字段名	类型	说明
标题	文本	书签标题（默认第一列）
URL	超链接	书签链接
文件夹路径	文本	书签所在的文件夹路径
创建时间	数字	书签创建时间戳
最后修改时间	数字	最后修改时间戳
来源浏览器	单选	Chrome / Edge / Safari / Firefox / Opera / 其他
浏览器内部ID	文本	浏览器内部标识
同步状态	单选	正常 / 已删除

目录结构

qingniao/
├── README.md                          # 项目介绍与使用说明
├── CLAUDE.md                          # Claude Code 专用开发规范
├── CHANGELOG.md                       # 版本更新日志
├── src/                               # 扩展源代码
│   ├── manifest.json                  # 扩展配置文件
│   ├── background/                    # 后台服务脚本（监听书签变动）
│   ├── popup/                         # 弹出界面（主交互界面）
│   ├── options/                       # 设置界面（配置页）
│   ├── utils/                         # 工具函数（API 封装等）
│   │   ├── feishu.js                  # 飞书 API 封装
│   │   ├── sync.js                    # 同步核心逻辑
│   │   └── bookmarks.js               # 浏览器书签操作
│   └── assets/                        # 图标等静态资源
└── docs/                              # 文档

隐私说明

• 所有数据仅存储在本地浏览器和您自己的飞书多维表格中
• 不会上传任何数据到第三方服务器
• 飞书授权信息仅用于同步书签，不会用于其他用途

故障排除

连接失败

• 检查 App ID 和 App Secret 是否正确
• 确认已在飞书开放平台添加重定向 URL
• 确认已开启 bitable:app 权限

同步失败

• 检查网络连接是否正常
• 确认飞书多维表格 URL 格式正确
• 查看浏览器控制台（F12）获取详细错误信息

通知不显示

• 检查浏览器通知权限是否开启
• 检查操作系统通知设置

更新日志

详见 CHANGELOG.md

开发指南

本项目使用 Claude Code 作为主要开发辅助工具。

本地开发

1. 修改代码后，在扩展管理页面点击「重新加载」刷新扩展
2. 查看背景页日志：扩展详情页 → 背景页 → 查看控制台
3. 查看弹出页日志：右键点击青鸟图标 → 检查弹出内容

许可证

MIT License

---

青鸟 - 让你的书签触手可及，让知识永不丢失。

This site is open source. Improve this page.