Nội bộ kiến trúc Plugin

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Quy trình tải

1. phát hiện các gốc Plugin ứng viên
2. đọc manifest bundle native hoặc tương thích và siêu dữ liệu package
3. từ chối các ứng viên không an toàn
4. chuẩn hóa cấu hình Plugin (plugins.enabled, allow, deny, entries, slots, load.paths)
5. quyết định trạng thái bật cho từng ứng viên
6. tải các module native đã bật: các module đi kèm đã build dùng bộ tải native; các Plugin native chưa build dùng jiti
7. gọi hook native register(api) và thu thập các đăng ký vào registry Plugin
8. cung cấp registry cho các lệnh/bề mặt runtime

​

Hành vi ưu tiên manifest

• định danh Plugin
• phát hiện kênh/skills/schema cấu hình hoặc năng lực bundle đã khai báo
• xác thực plugins.entries.<id>.config
• bổ sung nhãn/placeholder cho Control UI
• hiển thị siêu dữ liệu cài đặt/catalog
• giữ các descriptor kích hoạt và thiết lập rẻ mà không tải runtime Plugin

• tải CLI thu hẹp xuống các Plugin sở hữu lệnh chính được yêu cầu
• phân giải thiết lập/Plugin kênh thu hẹp xuống các Plugin sở hữu id kênh được yêu cầu
• phân giải thiết lập/runtime provider tường minh thu hẹp xuống các Plugin sở hữu id provider được yêu cầu
• lập kế hoạch khởi động Gateway dùng activation.onStartup cho các import khởi động tường minh và opt-out khởi động; mọi Plugin nên khai báo nó khi OpenClaw chuyển khỏi các import khởi động ngầm định, trong khi Plugin không có siêu dữ liệu năng lực tĩnh và không có activation.onStartup vẫn dùng fallback sidecar khởi động ngầm định đã lỗi thời để tương thích

​

Ranh giới cache Plugin

• PluginLoaderCacheState và registry runtime đang hoạt động tương thích
• cache jiti/module và cache bộ tải bề mặt công khai dùng để tránh import cùng một bề mặt runtime nhiều lần
• mirror dependency runtime và cache hệ thống file cho artifact Plugin đã cài đặt
• map theo từng lời gọi tồn tại ngắn hạn để chuẩn hóa đường dẫn hoặc phân giải bản trùng

• kết quả phát hiện
• registry manifest trực tiếp
• registry manifest được tái tạo từ index Plugin đã cài đặt
• lookup owner provider, chặn model, policy provider hoặc siêu dữ liệu artifact công khai
• bất kỳ câu trả lời nào khác suy ra từ manifest mà manifest, index đã cài đặt hoặc load path đã thay đổi phải hiển thị ở lần đọc siêu dữ liệu tiếp theo

​

Mô hình registry

• bản ghi Plugin (định danh, nguồn, origin, trạng thái, chẩn đoán)
• công cụ
• hook kế thừa và hook có kiểu
• kênh
• provider
• handler RPC Gateway
• tuyến HTTP
• registrar CLI
• dịch vụ nền
• lệnh do Plugin sở hữu

• module Plugin -> đăng ký registry
• runtime core -> tiêu thụ registry

​

Callback liên kết cuộc trò chuyện

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // A binding now exists for this plugin + conversation.
        console.log(event.binding?.conversationId);
        return;
      }

      // The request was denied; clear any local pending state.
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" hoặc "denied"
• decision: "allow-once", "allow-always" hoặc "deny"
• binding: binding đã phân giải cho yêu cầu được phê duyệt
• request: tóm tắt yêu cầu gốc, gợi ý detach, id người gửi và siêu dữ liệu cuộc trò chuyện

​

Hook runtime provider

• Siêu dữ liệu manifest để lookup trước runtime với chi phí thấp: setup.providers[].envVars, tương thích đã lỗi thời providerAuthEnvVars, providerAuthAliases, providerAuthChoices và channelEnvVars.
• Hook thời điểm cấu hình: catalog (discovery kế thừa) cộng với applyConfigDefaults.
• Hook runtime: hơn 40 hook tùy chọn bao phủ auth, phân giải model, bọc stream, mức suy nghĩ, policy replay và endpoint usage. Xem danh sách đầy đủ trong Thứ tự hook và cách dùng.

​

Thứ tự hook và cách dùng

​

Ví dụ về nhà cung cấp

api.registerProvider({
  id: "example-proxy",
  label: "Example Proxy",
  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: "Auto" }],
        },
      };
    },
  },
  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);
  },
});

​

Ví dụ tích hợp sẵn

​

Trình trợ giúp runtime

const clip = await api.runtime.tts.textToSpeech({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

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

• textToSpeech trả về payload đầu ra TTS lõi thông thường cho các bề mặt tệp/ghi chú thoại.
• Sử dụng cấu hình lõi messages.tts và lựa chọn nhà cung cấp.
• Trả về bộ đệm âm thanh PCM + tốc độ lấy mẫu. Plugin phải lấy mẫu lại/mã hóa cho nhà cung cấp.
• listVoices là tùy chọn theo từng nhà cung cấp. Dùng nó cho các bộ chọn giọng nói hoặc luồng thiết lập do nhà cung cấp sở hữu.
• Danh sách giọng nói có thể bao gồm metadata phong phú hơn như ngôn ngữ, giới tính và thẻ tính cách cho các bộ chọn nhận biết nhà cung cấp.
• OpenAI và ElevenLabs hiện hỗ trợ điện thoại. Microsoft thì không.

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,
    };
  },
});

• Giữ chính sách TTS, fallback và phân phối trả lời trong lõi.
• Dùng nhà cung cấp giọng nói cho hành vi tổng hợp do nhà cung cấp sở hữu.
• Đầu vào Microsoft cũ edge được chuẩn hóa thành id nhà cung cấp microsoft.
• Mô hình sở hữu được ưu tiên là theo công ty: một Plugin nhà cung cấp có thể sở hữu nhà cung cấp văn bản, giọng nói, hình ảnh và phương tiện trong tương lai khi OpenClaw bổ sung các hợp đồng capability đó.

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

• Giữ điều phối, fallback, cấu hình và đấu nối kênh trong lõi.
• Giữ hành vi nhà cung cấp trong Plugin nhà cung cấp.
• Mở rộng bổ sung nên giữ có kiểu: phương thức tùy chọn mới, trường kết quả tùy chọn mới, capability tùy chọn mới.
• Tạo video đã theo cùng mẫu:
  • lõi sở hữu hợp đồng capability và trình trợ giúp runtime
  • Plugin nhà cung cấp đăng ký api.registerVideoGenerationProvider(...)
  • Plugin tính năng/kênh tiêu thụ 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 { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // Optional when MIME cannot be inferred reliably:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* là bề mặt dùng chung được ưu tiên cho việc hiểu hình ảnh/âm thanh/video.
• Sử dụng cấu hình âm thanh media-understanding của lõi (tools.media.audio) và thứ tự fallback nhà cung cấp.
• Trả về { text: undefined } khi không tạo ra đầu ra phiên âm nào (ví dụ đầu vào bị bỏ qua/không được hỗ trợ).
• api.runtime.stt.transcribeAudioFile(...) vẫn là alias tương thích.

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

• provider và model là các ghi đè tùy chọn theo từng lần chạy, không phải thay đổi phiên lâu dài.
• OpenClaw chỉ tôn trọng các trường ghi đè đó cho bên gọi đáng tin cậy.
• Với các lần chạy fallback do Plugin sở hữu, operator phải chọn tham gia bằng plugins.entries.<id>.subagent.allowModelOverride: true.
• Dùng plugins.entries.<id>.subagent.allowedModels để giới hạn Plugin đáng tin cậy vào các đích provider/model chuẩn cụ thể, hoặc "*" để cho phép rõ ràng mọi đích.
• Các lần chạy subagent của Plugin không đáng tin cậy vẫn hoạt động, nhưng yêu cầu ghi đè bị từ chối thay vì âm thầm fallback.
• Các phiên subagent do Plugin tạo được gắn thẻ bằng id Plugin tạo ra. Fallback api.runtime.subagent.deleteSession(...) chỉ có thể xóa các phiên được sở hữu đó; xóa phiên tùy ý vẫn cần một yêu cầu Gateway có phạm vi admin.

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

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: {
    query: "OpenClaw plugin runtime helpers",
    count: 5,
  },
});

• Giữ lựa chọn nhà cung cấp, phân giải thông tin xác thực và ngữ nghĩa yêu cầu dùng chung trong lõi.
• Dùng nhà cung cấp tìm kiếm web cho các transport tìm kiếm riêng theo nhà cung cấp.
• api.runtime.webSearch.* là bề mặt dùng chung được ưu tiên cho Plugin tính năng/kênh cần hành vi tìm kiếm mà không phụ thuộc vào wrapper công cụ agent.

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "A friendly lobster mascot", size: "1024x1024" },
});

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

• generate(...): tạo hình ảnh bằng chuỗi nhà cung cấp tạo hình ảnh đã cấu hình.
• listProviders(...): liệt kê các nhà cung cấp tạo hình ảnh có sẵn và capability của họ.

​

Tuyến HTTP của Gateway

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

• path: đường dẫn tuyến trong máy chủ HTTP của gateway.
• auth: bắt buộc. Dùng "gateway" để yêu cầu xác thực gateway thông thường, hoặc "plugin" cho xác thực/xác minh Webhook do Plugin quản lý.
• match: tùy chọn. "exact" (mặc định) hoặc "prefix".
• replaceExisting: tùy chọn. Cho phép cùng Plugin thay thế đăng ký tuyến hiện có của chính nó.
• handler: trả về true khi tuyến đã xử lý yêu cầu.

• api.registerHttpHandler(...) đã bị gỡ bỏ và sẽ gây lỗi tải Plugin. Thay vào đó, hãy dùng api.registerHttpRoute(...).
• Các route của Plugin phải khai báo auth một cách rõ ràng.
• Các xung đột path + match chính xác sẽ bị từ chối trừ khi có replaceExisting: true, và một Plugin không thể thay thế route của Plugin khác.
• Các route chồng lấn với mức auth khác nhau sẽ bị từ chối. Chỉ giữ các chuỗi chuyển tiếp exact/prefix ở cùng một mức auth.
• Các route auth: "plugin" không tự động nhận phạm vi runtime của operator. Chúng dành cho webhook/xác minh chữ ký do Plugin quản lý, không phải các lệnh gọi trợ giúp Gateway có đặc quyền.
• Các route auth: "gateway" chạy bên trong phạm vi runtime của yêu cầu Gateway, nhưng phạm vi đó được cố ý giữ thận trọng:
  • xác thực bearer bằng bí mật dùng chung (gateway.auth.mode = "token" / "password") giữ phạm vi runtime của route Plugin cố định ở operator.write, ngay cả khi bên gọi gửi x-openclaw-scopes
  • các chế độ HTTP có danh tính đáng tin cậy (ví dụ trusted-proxy hoặc gateway.auth.mode = "none" trên ingress riêng tư) chỉ tôn trọng x-openclaw-scopes khi header đó được cung cấp rõ ràng
  • nếu thiếu x-openclaw-scopes trên các yêu cầu route Plugin có danh tính đó, phạm vi runtime sẽ quay về operator.write
• Quy tắc thực tế: đừng giả định route Plugin xác thực qua gateway là một bề mặt admin ngầm định. Nếu route của bạn cần hành vi chỉ dành cho admin, hãy yêu cầu chế độ auth có danh tính và ghi tài liệu cho hợp đồng header x-openclaw-scopes rõ ràng.

​

Đường dẫn import Plugin SDK

• index.js — entry Plugin đóng gói sẵn
• api.js — barrel trình trợ giúp/kiểu
• runtime-api.js — barrel chỉ dành cho runtime
• setup-entry.js — entry Plugin thiết lập

​

Schema công cụ tin nhắn

• presentation cho các khối trình bày ngữ nghĩa (text, context, divider, buttons, select)
• delivery-pin cho yêu cầu ghim việc gửi

​

Phân giải mục tiêu kênh

• messaging.inferTargetChatType({ to }) quyết định liệu một mục tiêu đã chuẩn hóa nên được xem là direct, group, hay channel trước khi tra cứu thư mục.
• messaging.targetResolver.looksLikeId(raw, normalized) cho core biết liệu một đầu vào nên bỏ qua thẳng sang phân giải dạng id thay vì tìm kiếm thư mục.
• messaging.targetResolver.resolveTarget(...) là fallback của Plugin khi core cần phân giải cuối cùng do nhà cung cấp sở hữu sau khi chuẩn hóa hoặc sau khi không tìm thấy trong thư mục.
• messaging.resolveOutboundSessionRoute(...) sở hữu việc xây dựng route phiên theo nhà cung cấp sau khi một mục tiêu đã được phân giải.

• Dùng inferTargetChatType cho các quyết định phân loại cần xảy ra trước khi tìm kiếm peer/group.
• Dùng looksLikeId cho các kiểm tra “xem mục này là id mục tiêu rõ ràng/gốc”.
• Dùng resolveTarget cho fallback chuẩn hóa theo nhà cung cấp, không dùng cho tìm kiếm thư mục rộng.
• Giữ các id gốc của nhà cung cấp như chat id, thread id, JID, handle và room id bên trong các giá trị target hoặc tham số theo nhà cung cấp, không đặt trong trường SDK chung.

​

Thư mục dựa trên config

• peer DM dựa trên allowlist
• ánh xạ kênh/group đã cấu hình
• fallback thư mục tĩnh theo phạm vi tài khoản

• lọc truy vấn
• áp dụng giới hạn
• trình trợ giúp loại trùng/chuẩn hóa
• xây dựng ChannelDirectoryEntry[]

​

Danh mục nhà cung cấp

• { provider } cho một mục nhà cung cấp
• { providers } cho nhiều mục nhà cung cấp

• simple: nhà cung cấp thuần API key hoặc do env điều khiển
• profile: nhà cung cấp xuất hiện khi có hồ sơ auth
• paired: nhà cung cấp tổng hợp nhiều mục nhà cung cấp liên quan
• late: lượt cuối, sau các nhà cung cấp ngầm định khác

• discovery vẫn hoạt động như alias cũ
• nếu cả catalog và discovery được đăng ký, OpenClaw dùng catalog

​

Kiểm tra kênh chỉ đọc

• resolveAccount(...) là đường dẫn runtime. Nó được phép giả định thông tin xác thực đã được materialize đầy đủ và có thể thất bại nhanh khi thiếu secret bắt buộc.
• Các đường dẫn lệnh chỉ đọc như openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve, và các luồng doctor/config repair không nên cần materialize thông tin xác thực runtime chỉ để mô tả cấu hình.

• Chỉ trả về trạng thái tài khoản mang tính mô tả.
• Giữ nguyên enabled và configured.
• Bao gồm các trường nguồn/trạng thái thông tin xác thực khi liên quan, chẳng hạn:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Bạn không cần trả về giá trị token thô chỉ để báo cáo khả năng sẵn có chỉ đọc. Trả về tokenStatus: "available" (và trường nguồn tương ứng) là đủ cho các lệnh kiểu status.
• Dùng configured_unavailable khi thông tin xác thực được cấu hình qua SecretRef nhưng không khả dụng trong đường dẫn lệnh hiện tại.

​

Gói package

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

• bản thân việc đăng ký kênh
• mọi route HTTP phải khả dụng trước khi gateway bắt đầu lắng nghe
• mọi phương thức, công cụ hoặc dịch vụ gateway phải tồn tại trong cùng khoảng thời gian đó

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

{
  "name": "@scope/my-channel",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}

​

Siêu dữ liệu catalog kênh

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: nhãn phụ cho các bề mặt catalog/trạng thái phong phú hơn
• docsLabel: ghi đè văn bản liên kết cho liên kết tài liệu
• preferOver: các id Plugin/kênh có mức ưu tiên thấp hơn mà mục catalog này nên xếp trên
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: các điều khiển nội dung cho bề mặt lựa chọn
• markdownCapable: đánh dấu kênh là có khả năng markdown cho các quyết định định dạng gửi ra
• exposure.configured: ẩn kênh khỏi các bề mặt liệt kê kênh đã cấu hình khi đặt thành false
• exposure.setup: ẩn kênh khỏi các bộ chọn thiết lập/cấu hình tương tác khi đặt thành false
• exposure.docs: đánh dấu kênh là nội bộ/riêng tư cho các bề mặt điều hướng tài liệu
• showConfigured / showInSetup: các alias cũ vẫn được chấp nhận để tương thích; ưu tiên exposure
• quickstartAllowFrom: chọn cho kênh tham gia luồng quickstart allowFrom tiêu chuẩn
• forceAccountBinding: yêu cầu liên kết tài khoản rõ ràng ngay cả khi chỉ có một tài khoản tồn tại
• preferSessionLookupForAnnounceTarget: ưu tiên tra cứu phiên khi phân giải đích thông báo

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

​

Plugin công cụ ngữ cảnh

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 },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    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: "My Memory Engine",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

Thêm một capability mới

1. định nghĩa hợp đồng lõi Quyết định hành vi dùng chung nào lõi nên sở hữu: chính sách, fallback, hợp nhất cấu hình, lifecycle, ngữ nghĩa hướng kênh và hình dạng helper runtime.
2. thêm các bề mặt đăng ký/runtime Plugin có kiểu Mở rộng OpenClawPluginApi và/hoặc api.runtime với bề mặt capability có kiểu nhỏ nhất hữu ích.
3. nối dây lõi + consumer kênh/tính năng Các kênh và Plugin tính năng nên dùng capability mới thông qua lõi, không import trực tiếp một triển khai vendor.
4. đăng ký các triển khai vendor Sau đó các Plugin vendor đăng ký backend của chúng với capability.
5. thêm coverage hợp đồng Thêm kiểm thử để quyền sở hữu và hình dạng đăng ký vẫn rõ ràng theo thời gian.

​

Checklist capability

• kiểu hợp đồng lõi trong src/<capability>/types.ts
• runner/helper runtime lõi trong src/<capability>/runtime.ts
• bề mặt đăng ký API Plugin trong src/plugins/types.ts
• nối dây registry Plugin trong src/plugins/registry.ts
• phơi bày runtime Plugin trong src/plugins/runtime/* khi Plugin tính năng/kênh cần dùng nó
• helper capture/kiểm thử trong src/test-utils/plugin-registration.ts
• assertion quyền sở hữu/hợp đồng trong src/plugins/contracts/registry.ts
• tài liệu operator/Plugin trong docs/

​

Mẫu capability

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

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

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

expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);

• lõi sở hữu hợp đồng capability + điều phối
• Plugin vendor sở hữu triển khai vendor
• Plugin tính năng/kênh dùng helper runtime
• kiểm thử hợp đồng giữ cho quyền sở hữu rõ ràng

​

Liên quan

• Kiến trúc Plugin — mô hình capability công khai và các hình dạng
• Subpath Plugin SDK
• Thiết lập Plugin SDK
• Xây dựng Plugin