# 版本与兼容性

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

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

## SDK 版本策略

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

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

### 内测期(0.x)

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

### 正式 1.0 之后

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

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

## API 契约演进

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

### 内测期

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

### 正式开放后

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

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

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

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

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

## 废弃流程

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

  
    1

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

  

  
    2

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

  

  
    3

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

  

## 系统要求

以下要求与 [iOS SDK](/docs/embedded/ios-sdk/) 页的环境要求一致,以该页与正式发布说明为准。

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

Android SDK 正在内测排期中,系统要求会随接口稳定后在 [Android SDK](/docs/embedded/android-sdk/) 页公布。

## 如何关注变更

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

[Embedded 更新日志 SDK 与 API 的版本更新、破坏性变更与废弃公告,倒序排列。 查看更新日志](/docs/embedded/changelog/)

[MCP & CLI 更新日志 MCP 服务与命令行工具的版本更新记录。 查看更新日志](/docs/mcp-cli/changelog/)

邮件通知发送到开通时登记的邮箱;换人对接时请通过[联系我们](/docs/mcp-cli/contact/)更新收件人。

### 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
```