fileflow-cli 0.2.0

🧹 智能文件整理器 — YAML 规则引擎驱动的 CLI 文件分类/移动/清理工具

🧹 FileFlow CLI

智能文件整理器 — YAML 规则引擎驱动的 CLI 文件分类/移动/清理工具

---

🇬🇧 English · 🇨🇳 简体中文

---

✨ 一分钟上手

# 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

干净、有序、一目了然。

---

🚀 功能特性

特性	说明
🎯 YAML 规则引擎	声明式配置，想怎么分就怎么分
🔍 预览模式	先看效果再执行，安全无副作用
📂 6 种匹配方式	扩展名/通配符/正则/文件名包含/文件大小/组合 AND
📦 文件操作	移动/复制/删除，自动创建目录
⚡ 冲突处理	跳过/重命名/覆盖，策略可选
⏪ 支持撤销	fileflow undo 一键回退
📊 统计功能	fileflow stats 查看整理记录
🔌 可扩展	匹配器和操作都支持插件式注册
🎨 终端美化	Rich 进度条 + 彩色表格
🪶 轻量依赖	只需 typer + rich + pyyaml

---

📖 详细用法

命令一览

fileflow init          # 🚀 生成默认 .fileflow.yaml
fileflow run .         # 🔍 预览整理效果
fileflow run . --force # 📦 执行整理
fileflow validate      # ✅ 验证配置文件
fileflow list-rules    # 📋 查看规则列表
fileflow stats         # 📊 查看统计信息
fileflow undo          # ⏪ 撤销最近操作
fileflow --help        # 📖 查看帮助

常用选项

选项	说明
--config, -c	指定配置文件
--dry-run, -n	仅预览模式
--force, -f	跳过预览，直接执行
--yes, -y	跳过所有确认提示
--no-recursive	不扫描子目录
--no-progress	不显示进度条
--verbose, -v	详细输出
--version, -V	显示版本

示例

# 整理桌面
fileflow run ~/Desktop

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

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

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

# 撤销最近 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            # 默认禁用，需手动启用

📂 路径模板变量

变量	说明	示例值
{filename}	完整文件名	report.pdf
{name}	文件名（无扩展名）	report
{ext_no_dot}	扩展名（无点，推荐目录用）	pdf
{ext}	扩展名（含点）	.pdf
{year}	4 位年份	2026
{month}	2 位月份	07
{day}	2 位日期	13

推荐使用 {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

---

如果 FileFlow 帮到了你，请给它 ⭐ 支持一下！ 🌟