File Organizer

一个基于 TUI / Raycast 的文件整理工具，通过模式匹配自动将文件移动到指定文件夹。

使用方式

方式	说明
TUI	终端交互界面，功能完整
Raycast	macOS 快捷启动，快速操作
CLI	命令行 JSON 输出，适合脚本调用

安装

cd /Users/menggq/Documents/file_manager
pip install -e .

快速开始

TUI 模式

# 运行工具（默认读取当前目录的 file_organizer.toml）
file-organizer

# 指定配置文件
file-organizer -c /path/to/config.toml

# 启动监控模式
file-organizer -w

Raycast 模式

# 1. 安装 Raycast 扩展依赖
cd raycast-extension
npm install

# 2. 开发模式运行
npm run dev

# 3. 在 Raycast 中搜索 "整理文件"

详见 raycast-extension/README.md

CLI 模式 (JSON 输出)

# 列出匹配的文件
file-organizer-cli -c config.toml list

# 显示配置
file-organizer-cli -c config.toml config

# 移动文件
file-organizer-cli -c config.toml move "文件名.pdf"

# 预览移动
file-organizer-cli -c config.toml move --dry-run "文件名.pdf"

---

配置文件详解

配置文件使用 TOML 格式，默认文件名为 file_organizer.toml。

基本结构

source_dir = "扫描的源目录"

[[rules]]
name = "规则名称"
pattern = "匹配模式"
match_type = "匹配类型"
target_dir = "目标目录"

[[rules]]
name = "另一条规则"
pattern = "..."
match_type = "..."
target_dir = "..."

配置项说明

source_dir (必需)

要扫描的源目录，工具会遍历此目录下的所有文件进行匹配。

source_dir = "~/Downloads"                    # 支持 ~ 展开为用户目录
source_dir = "/Users/menggq/Downloads"        # 绝对路径
source_dir = "./downloads"                    # 相对路径（相对于配置文件所在目录）

[[rules]] (必需，可多条)

每条规则定义一种文件匹配和移动的方式。

字段	必需	说明
name	是	规则名称，用于 TUI 界面显示
pattern	是	匹配模式字符串
match_type	是	匹配类型：prefix / suffix / extension / regex
target_dir	是	目标目录路径
enabled	否	是否启用此规则，默认 true

---

匹配类型详解

1. prefix - 前缀匹配

文件名以指定字符串开头即匹配。

[[rules]]
name = "大论文参考PDF"
pattern = "大论文参考"
match_type = "prefix"
target_dir = "/Users/menggq/Desktop/02-论文写作/01-大论文/参考论文"

匹配示例：

• 大论文参考_神经网络.pdf ✓
• 大论文参考-综述.docx ✓
• 小论文参考.pdf ✗

2. suffix - 后缀匹配

文件名以指定字符串结尾即匹配。

[[rules]]
name = "日志文件"
pattern = ".log"
match_type = "suffix"
target_dir = "~/Logs"

匹配示例：

• error.log ✓
• app.2024.log ✓
• log.txt ✗

3. extension - 扩展名匹配

专门用于匹配文件扩展名，更智能（自动处理 . 前缀）。

[[rules]]
name = "图片文件"
pattern = ".jpg"
match_type = "extension"
target_dir = "~/Pictures/Downloads"

[[rules]]
name = "PNG图片"
pattern = "png"
match_type = "extension"
target_dir = "~/Pictures/Downloads"

.jpg 和 jpg 写法都可以，效果相同。

匹配示例：

• photo.jpg ✓
• image.JPG ✗（区分大小写）
• photo.jpg.bak ✗

4. regex - 正则表达式匹配

使用 Python 正则表达式进行灵活匹配。

[[rules]]
name = "日期文件"
pattern = "\\d{4}-\\d{2}-\\d{2}"
match_type = "regex"
target_dir = "~/Documents/Dated"

[[rules]]
name = "发票PDF"
pattern = "发票.*\\.pdf$"
match_type = "regex"
target_dir = "~/Documents/Invoices"

匹配示例（\\d{4}-\\d{2}-\\d{2}）：

• 2024-01-15_report.pdf ✓
• backup-2024-12-31.zip ✓
• report.pdf ✗

---

完整配置示例

# 扫描 Downloads 文件夹
source_dir = "~/Downloads"

# 规则1：大论文参考资料
[[rules]]
name = "大论文参考PDF"
pattern = "大论文参考"
match_type = "prefix"
target_dir = "/Users/menggq/Desktop/02-论文写作/01-大论文/参考论文"

# 规则2：图片文件
[[rules]]
name = "JPG图片"
pattern = ".jpg"
match_type = "extension"
target_dir = "~/Pictures/Downloads"

[[rules]]
name = "PNG图片"
pattern = ".png"
match_type = "extension"
target_dir = "~/Pictures/Downloads"

# 规则3：PDF 文档
[[rules]]
name = "PDF文档"
pattern = ".pdf"
match_type = "extension"
target_dir = "~/Documents/PDFs"

# 规则4：压缩包
[[rules]]
name = "压缩包"
pattern = ".zip"
match_type = "extension"
target_dir = "~/Downloads/Archives"

# 规则5：日志文件（禁用）
[[rules]]
name = "日志文件"
pattern = ".log"
match_type = "suffix"
target_dir = "~/Logs"
enabled = false

# 规则6：正则匹配发票
[[rules]]
name = "发票文件"
pattern = "发票.*\\.pdf$"
match_type = "regex"
target_dir = "~/Documents/Invoices"

---

TUI 界面操作

快捷键

快捷键	功能
Space	选择/取消选择当前行
a	全选所有文件
n	取消选择所有文件
/	打开/关闭搜索框
Esc	关闭搜索框
r	重新扫描源目录
d	Dry Run 预览模式
e	执行移动（需确认）
u	撤销上一次移动
w	开启/关闭监控模式
m	打开规则编辑器
q	退出程序

界面功能

功能	说明
选择性移动	用 Space/A/N 选择文件，只移动选中的文件
文件大小统计	显示总文件数、总大小、选中文件数、选中大小
确认对话框	执行前弹出确认，防止误操作
进度条	移动过程中显示进度
撤销功能	移动后可一键撤销，恢复文件原位置
搜索过滤	按 / 打开搜索框，实时过滤文件列表
规则编辑	按 m 在 TUI 中添加/编辑规则
监控模式	按 w 开启，自动监控新文件并移动

建议工作流

1. 运行后查看匹配的文件列表
2. 用 / 搜索特定文件（可选）
3. 用 Space 选择需要移动的文件，或用 a 全选
4. 按 d (Dry Run) 预览，确认匹配结果正确
5. 按 e (Execute) 执行移动，在确认对话框中确认
6. 如发现错误，按 u (Undo) 撤销
7. 如需重新扫描，按 r (Refresh)

---

监控模式

监控模式会自动监视源目录，当新文件出现时自动匹配并移动。

启动方式

# 命令行参数启动
file-organizer -w

# 或在 TUI 中按 w 键切换

安装依赖

pip install file-organizer[watch]
# 或
pip install watchdog

工作原理

1. 监控 source_dir 目录中的文件创建事件
2. 新文件出现时，自动匹配规则
3. 匹配成功则立即移动到目标目录
4. 移动结果会在界面显示通知

---

规则编辑

按 m 键可在 TUI 中添加新规则，无需手动编辑配置文件。

规则字段

字段	说明
规则名称	显示在列表中的名称
匹配模式	用于匹配的字符串或正则
匹配类型	prefix/suffix/extension/regex
目标目录	文件移动的目标路径

---

注意事项

1. 匹配优先级：规则按配置文件中的顺序执行，文件只匹配第一条符合的规则
2. 目标目录：如果目标目录不存在，工具会自动创建
3. 文件冲突：如果目标目录已存在同名文件，默认跳过该文件
4. 路径格式：支持 ~（用户目录）、绝对路径、相对路径

---

故障排除

找不到配置文件

# 指定配置文件路径
file-organizer -c /path/to/your/config.toml

没有匹配到文件

1. 检查 source_dir 路径是否正确
2. 检查 pattern 和 match_type 是否匹配目标文件
3. 在 TUI 中按 r 刷新文件列表

中文路径问题

确保配置文件使用 UTF-8 编码保存。

file_manager