fileflow-cli 0.1.0

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

🧹 FileFlow

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

---

✨ 功能

• 📝 YAML 规则引擎 — 声明式配置，一目了然
• 🔍 预览模式 — 先看效果再执行，安全无副作用
• 📂 多种匹配方式 — 扩展名/通配符/正则/文件名/大小
• 🎯 智能文件移动 — 自动创建目录，冲突策略可选
• ⏪ 支持撤销 — 操作历史可追溯（即将推出）
• 🎨 Rich 终端美化 — 彩色表格，清晰直观
• 🔌 可扩展架构 — 匹配器和操作都支持注册表模式

🚀 快速开始

安装

pip install fileflow

1. 初始化配置

在要整理的目录下生成配置文件：

cd ~/Downloads
fileflow init

这会生成 .fileflow.yaml，内置了图片/文档/视频/代码等常用规则。

2. 预览效果

fileflow run .

以预览模式运行，会展示每个文件将被如何整理，不会真正移动文件。

3. 执行整理

fileflow run . --force

确认无误后，使用 --force 真正执行。

一键完成（跳过确认）

fileflow run . --force --yes

📖 使用指南

命令概览

fileflow init          # 生成默认配置文件
fileflow run           # 运行整理（默认预览）
fileflow validate      # 验证配置文件
fileflow list-rules    # 查看规则列表
fileflow --help        # 查看全部命令

选项

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

配置示例

# .fileflow.yaml
version: "1.0"

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

rules:
  - name: "整理图片"
    match:
      extensions: [".jpg", ".jpeg", ".png", ".gif", ".svg"]
    action: move
    target: "Pictures/{ext}/{filename}"

  - name: "清理旧日志"
    match:
      extensions: [".log"]
      modified_before_days: 30
    action: delete
    enabled: false  # 默认禁用

📂 模板变量

目标路径 target 支持以下变量：

变量	说明	示例
{filename}	完整文件名	report.pdf
{name}	文件名（不含扩展名）	report
{ext}	扩展名（含点，推荐用于文件名）	.pdf
{ext_no_dot}	扩展名（不含点，推荐用于目录名）	pdf
{year}	4 位年份	2026
{month}	2 位月份	07
{day}	2 位日期	13
{hour}	2 位小时	14
{minute}	2 位分钟	30

🏗 项目架构

fileflow/
├── src/fileflow/
│   ├── cli.py        # CLI 命令定义 (Typer)
│   ├── config.py     # YAML 配置加载 & 验证
│   ├── engine.py     # 核心编排引擎
│   ├── rules.py      # 规则数据模型
│   ├── matchers.py   # 匹配器注册表 & 内置匹配器
│   ├── actions.py    # 文件操作 (move/copy/delete)
│   ├── templates.py  # 路径模板变量解析
│   ├── report.py     # Rich 终端输出
│   └── watcher.py    # 实时监控（可选）
├── tests/            # 全模块测试覆盖
└── pyproject.toml    # 项目配置

🧪 运行测试

pip install -e ".[dev]"
pytest

查看测试覆盖率：

pytest --cov --cov-report=html

🤝 贡献

欢迎提交 Issue 和 PR！详情见 CONTRIBUTING.md。

📄 许可证

MIT © 2026 Yuluo