feat: 完整游戏运维功能

2026-07-18 09:04:01 +08:00
parent f3b14b7945
commit 48b8ad8d6c
187 changed files with 16607 additions and 1140 deletions
@@ -0,0 +1,68 @@
+## ADDED Requirements
+
+### Requirement: Lifecycle execution uses declared typed actions
+Platform and Run SHALL execute local lifecycle jobs only from the server's selected plugin runtime profile and a bounded typed action declaration whose action matches the requested capability. Run MUST reject arbitrary shell, unrestricted PATH execution, absolute executables, undeclared environment fields, and unsafe argument content.
+
+#### Scenario: Declared start action executes
+- **WHEN** an authorized start Job carries the selected profile scope and its declared relative action ref
+- **THEN** Run validates the typed start declaration and starts only the workspace-contained executable with the declared argument vector
+
+#### Scenario: Shell or mismatched action is rejected
+- **WHEN** an action declaration contains shell execution, an unsafe executable, or an action different from the Job capability
+- **THEN** Run fails the Job without creating a supervised process
+
+### Requirement: Process start and stop are real and idempotent
+Run SHALL supervise at most one matching game process per server/profile scope and SHALL make repeated start and stop operations converge without creating duplicate processes or failing solely because the desired state already exists.
+
+#### Scenario: Start already-running process
+- **WHEN** a start Job targets a scope whose matching supervised process is alive
+- **THEN** Run returns a successful typed `running` result and does not spawn another process
+
+#### Scenario: Stop running process
+- **WHEN** a stop Job targets a live supervised process
+- **THEN** Run requests bounded graceful termination, escalates only within the declared policy, records the exit, and returns a safe `stopped` result
+
+#### Scenario: Stop already-stopped process
+- **WHEN** a stop Job targets a scope with no live supervised process
+- **THEN** Run returns an idempotent successful `stopped` result without exposing process identifiers
+
+### Requirement: Process state survives Run restart reconciliation
+Run SHALL persist private controlled process identity/state atomically with owner-only permissions and SHALL reconcile every record against OS liveness before accepting new lifecycle work after startup or session rotation.
+
+#### Scenario: Live process survives Run restart
+- **WHEN** Run restarts while a recorded supervised process remains alive
+- **THEN** startup reconciliation retains the logical process as `running` and a later status/start operation observes the same process rather than spawning a duplicate
+
+#### Scenario: Process exited while Run was offline
+- **WHEN** a recorded process is no longer alive during startup reconciliation
+- **THEN** Run records a safe exited state and does not treat the stale PID as running
+
+### Requirement: Unexpected exits and status queries are typed
+Run SHALL observe exits of processes it starts and SHALL return bounded typed state, exit classification, timestamps, and audit summary for status Jobs without returning PID, host path, command bytes, environment credentials, sockets, sessions, leases, or hashes.
+
+#### Scenario: Managed process exits unexpectedly
+- **WHEN** a supervised process exits without a completed stop operation
+- **THEN** Run records an unexpected-exit classification and a subsequent status result reports `exited` with bounded safe evidence
+
+#### Scenario: User reads process result
+- **WHEN** an authorized owner or administrator reads the completed lifecycle/status Job
+- **THEN** Platform returns safe process state and exit classification and omits all private machine identity and fencing fields
+
+### Requirement: Process operations honor cancellation and attempt fencing
+Run SHALL bind process mutations to the current reconciled Job attempt and Platform SHALL apply typed terminal results only after endpoint, session generation, attempt, lease, deadline, cancellation, and signature checks succeed.
+
+#### Scenario: Start is cancelled before commit
+- **WHEN** the current start attempt is cancelled or times out before Run commits its process record
+- **THEN** Run terminates any child created by that attempt and returns a cancelled result
+
+#### Scenario: Stale attempt reports process result
+- **WHEN** an older attempt or stale session submits a process result after retry/reconciliation
+- **THEN** Platform rejects it and does not change the server process projection
+
+### Requirement: Process traffic remains channel-isolated
+Process execution, monitoring, and result reporting SHALL use the existing Job channel and MUST NOT block control heartbeat or Job acknowledgement/result traffic when log or artifact work is blocked.
+
+#### Scenario: Artifact or log request blocks during process operation
+- **WHEN** a log upload or artifact transfer remains blocked while a process Job completes
+- **THEN** control heartbeat and the process Job acknowledgement/result continue through their independent paths
+
@@ -0,0 +1,104 @@
+## ADDED Requirements
+
+### Requirement: Platform persists approved bounded execution input
+Platform SHALL authorize config/file operations against server ownership, plugin permissions, endpoint ownership, selected runtime binding, declared logical target, and scoped input/artifact reference before creating a Job. Approved bounded bytes, workspace profile, expected version/checksum, and read limit SHALL persist with the Job and SHALL remain private from user Job DTOs.
+
+#### Scenario: Approved config survives Platform restart
+- **WHEN** a reviewed config write is queued and Platform restarts before Run claims it
+- **THEN** the same approved content, logical ref, expected version/checksum, and workspace scope remain available to the fenced Run assignment
+
+#### Scenario: Cross-owner or wrong-endpoint dispatch is attempted
+- **WHEN** a caller lacks server authority or a Job/ref belongs to another server or endpoint
+- **THEN** Platform rejects the request without persisting or dispatching execution input
+
+### Requirement: Workspace resolution prevents boundary escape
+Run SHALL map the Platform-approved server ID and profile key into a private workspace and SHALL reject absolute paths, traversal, backslashes, symlinked components, symlink targets, reserved state/action targets, non-directory parents, device files, FIFOs, sockets, and any path outside the selected scope.
+
+#### Scenario: Traversal or absolute target is submitted
+- **WHEN** a config/file Job contains a traversal, absolute, or otherwise invalid logical target
+- **THEN** Platform or Run rejects it before filesystem access
+
+#### Scenario: Symlink escapes workspace
+- **WHEN** any parent or final target is a symlink that resolves inside or outside the workspace
+- **THEN** Run rejects the operation and leaves the referenced file unchanged
+
+#### Scenario: Device or special file is targeted
+- **WHEN** a read or write resolves to a device, FIFO, socket, or other non-regular file
+- **THEN** Run rejects the operation without opening the special file
+
+### Requirement: Config and file writes are atomic compare-and-swap operations
+Run SHALL enforce bounded input, compare the current controlled version/checksum to the expected values, write an owner-only temporary regular file in the verified target directory, fsync and atomically rename it, and persist updated version/checksum metadata only after success.
+
+#### Scenario: Atomic write succeeds
+- **WHEN** expected version/checksum match and the approved input is valid
+- **THEN** readers observe either the complete old content or complete new content and Run returns the incremented version, checksum, size, and safe audit summary
+
+#### Scenario: Expected version conflicts
+- **WHEN** the current controlled version differs from `expectedVersion`
+- **THEN** Run returns a typed conflict and does not replace the file or metadata
+
+#### Scenario: Expected checksum conflicts
+- **WHEN** the current file checksum differs from `expectedChecksum`
+- **THEN** Run returns a typed conflict and leaves content/version unchanged
+
+#### Scenario: Write is cancelled before rename
+- **WHEN** cancellation or attempt invalidation is observed before atomic commit
+- **THEN** Run removes the temporary file and leaves the prior target/version unchanged
+
+### Requirement: Reads are bounded and typed
+Run SHALL read only regular contained files, enforce the assignment's maximum before and during I/O, compute SHA-256, and return a typed result with private bounded content plus safe version/checksum/size/audit metadata.
+
+#### Scenario: Bounded read succeeds
+- **WHEN** a contained regular file is no larger than the approved limit
+- **THEN** Run returns its exact bounded content privately and reports matching checksum, size, and controlled version
+
+#### Scenario: File exceeds read limit
+- **WHEN** file metadata or streamed bytes exceed the approved limit
+- **THEN** Run fails with a bounded size error and does not return partial content
+
+### Requirement: Terminal config results update durable Platform state
+Platform SHALL validate typed result/capability consistency after existing fencing, persist the safe result, and only then project a successful config write into the server's durable config content, checksum, version, and update time. Failed, cancelled, stale, or conflicting results MUST NOT mutate config state.
+
+#### Scenario: Config write result is accepted
+- **WHEN** the current fenced attempt returns a successful config result matching its approved content checksum and next version
+- **THEN** Platform updates the server config and authorized config reads return the new content/version/checksum
+
+#### Scenario: Stale config result arrives
+- **WHEN** a stale attempt, invalid signature/session, wrong endpoint, or cancelled attempt returns a config result
+- **THEN** Platform rejects it and preserves the prior config content/version/checksum
+
+### Requirement: AI suggestions remain review-before-write
+AI-assisted configuration SHALL continue to produce a reviewable diff and MUST NOT dispatch a config write until an authorized user approves that diff with the current expected version/checksum.
+
+#### Scenario: AI suggestion is generated
+- **WHEN** AI proposes configuration content
+- **THEN** Platform and platform_web show a reviewable diff without creating a Run write Job
+
+#### Scenario: User approves suggestion
+- **WHEN** an authorized user approves the current diff
+- **THEN** Platform persists the approved input and dispatches it through the normal fenced config Job path
+
+### Requirement: User projections remain credential-free
+Platform and platform_web SHALL expose only authorized process/config/file state, version, checksum, size, conflict/error classification, and bounded audit summary, and MUST NOT expose approved private Job content, raw AI keys, Run tokens, leases/hashes, secret refs, host paths, PID, sockets, or credentials.
+
+#### Scenario: Authorized result is rendered
+- **WHEN** an authorized user views config or operation history
+- **THEN** platform_web renders safe typed metadata using existing theme surfaces and existing 401/403 handling
+
+#### Scenario: Plugin requests a file operation
+- **WHEN** a plugin page submits a declared scoped file request
+- **THEN** it receives only the Platform-owned Job/safe result projection and no direct Run or workspace information
+
+### Requirement: Config/file traffic remains channel-isolated
+Config/file execution SHALL use bounded Job payloads and MUST NOT carry log batches or artifact chunks. Slow config/file I/O MUST NOT block control heartbeat, Job acknowledgement/result, or the independent log/artifact routes.
+
+#### Scenario: File execution blocks
+- **WHEN** a file executor is deliberately blocked
+- **THEN** control heartbeat and unrelated Job acknowledgement/result requests continue within their own deadlines
+
+### Requirement: Roadmap boundary remains explicit
+Completion of this capability MUST NOT be reported as readiness for durable logs/artifacts/metrics/backups, remote adapters, dependency installation, Run self-update, client-manager lifecycle, production scaling/alerts/plugin lifecycle, or real AI-provider integration.
+
+#### Scenario: Change is handed off
+- **WHEN** implementation and verification complete
+- **THEN** the handoff identifies those later-route capabilities as not implemented by this change