# 变更记录

格式参照 Keep a Changelog，版本号规则见 COMPATIBILITY.md。各端的详细变更见各端目录下的 CHANGELOG.md。

来源：https://open.shengzhiai.com/sdk/v2/changelog/

## 版本 `2.1.2`，2026-10-13

只发了安卓 `com.stkouyu` 与 iOS `STKouyuEngine` 两个声通平替，其余五端仍为 `2.1.0`。

### 新增
- 声通兼容接口新增中文开放题 `open.eval.cn`，与原生 `coreType` 为 `open` 同一套评分。`refText` 与声通相同，可以是用竖线隔开的参考答案，也可以是题目，由评分模型判断，是参考答案时意思一致就算答对，短答不扣分。`qType` 5 与 6 分别按看图说话与情景问答评，其他按自由表达评，`keypoints` 与 `keywords` 为采分点。结果另有声通的 `pronunciation`，`fluency`，`integrity`，`coherence`，`speed`。两个平替层放开这个内核，实时评测不下发朗读进度。

## 版本 `2.1.1`，2026-10-13

只发了安卓 `com.stkouyu` 与 iOS `STKouyuEngine` 两个声通平替，其余五端仍为 `2.1.0`。

### 变更
- 平台侧：声通兼容接口固定内容题型的 `words` 只含参考文本里的字词，增读与重复读在请求带 `readtype_diagnosis=1` 时才给，计分不变。
- 两个平替层默认边录边传：麦克风录音与送流走兼容实时评测，不再等录音结束才整段上传。安卓 `YuguCompat.setStreamUpload(false)`，iOS `YuguCompat.streamUpload = NO` 时恢复录完整段上传。`realtime_feedback` 只决定有没有朗读进度回调。
- 安卓平替层的实时连接协商 `permessage-deflate`，终评结果压缩传输。iOS 由系统网络库协商。
- 日志级别为 INFO 时每次评测记一行分段耗时，含上传，等待，下载，解析与服务端各环节耗时，DEBUG 时另记引擎各环节。安卓的日志设置在 `initEngine` 之后修改也立即生效。

### 新增
- 平台侧：兼容接口的 REST 响应头带 `Server-Timing`，请求带 `timing=1` 时结果顶层附 `timing`，格式见 `CONTRACT.md` 3.3 节。兼容接口不再合成示范音。

### 兼容性
- 与 `2.1.0` 源码兼容，二进制兼容，替换版本号即可升级。交给应用的结果 JSON 不变。

## 版本 `2.1.0`，2026-10-12

### 新增
- 实时评测朗读进度：原生实时评测的开始帧带 `realtimeFeedback`，声通兼容实时评测的参数帧带 `realtime_feedback` 时，平台边收音边下发进度帧，参考文本逐字或逐词给出 `read` 与 `matched`，另有 `readUnits`，`matchedUnits` 与 `totalUnits`，格式见 `CONTRACT.md` 5.5 节。
- 五端 SDK 的 `onPartial` 带朗读进度，原生实时评测新增 `realtimeFeedback` 选项，断线重连后回调的进度不倒退。
- 安卓 `com.stkouyu` 与 iOS `STKouyuEngine` 平替层支持 `realtime_feedback`：打开后边录边传，录音过程中多次回调，`eof` 为 0 的结果是朗读进度，结束后回调 `eof` 为 1 的终评。iOS 平替层的这项能力需要 iOS 13。
- 平台侧：两条实时评测通道下发朗读进度帧，终评与计费不变。

### 变更
- 声通兼容实时评测的进度帧在 `bytes` 之外增加朗读进度字段，只读 `bytes` 的 `2.0.0` 客户端不受影响。

### 兼容性
- 与 `2.0.0` 源码兼容，二进制兼容，替换版本号即可升级。

## 版本 `2.0.0`，2026-10-08

### 新增
- 五端写操作自动带幂等键，重试与实时评测重连复用同一个键，平台按键只评测一次，只计费一次。
- 可配置的重试策略，默认重试 2 次，指数退避加随机抖动，尊重 Retry-After，只对可重试错误生效，重试事件可观测。
- 实时评测会话状态机，自动重连，REPLAY，DROP，FAIL 三种音频缓冲策略，心跳，终评超时，结构化事件回调。
- 十六类错误分类与对应异常类型，统一错误码表 `ERRORS.md`，公开的可重试判定函数。
- 客户端，会话，录音器的释放接口与状态查询。
- 日志级别与指标回调。
- 上传前音频预检。
- 网页与小程序 TypeScript 声明。
- 安卓 `com.stkouyu` 与 iOS `STKouyuEngine` 声通平替层，附接口比对工具。
- 自建 Maven 仓库，npm 源与 SwiftPM 仓库，持续集成与公开构建记录。
- 沙箱密钥，`SANDBOX.md`。
- OpenAPI 描述 `spec/openapi.yaml`，供其他服务端语言生成客户端。
- 平台侧：兼容整段评测，语音合成，两条实时评测接入幂等键，实时评测应用层心跳，错误帧带错误码，新错误码 40901，40902，40903，42903。
- 平台侧：兼容接口支持 `attachAudioUrl`，返回录音下载地址，保留 7 天。
- 平台侧：段落题参考文本只有一句时返回一个分句。

### 变更
- 包名与仓库坐标统一为 `com.shengzhiai.yugu` 与 `@shengzhiai`，默认基址改为 `https://open.shengzhiai.com`。
- 许可改为 Apache-2.0。
- 平台侧：额度不足的错误码由 40900 改为 40902，HTTP 状态仍为 409。
- 平台侧：原生实时评测以 appKey 签名握手时按次计费，评测记录归属密钥所属账号，按 recordId 可以查到报告，并发与额度限制与原生整段评测一致。

### 修复
- 小程序原生整段评测恒报 HTTP 415。
- 安卓只签部分 config 字段导致签名失败。
- iOS 整数值小数字段签名与发送不一致。

### 破坏性变更
- 包名与坐标变化，迁移见 `MIGRATION-2.0.md`。
- 网页 SDK 移除 `streamRealtime`。

## 版本 `1.0.0`，2026-06-24

### 新增
- 首个版本，五端整段评测，语音合成，报告查询，原生与声通兼容实时评测，签名与 token 两种鉴权。