cc-viewer 1.6.300 → 1.6.302

package/dist/index.html

@@ -21,7 +21,7 @@
     // 整体显示大小已弃用 CSS zoom：Electron 改用 webFrame.setZoomFactor（首屏抢占见
     // electron/tab-content-preload.js），纯浏览器交由用户用浏览器自带快捷键缩放，故此处不再设 zoom。
   </script>
-  <script type="module" crossorigin src="/assets/index-BXb1GO0R.js"></script>
+  <script type="module" crossorigin src="/assets/index-DSz9bNGm.js"></script>
   <link rel="modulepreload" crossorigin href="/assets/vendor-antd-Bur5ZxWE.js">
   <link rel="modulepreload" crossorigin href="/assets/vendor-codemirror-Si44UqBp.js">
   <link rel="modulepreload" crossorigin href="/assets/vendor-mdxeditor-Cco3AQJS.js">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-viewer",
-  "version": "1.6.300",
+  "version": "1.6.302",
   "description": "Claude Code Logger visualization management tool",
   "license": "MIT",
   "main": "server.js",

package/server/i18n.js

@@ -448,44 +448,44 @@ const i18nData = {
     "uk": "\nCC Viewer запущено:"
   },
   "server.startedLocal": {
-    "zh": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "en": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "zh-TW": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "ko": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "ja": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "de": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "es": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "fr": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "it": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "da": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "pl": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "ru": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "ar": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "no": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "pt-BR": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "th": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "tr": "  ➜ Local:   {protocol}://127.0.0.1:{port}",
-    "uk": "  ➜ Local:   {protocol}://127.0.0.1:{port}"
+    "zh": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "en": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "zh-TW": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "ko": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "ja": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "de": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "es": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "fr": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "it": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "da": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "pl": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "ru": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "ar": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "no": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "pt-BR": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "th": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "tr": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}",
+    "uk": "  ➜ Local:   {protocol}://127.0.0.1:{port}{basePath}"
   },
   "server.startedNetwork": {
-    "zh": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "en": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "zh-TW": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "ko": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "ja": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "de": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "es": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "fr": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "it": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "da": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "pl": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "ru": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "ar": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "no": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "pt-BR": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "th": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "tr": "  ➜ Network: {protocol}://{ip}:{port}?token={token}",
-    "uk": "  ➜ Network: {protocol}://{ip}:{port}?token={token}"
+    "zh": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "en": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "zh-TW": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "ko": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "ja": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "de": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "es": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "fr": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "it": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "da": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "pl": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "ru": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "ar": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "no": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "pt-BR": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "th": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "tr": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}",
+    "uk": "  ➜ Network: {protocol}://{ip}:{port}{basePath}?token={token}"
   },
   "server.passwordActive": {
     "zh": "  🔒 密码保护已开启，密码: {password}",
@@ -527,6 +527,26 @@ const i18nData = {
     "tr": "  ⚠️  Parola boş: uzaktan erişim doğrulama gerektirmez — güvenlik riski",
     "uk": "  ⚠️  Пароль порожній: віддалений доступ не потребує перевірки — загроза безпеці"
   },
+  "basePath.missingLeadingSlash": {
+    "zh": "  ⚠️  CCV_BASE_PATH \"{value}\" 必须以 \"/\" 开头，已忽略。示例：\"/proxy/\"",
+    "en": "  ⚠️  CCV_BASE_PATH \"{value}\" must start with \"/\" — ignored. Use e.g. \"/proxy/\".",
+    "zh-TW": "  ⚠️  CCV_BASE_PATH \"{value}\" 必須以 \"/\" 開頭，已忽略。範例：\"/proxy/\"",
+    "ko": "  ⚠️  CCV_BASE_PATH \"{value}\"는 \"/\"로 시작해야 합니다 — 무시됨. 예: \"/proxy/\"",
+    "ja": "  ⚠️  CCV_BASE_PATH \"{value}\" は \"/\" で始まる必要があります — 無視されました。例: \"/proxy/\"",
+    "de": "  ⚠️  CCV_BASE_PATH \"{value}\" muss mit \"/\" beginnen — ignoriert. Beispiel: \"/proxy/\"",
+    "es": "  ⚠️  CCV_BASE_PATH \"{value}\" debe comenzar con \"/\" — ignorado. Ejemplo: \"/proxy/\"",
+    "fr": "  ⚠️  CCV_BASE_PATH \"{value}\" doit commencer par \"/\" — ignoré. Exemple : \"/proxy/\"",
+    "it": "  ⚠️  CCV_BASE_PATH \"{value}\" deve iniziare con \"/\" — ignorato. Esempio: \"/proxy/\"",
+    "da": "  ⚠️  CCV_BASE_PATH \"{value}\" skal starte med \"/\" — ignoreret. Eksempel: \"/proxy/\"",
+    "pl": "  ⚠️  CCV_BASE_PATH \"{value}\" musi zaczynać się od \"/\" — zignorowano. Przykład: \"/proxy/\"",
+    "ru": "  ⚠️  CCV_BASE_PATH \"{value}\" должен начинаться с \"/\" — проигнорировано. Пример: \"/proxy/\"",
+    "ar": "  ⚠️  يجب أن يبدأ CCV_BASE_PATH \"{value}\" بـ \"/\" — تم التجاهل. مثال: \"/proxy/\"",
+    "no": "  ⚠️  CCV_BASE_PATH \"{value}\" må starte med \"/\" — ignorert. Eksempel: \"/proxy/\"",
+    "pt-BR": "  ⚠️  CCV_BASE_PATH \"{value}\" deve começar com \"/\" — ignorado. Exemplo: \"/proxy/\"",
+    "th": "  ⚠️  CCV_BASE_PATH \"{value}\" ต้องขึ้นต้นด้วย \"/\" — ถูกละเว้น ตัวอย่าง: \"/proxy/\"",
+    "tr": "  ⚠️  CCV_BASE_PATH \"{value}\" \"/\" ile başlamalıdır — yok sayıldı. Örnek: \"/proxy/\"",
+    "uk": "  ⚠️  CCV_BASE_PATH \"{value}\" має починатися з \"/\" — проігноровано. Приклад: \"/proxy/\""
+  },
   "server.auth.loginTitle": {
     "zh": "请输入访问密码",
     "en": "Enter access password",

package/server/lib/base-path.js

@@ -0,0 +1,34 @@
+// CCV_BASE_PATH（反向代理子路径部署）的统一 normalize / validate / strip。
+// 纯函数，无副作用，server.js（HTTP 剥离 / <base> 注入 / WS upgrade）与 cli.js（启动 URL
+// 打印）共用，消除各处复制粘贴的 normalize 逻辑。vite.config.js 不复用（构建期 base 有
+// `undefined→'/'` 的三态语义，与运行时"未设=无前缀"不同，见该文件注释）。
+
+// 规范化 basePath：未设 / 空串 / 根 '/' → ''（无前缀）；其余补尾斜杠（'/proxy' → '/proxy/'）。
+// 尾斜杠是 startsWith 匹配的防歧义关键（'/proxy/' 不会误命中 '/proxyextra/x'）。
+// 缺前导 '/' 的非法值（'proxy/x'）也返回 ''（忽略）——否则注入段会产出相对 <base> 破坏页面；
+// 告警由 validateBasePath 在启动期负责。
+export function normalizeBasePath(raw) {
+  if (!raw || raw === '/' || !raw.startsWith('/')) return '';
+  // 剥裸换行符：含 \n/\r 的值会把 index.html 注入的 JS 字符串断成语法错误（页面级 DoS）
+  return raw.replace(/[\r\n]/g, '').replace(/\/?$/, '/');
+}
+
+// 校验 + 规范化。非空但缺前导 '/'（如 'proxy/x'）属配置错误：startsWith 永不命中、剥离
+// 静默失效。不自动补 '/' —— 自动修正会掩盖与代理侧前缀的错配，更难排查；这里选择
+// 忽略（按无前缀工作）并返回 i18n key 供启动期 console.warn。
+export function validateBasePath(raw) {
+  if (raw && raw !== '/' && !raw.startsWith('/')) {
+    return { ok: false, normalized: '', warning: 'basePath.missingLeadingSlash' };
+  }
+  return { ok: true, normalized: normalizeBasePath(raw), warning: null };
+}
+
+// 从请求 pathname 剥掉 basePath 前缀，保证结果带前导 '/'（路由表按 '/api/...' 匹配）。
+// slice(length - 1) 让 normalizedBase 的尾斜杠留作结果的前导斜杠：
+//   stripBasePath('/proxy/api/x', '/proxy/') → '/api/x'
+//   stripBasePath('/proxy/',      '/proxy/') → '/'
+// 不匹配（含裸前缀 '/proxy' 无尾斜杠的访问）原样返回，由调用方按 SPA/404 处理。
+export function stripBasePath(pathname, normalizedBase) {
+  if (!normalizedBase || !pathname.startsWith(normalizedBase)) return pathname;
+  return pathname.slice(normalizedBase.length - 1) || '/';
+}

package/server/lib/log-watcher.js

@@ -249,10 +249,16 @@ function _scheduleDebouncedRead(fileState) {
   }, FSWATCH_DEBOUNCE_MS);
 }
 
+// 测试注入缝(仿 updater fetchImpl 惯例):替换轮询分支的 watchFile 实现。
+// 真实 watchFile 的 stat 基线与 500ms 间隔在 CI 慢机上不可确定性驱动(基线竞态曾致
+// 25s 全程静默 flake),单测注入假实现手动触发回调即可零时序覆盖。生产恒为 node:fs 原版。
+let _watchFileImpl = watchFile;
+export function __setWatchFileImplForTests(fn) { _watchFileImpl = fn || watchFile; }
+
 function _fallbackToPolling(fileState) {
   if (fileState.polling) return;
   fileState.polling = true;
-  watchFile(fileState.logFile, { interval: 500 }, () => {
+  _watchFileImpl(fileState.logFile, { interval: 500 }, () => {
     _readDelta(fileState);
   });
 }

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

@@ -0,0 +1,191 @@
+/**
+ * PTY → WS 洪泛限流器（Windows ConPTY 洪泛防卡死，server 侧字节率上限）。
+ *
+ * 背景：pty-manager 的 setImmediate 合帧已把"消息数"压到每 tick 一条，但**字节量
+ * 没有上限**——ConPTY 把 TUI 全屏对话框/重绘转译成 macOS forkpty 10~100 倍的字节流
+ * （如 /theme 选择器开/关、全屏 TUI 重绘），ws-backpressure gate 只在慢网络
+ * （bufferedAmount > 1MB）介入，快 LAN 上洪泛字节全量到达前端，xterm 逐帧解析渲染
+ * 稠密 SGR+CJK 重绘把主线程打满。本器在发送侧限流：
+ *
+ *   - 直通态：chunk 立即 send（零延迟，不起 timer）。字节率按固定 flushMs 桶统计，
+ *     当前桶累计超 floodThresholdBytesPerWin → 进入限流态。打字回显 / 正常 token
+ *     流远低于阈值（≈256KB/s），不受影响。
+ *   - 限流态：chunk 剥掉自带的 DEC 2026 标记后追加进 pending（pending 内部因此
+ *     **绝无 2026 标记**，截断永不切坏配对）；每 flushMs 把 pending 用单对
+ *     SYNC_BEGIN/END 重新包裹成**一条** send 发出并清空（无论下游是否跳发，
+ *     flush 后必清——下游 bpGate 跳发时由其 data-resync 快照对齐，不在这里重试）。
+ *     发送前若 pending 超 flushBudgetBytes → findSafeSliceStart 截到尾部预算内：
+ *     这是真正的速率上限（≈ flushBudgetBytes / flushMs ≈ 1.9MB/s），与前端
+ *     TerminalWriteQueue 32KB/帧的消化速率同量级，洪泛期客户端入速 ≈ 出速不积压。
+ *     pending 超 pendingCap → 同样截到 trimTo（flush 间隔内的内存上界）。中间全屏
+ *     重绘帧 last-wins 可丢，ConPTY 重绘流自愈。findSafeSliceStart 只保 ANSI 边界、
+ *     不保 2026 配对——配平靠剥标记+重包裹兜底，截断切坏配对会让 xterm 卡在同步
+ *     缓冲态（黑屏）。scratch PTY 的 chunk 本就无 2026 标记，剥除为 no-op、重包裹
+ *     无害（不支持的终端忽略该序列），两条路径共用同一实现。
+ *   - 回落：连续 fallbackWins 个桶低于阈值 → flush 残余后回直通态。
+ *   - reset()：清 pending + timer + 回直通态。bpGate onBehind/onResume 时必须调用：
+ *     data-resync 快照（getOutputBuffer）是唯一真相源，残留 pending 若不清会把早于
+ *     快照的旧字节回灌导致画面回退。
+ *
+ * 纯逻辑、时钟可注入（setTimer/clearTimer/now），便于单测。仿 ws-backpressure.js 惯例。
+ */
+
+const SYNC_BEGIN = '\x1b[?2026h';
+const SYNC_END = '\x1b[?2026l';
+// 全局替换两种标记。pty-manager flushBatch 只在首尾各加一对，但限流态 pending 由
+// 多个 chunk 拼接而成，内部会出现多对交替——统一剥净再整体包一对。
+const SYNC_MARKS_RE = /\x1b\[\?2026[hl]/g;
+
+// 默认常量可经 CCV_FLOOD_* 环境变量覆盖（仿 CCV_FORCE_POLL 先例），便于 Windows
+// 实机排障时调参而不改源码。非法/非正整数值回落默认。
+function envInt(name, fallback) {
+  const v = parseInt(process.env[name], 10);
+  return Number.isFinite(v) && v > 0 ? v : fallback;
+}
+
+const DEFAULT_FLUSH_MS = envInt('CCV_FLOOD_FLUSH_MS', 33);                       // 限流态合并窗口 = 字节率统计桶宽
+const DEFAULT_FLOOD_THRESHOLD = envInt('CCV_FLOOD_THRESHOLD', 8 * 1024);         // 单桶超 8KB（≈256KB/s）判定洪泛
+const DEFAULT_FALLBACK_WINS = envInt('CCV_FLOOD_FALLBACK_WINS', 3);              // 连续 N 个低于阈值的桶才回直通（迟滞）
+const DEFAULT_PENDING_CAP = envInt('CCV_FLOOD_PENDING_CAP', 256 * 1024);         // 限流态 pending 上限（flush 间隔内的内存上界）
+const DEFAULT_TRIM_TO = envInt('CCV_FLOOD_TRIM_TO', 128 * 1024);                 // pendingCap 截断后保留的尾部量
+// 单次 flush 发送预算 = 真速率上限：64KB / 33ms ≈ 1.9MB/s，与前端 32KB/帧消化速率同量级
+const DEFAULT_FLUSH_BUDGET = envInt('CCV_FLOOD_FLUSH_BUDGET', 64 * 1024);
+
+/**
+ * @param {object} opts
+ * @param {(data: string) => void} opts.send - 实际发送回调（调用方在内部接 bpGate + ws.send）
+ * @param {(buf: string, rawStart: number) => number} opts.findSafeSliceStart - ANSI 安全截断（pty-manager 导出）
+ * @param {(buffered: number) => void} [opts.onFloodStart] - 进入限流态（observability 埋点）
+ * @param {() => void} [opts.onFloodEnd] - 回落直通态
+ * @param {number} [opts.flushMs]
+ * @param {number} [opts.floodThresholdBytesPerWin]
+ * @param {number} [opts.fallbackWins]
+ * @param {number} [opts.pendingCap]
+ * @param {number} [opts.trimTo]
+ * @param {number} [opts.flushBudgetBytes]
+ * @param {(fn: Function, ms: number) => any} [opts.setTimer] - 测试注入
+ * @param {(t: any) => void} [opts.clearTimer] - 测试注入
+ * @returns {{ offer: (chunk: string) => void, reset: () => void, dispose: () => void, isFlooding: () => boolean }}
+ */
+export function createFloodCoalescer({
+  send,
+  findSafeSliceStart,
+  onFloodStart,
+  onFloodEnd,
+  flushMs = DEFAULT_FLUSH_MS,
+  floodThresholdBytesPerWin = DEFAULT_FLOOD_THRESHOLD,
+  fallbackWins = DEFAULT_FALLBACK_WINS,
+  pendingCap = DEFAULT_PENDING_CAP,
+  trimTo = DEFAULT_TRIM_TO,
+  flushBudgetBytes = DEFAULT_FLUSH_BUDGET,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+}) {
+  let flooding = false;
+  let pending = '';
+  let winBytes = 0;       // 当前桶累计字节（直通态由 offer 累计，限流态由 flush 结算）
+  let calmWins = 0;       // 连续低于阈值的桶数
+  let flushTimer = null;  // 限流态周期 flush；直通态下亦作为桶边界 timer（见 offer）
+  let disposed = false;
+
+  const stopTimer = () => {
+    if (flushTimer) {
+      clearTimer(flushTimer);
+      flushTimer = null;
+    }
+  };
+
+  // 直通态的桶边界：到点清零计数。无流量时 timer 不存在，零常驻开销。
+  const armPassthroughWindow = () => {
+    if (flushTimer) return;
+    flushTimer = setTimer(() => {
+      flushTimer = null;
+      winBytes = 0;
+    }, flushMs);
+    flushTimer.unref?.();
+  };
+
+  const flushPending = () => {
+    if (!pending) return;
+    // 单次 flush 发送预算 = 真正的速率上限：超预算截到尾部（last-wins），
+    // 保证洪泛期送达客户端的字节率 ≤ flushBudgetBytes/flushMs，与前端消化速率同量级。
+    if (pending.length > flushBudgetBytes) {
+      const rawStart = pending.length - flushBudgetBytes;
+      pending = pending.slice(findSafeSliceStart(pending, rawStart));
+    }
+    const merged = SYNC_BEGIN + pending + SYNC_END;
+    pending = '';
+    try { send(merged); } catch { }
+  };
+
+  const onFloodTick = () => {
+    flushTimer = null;
+    if (disposed || !flooding) return;
+    // 本桶结算：低于阈值累计 calm 桶数，连续 fallbackWins 个即回落
+    if (winBytes <= floodThresholdBytesPerWin) {
+      calmWins++;
+    } else {
+      calmWins = 0;
+    }
+    winBytes = 0;
+    flushPending();
+    if (calmWins >= fallbackWins) {
+      flooding = false;
+      calmWins = 0;
+      try { onFloodEnd?.(); } catch { }
+      return; // 不再续约 timer，回直通
+    }
+    flushTimer = setTimer(onFloodTick, flushMs);
+    flushTimer.unref?.();
+  };
+
+  return {
+    /** 每条 PTY chunk 调用。直通态立即 send；限流态进 pending 等周期 flush。 */
+    offer(chunk) {
+      if (disposed || !chunk) return;
+      winBytes += chunk.length;
+      if (!flooding) {
+        if (winBytes > floodThresholdBytesPerWin) {
+          // 进入限流态：当前 chunk 是压垮桶的那条，一并纳入 pending（含它之前
+          // 本桶已直通的部分不回收——它们已发出，量级在阈值内）。
+          flooding = true;
+          calmWins = 0;
+          stopTimer();
+          pending = chunk.replace(SYNC_MARKS_RE, '');
+          flushTimer = setTimer(onFloodTick, flushMs);
+          flushTimer.unref?.();
+          try { onFloodStart?.(winBytes); } catch { }
+          return;
+        }
+        armPassthroughWindow();
+        try { send(chunk); } catch { }
+        return;
+      }
+      pending += chunk.replace(SYNC_MARKS_RE, '');
+      // 单 chunk 可超 cap：pty-manager 每 tick 合帧，一个 tick（如 /resume 重放）可达数百 KB，
+      // 故该分支并非不可达——它是 flush 间隔内的内存上界，与 flushPending 的速率预算各司其职。
+      if (pending.length > pendingCap) {
+        const rawStart = pending.length - trimTo;
+        const safeStart = findSafeSliceStart(pending, rawStart);
+        pending = pending.slice(safeStart);
+      }
+    },
+    /** bpGate onBehind/onResume 时调用：resync 快照是唯一真相源，清掉旧 pending 防回灌。 */
+    reset() {
+      stopTimer();
+      pending = '';
+      winBytes = 0;
+      calmWins = 0;
+      flooding = false;
+    },
+    isFlooding() {
+      return flooding;
+    },
+    /** ws close 时调用，终态。 */
+    dispose() {
+      disposed = true;
+      stopTimer();
+      pending = '';
+    },
+  };
+}

package/server/lib/term-signals.js

@@ -0,0 +1,80 @@
+// Windows Ctrl+C 退出链三层防御（macOS/Linux 行为不变）。
+// 背景：cli.js / server.js 的 SIGINT handler 都是 `doCleanup → .finally(process.exit)` 形态，
+// 注册 handler 后 Node 不再默认退出 —— 链上任何一环挂住（node-pty ConPTY kill 同步挂起、
+// IM bridge teardown await 无超时、SIGINT 事件被 ConPTY 吞掉）进程就永不退出，
+// 即 Windows 用户报告的 "Ctrl+C 完全无反应"。
+// 三函数全部依赖注入（仿 log-watcher __setWatchFileImplForTests 惯例），纯逻辑可单测。
+
+import { spawnSync as _spawnSync } from 'node:child_process';
+import { emitKeypressEvents as _emitKeypressEvents } from 'node:readline';
+
+// 把 `doCleanup → exit` 包装成幂等 + 双保险的 cleanup：
+//   首次触发：先武装 watchdog（watchdogMs 后强制 exit(130)，unref 不滞留事件循环），
+//             再 try/catch 跑 doCleanup（同步抛错不阻断退出），完成后 exit()。
+//   二次触发（用户连按 Ctrl+C）：立即 exit(130)，不再等优雅收尾。
+// watchdogMs 默认 5s：_doStop 内 IM teardown + serverStopping hook 共用一个 3s 总预算
+// （见 server.js _doStop 的合并 race），其后还有 rename temp jsonl（用户数据）要顺序
+// 执行 —— watchdog 必须 > 3s 总预算 + rename 余量，避免中途截断。
+export function createHardenedCleanup({ doCleanup, exit = process.exit, setTimeoutImpl = setTimeout, watchdogMs = 5000 }) {
+  let invoked = false;
+  return function hardenedCleanup() {
+    if (invoked) { exit(130); return; }
+    invoked = true;
+    const watchdog = setTimeoutImpl(() => exit(130), watchdogMs);
+    if (watchdog && typeof watchdog.unref === 'function') watchdog.unref();
+    try {
+      const r = doCleanup();
+      if (r && typeof r.then === 'function') {
+        r.then(() => exit(), () => exit(130));
+      } else {
+        // 同步 doCleanup：完成即退（统一契约"doCleanup 结束 → exit"；当前所有调用方
+        // 都返回 promise 走上面分支，此分支为前向兼容）
+        exit();
+      }
+    } catch {
+      exit(130);
+    }
+  };
+}
+
+// Windows 下 ConPTY/控制台事件链偶发吞掉 Ctrl+C（SIGINT 永不送达）的兜底：
+// 把本地终端 stdin 切 raw mode 监听 keypress，\x03(Ctrl+C)/\x04(Ctrl+D) 直连 onInterrupt。
+// 注意：raw mode 下控制台**不再产生 SIGINT**，onInterrupt 必须直接是 hardened cleanup
+// 本体（不能 re-emit SIGINT —— 那条路在 raw mode 下已死）。
+// 仅 win32 且 stdin 是 TTY 时安装（silent/PTY 与 SDK 模式本地终端本就无人读 stdin，
+// 无副作用；proxy 模式 stdio:'inherit' 子进程持有控制台，调用方不得安装）。
+// 进程退出时通过 'exit' 同步钩子恢复 cooked mode，防 Windows 终端残留 raw 态
+// （watchdog 的 exit(130) 同样触发 'exit' 钩子）。
+export function installWinKeypressFallback({ stdin = process.stdin, onInterrupt, platform = process.platform, emitKeypressEvents = _emitKeypressEvents }) {
+  if (platform !== 'win32' || !stdin || !stdin.isTTY) return null;
+  emitKeypressEvents(stdin);
+  try { stdin.setRawMode(true); } catch { return null; }
+  const restore = () => { try { stdin.setRawMode(false); } catch { /* noop */ } };
+  process.on('exit', restore);
+  const onKeypress = (str, key) => {
+    const isCtrlC = (key && key.ctrl && key.name === 'c') || str === '\u0003';
+    const isCtrlD = (key && key.ctrl && key.name === 'd') || str === '\u0004';
+    if (isCtrlC || isCtrlD) onInterrupt();
+  };
+  stdin.on('keypress', onKeypress);
+  stdin.resume();
+  return () => {
+    stdin.off('keypress', onKeypress);
+    restore();
+    process.off('exit', restore);
+  };
+}
+
+// Windows 下杀掉 PTY 进程树（ConPTY agent + claude）。
+// 用 spawnSync taskkill 而非 ptyProcess.kill()：后者在 ConPTY 下有已知同步挂起问题
+// （microsoft/node-pty#454 等），且 killPty 的 respawn 调用方（spawnClaude 内部
+// kill→立即重启、workspaces stop→launch）需要"返回时进程已死"的同步语义 ——
+// taskkill /F 通常 <200ms，timeout 2s 兜底有界，不会废掉 5s watchdog。
+// 非 win32 返回 false，调用方走原 ptyProcess.kill() 路径。
+export function killPtyTree(pid, { platform = process.platform, spawnSyncImpl = _spawnSync } = {}) {
+  if (platform !== 'win32' || !pid) return false;
+  try {
+    spawnSyncImpl('taskkill', ['/pid', String(pid), '/T', '/F'], { timeout: 2000, windowsHide: true });
+  } catch { /* taskkill 不在 PATH 等极端情况，调用方仍有 watchdog 兜底 */ }
+  return true;
+}

package/server/pty-manager.js

@@ -5,6 +5,7 @@ import { chmodSync, statSync } from 'node:fs';
 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';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -46,8 +47,11 @@ async function getPty() {
  * 在 outputBuffer 截断时，找到安全的截断位置，
  * 避免从 ANSI 转义序列中间开始导致终端状态紊乱。
  * 策略：从截断点向后扫描，跳过可能被截断的不完整转义序列。
+ * 注意：只保 ANSI 序列边界，不保 DEC 2026 同步标记的配对——
+ * 跨 2026 块截断的配平由调用方负责（见 lib/pty-flood-coalescer.js）。
+ * export 供洪泛限流器复用同一截断语义。
  */
-function findSafeSliceStart(buf, rawStart) {
+export function findSafeSliceStart(buf, rawStart) {
   // 从 rawStart 开始，向后最多扫描 64 字节寻找安全起点
   const scanLimit = Math.min(rawStart + 64, buf.length);
   let i = rawStart;
@@ -474,7 +478,14 @@ export function killPty() {
     flushBatch();
     batchBuffer = '';
     batchScheduled = false;
-    try { ptyProcess.kill(); } catch { }
+    // Windows：node-pty 的 ConPTY kill 有已知同步挂起问题（microsoft/node-pty#454），
+    // 挂住会连 Ctrl+C 退出链的 watchdog 一起废掉。改用 spawnSync taskkill /T /F 收割
+    // 整棵进程树（ConPTY agent + claude），有界（timeout 2s）且提供"返回时已死"语义
+    // （spawnClaude 内部 kill→respawn、workspaces stop→launch 依赖这一点）。
+    // win32 下完全跳过 ptyProcess.kill()。非 Windows 行为不变。
+    if (!killPtyTree(ptyProcess.pid)) {
+      try { ptyProcess.kill(); } catch { }
+    }
     ptyProcess = null;
     ptyKind = null;
     ptySkipPermissions = false;

package/server/routes/files-fs.js

@@ -560,8 +560,12 @@ function revealFile(req, res, parsedUrl, isLocal, deps) {
       if (plat === 'darwin') {
         execFile('open', ['-R', fullPath], () => {});
       } else if (plat === 'win32') {
-        // explorer /select,<path> 必须合到一个 arg；分两个会让含空格/中文路径 escape 失败。
-        spawn('explorer.exe', [`/select,${fullPath}`], { shell: false, windowsHide: true });
+        // explorer /select 的规范形式是 /select,"<path>"（仅路径部分加引号、整体一个 arg）。
+        // 必须 windowsVerbatimArguments 透传：否则 Node 对含空格 arg 整体加引号生成
+        // explorer.exe "/select,C:\My Proj\x.txt"，explorer 解析不了 → 功能失效。
+        // Windows 文件名不允许 "，且不经 cmd.exe，无元字符注入面。
+        const child = spawn('explorer.exe', [`/select,"${fullPath}"`], { windowsVerbatimArguments: true, windowsHide: true });
+        child.on('error', () => {}); // 防 async ENOENT 变 uncaughtException 砸进程
       } else {
         execFile('xdg-open', [dirname(fullPath)], () => {});
       }

package/server/routes/misc.js

@@ -1,6 +1,7 @@
 // Miscellaneous small routes (moved verbatim from server.js handleRequest).
 import { getUserProfile } from '../lib/user-profile.js';
 import { runWaterfallHook } from '../lib/plugin-loader.js';
+import { normalizeBasePath } from '../lib/base-path.js';
 
 async function userProfile(req, res) {
   const profile = await getUserProfile();
@@ -10,7 +11,10 @@ async function userProfile(req, res) {
 
 async function localUrl(req, res, parsedUrl, isLocal, deps) {
   const localIp = deps.getLocalIp();
-  const defaultUrl = `${deps.protocol}://${localIp}:${deps.actualPort}?token=${deps.ACCESS_TOKEN}`;
+  // 反代子路径部署时分享/二维码 URL 也要带前缀，否则扫码绕过代理直连源站端口（与
+  // server.startedNetwork 启动打印保持一致）。未设 CCV_BASE_PATH 时为空串，行为不变。
+  const basePath = normalizeBasePath(process.env.CCV_BASE_PATH);
+  const defaultUrl = `${deps.protocol}://${localIp}:${deps.actualPort}${basePath}?token=${deps.ACCESS_TOKEN}`;
   const hookResult = await runWaterfallHook('localUrl', { url: defaultUrl, ip: localIp, port: deps.actualPort, token: deps.ACCESS_TOKEN });
   res.writeHead(200, { 'Content-Type': 'application/json' });
   res.end(JSON.stringify({ url: hookResult.url }));

package/server/routes/preferences.js

@@ -18,6 +18,14 @@ function stripImConfigs(obj) {
   if (obj) for (const id of listPlatforms()) delete obj[id];
 }
 
+// /theme 选择器特征：选项文案高特异、不太可能出现在普通生成输出里（ESC 兜底的门控签名）
+const THEME_PICKER_RE = /Auto \(match terminal\)|colorblind-friendly/;
+
+// 并发切主题防重入：双端同时 POST themeColor 时只允许一条 /theme 同步链路在途，
+// 防止双监听器 + 双 /theme 注入 + 双 ESC（后到的 POST 仅落盘偏好，跳过 PTY 同步）。
+let _themeSyncInFlight = false;
+export function _resetThemeSyncForTests() { _themeSyncInFlight = false; }
+
 function preferencesGet(req, res, parsedUrl, isLocal, deps) {
   let prefs = {};
   try { if (existsSync(deps.getPrefsFile())) prefs = JSON.parse(readFileSync(deps.getPrefsFile(), 'utf-8')); } catch { }
@@ -84,11 +92,18 @@ function preferencesPost(req, res, parsedUrl, isLocal, deps) {
       // preferences.json 可能携带 auth 的 base64 密码 —— 与 lib/auth.js writePrefs 一致地
       // 重申 0600,避免该路径(无 mode/不 chmod)把密码文件留成默认 umask 的可读权限。
       try { chmodSync(prefsFile, 0o600); } catch { /* best-effort; non-POSIX or race */ }
-      // 主题切换时同步到 Claude Code CLI：发 /theme，监听输出验证结果，不对就再发一次
-      if (incoming.themeColor && deps.writeToPty && deps.onPtyData) {
+      // 主题切换时同步到 Claude Code CLI：发 /theme，监听输出验证结果。
+      // 现代 CLI（≥2.x）的 /theme 是交互式选择器（args 被忽略），注入后对话框可能
+      // 残留在终端：
+      //   - mismatch 时**不再重发** /theme —— toggle 语义已不存在，重发只会把选择器
+      //     再次打开，把终端困进"确认-重开"循环（Windows ConPTY 下每轮全屏重绘洪泛）。
+      //   - 5s 超时若 buf 检出选择器特征（选项文案，见 THEME_PICKER_RE），补发一次
+      //     ESC 关闭残留对话框。无特征绝不发 ESC —— CLI 正在流式生成时 /theme 只是被
+      //     排队、对话框未开，误发 ESC 会 interrupt 用户正在跑的任务（宁漏关不误发）。
+      if (incoming.themeColor && deps.writeToPty && deps.onPtyData && !_themeSyncInFlight) {
+        _themeSyncInFlight = true;
         const target = incoming.themeColor === 'light' ? 'light' : 'dark';
         let buf = '';
-        let retried = false;
         const removeListener = deps.onPtyData((data) => {
           buf += data;
           if (buf.length > 4096) buf = buf.slice(-2048); // 限制 buf 大小
@@ -97,15 +112,20 @@ function preferencesPost(req, res, parsedUrl, isLocal, deps) {
           if (match) {
             removeListener();
             clearTimeout(timeout);
-            if (match[1] !== target && !retried) {
-              // 结果与目标不一致，再 toggle 一次
-              retried = true;
-              try { deps.writeToPty('/theme\r'); } catch {}
+            _themeSyncInFlight = false;
+            if (match[1] !== target) {
+              console.warn(`[preferences] CLI theme sync mismatch: got ${match[1]}, wanted ${target} (no retry; modern /theme is an interactive picker)`);
             }
           }
         });
-        // 5 秒超时，避免监听器泄漏
-        const timeout = setTimeout(() => { removeListener(); }, 5000);
+        // 5 秒超时，避免监听器泄漏；检出选择器残留时 ESC 兜底关闭
+        const timeout = setTimeout(() => {
+          removeListener();
+          _themeSyncInFlight = false;
+          if (THEME_PICKER_RE.test(buf)) {
+            try { deps.writeToPty('\x1b'); } catch {}
+          }
+        }, 5000);
         try { deps.writeToPty('/theme\r'); } catch {}
       }
       // 回显里也剥离 auth/authByProject(含 base64 密码) —— GET 已剥离,POST 回显同样不能漏给

package/server/scratch-pty-manager.js

@@ -4,6 +4,7 @@ import { chmodSync, statSync } from 'node:fs';
 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';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -219,7 +220,11 @@ export function killScratch(id) {
     flushBatch(s);
     s.batchBuffer = '';
     s.batchScheduled = false;
-    try { s.ptyProcess.kill(); } catch { }
+    // 与 pty-manager.killPty 同款：win32 用 taskkill /T 收割 ConPTY 树，
+    // 绕开 node-pty kill 的同步挂起问题；非 Windows 走原路径。
+    if (!killPtyTree(s.ptyProcess.pid)) {
+      try { s.ptyProcess.kill(); } catch { }
+    }
     s.ptyProcess = null;
   }
   // 显式 kill 后整条记录清掉，监听器一并丢弃（前端 ws.close 也会清）