mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-31 06:17:25 +00:00
b2872f3702
兼容性判据原有三处自造版本号，全部删除：
- procProtocolVersion（模板侧握手常量）
- shmVersion / shmOffVersion（共享段 header）
- unifiedVersion（SuperBlock）
为什么废除：语义版本变动频繁（修 bug、加字段），再要求人去升一个额外的号，
那个号必然漏升而腐烂。实证：ProtocolVersion 常量在多次布局变更里只升过一次，
而对应的守卫测试（TestProcTemplate_ShmLayoutMatchesKernel）长期处于失败状态
无人察觉 —— 它当时期望 shmStageFieldCount=18/shmVersion=1，实际已是 19/2。
取而代之的两个判据都是**结构的派生事实**，不需要谁记得去同步：
1. 主版本号：内核 meta.Version ↔ 插件 sdk.SDKVersion 的主版本段比对。
主版本跃迁正是破坏性变更的定义（1.0.0 从 C ABI 改子进程即属此列），
所以它天然是正确分界。
2. field_count：StageContext 描述符个数，决定标志位基址。
顺带修正了 shmFlagsOff：原实现用本插件的编译期常量推算标志位基址，
内核加字段时会静默错位。现改为从 header 读取内核下发的描述符个数。
SuperBlock 的 version 槽位保留（不动其余偏移），值不再写入也不再校验。
判据：TestProcTemplate_RejectsIncompatiblePeer（含 banned 列表，
防这些号被重新引入）。
94 lines
4.2 KiB
Markdown
94 lines
4.2 KiB
Markdown
# 版本与兼容
|
||
|
||
## 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`，
|
||
每条裁定都附源码依据 —— 改这里而不是改生成物。
|