Hoarder项目：Pocket导出格式变更及CSV导入适配分析

背景概述

Hoarder作为一个自托管的书签管理应用，原本支持从Pocket导入HTML格式的书签数据。然而近期Pocket对其导出功能进行了重大更新，导致Hoarder原有的导入机制需要进行相应调整。

Pocket导出机制变更详情

Pocket近期对其数据导出系统进行了重构，主要变更点包括：

1. 格式转换：从原有的HTML单文件导出改为发送包含CSV文件的ZIP压缩包
2. 容量限制解除：新版系统取消了5000条记录的上限，支持无限制导出
3. 分块机制：每个CSV文件包含最多10,000条记录，大容量账户会收到多个CSV文件
4. 邮件交付：用户请求导出后，系统会通过电子邮件发送数据文件

CSV文件格式解析

新的CSV导出文件具有以下技术特征：

• 字段结构：包含6个标准字段(title, url, time_added, cursor, tags, status)
• 特殊字符处理：
  • 字段内包含逗号时，整个字段会用双引号包裹
  • 标签(tags)字段使用竖线符号"|"作为分隔符
  • 支持Unicode字符(如德语变音符号äÄöÖüÜ)
  • 标签内允许包含空格
• 示例结构：

title,url,time_added,cursor,tags,status
"示例标题,含逗号","https://example.com/path,with,commas",1728576752,7187623980,标签1|标签2,unread
简单标题,https://simple.example.com,1728576752,7187623980,,read

技术适配方案

针对这一变更，Hoarder需要实现以下技术改进：

1. ZIP解压支持：增加对压缩包文件的处理能力
2. CSV解析器：开发专门的CSV解析模块，需特别注意：
   • 引号包裹字段的处理
   • 特殊分隔符的识别
   • 多文件合并逻辑
3. 标签系统适配：将管道分隔的标签转换为Hoarder的内部标签结构
4. 状态映射：将Pocket的unread/read状态转换为Hoarder的归档标志

实现建议

建议采用以下技术方案实现适配：

1. 使用成熟的CSV解析库(如Python的csv模块)处理基础解析
2. 对于特殊字符场景，实现自定义的字段清洗逻辑
3. 设计批量导入接口，支持中断恢复机制
4. 添加格式检测功能，自动识别HTML或CSV格式

用户影响与建议

对于终端用户，这一变更意味着：

• 大容量用户现在可以完整导出所有书签
• 导入过程需要等待邮件接收数据文件
• 可能需要更新客户端以支持新格式

建议用户在导入前：

1. 确认使用的Hoarder版本支持CSV导入
2. 检查收到的CSV文件编码是否正确
3. 考虑分批导入以降低系统负载

总结

Pocket导出机制的这次变更加强了数据可移植性，同时也对第三方应用提出了新的适配要求。Hoarder通过实现CSV导入支持，不仅解决了当前兼容性问题，还为未来处理其他来源的结构化数据打下了基础。这种演进体现了现代书签管理工具在数据交换标准化道路上的进步。