# 版本与兼容性

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

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

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

## SDK 版本策略

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

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

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

### 内测期(0.x)

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

### 正式 1.0 之后

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

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

## API 契约演进

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

### 内测期

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

### 正式开放后

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

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

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

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

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

## 废弃流程

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

  
    1

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

  

  
    2

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

  

  
    3

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

  

## 系统要求

只调用服务端三组接口时,只需要一个能发 HTTPS 请求的运行时,[教程后端篇](/docs/embedded/tutorial-backend/)用的是 Node.js 20.6 及以上。下表其余各项在 SDK 开放后适用,口径与 [iOS SDK](/docs/embedded/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](/docs/embedded/android-sdk/) 页公布,并同步到开通邮件。

## 如何关注变更

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

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

[MCP & CLI 更新日志 记忆 MCP 与规划组件的版本记录入口。录音／逐字稿类工具、一键安装器与 CLI 规划中,尚未开放。 查看更新日志](/docs/mcp-cli/changelog/)

当前记忆 MCP 的接入说明见[记忆 MCP 文档](/docs/mcp-cli/mcp/)。邮件通知发送到开通时登记的邮箱;换人对接时请通过[联系我们](/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
```