99 lines
10 KiB
Markdown
99 lines
10 KiB
Markdown
## Context
|
|
|
|
The current platform already has the foundation for plugin runtime declarations, Client Manager build/deploy/control/update/rollback/uninstall, component-key registration, heartbeat, safe status projections, log ingest, artifact records, config diff review, remote access declarations, and backup metadata. The SCUM example manifest also declares a `custom-client` lifecycle and `game-client.bridge` capability, but the bridge is only a placeholder: there is no durable command domain, snapshot ingest/query model, bridge service, repository, DTO, or API surface.
|
|
|
|
The reference SCUM repositories contain useful behavior: a companion client that can interact with the game window and OCR, server operations and command flows, SCUM log parsing, player/squad/vehicle/flag state, backups, restarts, rewards, events, and database-backed queries. They also contain patterns that must not be copied into this platform: shared credentials, insecure TLS skip, arbitrary terminal commands, arbitrary SQL, raw host paths, direct run sockets, direct cloud credentials, and SCUM business rules embedded into executor code.
|
|
|
|
The intended ownership model is:
|
|
|
|
- `game.scum` plugin owns SCUM semantics: pages, schemas, commands, players, squads, vehicles, flags, logs, database query templates, backup/restart/event policy, and `scum_client` companion behavior.
|
|
- Platform owns generic product infrastructure: auth, permission checks, durable queue, scheduling, audit, persistence, safe projections, and plugin-page APIs.
|
|
- Independent Run owns generic privileged execution only: process supervision, bounded file/SQLite/archive operations, and artifact transfer. No SCUM-specific source tree is added to this repository.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
|
|
- Introduce a generic Game Client Bridge that supports authenticated companion clients, durable commands, command claims, acknowledgements, results, cancellation, expiry, idempotency, fencing, and typed snapshot ingestion/query.
|
|
- Add SCUM plugin operations that declare commands, snapshots, permissions, approval levels, page contracts, and companion-client expectations.
|
|
- Align the SCUM plugin manifest and the real `scum_client` model so generated packages use Platform Client Manager registration/session and bridge APIs instead of legacy `/api/v1/scum-clients/*` shared-token endpoints.
|
|
- Preserve channel isolation: game-client bridge traffic does not block run control, jobs, log ingest, or artifact transfer.
|
|
- Keep raw credentials, host paths, SQL text, direct sockets, and component secrets out of plugin pages and browser-visible DTOs.
|
|
|
|
**Non-Goals:**
|
|
|
|
- Do not implement SCUM business logic inside independent Run.
|
|
- Do not add a `run/` source tree back to this repository.
|
|
- Do not expose arbitrary shell, arbitrary SQL, generic remote desktop, direct cloud storage credentials, QQ/SMS/music/Douyin/provider workflows, host sales, billing, or unrelated SaaS marketplace features.
|
|
- Do not auto-ban or auto-punish players from heuristics in the first bridge phase; moderation begins as evidence, alerts, and operator-approved actions.
|
|
- Do not require all legacy SCUM robot features to ship in one implementation pass.
|
|
|
|
## Decisions
|
|
|
|
### Decision: Separate Game Client Bridge from Run lifecycle channels
|
|
|
|
Platform will add a separate bridge domain and API for companion-client commands and snapshots. It will not reuse Run job leases, log batches, artifact chunks, or lifecycle control endpoints for game-window operations.
|
|
|
|
Rationale: the existing run-contracts already state that the optional game client bridge is separate from run lifecycle, control registration, job handling, log ingest, and artifact transport. Keeping it separate prevents game commands or large snapshots from delaying heartbeat, job acknowledgement, log upload, or artifact transfer.
|
|
|
|
Alternative considered: model every companion action as a Run job. That would blur operator-visible game operations with machine-side lifecycle execution, make SCUM commands look like generic privileged jobs, and increase the risk of leaking host/executor details into plugin pages.
|
|
|
|
### Decision: Reuse Client Manager identity for companion clients
|
|
|
|
`scum_client` will be deployed and supervised through the existing Client Manager lifecycle. Bridge APIs will require a valid component session bound to server instance, plugin, profile key, artifact, key generation, deployment generation, capabilities, and expiry.
|
|
|
|
Rationale: the platform already has component-key generation, registration signatures, session revocation, heartbeat, health projection, and staged update/rollback. Extending from that identity avoids introducing a second secret model.
|
|
|
|
Alternative considered: preserve legacy shared `SCUMClientCredential` and `/api/v1/scum-clients/hello|heartbeat|commands|results|snapshots`. That pattern cannot meet current security boundaries because one shared credential can outlive deployment generations, cannot fence stale packages cleanly, and was paired with insecure TLS behavior in the reference client.
|
|
|
|
### Decision: Let plugins declare SCUM semantics, not Platform or Run
|
|
|
|
The `game.scum` plugin will declare command catalog entries, snapshot schemas, query templates, page contracts, permission scopes, and approval levels. Platform will validate and persist these declarations, enforce auth/audit/lifecycle mechanics, and expose safe bridge APIs. Run will only execute generic capabilities requested by Platform.
|
|
|
|
Rationale: the user correctly pointed out that these are SCUM plugin features. Putting SCUM semantics in Platform or Run would make the generic layers harder to reuse for other games and would violate the repository boundary that Run stays independent.
|
|
|
|
Alternative considered: add first-class SCUM domain services directly to Platform. That would produce faster short-term UI but would freeze SCUM-specific concepts into platform core.
|
|
|
|
### Decision: Use typed templates for database and file operations
|
|
|
|
SCUM database reads will be exposed as plugin-declared read-only query templates with typed parameters and bounded result schemas. Backups and restart automation will be declared as SCUM logical policies but executed through generic Platform/Run operations.
|
|
|
|
Rationale: the reference projects include useful SCUM.db and maintenance behavior, but arbitrary SQL or raw path access is not acceptable in the plugin-page boundary. Template declarations preserve common workflows while keeping operations reviewable and enforceable.
|
|
|
|
Alternative considered: expose a generic SQL console or file browser to plugin pages. That would violate the existing platform rule that pages never receive DSNs, credentials, host paths, or direct Run endpoints.
|
|
|
|
### Decision: Start moderation as evidence and approval flows
|
|
|
|
Duplicate IP, mine, unlock, trade, and suspicious activity signals will initially create typed evidence, alerts, and suggested actions. Destructive or punitive actions require explicit operator approval and audit.
|
|
|
|
Rationale: the reference robot contains powerful heuristics, but automatic punishments have high false-positive and abuse risk. Approval-first flows are safer and still make the signals useful.
|
|
|
|
Alternative considered: directly port automatic punish/ban behavior. That is out of scope for the first bridge and would require separate governance requirements.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- Bridge queue and snapshot persistence can become broad quickly -> Mitigation: phase implementation around a small generic state machine, bounded payload sizes, schema versioning, retention, and server-scoped query filters.
|
|
- Real `scum_client` currently reads embedded `config.yaml` and does not parse the manifest's `--config config.json` argument -> Mitigation: update the SCUM plugin declaration and companion bootstrap together; support a generated config format that carries Platform registration settings without raw secrets in browser-visible DTOs.
|
|
- Snapshot schemas may drift from actual SCUM output -> Mitigation: version schemas, persist raw diagnostic excerpts only in redacted server-side records when needed, and keep plugin validators close to parser code.
|
|
- Remote read-only SQLite transport currently has gaps around payload/input propagation -> Mitigation: implement bridge database templates only after the remote access request path preserves declared inputs end to end.
|
|
- Frontend scope could sprawl into the whole legacy admin product -> Mitigation: first pages should cover operationally central SCUM surfaces only: client health, commands, players/sessions, vehicles/squads/flags, semantic logs, and maintenance.
|
|
- Long-running commands may conflict with deployment updates or session resets -> Mitigation: command claims include component session, deployment generation, lease expiry, and fencing tokens; stale sessions cannot ack or complete current commands.
|
|
|
|
## Migration Plan
|
|
|
|
1. Add Platform bridge domain, DTOs, repository interfaces, persistence, service methods, validators, routes, and tests.
|
|
2. Extend plugin manifest/schema validation for game-client command catalogs, snapshot schemas, approval levels, and page bridge contracts.
|
|
3. Update the SCUM example plugin manifest from local proof placeholders to a real `game.scum` lifecycle/client declaration aligned with generated config and Client Manager registration.
|
|
4. Add SCUM plugin page/API types and initial UI surfaces using safe Platform projections.
|
|
5. Adapt `scum_client` packaging expectations so it registers and heartbeats through Client Manager sessions and uses bridge command/snapshot APIs.
|
|
6. Add typed SCUM log parsing, database query templates, backup/restart declarations, and event/reward flows in later task groups after the bridge is verified.
|
|
7. Run `openspec validate implement-game-client-bridge-and-scum-operations --strict`, focused backend/frontend/plugin tests, and `scripts/check-structure.sh`.
|
|
|
|
Rollback is feature-flag-like by declaration: servers without a deployed compatible Client Manager or without a plugin-declared bridge catalog see disabled bridge actions and no command dispatch. Existing run lifecycle, log ingest, and plugin registry behavior remains intact.
|
|
|
|
## Open Questions
|
|
|
|
- Which exact SCUM operations should be enabled in the first UI pass: read-only snapshots plus announcements, or also gifts/rewards/restarts?
|
|
- Should bridge command payload/result bodies be stored entirely in Platform DB for the first pass, or split larger artifacts to the artifact channel once payloads exceed a small threshold?
|
|
- Does `scum_client` remain in the external SCUM repository with generated packaging metadata, or should a minimal companion fixture be added under the plugin example for local smoke tests only?
|