企业官网建设流程全解析

• 桌面应用
• AI 应用

Pot（"派了个萌的翻译器"）是当前开源仓库 pot-app/pot-desktop 中的核心项目：一款基于 Tauri + Rust 构建的跨平台划词翻译与 OCR 桌面软件，覆盖 Windows、macOS、Linux 三大平台，并以 "多接口并行 + 插件扩展 + HTTP 外部调用" 为核心设计。本文以仓库根目录的 README.md 为主线，结合src-tauri下的 Rust 源码（如 server.rs、hotkey.rs、cmd.rs）与前端服务实现，系统讲解六大核心使用方式、内置/插件接口体系、HTTP API 外部调用方案、安装与手动编译流程，以及 Wayland 桌面环境下的适配技巧，帮助读者快速上手并二次集成 Pot 的能力。

一、核心使用方式

Pot 的全部常用功能都由全局快捷键驱动，快捷键在应用内"偏好设置"中可自由配置。Rust 侧通过 hotkey.rs 的register_shortcut在应用启动时统一注册selection_translate、input_translate、ocr_recognize、ocr_translate四类全局快捷键，前端修改后通过register_shortcut_by_frontend命令热更新（hotkey.rs）。六种主要使用方式如下：

其中截图相关逻辑集中在 window.rs：ocr_recognize与ocr_translate在 macOS 上直接调用系统screencapture命令，在其他平台则创建全屏透明的screenshot窗口并监听success事件，框选裁剪后写入缓存图片pot_screenshot_cut.png再交由识别服务处理。翻译窗口则默认跟随鼠标弹出（translate_window_position默认为"mouse"），并自动规避超出屏幕边界的情况（window.rs）。

二、特色功能一览

• 多接口并行翻译（详见"支持接口"）
• 多接口文字识别（详见"支持接口"）
• 多接口语音合成（详见"支持接口"）
• 导出到生词本（详见"支持接口"）
• 外部调用（HTTP API 服务）
• 插件系统（.potext扩展）
• 支持所有 PC 平台：Windows、macOS、Linux
• 支持 Wayland（在 KDE、Gnome 以及 Hyprland 上测试）
• 多语言支持（i18n 多语言界面）

值得说明的是"多接口并行"与"多实例"能力。从 config.rs 的check_service_available可以看到，内置服务分为recognize、translate、tts、collection四类服务清单，分别保存在recognize_service_list、translate_service_list、tts_service_list、collection_service_list配置项中；前端 service_instance.ts 通过createServiceInstanceKey以服务名@随机ID的形式支持同一接口配置多个实例，并对以plugin开头的服务实例自动识别为插件来源（service_instance.ts），从而实现同一翻译/识别任务可由多个服务并行分发。

三、支持接口体系

Pot 的接口分为内置接口与插件接口两大类，内置接口在 config.rs 中作为白名单硬编码校验，插件接口通过安装.potext插件动态注册。

翻译接口

内置翻译接口包括：

• AI/大模型类：OpenAI、智谱 AI、Gemini Pro、Ollama（离线）
• 国内云厂商：阿里翻译、百度翻译、彩云小译、腾讯翻译君、腾讯交互翻译、火山翻译、小牛翻译
• 国际通用：Google、Bing、Bing 词典、DeepL、有道翻译、剑桥词典、Yandex、Lingva
• 社区/插件：Tatoeba、ECDICT（以上两项以插件形式提供）

以 OpenAI 为例，其实现位于 services/translate/openai/index.jsx：自动补全v1/chat/completions端点、将$text/$from/$to/$detect占位符注入系统提示词，并支持stream流式输出（通过ReadableStream逐段解析data:增量并实时刷新结果），配置项则定义了 API Key、模型名、请求参数、Prompt 模板等（Config.jsx）。同类的 LLM 接口（智谱、Gemini、Ollama、OpenAI）共享 OpenAI 兼容协议的封装思路。

文字识别接口

• 系统 OCR（离线）：Windows 使用 Windows.Media.OCR，macOS 使用 Apple Vision Framework，Linux 使用 Tesseract
• 离线方案：Tesseract.js、Rapid（离线插件）、Paddle（离线插件）
• 云端方案：百度、腾讯、火山、迅飞通用 OCR，腾讯图片翻译、百度图片翻译，Simple LaTeX（公式识别）
• 其他：OCRSpace（插件）

系统 OCR 的实现细节非常清晰（system_ocr.rs）：Windows 分支通过Windows.Media.Ocr.OcrEngine读取缓存截图并识别，若语言包缺失会提示安装；macOS 分支调用内嵌的ocr-{arch}-apple-darwin二进制；Linux 分支直接执行系统tesseract命令（tesseract <图片> stdout [-l lang]），并在缺少 Tesseract 或语言数据时给出明确的安装提示（system_ocr.rs）。

语音合成接口

• Lingva），更多 TTS 接口通过插件扩展。

生词本（导出）接口

• 内置：Anki、欧路词典
• 插件：有道、扇贝

Anki 与欧路词典的导出实现分别位于 services/collection/anki 与 services/collection/eudic。

四、插件系统

软件内置接口数量有限，但可以通过插件系统扩展翻译、识别、TTS、生词本任意一类能力。

插件安装

1. 在 Pot 官网的 Plugin List 页面查找需要的插件，前往插件仓库下载；
2. Pot 插件扩展名为.potext，获得文件后进入偏好设置 → 服务设置 → 添加外部插件 → 安装外部插件，选择对应的.potext文件即可安装；
3. 安装成功后，在服务列表中即可像内置服务一样正常配置和使用。

安装的底层逻辑由install_plugin命令实现（cmd.rs）：校验文件名必须以plugin开头，以 zip 方式解压并校验压缩包内必须包含info.json（读取plugin_type判定插件类别）与main.js（插件入口），随后解压到$CONFIG/com.pot-app.desktop/plugins/{plugin_type}/{plugin_name}目录。

故障排除

• 找不到指定的模块（Windows）：此类报错通常因系统缺少 C++ 运行库（Visual C++ Redistributable）导致，安装对应运行库即可解决。
• 不是有效的 Win32 应用程序（Windows）：说明下载的插件与当前系统或 CPU 架构不匹配，请前往插件仓库下载对应架构（x64/x86/arm64）的插件。

插件开发

Pot 官网 Plugin List 的"模板"章节提供了各类插件的开发模板，具体开发文档见对应模板仓库。运行机制上，前端通过 invoke_plugin.js 读取插件目录下的main.js，将其eval后执行，同时注入tauriFetch/http（网络请求）、readBinaryFile/readTextFile（文件读取）、Database（SQLite）、CryptoJS（加解密）、run（调用run_binary命令执行插件内置二进制）、cacheDir/pluginDir、osType等实用工具对象。插件如需携带原生二进制（如 OCR 引擎），则由run_binary在插件目录上下文中启动子进程并返回 stdout/stderr/status（cmd.rs）。

五、安装指南

Windows

Winget 安装：

winget install Pylogmon.pot

手动安装：

1. 在 Release 页面下载最新exe安装包：
   • 64 位机器下载pot_{version}_x64-setup.exe
   • 32 位机器下载pot_{version}_x86-setup.exe
   • arm64 机器下载pot_{version}_arm64-setup.exe
2. 双击安装包进行安装。

故障排除：

• 启动后没有界面，点击托盘图标没有反应：检查是否卸载/禁用了 WebView2；若企业版系统无法安装 WebView2，可下载内置 WebView2 运行时的版本pot_{version}_{arch}_fix_webview2_runtime-setup.exe；问题仍存在可尝试以 Windows 7 兼容模式启动。

MacOS

Brew 安装：

brew tap pot-app/homebrew-tap brew install --cask pot brew upgrade --cask pot # 更新 pot

手动安装：

1. 从 Release 页面下载最新dmg安装包：M1/M2 芯片下载pot_{version}_aarch64.dmg，Intel 机型下载pot_{version}_x64.dmg；
2. 双击后将 pot 拖入 Applications 文件夹即完成安装。

故障排除：

• "由于开发者无法验证，pot 无法打开"：点击"取消"，前往 设置 → 隐私与安全性，点击"仍要打开"，再在弹出的窗口点击"打开"；若找不到该选项或提示文件损坏，在 Terminal 中执行以下命令后重启：

  sudo xattr -d com.apple.quarantine /Applications/pot.app

• 辅助功能权限问题：若每次打开都提示辅助功能权限，或无法进行划词翻译，请前往 设置 → 隐私与安全 → 辅助功能，移除 "pot" 后重新添加。

Linux

Debian/Ubuntu：从 Release 下载对应架构的deb包后执行：

sudo apt-get install ./pot_{version}_amd64.deb

Arch/Manjaro：可在 AUR 搜索pot-translation后用 AUR helper 安装：

yay -S pot-translation # 或 pot-translation-bin # paru -S pot-translation # 或 pot-translation-bin

若使用archlinuxcn源，可直接：

sudo pacman -S pot-translation

[!WARNING] 在较新版本的 Webkit2Gtk（如 2.42.0）中，Nvidia 专有驱动未完全实现 DMABUF，会导致无法启动或崩溃。请降级，或在/etc/environment等环境变量配置处加入WEBKIT_DISABLE_DMABUF_RENDERER=1以关闭 DMABUF 渲染。

Flatpak：可通过 Flathub 应用中心安装（注意：Flatpak 版本缺失托盘图标）。

六、外部调用（HTTP API）

Pot 内置完整的 HTTP 接口，可被任意外部软件调用。其实现位于 server.rs：应用启动时即start_server，读取配置项server_port（默认60828，可在软件设置中更改），监听127.0.0.1:port；若端口被占用会弹通知提示"Please Change Server Port and restart the application"。请求分发由 http_handle 完成。

API 端点

注意区分screenshot=true/false的差异：服务端通过 URL 是否以false结尾来分流（server.rs）——false分支直接读取缓存截图文件pot_screenshot_cut.png进入识别/翻译窗口，true或默认分支则先启动软件内的截图框选流程。

调用示例

例如用 curl 触发划词翻译：

curl "127.0.0.1:60828/selection_translate"

不使用软件内截图

该能力允许在不依赖软件内截图的前提下调用截图 OCR/截图翻译，可以使用任意喜欢的截图工具，也规避了部分平台（尤其 Wayland）内置截图不可用的问题。调用流程：

1. 使用其他截图工具截图；
2. 将截图保存到$CACHE/com.pot-app.desktop/pot_screenshot_cut.png；
3. 请求127.0.0.1:port/ocr_recognize?screenshot=false即可完成识别。

$CACHE为系统缓存目录，Windows 上对应C:\Users\{用户名}\AppData\Local\com.pot-app.desktop\pot_screenshot_cut.png。

该文件名的约定与软件内部完全一致——内置截图框选后由cut_image命令裁剪输出到同名文件（cmd.rs），后续所有 OCR 服务（含系统 OCR）都从该路径读取图片，因此外部截图只需"覆盖"此文件即可无缝接入。

Linux 下结合 Flameshot 的完整示例：

rm ~/.cache/com.pot-app.desktop/pot_screenshot_cut.png && flameshot gui -s -p ~/.cache/com.pot-app.desktop/pot_screenshot_cut.png && curl "127.0.0.1:60828/ocr_recognize?screenshot=false"

现有用法（快捷划词翻译）

• SnipDo（Windows）：从 Microsoft Store 安装 SnipDo，下载安装 pot 的 SnipDo 扩展（pot.pbar）后，选中文字即可在弹出的工具条点击翻译按钮。
• PopClip（MacOS）：从 App Store 安装 PopClip，下载安装 pot 的 PopClip 扩展（pot.popclipextz）并在 PopClip 扩展中启用后，选中文本即可点击翻译。
• Starry（Linux）：目前仍处于开发阶段，需要手动编译（其源码仓库由社区维护）。

七、Wayland 支持

由于各大发行版对 Wayland 的支持程度不同，Pot 自身无法做到完美适配，但通过合理配置也可以在 Wayland 下稳定运行。以下是常见问题的解决方案。

快捷键无法使用

Tauri 的全局快捷键方案尚未支持 Wayland，因此 Pot 应用内设置的快捷键在 Wayland 下无效。解决思路是用系统快捷键 + curl 请求触发 Pot，即通过系统的快捷键绑定把请求发给 Pot 的 HTTP 服务，详见上文"外部调用"。

截图无法使用

在部分纯 Wayland 桌面环境/窗口管理器（如 Hyprland）上，Pot 内置截图无法使用，可改用其他截图工具配合screenshot=false参数（见上文"不使用软件内截图"）。下面是 Hyprland 下使用 grim + slurp 实现截图的配置示例：

bind = ALT, X, exec, grim -g "$(slurp)" ~/.cache/com.pot-app.desktop/pot_screenshot_cut.png && curl "127.0.0.1:60828/ocr_recognize?screenshot=false" bind = ALT, C, exec, grim -g "$(slurp)" ~/.cache/com.pot-app.desktop/pot_screenshot_cut.png && curl "127.0.0.1:60828/ocr_translate?screenshot=false"

其他桌面环境/窗口管理器思路类似。此外，仓库中的 patches/hyprland.patch 记录了针对 Hyprland 的一个官方修复补丁：注释掉翻译窗口中监听tauri://move事件（该事件在 Wayland 下会干扰失焦自动关闭窗口的逻辑），可作为二次开发时的参考。

划词翻译窗口跟随鼠标位置

Pot 目前无法在 Wayland 下获取正确鼠标坐标，可通过桌面环境/窗口管理器的窗口规则实现跟随。以 Hyprland 为例：

windowrulev2 = float, class:(pot), title:(Translator|OCR|PopClip|Screenshot Translate) # Translation window floating windowrulev2 = move cursor 0 0, class:(pot), title:(Translator|PopClip|Screenshot Translate) # Translation window follows the mouse position.

八、国际化与贡献

Pot 的国际化通过 Weblate 平台协作翻译（仓库内已内置 21 个语言文件，位于 src/i18n/locales，包含简体/繁体中文、英、日、韩、法、德、俄、西、意等），用户可在 Weblate 页面参与翻译。项目在 README 中向灵感来源 Bob、OpenAI 接口参考项目以及 Tauri 框架表达了致谢。

九、手动编译

Pot 是标准的 Tauri 项目，前端为 Vite + React（src），后端为 Rust（src-tauri/src），可自行编译调试。

环境要求：

• Node.js >= 18.0.0
• pnpm >= 8.5.0
• Rust >= 1.80.0

编译步骤：

git clone https://gitcode.com/pot-app/pot-desktop.git cd pot-desktop pnpm install

仅 Linux 需要额外安装系统依赖：

sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.0-dev libayatana-appindicator3-dev librsvg2-dev patchelf libxdo-dev libxcb1 libxrandr2 libdbus-1-3

开发调试与打包：

pnpm tauri dev # 以开发模式运行应用 pnpm tauri build # 打包生成安装包

打包配置位于 src-tauri/tauri.conf.json：产品名pot、bundle 标识com.pot-app.desktop，并针对 Windows/macOS/Linux 分别有 tauri.windows.conf.json、tauri.macos.conf.json、tauri.linux.conf.json 平台级覆盖配置；deb/rpm 包会自动声明libxdo-dev、libxcb1、libxrandr2、tesseract-ocr等运行时依赖（tauri.conf.json）。项目以 GPLv3 协议开源（见根目录 LICENSE）。

• 桌面应用
• AI 应用