first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,39 @@
+# AI Provider Contracts
+
+AI providers are platform-managed model endpoints used by plugins through scoped platform capabilities.
+
+## AIProviderConfig
+
+- `id`: provider ID.
+- `name`: display name.
+- `kind`: provider kind.
+- `baseUrl`: base URL or relay URL.
+- `apiKeyRef`: secret reference.
+- `models`: allowed model list.
+- `defaultModel`: default model.
+- `relayMode`: direct, relay, or local.
+- `timeoutMs`: timeout.
+- `status`: active, disabled, or error.
+- `redactionPolicy`: redaction policy key.
+
+## AIInvocationRequest
+
+- `providerId`: selected provider.
+- `purpose`: scoped purpose such as `config.suggest` or `logs.diagnose`.
+- `serverInstanceId`: optional server context.
+- `pluginId`: caller plugin.
+- `inputRef`: artifact or bounded structured input.
+- `model`: optional model override.
+
+AI invocation responses must be bounded and must not include raw provider credentials. Config write suggestions must be presented as a diff or recommendation before dispatching run jobs.
+
+## Management API Contracts
+
+- `AIProviderCreateRequest`: create provider metadata with `apiKeyRef`, never raw key material.
+- `AIProviderUpdateRequest`: replace editable provider metadata while preserving status through the service layer.
+- `AIProviderStatusRequest`: set provider status to `active` or `disabled`.
+- `AIProviderResponse`: redacted provider response with `apiKeyRef` only.
+- `AIProviderTestResponse`: local metadata validation result with `mode=metadata`; live external connectivity is deferred.
+- `AIProviderModelsResponse`: configured model list and default model, without credentials.
+
+Management endpoints must reject raw key-shaped values in `apiKeyRef`. Platform-mediated AI invocation is implemented through the platform service boundary; live external connectivity tests and remote model discovery are deferred to later changes.