comate-ui-inspector 0.1.6-alpha.2 → 0.1.6-alpha.3

package/bridge/server.mjs

@@ -6,7 +6,7 @@
  * ~/.ui-inspector/*.json。浏览器扩展（transport=http）直连本服务。
  */
 import {createServer} from 'node:http';
-import {readFileSync, writeFileSync, appendFileSync, mkdirSync} from 'node:fs';
+import {readFileSync, writeFileSync, appendFileSync, mkdirSync, readdirSync, rmSync} from 'node:fs';
 import {dirname, resolve} from 'node:path';
 import {homedir} from 'node:os';
 
@@ -17,6 +17,8 @@ const recordingFile = resolve(homedir(), '.ui-inspector/recording.json');
 const eventsFile = resolve(homedir(), '.ui-inspector/recording-events.ndjson');
 // figma「带入对话」采集的节点结构。
 const figmaPendingFile = resolve(homedir(), '.ui-inspector/figma-pending.json');
+// figma 节点内导出的图片字节落盘到这里（按采集批次分子目录）。
+const figmaAssetsDir = resolve(homedir(), '.ui-inspector/figma-assets');
 const PORT = Number(process.env.UI_INSPECTOR_BRIDGE_PORT) || 8917;
 const HOST = process.env.UI_INSPECTOR_BRIDGE_HOST || '127.0.0.1';
 
@@ -84,10 +86,89 @@ function recStop(endedAt) {
 }
 
 // figma 节点采集：追加到 figma-pending.json（上限 10 个，防爆）。
+function sanitizeName(name) {
+    return (
+        String(name || 'image')
+            .replace(/[^a-zA-Z0-9._-]+/g, '_')
+            .replace(/^_+|_+$/g, '')
+            .slice(0, 60) || 'image'
+    );
+}
+
+// 清理旧的图片批次：保留当前仍在 figma-pending.json 里引用的批次目录（尚未被消费的节点），
+// 其余（已被 hook 注入消费、或被挤出 pending 的）全部删除。只在新一次导出时触发——「下次导出 PNG 才删上次的」。
+function pruneStaleAssets() {
+    let keep = new Set();
+    try {
+        const list = JSON.parse(readFileSync(figmaPendingFile, 'utf8'));
+        for (const entry of Array.isArray(list) ? list : []) {
+            const imgs = (entry && entry.node && entry.node.images) || [];
+            for (const im of imgs) {
+                if (im && im.file) {
+                    keep.add(dirname(im.file));
+                }
+            }
+        }
+    } catch {
+        keep = new Set();
+    }
+    let dirs = [];
+    try {
+        dirs = readdirSync(figmaAssetsDir);
+    } catch {
+        return; // 目录不存在，无需清理
+    }
+    for (const name of dirs) {
+        const full = resolve(figmaAssetsDir, name);
+        if (!keep.has(full)) {
+            try {
+                rmSync(full, {recursive: true, force: true});
+            } catch {
+                // 删除失败忽略
+            }
+        }
+    }
+}
+
+// 把 node.images 里的 base64 落成本地 PNG 文件，node 只保留 {file,name,id,width,height}，避免 json 膨胀。
+function persistImages(node) {
+    if (!node || !Array.isArray(node.images) || !node.images.length) {
+        if (node) {
+            delete node.images;
+        }
+        return;
+    }
+    pruneStaleAssets();
+    const batch = resolve(figmaAssetsDir, `${Date.now()}`);
+    mkdirSync(batch, {recursive: true});
+    const used = {};
+    const saved = [];
+    node.images.forEach((img, i) => {
+        if (!img || !img.base64) {
+            return;
+        }
+        let base = sanitizeName(img.name) + '-' + i;
+        if (used[base]) {
+            base += '_' + used[base]++;
+        } else {
+            used[base] = 1;
+        }
+        const file = resolve(batch, `${base}.png`);
+        try {
+            writeFileSync(file, Buffer.from(img.base64, 'base64'));
+            saved.push({id: img.id, name: img.name, width: img.width, height: img.height, file});
+        } catch {
+            // 单张落盘失败跳过
+        }
+    });
+    node.images = saved;
+}
+
 function figmaCapture(node) {
     if (!node) {
         return;
     }
+    persistImages(node);
     let list = [];
     try {
         const p = JSON.parse(readFileSync(figmaPendingFile, 'utf8'));

package/enhancements/figma/figma-exec.js

@@ -1,7 +1,9 @@
 /*
  * Figma 命令执行器（MAIN world，figma.com）：响应「带入对话」——把当前选中节点转成 F2C HTML 结构，
- * 回传给 figma-ui 落盘待 hook 注入。页面内已解锁的 window.figma / window.F2CConverter 由
- * rewrite.js + browser.global.js 提供。
+ * 并把节点内的图片（IMAGE 填充 / 图片节点）用 exportAsync 导出为 PNG，一并回传给 figma-ui 落盘待 hook 注入。
+ * F2CConverter 的 convertFigmaNodeToHtml 强制 withoutImages，HTML 里的图片只是占位路径、没有字节，
+ * 所以图片要我们自己走 window.figma 的 exportAsync 取。页面内已解锁的 window.figma / window.F2CConverter
+ * 由 rewrite.js + browser.global.js 提供。
  */
 (function () {
     if (window.__oreateFigmaExec) {
@@ -9,6 +11,9 @@
     }
     window.__oreateFigmaExec = true;
 
+    var MAX_IMAGES = 20; // 单次最多导出的图片数，防爆
+    var SCALE = 2; // 导出倍率，兼顾清晰度与体积
+
     function resolveNode() {
         var fig = window.figma;
         if (!fig) {
@@ -21,6 +26,109 @@
         throw new Error('未选中节点：请先在画布选中一个节点');
     }
 
+    // 该节点自身是否「携带图片」：IMAGE 类型节点，或 fills 里有可见的 IMAGE 填充。
+    function hasImage(node) {
+        if (!node) {
+            return false;
+        }
+        if (node.type === 'IMAGE') {
+            return true;
+        }
+        var fills;
+        try {
+            fills = node.fills;
+        } catch (e) {
+            return false;
+        }
+        if (!Array.isArray(fills)) {
+            return false; // figma.mixed 或不支持 fills
+        }
+        return fills.some(function (f) {
+            return f && f.type === 'IMAGE' && f.visible !== false;
+        });
+    }
+
+    // 深度遍历子树，收集携带图片的节点（含根自身），按先序、去重、限量。
+    function collectImageNodes(root) {
+        var out = [];
+        var seen = {};
+        var stack = [root];
+        while (stack.length && out.length < MAX_IMAGES) {
+            var n = stack.shift();
+            if (!n || seen[n.id]) {
+                continue;
+            }
+            seen[n.id] = true;
+            if (hasImage(n)) {
+                out.push(n);
+            }
+            var kids;
+            try {
+                kids = n.children;
+            } catch (e) {
+                kids = null;
+            }
+            if (Array.isArray(kids)) {
+                // 保持先序：子节点插到队首前面
+                stack = kids.concat(stack);
+            }
+        }
+        return out;
+    }
+
+    function toBase64(bytes) {
+        if (window.figma && typeof window.figma.base64Encode === 'function') {
+            try {
+                return window.figma.base64Encode(bytes);
+            } catch (e) {
+                /* 落到下面手工编码 */
+            }
+        }
+        var bin = '';
+        for (var i = 0; i < bytes.length; i++) {
+            bin += String.fromCharCode(bytes[i]);
+        }
+        return btoa(bin);
+    }
+
+    async function exportImages(root) {
+        var nodes = collectImageNodes(root);
+        var images = [];
+        for (var i = 0; i < nodes.length; i++) {
+            var n = nodes[i];
+            try {
+                var bytes = await n.exportAsync({format: 'PNG', constraint: {type: 'SCALE', value: SCALE}});
+                images.push({
+                    id: n.id,
+                    name: n.name || 'image-' + i,
+                    type: n.type,
+                    width: Math.round(n.width || 0),
+                    height: Math.round(n.height || 0),
+                    format: 'PNG',
+                    base64: toBase64(bytes),
+                });
+            } catch (e) {
+                // 单张导出失败不影响其余（部分节点可能不可导出）
+            }
+        }
+        return images;
+    }
+
+    // 把整个选中节点导出成一张 PNG（用于开发页「走查」覆盖层）。width/height 是节点的 CSS 像素尺寸，
+    // 覆盖层按此宽度 1:1 显示即与设计稿同像素。导出倍率 SCALE 保证高清。
+    async function exportSnapshot(root) {
+        try {
+            var bytes = await root.exportAsync({format: 'PNG', constraint: {type: 'SCALE', value: SCALE}});
+            return {
+                base64: toBase64(bytes),
+                width: Math.round(root.width || 0),
+                height: Math.round(root.height || 0),
+            };
+        } catch (e) {
+            return null;
+        }
+    }
+
     window.addEventListener('message', function (ev) {
         if (ev.source !== window || !ev.data || ev.data.__uiInspectorFigmaCapture !== true) {
             return;
@@ -32,11 +140,15 @@
                 }
                 var node = resolveNode();
                 var html = await window.F2CConverter.convertFigmaNodeToHtml(node, {});
+                var images = await exportImages(node);
+                var snapshot = await exportSnapshot(node);
                 return {
                     nodeId: node.id,
                     name: node.name,
                     type: node.type,
                     html: typeof html === 'string' ? html : JSON.stringify(html),
+                    images: images,
+                    snapshot: snapshot,
                 };
             })
             .then(function (node) {

package/enhancements/figma/figma-ui.js

@@ -50,13 +50,36 @@
         if (!alive()) {
             return;
         }
+        const node = payload.node || {};
+        // 整节点快照只给开发页「走查」覆盖层用，存 chrome.storage.local，不随 figma-capture 进 figma-pending.json。
+        const snap = node.snapshot;
+        delete node.snapshot;
+        if (snap && snap.base64) {
+            try {
+                chrome.storage.local.set(
+                    {
+                        figmaOverlay: {
+                            dataUrl: 'data:image/png;base64,' + snap.base64,
+                            width: snap.width,
+                            height: snap.height,
+                            name: node.name || node.nodeId,
+                            ts: Date.now(),
+                        },
+                    },
+                    () => void chrome.runtime.lastError
+                );
+            } catch {
+                // 存储失败不影响带入
+            }
+        }
         try {
-            chrome.runtime.sendMessage({type: 'figma-capture', node: payload.node}, resp => {
+            chrome.runtime.sendMessage({type: 'figma-capture', node: node}, resp => {
                 if (chrome.runtime.lastError || !resp || !resp.ok) {
                     toast('落盘失败，请重试', false);
                     return;
                 }
-                toast(`已带入「${payload.node.name || payload.node.nodeId}」，去 Comate 发消息即可生成代码`, true);
+                const extra = snap ? '，已可在开发页点「走查」覆盖' : '';
+                toast(`已带入「${node.name || node.nodeId}」${extra}，去 Comate 发消息即可生成代码`, true);
             });
         } catch {
             toast('扩展上下文失效，请刷新页面', false);

package/enhancements/figma/pane.html

@@ -8,6 +8,20 @@
     class="hint"
     style="margin-top: 6px"
 ></div>
+<div style="margin-top: 10px">
+    <button
+        id="figma-walkthrough"
+        class="primary"
+        style="width: 100%"
+    >
+        走查
+    </button>
+    <div
+        id="figma-walkthrough-status"
+        class="hint"
+        style="margin-top: 4px"
+    ></div>
+</div>
 <div
     class="hint"
     style="margin-top: 6px"

package/enhancements/figma/pane.js

@@ -1,17 +1,70 @@
 /*
- * Figma 增强包弹窗面板：只做状态提示。真正的注入在 figma.com 页面内由 rewrite.js + browser.global.js
- * （MAIN world，document_start）完成；导出能力（节点→HTML/图片）由后续的命令通道 + MCP 工具提供。
+ * Figma 增强包弹窗面板：
+ *  1) 显示 figma.com 授权状态；
+ *  2)「走查」按钮——把上次带入的整节点快照覆盖到当前开发页面，供像素级比对。
+ *     真正的注入在 figma.com 页面内由 rewrite.js + browser.global.js（MAIN world）完成；
+ *     覆盖层由开发页的 bridge-content.js 渲染，这里只负责向当前活动 tab 发切换消息。
  */
 (function () {
     const el = document.getElementById('figma-status');
-    if (!el) {
+    if (el) {
+        chrome.permissions.contains({origins: ['https://www.figma.com/*']}, granted => {
+            if (chrome.runtime.lastError) {
+                return;
+            }
+            el.textContent = granted ? '✓ 已授权 figma.com，打开设计稿即生效' : '✗ 尚未授权 figma.com';
+            el.style.color = granted ? '#1a7f37' : '#cf222e';
+        });
+    }
+
+    const btn = document.getElementById('figma-walkthrough');
+    const status = document.getElementById('figma-walkthrough-status');
+    if (!btn) {
         return;
     }
-    chrome.permissions.contains({origins: ['https://www.figma.com/*']}, granted => {
+
+    function setStatus(text, ok) {
+        if (!status) {
+            return;
+        }
+        status.textContent = text;
+        status.style.color = ok === false ? '#cf222e' : ok ? '#1a7f37' : '#656d76';
+    }
+
+    // 有没有可用的快照（提示用户先去 figma 带入节点）。
+    chrome.storage.local.get({figmaOverlay: null}, o => {
         if (chrome.runtime.lastError) {
             return;
         }
-        el.textContent = granted ? '✓ 已授权 figma.com，打开设计稿即生效' : '✗ 尚未授权 figma.com';
-        el.style.color = granted ? '#1a7f37' : '#cf222e';
+        if (!o || !o.figmaOverlay) {
+            setStatus('还没有可走查的节点，先去 Figma 点「带入 Comate 生成代码」');
+        } else {
+            setStatus(`已就绪：${o.figmaOverlay.name || '节点'}（${o.figmaOverlay.width}×${o.figmaOverlay.height}）`);
+        }
     });
+
+    btn.onclick = () => {
+        chrome.tabs.query({active: true, currentWindow: true}, tabs => {
+            const tab = tabs && tabs[0];
+            if (!tab || !tab.id) {
+                setStatus('找不到当前标签页', false);
+                return;
+            }
+            try {
+                chrome.tabs.sendMessage(tab.id, {type: 'toggle-figma-overlay'}, resp => {
+                    if (chrome.runtime.lastError) {
+                        setStatus('当前页面未注入脚本（确认是已授权的开发域名并已刷新）', false);
+                        return;
+                    }
+                    if (!resp || !resp.ok) {
+                        setStatus((resp && resp.error) || '切换失败', false);
+                        return;
+                    }
+                    setStatus(resp.shown ? '已覆盖到页面，可拖拽/缩放/调透明度' : '已关闭覆盖层', true);
+                });
+            } catch (e) {
+                setStatus(String(e), false);
+            }
+        });
+    };
 })();

package/extension/bridge-content.js

@@ -178,6 +178,169 @@
         // 上下文失效
     }
 
+    // ---------- Figma 走查覆盖层（popup 点「走查」→ 这里把带入的整节点快照覆盖到页面）----------
+    // 覆盖层容器只放图片并整体调透明度；工具条单独一层（始终不透明、可操作），避免被透明度一起吃掉。
+    var ov = null;
+    var ovImg = null;
+    var ovBar = null;
+    var ovs = {x: 40, y: 40, scale: 1, opacity: 0.5, baseW: 0, through: false};
+    var dragFrom = null;
+
+    function ovRemove() {
+        if (ov) {
+            ov.remove();
+            ov = null;
+            ovImg = null;
+        }
+        if (ovBar) {
+            ovBar.remove();
+            ovBar = null;
+        }
+        document.removeEventListener('mousemove', ovDrag);
+        document.removeEventListener('mouseup', ovDragEnd);
+    }
+
+    function ovApply() {
+        if (!ov) {
+            return;
+        }
+        ov.style.left = ovs.x + 'px';
+        ov.style.top = ovs.y + 'px';
+        ov.style.opacity = String(ovs.opacity);
+        ovImg.style.width = (ovs.baseW * ovs.scale || 0) + 'px';
+        ovImg.style.pointerEvents = ovs.through ? 'none' : 'auto';
+        ov.style.pointerEvents = ovs.through ? 'none' : 'auto';
+    }
+
+    function ovDrag(e) {
+        if (!dragFrom) {
+            return;
+        }
+        ovs.x = e.clientX - dragFrom.dx;
+        ovs.y = e.clientY - dragFrom.dy;
+        ovApply();
+    }
+    function ovDragEnd() {
+        dragFrom = null;
+    }
+
+    function ovBuild(data) {
+        ovRemove();
+        ovs = {x: 40, y: 40, scale: 1, opacity: 0.5, baseW: data.width || 0, through: false};
+        ov = document.createElement('div');
+        ov.style.cssText = 'position:fixed;z-index:2147483646;left:40px;top:40px;opacity:0.5;';
+        ovImg = document.createElement('img');
+        ovImg.src = data.dataUrl;
+        ovImg.draggable = false;
+        ovImg.style.cssText = 'display:block;cursor:move;box-shadow:0 0 0 1px rgba(255,0,0,0.35);';
+        ovImg.addEventListener('load', function () {
+            if (!ovs.baseW) {
+                ovs.baseW = ovImg.naturalWidth || 0;
+            }
+            ovApply();
+        });
+        ovImg.addEventListener('mousedown', function (e) {
+            if (ovs.through) {
+                return;
+            }
+            dragFrom = {dx: e.clientX - ovs.x, dy: e.clientY - ovs.y};
+            e.preventDefault();
+        });
+        document.addEventListener('mousemove', ovDrag);
+        document.addEventListener('mouseup', ovDragEnd);
+        ov.appendChild(ovImg);
+        document.documentElement.appendChild(ov);
+        ovToolbar();
+        ovApply();
+    }
+
+    function ovField(label, ctrl) {
+        var w = document.createElement('span');
+        w.style.cssText = 'display:flex;align-items:center;gap:6px;';
+        var l = document.createElement('span');
+        l.textContent = label;
+        w.appendChild(l);
+        w.appendChild(ctrl);
+        return w;
+    }
+
+    function ovToolbar() {
+        ovBar = document.createElement('div');
+        ovBar.style.cssText =
+            'position:fixed;top:12px;left:50%;transform:translateX(-50%);z-index:2147483647;display:flex;' +
+            'align-items:center;gap:12px;padding:6px 12px;border-radius:999px;background:#111;color:#fff;' +
+            'font:12px/1.4 sans-serif;box-shadow:0 2px 10px rgba(0,0,0,0.3);';
+        var o = document.createElement('input');
+        o.type = 'range';
+        o.min = '0';
+        o.max = '100';
+        o.value = '50';
+        o.style.width = '80px';
+        o.oninput = function () {
+            ovs.opacity = Number(o.value) / 100;
+            ovApply();
+        };
+        var z = document.createElement('input');
+        z.type = 'range';
+        z.min = '10';
+        z.max = '300';
+        z.value = '100';
+        z.style.width = '100px';
+        var zl = document.createElement('span');
+        zl.textContent = '100%';
+        z.oninput = function () {
+            ovs.scale = Number(z.value) / 100;
+            zl.textContent = z.value + '%';
+            ovApply();
+        };
+        var tc = document.createElement('input');
+        tc.type = 'checkbox';
+        tc.onchange = function () {
+            ovs.through = tc.checked;
+            ovApply();
+        };
+        var c = document.createElement('button');
+        c.textContent = '关闭';
+        c.style.cssText =
+            'border:none;border-radius:999px;padding:3px 10px;background:#ff5a5a;color:#fff;cursor:pointer;font:inherit;';
+        c.onclick = ovRemove;
+        ovBar.appendChild(ovField('透明', o));
+        ovBar.appendChild(ovField('缩放', z));
+        ovBar.appendChild(zl);
+        ovBar.appendChild(ovField('穿透', tc));
+        ovBar.appendChild(c);
+        document.documentElement.appendChild(ovBar);
+    }
+
+    // popup 的「走查」按钮 → 这里切换覆盖层：已显示则关闭，否则读 storage 的快照渲染。
+    try {
+        chrome.runtime.onMessage.addListener(function (msg, sender, sendResponse) {
+            if (!msg || msg.type !== 'toggle-figma-overlay') {
+                return;
+            }
+            if (ov) {
+                ovRemove();
+                sendResponse({ok: true, shown: false});
+                return;
+            }
+            chrome.storage.local.get({figmaOverlay: null}, function (o) {
+                if (chrome.runtime.lastError) {
+                    sendResponse({ok: false, error: '读取快照失败'});
+                    return;
+                }
+                if (!o || !o.figmaOverlay || !o.figmaOverlay.dataUrl) {
+                    sendResponse({ok: false, error: '还没有可走查的节点，先去 Figma 点「带入 Comate 生成代码」'});
+                    return;
+                }
+                ovBuild(o.figmaOverlay);
+                sendResponse({ok: true, shown: true});
+            });
+            return true; // 异步 sendResponse
+        });
+    } catch {
+        // 上下文失效
+    }
+
     const timer = setInterval(() => {
         if (!alive()) {
             clearInterval(timer);
@@ -194,7 +357,6 @@
                 const status = resp.status;
                 const id = status && status.id !== undefined ? status.id : null;
                 if (!statusSeeded) {
-                    // 首轮：记录当前状态 id（可能是上轮遗留），本轮不弹，避免刷新页面重放旧 toast
                     statusSeeded = true;
                     lastStatusId = id;
                 } else if (status && id !== lastStatusId) {

package/extension/manifest.json

@@ -5,7 +5,7 @@
     "description": "按住 Alt 点元素多选，交给本地 host / bridge，供 Comate 定位源码修改。目标域名与传输通路在扩展弹窗里配置。仅开发用。",
     "minimum_chrome_version": "111",
     "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArHbA4zi22qf48xgfUtkMM6vXEtWiTtmhlppNAMlfG/uFjujAK9EEGssy6674woq5W9ugl+FlVE4rf477m9drGnGjnvaaFc9U8xCVqUoe/+vTmRyDWAtSPyu2aulAXd9P78WCia5ROSpecian7b0pG/iPyqvgZsyJfYk1qC3VyEBOnOqVeWawawKE23OaxUZJaci4wB10xNrWBHBIAztL8xmRDSkkByImwNshtlzbo2pE17LHZGr35FMbQXdRBKWxsdKlT1t0j7ezK73bCFjsYLWoAXVSpK+eAjltGTqKtOTvNxV94TXwr/j0v7ikgz80XD4ffzXV0qDbQ8HCxRSZMwIDAQAB",
-    "permissions": ["nativeMessaging", "scripting", "storage"],
+    "permissions": ["nativeMessaging", "scripting", "storage", "unlimitedStorage"],
     "host_permissions": ["http://localhost/*", "http://127.0.0.1/*"],
     "optional_host_permissions": ["*://*/*"],
     "background": {

package/extension/native-host/host.mjs

@@ -11,7 +11,7 @@
  *
  * 数据文件与 MCP server / hook 共用：统一在用户主目录 ~/.ui-inspector/pending.json（与仓库位置无关）。
  */
-import {readFileSync, writeFileSync, appendFileSync, mkdirSync, readdirSync} from 'node:fs';
+import {readFileSync, writeFileSync, appendFileSync, mkdirSync, readdirSync, rmSync} from 'node:fs';
 import {dirname, resolve} from 'node:path';
 import {homedir} from 'node:os';
 
@@ -24,6 +24,8 @@ const recordingFile = resolve(homedir(), '.ui-inspector/recording.json');
 const eventsFile = resolve(homedir(), '.ui-inspector/recording-events.ndjson');
 // figma「带入对话」采集的节点结构，等 hook 注入下一条消息。
 const figmaPendingFile = resolve(homedir(), '.ui-inspector/figma-pending.json');
+// figma 节点内导出的图片字节落盘到这里（按采集批次分子目录）。
+const figmaAssetsDir = resolve(homedir(), '.ui-inspector/figma-assets');
 
 function readStore() {
     try {
@@ -88,10 +90,89 @@ function recStop(endedAt) {
 }
 
 // figma 节点采集：追加到 figma-pending.json（上限 10 个，防爆）。
+function sanitizeName(name) {
+    return (
+        String(name || 'image')
+            .replace(/[^a-zA-Z0-9._-]+/g, '_')
+            .replace(/^_+|_+$/g, '')
+            .slice(0, 60) || 'image'
+    );
+}
+
+// 清理旧的图片批次：保留当前仍在 figma-pending.json 里引用的批次目录（尚未被消费的节点），
+// 其余（已被 hook 注入消费、或被挤出 pending 的）全部删除。只在新一次导出时触发——「下次导出 PNG 才删上次的」。
+function pruneStaleAssets() {
+    let keep = new Set();
+    try {
+        const list = JSON.parse(readFileSync(figmaPendingFile, 'utf8'));
+        for (const entry of Array.isArray(list) ? list : []) {
+            const imgs = (entry && entry.node && entry.node.images) || [];
+            for (const im of imgs) {
+                if (im && im.file) {
+                    keep.add(dirname(im.file));
+                }
+            }
+        }
+    } catch {
+        keep = new Set();
+    }
+    let dirs = [];
+    try {
+        dirs = readdirSync(figmaAssetsDir);
+    } catch {
+        return; // 目录不存在，无需清理
+    }
+    for (const name of dirs) {
+        const full = resolve(figmaAssetsDir, name);
+        if (!keep.has(full)) {
+            try {
+                rmSync(full, {recursive: true, force: true});
+            } catch {
+                // 删除失败忽略
+            }
+        }
+    }
+}
+
+// 把 node.images 里的 base64 落成本地 PNG 文件，node 只保留 {file,name,id,width,height}，避免 json 膨胀。
+function persistImages(node) {
+    if (!node || !Array.isArray(node.images) || !node.images.length) {
+        if (node) {
+            delete node.images;
+        }
+        return;
+    }
+    pruneStaleAssets();
+    const batch = resolve(figmaAssetsDir, `${Date.now()}`);
+    mkdirSync(batch, {recursive: true});
+    const used = {};
+    const saved = [];
+    node.images.forEach((img, i) => {
+        if (!img || !img.base64) {
+            return;
+        }
+        let base = sanitizeName(img.name) + '-' + i;
+        if (used[base]) {
+            base += '_' + used[base]++;
+        } else {
+            used[base] = 1;
+        }
+        const file = resolve(batch, `${base}.png`);
+        try {
+            writeFileSync(file, Buffer.from(img.base64, 'base64'));
+            saved.push({id: img.id, name: img.name, width: img.width, height: img.height, file});
+        } catch {
+            // 单张落盘失败跳过
+        }
+    });
+    node.images = saved;
+}
+
 function figmaCapture(node) {
     if (!node) {
         return;
     }
+    persistImages(node);
     let list = [];
     try {
         const p = JSON.parse(readFileSync(figmaPendingFile, 'utf8'));

package/hooks/inject-ui-inspector.mjs

@@ -153,6 +153,16 @@ function describeFigma(nodes) {
         if ((n.html || '').length > 20000) {
             parts.push('…（结构过长已截断）');
         }
+        const imgs = Array.isArray(n.images) ? n.images.filter(im => im && im.file) : [];
+        if (imgs.length) {
+            parts.push(
+                `  该节点含 ${imgs.length} 张图片，已导出为本地 PNG（HTML 里的图片是占位路径没有字节，请用下面的真实文件；可用 Read 工具查看图片内容，按「名称」与 HTML 占位 src 对应）：`
+            );
+            imgs.forEach(im => {
+                const dim = im.width && im.height ? ` ${im.width}x${im.height}` : '';
+                parts.push(`    - ${im.name || '(未命名)'}（id ${im.id || '?'}${dim}）: ${im.file}`);
+            });
+        }
     });
     return parts.join('\n');
 }
@@ -186,6 +196,8 @@ try {
         writeFileSync(eventsFile, '', 'utf8');
     }
     if (hasFigma) {
+        // figma 节点注入后清空 pending，但导出的 PNG 文件保留——它们由下一次采集导出时清理（见 host/bridge
+        // 的 persistImages），这样注入后 Agent 仍可随时 Read 这些图片，直到下次带入新节点才替换。
         writeFileSync(figmaPendingFile, '[]\n', 'utf8');
     }
 } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "comate-ui-inspector",
-    "version": "0.1.6-alpha.2",
+    "version": "0.1.6-alpha.3",
     "description": "按住 Alt 点选页面元素，把「元素 + Vue 组件源码路径」交给 Comate 定位源码修改。浏览器扩展 + Native Messaging host + MCP + hook。",
     "type": "module",
     "license": "MIT",