browser/AGENTS.md

AGENTS.md

This file applies to the entire repository.

Scope

This repository is a game server management platform. Do not add billing, cloud host sales, agent-provider/cloud-provider workflows, or unrelated SaaS marketplace features unless a future OpenSpec change explicitly requires them.

The platform's required first-party areas are 首页、服务器管理、插件市场、用户管理、AI 提供商管理.

The platform_web visual direction is a unified magical-girl crystal-moonlight game operations console. Preserve the style rules in platform_web/AGENTS.md and platform_web/theme/README.md; do not replace it with generic opaque SaaS cards or unrelated visual systems without a future OpenSpec change. Global magical ultimate effects belong in platform_web/components/MagicalParticleLayer.tsx, not in page-local fixed decoration spans or one-off backdrop CSS.

Frontend Design and Browser Tools

For frontend work, agents are allowed and encouraged to use @浏览器 to automatically open local frontend pages, inspect UI behavior, debug visual issues, and perform browser walkthrough verification.

For frontend design work, agents are allowed and encouraged to use $design-taste-frontend as a design review and implementation aid. Apply it in support of this repository's existing platform_web visual direction and local theme rules; it must not override the magical-girl crystal-moonlight game operations console style without a future OpenSpec change.

Project Roots

• platform/ contains backend platform code.
• run/ contains the machine-side executor.
• platform_web/ contains the management frontend.
• plugins/ contains game management plugins and plugin SDK/examples.

Do not place implementation code outside the matching root. Shared contracts must be generated or copied through explicit contract packages, not imported by reaching across ownership boundaries casually.

OpenSpec Rules

• Every non-trivial change must start with an OpenSpec change under openspec/changes/.
• Update proposal/design/specs/tasks before implementation when behavior, architecture, or validation rules change.
• Do not mark tasks complete until their verification evidence exists.
• Run openspec validate <change> --strict before completion.

Structure Rules

Backend roots must keep these concerns in fixed directories:

• API route declarations and handlers.
• Request/response DTOs.
• Domain types.
• Database models.
• Repository interfaces and implementations.
• Service interfaces and implementations.
• Protocol contracts.
• Validation rules.
• Shared utilities.

Frontend and plugin page roots must keep these concerns in fixed directories:

• API clients and API types.
• Route definitions.
• Page/view contracts.
• Component contracts.
• Schemas and validators.
• Bridge/SDK types.
• Shared utilities.

Do not define business structs inside functions. Do not define request/response structs inside handlers. Do not define database models inside migrations. Do not hide shared frontend types inside page components.

Run and Channel Rules

Run must not expose host paths, raw credentials, or direct sockets to plugins or platform_web.

Run-platform communication must remain channelized:

• Control is lightweight and high priority.
• Jobs carry lifecycle and bounded operations.
• Logs use durable batch ingest with local spool and sequence acknowledgement.
• Artifacts use chunked and resumable transfer with lower priority than logs/control.
• Optional game client bridge is separate from run lifecycle and log ingest.

Large file transfer must not block control heartbeat, job ack/result, or log upload.

AI Provider Rules

AI provider keys and base URLs belong to platform/. Plugins may request AI assistance only through platform-mediated capabilities. Plugin page must never receive raw AI keys.

AI-suggested config changes must produce a reviewable diff or recommendation before platform dispatches a run-side write job.

Verification Rules

Run this before completion:

scripts/check-structure.sh

If you add or change a structural rule, update scripts/check-structure.sh in the same change.

If work touches frontend pages, use a browser walkthrough before claiming the UI is accepted.