dsh-design-studio 0.10.0 → 0.12.0

package/lib/gallery/zip.js

@@ -0,0 +1,212 @@
+/**
+ * 极简 zip：打包（只存储不压缩，CRC32 自己算）和解包（存储 / deflate），不加依赖。
+ *
+ * 解包是给「朋友传来的 zip」用的，按不可信数据处理：
+ *   - 只收普通文件（目录项跳过）；软链接、加密、分卷、zip64 一律拒
+ *   - 路径：不能是绝对路径、不能有 ..、反斜杠、NUL、控制字符；Mac 打包带的 __MACOSX/、.DS_Store 直接跳过
+ *   - 个数、单个大小、总大小都有上限，解压时按上限截断（防 zip 炸弹：声明的大小不可信，以实际解出来的为准）
+ * 规则（扩展名白名单、内容检查）在 policy.js 的 checkPack 里，这里只管拆包本身安全
+ */
+
+import zlib from 'node:zlib'
+
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256)
+  for (let n = 0; n < 256; n++) {
+    let c = n
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+    t[n] = c >>> 0
+  }
+  return t
+})()
+
+export function crc32(buf) {
+  let c = 0xffffffff
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8)
+  return (c ^ 0xffffffff) >>> 0
+}
+
+/** DOS 时间（zip 里的修改时间） */
+function dosTime(d) {
+  const y = Math.max(1980, d.getFullYear())
+  return {
+    time: (d.getHours() << 11) | (d.getMinutes() << 5) | Math.floor(d.getSeconds() / 2),
+    date: ((y - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate(),
+  }
+}
+
+/** [{ path, data: Buffer }] → zip 的 Buffer（文件名 UTF-8，只存储） */
+export function writeZip(files, { now = new Date() } = {}) {
+  const { time, date } = dosTime(now)
+  const locals = []
+  const centrals = []
+  let offset = 0
+  for (const f of files) {
+    const name = Buffer.from(String(f.path), 'utf8')
+    const data = Buffer.isBuffer(f.data) ? f.data : Buffer.from(String(f.data), 'utf8')
+    const crc = crc32(data)
+    const lh = Buffer.alloc(30)
+    lh.writeUInt32LE(0x04034b50, 0)
+    lh.writeUInt16LE(20, 4) // 解压要的版本
+    lh.writeUInt16LE(0x0800, 6) // 第 11 位：文件名是 UTF-8
+    lh.writeUInt16LE(0, 8) // 只存储
+    lh.writeUInt16LE(time, 10)
+    lh.writeUInt16LE(date, 12)
+    lh.writeUInt32LE(crc, 14)
+    lh.writeUInt32LE(data.length, 18)
+    lh.writeUInt32LE(data.length, 22)
+    lh.writeUInt16LE(name.length, 26)
+    lh.writeUInt16LE(0, 28)
+    locals.push(lh, name, data)
+    const ch = Buffer.alloc(46)
+    ch.writeUInt32LE(0x02014b50, 0)
+    ch.writeUInt16LE(0x031e, 4) // 做出来的版本：Unix
+    ch.writeUInt16LE(20, 6)
+    ch.writeUInt16LE(0x0800, 8)
+    ch.writeUInt16LE(0, 10)
+    ch.writeUInt16LE(time, 12)
+    ch.writeUInt16LE(date, 14)
+    ch.writeUInt32LE(crc, 16)
+    ch.writeUInt32LE(data.length, 20)
+    ch.writeUInt32LE(data.length, 24)
+    ch.writeUInt16LE(name.length, 28)
+    ch.writeUInt16LE(0, 30)
+    ch.writeUInt16LE(0, 32)
+    ch.writeUInt16LE(0, 34)
+    ch.writeUInt16LE(0, 36)
+    ch.writeUInt32LE((0o100644 << 16) >>> 0, 38) // 普通文件 rw-r--r--
+    ch.writeUInt32LE(offset, 42)
+    centrals.push(ch, name)
+    offset += 30 + name.length + data.length
+  }
+  const cd = Buffer.concat(centrals)
+  const end = Buffer.alloc(22)
+  end.writeUInt32LE(0x06054b50, 0)
+  end.writeUInt16LE(files.length, 8)
+  end.writeUInt16LE(files.length, 10)
+  end.writeUInt32LE(cd.length, 12)
+  end.writeUInt32LE(offset, 16)
+  return Buffer.concat([...locals, cd, end])
+}
+
+export const ZIP_LIMITS = { files: 200, file: 4 * 1024 * 1024, total: 12 * 1024 * 1024, zip: 8 * 1024 * 1024 }
+
+class ZipError extends Error {
+  constructor(code, x = '') {
+    super(`${code}${x ? ': ' + x : ''}`)
+    this.code = code
+    this.x = x
+  }
+}
+
+/** Mac / Windows 打包时顺手塞进去的东西：不算设计文件，直接跳过 */
+const JUNK = /(^|\/)(__MACOSX|\.DS_Store|Thumbs\.db|desktop\.ini)(\/|$)|(^|\/)\._/i
+
+/** zip 里的路径 → 干净的相对路径；不安全给 null */
+function safeName(raw) {
+  if (/[\x00-\x1f\x7f\\]/.test(raw)) return null
+  if (raw.startsWith('/') || /^[A-Za-z]:/.test(raw)) return null
+  const parts = raw.split('/').filter((p) => p !== '' && p !== '.')
+  if (!parts.length || parts.some((p) => p === '..')) return null
+  return parts.join('/')
+}
+
+/**
+ * zip 的 Buffer → { files: [{ path, data }], skipped: [路径] }；不安全 / 坏的抛 ZipError（code：bad / big / count / link / crypt / method / zip64 / path / dup）
+ * 包外面套了一层同名文件夹（「晨光咖啡/home.html」）的，自动去掉这一层
+ */
+export function readZip(buf, limits = ZIP_LIMITS) {
+  if (!Buffer.isBuffer(buf) || buf.length < 22) throw new ZipError('bad')
+  if (buf.length > limits.zip) throw new ZipError('big')
+  // 找中央目录结尾（最后 64KB + 22 字节内）
+  let eocd = -1
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 0xffff); i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) { eocd = i; break }
+  }
+  if (eocd < 0) throw new ZipError('bad')
+  const disk = buf.readUInt16LE(eocd + 4)
+  const cdDisk = buf.readUInt16LE(eocd + 6)
+  const count = buf.readUInt16LE(eocd + 10)
+  const cdSize = buf.readUInt32LE(eocd + 12)
+  const cdOff = buf.readUInt32LE(eocd + 16)
+  if (disk !== 0 || cdDisk !== 0) throw new ZipError('bad', 'multi-disk')
+  if (count === 0xffff || cdOff === 0xffffffff || cdSize === 0xffffffff) throw new ZipError('zip64')
+  if (cdOff + cdSize > eocd) throw new ZipError('bad')
+  if (count > limits.files * 2) throw new ZipError('count')
+
+  const entries = []
+  let p = cdOff
+  for (let n = 0; n < count; n++) {
+    if (p + 46 > eocd || buf.readUInt32LE(p) !== 0x02014b50) throw new ZipError('bad')
+    const flags = buf.readUInt16LE(p + 8)
+    const method = buf.readUInt16LE(p + 10)
+    const crc = buf.readUInt32LE(p + 16)
+    const csize = buf.readUInt32LE(p + 20)
+    const usize = buf.readUInt32LE(p + 24)
+    const nlen = buf.readUInt16LE(p + 28)
+    const xlen = buf.readUInt16LE(p + 30)
+    const clen = buf.readUInt16LE(p + 32)
+    const made = buf.readUInt16LE(p + 4) >> 8
+    const ext = buf.readUInt32LE(p + 38)
+    const loff = buf.readUInt32LE(p + 42)
+    if (p + 46 + nlen > eocd) throw new ZipError('bad')
+    const nameBuf = buf.subarray(p + 46, p + 46 + nlen)
+    // 文件名：标了 UTF-8 的按 UTF-8；没标的也先按 UTF-8 认（Mac 自带的压缩就是这样），认不出来按 latin1 当乱码路径，后面会被拒
+    const name = new TextDecoder('utf-8', { fatal: false }).decode(nameBuf)
+    p += 46 + nlen + xlen + clen
+    const isDir = name.endsWith('/')
+    if (JUNK.test(name)) continue
+    if (isDir) continue
+    if (flags & 1) throw new ZipError('crypt', name)
+    if (made === 3) {
+      const mode = (ext >>> 16) & 0o170000
+      if (mode === 0o120000) throw new ZipError('link', name) // 软链接
+      if (mode && mode !== 0o100000) throw new ZipError('link', name) // 设备文件、管道之类
+    }
+    if (csize === 0xffffffff || usize === 0xffffffff || loff === 0xffffffff) throw new ZipError('zip64')
+    if (method !== 0 && method !== 8) throw new ZipError('method', name)
+    const clean = safeName(name)
+    if (!clean) throw new ZipError('path', name)
+    if (usize > limits.file) throw new ZipError('big', clean)
+    entries.push({ name: clean, method, crc, csize, usize, loff, flags })
+  }
+  if (entries.length > limits.files) throw new ZipError('count')
+
+  const files = []
+  const seen = new Set()
+  let total = 0
+  for (const e of entries) {
+    if (e.loff + 30 > buf.length || buf.readUInt32LE(e.loff) !== 0x04034b50) throw new ZipError('bad', e.name)
+    const start = e.loff + 30 + buf.readUInt16LE(e.loff + 26) + buf.readUInt16LE(e.loff + 28)
+    if (start + e.csize > buf.length) throw new ZipError('bad', e.name)
+    const raw = buf.subarray(start, start + e.csize)
+    let data
+    if (e.method === 0) {
+      data = Buffer.from(raw)
+    } else {
+      try {
+        // 以实际解出来的为准：超过单个上限就停（maxOutputLength 超了会抛）
+        data = zlib.inflateRawSync(raw, { maxOutputLength: limits.file })
+      } catch {
+        throw new ZipError('big', e.name)
+      }
+    }
+    if (data.length !== e.usize || crc32(data) !== e.crc) throw new ZipError('bad', e.name)
+    total += data.length
+    if (total > limits.total) throw new ZipError('big')
+    const key = e.name.toLowerCase()
+    if (seen.has(key)) throw new ZipError('dup', e.name)
+    seen.add(key)
+    files.push({ path: e.name, data })
+  }
+  // 外面套了一层文件夹：所有文件都在同一个顶层目录里 → 去掉这一层
+  const tops = new Set(files.map((f) => (f.path.includes('/') ? f.path.split('/')[0] : '')))
+  let wrapper = ''
+  if (files.length && tops.size === 1 && !tops.has('')) {
+    wrapper = [...tops][0]
+    for (const f of files) f.path = f.path.slice(wrapper.length + 1)
+  }
+  return { files, wrapper }
+}
+
+export { ZipError }

package/lib/handoff.js

@@ -27,9 +27,15 @@ export const FRAMEWORKS = {
   vue: { label: 'Vue 3 + Vite（TypeScript）', create: 'npm create vite@latest {name} -- --template vue-ts', router: 'vue-router' },
   next: { label: 'Next.js（App Router，TypeScript）', create: 'npx create-next-app@latest {name} --ts --app --use-npm', router: '' },
   html: { label: '纯 HTML / CSS（不用框架）', create: '', router: '' },
+  // 小程序：uni-app 一份代码出微信小程序和网页版（网页版能用 compare_design 比）；原生写 WXML / WXSS（没有脚手架命令，手搭骨架）
+  uniapp: { label: 'uni-app（Vue 3 + Vite，TypeScript；出微信小程序和网页版）', create: 'npx degit dcloudio/uni-preset-vue#vite-ts {name}', router: '' },
+  weapp: { label: '微信原生小程序（WXML / WXSS）', create: '', router: '' },
 }
 
-const FW_DEPS = [['next', 'next', 'Next.js'], ['nuxt', 'vue', 'Nuxt'], ['@sveltejs/kit', 'svelte', 'SvelteKit'], ['svelte', 'svelte', 'Svelte'], ['astro', 'astro', 'Astro'], ['@angular/core', 'angular', 'Angular'], ['solid-js', 'solid', 'Solid'], ['@builder.io/qwik', 'qwik', 'Qwik'], ['ember-source', 'ember', 'Ember'], ['preact', 'preact', 'Preact'], ['lit', 'lit', 'Lit'], ['vue', 'vue', 'Vue'], ['react-native', 'react-native', 'React Native'], ['react', 'react', 'React']]
+/** 做成小程序的写法（交接说明按小程序的规矩写：rpx、page 上的变量、view / text、pages.json / app.json 登记页面） */
+const MINI = new Set(['uniapp', 'weapp', 'taro'])
+
+const FW_DEPS = [['@dcloudio/uni-app', 'uniapp', 'uni-app'], ['@tarojs/taro', 'taro', 'Taro'], ['next', 'next', 'Next.js'], ['nuxt', 'vue', 'Nuxt'], ['@sveltejs/kit', 'svelte', 'SvelteKit'], ['svelte', 'svelte', 'Svelte'], ['astro', 'astro', 'Astro'], ['@angular/core', 'angular', 'Angular'], ['solid-js', 'solid', 'Solid'], ['@builder.io/qwik', 'qwik', 'Qwik'], ['ember-source', 'ember', 'Ember'], ['preact', 'preact', 'Preact'], ['lit', 'lit', 'Lit'], ['vue', 'vue', 'Vue'], ['react-native', 'react-native', 'React Native'], ['react', 'react', 'React']]
 
 // 文件夹里只有这些就算空的
 const JUNK = /^\.(DS_Store|git|gitignore)$|^(Thumbs\.db|desktop\.ini)$/i
@@ -65,22 +71,66 @@ function monoRoot(dir, pkg) {
   return !!m && listsOthers([...m[1].matchAll(/['"]?([^'"\s,[\]-][^'"\s,[\]]*)['"]?/g)].map((x) => x[1]))
 }
 
+/** 读 JSON 对象：读不了、写坏了、不是对象都返回 null */
+function readObj(file) {
+  try { const o = JSON.parse(readText(file)); return o && typeof o === 'object' && !Array.isArray(o) ? o : null } catch { return null }
+}
+
+/**
+ * 没有 package.json 也认得出的小程序项目：
+ * HBuilderX 建的 uni-app（根目录有 manifest.json 和写了 pages 的 pages.json；manifest.json 里 vueVersion 是 3 就是 Vue 3，没写是 Vue 2）、
+ * 微信原生小程序（project.config.json，miniprogramRoot 指的目录（默认根目录）里有 app.json）
+ */
+/** Taro 的源码目录：config/index 里写死的 sourceRoot（只认项目里面的相对目录），没写或认不出就是默认的 src/ */
+function taroRoot(dir) {
+  for (const f of ['index.ts', 'index.js', 'index.mjs', 'index.cjs']) {
+    const m = /\bsourceRoot\s*:\s*(['"`])([^'"`$\n]+)\1/.exec(readText(path.join(dir, 'config', f)) || '')
+    if (!m) continue
+    const r = m[2].trim().replace(/\\/g, '/').replace(/^(\.\/)+|\/+$/g, '')
+    return r && r !== '.' && !/(^|\/)\.\.(\/|$)|^\/|^[a-z]:/i.test(r) ? r + '/' : 'src/'
+  }
+  return 'src/'
+}
+
+function miniOf(dir) {
+  if (!dir) return null
+  const pages = readText(path.join(dir, 'pages.json'))
+  if (pages !== null && /"pages"\s*:/.test(pages) && fs.existsSync(path.join(dir, 'manifest.json'))) {
+    const v3 = /"vueVersion"\s*:\s*"?3/.test(readText(path.join(dir, 'manifest.json')) || '')
+    return { framework: 'uniapp', label: `uni-app（HBuilderX，Vue ${v3 ? 3 : 2}）`, hbx: true, pagesAt: '' }
+  }
+  const cfg = readObj(path.join(dir, 'project.config.json'))
+  if (!cfg) return null
+  // miniprogramRoot 只认项目里面的相对目录（'miniprogram/'），别的当根目录
+  const sub = typeof cfg.miniprogramRoot === 'string' && !/(^|[\\/])\.\.([\\/]|$)|^[\\/]|^[a-z]:/i.test(cfg.miniprogramRoot) ? cfg.miniprogramRoot.replace(/\\/g, '/').replace(/^(\.\/)+|\/+$/g, '') : ''
+  if (fs.existsSync(path.join(dir, sub, 'app.json'))) return { framework: 'weapp', label: '微信原生小程序', hbx: false, pagesAt: sub ? sub + '/' : '' }
+  if (sub && fs.existsSync(path.join(dir, 'app.json'))) return { framework: 'weapp', label: '微信原生小程序', hbx: false, pagesAt: '' }
+  return null
+}
+
 /**
  * 目录是不是个项目、用的什么：{ dir, pkg, site（有 index.html 入口）, empty（不存在或没正经东西）, mono（像 monorepo 根目录）, name, framework, label, tailwind, ts, pm }
  * 后端、monorepo 根目录、只用 CDN 的纯 HTML 站点也都算项目：是不是前端、页面该放进哪个子包，交接说明里让写代码的模型看清结构自己定（猜不准）
  */
 export function detectProject(dir) {
-  const out = { dir, pkg: false, site: false, empty: true, mono: false, name: path.basename(dir || ''), framework: '', label: '', tailwind: false, ts: false, pm: 'npm' }
+  const out = { dir, pkg: false, site: false, empty: true, mono: false, name: path.basename(dir || ''), framework: '', label: '', tailwind: false, ts: false, pm: 'npm', hbx: false, pagesAt: '' }
   out.site = !!dir && HTML_ENTRIES.some((f) => fs.existsSync(path.join(dir, f)))
   out.empty = !dir || !hasStuff(dir)
-  let pkg = null
-  try { pkg = dir ? JSON.parse(readText(path.join(dir, 'package.json'))) : null } catch { /* 没有或写坏了 */ }
-  if (!pkg || typeof pkg !== 'object' || Array.isArray(pkg)) return out
+  const mini = miniOf(dir)
+  const pkg = dir ? readObj(path.join(dir, 'package.json')) : null
+  if (!pkg) {
+    if (mini) Object.assign(out, mini, { ts: fs.existsSync(path.join(dir, 'tsconfig.json')) })
+    return out
+  }
   out.pkg = true
   if (typeof pkg.name === 'string' && pkg.name) out.name = pkg.name
   const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) }
   const hit = FW_DEPS.find(([d]) => deps[d])
-  if (hit) { out.framework = hit[1]; out.label = hit[2] + (hit[0] === 'react' && deps.vite ? ' + Vite' : hit[0] === 'vue' && deps.vite ? ' + Vite' : '') }
+  // HBuilderX 项目、原生小程序也常有 package.json（装 uView、Vant Weapp 这些）：没写 uni-app / Taro 的依赖就按目录结构认
+  if (mini && !(hit && MINI.has(hit[1]))) Object.assign(out, mini)
+  else if (hit && hit[1] === 'uniapp') Object.assign(out, { framework: 'uniapp', label: `uni-app（Vue ${/^\D*2\./.test(String(deps.vue || '')) ? 2 : 3}）`, pagesAt: fs.existsSync(path.join(dir, 'src', 'pages.json')) ? 'src/' : '' })
+  else if (hit && hit[1] === 'taro') Object.assign(out, { framework: 'taro', label: 'Taro', pagesAt: taroRoot(dir) })
+  else if (hit) { out.framework = hit[1]; out.label = hit[2] + (hit[0] === 'react' && deps.vite ? ' + Vite' : hit[0] === 'vue' && deps.vite ? ' + Vite' : '') }
   out.tailwind = !!deps.tailwindcss
   out.mono = monoRoot(dir, pkg)
   out.ts = !!deps.typescript || fs.existsSync(path.join(dir, 'tsconfig.json'))
@@ -88,14 +138,22 @@ export function detectProject(dir) {
   return out
 }
 
-/** 是个项目（不用往里面再套一层）：有 package.json、index.html 入口或 .git（后端、monorepo 根目录、刚建只有 README 的仓库都算） */
+/** 是个项目（不用往里面再套一层）：有 package.json、index.html 入口、.git，或是认得出的小程序（后端、monorepo 根目录、刚建只有 README 的仓库都算） */
 function isProject(dir) {
-  return ['package.json', '.git', ...HTML_ENTRIES].some((f) => fs.existsSync(path.join(dir, f)))
+  return ['package.json', '.git', ...HTML_ENTRIES].some((f) => fs.existsSync(path.join(dir, f))) || !!miniOf(dir)
 }
 
-/** 不指定框架时用什么：认得出的项目就跟它一样，纯 HTML 站点（没有 package.json）就纯 HTML，别的用 React（右侧栏和 handoff_design 都按这个） */
-export function defaultFramework(project) {
-  return project && project.pkg && project.framework ? 'same' : project && project.site && !project.pkg ? 'html' : 'react'
+/** 认得出的现有项目：有 package.json，或者是没有 package.json 的小程序（HBuilderX 的 uni-app、微信原生） */
+export const isCode = (p) => !!(p && (p.pkg || p.framework))
+
+/**
+ * 不指定框架时用什么：认得出框架的项目就跟它一样，纯 HTML 站点（没有 package.json）就纯 HTML，
+ * 别的：小程序的设计用 uni-app（能出微信小程序，网页版还能逐像素比），其余用 React（右侧栏和 handoff_design 都按这个）
+ */
+export function defaultFramework(project, kind = '') {
+  if (project && project.framework) return 'same'
+  if (project && project.site && !project.pkg) return 'html'
+  return kind === 'miniprogram' ? 'uniapp' : 'react'
 }
 
 /** 真实路径：不存在的部分接在最近一级存在的上级目录的真实路径后面（新建的目录也能按真实位置比） */
@@ -129,23 +187,23 @@ export function within(p, root) {
  */
 export function projectFor(dest) {
   const own = detectProject(dest)
-  if (own.pkg || !fs.existsSync(dest)) return own
+  if (isCode(own) || !fs.existsSync(dest)) return own
   const home = fold(realish(os.homedir()))
   for (let cur = path.dirname(realish(dest)); fold(cur) !== home && path.dirname(cur) !== cur; cur = path.dirname(cur)) {
-    if (!fs.existsSync(path.join(cur, 'package.json'))) continue
+    if (!fs.existsSync(path.join(cur, 'package.json')) && !miniOf(cur)) continue
     const p = detectProject(cur)
-    if (p.pkg) return own.site && !p.framework ? own : p
+    if (isCode(p)) return own.site && !p.framework ? own : p
   }
   return own
 }
 
 /**
- * 代码默认放哪：会话目录是个项目（有 package.json）、又不在设计目录里 → 就放会话目录；
+ * 代码默认放哪：会话目录是个项目（有 package.json，或是认得出的小程序）、又不在设计目录里 → 就放会话目录；
  * 否则新建 <设计名>-app：设计目录在会话目录下就建在会话目录里，不然建在设计目录旁边（别塞进设计目录）
  */
 export function defaultDest(root, cwd, project) {
   const inside = !!root && within(cwd, root)
-  if (project && project.pkg && !inside) return cwd
+  if (isCode(project) && !inside) return cwd
   const under = !!root && !inside && within(root, cwd)
   return path.join(root && !under ? path.dirname(root) : cwd, appDirName(root))
 }
@@ -168,7 +226,7 @@ export function pickedDest(dir, root) {
   const beside = { dest: path.join(path.dirname(root || dir), name), why: 'beside' }
   if (root && within(dir, root)) return beside
   let out = { dest: dir, why: '' }
-  if (!isProject(dir) && !projectFor(dir).pkg && path.basename(dir).toLowerCase() !== name) {
+  if (!isProject(dir) && !isCode(projectFor(dir)) && path.basename(dir).toLowerCase() !== name) {
     if (hasStuff(dir)) out = { dest: path.join(dir, name), why: 'nested' } // 还不存在 / 读不了 / 空的：就用它
   }
   return root && within(out.dest, root) ? beside : out
@@ -180,6 +238,13 @@ export function routeOf(key) {
   return b === 'index' || b === 'home' ? '/' : '/' + b.replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '')
 }
 
+/** 文件名 → 小程序的页面路径（登记进 pages.json / app.json 的，相对它们所在的目录）：index / home → pages/index/index，别的 pages/名字/名字（Taro 是 pages/名字/index） */
+export function pagePathOf(key, target = 'uniapp') {
+  const r = routeOf(key)
+  const b = r === '/' ? 'index' : r.slice(1) || 'page'
+  return `pages/${b}/${target === 'taro' ? 'index' : b}`
+}
+
 const CLASS_TAGS = /^(header|nav|footer|aside|section|div|a|button|ul|ol|li|form|article|main|figure)$/
 
 /** 几屏共用的 class（≥ 2 屏都有，多半该抽成组件）：[{ cls, n, screens }] */
@@ -278,7 +343,23 @@ export function handoffMd({ root, rows, kind, size, framework, dest, project, sy
   const fwLabel = same ? `${project.label}（跟项目一样）` : fw ? fw.label : framework
   const name = path.basename(root)
   const keys = rows.map((r) => r.key)
-  const route = (k) => routeOf(k)
+  // 做成什么：跟项目一样就是项目的框架；小程序的写法（uni-app / 原生 / Taro）按小程序的规矩写
+  const target = framework === 'same' ? (project && project.framework) || '' : framework
+  const uni = target === 'uniapp'
+  const wx = target === 'weapp'
+  const taro = target === 'taro'
+  const mini = MINI.has(target)
+  const known = isCode(project)
+  // 目标目录本来就是这种小程序项目（往里加页面，不新建）
+  const hasMini = mini && !!project && project.framework === target
+  // 目标目录是别的前端项目（React / Vue 网页、别种小程序）：不往里硬加，在里面另建子项目
+  const mismatch = mini && known && !hasMini && !!project.framework
+  // 页面、pages.json 在哪个目录：现有项目照它（命令行建的 uni-app、Taro 在 src/）；新建的 uni-app 模板也在 src/
+  // Taro 照项目 config/index 的 sourceRoot（默认 src/）
+  const at = hasMini ? project.pagesAt || (taro ? 'src/' : '') : uni ? 'src/' : ''
+  const cfgFile = uni ? `${at}pages.json` : wx ? `${at}app.json` : `${at}app.config`
+  const api = uni ? 'uni' : taro ? 'Taro' : 'wx'
+  const route = (k) => (mini ? pagePathOf(k, target) : routeOf(k))
   const keyOfLink = (p) => String(p || '').replace(/^\/+/, '').split(/[?#]/)[0]
   const lines = []
   lines.push(`# 交接：${name} → ${fwLabel}`, '')
@@ -287,20 +368,60 @@ export function handoffMd({ root, rows, kind, size, framework, dest, project, sy
   lines.push(`- 设计目录：\`${root}\`（${rows.length} 屏${more ? `，另有 ${more} 屏没列进来` : ''}，${kind} ${size[0]}×${size[1]}）`)
   // 目录里已经有别的东西、又不是 Node 项目（别的语言的仓库、后端……）：别在原地或旁边跑脚手架
   // （纯 HTML 站点再做成纯 HTML 不算：就加在这个站点里，下面第 1 步提醒别覆盖现有页面）
-  const occupied = !!(project && !project.pkg && project.empty === false) && !(project.site && framework === 'html')
-  if (project && project.pkg) lines.push(`- 做到：\`${dest || project.dir}\`（现有项目 ${project.name}：${project.label || '没认出框架'}${project.tailwind ? ' + Tailwind' : ''}${project.ts ? '，TypeScript' : ''}，包管理 ${project.pm}）`)
+  const occupied = !!(project && !known && project.empty === false) && !(project.site && framework === 'html')
+  if (known) lines.push(`- 做到：\`${dest || project.dir}\`（现有项目 ${project.name}：${project.label || '没认出框架'}${project.tailwind ? ' + Tailwind' : ''}${project.ts ? '，TypeScript' : ''}${project.pkg ? `，包管理 ${project.pm}` : '，没有 package.json'}）`)
   else if (occupied) lines.push(`- 做到：\`${dest}\`（目录里已经有别的东西，不是 Node 项目：先看清结构，前端放进它里面新的子目录）`)
   else if (fw && fw.create) lines.push(`- 做到：\`${dest}\`（新建项目：\`${fw.create.replace('{name}', path.basename(dest || name + '-app'))}\`，在 \`${path.dirname(dest || root)}\` 里跑）`)
   else lines.push(`- 做到：\`${dest}\``)
   lines.push(`- 框架：${fwLabel}`)
   if (system) lines.push(`- 设计系统：${system}（设计用的是它的 tokens.css / components.css，项目里也照它）`)
   lines.push(`- 生成时间：${now.toISOString().slice(0, 16).replace('T', ' ')}`, '')
-  if (kind === 'miniprogram') {
+  if (kind === 'miniprogram' && !mini) {
+    // 小程序的设计、选的是网页框架：做成手机网页，别混进小程序的写法
+    lines.push('## 小程序设计做成网页（H5）', '')
+    lines.push(`- 这是微信小程序的设计（${size[0]} 宽）。框架选的「${fwLabel}」，就做成手机网页：样式照设计稿写 px（宽 ${size[0]} 的移动端页面，带 \`<meta name="viewport" content="width=device-width, initial-scale=1">\`），不用 rpx、不用 \`wx.*\`。用户其实要真小程序的话，用 handoff_design 的 framework: uniapp（uni-app）或 weapp（原生）重新出交接说明。`)
+    lines.push('- 设计稿顶上画的状态栏、右上角的胶囊是微信自己画的，网页里不做；导航栏做成页面自己的顶栏。底部标签栏做成固定在底部的导航，留出安全区 `env(safe-area-inset-bottom)`。', '')
+  }
+  if (mini) {
+    const cfg = uni ? `${cfgFile} 的 \`globalStyle\` / 页面的 \`style\`` : taro ? `\`${cfgFile}\` / 页面的 \`.config\`` : `${cfgFile} / 页面 json`
     lines.push('## 小程序要点', '')
-    lines.push(`- 这是微信小程序的设计（${size[0]} 宽）。要做成真小程序：原生写 WXML / WXSS，或用 Taro、uni-app；框架选的「${fwLabel}」是做成网页的写法，用户要的是哪种先问清。`)
-    lines.push(`- 尺寸换成 rpx：设计稿 1px = ${Math.round((750 / size[0]) * 100) / 100}rpx（整屏宽 750rpx）。`)
-    lines.push('- 设计稿顶上画的状态栏不用做，微信自带；右上角的胶囊也是微信画的。导航栏用 app.json / 页面 json 的默认导航栏，或 `navigationStyle: custom` 自己画——自己画时状态栏高用 `wx.getWindowInfo().statusBarHeight`、导航栏高度和右边让开的宽度按 `wx.getMenuButtonBoundingClientRect()` 算（设计稿的 44 / 88 / 101px 只是预览手机的）。顶栏是深色的（预览里胶囊是白的），页面配置写 `navigationBarTextStyle: white`。')
-    lines.push('- 底部标签栏写进 app.json 的 `tabBar`（样式特殊就用自定义 tabBar），底部留出安全区 `env(safe-area-inset-bottom)`。', '')
+    lines.push(taro
+      ? `- 尺寸：Taro 会自己把样式里的 px 换成 rpx，按 \`config/index\` 的 \`designWidth\` 算（默认 750）。别改项目的 designWidth（旧页面会跟着变大变小）：照它换算——designWidth 是 750 时设计稿 1px 写 ${Math.round((750 / size[0]) * 100) / 100}px，是 ${size[0]} 就照设计稿写。`
+      : `- 尺寸换成 rpx：设计稿 1px = ${Math.round((750 / size[0]) * 100) / 100}rpx（整屏宽 750rpx）。`)
+    if (kind === 'miniprogram') {
+      // 胶囊位置只有小程序里拿得到；uni-app、Taro 的网页版（拿来逐像素比的）要分开写
+      const h5Nav = uni ? '（`getMenuButtonBoundingClientRect` 网页版没有：包在 `// #ifdef MP-WEIXIN` … `// #endif` 里，网页版走 `// #ifdef H5`，顶栏高按 44px、状态栏按 0）'
+        : taro ? '（`getMenuButtonBoundingClientRect` 网页版拿不到：用 `process.env.TARO_ENV === \'weapp\'` 分开，网页版顶栏高按 44px、状态栏按 0）' : ''
+      lines.push(`- 设计稿顶上画的状态栏不用做，微信自带；右上角的胶囊也是微信画的。导航栏用 ${cfg} 里的默认导航栏，或 \`navigationStyle: custom\` 自己画——自己画时状态栏高用 \`${api}.getWindowInfo().statusBarHeight\`、导航栏高度和右边让开的宽度按 \`${api}.getMenuButtonBoundingClientRect()\` 算（设计稿的 44 / 88 / 101px 只是预览手机的）${h5Nav}。顶栏是深色的（预览里胶囊是白的），页面配置写 \`navigationBarTextStyle: white\`。`)
+      lines.push(`- 底部标签栏写进 \`${cfgFile}\` 的 \`tabBar\`（样式特殊就用自定义 tabBar），底部留出安全区 \`env(safe-area-inset-bottom)\`。`)
+    }
+    if (mismatch) lines.push(`- 目标目录 \`${dest || project.dir}\` 是 ${project.label} 项目，不是 ${fwLabel}：按下面第 1 步在里面另建一个子项目，下面说的路径都相对那个子项目。`)
+    lines.push('')
+  }
+  if (uni) {
+    lines.push('## 做成 uni-app', '')
+    lines.push(`- 页面：每屏一个 \`${at}pages/<名字>/<名字>.vue\`，在 \`${cfgFile}\` 的 \`pages\` 里登记（第一项是首页），标题、导航栏颜色写在那一页的 \`style\` 里。下面表里的「页面路径」就是要登记的 path。`)
+    lines.push('- 标签换成 uni-app 的组件：`div` → `view`，文字 → `text`，`img` → `image`（照设计的裁切写 `mode`，比如 `aspectFill`），输入框、按钮用同名组件；点击写 `@tap`；跳转用 `uni.navigateTo`（标签页 `uni.switchTab`），别用 `<a>` 和 vue-router。')
+    lines.push('- 设计变量放进 `App.vue` 的全局样式，选择器写 `page`（小程序里没有 `:root`，网页版也认 `page`）：`page { --color-primary: …; }`，各处用 `var(--…)`。')
+    lines.push('- 别用 `window`、`document`、`localStorage`、`fetch`：换成 `uni.getStorageSync`、`uni.request` 这些。')
+    if (hasMini) lines.push(`- 先看清项目现有的写法再动手：Vue ${/Vue 2/.test(project.label) ? '2（选项式）' : '3（`<script setup>` 还是选项式）'}、用没用 uni-ui / uView 这些组件库、\`uni.scss\` 里有没有现成的变量，照它来。`)
+    if (hasMini && project.hbx) lines.push(project.pkg ? '- 这是 HBuilderX 建的项目：别跑 npm 脚手架；要的依赖照现有 package.json 装，跑起来让用户在 HBuilderX 里点「运行」。' : '- 这是 HBuilderX 建的项目（没有 package.json）：别跑 npm 脚手架、别装依赖；跑起来让用户在 HBuilderX 里点「运行」。')
+    lines.push('')
+  }
+  if (wx) {
+    lines.push('## 做成原生小程序', '')
+    lines.push(`- 页面：每屏一个目录 \`${at}pages/<名字>/\`，四个文件 \`<名字>.wxml / .wxss / .js / .json\`，在 \`${cfgFile}\` 的 \`pages\` 里登记（第一项是首页）；公共样式写 \`${at}app.wxss\`。下面表里的「页面路径」就是要登记的。`)
+    if (!hasMini) lines.push('- 这里还没有小程序：先手搭最小骨架——`app.json`、`app.js`（`App({})`）、`app.wxss`、`sitemap.json`，`project.config.json` 里写 `"compileType": "miniprogram"`、`appid` 用户有就填，没有先写 `touristappid`（游客模式）。别找 npm 脚手架。')
+    lines.push('- HTML 换成 WXML：`div` → `view`，文字 → `text`，`img` → `image`（照设计的裁切写 `mode`），点击 `bindtap`，列表 `wx:for`，条件 `wx:if`；跳转 `wx.navigateTo`（标签页 `wx.switchTab`）；页面数据放 `Page({ data })`，用 `this.setData` 改。设计稿里的脚本照这个改写。')
+    lines.push(`- 设计变量写在 \`${at}app.wxss\` 的 \`page { … }\` 上（WXSS 没有 \`:root\`），各页用 \`var(--…)\`。`)
+    lines.push('- WXSS 只用常见的选择器（class、id、标签、后代 / 子代、`::before` / `::after`）；`*` 通配、属性选择器、`:hover` 别用——按下的样式用组件的 `hover-class`。')
+    lines.push('')
+  }
+  if (taro) {
+    lines.push('## 做成 Taro', '')
+    lines.push(`- 源码目录是 \`${at}\`（项目 \`config/index\` 里的 \`sourceRoot\`${at === 'src/' ? '，默认 src；那里写的不是 src 就照它' : ''}）。页面放 \`${at}pages/<名字>/index\`（\`.tsx\` 还是 \`.vue\` 看项目用 React 还是 Vue），在 \`${cfgFile}\`（\`.ts\` 或 \`.js\`，看项目）的 \`pages\` 里登记；组件用 \`@tarojs/components\` 的 \`View\`、\`Text\`、\`Image\`；跳转 \`Taro.navigateTo\`（标签页 \`Taro.switchTab\`）。`)
+    lines.push(`- 设计变量写在 \`${at}app\` 的全局样式里，选择器写 \`page, .taro_page { … }\`：小程序认 \`page\`（没有 \`:root\`），网页版的页面容器是 \`.taro_page\`（\`page\` 在网页版不生效）；各处用 \`var(--…)\`。先看清项目现有的写法、组件库（Taro UI、NutUI 之类）再动手。`)
+    lines.push('')
   }
 
   if (kind === 'desktop') {
@@ -310,7 +431,7 @@ export function handoffMd({ root, rows, kind, size, framework, dest, project, sy
     lines.push('- 整个窗口不滚，侧栏、列表、详情各自滚（`overflow: auto`）；最小窗口尺寸照设计里最小的那种（多尺寸里的 1024×680）设。', '')
   }
 
-  lines.push('## 屏幕和路由', '', '| 屏 | 设计文件 | 建议路由 | 截图（handoff/shots/） | 跳到 |', '| --- | --- | --- | --- | --- |')
+  lines.push(mini ? '## 屏幕和页面' : '## 屏幕和路由', '', `| 屏 | 设计文件 | ${mini ? '页面路径' : '建议路由'} | 截图（handoff/shots/） | 跳到 |`, '| --- | --- | --- | --- | --- |')
   for (const r of rows) {
     const to = [...new Set((r.links || []).map((l) => keyOfLink(l.path)).filter((k) => k && k !== r.key))]
     const shots = r.error ? `没截成（${r.error}）` : [...r.shots, r.mobile].filter(Boolean).join('、') + (r.more ? `（还有 ${r.more} 段没截）` : '')
@@ -327,7 +448,9 @@ export function handoffMd({ root, rows, kind, size, framework, dest, project, sy
   if (tn.length) {
     const colors = tn.filter((n) => /^--colou?r-/.test(n))
     lines.push(`\`tokens.css\` 里 ${tn.length} 个变量（颜色 ${colors.length} 个：${colors.slice(0, 10).map((n) => `\`${n}: ${tok[n]}\``).join('、')}${colors.length > 10 ? ' …' : ''}）。`, '')
-    lines.push(project && project.tailwind
+    lines.push(mini
+      ? `- 把 tokens.css 里的变量搬进${uni ? ' `App.vue` 全局样式' : wx ? ` \`${at}app.wxss\`` : '全局样式'}的 \`${taro ? 'page, .taro_page' : 'page'} { … }\`（小程序没有 \`:root\`）；组件样式里一律用 \`var(--…)\`，别写死色值、字号。`
+      : project && project.tailwind
       ? '- 把 tokens.css 原样放进项目的全局样式并在入口引入；Tailwind 的 theme.extend 里把颜色、圆角、字号、阴影映射到这些变量（如 `primary: \'var(--color-primary)\'`），类名里别写死色值。'
       : '- 把 tokens.css 原样放进项目的全局样式（如 `src/styles/tokens.css`）并在入口引入；组件样式里一律用 `var(--…)`，别写死色值、字号。')
   } else if (hasTokens) lines.push('- `tokens.css` 的第一段 `:root` 里没读到变量：先打开看看，把各屏用到的颜色、字号收成 `:root` 上的变量再动手。')
@@ -339,12 +462,19 @@ export function handoffMd({ root, rows, kind, size, framework, dest, project, sy
   // 共用部分
   const parts = sharedParts(htmlByKey)
   lines.push('## 几屏共用的部分（做成组件）', '')
-  if (parts.length) for (const p of parts) lines.push(`- \`.${p.cls}\`：${p.n} 屏都有（${p.screens.map((k) => k.replace(/\.html?$/i, '')).join('、')}）→ \`${pascal(p.cls)}\` 组件`)
+  // 小程序设计的骨架（技能里的 .mp-status / .mp-nav / .mp-tabbar …）是在模拟微信自己画的东西：照微信的做法，别做成组件
+  const tabCfg = `\`${cfgFile}\``
+  const chrome = kind !== 'miniprogram' ? {} : mini
+    ? { 'mp-status': '预览手机的状态栏，不做（微信自带）', 'mp-top': '状态栏 + 导航栏的外壳：照上面「小程序要点」用默认导航栏，或自己画导航', 'mp-nav': '导航栏：纯色底就用默认导航栏（标题、颜色写进页面配置）；渐变、图片、搜索框这种才做自定义导航组件', 'mp-back': '返回按钮：默认导航栏自带', 'mp-tabbar': `底部标签栏：写进 ${tabCfg} 的 \`tabBar\`（样式特殊才做自定义 tabBar）` }
+    : { 'mp-status': '预览手机的状态栏，网页里不做', 'mp-top': '→ 页面顶栏组件', 'mp-tabbar': '→ 固定在底部的导航组件' }
+  if (parts.length) for (const p of parts) lines.push(chrome[p.cls] ? `- \`.${p.cls}\`：${chrome[p.cls]}` : `- \`.${p.cls}\`：${p.n} 屏都有（${p.screens.map((k) => k.replace(/\.html?$/i, '')).join('、')}）→ \`${pascal(p.cls)}\` 组件`)
   else lines.push('- 没找到几屏共用的结构；按页面拆就行。')
   if (fs.existsSync(path.join(root, 'icons.svg'))) {
     let n = 0
     try { n = (fs.readFileSync(path.join(root, 'icons.svg'), 'utf8').match(/<symbol\b/g) || []).length } catch { n = 0 }
-    lines.push(`- \`icons.svg\`：${n} 个图标（<symbol id>）→ 一个 \`Icon\` 组件按 id 取，或拆成单个 SVG 组件`)
+    lines.push(mini
+      ? `- \`icons.svg\`：${n} 个图标（<symbol id>）→ 小程序的模板里不能直接写 \`<svg>\`，本地 .svg 文件用 \`<image>\` 显示也不是每个版本都稳：导出成 PNG（3 倍图）用 \`<image>\`，或者把 SVG 写成 \`data:image/svg+xml\` 放进 \`background-image\`（要换颜色就改里面的 fill），或做成图标字体`
+      : `- \`icons.svg\`：${n} 个图标（<symbol id>）→ 一个 \`Icon\` 组件按 id 取，或拆成单个 SVG 组件`)
   }
   lines.push('')
 
@@ -385,7 +515,9 @@ export function handoffMd({ root, rows, kind, size, framework, dest, project, sy
   }
   walk(root, '', 0)
   lines.push('## 图片和字体', '')
-  lines.push(assets.length ? `- ${assets.slice(0, 30).map((a) => `\`${a}\``).join('、')}${assets.length > 30 ? ' …' : ''}：照原样复制进项目的静态资源目录（public/ 或 src/assets/）` : '- 没有单独的图片、字体文件（图形都写在 HTML / SVG 里）。', '')
+  lines.push(assets.length ? `- ${assets.slice(0, 30).map((a) => `\`${a}\``).join('、')}${assets.length > 30 ? ' …' : ''}：照原样复制进项目的静态资源目录（${mini ? (uni ? `\`${at}static/\`` : taro ? `\`${at}assets/\`` : `\`${at}images/\` 之类`) : 'public/ 或 src/assets/'}）` : '- 没有单独的图片、字体文件（图形都写在 HTML / SVG 里）。')
+  if (mini) lines.push(`- 小程序主包不能超过 2MB：大图放服务器用网址；字体文件要用 \`${api}.loadFontFace\` 从网址加载，加载不了就用系统字体。`)
+  lines.push('')
 
   // 做法
   // 在认不出前端框架的项目（后端）或 monorepo 里选了个空的新文件夹：就在这里新建前端项目，不用再看结构、另套一层
@@ -395,18 +527,40 @@ export function handoffMd({ root, rows, kind, size, framework, dest, project, sy
   const PLAIN = { react: 'React', vue: 'Vue', next: 'Next.js' }
   const fwNew = fw || (fresh && same && PLAIN[project.framework] === String(project.label || '').replace(/ \+ Vite$/, '') ? FRAMEWORKS[project.framework] : null)
   const pm = fresh && project.pm && project.pm !== 'npm' ? project.pm : ''
-  const create = (!(project && project.pkg) || fresh) && !occupied && fwNew && fwNew.create ? fwNew.create.replace('{name}', path.basename(dest || name + '-app')).replace('--use-npm', pm ? `--use-${pm}` : '--use-npm') : ''
+  const create = (!known || fresh) && !occupied && fwNew && fwNew.create ? fwNew.create.replace('{name}', path.basename(dest || name + '-app')).replace('--use-npm', pm ? `--use-${pm}` : '--use-npm') : ''
   lines.push('## 做法和验收', '')
   // 现有项目但没认出前端框架（后端、monorepo 根目录、别的语言的仓库）/ 像 monorepo 根目录：页面该放哪让模型看清结构再定，别直接往根目录塞
   const bare = !create && framework !== 'html' && framework !== 'same' && !!(project && ((project.pkg && !project.framework) || occupied))
   const sub = fw && fw.create ? fw.create.replace('{name}', 'web') : ''
   const mono = !create && !fresh && !!(project && project.mono)
   const keep = project && project.empty === false ? '；目录里已经有文件：别覆盖现有的页面，重名的先问用户' : ''
-  lines.push(`1. 搭骨架：${create ? `新建项目 \`${create}\`${fresh ? `（在 \`${path.dirname(dest)}\` 里跑）` : ''}，${pm ? `用 ${pm} ` : ''}装好依赖${fwNew.router ? `和 ${fwNew.router}` : ''}` : framework === 'html' ? `整理成一个静态站点目录（每屏一个页面，公共样式一份）${keep}` : fresh ? `在这个空文件夹里新建一个 ${fwLabel.replace('（跟项目一样）', '')} 子项目，照仓库里别的子包怎么搭的来（monorepo 记得加进 workspace）${pm ? `，用 ${pm} 装依赖` : ''}` : bare ? `这个目录里已经有东西，但没认出前端框架（可能是后端、monorepo 根目录或别的语言的仓库）：先看清它的结构和用途再定放哪——适合直接加页面就加；不适合就在里面另建一个前端（monorepo 放进 apps/ 之类的子包，别的放进新的子目录${sub ? `，比如在里面跑 \`${sub}\`` : ''}），用 ${fw ? fw.label : framework} 搭，别打乱现有代码` : `在现有项目里加页面和路由（看清它现有的目录结构、样式写法、组件库再动手）`}${mono && !bare ? '（这像是 monorepo 根目录：先看根目录和 apps/ 之类的子包里有没有现成的前端应用，有就加进去；没有再新建一个子包，别把页面散放在根目录）' : ''}；把 tokens.css${sheets.length ? '（和公共样式表）' : ''}搬进去。`)
-  lines.push('2. 一屏一个页面，路由照上面的表；先抽几屏共用的组件，再拼页面。')
-  lines.push('3. 结构、文案、数字、图标照设计稿的 HTML 搬；class 名可以改成项目的习惯，样式值（间距、字号、颜色、圆角、阴影）一律用设计变量。')
-  lines.push('4. 每做完一屏：把开发服务器跑起来，调 `compare_design`（screen 填设计文件名，url 填这一屏在开发服务器上的地址），照差异图把不一样的地方改掉，直到差异在 3% 以内，或者剩下的差别说得出理由（比如真实数据、系统字体）。')
-  lines.push('5. 全部做完：每屏再对一遍；告诉用户做了哪些页面、怎么跑起来（命令和地址）、还有哪里和设计稿不一样。')
+  const tokTail = mini ? `；tokens.css 里的变量搬进全局样式的 \`${taro ? 'page, .taro_page' : 'page'} { }\`${sheets.length ? '，公共样式表也拆进去' : ''}` : `；把 tokens.css${sheets.length ? '（和公共样式表）' : ''}搬进去`
+  const step1 = create ? `新建项目 \`${create}\`${fresh ? `（在 \`${path.dirname(dest)}\` 里跑）` : ''}，${pm ? `用 ${pm} ` : ''}装好依赖${fwNew.router ? `和 ${fwNew.router}` : ''}${uni ? '（GitHub 连不上就从 gitee 下载模板压缩包 `https://gitee.com/dcloud/uni-preset-vue/repository/archive/vite-ts.zip`，解开当项目目录）' : ''}`
+    : framework === 'html' ? `整理成一个静态站点目录（每屏一个页面，公共样式一份）${keep}`
+    : fresh ? `在这个空文件夹里新建一个 ${fwLabel.replace('（跟项目一样）', '')} 子项目，照仓库里别的子包怎么搭的来（monorepo 记得加进 workspace）${pm ? `，用 ${pm} 装依赖` : ''}`
+    : bare ? `这个目录里已经有东西，但没认出前端框架（可能是后端、monorepo 根目录或别的语言的仓库）：先看清它的结构和用途再定放哪——适合直接加页面就加；不适合就在里面另建一个前端（monorepo 放进 apps/ 之类的子包，别的放进新的子目录${sub ? `，比如在里面跑 \`${sub}\`` : wx ? '，比如 `miniprogram/`，照上面搭骨架' : ''}），用 ${fw ? fw.label : framework} 搭，别打乱现有代码`
+    : mismatch ? `这个目录是 ${project.label} 项目，不是 ${fwLabel}：别往里面硬加——在里面另建一个子目录（比如 \`${uni ? 'uni-app' : 'miniprogram'}/\`）${uni ? `，在里面跑 \`${FRAMEWORKS.uniapp.create.replace('{name}', 'uni-app')}\` 新建 uni-app 项目再装依赖` : '，照上面「做成原生小程序」搭骨架'}，现有代码别动`
+    : wx && !hasMini ? `在 \`${dest}\` 里照上面「做成原生小程序」搭好骨架${keep}`
+    : mini ? `在现有项目里加页面：放进 \`${at}pages/\`，登记进 \`${cfgFile}\`（看清它现有的目录结构、写法、组件库再动手）`
+    : '在现有项目里加页面和路由（看清它现有的目录结构、样式写法、组件库再动手）'
+  lines.push(`1. 搭骨架：${step1}${mono && !bare ? '（这像是 monorepo 根目录：先看根目录和 apps/ 之类的子包里有没有现成的前端应用，有就加进去；没有再新建一个子包，别把页面散放在根目录）' : ''}${tokTail}。`)
+  lines.push(mini
+    ? `2. 一屏一个页面，照上面的表登记页面路径；先抽几屏共用的组件（${wx ? '做成自定义组件，放 `components/`' : '放 `components/`'}），再拼页面。`
+    : '2. 一屏一个页面，路由照上面的表；先抽几屏共用的组件，再拼页面。')
+  lines.push(`3. 结构、文案、数字、图标照设计稿的 HTML 搬${mini ? `（标签换成${wx ? ' WXML ' : '小程序'}的组件）` : ''}；class 名可以改成项目的习惯，样式值（间距、字号、颜色、圆角、阴影）一律用设计变量${mini && !taro ? '，尺寸按上面换成 rpx' : ''}。`)
+  if (wx) {
+    lines.push('4. 每做完一屏：原生小程序在浏览器里跑不起来，`compare_design` 比不了——让用户用微信开发者工具「导入项目」打开这个目录（没有 AppID 就用测试号 / 游客模式）看这一屏，截图发回来，和 handoff/shots/ 里的截图对照着改。')
+    lines.push('5. 全部做完：告诉用户做了哪些页面、在微信开发者工具里导入哪个目录、还有哪里和设计稿不一样。')
+  } else if (mini) {
+    const h5 = uni && hasMini && project.hbx ? '让用户在 HBuilderX 里点「运行 → 运行到浏览器」' : '后台跑 `npm run dev:h5`'
+    // 现有的命令行项目不一定配了网页版
+    const noH5 = hasMini && !project.hbx ? `（package.json 里没有 \`dev:h5\` 就是没配网页版：先问用户要不要加；不加就请用户在微信开发者工具里看这一屏，照截图对）` : ''
+    lines.push(`4. 每做完一屏：先跑网页版（${h5}）${noH5}，调 \`compare_design\`（screen 填设计文件名，url 填这一屏在网页版上的地址，比如 \`http://localhost:5173/#/${route(rows[0] ? rows[0].key : 'index')}\`），照差异图把不一样的地方改掉，直到差异在 3% 以内，或者剩下的差别说得出理由（网页版顶上是 ${uni ? 'uni-app' : 'Taro'} 画的导航栏、没有状态栏和胶囊，这块不一样是正常的）。`)
+    lines.push(`5. 全部做完：每屏再对一遍；告诉用户做了哪些页面、网页版怎么跑起来、微信小程序怎么出（${uni && hasMini && project.hbx ? 'HBuilderX「运行 → 运行到小程序模拟器 → 微信开发者工具」' : uni ? '`npm run dev:mp-weixin`，再用微信开发者工具打开 `dist/dev/mp-weixin`' : '`npm run dev:weapp`，再用微信开发者工具打开项目目录'}）、还有哪里和设计稿不一样。`)
+  } else {
+    lines.push('4. 每做完一屏：把开发服务器跑起来，调 `compare_design`（screen 填设计文件名，url 填这一屏在开发服务器上的地址），照差异图把不一样的地方改掉，直到差异在 3% 以内，或者剩下的差别说得出理由（比如真实数据、系统字体）。')
+    lines.push('5. 全部做完：每屏再对一遍；告诉用户做了哪些页面、怎么跑起来（命令和地址）、还有哪里和设计稿不一样。')
+  }
   lines.push('', '别做：改设计（配色、文案、布局）、加设计稿里没有的功能、引入新的 UI 组件库（项目已经在用的除外）。', '')
   return lines.join('\n')
 }

package/lib/history.js

@@ -191,7 +191,7 @@ export function createHistory({ base, now = Date.now, log = () => {} }) {
    * 那一版之后新加的文件不删；落到目录外的（父目录是指到外面的软链接）不写。
    * @returns { restored: 文件数, saved: 回退前存的那一版 | null }
    */
-  function restore(root, n) {
+  function restore(root, n, { before = null } = {}) {
     const v = load(root).find((x) => x && x.n === Number(n))
     if (!v) throw new Error(`没有第 ${n} 版`)
     const objDir = path.join(dirOf(root), 'objects')
@@ -203,6 +203,8 @@ export function createHistory({ base, now = Date.now, log = () => {} }) {
       if (!buf) throw new Error(`第 ${n} 版的文件不全（${rel}），没有回退`)
       wanted.push([rel, buf])
     }
+    // 写之前先告诉调用方要退回哪些页面（sha256）：装好的别人的设计系统要先记下来，写进去的那一刻起就按别人做的预览；它出错就不回
+    if (before) before(wanted.filter(([rel]) => /\.html?$/i.test(rel)).map(([, buf]) => crypto.createHash('sha256').update(buf).digest('hex')))
     let saved
     try {
       saved = take(root, '回退前', true)