DeskMaid

AI 智能桌面文件整理工具。
它不按“文件格式”生硬归类，而是尽量按真实使用场景整理你的桌面。

它适合解决什么问题

很多桌面整理工具只会按 PDF / 图片 / 压缩包 / 文档 这种格式分类。
DeskMaid 更接近人的使用习惯：

• 把同一个项目相关的 PDF、文档、截图放在一起
• 区分工作资料、学习资料、生活归档、临时下载
• 给出整理预案，确认后再执行
• 每次操作都记录日志，支持一键撤销

实际使用效果

下面这组截图展示了一个完整流程：整理前 → 运行整理 → 整理后 → 查看历史 → 撤销恢复。

1. 整理前

2. 运行整理

3. 整理后目录结构

4. 查看历史记录

5. 一键撤销

6. 撤销后恢复原状

核心特性

• 三种分类模式
  • quick：直接扫描 + AI 分类，适合快速整理
  • personal：先采集使用偏好，再按个人习惯分类
  • deep：读取文件内容摘要，做更细的语义分类
• 桌面女仆模式
  • 提供一个可拖动的常驻小助手
  • 双击即可整理桌面，右键可打开设置、历史、撤销等菜单
  • 保留原有 CLI，不影响命令行工作流
• 不是按后缀整理，而是按场景整理
  • 例如把项目里的 PDF、PPT、说明文档、图片放进同一类
• 轻量二级整理
  • 不只处理目标目录第一层；发现明显凌乱的子目录时，会做一次受控的二级整理
• 交互式确认
  • 分类方案先展示，用户可以接受或提出修改意见
• 一键撤销
  • 每次整理都记录事务日志，随时恢复原状
• 多 API 支持
  • 支持 Azure OpenAI、OpenAI、自定义兼容接口
• 离线演示模式
  • --demo 在未配置 API 时会自动切换到内置演示分类逻辑，方便截图、录屏和文档展示

安装

pip install -e .

要求：

• Python >= 3.10

快速开始

1. 配置 API

deskmaid config

按提示填写：

• API Provider：azure-openai / openai / custom
• API Base URL
• API Key
• 模型名称
• 目标桌面路径

配置目录：

• macOS / Linux：~/.deskmaid/
• Windows：%APPDATA%\DeskMaid\

2. 开始整理

deskmaid run

常用参数：

deskmaid run --path ~/Downloads
deskmaid run --mode quick
deskmaid run --mode personal
deskmaid run --mode deep
deskmaid run --path ~/Desktop --mode personal

3. 启动桌面女仆模式

deskmaid desktop

或者：

deskmaid-gui

桌面模式说明：

• 双击女仆形象：立即整理桌面
• 拖动女仆形象：调整悬浮位置
• 右键女仆形象：打开整理、撤销、历史、CLI 指南、设置、退出菜单
• 在设置中可切换默认模式、API、目标路径和个性化画像

4. 撤销上一次整理

deskmaid undo

5. 查看最近历史

deskmaid history

整理流程

deskmaid run 的执行顺序大致如下：

1. 扫描目标目录，统计文件、文件夹和疑似凌乱子目录
2. 选择分类模式
3. 个性化模式下采集用户偏好
4. 深度模式下读取文件内容摘要
5. AI 先提出分类方案
6. 用户确认后，AI 再生成逐项整理预案
7. 用户确认执行
8. 写入历史日志，必要时补做一次轻量二级整理

命令一览

deskmaid --help
deskmaid run --help
deskmaid config
deskmaid run
deskmaid undo
deskmaid history
deskmaid desktop
deskmaid-gui

CLI 帮助界面

为 README 生成演示截图

仓库里附带了演示数据和截图脚本，后续可以直接重新生成：

bash docs/capture_demo_assets.sh

这个脚本会：

• 重建一个演示用目录
• 跑一次 deskmaid run --mode personal --demo
• 生成整理前、整理后、历史、撤销等 SVG 截图

项目结构

deskmaid/
├── cli.py
├── modes.py
├── interview.py
├── content_reader.py
├── ai_engine.py
├── scanner.py
├── organizer.py
├── config.py
└── undo.py

主要模块说明：

• cli.py：CLI 入口，基于 Typer + Rich
• gui.py：桌面女仆悬浮窗口，支持拖动、右键菜单、设置和历史查看
• service.py：CLI 和 GUI 共用的整理服务层
• ai_engine.py：分类方案生成与文件归类
• scanner.py：目录扫描与结构判断
• organizer.py：实际移动文件并记录事务日志
• undo.py：撤销最近一次整理
• interview.py：个性化模式下的用户画像采集
• content_reader.py：深度模式的文件内容提取

依赖

• Typer
• Rich
• OpenAI Python SDK
• python-docx
• openpyxl
• python-pptx
• pdfplumber

打包为可下载应用

macOS .app + .dmg

项目已附带一个打包脚本：

bash scripts/build_macos_app.sh

它会：

• 安装 PyInstaller
• 生成 dist/DeskMaid.app
• 再打成 dist/DeskMaid.dmg

生成后用户可直接双击 .app 使用，或者分发 .dmg 给其他 macOS 用户下载安装。

Star History

License

MIT