85 lines
4.1 KiB
Markdown
85 lines
4.1 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.
|
|
|
|
## Project Roots
|
|
|
|
- `platform/` contains backend platform code.
|
|
- `platform_web/` contains the management frontend.
|
|
- `plugins/` contains game management plugins and plugin SDK/examples.
|
|
|
|
The machine-side run executor lives in the independent repository `git@git.npc0.com:admin343/run.git`; do not re-add a `run/` source tree to this repository.
|
|
|
|
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
|
|
|
|
- Use judgment before creating an OpenSpec change. Create one when the work changes behavior, architecture, public/API contracts, validation rules, persistence, security boundaries, cross-root workflows, or the required product/visual direction.
|
|
- OpenSpec is not required for small scoped bug fixes, copy/documentation updates, tests, local refactors without behavior change, or styling/label fixes that preserve the existing visual system. For those, reason through the steps, make the edit directly, and report the verification performed.
|
|
- If an OpenSpec change is created, update proposal/design/specs/tasks before implementation when behavior, architecture, or validation rules change.
|
|
- If an OpenSpec change is created, do not mark its tasks complete until verification evidence exists, and 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
|
|
|
|
The external run executor 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.
|