mysphinx-snip 0.0.1

A cross-platform desktop screenshot tool (region capture, annotation, pin-to-screen).

mysphinx-snip

一个用 Python + PySide6 实现的跨平台桌面截图工具。

功能（v0.0.1）

• 区域截图：拖拽框选屏幕区域，支持框选后移动 / 缩放（八个手柄）。
• 标注工具：矩形、椭圆、箭头、画笔、文字、马赛克、高亮、序号，支持 撤销 / 重做（Ctrl+Z / Ctrl+Y），可调颜色与线宽。
• 输出：复制到剪贴板、保存为 PNG/JPEG（自动按时间戳命名）。
• 贴图：把截图钉在屏幕最上层的悬浮窗，可拖动、滚轮缩放、右键菜单 （复制 / 保存 / 不透明度 / 关闭）。
• 系统托盘 + 全局热键：默认 Ctrl+Shift+A（macOS 为 Cmd+Shift+A）。
• 多显示器 / HiDPI：每块屏幕一个覆盖层，按 device-pixel-ratio 输出物理像素。

暂未实现（后续迭代）：长截图、录屏（MP4/GIF）、带壳截图、OCR/AI、截图历史回溯。

安装

pip install -e .          # 或者：pip install -r requirements.txt

运行

mysphinx-snip             # 安装后提供的命令
# 或
python -m snip

启动后程序常驻系统托盘。点击托盘图标或按全局热键即可开始截图。

截图操作

1. 触发后屏幕变暗，拖拽框选要截取的区域。
2. 选区下方出现工具条：选择标注工具进行标注（未选工具时可移动/缩放选区）。
3. 点击 复制 / 保存 / 贴图，或按 Enter 复制、Esc 取消。

平台说明

• macOS：需要在 系统设置 → 隐私与安全性 授予两类权限：
  • 屏幕录制（必需）：否则截到的图只有壁纸、没有窗口内容。首次运行会自动弹出授权请求。
  • 辅助功能（仅全局热键需要）：否则会看到 This process is not trusted! ... 且 Cmd+Shift+A 无效。 权限要授给运行本程序的那个应用——从终端启动就是 Terminal/iTerm（打包成 .app 后则是该 App）。 授权后必须完全退出并重启该终端/App 才会生效。

    提示：即使没开热键，也可以直接点菜单栏图标 →「截图」 使用；菜单里的 「权限设置…」可一键打开对应的系统设置面板。 已知限制：覆盖层无法盖住系统菜单栏区域（普通窗口层级限制），不影响其余区域截图。

• Windows：进程默认开启 Per-Monitor v2 DPI 感知，HiDPI 下输出清晰。
• Linux：X11 下可用；Wayland 对全屏覆盖层与全局热键支持有限（非主要目标平台）。

开发

pip install -e ".[dev]"
QT_QPA_PLATFORM=offscreen pytest      # 标注模型与逻辑层单测，无需真实显示

项目结构

snip/
  app.py          # 入口：系统托盘、全局热键、截图流程编排
  capture.py      # 屏幕抓取（QScreen.grabWindow → QPixmap，多屏 / HiDPI）
  overlay.py      # 全屏选区覆盖层 + 实时标注交互
  toolbar.py      # 选区浮动工具条
  annotations.py  # 标注数据模型 + 渲染 + 撤销/重做（纯逻辑，可单测）
  pin.py          # 贴图悬浮窗
  config.py       # 配置（QSettings）