[feature] 语音快捷键触发 Claude Code / OpenCode Agent，并支持语音润色模型配置 #579

背景

OpenLess 当前已经支持热键录音、ASR、LLM 润色、文本插入、Selection Ask QA 面板。希望在此基础上新增一个“语音调用代码 Agent”的独立能力：

1. 用户触发专用快捷键后，OpenLess 开始录音。
2. 再次触发快捷键后结束录音，ASR 得到文本。
3. 系统可按配置先用“语音润色大语言模型”整理语音转写内容。
4. 后端把最终文本发送给 Claude Code 或开源 OpenCode Agent。
5. Agent 输出结果流式返回前端面板展示。

当前 OpenLess README 中说明产品主要负责文本整理，不负责回答问题、执行任务或分析项目。本功能会扩展为独立的 coding-agent 模式，应保持和普通听写、翻译、Selection Ask QA 分离，避免改变现有默认听写行为。

目标

新增一个独立功能：Voice Coding Agent。

默认行为：

• 默认关闭，需要用户在设置页开启。
• 使用独立快捷键，默认建议：
  • Windows/Linux: Ctrl+Shift+Enter
  • macOS: Cmd+Shift+Enter
• 第一次按下开始录音。
• 第二次按下停止录音并进入 ASR。
• ASR 结果可先经过语音润色模型整理。
• 整理后的指令发送给 configured coding agent。
• 前端显示：
  • 原始 ASR 文本
  • 润色后的指令
  • Agent 当前状态
  • 流式输出
  • 错误、超时、取消状态
• 默认不自动插入文本到当前光标位置。
• 默认不允许 Agent 修改本地文件；权限模式默认为只读/计划模式。
• 用户可在高级设置中切换为更强权限模式。

非目标

• 不改变普通听写热键行为。
• 不改变 Selection Ask QA 的现有交互。
• 不把 Claude Code 输出默认插入到其他应用。
• 不默认启用 bypassPermissions。
• 不把 API key、access token、命令输出中的敏感字段写入前端事件、日志或历史记录。

调研结论

• OpenLess 当前主处理路径已经具备热键录音、ASR、LLM 润色、历史保存、QA 面板流式回答能力，可复用大部分基础设施。
• 现有 Selection Ask QA 功能最接近目标：qa_hotkey 负责打开面板，主听写热键在面板可见时开始/结束 QA 录音，后端用 ASR 得到文本，再调用当前 LLM provider，前端通过 qa:state 接收流式回答。
• 当前 UserPreferences 已有 active_llm_provider、llm_thinking_enabled、qa_hotkey 等字段；凭据通过 OS vault 保存，LLM provider 支持 Ark、OpenAI-compatible、Gemini、Codex OAuth、custom 等。
• 官方 Claude Code 可通过 CLI 和 SDK 集成，关键参数包括 claude -p/--print、--output-format text|json|stream-json、--model、--fallback-model、--permission-mode、--allowedTools、--disallowedTools、--mcp-config。
• 官方 Claude Code 未定位为可 fork 的开源实现；开源优先方案应增加 opencode 适配器。OpenCode 是开源终端 coding agent，适合做二次开发优先落点，同时保留官方 claude-code-cli 适配器满足 Claude Code 用户。
• 相关 Issue 不构成重复：[insertion] 新增送出前文字處理 Hook #575 是“送出前文字处理 Hook”，[area] 无法现在大模型，也不知道哪个处于启用状态 #578 是模型选择状态问题；本需求是独立的语音触发代码 Agent 功能，但需要兼容 [insertion] 新增送出前文字處理 Hook #575 的文本处理扩展思路。

参考资料：

• Claude Code overview
• Claude Code CLI reference
• Claude Code SDK
• Claude Code MCP
• Claude Code hooks
• OpenCode official site
• OpenCode GitHub

Claude Code / OpenCode 集成策略

Provider 抽象

新增后端 trait：

#[async_trait]
pub trait CodingAgentProvider: Send + Sync {
    async fn run(
        &self,
        request: CodingAgentRequest,
        sink: CodingAgentEventSink,
        cancel: CancellationToken,
    ) -> Result<CodingAgentResult, CodingAgentError>;
}

核心类型：

pub struct CodingAgentRequest {
    pub session_id: String,
    pub prompt: String,
    pub raw_transcript: String,
    pub polished_prompt: Option<String>,
    pub cwd: PathBuf,
    pub model: Option<String>,
    pub fallback_model: Option<String>,
    pub permission_mode: CodingAgentPermissionMode,
    pub allowed_tools: Vec<String>,
    pub disallowed_tools: Vec<String>,
    pub timeout_secs: u64,
    pub extra_system_prompt: Option<String>,
}

pub enum CodingAgentEvent {
    Started { session_id: String },
    TranscriptReady { text: String },
    PromptReady { text: String },
    Delta { text: String },
    ToolEvent { name: String, status: String },
    Completed { text: String },
    Cancelled,
    Error { message: String },
}

Provider IDs：

• claude-code-cli
• opencode-cli
• 预留：claude-code-sdk

Claude Code CLI 适配器

新增 ClaudeCodeCliProvider：

• 默认可执行文件：claude
• 支持用户配置可执行文件路径。
• 使用非交互 print 模式：
  • claude -p
  • --output-format stream-json
  • --model <model>
  • --fallback-model <fallback_model>
  • --permission-mode <mode>
  • --add-dir <cwd> 如用户配置了额外目录
  • --mcp-config <path> 如用户配置 MCP
  • --append-system-prompt <prompt> 如配置了额外系统提示词
• stdin 写入最终 prompt。
• stdout 按行解析 stream-json。
• stderr 独立收集，只在错误状态中返回摘要。
• timeout 到期后 kill 子进程并发送 agent:error。
• 用户取消时 kill 子进程并发送 agent:cancelled。
• 子进程退出码非 0 时返回 CodingAgentError::ProcessExit。

默认权限：

permission_mode = CodingAgentPermissionMode::Plan
timeout_secs = 300
allowed_tools = []
disallowed_tools = []

高级权限选项：

• plan
• default
• acceptEdits
• bypassPermissions

UI 中 bypassPermissions 必须放在高级区，附带明确风险文案，不能作为默认值。

OpenCode 适配器

新增 OpenCodeCliProvider：

• provider id: opencode-cli
• 作为开源优先落点。
• 默认可执行文件：opencode
• 先实现同一 CodingAgentProvider trait。
• 命令参数由适配器内部封装，保持前端配置和 Claude Code 适配器一致：
  • cwd
  • model
  • permission_mode
  • timeout_secs
  • extra_system_prompt
• 若当前 OpenCode CLI 版本缺少稳定的非交互 stream 输出协议，先以实验 provider 暴露，并在 UI 中显示“experimental”。

后端实现

Preferences

在 UserPreferences 增加字段：

pub coding_agent_enabled: bool,
pub coding_agent_hotkey: Option<ShortcutBinding>,
pub coding_agent_provider: CodingAgentProviderId,
pub coding_agent_workdir: Option<String>,
pub coding_agent_permission_mode: CodingAgentPermissionMode,
pub coding_agent_model: Option<String>,
pub coding_agent_fallback_model: Option<String>,
pub coding_agent_timeout_secs: u64,
pub coding_agent_show_panel_on_start: bool,
pub coding_agent_save_history: bool,
pub coding_agent_use_voice_polish: bool,
pub voice_polish_model_mode: VoicePolishModelMode,
pub voice_polish_provider_id: Option<String>,
pub voice_polish_thinking_enabled: bool,

默认值：

coding_agent_enabled = false
coding_agent_hotkey = CtrlOrCmd + Shift + Enter
coding_agent_provider = "claude-code-cli"
coding_agent_workdir = None
coding_agent_permission_mode = Plan
coding_agent_timeout_secs = 300
coding_agent_show_panel_on_start = true
coding_agent_save_history = true
coding_agent_use_voice_polish = true
voice_polish_model_mode = SystemDefault
voice_polish_provider_id = None
voice_polish_thinking_enabled = false

新增 enum：

pub enum VoicePolishModelMode {
    SystemDefault,
    CustomProvider,
}

pub enum CodingAgentPermissionMode {
    Plan,
    Default,
    AcceptEdits,
    BypassPermissions,
}

同步更新：

• Rust defaults
• serde rename
• TypeScript UserPreferences
• IPC mock settings
• 设置页初始值
• 所有 i18n locale key

语音润色模型配置层

新增“语音润色大语言模型”配置，不直接复用全局 active LLM 的写入命令，避免改变普通听写配置。

配置模式：

1. SystemDefault
   • 读取现有 active LLM provider。
   • 使用现有润色 prompt 和 style pack。
   • 不新增凭据。
2. CustomProvider
   • 使用独立 provider id：voice-polish-custom。
   • 凭据仍写入 OS vault 的 LLM providers map。
   • 保存字段：
     • displayName
     • apiKey
     • baseURL
     • model
     • temperature
     • extraHeaders
   • 前端只显示 hasApiKey，不回传明文 key。
   • 提供校验按钮，调用后端真实发起轻量模型请求。

新增后端命令：

get_voice_polish_model_config() -> VoicePolishModelConfigWire
set_voice_polish_model_mode(mode: VoicePolishModelMode)
set_voice_polish_provider_config(config: VoicePolishProviderConfigWire)
validate_voice_polish_provider_config(config: VoicePolishProviderConfigWire) -> ProviderValidationResult
list_voice_polish_provider_models(config: VoicePolishProviderConfigWire) -> Vec<ModelInfo>

新增 provider factory：

fn build_voice_polish_provider(
    prefs: &UserPreferences,
    vault: &CredentialsVault,
) -> Result<Box<dyn LLMProvider>, ProviderError>

规则：

• SystemDefault 走现有 ActiveLLMProvider。
• CustomProvider 通过 provider id 精确读取 vault entry。
• 不修改 active_llm_provider。
• 不使用 ...storedSettings 展开旧字段。
• 保存 preferences 时仅写白名单字段。

Hotkey

新增 hotkey watcher 字段：

coding_agent_hotkey: Arc<Mutex<Option<ShortcutBinding>>>

新增命令：

get_coding_agent_hotkey_label()
set_coding_agent_hotkey(binding: Option<ShortcutBinding>)

更新冲突检测：

• dictation hotkey
• translation hotkey
• selection ask hotkey
• switch style hotkey
• open app hotkey
• coding agent hotkey

冲突时返回当前已有的快捷键名称。

Coordinator 状态机

新增状态：

pub enum CodingAgentPhase {
    Idle,
    Recording,
    Transcribing,
    Polishing,
    AgentRunning,
}

新增 session state：

pub struct CodingAgentSessionState {
    pub session_id: String,
    pub phase: CodingAgentPhase,
    pub started_at: Instant,
    pub raw_transcript: Option<String>,
    pub polished_prompt: Option<String>,
    pub cancel_token: CancellationToken,
}

快捷键处理：

1. Idle 且 feature enabled：
   • 校验 workdir 已配置且存在。
   • 校验 ASR provider 可用。
   • 打开 Agent panel。
   • 启动 recorder + ASR session。
   • phase -> Recording。
2. Recording：
   • stop recorder。
   • send last frame。
   • phase -> Transcribing。
   • 等待 ASR final。
3. ASR final 为空：
   • phase -> Idle
   • 前端显示空转写错误。
4. coding_agent_use_voice_polish = true：
   • phase -> Polishing
   • 调用 voice polish provider。
   • 失败时按配置 fallback：
     • 默认 fallback 到 raw transcript，并在 UI 显示 warning。
5. 调用 coding agent：
   • phase -> AgentRunning
   • 将 stream event 转成 Tauri event。
6. 完成：
   • 保存历史。
   • phase -> Idle
   • 前端显示完成。

事件名建议：

• coding-agent:state
• coding-agent:level
• coding-agent:dismiss
• coding-agent:history

前端事件 payload：

type CodingAgentStateEvent =
  | { kind: "phase"; phase: CodingAgentPhase; sessionId: string }
  | { kind: "transcript"; text: string; sessionId: string }
  | { kind: "prompt"; text: string; sessionId: string }
  | { kind: "delta"; text: string; sessionId: string }
  | { kind: "answer"; text: string; sessionId: string }
  | { kind: "error"; message: string; sessionId: string }
  | { kind: "cancelled"; sessionId: string };

所有事件必须带 sessionId，前端丢弃旧 session 的延迟事件。

前端

新增页面/组件：

• VoiceCodingAgentPanel.tsx
• VoiceCodingAgentSettings.tsx
• 设置页新增分组：“语音调用代码 Agent”
• provider 设置页新增分组：“语音润色大语言模型”

面板展示：

• phase badge
• raw ASR transcript collapsible block
• polished prompt collapsible block
• streaming markdown answer
• stop button
• copy answer button
• copy prompt button
• open settings button
• error banner

设置项：

• 启用 Voice Coding Agent
• 快捷键录制器
• Agent provider：Claude Code CLI / OpenCode CLI
• Agent executable path
• 工作目录选择
• model
• fallback model
• permission mode
• timeout
• 是否先语音润色
• 语音润色模型模式：系统默认 / 自定义
• 自定义 base URL
• 自定义 model
• 自定义 API key
• 校验模型按钮

安全与错误处理

• 默认权限为 Plan。
• 未配置 workdir 时不启动 Agent，前端提示用户先选择项目目录。
• 未找到 claude 或 opencode 时显示安装提示。
• API key 永不通过普通 state event 回传。
• 日志中屏蔽 bearer token、API key、account id。
• 子进程必须支持取消和 timeout。
• 快速连续按快捷键时只允许当前 session 生效。
• ASR、润色、Agent 任一阶段失败都要恢复 phase 到 Idle。
• 旧 session 的 late event 必须被丢弃。
• 历史记录只保存用户允许保存的 raw transcript、polished prompt、answer、provider id、model、时间戳，不保存 secret。

测试计划

Rust：

• preferences 默认值和 serde 兼容测试。
• hotkey collision 测试，覆盖所有已有快捷键。
• voice polish custom provider 精确读取 provider id，不修改 active LLM。
• Claude Code CLI args 构造测试。
• stream-json parser 测试。
• timeout kill 子进程测试。
• cancel kill 子进程测试。
• session id guard 测试。
• 空 ASR 文本测试。
• Agent process exit 非 0 测试。

Frontend：

• UserPreferences 类型同步测试。
• settings 初始渲染测试。
• system default/custom voice polish 切换测试。
• API key redacted 显示测试。
• panel stream delta 合并测试。
• stale session event 丢弃测试。
• error banner 和 phase reset 测试。

手动验收：

• 普通听写热键仍可录音、润色、插入。
• Selection Ask QA 仍可打开、录音、返回回答。
• Voice Coding Agent 关闭时快捷键无动作。
• Voice Coding Agent 启用但未配置 workdir 时给出设置提示。
• 使用系统默认语音润色模型能完成一次完整流程。
• 使用自定义强模型能完成一次完整流程。
• Claude Code CLI 不存在时给出可理解错误。
• Claude Code 输出能流式显示。
• 取消运行能终止子进程。
• 超时能终止子进程。
• 权限模式默认为计划/只读，不默认修改文件。
• 切换到 OpenCode provider 后能走同一 UI 与事件协议。

验收标准

• 用户可以在前端配置“语音润色大语言模型”，支持系统默认和自定义强模型。
• 用户可以配置 Voice Coding Agent 的快捷键、provider、模型、工作目录、权限模式。
• 触发快捷键后，ASR 内容能发送给 Claude Code CLI。
• Claude Code 处理结果能返回前端并流式展示。
• OpenCode provider 作为开源优先方案接入同一 provider trait。
• 功能不破坏普通听写、翻译、Selection Ask QA。
• 所有 secret 仍由 OS vault 保存，不进入前端事件和历史。
• 默认权限不会修改用户项目文件。