mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 05:20:43 +00:00
84 lines
4.2 KiB
Markdown
84 lines
4.2 KiB
Markdown
# Extensions Boundary
|
|
|
|
This directory contains bundled plugins. Treat it as the same boundary that
|
|
third-party plugins see.
|
|
|
|
## Public Contracts
|
|
|
|
- Docs:
|
|
- `docs/plugins/building-plugins.md`
|
|
- `docs/plugins/architecture.md`
|
|
- `docs/plugins/sdk-overview.md`
|
|
- `docs/plugins/sdk-entrypoints.md`
|
|
- `docs/plugins/sdk-runtime.md`
|
|
- `docs/plugins/sdk-channel-plugins.md`
|
|
- `docs/plugins/sdk-provider-plugins.md`
|
|
- `docs/plugins/manifest.md`
|
|
- Definition files:
|
|
- `src/plugin-sdk/plugin-entry.ts`
|
|
- `src/plugin-sdk/core.ts`
|
|
- `src/plugin-sdk/provider-entry.ts`
|
|
- `src/plugin-sdk/channel-contract.ts`
|
|
- `scripts/lib/plugin-sdk-entrypoints.json`
|
|
- `package.json`
|
|
|
|
## Boundary Rules
|
|
|
|
- Extension production code should import from `openclaw/plugin-sdk/*` and its
|
|
own local barrels such as `./api.ts` and `./runtime-api.ts`.
|
|
- Do not import core internals from `src/**`, `src/channels/**`,
|
|
`src/plugin-sdk-internal/**`, or another extension's `src/**`.
|
|
- Do not use relative imports that escape the current extension package root.
|
|
- Keep plugin metadata accurate in `openclaw.plugin.json` and the package
|
|
`openclaw` block so discovery and setup work without executing plugin code.
|
|
- Plugin runtime dependencies belong to the owning plugin package. If a plugin
|
|
dependency has a runtime peer, declare/provide it in that plugin's
|
|
`package.json`; do not move it to root unless root/package dist owns the
|
|
import. Runtime never installs deps; install/update/doctor are repair points.
|
|
- Keep plugin dependency assertions in generic contracts
|
|
(`package-manifest.contract.test.ts`,
|
|
`extension-runtime-dependencies.contract.test.ts`) rather than plugin e2e
|
|
tests when they express package ownership.
|
|
- Treat files like `src/**`, `onboard.ts`, and other local helpers as private
|
|
unless you intentionally promote them through `api.ts` and, if needed, a
|
|
matching `src/plugin-sdk/<id>.ts` facade.
|
|
- If core or core tests need a bundled plugin helper, export it from `api.ts`
|
|
first instead of letting them deep-import extension internals.
|
|
- For provider plugins, keep auth, onboarding, catalog selection, and
|
|
vendor-only product behavior local to the plugin. Do not move those into
|
|
core just because two providers look similar.
|
|
- Before adding a new provider-local `wrapStreamFn`, `buildReplayPolicy`,
|
|
`normalizeToolSchemas`, `inspectToolSchemas`, or compat patch helper, check
|
|
whether the same behavior already exists through `openclaw/plugin-sdk/*`.
|
|
Reuse shared family helpers first.
|
|
- If two bundled providers share the same replay policy shape, tool-schema
|
|
compat rewrite, payload patch, or stream-wrapper chain, stop copying the
|
|
logic. Extract one shared helper and migrate both call sites in the same
|
|
change.
|
|
- Prefer named provider-family helpers over repeating raw option bags. If a
|
|
provider needs OpenAI-style Anthropic tool payload compat, Gemini schema
|
|
cleanup, or an XAI compat patch, use a named shared helper instead of
|
|
inlining the policy knobs again.
|
|
- Keep control-plane metadata separate from runtime logic. Discovery, config
|
|
validation, setup hints, onboarding hints, and activation planning should be
|
|
expressible from manifest/descriptors whenever possible.
|
|
- If setup truly requires runtime execution, make that explicit in the plugin's
|
|
declared setup/runtime surface instead of letting metadata flows import
|
|
runtime code accidentally.
|
|
- Do not rely on eager global registry seeding or import-time side effects to
|
|
make a plugin “available”. Plugin availability should come from manifest
|
|
ownership plus targeted activation.
|
|
- When core needs plugin-owned static data on a hot path, expose a lightweight
|
|
top-level artifact such as `gateway-auth-api.ts`, `message-tool-api.ts`, or a
|
|
similarly narrow `*-api.ts`. Reuse the same local helper from the artifact and
|
|
the full plugin so fast paths do not drift from runtime behavior.
|
|
|
|
## Expanding The Boundary
|
|
|
|
- If an extension needs a new seam, add a typed Plugin SDK subpath or additive
|
|
export instead of reaching into core.
|
|
- Keep new plugin-facing seams backwards-compatible and versioned. Third-party
|
|
plugins consume this surface.
|
|
- When intentionally expanding the contract, update the docs, exported subpath
|
|
list, package exports, and API/contract checks in the same change.
|