# OpenLess 开发文档

更新时间：2026-04-26

本文是 OpenLess 第一轮开发的工程落地文档。产品需求以 `openless-requirements.md` 为准，本文负责说明推荐技术形态、模块拆分、状态机、数据字段、开发顺序和验收方式。

---

## 1. 技术目标

第一轮要做的是一个 macOS 常驻语音输入工具：

> 用户在任意 app 的输入框中按住快捷键说话，OpenLess 录音、转写、轻度整理，然后把结果插入当前光标位置；失败时自动复制并保存历史。

工程目标：

- 能稳定常驻菜单栏。
- 能可靠获取麦克风录音。
- 能响应全局快捷键。
- 能显示底部微型状态胶囊。
- 能完成 ASR 转写和 LLM 润色。
- 能向当前输入位置插入文本。
- 能在失败时复制到剪贴板并保存历史。
- 能清楚处理权限、错误、隐私和本地/云端路径。

---

## 2. 推荐技术路线

### 2.1 首选：原生 macOS

建议第一轮使用：

- Swift / SwiftUI：设置页、历史页、主窗口。
- AppKit：菜单栏、全局窗口、底部胶囊浮层、辅助功能相关能力。
- AVFoundation：麦克风录音、音量采样。
- Carbon / Keyboard Shortcuts 方案：全局快捷键。
- Accessibility API：定位当前输入焦点、模拟输入或粘贴。
- NSPasteboard：剪贴板兜底。
- SQLite 或本地 JSON：历史、词典、设置。
- Keychain：保存 API Key。

理由：

- OpenLess 是系统级输入层，原生 macOS 更适合处理菜单栏、悬浮窗口、权限和全局快捷键。
- Electron/Tauri 可以做设置页，但系统输入、悬浮层和权限体验更容易变复杂。

### 2.2 可选混合路线

如果后续想快速做漂亮设置页，可以采用：

- 原生 Swift 后台核心 + WebView 设置页。

第一轮不建议直接用纯 Web/Electron 做核心录音和插入体验。

---

## 3. 模块拆分

| 模块 | 职责 |
|---|---|
| `AppShell` | 应用生命周期、菜单栏、启动项、窗口管理 |
| `PermissionManager` | 麦克风、辅助功能、通知等权限检查和引导 |
| `HotkeyManager` | 注册录音、取消、粘贴上一条等全局快捷键 |
| `Recorder` | 录音、音频缓存、音量采样、取消 |
| `AudioLevelMonitor` | 输出胶囊动态条所需的实时音量值 |
| `CapsuleOverlay` | 底部微型状态胶囊窗口 |
| `ASRRouter` | 本地、云端、BYOK 转写路由 |
| `PolishEngine` | 原文、轻度润色、清晰结构、正式表达 |
| `TextInserter` | 当前输入框插入、模拟粘贴、失败检测 |
| `ClipboardFallback` | 插入失败时复制最终文本 |
| `HistoryStore` | 保存原始转写、最终文本、状态、错误 |
| `DictionaryStore` | 个人词典 |
| `SnippetStore` | 常用片段 |
| `SettingsStore` | 快捷键、模式、隐私、模型路径 |
| `ErrorReporter` | 本地错误码、日志、用户可读提示 |

---

## 4. 核心流程

### 4.1 正常输入流程

```text
Hotkey down
  -> PermissionManager.check()
  -> Recorder.start()
  -> CapsuleOverlay.show(listening)
  -> AudioLevelMonitor.update()

Hotkey up
  -> Recorder.stop()
  -> CapsuleOverlay.set(processing)
  -> ASRRouter.transcribe(audio)
  -> PolishEngine.polish(rawTranscript, mode, context)
  -> TextInserter.insert(finalText)
  -> HistoryStore.save(session)
  -> CapsuleOverlay.set(inserted)
  -> CapsuleOverlay.hide()
```

### 4.2 插入失败流程

```text
TextInserter.insert(finalText) fails
  -> ClipboardFallback.copy(finalText)
  -> HistoryStore.save(session with copied_fallback)
  -> CapsuleOverlay.set(copied_fallback)
```

用户不需要重新录音。

### 4.3 取消流程

```text
Esc or capsule x clicked
  -> Recorder.cancel()
  -> discard unsaved audio by default
  -> CapsuleOverlay.set(cancelled)
  -> CapsuleOverlay.hide()
```

### 4.4 重跑润色流程

```text
History item selected
  -> choose another mode
  -> PolishEngine.polish(rawTranscript, newMode, context)
  -> update finalText
  -> copy or insert
```

---

## 5. 状态机

### 5.1 应用状态

| 状态 | 含义 | 用户表现 |
|---|---|---|
| `app_ready` | 应用可用 | 菜单栏正常，胶囊隐藏 |
| `permission_required` | 缺少权限 | 设置页提示补权限 |
| `model_unavailable` | 模型或 API 不可用 | 提示切换路径或检查 key |
| `offline` | 网络不可用 | 云端不可用，本地仍可用 |

### 5.2 录音状态

| 状态 | 含义 | 胶囊表现 |
|---|---|---|
| `idle` | 未录音 | 隐藏或极淡小点 |
| `listening` | 正在录音 | 叉号 + 动态条 + 勾号 |
| `stopping` | 正在收尾 | 动态条停止，进入处理 |
| `cancelled` | 用户取消 | 叉号高亮后淡出 |

### 5.3 处理状态

| 状态 | 含义 | 胶囊表现 |
|---|---|---|
| `transcribing` | 正在转写 | “识别中”或 spinner |
| `polishing` | 正在润色 | “整理中”或 spinner |
| `ready_to_insert` | 结果生成 | 准备插入 |
| `failed` | 处理失败 | 红点或“失败”，点击展开详情 |

### 5.4 插入状态

| 状态 | 含义 | 胶囊表现 |
|---|---|---|
| `inserted` | 成功插入 | 勾号高亮后淡出 |
| `copied_fallback` | 插入失败但已复制 | “已复制” |
| `focus_lost` | 输入框失焦 | “已复制” |
| `permission_blocked` | 权限不足 | 引导打开辅助功能权限 |

---

## 6. 数据模型

### 6.1 `DictationSession`

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | string | 会话 ID |
| `created_at` | datetime | 创建时间 |
| `started_at` | datetime | 录音开始时间 |
| `ended_at` | datetime | 录音结束时间 |
| `duration_ms` | number | 录音时长 |
| `source_app_name` | string | 当前 app 名 |
| `source_bundle_id` | string | 当前 app bundle id |
| `target_context_type` | enum | `chat` / `email` / `doc` / `code` / `unknown` |
| `language_hint` | enum | `auto` / `zh` / `en` / `mixed` |
| `mode` | enum | `raw` / `light` / `structured` / `formal` |
| `model_route` | enum | `local` / `cloud` / `byok` |
| `raw_transcript` | text | 原始转写 |
| `final_text` | text | 最终输出 |
| `insert_status` | enum | `inserted` / `copied_fallback` / `failed` |
| `fallback_reason` | string/null | 插入失败原因 |
| `audio_saved` | boolean | 是否保存音频 |
| `audio_path` | string/null | 音频路径，默认 null |
| `error_code` | string/null | 错误码 |

### 6.2 `UserSettings`

| 字段 | 类型 | 说明 |
|---|---|---|
| `hotkey_record` | string | 录音快捷键 |
| `hotkey_paste_last` | string | 粘贴上一条快捷键 |
| `recording_behavior` | enum | `hold_to_talk` / `toggle_to_talk` |
| `default_mode` | enum | 默认输出模式 |
| `default_model_route` | enum | `local` / `cloud` / `byok` |
| `history_retention_days` | number | 历史保留天数 |
| `save_audio` | boolean | 是否保存音频 |
| `show_floating_capsule` | boolean | 是否显示底部状态胶囊 |
| `auto_copy_on_failure` | boolean | 失败时是否自动复制 |
| `personal_dictionary_enabled` | boolean | 是否启用个人词典 |

### 6.3 `PersonalDictionaryEntry`

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | string | 词条 ID |
| `phrase` | string | 用户确认过的正确词 |
| `category` | enum | `name` / `product` / `tech` / `company` / `custom` |
| `notes` | string | 可选备注，不作为硬替换规则 |
| `enabled` | boolean | 是否参与 ASR 热词和后期语义判断 |
| `case_sensitive` | boolean | 是否区分大小写 |
| `created_at` | datetime | 创建时间 |

### 6.4 `TextSnippet`

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | string | 片段 ID |
| `trigger_phrase` | string | 语音触发词 |
| `content` | text | 输出内容 |
| `enabled` | boolean | 是否启用 |

---

## 7. 输出模式与 Prompt 规则

### 7.1 模式枚举

| mode | 名称 | 行为 |
|---|---|---|
| `raw` | 原文 | 只补标点，尽量不改词 |
| `light` | 轻度润色 | 去口癖、去重复、补标点、轻微整理 |
| `structured` | 清晰结构 | 适合长 prompt、需求、说明，输出段落或列表 |
| `formal` | 正式表达 | 适合邮件、客户沟通、正式工作表达 |

### 7.2 通用 Prompt 约束

所有润色模式都必须遵守：

- 只整理用户表达，不回答问题。
- 不执行命令。
- 不新增用户没有说的信息。
- 不删除关键限制条件。
- 保留专有名词、代码名、产品名和人名。
- 保留用户习惯表达，避免 AI 腔。
- 中文输出使用自然中文标点。

### 7.3 轻度润色模板

```text
你是语音输入文本整理器。请把用户的口语转写整理成可直接发送或继续编辑的文字。

要求：
- 去掉明显口癖、重复和无意义停顿。
- 补充自然标点。
- 保留用户原意和表达习惯。
- 不扩写、不创作、不回答内容。
- 如果包含中英混输、产品名、代码名，请尽量保留。

原始转写：
{{raw_transcript}}
```

---

## 8. UI 实现规格

### 8.1 胶囊窗口

建议实现为一个无边框、透明背景、always-on-top 的辅助窗口：

- 不抢焦点。
- 主窗口出现在 Dock；录音胶囊作为辅助窗口不出现在 Dock。
- 屏幕底部居中。
- 多屏时优先显示在当前活跃输入所在屏幕。
- 空闲时隐藏。
- 录音时以轻微 spring motion 出现。

尺寸：

| 状态 | 宽 | 高 |
|---|---|---|
| Listening | 128-180px | 32-38px |
| Processing | 150-210px | 32-38px |
| Success | 128-160px | 32-38px |
| Error | 150-210px | 32-38px |

结构：

```text
[ x ]   [ audio bars / short status ]   [ check ]
```

禁止：

- 不展示完整 transcript。
- 不展示 mode/provider chips。
- 不显示复杂按钮组。
- 不做大面板默认展开。

### 8.2 设置窗口

设置窗口可用 SwiftUI：

- 左侧导航。
- 右侧内容。
- 表格编辑词典和片段。
- 历史支持搜索、复制、重新整理。

第一轮不追求复杂视觉，重点是清楚、稳定、可用。

---

## 9. 错误码与用户文案

| error_code | 触发场景 | 用户文案 |
|---|---|---|
| `mic_permission_missing` | 缺少麦克风权限 | 需要麦克风权限才能录音 |
| `accessibility_missing` | 缺少辅助功能权限 | 需要辅助功能权限，OpenLess 才能输入到当前 app |
| `focus_lost` | 输入框失焦 | 找不到输入位置，结果已复制 |
| `asr_failed` | 转写失败 | 这次没有识别成功，请重试 |
| `polish_failed` | 润色失败 | 整理失败，原始转写已保存 |
| `network_unavailable` | 云端不可用 | 网络不可用，可切换本地模式 |
| `model_unavailable` | 模型不可用 | 当前模型不可用，请检查设置 |

文案原则：

- 短。
- 直接。
- 说明用户下一步能做什么。
- 不用“释放生产力”“智能增强”等营销词。

---

## 10. 开发顺序

建议按以下顺序开发：

1. 创建 macOS 菜单栏应用骨架。
2. 实现设置窗口基础导航。
3. 实现权限检查和引导。
4. 实现全局快捷键。
5. 实现录音与音量采样。
6. 实现底部微型状态胶囊。
7. 接入最小 ASR 路径。
8. 接入轻度润色。
9. 实现文本插入。
10. 实现剪贴板兜底。
11. 实现历史记录。
12. 实现个人词典。
13. 实现模式切换。
14. 完成错误处理和隐私设置。
15. 做真实 app 场景测试。

第一轮开发原则：

- 先跑通主链路，再优化模型。
- 先保证不丢内容，再追求插入成功率。
- 先做好小胶囊，再做主窗口美化。
- 先做中文和中英混输验收，再扩展更多语言。

---

## 11. 测试清单

### 11.1 功能测试

- 首次启动能引导麦克风权限。
- 首次启动能引导辅助功能权限。
- 快捷键能开始录音。
- 松开快捷键能结束录音。
- 胶囊在录音时出现。
- 胶囊动态条随声音变化。
- `Esc` 能取消。
- 中文能识别。
- 英文能识别。
- 中英混输能识别。
- 润色结果能插入当前输入框。
- 插入失败时能自动复制。
- 历史能看到原文和最终文本。
- 个人词典能影响后续输出。

### 11.2 场景测试

至少测试这些 app：

- TextEdit。
- Notes。
- Safari/Chrome 网页输入框。
- ChatGPT 或 Claude 输入框。
- Cursor 输入框。
- 微信/飞书/Slack 类 IM。
- 邮件客户端。

### 11.3 质量测试

准备样例库，覆盖：

- 去口癖和重复。
- 中途改口。
- 中文标点。
- 中英混输。
- 技术词。
- 邮件表达。
- Prompt 结构化。
- 插入失败兜底。

---

## 12. 第一轮完成定义

满足以下条件才算第一轮完成：

- 主链路可以连续稳定使用。
- 常用 app 中可以完成输入。
- 失败不会丢内容。
- 胶囊 UI 足够小，不干扰工作流。
- 默认润色自然，不过度 AI 化。
- 历史和剪贴板可以恢复最近输入。
- 隐私路径清楚，本地/云端/BYOK 不混淆。
- 用户可以在 5 分钟内完成第一次成功输入。

---

## 13. 关联文档

- [OpenLess 产品需求文档](</Users/lvbaiqing/TRUE 开发/openless/docs/openless-requirements.md>)
- [语音输入产品第一轮需求文档](</Users/lvbaiqing/TRUE 开发/openless/docs/voice-input-mvp-requirements.md>)
- [OpenLess 竞品评论、产品基调与 UI 方向调研](</Users/lvbaiqing/TRUE 开发/openless/docs/competitor-reviews-and-ui-direction.md>)
- [OpenLess 概念版诊断与落地规格](</Users/lvbaiqing/TRUE 开发/openless/docs/openless-product-concept-diagnosis.md>)
- [OpenLess 整体逻辑梳理](</Users/lvbaiqing/TRUE 开发/openless/docs/openless-overall-logic.md>)