xhs-minitool-creator 1.0.0

package/template/.agents/skills/minitool-zip-builder/scripts/audit_artifact.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/** Audit deterministic mini-tool package and text-file size limits. */
+
+import fs from "node:fs";
+import path from "node:path";
+
+const MIB = 1024 * 1024;
+const ZIP_LIMIT = 10 * MIB;
+const ZIP_RECOMMENDED = 2 * MIB;
+const TEXT_FILE_WARNING = 2 * MIB;
+const TEXT_TOTAL_WARNING = 5 * MIB;
+const TEXT_SUFFIXES = new Set([".html", ".css", ".js", ".json"]);
+
+function formatSize(size) {
+  return `${(size / MIB).toFixed(2)} MiB`;
+}
+
+function walkDirectory(root) {
+  const files = [];
+  function walk(current) {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      if (entry.name === ".git") continue;
+      const target = path.join(current, entry.name);
+      if (entry.isDirectory()) walk(target);
+      else if (entry.isFile()) files.push(target);
+    }
+  }
+  walk(root);
+  return files;
+}
+
+function auditDirectory(root) {
+  const errors = [];
+  const warnings = [];
+  const files = walkDirectory(root);
+  let textTotal = 0;
+
+  for (const file of files) {
+    if (!TEXT_SUFFIXES.has(path.extname(file).toLowerCase())) continue;
+    const size = fs.statSync(file).size;
+    const name = path.relative(root, file).split(path.sep).join("/");
+    textTotal += size;
+    if (size > TEXT_FILE_WARNING) {
+      warnings.push(`${name}: text file is ${formatSize(size)}; review parse and memory cost`);
+    }
+  }
+  if (textTotal > TEXT_TOTAL_WARNING) {
+    warnings.push(`uncompressed HTML/CSS/JS/JSON total is ${formatSize(textTotal)}; review for embedded databases or generated content`);
+  }
+  return { errors, warnings, count: files.length };
+}
+
+function auditZipSize(file) {
+  const errors = [];
+  const warnings = [];
+  const size = fs.statSync(file).size;
+  if (size > ZIP_LIMIT) errors.push(`${path.basename(file)}: zip is ${formatSize(size)}; hard limit is 10 MiB`);
+  else if (size > ZIP_RECOMMENDED) warnings.push(`${path.basename(file)}: zip is ${formatSize(size)}; recommended target is 2 MiB`);
+  return { errors, warnings, count: 1, note: "Node audit checks zip size only; artifact contents must be audited before packaging" };
+}
+
+function main() {
+  const target = process.argv[2];
+  if (!target) {
+    console.error("Usage: node audit_artifact.mjs <artifact-directory-or-zip>");
+    return 2;
+  }
+  const resolved = path.resolve(target);
+  if (!fs.existsSync(resolved)) {
+    console.error(`ERROR: path not found: ${resolved}`);
+    return 2;
+  }
+
+  let result;
+  try {
+    result = fs.statSync(resolved).isDirectory()
+      ? auditDirectory(resolved)
+      : auditZipSize(resolved);
+  } catch (error) {
+    console.error(`ERROR: cannot inspect ${resolved}: ${error.message}`);
+    return 2;
+  }
+
+  for (const message of result.errors) console.log(`ERROR: ${message}`);
+  for (const message of result.warnings) console.log(`WARN: ${message}`);
+  if (result.note) console.log(`NOTE: ${result.note}`);
+  if (result.errors.length) {
+    console.log(`FAILED: ${result.errors.length} error(s), ${result.warnings.length} warning(s)`);
+    return 1;
+  }
+  console.log(`PASS: ${result.count} file(s), ${result.warnings.length} warning(s)`);
+  return 0;
+}
+
+process.exitCode = main();

package/template/.agents/skills/minitool-zip-builder/scripts/audit_artifact.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""Audit deterministic mini-tool package and text-file size limits."""
+
+from __future__ import annotations
+
+import sys
+import zipfile
+from pathlib import Path, PurePosixPath
+
+MIB = 1024 * 1024
+ZIP_LIMIT = 10 * MIB
+ZIP_RECOMMENDED = 2 * MIB
+TEXT_FILE_WARNING = 2 * MIB
+TEXT_TOTAL_WARNING = 5 * MIB
+TEXT_SUFFIXES = {".html", ".css", ".js", ".json"}
+
+
+def format_size(size: int) -> str:
+    return f"{size / MIB:.2f} MiB"
+
+
+def audit_entries(entries: list[tuple[str, int]]) -> list[str]:
+    warnings: list[str] = []
+    text_total = 0
+    for name, size in entries:
+        if PurePosixPath(name).suffix.lower() not in TEXT_SUFFIXES:
+            continue
+        text_total += size
+        if size > TEXT_FILE_WARNING:
+            warnings.append(
+                f"{name}: text file is {format_size(size)}; review parse and memory cost"
+            )
+
+    if text_total > TEXT_TOTAL_WARNING:
+        warnings.append(
+            f"uncompressed HTML/CSS/JS/JSON total is {format_size(text_total)}; "
+            "review for embedded databases or generated content"
+        )
+    return warnings
+
+
+def read_directory(path: Path) -> list[tuple[str, int]]:
+    return [
+        (file.relative_to(path).as_posix(), file.stat().st_size)
+        for file in sorted(path.rglob("*"))
+        if file.is_file() and ".git" not in file.relative_to(path).parts
+    ]
+
+
+def read_zip(path: Path) -> tuple[list[tuple[str, int]], list[str], list[str]]:
+    errors: list[str] = []
+    warnings: list[str] = []
+    if path.stat().st_size > ZIP_LIMIT:
+        errors.append(
+            f"{path.name}: zip is {format_size(path.stat().st_size)}; hard limit is 10 MiB"
+        )
+    elif path.stat().st_size > ZIP_RECOMMENDED:
+        warnings.append(
+            f"{path.name}: zip is {format_size(path.stat().st_size)}; recommended target is 2 MiB"
+        )
+
+    with zipfile.ZipFile(path) as archive:
+        infos = [info for info in archive.infolist() if not info.is_dir()]
+        entries = [(info.filename, info.file_size) for info in infos]
+    return entries, errors, warnings
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("Usage: python3 audit_artifact.py <artifact-directory-or-zip>")
+        return 2
+
+    path = Path(sys.argv[1]).resolve()
+    if not path.exists():
+        print(f"ERROR: path not found: {path}")
+        return 2
+
+    errors: list[str] = []
+    warnings: list[str] = []
+    try:
+        if path.is_dir():
+            entries = read_directory(path)
+        elif zipfile.is_zipfile(path):
+            entries, zip_errors, zip_warnings = read_zip(path)
+            errors.extend(zip_errors)
+            warnings.extend(zip_warnings)
+        else:
+            print(f"ERROR: expected a directory or zip file: {path}")
+            return 2
+    except (OSError, zipfile.BadZipFile) as exc:
+        print(f"ERROR: cannot inspect {path}: {exc}")
+        return 2
+
+    warnings.extend(audit_entries(entries))
+
+    for message in errors:
+        print(f"ERROR: {message}")
+    for message in warnings:
+        print(f"WARN: {message}")
+
+    if errors:
+        print(f"FAILED: {len(errors)} error(s), {len(warnings)} warning(s)")
+        return 1
+    print(f"PASS: {len(entries)} file(s), {len(warnings)} warning(s)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/template/.agents/skills/minitool-zip-builder/skill-package.json

@@ -0,0 +1,5 @@
+{
+  "name": "minitool-zip-builder",
+  "version": "1.6.0",
+  "format": "cursor-skill-zip-v1"
+}

package/template/_gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+xhs-tool/
+*.zip
+.DS_Store
+*.log
+.vite/

package/template/index.html

@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover"
+    />
+    <title>{{NAME}}</title>
+  </head>
+  <body>
+    <div id="app">
+      <!--
+        容器不支持打开新页面，多视图请在单页内用 JS 切换（SPA）。
+        每个 .page 是一个全屏子容器，通过 .is-active 控制显示。
+      -->
+      <section class="page is-active" data-page="home">
+        <header class="hero">
+          <div class="hero-icon">{{ICON}}</div>
+          <h1 class="hero-title">{{TITLE}}</h1>
+          <p class="hero-desc">{{DESC}}</p>
+        </header>
+
+        <div class="panel">
+          <label class="field">
+            <span class="field-label">你的名字</span>
+            <input id="nameInput" class="field-input" type="text" placeholder="输入后点下方按钮" />
+          </label>
+          <button id="goBtn" class="btn btn-primary" type="button">开始</button>
+          <p id="greet" class="result" hidden></p>
+        </div>
+
+        <footer class="foot">
+          <p>计数：<span id="count">0</span> 次</p>
+          <button id="resetBtn" class="btn btn-ghost" type="button">重置</button>
+        </footer>
+      </section>
+    </div>
+
+    <div class="toast" id="toast" hidden></div>
+
+    <!-- 脚本必须外置（容器 CSP 禁止内联脚本与行内事件）。
+         开发/构建期保持 type="module"，Vite 才能把 import 打包进单文件；
+         打包时由脚手架自动重建为经典脚本（容器离线加载 module 解析不可靠）。 -->
+    <script type="module" src="./src/main.js"></script>
+  </body>
+</html>

package/template/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "{{NAME}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "{{DESC}}",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && xhs-minitool-creator pack",
+    "pack": "xhs-minitool-creator pack",
+    "validate": "xhs-minitool-creator validate",
+    "skill": "xhs-minitool-creator skill",
+    "preview": "vite preview --port 5174"
+  },
+  "devDependencies": {
+    "vite": "^6.3.5",
+    "xhs-minitool-creator": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  }
+}

package/template/public/icons/icon-192.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="192" height="192" viewBox="0 0 192 192">
+  <rect width="192" height="192" rx="42" fill="#FF2442"/>
+  <text x="96" y="118" font-size="72" text-anchor="middle" fill="#fff" font-family="-apple-system,sans-serif" font-weight="700">工</text>
+</svg>

package/template/public/icons/icon-512.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512">
+  <rect width="192" height="192" rx="112" fill="#FF2442"/>
+  <text x="256" y="310" font-size="192" text-anchor="middle" fill="#fff" font-family="-apple-system,sans-serif" font-weight="700">工</text>
+</svg>

package/template/src/lib/storage.js

@@ -0,0 +1,54 @@
+/**
+ * localStorage 安全包装
+ *
+ * 容器内 localStorage 通常可用，但个别环境（隐私模式、存储被禁用）会直接抛异常。
+ * 未捕获会导致整个脚本中断、页面白屏。这里统一 try/catch，
+ * 失败时降级到内存 Map，保证功能不崩（数据在本次会话内有效）。
+ */
+
+const memory = new Map();
+
+function canUse() {
+  try {
+    const k = '__xmc_probe__';
+    window.localStorage.setItem(k, '1');
+    window.localStorage.removeItem(k);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const usable = canUse();
+
+export const safeStorage = {
+  /** @returns {string|null} */
+  get(key) {
+    try {
+      if (usable) return window.localStorage.getItem(key);
+    } catch { /* 降级 */ }
+    return memory.has(key) ? memory.get(key) : null;
+  },
+  set(key, value) {
+    try {
+      if (usable) {
+        window.localStorage.setItem(key, value);
+        return;
+      }
+    } catch { /* 降级 */ }
+    memory.set(key, value);
+  },
+  remove(key) {
+    try {
+      if (usable) {
+        window.localStorage.removeItem(key);
+        return;
+      }
+    } catch { /* 降级 */ }
+    memory.delete(key);
+  },
+  /** localStorage 是否真的可用（false 表示已降级到内存） */
+  persistent: usable,
+};
+
+export default safeStorage;

package/template/src/main.js

@@ -0,0 +1,81 @@
+import './styles/app.css';
+import { safeStorage } from './lib/storage.js';
+
+/**
+ * 示例：一个最小可用的小工具页面。
+ * 演示三件事：
+ *  1. 事件用 addEventListener 绑定（容器禁止 onclick 等行内事件）
+ *  2. 本地存储用 safeStorage 包装（个别环境 localStorage 会抛错）
+ *  3. 多视图在单页内切换（容器不支持打开新页面）
+ */
+
+const THEME_KEY = 'demo_theme';
+const COUNT_KEY = 'demo_count';
+
+/** 朴素但够用的 toast */
+function toast(message) {
+  const el = document.getElementById('toast');
+  if (!el) return;
+  el.textContent = message;
+  el.hidden = false;
+  el.classList.add('is-show');
+  clearTimeout(toast._t);
+  toast._t = setTimeout(() => {
+    el.classList.remove('is-show');
+    el.hidden = true;
+  }, 1600);
+}
+
+function renderCount() {
+  const el = document.getElementById('count');
+  if (el) el.textContent = String(Number(safeStorage.get(COUNT_KEY) || 0));
+}
+
+function init() {
+  const input = document.getElementById('nameInput');
+  const goBtn = document.getElementById('goBtn');
+  const resetBtn = document.getElementById('resetBtn');
+  const greet = document.getElementById('greet');
+
+  // 恢复上次输入
+  const saved = safeStorage.get('demo_name');
+  if (saved && input) input.value = saved;
+
+  renderCount();
+
+  goBtn?.addEventListener('click', () => {
+    const name = (input?.value || '').trim();
+    if (!name) {
+      toast('先输入名字吧');
+      input?.focus();
+      return;
+    }
+    safeStorage.set('demo_name', name);
+
+    const next = Number(safeStorage.get(COUNT_KEY) || 0) + 1;
+    safeStorage.set(COUNT_KEY, String(next));
+    renderCount();
+
+    if (greet) {
+      greet.textContent = `你好，${name}！这是第 ${next} 次使用。`;
+      greet.hidden = false;
+    }
+    toast('已保存，下次打开还在');
+  });
+
+  resetBtn?.addEventListener('click', () => {
+    safeStorage.remove(COUNT_KEY);
+    safeStorage.remove('demo_name');
+    if (input) input.value = '';
+    if (greet) greet.hidden = true;
+    renderCount();
+    toast('已重置');
+  });
+
+  // 主题跟随系统（仅作演示，可删）
+  const dark = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches;
+  document.body.dataset.theme = safeStorage.get(THEME_KEY) || (dark ? 'dark' : 'light');
+}
+
+// 经典脚本环境下 DOM 已就绪（脚本在 body 末尾），直接初始化即可
+init();

package/template/src/styles/app.css

@@ -0,0 +1,229 @@
+/*
+ * 基线：Chrome 61 / Android 8.1（官方 Skill v1.6.0 css-compatibility.md）
+ * 原则：先写 Chrome 61 可用的基线层，再用 @supports / 能力检测做增强。
+ * 不使用：flex gap（改 margin）、aspect-ratio、clamp()、逻辑属性、
+ *         :has()、Container Queries、dvh、color-mix() 等作为唯一实现。
+ */
+
+:root {
+  --accent: #ff2442; /* 由脚手架按主题色注入 */
+  --bg: #f6f6f8;
+  --card: #ffffff;
+  --text: #1a1a1e;
+  --text-2: #6b6b76;
+  --border: rgba(0, 0, 0, 0.1);
+  --radius: 14px;
+
+  /* 平台在顶部叠加原生导航栏（左返回 / 右分享），不占布局高度，需自行让位。
+     PC 模拟器注入 --safe-area-inset-* 变量，真机用 env()，故组合书写。 */
+  --safe-top: var(--safe-area-inset-top, env(safe-area-inset-top, 0px));
+  --safe-bottom: var(--safe-area-inset-bottom, env(safe-area-inset-bottom, 0px));
+}
+
+body[data-theme='dark'] {
+  --bg: #121216;
+  --card: #1c1c22;
+  --text: #f2f2f5;
+  --text-2: #9a9aa6;
+  --border: rgba(255, 255, 255, 0.12);
+}
+
+* {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+  -webkit-tap-highlight-color: transparent;
+}
+
+html {
+  /* 统一鼠标与触摸，避免点击延迟与误触 */
+  touch-action: manipulation;
+}
+
+body {
+  min-height: 100vh;
+  background: var(--bg);
+  color: var(--text);
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC',
+    'Hiragino Sans GB', 'Microsoft YaHei', sans-serif;
+  font-size: 16px;
+  line-height: 1.6;
+  -webkit-font-smoothing: antialiased;
+  -webkit-user-select: none;
+  user-select: none;
+  -webkit-touch-callout: none;
+  transition: background 0.2s, color 0.2s;
+}
+
+#app {
+  width: 100%;
+  max-width: 640px;
+  margin: 0 auto;
+  padding-top: calc(var(--safe-top) + 52px); /* 52px 为平台导航栏预留 */
+  padding-left: 16px;
+  padding-right: 16px;
+  padding-bottom: calc(var(--safe-bottom) + 24px);
+}
+
+/* ---------- 单页多视图 ---------- */
+.page {
+  display: none;
+  min-height: 60vh;
+}
+.page.is-active {
+  display: block;
+}
+
+/* ---------- Hero ---------- */
+.hero {
+  text-align: center;
+  padding-bottom: 20px;
+}
+.hero-icon {
+  font-size: 52px;
+  line-height: 1;
+  margin-bottom: 12px;
+}
+.hero-title {
+  font-size: 22px;
+  font-weight: 700;
+  letter-spacing: 0.2px;
+}
+.hero-desc {
+  margin-top: 8px;
+  font-size: 14px;
+  color: var(--text-2);
+}
+
+/* ---------- 卡片 ---------- */
+.panel {
+  background: var(--card);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 18px;
+  margin-bottom: 16px;
+}
+
+.field {
+  display: block;
+  margin-bottom: 14px;
+}
+.field-label {
+  display: block;
+  font-size: 13px;
+  color: var(--text-2);
+  margin-bottom: 6px;
+}
+.field-input {
+  width: 100%;
+  height: 44px;
+  padding: 0 12px;
+  font-size: 16px; /* 低于 16px 在 iOS 上会触发自动缩放 */
+  color: var(--text);
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  outline: none;
+  -webkit-user-select: text; /* 输入框需要可选中 */
+  user-select: text;
+}
+.field-input:focus {
+  border-color: var(--accent);
+}
+
+/* ---------- 按钮 ---------- */
+.btn {
+  display: block;
+  width: 100%;
+  height: 46px;
+  font-size: 16px;
+  font-weight: 600;
+  border: 1px solid transparent;
+  border-radius: 10px;
+  cursor: pointer;
+  transition: opacity 0.15s, transform 0.1s;
+}
+.btn:active {
+  opacity: 0.75;
+  transform: scale(0.99);
+}
+.btn-primary {
+  color: #fff;
+  background: var(--accent);
+}
+.btn-ghost {
+  color: var(--text-2);
+  background: transparent;
+  border-color: var(--border);
+}
+
+/* ---------- 结果 ---------- */
+.result {
+  margin-top: 14px;
+  padding: 12px;
+  font-size: 15px;
+  text-align: center;
+  color: var(--accent);
+  background: rgba(255, 36, 66, 0.08);
+  border-radius: 10px;
+}
+
+/* ---------- 底部 ---------- */
+.foot {
+  display: block;
+  padding: 4px 0 8px;
+  font-size: 13px;
+  color: var(--text-2);
+  text-align: center;
+}
+.foot p {
+  margin-bottom: 10px;
+}
+
+/* ---------- Toast ---------- */
+.toast {
+  position: fixed;
+  left: 50%;
+  bottom: calc(var(--safe-bottom) + 40px);
+  z-index: 100;
+  max-width: 80%;
+  padding: 10px 18px;
+  font-size: 14px;
+  color: #fff;
+  background: rgba(0, 0, 0, 0.82);
+  border-radius: 999px;
+  opacity: 0;
+  transform: translate(-50%, 8px);
+  transition: opacity 0.18s, transform 0.18s;
+  pointer-events: none;
+}
+.toast.is-show {
+  opacity: 1;
+  transform: translate(-50%, 0);
+}
+
+/* 增强层：支持毛玻璃时才启用，不支持时用实色（基线已提供） */
+@supports ((-webkit-backdrop-filter: blur(12px)) or (backdrop-filter: blur(12px))) {
+  .toast {
+    -webkit-backdrop-filter: blur(8px);
+    backdrop-filter: blur(8px);
+  }
+}
+
+/* ---------- 小屏适配 ---------- */
+@media (max-width: 360px) {
+  #app {
+    padding-left: 12px;
+    padding-right: 12px;
+  }
+  .hero-title {
+    font-size: 20px;
+  }
+}
+
+/* 鼠标设备才启用 hover 效果（触摸端关键操作不能只靠 hover 出现） */
+@media (hover: hover) {
+  .btn:hover {
+    opacity: 0.9;
+  }
+}

package/template/vite.config.js

@@ -0,0 +1,9 @@
+import { defineMinitoolConfig } from 'xhs-minitool-creator/vite';
+
+// defineMinitoolConfig 已内置官方要求的全部构建约束，
+// 其中最重要的是 build.target = ['es2017','chrome61'] —— 缺少它
+// 会把 `??` 等 ES2020 语法保留进产物，在低端 WebView 上白屏且无报错。
+export default defineMinitoolConfig({
+  // 需要额外覆盖时在此添加，例如：
+  // server: { port: 5173 },
+});