Architecture Review · Source-Verified

纪要(Minutes) macOS 原生会议转写与纪要应用。它真正的架构不在 SwiftUI 界面里,而在「应用进程」与「两个本地推理进程」之间的那条契约上。

仓库 wang-junjian/Minutes 分支 main @ 4676637 Swift 6 · macOS 14+ 应用源码 2,893 行 / 22 文件 核对方式 源码逐行 + 实测数据
2
独立推理进程
4.86GiB
本地 GGUF 权重
0
Python / 云端依赖
3,331行
Swift(含测试与基准)
7
自动化验证入口

01七条论断

如果只读一页,读这里。每一条都能在源码里被证伪——这是本文唯一的写作标准。

01

耦合点是协议,不是框架

应用只依赖两件事:一个接受 multipart WAV 的 transcription 端点,一个说 OpenAI Chat Completions SSE 的对话端点。换掉 audio.cpp 或 llama.cpp,只要新引擎说这两句话,Swift 侧一行都不用改。反过来说,这也是它敢在上一版把整套 Python worker 整体删除的底气。

README.md:27 · EngineClient.swift:29,84
02

稳定性来自「把不可靠的东西挪到进程外」

模型推理是最可能崩的一段代码,也是内存占用最大的一段。它被放进两个独立进程:崩了只影响那一个引擎,UI 存活并展示失败原因;应用重启也不会去杀端口上归属不明的进程。代价是跨进程通信与状态同步,收益是崩溃半径被压到最小。

EngineWorker.swift:111 · MinutesApp.swift:62
03

正确性由三个计数器守住:闸门、代次、序号

并发送识别会压垮引擎(闸门),在飞的旧结果会覆盖新分段(代次),识别完成顺序与音频顺序不一致会让转写串行(序号)。三个问题各配一个极小机制,加起来不到 80 行,但缺任何一个都会出现「文字乱序」「重复句」「丢句」这类难复现的诡异 bug。

MeetingSession.swift:7,117,306
04

「就绪」不是布尔值,是一个待证明的身份

端口上有人应答 HTTP 200 不等于「我的模型加载好了」。健康检查同时校验运行时特征、模型路径(符号链接归一后逐字符比对)和加载状态;三者任一不符就判 incompatible 而不是 ready。这让「旧进程还没退干净」「端口被别的服务占了」从玄学变成一句明确报错。

EngineHealth.swift:11,28 · EngineWorker.swift:320
05

断句问题被从声学搬到了文本

没有 VAD。音频按固定 1.5 秒节奏整段送识别,切段的条件是「识别文本以句末标点收尾且音频够长」,或「段长触顶 15 秒」。复杂声学环境下的能量阈值不可靠(噪声爬升漏检、切句点断词),而标点由模型给,稳定得多。

MeetingSession.swift:89-97,137
06

供应链是代码的一部分,不是 README 的一句话

上游 commit、模型 revision、字节数、SHA256 全部锁进 dependencies.lock;构建脚本还会用 otool 检查产物没有偷偷链上 Python.framework、Torch、MLX、ffmpeg 或 Homebrew。镜像只影响传输,不影响最终校验。

Engine/dependencies.lock:3 · scripts/bootstrap.sh:121
07

「原生」不等于「全面更快」,文档自己也承认

迁移到 Metal 原生服务后,ASR 耗时降到约一半、内存 footprint 降 36–51%,LLM 总耗时降 8%——但纯生成速度从 85.30 掉到 80.76 token/s。这个倒退被写进了基准文档而不是藏起来,是这套工程里最值得学的一处诚实。

Benchmarks/README.md:原生版本小节

02系统全景

一句话:一个 SwiftUI 应用进程,加两个由它拉起、只监听回环地址的原生推理进程。三者之间没有共享内存、没有私有 RPC、没有 Python。

macOS 应用进程 · Swift 6 / SwiftUI 表现层 ContentView · SidebarView · LiveMeetingView · TranscriptView MinutesView · SettingsView · EngineStatusControl MeetingSession @MainActor @Observable · 状态机 采集 → 节奏识别 → 纪要 的编排者 MeetingsStore 一会议一 JSON 可直接人读、可 diff EngineSupervisor 聚合两个 worker 的状态与日志 UI 唯一需要打交道的引擎入口 EngineClient · actor WAV multipart / OpenAI SSE 唯一发 HTTP 的地方 AudioCapture AVAudioEngine 逐缓冲重采样 16k / mono WAVEncoder float32 → PCM16 手写 44 字节头 零依赖 SSEParser 逐字节状态机 完整事件才解码 中文不被拆坏 EngineConfig UserDefaults 端口 / 模型 / Prompt 配置版本迁移 全部中间数据落在 ~/Library/Application Support/Minutes 应用沙箱未启用(需访问任意路径 GGUF 与本机端口) 本机推理进程 · Metal / arm64 audiocpp_server audio.cpp @ 6f71a3b Qwen3-ASR-1.7B Q8_0 · 2.47 GB 127.0.0.1:8797 POST /v1/audio/transcriptions GET /health · /v1/models model=minutes-asr · 离线模式 llama-server llama.cpp @ 513ad7a Qwen3.5-4B Q4_K_M · 2.74 GB 127.0.0.1:8788 POST /v1/chat/completions(SSE) GET /health · /props ctx 32768 · parallel 1 · 全量 GPU 层 由应用拉起,退出时由应用终止 仅监听回环地址,全程无出网请求 两个进程互相无感知,可独立崩溃恢复
图 1 分层与运行时拓扑。虚线框内是应用进程;右侧两个原生服务是独立进程,通过 HTTP 与 actor 通信。注意 EngineClient 是唯一发网络请求的组件——EngineSupervisor 只做进程与状态的聚合,不碰数据面。

运行时契约

把「进程边界」当作架构里一等公民,代价与收益都要写清楚。下面这张表是两侧实际约定,不是设计意图的转述。

维度ASR 侧LLM 侧
可执行文件engine/bin/audiocpp_serverengine/bin/llama-server
默认端口8797(避开常被占用的 8787)8788
模型别名minutes-asrminutes-llm
启动参数由应用生成 runtime/asr-<port>.json纯命令行参数,无配置文件
数据面multipart/form-data + PCM16 WAVJSON + text/event-stream
身份证明backend=metal + 模型 family=qwen3_asr + loaded + 路径一致build_info 非空 + model_path 一致 + 非 sleeping
就绪判据HTTP 200 且模型已加载HTTP 200;503 且 message 含 loading 视为启动中
超时策略单请求 600s,资源 3600s启动探测 1.5s,总等待 180s
设计取舍

两个引擎都不接受「应用内嵌」。嵌入式调用能省掉 HTTP 与进程管理,但会让模型崩溃等于应用崩溃、模型内存常驻不可回收、也无法在应用重启时保留已加载的权重。当前形态的代价是每次识别多一次回环 HTTP(<1ms 量级),收益是崩溃隔离与可独立观测。对「一次会议要跑一两个小时」的场景,这个交换是划算的。

03进程契约:什么时候必须重启,凭什么算就绪

进程管理的难点不在「拉起来」,在「判断该不该拉」和「判断拉起来的到底是谁」。前者用启动签名,后者用三重身份校验。

启动签名:一个字符串取代一堆布尔标记

EngineWorker 没有为端口、模型、路径各存一个 didChange 标记,而是把它们拼成一个签名。每次 start() 先算当前签名,与正在运行的那个比对:一致且已 ready 就什么都不做;不一致就先把旧进程停掉。这让「改完端口点启动」这种操作不会出现两个进程抢同一个端口。

// EngineWorker.swift:89 — 任一变化都必须重启
private func launchSignature() -> String {
    [
        configuration.engineRoot,
        configuration.modelPath(for: kind),
        String(configuration.port(for: kind)),
        kind == .llm ? String(configuration.llmContextSize) : "offline",
    ].joined(separator: "|")
}

签名还被用来做竞态护栏:所有状态跃迁函数(becomeReady / failIfStarting)都要求「当前签名等于当初传入的签名」才生效。用户在中途改了端口,那个还在跑的旧 Task 就无法把新会话误标成 failed。

三重身份校验:把「端口上有人」变成「端口上是我的人」

只查 GET /health 是否 200 是不够的——上一版遗留的 Python worker 也会返回 200。当前实现要求同时满足三个条件,任一不符即判 incompatible 并给出可读原因:

① 运行时特征

LLM 要求 /props 返回非空 build_info;ASR 要求 health.backend == "metal" 且有 version。旧 Python 服务没有这些字段。

② 模型路径一致

取服务自报的模型路径,与设置里的期望路径各自做 expandingTildeInPath → standardizedFileURL → resolvingSymlinksInPath 归一后逐字符比对。

③ 加载完成

LLM 要求 is_sleeping 为假;ASR 要求模型条目 configured 且 loaded 为真。否则返回 starting,继续等。

// EngineHealth.swift:11 — 返回三态而非布尔
static func validateLLM(health: [String: Any], props: [String: Any],
                       expectedModelPath: String) -> Status {
    guard health["status"] as? String == "ok",
          let build = props["build_info"] as? String, !build.isEmpty
    else { return .incompatible("端口上的服务不是受支持的 llama.cpp") }

    guard let modelPath = props["model_path"] as? String
    else { return .incompatible("llama.cpp 未返回模型路径") }
    guard pathsEqual(modelPath, expectedModelPath)
    else { return .incompatible("加载的模型与当前设置不一致") }

    if props["is_sleeping"] as? Bool == true { return .starting }
    return .ready(detail: "llama.cpp \(build)")
}

端口被占用时,代码分得清三种情况

这是「本地服务」类应用最常见的支持工单来源。当前实现不猜,直接探测后分流:

探测结果含义动作
unavailable端口无人应答自己拉起进程,等它健康(180s 上限)
starting有服务在,但模型还在加载不重复拉起,只轮询等它 ready,之后转为外部存活监测(每 5s)
incompatible有服务在,但不是我要的那个立即失败并提示「端口被占用:…。请停止旧服务或修改端口」

注意第二行的细节:外部启动的服务没有 Process 终止回调,所以 ready 之后要切到另一条代码路径继续盯它,否则用户手动 kill 了引擎,应用会一直以为它还活着。monitorExternalHealth 就是那条路径。

一处容易被忽略的卫生

拉起子进程前,代码主动从环境里删掉 DYLD_LIBRARY_PATH 与 DYLD_FALLBACK_LIBRARY_PATH(EngineWorker.swift:142)。否则在 Xcode 里启动应用时,继承来的这两个变量会让 llama-server 加载到错误版本的动态库——表现是启动即崩溃,日志里看不出原因。

04数据流水线:从麦克风到可读纪要

一条主线,九个环节,没有任何环节把音频或文本送出本机。整条链上只有三处异步:音频回调、识别请求、SSE 流。

① 采集 AVAudioEngine tap 按总线原生格式收 4096 frame / 次 ② 重采样 每缓冲新建 converter → 16 kHz / 单声道 float32,附 RMS ③ 累积缓冲 AsyncStream 最新 64 块 按 60 s 上限裁旧 记录首尾偏移秒数 ④ 节奏识别 1.5 s 快照缓冲 → WAV 上传 非阻塞取名额 interim 文本灰色上屏 ⑤ 切段判定 句末标点 且 音频 ≥5 s 或段长 ≥15 s 强制切 否则只更新 interim ⑥ 落定分段 分配 sequence 序号 代次 +1,清空缓冲 空文本不产生空段 ⑦ 按序归位 暂存 pending 只按 expect 顺序出队 保证转写不串行 ⑧ 纪要生成 冲刷残余音频 12000 字符分块 map reduce 成四节结构 ① 的关键约束:tap 必须传总线原生格式,请求别的采样率会直接 SIGSEGV;converter 不能跨缓冲复用,所以每个缓冲新建一个(约零点几毫秒开销)。 ③ 的 60 s 上限用于引擎崩溃自愈窗口:引擎不可用时识别请求会被跳过,缓冲若无限增长就是内存泄漏。 ⑧ 在单块(≤12000 字符)时直接一次调用;多块时才走 map-reduce,会议长达两小时也不会撑爆 32768 的上下文。
图 2 主数据流水线。上半段(蓝)是音频侧,下半段(青)是文本侧。注意 ④ 与 ⑤ 之间不是「一问一答」——缓冲在识别期间继续增长,回来的是对旧快照的判断,这正是需要代次机制的根因。

节奏参数:全部集中在 MeetingSession 顶部

参数值为什么是这个值
pollInterval1.5 s离线识别 25 s 音频耗 0.96 s,1.5 s 的节奏留有 1.5 倍余量;再密就是空转
minCloseSeconds5 s防止「嗯。」「好。」这类极短句被切成独立段,导致分段碎片化
maxSegmentSeconds15 s无标点(连续讲述)时的兜底切分,保证时间戳密度
bufferCapSeconds60 s覆盖引擎重启窗口;超出丢最旧,防止内存无界
TranscriptionGate.limit2让「正在进行的识别」与「刚完成的识别」有重叠,又不至于排队雪崩
最短音频0.5 ssamples < 8000 直接返回空文本,不触发模型推理

三个计数器:整条链的正确性支点

闸门 · TranscriptionGate

一个 actor 实现的计数信号量,但它提供两种取法,语义完全不同:

这个区分很关键。如果全用阻塞版,引擎变慢时请求会堆积,越堆越慢,最后超时丢一片;如果全用非阻塞版,收尾那段音频可能永远等不到名额。

代次 · interimGeneration

发出识别请求时记下当前代次,结果回来后比对:不等就整个丢弃。因为在此期间缓冲可能已经被切段(closeSegment 里 interimGeneration += 1)或冲刷(flushBuffer 同样 +1)。没有这一层,一个慢回来的识别结果会把已经落定的分段又写成 interim 文本,用户看到「刚说过的字又退回去」。

序号 · sequence + pendingSequences

识别是并发的(limit=2),完成顺序天然不等于音频顺序。落定时分配递增序号,先进 pendingSequences 字典,只有当 nextExpectedSequence 存在时才出队追加到 meeting.segments。一个晚到的 5 号会等在字典里,直到 0–4 都到齐。

为什么没有 VAD

代码注释写得很直白:能量阈值在复杂声学环境下不可靠(噪声爬升漏检、切句点断词)。VAD 的误判会直接变成「漏字」或「断词」,而这类错误用户无法自行修正。改用固定节奏 + 文本标点后,最坏情况只是分段粒度不理想,文本本身仍完整——把不可恢复的错误降级为可恢复的瑕疵,这是整条流水线里最值得抄的一个决策。

05分层与职责边界

22 个 Swift 文件、2,893 行。分层不是按「MVC」切的,而是按「谁依赖谁的隔离域」切的——读依赖方向比读目录名有用。

层 / 文件行职责边界约束
入口 MinutesApp65窗口、设置场景、启动与退出钩子测试宿主下不启动模型(检测 XCTestCase 是否存在)
表现层 · 913 行
ContentView106三栏骨架、工具栏、空状态只读 supervisor 状态决定按钮可用性,不发起引擎操作
SidebarView92会议列表、删除确认删除按钮常驻占位、只切透明度,避免布局跳动
LiveMeetingView105状态条、波形、暂停/继续/结束只调 session 的方法,不直接碰 client
TranscriptView93分段列表、interim 灰字、自动滚底按 sequence 排序后再渲染,双保险
MinutesView228纪要四节、转写原文、重生成、标题编辑长转写按行 LazyVStack;DateFormatter 静态缓存
SettingsView183模型路径、端口、Prompt、诊断日志路径即时校验并给出可读错误
EngineStatusControl106工具栏状态灯 + 启停菜单把两个 worker 的多态折叠成一个总体状态
领域与会话 · 713 行
MeetingSession421状态机、节奏识别、切段、纪要编排@MainActor;不 import SwiftUI,状态靠 @Observable 投影
MinutesComposer145提示词、分块、map-reduce、四节解析纯函数集合,无副作用,可单独单测
MeetingsStore63会议列表加载、保存、删除文件名只由会议 id 决定,反复保存不产生重复文件
Models84Meeting / TranscriptSegment / MinutesDocument / 错误类型全部 Codable + Sendable,无行为
引擎接入 · 891 行
EngineWorker415单进程生命周期、健康探测、日志泵、退避重启@unchecked Sendable + NSLock;健康探测跑在 detached Task
EngineConfiguration177路径、端口、Prompt、配置迁移@unchecked Sendable(UserDefaults 本身线程安全)
EngineClient168WAV 上传、SSE 流式对话actor;全应用唯一发网络请求处
EngineSupervisor66两个 worker 的状态与日志聚合@MainActor @Observable;日志环形上限 2000 行
EngineHealth65把两种上游健康响应归一为三态无状态纯函数,路径比较前做符号链接归一
传输与编码 · 194 行
OpenAIStreamParser105逐字节 SSE 状态机值类型 struct;[DONE] 缺失即抛错,不保存半篇
WAVEncoder50float32 → PCM16 WAV拒绝 NaN/Inf;超长直接抛错而不是静默截断
ASRServerConfiguration39按当前配置生成 audio.cpp 的 JSON每次启动重写;请求体上限 8 MiB
采集与基础设施 · 117 行
AudioCaptureService98麦克风采集、重采样、RMS实时音频线程只做转换与 yield,不做任何 IO
Log19os.Logger 分四个 category无自定义日志框架,接系统 Console

依赖方向

依赖是一条单向链,没有回边:Views → MeetingSession → EngineClient → HTTP,而 EngineSupervisor 与 MeetingSession 之间是平级注入而非包含。这点在代码里体现得很具体——MeetingSession 持有 engineSupervisor 的引用是为了读 states 和 baseURL,它并不命令 supervisor 去启动引擎;启停是用户在工具栏或设置里做的独立操作。

好处是「引擎没就绪」这个条件可以优雅降级:start() 检查不到 ASR ready 就设 errorMessage 返回,composeMinutes() 检查不到 LLM ready 就只保留转写原文并写一句提示。整条链路没有一处假设引擎一定可用。

06引擎生命周期与自愈

四个状态、五条转移。真正值得看的是两条边上的策略差:为什么一种退出要重试,另一种绝对不重试。

stopped 无进程 · 不占端口 starting 拉起中 / 等外部服务 ready 身份校验通过 · 可服务 failed(message) 保存可读原因 UI 直接展示,不吞异常 start() · 校验通过 探测到健康且身份匹配 进程意外退出 / 外部服务消失 退避后重试 ready 态退出才走这条边 环境变量已清理 DYLD_* 外部服务转 5 s 存活监测 无进程句柄时只报错不重试
图 3 EngineWorker 的状态机。注意 starting → failed 与 ready → failed 落进同一个状态,但后续行为完全不同:前者不重试,后者退避重试。区分逻辑在 handleTermination 里。

为什么「启动即退出」不重试

如果 starting 阶段进程就退出了,几乎一定是配置问题:模型文件不存在、端口被占、GGUF 与二进制不匹配。这类错误重试一万次也是同样的结果,只会把 CPU 吃满、把日志刷爆、且用户看不到真正原因。所以代码在这里直接返回,把日志留给用户看:

// EngineWorker.swift:243 — 两种退出,两种待遇
if case .ready = state {
    state = .failed("\(kind.runtimeName) 意外退出,正在自动重启…")
} else if case .starting = state {
    // 启动即退出通常是模型、端口或配置错误,先展示日志,不做崩溃循环
    state = .failed("\(kind.runtimeName) 启动即退出,详见日志")
    return
} else { return }

failureCount += 1
let backoffNanos = UInt64(3 * min(1 << min(failureCount, 4), 16)) * 1_000_000_000
连续失败次数1234≥5
退避等待6 s12 s24 s48 s48 s(封顶)

封顶 48 秒而非无限增长,是因为本地推理进程的典型故障(显存不足、模型被外部删除)恢复后重试就能成功,长退避只会让用户以为「卡住了」。成功进入 ready 时 failureCount 归零,下次崩溃仍从 6 秒起步。

应用级启动编排

AppDelegate 做了一件不太显眼但很实用的事:启动 3 秒后,对仍处于 failed 的 worker 再试一次。

原因是上一个应用实例的模型进程可能还在退出过程中——用户按 Cmd+Q 后立刻重开,旧进程还占着 8797/8788,新实例的健康探测会判 incompatible(「端口被占用」)。等 3 秒后旧进程通常已释放端口,重试即成功。这比「无条件重试」克制,也比「让用户自己点重试」友好。

只重试 failed 的、不重试 ready 的,也不会打断正在正常加载的引擎。

07并发模型:五个隔离域,各管一件事

Swift 6 的严格并发检查会逼着人做选择。这个项目没有「一刀切全上 actor」,而是按「这段代码能不能阻塞」分成五类——这是全文技术含量最高的一节。

隔离域承载者为什么是它
主 actor Views、MeetingSession、EngineSupervisor @Observable 的变更通知与 SwiftUI 渲染必须在主线程;状态机的相位推进也只在这里发生,天然串行
自定义 actor EngineClient、TranscriptionGate 保护 URLSession 的调用与信号量计数。两者都不做阻塞操作,纯 async/await,适合 actor
detached Task 健康探测、退避重启、外部服务监测 健康探测内部用 DispatchSemaphore 同步等 HTTP 返回。如果继承 MainActor,就会把 UI 冻住 1.5 秒
NSLock EngineWorker 的进程句柄与状态、HealthResponseBox 这些读操作需要同步返回(如 isStarting(signature) 在 guard 里用),改成 async 会污染整条调用链
实时音频线程 AudioCaptureService.handleInput CoreAudio 回调线程,不能 await、不能分配锁。只做格式转换、算 RMS、continuation.yield

关键一处:为什么 EngineWorker 不是 actor

直觉上「进程管理器」最像 actor。但它的健康探测是这样写的:

// EngineWorker.swift:372 — 同步等待,不能放进 actor
private func fetch(_ path: String) -> (data: Data?, response: HTTPURLResponse?) {
    let semaphore = DispatchSemaphore(value: 0)
    let result = HealthResponseBox()
    URLSession.shared.dataTask(with: request) { data, response, _ in
        result.store(data: data, response: response as? HTTPURLResponse)
        semaphore.signal()
    }.resume()
    semaphore.wait()          // ← 阻塞当前线程直到超时(1.5 s)
    return result.load()
}

在 actor 里 semaphore.wait() 会独占该 actor 的执行器线程,而回调 store(...) 又要进同一个 actor——直接死锁。所以这里是 @unchecked Sendable + NSLock + 在 Task.detached 里跑的经典组合。代码里那句注释就是结论:健康探测内部有信号量等待,不能继承 MainActor。

反直觉但正确

这里用同步阻塞 HTTP 换取的是「状态判断的原子性」:探测结果、签名比对、状态跃迁在一个不可打断的片段里完成。如果改成 async,就会多出若干个 await 挂起点,每个挂起点都可能让用户改配置、让旧 Task 完成——那才是真正的竞态温床。代价是 1.5 秒的线程占用,但它在 detached 线程上,不影响 UI。

主线程为什么不会被网络请求堵住

MeetingSession 标了 @MainActor,整条流水线看起来都在主线程跑。实际上不会阻塞,因为:

  1. pipelineTask 虽然继承 @MainActor 隔离,但它在 for await chunk in stream 处挂起,把主线程交还出去;每块音频回来只做几十微秒的数组追加。
  2. client.transcribe(...) 是跨 actor 调用,await 期间主 actor 完全空闲,SwiftUI 正常渲染。
  3. SSE 逐字节解析(streamChat)跑在 EngineClient 的 Task 里,只有解析出的文本块才 yield 回主 actor 追加到 composedText。

换句话说,主线程承担的是「状态变更」,不是「数据传输」。这是 @MainActor 用得对不对的分水岭:把状态放主线程是必须的,把等待放主线程才是错的。

日志的跨域投递

worker 的 stdout/stderr 由 readabilityHandler 在任意线程上泵出,要进 @MainActor 的 EngineSupervisor.logs。做法是 Task { @MainActor in ... },并在每行带上 Date() 时间戳——因为经过调度后到达顺序不保证严格等于产生顺序,靠时间戳而不是数组位置来表达真实次序。日志环形上限 2000 行,超出丢最旧,长时间挂机不会吃内存。

08数据模型与持久化

没有任何数据库。一场会议一个 JSON 文件,键名有序输出,可以直接 cat、可以 diff、可以手工修。

三层结构

Meeting 是根,包含元信息、分段数组、可选纪要和一份冗余的纯文本转写:

Meeting
├── id: UUID                 // 同时是文件名
├── title: String            // 空则由 LLM 生成,失败回退「M月d日 HH:mm 会议」
├── createdAt: Date          // ISO8601 编码
├── duration: TimeInterval
├── segments: [TranscriptSegment]
│     ├── start / end        // 相对会议开始的秒数
│     ├── text
│     ├── language           // 引擎自报,可能为 nil
│     └── sequence           // 落定顺序,用于归位与排序
├── minutes: MinutesDocument?
│     ├── summary            // 摘要正文
│     ├── decisions[]        // 决议条目
│     ├── actionItems[]      // 行动项条目
│     └── keywords[]         // 关键词
└── transcriptText: String   // 冗余:所有分段用 \n 拼起来

transcriptText 是刻意的冗余。它让「重新生成纪要」不必遍历分段重拼,也让旧版本数据(只有分段、没有该字段)能靠 segments.map(\.text).joined() 平滑兼容——MinutesView 里就是这个兜底写法。

文件名策略里的一次事故

代码注释里的真实 bug

fileURL(for:) 上面写着:文件名只由会议 id 决定:同一次会议反复保存只落一个文件,反复 save 不会产生带不同时间戳前缀的重复文件。 而在 MeetingSession.init 里还有另一段注释,记录了更严重的问题:

曾共用 store.draft 的副本,所有新会议 id 相同,后一个会把前一个在列表和磁盘上整体覆盖——「新建会议把上一个会议整没了」的元凶。

两处注释合起来说明一件事:标识符策略必须与持久化策略一起设计。id 复用会让「保存」变成「覆盖」,而这类 bug 在 UI 上表现为「数据莫名其妙消失」,极难归因。

写入的原子性

data.write(to:options: .atomic) + JSONEncoder.outputFormatting = [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes]。三个选项各有明确目的:

加载侧是「宽松解析」:compactMap { try? decoder.decode(...) },单个文件损坏只会少一场会议,不会导致列表整体加载失败。这是本地文件存储的正确姿势——一份坏数据不该拖垮全部。

配置迁移

EngineConfiguration 维护 engineConfigurationVersion(当前为 2)。迁移逻辑只处理一件具体的事:把两个旧硬编码默认路径(MLX 的 HF 缓存目录、旧 qwenasr-studio 的模型目录)一次性改写成新的 GGUF 默认路径,自定义路径原样保留。

这里有个细节值得注意:testEmptyDefaultsDoNotFreezeEnvironmentDrivenModelRoot 这个测试在断言——空配置时不要往 UserDefaults 里写值。因为一旦写了,后续 MINUTES_MODELS_ROOT 环境变量就再也不会生效(getter 优先返回已存的值)。「默认值不应该被固化成显式配置」,这是配置系统里最容易踩的一脚。

09供应链:把「可复现」写成脚本

从「git clone 一下」到「一条命令得到字节级可验证的引擎」,中间隔着一份锁文件、两个脚本和一道 otool 门禁。

锁文件:所有不确定性收敛到一处

Engine/dependencies.lock 是个 19 行的 Bash 片段,被两个脚本 source 进去。它同时锁住了源码版本与模型版本:

锁定项值作用
audio.cpp commit6f71a3b87105b974…ASR 服务源码
llama.cpp commit513ad7ae0770cdd7…LLM 服务源码
ASR 模型 revision7a103b33f0412053…Qwen3-ASR-1.7B Q8_0
ASR 字节数 / SHA2562,473,017,600 / 3bc2462e…完整性校验
LLM 模型 revisione87f176479d0855a…Qwen3.5-4B Q4_K_M
LLM 字节数 / SHA2562,740,937,888 / 00fe7986…完整性校验

关键在于镜像只影响传输路径,不影响验收标准。下载脚本列了三个来源(ModelScope 镜像 → hf-mirror → Hugging Face 官方),逐个尝试;无论从哪个来源拿到,最终都必须通过锁文件里的字节数与 SHA256。这解决了国内网络环境下的真实痛点,又没有牺牲可验证性。

构建脚本的四道门

① 工具存在性

逐个检查 git cmake clang++ xcrun curl install otool codesign tar,以及 metal 编译器。缺任何一个都在第 0 秒失败,而不是编译到一半。

② 源码获取三路

git fetch --depth 1 优先;失败则下载同提交的 tarball;再失败则用已经验证过的本地归档。每路都写 .minutes-source-commit 印记。

③ 二进制卫生

otool -L 扫产物,出现 Python.framework、Torch、MLX、ffmpeg、/opt/homebrew 即报错退出。确保「零 Python」不是口号。

④ 原子安装

先 install -m 755 到 .name.installing,再 mv 覆盖,最后 ad-hoc codesign。应用运行中升级不会读到半个可执行文件。

构建配置本身也是「够用就好」的取向:关掉 tests、examples、UI、CURL、OpenSSL,只留 server;BUILD_SHARED_LIBS=OFF 生成静态链接,避免 dyld 找库问题;GGML_METAL_EMBED_LIBRARY=ON 把 metallib 嵌进二进制,省掉运行时定位资源目录的麻烦。

下载脚本:把「断点续传」做对

没有用 huggingface-cli,也没有 pip。只用 curl、shasum、stat、xargs,代价是要自己处理分块。几个细节说明作者踩过坑:

拼装后做一次全文件 SHA256,不符则清理全部分块并报错。宁可让用户重下 2.5 GB,也不让一个损坏的 GGUF 进入推理路径——后者会导致难查的乱码输出。

脚本里的安全习惯

两个脚本开头都检查 id -u,发现是 root 立刻退出并说明原因:引擎装在当前用户的 ~/Library/Application Support/Minutes,用 sudo 跑会改为查 root 的目录,结果是应用找不到文件。这条提示同时出现在 README 里,属于「一定会有人踩」的坑。

10验证体系:三层,从纯逻辑到真实推理

6 个单元测试文件、359 行,一个 XCTest 宿主之外的冒烟程序。三层各自负责一种失败模式,谁都不越界。

层手段守住什么
纯逻辑单测WAVEncoderTests、OpenAIStreamParserTests、MinutesComposer 解析字节级正确性:WAV 头 44 字节、−32767 的位模式、UTF-8 跨字节不破、CRLF 与多行 data
契约单测EngineClientTests(URLProtocol 打桩)、EngineHealthTests、EngineConfigurationTests请求形状(multipart 头、model=minutes-llm、stream=true)、身份校验拒绝旧服务、配置迁移不冻结默认值
真实闭环scripts/verify_native.sh + Benchmarks/NativeWorkerSmoke真进程、真模型、真音频:两个 worker 就绪、ASR 关键词命中、LLM 四节格式、map-reduce 产出摘要

为什么闭环验证要绕开 XCTest

verify_native.sh 用 swiftc 直接把 9 个源文件和一个 main.swift 编成一个独立可执行文件,不经过 XCTest 宿主。理由写在脚本注释和 README 里:XCTest 宿主下环境变量常常传不进去,导致依赖 MINUTES_SMOKE_ASR 的断言静默跳过——测试显示「全部通过」,实际什么也没验。

这是一类容易被忽视的假绿:XCTSkip 和「条件不满足就 return」都会让 CI 显示绿灯,但覆盖面为零。绕开宿主是最彻底的修法。

三道断言都是内容级的,不是「有没有返回」级的:

测试里的巧思

EngineWorkerTests 要验证「启动即退出应立刻 failed,而不是等 180 秒超时」。它把 /usr/bin/false 复制成假的 audiocpp_server——一个必定以非零码退出的可执行文件——然后断言 5 秒内进入 failed。用系统自带二进制构造失败场景,不需要 mock 框架,也不需要真的模型。

11性能基线:一次诚实的迁移复盘

从「PyTorch/MPS + MLX」换到「audio.cpp + llama.cpp 原生 Metal」,六个指标里五个变好、一个变差。这个变差被写进了文档,而不是从表里删掉。

旧版 原生 每行以旧版 = 100% 归一化 0 50% 100% 120% ASR · 11.4 秒音频 1.061 s 0.545 s ASR · 25 秒音频 1.909 s 0.957 s LLM · 单次纪要总耗时 2.996 s 2.755 s LLM · 生成速度 85.30 tok/s 80.76 tok/s ASR · phys_footprint 6,245 MB 3,065 MB LLM · phys_footprint 3,543 MB 1,284 MB 琥珀色这一行是唯一的退步:纯生成速度下降约 5%,不能宣称「原生全面更快」。 ASR 与 LLM 的内存取 phys_footprint 口径;两者的 RSS 反而上升,所以要并列看。
图 4 六项指标的归一化对比(旧版 = 100%)。ASR 是这次迁移的最大受益者:两种音频长度下耗时都降到约一半,footprint 降 51%。LLM 则是「总耗时小幅改善、纯生成速度小幅退步」的混合结果。
指标旧版原生变化判读
ASR 11.4 s 音频1.061 s(RTF 0.093)0.545 s(RTF 0.048)−49%明显改善
ASR 25 s 音频1.909 s(RTF 0.076)0.957 s(RTF 0.038)−50%长音频优势稳定
LLM 首 token(TTFT)0.366 s0.024 s−93%含 prompt cache 命中,不能直接比
LLM 总耗时2.996 s2.755 s−8%小幅改善
LLM 生成速度85.30 tok/s80.76 tok/s−5%退步
ASR footprint6,245 MB3,065 MB−51%显著改善
LLM footprint3,543 MB1,284 MB−64%显著改善
ASR RSS约 1.02 GiB约 3.09 GiB+202%口径相反,需并列看
LLM RSS约 3.37 GiB约 3.87 GiB+15%同上

为什么不能只报一个内存数字

文档里同时保留 ps RSS 与 phys_footprint,并明确写出「两种口径均保留,避免把 mmap/统一内存差异误写成单一的内存结论」。这是很专业的克制:

量化带来的质量差异,也被写下来了

同一个 25 秒样本,旧版开头识别为「数据合在一起…总出力…」,新版为「时聚合在一起…总处理…」,新版还多出「核电状态」。文档的结论是:

原文结论

主体内容一致,但个别词错误说明 Q8 不能视为与 FP16 完全等价,后续仍应使用带人工校对文本的会议集评估 CER。

同时它也明确写了「当前样本没有人工校对参考文本,因此本表不虚构 CER/WER」。在一个很容易吹指标的领域里,这两句比任何数字都更能说明工程素养。

方法学

为了可复现,基准测试本身是代码:Benchmarks/NativeWorkerSmoke/main.swift 在真实进程上跑,TTFT 用服务器返回的 prompt_ms、生成速度用服务器 token 计数(不拿字符数换算 token)。每个样本预热 1 次、测 5 次取中位数并给出范围。RSS 是采样值不是峰值监控,文档也如实标注了这一点。

12边界与技术债

这一节按「多久会开始咬人」排序,而不是按好修程度排。第一条是读代码时发现的真实缺陷,建议优先实机复现。

#问题位置表现严重度
1 暂停/继续的时间基准不一致 MeetingSession.swift:99,203,243 恢复后长时间不再出字;分段时间戳回退到 00:00 附近 高
2 分块不拆超长单行 MinutesComposer.swift:43 单行超过 12000 字符时块预算失效,可能撑爆上下文 中
3 写盘失败被静默吞掉 MeetingsStore.swift:49 磁盘满或权限异常时会议未落盘,UI 无任何提示 中
4 长会议 map 阶段串行 EngineWorker.swift:131 --parallel 1,两小时会议要跑 N 次串行压缩 中
5 无 CI 仓库根 6 个测试文件靠本机 Xcode 手跑,回归全凭自觉 中
6 旧路径常量含开发者绝对路径 EngineConfiguration.swift:53 迁移逻辑只在作者本机命中;开源仓库暴露用户名 低
7 默认端口写死 EngineConfiguration.swift:17 8797/8788 被占需手动改,改完要重启对应 worker 低
8 沙箱未启用 project.pbxproj CODE_SIGN_ENTITLEMENTS 为空;无法上架 App Store 设计选择

第一条展开:为什么暂停会打断识别

这不是风格问题,是一条能推出具体症状的路径。三个事实串起来:

  1. pause() 只是取消采集任务并停止引擎,既不清空 buffer,也不冲刷它;
  2. resume() 走 start(),音频 offset 的基准被重新设为 startTime = Date(),即从 0 重新计;
  3. appendToBuffer 只在 buffer.isEmpty 时才更新 bufferStart。

于是恢复后的第一块音频会让 bufferStart 保持暂停前的旧值(例如 1234.5 秒),而 bufferEnd 变成 0.28 秒,bufferLength 直接成为负数。轮询条件是 bufferLength - lastPollAt >= 1.5,负值永远不满足,识别就此静默停止,直到 offset 重新长过暂停前的累计时长。

// MeetingSession.swift:99 — 只有 buffer 为空才重置起点
private func appendToBuffer(_ chunk: CapturedChunk, offset: TimeInterval) {
    if buffer.isEmpty { bufferStart = offset }   // ← 恢复后 buffer 仍非空,这里不执行
    buffer.append(contentsOf: chunk.samples)
    bufferEnd = offset + Double(chunk.samples.count) / 16000.0
    var bufferLength = bufferEnd - bufferStart   // ← 0.28 - 1234.5 < 0
    if bufferLength - lastPollAt >= pollInterval { ... }   // ← 永不成立
}
建议的复现与修法

复现:开一场会议,说 2–3 分钟让 bufferStart 累积到较大值,点暂停,10 秒后点继续,然后持续说话——正常情况下应每 1.5 秒更新一次灰色 interim 文本,实际会长时间没有任何新字。

修法:pause() 里把缓冲一并处理掉(要么 await flushBuffer() 落定,要么直接清空并重置 bufferStart/lastPollAt)。后者更简单,代价是最多丢 1.5 秒音频;前者更完整,但 pause 目前是同步方法,需要改成 async 或起一个 Task。

说明:以上由静态代码路径推断,未做运行时复现。同一根因还会让恢复后的分段时间戳从 00:00 重新开始,与顶部的会议计时脱节。

第二条展开:分块函数的隐含前提

makeBlocks 按行累加,块间不拆行——这个设计的理由是「保证每块语义完整」,本身是对的。但它隐含假设「单行不会超过预算」。转写文本是 ASR 输出,正常情况下每段几十字,不会触发;但如果将来接入「粘贴一份完整会议记录」或「导入字幕文件」,一行一万多字的情况立刻会让 current 单块超预算,进而在 32768 上下文里挤掉输出空间。

修法很轻:在 line.count > maxChars 时把该行按字符切开,或直接把 maxChars 作为硬上限做二次切分。

这些是边界,不是缺陷

13结论与文件索引

三条判断

第一,这套架构的价值在于「把不确定性关进笼子」。模型会崩、端口会被占、识别结果会乱序、用户会在会议中途改配置——每一件都被一个具体机制接住了:进程隔离、三重身份校验、序号归位、启动签名。没有一处用「正常情况下不会发生」来搪塞。

第二,它的复杂度花在了正确的地方。2,893 行里,接近 900 行在引擎接入与进程管理,只有 913 行在界面。对一个「本地推理应用」来说这个比例是对的——难的不是画界面,是让一个会崩溃的模型在用户机器上表现得像一个稳定功能。

第三,它最值得学习的是文档纪律。README 写「当前边界」,基准文档写「这一项退步了」,代码注释写「这里曾经有个 bug 导致新建会议把上一个整没了」。这些不是装饰,它们让下一个人(或下一次的自己)不必重新踩一遍。

如果要继续演进

优先级建议:先修暂停/继续的时间基准(用户可感知的功能缺陷),再补 CI(防止回归),然后考虑下载脚本的断点续传可观测性(目前分块进度只在 stdout)。至于换更大模型、加说话人分离、开沙箱上架——这些都是产品决策,不是架构债。

文件索引

想改什么看这里行数
采集参数、重采样Minutes/Audio/AudioCaptureService.swift98
识别节奏、切段规则、分段归位Minutes/Meeting/MeetingSession.swift421
纪要提示词、分块、四节解析Minutes/Meeting/MinutesComposer.swift145
会话列表与 JSON 读写Minutes/Meeting/MeetingsStore.swift63
进程拉起、健康探测、退避重启Minutes/Engine/EngineWorker.swift415
身份校验规则Minutes/Engine/EngineHealth.swift65
HTTP 请求形状Minutes/Engine/EngineClient.swift168
SSE 逐字节解析Minutes/Engine/OpenAIStreamParser.swift105
WAV 头与 PCM16Minutes/Engine/WAVEncoder.swift50
端口、模型路径、Prompt、迁移Minutes/Engine/EngineConfiguration.swift177
audio.cpp 的 JSON 配置Minutes/Engine/ASRServerConfiguration.swift39
数据模型与错误类型Minutes/Core/Models.swift84
原生引擎构建scripts/bootstrap.sh134
模型下载与校验scripts/download_models.sh145
真进程闭环验证scripts/verify_native.sh + Benchmarks/NativeWorkerSmoke/main.swift28 + 79
版本与校验和锁定Engine/dependencies.lock19