[English](DECISIONS.en.md)

# dsh-omi-voice 决策记录（DECISIONS）

> 记录已定型的决策与理由（对应 Omi 的 `DESIGN_DECISIONS.md`）。新决策按倒序追加。

## 2026-08-18（v0.1.0 → v0.1.2 开发期）

| # | 决策 | 理由 |
|---|---|---|
| D1 | **引擎播放**（插件只发指令，音频由 Omi 引擎本地播放） | 复用现有 PCM 播放器/变速/暂停/缓存，零音频格式工作；浏览器播放留 v2 |
| D2 | **移除自动朗读**，仅点读 | 用户产品决策反转：默认关仍不够，直接删除（v0.1.1），避免"文档承诺的功能不存在" |
| D3 | 只读最终回答（`kind==='text'` 块过滤） | 工具日志/思考被误读是真实 bug；引擎清洗救不了，必须在插件取块层过滤 |
| D4 | 代码围栏/表格/盒绘/ASCII 图形**请求前过滤** | 这类内容无法朗读且烧字数；纯此类内容返回 `invalid_text` 不发请求 |
| D5 | 进程内 **LRU 缓存 3 条 / ≤5MB** | 复读近几条不重复计费；纯内存零硬盘、退出即清（用户"少占缓存"原则） |
| D6 | Keychain **关闭 data protection** | ad-hoc 签名无 keychain-access-groups entitlement，开了会导致保存 -34018 |
| D7 | 端口固定 **8765** + CORS 放行任意 loopback | 避免换端口复现难排查的 "Load failed"；威胁模型不变（仍只绑 127.0.0.1） |
| D8 | 同文本 3 秒去重 + 任意朗读 300ms 节流 | 防连点/重复请求烧豆包字数 |
| D9 | 引擎**并入同一仓库** `engine/` | 用户要求：一个仓库搞定插件 + 引擎，安装命令 `&path:/` 保持不变 |
| D10 | 插件/引擎版本**统一 0.1.2** | 消除两套版本体系的困惑 |
| D11 | 标语「**沉浸式听朗读 · 豆包音质**」 | 从用户场景出发（Vibe Coding 听读、通勤听复盘），替代空泛的"有温度的对话内朗读" |
| D12 | 无鉴权 token（v1） | 仅本机回环、Key 不出机、文本不落盘；影响面仅"本机扬声器出声"，可接受 |
| D13 | UI 本地化：**自动跟随系统语言**（NSLocalizedString + `en.lproj` + **`zh-Hans.lproj`**，中文串为 key） | 国际分发标准做法；**必须 en + zh-Hans 两个 .lproj 都加**（只加 en 会被判为只会英文、恒显英文，实测 Bug）；英文系统→英文、中文系统→中文，零手动切换 |

## 待定（未执行，留待后续决策）

- 鉴权 token（若未来加"读本地文件"类能力则必须）
- 语速 UI、跳过段落、端口配置 UI（v1.1）
- 引擎 Omi DSH 版是否取消 ⌥⇧Q 热键（与 v0.1.3 剪贴板版共存时易误用）