@xiaobuyu/nodesign 0.0.1

package/server/api/exports/cards.js

@@ -0,0 +1,118 @@
+/**
+ * api/exports/cards.js — 按**产物卡**导出（2026-08-17 重做导出的入口）
+ *
+ * 从 exports.js 拆出来（行数棘轮：那份已经贴着上限）。放这儿也更对 ——
+ * 它跟老的四条烘焙路由（html/pdf/pptx/site）不是一档东西：
+ *   老路由 = **烘焙**，要跑 playwright / esbuild，产出是「给人看的文件」。
+ *   本路由 = **原样打包**，产出是「别人能接手继续开发的工程」。
+ *
+ * 旧导出以「会话当前产物」为单位，且把整个项目级 `shared/assets` 打进包
+ * （生产上最大的项目那目录 280MB）。新的以**画布上的那张卡**为单位：卡的类型
+ * 决定收什么，素材只收这份产物真正引用到的。
+ */
+
+import { collectCards } from '../../lib/export-collect.js';
+import { packageBundles } from '../../lib/export-package.js';
+
+const FORMATS = ['raw', 'zip', 'md', 'handoff'];
+const MAX_CARDS = 200;
+
+/**
+ * 并发闸。
+ *
+ * 打包是这台机器上最重的同步活：每个文件整读进内存，JSZip 的 DEFLATE 又在主线程
+ * 跑。生产机是 **1 vCPU / 8G / 无 swap**（尖峰直接进内核 OOM killer），压缩期间
+ * 唯一那颗核被占住，所有 SSE 与 agent 流一起饿着。没有闸的话，任何登录用户连点
+ * 几下导出就能把整台机器拖垮 —— 而且症状是「网站卡住」，没人会怀疑到导出头上。
+ *
+ * 全局 2 是按核数定的，不是按用户：护的是机器不是公平性。per-project 再压 1，
+ * 免得一个人连点把两个位置都占满。
+ *
+ * ⚠️ 这只挡住**同时几个**，挡不住**单个太大**（200 张视频卡可以到 GB 级）。
+ * 体积闸是另一件事，还没做。
+ */
+const MAX_INFLIGHT = 2;
+let inflight = 0;
+const inflightByProject = new Map();
+
+/**
+ * @param {object} deps
+ * @param {(req,res)=>object|null} deps.guard   exports.js 的 guard（项目/会话双挂载）
+ * @param {(req)=>string} deps.rootOf           工作区根
+ */
+export function makeCardsExportHandler({ guard, rootOf }) {
+  return async function handleCardsExport(req, res, next) {
+    try {
+      const project = guard(req, res);
+      if (!project) return;
+      const { cardIds, format } = req.body || {};
+      if (!Array.isArray(cardIds) || !cardIds.length) {
+        return res.status(400).json({ error: '要导出哪几张卡（cardIds 不能为空）' });
+      }
+      if (cardIds.length > MAX_CARDS) {
+        return res.status(400).json({ error: `一次最多导出 ${MAX_CARDS} 张卡` });
+      }
+      if (!FORMATS.includes(format)) {
+        return res.status(400).json({ error: `不认识的导出格式：${format}` });
+      }
+
+      if (inflight >= MAX_INFLIGHT) {
+        res.setHeader('Retry-After', '10');
+        return res.status(429).json({ error: '导出排队中（这台机器一次只打两个包），过几秒再点' });
+      }
+      if (inflightByProject.get(project.id)) {
+        res.setHeader('Retry-After', '10');
+        return res.status(429).json({ error: '这个项目已经有一个导出在跑了，等它完事' });
+      }
+      inflight += 1;
+      inflightByProject.set(project.id, true);
+      try {
+      const workspaceRoot = rootOf(req);
+      const { bundles, skipped } = await collectCards({ workspaceRoot, cardIds });
+      if (!bundles.length) {
+        return res.status(skipped[0]?.status === 404 ? 404 : 400)
+          .json({ error: '一张都没收到', skipped });
+      }
+
+      // 格式合法性由 packageBundles 自己把关（raw 要单文件、md 要有 markdown），
+      // 不在这儿再抄一份判据。⚠️ 曾经拿 `bundle.exportFormats.includes(format)`
+      // 当闸，是错的：那张表说的是**产物形态**能出什么（site 卡是 site/html/handoff），
+      // 跟本路由的打包档（zip/raw/md/handoff）语义不同，混用会把正常请求判死。
+      const { filename, buffer, mime } = await packageBundles(bundles, {
+        format,
+        projectName: bundles.length === 1 ? bundles[0].title : project.name,
+      });
+
+      // 收不到的卡不拖累整批，但**必须让前端能说出少了哪几张**。
+      // 静默少东西是导出最贵的失败方式：用户解压之后才发现，那时已经不知道
+      // 是哪一步丢的。
+      if (skipped.length) {
+        // ⚠️ 头要封顶。中文经 UTF-8 + 百分号编码大约 9 倍膨胀，100 条 skipped
+        // 实测 32KB —— nginx 默认 proxy_buffer_size 4k/8k，超了就是
+        // "upstream sent too big header" → **502，打好的 zip 一个字节都到不了用户**。
+        // 卡 id 长度也不设限的话，一个恶意长 id 单发就能触发。
+        const items = skipped.slice(0, 20).map(x => ({
+          cardId: String(x.cardId).slice(0, 120),
+          reason: String(x.reason).slice(0, 120),
+          status: x.status,
+        }));
+        let v = encodeURIComponent(JSON.stringify({ total: skipped.length, items }));
+        if (v.length > 4000) v = encodeURIComponent(JSON.stringify({ total: skipped.length, items: [] }));
+        res.setHeader('X-Export-Skipped', v);
+      }
+      res.setHeader('Content-Type', mime);
+      res.setHeader('Content-Disposition', `attachment; filename*=UTF-8''${encodeURIComponent(filename)}`);
+      res.setHeader('Content-Length', buffer.length);
+      res.end(buffer);
+      } finally {
+        // finally 不能漏：抛错时不减计数 = 闸门永久卡死，两次失败之后
+        // 这个功能就再也用不了了，而且重启前查不出原因
+        inflight -= 1;
+        inflightByProject.delete(project.id);
+      }
+    } catch (err) {
+      if (err.status) return res.status(err.status).json({ error: err.message });
+      next(err);
+    }
+  };
+}

package/server/api/exports/docx-pdf.js

@@ -0,0 +1,46 @@
+/**
+ * exports/docx-pdf.js — docx → PDF 导出。
+ *
+ * 单开一个文件而不是往 exports.js 的 pdf 路由里塞 if：那条路由整段是
+ * playwright + `<section data-page>` 的 deck 逻辑，docx 跟它一行代码都不共享
+ * （LibreOffice 直接出 PDF，没有分页 section 这回事）。
+ *
+ * ⚠️ 这里出的 PDF 跟用户在 Word 里「另存为 PDF」**不是同一个东西** —— 域
+ * （TOC）不更新、中文是替身字体。给用户下载时说清楚：要发出去的正式
+ * PDF，请在 Word 里导；这份是快速预览用的。
+ */
+
+import { renderDocx, cleanupRender } from '../../lib/docx/render.js';
+
+/**
+ * @param {import('express').Response} res
+ * @param {{absPath:string, relPath:string}} target
+ */
+export async function docxToPdfResponse(res, target) {
+  let out;
+  try {
+    out = await renderDocx(target.absPath, {});     // 只要 pdf，不出 png
+  } catch (err) {
+    return res.status(500).json({
+      error: 'LibreOffice 转换失败',
+      details: String(err.message || err).slice(0, 500),
+    });
+  }
+  try {
+    const { readFile } = await import('node:fs/promises');
+    const buf = await readFile(out.pdf);
+    const stem = target.relPath.replace(/\.docx$/i, '').split('/').pop() || '文档';
+    res.setHeader('Content-Type', 'application/pdf');
+    res.setHeader(
+      'Content-Disposition',
+      `attachment; filename*=UTF-8''${encodeURIComponent(`${stem}.pdf`)}`,
+    );
+    res.setHeader('Content-Length', buf.length);
+    // 让下载方知道这份 PDF 的成色，别拿它当正式稿发出去
+    res.setHeader('X-Docx-Pdf-Note', 'toc-field-not-updated; substituted-cjk-fonts');
+    res.end(buf);
+  } finally {
+    await cleanupRender(out);
+  }
+  return undefined;
+}

package/server/api/exports/export-page.js

@@ -0,0 +1,142 @@
+/**
+ * exports/export-page.js — deck 导出（PDF / PPTX / 单页 HTML）的共用底座。
+ *
+ * 2026-08-17 从 exports.js 搬出来。这两个函数是**纯辅助**，被 pdf / pptx /
+ * html 三条路由共用，本来就不该住在路由文件里。
+ *
+ * ⚠️ 上一次拆 exports.js（拆 handoff）时，它俩是被**误伤**带走的，`node --check`
+ * 和 vite build 都不报，只有 no-undef.lint 抓到了。这次是**故意**给它们安家，
+ * 顺带把那次事故的教训坐实成目录结构。
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { resolveDeckSize, extractDeckAspect } from '../../shared/deck.js';
+import { fitInjectionBlock } from '../standalone-fit.js';
+import { buildStandaloneHtml, isHybridHtml } from './build-standalone.js';
+
+/**
+ * 共用导出准备：启 Playwright page、等字体/图片就绪、注入基线 reset、探测实际 section 尺寸。
+ * 返回 { page, ctx, pageSize: { w, h } }。
+ *
+ * 多比例支持：先读 canvas.html 抽 wrap data-deck-aspect → 设对应 viewport
+ * （16:9=1920×1080 / 9:16=1080×1920 / 4:3=1440×1080）。
+ */
+export async function prepareExportPage(browser, filePath, opts = {}) {
+  const dpr = opts.dpr ?? 2;
+
+  // 读文件抽 deck 比例 → 决定 viewport
+  const html = await fs.readFile(filePath, 'utf8').catch(() => '');
+  const aspect = extractDeckAspect(html);
+  const dims = resolveDeckSize(aspect);
+
+  // 跑跟 /exports/html 同款 standalone 管道——把 Google Fonts / 本地图片 / CDN
+  // 全 inline，写到 tmp 文件让 Playwright 从那加载。这样 PDF/PPT 用的字体跟
+  // HTML 下载产物 1:1，不再依赖 server 能否 reach fonts.googleapis.com（国内
+  // 网络 / firewall 直接封死的话原方案 PDF 字体会无声 fallback 到系统字体）。
+  // hybrid 检测失败或 build 失败 → fallback 到原 file://，至少导出能跑通。
+  let loadPath = filePath;
+  let cleanup = async () => {};
+  if (isHybridHtml(html)) {
+    try {
+      const baked = await buildStandaloneHtml(html, { sessionRoot: opts.sessionRoot, baseDir: path.dirname(filePath) });
+      const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'nd-export-'));
+      const tmpFile = path.join(tmpDir, 'baked.html');
+      await fs.writeFile(tmpFile, baked, 'utf8');
+      loadPath = tmpFile;
+      cleanup = async () => { await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {}); };
+    } catch (err) {
+      console.warn('[prepareExportPage] standalone bake failed, loading raw canvas.html:', err.message);
+    }
+  }
+
+  const ctx = await browser.newContext({
+    viewport: { width: dims.width, height: dims.height },
+    deviceScaleFactor: dpr,
+  });
+  const page = await ctx.newPage();
+  await page.goto('file://' + loadPath, { waitUntil: 'networkidle', timeout: 30_000 });
+
+  // 字体强等待——比 await document.fonts.ready 严格得多。
+  //
+  // 背景：Google Fonts 把 CJK 字体（Noto Sans SC）拆成 80+ 个 unicode-range
+  // 子集，每个子集 + 每个 weight 是独立 @font-face。HTML 用 font-display: swap
+  // 的话浏览器先用 fallback 字体绘制，字体异步加载完后 swap。
+  //
+  // document.fonts.ready 只等"已经 pending 的"face——CSS 引用了但还没被使用
+  // 过的 face 不算 pending（lazy load 机制）。截图时若某个 weight × range
+  // 子集还没被触发，PDF/PPT 就截到 swap 前的 fallback 字体（preview 走 macOS
+  // 系统字体看着对，PPT/PDF 走 Linux Chromium 默认字体看着错）。
+  //
+  // 4 步保 ready：
+  //   1. 强制 layout（让所有字体使用注册到 FontFaceSet）
+  //   2. 显式 .load() 所有声明的 face（含未被使用的 weight × range 子集）
+  //   3. await document.fonts.ready（兜底等剩余 pending）
+  //   4. 双 rAF 等 paint 真正应用 swap
+  await page.evaluate(async () => {
+    document.body.offsetHeight;  // force layout
+    const faces = Array.from(document.fonts);
+    await Promise.all(faces.map((f) => f.load().catch(() => {})));
+    await document.fonts.ready;
+    await new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));
+  });
+  await page.waitForTimeout(200);  // 短兜底（rAF 后再给 paint 一帧时间）
+
+  // 抹掉 body margin + 砍掉 fit-active 视觉缩放（如果 file:// 加载的 canvas.html
+  // 有 standalone-fit script，frame 包装 + section transform: scale 会让 boundingBox
+  // 拿到的不是设计稿原坐标）。Playwright viewport 已经 = deck 比例，原生渲染。
+  await page.addStyleTag({ content: `
+    body { margin: 0 !important; padding: 0 !important; }
+    body.__nd-fit-active > .__nd-deck-wrap > .__nd-page-frame {
+      width: ${dims.width}px !important; height: ${dims.height}px !important;
+      display: block !important; overflow: visible !important;
+    }
+    body.__nd-fit-active section[data-page] { transform: none !important; }
+  ` });
+
+  const fallback = { w: dims.width, h: dims.height };
+  const pageSize = await page.evaluate((fb) => {
+    const first = document.querySelector('section[data-page]');
+    if (!first) return fb;
+    const rect = first.getBoundingClientRect();
+    return { w: Math.round(rect.width), h: Math.round(rect.height) };
+  }, fallback);
+
+  return { page, ctx, pageSize, cleanup };
+}
+
+/**
+ * 导出 HTML 时注入 viewport 自适应脚本（服务端兜底）。
+ *
+ * 逻辑：scale(viewportWidth / DECK.width) 让任意视口宽都满铺 + 完整。
+ * 仅在独立打开时生效（iframe 内 window!==top 早退，前端 CanvasFrame 自算 scale）。
+ *
+ * 行为升级（2026-05-08）：内部改调 server/api/standalone-fit.js 的 fitInjectionBlock()，
+ * 升级到 4 mode 感知（stack/ppt/carousel/custom）+ transform-origin: top left。
+ * 调用方零改动，老 deck（无 data-deck-mode attr）自动按 stack 兜底。
+ */
+export function injectViewportFit(html) {
+  // 1. 替换 agent 写的固定 viewport meta → 响应式 viewport（让 fit script 控）
+  if (/<meta\s+name=["']viewport["'][^>]*>/i.test(html)) {
+    html = html.replace(
+      /<meta\s+name=["']viewport["'][^>]*>/i,
+      '<meta name="viewport" content="width=device-width,initial-scale=1">',
+    );
+  } else if (html.includes('</head>')) {
+    html = html.replace(
+      '</head>',
+      '<meta name="viewport" content="width=device-width,initial-scale=1">\n</head>',
+    );
+  }
+
+  // 2. 调 standalone-fit 拼完整 fit injection block 注入
+  const block = fitInjectionBlock();
+  if (html.includes('</body>')) {
+    return html.replace('</body>', block + '\n</body>');
+  }
+  if (html.includes('</html>')) {
+    return html.replace('</html>', block + '\n</html>');
+  }
+  return html + block;
+}

package/server/api/exports/handoff.js

@@ -0,0 +1,147 @@
+/**
+ * api/exports/handoff.js — 旧的「工程交付包」打包逻辑（2026-08-17 从 exports.js 拆出）
+ *
+ * ⚠️ **这是旧口径，正在被 exports/cards.js 那条替换。** 它的已知毛病：
+ *   - `design/assets/` 把整个项目级 `shared/assets` 递归打包（最大的项目 280MB，
+ *     会把别的任务的图一起交出去）
+ *   - `prompt.txt` 恒空、`chat-history.json` 只有 runId 列表
+ *   - `spec.json` 是 agent 私域档案却进包，而真决策（notes/决策.md）反而没进
+ *   - README 是静态模板，不讲怎么跑 / 依赖 / 改哪里
+ *
+ * 拆出来是为了两件事：exports.js 贴着行数棘轮上限；以及把「待退役的那一坨」
+ * 圈在一个文件里，退役时整份删掉即可，不用在大文件里挑。
+ * MCP 工具 `export_handoff` 还在用它，退役要连那条一起换。
+ */
+
+import path from 'path';
+import { promises as fs } from 'fs';
+import JSZip from 'jszip';
+import { walkTaskFiles, loadIgnore } from '../../lib/task-scan.js';
+import { KIND_SITE } from '../../lib/artifact-target.js';
+
+/**
+ * 共享 handoff 打包逻辑 —— HTTP 路由 + MCP tool（export_handoff）共用。
+ *
+ * @param {string} sessionRoot  sessions/<sid>/ 绝对路径（canvas/spec 在这）
+ * @param {string} sharedRoot   shared/ 绝对路径（assets 在这）
+ */
+export async function buildHandoffZip(sessionRoot, sharedRoot, { projectId, projectName, skillId, sessionId, runs = [], deckPath = 'canvas.html', kind = null } = {}) {
+  const zip = new JSZip();
+  const isSite = kind === KIND_SITE;
+
+  if (isSite) {
+    // 站点：产物根整个进 design/，保留文件名与子目录 —— 只留入口页并改名叫
+    // canvas.html 的话，子页和 style.css 全丢，页间相对链接必然断。
+    // dirname(入口) 就是产物根（手写 = 任务根，构建型 = dist/）；忽略规则
+    // 从任务根读（.ndignore 住那），试作 `_drafts/` 不进交付包。
+    const artifactDirAbs = path.dirname(path.resolve(sessionRoot, deckPath));
+    // 忽略规则（.ndignore）住工作区根；构建型站点的产物根是 dist/，
+    // 规则却写在源那边，所以这两个目录必须分开取
+    const taskRootAbs = path.resolve(sessionRoot);
+    const siteFiles = await walkTaskFiles(artifactDirAbs, {
+      maxDepth: 6,
+      ignore: await loadIgnore(taskRootAbs),
+      ignoreBase: taskRootAbs,
+    });
+    for (const f of siteFiles) {
+      try { zip.file(`design/${f.rel}`, await fs.readFile(f.abs)); } catch { /* 中途被删就跳过 */ }
+    }
+    // 站内 html/css 的 `../../assets/` 归一（zip 布局是 design/<页面> + design/assets/）
+    for (const rel of Object.keys(zip.files)) {
+      if (zip.files[rel].dir || !/\.(html?|css)$/i.test(rel)) continue;
+      const depth = rel.split('/').length - 2;             // design/ 之下还有几层
+      const up = '../'.repeat(Math.max(0, depth));
+      const text = await zip.files[rel].async('string');
+      zip.file(rel, text.replace(/(["'(])(?:\.\.\/)+assets\//g, `$1${up}assets/`));
+    }
+  } else {
+    try {
+      // deckPath 相对 sessionRoot（任务模型下是 tasks/<任务>/canvas.html）
+      const raw = await fs.readFile(path.resolve(sessionRoot, deckPath), 'utf8');
+      // zip 里的布局是 design/canvas.html + design/assets/…，而任务 deck 写的是
+      // `../../assets/generated/x.png`（相对它在 workspace 里的位置）—— 不改写的话
+      // 解压出来图全裂。统一压成 `assets/…`。
+      const html = raw.replace(/(["'(])(?:\.\.\/)+assets\//g, '$1assets/');
+      zip.file('design/canvas.html', html);
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+      zip.file('design/canvas.html', '<!-- canvas.html not yet generated -->');
+    }
+  }
+
+  try {
+    const spec = await fs.readFile(path.join(sessionRoot, 'spec.json'), 'utf8');
+    zip.file('design/spec.json', spec);
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+
+  // assets 来自 shared/（跨 session 共享）—— 递归走子目录，
+  // 主要是 assets/generated/（generate_image MCP 落档处）必须进 zip，
+  // 否则 canvas.html 里的 <img src="assets/generated/..."> 在打开导出时全 404。
+  const assetsDir = path.join(sharedRoot, 'assets');
+  await zipDirRecursive(zip, assetsDir, 'design/assets');
+
+  const chatHistory = (runs || []).map((row) => ({ runId: row.id }));
+  zip.file('chat-history.json', JSON.stringify({ projectId, sessionId, runs: chatHistory }, null, 2));
+
+  zip.file('prompt.txt', '');
+  zip.file('README.md', renderReadme({ id: projectId, name: projectName, skillId, sessionId, kind }));
+
+  return zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+}
+
+/**
+ * 递归把 srcDir 下所有文件加进 zip（保留相对路径），dst 是 zip 内根前缀。
+ * srcDir 不存在时静默 noop（fail-soft）。子目录中的 dotfile / 软链按需可扩展。
+ */
+async function zipDirRecursive(zip, srcDir, dstPrefix, { skipDotfiles = false } = {}) {
+  let entries;
+  try {
+    entries = await fs.readdir(srcDir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return;
+    throw err;
+  }
+  for (const e of entries) {
+    if (skipDotfiles && e.name.startsWith('.')) continue;
+    const srcAbs = path.join(srcDir, e.name);
+    const dstRel = `${dstPrefix}/${e.name}`;
+    if (e.isDirectory()) {
+      await zipDirRecursive(zip, srcAbs, dstRel, { skipDotfiles });
+      continue;
+    }
+    if (!e.isFile()) continue;  // 跳软链 / fifo 等
+    const buf = await fs.readFile(srcAbs);
+    zip.file(dstRel, buf);
+  }
+}
+
+function renderReadme(project) {
+  return `# ${project.name}
+
+NoDesign 工程交付包。
+
+## 文件结构
+
+${project.kind === 'site' ? `- \`design/\` — 站点全部文件（保留原目录结构与文件名）
+- \`design/${'index.html'}\` — 入口页
+- \`design/assets/\` — 站点引用到的项目素材` : `- \`design/canvas.html\` — 单文件 self-contained HTML，主产物
+- \`design/assets/\` — 项目共享素材`}
+- \`design/spec.json\` — 设计意图档案（agent 私域记忆）
+- \`chat-history.json\` — runs 摘要
+- \`prompt.txt\` — 占位
+
+## 怎么用
+
+${project.kind === 'site' ? `把 \`design/\` 整个目录当站点根目录发布（任何静态托管都行），或者直接双击
+\`design/index.html\` 在本地浏览 —— 页面之间是相对链接，不依赖服务器。` : `直接在浏览器打开 \`design/canvas.html\` 看 deck。
+导出 PDF：用浏览器打印（${'${DECK.width}'}×${'${DECK.height}'} 视口最佳）。`}
+
+---
+导出时间：${new Date().toISOString()}
+项目 ID：${project.id}
+Session ID：${project.sessionId}
+Skill：${project.skillId}
+`;
+}