terminal-bridge-setup 2.8.0 → 2.9.1

package/files/proxy/client-example.mjs

@@ -24,7 +24,7 @@ const BRIDGE = process.env.BRIDGE || "ws://127.0.0.1:8787/ssh";
  * @param {number} timeoutMs - 超时（默认 10s）
  * @returns {Promise<{ok: boolean, output?: string, error?: string, suggest?: string, message?: string}>}
  */
-function run(cmd, timeoutMs = 10000) {
+function run(cmd, timeoutMs = 10000, opts = {}) {
   return new Promise((resolve) => {
     const ws = new WebSocket(BRIDGE);
     const reqId = randomBytes(4).toString("hex");
@@ -47,7 +47,12 @@ function run(cmd, timeoutMs = 10000) {
     };
 
     ws.on("open", () => {
-      ws.send(JSON.stringify({ type: "run", reqId, cmd, timeoutMs }));
+      // base64 通道：命令 base64 编码后由代理包装成 `echo <b64> | base64 -d | sh`。
+      // 用于多层引号场景（Bash→mjs→SSH→kubectl exec→sh -c），彻底规避引号剥离。
+      const payload = { type: "run", reqId, timeoutMs };
+      if (opts.b64) payload.cmdB64 = Buffer.from(cmd, "utf8").toString("base64");
+      else payload.cmd = cmd;
+      ws.send(JSON.stringify(payload));
     });
 
     ws.on("message", (raw) => {
@@ -85,10 +90,11 @@ function run(cmd, timeoutMs = 10000) {
  * @param {function} ask - 可选的自定义询问函数，默认用 readline 控制台提问。
  *                         Agent 接入时应传入自己的 AskUserQuestion 逻辑。
  *                         签名: async (message) => boolean
+ * @param {object} opts - 可选，透传给 run()：{ b64: true } 走 base64 通道
  * @returns {Promise<{ok: boolean, output?: string, error?: string}>}
  */
-async function runWithSudoRetry(cmd, timeoutMs = 10000, ask = defaultAsk) {
-  let result = await run(cmd, timeoutMs);
+async function runWithSudoRetry(cmd, timeoutMs = 10000, ask = defaultAsk, opts = {}) {
+  let result = await run(cmd, timeoutMs, opts);
 
   if (result.error === "sudo-required") {
     const approved = await ask(result.message || "检测到需要 sudo 权限，是否切换到 root 后重试？");
@@ -103,7 +109,7 @@ async function runWithSudoRetry(cmd, timeoutMs = 10000, ask = defaultAsk) {
     }
     // 切成功后重发原命令
     console.log("→ 重新执行原命令");
-    result = await run(cmd, timeoutMs);
+    result = await run(cmd, timeoutMs, opts);
   }
 
   return result;
@@ -178,20 +184,26 @@ async function runWithArthasGuard(cmd, timeoutMs = 10000, ask = defaultAsk) {
 }
 
 // --- CLI ---
-const cmd = process.argv[2] || "uname -a";
-const timeoutMs = Number(process.argv[3] || 10000);
-
-console.log(`→ run: ${cmd}`);
+// 用法：node client-example.mjs [--b64] "<cmd>" [timeoutMs]
+//   --b64  命令经 base64 通道下发（多层引号场景防剥离，kubectl exec 刚需）
+const cliArgs = process.argv.slice(2).filter(a => a !== "--b64");
+const useB64 = process.argv.slice(2).includes("--b64");
+const cmd = cliArgs[0] || "uname -a";
+const timeoutMs = Number(cliArgs[1] || 10000);
+const runOpts = { b64: useB64 };
+
+console.log(`→ run${useB64 ? " [b64]" : ""}: ${cmd}`);
 // 自动判断用哪种 wrapper：Arthas 命令走 guard，其他走 sudo 重试
 const { isArthasCommand } = await import("./arthas-guard.js");
 const result = isArthasCommand(cmd)
   ? await runWithArthasGuard(cmd, timeoutMs)
-  : await runWithSudoRetry(cmd, timeoutMs);
+  : await runWithSudoRetry(cmd, timeoutMs, undefined, runOpts);
 if (result.ok) {
   console.log(`✓ ok (${result.elapsedMs}ms)`);
   console.log(result.output);
 } else {
   console.error(`✗ failed: ${result.error || "unknown"}`);
+  if (result.message) console.error(result.message);
   if (result.output) console.log("--- partial output ---\n" + result.output);
   process.exit(1);
 }

package/files/proxy/server.js

@@ -70,11 +70,42 @@ function genReqId() {
 }
 
 // Agent 发来的 run 请求
+// 支持两种命令下发方式：
+//   { cmd: "..." }          —— 明文命令（原有）
+//   { cmdB64: "<base64>" }  —— base64 编码命令（多层引号场景的安全传参通道）
+//       代理解码后包装成 `echo <b64> | base64 -d | sh` 下发：
+//       base64 字符集（A-Za-z0-9+/=）不含引号/空格/元字符，四层引号嵌套
+//       （Bash→mjs→SSH→kubectl exec→sh -c）下也不会被任何一层剥离篡改。
 function handleRun(ws, msg) {
   const reqId = msg.reqId || genReqId();
-  const cmd = (msg.cmd || "").toString();
   const timeoutMs = Number(msg.timeoutMs || DEFAULT_TIMEOUT_MS);
 
+  let cmd;
+  let wrapped = null;  // 实际注入终端的完整文本（base64 通道时为 wrapper 命令）
+
+  if (msg.cmdB64) {
+    // base64 通道：解码 → 校验 → 包装
+    let decoded;
+    try {
+      decoded = Buffer.from(String(msg.cmdB64), "base64").toString("utf8");
+    } catch {
+      ws.send(JSON.stringify({ type: "result", reqId, ok: false, error: "invalid cmdB64" }));
+      return;
+    }
+    if (!decoded.trim()) {
+      ws.send(JSON.stringify({ type: "result", reqId, ok: false, error: "empty cmd" }));
+      return;
+    }
+    if (decoded.length > 16 * 1024) {
+      ws.send(JSON.stringify({ type: "result", reqId, ok: false, error: "cmd too long (max 16KB after decode)" }));
+      return;
+    }
+    cmd = decoded;
+    wrapped = `echo ${Buffer.from(cmd, "utf8").toString("base64")} | base64 -d | sh`;
+  } else {
+    cmd = (msg.cmd || "").toString();
+  }
+
   if (!cmd) {
     ws.send(JSON.stringify({ type: "result", reqId, ok: false, error: "empty cmd" }));
     return;
@@ -109,7 +140,7 @@ function handleRun(ws, msg) {
     }
   }
 
-  const job = { ws, reqId, cmd: finalCmd, timeoutMs, sentAt: Date.now() };
+  const job = { ws, reqId, cmd: finalCmd, wrapped, timeoutMs, sentAt: Date.now() };
   queue.push(job);
   maybeRunNext();
 }
@@ -129,12 +160,14 @@ function maybeRunNext() {
   // 关键：prompt 是服务端 shell 在命令完成后输出的，不受 kitty 输入重绘影响。
   //
   // 流程：
-  //   1. 发 cmd + \r
+  //   1. 发 cmd + \r（base64 通道时发 `echo <b64> | base64 -d | sh` + \r）
   //   2. 在 ws-recv 流里累积，找 prompt 正则匹配（]\s*[#$]\s*$ 在行尾）
   //   3. 第一次匹配到 prompt：说明之前的 buffer 含"上一条命令的尾部 prompt + cmd 回显"，
   //      从这个 prompt 之后开始才是本命令的输出区域
   //   4. 第二次匹配到 prompt：命令执行完毕，两个 prompt 之间就是输出
-  const wrapped = `${job.cmd}\r`;
+  // 注：wrapped 优先用 handleRun 传入的 base64 wrapper（此时终端回显的是 wrapper
+  // 命令而非原始 cmd，回显清理必须按 wrapper 比对才能删掉）。
+  const wrapped = `${job.wrapped != null ? job.wrapped : job.cmd}\r`;
 
   // 状态机：
   //   phase 0 (wait_prompt_1) : 等 prompt 第 1 次出现（命令回显前的 prompt）
@@ -144,6 +177,7 @@ function maybeRunNext() {
       if (pending.has(job.reqId)) {
         clearTimeout(entry.timer);
         if (entry.weakTimer != null) { clearTimeout(entry.weakTimer); entry.weakTimer = null; }
+        if (entry.ps2Timer != null) { clearTimeout(entry.ps2Timer); entry.ps2Timer = null; }
         pending.delete(job.reqId);
         try {
           job.ws.send(JSON.stringify({ type: "result", reqId: job.reqId, ...result }));
@@ -156,6 +190,8 @@ function maybeRunNext() {
     phase: 0,
     buffer: "",
     cmd: job.cmd,
+    // 回显清理用的比对串：base64 通道下终端实际回显的是 wrapper 命令
+    echoCmd: job.wrapped != null ? job.wrapped : job.cmd,
     promptCount: 0
   };
   pending.set(job.reqId, entry);
@@ -168,7 +204,7 @@ function maybeRunNext() {
     entry.resolve({
       ok: false,
       error: "timeout",
-      output: cleanOutput(entry.buffer, entry.cmd),
+      output: finalizeOutput(entry),
       elapsedMs: Date.now() - job.sentAt
     });
   }, job.timeoutMs);
@@ -362,6 +398,40 @@ function handleWsRecv(payload) {
       continue;  // 已 resolve，跳过后续 prompt 检测
     }
 
+    // ====== PS2 续行快速失败（问题 3，必须在 prompt 匹配之前）======
+    // 多层引号在某层被剥离/篡改后，远端 shell 因引号未闭合进入续行等待，
+    // 终端显示行首孤立的 >（PS2 提示符）。此时 prompt 锚点永远不会命中 →
+    // 死等超时。检测到孤立 > 且 400ms 无新数据时立即失败并 Ctrl+C 退出续行
+    // （终端回到正常 prompt，可继续执行后续命令），返回明确的错误类型。
+    // 顺序关键：unknown 类型的宽松兜底正则含裸 >，PS2 的 > 若先落到那里
+    // 会被误判成"命令完成"（实测：ok + 空输出），所以 PS2 必须先检查。
+    if (entry.phase === 0 && /^\s*>$/.test(lastNonEmptyLine(entry.buffer))) {
+      if (entry.ps2Timer == null) {
+        const ps2SnapLen = entry.buffer.length;
+        entry.ps2Timer = setTimeout(() => {
+          entry.ps2Timer = null;
+          if (!pending.has(reqId) || entry.buffer.length !== ps2SnapLen) return;
+          if (!/^\s*>$/.test(lastNonEmptyLine(entry.buffer))) return;
+          console.warn(TAG, `[${reqId}] PS2 续行命中（未闭合引号），快速失败 + Ctrl+C 退出续行`);
+          sendCtrlC();
+          entry.resolve({
+            ok: false,
+            error: "unterminated-quote",
+            message: "命令疑似包含未闭合的引号/括号，远端 shell 进入续行等待（PS2 >）。已自动 Ctrl+C 退出续行。多层引号场景请改用 base64 通道下发命令。",
+            suggest: "用 client 的 --b64 参数（或 run 帧的 cmdB64 字段）下发，规避多层引号剥离",
+            output: finalizeOutput(entry),
+            elapsedMs: Date.now() - entry.sentAt
+          });
+        }, 400);
+      }
+      // PS2 等待期间不做 prompt 匹配（下一帧数据到达会重新进入本循环）
+      continue;
+    }
+    if (entry.ps2Timer != null) {
+      clearTimeout(entry.ps2Timer);
+      entry.ps2Timer = null;
+    }
+
     // 检查清理后 buffer 的尾部是否以 prompt 结尾
     // 用按终端类型选出的正则（截断根治：jumpserver 不再被裸 > 误触发）
     const tail = cleanFull.slice(-200);
@@ -375,8 +445,8 @@ function handleWsRecv(payload) {
         // 早已流过（attach 之前）。我们注入 cmd 后，第一个出现的 prompt 就是
         // 命令完成后的 prompt。所以只需等 1 个 prompt。
         // buffer 里 = kitty 重绘碎片 + cmd 回显 + 真实输出 + 最终 prompt
-        // 切掉末尾 prompt，前面的内容交给 cleanOutput 清理（删 prompt 行、碎片）
-        const output = cleanOutput(entry.buffer, entry.cmd);
+        // 切掉末尾 prompt，前面的内容交给清理器（finalizeOutput 含空兜底）
+        const output = finalizeOutput(entry);
         entry.resolve({
           ok: true,
           output,
@@ -403,7 +473,7 @@ function handleWsRecv(payload) {
               entry.lastScanLen = entry.buffer.length;
               entry.resolve({
                 ok: true,
-                output: cleanOutput(entry.buffer, entry.cmd),
+                output: finalizeOutput(entry),
                 elapsedMs: Date.now() - entry.sentAt
               });
             }
@@ -446,11 +516,13 @@ function probeLog(data, opcode) {
 
 // ===================== 输出清理 =====================
 // prompt 锚点方案：buffer = kitty 重绘碎片 + cmd 回显 + 真实输出 + 最终 prompt
-// 清理策略：
+// 清理策略（收紧：只删确定属于终端噪音的内容，其余原样保留）：
 //   1. 去 ANSI（颜色、OSC 标题）
-//   2. 删含 prompt 模式的行（命令回显行，含粘在前面的碎片）
-// 注：kitty 重绘碎片（cmd 文本的片段）可能残留几行，但不影响 Agent 理解输出。
-// 不做 cmd 子串清理——它会误删真实输出（如 cmd="echo hello"，输出"hello"会被删）。
+//   2. 控制字符替换为空格（NUL/x00 等，/proc/*/cmdline 场景；绝不因含控制字符丢整段）
+//   3. 删 prompt 行（要求 prompt 出现在行首附近，且 #$ 紧跟 prompt——
+//      旧行为 "]/…任意内容…/#$" 会把含 ] 和 $ 的长 JSON 输出整行误删，即问题 1 根因）
+//   4. 删 koko 控制消息行
+//   5. 删命令回显行（折行感知：终端宽度折行会把长命令拆成多行，先做软换行 join 再比对）
 function cleanOutput(text, cmd) {
   if (!text) return "";
   let out = text
@@ -458,23 +530,39 @@ function cleanOutput(text, cmd) {
     .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "")
     // ANSI OSC 序列：ESC ] ... BEL 或 ESC \（标题设置等）
     .replace(/\x1b\][^\x07\x1b]*(\x07|\x1b\\)/g, "")
+    // 控制字符 → 空格：NUL 等 C0 控制符（保留 \t\n\r，它们在下一步处理）。
+    // /proc/*/cmdline、environ 都是 NUL 分隔，替换而非丢弃（问题 2）
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, " ")
     // \r\n 和孤立 \r → \n
     .replace(/\r\n?/g, "\n");
 
-  // 删除 prompt 行：
-  //   - shell 风格（红帽系）：行里出现 [user@host /cwd]# 或 ]$ → 整行删
-  //     （删 "[root@host ~]# echo hello" 这种命令回显行，含粘在前面的碎片）
-  //   - shell 风格（Ubuntu/Debian，无方括号）：user@host:~/path$ 结尾的行
-  //   - Arthas 风格：行尾是 arthas@xxx> 或单独的 > → 整行删
+  // 删除 prompt 行（命令回显行 = prompt + 命令文本，可能粘有 kitty 重绘碎片）：
+  //   - 红帽系：[user@host /cwd]# —— user/host 段各限长 64（真实 prompt 远短于此）。
+  //     不限长时的实测反例（Case A）：head -c 600 截断的 JSON 无闭合 ]，
+  //     "data":[ 的 [ 落在前缀窗口内，[^\]]+ 跨过整段 JSON 匹配到 prompt 的 @…]
+  //     → 647 字符合并行整行被误删。长度约束让这种跨吞匹配失败。
+  //   - Ubuntu/Debian：user@host:~/path$ —— 同样限长
+  //   - Arthas：行尾 > 且行短（≤60 字符）
+  // 前缀窗口 40 字符：正常 prompt 行 prompt 就在行首；碎片通常几到几十字符。
   out = out.split("\n").filter(line => {
-    if (/\[[^\]\n]+@[^\]\n]+\][^\n]*[#$]/.test(line)) return false;
-    // Ubuntu prompt 行（含粘在命令回显前的情况）
-    if (/[\w.-]+@[\w.-]+:\S*[$#]\s*$/.test(line)) return false;
+    if (/^.{0,40}\[[^\]\n]{1,64}@[^\]\n]{1,64}\]\s*[#$]/.test(line)) return false;
+    if (/^.{0,40}[\w.-]{1,64}@[\w.-]{1,64}:[^\s]{0,128}[$#]/.test(line)) return false;
     // Arthas / 通用 REPL prompt：行尾 > （允许前面有 arthas@xxx 等前缀）
     if (/>\s*$/.test(line) && line.trim().length <= 60) return false;
     return true;
   }).join("\n");
 
+  // 行尾 prompt 后缀剥离：无尾换行的输出（head -c N 截断）会与后续 prompt
+  // 合并成同一物理行。上面的整行过滤（带前缀窗口）会放过这种合并行——内容
+  // 保住了，但 prompt 碎片粘在输出尾巴上（如 JSON 尾 + [root@host dir]#），
+  // 污染 Agent 的后续解析。这里只剥离行尾的 prompt 形态后缀，内容原样保留。
+  out = out.split("\n").map(line => {
+    if (line.length <= 100) return line;  // 短行已由整行过滤处理，避免误伤
+    return line
+      .replace(/\[[^\]\n]{1,64}@[^\]\n]{1,64}\]\s*[#$]\s*$/, "")   // 红帽系后缀
+      .replace(/[\w.-]{1,64}@[\w.-]{1,64}:[^\s]{0,128}[$#]\s*$/, ""); // Ubuntu 后缀
+  }).join("\n");
+
   // 删除 koko 控制消息：koko 偶尔在终端流里发送 JSON 控制消息
   // （TERMINAL_RESIZE、PING 等），特征是以 {"id": 开头的 JSON 行（可能前面带 # ）
   out = out.split("\n").filter(line => {
@@ -483,14 +571,33 @@ function cleanOutput(text, cmd) {
     return true;
   }).join("\n");
 
-  // 删除命令回显行：整行（去空白后）等于 cmd 的行
-  // 注意是精确匹配整行，不是子串——避免误删真实输出
-  if (cmd) {
+  // 删除命令回显行：整行（去空白后）等于 cmd 的行。
+  // 折行感知（问题 4）：长命令在终端宽度处折行会拆开 token（--com\nmand=），
+  // 单行比对失败 → 残留回显碎片。这里允许把连续 1-4 行 join 后再与 cmd 比对，
+  // 匹配则整组删除。只做"合并后完全相等"的精确匹配，不做子串匹配（防误删真实输出）。
+  if (cmd && cmd.trim()) {
     const cmdNoWs = cmd.replace(/\s+/g, "");
-    out = out.split("\n").filter(line => {
-      const lineNoWs = line.replace(/\s+/g, "");
-      return lineNoWs !== cmdNoWs;
-    }).join("\n");
+    const lines = out.split("\n");
+    const kept = [];
+    let i = 0;
+    while (i < lines.length) {
+      let matched = false;
+      let joinedNoWs = "";
+      for (let k = 0; i + k < lines.length; k++) {
+        joinedNoWs += lines[i + k].replace(/\s+/g, "");
+        if (joinedNoWs.length > cmdNoWs.length) break;
+        if (joinedNoWs === cmdNoWs) {
+          i += k + 1;
+          matched = true;
+          break;
+        }
+      }
+      if (!matched) {
+        kept.push(lines[i]);
+        i++;
+      }
+    }
+    out = kept.join("\n");
   }
 
   return out
@@ -498,6 +605,38 @@ function cleanOutput(text, cmd) {
     .trim();
 }
 
+// ===================== 输出兜底（问题 1 的安全网）=====================
+// 两层防御：
+//   1. 清理后为空 + 原始内容 ≥512 字符 → 返回截断原始内容 + warning
+//   2. 清理损失率 >80%（原始 ≥512 字符但清理后 <20%）→ 保留清理结果，
+//      但附加 warning + 原始内容截断——任何未来的 filter 误杀都不再静默
+// （Case A 教训：REDHAT 正则曾跨吞 647 字节合并行，靠这层兜底可暴露）
+const RAW_FALLBACK_THRESHOLD = 512;   // 原始内容低于此值视为真无输出
+const RAW_FALLBACK_LIMIT = 4000;      // 兜底输出截断长度
+
+function finalizeOutput(entry) {
+  const echoCmd = entry.echoCmd != null ? entry.echoCmd : entry.cmd;
+  const cleaned = cleanOutput(entry.buffer, echoCmd);
+
+  const raw = stripAnsi(entry.buffer)
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, " ")
+    .replace(/\r\n?/g, "\n")
+    .trim();
+  if (raw.length < RAW_FALLBACK_THRESHOLD) return cleaned;
+
+  const truncated = raw.length > RAW_FALLBACK_LIMIT
+    ? raw.slice(0, RAW_FALLBACK_LIMIT) + "\n...[truncated]"
+    : raw;
+
+  if (cleaned.length === 0) {
+    return truncated + `\n[warning] output filtered to empty by cleaner; raw ${raw.length} chars shown]`;
+  }
+  if (cleaned.length < raw.length * 0.2) {
+    return cleaned + `\n[warning] cleaner dropped ${(100 - Math.round(cleaned.length / raw.length * 100))}% of output; raw tail:\n${truncated}`;
+  }
+  return cleaned;
+}
+
 // ===================== WebSocket 服务 =====================
 const wss = new WebSocketServer({ host: HOST, port: PORT });
 

package/files/skill/SKILL.md

@@ -120,6 +120,10 @@ node client-example.mjs "uname -a"
 node client-example.mjs "df -h" 15000              # 第二参数是超时 ms
 node client-example.mjs "ps aux | grep java" 20000
 
+# 多层引号场景（kubectl exec / 嵌套引号）：加 --b64 走 base64 通道，
+# 命令经 base64 编码下发（echo <b64> | base64 -d | sh），任何一层都不会剥离引号
+node client-example.mjs --b64 "kubectl exec -n ns pod -- sh -c 'ps aux | grep java'"
+
 # Arthas 场景
 node client-example.mjs "help"
 node client-example.mjs "thread"                    # 查看线程概况
@@ -259,6 +263,8 @@ Agent → 代理：
 | `error: arthas-forbidden` | Arthas 高风险命令（retransform/profiler/stop/reset）被禁用 | 告知用户去浏览器 Arthas 终端手动执行，不要重试或绕过 |
 | `error: arthas-needs-limit` | 中风险命令（trace/watch/stack/monitor）缺 -n/#cost（严格模式） | 按 suggest 补参数重发，或加 `-n 1` |
 | `error: arthas-quota-exceeded` | 中风险命令会话内超限（默认 20 次） | 告知用户已达上限，不要重试；如需继续重启代理 |
+| `error: unterminated-quote` | 命令含未闭合引号，远端 shell 卡在 PS2 续行（已自动 Ctrl+C 退出） | 检查引号配对；多层引号场景改用 `--b64` 通道重发 |
+| 输出末尾带 `[warning] output filtered to empty...` | 清理器把输出过滤为空，兜底返回了原始内容（截断） | 输出可用但含终端噪音；原命令输出被判定为 prompt 噪音时可调整命令（如拆行） |
 | `error: timeout` + output 含 `[sudo] password` | 旧版代理未实现 sudo 检测 | 升级 proxy/server.js；临时用绝对路径 `/bin/cat` 绕过 |
 | `error: timeout` + output 为空 | 命令是交互式/持续刷新（vim/dashboard/monitor） | 改用非交互等价命令，或 Arthas 用一次性命令（thread/jad） |
 | 命令发出去但 Arthas/JumpServer 没反应 | content script 没识别到 xterm | 让用户 F5 刷新终端页，或在 popup 点"捕捉 xterm" |

package/files/skill/references/protocol.md

@@ -27,9 +27,14 @@
 }
 ```
 - `reqId`：可选。不传则代理生成（8 位 hex）。用于配对 result。
-- `cmd`：必填。命令本身，**不要自己加哨兵/换行**——代理会自动包末尾 `\r`。
+- `cmd`：必填（与 `cmdB64` 二选一）。命令本身，**不要自己加哨兵/换行**——代理会自动包末尾 `\r`。
   - JumpServer：linux 命令，如 `ps aux | grep java`
   - Arthas：Arthas 命令，如 `jad com.foo.Bar`
+- `cmdB64`：可选，与 `cmd` 二选一。命令的 base64 编码（UTF-8）。
+  代理解码后包装成 `echo <b64> | base64 -d | sh` 下发——base64 字符集不含
+  引号/空格/元字符，Bash→mjs→SSH→kubectl exec→sh -c 多层引号嵌套下也不会
+  被任何一层剥离篡改。kubectl exec / 嵌套引号场景**必须**用这个通道。
+  限制：解码后 ≤16KB。client 侧对应 `--b64` 参数。
 - `timeoutMs`：可选，默认 10000。超时则返回 `ok:false, error:timeout`。
 
 ### 代理 → Agent
@@ -50,14 +55,23 @@
   "type": "result",
   "reqId": "abc123",
   "ok": false,
-  "error": "timeout | inject failed | extension disconnected | sudo-required | arthas-forbidden | arthas-needs-limit | arthas-quota-exceeded",
+  "error": "timeout | inject failed | extension disconnected | sudo-required | arthas-forbidden | arthas-needs-limit | arthas-quota-exceeded | unterminated-quote",
   "output": "部分输出（可能为空）",
   "suggest": "更安全的替代命令（部分错误才有）",
   "message": "给用户看的说明文字（部分错误才有）",
   "elapsedMs": 10000
 }
 ```
-- `output`：prompt 锚点出现前的所有 recv 帧拼接，已去 ANSI、`\r\n`→`\n`、删 prompt 行和命令回显行、首尾 trim。
+- `output`：prompt 锚点出现前的所有 recv 帧拼接，已去 ANSI、`\r\n`→`\n`、
+  控制字符（NUL 等）替换为空格、删 prompt 行和命令回显行（折行感知）、
+  剥离行尾 prompt 后缀（无尾换行输出与 prompt 合并形态）、首尾 trim。
+  prompt 段识别带长度约束（user/host 各 ≤64 字符），防止截断 JSON 的 `[`
+  被当作 prompt 起点跨吞整行（Case A 根因）。
+  **双层兜底**：清理后为空或清理损失率 >80%（原始 ≥512 字符）时，附加
+  `[warning]` + 截断原始内容——绝不静默丢弃大段输出。
+- `unterminated-quote`：命令含未闭合引号，远端 shell 卡在 PS2 续行（`>` 提示）。
+  代理检测到后 ~400ms 快速失败并自动 Ctrl+C 退出续行（终端可继续用），
+  `suggest` 会指向 base64 通道。
 - `error` 枚举：
   - `timeout` — 命令超时（交互式/持续命令会触发）
   - `inject failed` — content script 注入失败（xterm 没捕捉到）

package/package.json

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