youle_cocos/docs/guides/配置与调试指南.md

YouleNexus 配置与调试指南

本指南对应单文件启动配置设计：docs/superpowers/specs/2026-09-05-unified-startup-config-design.md。历史计划和验收报告记录当时行为，不作为当前配置步骤。

修改启动配置

只在 cocoscreator_projects/YouleNexus/assets/framework/config/profiles.ts 的 STARTUP_CONFIG 修改应用启动选项：

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;

• mode：应用运行模式，值为 debug 或 release。
• gameserver：远程配置 JSON 的 HTTP(S) 地址；不是 WebSocket 服务器地址。
• useLocalServer：true 使用本地地址，false 使用远程 JSON 按身份解析出的服务器地址。
• localServers：本地服务器候选列表，必须是有效回环 WebSocket 地址。

运行模式和服务器选择独立；release 不会偷偷改写 useLocalServer。发布时在这里明确设置 mode: 'release'、useLocalServer: false，并核对 gameserver。Creator 构建面板的 Debug 选项控制引擎编译，不能代替这里的应用配置。

URL 的 mode/profile 参数不再参与启动选择，也不再要求它们存在。runtime-mode.ts 不自动读取 URL 或全局 DEBUG。生产调用方不再另传 mode、硬编码服务器或复制上述配置；测试可以整体注入 StartupConfig，以覆盖不同组合。

网页本地测试

1. 确认 STARTUP_CONFIG 为 debug、useLocalServer=true，且本地服务运行在配置的地址。
2. Creator 打开主 checkout 的 YouleNexus 工程和 assets/scenes/LocalPlatformLogin.scene。
3. 点击网页预览，使用编辑器生成的原始地址，例如 http://127.0.0.1:7456/。不需要追加查询参数，端口以实际预览为准。
4. 观察远程配置读取、资源加载、本地连接完成后进入可登录页面。需要验收登录时再点击游客登录。

LocalPlatformLogin 是 DEBUG 浏览器下的本地诊断场景，要求应用配置 debug/useLocalServer=true，保留回环目标和生命周期保护。它不是正式生产入口；旧 Login.scene 也尚未接入新 Runtime，不用它替代验收。编辑器资源操作遵循仓库 AGENTS.md，通过 funplay MCP；未经授权不改序列化资源。

配置读取流程

统一配置 → 宿主身份 → 远程地址注入解析 → HTTP 读取 → JSON 根与身份层级解析 → 选择最终服务器 → Runtime 启动。

无论 debug/release，也无论是否使用本地服务器，都必须先读取远程配置。HttpConfigFetcher 忠实使用 POST 空 body，URL 无条件拼接 ? 和时间戳。HTTP/JSON/层级错误明确抛出，不使用旧缓存或连接兜底。

远程响应本身是根 JSON；原工程 getConfig_Succ 将它放进客户端 GameData.serverConfig.data，data 不是远程信封。当前 RuntimeConfig.rawConfig 与 RuntimeConfig.remoteConfig.raw 引用同一根对象；remoteConfig.getValue(name) 提供统一取值。只存内存，无远程文件落盘或 localStorage 快照。

层级规则沿用原 get_paravalue：全局 → agent → game → channel → market；每层第一个身份宽松相等的条目生效；只有 truthy 值覆盖，0/false/空串不覆盖；缺少匹配层即继承已取得的值；对象和数组整体替换，不自动深合并。

useLocalServer=false 时，选择 truthy game_server_tcp，否则 player_server_tcp，支持字符串和数组，保留顺序及重复项。不使用 visitor_server_tcp 兜底。最终候选在配置边界验证，禁止认证信息、非法协议和 URL 片段。

useLocalServer=true 时，在远程根和层级解析完成后使用 localServers；未消费的远程 game/player TCP 可以缺失。该逻辑是显式来源选择，不是读取错误后的退路。

公告、大厅配置、登录图片等字段由相同 getValue 读取。界面显示转换和原工程 UI 副作用在各自接线批次实现。

身份、账号与设备

身份唯一构建来源仍是 config/sources/defaults.ts 的 BUILD_IDENTITY，不在 profiles.ts 再复制一份。协议字段为 agentid、channelid、gameid、marketid、version；version 是 number，不是显示版本字符串。

• H5 使用 BUILD_IDENTITY，再应用 query-string.ts 支持的 agentid/channelid/marketid/version 覆盖；gameid 不从 URL 覆盖。
• native-settings 使用构建 gameid/version 与原生提供的 agent/channel/market；不完整身份明确失败，不用 H5 身份填补。
• uAgent_3 使用 app_agent/app_channel/app_market 等原生全局，按显式 hostKind 选择，不从浏览器 URL 猜测宿主。

原生接口名和源适配器中已定义的缺省语义保持原工程契约，不在下游重复实现。

本地游客账号由 adapters/local/visitor-account.ts 读取其已有作用域缓存或生成。openid 是 testopenid_ 加随机数，unionid 是 ylgame 加同一随机数，同时产生昵称、头像、性别和地区。设备字段由 login-sources.ts 等来源提供；UI 和协议消费方不补默认值。账号/机器标识的已有存储与“远程配置只存内存”是不同职责。

不运行历史 scripts/login-live.ts，不使用其占位账号或 staging 路径作为本次验证入口。

原生远程地址注入

保留原工程 gameconfig 契约：非空注入字符串按 -→/、#→: 解码，再形成 http://…txt。native-settings 读取 getothername('gameconfig')，uAgent_3 读取 app_gameconfig，普通 H5 的对应参数在统一配置解析边界处理。未注入时只使用 STARTUP_CONFIG.gameserver。

这是宿主契约的集中解析，不是另一份生产配置常量。本地诊断入口仍拒绝非空 gameconfig 和 gameid 覆盖，避免误用该诊断环境；普通运行配置解析仍保留注入兼容。

代码入口

• profiles.ts：唯一可编辑 STARTUP_CONFIG 及配置类型/验证，保留远程地址注入解码。
• runtime-mode.ts：运行模式类型及纯读取逻辑，不拥有另一套默认配置。
• runtime-config.ts：最终身份、服务器和内存远程配置的统一解析入口。
• remote-config.ts：根/层级验证、getValue 与远程服务器候选解析。
• remote-config-fetcher.ts：真实 HTTP 读取。
• local-startup.ts：本地诊断边界验证，使用解析结果携带的配置来源。
• bootstrap.ts：旧调用方的兼容外观，委托同一个 runtime-config；新流程直接使用 Runtime。

普通网页配置解析示例（由启动宿主继续接入 Runtime）：

const config = await resolveRuntimeConfig({
  hostKind: 'h5',
  win: window as unknown as NativeHost,
  search: window.location.search,
  fetcher: new HttpConfigFetcher(),
});

不要在这个调用处再次写 mode 或服务器地址，也不要捕获配置错误后创建兜底连接。

自动化验证

PowerShell 工作目录为 cocoscreator_projects：

$testPaths = @(rg --files framework-tests -g '*.test.ts' | Sort-Object)
node --import tsx --test --test-concurrency=1 @testPaths
node --test framework-tests/architecture/import-boundaries.test.mjs framework-tests/architecture/presentation-boundaries.test.mjs
node node_modules/typescript/bin/tsc -p tsconfig.framework.json --noEmit
node scripts/check-import-boundaries.mjs

禁止运行 npm test、test:framework 或 scripts/run-framework-tests.mjs；历史聚合入口含资源生成器。测试在 assets 外，不能用无引擎测试通过替代真实 Creator 界面验收。遇到已知 tsx 沙箱 uv_os_get_passwd ENOMEM，在获准环境执行同一精确命令，不改业务代码绕过。

发布与实际来源限制

发布前修改 STARTUP_CONFIG 中的应用模式和服务器选择，并核对远程配置是否为目标身份提供有效 game/player TCP。游戏身份、原生接口和账号来源按各自权威配置验证，不复制临时值到消费端。

2026-09-05 的真实配置对当前 BUILD 身份匹配 agent，但没有其下匹配 game，继承得到的 game/player TCP 均缺失。因此本地诊断可以在读取后使用明确本地地址；选择远程服务器的真实启动仍会显式报错。不要据此擅自选择子游戏、更换身份或使用游客服务器地址。

远程/原生/服务器契约仍以实际原工程及 docs/protocol 对应章节核对。此前指南中的 GET、远程 data 包装、URL profile 选择、直连跳过读取、版本字符串及默认身份兜底说明已失效，本版不再沿用。