@spaceflow/core 0.1.1

package/src/shared/llm-proxy/stream-logger.ts

@@ -0,0 +1,97 @@
+import type { LlmStreamEvent } from "./interfaces";
+
+export interface StreamLoggerState {
+  isFirstText: boolean;
+}
+
+/**
+ * 创建一个新的 StreamLogger 状态
+ */
+export function createStreamLoggerState(): StreamLoggerState {
+  return { isFirstText: true };
+}
+
+/**
+ * 记录 LLM 流式事件到终端
+ * @param event LLM 流式事件
+ * @param state 日志状态（用于跟踪是否是第一个文本块）
+ */
+export function logStreamEvent(event: LlmStreamEvent, state: StreamLoggerState): void {
+  switch (event.type) {
+    case "text":
+      if (state.isFirstText) {
+        process.stdout.write("\n🤖 AI: ");
+        state.isFirstText = false;
+      }
+      process.stdout.write(event.content);
+      break;
+    case "tool_use":
+      console.log(`\n🛠️  工具调用: ${event.name}`);
+      if (event.title) {
+        console.log(`   标题: ${event.title}`);
+      }
+      console.log(`   输入: ${JSON.stringify(event.input)}`);
+      if (event.status) {
+        console.log(`   状态: ${event.status}`);
+      }
+      if (event.output) {
+        console.log(
+          `   输出: ${event.output.substring(0, 200)}${event.output.length > 200 ? "..." : ""}`,
+        );
+      }
+      state.isFirstText = true;
+      break;
+    case "thought":
+      console.log(`\n💭 思考: ${event.content}`);
+      state.isFirstText = true;
+      break;
+    case "result":
+      console.log(`\n✅ 结果已返回`);
+      state.isFirstText = true;
+      break;
+    case "error":
+      console.error(`\n❌ 错误: ${event.message}`);
+      state.isFirstText = true;
+      break;
+    case "agent":
+      console.log(`\n🤖 子代理: ${event.name}`);
+      if (event.source) {
+        console.log(
+          `   来源: ${event.source.substring(0, 100)}${event.source.length > 100 ? "..." : ""}`,
+        );
+      }
+      state.isFirstText = true;
+      break;
+    case "subtask":
+      console.log(`\n📋 子任务: ${event.description}`);
+      console.log(`   代理: ${event.agent}`);
+      console.log(
+        `   提示: ${event.prompt.substring(0, 100)}${event.prompt.length > 100 ? "..." : ""}`,
+      );
+      state.isFirstText = true;
+      break;
+    case "step_start":
+      console.log(`\n▶️  步骤开始`);
+      state.isFirstText = true;
+      break;
+    case "step_finish":
+      console.log(`\n⏹️  步骤结束: ${event.reason}`);
+      if (event.tokens) {
+        const tokens = event.tokens as any;
+        console.log(
+          `   Token: 输入=${tokens.input || 0}, 输出=${tokens.output || 0}, 推理=${tokens.reasoning || 0}`,
+        );
+      }
+      if (event.cost !== undefined) {
+        console.log(`   成本: $${event.cost.toFixed(6)}`);
+      }
+      state.isFirstText = true;
+      break;
+    case "reasoning":
+      console.log(
+        `\n🧠 推理: ${event.content.substring(0, 200)}${event.content.length > 200 ? "..." : ""}`,
+      );
+      state.isFirstText = true;
+      break;
+  }
+}

package/src/shared/logger/index.ts

@@ -0,0 +1,11 @@
+export { Logger } from "./logger";
+export type {
+  LoggerOptions,
+  LogLevel,
+  RenderMode,
+  Spinner,
+  ProgressBar,
+  ProgressBarOptions,
+  TaskItem,
+  TaskControl,
+} from "./logger.interface";

package/src/shared/logger/logger.interface.ts

@@ -0,0 +1,93 @@
+import type { LogLevel } from "../verbose";
+import { LOG_LEVEL_PRIORITY } from "../verbose";
+
+export type { LogLevel };
+export { LOG_LEVEL_PRIORITY };
+
+/** 渲染模式 */
+export type RenderMode = "plain" | "tui" | "auto";
+
+/** Logger 配置 */
+export interface LoggerOptions {
+  /** 日志所属命名空间（通常为命令名） */
+  readonly name: string;
+  /** 输出模式，默认 "auto"（TTY=tui，CI/管道=plain） */
+  readonly mode?: RenderMode;
+  /** 日志级别，默认 "info" */
+  readonly level?: LogLevel;
+}
+
+/** Spinner 控制接口 */
+export interface Spinner {
+  /** 更新 spinner 文本 */
+  update(message: string): void;
+  /** 成功结束 */
+  succeed(message?: string): void;
+  /** 失败结束 */
+  fail(message?: string): void;
+  /** 静默停止 */
+  stop(): void;
+}
+
+/** 进度条控制接口 */
+export interface ProgressBar {
+  /** 更新进度 */
+  update(current: number, message?: string): void;
+  /** 完成 */
+  finish(message?: string): void;
+}
+
+/** 进度条配置 */
+export interface ProgressBarOptions {
+  /** 总数 */
+  readonly total: number;
+  /** 标签 */
+  readonly label?: string;
+  /** 进度条宽度（字符数），默认 30 */
+  readonly width?: number;
+}
+
+/** 任务控制接口 */
+export interface TaskControl {
+  /** 更新任务状态文本 */
+  update(message: string): void;
+  /** 跳过任务 */
+  skip(reason?: string): void;
+}
+
+/** 任务项定义 */
+export interface TaskItem<T = void> {
+  /** 任务标题 */
+  readonly title: string;
+  /** 任务执行函数 */
+  readonly task: (ctx: T, control: TaskControl) => Promise<T>;
+  /** 是否启用，默认 true */
+  readonly enabled?: boolean;
+}
+
+/** 任务执行结果 */
+export type TaskStatus = "pending" | "running" | "success" | "failed" | "skipped";
+
+/** 渲染器接口（策略模式） */
+export interface LogRenderer {
+  /** 输出 info 级别日志 */
+  info(prefix: string, message: string): void;
+  /** 输出 success 级别日志 */
+  success(prefix: string, message: string): void;
+  /** 输出 warn 级别日志 */
+  warn(prefix: string, message: string): void;
+  /** 输出 error 级别日志 */
+  error(prefix: string, message: string): void;
+  /** 输出 debug 级别日志 */
+  debug(prefix: string, message: string): void;
+  /** 输出 verbose 级别日志 */
+  verbose(prefix: string, message: string): void;
+  /** 创建 Spinner */
+  createSpinner(prefix: string, message: string): Spinner;
+  /** 创建进度条 */
+  createProgressBar(prefix: string, options: ProgressBarOptions): ProgressBar;
+  /** 执行任务列表 */
+  runTasks<T>(prefix: string, items: TaskItem<T>[]): Promise<T[]>;
+  /** 输出表格 */
+  table(prefix: string, data: Record<string, unknown>[]): void;
+}

package/src/shared/logger/logger.spec.ts

@@ -0,0 +1,178 @@
+import { vi, type MockInstance } from "vitest";
+import { Logger } from "./logger";
+
+describe("Logger", () => {
+  let consoleSpy: {
+    log: MockInstance;
+    warn: MockInstance;
+    error: MockInstance;
+  };
+
+  beforeEach(() => {
+    consoleSpy = {
+      log: vi.spyOn(console, "log").mockImplementation(),
+      warn: vi.spyOn(console, "warn").mockImplementation(),
+      error: vi.spyOn(console, "error").mockImplementation(),
+    };
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("基础日志", () => {
+    it("info 输出包含前缀和消息", () => {
+      const logger = new Logger({ name: "test", mode: "plain" });
+      logger.info("hello");
+      expect(consoleSpy.log).toHaveBeenCalledTimes(1);
+      const output = consoleSpy.log.mock.calls[0][0] as string;
+      expect(output).toContain("[test]");
+      expect(output).toContain("hello");
+    });
+
+    it("success 输出包含 ✅", () => {
+      const logger = new Logger({ name: "test", mode: "plain" });
+      logger.success("done");
+      const output = consoleSpy.log.mock.calls[0][0] as string;
+      expect(output).toContain("✅");
+      expect(output).toContain("done");
+    });
+
+    it("warn 使用 console.warn", () => {
+      const logger = new Logger({ name: "test", mode: "plain" });
+      logger.warn("caution");
+      expect(consoleSpy.warn).toHaveBeenCalledTimes(1);
+      const output = consoleSpy.warn.mock.calls[0][0] as string;
+      expect(output).toContain("caution");
+    });
+
+    it("error 使用 console.error", () => {
+      const logger = new Logger({ name: "test", mode: "plain" });
+      logger.error("fail");
+      expect(consoleSpy.error).toHaveBeenCalledTimes(1);
+      const output = consoleSpy.error.mock.calls[0][0] as string;
+      expect(output).toContain("fail");
+    });
+  });
+
+  describe("日志级别", () => {
+    it("level=info 时 verbose 不输出", () => {
+      const logger = new Logger({ name: "test", mode: "plain", level: "info" });
+      logger.verbose("detail");
+      expect(consoleSpy.log).not.toHaveBeenCalled();
+    });
+
+    it("level=verbose 时 verbose 输出", () => {
+      const logger = new Logger({ name: "test", mode: "plain", level: "verbose" });
+      logger.verbose("detail");
+      expect(consoleSpy.log).toHaveBeenCalledTimes(1);
+    });
+
+    it("level=verbose 时 debug 不输出", () => {
+      const logger = new Logger({ name: "test", mode: "plain", level: "verbose" });
+      logger.debug("trace");
+      expect(consoleSpy.log).not.toHaveBeenCalled();
+    });
+
+    it("level=debug 时 debug 输出", () => {
+      const logger = new Logger({ name: "test", mode: "plain", level: "debug" });
+      logger.debug("trace");
+      expect(consoleSpy.log).toHaveBeenCalledTimes(1);
+      const output = consoleSpy.log.mock.calls[0][0] as string;
+      expect(output).toContain("[DEBUG]");
+    });
+
+    it("level=silent 时所有日志不输出", () => {
+      const logger = new Logger({ name: "test", mode: "plain", level: "silent" });
+      logger.info("a");
+      logger.success("b");
+      logger.warn("c");
+      logger.error("d");
+      logger.verbose("e");
+      logger.debug("f");
+      expect(consoleSpy.log).not.toHaveBeenCalled();
+      expect(consoleSpy.warn).not.toHaveBeenCalled();
+      expect(consoleSpy.error).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("字符串构造", () => {
+    it("支持字符串参数快捷创建", () => {
+      const logger = new Logger("build");
+      logger.info("start");
+      // 不报错即可，auto 模式下可能是 plain 或 tui
+      expect(consoleSpy.log).toHaveBeenCalled();
+    });
+  });
+
+  describe("child", () => {
+    it("子 Logger 前缀包含父命名空间", () => {
+      const logger = new Logger({ name: "build", mode: "plain" });
+      const child = logger.child("compile");
+      child.info("processing");
+      const output = consoleSpy.log.mock.calls[0][0] as string;
+      expect(output).toContain("[build:compile]");
+    });
+  });
+
+  describe("Spinner (plain 模式)", () => {
+    it("spin 输出开始消息", () => {
+      const logger = new Logger({ name: "test", mode: "plain" });
+      const spinner = logger.spin("loading");
+      expect(consoleSpy.log).toHaveBeenCalledTimes(1);
+      const output = consoleSpy.log.mock.calls[0][0] as string;
+      expect(output).toContain("loading");
+      spinner.succeed("loaded");
+      expect(consoleSpy.log).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe("ProgressBar (plain 模式)", () => {
+    it("progress 输出进度信息", () => {
+      const logger = new Logger({ name: "test", mode: "plain" });
+      const bar = logger.progress({ total: 10, label: "files" });
+      expect(consoleSpy.log).toHaveBeenCalledTimes(1);
+      bar.update(5);
+      expect(consoleSpy.log).toHaveBeenCalledTimes(2);
+      const output = consoleSpy.log.mock.calls[1][0] as string;
+      expect(output).toContain("50%");
+      bar.finish();
+      expect(consoleSpy.log).toHaveBeenCalledTimes(3);
+    });
+  });
+
+  describe("Tasks (plain 模式)", () => {
+    it("顺序执行任务并输出状态", async () => {
+      const logger = new Logger({ name: "test", mode: "plain" });
+      const results = await logger.tasks([
+        { title: "步骤1", task: async () => "a" as never },
+        { title: "步骤2", task: async () => "b" as never },
+      ]);
+      expect(results).toHaveLength(2);
+      const allOutput = consoleSpy.log.mock.calls.map((c: unknown[]) => c[0]).join("\n");
+      expect(allOutput).toContain("步骤1");
+      expect(allOutput).toContain("步骤2");
+    });
+
+    it("任务失败时抛出错误", async () => {
+      const logger = new Logger({ name: "test", mode: "plain" });
+      await expect(
+        logger.tasks([
+          {
+            title: "会失败",
+            task: async () => {
+              throw new Error("boom");
+            },
+          },
+        ]),
+      ).rejects.toThrow("boom");
+    });
+
+    it("enabled=false 的任务被跳过", async () => {
+      const logger = new Logger({ name: "test", mode: "plain" });
+      const taskFn = vi.fn();
+      await logger.tasks([{ title: "跳过", task: taskFn, enabled: false }]);
+      expect(taskFn).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/shared/logger/logger.ts

@@ -0,0 +1,175 @@
+import type {
+  LoggerOptions,
+  LogLevel,
+  RenderMode,
+  LogRenderer,
+  Spinner,
+  ProgressBar,
+  ProgressBarOptions,
+  TaskItem,
+} from "./logger.interface";
+import { LOG_LEVEL_PRIORITY } from "./logger.interface";
+import { PlainRenderer } from "./renderers/plain.renderer";
+
+/** 检测是否为 TUI 环境 */
+const detectMode = (): RenderMode => {
+  if (process.env.CI || !process.stdout.isTTY) return "plain";
+  return "tui";
+};
+
+/** TUI 渲染器缓存（延迟加载，避免 ESM 兼容问题） */
+let tuiRendererCache: LogRenderer | null = null;
+
+/** 延迟加载 TUI 渲染器（chalk/ora/log-update 均为纯 ESM 包） */
+const loadTuiRenderer = async (): Promise<LogRenderer> => {
+  if (tuiRendererCache) return tuiRendererCache;
+  const { TuiRenderer } = await import("./renderers/tui.renderer");
+  tuiRendererCache = new TuiRenderer();
+  return tuiRendererCache;
+};
+
+/** 解析渲染模式，返回实际模式标识 */
+const resolveMode = (mode: RenderMode): "plain" | "tui" => {
+  if (mode === "auto") return detectMode() === "tui" ? "tui" : "plain";
+  return mode;
+};
+
+/**
+ * 全局日志工具类
+ *
+ * 每个子命令创建独立实例，支持 plain / tui 两种输出模式。
+ * TUI 模式提供 Spinner、进度条、任务列表等富交互能力，
+ * plain 模式下自动降级为普通文本输出。
+ *
+ * @example
+ * ```typescript
+ * const logger = new Logger("build");
+ * logger.info("开始构建");
+ * const s = logger.spin("编译中...");
+ * s.succeed("编译完成");
+ * ```
+ */
+export class Logger {
+  private readonly name: string;
+  private readonly level: LogLevel;
+  private readonly resolvedMode: "plain" | "tui";
+  private readonly plainRenderer: PlainRenderer;
+  private tuiRenderer: LogRenderer | null = null;
+
+  constructor(options: LoggerOptions | string) {
+    const opts = typeof options === "string" ? { name: options } : options;
+    this.name = opts.name;
+    this.level = opts.level ?? "info";
+    this.resolvedMode = resolveMode(opts.mode ?? "auto");
+    this.plainRenderer = new PlainRenderer();
+  }
+
+  /** 格式化前缀 */
+  private get prefix(): string {
+    return `[${this.name}]`;
+  }
+
+  /** 获取当前渲染器（TUI 未加载时降级为 plain） */
+  private get renderer(): LogRenderer {
+    if (this.resolvedMode === "tui" && this.tuiRenderer) return this.tuiRenderer;
+    return this.plainRenderer;
+  }
+
+  /**
+   * 初始化 TUI 渲染器（异步）
+   * 在使用 TUI 特有功能前调用，确保渲染器已加载
+   */
+  async init(): Promise<void> {
+    if (this.resolvedMode === "tui" && !this.tuiRenderer) {
+      this.tuiRenderer = await loadTuiRenderer();
+    }
+  }
+
+  /** 判断是否应输出指定级别的日志 */
+  private shouldLog(level: LogLevel): boolean {
+    return LOG_LEVEL_PRIORITY[level] <= LOG_LEVEL_PRIORITY[this.level];
+  }
+
+  /** 输出 info 级别日志 */
+  info(message: string): void {
+    if (this.shouldLog("info")) {
+      this.renderer.info(this.prefix, message);
+    }
+  }
+
+  /** 输出 success 级别日志 */
+  success(message: string): void {
+    if (this.shouldLog("info")) {
+      this.renderer.success(this.prefix, message);
+    }
+  }
+
+  /** 输出 warn 级别日志 */
+  warn(message: string): void {
+    if (this.shouldLog("info")) {
+      this.renderer.warn(this.prefix, message);
+    }
+  }
+
+  /** 输出 error 级别日志 */
+  error(message: string): void {
+    if (this.shouldLog("info")) {
+      this.renderer.error(this.prefix, message);
+    }
+  }
+
+  /** 输出 verbose 级别日志（level >= verbose 才输出） */
+  verbose(message: string): void {
+    if (this.shouldLog("verbose")) {
+      this.renderer.verbose(this.prefix, message);
+    }
+  }
+
+  /** 输出 debug 级别日志（level >= debug 才输出） */
+  debug(message: string): void {
+    if (this.shouldLog("debug")) {
+      this.renderer.debug(this.prefix, message);
+    }
+  }
+
+  /**
+   * 创建 Spinner
+   * TUI 模式下显示动画 spinner，plain 模式下降级为普通日志
+   */
+  spin(message: string): Spinner {
+    return this.renderer.createSpinner(this.prefix, message);
+  }
+
+  /**
+   * 创建进度条
+   * TUI 模式下显示实时进度条，plain 模式下降级为百分比日志
+   */
+  progress(options: ProgressBarOptions): ProgressBar {
+    return this.renderer.createProgressBar(this.prefix, options);
+  }
+
+  /**
+   * 执行任务列表
+   * TUI 模式下多行实时更新，plain 模式下顺序输出
+   */
+  async tasks<T>(items: TaskItem<T>[]): Promise<T[]> {
+    return this.renderer.runTasks<T>(this.prefix, items);
+  }
+
+  /** 输出表格 */
+  table(data: Record<string, unknown>[]): void {
+    this.renderer.table(this.prefix, data);
+  }
+
+  /**
+   * 创建子 Logger
+   * 命名空间自动拼接，如 "build" → "build:compile"
+   */
+  child(name: string): Logger {
+    return new Logger({
+      name: `${this.name}:${name}`,
+      level: this.level,
+      mode: this.resolvedMode,
+    });
+  }
+}

package/src/shared/logger/renderers/plain.renderer.ts

@@ -0,0 +1,116 @@
+import type {
+  LogRenderer,
+  Spinner,
+  ProgressBar,
+  ProgressBarOptions,
+  TaskItem,
+  TaskControl,
+} from "../logger.interface";
+
+/** 时间戳格式化 */
+const timestamp = (): string => {
+  const now = new Date();
+  return `${now.toLocaleTimeString()}`;
+};
+
+/** plain 模式渲染器：纯文本输出，适合 CI / 管道 */
+export class PlainRenderer implements LogRenderer {
+  info(prefix: string, message: string): void {
+    console.log(`${timestamp()} ${prefix} ${message}`);
+  }
+
+  success(prefix: string, message: string): void {
+    console.log(`${timestamp()} ${prefix} ✅ ${message}`);
+  }
+
+  warn(prefix: string, message: string): void {
+    console.warn(`${timestamp()} ${prefix} ⚠️ ${message}`);
+  }
+
+  error(prefix: string, message: string): void {
+    console.error(`${timestamp()} ${prefix} ❌ ${message}`);
+  }
+
+  debug(prefix: string, message: string): void {
+    console.log(`${timestamp()} ${prefix} [DEBUG] ${message}`);
+  }
+
+  verbose(prefix: string, message: string): void {
+    console.log(`${timestamp()} ${prefix} ${message}`);
+  }
+
+  createSpinner(prefix: string, message: string): Spinner {
+    console.log(`${timestamp()} ${prefix} ⏳ ${message}`);
+    return {
+      update: (msg: string) => {
+        console.log(`${timestamp()} ${prefix} ⏳ ${msg}`);
+      },
+      succeed: (msg?: string) => {
+        console.log(`${timestamp()} ${prefix} ✅ ${msg ?? message}`);
+      },
+      fail: (msg?: string) => {
+        console.error(`${timestamp()} ${prefix} ❌ ${msg ?? message}`);
+      },
+      stop: () => {},
+    };
+  }
+
+  createProgressBar(prefix: string, options: ProgressBarOptions): ProgressBar {
+    const { total, label = "" } = options;
+    const tag = label ? `${label} ` : "";
+    console.log(`${timestamp()} ${prefix} ${tag}0/${total}`);
+    return {
+      update: (current: number, msg?: string) => {
+        const pct = Math.round((current / total) * 100);
+        const suffix = msg ? ` ${msg}` : "";
+        console.log(`${timestamp()} ${prefix} ${tag}${current}/${total} (${pct}%)${suffix}`);
+      },
+      finish: (msg?: string) => {
+        const suffix = msg ? ` ${msg}` : "";
+        console.log(`${timestamp()} ${prefix} ✅ ${tag}${total}/${total} (100%)${suffix}`);
+      },
+    };
+  }
+
+  async runTasks<T>(prefix: string, items: TaskItem<T>[]): Promise<T[]> {
+    const results: T[] = [];
+    for (const item of items) {
+      if (item.enabled === false) {
+        console.log(`${timestamp()} ${prefix} ⏭️ [跳过] ${item.title}`);
+        continue;
+      }
+      console.log(`${timestamp()} ${prefix} ▶ ${item.title}`);
+      let skipped = false;
+      let skipReason = "";
+      const control: TaskControl = {
+        update: (msg: string) => {
+          console.log(`${timestamp()} ${prefix}   ${msg}`);
+        },
+        skip: (reason?: string) => {
+          skipped = true;
+          skipReason = reason ?? "";
+        },
+      };
+      try {
+        const ctx = (results.length > 0 ? results[results.length - 1] : undefined) as T;
+        const result = await item.task(ctx, control);
+        if (skipped) {
+          const suffix = skipReason ? `: ${skipReason}` : "";
+          console.log(`${timestamp()} ${prefix} ⏭️ ${item.title}${suffix}`);
+        } else {
+          console.log(`${timestamp()} ${prefix} ✅ ${item.title}`);
+        }
+        results.push(result);
+      } catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.error(`${timestamp()} ${prefix} ❌ ${item.title}: ${errMsg}`);
+        throw err;
+      }
+    }
+    return results;
+  }
+
+  table(_prefix: string, data: Record<string, unknown>[]): void {
+    console.table(data);
+  }
+}