92 lines
4.3 KiB
Markdown
92 lines
4.3 KiB
Markdown
# 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.
|