参考

版本与兼容性

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

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

适用范围:「API 契约演进」与「废弃流程」两节适用于现已可用的服务端三组接口(认证 / 文件上传 / 转写)。「SDK 版本策略」一节所述的 SDK 尚未开放,下述规则在开放后适用。

SDK 版本策略

Embedded SDK(iOS / Android / React Native 桥)规划中,尚未开放,目前没有可取用的版本;以下是开放后适用的版本策略,供你提前评估升级与依赖锁定成本。开放时间以开通邮件为准。

SDK 开放后遵循语义化版本,版本号形如 主版本.次版本.修订号。

SDK 开放时按 0.x 内测版本起步(版本号在开放时随开通邮件与更新日志公布)。按语义化版本惯例,0.x 允许在次版本中引入破坏性变更。内测期的每次破坏性变更都会提前通过联调渠道与开通邮箱通知,并附迁移说明。

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

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

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

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

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

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

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

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

公告

在更新日志发布废弃公告,并向开通时登记的邮箱发送邮件通知,写明替代方案与迁移说明。

过渡期

公告后进入过渡期,旧接口与新接口并行可用,期间旧接口只修缺陷、不加能力。过渡期的具体时长会在正式开放时公布;内测期以联调口径为准。

下线

过渡期结束后移除旧接口,并在更新日志中记录下线时间。此后调用旧接口会返回明确的错误码。

只调用服务端三组接口时,只需要一个能发 HTTPS 请求的运行时,教程后端篇用的是 Node.js 20.6 及以上。下表其余各项在 SDK 开放后适用,口径与 iOS SDK 页一致,以该页与正式发布说明为准。

项目	要求	状态
Node.js(服务端接口与教程后端篇)	20.6 及以上	现已可用
iOS 部署目标	iOS 15.0 及以上(以正式发布说明为准)	SDK 开放后适用
Xcode	15 及以上	SDK 开放后适用
Swift	5.9 及以上	SDK 开放后适用
React Native 桥	计划支持 Expo prebuild 工作流,具体版本要求随开通邮件说明	规划中
测试设备	需真机 iPhone。SDK 以 arm64 真机框架分发,模拟器不支持设备联调	SDK 开放后适用
硬件	一张 iKho S1 录音卡(硬件规格以量产规格为准)	SDK 开放后适用

Android SDK 规划中,尚未开放;系统要求会在开放时于 Android SDK 页公布,并同步到开通邮件。

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

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

MCP 服务与命令行工具的版本更新记录。该能力规划中,尚未开放。

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

文档站在 /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

这一页有帮助吗?