# 版本与兼容

## SDK 版本语义

**SDK 版本跟随内核的中版本，patch 位恒为 `.0`。**

整条内核 `1.1.x` 线（1.1.0、1.1.1、1.1.7…）共用 **SDK 1.1.0**；
只有内核进入 `1.2.0` 这种中版本跃迁时，SDK 才升到 1.2.0。

这样插件作者只需关心「我在为哪个中版本写插件」，不必跟着内核的每个 bugfix 换依赖。
当前内核声明的兼容上限是 **SDK 1.3.0**。

## 版本历史

| SDK | 内核 | 变化 | 需要重编？ |
|---|---|---|---|
| **1.3.0** | 1.4.0+ | 驻留子 agent、`RecallPolicy` 等 | 想用新 API 才需要 |
| **1.2.0** | 1.2.0 / 1.3.x | `InjectOptions{NoMemory, ContextPolicy}`、六个 `*Opts` 变体、`ChannelDef.ContextPolicy` | 不需要 |
| **1.1.0** | 1.1.x | 多模态贯通：`Triple.SentenceText`、`Doc.Attachments`、`MediaAttachment`、`InsertWithMedia`、媒体注入方法 | 不需要 |
| **1.0.0** | 1.0.0+ | **运行模型变更**：C ABI 动态库 → 子进程 + 共享内存 | **需要** |

### 1.0.0 是唯一一次破坏性变更

- `.so` / `.dylib` / `.dll` **不再被加载**，遇到旧产物会跳过并报可操作错误（不崩溃）。
- **业务代码不用改一行** —— 公开 SDK 接口零改动，用新版 `hmapdev` 重编即可。
- 产物从 `plugin.so` 变为 `plugin.bin`；不再需要 cgo。

### 1.1.0 / 1.2.0 是纯追加

两次都是**新增方法由插件调用、内核实现**，不调就不受影响。
零值 `InjectOptions` 与旧的三参数方法完全等价，因此存量插件**不需要改、也不需要重编**；
想用新字段的重编即可。

!!! tip "什么时候必须重编"
    只有一种情况：**内核跨了主版本**（如 1.x → 2.x）。
    主版本跃迁是破坏性变更的定义，此后的帧格式与共享段布局都不兼容，
    必须用配套 `hmapdev` 重编。

    **中版本跃迁（如 1.1 → 1.2）不需要重编**：1.x 内的新增全部是
    「插件调用、内核实现」，不调新面就不受影响。

## 协议兼容性：只认主版本号

**没有独立的协议版本号。** 兼容性由双方版本号的**主版本段**表态：
内核的 `meta.Version` 与插件的 `sdk_version`（插件包里的 `sdk_version` 字段，
即编译时链接的 SDK 版本）。

| 内核 | 插件 SDK | 结果 |
|---|---|---|
| 1.4.0 | 1.0.0 / 1.1.0 / 1.3.0 | ✅ 建链（同主版本） |
| 1.4.0 | 2.0.0 | ❌ 拒绝（跨主版本） |

**为什么不设独立的协议号**：语义版本变动频繁（修 bug、加字段），如果每个
这类改动都要人去升一个额外的号，那个号必然会被漏升而腐烂（历史实证：
曾有一个 `ProtocolVersion` 常量，多次布局变更里只升过一次，而对应的守卫
测试长期处于失败状态、无人察觉）。让兼容性只挂在**始终会被发的那个号**上，
就没有「忘同步」这个失效模式。

跨主版本错配**不会静默失效**——握手时会显式拦下，并提示用配套 `hmapdev` 重编。
此外握手还会比对 `field_count`（StageContext 描述符个数）：它决定标志位基址，
不一致会让插件读到错位字段，因此也在握手上显式拒绝。

## 怎么确认自己在用什么

装的 SDK 版本：

```bash
hmapdev sdk current
hmapdev sdk list
```

插件声明的目标版本在 `plg.json` 的 `sdk` 字段。若该版本不在本地存储里，
`hmapdev` 会**明确报错**，不静默降级 —— 静默降级会产出与内核协议不匹配的包，
那种失败要到运行时才暴露。

## 文档站对应的版本

本页与 [API 参考](api/index.md) 由 `tools/apidoc` 从源码生成，
内容随源码一起演进。发现文档与代码不一致时，**改的是源码注释**，
`go run ./tools/apidoc` 重新生成即可（见下方「维护」）。

## 维护（给 SDK 维护者）

```bash
cd homeagent-sdk
go run ./tools/apidoc -pkgdir ./sdk -out /tmp/api.json
go run ./tools/apidoc/gensite -api /tmp/api.json -out ./docs -examples ./example
mkdocs serve     # 本地预览
mkdocs build     # 产出 site_build/
```

API 面的**能力分层**（哪些 API 仅内置可用）记在 `tools/apidoc/tiers.json`，
每条裁定都附源码依据 —— 改这里而不是改生成物。