iOS 声通平替

版本与环境#

接入步骤#

需要移除的声通文件#

1. 在 Xcode 工程里删除 STKouyuEngine.framework 与 libskegn.a，同时删除 Build Phases 里对二者的链接与嵌入设置。
2. 用 CocoaPods 接入声通的工程，在 Podfile 里删掉 pod '17kouyu-tt' 一行，再执行 pod install。
3. 工程里自带的 skegn.h 副本可以保留，声明与本包相同。

SwiftPM 依赖#

在 Xcode 菜单 File > Add Package Dependencies 填入包地址 https://open.shengzhiai.com/git/stkouyu-ios-compat.git，规则选 Up to Next Major Version，起始版本 2.1.2，把产品 STKouyuEngine 加到应用 target。

用 Package.swift 管理依赖的工程这样写：

dependencies: [
    .package(url: "https://open.shengzhiai.com/git/stkouyu-ios-compat.git", from: "2.1.2"),
],
targets: [
    .target(name: "App", dependencies: [
        .product(name: "STKouyuEngine", package: "stkouyu-ios-compat"),
    ]),
]

代码与密钥#

导入写法不变：

#import <STKouyuEngine/STKouyuEngine.h>
#import <STKouyuEngine/KYTestEngine.h>
@import STKouyuEngine;

import STKouyuEngine

1. KYStartEngineConfig 的 appKey 与 secretKey 换成优谷雅言控制台的密钥。联调期间用沙箱密钥，说明见优谷雅言 SDK 仓库根目录的 SANDBOX.md。
2. server 留空或保留声通地址时，请求发往 https://open.shengzhiai.com。私有部署或联调环境写 https:// 开头的完整地址。
3. 应用原有的 NSMicrophoneUsageDescription 继续生效，平替包不需要新增权限声明。

生命周期示例#

Objective-C：

#import <STKouyuEngine/KYTestEngine.h>

@interface ReadingViewController () <KYTestEngineDelegate>
@end

@implementation ReadingViewController

- (void)setUpEngine {
    KYStartEngineConfig *config = [[KYStartEngineConfig alloc] init];
    config.appKey = @"优谷雅言 appKey";
    config.secretKey = @"优谷雅言 secretKey";
    config.vadEnable = YES;
    [KYTestEngine sharedInstance].delegate = self;
    [[KYTestEngine sharedInstance] initEngine:KY_CloudEngine
                            startEngineConfig:config
                                  finishBlock:^(BOOL isSuccess, NSString *str) {
        NSLog(@"init %d %@", isSuccess, str);
    }];
}

- (void)startReading {
    KYTestConfig *test = [[KYTestConfig alloc] init];
    test.coreType = KYTestType_Sentence_Cn;
    test.refText = @"今天天气很好";
    test.duration = 10000;
    NSString *tokenId = [[KYTestEngine sharedInstance] startEngineWithTestConfig:test result:^(NSString *testResult) {
        NSData *data = [testResult dataUsingEncoding:NSUTF8StringEncoding];
        NSDictionary *json = [NSJSONSerialization JSONObjectWithData:data options:0 error:NULL];
        if (json[@"errId"]) {
            NSLog(@"errId %@ %@", json[@"errId"], json[@"error"]);
        } else {
            NSLog(@"overall %@", json[@"result"][@"overall"]);
        }
    } finishBlock:^(BOOL isSuccess, NSString *str) {
        NSLog(@"start %d %@", isSuccess, str);
    }];
    NSLog(@"tokenId %@", tokenId);
}

- (void)stopReading {
    [[KYTestEngine sharedInstance] stopEngine];   // 结束录音并评测，结果回到 result block
}

- (void)leavePage {
    [[KYTestEngine sharedInstance] cancelEngine]; // 放弃本次评测，不再回调
}

- (void)shutDown {
    [[KYTestEngine sharedInstance] deleteEngine]; // 释放引擎，可重复调用，之后需要重新 initEngine
}

@end

Swift：

let engine = KYTestEngine.sharedInstance()!
let config = KYStartEngineConfig()
config.appKey = "优谷雅言 appKey"
config.secretKey = "优谷雅言 secretKey"
engine.initEngine(KY_CloudEngine, startEngineConfig: config) { ok, message in print(ok, message ?? "") }

let test = KYTestConfig()
test.coreTypeNS = "sent.eval"
test.refText = "How are you"
let tokenId = engine.start(with: test, result: { json in print(json ?? "") }) { ok, str in print(ok, str ?? "") }
engine.stop()
engine.delete()

Swift 里的方法名由编译器按头文件推导，与使用声通 framework 时相同。编译器去掉方法名里与类名 KYTestEngine 重复的 Engine，也去掉参数名末尾的 Block，常用方法的 Swift 写法如下：

onScoreBlock 保留 Block，是编译器的推导结果。上面的示例与全部方法的 Swift 写法都写在 Tests/STKouyuEngineTests 里，随测试一起编译。

评测内核#

coreTypeNS 不为空时优先于 coreType。

其余内核在本地回调 errId 60003，不发网络请求，包括 open.eval，choice.rec，asr.rec，asr.eval，align.eval，法语，日语与韩语内核，KYTestType_Wordspell，以及声通内核以外的名字。

refText 为空时回调 errId 60006。中文内核与 pinyin 设置了 refPinyin 时可以不设 refText，open.eval.cn 除外。

中文开放题#

2.1.2 起支持 open.eval.cn。KYTestType 没有这个内核的成员，要用 coreTypeNS 指定。平台按原生开放题评分，看内容，语言运用与表达三项，语言固定为中文。

KYTestConfig *test = [[KYTestConfig alloc] init];
test.coreTypeNS = @"open.eval.cn";
test.refText = @"我是学生|我不是学生";
test.qType = KYQType_SituationalReply;

结果 JSON 的 result 含原生开放题的全部字段：overall 总分，content 内容，languageUse 语言运用，delivery 表达，transcript 识别文本，feedback 点评，含义见仓库根目录 RESULTS.md 的开放题一节。openTaskAudit.refKind 为 answers 时评分模型把 refText 当参考答案，为 question 时当题目。另有与声通相同的扁平字段 pronunciation，fluency，integrity，coherence 与 speed，speed 为每分钟字数。结果里没有逐字的 words 与 sentences。录音同样边录边传，realtime_feedback 为 YES 时中间结果只有已收音频的字节数 bytes，没有朗读进度。

参数映射#

评测请求为 POST {平台地址}/{coreType}，multipart/form-data，文本字段不带文件名，音频为 audio 文件字段。签名覆盖全部非空文本字段。

customParams 的值转成文本的规则：字符串原样，布尔值为 true 或 false，整数不带小数点，小数取最短形式，数组与字典为 JSON 文本。

只在本机生效的属性：

照收但不生效的属性：

初始化参数#

KY_NativeEngine 与 KY_MultiEngine 照收，按云端评测，打印警告日志。KY_CloudServer_Release 与 KY_CloudServer_Gray 为声通文档里的两个地址，作为 server 时都改用 https://open.shengzhiai.com。

回调规则#

全部回调在主线程，按发生顺序回调。一次评测在结果回调里收到一份结果 JSON 或错误 JSON，realtime_feedback 为 YES 时在此之前还会收到若干份 eof 为 0 的朗读进度 JSON，见朗读进度一节。调用 cancelEngine 或 deleteEngine 之后这次评测不再有任何回调。结果回调指 testResultBlock 或 onScoreBlock，同时回调代理的 kyTestEngineDidScore:。

开始成功时 finishBlock 收到 YES 与 tokenId，录音与 feed 模式随后回调 onStartBlock 与 kyTestEngineDidRecordStart。开始失败时 finishBlock 收到 NO 与错误 JSON，其余回调与安卓平替层一致：

录音过程的回调：

1. 录音结束时回调 onRecordEndBlock，kyTestEngineDidRecordEnd 与 kyTestEngineDidRecordWriteAudioResult:。音频已在录音过程中上传，随后发出剩余音频与结束帧，等待评测结果。YuguCompat.streamUpload 为 NO 时此时整段上传，见边录边传一节。
2. 设置 duration 后每隔 durationInterval 回调剩余毫秒与剩余百分比，百分比取值 0 到 100，到时结束录音。
3. vadEnable 为 YES 时回调 vad_status 与 sound_intensity。vad_status 为 0 表示没开始说话，1 表示说话中，2 表示说话结束。说话后静音达到 seek 乘以 10 毫秒即判定结束，录音模式随即结束录音。soundIntensityEnable 为 NO 时 sound_intensity 为 0，为 YES 时取 0 到 100。
4. forceRecord 为 YES 时 VAD 与 duration 都不结束评测。到达 duration 时停止录音，保留音频，调用 stopEngine 后才上传。
5. 电话等系统打断录音时回调 onPauseBlock，打断结束后继续录音。
6. audioPath 模式开始后立即上传，文件不可读与音频不合格都以错误 JSON 回到结果回调。

其他接口：

结果 JSON#

{"tokenId":"3f0b6a1c9d2e4f5a8b7c6d5e4f3a2b1c","recordId":"eval_77c081e19541","applicationId":"优谷雅言 appKey",
 "userId":"u1","refText":"今天天气很好","eof":1,"dtLastResponse":"2026-10-08 16:21:32:255",
 "result":{"overall":94.6,"pronunciation":100,"fluency":96,"integrity":100,"words":[]},
 "params":{"app":{"applicationId":"优谷雅言 appKey","userId":"u1","timestamp":"1791447692"},
           "audio":{"audioType":"wav","sampleRate":16000,"channel":1,"sampleBytes":2},
           "request":{"coreType":"sent.eval.cn","tokenId":"3f0b6a1c9d2e4f5a8b7c6d5e4f3a2b1c","refText":"今天天气很好","phoneme_output":"1"}}}

1. result 为平台兼容接口返回的评测结果，原样转交，常用取分字段与声通同名。只有一处补充：平台把逐字得分放在 sentences[].details[].scores 里，声通示例直接读取 details[].overall，所以 details[] 里缺少 overall 的条目在末尾补上取自 scores.overall 的 overall，条目没有 pronunciation 时一并补上取自 scores.pronunciation 的 pronunciation。原有的键不改不删，其余内容逐字节不变。
2. recordId 为平台评测记录号，平台没有返回时不出现。
3. params 只在 getParam 为 YES 时出现。audioUrl 只在 attachAudioUrl 为 YES 时出现，位于 JSON 末尾，取值为平台返回的录音下载地址，原样转交。平台保留录音 7 天，到期删除，需要长期保存的录音在 7 天内下载，或用 getLastRecordPath 取本机录音。同一 tokenId 重复提交时平台返回同一个地址。
4. para.eval 与 para.eval.cn 一律请求逐字得分，结果总带 result.sentences[].details[]。
5. dtLastResponse 为本机时区收到结果的时刻，格式 yyyy-MM-dd HH:mm:ss:SSS。

边录边传#

录音模式与 feed 模式默认边录边传：音频在录音过程中经声通兼容实时评测接口 wss://{平台地址}/{coreType} 上传，stopEngine 时只剩最后一小段音频与结束帧，平台随即评测，不再等录音结束后整段上传。录音文件照旧写入 recordPath，getLastRecordPath 与回放不变。

1. feed 模式要求 audioType 为 wav 或 pcm，sampleRate 为 16000，channel 为 1，sampleBytes 为 2，其他格式在 stopEngine 之后整段上传。audioPath 模式总是整段上传。
2. 需要 iOS 13 或更新版本，iOS 12 上照旧整段上传，日志级别为 info 时打印一行原因。
3. 不打开 realtime_feedback 时参数帧不带 realtime_feedback，平台不下发进度，结果回调只收到终评 JSON，与整段上传时相同。打开时回调朗读进度，见朗读进度一节。
4. 结束帧发出之前连接失败，例如握手被拒，断网或心跳超时，stopEngine 之后用同一个 tokenId 整段上传评测，日志级别为 warn 时打印失败原因。结束帧发出之后连接失败时按朗读进度一节第 8 条重新连接。同一个 tokenId 只评测一次，只计费一次。
5. YuguCompat.streamUpload 设为 NO 之后开始的评测与 2.1.0 相同，录音结束后整段上传。realtime_feedback 为 YES 的评测仍然边录边传，回调朗读进度。

#import <STKouyuEngine/YuguCompat.h>

YuguCompat.streamUpload = NO;   // 录音结束后整段上传，与 2.1.0 相同，默认 YES

import STKouyuEngine.YuguCompat

YuguCompat.streamUpload = false

压缩#

1. 整段上传的评测结果：NSURLSession 自动在请求头带上 Accept-Encoding: gzip, deflate, br，回调之前自动解压，平台对评测结果做 gzip 压缩，1.5 MB 的段落结果在网络上约 120 KB。平替包不改这个请求头。
2. 边录边传的终评帧：平替包使用系统的 NSURLSessionWebSocketTask，由系统自行在握手里提出 permessage-deflate，平台接受后终评帧压缩传输，系统解压之后交给平替包。系统同时压缩上行的音频帧。平替包不另写 WebSocket 实现，也不改握手里的这个请求头，系统没有提出时终评帧不压缩传输。
3. 是否提出由系统版本决定，Apple 的接口文档没有说明。Apple 开发者论坛上 Apple 技术支持工程师的答复与抓包显示 URLSession 的 WebSocket 握手带 Sec-WebSocket-Extensions: permessage-deflate，出处与核对情况见验证状态一节。
4. 分段耗时日志里 deflate 表示这一次协商成功，gzip 表示整段上传的结果经 gzip 压缩，wire 为结果在网络上的字节数。系统不报告终评帧在网络上的字节数，边录边传时 wire 记为 -。

朗读进度#

KYTestConfig.realtime_feedback 设为 YES 时，录音与 feed 模式的评测经声通兼容实时评测接口 wss://{平台地址}/{coreType} 边读边上传音频，参数帧带 realtime_feedback。平台在收音过程中回报参考文本里读到了哪里，平替包把进度以 eof 为 0 的 JSON 交给结果回调，与终评使用同一个回调，结构同声通 realtime_feedback 的中间结果。界面可以据此让参考文本跟随朗读位置。终评 JSON 与不打开时相同，同一个 tokenId 只评测一次，只计费一次。

{"tokenId":"3f0b6a1c9d2e4f5a8b7c6d5e4f3a2b1c","recordId":"","applicationId":"优谷雅言 appKey","userId":"u1",
 "refText":"北京你好","eof":0,"dtLastResponse":"2026-10-12 14:03:21:456",
 "result":{"kernel_version":"1.0.0","resource_version":"1.0.0",
  "words":[{"charType":0,"scores":{"pronunciation":100,"skipped":0,"tone":100,"overall":100,"overall_pron":100},
            "word":"京","word_parts":[{"beginIndex":0,"charType":0,"endIndex":0,"part":"京"}]}],
  "bytes":48000,"readUnits":2,"matchedUnits":2,"totalUnits":4,
  "progress":[{"word":"北","read":true,"matched":true},{"word":"京","read":true,"matched":true},
              {"word":"你","read":false,"matched":false},{"word":"好","read":false,"matched":false}]}}

1. 中文按字，去掉标点与空白。英文按空白分词，去掉词首词尾的标点，词内的撇号与连字符保留。coreType 以 .cn 结尾或为 pinyin 时按字，其余按词，customParams 带 language 时按 language 判断。
2. 读到新的字或词时平台立即下发进度，此外大约每 0.5 秒音频下发一次。没有新读到内容的进度不回调，只有字节数的进度也不回调。进度一般比朗读晚 1 到 2 秒，随网络情况变化。
3. stopEngine 发出结束帧之后，平台对最后一段音频再识别一次，句末的几个字以进度回调送达，然后才是终评。终评之后不再有进度回调。
4. 朗读进度只对 16 kHz 16 位单声道 PCM 生效。录音模式总是满足，feed 模式要求 audioType 为 wav 或 pcm，sampleRate 为 16000，channel 为 1，sampleBytes 为 2。audioPath 模式与其他音频照旧整段评测，不回调进度。
5. 需要 iOS 13 或更新版本。iOS 12 上照旧整段评测，不回调进度，日志级别为 info 时打印一行说明。
6. 参考文本为空或平台当时无法跟踪进度时，这一轮没有进度回调，终评不受影响。
7. 结束帧发出之前连接失败，例如握手被拒，断网或心跳超时，平替包关闭连接，不再回调进度，录音照常进行，stopEngine 之后用同一个 tokenId 整段评测，与 YuguCompat.streamUpload 为 NO 时相同。平台没有收到结束帧时不评测，不计费。
8. 结束帧发出之后连接失败或终评超时，平替包用同一个 tokenId 重新连接，重发参数帧，全部音频与结束帧。重连次数与整段评测的重试次数相同，默认 2 次，用尽后回调与整段评测相同的错误 JSON，errId 为 20009。平台按 tokenId 只评测一次，重放期间平台从第一个字重新计算进度，已经回调过的字或词按位置去掉，不会重复回调。
9. 握手的 query 带 appKey，timestamp，nonce，idempotencyKey 与 signature，签名算法与整段评测相同，参数帧为参数映射一节的表单字段加 realtime_feedback，日志级别为 info 或 debug 时另加 timing，最后是 idempotencyKey。结束帧发出之前每 15 秒发一次协议层 ping，30 秒收不到 pong 视为断线。

按朗读进度给参考文本着色#

#import <STKouyuEngine/KYTestEngine.h>
#import <UIKit/UIKit.h>

/// 按 result.progress 给参考文本着色：已读且对上为绿色，已读未对上为橙色，未读为灰色
static NSAttributedString *ColoredRefText(NSString *refText, NSArray<NSDictionary *> *progress) {
    NSMutableAttributedString *text = [[NSMutableAttributedString alloc]
        initWithString:refText attributes:@{NSForegroundColorAttributeName : UIColor.grayColor}];
    NSUInteger from = 0;
    for (NSDictionary *unit in progress) {
        NSRange r = [refText rangeOfString:unit[@"word"] options:0 range:NSMakeRange(from, refText.length - from)];
        if (r.location == NSNotFound) break;
        from = NSMaxRange(r);
        if (![unit[@"read"] boolValue]) continue;
        [text addAttribute:NSForegroundColorAttributeName
                     value:[unit[@"matched"] boolValue] ? UIColor.greenColor : UIColor.orangeColor
                     range:r];
    }
    return text;
}

static void StartReadingWithProgress(UILabel *label) {
    KYTestConfig *test = [[KYTestConfig alloc] init];
    test.coreType = KYTestType_Sentence_Cn;
    test.refText = @"我是中国人，我是中国人。我们都是中国人。中华民族是一家人。";
    test.realtime_feedback = YES;
    label.attributedText = ColoredRefText(test.refText, @[]);
    [[KYTestEngine sharedInstance] startEngineWithTestConfig:test
        result:^(NSString *testResult) {
            NSData *data = [testResult dataUsingEncoding:NSUTF8StringEncoding];
            NSDictionary *json = [NSJSONSerialization JSONObjectWithData:data options:0 error:NULL];
            if ([json[@"eof"] integerValue] == 0) {
                label.attributedText = ColoredRefText(test.refText, json[@"result"][@"progress"]);
            } else if (json[@"errId"]) {
                NSLog(@"errId %@ %@", json[@"errId"], json[@"error"]);
            } else {
                NSLog(@"overall %@", json[@"result"][@"overall"]);
            }
        }
        finishBlock:nil];
}

result.progress 每次都是全部字或词的最新状态，整段重新着色即可。只需要跟随朗读位置时，取 result.readUnits，或者累加各次回调 result.words 的个数。示例与测试一起编译，副本在 Tests/STKouyuEngineObjCSupport 里。

错误 JSON 与 errId#

{"tokenId":"3f0b6a1c9d2e4f5a8b7c6d5e4f3a2b1c","errId":20009,"error":"网络或服务端临时故障，可重评，autoRetry 默认重评此码: HTTP 503 code=50000 system busy (attempts 3)","eof":1,"applicationId":"优谷雅言 appKey"}

错误响应体没有错误码时按 HTTP 状态取码：401 为 40100，403 为 40300，404 为 40400，409 为 40900，501 为 50010，其他 4xx 为 40001，其他 5xx 为 50000，其余状态为 90005。完整错误码表见优谷雅言 SDK 仓库根目录的 ERRORS.md。

error 字段：errId 20009 时依次为 20009 的含义，HTTP 状态与错误码，平台消息与尝试次数，其他 errId 为平台消息或本机检查的说明。

重试与自动重评#

1. 每次评测的 tokenId 同时作为请求头 Idempotency-Key，重试与自动重评都用同一个 tokenId。平台对同一个 tokenId 只计费一次，重复提交得到第一次的结果。
2. 网络错误，超时，可重试的 HTTP 状态与可重试的错误码自动重试，一次提交最多 3 次请求，两次重试的间隔约 200 毫秒与 400 毫秒，上下浮动 30%。响应带 Retry-After 时至少等待该时长，最多 30 秒。重试与等待限定在一次评测 300 秒的总时限内，下一次重试会越过总时限时不再重试，直接回调错误 JSON。
3. 400 等不可重试的错误不重试，直接回调错误 JSON。
4. autoRetry 为 YES 时，错误 JSON 的 errId 落在 errIds 里的评测用同一个 tokenId 重新提交，最多 2 次。errIds 默认为 @[@"20009"]，元素可以是字符串或数字。
5. YuguCompat 可以调整重试次数与总时限。

与声通 SDK 的行为差异#

C 接口#

skegn.h 的声明与声通公开的 skegn.h 相同，由本包实现，替换 libskegn.a。直接调用 C 接口的代码不用改，#include "skegn.h" 可以继续使用工程里的副本，也可以改为 #import <STKouyuEngine/skegn.h>。Swift 用 import STKouyuEngine.skegn。

request 成员转成文本的规则：字符串原样，JSON 布尔值为 1 或 0，数字取最短形式，数组与对象为 JSON 文本。request.getParam 为真时结果带上 params，request.autoRetry 为真时按 errId 20009 自动重评。回调里可以调用 skegn_cancel 与 skegn_start。

朗读进度与边录边传只在 KYTestEngine 上提供。C 接口照旧在 skegn_stop 之后整段评测，request 里的 realtime_feedback 与其他成员一样作为表单字段发送，不回调进度。日志级别为 info 时同样每次评测打印一行分段耗时。

扩展配置#

声通接口以外的配置集中在 YuguCompat.h，不改变原有声明。

#import <STKouyuEngine/YuguCompat.h>

YuguCompat.baseURL = @"https://sandbox.example.com";   // 优先于 KYStartEngineConfig.server，nil 取消
[YuguCompat setLogLevel:YuguCompatLogLevelDebug];      // 优先于 KYStartEngineConfig.logLevel
[YuguCompat setLogHandler:^(NSInteger level, NSString *message) { /* 写入应用自己的日志 */ }];
YuguCompat.maxRetries = 2;      // 一次提交内的重试次数，0 到 5
YuguCompat.totalTimeout = 300;  // 一次评测的总时限，单位秒
YuguCompat.streamUpload = YES;  // 录音与 feed 边录边传，默认 YES，见边录边传一节
NSLog(@"%@ %@", YuguCompat.sdkVersion, YuguCompat.effectiveBaseURL);

Swift 用 import STKouyuEngine.YuguCompat。

日志#

1. 级别 0 为 error，1 为 warn，2 为 info，3 为 debug，默认 warn，与 KYLOG_ERROR，KYLOG_WARN，KYLOG_INFO，KYLOG_DEBUG 的取值相同。
2. isOutputLog 为 YES 时写控制台，sdkLogEnable 为 YES 时另外写入 sdkLogPath，默认 Documents/sdkLog.txt。
3. 日志不含 secretKey，签名与音频内容，appKey 只记前 4 位。
4. 应用调用 KYLog 的内容写入同一日志。
5. warn 级别下评测成功时不打印日志。需要看评测各步骤耗时时打开 info 级别，见分段耗时一节。

打开日志#

声通文档里的写法照样生效：sdkLogEnable 设为 YES，logLevel 设为 2，日志级别为 info，日志写入控制台与 sdkLogPath。

KYStartEngineConfig *config = [[KYStartEngineConfig alloc] init];
config.sdkLogEnable = YES;   // 写入日志文件
config.logLevel = 2;         // info，每次评测打印一行分段耗时
config.sdkLogPath = [NSTemporaryDirectory() stringByAppendingPathComponent:@"sdkLog.txt"]; // 可选，默认 Documents/sdkLog.txt

1. 日志文件默认在应用沙盒的 Documents/sdkLog.txt，在 Xcode 的 Devices and Simulators 窗口下载应用容器即可取出，模拟器上直接在 xcrun simctl get_app_container booted <bundle id> data 给出的目录里查看。
2. [YuguCompat setLogLevel:YuguCompatLogLevelInfo] 覆盖 logLevel，setLogHandler: 把日志交给应用自己的日志系统，交给 handler 时不再写控制台，文件照写。
3. C 接口在 skegn_new 的 cfg 里写 "sdkLog":{"enable":1,"level":2,"output":"<日志文件路径>"}，level 也接受 error，warn，info，debug 这几个名称。

分段耗时#

日志级别为 info 或 debug 时，每次到达平台的评测在结果回调开始之后打印一行 timing，字段与安卓平替层相同。此时请求另带 timing=1，实时评测的参数帧另带 "timing":1，平台在结果里附上平台侧耗时，平替包读取之后从结果中去掉，应用收到的结果 JSON 与 warn 级别时相同。warn，error 与关闭日志时不请求，不打印。

timing tokenId=3f0b6a1c9d2e4f5a8b7c6d5e4f3a2b1c mode=ws audio=31.20s afterStop=1830ms upload=120ms wait=1610ms download=- parse=40ms deliver=3ms handshake=85ms queued=6400B final=1532118B wire=- deflate server.total=1321ms server.engine=1100ms server.platform=221ms
timing tokenId=9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d mode=rest audio=12.30s afterStop=6150ms upload=1884ms wait=4120ms download=85ms parse=40ms deliver=10ms attempts=1 sent=394012B body=1532118B wire=122880B gzip server.total=3910ms server.engine=3700ms server.platform=210ms

1. 不明的值记为 -。
2. debug 级别另外打印两行：phases 为各阶段相对第一个阶段的时刻，engineStages 为平台评测引擎各环节的耗时与平台收到请求的时刻。
3. 判断慢在哪一步：afterStop 接近 server.total 时时间花在平台评测上，server.engine 占大头时花在评测引擎上。upload 大说明上行慢，结束录音时积压的音频看 queued。wait 减去 server.total 约为网络往返与终评帧的下载。整段上传时 download 大说明下行慢。

头文件一致性核对#

tools/headers-diff.py 随包发布，接入方可以用手上的声通 framework 核对两边的公开接口是否逐项一致。只需要 Python 3.7 或更新版本，不依赖第三方库。

# 克隆本包后在包目录执行，第二个参数默认为本包的头文件目录
python3 tools/headers-diff.py /path/to/STKouyuEngine.framework/Headers
# 连同 skegn.h 一起比对，参数名不同也算差异
python3 tools/headers-diff.py --original /path/to/STKouyuEngine.framework/Headers \
    --original /path/to/skegn.h --strict --json headers-diff.json

比对内容：类与父类，协议与继承关系，属性及其修饰符与类型，方法的选择子，返回类型与参数类型，协议方法的 @optional 与 @required，枚举的成员与取值，typedef 与 block 类型，结构体，外部常量与函数及其属性宏，宏的取值，头文件保护宏，以及 framework 内部头文件之间的导入。注释，空白与换行不影响结果，UIKit 与 Foundation 等系统头文件的导入不比对。

退出码：0 表示一致，1 表示有差异，2 表示参数错误或无法解析。只存在于本包的 YuguCompat.h 列出但不比对。

验证状态#

Linux 上的结果与沙箱用例截至 2026-10-13，对应 2.1.2。macOS 构建机上的结果截至 2026-10-13，对应 2.1.1，GitHub Actions 运行 38347556835 的 11 个作业全部通过。2.1.2 的 Objective-C 层只改了版本号与头文件注释：

常见问题#

skegn 符号重复的链接错误#

工程里还留着 libskegn.a，删除即可。本包已经实现全部 skegn_* 函数。

开始评测时的 60008 回调#

上一次评测还没有回调结果就开始了新评测。等结果回调之后再开始，或者先调用 cancelEngine。

结果里的声通字段#

外层字段与声通一致。result 内为优谷雅言评测结果，常用取分字段 overall，pronunciation，fluency，integrity，words 与声通同名，其余字段以优谷雅言接口文档为准。

私有部署与联调地址#

server 写 https:// 开头的地址，或设置 YuguCompat.baseURL。用 http:// 地址时应用需要配置 App Transport Security 例外，否则回调 errId 90011。

扩展名为 mp3 的 WAV 录音文件#

平替包不带 MP3 编码器。recordName 写 .mp3 时保留文件名，内容为 WAV，用 playback 或 AVAudioPlayer 都能正常播放。

应用自管的音频会话#

把 customized_avaudiosession 设为 YES，平替包不再设置 AVAudioSession。录音前需要应用把类别设为可录音的类别。

重复提交与计费#

同一次评测的重试与自动重评共用一个 tokenId，只计费一次。每次 startEngine 都生成新的 tokenId，算作新的评测。

收不到朗读进度#

依次核对：realtime_feedback 为 YES，系统为 iOS 13 或更新版本，评测为录音模式或 16 kHz 16 位单声道 PCM 的 feed 模式，参考文本不为空。条件不满足时平替包照旧整段评测，日志级别为 info 时打印原因。实时连接在结束帧之前失败时进度停止，日志级别为 warn 时打印原因，stopEngine 之后照常拿到终评。

停止录音之后等待时间长#

把日志级别设为 info，按日志一节的分段耗时一行判断慢在哪一步。mode 为 rest 时核对 YuguCompat.streamUpload 是否被设为 NO，系统是否为 iOS 13 或更新版本，feed 的音频是否为 16 kHz 16 位单声道 PCM。mode 为 ws>rest 时行末的 fallback 给出边录边传失败的原因。

许可#

Apache License 2.0，全文见 LICENSE，另见 NOTICE。声通与 17kouyu 是其各自权利人的名称，此处仅用于说明接口兼容关系。本包只按公开头文件重新实现，不含声通的实现代码，不分发声通的二进制文件。