first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,76 @@
+## ADDED Requirements
+
+### Requirement: Plugin bridge exposes only platform-mediated actions
+
+The system SHALL define a plugin page bridge with narrow action names for server context reads, job dispatch, log queries, artifact references, scoped file requests, and platform-mediated AI invocation.
+
+#### Scenario: Plugin page requests allowed bridge action
+
+- **WHEN** a plugin page requests a bridge action declared by the bridge contract and permitted by its manifest metadata
+- **THEN** the platform authorizes the request without exposing run credentials, raw host paths, direct sockets, storage backend credentials, platform auth storage, or AI provider keys
+
+#### Scenario: Plugin page requests unsupported bridge action
+
+- **WHEN** a plugin page requests an action outside the bridge contract
+- **THEN** the platform rejects the request with a validation error before dispatching any run, file, log, artifact, or AI work
+
+### Requirement: Bridge permissions are enforced from manifest metadata
+
+The system SHALL evaluate each bridge action against the installed plugin's declared permissions, page permissions, and AI purposes before allowing the action.
+
+#### Scenario: Missing permission denies bridge action
+
+- **WHEN** a plugin page requests `files.request` without the required file permission in its manifest or page permissions
+- **THEN** the platform returns a denied bridge authorization decision and does not create a file job
+
+#### Scenario: Allowed AI purpose authorizes AI request
+
+- **WHEN** a plugin page requests `ai.invoke` with an AI purpose declared by the plugin manifest and the plugin has `ai.invoke` permission
+- **THEN** the platform returns an allowed bridge authorization decision without exposing provider base URLs or API keys
+
+#### Scenario: Undeclared AI purpose denies AI request
+
+- **WHEN** a plugin page requests `ai.invoke` with a purpose not declared by the plugin manifest
+- **THEN** the platform rejects or denies the request before invoking any AI provider
+
+### Requirement: Plugin SDK provides typed bridge helpers
+
+The plugin SDK SHALL provide TypeScript types and helpers for bridge context, bridge action names, bridge request envelopes, bridge responses, permission checks, and safe errors.
+
+#### Scenario: SDK builds typed bridge request
+
+- **WHEN** plugin author code builds a request for a supported bridge action through SDK helpers
+- **THEN** the request envelope includes plugin ID, route key, action, request ID, and scoped payload fields that can be validated by the platform host
+
+#### Scenario: SDK detects missing local permission
+
+- **WHEN** plugin author code checks a bridge context for a missing permission
+- **THEN** the SDK helper returns a negative result without performing transport or privileged work
+
+### Requirement: Browser host creates safe bridge context
+
+The frontend host SHALL construct plugin bridge context from installed plugin metadata, current route, selected server instance, safe theme tokens, and effective permissions only.
+
+#### Scenario: Host context omits secrets
+
+- **WHEN** the browser host creates bridge context for a plugin page
+- **THEN** the context excludes raw AI keys, platform auth storage, run credentials, direct sockets, raw host paths, and storage backend credentials
+
+#### Scenario: Host filters page permissions
+
+- **WHEN** a plugin page declares route-specific permissions
+- **THEN** the host context contains only permissions allowed by both the plugin manifest and the current page declaration
+
+### Requirement: Bridge implementation respects root ownership boundaries
+
+The system SHALL keep plugin SDK, frontend host utilities, and platform authorization logic in their owning roots without casual cross-root imports.
+
+#### Scenario: Contracts are copied through explicit root files
+
+- **WHEN** bridge action or permission contracts are needed in multiple roots
+- **THEN** each root owns an explicit local contract file or generated/copy artifact instead of importing implementation code from another root
+
+#### Scenario: Structure validation passes after bridge implementation
+
+- **WHEN** the bridge and SDK implementation is complete
+- **THEN** repository structure validation passes without placing implementation code outside `plugins/`, `platform_web/`, or `platform/`