first commit

openspec/changes/implement-local-debug-workspace/design.md

@@ -0,0 +1,66 @@
+## Context
+
+The platform now has real local capabilities across `platform/`, `run/`, `platform_web/`, and `plugins/`: platform can serve API-backed metadata, run can register and execute lifecycle jobs, platform_web can operate against platform APIs, and the local proof plugin can drive server lifecycle through platform-mediated contracts. The remaining local-development gap is repeatability. Contributors currently need to reconstruct proof commands, temporary data roots, setup payloads, frontend proxy settings, browser walkthrough steps, and cleanup procedures from scattered task evidence.
+
+This change creates a first-party local debug workspace. It should make the real stack easy to boot, reset, inspect, and verify without introducing production deployment scope or bypassing platform mediation.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Provide one documented and/or scripted local workflow for platform, run worker, platform_web, and the dev game plugin path.
+- Use explicit local ports, environment variables, data roots, spool roots, log roots, and reset commands.
+- Include smoke checks for platform health, run registration/heartbeat, plugin registration/installation, server lifecycle, logs/artifact references, and API-backed frontend behavior.
+- Include browser walkthrough requirements for 首页、服务器管理、插件市场、用户管理、AI 提供商管理 and one plugin lifecycle path.
+- Keep all plugin/browser operations platform-mediated and prove no raw host paths, credentials, direct sockets, run tokens, raw AI keys, or plugin-owned transport details are visible.
+
+**Non-Goals:**
+- Do not add cloud deployment, billing, host sales, agent-provider flows, or unrelated SaaS marketplace behavior.
+- Do not add Docker-only requirements; local workflow may coexist with Docker but must be runnable with repository commands.
+- Do not replace the existing magical-girl crystal-moonlight platform_web style.
+- Do not make plugins connect directly to run or expose run sockets/tokens to platform_web.
+- Do not implement the later automated browser acceptance suite here; this change may define a manual/semiautomated walkthrough that a later change can automate.
+
+## Decisions
+
+1. Use repository-owned local scripts/docs instead of only OpenSpec task notes.
+
+   The workflow must survive after the implementation chat. A script plus a short markdown guide is preferable to evidence-only commands because contributors need a stable entry point. The script should print the exact platform, run, and frontend commands and write logs to predictable local files.
+
+   Alternative considered: keep commands solely in `tasks.md`. That satisfies the change once but does not improve day-to-day local debugging.
+
+2. Keep local data under a disposable workspace root.
+
+   Platform metadata, platform log bodies, run workspace files, and run spool files should live under an explicit root such as `.local-debug/` or `/private/tmp/browser-local-debug-workspace`. Reset must remove only that root and should never delete broad user directories.
+
+   Alternative considered: reuse `.platform-data` and `.run-workspace` defaults. That is convenient but makes reset behavior less auditable and can mix unrelated local experiments.
+
+3. Use the existing API-backed platform and Vite proxy shape.
+
+   The frontend should run with `PLATFORM_API_PROXY=http://127.0.0.1:<platform-port>` and `VITE_PLATFORM_API_BASE_URL=/api/v1`, proving browser calls go through platform-owned APIs. Browser/plugin pages must not receive direct run URLs or run credentials.
+
+   Alternative considered: have platform_web point directly at a run worker or plugin dev server. That violates the architecture boundaries and is explicitly out of scope.
+
+4. Seed only safe local fixtures.
+
+   The local workflow may create a dev plugin, one or more server instances, and lifecycle action templates under the scoped run workspace. Fixtures must use logical IDs and harmless commands. They must not require real game binaries, raw credentials, shell launchers, direct sockets, absolute host paths in API payloads, or raw AI keys.
+
+   Alternative considered: require a real game server installation. That would make the debug workflow too heavy and environment-specific for this stream step.
+
+## Risks / Trade-offs
+
+- Port collisions -> Provide configurable env vars and print the resolved ports before starting services.
+- Background process cleanup is brittle -> Prefer explicit log/PID files and a stop/reset command over hidden shell process management.
+- Smoke setup can drift from APIs -> Implement smoke using the same public/local API routes and plugin manifest validation used elsewhere.
+- Browser walkthrough remains manual -> Record exact pages, expected API-backed signals, and forbidden-fragment scan requirements so the later acceptance-suite change can automate it.
+- Reset can become dangerous -> Scope cleanup to the local debug root and document what is removed before removing it.
+
+## Migration Plan
+
+1. Add local debug documentation and scripts or command wrappers under the appropriate repository location.
+2. Add or update tests/smoke checks for generated commands, safe reset scope, and API-backed local fixture setup.
+3. Run the documented local stack and browser/API walkthrough.
+4. Record evidence in `tasks.md`, run structure checks and strict OpenSpec validation, and advance the stream pointer.
+
+## Open Questions
+
+- None currently. If implementation reveals an existing script location convention, follow it rather than inventing a parallel tool layout.