# 极简粘贴板

**Repository Path**: user_gitee/miniclipboard

## Basic Information

- **Project Name**: 极简粘贴板
- **Description**: 一款优美、极简的粘贴板工具，粘贴板内容持久化，用来替换windows系统原生难用的粘贴板。
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-01
- **Last Updated**: 2026-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 极简粘贴板 (MiniClipboard)

一款现代化、简约的 Windows 剪贴板历史工具，**替换系统原生难用的剪贴板历史**。

- 技术栈：**Python 3.13.11 + PyQt6**
- 默认全局热键 **Alt+V** 唤起（不与系统冲突）
- 可在设置中切换为 **Win+V**（替换系统剪贴板历史，需重启资源管理器生效）
- 界面、桌面图标、任务栏、系统托盘统一使用 `app.ico`
- 开机自启、单实例运行、关闭窗口收进托盘
- 剪贴板历史持久化，按月份归档，可配置保留时长
- 日志按天分割自动清理
- PyInstaller 打包为绿色单目录 exe（`_internal` 结构），数据与 exe 同级，移动/重命名不受影响

## 功能特性

| 功能 | 说明 |
| --- | --- |
| 全局热键 | 默认 Alt+V 唤起主窗口；设置中可切换 Win+V 或自定义组合键 |
| 设置界面 | 常规 / 热键 / 外观 / 历史 / 日志 / 关于 六个分页 |
| 剪贴板监听 | 自动捕获文本 / 图片（含 Win+Shift+S 截图）/ 文件，双通道（信号 + 轮询兜底），图片内容指纹去重 |
| 历史持久化 | 存入 exe 同级 `history/`，按 `YYYY-MM` 月份子文件夹归档 |
| 历史管理 | 搜索过滤、单击粘贴并收起、右键复制/删除、清空（归档而非删除） |
| 图片预览 | 图片条目直接显示缩略图预览（尺寸、时间） |
| 单实例 | 重复运行自动唤醒已有实例，不重复占用 |
| 系统托盘 | 右键菜单：打开 / 退出；左键单击打开；关闭窗口收进托盘；可设置隐藏托盘图标 |
| 开机自启 | 注册表 HKCU Run 项，可设置开机静默（自启不弹窗仅托盘常驻） |
| 日志系统 | `logs/log_年月日_时分秒_两位串号.log`，按天分割，默认保留 30 天 |
| 现代化 UI | 默认浅色主题（可切深色）、圆角卡片、可配置透明度与置顶 |
| 提示弹窗 | 非模态 15 秒自关闭 Toast 提示 |

## 目录结构

```
MiniClipboard/
├── main.py                    # 程序入口
├── MiniClipboard.spec         # PyInstaller 打包配置（onedir + _internal + 版本信息）
├── build.bat / build.ps1      # 一键打包脚本
├── app.ico                    # 全软件统一图标
├── pyproject.toml / requirements.txt
├── docs/develop_readme.md     # 开发文档
└── src/miniclipboard/
    ├── app.py                 # 应用组装
    ├── paths.py               # 路径解析（exe 同级目录，frozen 感知）
    ├── config.py              # 配置管理（configs/config.json）
    ├── logger.py              # 日志（按天分割 + 两位串号）
    ├── single_instance.py     # 单实例 + 唤醒
    ├── hotkey.py              # Win32 全局热键（ctypes RegisterHotKey）
    ├── clipboard_monitor.py   # 剪贴板监听（文本/图片/文件）
    ├── history.py             # 历史存储（按月归档）
    ├── autostart.py           # 开机自启（支持 --silent 静默）+ 系统剪贴板历史开关
    ├── shortcut.py            # 桌面快捷方式
    └── ui/                    # 主窗口 / 设置窗口 / 托盘 / 主题 / Toast 弹窗
```

## 运行（开发）

```bash
# 需要 Python 3.13+
pip install -r requirements.txt
python main.py
```

## 打包（生成 exe）

```bash
# Windows 下任选其一
build.bat
# 或
powershell -ExecutionPolicy Bypass -File build.ps1
```

产物：`dist/MiniClipboard/MiniClipboard.exe`

```
dist/MiniClipboard/
├── MiniClipboard.exe    # 主程序（右键属性可查看作者 XAF、版本、版权）
└── _internal/           # 依赖与资源（app.ico 在内）
```

首次运行后自动生成：
```
dist/MiniClipboard/
├── configs/config.json  # 配置（可编辑，热键/主题/保留时长等）
├── logs/                # 操作日志（按天分割）
└── history/             # 剪贴板历史（按月份子文件夹归档，图片存 images/）
```

## 设置项（设置窗口，持久化到 configs/config.json）

| 分页 | 配置 | 默认值 | 说明 |
| --- | --- | --- | --- |
| 常规 | 开机自启 | 开 | 注册表 HKCU Run |
| 常规 | 开机启动静默 | 开 | 自启时不显示主窗口，仅常驻托盘 |
| 常规 | 显示系统托盘图标 | 开 | 关闭后只能通过热键/快捷方式打开 |
| 常规 | 启动隐藏 | 关 | 启动后显示主窗口 |
| 常规 | 关闭进托盘 | 开 | 关闭窗口收进托盘而非退出（托盘关闭时直接退出） |
| 热键 | 唤起快捷键 | `Alt+V` | 可切换 Win+V（替换系统剪贴板）/ Ctrl+Alt+V / 自定义 |
| 外观 | 主题 | 浅色 | 浅色 / 深色 |
| 外观 | 窗口置顶 | 开 | 现代化外观 |
| 外观 | 失焦自动隐藏 | 开 | 点击窗口外部自动收进托盘 |
| 外观 | 粘贴后收起 | 开 | 粘贴完成后自动收起窗口（关闭则粘贴后窗口保持显示） |
| 外观 | 透明度 | 100% | 50% = 半透明，100% = 不透明（线性映射） |
| 历史 | 显示最近 | 1 个月 | 下拉可选 1/3/6/12 个月或全部显示 |
| 历史 | 历史保留 | 1 个月 | 下拉可选 1/3/6/12/24 个月或全部保留 |
| 历史 | 单条最大长度 | 10 万字符 | 下拉可选 1万/10万/50万/100万或不限制 |
| 历史 | 记录图片 / 连续去重 / 忽略安全输入 | 开 | 智能捕获 |
| 日志 | 保留天数 | 30 天 | 下拉可选 7/30/90/180/365 天或全部保留 |
| 日志 | 级别 | INFO | DEBUG/INFO/WARNING/ERROR |
| 关于 | 版本号 | v1.4.0 | 当前软件版本 |

修改配置后无需重启，保存即生效（热键、主题等实时应用）。

> 注：0 值语义——历史"全部显示/全部保留"、单条"不限制"、日志"全部保留"均以 0 存储。

## 常见问题

- **Alt+V 弹不出窗口？** 检查是否被其他软件占用；设置中可换 Win+V 或自定义组合键。
- **截图没进历史？** 已支持 Win+Shift+S 等截图（图片存入 `history/YYYY-MM/images/`）。若仍无记录，检查设置中"记录图片"是否开启。
- **Win+V 选项有什么用？** Win+V 是系统剪贴板历史的快捷键。选择它后程序会禁用系统剪贴板历史并提示重启资源管理器，之后 Win+V 归本软件使用。
- **清空后历史还在吗？** 清空是把当前全部记录【归档】：界面立即不再显示，下次打开也不显示；历史文件完整保留在 `history/archived/` 目录中（可手工恢复），并非物理删除。
- **托盘图标不见了？** 在 设置 → 常规 中开启了「显示系统托盘图标」，关闭后可通过热键（Alt+V）或桌面快捷方式打开主窗口。
- **开机不弹窗？** 设置了「开机启动静默」后，自启只常驻托盘不显示窗口（手动运行仍正常弹窗）。
- **exe 可以移动吗？** 可以。所有数据（configs/logs/history）都在 exe 同级目录，程序通过 `sys.executable` 定位自身真实路径，与 `_internal` 无关。

## 开发文档

详见 [docs/develop_readme.md](docs/develop_readme.md)

## License

MIT License — © XAF 2026.9