first commit
This commit is contained in:
npc0-hue
@@ -0,0 +1,91 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user