terminal-bridge-setup 3.2.0 → 3.3.0

package/files/proxy/server.js

@@ -23,6 +23,9 @@ import {
   auditArthasCommand,
   isArthasCommand,
 } from "./arthas-guard.js";
+import {
+  validateReadonlySql,
+} from "./yr-sql-guard.js";
 
 const PORT = Number(process.env.PORT || 8787);
 const HOST = process.env.HOST || "127.0.0.1";
@@ -80,6 +83,7 @@ function broadcastTap(payload) {
         url,
         data: payload.data,
         opcode: payload.opcode,
+        dir: payload.dir,   // sent=上行(客户端→服务器)/recv=下行，探针观测口
         t: payload.t
       }));
     } catch {}
@@ -95,18 +99,27 @@ function broadcastTap(payload) {
 const yrCmdWaiters = new Map();  // reqId -> resolve
 const yrRunWaiters = new Set();  // { tryConsume(payload) -> boolean }
 
-function sendYrCmd(sub, sql, tabId) {
+// sub → 配对超时：db-select/source-switch 含点击+枚举+验证的多轮往返，放宽到 25s
+const YR_CMD_TIMEOUT_MS = {
+  "db-select": 25000,
+  "source-switch": 25000,
+};
+const DEFAULT_YR_CMD_TIMEOUT_MS = 5000;
+
+function sendYrCmd(sub, sql, tabId, extra = {}) {
   const reqId = genReqId();
+  const timeoutMs = YR_CMD_TIMEOUT_MS[sub] || DEFAULT_YR_CMD_TIMEOUT_MS;
   return new Promise((resolve) => {
     const timer = setTimeout(() => {
       yrCmdWaiters.delete(reqId);
       resolve({ ok: false, error: `yr-cmd ${sub} timeout` });
-    }, 5000);
+    }, timeoutMs);
     yrCmdWaiters.set(reqId, (res) => {
       clearTimeout(timer);
       resolve(res);
     });
-    const ok = sendToExtension({ type: "yr-cmd", sub, sql, reqId, tabId });
+    // sub=new-sql/db-select/source-switch 时 sql 字段承载目标参数（库名/源名）
+    const ok = sendToExtension({ type: "yr-cmd", sub, sql, reqId, tabId, ...extra });
     if (!ok) {
       yrCmdWaiters.delete(reqId);
       clearTimeout(timer);
@@ -115,12 +128,15 @@ function sendYrCmd(sub, sql, tabId) {
   });
 }
 
-// 插件回的 yr-result：唤醒对应的 yr-cmd 等待者
+// 插件回的 yr-result：唤醒对应的 yr-cmd 等待者。
+// 控制字段外的全部业务负载（editor/buttons/sourceEntry/selects/hash 等）原样下发，
+// 让编排层与探测输出拿到完整的页面回执。
 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 });
+    const { type, reqId, tabId, ...payload } = msg;
+    waiter(payload);
   }
 }
 
@@ -174,21 +190,56 @@ 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);
+  const autoQuery = msg.autoQuery !== false;   // 默认自动点查询（兼容旧客户端）
+  const prepareMode = !autoQuery;
+  // prepare 模式等的是人点「查 询」，时限放宽；普通模式维持原上限
+  const timeoutCap = prepareMode ? 1800000 : 300000;
+  const timeoutDefault = prepareMode ? 600000 : 60000;
+  const timeoutMs = Math.min(Number(msg.timeoutMs || timeoutDefault), timeoutCap);
   if (!sql.trim()) {
     ws.send(JSON.stringify({ type: "result", reqId, ok: false, error: "empty sql" }));
     return;
   }
+  // 只读白名单：写操作在此拒绝，不进页面
+  const guard = validateReadonlySql(sql);
+  if (!guard.ok) {
+    console.warn(TAG, `[yr-run ${reqId}] SQL 白名单拦截: ${guard.error}`);
+    ws.send(JSON.stringify({ type: "result", reqId, ok: false, error: guard.error, message: guard.message }));
+    return;
+  }
 
-  // 结果帧等待者：收到第一个 results 非空帧即完成
+  // 编排失败快速返回：清理 waiter 后回错误
   let settled = false;
+  let timer = null;
+  const failFast = (error, message) => {
+    if (settled) return true;
+    settled = true;
+    yrRunWaiters.delete(runEntry);
+    if (timer) clearTimeout(timer);
+    ws.send(JSON.stringify({ type: "result", reqId, ok: false, error, message }));
+    return true;
+  };
+
+  // 结果帧等待者：收到第一个 results 非空帧即完成
+  const sentAt = Date.now();
   const runEntry = {
     tabId,
-    sentAt: Date.now(),
+    ws,
+    sentAt,
+    abort: () => {
+      // 客户端断开时由 ws close 调用：停定时器并摘除，防死 waiter 残留
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      yrRunWaiters.delete(runEntry);
+    },
     tryConsume: (obj) => {
-      if (settled) return true;
+      // 已完成的 waiter 必须返回 false 放行——返回 true 会"假消费"，
+      // 把后续新 waiter 的结果帧截走饿到超时（死客户端残留时实测踩过）
+      if (settled) return false;
       settled = true;
       yrRunWaiters.delete(runEntry);
+      clearTimeout(timer);
       console.log(TAG, `[yr-run ${reqId}] 结果帧到达（query_time=${obj.query_time ?? "?"}）`);
       // 同步发给插件：浏览器侧生成 CSV 落下载（popup 可见、可重新下载）
       sendToExtension({
@@ -204,54 +255,80 @@ async function handleYrRun(ws, msg) {
       ws.send(JSON.stringify({
         type: "result", reqId, ok: true,
         output: JSON.stringify(obj),
-        elapsedMs: Date.now() - runEntry.sentAt,
+        elapsedMs: Date.now() - sentAt,
       }));
       return true;
     },
   };
   yrRunWaiters.add(runEntry);
 
-  const timer = setTimeout(() => {
+  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,
+      message: prepareMode
+        ? "prepare 模式超时：仍在等待用户点「查 询」后产生的结果帧"
+        : "Yearning 查询未在时限内返回结果帧（确认页面已点「监听当前页 WS」且查询能正常执行）",
+      elapsedMs: Date.now() - 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 编辑器失败" }));
+  // 1. 可选：切数据源（目标名经由 yr-cmd 的 sql 字段携带）
+  if (msg.source) {
+    const srcRes = await sendYrCmd("source-switch", String(msg.source), tabId);
+    if (!srcRes.ok && !failFast(
+      "source-switch failed: " + (srcRes.error || ""),
+      `切换数据源 ${msg.source} 失败；现场证据: ${JSON.stringify(srcRes).slice(0, 800)}`
+    )) {
+      return;
     }
+    console.log(TAG, `[yr-run ${reqId}] 已切数据源 → ${msg.source}（via ${srcRes.via}）`);
+  }
+
+  // 2. 指定目标库时：先显式新建查询 tab 并把 schema 选好，
+  //    再注入 SQL（bg 对空库有 database-not-selected 预检，顺序不能反）
+  let skipNew = false;
+  if (msg.database) {
+    const newRes = await sendYrCmd("new-sql", "", tabId);
+    if (!newRes.ok) {
+      // 零 SQL tab 状态下页面没有「新建」按钮（实测清空 tab 后触发），
+      // 此时本就有现成编辑器——跳过新建直接注入，其余错误照旧快速失败
+      if (String(newRes.error || "").includes("新建按钮未找到")) {
+        console.warn(TAG, `[yr-run ${reqId}] 无「新建」按钮（零 tab 状态），使用当前编辑器`);
+      } else if (!failFast("new-sql failed: " + (newRes.error || ""), "新建查询 tab 失败")) {
+        return;
+      }
+    }
+    const dbRes = await sendYrCmd("db-select", String(msg.database), tabId);
+    if (!dbRes.ok && !failFast(
+      "db-select failed: " + (dbRes.error || ""),
+      `选择数据库 ${msg.database} 失败；现场证据: ${JSON.stringify(dbRes).slice(0, 800)}`
+    )) return;
+    console.log(TAG, `[yr-run ${reqId}] 已选库 → ${msg.database}`);
+    skipNew = true;  // 已建过 tab（或零 tab 状态），sql-set 不再重复新建
+  }
+
+  // 3. 注入 SQL
+  const setRes = await sendYrCmd("sql-set", sql, tabId, { skipNew });
+  if (!setRes.ok && !failFast("sql-set failed: " + (setRes.error || ""), "SQL 注入 Yearning 编辑器失败")) {
     return;
   }
   console.log(TAG, `[yr-run ${reqId}] SQL 已注入（via ${setRes.via}）`);
 
-  // 2. 点「查询」
+  // 4. 点「查询」（autoQuery=false 时留给人点）
+  if (prepareMode) {
+    console.log(TAG, `[yr-run ${reqId}] prepare 完成，等待用户点「查 询」（timeout ${timeoutMs}ms）...`);
+    return;
+  }
   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),
-      }));
-    }
+  if (!clickRes.ok && !failFast("query-click failed: " + (clickRes.error || ""),
+    "未找到「查询」按钮；页面按钮: " + JSON.stringify(clickRes.info || []).slice(0, 300))) {
     return;
   }
   console.log(TAG, `[yr-run ${reqId}] 已点「查询」（via ${clickRes.via}），等待结果帧...`);
-  // 3. 结果帧由 feedYearningWaiters 消费（timer 兜底）
+  // 5. 结果帧由 feedYearningWaiters 消费（timer 兜底）
 }
 
 // ===================== 请求-响应配对 =====================
@@ -892,20 +969,33 @@ wss.on("connection", (ws, req) => {
       return;
     }
     if (msg.type === "yr-ping") {
-      // 探测：编辑器类型 + 查询按钮（不执行任何操作）
+      // 探测：编辑器类型 + 查询按钮 + Select/切源入口/路由（不执行任何操作）
       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) }));
+        ws.send(JSON.stringify({ type: "result", reqId: msg.reqId || "", ok: r.ok, output: JSON.stringify(r, null, 1) }));
       });
       return;
     }
     if (msg.type === "yr-set") {
       // 只注入 SQL 不点查询（用户手动点，配合 tap 探针收结果）
+      const guard = validateReadonlySql(msg.sql || "");
+      if (!guard.ok) {
+        ws.send(JSON.stringify({ type: "result", reqId: msg.reqId || "", ok: false, error: guard.error, output: guard.message }));
+        return;
+      }
       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;
     }
 
+    if (msg.type === "yr-dom-probe") {
+      // 只读 DOM 探测：Select/下拉/弹窗结构（诊断未知 UI 用）
+      sendYrCmd("dom-probe", String(msg.selector || ""), msg.tabId != null ? Number(msg.tabId) : activeYearningTabId).then(r => {
+        ws.send(JSON.stringify({ type: "result", reqId: msg.reqId || "", ok: r.ok, output: JSON.stringify(r, null, 1) }));
+      });
+      return;
+    }
+
     // --- Agent 发来的 WS 监听（tap）请求：非终端页面（Yearning 等）的帧流 ---
     if (msg.type === "tap-start") {
       const urlIncludes = (msg.urlIncludes || "").toString();
@@ -966,6 +1056,13 @@ wss.on("connection", (ws, req) => {
     if (tapClients.delete(ws)) {
       console.log(TAG, `tap client 已断开 (total=${tapClients.size})`);
     }
+    // 客户端断开即摘除其 yr-run 等待者，防止死 waiter 残留截走后续结果帧
+    for (const waiter of [...yrRunWaiters]) {
+      if (waiter.ws === ws) {
+        waiter.abort();
+        console.log(TAG, `[yr-run] 等待者随客户端断开移除 (剩余 ${yrRunWaiters.size})`);
+      }
+    }
     if (ws === extensionWs) {
       extensionWs = null;
       console.log(TAG, "extension 已断开");

package/files/proxy/yr-example.mjs

@@ -1,14 +1,19 @@
 // Yearning SQL 自动化客户端
 //
 // 用法：
-//   node yr-example.mjs ping                 # 探测编辑器/按钮
+//   node yr-example.mjs ping                 # 探测编辑器/按钮/Select/切源入口
 //   node yr-example.mjs "SELECT 1"           # 执行查询（注入+点查询+收结果）
 //   node yr-example.mjs "SELECT ..." 30000   # 指定超时 ms
 //   node yr-example.mjs "SELECT ..." 60000 --csv  # 结果另存 CSV（当前目录）
+//   node yr-example.mjs "SELECT ..." --prepare --db 库名 [--source 数据源名]
+//                                            # 只切源+建tab+选库+写SQL，不点查询；
+//                                            # 挂起等用户手动点「查 询」后收结果
 //
 // 多页面时用环境变量指定目标 tab：YEARNING_TAB_ID=123 node yr-example.mjs "..."
 // 不指定时使用 popup「Yearning 监听」列表中选中的页面。
 //
+// 安全：代理侧只读白名单，仅放行 SELECT/SHOW/DESC/EXPLAIN；写语句一律拒绝。
+//
 // 前置：Yearning 页面已开 + popup 已点「📡 监听当前 Yearning 页」；多页面时先选中目标 tab
 
 import WebSocket from "ws";
@@ -20,6 +25,11 @@ 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 flagValue(name, args) {
+  const i = args.indexOf(name);
+  return i >= 0 ? (args[i + 1] || "") : undefined;
+}
+
 function yrRun(msg, timeoutMs) {
   return new Promise((resolve) => {
     const ws = new WebSocket(BRIDGE);
@@ -77,9 +87,23 @@ function saveResultCsv(jsonText) {
 
 const mode = process.argv[2] || "ping";
 const csvExport = process.argv.includes("--csv");
+const cliSelector = process.argv.slice(3).find(a => !a.startsWith("-")) || "";
 
-if (mode === "ping") {
+if (mode === "probe") {
+  // 只读 DOM 探测：node yr-example.mjs probe [selector]
   const ws = new WebSocket(BRIDGE);
+  ws.on("open", () => ws.send(JSON.stringify({ type: "yr-dom-probe", reqId: randomBytes(4).toString("hex"), tabId: selectedTabId, selector: cliSelector })));
+  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 ? "✓ probe ok" : "✗ probe 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 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;
@@ -94,9 +118,21 @@ if (mode === "ping") {
 } 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);
+  const prepare = cliArgs.includes("--prepare");
+  const database = flagValue("--db", cliArgs);
+  const source = flagValue("--source", cliArgs);
+  // 超时只认纯数字位置参数（第 2 个位置起），跳过 --db/--source 及其值
+  const numericArg = cliArgs.slice(1).find(a => /^\d+$/.test(a));
+  const timeoutMs = Number(numericArg || (prepare ? 600000 : 60000));
+  // prepare 模式默认等用户点查询，client 兜底超时要与等待时限同量级
+  if (prepare && !cliArgs[1]) {
+    console.log(`→ prepare 模式：最多等待 ${timeoutMs / 1000}s 用户点「查 询」`);
+  }
+  const runMsg = { sql, timeoutMs, autoQuery: !prepare };
+  if (database) runMsg.database = database;
+  if (source) runMsg.source = source;
+  console.log(`→ yr-run${prepare ? " [prepare]" : ""}${database ? ` [db ${database}]` : ""}${source ? ` [source ${source}]` : ""}${selectedTabId ? ` [tab ${selectedTabId}]` : ""}: ${sql.slice(0, 100)}`);
+  const r = await yrRun(runMsg, timeoutMs);
   if (r.ok) {
     console.log(`✓ ok (${r.elapsedMs}ms)`);
     if (csvExport) saveResultCsv(r.output);

package/files/proxy/yr-sql-guard.js

@@ -0,0 +1,43 @@
+// Yearning SQL 只读白名单（纯函数，供 server.js 与测试脚本共用）
+//
+// 红线：Yearning 通道只允许只读查询。剥离注释后按分号拆条，逐条校验首动词。
+// 校验放在代理层，yr-run / yr-set / 编排模式全覆盖；不依赖页面端兜底。
+
+// SELECT 前缀下的写副作用例外：INTO OUTFILE/DUMPFILE 写数据库服务器文件、FOR UPDATE 锁行
+const HIDDEN_WRITE_RE = /\binto\s+(outfile|dumpfile)\b|\bfor\s+update\b/i;
+
+export function stripSqlComments(sql) {
+  return String(sql || "")
+    .replace(/\/\*[\s\S]*?\*\//g, " ")  // 块注释
+    .replace(/--[^\n]*/g, " ")          // 行注释
+    .replace(/#[^\n]*/g, " ");          // MySQL # 注释
+}
+
+export function validateReadonlySql(sql) {
+  const statements = stripSqlComments(sql)
+    .split(";")
+    .map(s => s.trim())
+    .filter(s => s.length > 0);
+  if (statements.length === 0) {
+    return { ok: false, error: "empty-sql", message: "SQL 为空" };
+  }
+  for (const stmt of statements) {
+    const verb = (stmt.match(/^\S+/) || [""])[0];
+    const verbUpper = verb.toUpperCase();
+    if (!["SELECT", "SHOW", "DESC", "DESCRIBE", "EXPLAIN"].includes(verbUpper)) {
+      return {
+        ok: false,
+        error: "write-forbidden",
+        message: `非只读语句被拦截（${verb}）。Yearning 通道仅允许 SELECT/SHOW/DESC/EXPLAIN。`,
+      };
+    }
+    if (HIDDEN_WRITE_RE.test(stmt)) {
+      return {
+        ok: false,
+        error: "write-forbidden",
+        message: "SELECT 中含 INTO OUTFILE/DUMPFILE 或 FOR UPDATE 等副作用子句，被拦截。",
+      };
+    }
+  }
+  return { ok: true, statementCount: statements.length };
+}

package/files/skill/SKILL.md

@@ -50,6 +50,19 @@ Arthas 的能力不止于读，以下命令/用法一律禁止通过桥接执行
 
 **Arthas 命令的默认判定**：若命令语法同时支持读和写（如 `vmoption`、`logger`、`ognl`），**默认视为写操作禁止**，只有当且仅当命令形态确认是只读时才允许。
 
+### Yearning 侧——禁止清单
+
+| 类别 | 禁止的 SQL/操作 | 为什么 |
+|------|----------------|--------|
+| 数据写 | `INSERT` / `UPDATE` / `DELETE` / `REPLACE` / `MERGE` | 改业务数据 |
+| 结构写 | `CREATE` / `ALTER` / `DROP` / `TRUNCATE` / `RENAME` | 改表结构 |
+| 事务/锁 | `SET`、`USE`、`LOCK`、`SELECT ... FOR UPDATE` | 改会话状态或锁行 |
+| 服务端副作用 | `SELECT ... INTO OUTFILE/DUMPFILE`、`LOAD_FILE()` | 在数据库服务器上读写文件 |
+
+代理已内置只读白名单（仅放行 SELECT/SHOW/DESC/EXPLAIN），写语句会在代理层直接
+返回 `error:"write-forbidden"`。Agent 收到该错误不要换写法绕过（注释混淆、拆分
+语句等），直接走「用户手动执行」路径。
+
 ### 当用户要求写操作时——标准应对
 
 1. **不要执行，也不要"先执行再看看"**。直接拒绝并说明：桥接是只读诊断通道，写操作需手动。
@@ -230,6 +243,66 @@ Arthas 直接挂在线上 JVM 上，命令不当会拖垮服务。代理内置
 | `ARTHAS_MAX_MEDIUM` | 20 | 中风险命令会话内最大次数 |
 | `ARTHAS_AUTO_PATCH` | 1 | 中风险命令缺限制时：1=自动补 `-n 1`，0=拒绝让 Agent 显式补 |
 
+## Yearning SQL 查询与「备查」协作模式
+
+Yearning（sql.meiyunji.net）页面在 popup「Yearning 监听」里监听并选中后，Agent 可以查数据：
+
+```bash
+cd ~/.terminal-bridge/proxy
+
+# 自动执行：注入 + 点查询 + 收结果
+node yr-example.mjs "show index from t_dk_message__8;" 30000 --csv
+# 指定库/数据源：先切源 → 新建查询 tab → 选 schema → 注入 → 点查询
+node yr-example.mjs "select * from t_order limit 10;" --db dk_order_3 --source dk-test-3 --csv
+# 诊断页面状态（只读）：编辑器/按钮/Select/切源入口/路由
+node yr-example.mjs ping
+node yr-example.mjs probe
+```
+
+### 已知环境（实测 2026-08）
+
+- **数据源清单**（「切换数据源」弹层全量）：`dk-shard-0..7-tdsql-c`、`dk-prod-1-tdsql-c`、`dk-doris`、`dk-chat-1`、`dk-livechat-1`
+- **中心库**：`dk-prod-1-tdsql-c` 的中心库是 `dk1`（其余为 xxl_job 调度库等）；分库分表源（dk-shard-*）内是 `dk_shard`
+- 用户说"xxx 分库"通常指某个 dk-shard-N 源；说"中心库/主库"通常指 dk-prod-1 的 dk1
+
+### 名称不确定时：假名探测（零副作用）
+
+源名/库名拿不准时，用假名跑一次，失败报告会带回**全量候选清单**（弹层会自动关闭）：
+
+```bash
+node yr-example.mjs "select 1;" --source zz_probe --db zz_probe --prepare
+# db-select failed: 下拉中无匹配的库 ... "options":["information_schema","dk1","xxl_job","xxl_job_prod2"]
+```
+
+拿到清单后按语义选目标（如中心库=dk1），再用真名重跑。
+
+### prepare 模式：AI 备查，人点查询（推荐协作流）
+
+用户说"帮我查 xxx 库下 xxx 表的数据"时：
+
+1. **Agent 备好一切但不执行**：
+   ```bash
+   node yr-example.mjs "select ... from t_shop where puid=... limit 20;" --source dk-prod-1-tdsql-c --db dk1 --prepare
+   ```
+   命令依次：切数据源（已在目标源时自动跳过）→ 新建查询 tab（零 tab 状态自动降级用现有编辑器）→
+   antd 下拉选 schema → CDP 注入 SQL → **不点查询**，挂起等待
+   （默认最长 10 分钟，`--prepare` 后可再传超时 ms，上限 30 分钟）。
+2. **告知用户**：「SQL 已就绪，请在 Yearning 页面点击『查 询』」。
+3. **阻塞等待结果帧**。用户点查询后结果自动回传（同一条命令的 stdout 返回 JSON），
+   CSV 同时进 popup 列表；期间可随时向用户同步进度。
+4. **兜底**：若等待超时/连接断开，结果也会以 CSV 形式落在 popup 列表
+   （`~/Downloads/yearning-csv/`），可用 popup 的复制按钮拿到读文件提示词继续干活。
+
+编排失败快速返回明确错误：`source-switch failed`（含候选清单）、`db-select failed`
+（含 options 清单）、`write-forbidden`（只读白名单拦截）、`no tap tab`（需 popup 重新监听选中）。
+
+### 运维注意
+
+- **代理重启会丢内存态**（active Yearning tab 等）：重启后让用户在 popup 重新点选监听页
+- **切源是页面路由切换**（hash 变化），CDP attach 不受影响，tap 监听持续有效
+- **改插件代码后**必须 `chrome://extensions ↻` **再 F5 页面**再 popup 重新选中，
+  顺序不能反；popup 标题旁的版本号可快速确认加载的是否最新代码
+
 ## 消息格式
 
 Agent → 代理：

package/files/skill/references/protocol.md

@@ -34,6 +34,33 @@ Yearning 页面必须先在 popup 的「Yearning 监听」列表中监听并选
 WebSocket 结果帧。Yearning 结果帧是 opcode=2 二进制帧，解码后通常为
 `{ export, error, results, query_time, status, heartbeat, is_only }`。
 
+可选编排参数（执行顺序：切源 → 建查询 tab → 选库 → 注入 SQL → 点查询）：
+
+- `source`：目标数据源名。幂等：已在目标源（URL hash 一致）时直接成功不重复点击。
+  名称不确定时可用假名探测，失败报告带回全量候选。已验证清单：
+  dk-shard-0..7-tdsql-c / dk-prod-1-tdsql-c / dk-doris / dk-chat-1 / dk-livechat-1。
+- `database`：目标库（schema）。显式新建查询 tab 后打开 antd Select 下拉点选，
+  以重读 meta 的 database 值验证。零 SQL tab 状态自动降级为使用现有编辑器。
+  同样支持假名探测（失败带回 options 清单）。
+- `autoQuery`：默认 `true`。设为 `false` 进入 **prepare 模式**——写好 SQL 后
+  不点查询，挂起等待用户手动点「查 询」产生的结果帧；此模式超时默认 600s、
+  上限 1800s。适合「AI 备查、人点查询、结果回传继续干活」的协作流程。
+
+**只读白名单**：代理对下发的 SQL 强制校验（剥注释后逐条），仅放行
+SELECT/SHOW/DESC/EXPLAIN；命中 INTO OUTFILE/DUMPFILE/FOR UPDATE 等副作用子句
+同样拒绝。失败返回 `ok:false, error:"write-forbidden"`。yr-set 路径同受约束。
+
+prepare 模式示例：
+
+```json
+{ "type": "yr-run", "sql": "select * from t_order limit 10;", "source": "dk-prod-1-tdsql-c", "database": "dk1", "autoQuery": false, "timeoutMs": 600000, "tabId": 123 }
+```
+
+诊断消息（均只读）：
+
+- `yr-ping`（客户端 `ping`）：编辑器/按钮/Select 状态/切源入口/路由 hash
+- `yr-dom-probe`（客户端 `probe`）：`.ant-select` 与弹层的 DOM 结构、坐标、meta 现值
+
 ### 完整消息列表
 
 ### Agent → 代理

package/package.json

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