插件兼容性与升级
Wuu 产品版本更新，不代表插件 API 必然兼容。产品使用 UTC CalVer；SDK 包、服务契约、运行时生命周期、组合配置和持久化数据各有独立版本。应检查插件实际依赖的契约，而不只看 minimum_wuu_version。
当前支持边界
Section titled “当前支持边界”| 层面 | 支持范围 |
|---|---|
| 包 manifest | Schema 1。包依赖版本范围约束包版本，不等于服务版本或产品版本。 |
| 进程传输 | wuu-plugin-v1，传输层 protocol_version: 1。 |
| 能力协商 | 版本 1、2、3；省略版本或值为 0 时视为 1。明确声明的不支持版本会被拒绝，不会自动降级。版本 1 不能声明能力；服务声明要求版本 3。 |
| Generation 生命周期 | 版本 2：initialize 声明、prepare 验证依赖与状态、提交后 activate，最后 shutdown。即使能力版本受支持，产品预检仍拒绝生命周期 0/1 和未知版本。 |
| 服务 | 消费者声明名称和主版本，所选提供者必须实现该主版本。不保证所有旧主版本继续可用。例如设置网关和 state.documents 使用主版本 1；当前 driver.turn 使用主版本 4，驱动 profile 服务使用主版本 2。 |
| 组合配置 | 版本 1–5。执行、资源授权及版本 5 之前的功能界面兼容投影只读；版本 5 要求明确列出运行时与 UI 依赖。 |
| 桌面 | 各公开快照和动作契约独立版本化。运行时兼容不能证明桌面贡献仍能正确显示和交互。 |
SDK 包目前仍为 0.1.0；这个数字不能独立标识源代码修订或全部支持的契约。发布插件时，应保留依赖锁文件和产物哈希。单文件开发使用宿主内嵌 SDK；用当前 SDK 重新构建插件，不等于旧插件兼容回归。
例如，仓库提交 08000266921da772f2ca999b8687f34fb4dbc911 分发的 SDK 已支持生命周期 2，无需采用新的可选响应字段，就能调用当前设置网关。更早的生命周期 1 包需要作者更新后才能通过 generation 预检。这不代表该提交的全部 API 都继续受支持：服务主版本仍会独立校验。
契约维护与弃用
Section titled “契约维护与弃用”- 保留受支持主版本的可观察行为：原有有效调用、结果字段、错误、取消、归属和清理。新增可选字段不能成为旧调用方的必填项。需要协商的新行为应使用明确能力或新方法；不得使用未选中的提供者悄悄补齐。
- 不兼容的服务变更需要新服务主版本，不能拿产品版本更新代替。纯增量变更不应人为引入破坏性主版本。只有相应契约变化时才调整生命周期或能力协议。
- 移除仍受支持的契约前，在公开契约和发布说明中写明替代方案、受影响版本、最后兼容的宿主/SDK 修订、迁移步骤及恢复限制。弃用的作者 API 应标注替代方案。只要仍声称支持，就保留旧产物回归；移除必须是明确评审的兼容性变更，不能靠重新生成基线掩盖破坏。
- 移除后仍保留拒绝测试。不支持的契约应指出失败版本或依赖，在效果发生前停止，而不是选择默认提供者。这些规则不承诺无限期支持每个历史插件或 SDK，也不承诺维护其安全修复。
当前接受的能力协议版本和生命周期 2 没有标记移除计划。实验契约和已移除的服务主版本，不会因为同属 SDK 0.1.0 而自动获得兼容承诺。
Project Agent 移除
Section titled “Project Agent 移除”Project Agent 及其实验契约 project.coordination@1、project_session 工具、桌面 application.projects API、项目草稿模式、session.domain@1 的项目工作方法，以及旧 thread/control/take 和 thread/control/return RPC 均已移除。已核验这些宿主和仓库 SDK 契约的移除前参考为 main 修订 e1de6e0ca（SDK 0.1.0）。移除边界是 PR #1167；在该 PR 合入前的后续修订也可能仍保留这些契约。产品版本和 SDK 包版本号不能单独标识支持范围。
升级前应移除对这些契约的依赖及其组合选择。没有内置替代项目调度器；自行实现协调的扩展可使用 host.managed-session@1 和公共会话生命周期。普通工作区项目仍受支持。原生 managed-session 响应保留 capacity_full: false，执行准入保留原有四个传输参数，但忽略已移除的容量参数。
已有 Project Agent 对话仍可从普通会话列表阅读，但不能执行，也不会在重启后恢复排队任务。历史工作记录保留在存储中，并作为不透明记录迁移；旧配置键 project_models 和 project_max_parallel 会被忽略。继续工作需新建普通对话。回退需要旧可执行文件和一致备份；升级不会撤销已发生的外部效果。
安全升级与恢复
Section titled “安全升级与恢复”- 保留旧可执行文件、插件产物、组合配置源，以及提供者拥有的历史、设置、绑定和 checkpoint 的一致备份。
- 使用所选提供者准备候选。准备失败保留当前 generation。持久化提交之后的激活失败会报告已提交状态及诊断，不会自动回滚。
- 已接收的工作继续使用捕获的 generation。同 ID 更新可能在旧工作排空前短暂重叠；移除或禁用会撤销该插件及必需消费者。恢复选择不会撤销已完成的外部效果。
- 将组合版本 1–4 明确保存为版本 5 前，先检查适用的
migration:vN-to-v3执行投影、migration:vN-to-v4资源授权投影和migration:vN-to-v5功能 UI 投影。启动不会重写旧源文件。明确排除、替代和空选择仍然有效。 - 更换状态提供者须遵循其迁移契约：保留源数据，拒绝冲突目标或未知非空旧表。不得删除历史、编造 checkpoint 身份，或使用原生默认驱动接管外部驱动。降级需要兼容数据及原有提供者/绑定集合，不是改一个版本号。
实际的数据转移及 checkpoint 要求见组合与持久化契约。
冻结产物回归
Section titled “冻结产物回归”使用 go.mod 指定的 Go 和 Node 22.7+ 运行 node scripts/plugin-compatibility-e2e.mjs。无需构建 SDK、安装包、模型凭证或推理。回归先验证哈希，再直接使用保留的历史 npm-pack 内容及原样分发的 TODO JavaScript。来源记录包含公开代码修订和编译器，不声称该包曾发布到 npm 注册表。
回归覆盖当前 Go 进程/配置服务、准备、激活、调用、失败升级、重新加载、撤销、不支持版本、缺失提供者、增量字段，以及现有组合和执行日志迁移回归。report.json、协议记录及 Go JSON 测试日志保存到 .tmp/plugin-compatibility/；可用 WUU_COMPATIBILITY_EVIDENCE 改变位置。CI 会保留证据。桌面渲染、上游服务行为及全部历史 API 仍需独立验收。