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

package/bridge/server.mjs

@@ -5,8 +5,8 @@
  * 跑在「Comate agent / hook / MCP 所在的那台机器」（通常是远程开发机），读写和它们同一份
  * ~/.ui-inspector/*.json。浏览器扩展（transport=http）直连本服务。
  */
-import {createServer} from 'node:http';
-import {readFileSync, writeFileSync, appendFileSync, mkdirSync} from 'node:fs';
+import {createServer, get} from 'node:http';
+import {readFileSync, writeFileSync, appendFileSync, mkdirSync, readdirSync, rmSync} from 'node:fs';
 import {dirname, resolve} from 'node:path';
 import {homedir} from 'node:os';
 
@@ -17,6 +17,10 @@ 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');
+// bridge 实际绑定的端口写这里，供 cli（install --remote）读取并打印真正在用的端口。
+const portFile = resolve(homedir(), '.ui-inspector/bridge.json');
 const PORT = Number(process.env.UI_INSPECTOR_BRIDGE_PORT) || 8917;
 const HOST = process.env.UI_INSPECTOR_BRIDGE_HOST || '127.0.0.1';
 
@@ -84,10 +88,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'));
@@ -195,6 +278,95 @@ const server = createServer((req, res) => {
     json(res, 404, {ok: false, error: 'not found'});
 });
 
-server.listen(PORT, HOST, () => {
-    process.stdout.write(`ui-inspector bridge listening on http://${HOST}:${PORT}\n`);
+let currentPort = PORT;
+let triedReuse = false;
+let bound = false;
+const MAX_PORT_TRIES = 20;
+
+// 绑定成功：把实际端口写进 bridge.json（cli install --remote 据此打印真正在用的端口）。
+server.on('listening', () => {
+    bound = true;
+    const addr = server.address();
+    const actual = (addr && addr.port) || currentPort;
+    try {
+        mkdirSync(dirname(portFile), {recursive: true});
+        writeFileSync(
+            portFile,
+            `${JSON.stringify({host: HOST, port: actual, pid: process.pid, ts: Date.now()})}\n`,
+            'utf8'
+        );
+    } catch {
+        // 写端口文件失败不影响服务
+    }
+    process.stdout.write(`ui-inspector bridge listening on http://${HOST}:${actual}\n`);
+});
+
+// 顺延到下一个端口；连试 MAX_PORT_TRIES 个都不行才放弃。bound 后幂等，避免重复 listen 崩溃。
+function hopNext() {
+    if (bound) {
+        return;
+    }
+    if (currentPort - PORT >= MAX_PORT_TRIES) {
+        process.stderr.write(
+            `从 ${PORT} 起连续 ${MAX_PORT_TRIES} 个端口都被占用，放弃。手动指定 UI_INSPECTOR_BRIDGE_PORT。\n`
+        );
+        process.exit(1);
+        return;
+    }
+    currentPort += 1;
+    server.listen(currentPort, HOST);
+}
+
+// 端口被占用是常见情况。基准端口被占时先探测是不是已有我们的 bridge：是就复用退出（幂等）；
+// 否则自动顺延到下一个可用端口。其它启动错误直接友好报错退出，不抛未捕获异常。
+server.on('error', err => {
+    if (!err || err.code !== 'EADDRINUSE') {
+        process.stderr.write(`ui-inspector bridge 启动失败：${String(err)}\n`);
+        process.exit(1);
+        return;
+    }
+    if (currentPort === PORT && !triedReuse) {
+        triedReuse = true;
+        const probeHost = HOST === '0.0.0.0' ? '127.0.0.1' : HOST;
+        // probe 的 end/error/timeout 可能多次触发（如 destroy 又引发 error），用 settled 保证只处理一次。
+        let settled = false;
+        const settle = fn => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            fn();
+        };
+        const req = get({host: probeHost, port: PORT, path: '/state', timeout: 1500}, res => {
+            let body = '';
+            res.on('data', c => (body += c));
+            res.on('end', () =>
+                settle(() => {
+                    let ok = false;
+                    try {
+                        ok = JSON.parse(body).ok === true;
+                    } catch {
+                        ok = false;
+                    }
+                    if (ok) {
+                        process.stdout.write(
+                            `ui-inspector bridge 已在 http://${HOST}:${PORT} 运行，复用现有实例即可。\n`
+                        );
+                        process.exit(0);
+                    } else {
+                        hopNext(); // 被非 bridge 占用 → 换端口
+                    }
+                })
+            );
+        });
+        req.on('error', () => settle(hopNext));
+        req.on('timeout', () => {
+            req.destroy();
+            settle(hopNext);
+        });
+        return;
+    }
+    hopNext();
 });
+
+server.listen(currentPort, HOST);

package/cli.mjs

@@ -119,6 +119,29 @@ function installNativeHost() {
 }
 
 // 后台拉起 bridge 并与本进程脱钩，install --remote 用：装完 hook/MCP 顺手把 bridge 跑起来。
+// bridge 可能因端口被占而自动顺延端口，所以不能直接用传入的 port——读它落盘的 bridge.json 拿真正在用的端口。
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+// 轮询 ~/.ui-inspector/bridge.json，拿一条「本次启动之后写入」的记录（ts >= since）。读不到返回 null。
+function readActualBridgePort(since, timeoutMs = 4000) {
+    const f = resolve(pendingDir, 'bridge.json');
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const j = JSON.parse(readFileSync(f, 'utf8'));
+            if (j && j.port && (j.ts || 0) >= since) {
+                return j.port;
+            }
+        } catch {
+            // 文件还没写出来
+        }
+        sleepSync(150);
+    }
+    return null;
+}
+
 function startBridgeDetached(port, host) {
     mkdirSync(pendingDir, {recursive: true});
     const logFile = resolve(pendingDir, 'bridge.log');
@@ -127,14 +150,21 @@ function startBridgeDetached(port, host) {
     if (host) {
         env.UI_INSPECTOR_BRIDGE_HOST = String(host);
     }
+    const spawnedAt = Date.now();
     const child = spawn(process.execPath, [resolve(pkgRoot, 'bridge/server.mjs')], {
         detached: true,
         stdio: ['ignore', fd, fd],
         env,
     });
     child.unref();
-    out(`bridge 已后台启动（pid ${child.pid}，监听 ${host || '127.0.0.1'}:${port}），日志：${logFile}`);
+    // 端口可能被占而自动顺延；读 bridge.json 拿真正在用的端口。复用现有实例时子进程不写新记录，回落到传入 port。
+    const actual = readActualBridgePort(spawnedAt) || port;
+    out(`bridge 已后台启动（pid ${child.pid}，监听 ${host || '127.0.0.1'}:${actual}），日志：${logFile}`);
+    if (String(actual) !== String(port)) {
+        out(`  注意：端口 ${port} 被占用，已自动改用 ${actual}——扩展弹窗地址请填这个端口。`);
+    }
     out(`  停止：kill ${child.pid}`);
+    return actual;
 }
 
 function install({remote, port, host}) {
@@ -142,9 +172,9 @@ function install({remote, port, host}) {
     if (remote) {
         const bindHost = host || '0.0.0.0';
         out('\n== 远程开发机：跳过 native host/扩展（这台没浏览器），后台启动 bridge ==');
-        startBridgeDetached(port, bindHost);
+        const actual = startBridgeDetached(port, bindHost);
         out(
-            `\n浏览器在扩展弹窗里把传输设为「远程（HTTP bridge）」、地址填「本机可达地址:${port}」（如 devlocal.oreateai.com:${port}）即可直连。`
+            `\n浏览器在扩展弹窗里把传输设为「远程（HTTP bridge）」、地址填「本机可达地址:${actual}」（如 devlocal.oreateai.com:${actual}）即可直连。`
         );
         return;
     }

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,178 @@
         // 上下文失效
     }
 
+    // ---------- 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('pointermove', ovDrag);
+        document.removeEventListener('pointerup', ovDragEnd);
+        document.removeEventListener('pointercancel', 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;
+        // touch-action:none —— 否则移动端/模拟器会把触摸当成页面滚动吞掉，pointermove 不触发。
+        ovImg.style.cssText = 'display:block;cursor:move;touch-action:none;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();
+        });
+        // 用 Pointer Events 统一鼠标 + 触摸（含 DevTools 移动端模拟器把鼠标转成 touch 的情况）。
+        ovImg.addEventListener('pointerdown', function (e) {
+            if (ovs.through) {
+                return;
+            }
+            dragFrom = {dx: e.clientX - ovs.x, dy: e.clientY - ovs.y};
+            try {
+                ovImg.setPointerCapture(e.pointerId);
+            } catch (err) {
+                // 某些环境不支持指针捕获，忽略
+            }
+            e.preventDefault();
+        });
+        document.addEventListener('pointermove', ovDrag);
+        document.addEventListener('pointerup', ovDragEnd);
+        document.addEventListener('pointercancel', 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 +366,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/inspector-main.js

@@ -39,6 +39,17 @@
     panelHead.style.cssText = 'display:flex;align-items:center;justify-content:space-between;margin-bottom:6px;';
     var panelCount = document.createElement('span');
     panelCount.style.cssText = 'font-weight:600;';
+    // 右侧按钮组：收起/展开 + 清空。
+    var panelBtns = document.createElement('div');
+    panelBtns.style.cssText = 'display:flex;gap:6px;flex:none;';
+    var panelToggle = document.createElement('button');
+    panelToggle.textContent = '收起';
+    panelToggle.style.cssText =
+        'border:none;background:#2f2f2f;color:#fff;border-radius:4px;padding:2px 8px;cursor:pointer;font:inherit;';
+    panelToggle.onclick = function () {
+        panelCollapsed = !panelCollapsed;
+        renderPanel();
+    };
     var panelClear = document.createElement('button');
     panelClear.textContent = '清空';
     panelClear.style.cssText =
@@ -49,8 +60,10 @@
         renderPanel();
         showHint('已清空全部选中');
     };
+    panelBtns.appendChild(panelToggle);
+    panelBtns.appendChild(panelClear);
     panelHead.appendChild(panelCount);
-    panelHead.appendChild(panelClear);
+    panelHead.appendChild(panelBtns);
     var panelList = document.createElement('div');
     panel.appendChild(panelHead);
     panel.appendChild(panelList);
@@ -81,6 +94,7 @@
     // DOM 树上下级导航状态：navPath 从叶子往上累积，navIdx 当前停在哪一层（0 = 叶子）。
     var navPath = [];
     var navIdx = 0;
+    var panelCollapsed = false; // 侧边栏收起态：仅隐藏列表，保留标题与计数
 
     function renderPanel() {
         if (!selected.length) {
@@ -89,6 +103,8 @@
         }
         panel.style.display = 'block';
         panelCount.textContent = '已选中 ' + selected.length + ' 个';
+        panelToggle.textContent = panelCollapsed ? '展开' : '收起';
+        panelList.style.display = panelCollapsed ? 'none' : 'block';
         panelList.textContent = '';
         renumber();
         selected.forEach(function (item, i) {

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/extension/popup.html

@@ -225,15 +225,13 @@
                         <input
                             id="bridge-target"
                             type="text"
-                            placeholder="devlocal.oreateai.com:8917"
+                            placeholder="<remote-ip>:<port>"
                         />
                     </div>
                     <div class="hint">
                         填开发机 bridge 的完整地址（如
-                        <code>devlocal.oreateai.com:8917</code>
-                        ）。开发机上
-                        <code>ui-inspector install --remote</code>
-                        起 bridge（默认绑 0.0.0.0 供直连）。
+                        <code><\remote-ip>:<\port></code>
+                        ）
                     </div>
                 </div>
             </section>

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.4",
     "description": "按住 Alt 点选页面元素，把「元素 + Vue 组件源码路径」交给 Comate 定位源码修改。浏览器扩展 + Native Messaging host + MCP + hook。",
     "type": "module",
     "license": "MIT",