@skillbuilder/miniapp-simulator 0.2.4 → 0.2.8

package/docs/desktop-gesture-design.redoc.xml

@@ -0,0 +1,96 @@
+<title>模拟器桌面手势与独立触点设计</title>
+<h1>1. 背景与问题</h1>
+<p>移动端游戏通常按触摸屏设计，玩家可以一只手持续控制方向，另一只手操作油门、刹车或技能。审核人员在电脑上体验这些游戏时，主要使用鼠标和键盘。单个鼠标只能持续操作一个位置，难以直接完成手机上的双手配合。</p>
+<p>以《公路之王》为例，驾驶时需要一边转动方向盘，一边控制踏板；接单时还要拖动滑条并在合适位置松手。如果模拟器只提供点击，或者没有完整传递拖动与释放事件，审核人员即使看到了控件，也可能无法推进游戏流程。</p>
+<table header-row="true"><colgroup><col width="190"/><col width="290"/><col width="260"/></colgroup><tbody>
+<tr><td><p>操作场景</p></td><td><p>桌面操作遇到的问题</p></td><td><p>对审核体验的影响</p></td></tr>
+<tr><td><p>方向盘与踏板同时操作</p></td><td><p>鼠标拖动方向盘时，无法同时移动到油门或刹车上保持按下。</p></td><td><p>难以体验正常驾驶，也难以判断组合操作是否正确。</p></td></tr>
+<tr><td><p>滑动接单、拖动控件</p></td><td><p>控件可能依赖稳定的触点标识、完整的移动轨迹、指针捕获及释放顺序。</p></td><td><p>画面上有拖动动作，游戏却没有提交操作，容易将模拟器输入问题误判为游戏缺陷。</p></td></tr>
+<tr><td><p>不同游戏的操作区域</p></td><td><p>按钮位置、大小和交互方式各不相同。</p></td><td><p>固定键位难以通用，每个游戏单独适配的维护成本高。</p></td></tr>
+<tr><td><p>画面朝向与辅助面板</p></td><td><p>侧放画面影响阅读；辅助面板挤占空间或遮挡控件。</p></td><td><p>游戏画面变小，配置键位与实际操作互相干扰。</p></td></tr>
+</tbody></table>
+<p>因此，模拟器需要提供能表达手机触摸操作的桌面输入方式，让审核人员顺畅进入并体验核心玩法，同时准确区分游戏自身问题与模拟器的输入限制。</p>
+<h1>2. 设计目标</h1>
+<ul>
+<li>鼠标负责连续拖动，键盘可以保持多个独立触点；各触点能同时生效、分别释放。</li>
+<li>通过用户点选或框选画面建立键位映射，适应不同游戏的控件布局。</li>
+<li>保持游戏原有的触摸与指针事件语义，让滑动、长按和组合操作交给游戏自己的业务逻辑处理。</li>
+<li>配置面板可移开，打开面板保持游戏画面大小；屏幕旋转后，点击与映射仍落在正确位置。</li>
+<li>操作能力随现有远程 Runtime 更新，接入页面使用稳定的加载与通信接口。</li>
+</ul>
+<h1>3. 整体方案</h1>
+<p>采用「鼠标连续操作 + 键盘区域映射」的方式：鼠标拖动保持一个触点，每个映射键按下时，在指定区域创建一个独立触点。模拟器统一管理这些触点的状态和顺序，再将对应事件发送给游戏。</p>
+<p>例如，鼠标持续转动方向盘，W 在油门区域保持按下，S 在刹车区域保持按下。松开 W 只释放油门触点，方向盘和刹车仍保持原有操作状态。这样既能完成双手配合，也能检查多个控件同时输入时的游戏表现。</p>
+<table header-row="true"><colgroup><col width="210"/><col width="530"/></colgroup><tbody>
+<tr><td><p>设计选择</p></td><td><p>原因与效果</p></td></tr>
+<tr><td><p>按键对应独立触点</p></td><td><p>将持续按住的按钮交给键盘，鼠标可以保持连续拖动；每个输入源具有自己的生命周期。</p></td></tr>
+<tr><td><p>用户指定映射区域</p></td><td><p>按画面位置配置操作，适用于 DOM 或 Canvas 控件，无需依赖游戏内部的元素名称或专用输入接口。</p></td></tr>
+<tr><td><p>按住区域／拖动并保持</p></td><td><p>分别表达按钮长按与一次拖动后的持续保持，覆盖常见的踏板、技能按钮和摇杆操作。</p></td></tr>
+<tr><td><p>整机视觉旋转</p></td><td><p>将侧放画面转到便于阅读的方向，同时保持游戏逻辑视口与布局稳定。</p></td></tr>
+<tr><td><p>外层悬浮面板</p></td><td><p>用户可以把配置面板拖离游戏区域；面板与手机布局独立，打开时不会挤压画面。</p></td></tr>
+</tbody></table>
+<h1>4. 交互设计</h1>
+<h2>4.1 配置区域与按键</h2>
+<ol>
+<li>点击手机旁的「键位」，打开悬浮面板。</li>
+<li>选择「添加映射」，在游戏画面中点击一个位置，或拖动框选一个控件区域。</li>
+<li>按下要绑定的字母、数字、方向键或空格。按键触点位于所选区域中心。</li>
+<li>选择操作方式。普通按钮使用「按住区域」；需要拖动的控件使用「拖动并保持」，并在画面中点选终点。</li>
+<li>勾选面板顶部「启用按键映射」即可操作游戏，面板可以保持打开。点击右上角 × 可收起面板。</li>
+</ol>
+<p>映射支持修改按键、重选区域和删除，最多配置 16 组，重复按键不能绑定到两条映射。启用状态与映射数量独立，用户可以先启用再添加；空列表时不会产生触点。</p>
+<h2>4.2 同时操作与分别释放</h2>
+<p>「按住区域」在按键按下时创建触点，保持到松键。「拖动并保持」在按下后约 120ms 内从区域中心移动到终点，再保持到松键。键盘自动重复产生的 keydown 不重复创建触点。</p>
+<p>鼠标与各映射键独立控制自己的触点。先松鼠标时，按住的键盘触点继续生效；先松某个键时，鼠标和其他按键继续生效。全部释放后，模拟器清空活动触点，并向游戏发送对应的释放事件。</p>
+<p>方向盘这类需要连续调节角度的控件优先交给鼠标：用户沿轮缘拖动，游戏根据移动轨迹处理转向。快速打方向由鼠标操作与游戏规则共同决定。「拖动并保持」用于配置明确的起点和终点，持续转速、最大转角及自动回正需要专门的方向盘模型另行设计。</p>
+<h2>4.3 悬浮面板</h2>
+<p>面板顶部放置「启用按键映射」、拖动提示和关闭按钮。用户拖动顶部空白区域或提示文字即可移动面板；checkbox、文字标签、按钮和下拉框各自响应点击。面板文字禁止选中，避免拖动时产生文字选区。</p>
+<p>面板挂载到接入页面的 body，可拖出模拟器挂载范围，并限制在浏览器可视区域内。面板打开、关闭和移动均保持手机尺寸与位置。面板位置在当前实例中保留。</p>
+<h2>4.4 旋转屏幕</h2>
+<p>「逆时针旋转 90°」和「顺时针旋转 90°」每点击一次，将手机外壳与 iframe 整体按对应方向旋转 90°；同方向连续四次回到原位。竖直时，「键位」和两个旋转按钮在手机左侧纵向排列；横向时在手机下方横向排列。</p>
+<p>手机在挂载区域内靠上摆放。竖直时质量分及体验评测位于手机右侧；横向时位于手机和操作按钮下方，内容保持正向，正文可独立滚动。</p>
+<p>这是设备的显示旋转，游戏逻辑视口的宽高保持不变。旋转时先释放活动触点，避免用户改变画面朝向后继续保持错误的拖动状态。</p>
+<h1>5. 技术设计</h1>
+<h2>5.1 输入处理链路</h2>
+<p>游戏原包通过 Runtime 解压并由 Service Worker 提供虚拟资源路径，HTML 加载时注入输入接收器。鼠标与键盘的转换在模拟器侧完成，游戏沿用自己的事件监听和业务逻辑。</p>
+<text-draw remote-syntax="Mermaid" remote-view="show-all">flowchart TD
+  Mouse[鼠标按下、移动、松开] --&gt; Input[Runtime 输入处理]
+  Keyboard[映射键按下、松开] --&gt; Input
+  Panel[悬浮面板：区域与按键配置] -- 配置命令 --&gt; Input
+  Input -- 坐标转换与输入排序 --&gt; Contacts[统一触点集合：每个来源独立标识]
+  Contacts -- 触点变化消息 --&gt; Receiver[游戏 iframe 输入接收器]
+  Receiver -- Pointer / Touch 事件 --&gt; Game[游戏自身的控件与业务逻辑]
+  Input -- 配置状态 --&gt; Panel</text-draw>
+<h2>5.2 独立触点与事件语义</h2>
+<p>为鼠标与每个映射键分配独立触点标识。触点开始时确定目标元素，后续移动、释放与取消保持同一目标和指针身份，并支持指针捕获。统一活动集合保存所有仍按住的触点；某个来源结束时，仅移除对应触点。</p>
+<p>派发事件时，touches 表示全部活动触点，changedTouches 表示本次变化，targetTouches 表示当前目标上的触点。这样，游戏能够区分「松开油门」与「结束全部触摸」，避免一个按键的释放打断另一个控件。</p>
+<p>接收器在同一批次中先派发 Pointer，再派发 Touch。《公路之王》的接单滑条会在 pointerup 判断拖动是否达到阈值，touchend 则清理触摸状态；提交动作需要在清理之前完成。稳定的 pointerId、连续位移和完整释放事件共同保证游戏能够按自己的规则识别滑动。</p>
+<p>同时尊重游戏的 preventDefault。多触点操作抑制额外的点击、长按和单指默认滚动；对于合成事件不能自动完成的单指滚动、滑块和点击行为，由接收器按交互状态处理。</p>
+<h2>5.3 跨窗口顺序与取消</h2>
+<p>键盘事件可能发生在游戏 iframe 中，再通过消息到达 Runtime；鼠标事件则由 Runtime 直接捕获。输入调度按事件发生时间与稳定的入队顺序合并，并通过 iframe 确认消息确保较早的按键边沿已经到达。按键序号与输入代次用于丢弃过期消息，避免快速松键后又收到迟到的按下事件。</p>
+<p>只接管已启用的映射键，避免同时触发游戏原生键盘操作与映射触点。面板打开时映射继续生效；从面板切入同一游戏画面时保持按住的触点。输入框、下拉框、组合输入和系统修饰键快捷键保留正常行为。选区、录键、离开当前游戏、页面隐藏、禁用映射、游戏重载和实例销毁时，取消活动输入并清理待处理事件，防止卡键。</p>
+<h2>5.4 坐标、旋转与缩放</h2>
+<p>选区按游戏逻辑视口归一化保存。鼠标位置先从外层屏幕坐标转换为游戏坐标，触点、选区和提示标记使用同一套变换。设备旋转与缩放均通过对应的逆变换定位，保证看到的控件与实际命中的控件一致。</p>
+<p>设备容器负责旋转，外层布局按旋转后的宽高占位，iframe 继续使用原有逻辑视口。窗口缩放可以保持区域比例；游戏内部控件布局发生变化时，需要用户检查并重选映射区域。</p>
+<h2>5.5 悬浮面板与远程更新</h2>
+<p>Runtime 持有区域、键位、编辑状态和触点。外层面板接收可序列化的状态快照，将添加、选区、绑定、启用等语义命令通过 MessageChannel 返回 Runtime。会话标识、控制器标识和递增修订号用于隔离实例及忽略迟到消息。</p>
+<p>面板视图、拖拽和交互逻辑由现有 runtime.js 导出。服务清单负责选择 Runtime 页面，页面按既有链路加载模块；Runtime entry 将自身 import.meta.url 通过现有握手返回，接入页面按需导入同一资源中的面板视图，并挂载到自己的 body。功能复用这一份 Runtime 资源及其发布流程；薄 SDK 只承担加载、挂载、通信、必要的焦点交接和生命周期。</p>
+<p>模块地址由服务选定的 Runtime iframe 经当前会话的 MessagePort 提供，接入页面校验会话、协议、能力及模块地址的协议与属性。Runtime 页面加载模块时启动运行服务，接入页面按需导入时使用面板导出，避免在外层页面重复启动运行环境。</p>
+<p>面板中的选择、绑定操作按需要把焦点交给游戏所在的 Runtime；窗口失焦或点击外部输入区域时取消当前输入。面板内的悬停与焦点属于审核操作范围，用于避免编辑键位时触发离开超时，但不计作游戏操作。</p>
+<h1>6. 能力范围</h1>
+<ul>
+<li>区域映射由用户配置，在当前模拟器实例中保存。自动识别控件、跟随游戏布局变化与跨实例持久化配置需单独设计。</li>
+<li>「拖动并保持」表达一次直线拖动。方向盘连续角度控制、转速曲线与回正参数属于专门的控件映射能力。</li>
+<li>顺时针与逆时针旋转均保持游戏逻辑视口。真正的横屏适配需要定义视口变化和游戏重排规则。</li>
+<li>一个系统鼠标与键盘共同模拟多个触点。浏览器提供的鼠标事件不区分两只物理鼠标的独立指针。</li>
+<li>输入接收器生成的是合成事件，适用于游戏事件监听；浏览器特权操作与真实硬件特性仍受浏览器限制。</li>
+</ul>
+<h1>7. 《公路之王》操作验收图</h1>
+<p>用鼠标持续控制方向盘，将油门和刹车分别映射到 W、S。图中方向盘、油门与刹车上的触点同时保持，W／S 标记表示按键对应的操作区域。</p>
+<image url="./assets/road-king-controls.png" width="900" height="490" align="center" />
+<ol>
+<li>进入驾驶页，点击「逆时针旋转 90°」，使驾驶画面正向显示。用鼠标拖动游戏手机中的「滑动接单」滑条，超过行程四分之三后松手，进入接驾流程。</li>
+<li>打开「键位」并添加映射，框选油门区域后按 W；再框选刹车区域后按 S。两项均选择「按住区域」，勾选「启用按键映射」后即可操作，面板可以保持打开。</li>
+<li>鼠标按住方向盘并沿轮缘拖动，同时按住 W 控制油门。需要刹车时按 S；鼠标、W、S 可以同时保持，游戏按自己的驾驶规则处理组合输入。</li>
+<li>分别松开 W、S 和鼠标：松 W 只释放油门，松 S 只释放刹车，松鼠标只结束方向盘拖动。先松鼠标时，仍按住的 W／S 继续生效。</li>
+</ol>

package/docs/electron-review.md

@@ -138,7 +138,7 @@ idle → preparing → attached → warming → measuring → finalizing → fin
 
 ## 6. APM 上报与字段登记
 
-二期沿用现有 APM 事件，不新增自有 `/audit/raw` 接口。`miniapp_audit_session`、`miniapp_audit_sample`、`miniapp_audit_incident`、`miniapp_audit_package`、`miniapp_audit_result` 通过 `executionEnv: electron` 与一期区分。所有 `measurement_data` 只放数字；布尔值用 `0/1`。
+二期沿用现有 APM 事件，不新增自有 `/audit/raw` 接口。`miniapp_audit_session`、`miniapp_audit_incident`、`miniapp_audit_package`、`miniapp_audit_result` 通过 `executionEnv: electron` 与一期区分。所有 `measurement_data` 只放数字；布尔值用 `0/1`。
 
 每次结果必须登记：
 

package/docs/quality-evaluation-redoc.xml

@@ -39,10 +39,10 @@
 <p>资源评价顺序为：<b>ZIP 压缩体积 → 解压后总体积 → 最大单图与大 JS 文件</b>。ZIP 体积是包体评分的首要指标、资源维度中的最高权重项，解压后体积作为次要评分项，两项分别展示、分别上报。小工具 ZIP 包上限为 10MB，该上限约束压缩包，不是解压后体积或运行内存。</p>
 <table header-row="true"><colgroup><col width="155"/><col width="240"/><col width="230"/><col width="230"/></colgroup><tbody>
 <tr><td><p>指标</p></td><td><p>统计口径</p></td><td><p>评分定位与依据</p></td><td><p>产品解释与建议</p></td></tr>
-<tr><td><p><b>ZIP 压缩体积</b></p></td><td><p>实际 ZIP 文件的字节数；所有业务形态统一遵守 10MB 包上限。</p></td><td><p>包体评分第一位。交付规范建议控制在 2MB 以内；评分曲线在有效包范围内按体积设置，并通过试跑校准。10MB 是业务上限，不直接等同于零分线。</p></td><td><p>优先评价交付包负担，检查素材压缩、重复依赖与无用文件。包小不代表展开后的资源也小，需结合解压体积判断。</p></td></tr>
-<tr><td><p>解压后总体积</p></td><td><p>解压后包内文件字节数求和，与 ZIP 字节数独立记录。</p></td><td><p>包体评分第二位。根据真实包分布和资源用途校准预算，不套用 ZIP 的 10MB 上限。</p></td><td><p>用于识别压缩后较小、展开后仍较重的资源包；排查冗余素材与重复依赖。它不是运行期内存占用。</p></td></tr>
-<tr><td><p>最大单图</p></td><td><p>包内最大图片文件大小，不是解码后的像素内存。</p></td><td><p>≤ 300KiB 为 100 分；300–1,200KiB 线性扣分；≥ 1,200KiB 为 0 分。权重 3。</p></td><td><p>检查尺寸、格式与压缩；结合首屏用途判断是否需要优化，不能只看文件大就判功能失败。</p></td></tr>
-<tr><td><p>大 JS 文件</p></td><td><p>统计单文件超过 1MiB 的 JS 体积之和。面板“未压缩 JS”字段实际采用此启发式口径，并未检查源码是否压缩。</p></td><td><p>没有超线文件为 100 分；超线文件总量按 0–4MiB 线性计分，达到 4MiB 为 0 分。权重 3。</p></td><td><p>引导拆包与依赖治理；不能据此认定开发者没有压缩代码。</p></td></tr>
+<tr><td><p><b>ZIP 压缩体积</b></p></td><td><p>实际 ZIP 文件的字节数；所有业务形态统一遵守 10MB 包上限。</p></td><td><p>包体评分第一位，权重 5。初始评分线为 ≤2MiB 得 100 分，5MiB 得 60 分，≥10MiB 得 0 分，区间内线性评分；由 Apollo 的 size.zip 配置并通过试跑校准。</p></td><td><p>优先评价交付包负担，检查素材压缩、重复依赖与无用文件。包小不代表展开后的资源也小，需结合解压体积判断。</p></td></tr>
+<tr><td><p>解压后总体积</p></td><td><p>解压后包内文件字节数求和，与 ZIP 字节数独立记录。</p></td><td><p>包体评分第二位，权重 3。工具类 2/4/9MiB、2D 游戏 6/12/24MiB、3D 游戏 12/20/32MiB 分别对应 100/60/0 分，区间线性评分；由 Apollo 各形态的 size 配置。</p></td><td><p>用于识别压缩后较小、展开后仍较重的资源包；排查冗余素材与重复依赖。它不是运行期内存占用。</p></td></tr>
+<tr><td><p>最大单图</p></td><td><p>包内最大图片文件大小，不是解码后的像素内存。</p></td><td><p>≤ 300KiB 为 100 分；300–1,200KiB 线性扣分；≥ 1,200KiB 为 0 分。权重 1。</p></td><td><p>检查尺寸、格式与压缩；结合首屏用途判断是否需要优化，不能只看文件大就判功能失败。</p></td></tr>
+<tr><td><p>大 JS 文件</p></td><td><p>统计单文件超过 1MiB 的 JS 体积之和。面板“未压缩 JS”字段实际采用此启发式口径，并未检查源码是否压缩。</p></td><td><p>没有超线文件为 100 分；超线文件总量按 0–4MiB 线性计分，达到 4MiB 为 0 分。权重 1。</p></td><td><p>引导拆包与依赖治理；不能据此认定开发者没有压缩代码。</p></td></tr>
 </tbody></table>
 <p>资源预算方法参考 <a href="https://web.dev/articles/performance-budgets-101">web.dev：Performance budgets</a>。10MB ZIP 上限和 2MB 优化建议来自小工具交付规范；具体评分分档由本产品试跑数据校准，不作为行业统一阈值。APM 保留两种体积的原始字节数，展示时明确标注 ZIP 或解压后体积；MiB、KiB 按 1024 进制计算。资源用途用于解释负担，不能仅凭 WebGL 特征认定内容是 3D 游戏并放宽包上限。</p>
 <p><b>微信参考：</b>微信的图片大小规则关注原图像素面积是否超过显示面积 × 设备像素比²，图片缓存规则关注 HTTP 缓存，资源冗余规则关注不可访问页面和未使用样式。这些做法支持从“资源是否有效使用”解释成本。本方案依次评价 ZIP 体积、解压体积和单项资源；图片尺寸利用率、缓存和资源使用率可作为后续诊断方向。微信的像素面积规则与本方案的文件字节阈值分别衡量不同成本。</p>

package/docs/tracker.md

@@ -53,8 +53,9 @@ createMiniAppSimulator({
   });
   ```
 
-- **批量上报**：打点先进缓冲，满 10 条或最多 10s 后合并成一次请求发送；页面隐藏（`visibilitychange`）
-  与 `destroy()` 时立即冲刷，避免关闭前丢数据。
+- **批量上报**：打点先进缓冲，满 10 条或最多 10s 后触发发送。每个请求最多 10 条，50 条分为
+  5 个请求，尾批按实际条数发送。同一 SDK 模块内的 tracker 共用有序队列；一批完成（含重试）后发送下一批。
+  每次尝试最多等待 5 秒；网络错误、超时及 5xx 最多尝试三次，4xx 结束该批。页面隐藏（`visibilitychange`）与 `destroy()` 时立即冲刷。
 - **本地开发**：`localhost` / `127.0.0.1` 默认上报到测试 APM；需要只看 console 时显式传 `debug: true`。
 
 ## 字段说明