xhs-minitool-creator 1.1.0 → 1.2.0

package/README.md

@@ -1,143 +1,80 @@
 # xhs-minitool-creator
 
-一个命令行工具，帮你创建、打包、检查**小红书小工具**项目。
+小红书「小工具」项目脚手架：创建、构建、打包、合规校验，一条命令完成。
 
-你只需要会最基本的终端操作：输入一条命令，就得到一个可以直接上传小红书的工具页面。不需要懂打包配置，不需要懂 zip 格式，也不需要提前了解小红书的开发规范——它都帮你处理好了。
+你不需要先啃小红书小工具的平台规范，脚手架已把平台约束内置到构建配置与校验规则中。用它产出的 zip 直接上传创作服务平台即可。
 
----
-
-## 快速上手（3 步）
-
-> 前提：电脑上装好 [Node.js](https://nodejs.org)（18.17 或更新版本）。装好后在终端输入 `node -v` 能显示版本号即可。
-
-### 第 1 步：创建项目
-
-在终端里输入（把 `my-tool` 换成你喜欢的名字，只能用小写字母、数字和短横线）：
-
-```bash
-npx xhs-minitool-creator my-tool
-```
-
-输入后它会问你几个简单的问题（页面标题、描述等），**不想回答就一路按回车**，全部用默认值即可。
-
-### 第 2 步：进入项目并安装依赖
+## 快速开始
 
 ```bash
+npx xhs-minitool-creator my-tool -y
 cd my-tool
 npm install
+npm run build   # 产出 my-tool-xhs-minitool.zip，上传创作服务平台即可
 ```
 
-第一次会下载一些文件，等待几十秒。
-
-### 第 3 步：打包
-
-```bash
-npm run build
-```
-
-完成后，项目目录下会多出一个 `my-tool-xhs-minitool.zip`。**把这个 zip 上传到小红书创作服务平台，你的小工具就上线了。**
-
----
-
-## 日常使用
+交互式创建（自定义标题 / 描述）：
 
 ```bash
-npm run dev      # 本地预览：改代码时边改边看效果
-npm run build    # 打包：生成可上传的 zip
-npm run validate # 体检：检查有没有违反平台规则的地方
+npx xhs-minitool-creator my-tool
 ```
 
-改完代码后，重新执行 `npm run build`，把新生成的 zip 再传一次即可更新。
-
----
-
-## 常见问题
+## 命令
 
-**我需要会写代码吗？**
-
-会用就行。它生成的项目自带一个能跑通的示例页面（输入名字、显示计数），你可以直接照葫芦画瓢改文字、改颜色。想做得更复杂，可以基于示例继续加代码，或让 AI 按项目里自带的开发规范（`.agents/` 目录）帮你改。
-
-**打包时报错了怎么办？**
-
-执行 `npm run validate`，它会告诉你哪里不合规、怎么改。大多数问题（比如引用了网络图片）它都能直接指出。
-
-**zip 最大能多大？**
-
-平台硬性上限 10 MB，建议控制在 2 MB 以内。图片尽量压缩后再放进去。打包时工具会自动汇报体积。
-
-**为什么不能直接引用网络图片？**
-
-小红书小工具在离线环境运行，网络图片、网络请求都会被禁止。把图片下载下来放进 `public/` 目录即可。
-
-**这个工具和小红书官方是什么关系？**
-
-没有隶属关系。它只是把小红书的官方开发规范内置进来帮你自动检查，规范原文就在项目 `.agents/skills/` 目录里，会随官方更新。
-
----
-
-## 命令速查
-
-```
-npx xhs-minitool-creator <名字>                    创建项目（默认）
-npx xhs-minitool-creator <名字> --yes              跳过提问，全部用默认值
-npx xhs-minitool-creator <名字> --title "我的工具"   指定页面标题
-npx xhs-minitool-creator <名字> --theme "#ff2442"   指定主题色
-```
-
-| 选项 | 说明 |
+| 命令 | 作用 |
 | --- | --- |
-| `--yes` | 跳过提问，全部用默认值 |
-| `--title` | 页面标题 |
-| `--desc` | 项目描述 |
-| `--icon` | 首页图标字符（默认「工」） |
-| `--theme` | 主题色（默认 `#ff2442`） |
+| `npm run dev` | 本地预览（Vite dev server） |
+| `npm run build` | 构建 + 打包，输出 `<name>-xhs-minitool.zip` |
+| `npm run validate` | 静态合规校验（输出 ERROR / WARNING 汇总） |
+| `npm run skill` | 查看项目内置官方规范版本 |
 
----
+CLI 子命令 `create / pack / validate / skill`，详见 `npx xhs-minitool-creator --help`。
 
-## 进阶
+create 选项：`--yes`（跳过交互）、`--title`、`--desc`。
 
-### 项目里自带什么？
+## 生成的项目
 
-创建出的项目包含：
+- Vite 项目，构建预设已内置平台约束，输出目录 `xhs-minitool/`
+- 示例页面：单页多视图切换、适配平台原生导航栏与安全区
+- 官方打包规范 `minitool-zip-builder` 快照（`.agents/skills/`），可直接供 AI 参考辅助开发
 
-- 一个开箱即用的示例页面（单页多视图，适配平台顶部导航栏与安全区）
-- 已配置好的构建工具（Vite），**默认输出到 `xhs-minitool/` 目录**
-- 打包与检查命令（纯 Node 实现，Windows / macOS / Linux 都能用）
-- 官方开发规范 `minitool-zip-builder`（放在 `.agents/skills/`，给 AI 或人参考）
+## 平台约束速览
 
-### 更新官方开发规范
+- **完全离线**：禁 `fetch` / `XMLHttpRequest` / `WebSocket`；外部 `http(s)://` 资源（图片、字体、CDN 脚本）必须下载进包改相对路径
+- **CSP 限制**：禁内联 `<script>` 与行内事件（`onclick=` 等），脚本必须外置 + `addEventListener`
+- **经典脚本**：产物不允许 `type="module"` / `import`（离线环境下模块解析不可靠）——脚手架打包时自动转换，勿自行改回
+- **单页应用**：容器不打开新页面，多视图在单页内用 JS 切换 DOM
+- **WebView 基线低**：Chrome 61 / ES2017。构建预设已设 `build.target: ['es2017', 'chrome61']`，若自己覆盖 Vite 配置别把它弄丢（否则 `??` 等 ES2020 语法会泄漏，真机白屏无报错）
+- **体积**：zip 硬上限 10 MiB，建议 ≤ 2 MiB；单条 Base64 ≤ 1 MiB
+- **禁用 API**：`window.open`、Worker、剪贴板、地理定位、设备传感器、WebAssembly 等（`validate` 会扫描）
+- **安全区**：`viewport-fit=cover` + `env(safe-area-inset-*)`，且顶部需为平台原生导航栏让位
+- **原生能力**：官方提供 4 个 JSBridge API（发笔记、存相册等，见 `.agents/skills/` 内 `jsbridge-api.md`）
 
-官方规范会持续更新，且没有自动更新入口。做法：
+`npm run validate` 内置上述规则的静态扫描；静态检查无法覆盖运行时行为，交付前务必真机预览。
 
-1. 从官方渠道拿到最新规范包的下载地址（`.skill` 文件）
-2. 在项目目录执行：
+## 更新官方规范
 
-```bash
-npx xhs-minitool-creator skill update --url <地址>
-```
-
-### 检查命令的更多用法
+官方规范经小红书 CDN 分发，**无稳定 latest 端点**（URL 含时间戳），需手动更新：
 
 ```bash
-npx xhs-minitool-creator validate ./xhs-minitool        # 检查构建产物目录
-npx xhs-minitool-creator validate ./xxx-xhs-minitool.zip # 检查已打包的 zip
-npx xhs-minitool-creator pack --outDir <目录>            # 指定产物目录再打包
+npx xhs-minitool-creator skill update --url <官方 .skill 包地址>
 ```
 
-### 编程式使用
+## 编程式使用
 
 ```js
 import { defineMinitoolConfig } from 'xhs-minitool-creator/vite';
 import { pack, validateDir } from 'xhs-minitool-creator';
 ```
 
----
+## 打包器说明
+
+打包优先使用系统 `zip` 命令（macOS 自带），未安装则回退内置纯 Node 实现，两条路径产物一致；校验与 zip 读写零系统依赖（Windows / Linux 均可用）。
 
 ## 说明
 
-- 打包时若检测到系统自带 `zip` 命令（macOS 自带）会优先使用；没有则自动改用内置打包器，结果一致
-- 静态检查无法替代真机验证，上线前请务必在小红书真机预览
-- 平台规则可能随时调整，关键决策以小红书创作服务平台实时规则为准
+- 本工具与小红书官方无隶属关系，内置规范内容版权归小红书
+- 平台规则可能调整，关键决策以创作服务平台实时规则为准
 
 ## License
 

package/bin/create.mjs

@@ -11,7 +11,7 @@
  * 零运行时依赖，仅使用 Node 内置模块。
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from 'node:fs';
-import { join, resolve, relative, dirname } from 'node:path';
+import { join, resolve, relative, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
@@ -36,8 +36,6 @@ create 选项：
   -y, --yes          跳过交互，全部使用默认值
   --title <标题>     页面标题（默认同项目名）
   --desc <描述>      项目描述
-  --icon <字符>      首页图标字符（默认「工」）
-  --theme <颜色>     主题色（默认 #ff2442）
 
 pack 选项：
   --outDir <目录>    构建产物目录（默认 xhs-minitool）
@@ -63,8 +61,7 @@ function parseArgs(argv) {
     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') {
+    else if (a === '--title' || a === '--desc' || a === '--outDir' || a === '--zipName' || a === '--url') {
       const v = argv[i + 1];
       if (!v) fail(`选项 ${a} 缺少参数`);
       args.flags[a.slice(2)] = v;
@@ -119,6 +116,9 @@ function copyTemplate(targetDir, vars) {
 
   let count = 0;
   for (const file of walk(srcDir)) {
+    // macOS 目录垃圾文件不入模板
+    if (basename(file) === '.DS_Store') continue;
+
     let rel = relative(srcDir, file).split('\\').join('/');
     // npm 发布时 .gitignore 会被吞掉，模板内用 _gitignore 占位，落盘时改回
     if (rel === '_gitignore') rel = '.gitignore';
@@ -137,10 +137,7 @@ function copyTemplate(targetDir, vars) {
         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};`);
+          .replace(/\{\{DESC\}\}/g, vars.desc);
       }
       content = Buffer.from(text, 'utf8');
     }
@@ -160,26 +157,20 @@ async function createProject(args, flags) {
   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('  名称无效，请重新输入');
+    while (!name || !validName(name)) {
+      const answer = await prompt('项目名（必填，小写字母/数字/连字符，如 lucky-draw）：', '');
+      name = normalizeName(answer);
+      if (!name || !validName(name)) {
+        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 title = await prompt(`页面标题（回车跳过，默认「${name}」）：`, name);
+    const desc = await prompt('项目描述（回车跳过）：', '一个小红书小工具');
 
-    const finalVars = { name, title, desc, icon, theme };
-    console.log(`\n将创建：${name}（标题「${title}」，主题色 ${theme}）`);
-    const ok = await prompt('确认？(Y/n) ：', 'Y');
+    const finalVars = { name, title, desc };
+    console.log(`\n将创建：./${name}（标题「${title}」）`);
+    const ok = await prompt('确认创建？(Y/n，回车确认)：', 'Y');
     if (ok && !/^y/i.test(ok)) fail('已取消');
     await doCreate(name, finalVars);
   } else {
@@ -193,8 +184,6 @@ async function createProject(args, flags) {
       name,
       title: flags.title || name,
       desc: flags.desc || '一个小红书小工具',
-      icon: flags.icon || '工',
-      theme: flags.theme || '#ff2442',
     };
     await doCreate(name, finalVars);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xhs-minitool-creator",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "小红书小工具脚手架：创建项目 / Vite 构建预设 / 打包 / 静态校验，内置官方打包规范 Skill",
   "type": "module",
   "bin": {

package/src/pack.mjs

@@ -10,8 +10,8 @@
  * 关键改进：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 { existsSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { extname, join, relative, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { createZip, listZipEntries } from './zip.mjs';
 import { ALLOWED_EXT, validateDir, validateZip, formatIssues } from './validate.mjs';
@@ -89,17 +89,6 @@ export function patchIndexHtml(outDir) {
   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';
@@ -143,8 +132,8 @@ function makeZip(outDir, zipPath, entries) {
 
 /**
  * @param {{
- *   cwd?: string, outDir?: string, zipName?: string, publicDir?: string,
- *   skipValidate?: boolean, strict?: boolean
+ *   cwd?: string, outDir?: string, zipName?: string,
+ *   strict?: boolean
  * }} [options]
  */
 export function pack(options = {}) {
@@ -152,14 +141,12 @@ export function pack(options = {}) {
   const outDir = resolve(cwd, options.outDir || 'xhs-minitool');
   const zipName = options.zipName || `${readPackageName(cwd)}-xhs-minitool.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);

package/template/index.html

@@ -16,7 +16,7 @@
       -->
       <section class="page is-active" data-page="home">
         <header class="hero">
-          <div class="hero-icon">{{ICON}}</div>
+          <div class="hero-icon">😊</div>
           <h1 class="hero-title">{{TITLE}}</h1>
           <p class="hero-desc">{{DESC}}</p>
         </header>

package/template/package.json

@@ -14,7 +14,7 @@
   },
   "devDependencies": {
     "vite": "^6.3.5",
-    "xhs-minitool-creator": "^1.1.0"
+    "xhs-minitool-creator": "^1.2.0"
   },
   "engines": {
     "node": ">=18.17.0"

package/template/src/main.js

@@ -1,18 +1,15 @@
 import './styles/app.css';
-import { safeStorage } from './lib/storage.js';
 
 /**
  * 示例：一个最小可用的小工具页面。
  * 演示三件事：
- *  1. 事件用 addEventListener 绑定（容器禁止 onclick 等行内事件）
- *  2. 本地存储用 safeStorage 包装（个别环境 localStorage 会抛错）
- *  3. 多视图在单页内切换（容器不支持打开新页面）
+ *  1. 事件用 addEventListener 绑定（容器 CSP 禁止 onclick 等行内事件）
+ *  2. 多视图在单页内切换（容器不支持打开新页面）
+ *  3. 提示用页内 toast 元素实现（容器不支持系统弹窗）
  */
 
-const THEME_KEY = 'demo_theme';
-const COUNT_KEY = 'demo_count';
+let count = 0;
 
-/** 朴素但够用的 toast */
 function toast(message) {
   const el = document.getElementById('toast');
   if (!el) return;
@@ -28,7 +25,7 @@ function toast(message) {
 
 function renderCount() {
   const el = document.getElementById('count');
-  if (el) el.textContent = String(Number(safeStorage.get(COUNT_KEY) || 0));
+  if (el) el.textContent = String(count);
 }
 
 function init() {
@@ -37,12 +34,6 @@ function init() {
   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) {
@@ -50,22 +41,17 @@ function init() {
       input?.focus();
       return;
     }
-    safeStorage.set('demo_name', name);
-
-    const next = Number(safeStorage.get(COUNT_KEY) || 0) + 1;
-    safeStorage.set(COUNT_KEY, String(next));
+    count += 1;
     renderCount();
-
     if (greet) {
-      greet.textContent = `你好，${name}！这是第 ${next} 次使用。`;
+      greet.textContent = `你好，${name}！这是第 ${count} 次使用。`;
       greet.hidden = false;
     }
-    toast('已保存，下次打开还在');
+    toast('已更新');
   });
 
   resetBtn?.addEventListener('click', () => {
-    safeStorage.remove(COUNT_KEY);
-    safeStorage.remove('demo_name');
+    count = 0;
     if (input) input.value = '';
     if (greet) greet.hidden = true;
     renderCount();
@@ -74,7 +60,7 @@ function init() {
 
   // 主题跟随系统（仅作演示，可删）
   const dark = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches;
-  document.body.dataset.theme = safeStorage.get(THEME_KEY) || (dark ? 'dark' : 'light');
+  document.body.dataset.theme = dark ? 'dark' : 'light';
 }
 
 // 经典脚本环境下 DOM 已就绪（脚本在 body 末尾），直接初始化即可

package/template/src/styles/app.css

@@ -6,7 +6,7 @@
  */
 
 :root {
-  --accent: #ff2442; /* 由脚手架按主题色注入 */
+  --accent: #ff2442; /* 主题色，改成你喜欢的颜色即可 */
   --bg: #f6f6f8;
   --card: #ffffff;
   --text: #1a1a1e;

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

@@ -1,4 +0,0 @@
-<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

@@ -1,4 +0,0 @@
-<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

@@ -1,54 +0,0 @@
-/**
- * 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;