✨ 一分钟上手

# 1. 安装
pip install fileflow-cli

# 2. 进入乱糟糟的下载目录
cd ~/Downloads

# 3. 生成配置文件
fileflow init

# 4. 预览整理效果（安全，不会动你的文件）
fileflow run

# 5. 确认后执行整理
fileflow run --force

搞定！ 你的文件被自动分类到 Pictures/、Documents/、Code/、Videos/、Audio/ 等目录。

🎯 解决什么问题？

你的 Downloads 文件夹是不是像这样？

📁 Downloads/
├── IMG_2024.jpg
├── project_report.pdf
├── meeting_notes.docx
├── screenshot.png
├── vacation_photo.jpg
├── budget_2024.xlsx
├── app.py
├── style.css
├── video.mp4
├── song.mp3
├── archive.zip
├── another_doc.pdf
├── script.js
├── logo.svg
├── photo_from_2019.jpg
...

整理后 →

📁 Downloads/
├── 📁 Pictures/jpg/vacation_photo.jpg
│               png/screenshot.png
│               svg/logo.svg
├── 📁 Documents/pdf/project_report.pdf
│                 docx/meeting_notes.docx
│                 xlsx/budget_2024.xlsx
├── 📁 Code/py/app.py
│             css/style.css
│             js/script.js
├── 📁 Videos/mp4/video.mp4
├── 📁 Audio/mp3/song.mp3
├── 📁 Archives/zip/archive.zip

干净、有序、一目了然。

🚀 功能特性

📖 详细用法

命令一览

fileflow               # 🧹 欢迎面板 + 快速开始提示
fileflow run           # 🔍 预览并整理当前目录
fileflow run --force   # 📦 直接执行整理
fileflow init          # 🚀 生成默认 .fileflow.yaml
fileflow validate      # ✅ 验证配置文件 (简写: check)
fileflow list-rules    # 📋 查看规则列表 (简写: rules)
fileflow scan          # 🔍 扫描目录自动生成规则 (简写: sc)
fileflow stats         # 📊 查看统计信息
fileflow undo          # ⏪ 撤销最近操作
fileflow --help        # 📖 查看全部命令

常用选项

示例

# 整理桌面
fileflow run ~/Desktop

# 使用自定义配置
fileflow run . --config ~/my-rules.yaml

# 不递归子目录
fileflow run --force --no-recursive

# 只预览，不确认
fileflow run --dry-run -y

# 自动扫描后缀并生成整理规则
fileflow scan

# 扫描时排除 .tmp 和 .log 文件
fileflow scan --exclude .tmp --exclude .log

# 只生成出现 5 次以上的后缀规则
fileflow scan --min-count 5

# 撤销最近 3 次操作
fileflow undo --steps 3

# 撤销所有操作
fileflow undo --all

📝 配置文件 (.fileflow.yaml)

version: "1.0"

settings:
  dry_run_by_default: true   # 默认预览模式
  on_conflict: "skip"        # skip | rename | overwrite
  create_target_dirs: true

rules:
  - name: "整理图片"
    description: "按扩展名分类图片"
    match:
      extensions: [".jpg", ".jpeg", ".png", ".gif", ".svg", ".bmp"]
    action: move
    target: "Pictures/{ext_no_dot}/{filename}"

  - name: "整理文档"
    match:
      extensions: [".pdf", ".doc", ".docx", ".xls", ".xlsx"]
      max_size_mb: 50         # 忽略超过 50MB 的文件
    action: move
    target: "Documents/{ext_no_dot}/{filename}"

  - name: "清理旧日志"
    match:
      extensions: [".log"]
      min_size_mb: 100        # 只处理超过 100MB 的日志
    action: delete
    enabled: false            # 默认禁用，需手动启用

📂 路径模板变量

推荐使用 {ext_no_dot} 作为目录名，如 Documents/pdf/report.pdf，而不是 Documents/.pdf/report.pdf。

🏗 项目架构

fileflow/
├── src/fileflow/
│   ├── cli.py        # CLI 命令 (Typer)
│   ├── config.py     # YAML 配置加载 & 验证
│   ├── engine.py     # 核心引擎 (扫描→匹配→执行)
│   ├── history.py    # 操作历史 & Undo
│   ├── rules.py      # 规则数据模型
│   ├── matchers.py   # 匹配器注册表 + 6 种内置匹配器
│   ├── actions.py    # 文件操作注册表 (move/copy/delete)
│   ├── templates.py  # 路径模板变量解析
│   └── report.py     # Rich 终端美化输出
├── tests/            # 76 项单元测试
├── .github/          # CI/CD 自动化
└── pyproject.toml    # 项目配置

🧩 设计亮点

匹配器注册表模式 — 新增匹配器只需注册，无需修改其他代码：

@register("my_matcher")
class MyMatcher(Matcher):
    def __call__(self, path: Path) -> bool:
        return path.suffix == ".xyz"

🧪 开发 & 测试

git clone https://github.com/Linger668/fileflow.git
cd fileflow
pip install -e ".[dev]"

# 运行测试
pytest

# 代码检查
ruff check src/
ruff format src/
mypy src/

🤝 贡献

欢迎提交 Issue 和 PR！

新手友好 👉 查看 good first issues

📄 许可证

MIT © 2026 Yuluo