first commit

platform_web/AGENTS.md

@@ -0,0 +1,40 @@
+# AGENTS.md for platform_web
+
+This file applies to `platform_web/`.
+
+## Frontend Scope
+
+Build the actual management console, not a marketing site. Required first-party areas are 首页、服务器管理、插件市场、用户管理、AI 提供商管理.
+
+## Structure Rules
+
+Do not define API clients, shared DTOs, route definitions, schemas, or bridge contracts inside page components. Put them in dedicated directories.
+
+## Interaction Rules
+
+Do not use fixed left-list/right-detail master-detail layouts for server or plugin details. Use detail routes, modals, or drawers.
+
+## Visual Style Rules
+
+The platform_web visual system is a game operations console, not a generic SaaS dashboard. The default theme is black mecha; the selectable alternate theme is magical-girl. Future UI work must preserve the current style contract:
+
+- Use the shared theme tokens in `theme/tokens.ts` and shared styles in `theme/base.css`; do not add page-local opaque card systems, one-off dark dashboards, or unrelated visual languages.
+- Keep major surfaces translucent enough for the selected desktop/background to remain visible: side navigation, account/profile controls, metric cards, console panels, server cards, server detail headers, tables, drawers, dialogs, plugin groups, and operation history.
+- Preserve theme-specific materials: black mecha uses dark cockpit panels, angular clipped frames, cyan scanner lines, and amber energy accents; magical-girl uses pink jelly glass, gold star frames, ribbon glow, and visible magic-circle motifs.
+- Theme changes must be isolated and complete. Switching from magical-girl to black mecha must clear previous magical variables and update root theme marker, sidebar subtitle, active navigation frame, swatch strip, and shared surface accessories together.
+- Do not double-frame nested content. A `.state-view` inside an already framed shared parent such as a console panel, card, table wrapper, plugin group, or operation item is content only; the parent owns the visible border and accessory layer.
+- Keep the primary menu as a compact admin sidebar with two states: expanded text menu and collapsed icon rail. Do not reintroduce the single-column / double-column menu toggle. The same route order should render as a restrained dark mecha operations rail in black mecha and as a semi-transparent pink frosted-glass rail with star-framed active states in magical-girl.
+- Use `components/MagicalParticleLayer.tsx` for full-workspace theme-aware ultimate effects. Each theme should have a distinct low-cost “大招” scene, not a dense field of tiny rotating particles. Do not reintroduce hardcoded fixed decorative DOM/CSS elements such as page-local sparkles, hearts, moons, snowflakes, or sigils.
+- Built-in backgrounds must stay original CSS/generated motif desktops. Do not bundle recognizable third-party character art. User-uploaded backgrounds are allowed and must render behind readable contrast overlays.
+- Uploaded backgrounds take precedence over built-in desktop presets; the selected preset remains the fallback after the upload is removed.
+- Non-dangerous commands may use theme-appropriate lucide icons. Destructive, failed, warning, and safety-critical operations must retain familiar warning/status iconography and text.
+- Status, errors, operation results, logs, configuration diffs, and LLM review output must remain readable, traceable, and not color-only.
+- Cards and framed repeated items should keep 8px-or-less radii unless a native control shape requires a pill or circle.
+
+See `theme/README.md` before changing theme tokens, shared CSS surfaces, page chrome, account/theme settings, or background behavior.
+
+## Verification Rules
+
+If a change touches UI pages or interactions, verify the key workflow in a browser before claiming acceptance.
+
+For theme, frame, or uploaded-background changes, the browser walkthrough must include both directions of theme switching and must explicitly check that nested empty/loading/error states do not render a second border or accessory.