feat: 自动更新

2026-07-15 19:43:06 +08:00
parent f64eb0831f
commit f3b14b7945
54 changed files with 3207 additions and 589 deletions
@@ -0,0 +1,19 @@
+## Why
+
+AI provider setup currently exposes implementation fields such as provider ID, Base URL, models, timeout, and redaction policy as the primary workflow. This is too noisy for normal provider onboarding and makes operators fill fields that the platform can derive from a provider preset. The magical-girl theme also becomes visually harsh when a user-uploaded background is active because the custom-background overrides reintroduce high-saturation pink/gold overlays on already busy imagery.
+
+## What Changes
+
+- Simplify AI provider onboarding so the normal path is provider kind plus platform secret reference, with provider ID generated automatically.
+- Move Base URL, model list, default model, relay mode, timeout, and redaction policy into an advanced section with provider-specific defaults.
+- Preserve the platform boundary: the frontend manages secret references and does not persist or display raw API keys.
+- Require AI provider management API routes to use platform administrator authentication.
+- Reduce magical-girl custom-background surface saturation, frame accessory opacity, and pink/gold glow while keeping the crystal-moonlight visual direction.
+- Document the local debug port discipline: use `scripts/local-debug-start.sh` and the documented `LOCAL_DEBUG_*` overrides instead of starting ad hoc ports.
+
+## Impact
+
+- Affected roots: `platform/`, `platform_web/`, `docs/`, `openspec/`.
+- Expected files: AI provider API handlers/tests, AI provider frontend contracts/schema/page/tests, shared theme CSS/tests/readme, local-debug docs.
+- No billing, cloud host sales, provider marketplace, direct run socket, plugin credential, or unrelated SaaS behavior changes.
+- Verification: focused backend/frontend tests, `scripts/check-structure.sh`, `openspec validate polish-ai-provider-onboarding --strict`, and browser walkthrough against the existing local debug stack.
@@ -0,0 +1,35 @@
+## MODIFIED Requirements
+
+### Requirement: AI provider management preserves secret boundaries
+AI provider management SHALL reject raw key material in request fields and SHALL never expose raw API keys in API responses or frontend-visible types.
+
+#### Scenario: Raw key is submitted during update
+- **WHEN** a create or update request includes raw key material instead of a secret reference in `apiKeyRef`
+- **THEN** the platform MUST reject the request with a validation error and MUST NOT persist the provider
+
+#### Scenario: Provider is returned to UI
+- **WHEN** the backend or frontend API client returns provider data
+- **THEN** the response/type MUST include `apiKeyRef` only and MUST NOT include `apiKey`, `rawApiKey`, or equivalent raw credential fields
+
+#### Scenario: Provider management route is accessed without platform admin
+- **WHEN** a client creates, lists, reads, updates, tests, changes status, or lists models for AI providers without a platform administrator bearer session
+- **THEN** the platform MUST reject the request with a stable JSON authorization error
+
+### Requirement: AI provider console page is functional
+The management console SHALL provide a functional operational view for configured providers while keeping normal setup focused on provider kind and platform-owned secret references.
+
+#### Scenario: Operator opens AI provider page
+- **WHEN** the AI provider page renders
+- **THEN** it MUST show provider counts, status distribution, configured model counts, and a provider table
+
+#### Scenario: Operator creates provider from normal form
+- **WHEN** an operator creates a provider through the normal form
+- **THEN** the page MUST generate the provider ID and apply provider-specific defaults for Base URL, model list, relay mode, timeout, and redaction policy before submitting named API requests
+
+#### Scenario: Operator edits advanced provider metadata
+- **WHEN** an operator opens advanced settings
+- **THEN** the page MAY allow editing Base URL, model list, default model, relay mode, timeout, and redaction policy without requiring the operator to manually edit the provider ID
+
+#### Scenario: Operator uses provider actions
+- **WHEN** an operator triggers enable/disable, test, or model-list actions
+- **THEN** the page MUST call the matching API client methods and display the redacted result state
@@ -0,0 +1,12 @@
+## MODIFIED Requirements
+
+### Requirement: Uploaded backgrounds remain readable and restrained
+The platform_web theme system SHALL preserve uploaded background visibility while keeping operational surfaces readable and avoiding harsh high-saturation overlays.
+
+#### Scenario: Magical-girl theme uses a custom background
+- **WHEN** `data-custom-background="true"` and `data-theme-palette="magical-girl"` are active
+- **THEN** shared operational surfaces MUST use restrained translucent materials, muted frame accessories, and reduced glow so the background does not become visually harsh
+
+#### Scenario: Custom background theme styling changes
+- **WHEN** custom-background shared CSS is modified
+- **THEN** CSS contract tests or theme documentation MUST cover the intended restraint so future changes do not reintroduce excessive pink/gold gradients
@@ -0,0 +1,39 @@
+## 1. AI Provider Setup
+
+- [x] 1.1 Hide provider ID from the primary form and generate it deterministically from provider kind/name.
+- [x] 1.2 Keep the primary workflow to provider kind plus platform secret reference, using official-provider defaults for Base URL, models, relay mode, timeout, and redaction policy.
+- [x] 1.3 Move lower-frequency provider metadata into an advanced section.
+- [x] 1.4 Preserve frontend and backend raw-key redaction boundaries.
+
+## 2. API Authorization
+
+- [x] 2.1 Require platform administrator authentication for AI provider create/list/detail/update/status/test/models routes.
+- [x] 2.2 Add or update backend tests for authorized management and unauthorized rejection.
+
+## 3. Custom Background Theme Polish
+
+- [x] 3.1 Tone down magical-girl custom-background panel gradients, frame ornaments, and glow.
+- [x] 3.2 Add CSS contract coverage so custom-background magical-girl overrides stay muted.
+- [x] 3.3 Update theme documentation to explain custom-background restraint.
+
+## 4. Local Debug Documentation
+
+- [x] 4.1 Document that agents should use `scripts/local-debug-start.sh` and existing default ports unless explicit `LOCAL_DEBUG_*` overrides are provided.
+- [x] 4.2 Document restart discipline through `scripts/local-debug-stop.sh` then `scripts/local-debug-start.sh`.
+
+## 5. Verification
+
+- [x] 5.1 Run focused backend AI provider API tests.
+- [x] 5.2 Run focused frontend AI provider/theme tests plus typecheck/build if touched code requires it.
+- [x] 5.3 Run `scripts/check-structure.sh`.
+- [x] 5.4 Run `openspec validate polish-ai-provider-onboarding --strict`.
+- [x] 5.5 Browser-walkthrough `http://127.0.0.1:5173/#/aiProviders` using the existing local debug stack; cover magical-girl custom-background via CSS contract test.
+
+## Evidence
+
+- `npm test -- AiProvidersPage.test.tsx aiProviders.test.ts base-css.test.js` passed.
+- `go test ./api -run 'TestAIProvider|TestAIInvocation|TestPluginBridgeExecute|TestCoreAPI(CreateListDetailWorkflows|ErrorResponses)' -count=1` passed.
+- `npm run typecheck` and `npm run build` passed in `platform_web`.
+- `scripts/check-structure.sh` passed.
+- `openspec validate polish-ai-provider-onboarding --strict` returned valid; PostHog telemetry flush failed due DNS after validation success.
+- Browser walkthrough used existing `http://127.0.0.1:5173/#/aiProviders`: logged in with local debug account, opened 新增提供商, confirmed no editable ID input, generated ID copy, and no visible raw key copy. OpenAI defaults `gpt-5.6-terra, gpt-5.6-luna` are covered by `schemas/aiProviders.test.ts`; magical-girl custom-background restraint is covered by `theme/base-css.test.js`.