openless/USAGE.md

OpenLess 使用说明

面向普通用户。开发者和架构信息见 README.md 与 CLAUDE.md。

---

1. 下载与解除隔离

到 Releases 下载最新的 OpenLess-1.0.0.zip，解压会得到 OpenLess.app。把它拖到 应用程序。

由于 1.0 是 ad-hoc 签名构建（没有付费 Apple Developer ID），macOS Gatekeeper 会拦下提示「无法验证开发者」。在终端中执行一次：

xattr -dr com.apple.quarantine /Applications/OpenLess.app

之后双击就能启动。

这一步只需要做一次。下次升级版本，覆盖 OpenLess.app 后再执行一次同样的命令即可。

2. 授权

OpenLess 需要两个系统权限：

权限	在哪里授权	用来做什么
麦克风	系统设置 → 隐私与安全 → 麦克风	录音
辅助功能	系统设置 → 隐私与安全 → 辅助功能	监听全局快捷键 + 把文本写入当前输入框

授权辅助功能后必须退出 OpenLess 并重新打开。 macOS 不会把新授权同步给已经在跑的进程，全局快捷键监听需要进程重启才能生效。

3. 配置 ASR 和润色凭据

OpenLess 不内置任何云端 Key，需要你自己提供：

• 火山引擎流式 ASR：APP ID、Access Token、Resource ID。在火山引擎控制台开通「语音技术 → 流式语音识别」后获取。
• Ark / DeepSeek 兼容 Chat Completions：API Key、Model ID、Endpoint。Ark 默认 endpoint 是 https://ark.cn-beijing.volces.com/api/v3/chat/completions。

在 OpenLess 主窗口的「设置」标签页填入即可。凭据保存在系统 Keychain（service = com.openless.app），不会上传也不会写入仓库。

如果不填 Ark：OpenLess 会跳过润色，直接插入 ASR 原文。

如果不填火山：OpenLess 会跑一段 mock 流程，并把占位文本复制到剪贴板（不会插入到输入框）。

4. 日常使用

1. 把光标停在任意输入框（聊天框、邮件、代码编辑器、浏览器地址栏……）。
2. 按一次右 Option（默认快捷键）开始录音。底部胶囊会变成红色音量条。
3. 说话。
4. 再按一次右 Option 结束录音。胶囊会进入「转写 → 润色」状态。
5. 润色完的文字会自动插入到光标所在位置。如果当前应用拒绝写入，会复制到剪贴板，请手动 Cmd+V。
6. 按 Esc 在录音过程中取消，原始音频不会发送到 ASR。

每一次会话都会保存到「历史记录」标签页，包含：录音时长、原始转写、润色后文本、采用的模式。

5. 输出模式

在主窗口顶部切换：

模式	适合场景
原文	不想做任何修改，直接拿 ASR 结果。
轻度润色	去口癖、补标点。最常用。
清晰结构	把连贯口语拆成短句、列表。适合需求/任务描述。
正式表达	用更书面的语气重写。适合邮件、公告。

模式只影响润色 prompt，不会让模型「回答你说的话」。详见 README 的「提示词处理原则」。

6. 词典

「词典」标签页用来教模型识别你的专有名词、产品名、人名和新词。

• 每个词条只需要填正确写法、分类（可选）、备注（可选）。
• 启用的词条会作为火山 ASR 的 context.hotwords 提交，识别阶段就尽量正确。
• 同时会注入润色阶段，让模型根据上下文判断是否需要把同音词修正成你的词。例如词典里有 Claude，模型听到 Cloud 时会根据语境决定要不要改成 Claude。

7. 排查

• 按快捷键无反应：辅助功能没授权，或授权后未重启 OpenLess。

• 录音时胶囊一直是灰色：麦克风没授权，或被其他应用独占。

• 转写一直在转圈：火山凭据填错，或网络无法访问火山服务。看日志确认。

• 文字没插入但被复制了：当前应用拒绝 AX 写入和 Cmd+V，按 Cmd+V 手动粘贴。

• 看日志：

  tail -f ~/Library/Logs/OpenLess/OpenLess.log
  

8. 卸载

rm -rf /Applications/OpenLess.app
rm -rf ~/Library/Application\ Support/OpenLess
rm -rf ~/Library/Logs/OpenLess
rm -rf ~/.openless

Keychain 里的凭据可以用「钥匙串访问.app」搜索 com.openless.app 删除。