From 62328b6fd62fdc6435c2fa51a84dc44b04c24c7c Mon Sep 17 00:00:00 2001 From: Joywayer Date: Sat, 5 Sep 2026 21:08:31 +0800 Subject: [PATCH] docs: specify remote configuration memory flow --- .../plans/2026-09-05-remote-config-memory.md | 47 +++++++++++++++++++ .../2026-09-05-remote-config-memory-design.md | 43 +++++++++++++++++ 2 files changed, 90 insertions(+) create mode 100644 docs/superpowers/plans/2026-09-05-remote-config-memory.md create mode 100644 docs/superpowers/specs/2026-09-05-remote-config-memory-design.md diff --git a/docs/superpowers/plans/2026-09-05-remote-config-memory.md b/docs/superpowers/plans/2026-09-05-remote-config-memory.md new file mode 100644 index 0000000..9c6d9e2 --- /dev/null +++ b/docs/superpowers/plans/2026-09-05-remote-config-memory.md @@ -0,0 +1,47 @@ +# Remote Config Memory Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development. Steps use checkbox syntax for tracking. + +**Goal:** Both modes read remote JSON, resolve it like the legacy project, and keep it only in memory. + +**Architecture:** Existing remote-config.ts owns the hierarchy reader and server selection. Runtime configuration always awaits it; local selection overrides only the final connection targets. Existing local host preserves its lifecycle and loopback guards. + +**Tech Stack:** TypeScript, node:test/tsx, Cocos Creator 3.8.8 through funplay MCP. + +**Spec:** docs/superpowers/specs/2026-09-05-remote-config-memory-design.md + +## Global Constraints + +- Use branches in main checkout; never create worktrees. Current branch codex/local-platform-login. +- No server changes. No .scene/.prefab/.anim/.meta edits or generation. +- Both debug and release fetch remote data. Memory only: no storage or disk cache. +- Preserve legacy truthy hierarchy overrides, first loose identity match, whole-object replacement, game_server_tcp then player_server_tcp. +- Never connect production WebSockets during validation; local preview stays loopback only. +- Never run npm test, test:framework, or scripts/run-framework-tests.mjs. +- Do not stage unrelated files. Root controller owns spec/plan/protocol docs and live verification. + +### Task 1: Replace the obsolete remote contract and integrate every startup consumer + +**Files (all under cocoscreator_projects unless noted):** +- Modify YouleNexus/assets/framework/config/{remote-config.ts,runtime-config.ts,profiles.ts,local-startup.ts}. +- Modify existing YouleNexus/assets/scripts/local-platform-login files only if integration or sensitive diagnostic output needs correction. +- Test framework-tests/config/{remote-config.test.ts,runtime-config.test.ts,profiles.test.ts,local-startup.test.ts}; update dependent typed fixtures in framework-tests and old remote JSON fixture shapes to match new contract. +- Do not add new assets scripts. New test files outside assets are allowed if useful. + +**Interfaces:** Remote config view exposes readonly raw root and getValue(name: string): unknown; export a creator in remote-config.ts taking unknown root and ChannelIdentity. RuntimeConfig exposes the view as remoteConfig and keeps rawConfig as the same raw reference, source always remote and gameserver non-null. parseUrlServers receives the view and resolves game_server_tcp/player_server_tcp. Profiles retain unique servers for local override and all have remote gameserver. + +- [ ] Write failing tests first. Use the actual legacy get_paravalue extracted from 12_Logic.js in a node:vm sandbox as differential oracle; fixtures contain synthetic identities only. Assert values across all five scopes, false/0/empty values, object replacement, missing levels and first duplicate. Example: `assert.deepEqual(view.getValue('hall_config'), legacy(wrapper, 'hall_config'))`. +- [ ] Add startup behavior assertions: for debug local fake fetcher increment calls then return `{player_server_tcp:'remote.example:3088'}`; expect calls=1, source=remote, local servers, raw config retained. release with profile=local must still fetch and use remote candidates. Failed fetch or parse must leave local-host socket calls at zero. No persistence operation is added. +- [ ] Run exact focused tests from cocoscreator_projects: `node --import tsx --test --test-concurrency=1 framework-tests/config/remote-config.test.ts framework-tests/config/runtime-config.test.ts framework-tests/config/profiles.test.ts framework-tests/config/local-startup.test.ts`. Record expected assertion failures before production edits. If tsx ENOMEM occurs, repeat identical command with require_escalated. +- [ ] Implement the smallest integrated change. Loop scopes using first identity equality, update inherited value only if truthy, stop when scope is absent. Validate the JSON root and present hierarchy shape; normalize only the chosen server candidates. Runtime always awaits fetch, builds one memory view, parses candidates, then applies profile local servers. Preserve host cancellation guards and stop semantics. +- [ ] Update dependent tests/fixtures asserting the superseded direct contract; retain all unrelated assertions and add no runtime fallback. All test RuntimeConfig literals must supply the new view via a central test helper where appropriate. +- [ ] Run focused tests then full explicitly enumerated TS suite: `$testPaths = @(rg --files framework-tests -g '*.test.ts' | Sort-Object); node --import tsx --test --test-concurrency=1 @testPaths`. Run `node node_modules/typescript/bin/tsc -p tsconfig.framework.json --noEmit` and `node scripts/check-import-boundaries.mjs`. Discover and explicitly name the two platform architecture tests; do not invoke aggregate generators. +- [ ] Self-review, stage exact task files, commit. Report RED/GREEN commands, counts, changed files, and concerns in task-1-report.md. Do not touch root controller docs or existing dirty resources. +- [ ] Controller dispatches independent spec/quality reviewer; repair findings with failing regressions first, then scoped re-review. + +### Task 2: Documentation and real-boundary acceptance (controller) + +- [ ] Correct docs/protocol/01-传输层与架构.md remote-entry description to active get_config/getConfig_Succ, local wrapper and scoped server selection. Preserve unrelated protocol text. +- [ ] Read the live remote response through the production parser and current identity without storing response body or printing sensitive values. Record fetch/parse outcome and selected hierarchy depth only. +- [ ] Verify actual Cocos preview via funplay MCP, without asset mutations. Observe actual remote request and resolved local target; stop runtime after observation. If browser fetch fails, document status and exact origin/request facts before deciding a fix; do not disable security or proxy silently. +- [ ] Hash-check initial dirty files unchanged. Write a concise acceptance report with separate pure tests, live HTTP and real Creator evidence. Perform whole-change review before declaring completion. diff --git a/docs/superpowers/specs/2026-09-05-remote-config-memory-design.md b/docs/superpowers/specs/2026-09-05-remote-config-memory-design.md new file mode 100644 index 0000000..2d8e45f --- /dev/null +++ b/docs/superpowers/specs/2026-09-05-remote-config-memory-design.md @@ -0,0 +1,43 @@ +# 远程配置读取与内存解析 + +## 已确认目标 + +用户已确认：debug、release 都读取远程配置；按原工程解析；数据只存变量，不下载落盘、不写本地缓存。2026-09-05 用户回复“开始”，授权实施此方案。Login Layer/MainMenu 接线另批处理。 + +## 契约与来源 + +- 原工程 `projects/Game_Surface_3/js/00_Surface/12_Logic.js` 的实际入口是 `get_config`，POST 空 body，URL 为 `gameserver + '?' + timestamp`。`gameconfig` 注入仍按 `-`→`/`、`#`→`:` 后包成 `http://…txt`。 +- `getConfig_Succ` JSON.parse 后把根对象保存在 `GameData.serverConfig.data`。`data` 是客户端包装，不是远程响应信封。旧 `ServerUrl_Succ/data.urlserver` 是未启用路径，不能继续作为本次契约。 +- 当前项目配置源 DEFAULT_GAMESERVER 保持 `https://tsgames.daoqi88.cn/config/update_jsonv2.txt`。原模板旧 URL 在只读预检中返回非 JSON，不能因追求源码一致而切回失效地址；兼容的是读取与解析协议。 +- BUILD_IDENTITY、宿主与 query 身份链沿用已完成实现，不复制 agentid/gameid/channelid/marketid/version，也不改变测试账号与设备来源。 + +## 内存结构与解析 + +在现有 remote-config.ts 提供统一远程配置视图：持有原始根 JSON、已解析的身份，以及 `getValue(name)`。RuntimeConfig 持有此视图，rawConfig 引用同一根数据；所有配置值（含 hall_config、game_config、公告、登录图片、扩展字段）均保留。无 localStorage、文件、跨启动缓存或全局第二份配置。 + +getValue 严格复刻 get_paravalue：全局→匹配 agent→game→channel→market；每层首个宽松相等身份匹配；断层保留上层值；只有 truthy 值覆盖，0/false/空串不覆盖；对象和数组整体覆盖，不自动深合并；缺省返回 null。身份 marketid=0 时保留原函数不搜索该层的语义。非法结构显式 ConfigParseError，不修补。 + +WebSocket 候选按原 getConfig_Succ 选 truthy game_server_tcp，否则 player_server_tcp。支持原字符串/数组顺序及重复项；在协议适配入口转为 ws/wss URL。候选缺失或非法显式失败，不退回 data.urlserver。原工程明确的 game→player 选择属于来源契约。 + +本批不实现 Logic.setConfigInfo 内的 UI 布局、副作用及子游戏 Game_Modify 回调；其所需原始参数均可从统一 getValue 读取。后续界面接线时再按原工程执行各字段的显示转换和来源默认语义。 + +## 启动顺序 + +身份解析 → 远程读取 → 根结构及层级解析 → 服务器候选解析 → 显式本地服务器选择 → 发布 RuntimeConfig → 后续 Runtime 启动。 + +所有 profile 都是 remote。debug 与 release 共用解析器；isDebugger 保持构建模式语义，不控制是否读取。profile=local 是独立的本地服务器选择：仅 debug 使用，远程解析成功后覆盖连接目标为 PROFILES.local 唯一配置的回环地址。release 仍选 prod，不能因 URL 参数误接本地。 + +本地诊断入口继续严格验证 DEBUG/H5/profile=local、身份及回环目标；更新“必须 direct”的旧断言。远程读取/解析失败前不得创建 socket、准备账号或发送登录。停止发生在读取期间时，不得在读取完成后启动连接。 + +## 验收 + +1. 自动测试对照原 get_paravalue 实函数，覆盖五层、断层、重复身份、数字/字符串身份、truthy、对象覆盖及不存在字段。 +2. debug prod、debug local、release 均实际调用 fetcher；本地目标在读取解析完成后才生效；无缓存读写。 +3. 非 JSON、非法层级、地址缺失/非法、HTTP 失败均明确失败；本地 host 无 socket/登录副作用。 +4. 真实 HTTP 读取使用当前配置源与 BUILD_IDENTITY，输出脱敏结构/匹配情况；不输出原始配置及认证信息，不连接其生产 WS。 +5. 经 funplay MCP 验证实际 Creator 浏览器预览远程读取成功、配置在内存、最终目标仍为本地；若浏览器受 CORS 等阻止，记录真实阻塞，不能用 Node 成功代替浏览器通过。 +6. 显式枚举纯 TS 测试、指定架构测试、类型和导入边界检查。原有 dirty 资源不变。 + +## 实施边界 + +沿用主 checkout 的 codex/local-platform-login 分支，不创建 worktree。不改服务器、原生契约、资源序列化文件，不扩展 RPC/房间/子游戏。只修改已有 assets TS，避免新增脚本的 meta 生成要求。同步更正本次直接涉及的协议文档错误；已完成计划保留历史意义，不重新执行。