浏览器书签同步管理工具

一个轻量级 Windows 桌面工具，解决「多浏览器书签不同步、书签积累混乱、失效链接无人清理」的问题。它能直接读写本机各浏览器本地书签文件，一键把多个浏览器书签合并去重、保持一致；还能把书签导出成 JSON 配置表交办公智能体 AI 帮忙整理，整理完再导回；并支持批量检测书签链接是否存活。

一、功能特性

1. 多浏览器一键同步

• 自动探测本机已安装的浏览器（含多 Profile），读取各自书签。
• 按网址去重合并成同一份「全集」，一键写回所有浏览器，让各浏览器书签保持一致。
• 写回前自动备份原书签文件到 backups/时间戳/，误操作可找回。

2. 导出给 AI 整理（工具本身不内置 AI）

• 一键导出书签为统一的 JSON 配置表 + 一段提示词（整理说明_prompt.txt）。
• 用户拿着这个「结果物」去办公智能体 AI 帮忙整理：去重、归类建子文件夹、删失效、推荐新网址。
• AI 返回的同格式 JSON 可导回工具，再写回浏览器，形成「导出 AI 整理 导回」的闭环。

3. 链接存活检测

• 勾选要检测的书签，异步并发批量请求，把结果归类为：正常 / 重定向 / 已失效(404) / 服务端错误 / 超时 / DNS 失败 / SSL 错误 / 无法连接。

4. 自定义书签源

• 内置豆包、腾讯 ima、通义千问等 Chromium 系套壳浏览器的目录名映射。
• 也支持手动输入任意浏览器的 Bookmarks 文件路径（或 sqlite、收藏夹文件夹），纳入同步与导出。

二、支持的浏览器

探测采用统一模式 %LOCALAPPDATA%\<目录>\User Data\<Profile>\Bookmarks，用户名通过环境变量动态解析；新增品牌只需在 discover.py 的目录名映射里加一行。

三、技术栈

核心设计

• 统一书签树模型（models.py）：Node 只有 folder / url 两种类型，所有浏览器格式都先归一化成这套模型，上层同步、导出、检测只面向统一模型。
• 适配器层（adapters/）：chromium.py（Bookmarks JSON）、firefox.py（places.sqlite）、folder.py（收藏夹目录）。
• 精确复现 Chromium checksum：写回 Bookmarks 时必须按 Chromium 的「流式 MD5」重算顶层 checksum（深度优先遍历，按 id + name(UTF-16LE) + type + url 累加），否则浏览器会判定文件被外部修改。

四、项目结构

浏览器书签工具/
 src/bkmgr/
    main.py            # 入口（native 启动 + WebView2 检测 fallback）
    ui.py              # NiceGUI 界面（工作台：同步/导出/导入/检测）
    models.py          # 统一书签树模型 Node
    adapters/          # 浏览器适配层
       base.py        #   BookmarkSource 与读写门面
       chromium.py    #   Chromium Bookmarks JSON 读写（含 checksum）
       firefox.py     #   Firefox places.sqlite 读取
       folder.py      #   收藏夹文件夹读写
    discover.py        # 内置浏览器自动探测
    config.py          # 自定义书签源持久化（config.json）
    sync.py            # 合并去重 + 备份 + 写回
    export_import.py   # 中间 JSON 导出与导入
    prompts.py         # 交 AI 的提示词模板
    link_check.py      # 链接存活并发检测
    ...                # logging_setup / dialogs / resources 等
 tests/                 # 单元测试（sync / chromium / export）
 assets/                # 图标等资源
 pyproject.toml         # 项目与依赖声明
 dist/BookmarkSync/     # 打包产物（exe + _internal）

五、应用场景

1. 多浏览器书签割裂：工作用 Chrome、生活用 Edge、又装了豆包/千问等 AI 浏览器，书签各存各的、重复且不同步——用「一键同步」合并去重，全部对齐成同一套。
2. 书签越积越乱：书签栏塞了几百上千条、分类混乱——导出 JSON 交办公智能体 AI 自动归类、去重、建子文件夹，整理结果一键导回，不用自己手动拖拽。
3. 失效链接清理：收藏夹里一堆打不开的旧网址——勾选后批量检测存活，快速定位失效书签。
4. 浏览器迁移 / 备份：换浏览器或重装系统前，把书签合并导出成一份标准结构，安全迁移或归档。
5. 不想配 API Key：工具本身不内置 AI、不要求用户配置密钥，只通过「JSON 结果物 + 提示词」做外部交互，把 AI 能力留给用户已有的办公智能体。

六、快速开始

使用（普通用户）

1. 双击 dist/BookmarkSync/BookmarkSync.exe。
2. 左侧自动列出检测到的各浏览器及书签数，勾选要参与同步的浏览器。
3. 点「一键同步」——读取、合并、去重、自动备份、写回，多浏览器书签即刻一致。
4. 「导出给 AI」产出一份 bookmarks.json + 整理说明_prompt.txt，拿去给办公智能体 AI 整理；整理完在「导入回写」页选回该 JSON 写回。
5. 「链接检测」页勾选书签批量检测存活。

分发时请连同 BookmarkSync.exe 同级的 _internal 文件夹一起打包（整个 BookmarkSync 目录一起压缩/复制即可）。

开发

# 首次：确保 uv 环境（脚本会自动安装 uv / Python / 配置镜像）
python python-dev/scripts/py/ensure_uv_env.py

# 同步依赖（若已锁定 Python 版本则直接执行）
uv sync

# 运行（native 独立窗口；APP_NATIVE=0 走浏览器模式）
uv run bkmgr

# 质量检查
uv run ruff check src/
uv run mypy src/
uv run pytest

# 打包（onedir + windowed）
uv run pyinstaller --noconfirm --clean --windowed --onedir --name BookmarkSync \
  --add-data "<venv>/Lib/site-packages/nicegui;nicegui" \
  --add-data "assets;assets" --icon assets/app-icon.png src/bkmgr/main.py

七、技术要点与避坑记录

• Chromium checksum：Bookmarks 顶层 checksum 是「深度优先遍历所有节点做流式 MD5」的结果，且依赖每个节点的 id 字段（根固定 1/2/3，普通节点从 4 递增）。写回时重算并同步更新 Bookmarks.bak，避免浏览器回退或重置。
• 环境变量劫持：在自带 conda/Python 的办公智能体宿主里，UV_PYTHON/PYTHONHOME 会被注入、把 uv 和 Python 静默劫持到宿主 Python，导致打包漏收 libffi-8.dll、双击报 DLL load failed。构建脚本已内置清除这些变量。
• WebView2 依赖：native 模式底层是 pywebview，依赖系统 WebView2 注册表。注册表缺失时会回退 IE 内核导致界面白屏，因此启动时检测 WebView2，不可用则自动切浏览器模式。
• 书签文件占用：写回前若浏览器正在运行，书签文件可能被锁定或被内存缓存覆盖，建议同步前先关闭浏览器（写回本身会自动备份）。

八、许可与说明

本项目为个人/内部工具用途，书签数据全程保存在本机，不做任何云端上传。导出的 JSON 结果物仅用于交给用户自行选择的 AI 智能体整理，不通过本工具外发任何数据。