@xiaobuyu/nodesign 0.0.1

package/server/lib/artifact-file-path.js

@@ -0,0 +1,80 @@
+/**
+ * server/lib/artifact-file-path.js — artifact-file 的路径判据（2026-08-18 抽出）
+ *
+ * 抽出来的直接原因是行数棘轮，但抽对了：这几行是**安全判据**，而且它有一条已知的
+ * 错（见下面 `tasks/` 那段），judge 类的东西住在路由里没法单测。
+ *
+ * 可服务根 = 整个项目工作区（产物就住在这儿），但挡掉基础设施：`.claude/`（含
+ * settings.json 和整份 SDK 转录）、`.nd/`（会话私档）、`.git/`。扁平化之前这三样
+ * 都在可服务根之外、是目录结构在替我们把门；现在它们跟产物同级，必须显式拦 ——
+ * 否则 `artifact-file/.claude/settings.json` 是一个能公开读到配置的 URL。
+ *
+ * 点开头**一刀切拒是错的**：缩略图住在 `assets/generated/.thumbnails/`，一刀切下去
+ * 产物墙上所有缩略图全 403。所以按名字白名单（不是黑名单 —— 将来冒出个 `.env`
+ * 不该因为没人想到就漏出去）。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { safeResolveRead } from './safe-path.js';
+
+const DOT_OK = new Set(['.thumbnails', '.meta']);
+
+/**
+ * 这个绝对路径可不可以服出去：不越界、且路径里没有非白名单的点目录。
+ *
+ * 导出它是因为**改名转发**那条路要用同一个判据（`api/assets.js` 里原来自己又抄了
+ * 一遍 DOT_OK 和越界检查）。判据抄第二遍就是等着哪天改一处漏一处 ——
+ * 收成一份，两边都 import。
+ */
+export function isServablePath(sharedRoot, absPath) {
+  if (absPath !== sharedRoot && !absPath.startsWith(sharedRoot + path.sep)) return false;
+  const rel = path.relative(sharedRoot, absPath).split(path.sep);
+  return !rel.some(seg => seg.startsWith('.') && !DOT_OK.has(seg));
+}
+
+/**
+ * @param {string} sharedRootRaw 项目工作区根
+ * @param {string} rawSub 路由里的 *subPath（可能是数组段拼起来的）
+ * @returns {Promise<{ok:true, sharedRoot:string, absPath:string, subPath:string}
+ *   | {ok:false, status:number, error:string}>}
+ */
+export async function resolveArtifactFile(sharedRootRaw, rawSub) {
+  let subPath = Array.isArray(rawSub) ? rawSub.join('/') : (rawSub || '');
+  if (!subPath) return { ok: false, status: 400, error: 'file path required' };
+
+  const sharedRoot = path.resolve(sharedRootRaw);
+
+  // 兼容旧形态：`tasks/<任务>/x` 是扁平化之前的路径，浏览器缓存里、旧 board.json 里、
+  // 用户收藏的链接里都还有。剥掉前两段就是现在的位置。
+  // ⚠️ **但不能无条件剥**（2026-08-18 审查抓到）：扁平化之后 agent 完全可以在工作区里
+  // 真建一个叫 `tasks/` 的目录（它就是个普通名字），那时候剥掉前两段会把**磁盘上真实
+  // 存在的文件**变成 404。所以先看原路径在不在，在就别动它。
+  const asIs = path.resolve(sharedRoot, subPath);
+  const insideAsIs = asIs === sharedRoot || asIs.startsWith(sharedRoot + path.sep);
+  if (/^tasks\/[^/]+\//.test(subPath)) {
+    let existsAsIs = false;
+    if (insideAsIs) {
+      try { await fs.stat(asIs); existsAsIs = true; } catch { /* 不在 */ }
+    }
+    if (!existsAsIs) subPath = subPath.replace(/^tasks\/[^/]+\//, '');
+  }
+
+  // ⛔ **纯词法的 `path.resolve` 挡不住软链**。真攻过（2026-08-18）：在工作区里
+  // `ln -s /path/to/.env x.html`，`GET artifact-file/x.html` 回 **200 且字节数与
+  // .env 一字不差**。而这条路由今天更热了（感知通道走它、常驻浏览器的 cookie jar
+  // 也住在工作区里），并且**它跑在 server 主进程、沙盒管不着**。
+  //
+  // 仓库里早就有正确实现 `safe-path.js` 的 `safeResolveRead`（realpath 复核，
+  // ENOENT 不算越界）。照那条教训：**去掉第二份判据而不是添第三份**
+  // （[[feedback-copied-guard-shape]]：抄守卫要抄正确性不是形状 —— 08-17 同一天
+  // 栽两次，第二次就是抄了调用形状没抄 realpath 复核）。
+  const absPath = await safeResolveRead(sharedRoot, subPath);
+  if (!absPath) {
+    return { ok: false, status: 403, error: 'path escapes workspace (symlinks are resolved before the check)' };
+  }
+  if (!isServablePath(sharedRoot, absPath)) {
+    return { ok: false, status: 403, error: 'not a servable path' };
+  }
+  return { ok: true, sharedRoot, absPath, subPath };
+}

package/server/lib/artifact-target.js

@@ -0,0 +1,284 @@
+/**
+ * artifact-target.js — 产物寻址（2026-07-28 由 canvas-target.js 泛化；
+ * 2026-07-29 形态判定与解析下沉到 kinds/ 注册表；2026-08-07 任务层退役）
+ *
+ * 定死三件事：
+ *
+ * **① 产物有形态（kind），文件就是真相。** 判定规则在 kinds/ 注册表：
+ *    canvas.html → deck；index.html（工作区根 / 声明的产物根 / 约定构建目录）
+ *    → site。
+ *
+ * **② 寻址永远带着 kind 一起返回。** 下游（截图 / 分页 / 导出 / fit 注入）必须
+ *    能看见"这是 deck 还是 site"，才可能给出对的行为。kind 每次 resolve 按工作区
+ *    现状重算，不缓存。
+ *
+ * **③ 源和产物可以分开。** 构建型站点的源在工作区根、产物在 dist/ 之类的产物根。
+ *    resolve 返回 workspaceRoot（源，agent 的地盘）和 artifactDir（被预览 / 导出 /
+ *    发布的根），deck 和手写站点两者相同。消费方要"看"产物就用 artifactDir，
+ *    别再自己 dirname(entryPath)。
+ *
+ * 寻址顺序（越靠前越明确）：
+ *   ① 调用方显式给的 path
+ *   ② 本会话的"当前产物"——最近写过 / 截过 / 预览过哪份就是哪份
+ *   ③ 工作区只有一份产物就是它；多份就报错列出来让调用方指定
+ *
+ * ## 2026-08-07：第 ③ 条曾经是第 ④ 条
+ *
+ * 中间夹着一条「认领绑在本会话名下那个任务」——`tasks/<任务>/.nd-task.json`
+ * 里记着 sessionId，寻址时按当前会话去反查它的任务。那条规则存在的前提是
+ * **一个项目里有多个任务、而每个任务属于一个会话**；线上数据说这个前提从来
+ * 没成立过（13 个有产物的项目，每个都恰好一个任务）。
+ *
+ * 任务层拆掉之后，"这个会话的产物"这个问题本身就没有意义了 —— 产物属于项目，
+ * 谁开的对话都看得见同一批。剩下的歧义（工作区里有多份产物、调用方没说哪份）
+ * 由 ② 的最近使用和 ③ 的显式报错解决，这两条本来就在，而且不依赖任何绑定。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import {
+  KINDS, kindDef, readTaskMarker, taskManifest, artifactOfPath, can,
+} from './kinds/index.js';
+
+export const KIND_DECK = 'deck';
+export const KIND_SITE = 'site';
+
+/** 每种形态的入口文件名（从注册表派生；改形态契约去 kinds/） */
+export const ENTRY_FILE = Object.freeze(
+  Object.fromEntries(Object.values(KINDS).map(k => [k.id, k.entryFile])),
+);
+
+/**
+ * 产物入口**长什么样**（扩展名集合），同样从注册表派生。
+ * `.html` / `.htm` 是 deck+site 的形状，`.docx` 是 word 的 —— 加形态时这里
+ * 自动跟上，不用再回来补一条正则。
+ */
+const ENTRY_EXTS = new Set(
+  Object.values(KINDS)
+    .map(k => (k.entryFile.match(/\.[a-z0-9]+$/i) || [''])[0].toLowerCase())
+    .filter(Boolean)
+    .concat('.htm'),   // html 的老写法，注册表里只写了 .html
+);
+
+// 形态判定与解析的权威在 kinds/，这里转发老名字（消费方 import 不用改两次）
+export { readTaskMarker, taskManifest, kindDef, artifactOfPath };
+export { formatAllowed, docxClaimedFiles, isDirArtifact } from './kinds/index.js';
+export { can };
+
+/** sessionId → { path, kind }。会话结束不清也无妨（几个短字符串） */
+const activeArtifact = new Map();
+
+/**
+ * 记住这个会话正在做哪份产物（写文件 / 截图 / 预览时调）。
+ *
+ * 只认**产物入口的形状**（ENTRY_EXTS，从注册表派生）。以前还认"任务内的非
+ * html"（改 style.css 也算在这个任务上干活，寻址时走任务入口），任务层没了之后
+ * 那一支失去了落点：改 `style.css` 说明不了在做哪一份 deck，工作区根上可能并排
+ * 放着好几份。认不出来就不认，让 resolve 走"只有一份就是它 / 多份报错"那条 ——
+ * 比猜一个错的默认目标强。
+ */
+export function setActiveArtifact(sessionId, relPath, kind) {
+  if (!sessionId || typeof relPath !== 'string') return;
+  const p = normalizeRel(relPath);
+  if (/\.template\.(html?|css)$/i.test(p)) return;   // 模板不是产物
+  const ext = (p.match(/\.[a-z0-9]+$/i) || [''])[0].toLowerCase();
+  if (!ENTRY_EXTS.has(ext)) return;
+  activeArtifact.set(sessionId, { path: p, kind: kind || null });
+}
+
+export function getActiveArtifact(sessionId) {
+  return (sessionId && activeArtifact.get(sessionId)) || null;
+}
+
+export function clearActiveArtifact(sessionId) {
+  activeArtifact.delete(sessionId);
+}
+
+function normalizeRel(p) {
+  return String(p).replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+async function exists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+/** workspace 内才算数（resolve 不出根） */
+function insideWorkspace(workspaceRoot, absPath) {
+  const root = path.resolve(workspaceRoot);
+  return absPath === root || absPath.startsWith(root + path.sep);
+}
+
+/**
+ * 站点的页面清单（相对产物根）。
+ */
+export async function listSitePages(workspaceRoot) {
+  const m = await KINDS[KIND_SITE].manifest(workspaceRoot, null);
+  return m.pages;
+}
+
+/**
+ * 推断某个 html 路径的产物形态。
+ *
+ * 多产物平权：canvas.html 跟一个根站并存时仍然是 deck、about.html 是站点子页 ——
+ * 同名文件形态可以不同，问 artifacts 清单而不是猜文件名。清单里找不到（文件
+ * 还没写出来）才退回文件名约定。
+ */
+export async function kindOfPath(workspaceRoot, relPath) {
+  const p = normalizeRel(relPath);
+  const base = path.posix.basename(p);
+  const m = await taskManifest(workspaceRoot);
+  if (m) {
+    const art = artifactOfPath(m, p);
+    if (art) return art.kind;
+    if (m.kind) return m.kind;
+  }
+  if (base === ENTRY_FILE[KIND_DECK]) return KIND_DECK;
+  if (base === ENTRY_FILE[KIND_SITE]) return KIND_SITE;
+  // 清单里没有（文件还没写出来）时按扩展名回退。.docx 只可能是 word 形态，
+  // 让它落进 deck 会让感知层拿 playwright 去开一个二进制包。
+  const ext = (p.match(/\.[a-z0-9]+$/i) || [''])[0].toLowerCase();
+  const byExt = Object.values(KINDS).find(k => k.entryFile.toLowerCase().endsWith(ext) && ext !== '.html');
+  if (byExt) return byExt.id;
+  return KIND_DECK;   // 认不出的散装 .html 一律按 deck
+}
+
+/** 这个工作区现有的产物入口（平权，没有主次） */
+export async function listWorkspaceArtifacts(workspaceRoot) {
+  const m = await taskManifest(workspaceRoot);
+  return (m?.artifacts || []).map(a => ({ rel: a.entryRel, kind: a.kind }));
+}
+
+/** 兼容旧名：只要 deck 那些 */
+export async function listWorkspaceDecks(workspaceRoot) {
+  return (await listWorkspaceArtifacts(workspaceRoot))
+    .filter(a => a.kind === KIND_DECK)
+    .map(a => a.rel);
+}
+
+/**
+ * 解析产物目标。
+ *
+ * @param {string} workspaceRoot
+ * @param {string|null} relPath   调用方显式给的路径（优先级最高）
+ * @param {string|null} sessionId
+ * @returns {Promise<{ ok: true, absPath: string, relPath: string, kind: 'deck'|'site',
+ *                     task: string|null, taskDir: string|null,
+ *                     artifactDir: string|null, artifactRel: string|null }
+ *                  | { ok: false, message: string }>}
+ *   taskDir      源（任务根，agent 的地盘）
+ *   artifactDir  产物根（被预览 / 导出 / 发布的目录）；deck 和手写站点 = taskDir
+ */
+export async function resolveArtifactTarget(workspaceRoot, relPath, sessionId) {
+  const decorate = async (rel) => {
+    const p = normalizeRel(rel);
+    // 按所属产物定 kind 和产物根（多产物平权：canvas.html 是 deck、
+    // v2/index.html 是另一个站，root 各归各）
+    let kind = null;
+    let root = '';
+    let artifact = null;
+    const m = await taskManifest(workspaceRoot);
+    if (m) {
+      artifact = artifactOfPath(m, p);
+      if (artifact) { kind = artifact.kind; root = artifact.root || ''; }
+      else if (m.kind) { kind = m.kind; root = m.root || ''; }
+    }
+    if (!kind) kind = await kindOfPath(workspaceRoot, p);
+    return {
+      ok: true,
+      absPath: path.resolve(workspaceRoot, p),
+      relPath: p,
+      kind,
+      // task / taskDir 保留成兼容字段：任务层没了，"源目录"永远是工作区根。
+      // 下游有十几处读 taskDir 当"agent 的地盘"，给它对的值比改十几处安全。
+      task: null,
+      taskDir: workspaceRoot,
+      artifact,   // 所属产物条目（manifest.artifacts 里那条；散文件为 null）
+      artifactDir: root ? path.join(workspaceRoot, root) : workspaceRoot,
+      artifactRel: root || '.',
+    };
+  };
+
+  const tryPath = async (rel) => {
+    if (!rel) return null;
+    const abs = path.resolve(workspaceRoot, rel);
+    if (!insideWorkspace(workspaceRoot, abs)) return null;
+    return (await exists(abs)) ? decorate(rel) : null;
+  };
+
+  if (relPath) {
+    const hit = await tryPath(relPath);
+    if (hit) { setActiveArtifact(sessionId, hit.relPath, hit.kind); return hit; }
+    const abs = path.resolve(workspaceRoot, relPath);
+    return {
+      ok: false,
+      message: insideWorkspace(workspaceRoot, abs)
+        ? `${relPath} not found. Write it first, or check the path.`
+        : 'path escapes workspace',
+    };
+  }
+
+  const active = getActiveArtifact(sessionId);
+  if (active?.path) {
+    const activeHit = await tryPath(active.path);
+    if (activeHit) return activeHit;
+  }
+
+  const all = await listWorkspaceArtifacts(workspaceRoot);
+  if (all.length === 1) {
+    setActiveArtifact(sessionId, all[0].rel, all[0].kind);
+    return decorate(all[0].rel);
+  }
+  if (all.length > 1) {
+    return {
+      ok: false,
+      message: 'Multiple artifacts in this workspace — pass path explicitly:\n'
+        + all.map(a => `- ${a.rel}  (${a.kind})`).join('\n'),
+    };
+  }
+  return {
+    ok: false,
+    message: 'No artifact found. Deck = canvas.html, site = index.html — '
+      + 'write one first, or pass path explicitly.',
+  };
+}
+
+/**
+ * 浏览器类工具的统一闸门：目标形态不能用浏览器打开就别往下走。
+ *
+ * 用法是 resolveCanvasTarget 之后立刻过一道：
+ *   const target = await resolveCanvasTarget(...);
+ *   if (!target.ok) return err(target.message);
+ *   const gate = requireBrowsable(target);
+ *   if (gate) return err(gate);
+ *
+ * 不把它塞进 resolveArtifactTarget 内部，是因为导出、寻址这些**正当**需要拿到
+ * 不可浏览目标的调用方也走那个函数，在源头拦会误伤。
+ *
+ * @returns {string|null} 不可浏览时返回给 agent 的说明，可浏览返回 null
+ */
+export function requireBrowsable(target) {
+  if (!target?.kind || can(target.kind, 'browsable')) return null;
+  const who = target.relPath || target.kind;
+  // 可渲染形态（docx）要给对路的替代方案。说"直接 Read 它的文件"是**错的建议**
+  // —— 那是个二进制 zip，Read 出来是乱码，而它其实是**看得见**的，只是要先渲染。
+  if (can(target.kind, 'renderable')) {
+    return `${who} 是 ${target.kind} 形态，没有 DOM，读页面 / 查元素 / 取计算样式这几个工具对它无效。`
+      + '看长相用 screenshot（它会渲染成页图，可以带 pages 参数指定范围）；'
+      + '看结构读它的 token 源（同名 .json），别去 Read 那个 .docx 本身，它是二进制包。';
+  }
+  return `${who} 是 ${target.kind} 形态，没有可以用浏览器打开的入口，`
+    + '截图 / 读页面 / 查元素这类工具对它没有意义。直接 Read 它的文件。';
+}
+
+/** 给各工具复用的 path 参数描述（保持措辞一致） */
+export const ARTIFACT_PATH_DESC =
+  'Relative path of the artifact entry (deck: "canvas.html", site: "index.html" '
+  + 'or its built output like "dist/index.html", word: "文档.docx"). '
+  + 'Omit to use the artifact you are currently working on.';
+
+// ── 兼容层：老名字继续可用，内部全部走上面的实现 ────────────────────────────
+export const CANVAS_PATH_DESC = ARTIFACT_PATH_DESC;
+export const resolveCanvasTarget = resolveArtifactTarget;
+export const setActiveDeck = (sessionId, relPath) => setActiveArtifact(sessionId, relPath);
+export const getActiveDeck = (sessionId) => getActiveArtifact(sessionId)?.path || null;
+export const clearActiveDeck = clearActiveArtifact;

package/server/lib/asset-refs.js

@@ -0,0 +1,239 @@
+/**
+ * lib/asset-refs.js — 产物真正引用到了哪些素材（2026-08-17）
+ *
+ * 为什么要这个：旧的工程交付包把**整个** `shared/assets` 递归塞进 zip。那是
+ * **项目级**共享目录，不是这份产物引用的东西 —— 生产上最大的一个项目 assets
+ * 有 280MB，导出一份 deck 会把项目里每一张图（包括别的任务的）一起交出去。
+ *
+ * 所以改成扫引用：产物的 html/css/js 里写了哪些素材，就带哪些。
+ *
+ * ⚠️ **扫不到的一律不猜，但必须说出来。** 静态引用是确定的；算不出来的（动态拼
+ * 路径、脚本里的字面量、`<base href>` 改了解析基准）**不往包里多塞**，而是记进
+ * `unresolved` 由调用方写成清单放进包里。用户拍的板：宁可在纸面上说清缺什么，
+ * 也不靠多塞蒙混过去。**「既不进包也不进清单」是这条规矩里最坏的状态** —— 那是
+ * 假装没这回事，比多塞还糟。
+ *
+ * ── 2026-08-17 评审后重写，六条实测出来的病（每条都有单测钉着）──
+ *   1. `<script src="x.js">` 随整块脚本被摘掉 → 真引用静默丢失
+ *   2. HTML 注释里的旧引用照收 → 别的任务的图混进包
+ *   3. `src="it's.png"` 用混合字符类解析 → 幻影路径 `it`
+ *   4. `file:` 之类 scheme 漏过滤（原来是枚举表）→ 幻影 ref
+ *   5. 脚本里的字面量素材（`['a.png','b.png']`）既不进包也不进清单
+ *   6. 树外引用全域放行 → `<a href="../别的任务/x.html">` 把别人的产物收进来
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+/** 会被扫的文本类型（二进制不扫） */
+const SCANNABLE = /\.(html?|css|jsx?|mjs|cjs)$/i;
+
+/**
+ * 不是本地素材的引用。**用泛化判据不用枚举表** —— 枚举表漏一个 scheme（`file:`）
+ * 就会产出幻影 ref。代价是 `x:30.png` 这种带冒号的文件名会被当 scheme 滤掉，
+ * 但浏览器本来也按 scheme 解析它，滤掉才是对齐浏览器语义。
+ */
+const EXTERNAL = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i;
+
+/**
+ * 静态引用的抓取规则。
+ *
+ * ⚠️ **引号必须分支写**（`"([^"]*)"|'([^']*)'`），不能用 `["']([^"']+)["']` 那种
+ * 混合字符类：后者遇到 `src="it's.png"` 会在撇号处截断，抓出幻影 `it`。
+ * ⚠️ 属性名前的 `(?<![.\w-])` 挡的是 JS 里的 `img.src = '...'` —— 没有它，属性
+ * 规则会把代码里的赋值当成 HTML 属性，同样抓出幻影。
+ */
+/**
+ * **只对标记语言成立**的规则。`src=` / `href=` 是 HTML 属性 —— 拿它去扫 .js
+ * 会把 `const data = 'hello world'` 当成引用，捞出幻影路径 `站/hello world`
+ * 塞进 missing，交付物里印出假警报（实测踩过）。
+ */
+const MARKUP_PATTERNS = [
+  /(?<![.\w-])(?:src|href|poster|data-src|data)\s*=\s*(?:"([^"]*)"|'([^']*)')/gi,
+  /\bsrcset\s*=\s*(?:"([^"]*)"|'([^']*)')/gi,
+];
+
+/** 在 html / css / js 里语义都成立的规则 */
+const UNIVERSAL_PATTERNS = [
+  /url\(\s*(?:"([^"]*)"|'([^']*)'|([^'")][^)]*?))\s*\)/gi,
+  /@import\s+(?:"([^"]*)"|'([^']*)')/gi,
+  /\bfrom\s+["']([^"']+\.(?:css|png|jpe?g|webp|gif|svg))["']/gi,
+  // `new URL('x.png', import.meta.url)` 的第一个参数是**字面量**，静态可判，
+  // 不该只当成"算不出来"记进清单。
+  /new\s+URL\s*\(\s*(?:"([^"]*)"|'([^']*)')\s*,\s*import\.meta\.url/gi,
+];
+
+/** 从一次匹配里取出那个真正被捕获的分支 */
+function capturedOf(m) {
+  for (let i = 1; i < m.length; i++) if (m[i] != null) return m[i];
+  return null;
+}
+
+/**
+ * 摘掉脚本体但**保留开标签** —— `<script src="lib/chart.js"></script>` 里的 src
+ * 是真引用，整块摘掉会静默丢失它（实测踩过）。
+ */
+const SCRIPT_BLOCK = /(<script\b[^>]*>)[\s\S]*?<\/script>/gi;
+/** HTML 注释：里面的引用是历史残留，收进来就是把别的任务的旧图打进包 */
+const HTML_COMMENT = /<!--[\s\S]*?-->/g;
+/** CSS / JS 的块注释。**不摘 `//` 行注释** —— 会误杀 `https://` */
+const BLOCK_COMMENT = /\/\*[\s\S]*?\*\//g;
+
+/** 动态拼路径：抓到只报告不解析 */
+const DYNAMIC_HINTS = [
+  { re: /["'][^"']*assets\/[^"']*["']\s*\+/gi,        why: '字符串拼接' },
+  { re: /`[^`]*assets\/[^`]*\$\{[^`]*`/gi,            why: '模板字符串插值' },
+  { re: /\+\s*["'][^"']*\.(?:png|jpe?g|webp|gif|svg|mp4)["']/gi, why: '字符串拼接' },
+];
+
+/** 脚本里的素材字面量（画廊 / lightbox 的常见写法），只进清单不进包 */
+const SCRIPT_LITERAL = /["'`]([^"'`\n]{1,200}\.(?:png|jpe?g|webp|gif|svg|mp4|webm|pdf|woff2?))["'`]/gi;
+
+/** 去掉查询串和锚点（`x.webp?w=480` → `x.webp`）、反斜杠归一、URL 解码 */
+function cleanRef(raw) {
+  const s = String(raw).trim().replace(/\\/g, '/').split('#')[0].split('?')[0];
+  try { return decodeURIComponent(s); } catch { return s; }
+}
+
+/** srcset 拆成一组候选：`a.png 1x, b.png 2x` → ['a.png','b.png'] */
+function splitSrcset(value) {
+  return value.split(',').map(part => part.trim().split(/\s+/)[0]).filter(Boolean);
+}
+
+/**
+ * 扫一批产物文件，收出它们引用到的素材。
+ *
+ * @param {object} opts
+ * @param {Array<{abs:string, rel:string}>} opts.files  要扫的文件（rel 相对 baseRoot）
+ * @param {string}   opts.baseRoot       解析基准（工作区根）。返回的路径都相对它
+ * @param {string[]} [opts.allowPrefixes] 允许收的前缀白名单（树外只认这些，通常是
+ *   产物自己的根 + `assets/`）。**留空 = 不设闸**（根层产物就是这种情况，它的树
+ *   本来就是整个工作区）。被挡下的引用不静默丢，进 unresolved。
+ * @returns {Promise<{refs:string[], unresolved:Array<{from,why,snippet}>}>}
+ */
+export async function collectAssetRefs({ files, baseRoot, allowPrefixes = [] }) {
+  const own = new Set(files.map(f => f.rel.replace(/\\/g, '/')));
+  const refs = new Set();
+  const unresolved = [];
+  const candidates = [];              // 脚本里的字面量，等调用方按"磁盘上真有"再提升
+  const seenHint = new Set();          // 同一句话被多条规则命中时去重
+
+  const pushHint = (from, why, snippet) => {
+    const s = String(snippet).replace(/\s+/g, ' ').slice(0, 120);
+    const key = `${from}|${s}`;
+    if (seenHint.has(key)) return;
+    seenHint.add(key);
+    unresolved.push({ from, why, snippet: s });
+  };
+
+  const allowed = (rel) => {
+    if (!allowPrefixes.length) return true;
+    return allowPrefixes.some(p => (p === '' ? true : rel === p || rel.startsWith(p)));
+  };
+
+  for (const f of files) {
+    if (!SCANNABLE.test(f.rel)) continue;
+    let text;
+    try { text = await fs.readFile(f.abs, 'utf8'); } catch { continue; }
+
+    const fileDirAbs = path.dirname(f.abs);
+    const isMarkup = /\.html?$/i.test(f.rel);
+    const isScript = /\.(m?js|cjs|jsx)$/i.test(f.rel);
+    // 静态引用只在「非注释、非脚本体」的部分找；动态线索照旧扫全文
+    const staticText = text
+      .replace(HTML_COMMENT, ' ')
+      .replace(BLOCK_COMMENT, ' ')
+      .replace(SCRIPT_BLOCK, '$1</script>');
+
+    for (const pattern of (isMarkup ? [...MARKUP_PATTERNS, ...UNIVERSAL_PATTERNS] : UNIVERSAL_PATTERNS)) {
+      pattern.lastIndex = 0;
+      let m;
+      while ((m = pattern.exec(staticText)) !== null) {
+        const captured = capturedOf(m);
+        if (captured == null) continue;
+        const isSrcset = /srcset/i.test(pattern.source);
+        for (const c of (isSrcset ? splitSrcset(captured) : [captured])) {
+          if (!c || EXTERNAL.test(c.trim())) continue;
+          const cleaned = cleanRef(c);
+          if (!cleaned || cleaned.startsWith('/')) continue;   // 根路径引用平台本来就禁
+          const abs = path.resolve(fileDirAbs, cleaned);
+          const rel = path.relative(baseRoot, abs).replace(/\\/g, '/');
+          if (!rel || rel.startsWith('..')) continue;          // 逃出工作区的不收
+          if (own.has(rel)) continue;                          // 产物自己的页面不算素材
+          if (!allowed(rel)) {
+            pushHint(f.rel, '引用落在产物树外（只有 assets/ 和产物自己的目录会进包）', cleaned);
+            continue;
+          }
+          refs.add(rel);
+        }
+      }
+    }
+
+    // `<base href>` 会改写整页相对路径的解析基准，扫描器按文件目录解析就会整体偏移
+    if (/<base\b[^>]*\bhref/i.test(text)) {
+      pushHint(f.rel, '页面有 <base href>，本页所有相对引用的解析基准可能跟打包时算的不一样', '<base href=…>');
+    }
+
+    for (const { re, why } of DYNAMIC_HINTS) {
+      re.lastIndex = 0;
+      let m;
+      while ((m = re.exec(text)) !== null) pushHint(f.rel, why, m[0]);
+    }
+
+    // 脚本里的素材字面量（画廊 / lightbox 的常见写法）。
+    // **完整字面量是静态可判的**，所以不直接判死：能落进工作区、又过得了树外闸的
+    // 交给调用方按「磁盘上真有这个文件」提升成素材；剩下的才进清单。
+    // 这不违反「扫不到的不多塞」—— 它扫得到，只是来源是脚本而不是标签。
+    const scanLiterals = (body) => {
+      SCRIPT_LITERAL.lastIndex = 0;
+      let lit;
+      while ((lit = SCRIPT_LITERAL.exec(body)) !== null) {
+        const cleaned = cleanRef(lit[1]);
+        const snippet = lit[0].slice(0, 120);
+        if (!cleaned || EXTERNAL.test(cleaned) || cleaned.startsWith('/')) {
+          pushHint(f.rel, '脚本里的字符串字面量（打包时不解析）', snippet); continue;
+        }
+        const rel = path.relative(baseRoot, path.resolve(fileDirAbs, cleaned)).replace(/\\/g, '/');
+        if (!rel || rel.startsWith('..') || own.has(rel) || !allowed(rel)) {
+          pushHint(f.rel, '脚本里的字符串字面量（打包时不解析）', snippet); continue;
+        }
+        candidates.push({ rel, from: f.rel, snippet });
+      }
+    };
+    // ⚠️ 从**剥过注释**的文本里取脚本体：标签侧早就剥了注释，字面量侧漏剥的话，
+    // 注释里的旧图会被提升进包 —— 同一条规矩两个半边，只修一半等于没修。
+    const commentFree = text.replace(HTML_COMMENT, ' ');
+    for (const sm of commentFree.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/gi)) scanLiterals(sm[1]);
+    // ⚠️ 独立的 .js 文件**整个就是脚本体**，没有 <script> 标签可匹配。
+    // 不加这条的话，同一份画廊代码写在 HTML 里能收、抽成 js 文件就双失踪。
+    if (isScript) scanLiterals(text.replace(BLOCK_COMMENT, ' '));
+  }
+
+  return { refs: [...refs].sort(), candidates, unresolved };
+}
+
+/**
+ * 把 unresolved 渲染成放进包里的清单。没有动态引用时返回 null（不放空文件 ——
+ * 旧交付包里那个常年空着的 prompt.txt 就是这么来的）。
+ */
+export function renderUnresolvedReport(unresolved) {
+  if (!unresolved?.length) return null;
+  const lines = [
+    '# 没能解析的素材引用',
+    '',
+    '下面这些地方打包时算不出具体引用了哪个文件，**素材可能没进包**。',
+    '如果打开后有图裂了，照这个清单去原工程里找对应文件补进来。',
+    '',
+  ];
+  const byFile = new Map();
+  for (const u of unresolved) {
+    if (!byFile.has(u.from)) byFile.set(u.from, []);
+    byFile.get(u.from).push(u);
+  }
+  for (const [file, items] of [...byFile.entries()].sort()) {
+    lines.push(`## ${file}`, '');
+    for (const it of items) lines.push(`- （${it.why}）\`${it.snippet}\``);
+    lines.push('');
+  }
+  return lines.join('\n');
+}