arona-agent 1.0.0

package/src/config.ts

@@ -0,0 +1,245 @@
+import { homedir } from "os";
+import { join, resolve } from "path";
+import { existsSync, mkdirSync, readFileSync } from "fs";
+import type { LanguageSetting } from "./locale.ts";
+
+export const ARONA_DIR = join(homedir(), ".arona");
+export const MEMORY_FILE = join(ARONA_DIR, "MEMORY.md");
+export const SESSIONS_DIR = join(ARONA_DIR, "sessions");
+export const SKILLS_DIR = join(ARONA_DIR, "skills");
+export const SETTINGS_FILE = join(ARONA_DIR, "settings.json");
+export const PROJECT_ROOT = resolve(import.meta.dirname, "..");
+export const PYTHON_DIR = join(PROJECT_ROOT, "python");
+export const PET_DIR = join(PROJECT_ROOT, "pet");
+
+// Ensure directories exist
+function ensureDir(path: string) {
+  if (!existsSync(path)) mkdirSync(path, { recursive: true });
+}
+ensureDir(ARONA_DIR);
+ensureDir(SESSIONS_DIR);
+ensureDir(SKILLS_DIR);
+
+// Parse --no-voice flag from CLI args
+const noVoice = process.argv.includes("--no-voice");
+
+// Parse --verbose flag from CLI args（桌宠/子进程详细日志；Electron 加 --enable-logging 转发 renderer 日志）
+export const verbose = process.argv.includes("--verbose");
+
+export interface McpServerConfig {
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  url?: string;
+  /** 仅 url 型（Streamable HTTP）server 生效：自定义请求头，如 Authorization */
+  headers?: Record<string, string>;
+}
+
+interface AronaConfig {
+  // LLM
+  apiKey: string;
+  apiBaseUrl: string;
+  model: string;
+  thinkingLevel: string;
+  // 上下文窗口（token 数）：用于压缩阈值推导。settings.json 直接填数字（如 1000000），不填默认 1M。
+  contextWindow: number;
+  // Voice (Qwen / 阿里云百炼 DashScope)
+  noVoice: boolean;
+  // 百炼业务空间 ID（可选；留空走旧域名 dashscope.aliyuncs.com）
+  workspaceId: string;
+  ttsApiKey: string;
+  ttsModel: string;
+  // 系统音色名 或 自定义音色(声音复刻)ID —— 填声音复刻得到的 voice_id 即用自定义音色
+  ttsVoice: string;
+  ttsSampleRate: number;
+  sttApiKey: string;
+  sttModel: string;
+  sttFormat: string;
+  sttSampleRate: number;
+  ttsEnabled: boolean;
+  sttEnabled: boolean;
+  // Cua
+  cuaApiKey: string;
+  // Tavily（网页搜索；留空走 keyless 共享池，免费限流）
+  tavilyApiKey: string;
+  // Misc
+  pythonPath: string;
+  mcpServers: Record<string, McpServerConfig>;
+}
+
+interface Settings {
+  apiKey?: string;
+  apiBaseUrl?: string;
+  model?: string;
+  thinkingLevel?: string;
+  // 上下文窗口（token 数），默认 1M。用于压缩阈值推导，不填 SDK 走模型注册表。
+  contextWindow?: number;
+  language?: LanguageSetting;
+  // 主 Agent（arona | plana）：桌宠形象 + 人格，由 agent_registry.ts 读写
+  mainAgent?: string;
+  // 启用的子 Agent 列表（shiroko | hoshino），由 agent_registry.ts 读写
+  subAgents?: string[];
+  ttsEnabled?: boolean;
+  sttEnabled?: boolean;
+  /** @deprecated 已合并进 ttsEnabled，仅读兼容（旧配置 ttsAuto:false 仍生效） */
+  ttsAuto?: boolean;
+  workspaceId?: string;
+  ttsApiKey?: string;
+  ttsModel?: string;
+  ttsVoice?: string;
+  ttsSampleRate?: number;
+  sttApiKey?: string;
+  sttModel?: string;
+  sttFormat?: string;
+  sttSampleRate?: number;
+  cuaApiKey?: string;
+  // Tavily API Key（可选）：不填则 web_search/web_extract 走 keyless 共享池
+  tavilyApiKey?: string;
+  pythonPath?: string;
+  mcpServers?: Record<string, McpServerConfig>;
+}
+
+/**
+ * Check if ~/.arona/settings.json exists.
+ */
+export function settingsExist(): boolean {
+  return existsSync(SETTINGS_FILE);
+}
+
+/**
+ * Load settings from ~/.arona/settings.json.
+ * Returns {} if the file is missing or unparseable.
+ */
+function loadSettings(): Settings {
+  if (!existsSync(SETTINGS_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(SETTINGS_FILE, "utf-8"));
+  } catch {
+    console.warn("Failed to parse settings.json, using defaults");
+    return {};
+  }
+}
+
+// ============================================================
+// Model prefix auto-detection
+// ============================================================
+
+/**
+ * Model name patterns → provider prefix.
+ * Checked in order; first match wins. Higher priority than Base URL.
+ */
+const MODEL_PATTERNS: Array<[RegExp, string]> = [
+  [/^gpt[-_]/i, "openai"],
+  [/^o[134][-_]/i, "openai"],
+  [/^claude[-_]/i, "anthropic"],
+  [/^deepseek[-_]/i, "deepseek"],
+  [/^gemini[-_]/i, "google"],
+  [/^grok[-_]/i, "xai"],
+  [/^minimax[-_]/i, "minimax-cn"],
+  [/^kimi[-_]/i, "moonshotai-cn"],
+  [/^glm[-_]/i, "zai-coding-cn"],
+  [/^qwen/i, "qwen-token-plan-cn"],
+  [/^mistral[-_]/i, "mistral"],
+  [/^codestral[-_]/i, "mistral"],
+  [/^devstral[-_]/i, "mistral"],
+  [/^mimo[-_]/i, "xiaomi-token-plan-cn"],
+  [/^llama[-_]/i, "openrouter"],
+];
+
+/**
+ * Base URL domain → provider prefix.
+ * Checked in order; first match wins. Lower priority than model name.
+ */
+const URL_DOMAINS: Array<[string, string]> = [
+  ["api.openai.com", "openai"],
+  ["api.anthropic.com", "anthropic"],
+  ["api.deepseek.com", "deepseek"],
+  ["generativelanguage.googleapis.com", "google"],
+  ["api.x.ai", "xai"],
+  ["api.minimax.chat", "minimax-cn"],
+  ["api.moonshot.cn", "moonshotai-cn"],
+  ["open.bigmodel.cn", "zai-coding-cn"],
+  ["dashscope.aliyuncs.com", "qwen-token-plan-cn"],
+  ["api.mistral.ai", "mistral"],
+  ["openrouter.ai", "openrouter"],
+  ["api.groq.com", "groq"],
+];
+
+/**
+ * Auto-detect the provider prefix for a model name.
+ *
+ * - If the model already contains "/", return it as-is.
+ * - Otherwise, detect from the model name (higher priority), then Base URL.
+ * - Defaults to "openai" if nothing matches.
+ */
+export function resolveModelPrefix(model: string, apiBaseUrl: string): string {
+  // Already has a prefix
+  if (model.includes("/")) return model;
+
+  // 1. Model name patterns (higher priority)
+  for (const [pattern, provider] of MODEL_PATTERNS) {
+    if (pattern.test(model)) {
+      return `${provider}/${model}`;
+    }
+  }
+
+  // 2. Base URL domain (lower priority)
+  if (apiBaseUrl) {
+    const urlLower = apiBaseUrl.toLowerCase();
+    for (const [domain, provider] of URL_DOMAINS) {
+      if (urlLower.includes(domain)) {
+        return `${provider}/${model}`;
+      }
+    }
+  }
+
+  // 3. Default
+  return `openai/${model}`;
+}
+
+function loadConfig(): AronaConfig {
+  const s = loadSettings();
+
+  const apiKey = s.apiKey || "";
+  const apiBaseUrl = s.apiBaseUrl || "";
+
+  // Set OPENAI_BASE_URL for OpenAI-compatible endpoints
+  if (apiBaseUrl) {
+    process.env.OPENAI_BASE_URL = apiBaseUrl;
+  }
+
+  // Auto-detect model prefix
+  const rawModel = s.model || "openai/gpt-4o";
+  const model = resolveModelPrefix(rawModel, apiBaseUrl);
+
+  return {
+    apiKey,
+    apiBaseUrl,
+    model,
+    thinkingLevel: s.thinkingLevel || "medium",
+    contextWindow: typeof s.contextWindow === "number" && s.contextWindow > 0 ? s.contextWindow : 1000000,
+
+    noVoice,
+    // Skip TTS/STT fields when --no-voice is set
+    workspaceId: noVoice ? "" : (s.workspaceId || ""),
+    ttsApiKey: noVoice ? "" : (s.ttsApiKey || ""),
+    ttsModel: noVoice ? "" : (s.ttsModel || "qwen-audio-3.0-tts-plus"),
+    ttsVoice: noVoice ? "" : (s.ttsVoice || ""),
+    ttsSampleRate: noVoice ? 22050 : (s.ttsSampleRate || 22050),
+    sttApiKey: noVoice ? "" : (s.sttApiKey || ""),
+    sttModel: noVoice ? "" : (s.sttModel || "qwen-audio-3.0-asr-flash-streaming"),
+    sttFormat: noVoice ? "pcm" : (s.sttFormat || "pcm"),
+    sttSampleRate: noVoice ? 16000 : (s.sttSampleRate || 16000),
+    // ttsAuto 已合并进 ttsEnabled（旧配置兼容：ttsAuto ?? true）
+    ttsEnabled: noVoice ? false : (s.ttsEnabled ?? s.ttsAuto ?? true),
+    sttEnabled: noVoice ? false : (s.sttEnabled ?? true),
+
+    cuaApiKey: s.cuaApiKey || "",
+    tavilyApiKey: s.tavilyApiKey || "",
+
+    pythonPath: s.pythonPath || (process.platform === "win32" ? "python" : "python3"),
+    mcpServers: s.mcpServers || {},
+  };
+}
+
+export const config = loadConfig();

package/src/in_memory_credentials.ts

@@ -0,0 +1,61 @@
+/**
+ * 内存版凭证存储 —— 替代 Pi SDK 默认的 ~/.arona/auth.json。
+ *
+ * ARONA 的 API key 由 settings.json → setRuntimeApiKey() 在启动时注入
+ * RuntimeCredentials 的内存 overrides，从不落盘。给 ModelRuntime.create()
+ * 传入本存储，可让 SDK 跳过 FileAuthStorageBackend，彻底不再创建 auth.json。
+ *
+ * 代价：OAuth 订阅制登录（radius 网关等）的凭证无法跨会话持久化。
+ * 仅 type-only 导入，运行时零依赖，不受 pi-ai 版本分裂影响。
+ */
+import type {
+  AuthOperationOptions,
+  Credential,
+  CredentialInfo,
+  CredentialStore,
+} from "@earendil-works/pi-ai";
+
+/** 按 provider 串行化的写队列：保证 modify/delete 互斥，语义与 SDK 内存版一致。 */
+export class InMemoryCredentialStore implements CredentialStore {
+  private credentials = new Map<string, Credential>();
+  private chains = new Map<string, Promise<unknown>>();
+
+  private enqueue<T>(providerId: string, task: () => Promise<T>): Promise<T> {
+    const prev = this.chains.get(providerId) ?? Promise.resolve();
+    const next = prev.then(task, task);
+    this.chains.set(providerId, next.catch(() => undefined));
+    return next;
+  }
+
+  async read(providerId: string): Promise<Credential | undefined> {
+    return this.credentials.get(providerId);
+  }
+
+  async list(): Promise<readonly CredentialInfo[]> {
+    return [...this.credentials.entries()].map(([providerId, credential]) => ({
+      providerId,
+      type: credential.type,
+    }));
+  }
+
+  modify(
+    providerId: string,
+    fn: (current: Credential | undefined) => Promise<Credential | undefined>,
+  ): Promise<Credential | undefined> {
+    return this.enqueue(providerId, async () => {
+      const current = this.credentials.get(providerId);
+      const next = await fn(current);
+      // SDK 契约：fn 返回 undefined 表示"保持不变"（返回当前值），而非删除凭证
+      if (next !== undefined) {
+        this.credentials.set(providerId, next);
+      }
+      return next ?? current;
+    });
+  }
+
+  delete(providerId: string): Promise<void> {
+    return this.enqueue(providerId, async () => {
+      this.credentials.delete(providerId);
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,78 @@
+import { initAgent } from "./agent.ts";
+import { Repl } from "./repl.ts";
+import { resetConversationFlag, loadSession } from "./memory.ts";
+import { startPet } from "./pet.ts";
+import { config, settingsExist } from "./config.ts";
+import { t } from "./locale.ts";
+import chalk from "chalk";
+
+async function main() {
+  // Require settings.json — if missing, tell user to run arona setup
+  if (!settingsExist()) {
+    console.log(chalk.yellow(t("未找到配置文件。", "Config file not found.")));
+    console.log(chalk.cyan(t("请先运行 arona setup 进行初始化配置。", "Please run arona setup to initialize first.")));
+    process.exit(1);
+  }
+
+  // Check for required environment
+  if (!config.apiKey) {
+    console.log(chalk.yellow(t("警告：未找到 LLM API Key。", "Warning: LLM API Key not found.")));
+    console.log(chalk.cyan(t("请运行 arona setup 进行配置。", "Please run arona setup to configure.")));
+    console.log();
+  }
+
+  if (config.noVoice) {
+    console.log(chalk.cyan(t("语音功能已禁用（--no-voice）。", "Voice features disabled (--no-voice).")));
+  }
+
+  // Initialize agent
+  console.log(chalk.cyan(t("正在初始化 ARONA...", "Initializing ARONA...")));
+
+  let { session, modelRuntime, loader } = await initAgent();
+
+  // 启动桌宠（首次需下载 Electron 二进制，须等下载完成再进入 REPL，避免卡在后台静默下载）
+  await startPet();
+
+  // Handle session resume from command line arg
+  // 只加载消息到 session，渲染交给 Repl.start() 处理（确保 logo 在历史记录之前）
+  // initialSessionPath 传给 Repl，退出时覆盖保存回原文件而非另存为新文件
+  let resumedMessages: any[] | null = null;
+  let initialSessionPath: string | null = null;
+  const resumeArg = process.argv.find((a) => a.startsWith("--resume="));
+  if (resumeArg) {
+    const sessionPath = resumeArg.split("=")[1];
+    try {
+      resumedMessages = loadSession(sessionPath);
+      session.agent.state.messages = resumedMessages;
+      initialSessionPath = sessionPath;
+    } catch (err) {
+      console.warn(chalk.yellow(t("恢复会话失败：", "Failed to resume: ") + (err instanceof Error ? err.message : err)));
+    }
+  }
+
+  // Start REPL
+  const repl = new Repl(
+    session,
+    modelRuntime,
+    loader,
+    () => {
+      // onExit - cleanup is handled in repl
+    },
+    async () => {
+      // onNewSession - dispose old session, recreate, and return it so
+      // the Repl can rebind its reference + renderer subscription.
+      session.dispose();
+      resetConversationFlag();
+      return await initAgent();
+    },
+    resumedMessages,
+    initialSessionPath,
+  );
+
+  await repl.start();
+}
+
+main().catch((err) => {
+  console.error(chalk.red(t("致命错误：", "Fatal error: ") + (err instanceof Error ? err.message : err)));
+  process.exit(1);
+});

package/src/locale.ts

@@ -0,0 +1,131 @@
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, readFileSync } from "fs";
+import { execFileSync } from "child_process";
+
+type Language = "zh" | "en";
+export type LanguageSetting = "auto" | "zh" | "en";
+
+const SETTINGS_FILE = join(homedir(), ".arona", "settings.json");
+
+/**
+ * 读取 ~/.arona/settings.json 中的 language 字段（"auto"|"zh"|"en"）。
+ * 不 import config.ts —— config 在模块加载时读 settings，locale 再依赖它会成环。
+ * 解析失败或字段缺失返回 "auto"。
+ */
+function readSettingsLanguage(): LanguageSetting {
+  try {
+    if (!existsSync(SETTINGS_FILE)) return "auto";
+    const s = JSON.parse(readFileSync(SETTINGS_FILE, "utf-8")) as { language?: unknown };
+    const v = s.language;
+    if (v === "zh" || v === "en") return v;
+    return "auto";
+  } catch {
+    return "auto";
+  }
+}
+
+/** 统一英文判定：locale 以 "en" 开头（大小写不敏感）。 */
+function isEnglishLocale(locale: string): boolean {
+  return /^en/i.test(locale.trim());
+}
+
+/** 平台系统偏好检测（仅当环境变量缺失/未命中时调用一次）。失败静默返回 null。 */
+function detectSystemLocale(): string | null {
+  const platform = process.platform;
+  try {
+    if (platform === "darwin") {
+      // macOS: 系统语言列表，如 ["en-US", "zh-Hans"]，取首项
+      const out = execFileSync("defaults", ["read", "-g", "AppleLanguages"], {
+        encoding: "utf-8",
+        timeout: 3000,
+      }).trim();
+      const match = out.match(/["']([^"']+)["']/);
+      return match ? match[1] : null;
+    }
+    if (platform === "win32") {
+      // Windows: 注册表用户语言列表（分号分隔），取首个
+      try {
+        const out = execFileSync(
+          "reg",
+          ["query", "HKCU\\Control Panel\\International\\User Profile", "/v", "Languages"],
+          { encoding: "utf-8", timeout: 3000 },
+        );
+        const m = out.match(/LANGUAGES\s+REG_SZ\s+([^\r\n]+)/i);
+        if (m) {
+          const first = m[1].trim().split(";")[0];
+          if (first) return first;
+        }
+      } catch {
+        // 回退 PowerShell
+      }
+      const ps = execFileSync(
+        "powershell",
+        ["-NoProfile", "-Command", "[System.Globalization.CultureInfo]::CurrentUICulture.Name"],
+        { encoding: "utf-8", timeout: 5000 },
+      ).trim();
+      return ps || null;
+    }
+    // Linux 等：LANG 已在环境变量步骤覆盖，无需额外命令
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 检测当前语言。优先级链：
+ *   1. settings.json 手动配置（zh/en 直接定型；auto 继续下探）
+ *   2. 环境变量 LANG / LC_ALL（/^en/i 命中 → en）
+ *   3. 平台系统偏好（macOS defaults / Windows 注册表 + CurrentUICulture）
+ *   4. Intl 兜底
+ *   5. 默认 zh
+ */
+function detectLanguage(): Language {
+  // 1) 手动配置
+  const setting = readSettingsLanguage();
+  if (setting === "zh" || setting === "en") return setting;
+
+  // 2) 环境变量
+  const envLocale = process.env.LANG || process.env.LC_ALL || process.env.LC_MESSAGES || "";
+  if (envLocale && isEnglishLocale(envLocale)) return "en";
+  // 环境变量命中中文则直接定型，避免中文系统上再跑系统命令
+  if (/^zh/i.test(envLocale)) return "zh";
+
+  // 3) 平台系统偏好
+  const systemLocale = detectSystemLocale();
+  if (systemLocale) {
+    if (isEnglishLocale(systemLocale)) return "en";
+    if (/^zh/i.test(systemLocale)) return "zh";
+  }
+
+  // 4) Intl 兜底
+  try {
+    const intlLocale = Intl.DateTimeFormat().resolvedOptions().locale || "";
+    if (isEnglishLocale(intlLocale)) return "en";
+    if (/^zh/i.test(intlLocale)) return "zh";
+  } catch {
+    // ignore
+  }
+
+  // 5) 默认
+  return "zh";
+}
+
+// 模块加载时检测一次，全局缓存。运行时语言不热切换（符合"启动检测一次"的设计）。
+let lang: Language = detectLanguage();
+
+/** 按当前语言返回中英两版文案之一。 */
+export function t(zh: string, en: string): string {
+  return lang === "en" ? en : zh;
+}
+
+/** 当前语言（只读）。 */
+export function getLang(): Language {
+  return lang;
+}
+
+/** 手动切换语言（setup 向导改语言后即时生效）。 */
+export function setLang(l: Language): void {
+  lang = l;
+}

package/src/logo.ts

@@ -0,0 +1,120 @@
+/**
+ * 开屏 ASCII 艺术字（动态生成）。
+ *
+ * 使用 figlet 根据终端宽度自动选择合适的字体，确保在各种终端宽度下
+ * 都能显示立体艺术字。配色保留 SCHALE 风格的蓝→浅蓝→青三段行级渐变。
+ */
+
+import figlet from "figlet";
+
+// 配色（与原 launcher.sh 一致）
+const C = "\x1b[38;2;0;210;255m"; // CYAN  #00D2FF  边框 + 底部字母
+const B = "\x1b[38;2;66;135;245m"; // BLUE  #4287F5  顶部字母
+const L = "\x1b[38;2;100;180;255m"; // LIGHT_BLUE #64B4FF 中部字母
+const R = "\x1b[0m"; // RESET
+
+// 字体降级策略：ANSI Shadow 绝对优先，剩下立体优先、平面兜底
+//
+// 1) ANSI Shadow + 完整 "ARONA AGENT"   （用户最想要的效果，~101 列）
+// 2) ANSI Shadow + 缩短 "ARONA"         （~53 列）
+// 3) 其他 3D 立体字体（按宽度降序）：每个字体都先试 "ARONA AGENT"，装不下再试 "ARONA"
+// 4) 平面字体（最后兜底）：按宽度降序，每个字体也是先 AGENT 再 ARONA
+//
+// 列数估算已留出边框 2 格 + 缩进 2 格 + 内边距 6 格（即 width + 10）
+const VARIANTS: { text: string; font: figlet.Fonts }[] = [
+  // —— ANSI Shadow 绝对优先 ——
+  { text: "ARONA AGENT", font: "ANSI Shadow" }, // ~101 列
+  { text: "ARONA",       font: "ANSI Shadow" }, // ~53 列
+
+  // —— 其他 3D 立体字体（按宽度降序，AGENT → ARONA 配对） ——
+  { text: "ARONA AGENT", font: "Line Blocks" },     // ~100
+  { text: "ARONA",       font: "Line Blocks" },     // ~55
+  { text: "ARONA AGENT", font: "Larry 3D 2" },      // ~96
+  { text: "ARONA",       font: "Larry 3D 2" },      // ~54
+  { text: "ARONA AGENT", font: "Larry 3D" },        // ~96
+  { text: "ARONA",       font: "Larry 3D" },        // ~54
+  { text: "ARONA AGENT", font: "Speed" },           // ~96
+  { text: "ARONA",       font: "Speed" },           // ~49
+  { text: "ARONA AGENT", font: "Banner" },          // ~94
+  { text: "ARONA",       font: "Banner" },          // ~51
+  { text: "ARONA AGENT", font: "Old Banner" },      // ~93
+  { text: "ARONA",       font: "Old Banner" },      // ~50
+  { text: "ARONA AGENT", font: "Shadow" },          // ~91
+  { text: "ARONA",       font: "Shadow" },          // ~50
+  { text: "ARONA AGENT", font: "JS Block Letters" }, // ~83
+  { text: "ARONA",       font: "JS Block Letters" }, // ~46
+  { text: "ARONA AGENT", font: "Broadway KB" },      // ~79
+  { text: "ARONA",       font: "Broadway KB" },      // ~43
+  { text: "ARONA AGENT", font: "Small Shadow" },     // ~75
+  { text: "ARONA",       font: "Small Shadow" },     // ~42
+  { text: "ARONA AGENT", font: "Pyramid" },          // ~63
+  { text: "ARONA",       font: "Pyramid" },          // ~35
+
+  // —— 平面字体兜底（按宽度降序，AGENT → ARONA 配对） ——
+  { text: "ARONA AGENT", font: "Big" },              // ~88
+  { text: "ARONA",       font: "Big" },              // ~50
+  { text: "ARONA AGENT", font: "Slant" },            // ~79
+  { text: "ARONA",       font: "Slant" },            // ~43
+  { text: "ARONA AGENT", font: "Standard" },         // ~79
+  { text: "ARONA",       font: "Standard" },         // ~43
+  { text: "ARONA AGENT", font: "Small" },            // ~66
+  { text: "ARONA",       font: "Small" },            // ~39
+  { text: "ARONA",       font: "Mini" },             // ~34
+  { text: "ARONA",       font: "Bubble" },           // ~32
+  { text: "ARONA",       font: "Digital" },          // ~22
+];
+
+/**
+ * 输出开屏 logo。根据终端宽度自动选择 figlet 字体，
+ * 确保艺术字不会超出终端宽度导致换行错乱。
+ */
+export function printLogo(): void {
+  const cols = process.stdout.columns ?? 80;
+  const indent = "  ";
+  const pad = 3; // 边框内 padding
+
+  for (const { text, font } of VARIANTS) {
+    try {
+      const rendered = figlet.textSync(text, { font });
+      let lines = rendered.split("\n");
+      // 去除首尾全空行
+      lines = lines.filter((l) => l.trim().length > 0);
+      if (lines.length === 0) continue;
+
+      const maxLen = Math.max(...lines.map((l) => l.length));
+      const innerWidth = maxLen + pad * 2; // 内容区宽度（不含 ║）
+      const totalWidth = innerWidth + 2 + indent.length; // +2 for ║║
+
+      if (totalWidth > cols) continue;
+
+      // 三段渐变：上 1/3 蓝、中 1/3 浅蓝、下 1/3 青
+      const n = lines.length;
+      const bEnd = Math.floor(n / 3);
+      const lEnd = Math.floor((n * 2) / 3);
+
+      const border = "═".repeat(innerWidth);
+      const blank = " ".repeat(innerWidth);
+      const padStr = " ".repeat(pad);
+
+      const out: string[] = [];
+      out.push(`${C}${indent}╔${border}╗${R}`);
+      out.push(`${C}${indent}║${blank}║${R}`);
+      lines.forEach((line, i) => {
+        const color = i < bEnd ? B : i < lEnd ? L : C;
+        const padded = line.padEnd(maxLen, " ");
+        out.push(`${C}${indent}║${padStr}${color}${padded}${C}${padStr}║${R}`);
+      });
+      out.push(`${C}${indent}║${blank}║${R}`);
+      out.push(`${C}${indent}╚${border}╝${R}`);
+
+      process.stdout.write("\n" + out.join("\n") + "\n\n");
+      return;
+    } catch {
+      // 字体不存在或渲染失败，尝试下一个
+      continue;
+    }
+  }
+
+  // 所有字体都放不下，退化为单行文字
+  process.stdout.write(`${C}  ARONA AGENT${R}\n\n`);
+}