first commit
This commit is contained in:
npc0-hue
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-07-02
|
||||
@@ -0,0 +1,111 @@
|
||||
## Context
|
||||
|
||||
The new project starts in `/Users/tasia/Desktop/code/browser` and intentionally splits the system into four subprojects:
|
||||
|
||||
- `platform/`: backend control plane for users, game management plugins, server instances, AI providers, jobs, artifacts, logs, and audit.
|
||||
- `run/`: machine-side executor that performs scoped process, file, log, artifact, and server lifecycle work.
|
||||
- `platform_web/`: management console frontend for 首页、服务器管理、插件市场、用户管理、AI 提供商管理.
|
||||
- `plugins/`: game management plugin workspace where each plugin defines how to create and manage one server type and can create many server instances.
|
||||
|
||||
The previous implementation mixed API DTOs, models, store code, business logic, frontend types, runtime protocols, plugin execution, and generated rules across many directories. This design treats directory ownership and validation as product requirements, not style preferences.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- Make the platform a game server management platform, not a SCUM-only application.
|
||||
- Keep plugin semantics narrow: plugins define server types and server management workflows; they do not own platform transport, AI credentials, or run connections.
|
||||
- Give AI providers a clear role: model endpoint/key/model configuration used through platform-mediated plugin abilities.
|
||||
- Split run-platform communication into control, job, log ingest, artifact, and optional game client bridge channels.
|
||||
- Preserve log continuity when file transfer or plugin file operations are busy.
|
||||
- Create mandatory directories for DTOs, models, schemas, shared utilities, validators, and frontend types.
|
||||
- Add a repository structure checker that future changes must update when rules change.
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- No billing, cloud resource sales, or SaaS marketplace features.
|
||||
- No agent provider or cloud host provider system in this change.
|
||||
- No direct browser-to-run or plugin-to-run connection.
|
||||
- No raw UDP log transport for reliable historical logs.
|
||||
- No implementation of the full backend, frontend, or run binaries in this proposal.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Decision 1: Four subprojects are hard boundaries
|
||||
|
||||
The root project SHALL contain `run/`, `platform/`, `platform_web/`, and `plugins/` only as first-class implementation roots.
|
||||
|
||||
Alternative considered: one monorepo package tree with shared internal directories. Rejected because the old project already demonstrated that blurred roots let API structs, database models, protocol structs, and frontend types drift into business logic.
|
||||
|
||||
### Decision 2: Plugins are game management plugins
|
||||
|
||||
A plugin declares how to create and manage a class of game server. Installing `server.scum` or `server.minecraft` enables users to create multiple server instances from that plugin.
|
||||
|
||||
Alternative considered: treating every game-side mod or feature as a platform plugin. Rejected because it fragments one game into many pseudo-platform units and makes server creation unclear.
|
||||
|
||||
### Decision 3: AI provider management is a platform service
|
||||
|
||||
AI providers store base URL, API key reference, model list, routing mode, timeout, and policy. Plugins call a platform AI invocation API with scoped purpose and inputs; plugins never receive raw keys.
|
||||
|
||||
Alternative considered: plugin-owned AI provider configuration. Rejected because credentials would be duplicated, hard to audit, and unsafe for plugin frontends.
|
||||
|
||||
### Decision 4: Run communication is channelized by workload
|
||||
|
||||
The run executor SHALL use separate logical channels:
|
||||
|
||||
- control: hello, heartbeat, capability, capacity, version.
|
||||
- job: claim, ack, progress, result, cancel, reconcile.
|
||||
- log ingest: compressed batches, sequence acknowledgement, local spool, retry.
|
||||
- artifact: chunk upload/download, checksum, resumable transfer, throttling.
|
||||
- game client bridge: optional game-inside command polling and snapshots when a game needs it.
|
||||
|
||||
Alternative considered: one WebSocket with multiplexed message types. Rejected as the primary architecture because large files, long tasks, and high-volume logs can block each other and make backpressure hard to reason about.
|
||||
|
||||
### Decision 5: Logs are a data pipeline
|
||||
|
||||
Run SHALL collect process output and server log files into a local spool/WAL, upload compressed batches with monotonic sequence IDs, and delete local segments only after platform acknowledgement. Platform SHALL store log metadata separately from log bodies and support pluggable storage backends such as local compressed segments, Loki, ClickHouse, OpenSearch, or Elasticsearch.
|
||||
|
||||
Alternative considered: browser-oriented WebSocket logs from run to platform. Rejected because historical query, GPT analysis, retry, and thousands of server streams require durable ingestion semantics.
|
||||
|
||||
### Decision 6: File transfer is artifact-based
|
||||
|
||||
Plugins and frontend actions SHALL reference `artifactId` or `fileRef`, not host paths or raw run connections. Artifact transfer SHALL be chunked, resumable, checksummed, rate limited, and lower priority than control and log flush.
|
||||
|
||||
Alternative considered: synchronous file content inside job results. Accepted only for bounded small metadata or small text reads; rejected for general files because it can block logs and job status.
|
||||
|
||||
### Decision 7: Definitions live in fixed directories
|
||||
|
||||
Each backend subproject SHALL keep request/response DTOs, database models, domain types, protocol types, validation rules, shared helpers, and API route declarations in dedicated directories. Each frontend or plugin page SHALL keep API clients, page types, route definitions, schemas, bridge types, and shared utilities in dedicated directories.
|
||||
|
||||
Alternative considered: colocating structs and helper functions beside handlers for speed. Rejected because the user explicitly wants structure definitions, common functions, database definitions, and API definitions in predictable locations.
|
||||
|
||||
### Decision 8: Rules are validated by script
|
||||
|
||||
The root `scripts/check-structure.sh` SHALL verify required directories and governance files. Future implementation changes MUST extend the checker when adding new architectural rules.
|
||||
|
||||
Alternative considered: relying on AGENTS.md instructions only. Rejected because instructions alone do not prevent drift.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Risk] Directory rules may feel heavy before code exists -> Mitigation: start with lightweight presence checks and grow semantic checks with implementation.
|
||||
- [Risk] HTTP polling jobs can add latency -> Mitigation: begin with pull/long-poll for NAT reliability, then add HTTP/2 or gRPC streaming only where measured latency needs it.
|
||||
- [Risk] Log storage choice is premature -> Mitigation: define a storage adapter boundary and begin with local compressed segments plus metadata.
|
||||
- [Risk] Plugin flexibility is reduced -> Mitigation: expose platform abilities through a typed bridge and job/artifact APIs instead of direct run access.
|
||||
- [Risk] AI analysis may consume too much log context -> Mitigation: require log window extraction, redaction, summarization, and user confirmation before config writes.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Bootstrap the empty repository with four subproject roots, README files, AGENTS files, OpenSpec proposal artifacts, and the structure checker.
|
||||
2. Implement minimal platform models and route contracts for game management plugins, server instances, AI providers, run sessions, jobs, artifacts, and log streams.
|
||||
3. Implement run control, job claim/result, log spool/ingest, and artifact chunk APIs behind interfaces.
|
||||
4. Implement platform_web pages in the required navigation set and consume only platform APIs.
|
||||
5. Implement one dev game management plugin as the first proof that a plugin can create multiple server instances and use platform AI/file/log abilities.
|
||||
|
||||
Rollback is simple during bootstrap: remove the new change artifacts or directories before implementation starts. After implementation starts, rollback must follow OpenSpec task boundaries.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Which backend database will be used first for platform metadata?
|
||||
- Should log body MVP use local compressed files, ClickHouse, Loki, or OpenSearch first?
|
||||
- Should the initial run job channel be short polling, long polling, or HTTP/2 streaming?
|
||||
- What language/runtime should game management plugin action scripts use first?
|
||||
@@ -0,0 +1,34 @@
|
||||
## Why
|
||||
|
||||
The previous SCUM-specific platform grew into a tightly coupled mix of frontend shell, backend services, run executors, client bridges, plugin runtime, file operations, log streaming, database access, and generated rules. The new project needs a clean game server management platform foundation where each subproject has explicit ownership, fixed definition directories, and verifiable change rules from the first commit.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Create a new four-part project layout: `run/`, `platform/`, `platform_web/`, and `plugins/`.
|
||||
- Define the platform as a game server management system with 首页、服务器管理、插件市场、用户管理、AI 提供商管理.
|
||||
- Treat plugins as game management plugins that define how to create and manage game servers; each installed plugin can create many server instances.
|
||||
- Define AI providers as GPT/OpenAI-compatible/model-provider configuration used by plugins for assisted config reading, config generation, log diagnosis, and server file suggestions.
|
||||
- Separate run-platform-plugin communication into dedicated channels for control, jobs, logs, artifacts/files, and optional game client bridge behavior.
|
||||
- Require logs to be a first-class ingestion pipeline with batching, compression, sequence acknowledgement, local spool, storage adapters, and browser tail as a derived view rather than the primary transport.
|
||||
- Require artifact/file transfer to be chunked, resumable, checksummed, throttled, and isolated from log ingestion and control heartbeats.
|
||||
- Require every subproject to keep API DTOs, database models, domain structs, shared helpers, validation rules, and frontend types in dedicated directories instead of scattering definitions through business logic.
|
||||
- Add repository governance files so future changes update rules and run automated structure checks before being considered complete.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `project-workspace-governance`: Project layout, AGENTS rules, README contracts, and automated structure validation requirements for the four subprojects.
|
||||
- `game-server-platform-core`: Core platform resources for users, game management plugins, server instances, AI providers, jobs, artifacts, logs, and audit.
|
||||
- `run-execution-channel`: The run-side control, job, log ingest, artifact transfer, and optional game client bridge contracts.
|
||||
- `game-plugin-system`: Game management plugin packaging, local development, manifest rules, platform bridge, plugin marketplace, and multi-instance server creation.
|
||||
- `platform-web-console`: The frontend console structure, plugin page bridge rules, page model, API client layout, and design constraints.
|
||||
|
||||
### Modified Capabilities
|
||||
- None. This is a new project with no existing specs.
|
||||
|
||||
## Impact
|
||||
|
||||
- Adds project-level rules and documentation under `/Users/tasia/Desktop/code/browser`.
|
||||
- Establishes OpenSpec artifacts for the initial architecture before implementation begins.
|
||||
- Affects all future implementation in `run`, `platform`, `platform_web`, and `plugins`.
|
||||
- Introduces an initial repository structure verifier that future changes must keep updated as rules evolve.
|
||||
+44
@@ -0,0 +1,44 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Game management plugin manifest defines server creation
|
||||
A game management plugin SHALL provide a manifest that declares plugin identity, supported server type, create form schema, server lifecycle actions, required run capabilities, optional plugin pages, and AI/file/log permissions.
|
||||
|
||||
#### Scenario: Valid plugin installed
|
||||
- **WHEN** a plugin manifest declares a valid server type and required capabilities
|
||||
- **THEN** the platform MUST expose it in the plugin marketplace and allow creating server instances from it
|
||||
|
||||
#### Scenario: Plugin manifest requests unsafe access
|
||||
- **WHEN** a plugin manifest requests direct run credentials, raw host paths, or raw AI provider keys
|
||||
- **THEN** the platform MUST reject or disable that contribution
|
||||
|
||||
### Requirement: Plugins use platform bridge only
|
||||
Plugin page and plugin actions SHALL access platform abilities through a typed bridge or platform API and MUST NOT connect directly to run, log storage, artifact storage internals, or AI provider endpoints.
|
||||
|
||||
#### Scenario: Plugin reads logs
|
||||
- **WHEN** a plugin needs logs for a server instance
|
||||
- **THEN** it MUST query platform log APIs by server instance, stream, time range, cursor, or analysis window
|
||||
|
||||
#### Scenario: Plugin invokes AI
|
||||
- **WHEN** a plugin invokes AI for config or log assistance
|
||||
- **THEN** it MUST send a scoped platform AI request and receive a bounded response that excludes provider secrets
|
||||
|
||||
### Requirement: Local plugin development is first-class
|
||||
The project SHALL support local game management plugin development where a plugin can be registered as a dev plugin, provide UI from a dev server or static directory, and exercise real platform-run job, file, log, and AI flows against a selected test server instance.
|
||||
|
||||
#### Scenario: Developer runs local plugin
|
||||
- **WHEN** a developer starts a local plugin in dev mode
|
||||
- **THEN** platform_web MUST show the plugin as a dev game management plugin without requiring a marketplace publish
|
||||
|
||||
### Requirement: Plugin definitions are organized
|
||||
The `plugins/` workspace SHALL keep manifests, schemas, UI contracts, action definitions, test fixtures, and shared plugin SDK code in predictable directories.
|
||||
|
||||
#### Scenario: Plugin adds action input schema
|
||||
- **WHEN** a plugin adds or changes an action input
|
||||
- **THEN** the schema MUST live in a dedicated schema/contract location and tests MUST cover validation behavior
|
||||
|
||||
### Requirement: Plugin can create many server instances
|
||||
A game management plugin installation SHALL be reusable for multiple server instances with isolated configuration, artifacts, jobs, logs, and permissions per server instance.
|
||||
|
||||
#### Scenario: Two servers from one plugin
|
||||
- **WHEN** a user creates two server instances from the same plugin
|
||||
- **THEN** each instance MUST have separate configuration state, run binding, log streams, and artifact references
|
||||
+48
@@ -0,0 +1,48 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Platform navigation scope
|
||||
The platform SHALL define the primary product surface as 首页、服务器管理、插件市场、用户管理、AI 提供商管理.
|
||||
|
||||
#### Scenario: Navigation is generated
|
||||
- **WHEN** platform_web renders authenticated navigation
|
||||
- **THEN** it MUST expose 首页、服务器管理、插件市场、用户管理、AI 提供商管理 as the primary areas
|
||||
|
||||
### Requirement: Game management plugins create server instances
|
||||
The platform SHALL model game management plugins as definitions for creating and managing game server types, and each installed game management plugin MUST be able to create multiple server instances.
|
||||
|
||||
#### Scenario: Create server from plugin
|
||||
- **WHEN** a user creates a server from an installed game management plugin
|
||||
- **THEN** the platform MUST create a server instance linked to that plugin and a selected run endpoint
|
||||
|
||||
#### Scenario: Multiple instances per plugin
|
||||
- **WHEN** a game management plugin is installed once
|
||||
- **THEN** users MUST be able to create more than one server instance from that plugin without reinstalling the plugin
|
||||
|
||||
### Requirement: AI providers are platform-managed
|
||||
The platform SHALL manage AI provider configuration for OpenAI-compatible, GPT, Claude, local, or relay endpoints, including base URL, key reference, model settings, timeout, and routing metadata.
|
||||
|
||||
#### Scenario: Plugin requests AI assistance
|
||||
- **WHEN** a plugin needs AI assistance for config reading, config generation, or log diagnosis
|
||||
- **THEN** it MUST call a platform AI capability and MUST NOT receive raw provider API keys
|
||||
|
||||
#### Scenario: AI suggests a config change
|
||||
- **WHEN** AI generates a server configuration change
|
||||
- **THEN** the platform MUST present a bounded diff or recommendation before any run-side file write job is dispatched
|
||||
|
||||
### Requirement: Platform data definitions are centralized
|
||||
The platform backend SHALL keep database models, DTOs, domain types, API route declarations, repository contracts, service interfaces, validators, and shared helpers in fixed directories.
|
||||
|
||||
#### Scenario: New API added
|
||||
- **WHEN** platform code adds a new HTTP/API endpoint
|
||||
- **THEN** its request and response DTOs MUST be defined in the platform contract/DTO area and route declarations MUST be discoverable in the API area
|
||||
|
||||
#### Scenario: New database table added
|
||||
- **WHEN** platform code adds a new database table
|
||||
- **THEN** its model MUST be defined in the database model area with field comments and tags before migrations or repositories reference it
|
||||
|
||||
### Requirement: Platform does not expose run internals to plugins
|
||||
The platform SHALL mediate all plugin access to files, jobs, logs, AI providers, and run endpoints.
|
||||
|
||||
#### Scenario: Plugin requests file operation
|
||||
- **WHEN** a plugin requests file access for a server instance
|
||||
- **THEN** the platform MUST authorize the request and dispatch a scoped job or artifact operation instead of exposing host paths or run credentials
|
||||
+36
@@ -0,0 +1,36 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Console exposes required pages
|
||||
The platform web console SHALL provide 首页、服务器管理、插件市场、用户管理、AI 提供商管理 as first-party pages.
|
||||
|
||||
#### Scenario: Authenticated user opens console
|
||||
- **WHEN** an authenticated user opens platform_web
|
||||
- **THEN** the primary navigation MUST include 首页、服务器管理、插件市场、用户管理、AI 提供商管理
|
||||
|
||||
### Requirement: Server management uses routed or modal details
|
||||
Server management SHALL avoid fixed left-list/right-detail master-detail layouts and MUST use routed details, modal details, or drawers for server detail flows.
|
||||
|
||||
#### Scenario: User opens a server
|
||||
- **WHEN** a user selects a server from the server list
|
||||
- **THEN** platform_web MUST navigate to a detail route or open an overlay detail surface rather than permanently occupying a right-side detail pane
|
||||
|
||||
### Requirement: Plugin page is hosted through platform context
|
||||
Plugin page SHALL run inside a platform-controlled host that supplies theme tokens, server instance context, safe API access, AI invocation, log queries, artifact references, and job operations.
|
||||
|
||||
#### Scenario: Plugin page loads
|
||||
- **WHEN** a user opens an authorized plugin page for a server instance
|
||||
- **THEN** the host MUST pass only safe context and MUST not expose platform auth storage, AI keys, run credentials, or host paths
|
||||
|
||||
### Requirement: Frontend definitions are centralized
|
||||
platform_web SHALL keep API clients, route definitions, page contracts, bridge contracts, shared component types, schemas, and validation helpers in dedicated directories.
|
||||
|
||||
#### Scenario: New API call added
|
||||
- **WHEN** a frontend change adds a platform API call
|
||||
- **THEN** the call and related request/response types MUST live in the API/contract area rather than inside a view component
|
||||
|
||||
### Requirement: Logs and files are separate user flows
|
||||
The frontend SHALL treat log history/tail views and file/artifact operations as separate workflows so file operations do not imply log stream interruption.
|
||||
|
||||
#### Scenario: User uploads a file while viewing logs
|
||||
- **WHEN** a user uploads or downloads a server file from a plugin or file page
|
||||
- **THEN** active log history or tail views MUST continue to query or subscribe through the platform log APIs independently
|
||||
+45
@@ -0,0 +1,45 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Four-root project layout
|
||||
The repository SHALL use `run/`, `platform/`, `platform_web/`, and `plugins/` as the only first-class implementation roots for executor, backend, frontend, and game management plugin work.
|
||||
|
||||
#### Scenario: Bootstrap layout exists
|
||||
- **WHEN** a contributor inspects the repository root
|
||||
- **THEN** the root MUST contain `run/`, `platform/`, `platform_web/`, and `plugins/`
|
||||
|
||||
#### Scenario: New implementation is placed under the correct root
|
||||
- **WHEN** a change adds executor, backend, frontend, or game management plugin implementation
|
||||
- **THEN** the files MUST be placed under the matching implementation root
|
||||
|
||||
### Requirement: Governance documentation is mandatory
|
||||
The repository and each first-class implementation root SHALL contain an `AGENTS.md` and `README.md` that describe scope, directory rules, and verification expectations.
|
||||
|
||||
#### Scenario: Root governance files exist
|
||||
- **WHEN** a contributor starts work from the repository root
|
||||
- **THEN** root `AGENTS.md` and `README.md` MUST explain cross-project rules and verification commands
|
||||
|
||||
#### Scenario: Subproject governance files exist
|
||||
- **WHEN** a contributor works inside `run/`, `platform/`, `platform_web/`, or `plugins/`
|
||||
- **THEN** that directory MUST contain local `AGENTS.md` and `README.md` with root-specific rules
|
||||
|
||||
### Requirement: Definition directories are fixed
|
||||
Backend subprojects SHALL keep DTOs, domain structs, database models, API route definitions, validation rules, protocols, and shared helpers in dedicated directories. Frontend and plugin page subprojects SHALL keep API clients, route definitions, page types, schemas, bridge types, and shared utilities in dedicated directories.
|
||||
|
||||
#### Scenario: Backend code adds a request DTO
|
||||
- **WHEN** backend code adds a request or response structure
|
||||
- **THEN** the structure MUST live in a dedicated DTO or contract directory rather than inside a handler function
|
||||
|
||||
#### Scenario: Frontend code adds a shared type
|
||||
- **WHEN** frontend code adds a shared API, route, bridge, or component type
|
||||
- **THEN** the type MUST live in a dedicated type, contract, schema, or API directory rather than inside a page component
|
||||
|
||||
### Requirement: Structure checks gate completion
|
||||
The repository SHALL provide a structure validation command that verifies mandatory roots and governance files, and future changes MUST update that validator when adding new structure rules.
|
||||
|
||||
#### Scenario: Required directory missing
|
||||
- **WHEN** `scripts/check-structure.sh` runs and a required root or governance file is missing
|
||||
- **THEN** the command MUST fail with a clear missing-path message
|
||||
|
||||
#### Scenario: Rule changes with no validator update
|
||||
- **WHEN** a change adds a new mandatory directory or governance rule
|
||||
- **THEN** the change MUST update the structure checker before the task can be marked complete
|
||||
+52
@@ -0,0 +1,52 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Run control channel is lightweight
|
||||
The run executor SHALL use a lightweight control channel for hello, heartbeat, capability reporting, version reporting, and capacity reporting only.
|
||||
|
||||
#### Scenario: Run starts
|
||||
- **WHEN** run starts and reaches the platform
|
||||
- **THEN** it MUST register through hello and report capabilities before accepting jobs
|
||||
|
||||
#### Scenario: File transfer is active
|
||||
- **WHEN** run is uploading or downloading large artifacts
|
||||
- **THEN** control heartbeats MUST remain independent from artifact transfer progress
|
||||
|
||||
### Requirement: Job channel supports lifecycle semantics
|
||||
The run executor SHALL support job claim, ack, progress, result, cancel, and reconcile semantics for server lifecycle, config, database, backup, and plugin-triggered work.
|
||||
|
||||
#### Scenario: Job accepted
|
||||
- **WHEN** run accepts a job
|
||||
- **THEN** it MUST return a structured ack before execution and terminal result after execution
|
||||
|
||||
#### Scenario: Run restarts during job
|
||||
- **WHEN** run restarts or reconnects after accepting a job
|
||||
- **THEN** the platform MUST be able to request reconciliation using job identity or idempotency identity
|
||||
|
||||
### Requirement: Logs use durable ingest
|
||||
Run SHALL collect server logs into a local spool and upload compressed batches with stream identity, monotonic sequence range, checksum, and acknowledgement handling.
|
||||
|
||||
#### Scenario: Platform unavailable
|
||||
- **WHEN** platform log ingest is temporarily unavailable
|
||||
- **THEN** run MUST retain unacknowledged log batches locally and retry without losing sequence continuity
|
||||
|
||||
#### Scenario: User transfers files while logs are active
|
||||
- **WHEN** artifact transfer is consuming bandwidth
|
||||
- **THEN** log flush MUST keep priority over artifact chunks so historical logs continue to advance
|
||||
|
||||
### Requirement: Artifact transfer is isolated
|
||||
Run SHALL transfer files through an artifact channel with chunking, checksums, resume support, concurrency limits, and throttling separate from logs and control.
|
||||
|
||||
#### Scenario: Plugin writes a config file
|
||||
- **WHEN** a plugin asks the platform to write a config file
|
||||
- **THEN** run MUST receive a scoped job that references an artifact or bounded inline content and MUST write through a safe temp-and-replace flow
|
||||
|
||||
#### Scenario: Large file download active
|
||||
- **WHEN** a large file download is active
|
||||
- **THEN** job ack/result and log batch upload MUST NOT wait behind all artifact chunks
|
||||
|
||||
### Requirement: Game client bridge is optional and separate
|
||||
The system SHALL support an optional game client bridge channel for games that require in-game command execution or structured snapshots, but it MUST remain separate from run lifecycle and log ingestion channels.
|
||||
|
||||
#### Scenario: Game needs in-game command bridge
|
||||
- **WHEN** a game management plugin declares that a game needs an in-game client bridge
|
||||
- **THEN** the platform MUST route game command polling and snapshot reporting through the client bridge contract rather than the run artifact or log channels
|
||||
@@ -0,0 +1,43 @@
|
||||
## 1. Workspace Bootstrap
|
||||
|
||||
- [x] 1.1 Create the four first-class implementation roots: `run/`, `platform/`, `platform_web/`, and `plugins/`.
|
||||
- [x] 1.2 Add root `README.md` explaining the game server management platform scope and subproject boundaries.
|
||||
- [x] 1.3 Add root `AGENTS.md` with cross-project code organization, OpenSpec, verification, and no-scope-creep rules.
|
||||
- [x] 1.4 Add local `README.md` and `AGENTS.md` files in each implementation root.
|
||||
- [x] 1.5 Add `scripts/check-structure.sh` and wire it into documented verification commands.
|
||||
|
||||
## 2. Platform Foundation Contracts
|
||||
|
||||
- [x] 2.1 Define platform directories for API DTOs, database models, domain types, service contracts, repositories, validators, routes, config, and shared helpers.
|
||||
- [x] 2.2 Draft platform contracts for users, game management plugins, server instances, AI providers, run endpoints, jobs, artifacts, log streams, and audit events.
|
||||
- [x] 2.3 Define AI provider contract fields for provider kind, base URL, key reference, model list, relay mode, timeout, status, and redaction policy.
|
||||
- [x] 2.4 Define game management plugin and server instance lifecycle contracts proving one installed plugin can create many server instances.
|
||||
|
||||
## 3. Run Channel Contracts
|
||||
|
||||
- [x] 3.1 Define run control contract for hello, heartbeat, capabilities, version, and capacity.
|
||||
- [x] 3.2 Define run job contract for claim, ack, progress, result, cancel, reconcile, idempotency, and local journal behavior.
|
||||
- [x] 3.3 Define log ingest contract for local spool, batch compression, sequence acknowledgement, retry, and storage adapter boundaries.
|
||||
- [x] 3.4 Define artifact contract for chunk upload/download, checksum, resume, throttling, and priority separation from logs.
|
||||
- [x] 3.5 Define optional game client bridge contract for in-game commands and structured snapshots.
|
||||
|
||||
## 4. Plugin System Contracts
|
||||
|
||||
- [x] 4.1 Define game management plugin manifest schema with server type, create form, lifecycle actions, run capabilities, pages, and AI/file/log permissions.
|
||||
- [x] 4.2 Define local plugin development flow for dev registration, local UI hosting, action schema validation, and real platform-run flows.
|
||||
- [x] 4.3 Define plugin bridge contract that blocks direct run credentials, host paths, AI keys, and storage internals.
|
||||
- [x] 4.4 Add example plugin skeleton under `plugins/examples/` once implementation begins.
|
||||
|
||||
## 5. Frontend Console Contracts
|
||||
|
||||
- [x] 5.1 Define platform_web directories for API clients, route definitions, page contracts, schemas, bridge types, components, stores, and utilities.
|
||||
- [x] 5.2 Define first-party page skeletons for 首页、服务器管理、插件市场、用户管理、AI 提供商管理.
|
||||
- [x] 5.3 Define plugin page bridge UI contract for theme tokens, server instance context, safe API calls, job dispatch, log queries, artifacts, and AI invocation.
|
||||
- [x] 5.4 Add frontend verification rules that prevent API types and route definitions from living inside page components.
|
||||
|
||||
## 6. Verification
|
||||
|
||||
- [x] 6.1 Run `scripts/check-structure.sh` and fix missing required files or directories.
|
||||
- [x] 6.2 Run `openspec validate bootstrap-game-server-platform-architecture --strict` and fix proposal/spec/task issues.
|
||||
- [x] 6.3 Confirm OpenSpec status shows `tasks` done or ready for apply with all required artifacts present.
|
||||
- [x] 6.4 Update README verification instructions if any new required checker is added during implementation.
|
||||
Reference in New Issue
Block a user