bookmark_checker

检查浏览器导出的 HTML 书签文件，批量识别失效链接、超时链接和可能被网站拦截的链接。

当前项目已重构为标准 Python CLI 工具，核心逻辑和命令行入口分离，后续继续做桌面版或插件版时可以复用核心模块。

项目结构

src/bookmark_checker/
  cli.py
  comparison.py
  config.py
  models.py
  parser.py
  checker.py
  reporter.py

职责划分：

• cli.py: 命令行入口和退出码
• parser.py: 书签 HTML 解析和域名过滤
• checker.py: 链接检查、状态分类、重试、并发
• comparison.py: 两次检查结果对比
• reporter.py: CSV/JSON 输出和摘要
• models.py: 领域模型

安装

要求：

• Python 3.10+
• uv 或 pip

推荐使用 uv：

uv venv .venv
uv pip install -r requirements.txt

或直接：

uv pip install -e .

CLI 用法

安装后可用命令：

bookmark-checker check /path/to/bookmarks.html

也可以用模块方式运行：

python -m bookmark_checker check /path/to/bookmarks.html

常用示例：

bookmark-checker check /path/to/bookmarks.html \
  --format html \
  --output report.html \
  --workers 30 \
  --timeout 8 \
  --retries 2 \
  --proxy socks5://127.0.0.1:7891 \
  --only-problems \
  --verbose

生成 JSON 结果，便于后续做 diff：

bookmark-checker check /path/to/bookmarks.html \
  --format json \
  --output result.json

只检查某些域名：

bookmark-checker check /path/to/bookmarks.html \
  --include-domain github.com \
  --include-domain openai.com

排除某些域名：

bookmark-checker check /path/to/bookmarks.html \
  --exclude-domain localhost \
  --exclude-domain internal.example.com

对比两次结果：

bookmark-checker diff previous.json current.json

输出 JSON 差异数据：

bookmark-checker diff previous.json current.json \
  --format json \
  --output diff.json

输出格式

支持：

• csv
• json
• html

默认输出文件：

• bookmark_check_results.csv
• bookmark_check_results.json
• bookmark_check_results.html

diff 默认输出：

• bookmark_check_diff.html

输出字段：

• title
• url
• status
• status_code
• detail
• final_url
• is_problem
• is_uncertain

HTML 报告包含：

• 顶部摘要卡片
• 状态统计
• 可筛查的大表格
• 面向人工查看的可读布局

diff 报告包含：

• 旧结果与新结果汇总
• 新增、移除、变化、未变化数量
• 回归数量和恢复数量
• 逐条变化明细

状态说明

• ok: 访问成功
• blocked: 返回 401/403，通常是站点拦截脚本或要求登录
• client_error: 4xx 错误
• server_error: 5xx 错误
• timeout: 请求超时
• connection_error: 连接失败
• ssl_error: TLS/证书异常
• invalid_url: URL 格式错误
• too_many_redirects: 重定向过多
• request_error: 其他请求异常
• skipped_unsupported_scheme: mailto:、javascript: 等未检查链接

退出码：

• 0: 没有明确异常
• 1: 存在明确异常链接
• 2: 参数错误或输入文件错误

diff 退出码：

• 0: 没有回归
• 1: 检测到回归
• 2: 结果文件错误或参数错误

推荐工作流

第一次生成基线：

bookmark-checker check bookmarks.html --format json --output baseline.json

下一次检查：

bookmark-checker check bookmarks.html --format json --output latest.json

生成差异报告：

bookmark-checker diff baseline.json latest.json --format html --output diff.html

测试

先安装项目：

uv pip install -e .

再运行：

python -m unittest discover -s tests