[!WARNING] 本项目仍处于早期开发阶段，功能、模型兼容性和稳定性尚不成熟，不建议用于生产环境或关键场景。
0.7.2-beta使用CN=VoxSub Dev (self-signed)开发者自签名，但该证书不受 Windows 公共信任链信任，系统仍可能显示风险提示，安全软件也可能误报。请在安装前核对 SHA256；不要为了安装而盲目关闭安全软件。
Windows 10/11 大众实时翻译软件：麦克风对话、会议/网课系统声音、本地视频音频 → 实时双语字幕。默认全本地离线，云 STT 与云翻译可独立配置并混合使用。
当前源码候选版本：0.9.0-beta；GitHub 当前公开下载仍为 0.7.2-beta。实时 OCR 视觉与稳定性修复继续沿用同一候选版本，在用户验收前不会冒充已发布版本。本地最新候选安装包为 277,309,314 字节（264.46 MiB），SHA256 59E68EAF93AF2C6D9C1D9D57BBF5BEEE18C891BA516A94E857635A22AAC54C42。
Intel NPU 支持仍有限。
0.4.1-beta已在 Intel AI Boost 真机验证 Hy-MT2 1.8B Q4/Q6/Q8：VoxSub 自动调度和禁止 CPU 回退的强制 NPU 推理均通过。Hy-MT2 7B Q4/Q6/Q8 仅依据 llama.cpp OpenVINO 公开兼容资料列为“NPU 待验证”，启动真实翻译探针失败时会自动改用核显或 CPU；现有 sherpa-onnx ASR 和 OPUS 运行时不支持 NPU。
悬浮窗兼容性说明（当前源码）：背景不透明度已与毛玻璃设置解耦，并修复关闭系统材质后出现不透明底色的问题。透明圆角窗口暂使用普通半透明背景，保留毛玻璃设置但不冒充已恢复真实模糊。隐藏渲染回归已通过，实际桌面效果仍需验收。详见 验收边界。
VoxSub-Setup-0.7.2-beta.exe 为 214,817,504 字节（204.87 MiB）；SHA256 313714AE3C9557B88EDBCEBBFCB768A15BBDD65915A5266E0B3EB1D82CAF2211。语言选项由当前模型组合生成：识别语言取识别模型与翻译模型输入能力的交集，目标语言取翻译模型的输出能力，不再全局限定中英日韩。OPUS仍只支持中英；部分模型没有强制指定语种接口，界面会说明。FunASR切换识别语言需先结束会话。
原生流式模型可显示并修订逐步识别结果；当前整段模型接入不等于原生逐词输出。设置 → 识别调优的「中英辅助预览（额外占用资源）」默认关闭，显式开启才额外加载内置中英预览识别器，不自动下载，不适用于其他源语言。默认不会为了纠错重跑每段音频。以上是源码改动，不代表已更新公开安装包。
Electron 字幕浮窗透明度：设置 → 外观 →「浮窗背景不透明度」，20%–100%（默认 92%）；拖动即时预览，松开或键盘调整完成后自动保存到统一配置 overlay_opacity。仅改变背景，不降低字幕文字不透明度；隐藏后重新显示保持当前值，重启或重载浮窗恢复已保存值；启动或后端就绪时的旧配置恢复不会覆盖更新的预览或修改。此项源码已加入，尚未重新打包发布。离线验证：cd frontend && npm run test:overlay-opacity；配置校验：python -m pytest tests/test_overlay_opacity.py。
A 麦克风同传：可选择麦克风，语音分句后显示原文与译文；可选同时录音，按开始 → 暂停/继续 → 结束并保存操作
B 应用 / 系统声音：可选择系统输出端点，或只捕获指定应用进程树的声音
C 音视频字幕：选择 MP4/MKV/MOV/MP3/WAV 等文件，内置 ffmpeg 自动提音并导出同名 SRT
D 模式 OCR 图片与屏幕翻译：与麦克风、系统声音和音视频字幕平级，共用左侧常驻的中→英/英→中翻译方向；可框选屏幕或上传 PNG/JPG/WebP/BMP/TIFF，查看识别原文、译文、原图标框与原位覆盖译文，并导出译后图片。实时模式进入后后台预热 OCR 与翻译模型，画面变化先返回快速结果，稳定后再用所选高质量模型纠偏；原图和未导出的译后图分别缓存在非 C 盘，默认每类 15 张，0 可无限保留
模型广场：按语音识别/翻译/语音朗读/OCR 分类和质量排序，可下载、切换、卸载开源模型；OCR 提供 PP-OCRv6 Tiny/Small/Medium 与 PP-OCRv5 文档手写增强档。根据本机 CPU、内存、GPU/显存标注“不推荐 / 较为推荐 / 推荐 / 满载”
国内外双下载源：自动并行测速并故障切换，也可手动固定 Hugging Face/GitHub 全球源或 ModelScope 中国源；数 GB 模型遇到 CDN 断流会保留进度并自动续传
大众硬件路由：独显 GPU → NPU → 核显 → CPU；当前源码已验证 Hy-MT2 1.8B Q4/Q6/Q8 可自动路由到 Intel NPU，其他模型按模型卡上的“已验证 / 待验证 / 不可用”标签处理
内置诊断与实时日志：诊断页可开启 20 分钟自动结束的临时调试会话；日志、诊断报告和会话导出均使用应用内保存窗口并在后台写入
新设备基础模型自修复：安装包附带 Silero VAD；首次运行自动修复到当前用户模型目录，下载任意 ASR 模型后即可使用，不再需要另找 VAD 文件
云端与混合模式：STT 和翻译分别选择本地或云端；云 STT/云翻译各自设置 API Key、BaseURL、模型名，支持云 STT + 本地翻译、本地 STT + 云翻译以及全云链路。云 STT 仅上传本地 VAD 已结束的语音片段
中日韩英翻译：语言方向支持中文、英文、日文、韩文之间互译，以及自动源语言 → 固定目标语言。内置 OPUS 极速档仍仅支持中英；日语/韩语请在设置中选择 Hy-MT2 质量档或云翻译。质量档使用模型广场中标注“33 种语言”的 Hy-MT2 模型，未安装模型时请先下载对应模型。
识别调优：保留自动/响应优先/均衡/准确优先/自定义的原有逻辑；新增“智能上下文”模式，可按句意动态延长停顿、在硬等待上限内合并片段、用常用词和近期重复上下文做保守纠偏，并可关闭或轻度清理独立语气词；鼠标悬停 i 即显示通俗说明，调优草稿需显式保存
智能上下文优化：实时翻译与文件字幕可让当前质量档/云翻译参考少量近期定稿，帮助代词消歧和术语一致；草稿与失败结果不进入参考，切换语言/模型/会话后失效。识别纠偏增加数字、否定与相近热词歧义保护。快档保持逐句翻译，普通调优模式不变；云模式会把有限参考文本发往已配置端点，不新增模型或落盘历史。这是启发式增强，不保证所有歧义都能解决。
0.6.0-beta 候选新增：智能上下文的当前句会在同一条草稿中接近逐词更新，后续识别可纠正前文；译文随原文动态替换，只接受最新请求结果；整句稳定后才进入历史并开始呈现下一句。选择 Qwen3/Fun-ASR/SenseVoice 等生成式本地 ASR 或云 STT 时，内置 Zipformer 会作为轻量草稿旁路连续出字，当前高质量模型仍负责最终纠偏定稿，不会高频重跑大模型或重复上传音频。“实时双语草稿”可独立关闭，关闭后仍保留智能断句、纠偏和语气词清理。
0.7.0-beta 候选新增：模型广场可下载 MeloTTS 中英双语、AISHELL3 中文轻量和 LJSpeech 英文轻量音色；设置 → 语音朗读可分别选择中英模型并在运行中立即切换。修复 TTS 开关只保存但当前会话不生效；实时双语草稿模式下会朗读定稿译文，不会反复抢读每一次草稿修订。旧版 models/tts/zh 和 models/tts/en 自动兼容。
0.7.1-beta 候选修复：英文实时草稿的全大写中间结果改为只读性更好的句子式显示；连续 partial 不再无限重置翻译防抖，动态译文会按节流频率追赶原文，同时保留终句翻译优先级。
0.7.2-beta 修复：安装器不再依赖会把主窗关闭误解为托盘隐藏的 Windows Restart Manager；新版使用专用退出信号，旧版则快速关闭 VoxSub 进程树，消除约半分钟假死与最终关闭失败。
0.8.0-beta 候选新增：独立 OCR 工作区包含“截图 OCR 翻译”和“实时区域 OCR”两种模式；内置离线 RapidOCR 保留每行坐标，实时覆盖窗不会进入后续截图，静止画面不会反复运行模型。截图像素始终只在本机内存处理；选择云翻译时仅发送识别后的文字。当前通用模型以印刷体为主，手写体和艺术体将通过可替换 OCR 后端继续优化。
0.9.0-beta 候选新增与修复：修复安装包缺少 rapidocr.main 以及旧 PyInstaller 运行时残留遮蔽依赖导致两种 OCR 均失败；升级前只清理应用管理的运行时目录，保留 Models 与 Cache；框选前等待 Windows 完成隐藏主窗，消除应用虚影；支持上传图片、原位覆盖预览及译后图片导出；原图与译后图采用非 C 盘分离缓存，默认每类 15 张/0 无限；模型广场新增四档 OCR 模型并可直接切换。OCR 现在是主界面 D 平级模式，常驻显示翻译方向；进入模式即后台预热 DirectML OCR 和翻译模型，变化画面使用快速首帧、稳定画面使用所选模型纠偏。实时首轮限制为 20–24 个版面块和约 2.2–2.4K 字符，批量 JSON 异常时不再退回逐行请求；采集队列只保留最新画面并丢弃过期结果，页面切换不会被旧翻译任务拖住。实时覆盖层的 Windows 捕获排除已修正，不再每轮隐藏/显示；同一行碎片和连续正文会先合并成段落块，主正文列优先，已有目标语言界面不重复翻译；译文以原 OCR 框高度为字号基准，在可用空闲区域内按实际字体度量整块换行并自适应字号，覆盖框之间严格不重叠；URL、标识符和无空格的中日韩文本也能任意字符换行，避免末尾内容被裁剪；失败项保留可读原文，GPU 失败时安全回退 CPU。安装升级现在为正常收尾保留 5 秒、强制关闭后再复核进程状态，且运行标记保持到进程真正终止；应用退出会主动关闭 Pipeline 及其本地翻译进程，安装器还会按当前安装目录清理旧版本遗留的 llama-server.exe，避免 ggml-cpu.dll 被占用导致错误 5；本次打包成品的真实退出握手为 4.36 秒，不再因退出竞态误报“无法关闭 VoxSub”。
字幕会话：主窗与浮窗文字可复制，当前会话可清空或保存为 TXT/SRT/VTT；浮窗可选仅原文、仅译文或对照翻译，并可分别调节内容边距和原译间距
Soft Premium UI：深色 / 浅色 / 跟随系统；设置、模型广场和诊断页统一视觉；字幕浮窗支持更宽字号范围、自由缩放、拖动、锁定与鼠标穿透，锁定后悬停只显示“解锁”
固定尺寸长字幕：翻译到长句时不再自动扩大浮窗，内容会在用户设定的宽高内换行；普通滚轮查看当前长句，Ctrl + 滚轮翻看字幕历史
统一选择控件：设置页单选项保持稳定圆形，开关使用圆角轨道，模型广场筛选按钮保持胶囊形；不再因 Windows Qt 选中态变成方形
安装器语言：根据 Windows 界面语言自动选择简体中文、繁体中文或英文，无匹配翻译时回退英文
模型存储：新安装默认使用安装目录下的 Models 文件夹，并按 stt、translate、vad、tts 用途整理；升级用户继续使用原来的模型目录，只有在设置中主动更改时才迁移。设置支持更改位置、迁移已有模型和手动导入，更新安装包不会删除已下载模型。
0.5.0-beta 新增：独立、有界的上下文处理阶段；生成式/云 STT 可在翻译前合并未完片段，流式 Zipformer 可在句意未完时延长静音边界；等待始终受硬上限约束，纠偏只做可记录的小范围替换，旧调优模式完全旁路新阶段。
0.4.2-beta 候选修复：配置集中校验和安全迁移；采集、识别、翻译、TTS 队列全部有容量与过载策略；TTS 已接入独立播放线程；下载、模型提交和字幕导出使用完整性校验与原子写入；核心 Pipeline、硬件探测和 llama 启动流程已按职责拆分；外观页的译文字号和浮窗不透明度改用与识别调优一致、上下均可点击的箭头控件。
0.4.1-beta 修复：识别调优的上/下调节按钮均可点击；模型迁移放在后台执行，避免卡死或关闭页面时崩溃；迁移后会同步修正模型清单并立即使用新目录，不再误报文件缺失或继续读取旧目录；升级期间会兼容查找旧模型根目录中的翻译模型；Teams 新版窗口会自动捕获其宿主进程及子进程声音；长字幕不会再把浮窗撑到屏幕外。
更新说明：新版首次启动只显示一次本版更新内容，之后可在设置 → 关于中查看历史更新说明。
全屏体验：主窗口全屏时打开设置或模型广场，返回后仍保持全屏。
模型广场不是模型仓库的全量镜像。目录只保留 VoxSub 已有运行时适配、许可证明确，并在相近资源档位仍有价值的模型：Fun-ASR-Nano、Qwen3-ASR、SenseVoice Small，Hy-MT2 1.8B/7B 的 Q4/Q6/Q8 量化档，以及 MeloTTS 中英双语、AISHELL3 中文轻量、LJSpeech 英文轻量朗读模型。内置 Zipformer/OPUS 仅作为极低资源兜底。每张模型卡都会明确显示 NPU 可用性；“NPU 可用”只用于已完成强制 NPU 推理和应用自动调度双重验证的精确模型文件。
当前开发机没有 Intel NPU 时不能验证真实 NPU 推理，不能用 CPU/GPU 结果代替。请在装有 Intel AI Boost、已退出 VoxSub 的 Windows 电脑上执行下面的探针；它会在每一轮分别运行禁止 CPU 回退的 llama-server，以及 VoxSub 的强制 NPU 启动路径。第一轮还会记录默认自动路由，默认路由可能因为独显优先而选择 GPU，这不算失败：
$runtime = (Get-ChildItem "$env:TEMP\VoxSub_npu_runtime_*\llama-server.exe" -File -ErrorAction SilentlyContinue | Select-Object -First 1).DirectoryName
powershell -ExecutionPolicy Bypass -File .\scripts\npu_probe_matrix.ps1 `
-ModelPath "C:\path\to\Hy-MT2-1.8B-Q8_0.gguf" `
-LlamaDir $runtime -Iterations 3
如果运行时不在 TEMP，请把 -LlamaDir 改成包含 llama-server.exe、ggml-openvino.dll 和 openvino_intel_npu_plugin.dll 的目录。首次 OpenVINO 编译可能较慢，可用 -StartupTimeoutSeconds 1200 延长等待。结果保存在 %LOCALAPPDATA%\VoxSub\diagnostics\npu-matrix\<时间>\matrix-summary.json；请把该 JSON、每个 run-* 目录中的 probe.log、llama-server.stdout.log、llama-server.stderr.log 和 app-path.json 发给我，不要上传 GGUF 模型、音频或字幕内容。PASS 要求每轮的生产路径（production_openvino0_env_npu）和强制 VoxSub 路径都成功；另外两个直接变体仅用于定位参数差异，不会改变应用路由。失败时每轮仍会继续，便于比较驱动、编译缓存和进程状态的变化。只检查设备和驱动时可运行 scripts\npu_probe.ps1 -DriverCheckOnly，探测会依次尝试 WMI、Get-PnpDevice 和 pnputil。
建议先不加额外参数运行，让脚本验证设备和驱动。如果日志显示 npu_device_not_detected 或 npu_device_inventory_access_denied，但你确认这是 Intel NPU 真机，可再运行同一命令并加 -SkipHardwarePreflight：该参数只跳过 Windows 设备枚举，仍会启动真实 llama-server、执行健康检查和翻译，并且禁止 CPU 回退；只有日志出现明确的 OpenVINO NPU 标志才算通过。不要在没有 Intel NPU 的电脑上用这个参数把结果当成成功。
探针中的 voxsub_forced_npu 会设置 VOXSUB_LLAMA_TARGET=npu，调用与应用完全相同的运行时选择代码。也可以单独验证应用路径：
$env:VOXSUB_LLAMA_DIR = $runtime
$env:VOXSUB_LLAMA_TARGET = "npu"
python .\scripts\npu_app_probe.py --model-path "C:\path\to\Hy-MT2-1.8B-Q8_0.gguf" --runtime-dir $runtime --force npu
Remove-Item Env:VOXSUB_LLAMA_TARGET
强制模式只有在应用实际选择 openvino/NPU、健康检查和真实翻译都通过时才返回成功；运行时缺失、设备/驱动不可用或推理失败都会明确失败，绝不会把 GPU/CPU 回落伪报为 NPU。普通启动不设置该变量，现有自动路由和回退逻辑不变。
要求：Windows 10/11。源码运行不会把模型或配置写进 Git 工作树；Python、uv 和 Git 缺失时，一键启动脚本会在用户目录自动准备便携版本。
开发者手动准备（可选）：
git clone https://github.com/tuotuonuts/VoxSub.git
cd VoxSub
uv venv --python 3.11
uv pip sync --python .venv\Scripts\python.exe requirements.lock
.\.venv\Scripts\python.exe -m pytest tests/ -q
日常更新和源码启动：
git pull --ff-only
.\.venv\Scripts\python.exe -m pytest tests/ -q
.\.venv\Scripts\python.exe run_app.py
上述默认测试不会访问真实麦克风、回环或扬声器，因此不会播放测试声音或占用声卡。真实设备验收保留为手动步骤，仅在排查音频设备、驱动或按应用音频采集问题时执行：
# 真实麦克风/回环/扬声器测试；其中按应用音频测试仍需显式确认播放短音
.\.venv\Scripts\python.exe -m pytest tests/ -q -o "addopts=" -m hardware_audio
# 额外验证按应用音频捕获，会播放两段低音量短测试音
$env:VOXSUB_TEST_PROCESS_AUDIO = "1"
.\.venv\Scripts\python.exe -m pytest tests/test_process_audio.py -q -o "addopts=" -m hardware_audio
Remove-Item Env:VOXSUB_TEST_PROCESS_AUDIO
给朋友使用时，先获得一个带 .git 目录的源码副本（首次可由熟悉 Git 的人完成克隆或使用 GitHub Desktop），然后双击项目根目录的 更新并启动测试版.bat。以后每次双击同一个文件即可自动更新源码、准备本机 Python/uv、创建独立 .venv、同步 requirements.lock 并启动 run_app.py。Python、uv 或 Git 不存在时，脚本会下载固定版本到 %LOCALAPPDATA%\VoxSub\bootstrap，无需管理员权限或手动配置。首次真正使用质量翻译时，应用还会先自动修复缺失的 CPU/Vulkan/OpenVINO 运行时并执行真实探针；修复失败才按 GPU → CPU 顺序降级，不会伪报 NPU。脚本会清理 PYTHONPATH / PYTHONHOME，测试环境自动使用 testing 标记。GitHub 下载的 ZIP 不含 .git，因此不能作为后续 git pull 更新的源码副本。
关闭主窗口右上角通常只是隐藏到系统托盘，并不会结束 VoxSub。真正退出源码测试版时，必须右键托盘图标并选择“退出应用”。启动脚本会在 git pull 前检查 VoxSub、源码 Python 和 llama-server 进程；发现仍在运行时只提示先执行“退出应用”，不会强制杀进程。应用返回后，脚本还会等待相关子进程结束，确认干净退出后才返回。
脚本优先使用已安装的 uv，否则自动下载并校验便携 uv；没有系统 Python 时由 uv 自动下载并管理 Python 3.11。若同步时发现 .venv 被占用或权限异常，脚本会先将它改名备份，再用当前电脑重建后重试。CPU/Vulkan/OpenVINO 运行时下载会校验远端固定的文件大小、ZIP 文件头和 SHA256，失败自动重试 3 次；如果代理或网关返回 HTML、下载截断或缓存损坏，窗口和 %LOCALAPPDATA%\VoxSub\diagnostics\source-run\ 日志会记录实际大小、摘要前缀和文件头，便于定位网络问题。基础功能会在运行时网络失败时继续启动，网络恢复后再次双击即可重试。脚本不会复制其他电脑的 .venv，也不会删除模型、配置或用户数据。
启动前脚本还会检查 Git 跟踪的源码是否有未提交修改。发现时会列出文件并停止更新，防止 git pull 覆盖本地代码；模型、配置、日志和 .venv 不会触发该检查。需要保留本地代码时，请先自行提交到分支；只想临时保留时，可在项目目录执行：
git stash push -u -m "before VoxSub source update"
git pull --ff-only
之后可用 git stash list 查看暂存内容；确认需要恢复时再执行 git stash pop。若上游也修改了相同文件，恢复时可能需要手动处理 Git 合并冲突。
脚本每次自动设置 VOXSUB_ENVIRONMENT=testing。如果希望朋友的诊断报告进入你的 Sentry，可由你提前把 DSN 放到朋友电脑的 %LOCALAPPDATA%\VoxSub\sentry_dsn.txt（一行纯文本）；脚本会自动读取，朋友无需手动配置。没有该文件时仅写本地日志，不会联网。
run_app.py 是源码和打包版共用的入口。git pull 只更新 Git 跟踪的源码；配置保存在 %LOCALAPPDATA%\VoxSub\config.json，模型和缓存由 model_storage.py 放在用户模型根目录，不会被拉取、覆盖或删除。只有依赖发生变化时才需要重新同步：
uv pip sync --python .venv\Scripts\python.exe requirements.lock
更新直接依赖后，在已验证的 Windows Python 3.11 环境重建锁文件：
uv pip compile requirements.txt --python .venv\Scripts\python.exe --python-platform windows --generate-hashes -o requirements.lock
不设置 DSN 时不会联网，原有本地日志和诊断页照常工作。需要启用时，在启动进程的 PowerShell 会话中设置：
$env:VOXSUB_SENTRY_DSN = "https://<public-key>@<host>/<project-id>"
$env:VOXSUB_ENVIRONMENT = "development" # development | testing | production
$env:VOXSUB_BUILD = "source" # 可选，标识本次源码/构建
.\.venv\Scripts\python.exe run_app.py
也可以把 sentry_dsn、sentry_environment 和 sentry_build 写入 %LOCALAPPDATA%\VoxSub\config.json；环境变量优先于本地配置。DSN 不要提交到 Git 或写入源码。
Sentry 事件只包含软件版本、构建号、环境、操作系统、CPU、GPU/NPU、内存、驱动和推理后端，以及经过过滤的异常类型；不会上传 API Key、音频、字幕正文、识别文本、用户文件内容或私人路径。网络不可用时事件会丢弃，不会影响应用。
本地日志位于 %LOCALAPPDATA%\VoxSub\logs\voxsub.log，也可在应用“诊断 → 日志”页查看和导出。需要更详细现场时，在“诊断 → 日志”开启“诊断调试”；会话默认 20 分钟后自动结束，也可手动关闭。手动上传会话期间只提交该会话标记的日志，并附带行数与隐私过滤统计。“诊断 → 自检”页的“导出报告 (txt)”会生成当前最新自检结果；修复按钮只处理该结果中明确声明的目标。
配置 DSN 后，诊断页的“自检”会显示“发送到 Sentry”，用于上传当前最新自检报告和本地日志快照（隐私过滤后），不会重新执行自检；“日志”页也提供独立的“上传日志到 Sentry”，不需要先运行自检。为避免大日志把现场问题挤出附件，超过上传上限时会保留最新的完整日志行。上传完成后，日志页会显示来源和上传时间范围、原始/上传/省略行数、脱敏统计；同一份安全元数据也会写入 Sentry 附件头部。未配置或网络失败时不会影响应用。
“诊断 → 日志 → 清除本机日志”需要确认后才执行：它会清空 %LOCALAPPDATA%\VoxSub\logs 中的当前/轮转日志，以及 %LOCALAPPDATA%\VoxSub\diagnostics 中的启动日志；不会删除模型、配置、用户数据、Sentry 配置或已手动导出的报告。正在运行的 VoxSub 会继续写入一份新的空日志。
也可以直接在“设置 → 关于 → 诊断上报”中填写 DSN、环境和构建标识并保存；保存后当前进程立即重载配置，无需重启。
DSN 只负责上报，不能读取 Sentry Issue。需要长期排查时，维护者可创建只读 Sentry API Token，并仅勾选 org:read、project:read、event:read。不要使用写入或管理权限，也不要把 Token 发到聊天、写入源码、config.json 或 DSN 文件。
首次在本机执行下列命令；脚本会在隐藏输入提示中请求 Token，随后自动从可访问组织中定位 voxsub 项目并写入本机配置：
powershell -ExecutionPolicy Bypass -File .\scripts\initialize_sentry_diagnostics.ps1
令牌保存在 %LOCALAPPDATA%\VoxSub\sentry_auth_token.txt，项目定位配置保存在 %LOCALAPPDATA%\VoxSub\sentry_api.json，都不进入 Git，也不被 VoxSub 应用读取。默认使用德国数据区 https://de.sentry.io；若项目位于其他数据区，可传入 -SentryBase https://sentry.io。
配置完成后，可只读查看未解决 Issue：
powershell -ExecutionPolicy Bypass -File .\scripts\get_sentry_issues.ps1
令牌应设置较短有效期。设备不再用于维护或 Token 泄露时，立即在 Sentry 的 Auth Tokens 页面撤销。
构建安装包：
powershell -ExecutionPolicy Bypass -File scripts\build.ps1
安装包默认输出到项目上一级的 Release 目录；本项目开发工作区对应 D:\OneDrive\app_dve\Release。新安装默认把模型放在安装目录下的 Models 文件夹，并按用途分到 stt、translate、vad、tts、ocr；升级用户保留现有模型根目录，直到主动在设置中更改。模型属于用户数据，不会被安装包重复分发或在更新时删除。当前公开的 0.7.2-beta 安装包为 214,817,504 字节，SHA256 313714AE3C9557B88EDBCEBBFCB768A15BBDD65915A5266E0B3EB1D82CAF2211。本地最新候选 0.9.0-beta 为 277,309,314 字节（264.46 MiB），SHA256 59E68EAF93AF2C6D9C1D9D57BBF5BEEE18C891BA516A94E857635A22AAC54C42；本次构建未签名，用户验证前不会创建 GitHub Release。
voxsub/ Python 核心（识别 / 翻译 / TTS / OCR / 硬件探测 / 流水线）
frontend/ Electron 前端（界面、IPC 适配层、开发工具）
tests/ pytest 测试
scripts/ 构建/工具脚本
models/ 运行时模型缓存（gitignore）
界面是 Electron + TypeScript，Python 核心通过 stdin/stdout 上的 JSON Lines
协议被驱动（frontend/backend/ipc_server.py）。核心层不感知界面存在 ——
tests/test_architecture.py 强制这条边界。
开发启动（免打包）：
cd frontend
npm run launch # 增量构建 + 启动
npm run launch:silent # 静默模式：窗口不显示，供自动化验证
Qt 版（PySide6）前端已冻结在 qt-legacy 分支，保留完整源码与提交历史。
在 设置 → 快捷键 中自定义，默认全部留空、不占用任何组合键。可以录入组合键或手动输入，例如 Ctrl+Alt+T；点击“保存快捷键”后生效，清空并保存即可停用。
支持：显示/隐藏主窗、开始/结束当前会话、暂停/继续、结束会话、切换“同时录音”、显示/隐藏字幕浮窗、切换浮窗鼠标穿透。应用保持运行时，最小化或隐藏到托盘不影响已注册快捷键；完全退出后快捷键停用。会话动作使用当前模式、音源和模型，不自动选择文件或操作 OCR；录音切换遵循当前会话能力限制，不自行开始采集。
自动检查应用内重复、已知系统保留组合和系统注册失败。保存冲突或写入失败时保留旧设置与旧注册；其他软件只在其自身窗口内使用的快捷键无法可靠检测，应避免常用编辑组合键。录入期间暂时停用全局快捷键，取消、失焦、最小化或关页后恢复；恢复被系统拒绝时明确标为未生效。重启后重新注册并报告占用冲突，不静默换键。
音视频文件模式现在可在 识别＋翻译（双模型） 与 语音直接翻译（单模型） 之间选择；默认仍为双模型。主页文件区和设置页复用同一个选择控件。
.voxsub.srt，已有同名文件时创建新文件；手动导出支持 SRT、VTT、TXT，保留媒体时间戳。源码版额外运行 powershell -NoProfile -ExecutionPolicy Bypass -File scripts/setup-speech-runtime.ps1 安装隔离的 CPU 环境 .venv-speech；加 -Device cuda 安装官方 PyTorch CUDA 12.8 环境 .venv-speech-cuda，需要兼容的 NVIDIA 驱动与支持 BF16 的显卡。可用 -China 选择依赖索引镜像。组件不会混入轻量后端环境，也不会在用户点击“开始”时偷偷安装。完整发布流程会单独打包 VoxSubSpeechWorker，缺少组件时阻止发布。
测试边界与剩余限制见 docs/SINGLE_MODEL_SPEECH_ACCEPTANCE.md。这不是安装包已发布或现有用户实例已更新的声明。
模型广场新增 SeamlessStreaming，提供固定权重的全球／大陆镜像、暂停续传及官方运行说明。它的官方依赖需要 Linux／WSL，本应用只提供下载入口，不将它列为 Windows 内可直接使用的模型；不自动安装或启动 WSL。许可为 CC-BY-NC-4.0，仅非商业用途。
悬浮窗独立于主窗口缩放，按渲染后的字幕卡片边界裁剪；显示、缩放、尺寸变化会更新并读回原生区域和材质状态。失败退回普通半透明背景，必要时只重建该悬浮窗，保持隐藏／穿透状态。诊断分别记录裁剪、材质与桌面效果，隐藏窗口检查不会被标作可见桌面验收。最新范围见 docs/GPU_OVERLAY_DOWNLOAD_ACCEPTANCE.md。
[!WARNING] 本项目仍处于早期开发阶段，功能、模型兼容性和稳定性尚不成熟，不建议用于生产环境或关键场景。
0.7.2-beta使用CN=VoxSub Dev (self-signed)开发者自签名，但该证书不受 Windows 公共信任链信任，系统仍可能显示风险提示，安全软件也可能误报。请在安装前核对 SHA256；不要为了安装而盲目关闭安全软件。
Windows 10/11 大众实时翻译软件：麦克风对话、会议/网课系统声音、本地视频音频 → 实时双语字幕。默认全本地离线，云 STT 与云翻译可独立配置并混合使用。
当前源码候选版本：0.9.0-beta；GitHub 当前公开下载仍为 0.7.2-beta。实时 OCR 视觉与稳定性修复继续沿用同一候选版本，在用户验收前不会冒充已发布版本。本地最新候选安装包为 277,309,314 字节（264.46 MiB），SHA256 59E68EAF93AF2C6D9C1D9D57BBF5BEEE18C891BA516A94E857635A22AAC54C42。
Intel NPU 支持仍有限。
0.4.1-beta已在 Intel AI Boost 真机验证 Hy-MT2 1.8B Q4/Q6/Q8：VoxSub 自动调度和禁止 CPU 回退的强制 NPU 推理均通过。Hy-MT2 7B Q4/Q6/Q8 仅依据 llama.cpp OpenVINO 公开兼容资料列为“NPU 待验证”，启动真实翻译探针失败时会自动改用核显或 CPU；现有 sherpa-onnx ASR 和 OPUS 运行时不支持 NPU。
悬浮窗兼容性说明（当前源码）：背景不透明度已与毛玻璃设置解耦，并修复关闭系统材质后出现不透明底色的问题。透明圆角窗口暂使用普通半透明背景，保留毛玻璃设置但不冒充已恢复真实模糊。隐藏渲染回归已通过，实际桌面效果仍需验收。详见 验收边界。
VoxSub-Setup-0.7.2-beta.exe 为 214,817,504 字节（204.87 MiB）；SHA256 313714AE3C9557B88EDBCEBBFCB768A15BBDD65915A5266E0B3EB1D82CAF2211。语言选项由当前模型组合生成：识别语言取识别模型与翻译模型输入能力的交集，目标语言取翻译模型的输出能力，不再全局限定中英日韩。OPUS仍只支持中英；部分模型没有强制指定语种接口，界面会说明。FunASR切换识别语言需先结束会话。
原生流式模型可显示并修订逐步识别结果；当前整段模型接入不等于原生逐词输出。设置 → 识别调优的「中英辅助预览（额外占用资源）」默认关闭，显式开启才额外加载内置中英预览识别器，不自动下载，不适用于其他源语言。默认不会为了纠错重跑每段音频。以上是源码改动，不代表已更新公开安装包。
Electron 字幕浮窗透明度：设置 → 外观 →「浮窗背景不透明度」，20%–100%（默认 92%）；拖动即时预览，松开或键盘调整完成后自动保存到统一配置 overlay_opacity。仅改变背景，不降低字幕文字不透明度；隐藏后重新显示保持当前值，重启或重载浮窗恢复已保存值；启动或后端就绪时的旧配置恢复不会覆盖更新的预览或修改。此项源码已加入，尚未重新打包发布。离线验证：cd frontend && npm run test:overlay-opacity；配置校验：python -m pytest tests/test_overlay_opacity.py。
A 麦克风同传：可选择麦克风，语音分句后显示原文与译文；可选同时录音，按开始 → 暂停/继续 → 结束并保存操作
B 应用 / 系统声音：可选择系统输出端点，或只捕获指定应用进程树的声音
C 音视频字幕：选择 MP4/MKV/MOV/MP3/WAV 等文件，内置 ffmpeg 自动提音并导出同名 SRT
D 模式 OCR 图片与屏幕翻译：与麦克风、系统声音和音视频字幕平级，共用左侧常驻的中→英/英→中翻译方向；可框选屏幕或上传 PNG/JPG/WebP/BMP/TIFF，查看识别原文、译文、原图标框与原位覆盖译文，并导出译后图片。实时模式进入后后台预热 OCR 与翻译模型，画面变化先返回快速结果，稳定后再用所选高质量模型纠偏；原图和未导出的译后图分别缓存在非 C 盘，默认每类 15 张，0 可无限保留
模型广场：按语音识别/翻译/语音朗读/OCR 分类和质量排序，可下载、切换、卸载开源模型；OCR 提供 PP-OCRv6 Tiny/Small/Medium 与 PP-OCRv5 文档手写增强档。根据本机 CPU、内存、GPU/显存标注“不推荐 / 较为推荐 / 推荐 / 满载”
国内外双下载源：自动并行测速并故障切换，也可手动固定 Hugging Face/GitHub 全球源或 ModelScope 中国源；数 GB 模型遇到 CDN 断流会保留进度并自动续传
大众硬件路由：独显 GPU → NPU → 核显 → CPU；当前源码已验证 Hy-MT2 1.8B Q4/Q6/Q8 可自动路由到 Intel NPU，其他模型按模型卡上的“已验证 / 待验证 / 不可用”标签处理
内置诊断与实时日志：诊断页可开启 20 分钟自动结束的临时调试会话；日志、诊断报告和会话导出均使用应用内保存窗口并在后台写入
新设备基础模型自修复：安装包附带 Silero VAD；首次运行自动修复到当前用户模型目录，下载任意 ASR 模型后即可使用，不再需要另找 VAD 文件
云端与混合模式：STT 和翻译分别选择本地或云端；云 STT/云翻译各自设置 API Key、BaseURL、模型名，支持云 STT + 本地翻译、本地 STT + 云翻译以及全云链路。云 STT 仅上传本地 VAD 已结束的语音片段
中日韩英翻译：语言方向支持中文、英文、日文、韩文之间互译，以及自动源语言 → 固定目标语言。内置 OPUS 极速档仍仅支持中英；日语/韩语请在设置中选择 Hy-MT2 质量档或云翻译。质量档使用模型广场中标注“33 种语言”的 Hy-MT2 模型，未安装模型时请先下载对应模型。
识别调优：保留自动/响应优先/均衡/准确优先/自定义的原有逻辑；新增“智能上下文”模式，可按句意动态延长停顿、在硬等待上限内合并片段、用常用词和近期重复上下文做保守纠偏，并可关闭或轻度清理独立语气词；鼠标悬停 i 即显示通俗说明，调优草稿需显式保存
智能上下文优化：实时翻译与文件字幕可让当前质量档/云翻译参考少量近期定稿，帮助代词消歧和术语一致；草稿与失败结果不进入参考，切换语言/模型/会话后失效。识别纠偏增加数字、否定与相近热词歧义保护。快档保持逐句翻译，普通调优模式不变；云模式会把有限参考文本发往已配置端点，不新增模型或落盘历史。这是启发式增强，不保证所有歧义都能解决。
0.6.0-beta 候选新增：智能上下文的当前句会在同一条草稿中接近逐词更新，后续识别可纠正前文；译文随原文动态替换，只接受最新请求结果；整句稳定后才进入历史并开始呈现下一句。选择 Qwen3/Fun-ASR/SenseVoice 等生成式本地 ASR 或云 STT 时，内置 Zipformer 会作为轻量草稿旁路连续出字，当前高质量模型仍负责最终纠偏定稿，不会高频重跑大模型或重复上传音频。“实时双语草稿”可独立关闭，关闭后仍保留智能断句、纠偏和语气词清理。
0.7.0-beta 候选新增：模型广场可下载 MeloTTS 中英双语、AISHELL3 中文轻量和 LJSpeech 英文轻量音色；设置 → 语音朗读可分别选择中英模型并在运行中立即切换。修复 TTS 开关只保存但当前会话不生效；实时双语草稿模式下会朗读定稿译文，不会反复抢读每一次草稿修订。旧版 models/tts/zh 和 models/tts/en 自动兼容。
0.7.1-beta 候选修复：英文实时草稿的全大写中间结果改为只读性更好的句子式显示；连续 partial 不再无限重置翻译防抖，动态译文会按节流频率追赶原文，同时保留终句翻译优先级。
0.7.2-beta 修复：安装器不再依赖会把主窗关闭误解为托盘隐藏的 Windows Restart Manager；新版使用专用退出信号，旧版则快速关闭 VoxSub 进程树，消除约半分钟假死与最终关闭失败。
0.8.0-beta 候选新增：独立 OCR 工作区包含“截图 OCR 翻译”和“实时区域 OCR”两种模式；内置离线 RapidOCR 保留每行坐标，实时覆盖窗不会进入后续截图，静止画面不会反复运行模型。截图像素始终只在本机内存处理；选择云翻译时仅发送识别后的文字。当前通用模型以印刷体为主，手写体和艺术体将通过可替换 OCR 后端继续优化。
0.9.0-beta 候选新增与修复：修复安装包缺少 rapidocr.main 以及旧 PyInstaller 运行时残留遮蔽依赖导致两种 OCR 均失败；升级前只清理应用管理的运行时目录，保留 Models 与 Cache；框选前等待 Windows 完成隐藏主窗，消除应用虚影；支持上传图片、原位覆盖预览及译后图片导出；原图与译后图采用非 C 盘分离缓存，默认每类 15 张/0 无限；模型广场新增四档 OCR 模型并可直接切换。OCR 现在是主界面 D 平级模式，常驻显示翻译方向；进入模式即后台预热 DirectML OCR 和翻译模型，变化画面使用快速首帧、稳定画面使用所选模型纠偏。实时首轮限制为 20–24 个版面块和约 2.2–2.4K 字符，批量 JSON 异常时不再退回逐行请求；采集队列只保留最新画面并丢弃过期结果，页面切换不会被旧翻译任务拖住。实时覆盖层的 Windows 捕获排除已修正，不再每轮隐藏/显示；同一行碎片和连续正文会先合并成段落块，主正文列优先，已有目标语言界面不重复翻译；译文以原 OCR 框高度为字号基准，在可用空闲区域内按实际字体度量整块换行并自适应字号，覆盖框之间严格不重叠；URL、标识符和无空格的中日韩文本也能任意字符换行，避免末尾内容被裁剪；失败项保留可读原文，GPU 失败时安全回退 CPU。安装升级现在为正常收尾保留 5 秒、强制关闭后再复核进程状态，且运行标记保持到进程真正终止；应用退出会主动关闭 Pipeline 及其本地翻译进程，安装器还会按当前安装目录清理旧版本遗留的 llama-server.exe，避免 ggml-cpu.dll 被占用导致错误 5；本次打包成品的真实退出握手为 4.36 秒，不再因退出竞态误报“无法关闭 VoxSub”。
字幕会话：主窗与浮窗文字可复制，当前会话可清空或保存为 TXT/SRT/VTT；浮窗可选仅原文、仅译文或对照翻译，并可分别调节内容边距和原译间距
Soft Premium UI：深色 / 浅色 / 跟随系统；设置、模型广场和诊断页统一视觉；字幕浮窗支持更宽字号范围、自由缩放、拖动、锁定与鼠标穿透，锁定后悬停只显示“解锁”
固定尺寸长字幕：翻译到长句时不再自动扩大浮窗，内容会在用户设定的宽高内换行；普通滚轮查看当前长句，Ctrl + 滚轮翻看字幕历史
统一选择控件：设置页单选项保持稳定圆形，开关使用圆角轨道，模型广场筛选按钮保持胶囊形；不再因 Windows Qt 选中态变成方形
安装器语言：根据 Windows 界面语言自动选择简体中文、繁体中文或英文，无匹配翻译时回退英文
模型存储：新安装默认使用安装目录下的 Models 文件夹，并按 stt、translate、vad、tts 用途整理；升级用户继续使用原来的模型目录，只有在设置中主动更改时才迁移。设置支持更改位置、迁移已有模型和手动导入，更新安装包不会删除已下载模型。
0.5.0-beta 新增：独立、有界的上下文处理阶段；生成式/云 STT 可在翻译前合并未完片段，流式 Zipformer 可在句意未完时延长静音边界；等待始终受硬上限约束，纠偏只做可记录的小范围替换，旧调优模式完全旁路新阶段。
0.4.2-beta 候选修复：配置集中校验和安全迁移；采集、识别、翻译、TTS 队列全部有容量与过载策略；TTS 已接入独立播放线程；下载、模型提交和字幕导出使用完整性校验与原子写入；核心 Pipeline、硬件探测和 llama 启动流程已按职责拆分；外观页的译文字号和浮窗不透明度改用与识别调优一致、上下均可点击的箭头控件。
0.4.1-beta 修复：识别调优的上/下调节按钮均可点击；模型迁移放在后台执行，避免卡死或关闭页面时崩溃；迁移后会同步修正模型清单并立即使用新目录，不再误报文件缺失或继续读取旧目录；升级期间会兼容查找旧模型根目录中的翻译模型；Teams 新版窗口会自动捕获其宿主进程及子进程声音；长字幕不会再把浮窗撑到屏幕外。
更新说明：新版首次启动只显示一次本版更新内容，之后可在设置 → 关于中查看历史更新说明。
全屏体验：主窗口全屏时打开设置或模型广场，返回后仍保持全屏。
模型广场不是模型仓库的全量镜像。目录只保留 VoxSub 已有运行时适配、许可证明确，并在相近资源档位仍有价值的模型：Fun-ASR-Nano、Qwen3-ASR、SenseVoice Small，Hy-MT2 1.8B/7B 的 Q4/Q6/Q8 量化档，以及 MeloTTS 中英双语、AISHELL3 中文轻量、LJSpeech 英文轻量朗读模型。内置 Zipformer/OPUS 仅作为极低资源兜底。每张模型卡都会明确显示 NPU 可用性；“NPU 可用”只用于已完成强制 NPU 推理和应用自动调度双重验证的精确模型文件。
当前开发机没有 Intel NPU 时不能验证真实 NPU 推理，不能用 CPU/GPU 结果代替。请在装有 Intel AI Boost、已退出 VoxSub 的 Windows 电脑上执行下面的探针；它会在每一轮分别运行禁止 CPU 回退的 llama-server，以及 VoxSub 的强制 NPU 启动路径。第一轮还会记录默认自动路由，默认路由可能因为独显优先而选择 GPU，这不算失败：
$runtime = (Get-ChildItem "$env:TEMP\VoxSub_npu_runtime_*\llama-server.exe" -File -ErrorAction SilentlyContinue | Select-Object -First 1).DirectoryName
powershell -ExecutionPolicy Bypass -File .\scripts\npu_probe_matrix.ps1 `
-ModelPath "C:\path\to\Hy-MT2-1.8B-Q8_0.gguf" `
-LlamaDir $runtime -Iterations 3
如果运行时不在 TEMP，请把 -LlamaDir 改成包含 llama-server.exe、ggml-openvino.dll 和 openvino_intel_npu_plugin.dll 的目录。首次 OpenVINO 编译可能较慢，可用 -StartupTimeoutSeconds 1200 延长等待。结果保存在 %LOCALAPPDATA%\VoxSub\diagnostics\npu-matrix\<时间>\matrix-summary.json；请把该 JSON、每个 run-* 目录中的 probe.log、llama-server.stdout.log、llama-server.stderr.log 和 app-path.json 发给我，不要上传 GGUF 模型、音频或字幕内容。PASS 要求每轮的生产路径（production_openvino0_env_npu）和强制 VoxSub 路径都成功；另外两个直接变体仅用于定位参数差异，不会改变应用路由。失败时每轮仍会继续，便于比较驱动、编译缓存和进程状态的变化。只检查设备和驱动时可运行 scripts\npu_probe.ps1 -DriverCheckOnly，探测会依次尝试 WMI、Get-PnpDevice 和 pnputil。
建议先不加额外参数运行，让脚本验证设备和驱动。如果日志显示 npu_device_not_detected 或 npu_device_inventory_access_denied，但你确认这是 Intel NPU 真机，可再运行同一命令并加 -SkipHardwarePreflight：该参数只跳过 Windows 设备枚举，仍会启动真实 llama-server、执行健康检查和翻译，并且禁止 CPU 回退；只有日志出现明确的 OpenVINO NPU 标志才算通过。不要在没有 Intel NPU 的电脑上用这个参数把结果当成成功。
探针中的 voxsub_forced_npu 会设置 VOXSUB_LLAMA_TARGET=npu，调用与应用完全相同的运行时选择代码。也可以单独验证应用路径：
$env:VOXSUB_LLAMA_DIR = $runtime
$env:VOXSUB_LLAMA_TARGET = "npu"
python .\scripts\npu_app_probe.py --model-path "C:\path\to\Hy-MT2-1.8B-Q8_0.gguf" --runtime-dir $runtime --force npu
Remove-Item Env:VOXSUB_LLAMA_TARGET
强制模式只有在应用实际选择 openvino/NPU、健康检查和真实翻译都通过时才返回成功；运行时缺失、设备/驱动不可用或推理失败都会明确失败，绝不会把 GPU/CPU 回落伪报为 NPU。普通启动不设置该变量，现有自动路由和回退逻辑不变。
要求：Windows 10/11。源码运行不会把模型或配置写进 Git 工作树；Python、uv 和 Git 缺失时，一键启动脚本会在用户目录自动准备便携版本。
开发者手动准备（可选）：
git clone https://github.com/tuotuonuts/VoxSub.git
cd VoxSub
uv venv --python 3.11
uv pip sync --python .venv\Scripts\python.exe requirements.lock
.\.venv\Scripts\python.exe -m pytest tests/ -q
日常更新和源码启动：
git pull --ff-only
.\.venv\Scripts\python.exe -m pytest tests/ -q
.\.venv\Scripts\python.exe run_app.py
上述默认测试不会访问真实麦克风、回环或扬声器，因此不会播放测试声音或占用声卡。真实设备验收保留为手动步骤，仅在排查音频设备、驱动或按应用音频采集问题时执行：
# 真实麦克风/回环/扬声器测试；其中按应用音频测试仍需显式确认播放短音
.\.venv\Scripts\python.exe -m pytest tests/ -q -o "addopts=" -m hardware_audio
# 额外验证按应用音频捕获，会播放两段低音量短测试音
$env:VOXSUB_TEST_PROCESS_AUDIO = "1"
.\.venv\Scripts\python.exe -m pytest tests/test_process_audio.py -q -o "addopts=" -m hardware_audio
Remove-Item Env:VOXSUB_TEST_PROCESS_AUDIO
给朋友使用时，先获得一个带 .git 目录的源码副本（首次可由熟悉 Git 的人完成克隆或使用 GitHub Desktop），然后双击项目根目录的 更新并启动测试版.bat。以后每次双击同一个文件即可自动更新源码、准备本机 Python/uv、创建独立 .venv、同步 requirements.lock 并启动 run_app.py。Python、uv 或 Git 不存在时，脚本会下载固定版本到 %LOCALAPPDATA%\VoxSub\bootstrap，无需管理员权限或手动配置。首次真正使用质量翻译时，应用还会先自动修复缺失的 CPU/Vulkan/OpenVINO 运行时并执行真实探针；修复失败才按 GPU → CPU 顺序降级，不会伪报 NPU。脚本会清理 PYTHONPATH / PYTHONHOME，测试环境自动使用 testing 标记。GitHub 下载的 ZIP 不含 .git，因此不能作为后续 git pull 更新的源码副本。
关闭主窗口右上角通常只是隐藏到系统托盘，并不会结束 VoxSub。真正退出源码测试版时，必须右键托盘图标并选择“退出应用”。启动脚本会在 git pull 前检查 VoxSub、源码 Python 和 llama-server 进程；发现仍在运行时只提示先执行“退出应用”，不会强制杀进程。应用返回后，脚本还会等待相关子进程结束，确认干净退出后才返回。
脚本优先使用已安装的 uv，否则自动下载并校验便携 uv；没有系统 Python 时由 uv 自动下载并管理 Python 3.11。若同步时发现 .venv 被占用或权限异常，脚本会先将它改名备份，再用当前电脑重建后重试。CPU/Vulkan/OpenVINO 运行时下载会校验远端固定的文件大小、ZIP 文件头和 SHA256，失败自动重试 3 次；如果代理或网关返回 HTML、下载截断或缓存损坏，窗口和 %LOCALAPPDATA%\VoxSub\diagnostics\source-run\ 日志会记录实际大小、摘要前缀和文件头，便于定位网络问题。基础功能会在运行时网络失败时继续启动，网络恢复后再次双击即可重试。脚本不会复制其他电脑的 .venv，也不会删除模型、配置或用户数据。
启动前脚本还会检查 Git 跟踪的源码是否有未提交修改。发现时会列出文件并停止更新，防止 git pull 覆盖本地代码；模型、配置、日志和 .venv 不会触发该检查。需要保留本地代码时，请先自行提交到分支；只想临时保留时，可在项目目录执行：
git stash push -u -m "before VoxSub source update"
git pull --ff-only
之后可用 git stash list 查看暂存内容；确认需要恢复时再执行 git stash pop。若上游也修改了相同文件，恢复时可能需要手动处理 Git 合并冲突。
脚本每次自动设置 VOXSUB_ENVIRONMENT=testing。如果希望朋友的诊断报告进入你的 Sentry，可由你提前把 DSN 放到朋友电脑的 %LOCALAPPDATA%\VoxSub\sentry_dsn.txt（一行纯文本）；脚本会自动读取，朋友无需手动配置。没有该文件时仅写本地日志，不会联网。
run_app.py 是源码和打包版共用的入口。git pull 只更新 Git 跟踪的源码；配置保存在 %LOCALAPPDATA%\VoxSub\config.json，模型和缓存由 model_storage.py 放在用户模型根目录，不会被拉取、覆盖或删除。只有依赖发生变化时才需要重新同步：
uv pip sync --python .venv\Scripts\python.exe requirements.lock
更新直接依赖后，在已验证的 Windows Python 3.11 环境重建锁文件：
uv pip compile requirements.txt --python .venv\Scripts\python.exe --python-platform windows --generate-hashes -o requirements.lock
不设置 DSN 时不会联网，原有本地日志和诊断页照常工作。需要启用时，在启动进程的 PowerShell 会话中设置：
$env:VOXSUB_SENTRY_DSN = "https://<public-key>@<host>/<project-id>"
$env:VOXSUB_ENVIRONMENT = "development" # development | testing | production
$env:VOXSUB_BUILD = "source" # 可选，标识本次源码/构建
.\.venv\Scripts\python.exe run_app.py
也可以把 sentry_dsn、sentry_environment 和 sentry_build 写入 %LOCALAPPDATA%\VoxSub\config.json；环境变量优先于本地配置。DSN 不要提交到 Git 或写入源码。
Sentry 事件只包含软件版本、构建号、环境、操作系统、CPU、GPU/NPU、内存、驱动和推理后端，以及经过过滤的异常类型；不会上传 API Key、音频、字幕正文、识别文本、用户文件内容或私人路径。网络不可用时事件会丢弃，不会影响应用。
本地日志位于 %LOCALAPPDATA%\VoxSub\logs\voxsub.log，也可在应用“诊断 → 日志”页查看和导出。需要更详细现场时，在“诊断 → 日志”开启“诊断调试”；会话默认 20 分钟后自动结束，也可手动关闭。手动上传会话期间只提交该会话标记的日志，并附带行数与隐私过滤统计。“诊断 → 自检”页的“导出报告 (txt)”会生成当前最新自检结果；修复按钮只处理该结果中明确声明的目标。
配置 DSN 后，诊断页的“自检”会显示“发送到 Sentry”，用于上传当前最新自检报告和本地日志快照（隐私过滤后），不会重新执行自检；“日志”页也提供独立的“上传日志到 Sentry”，不需要先运行自检。为避免大日志把现场问题挤出附件，超过上传上限时会保留最新的完整日志行。上传完成后，日志页会显示来源和上传时间范围、原始/上传/省略行数、脱敏统计；同一份安全元数据也会写入 Sentry 附件头部。未配置或网络失败时不会影响应用。
“诊断 → 日志 → 清除本机日志”需要确认后才执行：它会清空 %LOCALAPPDATA%\VoxSub\logs 中的当前/轮转日志，以及 %LOCALAPPDATA%\VoxSub\diagnostics 中的启动日志；不会删除模型、配置、用户数据、Sentry 配置或已手动导出的报告。正在运行的 VoxSub 会继续写入一份新的空日志。
也可以直接在“设置 → 关于 → 诊断上报”中填写 DSN、环境和构建标识并保存；保存后当前进程立即重载配置，无需重启。
DSN 只负责上报，不能读取 Sentry Issue。需要长期排查时，维护者可创建只读 Sentry API Token，并仅勾选 org:read、project:read、event:read。不要使用写入或管理权限，也不要把 Token 发到聊天、写入源码、config.json 或 DSN 文件。
首次在本机执行下列命令；脚本会在隐藏输入提示中请求 Token，随后自动从可访问组织中定位 voxsub 项目并写入本机配置：
powershell -ExecutionPolicy Bypass -File .\scripts\initialize_sentry_diagnostics.ps1
令牌保存在 %LOCALAPPDATA%\VoxSub\sentry_auth_token.txt，项目定位配置保存在 %LOCALAPPDATA%\VoxSub\sentry_api.json，都不进入 Git，也不被 VoxSub 应用读取。默认使用德国数据区 https://de.sentry.io；若项目位于其他数据区，可传入 -SentryBase https://sentry.io。
配置完成后，可只读查看未解决 Issue：
powershell -ExecutionPolicy Bypass -File .\scripts\get_sentry_issues.ps1
令牌应设置较短有效期。设备不再用于维护或 Token 泄露时，立即在 Sentry 的 Auth Tokens 页面撤销。
构建安装包：
powershell -ExecutionPolicy Bypass -File scripts\build.ps1
安装包默认输出到项目上一级的 Release 目录；本项目开发工作区对应 D:\OneDrive\app_dve\Release。新安装默认把模型放在安装目录下的 Models 文件夹，并按用途分到 stt、translate、vad、tts、ocr；升级用户保留现有模型根目录，直到主动在设置中更改。模型属于用户数据，不会被安装包重复分发或在更新时删除。当前公开的 0.7.2-beta 安装包为 214,817,504 字节，SHA256 313714AE3C9557B88EDBCEBBFCB768A15BBDD65915A5266E0B3EB1D82CAF2211。本地最新候选 0.9.0-beta 为 277,309,314 字节（264.46 MiB），SHA256 59E68EAF93AF2C6D9C1D9D57BBF5BEEE18C891BA516A94E857635A22AAC54C42；本次构建未签名，用户验证前不会创建 GitHub Release。
voxsub/ Python 核心（识别 / 翻译 / TTS / OCR / 硬件探测 / 流水线）
frontend/ Electron 前端（界面、IPC 适配层、开发工具）
tests/ pytest 测试
scripts/ 构建/工具脚本
models/ 运行时模型缓存（gitignore）
界面是 Electron + TypeScript，Python 核心通过 stdin/stdout 上的 JSON Lines
协议被驱动（frontend/backend/ipc_server.py）。核心层不感知界面存在 ——
tests/test_architecture.py 强制这条边界。
开发启动（免打包）：
cd frontend
npm run launch # 增量构建 + 启动
npm run launch:silent # 静默模式：窗口不显示，供自动化验证
Qt 版（PySide6）前端已冻结在 qt-legacy 分支，保留完整源码与提交历史。
在 设置 → 快捷键 中自定义，默认全部留空、不占用任何组合键。可以录入组合键或手动输入，例如 Ctrl+Alt+T；点击“保存快捷键”后生效，清空并保存即可停用。
支持：显示/隐藏主窗、开始/结束当前会话、暂停/继续、结束会话、切换“同时录音”、显示/隐藏字幕浮窗、切换浮窗鼠标穿透。应用保持运行时，最小化或隐藏到托盘不影响已注册快捷键；完全退出后快捷键停用。会话动作使用当前模式、音源和模型，不自动选择文件或操作 OCR；录音切换遵循当前会话能力限制，不自行开始采集。
自动检查应用内重复、已知系统保留组合和系统注册失败。保存冲突或写入失败时保留旧设置与旧注册；其他软件只在其自身窗口内使用的快捷键无法可靠检测，应避免常用编辑组合键。录入期间暂时停用全局快捷键，取消、失焦、最小化或关页后恢复；恢复被系统拒绝时明确标为未生效。重启后重新注册并报告占用冲突，不静默换键。
音视频文件模式现在可在 识别＋翻译（双模型） 与 语音直接翻译（单模型） 之间选择；默认仍为双模型。主页文件区和设置页复用同一个选择控件。
.voxsub.srt，已有同名文件时创建新文件；手动导出支持 SRT、VTT、TXT，保留媒体时间戳。源码版额外运行 powershell -NoProfile -ExecutionPolicy Bypass -File scripts/setup-speech-runtime.ps1 安装隔离的 CPU 环境 .venv-speech；加 -Device cuda 安装官方 PyTorch CUDA 12.8 环境 .venv-speech-cuda，需要兼容的 NVIDIA 驱动与支持 BF16 的显卡。可用 -China 选择依赖索引镜像。组件不会混入轻量后端环境，也不会在用户点击“开始”时偷偷安装。完整发布流程会单独打包 VoxSubSpeechWorker，缺少组件时阻止发布。
测试边界与剩余限制见 docs/SINGLE_MODEL_SPEECH_ACCEPTANCE.md。这不是安装包已发布或现有用户实例已更新的声明。
模型广场新增 SeamlessStreaming，提供固定权重的全球／大陆镜像、暂停续传及官方运行说明。它的官方依赖需要 Linux／WSL，本应用只提供下载入口，不将它列为 Windows 内可直接使用的模型；不自动安装或启动 WSL。许可为 CC-BY-NC-4.0，仅非商业用途。
悬浮窗独立于主窗口缩放，按渲染后的字幕卡片边界裁剪；显示、缩放、尺寸变化会更新并读回原生区域和材质状态。失败退回普通半透明背景，必要时只重建该悬浮窗，保持隐藏／穿透状态。诊断分别记录裁剪、材质与桌面效果，隐藏窗口检查不会被标作可见桌面验收。最新范围见 docs/GPU_OVERLAY_DOWNLOAD_ACCEPTANCE.md。