@skillbuilder/miniapp-simulator 0.0.0-stage → 0.2.0

package/docs/remote-usage.md

@@ -0,0 +1,371 @@
+# Miniapp Simulator 远程模式接入与使用指南
+
+## 1. 接入前准备
+
+宿主页面需要满足：
+
+- 使用 HTTPS；本地 Simulator Server 调试可使用 `http://localhost` 或 `http://127.0.0.1`。
+- CSP 的 `connect-src` 放行 Simulator origin，用于请求 `/simulator/runtime-manifest`。
+- CSP 的 `frame-src` 放行 Simulator origin，用于加载远端 Runtime iframe。
+- 网关不能给 Simulator 页面附加 `X-Frame-Options: SAMEORIGIN`。
+
+业务接入使用以下服务地址：
+
+| 环境 | `serviceUrl` |
+| --- | --- |
+| 本地业务联调、SIT、Staging | `https://miniapp-sandbox.beta.xiaohongshu.com/simulator/` |
+| Production | `https://miniapp-sandbox.xiaohongshu.com/simulator/` |
+| Simulator Server 本地开发 | `http://127.0.0.1:5174/simulator/` |
+
+建议由业务项目封装环境映射，不要在每个页面重复判断。
+
+## 2. 最小接入
+
+```ts
+import {
+  BusinessLine,
+  createRemoteMiniAppSimulator,
+  type RemoteMiniAppSimulator,
+} from "@skillbuilder/miniapp-simulator/remote";
+
+const simulator: RemoteMiniAppSimulator = createRemoteMiniAppSimulator({
+  mount: document.querySelector("#simulator")!,
+  serviceUrl:
+    process.env.NODE_ENV === "production"
+      ? "https://miniapp-sandbox.xiaohongshu.com/simulator/"
+      : "https://miniapp-sandbox.beta.xiaohongshu.com/simulator/",
+  appId: "current-miniapp-id",
+  businessLine: BusinessLine.creator,
+  tracker: true,
+  gateway: {
+    edith: "https://edith.xiaohongshu.com",
+    www: "https://www.xiaohongshu.com",
+  },
+  hostApi: {
+    getUserInfo: async () => ({
+      userId: "current-user-id",
+      nickname: "当前用户",
+      avatar: "https://example.com/avatar.png",
+    }),
+  },
+  options: {
+    contentMode: "fullscreen",
+    viewport: { width: 390, height: 844 },
+    phoneFrame: false,
+    touchEmulation: true,
+    stageFit: false,
+  },
+});
+
+simulator.on("error", error => {
+  console.error("[miniapp-simulator]", error);
+});
+
+await simulator.ready;
+```
+
+参数分层：
+
+| 参数 | 位置 | 含义 |
+| --- | --- | --- |
+| `gateway` | 顶层 | 注入 `miniToolEnv.gateways` 的网关对象；包含 `edith`、`www`，后续可继续扩展其他网关 |
+| `mount` | 顶层 | 宿主挂载节点 |
+| `serviceUrl` | 顶层 | Simulator Server 入口 |
+| `fallbackServiceUrls` | 顶层 | 主服务失败后的独立备用服务 |
+| `appId` | 顶层 | 当前小应用 ID，同时参与远端策略匹配 |
+| `businessLine` | 顶层、必填 | `BusinessLine` 枚举值，用于默认 Host API、策略、打点和 AI 服务路由 |
+| `tracker` | 顶层 | 是否启用 Runtime 打点 |
+| `hostApi` | 顶层 | 运行在宿主 Realm 的自定义 Bridge 实现 |
+| `options` | 内层 | 可序列化的模拟器显示和交互配置 |
+
+`BusinessLine` 提供 `skillDesignable`、`creator`、`mars`、`dev` 四个成员，值分别为
+`skill-designable`、`creator`、`mars`、`dev`。
+
+`renderer`、`serviceWorker`、`security`、`jsapi`、`runtimeLimits` 不由宿主传入。它们由远端
+Runtime、Service Worker 和 Apollo 统一管理。
+
+Runtime 会在连接时按 `appId`、用户 ID 和 `businessLine` 请求一次统一配置，取得 CSP、性能保护和
+JSAPI 配置。`businessLine` 缺失或为空时薄 SDK 会拒绝创建实例。
+
+远端配置的作用规则：
+
+- `unsupported` 只调整明确不支持或没有 handler 的 JSAPI 提示，不影响已有实现。
+- API 名称可精确覆盖对应实现，例如 `postNote`；支持 `{ toast: "文案" }` 或
+  `{ alert: "文案" }`，两者同时存在时 Alert 优先。
+- 精确配置只展示提示并成功返回 `{}`，不会生成 API 专属返回字段。
+- 优先级为：宿主 `hostApi` → 单 API 远端配置 → `unsupported` → Runtime 默认行为。
+- 配置在实例连接 Runtime 时读取；配置更新后需要新建模拟器实例才能取得新值。
+
+## 3. 加载小应用
+
+### 加载 ZIP
+
+```ts
+const response = await fetch(zipUrl);
+const zipBlob = await response.blob();
+
+const result = await simulator.loadZip(zipBlob);
+console.log(result.entry, result.files);
+```
+
+远程模式的 Runtime 已内置 JSZip，宿主不需要传入 `jszip`。ZIP 不上传 Node 服务，直接从宿主浏览器
+传给 Runtime 并在浏览器内解压。
+
+### 加载文件表
+
+```ts
+await simulator.loadFiles({
+  "index.html": "<!doctype html><div id=\"app\"></div><script src=\"./app.js\"></script>",
+  "app.js": "document.querySelector('#app').textContent = 'Hello';",
+});
+```
+
+### 加载远程页面
+
+```ts
+await simulator.loadApp("https://example.com/miniapp/index.html", {
+  query: { source: "creator-preview" },
+});
+```
+
+### 只加载模拟器壳层
+
+```ts
+await simulator.load();
+```
+
+适用于半屏模式的空态、Permission Sheet 或 Note Preview 调试。
+
+## 4. 宿主 Host API
+
+函数不能序列化到跨域 iframe。薄 SDK 会在宿主保留函数，通过 MessageChannel 接收 Runtime 请求并执行：
+
+```ts
+const simulator = createRemoteMiniAppSimulator({
+  mount,
+  serviceUrl,
+  appId,
+  businessLine: BusinessLine.creator,
+  hostApi: {
+    getUserInfo: async () => ({
+      userId: currentUser.id,
+      nickname: currentUser.nickname,
+      avatar: currentUser.avatar,
+    }),
+    postNote: async request => {
+      return publishFromCreator(request.message);
+    },
+    openRedPage: async request => {
+      return openCreatorPage(request.message);
+    },
+  },
+});
+```
+
+规则：
+
+- `getUserInfo` 是 userId 的统一来源；不要单独传 tracker userId。
+- Runtime 会先注册 `businessLine` 对应的默认行为，再用宿主 `hostApi` 覆盖同名实现。
+- 宿主可以在运行期调用 `simulator.hostApi.set()`、`registerAll()`、`remove()` 或 `clear()`。
+- `appId`、`userId`、`businessLine` 会用于 Apollo CSP 和性能策略匹配；这些字段属于模拟器配置上下文，
+  不应作为服务端安全鉴权凭据。
+
+Runtime 内置 `setStorage`、`getStorage`、`getStorageInfo`、`removeStorage`、`clearStorage` 默认实现。
+数据持久化在 Simulator origin 的 IndexedDB，按 `businessLine + appId` 隔离；单 key 上限 1MB，
+每个小工具总上限 10MB。实现随远端 Runtime release 发布，宿主无需升级薄 SDK；如宿主注册同名
+`hostApi`，仍按上述优先级覆盖默认实现。
+
+## 5. 常用实例能力
+
+```ts
+simulator.setViewport({ width: 430, height: 932 });
+
+await simulator.switchContentMode("half");
+await simulator.switchPhoneFrame(false);
+await simulator.reload();
+
+simulator.notePreview.update({ title: "新的笔记标题" });
+simulator.notePreview.updateUser({ nickname: "新的用户昵称" });
+simulator.notePreview.updateAppCard({ name: "小工具名称" });
+
+await simulator.permissionSheet.show(["camera", "microphone"]);
+simulator.permissionSheet.hide();
+
+simulator.inspector.enable();
+simulator.inspector.setSelectionMode("multiple");
+const sceneTree = await simulator.inspector.getSceneTree();
+
+const image = await simulator.capture({ fullPage: false });
+```
+
+使用 `ready.capabilities` 判断远端 Runtime 是否支持可选能力：
+
+```ts
+const ready = await simulator.ready;
+if (ready.capabilities.includes("capture")) {
+  const image = await simulator.capture();
+}
+```
+
+## 6. 事件订阅
+
+```ts
+const unsubscribeError = simulator.on("error", error => {
+  console.error(error.code, error.message);
+});
+
+const unsubscribeRender = simulator.on("renderDone", event => {
+  console.log("rendered", event.duration);
+});
+
+const unsubscribeSelection = simulator.on("elementSelected", selection => {
+  console.log(selection);
+});
+
+const unsubscribeConsole = simulator.on("console", event => {
+  console[event.level](event.message);
+});
+
+// 页面不再需要订阅时主动解除。
+unsubscribeError();
+unsubscribeRender();
+unsubscribeSelection();
+unsubscribeConsole();
+```
+
+常用事件包括：`load`、`renderDone`、`error`、`navigation`、`console`、`guestError`、
+`performance`、`elementSelected`、`inspectorChange`。
+
+## 7. React 接入
+
+```tsx
+function MiniappPreview({ appId, zip }: { appId: string; zip?: Blob }) {
+  const mountRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!mountRef.current) return;
+    let disposed = false;
+
+    const simulator = createRemoteMiniAppSimulator({
+      mount: mountRef.current,
+      serviceUrl: SIMULATOR_SERVICE_URL,
+      appId,
+      businessLine: BusinessLine.creator,
+      tracker: true,
+      hostApi: {
+        getUserInfo: async () => getCurrentUser(),
+      },
+      options: {
+        contentMode: "fullscreen",
+        viewport: { width: 390, height: 844 },
+        phoneFrame: false,
+      },
+    });
+
+    void simulator.ready
+      .then(() => (zip ? simulator.loadZip(zip) : simulator.load()))
+      .catch(error => {
+        if (!disposed) console.error(error);
+      });
+
+    return () => {
+      disposed = true;
+      simulator.destroy("unmount");
+    };
+  }, [appId, zip]);
+
+  return <div ref={mountRef} style={{ width: "100%", height: "100%" }} />;
+}
+```
+
+注意：
+
+- React 开发模式可能执行挂载、卸载、重新挂载，用 `disposed` 忽略已经销毁实例的异步结果。
+- 清理函数必须调用 `destroy()`，否则 iframe、MessagePort 和 SW ZIP 文件可能继续占用资源。
+- 频繁变化的 viewport 不要重建实例，使用 `setViewport()`。
+- `appId` 改变时应创建新实例，避免策略、打点和 FS scope 混用。
+
+## 8. 同页多个模拟器
+
+```ts
+const simulators = apps.map((app, index) =>
+  createRemoteMiniAppSimulator({
+    mount: mounts[index],
+    serviceUrl,
+    appId: app.id,
+    businessLine: BusinessLine.creator,
+    options: { viewport: { width: 390, height: 844 } },
+  }),
+);
+
+await Promise.all(simulators.map((simulator, index) => simulator.loadZip(apps[index].zip)));
+
+// 页面退出时逐个销毁。
+for (const simulator of simulators) simulator.destroy("page-unmount");
+```
+
+每个实例拥有独立外层 iframe、sessionId、MessageChannel 和 mountId。同 release 最多同时挂载 16 个
+小应用。Web 模式的数据隔离不等于进程隔离；需要逐实例硬内存配额时使用 Electron。
+
+## 9. 服务降级
+
+```ts
+const simulator = createRemoteMiniAppSimulator({
+  mount,
+  serviceUrl: PRIMARY_SIMULATOR_SERVICE_URL,
+  fallbackServiceUrls: [BACKUP_SIMULATOR_SERVICE_URL],
+  appId,
+  businessLine: BusinessLine.creator,
+});
+```
+
+备用地址必须是实际独立部署、能够提供相同协议 release 的 Simulator Server。只配置另一个指向同一
+故障集群的域名不能提供有效降级。
+
+Client 会先依次请求主、备用服务。网络错误和最终非 2xx 响应会在等待 100ms 后重试一轮，请求超时由
+网关控制；2xx 响应中的协议不匹配、响应结构非法和 document origin 不匹配不会重试同一地址。
+即使没有配置 `fallbackServiceUrls`，主地址的瞬时故障也有一次重试机会。
+
+## 10. 常见问题
+
+### `/runtime-manifest` 请求失败
+
+检查宿主 `connect-src`、Simulator Server 网关和
+`/simulator/runtime-manifest?protocolVersion=6` 的 CORS。
+
+### iframe 被宿主 CSP 阻止
+
+把 Simulator origin 加入宿主 `frame-src`，并确认网关没有设置 `X-Frame-Options: SAMEORIGIN`。
+
+### Service Worker 注册失败
+
+检查 Runtime 是否为安全上下文、`/releases/:buildId/sw.js` 是否返回 JavaScript MIME、
+`Service-Worker-Allowed` 是否覆盖当前 release 的 `/app/` scope，以及 CDN SW module 是否允许 CORS。
+
+### 返回 HTTP 426
+
+Apollo release `list` 中没有与薄 SDK protocolVersion 一致的版本。保留旧协议 release，或者升级业务方
+薄 SDK。
+
+### 模拟器显示正常但控制台出现 destroyed rejection
+
+所有异步 `ready`、`loadZip`、`loadApp`、`reload` 调用都应处理 rejection；组件卸载时设置 disposed，
+再调用 `destroy()`。
+
+### 模拟器卡死或内存过高
+
+Web 模式使用 JS Heap 水位和 iframe 心跳兜底。恢复提示由薄 SDK展示，用户确认后重建 Runtime 并重放
+最近一次 load。完整 Renderer 内存和逐实例进程管控需要 Electron。
+
+## 11. 接入检查表
+
+- [ ] 按环境配置正确的 `serviceUrl`。
+- [ ] 宿主 CSP 放行 Simulator 的 `connect-src` 和 `frame-src`。
+- [ ] `appId`、`businessLine` 位于顶层。
+- [ ] `getUserInfo` 通过 `hostApi` 提供。
+- [ ] ZIP 使用 `loadZip()`，无需宿主传 JSZip。
+- [ ] 等待 `ready` 并处理 Promise rejection。
+- [ ] 组件卸载时调用 `destroy()`。
+- [ ] 多实例分别保存引用并使用不同 appId。
+- [ ] 可选新能力通过 `ready.capabilities` 判断。
+- [ ] 生产环境验证 Runtime 和 SW CDN CORS。

package/docs/request-design.md

@@ -0,0 +1,247 @@
+# 模拟器 Request 请求方案
+
+## 1. 结论
+
+模拟器保留两条独立请求链路：
+
+- `xhs.miniTool.request` 是面向小工具开发者的公开 API，在无宿主身份的隔离 iframe 中执行。
+- `xhsRequest` 是 JS SDK 内部 Bridge 能力，通过宿主注入的 `hostApi.request` 执行，用于 `xhs.AI` 等平台托管能力。
+
+两者复用请求参数、`RequestTask`、事件和错误模型，但不共享网络权限。公开链路不能被 `hostApi.request` 覆盖，避免开发者请求获得宿主 Cookie、签名或内部网关能力。
+
+## 2. 能力边界
+
+| 维度 | `xhs.miniTool.request` | `xhsRequest` |
+| --- | --- | --- |
+| 定位 | 公开 JSAPI | SDK 内部 Bridge 能力 |
+| 调用方 | 小工具业务代码 | `xhs.AI` 等 SDK 内部模块 |
+| 执行位置 | 独立 request manager iframe 内的 `fetch` | 宿主注入的 `hostApi.request` |
+| 身份与 Cookie | `credentials: omit`，不携带宿主 Cookie | 由宿主决定，可进入登录态、验签和拦截链 |
+| 跨域 | 遵循浏览器 CORS；iframe 为 opaque origin | 遵循宿主 HTTP 实现及运行环境约束 |
+| 流式响应 | 读取 Fetch `ReadableStream` | 宿主返回 `ReadableStream` 或完整字符串 |
+| API 暴露 | 正式公共 API | 不进入公共类型和正式 API 面；开发构建可临时暴露用于链路验证 |
+
+## 3. 总体架构
+
+```mermaid
+flowchart LR
+  A[小工具业务] -->|xhs.miniTool.request| B[JS SDK RequestTask]
+  C[xhs.AI / SDK 内部模块] -->|xhsRequest| B
+  B -->|request / xhsRequest + taskId| D[Bridge]
+  D -->|request| E[RequestRuntime.executePublic]
+  E -->|postMessage| F[隔离 Request Manager iframe]
+  F -->|fetch / credentials omit| G[开发者服务]
+  D -->|xhsRequest| H[RequestRuntime.executeInternal]
+  H -->|统一 Host Request 契约| I[hostApi.request]
+  I -->|Cookie / 验签 / 拦截 / Trace| J[平台服务]
+  F -.->|headers / SSE chunk| D
+  H -.->|headers / SSE chunk| D
+  D -.->|taskId 路由| B
+```
+
+`RequestRuntime` 是统一调度层，负责参数校验、活跃任务管理、取消和事件回传；真正的 I/O 由隔离 iframe 或宿主适配器完成。
+
+## 4. 为什么公开 request 走隔离 iframe
+
+公开请求不能直接在小工具渲染 iframe 或宿主页面执行：
+
+- 小工具渲染 iframe 承载不可信业务代码，并受页面 CSP、运行时封印和应用生命周期影响，不适合作为独立网络执行面。
+- 宿主页面拥有 Cookie、登录态、HTTP 拦截器和签名能力，直接复用会扩大公开 API 的权限。
+- 独立 iframe 可以使用 `sandbox="allow-scripts"` 形成 opaque origin，配合 `credentials: omit`、`no-referrer`、受控 CSP 和请求头过滤，建立清晰的无身份网络边界。
+- request manager 与单个模拟器实例绑定，可以独立维护任务表；模拟器销毁时直接取消请求并移除 iframe。
+
+### 4.1 为什么不走 Service Worker
+
+模拟器中的 Service Worker 负责 ZIP 文件表、虚拟 URL 和静态资源加载；公开 request 是显式 JSAPI RPC，两类问题的边界不同。
+
+| 考量 | 隔离 iframe | Service Worker |
+| --- | --- | --- |
+| 适用问题 | 执行显式请求 RPC | 拦截受 scope 控制的页面和子资源请求 |
+| 安全边界 | `sandbox` 去同源形成 opaque origin | 运行在注册 origin，不能提供同等直接的 opaque-origin 实例边界 |
+| 生命周期 | DOM 实例所有；创建、取消、销毁可预测 | 浏览器管理，可能休眠/重启，不能与模拟器实例严格同生共死 |
+| 隔离粒度 | 每个模拟器实例一个 manager 和任务表 | 同一 registration/scope 可被多个页面或实例共享 |
+| 部署条件 | 可使用内联 data URL 或服务端提供的 frame URL | 要求安全上下文、同源脚本、合法 scope 和注册成功 |
+| 版本管理 | 随 Runtime 版本加载并随实例销毁 | 存在安装、激活、更新和旧 worker 接管窗口 |
+| 宿主影响 | 不接管宿主或小工具的正常资源请求 | 扩大 fetch 拦截面，可能与现有模拟器 SW 或宿主 SW 冲突 |
+| 流式回传 | iframe 内直接读流，通过 `postMessage + taskId` 回传 | 需要额外的 client 定位、消息关联和 worker 存活处理 |
+
+采用 Service Worker 还会带来以下具体问题：
+
+1. SW 只能控制其注册 origin 和 scope 下的 client，不能从任意 CDN 跨域注册，也不能在 opaque origin/data URL 中注册。
+2. 当前远程模拟器已经使用版本化 SW 承载虚拟文件系统。把业务 request 混入该 SW 会把“包内资源解析”和“对外网络权限”耦合到同一个全局拦截器。
+3. 多模拟器、多标签页可能共享 SW registration，任务隔离、升级切换和故障回收都比实例级 iframe 更复杂。
+4. `xhs.miniTool.request` 已经通过 Bridge 明确发起，不需要 SW 的透明 fetch 拦截能力。
+5. 隔离 iframe 能直接执行 Fetch 和 ReadableStream，并用现有 `taskId` 协议回传响应头、SSE 分片和终态，链路更短。
+
+因此，Service Worker 继续负责“把 ZIP 文件映射为同源虚拟文件系统”；隔离 iframe 负责“公开、无身份、显式 request”；宿主 `hostApi.request` 负责“内部、有身份、平台托管 request”。
+
+## 5. SDK 请求契约
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `url` | string | 必填 | 非空 URL；公开链路仅允许 `http:` 和 `https:` |
+| `method` | GET/POST/PUT/DELETE/HEAD/OPTIONS | GET | 运行层统一转为大写 |
+| `header` | `Record<string, string>` | 空 | 公开链路移除受保护头；内部链路交给宿主 |
+| `data` | unknown | 空 | 不支持 `ArrayBuffer` 和 TypedArray |
+| `dataType` | json/text | json | json 模式尽力解析字符串响应 |
+| `responseType` | text | text | 当前仅支持文本响应 |
+| `timeout` | number | 60000 ms | 必须大于 0；超时中止底层请求 |
+| `enableChunked` | boolean | false | 开启 SSE 分片消费 |
+| `success/fail/complete` | callback | 空 | `complete` 在成功或失败后执行 |
+
+请求同步返回 `RequestTask`：
+
+```ts
+interface RequestTask {
+  abort(): void
+  onHeadersReceived(callback: (result: {
+    statusCode: number
+    header: Record<string, string>
+  }) => void): void
+  offHeadersReceived(callback?: Function): void
+  onChunkReceived(callback: (result: { data: string }) => void): void
+  offChunkReceived(callback?: Function): void
+}
+```
+
+SDK 先返回 Task，再异步发起 Bridge 调用，使调用方可以提前注册响应头和分片监听。任务完成、失败或取消后会清理订阅并忽略迟到事件。
+
+## 6. Bridge 协议
+
+- 请求事件：`request` 或 `xhsRequest`，消息体包含统一参数和唯一 `taskId`。
+- 响应头事件：`onHeadersReceivedRequest`，按 `taskId` 投递。
+- 流分片事件：`onEventStream`，按 `taskId` 投递。
+- 取消事件：`abortRequest`，只携带 `taskId`。
+- 终态：success 返回 `statusCode`、`header`、`data`；fail 返回 `errCode` 和 `errMsg`。
+
+## 7. 公开 request 执行链路
+
+1. SDK 创建 `RequestTask` 和 `taskId`，异步发送 `request`。
+2. `RequestRuntime.executePublic` 校验参数。
+3. 运行层按需创建隐藏 request manager iframe，通过 `postMessage` 发送请求。
+4. iframe 使用 `fetch` 请求，将响应头、SSE 分片和终态结果回传模拟器。
+5. 模拟器通过 Bridge 投递给对应 `RequestTask`。
+
+隔离策略：
+
+- iframe sandbox 仅启用 `allow-scripts`，不启用 `allow-same-origin`。
+- `referrerPolicy` 为 `no-referrer`；Fetch 固定 `credentials: omit`。
+- CSP 只开放脚本自身执行及 `http/https/ws/wss` 连接；URL 进一步限制为 `http:` 或 `https:`。
+- 过滤 `cookie`、`referer`、`origin`、`user-agent`、`host`、`content-length`。
+- 响应头统一小写并移除 `set-cookie`。
+
+公开 request 的目标服务必须允许浏览器跨域请求。由于执行上下文是 opaque origin，服务端需要按实际预检请求配置 CORS。
+
+## 8. 内部 xhsRequest 执行链路
+
+1. `xhs.AI` 等 SDK 内部模块发送 `xhsRequest`。
+2. `RequestRuntime.executeInternal` 读取 `hostApi.request`；未注入时返回 API unavailable。
+3. 运行层创建 `AbortController` 和超时计时器，转换为通用宿主请求契约。
+4. 宿主适配 Launcher HTTP、XHR、Fetch 或其他 HTTP 库，处理身份、Cookie、验签、拦截器和链路信息。
+5. 运行层校验并归一化宿主响应，回传响应头、SSE 分片和终态。
+
+```ts
+type MiniAppHostRequest = (options: {
+  url: string
+  method: string
+  header?: Record<string, string>
+  data?: unknown
+  responseType: 'text'
+  enableChunked: boolean
+  signal: AbortSignal
+}) => Promise<{
+  statusCode: number
+  header?: Record<string, string>
+  data?: unknown | ReadableStream<Uint8Array | string>
+}>
+```
+
+宿主必须响应 `signal`。HTTP 非 2xx 状态仍按正常响应返回；传输失败、取消、超时或适配器异常进入 fail。宿主只处理通用 HTTP 参数，不感知 `taskId` 和 Bridge 事件。
+
+## 9. 参数序列化与响应归一化
+
+| 场景 | 处理规则 |
+| --- | --- |
+| GET/HEAD | `data` 序列化到 query |
+| 无 Content-Type 的非 GET | 自动使用 `application/json` |
+| `application/json` | 非字符串请求体执行 `JSON.stringify` |
+| `application/x-www-form-urlencoded` | 按 query 规则序列化 |
+| 其他 Content-Type | 字符串原样发送，其他值转字符串 |
+| 普通响应 | 头转小写、移除 `set-cookie`；json 模式尽力解析 |
+| SSE | 按空行边界组装原始事件帧；每帧触发 `onChunkReceived`，终态 data 为空字符串 |
+
+## 10. 超时、取消与并发
+
+- 两条链路都创建超时计时器，到期后中止底层请求并返回 `REQUEST_TIMEOUT`。
+- `RequestTask.abort()` 立即将 SDK 任务置为终态、清理订阅，并发送 `abortRequest(taskId)`。
+- 模拟器销毁时执行 `abortAll`，取消全部活跃请求并移除 request manager iframe。
+- 活跃任务以 `taskId` 存储；重复 `taskId` 为非法参数，响应头和分片只投递给匹配任务。
+- 终态清除计时器、活跃任务记录和 SDK 事件订阅。
+
+## 11. 错误模型
+
+| 错误码 | 名称 | 触发条件 |
+| --- | --- | --- |
+| 10001 | INVALID_PARAM | URL/taskId、方法或 timeout 非法，二进制 data，非 text responseType，重复 taskId |
+| 10002 | API_UNAVAILABLE | `xhsRequest` 未找到 `hostApi.request` |
+| 10003 | URL_SCHEME_NOT_ALLOWED | 公开 request 使用非 http/https 协议 |
+| 10101 | REQUEST_TIMEOUT | 超过 timeout |
+| 10102 | REQUEST_ABORTED | 调用方取消或模拟器销毁 |
+| 15201 | REQUEST_FAILED | Fetch 失败、宿主异常、响应结构非法或二进制响应 |
+
+## 12. 接入要求
+
+小工具开发者：
+
+- 普通业务请求使用 `xhs.miniTool.request`。
+- 不直接依赖 `xhsRequest`；平台托管能力通过 `xhs.AI` 等公开模块使用。
+- SSE 设置 `enableChunked: true` 和 `dataType: 'text'`，通过 Task 注册 `onChunkReceived`。
+
+模拟器宿主：
+
+```ts
+createRemoteMiniAppSimulator({
+  // ...其他配置
+  hostApi: {
+    request: async (options) => {
+      // 适配 Launcher HTTP / Fetch / XHR，透传 options.signal
+      return { statusCode, header, data }
+    },
+  },
+})
+```
+
+- 仅在需要 SDK 内部平台请求时注入 `hostApi.request`。
+- 宿主决定凭证策略、签名、拦截器、Trace Header 和业务网关。
+- 不得把 Cookie、Token 或签名能力反向暴露给公开 request。
+
+## 13. 当前限制
+
+- 不支持二进制请求体和响应体。
+- `responseType` 只支持 `text`。
+- 公开 request 受 CORS 约束，不能携带宿主 Cookie或设置受保护请求头。
+- 流式分片只识别 `Content-Type: text/event-stream`，输出未解析的 SSE 原始事件帧。
+- 对象 query 是扁平键值序列化；复杂嵌套、数组和特殊编码由调用方预处理。
+- Multipart 不接收二进制 `FormData` 作为跨 Bridge 数据；调用方构造字符串请求体，或由内部宿主链路适配。
+
+## 14. 验收清单
+
+- [x] 公开 request：GET query、POST JSON、URL Encoded 可返回。
+- [x] 内部 xhsRequest：经 `hostApi.request` 进入宿主 HTTP 拦截链。
+- [x] 公开 request 不携带宿主 Cookie，受保护请求头被过滤。
+- [x] SSE：响应头先到达，分片按完整事件帧顺序回调，终态正确。
+- [x] abort、timeout、destroy 均中止任务并清理资源。
+- [x] HTTP 非 2xx 保留 statusCode，传输错误进入 fail。
+- [x] 缺少适配器、非法协议、非法参数和二进制数据返回明确错误码。
+- [x] 并发请求按 taskId 隔离。
+
+## 15. 代码落点
+
+| 模块 | 职责 |
+| --- | --- |
+| `miniapp-js-api/src/apis/request`（jsapi SDK 源码，已随包外移） | 请求参数、RequestTask、Bridge 发送和本地参数拒绝 |
+| `miniapp-js-api/src/ai/request.ts`（已外移） | 内部 xhsRequest 到 AI SDK 普通/流式请求适配 |
+| `miniapp-simulator/src/runtime/request-runtime.ts` | 双链路调度、校验、任务、超时和取消 |
+| `miniapp-simulator/src/runtime/request-manager-frame.ts` | 公开请求的隔离 iframe、Fetch、安全策略和 SSE |
+| `miniapp-simulator/src/runtime/host-request.ts` | 宿主请求适配、序列化、响应归一化和 SSE 分帧 |
+| `miniapp-simulator/src/core/simulator.ts` | 注册 request、xhsRequest、abortRequest handler |