terminal-bridge-setup 2.9.1 → 3.0.0

package/files/proxy/server.js

@@ -13,6 +13,7 @@
 
 import { WebSocketServer } from "ws";
 import { randomBytes } from "node:crypto";
+import { decode as msgpackDecode } from "@msgpack/msgpack";
 import { writeFileSync, unlinkSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
@@ -53,6 +54,206 @@ function sendToExtension(obj) {
   return false;
 }
 
+// ===================== WS 监听（tap）通道 =====================
+// 非终端页面（Yearning SQL 结果等）没有 xterm/prompt，无法走命令配对。
+// Agent 客户端发 {type:"tap-start", urlIncludes:"..."} 注册后，代理把
+// URL 匹配的原始 ws-recv 帧以 {type:"tap-frame", ...} 转发给它，由 Agent
+// 自行解析协议。与终端命令通道互不影响（终端配对只吃终端特征 URL）。
+const tapClients = new Map();  // ws -> { urlIncludes, tabId? }
+let activeYearningTabId = null;  // background 选中的 Yearning tab
+
+function broadcastTap(payload) {
+  // 内部 Yearning 编排等待者也吃一份（yr-run 等结果帧）
+  feedYearningWaiters(payload);
+  if (tapClients.size === 0) return;
+  const url = (payload && payload.url) || "";
+  for (const [client, filter] of tapClients) {
+    if (client.readyState !== client.OPEN) continue;
+    // url 匹配则转发；url 为空也转发（CDP 在 attach 前建立的连接会错过
+    // webSocketCreated，帧拿不到 url——宁可多送让客户端判断，不能静默丢弃）
+    if (filter.tabId != null && payload.tabId != null && filter.tabId !== payload.tabId) continue;
+    if (url && url.indexOf(filter.urlIncludes) === -1) continue;
+    try {
+      client.send(JSON.stringify({
+        type: "tap-frame",
+        tabId: payload.tabId,
+        url,
+        data: payload.data,
+        opcode: payload.opcode,
+        t: payload.t
+      }));
+    } catch {}
+  }
+}
+
+// ===================== Yearning SQL 自动化编排 =====================
+// Agent 发 {type:"yr-run", sql, timeoutMs}：
+//   1. yr-cmd sql-set   → 插件把 SQL 注入 Yearning 编辑器（CodeMirror/monaco/DOM）
+//   2. yr-cmd query-click → 插件点「查询」按钮
+//   3. 等 tap 帧里出现 results != null 的结果帧（msgpack 解码）→ resolve 返回
+// 前置条件：用户已在 Yearning 页面点「📡 监听当前页 WS」（tap tab 存在）。
+const yrCmdWaiters = new Map();  // reqId -> resolve
+const yrRunWaiters = new Set();  // { tryConsume(payload) -> boolean }
+
+function sendYrCmd(sub, sql, tabId) {
+  const reqId = genReqId();
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      yrCmdWaiters.delete(reqId);
+      resolve({ ok: false, error: `yr-cmd ${sub} timeout` });
+    }, 5000);
+    yrCmdWaiters.set(reqId, (res) => {
+      clearTimeout(timer);
+      resolve(res);
+    });
+    const ok = sendToExtension({ type: "yr-cmd", sub, sql, reqId, tabId });
+    if (!ok) {
+      yrCmdWaiters.delete(reqId);
+      clearTimeout(timer);
+      resolve({ ok: false, error: "extension not connected" });
+    }
+  });
+}
+
+// 插件回的 yr-result：唤醒对应的 yr-cmd 等待者
+function handleYrResult(msg) {
+  const waiter = yrCmdWaiters.get(msg.reqId);
+  if (waiter) {
+    yrCmdWaiters.delete(msg.reqId);
+    waiter({ ok: !!msg.ok, via: msg.via, error: msg.error, info: msg.editor || msg.buttons });
+  }
+}
+
+// tap 帧喂给 yr-run 等待者：结果帧（msgpack 解码后 results 非空）被消费。
+// 没有 yr-run 等待者时（用户在页面上手点「查 询」），同样生成 CSV 导出记录——
+// 桥接查询和手动查询的产出统一进 popup 列表。
+function feedYearningWaiters(payload) {
+  const url = (payload && payload.url) || "";
+  if (url && url.indexOf("sql.meiyunji.net") === -1) return;
+  const frameTabId = payload && payload.tabId;
+
+  const opcode = payload && payload.opcode;
+  const data = payload && payload.data;
+  if (opcode !== 2 || typeof data !== "string") return;
+  let obj = null;
+  try {
+    obj = msgpackDecode(Buffer.from(data, "base64"));
+  } catch { return; }
+  if (!obj || obj.results == null) return;  // 心跳帧忽略
+
+  let consumed = false;
+  if (yrRunWaiters.size > 0) {
+    for (const waiter of [...yrRunWaiters]) {
+      // tabId 双向可识别时严格隔离；帧缺 tabId（attach 前建立的旧 WS 连接，
+      // CDP 拿不到 webSocketCreated）时：仅当恰好只有一个 waiter 才兜底消费——
+      // 多 waiter 场景宁可不消费走超时，也不能猜错页面串结果。
+      if (waiter.tabId != null && payload.tabId != null && waiter.tabId !== payload.tabId) continue;
+      if (waiter.tabId != null && payload.tabId == null && yrRunWaiters.size > 1) continue;
+      if (waiter.tryConsume(obj)) { consumed = true; break; }
+    }
+  }
+
+  // 未被 yr-run 消费的结果帧 = 手动查询（或 yr-run 已完成后的重复帧），
+  // 也生成 CSV 记录。同一帧 yr-run 路径已经发过 export，不重复。
+  if (!consumed) {
+    const rows = Array.isArray(obj.results)
+      ? obj.results.map(t => (t && t.data ? t.data.length : 0)).reduce((a, b) => a + b, 0)
+      : 0;
+    sendToExtension({
+      type: "yr-export-csv",
+      reqId: "manual-" + genReqId(),
+      tabId: frameTabId ?? activeYearningTabId,
+      sql: "manual-query",
+      rows,
+      payload: JSON.stringify(obj),
+    });
+  }
+}
+
+async function handleYrRun(ws, msg) {
+  const reqId = msg.reqId || genReqId();
+  const sql = (msg.sql || "").toString();
+  const tabId = msg.tabId != null ? Number(msg.tabId) : activeYearningTabId;
+  const timeoutMs = Math.min(Number(msg.timeoutMs || 60000), 300000);
+  if (!sql.trim()) {
+    ws.send(JSON.stringify({ type: "result", reqId, ok: false, error: "empty sql" }));
+    return;
+  }
+
+  // 结果帧等待者：收到第一个 results 非空帧即完成
+  let settled = false;
+  const runEntry = {
+    tabId,
+    sentAt: Date.now(),
+    tryConsume: (obj) => {
+      if (settled) return true;
+      settled = true;
+      yrRunWaiters.delete(runEntry);
+      console.log(TAG, `[yr-run ${reqId}] 结果帧到达（query_time=${obj.query_time ?? "?"}）`);
+      // 同步发给插件：浏览器侧生成 CSV 落下载（popup 可见、可重新下载）
+      sendToExtension({
+        type: "yr-export-csv",
+        reqId,
+        tabId: tabId ?? activeYearningTabId,
+        sql: sql.slice(0, 120),
+        rows: Array.isArray(obj.results)
+          ? obj.results.map(t => (t && t.data ? t.data.length : 0)).reduce((a, b) => a + b, 0)
+          : 0,
+        payload: JSON.stringify(obj),
+      });
+      ws.send(JSON.stringify({
+        type: "result", reqId, ok: true,
+        output: JSON.stringify(obj),
+        elapsedMs: Date.now() - runEntry.sentAt,
+      }));
+      return true;
+    },
+  };
+  yrRunWaiters.add(runEntry);
+
+  const timer = setTimeout(() => {
+    if (settled) return;
+    settled = true;
+    yrRunWaiters.delete(runEntry);
+    ws.send(JSON.stringify({
+      type: "result", reqId, ok: false, error: "timeout",
+      message: "Yearning 查询未在时限内返回结果帧（确认页面已点「监听当前页 WS」且查询能正常执行）",
+      elapsedMs: Date.now() - runEntry.sentAt,
+    }));
+  }, timeoutMs);
+
+  // 1. 注入 SQL
+  const setRes = await sendYrCmd("sql-set", sql, tabId);
+  if (!setRes.ok) {
+    if (!settled) {
+      settled = true;
+      yrRunWaiters.delete(runEntry);
+      clearTimeout(timer);
+      ws.send(JSON.stringify({ type: "result", reqId, ok: false, error: "sql-set failed: " + (setRes.error || ""), message: "SQL 注入 Yearning 编辑器失败" }));
+    }
+    return;
+  }
+  console.log(TAG, `[yr-run ${reqId}] SQL 已注入（via ${setRes.via}）`);
+
+  // 2. 点「查询」
+  const clickRes = await sendYrCmd("query-click", "", tabId);
+  if (!clickRes.ok) {
+    if (!settled) {
+      settled = true;
+      yrRunWaiters.delete(runEntry);
+      clearTimeout(timer);
+      ws.send(JSON.stringify({
+        type: "result", reqId, ok: false,
+        error: "query-click failed: " + (clickRes.error || ""),
+        message: "未找到「查询」按钮；页面按钮: " + JSON.stringify(clickRes.info || []).slice(0, 300),
+      }));
+    }
+    return;
+  }
+  console.log(TAG, `[yr-run ${reqId}] 已点「查询」（via ${clickRes.via}），等待结果帧...`);
+  // 3. 结果帧由 feedYearningWaiters 消费（timer 兜底）
+}
+
 // ===================== 请求-响应配对 =====================
 // pending: reqId -> { resolve, timer, buffer, cmd, sentAt }
 //
@@ -676,9 +877,64 @@ wss.on("connection", (ws, req) => {
       return;
     }
 
+    // --- Agent 发来的 Yearning SQL 查询（注入编辑器 + 点查询 + 收 WS 结果）---
+    if (msg.type === "yr-run") {
+      handleYrRun(ws, msg);
+      return;
+    }
+    if (msg.type === "yr-result") {
+      handleYrResult(msg);
+      return;
+    }
+    if (msg.type === "yr-active-tab") {
+      activeYearningTabId = msg.tabId != null ? Number(msg.tabId) : null;
+      console.log(TAG, `[yr] active tab = ${activeYearningTabId}`);
+      return;
+    }
+    if (msg.type === "yr-ping") {
+      // 探测：编辑器类型 + 查询按钮（不执行任何操作）
+      sendYrCmd("ping", "", msg.tabId != null ? Number(msg.tabId) : activeYearningTabId).then(r => {
+        ws.send(JSON.stringify({ type: "result", reqId: msg.reqId || "", ok: r.ok, output: JSON.stringify({ via: r.via, error: r.error, info: r.info }, null, 1) }));
+      });
+      return;
+    }
+    if (msg.type === "yr-set") {
+      // 只注入 SQL 不点查询（用户手动点，配合 tap 探针收结果）
+      sendYrCmd("sql-set", msg.sql || "", msg.tabId != null ? Number(msg.tabId) : activeYearningTabId).then(r => {
+        ws.send(JSON.stringify({ type: "result", reqId: msg.reqId || "", ok: r.ok, output: JSON.stringify({ via: r.via, error: r.error }) }));
+      });
+      return;
+    }
+
+    // --- Agent 发来的 WS 监听（tap）请求：非终端页面（Yearning 等）的帧流 ---
+    if (msg.type === "tap-start") {
+      const urlIncludes = (msg.urlIncludes || "").toString();
+      if (!urlIncludes) {
+        ws.send(JSON.stringify({ type: "tap-error", error: "missing urlIncludes" }));
+        return;
+      }
+      const tapTabId = msg.tabId != null ? Number(msg.tabId) : null;
+      tapClients.set(ws, { urlIncludes, tabId: tapTabId });
+      console.log(TAG, `tap client 已注册 (urlIncludes=${urlIncludes}, tabId=${tapTabId}, total=${tapClients.size})`);
+      ws.send(JSON.stringify({ type: "tap-started", urlIncludes }));
+      return;
+    }
+    if (msg.type === "tap-stop") {
+      tapClients.delete(ws);
+      console.log(TAG, `tap client 已注销 (total=${tapClients.size})`);
+      ws.send(JSON.stringify({ type: "tap-stopped" }));
+      return;
+    }
+
     // --- 插件上报的 WS 帧 ---
     if (msg.type === "ws-recv") {
-      handleWsRecv(msg.payload);
+      // 先喂 tap 通道（按 URL 过滤转发原始帧），再喂终端配对。
+      // 终端配对只吃终端特征的 URL（koko / arthas / 空 = 旧插件不带 url），
+      // 防止 tap 页面（Yearning JSON 帧）污染终端命令的输出配对。
+      broadcastTap(msg.payload);
+      const frameUrl = (msg.payload && msg.payload.url) || "";
+      const isTerminalUrl = !frameUrl || /\/koko\/ws|connectArthas/i.test(frameUrl);
+      if (isTerminalUrl) handleWsRecv(msg.payload);
       return;
     }
     if (msg.type === "ws-send") {
@@ -707,6 +963,9 @@ wss.on("connection", (ws, req) => {
 
   ws.on("close", () => {
     clients.delete(ws);
+    if (tapClients.delete(ws)) {
+      console.log(TAG, `tap client 已断开 (total=${tapClients.size})`);
+    }
     if (ws === extensionWs) {
       extensionWs = null;
       console.log(TAG, "extension 已断开");

package/files/proxy/tap-example.mjs

@@ -0,0 +1,137 @@
+// WS 监听（tap）探针客户端 —— 捕获非终端页面（Yearning 等）的 WebSocket 帧
+//
+// 用法：
+//   node tap-example.mjs <urlIncludes> [maxFrames] [maxSeconds] [--quiet] [--csv]
+//   node tap-example.mjs sql.meiyunji.net          # 监听 URL 含该关键字的帧，直到 Ctrl+C
+//   node tap-example.mjs sql.meiyunji.net 20 60    # 收满 20 帧或 60 秒退出
+//   node tap-example.mjs sql.meiyunji.net 0 300 --quiet --csv  # 只看有效帧并把每次查询结果存 CSV
+//
+// 工作原理：连本地代理发 tap-start，代理把插件 CDP 抓到的、URL 匹配的
+// ws-recv 原始帧以 tap-frame 转发过来。opcode=2 的帧 data 是 base64，
+// 本脚本自动解码后打印。配合插件 popup 的「📡 监听当前 Yearning 页」按钮使用。
+// --csv：结果帧（results 数组）自动转 CSV 保存到当前目录（yearning-<时间戳>.csv，
+//        多结果集会带 -1/-2 序号；带 BOM，Excel 直接打开中文不乱码）。
+
+import WebSocket from "ws";
+import { decode as msgpackDecode } from "@msgpack/msgpack";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { cwd } from "node:process";
+
+const BRIDGE = process.env.BRIDGE || "ws://127.0.0.1:8787/ssh";
+const urlIncludes = process.argv[2] || "";
+const maxFrames = Number(process.argv[3] || 0);   // 0 = 不限
+const maxSeconds = Number(process.argv[4] || 0);  // 0 = 不限
+const quiet = process.argv.includes("--quiet");   // 跳过心跳帧，只打印有效负载
+const csvExport = process.argv.includes("--csv"); // 结果帧自动保存 CSV
+
+// CSV cell 转义：含逗号/引号/换行的值加引号，内部引号翻倍（RFC 4180）
+function csvCell(value) {
+  if (value == null) return "";
+  const s = String(value);
+  if (/[",\r\n]/.test(s)) return '"' + s.replace(/"/g, '""') + '"';
+  return s;
+}
+
+if (!urlIncludes) {
+  console.error("用法: node tap-example.mjs <urlIncludes> [maxFrames] [maxSeconds]");
+  process.exit(1);
+}
+
+const ws = new WebSocket(BRIDGE);
+let frames = 0;
+let bytes = 0;
+
+ws.on("open", () => {
+  console.log(`→ tap-start (urlIncludes=${urlIncludes})`);
+  console.log("  请在浏览器目标页面操作（如执行 SQL 查询），帧将实时打印：\n");
+  ws.send(JSON.stringify({ type: "tap-start", urlIncludes }));
+});
+
+ws.on("message", (raw) => {
+  let msg;
+  try { msg = JSON.parse(raw.toString()); } catch { return; }
+
+  if (msg.type === "tap-started") {
+    console.log(`✓ 监听已建立（${msg.urlIncludes}）\n`);
+    return;
+  }
+  if (msg.type === "tap-error") {
+    console.error("✗ tap-error:", msg.error);
+    process.exit(1);
+  }
+  if (msg.type !== "tap-frame") return;
+
+  let text = msg.data || "";
+  if (msg.opcode === 2 && text) {
+    // 二进制帧：CDP 给的是 base64。解码后若像 MessagePack（map/array/str 头）
+    // 自动 msgpack 解码成 JSON 展示（Yearning 走 msgpack 二进制帧）
+    const buf = Buffer.from(text, "base64");
+    const first = buf[0];
+    const looksMsgpack =
+      (first >= 0x80 && first <= 0x8f) || first === 0xde || first === 0xdf ||
+      first === 0x91 || (first >= 0x90 && first <= 0x9f);
+    if (looksMsgpack) {
+      try {
+        text = JSON.stringify(msgpackDecode(buf), null, 1);
+      } catch {
+        text = buf.toString("utf8");  // 解码失败退回原文（乱码但可见）
+      }
+    } else {
+      text = buf.toString("utf8");
+    }
+  }
+
+  // --quiet：跳过纯心跳帧（results 为 null 且 heartbeat=pong），只打印有效负载帧
+  if (quiet && text.includes('"results": null')) return;
+
+  // CSV 导出：结果帧（results 数组）自动落盘。
+  // 每个 result 元素是一张表（field=列定义 data=数据行），多表写多个文件。
+  if (csvExport) {
+    let obj = null;
+    try { obj = JSON.parse(text); } catch {}
+    if (obj && Array.isArray(obj.results) && obj.results.length > 0) {
+      const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+      obj.results.forEach((table, idx) => {
+        if (!table || !Array.isArray(table.field)) return;
+        const headers = table.field.map(f => csvCell(f.title || f.dataIndex || ""));
+        const rows = (table.data || []).map(row =>
+          table.field.map(f => csvCell(row[f.dataIndex])).join(",")
+        );
+        const csv = "\uFEFF" + [headers.join(","), ...rows].join("\r\n") + "\r\n";
+        const file = join(cwd(), `yearning-${stamp}${obj.results.length > 1 ? "-" + (idx + 1) : ""}.csv`);
+        writeFileSync(file, csv, "utf8");
+        console.log(`💾 CSV 已保存: ${file}（${rows.length} 行）`);
+      });
+    }
+  }
+
+  frames++;
+  bytes += text.length;
+
+  console.log(`--- frame #${frames} [${new Date(msg.t || Date.now()).toISOString()}] opcode=${msg.opcode} len=${text.length} url=${msg.url || "(unknown)"} ---`);
+  console.log(text.length > 6000 ? text.slice(0, 6000) + `\n...[截断，共 ${text.length} 字符]` : text);
+  console.log("");
+
+  if (maxFrames > 0 && frames >= maxFrames) {
+    console.log(`✓ 已收满 ${maxFrames} 帧（共 ${bytes} 字符），退出`);
+    process.exit(0);
+  }
+});
+
+ws.on("error", (err) => {
+  console.error("✗ ws error:", err.message);
+  process.exit(1);
+});
+
+if (maxSeconds > 0) {
+  setTimeout(() => {
+    console.log(`✓ 到达 ${maxSeconds}s 时限（收帧 ${frames} 个 / ${bytes} 字符），退出`);
+    process.exit(0);
+  }, maxSeconds * 1000);
+}
+
+process.on("SIGINT", () => {
+  console.log(`\n✓ 手动停止（收帧 ${frames} 个 / ${bytes} 字符）`);
+  process.exit(0);
+});

package/files/proxy/yr-example.mjs

@@ -0,0 +1,110 @@
+// Yearning SQL 自动化客户端
+//
+// 用法：
+//   node yr-example.mjs ping                 # 探测编辑器/按钮
+//   node yr-example.mjs "SELECT 1"           # 执行查询（注入+点查询+收结果）
+//   node yr-example.mjs "SELECT ..." 30000   # 指定超时 ms
+//   node yr-example.mjs "SELECT ..." 60000 --csv  # 结果另存 CSV（当前目录）
+//
+// 多页面时用环境变量指定目标 tab：YEARNING_TAB_ID=123 node yr-example.mjs "..."
+// 不指定时使用 popup「Yearning 监听」列表中选中的页面。
+//
+// 前置：Yearning 页面已开 + popup 已点「📡 监听当前 Yearning 页」；多页面时先选中目标 tab
+
+import WebSocket from "ws";
+import { randomBytes } from "node:crypto";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { cwd } from "node:process";
+
+const BRIDGE = process.env.BRIDGE || "ws://127.0.0.1:8787/ssh";
+const selectedTabId = process.env.YEARNING_TAB_ID ? Number(process.env.YEARNING_TAB_ID) : undefined;
+
+function yrRun(msg, timeoutMs) {
+  return new Promise((resolve) => {
+    const ws = new WebSocket(BRIDGE);
+    const reqId = randomBytes(4).toString("hex");
+    let settled = false;
+    const finish = (r) => {
+      if (settled) return;
+      settled = true;
+      try { ws.close(); } catch {}
+      resolve(r);
+    };
+    const fallback = setTimeout(
+      () => finish({ ok: false, error: "client timeout" }),
+      timeoutMs + 5000
+    );
+    ws.on("open", () => ws.send(JSON.stringify({ type: "yr-run", reqId, tabId: selectedTabId, ...msg })));
+    ws.on("message", (raw) => {
+      let m;
+      try { m = JSON.parse(raw.toString()); } catch { return; }
+      if (m.type === "result" && m.reqId === reqId) {
+        clearTimeout(fallback);
+        finish({ ok: !!m.ok, output: m.output, error: m.error, message: m.message, elapsedMs: m.elapsedMs });
+      }
+    });
+    ws.on("error", (err) => { clearTimeout(fallback); finish({ ok: false, error: "ws error: " + err.message }); });
+  });
+}
+
+// CSV cell 转义：含逗号/引号/换行的值加引号，内部引号翻倍（RFC 4180）
+function csvCell(value) {
+  if (value == null) return "";
+  const s = String(value);
+  if (/[",\r\n]/.test(s)) return '"' + s.replace(/"/g, '""') + '"';
+  return s;
+}
+
+// 结果 JSON（yr-run output）转 CSV 文件。多结果集写多个文件。
+function saveResultCsv(jsonText) {
+  let obj;
+  try { obj = JSON.parse(jsonText); } catch { return; }
+  if (!Array.isArray(obj.results)) return;
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  obj.results.forEach((table, idx) => {
+    if (!table || !Array.isArray(table.field)) return;
+    const headers = table.field.map(f => csvCell(f.title || f.dataIndex || ""));
+    const rows = (table.data || []).map(row =>
+      table.field.map(f => csvCell(row[f.dataIndex])).join(",")
+    );
+    const csv = "\uFEFF" + [headers.join(","), ...rows].join("\r\n") + "\r\n";
+    const file = join(cwd(), `yearning-${stamp}${obj.results.length > 1 ? "-" + (idx + 1) : ""}.csv`);
+    writeFileSync(file, csv, "utf8");
+    console.log(`💾 CSV 已保存: ${file}（${rows.length} 行）`);
+  });
+}
+
+const mode = process.argv[2] || "ping";
+const csvExport = process.argv.includes("--csv");
+
+if (mode === "ping") {
+  const ws = new WebSocket(BRIDGE);
+  ws.on("open", () => ws.send(JSON.stringify({ type: "yr-ping", reqId: randomBytes(4).toString("hex"), tabId: selectedTabId })));
+  ws.on("message", (raw) => {
+    let m;
+    try { m = JSON.parse(raw.toString()); } catch { process.exit(1); }
+    if (m.type !== "result") return;
+    console.log(m.ok ? "✓ ping ok" : "✗ ping failed");
+    console.log(m.output || m.error || "");
+    process.exit(m.ok ? 0 : 1);
+  });
+  ws.on("error", (e) => { console.error("✗", e.message); process.exit(1); });
+  setTimeout(() => { console.error("✗ timeout"); process.exit(1); }, 8000);
+} else {
+  const cliArgs = process.argv.slice(2).filter(a => a !== "--csv");
+  const sql = cliArgs[0];
+  const timeoutMs = Number(cliArgs[1] || 60000);
+  console.log(`→ yr-run${selectedTabId ? ` [tab ${selectedTabId}]` : ""}: ${sql.slice(0, 100)}`);
+  const r = await yrRun({ sql, timeoutMs }, timeoutMs);
+  if (r.ok) {
+    console.log(`✓ ok (${r.elapsedMs}ms)`);
+    if (csvExport) saveResultCsv(r.output);
+    console.log(r.output);
+  } else {
+    console.error(`✗ failed: ${r.error}`);
+    if (r.message) console.error(r.message);
+    if (r.output) console.log(r.output);
+    process.exit(1);
+  }
+}

package/files/skill/SKILL.md

@@ -100,6 +100,8 @@ cd ~/.terminal-bridge/proxy && node server.js &
 
 多终端场景：如果同时开了 JumpServer 和 Arthas 两个 tab，代理命令只会发给 popup 里"当前选中"的那个 tab。切换用 popup 的 tab 选择器，或让用户在 popup 点选。
 
+Yearning 场景：popup 的「Yearning 监听」会列出所有已监听页面，并显示数据库名、数据源、host 和当前标记。多个 Yearning 页面同时打开时，必须先点击列表项选择「当前 Yearning 页面」，SQL 只会注入该页面，结果也按 tab 隔离，不会串页。
+
 如果用户说"命令没反应"或"inject-failed"：
 1. `chrome://extensions/` 刷新 Terminal Bridge 插件 ↻
 2. 让用户在终端页面按 F5 刷新（让 content script 重新识别 xterm）

package/files/skill/references/protocol.md

@@ -13,7 +13,28 @@
 - **插件（Chrome extension background）**：唯一，连上后发 `hello{role:extension}` 声明身份。负责上报 WS 帧、接收注入指令。
 - **Agent**：可有多个。发 `run` 请求，收 `result` 响应。
 
-## 完整消息列表
+## Yearning 多页面监听
+
+Yearning 页面必须先在 popup 的「Yearning 监听」列表中监听并选择一个页面。
+每个监听项包含页面标题、数据库名/数据源、host 和 tabId；`✓ 当前 Yearning 页面`
+表示 SQL 自动化的目标页面，`● 当前浏览器页`表示用户当前正在看的 tab。
+
+- 多个 Yearning 页面可以同时监听，但 SQL 只会注入到选中的 active tab。
+- 结果帧带 `tabId`，代理只消费与目标 tab 相同的结果，避免多个页面串结果。
+- 手动客户端可通过环境变量显式指定：`YEARNING_TAB_ID=123 node yr-example.mjs "show index from t_dk_message__8;"`
+- `yr-run` 未传 `tabId` 时使用 popup 当前选中的 Yearning 页面。
+
+### Yearning 自动化消息
+
+```json
+{ "type": "yr-run", "reqId": "abc123", "sql": "show index from t_dk_message__8;", "timeoutMs": 60000, "tabId": 123 }
+```
+
+`yr-run` 会注入 SQL、点击 Yearning 的「查 询」按钮，并等待该 tab 的 MessagePack
+WebSocket 结果帧。Yearning 结果帧是 opcode=2 二进制帧，解码后通常为
+`{ export, error, results, query_time, status, heartbeat, is_only }`。
+
+### 完整消息列表
 
 ### Agent → 代理
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "terminal-bridge-setup",
-  "version": "2.9.1",
+  "version": "3.0.0",
   "description": "一次性安装器：释放终端桥接（JumpServer / Arthas）的本地代理 + Chrome 插件，并注册 native messaging host。让 Agent 能通过浏览器 xterm 终端执行命令并拿回输出。",
   "license": "MIT",
   "author": "encorearon",