smart-file-organizer-tool 0.1.0
智能文件整理工具，自动分类下载文件
License: MIT
Requires Python: >=3.10
Keywords: file, organizer, automation, macos

# 📂 Smart File Organizer

[![PyPI version](https://img.shields.io/pypi/v/smart-file-organizer.svg)](https://pypi.org/project/smart-file-organizer/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/release/python-3100/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

一个智能文件整理工具，自动将 `~/Downloads` 中的文件按类型分类。

## 🚀 功能特点

- ✅ **自动分类**：图片、文档、视频、音频、压缩包、代码
- ✅ **同名文件处理**：自动添加时间戳避免覆盖
- ✅ **模拟运行模式**：安全测试，不移动实际文件
- ✅ **详细日志记录**：所有操作记录在 `/tmp/smart_file_organizer.log`
- ✅ **定时任务支持**：可配置为每天自动运行
- ✅ **跳过隐藏文件和目录**：自动忽略 `.` 开头的文件和子目录
- ✅ **统计报告**：显示整理结果和分类统计

## 📦 安装

### 从 PyPI 安装（推荐）

```bash
pip install smart-file-organizer
```

### 从源码安装

```bash
git clone https://github.com/yourusername/smart-file-organizer.git
cd smart-file-organizer
pip install -e .
```

### 开发模式安装

```bash
git clone https://github.com/yourusername/smart-file-organizer.git
cd smart-file-organizer
pip install -e ".[dev]"
```

## 🎯 使用方法

### 基本使用

整理默认目录（`~/Downloads`）：

```bash
organize-files
```

### 指定源目录

```bash
organize-files --source ~/Documents
```

### 指定目标目录

```bash
organize-files --source ~/Downloads --target ~/Organized
```

### 试运行模式（推荐首次使用）

```bash
organize-files --dry-run
```

### 设置日志级别

```bash
organize-files --log-level DEBUG
```

### 完整示例

```bash
# 试运行，查看将要执行的操作
organize-files --source ~/Downloads --dry-run

# 实际执行整理
organize-files --source ~/Downloads

# 整理到指定目录
organize-files --source ~/Downloads --target ~/OrganizedFiles
```

## 📋 支持的文件类型

### 图片 (images)
`jpg`, `jpeg`, `png`, `gif`, `bmp`, `svg`, `webp`, `ico`, `tiff`, `tif`, `heic`, `heif`

### 文档 (documents)
`pdf`, `doc`, `docx`, `xls`, `xlsx`, `ppt`, `pptx`, `txt`, `rtf`, `odt`, `ods`, `odp`, `pages`, `numbers`, `key`

### 视频 (videos)
`mp4`, `avi`, `mov`, `wmv`, `flv`, `mkv`, `webm`, `m4v`, `mpg`, `mpeg`, `3gp`, `3g2`

### 音频 (audio)
`mp3`, `wav`, `flac`, `aac`, `ogg`, `wma`, `m4a`, `opus`, `aiff`, `au`

### 压缩包 (archives)
`zip`, `rar`, `7z`, `tar`, `gz`, `bz2`, `xz`, `tar.gz`, `tar.bz2`, `tar.xz`, `dmg`, `iso`

### 代码 (code)
`py`, `js`, `html`, `css`, `java`, `cpp`, `c`, `h`, `hpp`, `cs`, `php`, `rb`, `go`, `rs`, `swift`, `kt`, `ts`, `tsx`, `jsx`, `vue`, `json`, `xml`, `yaml`, `yml`, `sh`, `bash`, `zsh`, `ps1`, `bat`, `cmd`, `sql`, `md`, `markdown`

## 📊 输出示例

```
============================================================
整理完成！
============================================================
总文件数:     10
已整理:       9
已跳过:       1
错误数:       0

按类别统计:
  images      : 2
  documents   : 2
  videos      : 1
  audio       : 1
  archives    : 1
  code        : 2
============================================================
```

## ⚙️ 配置

### 日志文件

日志文件默认保存在 `/tmp/smart_file_organizer.log`，包含所有操作的详细记录。

### 定时任务（macOS）

可以使用 `launchd` 配置定时任务。示例配置文件位于 `launchd/com.smartfileorganizer.plist`。

编辑配置文件：

```bash
# 编辑定时任务配置
nano launchd/com.smartfileorganizer.plist

# 加载定时任务
launchctl load ~/Library/LaunchAgents/com.smartfileorganizer.plist

# 立即运行一次
launchctl start com.smartfileorganizer
```

## 🧪 开发

### 运行测试

```bash
# 运行所有测试
python -m unittest tests.test_main -v

# 或使用 pytest
pytest tests/ -v
```

### 项目结构

```
SmartFileOrganizer/
├── src/
│   └── smart_file_organizer/
│       ├── __init__.py
│       ├── main.py          # 主程序入口
│       └── utils.py         # 工具函数
├── tests/
│   └── test_main.py         # 单元测试
├── README.md
├── setup.py                  # 安装配置
├── pyproject.toml            # 现代 Python 项目配置
├── MANIFEST.in               # 包含文件清单
├── LICENSE                   # MIT 许可证
└── requirements.txt          # 依赖列表
```

### 代码质量

```bash
# 代码格式化
black src/ tests/

# 代码检查
flake8 src/ tests/

# 类型检查
mypy src/
```

## 📝 命令行选项

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--source` | 源目录路径 | `~/Downloads` |
| `--target` | 目标目录路径（可选） | 源目录 |
| `--dry-run` | 模拟运行模式，不实际移动文件 | `False` |
| `--log-level` | 日志级别（DEBUG/INFO/WARNING/ERROR） | `INFO` |
| `-h, --help` | 显示帮助信息 | - |

## 🔍 工作原理

1. **扫描源目录**：遍历指定目录中的所有文件
2. **文件分类**：根据文件扩展名识别文件类型
3. **创建分类目录**：在目标目录中创建对应的分类文件夹
4. **移动文件**：将文件移动到对应的分类目录
5. **处理冲突**：如果目标位置已存在同名文件，自动添加时间戳
6. **生成报告**：显示整理统计和结果

## ⚠️ 注意事项

- 工具会**移动**文件，而不是复制，请确保重要文件已备份
- 首次使用建议使用 `--dry-run` 模式测试
- 隐藏文件（以 `.` 开头）和子目录会被自动跳过
- 无法分类的文件会保留在原目录

## 🐛 问题反馈

如果遇到问题或有建议，请在 [GitHub Issues](https://github.com/yourusername/smart-file-organizer/issues) 中提交。

## 📄 许可证

本项目采用 [MIT 许可证](LICENSE)。

## 🙏 致谢

感谢所有贡献者和使用者的支持！

---

**Made with ❤️ for better file organization**