概述

compat/public-smoke.json 是 OpenClaw.NET 兼容性驗(yàn)證體系的核心清單文件。它承擔(dān)著以下關(guān)鍵職責(zé)：

• 集中管理所有已知公開插件（NPM Plugin）和技能（ClawHub Skill）的預(yù)期行為；
• 作為自動化煙霧測試（Public Smoke Tests） 的唯一數(shù)據(jù)源；
• 通過 CLI 命令 與 REST API 暴露給運(yùn)維與集成方查詢；
• 在構(gòu)建期作為嵌入資源（Embedded Resource）編譯進(jìn) OpenClaw.Core 程序集，對 NativeAOT 完全友好，運(yùn)行時無需訪問文件系統(tǒng)。

無論是發(fā)布前的回歸驗(yàn)證、外部集成方的兼容性自查，還是社區(qū)貢獻(xiàn)者新增插件，都以該清單為唯一事實(shí)來源（Single Source of Truth）。

文件結(jié)構(gòu)

清單頂層是一個帶版本號的 JSON 對象，entries 字段為條目數(shù)組：

{
  "version": 2,
  "entries": [
    {
      "id": "agentseo-plugin",
      "category": "ts-jiti-plugin",
      "kind": "npm-plugin",
      "spec": "@agentseo/openclaw-plugin@0.1.4",
      "packageName": "@agentseo/openclaw-plugin",
      "pluginId": "agentseo",
      "expectedStatus": "compatible",
      "configJson": "{\"apiKey\":\"test_key\"}",
      "expectedToolNames": ["agentseo_audit", "agentseo_keywords"],
      "expectedSkillNames": ["agentseo"]
    }
  ]
}

條目字段說明

字段按用途分為三組：通用字段、技能專用字段、插件專用字段。

通用字段（所有條目必填）

技能專用字段（kind == "clawhub-skill"）

插件專用字段（kind == "npm-plugin"）

?? 注意：NPM 插件條目必須顯式指定 expectedStatus，編譯期校驗(yàn)會拒絕缺失該字段的條目。

場景分類詳解

OpenClaw.NET 共定義了 5 種 category，覆蓋了從純技能到負(fù)面用例的全部典型場景：

正面與負(fù)面場景

正面場景（expectedStatus = "compatible"）

• 驗(yàn)證插件/技能能夠成功加載；
• 驗(yàn)證聲明的工具和技能均正確暴露到 Gateway；
• 使用 expectedToolNames 與 expectedSkillNames 進(jìn)行斷言；
• 任何缺失或多余的工具/技能均判定為失敗。

負(fù)面場景（expectedStatus = "incompatible"）

• 驗(yàn)證錯誤能被系統(tǒng)顯式檢測并拒絕，而非"部分加載"或靜默忽略；
• 使用 expectedDiagnosticCodes 斷言錯誤碼；
• 典型診斷碼：

使用方式

CLI 查詢

OpenClaw CLI 提供 compatibility catalog 子命令，便于本地查詢與腳本消費(fèi)：

# 查看所有條目
openclaw compatibility catalog
# 按狀態(tài)過濾
openclaw compatibility catalog --status compatible
openclaw compatibility catalog --status incompatible
# 按類型與分類過濾
openclaw compatibility catalog --kind npm-plugin --category ts-jiti-plugin
# JSON 格式輸出（適用于程序化消費(fèi)）
openclaw compatibility catalog --json
# 簡寫形式
openclaw compat catalog

REST API

Gateway 通過 /api/integration/compatibility 路由族對外暴露：

GET /api/integration/compatibility/catalog
GET /api/integration/compatibility/catalog?compatibilityStatus=compatible
GET /api/integration/compatibility/catalog?kind=npm-plugin&category=ts-jiti-plugin
GET /api/integration/compatibility/export

• /catalog 端點(diǎn)支持 compatibilityStatus、kind、category 三個查詢參數(shù)過濾；
• /export 端點(diǎn)返回完整的兼容性報(bào)告，包含運(yùn)行時模式（AOT / JIT）、安全態(tài)勢（Security Posture）、通道就緒狀態(tài)（Channel Readiness）等額外維度，適合在 CI 中歸檔或?qū)油獠块T戶。

自動化測試

測試類 PublicCompatibilitySmokeTests 在運(yùn)行時自動讀取清單并迭代執(zhí)行：

• 觸發(fā)開關(guān)：環(huán)境變量 OPENCLAW_PUBLIC_SMOKE=1 必須設(shè)置，否則測試整體跳過；
• ClawHub 技能：通過 npx clawhub 安裝并校驗(yàn) expectedRelativePath 文件存在；
• compatible 插件：執(zhí)行安裝、加載、然后斷言 expectedToolNames / expectedSkillNames 完整暴露；
• incompatible 插件：執(zhí)行安裝、加載，斷言加載失敗且診斷碼集合至少包含 expectedDiagnosticCodes 中的全部條目。

CI/CD 集成

在 GitHub Actions 中，public-compatibility-smoke 作業(yè)承擔(dān)清單的回歸驗(yàn)證：

• 觸發(fā)條件：定時執(zhí)行（schedule）或手動派發(fā)（workflow_dispatch）；
• 依賴環(huán)境：Node.js 20（用于 npm 與 clawhub 命令鏈路）；
• 執(zhí)行流程：dotnet test + --filter Category=PublicSmoke；
• 報(bào)告產(chǎn)物：生成 TRX 格式測試報(bào)告并作為 artifact 上傳；
• 失敗語義：任意條目斷言失敗即視為整個作業(yè)失敗，需在合并前修復(fù)。

如何貢獻(xiàn)新條目

添加新技能

{
  "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-plugin@1.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"]
}

添加不兼容場景（負(fù)面場景）

{
  "id": "broken-plugin-example",
  "category": "config-schema-plugin",
  "kind": "npm-plugin",
  "spec": "@my-org/broken-plugin@1.0.0",
  "packageName": "@my-org/broken-plugin",
  "pluginId": "broken-plugin",
  "expectedStatus": "incompatible",
  "configJson": "{\"wrongField\": 123}",
  "expectedDiagnosticCodes": ["config_one_of_mismatch"]
}

貢獻(xiàn)流程

• 在 compat/public-smoke.json 的 entries 數(shù)組末尾追加條目；
• 確保必填字段完整：
  • NPM 插件：必須包含 expectedStatus、spec、packageName、pluginId；
  • 技能：必須包含 slug、version、expectedRelativePath；
  • 本地設(shè)置 OPENCLAW_PUBLIC_SMOKE=1 并執(zhí)行：

dotnet test OpenClaw.Net.slnx --filter Category=PublicSmoke

• 如引入了新的 category 或 kind，需同步：
• 升級清單頂層 version 字段；
• 更新 PublicCompatibilityCatalog 中的枚舉與轉(zhuǎn)換邏輯；
• 更新本文檔的場景分類詳解表格(文中有介紹)。

數(shù)據(jù)轉(zhuǎn)換邏輯

清單在運(yùn)行時通過 PublicCompatibilityCatalog.CreateCatalog() 轉(zhuǎn)換為富目錄（Rich Catalog），以便 CLI 與 REST API 直接消費(fèi)。核心映射規(guī)則如下：

與 NativeAOT 的關(guān)系

OpenClaw.NET 的 NativeAOT 約束直接影響清單的加載與序列化方式：

• 嵌入資源：compat/public-smoke.json 在 .csproj 中以 <EmbeddedResource> 方式編譯進(jìn) OpenClaw.Core.dll，運(yùn)行時無任何文件 I/O；
• JSON 源生成：使用 CoreJsonContext（基于 JsonSerializerContext 的 source generator）反序列化清單，完全規(guī)避反射；
• 橋接協(xié)議：插件通過 plugin-bridge.mjs 走 JSON-RPC over stdio，避免在主進(jìn)程中動態(tài)加載托管程序集；
• AOT/JIT 一致性：清單驅(qū)動的煙霧測試同時覆蓋 AOT 與 JIT 兩種發(fā)布模式，確保行為一致。

故障排查

到此這篇關(guān)于OpenClaw.NET 兼容性目錄指南(Compatibility Catalog)的文章就介紹到這了,更多相關(guān)OpenClaw.NET 兼容性內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評論