插件架构内部

​

加载流水线

1. 发现候选插件根目录
2. 读取原生或兼容捆绑清单以及包元数据
3. 拒绝不安全的候选项
4. 规范化插件配置（plugins.enabled、allow、deny、entries、 slots、load.paths）
5. 为每个候选项决定是否启用
6. 加载已启用的原生模块：已构建的捆绑模块使用原生加载器； 第三方本地源码 TypeScript 使用紧急 Jiti 回退
7. 调用原生 register(api) 钩子，并将注册内容收集到插件注册表中
8. 将注册表暴露给命令/运行时界面

• 其解析后的入口逃逸出了插件根目录
• 其路径（或其根目录）是全局可写的
• 对于非捆绑插件，其路径所有权与当前 uid（或 root）不匹配

​

清单优先行为

• 识别插件
• 发现声明的通道/技能/配置模式或 bundle 能力
• 验证 plugins.entries.<id>.config
• 增强 Control UI 标签/占位符
• 展示安装/目录元数据
• 在不加载插件运行时的情况下保留廉价的激活和设置描述符

• CLI 加载会缩小到拥有所请求主命令的插件
• 通道设置/插件解析会缩小到拥有所请求通道 id 的插件
• 显式提供者设置/运行时解析会缩小到拥有所请求提供者 id 的插件
• Gateway 启动规划会对显式启动导入使用 activation.onStartup；没有启动元数据的插件只会通过更窄的激活触发器加载

​

插件缓存边界

• PluginLoaderCacheState 和兼容的活动运行时注册表
• jiti/module 缓存和公共表面加载器缓存，用于避免重复导入 相同的运行时表面
• 用于已安装插件工件的文件系统缓存
• 用于路径规范化或重复项解析的短生命周期、按调用创建的 map

• 发现结果
• 直接的清单注册表
• 从已安装插件索引重建的清单注册表
• 提供者所有者查找、模型抑制、提供者策略或公共工件元数据
• 任何其他派生自清单的答案，只要清单变更、已安装索引变化或加载路径变化，应在下一次元数据读取时可见

​

注册表模型

• 插件模块 -> 注册表注册
• 核心运行时 -> 注册表消费

​

会话绑定回调

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // 现在已经为该插件 + 会话存在一个绑定。
        console.log(event.binding?.conversationId);
        return;
      }

      // 请求被拒绝；清除任何本地待处理状态。
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status："approved" 或 "denied"
• decision："allow-once"、"allow-always" 或 "deny”`
• binding：批准请求的已解析绑定
• request：原始请求摘要、解除绑定提示、发送者 ID 和会话元数据

​

提供方运行时钩子

• Manifest 元数据，用于运行时前的低成本查找： setup.providers[].envVars、providerAuthAliases、providerAuthChoices 和 channelConfigs。
• 配置时钩子：catalog 以及 applyConfigDefaults。
• 运行时钩子：40 多个可选钩子，涵盖身份验证、模型解析、 流包装、思考级别、重放策略和用量端点。请参阅 钩子顺序和用法。

​

钩子顺序与使用

​

提供商示例

api.registerProvider({
  id: "example-proxy",
  label: "示例代理",
  auth: [],
  catalog: {
    order: "simple",
    run: async (ctx) => {
      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;
      if (!apiKey) {
        return null;
      }
      return {
        provider: {
          baseUrl: "https://proxy.example.com/v1",
          apiKey,
          api: "openai-completions",
          models: [{ id: "auto", name: "自动" }],
        },
      };
    },
  },
  resolveDynamicModel: (ctx) => ({
    id: ctx.modelId,
    name: ctx.modelId,
    provider: "example-proxy",
    api: "openai-completions",
    baseUrl: "https://proxy.example.com/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 8192,
  }),
  prepareRuntimeAuth: async (ctx) => {
    const exchanged = await exchangeToken(ctx.apiKey);
    return {
      apiKey: exchanged.token,
      baseUrl: exchanged.baseUrl,
      expiresAt: exchanged.expiresAt,
    };
  },
  resolveUsageAuth: async (ctx) => {
    const auth = await ctx.resolveOAuthToken();
    return auth ? { token: auth.token } : null;
  },
  fetchUsageSnapshot: async (ctx) => {
    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);
  },
});

​

内置示例

​

运行时辅助工具

const clip = await api.runtime.tts.textToSpeech({
  text: "来自 OpenClaw 的问候",
  cfg: api.config,
});

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "来自 OpenClaw 的问候",
  cfg: api.config,
});

const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});

• textToSpeech 为文件/语音消息表面返回正常的核心 TTS 输出载荷。
• 使用核心 tts 配置和提供方选择。
• 返回 PCM 音频缓冲区及采样率。插件必须针对提供方进行重采样/编码。
• listVoices 对每个提供方来说都是可选的。将其用于供应商自有的语音选择器或设置流程。
• 核心会向提供方的 listVoices 钩子传递解析后的请求截止时间；提供方特定的超时设置可能会覆盖该时间。
• 语音列表可以包含更丰富的元数据，例如区域设置、性别和个性标签，以便支持提供方感知的选择器。
• 目前 OpenAI 和 ElevenLabs 支持电话场景。Microsoft 不支持。

api.registerSpeechProvider({
  id: "acme-speech",
  label: "Acme Speech",
  isConfigured: ({ config }) => Boolean(config.messages?.tts),
  synthesize: async (req) => {
    return {
      audioBuffer: Buffer.from([]),
      outputFormat: "mp3",
      fileExtension: ".mp3",
      voiceCompatible: false,
    };
  },
});

• 将 TTS 策略、回退和回复投递保留在核心中。
• 对于供应商自有的合成行为，请使用语音提供方。
• 旧版 Microsoft edge 输入会被规范化为 microsoft 提供方 id。
• 推荐的所有权模型是公司导向的：一个供应商插件可以拥有文本、语音、图像，以及 OpenClaw 增加这些能力合同时的未来媒体提供方。

api.registerMediaUnderstandingProvider({
  id: "google",
  capabilities: ["image", "audio", "video"],
  describeImage: async (req) => ({ text: "..." }),
  transcribeAudio: async (req) => ({ text: "..." }),
  describeVideo: async (req) => ({ text: "..." }),
});

• 将编排、回退、配置和通道接线保留在核心中。
• 将供应商行为保留在提供方插件中。
• 增量扩展应保持类型化：新增可选方法、新增可选结果字段、新增可选能力。
• 视频生成已经遵循相同模式：
  • 核心负责能力合约和运行时辅助工具
  • 供应商插件注册 api.registerVideoGenerationProvider(...)
  • 功能/通道插件消费 api.runtime.videoGeneration.*

const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

const extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({
  provider: "codex",
  model: "gpt-5.6-sol",
  input: [
    {
      type: "image",
      buffer: receiptImageBuffer,
      fileName: "receipt.png",
      mime: "image/png",
    },
    { type: "text", text: "使用打印出的字段作为事实来源。" },
  ],
  instructions: "返回实体和可搜索标签。",
  schemaName: "example.evidence",
  jsonSchema: {
    type: "object",
    properties: {
      entities: { type: "array", items: { type: "string" } },
      tags: { type: "array", items: { type: "string" } },
    },
  },
  cfg: api.config,
});

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // 当无法可靠推断 MIME 时可选：
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* 是图像/音频/视频理解的首选共享接口。
• extractStructuredWithModel(...) 是面向插件的、用于有界供应商自有图像优先提取的衔接点。至少应包含一个图像输入；文本输入作为补充上下文。产品插件负责其路由和架构，而 OpenClaw 负责提供方/运行时边界。
• 使用核心媒体理解音频配置（tools.media.audio）和提供方回退顺序。
• 当未生成转写输出时（例如输入被跳过或不受支持），返回 { text: undefined }。

const result = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Expand this query into focused follow-up searches.",
  toolsAlsoAllow: ["my_plugin_progress"],
  provider: "openai",
  model: "gpt-4.1-mini",
  deliver: false,
});

• provider 和 model 是每次运行可选的覆盖项，不是持久的会话更改。
• toolsAlsoAllow 接受由调用插件注册的、精确且唯一拥有的工具名称。核心和含糊不清的名称会被拒绝。它会在正常配置文件的基础上进行叠加，但操作员的允许列表和拒绝列表仍然具有最终权威。
• OpenClaw 仅对受信任的调用方认可这些覆盖字段。
• 对于插件拥有的回退运行，操作员必须显式启用 plugins.entries.<id>.subagent.allowModelOverride: true。
• 使用 plugins.entries.<id>.subagent.allowedModels 将受信任插件限制到特定的规范化 provider/model 目标，或者使用 "*" 显式允许任何目标。
• 不受信任的插件子代理运行仍然可以工作，但覆盖请求会被拒绝，而不是静默回退。
• 由插件创建的子代理会话会标记创建它的插件 id。兼容的 api.runtime.subagent.deleteSession(...) 只能删除这些所属会话；任意会话删除仍然需要具有管理员范围的 Gateway 请求。

const providers = api.runtime.webSearch.listProviders({
  config: api.config,
});

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: {
    query: "OpenClaw 插件运行时辅助工具",
    count: 5,
  },
});

• 将提供方选择、凭据解析和共享请求语义保留在核心中。
• 对于供应商特定的搜索传输，请使用网络搜索提供方。
• api.runtime.webSearch.* 是需要搜索行为、但不依赖代理工具包装器的功能/通道插件的首选共享接口。

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "一个友好的龙虾吉祥物", size: "1024x1024" },
});

const providers = api.runtime.imageGeneration.listProviders({
  config: api.config,
});

• generate(...)：使用已配置的图像生成提供方链生成图像。
• listProviders(...)：列出可用的图像生成提供方及其能力。

​

Gateway HTTP 路由

api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin",
  match: "exact",
  handler: async (_req, res) => {
    res.statusCode = 200;
    res.end("ok");
    return true;
  },
});

• path: Gateway HTTP 服务器下的路由路径。
• auth: 必填，"gateway" 或 "plugin"。使用 "gateway" 要求常规 Gateway 身份验证，使用 "plugin" 则由插件管理身份验证或 Webhook 验证。
• match: 可选。"exact"（默认）或 "prefix"。
• handleUpgrade: 可选，用于处理同一路由上的 WebSocket 升级请求。
• replaceExisting: 可选。仅动态生命周期注册要替换自身现有路由时必需。
• handler: 路由处理请求时返回 true。

• api.registerHttpHandler(...) 已被移除，使用它会导致插件加载错误。请改用 api.registerHttpRoute(...)。
• 插件路由必须显式声明 auth。
• 具有相同 match 模式的规范等价路径共用一个路由。同一插件中的静态 api.registerHttpRoute(...) 调用会替换该路由；其他插件无法替换它。
• 不同 auth 级别的重叠路由会被拒绝。仅在相同的身份验证级别上保留 exact/prefix 回退链。
• 使用 openclaw/plugin-sdk/webhook-ingress 中的 registerPluginHttpRoute(...) 的动态生命周期代码必须设置 replaceExisting: true，以刷新自身的规范路由。命名注册只能替换具有相同非空 pluginId 的注册；当任一方设置了路由 source 时，双方都必须设置相同的非空 source。对于已发布 SDK 调用方，同一插件的无 source 到无 source 刷新以及匿名到匿名刷新仍受支持，但命名路由和匿名路由不能相互替换。
• 将路由 source 视为稳定的同插件子所有者标识，而不是诊断标签。现有的无 source 调用方可以继续省略它；使用 source 的调用方必须在刷新期间保持其不变。
• 动态生命周期注册在被拒绝时默认记录日志并返回一个空操作注销回调。当就绪状态依赖该路由时，请设置 throwOnFailure: true；必需的内置 Webhook 传输使用严格注册，因此不会在没有有效入口的情况下报告就绪。
• auth: "plugin" 路由不会自动获得操作员运行时作用域。它们用于插件管理的 Webhook 或签名验证，而不是特权 Gateway 辅助调用。
• auth: "gateway" 路由在 Gateway 请求运行时作用域中运行。默认界面（gatewayRuntimeScopeSurface: "write-default"）有意保持保守：
  • 共享密钥 bearer 身份验证（gateway.auth.mode = "token" / "password"）以及任何非可信代理身份验证方法，即使调用方发送了 x-openclaw-scopes，也只获得单个 operator.write 作用域
  • 未显式提供 x-openclaw-scopes 标头的 trusted-proxy 调用方同样仅保留传统的 operator.write 作用域界面
  • 提供了 x-openclaw-scopes 的 trusted-proxy 调用方则获得所声明的作用域
  • 路由可以选择 gatewayRuntimeScopeSurface: "trusted-operator"，以便对携带身份的身份验证模式始终遵循 x-openclaw-scopes（如果未提供该标头，则回退到完整的 CLI 默认作用域集合）
• 由 auth: "gateway" 路由支持的沙盒化外部 Control UI 标签页使用仅由经过身份验证的引导流程签发的短期签名 Cookie 授权；插件身份验证标签页保留其直接 iframe 路径。在挂载之前，父页面会在同一个不透明沙盒内运行路由专属探测；当浏览器隐私策略阻止 Cookie 时，探测会安全失败。该授权绑定到所属插件、匹配的路由根路径以及当前身份验证代次；其进程随机生成的 Cookie 名称可防止受信任的同主机 Gateway 相互覆盖，但 Cookie 无法隔离 TCP 端口。因此，Gateway 主机名构成一个凭据边界：不要在该主机名下托管相互不信任的服务，包括其他端口。路由分发会拒绝针对另一个插件所拥有嵌套路由的重用。由于沙盒后代在 Cookie 语义上属于跨站点内容，该授权仅接受带有 operator.read 的 GET 和 HEAD 请求；变更操作和 WebSocket 升级仍必须使用显式的 Gateway 身份验证界面。该 Cookie 有意不能使用 CHIPS：当前浏览器会在分区密钥中加入跨站祖先标记，因此嵌套的不透明沙盒框架将无法访问同一路由的资源。该 Cookie 要求安全上下文以及浏览器对跨站 Cookie 的许可，因此在普通 HTTP 局域网来源或完全阻止第三方 Cookie 的环境下，Gateway 身份验证的外部标签页不可用；请使用 HTTPS/Tailscale Serve，或使用兼容 Cookie 策略且受浏览器信任的回环地址。
• 该授权可防止 Gateway bearer 令牌泄露以及路由/作用域被意外复用；但它不会在原生插件之间建立安全边界。原生插件代码及其提供的 UI 内容仍属于同一受信任的进程内插件边界。
• 实际规则：不要假设 Gateway 身份验证的插件路由隐含具备管理员界面。如果你的路由需要仅限管理员的行为，请选择 trusted-operator 作用域界面，要求使用携带身份的身份验证模式，并记录明确的 x-openclaw-scopes 标头约定。
• 启动插件会在 Gateway 开始监听后，使用其完整运行时注册 HTTP 路由。在启动侧车就绪之前，未被其他路由声明的 HTTP 请求会返回 503 以及 Retry-After: 1；核心路由仍会正常分发。此通用回退机制覆盖了运行时注册表尚无法识别其所有者之前的插件路由。
• 路由匹配和身份验证后，普通处理程序会参与 Gateway 根级工作准入。Gateway 已准备就绪或正在重启时，会在调用处理程序之前返回 503。唯一的狭义例外是：一个拥有清单授权的 auth: "gateway" 路由，同时选择了路由专属的 trusted-operator 界面；该路由仍可访问，从而避免暂停控制分发被阻塞，而同一插件的普通兄弟路由仍处于准入边界之后。WebSocket handleUpgrade 的所有权使用相同的原子准入边界；一旦处理程序接受套接字，该套接字后续的生命周期便由插件所有，并不受此边界跟踪。

​

插件 SDK 导入路径

• index.js — 打包后的插件入口
• api.js — 辅助工具/类型聚合入口
• runtime-api.js — 仅运行时聚合入口
• setup-entry.js — 设置插件入口

​

消息工具架构

• presentation 用于语义展示块（text、context、 divider、chart、table、buttons、select）
• delivery-pin 用于置顶发送请求

​

渠道目标解析

• messaging.inferTargetChatType({ to }) 决定在目录查找之前，是否应将规范化目标视为 direct、group 或 channel。 隐式所有者心跳传递要求进行此直接分类；否则，Gateway 状态报告将显示 waiting for route。
• messaging.targetResolver.looksLikeId(raw, normalized) 告知核心，某个输入是否应跳过目录搜索，直接进行类似 ID 的解析。
• messaging.targetResolver.reservedLiterals 列出对于该提供商而言属于渠道／会话引用的裸词。解析会在拒绝保留字面量之前保留已配置的目录条目，然后在目录未命中时安全失败。
• messaging.targetResolver.resolveTarget(...) 是核心在规范化之后或目录未命中之后需要提供商负责的最终解析时，由插件提供的回退方案。
• messaging.resolveOutboundSessionRoute(...) 在目标解析完成后，负责构建提供商特定的会话路由。

• 将 inferTargetChatType 用于应在搜索对等方／群组之前发生的分类决策。
• 将 looksLikeId 用于“将其视为显式／原生目标 ID”的检查。
• 将 resolveTarget 用于提供商特定的归一化回退，而不是用于广泛目录搜索。
• 将聊天 ID、线程 ID、JID、句柄和房间 ID 等提供商原生 ID 保留在 target 值或提供商特定参数中，而不是放在通用 SDK 字段里。

​

基于配置的目录

• 基于 allowlist 的 DM peers
• 已配置的 channel/group 映射
• 账户作用域的静态目录回退

• 查询过滤
• limit 应用
• 去重/归一化辅助
• 构建 ChannelDirectoryEntry[]

​

provider 目录

• { provider } 表示单个 provider 条目
• { providers } 表示多个 provider 条目

• simple：普通 API key 或 env 驱动的 provider
• profile：在存在认证 profile 时出现的 provider
• paired：合成多个相关 provider 条目的 provider
• late：最后一轮，在其他隐式 provider 之后

• discovery 仍可作为旧别名使用，但会发出弃用警告
• 如果同时注册了 catalog 和 discovery，OpenClaw 会使用 catalog 并发出警告
• augmentModelCatalog 已弃用；内置 provider 应通过 registerModelCatalogProvider 发布补充行。

​

只读渠道检查

• resolveAccount(...) 是运行时路径。它可以假设凭据已经完全实例化，并且在所需密钥缺失时快速失败。
• 诸如 openclaw status、openclaw status --all、openclaw channels status、openclaw channels resolve 以及 doctor/config 修复流程等只读命令路径，不应仅为了描述配置而去实例化运行时凭据。

• 只返回具描述性的账户状态。
• 保留 enabled 和 configured。
• 在相关时包含凭据来源/状态字段，例如：
  • tokenSource、tokenStatus
  • botTokenSource、botTokenStatus
  • appTokenSource、appTokenStatus
  • signingSecretSource、signingSecretStatus
• 仅为了报告只读可用性，不需要返回原始 token 值。返回 tokenStatus: "available"（以及匹配的 source 字段）对状态类命令已经足够。
• 当凭据通过 SecretRef 配置，但在当前命令路径中不可用时，使用 configured_unavailable。

​

包集合

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"],
    "setupEntry": "./src/setup-entry.ts"
  }
}

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

​

频道目录元数据

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk（自托管）",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "通过 Nextcloud Talk webhook 机器人实现自托管聊天。",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel：用于更丰富的目录／状态界面的次要标签
• docsLabel：覆盖文档链接的文本
• preferOver：此目录条目应优先于的低优先级插件／频道 id
• selectionDocsPrefix、selectionDocsOmitLabel、selectionExtras：选择界面的文案控制项
• markdownCapable：将频道标记为支持 Markdown，以便进行出站格式化决策
• exposure.configured：设为 false 时，将频道从已配置频道列表界面中隐藏
• exposure.setup：设为 false 时，将频道从交互式设置／配置选择器中隐藏
• exposure.docs：将频道标记为内部／私有频道，用于文档导航界面
• quickstartAllowFrom：将频道加入标准快速入门 allowFrom 流程
• forceAccountBinding：即使只有一个账户，也要求显式账户绑定
• preferSessionLookupForAnnounceTarget：解析公告目标时优先使用会话查找

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

上下文引擎插件

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("lossless-claw", (ctx) => ({
    info: {
      id: "lossless-claw",
      name: "Lossless Claw",
      ownsCompaction: true,
      acceptedHostParams: ["sessionKey"],
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, sessionKey, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentSessionKey: sessionKey,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("my-memory-engine", (ctx) => ({
    info: {
      id: "my-memory-engine",
      name: "我的记忆引擎",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, sessionKey, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentSessionKey: sessionKey,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

添加新能力

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

​

能力检查清单

• src/<capability>/types.ts 中的 core 契约类型
• src/<capability>/runtime.ts 中的 core 运行器/运行时辅助函数
• 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 契约
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// 插件 API
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) {
    return await generateOpenAiVideo(req);
  },
});

// 供功能/渠道插件使用的共享运行时辅助函数
const clip = await api.runtime.videoGeneration.generate({
  prompt: "展示机器人在实验室中行走。",
  cfg,
});

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

• core 负责能力契约 + 编排
• 厂商插件负责厂商实现
• 功能/通道插件消费运行时辅助函数
• 契约测试让所有权保持明确。

​

相关内容

• 插件架构 — 公共能力模型和形状
• 插件 SDK 子路径
• 插件 SDK 设置
• 构建插件。