first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,35 @@
+# Plugin Bridge Contract
+
+Plugins use the platform bridge for every privileged action.
+
+## Allowed Bridge Areas
+
+- `server.instances`: read current server instance context.
+- `jobs.dispatch`: request platform-authorized run jobs.
+- `logs.query`: query historical logs by server, stream, time range, cursor, or analysis window.
+- `artifacts.open`: request platform-mediated artifact download references.
+- `files.request`: request scoped file list/read/patch/replace operations through platform jobs.
+- `ai.invoke`: request platform-mediated AI assistance.
+- `theme.tokens`: read safe platform theme tokens.
+
+## Execution Envelopes
+
+Plugin pages build execution requests with `createBridgeExecutionRequest` and hand them to the host-provided bridge transport. The SDK never owns `fetch`, platform authorization headers, run sockets, or provider credentials.
+
+Execution responses use `requestId`, plugin/page/server scope, action, status, optional result refs, and optional safe errors. Use `parseBridgeExecutionResponse` before reading results so plugin code handles denied, deferred, and failed states uniformly.
+
+AI requests use `createAIInvocationRequest` with an explicit purpose, prompt, scoped context refs, and optional current config. Use `parseAIInvocationResponse` to consume recommendations and safe errors. Plugin code must not include provider API keys, provider base URLs, bearer tokens, or direct transport details in AI request payloads.
+
+Artifact open requests use `createArtifactOpenRequest` with an artifact ID that belongs to the current server/job scope. Use `parseArtifactReference` to consume the bridge result. Parsed references contain platform-owned download URLs, filename, content type, size, checksum, expiry, range support, and chunk size; they do not contain bytes or raw storage adapter locations.
+
+## Forbidden Data
+
+The bridge must not expose:
+
+- raw run credentials.
+- raw host paths.
+- AI provider API keys.
+- platform auth storage.
+- storage backend endpoints.
+- unrestricted artifact storage credentials.
+- direct storage URLs or presigned backend URLs.