iOS SDK 变更记录

版本 2.1.0，2026-10-12#

新增#

• 实时评测朗读进度：StreamPartial 新增 readUnits，matchedUnits，totalUnits，progress 与 hasProgress。progress 取自进度帧的 result.progress，按原文顺序列出参考文本的每个字或词，元素为新类型 ReadingWord，含 word，read 与 matched。没有进度时三个数为 -1，progress 为空数组。帧格式见 SDK 总仓库 CONTRACT.md 5.5 节。
• 原生实时评测新增选项 EvaluateConfig.realtimeFeedback，缺省为 false。打开后开始帧带 "realtimeFeedback": true，onPartial 回调朗读进度。不打开时开始帧与 2.0.0 一字不差，整段评测不发送这个字段。
• 声通兼容实时评测的 CompatParams.realtimeFeedback 仍发送 realtime_feedback，进度帧在 bytes 之外带朗读进度，另带声通格式的增量 words 与空的 recordId，这两项保留在 raw 中，逐字状态只取 result.progress。
• 断线重连后服务端从零重新计算进度。缓冲策略为 .replay 时，会话只回调 readUnits 与 matchedUnits 都不小于上一次回调的进度帧，界面上的进度不会倒退，没有回调的进度帧各写一条 DEBUG 日志。缓冲策略为 .drop 时，新的服务端会话只覆盖重连之后的音频，重连成功时清除记住的进度。不带进度的帧照常回调。

变更#

• onPartial 在原生与声通兼容两种会话上都会回调，end() 之后到终评之前仍会收到进度帧。
• 每个请求与握手带 User-Agent: yugu-ios-sdk/2.1.0，YuguSDKInfo.version 为 2.1.0。

兼容性#

• 与 2.0.0 源码兼容。EvaluateConfig 的新参数带缺省值，原有构造写法不变，只读 bytes 的代码不受影响。

版本 2.0.0，2026-10-08#

新增#

• 产品拆为 YuguCore 与 YuguSDK。YuguCore 只依赖 Foundation，可在 Linux 上构建与测试，YuguSDK 在其上加录音器。
• 写操作与实时会话自动带幂等键，重试与重连复用同一个键，结果带 idempotencyKey 与 replayed，平台对同一个键只计费一次。
• 重试策略 RetryPolicy：指数退避加随机抖动，遵守 Retry-After，总时限 totalTimeoutMs，重试事件进入日志与指标回调，公开的可重试判定 YuguErrors.isRetryable。
• 实时评测会话 YuguStreamSession：十种状态，断线自动重连 ReconnectPolicy，音频缓冲策略 REPLAY，DROP，FAIL，协议层心跳，握手超时与终评超时，结构化回调 YuguStreamListener。
• 实时会话的保护规则：超过 32000 字节的音频拆成小帧发送，整个会话的重连总数不超过 maxAttempts 的 3 倍，服务端以 1002，1003，1007，1008，1009，1010 或 4000 到 4999 之间的代码关闭时不重连。
• 错误类型 YuguError：十六个类别与对应的便捷属性，保留原始错误码，HTTP 状态，幂等键，尝试次数与响应原文。码表 ErrorTable 由 spec/errors.json 生成。
• 资源释放与状态查询：客户端 close()，会话 cancel() 与 close()，录音器 release()，均可重复调用，会话与录音器可随时查询状态。
• 录音器的暂停与继续，音频中断与路由变化处理，WAV 导出，640 字节分帧回调。
• 上传前音频预检，WARN 与 REJECT 两种方式，实时会话在 end() 时检查。
• 外部音频输入 AudioInput：内存数据，文件，裸 PCM。
• 日志级别，日志脱敏，指标回调 YuguEventListener。
• async 写法与任务取消，取消令牌 YuguCancellationToken。
• 连读题与开放题的结果模型 ConnectedScores 与 OpenTaskScores，段落题的逐句详情，结果保留原始 JSON。
• 语音合成与报告查询的结果模型 TTSResult 与 ReportResult。
• 支持 macOS 11，新增 CocoaPods 规格文件 YuguSDK.podspec，单元测试，集成测试与覆盖率报告。

变更#

• 默认基址改为 https://open.shengzhiai.com 与 wss://open.shengzhiai.com，wsBaseUrl 未设置时由 baseUrl 推出。
• 每个请求与握手带 User-Agent: yugu-ios-sdk/2.0.0。
• 语音合成的签名改为请求体顶层的标量字段，取值为实际发出的 JSON 文本，与各端一致。
• HMAC-SHA256 改用 SDK 自带的实现，不再依赖 CryptoKit。
• 响应改用 SDK 自带的 JSON 解析器，各系统版本上的行为一致。
• 许可改为 Apache-2.0。

修复#

• 签名修复：1.0.0 版把小数字段按 1.0 的形式签名，JSON 里写的却是 1，整数值的小数字段因此签名失败。2.0.0 版签名的对象是 config 分片的整段 JSON 文本，JSON 由 SDK 按固定顺序生成，整数值写成整数，发出的文本与签名的文本一字不差。
• 实时评测握手参数里签名值的 +，/，= 改为百分号编码，避免服务端把 + 解码成空格后验签失败。
• 报告查询的签名改为空参数集，recordId 是路径的一部分，不参与签名。
• 实时会话的结果与错误回调只触发一次，连接中断与服务端无响应都有回调，不再出现静默停住。

破坏性变更#

• 配置类型 YuguConfig 改为 YuguClientOptions，鉴权写法 .signature(appKey:secretKey:) 改为 .appKey(_:secretKey:)。
• 整段评测的参数 audioWav: Data 改为 audio: AudioInput，完成回调的错误类型改为 YuguError，返回值为可取消的 YuguCall。
• evaluateCompat 的参数改为 coreType:audio:params:，参数类型为 CompatParams。
• tts 返回 TTSResult，getReport 返回 ReportResult。
• EvalResult.dims 改名为 dimensions，warnings 由整数数组改为 YuguWarning 数组。
• 实时评测由 streamEvaluate(config:) 改为 streamEvaluate(config:options:listener:)，connect() 改为 start()，finish() 改为 end()，代理协议 YuguStreamDelegate 改为 YuguStreamListener，sendAudio 改为可抛出错误。
• 录音器的 onFrame 闭包改为监听器 YuguRecorderListener，stop() 返回 YuguRecording。
• CoreType 与 CompatCoreType 由枚举改为结构体，.sentence 等写法不变。
• Swift 工具链要求 5.9 起，最低系统版本仍为 iOS 13。

版本 1.0.0，2026-06-24#

新增#

• 首个版本：原生整段评测，声通兼容整段评测，语音合成，报告查询，原生与声通兼容实时评测，签名与 token 两种鉴权，AVAudioEngine 录音与 WAV 封装。