cc-viewer 1.6.310 → 1.6.312

package/server/lib/pty-flood-coalescer.js

@@ -81,6 +81,12 @@ const DEFAULT_PT_COALESCE_MS = envIntAllowZero('CCV_FLOOD_PT_COALESCE_MS', 16);
  * @param {(buf: string, rawStart: number) => number} opts.findSafeSliceStart - ANSI 安全截断（pty-manager 导出）
  * @param {(buffered: number) => void} [opts.onFloodStart] - 进入限流态（observability 埋点）
  * @param {() => void} [opts.onFloodEnd] - 回落直通态
+ * @param {(droppedChars: number) => void} [opts.onTruncate] - 本轮洪泛**实际丢过字节**且已回落直通时触发
+ *   （紧随 onFloodEnd 之后，每轮洪泛至多一次，携带累计丢弃量）。安全切片只保证残片不上屏，
+ *   被截掉的中段对增量 TUI 流（macOS/Linux forkpty）不会自愈——调用方应在此用权威快照
+ *   （getOutputBuffer → data-resync）对齐客户端画面。洪泛进行中不触发：中途 resync 快照
+ *   立刻过期且加重负载，回落时一次终态对齐即可。reset()/dispose() 清零累计（resync 路径
+ *   自身就是快照对齐，无需重复触发）。
  * @param {number} [opts.flushMs]
  * @param {number} [opts.floodThresholdBytesPerWin]
  * @param {number} [opts.fallbackWins]
@@ -97,6 +103,7 @@ export function createFloodCoalescer({
   findSafeSliceStart,
   onFloodStart,
   onFloodEnd,
+  onTruncate,
   flushMs = DEFAULT_FLUSH_MS,
   floodThresholdBytesPerWin = DEFAULT_FLOOD_THRESHOLD,
   fallbackWins = DEFAULT_FALLBACK_WINS,
@@ -111,6 +118,7 @@ export function createFloodCoalescer({
   let pending = '';
   let winBytes = 0;       // 当前桶累计字节（直通态由 offer 累计，限流态由 flush 结算）
   let calmWins = 0;       // 连续低于阈值的桶数
+  let droppedChars = 0;   // 本轮洪泛累计实际丢弃的字符数（>0 时回落触发 onTruncate）
   let flushTimer = null;  // 限流态周期 flush；直通态下亦作为桶边界 timer（见 offer）
   let ptBuffer = '';      // 直通态微合并缓冲（窗口开启期间到达的后续 chunk）
   let ptTimer = null;     // 直通态微合并窗口 timer（16ms），与 flushTimer（33ms 字节桶）并存、职责正交
@@ -157,7 +165,9 @@ export function createFloodCoalescer({
     // 保证洪泛期送达客户端的字节率 ≤ flushBudgetBytes/flushMs，与前端消化速率同量级。
     if (pending.length > flushBudgetBytes) {
       const rawStart = pending.length - flushBudgetBytes;
-      pending = pending.slice(findSafeSliceStart(pending, rawStart));
+      const safeStart = findSafeSliceStart(pending, rawStart);
+      droppedChars += safeStart;
+      pending = pending.slice(safeStart);
     }
     const merged = SYNC_BEGIN + pending + SYNC_END;
     pending = '';
@@ -179,6 +189,13 @@ export function createFloodCoalescer({
       flooding = false;
       calmWins = 0;
       try { onFloodEnd?.(); } catch { }
+      // 本轮洪泛丢过字节 → 回落后通知一次终态对齐（见 opts.onTruncate doc）。
+      // 置零在调用**前**：回调内若同步 reset()/re-offer 不会重复触发。
+      if (droppedChars > 0) {
+        const dropped = droppedChars;
+        droppedChars = 0;
+        try { onTruncate?.(dropped); } catch { }
+      }
       return; // 不再续约 timer，回直通
     }
     flushTimer = setTimer(onFloodTick, flushMs);
@@ -227,6 +244,7 @@ export function createFloodCoalescer({
       if (pending.length > pendingCap) {
         const rawStart = pending.length - trimTo;
         const safeStart = findSafeSliceStart(pending, rawStart);
+        droppedChars += safeStart;
         pending = pending.slice(safeStart);
       }
     },
@@ -239,6 +257,7 @@ export function createFloodCoalescer({
       winBytes = 0;
       calmWins = 0;
       flooding = false;
+      droppedChars = 0; // resync 路径调用本方法，快照即对齐，不再补发 onTruncate
     },
     isFlooding() {
       return flooding;
@@ -250,6 +269,7 @@ export function createFloodCoalescer({
       stopPtTimer();
       pending = '';
       ptBuffer = '';
+      droppedChars = 0;
     },
   };
 }

package/server/pty-manager.js

@@ -6,6 +6,7 @@ import { platform, arch, homedir } from 'node:os';
 import { createRequire } from 'node:module';
 import { prepareEmbeddedShellSpawn, stripClaudeNoFlickerUnlessOptedIn } from './lib/terminal-env.js';
 import { killPtyTree } from './lib/term-signals.js';
+import { findSafeSliceStart } from './lib/ansi-safe-slice.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -35,6 +36,9 @@ let _spawnInflight = null;
 const PTY_COLS_MIN = 2, PTY_COLS_MAX = 1000;
 const PTY_ROWS_MIN = 1, PTY_ROWS_MAX = 1000;
 const MAX_BUFFER = 200000;
+// 裁剪滞回：超 MAX_BUFFER 触发后一次裁到 TRIM_TO，而非每个 chunk 都裁到 MAX_BUFFER——
+// 把 ~200KB slice 重分配的频率从每 chunk 一次降到每 ~20KB 新输出一次。
+const BUFFER_TRIM_TO = 180000;
 let batchBuffer = '';
 let batchScheduled = false;
 let _ptyImportForTests = null;
@@ -51,47 +55,9 @@ async function getPty() {
   return ptyMod.default || ptyMod;
 }
 
-/**
- * 在 outputBuffer 截断时，找到安全的截断位置，
- * 避免从 ANSI 转义序列中间开始导致终端状态紊乱。
- * 策略：从截断点向后扫描，跳过可能被截断的不完整转义序列。
- * 注意：只保 ANSI 序列边界，不保 DEC 2026 同步标记的配对——
- * 跨 2026 块截断的配平由调用方负责（见 lib/pty-flood-coalescer.js）。
- * export 供洪泛限流器复用同一截断语义。
- */
-export function findSafeSliceStart(buf, rawStart) {
-  // 从 rawStart 开始，向后最多扫描 64 字节寻找安全起点
-  const scanLimit = Math.min(rawStart + 64, buf.length);
-  let i = rawStart;
-  while (i < scanLimit) {
-    const ch = buf.charCodeAt(i);
-    // 如果当前字符是 ESC (0x1b)，可能是新转义序列的开头，
-    // 但也可能是被截断的序列的中间部分，跳过整个序列
-    if (ch === 0x1b) {
-      // 找到 ESC，向后寻找序列结束符（字母字符）
-      let j = i + 1;
-      while (j < scanLimit && !((buf.charCodeAt(j) >= 0x40 && buf.charCodeAt(j) <= 0x7e) && j > i + 1)) {
-        j++;
-      }
-      if (j < scanLimit) {
-        // 找到完整序列末尾，从下一个字符开始是安全的
-        return j + 1;
-      }
-      // 序列不完整，继续扫描
-      i = j;
-      continue;
-    }
-    // 如果字符是 CSI 参数字符 (0x30-0x3f) 或中间字符 (0x20-0x2f)，
-    // 说明我们在转义序列中间，继续向后
-    if ((ch >= 0x20 && ch <= 0x3f)) {
-      i++;
-      continue;
-    }
-    // 普通可见字符或控制字符（非转义相关），这是安全位置
-    break;
-  }
-  return i < buf.length ? i : rawStart;
-}
+// ANSI 安全截断起点：实现迁至 lib/ansi-safe-slice.js（锚点扫描算法，见该文件 doc）。
+// 保持从本模块 export——server.js 解构注入洪泛限流器、单测均从这里导入。
+export { findSafeSliceStart };
 
 // DEC Private Mode 2026 (Synchronized Output) markers.
 // xterm.js 6.0+ 原生支持：收到 BEGIN 后缓存所有写入，收到 END 后一次性渲染，
@@ -297,7 +263,7 @@ async function _spawnClaudeImpl(proxyPort, cwd, extraArgs = [], claudePath = nul
   ptyProcess.onData((data) => {
     outputBuffer += data;
     if (outputBuffer.length > MAX_BUFFER) {
-      const rawStart = outputBuffer.length - MAX_BUFFER;
+      const rawStart = outputBuffer.length - BUFFER_TRIM_TO;
       const safeStart = findSafeSliceStart(outputBuffer, rawStart);
       outputBuffer = outputBuffer.slice(safeStart);
     }
@@ -477,7 +443,7 @@ async function _spawnShellImpl() {
   ptyProcess.onData((data) => {
     outputBuffer += data;
     if (outputBuffer.length > MAX_BUFFER) {
-      const rawStart = outputBuffer.length - MAX_BUFFER;
+      const rawStart = outputBuffer.length - BUFFER_TRIM_TO;
       const safeStart = findSafeSliceStart(outputBuffer, rawStart);
       outputBuffer = outputBuffer.slice(safeStart);
     }

package/server/scratch-pty-manager.js

@@ -5,6 +5,7 @@ import { platform, arch, homedir } from 'node:os';
 import { createRequire } from 'node:module';
 import { prepareEmbeddedShellSpawn } from './lib/terminal-env.js';
 import { killPtyTree } from './lib/term-signals.js';
+import { findSafeSliceStart } from './lib/ansi-safe-slice.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -21,6 +22,8 @@ const STARTUP_CWD = (() => {
 })();
 
 const MAX_BUFFER = 50000;
+// 裁剪滞回：超 MAX_BUFFER 后一次裁到 TRIM_TO，降低每 chunk slice 重分配频率（同 pty-manager.js）
+const BUFFER_TRIM_TO = 45000;
 
 // id -> { ptyProcess, dataListeners, exitListeners, lastExitCode, outputBuffer, lastCols, lastRows, batchBuffer, batchScheduled }
 const ptys = new Map();
@@ -71,26 +74,6 @@ function maybeReap(id, s) {
   }
 }
 
-function findSafeSliceStart(buf, rawStart) {
-  const scanLimit = Math.min(rawStart + 64, buf.length);
-  let i = rawStart;
-  while (i < scanLimit) {
-    const ch = buf.charCodeAt(i);
-    if (ch === 0x1b) {
-      let j = i + 1;
-      while (j < scanLimit && !((buf.charCodeAt(j) >= 0x40 && buf.charCodeAt(j) <= 0x7e) && j > i + 1)) {
-        j++;
-      }
-      if (j < scanLimit) return j + 1;
-      i = j;
-      continue;
-    }
-    if (ch >= 0x20 && ch <= 0x3f) { i++; continue; }
-    break;
-  }
-  return i < buf.length ? i : rawStart;
-}
-
 function flushBatch(s) {
   s.batchScheduled = false;
   if (!s.batchBuffer) return;
@@ -164,7 +147,7 @@ export async function spawnScratch(id) {
     s.ptyProcess.onData((data) => {
       s.outputBuffer += data;
       if (s.outputBuffer.length > MAX_BUFFER) {
-        const rawStart = s.outputBuffer.length - MAX_BUFFER;
+        const rawStart = s.outputBuffer.length - BUFFER_TRIM_TO;
         const safeStart = findSafeSliceStart(s.outputBuffer, rawStart);
         s.outputBuffer = s.outputBuffer.slice(safeStart);
       }

package/server/server.js

@@ -1166,6 +1166,9 @@ async function setupTerminalWebSocket(httpServer) {
 
     // resync nudge 冷却（CCV_RESYNC_NUDGE_COOLDOWN_MS，0 = 不冷却；详见 lib/resync-nudge-gate.js）
     const RESYNC_NUDGE_COOLDOWN_MS = envIntAllowZero('CCV_RESYNC_NUDGE_COOLDOWN_MS', 3000);
+    // 客户端 resync-request 的服务端冷却兜底（客户端 write-queue trim 后自带节流，这里防风暴；
+    // 复用 nudge 门实现，0 = 不冷却）
+    const RESYNC_REQ_COOLDOWN_MS = envIntAllowZero('CCV_RESYNC_REQ_COOLDOWN_MS', 1000);
 
     // 洪泛限流器状态日志（与 makeBpLogger 同款 5s 节流，独立实例不共享计数）。
     // Windows 实机排"切主题/大流量卡死"时据此确认 ConPTY 洪泛是否触发、几次、量级。
@@ -1228,6 +1231,13 @@ async function setupTerminalWebSocket(httpServer) {
       // floodGate 在 bpGate 之后构造（send 闭包依赖 bpGate），onBehind/onResume 经 let 前向引用 reset：
       // resync 快照是唯一真相源，coalescer 残留 pending 不清会把早于快照的旧字节回灌导致画面回退。
       let floodGate = null;
+      // 权威快照对齐：bpGate.onResume / floodGate.onTruncate / 客户端 resync-request 三路共用。
+      // 调用前须 floodGate.reset()（快照已含 pending 字节，残留会在快照后回灌重复）。
+      const sendScratchResync = () => {
+        if (ws.readyState !== 1) return;
+        try { ws.send(JSON.stringify({ type: 'data-resync', data: getScratchOutputBuffer(id) })); } catch {}
+      };
+      const resyncReqGate = createResyncNudgeGate({ cooldownMs: RESYNC_REQ_COOLDOWN_MS });
       const bpGate = createBackpressureGate({
         getBufferedAmount: () => ws.bufferedAmount,
         onBehind: (buffered) => {
@@ -1237,8 +1247,7 @@ async function setupTerminalWebSocket(httpServer) {
         onResume: (buffered) => {
           _bpLog('resume', buffered);
           floodGate?.reset();
-          if (ws.readyState !== 1) return;
-          try { ws.send(JSON.stringify({ type: 'data-resync', data: getScratchOutputBuffer(id) })); } catch {}
+          sendScratchResync();
         },
         onTimeout: (buffered) => {
           _bpLog('timeout', buffered);
@@ -1260,6 +1269,12 @@ async function setupTerminalWebSocket(httpServer) {
         findSafeSliceStart,
         onFloodStart: (bytes) => _floodLog('start', bytes),
         onFloodEnd: () => _floodLog('end', 0),
+        // 洪泛期丢过中段：增量输出流不会自愈，回落直通后用权威快照对齐一次
+        onTruncate: (dropped) => {
+          _floodLog('truncate', dropped);
+          floodGate.reset();
+          sendScratchResync();
+        },
       });
 
       const removeDataListener = onScratchData(id, (data) => {
@@ -1283,6 +1298,12 @@ async function setupTerminalWebSocket(httpServer) {
             writeScratch(id, msg.data);
           } else if (msg.type === 'resize') {
             resizeScratch(id, msg.cols, msg.rows);
+          } else if (msg.type === 'resync-request') {
+            // 客户端 write-queue 积压丢弃后请求快照对齐（utils/terminalWriteQueue.js onTrim）
+            if (resyncReqGate.shouldNudge()) {
+              floodGate.reset();
+              sendScratchResync();
+            }
           } else if (msg.type === 'kill') {
             // 用户主动关闭 tab：杀 pty（killScratch 内部 ptys.delete 后配额自动释放）；前端会随后 close ws
             killScratch(id);
@@ -1352,6 +1373,34 @@ async function setupTerminalWebSocket(httpServer) {
       // 走冷却——nudge 让 ConPTY 再吐全屏重绘 = 新洪泛燃料，紧 behind→resume 循环里反复
       // nudge 会自我维持（客户端每轮 reset+重放快照 = 永久冻结表象）。详见 lib/resync-nudge-gate.js。
       const nudgeGate = createResyncNudgeGate({ cooldownMs: RESYNC_NUDGE_COOLDOWN_MS });
+      const resyncReqGate = createResyncNudgeGate({ cooldownMs: RESYNC_REQ_COOLDOWN_MS });
+      // 权威快照对齐：data-resync 快照无条件发，全屏重绘 nudge 走 nudgeGate 冷却。
+      // bpGate.onResume / floodGate.onTruncate / 客户端 resync-request 三路共用；
+      // 调用前须 floodGate.reset()（快照已含 pending/微合并缓冲字节，残留会在快照后回灌重复）。
+      const sendResync = (buffered = 0) => {
+        if (ws.readyState !== 1) return;
+        try { ws.send(JSON.stringify({ type: 'data-resync', data: getOutputBuffer() })); } catch {}
+        if (!nudgeGate.shouldNudge()) { _bpLog('nudge-skip', buffered); return; }
+        try {
+          if (process.platform !== 'win32') {
+            // POSIX：与下方 _needRedrawBootstrap 同款 SIGWINCH 兜底
+            const pid = getClaudePid();
+            if (pid && pid !== process.pid) process.kill(pid, 'SIGWINCH');
+          } else {
+            // Windows 无 SIGWINCH：resize 抖动经 ConPTY 通知重绘（恢复路径偶发，闪烁可接受）。
+            // 尺寸仲裁与 resize 消息处理一致：移动端优先，否则活跃客户端（activeWs 为 null 时
+            // 本 ws 视为所有者）——恢复的 ws 可能是非权威的慢后台 tab，用它自己的尺寸抖动会把
+            // 共享 PTY 永久改成它的尺寸、挤掉活跃/移动端画面；无权威尺寸则跳过抖动。
+            const mSize = getMobileSize();
+            const size = mSize
+              || ((activeWs === ws || activeWs === null) ? clientSizes.get(ws) : clientSizes.get(activeWs));
+            if (size) {
+              resizePty(size.cols, size.rows + 1);
+              resizePty(size.cols, size.rows);
+            }
+          }
+        } catch {}
+      };
       const bpGate = createBackpressureGate({
         getBufferedAmount: () => ws.bufferedAmount,
         onBehind: (buffered) => {
@@ -1361,28 +1410,7 @@ async function setupTerminalWebSocket(httpServer) {
         onResume: (buffered) => {
           _bpLog('resume', buffered);
           floodGate?.reset();
-          if (ws.readyState !== 1) return;
-          try { ws.send(JSON.stringify({ type: 'data-resync', data: getOutputBuffer() })); } catch {}
-          if (!nudgeGate.shouldNudge()) { _bpLog('nudge-skip', buffered); return; }
-          try {
-            if (process.platform !== 'win32') {
-              // POSIX：与下方 _needRedrawBootstrap 同款 SIGWINCH 兜底
-              const pid = getClaudePid();
-              if (pid && pid !== process.pid) process.kill(pid, 'SIGWINCH');
-            } else {
-              // Windows 无 SIGWINCH：resize 抖动经 ConPTY 通知重绘（恢复路径偶发，闪烁可接受）。
-              // 尺寸仲裁与 resize 消息处理一致：移动端优先，否则活跃客户端（activeWs 为 null 时
-              // 本 ws 视为所有者）——恢复的 ws 可能是非权威的慢后台 tab，用它自己的尺寸抖动会把
-              // 共享 PTY 永久改成它的尺寸、挤掉活跃/移动端画面；无权威尺寸则跳过抖动。
-              const mSize = getMobileSize();
-              const size = mSize
-                || ((activeWs === ws || activeWs === null) ? clientSizes.get(ws) : clientSizes.get(activeWs));
-              if (size) {
-                resizePty(size.cols, size.rows + 1);
-                resizePty(size.cols, size.rows);
-              }
-            }
-          } catch {}
+          sendResync(buffered);
         },
         onTimeout: (buffered) => {
           _bpLog('timeout', buffered);
@@ -1404,6 +1432,13 @@ async function setupTerminalWebSocket(httpServer) {
         findSafeSliceStart,
         onFloodStart: (bytes) => _floodLog('start', bytes),
         onFloodEnd: () => _floodLog('end', 0),
+        // 洪泛期丢过中段：安全切片只保证残片不上屏，被截掉的内容对增量 TUI 流
+        // （macOS/Linux forkpty）不会自愈——回落直通后用权威快照对齐一次
+        onTruncate: (dropped) => {
+          _floodLog('truncate', dropped);
+          floodGate.reset();
+          sendResync();
+        },
       });
 
       // PTY 输出 → WebSocket(合并 ws 后客户端自行按 msg.type 分发,server 端不再 role 过滤)
@@ -1488,6 +1523,12 @@ async function setupTerminalWebSocket(httpServer) {
             } else {
               replyDone(false);
             }
+          } else if (msg.type === 'resync-request') {
+            // 客户端 write-queue 积压丢弃后请求快照对齐（utils/terminalWriteQueue.js onTrim）
+            if (resyncReqGate.shouldNudge()) {
+              floodGate.reset();
+              sendResync();
+            }
           } else if (msg.type === 'ask-hook-answer') {
             // Client answered AskUserQuestion via hook bridge.
             // New protocol: msg.id required to address one of multiple pending asks.