# jietuba
**Repository Path**: songyulining/jietuba
## Basic Information
- **Project Name**: jietuba
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master2
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-28
- **Last Updated**: 2026-10-15
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
**[中文](README_zh-CN.md)** | [English](README.md) | [日本語](README_JA.md)
# 截图吧 — Windows 截图、OCR、钉图、翻译与剪贴板工具
[](https://github.com/1003129155/jietuba/actions/workflows/ci.yml) [](LICENSE) [](https://github.com/1003129155/jietuba/releases/latest) 
[下载 Windows 版](https://github.com/1003129155/jietuba/releases/latest) · [源码运行](#source-setup) · [开发与测试](#development)
## 项目简介
截图吧是一款免费开源的 Windows 截图工具：区域与窗口截图、滚动长截图拼接、标注、OCR 文字识别、翻译、钉图、GIF 录制、二维码/条形码识别、PDF 导出，以及完整的剪贴板历史管理。所有功能本地运行。
界面使用 PySide6 构建，图像处理、剪贴板操作和 OCR 由 Rust 实现，支持 Windows x86_64 与 ARM64。
提供可直接运行的 Windows 发行包，也支持从源码运行。
---
## 核心亮点
"截图 ⇄ 剪贴板 ⇄ 钉图"三向互通的顺滑体验
- **任意来源自动入史**：不只是自己截的图，复制的任何文本/图片/文件/html，都会自动进入同一份剪贴板历史，可分组永久保存一键导出多设备共享
- **历史 → 钉图 → 继续工作**：历史记录里的任何一张图，都能一键“钉”回屏幕最前端。随时拿来对照、缩放、继续标注、重新 OCR。
- **功能打磨到细节**：滚动截图支持上下左右全方向毫秒级精准拼接，多屏幕、多 DPI感知无缝截图，导出各种编码图片。各功能都比肩付费软件甚至更好。
- **内存占用**：有严格的运行内存设计，连续复杂使用场景下常驻内存也占用可以被压到非常低水平（往往仅在十几 MB 甚至几 MB 级别）
- **流畅 UI**：优化各种吃配置的场景，减少cpu占用让低配电脑也可以流畅使用
- **数据安全**：功能完全本地运行，无数据收集、无偷偷联网，数据全部保存在本地；翻译是唯一需要联网的功能，仅在你主动使用时调用你自己选择的第三方翻译 API
---
## 下载与使用
普通用户可以直接使用对应架构的 Windows x86_64 或 ARM64 发行包，无需安装 Python、Rust 或配置开发环境。
1. 打开 [Releases 下载页](https://github.com/1003129155/jietuba/releases/latest)，根据设备下载以 `-x64.zip` 或 `-arm64.zip` 结尾的程序包。
2. 完整解压压缩包，保留 `jietuba_pp.exe` 和同级的 `models/` 目录。
3. 双击 `jietuba_pp.exe` 启动程序。OCR 所需模型已随程序包提供。
4. 程序尚未进行数字签名，通过浏览器下载后，Windows 可能显示运行警告。出现提示时，点击“更多信息”，再选择“仍要运行”即可启动。
---
## 从源码运行
所有运行依赖均通过 [requirements.txt](requirements.txt) 统一安装。
### 一键安装
1. 先安装与系统架构一致的 Python 3.11（x64 或 ARM64，包含 Python Launcher）
2. 下载并解压或克隆本仓库，在项目根目录双击 [setup.bat](setup.bat)。
### 手动安装
先安装与系统架构一致的 Python 3.11（x64 或 ARM64，包含 Python Launcher），再在项目根目录打开 Windows 命令提示符（CMD），依次执行：
**1. 创建并激活虚拟环境**
```bat
py -3.11 -m venv venv311
call venv311\Scripts\activate.bat
```
**2. 安装全部运行依赖**
```bat
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```
**3. 运行程序**
```bat
cd main
python main_app.py
```
OCR 模型已放在仓库的 [models/](models/) 目录中，包括 `PP-OCRv6_det_small.onnx` 和 `PP-OCRv6_rec_small.onnx`，保留该目录即可使用。
### Rust 扩展包
以下四个包已包含在 `requirements.txt` 中，会在安装运行依赖时一并安装。它们可以独立使用，源码位于 [rust_libs/](rust_libs/)。PyPI 发行名与 Python 的 import 名对应如下：
| pip 包名 | import 名 | 版本 | 功能 |
|------|------|------|------|
| [`j-gif`](https://pypi.org/project/j-gif/) | `gifrecorder` | 0.3.1 | GIF/视频合成编码器 |
| [`j-stitch`](https://pypi.org/project/j-stitch/) | `longstitch` | 0.4.0 | 长截图拼接算法 |
| [`j-clipboard`](https://pypi.org/project/j-clipboard/) | `pyclipboard` | 0.4.4 | 剪贴板底层操作 |
| [`j-ppocr`](https://pypi.org/project/j-ppocr/) | `ppocr_rust` | 0.2.0 | PP-OCR (PaddleOCR) ONNX 文字识别引擎（纯 Rust + ONNX Runtime，需 det/rec 模型） |
预编译包面向 Windows x86_64 和 ARM64；各包的 Python 版本声明均为 `>=3.11`，Rust 绑定均启用了 `abi3-py311`，详见各包的 `pyproject.toml` 和 `Cargo.toml`。
---
## 开发与测试
在项目根目录、已激活的虚拟环境中安装开发依赖并运行测试：
```bat
python -m pip install -r requirements-dev.txt
python -m pytest main/tests -c main/tests/pytest.ini
```
[测试目录](main/tests/)包含截图、剪贴板、马赛克、钉图缩放、GIF 回放、OCR 文字层等模块的单元测试与集成测试。[CI 配置](.github/workflows/ci.yml)在 Windows x86_64 与 ARM64 的 Python 3.11 环境中执行测试及覆盖率检查，并在 x86_64 上执行静态检查；运行结果可在 [GitHub Actions](https://github.com/1003129155/jietuba/actions/workflows/ci.yml) 查看。
构建 Windows 发行包可运行 `python build_with_ocr_onefile.py`，产物为 `dist/jietuba_pp.exe` 和 `dist/models/`。自动发行流程见 [build.yml](.github/workflows/build.yml)，会分别生成 x64 与 ARM64 压缩包。
---
## 目录结构总览
展开目录结构
```text
# 项目根目录
├── README.md / README_zh-CN.md / README_JA.md # 英文、中文、日文说明文档
├── pyproject.toml # Python 项目元数据与依赖声明
├── requirements.txt # 运行依赖
├── requirements-dev.txt # 测试与构建依赖
├── build_with_ocr_onefile.py # PyInstaller 单文件构建脚本
│
├── main/ # Python 主程序
│ ├── main_app.py # 应用入口，系统托盘、全局快捷键、生命周期管理
│ ├── compile_translations.py # 翻译文件编译工具（.xml → .qm）
│ ├── scripts/ # 辅助脚本 — 翻译提供商对比
│ │
│ ├── barcode/ # 扫码模块 — 二维码/条形码识别（zxing-cpp）
│ ├── canvas/ # 画布模块 — 图形编辑核心
│ ├── capture/ # 截图捕获模块 — 屏幕截图与窗口识别
│ ├── clipboard/ # 剪贴板管理模块 — 历史记录、分组/快速启动、导入导出、搜索
│ ├── core/ # 核心基础模块 — 启动引导、日志、资源、主题、国际化、快捷键
│ ├── gif/ # GIF录制模块 — 屏幕录制、编辑、回放、导出
│ ├── ocr/ # OCR模块 — PP-OCR 文字识别
│ ├── pin/ # 钉图模块 — 截图置顶、编辑、OCR、翻译
│ ├── settings/ # 设置模块 — 统一配置管理
│ ├── stitch/ # 长截图拼接模块 — 滚动截图、自动拼接
│ ├── tools/ # 绘图工具模块 — 笔、矩形、箭头、文字、马赛克等
│ ├── translation/ # 翻译模块 — 多提供商翻译服务
│ ├── translations/ # 语言资源 — 中文/英文/日文/韩文
│ ├── ui/ # 用户界面模块 — 通用UI组件库
│ └── tests/ # 测试模块 — 单元测试与集成测试
│
├── rust_libs/ # Rust 库源码（可自行编译）
│ ├── gifrecorder/ # GIF/视频合成编码器源码
│ ├── longstitch/ # 长截图拼接算法源码
│ ├── pyclipboard/ # 剪贴板底层操作源码
│ └── ppocr_rust/ # PP-OCR (PaddleOCR) ONNX 识别引擎源码
│
├── models/ # PP-OCR ONNX 模型文件（OCR 必需）
│ ├── PP-OCRv6_det_small.onnx # 文本检测模型 (DBNet)
│ └── PP-OCRv6_rec_small.onnx # 文本识别模型 (CRNN/CTC)
│
└── svg/ # SVG 图标资源
```
## 模块详细说明
### barcode/ — 扫码模块
识别截图选区里的二维码和条形码。结果窗口左侧在截图上标出每个码的位置，右侧按序号列出内容。
展开目录结构
```text
barcode/
├── __init__.py
├── reader.py # read_codes / DecodedCode — 基于 zxing-cpp 解码，按阅读顺序给出内容、格式与轮廓
└── result_window.py # BarcodeResultWindow — 扫码结果窗口，截图与结果列表按序号对应
```
**核心功能：**
- 支持 QR Code、Data Matrix、Aztec、PDF417 及 Code 128、EAN/UPC 等常见一维码
- 一次识别选区内的多个码，悬停截图或列表中的任一项，两边同时高亮
- 内容一键复制；http(s) 链接可直接在浏览器打开
---
### canvas/ — 画布模块
图形编辑画布系统，提供场景管理、视图渲染、图形项选择和撤销/重做功能。
展开目录结构
```text
canvas/
├── __init__.py
├── scene.py # CanvasScene — 画布场景，继承 QGraphicsScene
├── view.py # CanvasView — 画布视图，继承 QGraphicsView，负责渲染和交互
├── selection_model.py # SelectionModel — 管理被选中的图形项，支持多选
├── undo.py # CommandUndoStack — 撤销/重做栈，支持添加、删除、批量删除、编辑命令
├── smart_edit_controller.py # SmartEditController — 智能编辑控制器，处理选择与编辑模式切换
├── smart_selection_anim.py # SmartSelectionAnimator — 智能选区换窗口时的矩形补间
├── handle_editor.py # LayerEditor / EditHandle — 图层编辑器，提供控制点拖拽编辑
├── gestures.py # 鼠标手势状态机 — 文字边缘拖动、拉选区、挂起的单击编辑
├── handle_overlay.py # HandleOverlay — 编辑控制点的独立合成层，避免整场景重绘
└── items/ # 绘制图形项
├── __init__.py
├── drawing_items.py # StrokeItem / RectItem / EllipseItem / NumberItem — 共用 DrawingItemMixin 的绘制项
├── background_item.py # BackgroundItem — 选区背景底图
├── mosaic_item.py # MosaicItem — 马赛克图形项
├── spotlight_item.py # SpotlightItem / SpotlightCurtain — 聚光灯的孔与共用幕布
├── selection_item.py # SelectionItem — 选中项的边界显示框
├── arrow_item.py # ArrowItem — 箭头图元，九种样式的箭杆/端头/描边几何
└── text_item.py # TextItem — 文字图元，描边/阴影/背景色块与三态交互框
```
**核心功能：**
- 基于 Qt Graphics View Framework 的画布系统
- 支持自由绘制、矩形、椭圆、箭头、文字、编号等图形项
- 完整的撤销/重做机制（基于 QUndoStack）
- 智能编辑控制器实现选择与绘制模式无缝切换
- 控制点编辑器支持图形变换
---
### capture/ — 截图捕获模块
屏幕截图和窗口智能识别的核心服务。
展开目录结构
```text
capture/
├── __init__.py
├── capture_service.py # CaptureService — 截图服务，屏幕截图核心逻辑
├── system_cursor.py # SystemCursor — 记录截屏时的鼠标指针并画进截图
├── uia_element_finder.py # 后台 UI Automation 元素检测与选区快照缓存
└── window_finder.py # WindowFinder — 窗口查找器，智能选择窗口，识别光标下的窗口
```
**核心功能：**
- 全屏截图和区域截图
- 智能窗口识别与选择（自动排除窗口阴影）
- 光标位置窗口检测
---
### clipboard/ — 剪贴板管理模块
类似 Ditto 的剪贴板历史管理系统，现已拆分为 controllers、core、services、ui 四层结构，支持文本、图片、HTML、文件等类型。
不仅能保存截图历史，还提供独立的三栏管理窗口用于维护分组与内容，并可从历史记录生成钉图。
展开目录结构
```text
clipboard/
├── __init__.py
├── controllers/ # 控制层 — 历史加载、粘贴流程、右键菜单、选择状态
│ ├── clipboard_controller.py # ClipboardController — 历史加载、粘贴和菜单逻辑
│ ├── selection_manager.py # SelectionManager — 列表选择状态管理
│ ├── context_menu_controller.py # ContextMenuController — 右键菜单数据与行为组装
│ ├── foreground_tracker.py # ForegroundWindowTracker — 记住粘贴目标窗口
│ ├── paste_keystroke.py # 把焦点还给目标窗口后发送 Ctrl+V
│ └── __init__.py
├── core/ # 数据层 — pyclipboard 封装、数据模型、分组类型
│ ├── manager.py # ClipboardManager — 数据存储、监听、粘贴 API
│ ├── models.py # ClipboardItem / Group — 剪贴板数据模型
│ ├── enums.py # GroupType — 分组类型定义
│ ├── text_transform.py # 纯文本加工函数 — 供「特殊粘贴」调用，全部无副作用
│ └── __init__.py
├── services/ # 服务层 — 文件 payload、分组规则、导入导出、保存逻辑
│ ├── file_payload_service.py # file 类型 JSON payload 与旧格式兼容
│ ├── group_service.py # 分组图标、命名与删除确认辅助
│ ├── import_export_service.py # 文本条目 CSV 导入/导出
│ └── manage_dialog_service.py # 管理窗口保存逻辑
├── ui/
│ ├── layout_scale.py # 管理窗口共用尺寸常量
│ ├── image_item_actions.py # 图片条目的读取与另存为，剪贴板窗口和管理窗口共用
│ ├── dialogs/
│ │ └── manage_dialog.py # 三栏管理窗口：分组、内容、导入导出
│ ├── forms/
│ │ ├── group_form.py
│ │ ├── text_content_form.py
│ │ ├── file_content_form.py
│ │ ├── import_export_form.py
│ │ ├── group_icon_picker.py
│ │ ├── form_widgets.py
│ │ └── image_content_form.py
│ ├── menus/
│ │ ├── action_menu.py
│ │ ├── group_context_menu.py
│ │ └── item_context_menu.py
│ ├── mixins/
│ │ └── frameless_mixin.py
│ ├── panels/
│ │ └── setting_panel.py
│ ├── resources/
│ │ └── emoji_data.py
│ ├── theme/
│ │ ├── themes.py
│ │ └── theme_styles.py
│ ├── widgets/
│ │ ├── group_bar.py
│ │ ├── item_delegate.py
│ │ ├── item_widget.py
│ │ ├── preview_popup.py
│ │ ├── quick_edit_popup.py
│ │ ├── manage_rows.py
│ │ └── reorder_list.py
│ └── windows/
│ ├── clipboard_window.py # 历史窗口、搜索、预览与快捷粘贴
│ └── pin_window.py # 从历史条目创建钉图
```
**核心功能：**
- 监听系统剪贴板变化，自动保存历史记录
- 支持文本、图片、HTML、文件等多种格式
- 支持通用分组、快速启动分组、收藏与搜索
- 独立三栏管理窗口，可编辑分组、文本内容和文件内容
- 文本条目支持 CSV 导入/导出
- 多主题 UI（亮色/暗色等）
- 快捷键快速粘贴历史内容
- 预览弹窗支持大图/长文查看
---
### core/ — 核心基础模块
提供日志、资源加载、主题管理、国际化、快捷键等基础设施。
展开目录结构
```text
core/
├── __init__.py
├── bootstrap.py # PreloadManager — 启动引导，环境初始化、DPI感知、单实例控制、链式预加载
├── logger.py # Logger — 文件+控制台日志系统，支持多级别 (debug/info/warning/error/exception)
├── crash_handler.py # install_crash_hooks() — 全局异常和线程异常捕获
├── resource_manager.py # ResourceManager — SVG/图片等资源加载管理
├── theme.py # ThemeManager — 应用级主题颜色管理
├── ui_scale.py # UIScaleManager — 工具栏/面板/弹层共用的缩放比例
├── i18n.py # I18nManager / XmlTranslator / tr() — 国际化管理，多语言支持
├── shortcut_manager.py # HotkeySystem / ShortcutManager — 全局热键和应用内快捷键管理
├── last_capture_region.py # 进程内存的"上次截图区域"，供恢复选区快捷键使用
├── save.py # SaveService — 文件保存服务（自动命名、路径管理、高质量 PDF 输出）
├── export.py # ExportService — 图像导出服务
├── clipboard_utils.py # copy_image_to_clipboard() — 图像复制到系统剪贴板
├── platform_utils.py # DPI感知设置、AppUserModelID、进程管理等 Windows API 工具
├── qt_utils.py # safe_disconnect() — Qt 信号安全断开工具
├── log_translations/ # 各模块日志文本翻译辅助
├── constants.py # 全局常量定义（字体、路径等）
├── update_checker.py # GitHub 最新版本异步查询与版本比较
└── ui_theme.py # UIThemeManager — 应用窗口与原生 Qt 控件的明暗外观（截图配色仍在 theme.py）
```
**核心功能：**
- 统一的日志系统，支持文件输出和控制台输出
- 全局崩溃处理，自动捕获未处理异常
- SVG/图片资源统一加载
- 应用级亮色/暗色主题管理
- XML 格式的多语言国际化系统（中/英/日）
- 全局热键系统（基于 Windows API）和应用内快捷键管理
- 文件保存/导出服务（含高质量 PDF 输出）
---
### gif/ — GIF 录制模块
屏幕录制、编辑、回放和导出为 GIF/视频。
展开目录结构
```text
gif/
├── __init__.py
├── record_window.py # GifRecordWindow / AppState — 主控制窗口，状态机协调器（管理3层窗口）
├── overlay.py # CaptureOverlay / OverlayMode — 捕获覆盖层，选区调整界面
├── drawing_view.py # GifDrawingView / GifDrawingScene — 录制中绘图编辑视图
├── drawing_toolbar.py # GifDrawingToolbar — 绘制工具栏
├── record_toolbar.py # RecordToolbar — 录制控制工具栏（开始/暂停/停止）
├── frame_recorder.py # FrameRecorder / FrameData / CursorSnapshot — 帧录制器，采样屏幕帧和光标
├── playback_engine.py # PlaybackEngine / PlayState — 回放引擎，帧播放和预览
├── playback_controller.py # PlaybackController — 回放控制器，管理回放UI和导出
├── playback_toolbar.py # PlaybackToolbar / RangeSlider — 回放工具栏，进度条、速度控制
├── composer.py # _ComposeWorker / ComposerProgressDialog — GIF合成，将帧合成为GIF/视频
├── cursor_overlay.py # CursorOverlay — 光标渲染和点击动画
└── _widgets.py # ClickMenuButton / svg_icon() — 自定义小部件
```
**核心功能：**
- 以状态机模式管理录制流程（选区 → 录制 → 回放 → 导出）
- 三层窗口架构：覆盖层（选区）、绘制层（标注）、工具栏层
- 帧采样录制，支持光标捕获和点击动画
- 回放预览，支持范围裁剪、速度调节
- 导出为 GIF 或视频格式（调用 Rust 库 gifrecorder）
---
### ocr/ — OCR 文字识别模块
支持 PP-OCR 引擎的文字识别管理。
展开目录结构
```text
ocr/
├── __init__.py
└── ocr_manager.py # OCRManager — 基于 ppocr_rust (PP-OCR) 的文字识别
```
**核心功能：**
- 自动检测引擎与模型可用性
- 基于 ppocr_rust 引擎（纯 Rust + ONNX Runtime，PP-OCR det + rec），推理在原生线程运行不阻塞 UI
- 支持中/英/日文识别
- 单例模式管理，统一的识别接口，返回文字和位置信息
---
### pin/ — 钉图模块
将截图固定在屏幕上，支持编辑、缩放、OCR识别、翻译等。
展开目录结构
```text
pin/
├── __init__.py
├── pin_window.py # PinWindow — 钉图主窗口，可拖动、缩放、编辑的置顶窗口
├── pin_canvas_view.py # PinCanvasView — 钉图画布视图（唯一内容渲染者）
├── pin_canvas.py # 钉图画布对象
├── pin_manager.py # PinManager — 管理所有钉图窗口（单例）
├── pin_toolbar.py # PinToolbar — 钉图工具栏
├── pin_controls.py # PinControlButtons — 控制按钮（关闭、编辑、复制等）
├── pin_context_menu.py # PinContextMenu — 右键菜单
├── pin_border_overlay.py # PinBorderOverlay — 边框效果覆盖层
├── pin_ocr_manager.py # PinOCRManager / _OCRThread — 钉图OCR管理（异步识别）
├── pin_shortcut.py # PinShortcutController — 快捷键控制（普通模式/编辑模式）
├── pin_thumbnail.py # PinThumbnailMode — 缩略图模式
├── pin_translation.py # PinTranslationHelper — 翻译助手
├── pin_image_transform.py # PinImageTransform — 图像变换（旋转、翻转等）
└── ocr_text_layer.py # OCRTextLayer / OCRTextItem — OCR文字层显示
```
**核心功能：**
- 截图结果钉在屏幕最前端，支持拖拽移动和滚轮缩放
- 钉图上可直接进行绘制编辑
- 集成 OCR 识别，显示可选中文字层
- 集成翻译功能，可直接翻译钉图中的文字
- 快捷键支持普通模式和编辑模式
---
### settings/ — 设置模块
统一的配置管理系统。
展开目录结构
```text
settings/
├── __init__.py
├── color_formats.py # 放大镜颜色格式模板：渲染、读取、保存
└── tool_settings.py # ToolSettingsManager / ToolSettings — 管理工具颜色、大小、热键等配置
```
**核心功能：**
- 单例模式的配置管理器
- 管理各绘图工具的颜色、线宽、字体大小等参数
- 持久化存储到 QSettings
---
### stitch/ — 长截图拼接模块
滚动截图和自动拼接功能。
展开目录结构
```text
stitch/
├── __init__.py
├── jietuba_long_stitch_unified.py # 长截图拼接接口（调用 Rust longstitch）
├── scroll_window.py # ScrollCaptureWindow — 滚动截图窗口
└── scroll_toolbar.py # 滚动截图工具栏
```
**核心功能：**
- 滚动页面并截图，支持横向和竖向
- 基于图像匹配的智能拼接算法（查找重叠区域）
- 统一的长截图接口（调用 Rust 库 longstitch 加速）
---
### tools/ — 绘图工具模块
提供各种绘图工具的实现。
展开目录结构
```text
tools/
├── __init__.py
├── base.py # Tool / ToolContext — 工具抽象基类和工具上下文
├── controller.py # ToolController — 工具控制器，管理工具切换和状态
├── action.py # ActionTools — 动作工具（复制、保存、取消等）
├── pen.py # PenTool — 自由绘制笔工具
├── rect.py # RectTool — 矩形工具（实心/空心）
├── ellipse.py # EllipseTool — 椭圆工具
├── arrow.py # ArrowTool — 箭头工具
├── text.py # TextTool — 文字工具
├── number.py # NumberTool — 数字编号工具（自动递增）
├── highlighter.py # HighlighterTool — 荧光笔工具
├── mosaic.py # MosaicTool — 马赛克工具
├── spotlight.py # SpotlightTool — 聚光灯工具（压暗框外区域）
├── cursor.py # CursorTool — 光标/选择工具
├── eraser.py # EraserTool — 橡皮擦工具
└── cursor_manager.py # CursorManager — 光标样式管理器
```
**核心功能：**
- 统一的工具基类架构（Tool → 各具体工具）
- 绘图工具：笔、矩形、椭圆、箭头、文字、数字、荧光笔、马赛克、光标、橡皮擦等
- 工具控制器负责工具切换、鼠标事件分发
- 工具上下文（ToolContext）提供场景、视图、设置等依赖注入
---
### translation/ — 翻译模块
多提供商翻译服务，支持 DeepL / Google / Azure / Amazon 等提供商。
展开目录结构
```text
translation/
├── __init__.py
├── provider.py # TranslationProvider / ProviderMetadata — 提供商抽象契约
├── registry.py # ProviderRegistry — 提供商注册表与工厂
├── service.py # TranslationService — 提供商选择与翻译编排
├── models.py # TranslationRequest / TranslationResult — 与提供商无关的请求/结果模型
├── worker.py # TranslationWorker — 所有提供商共用的 Qt 工作线程
├── providers/ # 各翻译提供商实现
│ ├── deepl.py # DeepL
│ ├── google.py # Google
│ ├── azure.py # Azure
│ ├── amazon.py # Amazon
│ ├── baidu.py # Baidu
│ ├── custom_llm.py # 自定义 OpenAI 兼容服务（Ollama、LM Studio 等）
│ ├── deepseek.py # DeepSeek (LLM)
│ └── openai_compatible.py # OpenAI 兼容接口基类
├── smart_translation_controller.py # SmartTranslationController — 一键选中文字探测与翻译弹窗路由
├── translation_popup.py # TranslationPopup — 紧凑翻译弹窗（选中文字/手动输入两种模式）
├── deepl_service.py # DeepLService / TranslationThread — 旧版 DeepL API 异步翻译
├── languages.py # SupportedLanguages — 支持的语言列表与语言代码
├── translation_manager.py # TranslationManager — 翻译窗口管理器（单例）
├── translation_dialog.py # TranslationDialog / TranslationLoadingDialog — 翻译结果显示窗口
└── ui/
├── __init__.py
├── dialog.py # 翻译对话框UI组件
└── widgets.py # 翻译相关小部件
```
**核心功能：**
- 可插拔的多提供商架构（DeepL / Google / Azure / Amazon），注册表统一管理
- 一键快捷键：自动探测选中文字并路由到翻译弹窗
- 紧凑翻译弹窗，支持选中文字与手动输入两种模式
- 异步翻译，不阻塞 UI
- 翻译结果支持复制
---
### translations/ — 语言资源
多语言翻译文件存放目录。
展开目录结构
```text
translations/
├── app_zh.xml / app_en.xml # 中文/英文翻译源文件
├── app_ja.xml / app_ko.xml # 日文/韩文翻译源文件
└── app_*.xml.qm # 编译后的 Qt 二进制文件（app_zh.xml.qm 等）
```
**说明：** `.xml` 为可编辑的翻译源文件，`*.xml.qm` 为 Qt 运行时加载的编译文件。修改翻译后需运行 `compile_translations.py` 重新编译。
---
### ui/ — 用户界面模块
通用 UI 组件库，为各模块提供统一的界面元素。
展开目录结构
```text
ui/
├── __init__.py
├── toolbar.py # Toolbar / _DragHandle — 可拖动工具栏基类
├── toolbar_layout.py # 截图工具栏按钮排布（顺序 / 显示方式）的归一化与读写
├── toolbar_layout_dialog.py # ToolbarLayoutDialog — 截图工具栏排布对话框
├── reorderable_rows.py # DragGrip / DraggableRow / ReorderableRowList — 可拖动重排的行列表
├── tray_menu.py # TrayMenu — 系统托盘菜单
├── screenshot_window.py # ScreenshotWindow — 截图主窗口（全屏覆盖、选区绘制）
├── dialogs.py # StandardDialog / 对话框函数集 — 确认、警告、信息、错误对话框
├── toast.py # Toast — 光标旁不抢焦点的一行轻提示
├── magnifier.py # MagnifierOverlay — 放大镜覆盖层（像素级取色）
├── color_picker_dialog.py # ColorPickerDialog — 自定义HSV颜色选择器
├── color_picker_button.py # ColorPickerButton — 颜色选择按钮
├── hotkey_edit.py # HotkeyEdit — 全局快捷键编辑框
├── inapp_key_edit.py # InAppKeyEdit — 应用内快捷键编辑框
├── key_chip.py # KeyChipLineEdit / StatusIcon — 快捷键按键块与状态图标
├── mask_overlay.py # 遮罩覆盖层
├── selection_overlay.py # SelectionOverlayWidget — 选区装饰浮层，压在遮罩之上
├── base_settings_panel.py # BaseSettingsPanel / StepperWidget — 设置面板基类
├── paint_settings_panel.py # PaintSettingsPanel — 画笔设置面板
├── shape_settings_panel.py # ShapeSettingsPanel — 形状设置面板
├── text_settings_panel.py # TextSettingsPanel — 文字设置面板
├── arrow_settings_panel.py # ArrowSettingsPanel — 箭头设置面板
├── number_settings_panel.py # 数字工具设置面板
├── mosaic_settings_panel.py # 马赛克工具设置面板
│
├── fluent_lite/ # Fluent 风格轻量组件库
│ ├── buttons.py / cards.py / icons.py / inputs.py # 按钮、卡片、图标、输入框
│ ├── labels.py / navigation.py / segmented.py # 标签、导航、分段控件
│ ├── switch.py / theme.py / titlebar.py # 开关、主题、标题栏
│ ├── frameless.py # 无边框窗口
│ └── text_context_menu.py # 文本右键菜单
│
├── settings_ui/ # 应用设置对话框
│ ├── __init__.py
│ ├── dialog.py # SettingsDialog — 主设置对话框（选项卡式）
│ ├── components.py # SettingCardGroup / ToggleSwitch — 设置组件库
│ ├── page_appearance.py # 外观设置页（主题、语言等）
│ ├── page_capture.py # 截图设置页
│ ├── page_quick_actions.py # 快捷行为设置页（跳过确认或结果窗口）
│ ├── color_format_dialog.py # ColorFormatDialog — 放大镜颜色格式管理窗口
│ ├── page_clipboard.py # 剪贴板设置页
│ ├── page_hotkey.py # 快捷键设置页
│ ├── page_translation.py # 翻译设置页
│ ├── provider_fields.py # 服务商字段的读写（按声明）
│ ├── page_log.py # 日志设置页
│ ├── page_developer.py # 开发者设置页
│ ├── page_misc.py # 杂项设置页
│ ├── page_about.py # 关于页面
│ └── mock_config.py # MockConfig — 测试用模拟配置
│
├── welcome/ # 首次启动欢迎向导
│ ├── __init__.py
│ ├── wizard.py # WelcomeWizard — 欢迎向导主窗口（多页滑动）
│ ├── base_page.py # BasePage — 向导页面基类
│ ├── page1_welcome.py # 欢迎页
│ ├── page2_screenshot.py # 截图快捷键设置页
│ ├── page3_clipboard.py # 剪贴板快捷键设置页
│ ├── page5_translation.py # 翻译功能说明页
│ ├── page6_finish.py # 完成页
│ └── page_hotkeys.py # 全局快捷键页 — 六个键同属一个冲突域，集中设置并统一判重
│
└── selection_info/ # 选区信息UI
├── __init__.py
├── controller.py # 选区信息控制器
├── panel.py # 选区信息面板（尺寸、坐标）
├── hook_manager.py # 钩子管理
├── border_shadow.py # 选区边框阴影效果
├── lock_ratio.py # 锁定宽高比功能
└── rounded_corners.py # 圆角截图功能
```
**核心功能：**
- 可拖动工具栏基类，所有工具栏继承自此
- 全屏截图窗口，处理选区绘制和交互
- 放大镜、颜色选择器等精细UI组件
- Fluent 风格轻量组件库（按钮、卡片、导航、分段、开关等）
- 完整的应用设置对话框（外观/截图/热键/翻译等多个页面）
- 首次启动欢迎向导（6页引导流程）
- 选区信息面板（尺寸显示、宽高比锁定、圆角等）
---
### tests/ — 测试模块
单元测试和集成测试。
展开目录结构
```text
tests/
├── conftest.py # pytest 配置和公共 fixture
├── pytest.ini # pytest 运行配置
├── run_tests.py # 测试运行脚本
├── test_drawing_tools.py # 绘图工具测试（笔/矩形/箭头/文字/数字/荧光笔）
├── test_mosaic_tool.py # 马赛克工具测试
├── test_spotlight.py # 聚光灯测试
├── test_functional_handles.py # 控制点编辑测试
├── test_capture_service.py # 截图服务测试
├── test_clipboard_api.py # 剪贴板公共 API 测试
├── test_clipboard_manage_dialog.py # 剪贴板管理窗口测试
├── test_frame_recorder.py # GIF 帧录制测试
├── test_playback_engine.py # GIF 回放引擎测试
├── test_ocr_text_layer.py # OCR 文字层测试
├── test_pin_window_zoom.py # 钉图缩放测试
├── test_smart_translation.py # 智能翻译测试
├── test_translation_architecture.py # 翻译提供商架构测试
├── test_stitch_dedup.py # 长截图拼接去重测试
├── test_settings_dialog_state.py # 设置对话框状态测试
├── test_welcome_translation.py # 欢迎向导翻译页测试
└── …（其余模块单元测试与集成测试，共 70 多个文件）
```
---