跳到正文
联系我们 开始接入
参考

版本与兼容性

Embedded SDK 与 API 的版本策略:内测期 0.x 的变更口径、正式开放后的兼容性承诺、废弃流程与系统要求。

本页说明 iKho Embedded 的版本号规则、API 契约如何演进、破坏性变更走什么流程,以及各端的系统要求。内测期与正式开放后的口径不同,两段都写清楚,便于你评估升级成本。

SDK 版本策略

Embedded SDK(iOS / React Native 桥)遵循语义化版本,版本号形如 主版本.次版本.修订号。

版本位递增时机对你的影响
主版本(major)发生不向后兼容的接口变更需要按迁移说明调整代码后再升级
次版本(minor)新增能力,已有接口保持兼容可直接升级,新能力按需接入
修订号(patch)缺陷修复与内部优化建议尽快升级,无需改代码

内测期(0.x)

当前 SDK 处于 0.x 内测阶段(见更新日志)。按语义化版本惯例,0.x 允许在次版本中引入破坏性变更。内测期的每次破坏性变更都会提前通过联调渠道与开通邮箱通知,并附迁移说明。

正式 1.0 之后

SDK 发布 1.0 后,同一主版本内保证向后兼容:已发布的公开接口不移除、不改语义;破坏性变更只随主版本号升级发布,并提前走下方的废弃流程。

锁定依赖版本的建议:内测期用精确版本(如 0.9.2)而非范围约束,升级时对照更新日志逐项确认;1.0 后可放宽到同一主版本内的范围约束。

API 契约演进

API(认证 / 文件上传 / 转写)的契约演进与 SDK 分开管理,规则如下。

内测期

接口契约以联调时提供的正式文档为准,文档站内容可能滞后于联调口径。内测期的契约变更(含破坏性变更)以联调通知为准,会同步记录到更新日志。

正式开放后

以下变更不算破坏性变更,可能在不升级版本的情况下随时发生:

  • 响应中新增字段
  • 请求中新增可选参数
  • 新增 API 端点或新增错误码
  • 调整错误信息的文案(错误码不变)

以下变更属于破坏性变更,一律走废弃流程,不会直接生效:

  • 移除或重命名已发布的字段、参数、端点
  • 修改字段类型或字段语义
  • 把可选参数改为必填,或收紧已发布的校验规则

写出前向兼容的客户端:解析响应时忽略未知字段;不依赖字段顺序;用错误码而非错误文案做分支判断。做到这三点,非破坏性变更不会影响你的应用。

废弃流程

正式开放后,任何破坏性变更按以下步骤推进。

1
公告
在更新日志发布废弃公告,并向开通时登记的邮箱发送邮件通知,写明替代方案与迁移说明。
2
过渡期
公告后进入过渡期,旧接口与新接口并行可用,期间旧接口只修缺陷、不加能力。过渡期的具体时长会在正式开放时公布;内测期以联调口径为准。
3
下线
过渡期结束后移除旧接口,并在更新日志中记录下线时间。此后调用旧接口会返回明确的错误码。

系统要求

以下要求与 iOS SDK 页的环境要求一致,以该页与正式发布说明为准。

项目要求
iOS 部署目标iOS 15.0 及以上(以正式发布说明为准)
Xcode15 及以上
Swift5.9 及以上
Node.js20.6 及以上(服务端示例、教程后端篇与 React Native 桥需要)
React Native 桥内测,支持 Expo prebuild 工作流,具体版本要求随开通邮件说明
测试设备需真机 iPhone。SDK 以 arm64 真机框架分发,模拟器不支持设备联调
硬件一张 iKho S1 录音卡(硬件规格以量产规格为准)

Android SDK 正在内测排期中,系统要求会随接口稳定后在 Android SDK 页公布。

如何关注变更

三个渠道,覆盖人读与机器读两种方式。

Embedded 更新日志

SDK 与 API 的版本更新、破坏性变更与废弃公告,倒序排列。

查看更新日志
MCP & CLI 更新日志

MCP 服务与命令行工具的版本更新记录。

查看更新日志

邮件通知发送到开通时登记的邮箱;换人对接时请通过联系我们更新收件人。

llms.txt:给 AI 客户端的索引

文档站在 /docs/llms.txt 提供全站页面索引,每个文档页另有同路径的 index.md 纯文本镜像。AI 客户端与 agent 可以订阅该索引,自动发现文档更新并读取任意页面的 Markdown 版本。

bash 
# 拉取全站文档索引
curl https://ikho.cn/docs/llms.txt

# 读取本页的 Markdown 镜像
curl https://ikho.cn/docs/embedded/versioning/index.md