语音桌面应用本地部署人工智能音频【免费下载链接】hexLocal voice dictation for mac, windows and linux项目地址https://gitcode.com/GitHub_Trending/hex19/hex点击查看免费下载Hex 是一款本地优先的语音听写工具语音转写在本机完成而 Voice Action 与 Modes 的文本润色则交给独立的 OpenCode V2 CLI 处理。2.0.17 这个补丁版本没有引入新界面而是集中修复了 Hex 与 OpenCode 之间那条最脆弱的链路能不能找到 CLI、能不能把请求发到正确的目录、以及在出错时能不能干净地收场。本文以发布说明 docs/releases/2.0.17.md 为骨架结合 src/dictation_processor.rs 的实际实现与测试把这三点背后的机制讲透。2.0.17 到底改了什么发布说明只有三条但每一条都对应一处具体的工程约束发布说明中的变更具体含义对应实现位置将有界 OpenCode 发现扩展到 pnpm 11、NVM、fnm、nodenv 安装且不启动 shell、不扫描整个文件系统在固定候选目录列表中补充 Node 生态的全局 bin 目录与版本管理器目录全部通过直接文件系统调用完成src/dictation_processor.rs正确编码隔离的 OpenCode 工作区并在安装位置移动或 OpenCode 启动瞬时失败时恢复工作区路径经规范化与百分号编码后写入x-opencode-directory请求头发现结论按可执行文件指纹缓存文件变化即失效对 Model unavailable 错误做一次限时重试src/dictation_processor.rs、src/dictation_processor.rs限制 OpenCode 子进程输出并在取消或超时时终止完整进程组避免后代进程拖住听写处理输出上限 16 MiB子进程放入独立进程组结束时对整个组发SIGKILL再 join 读取线程src/dictation_processor.rs理解这三条的前提是弄清 Hex 与 OpenCode 的关系docs/opencode-compatibility.md 明确写道Hex 不捆绑、不锁定 CLI 版本也不接管 OpenCode 的服务生命周期只是发现一个已经装好的opencode2并通过opencode2 api使用 OpenCode 自己的服务发现机制。因此对方装在哪里这件事天然是不确定的2.0.17 的三条改动本质上都是在为这种不确定性兜底。GUI 应用的发现难题为什么需要一份候选目录清单从 macOS 的 Finder 或 Dock 启动的 Hex继承的是 launchd 的PATH其中通常只有/usr/bin:/bin:/usr/sbin:/sbin这类系统目录用户通过 npm、pnpm、Homebrew 或版本管理器安装的 CLI 一律不在其中。直接调用Command::new(opencode2)在这种环境下必然失败。Hex 的解决办法不是去启动一个登录 shellsh -lc、zsh -ic之类来借用用户的交互式环境因为那样会引入启动延迟、shell 配置文件副作用甚至在用户 rc 文件报错时污染 stderr。它改为枚举已知的安装位置并直接检查文件整个过程中没有任何 shell 参与。核心常量如下const OPENCODE_BINARY_NAMES: [str; 2] [opencode2, opencode]; const OPENCODE_PROBE_DEADLINE: Duration Duration::from_secs(10); const HOME_INSTALL_DIRECTORIES: [str; 14] [ .opencode/bin, .vite-plus/bin, .bun/bin, Library/pnpm, Library/pnpm/bin, .yarn/bin, .config/yarn/global/node_modules/.bin, .npm-global/bin, .local/bin, bin, .volta/bin, .asdf/shims, .local/share/mise/shims, .nodenv/shims, ];这里有两个值得注意的细节。第一Library/pnpm与Library/pnpm/bin同时出现在列表中正是 2.0.17 对 pnpm 11 的适配随着 pnpm 版本演进全局 bin 目录可能落在 pnpm home 根下也可能落在其bin子目录下两者都检查可以让不同安装方式都命中。第二.nodenv/shims列在普通家目录清单中因为它本质上是一个 shim 目录不需要像 NVM、fnm 那样遍历多版本。搜索顺序与覆盖优先级opencode_candidates决定了候选路径的先后path_candidates // 继承的 PATH .chain(home_candidates) // 上表 14 个家目录位置 .chain(version_manager_candidates(home, name)) // NVM / fnm .chain([/opt/homebrew/bin, /usr/local/bin]) // Homebrew 收尾顺序并非无关紧要。find_opencode_executable会先遍历名为opencode2的所有候选全部落空后才开始考虑opencodefor name in OPENCODE_BINARY_NAMES { for candidate in opencode_candidates(name, path, home, current_directory) { if !is_executable(candidate) { continue; } if name opencode2 || is_v2(candidate) { return OpenCodeInstall::Ready(candidate); } found_v1 true; } }也就是说任何一个位置的opencode2都优先于任何位置的opencode而opencode这个名字必须证明自己是 V2才会被采用。这条规则由测试opencode2_is_preferred_and_only_a_v2_opencode_is_accepted覆盖即使某个opencode在搜索序上更靠前只要新出现的opencode2被创建发现结果就会切换。最终结果被归纳为三种状态pub(crate) enum OpenCodeInstall { Ready(PathBuf), // 一个 V2 CLIopencode2或已证实为 V2 的 opencode V1Only, // 只有 V1 的 opencodeHex 永不运行 Missing, }这两种失败状态在 UI 上分别对应不同的提示与不同的后续动作逻辑集中在 src/opencode_catalog.rsMissing给出Requires OpenCodeV1Only给出Requires OpenCode V2并引导安装 V2。相关文案测试包括opencode_missing_copy_offers_setup_without_an_error和opencode_v1_copy_asks_for_v2_with_setup。节点版本管理器有界扫描而不是全盘搜索真正容易失控的是版本管理器。NVM 和 fnm 会为每个 Node 版本创建独立目录路径里带着版本号无法硬编码。2.0.17 的做法是只读已知根的下一层并且限制条目数量。let roots [ (home.join(.nvm/versions/node), bin), (home.join(Library/Application Support/fnm/node-versions), installation/bin), (home.join(.local/share/fnm/node-versions), installation/bin), (home.join(.fnm/node-versions), installation/bin), ]; roots .into_iter() .flat_map(|(root, bin)| { fs::read_dir(root) .into_iter() .flatten() .flatten() .take(64) .map(move |entry| entry.path().join(bin).join(name)) }) .collect()三点约束在这里同时生效read_dir失败时通过flatten()静默跳过版本管理器没装就只是没有候选take(64)把每个根的扫描条目上限固定为 64避免异常目录例如误把大量文件放进版本目录导致回退到线性扫描槽位各不相同NVM 是version/binfnm 各平台可能是version/installation/bin也可能是version/bin这是同一工具在不同平台布局差异的如实反映。version_manager_discovery_is_bounded_to_known_roots用一个临时的.nvm/versions/node/v24.4.1/bin/opencode2验证了这条链路传入的PATH为None唯一能命中的就是版本管理器目录。这与发布说明里without launching a shell or searching the wider filesystem完全对应——既没有 shell 参与也没有调用which/locate去扫盘。显式覆盖与相对路径的陷阱HEX_OPENCODE_CLI是给开发和排查用的显式覆盖它的语义是信任并直接使用if let Some(configured) configured { return OpenCodeInstall::Ready(absolute_path(configured, current_directory)); }注意absolute_path的调用。覆盖值允许是相对路径但 OpenCode 子进程后续会切换工作目录到 Hex 的隔离工作区见下一节因此必须在切换之前把相对路径解析成绝对路径否则同一个配置在不同调用点会指向不同文件。测试configured_relative_executable_is_resolved_before_the_workspace_changes正是为此存在传入bin/opencode2与/tmp/hex-launch作为当前目录期望得到/tmp/hex-launch/bin/opencode2并且断言覆盖路径不会触发版本探测。隔离工作区为什么必须编码目录Hex 不希望 OpenCode 在用户的项目目录里执行也不希望把上下文写进用户自己的 OpenCode 工作区因此为它准备了一个固定位置pub fn opencode_workspace() - ResultPathBuf { Ok(support_dir()?.join(opencode)) }support_dir()遵循平台数据目录约定并允许用HEX_APPLICATION_SUPPORT_DIR覆盖在 macOS 上通常是~/Library/Application Support/hex/opencodeHex Test.app会使用独立的hex-test目录以免与已安装版本互相污染见 src/app_paths.rs。工作区路径要同时出现在两个地方curl的当前目录以及x-opencode-directory请求头。二者的处理并不相同fs::create_dir_all(workspace)?; let workspace workspace.canonicalize()?; // 解析符号链接、去掉 .. let directory workspace.to_str() .ok_or_else(|| eyre!(OpenCode workspace path is not valid UTF-8))?; command.current_dir(workspace); Some(format!(x-opencode-directory:{}, encode_uri_component(directory)))canonicalize先做规范化很关键macOS 上~/Library与/Users/name/Library可能通过符号链接互相指向若把未规范化的路径放进请求头OpenCode 侧会认为请求来自另一个目录工作区隔离就失效了。随后encode_uri_component做的是比 RFC 3986 更保守的编码——只保留 ASCII 字母数字其余字节一律%XXif byte.is_ascii_alphanumeric() { encoded.push(char::from(byte)); } else { encoded.push(%); encoded.push(char::from(b0123456789ABCDEF[(byte 4) as usize])); encoded.push(char::from(b0123456789ABCDEF[(byte 0x0f) as usize])); }这段实现直接按字节处理因此 UTF-8 多字节字符会被逐字节百分号编码天然避免了对非 ASCII 路径的错误截断。测试catalog_http_decodes_large_responses_with_private_auth_and_workspace_scope使用了一个刻意刁难的目录名scope %2F café包含空格、%、/和一个带重音的字符并断言command.get_current_dir()等于规范化后的工作区请求头匹配x-opencode-directory:百分号编码后的规范化路径任何参数中都不出现明文密码fixture-password也不出现其 Base64 形式。最后一点来自凭据处理方式认证信息通过curl --config -从 stdin 传入而不是命令行参数或临时文件同时用--noproxy *、--proxy 、--disable关闭用户 curlrc、代理与重定向并用--proto http限定协议。这些限制保证了这个本地服务调用不会被环境配置意外改道。恢复路径安装移动与启动瞬时失败发布说明第二条的后半句是两个不同的恢复场景实现上也分属两层。安装位置移动指纹缓存自动失效版本探测要依次尝试--version和api get /api/info最坏情况是一次完整往返。若每次检查 UI 或按热键都跑一遍会把延迟直接叠到听写体验上。Hex 因此缓存结论type OpenCodeFingerprint (Optionstd::time::SystemTime, u64); fn opencode_fingerprint(executable: Path) - OptionOpenCodeFingerprint { let metadata std::fs::metadata(executable).ok()?; Some((metadata.modified().ok(), metadata.len())) }缓存键是可执行文件路径缓存值包含(修改时间, 文件长度)的指纹和探测结论。只有当指纹完全一致时才命中缓存因此用户npm i -g升级了 OpenCodemtime 变化旧的 V1/V2 判定立即作废用户切换了 Node 版本NVM 路径中的版本号变化路径本身不同不会误用旧结论可执行文件被删除或被目录替换metadata失败缓存自然不命中。还有一条刻意的策略只有确定的答案才写入缓存。probe_opencode_generation返回OptionboolSome(false)会记录一条ignoring OpenCode V1的 info 日志超时得到的None则不入缓存下次目录检查会重新探测。这与发布说明中recovers when an installation moves直接对应——发现流程没有记住坏结果的粘性。启动瞬时失败一次限时重试OpenCode 的服务由它自己的 CLI 启动首次调用时可能出现服务已在起来、但模型尚未就绪的窗口期。Hex 对这个具体错误做一次重试fn retryable_generation_error(message: str) - bool { message.starts_with(Model unavailable:) }重试逻辑在generate_single_model中最多两轮且等待过程共享同一个截止时间与取消标志for attempt in 0..2 { let remaining remaining_generation_deadline(started, deadline)?; match post(data, remaining, cancelled)? { Response::Success { data } return Ok(data.text), Response::Error { message } if attempt 0 retryable_generation_error(message) { wait_for_generation_retry(started, deadline, cancelled)?; } Response::Error { message } { return Err(eyre!(OpenCode generation failed: {message})); } } }wait_for_generation_retry以 20 ms 为间隔轮询Duration::from_millis(1_500)每一轮都检查取消标志与总截止时间。这样即使 OpenCode 一直没起来也不会把一次听写卡住超过既定预算而generation_retry_wait_observes_cancellation验证了在 30 秒预算下取消会立即返回错误而不是继续等待。值得注意的是重试只针对 Model unavailable: 这一前缀。像Provider request failed或processor returned empty text这类错误不会触发重试retryable_generation_error的边界由单元测试断言避免把真实的上游故障伪装成再试一次就好。子进程边界输出上限与进程组终止第三条是三个改动中最容易被低估的一条如果不限制输出、不终止整个进程组一个不听话的子进程可以让听写线程永久阻塞。输出上限const MAX_OPENCODE_OUTPUT_BYTES: u64 16 * 1024 * 1024; fn read_bounded_output(mut output: impl Read, max_bytes: u64) - ResultVecu8 { let mut bytes Vec::new(); output.by_ref() .take(max_bytes 1) .read_to_end(mut bytes)?; if bytes.len() as u64 max_bytes { Err(eyre!(opencode2 output exceeded {max_bytes} bytes)) } else { Ok(bytes) } }take(max_bytes 1)是多读一个字节的经典写法既能把合法输出完整读完又能在超限时立刻判定而不是先分配一大块内存再溢出。16 MiB 的上限对模型目录响应足够宽裕——测试里特意构造了包含 2048 个模型的响应确认超过 256 KiB 的正常响应可以完整解码。进程组真正的问题是 Unix 上杀掉父进程不等于杀掉子进程。OpenCode CLI 自己可能会拉起服务或子进程若只对父进程kill()后代仍持有 stdout/stderr 管道写端读取线程就永远等不到 EOF。Hex 的应对是把子进程放进独立进程组出错时对整组发信号let mut child command .process_group(0) // 新进程组组长 PID 即子进程 PID .stdin(/* ... */) .stdout(Stdio::piped()) .stderr(Stdio::piped()) .spawn()?; // ... 轮询 try_wait检查 cancelled 与 deadline ... match outcome { Ok(_) kill_process_group(child.id()), // 成功也清场 Err(_) terminate_process_group(mut child), // 取消或超时 } let stdout stdout.join(); let stderr stderr.join();fn kill_process_group(pid: u32) { // run_command 创建的进程组 ID 就是子进程 PID unsafe { libc::killpg(pid as libc::pid_t, libc::SIGKILL); } } fn terminate_process_group(child: mut Child) { kill_process_group(child.id()); let _ child.kill(); let _ child.wait(); }两个细节体现了工程上的克制。其一成功路径也调用了kill_process_group主进程正常退出后如果它留下了持有管道的后代同样会阻塞 join所以清场不是错误路径专属。其二先终止、后join的顺序被显式注释说明——在 join 管道之前拆掉被中止的子进程让阻塞的读取方与输入写入方看到 EOF而不是把截止时间拖长。等待循环本身也是短周期轮询取消检查先于超时检查二者都通过AtomicBool与Instant实现loop { match child.try_wait() { Ok(Some(status)) break Ok(status), Ok(None) {} Err(error) break Err(error)?, } if cancelled.load(Ordering::Acquire) { break Err(eyre!(opencode2 {operation} was cancelled)); } if started.elapsed() deadline { break Err(eyre!(opencode2 {operation} exceeded {} seconds, deadline.as_secs())); } thread::sleep(Duration::from_millis(20)); }对应测试很直观cancelled_generation_process_is_killed_promptly启动一个会持续数秒的命令并预先置取消标志断言 1 秒内返回was cancelleddescendant_holding_output_cannot_outlive_the_deadline让子进程持有输出管道在 500 ms 预算下断言整体 2 秒内结束——如果只杀父进程第二个测试会直接挂住。Windows 走另一条等价路径src/dictation_processor.rs 中的cli模块通过 Job Object 管理子进程树terminate会把整个 job 结束而不是逐个 PID。这与 Unix 的killpg表达的是同一个约束取消必须覆盖整棵进程树。与其他版本的衔接与验证方式把 2.0.17 放到版本序列里看它的定位会更清楚更早的发布说明例如 docs/releases/2.1.9.md补上了~/.opencode/bin/opencode2这类官方安装位置docs/releases/2.1.23.md 又补上 Vite Plus2.0.17 则覆盖了 Node 生态的另一半——包管理器与版本管理器。后续 docs/features/voice-action.md 中给出的发现流程树可以看作这条演进路线收敛后的完整形态HEX_OPENCODE_CLI set - Use it as is Otherwise PATH, home install folders, Node version managers, Homebrew ├── Any opencode2 - Use it // beats every opencode ├── Else an opencode whose --version is 2.x - Use it ├── Else an opencode printing 0.0.0-… that answers api get /api/info - Use it ├── Only V1 opencode - Requires OpenCode V2 // never run for generation └── Nothing - Requires OpenCode // both rechecked every 60 s如果你要自行验证这些行为仓库里可用的抓手是这些不带外部依赖的单元测试它们用临时可执行脚本而不是真实安装的 CLI因此可离线重复运行standard_install_location_finds_opencode_outside_the_gui_path在PATH/usr/bin:/bin下仍能命中.opencode/bin、.vite-plus/bin、Library/pnpm/binversion_manager_discovery_is_bounded_to_known_rootsNVM 目录发现opencode2_is_preferred_and_only_a_v2_opencode_is_acceptedopencode2优先级与 V1 拒绝release_versions_tell_the_generations_apartopencode v2.2.0、2.10.1、1.19.5、0.0.0-snapshot-pnpm-…等版本字符串的判定catalog_http_decodes_large_responses_with_private_auth_and_workspace_scope工作区编码、凭据不上命令行、大响应解码configured_relative_executable_is_resolved_before_the_workspace_changes覆盖路径的早期绝对化cancelled_generation_process_is_killed_promptly与descendant_holding_output_cannot_outlive_the_deadline取消与后代进程的时限保证。需要说明的是这些测试验证的是 Hex 侧的契约与边界并不等同于对某个具体 OpenCode 版本的provider 端到端验证docs/opencode-compatibility.md 明确要求新的带 provider 的验证必须自行记录 CLI 与服务端的版本号。小结2.0.17 是一条典型的发布说明三行、实现牵一发动全身的补丁。把它的三条改动串起来可以归纳成三个可复用的工程原则GUI 应用不能假设PATH可用也不该通过启动登录 shell 去借环境枚举已知安装位置 直接文件系统检查才是有界且可预测的做法对版本管理器这种层级不固定的目录必须限定根与条目数。工作区隔离依赖路径的一致性先create_dir_all、再canonicalize、再做逐字节百分号编码三者缺一都会让x-opencode-directory与curl实际的工作目录产生偏差而缓存探测结论时必须绑定文件指纹才能让安装被移动/升级这种变化自动生效。每个外部子进程都需要一个可收回的边界输出上限防止内存与阻塞双失控独立进程组 SIGKILL保证取消能覆盖后代而先终止再 join的顺序决定了截止时间是否真的有效。这些机制集中在 src/dictation_processor.rs 一个文件里若你想继续深入建议按发现 → 工作区 → 生成 → 进程回收的顺序阅读并配合 src/opencode_catalog.rs 观察发现结论如何影响 Voice Action 与 Modes 的可用性提示。赞分享语音桌面应用本地部署人工智能音频【免费下载链接】hexLocal voice dictation for mac, windows and linux项目地址https://gitcode.com/GitHub_Trending/hex19/hex点击查看免费下载相关推荐Astrid 原生进程沙箱与工作区边界astrid-workspace 深入解析Astrid 原生进程沙箱与工作区边界astrid workspace 深入解析 Astrid 是一套可移植、以能力capability安全为核心的组合式OpenCode深度解析AI编程助手如何重塑开发工作流OpenCode深度解析AI编程助手如何重塑开发工作流 你是否曾因复杂的代码重构而头疼是否在项目协作中因沟通不畅而延误进度OpenCode作为一款开源AI人工智能AI Agent代码智能体AI 应用开发工具CLIqwen-code ACP Skill 管理模块深度解析源码获取、原子安装与安全边界qwen code ACP Skill 管理模块深度解析源码获取、原子安装与安全边界 导读 本文聚焦 qwen code一个运行在终端中的开源 AI 编码代人工智能AI Agent代码智能体CLIQwen上一篇AMD Phi-4-mini-instruct_rai_1.8.0_npu_16K 完整指南Ryzen AI NPU 本地大模型是什么为什么值得关注下一篇运行DeepSeek-V4-Flash-GGUF常见问题与解决方案从OOM到模板异常完整排错清单创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
