Metadata-Version: 2.4
Name: fileflow-cli
Version: 0.2.1
Summary: 🧹 智能文件整理器 — YAML 规则引擎驱动的 CLI 文件分类/移动/清理工具
Author-email: Yuluo <lingeryuluo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Linger668/fileflow
Project-URL: Repository, https://github.com/Linger668/fileflow
Project-URL: Issues, https://github.com/Linger668/fileflow/issues
Keywords: file-organization,file-management,cli,productivity
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Desktop Environment :: File Managers
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: watch
Requires-Dist: watchdog>=4.0.0; extra == "watch"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

<div align="center">

# 🧹 FileFlow CLI

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

[![PyPI version](https://img.shields.io/pypi/v/fileflow-cli?style=flat-square&logo=pypi&logoColor=white&color=blue)](https://pypi.org/project/fileflow-cli/)
[![Python Version](https://img.shields.io/pypi/pyversions/fileflow-cli?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/fileflow-cli/)
[![Downloads](https://img.shields.io/pypi/dm/fileflow-cli?style=flat-square&color=brightgreen)](https://pypi.org/project/fileflow-cli/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
[![Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg?style=flat-square)](https://github.com/astral-sh/ruff)
[![GitHub Stars](https://img.shields.io/github/stars/Linger668/fileflow?style=flat-square&logo=github)](https://github.com/Linger668/fileflow)

---

<p align="center">
  <b>🇬🇧 English</b> · <a href="README_zh.md">🇨🇳 简体中文</a>
</p>

---

</div>

## ✨ 一分钟上手

```bash
# 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 |

---

## 📖 详细用法

### 命令一览

```bash
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` | 显示版本 |

### 示例

```bash
# 整理桌面
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)

```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    # 项目配置
```

### 🧩 设计亮点

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

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

---

## 🧪 开发 & 测试

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

# 运行测试
pytest

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

---

## 🤝 贡献

欢迎提交 [Issue](https://github.com/Linger668/fileflow/issues) 和 [PR](https://github.com/Linger668/fileflow/pulls)！

**新手友好** 👉 查看 [good first issues](https://github.com/Linger668/fileflow/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)

---

## 📄 许可证

[MIT](LICENSE) © 2026 Yuluo

---

<div align="center">

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

[![GitHub Stars](https://img.shields.io/github/stars/Linger668/fileflow?style=social)](https://github.com/Linger668/fileflow)

</div>
