服务端接入起步

先让游戏服务器完成授权码兑换，再把 SDK 接入实际角色系统。v0.2.0 的兑换接口已实现；示例返回的是本地平台会话与模拟角色，外部游戏存档、角色和发货尚未接通。

准备应用与环境

1. 在开发者控制台创建逻辑游戏，选择 H5、Android 或 iOS，并保存首次显示的服务端密钥。等待平台审批通过；待审或停用应用不能登录。
2. 将控制台实际 App ID 加入你自己的游戏服务器允许列表。密钥仅注入游戏服务器环境，不写入 H5、Android 或 iOS 包、VITE_* 变量或请求日志。
3. 在本地启动平台 API，健康地址为 http://127.0.0.1:18787/api/health，正常返回 {"status":"ok","mode":"demo"}。

仓库提供 examples/game-server.mjs，默认监听 127.0.0.1:18788。默认允许列表是 starlight-h5、starlight-android，浏览器来源默认 http://127.0.0.1:5173。新应用通过 GAME_APP_IDS 配置逗号分隔的真实 App ID，通过 GAME_BROWSER_ORIGIN 配置实际浏览器 Origin，无需修改源码中的列表。所有配置的 App ID 必须属于当前密钥对应的同一逻辑游戏。

# 使用控制台实际发放的值；以下文字是占位符，不是真实凭据。
$env:ACCOUNT_ORIGIN = 'http://127.0.0.1:18787'
$env:GAME_SERVER_KEY = '<仅注入游戏服务器的应用密钥>'
$env:GAME_APP_IDS = '<实际H5_App_ID>,<实际Android_App_ID>,<实际iOS_App_ID>'
$env:GAME_BROWSER_ORIGIN = 'http://127.0.0.1:5173'
node examples/game-server.mjs

只填实际创建并批准的平台标识；仅接 iOS 时 GAME_APP_IDS 填一个真实 iOS App ID 即可。原生 URLSession/Android 请求通常不携带 Origin，示例允许这类请求；携带 Origin 的浏览器请求必须精确匹配配置值，不使用通配符。

新应用的密钥摘要已由平台保存，只给游戏服务器注入对应密钥即可。平台自身的 GAME_SERVER_KEY 仅用于原星渊演示游戏的初始化配置，不负责配置任意新应用。示例命令监听本机回环地址；真机联调需受控代理或调整部署，使手机能访问游戏服务器及平台 API。

连接 SDK 的 exchange 回调

SDK login() 会生成 PKCE、调用账号登录并检查 state。宿主提供的 exchange 回调只把 {appId,code,codeVerifier} 发给游戏服务器：

const sdk = new StarlightSDK({
  appId: applicationAppId,
  baseUrl: 'http://127.0.0.1:18787',
  exchange: async (input) => {
    const response = await fetch('http://127.0.0.1:18788/api/game/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(input),
      signal: AbortSignal.timeout(15000),
    });
    const result = await response.json();
    if (!response.ok) throw new Error(result.error?.message ?? '登录兑换失败');
    return result;
  },
});

applicationAppId 是你已经读取的 App ID，StarlightSDK 来自已安装的 SDK 包。此回调中没有 X-API-Key；它由游戏服务器请求平台时添加。示例会把平台 SessionResponse 原样返回，以匹配当前 SDK。真实游戏还要在服务器映射 gameUserId、建立自身游戏会话和处理撤销，不能直接把模拟角色当成实际存档。

验收与排错

完成一次 SDK 登录，确认游戏服务器访问 /api/server/auth/exchange 得到 token、user、role、expiresAt。随后用该玩家 token 调用 /api/me，比较 user.gameUserId 和 role.id。重新使用同一授权码应被拒绝；H5、Android 与 iOS 属同一逻辑游戏时应得到同一个角色。

APP_UNAVAILABLE 表示尚未审批、停用或开发者被停用；INVALID_GAME_KEY 先检查应用归属和最近是否轮换；INVALID_AUTH_CODE 重新开始登录，不持续重试已消费的码。示例返回 INVALID_INPUT 时检查 GAME_APP_IDS 与实际 App ID。新应用访问 /api/demo/game/session 会得到 GAME_BACKEND_REQUIRED，应接入带密钥的服务器兑换，而不是放宽客户端权限。

后续阅读：身份与角色、密钥管理、兑换接口。机器可读契约：OpenAPI 3.1。

实现依据

examples/game-server.mjs 的 /api/game/login 与 GAME_APP_IDS / GAME_BROWSER_ORIGIN 配置；packages/sdk/src/index.ts 的 createPkce()、login()；packages/server/src/app.ts 的 exchange；packages/contracts/src/index.ts 的 SessionResponse。示例不是已完成的生产游戏后端。