OpenClaw 通道契约测试助手：核心契约层的导入边界规则与 Bundled 插件公共面解析实现

OpenClaw 通道契约测试助手核心契约层的导入边界规则与 Bundled 插件公共面解析实现【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawOpenClaw 的核心通道实现位于src/channels/**其契约测试助手contract test helpers必须与生产代码遵守同一套插件公共面导入边界。本文基于 src/channels/plugins/contracts/test-helpers/CLAUDE.md 这份边界规则文档结合同目录下的实际实现与 公共面解析器 源码完整讲解核心契约测试如何不硬编码路径地加载 bundled 插件的公共/测试面读完后可掌握该目录全部导入规则、vi.doMock反 hoisting 手法以及契约分片sharding机制。目录定位core 拥有的契约测试助手该规则文档开篇即给出目录定位此目录存放由 core 拥有的通道契约测试助手core-owned channel contract test helpers并且本文件是在 src/channels/AGENTS.md 的通用边界规则之上追加的通道专属规则。从目录结构看这里聚集了一整套围绕bundled 通道插件是否符合契约的共享测试基础设施manifest.ts共享的 manifest 契约常量surface key 列表、session binding 契约通道列表registry-plugin.ts把 bundled 插件 id 分配到确定性的 registry 契约分片runtime-artifacts.ts通过 runtime 记录解析并导入生成的契约工件bundled-channel-plugin-loader.ts、surface-contract-registry.ts、channel-catalog-contract.ts 等加载器、公共面契约注册表与目录契约session-binding-registry-backed-contract.ts、registry-session-binding.tssession 绑定契约。这些助手被多个*-contract-suites.ts文件如 channel-plugin-catalog-contract-suites.ts、config-write-contract-suites.ts复用因此它们的导入方式本身就必须被严格约束——否则一次图方便的相对路径导入就会让 core 测试代码与extensions/**私有文件产生硬耦合。核心规则Bundled Plugin 导入边界完整继承规则文档的 Bundled Plugin Imports 一节是本文主体逐条继承如下每条均结合仓库实现展开规则一禁止硬编码仓库相对导入extensions/**Core contract helpers 不得硬编码指向extensions/**的仓库相对导入。也就是说契约助手里不允许出现import ... from ../../../../../../extensions/telegram/src/...这类写法。原因在于 bundled 插件目录extensions/pluginId在构建后还可能出现在dist-runtime/extensions与dist/extensions等产物根下——这一点可以从 bundled-plugin-public-surface.ts 中findBundledPluginMetadataFast的多根候选逻辑得到印证它依次尝试resolveBundledPluginsDir()、root/extensions、root/dist-runtime/extensions、root/dist/extensions。硬编码源码相对路径会让契约测试只在恰好处于仓库源码布局时才能运行偏离生产代码实际解析公共面的方式。规则二统一经由src/test-utils/bundled-plugin-public-surface.ts当助手需要访问 bundled 插件的公共/测试面时一律走 src/test-utils/bundled-plugin-public-surface.ts。该文件是这一规则的落点导出三个关键能力loadBundledPluginFacade({ pluginId, artifactBasename })先解析路径、确认文件存在再import(pathToFileURL(modulePath).href)。源码注释特别指出Fixture 导入必须共享测试运行器的 SDK 状态与 mocks即动态import()而非静态导入保证与测试环境一致的模块实例。resolveBundledPluginPublicModulePath(...)返回验证过的公共面文件路径找不到生成的 artifact 时回退到extensions/dirName/artifactBasename的校验路径注释说明契约调用方即使 artifact 尚不存在也需要这个经过校验的路径。resolveRelativeBundledPluginPublicModuleId(...)即下一条规则的主角。解析过程还包含两道安全校验isSafeBundledPluginDirName用正则/^[a-z0-9][a-z0-9._-]*$/u拦截非法目录名防止路径穿越readPluginManifestId读取插件目录内的openclaw.plugin.json并校验其中id与传入的pluginId一致后才认可该目录避免目录名碰巧相同的误解析。规则三用resolveRelativeBundledPluginPublicModuleId解析模块 id测试若需要用于动态 import 或 mock 的模块 id优先使用resolveRelativeBundledPluginPublicModuleId(...)。该函数见 bundled-plugin-public-surface.ts 第 98–112 行接收{ fromModuleUrl, pluginId, artifactBasename }先把当前模块 URL 转成文件路径再调用resolveBundledPluginPublicModulePath得到目标绝对路径最后用path.relative计算以调用方文件为基准的相对模块 id并统一分隔符为/、确保前缀./或../。相对模块 id 的价值在于它与import.meta.url组合后可在 Vitest 中被解析、被createRequire(...).resolve(...)定位同时不暴露仓库布局假设。规则四vi.mock的 hoisting 会过早求值改用vi.doMock若vi.mock(...)的 hoisting 会在求值时机上过早地评估模块 id则使用vi.doMock(...)并传入已解析的模块 id而不是退回到硬编码路径。这是 Vitest 的一个经典陷阱vi.mock的工厂会被提升到文件顶部执行此时import.meta.url相关的模块 id 表达式往往尚未就绪。仓库中的标准解法在 runtime-artifacts.ts 的importBundledChannelContractSourceArtifact第 16–33 行中可以完整看到export async function importBundledChannelContractSourceArtifactT extends object( pluginId: string, artifactBasename: string, mockFactories: Recordstring, () Recordstring, unknown, ): PromiseT { const moduleId resolveRelativeBundledPluginPublicModuleId({ fromModuleUrl: import.meta.url, pluginId, artifactBasename, }); const requirePlugin createRequire(new URL(moduleId, import.meta.url)); for (const [dependency, factory] of Object.entries(mockFactories)) { vi.doMock(requirePlugin.resolve(dependency), factory); } return (await import(moduleId)) as T; }三个细节值得注意用createRequire(new URL(moduleId, import.meta.url))构造一个以目标模块为基准的requirerequirePlugin.resolve(dependency)能把裸依赖名解析成该插件实际会加载的模块路径保证 mock 命中真实导入目标逐条vi.doMock(resolvedPath, factory)而非vi.mock把求值推迟到函数调用时刻源码注释说明惰性 transport 导入在 loader 返回之后仍需这些 mock且测试运行器会在文件之间清空 mock 注册表——所以 mock 生命周期必须覆盖到整个测试文件。规则五优先最小化内存 fixture拒绝加载宽 barrel对契约助手而言当契约只需要 capabilities、session binding 钩子、路由元数据或出站 payload 助手时优先使用最小化的内存 channel/plugin fixture。不要因为顺手就加载宽大的api.ts、runtime-api.ts、test-api.tsbarrel。这条规则与父级 src/channels/AGENTS.md 的整体基调一致通道入口是热导入路径异步-only 的 send/monitor/probe 面与大型runtime-api.tsbarrel 不应被静态拖入。契约测试同样如此——加载完整 barrel 会引入不必要的重依赖、拖慢契约套件并让测试表面与生产表面悄悄错位。规则六被测解析器要加载其所属的窄模块如果 bundled 插件的某个 parser 本身就是被测契约就加载拥有该 parser 的窄模块或提升一个小的公共 artifact不要为了 parse 一个目标 id 而拖入整个 extension barrel。这与规则五是同一原则的细化契约测试什么就只加载什么。runtime-artifacts.ts中的importBundledChannelContractArtifact(pluginId, entryBaseName)第 57–63 行展示了另一侧的标准做法——通过listBundledChannelPluginMetadata找到插件元数据再用resolvePluginRootPublicSurfacePath定位到插件根公共面下的具体 entry 文件并动态import而不是 import 插件入口。公共面常量与契约分片助手如何保持窄而确定规则文档虽未逐字列出这些实现但它们正是Bundled Plugin Imports规则的执行现场可作为验证依据一并了解公共面 key 白名单manifest.ts 定义了channelPluginSurfaceKeys [actions, setup, status, outbound, messaging, threading, directory, gateway]注释明确要求保持这些列表窄让每个 suite 只检查它自己拥有的 surface。session binding 契约通道同一文件给出sessionBindingContractChannelIds [discord, feishu, imessage, matrix, telegram]及对应的联合类型SessionBindingContractChannelId与 extensions/discord、extensions/feishu、extensions/imessage、extensions/matrix、extensions/telegram 五个 bundled 插件一一对应。确定性分片registry-plugin.ts 用index % shardCount shardIndex把listBundledChannelPluginIds()的每个插件稳定地分配到某个 registry 契约分片getPluginContractRegistryShardRefs再把分片映射为{ id }引用——保证 CI 分片运行时每个插件只被一个分片覆盖且分配不随列表顺序波动。设计意图防止 core 助手顺路越界规则文档的 Intent 一节总结了为什么要有这套约束让 core 契约助手与生产代码使用同一套公共/插件边界same public/plugin boundary保持对齐避免一种漂移core 契约助手因为在某一次测试里路径顺手就开始按路径直达 bundled 插件的私有文件边界一旦松口后续测试会不断复制这种做法。这与 src/channels/AGENTS.md 中extension 面一律经由openclaw/plugin-sdk/*不得直接导入src/channels/**的对称约束共同构成双向边界core 代码不依赖扩展私有文件扩展不依赖 core 内部实现而契约测试作为两者的裁判其自身的导入路径也必须被约束在同一边界内。相关验证命令按父级边界文档的要求当改动触及热通道入口或惰性加载缝隙时应运行pnpm build当 bundled 插件通道变更可能影响启动/导入成本时运行OPENCLAW_LOCAL_CHECK0 node --import tsx scripts/profile-extension-memory.mts --extension id --skip-combined --concurrency 1见 src/channels/AGENTS.md 的 Verification 一节scripts/profile-extension-memory.mts 即该 profiling 脚本。小结这份边界文档虽短却定下了 OpenClaw 契约测试层三条可执行的铁律公共面访问走统一解析器、模块 id 运行时解析vi.doMockcreateRequire.resolve、加载面窄化最小 fixture / 窄模块 / 公共面 key 白名单。配合 bundled-plugin-public-surface.ts 的目录名校验、manifest id 比对与多根回退解析以及 registry-plugin.ts 的确定性分片整套契约测试基础设施既保持了与生产导入路径一致又避免了任何一次图方便的硬编码路径造成 core 与 bundled 插件私有文件的越界耦合。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考