在另一个桌面应用中内置 Hex 转录¶

状态： 更新于 2026-09-01。@kitlangton/hex@0.3.0 已发布，本地 Electron 从录制到转录的测试已在 Apple Silicon macOS 上运行通过。原生辅助程序包尚未发布；当前嵌入仍需要显式的辅助命令。下面的其余原生分发工作是一项计划，而非已具备签名干净机器就绪性的声明。

读者与目标： 维护者应能与桌面消费方就一个集成里程碑达成一致，而无需承诺尚不存在的开箱即用原生分发。

交付一个运行时，而不是另一个需要安装的应用¶

桌面消费方需要本地转录，而无需其用户安装 Hex 或访问 Hex 设置。移动端集成不在本计划范围内。Hex 仍然是完整的听写应用。嵌入方案暴露的是可复用的模型和推理机制，而不是桌面 UI、快捷键或粘贴行为。

在消费方应用内部内置一个原生辅助程序，通过一个小型 SDK 控制。消费方应用负责录音、用户同意、UI 和偏好设置。辅助程序负责模型准备和本地推理，并随宿主退出。它是一个子进程，而不是进程内库或独立运行的守护进程。

Their desktop app
|-- Microphone permission, recording, and recording UI  // host-owned
|-- Model/language preference and transcript insertion // host-owned
`-- Hex SDK -> bundled native helper                   // host-owned lifetime
    |-- Model download, verification, and preparation
    `-- Completed audio -> raw transcript

成功意味着一个已签名的消费方应用能够在干净的受支持 Mac 上完成首次运行的模型设置和本地转录，而无需安装 Hex、克隆仓库、配置开发者工具链或手动设置可执行文件路径。

从一个受支持的消费方和平台开始¶

以下为规划默认值，并非消费方的承诺：

如果某个关键需求与这些默认值冲突，应在实现前修订范围。Windows/Linux 嵌入、沙盒化分发和实时部分转录是独立的工程工作，而不是打包勾选项。

复用已实现的核心，但验证分发声明¶

SDK 实现在 PR #57 中合并，PR #58 发布了版本 0.3.0。2026-08-31 的验证涵盖：

• SDK 类型检查、45 个测试、锁定的原生 release 构建，以及通过两个入口点对打包包进行消费，包括在不使用 Effect 的情况下使用 Promise。
• 一个本地 T3 Code 适配器和共享语音控制器：36 个测试，包括两次真实原生转录、已启动辅助程序的复用，以及已验证的辅助程序退出。
• 一个独立的、未提交的 Electron 实验室，使用已发布的 npm 包：22 个单元测试，以及全窗口录制、WAV 编码、IPC、原生推理、草稿插入、取消、过期草稿保护和关闭检查。自动录制使用合成麦克风音频；交互式麦克风使用也已在本地得到演练。

这些实验使用隔离的模型存储和显式提供的原生辅助程序。它们不是 T3 已发布的功能，也不是已签名、经过隔离、干净机器分发的证明。独立的实验室和 T3 原型仍保留在本地，不是仓库工件或公开集成承诺。

随附的服务规范记录了现有协议。本计划界定了交付范围与就绪标准；请在实施过程中同步修订过时的规范与 README 中的声明，而不是把它们视为已经实现的功能。

在主应用中保留录制与偏好设置¶

使用已发布的就绪转写器交互方式，而不是自创桌面设置控制界面。目前必须提供显式命令。省略该命令是原生打包的目标，而非当前干净安装即可正常工作的承诺。

import { create } from "@kitlangton/hex"

const transcriber = await create({
  command: ["/path/to/hex-service", "service", "--embedded"],
  model: "parakeet_unified_en",
  language: "en",
  onProgress: renderModelProgress,
})
try {
  // Host captures and encodes PCM WAV. No capture or paste occurs in the helper.
  const result = await transcriber.transcribe(wav, { signal })
  insertIntoHostInput(result.transcript)
} finally {
  await transcriber.close()
}

为主应用转写功能的整个生命周期保留一个辅助进程，而不是每次录音都新建一个。绑定模型的 create() 明确允许网络/模型加载工作；transcribe() 绝不静默下载。已安装但处于冷状态的模型可能需要重新加载。主应用仅在创建成功后保存其模型偏好。就绪转写器的进行中取消会在取消落定前关闭其辅助进程；下一次录音需要新的转写器。Effect 通过作用域终结器负责清理。清理失败仍然可见，包括启动失败。

不带模型的底层 create() 仍可用于目录浏览，并通过 client.models.list() 与 client.models.prepare() 进行显式准备。列表的 language 参数影响的是就绪元数据，而非语言过滤；主应用必须检查每个模型所支持的语言。进度仅用于模型准备；转写返回的是最终结果，而不是百分比或部分文本。公开契约请参阅 SDK README。

模型文件可按用户共享；但所选模型、热运行时、认证与推理队列均按辅助进程独立。即使两个主应用复用同一份下载，它们仍可能重复占用 GPU/内存。不要承诺共享热引擎。

原生分发前需满足的保证¶

以下是可分发辅助进程的验收要求。SDK 经过测试的生命周期并不能证明所有现有原生路径都已满足这些要求。

• 从可信的主应用代码直接运行辅助进程。绝不要从 Web 内容引导启动，也不得将 bearer token、可执行文件覆盖参数或任意辅助进程参数暴露给不受信任的渲染器。框架桥接仅接受受限的模型与音频操作，并强制输入/大小限制。
• 仅将经过认证的 HTTP 绑定到 loopback。启动凭据通过管道传递，而非命令行参数、发现文件、日志或渲染器状态。在接受操作之前拒绝协议不匹配。
• 主应用拥有麦克风权限与录音权。辅助进程不得请求麦克风、辅助功能、输入监控、自动化或登录项访问权限。除非其独立的 OS/运行时行为经过显式验证，否则不要将当前不可用的 Apple Speech 运行时纳入内嵌支持目录。
• 仅通过修订安全的存储共享经过验证的模型工件。当前基于文件名的缓存不足以满足独立版本化的辅助进程。保留锁定、取消与原子发布机制，并保持遗留的 Hex 文件不被改动。首个版本不提供模型删除接口。
• 绝不读取或修改 Hex 桌面端的偏好设置、历史记录、剪贴板或采集状态。内嵌诊断不得持久化音频、由音频衍生的张量、转写文本或 token。使用有边界、可供主应用消费的诊断，而不是不受控的共享日志。同时审计继承的诊断环境标志以及正常执行路径。
• 保持音频验证、上传预算、队列与截止时间的有界性。记录实际接受的格式与字节限制；不要把 64 MiB 音频预算描述为总进程内存上限。不存在任意的时长截断，但过大的录音可能收到类型化的资源拒绝。
• 底层请求取消会在检测到的地方抑制结果；原生工作可能在内部继续。就绪的 SDK 转写器则会在取消落定前关闭其辅助进程，除非关机本身失败。主应用收到明确的 busy/cancelled/failure 结果，而不是自动重试或重复提交。即使原生工作不可中断，功能关闭与主应用退出也会限定辅助进程的生命周期。
• 主应用拥有操作截止时间，根据所接受的工作负载设定，并传递中止信号。如果原生工作在取消后停滞，有界的辅助进程关闭与显式重启必须恢复可用性，同时主应用保持打开。绝不要自动重放超时的录音。
• 消费方应用随自身版本发布并更新固定版本的辅助进程。辅助进程不自我更新，也不使用 Sparkle。正常启动无需网络；显式请求的模型准备可能需要网络访问。

这些保证隔离协作的主应用，并拒绝未经认证的本地/Web 请求。bearer token 与仅所有者可读的文件，无法构成针对已经以同一用户身份运行的恶意进程的 OS 沙箱。

在承诺进行提取之前先确立可行性¶

在切片 1 之前，指定 Hex 与消费者集成的负责人，并商定一个 go/no-go 决策门，时间不晚于消费者的依赖决策截止日期。

在提取新二进制之前，先在消费者认可的代表性音频上运行现有的显式命令路径。对照其预期文本记录转录质量、冷/热延迟、内存，以及在受支持的最弱硬件上的行为。商定通过/失败标准和最大片段长度，而不仅仅是“成功转录文本”这一结果。使用已获同意的测试录音；不要提交私人语音或输出。

当前解码器对源帧和归一化样本都有限制。其 16,777,216 帧的上限在 48 kHz 下约为 5.8 分钟，而在 16 kHz 下约为 17.5 分钟，这还未计入其他字节/截止时间限制。测试实际宿主编码和所需的最长片段。如果工作负载不匹配，请明确界定归一化或准入变更的范围；不要承诺无限制录音，也不要默默加入流式处理。

在此决策门选择集成分支：兼容 Node 的宿主使用下文所述的 SDK 和 npm 路径；其他宿主在实现被授权之前，需要宿主适配器和原生产物交付路径。仅一个启动器并不等于该适配器。请包含一项早期的打包/签名可行性探测。

退出条件： 达成一致的范围、负责人、经测量的质量/工作负载适配度，以及带有日期的 go/no-go 决策。如果无法在此决策门证明可行性，应停止或重新谈判，而不是让消费者一直等待。

以四个验收门控切片交付¶

1. 用一位真实消费者验证签名嵌入路径¶

使用已确认的框架和打包流水线，而不是想当然的 Electron 演示。将可行性决策门的音频测试样本和验收标准带入本切片。

基于现有转录代码构建一个专用的辅助可执行文件。仅进行必要的内部拆离，以排除 Rune、Sparkle、Moonshine、录音、热键和桌面操作执行。保持协议与推理实现共享；不要将模块复制到第二个引擎中，也不要创建公开的 Rust/插件框架。无关的原生构建步骤同样需要门控。

将宿主租约监控移到可能阻塞的初始化之前。在签名试点之前选择并证明下载器所有权：使用有界的进程内传输，或使用在辅助进程崩溃和关闭升级时终止下载器子进程的监督机制。仅杀死辅助进程的 PID 是不够的。任何孤儿写入者都不得在锁释放后修改被重试复用的部分文件。

将无条件的桌面日志初始化替换为有界、宿主可消费的嵌入式诊断。定义允许的嵌入环境，禁用原生转储标志（如 TRANSCRIBE_DUMP_DIR），并测试外部转储目标，而不仅仅是 Hex 的支持目录。持久化调试转储不是嵌入功能，即使它是从父环境继承而来的。

检查二进制的动态依赖和资源。在不使用仓库相对路径、Homebrew 库或用户机器上的 Xcode 安装的前提下，打包其运行时所需的一切。确定并测试其最低 OS 版本。锁定 Rust/原生构建、部署目标和可移植 CPU 基线；记录实际生效的 CMake 标志，并防止继承的构建覆盖启用构建者特有的指令。钉住依赖中的 GGML_NATIVE 默认值需要显式处理；严格的 Metal 并不能消除所有 CPU 执行。在最老受支持的 Apple Silicon 代际/OS 以及当前 OS 上验证真实推理。验证现有的静态/嵌入式 Metal 构建，而不是想当然地认为 sidecar dylib 或着色器文件是必需的。

通过消费应用的实际签名、公证、隔离和安装路径来证明制品。遵循仓库中明确的签名团队和公证配置文件要求；不要沿用旧脚本的默认身份假设。从已装订（stapled）的服务应用中提取可执行文件，本身并不能证明提取出的辅助程序或最终宿主应用是可分发的。同时记录上游制品的签名者和最终嵌入代码的签名者。在提取之后以及任何消费者重新签名之后进行验证。重新签名会改变摘要和身份；请在该步骤之前验证上游字节，然后单独验证最终签名的宿主应用。子进程并不天然需要其父进程的团队标识。测试已下载、被隔离的最终消费者应用的正常安装和离线启动。如果最终交付物是一个嵌入可执行文件，则不需要单独的服务 .app。在分发该试点之前，完成试点模型/依赖的许可审查。

退出条件： 在一台干净且受支持的 Apple Silicon Mac 上，已签名的消费者应用能够以自身麦克风身份捕捉音频、准备模型，并在未安装 Hex 的情况下返回真实转录文本。它能在已准备好模型的情况下离线启动。记录在指定硬件上的启动、冷/热转录延迟、二进制大小和内存。除性能外，还要满足商定的质量与工作负载标准；屏幕上出现转录文本并不足够。测量最大可接受的 WAV，以及“活动+候选”模型切换峰值，而不只是短视频或稳态。如果最低硬件无法安全切换，请限制受支持的目录/输入预算；失败时旧模型必须保持可用，同时辅助进程继续存活。

停止条件： 如果签名、框架打包、所需语言或性能未通过试点，则不要扩大接口范围，也不要发布“开箱即用”（turnkey）的声明。

2. 让模型设置在消费者应用内安全且可用¶

在消费者的模型选择器和下载 UI 中使用 models.list() 和 models.prepare()。在 list、prepare 和 transcribe 流程中强制实施嵌入的受支持模型策略，而不仅仅是 UI 过滤；不要缩小共享桌面目录。记录每个受支持的修订版/哈希、架构、语言、许可义务和经过测试的运行时组合。在制品和消费者再分发指南中包含所需原生/模型声明；Hex 的 MIT 许可并不是适用于每个模型或依赖的通用许可。

宿主机将模型/语言选择与 Hex 分开保存。在无需打开 Hex 的情况下，让权限被拒、无网络、磁盘空间不足、下载取消、校验和不匹配、不支持的语言/硬件以及推理繁忙等状态变得可操作。仅在用户明确操作时才选择其他模型，不要静默替换。

在此实现修订安全的共享存储，而不是仅作为测试任务。通过固定摘要处理嵌入产物、部分下载、锁和收据，使得两个 helper 版本无法替换彼此预期的文件。旧版桌面路径保持不变。只有当匹配的旧版文件通过校验并复制到不可变存储中时才可复用；不要重命名或信任其旧收据。考虑临时/重复磁盘占用，并测试失败的采纳过程后两个存储仍可用。Helpers 共享此存储；较旧的桌面构建可保留自己的副本。

在传输、诊断输出、总时长/停滞时间、重定向以及磁盘写满行为中，将下载字节数限制在固定产物大小范围内。如果保留子进程，应使用确定性的可执行文件/配置策略并持续排空有界 stderr；继承的 PATH 或 curl 配置不是该策略。超大/分块响应和慢速传输不得耗尽磁盘，也不得让另一台宿主在本次失败尝试后无法准备。

在后端每个状态下明确取消行为：上传中、排队转写、活动推理、排队准备和候选激活。将取消贯穿准备 worker，并在替换活动模型前进行检查；取消前已提交的操作无需回滚。仅抑制 Promise 结果并不能取消排队的工作。测试实际宿主传输的 FIN/RST 行为；如果断连检测无法提供该契约，则通过兼容的协议/客户端变更添加显式操作取消。

在当前通用的 download-failed/verification-failed/load-failed 代码无法驱动恢复的地方，增加安全的准备错误分类。不要将原始 stderr、本地路径或凭据发送给渲染器。在指定新的客户端/helper 配对行为时，测试与随附 SDK 错误的兼容性。

退出： 首次运行设置、取消/重试、模型切换、应用重启和离线复用均可通过消费端 UI 完成。失败或提交前取消的准备过程保留旧选择和热模型，且 helper 继续存活。强制重启后，旧的已准备产物仍可重新加载。检查支持目录、日志和外部原生转储目标，确认没有桌面设置变更或残留的音频/转写文本/张量。

3. 验证生命周期、资源限制与共存¶

修复过时的冒烟测试脚本，并同时保留 SDK 单元测试和原生集成测试。使用最终的 helper（而不仅仅是假子进程）来执行以下矩阵：

另外，在提取 helper 后，对普通的 Hex 听写、桌面 connect() 捕获以及现有显式命令 SDK 路径进行冒烟测试。这是共享代码；一个成功的 helper 不得使现有应用或已发布的客户端发生回归。

退出标准： 记录可复现的命令、主机/操作系统/模型版本，以及矩阵的通过/失败结果。未运行的测试保持明确的未验证状态。

4. 发布消费者可实际交付的制品¶

根据现有 SDK 发布策略确定平台包名称。保留当前的 @kitlangton/hex 入口点；私有的 @hex-ai/service-darwin-arm64 名称不是公开兼容性承诺。自动解析原生制品；不执行 postinstall，不下载运行时辅助程序，也不需要用户配置路径。缺少可选依赖和不支持的目标必须以可操作的错误失败，而不是触发桌面安装。

确认命名空间所有权和新包的首次发布机制，然后为其可信发布者配置确切的仓库/工作流。现有客户端的发布权限并不授权发布新包。任何引导性发布都需要单独批准；后续发布使用 Changesets。

添加从 macOS 验证到打包的故障关闭交接：以发布提交和包版本为键的不可变制品，并包含摘要、可执行模式和签名检查。当辅助程序缺失、过期或不匹配时，打包必须失败。验证打包并安装的有效负载恰好包含已验证的上游字节和所需声明。Ubuntu 发布作业不得打包空的检出内容，也不得重建未经验证的替代品。

记录一个发布清单，映射客户端版本、原生包版本、原生 Cargo 版本/源代码修订版和协议版本。将客户端精确固定到经过测试的原生包。每次辅助程序变更都会对应一个新的原生包版本；仅辅助程序的发布也会更新客户端的固定版本和 Changeset。在引用它的客户端之前，发布并验证辅助程序的可检索性。如果发布部分失败，使用已验证的现有制品恢复，或发布新版本；绝不替换已发布版本下的字节。

为外部命令和桌面 connect() 配对定义兼容性，而不仅仅是捆绑配对。当前客户端会拒绝未知的模型 ID，因此添加目录条目并不会自动实现 API-2 兼容。不要在未提供版本化响应或协议过渡的情况下，向受支持的旧客户端引入新的封闭枚举值/响应形状。测试基线和新的客户端/辅助程序/桌面配对，以及刻意的失配拒绝。除非具体的兼容性变更需要，否则不需要新的协商端点。

主机打包指南涵盖可执行文件放置、权限、嵌套签名，以及相关的框架特定捆绑（如 Electron ASAR）。在其各自的信任阶段验证上游制品和消费者签名后的制品。

在任何已批准的引导之后，使用配置好的 SDK Changesets 工作流。为面向用户的客户端变更添加 Changesets，检查打包的 tarball，并将它们安装到此工作区之外的干净消费者环境中。验证 Promise 和 Effect 导入、捆绑辅助程序的启动，以及现有桌面连接行为。后续发布不要直接用 npm publish 替代配置的发布命令。

最低限度的干净消费者发布矩阵如下：

退出标准： 首位消费者使用发布制品（而非工作区链接或命令覆盖）复现已签名的试点。发布支持矩阵、OS 最低版本、已测试模型、观察到的资源/延迟测量值、已知限制和恢复行为。只有在这之后，才可将嵌入描述为对该矩阵普遍可用。

推迟不阻碍此集成的功能¶

• 此桌面嵌入计划中不包含 iOS 工作。
• 在平台特定的试点之前，不承诺支持 Windows、Linux 或 Intel Mac。
• 不提供部分转录、流式音频协议、说话人分离或长格式可恢复任务，除非消费者将其作为启动要求。
• 不提供共享守护进程、服务选举、跨主机推理调度器或热模型代理。
• 辅助程序中不提供 Hex 桌面设置界面、UI 嵌入、全局热键、粘贴、重写、历史记录或命令执行。
• 在实际的第二个适配器出现之前，不创建仅浏览器引导、公开 Rust ABI、插件框架或通用跨平台架构。
• 不提供模型删除、静默云回退、遥测或辅助程序自更新器。

用证据而非现有文档来承诺可用性¶

已发布的 SDK 支持范围限定的集成试点，而非跨平台原生分发的承诺。与消费者确认部署要求；实现负责人在此处或链接的测试报告中记录每个切片的证据。公开发布仍需明确批准。

剩余的决策门很小：消费者的打包分发、所需平台/语言、仅最终文本与实时文本，以及决策截止日期。如果 Apple Silicon 的仅最终文本试点满足这些需求，那就完成此运行时，而不是启动新的推理引擎。如果不满足，请尽早暴露不匹配之处，以便消费者无需等待未定义的 SDK 就能选择其他依赖。

对抗性审查记录¶

四位独立审查者于 2026-08-31 检查了草案：

三位工程评审员重新阅读了原始计划，并在其原始范围内报告没有剩余的高/中等级差距。这是计划级结果，而非实施批准或运行时安全证明。他们的评审是静态的；该阶段的验证涵盖 SDK 类型检查、28 项测试，以及文档差异/链接检查。后续实施和本地验证记录在上方基线和 PR #57 中。原生分发验收门仍然开放；本地测试成功并不能满足消费者的部署要求。