核心用法
Apple Photos Cleaner 是一套针对 macOS 平台 Apple 照片库的只读分析工具集，通过直接读取 SQLite 数据库（~/Pictures/Photos Library.photoslibrary/database/Photos.sqlite）提供 20 余项专业分析功能。核心能力覆盖四大维度：
1. 清理与去重：junk_finder.py 智能识别截图、低质量照片、连拍废片；duplicate_finder.py 结合 Apple 内置检测与时间戳/尺寸匹配定位重复照片，并基于收藏状态、质量分、文件大小推荐保留策略；cleanup_executor.py 通过 AppleScript 安全移入"最近删除"（30 天可恢复）。
2. 存储与结构分析：storage_analyzer.py 按年份、类型、文件格式拆解存储占用，识别"存储大户"；live_photo_analyzer.py 对比实况照片与静态照片的空间差异；shared_library.py 与 icloud_status.py 分别审计共享图库贡献分布与 iCloud 同步覆盖率。
3. 内容智能挖掘：best_photos.py 利用 Apple 计算质量分（构图、光线、对称性等）筛选高质照片与"隐藏 gems"；people_analyzer.py 分析人物出现频率、共现关系及时间趋势；location_mapper.py 聚类 GPS 坐标识别常去地点与旅行轨迹；scene_search.py 支持 200+ ML 场景标签（海滩、日落、宠物等）内容检索。
4. 叙事与时间线：timeline_recap.py 将照片按事件聚类生成自然语言故事；on_this_day.py 回溯历年同日记忆；photo_habits.py 分析拍摄时段、 streaks、季节性模式；seasonal_highlights.py 按季节精选最佳照片。
显著优点
- 零依赖安全设计：纯 Python 标准库（3.9+），无第三方包，只读数据库操作绝不修改原始照片
- 精准量化决策：提供保守/激进两种清理预估，明确可释放空间（如"287 张 30 天以上截图可释放 2.1 GB"）
- 深度利用 Apple 原生数据：整合计算属性（ZCOMPUTEDASSETATTRIBUTES 质量分）、人脸检测、场景分类、实况照片状态等私有但未加密字段
- 灵活输出：支持 JSON 程序化调用与
--human友好摘要双模式
潜在局限
- 平台锁定：macOS 专属，无法处理 Windows/iCloud 网页版或其他照片服务
- 执行依赖用户确认：除分析外，实际删除需 Photos.app 运行并通过 AppleScript 交互确认
- 地理编码有限：离线反地理编码仅覆盖约 100 个主要城市，偏远地区返回原始坐标
- 相似检测性能：基于质量特征向量的相似照片检测为 O(n²) 复杂度，大库需
--limit截断 - Schema 脆弱性：依赖 Apple 私有数据库结构，未来 macOS 版本升级可能破坏兼容性
适合人群
- 照片库超 10 GB 且增长失控的 macOS 用户
- 需要量化清理收益、厌恶盲目手动筛选的效率型用户
- 希望理解拍摄习惯、生成年度/季度照片故事的内容创作者
- 管理家庭共享图库、需审计成员贡献的共享库管理员
常规风险
- 误删风险：虽通过"最近删除"缓冲，但用户确认前仍需仔细核对预览列表
- 隐私敏感：工具读取完整照片元数据（时间、地点、人物、场景），输出文件需妥善保管
- AppleScript 超时：大数量批量操作可能导致 Photos.app 响应迟缓或脚本中断
- 质量分盲区：部分老照片或第三方导入照片缺乏 Apple 计算质量分，被低估为"低质量"