comate-ui-inspector 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,57 @@
-# Temporary Holding Version
+# ui-inspector
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+在浏览器里按住 **Alt 点元素多选**，把「选中元素 + Vue 组件源码路径」交给 Comate，然后在对话里写修改意见让 AI 改代码。不改任何构建代码、日常不用手动起服务。
+
+## 目录
+
+- `extension/`：Chrome/Edge MV3 扩展（`manifest.json` + MAIN/ISOLATED 内容脚本 + background SW）。
+    - `extension/native-host/host.mjs`：Native Messaging host（浏览器按需拉起，零依赖）。
+- `mcp/server.mjs`：MCP stdio server，`clear_pending_edits` = 取消选中。
+- `hooks/inject-ui-inspector.mjs`：Comate `UserPromptSubmit` hook，提交时自动注入全部选中元素。
+- `cli.mjs`：命令入口，提供 `install` / `uninstall` / `status`（发布为 npm 包后暴露为 `ui-inspector` 命令）。
+
+数据落在 `~/.ui-inspector/pending.json`（用户主目录、一台机器一份）。hook 注册为**个人级**（`~/.comate/hooks.json`，对所有项目生效），所以**整机只装一次、所有仓库通用**，命令在哪个目录跑都行。
+
+## 安装（macOS / Linux，整机一次）
+
+```bash
+npm i -g comate-ui-inspector   # 公网 npm；或本地：npm i -g <本包目录>
+ui-inspector install           # 注册 native host + 个人级 hook，并打印 MCP 配置与扩展目录
+```
+
+`install` 打印的两样东西要手动接上：
+
+1. 把打印的 **MCP 配置**贴进 Comate 的 MCP 设置，**reload Comate**。
+2. `chrome://extensions` → 开发者模式 →「加载已解压的扩展程序」→ 选打印出来的 **扩展目录**（只需一次）。
+
+## 卸载 / 状态
+
+```bash
+ui-inspector status            # 查看 host 清单 / 个人 hook / 待处理数 / 扩展目录
+ui-inspector uninstall         # 移除 native host 清单 + 个人级 hook（加 --purge 连 ~/.ui-inspector 一起删）
+npm un -g comate-ui-inspector  # 再删除命令本身
+```
+
+> 卸载后仍需手动：在 Comate MCP 配置里删掉 ui-inspector、在 `chrome://extensions` 里移除扩展（这两处 CLI 碰不到）。
+
+## 发布（维护者）
+
+```bash
+cd tools/ui-inspector
+npm publish            # 发到公网 npm（package.json 的 publishConfig 已指向 registry.npmjs.org；需 npm 账号）
+```
+
+## 用法
+
+- 按住 **Alt**，点页面元素（可多选，绿框；再点取消）。
+- 回 Comate **直接写修改意见发送**，选中元素会自动附带。
+- AI 改完调用 `clear_pending_edits`，页面高亮消失。
+
+## 说明 / 限制
+
+- 扩展默认只在 `local.oreateai.com` / `localhost` / `127.0.0.1` 生效；别的开发域名改 `extension/manifest.json` 的 `content_scripts[].matches`。
+- 只有 **dev 构建** 拿得到组件源码路径（Vue dev 的 `__file`）；生产构建组件链为空，退回选择器/文本定位。
+- **Windows 暂不支持**（native host 需 `.bat` 包装器）。
+- 扩展 ID 用 `manifest.json` 的公钥 `key` 钉死，所有人加载后一致；私钥未使用、未入库。
+- 多仓库共用一份落盘（`~/.ui-inspector/`），同一时刻只保留最近一次选中；跨仓库并行编辑时以最后一次选择为准。
+- 个人级 hook 会在**所有项目**的每次提交时触发；无选中时它直接返回 `allow`（空操作、不注入），对其它项目无副作用。

package/cli.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/*
+ * ui-inspector CLI。发布到 npm 后全局安装即可获得 `ui-inspector` 命令：
+ *   npm i -g comate-ui-inspector
+ *   ui-inspector install      # 注册 native host + 写个人级 hook + 打印 MCP 配置与扩展目录
+ *   ui-inspector uninstall    # 移除 native host 清单 + 个人级 hook（--purge 连 ~/.ui-inspector 一起删）
+ *   ui-inspector status       # 查看安装状态
+ *
+ * 全部按「整机一份、个人级」接入，不绑定任何仓库。仅 macOS / Linux。
+ */
+import {chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, rmSync} from 'node:fs';
+import {dirname, join, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {homedir, platform} from 'node:os';
+
+const HOST_NAME = 'com.oreate.ui_inspector';
+const EXT_ID = 'akpiagdjfeeaioifjepbmonpallececo';
+
+const pkgRoot = dirname(fileURLToPath(import.meta.url));
+const hostPath = resolve(pkgRoot, 'extension/native-host/host.mjs');
+const serverPath = resolve(pkgRoot, 'mcp/server.mjs');
+const hookPath = resolve(pkgRoot, 'hooks/inject-ui-inspector.mjs');
+const extensionDir = resolve(pkgRoot, 'extension');
+const home = homedir();
+const hooksFile = resolve(home, '.comate/hooks.json');
+const pendingDir = resolve(home, '.ui-inspector');
+
+function nmDirs() {
+    const rels =
+        platform() === 'darwin'
+            ? [
+                  'Library/Application Support/Google/Chrome/NativeMessagingHosts',
+                  'Library/Application Support/Google/Chrome Canary/NativeMessagingHosts',
+                  'Library/Application Support/Microsoft Edge/NativeMessagingHosts',
+                  'Library/Application Support/BraveSoftware/Brave-Browser/NativeMessagingHosts',
+              ]
+            : ['.config/google-chrome/NativeMessagingHosts', '.config/microsoft-edge/NativeMessagingHosts', '.config/chromium/NativeMessagingHosts'];
+    return rels.map(rel => join(home, rel));
+}
+
+function readHooks() {
+    try {
+        return JSON.parse(readFileSync(hooksFile, 'utf8'));
+    } catch {
+        return null;
+    }
+}
+
+function out(text) {
+    process.stdout.write(`${text}\n`);
+}
+function install() {
+    chmodSync(hostPath, 0o755);
+    const manifest = {
+        name: HOST_NAME,
+        description: 'ui-inspector native messaging host',
+        path: hostPath,
+        type: 'stdio',
+        allowed_origins: [`chrome-extension://${EXT_ID}/`],
+    };
+    for (const dir of nmDirs()) {
+        try {
+            mkdirSync(dir, {recursive: true});
+            writeFileSync(join(dir, `${HOST_NAME}.json`), `${JSON.stringify(manifest, null, 2)}\n`);
+            out(`host manifest -> ${join(dir, `${HOST_NAME}.json`)}`);
+        } catch (error) {
+            out(`skip ${dir}: ${String(error)}`);
+        }
+    }
+
+    const hookCommand = `node "${hookPath}"`;
+    const config = readHooks() || {hooks: {}};
+    config.hooks = config.hooks || {};
+    const list = Array.isArray(config.hooks.UserPromptSubmit) ? config.hooks.UserPromptSubmit : [];
+    if (!JSON.stringify(list).includes('inject-ui-inspector')) {
+        list.push({hooks: [{type: 'command', command: hookCommand, timeout: 10}]});
+        config.hooks.UserPromptSubmit = list;
+        mkdirSync(dirname(hooksFile), {recursive: true});
+        writeFileSync(hooksFile, `${JSON.stringify(config, null, 4)}\n`);
+        out(`hook installed -> ${hooksFile}`);
+    } else {
+        out('hook already present, skip');
+    }
+
+    out('\n== 把下面加进 Comate 的 MCP 配置（stdio），然后 reload Comate ==');
+    out(JSON.stringify({mcpServers: {'ui-inspector': {command: 'node', args: [serverPath]}}}, null, 4));
+    out('\n== 加载浏览器扩展（chrome://extensions → 开发者模式 → 加载已解压 → 选下面这个目录） ==');
+    out(extensionDir);
+    out('\n完成后：按住 Alt 点元素多选 → 回 Comate 写修改意见。');
+}
+
+function uninstall({purge}) {
+    for (const dir of nmDirs()) {
+        const file = join(dir, `${HOST_NAME}.json`);
+        if (existsSync(file)) {
+            rmSync(file);
+            out(`removed host manifest -> ${file}`);
+        }
+    }
+    const config = readHooks();
+    if (config?.hooks?.UserPromptSubmit) {
+        const before = config.hooks.UserPromptSubmit.length;
+        config.hooks.UserPromptSubmit = config.hooks.UserPromptSubmit.filter(
+            entry => !JSON.stringify(entry).includes('inject-ui-inspector')
+        );
+        if (config.hooks.UserPromptSubmit.length !== before) {
+            writeFileSync(hooksFile, `${JSON.stringify(config, null, 4)}\n`);
+            out(`removed hook <- ${hooksFile}`);
+        }
+    }
+    if (purge && existsSync(pendingDir)) {
+        rmSync(pendingDir, {recursive: true, force: true});
+        out(`purged ${pendingDir}`);
+    }
+    out('\n已移除本地注册。还需手动：① 在 Comate MCP 配置里删掉 ui-inspector；② chrome://extensions 里移除扩展。');
+}
+
+function status() {
+    out('ui-inspector 状态：');
+    for (const dir of nmDirs()) {
+        const file = join(dir, `${HOST_NAME}.json`);
+        out(`  host 清单 ${existsSync(file) ? '✓' : '✗'} ${file}`);
+    }
+    const hooked = JSON.stringify(readHooks()?.hooks?.UserPromptSubmit || []).includes('inject-ui-inspector');
+    out(`  个人 hook ${hooked ? '✓ 已注册' : '✗ 未注册'}（${hooksFile}）`);
+    const pending = resolve(pendingDir, 'pending.json');
+    let count = 0;
+    try {
+        count = JSON.parse(readFileSync(pending, 'utf8')).length;
+    } catch {
+        count = 0;
+    }
+    out(`  当前待处理选中：${count} 条（${pending}）`);
+    out(`  扩展目录：${extensionDir}`);
+}
+
+function help() {
+    out('用法：ui-inspector <install|uninstall|status>');
+    out('  install    注册 native host + 个人级 hook，并打印 MCP 配置与扩展目录');
+    out('  uninstall  移除上述注册（加 --purge 连 ~/.ui-inspector 数据一起删）');
+    out('  status     查看安装状态');
+}
+
+const cmd = process.argv[2] || 'help';
+if (cmd === 'install') {
+    install();
+} else if (cmd === 'uninstall') {
+    uninstall({purge: process.argv.includes('--purge')});
+} else if (cmd === 'status') {
+    status();
+} else {
+    help();
+}
+

package/extension/background.js

@@ -0,0 +1,36 @@
+/*
+ * ui-inspector 扩展的 background service worker。
+ *
+ * 改用 Native Messaging：不再 fetch 本地 HTTP（免去混合内容问题与手动起 server），
+ * 由 chrome.runtime.sendNativeMessage 触发浏览器**按需拉起**本地 node host（host.mjs），
+ * host 读写 .ui-inspector/pending.json 后退出。每次请求一问一答。
+ */
+const HOST = 'com.oreate.ui_inspector';
+
+chrome.runtime.onMessage.addListener((msg, _sender, sendResponse) => {
+    if (!msg || typeof msg.type !== 'string') {
+        return;
+    }
+
+    if (msg.type === 'ingest') {
+        chrome.runtime.sendNativeMessage(HOST, {type: 'ingest', targets: msg.targets || []}, resp => {
+            if (chrome.runtime.lastError) {
+                sendResponse({ok: false, error: chrome.runtime.lastError.message});
+                return;
+            }
+            sendResponse(resp);
+        });
+        return true; // 异步 sendResponse
+    }
+
+    if (msg.type === 'state') {
+        chrome.runtime.sendNativeMessage(HOST, {type: 'state'}, resp => {
+            if (chrome.runtime.lastError) {
+                sendResponse({ok: false, error: chrome.runtime.lastError.message});
+                return;
+            }
+            sendResponse(resp); // {ok, count}
+        });
+        return true;
+    }
+});

package/extension/bridge-content.js

@@ -0,0 +1,29 @@
+/*
+ * ISOLATED world 内容脚本：MAIN world 与 background 之间的中继。
+ *
+ * - 收到 MAIN 发来的 selection（window.postMessage）→ 转给 background 写入本地桥；
+ * - 每 1.5s 问 background 要一次 /state 的 count；count 为 0（AI 调 MCP 清空后）
+ *   → 回发 cleared 给 MAIN，让它撤掉页面高亮。
+ */
+(function () {
+    window.addEventListener('message', event => {
+        if (event.source !== window) {
+            return;
+        }
+        const data = event.data;
+        if (data && data.__uiInspector === 'selection') {
+            chrome.runtime.sendMessage({type: 'ingest', targets: data.targets || []});
+        }
+    });
+
+    setInterval(() => {
+        chrome.runtime.sendMessage({type: 'state'}, resp => {
+            if (chrome.runtime.lastError) {
+                return;
+            }
+            if (resp && resp.ok && resp.count === 0) {
+                window.postMessage({__uiInspectorBridge: 'cleared'}, '*');
+            }
+        });
+    }, 1500);
+})();

package/extension/inspector-main.js

@@ -0,0 +1,223 @@
+/*
+ * MAIN world 内容脚本：和原 Vite 客户端同款逻辑，但不 fetch——
+ * 选中集合通过 window.postMessage 交给 ISOLATED 的 bridge-content.js。
+ * 读 el.__vueParentComponent / type.__file 必须在 MAIN world（页面 JS 上下文）才拿得到。
+ */
+(function () {
+    if (window.__oreateUiInspector) {
+        return;
+    }
+    window.__oreateUiInspector = true;
+
+    var active = false;
+    var current = null;
+    var selected = []; // 每项 {el, info, box}
+
+    var overlay = document.createElement('div');
+    overlay.style.cssText =
+        'position:fixed;z-index:2147483646;pointer-events:none;border:2px solid #2f6bff;' +
+        'background:rgba(47,107,255,0.12);border-radius:4px;display:none;transition:all 0.05s;';
+    document.body.appendChild(overlay);
+
+    var hint = document.createElement('div');
+    hint.textContent = '按住 Alt 点元素可多选';
+    hint.style.cssText =
+        'position:fixed;left:50%;bottom:16px;transform:translateX(-50%);z-index:2147483647;' +
+        'padding:6px 12px;border-radius:999px;background:#111;color:#fff;font:12px/1.4 sans-serif;' +
+        'opacity:0;transition:opacity 0.15s;pointer-events:none;';
+    document.body.appendChild(hint);
+
+    function showHint(text) {
+        hint.textContent = text;
+        hint.style.opacity = '1';
+        window.clearTimeout(showHint._t);
+        showHint._t = window.setTimeout(function () {
+            hint.style.opacity = '0';
+        }, 1800);
+    }
+    function cssPath(el) {
+        var parts = [];
+        var node = el;
+        while (node && node.nodeType === 1 && parts.length < 6) {
+            var seg = node.nodeName.toLowerCase();
+            if (node.id) {
+                seg += '#' + node.id;
+                parts.unshift(seg);
+                break;
+            }
+            var cls = (node.getAttribute('class') || '').trim().split(/\s+/).filter(Boolean).slice(0, 2);
+            if (cls.length) {
+                seg += '.' + cls.join('.');
+            }
+            parts.unshift(seg);
+            node = node.parentElement;
+        }
+        return parts.join(' > ');
+    }
+
+    function componentChain(el) {
+        var chain = [];
+        var instance = el.__vueParentComponent;
+        while (instance && chain.length < 6) {
+            var type = instance.type || {};
+            var file = type.__file || null;
+            var name = type.__name || type.name || null;
+            if (file || name) {
+                chain.push({name: name, file: file});
+            }
+            instance = instance.parent;
+        }
+        return chain;
+    }
+
+    function collect(el) {
+        var rect = el.getBoundingClientRect();
+        return {
+            tag: el.nodeName.toLowerCase(),
+            id: el.id || null,
+            classList: Array.prototype.slice.call(el.classList),
+            selector: cssPath(el),
+            text: (el.textContent || '').trim().slice(0, 200),
+            rect: {x: Math.round(rect.x), y: Math.round(rect.y), w: Math.round(rect.width), h: Math.round(rect.height)},
+            componentChain: componentChain(el),
+            pageUrl: location.href,
+        };
+    }
+    function moveOverlay(el) {
+        var rect = el.getBoundingClientRect();
+        overlay.style.display = 'block';
+        overlay.style.left = rect.left + 'px';
+        overlay.style.top = rect.top + 'px';
+        overlay.style.width = rect.width + 'px';
+        overlay.style.height = rect.height + 'px';
+    }
+
+    function makeSelBox() {
+        var box = document.createElement('div');
+        box.style.cssText =
+            'position:fixed;z-index:2147483645;pointer-events:none;border:2px solid #16a34a;' +
+            'background:rgba(22,163,74,0.10);border-radius:4px;';
+        document.body.appendChild(box);
+        return box;
+    }
+
+    function placeBox(box, el) {
+        var rect = el.getBoundingClientRect();
+        box.style.left = rect.left + 'px';
+        box.style.top = rect.top + 'px';
+        box.style.width = rect.width + 'px';
+        box.style.height = rect.height + 'px';
+    }
+
+    function repositionBoxes() {
+        for (var i = 0; i < selected.length; i++) {
+            placeBox(selected[i].box, selected[i].el);
+        }
+    }
+
+    function clearSelection() {
+        for (var i = 0; i < selected.length; i++) {
+            selected[i].box.remove();
+        }
+        selected = [];
+    }
+
+    function indexOfEl(el) {
+        for (var i = 0; i < selected.length; i++) {
+            if (selected[i].el === el) {
+                return i;
+            }
+        }
+        return -1;
+    }
+
+    function postSelection() {
+        window.postMessage(
+            {
+                __uiInspector: 'selection',
+                targets: selected.map(function (s) {
+                    return s.info;
+                }),
+            },
+            '*'
+        );
+    }
+
+    function toggleSelect(el) {
+        var idx = indexOfEl(el);
+        if (idx >= 0) {
+            selected[idx].box.remove();
+            selected.splice(idx, 1);
+            showHint('已取消选中（当前 ' + selected.length + ' 个）');
+        } else {
+            var box = makeSelBox();
+            placeBox(box, el);
+            selected.push({el: el, info: collect(el), box: box});
+            showHint('已选中 ' + selected.length + ' 个，可继续选，或回对话写意见');
+        }
+        postSelection();
+    }
+    window.addEventListener(
+        'keydown',
+        function (e) {
+            if (e.key === 'Alt' && !active) {
+                active = true;
+                showHint('选择模式：点击元素可多选，再点取消；松开 Alt 退出');
+            }
+        },
+        true
+    );
+    window.addEventListener(
+        'keyup',
+        function (e) {
+            if (e.key === 'Alt') {
+                active = false;
+                overlay.style.display = 'none';
+            }
+        },
+        true
+    );
+    window.addEventListener(
+        'mousemove',
+        function (e) {
+            if (!active) {
+                return;
+            }
+            var el = document.elementFromPoint(e.clientX, e.clientY);
+            if (el && el !== current && el !== overlay && el !== hint) {
+                current = el;
+                moveOverlay(el);
+            }
+        },
+        true
+    );
+    window.addEventListener(
+        'click',
+        function (e) {
+            if (!active || !e.altKey) {
+                return;
+            }
+            e.preventDefault();
+            e.stopPropagation();
+            var el = document.elementFromPoint(e.clientX, e.clientY);
+            if (el && el !== overlay && el !== hint) {
+                toggleSelect(el);
+            }
+        },
+        true
+    );
+
+    window.addEventListener('scroll', repositionBoxes, true);
+    window.addEventListener('resize', repositionBoxes, true);
+
+    // bridge-content 轮询到服务端 pending 已清空时回发 cleared，撤掉全部高亮
+    window.addEventListener('message', function (event) {
+        if (event.source !== window) {
+            return;
+        }
+        if (event.data && event.data.__uiInspectorBridge === 'cleared' && selected.length) {
+            clearSelection();
+            showHint('已按 AI 指令取消全部选中');
+        }
+    });
+})();

package/extension/manifest.json

@@ -0,0 +1,24 @@
+{
+    "manifest_version": 3,
+    "name": "ui-inspector bridge",
+    "version": "0.0.1",
+    "description": "按住 Alt 点元素多选，经 Native Messaging 交给本地 host，供 Comate 定位源码修改。仅开发用。",
+    "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArHbA4zi22qf48xgfUtkMM6vXEtWiTtmhlppNAMlfG/uFjujAK9EEGssy6674woq5W9ugl+FlVE4rf477m9drGnGjnvaaFc9U8xCVqUoe/+vTmRyDWAtSPyu2aulAXd9P78WCia5ROSpecian7b0pG/iPyqvgZsyJfYk1qC3VyEBOnOqVeWawawKE23OaxUZJaci4wB10xNrWBHBIAztL8xmRDSkkByImwNshtlzbo2pE17LHZGr35FMbQXdRBKWxsdKlT1t0j7ezK73bCFjsYLWoAXVSpK+eAjltGTqKtOTvNxV94TXwr/j0v7ikgz80XD4ffzXV0qDbQ8HCxRSZMwIDAQAB",
+    "permissions": ["nativeMessaging"],
+    "background": {
+        "service_worker": "background.js"
+    },
+    "content_scripts": [
+        {
+            "matches": ["https://local.oreateai.com/*", "http://localhost/*", "http://127.0.0.1/*"],
+            "js": ["inspector-main.js"],
+            "world": "MAIN",
+            "run_at": "document_idle"
+        },
+        {
+            "matches": ["https://local.oreateai.com/*", "http://localhost/*", "http://127.0.0.1/*"],
+            "js": ["bridge-content.js"],
+            "run_at": "document_idle"
+        }
+    ]
+}

package/extension/native-host/host.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/*
+ * ui-inspector Native Messaging host（零依赖）。
+ *
+ * 由浏览器扩展经 chrome.runtime.sendNativeMessage 按需拉起：读一条 stdin 消息、处理、回一条、退出。
+ * Native Messaging 帧格式：4 字节 LE 长度前缀 + UTF-8 的 JSON。
+ *
+ * 消息：
+ *   {type:'ingest', targets:[...]}  → replace 写入 .ui-inspector/pending.json，回 {ok,pending}
+ *   {type:'state'}                  → 回 {ok,count}
+ *
+ * 数据文件与 MCP server / hook 共用：统一在用户主目录 ~/.ui-inspector/pending.json（与仓库位置无关）。
+ */
+import {readFileSync, writeFileSync, mkdirSync} from 'node:fs';
+import {dirname, resolve} from 'node:path';
+import {homedir} from 'node:os';
+
+// 共享落盘：一台机器一份，放用户主目录，不绑定任何仓库——一份代码可服务多个项目。
+const storeFile = resolve(homedir(), '.ui-inspector/pending.json');
+
+function readStore() {
+    try {
+        const parsed = JSON.parse(readFileSync(storeFile, 'utf8'));
+        return Array.isArray(parsed) ? parsed : [];
+    } catch {
+        return [];
+    }
+}
+
+function writeStore(list) {
+    mkdirSync(dirname(storeFile), {recursive: true});
+    writeFileSync(storeFile, `${JSON.stringify(list, null, 4)}\n`, 'utf8');
+}
+
+function send(obj) {
+    const body = Buffer.from(JSON.stringify(obj), 'utf8');
+    const header = Buffer.alloc(4);
+    header.writeUInt32LE(body.length, 0);
+    process.stdout.write(Buffer.concat([header, body]));
+}
+
+function handle(msg) {
+    let resp;
+    if (msg && msg.type === 'ingest') {
+        const targets = Array.isArray(msg.targets) ? msg.targets : [];
+        const now = new Date().toISOString();
+        writeStore(targets.map(target => ({target, receivedAt: now})));
+        resp = {ok: true, pending: targets.length};
+    } else if (msg && msg.type === 'state') {
+        resp = {ok: true, count: readStore().length};
+    } else {
+        resp = {ok: false, error: 'unknown message'};
+    }
+    send(resp);
+    process.exit(0);
+}
+
+let buf = Buffer.alloc(0);
+process.stdin.on('data', chunk => {
+    buf = Buffer.concat([buf, chunk]);
+    if (buf.length < 4) {
+        return;
+    }
+    const len = buf.readUInt32LE(0);
+    if (buf.length >= 4 + len) {
+        handle(JSON.parse(buf.slice(4, 4 + len).toString('utf8')));
+    }
+});

package/hooks/inject-ui-inspector.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/*
+ * Comate UserPromptSubmit hook：把 ui-inspector 在页面上选中的元素，自动注入到本轮对话。
+ *
+ * 流程：浏览器里按住 Alt 点元素（可多选，持久高亮）→ 落盘 .ui-inspector/pending.json；
+ * 回到 Comate 写修改意见提交 → 本 hook 读取**全部**选中元素，作为 additionalContext 注入给 Agent。
+ *
+ * 注意：这里**不清空** pending —— 选中态要一直保持到 AI 改完、主动调 MCP clear_pending_edits
+ * 才取消（页面轮询到 count=0 后撤掉高亮）。否则第一轮提交就会把多选清掉、页面提前取消高亮。
+ *
+ * 入参由 stdin 传入（UserPromptSubmit 的 JSON），这里用不到；输出 JSON 到 stdout。
+ */
+import {readFileSync} from 'node:fs';
+import {resolve} from 'node:path';
+import {homedir} from 'node:os';
+
+// 共享落盘：读用户主目录下的 pending（与 host / mcp 同一路径），一份代码可服务多个仓库。
+const storeFile = resolve(homedir(), '.ui-inspector/pending.json');
+
+function emit(output) {
+    process.stdout.write(JSON.stringify(output));
+    process.exit(0);
+}
+
+let list = [];
+try {
+    const parsed = JSON.parse(readFileSync(storeFile, 'utf8'));
+    list = Array.isArray(parsed) ? parsed : [];
+} catch {
+    emit({decision: 'allow'});
+}
+
+if (!list.length) {
+    emit({decision: 'allow'});
+}
+
+function describe(target, index, total) {
+    const files = (target.componentChain || []).map(item => item && item.file).filter(Boolean);
+    const head = total > 1 ? `【元素 ${index + 1}/${total}】` : '';
+    return [
+        head + (files.length ? `组件源码（由近及远）: ${files.join(' <- ')}` : '组件源码: 未捕获（不在 Vue 组件树内）'),
+        `  CSS 选择器: ${target.selector || '(无)'}`,
+        `  标签/文本: <${target.tag || '?'}> ${JSON.stringify((target.text || '').slice(0, 120))}`,
+        target.pageUrl ? `  页面: ${target.pageUrl}` : '',
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+
+const total = list.length;
+const body = list.map((entry, index) => describe(entry?.target ?? {}, index, total)).join('\n');
+const additionalContext = [
+    `【ui-inspector】用户在页面上选中了 ${total} 个元素，接下来这条消息是针对它们的修改意见：`,
+    body,
+    '请据此定位源码并按用户意见修改；改完调用 MCP 工具 clear_pending_edits 取消页面选中。',
+].join('\n');
+
+emit({decision: 'allow', additionalContext});

package/mcp/server.mjs

@@ -0,0 +1,120 @@
+/*
+ * ui-inspector 的 MCP server（零依赖，stdio 传输）。
+ *
+ * Comate 作为 MCP client 启动本进程，读取 ui-inspector 桥落盘的待处理修改意见。
+ * 数据文件：~/.ui-inspector/pending.json（由扩展的 Native Messaging host（native-host/host.mjs）写入）。
+ *
+ * MCP stdio 传输是「一行一条 JSON-RPC 2.0 消息」，这里手写最小实现：
+ *   initialize / notifications/initialized / tools/list / tools/call。
+ *
+ * 启动：node tools/ui-inspector/mcp/server.mjs
+ */
+import {readFileSync, writeFileSync, mkdirSync} from 'node:fs';
+import {dirname, resolve} from 'node:path';
+import {homedir} from 'node:os';
+import {createInterface} from 'node:readline';
+
+const storeFile = resolve(homedir(), '.ui-inspector/pending.json');
+
+function readStore() {
+    try {
+        const parsed = JSON.parse(readFileSync(storeFile, 'utf8'));
+        return Array.isArray(parsed) ? parsed : [];
+    } catch {
+        return [];
+    }
+}
+
+function clearStore() {
+    const count = readStore().length;
+    mkdirSync(dirname(storeFile), {recursive: true});
+    writeFileSync(storeFile, '[]\n', 'utf8');
+    return count;
+}
+
+const TOOLS = [
+    {
+        name: 'list_pending_edits',
+        description: '列出 ui-inspector 收到的全部待处理修改意见（含选中元素信息与 Vue 组件源码文件链）。',
+        inputSchema: {type: 'object', properties: {}},
+    },
+    {
+        name: 'get_latest_edit',
+        description: '取最新一条待处理修改意见。',
+        inputSchema: {type: 'object', properties: {}},
+    },
+    {
+        name: 'clear_pending_edits',
+        description: '处理完后清空待处理列表，返回被清空的条数。',
+        inputSchema: {type: 'object', properties: {}},
+    },
+];
+
+function callTool(name) {
+    if (name === 'list_pending_edits') {
+        return readStore();
+    }
+    if (name === 'get_latest_edit') {
+        const list = readStore();
+        return list.length ? list[list.length - 1] : null;
+    }
+    if (name === 'clear_pending_edits') {
+        return {cleared: clearStore()};
+    }
+    throw new Error('unknown tool: ' + name);
+}
+
+function send(message) {
+    process.stdout.write(JSON.stringify(message) + '\n');
+}
+
+function handle(msg) {
+    if (msg.method === 'initialize') {
+        send({
+            jsonrpc: '2.0',
+            id: msg.id,
+            result: {
+                protocolVersion: msg.params?.protocolVersion ?? '2024-11-05',
+                capabilities: {tools: {}},
+                serverInfo: {name: 'oreate-ui-inspector', version: '0.0.0'},
+            },
+        });
+        return;
+    }
+    if (msg.method === 'notifications/initialized') {
+        return;
+    }
+    if (msg.method === 'tools/list') {
+        send({jsonrpc: '2.0', id: msg.id, result: {tools: TOOLS}});
+        return;
+    }
+    if (msg.method === 'tools/call') {
+        try {
+            const result = callTool(msg.params?.name);
+            send({
+                jsonrpc: '2.0',
+                id: msg.id,
+                result: {content: [{type: 'text', text: JSON.stringify(result, null, 4)}]},
+            });
+        } catch (error) {
+            send({jsonrpc: '2.0', id: msg.id, error: {code: -32000, message: String(error)}});
+        }
+        return;
+    }
+    if (msg.id !== undefined) {
+        send({jsonrpc: '2.0', id: msg.id, error: {code: -32601, message: 'method not found: ' + msg.method}});
+    }
+}
+
+const rl = createInterface({input: process.stdin});
+rl.on('line', line => {
+    const text = line.trim();
+    if (!text) {
+        return;
+    }
+    try {
+        handle(JSON.parse(text));
+    } catch {
+        // 坏帧直接丢弃，不回错（没有可用的 id 关联）
+    }
+});

package/package.json

@@ -1,6 +1,36 @@
 {
-  "name": "comate-ui-inspector",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "comate-ui-inspector",
+    "version": "0.1.0",
+    "description": "按住 Alt 点选页面元素，把「元素 + Vue 组件源码路径」交给 Comate 定位源码修改。浏览器扩展 + Native Messaging host + MCP + hook。",
+    "type": "module",
+    "license": "MIT",
+    "bin": {
+        "ui-inspector": "./cli.mjs"
+    },
+    "files": [
+        "cli.mjs",
+        "extension",
+        "mcp",
+        "hooks",
+        "README.md"
+    ],
+    "engines": {
+        "node": ">=18"
+    },
+    "os": [
+        "darwin",
+        "linux"
+    ],
+    "keywords": [
+        "comate",
+        "vue",
+        "inspector",
+        "native-messaging",
+        "mcp",
+        "devtools"
+    ],
+    "publishConfig": {
+        "registry": "https://registry.npmjs.org",
+        "access": "public"
+    }
+}