From 81abd9d4c0d554606e900148238782cca5df4ebe Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Tue, 28 Apr 2026 04:03:15 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@1e3ce10e2782a4d2876a31132fbf8b56798b8c0f --- .openclaw-sync/source.json | 4 +- .../.generated/plugin-sdk-api-baseline.sha256 | 4 +- docs/plugins/architecture.md | 2 +- docs/plugins/building-plugins.md | 5 +-- docs/plugins/sdk-migration.md | 42 ++++++------------- docs/plugins/sdk-overview.md | 8 ++-- docs/plugins/sdk-subpaths.md | 17 +++----- 7 files changed, 30 insertions(+), 52 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 18359c658..61f9d3a36 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "4d69f81a4e6c700e0c14045fbc0cba9fc9a4271e", - "syncedAt": "2026-04-28T04:00:14.901Z" + "sha": "1e3ce10e2782a4d2876a31132fbf8b56798b8c0f", + "syncedAt": "2026-04-28T04:01:51.991Z" } diff --git a/docs/.generated/plugin-sdk-api-baseline.sha256 b/docs/.generated/plugin-sdk-api-baseline.sha256 index 77c81248e..5d0f3abc3 100644 --- a/docs/.generated/plugin-sdk-api-baseline.sha256 +++ b/docs/.generated/plugin-sdk-api-baseline.sha256 @@ -1,2 +1,2 @@ -5a77a53e9d48f4b683838a3993e583db8037edf836e8e13a209cc0ad1c89d809 plugin-sdk-api-baseline.json -d31c5887a379c48a714e91d00a7d7fde7dff353319aee38a98babfdb753f49fb plugin-sdk-api-baseline.jsonl +cde228fda2602bd5e9aa07bc855d12859ded5c56f64f0075caaa02ccb2a2bc3c plugin-sdk-api-baseline.json +3adcd10f99a2b055271bbac9a8066cf8f680ec550dbe4f8ea4fd98474d12e2ad plugin-sdk-api-baseline.jsonl diff --git a/docs/plugins/architecture.md b/docs/plugins/architecture.md index b37738ad7..5e771b0b7 100644 --- a/docs/plugins/architecture.md +++ b/docs/plugins/architecture.md @@ -473,7 +473,7 @@ Keep capability registration public. Trim non-contract helper exports: - vendor-specific convenience helpers - setup/onboarding helpers that are implementation details -Some bundled-plugin helper subpaths still remain in the generated SDK export map for compatibility and bundled-plugin maintenance. Current examples include `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup`, `plugin-sdk/bundled-channel-config-schema`, `plugin-sdk/channel-config-schema-legacy`, and several `plugin-sdk/matrix*` seams. Treat those as deprecated or reserved exports, not as the recommended SDK pattern for new third-party plugins. +Some bundled-plugin helper subpaths still remain in the generated SDK export map for bundled-plugin maintenance when they have tracked owner usage. Current examples include `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/github-copilot-token`, `plugin-sdk/memory-core`, `plugin-sdk/bundled-channel-config-schema`, and `plugin-sdk/channel-config-schema-legacy`. Treat those as reserved exports, not as the recommended SDK pattern for new third-party plugins. ## Internals and reference diff --git a/docs/plugins/building-plugins.md b/docs/plugins/building-plugins.md index 4018ad3b8..70695eda0 100644 --- a/docs/plugins/building-plugins.md +++ b/docs/plugins/building-plugins.md @@ -280,9 +280,8 @@ If a helper is only useful inside one bundled provider package, keep it on that package-root seam instead of promoting it into `openclaw/plugin-sdk/*`. Some generated `openclaw/plugin-sdk/` helper seams still exist for -bundled-plugin maintenance and compatibility, for example -`plugin-sdk/feishu-setup` or `plugin-sdk/zalo-setup`. Treat those as reserved -surfaces, not as the default pattern for new third-party plugins. +bundled-plugin maintenance when they have tracked owner usage. Treat those as +reserved surfaces, not as the default pattern for new third-party plugins. ## Pre-submission checklist diff --git a/docs/plugins/sdk-migration.md b/docs/plugins/sdk-migration.md index 1fa28aaa6..91551a1a7 100644 --- a/docs/plugins/sdk-migration.md +++ b/docs/plugins/sdk-migration.md @@ -90,18 +90,15 @@ For external plugins, compatibility work follows this order: Maintainers can audit the current migration queue with `pnpm plugins:boundary-report`. Use `pnpm plugins:boundary-report:summary` for -compact counts, `--owner ` for one plugin or compatibility owner, -`--retirement-plan` for an issue/PR-ready dormant SDK checklist, and +compact counts, `--owner ` for one plugin or compatibility owner, and `pnpm plugins:boundary-report:ci` when a CI gate should fail on due compatibility records, cross-owner reserved SDK imports, or unused reserved SDK -subpaths without a dormant classification. The report groups deprecated +subpaths. The report groups deprecated compatibility records by removal date, counts local code/docs references, -surfaces cross-owner reserved SDK imports, classifies dormant reserved SDK -subpaths with owner/replacement/remove-after metadata, and summarizes the -private memory-host SDK bridge so compatibility cleanup stays explicit instead -of relying on ad hoc searches. Dormant reserved SDK subpaths are package exports -with no tracked repo imports; keep them until their recorded removal date unless -a separate compatibility review proves the external import never shipped. +surfaces cross-owner reserved SDK imports, and summarizes the private +memory-host SDK bridge so compatibility cleanup stays explicit instead of +relying on ad hoc searches. Reserved SDK subpaths must have tracked owner usage; +unused reserved helper exports should be removed from the public SDK. If a manifest field is still accepted, plugin authors can keep using it until the docs and diagnostics say otherwise. New code should prefer the documented @@ -540,7 +537,6 @@ releases. | `plugin-sdk/memory-host-markdown` | Managed markdown helpers | Shared managed-markdown helpers for memory-adjacent plugins | | `plugin-sdk/memory-host-search` | Active memory search facade | Lazy active-memory search-manager runtime facade | | `plugin-sdk/memory-host-status` | Memory host status alias | Vendor-neutral alias for memory host status helpers | - | `plugin-sdk/memory-lancedb` | Bundled memory-lancedb helpers | Memory-lancedb helper surface | | `plugin-sdk/testing` | Test utilities | Legacy broad compatibility barrel; prefer focused test subpaths such as `plugin-sdk/plugin-test-runtime`, `plugin-sdk/channel-test-helpers`, `plugin-sdk/channel-target-testing`, `plugin-sdk/test-env`, and `plugin-sdk/test-fixtures` | @@ -548,28 +544,16 @@ This table is intentionally the common migration subset, not the full SDK surface. The full list of 200+ entrypoints lives in `scripts/lib/plugin-sdk-entrypoints.json`. -That list still includes some bundled-plugin helper seams such as -`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup`, and `plugin-sdk/matrix*`. Those remain exported for -bundled-plugin maintenance and compatibility, but they are intentionally -omitted from the common migration table and are not the recommended target for -new plugin code. +That list still includes a few bundled-plugin helper seams that have tracked +owner usage. They remain exported for bundled-plugin maintenance, but they are +intentionally omitted from the common migration table and are not the +recommended target for new plugin code. The same rule applies to other bundled-helper families such as: -- browser support helpers: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` -- Matrix: `plugin-sdk/matrix*` -- LINE: `plugin-sdk/line*` -- IRC: `plugin-sdk/irc*` -- bundled helper/plugin surfaces like `plugin-sdk/googlechat`, - `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, - `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, - `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, - `plugin-sdk/twitch`, - `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, - `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, - `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, - and `plugin-sdk/voice-call` +- browser support helpers: `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools` +- Matrix: `plugin-sdk/matrix-runtime-shared` +- bundled helper/plugin surfaces like `plugin-sdk/github-copilot-token` and `plugin-sdk/memory-core` `plugin-sdk/github-copilot-token` currently exposes the narrow token-helper surface `DEFAULT_COPILOT_API_BASE_URL`, diff --git a/docs/plugins/sdk-overview.md b/docs/plugins/sdk-overview.md index 44b71ce80..80802a743 100644 --- a/docs/plugins/sdk-overview.md +++ b/docs/plugins/sdk-overview.md @@ -51,10 +51,10 @@ pattern for new plugins. barrels or add a narrow generic SDK contract when a need is truly cross-channel. -A small set of bundled-plugin helper seams (`plugin-sdk/feishu`, -`plugin-sdk/zalo`, `plugin-sdk/matrix*`, and similar) still appear in the -generated export map. They exist for bundled-plugin maintenance only and are -not recommended import paths for new third-party plugins. +A small set of bundled-plugin helper seams still appear in the generated export +map when they have tracked owner usage. They exist for bundled-plugin +maintenance only and are not recommended import paths for new third-party +plugins. ## Subpath reference diff --git a/docs/plugins/sdk-subpaths.md b/docs/plugins/sdk-subpaths.md index 0ddf83809..3bcf51c28 100644 --- a/docs/plugins/sdk-subpaths.md +++ b/docs/plugins/sdk-subpaths.md @@ -11,10 +11,9 @@ This page catalogs the commonly used subpaths grouped by purpose. The generated full list of 200+ subpaths lives in `scripts/lib/plugin-sdk-entrypoints.json`; reserved bundled-plugin helper subpaths appear there but are implementation detail unless a doc page explicitly promotes them. Maintainers can audit active -and dormant reserved helper subpaths with `pnpm plugins:boundary-report:summary`; -`pnpm plugins:boundary-report --retirement-plan` emits an issue/PR-ready -checklist grouped by owner, and the full JSON report includes dormant helper -owner, replacement, and remove-after metadata. +reserved helper subpaths with `pnpm plugins:boundary-report:summary`; unused +reserved helper exports fail the CI report instead of staying in the public SDK +as dormant compatibility debt. For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview). @@ -311,18 +310,14 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview) | `plugin-sdk/memory-host-markdown` | Shared managed-markdown helpers for memory-adjacent plugins | | `plugin-sdk/memory-host-search` | Active memory runtime facade for search-manager access | | `plugin-sdk/memory-host-status` | Vendor-neutral alias for memory host status helpers | - | `plugin-sdk/memory-lancedb` | Bundled memory-lancedb helper surface | | Family | Current subpaths | Intended use | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Bundled browser plugin support helpers. `browser-profiles` exports `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile`, and `ResolvedBrowserTabCleanupConfig` for the normalized `browser.tabCleanup` shape. `browser-support` remains the compatibility barrel. | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Bundled Matrix helper/runtime surface | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Bundled LINE helper/runtime surface | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Bundled IRC helper surface | - | Channel-specific helpers | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | Deprecated bundled channel compatibility/helper seams. New plugins should import generic SDK subpaths or plugin-local barrels. | - | Auth/plugin-specific helpers | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Bundled feature/plugin helper seams; `plugin-sdk/github-copilot-token` currently exports `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken`, and `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools` | Bundled browser plugin support helpers still consumed by the owner package. | + | Matrix | `plugin-sdk/matrix-runtime-shared` | Bundled Matrix runtime surface still consumed by the owner package. | + | Auth/plugin-specific helpers | `plugin-sdk/github-copilot-token`, `plugin-sdk/memory-core` | Bundled feature/plugin helper seams still consumed by their owners; `plugin-sdk/github-copilot-token` currently exports `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken`, and `resolveCopilotApiToken`. |