From 239af0aa398acb75aee47cfe4196ee85f7cb0224 Mon Sep 17 00:00:00 2001 From: Joywayer Date: Sat, 5 Sep 2026 22:40:24 +0800 Subject: [PATCH] docs: specify unified startup configuration --- .../2026-09-05-unified-startup-config.md | 44 +++++++++++++++ ...026-09-05-unified-startup-config-design.md | 54 +++++++++++++++++++ 2 files changed, 98 insertions(+) create mode 100644 docs/superpowers/plans/2026-09-05-unified-startup-config.md create mode 100644 docs/superpowers/specs/2026-09-05-unified-startup-config-design.md diff --git a/docs/superpowers/plans/2026-09-05-unified-startup-config.md b/docs/superpowers/plans/2026-09-05-unified-startup-config.md new file mode 100644 index 0000000..494b360 --- /dev/null +++ b/docs/superpowers/plans/2026-09-05-unified-startup-config.md @@ -0,0 +1,44 @@ +# Unified Startup Config Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development. + +**Goal:** One profiles.ts source configures runtime mode, remote URL and local/remote server selection; browser testing requires no query switches. + +**Architecture:** STARTUP_CONFIG is the sole production source. Runtime takes an optional whole StartupConfig injection for tests and publishes a validated source snapshot. Local diagnostic consumers validate that source and derived targets, preserving account namespace and lifecycle. + +**Tech Stack:** TypeScript, node:test/tsx, Creator 3.8.8 via funplay MCP. + +**Spec:** docs/superpowers/specs/2026-09-05-unified-startup-config-design.md + +## Global Constraints + +- Main checkout codex/local-platform-login only; never worktrees. +- No server changes, serialized asset changes, new assets scripts, RPC expansion or subgame selection. +- mode and useLocalServer are independent. All four combinations read remote JSON into memory; no persistent cache. +- Source values appear once in STARTUP_CONFIG: mode debug, gameserver https://tsgames.daoqi88.cn/config/update_jsonv2.txt, useLocalServer true, localServers ws://127.0.0.1:3088. +- URL mode/profile cannot override or block startup. Preserve original gameconfig injection and identity sources. +- No npm test, test:framework, scripts/run-framework-tests.mjs or resource generators. +- Protect original52 dirty paths, stage exact task files only. No merge/push. + +### Task 1: Integrate the unified code configuration through all existing consumers + +**Files:** existing assets/framework/config/{profiles.ts,runtime-mode.ts,runtime-config.ts,local-startup.ts,bootstrap.ts}; existing assets/scripts/{LoginFlow.ts,local-platform-login/LocalPlatformLogin.ts}; dependent existing local-platform-login/adapters files only if required. Paths prefixed cocoscreator_projects/YouleNexus. Test files and fixtures are under cocoscreator_projects/framework-tests. + +**Interfaces:** export StartupConfig and STARTUP_CONFIG from profiles.ts. ResolveRuntimeConfigOptions replaces mode with optional startupConfig: Readonly; production default is the exported constant, test configuration is explicit. RuntimeConfig retains mode/isDebugger/identity/servers/remoteConfig/rawConfig and exposes validated startupConfig for local consumers to validate against the same source. No independent profile selector. runtime-mode.ts may export RuntimeMode and a pure reader but contains no environment or URL defaults. + +- [ ] Write RED tests in framework-tests/config/{profiles,runtime-mode,runtime-config,local-startup,bootstrap}.test.ts and local-platform-login/host.test.ts. For example, inject `{...STARTUP_CONFIG,mode:'release',useLocalServer:true}`, search `?mode=debug&profile=prod`, fake fetch `{visitor_server_tcp:'visitor:1'}`; assert one fetch and local servers with mode release. Repeat mode debug/release and useLocalServer true/false, using valid remote game/player candidates when false. Assert the default no-query local host starts, and conflicting/duplicate mode/profile parameters do not select another configuration. +- [ ] Run focused RED from cocoscreator_projects: `node --import tsx --test --test-concurrency=1 framework-tests/config/profiles.test.ts framework-tests/config/runtime-mode.test.ts framework-tests/config/runtime-config.test.ts framework-tests/config/local-startup.test.ts framework-tests/config/bootstrap.test.ts framework-tests/local-platform-login/host.test.ts`. Repeat identical command require_escalated on known sandbox ENOMEM. +- [ ] Implement source and validation: explicit mode enum, boolean useLocalServer, valid http(s) gameserver, valid loopback localServers. Freeze the source/array. Reject malformed values; no consumer defaults. Remove URL/environment mode selection and PROFILES selector. Preserve resolveGameServer original injection decoding. +- [ ] Integrate runtime: `const startupConfig = ...options.startupConfig or STARTUP_CONFIG` through one validated source function; resolve identity/injected remote URL, await fetch, create memory view, choose `startupConfig.useLocalServer ? startupConfig.localServers : parseUrlServers(remoteConfig)`. Preserve errors. Derive mode/isDebugger from startupConfig. +- [ ] Integrate diagnostic and facade: remove scalar mode in component; local-startup checks code source debug/local and loopback and accepts empty search. Ignore mode/profile query while retaining identity/gameconfig diagnostic restrictions. Use the same source snapshot in forged-context checks. Keep internal profile local namespace for account storage. Bootstrap uses same runtime; old LoginFlow stops after config error rather than assigning fallback identity/server, and forwards real location.search. Do not rewire the old UI or login contract. +- [ ] Update affected test literals via existing fixtures as appropriate; replace obsolete mode/profile expectations with new contract without weakening lifecycle/source tests. Add behavior tests for malformed local addresses and gameserver, remote failure, local diagnostic refusal of release/remote settings, and native injection compatibility. +- [ ] GREEN focused suite; explicit full suite: `$testPaths = @(rg --files framework-tests -g '*.test.ts' | Sort-Object); node --import tsx --test --test-concurrency=1 @testPaths`; architecture: `node --test framework-tests/architecture/import-boundaries.test.mjs framework-tests/architecture/presentation-boundaries.test.mjs`; type: `node node_modules/typescript/bin/tsc -p tsconfig.framework.json --noEmit`; boundaries: `node scripts/check-import-boundaries.mjs`. +- [ ] Self-review and exact task-only commit. Report RED/GREEN commands/results and file list in task-1-report.md; no full remote data/logged secrets. +- [ ] Independent task spec/quality review, fix loop with targeted regressions, then scoped re-review. + +### Task 2: Real browser and documentation acceptance (controller) + +- [ ] MCP verify actual main checkout Creator project and current dirty state; refresh only modified existing TS resources. +- [ ] Open actual LocalPlatformLogin preview without query parameters, verify remote config source, local target, login ready and no failure; stop afterward. Configuration-only browser calls may verify the other source selections without creating production sockets. +- [ ] Write docs/superpowers/reports/2026-09-05-unified-startup-config-acceptance.md with exact results, final current configuration location, publishing instructions and source limitation. Keep prior completed reports as history. +- [ ] Whole-change independent review; verify original dirty hashes/status unchanged; mark plan progress and commit exact documents. No merge/push. diff --git a/docs/superpowers/specs/2026-09-05-unified-startup-config-design.md b/docs/superpowers/specs/2026-09-05-unified-startup-config-design.md new file mode 100644 index 0000000..14c41c4 --- /dev/null +++ b/docs/superpowers/specs/2026-09-05-unified-startup-config-design.md @@ -0,0 +1,54 @@ +# 单文件启动配置 + +## 已批准方案 + +用户要求把远程配置地址、debug/release、是否使用本地服务器集中在同一个代码文件，便于发布修改；已确认布尔字段命名 useLocalServer，并回复“可以”授权实施。 + +唯一可编辑配置入口为已有 `cocoscreator_projects/YouleNexus/assets/framework/config/profiles.ts`： + +```ts +export const STARTUP_CONFIG = { + mode: 'debug', + gameserver: 'https://tsgames.daoqi88.cn/config/update_jsonv2.txt', + useLocalServer: true, + localServers: ['ws://127.0.0.1:3088'], +} as const; +``` + +上述四项只定义一处。配置有明确 StartupConfig 类型、只读约束和入口验证；发布时仅修改这里的 mode 和 useLocalServer。应用 mode 不冒充 Creator 的编译 DEBUG 标志；引擎构建选项仍由 Creator 管理。 + +## 读取与来源 + +- 生产入口不再传 mode 常量；runtime-mode.ts 不读取 URL、不探测全局 DEBUG、不默认 debug。它保留类型和必要的纯模式读取功能，最终模式来自 STARTUP_CONFIG。 +- runtime-config.ts 默认消费 STARTUP_CONFIG。保留显式整体配置注入作为纯测试接缝（options.startupConfig），不保留单独 mode/profile/servers 的第二套来源。 +- URL 的 mode/profile 完全不参与模式和目标选择，包括冲突值或重复项，不因此拒绝网页启动。 +- 原生/H5 的既有 gameconfig 注入解码、身份 query/native/BUILD 来源保持兼容，不把身份搬迁或复制。正常网页无参数即可运行。 +- 旧 PROFILES/ACTIVE_PROFILE/resolveActiveProfile 不再作为生产配置来源；删除不再使用的选择逻辑，避免维护两套配置。仅用于旧 facade 或账号存储命名的派生 profile 标签不构成配置开关。 + +## 模式与服务器选择 + +debug/release 与 useLocalServer 是两个独立字段，四种组合都读取远程 JSON，按已完成的原工程层级规则解析并仅保存在内存。 + +- useLocalServer=true：成功读取并验证远程根/层级后采用配置中的 localServers，不要求未使用的远程 TCP 字段存在。 +- useLocalServer=false：使用 game_server_tcp 或 player_server_tcp，缺失/非法显式失败，不使用 visitor TCP 或本地兜底。 +- mode=release 不再隐式强制远程地址，否则两个字段不独立。实际发版应明确设 release/false。 +- 本地地址必须有效、无认证信息/片段且为 loopback（127.0.0.0/8、localhost 或 ::1）；缺少配置显式失败，消费方不得补值。 + +## 入口和诊断边界 + +LocalPlatformLogin 不再硬编码 mode，也不要求 profile=local。保留 cc/env.DEBUG 与 H5 保护：它是本地诊断场景，未授权将它变成完整生产启动场景。进入诊断前验证配置的 mode=debug、useLocalServer=true，并沿已有严格回环目标、停止/失败生命周期检查工作。无参数 Creator 网页预览应进入 login/ready。 + +本地账号缓存的 namespace 保持原 local 标签，避免无关账号重建；标签可保留为内部常量，不再从 URL 读取。 + +旧 LoginFlow 仅做调用接口兼容调整：移除 mode/profile 硬编码和配置失败后的地址/身份兜底，失败时停止；不重做 UI 接线、不称旧场景已接入新 Runtime。其其他旧逻辑留在后续入口迁移批次。 + +## 验收及范围 + +1. 默认无参数读取统一配置；冲突的 mode/profile URL 不改变代码配置。 +2. 四种 mode/useLocalServer 组合、无效配置、远程读取失败、缺失远程地址和原生 gameconfig 注入有行为测试；任何失败无连接兜底。 +3. 原 get_paravalue、内存唯一引用与无远程持久化要求保持通过。 +4. 显式枚举纯 TS 测试，指定两项架构测试、类型和边界检查；每项实现 TDD、独立规格/质量和最终审查。 +5. funplay MCP 核实主 checkout 项目，刷新既有 TS 后用 `http://127.0.0.1:7456/`（实际端口为准）无参数预览，真实读取远程配置并进入可登录页，最终目标本地。验证后停止，不扩展 RPC 验收。 +6. 使用当前分支，不建 worktree。保留原有52项改动，不改服务器或任何 .scene/.prefab/.anim/.meta，不新增 assets 文件。 + +当前真实远程 JSON 对 BUILD 身份仍缺少 game/player TCP；useLocalServer=false 的实际启动限制保留，不通过改身份、选子游戏或修改远程服务来掩盖。