新能力

推荐用于添加插件 API 尚未具备的能力的顺序，以及文件检查清单和契约测试模式。属于 插件架构内部机制 指南的一部分。

添加新能力¶

当插件需要当前 API 无法容纳的行为时，不要通过私有的内部直接访问绕过插件系统。添加缺失的能力。

推荐顺序：

1. 定义核心契约。 决定核心应拥有哪些共享行为：策略、回退、配置合并、生命周期、面向通道的语义，以及运行时辅助函数形态。
2. 添加带类型的插件注册/运行时接口。 使用最小的有用带类型能力接口扩展 OpenClawPluginApi 和/或 api.runtime。
3. 连接核心 + 通道/功能消费者。 通道和功能插件应通过核心消费新能力，而不是直接导入供应商实现。
4. 注册供应商实现。 供应商插件随后针对该能力注册其后端。
5. 添加契约覆盖。 添加测试，使所有权和注册形态随时间保持明确。

这就是 OpenClaw 保持有明确设计取向，同时不会硬编码到某个供应商世界观的方式。有关具体的文件检查清单和实际示例，请参阅 添加能力。

能力检查清单¶

添加新能力时，实现通常应一起涉及这些接口：

• src/<capability>/types.ts 中的核心契约类型
• src/<capability>/runtime.ts 中的核心 runner/运行时辅助函数
• src/plugins/types.ts 中的插件 API 注册接口
• src/plugins/registry.ts 中的插件注册表连接
• 当功能/通道插件需要消费它时，src/plugins/runtime/* 中的插件运行时暴露
• src/test-utils/plugin-registration.ts 中的捕获/测试辅助函数
• src/plugins/contracts/registry.ts 中的所有权/契约断言
• docs/ 中的操作员/插件文档

如果缺少其中一个接口，通常表示该能力尚未完全集成。

能力模板¶

最小模式：

// core contract
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// plugin API
api.registerVideoGenerationProvider({
  id: "xai",
  label: "xAI",
  async generateVideo(req) {
    // generateXaiVideo is a placeholder for your own vendor call.
    return await generateXaiVideo(req);
  },
});

// shared runtime helper for feature/channel plugins
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

契约测试模式（src/plugins/contracts/registry.ts 暴露所有权查找，例如 providerContractPluginIds；测试断言插件的 contracts.videoGenerationProviders 列表与其实际注册的内容匹配）：

expect(pluginManifest.contracts?.videoGenerationProviders).toEqual(["xai"]);

这使规则保持简单：

• 核心拥有能力契约 + 编排
• 供应商插件拥有供应商实现
• 功能/通道插件消费运行时辅助函数
• 契约测试保持所有权明确