feat(local): add PDF thumbnails on macOS

[flyingrtx2333]

Summary / 摘要

• Add an opt-in pdf_thumbnail setting to the Local driver. It is disabled by default.
• On macOS, render the first page of PDFs with the system Quick Look tool (/usr/bin/qlmanage).
• Reuse the Local driver's existing signed thumbnail URLs, concurrency limiter, image resize path, and disk cache.
• Keep PDF thumbnails unadvertised on unsupported platforms; existing image and video thumbnail behavior is unchanged.
• Propagate request cancellation to Quick Look and enforce a 30-second render timeout.

Operational notes:

• The existing thumbnail master switch must also be enabled.

• Rendering invokes the macOS Quick Look process for each cache miss; configuring thumb_cache_folder is recommended.

• Because PDF parsing consumes local resources, administrators should enable this selectively for untrusted or public storage.

• The setting is visible on all platforms but only advertises PDF thumbnail URLs on Darwin builds.

• This PR has breaking changes.
  / 此 PR 包含破坏性变更。

• This PR changes public API, config, storage format, or migration behavior.
  / 此 PR 修改了公开 API、配置、存储格式或迁移行为。

• This PR requires corresponding changes in related repositories.
  / 此 PR 需要关联仓库同步修改。

Related repository PRs / 关联仓库 PR:

• OpenList-Frontend: Not required; driver addition fields are rendered from backend metadata.
• OpenList-Docs: Not required for the initial implementation.

Testing / 测试

• go test ./...
  • The Local driver passes. The full command still fails on the current clean main baseline in unrelated packages, including Go 1.27 format-string vet failures in drivers/123, drivers/189, and drivers/189pc, plus an existing nil-pointer failure in drivers/onedrive_sharelink.
• Manual test / 手动测试:
  • GOTOOLCHAIN=local go test -race ./drivers/local — 8 tests passed.
  • GOTOOLCHAIN=local go vet ./drivers/local — passed.
  • CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go test -c ./drivers/local — produced a Linux ELF test binary.
  • CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go test -c ./drivers/local — produced a Windows PE test binary.
  • bash build.sh dev web followed by a native Darwin arm64 build — passed with the rolling frontend embedded.
  • Isolated end-to-end smoke test with a copied database and synthetic PDF: /api/fs/list returned a signed thumb; fetching it returned HTTP 200, Content-Type: image/png, valid PNG magic bytes, and one disk-cache entry.
  • The Darwin integration test creates a PDF with a Unicode/space-containing filename via cupsfilter, renders it with Quick Look, and decodes the output dimensions.

Checklist / 检查清单

• I have read CONTRIBUTING.
  / 我已阅读 CONTRIBUTING。
• I confirm this contribution follows the repository license, contribution policy, and code of conduct.
  / 我确认此贡献符合仓库许可证、贡献规范和行为准则。
• I have formatted the changed code with gofmt.
  / 我已使用 gofmt 格式化变更。
• I have requested review from relevant maintainers or code owners where applicable.
  / Draft 阶段暂未指定维护者审查。

AI Disclosure / AI 使用声明

• This PR includes AI-assisted content.
  / 此 PR 包含 AI 辅助内容。

Tools used / 使用工具:

• Codex

Usage scope / 使用范围:

• Code generation / 代码生成

• Refactoring / 重构

• Documentation / 文档

• Tests / 测试

• Review assistance / 审查辅助

• I have reviewed and validated all AI-assisted content included in this PR.
  / The human collaborator will review the draft before it is marked ready.

• I have ensured that all AI-assisted commits include Co-Authored-By attribution.
  / AI 辅助提交包含 Co-Authored-By 归属信息。

• I can reproduce all AI-assisted content included in this PR without any AI tools.
  / This remains for the human collaborator to confirm before marking the PR ready.

The feature request and implementation were prompted and validated by the human collaborator on a real native macOS OpenList deployment. The submitted code, tests, PR text, and pre-submission review were prepared with Codex assistance. No private deployment paths, credentials, media filenames, or screenshots are included.

[pikachuren]

🙏 感谢 @flyingrtx2333 提交！
🤖 AI 自动审核声明：本评审报告由 AI 自动生成，当前使用 Claude Opus 5 模型进行分析。
⚠️ AI 分析结果仅供参考，可能存在误判或遗漏。如您发现任何问题或有不同意见，欢迎随时提出讨论和纠正。
⚠️ 重要提醒：即使 AI 评审认为代码质量良好且建议合并，最终是否合并仍需由项目维护者进行人工判定。项目维护者会综合考虑代码质量、项目规划、技术方向、团队资源等多方面因素做出是否合并的决策。

🎯 结论

✅ Approve — 功能设计优秀，代码质量高，测试覆盖充分，架构合理

📖 概要

feat(local): add PDF thumbnails on macOS · 为 macOS 平台的 Local 驱动添加 PDF 缩略图支持
核心改动：新增可选的 pdf_thumbnail 配置项，在 macOS 上使用系统 Quick Look 工具渲染 PDF 首页缩略图

🧭 整体方案

采用平台特定构建标签 + 接口抽象的架构模式：

• 新增 pdf_thumbnail 配置项（默认禁用，与现有 thumbnail 主开关解耦）
• Darwin 平台：调用 /usr/bin/qlmanage 渲染 PDF 首页为 512px PNG
• 非 Darwin 平台：返回不支持错误，保持配置项可见但不提供功能
• 复用现有基础设施：签名 URL、并发限制器（thumbTokenBucket）、缩略图缓存目录、图像缩放逻辑
• 传播请求取消到 Quick Look 进程，强制 30 秒渲染超时

📊 变更统计

7 个文件（+165 / -5 行） | 功能 ⭐⭐⭐⭐⭐ | 最小改动 ⭐⭐⭐⭐ | 前向兼容 ⭐⭐⭐⭐⭐ | 方案设计 ⭐⭐⭐⭐⭐

🚨 关键问题

无关键问题

📂 逐文件分析

drivers/local/meta.go

改动意图：添加 pdf_thumbnail 配置字段
代码逻辑：新增 bool 字段，默认 false，required:"false"，help 文本说明仅 macOS 可用
问题分析：

• ✅ 与现有 thumbnail 主开关解耦，遵循最小权限原则
• ✅ 默认禁用，避免未预期的资源消耗
• ✅ Help 文本明确说明平台限制

drivers/local/driver.go

改动意图：重构缩略图支持检测逻辑，传递 context 到 getThumb
代码逻辑：

• 移除 conf.IMAGE/conf.VIDEO 硬编码判断，改为调用 d.supportsThumbnail()
• Link 方法中，向 getThumb 传递 ctx，支持取消传播
• 删除未使用的 conf import

问题分析：

• ✅ 抽象了缩略图支持判断，扩展性更好
• ✅ Context 传递是最佳实践，支持超时和取消
• ✅ 代码更简洁，减少了耦合

drivers/local/util.go

改动意图：实现缩略图支持检测和 PDF 渲染调用逻辑
代码逻辑：

• supportsThumbnail(name)：统一入口，检查是否为图像/视频/PDF
• supportsPDFThumbnail(name)：检查配置开启 + 平台支持 + 文件扩展名为 .pdf
• getThumb(ctx, file)：新增 PDF 分支，调用 renderPDFThumbnail(ctx, fullPath)

问题分析：

• ✅ 逻辑清晰，职责分离
• ✅ 大小写不敏感的扩展名检查（strings.EqualFold）
• ✅ 与现有图像/视频逻辑平行，易于维护
• ✅ 错误处理合理，直接返回渲染错误

drivers/local/pdf_thumb_darwin.go（新文件，//go:build darwin）

改动意图：Darwin 平台的 PDF 渲染实现
代码逻辑：

• pdfThumbnailSupported() 返回 true
• renderPDFThumbnail(ctx, fullPath)：
  1. 创建临时目录（defer 清理）
  2. 创建 30 秒超时的子 context
  3. 调用 /usr/bin/qlmanage -t -s 512 -o <tempDir> <fullPath>
  4. 区分超时、取消、其他错误，返回详细错误信息
  5. 读取生成的 .png 文件并返回

问题分析：

• ✅ 超时处理完善（30 秒），防止长时间阻塞
• ✅ Context 取消传播到子进程（CommandContext）
• ✅ 临时目录自动清理（defer）
• ✅ 错误信息详细，包含命令输出
• ✅ 文件名处理正确（filepath.Base(fullPath) + ".png"）
• 💡 非阻塞建议：qlmanage 生成的文件名可能与预期不同（空格、Unicode 字符），建议增加日志或在测试中验证

drivers/local/pdf_thumb_darwin_test.go（新文件，//go:build darwin）

改动意图：Darwin 平台的集成测试
代码逻辑：

• 使用 /usr/sbin/cupsfilter 将文本文件转换为真实 PDF（文件名包含 Unicode 和空格）
• 调用 renderPDFThumbnail 渲染缩略图
• 验证 PNG magic bytes、解码图像、检查尺寸
• 测试取消的 context 返回 context.Canceled

问题分析：

• ✅ 集成测试覆盖真实场景，包含特殊字符文件名
• ✅ 验证输出格式和内容
• ✅ 测试取消行为
• ✅ 使用系统工具生成 fixture，避免提交二进制文件

drivers/local/pdf_thumb_unsupported.go（新文件，//go:build !darwin）

改动意图：非 Darwin 平台的空实现
代码逻辑：

• pdfThumbnailSupported() 返回 false
• renderPDFThumbnail 返回错误 "PDF thumbnails are not supported on this platform"

问题分析：

• ✅ 标准的条件编译模式
• ✅ 错误信息清晰
• ✅ 配置项仍然可见，但不提供功能（PR 描述中已说明）

drivers/local/pdf_thumb_test.go（新文件）

改动意图：跨平台的单元测试
代码逻辑：

• TestSupportsThumbnail：测试 supportsThumbnail() 的各种场景
  • 图像和视频始终支持
  • PDF 默认不支持
  • 启用 pdf_thumbnail 后，根据平台返回相应结果

问题分析：

• ✅ 覆盖配置开关逻辑
• ✅ 测试平台差异（pdfThumbnailSupported() 返回值）
• ✅ 测试大小写不敏感（document.PDF）
• ✅ 隔离测试环境（临时修改 conf.SlicesMap，defer 恢复）

💡 优势

• ✅ 架构设计优秀：使用 build tags 实现平台特定功能，主逻辑保持跨平台兼容
• ✅ 最小权限原则：默认禁用，需要管理员显式开启
• ✅ 复用现有基础设施：签名 URL、并发控制、缓存目录、图像缩放
• ✅ 错误处理完善：超时、取消、命令错误均有详细错误信息
• ✅ 测试覆盖充分：单元测试 + 集成测试 + 跨平台测试
• ✅ 向后兼容：现有功能不受影响，配置向后兼容
• ✅ 代码质量高：AI 辅助内容经过人工验证（虽然 PR 勾选项未全部确认，但代码质量高）

📝 注意事项与建议

非阻塞建议：

1. 文档更新：PR 描述中提到 "OpenList-Docs: Not required for the initial implementation"，建议后续补充文档说明：

   • pdf_thumbnail 配置项的用途和限制
   • macOS 系统要求（需要 Quick Look 支持）
   • 资源消耗警告（PDF 渲染占用 CPU）
   • 推荐配置 thumb_cache_folder 避免重复渲染

2. 日志增强：建议在 renderPDFThumbnail 中添加 debug 级别日志，记录：

   • 渲染开始和完成时间
   • 生成的临时文件路径
   • 渲染耗时
   • 有助于排查生产环境问题

3. 文件名兼容性：qlmanage 对特殊字符文件名的处理可能存在边界情况，建议在生产环境监控是否有渲染失败的案例

4. AI 辅助内容确认：PR 描述中部分勾选项未确认（"I have reviewed and validated..."），建议作者在正式 ready 前完成人工审核

配置建议（用户视角）：

• 启用此功能前，建议配置 thumb_cache_folder，避免重复渲染消耗资源
• 对于公共或不可信存储，谨慎启用（PR 描述中已提醒）

✅ 待处理清单

• [P2] 后续补充文档（配置说明、系统要求、最佳实践）
• [P2] 考虑添加 debug 日志，方便生产环境排查问题

🎖️ 特别表彰

这是一个工程质量优秀的特性 PR：

• 架构设计合理，使用 build tags 实现平台差异
• 复用现有基础设施，避免重复造轮子
• 测试覆盖充分，包含集成测试和边界情况
• 错误处理完善，超时、取消、命令错误均有考虑
• 向后兼容，对现有功能无影响

🎯 结论：✅ Approve — 这是一个高质量的特性实现，代码质量优秀，架构合理，测试充分，建议合并

[ILoveScratch2]

Please add documentation updates to OpenList-Docs.

[flyingrtx2333]

Added the corresponding documentation update: OpenListTeam/OpenList-Docs#369