xhs-minitool-creator 1.0.0

package/src/zip.mjs

@@ -0,0 +1,190 @@
+/**
+ * 纯 Node ZIP 写入器（zero dependency, cross-platform）
+ *
+ * 为什么自己实现：原脚手架依赖系统的 `zip` / `zipinfo` 二进制，
+ * 在 Windows 或无 zip 工具的环境直接不可用。这里用 zlib 实现最小可用的
+ * ZIP（local file header + central directory + EOCD），只做 deflate 与 store
+ * 两种压缩方式，满足小工具交付包需求。
+ */
+import { deflateRawSync, crc32 } from 'node:zlib';
+
+const LOCAL_SIG = 0x04034b50;
+const CENTRAL_SIG = 0x02014b50;
+const EOCD_SIG = 0x06054b50;
+
+const STORE = 0;
+const DEFLATE = 8;
+
+/** create_system：3 = Unix，见 createZip 中关于文件名编码的说明 */
+const UNIX_SYSTEM = 3;
+
+/** 体积小于该阈值时不压缩（deflate 反而变大） */
+const DEFLATE_MIN_SIZE = 64;
+
+/** 已本身就是压缩格式，deflate 收益极低，直接 store */
+const NO_COMPRESS_EXT = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.zip',
+  '.gz', '.br', '.woff', '.woff2', '.mp3', '.mp4', '.webm',
+]);
+
+function toDosDateTime(date) {
+  const year = Math.max(date.getFullYear(), 1980);
+  const time =
+    ((date.getHours() & 0x1f) << 11) |
+    ((date.getMinutes() & 0x3f) << 5) |
+    ((date.getSeconds() / 2) & 0x1f);
+  const day =
+    (((year - 1980) & 0x7f) << 9) |
+    (((date.getMonth() + 1) & 0x0f) << 5) |
+    (date.getDate() & 0x1f);
+  return { time, day };
+}
+
+function crc32Of(buf) {
+  // Node 22+ 内置 zlib.crc32；低版本回退到查表实现
+  if (typeof crc32 === 'function') return crc32(buf) >>> 0;
+  return crc32Table(buf);
+}
+
+let TABLE = null;
+function crc32Table(buf) {
+  if (!TABLE) {
+    TABLE = new Int32Array(256);
+    for (let n = 0; n < 256; n += 1) {
+      let c = n;
+      for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+      TABLE[n] = c;
+    }
+  }
+  let crc = -1;
+  for (let i = 0; i < buf.length; i += 1) {
+    crc = (crc >>> 8) ^ TABLE[(crc ^ buf[i]) & 0xff];
+  }
+  return (crc ^ -1) >>> 0;
+}
+
+/**
+ * 创建 zip 二进制内容
+ * @param {{ name: string, data: Buffer, date?: Date }[]} entries
+ * @returns {Buffer}
+ */
+export function createZip(entries) {
+  const chunks = [];
+  const central = [];
+  let offset = 0;
+
+  for (const entry of entries) {
+    // 统一为 POSIX 路径分隔符
+    const name = entry.name.split('\\').join('/');
+    const nameBuf = Buffer.from(name, 'utf8');
+    const raw = entry.data;
+    const date = entry.date || new Date();
+    const { time, day } = toDosDateTime(date);
+    const crc = crc32Of(raw);
+
+    const ext = name.slice(name.lastIndexOf('.')).toLowerCase();
+
+    // 文件名含非 ASCII（如中文）时必须置 UTF-8 标志位（bit 11），
+    // 否则解压方按本地编码解析会得到乱码甚至创建失败。
+    const isUtf8Name = /[^\x00-\x7F]/.test(name);
+    const flags = isUtf8Name ? 0x0800 : 0;
+
+    const shouldDeflate =
+      raw.length >= DEFLATE_MIN_SIZE && !NO_COMPRESS_EXT.has(ext);
+
+    let method;
+    let payload;
+    if (shouldDeflate) {
+      const compressed = deflateRawSync(raw, { level: 9 });
+      if (compressed.length < raw.length) {
+        method = DEFLATE;
+        payload = compressed;
+      } else {
+        method = STORE;
+        payload = raw;
+      }
+    } else {
+      method = STORE;
+      payload = raw;
+    }
+
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(LOCAL_SIG, 0);
+    local.writeUInt16LE(20, 4); // version needed
+    local.writeUInt16LE(flags, 6);
+    local.writeUInt16LE(method, 8);
+    local.writeUInt16LE(time, 10);
+    local.writeUInt16LE(day, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(payload.length, 18);
+    local.writeUInt32LE(raw.length, 22);
+    local.writeUInt16LE(nameBuf.length, 26);
+    local.writeUInt16LE(0, 28); // extra len
+
+    chunks.push(local, nameBuf, payload);
+
+    const cd = Buffer.alloc(46);
+    cd.writeUInt32LE(CENTRAL_SIG, 0);
+    // version made by 高字节为 create_system：3 = Unix。
+    // 必须写成 Unix 而非 0(MS-DOS/FAT)，否则 BSD/macOS unzip 会按
+    // 本地代码页解析文件名，即使 UTF-8 标志位已置也会乱码或创建失败。
+    cd.writeUInt16LE((UNIX_SYSTEM << 8) | 20, 4);
+    cd.writeUInt16LE(20, 6); // version needed
+    cd.writeUInt16LE(flags, 8);
+    cd.writeUInt16LE(method, 10);
+    cd.writeUInt16LE(time, 12);
+    cd.writeUInt16LE(day, 14);
+    cd.writeUInt32LE(crc, 16);
+    cd.writeUInt32LE(payload.length, 20);
+    cd.writeUInt32LE(raw.length, 24);
+    cd.writeUInt16LE(nameBuf.length, 28);
+    cd.writeUInt16LE(0, 30); // extra len
+    cd.writeUInt16LE(0, 32); // comment len
+    cd.writeUInt16LE(0, 34); // disk number
+    cd.writeUInt16LE(0, 36); // internal attrs
+    // 外部属性：Unix 权限位（0o100644 << 16），缺少时部分解压工具行为异常。
+    // 注意 JS 位运算产生有符号 32 位，需 >>> 0 转回无符号。
+    cd.writeUInt32LE(((0o100644 << 16) >>> 0), 38);
+    cd.writeUInt32LE(offset, 42);
+
+    central.push(Buffer.concat([cd, nameBuf]));
+    offset += local.length + nameBuf.length + payload.length;
+  }
+
+  const centralBuf = Buffer.concat(central);
+
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(EOCD_SIG, 0);
+  eocd.writeUInt16LE(0, 4); // disk number
+  eocd.writeUInt16LE(0, 6); // disk with central dir
+  eocd.writeUInt16LE(entries.length, 8);
+  eocd.writeUInt16LE(entries.length, 10);
+  eocd.writeUInt32LE(centralBuf.length, 12);
+  eocd.writeUInt32LE(offset, 16);
+  eocd.writeUInt16LE(0, 20); // comment len
+
+  return Buffer.concat([...chunks, centralBuf, eocd]);
+}
+
+/**
+ * 读取 zip 内的文件名清单（用于自检）
+ * @param {Buffer} zipBuf
+ * @returns {string[]}
+ */
+export function listZipEntries(zipBuf) {
+  const names = [];
+  let pos = 0;
+  // 扫描 local file header
+  while (pos + 30 <= zipBuf.length) {
+    const sig = zipBuf.readUInt32LE(pos);
+    if (sig !== LOCAL_SIG) break;
+    const method = zipBuf.readUInt16LE(pos + 8);
+    const compSize = zipBuf.readUInt32LE(pos + 18);
+    const nameLen = zipBuf.readUInt16LE(pos + 26);
+    const extraLen = zipBuf.readUInt16LE(pos + 28);
+    const name = zipBuf.slice(pos + 30, pos + 30 + nameLen).toString('utf8');
+    names.push({ name, method, size: compSize });
+    pos += 30 + nameLen + extraLen + compSize;
+  }
+  return names;
+}

package/template/.agents/skills/minitool-zip-builder/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: minitool-zip-builder
+description: >-
+  小红书小工具构建开发指南：把 H5 页面打包成符合容器规范的离线 zip。
+  新建或改写小工具 / H5 页面、打包小工具 zip、处理端能力限制与容器 CSP 约束时使用。
+metadata:
+  version: "1.6.0"
+---
+
+# 小工具 ZIP 构建指南
+
+**小工具是一种基于离线 H5 实现的 app 形式**：你写一套标准网页（以 `index.html` 为入口），打包成 `.zip`，由容器（PC 模拟器 / 真机 WebView）加载运行。它本质就是 Web，HTML/CSS/JS 经验直接适用——只是运行在受控容器里：**纯本地、不联网，所有资源须打包在内**，且部分 Web 能力被收紧。
+
+目标产物：可直接上传的 **`.zip` 静态包**，在 PC 模拟器与真机行为一致。
+
+## 何时使用
+
+- 从零新建小工具页面并打包成 `.zip`
+- 将已有纯 H5 页面改写为小工具规范并打包
+
+## 工作流程
+
+每一步**动手前必须先读对应 reference 并严格遵守其全部约束**，不要凭记忆产出：
+
+1. **编写 / 适配 HTML** — 先读 [zip-artifact-spec.md](references/zip-artifact-spec.md)：目录结构、`index.html` 模板、路径与资源引用规则，按其编写
+2. **端能力合规** — 先读 [device-capabilities.md](references/device-capabilities.md)：对照「不可用能力 / 行为」逐项核对，命中项移除或改用其给出的替代写法
+3. **Native 能力（JSBridge）** — 需要发笔记、存相册、跳原生页等能力时，先读 [jsbridge-api.md](references/jsbridge-api.md)：仅使用文档列出的 `window.xhs.miniTool.*` API，参数与必填项以该文档为准，未列出的字段不要传
+4. **JS 兼容性** — 先读 [js-compatibility.md](references/js-compatibility.md)：以 Android 8.1 出场 Chrome / WebView 61 为最低基线；直接交付的 JS 可使用 ES2017，更新语法须由已有构建链转译，Web API 须做能力检测
+5. **CSS 兼容性** — 先读 [css-compatibility.md](references/css-compatibility.md)：采用“Chrome 61 基线层 + 能力检测增强层”；只为实际使用的新能力提供局部回退，不维护两套完整 CSS
+6. **跨端适配** — 先读 [cross-platform-h5.md](references/cross-platform-h5.md)：触摸、滚动、安全区、PC vs 真机差异
+7. **性能设计** — 先读 [performance-budget.md](references/performance-budget.md)：控制源码 / 静态数据 / Base64 / 媒体体积；使用 WebGL 时必须控制 GPU 资源，并提供运行时降级
+8. **正确性自查** — 静态核对页面能正常运行、无违规能力（被禁 API 无调用 / 残留、脚本加载顺序、引用资源都在 zip 内、改写时未误改业务逻辑），见 [zip-artifact-spec.md](references/zip-artifact-spec.md) 自检清单
+9. **审计并打包** — 按 [performance-budget.md](references/performance-budget.md) 的环境分支选择 Node、Python 或人工审计；修复全部错误，逐条核对各 reference 末尾的自检清单后再交付。审计脚本是辅助工具，不得因运行时缺失跳过门禁
+
+> **产出前提**：交付的 zip 必须同时满足 `zip-artifact-spec.md`、`device-capabilities.md`、`js-compatibility.md`、`css-compatibility.md`、`performance-budget.md` 与（若使用 JSBridge）`jsbridge-api.md` 的全部约束。任何约束以 reference 为准。
+
+## Reference
+
+| 文档 | 何时读 |
+| --- | --- |
+| [zip-artifact-spec.md](references/zip-artifact-spec.md) | 写 HTML / 打包时：目录结构、`index.html` 模板、路径与资源引用规则、打包自检 |
+| [device-capabilities.md](references/device-capabilities.md) | 处理端能力时：哪些 Web 能力可用 / 不可用及替代写法、如何实现常见交互（手势、拍照、选图等） |
+| [jsbridge-api.md](references/jsbridge-api.md) | 调用 Native 能力时：`window.xhs.miniTool.*` 全量 API、参数约束、示例与常见组合 |
+| [js-compatibility.md](references/js-compatibility.md) | 写 JS / 选择构建产物时：Android 8.1 出场 Chrome / WebView 61 最低基线、Web API 检测与局部降级 |
+| [css-compatibility.md](references/css-compatibility.md) | 写 CSS / 选择构建产物时：Chrome 61 基线、能力检测、现代 CSS 增强与局部回退 |
+| [cross-platform-h5.md](references/cross-platform-h5.md) | 适配多端时：触摸、滚动、安全区、PC 模拟器与真机差异 |
+| [performance-budget.md](references/performance-budget.md) | 开发和交付前：包体、静态数据、Base64、媒体、长列表与 WebGL 资源控制和降级 |

package/template/.agents/skills/minitool-zip-builder/references/cross-platform-h5.md

@@ -0,0 +1,69 @@
+# 跨端 H5 适配
+
+> 小工具同一份 H5 同时跑在 PC 模拟器与真机 WebView。以下是保证两端一致体验的适配要点。
+
+CSS 的最低语法与布局能力以 [css-compatibility.md](./css-compatibility.md) 为准；本文件只说明触摸、滚动、安全区和设备形态差异。
+
+---
+
+## 1. 触摸
+
+```css
+body { -webkit-touch-callout: none; }
+.touchable:active { opacity: 0.7; }
+html { touch-action: manipulation; }
+```
+
+交互优先用 Pointer Events（`pointerdown/move/up`）统一处理鼠标与触摸；纯触摸场景用 `touchstart/touchmove/touchend`。
+
+---
+
+## 2. 滚动
+
+```css
+.scroll-container {
+  overflow-y: auto;
+  -webkit-overflow-scrolling: touch;
+  overscroll-behavior-y: contain;
+}
+```
+
+纵向回弹由容器控制，HTML 无需额外配置。
+
+---
+
+## 3. 安全区
+
+```css
+.custom-nav { padding-top: var(--safe-area-inset-top, env(safe-area-inset-top, 0px)); }
+.bottom-bar { padding-bottom: var(--safe-area-inset-bottom, env(safe-area-inset-bottom, 0px)); }
+```
+
+需配合 `<meta name="viewport" ... viewport-fit=cover>`。PC 模拟器不产生真实 `env()`，而是注入 `--safe-area-inset-*` 变量模拟安全区；真机 `env()` 为真实值。用 `var(--safe-area-inset-*, env(...))` 组合，两端都生效。
+
+---
+
+## 4. 布局与媒体
+
+- 页面级容器用 `%` / `flex` / `vw`，勿写死 `width: 375px`
+- 图片 `max-width: 100%`
+- 用系统字体栈，避免非必要 `.woff2`
+
+---
+
+## 5. PC 模拟器 vs 真机
+
+| 特性 | PC 模拟器 | 真机 | 建议 |
+| --- | --- | --- | --- |
+| 触摸 | 鼠标 → touch 模拟 | 原生 touch | 用 pointer events 统一 |
+| 安全区 | 注入 `--safe-area-inset-*` 变量模拟 | `env()` 真实值 | 用 `var(--safe-area-inset-*, env(safe-area-inset-*, 0px))` 组合 |
+| 软键盘 | 无 | 遮挡输入框 | 监听 `visualViewport` 处理 |
+
+---
+
+## 6. 自检
+
+- [ ] 交互用 pointer / touch events，未依赖鼠标 hover 才能触发的关键操作
+- [ ] 布局自适应，无写死像素宽度
+- [ ] 安全区用 `var(--safe-area-inset-*, env(safe-area-inset-*, 0px))` 组合，配合 `viewport-fit=cover`
+- [ ] 图片自适应且体积受控

package/template/.agents/skills/minitool-zip-builder/references/css-compatibility.md

@@ -0,0 +1,171 @@
+# CSS 兼容性规范
+
+> 小工具 CSS 的最低兼容基线是 **Android 8.1 出场 Chrome / WebView 61**。这不等于只能写旧 CSS：交付物采用“Chrome 61 可用的基线层 + 能力检测后的增强层”，在新内核上使用更合适的 CSS 能力。
+
+## 1. 基线原则
+
+- 基线层保证布局、文字、按钮和核心交互在 Chrome 61 可用；增强层可以使用新 CSS 改善布局、视觉或交互。
+- 按功能点提供回退与增强，不维护两套完整页面或两份完整样式表，避免双份样式逐渐漂移。
+- 根据特性选择检测方法：能用声明级回退的按层叠覆盖，能准确查询的使用 `@supports`，语法检测无法证明实际布局行为时使用 JS 做最小行为检测。
+- 浏览器会静默丢弃无法解析的选择器、声明或整条 at-rule。不能像 JS 一样靠异常发现 CSS 不兼容，必须检查最终产物和实际布局。
+- 兼容性以最终 zip 内的 CSS 为准。源码使用了构建工具，不代表产物已经兼容。
+
+## 2. Chrome 61 不可作为唯一实现的能力
+
+以下能力晚于 Chrome 61，不能作为唯一实现。先提供基线路径，再用适合该能力的检测方式启用增强。
+
+| 能力 | 基线写法 / 降级方式 |
+| --- | --- |
+| Flexbox `gap` / `row-gap` / `column-gap` | 基线用子项单边 `margin`；增强用 JS 实际测量 Flex 布局后切换 class，不能只检测 `gap` 属性语法 |
+| `aspect-ratio` | 固定媒体尺寸，或用百分比 `padding-top` 比例盒；内容绝对定位 |
+| `min()` / `max()` / `clamp()` | 先写固定值、百分比或 `calc()`，再用媒体查询分档 |
+| `inset`、`margin-inline`、`padding-block` 等逻辑属性 / 简写 | 使用 `top/right/bottom/left` 与 `margin-left/right`、`padding-top/bottom` 等物理属性 |
+| `overflow: clip` | 使用 `overflow: hidden` |
+| `:focus-visible` | 先提供 `:focus` 样式；增强规则不能让键盘焦点在基线端消失 |
+| `:has()` | 由 JS 在父元素上切换状态 class |
+| Container Queries（`@container`） | 使用 viewport 媒体查询，或由 JS 按容器尺寸切换 class |
+| Subgrid | 使用普通 Grid、Flex 或显式轨道尺寸 |
+| CSS Nesting、Cascade Layers（`@layer`）、`@property` | 已有构建链能可靠展开时才在源码使用；最终产物不得保留为核心规则 |
+| `dvh` / `svh` / `lvh` | 先用 `%` / `100vh`；受软键盘影响的全屏高度用 JS 维护 CSS 变量并保留静态兜底 |
+| `color-mix()`、`oklab()`、`oklch()` 等现代颜色 | 先写 `#hex`、`rgb()`、`rgba()` 或 `hsl()` 颜色 |
+| `backdrop-filter` | 先给不依赖模糊的实色 / 半透明背景；模糊仅作增强，并同时考虑 `-webkit-backdrop-filter` |
+| `text-wrap: balance` 等现代排版属性 | 保留普通换行；不要让其决定关键区域高度 |
+
+## 3. 布局与前缀
+
+Chrome 61 可使用 Flexbox、基础 Grid、媒体查询、CSS Variables、`calc()`、transform、transition 和 animation。仍须处理以下跨端差异：
+
+- Flex 子项内有长文本、图片或滚动区域时，按方向显式设置 `min-width: 0` 或 `min-height: 0`，避免内容撑破容器。
+- Flex 间距先用子项 `margin` 形成基线；需要时通过行为检测启用 `gap` 并清除 margin。动态增删子项时确认首尾间距仍正确。
+- Grid 只使用基础显式 / 隐式轨道；间距使用 Chrome 61 可解析的 `grid-gap`。不要使用 Subgrid、Masonry 或依赖新语法的自动布局。
+- 需要隐藏文本时使用 `overflow: hidden; text-overflow: ellipsis; white-space: nowrap`。多行截断使用 `display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: <行数>; overflow: hidden`，并保证截断失效时页面仍可用。
+- `user-select`、`appearance`、文字截断和毛玻璃等 WebKit 相关能力按需同时写 `-webkit-` 前缀与标准声明。不要机械给所有属性加前缀。
+- 关键操作不能只在 `:hover` 出现；触摸端默认可见，并可用 `@media (hover: hover)` 增加鼠标悬停效果。
+
+## 4. 基线层与增强层
+
+### 声明回退和 `@supports`
+
+先写 Chrome 61 可用的完整基线，再覆盖增强：
+
+```css
+.panel {
+  background: rgba(255, 255, 255, 0.96);
+}
+
+@supports ((-webkit-backdrop-filter: blur(12px)) or (backdrop-filter: blur(12px))) {
+  .panel {
+    background: rgba(255, 255, 255, 0.72);
+    -webkit-backdrop-filter: blur(12px);
+    backdrop-filter: blur(12px);
+  }
+}
+```
+
+同一属性使用“旧值在前、新值在后”的回退顺序：
+
+```css
+.page {
+  min-height: 100vh;
+  min-height: var(--app-height, 100vh);
+}
+```
+
+安全区须先保留普通值，再使用容器注入变量与 `env()`：
+
+```css
+.bottom-bar {
+  padding-bottom: 0;
+  padding-bottom: var(--safe-area-inset-bottom, env(safe-area-inset-bottom, 0px));
+}
+```
+
+`@supports` 适合检测 `aspect-ratio`、`backdrop-filter`、动态视口单位等能由单个声明准确表达的能力。需要由 JS 切换 class 时，可以使用 `CSS.supports()` 检测同类声明。任何检测路径都必须保留基础样式。
+
+### Flex gap 必须检测布局行为
+
+`CSS.supports('gap', '1px')` 和 `@supports (gap: 1px)` 只能证明浏览器认识该属性和值，不能证明 `gap` 在 Flexbox 中生效；支持 Grid gap、但不支持 Flex gap 的内核也可能通过语法检测。需要启用 Flex gap 时，实际创建一次 Flex 容器并测量：
+
+```js
+function supportsFlexGap() {
+  var flex = document.createElement('div');
+  flex.style.position = 'absolute';
+  flex.style.visibility = 'hidden';
+  flex.style.display = 'flex';
+  flex.style.flexDirection = 'column';
+  flex.style.rowGap = '1px';
+  flex.appendChild(document.createElement('div'));
+  flex.appendChild(document.createElement('div'));
+  document.body.appendChild(flex);
+  var supported = flex.scrollHeight === 1;
+  flex.parentNode.removeChild(flex);
+  return supported;
+}
+
+if (supportsFlexGap()) {
+  document.documentElement.classList.add('supports-flex-gap');
+}
+```
+
+对应 CSS 只维护一套组件规则，其中 margin 是基线，gap 是增强：
+
+```css
+.actions {
+  display: flex;
+}
+
+.actions > * + * {
+  margin-left: 12px;
+}
+
+.supports-flex-gap .actions {
+  column-gap: 12px;
+}
+
+.supports-flex-gap .actions > * + * {
+  margin-left: 0;
+}
+```
+
+行为检测放在包内经典脚本中，并在 `document.body` 存在后、核心页面渲染前执行。检测一次即可，不要在 resize 或渲染循环中反复测量。
+
+不要用 UA、Android 版本或机型字符串决定样式能力。能力检测决定是否启用增强，Chrome 61 基线层始终保留。
+
+## 5. 有构建链与无构建链
+
+### 直接交付静态文件
+
+没有现成构建链时，不为 CSS 兼容性临时引入 PostCSS、Autoprefixer 或新的 npm 依赖；直接按 Chrome 61 基线编写。
+
+### 项目已有构建链
+
+将目标浏览器至少设置为：
+
+```text
+Chrome >= 61
+ios_saf >= 18.4
+```
+
+- 可使用已有的 Autoprefixer 补必要前缀；若源码使用 nesting 等新语法，须确认已有插件会把它转换成普通 CSS。
+- Autoprefixer 只补前缀，不会把 Flex `gap`、`aspect-ratio`、`:has()`、Container Queries 或动态视口单位自动改写成等价的旧布局。
+- 压缩器也须使用相同浏览器目标，避免把兼容写法重新合并成 Chrome 61 无法解析的现代语法。
+- 交付前检查构建后的 CSS；zip 中只保留最终静态产物，不带 source map 和构建配置。
+
+## 6. 视口、安全区与实测
+
+- 页面宽度使用 `%`、Flex 或基础 Grid，不写死 `375px` 等单一机型宽度。
+- `100vh` 在移动端地址栏、容器高度变化和软键盘出现时可能不等于可视高度。关键全屏区域优先使用父容器百分比；必须跟随可视高度时，由 JS 监听尺寸变化并维护 `--app-height`，同时保留 `100vh` 回退。
+- 安全区规则须配合 `viewport-fit=cover`，具体组合见 [cross-platform-h5.md](./cross-platform-h5.md)。
+- 现代桌面浏览器或 PC 模拟器通过不等于 Chrome 61 通过。能够运行旧内核时，至少检查首屏、滚动区、弹层、表单、横竖屏 / 尺寸变化和核心交互；无法运行时在交付说明中标记“Chrome 61 CSS 兼容性未实测”。
+
+## 7. 交付检查
+
+- [ ] Chrome 61 基线层能够独立完成核心布局和交互，新内核通过能力检测启用增强层
+- [ ] 未维护两套完整 CSS；只为实际使用的现代能力提供局部回退与增强
+- [ ] Flex gap 使用布局行为检测，或仅使用 margin 基线；未把 `@supports (gap: ...)` / `CSS.supports('gap', ...)` 当作 Flex gap 检测
+- [ ] `aspect-ratio`、`clamp()`、逻辑属性、`:has()`、Container Queries、Subgrid、CSS Nesting、动态视口单位等实际使用项均有合适的回退与检测 / 构建转换
+- [ ] Flex 子项已检查溢出与滚动，必要处有 `min-width: 0` / `min-height: 0`
+- [ ] 关键操作在触摸端可见，不依赖 `:hover`；焦点样式不只依赖 `:focus-visible`
+- [ ] 安全区、全屏高度、软键盘、长文本和多行截断均有基线回退
+- [ ] 使用构建链时已检查最终 CSS，而不是只检查源码或 Autoprefixer 是否运行
+- [ ] 未进行 Chrome 61 / Android 8.1 实际验证时明确标记“CSS 兼容性未实测”

package/template/.agents/skills/minitool-zip-builder/references/device-capabilities.md

@@ -0,0 +1,169 @@
+# 小工具能力清单
+
+> 小工具运行在受限容器中：**纯本地、不联网**，把它当作一个能力受限的浏览器页面。
+> **以本文为基线**：命中「不可用」项必须移除或改用替代写法。
+
+## 目录
+
+- §1 可用能力
+- §2 Native 能力（JSBridge）
+- §3 不可用能力（Web API）
+- §4 不可用行为
+- §5 WebGL / 图形计算边界
+- §6 常见交互怎么实现
+- §7 能力扫描清单
+
+---
+
+## 1. 可用能力
+
+### 页面与渲染
+
+标准 HTML / CSS / JS 可用，但最终产物须满足目标内核基线：JS 见 [js-compatibility.md](./js-compatibility.md)，CSS 见 [css-compatibility.md](./css-compatibility.md)。可使用基线内的 Flexbox / Grid / 动画 / 媒体查询、Canvas 2D（`getContext('2d')`）、WebGL（`getContext('webgl'/'webgl2')`，能力边界见 §5、性能与低端机降级见 [performance-budget.md](./performance-budget.md) §4–5），文本选择不限制。
+
+### 媒体与文件
+
+| 能力 | 用法 | 约束 |
+| --- | --- | --- |
+| 摄像头 | `navigator.mediaDevices.getUserMedia({ video: true })` | 用户手势触发 + 系统弹窗授权 |
+| 麦克风 | `navigator.mediaDevices.getUserMedia({ audio: true })` | 用户手势触发 + 系统弹窗授权 |
+| 选择图片 / 拍照 | `<input type="file">` | 系统选择器接管，**仅能选图片和视频**（无论 `accept` 如何设置） |
+| 音视频播放 | `<video>` / `<audio>` | 内联播放，媒体文件须打包在内 |
+
+### 数据存储
+
+`localStorage` / `sessionStorage` / `IndexedDB` / `Cookie` / `Cache API` 均可用，按小工具独立隔离，其他小工具与外部无法访问。
+
+Cookie 仅作本地存储：可读写、按 origin 隔离，但因不联网**不会随请求发往服务端**，不能用于登录态 / 鉴权。需要本地存储优先用 `localStorage` / `IndexedDB`。数据不保证永久持久化。
+
+### 交互
+
+`alert()` / `confirm()` 可用，以原生 UI 展示。
+
+---
+
+## 2. Native 能力（JSBridge）
+
+容器会注入 **`window.xhs.miniTool.*`**，通过它调用 Native 能力（发笔记、存相册、跳 App 页等）。
+
+| 规则 | 说明 |
+| --- | --- |
+| 唯一入口 | 只用 `window.xhs.miniTool.<apiName>(options)`，**禁止**自行 `postMessage` 到 bridge |
+| 契约来源 | 以 [`jsbridge-api.md`](./jsbridge-api.md) 为准 |
+| 参数校验 | 必填项、长度、数组上限等以 [`jsbridge-api.md`](./jsbridge-api.md) 为准 |
+| 本地路径 | `saveImageToPhotosAlbum.filePath` 不支持网络 URL；base64 可先 `writeTempFile` 换 `filePath` |
+| data:uri | `writeTempFile.data` 必须是完整 `data:<mime>;base64,...`（`canvas.toDataURL()` 原样传），裸 base64 会失败 |
+| 发笔记 | `postNote.mediaInfo` 必填；图片走 `image_resources[].url`，视频走 `video_resources` |
+| 跳原生页 | `openRedPage.type` 须命中 Native 规则表白名单，`params` 为语义参数 |
+
+完整 API 列表、字段表与示例 → **[jsbridge-api.md](./jsbridge-api.md)**。
+
+---
+
+## 3. 不可用能力（Web API）
+
+以下 API 已禁用，调用会抛异常、返回空值或被拦截，必须移除或改用替代写法。
+
+| 分类 | 涉及 API | 替代方案 |
+| --- | --- | --- |
+| 定位 | `navigator.geolocation.getCurrentPosition` / `watchPosition` | 移除 |
+| 剪贴板 | `navigator.clipboard.readText` / `writeText`、`document.execCommand('copy'/'cut'/'paste')` | 展示可选中文本，引导用户长按 / 选中手动复制 |
+| 硬件连接 | `navigator.bluetooth` / `navigator.usb` / `navigator.hid` / `navigator.serial` | 移除 |
+| 传感器 | `new Accelerometer()` / `new Gyroscope()` / `new Magnetometer()`、环境光、`DeviceMotionEvent` / `DeviceOrientationEvent` | 改用触摸 / 指针手势（见 §5），摇一摇类移除 |
+| 实时通信 | `new WebSocket()`、`new EventSource()`、`new RTCPeerConnection()` | 移除（不联网，无轮询替代） |
+| 后台运行 | Web Worker、SharedWorker、Service Worker（`navigator.serviceWorker.register`） | 移除，逻辑放主线程 |
+| 屏幕 | `getDisplayMedia`（屏幕共享）、`Element.requestFullscreen`（全屏由容器统一管理） | 全屏用 CSS 沉浸式布局实现视觉全屏 |
+| 设备信息 | `navigator.getBattery`、`navigator.connection`、`navigator.mediaDevices.enumerateDevices` | 移除 |
+| 存储进阶 | `navigator.storage.persist`（持久化）、跨域存储访问 | 移除，本地缓存用 `localStorage` / `IndexedDB` |
+| 凭据 | `navigator.credentials.get` / `create`（WebAuthn）、`navigator.locks` | 移除 |
+| 窗口 | `window.open`（弹新窗口）、`window.prompt` | 单页内 JS 切换视图 DOM；输入用页内 Modal |
+
+移动端 WebView 本身也不支持：支付 `PaymentRequest`、系统通知 / 推送、NFC、MIDI、XR / AR / VR、后台同步 / 下载、PWA 安装、窗口管理、指针 / 键盘锁定。一律移除。
+
+---
+
+## 4. 不可用行为
+
+| 行为 | 说明 | 替代方案 |
+| --- | --- | --- |
+| 网络请求 | `fetch` / `XMLHttpRequest`、加载外部图片 / 字体 / 媒体等一切联网请求 | 所有资源打包在内，改本地相对引用；仅小型配置 / 数据可随包提供，大型只读数据集不适合小工具，见 [performance-budget.md](./performance-budget.md) §2 |
+| 动态执行代码 | `eval()`、`new Function()` | 改写为静态逻辑 |
+| WebAssembly | WASM 编译执行（依赖 WASM 的库无法运行） | 移除或改用纯 JS 实现 |
+| iframe / object | 内嵌 iframe / object，或被外部页面嵌入 | 内容直接写进页面 |
+| 表单跳转提交 | `<form>` 提交跳转 | `addEventListener('submit', e => e.preventDefault())` 后用 JS 处理 |
+| 文件下载 | `a[download]`、blob 下载 | 移除 |
+| 打开外链 / 新窗口 | `target="_blank"`、`window.open`、跳转站外 URL | 单页内 JS 切换视图 DOM |
+| 跳转其他小工具 | 小工具间互相跳转 | 移除 |
+| 长按菜单 | 系统长按菜单已禁用 | 用自定义交互替代 |
+| 插件 | Flash 等浏览器插件 | 移除 |
+
+---
+
+## 5. WebGL / 图形计算边界
+
+纯 WebGL 渲染可用，组合能力受限：
+
+| 场景 | 是否可用 |
+| --- | --- |
+| 包内资源 / Canvas / 内存对象作为纹理 | ✅ |
+| 外部域名图片作为纹理 | 🔴 不联网，纹理须打包在内 |
+| 依赖 WASM 的加速库（Draco / Basis / ONNX / 抠图算法等） | 🔴 |
+| 依赖 Worker 的离屏渲染（OffscreenCanvas + Worker） | 🔴 |
+| SharedArrayBuffer 多线程 | 🔴 |
+
+WebGL 适合用包内资源做本地渲染；AI 图像处理等重计算（需联网或 WASM 模型）无法支持。WebGL 可用不等于低端真机性能足够：DPR、像素、纹理、draw call、几何预算、动态降档与兜底必须遵守 [performance-budget.md](./performance-budget.md) §4–5。
+
+---
+
+## 6. 常见交互怎么实现
+
+| 需求 | 实现 |
+| --- | --- |
+| 手势 / 拖拽 / 滑动 | `addEventListener('touchstart'/'touchmove'/'touchend')` 或 Pointer Events（`pointerdown`/`move`/`up`） |
+| 拍照 / 录音 | `getUserMedia(...)`，由按钮点击等用户手势触发 + 授权 |
+| 选择图片 / 视频 | `<input type="file">` |
+| 复制文本 | 展示可选中文本，引导用户长按 / 选中复制 |
+| 视觉全屏 | CSS 布局（`100vh` / flex + 隐藏滚动） |
+| 页面跳转 | 单页内用 JS 切换视图 DOM |
+| 输入弹窗 | 页内 Modal 组件 |
+| 保存图片到相册 | `writeTempFile({ data: canvas.toDataURL(...) })`（须完整 data:uri）→ `saveImageToPhotosAlbum({ filePath })`，见 [jsbridge-api.md](./jsbridge-api.md) |
+| 发布笔记 | `postNote({ mediaInfo, title?, content? })` |
+| 跳转 App 搜索 / 用户页等 | `openRedPage({ type, params? })`，`type` 须在白名单内 |
+
+---
+
+## 7. 能力扫描清单
+
+扫描代码，命中下列模式则**必须删除或改用替代写法**：
+
+```
+fetch( / XMLHttpRequest / new WebSocket( / new EventSource( / new RTCPeerConnection(
+navigator.geolocation.getCurrentPosition / watchPosition
+navigator.clipboard.readText / writeText  ·  document.execCommand('copy')
+navigator.bluetooth / navigator.usb / navigator.hid / navigator.serial
+navigator.getBattery / navigator.connection / navigator.credentials / navigator.locks
+navigator.mediaDevices.enumerateDevices / navigator.mediaDevices.getDisplayMedia
+navigator.storage.persist / navigator.serviceWorker.register
+new Worker( / new SharedWorker(
+new Accelerometer() / new Gyroscope() / new Magnetometer()
+DeviceMotionEvent / DeviceOrientationEvent / addEventListener('devicemotion' / 'deviceorientation')
+Element.requestFullscreen / webkitRequestFullscreen
+eval( / new Function( / WebAssembly.
+window.open( / window.prompt(
+location.href = / location.assign(   （跳转站外 URL）
+<form ...> 提交跳转  ·  <a ... download>  ·  target="_blank"
+<iframe> / <object>
+<script src="https://..."> / <link href="https://..."> / <img src="https://..."> / CSS url(https://...)
+    —— 外部资源一律加载不到，须下载后打进 zip 改本地相对引用
+```
+
+**允许保留**：
+
+```
+navigator.mediaDevices.getUserMedia({ video / audio })   // 用户手势 + 授权
+<input type="file">                                       // 选图片 / 视频
+localStorage / sessionStorage / IndexedDB / Cookie / Cache API   // 独立隔离
+alert() / confirm()
+touch / pointer events                                    // 手势交互
+标准 DOM / CSS / Canvas 2D / WebGL 渲染
+```