# 「身体档案」输入框语音听写 Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** 在「身体档案」(`HealthExportSheet`)底部聊天输入框加端侧语音听写:点 mic 开始、识别文字实时流进输入框、再点停止,不调 LLM、不自动发送。 **Architecture:** 复用 `SpeechDictationService`(@State 持有);新增 static 纯函数 `merge(prefix:partial:)` 处理"已有文字 + 听写文字"拼接(唯一可单测逻辑);`HealthExportSheet` 加 6 个 @State + mic 按钮 + 3 个流程函数。Spec:`docs/superpowers/specs/2026-06-10-voice-export-composer-design.md`。 **Tech Stack:** SwiftUI、Speech(经 SpeechDictationService)、Swift Testing。 **工程约定:** 同 `2026-06-10-voice-diary.md` 的「执行前必读」(同步组免改 pbxproj、CLI 用 `DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer` + `-derivedDataPath ./build/cli-dd`、全量并行测试不可信要 `-only-testing` 定点跑、commit 逐文件 add 不带 `Localizable.xcstrings`)。**当前环境注意**:xcode-select 已指向完整 Xcode 且许可证未接受——`git` 用 `DEVELOPER_DIR=/Library/Developer/CommandLineTools` 前缀绕过;`xcodebuild` 必须先让用户跑 `sudo xcodebuild -license accept`。直接在 `feat/mnn-sme2-runtime` 分支上做(上一功能合并后该分支即集成分支,不再另开分支避免并发会话分支错位)。 --- ### Task 1: `merge(prefix:partial:)`(TDD) **Files:** - Test: `康康Tests/SpeechDictationMergeTests.swift`(新建) - Modify: `康康/Services/SpeechDictationService.swift`(`isAvailable` 之后加 static 方法) - [ ] **Step 1: 写失败测试** 新建 `康康Tests/SpeechDictationMergeTests.swift`: ```swift import Testing @testable import 康康 struct SpeechDictationMergeTests { @Test func emptyPrefixReturnsPartial() { #expect(SpeechDictationService.merge(prefix: "", partial: "今天头晕") == "今天头晕") } @Test func plainPrefixJoinsWithSpace() { #expect(SpeechDictationService.merge(prefix: "已有内容", partial: "新听写") == "已有内容 新听写") } @Test func whitespaceTerminatedPrefixConcatsDirectly() { #expect(SpeechDictationService.merge(prefix: "第一行\n", partial: "新听写") == "第一行\n新听写") } @Test func emptyPartialKeepsPrefix() { #expect(SpeechDictationService.merge(prefix: "已有内容", partial: "") == "已有内容") } } ``` - [ ] **Step 2: 跑测试确认编译失败** ```bash cd /Users/xuhuayong/apps/康康 export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcodebuild test -project 康康.xcodeproj -scheme 康康 \ -destination 'platform=iOS Simulator,name=iPhone 17' \ -only-testing:'康康Tests/SpeechDictationMergeTests' \ -derivedDataPath ./build/cli-dd CODE_SIGNING_ALLOWED=NO 2>&1 | grep -E "error:|TEST (SUCCEEDED|FAILED)" | head -5 ``` Expected: `error: type 'SpeechDictationService' has no member 'merge'`(TEST FAILED)。 - [ ] **Step 3: 实现 merge** 在 `康康/Services/SpeechDictationService.swift` 的 `static var isAvailable` 行之后加: ```swift /// 听写文本拼接:听写开始时输入框已有 prefix,partial 持续拼在其后。 /// prefix 空 → 直接用 partial;prefix 以空白/换行结尾 → 直接连接;否则补一个空格。 static func merge(prefix: String, partial: String) -> String { guard !partial.isEmpty else { return prefix } guard !prefix.isEmpty else { return partial } if let last = prefix.unicodeScalars.last, CharacterSet.whitespacesAndNewlines.contains(last) { return prefix + partial } return prefix + " " + partial } ``` - [ ] **Step 4: 跑测试确认通过** 同 Step 2 命令。Expected: `** TEST SUCCEEDED **`,4 个用例通过。 - [ ] **Step 5: Commit** ```bash cd /Users/xuhuayong/apps/康康 DEVELOPER_DIR=/Library/Developer/CommandLineTools git add 康康Tests/SpeechDictationMergeTests.swift 康康/Services/SpeechDictationService.swift DEVELOPER_DIR=/Library/Developer/CommandLineTools git commit -m "feat(语音听写): SpeechDictationService.merge 前缀拼接(TDD)" ``` --- ### Task 2: HealthExportSheet 接入 **Files:** - Modify: `康康/Features/Archive/HealthExportSheet.swift`(状态区 :27-30、canAsk :38、canGenerateReport :49、快捷问答 chip :133、onDisappear :103、alert :104、composer :410) - [ ] **Step 1: 加听写状态(「快捷问答」状态块之后、`init` 之前)** 在 `@State private var newPromptText = ""` 之后插入: ```swift // 语音听写(spec 2026-06-10-voice-export-composer)。 // dictation 必须 @State:struct View 重建时普通 let 会换新实例(日记踩过的坑)。 @State private var dictation = SpeechDictationService() @State private var isDictating = false /// 听写开始时输入框已有文字,partial 始终拼在它后面。 @State private var dictationPrefix = "" @State private var dictationTask: Task? @State private var dictationWatchdog: Task? @State private var dictationDeniedAlert = false /// 录音上限,与日记一致(防麦克风悬挂)。 private static let dictationMaxSeconds = 180 ``` - [ ] **Step 2: 录音中禁发送/生成/chip** `canAsk` 加条件: ```swift private var canAsk: Bool { !isAnswering && !isGeneratingReport && !isDictating && !draftQuestion.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty } ``` `canGenerateReport` 的 `!isGeneratingReport &&` 后加 `!isDictating &&`。 快捷问答 chip 动作(`draftQuestion = p.prompt` 处)改为: ```swift guard !isDictating else { return } draftQuestion = p.prompt ``` - [ ] **Step 3: composer 加 mic 按钮 + TextField 录音中禁用** TextField 的 `.disabled(isAnswering || isGeneratingReport)` 改为 `.disabled(isAnswering || isGeneratingReport || isDictating)`。 TextField 与发送 Button 之间插入: ```swift if SpeechDictationService.isAvailable { Button { toggleDictation() } label: { Image(systemName: isDictating ? "stop.fill" : "mic.fill") .font(.tjScaled(15, weight: .semibold)) .foregroundStyle(isDictating ? Tj.Palette.paper : Tj.Palette.brick) .frame(width: 40, height: 40) .background(Circle().fill(isDictating ? Tj.Palette.brick : Tj.Palette.brickSoft)) .symbolEffect(.pulse, options: .repeating, isActive: isDictating) } .disabled(isAnswering || isGeneratingReport) .accessibilityLabel(isDictating ? String(appLoc: "停止听写") : String(appLoc: "语音输入")) } ``` - [ ] **Step 4: 生命周期 + 权限 alert** `.onDisappear { task?.cancel() }` 改为: ```swift .onDisappear { task?.cancel() dictationTask?.cancel() dictationWatchdog?.cancel() dictation.abort() } ``` 现有「添加快捷问答」alert 的 `}` 闭合之后追加: ```swift .alert(String(appLoc: "需要麦克风与语音识别权限"), isPresented: $dictationDeniedAlert) { Button(String(appLoc: "前往设置")) { if let url = URL(string: UIApplication.openSettingsURLString) { UIApplication.shared.open(url) } } Button(String(appLoc: "取消"), role: .cancel) {} } message: { Text("语音输入全程在本机完成,声音和文字都不会上传。请在设置中允许麦克风和语音识别。") } ``` - [ ] **Step 5: 流程函数(`// MARK: - Actions` 之后、`sendQuestion` 之前)** ```swift // MARK: 语音听写 private func toggleDictation() { if isDictating { stopDictation() } else { startDictation() } } private func startDictation() { questionFocused = false dictationTask = Task { @MainActor in guard await dictation.requestAuthorization() else { dictationDeniedAlert = true return } do { dictationPrefix = draftQuestion try dictation.start { partial in draftQuestion = SpeechDictationService.merge(prefix: dictationPrefix, partial: partial) } withAnimation(.snappy(duration: 0.2)) { isDictating = true } dictationWatchdog = Task { @MainActor in try? await Task.sleep(nanoseconds: UInt64(Self.dictationMaxSeconds) * 1_000_000_000) guard !Task.isCancelled, isDictating else { return } stopDictation() } } catch { isDictating = false } } } private func stopDictation() { guard isDictating else { return } dictationWatchdog?.cancel() dictationTask = Task { @MainActor in let final = (await dictation.stop()).trimmingCharacters(in: .whitespacesAndNewlines) if !final.isEmpty { draftQuestion = SpeechDictationService.merge(prefix: dictationPrefix, partial: final) } // final 为空:partial 已实时在输入框,保持现状即天然兜底(spec:不提示「没听清」) withAnimation(.snappy(duration: 0.2)) { isDictating = false } } } ``` - [ ] **Step 6: touch 强制重编验证** ```bash cd /Users/xuhuayong/apps/康康 touch 康康/Features/Archive/HealthExportSheet.swift export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcodebuild -project 康康.xcodeproj -scheme 康康 \ -destination 'platform=iOS Simulator,name=iPhone 17' \ -configuration Debug build -derivedDataPath ./build/cli-dd \ CODE_SIGNING_ALLOWED=NO 2>&1 | grep -E "\.swift:[0-9]+:[0-9]+: (error|warning):|BUILD (SUCCEEDED|FAILED)" ``` Expected: `BUILD SUCCEEDED`,无新增 warning。 - [ ] **Step 7: 定点回归(语音相关全部测试)** ```bash xcodebuild test -project 康康.xcodeproj -scheme 康康 \ -destination 'platform=iOS Simulator,name=iPhone 17' \ -only-testing:'康康Tests/SpeechDictationMergeTests' \ -only-testing:'康康Tests/SpeechDictationAvailabilityTests' \ -only-testing:'康康Tests/DiaryOrganizePromptTests' \ -derivedDataPath ./build/cli-dd CODE_SIGNING_ALLOWED=NO 2>&1 | grep -E "Test case.*(passed|failed)|TEST (SUCCEEDED|FAILED)" ``` Expected: `** TEST SUCCEEDED **`,7 用例通过。 - [ ] **Step 8: Commit** ```bash cd /Users/xuhuayong/apps/康康 DEVELOPER_DIR=/Library/Developer/CommandLineTools git add 康康/Features/Archive/HealthExportSheet.swift DEVELOPER_DIR=/Library/Developer/CommandLineTools git commit -m "feat(语音听写): 身体档案输入框听写实时上屏" ``` --- ### Task 3: 真机手测清单 - [ ] **Step 1: 真机逐项确认** 1. 「身体档案」composer 出现 mic 按钮(模拟器不支持端侧识别时隐藏) 2. 点 mic → 说话 → 字实时出现在输入框;输入框已有文字时保留并以空格衔接 3. 录音中:输入框/发送/「生成整理报告」/快捷问答 chip 均不可用;mic 为红色停止态 4. 再点 mic → 停止,文字落定,点发送正常走问答 5. 权限拒绝 → alert 跳设置 6. 录音中直接关 sheet → 无崩溃、麦克风指示灯熄灭 7. 3 分钟自动停止 --- ## Self-Review 记录 - **Spec 覆盖**:merge 纯函数+单测(T1)、@State 持有/实时上屏/停止落定/空结果保持现状(T2 S5)、mic 隐藏与禁用矩阵(T2 S2-S3)、权限 alert + onDisappear abort + 看门狗(T2 S4-S5)、真机清单(T3)。无缺口。 - **占位符**:无;所有代码步骤给全。 - **类型一致性**:`merge(prefix:partial:)` T1 定义、T2 S5 调用一致;`dictationMaxSeconds`/`isDictating`/`dictationPrefix` 命名前后一致;`SpeechDictationService.isAvailable/requestAuthorization/start/stop/abort` 与现有实现签名一致。