LocalTranslate 是一个面向 macOS 的本机轻量工具箱，把划词翻译、截图 OCR 翻译、 本机助手、系统音频实时字幕和 AI 用量看板放在同一个菜单栏 App 中。翻译与语音 内容默认只发送到本机 Ollama；本机助手默认经 agy 发往 Antigravity。
当前已发布版本：v1.8.0
⌥⇧T：读取当前选中文本并打开完整翻译面板；支持编辑、翻译风格、复制和置顶。⌥⇧D：在鼠标附近显示轻量翻译气泡。⌥⇧S：调用 macOS 交互式框选，使用 Apple Vision 在本机 OCR，再交给 Ollama 翻译。- 源语言由原文自动识别，无需选择；目标语言可在设置中选择（简体中文、繁體中文、 英、日、韩、法、德、西、俄）。原文本身已是目标语言时，中文与英文互译， 其余语言译为简体中文。
- 原文与译文各有一个朗读按钮，使用系统语音在本机合成，不联网。译文的语音语言即目标 语言；原文按字形与识别结果判定，单个拉丁词识别不可靠时按英文朗读。
- 默认 Ollama 地址是
http://127.0.0.1:11434，默认模型是qwen3.5:4b；地址、模型、keep-alive 和翻译风格可在设置中修改。
⌥⇧E：打开输入框，并在后台拉起agy（等到init，不发提问）。 有选中文本就预填进去（报错栈、日志、代码、术语），没有选中就空着； 都可以改，⌘↩ 才提交。可钉住，钉住后点击外部不关闭。不额外要求辅助功能权限。 菜单栏也可「启动助手」。- 输出三类之一：可直接执行的命令、报错栈的直接原因与该看哪一行、 选中内容的三句解释。命令只复制到剪贴板，不会自动执行或粘贴进终端。
- 破坏性由代码判定，不采信模型自述：
rm -rf、git reset --hard、push --force、sed -i、DROP TABLE等命中即在命令正下方标红且不可折叠； 不可撤销的额外标注"这一步没有本地退路"。 - 需要外部核对时，可预览并复制有长度上限、带注入防护的交接内容，再打开 ChatGPT 或 Antigravity；网页不会自动粘贴或发送。
- 默认经本机
agy把问题发给 Antigravity（--model gemini-3.8-flash --effort medium）。agy 不可用、 超时或未登录时降到本机 Ollama，并在面板上写明来源。设置里有「只用本地」总开关。
⌥⇧C：打开、暂停或恢复实时字幕。- 源语言、字幕呈现与字号可在字幕条工具栏或设置的「实时字幕」页调整。
- 使用 Core Audio private process tap 捕获系统输出，不安装虚拟声卡，也不创建屏幕共享流。
- 使用 Apple
SpeechAnalyzer/SpeechTranscriber做端侧增量 ASR，再使用本地 Ollama 翻译。 - 支持英语、日语、韩语、普通话、粤语、法语、德语、西班牙语和俄语；可切换双语、仅译文或仅原文。
- 字幕条是固定的三行：上一句译文降权在最上，当前译文居中高亮，当前原文在最下。 三行的位置和高度全程不变，不会因为有没有译文而跳动。
- 当前译文以续写方式增长——已经显示出来的字不会被改写。整句定稿是唯一一次可以 推翻先前措辞的机会，它定稿后进入上一行，主行随之翻到下一句。
- 已确认的历史字幕不因后续识别 revision 被改写。
实时链路不是“每次 partial 全文重翻”，而是两个并行状态：
system audio -> ASR -> committed transcript + volatile partial
├─ semantic window planner (翻译单元) -> 整句定稿
└─ caption pager (显示单元) -> preview
-> committed translation + preview translation
-> immutable history + highlighted current caption
翻译单元和显示单元是分开的：planner 按标点、时长和词数切出送去翻译的窗口， 主行显示到哪由字幕自己攒页决定。两者共用边界时，planner 每切走一段主行就会 凭空缩水。
audio range 用于消除 rolling overlap；sessionID / segmentID / revision 用于拦截旧 Ollama 响应。preview 请求把已显示的译文作为末尾 assistant 消息送出，模型只能往后写，因此屏幕上的字不会被改写。
调整字幕节奏时可以在设置的「实时字幕」页打开「节奏诊断日志」，会话总表写到
~/.localtranslate/live-subtitles/，记录每句在屏幕上变了几次、被擦掉重写多少字
以及字幕落后语音多少秒。默认关闭——不写盘是实时字幕的资源基线。
- 汇总本机 Codex、Claude、Antigravity、Grok 与百炼 Token Plan 数据源。
- 账号来源可配置：Codex 账号可增删改（每个对应一个
CODEX_HOME目录）， 其余固定路径来源可单独启停。入口在用量页右上角「账号来源」。 - 模型用量按
modelID全局归一，账号卡片聚焦配额窗口和时间汇总。 - Antigravity 运行时优先从其本机 language server 读取 Gemini 与 Claude/GPT 的 5 小时、每周额度；本机会话库提供可验证时间时统计模型 Token，尚无事件时间时 只保留零 Token 模型证据并标明等待落盘。
- 使用内存与磁盘增量缓存；单个 Provider 失败时保留其他可用数据。
- 首次索引大量历史日志时分片进行，卡片上显示「已索引 x/y 个文件」并标明当前 数字尚不完整，补齐完成后自动消失。
- macOS 26 或更高版本；
- Xcode 26.x（从源码构建时）；
- 已安装并运行 Ollama；
- 至少一个本地翻译模型。
首次使用可以准备默认模型：
ollama pull qwen3.5:4b
ollama serve如果 Ollama 已由桌面 App 启动，不需要重复执行 ollama serve。
从 Releases 下载 DMG 或 ZIP。当前自动发布产物未签名、未公证，首次打开可能被 Gatekeeper 阻止；可在 Finder 中按住 Control 点击 App，选择“打开”，并确认来源。
也可以在 Xcode 26 中打开 LocalTranslate.xcodeproj，选择 LocalTranslate scheme 后运行。
| 权限 | 触发功能 | 用途 |
|---|---|---|
| 辅助功能 | 划词翻译 | 读取当前选中文本；必要时模拟复制并恢复剪贴板 |
| 屏幕与系统音频录制 | 截图 OCR | 仅在用户按 ⌥⇧S 框选屏幕时请求 |
| 系统音频录制 | 实时字幕 | 通过 Core Audio process tap 读取系统输出 |
| 语音识别 | 实时字幕 | 将系统音频转换为增量源文本 |
实时字幕不使用麦克风，也不使用 ScreenCaptureKit display stream。截图 OCR 的屏幕权限与实时字幕链路相互独立。
| 快捷键 | 功能 |
|---|---|
⌥⇧T |
划词翻译 / 完整面板 |
⌥⇧D |
划词翻译气泡 |
⌥⇧E |
本机助手：有选区预填进输入框，⌘↩ 提交 |
⌥⇧S |
截图 OCR 翻译 |
⌥⇧C |
实时字幕 |
⌘↩ |
在翻译面板中立即翻译 |
Esc |
隐藏浮窗或取消截图 |
⌘, |
打开设置 |
快捷键当前不可自定义。若某个组合已被其他 App 占用，设置页的「全局快捷键」会标记为「已被占用」。
- 文本、截图 OCR 结果和语音转录默认只发送到
127.0.0.1的 Ollama；如果修改 Ollama Base URL，数据边界随该配置变化。 - 翻译、划词、实时字幕只发送到
127.0.0.1的 Ollama。本机助手默认经agy发往 Antigravity；打开设置里的「只用本地」后助手也只走 Ollama。 点击交接按钮时，才把输入、上下文和答案复制到剪贴板并打开目标网站。 网页不会自动粘贴或提交。LocalTranslate 自身不保存提问；走 agy 时 CLI 会在~/.gemini/antigravity-cli/留下会话记录，会话结束时按 ID 删除本 App 创建的那些。 CLI 全局日志（log/cli-*.log）不动。菜单栏显示未运行 / 启动中 / 运行中， 可启动或停止助手。 - 截图在临时目录中生成，读取后删除。
- 实时字幕暂停或关闭时会结束识别输入，并销毁 IOProc、aggregate device 和 process tap，同时取消翻译任务并请求卸载模型。
- AI 用量活动读取本机客户端数据；刷新额度时，Codex 可能通过本机 app-server
使用现有登录态，Grok 会访问其官方额度服务。Antigravity 额度请求只连接
127.0.0.1上已运行的 language server。LocalTranslate 不代用户登录账号。
- v1.2.0 已优先解决 partial/final 混合、源转录重复、stale response 覆盖和字幕全文闪烁。
- v1.5.0 修复 AGY 用量的事件时间来源：Token 此前因时间戳解析落空而无法归入当日，
现按会话库
steps表的事件时间归日。 - 快速访谈与长句场景仍可能感知约 2 秒端到端时差，后续优化记录在 Issue #3。优化不会以恢复全文跳变或修改 committed 字幕为代价。
- Release 产物尚未做 Developer ID 签名与 Apple notarization。
状态测试（实时字幕增量契约、AI 用量与助手安全规则）：
./Scripts/run-state-tests.shRelease 构建：
xcodebuild -project LocalTranslate.xcodeproj \
-scheme LocalTranslate \
-configuration Release \
-destination 'generic/platform=macOS' \
build \
CODE_SIGN_IDENTITY="" \
CODE_SIGNING_REQUIRED=NO \
CODE_SIGNING_ALLOWED=NOGitHub Actions 在 macos-15 runner 上显式选择 Xcode 26.x，先跑状态测试再执行 Release 构建。推送到 main 会执行 CI；推送 v* 标签会生成 DMG 和 ZIP，并创建 GitHub Release。
架构不变量、实时字幕增量契约、权限检查和发布流程见 AGENTS.md。