咸蛋翻译官维护手册（Xiandan Translator Maintenance）
> 本技能为可分发版：assets/app/ 内含完整应用源码副本，可直接发给他人部署。所有路径用 {{占位符}} 表示，请按部署环境替换。本工具翻译为完全离线本地推理，默认不含任何个人密钥。
Overview
咸蛋翻译官是一款完全离线的字幕/视频翻译工具（推理阶段不依赖外网）：
- 音频/视频 → faster-whisper 语音识别 → 原文 srt
- 字幕/原文 → 本地大模型（llama.cpp 或 Ollama）→ 简体中文 srt
两套前端共用同一套识别/翻译引擎逻辑（engine.py）：
- 桌面版：{{PROJECT_ROOT}}/咸蛋翻译官.py（CustomTkinter 6.0.0）+ PyInstaller onefile 的 咸蛋翻译官.exe
- 网页版：{{PROJECT_ROOT}}/web批量翻译版/（FastAPI + 原生 HTML/JS，localhost 私用，非对外发布）
When to use
- 修改 / 重建 / 排错咸蛋翻译官（桌面或网页任一端）
- 报错涉及 ffmpeg、CustomTkinter、whisper、llama.cpp、Ollama、PyInstaller、多线程 / 队列
- 新增或切换翻译模型、调整翻译提示词、调并发（
WEB_WORKERS）/ 重试（MAX_RETRIES） - 给识别或翻译流程加功能
自助部署（给他人）
把本技能 assets/app/ 整目录复制出来作为 {{PROJECT_ROOT}}，再按 assets/app/README_部署.md 放置外部组件（ffmpeg / llama.cpp 或 Ollama / whisper 模型 / 翻译 GGUF）并安装依赖即可。可运行 scripts/init_env.py 一键校验组件、生成 requirements.txt 与 .env.example。
Key paths（均相对于 {{PROJECT_ROOT}}）
| 作用 | 路径 |
|---|---|
| 桌面源码 | {{PROJECT_ROOT}}/咸蛋翻译官.py |
| 桌面 exe | {{PROJECT_ROOT}}/咸蛋翻译官.exe（必须放主目录运行） |
| 网页目录 | {{PROJECT_ROOT}}/web批量翻译版/ |
| 引擎（无 tkinter） | web批量翻译版/engine.py（SubtitleEngine/TranslateEngine + 纯函数） |
| 网页服务 | web批量翻译版/server.py + web批量翻译版/static/index.html |
| 启动器 | web批量翻译版/start_web.bat |
| 构建 venv | 你自己创建的 Python venv（如 {{PROJECT_ROOT}}/venv），含 faster-whisper / pyinstaller / customtkinter 等 |
| 模型 / 组件 | ffmpeg_bin/ llama_bin/ whisper_models/ models/（外置，不打包进 exe，靠 BASE_DIR 同目录定位） |
Architecture
engine.py：抽离后的纯逻辑层，无 tkinter 依赖，被桌面与网页共用。核心：SubtitleEngine（识别）、TranslateEngine（翻译）、_to_wav()（音频转码）、parse_srt/make_srt（字幕解析 / 合并，双语字幕用）。server.py：FastAPI。ThreadPoolExecutor(WEB_WORKERS)接任务 + 全局ENGINE_LOCK串行化底层 whisper/llama 推理（二者为单例非线程安全）。进度回调progress(stage, pct, msg)：stage ∈ {asr, translate} → 分别写asr_progress(0~50%) /translate_progress(50~100%)。失败自动重试：MAX_RETRIES+NON_RETRYABLE确定性失败白名单 +status="retrying"。index.html：深色原生单页，每文件一张卡，双进度条（识别 / 翻译），1s 轮询/api/jobs/{id}。
Common workflows
重建桌面 exe：在 {{PROJECT_ROOT}} 执行（用你的构建 venv 的 pyinstaller）
pyinstaller 咸蛋翻译官.spec --noconfirm --distpath {{PROJECT_ROOT}} --workpath {{PROJECT_ROOT}}/_build
（细节见 references/build.md）
启动网页版：双击 web批量翻译版/start_web.bat（细节见 references/build.md）。
排错崩溃：桌面 exe 的 console=False 使 stdout/stderr 为 None，异常被 sys.excepthook / threading.excepthook 兜底写入 _last_error.log。先看该日志定位栈（典型：_run_asr → _to_wav）。
改翻译质量：编辑 engine.py / 咸蛋翻译官.py 中翻译提示词，硬约束「只输出翻译结果，不要加引号」，否则 llama 会回带前缀污染字幕。
Critical pitfalls（必读）
完整清单与代码模式见 references/pitfalls.md。高频雷区：
1. ffmpeg 同路径原地覆盖 → exit −22 / 4294967274。输入 == 输出时跳过转码直接交 whisper。
2. CTk 6.0 迁移坑（10 条：禁 .config()、.set() 程序化切页不触发回调、字号用像素负值 × ui_scale 等）。
3. PyInstaller console=False → stdout/stderr None，必须重定向 + 接 excepthook。
4. tkinter 非线程安全 → 子线程走 queue.Queue + 主线程 after 轮询。
5. 本地模型单例 → 用 ENGINE_LOCK 串行化，并发只影响排队展示。
6. whisper 断点续传 → clip_timestamps="起点,终点"，segment 时间为绝对时间可直接拼接。
Local environment（必读）
作者机器硬件 / 工具链 / 模型路径仅作示例参考（你的环境可能不同），见 references/env.md。
Resources
references/pitfalls.md— 已知坑位与修复代码模式（排错第一手资料）references/build.md— PyInstaller spec 要点、网页版启动与环境变量references/env.md— 环境示例、密钥占位与组件获取方式assets/app/— 完整应用源码副本（可直接部署）assets/app/README_部署.md— 分步部署指南scripts/init_env.py— 组件校验 + requirements 生成
