browser/AGENTS.md

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 an explicit future product decision requires them.

The platform's required first-party areas are 首页、服务器管理、插件市场、用户管理、AI 提供商管理.

The platform_web visual direction is a unified themed game operations console: the default first-party theme is black mecha, and the selectable alternate first-party theme is magical-girl crystal-moonlight. 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 an explicit future product decision. Global theme-aware ultimate effects belong in platform_web/components/MagicalParticleLayer.tsx, not in page-local fixed decoration spans or one-off backdrop CSS.

Pre-1.0 Product Completion Rules

Until the primary first-party workflows are implemented end-to-end and the product is ready for a 1.0 milestone, do not add audit-event systems, audit logs, audit-gated behavior, capability allowlists, controlled-action declarations, or similar feature restrictions. Incomplete functionality must not be wrapped in placeholder governance such as a declared-but-unimplemented controlled action like announcement.send.

Before 1.0, prioritize making the actual user-facing flows work fully. Remove or avoid audit/restriction scaffolding when it blocks, distracts from, or outpaces the core implementation. Reintroduce audit, compliance, or restrictive governance only after an explicit future product decision for a completed flow.

Until the primary flows are running end-to-end, do not block implementation behind restrictive policy scaffolding, capability allowlists, delivery acknowledgements, audit gates, or placeholder governance. The governing rule is: make the first-party feature work in the product first, then harden it later only when explicitly requested.

Project Roots

• platform/ contains backend platform code.
• platform_web/ contains the management frontend.
• plugins/ contains game management plugins and plugin SDK/examples.

Local Development

• scum.npc0.com is NAT-mapped to the local frontend at http://127.0.0.1:5173/.
• GPT must ignore the .local-debug/ directory when searching, inspecting, or modifying repository files.

Server Management MCP Notes

• For remote server work, use the server-management MCP path, not raw SSH. Start with list_devices, then test_connection, then ssh_exec; the configured 枣庄 device is named 枣庄服务器 with id FyBDIohqPhRx7Cia.
• If native MCP tool wrappers return unsupported call, do not keep retrying the same wrapper. Read the server-management plugin MCP config and call the local MCP JSON-RPC gateway (initialize, tools/list, tools/call) from a small Node script; never print or commit MCP headers, tokens, host credentials, or raw .mcp.json contents.
• If local access to the MCP gateway fails with EPERM on 127.0.0.1, request sandbox escalation for that MCP gateway call instead of falling back to raw SSH.
• On Windows targets, assume ssh_exec may run under cmd; for PowerShell diagnostics, send powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass -EncodedCommand <utf16le-base64> to avoid quoting/glob problems.
• For SCUM current-service discovery, run bounded read-only scripts on 枣庄服务器 itself and return only redacted aggregates/fingerprints. Do not download or parse SCUM.db on the platform/plugin/browser side; product evidence must flow through Platform durable jobs and Run typed/redacted envelopes.

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.

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

All repository modifications must happen on main unless the user explicitly asks for another branch in the current task. Do not create, switch to, or push codex/* or other task branches by default. If the working tree is not on main, switch back to main before editing; if local changes block the switch, stop and report the blocker instead of creating a new branch.

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.

Platform, plugin, and run lifecycle ownership must stay separated. Run is the machine-side state machine for execution; Platform records desired lifecycle intent, registration/auth, generated package inputs, and persisted lifecycle projections from Run-reported facts, not observed process truth:

• Platform owns server instances, plugin manifest validation, platform-side distribution builds, generated Run package inputs, run registration binding, authorization, persisted lifecycle projections, and live transport relay between Run, plugins, and platform_web.
• Plugins own game-specific lifecycle declarations: init/install/update/pre-start checks, dependency probes/install plans, start arguments, stop logic, status/readiness probes, executable paths, Steam app IDs, game-specific dependency commands, game-log storage, game-log analysis, and console-page log stream fan-out to the frontend.
• Run owns generic machine lifecycle execution and the observed runtime/process state it supervises: local bootstrap from generated package plans, scoped file operations, bounded process execution/supervision, current process output push, artifacts, and channel transport. Run must behave as a state machine, not as a durable log database or log-delivery authority.

Observed machine/runtime status must flow from run reports, heartbeats, supervised process facts, and job/control events. Platform must not treat stale persisted server state, such as running, as authoritative when evaluating the current machine process state.

Do not hardcode game-specific deployment behavior in run or platform services. Values such as SCUMServer.exe, Steam app 3792580, steamcmd +app_update, SCUM install directories, -port, -MaxPlayers, or -log belong in the SCUM plugin's manifests, action specs, templates, or scripts.

When a game needs "install if missing, update if present, then start" behavior, implement it as plugin-owned lifecycle actions and package those declarations into the generated Run autonomous lifecycle plan. Run executes the plan through generic capabilities; neither Platform nor Run should special-case a game by name to perform those steps.

Do not add extra platform/frontend lifecycle states just to represent game-specific setup checks. A plugin-owned start action should verify its declared files and dependencies, create missing directories, install or update missing server bits, then start the service through the same plugin-declared lifecycle script. Run should only execute that declared script through generic supervision, hide the started process window where the operating system supports it, and push the current supervised process output through the declared stdout/stderr live log relay without caching or delivery acknowledgement.

Realtime log collection must be plugin-declared and plugin-configured. Run only pushes current log/output events that it is observing now; it must not care whether the server side has accepted them, must not maintain durable local log caches, and must not block lifecycle/control/job progress on log delivery. Platform only forwards live log traffic and should not store, analyze, acknowledge, sequence-gate, or own game-log history. The SCUM plugin owns SCUM log storage, analysis, and forwarding live console streams to platform_web when the operator opens the console page.

Run-platform communication must remain channelized, but logs are best-effort live traffic rather than durable platform-owned delivery:

• Control is lightweight and high priority.
• Jobs carry lifecycle and bounded operations.
• Logs are current best-effort push/relay only: no Run durable spool, no Run resend backlog, no platform sequence acknowledgement dependency, and no platform-owned log persistence. If a game needs stored logs or analysis, implement it in that game plugin.
• Artifacts use chunked and resumable transfer with lower priority than logs/control.
• Optional game client bridge is separate from run lifecycle and live log relay.

Large file transfer must not block control heartbeat, job ack/result, or live log relay.

Distribution Build Ownership Rules

Distribution building is a platform-side responsibility. The platform must be able to build a run package for any server instance without depending on a privileged worker run endpoint being registered and online. Do not route distribution.build execution through machine-side run endpoints, and do not derive build availability from a run endpoint advertising that capability.

Platform-side builds must execute in a platform-owned Docker builder using a pinned image, with build workspaces isolated per plugin and per job. Builder readiness is a platform-level probe; when it is unavailable, the reported reason must name the platform builder rather than a run endpoint capability.

A generated run carries credentials scoped to one server instance and must never hold distribution-build authority. This restriction is a security boundary, not a fallback path: it must not be relaxed to unblock building. Fix the build path instead.

Component auth keys must stay inside the platform for builder-executed builds. Do not return plaintext auth keys to machine-side run endpoints for distribution builds.

Local Run Distribution Testing

For local testing, when a generated run.exe must be made available to a remote server, start a temporary file server from the build output directory with python3 -m http.server 8000. Download the artifact through https://bt.npc0.com/ followed by its relative file path, then download that file again on the machine where run will execute. This is a test-only distribution path; do not treat the temporary HTTP server or tunnel as a production artifact-delivery service.

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:

scripts/check-structure.sh

If you add or change a structural rule, update scripts/check-structure.sh in the same change.