@xiaobuyu/nodesign 0.0.1 → 0.0.3

package/server/lib/reference-assets.js

@@ -1,92 +1,92 @@
-/**
- * server/lib/reference-assets.js — 参考素材清单（2026-08-18）
- *
- * `assets/references/**` 里的东西：web-search 下载的参考图、`browser_capture` 从
- * 参照站带回来的截图与调色板/字体/结构 json。
- *
- * ## 它们此前完全看不见，原因不是"kinds 不认图片"
- *
- * 图片有自己的 file-kind（`kinds/file-kinds.js`，IMAGE_EXTS 六种齐全）。真正的断点
- * 是**扫描根**：`api/assets.js` 的 `/assets` 端点只 readdir 顶层文件，而产物清单那遍
- * `scanDir` 用的是默认 `depth = 0`（`depth <= 0` 就不进子目录）——
- * `assets/generated` 和 `assets/notes` 能上墙只因为它们被**单独列了一行**，
- * `assets/references/` 没被列。所以修法是加一个扫描口，不是改形态注册表。
- *
- * ## 走抽屉不走画布（用户 2026-08-18 拍板）
- *
- * 每逛一站甩十几张卡到画布上是噪音，而 web-search 下载的参考图还会成倍冒出来
- * （它按 `count*2` 下载但只上报 `count` 张，磁盘上本来就有 agent 不知道的孤儿）。
- * 收进「参考素材」抽屉杂波小得多。
- */
-
-import path from 'node:path';
-import fs from 'node:fs/promises';
-
-/**
- * 最多下探几层：`references/`(0) → `web/`(1) → `<站名>/`(2) → 文件。
- *
- * ⭐ 2026-08-18 下午 +1：`browser_capture` 改成**一站一文件夹**（按站点产物那条
- * 范式：目录 = 单位）。深度不够的话整棵采集树在清单里凭空消失 —— 而"扫描根/深度
- * 不够"正是当初参考素材完全看不见的真因（见文件头），同一个坑别踩第二次。
- */
-const MAX_DEPTH = 3;
-
-/** 这份素材属于哪个参照站（`assets/references/web/<站名>/…` 的那一段） */
-function siteOf(rel) {
-  const m = /^assets\/references\/web\/([^/]+)\//.exec(rel);
-  return m ? m[1] : null;
-}
-
-/**
- * @param {string} assetsDir  `<工作区>/assets` 的绝对路径
- * @returns {Promise<Array<{rel,name,size,mtime,source?,lookingFor?,capturedAt?}>>}
- *   按 mtime 倒序。读不到就返回空数组 —— 素材列不出来不该让整份 /assets 响应失败。
- */
-export async function listReferences(assetsDir) {
-  const out = [];
-
-  const walk = async (dir, relPrefix, depth) => {
-    let ents;
-    try { ents = await fs.readdir(dir, { withFileTypes: true }); } catch { return; }
-    for (const e of ents) {
-      if (e.name === '.meta') continue;                     // sidecar 目录本身不列
-      if (e.isDirectory()) {
-        if (depth > 0) await walk(path.join(dir, e.name), `${relPrefix}/${e.name}`, depth - 1);
-        continue;
-      }
-      if (!e.isFile() || e.name.startsWith('.')) continue;
-      let st;
-      try { st = await fs.stat(path.join(dir, e.name)); } catch { continue; }
-
-      // 出处：照 generate-image 的 `.meta/<主干>.json` 约定读（不另发明一套）。
-      // 没有出处很正常 —— web-search 下载的那些本来就没写 sidecar。
-      let meta = null;
-      try {
-        const stem = e.name.replace(/\.[^.]+$/, '');
-        meta = JSON.parse(await fs.readFile(path.join(dir, '.meta', `${stem}.json`), 'utf8'));
-      } catch { /* 无出处 */ }
-
-      const rel = `${relPrefix}/${e.name}`;
-      out.push({
-        rel,
-        name: e.name,
-        site: siteOf(rel),
-        // 类别写在文件名里（`.screenshot.webp` / `.palette.json` / `.css` …），
-        // sidecar 里也记着一份 —— 文件名优先，它是用户和 agent 直接看到的那个
-        category: /\.(screenshot)\.\w+$/.test(e.name) ? 'screenshot'
-          : (/\.(palette|fonts|skeleton)\.json$/.exec(e.name)?.[1] || (e.name.endsWith('.css') ? 'css' : null)),
-        size: st.size,
-        mtime: st.mtime.toISOString(),
-        ...(meta ? {
-          source: meta.sourceUrl || null,
-          lookingFor: meta.lookingFor || null,
-          capturedAt: meta.capturedAt || null,
-        } : {}),
-      });
-    }
-  };
-
-  await walk(path.join(assetsDir, 'references'), 'assets/references', MAX_DEPTH);
-  out.sort((a, b) => (a.mtime < b.mtime ? 1 : -1));
-  return out;
-}
+/**
+ * server/lib/reference-assets.js — 参考素材清单（2026-08-18）
+ *
+ * `assets/references/**` 里的东西：web-search 下载的参考图、`browser_capture` 从
+ * 参照站带回来的截图与调色板/字体/结构 json。
+ *
+ * ## 它们此前完全看不见，原因不是"kinds 不认图片"
+ *
+ * 图片有自己的 file-kind（`kinds/file-kinds.js`，IMAGE_EXTS 六种齐全）。真正的断点
+ * 是**扫描根**：`api/assets.js` 的 `/assets` 端点只 readdir 顶层文件，而产物清单那遍
+ * `scanDir` 用的是默认 `depth = 0`（`depth <= 0` 就不进子目录）——
+ * `assets/generated` 和 `assets/notes` 能上墙只因为它们被**单独列了一行**，
+ * `assets/references/` 没被列。所以修法是加一个扫描口，不是改形态注册表。
+ *
+ * ## 走抽屉不走画布（用户 2026-08-18 拍板）
+ *
+ * 每逛一站甩十几张卡到画布上是噪音，而 web-search 下载的参考图还会成倍冒出来
+ * （它按 `count*2` 下载但只上报 `count` 张，磁盘上本来就有 agent 不知道的孤儿）。
+ * 收进「参考素材」抽屉杂波小得多。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+/**
+ * 最多下探几层：`references/`(0) → `web/`(1) → `<站名>/`(2) → 文件。
+ *
+ * ⭐ 2026-08-18 下午 +1：`browser_capture` 改成**一站一文件夹**（按站点产物那条
+ * 范式：目录 = 单位）。深度不够的话整棵采集树在清单里凭空消失 —— 而"扫描根/深度
+ * 不够"正是当初参考素材完全看不见的真因（见文件头），同一个坑别踩第二次。
+ */
+const MAX_DEPTH = 3;
+
+/** 这份素材属于哪个参照站（`assets/references/web/<站名>/…` 的那一段） */
+function siteOf(rel) {
+  const m = /^assets\/references\/web\/([^/]+)\//.exec(rel);
+  return m ? m[1] : null;
+}
+
+/**
+ * @param {string} assetsDir  `<工作区>/assets` 的绝对路径
+ * @returns {Promise<Array<{rel,name,size,mtime,source?,lookingFor?,capturedAt?}>>}
+ *   按 mtime 倒序。读不到就返回空数组 —— 素材列不出来不该让整份 /assets 响应失败。
+ */
+export async function listReferences(assetsDir) {
+  const out = [];
+
+  const walk = async (dir, relPrefix, depth) => {
+    let ents;
+    try { ents = await fs.readdir(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (e.name === '.meta') continue;                     // sidecar 目录本身不列
+      if (e.isDirectory()) {
+        if (depth > 0) await walk(path.join(dir, e.name), `${relPrefix}/${e.name}`, depth - 1);
+        continue;
+      }
+      if (!e.isFile() || e.name.startsWith('.')) continue;
+      let st;
+      try { st = await fs.stat(path.join(dir, e.name)); } catch { continue; }
+
+      // 出处：照 generate-image 的 `.meta/<主干>.json` 约定读（不另发明一套）。
+      // 没有出处很正常 —— web-search 下载的那些本来就没写 sidecar。
+      let meta = null;
+      try {
+        const stem = e.name.replace(/\.[^.]+$/, '');
+        meta = JSON.parse(await fs.readFile(path.join(dir, '.meta', `${stem}.json`), 'utf8'));
+      } catch { /* 无出处 */ }
+
+      const rel = `${relPrefix}/${e.name}`;
+      out.push({
+        rel,
+        name: e.name,
+        site: siteOf(rel),
+        // 类别写在文件名里（`.screenshot.webp` / `.palette.json` / `.css` …），
+        // sidecar 里也记着一份 —— 文件名优先，它是用户和 agent 直接看到的那个
+        category: /\.(screenshot)\.\w+$/.test(e.name) ? 'screenshot'
+          : (/\.(palette|fonts|skeleton)\.json$/.exec(e.name)?.[1] || (e.name.endsWith('.css') ? 'css' : null)),
+        size: st.size,
+        mtime: st.mtime.toISOString(),
+        ...(meta ? {
+          source: meta.sourceUrl || null,
+          lookingFor: meta.lookingFor || null,
+          capturedAt: meta.capturedAt || null,
+        } : {}),
+      });
+    }
+  };
+
+  await walk(path.join(assetsDir, 'references'), 'assets/references', MAX_DEPTH);
+  out.sort((a, b) => (a.mtime < b.mtime ? 1 : -1));
+  return out;
+}

package/server/lib/region-shot.js

@@ -1,135 +1,135 @@
-/**
- * lib/region-shot.js —— 把用户在预览上圈的那一块截下来。
- *
- * 为什么在服务端截而不是前端：产物是 iframe 里的**真实网页**，前端要把它变成
- * 位图只能靠 html2canvas 那类重写渲染器的库 —— 那玩意儿在有 3D、滤镜、
- * 自定义字体、伪元素的页面上出来的东西跟屏幕上不是一回事，而这张图恰恰是要
- * 给 agent 当"眼见为实"的证据用的。chromium 真跑一遍才是它自己的样子，
- * 而且这台机器上封面和 screenshot_canvas 早就是这么干的（lib/cover.js）。
- *
- * 取景：以圈为中心带一圈余量。只截圈内的话 agent 拿到一块没有上下文的碎片，
- * 分不清"这是页面哪儿"；余量给到它周围一点参照。
- */
-
-import path from 'node:path';
-import { openArtifactPage, launchPerceptionBrowser, degradedNote } from '../engine/mcp/tools/helpers/perception-page.js';
-import fs from 'node:fs/promises';
-
-/** 圈外多留这么多像素当上下文 */
-export const PADDING = 32;
-
-/** 出图长边上限，跟 screenshot 工具同口径（API 侧本来就会缩到这个规格） */
-export const OUT_LONG_EDGE = 1200;
-
-/** 截图串行：一台 1 核机器上同时开两个 chromium 会双双卡住 */
-let chain = Promise.resolve();
-function serialize(fn) {
-  const next = chain.then(fn, fn);
-  chain = next.catch(() => {});
-  return next;
-}
-
-/**
- * @param {object} p
- * @param {string} p.absPath   产物页面的绝对路径
- * @param {{x,y,w,h}} p.region 页面坐标（CSS px，含滚动量）
- * @param {{width,height}} p.viewport 用户当时的取景宽高
- * @param {string} [p.projectId]      有它就走 http（与用户预览同源）
- * @param {string} [p.workspaceRoot]  同上，两个都给才走 http
- * @returns {Promise<{ buffer: Buffer, clip: {x,y,width,height}, degraded: string|null }>}
- */
-export async function renderRegionShot({ absPath, region, viewport, projectId, workspaceRoot }) {
-  return serialize(async () => {
-    let browser;
-    try {
-      browser = await launchPerceptionBrowser();
-      // 圈选截的是**用户圈的那一块**，所以更要跟用户看到的同源：file:// 下
-      // fetch 回来的内容不会出现在图里，agent 会以为用户圈了一块空白。
-      const opened = await openArtifactPage(browser, {
-        projectId, workspaceRoot, absPath, viewport, deviceScaleFactor: 1, timeout: 20_000,
-      });
-      const ctx = opened.context;
-      const page = opened.page;
-      await opened.goto();
-      // 字体加载完再截（CJK 子集是 lazy 的，不显式 load 会截到 fallback 字形）
-      await page.evaluate(async () => {
-        document.body.offsetHeight;
-        await Promise.all(Array.from(document.fonts).map(f => f.load().catch(() => {})));
-        await document.fonts.ready;
-        await new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r)));
-      }).catch(() => { /* 页面自己抛错也照截 */ });
-      // deck 的 standalone-fit 会在真实 viewport 下再缩一次，抹掉（同 cover.js）
-      await page.addStyleTag({ content: `
-        body { margin: 0 !important; padding: 0 !important; }
-        body.__nd-fit-active > .__nd-deck-wrap > .__nd-page-frame {
-          width: ${viewport.width}px !important; height: ${viewport.height}px !important;
-          display: block !important; overflow: visible !important;
-        }
-        body.__nd-fit-active section[data-page] { transform: none !important; }
-      ` }).catch(() => {});
-      await page.waitForTimeout(500);
-
-      const want = {
-        x: Math.max(0, region.x - PADDING),
-        y: Math.max(0, region.y - PADDING),
-        w: region.w + PADDING * 2,
-        h: region.h + PADDING * 2,
-      };
-
-      // 滚到目标位置再按视口坐标裁。**滚动会被文档末尾夹住**，所以要把真实
-      // 落点读回来算裁剪框，不然页尾附近截出来的是错位的一块。
-      const scroll = await page.evaluate(([x, y]) => {
-        window.scrollTo(x, y);
-        const e = document.scrollingElement || document.documentElement;
-        return [e.scrollLeft, e.scrollTop];
-      }, [want.x, want.y]);
-
-      const clip = {
-        x: Math.max(0, want.x - scroll[0]),
-        y: Math.max(0, want.y - scroll[1]),
-        width: Math.min(want.w, viewport.width),
-        height: Math.min(want.h, viewport.height),
-      };
-      clip.width = Math.max(1, Math.min(clip.width, viewport.width - clip.x));
-      clip.height = Math.max(1, Math.min(clip.height, viewport.height - clip.y));
-
-      // ⚠️ 滚完要**等一拍**再截。上面那个 500ms 花在滚动**之前**，滚完立刻截 →
-      // 视口里新进来的懒加载图（`loading=lazy` / IntersectionObserver）还没解码，
-      // 图里是空的。而 `get_pending_changes` 把这张图当作"用户所见的 ground truth"
-      // 交给 agent —— 空白处会被当成"用户圈了一块空白"。
-      await page.evaluate(async () => {
-        // 给 IO 回调一次机会，再等两帧确保解码后的图上了屏
-        await new Promise(r => setTimeout(r, 250));
-        await Promise.all([...document.images].filter(i => !i.complete)
-          .map(i => new Promise((res) => { i.addEventListener('load', res, { once: true });
-            i.addEventListener('error', res, { once: true }); setTimeout(res, 1200); })));
-        await new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r)));
-      }).catch(() => { /* 页面自己抛错也照截 */ });
-
-      const png = await page.screenshot({ type: 'png', clip });
-      await ctx.close();
-
-      const { default: sharp } = await import('sharp');
-      const buffer = await sharp(png)
-        .resize({ width: OUT_LONG_EDGE, height: OUT_LONG_EDGE, fit: 'inside', withoutEnlargement: true })
-        .webp({ quality: 82 })
-        .toBuffer();
-      // note 非空 = 没走成 http。圈选截图尤其在意这个：file:// 下 fetch 回来的
-      // 内容不会出现在图里，而这张图是被当"ground truth"用的
-      return { buffer, clip, degraded: degradedNote(opened) };
-    } finally {
-      await browser?.close().catch(() => {});
-    }
-  });
-}
-
-/** 圈选截图在会话工作区里的落点（agent 按这个相对路径找得到） */
-export const SHOT_DIR = 'region-shots';
-
-export async function saveRegionShot(sessionRoot, id, buffer) {
-  const dir = path.join(sessionRoot, SHOT_DIR);
-  await fs.mkdir(dir, { recursive: true });
-  const rel = `${SHOT_DIR}/${id}.webp`;
-  await fs.writeFile(path.join(sessionRoot, rel), buffer);
-  return rel;
-}
+/**
+ * lib/region-shot.js —— 把用户在预览上圈的那一块截下来。
+ *
+ * 为什么在服务端截而不是前端：产物是 iframe 里的**真实网页**，前端要把它变成
+ * 位图只能靠 html2canvas 那类重写渲染器的库 —— 那玩意儿在有 3D、滤镜、
+ * 自定义字体、伪元素的页面上出来的东西跟屏幕上不是一回事，而这张图恰恰是要
+ * 给 agent 当"眼见为实"的证据用的。chromium 真跑一遍才是它自己的样子，
+ * 而且这台机器上封面和 screenshot_canvas 早就是这么干的（lib/cover.js）。
+ *
+ * 取景：以圈为中心带一圈余量。只截圈内的话 agent 拿到一块没有上下文的碎片，
+ * 分不清"这是页面哪儿"；余量给到它周围一点参照。
+ */
+
+import path from 'node:path';
+import { openArtifactPage, launchPerceptionBrowser, degradedNote } from '../engine/mcp/tools/helpers/perception-page.js';
+import fs from 'node:fs/promises';
+
+/** 圈外多留这么多像素当上下文 */
+export const PADDING = 32;
+
+/** 出图长边上限，跟 screenshot 工具同口径（API 侧本来就会缩到这个规格） */
+export const OUT_LONG_EDGE = 1200;
+
+/** 截图串行：一台 1 核机器上同时开两个 chromium 会双双卡住 */
+let chain = Promise.resolve();
+function serialize(fn) {
+  const next = chain.then(fn, fn);
+  chain = next.catch(() => {});
+  return next;
+}
+
+/**
+ * @param {object} p
+ * @param {string} p.absPath   产物页面的绝对路径
+ * @param {{x,y,w,h}} p.region 页面坐标（CSS px，含滚动量）
+ * @param {{width,height}} p.viewport 用户当时的取景宽高
+ * @param {string} [p.projectId]      有它就走 http（与用户预览同源）
+ * @param {string} [p.workspaceRoot]  同上，两个都给才走 http
+ * @returns {Promise<{ buffer: Buffer, clip: {x,y,width,height}, degraded: string|null }>}
+ */
+export async function renderRegionShot({ absPath, region, viewport, projectId, workspaceRoot }) {
+  return serialize(async () => {
+    let browser;
+    try {
+      browser = await launchPerceptionBrowser();
+      // 圈选截的是**用户圈的那一块**，所以更要跟用户看到的同源：file:// 下
+      // fetch 回来的内容不会出现在图里，agent 会以为用户圈了一块空白。
+      const opened = await openArtifactPage(browser, {
+        projectId, workspaceRoot, absPath, viewport, deviceScaleFactor: 1, timeout: 20_000,
+      });
+      const ctx = opened.context;
+      const page = opened.page;
+      await opened.goto();
+      // 字体加载完再截（CJK 子集是 lazy 的，不显式 load 会截到 fallback 字形）
+      await page.evaluate(async () => {
+        document.body.offsetHeight;
+        await Promise.all(Array.from(document.fonts).map(f => f.load().catch(() => {})));
+        await document.fonts.ready;
+        await new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r)));
+      }).catch(() => { /* 页面自己抛错也照截 */ });
+      // deck 的 standalone-fit 会在真实 viewport 下再缩一次，抹掉（同 cover.js）
+      await page.addStyleTag({ content: `
+        body { margin: 0 !important; padding: 0 !important; }
+        body.__nd-fit-active > .__nd-deck-wrap > .__nd-page-frame {
+          width: ${viewport.width}px !important; height: ${viewport.height}px !important;
+          display: block !important; overflow: visible !important;
+        }
+        body.__nd-fit-active section[data-page] { transform: none !important; }
+      ` }).catch(() => {});
+      await page.waitForTimeout(500);
+
+      const want = {
+        x: Math.max(0, region.x - PADDING),
+        y: Math.max(0, region.y - PADDING),
+        w: region.w + PADDING * 2,
+        h: region.h + PADDING * 2,
+      };
+
+      // 滚到目标位置再按视口坐标裁。**滚动会被文档末尾夹住**，所以要把真实
+      // 落点读回来算裁剪框，不然页尾附近截出来的是错位的一块。
+      const scroll = await page.evaluate(([x, y]) => {
+        window.scrollTo(x, y);
+        const e = document.scrollingElement || document.documentElement;
+        return [e.scrollLeft, e.scrollTop];
+      }, [want.x, want.y]);
+
+      const clip = {
+        x: Math.max(0, want.x - scroll[0]),
+        y: Math.max(0, want.y - scroll[1]),
+        width: Math.min(want.w, viewport.width),
+        height: Math.min(want.h, viewport.height),
+      };
+      clip.width = Math.max(1, Math.min(clip.width, viewport.width - clip.x));
+      clip.height = Math.max(1, Math.min(clip.height, viewport.height - clip.y));
+
+      // ⚠️ 滚完要**等一拍**再截。上面那个 500ms 花在滚动**之前**，滚完立刻截 →
+      // 视口里新进来的懒加载图（`loading=lazy` / IntersectionObserver）还没解码，
+      // 图里是空的。而 `get_pending_changes` 把这张图当作"用户所见的 ground truth"
+      // 交给 agent —— 空白处会被当成"用户圈了一块空白"。
+      await page.evaluate(async () => {
+        // 给 IO 回调一次机会，再等两帧确保解码后的图上了屏
+        await new Promise(r => setTimeout(r, 250));
+        await Promise.all([...document.images].filter(i => !i.complete)
+          .map(i => new Promise((res) => { i.addEventListener('load', res, { once: true });
+            i.addEventListener('error', res, { once: true }); setTimeout(res, 1200); })));
+        await new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r)));
+      }).catch(() => { /* 页面自己抛错也照截 */ });
+
+      const png = await page.screenshot({ type: 'png', clip });
+      await ctx.close();
+
+      const { default: sharp } = await import('sharp');
+      const buffer = await sharp(png)
+        .resize({ width: OUT_LONG_EDGE, height: OUT_LONG_EDGE, fit: 'inside', withoutEnlargement: true })
+        .webp({ quality: 82 })
+        .toBuffer();
+      // note 非空 = 没走成 http。圈选截图尤其在意这个：file:// 下 fetch 回来的
+      // 内容不会出现在图里，而这张图是被当"ground truth"用的
+      return { buffer, clip, degraded: degradedNote(opened) };
+    } finally {
+      await browser?.close().catch(() => {});
+    }
+  });
+}
+
+/** 圈选截图在会话工作区里的落点（agent 按这个相对路径找得到） */
+export const SHOT_DIR = 'region-shots';
+
+export async function saveRegionShot(sessionRoot, id, buffer) {
+  const dir = path.join(sessionRoot, SHOT_DIR);
+  await fs.mkdir(dir, { recursive: true });
+  const rel = `${SHOT_DIR}/${id}.webp`;
+  await fs.writeFile(path.join(sessionRoot, rel), buffer);
+  return rel;
+}

package/server/lib/safe-path.js

@@ -1,73 +1,73 @@
-/**
- * lib/safe-path.js — 工作区内路径的越界检查。
- *
- * ⚠️ **词法检查不够。** `path.resolve` + `path.relative` 挡得住 `../..`，
- * 挡不住工作区里一个**指向外面的软链** —— 那条路径逐字看都在工作区内，
- * 解引用之后在 `/etc` 或者 `.env` 上。
- *
- * 这个洞在这个仓库里已经出现过两次形状相同的实例（导出收集器、docx 页图路由），
- * 第二次是照着第一次的**调用形状**抄的、没抄它的**正确性**。所以判据收成一份：
- * 谁要在工作区里按用户给的相对路径开文件，就 import 这里，别再各写一遍。
- *
- * 读和写的判据不一样，分两个函数：
- *   - 读：目标必须存在，realpath 之后仍在工作区内
- *   - 写：目标可能还不存在（正要创建），所以查**父目录**的 realpath；
- *     另外目标自己若已经是软链，一律拒 —— 顺着它写等于把别人的文件覆盖掉
- */
-
-import path from 'node:path';
-import { promises as fs } from 'node:fs';
-
-/** 词法层：拼出绝对路径并确认字面上没跑出去。跑出去返回 null */
-function lexical(rootAbs, rel) {
-  const abs = path.resolve(rootAbs, String(rel || ''));
-  const within = path.relative(rootAbs, abs);
-  if (within.startsWith('..') || path.isAbsolute(within)) return null;
-  return abs;
-}
-
-/**
- * 读用：解析一个工作区内的相对路径。
- * @returns {Promise<string|null>} 绝对路径；越界（含软链穿透）返回 null
- *   目标不存在**不算越界** —— 让调用方自己去 stat 报 404，这里只管边界
- */
-export async function safeResolveRead(workspaceRoot, rel) {
-  const abs = lexical(path.resolve(workspaceRoot), rel);
-  if (!abs) return null;
-  try {
-    const realRoot = await fs.realpath(workspaceRoot);
-    const real = await fs.realpath(abs);
-    const rw = path.relative(realRoot, real);
-    if (rw.startsWith('..') || path.isAbsolute(rw)) return null;
-  } catch (err) {
-    // ENOENT：文件还没写出来，边界上没问题，留给调用方 stat
-    if (err?.code !== 'ENOENT') return null;
-  }
-  return abs;
-}
-
-/**
- * 写用：解析一个工作区内的写入目标。
- * @returns {Promise<string|null>} 绝对路径；越界 / 目标是软链 返回 null
- */
-export async function safeResolveWrite(workspaceRoot, rel) {
-  const abs = lexical(path.resolve(workspaceRoot), rel);
-  if (!abs) return null;
-  try {
-    const realRoot = await fs.realpath(workspaceRoot);
-    // 目标本身若已存在且是软链 → 拒。顺着它写会覆盖软链指向的那个文件，
-    // 而那个文件可以在工作区外（lstat 不解引用，这是判据的关键）
-    try {
-      if ((await fs.lstat(abs)).isSymbolicLink()) return null;
-    } catch (err) {
-      if (err?.code !== 'ENOENT') return null;   // 目标还不存在是正常的
-    }
-    // 父目录必须真的在工作区内（父目录是软链的话，新建的文件会落到外面）
-    const realParent = await fs.realpath(path.dirname(abs));
-    const rw = path.relative(realRoot, realParent);
-    if (rw.startsWith('..') || path.isAbsolute(rw)) return null;
-  } catch {
-    return null;   // 父目录都解析不了，不给写
-  }
-  return abs;
-}
+/**
+ * lib/safe-path.js — 工作区内路径的越界检查。
+ *
+ * ⚠️ **词法检查不够。** `path.resolve` + `path.relative` 挡得住 `../..`，
+ * 挡不住工作区里一个**指向外面的软链** —— 那条路径逐字看都在工作区内，
+ * 解引用之后在 `/etc` 或者 `.env` 上。
+ *
+ * 这个洞在这个仓库里已经出现过两次形状相同的实例（导出收集器、docx 页图路由），
+ * 第二次是照着第一次的**调用形状**抄的、没抄它的**正确性**。所以判据收成一份：
+ * 谁要在工作区里按用户给的相对路径开文件，就 import 这里，别再各写一遍。
+ *
+ * 读和写的判据不一样，分两个函数：
+ *   - 读：目标必须存在，realpath 之后仍在工作区内
+ *   - 写：目标可能还不存在（正要创建），所以查**父目录**的 realpath；
+ *     另外目标自己若已经是软链，一律拒 —— 顺着它写等于把别人的文件覆盖掉
+ */
+
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+
+/** 词法层：拼出绝对路径并确认字面上没跑出去。跑出去返回 null */
+function lexical(rootAbs, rel) {
+  const abs = path.resolve(rootAbs, String(rel || ''));
+  const within = path.relative(rootAbs, abs);
+  if (within.startsWith('..') || path.isAbsolute(within)) return null;
+  return abs;
+}
+
+/**
+ * 读用：解析一个工作区内的相对路径。
+ * @returns {Promise<string|null>} 绝对路径；越界（含软链穿透）返回 null
+ *   目标不存在**不算越界** —— 让调用方自己去 stat 报 404，这里只管边界
+ */
+export async function safeResolveRead(workspaceRoot, rel) {
+  const abs = lexical(path.resolve(workspaceRoot), rel);
+  if (!abs) return null;
+  try {
+    const realRoot = await fs.realpath(workspaceRoot);
+    const real = await fs.realpath(abs);
+    const rw = path.relative(realRoot, real);
+    if (rw.startsWith('..') || path.isAbsolute(rw)) return null;
+  } catch (err) {
+    // ENOENT：文件还没写出来，边界上没问题，留给调用方 stat
+    if (err?.code !== 'ENOENT') return null;
+  }
+  return abs;
+}
+
+/**
+ * 写用：解析一个工作区内的写入目标。
+ * @returns {Promise<string|null>} 绝对路径；越界 / 目标是软链 返回 null
+ */
+export async function safeResolveWrite(workspaceRoot, rel) {
+  const abs = lexical(path.resolve(workspaceRoot), rel);
+  if (!abs) return null;
+  try {
+    const realRoot = await fs.realpath(workspaceRoot);
+    // 目标本身若已存在且是软链 → 拒。顺着它写会覆盖软链指向的那个文件，
+    // 而那个文件可以在工作区外（lstat 不解引用，这是判据的关键）
+    try {
+      if ((await fs.lstat(abs)).isSymbolicLink()) return null;
+    } catch (err) {
+      if (err?.code !== 'ENOENT') return null;   // 目标还不存在是正常的
+    }
+    // 父目录必须真的在工作区内（父目录是软链的话，新建的文件会落到外面）
+    const realParent = await fs.realpath(path.dirname(abs));
+    const rw = path.relative(realRoot, realParent);
+    if (rw.startsWith('..') || path.isAbsolute(rw)) return null;
+  } catch {
+    return null;   // 父目录都解析不了，不给写
+  }
+  return abs;
+}