From bca4f935ba5c08e12973f19eb9213c596013ad9e Mon Sep 17 00:00:00 2001 From: npc0-hue Date: Fri, 31 Jul 2026 17:41:54 +0800 Subject: [PATCH] Document platform plugin run boundaries --- AGENTS.md | 10 ++++++++++ platform/AGENTS.md | 6 ++++++ plugins/AGENTS.md | 6 ++++++ 3 files changed, 22 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index f191cf2..550d718 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -85,6 +85,16 @@ Do not define business structs inside functions. Do not define request/response 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: + +- Platform owns server instances, plugin manifest validation, distribution builds, run registration binding, authorization, and lifecycle job dispatch. +- Plugins own game-specific lifecycle behavior: install, update, pre-start checks, start arguments, stop logic, status probes, executable paths, Steam app IDs, and game-specific dependency commands. +- Run owns generic machine execution only: scoped file operations, bounded process execution/supervision, declared capability enforcement, logs, artifacts, and channel transport. + +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. Platform may package and dispatch those actions, and run may execute them through generic capabilities, but neither platform nor run should special-case a game by name to perform those steps. + Run-platform communication must remain channelized: - Control is lightweight and high priority. diff --git a/platform/AGENTS.md b/platform/AGENTS.md index 37823fc..edb8f2e 100644 --- a/platform/AGENTS.md +++ b/platform/AGENTS.md @@ -24,3 +24,9 @@ Prefer model-first table definitions. Do not define table schemas only inside mi ## Platform Boundaries Plugins and platform_web must never receive run credentials, raw host paths, or AI provider keys. All access must pass through platform authorization and bounded DTOs. + +Platform may read plugin manifests, validate lifecycle/action declarations, package plugin-owned action assets into generated run distributions, and dispatch lifecycle jobs with typed inputs. Platform must not implement game-specific install/update/start behavior itself. + +Do not add platform service code that hardcodes a game's executable path, Steam app ID, SteamCMD command line, process name, default launch flags, or update policy. For SCUM specifically, `SCUMServer.exe`, app `3792580`, `+app_update 3792580 validate`, `-port`, `-MaxPlayers`, and `-log` must come from the SCUM plugin action assets or plugin-declared startup fields. + +If a lifecycle job requires checking whether game files exist, installing missing files, updating existing files, stopping before update, or building the final launch command, dispatch the plugin-owned action and keep platform limited to authorization, input validation, job creation, and result handling. diff --git a/plugins/AGENTS.md b/plugins/AGENTS.md index 4b55105..fcd041a 100644 --- a/plugins/AGENTS.md +++ b/plugins/AGENTS.md @@ -6,6 +6,12 @@ This file applies to `plugins/`. Plugins are game management plugins. Do not model unrelated billing, cloud sales, host provider behavior, or independent plugin backend services here. +Game-specific lifecycle behavior belongs here, not in platform services or the generic run executor. A plugin must own its install, update, pre-start checks, start command construction, stop behavior, status checks, executable paths, dependency commands, default launch flags, and game-specific app IDs. + +When a game needs automatic setup, express it through plugin manifests, action specs, templates, or scripts. For example, the SCUM plugin should own the SteamCMD install/update flow, including stopping the server before update, running `steamcmd +force_install_dir ... +login anonymous +app_update 3792580 validate +quit`, and starting `SCUMServer.exe` with plugin-declared `port` and `MaxPlayers` plus the plugin default `-log`. + +Do not rely on run or platform hardcoding a specific game path, Steam app ID, command line, or startup flag to make a plugin work. If a new capability is needed, declare the generic capability the plugin needs and keep the game-specific policy in the plugin. + ## Structure Rules Manifests, schemas, SDK contracts, example plugins, and test fixtures must live in dedicated directories. Do not bury action schemas or bridge types inside UI page code.