xhs-minitool-creator 1.0.0 → 1.1.0

package/README.md

@@ -1,88 +1,143 @@
 # 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，校验规则与之一致
+你只需要会最基本的终端操作：输入一条命令，就得到一个可以直接上传小红书的工具页面。不需要懂打包配置，不需要懂 zip 格式，也不需要提前了解小红书的开发规范——它都帮你处理好了。
 
-## 快速开始
+---
+
+## 快速上手（3 步）
+
+> 前提：电脑上装好 [Node.js](https://nodejs.org)（18.17 或更新版本）。装好后在终端输入 `node -v` 能显示版本号即可。
+
+### 第 1 步：创建项目
+
+在终端里输入（把 `my-tool` 换成你喜欢的名字，只能用小写字母、数字和短横线）：
 
 ```bash
-# 创建项目（交互式）
 npx xhs-minitool-creator my-tool
+```
+
+输入后它会问你几个简单的问题（页面标题、描述等），**不想回答就一路按回车**，全部用默认值即可。
 
-# 非交互式
-npx xhs-minitool-creator my-tool --yes --title "我的工具" --theme "#ff2442"
+### 第 2 步：进入项目并安装依赖
 
+```bash
 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 命令
+### 第 3 步：打包
 
+```bash
+npm run build
 ```
-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
+
+完成后，项目目录下会多出一个 `my-tool-xhs-minitool.zip`。**把这个 zip 上传到小红书创作服务平台，你的小工具就上线了。**
+
+---
+
+## 日常使用
+
+```bash
+npm run dev      # 本地预览：改代码时边改边看效果
+npm run build    # 打包：生成可上传的 zip
+npm run validate # 体检：检查有没有违反平台规则的地方
 ```
 
-### create 选项
+改完代码后，重新执行 `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"   指定主题色
+```
 
 | 选项 | 说明 |
 | --- | --- |
-| `-y, --yes` | 跳过交互，全部使用默认值 |
-| `--title <标题>` | 页面标题（默认同项目名） |
-| `--desc <描述>` | 项目描述 |
-| `--icon <字符>` | 首页图标字符（默认「工」） |
-| `--theme <颜色>` | 主题色（默认 `#ff2442`） |
+| `--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. 内置的官方规范快照会随官方演进而过时
+- 一个开箱即用的示例页面（单页多视图，适配平台顶部导航栏与安全区）
+- 已配置好的构建工具（Vite），**默认输出到 `xhs-minitool/` 目录**
+- 打包与检查命令（纯 Node 实现，Windows / macOS / Linux 都能用）
+- 官方开发规范 `minitool-zip-builder`（放在 `.agents/skills/`，给 AI 或人参考）
 
-本脚手架的对应方案：
+### 更新官方开发规范
 
-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 的更新
+1. 从官方渠道拿到最新规范包的下载地址（`.skill` 文件）
+2. 在项目目录执行：
 
-官方 CDN **没有稳定的 latest 端点**（URL 内含不可预测的时间戳），因此无法自动发现新版本。做法：
+```bash
+npx xhs-minitool-creator skill update --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 <目录>            # 指定产物目录再打包
+```
 
-1. 从官方文档取得最新 `.skill` 地址
-2. 执行 `xhs-minitool-creator skill update --url <地址>`
+### 编程式使用
+
+```js
+import { defineMinitoolConfig } from 'xhs-minitool-creator/vite';
+import { pack, validateDir } from 'xhs-minitool-creator';
+```
 
-校验依据随 Skill 更新而变化时，请同时关注本包的新版本发布。
+---
 
-## 限制与说明
+## 说明
 
-- 静态校验无法替代真机验证，交付前请务必在小红书真机预览
-- 官方规则可能随时调整，关键决策以小红书创作服务平台实时规则为准
-- 本脚手架与小红书官方无隶属关系，`minitool-zip-builder` Skill 版权归小红书所有
+- 打包时若检测到系统自带 `zip` 命令（macOS 自带）会优先使用；没有则自动改用内置打包器，结果一致
+- 静态检查无法替代真机验证，上线前请务必在小红书真机预览
+- 平台规则可能随时调整，关键决策以小红书创作服务平台实时规则为准
 
 ## License
 

package/bin/create.mjs

@@ -40,8 +40,8 @@ create 选项：
   --theme <颜色>     主题色（默认 #ff2442）
 
 pack 选项：
-  --outDir <目录>    构建产物目录（默认 xhs-tool）
-  --zipName <文件名> 输出 zip 名（默认 <包名>-xhs-tool.zip）
+  --outDir <目录>    构建产物目录（默认 xhs-minitool）
+  --zipName <文件名> 输出 zip 名（默认 <包名>-xhs-minitool.zip）
   --strict           警告也视为失败
 
 其他：
@@ -215,7 +215,7 @@ async function doCreate(name, vars) {
   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 build    # 构建 + 打包（输出 <项目名>-xhs-minitool.zip）');
   console.log('  npm run validate # 静态校验');
   console.log('\n上传入口：小红书创作服务平台（以平台实时规则为准）');
 }
@@ -224,7 +224,7 @@ async function doCreate(name, vars) {
 
 function cmdPack(flags) {
   const code = pack({
-    outDir: flags.outDir || 'xhs-tool',
+    outDir: flags.outDir || 'xhs-minitool',
     zipName: flags.zipName,
     strict: flags.strict !== undefined ? flags.strict : true,
   });
@@ -234,7 +234,7 @@ function cmdPack(flags) {
 function cmdValidate(args, flags) {
   const target = args._[0];
   if (!target) {
-    fail('请指定要校验的目录或 zip，例如：xhs-minitool-creator validate ./xhs-tool');
+    fail('请指定要校验的目录或 zip，例如：xhs-minitool-creator validate ./xhs-minitool');
   }
   const strict = flags.strict !== undefined ? flags.strict : true;
 

package/package.json

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

package/src/pack.mjs

@@ -12,6 +12,7 @@
  */
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, 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';
 
@@ -109,6 +110,37 @@ function readPackageName(cwd) {
   }
 }
 
+/** 系统 zip 命令是否可用（macOS 自带；多数 Linux 需自行安装；Windows 无） */
+function systemZipAvailable() {
+  const probe = spawnSync('zip', ['-v'], { stdio: 'ignore' });
+  return !probe.error && probe.status === 0;
+}
+
+/**
+ * 打 zip：优先使用系统 zip 命令（行为与平台工具一致），
+ * 不可用时回退到纯 Node 实现（零依赖，跨平台兜底）。
+ * 两种路径产物都会被自实现读取器校验结构。
+ */
+function makeZip(outDir, zipPath, entries) {
+  if (systemZipAvailable()) {
+    if (existsSync(zipPath)) rmSync(zipPath, { force: true });
+    const result = spawnSync('zip', ['-r', zipPath, '.', '-x', '*.DS_Store'], {
+      cwd: outDir,
+      encoding: 'utf8',
+    });
+    if (result.status !== 0) {
+      throw new Error(`系统 zip 打包失败：${result.stderr || result.stdout || 'unknown'}`);
+    }
+    console.log('  · 使用系统 zip 命令打包');
+    return readFileSync(zipPath);
+  }
+
+  console.log('  · 未检测到系统 zip，使用内置打包器');
+  const zipBuf = createZip(entries);
+  writeFileSync(zipPath, zipBuf);
+  return zipBuf;
+}
+
 /**
  * @param {{
  *   cwd?: string, outDir?: string, zipName?: string, publicDir?: string,
@@ -117,8 +149,8 @@ function readPackageName(cwd) {
  */
 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 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');
 
@@ -144,8 +176,7 @@ export function pack(options = {}) {
     throw new Error('产物根目录缺少 index.html');
   }
 
-  const zipBuf = createZip(entries);
-  writeFileSync(zipPath, zipBuf);
+  const zipBuf = makeZip(outDir, zipPath, entries);
 
   // 自检：确认 zip 结构正确（根含 index.html、无禁止文件）
   const listed = listZipEntries(zipBuf).map((e) => e.name);

package/src/vite-preset.mjs

@@ -14,7 +14,7 @@ export function defineMinitoolConfig(overrides = {}) {
   return {
     base: './',
     build: {
-      outDir: 'xhs-tool',
+      outDir: 'xhs-minitool',
       emptyOutDir: true,
       assetsInlineLimit: 0,
       cssCodeSplit: false,

package/template/_gitignore

@@ -1,6 +1,6 @@
 node_modules/
 dist/
-xhs-tool/
+xhs-minitool/
 *.zip
 .DS_Store
 *.log

package/template/package.json

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