@66rpg/lumimaker 0.1.37 → 0.1.39

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

@@ -1,100 +1,100 @@
-# CgMakerSdk 接口规范细则
-
-全局挂载对象为 `window.CgMakerSdk`。当游戏发布到平台并在社区播放页（iframe）中运行时，平台宿主会自动将此对象注入到全局环境中。
-
----
-
-## 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()` 或握手成功后返回的上下文结构如下：
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `gameId` | string | 当前作品在平台上的全局游戏 ID。 |
-| `lang` | string | 播放页当前的语言代码（如 `"zh"`、`"en"` 等）。 |
-| `user` | object \| null | 当前登录的用户信息对象（未登录时为 `null`），包含 `username`、`nickname`、`avatar`。 |
-| `variant` | number | 当前作品的版本形态：`1` 正式版 · `2` 试玩版（demo） · `3` 衍生版。 |
-| `parentOrigin` | string | 仅供 SDK 内部验证跨域消息来源的安全字段，游戏业务逻辑切勿依赖此字段。 |
-
----
-
-## 2. 账号与登录认证
-
-| 方法 | 返回类型 | 功能与使用说明 |
-|---|---|---|
-| `requireLogin()` | `Promise<void>` | 要求用户进行登录。<br>• 若当前已处于登录状态，Promise 将立即以成功状态 resolve。<br>• 若当前未登录，宿主将弹出社区官方登录窗口。<br>• 若用户主动关闭或取消登录窗口，Promise 将以带有错误码 `LOGIN_CANCELLED` 的异常 reject。 |
-
-> **提示**：未登录时，试玩版（demo）通常仍允许玩家离线体验基础内容；但此时调用 `queryGame()` 或 `queryUser()` 均会抛出 `NOT_LOGGED_IN` 错误。
-
----
-
-## 3. 游戏与用户信息查询
-
-调用查询接口前，必须已处于登录状态，否则接口将返回错误码 `NOT_LOGGED_IN`。**严禁在游戏内自行携带 Cookie 请求社区后端接口**。
-
-| 方法 | 返回类型 | 功能与使用说明 |
-|---|---|---|
-| `queryGame()` | `Promise<CgMakerGameInfo>` | 查询当前游戏作品在平台的发布信息、价格及游玩授权状态。 |
-| `queryUser()` | `Promise<CgMakerUserInfo>` | 查询当前已登录用户的详细个人资料（包含 `username`、`nickname`、`avatar`）。 |
-
-### `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 自行进行页面重定向**。 |
-
----
-
-## 4. 页面导航与全屏控制
-
-为保证运行沙箱安全，页面跳转与全屏控制**只允许调用以下无参方法**。严禁直接操作 `window.top.location`，切勿向这些方法中传入自定义 URL。
-
-| 方法 | 返回类型 | 功能与说明 |
-|---|---|---|
-| `navigateHome()` | void | 触发播放器外壳返回幻光社区首页。 |
-| `navigateAuthorPage()`| void | 触发播放器外壳打开该作品作者的社区个人主页。 |
-| `navigateBack()` | void | 触发返回上一级页面（若外壳无上一页历史，默认返回作品社区帖子）。 |
-| `requestFullscreen()`| `Promise<void>` | 请求将**播放器整体外壳**切换至全屏状态（全屏由外壳容器承接，游戏无需自改样式）。 |
-| `exitFullscreen()` | `Promise<void>` | 请求退出播放器外壳的全屏状态。 |
-
----
-
-## 5. 错误码与异常处理
-
-当 SDK 方法调用失败时，抛出的错误对象（`CgMakerError`）通常包含 `code` 属性。常见错误码对照如下：
-
-| 错误代码 (`code`) | 触发场景 | 推荐处理方案 |
-|---|---|---|
-| `NOT_LOGGED_IN` | 当前用户未登录，或调用 `queryGame` / `queryUser` 时鉴权未通过。 | 引导调用 `requireLogin()` 完成登录，或在游戏内提示访客限制。 |
-| `LOGIN_CANCELLED` | 唤起登录窗口后，用户主动点击关闭或取消。 | 视为非致命取消操作，允许玩家继续游玩未锁定关卡或保留在当前界面。 |
-| `TIMEOUT` | 跨窗口握手通信超时或请求宿主桥接超时（注：`ready()` 超时仅返回 `ready: false`，不抛出本错误）。 | 检查运行环境是否处于沙箱异常状态，做好容错兜底。 |
-| `FULLSCREEN_DENIED`| 浏览器安全策略拦截全屏请求（例如未在真实用户点击手势内调用）。 | 确保仅在按钮的 `click` 等显式手势回调中调用 `requestFullscreen()`。 |
-| `FAILED` | 其他未知系统级或通信层错误。 | 记录调试日志，对用户展示通用重试提示。 |
+# CgMakerSdk 接口规范细则
+
+全局挂载对象为 `window.CgMakerSdk`。当作品发布到平台并在社区播放页（iframe）中运行时，平台宿主会自动将此对象注入到全局环境中。
+
+---
+
+## 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()` 或握手成功后返回的上下文结构如下：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `gameId` | string | 当前作品在平台上的全局作品 ID。 |
+| `lang` | string | 播放页当前的语言代码（如 `"zh"`、`"en"` 等）。 |
+| `user` | object \| null | 当前登录的用户信息对象（未登录时为 `null`），包含 `username`、`nickname`、`avatar`。 |
+| `variant` | number | 当前作品的版本形态：`1` 正式版 · `2` 试玩版（demo） · `3` 衍生版。 |
+| `parentOrigin` | string | 仅供 SDK 内部验证跨域消息来源的安全字段，作品业务逻辑切勿依赖此字段。 |
+
+---
+
+## 2. 账号与登录认证
+
+| 方法 | 返回类型 | 功能与使用说明 |
+|---|---|---|
+| `requireLogin()` | `Promise<void>` | 要求用户进行登录。<br>• 若当前已处于登录状态，Promise 将立即以成功状态 resolve。<br>• 若当前未登录，宿主将弹出社区官方登录窗口。<br>• 若用户主动关闭或取消登录窗口，Promise 将以带有错误码 `LOGIN_CANCELLED` 的异常 reject。 |
+
+> **提示**：未登录时，试玩版（demo）通常仍允许玩家离线体验基础内容；但此时调用 `queryGame()` 或 `queryUser()` 均会抛出 `NOT_LOGGED_IN` 错误。
+
+---
+
+## 3. 作品与用户信息查询
+
+调用查询接口前，必须已处于登录状态，否则接口将返回错误码 `NOT_LOGGED_IN`。**严禁在作品内自行携带 Cookie 请求社区后端接口**。
+
+| 方法 | 返回类型 | 功能与使用说明 |
+|---|---|---|
+| `queryGame()` | `Promise<CgMakerGameInfo>` | 查询当前作品在平台的发布信息、价格及游玩授权状态。 |
+| `queryUser()` | `Promise<CgMakerUserInfo>` | 查询当前已登录用户的详细个人资料（包含 `username`、`nickname`、`avatar`）。 |
+
+### `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 自行进行页面重定向**。 |
+
+---
+
+## 4. 页面导航与全屏控制
+
+为保证运行沙箱安全，页面跳转与全屏控制**只允许调用以下无参方法**。严禁直接操作 `window.top.location`，切勿向这些方法中传入自定义 URL。
+
+| 方法 | 返回类型 | 功能与说明 |
+|---|---|---|
+| `navigateHome()` | void | 触发播放器外壳返回幻光文游社区首页。 |
+| `navigateAuthorPage()`| void | 触发播放器外壳打开该作品作者的社区个人主页。 |
+| `navigateBack()` | void | 触发返回上一级页面（若外壳无上一页历史，默认返回作品社区帖子）。 |
+| `requestFullscreen()`| `Promise<void>` | 请求将**播放器整体外壳**切换至全屏状态（全屏由外壳容器承接，作品无需自改样式）。 |
+| `exitFullscreen()` | `Promise<void>` | 请求退出播放器外壳的全屏状态。 |
+
+---
+
+## 5. 错误码与异常处理
+
+当 SDK 方法调用失败时，抛出的错误对象（`CgMakerError`）通常包含 `code` 属性。常见错误码对照如下：
+
+| 错误代码 (`code`) | 触发场景 | 推荐处理方案 |
+|---|---|---|
+| `NOT_LOGGED_IN` | 当前用户未登录，或调用 `queryGame` / `queryUser` 时鉴权未通过。 | 引导调用 `requireLogin()` 完成登录，或在作品内提示访客限制。 |
+| `LOGIN_CANCELLED` | 唤起登录窗口后，用户主动点击关闭或取消。 | 视为非致命取消操作，允许玩家继续游玩未锁定关卡或保留在当前界面。 |
+| `TIMEOUT` | 跨窗口握手通信超时或请求宿主桥接超时（注：`ready()` 超时仅返回 `ready: false`，不抛出本错误）。 | 检查运行环境是否处于沙箱异常状态，做好容错兜底。 |
+| `FULLSCREEN_DENIED`| 浏览器安全策略拦截全屏请求（例如未在真实用户点击手势内调用）。 | 确保仅在按钮的 `click` 等显式手势回调中调用 `requestFullscreen()`。 |
+| `FAILED` | 其他未知系统级或通信层错误。 | 记录调试日志，对用户展示通用重试提示。 |

package/skill/lumimaker-template-spec/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: lumimaker-template-spec
-description: 幻光 lumimaker 模板工程规范。用户准备发布模板、做模板、询问工程是否符合模板规范，或调整模板目录、scripts 脚本、package.json 字段与 dist 产物时使用。不符合时对照模板规范协议调整适配。
+description: 幻光文游社区模板工程规范。用户准备发布模板、做模板、询问工程是否符合模板规范，或调整模板目录、scripts 脚本、package.json 字段与 dist 产物时使用。不符合时对照模板规范协议调整适配。
 ---
 
 # 模板规范指引
 
-本技能用于验证当前工程是否符合幻光平台模板规范，并在不合规时引导进行标准化调整。
+本技能用于验证当前工程是否符合幻光文游社区模板规范，并在不合规时引导进行标准化调整。
 
 所有硬性规则与格式要求均以 [模板规范协议](references/protocol.md) 为唯一事实来源。本技能仅提供操作流程与排查指引。
 

package/skill/lumimaker-template-spec/references/protocol.md

@@ -1,113 +1,113 @@
-# 幻光 lumimaker 模板规范协议
-
-| 项 | 内容 |
-|---|---|
-| 协议版本 | 1.0 |
-| 最新更新 | 2026-09-22 |
-| 修订日期 | 2026-09-22 |
-
-本协议约定幻光平台模板工程的基础结构、`package.json` 配置与构建产物要求。未在本文中列出的目录、文件与配置字段，均不属于本协议的约定范围。
-
-**约束用词定义**：
-- **必须**：模板工程必须满足的硬性要求，未满足则视为不合规。
-- **可选**：模板工程可自行决定是否提供；若提供，须符合本协议规定的格式。
-- **建议**：推荐的最佳实践做法，不作为合规与否的判断条件。
-
----
-
-## 1. 目录结构
-
-模板工程根目录即为项目的源码根目录。
-
-### 1.1 结构全景
-
-```text
-.
-├── package.json        # 必须：工程配置与脚本清单
-├── README.md           # 必须：模板使用说明（供人阅读）
-├── AGENTS.md           # 必须：AI 协同指南（说明工程结构与修改建议）
-├── src/                # 必须：模板源代码目录
-├── assets/             # 可选：模板资源目录（包含游戏数据、图片、音频等；若有资源放入此目录，也可没有任何资源，纯 index.html）
-└── skill/              # 可选：模板自带的玩法技能目录
-    └── SKILL.md        # 可选：供 AI 阅读的玩法说明
-```
-
-### 1.2 目录与文件说明
-
-| 路径 | 属性 | 作用与要求 |
-|---|---|---|
-| `package.json` | **必须** | 模板工程的包清单，声明平台展示名、英文标识、版本号、数据包版本与必要脚本。详见第 2 节。 |
-| `README.md` | **必须** | 供创作者阅读的工程说明与使用指引。 |
-| `AGENTS.md` | **必须** | 供 AI 助手阅读的协同指南，须明确说明工程组织方式与推荐的修改位置（若包含 `assets/` 须说明其子目录划分）。 |
-| `src/` | **必须** | 模板的完整源代码目录，不限制编程语言或开发框架（如 React、Vue、Pixi、原生 Canvas 均可）。 |
-| `assets/` | **可选** | 模板的资源目录（包含游戏数据、图片、音频、样式等）。若模板包含静态资源，统一存放于此；也可以没有任何资源文件或不创建此目录，工程最终可仅依赖纯 `index.html` 运行。 |
-| `skill/SKILL.md` | **可选** | 本模板特定的玩法技能说明文件，指导 AI 助手如何协助创作者调整游戏规则。若无独立玩法技能可不提供。 |
-
----
-
-## 2. package.json
-
-`package.json` 文件必须位于工程根目录，且内容为合法的 JSON 对象。
-
-### 2.1 基础配置字段
-
-所有字段集中约定如下：
-
-| 字段 | 属性 | 数据类型 | 格式与要求 | 示例 |
-|---|---|---|---|---|
-| `name` | **必须** | string | 平台展示名称，供人阅读，支持中文；去掉首尾空格后长度至少为 1；不能包含字符 `/` 或 `@`。 | `"趣味问答"`、`"quiz-react"` |
-| `slug` | **必须** | string | 模板英文短名，在平台中唯一标识本模板；格式须匹配 `^[a-z0-9][a-z0-9-]{0,62}$`。详见下方细则。 | `"quiz-react"` |
-| `version` | **必须** | string | 模板版本号；格式须匹配 `^(?=.{1,16}$)[a-z0-9]+(?:[.-][a-z0-9]+)*$`。详见下方细则。 | `"0.1.0"`、`"1.0.0-a"` |
-| `data_ver` | **必须** | string 或 number | 配套数据包版本；非空字符串或有限数字。详见下方细则。 | `"1"` 或 `1` |
-| `description` | **可选** | string | 模板简介说明。若省略，默认取值视为空字符串 `""`；若填写，允许为空字符串。 | `"基于 React 的题库答题游戏模板"` |
-
-#### 字段格式细则
-
-- **`slug`（英文短名）**
-  - 正则表达式：`^[a-z0-9][a-z0-9-]{0,62}$`
-  - 长度限制：1 至 63 个字符。
-  - 字符范围：仅允许小写英文字母（`a-z`）、数字（`0-9`）和连字符（`-`）。
-  - 起始字符：必须以小写字母或数字开头（首字符不能是连字符 `-`）。
-
-- **`version`（模板版本号）**
-  - 正则表达式：`^(?=.{1,16}$)[a-z0-9]+(?:[.-][a-z0-9]+)*$`
-  - 长度限制：1 至 16 个字符。
-  - 字符范围：仅允许小写英文字母（`a-z`）、数字（`0-9`）、英文点号（`.`）和连字符（`-`）。
-  - 边界要求：必须以小写字母或数字开头，且以小写字母或数字结尾。
-  - 连续符号限制：点号与连字符不能相邻或连续出现（例如禁止 `..`、`--`、`.-`、`-.`）。
-  - 合法示例：`0.1.0`、`1.0.0-a`、`1.0.0-rc1`。
-
-- **`data_ver`（数据包版本）**
-  - 当类型为字符串（string）时：去除首尾空白字符后，长度至少为 1。示例：`"1"`。
-  - 当类型为数字（number）时：必须为合法的有限数值。示例：`1`。
-
-### 2.2 必须脚本命令 (`scripts`)
-
-`package.json` 中的 `scripts` 字段必须为对象，且必须包含以下 5 个指定脚本。每个脚本对应的值必须为字符串，且去除首尾空白后不可为空。脚本的具体执行命令由模板自身的技术栈决定。
-
-| 脚本名称 | 属性 | 作用与要求 |
-|---|---|---|
-| `dev` | **必须** | 启动正式内容的本地开发服务。 |
-| `dev:demo` | **必须** | 启动试玩内容的本地开发服务。若模板未制作独立的试玩内容，命令可与 `dev` 保持完全一致。 |
-| `build` | **必须** | 构建正式版产物到根目录 `dist/`。详见第 3 节。 |
-| `build:demo` | **必须** | 构建试玩版产物到根目录 `dist/`。若模板未制作独立的试玩内容，命令可与 `build` 保持完全一致。 |
-| `validate` | **必须** | 执行模板自身的数据检查。若模板包含独立的试玩数据，此单条脚本须同时覆盖正式数据与试玩数据的校验。 |
-
----
-
-## 3. 构建产物 (dist/)
-
-构建产物用于静态托管与作品发布，统一约定如下：
-
-1. **产物目录**：`scripts.build` 与 `scripts.build:demo` 的输出目录必须是工程根目录下的 `dist/`，两者共用该目录。
-2. **入口文件**：`dist/` 根目录下**必须**产出 `index.html` 入口文件。可以仅产出纯 `index.html`，无需任何其他静态资源文件。
-3. **静态资源（建议）**：若构建产物包含 JavaScript、CSS、图片等静态资源，建议放置于与 `index.html` 同级的 `dist/assets/` 目录下。
-4. **其他产物**：除 `dist/index.html` 外，产物目录内的其他文件组织形式本协议不作强制限制。
-
----
-
-## 修订记录
-
-| 文档版本 | 修订日期 | 变更说明 |
-|---|---|---|
-| 1.0 | 2026-09-22 | 初始版本。明确工程目录结构、`package.json` 配置字段与脚本规范，以及 `dist/` 构建产物约定（assets 为可选，支持纯 index.html）。 |
+# 幻光文游社区模板规范协议
+
+| 项 | 内容 |
+|---|---|
+| 协议版本 | 1.0 |
+| 最新更新 | 2026-09-22 |
+| 修订日期 | 2026-09-22 |
+
+本协议约定幻光文游社区模板工程的基础结构、`package.json` 配置与构建产物要求。未在本文中列出的目录、文件与配置字段，均不属于本协议的约定范围。
+
+**约束用词定义**：
+- **必须**：模板工程必须满足的硬性要求，未满足则视为不合规。
+- **可选**：模板工程可自行决定是否提供；若提供，须符合本协议规定的格式。
+- **建议**：推荐的最佳实践做法，不作为合规与否的判断条件。
+
+---
+
+## 1. 目录结构
+
+模板工程根目录即为项目的源码根目录。
+
+### 1.1 结构全景
+
+```text
+.
+├── package.json        # 必须：工程配置与脚本清单
+├── README.md           # 必须：模板使用说明（供人阅读）
+├── AGENTS.md           # 必须：AI 协同指南（说明工程结构与修改建议）
+├── src/                # 必须：模板源代码目录
+├── assets/             # 可选：模板资源目录（包含作品数据、图片、音频等；若有资源放入此目录，也可没有任何资源，纯 index.html）
+└── skill/              # 可选：模板自带的玩法技能目录
+    └── SKILL.md        # 可选：供 AI 阅读的玩法说明
+```
+
+### 1.2 目录与文件说明
+
+| 路径 | 属性 | 作用与要求 |
+|---|---|---|
+| `package.json` | **必须** | 模板工程的包清单，声明平台展示名、英文标识、版本号、数据包版本与必要脚本。详见第 2 节。 |
+| `README.md` | **必须** | 供创作者阅读的工程说明与使用指引。 |
+| `AGENTS.md` | **必须** | 供 AI 助手阅读的协同指南，须明确说明工程组织方式与推荐的修改位置（若包含 `assets/` 须说明其子目录划分）。 |
+| `src/` | **必须** | 模板的完整源代码目录，不限制编程语言或开发框架（如 React、Vue、Pixi、原生 Canvas 均可）。 |
+| `assets/` | **可选** | 模板的资源目录（包含作品数据、图片、音频、样式等）。若模板包含静态资源，统一存放于此；也可以没有任何资源文件或不创建此目录，工程最终可仅依赖纯 `index.html` 运行。 |
+| `skill/SKILL.md` | **可选** | 本模板特定的玩法技能说明文件，指导 AI 助手如何协助创作者调整作品规则。若无独立玩法技能可不提供。 |
+
+---
+
+## 2. package.json
+
+`package.json` 文件必须位于工程根目录，且内容为合法的 JSON 对象。
+
+### 2.1 基础配置字段
+
+所有字段集中约定如下：
+
+| 字段 | 属性 | 数据类型 | 格式与要求 | 示例 |
+|---|---|---|---|---|
+| `name` | **必须** | string | 平台展示名称，供人阅读，支持中文；去掉首尾空格后长度至少为 1；不能包含字符 `/` 或 `@`。 | `"趣味问答"`、`"quiz-react"` |
+| `slug` | **必须** | string | 模板英文短名，在平台中唯一标识本模板；格式须匹配 `^[a-z0-9][a-z0-9-]{0,62}$`。详见下方细则。 | `"quiz-react"` |
+| `version` | **必须** | string | 模板版本号；格式须匹配 `^(?=.{1,16}$)[a-z0-9]+(?:[.-][a-z0-9]+)*$`。详见下方细则。 | `"0.1.0"`、`"1.0.0-a"` |
+| `data_ver` | **必须** | string 或 number | 配套数据包版本；非空字符串或有限数字。详见下方细则。 | `"1"` 或 `1` |
+| `description` | **可选** | string | 模板简介说明。若省略，默认取值视为空字符串 `""`；若填写，允许为空字符串。 | `"基于 React 的题库答题作品模板"` |
+
+#### 字段格式细则
+
+- **`slug`（英文短名）**
+  - 正则表达式：`^[a-z0-9][a-z0-9-]{0,62}$`
+  - 长度限制：1 至 63 个字符。
+  - 字符范围：仅允许小写英文字母（`a-z`）、数字（`0-9`）和连字符（`-`）。
+  - 起始字符：必须以小写字母或数字开头（首字符不能是连字符 `-`）。
+
+- **`version`（模板版本号）**
+  - 正则表达式：`^(?=.{1,16}$)[a-z0-9]+(?:[.-][a-z0-9]+)*$`
+  - 长度限制：1 至 16 个字符。
+  - 字符范围：仅允许小写英文字母（`a-z`）、数字（`0-9`）、英文点号（`.`）和连字符（`-`）。
+  - 边界要求：必须以小写字母或数字开头，且以小写字母或数字结尾。
+  - 连续符号限制：点号与连字符不能相邻或连续出现（例如禁止 `..`、`--`、`.-`、`-.`）。
+  - 合法示例：`0.1.0`、`1.0.0-a`、`1.0.0-rc1`。
+
+- **`data_ver`（数据包版本）**
+  - 当类型为字符串（string）时：去除首尾空白字符后，长度至少为 1。示例：`"1"`。
+  - 当类型为数字（number）时：必须为合法的有限数值。示例：`1`。
+
+### 2.2 必须脚本命令 (`scripts`)
+
+`package.json` 中的 `scripts` 字段必须为对象，且必须包含以下 5 个指定脚本。每个脚本对应的值必须为字符串，且去除首尾空白后不可为空。脚本的具体执行命令由模板自身的技术栈决定。
+
+| 脚本名称 | 属性 | 作用与要求 |
+|---|---|---|
+| `dev` | **必须** | 启动正式内容的本地开发服务。 |
+| `dev:demo` | **必须** | 启动试玩内容的本地开发服务。若模板未制作独立的试玩内容，命令可与 `dev` 保持完全一致。 |
+| `build` | **必须** | 构建正式版产物到根目录 `dist/`。详见第 3 节。 |
+| `build:demo` | **必须** | 构建试玩版产物到根目录 `dist/`。若模板未制作独立的试玩内容，命令可与 `build` 保持完全一致。 |
+| `validate` | **必须** | 执行模板自身的数据检查。若模板包含独立的试玩数据，此单条脚本须同时覆盖正式数据与试玩数据的校验。 |
+
+---
+
+## 3. 构建产物 (dist/)
+
+构建产物用于静态托管与作品发布，统一约定如下：
+
+1. **产物目录**：`scripts.build` 与 `scripts.build:demo` 的输出目录必须是工程根目录下的 `dist/`，两者共用该目录。
+2. **入口文件**：`dist/` 根目录下**必须**产出 `index.html` 入口文件。可以仅产出纯 `index.html`，无需任何其他静态资源文件。
+3. **静态资源（建议）**：若构建产物包含 JavaScript、CSS、图片等静态资源，建议放置于与 `index.html` 同级的 `dist/assets/` 目录下。
+4. **其他产物**：除 `dist/index.html` 外，产物目录内的其他文件组织形式本协议不作强制限制。
+
+---
+
+## 修订记录
+
+| 文档版本 | 修订日期 | 变更说明 |
+|---|---|---|
+| 1.0 | 2026-09-22 | 初始版本。明确工程目录结构、`package.json` 配置字段与脚本规范，以及 `dist/` 构建产物约定（assets 为可选，支持纯 index.html）。 |