@xiaobuyu/nodesign 0.0.1

package/server/lib/export-collect.js

@@ -0,0 +1,289 @@
+/**
+ * lib/export-collect.js — 按「产物卡」收集要导出的东西（2026-08-17）
+ *
+ * 导出的寻址单位从「会话当前产物」换成**画布上的那张卡**：卡的类型决定收什么。
+ * site 卡收站点那棵树、图片卡收那张图，以此类推。
+ *
+ * 为什么按卡 id 就够、不用再造一份枚举：
+ *   卡 id 本身**就是地址**（`site:<产物根>` / `deck:<html路径>` / 文件卡是裸路径），
+ *   前端 `BoardCanvas` 拼它、服务端 `board-store.mapId` 认它，用的是同一套前缀判据。
+ *   这里只解析地址、落到磁盘上收，权威清单仍然只有 `/artifacts` 那一份。
+ *
+ * 素材只收**这份产物真正引用到的**（`asset-refs.js` 扫出来的），不再像旧交付包那样
+ * 把整个项目级 `shared/assets` 一锅端 —— 那会把别的任务的图一起交出去，生产上最大的
+ * 项目那个目录有 280MB。
+ *
+ * ── 2026-08-17 评审后修的四个洞（都有单测钉着）──
+ *   1. **根级站点卡**（`site:`，rel 为空 —— 扁平化后「根 index.html = 一个站」是常态）
+ *      从工作区根盲走，把 `assets/`、`exports/`、`board.json`、别的任务全打进包，
+ *      280MB 病原样复活。
+ *   2. **单页站点卡**（`site:任务/_drafts/试作.html`）整类 400 —— 它是画布上真实存在
+ *      的一种卡，收集器却要求 site 必须是目录。
+ *   3. **`.ndignore` 基准**从卡 id 字符串上切第一段，只有「深度 1 的任务文件夹」这一
+ *      种布局碰巧对；根级构建站、嵌套站全取错，忽略规则静默失效。
+ *   4. **软链逃逸**：`safeResolve` 只做词法检查，工作区里一个指向外面的软链能把
+ *      工作区外的文件收进包（实测读出过 /tmp 下的文件内容）。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { walkTaskFiles, loadIgnore, RESERVED_DIRS, isReservedFile } from './task-scan.js';
+import { collectAssetRefs } from './asset-refs.js';
+import { kindDef, taskManifest, can } from './kinds/index.js';
+import { fileKindOfPath, fileKindDef } from './kinds/file-kinds.js';
+// 越界判据收在一处（原来这里有第二份实现，docx 页图路由抄它的形状时抄漏了 realpath）
+import { safeResolveRead as safeResolve } from './safe-path.js';
+
+/**
+ * 卡 id → { kind, rel }。
+ *
+ * ⚠️ 前缀只认纯字母（`deck:` `site:`）—— 路径里本来就可能有冒号，判据必须跟
+ * 前端 `stage.js` 的 `zoneOfObjectId` 和服务端 `board-store.mapId` 保持一致。
+ * 没有合法前缀 = 文件卡，类型按路径推。
+ * 认哪些前缀问注册表（kindDef）—— 原来是两个手写 Set，加形态时这里必漏，
+ * 新形态的卡会被当成裸文件路径去解析（「写死表家族」第 5 处，2026-08-18 收）。
+ *
+ * ⚠️ 已知歧义：根层一个叫 `final:v2.png` 的文件，卡 id 就是裸路径，这里会把
+ * `final` 当前缀剥掉。三处判据是**一致地**这样，改判据要三处一起改；collectCard
+ * 里对这种情况有一次「整串当路径」的回退。
+ */
+export function parseCardId(cardId) {
+  if (!cardId || typeof cardId !== 'string') return null;
+  const c = cardId.indexOf(':');
+  if (c > 0 && /^[a-z]+$/.test(cardId.slice(0, c))) {
+    const kind = cardId.slice(0, c);
+    const rel = cardId.slice(c + 1).replace(/\\/g, '/');
+    if (kindDef(kind)) return { kind, rel };
+    return { kind: fileKindOfPath(rel), rel };
+  }
+  const rel = cardId.replace(/\\/g, '/');
+  return { kind: fileKindOfPath(rel), rel };
+}
+
+
+/** 这种形态能导出成什么。single = 单页产物，没有「整站 zip」可言（跟 taskManifest 的 decorate 同一条剥除） */
+export function exportFormatsFor(kind, { single = false } = {}) {
+  const list = kindDef(kind)?.exportFormats || fileKindDef(kind)?.exportFormats || [];
+  return single ? list.filter(f => f !== 'site') : list;
+}
+
+/**
+ * 忽略规则的基准目录 = **`.ndignore` 自己所在的那一层**，从产物根往上找第一个。
+ *
+ * 这跟 `.gitignore` 是同一条语义：规则文件的作用域就是它自己的目录。
+ *
+ * 曾经从卡 id 字符串上切第一段（`rel.split('/')[0]`）当基准，只有「深度 1 的任务
+ * 文件夹」这一种布局碰巧对：根级构建站（`site:dist`）会切出 `dist`、嵌套站
+ * （`site:客户/官网`）会切出 `客户`，两种情况下忽略规则都**静默失效**。
+ * 也试过问 `taskManifest` 谁认领了这个产物根，但构建站的 `dist/` 自己看起来也像
+ * 个站，从深往浅问会停在 `dist` 上 —— 而 `.ndignore` 明明在更外面。
+ * 按规则文件自己的位置找，三种布局一次都不会错。
+ */
+async function ignoreBaseFor(workspaceRoot, rel) {
+  const segs = rel ? rel.split('/') : [];
+  for (let i = segs.length; i >= 0; i--) {
+    const cand = segs.slice(0, i).join('/');
+    const dir = cand ? path.join(workspaceRoot, cand) : workspaceRoot;
+    try {
+      await fs.access(path.join(dir, '.ndignore'));
+      return cand;
+    } catch { /* 这层没有，往上找 */ }
+  }
+  return '';   // 一个都没有：基准取工作区根（规则为空，等价于不过滤）
+}
+
+/**
+ * 收一张卡。
+ *
+ * @returns {Promise<{cardId, kind, rel, title, single, files, assets, missing, unresolved, exportFormats}>}
+ *   files       产物自身的文件（rel 相对工作区根）
+ *   assets      它真正引用到、且磁盘上确实存在的素材
+ *   missing     引用了但磁盘上找不到的（裂图预警）
+ *   unresolved  算不出来的引用（动态拼接 / 脚本字面量 / 树外引用 / `<base href>`）
+ */
+export async function collectCard({ workspaceRoot, cardId }) {
+  const parsed = parseCardId(cardId);
+  if (!parsed) throw Object.assign(new Error(`认不出这张卡：${cardId}`), { status: 400 });
+
+  let { kind, rel } = parsed;
+  let abs = await safeResolve(workspaceRoot, rel);
+  let stat = null;
+  if (abs) { try { stat = await fs.stat(abs); } catch { /* 下面回退 */ } }
+
+  // 前缀剥错了的回退：`final:v2.png` 这种文件名会被当成 `final:` 前缀
+  if (!stat && cardId !== rel) {
+    const whole = cardId.replace(/\\/g, '/');
+    const absWhole = await safeResolve(workspaceRoot, whole);
+    if (absWhole) {
+      try {
+        stat = await fs.stat(absWhole);
+        abs = absWhole; rel = whole; kind = fileKindOfPath(whole);
+      } catch { /* 仍然没有 */ }
+    }
+  }
+  if (!abs) throw Object.assign(new Error(`路径越界或指向工作区外：${rel}`), { status: 400 });
+  if (!stat) throw Object.assign(new Error(`产物不存在：${rel}`), { status: 404 });
+
+  const files = [];
+  // 「这种形态有没有目录型」问注册表（kind 条目声明 directory）。整树打包只对
+  // browsable 的目录型成立（站点 = 一棵互相引用的树）；word 文件夹也是目录型，
+  // 但 .docx 成员各自自包含，卡级导出走下面挑主成员那条，不走树
+  const dirKind = !!kindDef(kind)?.directory;
+  // 单页站点（`_drafts/试作.html` 这类）也是 site 卡，只是它是一个文件不是一棵树
+  const single = dirKind && can(kind, 'browsable') && stat.isFile();
+  const isTree = dirKind && can(kind, 'browsable') && stat.isDirectory();
+
+  const deepWarn = [];
+  if (isTree && !rel) {
+    // ⭐**根站不盲走。** 扁平化后「根 index.html = 一个站」是常态，而根站的「树」
+    // 就是整个工作区 —— 盲走会把项目基础设施和**别的任务**一起卷进来。
+    // 正解是问权威解析器要页面清单：`taskManifest` 的根站条目（site / 非 single /
+    // 无 srcRoot，跟 assets.js 判 rootSite 同一口径）里的 `pages` 就是它认领了哪些页。
+    // 别的任务的 index.html 不在这份 pages 里，天然被排除；页面引用到的 css/js/图
+    // 由下面的 refs 收。这比我自己拿一张保留目录表去猜要靠谱 —— 谁属于这个站，
+    // 只有解析器说了算。
+    const m = await taskManifest(workspaceRoot).catch(() => null);
+    const rootSite = (m?.artifacts || []).find(a => a.kind === 'site' && !a.single && !a.srcRoot);
+    for (const pg of (rootSite?.pages || [])) {
+      const pRel = String(pg).replace(/\\/g, '/');
+      const pAbs = await safeResolve(workspaceRoot, pRel);
+      if (!pAbs) continue;
+      try { if ((await fs.stat(pAbs)).isFile()) files.push({ abs: pAbs, rel: pRel }); } catch { /* 页面刚被删 */ }
+    }
+    if (!files.length) {
+      // 解析器认不出根站（还没写出 index.html 之类）→ 退回入口文件本身，
+      // 绝不退回「盲走整个工作区」
+      const entryAbs = await safeResolve(workspaceRoot, 'index.html');
+      if (entryAbs) {
+        try { if ((await fs.stat(entryAbs)).isFile()) files.push({ abs: entryAbs, rel: 'index.html' }); } catch { /* */ }
+      }
+    }
+  } else if (isTree) {
+    const ignoreBaseRel = await ignoreBaseFor(workspaceRoot, rel);
+    const ignoreBaseAbs = (await safeResolve(workspaceRoot, ignoreBaseRel)) || workspaceRoot;
+    const ignore = await loadIgnore(ignoreBaseAbs);
+    const walked = await walkTaskFiles(abs, { maxDepth: 6, ignore, ignoreBase: ignoreBaseAbs });
+    for (const f of walked) {
+      const r = path.relative(workspaceRoot, f.abs).replace(/\\/g, '/');
+      files.push({ abs: f.abs, rel: r });
+      // maxDepth 撞顶是静默截断的（walkTaskFiles 不给信号）。贴着上限的文件说明
+      // 这棵树很深，更深的东西可能没进包 —— 报出来，别让人以为齐了。
+      // ⚠️ 深度要按 **walk 相对卡根** 的路径算（`f.rel`），不是工作区相对的 `r`：
+      // 嵌套站 `客户/官网/a/b/c/x.png` 在工作区坐标下有 6 段，但 walk 只走了 4 层，
+      // 离截断远着 —— 用错坐标系会往交付物里印假警报。
+      if (f.rel.split('/').length >= 6) deepWarn.push(r);
+    }
+  } else if (kind === 'docx' && stat.isDirectory()) {
+    // word 文件夹卡（`docx:报告`）：地址是文件夹，导出对象是主成员 —— 窗里的
+    // 导出按钮会点名具体成员（`docx:报告/文档v2.docx`），走上面的单文件分支；
+    // 这条是卡级导出的兜底。挑主成员的判据在 kinds/docx.js，别在这儿抄第二份。
+    let names = [];
+    try { names = kindDef('docx').sortDocxNames(await fs.readdir(abs)); } catch { /* 下面报 404 */ }
+    if (!names.length) throw Object.assign(new Error(`${rel} 里没有 .docx`), { status: 404 });
+    rel = `${rel}/${names[0]}`;
+    files.push({ abs: path.join(abs, names[0]), rel });
+  } else {
+    if (!stat.isFile()) throw Object.assign(new Error(`${rel} 不是文件`), { status: 400 });
+    files.push({ abs, rel });
+  }
+
+  if (!files.length) {
+    throw Object.assign(new Error(`${rel} 里没有可导出的文件`), { status: 400 });
+  }
+
+  // 树外引用只认 `assets/` 和产物自己的目录（旧 /exports/site 有这道闸，别丢）。
+  // 根层产物的自有前缀是空串 = 不设闸：它的树本来就是整个工作区，这条认账。
+  const ownPrefix = isTree ? (rel ? `${rel}/` : '') : (path.posix.dirname(rel) === '.' ? '' : `${path.posix.dirname(rel)}/`);
+  // 只有**标记语言**产物需要跟着引用扫下去。`browsable` 正好是这条线：能用浏览器
+  // 打开 = 由 html/css 组成 = 有外部引用要带。docx 是自包含的 zip（图片字体都在
+  // 包里），拿二进制去跑引用扫描器是白费力气，还可能在压缩字节里撞出假路径。
+  // 问注册表和能力，不问形态名 —— 加第四种形态时这行不用动。
+  const scannable = !!kindDef(kind) && can(kind, 'browsable');
+  let refs = []; let unresolved = []; let candidates = [];
+  if (scannable) {
+    // ⭐**传递引用要跟着扫下去。** html 引 css、css 再引图 —— 只扫产物自身的话，
+    // 那张图既不进包也不进清单（用户拍的规矩里最坏的状态），解压即裂图且零预警。
+    // deck 卡 / 单页站 / 根站三类全中，因为它们的 files 里只有页面本身。
+    // 定点到不动为止，最多四轮（防环、也防超深链把单次导出拖垮）。
+    const allow = ownPrefix === '' ? [] : [ownPrefix, 'assets/'];
+    const scanned = new Set(files.map(f => f.rel));
+    let batch = files;
+    for (let round = 0; round < 4 && batch.length; round++) {
+      const r = await collectAssetRefs({ files: batch, baseRoot: workspaceRoot, allowPrefixes: allow });
+      refs.push(...r.refs); unresolved.push(...r.unresolved); candidates.push(...r.candidates);
+      batch = [];
+      for (const rr of r.refs) {
+        if (scanned.has(rr) || !/\.(html?|css|m?js|cjs)$/i.test(rr)) continue;
+        scanned.add(rr);
+        const a = await safeResolve(workspaceRoot, rr);
+        if (a) batch.push({ abs: a, rel: rr });
+      }
+    }
+    refs = [...new Set(refs)];
+  }
+  if (deepWarn.length) {
+    unresolved.push({
+      from: rel || '(工作区根)',
+      why: `目录深度贴到上限 6 层，更深的文件没有进包（命中 ${deepWarn.length} 个）`,
+      snippet: deepWarn.slice(0, 3).join(' / '),
+    });
+  }
+
+  const assets = []; const missing = [];
+  const ownSet = new Set(files.map(f => f.rel));
+  // 脚本里的完整字面量路径（画廊 / lightbox 那种）：**磁盘上真有这个文件就不是猜**，
+  // 提升成素材；解析不到的仍然只进清单。这不违反「扫不到的不多塞」——
+  // 它扫得到，只是来源是脚本而不是标签。
+  for (const c of candidates) {
+    const a = await safeResolve(workspaceRoot, c.rel);
+    if (!a || ownSet.has(c.rel)) continue;
+    try {
+      if ((await fs.stat(a)).isFile()) { refs.push(c.rel); continue; }
+    } catch { /* 不存在 */ }
+    unresolved.push({ from: c.from, why: '脚本里的字符串字面量（磁盘上没找到对应文件）', snippet: c.snippet });
+  }
+  refs = [...new Set(refs)].sort();
+  for (const r of refs) {
+    const a = await safeResolve(workspaceRoot, r);
+    if (!a) continue;                                    // 软链逃逸的引用直接不收
+    let st = null;
+    try { st = await fs.stat(a); } catch { missing.push(r); continue; }
+    if (st.isFile()) { assets.push({ abs: a, rel: r }); continue; }
+    if (st.isDirectory()) {
+      // pretty-URL（`href="about/"`）指的是 `about/index.html`，不是裂图。
+      // 不处理的话每个多页站导出都会带一堆假的缺失警报。
+      const idxRel = `${r.replace(/\/$/, '')}/index.html`;
+      if (ownSet.has(idxRel)) continue;
+      const idxAbs = await safeResolve(workspaceRoot, idxRel);
+      if (idxAbs) {
+        try {
+          if ((await fs.stat(idxAbs)).isFile()) { assets.push({ abs: idxAbs, rel: idxRel }); continue; }
+        } catch { /* 落 missing */ }
+      }
+    }
+    missing.push(r);
+  }
+
+  return {
+    cardId, kind, rel, single,
+    title: path.basename(rel) || rel || '产物',
+    files, assets, missing, unresolved,
+    exportFormats: exportFormatsFor(kind, { single }),
+  };
+}
+
+/**
+ * 按类型收一批卡（「导出全部图片」这种）。
+ * 单张失败不拖累整批 —— 收不到的记进 skipped，让人看见少了什么。
+ */
+export async function collectCards({ workspaceRoot, cardIds }) {
+  const bundles = []; const skipped = [];
+  for (const id of cardIds) {
+    try {
+      bundles.push(await collectCard({ workspaceRoot, cardId: id }));
+    } catch (err) {
+      skipped.push({ cardId: id, reason: err.message, status: err.status || 500 });
+    }
+  }
+  return { bundles, skipped };
+}

package/server/lib/export-package.js

@@ -0,0 +1,210 @@
+/**
+ * lib/export-package.js — 把收集到的产物打成用户拿得走的东西（2026-08-17）
+ *
+ * 分两个出口，各自说清给谁：
+ *   **看的出口**  raw / zip —— 给不动手的人。原件或一个压缩包，双击就能看。
+ *   **接手的出口** handoff（工程包）—— 给要继续开发的人。除了源码，还带一份
+ *                  「这是什么、怎么跑、mock 数据在哪、你的后端要实现哪些接口」。
+ *
+ * ⭐**zip 布局保持工作区相对路径，不做任何改写。**
+ * 旧交付包把东西塞进 `design/` 再回头重写 `../../assets/` 前缀，于是有了一整类
+ * 裂图 bug（深度算错一层，图全裂）。保持原布局的话，产物里的相对引用**天然成立**，
+ * 零改写、零深度计算 —— 那类 bug 从根上不存在。代价只是解压出来多一层目录，
+ * 换来的是"打开就对"。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import JSZip from 'jszip';
+import { renderUnresolvedReport } from './asset-refs.js';
+
+/** 文件名里不能出现的东西（路径分隔与父目录） */
+export function safeName(name, fallback = '导出') {
+  const s = String(name || '').replace(/[/\\]/g, '_').replace(/\.\.+/g, '.').trim();
+  return s || fallback;
+}
+
+/**
+ * 从 `api.js` 那层抽出后端接口清单。
+ *
+ * 应用道的约定是：所有数据访问走一层 `api/` 函数，每个函数右边注上建议路由
+ * （`// GET /api/posts`）。**那列注释就是交接文档的草稿** —— 这里把它抽成表，
+ * 用户拿到的就不只是前端，还有一份现成的后端需求规格。这是「用了模拟数据」
+ * 从缺陷变成资产的那一步。
+ *
+ * 抓的是 `export const 名字 = ... // METHOD /path` 和 `export async function 名字`。
+ */
+export function extractApiContract(source) {
+  const rows = [];
+  // ⚠️ 标识符类必须认 Unicode。JS 的标识符本来就允许非 ASCII，而这个产品里
+  // agent 写的代码大量用中文命名（`export const 列出书目 = …`）—— 用
+  // `[A-Za-z_$]` 会把它们整片漏掉，接口表少一半还不报错。
+  const lineRe = /export\s+(?:const|let|async\s+function|function)\s+([\p{L}_$][\p{L}\p{N}_$]*)[^\n]*?(?:\/\/\s*(GET|POST|PUT|PATCH|DELETE)\s+(\S+))?\s*$/gmu;
+  let m;
+  while ((m = lineRe.exec(source)) !== null) {
+    const [, name, method, route] = m;
+    if (!name) continue;
+    rows.push({ name, method: method || null, route: route || null });
+  }
+  return rows;
+}
+
+/** 在收到的文件里找 api 层（`app/api.js` / `src/api/index.js` / 任何 `api.js`） */
+function findApiFile(files) {
+  const score = (rel) => {
+    if (/(^|\/)app\/api\.js$/i.test(rel)) return 3;
+    if (/(^|\/)api\/index\.js$/i.test(rel)) return 2;
+    if (/(^|\/)api\.js$/i.test(rel)) return 1;
+    return 0;
+  };
+  return files.map(f => ({ f, s: score(f.rel) })).filter(x => x.s > 0)
+    .sort((a, b) => b.s - a.s)[0]?.f || null;
+}
+
+/** 有没有 package.json，决定 README 里写「双击打开」还是「npm i && npm run build」 */
+function findPackageJson(files) {
+  return files.find(f => /(^|\/)package\.json$/.test(f.rel)) || null;
+}
+
+/**
+ * 工程包的 README —— 交付物的一半。
+ * 没有它，用户拿到的是一堆他不敢动的文件。
+ */
+async function renderHandoffReadme({ projectName, bundles, apiRows, pkg, missing, hasMock }) {
+  const titles = bundles.map(b => b.title).join('、');
+  const L = [];
+  L.push(`# ${projectName || titles || '设计交付'}`, '');
+  L.push(`本包由 NoDesign 导出，包含 ${bundles.length} 份产物：${titles}。`, '');
+
+  L.push('## 怎么打开', '');
+  if (pkg) {
+    L.push('这是一个需要构建的工程：', '', '```bash', 'npm install', 'npm run build', '```', '');
+    L.push('构建产物在 `dist/`（或 package.json 里 build 脚本指定的目录）。**`node_modules` 不在包里**，靠上面这两行装回来。', '');
+  } else {
+    L.push('直接用浏览器打开入口 html 就行，不需要装任何东西。页面之间是相对链接，不依赖服务器。', '');
+  }
+
+  if (hasMock) {
+    L.push('## 现在的数据是假的', '');
+    L.push('所有数据来自 `mock` / `seed` 那一层，写操作存在浏览器 localStorage 里。清掉浏览器数据就回到初始状态。', '');
+    L.push('**这是一个可运行的原型，不是上线的系统** —— 托管和真实数据是你自己的事。', '');
+  }
+
+  if (apiRows.length) {
+    L.push('## 换成真后端要改哪里', '');
+    L.push('只改 api 那一层文件：把每个函数从调用 mock 改成 `fetch`。**页面代码一行都不用动。**', '');
+    L.push('你的后端需要提供这些接口：', '');
+    L.push('| 函数 | 建议路由 |', '|---|---|');
+    for (const r of apiRows) {
+      L.push(`| \`${r.name}\` | ${r.method && r.route ? `\`${r.method} ${r.route}\`` : '（源码里没注路由，自己定）'} |`);
+    }
+    L.push('');
+  }
+
+  if (missing.length) {
+    L.push('## ⚠️ 有几个引用没找到对应文件', '');
+    L.push('下面这些是页面里引用了、但打包时磁盘上没有的（原工程里可能已经删了或改名了）：', '');
+    for (const m of missing.slice(0, 30)) L.push(`- \`${m}\``);
+    if (missing.length > 30) L.push(`- …还有 ${missing.length - 30} 条`);
+    L.push('');
+  }
+
+  L.push('## 包里有什么', '');
+  L.push('目录结构跟原工作区一致，**没有做任何路径改写** —— 所以页面里的相对引用原样成立，解压出来直接能用。', '');
+  return L.join('\n');
+}
+
+/**
+ * 打包。
+ *
+ * @param {Array} bundles  collectCard 的产出
+ * @param {object} opts
+ * @param {'raw'|'zip'|'md'|'handoff'|'site'} opts.format
+ * @param {string} [opts.projectName]
+ * @returns {Promise<{filename:string, buffer:Buffer, mime:string}>}
+ */
+export async function packageBundles(bundles, { format, projectName } = {}) {
+  if (!bundles?.length) {
+    throw Object.assign(new Error('没有可导出的产物'), { status: 400 });
+  }
+
+  // 原件直下：只有单张卡、且只有一个文件时成立
+  if (format === 'raw') {
+    if (bundles.length !== 1 || bundles[0].files.length !== 1) {
+      throw Object.assign(new Error('原件直下只能对单个文件用，多个请用 zip'), { status: 400 });
+    }
+    const f = bundles[0].files[0];
+    return {
+      filename: path.basename(f.rel),
+      buffer: await fs.readFile(f.abs),
+      mime: 'application/octet-stream',
+    };
+  }
+
+  // 便签合并成一份 markdown
+  if (format === 'md') {
+    const parts = [];
+    for (const b of bundles) {
+      for (const f of b.files) {
+        if (!/\.md$/i.test(f.rel)) continue;
+        parts.push(`<!-- ${f.rel} -->\n\n${await fs.readFile(f.abs, 'utf8')}`);
+      }
+    }
+    if (!parts.length) throw Object.assign(new Error('这些卡里没有 markdown 可合并'), { status: 400 });
+    return {
+      filename: `${safeName(projectName, '便签')}.md`,
+      buffer: Buffer.from(parts.join('\n\n---\n\n'), 'utf8'),
+      mime: 'text/markdown; charset=utf-8',
+    };
+  }
+
+  const zip = new JSZip();
+  const seen = new Set();
+
+  // 裹不裹一层：**只在真会「解压即散落」时裹**。
+  // 根级站点的文件就住在工作区根（`index.html`、`lib/…`），不裹的话 unzip 会把
+  // 一堆东西直接倒进当前目录 —— 旧的 /exports/site 靠 `site/` 前缀避开了这点，
+  // 换新管线不能把它丢了。判据就是"有没有文件贴在包根上"。
+  // ⚠️ 裹是**整体平移**，所有文件和素材同加一个前缀，相对引用原样成立 ——
+  // 仍然零改写，不碰旧那套按深度重写 `../assets/` 的老路（那是裂图事故的根）。
+  const allRels = bundles.flatMap(b => [...b.files, ...b.assets].map(f => f.rel));
+  const needsWrap = allRels.some(r => !r.includes('/'));
+  const wrapBase = needsWrap ? `${safeName(projectName || bundles[0].title, '导出')}/` : '';
+  const allMissing = []; const allUnresolved = [];
+  const allFiles = []; const allAssets = [];
+
+  for (const b of bundles) {
+    allMissing.push(...b.missing);
+    allUnresolved.push(...b.unresolved);
+    allFiles.push(...b.files);
+    allAssets.push(...b.assets);
+    for (const f of [...b.files, ...b.assets]) {
+      if (seen.has(f.rel)) continue;          // 多张卡引用同一张图时只进一次
+      seen.add(f.rel);
+      try { zip.file(wrapBase + f.rel, await fs.readFile(f.abs)); } catch { /* 中途被删就跳过 */ }
+    }
+  }
+
+  // 没解析出来的引用写成清单。**没有就不放** —— 旧包里那个常年空着的
+  // prompt.txt 就是"占位符放着放着就成了垃圾"的样板。
+  const report = renderUnresolvedReport(allUnresolved);
+  if (report) zip.file('未解析的引用.md', report);
+
+  if (format === 'handoff') {
+    const apiFile = findApiFile(allFiles);
+    const apiRows = apiFile ? extractApiContract(await fs.readFile(apiFile.abs, 'utf8').catch(() => '')) : [];
+    const pkg = findPackageJson(allFiles);
+    const hasMock = allFiles.some(f => /(^|\/)(mock|seed)[./]/i.test(f.rel));
+    zip.file('README.md', await renderHandoffReadme({
+      projectName, bundles, apiRows, pkg, missing: allMissing, hasMock,
+    }));
+  }
+
+  const base = safeName(projectName || bundles[0].title, '导出');
+  const suffix = format === 'handoff' ? '-工程包' : '';
+  return {
+    filename: `${base}${suffix}.zip`,
+    buffer: await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' }),
+    mime: 'application/zip',
+  };
+}

package/server/lib/html-srcset.js

@@ -0,0 +1,145 @@
+/**
+ * lib/html-srcset.js — 给站点 HTML 的 <img> 注入 srcset
+ *
+ * 问题：agent 写的站点是 `<img src="assets/x.png">`，手机上也照发 1536px 宽的原图。
+ * 站点按真实设备宽取景，服务端不能自作主张缩尺寸（缩了桌面就糊），所以只能把
+ * "有哪些尺寸可选"告诉浏览器，让它按视口和 DPR 自己挑。
+ *
+ * 做法：只加属性，**不改 DOM 结构**。
+ *
+ *   <img src="assets/x.png">
+ *   →
+ *   <img src="assets/x.png?v=ab12ef" sizes="100vw"
+ *        srcset="assets/x.png?w=480&v=ab12ef 480w, assets/x.png?w=960&v=ab12ef 960w, assets/x.png 1536w">
+ *
+ * **为什么不用 <picture>**：<picture> 能按 type 分发 avif/webp 且不需要 Vary，
+ * 技术上更优。但它要在 <img> 外面套一层元素，而站点 HTML 是 agent 写的，
+ * `.grid > img` 这类直接子选择器会失配，img 作为 grid/flex item 时盒子也会变成
+ * picture（默认 inline）导致布局位移。为了压几十 KB 去动别人的布局不划算。
+ * 所以格式仍走 Accept 协商（响应带 Vary: Accept），这里只管尺寸。
+ *
+ * sizes 的取值：默认 100vw。这是"高估"的一侧 —— 浏览器会挑偏大的那档，省得少
+ * 但绝不会糊。反过来低估会让图变糊，那是肉眼可见的质量事故。真正的收益在移动端：
+ * 480 CSS px 的手机按 DPR 2 只需要 960w，不再拉 1536。img 自己写了 width 属性或
+ * 内联 px 宽度时按它算，那是 agent 明确表达过的意图，比默认值准。
+ *
+ * 跳过的情况：已有 srcset（agent 自己写过）、非本地相对路径（http/data/协议相对）、
+ * 拿不到原图尺寸、原图本来就比最小那档还窄。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import sharp from 'sharp';
+import { RESPONSIVE_WIDTHS, shouldTranscode, versionTag } from './image-variant.js';
+
+/** 图片元数据缓存：绝对路径 → { key, width, height, v }。key 带 mtime+size，源变了自然失效 */
+const metaCache = new Map();
+const META_CACHE_MAX = 2000;
+
+async function imageMeta(absPath) {
+  let stat;
+  try {
+    stat = await fs.stat(absPath);
+    if (!stat.isFile()) return null;
+  } catch { return null; }
+
+  const key = `${stat.mtimeMs}|${stat.size}`;
+  const hit = metaCache.get(absPath);
+  if (hit && hit.key === key) return hit;
+
+  let meta;
+  try {
+    meta = await sharp(await fs.readFile(absPath)).metadata();
+  } catch { return null; }
+  if (!meta?.width) return null;
+
+  const entry = { key, width: meta.width, height: meta.height || 0, v: versionTag(stat) };
+  if (metaCache.size >= META_CACHE_MAX) metaCache.delete(metaCache.keys().next().value);
+  metaCache.set(absPath, entry);
+  return entry;
+}
+
+/** <img ...> 整标签。属性值里不会出现 '>' 的常规写法，够用且不引入 HTML parser 依赖 */
+const IMG_TAG_RE = /<img\b([^>]*)>/gi;
+
+function attrOf(attrs, name) {
+  const m = attrs.match(new RegExp(`\\b${name}\\s*=\\s*("([^"]*)"|'([^']*)')`, 'i'));
+  return m ? (m[2] ?? m[3] ?? '') : null;
+}
+
+/**
+ * 这个 img 打算显示多宽（CSS px）。拿不准返 null，调用方退回 100vw。
+ * 只认 width 属性和内联 style 里的 px 宽度，百分比 / vw / rem 一律不猜。
+ */
+function declaredWidth(attrs) {
+  const w = attrs.match(/\bwidth\s*=\s*["']?(\d+)/i);
+  if (w) return Number(w[1]);
+  const style = attrOf(attrs, 'style');
+  const m = style && style.match(/(?:^|;)\s*width\s*:\s*(\d+(?:\.\d+)?)px/i);
+  return m ? Math.round(Number(m[1])) : null;
+}
+
+function appendQuery(url, params) {
+  const [base, hash = ''] = url.split('#');
+  const sep = base.includes('?') ? '&' : '?';
+  return `${base}${sep}${params}${hash ? '#' + hash : ''}`;
+}
+
+/**
+ * 给一份 HTML 里的 <img> 加 srcset/sizes。
+ *
+ * @param {string} html
+ * @param {string} baseDir 这份 HTML 所在目录的绝对路径（相对 src 按它解析）
+ * @param {string} rootGuard 允许触及的根（防路径逃逸；解析结果必须在它之下）
+ * @returns {Promise<string>}
+ */
+export async function injectSrcset(html, baseDir, rootGuard) {
+  if (!html || !/<img\b/i.test(html)) return html;
+
+  // 先把要查的 src 收齐，去重后并发查元数据，避免同一张图查 N 遍
+  const tags = [...html.matchAll(IMG_TAG_RE)];
+  const wanted = new Map();   // src → absPath
+  for (const [, attrs] of tags) {
+    const src = attrOf(attrs, 'src');
+    if (!src || wanted.has(src)) continue;
+    if (attrOf(attrs, 'srcset') !== null) continue;               // agent 自己写过
+    if (/^(?:[a-z][a-z0-9+\-.]*:|\/\/|#)/i.test(src)) continue;   // 绝对 / data: / 协议相对
+    if (!shouldTranscode(path.extname(src.split('?')[0]))) continue;
+    const abs = path.resolve(baseDir, decodeURIComponent(src.split('?')[0]));
+    if (abs !== rootGuard && !abs.startsWith(rootGuard + path.sep)) continue;
+    wanted.set(src, abs);
+  }
+  if (!wanted.size) return html;
+
+  const metas = new Map();
+  await Promise.all([...wanted].map(async ([src, abs]) => {
+    const m = await imageMeta(abs);
+    if (m) metas.set(src, m);
+  }));
+  if (!metas.size) return html;
+
+  return html.replace(IMG_TAG_RE, (whole, attrs) => {
+    const src = attrOf(attrs, 'src');
+    const meta = src && metas.get(src);
+    if (!meta) return whole;
+
+    // 比原图还宽的档没有意义（withoutEnlargement 会让它跟原图一样大，白占缓存）
+    const widths = RESPONSIVE_WIDTHS.filter(w => w < meta.width);
+    if (!widths.length) return whole;
+
+    const candidates = widths.map(w => `${appendQuery(src, `w=${w}&v=${meta.v}`)} ${w}w`);
+    candidates.push(`${appendQuery(src, `v=${meta.v}`)} ${meta.width}w`);
+
+    const dw = declaredWidth(attrs);
+    const sizes = dw ? `${dw}px` : '100vw';
+
+    let next = attrs;
+    if (attrOf(attrs, 'sizes') === null) next += ` sizes="${sizes}"`;
+    next += ` srcset="${candidates.join(', ')}"`;
+    // loading/decoding 是白送的：站点常常一屏之外还有十几张图，浏览器原生懒加载
+    // 能把它们整个推迟掉，比任何编码优化都省。已经写了的不覆盖。
+    if (attrOf(attrs, 'loading') === null) next += ' loading="lazy"';
+    if (attrOf(attrs, 'decoding') === null) next += ' decoding="async"';
+    return `<img${next}>`;
+  });
+}