生命周期与工具

资源释放与生命周期

releaseChannel()

public func releaseChannel()

说明：

• 释放当前翻译通道与当前会话相关资源。

• 会停止并释放当前通道引擎，取消未完成建房请求，异步关闭当前在线房间，并清理离线模型下载管理器等会话状态。

• 不会清空 sdkInit 的全局配置，也不会清空鉴权状态。

• 释放后可以重新创建新通道。

• 在线模式下，如果当前通道绑定了已创建的房间，SDK 会 fire-and-forget 调用关房流程；业务侧不需要再对同一房间重复调用 closeRoom(...)。

destroy()

public func destroy()

说明：

• 释放全局资源。

• 会释放当前通道、清空鉴权状态、清空全局配置、关闭诊断与网络监听。

• 调用后如果要继续使用 SDK，必须重新执行 sdkInit(_:)。

建议

• 页面级退出当前翻译会话时，优先使用 releaseChannel()。
• 应用彻底退出 SDK 使用场景时，再调用 destroy()。

---

可取消请求句柄

TmkSDKCancellable

public protocol TmkSDKCancellable {
    func cancel()
}

说明：

• 用于取消未完成的异步请求，例如语言列表请求、房间关闭请求等。

• 取消只影响尚未执行或尚未回调的任务；已经完成的服务端动作不会回滚。离线底层不支持中途取消的接口返回 nil，业务侧仍应等待 completion 的最终结果。

TmkAnySDKCancellable

public final class TmkAnySDKCancellable: TmkSDKCancellable {
    public init(onCancel: @escaping () -> Void)
    public func cancel()
}

一般业务方不需要主动创建，通常只需要持有 SDK 返回的 TmkSDKCancellable? 即可。

---

PCM 工具

TmkTranslationPCMTools 提供常用 PCM 工具方法：

public enum TmkTranslationPCMTools {
    public static func mixStereo16LE(left: Data, right: Data) -> Data?
    public static func mixMonoToStereo16LE(mono: Data, isLeft: Bool) -> Data?
    public static func splitStereoInterleaved16LE(_ stereo: Data) -> (left: Data, right: Data)?
    public static func pcm16LEToFloat(_ data: Data) -> [Float]
    public static func floatToPCM16LE(_ samples: [Float]) -> Data
}

用途说明：

• mixStereo16LE(left:right:)

  • 将左右单声道 PCM 合成为立体声交错 PCM。

• mixMonoToStereo16LE(mono:isLeft:)

  • 把单声道复制到左或右声道，生成立体声。

• splitStereoInterleaved16LE(_:)

  • 将立体声交错 PCM 拆成左右单声道。

• pcm16LEToFloat(_:)

  • 16-bit PCM 转浮点数组。

• floatToPCM16LE(_:)

  • 浮点数组转 16-bit PCM。

---

诊断能力

iOS 诊断日志由 TmkTranslationGlobalConfig 控制。诊断能力默认开启，默认等级为 .essential；如果业务不希望采集任何诊断文件，需要显式关闭。

配置	说明
setDiagnosisConfig(_:)	设置分级诊断日志配置，包括启用状态、采集等级、自定义根目录和音频采集开关。

示例：

let config = TmkDiagnosisConfig(
    enabled: true,
    level: .diagnostic,
    rootDirectory: nil,
    audioCaptureEnabled: false
)

诊断等级

等级	采集内容	保留策略
.essential	SDK 初始化/销毁、在线和离线鉴权结果、License 与离线包状态、创建/加入/关闭房间、切换语言、切换音色、翻译引擎切换、房间能力接口、错误、超时、创建房间前网络环境、严重网络异常。默认不采集普通 RTC/RTM/Audio/TTS 高频日志，不采集 ASR/MT partial，不创建 Agora 目录，不采集音频文件。	每个文件最大 10 MiB，超限后清理最旧完整日志行，目标清理约 20%；最多保留 10 次会话日志。
.diagnostic	包含 .essential，并增加 Agora 普通日志、常规网络状态、ASR/MT completed 或 final 结果、TTS 关键阶段日志。	仅保留 2 天内数据；单文件最大 10 MiB；滚动文件命名为 workflow.log、workflow1.log 等。
.trace	包含 .diagnostic，并增加 ASR/MT partial、RTC/RTM/Audio/TTS 追踪日志等高频数据；只有 audioCaptureEnabled=true 时才采集 PCM/WAV/Agora 音频文件。	仅保留 4 天内数据；单文件最大 10 MiB；滚动文件命名为 workflow.log、workflow1.log 等。

getDiagnosisDirectoryURL()

public func getDiagnosisDirectoryURL() -> URL?

返回值：

• 诊断目录 URL。

• 如果当前没有诊断目录，返回 nil。

说明：

• 只有诊断配置 enabled=true 时，SDK 才会产生诊断文件。

目录	说明
Library/sdk_diagnosis	SDK 诊断根目录。
Library/sdk_diagnosis/sdk.log	SDK 初始化、鉴权、License、离线包、销毁等全局诊断日志。
Library/sdk_diagnosis/network_status.log	网络环境、Agora 连接状态、丢包和严重网络异常日志。
Library/sdk_diagnosis/<conversation>/workflow.log	单次对话工作流日志，包括建房、入会、关房、语言/音色/引擎/能力接口、ASR/MT/TTS 关键事件和错误。
Library/sdk_diagnosis/<conversation>/Agora	Agora RTC/RTM 普通日志目录，仅 .diagnostic 和 .trace 按需创建。
Library/sdk_diagnosis/<conversation>/pcm 或 WAV 文件	音频诊断文件，仅 .trace 且 audioCaptureEnabled=true 时按需创建。

• 关闭诊断时，SDK 不采集诊断日志，也不采集 Agora RTC/RTM 日志。

• 切换诊断等级不会主动清理历史日志；清理只由保留策略、文件超限或磁盘紧张触发。

• SDK 诊断日志先进入有界内存队列，再由后台批量落盘；文件 I/O 不应阻塞 SDK 业务线程。应用退出、进入后台、释放通道或导出诊断目录时会尽量触发落盘。

• 磁盘紧张时，SDK 会优先清理 PCM/WAV/音频诊断文件和较旧的对话日志。

• getDiagnosisDirectoryURL() 返回 SDK 诊断根目录；业务可基于该 URL 自行打包和分享诊断文件。

• 分享或上传前，建议由业务方确认数据合规。

• 如需上传诊断目录，建议业务侧先完成用户授权、脱敏和访问控制。

诊断数据脱敏

诊断日志可能包含 licenseId、错误码、模型版本、包名和耗时等排障字段。SDK 会对 token、connect token、Agora app id、用户标识、license 等敏感字段做脱敏；上传诊断日志前仍需要完成用户授权、业务侧脱敏复核和访问控制，不应记录或上传原始 License、clientSecret、设备私钥或完整用户隐私数据。

示例：

guard let diagnosisURL = TmkTranslationSDK.shared.getDiagnosisDirectoryURL() else {
    return
}
print(diagnosisURL)

数据安全与凭据管理

凭据安全

• appId / clientSecret 是业务鉴权凭据，建议通过独立配置或 CI 注入，避免写入公开仓库。
• clientSecret 会参与本地 License 加密/解密，变更后旧 License 可能无法继续解密。SDK 会尝试重新请求 License；如果设备处于离线状态，业务侧应提示用户联网后重新调用 verifyAuth(_:)。
• 设备密钥由 tmk-offline 组件维护，密钥 tag 通过组件接口获取。业务侧不应硬编码 tag，也不应在 Release 版本调用调试清理能力。

---