Metadata-Version: 2.4
Name: fileflow-cli
Version: 0.1.0
Summary: 🧹 智能文件整理器 — YAML 规则引擎驱动的 CLI 文件分类/移动/清理工具
Author-email: Yuluo <lingeryuluo@gmail.com>
License: 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: License :: OSI Approved :: MIT License
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

# 🧹 FileFlow

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

[![PyPI version](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/fileflow/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

---

## ✨ 功能

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

## 🚀 快速开始

### 安装

```bash
pip install fileflow
```

### 1. 初始化配置

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

```bash
cd ~/Downloads
fileflow init
```

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

### 2. 预览效果

```bash
fileflow run .
```

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

### 3. 执行整理

```bash
fileflow run . --force
```

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

### 一键完成（跳过确认）

```bash
fileflow run . --force --yes
```

## 📖 使用指南

### 命令概览

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

### 配置示例

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

## 🧪 运行测试

```bash
pip install -e ".[dev]"
pytest
```

查看测试覆盖率：

```bash
pytest --cov --cov-report=html
```

## 🤝 贡献

欢迎提交 Issue 和 PR！详情见 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 📄 许可证

[MIT](LICENSE) © 2026 Yuluo
