103 lines
5.5 KiB
Markdown
103 lines
5.5 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.
|
|
|
|
## CSS Authoring Rules
|
|
|
|
Any task that touches CSS must keep CSS declarations compressed and compact. Do not expand a single selector's style block across many lines when it can be written as a concise one-line rule.
|
|
|
|
## 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.
|
|
|
|
## Task Creation Rules
|
|
|
|
When creating a task, include the following prompt boundaries before implementation starts:
|
|
|
|
- Positive prompt (正向提示词): clearly state the intended outcome, accepted success criteria, and the first-party product area the work supports.
|
|
- Directional prompt (方向提示词): state the expected implementation direction, affected project root, relevant existing patterns to preserve, and verification command or evidence expected.
|
|
- Boundary prompt (任务边界): explicitly list out-of-scope areas, forbidden product expansions, and files or roots that must not be touched unless the task explicitly requires them.
|
|
|
|
## Git Completion Rules
|
|
|
|
For every substantial session task that modifies repository files, automatically stage only the files changed for that task, create a concise git commit after verification succeeds, and push the current branch to its configured git remote before sending the final response.
|
|
|
|
Do not include unrelated pre-existing worktree changes in the commit. If commit or push is blocked by missing credentials, a missing remote, conflicts, or a failing required verification step, report the blocker clearly instead of broadening the commit scope.
|
|
|
|
## 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.
|