@ai-setting/roy-agent-cli 1.0.0

package/src/commands/debug/span.ts

@@ -0,0 +1,211 @@
+/**
+ * @fileoverview Debug Span Command
+ * 
+ * Command: roy debug span <spanId>
+ * 
+ * 通过 spanId 从 SQLite 中查询详细的 span 信息
+ */
+
+import * as path from "path";
+import * as os from "os";
+import type { CommandModule } from "yargs";
+import { SQLiteSpanStorage } from "@ai-setting/roy-agent-core";
+import type { Span } from "@ai-setting/roy-agent-core";
+
+interface SpanOptions {
+  spanId?: string;
+  db?: string;
+}
+
+export const SpanCommand: CommandModule<object, SpanOptions> = {
+  command: "span",
+  describe: "通过 spanId 查询详细的 span 信息",
+
+  builder: (yargs) =>
+    yargs
+      .positional("spanId", {
+        type: "string",
+        describe: "Span ID",
+        demandOption: true,
+      })
+      .option("db", {
+        type: "string",
+        describe: "SQLite 数据库路径（可选，默认使用配置路径）",
+      }),
+
+  async handler(args) {
+    const spanId = args._[2] as string || args.spanId;
+    
+    if (!spanId) {
+      console.error("Error: spanId is required");
+      console.error("Usage: roy debug span <spanId>");
+      process.exit(1);
+    }
+    
+    // 获取数据库路径
+    const dbPath = args.db || getDefaultSpanDbPath();
+    
+    // 创建存储实例并读取数据
+    const storage = new SQLiteSpanStorage(dbPath);
+    await storage.initialize();
+    
+    try {
+      // 查询 span
+      const span = storage.findBySpanId(spanId);
+      
+      if (!span) {
+        console.log(`Span ${spanId} not found.`);
+        return;
+      }
+
+      // 格式化输出详细信息
+      const output = formatSpanDetail(span);
+      console.log(output);
+    } finally {
+      storage.close();
+    }
+  },
+};
+
+/**
+ * 获取默认的 span 数据库路径
+ */
+export function getDefaultSpanDbPath(): string {
+  // 支持环境变量覆盖
+  if (process.env.LOG_TRACE_TRACING_DB_PATH) {
+    return process.env.LOG_TRACE_TRACING_DB_PATH;
+  }
+  
+  // 使用 XDG 标准路径
+  const home = os.homedir();
+  const dataHome = process.env.XDG_DATA_HOME || path.join(home, ".local", "share");
+  return path.join(dataHome, "roy-agent", "traces.db");
+}
+
+/**
+ * 安全序列化对象，处理循环引用和其他异常
+ */
+function safeStringify(obj: unknown, indent: number = 2): string {
+  // 处理非对象类型
+  if (obj === null) return "null";
+  if (obj === undefined) return "undefined";
+  if (typeof obj !== "object") return String(obj);
+  
+  // 如果已经是字符串，可能是已经 stringify 过的
+  if (typeof obj === "string") {
+    // 尝试检测是否是 JSON 字符串
+    try {
+      const parsed = JSON.parse(obj);
+      return safeStringify(parsed, indent);
+    } catch {
+      return obj;
+    }
+  }
+  
+  // 处理数组
+  if (Array.isArray(obj)) {
+    try {
+      const items = obj.map(item => safeStringify(item, 0));
+      return `[${items.join(", ")}]`;
+    } catch {
+      return "[Array - cannot stringify]";
+    }
+  }
+  
+  // 使用 WeakSet 检测循环引用
+  const seen = new WeakSet<object>();
+  
+  const stringify = (value: unknown, depth: number): string => {
+    if (value === null) return "null";
+    if (value === undefined) return "undefined";
+    if (typeof value !== "object") return JSON.stringify(value);
+    
+    if (typeof value === "string") {
+      // 可能是已经 stringify 过的 JSON 字符串
+      try {
+        const parsed = JSON.parse(value);
+        return JSON.stringify(parsed);
+      } catch {
+        return JSON.stringify(value);
+      }
+    }
+    
+    if (Array.isArray(value)) {
+      if (seen.has(value)) return '"[Circular]"';
+      seen.add(value);
+      const items = value.map(item => stringify(item, depth + 1));
+      return `[${items.join(", ")}]`;
+    }
+    
+    if (seen.has(value)) return '"[Circular]"';
+    seen.add(value);
+    
+    const entries = Object.entries(value as Record<string, unknown>);
+    const props = entries.map(([k, v]) => `"${k}": ${stringify(v, depth + 1)}`);
+    return `{${props.join(", ")}}`;
+  };
+  
+  try {
+    return stringify(obj, 0);
+  } catch (e) {
+    return `[Object - cannot stringify: ${e instanceof Error ? e.message : String(e)}]`;
+  }
+}
+
+/**
+ * 格式化 span 为详细输出
+ */
+export function formatSpanDetail(span: Span): string {
+  const lines: string[] = [];
+  
+  // 基本信息
+  lines.push(`Span ID:    ${span.spanId}`);
+  lines.push(`Trace ID:   ${span.traceId}`);
+  lines.push(`Name:       ${span.name}`);
+  lines.push(`Kind:       ${span.kind}`);
+  lines.push(`Status:     ${span.status}`);
+  
+  // 时间信息
+  const duration = span.endTime 
+    ? `${span.endTime - span.startTime}ms` 
+    : "(running)";
+  lines.push(`Duration:   ${duration}`);
+  lines.push(`Start:      ${span.startTime} (${new Date(span.startTime).toISOString()})`);
+  if (span.endTime) {
+    lines.push(`End:        ${span.endTime} (${new Date(span.endTime).toISOString()})`);
+  }
+  
+  // 父子关系
+  if (span.parentSpanId) {
+    lines.push(`Parent:     ${span.parentSpanId}`);
+  }
+  
+  // 错误信息
+  if (span.error) {
+    lines.push(`Error:      ${span.error}`);
+  }
+  
+  // 属性
+  if (span.attributes && Object.keys(span.attributes).length > 0) {
+    lines.push("");
+    lines.push("Attributes:");
+    for (const [key, value] of Object.entries(span.attributes)) {
+      lines.push(`  ${key}: ${safeStringify(value, 0)}`);
+    }
+  }
+  
+  // 结果
+  if (span.result !== undefined) {
+    lines.push("");
+    lines.push("Result:");
+    // 如果是字符串，尝试解析为 JSON 显示；如果是已损坏的数据，显示提示
+    const resultStr = typeof span.result === "string"
+      ? (span.result.includes("[Object with circular reference") 
+          ? "[Circular reference - original data contained circular structures]" 
+          : span.result)
+      : safeStringify(span.result);
+    lines.push(`  ${resultStr}`);
+  }
+  
+  return lines.join("\n");
+}

package/src/commands/debug/trace.test.ts

@@ -0,0 +1,254 @@
+/**
+ * @fileoverview Debug Trace Command - TDD Tests
+ * 
+ * TDD 开发流程:
+ * 1. RED - 编写失败的测试
+ * 2. GREEN - 编写最小代码让测试通过
+ * 3. REFACTOR - 重构
+ * 
+ * 测试目标: debug trace <traceId>
+ * 功能: 以 tree 方式展示 traceId 的 spans
+ */
+
+import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import type { Span } from "@ai-setting/roy-agent-core";
+import { SpanKind, SpanStatus } from "@ai-setting/roy-agent-core";
+
+describe("Debug Trace Command - TDD", () => {
+  describe("RED: getDefaultSpanDbPath()", () => {
+    test("should return path in XDG_DATA_HOME/roy-agent/traces.db by default", async () => {
+      const { getDefaultSpanDbPath } = await import("./trace");
+      
+      // Clear environment variables
+      delete process.env.LOG_TRACE_TRACING_DB_PATH;
+      
+      const dbPath = getDefaultSpanDbPath();
+      
+      expect(dbPath).toContain("roy-agent");
+      expect(dbPath).toContain("traces.db");
+    });
+
+    test("should use LOG_TRACE_TRACING_DB_PATH environment variable when set", async () => {
+      const { getDefaultSpanDbPath } = await import("./trace");
+      
+      const customPath = "/custom/path/my-traces.db";
+      process.env.LOG_TRACE_TRACING_DB_PATH = customPath;
+      
+      const dbPath = getDefaultSpanDbPath();
+      
+      expect(dbPath).toBe(customPath);
+      
+      delete process.env.LOG_TRACE_TRACING_DB_PATH;
+    });
+  });
+
+  describe("RED: formatSpanTree()", () => {
+    test("should format single root span", async () => {
+      const { formatSpanTree } = await import("./trace");
+      
+      const spans: Span[] = [{
+        traceId: "trace_1",
+        spanId: "span_1",
+        name: "root",
+        kind: SpanKind.INTERNAL,
+        status: SpanStatus.OK,
+        startTime: 1000,
+        endTime: 2000,
+        attributes: {},
+        children: [],
+      }];
+
+      const output = formatSpanTree(spans);
+      
+      expect(output).toContain("root");
+      expect(output).toContain("1000ms"); // duration
+    });
+
+    test("should format span with children showing indentation", async () => {
+      const { formatSpanTree } = await import("./trace");
+      
+      // spans 是已经构建好的树结构（根节点数组，每个节点有 children）
+      const spans: Span[] = [
+        {
+          traceId: "trace_1",
+          spanId: "span_1",
+          name: "root",
+          kind: SpanKind.INTERNAL,
+          status: SpanStatus.OK,
+          startTime: 1000,
+          endTime: 2000,
+          attributes: {},
+          children: [
+            {
+              traceId: "trace_1",
+              spanId: "span_2",
+              parentSpanId: "span_1",
+              name: "child",
+              kind: SpanKind.INTERNAL,
+              status: SpanStatus.OK,
+              startTime: 1200,
+              endTime: 1500,
+              attributes: {},
+              children: [],
+            },
+          ],
+        },
+      ];
+
+      const output = formatSpanTree(spans);
+      
+      expect(output).toContain("root");
+      expect(output).toContain("child");
+      // Should show child under parent with indentation indicator
+      expect(output).toContain("└──") || expect(output).toContain("child");
+    });
+
+    test("should calculate duration correctly", async () => {
+      const { formatSpanTree } = await import("./trace");
+      
+      const spans: Span[] = [{
+        traceId: "trace_1",
+        spanId: "span_1",
+        name: "operation",
+        kind: SpanKind.INTERNAL,
+        status: SpanStatus.OK,
+        startTime: 1000,
+        endTime: 2500, // 1500ms duration
+        attributes: {},
+        children: [],
+      }];
+
+      const output = formatSpanTree(spans);
+      
+      expect(output).toContain("1500ms");
+    });
+
+    test("should handle span without endTime (running)", async () => {
+      const { formatSpanTree } = await import("./trace");
+      
+      const spans: Span[] = [{
+        traceId: "trace_1",
+        spanId: "span_1",
+        name: "running-operation",
+        kind: SpanKind.INTERNAL,
+        status: SpanStatus.OK,
+        startTime: 1000,
+        endTime: undefined,
+        attributes: {},
+        children: [],
+      }];
+
+      const output = formatSpanTree(spans);
+      
+      expect(output).toContain("running-operation");
+      expect(output).toContain("(running)");
+    });
+
+    test("should show error indicator for failed spans", async () => {
+      const { formatSpanTree } = await import("./trace");
+      
+      const spans: Span[] = [{
+        traceId: "trace_1",
+        spanId: "span_1",
+        name: "failed-operation",
+        kind: SpanKind.INTERNAL,
+        status: SpanStatus.ERROR,
+        startTime: 1000,
+        endTime: 2000,
+        attributes: {},
+        error: "Something went wrong",
+        children: [],
+      }];
+
+      const output = formatSpanTree(spans);
+      
+      expect(output).toContain("failed-operation");
+      expect(output).toContain("Something went wrong");
+    });
+
+    test("should handle empty spans array", async () => {
+      const { formatSpanTree } = await import("./trace");
+      
+      const output = formatSpanTree([]);
+      
+      expect(output).toContain("(empty)");
+    });
+
+    test("should show spanId in output", async () => {
+      const { formatSpanTree } = await import("./trace");
+      
+      const spans: Span[] = [{
+        traceId: "trace_1",
+        spanId: "span_1",
+        name: "operation",
+        kind: SpanKind.INTERNAL,
+        status: SpanStatus.OK,
+        startTime: 1000,
+        endTime: 2000,
+        attributes: { "http.method": "GET", "http.url": "/api/test" },
+        children: [],
+      }];
+
+      const output = formatSpanTree(spans);
+      
+      // Should show spanId
+      expect(output).toContain("[spanId:span_1]");
+      // Should NOT show attributes (simplified output)
+      expect(output).not.toContain("http.method");
+      expect(output).not.toContain("GET");
+    });
+  });
+
+  describe("GREEN: TraceCommand structure", () => {
+    test("should have correct command name 'trace'", async () => {
+      const { TraceCommand } = await import("./index");
+      
+      expect(TraceCommand.command).toBe("trace");
+    });
+
+    test("should have describe text mentioning tree visualization", async () => {
+      const { TraceCommand } = await import("./index");
+      
+      expect(TraceCommand.describe).toBeDefined();
+      expect(typeof TraceCommand.describe).toBe("string");
+    });
+
+    test("should have builder that adds traceId positional argument", async () => {
+      const { TraceCommand } = await import("./index");
+      
+      let positionalConfig: any = null;
+      const mockYargs = {
+        positional: (name: string, config: any) => {
+          if (name === "traceId") {
+            positionalConfig = config;
+          }
+          return mockYargs;
+        },
+        option: () => mockYargs,
+      };
+      
+      TraceCommand.builder(mockYargs as any);
+      
+      expect(positionalConfig).toBeDefined();
+      expect(positionalConfig.type).toBe("string");
+    });
+
+    test("should have --db option for custom db path", async () => {
+      const { TraceCommand } = await import("./index");
+      
+      let capturedOptions: Record<string, any> = {};
+      const mockYargs = {
+        option: (name: string, config: any) => {
+          capturedOptions[name] = config;
+          return mockYargs;
+        },
+        positional: () => mockYargs,
+      };
+      
+      TraceCommand.builder(mockYargs as any);
+      
+      expect(capturedOptions.db).toBeDefined();
+      expect(capturedOptions.db.type).toBe("string");
+    });
+  });
+});

package/src/commands/debug/trace.ts

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview Debug Trace Command
+ * 
+ * Command: roy debug trace <traceId>
+ * 
+ * 以 tree 方式展示 traceId 的 spans
+ */
+
+import * as path from "path";
+import * as os from "os";
+import type { CommandModule } from "yargs";
+import { SQLiteSpanStorage } from "@ai-setting/roy-agent-core";
+import type { Span } from "@ai-setting/roy-agent-core";
+
+interface TraceOptions {
+  traceId?: string;
+  db?: string;
+}
+
+export const TraceCommand: CommandModule<object, TraceOptions> = {
+  command: "trace",
+  describe: "以 tree 方式查看 trace 的 spans",
+
+  builder: (yargs) =>
+    yargs
+      .positional("traceId", {
+        type: "string",
+        describe: "Trace ID",
+        demandOption: true,
+      })
+      .option("db", {
+        type: "string",
+        describe: "SQLite 数据库路径（可选，默认使用配置路径）",
+      }),
+
+  async handler(args) {
+    const traceId = args._[2] as string || args.traceId;
+    
+    if (!traceId) {
+      console.error("Error: traceId is required");
+      console.error("Usage: roy debug trace <traceId>");
+      process.exit(1);
+    }
+    
+    // 获取数据库路径
+    const dbPath = args.db || getDefaultSpanDbPath();
+    
+    // 创建存储实例并读取数据
+    const storage = new SQLiteSpanStorage(dbPath);
+    await storage.initialize();
+    
+    try {
+      // 查询 spans
+      const spans = storage.findByTraceId(traceId);
+      
+      if (spans.length === 0) {
+        console.log(`Trace ${traceId} not found.`);
+        return;
+      }
+
+      // 格式化输出为 tree
+      // 注意：spans 已经是 buildTree() 返回的根节点数组，每个节点有 children
+      const treeOutput = formatSpanTree(spans);
+      
+      // 分段输出到 stderr，避免被 log-trace 的 maxOutput 截断
+      const chunkSize = 4000;
+      for (let i = 0; i < treeOutput.length; i += chunkSize) {
+        console.error(treeOutput.substring(i, i + chunkSize));
+      }
+    } finally {
+      storage.close();
+    }
+  },
+};
+
+/**
+ * 获取默认的 span 数据库路径
+ */
+export function getDefaultSpanDbPath(): string {
+  // 支持环境变量覆盖
+  if (process.env.LOG_TRACE_TRACING_DB_PATH) {
+    return process.env.LOG_TRACE_TRACING_DB_PATH;
+  }
+  
+  // 使用 XDG 标准路径
+  const home = os.homedir();
+  const dataHome = process.env.XDG_DATA_HOME || path.join(home, ".local", "share");
+  return path.join(dataHome, "roy-agent", "traces.db");
+}
+
+/**
+ * 格式化 spans 为 tree 视图
+ * 
+ * spans 是已经构建好的树结构（根节点数组，每个节点有 children）
+ * 直接遍历输出即可
+ */
+export function formatSpanTree(spans: Span[]): string {
+  if (spans.length === 0) {
+    return "(empty)";
+  }
+
+  // spans 已经是根节点数组，直接格式化
+  const lines: string[] = [];
+  
+  for (const root of spans) {
+    formatSpanNode(root, 0, lines);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * 递归格式化单个 span
+ * 
+ * 简化输出：只显示 name、duration、error、spanId
+ */
+function formatSpanNode(span: Span, depth: number, lines: string[]): void {
+  const indent = "  ".repeat(depth);
+  const connector = depth === 0 ? "" : "└── ";
+  
+  // 计算耗时
+  const duration = span.endTime 
+    ? `${span.endTime - span.startTime}ms` 
+    : "(running)";
+  
+  // 构建错误信息
+  const errorInfo = span.error 
+    ? ` ⚠ ${span.error}` 
+    : "";
+
+  // 添加 spanId 显示
+  const spanIdInfo = `[spanId:${span.spanId}]`;
+
+  lines.push(`${indent}${connector}${span.name} (${duration})${errorInfo} ${spanIdInfo}`);
+
+  // 递归处理子 span
+  for (const child of span.children || []) {
+    formatSpanNode(child, depth + 1, lines);
+  }
+}