first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -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