@tunnelbox/core 0.1.10 → 0.1.16

package/src/messages.ts

@@ -1,171 +1,171 @@
-/**
- * 会话消息快照缓存与分页窗口工具（各智能体适配器共享）。
- *
- * 背景：拉取历史（session.messages）在部分适配器开销可观——opencode 会对整段会话做
- * 全量 hydrate、claude-code 需读盘解析 transcript；手机端蜂窝环境下还要把整份 JSON
- * 经 WS 下发并一次性渲染。两点缓解：
- *  1. 分页窗口：应答按 [before, limit] 只下发最近的 N 条，过长历史由手机端"滚动到顶
- *     加载更早"再拉；构建出完整列表后切片（构建仍是最重一步，缓存命中可完全跳过）。
- *  2. 短 TTL 快照：对重复/快速回看的打开直接从缓存切片，避免重复构建。快照在流式事件
- *     （message.part / session.status 等）到达时由适配器 invalidate，保证不长期陈旧。
- *
- * 消息数组统一约定为**时间升序（旧 → 新）**，与手机端展示顺序一致。
- *
- * 3. 载荷上界：超长会话/超大单条内容可能把一帧 push 撑到 relay 的连接读上限
- *    （旧 relay 4MB）而被误判断开。sliceWindow 统一在返回前截断单条文本/参数长度，
- *    并做**字节预算**——超预算从窗口更旧侧继续裁剪（保留最新，缺口可经 before 续拉，
- *    不丢内容），保证任何应答帧稳定远小于连接上限。截断只影响手机端展示。
- */
-import type { ChatMessage, Part } from "./types";
-
-/** 单页默认条数（手机端首屏/每次"加载更早"的展示窗口）。 */
-export const DEFAULT_PAGE_SIZE = 20;
-
-/** 单条 part 文本（text/thinking）展示上限（字符）。 */
-export const MAX_PART_TEXT = 16000;
-/** 单条 tool 参数展示上限（字符）。 */
-export const MAX_PART_ARGS = 4000;
-/** 单页串行化字节预算：预留明显余量，确保帧远小于 relay 连接读上限（4MB/32MB）。 */
-export const MAX_PAGE_BYTES = 1_500_000;
-
-export interface MessagesPageQuery {
-  /** 游标：只返回早于该消息 id 的更早消息（第一页不传）。 */
-  before?: string;
-  /** 每页条数（缺省 DEFAULT_PAGE_SIZE）。 */
-  limit?: number;
-  /** 字节预算（缺省 MAX_PAGE_BYTES）。 */
-  maxBytes?: number;
-}
-
-export interface MessagesPageResult {
-  sessionID: string;
-  messages: ChatMessage[];
-  /** 更早历史是否仍存在（手机端据此决定是否继续"加载更早"）。 */
-  hasMore?: boolean;
-}
-
-function capStr(s: string, max: number): string {
-  if (s.length <= max) return s;
-  return `${s.slice(0, max)}…`;
-}
-
-/** 截断单条消息内过大部件（返回新对象；未超限原样返回）。只影响手机端展示体积。 */
-export function capMessage(m: ChatMessage): ChatMessage {
-  let parts: Part[] | undefined;
-  for (let i = 0; i < m.parts.length; i++) {
-    const p = m.parts[i];
-    const nText =
-      typeof p.text === "string" && p.text.length > MAX_PART_TEXT
-        ? capStr(p.text, MAX_PART_TEXT)
-        : p.text;
-    const nDelta =
-      typeof p.delta === "string" && p.delta.length > MAX_PART_TEXT
-        ? capStr(p.delta, MAX_PART_TEXT)
-        : p.delta;
-    const nArgs =
-      typeof p.args === "string" && p.args.length > MAX_PART_ARGS
-        ? capStr(p.args, MAX_PART_ARGS)
-        : p.args;
-    if (nText !== p.text || nDelta !== p.delta || nArgs !== p.args) {
-      if (!parts) parts = m.parts.slice(0, i);
-      parts.push({ ...p, text: nText, delta: nDelta, args: nArgs });
-    } else if (parts) {
-      parts.push(p);
-    }
-  }
-  return parts ? { ...m, parts } : m;
-}
-
-/** 整批截断（仅对确有超限的条目重建，避免无谓分配）。 */
-export function capMessages(messages: ChatMessage[]): ChatMessage[] {
-  let changed = false;
-  const out = messages.map((m) => {
-    const c = capMessage(m);
-    if (c !== m) changed = true;
-    return c;
-  });
-  return changed ? out : messages;
-}
-
-function byteLength(messages: ChatMessage[]): number {
-  try {
-    return JSON.stringify(messages).length;
-  } catch {
-    // 循环引用等异常兜底：按上限放大估算，防止误超
-    return messages.length * MAX_PART_TEXT * 2;
-  }
-}
-
-/** 在完整（升序）消息列表上切出目标窗口：截断超大内容 + 字节预算裁剪最旧侧。 */
-export function sliceWindow(
-  full: ChatMessage[],
-  query: MessagesPageQuery = {},
-): Pick<MessagesPageResult, "messages" | "hasMore"> {
-  const limit = Math.max(1, query.limit ?? DEFAULT_PAGE_SIZE);
-  const maxBytes = query.maxBytes ?? MAX_PAGE_BYTES;
-  let end = full.length;
-  if (query.before !== undefined && query.before !== "") {
-    const idx = full.findIndex((m) => m.id === query.before);
-    // 游标消息本身不含在内；找不到（已被清理/不一致）时回退整段，避免丢消息。
-    if (idx >= 0) end = idx;
-  }
-  let start = Math.max(0, end - limit);
-  let messages = full.slice(start, end);
-  // 先按条数取窗口，再在「截断后」体积上做预算：超出才从最旧侧继续裁剪
-  // （单条超大内容经 cap 已大幅缩小，避免按原始长度过度裁剪）。
-  while (messages.length > 1) {
-    const capped = capMessages(messages);
-    if (byteLength(capped) <= maxBytes) {
-      messages = capped;
-      break;
-    }
-    start++;
-    messages = full.slice(start, end);
-  }
-  return { messages: capMessages(messages), hasMore: start > 0 };
-}
-
-/** 会话消息快照缓存：仅缓存**完整列表**（窗口切片在各请求时现算）。 */
-export class MessagesCache {
-  private ttlMs: number;
-  private maxEntries: number;
-  private store = new Map<string, { full: ChatMessage[]; at: number }>();
-
-  constructor(ttlMs = 2000, maxEntries = 64) {
-    this.ttlMs = ttlMs;
-    this.maxEntries = maxEntries;
-  }
-
-  /** 命中且未过 TTL 时返回完整列表副本；否则 undefined。 */
-  get(sessionID: string, now = Date.now()): ChatMessage[] | undefined {
-    const e = this.store.get(sessionID);
-    if (!e) return undefined;
-    if (now - e.at > this.ttlMs) {
-      this.store.delete(sessionID);
-      return undefined;
-    }
-    return e.full;
-  }
-
-  put(sessionID: string, full: ChatMessage[]): void {
-    if (this.store.size >= this.maxEntries && !this.store.has(sessionID)) {
-      // 简单 FIFO 淘汰最旧条目，防内存膨胀
-      const oldest = this.store.keys().next().value;
-      if (oldest !== undefined) this.store.delete(oldest);
-    }
-    this.store.set(sessionID, { full, at: Date.now() });
-  }
-
-  /** 会话内容变化（流式部件/状态/删除等）时调用，立即失效快照。 */
-  invalidate(sessionID: string): void {
-    this.store.delete(sessionID);
-  }
-
-  /** 适配器重连/整体失效（如清除全部快照）。 */
-  clear(): void {
-    this.store.clear();
-  }
-}
-
-/** 共享会话消息快照缓存（各适配器复用同一实例）。 */
-export const messagesCache = new MessagesCache();
+/**
+ * 会话消息快照缓存与分页窗口工具（各智能体适配器共享）。
+ *
+ * 背景：拉取历史（session.messages）在部分适配器开销可观——opencode 会对整段会话做
+ * 全量 hydrate、claude-code 需读盘解析 transcript；手机端蜂窝环境下还要把整份 JSON
+ * 经 WS 下发并一次性渲染。两点缓解：
+ *  1. 分页窗口：应答按 [before, limit] 只下发最近的 N 条，过长历史由手机端"滚动到顶
+ *     加载更早"再拉；构建出完整列表后切片（构建仍是最重一步，缓存命中可完全跳过）。
+ *  2. 短 TTL 快照：对重复/快速回看的打开直接从缓存切片，避免重复构建。快照在流式事件
+ *     （message.part / session.status 等）到达时由适配器 invalidate，保证不长期陈旧。
+ *
+ * 消息数组统一约定为**时间升序（旧 → 新）**，与手机端展示顺序一致。
+ *
+ * 3. 载荷上界：超长会话/超大单条内容可能把一帧 push 撑到 relay 的连接读上限
+ *    （旧 relay 4MB）而被误判断开。sliceWindow 统一在返回前截断单条文本/参数长度，
+ *    并做**字节预算**——超预算从窗口更旧侧继续裁剪（保留最新，缺口可经 before 续拉，
+ *    不丢内容），保证任何应答帧稳定远小于连接上限。截断只影响手机端展示。
+ */
+import type { ChatMessage, Part } from "./types";
+
+/** 单页默认条数（手机端首屏/每次"加载更早"的展示窗口）。 */
+export const DEFAULT_PAGE_SIZE = 20;
+
+/** 单条 part 文本（text/thinking）展示上限（字符）。 */
+export const MAX_PART_TEXT = 16000;
+/** 单条 tool 参数展示上限（字符）。 */
+export const MAX_PART_ARGS = 4000;
+/** 单页串行化字节预算：预留明显余量，确保帧远小于 relay 连接读上限（4MB/32MB）。 */
+export const MAX_PAGE_BYTES = 1_500_000;
+
+export interface MessagesPageQuery {
+  /** 游标：只返回早于该消息 id 的更早消息（第一页不传）。 */
+  before?: string;
+  /** 每页条数（缺省 DEFAULT_PAGE_SIZE）。 */
+  limit?: number;
+  /** 字节预算（缺省 MAX_PAGE_BYTES）。 */
+  maxBytes?: number;
+}
+
+export interface MessagesPageResult {
+  sessionID: string;
+  messages: ChatMessage[];
+  /** 更早历史是否仍存在（手机端据此决定是否继续"加载更早"）。 */
+  hasMore?: boolean;
+}
+
+function capStr(s: string, max: number): string {
+  if (s.length <= max) return s;
+  return `${s.slice(0, max)}…`;
+}
+
+/** 截断单条消息内过大部件（返回新对象；未超限原样返回）。只影响手机端展示体积。 */
+export function capMessage(m: ChatMessage): ChatMessage {
+  let parts: Part[] | undefined;
+  for (let i = 0; i < m.parts.length; i++) {
+    const p = m.parts[i];
+    const nText =
+      typeof p.text === "string" && p.text.length > MAX_PART_TEXT
+        ? capStr(p.text, MAX_PART_TEXT)
+        : p.text;
+    const nDelta =
+      typeof p.delta === "string" && p.delta.length > MAX_PART_TEXT
+        ? capStr(p.delta, MAX_PART_TEXT)
+        : p.delta;
+    const nArgs =
+      typeof p.args === "string" && p.args.length > MAX_PART_ARGS
+        ? capStr(p.args, MAX_PART_ARGS)
+        : p.args;
+    if (nText !== p.text || nDelta !== p.delta || nArgs !== p.args) {
+      if (!parts) parts = m.parts.slice(0, i);
+      parts.push({ ...p, text: nText, delta: nDelta, args: nArgs });
+    } else if (parts) {
+      parts.push(p);
+    }
+  }
+  return parts ? { ...m, parts } : m;
+}
+
+/** 整批截断（仅对确有超限的条目重建，避免无谓分配）。 */
+export function capMessages(messages: ChatMessage[]): ChatMessage[] {
+  let changed = false;
+  const out = messages.map((m) => {
+    const c = capMessage(m);
+    if (c !== m) changed = true;
+    return c;
+  });
+  return changed ? out : messages;
+}
+
+function byteLength(messages: ChatMessage[]): number {
+  try {
+    return JSON.stringify(messages).length;
+  } catch {
+    // 循环引用等异常兜底：按上限放大估算，防止误超
+    return messages.length * MAX_PART_TEXT * 2;
+  }
+}
+
+/** 在完整（升序）消息列表上切出目标窗口：截断超大内容 + 字节预算裁剪最旧侧。 */
+export function sliceWindow(
+  full: ChatMessage[],
+  query: MessagesPageQuery = {},
+): Pick<MessagesPageResult, "messages" | "hasMore"> {
+  const limit = Math.max(1, query.limit ?? DEFAULT_PAGE_SIZE);
+  const maxBytes = query.maxBytes ?? MAX_PAGE_BYTES;
+  let end = full.length;
+  if (query.before !== undefined && query.before !== "") {
+    const idx = full.findIndex((m) => m.id === query.before);
+    // 游标消息本身不含在内；找不到（已被清理/不一致）时回退整段，避免丢消息。
+    if (idx >= 0) end = idx;
+  }
+  let start = Math.max(0, end - limit);
+  let messages = full.slice(start, end);
+  // 先按条数取窗口，再在「截断后」体积上做预算：超出才从最旧侧继续裁剪
+  // （单条超大内容经 cap 已大幅缩小，避免按原始长度过度裁剪）。
+  while (messages.length > 1) {
+    const capped = capMessages(messages);
+    if (byteLength(capped) <= maxBytes) {
+      messages = capped;
+      break;
+    }
+    start++;
+    messages = full.slice(start, end);
+  }
+  return { messages: capMessages(messages), hasMore: start > 0 };
+}
+
+/** 会话消息快照缓存：仅缓存**完整列表**（窗口切片在各请求时现算）。 */
+export class MessagesCache {
+  private ttlMs: number;
+  private maxEntries: number;
+  private store = new Map<string, { full: ChatMessage[]; at: number }>();
+
+  constructor(ttlMs = 2000, maxEntries = 64) {
+    this.ttlMs = ttlMs;
+    this.maxEntries = maxEntries;
+  }
+
+  /** 命中且未过 TTL 时返回完整列表副本；否则 undefined。 */
+  get(sessionID: string, now = Date.now()): ChatMessage[] | undefined {
+    const e = this.store.get(sessionID);
+    if (!e) return undefined;
+    if (now - e.at > this.ttlMs) {
+      this.store.delete(sessionID);
+      return undefined;
+    }
+    return e.full;
+  }
+
+  put(sessionID: string, full: ChatMessage[]): void {
+    if (this.store.size >= this.maxEntries && !this.store.has(sessionID)) {
+      // 简单 FIFO 淘汰最旧条目，防内存膨胀
+      const oldest = this.store.keys().next().value;
+      if (oldest !== undefined) this.store.delete(oldest);
+    }
+    this.store.set(sessionID, { full, at: Date.now() });
+  }
+
+  /** 会话内容变化（流式部件/状态/删除等）时调用，立即失效快照。 */
+  invalidate(sessionID: string): void {
+    this.store.delete(sessionID);
+  }
+
+  /** 适配器重连/整体失效（如清除全部快照）。 */
+  clear(): void {
+    this.store.clear();
+  }
+}
+
+/** 共享会话消息快照缓存（各适配器复用同一实例）。 */
+export const messagesCache = new MessagesCache();

package/src/qr.ts

@@ -1,108 +1,108 @@
-/**
- * 终端二维码与配对信息打印。qrcode 为可选依赖，失败时降级为配对码提示。
- * 输出文案经 core i18n 按语言翻译（见 ./i18n）。
- */
-import { writePairingFile } from "./state";
-import { normalizeLang, resolveLang, t, type Lang } from "./i18n";
-
-/** 加载 qrcode 渲染器（可选依赖，加载失败返回 null）。 */
-async function loadQrcode(): Promise<{
-  toString?: (text: string, opts: unknown) => Promise<string>;
-} | null> {
-  try {
-    const mod = await import("qrcode");
-    const render = (mod as { default?: unknown }).default ?? mod;
-    const toString = (render as { toString?: (text: string, opts: unknown) => Promise<string> }).toString;
-    return toString ? { toString } : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * 生成适合嵌入聊天/等宽代码块的纯文本二维码（无 ANSI 颜色码，半块字符）。
- * 供手机「扫一扫」直接扫码配对。qrcode 不可用时返回空字符串（由调用方降级）。
- *
- * 注意：聊天区无法像终端 printPairing 那样用 ANSI 背景色“直接涂黑白”，只能靠字符，
- * 因此必须强制**反相**输出——白色模块用实心块字符（渲染成亮前景）、黑色模块留空
- * （呈现深色背景），从而在 opencode 默认的深色 TUI 里保持标准“深码浅底”对比度；
- * 若按常规映射（黑码实心、白码空格）在深色主题下会反相，手机无法扫码。
- */
-export async function renderPairingQrText(text: string): Promise<string> {
-  const render = await loadQrcode();
-  if (!render?.toString) return "";
-  try {
-    const qr = await render.toString(text, {
-      type: "utf8",
-      margin: 4,
-      // 令 qrcode 选用反相块字符表（dark=白/light=黑 → INVERTED_BLOCK_CHAR）
-      color: { dark: "#ffffff", light: "#000000" },
-    });
-    return qr || "";
-  } catch {
-    return "";
-  }
-}
-
-/** 近似显示宽度：ASCII 宽 1，其余按宽字符 2 计（用于跨语言的框线对齐）。 */
-function dispWidth(s: string): number {
-  let w = 0;
-  for (const ch of s) w += ch.charCodeAt(0) > 0xff ? 2 : 1;
-  return w;
-}
-
-function padVisual(s: string, width: number, align: "left" | "center" = "left"): string {
-  const cur = dispWidth(s);
-  if (cur >= width) return s;
-  const pad = width - cur;
-  if (align === "center") {
-    const left = Math.floor(pad / 2);
-    return " ".repeat(left) + s + " ".repeat(pad - left);
-  }
-  return s + " ".repeat(pad);
-}
-
-/**
- * 打印配对信息框 + 二维码（二维码内容为配对码本身，供 tunnelbox App「扫一扫」配对）。
- */
-export async function printPairing(
-  code: string,
-  type?: string,
-  name?: string,
-  lang?: Lang,
-): Promise<void> {
-  const resolved = lang ? normalizeLang(lang) : resolveLang();
-  const file = writePairingFile(code, type);
-  const tt = (key: Parameters<typeof t>[1], vars?: Parameters<typeof t>[2]) => t(resolved, key, vars);
-
-  const title = type ? tt("qr.titleWithType", { type }) : tt("qr.titleNoType");
-  const codeLine = `${tt("qr.codeLabel")}: ${code}`;
-  const hint = tt("qr.openHint");
-
-  const inner = Math.max(40, dispWidth(codeLine), dispWidth(title));
-  const W = Math.min(76, inner + 4);
-  const bar = "─".repeat(W);
-
-  console.log("");
-  console.log("┌" + bar + "┐");
-  console.log("│ " + padVisual(title, W - 2, "center") + " │");
-  console.log("├" + bar + "┤");
-  console.log("│ " + padVisual(codeLine, W - 2) + " │");
-  console.log("└" + bar + "┘");
-  console.log("  " + hint);
-
-  try {
-    const mod = await import("qrcode");
-    const render = (mod as { default?: unknown }).default ?? mod;
-    const toString = (render as { toString?: (text: string, opts: unknown) => Promise<string> }).toString;
-    if (toString) {
-      const qr = await toString(code, { type: "terminal", small: true });
-      if (qr) console.log(qr);
-    }
-  } catch {
-    console.log("  " + tt("qr.unavailable"));
-  }
-
-  console.log("  " + tt("qr.fileWritten", { path: file }));
-  console.log("");
-}
+/**
+ * 终端二维码与配对信息打印。qrcode 为可选依赖，失败时降级为配对码提示。
+ * 输出文案经 core i18n 按语言翻译（见 ./i18n）。
+ */
+import { writePairingFile } from "./state";
+import { normalizeLang, resolveLang, t, type Lang } from "./i18n";
+
+/** 加载 qrcode 渲染器（可选依赖，加载失败返回 null）。 */
+async function loadQrcode(): Promise<{
+  toString?: (text: string, opts: unknown) => Promise<string>;
+} | null> {
+  try {
+    const mod = await import("qrcode");
+    const render = (mod as { default?: unknown }).default ?? mod;
+    const toString = (render as { toString?: (text: string, opts: unknown) => Promise<string> }).toString;
+    return toString ? { toString } : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 生成适合嵌入聊天/等宽代码块的纯文本二维码（无 ANSI 颜色码，半块字符）。
+ * 供手机「扫一扫」直接扫码配对。qrcode 不可用时返回空字符串（由调用方降级）。
+ *
+ * 注意：聊天区无法像终端 printPairing 那样用 ANSI 背景色“直接涂黑白”，只能靠字符，
+ * 因此必须强制**反相**输出——白色模块用实心块字符（渲染成亮前景）、黑色模块留空
+ * （呈现深色背景），从而在 opencode 默认的深色 TUI 里保持标准“深码浅底”对比度；
+ * 若按常规映射（黑码实心、白码空格）在深色主题下会反相，手机无法扫码。
+ */
+export async function renderPairingQrText(text: string): Promise<string> {
+  const render = await loadQrcode();
+  if (!render?.toString) return "";
+  try {
+    const qr = await render.toString(text, {
+      type: "utf8",
+      margin: 4,
+      // 令 qrcode 选用反相块字符表（dark=白/light=黑 → INVERTED_BLOCK_CHAR）
+      color: { dark: "#ffffff", light: "#000000" },
+    });
+    return qr || "";
+  } catch {
+    return "";
+  }
+}
+
+/** 近似显示宽度：ASCII 宽 1，其余按宽字符 2 计（用于跨语言的框线对齐）。 */
+function dispWidth(s: string): number {
+  let w = 0;
+  for (const ch of s) w += ch.charCodeAt(0) > 0xff ? 2 : 1;
+  return w;
+}
+
+function padVisual(s: string, width: number, align: "left" | "center" = "left"): string {
+  const cur = dispWidth(s);
+  if (cur >= width) return s;
+  const pad = width - cur;
+  if (align === "center") {
+    const left = Math.floor(pad / 2);
+    return " ".repeat(left) + s + " ".repeat(pad - left);
+  }
+  return s + " ".repeat(pad);
+}
+
+/**
+ * 打印配对信息框 + 二维码（二维码内容为配对码本身，供 tunnelbox App「扫一扫」配对）。
+ */
+export async function printPairing(
+  code: string,
+  type?: string,
+  name?: string,
+  lang?: Lang,
+): Promise<void> {
+  const resolved = lang ? normalizeLang(lang) : resolveLang();
+  const file = writePairingFile(code, type);
+  const tt = (key: Parameters<typeof t>[1], vars?: Parameters<typeof t>[2]) => t(resolved, key, vars);
+
+  const title = type ? tt("qr.titleWithType", { type }) : tt("qr.titleNoType");
+  const codeLine = `${tt("qr.codeLabel")}: ${code}`;
+  const hint = tt("qr.openHint");
+
+  const inner = Math.max(40, dispWidth(codeLine), dispWidth(title));
+  const W = Math.min(76, inner + 4);
+  const bar = "─".repeat(W);
+
+  console.log("");
+  console.log("┌" + bar + "┐");
+  console.log("│ " + padVisual(title, W - 2, "center") + " │");
+  console.log("├" + bar + "┤");
+  console.log("│ " + padVisual(codeLine, W - 2) + " │");
+  console.log("└" + bar + "┘");
+  console.log("  " + hint);
+
+  try {
+    const mod = await import("qrcode");
+    const render = (mod as { default?: unknown }).default ?? mod;
+    const toString = (render as { toString?: (text: string, opts: unknown) => Promise<string> }).toString;
+    if (toString) {
+      const qr = await toString(code, { type: "terminal", small: true });
+      if (qr) console.log(qr);
+    }
+  } catch {
+    console.log("  " + tt("qr.unavailable"));
+  }
+
+  console.log("  " + tt("qr.fileWritten", { path: file }));
+  console.log("");
+}