feat: 自动更新

2026-07-15 19:43:06 +08:00
parent f64eb0831f
commit f3b14b7945
54 changed files with 3207 additions and 589 deletions
@@ -31,6 +31,10 @@ Platform stores generated run and client-manager packages as artifacts with a di

 Alternative considered: ship one global run binary and ask users to hand-edit config files. Rejected because it causes copy/paste key exposure, weak auditability, and poor operator experience.

+Distribution generation is asynchronous. Platform creates a bounded `distribution.build` job on the assigned run endpoint and returns a `building` distribution with the real job ID. The run worker obtains the secret-bearing build input only through its authenticated leased-job channel, builds in an isolated workspace, and uploads the resulting archive through the artifact channel. Platform marks a distribution `available` only after the job succeeds and the referenced artifact is present and available. A JSON build plan, generated config, or synthetic build log is never a downloadable distribution artifact.
+
+Run packages are built from the trusted run worker checkout. Plugin-declared client managers are checked out from the approved HTTPS Git repository and revision carried by the build job. Build execution uses a fixed build-system adapter and target tuple; repository content cannot supply arbitrary platform-side commands.
+
 ### Decision 2: Run and client-manager credentials are separate singleton keys

 Each server/component has exactly one active run key and, when needed, exactly one active client-manager key. Run and client-manager keys remain different secrets, but platform does not keep multiple simultaneously valid keys for the same component. Resetting a key replaces the encrypted database value, increments the key generation, invalidates every older run or client package for that component, and requires regenerating and redeploying the affected package.
@@ -5,7 +5,11 @@ The platform SHALL let an authorized operator generate a run package for a selec

 #### Scenario: Operator generates run from server actions
 - **WHEN** an authorized operator selects generate executor for a server instance and chooses a supported OS/architecture
- **THEN** platform MUST create or reuse the server's current encrypted run key, write that key into the generated package config, create a distribution record with key generation, build/download artifact, checksum metadata, and audit event, and MUST NOT return the raw key in the API response
+- **THEN** platform MUST create or reuse the server's current encrypted run key, queue a real run-worker build job, return a building distribution with its job ID, compile the target executable, package it with the generated config, publish the completed binary archive and checksum through the artifact channel, record an audit event, and MUST NOT return the raw key in the API response
+
+#### Scenario: Run generation has not completed
+- **WHEN** the run-worker build job is queued, running, failed, or cancelled
+- **THEN** platform MUST keep the distribution unavailable for download, expose the real job state and progress, and MUST NOT substitute generated configuration JSON or a synthetic build log as the downloadable run package

 #### Scenario: Operator downloads generated run package
 - **WHEN** an authorized operator downloads a generated run artifact
@@ -75,7 +79,11 @@ The platform SHALL support plugin-declared client-manager build profiles for com

 #### Scenario: SCUM-style client manager is generated
 - **WHEN** a plugin declares a client-manager build profile with repository, revision policy, supported target platform, build system, config template, and output artifact paths
- **THEN** platform MUST create a build job that checks out the approved source, injects redacted configuration from secret refs, produces a downloadable artifact, and redacts secrets from build logs
+- **THEN** platform MUST create a run-worker build job that checks out the approved source and revision, injects configuration obtained through the authenticated job-input channel, compiles the target executable, uploads the downloadable artifact through the artifact channel, and redacts secrets and workspace paths from progress and build results
+
+#### Scenario: Client-manager build is still running
+- **WHEN** the source checkout, environment check, dependency download, compile, or artifact upload stage is incomplete
+- **THEN** platform_web MUST display the corresponding real job progress and MUST NOT mark later stages complete on a local timer

 #### Scenario: Unsupported client-manager target is requested
 - **WHEN** an operator requests a client-manager build for an OS/architecture not declared by the plugin profile
@@ -53,6 +53,14 @@
 - [x] 7.4 Complete a browser walkthrough for touched server-list and server-detail workflows before marking UI acceptance complete.
 - [x] 7.5 Record verification evidence in this task file before completion.

+## 8. Real Distribution Build Repair
+
+- [ ] 8.1 Replace synchronous synthetic run/client artifacts with queued `distribution.build` jobs, building distribution records, authenticated build-input retrieval, and terminal job projection.
+- [ ] 8.2 Implement the independent run worker build adapter for trusted run source and approved HTTPS client-manager repositories, including fixed Go builds, isolated workspaces, config packaging, checksums, and chunked artifact upload.
+- [ ] 8.3 Drive the platform_web generation dialog from real job progress and terminal state instead of timer-completed stages.
+- [ ] 8.4 Add regression coverage proving generation queues a backend job, does not publish JSON plans as artifacts, publishes only uploaded build output, and reports actual progress/failure.
+- [ ] 8.5 Run focused platform, run, frontend, OpenSpec, and structure verification and record the evidence below.
+
 ## Verification Evidence

 - `cd plugins && npm run validate:manifest`: passed. First sandbox attempt failed with `listen EPERM` on the local `tsx` IPC pipe, then the same command passed with approved escalation.
@@ -0,0 +1,17 @@
+## Why
+
+Profile settings correctly render an uploaded custom background, but the page header metric and background preset controls still label the built-in preset as the current background. This makes users think the uploaded background was ignored when the built-in preset is actually only the fallback after upload removal.
+
+## What Changes
+
+- Show an uploaded custom background as the active background in profile settings summary metrics.
+- Treat the selected built-in background preset as a fallback while a custom background is active.
+- Label the fallback preset explicitly and avoid marking it as the pressed/active visible background.
+- Keep uploaded background precedence and existing theme visual direction unchanged.
+
+## Impact
+
+- Affected root: `platform_web/`.
+- Expected files: `platform_web/pages/ProfileSettingsPage.tsx`, `platform_web/theme/base.css`, and focused page rendering tests.
+- No platform API, persistence schema, authentication, plugin, run, or server management behavior changes.
+- Verification: focused frontend tests, `scripts/check-structure.sh`, and `openspec validate fix-custom-background-status --strict`.
@@ -0,0 +1,19 @@
+## ADDED Requirements
+
+### Requirement: Profile settings distinguish active custom backgrounds from fallback presets
+
+The platform_web profile settings page SHALL report an uploaded custom background as the active workspace background while preserving the selected built-in preset only as the fallback after upload removal.
+
+#### Scenario: Uploaded background is active
+
+- **WHEN** a user has configured an uploaded custom background
+- **AND** a built-in background preset is also selected
+- **THEN** the profile settings summary MUST label the active background as custom rather than naming the built-in preset as current
+- **AND** the selected built-in preset MUST be visibly identified as a fallback that appears after the uploaded background is removed
+- **AND** the uploaded background MUST remain the workspace desktop
+
+#### Scenario: Uploaded background is removed
+
+- **WHEN** a user removes the uploaded custom background
+- **THEN** the previously selected built-in preset becomes the visible active background again
+- **AND** the profile settings summary MAY name that built-in preset as current
@@ -0,0 +1,22 @@
+## 1. Custom Background Status
+
+- [x] 1.1 Show uploaded custom backgrounds as the active background in the profile settings header metric.
+- [x] 1.2 Render the selected built-in preset as a clearly labeled fallback while an uploaded background is active.
+- [x] 1.3 Preserve fallback preset selection so removing the uploaded background restores the selected built-in desktop.
+
+## 2. Verification
+
+- [x] 2.1 Add focused rendering coverage for uploaded-background labeling.
+- [x] 2.2 Run focused frontend tests.
+- [x] 2.3 Run `scripts/check-structure.sh`.
+- [x] 2.4 Run `openspec validate fix-custom-background-status --strict`.
+
+## Evidence
+
+- `npm test -- pages/ConsolePages.test.tsx` passed 10 tests.
+- `npm test` passed 13 files / 68 tests.
+- `npm run typecheck` passed.
+- `npm run build` passed.
+- `scripts/check-structure.sh` passed.
+- `openspec validate fix-custom-background-status --strict` passed; the command printed a PostHog network flush warning after validation because the sandbox cannot resolve `edge.openspec.dev`.
+- Runtime UI check on `http://127.0.0.1:5173/#/profile` confirmed `data-custom-background="true"`, summary `背景 自定义背景`, fallback chip `机甲格纳库 备用`, and theme switch black mecha -> magical-girl preserved the uploaded background.
@@ -0,0 +1,16 @@
+## Why
+
+The local debug SCUM fixture can be registered with a reduced manifest that omits `server.run.distribution`. That makes `scum-alpha` visible and manageable, but `POST /api/v1/server-instances/scum-alpha/run/generate` is denied even though the first-party SCUM manifest declares run distribution support.
+
+## What Changes
+
+- Register the local debug SCUM plugin with the run distribution, dependency, client-manager, bridge, and remote-access declarations from the first-party manifest.
+- Extend local debug smoke proof to verify `generate-run` is available for `scum-alpha`.
+- Extend local debug smoke proof to generate a Windows AMD64 run distribution for `scum-alpha`.
+- Make deterministic run generation recover from an already-created package artifact instead of surfacing `duplicate_resource` to the UI.
+- Make repeated run self-update dispatches return the existing update job when the artifact/checksum/idempotency key match.
+
+## Impact
+
+- Affected specs: `scum-run-distribution-smoke`
+- Affected code: `scripts/local-debug-smoke.sh`, `platform/service/distributions.go`
@@ -0,0 +1,20 @@
+## ADDED Requirements
+
+### Requirement: SCUM local debug run distribution proof
+The local debug smoke fixture SHALL register the first-party SCUM plugin with enough safe platform metadata for SCUM run distribution APIs to be exercised.
+
+#### Scenario: SCUM run generation is available
+- **WHEN** local debug smoke registers `game.scum` and creates `scum-alpha`
+- **THEN** `GET /api/v1/server-instances/scum-alpha/runtime/actions` MUST report `generate-run` as available
+
+#### Scenario: SCUM run package is generated
+- **WHEN** local debug smoke calls `POST /api/v1/server-instances/scum-alpha/run/generate` for Windows AMD64
+- **THEN** the response MUST include an artifact ID and checksum without exposing raw keys, host paths, direct sockets, bearer credentials, or plugin-owned transport details
+
+#### Scenario: SCUM run package generation is idempotent after a partial artifact write
+- **WHEN** `POST /api/v1/server-instances/scum-alpha/run/generate` is retried with the same idempotency key after the deterministic artifact already exists but the run distribution row is missing
+- **THEN** the platform MUST reuse the matching artifact, create or return the run distribution, and MUST NOT return `duplicate_resource`
+
+#### Scenario: SCUM run self-update dispatch is idempotent
+- **WHEN** `POST /api/v1/server-instances/scum-alpha/run/update` is retried with the same artifact, checksum, and idempotency key
+- **THEN** the platform MUST return the existing update job and MUST NOT return `duplicate_resource`
@@ -0,0 +1,30 @@
+## 1. Local Debug SCUM Runtime Proof
+
+- [x] 1.1 Preserve SCUM manifest run distribution declarations in local debug registration.
+- [x] 1.2 Add smoke assertions that `scum-alpha` exposes `generate-run` as available.
+- [x] 1.3 Add smoke proof that `scum-alpha` can generate a Windows AMD64 run distribution.
+- [x] 1.4 Recover run generation retries when the deterministic artifact exists before the distribution row.
+- [x] 1.5 Recover repeated run self-update dispatches for the same artifact/checksum/idempotency key.
+
+## 2. Verification
+
+- [x] 2.1 Run `bash -n scripts/local-debug-smoke.sh`.
+- [x] 2.2 Run `scripts/check-structure.sh`.
+- [x] 2.3 Run `openspec validate fix-scum-run-distribution-smoke --strict`.
+- [x] 2.4 Run focused local debug smoke proof for the fixed SCUM run distribution path.
+- [x] 2.5 Run focused backend distribution retry tests.
+- [x] 2.6 Run focused run update idempotency regression tests.
+
+## Evidence
+
+- `bash -n scripts/local-debug-smoke.sh` passed.
+- `scripts/check-structure.sh` passed with `structure check passed`.
+- `openspec validate fix-scum-run-distribution-smoke --strict` passed; OpenSpec telemetry flush reported `ENOTFOUND edge.openspec.dev`, which did not affect validation.
+- Isolated local debug smoke passed with `LOCAL_DEBUG_SELF_START=true LOCAL_DEBUG_PLATFORM_PORT=18283 LOCAL_DEBUG_WEB_PORT=5196 LOCAL_DEBUG_ROOT=/private/tmp/browser-scum-run-distribution-smoke-4 scripts/local-debug-smoke.sh`.
+- Smoke evidence directory: `/private/tmp/browser-scum-run-distribution-smoke-4/smoke`.
+- The passing smoke verified `scum-alpha` exposes `generate-run` as available and generated a Windows AMD64 run package without forbidden local-debug fragments.
+- `go test ./service -run 'TestCoreService(GeneratesRunDistributionWithEncryptedSingletonKey|RunDistributionRetryReusesPartialArtifact|BuildsClientManagerWithDistinctKeyAndAuditsSensitiveOperations)' -count=1` passed from `platform/`.
+- `go test ./api ./service -run 'Test.*(Run|Distribution|Artifact|ClientManager|Runtime)' -count=1` passed from `platform/`.
+- `go test ./service -run 'TestCoreService(RunDistributionRetryReusesPartialArtifact|PushRunUpdateReusesExistingUpdateJob|BuildsClientManagerWithDistinctKeyAndAuditsSensitiveOperations)' -count=1` passed from `platform/`.
+- Rerun `scripts/check-structure.sh` passed with `structure check passed`.
+- Rerun `openspec validate fix-scum-run-distribution-smoke --strict` passed; OpenSpec telemetry flush reported `ENOTFOUND edge.openspec.dev`, which did not affect validation.
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-14
@@ -0,0 +1,18 @@
+## Why
+
+The server management card action menu currently opens inside the card as a large vertical command stack, which obscures operational data and makes the card feel broken. The same card stat tiles render label/value text over busy translucent materials, so placeholder values such as `--` and labels like 玩家, TPS, 延迟, and 任务 lose contrast against uploaded or magical-girl backgrounds.
+
+## What Changes
+
+- Replace the in-card runtime action stack with a compact anchored overlay that does not resize or reflow server cards.
+- Keep runtime actions platform-mediated and unchanged while closing the overlay on outside click, Escape, and action selection.
+- After an operator selects a runtime action, show a modal task flow with stage progress for code pull, environment install/check, dependency download, compile/build, packaging, queued jobs, and final success/failure.
+- Increase server card stat readability with stronger token-driven material, label contrast, value contrast, and text shadow that works across black mecha, magical-girl, and uploaded backgrounds.
+- Remove misleading whole-card pointer affordance so only actual controls look clickable.
+
+## Impact
+
+- Affected root: `platform_web/`.
+- Expected files: `platform_web/pages/ServersPage.tsx`, `platform_web/pages/ServerDetailPage.tsx`, `platform_web/components/RuntimeTaskProgress.tsx`, `platform_web/theme/base.css`, and focused rendering/style contract tests if useful.
+- No platform, run, plugin, lifecycle, authorization, credential, or API behavior changes.
+- Verification: focused frontend tests/typecheck, `scripts/check-structure.sh`, `openspec validate fix-server-card-action-menu --strict`, and browser walkthrough of 服务器管理.
@@ -0,0 +1,47 @@
+## ADDED Requirements
+
+### Requirement: Server cards use compact runtime action overlays
+
+The platform_web server management page SHALL expose server-card runtime actions through a compact anchored overlay that does not resize, stretch, or reflow the server card.
+
+#### Scenario: Operator opens runtime actions from a server card
+
+- **WHEN** an operator selects the 运行操作 trigger on a server card
+- **THEN** runtime actions MUST appear in a compact overlay anchored near the trigger instead of as a tall in-card vertical command stack
+- **AND** the server card layout, neighboring cards, metrics, progress bars, title, and status badge MUST remain structurally stable
+
+#### Scenario: Operator dismisses runtime actions
+
+- **WHEN** the runtime action overlay is open
+- **THEN** outside click, Escape, and selecting an action MUST dismiss the overlay
+- **AND** the action dispatch MUST continue to use the existing platform-mediated runtime APIs
+
+### Requirement: Runtime actions show task progress dialogs
+
+The platform_web server management and server detail runtime action surfaces SHALL show a modal task flow after an operator selects a runtime action so the operator can see meaningful progress instead of a silent click-and-finish interaction.
+
+#### Scenario: Operator generates a run package
+
+- **WHEN** an operator selects 生成 run for a server
+- **THEN** platform_web MUST open a modal task dialog that shows stage progress for code pull, environment install/check, dependency download, compile/build, package finalization, and terminal success or failure
+- **AND** the dialog MUST include a readable progress meter, current stage, recent task log lines, and final artifact/job summary when the platform API returns
+
+#### Scenario: Operator starts a queued runtime maintenance action
+
+- **WHEN** an operator selects dependency check, dependency install, push update, live logs, or historical logs from the runtime action surfaces
+- **THEN** platform_web MUST show a modal task dialog with action-specific staged progress and final queued job or navigation status
+- **AND** the dialog MUST keep sensitive runtime credentials, raw host paths, direct sockets, and secret material hidden
+
+### Requirement: Server card metrics remain readable over themed backgrounds
+
+Server card metric tiles SHALL keep labels and values readable across black mecha, magical-girl, and uploaded-background states.
+
+#### Scenario: Metrics are unavailable or pending
+
+- **WHEN** 玩家, TPS, 延迟, or 任务 values render as pending or unavailable placeholders such as `…` or `--`
+- **THEN** both the label and value text MUST remain legible over the card background and selected workspace background
+
+#### Scenario: Custom background is active
+
+- **WHEN** an uploaded background is active behind server cards
+- **THEN** metric tiles MUST use stronger surface material, borders, and text contrast so operational data is not visually swallowed by the background image
@@ -0,0 +1,31 @@
+## 1. Server Card Interaction Fix
+
+- [x] 1.1 Replace the `<details>` runtime action stack with a compact overlay that is anchored to the trigger and does not reflow the card.
+- [x] 1.2 Close the overlay on outside click, Escape, and action selection.
+- [x] 1.3 Keep runtime action dispatch semantics unchanged.
+- [x] 1.4 Show a runtime task progress dialog after action selection with staged progress, logs, and terminal success/failure state.
+- [x] 1.5 Reuse the same progress dialog from server detail runtime distribution actions.
+
+## 2. Server Card Readability Fix
+
+- [x] 2.1 Strengthen `.server-card-stat` label/value contrast for 玩家, TPS, 延迟, 任务, and placeholder values.
+- [x] 2.2 Preserve the shared black-mecha / magical-girl console visual system and uploaded-background readability.
+- [x] 2.3 Remove misleading whole-card click affordance while keeping explicit detail/menu controls.
+
+## 3. Verification
+
+- [x] 3.1 Run focused frontend tests and typecheck.
+- [x] 3.2 Run `scripts/check-structure.sh`.
+- [x] 3.3 Run `openspec validate fix-server-card-action-menu --strict`.
+- [ ] 3.4 Browser-walkthrough 服务器管理 and verify the menu is compact, card stats are readable, action selection opens the progress dialog, and no metrics/progress/status are covered.
+
+## Evidence
+
+- `npm run typecheck` passed.
+- `npm test -- ConsolePages.test.tsx ServerDetailPage.test.tsx base-css.test.js` passed with 22 tests.
+- `npm test` passed with 68 tests.
+- `npm run build` passed.
+- `go test ./api ./service -run 'Test.*(Run|Distribution|Artifact|ClientManager|Runtime)' -count=1` passed from `platform/`, proving backend run distribution, artifact download, update, and client-manager paths are implemented.
+- `scripts/check-structure.sh` passed with `structure check passed`.
+- `openspec validate fix-server-card-action-menu --strict` passed. OpenSpec telemetry flush failed with `ENOTFOUND edge.openspec.dev`, which did not affect validation.
+- Browser walkthrough is still pending because the Browser plugin reported no available browser backends (`agent.browsers.list()` returned `[]`).
@@ -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`.