@skillbuilder/miniapp-simulator 0.0.0-beta-20261023084421

package/docs/sdk-usage.md

@@ -0,0 +1,260 @@
+# Designable Miniapp Simulator SDK 使用文档
+
+## 设计定位
+
+SDK 核心只渲染 **干净的手机本体（设备舞台）**：手机壳 + 内容层 + 内置 overlay（权限 Sheet / REDNote 壳层 / toast）。
+顶栏、侧栏、授权触发按钮等 chrome 由消费场景（PC 预览 / 审核模拟器）自行实现，全部通过 **实例方法** 驱动模拟器。
+
+- **挂载**：只需提供一个 `mount` root 节点，SDK 在其内部创建自己的宿主元素，默认用 **Shadow DOM** 隔离样式。
+- **切换**：外壳、内容模式、设备、视口、能力开关都以语义化实例方法暴露（`switchMode` / `switchPhoneFrame` / `switchDevice` / `setViewport` ...）。
+- **回调化**：加载链路提供 `beforeLoad` → `load` → `renderDone` 事件与同名 option 回调。
+
+## Core SDK
+
+```ts
+import { createMiniAppSimulator } from "@skillbuilder/miniapp-simulator";
+
+const simulator = createMiniAppSimulator({
+  // 挂载目标：CSS 选择器或 HTMLElement，SDK 在其内部创建 shadow host
+  mount: "#preview",
+  // Shadow DOM 样式隔离，默认 true；传 false 退化为 light DOM
+  shadow: true,
+  // Web 运行时：Service Worker 虚拟服务器（默认）。Electron 用 "webview"
+  renderer: "iframe-service-worker",
+  // SW 模式需消费方自托管 SW 脚本（同源）
+  serviceWorker: { scriptUrl: "/miniapp-sw.js" },
+  viewport: { width: 390, height: 844 },
+  query: {
+    source: "preview",
+  },
+  // 生命周期回调（等价于对应 simulator.on(...)，实例创建即绑定）
+  onBeforeLoad: (event) => console.log("beforeLoad", event.url, event.source),
+  onLoad: (event) => console.log("loaded", event.duration),
+  onRenderDone: (event) => console.log("renderDone", event.duration),
+  onError: (error) => console.error(error.code, error.message),
+});
+
+// create 只配置；入口由 loadApp / loadZip / loadFiles 加载
+await simulator.loadApp("http://127.0.0.1:5173/demo-app.html");
+```
+
+## 实例方法（切换 / 加载）
+
+无需销毁重建，所有"切换"通过方法完成：
+
+```ts
+// 内容模式：half / fullscreen（switchMode 为别名）
+await simulator.switchContentMode("half");
+await simulator.switchMode("fullscreen");
+
+// 切换 / 关闭手机外壳（会重建渲染器并重新加载）
+await simulator.switchPhoneFrame("nexus-5x");
+await simulator.switchPhoneFrame(false);
+
+// 设备预设（联动逻辑视口，仅 resize 不重载）
+simulator.switchDevice("iphone-15-pro-max");
+
+// 直接设置逻辑视口（resize 的语义化别名）
+simulator.setViewport({ width: 430, height: 932 });
+
+// 加载新的小工具 URL（可附带 query）
+await simulator.loadApp("https://cdn.../index.html", { query: { versionId: "v2" } });
+
+// 自动加载 .zip 工具包（解压 + 交 SW 虚拟服务器直供 + 加载，一步到位）
+await simulator.loadZip(zipFile, { jszip: JSZip });
+
+// 加载目录文件表（AI 出码目录产物等无 zip 打包场景）
+await simulator.loadFiles({ "index.html": "<!doctype html>...", "app.js": "..." });
+
+// 能力开关（会重新加载渲染器）
+await simulator.setTouchEmulation(true);
+```
+
+## 加载 .zip 工具包（`loadZip`）
+
+`loadZip` 把「解压 → 原始文件表挂载给 Service Worker（同源虚拟服务器）→ iframe 直连虚拟 URL」收敛为一个实例方法，
+入参支持 `Blob | File | ArrayBuffer | Uint8Array`，返回包解析结果便于业务侧展示。
+> `loadZip` / `loadFiles` 在 `renderer: "iframe-service-worker"`（默认）下可用，需配 `serviceWorker.scriptUrl`。
+
+```ts
+import { createMiniAppSimulator } from "@skillbuilder/miniapp-simulator";
+import JSZip from "jszip"; // 或在全局挂载 window.JSZip（CDN / UMD），不传 jszip 时自动回退
+
+const simulator = createMiniAppSimulator({ mount: "#preview" });
+await simulator.load();
+
+const result = await simulator.loadZip(zipFile, {
+  jszip: JSZip, // JSZip 兼容对象（含静态 loadAsync）；缺失时回退 window.JSZip
+  // entry: "index.html", // 入口 HTML 文件名，默认 index.html
+  // query: { source: "zip-preview" }, // 追加 / 覆盖到加载 URL 的 query
+});
+
+result.files; // 包内文件清单 [{ path, size }]
+result.entry; // 实际命中的入口 HTML 路径
+```
+
+- **技术栈无关**：本包不强依赖 JSZip。通过 `{ jszip }` 注入 JSZip 兼容对象，或在全局挂载 `window.JSZip`；二者皆缺失时抛出 `MiniAppSimulatorError`（code `ZIP_LOAD_FAILED`）。
+- 包内缺少入口 HTML 时抛出 code `ZIP_NO_ENTRY`。
+- 解压后的文件通过 Service Worker 挂载为同源虚拟路径，下次加载或销毁时自动卸载。
+- 解压资源经过 ZIP 路径穿越防护（`..` 条目直接拒绝）。
+
+## 设备能力枚举（`MiniAppCapability` / 元数据）
+
+`deviceCapabilities.sealAllow` 接受 `MiniAppCapability` 枚举值（白名单语义）。支持的能力连同**受控方 / 说明 / 关联 permission**已结构化导出，可直接用于配置面板渲染与白名单校验：
+
+```ts
+import {
+  MiniAppCapability,
+  MINI_APP_CAPABILITIES, // 全量能力元数据表（唯一事实源）
+  SEAL_CONTROLLED_CAPABILITIES, // 受 sealAllow 白名单实际控制的能力
+  HOST_CONTROLLED_CAPABILITIES, // 由宿主层控制的能力（camera / microphone / photo-library）
+  isMiniAppCapability, // 校验单个值是否为合法枚举取值
+  sanitizeCapabilityList, // 清洗 allow 列表：剔除非枚举项 + 去重
+} from "@skillbuilder/miniapp-simulator";
+
+// 渲染「能力开关」面板
+const panel = MINI_APP_CAPABILITIES.map((cap) => ({
+  value: cap.value,
+  label: cap.description,
+  controlledBy: cap.controlledBy, // "seal" 才真正受 sealAllow 控制
+}));
+
+// 把不可信的外部配置归一化后再下发
+await simulator.setDeviceCapabilities({
+  sealAllow: sanitizeCapabilityList(userSelectedCapabilities),
+});
+```
+
+## Debug 调试面板（`debug`）
+
+由模拟器开发者通过入参 `debug: true` 控制开启（默认 `false`，不影响生产消费方）。开启后：
+
+```ts
+const simulator = createMiniAppSimulator({
+  mount: "#preview",
+  debug: true, // 开启内置调试面板
+});
+await simulator.loadApp("https://example.com/demo-app.html");
+```
+
+- **唤起快捷键**：`Shift + Command + U`（macOS）/ `Shift + Ctrl + U`（其他平台）。再次按下或点击右上角 `×` 关闭。
+- **布局**：面板以玻璃拟态形态、`position: fixed` 停靠在**窗口右侧**（类似浏览器 DevTools 右侧停靠），挂在 `document.body`，**不进入模拟器 mount 容器、不压缩或遮挡手机舞台**。
+- 面板包含两个 Tab：
+
+| Tab | 能力 |
+| --- | --- |
+| 能力管控 | 枚举全部 `MiniAppCapability`，按 `seal` / `host` 分组展示当前**放行 / 已封印**状态。每项开关切换即重算 `sealAllow` 白名单并调用 `setDeviceCapabilities` **整页重新加载**小应用（seal 封印为加载期一次性生效）。附「全部放行 / 全部封印 / 恢复默认」。Worker / WebSocket 等由 CSP 指令管控的能力不在此面板，被拦时看 console 的 CSP 违规日志。 |
+| 运行日志 | 订阅模拟器事件流，实时滚动展示生命周期、`console`、`navigation`（被拦截跳转高亮）等关键事件，支持文本过滤、暂停滚动、清空。`network` 事件在采集到时一并展示。 |
+
+> 提示：当焦点位于小应用 iframe 内部时，父文档收不到快捷键，需先点击手机外区域再按快捷键。
+
+## 生命周期事件
+
+| 事件 | 触发时机 | payload |
+| --- | --- | --- |
+| `ready` | 渲染容器初始化完成 | `{ renderer, viewport }` |
+| `beforeLoad` | 即将加载（renderer.load 之前） | `{ url, contentMode, source }` |
+| `load` | URL 加载完成（iframe/webview onload） | `{ url, duration }` |
+| `renderDone` | 小应用首屏渲染完毕（子文档首帧回报） | `{ url, duration }` |
+| `error` / `navigation` / `console` / `network` / `destroy` | 同既有定义 | —— |
+
+`renderDone` 通过 SW 直供 HTML 中注入的 bootstrap 在子文档 `DOMContentLoaded` 后下一帧回报；webview 时以 `load` 近似。
+
+## Shadow DOM 隔离
+
+默认 `shadow: true`，SDK 在 `mount` root 内创建一个宿主元素并 `attachShadow`，手机壳 / 内容层 / 缩放手柄 / 权限 Sheet / REDNote 壳层 / jsapi toast 全部渲染在 shadow root 内，不受消费方页面 CSS 影响，也不会污染宿主页面。需要调试或在不支持 Shadow DOM 的环境运行时可传 `shadow: false` 退化为 light DOM。
+
+## 内容模式（`contentMode`）
+
+通过 `contentMode` 切换手机框内的展示形态：
+
+| `contentMode` | 说明 |
+| --- | --- |
+| `fullscreen`（默认） | 启动即全屏、右侧滑入、顶部返回键；不可下滑收起，点返回键收起露出笔记详情页背景 |
+| `half` | 笔记详情顶栏 + 背景 + **底部半屏 Sheet 内嵌 iframe**；下滑收起、上滑展开全屏 |
+
+```ts
+import { createMiniAppSimulator } from "@skillbuilder/miniapp-simulator";
+
+// 半屏：小工具在半屏 iframe 中打开
+const halfSimulator = createMiniAppSimulator({
+  mount: "#preview",
+  contentMode: "half",
+  notePreview: {
+    user: { avatar: "https://...", nickname: "Purple阿紫" },
+    title: "笔记标题",
+    descHtml: "正文",
+    images: [{ url: "https://...", ratio: 1 }],
+  },
+  rednoteDetail: {
+    heightRatio: 0.85,
+    placeholderText: "部署成功后可预览",
+  },
+  viewport: { width: 390, height: 844 },
+});
+
+// 全屏：小工具占满设备、右侧滑入
+const fullscreenSimulator = createMiniAppSimulator({
+  mount: "#full-preview",
+  contentMode: "fullscreen",
+  viewport: { width: 390, height: 844 },
+});
+
+// 先出壳层（无入口时半屏显示 placeholderText「部署成功后可预览」）
+await halfSimulator.load();
+// 有入口时加载进半屏 iframe
+await halfSimulator.loadApp("http://127.0.0.1:5173/demo-app.html");
+
+// 运行时更新壳层数据（无需 reload）
+halfSimulator.notePreview.update({ title: "新标题" });
+
+// 仅切换顶栏用户头像与昵称
+halfSimulator.notePreview.updateUser({
+  avatar: "https://example.com/avatar.png",
+  nickname: "Purple阿紫",
+});
+
+// 切换 contentMode 会自动 reload
+halfSimulator.updateConfig({ contentMode: "fullscreen" });
+await halfSimulator.loadApp("https://example.com/demo-app.html");
+```
+
+手机外壳是模拟器内置能力，**默认无贴图外壳**（`phoneFrame: false`），保留标准深色圆角边框。需要贴图壳时再传：
+
+```ts
+createMiniAppSimulator({
+  mount,
+  phoneFrame: "iphone-14-pro-max", // 或 "nexus-5x"
+});
+
+// 运行时也可切换外壳（会重建渲染器并重新加载）
+await simulator.switchPhoneFrame("iphone-14-pro-max");
+```
+
+`phoneFrame: false`（无贴图外壳）时，模拟器内置创作发布同款标准设备边框：
+
+- 颜色：`rgba(0, 0, 0, 0.65)`（`--color-text-paragraph`）
+- 分档：与 ImagePreview / CoverPreview `@media` 一致（1439 / 1440 / 1680 / 1920 / 2285）
+- 缩放：按逻辑 viewport 高度相对各档 `shellHeight`（442 / 552 / 662 / 729 / 868）等比放大
+
+窗口 resize 时自动重算分档。
+
+## stageFit（自适应缩放）
+
+默认开启：模拟器会按 mount 区域 **100% 撑满**自适应（`scaleMultiplier: 1`、`capToBounds: true`），父容器尺寸变化时通过 `ResizeObserver` 自动重算。
+
+手动拖拽缩放（playground 右上角手柄）需显式开启：
+
+```ts
+createMiniAppSimulator({
+  mount,
+  stageFit: {
+    resizeHandle: true,
+    // 可选：与 playground 一致保持居中且不溢出
+    centerInBounds: true,
+    capToBounds: true,
+  },
+});
+```
+
+传 `stageFit: false` 可关闭自适应，设备保持逻辑 viewport 原始像素尺寸。

package/docs/server-playground-https-debugging.md

@@ -0,0 +1,150 @@
+# Simulator Server Playground 本地 HTTPS 与 AI 联调
+
+这份文档用于联调 `miniapp-simulator-server`、`miniapp-simulator` 和 AI SDK。推荐入口是：
+
+```text
+https://local.devops.sit.xiaohongshu.com:5176/ai-chat
+```
+
+本地链路由两个进程组成：
+
+```text
+小应用 → xhs.AI → Bridge → Simulator 宿主 request
+      → 5176 HTTPS Playground / Vite proxy
+      ├─ /simulator-dev/*、/simulator/runtime-config → 127.0.0.1:5174
+      └─ Creator AI path → Creator beta 独立泳道
+```
+
+`5174` 提供 Simulator Runtime，`5176` 承载 Playground、Service Worker 和本地代理。AI SDK 始终通过 Bridge 调用容器注入的宿主 `request` 能力；本地代理只是宿主 request 在开发环境中的网络实现，不是 SDK API，也没有 `/api/host-request` 业务协议层。
+
+## 1. 首次配置
+
+以下步骤从 `skill-designable-kit` 仓库根目录执行。
+
+### 1.1 配置本地域名
+
+在 `/etc/hosts` 增加：
+
+```text
+127.0.0.1 local.devops.sit.xiaohongshu.com
+```
+
+macOS 可用下面的命令检查解析结果：
+
+```bash
+dscacheutil -q host -a name local.devops.sit.xiaohongshu.com
+```
+
+结果应包含 `127.0.0.1`。修改 hosts 后无需把本地域名映射到真实的 beta 服务。
+
+### 1.2 启动 Simulator Server
+
+终端 A：
+
+```bash
+pnpm --filter @skillbuilder/miniapp-simulator-server dev
+```
+
+该进程监听 `127.0.0.1:5174`，提供本地 Runtime、Service Worker 和运行时配置。已经构建过 Runtime、只改服务端代码时可以使用：
+
+```bash
+pnpm --filter @skillbuilder/miniapp-simulator-server dev:fast
+```
+
+### 1.3 启动 HTTPS Playground
+
+终端 B：
+
+```bash
+pnpm --filter @skillbuilder/miniapp-simulator-server-playground dev:https
+```
+
+首次启动会在 Playground 的 `node_modules/.vite/basic-ssl-devops/` 下生成本地证书。Vite 监听 `0.0.0.0:5176`，但浏览器应使用带证书域名的地址访问。
+
+### 1.4 信任本地证书
+
+终端 C，仅首次生成证书或证书重新生成后执行：
+
+```bash
+pnpm --filter @skillbuilder/miniapp-simulator-server-playground trust:https
+```
+
+该脚本会在 macOS 登录钥匙串中信任证书，系统可能要求输入密码。执行后完全退出并重新打开 Chrome，再访问：
+
+```text
+https://local.devops.sit.xiaohongshu.com:5176/ai-chat
+```
+
+只在 Chrome 证书警告页点击“继续访问”不够。页面虽然可能打开，但该 Origin 仍不满足 Service Worker 的可信上下文要求，Demo 会表现为 Runtime 脚本加载失败。
+
+Windows/Linux 暂无自动信任脚本，需要从
+`apps/miniapp-simulator-server-playground/node_modules/.vite/basic-ssl-devops/_cert.pem` 提取
+`BEGIN CERTIFICATE` 到 `END CERTIFICATE` 段，再导入系统或浏览器信任库；不要导入同文件中的私钥段。
+
+## 2. 日常启动与自检
+
+日常只需启动两个进程：
+
+```bash
+# 终端 A
+pnpm --filter @skillbuilder/miniapp-simulator-server dev
+
+# 终端 B
+pnpm --filter @skillbuilder/miniapp-simulator-server-playground dev:https
+```
+
+打开 `/ai-chat` 后，Network 面板应看到以下请求成功：
+
+| 请求 | 预期 | 作用 |
+| --- | --- | --- |
+| `GET /simulator-dev/runtime-manifest` | 200 | 薄 SDK 获取本地 Runtime 地址 |
+| `GET /simulator-dev` | 200 | Runtime 容器页面 |
+| `GET /simulator-dev/runtime.js` | 200 | 本地 Runtime 脚本 |
+| `GET /simulator-dev/sw.js` | 200 | 宿主 request 使用的 Service Worker |
+| `POST /simulator/runtime-config` | 200 | 容器运行时配置与宿主能力下发 |
+
+可用下面的命令先验证 5176 与证书服务是否可访问；`-k` 只用于命令行探活，不代表浏览器已信任证书：
+
+```bash
+curl -kI https://local.devops.sit.xiaohongshu.com:5176/ai-chat
+curl -kI https://local.devops.sit.xiaohongshu.com:5176/simulator-dev/runtime-manifest
+```
+
+## 3. Creator AI 独立泳道联调
+
+当前 `/ai-chat` 的 Creator AI 地址只用于本地开发，不进入 AI SDK 的线上默认配置。联调流程如下：
+
+1. 在已登录的 Creator beta 页面找到一条能够请求独立泳道的 AI 请求。
+2. 在 DevTools Network 中选择 **Copy as cURL**。
+3. 把完整 cURL 粘贴到 `/ai-chat` 的 “Creator cURL” 输入框并应用。
+4. 页面提取并展示 `Cookie`、`Origin`、`Referer`、`x-s`、`x-s-common`、`x-t` 和 `x-minitool-appid`。
+5. 触发非流式 Demo，确认请求体和 `x-minitool-appid` 仍由 AI SDK 生成，鉴权信息由 5176 的 Vite proxy 恢复到上游请求。
+
+页面会把 cURL 和 appId 存在当前浏览器的 `localStorage`，方便刷新后继续调试。它们是可见的开发凭据：不要提交到 Git、粘贴到公共文档或用于线上配置，调试完成后点击“清空鉴权”。
+
+签名和 Cookie 都可能过期。出现 `HTTP 401` 或“无登录信息”时，应从 Creator 页面重新复制一条刚刚成功的 cURL，不要只替换单个签名字段。
+
+本期 AI SDK 业务验收只覆盖非流式调用；流式 Case 仅用于观察 Simulator/Bridge 能力，不作为本期上线结论。
+
+## 4. 常见问题
+
+| 现象 | 原因 | 处理方式 |
+| --- | --- | --- |
+| 页面显示“不安全”，Demo 全部加载失败 | 证书未被系统信任，Service Worker 无法注册 | 先运行 `dev:https` 生成证书，再运行 `trust:https`，完全重启 Chrome |
+| 证书过期或域名不匹配 | 本地证书已过期，或证书不是为当前域名生成 | 停止 5176，删除 `node_modules/.vite/basic-ssl-devops/` 后重新运行 `dev:https` 和 `trust:https` |
+| `An unknown error occurred when fetching the script` | 5174 未启动、Runtime 产物未构建，或 Service Worker 仍使用旧缓存 | 启动 5174；重启 5176；必要时在 Application → Service Workers 注销旧 Worker 并清除此站点数据 |
+| `/simulator-dev/runtime.js` 或 `/sw.js` 返回 503 | 本地 Runtime 产物不存在 | 使用普通 `dev`/`dev:https` 先执行构建，不要直接使用跳过构建的启动方式 |
+| `Blocked request. This host ... is not allowed` | 使用了旧 Vite 配置或改完配置后未重启 | 更新代码并重启 5176；当前 `allowedHosts` 已包含 `local.devops.sit.xiaohongshu.com` |
+| AI 请求 401 / “无登录信息” | cURL 未带完整 Cookie，或 Cookie/签名已过期 | 回到已登录 Creator 页面重新 Copy as cURL 并完整粘贴 |
+| `Origin-Agent-Cluster` 警告 | 同一 Origin 曾以不同响应头打开，浏览器保留了旧站点状态 | 关闭该 Origin 的所有标签页，清除站点数据后重新打开；该警告本身不等于 AI 请求失败 |
+| `favicon.ico` 404 | Playground 没有 favicon | 可忽略，不影响 Runtime、Bridge 或 AI 请求 |
+| Chrome 顶部提示使用不受支持的命令行标记 | 曾启用 `Insecure origins treated as secure` | 在 `chrome://flags/#unsafely-treat-insecure-origin-as-secure` 清空地址并选择 Disabled，然后重启；本链路使用真实 HTTPS 证书，不需要该 flag |
+
+如果页面能加载但按钮点击后像是刷新，先在 Network 面板确认是否重新请求了页面文档。独立 Case 中的按钮必须使用 `type="button"`，表单提交事件需要调用 `preventDefault()`；这类问题与 HTTPS 和 AI 鉴权无关。
+
+## 5. 边界说明
+
+- `miniToolEnv.gateways` 由宿主按环境注入；AI SDK 不负责判断审核、创服或真机域名。
+- 小应用只使用 `xhs.AI.createModel(...)` 和 AI SDK API，不读取 Cookie，也不感知 Vite proxy。
+- Simulator 本地独立泳道通过粘贴 cURL 恢复 Creator 登录上下文，仅供开发。
+- VibeCreator Builder 的正式链路应由网关校验 VibeCreator 扫码 session，并在服务端置换下游登录态；浏览器不持有下游 Cookie。

package/docs/storage-api-design.md

@@ -0,0 +1,275 @@
+# 模拟器 Storage API 设计
+
+## 1. 背景与目标
+
+模拟器需要向小工具提供与客户端调用方式一致的异步 Storage API，使业务代码可以在本地、远程预览等场景完成缓存写入、读取、删除、容量查询和清空操作。
+
+本文描述当前实现的接口、数据模型、隔离规则、容量计算、并发语义和安全边界，作为联调、测试与后续演进的统一依据。
+
+设计目标：
+
+- 对外暴露 `xhs.miniTool` 下的 5 个异步 Storage API；
+- 默认实现由模拟器 Core 提供，本地和远程模式保持一致的存储行为；
+- 数据在页面刷新后仍可读取，并按小工具维度隔离；
+- 对单条数据和单个 scope 的总量进行容量控制；
+- 宿主可按 API 名覆盖默认实现，以接入平台侧存储能力。
+
+非目标：
+
+- 不提供同步 Storage API；
+- 不提供 TTL、批量事务、变更订阅和跨设备同步；
+- 不将 `encrypt` 实现为密码学加密；
+- 不在默认 scope 中提供用户级隔离。
+
+## 2. 总体架构
+
+```text
+小工具业务代码
+  │  xhs.miniTool.setStorage / getStorage / ...
+  ▼
+miniapp-js-api
+  │  Bridge invoke(event, options)
+  ▼
+模拟器 Bridge / Remote Host API Bridge
+  │  按 event 分发；宿主同名 handler 可覆盖
+  ▼
+createSimulatorStorageHostApi
+  │  参数校验、JSON 复制、配额、写操作排队
+  ▼
+SimulatorStorageRepository
+  ▼
+当前 Runtime origin 的 IndexedDB
+```
+
+Storage 属于模拟器 Core 的默认 JSAPI。业务侧只依赖 `xhs.miniTool`，不直接访问 IndexedDB。这样可以统一接口校验、隔离 scope、容量规则和错误语义，同时保留宿主替换底层实现的能力。
+
+默认仓储使用 IndexedDB，而不使用 `localStorage`，原因是 Storage API 本身是异步接口，IndexedDB 不阻塞主线程，容量和数据组织能力也更适合 10 MiB 级别的数据。数据仍受浏览器 origin 存储边界和浏览器清理策略约束。
+
+## 3. API 设计
+
+所有接口都支持 Promise 调用方式以及 SDK 的 `success`、`fail`、`complete` 回调约定。本文示例使用 Promise。
+
+| API | 入参 | 成功结果 | 行为 |
+| --- | --- | --- | --- |
+| `setStorage` | `key: string`、`data: unknown`、`encrypt?: boolean` | `{}` | 新增或覆盖当前 scope 下的 key |
+| `getStorage` | `key: string`、`encrypt?: boolean` | `{ data: unknown }` | 读取当前 scope 下的 key；不存在时返回 `data: null` |
+| `removeStorage` | `key: string` | `{}` | 删除当前 scope 下的 key；key 不存在也成功 |
+| `getStorageInfo` | 无业务入参 | `{ keys, usedBytes, limitBytes }` | 返回排序后的 key 和容量信息，容量单位为字节 |
+| `clearStorage` | 无业务入参 | `{}` | 只清空当前 scope 的全部 key |
+
+### 3.1 写入与读取示例
+
+```ts
+await window.xhs.miniTool.setStorage({
+  key: "profile",
+  data: { nickname: "小红薯", tags: ["旅行", "摄影"] },
+});
+
+const { data } = await window.xhs.miniTool.getStorage({
+  key: "profile",
+});
+```
+
+### 3.2 删除、查询容量与清空
+
+```ts
+await window.xhs.miniTool.removeStorage({ key: "profile" });
+
+const { keys, usedBytes, limitBytes } =
+  await window.xhs.miniTool.getStorageInfo();
+
+await window.xhs.miniTool.clearStorage();
+```
+
+## 4. 数据模型与持久化
+
+默认实现使用如下 IndexedDB 结构：
+
+| 配置项 | 值 |
+| --- | --- |
+| Database | `miniapp-simulator-storage` |
+| Version | `1` |
+| Object Store | `entries` |
+| 主键 | `[scope, key]` 复合主键 |
+| 索引 | `by_scope`，字段为 `scope`，非唯一 |
+
+每条记录结构如下：
+
+```ts
+interface SimulatorStorageRecord {
+  scope: string;
+  key: string;
+  data: unknown;
+  sizeBytes: number;
+  encrypted: boolean;
+}
+```
+
+- `scope`：模拟器计算出的逻辑隔离标识；
+- `key`：业务传入的非空字符串；
+- `data`：经过 JSON 序列化再反序列化后的值；
+- `sizeBytes`：序列化后数据的 UTF-8 字节数；
+- `encrypted`：写入时的 `encrypt` 标记，仅用于读取一致性校验。
+
+数据库归属于当前 Runtime origin。浏览器刷新不会主动清空数据；清理站点数据、无痕会话结束、浏览器配额回收或 Runtime origin 变化都可能导致数据不可用。
+
+## 5. 隔离模型
+
+### 5.1 scope 生成规则
+
+| 运行方式 | scope |
+| --- | --- |
+| 模拟器 Core 默认模式 | `JSON.stringify(["app", appId])` |
+| 远程 Runtime 模式 | `JSON.stringify([businessLine, appId])` |
+
+Core 模式未传有效 `appId` 时会生成当前挂载实例的随机 ID。这种情况下刷新或重新创建实例不能依赖原 scope 复用数据；需要稳定持久化时必须传入稳定的 `appId`。
+
+复合主键 `[scope, key]` 保证不同 scope 下可以存在同名 key，`getStorageInfo` 和 `clearStorage` 也只作用于当前 scope。
+
+### 5.2 用户隔离边界
+
+默认 scope 不包含用户 ID。同一 Runtime origin 下，只要 `businessLine` 和 `appId` 相同，不同登录账号会访问同一份模拟器缓存。因此不得使用默认 Storage 保存账号令牌、密码或其他需要按用户强隔离的敏感数据。
+
+需要用户级隔离时，接入方应选择以下方案之一：
+
+- 在账号退出或切换时调用 `clearStorage`；
+- 在业务 key 中加入经过规范化的用户维度；
+- 通过宿主同名 Host API 覆盖默认实现，在宿主存储层实现用户级命名空间和生命周期管理。
+
+## 6. 序列化语义
+
+`setStorage` 通过 `JSON.stringify(data)` 生成用于计费和保存的值，再通过 `JSON.parse` 生成 JSON 兼容副本。业务读取到的是 JSON 语义下的副本，不是写入对象的引用。
+
+| 输入类型 | 结果 |
+| --- | --- |
+| string、number、boolean、null、普通对象、数组 | 按 JSON 语义保存 |
+| `Date` | 保存为 ISO 字符串 |
+| 对象属性中的 `undefined`、function、symbol | 该属性被忽略 |
+| 数组元素中的 `undefined`、function、symbol | 转换为 `null` |
+| `NaN`、`Infinity`、`-Infinity` | 转换为 `null` |
+| 根值为 `undefined`、function 或 symbol | 拒绝写入，错误码 `10001` |
+| `BigInt` 或循环引用 | 拒绝写入，错误码 `10001` |
+
+`key` 当前只校验为非空字符串，不进行 trim、字符集限制或长度限制。调用方应使用稳定、可读且带业务前缀的 key，避免空白 key、超长 key 和非预期覆盖。
+
+## 7. 容量与计费
+
+容量按 `JSON.stringify(data)` 结果的 UTF-8 字节数计算，不包含 key、scope 和记录元数据。
+
+| 限制 | 数值 | 失败错误码 |
+| --- | --- | --- |
+| 单条数据 | 1 MiB，即 `1 * 1024 * 1024` 字节 | `50201` |
+| 单个 scope 总量 | 10 MiB，即 `10 * 1024 * 1024` 字节 | `50201` |
+
+覆盖已有 key 时，总量计算公式为：
+
+```text
+写入后总量 = 当前总量 - 旧值字节数 + 新值字节数
+```
+
+因此覆盖不会重复计算旧值。`getStorageInfo` 返回：
+
+- `keys`：当前 scope 的全部 key，按字符串排序；
+- `usedBytes`：当前 scope 已使用的字节数；
+- `limitBytes`：固定为 `10485760`，即 10 MiB。
+
+## 8. 并发与一致性
+
+同一个 `createSimulatorStorageHostApi` 实例内，`setStorage`、`removeStorage` 和 `clearStorage` 进入同一条 mutation queue，按进入队列的顺序串行执行。某次写操作失败后，队列会继续处理后续操作，不会永久阻塞。
+
+`getStorage` 和 `getStorageInfo` 不进入写队列，可以并发执行。业务代码如果需要“写后立即读”的确定性，必须等待写 Promise 完成：
+
+```ts
+await window.xhs.miniTool.setStorage({ key: "draft", data: payload });
+const { data } = await window.xhs.miniTool.getStorage({ key: "draft" });
+```
+
+以下情况不提供全局串行保证：
+
+- 未等待 `setStorage` 完成就发起读取；
+- 多个 Storage Host API 实例同时操作同一 scope；
+- 多个页面或标签页共享同一 origin 和 scope。
+
+这些场景下 IndexedDB 负责事务原子性，但“先统计总量、再写入”的配额判断不是跨实例原子事务。接入方不应依赖并发写入时的严格全局顺序。
+
+## 9. `encrypt` 语义与安全边界
+
+> `encrypt: true` 在模拟器默认实现中不执行密码学加密，也不会改变 IndexedDB 中 `data` 的明文表示。
+
+当前实现只把 `encrypt` 保存为布尔元数据。`getStorage` 必须传入与 `setStorage` 相同的值：
+
+```ts
+await window.xhs.miniTool.setStorage({
+  key: "settings",
+  data: { theme: "dark" },
+  encrypt: true,
+});
+
+const { data } = await window.xhs.miniTool.getStorage({
+  key: "settings",
+  encrypt: true,
+});
+```
+
+读写标记不一致时读取失败。该行为用于兼容客户端接口约定，不能作为数据保密能力。敏感数据应由宿主覆盖 Storage handler，并在可信边界内完成密钥管理、加解密和用户隔离；业务层也不应把凭证、私钥或长期令牌写入模拟器默认 Storage。
+
+## 10. 错误处理
+
+| 场景 | 错误码 | 说明 |
+| --- | --- | --- |
+| key 缺失、为空或不是字符串 | `10001` | `INVALID_PARAM` |
+| data 缺失、根值为 `undefined` 或不可 JSON 序列化 | `10001` | `INVALID_PARAM` |
+| encrypt 不是 boolean | `10001` | `INVALID_PARAM` |
+| 单条或 scope 总量超限 | `50201` | `STORAGE_QUOTA_EXCEEDED` |
+| getStorage 的 encrypt 与写入标记不一致 | 暂无稳定错误码 | Promise reject，错误信息说明标记不一致 |
+| IndexedDB 打开、阻塞或请求失败 | 暂无稳定错误码 | 底层错误经 Bridge 透传 |
+
+枚举中已定义 `50101 STORAGE_IO_ERROR`，默认 Storage 仓储当前未把 IndexedDB 异常统一归一化到该错误码。调用方应以 Promise reject 或 `fail` 回调作为失败判断，不应只依赖错误文案。
+
+## 11. 宿主覆盖机制
+
+模拟器先注册默认 Storage handlers，再合并宿主提供的同名 Host API。宿主实现可覆盖任意一个或全部 Storage API，用于接入客户端存储、用户隔离、加密、审计或其他平台能力。
+
+覆盖实现必须保持以下对外契约：
+
+- API 名和异步调用方式不变；
+- 参数校验、缺失 key、幂等删除等行为与本文一致；
+- `getStorageInfo` 的容量单位为字节；
+- 错误通过 reject 返回，并尽量使用统一错误码；
+- 同一 scope 内的隔离和清理行为可预测。
+
+部分覆盖时需要特别谨慎。例如只覆盖 `setStorage` 而保留默认 `getStorage`，会造成读写落在不同存储后端。推荐成组覆盖 5 个接口。
+
+## 12. 生命周期与清理
+
+- 模拟器实例销毁不会清空 IndexedDB；
+- 页面刷新不会清空稳定 scope 的数据；
+- `removeStorage` 只删除一个 `[scope, key]`；
+- `clearStorage` 先按 `by_scope` 找到复合主键，再删除当前 scope 的全部记录；
+- 其他 app、businessLine 或 scope 的数据不会被 `clearStorage` 删除；
+- 浏览器站点数据清理和存储回收属于 Runtime 环境能力，模拟器不承诺永久持久化。
+
+## 13. 验收清单
+
+- 5 个异步 API 均可通过 Promise 和回调调用；
+- 写入后等待 Promise，再读取可得到 JSON 兼容副本；
+- 相同 key 在不同 scope 下互不影响；
+- 缺失 key 返回 `{ data: null }`；
+- 删除不存在的 key 成功；
+- 单条超过 1 MiB、总量超过 10 MiB 时返回 `50201`；
+- 覆盖已有 key 时正确扣除旧值容量；
+- `getStorageInfo.keys` 有序，容量单位和取整方式正确；
+- 同实例写操作按调用顺序执行，失败后队列仍可继续；
+- `clearStorage` 只清理当前 scope；
+- `encrypt` 一致时可读，不一致时失败；
+- 文档和用例明确 `encrypt` 不提供真实加密；
+- 宿主覆盖时 5 个接口使用同一后端和隔离规则。
+
+## 14. 代码位置
+
+- 默认实现：`packages/miniapp-simulator/src/runtime/storage-host-api.ts`
+- Core 注册：`packages/miniapp-simulator/src/core/simulator.ts`
+- 远程 Runtime 注册：`packages/miniapp-simulator/src/remote/runtime.ts`
+- SDK API：`packages/miniapp-js-api/src/apis/storage/`（已随包外移）
+- JSON Schema：`packages/miniapp-js-api/src/schemas/*Storage*.schema.json`（已外移）
+- 测试：`packages/miniapp-simulator/tests/remote-storage.test.ts`