@ai-setting/roy-agent-cli 1.3.15 → 1.3.16

package/dist/core/src/env/log-trace/logger.js

@@ -0,0 +1,445 @@
+/**
+ * @fileoverview Logger - 统一日志系统
+ *
+ * 遵循 XDG Base Directory Specification:
+ * - 日志存储在 XDG_DATA_HOME/roy-agent/logs/ (默认 ~/.local/share/roy-agent/logs/)
+ * 无需配置，自动创建目录
+ *
+ * 支持 traceId 追踪：通过 trace-context 模块自动注入
+ *
+ * 配置优先级（从高到低）：
+ * 1. ConfigComponent (log-trace.logging.level, log-trace.logging.dir)
+ * 2. 环境变量 (LOG_LEVEL, LOG_DIR)
+ * 3. setLogDirOverride() 手动设置
+ * 4. XDG 默认路径
+ */
+import { appendFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import { getTracerProvider } from "./opentelemetry/tracer-provider.js";
+/**
+ * 简化 Bun file: 协议的编码路径
+ * 例如: packages+core/node_modules/.bun/@roy-agent+core@file+packages+core/node_modules/@roy-agent/core/src/env/agent/agent-component.ts
+ * 转换为: packages/core/src/env/agent/agent-component.ts
+ */
+export function simplifyFilePath(fullPath) {
+    let path = fullPath.replace(/\\/g, "/");
+    // 处理 Bun 虚拟文件系统路径
+    // 例如: /$bunfs/root/cli/src/bin/roy.js -> cli/src/bin/roy.js
+    const bunfsMatch = path.match(/\/\$bunfs\/root\/(.+)$/);
+    if (bunfsMatch) {
+        // 从虚拟路径中提取相对路径
+        const virtualPath = bunfsMatch[1];
+        // 查找 packages/ 开头的路径
+        const packagesMatch = virtualPath.match(/(packages\/[^/]+\/src\/[^/]+\/.+)$/);
+        if (packagesMatch) {
+            return packagesMatch[1];
+        }
+        // 返回去掉 bunfs 前缀的路径
+        return virtualPath;
+    }
+    // 尝试匹配并简化 @roy-agent/core 的路径
+    const fileProtocolMatch = path.match(/@roy-agent\+core@file\+([^/]+)\/node_modules\/@roy-agent\/core\/(.+)$/);
+    if (fileProtocolMatch) {
+        const rootPkg = fileProtocolMatch[1].replace(/\+/g, "/");
+        const remaining = fileProtocolMatch[2];
+        const prefix = rootPkg;
+        const suffix = remaining.startsWith("src/") ? remaining : `src/${remaining}`;
+        return `${prefix}/${suffix}`;
+    }
+    // 回退：查找 packages/ 开头的路径
+    const packagesRootMatch = path.match(/(packages\/[^/]+\/src\/[^/]+\/.+)$/);
+    if (packagesRootMatch) {
+        return packagesRootMatch[1];
+    }
+    // 回退到简单查找
+    const rootMarkers = ["packages/core/src", "packages/core", "packages"];
+    for (const marker of rootMarkers) {
+        const idx = path.indexOf(marker);
+        if (idx !== -1) {
+            return path.substring(idx);
+        }
+    }
+    return path;
+}
+// ============================================================================
+// Default Paths (based on XDG_DATA_HOME)
+// ============================================================================
+/**
+ * 获取默认日志目录（基于 XDG 标准）
+ * 存储在 XDG_DATA_HOME/roy-agent/logs/
+ */
+function getDefaultLogDir() {
+    const home = process.env.HOME || process.env.USERPROFILE || "/tmp";
+    // 尝试使用 xdg-basedir
+    try {
+        const xdg = require("xdg-basedir");
+        if (xdg.xdgData) {
+            return join(xdg.xdgData, "roy-agent", "logs");
+        }
+    }
+    catch { }
+    // 回退到 ~/.local/share/roy-agent/logs
+    return join(home, ".local", "share", "roy-agent", "logs");
+}
+// 导入 ConfigComponent 类型（延迟导入避免循环依赖）
+let ConfigComponent = null;
+function getConfigComponentClass() {
+    if (!ConfigComponent) {
+        try {
+            ConfigComponent = require("../config/config-component").ConfigComponent;
+        }
+        catch {
+            return null;
+        }
+    }
+    return ConfigComponent;
+}
+let configComponentInstance = null;
+// ============================================================================
+// 安静模式
+// ============================================================================
+/**
+ * 安静模式：启用后日志只写入文件，不输出到 stdout/stderr
+ */
+let quietMode = false;
+export function isQuietMode() {
+    return quietMode;
+}
+export function setQuietMode(enabled) {
+    quietMode = enabled;
+}
+// ============================================================================
+// ConfigComponent 配置
+// ============================================================================
+/**
+ * 设置 ConfigComponent 实例（用于实时配置读取）
+ */
+export function setConfigComponent(component) {
+    configComponentInstance = component;
+}
+/**
+ * 获取日志级别（支持热更新）
+ */
+export function getLogLevel() {
+    // 1. 优先从 ConfigComponent 获取
+    if (configComponentInstance) {
+        const level = configComponentInstance.get("log_trace.logging.level");
+        if (level && ["debug", "info", "warn", "error"].includes(level)) {
+            return level;
+        }
+    }
+    // 2. 环境变量
+    const envLevel = process.env.LOG_LEVEL;
+    if (envLevel && ["debug", "info", "warn", "error"].includes(envLevel)) {
+        return envLevel;
+    }
+    // 3. 默认值
+    return "info";
+}
+/**
+ * 获取指定类别的日志级别
+ *
+ * 支持按类别配置日志级别，配置路径：log-trace.logging.levels.<category>
+ *
+ * @param category 日志类别（如 "llm", "agent", "tool"）
+ * @returns 该类别的日志级别，如果未配置则返回全局级别
+ */
+export function getCategoryLogLevel(category) {
+    // 1. 从 ConfigComponent 获取按类别日志级别
+    if (configComponentInstance) {
+        // 支持嵌套配置：log-trace.logging.levels.llm
+        const levels = configComponentInstance.get("log_trace.logging.levels");
+        if (levels && typeof levels === "object") {
+            const categoryLevel = levels[category];
+            if (categoryLevel && ["debug", "info", "warn", "error"].includes(categoryLevel)) {
+                return categoryLevel;
+            }
+        }
+        // 也支持直接配置：log-trace.logging.levels.llm = "debug"
+        const directLevel = configComponentInstance.get(`log_trace.logging.levels.${category}`);
+        if (directLevel && ["debug", "info", "warn", "error"].includes(directLevel)) {
+            return directLevel;
+        }
+    }
+    // 2. 环境变量（使用前缀，如 LOG_LEVEL_LLM）
+    const envKey = `LOG_LEVEL_${category.toUpperCase().replace(/:/g, "_")}`;
+    const envLevel = process.env[envKey];
+    if (envLevel && ["debug", "info", "warn", "error"].includes(envLevel)) {
+        return envLevel;
+    }
+    // 3. 返回全局级别作为默认值
+    return getLogLevel();
+}
+// ============================================================================
+// 日志目录
+// ============================================================================
+/**
+ * 判断路径是否为绝对路径
+ * 支持：Unix (/开头)、Windows (盘符开头)、~ (home目录)
+ */
+function isAbsolutePath(path) {
+    // Unix 绝对路径
+    if (path.startsWith("/")) {
+        return true;
+    }
+    // Windows 盘符路径 (如 C:\, D:\)
+    if (/^[a-zA-Z]:[/\\]/.test(path)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * 解析路径中的 ~ 为 home 目录
+ */
+function expandHomeDir(path) {
+    if (path.startsWith("~")) {
+        const home = process.env.HOME || process.env.USERPROFILE || "/tmp";
+        return join(home, path.slice(1));
+    }
+    return path;
+}
+/**
+ * 获取日志文件名
+ * 实时从 ConfigComponent 读取（支持 env/file/memory 多 source）
+ */
+export function getLogFile() {
+    if (configComponentInstance) {
+        const file = configComponentInstance.get("log_trace.logging.file");
+        if (file) {
+            return file;
+        }
+    }
+    return "app.log";
+}
+export function getLogDir() {
+    if (configComponentInstance) {
+        const dir = configComponentInstance.get("log_trace.logging.dir");
+        if (dir) {
+            return dir;
+        }
+    }
+    return getDefaultLogDir();
+}
+/**
+ * 获取日志输出最大长度配置
+ * 实时从 ConfigComponent 读取
+ *
+ * @returns 配置的值（0 表示不限制），如果未配置则返回 undefined
+ */
+export function getMaxOutput() {
+    if (configComponentInstance) {
+        const maxOutput = configComponentInstance.get("log-trace.logging.maxOutput");
+        if (typeof maxOutput === "number") {
+            return maxOutput;
+        }
+    }
+    return undefined; // 未配置
+}
+// 日志目录覆盖（手动设置，优先级最高）
+let logDirOverride;
+export function setLogDirOverride(dir) {
+    logDirOverride = dir;
+}
+export function getLogDirOverride() {
+    return logDirOverride;
+}
+// 修改 getLogDir 使用 override
+const originalGetLogDir = getLogDir;
+// getLogDir 保持不变，override 由外部使用
+// ============================================================================
+// Logger 实现
+// ============================================================================
+const levelPriority = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+const levelEnvMap = {
+    "debug": "debug",
+    "info": "info",
+    "warn": "warn",
+    "error": "error",
+};
+function getEffectiveLevel(configured) {
+    // 优先级：构造函数配置 > 环境变量 > 默认 info
+    if (configured)
+        return configured;
+    const envLevel = process.env.LOG_LEVEL;
+    return levelEnvMap[envLevel || ""] || "info";
+}
+class Logger {
+    prefix;
+    constructor(prefix) {
+        this.prefix = prefix;
+    }
+    shouldLog(level) {
+        // 获取该类别的日志级别（支持按类别配置）
+        const categoryLevel = getCategoryLogLevel(this.prefix);
+        return levelPriority[level] >= levelPriority[categoryLevel];
+    }
+    ensureLogDirectory(dir) {
+        if (!existsSync(dir)) {
+            try {
+                mkdirSync(dir, { recursive: true });
+            }
+            catch (err) {
+                console.error("[Logger] Failed to create log directory:", dir, err);
+            }
+        }
+    }
+    getCallerLocation() {
+        const originalLimit = Error.stackTraceLimit;
+        Error.stackTraceLimit = 10;
+        const err = new Error();
+        Error.captureStackTrace(err, this.formatMessage);
+        const stack = err.stack?.split("\n") || [];
+        Error.stackTraceLimit = originalLimit;
+        for (let i = 1; i < stack.length; i++) {
+            const line = stack[i];
+            if (line.includes("at ") && !line.includes("logger.ts") && !line.includes("formatMessage")) {
+                const match = line.match(/at\s+.+\s+\((.+):(\d+):\d+\)/) || line.match(/at\s+(.+):(\d+):\d+/);
+                if (match) {
+                    const filePath = match[1];
+                    const relativePath = this.getRelativePath(filePath);
+                    return {
+                        file: relativePath,
+                        line: parseInt(match[2], 10),
+                    };
+                }
+            }
+        }
+        return null;
+    }
+    getRelativePath(fullPath) {
+        return simplifyFilePath(fullPath);
+    }
+    formatMessage(level, message, data) {
+        const now = new Date();
+        const timestamp = now.toLocaleString("zh-CN", {
+            timeZone: "Asia/Shanghai",
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+            hour: "2-digit",
+            minute: "2-digit",
+            second: "2-digit",
+            hour12: false,
+        }).replace(/\//g, "-") + "." + String(now.getMilliseconds()).padStart(3, "0");
+        const prefix = this.prefix ? `[${this.prefix}]` : "";
+        // 获取 OTel tracer 中的 traceId
+        let traceIdStr = "";
+        try {
+            const provider = getTracerProvider();
+            const tracer = provider.getTracer("roy-tracer");
+            const context = tracer.getCurrentContext();
+            if (context?.traceId) {
+                traceIdStr = `[traceId=${context.traceId}]`;
+            }
+        }
+        catch {
+            // 忽略 tracer 获取失败的情况
+        }
+        // 检查 data 中是否包含 callerLocation（用于 traced 装饰器传递原函数位置）
+        let locationStr = "";
+        if (data && typeof data === "object" && "callerLocation" in data) {
+            const logData = data;
+            locationStr = logData.callerLocation ? ` [${logData.callerLocation}]` : "";
+            // 从 data 中移除 callerLocation，避免它在日志中显示
+            const { callerLocation: _callerLocation, ...rest } = logData;
+            data = Object.keys(rest).length > 0 ? rest : undefined;
+        }
+        else {
+            const location = this.getCallerLocation();
+            if (location) {
+                locationStr = ` [${location.file}:${location.line}]`;
+            }
+        }
+        let formatted = `${timestamp} [${level.toUpperCase()}]${traceIdStr}${locationStr}${prefix} ${message}`;
+        if (data !== undefined) {
+            if (typeof data === "object") {
+                // 使用单行 JSON 格式，避免换行
+                formatted += " " + JSON.stringify(data).replace(/\n/g, "");
+            }
+            else {
+                formatted += " " + String(data);
+            }
+        }
+        // 应用 maxOutput 截断
+        const maxOutput = getMaxOutput();
+        if (maxOutput && maxOutput > 0 && formatted.length > maxOutput) {
+            formatted = formatted.substring(0, maxOutput) + " [TRUNCATED]";
+        }
+        return formatted;
+    }
+    writeToFile(message) {
+        try {
+            // 实时获取配置，支持热更新
+            const dir = getLogDir();
+            const filename = getLogFile();
+            // 解析路径：展开 ~，判断绝对/相对路径
+            const expandedDir = expandHomeDir(dir);
+            const resolvedDir = isAbsolutePath(expandedDir) ? expandedDir : join(process.cwd(), expandedDir);
+            this.ensureLogDirectory(resolvedDir);
+            const logFile = join(resolvedDir, filename);
+            appendFileSync(logFile, message + "\n", "utf-8");
+        }
+        catch (err) {
+            console.error("[Logger] Failed to write to log file:", err);
+        }
+    }
+    log(level, message, data) {
+        if (!this.shouldLog(level))
+            return;
+        // formatMessage 会处理 callerLocation 并将其从 data 中移除
+        // 返回的 formatted 只包含 message 和剩余的 data
+        const formatted = this.formatMessage(level, message, data);
+        // 总是写入文件
+        this.writeToFile(formatted);
+        // 根据安静模式和级别决定是否输出到控制台
+        // 注意：不需要额外传递 data，因为 formatted 已包含所有需要的信息
+        if (!isQuietMode()) {
+            const consoleMethod = level === "error" ? console.error :
+                level === "warn" ? console.warn :
+                    level === "info" ? console.log :
+                        console.debug;
+            consoleMethod(formatted);
+        }
+    }
+    debug(message, data) {
+        this.log("debug", message, data);
+    }
+    info(message, data) {
+        this.log("info", message, data);
+    }
+    warn(message, data) {
+        this.log("warn", message, data);
+    }
+    error(message, data) {
+        this.log("error", message, data);
+    }
+}
+// ============================================================================
+// 导出
+// ============================================================================
+const loggerCache = new Map();
+/**
+ * 创建或获取 Logger 实例
+ * @param prefix Logger 前缀
+ *
+ * 日志文件名通过 ConfigComponent 实时读取（log-trace.logging.file）
+ */
+export function createLogger(prefix) {
+    // 缓存 key 只用 prefix，因为 filename 通过配置实时读取
+    if (!loggerCache.has(prefix)) {
+        loggerCache.set(prefix, new Logger(prefix));
+    }
+    return loggerCache.get(prefix);
+}
+/**
+ * 获取所有日志级别
+ */
+export function getLogLevels() {
+    return ["debug", "info", "warn", "error"];
+}
+//# sourceMappingURL=logger.js.map

package/dist/core/src/env/log-trace/logger.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=logger.test.d.ts.map

package/dist/core/src/env/log-trace/logger.test.js

@@ -0,0 +1,118 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { createLogger, getLogDir, getLogLevel, getCategoryLogLevel, setQuietMode, isQuietMode, setConfigComponent, } from "./logger.js";
+describe("Logger", () => {
+    beforeEach(() => {
+        // 创建临时日志目录用于测试
+    });
+    afterEach(() => {
+        // 清理
+    });
+    describe("createLogger", () => {
+        test("should create logger with default config", () => {
+            const logger = createLogger("test");
+            expect(logger).toBeDefined();
+            expect(typeof logger.debug).toBe("function");
+            expect(typeof logger.info).toBe("function");
+            expect(typeof logger.warn).toBe("function");
+            expect(typeof logger.error).toBe("function");
+        });
+        test("should create logger with custom prefix", () => {
+            const logger = createLogger("custom-prefix");
+            expect(logger).toBeDefined();
+        });
+        test("should create multiple loggers with same name (caching)", () => {
+            const logger1 = createLogger("shared");
+            const logger2 = createLogger("shared");
+            expect(logger1).toBe(logger2); // 同一个实例
+        });
+    });
+    describe("log levels", () => {
+        test("should log debug messages", () => {
+            const logger = createLogger("debug-test");
+            // 不应该抛出错误
+            expect(() => logger.debug("test message")).not.toThrow();
+        });
+        test("should log info messages", () => {
+            const logger = createLogger("info-test");
+            expect(() => logger.info("test message")).not.toThrow();
+        });
+        test("should log warn messages", () => {
+            const logger = createLogger("warn-test");
+            expect(() => logger.warn("test message")).not.toThrow();
+        });
+        test("should log error messages", () => {
+            const logger = createLogger("error-test");
+            expect(() => logger.error("test message")).not.toThrow();
+        });
+        test("should log with data", () => {
+            const logger = createLogger("data-test");
+            expect(() => logger.info("test message", { key: "value" })).not.toThrow();
+        });
+    });
+    describe("quiet mode", () => {
+        test("should enable quiet mode", () => {
+            setQuietMode(true);
+            expect(isQuietMode()).toBe(true);
+        });
+        test("should disable quiet mode", () => {
+            setQuietMode(false);
+            expect(isQuietMode()).toBe(false);
+        });
+        test("should not output to console in quiet mode", () => {
+            setQuietMode(true);
+            const logger = createLogger("quiet-test");
+            // 在 quiet 模式下，日志应该只写入文件，不输出到控制台
+            expect(() => logger.info("quiet message")).not.toThrow();
+        });
+    });
+    describe("getLogDir", () => {
+        test("should return default logs directory", () => {
+            const logDir = getLogDir();
+            // 默认应该是 XDG 路径
+            expect(logDir).toMatch(/\.local\/share\/roy-agent\/logs$/);
+        });
+    });
+    describe("category log levels", () => {
+        // Mock ConfigComponent
+        const mockConfigComponent = {
+            get: (key) => {
+                const config = {
+                    "log_trace.logging.levels": {
+                        llm: "debug",
+                        agent: "warn",
+                    },
+                    "log_trace.logging.level": "info",
+                };
+                return config[key];
+            },
+        };
+        test("should return default log level", () => {
+            // 在没有配置的情况下应该返回默认值 info
+            setConfigComponent(null);
+            const level = getLogLevel();
+            expect(["debug", "info", "warn", "error"]).toContain(level);
+        });
+        test("should return category-specific log level", () => {
+            setConfigComponent(mockConfigComponent);
+            // llm 配置为 debug
+            expect(getCategoryLogLevel("llm")).toBe("debug");
+            // agent 配置为 warn
+            expect(getCategoryLogLevel("agent")).toBe("warn");
+        });
+        test("should fallback to global level for unconfigured categories", () => {
+            setConfigComponent(mockConfigComponent);
+            // tool 没有配置，应该返回全局级别 info
+            expect(getCategoryLogLevel("tool")).toBe("info");
+        });
+        test("should use category level in logger", () => {
+            setConfigComponent(mockConfigComponent);
+            // llm logger 使用 debug 级别
+            const llmLogger = createLogger("llm");
+            expect(() => llmLogger.debug("debug message")).not.toThrow();
+            // agent logger 使用 warn 级别
+            const agentLogger = createLogger("agent");
+            expect(() => agentLogger.warn("warn message")).not.toThrow();
+        });
+    });
+});
+//# sourceMappingURL=logger.test.js.map

package/dist/core/src/env/log-trace/opentelemetry/cli-propagation.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview CLI Propagation 模块
+ *
+ * 提供 CLI 启动时从环境变量提取 trace context 的功能：
+ * - 从 TRACEPARENT 环境变量提取父 span context
+ * - 支持 W3C TraceContext 格式
+ *
+ * 使用场景：
+ * - Workflow CLI 启动时从父进程传递 trace context
+ * - 子进程能够关联到主进程的 trace
+ */
+import type { SpanContext } from '../types';
+/**
+ * CLI 传播选项
+ */
+export interface CliPropagationOptions {
+    /** 是否静默模式（不输出日志） */
+    silent?: boolean;
+    /** 自定义 carrier（默认从 process.env 读取） */
+    carrier?: Record<string, string | undefined>;
+}
+/**
+ * 提取结果
+ */
+export interface ExtractResult {
+    /** 提取的 traceId */
+    traceId: string;
+    /** 父 spanId（新 span 的 parentSpanId） */
+    parentSpanId: string;
+    /** 原始的 traceparent 字符串 */
+    rawTraceparent: string;
+}
+/**
+ * 从环境变量提取 trace context
+ *
+ * @param options 传播选项
+ * @returns 提取结果，如果不存在则返回 undefined
+ */
+export declare function extractFromEnv(options?: CliPropagationOptions): ExtractResult | undefined;
+/**
+ * 从提取结果构建 SpanContext
+ *
+ * 用于初始化 OTelTracerProvider 时构建传入的上下文
+ *
+ * @param extracted 提取结果
+ * @returns 适用于初始化 provider 的 SpanContext
+ */
+export declare function buildSpanContextFromExtracted(extracted: ExtractResult): SpanContext;
+/**
+ * 从提取结果构建完整 SpanContext（包含占位 spanId）
+ *
+ * 用于初始化 OTelTracerProvider 的 tracer.currentContext
+ *
+ * @param extracted 提取结果
+ * @returns SpanContext，其中 spanId 待 provider 生成新值
+ */
+export declare function buildInitialSpanContext(extracted: ExtractResult): SpanContext;
+/**
+ * CLI 初始化追踪器
+ *
+ * 从环境变量提取 trace context 并初始化 OTelTracerProvider
+ *
+ * 使用场景：
+ * ```typescript
+ * // 在 CLI 启动时调用
+ * import { initTracerFromEnv } from './opentelemetry/cli-propagation';
+ * import { getTracerProvider } from './opentelemetry/tracer-provider';
+ *
+ * async function main() {
+ *   const provider = getTracerProvider();
+ *   await provider.initialize();
+ *
+ *   // 尝试从环境变量恢复上下文
+ *   initTracerFromEnv(provider);
+ *
+ *   // 继续正常执行...
+ * }
+ * ```
+ *
+ * @param provider OTelTracerProvider 实例
+ * @param options 传播选项
+ */
+export declare function initTracerFromEnv(provider: {
+    getTracer: (name: string) => {
+        setCurrentContext: (ctx: SpanContext | undefined) => void;
+    };
+}, options?: CliPropagationOptions): void;
+/**
+ * 检查是否存在 trace context
+ *
+ * @returns 是否存在有效的 trace context
+ */
+export declare function hasTraceContext(): boolean;
+/**
+ * 获取当前 traceId（如果存在）
+ *
+ * @returns traceId 或 undefined
+ */
+export declare function getTraceId(): string | undefined;
+/**
+ * 获取当前 parentSpanId（如果存在）
+ *
+ * @returns parentSpanId 或 undefined
+ */
+export declare function getParentSpanId(): string | undefined;
+//# sourceMappingURL=cli-propagation.d.ts.map