@skillbuilder/miniapp-simulator 0.0.0-beta-20261023084421

package/docs/file-system-design.md

@@ -0,0 +1,334 @@
+# 模拟器 FS 文件系统方案
+
+## 1. 结论
+
+模拟器文件系统采用“JSAPI + Bridge + Simulator Runtime + Service Worker + IndexedDB”的分层方案：
+
+- 小工具通过 `xhs.miniTool` 文件 API 操作文件，不直接访问浏览器存储。
+- Simulator Runtime 负责 JSAPI 路由、实例上下文和错误归一化。
+- Service Worker 是文件系统执行层，负责路径校验、读写、目录、配额、协议 URL 和资源响应。
+- IndexedDB 保存文件字节及元信息，以 `(fsScope, path)` 作为复合主键。
+- `xhsfile://` 只作为端侧兼容的逻辑文件路径被文件 API 解析；浏览器实际请求的是模拟器生成的同源 `/_xhsfile_/` HTTP URL，Service Worker 拦截该 HTTP URL 后从 IndexedDB 返回文件。
+
+## 2. 设计目标
+
+- API 语义贴近端侧小工具文件能力。
+- 文件数据与小工具实例、应用身份隔离。
+- 支持 UTF-8、Base64、分片读取、临时文件转持久文件。
+- 生成浏览器可直接加载的同源资源 URL。
+- 对路径穿越、保留名称、容量和单次读写大小进行约束。
+- Service Worker 被浏览器回收或被外部注销后可以恢复。
+- Runtime 与 Service Worker 作为同一 release 发布，协议严格配对。
+
+## 3. 总体架构
+
+```mermaid
+flowchart LR
+  A[小工具代码] -->|xhs.miniTool 文件 API| B[JS SDK]
+  B -->|Bridge event + callbackId| C[Simulator Runtime]
+  C -->|fsInvoke: id + op + reqId + fsScope| D[ServiceWorkerHost]
+  D -->|MessageChannel| E[Service Worker]
+  E --> F[路径/编码/配额校验]
+  F --> G[(IndexedDB miniapp-simulator-fs)]
+  A -->|img/video src| H[同源 /_xhsfile_/ URL]
+  H -->|fetch 拦截| E
+  E -->|Response bytes + MIME| A
+```
+
+## 4. 分层职责
+
+| 层 | 主要职责 |
+| --- | --- |
+| JS SDK | 暴露 Promise/callback API 和 TypeScript 类型，发送标准 Bridge 事件 |
+| Simulator Core | 注册内置文件 handler，注入 `userDataPath`，传递 `appId` 作为 `fsScope` |
+| `file-host-api` | 将 JSAPI 名映射为 `fs*` 操作，归一化存储错误 |
+| `ServiceWorkerHost` | 注册/激活 SW、挂载实例、协议握手、MessageChannel 请求关联、失活恢复 |
+| SW `fs-ops` | 参数、路径、编码、配额校验；执行文件和目录操作 |
+| SW `fs-store` | IndexedDB 事务与 `(scope, path)` 数据访问 |
+| SW fetch handler | 把虚拟文件 URL 转换为浏览器可消费的 HTTP `Response` |
+
+## 5. 文件空间模型
+
+### 5.1 `usr` 持久区
+
+- `writeFile`、`appendFile`、`mkdir`、`unlink` 只允许操作 `usr`。
+- `saveFile` 把 `tmp` 文件移动到 `usr`；目标未传时自动生成文件名并保留扩展名。
+- `readFile`、`readDir`、`statFile` 可读取 `usr`。
+- `getFileStorageInfo.usedBytes` 和 `fileCount` 只统计 `usr` 普通文件。
+
+### 5.2 `tmp` 临时区
+
+- `writeTempFile` 接收 Base64 Data URI，自动生成 `tmp/<uuid>.<ext>`。
+- `tmp` 可被 `readFile`、`readDir`、`statFile` 读取，不能被 `writeFile`、`appendFile`、`mkdir` 或 `unlink` 直接修改。
+- `saveFile` 以移动语义把临时文件转入 `usr`，成功后原临时路径失效。
+- `getFileStorageInfo.tmpUsedBytes` 单独报告临时区占用。
+
+### 5.3 存储桶隔离
+
+`fsScope = appId || mountId`：
+
+- 配置稳定 `appId` 时，同一应用的文件使用稳定存储桶，可跨模拟器重建和页面会话访问。
+- 未配置 `appId` 时使用随机 `mountId`，新实例不会获得旧实例的存储桶地址，业务语义为会话级。
+- IndexedDB 使用 `[scope, path]` 复合键，不同应用即使使用相同逻辑路径也不会串数据。
+
+## 6. `xhsfile://` 协议实现
+
+### 6.1 先明确：浏览器不直接拦截 `xhsfile://`
+
+端侧使用以下逻辑路径表达文件：
+
+```text
+xhsfile://usr/drafts/note.json
+xhsfile://tmp/<uuid>.png
+```
+
+浏览器的 Service Worker 只能拦截其 registration scope 下的 HTTP/HTTPS 请求，不能注册或拦截 `xhsfile://` 自定义 scheme。因此当前实现不存在“浏览器发出 `xhsfile://` 请求，再由 SW 截获”的过程。
+
+`xhsfile://` 只承担端侧兼容的逻辑路径语义，并在文件 JSAPI 的 `parseFilePath → extractLogicalPath` 阶段被识别。`usr` 和 `tmp` 是逻辑根目录。文件 API 的入参解析器兼容两种形式：
+
+1. `xhsfile://usr/...`、`xhsfile://tmp/...` 逻辑路径；
+2. 模拟器生成的同源 `/_xhsfile_/` HTTP URL。
+
+两种输入最终都被归一化为 `usr/...` 或 `tmp/...`，再使用当前请求携带的 `fsScope` 访问 IndexedDB。对于 HTTP URL，解析器还会校验 URL 中编码的 scope 必须等于当前 `fsScope`，避免用一个应用的 URL 越权访问另一个应用的文件。
+
+### 6.2 从逻辑协议到可拦截 URL
+
+为了让 `<img>`、`<video>`、CSS 和 Fetch 能消费运行期文件，模拟器生成位于 SW registration scope 下的同源 HTTP/HTTPS URL：
+
+```text
+https://<simulator-origin>/<sw-scope>/_xhsfile_/<encoded-fsScope>/usr/drafts/note.json
+https://<simulator-origin>/<sw-scope>/_xhsfile_/<encoded-fsScope>/tmp/<uuid>.png
+```
+
+生成公式：
+
+```ts
+fileUrl(fsScope, path) =
+  new URL(`_xhsfile_/${encodeURIComponent(fsScope)}/${path}`, serviceWorkerScope)
+```
+
+这里使用 `sw.registration.scope` 作为 URL 基址是拦截能够生效的关键：生成结果天然处于该 Service Worker 的控制范围内。
+
+URL 有三个来源：
+
+- `ServiceWorkerHost.fileUrl(fsScope, "usr")` 生成 `userDataPath`；
+- `writeTempFile` 写入 `tmp` 后返回同源 URL，Core 将其作为 `filePath` 返回；
+- `saveFile` 移动到 `usr` 后返回同源 `savedFilePath`。
+
+模拟器将 `fileUrl(fsScope, "usr")` 注入 `launchOptions.miniToolEnv.userDataPath`。业务代码必须基于 `userDataPath` 拼接路径，不应硬编码 simulator origin、SW scope 或 `fsScope`。
+
+```ts
+const { userDataPath } = window.xhs.launchOptions.miniToolEnv
+const filePath = `${userDataPath}/drafts/note.json`
+```
+
+直接把 `xhsfile://usr/a.png` 赋给 `<img src>` 不会进入这条链路；DOM 场景必须使用 API 返回的同源 URL或基于 `userDataPath` 拼出的同源 URL。
+
+### 6.3 Service Worker 拦截如何发生
+
+拦截依赖两个前提：
+
+1. `ServiceWorkerHost.acquire` 已通过 `navigator.serviceWorker.register(scriptUrl, { scope })` 注册并等待 worker 激活；
+2. 页面是该 scope 下、已被 worker 控制的同源页面。worker 在 `activate` 阶段调用 `clients.claim()`，接管 scope 内的现有客户端。
+
+完整读取链路如下：
+
+1. 业务把同源 `/_xhsfile_/` URL 赋给 `<img>`、`<video>` 等元素，浏览器发起普通 GET；不是 `xhsfile://` 请求。
+2. 因为 URL 位于 SW registration scope 下，GET 触发 worker 的 `fetch` 事件。
+3. `main.ts` 的 fetch handler 最先调用 `parseXhsFileUrl(event.request.url)`；该分支位于包内资源和远程回源逻辑之前。
+4. `parseXhsFileUrl` 在 URL pathname 中查找保留标记 `/_xhsfile_/`，把后续内容拆成 `<encoded-fsScope>/<path>`，分别执行安全解码。
+5. 解析器拒绝空 scope、空 path、NUL、反斜杠和 `..` 路径穿越；不满足虚拟文件格式时返回 `null`，继续执行其他资源路由。
+6. 命中后立即调用 `event.respondWith(serveXhsFile(scope, path))` 并 `return`，所以不会进入包文件匹配或网络回源。
+7. `serveXhsFile` 使用 `[scope, path]` 复合键从 IndexedDB 的 `miniapp-simulator-fs/files` 读取 Blob 字节。这条读取链路不依赖内存中的 mount 表，因此 SW 进程重启后仍可读取持久文件。
+8. 读取到普通文件后，通过文件头 `sniffMediaMime` 识别媒体类型，再由 `serveBytes` 构造 HTTP `Response`，返回 `Content-Type`、`Content-Length` 和禁止缓存的响应头。
+9. 目录、保留路径、未知 MIME、缺失文件和 IndexedDB 异常统一返回 404。`/_xhsfile_/` 是封闭命名空间，命中该路由后失败也不会透传到真实网络。
+
+核心分派等价于：
+
+```ts
+sw.addEventListener("fetch", (event) => {
+  if (event.request.method !== "GET") return
+
+  const file = parseXhsFileUrl(event.request.url)
+  if (file) {
+    event.respondWith(serveXhsFile(file.scope, file.path))
+    return
+  }
+
+  // 后续才处理包内资源和远程回源
+})
+```
+
+```mermaid
+sequenceDiagram
+  participant Biz as 小工具页面
+  participant Browser as 浏览器网络层
+  participant SW as Service Worker
+  participant IDB as IndexedDB
+  Biz->>Browser: img.src = 同源 /_xhsfile_/scope/path
+  Browser->>SW: scope 内 GET / fetch event
+  SW->>SW: parseXhsFileUrl + 路径校验
+  SW->>IDB: get([scope, path])
+  IDB-->>SW: Blob bytes
+  SW-->>Browser: Response(bytes, MIME, no-store)
+  Browser-->>Biz: 图片/视频资源可用
+```
+
+### 6.4 文件 API 路径解析与资源 GET 是两条入口
+
+| 场景 | 输入 | 处理入口 | 是否触发 SW fetch |
+| --- | --- | --- | --- |
+| `readFile`、`writeFile` 等 JSAPI | `xhsfile://usr/a.txt` | Bridge → `fsInvoke` → SW message → `extractLogicalPath` | 否 |
+| `readFile` 等 JSAPI | 同源 `/_xhsfile_/scope/usr/a.txt` URL | Bridge → `fsInvoke` → SW message → `extractLogicalPath`，并校验 scope | 否 |
+| `<img>`、`<video>` 等资源加载 | 同源 `/_xhsfile_/scope/usr/a.png` URL | 浏览器 GET → SW fetch → `parseXhsFileUrl` → `serveXhsFile` | 是 |
+| `<img src="xhsfile://usr/a.png">` | 自定义 scheme | 浏览器自身处理 | 否，模拟器不支持这种 DOM 用法 |
+
+JSAPI 调用通过 `MessageChannel` 发送 `FS` 消息到 SW，资源加载通过浏览器 `fetch` 事件进入 SW。两条入口最终共享相同的 `fsScope + path` 数据模型和 IndexedDB 文件记录，但协议入口不同。
+
+### 6.5 为什么使用 Service Worker
+
+- 原生 DOM 元素只能消费浏览器支持的 URL，无法识别 `xhsfile://`。
+- Blob URL 生命周期局限于创建页面，难以表达稳定的应用级路径，也不利于跨重载恢复。
+- SW 可以在同源 URL 层返回真实 `Response`，因此 `<img>`、`<video>` 和 Canvas 可以按普通资源使用。
+- FS 与模拟器现有的 ZIP 虚拟文件系统共用同一个版本化 SW，Runtime 和 SW 协议随 release 精确配对。
+
+`xhsfile://` 保留端侧路径语义；同源 `/_xhsfile_/` URL 才是浏览器网络层和 Service Worker 实际处理的资源地址。
+
+## 7. 文件 API
+
+| API | 输入 | 输出 | 语义 |
+| --- | --- | --- | --- |
+| `writeTempFile` | Base64 Data URI | `filePath` | 解码媒体并写入自动命名的 `tmp` 文件 |
+| `saveFile` | `tempFilePath`、可选 `filePath` | `savedFilePath` | 把 `tmp` 文件移动到 `usr`，目标不能已存在 |
+| `writeFile` | `filePath`、string data、encoding | `writtenBytes` | 覆盖写入 `usr`，自动创建缺失的父目录 |
+| `appendFile` | 同 writeFile | `writtenBytes` | 向 `usr` 文件末尾追加；文件不存在时创建 |
+| `readFile` | `filePath`、encoding、position、length | `data`、`bytesRead`、`eof` | 按字节区间读取 `tmp` 或 `usr` |
+| `readDir` | `dirPath` | `files`、`truncated` | 返回直接子项，不递归 |
+| `statFile` | `filePath` | `size`、`lastModified`、`isDir` | 获取文件或目录元信息 |
+| `unlink` | `filePath` | 空对象 | 删除 `usr` 普通文件，不删除目录 |
+| `mkdir` | `dirPath`、`recursive` | 空对象 | 在 `usr` 创建目录 |
+| `getFileStorageInfo` | 无业务参数 | 容量和分片限制 | 返回 `usr/tmp` 占用及读写限制 |
+
+API 支持 Promise 和 `success/fail/complete` 回调两种调用方式；回调只在 SDK 本地消费，不进入 Bridge 消息。
+
+## 8. 写入与读取规则
+
+### 8.1 编码
+
+- `writeFile` / `appendFile` 支持 `utf8` 和严格标准 Base64。
+- Base64 必须满足标准字符集、长度和 padding；URL-safe Base64 不被接受。
+- `readFile(..., encoding: 'utf8')` 使用 fatal UTF-8 解码，非法字节返回参数错误。
+- `readFile(..., encoding: 'base64')` 返回标准 Base64 字符串。
+- `writeTempFile` 只接受 `data:<mime>;base64,<body>`。
+
+`writeTempFile` 支持 MIME：PNG、JPEG、WebP、GIF、MP4、QuickTime MOV、WebM。
+
+### 8.2 分片读取
+
+- `position` 默认为 0，按字节偏移。
+- `length` 默认为 2 MiB，最大 2 MiB。
+- 超过文件末尾返回空数据、`bytesRead: 0`、`eof: true`。
+- UTF-8 分片必须落在合法字符边界，否则 fatal 解码失败；任意字节分片优先使用 Base64。
+
+### 8.3 目录
+
+- `readDir` 只返回一级直接子项，并按路径排序。
+- 单次最多返回 1000 项；超出时 `truncated: true`。
+- `mkdir({ recursive: true })` 自动创建缺失父目录；非递归模式要求父目录已存在。
+- 当前没有递归删除目录 API。
+
+## 9. 路径安全
+
+| 规则 | 当前值 |
+| --- | --- |
+| 允许根目录 | 读取：`tmp`、`usr`；写入：`usr` |
+| 最大相对路径字节数 | 255 bytes |
+| 最大目录深度 | 4 段 |
+| 单段字符 | `[A-Za-z0-9._-]` |
+| 单段长度 | 1–64 字符 |
+| 禁止内容 | NUL、反斜杠、`.`、`..`、无法解码的 URL |
+| 保留名称 | 任意以 `__xhs` 开头的路径段 |
+| 同源 URL 校验 | URL 内 `fsScope` 必须等于当前调用上下文的 scope |
+
+## 10. 配额与并发
+
+| 限制 | 当前值 | 说明 |
+| --- | --- | --- |
+| `usr` 总容量 | 50 MiB / `fsScope` | 覆盖写会扣除被替换文件大小后计算 |
+| 单次写入/追加 | 2 MiB | 按解码后的实际字节计算 |
+| 单次读取 | 2 MiB | `length` 上限 |
+| 单模拟器会话累计写入 | 200 MiB | 防止通过反复覆盖绕过流量上限；UNMOUNT 时释放计数 |
+| FS 操作超时 | 30 秒 | Host 等待 `FS_ACK` 的上限 |
+| 单 release 活跃挂载 | 16 个 | 超限明确失败，不驱逐正在运行的实例 |
+
+所有变更操作进入 SW 内的统一 mutation queue，避免并发写、移动、删除和建目录互相覆盖。读取操作不进入该串行队列。
+
+当前 `tmp` 数据不计入 50 MiB `usr` 配额，`writeTempFile` 也不累计 200 MiB 会话写入限制；临时区只通过 `tmpUsedBytes` 暴露占用，实际仍受浏览器 IndexedDB 配额约束。
+
+## 11. SW 生命周期与恢复
+
+1. `ServiceWorkerHost.acquire` 按 `(scope, scriptUrl)` 单例注册 module SW，触发更新检查并等待 activated。
+2. Runtime 发送 `MOUNT`，传入实例 ID、文件表、CSP、注入片段和 `fsScope`。
+3. SW 返回 `MOUNT_ACK`，包含协议版本和支持的 `fsOps`；协议版本必须与 Runtime 完全一致。
+4. FS 调用使用独立 `MessageChannel`，以 `id + op + reqId` 校验应答，避免并发串包。
+5. Host 保留 mount 快照。SW 内存状态丢失并返回 `ERR_NOT_MOUNTED` 时，Host 重新注册/激活、重放 MOUNT，并重试一次 FS 调用。
+6. reload、destroy、pagehide 发送 `UNMOUNT`，释放内存挂载表和本次会话写入计数；IndexedDB 文件按 `fsScope` 保留。
+7. MOUNT 前清理已不存在 owner client 的孤儿挂载，避免异常退出长期占用 16 个挂载名额。
+
+## 12. 错误模型
+
+| 错误码 | 名称 | 场景 |
+| --- | --- | --- |
+| 10001 | INVALID_PARAM | 缺字段、类型/encoding/range/base64/UTF-8 非法 |
+| 50101 | STORAGE_IO_ERROR | IndexedDB 或未预期存储异常 |
+| 50201 | STORAGE_QUOTA_EXCEEDED | 单次写入、`usr` 总容量或会话累计写入超限 |
+| 50202 | FILE_NOT_FOUND | 文件或父目录不存在 |
+| 50203 | PATH_INVALID | 目录不允许、穿越、保留名、路径过深/过长/字符非法 |
+| 50204 | FILE_ALREADY_EXISTS | saveFile 目标已存在，或非递归 mkdir 目标已存在 |
+| 50205 | NOT_A_FILE | 目标是目录，或父路径被普通文件占用 |
+| 50206 | NOT_A_DIRECTORY | readDir 目标不是目录 |
+
+内部 SW 协议还使用 `ERR_NOT_MOUNTED`、`ERR_UNSUPPORTED_OP`、`ERR_MOUNT_LIMIT` 等控制面错误；Runtime 对未知存储异常归一为 50101。
+
+## 13. 与其他能力的关系
+
+- `saveImageToPhotosAlbum` 可接收 Data URI，或通过 FS Bridge 读取 `writeTempFile` / `saveFile` 返回的本地路径。
+- `<img>`、`<video>`、Canvas 等通过同源 `/_xhsfile_/` URL 加载可识别媒体。
+- 包内静态资源走 `/<mountId>/<packagePath>`；运行期文件走不含 mountId 的 `/_xhsfile_/<fsScope>/<path>`，两套命名空间独立。
+- 远程应用未命中的包内资源可以回源；`/_xhsfile_/` 未命中固定返回 404，避免污染宿主网络。
+
+## 14. 当前限制
+
+- 仅 `iframe-service-worker` 渲染模式提供该浏览器 FS 实现；SW 不可用时文件 JSAPI 不可用。
+- SW 需要安全上下文、同源脚本 URL 和合法 scope。
+- 没有 rename、copy、递归删除、目录删除和随机写 API。
+- DOM URL 只直供能通过文件魔数识别的图片/视频；文本等文件使用 `readFile` 获取。
+- `writeTempFile` 只接受白名单媒体 Base64 Data URI。
+- 文件名不支持空格、中文和白名单外符号。
+- `usr` 文件持久化未提供面向业务的整桶清理 API。
+
+## 15. 验收清单
+
+- [x] UTF-8 与 Base64 覆盖写、追加和读取。
+- [x] position/length 分片读取与 EOF 语义。
+- [x] 临时媒体写入、DOM URL 加载、saveFile 移动到 `usr`。
+- [x] 目录创建、直接子项读取、stat 和 unlink。
+- [x] `xhsfile://` 与同源 `/_xhsfile_/` 输入解析一致。
+- [x] appId 存储桶隔离和跨会话访问。
+- [x] 路径穿越、保留名称、深度、长度和编码校验。
+- [x] 单次、总容量、会话累计写入限制。
+- [x] SW 协议版本与能力握手。
+- [x] SW 丢失挂载后自动恢复并重试。
+
+## 16. 代码落点
+
+| 模块 | 职责 |
+| --- | --- |
+| `miniapp-js-api/src/apis/fileSystem`（已外移） | 9 个通用文件 API 的类型与 Bridge 封装 |
+| `miniapp-js-api/src/apis/writeTempFile.ts`（已外移） | Base64 Data URI 转临时文件 API |
+| `miniapp-simulator/src/runtime/file-host-api.ts` | JSAPI 到 SW FS op 映射及错误归一化 |
+| `miniapp-simulator/src/sw/protocol.ts` | Runtime/SW 协议版本、操作联合类型 |
+| `miniapp-simulator/src/sw/service-worker-host.ts` | SW 注册、MOUNT、FS RPC、恢复和 UNMOUNT |
+| `miniapp-simulator/src/sw/worker/fs-ops.ts` | 文件操作、路径、编码、配额和 `xhsfile` URL |
+| `miniapp-simulator/src/sw/worker/fs-store.ts` | IndexedDB 存储实现 |
+| `miniapp-simulator/src/sw/worker/main.ts` | message/fetch 分派和 `/_xhsfile_/` 路由 |

package/docs/host-external-api.md

@@ -0,0 +1,235 @@
+# 模拟器对外接口 —— 路由 / 小工具封面 / 截图
+
+> 面向宿主接入方（创服 PC 等平台）。本文是**接口契约**：宿主可先按本文接入编码，SDK 实现落地后无需调整调用方式。
+>
+> 涉及能力：
+> 1. 页面路由：笔记页 / 小工具页 / 个人页 之间的跳转与状态同步（`redirectTo` + `routerChange`）
+> 2. 小工具封面：`widgetCover.update`（笔记尾卡 + 个人页卡片两处生效；用户信息由 hostApi `getUserInfo` 自动填充）
+> 3. 小工具运行截图：`screenShot()` 主动截图 + `onScreenShot` 回调（base64 / 失败原因）
+
+---
+
+## 一、页面路由
+
+### 1.1 页面枚举
+
+```ts
+type MiniAppSimulatorRoute =
+  | "note"     // 笔记页
+  | "minitool" // 小工具页（运行内容，默认全屏）
+  | "profile"; // 个人页
+```
+
+### 1.2 跳转：`redirectTo`
+
+```ts
+simulator.redirectTo(route: MiniAppSimulatorRoute, options?: {
+  sheetMode?: "half" | "full"; // 仅 route === "minitool" 时生效，默认 "full"
+}): Promise<void>;
+```
+
+- 宿主侧切换 Tab 时调用，例：`simulator.redirectTo("profile")`。
+- 跳转完成 resolve；传非法 route 时 reject。
+- 不传 `sheetMode` 时小工具页按**全屏**打开。
+
+```ts
+simulator.getCurrentRoute(): MiniAppSimulatorRoute; // 当前页面："note" | "minitool" | "profile"
+```
+
+### 1.3 路由变化回调：`routerChange`
+
+模拟器内部跳转（点头像、点卡片、下滑关闭、命中内存限制被回收等）与宿主调用 `redirectTo` 都会触发，宿主据此保持两侧状态一致：
+
+```ts
+interface MiniAppRouterChangeEvent {
+  from: MiniAppSimulatorRoute;
+  to: MiniAppSimulatorRoute;
+}
+```
+
+两种注册方式（与现有 `onLoad` / `onError` 同一套机制）：
+
+```ts
+// 方式一：事件级（on / once / off 三件套）
+const off = simulator.on("routerChange", (e) => {
+  // e.from / e.to
+});
+
+// 方式二：option 级，构造时绑定
+createMiniAppSimulator({
+  onRouterChange(e) {
+    // e.from / e.to
+  },
+});
+```
+
+注意：**宿主自己调用 `redirectTo` 也会收到 `routerChange` 回声**。如需区分是否自己发起，可在调用前后自行打标（`redirectTo` 返回 Promise，天然可界定）。
+
+典型用法 —— 宿主 Tab 与模拟器双向同步：
+
+```ts
+// 模拟器 → 宿主：内部跳转时同步宿主 Tab
+simulator.on("routerChange", ({ to }) => setHostTab(to));
+
+// 宿主 → 模拟器：宿主 Tab 切换时驱动模拟器
+onHostTabChange((tab) => simulator.redirectTo(tab));
+```
+
+内部触发路由变化的已知场景：
+
+| 场景 | 变化 |
+| --- | --- |
+| 笔记页点击导航栏头像 | `note → profile` |
+| 笔记页 / 个人页点击小工具卡片 | `note/profile → minitool` |
+| 全屏小工具页返回、半屏下滑关闭 | `minitool → note` |
+| 小工具命中内存限制被回收 | `minitool → note` |
+
+---
+
+## 二、小工具封面：`widgetCover.update`
+
+小工具封面是**一个小工具的属性**：设置了它，笔记轮播「小工具尾卡」和个人页「作品 → 小工具」卡片**两处同时生效**。个人页卡片的用户信息（头像 / 昵称）由 SDK 通过 hostApi `getUserInfo` 自动填充，宿主无需调用任何接口。
+
+```ts
+interface MiniAppWidgetCoverController {
+  /** 部分字段更新（title / cover 单独覆盖） */
+  update(data: Partial<XhsWidgetCoverData>): void;
+}
+
+interface XhsWidgetCoverData {
+  /** 标题；不传默认「小工具模拟器」 */
+  title?: string;
+  /** 封面图 url / dataURL；不传用 SDK 自动截图结果（内部按 3:4 顶部对齐裁剪展示） */
+  cover?: string;
+}
+```
+
+正常链路（宿主无需干预）：部署成功 → SDK 自动截图 → 内部裁 3:4 → 尾卡 + 个人页卡片自动更新；完整截图经 `onScreenShot`（source: "auto"）回调宿主。
+
+宿主对自动截图不满意，自己传一张（部分字段覆盖，title 不受影响）：
+
+```ts
+simulator.widgetCover.update({ cover: hostCustomCover });
+// 笔记尾卡 ← 覆盖
+// 个人页卡片 ← 覆盖
+```
+
+也可在构造时传入初始数据：
+
+```ts
+createMiniAppSimulator({
+  widgetCover: { title: "汇率计算器", cover },
+});
+```
+
+---
+
+## 三、截图：`screenShot` / `onScreenShot`
+
+### 3.1 结果结构
+
+```ts
+type MiniAppScreenShotResult =
+  | {
+      success: true;
+      /** 完整 dataURL（data:image/png;base64,xxx），可直接用于 <img> 或上传 */
+      base64: string;
+      width: number;
+      height: number;
+      /** auto = 部署成功后自动截图；manual = 宿主主动调用 screenShot() */
+      source: "auto" | "manual";
+    }
+  | {
+      success: false;
+      code:
+        | "not-loaded"     // 小工具尚未加载
+        | "render-failed"  // 页面渲染异常，截图内容不可用
+        | "timeout"        // 截图超时
+        | "unsupported";   // 当前环境不支持截图
+      /** 人类可读的失败原因 */
+      reason: string;
+    };
+```
+
+### 3.2 主动截图
+
+```ts
+simulator.screenShot(): Promise<MiniAppScreenShotResult>;
+```
+
+返回**完整截图**（整页画面，不裁剪），成功返回 base64，失败返回原因；**不抛异常**（除非法入参），失败信息在 result 里。结果同时以 `screenShot` 事件（`source: "manual"`）回调。
+
+### 3.3 自动截图回调
+
+```ts
+createMiniAppSimulator({
+  // 部署成功后 SDK 自动截图并回调 onScreenShot（source: "auto"），失败也会回调失败原因
+  onScreenShot(result) {
+    if (result.success) uploadCover(result.base64);
+    else showUploadPlaceholder(result.reason); // 没截到图 → 引导用户手动上传封面
+  },
+});
+
+// 事件级订阅（manual 截图也会触发该事件）
+simulator.on("screenShot", (result) => {});
+```
+
+说明：
+
+- 回调结果以 `source: "auto" | "manual"` 区分是部署后自动截图还是宿主主动调用。
+- 笔记轮播「小工具尾卡」的内部封面（SDK 自行裁剪 3:4）不受对外结果影响，始终自动更新。
+- 已有 `simulator.capture(): Promise<Blob>` 保持不变；`screenShot()` 是面向封面上传场景的新入口，产出 base64 + 失败原因。
+
+### 3.4 典型链路（创服封面上传）
+
+```ts
+const simulator = createMiniAppSimulator({
+  onRouterChange({ to }) {
+    setHostTab(to);
+  },
+});
+
+// 部署成功后：截图 → 上传 → 设置封面（尾卡 + 个人页卡片两处生效）
+await simulator.loadZip(file);
+const shot = await simulator.screenShot();
+if (shot.success) {
+  await uploadCover(shot.base64);
+  simulator.widgetCover.update({ title: "汇率计算器", cover: shot.base64 });
+}
+```
+
+---
+
+## 四、远程模式（`@skillbuilder/miniapp-simulator/remote`）
+
+`createRemoteMiniAppSimulator` 的返回值镜像透出以上全部能力，用法与本地模式一致：
+
+```ts
+const remote = createRemoteMiniAppSimulator({ /* ... */ });
+
+remote.redirectTo("profile");
+remote.getCurrentRoute();
+remote.widgetCover.update({ title, cover });
+remote.screenShot();                       // Promise<MiniAppScreenShotResult>
+remote.on("routerChange", (e) => {});      // 事件转发
+remote.on("screenShot", (result) => {});
+```
+
+远程选项 `options`（`RemoteMiniAppSimulatorOptions.options`）中同样支持 `widgetCover` 数据、`onRouterChange` / `onScreenShot` 回调（回调经协议转发回宿主侧触发）。
+
+> 远程协议版本将升到 7；客户端与 Runtime 版本不匹配时握手会直接报错，升级 SDK 时请两端同步发版。
+
+---
+
+## 五、能力总览（新增部分）
+
+| 接口 | 说明 |
+| --- | --- |
+| `redirectTo(route, options?)` | 跳转页面（note / minitool / profile），minitool 默认全屏 |
+| `getCurrentRoute()` | 获取当前页面（note / minitool / profile） |
+| `on("routerChange", handler)` / `onRouterChange` | 任意来源的页面切换回调 `{ from, to }` |
+| `widgetCover.update(data)` | 设置小工具封面（title / cover），笔记尾卡 + 个人页卡片两处生效 |
+| `screenShot()` | 主动截图（完整画面），成功返回 base64，失败返回 code + reason |
+| `on("screenShot", handler)` / `onScreenShot` | 截图结果回调（`source: "auto" \| "manual"` 区分来源） |
+
+个人页卡片作者行的用户信息（头像 / 昵称）无对外接口，由 SDK 经 hostApi `getUserInfo` 自动填充。