@66rpg/lumimaker 0.1.40 → 0.1.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@66rpg/lumimaker",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "description": "幻光文游制作器：登录、校验并发布到幻光文游社区；validate-template（TS）；login / publish 等转发 lumimaker",
   "type": "module",
   "bin": {
@@ -33,9 +33,9 @@
     "picocolors": "^1.1.1"
   },
   "optionalDependencies": {
-    "@66rpg/lumimaker-win32-x64": "0.1.40",
-    "@66rpg/lumimaker-darwin-arm64": "0.1.40",
-    "@66rpg/lumimaker-darwin-x64": "0.1.40"
+    "@66rpg/lumimaker-win32-x64": "0.1.42",
+    "@66rpg/lumimaker-darwin-arm64": "0.1.42",
+    "@66rpg/lumimaker-darwin-x64": "0.1.42"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",

package/skill/lumimaker/SKILL.md

@@ -15,7 +15,7 @@ description: 命令操作与发布指引。用户询问如何登录、发布作
 
 - **CLI 命令操作与交互规范**：由本技能（`lumimaker`）说明。
 - **模板工程规范协议**：查阅 `lumimaker-template-spec`（校验工程目录、`package.json` 字段与脚本、构建产物）。
-- **播放页 SDK 接入**：查阅 `lumimaker-play-sdk`（在作品代码中通过 `window.CgMakerSdk` 调用平台功能）。
+- **播放页 SDK 接入**：查阅 `lumimaker-play-sdk`（在作品代码中通过 `window.LumiMakerSdk` 调用平台功能）。
 - **免费背景音乐和音效**：查阅 `lumimaker-free-audio`（按用户描述挑选，下载到工程里再用，不要把网上的音频地址写进作品）。
 
 ---

package/skill/lumimaker/references/publish-game.md

@@ -21,7 +21,7 @@
    - **产物共用机制**：正式版与试玩版的构建产物均输出到工程根目录的 `dist/`，后构建的一方会覆盖前一方。因此，每次构建完成后须立即执行对应的发布命令，切勿连续构建后再发。
 2. **纯静态与本地化**：
    - 静态产物中引用的所有资源（图片、音频、字体、脚本、样式）必须全部打包在 `dist/` 本地文件中，严禁在页面中引用在线 CDN 外链。
-   - 平台播放器会在运行时自动向页面注入 `window.CgMakerSdk`，切勿手动将 SDK 文件打包进产物中。
+   - 平台播放器会在运行时自动向页面注入 `window.LumiMakerSdk`，切勿手动将 SDK 文件打包进产物中。
 
 ---
 

package/skill/lumimaker-play-sdk/SKILL.md

@@ -1,87 +1,75 @@
 ---
 name: lumimaker-play-sdk
-description: 幻光文游社区播放页 SDK（window.CgMakerSdk）接入指引。在作品内实现用户登录、展示昵称头像、查询游玩/购买权限（章节锁）、安全返回社区或进入全屏时使用。平台自动注入 SDK 脚本，严禁手动引入或打包 SDK 文件。
+description: 幻光文游社区播放页 SDK（window.LumiMakerSdk）接入指引。在作品内实现用户登录、展示昵称头像、查询游玩/购买权限（章节锁）、安全返回社区、进入全屏或响应播放页静音时使用。平台自动注入 SDK 脚本，严禁手动引入或打包 SDK 文件。当前无云存档、无内购接口。
 ---
 
-# 播放页 SDK（CgMakerSdk）
+# 播放页 SDK（LumiMakerSdk）
 
-作品发布后，将在幻光文游社区的**播放页**（宿主环境）内通过 iframe 运行。宿主环境会在全局自动注入 `window.CgMakerSdk` 对象，为作品提供登录验证、用户信息读取、作品购买/游玩权限查询、安全跳转以及全屏播放等能力。
+作品发布后，在幻光文游社区的**播放页**（宿主）里通过 iframe 运行。平台会在玩法 HTML 里注入脚本，全局对象是 **`window.LumiMakerSdk`**（当前脚本版本 `0.1.10`）。作品用它做登录、读用户、查作品权限、安全跳转、全屏。播放页静音由脚本自动处理本页 `audio` / `video` / `AudioContext`，不必先调 API。
 
 > **核心原则**：
-> 1. **严禁在工程中引入 SDK 文件**：平台在发布时会自动将 SDK 注入作品 HTML。**切勿**下载 `lumimaker-game.js`、**切勿**拷进 `dist/` 或源码、**切勿**手动编写 `<script src="...lumimaker-game.js">`。
-> 2. **SDK 不负责画面渲染**：作品的画布、UI 与核心玩法逻辑完全由您自己的代码绘制。
-> 3. **本地开发无宿主**：本地使用 `npm run dev` 预览时无宿主环境，`ready()` 握手超时属于正常现象，无需进行 mock。
+> 1. **严禁在工程中引入 SDK 文件**：发布时平台注入。**切勿**下载 `lumimaker-game.js`、**切勿**拷进 `dist/` 或源码、**切勿**手写 `<script src="...lumimaker-game.js">`。
+> 2. **SDK 不负责画面渲染**：画布、UI 与玩法由作品自己画。
+> 3. **本地 `npm run dev` 无宿主**：`ready()` 约 5 秒后 `ready: false`，`error` 为「等待主站数据超时」，属正常。不要 mock 登录或假用户。
+> 4. **当前一期没有云存档、没有内购/下单接口**。不要承诺「SDK 会帮你存进度、买章节」。
+
+脚本加载后会判定容器：只允许在**社区播放页 iframe**或**官方 App**里玩。用浏览器地址栏直接打开托管页、或被第三方站点嵌套，会跳到社区作品帖（拿不到帖则空白页）。这是客户端劝阻，卸掉脚本即可绕过；真正鉴权仍在宿主。错误文案：「请在幻光社区或官方 App 中打开」。
 
 ---
 
 ## 1. 适用场景
 
-- **用户信息与登录**：需要在作品内唤起社区登录、展示玩家昵称/头像，或保存玩家专属云端进度。
-- **权限与章节锁**：根据用户是否已购买或是否拥有游玩权限，控制后续关卡锁或自制试玩结束提示。
-- **页面导航与全屏**：在作品界面提供“返回社区首页”、“查看作者主页”、“返回上一页”或“切换全屏”按钮。
-- **环境疑问解答**：确认 SDK 是否需要 npm 安装、文件存放位置等疑问（无需安装，平台运行时注入）。
+- **用户信息与登录**：唤起社区登录、展示昵称/头像。未登录的试玩仍可玩离线内容。
+- **权限与章节锁**：读 `queryGame()` 的 `can_play` / `purchased`，画作品**自己的**关卡锁或试玩结束提示。正式版未获权时播放页会盖购买遮罩，**根本不会加载**作品 iframe。
+- **安全跳转与全屏**：回社区首页、作者页、上一页；进入/退出播放器全屏壳。公开 API **没有** `toggleFullscreen()`。
+- **播放页静音**：宿主拨静音后脚本已自动静音本页媒体。可选 `isMuted()` / `onMuteChange()`。
+
+不要用本 skill 讲发版命令；发版看 `lumimaker`。
 
 ---
 
 ## 2. 快速接入示例
 
-在作品代码中，仅通过 `window.CgMakerSdk` 与宿主进行通信。**切勿使用原生 `postMessage`，切勿尝试读取或操作 token**。
+只通过 `window.LumiMakerSdk` 与宿主通信。**不要**自己 `postMessage`，**不要**读 token。
 
 ```js
-// 初始化并连接宿主播放页
 async function initPlaySdk() {
-  const sdk = window.CgMakerSdk
-  if (!sdk) {
-    // 本地开发预览，或当前页面未运行在社区播放页中
-    return null
-  }
+  const sdk = window.LumiMakerSdk
+  if (!sdk) return null
 
-  // 1. 与宿主建立握手（约 5 秒超时，超时不会抛出异常，而是返回 ready: false）
   const { ready, context, error } = await sdk.ready()
   if (!ready) {
-    console.debug('未连接到宿主环境（本地预览时此情况属正常现象）：', error)
+    console.debug('未连接到宿主（本地预览正常）：', error)
     return null
   }
 
-  // 2. 检查并按需请求登录（如未登录，引导用户唤起社区登录弹窗）
   if (!sdk.isLoggedIn()) {
     try {
       await sdk.requireLogin()
     } catch (err) {
-      if (err && err.code === 'LOGIN_CANCELLED') {
-        // 用户主动关闭了登录弹窗，作品可继续以访客模式运行
-        console.log('用户取消了登录')
-        return null
-      }
+      if (err && err.code === 'LOGIN_CANCELLED') return null
       throw err
     }
   }
 
-  // 3. 查询当前作品在社区的发布信息与权限
   const gameInfo = await sdk.queryGame()
-  // 可根据 gameInfo.can_play / gameInfo.purchased 控制作品内的章节锁等自制 UI
-  // 注意：切勿使用 gameInfo.play_url 强行进行页面重定向
+  // 用 gameInfo.can_play / gameInfo.purchased 画自制章节锁
+  // 不要用 gameInfo.play_url 跳转；不要把播放地址或关联帖 ID 念给玩家
 
-  // 4. 监听环境与登录态变化（如用户在外部切换语言或完成登录）
-  const unbind = sdk.onChange((nextContext) => {
-    // 收到环境变化，在此处刷新作品内的个人信息或文案
+  const unbind = sdk.onChange(() => {
+    // 登录态变化时刷新 UI。现网宿主尚未推送语言变更。
   })
 
   return { sdk, context, gameInfo, unbind }
 }
 
-// 页面加载完成后调用
 initPlaySdk().then((host) => {
   if (!host) return
-
-  // 示例：按钮点击事件绑定
-  // document.getElementById('btn-home').onclick = () => host.sdk.navigateHome()
-  // document.getElementById('btn-author').onclick = () => host.sdk.navigateAuthorPage()
-  // document.getElementById('btn-back').onclick = () => host.sdk.navigateBack()
-  // document.getElementById('btn-fullscreen').onclick = () => host.sdk.requestFullscreen()
-
-  // 页面卸载或组件销毁时，解除监听
-  // window.addEventListener('unload', () => host.unbind())
+  // host.sdk.navigateHome()
+  // host.sdk.navigateAuthorPage()
+  // host.sdk.navigateBack()
+  // host.sdk.requestFullscreen()
+  // host.sdk.exitFullscreen()
 })
 ```
 
@@ -89,24 +77,28 @@ initPlaySdk().then((host) => {
 
 ## 3. TypeScript 类型声明（可选）
 
-若使用 TypeScript 开发，可将以下全局声明加入项目声明文件（如 `src/env.d.ts`）：
+可放进 `src/env.d.ts`：
 
 ```ts
 export {}
 
 declare global {
   interface Window {
-    CgMakerSdk?: {
+    LumiMakerSdk?: {
       version: string
-      ready(): Promise<{ ready: boolean; context: CgMakerContext | null; error?: string }>
+      ready(): Promise<{ ready: boolean; context: LumiMakerContext | null; error?: string }>
       isReady(): boolean
-      getError(): string | null
-      getContext(): CgMakerContext | null
-      onChange(fn: (context: CgMakerContext) => void): () => void
+      getError(): string
+      getContext(): LumiMakerContext | null
+      getGameId(): string
+      getUser(): LumiMakerUser | null
       isLoggedIn(): boolean
+      onChange(fn: (context: LumiMakerContext | null) => void): () => void
+      isMuted(): boolean
+      onMuteChange(fn: (muted: boolean) => void): () => void
       requireLogin(): Promise<void>
-      queryGame(): Promise<CgMakerGameInfo>
-      queryUser(): Promise<CgMakerUserInfo>
+      queryGame(): Promise<LumiMakerGameInfo>
+      queryUser(): Promise<LumiMakerUser>
       navigateHome(): void
       navigateAuthorPage(): void
       navigateBack(): void
@@ -115,26 +107,28 @@ declare global {
     }
   }
 
-  interface CgMakerContext {
+  interface LumiMakerContext {
     gameId: string
     lang: string
-    user: CgMakerUserInfo | null
-    variant: 1 | 2 | 3 // 1 正式版 · 2 试玩版 · 3 衍生版
+    user: LumiMakerUser | null
+    variant: 1 | 2 | 3
+    parentOrigin: string
   }
 
-  interface CgMakerUserInfo {
+  interface LumiMakerUser {
     username: string
     nickname: string
     avatar: string
   }
 
-  interface CgMakerGameInfo {
+  interface LumiMakerGameInfo {
     game_id: string
     owner: string
     name: string
     summary: string
     cover_url: string
     variant: number
+    parent_game_id: string
     can_play: boolean
     purchased: boolean
     play_url: string
@@ -142,29 +136,21 @@ declare global {
 }
 ```
 
+`parentOrigin` 只给 SDK 校验消息来源，作品业务不要用。`getGameId()` 未握手时是空字符串。`getError()` 无失败时是空字符串。
+
 ---
 
 ## 4. 核心规范与操作红线
 
-1. **宿主注入与源码纯净**：
-   - **绝对不要**将 `lumimaker-game.js` 文件放入工程或产物目录中。
-   - **绝对不要**在 HTML 中手动写 `<script src="...lumimaker-game.js">`，发版时系统会自动安全注入。
-2. **安全通信边界**：
-   - 严禁自行调用 `window.parent.postMessage`，严禁尝试向父级页面读取、打印或篡改鉴权 token。
-   - 严禁在作品内自行实现社区账号登录、签发 token、创建订单或支付逻辑，所有交互均通过 SDK 提供的标准方法交由宿主承接。
-3. **页面导航红线**：
-   - 严禁使用 `window.top.location` 进行整页重定向。
-   - 页面返回与跳转必须且仅能调用 `navigateHome()`、`navigateAuthorPage()`、`navigateBack()` 等无参方法，切勿向方法中传递自定义 URL。
-   - 切勿使用 `queryGame()` 返回的 `play_url` 进行跳转。
-4. **权限与购买体验**：
-   - 正式版作品未获游玩授权时，宿主播放页会自动覆盖平台购买界面，根本不会加载作品 iframe。
-   - 作品内只需根据 `can_play` / `purchased` 处理“已经进入作品后”的章节锁或提示，**切勿在作品内自制并复刻社区的购买结算弹窗**。
-5. **本地开发调试预期**：
-   - 本地 `npm run dev` 阶段不存在宿主环境，`sdk.ready()` 握手超时为正常情况，请做好判空保护，**不要在本地伪造假登录或假用户数据**。
-   - 作品内的图片、音效、字体等资源依然遵循工程本地化原则，严禁使用 SDK 请求未经打包的在线 CDN 资源。
+1. **不要把 SDK 打进工程**：不要放 `lumimaker-game.js`，不要手写 script 标签。发版会注入玩法 HTML（`index.html`；若已有语言/方向页也会注入那些页）。
+2. **通信边界**：不要 `window.parent.postMessage`，不要读、打印、改 token。不要自己调社区登录、签发 token、下单、支付。
+3. **跳转**：只用 `navigateHome()` / `navigateAuthorPage()` / `navigateBack()`，不要传 URL，不要 `window.top.location`。不要用 `queryGame()` 的 `play_url` 跳转。对玩家只展示帖子链接（若发版卡片有），不要念播放页地址、作品 ID、关联帖 ID。
+4. **购买**：正式版未获权时播放页遮罩，iframe 不会开。作品内只处理「已经进来之后」的自制锁，不要复刻社区购买墙。
+5. **本地预览**：无宿主时 `ready()` 失败正常。不要伪造登录。图音字体继续用工程本地文件。
+6. **没有这些能力**：云存档、内购、查权买断、游戏自己切静音宿主（宿主推静音；作品只可选监听）。
 
 ---
 
 ## 5. API 完整参考
 
-详细的方法签名、字段解释与错误码对照表，请查阅 [API 接口规范细则](references/api.md)。
+方法签名、字段与错误码见 [API 接口规范细则](references/api.md)。

package/skill/lumimaker-play-sdk/references/api.md

@@ -1,100 +1,119 @@
-# CgMakerSdk 接口规范细则
+# LumiMakerSdk 接口规范细则
 
-全局挂载对象为 `window.CgMakerSdk`。当作品发布到平台并在社区播放页（iframe）中运行时，平台宿主会自动将此对象注入到全局环境中。
+全局对象为 **`window.LumiMakerSdk`**。发布到幻光文游社区后，在社区播放页的 iframe（或官方 App 打开的受信壳）里运行时，平台注入该对象。脚本版本见 `version`（当前 `0.1.10`）。
+
+失败时抛出的错误对象名为 **`LumiMakerError`**，带 `code` 字符串。
+
+作品不要自己 `postMessage`，不要读 token，不要带 Cookie 调社区接口。
 
 ---
 
 ## 1. 生命周期与上下文
 
-### 1.1 核心方法
-
-| 方法 / 属性 | 返回类型 | 功能与使用说明 |
+| 方法 / 属性 | 返回类型 | 说明 |
 |---|---|---|
-| `version` | string | 当前 SDK 脚本的版本号字符串（如 `"0.1.0"`）。 |
-| `ready()` | `Promise<{ ready: boolean; context: CgMakerContext \| null; error?: string }>` | 与宿主播放页握手建立连接。<br>• 握手超时时间约为 5 秒。<br>• **超时不会抛出异常**，而是返回 `ready: false`，并在 `error` 字段中说明“等待主站数据超时”（本地预览时属正常表现）。 |
-| `isReady()` | boolean | 检查当前是否已成功完成握手并获取到环境上下文。 |
-| `getError()` | string \| null | 获取最近一次握手失败的具体错误信息。 |
-| `getContext()` | CgMakerContext \| null | 直接获取当前环境上下文对象（未握手成功时返回 `null`）。上下文内不包含敏感 token。 |
-| `onChange(fn)` | `() => void` | 监听环境上下文或用户登录态的变化（如外部切换了语言或登录状态改变）。<br>• 参数 `fn` 接收最新的 `context` 对象。<br>• **必须保存并调用该方法的返回值以取消事件监听**，避免组件销毁后造成内存泄漏。 |
-| `isLoggedIn()` | boolean | 快捷检查当前是否已有用户登录态。 |
-| `getGameId()` | string \| null | 快捷获取当前作品的唯一标识 ID。 |
-| `getUser()` | CgMakerUserInfo \| null | 快捷获取当前已登录用户的基本信息。 |
-
-### 1.2 环境上下文对象 (`CgMakerContext`)
-
-调用 `getContext()` 或握手成功后返回的上下文结构如下：
+| `version` | string | 脚本版本，如 `"0.1.10"`。 |
+| `ready()` | `Promise<{ ready: boolean; context: LumiMakerContext \| null; error?: string }>` | 与播放页握手。约 5 秒超时。**超时不 throw**，返回 `ready: false`。受信壳超时 `error` 为「等待主站数据超时」（本地预览正常）。未受信容器立刻失败，`error` 为「请在幻光社区或官方 App 中打开」，并跳到社区作品帖。 |
+| `isReady()` | boolean | 是否已拿到 context。 |
+| `getError()` | string | 最近一次握手失败文案；无失败时为空字符串。不是所有通道错误都会写入。 |
+| `getContext()` | LumiMakerContext \| null | 公开上下文。无 token、无 api 地址。 |
+| `getGameId()` | string | 便捷读取；未握手为空字符串。 |
+| `getUser()` | LumiMakerUser \| null | 便捷读取当前用户。 |
+| `isLoggedIn()` | boolean | 等价于是否已有 `getUser()`。 |
+| `onChange(fn)` | `() => void` | context / 登录变化。`fn` 可能收到 `null`。必须用返回值取消监听。语言仅在宿主推语言消息时变；**现网播放页尚未推这条**。 |
+| `isMuted()` | boolean | 播放页静音开关，默认 `false`。不进 `getContext()`。脚本加载后已自动听宿主并静音本页媒体，**不必调用**。 |
+| `onMuteChange(fn)` | `() => void` | 宿主静音状态变化时回调。必须用返回值取消监听。 |
+
+### 1.1 `getContext()` 字段
 
 | 字段 | 类型 | 说明 |
 |---|---|---|
-| `gameId` | string | 当前作品在平台上的全局作品 ID。 |
-| `lang` | string | 播放页当前的语言代码（如 `"zh"`、`"en"` 等）。 |
-| `user` | object \| null | 当前登录的用户信息对象（未登录时为 `null`），包含 `username`、`nickname`、`avatar`。 |
-| `variant` | number | 当前作品的版本形态：`1` 正式版 · `2` 试玩版（demo） · `3` 衍生版。 |
-| `parentOrigin` | string | 仅供 SDK 内部验证跨域消息来源的安全字段，作品业务逻辑切勿依赖此字段。 |
+| `gameId` | string | 当前作品对外 id。 |
+| `lang` | string | 握手时播放页语言。 |
+| `user` | object \| null | `{ username, nickname, avatar }`；未登录为 `null`。`username` 来自社区用户 id。 |
+| `variant` | number | `1` 正式 · `2` 试玩（demo） · `3` 衍生。 |
+| `parentOrigin` | string | 仅供 SDK 校验消息来源，作品业务不要用。 |
 
 ---
 
-## 2. 账号与登录认证
+## 2. 登录
 
-| 方法 | 返回类型 | 功能与使用说明 |
+| 方法 | 返回类型 | 说明 |
 |---|---|---|
-| `requireLogin()` | `Promise<void>` | 要求用户进行登录。<br>• 若当前已处于登录状态，Promise 将立即以成功状态 resolve。<br>• 若当前未登录，宿主将弹出社区官方登录窗口。<br>• 若用户主动关闭或取消登录窗口，Promise 将以带有错误码 `LOGIN_CANCELLED` 的异常 reject。 |
+| `requireLogin()` | `Promise<void>` | 已登录立刻成功。否则请播放页弹出社区登录。用户取消 → `LOGIN_CANCELLED`。未受信壳会先抛 `UNTRUSTED_SHELL`。 |
 
-> **提示**：未登录时，试玩版（demo）通常仍允许玩家离线体验基础内容；但此时调用 `queryGame()` 或 `queryUser()` 均会抛出 `NOT_LOGGED_IN` 错误。
+未登录时试玩 iframe 仍可玩离线内容。无 token 时 `queryGame()` / `queryUser()` 得到 `NOT_LOGGED_IN`。
 
 ---
 
-## 3. 作品与用户信息查询
+## 3. 查询（须已登录）
 
-调用查询接口前，必须已处于登录状态，否则接口将返回错误码 `NOT_LOGGED_IN`。**严禁在作品内自行携带 Cookie 请求社区后端接口**。
+游戏自己发 HTTP，`credentials: 'omit'`，只打平台 `/v1/game-sdk/*`。`game_id` 由 token 绑定，不要自己拼查询参数。
 
-| 方法 | 返回类型 | 功能与使用说明 |
+| 方法 | 返回类型 | 说明 |
 |---|---|---|
-| `queryGame()` | `Promise<CgMakerGameInfo>` | 查询当前作品在平台的发布信息、价格及游玩授权状态。 |
-| `queryUser()` | `Promise<CgMakerUserInfo>` | 查询当前已登录用户的详细个人资料（包含 `username`、`nickname`、`avatar`）。 |
+| `queryGame()` | `Promise<LumiMakerGameInfo>` | 当前作品货架与权限。SDK 原样返回服务端对象，不做字段校验。 |
+| `queryUser()` | `Promise<LumiMakerUser>` | `username`、`nickname`、`avatar`。 |
 
-### `queryGame()` 返回常用字段一览
+### `queryGame()` 字段
 
-| 字段名称 | 数据类型 | 说明与业务指引 |
+| 字段 | 类型 | 说明 |
 |---|---|---|
-| `game_id` | string | 作品 ID。 |
-| `name` | string | 作品在平台显示的名称。 |
-| `owner` | string | 作品作者的平台用户名。 |
-| `summary` | string | 作品简介摘要。 |
-| `cover_url` | string | 封面图地址。 |
-| `variant` | number | 作品形态：`1` 正式版 · `2` 试玩版。 |
-| `parent_game_id`| string \| null | 若为试玩版，对应关联的正式版作品 ID。 |
-| `price_flower` | number | 作品标价（鲜花数）。 |
-| `price_cny` | number | 作品人民币售价（分）。 |
-| `status` | number | 作品状态：`1` 正常启用 · `2` 已禁用。 |
-| `purchased` | boolean | 当前登录用户是否已购买该可售作品（未购买时为 `false`）。 |
-| `can_play` | boolean | 当前用户当前是否具备游玩权限。作品可用此字段控制后续章节锁。 |
-| `play_url` | string | 播放链接。**严禁使用此 URL 自行进行页面重定向**。 |
+| `game_id` | string | 作品 id。不要把原始 id 念给玩家。 |
+| `owner` | string | 作者用户名。 |
+| `name` | string | 平台显示名。 |
+| `summary` | string | 简介。 |
+| `cover_url` | string | 封面地址。 |
+| `variant` | number | `1` 正式 · `2` 试玩 · `3` 衍生。 |
+| `parent_game_id` | string | 试玩 / 衍生关联的正式版 id；没有则为空字符串。 |
+| `price_flower` / `price_cny` / `price_usd` | number | 标价。作品内不要用它们复刻社区购买墙。 |
+| `latest_version_no` | number | 平台最新版本序号。不要把版本 ID 念给玩家。 |
+| `play_url` | string | 托管播放地址。**严禁用此 URL 跳转**；也不要念给玩家。 |
+| `post_id` | string | 关联主帖 id；demo 与正式版共用；无则为空字符串。不要念给玩家。 |
+| `status` | number | 货架 `1` 启用 / `2` 禁用。 |
+| `purchased` | boolean | 对该可售主体是否有已支付订单；作者未下单为 `false`。 |
+| `can_play` | boolean | 能拿到 token 时为 `true`。用来画自制章节锁。 |
+| `ai_model` / `engine` / `languages` / `orientations` / `play_duration` | 可选 | 可能缺省。 |
+
+自制 UI 读 `can_play` / `purchased`。正式版未获权时播放页不会加载 iframe。
 
 ---
 
-## 4. 页面导航与全屏控制
+## 4. 安全跳转与全屏
 
-为保证运行沙箱安全，页面跳转与全屏控制**只允许调用以下无参方法**。严禁直接操作 `window.top.location`，切勿向这些方法中传入自定义 URL。
+只允许下列无参方法。不要操作 `window.top.location`，不要传入自定义 URL。公开 API **没有** `toggleFullscreen()`（协议里宿主可认全屏 `toggle`，游戏不要调）。
 
-| 方法 | 返回类型 | 功能与说明 |
+| 方法 | 返回类型 | 说明 |
 |---|---|---|
-| `navigateHome()` | void | 触发播放器外壳返回幻光文游社区首页。 |
-| `navigateAuthorPage()`| void | 触发播放器外壳打开该作品作者的社区个人主页。 |
-| `navigateBack()` | void | 触发返回上一级页面（若外壳无上一页历史，默认返回作品社区帖子）。 |
-| `requestFullscreen()`| `Promise<void>` | 请求将**播放器整体外壳**切换至全屏状态（全屏由外壳容器承接，作品无需自改样式）。 |
-| `exitFullscreen()` | `Promise<void>` | 请求退出播放器外壳的全屏状态。 |
+| `navigateHome()` | void | 播放页回社区首页。 |
+| `navigateAuthorPage()` | void | 打开作者页。 |
+| `navigateBack()` | void | 有历史则后退，否则回作品帖。 |
+| `requestFullscreen()` | `Promise<void>` | 全屏**播放器外壳**，不是游戏改 `top`。须在真实点击等手势里调用。 |
+| `exitFullscreen()` | `Promise<void>` | 退出播放器全屏。 |
 
----
+浏览器拒绝全屏 → `FULLSCREEN_DENIED`。
 
-## 5. 错误码与异常处理
+---
 
-当 SDK 方法调用失败时，抛出的错误对象（`CgMakerError`）通常包含 `code` 属性。常见错误码对照如下：
+## 5. 错误码
 
-| 错误代码 (`code`) | 触发场景 | 推荐处理方案 |
+| `code` | 何时 | 处理 |
 |---|---|---|
-| `NOT_LOGGED_IN` | 当前用户未登录，或调用 `queryGame` / `queryUser` 时鉴权未通过。 | 引导调用 `requireLogin()` 完成登录，或在作品内提示访客限制。 |
-| `LOGIN_CANCELLED` | 唤起登录窗口后，用户主动点击关闭或取消。 | 视为非致命取消操作，允许玩家继续游玩未锁定关卡或保留在当前界面。 |
-| `TIMEOUT` | 跨窗口握手通信超时或请求宿主桥接超时（注：`ready()` 超时仅返回 `ready: false`，不抛出本错误）。 | 检查运行环境是否处于沙箱异常状态，做好容错兜底。 |
-| `FULLSCREEN_DENIED`| 浏览器安全策略拦截全屏请求（例如未在真实用户点击手势内调用）。 | 确保仅在按钮的 `click` 等显式手势回调中调用 `requestFullscreen()`。 |
-| `FAILED` | 其他未知系统级或通信层错误。 | 记录调试日志，对用户展示通用重试提示。 |
+| `NOT_LOGGED_IN` | 无 token，或查询鉴权失败 | 需要登录时再 `requireLogin()`；试玩可继续离线。 |
+| `LOGIN_CANCELLED` | 用户关掉登录 | 非致命，留在当前界面。 |
+| `TIMEOUT` | 握手或桥接超时。**`ready()` 超时只返回 `ready: false`，不 throw 本码** | 本地预览按未连接处理。 |
+| `FULLSCREEN_DENIED` | 浏览器拒绝全屏 | 只在用户点击里请求全屏。 |
+| `UNTRUSTED_SHELL` | 不在社区播放页 iframe / 官方 App | 提示在幻光社区或官方 App 打开。 |
+| `FAILED` | 其它业务或通信失败 | 通用重试提示；不要把内部报文念给玩家。 |
+
+---
+
+## 6. 容器（作者需要知道的行为）
+
+| 环境 | 行为 |
+|---|---|
+| 社区播放页 iframe | 正常握手。 |
+| 官方 App（本窗有官方桥） | 不跳走。没有播放页 Host 时 `ready()` 仍超时，离线可玩。 |
+| 浏览器地址栏直开托管页，或第三方站点嵌套 | 跳到社区作品帖；拿不到帖则空白页。 |
+
+不要把「直开托管地址」当成正规玩法入口。本地预览请继续 `npm run dev`，或嵌在社区播放页 / 官方 App。