# snapforge **Repository Path**: kill-life/snapforge ## Basic Information - **Project Name**: snapforge - **Description**: SnapForge · 闪构 · 免费开源的 Linux 截图 · 标注 · 贴图 · 录屏 · 取字一体化工具 - **Primary Language**: Unknown - **License**: GPL-3.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-11 - **Last Updated**: 2026-10-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
# SnapForge · 闪构 SnapForge 应用图标 **免费开源的 Linux 截图 · 标注 · 贴图 · 录屏 · 取字一体化工具** 把 PixPin、iShot、Snipaste 各自的杀手锏合到一个工具里，为 Linux 桌面补齐那块长期缺失的拼图。 [![版本](https://img.shields.io/badge/version-1.0.1-0A84FF)](pyproject.toml) [![许可证](https://img.shields.io/badge/license-GPL--3.0--or--later-32D74B)](LICENSE) [![平台](https://img.shields.io/badge/platform-Linux%20%7C%20X11%E4%BC%9A%E8%AF%9D%20%7C%20KDE%2FGNOME%2FXfce-FFD60A)](#系统要求) [![测试](https://img.shields.io/badge/tests-673%20passed%20%7C%201%20skipped-32D74B)](tests) [![依赖](https://img.shields.io/badge/%E4%BE%9D%E8%B5%96-%E9%9B%B6%20sudo%20%C2%B7%20%E7%BA%AF%20Python-9C9CAB)](#安装) 简体中文 | [English](#english)
--- ## 初心 Linux 上不缺截图工具，缺的是**一个把事做完的工具**。调研 102 个竞品功能点、46 张对比表后结论明确：**没有任何一款 Linux 工具能同时做好「截图 / 标注 / 贴图 / 录屏 / OCR / 滚动长截图」六件事。** | 工具 | 截图 | 标注 | 贴图钉屏 | 录屏 | OCR | 滚动长截图 | 评价 | |---|:--:|:--:|:--:|:--:|:--:|:--:|---| | Flameshot | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | 标注体验好，但没有贴图/录屏/取字 | | Spectacle (KDE) | ✅ | ⚠️ | ❌ | ⚠️ | ❌ | ❌ | 截图稳，标注弱，无贴图 | | GNOME Screenshot | ✅ | ❌ | ❌ | ⚠️ | ❌ | ❌ | 太基础 | | Shutter | ✅ | ✅ | ❌ | ❌ | ⚠️ | ❌ | 维护缓慢，依赖重（Perl + 大量 GTK 模块） | | Snipaste (Windows/macOS) | ✅ | ✅ | ✅ | ❌ | ⚠️ | ❌ | 贴图是标杆，但 Linux 版缺位 | | PixPin (Windows) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 功能标杆，闭源且只有 Windows | | **SnapForge** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | **六项全绿，免费开源，零 sudo 依赖** | SnapForge 不是又一个截图工具，而是把上述工具各自的优点**集成于一体**。 --- ## 功能一览 ### 📷 截图 - **区域 / 窗口 / 全屏 / 延时 / 上次区域重截 / 剪贴板导入** - 区域截图：全屏冻结、放大镜像素级取色、边缘吸附、悬停自动高亮窗口 - 窗口截图：XComposite 抓取**未被遮挡的完整窗口**（被其他窗口压住也能抓全） - 多显示器与 HiDPI 混合缩放正确处理（内部统一使用虚拟桌面原生像素坐标系） ### ✏️ 就地标注（12 种工具） - 矩形、椭圆、箭头、直线、画笔、荧光笔、文字、序号、马赛克、模糊、色块遮挡、聚光灯 - 遮罩上直接画，不用先开编辑器；画完可继续选中、移动、缩放、改色改粗细 - 两级工具条：同类工具收进一个按钮，属性条只显示当前工具用得上的属性；**每个工具独立记忆自己的样式** - 马赛克 / 模糊从**原图采样**，不会把已画标注再打码；序号自动递增；`Shift` 约束正方形与 45° 直线 ### 🎨 编辑器 - 裁剪、旋转 90°、水平/垂直翻转、等比缩放，**全部可撤销**（裁剪无损贴回原画布） - **美化外框**：圆角 / 内边距 / 阴影 / 背景（渐变、纯色、毛玻璃、壁纸），6 套渐变预设 - **水印**：文字或图片、九宫格定位、透明度、平铺防搬运 - 导出 PNG / JPEG / WebP / BMP / TIFF，文件名模板 `{date} {time} {datetime} {seq} {app} {type}` ### 📌 贴图钉屏 - 截图"钉"在屏幕当参考：拖动、滚轮缩放、`Ctrl+滚轮` 透明度、`Shift+滚轮` 旋转、边缘拉伸手柄、悬停浮出小工具条 - **鼠标穿透**、多张贴图自动吸附对齐、退出后自动恢复上次的贴图 ### 🎬 录屏与 GIF 编辑 - MP4 / MKV / WebM / **GIF**，画质三档（高清文字 / 平衡 / 小体积）、帧率与 CRF 可调、**硬件编码自动探测**（VAAPI / NVENC）、系统声音 + 麦克风混音、倒计时、录制中浮动控制条 - GIF 高保真管线：crf 18 + yuv444p 保文字边缘，自动选用 [gifski](https://gif.ski) 逐帧调色板（体积约 1/4），默认**原始尺寸不缩放** —— 录文档/代码不糊字 - **GIF 编辑器**：帧时间线 Ctrl/Shift 多选删段、删除重复帧（观感不变、体积大降）、变速 0.25×–4×、逐帧延时、隔帧抽稀、预览上直接拖框裁剪，全部可撤销 ### 🧵 滚动长截图（**你滚，我们拼**） - 框选内容区 → **你自己滚动滚轮** → 实时看到长图长起来 → 点「完成」 - **不盖全屏遮罩、不注入滚轮事件**：目标窗口保持焦点，滚轮自然送达，抓帧天然干净 - 观测式静止抓帧：画面静止才抓帧，XShm 零拷贝（0.41 ms/帧）、模板级联匹配 + 逐像素一致性校验、吸顶/吸底固定元素只保留一次、回滚自动回退、匹配失败插**看得见的橙色缺口带** - 实测 12 个场景（慢滚/快滚/周期页/回滚等）与真值**逐像素一致**（`tests/test_scroll_engine.py`） ### 🔍 OCR 取字（两种模式） - **本地引擎（默认，完全离线）**：RapidOCR 模型直接打进 wheel（16MB），无需联网、无需系统依赖；也支持 Tesseract - **多模态大模型（可选）**：不只认字，还能还原**版面结构** —— 标题层级、列表、表格、代码块，直接输出规范 **Markdown**；支持 OpenAI 兼容协议 / Claude / Ollama（本地模型，数据不出本机） - **安全兜底**：`auto` 后端只在本地引擎里挑，配了 Key 也不会偷偷把截图发出去；大模型失败时自动回退本地识别 ### 🗂 截图库 · 托盘 · CLI - SQLite 截图库：卡片网格、**全文搜索（含 OCR 文本）**、收藏、批量操作、分段类型筛选、清理策略 - 系统托盘常驻 + 15 个可自定义**全局快捷键**（XGrabKey 实现，不依赖 D-Bus） - 单实例 + IPC（脚本调用转发给已运行实例并取回结果）、完整 CLI 与 `--json` 输出 --- ## 界面预览 | 截图遮罩与就地标注 | 截图库 | |---|---| | ![遮罩](docs/images/01-截图遮罩与就地标注.png) | ![截图库](docs/images/07-截图库.png) | | 编辑器 · 多工具标注 | 编辑器 · 美化 | |---|---| | ![标注](docs/images/04-编辑器-多工具标注.png) | ![美化](docs/images/05-编辑器-美化面板.png) | | 贴图钉屏 | 滚动长截图 | |---|---| | ![贴图](docs/images/09-贴图钉屏.png) | ![长截图](docs/images/15-长截图-用户驱动.png) | | OCR 取字 | 设置 | |---|---| | ![OCR](docs/images/10-OCR取字.png) | ![设置](docs/images/08-设置-通用.png) | > 以上截图由 `python3 tools/make_screenshots.py` 从**真实运行的程序**离屏渲染生成，可随时重新生成。 --- ## 安装 **推荐：用户级安装脚本（零 sudo，装到 `~/.local`，含启动器、桌面菜单项与图标）** ```bash git clone https://github.com/snapforge/snapforge.git cd snapforge bash packaging/install.sh ``` ```bash bash packaging/install.sh --uninstall # 卸载（保留配置与历史） PREFIX=/opt/snapforge bash packaging/install.sh # 自定义前缀 ``` **其它分发形式**（产物在 `dist/`）： | 形式 | 构建 | 安装 / 使用 | |---|---|---| | Debian 包 | `bash packaging/build_deb.sh` | `sudo apt install ./dist/snapforge_1.0.1_all.deb` | | AppImage | `bash packaging/build_appimage.sh` | 便携单文件，拷到哪都能跑 | | Python 包 | `bash packaging/build_wheel.sh` | `pip install dist/snapforge-1.0.1-py3-none-any.whl` 后 `snapforge --install-desktop` | | 从源码运行 | `pip install --user PySide6 Pillow` | `python3 -m snapforge --help` | > SnapForge 运行在**独立的 uv venv** 中：实测 conda 自带的 Qt6 二进制会与 pip 安装的 PySide6 冲突（QtWebEngine 一 import 就段错误），系统 Python 环境又不可控。安装脚本按顺序复用 `~/.local/share/snapforge/.venv` → 项目目录 `.venv` → 新建 `uv venv --python 3.12`，无需手工干预。 **可选增强**（缺失只影响对应功能，不影响主流程）： | 能力 | 安装方式 | 缺失后果 | |---|---|---| | 录屏 | `sudo apt install ffmpeg` | 录屏功能自动隐藏并提示 | | 长截图加速 | `pip install numpy opencv-python-headless` | 回退到纯 Python 拼接（慢但仍可用） | | OCR 取字 | `pip install rapidocr-onnxruntime` | 提示改用 Tesseract 或安装命令 | | OCR 系统引擎 | `sudo apt install tesseract-ocr tesseract-ocr-chi-sim` | 同上 | | 全局快捷键 / 窗口识别 | X11 会话（libX11 等桌面发行版自带） | Wayland 下降级，见[常见问题](#常见问题) | 安装后自检：`snapforge info` --- ## 5 分钟上手 1. **按 `Ctrl+Alt+A`**（或托盘图标 → 区域截图）：屏幕冻结，出现截图遮罩。 2. **拖拽选择区域** —— 放大镜跟随光标显示像素与色值，悬停时自动高亮整个窗口，单击即选中该窗口。 3. **就地标注**：直接点工具条上的工具画就行，画错了 `Ctrl+Z`。 4. **选一个动作**： - `Enter` / `Ctrl+C` 复制（粘到聊天工具是图、粘到终端是路径） - `Ctrl+S` 保存 · `Ctrl+T` 贴到屏幕 · `Ctrl+E` 进编辑器精修 · `Ctrl+O` 提取文字 - `Ctrl+Alt+L` 滚动长截图 · `Ctrl+Alt+S` 区域录屏 5. **`Ctrl+Alt+H`** 打开截图库，找回历史截图。 --- ## 默认快捷键 全局快捷键（X11 下由 `XGrabKey` 注册，可在 **设置 → 快捷键** 逐条修改，留空则不注册；与其它程序冲突时会记为注册失败并提示，换个组合即可）： | 功能 | 默认组合 | 功能 | 默认组合 | |---|---|---|---| | 区域截图 | `Ctrl+Alt+A` | 区域录屏 | `Ctrl+Alt+S` | | 全屏截图 | `Ctrl+Alt+F` | 全屏录屏 | `Ctrl+Alt+Shift+S` | | 窗口截图 | `Ctrl+Alt+W` | 开始/停止录制 | `Ctrl+Alt+P` | | 重复上次区域 | `Ctrl+Alt+R` | 滚动长截图 | `Ctrl+Alt+L` | | 延时截图 | `Ctrl+Alt+D` | OCR 取字 | `Ctrl+Alt+O` | | 贴图（剪贴板） | `Ctrl+Alt+V` | OCR（剪贴板） | `Ctrl+Alt+Shift+O` | | 打开截图库 | `Ctrl+Alt+H` | 打开设置 | `Ctrl+Alt+,` | | 显示/隐藏全部贴图 | `Ctrl+Alt+X` | | | 截图遮罩内（无需记忆，工具条上有提示）： | 按键 | 作用 | 按键 | 作用 | |---|---|---|---| | `R` / `E` / `A` / `L` | 矩形 / 椭圆 / 箭头 / 直线 | `Ctrl+C` | 复制到剪贴板 | | `P` / `H` | 画笔 / 荧光笔 | `Ctrl+S` | 保存 | | `T` / `N` | 文字 / 序号 | `Ctrl+E` | 进编辑器 | | `M` / `B` / `D` | 马赛克 / 模糊 / 色块遮挡 | `Ctrl+T` / `Ctrl+P` | 贴到屏幕 | | `V` | 选择/移动已画标注 | `Ctrl+O` / `O` | 提取文字 (OCR) | | `Ctrl+A` | 全选当前屏幕 | `Ctrl+R` | 开始录屏 | | `Ctrl+Z` / `Ctrl+Shift+Z` / `Ctrl+Y` | 撤销 / 重做 | `Ctrl+L` | 滚动长截图 | | `Tab` | 切换"悬停识别窗口"模式 | `Delete` | 删除选中标注 | | `Enter` | 确认（默认复制） | `←↑→↓` | 微调选区（`Shift` 加速） | | `Esc` | 取消截图 | | | 编辑器内：`Ctrl+C/S/Shift+S` 复制/保存/另存为，`Ctrl+Z` / `Ctrl+Y` 撤销重做，`Ctrl+0` 适应窗口、`Ctrl+1` 实际大小、`Ctrl++/-` 缩放，`Ctrl+B` 显隐侧栏，`C` 裁剪。 贴图内：滚轮缩放、`Ctrl+滚轮` 透明度、`Shift+滚轮` 旋转、`Ctrl+C/S` 复制/保存、`Esc` 关闭、方向键微调。 --- ## 命令行接口 ```bash snapforge info # 环境与能力自检 snapforge capture --mode region # 区域截图（自动转发给托盘实例） snapforge capture --region 100,100,800,600 # 直接抓指定区域，无需交互，适合脚本 snapforge capture --mode monitor --monitor 1 # 指定显示器；--screen HDMI-1-0|1|cursor|primary 限定某屏 snapforge capture -d 5 --json # 延时截图，JSON 输出便于脚本消费 snapforge record --pick-region -t 10 -o demo.mp4 # 交互选区录制 10 秒 snapforge record --region 0,0,1280,720 --fps 60 --audio system snapforge record --format gif -t 6 # 直接录 GIF snapforge ocr --file shot.png --markdown # OCR 并输出 Markdown；--clipboard 识别剪贴板 snapforge scroll --region-picker # 长截图（CLI 路径用 XTest 合成滚轮，桌面交互走「用户自己滚」引擎） snapforge pin --file shot.png # 把图片贴到屏幕上 snapforge history --search 发票 --json # 搜索历史 snapforge settings --set save.format=webp # 命令行改配置 snapforge --tray # 托盘常驻，不弹主窗口 ``` 完整命令见 `snapforge --help`。 --- ## 托盘与常驻 SnapForge 是**托盘常驻型**工具：关掉所有窗口仍在后台待命，快捷键随时可用。托盘走现代 **StatusNotifierItem (D-Bus)** 协议，KDE Plasma、GNOME（需 AppIndicator 扩展）、Xfce、Cinnamon、MATE 均支持。 | 操作 | 效果 | |---|---| | 左键单击 | 直接开始区域截图 | | 双击 | 打开截图库主窗口 | | 右键 | 完整菜单：截图 / 录屏 / 长截图 / 取字 / 贴图管理 / 设置 / 退出 | ```bash snapforge --tray # 驻留托盘，不弹主窗口 snapforge settings --set general.autostart=true # 开机自动驻留（写 XDG autostart） ``` > **没看到图标？** KDE 默认把新托盘图标收进右下角 `∧` 箭头里；想常驻可见：右键托盘 → 配置系统托盘 → SnapForge → 可见性改为"始终显示"。桌面环境没有托盘时，程序自动退化为普通窗口应用并打印明确日志。 --- ## 多显示器 默认在**所有屏幕**显示截图遮罩，一条选区可跨屏。只想操作某一屏时： ```bash snapforge capture --screen HDMI-1-0 # 屏幕名（xrandr 里的名字）/ 序号 / cursor / primary snapforge settings --set capture.overlay_monitor=HDMI-1-0 # 设为默认 ``` 限定屏幕后，遮罩只出现在该屏上，选区被限制在该屏内，"全屏截图"的含义也变成只截这块屏。 --- ## 配置与数据目录 | 用途 | 路径 | 说明 | |---|---|---| | 配置 | `${XDG_CONFIG_HOME:-~/.config}/snapforge/config.json` | 原子写入，损坏时自动备份并回落默认值 | | 历史原图 | `${XDG_DATA_HOME:-~/.local/share}/snapforge/history/` | 可用文件管理器直接管理 | | 历史索引 | `…/snapforge/history.db` | SQLite（WAL 模式） | | 缩略图 | `${XDG_CACHE_HOME:-~/.cache}/snapforge/thumbs/` | 可安全删除 | | 日志 | `…/snapforge/logs/snapforge.log` | 轮转日志，`--log DEBUG` 开调试 | | 贴图状态 | `…/snapforge/pins.json` | 退出后下次启动恢复贴图 | 所有路径都可用环境变量 `SNAPFORGE_HOME` 整体重定向（便于测试与便携部署）。 --- ## 设计取舍 - **ctypes 直调 libX11**（而非 python-xlib / mss）：抓屏是热点路径，2560×1440 约 32 ms，比走 Python 层封装快数倍，且零额外依赖。 - **遮罩与编辑器共用自绘渲染器**：保证"遮罩里看到的"和"编辑器导出的"像素一致（所见即所得），并精确控制 HiDPI 变换与马赛克采样源。 - **零 sudo**：面向桌面用户，所有能力走 ctypes + 可选 pip 依赖；缺依赖时功能优雅降级并给出可操作提示，而不是崩掉。 - **统一原生像素坐标系**：规避 Qt 在 X11 上"位置为原生像素、尺寸为逻辑像素"的混合坐标系，多屏 + HiDPI 错位问题在架构上一次解决。 - **主界面用 QML 而非 Electron / Flutter**：截图遮罩必须用 override-redirect 窗口绕过窗口管理器并逐像素透明 —— Flutter 无公开窗口 API（[#66751](https://github.com/flutter/flutter/issues/66751) 挂了 5 年），Electron 的 overlay 库自认在 Linux 上做不到（[electron-overlay-window#48](https://github.com/SnosMe/electron-overlay-window/issues/48)）；QML 与 Python 核心同进程、零打包增量，一套技术栈一种观感。 - **性能与可访问性**：设计令牌构建期确定性生成，运行期零文件 IO；83 对前景/背景的 WCAG 对比度在测试里自算达标，标注色板通过色盲模拟验证；遮罩局部重绘实测 7.43 ms → **2.52 ms（3.0×）**。 - **已知限制**：X11 下录屏暂停采用 SIGSTOP 暂停 ffmpeg 管道，恢复后文件时长与界面计时存在偏差；全屏录制无法排除控制条（X11 无窗口排除机制），建议区域录屏。 --- ## 系统要求 | 项目 | 要求 | |---|---| | 系统 | Linux（Ubuntu 22.04+ / Debian 12+ / 其它现代发行版） | | 桌面 | **X11 会话**（KDE Plasma / GNOME / Xfce / Cinnamon / MATE / i3 等） | | Python | 3.10+（已在 3.13 上验证） | | 图形 | PySide6 ≥ 6.5（Qt 6） | | 必需库 | libX11 / libXtst / libXfixes（绝大多数桌面发行版自带） | | 可选 | ffmpeg（录屏）、numpy + opencv（长截图加速）、rapidocr 或 tesseract（取字） | **Wayland**：应用可以启动，但能力**大幅降级** —— 全局快捷键、窗口识别、模拟输入、滚动长截图不可用，且只能拍到 XWayland 应用。应用会在 `snapforge info` 与界面能力提示里如实汇报，不会假装支持。**追求完整体验请使用 X11 会话**（登录界面右下角可切换）。 --- ## 常见问题
按快捷键没反应 1. 确认程序在运行：托盘里应有 SnapForge 图标（`snapforge --tray`）。 2. 跑 `snapforge info` 看「全局快捷键」是否为 ✓（Wayland 下会是 ✗）。 3. 组合被别的程序占用了：`snapforge --log DEBUG` 启动，日志里会写哪一条注册失败；或在 `设置 → 快捷键` 页底部查看冲突提示，换一个组合。
录屏没有声音 - `snapforge info` 看「音频」是否为 ✓；需要 PulseAudio 或 PipeWire。 - `设置 → 录屏 → 音源` 选「系统声音」录 monitor 源；麦克风选「麦克风」。 - 带音频录制开头有 0.3~0.5 秒空档（ffmpeg 打开 pulse 设备耗时），属已知行为。
长截图拼不上，或者中途就停了 前提是页面能**整体平移**。固定布局、内部独立滚动容器、视频/聊天流式更新、滚动条到底时会正确判停而不是拼出重影。 其它检查项：鼠标要能落在可滚动区域上（程序会把指针移到选区中心再滚动）；滚动步长不能超过单帧高度的 87.5%；页面动画会让匹配失败，等它停一停再试。
OCR 不可用 / 识别不准 - 推荐离线引擎：`python3 -m pip install rapidocr-onnxruntime`（中英文，无需联网）。 - 或系统引擎：`sudo apt install tesseract-ocr tesseract-ocr-chi-sim`。 - 小字识别不准：保持 `设置 → 文字识别 → 图像预处理` 开启。 - RapidOCR 内置模型固定为中英文；日/韩/俄等需要 Tesseract 及其语言包。
HiDPI / 多屏下位置错位 请反馈 `snapforge info --json` 与 `xrandr --listmonitors` 的输出。项目内部已统一到原生像素坐标系，若仍有错位属于环境特例，日志（`--log DEBUG`）会打印每个遮罩窗口的逻辑/原生偏移与 dpr，便于定位。
全屏录屏把控制条录进去了 X11 没有"窗口排除"机制，全屏录制时控制条必然出现在画面里。请改用**区域录屏**，或在 `设置 → 录屏` 里关闭「显示浮动控制条」（改用快捷键 `Ctrl+Alt+P` 停止录制）。
贴图"看不见"了 可能开了**鼠标穿透**。用 `Ctrl+Alt+X` 显示/隐藏全部贴图，或托盘右键 →「贴图管理 → 关闭鼠标穿透」。
粘贴到别处没有图片 SnapForge 复制时同时写入图片、文本路径与文件 URI 三种格式；若目标程序仍拿不到图片，请确认它在 X11 剪贴板可用（部分沙箱应用需要通过文件路径粘贴），也可以先保存成文件再粘贴。
--- ## 开发 ```bash git clone https://github.com/snapforge/snapforge.git cd snapforge python3 -m pip install --user -e ".[dev,fast,ocr]" python3 -m pytest tests/ -q # 673 passed, 1 skipped（默认 offscreen，无需显示器） DISPLAY=:0 python3 -m pytest tests/ -q # 真机用例（录屏等）会自动启用 python3 tools/make_screenshots.py # 重新生成文档截图 python3 tools/gui_smoke.py # 开一遍所有窗口并做像素校验 python3 -m snapforge --log DEBUG # 调试运行 # 滚动长截图端到端（真实窗口 + 真实 XTest 滚轮，自动预检滚轮送达） xvfb-run -a -s "-screen 0 2560x1440x24" python3 tools/e2e_scroll_capture.py --steps 14 --clicks 5 # CI 虚拟显示 DISPLAY=:0 python3 tools/e2e_scroll_capture.py --steps 10 --clicks 3 --max-gaps 2 # 真机 # 已安装实例的增量更新（rsync 源码 → 复用 venv → 刷新启动器 → 冒烟验证） bash packaging/update.sh --check # 只看差异 bash packaging/update.sh --restart # 停实例 → 更新 → 重启托盘 ``` ### 目录结构 ``` snapforge/ ├── core/ # 与界面无关的领域层 │ ├── x11.py # ctypes 原生 X11：抓屏/窗口枚举/XTest/XFixes/XGrabKey │ ├── capture/ # 抓屏后端（原生 X11 / Qt / Wayland）与图像工具 │ ├── annotate.py # 标注数据模型 + 渲染器（遮罩与编辑器共用） │ ├── decorate.py # 美化外框与水印 │ ├── exporter.py # 导出与格式处理 │ ├── recorder.py # 录屏（ffmpeg 编排） │ ├── scrollshot.py # 滚动长截图与拼接算法 │ ├── ocr/ # OCR 后端（rapidocr / tesseract） │ ├── history.py # SQLite 历史库 │ ├── ipc.py # 单实例与进程间通信 │ ├── config.py # 配置树（11 个分类）+ 原子读写 │ └── platform.py # 能力探测 ├── ui/ # 界面层 │ ├── overlay/ # 截图遮罩 + 浮动工具条 │ ├── editor/ # 编辑器窗口 / 画布 / 侧栏面板 │ ├── widgets/ # 主题化控件、无边框窗口、气泡、倒计时… │ ├── theme.py # 设计令牌与样式表 │ ├── icons.py # 104 个内联 SVG 图标 │ └── … # 贴图、截图库、设置、OCR、录屏界面 ├── app.py # 应用控制器（托盘/热键/流程编排） ├── cli.py # 命令行 tests/ # pytest（默认 offscreen 可跑） tools/ # 开发与验证脚本 docs/ # 调研 / PRD / 架构 / UI 规范 / 手册 / 子系统设计 packaging/ # 安装脚本、deb/AppImage 构建、桌面项、图标生成 ``` --- ## 文档 完整设计文档（竞品调研、PRD、架构设计、UI/视觉规范、录屏与长截图算法等 13 篇）由作者本机维护，不随本仓库分发；`docs/images/` 保存 README 引用的配图。 --- ## 许可证 [GPL-3.0-or-later](LICENSE)。可自由使用、修改、分发；衍生作品需同样开源。 ---
## English **SnapForge** is a free and open-source screenshot suite for Linux (X11), bringing screenshot, annotation, pin-to-screen, screen recording, OCR and scrolling capture into one tool — the combination that no Linux screenshot utility currently offers. ```bash bash packaging/install.sh # user-level install, no sudo required snapforge info # capability self-check snapforge --help # CLI overview ``` Everything (including the UI) speaks Chinese; the codebase and CLI are documented in Chinese with English identifiers. Released under GPL-3.0-or-later. Issues and PRs are welcome.