Soundiary · 工程技术文档 v1.0

0 · 文档信息与约定

0.1 三条工程底线

✅ ②的当前状态：云端 Provider 与「用户自填 API Key」相关代码已按此条物理删除（不是用 #if 包裹）—— 设置页的密钥输入分组、洞察页的云端分派、顶栏承诺条的分流文案、以及 LLMConfig/LLMClient 等实现一并移除，归档在 Docs/archive/。核验方式（4 项全过才算数）：nm -a 无 URLSession 符号、strings 无 chat/completions、otool -L 未链接 CFNetwork、打包后的 Info.plist 里不存在 NSAppTransportSecurity 键（连空字典都不留）。

0.2 术语

1 · 工程结构与 Target

1.1 Xcode 工程拓扑

1.2 能力矩阵（全球统一，无地区差异）

2 · 构建配置与离线审计

2.1 xcconfig（全局唯一配置）

// Config/Soundiary.xcconfig —— 唯一一份，没有 CN / Global 之分
PRODUCT_BUNDLE_IDENTIFIER          = com.soundiary.app
ENABLE_ON_DEMAND_RESOURCES         = NO
// 不设 INFOPLIST_KEY_NSAppTransportSecurity：没有任何网络请求，ATS 无用武之地

// ⚠️ 不要定义 SOUNDIARY_OFFLINE_ONLY 之类的「全球版」开关：
//    单一 App 没有第二个构建目标，宏无从区分，反而会让人误以为存在全球分支。

2.2 后端选择：运行时判断，不是编译期

public enum ModelHub {
    public static var availableBackends: [LLMBackend] {
        // L1：Foundation Models。必须用 isAvailable，不能按地区字符串分流——
        // 官方口径是「国行设备 或 大陆 Apple Account」二选一即不可用；
        // 非大陆设备 + 非大陆账号，人在中国大陆也能用。别误伤常驻海外的用户。
        if FoundationModels.isAvailable { return [.foundationModels, .coreMLBundled, .templateFallback] }
        // L2：自带模型是老设备与大陆用户的唯一路径；L3 兜底。
        return [.coreMLBundled, .templateFallback]
    }
}

2.3 CI 卡口脚本（提交前必跑）

#!/bin/bash
# Scripts/audit_offline.sh —— 全 App 零联网审计
set -e
APP="$BUILD_DIR/Soundiary.app"
BIN="$APP/Soundiary"

echo "== 1) 网络符号扫描 =="
if nm -u "$BIN" | grep -E "URLSession|NSURLConnection|nw_connection_create|CFNetwork"; then
  echo "❌ 发现网络符号（需人工确认白名单）"; exit 1
fi

echo "== 2) 第三方域名字符串扫描 =="
if strings "$BIN" | grep -Ei "(\.com|\.cn|\.net|\.io)/|https?://" | grep -v "apple.com" | grep -v "soundiary"; then
  echo "❌ 发现疑似第三方域名"; exit 1
fi

echo "== 3) 可回放录音 API 扫描 =="
if nm -u "$BIN" | grep -E "AVAudioRecorder|AVAssetWriter|AVAudioFile"; then
  echo "❌ 出现可产出可回放录音的 API，违反底线①"; exit 1
fi

echo "== 4) 动态库清单 =="
otool -L "$BIN" | grep -v "/usr/lib|/System|@rpath.*Soundiary" || true
echo "✅ 全部通过"

把此脚本加入 Build Phases → Run Script（唯一 Target 即可），失败即构建失败，避免侥幸。

3 · Watch 声音抽样引擎

主录音设备 = Apple Watch。核心结论：不做连续录音，做声音抽样。

3.1 为什么只能是抽样

3.2 采样策略参数

public struct SamplingPolicy {
    public var idleInterval: TimeInterval = 180          // 静默期基础间隔 3 分钟
    public var baseDuration: TimeInterval = 8             // 单次采样 8 秒（< 17s）
    public var voiceExtendedDuration: TimeInterval = 30   // 连续人声时延长上限
    public var voiceExtendThreshold: TimeInterval = 1.2   // 持续人声 1.2s 触发延长
    public var sampleRate: Double = 16_000                // 16 kHz，转写与声纹共用
    public var continuous: Bool = false                   // true = 连续采样档（需 HKWorkoutSession 保活）
    public var continuousWindowSeconds: TimeInterval = 30 // 连续档窗长
    public var bodySampleInterval: TimeInterval = 0       // 体征采样间隔（0 = 随音频窗采）
    public var bodyOnlyPushInterval: TimeInterval = 0     // 纯体征窗推送间隔（0 = 不推）

    public static let standard = SamplingPolicy()
    public static let lowPower = SamplingPolicy(idleInterval: 600, baseDuration: 6,
                                     voiceExtendedDuration: 20, voiceExtendThreshold: 1.5,
                                     bodySampleInterval: 60, bodyOnlyPushInterval: 300)
    public static let dense = SamplingPolicy(continuous: true, continuousWindowSeconds: 30)
    public var dutyCycle: Double { baseDuration / idleInterval }   // ≈ 4.4%
}
// ⚠️ 档位由用户在设置里选（标准 / 省电 / 连续），首版没有「夜间自动降频」——
//    入睡检测已于 2026-10-15 正式取消（见 §3.6），首版只按时间表采样，不判断用户是否入睡。

3.3 调度与唤醒时序

3.4 后台调度的可行手段（按推荐度排序）

3.5 电量与可感知时长估算

public enum BudgetEstimator {
    /// 返回：预计可感知小时数 + 档位文案 key
    public static func estimate(policy: SamplingPolicy = .standard,
                                battery: Double) -> (hours: Double, levelKey: String) {
        let health   = HealthCalibration.shared.degradationFactor   // 电池健康度 → 0.6~1.0
        let drainPerHour = policy.dutyCycle * 7.5              // 经验系数：满占空比 7.5%/h
                            + 1.2                                  // 蓝牙传输基线
        let usable   = max(0, battery - 0.15) * health          // 保留 15% 安全电量
        let hours    = usable / drainPerHour
        return (hours, hours > 10 ? "budget.long" : hours > 4 ? "budget.mid" : "budget.short")
    }
}

⚠️ 经验系数 7.5%/h 需用真机实测校准（建议 Series 7/9/Ultra 各测 3 轮），并在设置页以「估算值，非精确值」声明。

3.6 入睡检测（三重判据） 已取消 · 任何版本都不实现

⚠️ 本功能已于 2026-10-15 正式取消，任何版本都不会实现，本节设计仅作历史留存。代码中不存在任何入睡判断逻辑（sleep.* 界面文案零引用）；HealthKit 只读心率 / HRV / 静息心率，不读睡眠数据。采样完全由用户选定的档位掌控——想停就停，不需要"检测入睡"。

（以下为历史设计，已取消）综合得分 ≥ 0.7 判定入睡 → 自动切换 nightInterval（10 分钟）并继续低频环境监测；连续 30 分钟无人声则完全停止采样，晨起（首次显著运动 + 光照/时间窗）自动恢复。

4 · 采集即弃流水线（iPhone 侧）

4.1 数据流

4.2 关键实现要点

5 · 端侧模型与 Core ML 集成（全球统一）

5.1 三级降级

5.2 模型清单与实际体积

5.3 模型转换与打包

# 1) Whisper → Core ML（使用 whisper.cpp 的 models/convert-whisper-to-coreml.py
#    或 HuggingFace 上已转换好的 aniemore/whisper-tiny-coreml）
python convert-whisper-to-coreml.py --model tiny --encoder-only false --output Models/
xcrun coremlcompiler compile WhisperTiny_int8.mlpackage Models/

# 2) Qwen2.5-0.5B → Core ML int4（coremltools + palettization）
python - <<'PY'
import coremltools as ct, torch, numpy as np
from transformers import AutoModelForCausalLM, AutoTokenizer
name = "Qwen/Qwen2.5-0.5B-Instruct"
m = AutoModelForCausalLM.from_pretrained(name, torch_dtype=torch.float16).eval()
tok = AutoTokenizer.from_pretrained(name)
ids = torch.tensor([tok("今天我").input_ids])          # 追踪用样例（长度决定 KV cache）
traced = torch.jit.trace(m, (ids,), strict=False)
mlmodel = ct.convert(traced, inputs=[ct.TensorType("input_ids", shape=(1, ct.RangeDim(1,1024)))],
                     compute_units=ct.ComputeUnit.CPU_AND_NE,
                     minimum_deployment_target=ct.target.iOS18)
op = ct.optimize.coreml.OpPalettizerConfig(mode="kmeans", nbits=4, weight_threshold=512)
mlmodel = ct.compression_utils.palettize_weights(mlmodel, config=op)
mlmodel.save("Qwen25_05B_int4.mlpackage")
PY
xcrun coremlcompiler compile Qwen25_05B_int4.mlpackage Models/

# 3) 声纹 / 环境分类同理（ECAPA 用 torchaudio 导出 ONNX 再转 Core ML）

# 4) 加入 Xcode：拖入 SoundiaryKit/Resources/Models/
#    Target Membership → 勾选 Soundiary（唯一 Target，全球同一份）

5.4 运行时加载与内存

public actor CoreMLBackend: LLMBackend {
    private var model: MLModel?
    public func load() async throws {
        // 首次推理前才加载；加载后常驻，直到收到内存警告
        let cfg = MLModelConfiguration()
        cfg.computeUnits = .cpuAndNeuralEngine      // NE 加速，CPU 兜底
        cfg.allowLowPrecisionAccumulationOnGPU = true
        guard let url = Bundle.main.url(forResource: "Qwen25_05B_int4", withExtension: "mlmodelc")
        else { throw ModelError.bundledModelMissing }
        model = try MLModel(contentsOf: url, configuration: cfg)
    }
    public func unloadOnMemoryPressure() { model = nil }   // 收到 UIApplicationDidReceiveMemoryWarning
}

推理时机：只在充电 + 连接 Wi-Fi（仅指局域网存在与否，不产生请求）或用户主动打开「今日故事」时批量执行；不在采样瞬间跑大模型，避免发热。

5.5 三语提示词

// PromptCatalog.swift —— 提示词必须随界面语言走，否则中文用户拿到英文腔日记
public enum PromptCatalog {
    public static func dailyStory(locale: Locale, snapshots: [String]) -> String {
        switch locale.language.languageCode {
        case .chinese:
            return """
            以下是用户一天的语音转写片段（按时间排序，已去除音频）：
            \(snapshots.joined(separator: "\n"))
            请用简体中文写一段 300 字以内的第三人称日记，语气克制温柔，不要臆测未提及的事实。
            """
        case .spanish:
            return """
            Fragmentos transcritos del día (sin audio): ...
            Escribe un diario en tercera persona de menos de 300 palabras, en español, tono sobrio.
            """
        default: // .english
            return """
            Transcribed fragments of the day (audio discarded): ...
            Write a third-person diary under 300 words, in English, restrained tone.
            """
        }
    }
}

6 · 多源融合时间轴

6.1 数据源与对齐

⚠️ 首版只读上表前三行。血压 / 睡眠 / 步数 / 运动均不读（早期文档写过，已按实现删除）；位置与照片见文首范围声明，属完整版规划。

6.2 时间轴对齐算法

public struct TimelineBus {
    /// 统一时间基准：所有事件转为 UTC 后按本地时区分桶（桶宽 5 分钟）
    public func fuse(snapshots: [SoundSnapshot],
                     health: [HealthSample]) -> [TimelineBucket] {
        let bucketSize: TimeInterval = 300
        // 1) 各自按 startDate 落入桶
        // 2) 桶内做「跨模态共现」打分：声音×心率
        // 3) 生成自然语言线索，如「19:40 心率 92 + 地铁环境声 → 通勤途中」
    }
}

钟差校正：Watch 与 iPhone 的时间戳分别记录，用 WCSession 激活时的往返做一次偏移估计（通常 < 50ms），记录在 AudioFrame.capturedAt 校正值中。

6.3 备忘录的可行接入方式

7 · 数据模型与保留策略

7.1 SwiftData Schema

@Model final class Day {
    var date: Date                        // 本地日历日（零点由用户时区决定）
    var story: String?                     // LLM 生成的当日故事
    var emotionScore: Double?               // -1.0 ~ 1.0
    var todos: [TodoItem]
    @Relationship(deleteRule: .cascade) var snapshots: [SoundSnapshotEntity]
    var discardedBytes: Int64               // 透明度面板用
    var sensedSeconds: Int
}

@Model final class SoundSnapshotEntity {
    var id: UUID
    var startAt: Date
    var endAt: Date
    var transcript: String                 // 可能为空（纯环境声）
    var envLabel: String                  // quiet / speech / crowd / traffic / music ...
    var loudness: [Float]                  // 每 5s 一个 dBFS，≈ 6 个值
    var voiceprint: Data?                 // 192 × Float32 = 768B，加密存储
    var clusterID: Int?
    var isPartial: Bool                   // 传输中断标记
    // ❗ 没有任何 audioURL / audioData 字段 —— 这是设计约束，不是遗漏
}

@Model final class Speaker {
    var clusterID: Int
    var nickname: String?                 // 用户确认后填写
    var centroid: Data                    // 声纹中心向量（加密）
    var confirmed: Bool = false           // 用户是否已确认身份
    var lastSeen: Date
}

@Model final class Insight {
    var title: String
    var body: String
    var kind: String                      // pattern / knowledge / habit / reminder
    var evidenceDayIDs: [UUID]
    var createdAt: Date
    var isRead: Bool
}

7.2 保留策略（默认，用户可改）

7.3 导出与删除

• 导出：UIActivityViewController 导出 JSON / Markdown（明文，用户自选保存位置）。导出内容不含任何音频，导出动作本身不联网。
• 删除：设置 → 数据管理，提供「删除今天 / 删除 30 天前 / 删除全部」。删除时对加密 SQLite 执行 VACUUM 并覆写空闲页，避免残留。
• 卸载即清空：所有数据存于 App Group 容器（非 iCloud、非 CloudKit），卸载 App 后系统自动清除。需在隐私政策中明确告知。

8 · 存储加密与密钥

// SecureKeyStore 关键片段
let access = SecAccessControlCreateWithFlags(
    nil,
    kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
    [.privateKeyUsage, .biometryCurrentSet],   // 生物识别变更后密钥自动失效
    nil)!
let attrs: [String: Any] = [
    kSecAttrKeyType as String: kSecAttrKeyTypeECSECPrimeRandom,
    kSecAttrKeySizeInBits as String: 256,
    kSecAttrTokenID as String: kSecAttrTokenIDSecureEnclave,  // 硬件背书
    kSecPrivateKeyAttrs as String: [kSecAttrIsPermanent: true, kSecAttrAccessControl: access]
]

9 · 零联网保障工程化

9.1 允许的网络行为白名单（全 App）

9.2 抓包自检流程（提交前必做）

今日已感知            8 小时 12 分
已丢弃原始音频        4.2 GB
本地占用              48 KB
第三方网络请求        0 次
最后联网行为          无（App 运行时零联网）

10 · 三语本地化工程

10.1 语言与区域

10.2 目录与命名

10.3 易错点清单

11 · Info.plist 与权限清单

11.1 iOS（iPhone Target）

⚠️ 本地通知（UNUserNotificationCenter）不需要用途描述键 —— 早期文档列的 NSUserNotificationsUsageDescription 不存在也不需要。

11.2 watchOS（Watch App Target）

11.3 HealthKit 授权请求代码要点

// 手表端实际请求的范围（WatchSensingEngine.BodySignals + WorkoutKeepAlive）
let toRead: Set<HKObjectType> = [
    HKObjectType.quantityType(forIdentifier: .heartRate)!,
    HKObjectType.quantityType(forIdentifier: .heartRateVariabilitySDNN)!,
    HKObjectType.quantityType(forIdentifier: .restingHeartRate)!
]
let toShare: Set<HKSampleType> = [HKObjectType.workoutType()]  // 仅为后台执行权，结束即 discardWorkout()
try await healthStore.requestAuthorization(toShare: toShare, read: toRead)
// ⚠️ 审核红线：HealthKit 数据不得用于广告、数据经纪、不得写入 iCloud、不得披露给第三方
// ⚠️ 血压 / 睡眠 / 步数 / 运动一律不读 —— 权限范围与 §6.1 数据来源表严格一致

12 · 知情同意流程

12.1 四步引导（首次启动）

⚠️ 状态说明（2026-10-15 核对）：这四步目前是设计稿，代码中尚未实现——iPhone 端搜不到任何首次启动引导页（无 onboard / firstLaunch / walkthrough 相关实现）。因此 不要把「四步引导」「逐项可关的同意流程」写进 App Store 描述，否则属虚假宣称。当前真实的授权流程是：Watch 端采样时由系统弹窗逐项询问麦克风与 HealthKit，用户可逐项拒绝；设置页常驻感知状态开关与「今日透明度」面板。

12.2 持续可见的同意状态（PIPL / GDPR 要求「可撤回」）

• 设置页顶部常驻「感知状态」开关，一键停止且立即清零缓冲；
• 每次采样窗开始时，Watch 端可显示极轻量的状态点（可选，用户可关）；
• 通知栏常驻（可选）：「Soundiary 正在感知 · 点击停止」——iOS 26 支持持续通知；
• 任何时刻进入 App 都能看到今天的透明度面板（§9）。

13 · 付费下载配置（无内购）

13.1 定价配置（在 App Store Connect 中设置，不在代码里）

13.2 换设备后如何「恢复」

付费 App 不需要 App 内的「恢复购买」按钮，也因此不触发 Guideline 3.1.1（该条款只针对 App 内购买）。换设备后：

1. 用原 Apple ID 打开 App Store；
2. 进入「已购项目 / Purchases」；
3. 找到 Soundiary，点云下载图标重新下载——无需重复付费。

恢复流程完全由 Apple 侧处理，App 不参与、不存储任何支付凭据。

14 · 备案豁免提交包

14.1 提交路径

1. 登录 App Store Connect → 页面底部 「联系我们 / Contact Us」；
2. 依次选择：App Store 分发 → 其他疑问 / Additional Questions；
3. 在附件中上传《不适用备案说明函》（PDF，含 Team ID 与手写签名）；
4. 正文写明：App 名称、Apple ID、Bundle ID、Team ID、中国区上架诉求、以及「本 App 不提供互联网信息服务」的事实依据。

14.2 说明函模板（可直接复制打印）

14.3 提交前自检（全部 ✅ 才可提交）

• 抓包报告显示 0 次第三方请求（含冷启动、后台、IAP 全流程）
• 二进制符号扫描通过（§2.3 脚本 4 项全绿）
• 无第三方 SDK（检查 Pods/、SPM 依赖、Frameworks/ 为空）
• 隐私政策已上线且 URL 可访问（HTTPS）
• App 隐私标签填写为「未收集数据」或仅 Apple 支付相关（见 §15）
• App 内无「登录 / 注册 / 账号」字样
• App 内无用户生成内容入口（无评论、无分享社区、无反馈上传附件）
• 技术支持 URL 与隐私政策 URL 均已填写且有效

15 · App Store 隐私标签填写对照

ASC → App 信息 → App 隐私 → 按下列填写。

✅ 目标状态：「此 App 未收集数据」（Data Not Collected）。这是最有说服力的隐私标签，也是豁免申请的有力佐证。

16 · 测试与验收

16.1 测试矩阵

16.2 隐私回归测试（每次发版必跑）

func testNoAudioArtifactsOnDisk() throws {
    let urls = try FileManager.default.contentsOfDirectory(
        at: FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0],
        includingPropertiesForKeys: nil)
    let audio = urls.filter { ["m4a","caf","wav","mp3","opus"].contains($0.pathExtension) }
    XCTAssertEqual(audio.count, 0, "磁盘上出现音频文件，违反底线①")
}

func testNoNetworkBackendExists() throws {
    // 单一 App：不存在任何云端后端，连枚举 case 都不该有。
    // 由 CI 脚本 audit_offline.sh 在构建期扫描 __TEXT 符号表保证。
    XCTAssertEqual(ModelHub.availableBackends.count, 3,
                   "只允许 foundationModels / coreMLBundled / templateFallback 三个后端")
}

17 · 发布清单

17.1 上架前（T-14 天）

• 隐私政策三语上线（HTTPS，需含「生效日期」「联系邮箱」）
• 技术支持页三语上线
• 《不适用备案说明函》PDF 完成并签名盖章
• 抓包报告 + 符号扫描报告归档
• App 图标 1024×1024（无 alpha、无圆角）
• 三语宣传图各 6 屏 iPhone（1290×2796）+ 2 屏 Watch（410×502）
• 三语元数据：标题（≤30）、副标题（≤30）、关键词（≤100）、描述、宣传文本
• 年龄分级问卷填写（注意：涉及健康数据，如实填写）
• 出口合规（加密导出）：使用免申报例外（5.D.992.c）——仅使用标准加密且不提供网络安全功能
• IAP 商品审核通过

17.2 提审后

• 若收到「需备案号」驳回 → 回复工单并附说明函 PDF（同一工单内追加，不要新建）
• 若收到 5.1.1（数据收集最小化）→ 附上隐私政策链接与透明度面板截图
• 若收到 4.2（最低限度功能）→ 演示完整日流程录屏（感知→故事→洞察）
• 记录每次驳回模板与应对话术，形成团队知识库

17.3 版本记录