# 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 [@浏览器](plugin://browser@openai-bundled) 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](/Users/tasia/.agents/skills/design-taste-frontend/SKILL.md) 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:

```bash
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.