Wenyi Desktop
Desktop 在本地运行，拥有独立的项目与设置。发行包已包含翻译引擎，无需安装 Python、Docker 或部署 Web 服务。它不读取或迁移 CLI、Web 项目。
本地存储不代表离线翻译。除非配置本地模型服务，文本仍会发送给选定的模型提供商；PDF 解析也可能使用外部服务。
安装 Desktop
从 GitHub Releases 下载适合系统的 wenyi-desktop-<版本>-<平台>-<架构> 文件：
| 平台 | 安装包 |
|---|---|
| Windows x64 | .exe 安装程序 |
| Linux x64 | .AppImage、.deb 或 .rpm |
| macOS Apple Silicon | macos-arm64.dmg |
| macOS Intel | macos-x64.dmg |
安装包直接提供，不套外层 ZIP。AppImage 需先在文件属性中允许执行。macOS 按芯片选择安装包，不提供通用包。平台要求与签名状态以发行说明为准。
程序安装目录应与文档数据分开。Windows 默认安装到 %LOCALAPPDATA%\Programs\Wenyi Desktop，更改安装位置不会搬迁数据。安装器会拒绝不安全或被其他文件占用的目录，包括与文译数据目录重叠的位置；请选择专用空目录或已有的文译安装目录。
Windows 安装器应以普通用户运行，不要选择以管理员身份运行。若提示文译或其引擎仍在运行，请从托盘退出并等待任务停止；安装器不会强制中断翻译。旧版本不能覆盖安装到新版本之上。
安装后先配置 API 密钥，再按共享工作台指南创建、翻译、校阅和导出书籍。源码运行与构建见 Desktop 开发指南。
API 密钥
模型连接
打开设置 → 模型与接口，添加或选择连接，填写 API 密钥及需要的自定义接口地址。保存配置会保存连接并一并提交密钥，无需另行保存模型密钥。未保存的密钥只是内存草稿，离开设置页会丢弃。
- Desktop 优先使用系统凭据库：macOS Keychain、Windows 凭据库，或受支持的 Linux Secret Service/KWallet。
- 凭据库不可用或无法保存时，密钥仅保留在当前会话内存中，并明确提示；重启后需重新输入，不会回退到明文文件。
- 已保存的手动密钥以掩码显示，可用眼睛控件查看。清空模型密钥框并保存会删除已存密钥。
- 改用环境变量会移除手动凭据，改读配置的变量；未指定变量名时使用提供商默认值。缺失的手动／会话密钥不会悄悄回退到环境变量，显式指定的变量也不会回退到其他变量。
- 在应用外修改其继承的环境变量后需重启。凭据变化对新建客户端生效，不替换运行中任务已取得的配置和凭据。
文译不把密钥写入 YAML/JSON、SQLite、项目文件、浏览器存储或日志。项目备份仅含凭据引用，不含系统凭据库或会话内存中的秘密值。
注册模型、获取名称与测试连接见选择模型与流程。获取名称不消耗模型 token；测试连接会发送真实模型请求，可能产生费用。校验配置检查当前草稿，不发送模型请求。
MinerU PDF 解析密钥
在设置 → PDF 解析中填写用于 PDF 转换的 MinerU 密钥，它与模型 API 密钥独立。
手动 MinerU 密钥在输入停顿或离开输入框时自动保存，没有保存按钮。 清空输入框即移除手动密钥。保存独立于模型／配置保存，优先使用系统凭据库，不可用时仅存于当前会话并提示。
存在 MINERU_API_KEY 时优先使用环境变量，输入框显示来源且不可编辑或回显。无效的环境密钥不会回退到手动密钥，请修正后重启。重命名／删除模型连接或恢复模型默认配置不移除 MinerU 密钥。
保存密钥不会上传文档或发送可能计费的解析请求。新的 MinerU 转换需要它，其他格式或匹配的 PDF 解析缓存复用不需要。
数据位置与备份
原文与项目状态保存在同一项目目录。创建对话框的项目文件夹只选择这个新项目的父目录，不改变已有项目的位置。
Desktop 使用一个与程序目录分离的数据根目录：
| 平台 | 默认数据根目录 |
|---|---|
| Linux | ${XDG_DATA_HOME:-~/.local/share}/wenyi/Desktop |
| macOS | ~/Library/Application Support/Wenyi/Desktop |
| Windows | %LOCALAPPDATA%\Wenyi\Desktop |
根目录中的 catalog.sqlite3 保存项目列表和设置，projects/ 保存默认项目文件，logs/ 保存日志，locks/ 保存锁，runtime/ 保存插件，backups/ 保存升级快照。API 密钥仍在系统凭据库或会话内存中，不写入这些文件。
新项目默认保存在 <数据根目录>/projects/，而非安装目录旁。也可选择其他本地卷上的项目库；受保护的程序、系统、设置与缓存位置会被拒绝，已有项目保留所记录的位置。
--data-dir <路径> 选择整套数据根目录，包括目录库、设置、插件和日志；不同根目录不共享隐藏的目录库。选择另一根目录不会搬迁或发现已有项目。Linux 仅使用绝对路径形式的 XDG_DATA_HOME，未设置、空白或相对路径均回退到 ~/.local/share；Windows 和 macOS 忽略该变量。
旧 Desktop 布局不会自动迁移。 旧目录库、设置、凭据、项目和插件均保留原位，新默认位置以空项目列表启动。本版没有旧格式导入或迁移命令，重命名旧目录库也不能升级。如需重新打开旧项目，请保留原始数据及适用的旧发行版。
数据根目录和项目库都应放在本地磁盘。 网络共享、映射驱动器和 OneDrive、Dropbox、iCloud Drive、Google Drive 等云同步目录不受支持。数据库加锁、占位文件和不同步的复制时序可能损坏保存结果或产生不完整备份；Desktop 不会检测所有这类位置。
要取得可恢复的备份：
- 保存编辑器／设置草稿，暂停或完成全部任务，然后退出所有 Desktop 实例。隐藏到托盘不等于退出。
- 将完整数据根目录复制到独立的备份位置，包括存在的
-wal、-shm等数据库附属文件；不要只复制单个 SQLite 数据库。 - 另外复制全部已登记的外部项目目录；有自选项目库时，只备份数据根目录并不完整。
- 保留根目录
runtime/中的 BabelDOC 插件及 PDF 会话。另存的书籍导出按普通文档自行备份。
恢复时使用一致的整套目录库与项目文件，不要把单独的旧数据库混入较新数据。未标识或不支持的目录库会被拒绝，而非自动升级。确认恢复／导入后的项目可用，再移除原备份。系统凭据库不在这份备份中，在另一台电脑上可能需要重新输入密钥。Windows/Linux 的 WebView 数据位于 runtime/webview/；macOS 的 WKWebView 存储由系统在根目录之外管理。
导入已有项目
项目列表的导入已有项目用于接管本机移动过或从另一台电脑复制来的 Desktop 项目目录。它不同于在创建项目中选择原文书籍，也不是 CLI/Web 迁移工具。
导入只接受当前格式的 Desktop 项目。接受目录前会检查保存的状态、项目身份与原文。项目标记过旧或缺失、缺少 state.sqlite3、元数据不可读、原文不唯一、校验值不匹配，或标记损坏／矛盾时会拒绝。请恢复匹配的原文，不要把旧译文关联到已改动的源内容；已注册的项目身份也不能重复导入。
通过检查的目录会移入 <数据根目录>/projects/，再按已保存进度加入项目列表。需要保留原文件夹时，请导入其副本。启动不会扫描项目文件夹来重建丢失的目录库，应恢复一致的备份。
记录的盘符或文件夹不可用时，项目仍留在列表中，但无法打开。请重新连接，Desktop 不会自动改用其他同 ID 副本或创建空目录替代。移除不可用项目的目录库记录，不会擦除断开磁盘上的数据。Web 没有项目文件夹导入功能。
导入新书籍则在创建项目中拖入原文或使用浏览文件；仅选择文件不会上传。原生上传失败或选择授权过期后，需重新选择／拖入文件再试。
可选 BabelDOC 插件
使用设置 → BabelDOC 插件 → 启用并下载，可进行保留版式的 PDF 翻译。插件默认关闭，从官方 BabelDOC bridge 发行版下载独立的 AGPL-3.0-only 运行环境及模型／字体包；普通 Desktop 安装不会下载它。
等待已就绪后，在创建 PDF 项目时选择 BabelDOC 解析器。启用插件不会把默认解析器从 MinerU 自动切换，也不转换已有项目。只有经 BabelDOC 解析的项目支持保留版式的 PDF 导出。
- 取消安装会禁用插件；重试复用已完成且通过校验的下载。中断的安装需重试。
- 已安装且启用的插件随 Desktop 启动。禁用保留安装文件、模型与 PDF 会话；禁用前请完成项目任务。
- 检查插件更新和更新插件需手动操作，重启或重新启用不会自动升级。
- 切换版本须等待全部项目任务、导出与原生保存结束。取消或安装／启动失败会保留旧版；不会删除旧安装和会话。bridge 兼容性变化可能要求重新解析受影响的 PDF。
插件及保留的 PDF 会话位于 <数据根目录>/runtime/plugins/babeldoc/。旧布局的插件不会复用或迁移，需要时在新根目录重新安装。手动备份应包含此目录；应用升级快照只覆盖目录库和已登记项目，不包含插件运行时与会话。
应用更新
在设置 → 关于查看当前版本、检查更新和阅读发行说明。已配置更新能力的稳定发行版也会在启动时检查；检查不会静默下载、安装或重启，安装需要明确确认。
安装前，请完成或暂停项目任务，等待导出、保存及插件安装结束，保存或放弃编辑器／设置中未保存的修改，并关闭同一程序的其他副本，即使它们使用不同数据根目录。
支持的发行版可在 Windows、macOS 和 Linux AppImage 内安装更新；macOS 保持原架构。Linux .deb/.rpm 通过下载的软件包升级，不替换成 AppImage。旧版或未配置更新能力的构建可能需手动升级。网络／检查失败不影响继续使用。
应用内安装先停止写入与引擎，再把全部已注册项目目录及 catalog.sqlite3 备份到 <数据根目录>/backups/<版本>-<时间戳>/。备份包括存在的数据库 WAL/SHM，及记录原位置和文件校验信息的 MANIFEST.json，不复制旧备份、不导出凭据秘密值，也不代替日常备份。
项目目录不可用、磁盘空间不足、不安全链接或复制／校验失败都会阻止安装。请重新连接缺失磁盘或修正所报问题后再试。若更新准备无法正常取消，请退出并重新打开 Desktop，不要假定写入已恢复。
手动安装器不生成这份快照，也不要求存在历史备份标记。替换程序前请自行备份当前数据，优先从文译内更新。
Windows 卸载
卸载默认保留数据，两个相互独立的删除选项最初均不勾选：
- 删除目录库、设置、日志、锁及运行时，不删除项目文件。
- 永久删除默认项目文件及升级备份。
两项只处理 %LOCALAPPDATA%\Wenyi\Desktop；自定义数据根目录、外部项目库和旧版目录均保留。删除目录库也会丢失项目列表，即使项目文件仍在，也不会自动重新发现。静默卸载及升级替换不会选择任何删除选项。恢复或重装时，请保持两项均不勾选，并保留独立备份。
关闭窗口与退出
- 最小化或关闭窗口不会暂停翻译。关闭会隐藏到系统托盘；托盘不可用时改为最小化。后台任务仍可能产生模型费用。
- 使用 Show Wenyi、macOS Dock，或再次打开程序／快捷方式，可恢复原窗口及其中的内存草稿、会话凭据。
- 使用 Quit Wenyi、Windows/Linux 的 Ctrl+Q 或 macOS 的 Cmd+Q 才会退出。Desktop 停止接收新任务，让现有任务安全停止；重新打开项目可继续已保存进度。
- 退出前保存草稿。 未保存的校阅、文风和设置编辑不是翻译检查点；隐藏窗口只是保留内存，不是可靠备份，也不会阻止电脑休眠。
若上次实例仍在退出，请等待结束，不要试图绕过其锁。
诊断与反馈
遇到 Desktop 问题时：
- 记录预期结果、实际现象及可见的错误编号。需要时启用设置 → 诊断与反馈 → 开启详细日志 30 分钟，然后复现问题；详细日志到期自动关闭，重启也会恢复默认。
- 选择导出诊断报告，范围可用最近 24 小时、本次启动或最近 7 天，再保存 ZIP。取消不会创建书籍导出任务或替换文件；覆盖已有文件需确认。
- 分享前检查 ZIP，不会自动上传任何内容。 请自行附到反馈中，补充复现步骤与错误编号。复制排查摘要可取得版本、最近错误编号和日志健康信息。
主界面或翻译引擎不可用时，可从原生应用／托盘菜单选择 Export diagnostic report…，或按 Ctrl+Shift+D（macOS 为 Cmd+Shift+D）。启动错误页也提供导出；完全无法启动的程序不能自行导出报告。
报告包含版本／平台信息及可用的应用日志，不包含书籍正文、提示词、模型响应、凭据、原始配置或项目数据库。时间和平台元信息仍可能具有识别性。报告有大小限制，可能缺少不可用或较早的记录；它不是完整历史，也不是项目备份。日志已回退到仅内存保存时，请在退出前导出。
打开日志目录可找到受管理的日志位置；清理应用日志会要求确认，只删除文译所属日志，不删除项目、译文、检查点、用量或其他程序放入的文件。