diff --git a/CLAUDE.md b/CLAUDE.md index add8a32a..ccbbf0d7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -33,6 +33,19 @@ INSTALL=0 ./scripts/build-mac.sh # build only # Frontend-only TS check npm run build # = tsc && vite build + +# Rust type-check without full compile +cargo check --manifest-path src-tauri/Cargo.toml +``` + +### Windows (cross-check only — no macOS runner in CI) + +```powershell +# Preflight: verify toolchain +.\scripts\windows-preflight.ps1 + +# Build (requires Windows host or cross-compile target) +.\scripts\windows-build-gnu.ps1 ``` Generated artifacts: @@ -67,7 +80,7 @@ Swift (Sources/OpenLess*) Rust (openless -all/app/src-tauri/src) P OpenLessCore types.rs Pure value types: DictationSession, PolishMode, HotkeyBinding, errors OpenLessHotkey hotkey.rs Global hotkey monitor (modifier-key edges) OpenLessRecorder recorder.rs Mic → 16 kHz mono Int16 PCM, RMS callback -OpenLessASR asr/{mod,frame,volcengine}.rs Volcengine streaming ASR over WebSocket +OpenLessASR asr/{mod,frame,volcengine,whisper}.rs ASR providers: Volcengine streaming WebSocket + Whisper HTTP OpenLessPolish polish.rs OpenAI-compatible chat completions (Ark / DeepSeek / etc.) OpenLessInsertion insertion.rs AX focused-element write → clipboard + Cmd+V → copy-only fallback OpenLessPersistence persistence.rs History/preferences/vocab JSON + Keychain credentials @@ -75,6 +88,8 @@ OpenLessUI src/components/Capsule.tsx C OpenLessApp / DictationCoord. coordinator.rs + commands.rs + lib.rs State machine, IPC surface, tray icon, window plumbing permissions.rs TCC checks (Accessibility / Microphone) src/ (React) Main window UI: Overview / History / Vocab / Style / Settings + src/pages/_atoms.tsx Recoil atoms — global frontend state + src/state/HotkeySettingsContext.tsx HotkeySettings React context (capability + binding from backend) ``` ### Dictation pipeline diff --git a/README.md b/README.md index 12e7c889..39438392 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,8 @@

OpenLess

- Open-source macOS voice input for the AI era.
- Press a hotkey, speak, get a usable AI prompt at your cursor. + Open-source voice input for macOS & Windows.
+ Press a hotkey, speak, get AI-polished text at your cursor.

@@ -16,14 +16,20 @@

release license - macOS - Swift + macOS + Windows + Tauri + Rust Stars

+

+ Join our QQ Group: 1078960553 +

+ --- -OpenLess is a native macOS voice-input app — a **fully open-source** alternative to commercial tools like [Typeless](https://www.typeless.com/), [Wispr Flow](https://wisprflow.ai), [Lazy](https://heylazy.com), and Superwhisper. +OpenLess is a cross-platform (macOS & Windows) voice-input app — a **fully open-source** alternative to commercial tools like [Typeless](https://www.typeless.com/), [Wispr Flow](https://wisprflow.ai), [Lazy](https://heylazy.com), and Superwhisper. Put your cursor in any text field — ChatGPT, Claude, Cursor, Notion, an email draft, a chat box — press one global hotkey and talk. OpenLess records, transcribes, polishes the text in the mode you picked, and inserts the result at the cursor. If insertion is blocked it copies to the clipboard, so the words you spoke don't get lost. @@ -84,60 +90,68 @@ OpenLess does one thing: **turn speech into usable written text (especially AI p | [Lazy](https://heylazy.com) | Closed-source notes / capture tool | Not a notes container — inserts straight into any input field | | [Superwhisper](https://superwhisper.com) | Closed-source macOS, subscription | Open source; cloud ASR today, local ASR on the roadmap | -## Status (v1.0) +## Status (v1.1) -- Native Swift / SwiftUI / AppKit, SwiftPM project; macOS 15+. -- macOS 26+ uses Liquid Glass; older systems fall back to system materials. +- Tauri 2 + Rust backend + React/TS frontend. macOS 12+, Windows 10+. - Toggle-style recording: press to start, press again to stop. `Esc` cancels. - Volcengine streaming ASR + Ark / DeepSeek-compatible chat-completions for polish. - 4 output modes: raw, light polish, structured (**AI prompt mode**), formal. -- Main window: Home / History / Dictionary / Settings. Persistent menu bar. Mini status capsule at the bottom of the screen. -- Dictionary entries are injected as Volcengine ASR `context.hotwords` and as semantic hints during polish. +- Main window: Overview / History / Vocab / Style / Settings. Persistent tray icon. Mini status capsule floating on screen. +- Dictionary entries injected as Volcengine ASR `context.hotwords` and as semantic hints during polish. +- Platform-native global hotkey: CGEventTap on macOS, low-level keyboard hook (`WH_KEYBOARD_LL`) on Windows. ## Download & install (end users) -Grab `OpenLess-1.0.0.zip` from [Releases](../../releases), unzip to get `OpenLess.app`, drag to `/Applications`. +Go to [Releases](../../releases) and download: +- **macOS**: `OpenLess__aarch64.dmg` — open, drag to `/Applications` +- **Windows**: `OpenLess__x64-setup.exe` — run the installer -**Important:** the 1.0 build is ad-hoc signed (no Apple Developer ID + notarization). macOS Gatekeeper will block it with "cannot verify developer". Remove the quarantine attribute once in Terminal: +On first launch, grant the permissions the app requests: -```bash -xattr -dr com.apple.quarantine /Applications/OpenLess.app -``` +**macOS:** +1. Grant Microphone access. +2. Grant Accessibility access. +3. **Quit and reopen the app** — Accessibility only takes effect after a restart. +4. Open Settings → fill in Volcengine ASR + Ark credentials. -Then double-click to launch. On first launch, in `System Settings → Privacy & Security`: +**Windows:** +1. Grant Microphone access when prompted. +2. Open Settings → Permissions to verify the global hotkey listener is active. +3. Fill in Volcengine ASR + Ark credentials in Settings. -1. Grant Microphone access to OpenLess. -2. Grant Accessibility access to OpenLess. -3. **Quit OpenLess and reopen it.** Accessibility permission only takes effect for the global hotkey after a process restart. -4. Open the OpenLess home from the Dock → "Settings" → fill in Volcengine ASR + Ark credentials. - -Full end-user walkthrough: [USAGE.md](USAGE.md) (Chinese; English version coming). +Full end-user walkthrough: [USAGE.md](USAGE.md). ## Build from source (developers) +The active codebase is in `openless -all/app/` (Tauri 2 + Rust + React/TS). + ```bash -# Library / test build -swift build -swift test +cd "openless -all/app" +npm ci -# Full .app build (release, ad-hoc signed, resets TCC by default) -./scripts/build-app.sh +# Dev: Vite at :1420 + Tauri shell +npm run tauri dev -# Keep existing TCC approvals -RESET_TCC=0 ./scripts/build-app.sh +# macOS release build (signs, installs, resets TCC) +./scripts/build-mac.sh +INSTALL=0 ./scripts/build-mac.sh # build only, skip install -# Launch -open build/OpenLess.app +# Rust type-check without full compile +cargo check --manifest-path src-tauri/Cargo.toml -# Tail logs -tail -f ~/Library/Logs/OpenLess/OpenLess.log +# Frontend TS check +npm run build ``` -Launch arguments (handled in `AppDelegate.runLaunchActions`): +Logs: `~/Library/Logs/OpenLess/openless.log` (macOS) / `%LOCALAPPDATA%\OpenLess\Logs\openless.log` (Windows). + +**Windows build** — see [`openless -all/README.md`](openless%20-all/README.md) for MSVC vs GNU/MinGW routes. + +**Swift (legacy, Sparkle updates only):** ```bash -open build/OpenLess.app --args --open-settings -open build/OpenLess.app --args --start-recording +swift build && swift test +./scripts/build-app.sh ``` ## Credentials @@ -183,44 +197,46 @@ The main window is organized as Home / History / Dictionary / Settings. The Dict ## Architecture -A SwiftPM workspace: 1 executable + 8 libraries. Libraries don't depend on each other — they all depend only on `OpenLessCore`. `OpenLessApp` wires everything together inside `DictationCoordinator`. +The active implementation is Tauri 2 (`openless -all/app/`). The Swift/SwiftPM codebase under `Sources/` is legacy and still serves Sparkle auto-updates for existing users. + +**Tauri backend (Rust)** — each module depends only on `types.rs`: ``` -OpenLessCore // Pure value types: DictationSession, PolishMode, HotkeyBinding, - // AudioConsumer protocol, RawTranscript/FinalText, errors. -OpenLessHotkey // CGEventTap-based modifier-key monitor. Requires Accessibility. -OpenLessRecorder // AVAudioEngine → 16 kHz mono Int16 PCM, pushed to AudioConsumer. -OpenLessASR // Volcengine streaming ASR over WebSocket. -OpenLessPolish // Ark / Doubao chat-completions client + mode-driven prompts. -OpenLessInsertion // AX focused-element first; clipboard + Cmd+V; copy-only fallback. -OpenLessPersistence // CredentialsVault (Keychain), HistoryStore, DictionaryStore, - // UserPreferences. -OpenLessUI // SwiftUI capsule view + state enum (no window plumbing). -OpenLessApp // AppDelegate, menu bar, settings window, capsule window, - // DictationCoordinator. +types.rs Pure value types: DictationSession, PolishMode, HotkeyBinding, errors +hotkey.rs Global hotkey (CGEventTap on macOS, WH_KEYBOARD_LL on Windows, rdev on Linux) +recorder.rs Mic → 16 kHz mono Int16 PCM, RMS callback +asr/ Volcengine streaming ASR (WebSocket) + Whisper HTTP +polish.rs OpenAI-compatible chat-completions (Ark / DeepSeek / etc.) +insertion.rs AX focused-element → clipboard + Cmd+V → copy-only fallback +persistence.rs History / preferences / vocab JSON + Keychain credentials +permissions.rs TCC checks (Accessibility / Microphone) +coordinator.rs State machine: Idle → Starting → Listening → Processing +commands.rs Tauri IPC surface ``` -The record → transcribe → polish → insert state machine is owned exclusively by `Sources/OpenLessApp/DictationCoordinator.swift`. See [CLAUDE.md](CLAUDE.md) for details. +**React frontend (`src/`)** — state via Recoil atoms (`pages/_atoms.tsx`); hotkey capability/binding via `HotkeySettingsContext`; all backend calls go through `lib/ipc.ts`. -## Roadmap (post-1.0) +The dictation pipeline: `hotkey edge → Recorder.start + ASR.openSession → [audio frames] → hotkey edge → Recorder.stop + ASR.sendLastFrame → Polish → Insert → History.save`. -Planned in the requirements docs but not in the 1.0 release: +See [CLAUDE.md](CLAUDE.md) for invariants and module-wiring rules. -- Local ASR (today only Volcengine cloud). +## Roadmap + +Planned but not yet shipped: + +- Local ASR (Whisper integration in progress; currently Volcengine cloud only). - Snippets (no UI / trigger logic yet). - History enhancements: copy button, search, re-polish, re-insert. - "Paste last result" hotkey. - Multi-monitor capsule placement on the focused screen. -- Developer ID signing + notarization + Sparkle auto-update. ## Maintainer release checklist -- Confirm `.build/`, `build/`, `.DS_Store`, `~/.openless/credentials.json`, and stray screenshots are not committed. -- Keep `Resources/Brand/openless-app-icon-source.jpg`, `Resources/AppIcon.png`, `Resources/AppIcon.icns`. -- Run `./scripts/build-app.sh` and confirm `build/OpenLess.app` launches. +- Bump version in `openless -all/app/package.json`, `src-tauri/tauri.conf.json`, and `src-tauri/Cargo.toml`. +- Run `INSTALL=0 ./scripts/build-mac.sh` and confirm the `.app` launches. - Verify on a clean macOS box: permission flow, hotkey, recording, ASR, polish, insertion, clipboard fallback. -- Package with `ditto -c -k --keepParent build/OpenLess.app build/OpenLess-.zip` so ad-hoc signature and xattrs survive. -- Do Developer ID signing + notarization before any production distribution. +- Push a `v-tauri` tag — CI builds and signs the macOS `.dmg` + Windows `.msi`. +- **Swift legacy release** (for Sparkle users): `./scripts/release.sh ` — see [CLAUDE.md](CLAUDE.md) for the full flow. ## License diff --git a/README.zh.md b/README.zh.md index 4d5c5350..21b9254a 100644 --- a/README.zh.md +++ b/README.zh.md @@ -5,8 +5,8 @@

OpenLess

- 面向 AI 时代的开源 macOS 语音输入。
- 按一次快捷键说话，自动整理成可直接用的 AI prompt，落到当前光标。 + 开源语音输入，支持 macOS 和 Windows。
+ 按一次快捷键说话，AI 润色后的文字直接落到当前光标。

@@ -16,14 +16,20 @@

release license - macOS - Swift + macOS + Windows + Tauri + Rust Stars

+

+ 加入 QQ 群：1078960553 +

+ --- -OpenLess 是一个原生 macOS 语音输入应用，对标 [Typeless](https://www.typeless.com/)、[Wispr Flow](https://wisprflow.ai)、[Lazy](https://heylazy.com)、Superwhisper 等商业语音输入工具的 **完全开源** 替代品。 +OpenLess 是一个跨平台（macOS & Windows）语音输入应用，对标 [Typeless](https://www.typeless.com/)、[Wispr Flow](https://wisprflow.ai)、[Lazy](https://heylazy.com)、Superwhisper 等商业语音输入工具的 **完全开源** 替代品。 把光标放在 ChatGPT、Claude、Cursor、Notion、邮件、聊天框任意输入框里，按一次全局快捷键说话——OpenLess 会录音、转写、按你选的模式润色，把结果直接插入光标位置。插入失败时会自动复制到剪贴板，尽量保证「你说过的话不丢」。 @@ -84,60 +90,68 @@ OpenLess 只做一件事：**把语音变成可用的书面文字（尤其是 AI | [Lazy](https://heylazy.com) | 闭源笔记/捕获工具 | 不做笔记容器，专做「插入到任意输入框」 | | [Superwhisper](https://superwhisper.com) | 闭源 macOS，订阅制 | 开源；目前云端 ASR 优先，本地 ASR 在 roadmap | -## 当前状态（v1.0） +## 当前状态（v1.1） -- 原生 Swift / SwiftUI / AppKit，SwiftPM 项目；macOS 15+。 -- macOS 26+ 使用 Liquid Glass 效果，旧系统回退到系统 material。 -- 默认是切换式录音：按一次开始，再按一次结束；录音中按 `Esc` 取消。 +- Tauri 2 + Rust 后端 + React/TS 前端；macOS 12+，Windows 10+。 +- 切换式录音：按一次开始，再按一次结束；录音中按 `Esc` 取消。 - 接入火山引擎流式 ASR 和 Ark / DeepSeek 兼容 Chat Completions 进行润色。 - 4 种输出模式：原文、轻度润色、清晰结构（**AI prompt 模式**）、正式表达。 -- 主窗口按「首页 / 历史记录 / 词典 / 设置」组织；菜单栏常驻；底部有微型状态胶囊。 -- 词典支持作为 ASR 热词注入和润色阶段的语义判断。 +- 主窗口按「概览 / 历史 / 词典 / 风格 / 设置」组织；托盘图标常驻；浮动状态胶囊。 +- 词典条目注入 ASR 热词和润色语义提示。 +- 平台原生全局快捷键：macOS 使用 CGEventTap，Windows 使用低层键盘钩子（`WH_KEYBOARD_LL`）。 ## 下载与安装（普通用户） -到 [Releases](../../releases) 下载 `OpenLess-1.0.0.zip`，解压得到 `OpenLess.app`，拖到 `应用程序`。 +到 [Releases](../../releases) 下载对应平台的安装包： +- **macOS**：`OpenLess_<版本>_aarch64.dmg` — 打开后拖入「应用程序」 +- **Windows**：`OpenLess_<版本>_x64-setup.exe` — 运行安装程序 -**重要：** 1.0 是开发期 ad-hoc 签名构建（未做 Apple Developer ID 签名和 notarization）。直接打开会被 Gatekeeper 拦下提示“无法验证开发者”。需要在终端中移除隔离属性： +首次启动需要授予权限： -```bash -xattr -dr com.apple.quarantine /Applications/OpenLess.app -``` +**macOS：** +1. 授予麦克风权限。 +2. 授予辅助功能权限。 +3. **退出 OpenLess 并重新打开**（辅助功能授权需要重启才对全局快捷键生效）。 +4. 打开「设置」，填入火山引擎 ASR 和 Ark 凭据。 -之后就可以双击启动。首次启动需要在 `系统设置 → 隐私与安全`： +**Windows：** +1. 按提示授予麦克风权限。 +2. 打开「设置 → 权限」确认全局快捷键监听器已启动。 +3. 在「设置」中填入火山引擎 ASR 和 Ark 凭据。 -1. 授予 OpenLess 麦克风权限。 -2. 授予 OpenLess 辅助功能权限。 -3. **退出 OpenLess 并重新打开**（辅助功能授权对全局快捷键生效需要重启进程）。 -4. 从 Dock 打开 OpenLess 首页 → 「设置」 → 填入火山引擎 ASR 和 Ark 凭据。 - -完整的端用户使用步骤见 [USAGE.md](USAGE.md)。 +完整使用步骤见 [USAGE.md](USAGE.md)。 ## 从源码构建（开发者） +当前活跃代码库在 `openless -all/app/`（Tauri 2 + Rust + React/TS）。 + ```bash -# 库 / 测试构建 -swift build -swift test +cd "openless -all/app" +npm ci -# 完整 .app 构建（release，ad-hoc 签名，默认重置 TCC） -./scripts/build-app.sh +# 开发模式：Vite at :1420 + Tauri shell +npm run tauri dev -# 保留已授予的 TCC 权限 -RESET_TCC=0 ./scripts/build-app.sh +# macOS release 构建（签名、安装、重置 TCC） +./scripts/build-mac.sh +INSTALL=0 ./scripts/build-mac.sh # 只构建，不安装 -# 启动 -open build/OpenLess.app +# Rust 类型检查（不做完整编译） +cargo check --manifest-path src-tauri/Cargo.toml -# 实时日志 -tail -f ~/Library/Logs/OpenLess/OpenLess.log +# 前端 TS 检查 +npm run build ``` -启动参数（在 `AppDelegate.runLaunchActions` 处理）： +日志路径：`~/Library/Logs/OpenLess/openless.log`（macOS）/ `%LOCALAPPDATA%\OpenLess\Logs\openless.log`（Windows）。 + +**Windows 构建** — MSVC 和 GNU/MinGW 两种路线详见 [`openless -all/README.md`](openless%20-all/README.md)。 + +**Swift（仅用于 Sparkle 遗留版本发布）：** ```bash -open build/OpenLess.app --args --open-settings -open build/OpenLess.app --args --start-recording +swift build && swift test +./scripts/build-app.sh ``` ## 凭据 @@ -187,43 +201,46 @@ OpenLess 的润色模型只做文本整理，不做问答、不做任务执行 ## 架构概览 -SwiftPM 工作区，1 个可执行 + 8 个库。库与库之间无相互依赖，全部只依赖 `OpenLessCore`，由 `OpenLessApp` 统一在 `DictationCoordinator` 里编排。 +当前活跃实现是 Tauri 2（`openless -all/app/`）。`Sources/` 下的 Swift/SwiftPM 代码是遗留版本，仍为老用户提供 Sparkle 自动更新。 + +**Tauri 后端（Rust）** — 各模块只依赖 `types.rs`： ``` -OpenLessCore // Pure value types: DictationSession, PolishMode, HotkeyBinding, - // AudioConsumer protocol, RawTranscript/FinalText, errors. -OpenLessHotkey // CGEventTap-based modifier-key monitor. Requires Accessibility. -OpenLessRecorder // AVAudioEngine → 16 kHz mono Int16 PCM, 推送到 AudioConsumer. -OpenLessASR // 火山引擎 streaming ASR over WebSocket. -OpenLessPolish // Ark / Doubao chat-completions 客户端 + 模式驱动 prompts。 -OpenLessInsertion // AX focused-element 优先；剪贴板 + Cmd+V 兜底；最后 copy-only。 -OpenLessPersistence // CredentialsVault (Keychain), HistoryStore, DictionaryStore, - // UserPreferences。 -OpenLessUI // SwiftUI 胶囊视图 + 状态枚举（不接窗口）。 -OpenLessApp // AppDelegate, 菜单栏, 设置窗口, 胶囊窗口, DictationCoordinator。 +types.rs 纯值类型：DictationSession, PolishMode, HotkeyBinding, 错误类型 +hotkey.rs 全局快捷键（macOS: CGEventTap，Windows: WH_KEYBOARD_LL，Linux: rdev） +recorder.rs 麦克风 → 16 kHz 单声道 Int16 PCM，RMS 回调 +asr/ 火山引擎流式 ASR（WebSocket）+ Whisper HTTP +polish.rs OpenAI 兼容 chat-completions（Ark / DeepSeek 等） +insertion.rs AX focused-element → 剪贴板 + Cmd+V → 仅复制兜底 +persistence.rs 历史记录 / 偏好设置 / 词典 JSON + Keychain 凭据 +permissions.rs TCC 权限检查（辅助功能 / 麦克风） +coordinator.rs 状态机：Idle → Starting → Listening → Processing +commands.rs Tauri IPC 接口 ``` -录音 → 转写 → 润色 → 插入的状态机由 `Sources/OpenLessApp/DictationCoordinator.swift` 单一拥有，详见 [CLAUDE.md](CLAUDE.md)。 +**React 前端（`src/`）** — 状态通过 Recoil atoms（`pages/_atoms.tsx`）管理；快捷键能力和绑定通过 `HotkeySettingsContext` 获取；所有后端调用走 `lib/ipc.ts`。 -## 1.0 之后的规划 +录音 → 转写 → 润色 → 插入流水线：`快捷键触发 → Recorder.start + ASR.openSession → [音频帧] → 再次触发 → Recorder.stop + ASR.sendLastFrame → Polish → Insert → History.save`。 -下面这些功能在需求文档里有规划，但 1.0 没有发布： +详细的不变量和模块接线规则见 [CLAUDE.md](CLAUDE.md)。 -- 本地 ASR：当前仅接入火山引擎云端 ASR。 +## 规划中 + +尚未发布的功能： + +- 本地 ASR（Whisper 接入进行中；当前仅支持火山引擎云端）。 - 常用片段 Snippets：尚无 UI 和触发逻辑。 - 历史增强：复制按钮、搜索、重新润色、重新插入。 -- 粘贴上一条快捷键。 -- 多屏定位：胶囊按当前焦点所在屏幕显示。 -- Developer ID 签名 + Notarization + Sparkle 自动更新。 +- 粘贴上一条结果快捷键。 +- 多屏定位：胶囊跟随焦点所在屏幕显示。 -## 维护者：发布前检查 +## 维护者：发布检查 -- 确认没有提交 `.build/`、`build/`、`.DS_Store`、`~/.openless/credentials.json` 或临时截图。 -- 保留 `Resources/Brand/openless-app-icon-source.jpg`、`Resources/AppIcon.png`、`Resources/AppIcon.icns`。 -- 运行 `./scripts/build-app.sh`，确认 `build/OpenLess.app` 可启动。 -- 在一台干净 macOS 机器上验证权限引导、快捷键、录音、ASR、润色、插入和剪贴板兜底。 -- 用 `ditto -c -k --keepParent build/OpenLess.app build/OpenLess-.zip` 打包，确保 ad-hoc 签名和扩展属性保留。 -- 正式分发前请完成 Developer ID 签名和 notarization。 +- 同步更新 `openless -all/app/package.json`、`src-tauri/tauri.conf.json`、`src-tauri/Cargo.toml` 中的版本号。 +- 运行 `INSTALL=0 ./scripts/build-mac.sh`，确认 `.app` 可启动。 +- 在干净 macOS 机器上验证：权限引导、快捷键、录音、ASR、润色、插入、剪贴板兜底。 +- 推送 `v-tauri` tag → CI 构建并签名 macOS `.dmg` + Windows `.msi`。 +- **Swift 遗留发布**（面向 Sparkle 老用户）：`./scripts/release.sh ` — 详见 [CLAUDE.md](CLAUDE.md)。 ## 许可 diff --git a/USAGE.md b/USAGE.md new file mode 100644 index 00000000..5945bf19 --- /dev/null +++ b/USAGE.md @@ -0,0 +1,128 @@ +# OpenLess 使用指南 + +## 安装 + +### macOS + +1. 从 [Releases](https://github.com/appergb/openless/releases/latest) 下载 `OpenLess_<版本>_aarch64.dmg`。 +2. 打开 dmg，将 OpenLess.app 拖入「应用程序」文件夹。 +3. 双击启动。 + +### Windows + +1. 从 [Releases](https://github.com/appergb/openless/releases/latest) 下载 `OpenLess_<版本>_x64-setup.exe`。 +2. 运行安装程序，按提示完成安装。 +3. 从开始菜单启动 OpenLess。 + +--- + +## 首次配置 + +### macOS 权限 + +首次启动后，在「系统设置 → 隐私与安全」中授予以下权限： + +1. **麦克风** — 允许 OpenLess 录音。 +2. **辅助功能** — 允许 OpenLess 读写当前焦点输入框。授权后须**完全退出并重新启动** OpenLess，快捷键才会生效。 + +### Windows 权限 + +1. 按系统提示授予**麦克风**权限。 +2. 打开 OpenLess → 「设置 → 权限」，确认全局快捷键监听器状态显示为「已启动」。 + +### 填入凭据 + +打开 OpenLess → **设置**，填入以下字段： + +| 字段 | 说明 | +| --- | --- | +| 火山引擎 App ID | 语音识别服务的应用 ID | +| 火山引擎 Access Token | 语音识别访问凭据 | +| 火山引擎 Resource ID | 语音识别资源 ID | +| Ark API Key | 文本润色服务的 API Key | +| Ark Model ID | 使用的模型 ID（如 `doubao-pro-32k`） | +| Ark Endpoint | 接口地址，默认 `https://ark.cn-beijing.volces.com/api/v3/chat/completions` | + +保存后设置立即生效，无需重启。 + +--- + +## 基本使用 + +### 开始录音 + +按下全局快捷键（默认 macOS 右 Option，Windows 右 Control）。 +屏幕边缘会出现状态胶囊，显示「录音中」。 + +### 结束录音 + +再次按下同一快捷键。OpenLess 会： + +1. 停止录音并发送音频进行转写。 +2. 对转写结果按当前输出模式进行润色。 +3. 将润色后的文字插入当前焦点输入框（失败时自动复制到剪贴板）。 + +### 取消录音 + +录音过程中按 `Esc`，当前录音内容会被丢弃，不做任何插入。 + +--- + +## 输出模式 + +在 OpenLess 主窗口的胶囊或「设置」中切换模式： + +| 模式 | 说明 | +| --- | --- | +| 原文 | 直接输出转写文字，不做任何修改 | +| 轻度润色 | 修正语气词、标点、明显错字，保留原意 | +| 清晰结构（AI prompt 模式） | 把口语整理成有结构、有约束、有上下文的 prompt，适合直接喂给 ChatGPT / Claude / Cursor | +| 正式表达 | 将口语转换为正式书面语 | + +--- + +## 词典 + +词典用于提高特定词汇的识别准确率（产品名、人名、专有名词等）。 + +1. 打开主窗口 → **词典**。 +2. 点击「新建」，填入正确拼写、分类和备注。 +3. 启用后，词条会作为热词注入 ASR 识别阶段，并在润色阶段辅助语义判断。 + +--- + +## 历史记录 + +主窗口 → **历史**，可查看所有录音记录，包括原始转写和润色结果。 + +--- + +## 更换快捷键 + +主窗口 → **设置 → 快捷键**，选择触发键。 +macOS 支持右侧修饰键（Option / Control / Command / Shift）；Windows 支持右 Control。 + +--- + +## 常见问题 + +**Q: 快捷键没反应？** +macOS：确认已授予辅助功能权限，且授权后重启过 OpenLess。 +Windows：在「设置 → 权限」中检查监听器状态。 + +**Q: 识别结果为空或是占位文字？** +检查火山引擎 ASR 凭据是否填写正确。填写正确后识别才能正常工作。 + +**Q: 文字没有插入，只是复制到了剪贴板？** +当目标输入框不支持辅助功能写入时（如某些安全限制的应用），OpenLess 会自动回退到剪贴板复制，手动粘贴即可。 + +**Q: 润色结果和预期不符？** +尝试切换输出模式，或在词典中添加相关专有名词。 + +--- + +## 社区与支持 + +欢迎通过 QQ 加入用户群，反馈问题或交流使用体验： + +**QQ 群：1078960553**