Phockup：智能媒体文件整理工具全解析

核心功能解析

实现媒体自动化分类

Phockup作为一款专业的媒体整理工具，核心价值在于解决用户面临的照片与视频混乱存储问题。通过解析文件元数据（尤其是EXIF信息），工具能够自动识别媒体创建时间，并按年/月/日层级结构重建文件系统。这种自动化处理避免了手动分类的繁琐，特别适合摄影爱好者、内容创作者等需要管理大量媒体文件的用户。

支持多格式与元数据提取

工具内置的元数据解析引擎[src/exif.py]能够处理JPEG、MP4等主流媒体格式，通过读取文件头信息和扩展元数据（如XMP格式）确定准确的创建时间。对于缺失元数据的文件，系统会智能回退到文件修改时间或文件名解析（如"date_20180101_010101.jpg"格式），确保每个文件都能被正确归类。

快速上手流程

完成环境部署

首先通过Git获取项目代码并安装依赖：

git clone https://gitcode.com/gh_mirrors/ph/phockup
cd phockup
pip install -r requirements.txt

项目结构采用模块化设计，核心处理逻辑集中在[src/phockup.py]，元数据解析由[src/exif.py]负责，日期处理功能封装在[src/date.py]中，各模块通过清晰接口实现数据流转。

执行基础整理命令

使用以下命令即可完成媒体文件整理：

python phockup.py [源目录] [目标目录]

工具会扫描源目录中所有媒体文件，提取创建时间后，在目标目录生成如"2023/10/25"的层级结构，并将文件复制或移动到对应位置。默认情况下，工具采用复制模式以确保原始文件安全。

高级配置指南

定制文件命名规则

通过命令行参数可自定义输出文件名格式，例如：

python phockup.py ./input ./output --filename "{YYYY}{MM}{DD}_{HH}{mm}{ss}_{original}"

支持的占位符包括日期组件（YYYY/MM/DD等）、原始文件名（{original}）和计数器（{counter}），满足不同场景下的命名需求。配置优先级为：命令行参数 > 环境变量 > 默认配置。

处理特殊文件场景

针对损坏文件、无元数据文件等特殊情况，工具提供灵活的处理策略：

• 无法解析的文件自动归类到"unknown"目录
• 可通过--link参数创建硬链接而非复制文件，节省磁盘空间
• 对于重复文件，系统会自动重命名避免冲突（添加计数器后缀）

集成与扩展方案

项目提供Docker部署支持，通过[Dockerfile]和[entrypoint.sh]可快速构建容器化应用。开发人员可通过扩展[src/dependency.py]中的依赖注入机制，添加自定义元数据解析器或存储适配器，满足特定业务需求。测试用例[tests/test_phockup.py]提供了完整的功能验证框架，确保定制化修改的兼容性。

使用注意事项

在处理大量文件时，建议先通过--dry-run参数预览操作结果：

python phockup.py ./input ./output --dry-run

该模式下工具仅输出整理计划而不执行实际操作，帮助用户在正式运行前确认配置效果。对于包含符号链接的目录，需使用--follow-links参数确保链接文件被正确处理。