截图粘贴助手（ScreenshotPasteAssistant）

Windows 截图后，你想把图片放进文件夹，却发现 Ctrl+V 没反应，只好先打开画图再保存。这个轻量后台工具让 Win+Shift+S 截图后，在文件夹里 Ctrl+V 就能直接得到图片文件；在 Word 等程序里普通粘贴图片也照常可用。

Windows Explorer cannot normally paste a Win+Shift+S screenshot as a file. This background tool lets you press Ctrl+V in a folder to create the image file, while ordinary image pasting still works.

---

快速开始 / Quick start

git clone https://github.com/awslew/screenshot-paste-assistant.git
cd screenshot-paste-assistant
pip install -r requirements.txt
pythonw main.py

然后：Win+Shift+S 截图 → 打开任意文件夹 → Ctrl+V → 图片文件出现。

git clone https://github.com/awslew/screenshot-paste-assistant.git && cd screenshot-paste-assistant
pip install -r requirements.txt
pythonw main.py          # no console window; use `python main.py` to see logs

Then: Win+Shift+S → open any folder → Ctrl+V.

---

痛点 / Why this exists

Win+Shift+S 截图后，剪贴板里只有位图 / PNG 等图像格式，没有 Windows 资源管理器需要的「文件类」格式（CF_HDROP）。所以你在文件夹里按 Ctrl+V 时，Explorer 没有任何反应。

这个工具在后台监听剪贴板：

• 检测到图片 → 补一个文件类格式（CF_HDROP 指向一张时间戳命名的临时 PNG）
• 同时保留原图像格式（DIB / DIBV5 / PNG）

之后你在任意文件夹 Ctrl+V / 右键粘贴，Explorer 就会把图片当文件复制进去；Word、画图里粘贴图片也照常。

After Win+Shift+S the clipboard only carries bitmap/PNG image formats and no file-class format (CF_HDROP), so Explorer ignores Ctrl+V in a folder. This tool watches the clipboard in the background, re-exposes the image with a CF_HDROP file-class format, and keeps the original image formats — so pasting into a folder (or Word/Paint) just works.

功能 / Features

• 后台常驻，纯监听，无窗口、无托盘（可配置托盘）；仅图片触发，复制文本/文件不干扰

• 截图后任意文件夹 Ctrl+V / 右键粘贴 → 出现 截图_2026-08-03_19-38-38.png，同秒自动加 _1 后缀去重

• 工具启动时也会处理剪贴板上已有的图片（先截图、后启动工具也能粘贴）

• 两种模式：A 补粘贴（默认）/ B 自动保存到目录

• 配置改完保存约 1 秒自动生效；可选开机自启

• Resides in the background with no window (tray optional); only reacts to images

• Paste as file into any folder; auto _1 dedup for same-second screenshots

• Handles an image already on the clipboard at startup

• Mode A = paste-as-file (default); Mode B = auto-save to a folder

• Config hot-reloads ~1s after save; optional autostart

安装 / Install

需要 Windows + Python 3.9+（开发于 3.11）。

cd screenshot-paste-assistant
pip install -r requirements.txt

Requires Windows + Python 3.9+ (developed on 3.11).

运行 / Run

源码运行（无控制台窗口，推荐）：

pythonw main.py

调试时想看到日志，用 python main.py（会带控制台）。首次运行会自动生成 config.json（可参照 config.example.json）。

1. Win+Shift+S 截图
2. 打开任意文件夹 → Ctrl+V → 出现图片文件

停止：taskkill /F /IM ScreenshotPasteAssistant.exe，或在配置里设 "paused": true 临时停用。

Run from source (no console): pythonw main.py. A config.json is auto-created on first run (see config.example.json). Then Win+Shift+S → open a folder → Ctrl+V. Stop with taskkill /F /IM ScreenshotPasteAssistant.exe or "paused": true.

配置 / Configuration

config.json 在程序目录下（源码运行 = 项目根；打包后 = exe 目录）。保存后约 1 秒自动生效。

键	默认	说明
filename_format	截图_%Y-%m-%d_%H-%M-%S	文件名 strftime 模板（不含扩展名）
mode	"A"	A=补粘贴（推荐）；B=自动保存到 save_dir（不重建剪贴板）
save_dir	""	B 模式保存目录；留空 = 自动（当前用户 图片\Screenshots）
temp_dir	""	A 模式临时目录；留空 = 程序目录下 temp（24h 自动清理）
paused	false	true = 暂停（截图不再被处理，Ctrl+V 恢复系统原始行为）
autostart	false	开机自启标记（可在托盘菜单切换）
show_tray	false	true = 显示托盘图标（暂停 / 恢复 / 打开配置 / 自启 / 退出）

Key	Default	Description
filename_format	截图_%Y-%m-%d_%H-%M-%S	strftime filename template (no extension)
mode	"A"	A = paste-as-file (default); B = auto-save to save_dir
save_dir	""	B-mode save dir; empty = Pictures\Screenshots under the current user
temp_dir	""	A-mode temp dir; empty = <program>\temp (auto-cleaned after 24h)
paused	false	true = pause processing
autostart	false	Run at logon (toggleable in the tray menu)
show_tray	false	true = show a tray icon (pause/resume/open config/autostart/quit)

构建 / 自测 / Build & self-test

# 自测（期望最后一行输出 最终判定: PASS）
python tools/selftest_engine.py

# 剪贴板格式侦查
python tools/capture_clipboard.py [--wait N]

# 打包成独立程序（产物 dist\ScreenshotPasteAssistant\）
build.bat

Self-test: python tools/selftest_engine.py (expect 最终判定: PASS). Package with build.bat → dist\ScreenshotPasteAssistant\ (PyInstaller --noconsole --onedir).

已知取舍 / Known trade-offs

• 重建后剪贴板不再包含 Windows 云剪贴板 / OLE 私有格式 → Win+V 云剪贴板、剪贴板历史可能不收录重建内容（Windows 私有格式无法经 SetClipboardData 还原；不影响核心目标）。

• 工具对所有复制到剪贴板的图片都生效（不只是截图）；不需要时在配置里 "paused": true。

• 临时 PNG 采用 COPY 语义（源文件保留），由程序每小时清理 24h 前的文件。

• After rebuilding, Win+V cloud clipboard / clipboard history may not record the content (Windows private OLE formats can't be restored via SetClipboardData; the core goal is unaffected).

• The tool enhances all images copied to the clipboard, not just screenshots. Set "paused": true if not needed.

• Temp PNGs are COPY-semantics and auto-cleaned hourly (files older than 24h).

目录结构 / Layout

clipboard_engine.py   # 剪贴板监听 + 重建核心（隐藏窗口 + WM_CLIPBOARDUPDATE）
main.py               # 入口：组装 config / 引擎 /（可选）托盘
tray.py               # 托盘（show_tray=true 才启用）
config.py             # config.json 读写
autostart.py          # 开机自启（HKCU\...\Run）
build.bat             # PyInstaller 打包
tools/                # capture_clipboard.py / selftest_engine.py
DESIGN.md             # 设计文档（根因 / 接口契约 / 线程模型）
LICENSE               # MIT

🤖 For AI agents

• What it is: a Windows clipboard background daemon. It does not take screenshots — it makes an existing screenshot pasteable as a file. Core trick: add the CF_HDROP file-class format that Explorer requires, while keeping the original DIB/DIBV5/PNG formats.
• How to run: pythonw main.py (no console) or python main.py (with logs). Requires Windows + Python 3.9+.
• How to verify it works: python tools/selftest_engine.py — the last line must print 最终判定: PASS.
• Inspect clipboard formats: python tools/capture_clipboard.py --wait N.
• Package: build.bat → dist\ScreenshotPasteAssistant\ (PyInstaller --noconsole --onedir).
• Config: config.json next to the program (auto-created); hot-reloads ~1s after save. Key: "paused": true disables all processing without quitting.
• Not a screenshot tool: it reacts to any image copied to the clipboard, not only Win+Shift+S.
• Docs index: llms.txt. Contributor/agent conventions: AGENTS.md.

---

常见问题 / FAQ

粘贴出来的图片存在哪？ A 模式（默认）下临时 PNG 落在程序目录的 temp\（每小时清理 24 小时前的文件）， Ctrl+V 时 Explorer 会把它复制到你粘贴的位置——源临时文件保留，可随时删。

为什么 Win+V 剪贴板历史里看不到？ 重建后剪贴板不再包含 Windows 私有 OLE 格式，云剪贴板/历史可能不收录 （见上方「已知取舍」）。这是有意取舍：私有格式无法通过 SetClipboardData 还原， 要保它能粘贴成文件，就只能放弃它。核心目标（Ctrl+V 出文件）不受影响。

我不想让它处理所有复制的图片，能只处理截图吗？ 不能按来源区分（Windows 剪贴板不携带"来自 Win+Shift+S"的标记）。不需要时设 "paused": true，或关掉工具。

能改文件名格式吗？ 可以，filename_format 是 strftime 模板，默认 截图_%Y-%m-%d_%H-%M-%S。 同一秒内多次截图会自动加 _1 后缀去重。

怎么彻底卸载？ 退出程序（托盘菜单，或 taskkill /F /PID <pid>），再删除程序目录。若开过开机自启， 删掉注册表 HKCU\Software\Microsoft\Windows\CurrentVersion\Run 下的对应值即可； 开了托盘的话直接点托盘菜单里的自启开关更省事。

怎么命令行切换开机自启？ python autostart.py —— 注意它是个自测脚本：会依次打印命令值、启用、检查、再禁用， 跑完等于把自启关掉。要持久启用请用托盘菜单开关，或改配置里的 autostart。

为什么托盘图标默认不显示？ 默认 show_tray: false —— 工具设计成"无感常驻"。想看到它（暂停/恢复/自启）就把 show_tray 设为 true。

---

License

MIT — see LICENSE.