first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-06
@@ -0,0 +1,67 @@
+## Context
+
+AI provider credentials and base URLs belong to `platform/`, while plugin pages may request AI assistance only through platform-mediated capabilities. AI-suggested config changes must be reviewable before any run-side write job is dispatched. This change introduces the invocation boundary and keeps provider clients mockable so implementation and tests do not require real keys or external services.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Add AI invocation request/response contracts with plugin, server, purpose, model preference, input, and review context.
+- Enforce allowed purposes from plugin manifest metadata and platform policy.
+- Route invocation through platform-owned provider configuration and a provider client interface.
+- Return bounded recommendations, safe text, structured diff suggestions, and usage metadata.
+- Ensure config-writing suggestions remain reviewable and are not automatically dispatched to run.
+- Add tests for validation, provider selection, mock invocation, purpose denial, redaction, and bridge integration.
+
+**Non-Goals:**
+
+- No real external provider network calls in tests or default local mode.
+- No raw API key exposure to plugins, platform_web, run, logs, job payloads, or API responses.
+- No automatic config write dispatch from AI output.
+- No provider billing, agent-provider marketplace, cloud host sales, or unrelated SaaS workflows.
+
+## Decisions
+
+### Decision 1: Provider client is an interface with mock default for tests
+
+The platform service owns provider selection and calls a narrow provider client interface. Tests and local verification use a deterministic fake provider client, while live provider clients can be added later behind the same interface.
+
+Alternative considered: implement live OpenAI/Anthropic calls immediately. Rejected because this request must not require real keys/accounts or external paid services.
+
+### Decision 2: AI purposes are mandatory
+
+Every invocation request includes a purpose such as config recommendation, troubleshooting, log summary, or plugin assistant. Platform validation checks that the plugin and requested context allow that purpose before provider selection.
+
+Alternative considered: infer purpose from prompt text. Rejected because permission checks need explicit reviewable inputs.
+
+### Decision 3: Config outputs are recommendations, not writes
+
+For config-related requests, responses may include a proposed diff or recommendation object. The caller must still use config preview/approval APIs before any run-side write occurs.
+
+Alternative considered: let AI invocation directly queue config write jobs. Rejected because AI-suggested changes must be reviewable before dispatch.
+
+### Decision 4: Redaction happens before persistence and response
+
+Request metadata, prompts, provider errors, and responses are scanned for unsafe credential-like content before logging or returning to browser/plugin callers.
+
+Alternative considered: rely on caller discipline and avoid scanning. Rejected because provider and prompt output can accidentally include sensitive-looking material.
+
+## Risks / Trade-offs
+
+- [Risk] Mock provider behavior can hide live provider quirks. Mitigation: keep provider interface small and add live integration in a separate opt-in change.
+- [Risk] Purpose checks may reject useful flows. Mitigation: add new purposes through explicit manifest and OpenSpec updates.
+- [Risk] AI output can be over-trusted by operators. Mitigation: config changes return reviewable diffs and never auto-dispatch.
+
+## Migration Plan
+
+1. Add platform invocation contracts, validators, provider client interface, service, routes, and tests.
+2. Add frontend API client and plugin bridge request plumbing.
+3. Add plugin SDK/example helpers and tests.
+4. Update docs and run full verification.
+
+Rollback removes invocation routes/provider interface integrations and this change's artifacts before plugin workflows depend on them.
+
+## Open Questions
+
+- Which live provider client should be implemented first after mock-mediated invocation passes?
+- Which audit event schema should capture AI recommendation review and operator approval?
@@ -0,0 +1,28 @@
+## Why
+
+AI provider management can store safe provider metadata, and plugin bridge contracts can request AI assistance by purpose. The missing piece is the platform-mediated invocation path: plugins and pages need AI help for reviewable recommendations without ever receiving raw provider keys, base URL credentials, or unmanaged model access.
+
+## What Changes
+
+- Add platform AI invocation domain, DTO, validator, service, and API behavior for purpose-scoped requests.
+- Route requests through platform-owned provider configuration and mockable provider clients, with no real-key requirement for tests.
+- Return bounded AI recommendations, usage metadata, and reviewable config diff suggestions instead of direct run-side writes.
+- Add plugin bridge/SDK and frontend client integration for `ai.invoke` requests without exposing provider credentials.
+- Add tests proving purpose enforcement, provider redaction, unsafe prompt/payload rejection, mock provider behavior, and no raw key exposure.
+
+## Capabilities
+
+### New Capabilities
+
+- `platform-mediated-ai-invocation`: Platform-owned AI invocation for plugin and console workflows with purpose validation, credential isolation, bounded outputs, and reviewable recommendations.
+
+### Modified Capabilities
+
+- Builds on `ai-provider-management` and plugin bridge capabilities without adding raw provider access to plugins or platform_web.
+
+## Impact
+
+- Affects `platform/` AI invocation contracts, services, validators, APIs, and tests.
+- Affects `platform_web/` API contracts/client and plugin bridge host behavior for AI requests.
+- Affects `plugins/` SDK/example AI request helpers and tests.
+- Does not require real provider keys/accounts, external paid services, live network calls in tests, billing, cloud host sales, or direct config writes.
@@ -0,0 +1,65 @@
+## ADDED Requirements
+
+### Requirement: AI invocation is platform-mediated
+
+The platform SHALL expose AI invocation only through platform-owned APIs and services that use stored provider metadata and never expose raw provider credentials to plugins, platform_web, run, or API responses.
+
+#### Scenario: Plugin invokes allowed AI purpose
+- **WHEN** a plugin page submits an `ai.invoke` request with an allowed purpose and bounded input
+- **THEN** the platform MUST validate the purpose, select an enabled provider through platform-owned configuration, invoke a provider client, and return a redacted AI response
+
+#### Scenario: Raw provider credential is never returned
+- **WHEN** any AI invocation succeeds or fails
+- **THEN** the response MUST NOT include raw API keys, provider bearer tokens, provider base URL secrets, platform auth storage, run credentials, direct sockets, or raw host paths
+
+### Requirement: AI purposes and payloads are validated
+
+The platform SHALL validate invocation purpose, plugin permissions, server scope, model preference, input size, context references, and unsafe credential-like content before invoking a provider client.
+
+#### Scenario: Undeclared purpose is denied
+- **WHEN** a plugin requests an AI purpose not declared by its manifest metadata or current bridge page permissions
+- **THEN** the platform MUST deny the request before provider invocation
+
+#### Scenario: Unsafe payload is rejected
+- **WHEN** an invocation payload includes raw key-like content, absolute host paths, direct sockets, or unbounded input
+- **THEN** the platform MUST reject the request with a safe validation error
+
+### Requirement: Provider invocation is mockable and bounded
+
+The platform SHALL invoke AI through a provider client interface that supports deterministic tests without real external accounts or paid services.
+
+#### Scenario: Mock provider returns recommendation
+- **WHEN** tests or local mode use the mock provider client
+- **THEN** invocation MUST return deterministic safe content, usage metadata, and optional structured recommendations without network access
+
+#### Scenario: Provider failure is redacted
+- **WHEN** the provider client returns an error
+- **THEN** the platform MUST return a safe error response without provider credentials or raw transport details
+
+### Requirement: Config suggestions remain reviewable
+
+AI-generated configuration changes SHALL be returned as recommendations or diff previews and SHALL NOT directly dispatch run-side config write jobs.
+
+#### Scenario: AI suggests config edit
+- **WHEN** an invocation purpose requests config assistance
+- **THEN** the response MAY include a proposed diff or recommendation, but the platform MUST require the separate config preview/approval workflow before dispatching a write job
+
+### Requirement: Frontend and plugin SDK use mediated AI contracts
+
+The frontend and plugin SDK SHALL use typed AI bridge/API contracts and SHALL NOT expose provider keys or raw provider configuration to plugin code.
+
+#### Scenario: Plugin SDK builds AI request
+- **WHEN** plugin code builds an AI invocation request
+- **THEN** it MUST include purpose, request ID, scoped input, and context references while excluding raw provider credentials
+
+#### Scenario: Browser walkthrough verifies AI request safety
+- **WHEN** AI invocation UI behavior is claimed complete
+- **THEN** a browser walkthrough MUST verify an AI-assisted workflow renders redacted results and does not expose raw credential markers
+
+### Requirement: Platform-mediated AI invocation is verified
+
+The change SHALL include backend tests, frontend tests/build, plugin tests/typecheck, browser walkthrough evidence, structure validation, and strict OpenSpec validation.
+
+#### Scenario: Verification commands pass
+- **WHEN** the change is complete
+- **THEN** platform tests, platform_web tests/typecheck/build, plugin tests/typecheck, `scripts/check-structure.sh`, and `openspec validate implement-platform-mediated-ai-invocation --strict` MUST pass
@@ -0,0 +1,41 @@
+## 1. Platform AI Invocation Contracts
+
+- [x] 1.1 Add domain and DTO contracts for AI invocation requests, context refs, purposes, recommendations, usage metadata, and safe errors.
+- [x] 1.2 Add validators for purpose authorization, provider IDs, model preferences, bounded input/output, context refs, and unsafe credential/path/socket content.
+- [x] 1.3 Add a platform provider client interface and deterministic mock provider implementation for tests/local verification.
+
+## 2. Platform AI Invocation Service And API
+
+- [x] 2.1 Add service methods that authorize purpose-scoped invocation, select enabled providers, call the provider client, redact outputs, and return typed responses.
+- [x] 2.2 Implement AI invocation route using named DTOs and service methods.
+- [x] 2.3 Ensure config-related AI responses produce reviewable recommendations/diffs and never dispatch run-side writes directly.
+- [x] 2.4 Update platform route/protocol documentation for mediated AI invocation and live-provider deferral.
+- [x] 2.5 Add platform tests for allowed invocation, undeclared purpose denial, unsafe payload rejection, provider failure redaction, config recommendation reviewability, and no raw key exposure.
+
+## 3. Frontend And Plugin Integration
+
+- [x] 3.1 Add centralized `platform_web/api` AI invocation types and client methods.
+- [x] 3.2 Integrate AI invocation into plugin bridge host execution flow for `ai.invoke` responses.
+- [x] 3.3 Add plugin SDK/example helpers for AI invocation request builders and safe response parsing.
+- [x] 3.4 Add frontend and plugin tests for mediated AI requests, denied purposes, redacted results, and no direct provider config exposure.
+
+## 4. Verification
+
+- [x] 4.1 Run `cd platform && go test ./...` and record evidence.
+- [x] 4.2 Run `cd platform_web && npm run typecheck && npm test && npm run build` and record evidence.
+- [x] 4.3 Run `cd plugins && npm run typecheck && npm test` and record evidence.
+- [x] 4.4 Run browser walkthrough for mediated AI invocation and record evidence.
+- [x] 4.5 Run `scripts/check-structure.sh` and record evidence.
+- [x] 4.6 Run `openspec validate implement-platform-mediated-ai-invocation --strict` and record evidence.
+
+## Evidence
+
+- 2026-07-06: `cd platform && GOCACHE=/private/tmp/browser-go-build-cache go test ./... -run TestAIInvocationAPIIsMediatedAndSafe -count=1` passed for mediated invocation, purpose denial, unsafe prompt rejection, config suggestion reviewability/no job dispatch, bridge `ai.invoke`, and no forbidden response fragments.
+- 2026-07-06: `cd platform_web && npm run typecheck` and `cd platform_web && npm test -- --run api/client.test.ts utils/pluginBridgeHost.test.ts` passed for AI invocation API types/client and bridge `ai.invoke` dispatcher behavior.
+- 2026-07-06: `cd plugins && npm run typecheck` and `cd plugins && npm test -- --run tests/manifest-validation.test.ts` passed for SDK AI invocation request/response helpers and no provider config exposure.
+- 2026-07-06: `cd platform && GOCACHE=/private/tmp/browser-go-build-cache go test ./...` passed.
+- 2026-07-06: `cd platform_web && npm run typecheck`, `cd platform_web && npm test`, and `cd platform_web && npm run build` passed.
+- 2026-07-06: `cd plugins && npm run typecheck` and `cd plugins && npm test` passed.
+- 2026-07-06: Browser walkthrough passed using a local mock platform API plus headless Chrome: logged in, opened `#/servers/server-ai-walkthrough`, switched to `插件控制`, clicked `AI 调用`, verified `AI 建议已返回`, and confirmed no forbidden credential/path/provider fragments were rendered.
+- 2026-07-06: `scripts/check-structure.sh` passed.
+- 2026-07-06: `openspec validate implement-platform-mediated-ai-invocation --strict` passed (`Change 'implement-platform-mediated-ai-invocation' is valid`; PostHog DNS flush warnings were non-fatal telemetry failures).