契约测试

契约测试（插件与渠道结构）¶

契约测试验证每个已注册的插件和渠道是否遵循其接口契约。它们遍历所有已发现的插件，并运行一组结构和行为断言。默认的 pnpm test 单元测试通道会特意跳过这些共享接缝和冒烟文件；当你改动共享渠道或提供者表面时，请显式运行契约命令。

命令¶

• 所有契约：pnpm test:contracts
• 仅渠道契约：pnpm test:contracts:channels
• 仅提供者契约：pnpm test:contracts:plugins

渠道契约¶

位于 src/channels/plugins/contracts/*.contract.test.ts。当前顶层类别包括：

• channel-catalog - 捆绑/注册表渠道目录条目元数据
• plugin（基于注册表，分片）- 基本插件注册结构
• surfaces-only（基于注册表，分片）- 对 actions、setup、status、outbound、messaging、threading、directory 和 gateway 的逐表面结构检查
• session-binding（基于注册表）- 会话绑定行为
• outbound-payload - 消息负载结构与规范化
• group-policy（回退）- 每个渠道的默认组策略执行
• threading（基于注册表，分片）- 线程 ID 处理
• directory（基于注册表，分片）- 目录/名册 API
• registry 和 plugins-core.* - 渠道插件注册表、加载器以及配置写入授权内部机制

这些测试套件所使用的入站分发捕获和出站负载测试辅助工具，通过 src/plugin-sdk/channel-contract-testing.ts 在内部暴露（已被 npm 排除，不是公开的 SDK 子路径）；此目录中不存在独立的 inbound.contract.test.ts 文件。

提供者契约¶

位于 src/plugins/contracts/*.contract.test.ts。当前类别包括：

• shape - 插件清单、API 和运行时导出的结构
• plugin-registration（+ 并行）- 清单注册用例
• package-manifest - 包清单要求
• loader - 插件加载器的设置/拆除行为
• registry - 插件契约注册表内容与查找
• providers - 所有捆绑提供者之间共享的提供者行为，以及网络搜索提供者
• auth-choice - 认证选择元数据和设置行为
• provider-catalog-deprecation - 已弃用的提供者目录元数据
• wizard.choice-resolution、wizard.model-picker、wizard.setup-options - 提供者设置向导契约
• embedding-provider、memory-embedding-provider、web-fetch-provider、tts - 特定能力的提供者契约
• session-actions、session-attachments、session-entry-projection - 插件拥有的会话状态契约
• scheduled-turns - 插件计划回合元数据和时间戳边界
• host-hooks、run-context-lifecycle、runtime-import-side-effects、runtime-seams - 插件宿主/运行时生命周期和导入边界契约
• extension-runtime-dependencies - 扩展的运行时依赖放置

运行时机¶

• 更改 plugin-sdk 导出或子路径之后
• 添加或修改渠道或提供者插件之后
• 重构插件注册或发现逻辑之后

契约测试在 CI 中运行，不需要真实的 API 密钥。