ai-file-organizer

# AI File Organizer Skill v3.0.0 **下一代智能文件整理工具** - 异步引擎、AI 内容分析、云同步、版本管理 ## 🎯 触发条件 - **手动触发**: `/organize-files` 或 "帮我整理文件"、"清理重复文件" - **定时触发**: 每周/每月自动整理下载文件夹 - **文件夹监控**: 监控指定文件夹自动整理 - **云同步触发**: 文件整理完成后自动同步到云端 ## ✨ 核心功能 ### 1. 异步处理引擎 🚀 - **并发处理**: 基于 asyncio 的异步 IO，速度提升 40% - **智能调度**: 自动优化并发数，适配不同硬件 - **进度追踪**: 实时进度条 + 预估完成时间 - **错误隔离**: 单文件失败不影响整体流程 ### 2. AI 内容分析 🧠 - **智能标签**: LLM 分析文件内容，生成精准描述 - **语义分类**: 基于内容语义自动分类，非简单关键词匹配 - **置信度评分**: 每个分类附带置信度，低置信度可人工复核 - **自学习**: 根据用户反馈优化分类模型 ### 3. 智能缓存系统 💾 - **哈希缓存**: 文件哈希缓存，避免重复计算 - **分类缓存**: 已分类结果缓存，二次整理速度提升 70% - **TTL 管理**: 自动过期机制，缓存不过度占用空间 - **持久化**: 重启后缓存依然有效 ### 4. 云同步支持 ☁️ - **多云支持**: 阿里云盘、百度网盘、OneDrive - **自动同步**: 整理完成后自动上传到云端 - **增量同步**: 仅上传变更文件，节省带宽 - **断点续传**: 网络中断后可继续传输 ### 5. 文件版本管理 🔄 - **自动版本**: 文件变更自动保留历史版本 - **版本对比**: 支持查看不同版本差异 - **一键恢复**: 快速恢复到任意历史版本 - **版本清理**: 自动清理过期版本，节省空间 ### 6. 重复文件清理 🗑️ - **内容哈希**: SHA256 哈希检测完全重复 - **相似度检测**: 感知哈希检测相似图片 - **智能保留**: 自动保留最佳版本（最高质量/最早创建） - **安全删除**: 移动到回收站而非直接删除 ### 7. 交互式 CLI 👆 - **预览模式**: 操作前预览整理方案 - **交互确认**: 关键操作前请求确认 - **详细日志**: 结构化日志，支持 JSON 导出 - **丰富输出**: Emoji、进度条、彩色输出 ### 8. 智能清理建议 💡 - **临时文件**: 识别并建议删除系统临时文件 - **缓存清理**: 应用缓存、浏览器缓存清理建议 - **大文件检测**: 找出占用空间的大文件 - **重复下载**: 检测重复下载的文件 ## 📋 配置参数 ```yaml # 命名规则 naming: format: "{date}_{type}_{original}" # 日期_类型_原名 date_format: "%Y%m%d" max_length: 100 replace_spaces: true # 分类规则 classification: enabled: true ai_analysis: true # 启用 AI 内容分析 categories: - name: "工作文档" keywords: ["报告", "方案", "合同", "发票"] folder: "Work/Documents" - name: "学习资料" keywords: ["教程", "课程", "笔记"] folder: "Learning" - name: "图片视频" extensions: ["jpg", "png", "mp4", "mov"] folder: "Media" - name: "代码项目" extensions: ["py", "js", "java", "go", "rs"] folder: "Code" # 重复文件处理 duplicates: enabled: true similarity_threshold: 0.95 keep_best: true move_to_folder: "_duplicates" # 云同步 cloud_sync: enabled: false provider: "aliyun" # aliyun | baidu | onedrive access_key: "${ALIYUN_ACCESS_KEY}" secret_key: "${ALIYUN_SECRET_KEY}" bucket: "my-files" auto_sync: true # 版本管理 versioning: enabled: true max_versions: 5 version_folder: ".versions" # 缓存 cache: enabled: true max_size: 10000 ttl_days: 7 # 性能 performance: max_concurrent: 10 chunk_size: 8192 use_async_io: true # 日志 logging: level: "INFO" file: "logs/organizer.log" format: "json" ``` ## 🚀 使用示例 ### 示例 1: 整理下载文件夹 ```bash # 基础整理 python scripts/organizer.py --organize ~/Downloads # 指定目标文件夹 python scripts/organizer.py --organize ~/Downloads --target ~/Organized # 高性能模式 python scripts/organizer.py --organize ~/Downloads --concurrent 20 ``` ### 示例 2: 清理重复文件 ```bash # 检测重复 python scripts/organizer.py --duplicates ~/Files # 清理并移动 python scripts/organizer.py --duplicates ~/Files --move-to _duplicates ``` ### 示例 3: 使用配置文件 ```bash # 使用自定义配置 python scripts/organizer.py --organize ~/Downloads --config config.yaml # 导出整理报告 python scripts/organizer.py --organize ~/Downloads --report report.json ``` ### 示例 4: 预览模式 ```bash # 先预览整理方案 python scripts/organizer.py --organize ~/Downloads --dry-run # 交互确认模式 python scripts/organizer.py --organize ~/Downloads --interactive ``` ### 示例 5: 云同步 ```bash # 配置环境变量 export ALIYUN_ACCESS_KEY="your_key" export ALIYUN_SECRET_KEY="your_secret" # 整理并同步 python scripts/organizer.py --organize ~/Downloads --config cloud_config.yaml ``` ## 📊 输出示例 ``` ============================================================ 🚀 开始文件整理 (v3.0.0 异步引擎) ============================================================ 📂 源目录：/home/user/Downloads 📁 目标目录：/home/user/Organized 📊 发现 523 个文件 处理进度: 100%|████████████████| 523/523 [00:26<00:00, 20.1file/s] ============================================================ 📊 整理完成 ============================================================ 总文件数：523 ✅ 成功：520 ❌ 失败：3 ⚡ 速度：20.0 个/秒 ⏱️ 耗时：26.0 秒 💾 缓存命中率：68.5% 分类统计: 📄 Documents: 125 个 🖼️ Images: 234 个 🎥 Videos: 89 个 💻 Code: 45 个 📦 Archives: 27 个 📋 报告已导出：report.json ``` ## 🔧 命令行参数 ``` usage: organizer.py [-h] [--demo] [--organize DIR] [--target DIR] [--duplicates DIR] [--config FILE] [--concurrent N] [--no-cache] [--verbose] [--report FILE] 可选参数: -h, --help 显示帮助信息 --demo 运行演示 --organize DIR 整理指定文件夹 --target DIR 目标文件夹 --duplicates DIR 检测重复文件 --config FILE 配置文件路径 --concurrent N 最大并发数 (默认：10) --no-cache 禁用缓存 --verbose, -v 详细输出 --report FILE 导出报告路径 ``` ## 📈 性能基准 | 场景 | v2.0.0 | v3.0.0 | 提升 | |------|--------|--------|------| | 1000 文件 | 45 秒 | 26 秒 | **73%** ⬆️ | | 10000 文件 | 8 分钟 | 4.5 分钟 | **78%** ⬆️ | | 内存占用 | 256MB | 128MB | **50%** ⬇️ | | 缓存命中率 | 0% | 70% | **新增** | ## 🛡️ 安全特性 - **只读优先**: 默认复制而非移动，原文件保留 - **操作审计**: 完整记录所有操作日志 - **权限检查**: 自动检查文件访问权限 - **敏感路径排除**: 自动跳过系统目录和隐藏目录 - **还原点**: 操作前自动创建还原点 - **加密存储**: 配置文件中的敏感信息加密存储 ## 🔌 扩展开发 ### 添加自定义分类器 ```python from organizer import AIFileOrganizer class CustomOrganizer(AIFileOrganizer): def classify_file(self, file_path, filename): # 自定义分类逻辑 if 'invoice' in filename.lower(): return 'Finance/Invoices', 0.95 return super().classify_file(file_path, filename) ``` ### 添加云存储 provider ```python from cloud_providers.base import BaseCloudProvider class CustomCloudProvider(BaseCloudProvider): def upload(self, file_path, remote_path): # 实现上传逻辑 pass def download(self, remote_path, local_path): # 实现下载逻辑 pass ``` ## 🐛 常见问题 ### Q: 处理速度慢？ **A:** 1. 增加并发数：`--concurrent 20` 2. 启用缓存：确保 `cache.enabled: true` 3. 检查磁盘 IO 性能 ### Q: 分类不准确？ **A:** 1. 完善分类规则的关键词 2. 启用 AI 内容分析：`ai_analysis.enabled: true` 3. 检查文件名是否包含足够信息 ### Q: 云同步失败？ **A:** 1. 检查 API 密钥配置 2. 确认网络连接正常 3. 查看日志：`logs/organizer.log` ## 📚 相关文档 - [README.md](README.md) - 完整文档 - [QUICKSTART.md](QUICKSTART.md) - 快速开始 - [CHANGELOG.md](CHANGELOG.md) - 更新日志 - [docs/PERFORMANCE.md](docs/PERFORMANCE.md) - 性能调优 ## 🧪 测试 ```bash # 单元测试 python -m pytest tests/test_organizer.py -v # 覆盖率报告 python -m pytest tests/test_organizer.py -v --cov=scripts --cov-report=html # 性能基准测试 python tests/benchmark.py ``` ## 📦 依赖 **必需:** - Python 3.8+ - aiofiles - aiomultiprocess **可选:** - tqdm (进度条) - pyyaml (YAML 配置) - dashscope (AI 内容分析) ## 📄 许可证 MIT License ## 👥 作者 于金泽 --- **版本**: 3.0.0 **更新日期**: 2026-03-16 **文档**: https://github.com/your-repo/ai-file-organizer