成熟度：Planned
目标
把“版本发生了什么变化”转化为开发者可验证的升级动作，避免只依赖 Changelog 猜测数据、协议和运行环境是否兼容。
当前可用
当前各组件按各自版本和发布说明演进，尚未提供统一的 SDK × Protocol × Gateway × Host × Console 兼容矩阵，也没有覆盖所有版本跨度的迁移指南。
升级前应固定现有 SDK 与部署版本，保存回归输入和预期结果，并在目标环境重新验证认证、Thread / Run、SSE、Consent、Sandbox、Connector 与数据持久化。Desktop 迁移到 Server 不是复制目录：身份、数据库、文件路径、凭证引用、网络和沙箱策略都需重新建立。
AG-UI / Interfaces（≥ @fellow.work/client 0.5.90）
P5-01 Interfaces Preview exit @ 0.5.90（fpp-0027）· Stable @ 0.7.1（fpp-0032）；与 Interaction / Management 升级正交。
| 从 | 到 |
|---|---|
import { AgUiMapper } from '@fellow.work/client' | import { AgUiMapper } from '@fellow/ag-ui-adapter' 或 '@fellow.work/client/ag-ui' |
根 import AgUiMapContext | 同上（≥ 0.5.89 CI 门禁；pack 证据 ≥ 0.5.90） |
仅 pin 旧 SDK、无 @fellow/ag-ui-adapter | client ≥ 0.5.77 已声明 adapter 依赖； tarball：pnpm spec:runner:adapter:tarball |
根 re-export deprecated @ 0.5.79 · 已移除 @ 0.7.0（fpp-0026）。≥ 0.7.0 必须使用 adapter 或 /ag-ui subpath。详见 spec/operations/ag-ui-adapter-migration.md 与 Interfaces Protocol。
边界
- Changelog 记录变化事实，Migration Guide 解释动作；两者不能互相替代。
- SDK 包版本不代表协议版本，Gateway、Host 和 Console 也不能仅按产品名推断兼容。
- 通用协议版本协商、最低组件版本和统一弃用周期尚未冻结。
- HARP 同
id升级会保留应用数据目录，但破坏性数据迁移仍由应用负责。
未来能力
Planned： 按版本发布迁移指南、弃用窗口、最低版本要求、能力发现、兼容矩阵和回滚检查表。在这些材料发布前，不对未列出的跨版本组合做兼容承诺。