书签管理工具集 - 综合使用手册 (v2.1)

欢迎使用本套书签管理工具集！这里提供了多个独立的Python脚本，旨在解决您在书签管理中遇到的各种问题，包括去重、比较、格式转换等。

目录

1. 环境要求与快速开始
2. 功能一：书签去重
   • 2.1 deduplicate_bookmarks_健壮版2.py (推荐)
   • 2.2 deduplicate_bookmarks_健壮版1.py
   • 2.3 批量书签去重.py
   • 2.4 版本区别总结 (表格)
3. 功能二：书签比较
   • 3.1 compare_multi_bookmarks-健壮正则表达式版.py (推荐)
   • 3.2 compare_bookmarks-健壮正则表达式版.py
   • 3.3 compare_multi_bookmarks.py
   • 3.4 compare_bookmarks.py
   • 3.5 compare_multi_bookmarks_流式解析.py
   • 3.6 compare_bookmarks_流式解析.py
   • 3.7 版本区别总结 (表格)
4. 功能三：格式转换 (JSON -> HTML)
   • 4.1 批量书签json转换书签html.py (推荐)
   • 4.2 书签json转换书签html.py
   • 4.3 版本区别总结 (表格)
5. 通用注意事项

---

1. 环境要求与快速开始

1. Python 版本: 推荐使用 Python 3.7+。

2. 依赖库:

   • 推荐的脚本 (文件名中包含 健壮, 批量, 流式解析) 无需任何第三方库。
   • 部分备用脚本（文件名含 bs4 的比较脚本）依赖 BeautifulSoup4 和 lxml。如需使用，请先安装：

     pip install beautifulsoup4 lxml

3. 操作步骤:

   • 将所有脚本文件和您的书签文件放在同一个文件夹内。
   • 打开命令行工具 (CMD, PowerShell, Terminal)。
   • 使用 cd 命令进入该文件夹。
   • 参考下文的具体说明，运行您需要的命令。

---

2. 功能一：书签去重

2.1 deduplicate_bookmarks_健壮版3.py (推荐)

• 功能: 精确查找并移除单个HTML书签文件内的重复项。使用正则表达式，性能高，零依赖。
• 解码逻辑:
  • 标题：始终进行HTML实体解码 (& -> &)。
  • URL：始终进行HTML实体解码 (& -> &)。仅在启用 -d 开关时，才进行百分号解码。
• 用法: python "deduplicate_bookmarks_健壮版3.py" [文件名] [选项...]
• 高级选项详解:
  • -m, --mode [url|url-title]: 去重模式 (默认: url)
    • url: 只根据链接地址（URL）判断重复。这是最常用的模式。
    • url-title: 严格模式，URL和标题必须都相同才算作重复。
  • -d, --decode: 启用URL解码
    • 启用后，会先对URL进行解码（处理%20等）再比较，能找出编码不同的“隐形”重复项。
  • --strict-protocol: 严格区分协议
    • 启用后，http://example.com 和 https://example.com 将被视为不同的书签。默认不启用（视为相同）。
  • --ignore-slash: 忽略URL末尾的斜杠
    • 启用后，example.com/page 和 example.com/page/ 被视为相同。默认不启用（视为不同）。

2.1 deduplicate_bookmarks_健壮版2.py

• 功能: 精确查找并移除单个HTML书签文件内的重复项。使用正则表达式，性能高，零依赖。
• 解码逻辑:
  • 标题：始终进行HTML实体解码 (& -> &)。
  • URL：仅在启用 -d 开关时，才进行HTML实体和百分号解码。
• 用法: python "deduplicate_bookmarks_健壮版2.py" [文件名] [选项...]
• 高级选项详解:
  • -m, --mode [url|url-title]: 去重模式 (默认: url)
    • url: 只根据链接地址（URL）判断重复。这是最常用的模式。
    • url-title: 严格模式，URL和标题必须都相同才算作重复。
  • -d, --decode: 启用URL解码
    • 启用后，会先对URL进行解码（处理%20和&等）再比较，能找出编码不同的“隐形”重复项。
  • --strict-protocol: 严格区分协议
    • 启用后，http://example.com 和 https://example.com 将被视为不同的书签。默认不启用（视为相同）。
  • --ignore-slash: 忽略URL末尾的斜杠
    • 启用后，example.com/page 和 example.com/page/ 被视为相同。默认不启用（视为不同）。

2.2 deduplicate_bookmarks_健壮版1.py

• 功能: 与 健壮版2 或健壮版3基本相同，也是基于正则表达式的高性能去重工具。
• 解码逻辑 (关键区别):
  • 标题和URL：在启用 -d 开关时，会同时对URL和标题进行解码。如果-d关闭，则都不解码。
• 用法: 与 健壮版2 或健壮版3完全相同。
• 高级选项详解: 与 健壮版2 或健壮版3完全相同。

2.3 批量书签去重.py

• 功能: “指挥官”脚本，用于自动化地对多个HTML书签文件执行去重操作。它会调用您指定的去重脚本。
• 用法: python "批量书签去重.py" [要去重的脚本名] [文件/目录...] [选项...]
• 高级选项详解:
  • script: 要调用的去重脚本路径。必须是第一个参数，例如 "deduplicate_bookmarks_健壮版2.py"。
  • targets: 一个或多个目标路径。可以是具体的文件名，也可以是目录。
  • -bm, --batch-mode [url|url-title|all]: 批量执行模式 (默认: all)
    • url: 对每个文件只运行 'url' 模式去重。
    • url-title: 对每个文件只运行 'url-title' 模式去重。
    • all: 对每个文件依次运行以上两种模式。
  • 参数传递: 所有去重选项 (-d, --strict-protocol, --ignore-slash) 都会被自动传递给其调用的核心去重脚本。

2.4 版本区别总结 (表格)

脚本名	主要技术	解码逻辑区别	优点	推荐度
deduplicate_bookmarks_健壮版3.py（推荐）	正则	标题和URL始终解码，URL按需百分号解码，更精确	逻辑最严谨，性能高，零依赖（虽然更推荐这个，但是还是按你的实际需求选择健壮版1还是健壮版2还是健壮版3）	最高
deduplicate_bookmarks_健壮版2.py	正则	标题始终解码，URL按需解码，更精确	逻辑严谨，性能高，零依赖	高
deduplicate_bookmarks_健壮版1.py	正则	标题和URL的解码绑定在同一个-d开关上	性能高，零依赖	次选
批量书签去重.py	调度器	(不直接处理) 调用其他脚本	自动化处理，极大提升效率	必用

---

3. 功能二：书签比较分析

核心功能区别:

• compare_bookmarks (双文件版): 生成一份详尽的差异报告，清晰列出文件A比文件B多什么，文件B比文件A多什么（包括书签和文件夹）。
• compare_multi_bookmarks (多文件版): 生成一份分析报告，找出所有文件共有的交集，或每个文件独有的项（包括书签和文件夹）。

3.1 compare_multi_bookmarks_健壮正则表达式版.py (推荐)

• 功能: 比较两个或多个HTML书签文件，找出它们的交集或独有项。报告会分别列出书签和文件夹的分析结果。使用正则表达式，性能高，零依赖。
• 用法: python "compare_multi_bookmarks-健壮正则表达式版.py" [文件1] [文件2] ... [选项...]
• 高级选项详解:
  • -a, --analysis [intersection|unique]: 分析模式 (默认: unique)
    • unique: 找出每个文件中独有的书签和文件夹。
    • intersection: 找出在所有文件中都存在的共同书签和文件夹。
  • -c, --compare-mode [url|url-title]: 比较模式 (默认: url)
    • url: 只根据链接地址（URL）比较书签。
    • url-title: URL和标题必须都相同才视为一样。
  • -f, --filter: 启用协议过滤
    • 启用后，只分析 http, https, ftp 协议的链接。
  • -d, --decode: 启用URL解码
    • 启用后，会先对URL进行解码再比较。

3.2 compare_bookmarks_健壮正则表达式版.py

• 功能: 仅限比较两个文件，生成一份详细的差异报告，列出文件A相对文件B、文件B相对文件A缺失的书签和文件夹。
• 用法: python "compare_bookmarks-健壮正则表达式版.py" [文件1] [文件2] [选项...]
• 高级选项详解: 与 multi 版基本相同，但不包含 -a (分析模式)，因为其功能固定为生成差异报告。

3.3 compare_multi_bookmarks_bs4.py

• 功能: multi 正则版的备用方案，使用 BeautifulSoup 库进行解析。
• 用法与选项: 与 multi 正则版完全相同。

3.4 compare_bookmarks_bs4版.py

• 功能: 正则双文件版的备用方案，使用 BeautifulSoup 库解析。
• 用法与选项: 与正则双文件版完全相同。

3.5 compare_multi_bookmarks_流式解析.py

• 功能: multi 正则版的另一种备用方案，使用Python内置的 html.parser 进行流式解析。
• 用法与选项: 与 multi 正则版完全相同。

3.6 compare_bookmarks_流式解析.py

• 功能: 正则双文件版的另一种备用方案，使用 html.parser 流式解析。
• 用法与选项: 与正则双文件版完全相同。

3.7 版本区别总结 (表格)

脚本名	文件数量	主要技术	优点	缺点	推荐度
compare_multi..._健壮正则...	多个	正则	速度极快，零依赖，最推荐	理论上可能无法处理极端不规范的HTML	最高
compare_bookmarks_健壮正则...	仅两个	正则	速度快，零依赖，生成直观的A/B差异报告	功能相对单一	高
compare_multi..._流式解析.py	多个	html.parser	零依赖，内存效率高，速度快，对复杂HTML结构理论上更稳健	代码相对正则版更复杂	高
compare_bookmarks_流式解析.py	仅两个	html.parser	优点同上，生成A/B差异报告	功能相对单一	次选
compare_multi_bookmarks_bs4版.py	多个	BeautifulSoup (BS4)	容错性极强	需要依赖，处理大文件时慢且耗内存	备用
compare_bookmarks_bs4版.py	仅两个	BeautifulSoup (BS4)	容错性极强	功能单一，且有性能问题	备用

---

4. 功能三：格式转换 (JSON -> HTML)

4.1 批量书签json转换书签html.py (推荐)

• 功能: 将JSON格式书签，批量转换为通用的HTML格式，并根据书签数量智能命名。
• 用法: python "批量书签json转换书签html.py" [文件/模式...] [选项...]
• 高级选项详解:
  • input_patterns: 一个或多个输入文件/模式。可以使用通配符，如 *.json 或 backups/**/Bookmarks (需要引号)。
  • -o, --output-dir [DIRECTORY]: 指定输出目录
    • 指定一个统一的目录来存放所有转换后的HTML文件。如果未提供，则输出到原文件所在的目录。

4.2 书签json转换书签html.py

• 功能: 与批量版功能相同，但文件名处理逻辑不同（输出文件名与输入文件名挂钩）。
• 用法: 与批量版相同。
• 高级选项详解: 与批量版完全相同。

4.3 版本区别总结 (表格)

脚本名	核心区别（文件名处理）	推荐度
批量书签json转换书签html.py	根据书签数智能命名，自动处理冲突，推荐	最高
书签json转换书签html.py	输出文件名与输入文件名挂钩，不够智能	次选

---

5. 通用注意事项

• 备份为先: 在运行任何修改或生成文件的脚本前，强烈建议您备份原始的书签文件。
• 文件路径: 如果您的文件路径包含空格，请务必用双引号 " 将其括起来。
• 大文件处理: 当处理包含数万条书签的超大文件时：
  • 优先使用正则表达式版 (健壮版)，它们速度最快。
  • 如果必须使用 BeautifulSoup 版（如 compare_bookmarks_bs4版.py），请注意它会消耗大量内存并需要更长的处理时间，请确保您的电脑有足够资源并耐心等待。
• 理解解码 (-d): 解码选项非常强大，但请注意，它可能会将一些原本看起来不同的URL（如 example.com/a%20b 和 example.com/a b）视为相同。请根据您的具体需求决定是否启用。