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 列表，
防这些号被重新引入）。
4.2 KiB
版本与兼容
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 版本：
hmapdev sdk current
hmapdev sdk list
插件声明的目标版本在 plg.json 的 sdk 字段。若该版本不在本地存储里，
hmapdev 会明确报错，不静默降级 —— 静默降级会产出与内核协议不匹配的包，
那种失败要到运行时才暴露。
文档站对应的版本
本页与 API 参考 由 tools/apidoc 从源码生成，
内容随源码一起演进。发现文档与代码不一致时，改的是源码注释，
go run ./tools/apidoc 重新生成即可（见下方「维护」）。
维护（给 SDK 维护者）
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，
每条裁定都附源码依据 —— 改这里而不是改生成物。