xhs-minitool-creator 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 navhu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# xhs-minitool-creator
+
+小红书「小工具」脚手架：一键创建合规项目、构建、打包、静态校验，内置官方打包规范 Skill。
+
+- **零系统依赖**：ZIP 用纯 Node 实现，校验也是纯 Node —— 不再依赖系统 `zip` / `zipinfo` / Python，Windows / macOS / Linux 均可使用
+- **默认即合规**：Vite 预设内置 `build.target: ['es2017', 'chrome61']`，从源头避免 ES2020 语法泄漏导致的真机白屏
+- **以官方规范为准**：内置官方打包规范 Skill（`minitool-zip-builder`）v1.6.0，校验规则与之一致
+
+## 快速开始
+
+```bash
+# 创建项目（交互式）
+npx xhs-minitool-creator my-tool
+
+# 非交互式
+npx xhs-minitool-creator my-tool --yes --title "我的工具" --theme "#ff2442"
+
+cd my-tool
+npm install
+npm run dev      # 本地预览
+npm run build    # 构建 + 打包，输出 my-tool-xhs-tool.zip
+npm run validate # 静态校验
+```
+
+将 `my-tool-xhs-tool.zip` 上传至小红书创作服务平台即可。
+
+## CLI 命令
+
+```
+xhs-minitool-creator <name>                    创建新项目（默认子命令）
+xhs-minitool-creator create <name> [选项]      同上
+xhs-minitool-creator pack [选项]               整理产物并打包
+xhs-minitool-creator validate <目录|zip>       静态校验
+xhs-minitool-creator skill                     查看内置官方 Skill 版本
+xhs-minitool-creator skill update --url <地址> 手动更新官方 Skill
+```
+
+### create 选项
+
+| 选项 | 说明 |
+| --- | --- |
+| `-y, --yes` | 跳过交互，全部使用默认值 |
+| `--title <标题>` | 页面标题（默认同项目名） |
+| `--desc <描述>` | 项目描述 |
+| `--icon <字符>` | 首页图标字符（默认「工」） |
+| `--theme <颜色>` | 主题色（默认 `#ff2442`） |
+
+### 编程式使用
+
+```js
+import { defineMinitoolConfig } from 'xhs-minitool-creator/vite';
+import { pack } from 'xhs-minitool-creator';
+import { validateDir } from 'xhs-minitool-creator/validate';
+```
+
+## 为什么需要这个脚手架
+
+参考实现（`create-xhs-minitool`）存在几个长期风险：
+
+1. 依赖系统 `zip` / `zipinfo` 二进制，Windows 不可用
+2. 校验依赖 Python，且规则停留在旧版规范
+3. Vite 预设未设置 `build.target`，ES2020 语法（`??`）会泄漏进产物，在低端 WebView 上白屏且无报错
+4. 内置的官方规范快照会随官方演进而过时
+
+本脚手架的对应方案：
+
+1. ZIP 写入用 Node `zlib.deflateRawSync` 自实现，交叉验证过 macOS `unzip` 与 Python `zipfile`
+2. 校验为纯 Node 静态扫描，规则对齐官方 Skill v1.6.0（含 10 MiB 硬上限、经典脚本约束、ES2017 基线）
+3. 预设显式声明 `build.target: ['es2017', 'chrome61']`
+4. 提供 `skill` 子命令查看版本并手动更新
+
+## 官方规范 Skill 的更新
+
+官方 CDN **没有稳定的 latest 端点**（URL 内含不可预测的时间戳），因此无法自动发现新版本。做法：
+
+1. 从官方文档取得最新 `.skill` 地址
+2. 执行 `xhs-minitool-creator skill update --url <地址>`
+
+校验依据随 Skill 更新而变化时，请同时关注本包的新版本发布。
+
+## 限制与说明
+
+- 静态校验无法替代真机验证，交付前请务必在小红书真机预览
+- 官方规则可能随时调整，关键决策以小红书创作服务平台实时规则为准
+- 本脚手架与小红书官方无隶属关系，`minitool-zip-builder` Skill 版权归小红书所有
+
+## License
+
+MIT

package/bin/create.mjs

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+/**
+ * xhs-minitool-creator —— 小红书小工具脚手架
+ *
+ * 子命令：
+ *   create  [name]          创建新项目（默认子命令，可直接 xhs-minitool-creator <name>）
+ *   pack                    整理构建产物并打出可上传 zip
+ *   validate [dir|zip]      静态合规校验（官方 Skill v1.6.0 规则）
+ *   skill [info|update]     查看 / 更新内置官方打包规范 Skill
+ *
+ * 零运行时依赖，仅使用 Node 内置模块。
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve, relative, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { pack } from '../src/pack.mjs';
+import { validateDir, validateZip, formatIssues } from '../src/validate.mjs';
+import { printSkillInfo, skillUpdate } from '../src/skill.mjs';
+
+const PKG_ROOT = fileURLToPath(new URL('..', import.meta.url));
+const TEMPLATE_DIR = join(PKG_ROOT, 'template');
+
+const HELP = `xhs-minitool-creator —— 小红书小工具脚手架
+
+用法：
+  xhs-minitool-creator <name>                    创建新项目（默认子命令）
+  xhs-minitool-creator create <name> [选项]      同上
+  xhs-minitool-creator pack [选项]               整理产物并打包
+  xhs-minitool-creator validate <目录|zip>       静态校验
+  xhs-minitool-creator skill                     查看内置官方 Skill 版本
+  xhs-minitool-creator skill update --url <地址> 手动更新官方 Skill
+
+create 选项：
+  -y, --yes          跳过交互，全部使用默认值
+  --title <标题>     页面标题（默认同项目名）
+  --desc <描述>      项目描述
+  --icon <字符>      首页图标字符（默认「工」）
+  --theme <颜色>     主题色（默认 #ff2442）
+
+pack 选项：
+  --outDir <目录>    构建产物目录（默认 xhs-tool）
+  --zipName <文件名> 输出 zip 名（默认 <包名>-xhs-tool.zip）
+  --strict           警告也视为失败
+
+其他：
+  -v, --version      显示版本
+  -h, --help         显示帮助
+`;
+
+const PKG = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'));
+
+function fail(msg) {
+  console.error(`\n✗ ${msg}`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const args = { _: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--yes' || a === '-y') args.flags.yes = true;
+    else if (a === '--strict') args.flags.strict = true;
+    else if (a === '--no-strict' || a === '--strict=false') args.flags.strict = false;
+    else if (a === '--title' || a === '--desc' || a === '--icon' || a === '--theme' ||
+             a === '--outDir' || a === '--zipName' || a === '--url') {
+      const v = argv[i + 1];
+      if (!v) fail(`选项 ${a} 缺少参数`);
+      args.flags[a.slice(2)] = v;
+      i += 1;
+    } else if (a === '--version' || a === '-v') args.flags.version = true;
+    else if (a === '--help' || a === '-h') args.flags.help = true;
+    else if (a.startsWith('-')) fail(`未知选项 ${a}`);
+    else args._.push(a);
+  }
+  return args;
+}
+
+/* ============================ 创建项目 ============================ */
+
+const NAME_RE = /^[a-z][a-z0-9-]*$/;
+const RESERVED = new Set(['node_modules', 'src', 'dist', 'xhs-tool', 'public']);
+
+function normalizeName(raw) {
+  const name = raw.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+  if (!name) return null;
+  return name.slice(0, 60);
+}
+
+function validName(name) {
+  if (!NAME_RE.test(name) || RESERVED.has(name)) return false;
+  if (name.length > 60) return false;
+  return true;
+}
+
+async function prompt(text, fallback) {
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = (await rl.question(text)).trim();
+    return answer || fallback;
+  } finally {
+    rl.close();
+  }
+}
+
+function copyTemplate(targetDir, vars) {
+  const srcDir = TEMPLATE_DIR;
+
+  const walk = (dir) => {
+    const out = [];
+    for (const name of readdirSync(dir)) {
+      const p = join(dir, name);
+      if (statSync(p).isDirectory()) out.push(...walk(p));
+      else out.push(p);
+    }
+    return out;
+  };
+
+  let count = 0;
+  for (const file of walk(srcDir)) {
+    let rel = relative(srcDir, file).split('\\').join('/');
+    // npm 发布时 .gitignore 会被吞掉，模板内用 _gitignore 占位，落盘时改回
+    if (rel === '_gitignore') rel = '.gitignore';
+
+    const dest = join(targetDir, rel);
+    mkdirSync(dirname(dest), { recursive: true });
+
+    const ext = rel.split('.').pop();
+    let content = readFileSync(file);
+
+    if (['html', 'json', 'css'].includes(ext)) {
+      let text = content.toString('utf8');
+      if (rel === 'package.json') {
+        text = text.replace(/\{\{NAME\}\}/g, vars.name).replace(/\{\{DESC\}\}/g, vars.desc);
+      } else if (rel === 'index.html') {
+        text = text
+          .replace(/\{\{NAME\}\}/g, vars.title)
+          .replace(/\{\{TITLE\}\}/g, vars.title)
+          .replace(/\{\{DESC\}\}/g, vars.desc)
+          .replace(/\{\{ICON\}\}/g, vars.icon);
+      } else if (rel.endsWith('.css') && vars.theme && vars.theme !== '#ff2442') {
+        text = text.replace(/--accent:\s*#[0-9a-fA-F]{3,8};/, `--accent: ${vars.theme};`);
+      }
+      content = Buffer.from(text, 'utf8');
+    }
+
+    writeFileSync(dest, content);
+    count += 1;
+  }
+  return count;
+}
+
+async function createProject(args, flags) {
+  const rawName = args._[0];
+  const tty = Boolean(stdin.isTTY && stdout.isTTY);
+
+  let name = rawName ? normalizeName(rawName) : null;
+
+  if (!flags.yes && tty) {
+    console.log('\n创建小红书小工具项目\n');
+
+    let input = name;
+    while (!input || !validName(input)) {
+      input = await prompt(
+        '项目名（小写字母/数字/连字符，如 lucky-draw）：',
+        name || '',
+      ).then((v) => normalizeName(v));
+      if (!input) {
+        console.log('  名称无效，请重新输入');
+      }
+    }
+    name = input;
+
+    const title = await prompt(`页面标题（默认「${name}」）：`, name);
+    const desc = await prompt('项目描述（可选）：', '一个小红书小工具');
+    const icon = await prompt('首页图标字符（默认「工」）：', '工');
+    const theme = await prompt('主题色（默认 #ff2442）：', '#ff2442');
+
+    const finalVars = { name, title, desc, icon, theme };
+    console.log(`\n将创建：${name}（标题「${title}」，主题色 ${theme}）`);
+    const ok = await prompt('确认？(Y/n) ：', 'Y');
+    if (ok && !/^y/i.test(ok)) fail('已取消');
+    await doCreate(name, finalVars);
+  } else {
+    if (!name) {
+      fail('缺少项目名，例如：xhs-minitool-creator lucky-draw');
+    }
+    if (!validName(name)) {
+      fail(`项目名「${name}」不合法：需以小写字母开头，仅含小写字母/数字/连字符`);
+    }
+    const finalVars = {
+      name,
+      title: flags.title || name,
+      desc: flags.desc || '一个小红书小工具',
+      icon: flags.icon || '工',
+      theme: flags.theme || '#ff2442',
+    };
+    await doCreate(name, finalVars);
+  }
+}
+
+async function doCreate(name, vars) {
+  const targetDir = resolve(process.cwd(), name);
+
+  if (existsSync(targetDir) && readdirSync(targetDir).length > 0) {
+    fail(`目录 ${name} 已存在且不为空，为避免覆盖请换一个名字或清空该目录`);
+  }
+  mkdirSync(targetDir, { recursive: true });
+
+  const count = copyTemplate(targetDir, vars);
+  console.log(`\n✓ 已在 ./${name} 创建项目（${count} 个文件，含官方打包规范 Skill v1.6.0）`);
+
+  console.log('\n下一步：');
+  console.log(`  cd ${name}`);
+  console.log('  npm install');
+  console.log('  npm run dev      # 本地预览');
+  console.log('  npm run build    # 构建 + 打包（输出 <项目名>-xhs-tool.zip）');
+  console.log('  npm run validate # 静态校验');
+  console.log('\n上传入口：小红书创作服务平台（以平台实时规则为准）');
+}
+
+/* ============================ 其他子命令 ============================ */
+
+function cmdPack(flags) {
+  const code = pack({
+    outDir: flags.outDir || 'xhs-tool',
+    zipName: flags.zipName,
+    strict: flags.strict !== undefined ? flags.strict : true,
+  });
+  process.exit(code);
+}
+
+function cmdValidate(args, flags) {
+  const target = args._[0];
+  if (!target) {
+    fail('请指定要校验的目录或 zip，例如：xhs-minitool-creator validate ./xhs-tool');
+  }
+  const strict = flags.strict !== undefined ? flags.strict : true;
+
+  let result;
+  if (target.endsWith('.zip')) {
+    if (!existsSync(target)) fail(`文件不存在：${target}`);
+    result = validateZip(target, readFileSync(target), { strict });
+  } else {
+    if (!existsSync(target)) fail(`目录不存在：${target}`);
+    result = validateDir(target, { strict });
+  }
+
+  if (result.errors.length || result.warnings.length) {
+    console.log('\n' + formatIssues(result));
+  }
+  const { files, bytes } = result.summary || {};
+  const sizeText = bytes ? `${(bytes / 1024 / 1024).toFixed(2)} MiB` : '-';
+  console.log(`\n${result.errors.length} 错误 / ${result.warnings.length} 警告 · ${files || '-'} 个文件 · ${sizeText}`);
+  if (result.errors.length) {
+    console.log('✗ 校验未通过');
+    process.exit(1);
+  }
+  if (result.warnings.length) {
+    console.log(strict ? '⚠ 有警告（strict 模式视为失败，可加 --no-strict 忽略）' : '✓ 校验通过（有警告）');
+    process.exit(strict ? 2 : 0);
+  }
+  console.log('✓ 校验通过');
+  process.exit(0);
+}
+
+function cmdSkill(args, flags) {
+  const sub = args._[0] || 'info';
+  if (sub === 'info' || sub === 'show') {
+    printSkillInfo();
+    process.exit(0);
+  }
+  if (sub === 'update') {
+    try {
+      skillUpdate(flags.url, process.cwd());
+      process.exit(0);
+    } catch (e) {
+      fail(e.message);
+    }
+  }
+  fail(`未知 skill 子命令「${sub}」，可用：info | update --url <地址>`);
+}
+
+/* ============================ 入口 ============================ */
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (!argv.length) {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  const args = parseArgs(argv);
+  if (args.flags.help) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  if (args.flags.version) {
+    console.log(PKG.version);
+    process.exit(0);
+  }
+
+  // 第一个非选项参数是子命令名，否则视为项目名（默认 create）
+  const first = args._[0];
+  const SUBCOMMANDS = new Set(['create', 'pack', 'validate', 'skill']);
+
+  if (first && SUBCOMMANDS.has(first)) {
+    args._.shift();
+    const sub = first;
+    if (sub === 'create') return createProject(args, args.flags);
+    if (sub === 'pack') return cmdPack(args.flags);
+    if (sub === 'validate') return cmdValidate(args, args.flags);
+    if (sub === 'skill') return cmdSkill(args, args.flags);
+  }
+
+  // 默认 create
+  return createProject(args, args.flags);
+}
+
+main().catch((e) => fail(e.message || String(e)));

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "xhs-minitool-creator",
+  "version": "1.0.0",
+  "description": "小红书小工具脚手架：创建项目 / Vite 构建预设 / 打包 / 静态校验，内置官方打包规范 Skill",
+  "type": "module",
+  "bin": {
+    "xhs-minitool-creator": "bin/create.mjs"
+  },
+  "main": "src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./vite": "./src/vite-preset.mjs",
+    "./pack": "./src/pack.mjs",
+    "./validate": "./src/validate.mjs",
+    "./skill": "./src/skill.mjs",
+    "./zip": "./src/zip.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "template",
+    "template/.agents",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "keywords": [
+    "xiaohongshu",
+    "小红书",
+    "minitool",
+    "小工具",
+    "create",
+    "vite",
+    "scaffold"
+  ],
+  "license": "MIT"
+}

package/src/index.mjs

@@ -0,0 +1,9 @@
+/**
+ * xhs-minitool-creator 库入口
+ * CLI 见 bin/create.mjs；此文件供编程式调用（可选）。
+ */
+export { defineMinitoolConfig } from './vite-preset.mjs';
+export { pack, patchIndexHtml } from './pack.mjs';
+export { validateDir, validateZip, formatIssues, ALLOWED_EXT } from './validate.mjs';
+export { createZip, listZipEntries } from './zip.mjs';
+export { skillInfo, skillUpdate, DEFAULT_SKILL_PATH } from './skill.mjs';

package/src/pack.mjs

@@ -0,0 +1,188 @@
+/**
+ * 整理构建产物并打出可上传的 zip
+ *
+ * 继承并强化原 xhs-minitool-pack 的思路：
+ *  - 白名单过滤、清空空目录
+ *  - patchIndexHtml：绝对路径转相对、去掉 crossorigin/manifest、
+ *    脚本重建为经典脚本并移到 </body> 前
+ *  - 从目录内部打包，保证 index.html 位于 zip 根
+ *
+ * 关键改进：zip 用纯 Node 实现（src/zip.mjs），
+ * 不再依赖系统的 zip / zipinfo 二进制，Windows 亦可用。
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, relative, resolve } from 'node:path';
+import { createZip, listZipEntries } from './zip.mjs';
+import { ALLOWED_EXT, validateDir, validateZip, formatIssues } from './validate.mjs';
+
+function walk(dir) {
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    if (statSync(p).isDirectory()) out.push(...walk(p));
+    else out.push(p);
+  }
+  return out;
+}
+
+function removeUnsupported(outDir) {
+  for (const file of walk(outDir)) {
+    const ext = extname(file).toLowerCase();
+    if (!ALLOWED_EXT.has(ext)) {
+      rmSync(file, { force: true });
+      console.log(`  · 移除不支持的文件：${relative(outDir, file)}`);
+    }
+  }
+}
+
+function pruneEmptyDirs(dir) {
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    if (statSync(p).isDirectory()) {
+      pruneEmptyDirs(p);
+      if (readdirSync(p).length === 0) rmSync(p, { recursive: true, force: true });
+    }
+  }
+}
+
+/**
+ * 修正 index.html 使其符合容器要求。
+ * 这是整个流程里最容易出错也最有价值的一步。
+ */
+export function patchIndexHtml(outDir) {
+  const htmlPath = join(outDir, 'index.html');
+  if (!existsSync(htmlPath)) {
+    throw new Error(`${relative(process.cwd(), htmlPath)} 不存在，请先执行构建`);
+  }
+
+  let html = readFileSync(htmlPath, 'utf8');
+
+  // 绝对路径资源 -> 相对路径（离线 zip 根为 /）
+  html = html.replace(/(href|src)="\/([^"]+)"/g, '$1="./$2"');
+  // 去掉 crossorigin（离线同源无需，且部分内核处理异常）
+  html = html.replace(/\s+crossorigin(?:="[^"]*")?/g, '');
+  // 移除 manifest（容器内无意义，且与 PWA 行为冲突）
+  html = html.replace(/<link[^>]+rel="manifest"[^>]*>/gi, '');
+
+  // 收集所有外置脚本，重建为经典脚本（顺带消除 type="module"），
+  // 并统一挪到 </body> 前，保证 IIFE 依赖的 DOM 已存在。
+  // ^\s* 整行消费保证多次运行幂等（不会累积缩进空白）。
+  const scripts = [];
+  html = html.replace(
+    /^[ \t]*<script(?:\s[^>]*)?\ssrc="(\.\/[^"]+)"(?:\s[^>]*)?>\s*<\/script>[ \t]*\r?\n?/gim,
+    (_m, src) => {
+      scripts.push(`<script src="${src}"></script>`);
+      return '';
+    },
+  );
+
+  if (scripts.length) {
+    if (/<\/body>/i.test(html)) {
+      html = html.replace(/<\/body>/i, `    ${scripts.join('\n    ')}\n  </body>`);
+    } else {
+      html += `\n${scripts.join('\n')}\n`;
+    }
+  }
+
+  writeFileSync(htmlPath, html);
+  return scripts.length;
+}
+
+function copyIcons(outDir, publicDir) {
+  for (const icon of ['icon-192.svg', 'icon-512.svg']) {
+    const dest = join(outDir, 'icons', icon);
+    const src = join(publicDir, 'icons', icon);
+    if (!existsSync(dest) && existsSync(src)) {
+      mkdirSync(dirname(dest), { recursive: true });
+      copyFileSync(src, dest);
+    }
+  }
+}
+
+function readPackageName(cwd) {
+  const pkgPath = join(cwd, 'package.json');
+  if (!existsSync(pkgPath)) return 'minitool';
+  try {
+    return JSON.parse(readFileSync(pkgPath, 'utf8')).name || 'minitool';
+  } catch {
+    return 'minitool';
+  }
+}
+
+/**
+ * @param {{
+ *   cwd?: string, outDir?: string, zipName?: string, publicDir?: string,
+ *   skipValidate?: boolean, strict?: boolean
+ * }} [options]
+ */
+export function pack(options = {}) {
+  const cwd = resolve(options.cwd || process.cwd());
+  const outDir = resolve(cwd, options.outDir || 'xhs-tool');
+  const zipName = options.zipName || `${readPackageName(cwd)}-xhs-tool.zip`;
+  const zipPath = resolve(cwd, zipName);
+  const publicDir = resolve(cwd, options.publicDir || 'public');
+
+  if (!existsSync(outDir)) {
+    throw new Error(`缺少输出目录 ${relative(cwd, outDir)}，请先执行构建`);
+  }
+
+  console.log('\n▸ 整理产物');
+  copyIcons(outDir, publicDir);
+  removeUnsupported(outDir);
+  pruneEmptyDirs(outDir);
+  const scriptCount = patchIndexHtml(outDir);
+  console.log(`  · 已修正 index.html（${scriptCount} 个脚本重建为经典脚本并移至 body 末尾）`);
+
+  console.log('\n▸ 打包');
+  const files = walk(outDir);
+  const entries = files.map((file) => ({
+    name: relative(outDir, file).split('\\').join('/'),
+    data: readFileSync(file),
+  }));
+
+  if (!entries.some((e) => e.name === 'index.html')) {
+    throw new Error('产物根目录缺少 index.html');
+  }
+
+  const zipBuf = createZip(entries);
+  writeFileSync(zipPath, zipBuf);
+
+  // 自检：确认 zip 结构正确（根含 index.html、无禁止文件）
+  const listed = listZipEntries(zipBuf).map((e) => e.name);
+  if (!listed.includes('index.html')) {
+    throw new Error('zip 根目录缺少 index.html（可能多套了一层目录）');
+  }
+  for (const bad of listed) {
+    if (bad.startsWith('node_modules/') || bad.endsWith('.map')) {
+      throw new Error(`zip 内含禁止文件：${bad}`);
+    }
+  }
+
+  const mib = (n) => `${(n / 1024 / 1024).toFixed(2)} MiB`;
+  console.log(`  · zip 已生成：${relative(cwd, zipPath)}`);
+  console.log(`  · 条目 ${listed.length} 个，体积 ${mib(zipBuf.length)}（硬上限 10 MiB，建议 ≤ 2 MiB）`);
+
+  console.log('\n▸ 校验');
+  const dirResult = validateDir(outDir, { strict: options.strict });
+  const zipResult = validateZip(zipName, zipBuf, { strict: options.strict });
+
+  const allErrors = [...dirResult.errors, ...zipResult.errors];
+  const allWarnings = [...dirResult.warnings, ...zipResult.warnings];
+
+  if (allErrors.length || allWarnings.length) {
+    console.log(formatIssues({ errors: allErrors, warnings: allWarnings }));
+  }
+
+  if (allErrors.length) {
+    console.log(`\n✗ 校验未通过：${allErrors.length} 个错误，${allWarnings.length} 个警告`);
+    return 1;
+  }
+  if (allWarnings.length) {
+    console.log(`\n⚠ 校验通过（有 ${allWarnings.length} 个警告）`);
+    return options.strict === false ? 0 : 2;
+  }
+  console.log('\n✓ 校验通过：0 错误 0 警告');
+  return 0;
+}
+
+export default pack;