最近遇到一个很有意思的开源项目Kuma Voice。它的定位很简单但足够戳中很多 Apple Watch 用户的痛点——一个开源的 Apple Watch 语音助手不需要 iPhone。这里说的不需要 iPhone不是说手表能脱离手机完成一次性的初始配对而是说在手表日常运行的过程中不再需要手机作为计算节点、中转站或者数据来源。如果你动手做过 watchOS 开发就会明白这个差异到底意味着什么。这篇文章不准备只贴项目介绍。我想以 Kuma Voice 为切入点把独立 watchOS 语音助手这条技术链路完整拆一遍从 Watch-only App 的工程架构到语音识别权限、麦克风采集、意图解析、TTS 回复再到真机调试和常见坑。即使你完全不打算用这个项目看完也能对齐一套关于 watchOS 独立应用的实现思路。先给一个明确判断Kuma Voice 这类项目真正的价值不在多了一个语音助手而在它证明了第三方开发者可以在不借助 iPhone 的情况下用系统框架在手表上跑通一套语音交互链路。这是 watchOS 平台开放能力的一次实践展示。1. 这篇文章真正要解决的问题很多人对 Apple Watch 语音助手的认知停留在Siri 必须靠 iPhone这个阶段。实际情况是从 watchOS 版本迭代开始Apple Watch 已经支持独立的应用运行和网络连接。只要手表具备 Wi-Fi 或蜂窝网络能力应用完全可以在没有 iPhone 在场的情况下访问网络、采集音频、调用系统能力。但事情没这么简单。真正做过 watchOS 独立应用的人都知道这套链路里有几个很现实的问题第一权限模型比 iOS 更敏感。语音识别和麦克风权限需要明确的用途声明没有配置 Info.plist应用会在启动时静默失败而不是弹出权限框。第二音频会话管理在手表上更脆弱。watchOS 的资源限制比 iOS 严格长时间挂着 AVAudioEngine 会导致系统杀掉进程。第三后台执行能力极其有限。iOS 可以靠 Background Task 做很多事情watchOS 上想后台定时提醒需要另一套 API。如果你在网上搜索 Kuma Voice、Apple Watch、voice assistant 这些关键词会看到大量关于手表助手是否真的脱离手机的讨论。但这些讨论大多停留在概念层面。这篇文章想解决的是把这套概念落到工程层面你到底需要哪些权限代码应该怎么写验证要怎么做失败了怎么排读完你至少能获得四样东西理解不需要 iPhone在 watchOS 工程上的准确含义掌握 Speech framework 在 watchOS 上的最小可用写法知道一个语音助手的意图解析和回复链路怎么组织拿到一份可直接套用的常见问题排查清单。2. 不需要 iPhone到底意味着什么Watch-only 应用的技术基础要真正理解 Kuma Voice先要重新理解 watchOS 应用的发展历史。早期的 watchOS 应用并不是真正独立的应用。第三方应用被打包成一个 extension挂在配套 iOS 应用内部手表只是 iOS 应用的一个展示层。这意味着你打开手表应用实际上是在间接使用手机的网络、数据和计算能力。这就是不依赖 iPhone和依赖 iPhone这个问题的根源——旧架构下手表根本不是一个独立计算设备。转折点出现在 watchOS 6。从那个版本起Apple 正式允许开发者创建Watch-only App也就是不再需要 iOS companion app 的独立手表应用。这个变化是 Kuma Voice 这类项目存在的制度前提。但必须澄清一个容易误解的点Apple Watch 的初始激活和配对目前仍然需要一部 iPhone。手表第一次开机、写入账号、同步系统设置这些环节逃不掉 iPhone。Kuma Voice 标题里的no iPhone needed说的是运行阶段不是激活阶段。具体到工程上运行阶段不需要 iPhone意味着三件事网络独立手表通过 Wi-Fi 或蜂窝网络直接发起 URLSession 请求不需要经过 iPhone 转发数据独立应用的设置、缓存、历史记录都存储在手表本地不走 iPhone 同步也不依赖 WCSession计算独立语音识别、意图判断、回复生成要么在手表端完成要么由手表直接请求云端服务完成。还有一个用户容易忽略的技术细节Apple Watch 必须和 iPhone 保持配对关系但配对之后只要手表能连上网络它就可以独立运行大多数功能。蜂窝版手表在这方面体验最好Wi-Fi 版在离开手机但是连着已知 Wi-Fi 时也能工作只是需要网络环境配合。所以Kuma Voice 的不需要 iPhone本质上是一个架构选择项目按 Watch-only App 的方式设计和部署所有能力都以手表为边界展开。这也直接影响了它的代码组织方式。如果某个环节还需要借助 iPhone 的计算能力那标题就不会这么写了。3. Kuma Voice 的核心模块与技术选型从项目标题和同类开源助手的一般结构来看一个不依赖 iPhone 的 watchOS 语音助手至少需要四层能力。我把它们拆开顺便给出每层可选的系统 API。模块职责watchOS 上可用的能力常见技术选型音频采集从手表麦克风采集用户语音AVAudioEngine、AVAudioSessionSpeech framework 内置的录音 pipeline语音识别将音频转成文字Speech framework 的 SFSpeechRecognizer系统识别服务本地或远端意图解析从文字中拿出用户想做的事自研规则 / 本地模型 / 云端 LLM小型关键词规则或后端 LLM API动作执行执行具体操作Timer、WKInterfaceDevice、网络请求系统 API URLSession语音回复把结果读给用户AVSpeechSynthesizer系统 TTS中文用 zh-CN 语音这套链路和我们在手机上做的语音助手没有本质区别唯一的差异在于硬件约束手表屏幕小、交互入口少、CPU 和内存更紧张、电池有限。所以 Kuma Voice 这类项目在技术选型上通常会倾向于两个原则第一个原则是能少做就少做。语音识别尽量交给系统 Speech framework而不是嵌套一个几百 MB 的离线识别引擎。watchOS 应用的包体积限制很严格嵌入大模型引擎不现实。第二个原则是云端分担理解压力。如果项目接了云端大模型做意图解析那么手表端通常只负责录音、识别和播放回复语义理解放在服务端。这样手表端代码量会小很多。从开源项目的性质来看Kuma Voice 还有一个隐性优点可审计。用户能直接看源码来确认音频是否被上传、上传到哪里、本地保存了什么数据。这个优势在语音类应用里非常关键因为语音天然是敏感信息。如果你打算二次开发也可以从源码层面评估它的隐私边界而不是只听官方说明。4. 环境准备与前置条件在开始写代码之前先说清楚环境。watchOS 开发的环境准备比 iOS 要复杂一点因为很多功能在模拟器上不可用或表现很差。基础环境macOS Xcode。Xcode 本身自带 watchOS SDK不需要额外安装工具链。代码语言Swift SwiftUI。SwiftUI 是目前官方主推的 watchOS 界面开发方式WatchKit 的纯代码方式已经逐渐边缘化。系统版本本文给出的代码基于较新的 Swift 语法如果你的 Xcode 版本偏旧可能需要把if let简写改回传统写法。具体版本请以你的实际项目为准。真机调试强烈建议准备一台 Apple Watch 真机。watchOS 模拟器能跑界面但麦克风、语音识别、音频会话这类依赖硬件的功能模拟器表现不可靠。签名要求watchOS 真机部署需要 Xcode 签名配置。免费个人账户在某些情况下受到限制如果签名一直失败更稳妥的做法是使用 Apple Developer Program 账号。工程创建的方式也值得说清楚。在 Xcode 中新建项目时选择 watchOS 下的 App 模板。重点在于目标配置如果你只需要独立的手表应用不需要 iPhone 上的 companion app就要把项目配置成Watch-only App。在 Xcode 的目标配置中只保留 Watch App target移除或不要创建 iOS App 作为宿主 target。这里真正容易踩坑的地方是很多开发者沿用旧习惯先创建一个 iOS 项目再往里面塞 WatchKit App。这样做不是不行但它天然适合手表应用依赖手机应用的架构。Kuma Voice 这类完全脱离 iPhone的项目最好从创建 watchOS App 模板开始避免后续剥离宿主关系时的麻烦。另外如果你是想把源码拉下来跑跑看建议先看 README 里写的 watchOS 最低版本要求。语音识别和独立网络请求在不同 watchOS 版本上的行为有差异版本太老会导致 API 不可用。5. 最小闭环在 watchOS 上实现语音识别现在进入核心代码部分。我们先用一个最小闭环验证按下按钮、开始录音、 Speech framework 把语音转成文字。这是整个语音助手的底座。5.1 配置权限声明与 iOS 一样在 watchOS 上使用麦克风和语音识别必须先在 Info.plist 中声明用途。缺少声明不会崩溃但会在请求权限时直接失败并伴随一段不明显的日志。!-- 文件路径watchOS App target 的 Info.plist -- keyNSMicrophoneUsageDescription/key stringKuma Voice 需要访问麦克风来接收你的语音指令/string keyNSSpeechRecognitionUsageDescription/key stringKuma Voice 需要使用语音识别能力来理解你说了什么/string需要注意这两个权限文案不是摆设。一方面 App Store 审核会检查用途描述是否与实际功能一致另一方面用户在手表上看到权限弹窗时文案如果含糊授权率会明显下降。5.2 请求语音识别权限Speech framework 的权限请求是独立的。建议在应用启动后尽早请求而不是在用户已经按下录音按钮时才弹窗。手表上的交互成本比手机高临时弹窗容易让用户一头雾水。// 文件路径SpeechAuth.swift import Speech enum SpeechAuth { static func requestPermission() async - Bool { let status await withCheckedContinuation { continuation in SFSpeechRecognizer.requestAuthorization { state in continuation.resume(returning: state) } } switch status { case .authorized: return true case .denied, .restricted, .notDetermined: return false unknown default: return false } } }5.3 核心识别类这个类是关键。它做的事情是创建音频引擎、从麦克风输入节点持续采集音频、把音频数据交给 SFSpeechAudioBufferRecognitionRequest最后从识别结果中取出文字。// 文件路径SpeechRecognizer.swift import Speech import AVFoundation final class SpeechRecognizer: ObservableObject { Published var transcript Published var isRunning false private let audioEngine AVAudioEngine() private var recognitionRequest: SFSpeechAudioBufferRecognitionRequest? private var recognitionTask: SFSpeechRecognitionTask? private let recognizer SFSpeechRecognizer(locale: Locale(identifier: zh-CN)) func start() throws { // 启动音频会话 let audioSession AVAudioSession.sharedInstance() try audioSession.setCategory(.record, mode: .measurement, options: .duckOthers) try audioSession.setActive(true, options: .notifyOthersOnDeactivation) // 创建识别请求 let request SFSpeechAudioBufferRecognitionRequest() request.shouldReportPartialResults true recognitionRequest request guard let recognizer, recognizer.isAvailable else { throw SpeechError.recognizerUnavailable } // 从麦克风采集音频并送入请求 let inputNode audioEngine.inputNode let recordingFormat inputNode.outputFormat(forBus: 0) inputNode.installTap(onBus: 0, bufferSize: 1024, format: recordingFormat) { buffer, _ in request.append(buffer) } audioEngine.prepare() try audioEngine.start() isRunning true // 识别结果回调 recognitionTask recognizer.recognitionTask(with: request) { [weak self] result, error in guard let self else { return } if let result { self.transcript result.bestTranscription.formattedString } if error ! nil || result?.isFinal true { self.stop() } } } func stop() { audioEngine.stop() audioEngine.inputNode.removeTap(onBus: 0) recognitionRequest?.endAudio() recognitionTask?.cancel() isRunning false } } enum SpeechError: Error { case recognizerUnavailable }这段代码有几点值得说明。第一SFSpeechRecognizer(locale:)如果当前系统不支持指定区域会返回 nil。示例里用了zh-CN如果用户手表是英文系统这里可能出现识别器不可用。更健壮的做法是回退到Locale.current。第二installTap是持续采集的机制。每次麦克风收到音频数据都会通过 buffer 追加给识别请求。这个 tap 在stop()里必须移除否则再次启动时会崩溃或重复叠加采集。第三isAvailable表示识别器当前是否可用。网络有问题、识别服务不可用、或者权限没有授权时这里都会变成 false。5.4 一个简单的触发界面在手表上最自然的交互是点击一个按钮开始说话再点击一次结束。SwiftUI 代码如下// 文件路径ContentView.swift import SwiftUI struct ContentView: View { StateObject private var recognizer SpeechRecognizer() var body: some View { VStack(spacing: 16) { Text(recognizer.transcript.isEmpty ? 点击开始说话 : recognizer.transcript) .multilineTextAlignment(.center) .foregroundStyle(.secondary) Button(recognizer.isRunning ? 停止 : 开始) { if recognizer.isRunning { recognizer.stop() } else { try? recognizer.start() } } .buttonStyle(.borderedProminent) } .padding() } }到这里一个最小的语音识别闭环就完成了。你把手表举到嘴边点击开始说出设置一个 3 分钟计时器界面上应该会出现对应的文字。6. 从语音到指令意图解析与语音回复识别出文字只是第一步。语音助手之所以是助手是因为它能从文字里提取意图然后执行动作最后用语音回复用户。这一节处理的是从文本到行动这一段链路。6.1 简易意图解析watchOS 应用不可能像完整后端那样跑一个庞大的 NLP 服务。简单场景下用关键词规则就能覆盖不少需求这也是很多开源 watchOS 助手常用的起步方案。// 文件路径CommandParser.swift import Foundation enum Command { case startTimer(seconds: Int) case unknown } struct CommandParser { static func parse(_ text: String) - Command { let trimmed text.trimmingCharacters(in: .whitespacesAndNewlines) if trimmed.contains(计时) || trimmed.contains(timer) { let digits trimmed.filter { $0.isNumber } if let seconds Int(digits), seconds 0 { return .startTimer(seconds: seconds) } return .startTimer(seconds: 60) } return .unknown } }这个解析器的实现很初级但思路是对的先判断语义关键词再提取参数。真正做复杂一点可以引入正则、同义词表、或者把整个文本交给云端大模型去分类。规则解析的好处是快速、离线可用、行为可预期坏处是覆盖面窄用户换个说法就失效。6.2 语音回复执行完指令之后需要把结果念给用户听。watchOS 上可以直接使用 AVSpeechSynthesizer。// 文件路径VoiceReplier.swift import AVFoundation final class VoiceReplier { private let synthesizer AVSpeechSynthesizer() func speak(_ text: String) { let utterance AVSpeechUtterance(string: text) utterance.voice AVSpeechSynthesisVoice(language: zh-CN) utterance.rate 0.5 synthesizer.speak(utterance) } }注意AVSpeechSynthesizer 会接管音频输出。如果你的 App 还在同时播放其他音频需要提前规划好音频会话参数。另外用户可能在嘈杂环境下使用语速不要设置太快0.5 左右是一个偏向清晰的起步值。6.3 把两部分串起来在 SwiftUI 的按钮回调里把结束录音、解析文本、执行动作、语音回复串成完整链路func handleCommand(_ text: String) { switch CommandParser.parse(text) { case .startTimer(let seconds): replier.speak(好的\(seconds) 秒后提醒你) // 这里启动 WKExtendedRuntimeSession 以支持后台计时 case .unknown: replier.speak(没听清请再说一次) } }这里有一个重要的 watchOS 工程坑普通 Timer 在 watchOS 上不会可靠地在后台运行。如果你的应用退到后台系统很快会挂起进程。要做一个真正能够到点提醒的计时器需要用到WKExtendedRuntimeSession它专门用于延长手表应用的后台运行时间。初次接触 watchOS 的开发者最容易在这个地方误以为写个 Timer 就完事了。6.4 如果要接云端大模型很多智能助手最终会接入大模型做语义理解。这里有一个安全建议不要把 API Key 放到 watchOS 客户端里。手表应用没有足够强的安全边界Key 一旦泄漏随之而来的就是费用失控和安全问题。更稳妥的架构是手表端只负责录音和语音回复所有理解请求都发送到你自己的后端由后端持有 Key、做鉴权、做限流再调用大模型。请求示例大致如下// 文件路径AssistantService.swift import Foundation struct ChatRequest: Codable { let messages: [ChatMessage] } struct ChatMessage: Codable { let role: String let content: String } func askAssistant(_ text: String) async throws - String { var request URLRequest(url: URL(string: https://api.example.com/assistant)!) request.httpMethod POST request.setValue(application/json, forHTTPHeaderField: Content-Type) request.httpBody try JSONEncoder().encode( ChatRequest(messages: [ChatMessage(role: user, content: text)]) ) let (data, response) try await URLSession.shared.data(for: request) guard let http response as? HTTPURLResponse, http.statusCode 200 else { throw URLError(.badServerResponse) } return String(data: data, encoding: .utf8) ?? }把请求地址放到客户端本身是可接受的但服务端一定要自己做鉴权比如校验客户端签名、用户 Token而不是暴露可直接调用付费模型的裸接口。7. 运行验证与效果判断代码写完接下来是验证环节。watchOS 应用的真机调试步骤比 iOS 多一些这里整理一套标准的验证流程。7.1 部署到手表在 Xcode 中选中你的 Watch App scheme把 Deployment Target 设置为连接的手表设备直接 Run。第一次运行时系统会提示安装到配对的手表上。需要特别注意手表应用是通过配对的 iPhone 安装到手表上的但安装完成后的运行不依赖 iPhone。如果 Xcode 提示找不到设备先检查 iPhone 与手表的配对状态再检查 watchOS 与 Xcode 版本是否兼容。7.2 授权链路验证首次启动后应用应该依次弹出麦克风权限和语音识别权限。如果只有一个弹窗或者干脆不弹优先检查 Info.plist 是否真的写入了当前 target 的配置。7.3 识别链路验证点击开始按钮对着手表说一句简短的话。预期现象是屏幕上的文字会实时更新。这里分成两个观察点实时文字出现说明音频采集和 speech 识别通路正常停止后能正确解析说明意图解析链路正常会给出对应的语音回复。如果文字没有出现但按钮状态正常优先检查麦克风是否被系统静音、手表是否处于静音模式或剧院模式以及 AVSpeechSynthesizer 的音频输出是否被静音。7.4 判断成功的标准一个完整的验证用例应该覆盖唤醒、说话、识别、理解、回复五个环节。最简单的方式是打印日志在每一层都输出关键信息音频会话是否启动成功识别器是否可用最终识别文本是什么意图解析结果是什么语音回复是否触发。如果每一层都有日志定位问题就非常方便。watchOS 上可以通过 Xcode 的 console 直接查看输出不需要额外工具。8. 常见问题与排查思路watchOS 上的语音助手开发很多问题不是出在业务逻辑而是出在权限、音频会话和系统限制上。下面是实际开发中最容易遇到的几类问题。问题现象可能原因排查方式解决方案权限弹窗没有出现Info.plist 缺少用途声明检查 target 的 Info.plist 配置添加NSSpeechRecognitionUsageDescription和NSMicrophoneUsageDescription语音识别结果一直为空识别器不可用或语言环境不匹配检查recognizer.isAvailable和 locale 配置回退到Locale.current联网后重试点击开始后音频引擎崩溃音频会话配置不对或上一次 tap 未移除查看崩溃日志检查removeTap是否调用在stop()中移除 tap确保可以重复启动应用退到后台后提醒失效watchOS 后台执行限制检查计时器是否在真机上退出后台后失效改用WKExtendedRuntimeSession延长后台运行语音回复没有声音手表静音模式启动或音频输出冲突检查手表是否静音、AVAudioSession 是否 active手动调整音频会话或提示用户取消静音识别速度明显偏慢网络状态不佳识别服务依赖网络检查手表 Wi-Fi 或蜂窝信号优化音频采样格式或考虑离线识别方案无法连接后端 API手表未连网或 ATS 限制检查手表网络与请求错误配置 HTTPS 请求确保后端支持 TLS有一个问题值得单独强调watchOS 模拟器上的语音识别体验和真机差异很大。模拟器可以用电脑的麦克风但音频会话的表现、权限弹窗的触发方式、识别结果的实时性都和真机不完全一致。如果你的目标是做一个真正能戴出门的助手一定要尽早换到真机调试。9. 最佳实践与工程建议如果你的目标是像 Kuma Voice 一样做一个开源 watchOS 语音助手或者你想在现有项目里加入语音能力下面这些工程建议值得参考。9.1 音频会话策略要简单稳定在 watchOS 上不要像 iOS 那样把音频会话玩出太多花样。watchOS 硬件资源有限复杂的setCategory参数和频繁的 session 切换很容易引发奇怪的问题。推荐的做法是开始识别时统一设为.record模式识别结束时恢复默认状态必要时才使用.duckOthers去压低其他音频。9.2 把权限请求前置把失败兜底做全语音助手的核心链路依赖权限。建议在第一次启动时就引导用户授权而不是等到用户点开始说话才弹窗。同时权限被拒绝后要给出明确的 UI 提示不要让用户点击按钮后毫无反应。9.3 离线兜底和网络降级手表端的语音识别可能依赖网络。如果用户的手表没有 Wi-Fi 或蜂窝网络识别链路会直接失败。工程上要设计降级策略比如本地先缓存用户指令文本等网络恢复后补做意图解析或者至少给出当前无法识别请稍后再试的语音反馈。9.4 明白 watchOS 的后台边界这是 watchOS 开发者和 iOS 开发者最大的认知差异。在 iOS 上你有很多合法方式延长后台执行时间但在 watchOS 上WKExtendedRuntimeSession是处理后台任务的主要手段而且它也有时间上限。涉及计时器、健身体训、导航这类需要后台运行的功能时一定要在设计阶段就考虑这个限制否则 App 退到后面就被挂起。9.5 开源合规检查不能少Kuma Voice 是 OSS 项目这是它的优点但使用 OSS和合规使用 OSS是两件事。如果你要在自己的项目里集成它或者给它贡献代码需要注意依赖库的许可证兼容性。常见的做法包括引入依赖前做许可证扫描确认是 MIT、Apache 2.0 等宽松许可还是 GPL 等具有传染性的许可建立 SBOM软件物料清单记录每个第三方组件的版本和许可证保留原有的 LICENSE、NOTICE、COPYRIGHT 声明如果项目会对外分发最好使用扫描工具定期检查整个依赖树避免无意中引入存在合规风险的组件。10. 总结与后续学习方向Kuma Voice 这个项目的出现说明了一件事Apple Watch 作为独立设备的边界正在被开发者一点点推开。过去我们默认手表上的助手离不开 iPhone现在开源社区已经在用实际代码证明语音识别、意图解析、语音回复这套完整链路可以在手表上独立跑通。这篇文章带你把这条链路完整过了一遍从 Watch-only App 的架构基础到权限声明、音频采集、识别、意图解析、语音回复再到真机验证和常见问题排查。你手里的最小示例已经是一个能听、懂、说的雏形。接下来如果你想继续深入可以沿着这几个方向走把意图解析从规则升级为云端 LLM并设计一套后端鉴权方案研究WKExtendedRuntimeSession把计时器、提醒这类后台任务做扎实尝试接入 HomeKit让手表能直接控制智能家居体验 Kuma Voice 的源码看看社区项目在架构拆分、错误处理、权限设计上的取舍。如果你正准备做自己的 watchOS 助手建议先把文中的最小闭环跑通再逐步加功能。手表端的调试成本比手机高越早暴露问题后面的改进越轻松。