@tunnelbox/core 0.1.0 → 0.1.7

package/src/qr.ts

@@ -1,42 +1,108 @@
 /**
- * 终端二维码与配对信息打印。qrcode 为可选依赖，失败时降级为链接。
+ * 终端二维码与配对信息打印。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(
-  relayHttpBase: string,
   code: string,
   type?: string,
   name?: string,
+  lang?: Lang,
 ): Promise<void> {
-  const p = new URLSearchParams({ code });
-  if (type) p.set("type", type);
-  if (name) p.set("name", name);
-  const link = `${relayHttpBase}/app/#/pages/index/index?${p.toString()}`;
-  const file = writePairingFile(link, code, type);
-  const tag = type ? ` ${type}` : "";
+  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("┌──────────────────────────────────────────────────────────┐");
-  console.log(`│                tunnelbox${tag} 手机配对               │`);
-  console.log("├──────────────────────────────────────────────────────────┤");
-  console.log(`│  配对码: ${code.padEnd(42)} │`);
-  console.log(`│  链接  : ${link.padEnd(42)} │`);
-  console.log("└──────────────────────────────────────────────────────────┘");
-  console.log("  手机浏览器打开链接，或打开 App 后手动输入配对码。");
+  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(link, { type: "terminal", small: true });
+      const qr = await toString(code, { type: "terminal", small: true });
       if (qr) console.log(qr);
     }
   } catch {
-    console.log("  （未安装 qrcode，请使用上方链接或配对码）");
+    console.log("  " + tt("qr.unavailable"));
   }
 
-  console.log(`  配对信息已写入: ${file}`);
+  console.log("  " + tt("qr.fileWritten", { path: file }));
   console.log("");
 }

package/src/state.ts

@@ -1,105 +1,101 @@
-/**
- * 本地状态持久化。默认存于 opencode 全局配置目录；支持按智能体类型隔离文件
- * （多 agent 同机时各适配器使用独立文件：remote-state.<type>.json）。
- */
-import { randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-
-/**
- * 默认中继地址（按环境区分，生产部署建议用 opencode.json 或
- * TUNNELBOX_RELAY_URL 显式配置，优先级最高）：
- *  - 生产（NODE_ENV=production）：wss://chat.wxngrok.com
- *  - 开发/其他：ws://127.0.0.1:8080
- */
-export const DEFAULT_RELAY_URL =
-  process.env.TUNNELBOX_RELAY_URL ||
-  (process.env.NODE_ENV === "production" ? "wss://chat.wxngrok.com" : "ws://127.0.0.1:8080");
-
-export interface State {
-  agentId: string;
-  relayUrl: string;
-  /** 账号体系（Phase 1）：是否已被手机账号认领。认领后不再自动申请配对码。 */
-  claimed?: boolean;
-}
-
-function baseName(): string {
-  return join(homedir(), ".config", "opencode");
-}
-
-function suffix(type?: string): string {
-  return type ? `.${type}` : "";
-}
-
-export function statePath(type?: string): string {
-  return join(baseName(), `remote-state${suffix(type)}.json`);
-}
-
-export function saveState(st: State, type?: string): void {
-  try {
-    const p = statePath(type);
-    mkdirSync(dirname(p), { recursive: true });
-    writeFileSync(p, JSON.stringify(st, null, 2), "utf8");
-  } catch (e) {
-    console.error("[tunnelbox] 保存状态失败", e);
-  }
-}
-
-/** 读取状态；不存在时生成新 agentID 并持久化。 */
-export function loadState(type?: string): State {
-  const fallback: State = {
-    agentId: randomBytes(16).toString("hex"),
-    relayUrl: DEFAULT_RELAY_URL,
-  };
-  try {
-    if (!existsSync(statePath(type))) {
-      saveState(fallback, type);
-      return fallback;
-    }
-    const parsed = JSON.parse(readFileSync(statePath(type), "utf8")) as Partial<State>;
-    if (parsed.agentId && parsed.agentId.length >= 16) {
-      return {
-        agentId: parsed.agentId,
-        relayUrl: parsed.relayUrl || DEFAULT_RELAY_URL,
-        claimed: parsed.claimed === true,
-      };
-    }
-    saveState(fallback, type);
-    return fallback;
-  } catch {
-    saveState(fallback, type);
-    return fallback;
-  }
-}
-
-/** 把配对信息写入本地文件，作为终端日志被吞时的兜底。 */
-export function writePairingFile(link: string, code: string, type?: string): string {
-  const p = join(baseName(), `remote-pairing${suffix(type)}.txt`);
-  try {
-    mkdirSync(dirname(p), { recursive: true });
-    writeFileSync(p, `配对码: ${code}\n配对链接: ${link}\n`, "utf8");
-  } catch {
-    /* ignore */
-  }
-  return p;
-}
-
-export interface PairingInfo {
-  code: string;
-  link: string;
-  relayUrl: string;
-  at: number;
-}
-
-/** 把最新配对信息写入 JSON（供配套 UI/工具读取）。 */
-export function writePairingJson(info: PairingInfo, type?: string): string {
-  const p = join(baseName(), `remote-pairing${suffix(type)}.json`);
-  try {
-    mkdirSync(dirname(p), { recursive: true });
-    writeFileSync(p, JSON.stringify(info, null, 2), "utf8");
-  } catch {
-    /* ignore */
-  }
-  return p;
-}
+/**
+ * 本地状态持久化。默认存于 tunnelbox 独立根目录 ~/.tunnelbox；支持按智能体类型隔离文件
+ * （多 agent 同机时各适配器使用独立文件：remote-state.<type>.json）。
+ *
+ * 中继地址不再作为连接选择源：环境默认由构建期经 esbuild `__TB_DEFAULT_RELAY__`
+ * 注入（配置来自 plugin/env/.env.*），运行期仅接受 TUNNELBOX_RELAY_URL / 显式配置覆盖。
+ */
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { normalizeLang, type Lang } from "./i18n";
+
+export interface State {
+  agentId: string;
+  /** 遗留字段（信息用途，不再作为连接选择源）。 */
+  relayUrl?: string;
+  /** 账号体系（Phase 1）：是否已被手机账号认领。认领后不再自动申请配对码。 */
+  claimed?: boolean;
+  /** 语言（install-local 安装时写入，opencode.json options.language / TUNNELBOX_LANG 可覆盖）。 */
+  lang?: Lang;
+}
+
+function baseName(): string {
+  return join(homedir(), ".tunnelbox");
+}
+
+function suffix(type?: string): string {
+  return type ? `.${type}` : "";
+}
+
+export function statePath(type?: string): string {
+  return join(baseName(), `remote-state${suffix(type)}.json`);
+}
+
+export function saveState(st: State, type?: string): void {
+  try {
+    const p = statePath(type);
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(st, null, 2), "utf8");
+  } catch (e) {
+    console.error("[tunnelbox] 保存状态失败", e);
+  }
+}
+
+/** 读取状态；不存在时生成新 agentID 并持久化。relayUrl 仅信息用途，不参与连接选择。 */
+export function loadState(type?: string): State {
+  const fallback: State = {
+    agentId: randomBytes(16).toString("hex"),
+  };
+  try {
+    if (!existsSync(statePath(type))) {
+      saveState(fallback, type);
+      return fallback;
+    }
+    const parsed = JSON.parse(readFileSync(statePath(type), "utf8")) as Partial<State>;
+    if (parsed.agentId && parsed.agentId.length >= 16) {
+      return {
+        agentId: parsed.agentId,
+        relayUrl: parsed.relayUrl || "",
+        claimed: parsed.claimed === true,
+        lang: parsed.lang ? normalizeLang(parsed.lang) : undefined,
+      };
+    }
+    saveState(fallback, type);
+    return fallback;
+  } catch {
+    saveState(fallback, type);
+    return fallback;
+  }
+}
+
+/** 把配对码写入本地文件，作为终端日志被吞时的兜底。 */
+export function writePairingFile(code: string, type?: string): string {
+  const p = join(baseName(), `remote-pairing${suffix(type)}.txt`);
+  try {
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, `配对码: ${code}\n`, "utf8");
+  } catch {
+    /* ignore */
+  }
+  return p;
+}
+
+export interface PairingInfo {
+  code: string;
+  relayUrl: string;
+  at: number;
+}
+
+/** 把最新配对信息写入 JSON（供配套 UI/工具读取）。 */
+export function writePairingJson(info: PairingInfo, type?: string): string {
+  const p = join(baseName(), `remote-pairing${suffix(type)}.json`);
+  try {
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(info, null, 2), "utf8");
+  } catch {
+    /* ignore */
+  }
+  return p;
+}

package/src/types.ts

@@ -1,127 +1,156 @@
-/**
- * tunnelbox 统一协议类型（各智能体适配器共享）。
- * 与 relay/internal/proto、web/src/protocol 通过 JSON 互通（镜像维护）。
- */
-
-export interface Envelope<T = unknown> {
-  id?: string;
-  type: string;
-  payload: T;
-  ts: number;
-  /** 中继注入/回填：手机端会话 id，用于回路由 */
-  clientID?: string;
-}
-
-export function envelope<T>(type: string, payload: T, id?: string): Envelope<T> {
-  return { id, type, payload, ts: Date.now() };
-}
-
-export interface AgentInfo {
-  name: string;
-  version: string;
-  platform?: string;
-  directory?: string;
-  /** 智能体类型：opencode | claude-code | codex | dsh | openclaw | hermes | cursor */
-  type?: string;
-  /** IANA 时区名（如 Asia/Shanghai），仅用于"电脑本地时间"展示 */
-  timezone?: string;
-  /** 能力位 */
-  capabilities?: {
-    streaming?: boolean;
-    thinking?: boolean;
-    permission?: boolean;
-    commands?: boolean;
-    abort?: boolean;
-  };
-}
-
-export type SessionStatus = "queued" | "running" | "idle" | "error";
-
-export interface SessionInfo {
-  id: string;
-  title: string;
-  created: number;
-  updated: number;
-  status: SessionStatus;
-  /** 会话所在工作区目录（dsh 按 workspace 分目录持久化） */
-  workspace?: string;
-}
-
-export interface WorkspaceInfo {
-  /** 工作区目录绝对路径 */
-  path: string;
-  /** 展示名（取目录名） */
-  name: string;
-  /** 该工作区内的会话数 */
-  sessionCount: number;
-  /** 最近会话更新时间 */
-  updated: number;
-}
-
-export interface Part {
-  id: string;
-  type: "text" | "tool" | "thinking";
-  text?: string;
-  delta?: string;
-  tool?: string;
-  args?: string;
-  complete?: boolean;
-}
-
-export interface ChatMessage {
-  id: string;
-  role: "user" | "assistant" | "tool" | "system";
-  parts: Part[];
-  created: number;
-}
-
-/** 权限请求的作答方式：approval=允许/拒绝/总是允许；choice=从选项中选择；input=输入文本。 */
-export type PermissionKind = "approval" | "choice" | "input";
-
-export interface PermissionRequest {
-  id: string;
-  sessionID: string;
-  tool: string;
-  args: Record<string, unknown>;
-  prompt?: string;
-  createdAt: number;
-  /** 作答方式（缺省视为 approval） */
-  kind?: PermissionKind;
-  /** choice 类型的可选项（显示为按钮列表） */
-  options?: string[];
-}
-
-/** 结构化提问（opencode question.v2.asked 等）中的单条问题。 */
-export interface QuestionInfo {
-  question: string;
-  header?: string;
-  options: string[];
-  multiple?: boolean;
-  custom?: boolean;
-}
-
-export interface QuestionRequest {
-  id: string;
-  sessionID: string;
-  prompt?: string;
-  questions: QuestionInfo[];
-  createdAt: number;
-}
-
-export interface CommandInfo {
-  name: string;
-  description?: string;
-}
-
-/** 账号体系（Phase 1）：电脑被手机账号认领后 relay 下发。 */
-export interface AgentClaimedMessage {
-  email?: string;
-}
-
-/** 账号体系（Phase 1）：电脑被解绑后 relay 下发，适配器应重置并重新生成 agentID。 */
-export interface AgentRevokedMessage {}
-
-/** agent 断开后中继推送给已连接手机（在线信号为 agent.info 广播）。 */
-export interface AgentOfflineMessage {
-  agentID?: string;
-}
+/**
+ * tunnelbox 统一协议类型（各智能体适配器共享）。
+ * 与 relay/internal/proto、web/src/protocol 通过 JSON 互通（镜像维护）。
+ */
+
+export interface Envelope<T = unknown> {
+  id?: string;
+  type: string;
+  payload: T;
+  ts: number;
+  /** 中继注入/回填：手机端会话 id，用于回路由 */
+  clientID?: string;
+}
+
+export function envelope<T>(type: string, payload: T, id?: string): Envelope<T> {
+  return { id, type, payload, ts: Date.now() };
+}
+
+export interface AgentInfo {
+  name: string;
+  version: string;
+  platform?: string;
+  directory?: string;
+  /** 智能体类型：opencode | claude-code | codex | dsh | openclaw | hermes | cursor */
+  type?: string;
+  /** IANA 时区名（如 Asia/Shanghai），仅用于"电脑本地时间"展示 */
+  timezone?: string;
+  /** 能力位 */
+  capabilities?: {
+    streaming?: boolean;
+    thinking?: boolean;
+    permission?: boolean;
+    commands?: boolean;
+    abort?: boolean;
+  };
+}
+
+export type SessionStatus = "queued" | "running" | "idle" | "error";
+
+export interface SessionInfo {
+  id: string;
+  title: string;
+  created: number;
+  updated: number;
+  status: SessionStatus;
+  /** 会话所在工作区目录（dsh 按 workspace 分目录持久化） */
+  workspace?: string;
+}
+
+export interface WorkspaceInfo {
+  /** 工作区目录绝对路径 */
+  path: string;
+  /** 展示名（取目录名） */
+  name: string;
+  /** 该工作区内的会话数 */
+  sessionCount: number;
+  /** 最近会话更新时间 */
+  updated: number;
+}
+
+export interface Part {
+  id: string;
+  type: "text" | "tool" | "thinking";
+  text?: string;
+  delta?: string;
+  tool?: string;
+  args?: string;
+  complete?: boolean;
+}
+
+export interface ChatMessage {
+  id: string;
+  role: "user" | "assistant" | "tool" | "system";
+  parts: Part[];
+  created: number;
+  /** 消息对应的模式/agent（opencode: build|plan），用于手机端气泡标注 */
+  mode?: string;
+}
+
+/** 权限请求的作答方式：approval=允许/拒绝/总是允许；choice=从选项中选择；input=输入文本。 */
+export type PermissionKind = "approval" | "choice" | "input";
+
+/**
+ * 审批"允许"的作用域（Hermes 审批门 / claude `canUseTool` 等宿主可能提供多种允许粒度）：
+ * - once    仅本次允许（默认）
+ * - session 本会话内允许
+ * - always  总是允许（宿主永久 allowlist）
+ * 手机端按请求方提供的 allowed 作用域渲染按钮；仅当 status="allow" 时生效，缺省视为 once。
+ */
+export type PermissionScope = "once" | "session" | "always";
+
+export interface PermissionRequest {
+  id: string;
+  sessionID: string;
+  tool: string;
+  args: Record<string, unknown>;
+  prompt?: string;
+  createdAt: number;
+  /** 作答方式（缺省视为 approval） */
+  kind?: PermissionKind;
+  /** choice 类型的可选项（显示为按钮列表） */
+  options?: string[];
+}
+
+/** 手机端对权限请求的应答（permission.reply）。status=allow 时可携带 scope 表达允许作用域。 */
+export interface PermissionReply {
+  permissionID: string;
+  status: "allow" | "deny";
+  /** 允许作用域（status=allow 时生效；缺省 once）。宿主仅接受其提供的 allowed 作用域。 */
+  scope?: PermissionScope;
+  /** 兼容旧字段：是否总是允许（等价 scope="always"）。 */
+  always?: boolean;
+  /** choice/input 型作答的选中值/输入文本。 */
+  value?: string;
+}
+
+/** 结构化提问（opencode question.v2.asked 等）中的单条问题。 */
+export interface QuestionInfo {
+  question: string;
+  header?: string;
+  options: string[];
+  multiple?: boolean;
+  custom?: boolean;
+}
+
+export interface QuestionRequest {
+  id: string;
+  sessionID: string;
+  prompt?: string;
+  questions: QuestionInfo[];
+  createdAt: number;
+  /**
+   * 会话内容锚点（可选）：该提问对应会话里哪条 assistant 消息/哪个 tool-call 部件，
+   * 前端可据此把选择卡内联到消息下方渲染（如 dsh 的 ask_user_question / exit_plan_mode）。
+   */
+  messageID?: string;
+  partID?: string;
+}
+
+export interface CommandInfo {
+  name: string;
+  description?: string;
+}
+
+/** 账号体系（Phase 1）：电脑被手机账号认领后 relay 下发。 */
+export interface AgentClaimedMessage {
+  email?: string;
+}
+
+/** 账号体系（Phase 1）：电脑被解绑后 relay 下发，适配器应重置并重新生成 agentID。 */
+export interface AgentRevokedMessage {}
+
+/** agent 断开后中继推送给已连接手机（在线信号为 agent.info 广播）。 */
+export interface AgentOfflineMessage {
+  agentID?: string;
+}