小工具容器 · 能力清单

01运行环境

小工具是运行在受限沙箱环境里的纯 Web 应用（HTML / CSS / JS），请把它当作一个"能力受限的浏览器页面"来开发。

02可用能力

2.1 页面与渲染

2.2 JS / CSS 兼容基线

小工具最低兼容 Android 8.1 出厂 Chrome / WebView 61，iOS 最低支持 iOS 18.4。

• JavaScript：最终交付代码须编译到 ES2017 / Chrome 61；更高版本语法由构建工具转译。
• CSS：最终样式须兼容 Chrome 61；更高版本 CSS 只能作为增强，并保留基础样式。
• 能力检测：使用 Chrome 61 基线外的高级 Web API 或 CSS 能力前，必须先检测是否支持； 支持时启用增强，不支持时走降级路径。

开发方式：请复制小工具上传页提供的完整改写口令，让 AI 助手加载对应版本 Skill， 并严格按照 SKILL.md 完成开发、兼容处理、校验和打包。具体开发规则以 Skill 为准。

2.3 媒体与文件

2.4 数据存储

• 数据仅属于当前小工具，其他小工具与外部无法访问。请勿假设数据永久持久化。

2.5 交互

2.6 资源加载规则

小工具为本地运行、不联网，容器对页面如何加载各类资源有明确约束（对应浏览器 CSP 限制）。所有资源须打包在小工具内（下表"包内资源"），另按类型额外允许 data: / blob: 等内存来源。

支持的文件类型

小工具包内仅支持以下文件类型：

实践要点

• 脚本必须外置：容器禁止内联脚本与行内事件处理器，请把 JS 写进包内 .js 文件用 <script src> 引入，事件绑定改用 addEventListener（不要用 onclick= 属性）。
• 样式可内联：<style> 和 style="..." 都能用，无需外置。
• 选图预览用 <img src> 配 data: 或 blob: 均可显示（如 FileReader.readAsDataURL 或 URL.createObjectURL）。

03端能力 JS API

除标准 Web 能力外，容器会自动注入 JS API SDK，小工具可通过 window.xhs.miniTool.* 调用 App 原生能力：发布笔记、保存图片到相册、 本地缓存、文件读写和发布评论。无需在包内引入任何 SDK 脚本。

3.1 调用约定

const miniTool = window.xhs && window.xhs.miniTool;
if (!miniTool) return; // 当前环境未注入端能力

// Promise 形态
try {
  await miniTool.saveImageToPhotosAlbum({ filePath });
} catch (err) {
  console.log(err.errMsg); // "saveImageToPhotosAlbum:fail ..."
}

// 回调形态（返回 undefined）
miniTool.saveImageToPhotosAlbum({
  filePath,
  success: (res) => console.log(res.errMsg),
  fail: (err) => console.log(err.errMsg),
  complete: () => {},
});

3.2 API 一览

3.3 postNote — 发布笔记

唤起 App 笔记发布页，并带入小工具产出的内容与媒体。用户在发布页可继续编辑或取消。

// 图文笔记
await window.xhs.miniTool.postNote({
  title: "我的作品",
  content: "用小工具生成的",
  pageType: "photo_publish",
  mediaInfo: {
    image_resources: [{ url: "data:image/png;base64,iVBORw0KGgo..." }],
  },
});

// 视频笔记
await window.xhs.miniTool.postNote({
  pageType: "video_publish",
  mediaInfo: {
    video_resources: { video_url: videoPath, cover_url: coverPath },
  },
});

// 实况笔记（客户端 9.43+）
await window.xhs.miniTool.postNote({
  pageType: "slides_edit",
  mediaInfo: {
    live_photo_sources: [{ url: coverPath, video_url: videoPath }],
  },
});

3.4 saveImageToPhotosAlbum — 保存图片到相册

// Canvas 导出直接保存
const dataUrl = canvas.toDataURL("image/png");
await window.xhs.miniTool.saveImageToPhotosAlbum({ filePath: dataUrl });

• 需由用户主动操作（点击等）触发，首次调用可能弹出系统相册权限弹窗；用户拒绝授权会走失败回调。
• 大图建议先 writeTempFile 落成文件再保存，避免超长 base64 上行。

3.5 writeTempFile — base64 转临时文件

把内存里的 base64（Canvas 导出、选图预览结果等）写成容器内的临时文件，换取可传给其他 JS API 的 filePath。

const { filePath } = await window.xhs.miniTool.writeTempFile({
  data: canvas.toDataURL("image/png"),
});

await window.xhs.miniTool.saveImageToPhotosAlbum({ filePath });
// 或带入发布页
await window.xhs.miniTool.postNote({
  mediaInfo: { image_resources: [{ url: filePath }] },
});

• 返回的是临时文件，不保证长期有效，请即用即弃，不要持久化保存该路径。
• 仅支持常见图片 / 视频类型（png、jpeg、webp、gif、mp4），其他类型会失败。

3.6 客户端版本判断

window.xhs、launchOptions、miniToolEnv 和 buildVersion 都可能缺失，同步读取时必须逐级判空。同步值不存在时， 在确认 window.xhs.miniTool.getLaunchOptions 是函数后，再异步获取客户端值。 两种方式都无法取到版本号时，按不支持 Storage JS API 处理。

function readBuildVersion(launchOptions) {
  const miniToolEnv = launchOptions && launchOptions.miniToolEnv;
  return Number(miniToolEnv && miniToolEnv.buildVersion) || 0;
}

async function getBuildVersion() {
  const xhs = window.xhs;
  const syncBuildVersion = readBuildVersion(xhs && xhs.launchOptions);
  if (syncBuildVersion) return syncBuildVersion;

  const miniTool = xhs && xhs.miniTool;
  if (!miniTool || typeof miniTool.getLaunchOptions !== "function") return 0;

  try {
    const launchOptions = await miniTool.getLaunchOptions();
    return readBuildVersion(launchOptions);
  } catch (error) {
    return 0;
  }
}

function getClientVersion(buildVersion) {
  // 例如 9462004 / 1000 取整后为 9462，即客户端 9.46.2
  return Math.floor(buildVersion / 1000);
}

function isClientVersionAtLeast(buildVersion, minimumClientVersion) {
  return getClientVersion(buildVersion) >= minimumClientVersion;
}

3.7 Storage — 小工具本地缓存

const STORAGE_MIN_CLIENT_VERSION = 9460; // 客户端 9.46.0

async function setLocalData(key, data) {
  let serializedData;
  try {
    serializedData = JSON.stringify(data);
  } catch (error) {
    return false;
  }
  if (typeof serializedData !== "string") return false;

  const buildVersion = await getBuildVersion();
  const miniTool = window.xhs && window.xhs.miniTool;

  if (
    isClientVersionAtLeast(buildVersion, STORAGE_MIN_CLIENT_VERSION) &&
    miniTool &&
    typeof miniTool.setStorage === "function"
  ) {
    try {
      await miniTool.setStorage({ key, data: serializedData });
      return true;
    } catch (error) {
      return false;
    }
  }

  // 仅用于兼容低版本客户端；容器不保证其可用性或持久性
  try {
    localStorage.setItem(key, serializedData);
    return true;
  } catch (error) {
    return false;
  }
}

调用方必须处理 setLocalData 返回 false 的情况， 不能假设数据已成功持久化。

• 单个 key 最大 1 MB，当前小工具全部缓存最大 10 MB。
• data 只支持 JSON 字符串。对象、数组等数据必须先用 JSON.stringify 序列化；读取后再用 JSON.parse 解析。
• encrypt 默认为 false；读取时必须与写入时保持一致。
• 这些 API 同时支持 Promise 与 success / fail / complete 回调。

await window.xhs.miniTool.setStorage({
  key: "profile",
  data: JSON.stringify({ nickname: "小红薯" }),
});

const { data } = await window.xhs.miniTool.getStorage({ key: "profile" });
const profile = data === null ? null : JSON.parse(data);
const { keys, currentSize, limitSize } = await window.xhs.miniTool.getStorageInfo();

await window.xhs.miniTool.removeStorage({ key: "profile" });
await window.xhs.miniTool.clearStorage();

3.8 文件系统

文件和二进制数据使用文件系统保存。持久目录根路径由 launchOptions.miniToolEnv.userDataPath 提供；请只在该路径后拼接相对路径， 不要硬编码、解析或改写端上返回的文件句柄。

const miniTool = window.xhs && window.xhs.miniTool;
const launchOptions = await miniTool.getLaunchOptions();
const userDataPath = launchOptions.miniToolEnv.userDataPath;
const filePath = userDataPath + "/drafts/note.json";

await miniTool.writeFile({
  filePath,
  data: JSON.stringify({ title: "草稿" }),
  encoding: "utf8",
});

const { data } = await miniTool.readFile({
  filePath,
  encoding: "utf8",
});

• writeFile 覆盖写入，appendFile 追加写入。大文件由业务自行分片：第一片用 writeFile，后续片串行调用 appendFile。
• 分片大小以 getFileStorageInfo 返回的 writeChunkMaxBytes 和 readChunkMaxBytes 为准，不要硬编码。
• 图片和视频渲染时直接使用文件句柄作为 img.src、video.src 或 CSS 资源；需要文件字节时才使用 readFile。
• usr 是本地工作区而非备份空间。它不随容器关闭清空，但卸载、清数据或包清理后仍可能丢失，重要数据应可重建或引导用户导出。

3.9 interactionOpenApi — 发布评论

用于唤起评论区并携带评论草稿；草稿字段遵循评论侧契约。容器会统一关闭小工具后再拉起评论区。

const result = await window.xhs.miniTool.interactionOpenApi({
  payload: {
    action: "post_comment",
    content: "快来和我 PK！",
    media_bean: [{
      media_type: "image",
      cover_image_url: imageFilePath,
    }],
    miniToolSnapshotInfo: JSON.stringify({ page: "result" }),
  },
  saveToAlbum: true,
});

// { routed, savedToAlbum, albumFailReason? }

• 目前仅支持图片，使用 { media_type: "image", cover_image_url }；视频和实况图不支持。
• 媒体路径必须是容器可访问的本地文件句柄；网络 URL、data: URI 和绝对路径不可用。
• miniToolSnapshotInfo 有效时，用户从评论区重新打开小工具可读取该数据，用于恢复对应业务状态；恢复逻辑由开发者自行实现。
• routed 表示评论侧路由是否成功。请求保存相册但失败时，失败原因会通过可选字段 albumFailReason 返回。

04不可用能力

以下能力在容器内已被禁用，调用会失败（抛出异常、返回空值或被拦截），请勿使用。

4.1 已禁用的 Web API

4.2 已禁用的行为

4.3 移动端不支持

以下能力移动端 WebView 本身不支持，无法使用：支付 PaymentRequest、系统通知 / 推送、NFC、MIDI、XR / AR / VR、后台同步 / 下载、PWA 安装、窗口管理、指针 / 键盘锁定等。

05WebGL / 图形计算边界

纯 WebGL 渲染可用，但组合能力受限：

WebGL 适合用打包在小工具内的资源做本地渲染；需要 AI 图像处理等重计算的场景无法支持（既不能联网也不能跑 WASM 模型）。