ZeroClaw WIT 破坏性变更检查wit-breaking-change-check实战指南冻结版本标记、变更分类与插件迁移路径【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw本文是 ZeroClaw 插件体系下 WIT 接口变更审查的完整实战指南。它以仓库内 wit-breaking-change-check 技能文档 为骨架结合 WIT 版本管理规范 与 wit/v0 实际接口定义 展开介绍如何对每一次触及wit/目录的改动执行破坏性变更分类、给出逐项 verdict并推导插件作者的迁移路径。读完本文你将能在合并任何触碰 WIT 定义的 PR 之前独立完成一次符合仓库规范的兼容性审查。一、为什么需要 WIT 破坏性变更检查ZeroClaw 的插件体系基于 WebAssembly Component Model插件与宿主之间通过 WITWebAssembly Interface Types 接口契约通信。WIT 接口一旦被插件编译进组件component就与宿主运行时的 ABI 绑定。对已冻结frozen版本的 WIT 做出删除、重命名、改签名等操作会让旧组件与新宿主或新组件与旧宿主无法链接属于典型的破坏性变更。因此仓库将 WIT 版本管理当作发布契约的一部分每个wit/vN/目录对应一个 WIT 包主版本目录内的稳定性由.frozen标记文件约束。.claude/skills/wit-breaking-change-check/SKILL.md定义的正是一套可重复执行的审查流程用于在合并前判定每一次 WIT diff 是破坏性还是非破坏性并对每一处修改给出结论与理由。二、何时执行本检查根据 SKILL.md 的When to Use章节以下三种场景必须运行本流程合并任何触及wit/目录的分支之前——这是硬性门槛审查修改了 WIT 接口定义的 PR 时发布插件兼容性版本前验证 WIT 改动是否安全。从仓库布局看WIT 定义集中在 wit/ 根目录下的v0/子目录共 9 个.wit文件channel.wit、config.wit、inbound.wit、logging.wit、memory.wit、plugin-info.wit、secrets.wit、tool.wit、types.wit未来破坏性变更将进入新的v1/目录。也就是说现阶段所有 touches wit/ 的改动都集中作用于v0/审查面清晰可控。三、标准检查流程Procedure技能文档定义的四步流程是整套检查的核心操作程序第 1 步获取当前 diffgit diff origin/master -- wit/以origin/master为基线仅聚焦wit/目录的改动避免其他模块的噪音干扰审查。第 2 步核对冻结状态对 diff 中出现的每个wit/vN/目录检查是否存在wit/vN/.frozen文件存在该版本已冻结适用当前主版本 前一主版本的宿主兼容窗口不存在该版本为实验性experimental状态应如实报告组件必须针对目标宿主随附的 WIT 重新构建不得声称冻结版本的兼容窗口适用。当前 wit/v0/README.md 明确标注状态为Experimental且仓库中不存在wit/v0/.frozen文件——这意味着 v0 目前允许被自由修改任何 diff 审查都应先声明这一前提。第 3 步逐项分类对每个冻结版本中的每一处修改对照 wit/VERSIONING.md 的破坏性变更分类学taxonomy进行归类细则见下一节。第 4 步输出 verdict对每个 finding 给出三种结论之一✅Non-breaking非破坏性——简要给出引用分类学的理由❌Breaking破坏性——简要给出引用分类学的理由⚠️Uncertain不确定——解释歧义所在。如果发现任何破坏性变更必须汇总插件作者所需的迁移路径见第六节。对于未冻结的实验性版本应声明组件必须针对目标宿主随附的 WIT 重建并说明当前与上一主版本的宿主兼容窗口只有在版本目录冻结后才开始。四、破坏性变更分类学Taxonomy这是整个检查的判定标准来自 wit/VERSIONING.md。对已冻结的vN/目录以下操作属于Breaking必须开新目录vN1/类别具体操作风险原因类型级删除或重命名任何类型、函数、record 字段、enum case、variant case旧组件/新宿主无法链接枚举/联合向既有 enum 或 variant 添加 case封闭类型closed types双向链接失败签名修改任何函数参数或返回值的类型ABI 不匹配字段修改任何 record 字段的类型ABI 不匹配布局重排 record 字段顺序内存布局改变而以下操作属于Non-breaking允许在既有vN/目录内通过since注解增量添加新增flags位如*-capabilities新增由 capability 门控capability-gated的函数新增 record / variant / enum类型注意不是向既有 enum/variant 添加 case新增 WITinterface定义新增world定义新增since/unstable注解。源码佐证capability-gated 的设计这一分类的现实依据可以直接在 channel.wit 中看到channel-capabilities是一个庞大的flags位掩码包含health-check、self-handle、drop-self-message、start-typing、supports-draft-updates、webhook-ingress等 20 余个标志位。文档注释明确说明运行时在加载期只调用一次get-channel-capabilities对每个未置位的 flag 使用 Rust trait 默认值如health-check → true、multi-message-delay-ms → 800、webhook-path → none、parse-webhook → err(bad-request(unsupported))且所有对应函数仍必须被插件导出stub 实现即可运行时仅在 flag 置位时才调用它们。这正是新增 capability-gated 函数属于非破坏性的原因新函数以新 flag 位门控旧插件导出 stub 即可宿主不会调用它反过来新插件在旧宿主上运行时未识别的 flag 位也不会触发任何调用。源码佐证封闭类型的真实含义分类学强调向既有 enum/variant 添加 case 是破坏性的因为它们是封闭类型。参考 channel.wit 中的approval-responsevariantapprove/deny/always-approve/deny-with-edit(string)与webhook-rejectionvariantunauthorized(string)/bad-request(string)组件编译时会对 variant 的分支数生成匹配代码宿主运行时对 case 的判别tag进行匹配。任何一侧增减 case 都会导致另一侧的判别失败这就是旧组件和新宿主或新组件和旧宿主会链接失败的直接机理。五、unstable/since生命周期与稳定性围栏注解生命周期wit/VERSIONING.md 规定了两个注解的用法开发期用unstable(feature your-feature-name)标注未显式 opt-in 该 feature 的bindgen!调用方看不到该条目发布期移除unstable改为since(version 0.x.0)所有未加 feature gate 的bindgen!调用方自动可见。当前wit/v0/的全部内容都位于unstable(feature plugins-wit-v0)门控之后——types.wit、tool.wit、channel.wit、config.wit、secrets.wit 均可见该注解。它会随首个稳定版 Component Model 发布而毕业graduate。在版本目录冻结之前整个 v0 都是实验性的即使只是向既有 enum/variant 添加 case组件也必须针对目标宿主随附的 WIT 重建。稳定性围栏Stability Fencewit/vN/.frozen文件在专门的 PR中、当对应版本被宣布稳定时创建。其存在之后wit-breaking-change-check技能将对任何删除或修改wit/vN/*.wit既有行的 PR 给出判定只接受纯增量改动新类型、新函数、since注解围栏虽有部分自动化特征仍依赖人工尽职审查者必须确保技能被运行、且任何报告的破坏性变更在合并前得到处理。源码佐证since的增量模式仓库内crates/zeroclaw-plugins/下的组件 fixture如tests/fixtures/tool-fixture、channel-fixture通过bindgen!生成绑定代码其 Cargo.toml 中与 feature 门控相对应。这印证了 VERSIONING.md 的说明minor 升级0.1 → 0.2只需重新编译无需源码改动——因为经由since新增的条目对旧调用方是透明的。六、宿主兼容窗口与版本淘汰vit/VERSIONING.md 定义了冻结后的宿主兼容窗口宿主为当前主版本与上一主版本N-1维护适配器。该窗口对未冻结的实验性版本不适用发布版本Supported支持Dropped淘汰V0当前V0—V1V1, V0—V2V2, V1V0淘汰某个版本有一组强制要求必须包含 CHANGELOG 条目、在先前版本中发布弃用通知deprecation notice并给出明确报错信息以命名检测到的 WIT 版本。这意味着 WIT 版本迁移不是静默发生的插件作者总能从错误信息中定位宿主期望的版本。七、插件作者的迁移路径vit/VERSIONING.md 按场景给出了三条明确的迁移路径场景 A当前实验性 V0本仓库当前状态tool与channel两个 world 都导入secrets接口且channelworld 还导入config。channel 的configure已从configure(config: string)改为configure()——这一点在 channel.wit 中可以得到印证configure: func() - result_, string注释要求通过config.get读取当前 schema 校验过的公开对象通过secrets.get读取密钥属性两者在一次调用中共享同一个已解析的 canonical revision且不得为后续操作保留 config 派生值。因此迁移要求为两类组件都必须针对当前wit/v0/定义重建才能安装到本宿主Channel 作者必须在configure及每个使用 config 的操作导出中改为调用config.get获取类型化公开对象在同一使用点调用secrets.get且不得在 guest 热状态warm guest state中保留任一值Tool 作者保留既有的__config注入契约和execute期间调用secrets.get的契约见 tool.wit 的tool-pluginworld导入logging与secrets导出plugin-info与tool发布每个重建组件的新 registry digest若签名覆盖的 manifest 内容发生变化则需重新签名早期实验性 world 的预构建组件不是一致性目标——这是wit/v0/.frozen缺失期间刻意的稳定性前断裂。场景 B瞄准 minor 升级如 0.1 → 0.2只需重新编译经由since新增的条目无需任何源码改动。场景 C瞄准新主版本如 V0 → V1将package声明更新为zeroclaw:plugin1.0.0更新 import 路径以引用新接口依据 V1 的 CHANGELOG 条目适配任何被重命名/删除的条目以wasm32-wasip2为目标重新编译。附加事实webhook-ingress 的连锁影响wit/VERSIONING.md 特别指出实验性 channel world 还包含webhook-ingresscapability、webhook-rejectionvariant以及webhook-path/parse-webhook两个导出。即使某个 channel 组件不声明 webhook 入站也必须导出文档规定的 stubwebhook-path → none、parse-webhook → err(bad-request(unsupported))。该新增项改变了生成的组件 ABI因此宿主升级时非 webhook 的 channel 组件也必须一并重建。八、在 PR 审查中的落地要点将上述内容收敛为日常审查清单运行git diff origin/master -- wit/确认改动边界逐个检查 diff 涉及的wit/vN/是否含.frozen当前仓库中wit/v0/.frozen不存在任何 diff 都应先声明实验性版本前提逐行对照分类学删除/重命名/改签名/改字段/重排/加 enum case 均判 Breaking新增 flags 位、capability-gated 函数、新类型、新 interface、新 world、since/unstable注解判 Non-breaking为每个 finding 输出 ✅ / ❌ / ⚠️ 及引用分类学的理由存在 Breaking 时按第七节场景汇总迁移路径并核对 CHANGELOG、弃用通知、错误信息等淘汰要求如涉及版本淘汰。这套流程的可靠性同时依赖文档约定与人工执行.frozen是人可读的约定其存在向审查者与技能本身宣告该版本已稳定、合并且前必须执行破坏性变更检查而围栏的自动化特征仍需要审查者在合并前确认技能已运行、Breaking 报告已被处理。这正是 ZeroClaw 在插件生态 ABI 稳定性上的设计取舍——用明确的分层目录、冻结标记与可重复的分类流程把接口是否可破坏从主观判断变成可审计的工程决策。【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ZeroClaw WIT 破坏性变更检查（wit-breaking-change-check）实战指南：冻结版本标记、变更分类与插件迁移路径
ZeroClaw WIT 破坏性变更检查wit-breaking-change-check实战指南冻结版本标记、变更分类与插件迁移路径【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw本文是 ZeroClaw 插件体系下 WIT 接口变更审查的完整实战指南。它以仓库内 wit-breaking-change-check 技能文档 为骨架结合 WIT 版本管理规范 与 wit/v0 实际接口定义 展开介绍如何对每一次触及wit/目录的改动执行破坏性变更分类、给出逐项 verdict并推导插件作者的迁移路径。读完本文你将能在合并任何触碰 WIT 定义的 PR 之前独立完成一次符合仓库规范的兼容性审查。一、为什么需要 WIT 破坏性变更检查ZeroClaw 的插件体系基于 WebAssembly Component Model插件与宿主之间通过 WITWebAssembly Interface Types 接口契约通信。WIT 接口一旦被插件编译进组件component就与宿主运行时的 ABI 绑定。对已冻结frozen版本的 WIT 做出删除、重命名、改签名等操作会让旧组件与新宿主或新组件与旧宿主无法链接属于典型的破坏性变更。因此仓库将 WIT 版本管理当作发布契约的一部分每个wit/vN/目录对应一个 WIT 包主版本目录内的稳定性由.frozen标记文件约束。.claude/skills/wit-breaking-change-check/SKILL.md定义的正是一套可重复执行的审查流程用于在合并前判定每一次 WIT diff 是破坏性还是非破坏性并对每一处修改给出结论与理由。二、何时执行本检查根据 SKILL.md 的When to Use章节以下三种场景必须运行本流程合并任何触及wit/目录的分支之前——这是硬性门槛审查修改了 WIT 接口定义的 PR 时发布插件兼容性版本前验证 WIT 改动是否安全。从仓库布局看WIT 定义集中在 wit/ 根目录下的v0/子目录共 9 个.wit文件channel.wit、config.wit、inbound.wit、logging.wit、memory.wit、plugin-info.wit、secrets.wit、tool.wit、types.wit未来破坏性变更将进入新的v1/目录。也就是说现阶段所有 touches wit/ 的改动都集中作用于v0/审查面清晰可控。三、标准检查流程Procedure技能文档定义的四步流程是整套检查的核心操作程序第 1 步获取当前 diffgit diff origin/master -- wit/以origin/master为基线仅聚焦wit/目录的改动避免其他模块的噪音干扰审查。第 2 步核对冻结状态对 diff 中出现的每个wit/vN/目录检查是否存在wit/vN/.frozen文件存在该版本已冻结适用当前主版本 前一主版本的宿主兼容窗口不存在该版本为实验性experimental状态应如实报告组件必须针对目标宿主随附的 WIT 重新构建不得声称冻结版本的兼容窗口适用。当前 wit/v0/README.md 明确标注状态为Experimental且仓库中不存在wit/v0/.frozen文件——这意味着 v0 目前允许被自由修改任何 diff 审查都应先声明这一前提。第 3 步逐项分类对每个冻结版本中的每一处修改对照 wit/VERSIONING.md 的破坏性变更分类学taxonomy进行归类细则见下一节。第 4 步输出 verdict对每个 finding 给出三种结论之一✅Non-breaking非破坏性——简要给出引用分类学的理由❌Breaking破坏性——简要给出引用分类学的理由⚠️Uncertain不确定——解释歧义所在。如果发现任何破坏性变更必须汇总插件作者所需的迁移路径见第六节。对于未冻结的实验性版本应声明组件必须针对目标宿主随附的 WIT 重建并说明当前与上一主版本的宿主兼容窗口只有在版本目录冻结后才开始。四、破坏性变更分类学Taxonomy这是整个检查的判定标准来自 wit/VERSIONING.md。对已冻结的vN/目录以下操作属于Breaking必须开新目录vN1/类别具体操作风险原因类型级删除或重命名任何类型、函数、record 字段、enum case、variant case旧组件/新宿主无法链接枚举/联合向既有 enum 或 variant 添加 case封闭类型closed types双向链接失败签名修改任何函数参数或返回值的类型ABI 不匹配字段修改任何 record 字段的类型ABI 不匹配布局重排 record 字段顺序内存布局改变而以下操作属于Non-breaking允许在既有vN/目录内通过since注解增量添加新增flags位如*-capabilities新增由 capability 门控capability-gated的函数新增 record / variant / enum类型注意不是向既有 enum/variant 添加 case新增 WITinterface定义新增world定义新增since/unstable注解。源码佐证capability-gated 的设计这一分类的现实依据可以直接在 channel.wit 中看到channel-capabilities是一个庞大的flags位掩码包含health-check、self-handle、drop-self-message、start-typing、supports-draft-updates、webhook-ingress等 20 余个标志位。文档注释明确说明运行时在加载期只调用一次get-channel-capabilities对每个未置位的 flag 使用 Rust trait 默认值如health-check → true、multi-message-delay-ms → 800、webhook-path → none、parse-webhook → err(bad-request(unsupported))且所有对应函数仍必须被插件导出stub 实现即可运行时仅在 flag 置位时才调用它们。这正是新增 capability-gated 函数属于非破坏性的原因新函数以新 flag 位门控旧插件导出 stub 即可宿主不会调用它反过来新插件在旧宿主上运行时未识别的 flag 位也不会触发任何调用。源码佐证封闭类型的真实含义分类学强调向既有 enum/variant 添加 case 是破坏性的因为它们是封闭类型。参考 channel.wit 中的approval-responsevariantapprove/deny/always-approve/deny-with-edit(string)与webhook-rejectionvariantunauthorized(string)/bad-request(string)组件编译时会对 variant 的分支数生成匹配代码宿主运行时对 case 的判别tag进行匹配。任何一侧增减 case 都会导致另一侧的判别失败这就是旧组件和新宿主或新组件和旧宿主会链接失败的直接机理。五、unstable/since生命周期与稳定性围栏注解生命周期wit/VERSIONING.md 规定了两个注解的用法开发期用unstable(feature your-feature-name)标注未显式 opt-in 该 feature 的bindgen!调用方看不到该条目发布期移除unstable改为since(version 0.x.0)所有未加 feature gate 的bindgen!调用方自动可见。当前wit/v0/的全部内容都位于unstable(feature plugins-wit-v0)门控之后——types.wit、tool.wit、channel.wit、config.wit、secrets.wit 均可见该注解。它会随首个稳定版 Component Model 发布而毕业graduate。在版本目录冻结之前整个 v0 都是实验性的即使只是向既有 enum/variant 添加 case组件也必须针对目标宿主随附的 WIT 重建。稳定性围栏Stability Fencewit/vN/.frozen文件在专门的 PR中、当对应版本被宣布稳定时创建。其存在之后wit-breaking-change-check技能将对任何删除或修改wit/vN/*.wit既有行的 PR 给出判定只接受纯增量改动新类型、新函数、since注解围栏虽有部分自动化特征仍依赖人工尽职审查者必须确保技能被运行、且任何报告的破坏性变更在合并前得到处理。源码佐证since的增量模式仓库内crates/zeroclaw-plugins/下的组件 fixture如tests/fixtures/tool-fixture、channel-fixture通过bindgen!生成绑定代码其 Cargo.toml 中与 feature 门控相对应。这印证了 VERSIONING.md 的说明minor 升级0.1 → 0.2只需重新编译无需源码改动——因为经由since新增的条目对旧调用方是透明的。六、宿主兼容窗口与版本淘汰vit/VERSIONING.md 定义了冻结后的宿主兼容窗口宿主为当前主版本与上一主版本N-1维护适配器。该窗口对未冻结的实验性版本不适用发布版本Supported支持Dropped淘汰V0当前V0—V1V1, V0—V2V2, V1V0淘汰某个版本有一组强制要求必须包含 CHANGELOG 条目、在先前版本中发布弃用通知deprecation notice并给出明确报错信息以命名检测到的 WIT 版本。这意味着 WIT 版本迁移不是静默发生的插件作者总能从错误信息中定位宿主期望的版本。七、插件作者的迁移路径vit/VERSIONING.md 按场景给出了三条明确的迁移路径场景 A当前实验性 V0本仓库当前状态tool与channel两个 world 都导入secrets接口且channelworld 还导入config。channel 的configure已从configure(config: string)改为configure()——这一点在 channel.wit 中可以得到印证configure: func() - result_, string注释要求通过config.get读取当前 schema 校验过的公开对象通过secrets.get读取密钥属性两者在一次调用中共享同一个已解析的 canonical revision且不得为后续操作保留 config 派生值。因此迁移要求为两类组件都必须针对当前wit/v0/定义重建才能安装到本宿主Channel 作者必须在configure及每个使用 config 的操作导出中改为调用config.get获取类型化公开对象在同一使用点调用secrets.get且不得在 guest 热状态warm guest state中保留任一值Tool 作者保留既有的__config注入契约和execute期间调用secrets.get的契约见 tool.wit 的tool-pluginworld导入logging与secrets导出plugin-info与tool发布每个重建组件的新 registry digest若签名覆盖的 manifest 内容发生变化则需重新签名早期实验性 world 的预构建组件不是一致性目标——这是wit/v0/.frozen缺失期间刻意的稳定性前断裂。场景 B瞄准 minor 升级如 0.1 → 0.2只需重新编译经由since新增的条目无需任何源码改动。场景 C瞄准新主版本如 V0 → V1将package声明更新为zeroclaw:plugin1.0.0更新 import 路径以引用新接口依据 V1 的 CHANGELOG 条目适配任何被重命名/删除的条目以wasm32-wasip2为目标重新编译。附加事实webhook-ingress 的连锁影响wit/VERSIONING.md 特别指出实验性 channel world 还包含webhook-ingresscapability、webhook-rejectionvariant以及webhook-path/parse-webhook两个导出。即使某个 channel 组件不声明 webhook 入站也必须导出文档规定的 stubwebhook-path → none、parse-webhook → err(bad-request(unsupported))。该新增项改变了生成的组件 ABI因此宿主升级时非 webhook 的 channel 组件也必须一并重建。八、在 PR 审查中的落地要点将上述内容收敛为日常审查清单运行git diff origin/master -- wit/确认改动边界逐个检查 diff 涉及的wit/vN/是否含.frozen当前仓库中wit/v0/.frozen不存在任何 diff 都应先声明实验性版本前提逐行对照分类学删除/重命名/改签名/改字段/重排/加 enum case 均判 Breaking新增 flags 位、capability-gated 函数、新类型、新 interface、新 world、since/unstable注解判 Non-breaking为每个 finding 输出 ✅ / ❌ / ⚠️ 及引用分类学的理由存在 Breaking 时按第七节场景汇总迁移路径并核对 CHANGELOG、弃用通知、错误信息等淘汰要求如涉及版本淘汰。这套流程的可靠性同时依赖文档约定与人工执行.frozen是人可读的约定其存在向审查者与技能本身宣告该版本已稳定、合并且前必须执行破坏性变更检查而围栏的自动化特征仍需要审查者在合并前确认技能已运行、Breaking 报告已被处理。这正是 ZeroClaw 在插件生态 ABI 稳定性上的设计取舍——用明确的分层目录、冻结标记与可重复的分类流程把接口是否可破坏从主观判断变成可审计的工程决策。【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考