FilePilot

FilePilot 是一个本地规则驱动的文件整理工具，用来整理 Mac 和 Windows 电脑里杂乱的桌面、下载、文档和工作资料。

它的核心思想很简单：先扫描，先生成整理建议，先让人确认，然后才移动文件。FilePilot 不联网、不使用 AI、不做定时任务、不提供网站、不自动删除文件。

适合谁

• 桌面、下载目录、文档目录长期堆积文件的人。
• 想把文件归档到统一 FileHub 目录的人。
• 希望先预览整理计划，确认后再移动文件的人。
• 同时需要管理私人 Mac 和工作 Windows 电脑的人。
• 不想把私人文件上传到云端或 AI 服务的人。

核心安全原则

• 默认只生成整理建议，不移动文件。
• 无法分类的文件默认保持原位置。
• 不直接删除任何文件。
• 执行整理前必须人工确认。
• dry-run 只预览，不移动。
• apply 才会真正移动文件。
• 每次 apply 都生成 rollback JSON，可以回滚。
• 文件名冲突时不会覆盖，会自动追加 _1、_2。
• 每次运行都会写入 logs/latest.log 和 reports/status.json。

功能概览

• 扫描指定目录。
• 支持 mac、windows、custom profile。
• 读取 YAML 配置：
  • config/profiles.yaml
  • config/project_rules.yaml
  • config/rules.yaml
  • config/ignore.yaml
• 根据项目关键词、主题关键词、工作场景、数据规则、扩展名生成分类建议。
• 生成文件清单、整理计划、无法分类清单。
• GUI 中查看、搜索、过滤、修改整理计划。
• GUI 中人工处理无法分类文件。
• 支持 dry-run、apply、rollback。
• 支持 Windows exe 打包，运行端不需要安装 Python。

目录结构

FilePilot/
├── config/
│   ├── profiles.yaml
│   ├── project_rules.yaml
│   ├── rules.yaml
│   └── ignore.yaml
├── filepilot/
│   ├── scanner.py
│   ├── classifier.py
│   ├── planner.py
│   ├── organizer.py
│   ├── rollback.py
│   └── utils.py
├── filepilot_gui/
│   ├── app.py
│   ├── main_window.py
│   ├── pages/
│   ├── widgets/
│   └── resources/
├── packaging/
│   ├── FilePilot.spec
│   ├── build_windows.ps1
│   ├── build_windows.bat
│   └── filepilot_gui_entry.py
├── reports/
├── logs/
├── main.py
├── requirements.txt
├── requirements-build.txt
└── README.md

快速开始：Windows 直接使用 exe

如果你拿到的是已经打包好的 FilePilot.exe，不需要安装 Python，也不需要安装 PySide6。

推荐把它放在一个固定目录，例如：

D:\Tools\FilePilot\

目录建议：

D:\Tools\FilePilot\
├── FilePilot.exe
├── config\
├── reports\
└── logs\

第一次启动时，如果 exe 同目录没有 config，FilePilot 会自动生成一份默认配置。reports 和 logs 会在运行后自动生成。

双击：

FilePilot.exe

然后按 GUI 流程操作：

1. 进入“配置”页。
2. 选择 windows 或 custom profile。
3. 添加要扫描的目录，比如桌面、下载、文档。
4. 选择目标 FileHub 目录，比如 D:\FileHub。
5. 点击“保存配置”。
6. 点击“开始扫描”。
7. 到“整理计划”页检查目标路径。
8. 到“无法分类”页人工处理未命中文件。
9. 到“执行”页先点“预览执行”。
10. 确认无误后再点“执行整理”。
11. 如需撤销，到“回滚”页选择 rollback 文件执行回滚。

快速开始：从源码运行 GUI

建议 Python 3.10+。

macOS / Linux：

python3 --version
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txt
python3 -m filepilot_gui.app

Windows PowerShell：

python --version
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python -m filepilot_gui.app

如果 macOS 提示 Could not find the Qt platform plugin "cocoa"，优先确认当前激活的是 FilePilot 自己的虚拟环境：

which python3
python3 -c "import sys, PySide6; print(sys.executable); print(PySide6.__file__)"

如果 PySide6 安装不完整，可以重装：

python3 -m pip install --force-reinstall PySide6
python3 -m filepilot_gui.app

FilePilot 的 GUI 启动入口会自动配置 PySide6 的 Qt 插件路径，并处理 macOS 路径包含空格时的 Qt 运行时缓存问题。

GUI 使用教程

1. 配置扫描范围

打开 FilePilot 后，先进入“配置”页。

你需要设置：

• Profile：选择 mac、windows 或 custom。
• FileHub 目标目录：整理后的根目录，例如 ~/FileHub 或 D:\FileHub。
• 扫描目录：要整理的目录，例如 Desktop、Downloads、Documents。
• Ignore patterns：扫描时跳过的目录或文件，例如 .git、node_modules、AppData。

配置好后点击：

保存配置
开始扫描

2. 查看扫描结果

扫描完成后进入“扫描结果”页。

这里可以看到：

• 扫描文件数。
• 可分类文件数。
• 无法分类文件数。
• 扫描耗时。
• 每个文件的扩展名、大小、修改时间、建议分类、命中规则。

你可以搜索文件名或路径，也可以打开文件所在目录。

3. 检查整理计划

进入“整理计划”页，这是最关键的一步。

表格会显示：

• 文件名。
• 目标分类。
• 分类层级。
• 命中规则。
• 命中关键词。
• 目标路径。
• 置信分。
• 状态。

重点检查 目标路径。FilePilot 会尽量显示有意义的 FileHub 相对路径，例如：

01_Work/WeeklyReport/2026-05/AI周报.docx
02_Project/AirView/切换问题定位记录.md
03_Knowledge/AI/AI_Coding/Codex使用技巧.pdf
07_Data/KPI/2026-05/UE_KPI.csv

如果文件只是命中了大类，没有识别出具体项目或主题，FilePilot 会保留原始来源路径，避免全部塞到同一个目录。例如桌面来的普通文件会进入：

01_Work/Desktop/客户资料/普通合同.docx

你可以在整理计划页：

• 取消某条移动计划。
• 修改目标分类。
• 直接修改目标路径。
• 批量设置分类。
• 将规则加入长期项目规则。
• 打开原文件。
• 打开原文件所在目录。

低置信度或需要复核的文件会标记为 need_review。

4. 处理无法分类文件

进入“无法分类”页。

这些文件默认不会移动。你可以选择：

• 保持原位置。
• 从下拉框选择一个分类。
• 输入自定义目标路径。
• 加入整理计划。

如果你把无法分类文件手动选到 01_Work、03_Knowledge、07_Data 这类大类，FilePilot 也会保留来源路径，例如：

07_Data/Downloads/raw/unknown.csv

5. 预览执行

进入“执行”页，先点：

预览执行

dry-run 不会移动文件，只会检查计划是否可执行。你可以确认：

• 即将移动文件数。
• 保持原位置文件数。
• 文件名冲突数。
• 将创建目录数。
• 错误列表。

6. 执行整理

确认无误后点击：

执行整理

GUI 会弹出二次确认。确认后才会真正移动文件。

执行完成后会显示：

• move_result 报告路径。
• rollback 文件路径。
• 成功数。
• 失败或跳过数。

7. 回滚

如果整理后发现不合适，可以进入“回滚”页。

选择对应的：

rollback_YYYY-MM-DD-HHMMSS.json

先预览，再执行回滚。回滚也不会覆盖同名文件。

8. 查看日志和报告

运行记录会保存在：

logs/latest.log
reports/status.json
reports/file_inventory_YYYY-MM-DD.csv
reports/organize_plan_YYYY-MM-DD.csv
reports/organize_plan_YYYY-MM-DD.md
reports/unclassified_YYYY-MM-DD.csv
reports/move_result_YYYY-MM-DD-HHMMSS.json
reports/rollback_YYYY-MM-DD-HHMMSS.json

GUI 的“日志”页可以查看最新日志和状态摘要。

配置教程

profiles.yaml

config/profiles.yaml 定义 Mac 和 Windows 的默认扫描目录与 FileHub 根目录。

示例：

mac:
  root_output: ~/FileHub
  scan_dirs:
    - ~/Desktop
    - ~/Downloads
    - ~/Documents
  exclude_dirs:
    - ~/Library
    - ~/Applications

windows:
  root_output: C:/FileHub
  scan_dirs:
    - C:/Users/YourName/Desktop
    - C:/Users/YourName/Downloads
    - C:/Users/YourName/Documents
  exclude_dirs:
    - C:/Users/YourName/AppData
    - C:/Windows
    - C:/Program Files

GUI 中保存 custom 配置后，会写入：

reports/gui_config_last.json

project_rules.yaml

config/project_rules.yaml 是多级分类的核心。

匹配优先级：

项目关键词规则 > 主题关键词规则 > 工作/数据规则 > 文件类型规则 > 无法分类

规则会综合匹配：

• 文件名。
• 原始路径。
• 父目录。
• 扩展名。
• 修改时间。

示例：

project_rules:
  AI_For_Work:
    target: "02_Project/AI_For_Work"
    priority: 100
    keywords:
      - "AI For Work"
      - "AI提效"
      - "Prompt库"

work_rules:
  WeeklyReport:
    target: "01_Work/WeeklyReport/{yyyy_mm}"
    priority: 85
    keywords:
      - "周报"
      - "双周报"
      - "月报"

{yyyy_mm} 会根据文件修改时间自动展开，例如：

01_Work/WeeklyReport/2026-05

分类结果会写入整理计划 CSV：

classification_level
matched_rule
matched_keywords
confidence_score
target_category
target_path

rules.yaml

config/rules.yaml 是兜底规则，主要按扩展名或简单关键词分类。

如果只命中这类大类目录，例如：

01_Work
03_Knowledge
07_Data

FilePilot 会将其标记为需要复核，并保留来源路径：

01_Work/Desktop/...
03_Knowledge/Downloads/...
07_Data/Documents/...

ignore.yaml

config/ignore.yaml 定义扫描时跳过的目录或文件名。

默认会跳过：

ignore_patterns:
  - .git
  - node_modules
  - __pycache__
  - .DS_Store
  - AppData
  - Library
  - Program Files
  - Windows
  - .venv
  - venv

CLI 使用教程

GUI 是推荐方式，CLI 适合高级用户或脚本化。

扫描

只生成文件清单，不生成移动计划，也不会移动文件。

python3 main.py scan --profile mac
python3 main.py scan --profile windows

输出：

reports/file_inventory_YYYY-MM-DD.csv
logs/latest.log
reports/status.json

生成整理计划

python3 main.py plan --profile mac
python3 main.py plan --profile windows

输出：

reports/file_inventory_YYYY-MM-DD.csv
reports/organize_plan_YYYY-MM-DD.csv
reports/organize_plan_YYYY-MM-DD.md
reports/unclassified_YYYY-MM-DD.csv

你可以先打开 Markdown 报告查看摘要：

reports/organize_plan_YYYY-MM-DD.md

也可以手动编辑 CSV 中的 target_path 或 status。

Dry-run

dry-run 是默认模式，不移动文件。

python3 main.py organize --profile mac --plan reports/organize_plan_YYYY-MM-DD.csv --dry-run

也可以省略 --dry-run：

python3 main.py organize --profile mac --plan reports/organize_plan_YYYY-MM-DD.csv

Apply

只有显式传入 --apply 才会移动文件。

python3 main.py organize --profile mac --plan reports/organize_plan_YYYY-MM-DD.csv --apply

apply 会：

• 检查源文件是否存在。
• 创建目标目录。
• 遇到同名文件时自动追加序号。
• 记录每个移动操作。
• 生成 rollback JSON。

Rollback

python3 main.py rollback --file reports/rollback_YYYY-MM-DD-HHMMSS.json

回滚会按相反顺序移动文件。如果原位置已有同名文件，也不会覆盖。

Windows 打包教程

如果你要生成一个可以直接发给 Windows 使用的 exe，需要在 Windows 电脑上打包。

进入项目目录后运行：

.\packaging\build_windows.ps1

如果 PowerShell 执行策略拦截：

powershell -ExecutionPolicy Bypass -File .\packaging\build_windows.ps1

或者双击：

packaging\build_windows.bat

打包脚本会自动安装构建依赖并执行 PyInstaller：

python -m pip install -r requirements-build.txt
python -m PyInstaller --clean --noconfirm packaging\FilePilot.spec

打包结果：

dist\FilePilot.exe
dist\FilePilot_Windows.zip

说明：

• 构建机需要 Python 和构建依赖。
• 使用 exe 的电脑不需要 Python。
• config 会被打进 exe，同时也会复制到 dist\config，方便你修改规则。
• reports 和 logs 会生成在 exe 同目录。

默认分类目录

00_Inbox
01_Work
02_Project
03_Knowledge
04_Output
05_Assets
06_Code
07_Data
08_Archive
99_TrashReview

推荐的 FileHub 结构大致如下：

FileHub/
├── 00_Inbox/
├── 01_Work/
│   ├── WeeklyReport/
│   ├── Meeting/
│   ├── Presentation/
│   └── Management/
├── 02_Project/
│   ├── AI_For_Work/
│   ├── AirView/
│   ├── Simulation_NPU/
│   ├── Personal_Blog/
│   ├── Quant_System/
│   └── FilePilot/
├── 03_Knowledge/
│   ├── AI/
│   ├── Wireless/
│   ├── Simulation/
│   └── Management/
├── 04_Output/
├── 05_Assets/
├── 06_Code/
├── 07_Data/
├── 08_Archive/
└── 99_TrashReview/

推荐日常工作流

1. 打开 GUI。
2. 设置扫描目录和 FileHub 目录。
3. 点击“开始扫描”。
4. 检查“整理计划”。
5. 人工处理“无法分类”。
6. 先“预览执行”。
7. 再“执行整理”。
8. 如果整理结果不满意，使用 rollback 回滚。
9. 根据本次复核经验，把长期规则补到 config/project_rules.yaml。

常见问题

会不会自动删除文件？

不会。FilePilot 不提供自动删除能力。

会不会覆盖同名文件？

不会。如果目标目录已经有同名文件，FilePilot 会自动生成新文件名，例如：

report.pdf
report_1.pdf
report_2.pdf

无法分类文件会不会被移动？

默认不会。只有你在 GUI 中人工选择分类并加入整理计划，或手动编辑计划 CSV，才会进入移动流程。

为什么有些文件被放到 Desktop 或 Downloads 子目录？

这是为了保留来源线索。如果 FilePilot 只识别到大类，例如 01_Work，没有识别到具体项目，就会保留原始路径来源：

01_Work/Desktop/...
03_Knowledge/Downloads/...
07_Data/Documents/...

这样不会把文件粗暴塞到一个大目录里。

Windows 上运行 exe 还需要复制 config 吗？

不强制需要。exe 内置默认配置，首次启动会自动生成 config。但如果你希望自己长期维护规则，建议把 config 文件夹和 exe 放在一起。

macOS 上 Qt 报 cocoa 插件错误怎么办？

先确认当前 Python 环境是否正确：

which python3
python3 -c "import sys, PySide6; print(sys.executable); print(PySide6.__file__)"

如果 PySide6 不完整，重装：

python3 -m pip install --force-reinstall PySide6

开发与验证

运行测试：

python3 -m unittest discover -s tests

GUI 启动 smoke test：

QT_QPA_PLATFORM=offscreen python3 -m filepilot_gui.app --qt-smoke-test

检查打包入口语法：

python3 -m compileall packaging filepilot_gui

不做的事

• 不做定时任务。
• 不做 AI 分类。
• 不自动删除文件。
• 不自动发布。
• 不联网。
• 不提供网站。