OpenClaw.NET 兼容性目录指南（Compatibility Catalog）

面向 OpenClaw.NET 用户与贡献者的compat/public-smoke.json完整技术指南。概述compat/public-smoke.json是 OpenClaw.NET 兼容性验证体系的核心清单文件。它承担着以下关键职责集中管理所有已知公开插件NPM Plugin和技能ClawHub Skill的预期行为作为自动化烟雾测试Public Smoke Tests的唯一数据源通过CLI 命令与REST API暴露给运维与集成方查询在构建期作为嵌入资源Embedded Resource编译进OpenClaw.Core程序集对 NativeAOT 完全友好运行时无需访问文件系统。无论是发布前的回归验证、外部集成方的兼容性自查还是社区贡献者新增插件都以该清单为唯一事实来源Single Source of Truth。文件结构清单顶层是一个带版本号的 JSON 对象entries字段为条目数组{ version:2, entries:[ { id:agentseo-plugin, category:ts-jiti-plugin, kind:npm-plugin, spec:agentseo/openclaw-plugin0.1.4, packageName:agentseo/openclaw-plugin, pluginId:agentseo, expectedStatus:compatible, configJson:{\apiKey\:\test_key\}, expectedToolNames:[agentseo_audit,agentseo_keywords], expectedSkillNames:[agentseo] } ] }条目字段说明字段按用途分为三组通用字段、技能专用字段、插件专用字段。通用字段所有条目必填字段类型说明idstring场景唯一标识须在entries中保持唯一categorystring场景分类pure-skill、js-tool-plugin、ts-jiti-plugin、config-schema-plugin、unsupported-surface-pluginkindstring资源类型clawhub-skill或npm-plugin技能专用字段kind clawhub-skill字段类型必填说明slugstring✅ClawHub 中的技能标识符versionstring✅技能的 SemVer 版本expectedRelativePathstring✅安装后的预期相对路径如skills/my-skill/SKILL.md插件专用字段kind npm-plugin字段类型必填说明specstring✅NPM 包规范如agentseo/openclaw-plugin0.1.4packageNamestring✅NPM 包名pluginIdstring✅插件唯一标识expectedStatusstring✅预期兼容性状态compatible或incompatibleconfigJsonstring⭕️JSON 字符串形式的示例配置installExtraPackagesstring[]⭕️需要额外安装的依赖包列表expectedToolNamesstring[]⭕️预期暴露的工具名称仅compatible场景expectedSkillNamesstring[]⭕️预期提供的技能名称仅compatible场景expectedDiagnosticCodesstring[]⭕️预期的诊断错误码仅incompatible场景⚠️注意NPM 插件条目必须显式指定expectedStatus编译期校验会拒绝缺失该字段的条目。场景分类详解OpenClaw.NET 共定义了 5 种category覆盖了从纯技能到负面用例的全部典型场景Category说明测试目的典型示例pure-skill独立技能包无 NPM 依赖验证 SKILL.md 格式与 ClawHub 安装流程pdf-form-fillerjs-tool-pluginJavaScript 编写的桥接插件验证 JS 插件加载与工具导出example/js-plugints-jiti-pluginTypeScript JITI 转译的插件验证 TypeScript 转译与 JITI 集成agentseo/openclaw-pluginconfig-schema-plugin配置校验负面场景验证无效配置被检测并返回诊断码缺失必填字段 / 字段类型错误unsupported-surface-plugin不支持功能的负面场景验证不支持的 API 被显式拒绝注册 CLI 命令 / 调用受限 API正面与负面场景正面场景expectedStatus compatible验证插件/技能能够成功加载验证声明的工具和技能均正确暴露到 Gateway使用expectedToolNames与expectedSkillNames进行断言任何缺失或多余的工具/技能均判定为失败。负面场景expectedStatus incompatible验证错误能被系统显式检测并拒绝而非部分加载或静默忽略使用expectedDiagnosticCodes断言错误码典型诊断码诊断码含义config_one_of_mismatch配置不满足oneOf约束unsupported_cli_registration插件尝试注册不支持的 CLI 命令unsupported_surface_call调用了未公开/受限的 API 表面schema_required_missing必填字段缺失使用方式CLI 查询OpenClaw CLI 提供compatibility catalog子命令便于本地查询与脚本消费# 查看所有条目 openclaw compatibility catalog # 按状态过滤 openclaw compatibility catalog --status compatible openclaw compatibility catalog --status incompatible # 按类型与分类过滤 openclaw compatibility catalog --kind npm-plugin --category ts-jiti-plugin # JSON 格式输出适用于程序化消费 openclaw compatibility catalog --json # 简写形式 openclaw compat catalogREST APIGateway 通过/api/integration/compatibility路由族对外暴露GET /api/integration/compatibility/catalog GET /api/integration/compatibility/catalog?compatibilityStatuscompatible GET /api/integration/compatibility/catalog?kindnpm-plugincategoryts-jiti-plugin GET /api/integration/compatibility/export/catalog端点支持compatibilityStatus、kind、category三个查询参数过滤/export端点返回完整的兼容性报告包含运行时模式AOT / JIT、安全态势Security Posture、通道就绪状态Channel Readiness等额外维度适合在 CI 中归档或对接外部门户。自动化测试测试类PublicCompatibilitySmokeTests在运行时自动读取清单并迭代执行触发开关环境变量OPENCLAW_PUBLIC_SMOKE1必须设置否则测试整体跳过ClawHub 技能通过npx clawhub安装并校验expectedRelativePath文件存在compatible插件执行安装、加载、然后断言expectedToolNames/expectedSkillNames完整暴露incompatible插件执行安装、加载断言加载失败且诊断码集合至少包含expectedDiagnosticCodes中的全部条目。CI/CD 集成在 GitHub Actions 中public-compatibility-smoke作业承担清单的回归验证触发条件定时执行schedule或手动派发workflow_dispatch依赖环境Node.js 20用于npm与clawhub命令链路执行流程dotnet test--filter CategoryPublicSmoke报告产物生成 TRX 格式测试报告并作为 artifact 上传失败语义任意条目断言失败即视为整个作业失败需在合并前修复。如何贡献新条目添加新技能{ id:my-new-skill, category:pure-skill, kind:clawhub-skill, slug:my-new-skill, version:1.0.0, expectedRelativePath:skills/my-new-skill/SKILL.md }添加兼容插件正面场景{ id:my-plugin, category:js-tool-plugin, kind:npm-plugin, spec:my-org/openclaw-plugin1.0.0, packageName:my-org/openclaw-plugin, pluginId:my-plugin, expectedStatus:compatible, configJson:{\apiKey\:\test_key\}, expectedToolNames:[my_tool_1,my_tool_2], expectedSkillNames:[my-skill] }添加不兼容场景负面场景{ id:broken-plugin-example, category:config-schema-plugin, kind:npm-plugin, spec:my-org/broken-plugin1.0.0, packageName:my-org/broken-plugin, pluginId:broken-plugin, expectedStatus:incompatible, configJson:{\wrongField\: 123}, expectedDiagnosticCodes:[config_one_of_mismatch] }贡献流程在compat/public-smoke.json的entries数组末尾追加条目确保必填字段完整NPM 插件必须包含expectedStatus、spec、packageName、pluginId技能必须包含slug、version、expectedRelativePath本地设置OPENCLAW_PUBLIC_SMOKE1并执行dotnet test OpenClaw.Net.slnx --filterCategoryPublicSmoke如引入了新的category或kind需同步升级清单顶层version字段更新PublicCompatibilityCatalog中的枚举与转换逻辑更新本文档的场景分类详解表格。数据转换逻辑清单在运行时通过PublicCompatibilityCatalog.CreateCatalog()转换为富目录Rich Catalog以便 CLI 与 REST API 直接消费。核心映射规则如下源字段生成字段转换逻辑slug/packageName/pluginId/idSubject按优先级取第一个非空值kindspec/slugInstallCommand技能openclaw clawhub install {slug}插件openclaw plugins install {spec} --dry-runcategoryexpectedStatusSummary根据场景性质生成人类可读描述expectedStatusScenarioTypecompatible→positiveincompatible→negative多字段组合Guidance[]上下文相关的操作建议如配置 schema 错误请参考插件文档与 NativeAOT 的关系OpenClaw.NET 的 NativeAOT 约束直接影响清单的加载与序列化方式嵌入资源compat/public-smoke.json在.csproj中以EmbeddedResource方式编译进OpenClaw.Core.dll运行时无任何文件 I/OJSON 源生成使用CoreJsonContext基于JsonSerializerContext的 source generator反序列化清单完全规避反射桥接协议插件通过plugin-bridge.mjs走JSON-RPC over stdio避免在主进程中动态加载托管程序集AOT/JIT 一致性清单驱动的烟雾测试同时覆盖 AOT 与 JIT 两种发布模式确保行为一致。故障排查症状可能原因解决方案测试报告 plugin failed to loadconfigJson格式错误或字段类型不匹配检查 JSON 是否符合插件实际 schema使用--dry-run先行验证expected tool not found插件未声明该工具或工具名拼写错误校对expectedToolNames与插件运行时实际暴露的工具名编译期错误 npm-plugin must declare expectedStatus新条目缺少expectedStatus字段明确指定compatible或incompatible烟雾测试整体未运行环境变量未设置设置OPENCLAW_PUBLIC_SMOKE1后重试clawhub安装失败Node.js 未安装或版本过低安装 Node.js 20 并确保npx可用expectedDiagnosticCodes不匹配错误码命名变更或新增查阅最新诊断码列表必要时同步更新清单AOT 模式启动报缺少元数据新增字段未在CoreJsonContext中声明在源生成上下文中添加对应类型