# shotx

**Repository Path**: panxu11/shotx

## Basic Information

- **Project Name**: shotx
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-20
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ShotX

简体中文 | [English](README.en.md)

ShotX 是基于 Tauri 2、Rust 和 React 构建的 Windows 桌面截图、标注、OCR、贴图与翻译工具。

仓库同时包含可直接发布的设置界面和项目介绍页；构建与项目门禁会校验文档、版本和发布资源的一致性。

## 当前状态

支持 Windows 10/11 x64：

- 区域、全屏和长截图
- 原生标注、复制、保存和贴图
- 文字标注支持直接编辑、鼠标定位光标和拖选替换
- PaddleOCR 和 Windows OCR 后端
- 可配置翻译 Provider，包括 OpenAI-compatible 自定义 AI 端点
- 全局快捷键和应用设置持久化

录屏功能处于规划中，当前尚未提供。

## 运行要求

- Windows 10/11 x64
- Node.js 20 或更高版本
- Rust stable 与 MSVC 工具链
- 安装 C++ 工作负载和 Windows SDK 的 Visual Studio 2022 Build Tools
- WebView2 Runtime

## 开发

安装 JavaScript 依赖：

```powershell
npm install
```

启动嵌入式开发构建：

```powershell
npm run tauri dev
```

需要 Vite 热更新时：

```powershell
npm run tauri:dev:hot
```

运行检查：

```powershell
npm run build
npm run docs:test
npm run docs:check
npm run source:gate
npm run cargo:test
```

原生截图叠加层的维护入口是 `src-tauri/src/platforms/windows/native_overlay/mod.rs`：入口文件提供按职责的持久索引，核心状态、共享类型、状态编辑、窗口消息、显示渲染、捕获输出和位图标注分别位于专用文件。所有新增或修改的第一方源文件都必须通过 `npm run source:gate` 的 2500 行边界检查。

翻译服务和 Windows Pin 原生窗口同样按职责拆分：`src-tauri/src/services/translation/` 保存 Provider 与共享辅助逻辑，`src-tauri/src/platforms/windows/native_pin/` 保存窗口、文本工具栏和图像渲染逻辑；原有模块入口保持不变。

首次在可联网环境使用 Rust 依赖时：

```powershell
cargo fetch --manifest-path src-tauri/Cargo.toml
```

## OCR 与翻译

PaddleOCR 是默认的本地 OCR 后端。OCR 模型和运行时二进制文件刻意不包含在源码仓库或 GitHub Release 中。安装 ShotX 后，优先运行应用 OCR 错误提示中的恢复命令；在 Windows 上，脚本会将经过锁定的资源下载到可写的用户目录 `%LOCALAPPDATA%\ShotX\ocr`，失败时自动重试并逐项校验 SHA-256。资源来源版本与哈希记录在 [`src-tauri/resources/ocr/README.md`](src-tauri/resources/ocr/README.md)。

在源码目录中执行以下命令安装资源；安装包环境应使用应用提示的完整命令：

```powershell
powershell -ExecutionPolicy Bypass -File scripts/setup-ocr.ps1
```

有意切换到新的已锁定模型或运行时版本时，加入 `-Refresh`。可使用 `-Destination` 指定自定义目录，或在运行时通过 `SHOTX_OCR_MODEL_DIR` 和 `SHOTX_OCR_RUNTIME_PATH` 配置路径。

网络受限时，可使用包含清单全部文件的已验证目录离线安装：

```powershell
powershell -ExecutionPolicy Bypass -File scripts/setup-ocr.ps1 `
	-OfflineSource D:\ShotX-OCR-resources
```

部分翻译 Provider 使用匿名公开网页接口，其他 Provider 可能需要用户提供凭据。不要提交 Provider Key、签名密钥、Cookie 或 Authorization Header。翻译与 OCR 请求可能会向所选 Provider 发送图片或文本数据，使用前请确认该 Provider 的隐私政策。诊断日志不会包含 OCR 文本、源图片片段、请求正文、Cookie 或授权值。

Custom AI Provider 支持 OpenAI-compatible 端点，例如 `/v1` 基础 URL 或完整的 `/chat/completions` URL，以及模型名称、可选 API Key 和自定义 Header。截图翻译先在本地执行 OCR，仅向端点发送识别出的文本块，不上传源截图。在 Windows 上，Custom AI Key、Youdao/Iciba Provider Key 和自定义代理密码使用 DPAPI 保护；应用启动时会从 `translation.json` 与 `network-settings.json` 迁移旧版明文值。

Youdao 和 Iciba API Key 可在翻译设置中填写。为兼容旧配置，仍支持本地环境变量 `SHOTX_YOUDAO_KEY_SECRET` 和 `SHOTX_ICIBA_SIGN_SECRET`，但它们不应出现在仓库中。
截图翻译会传递 OCR 检测到的源语言；Youdao 网页 Provider 按 OCR 文本块使用明确源语言请求，以保持块顺序并避免网页接口对自动检测或批量标记文本的错误响应。
翻译设置会将当前通道所需的 API Key 直接显示在通道摘要下方；专业模型的独立配置入口始终保留，以便首次完成配置后再启用该通道。

## 文档

- [`docs/README.md`](docs/README.md)：文档索引
- [`docs/ShotX-Requirements.md`](docs/ShotX-Requirements.md)：产品范围与验收边界
- [`docs/TECHNICAL_ARCHITECTURE.md`](docs/TECHNICAL_ARCHITECTURE.md)：技术架构
- [`docs/OCR_IMPLEMENTATION.md`](docs/OCR_IMPLEMENTATION.md)：OCR 后端与资源交付
- [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)：第三方许可

## 许可证

ShotX 使用 GNU General Public License v3 或更高版本（`GPL-3.0-or-later`）。你可以使用、修改、集成和再分发 ShotX，包括商业用途；分发二进制时须保留声明、提供相应源码，并以相同许可证发布衍生作品。详见 [`LICENSE`](LICENSE)。

第三方组件保留各自许可证。再分发前请阅读 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。