dsh-design-studio 0.9.0 → 0.11.0

package/lib/handoff.js

@@ -10,6 +10,7 @@
  */
 
 import fs from 'node:fs'
+import os from 'node:os'
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { prepare } from './look.js'
@@ -26,26 +27,135 @@ 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'], ['vue', 'vue', 'Vue'], ['react', 'react', 'React']]
+/** 做成小程序的写法（交接说明按小程序的规矩写：rpx、page 上的变量、view / text、pages.json / app.json 登记页面） */
+const MINI = new Set(['uniapp', 'weapp', 'taro'])
 
-/** 目录是不是个前端项目、用的什么：{ dir, pkg, name, framework, label, tailwind, ts, pm } */
+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
+
+/** 文件夹里有没有正经东西（不存在 / 读不了算没有） */
+function hasStuff(dir) {
+  try { return fs.readdirSync(dir).some((f) => !JUNK.test(f)) } catch { return false }
+}
+
+// 有这些就算网页入口（没有 package.json 的纯 HTML 站点也算个项目）
+const HTML_ENTRIES = ['index.html', 'src/index.html', 'public/index.html', 'app/index.html']
+
+/** workspaces 列表里有本目录以外的（只写 '.' 的不算 monorepo；'!' 开头是排除） */
+const listsOthers = (xs) => xs.some((x) => typeof x === 'string' && !/^!|^\.\/?$/.test(x.trim()))
+
+/** 读文本：去掉 BOM、换行统一成 \n（Windows 检出的文件常是 CRLF）；读不了返回 null */
+function readText(file) {
+  try { return fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n') } catch { return null }
+}
+
+/** 像是 monorepo 根目录：package.json 的 workspaces、lerna / rush / Nx 集成式（根上没有 project.json）、pnpm-workspace.yaml 的 packages 里列了别的包（只用来提醒模型放进子包，不拿来改放哪） */
+function monoRoot(dir, pkg) {
+  const ws = pkg && pkg.workspaces
+  const list = Array.isArray(ws) ? ws : ws && Array.isArray(ws.packages) ? ws.packages : null
+  if (list && listsOthers(list)) return true
+  const has = (f) => fs.existsSync(path.join(dir, f))
+  if (has('lerna.json') || has('rush.json') || (has('nx.json') && !has('project.json'))) return true
+  let y = readText(path.join(dir, 'pnpm-workspace.yaml'))
+  if (y === null) return false
+  y = y.replace(/#.*$/gm, '')
+  // packages: ['a/*', 'b'] 或者下面一行一个 - a/*
+  const m = y.match(/^packages[ \t]*:(.*(?:\n(?:[ \t]+.*|-.*|[ \t]*))*)/m)
+  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, name: path.basename(dir || ''), framework: '', label: '', tailwind: false, ts: false, pm: 'npm' }
-  let pkg
-  try { pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')) } catch { return out }
+  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)
+  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'))
   out.pm = fs.existsSync(path.join(dir, 'pnpm-lock.yaml')) ? 'pnpm' : fs.existsSync(path.join(dir, 'yarn.lock')) ? 'yarn' : fs.existsSync(path.join(dir, 'bun.lockb')) || fs.existsSync(path.join(dir, 'bun.lock')) ? 'bun' : 'npm'
   return out
 }
 
+/** 是个项目（不用往里面再套一层）：有 package.json、index.html 入口、.git，或是认得出的小程序（后端、monorepo 根目录、刚建只有 README 的仓库都算） */
+function isProject(dir) {
+  return ['package.json', '.git', ...HTML_ENTRIES].some((f) => fs.existsSync(path.join(dir, f))) || !!miniOf(dir)
+}
+
+/** 认得出的现有项目：有 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'
+}
+
 /** 真实路径：不存在的部分接在最近一级存在的上级目录的真实路径后面（新建的目录也能按真实位置比） */
 export function realish(p) {
   let cur = path.resolve(p)
@@ -70,16 +180,56 @@ export function within(p, root) {
 }
 
 /**
- * 代码默认放哪：会话目录是个前端项目、又不在设计目录里 → 就放会话目录；
+ * 代码放进 dest 时算哪个项目：dest 自己就是项目就用它；不是、但已经在某个项目里面（比如选了它的 src/pages）→ 用往上最近的那个
+ * （往上找到家目录为止，家目录本身不算：有人在家目录放 package.json；还不存在的目录不往上找：那是要新建的项目）
+ * dest 里有 index.html 时：上面的项目认得出框架才算它的（Angular、webpack 项目的 src/index.html）；
+ * 认不出的（Node 库仓库里的 docs/ 静态站点）还是当纯 HTML 站点
+ */
+export function projectFor(dest) {
+  const own = detectProject(dest)
+  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')) && !miniOf(cur)) continue
+    const p = detectProject(cur)
+    if (isCode(p)) return own.site && !p.framework ? own : p
+  }
+  return own
+}
+
+/**
+ * 代码默认放哪：会话目录是个项目（有 package.json，或是认得出的小程序）、又不在设计目录里 → 就放会话目录；
  * 否则新建 <设计名>-app：设计目录在会话目录下就建在会话目录里，不然建在设计目录旁边（别塞进设计目录）
  */
 export function defaultDest(root, cwd, project) {
   const inside = !!root && within(cwd, root)
-  if (project && project.pkg && !inside) return cwd
-  const base = (root ? path.basename(root) : 'app').replace(/[^\w-]+/g, '-').replace(/^-+|-+$/g, '').toLowerCase() || 'app'
-  const name = base === 'app' || base.endsWith('-app') ? `${base}-code` : `${base}-app`
+  if (isCode(project) && !inside) return cwd
   const under = !!root && !inside && within(root, cwd)
-  return path.join(root && !under ? path.dirname(root) : cwd, name)
+  return path.join(root && !under ? path.dirname(root) : cwd, appDirName(root))
+}
+
+/** 新建的代码目录叫什么：<设计名>-app */
+export function appDirName(root) {
+  const base = (root ? path.basename(root) : 'app').replace(/[^\w-]+/g, '-').replace(/^-+|-+$/g, '').toLowerCase() || 'app'
+  return base === 'app' || base.endsWith('-app') ? `${base}-code` : `${base}-app`
+}
+
+/**
+ * 用户在右侧栏选了个文件夹 → { dest, why }：
+ * 是个项目（有 package.json、index.html 或 .git，后端、monorepo 根目录也算）、在某个项目里面（比如它的 src/pages）、空文件夹、还不存在、
+ * 或者本来就叫 <设计名>-app（上回放过的）→ 就放这里（why 空）；
+ * 别的有东西的文件夹（比如 ~/Projects）→ 在它里面新建 <设计名>-app（why 'nested'）；
+ * 选到设计目录里面了 → 放到设计目录旁边（why 'beside'：设计稿要留着做对比，handoff_design 也不收设计目录里的地方）
+ */
+export function pickedDest(dir, root) {
+  const name = appDirName(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) && !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
 }
 
 /** 文件名 → 建议路由：index / home → /，别的 /名字 */
@@ -88,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 }] */
@@ -186,25 +343,85 @@ 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}`, '')
   lines.push(`> 给写代码的模型看：照这份把设计稿做成真页面。设计稿就是源码——每屏一个 HTML，样式在 tokens.css 等样式表里。先读源文件，截图只用来对照，别凭截图猜数值。`, '')
   lines.push('## 做什么', '')
   lines.push(`- 设计目录：\`${root}\`（${rows.length} 屏${more ? `，另有 ${more} 屏没列进来` : ''}，${kind} ${size[0]}×${size[1]}）`)
-  if (project && project.pkg) lines.push(`- 做到：\`${dest || project.dir}\`（现有项目 ${project.name}：${project.label || '没认出框架'}${project.tailwind ? ' + Tailwind' : ''}${project.ts ? '，TypeScript' : ''}，包管理 ${project.pm}）`)
+  // 目录里已经有别的东西、又不是 Node 项目（别的语言的仓库、后端……）：别在原地或旁边跑脚手架
+  // （纯 HTML 站点再做成纯 HTML 不算：就加在这个站点里，下面第 1 步提醒别覆盖现有页面）
+  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') {
@@ -214,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} 段没截）` : '')
@@ -231,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` 上的变量再动手。')
@@ -243,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('')
 
@@ -289,16 +515,52 @@ 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('')
 
   // 做法
-  const create = !(project && project.pkg) && fw && fw.create ? fw.create.replace('{name}', path.basename(dest || name + '-app')) : ''
+  // 在认不出前端框架的项目（后端）或 monorepo 里选了个空的新文件夹：就在这里新建前端项目，不用再看结构、另套一层
+  const fresh = !!(project && project.pkg && (!project.framework || project.mono) && dest && fold(realish(dest)) !== fold(realish(project.dir)) && !hasStuff(dest))
+  // 「跟项目一样」新建子包时照项目的框架；装依赖用项目的包管理器（create-next-app 自己装依赖，换成对应的 --use-xxx）
+  // 只认得出是普通 React / Vue / Next.js 时才套现成的脚手架命令（Nuxt 也算 vue，但不能用 Vue + Vite 的命令搭）
+  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 = (!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('## 做法和验收', '')
-  lines.push(`1. 搭骨架：${create ? `新建项目 \`${create}\`，装好依赖${fw.router ? `和 ${fw.router}` : ''}` : framework === 'html' ? '整理成一个静态站点目录（每屏一个页面，公共样式一份）' : `在现有项目里加页面和路由（看清它现有的目录结构、样式写法、组件库再动手）`}；把 tokens.css${sheets.length ? '（和公共样式表）' : ''}搬进去。`)
-  lines.push('2. 一屏一个页面，路由照上面的表；先抽几屏共用的组件，再拼页面。')
-  lines.push('3. 结构、文案、数字、图标照设计稿的 HTML 搬；class 名可以改成项目的习惯，样式值（间距、字号、颜色、圆角、阴影）一律用设计变量。')
-  lines.push('4. 每做完一屏：把开发服务器跑起来，调 `compare_design`（screen 填设计文件名，url 填这一屏在开发服务器上的地址），照差异图把不一样的地方改掉，直到差异在 3% 以内，或者剩下的差别说得出理由（比如真实数据、系统字体）。')
-  lines.push('5. 全部做完：每屏再对一遍；告诉用户做了哪些页面、怎么跑起来（命令和地址）、还有哪里和设计稿不一样。')
+  // 现有项目但没认出前端框架（后端、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 ? '；目录里已经有文件：别覆盖现有的页面，重名的先问用户' : ''
+  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)