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

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

@@ -0,0 +1,262 @@
+/**
+ * @fileoverview Log & Trace Component
+ *
+ * 提供日志和追踪的统一组件封装
+ *
+ * 配置通过 ConfigComponent 实时获取，支持配置热更新
+ */
+import { BaseComponent, type ComponentConfig, type ComponentSchema } from "../component";
+import { z } from "zod";
+import { createLogger, type LogLevel } from "./logger";
+import { type OTelTracer } from "./opentelemetry/tracer-provider";
+import { type ITraceContext } from "./trace-context";
+import type { ConfigComponent } from "../../config/config-component";
+/**
+ * 获取默认日志目录（基于 XDG 标准）
+ * 存储在 XDG_DATA_HOME/roy-agent/logs/
+ */
+export declare function getDefaultLogDir(): string;
+/**
+ * 获取默认的 span 数据库路径（基于 XDG 标准）
+ * 存储在 XDG_DATA_HOME/roy-agent/traces.db
+ */
+export declare function getDefaultSpanDbPath(): string;
+/**
+ * Log & Trace Component 配置 Schema
+ */
+export declare const LogTraceConfigSchema: z.ZodObject<{
+    /** 是否启用日志 */
+    logging: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        level: z.ZodDefault<z.ZodEnum<["debug", "info", "warn", "error"]>>;
+        quiet: z.ZodDefault<z.ZodBoolean>;
+        file: z.ZodDefault<z.ZodString>;
+        dir: z.ZodDefault<z.ZodString>;
+        /** 日志输出最大长度（0 表示不限制） */
+        maxOutput: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        level?: "error" | "debug" | "info" | "warn";
+        enabled?: boolean;
+        file?: string;
+        quiet?: boolean;
+        dir?: string;
+        maxOutput?: number;
+    }, {
+        level?: "error" | "debug" | "info" | "warn";
+        enabled?: boolean;
+        file?: string;
+        quiet?: boolean;
+        dir?: string;
+        maxOutput?: number;
+    }>>;
+    /** 是否启用追踪 */
+    tracing: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        dbPath: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        enabled?: boolean;
+        dbPath?: string;
+    }, {
+        enabled?: boolean;
+        dbPath?: string;
+    }>>;
+    /** 初始化请求上下文 */
+    initContext: z.ZodOptional<z.ZodObject<{
+        requestId: z.ZodOptional<z.ZodString>;
+        sessionId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        requestId?: string;
+        sessionId?: string;
+    }, {
+        requestId?: string;
+        sessionId?: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    logging?: {
+        level?: "error" | "debug" | "info" | "warn";
+        enabled?: boolean;
+        file?: string;
+        quiet?: boolean;
+        dir?: string;
+        maxOutput?: number;
+    };
+    tracing?: {
+        enabled?: boolean;
+        dbPath?: string;
+    };
+    initContext?: {
+        requestId?: string;
+        sessionId?: string;
+    };
+}, {
+    logging?: {
+        level?: "error" | "debug" | "info" | "warn";
+        enabled?: boolean;
+        file?: string;
+        quiet?: boolean;
+        dir?: string;
+        maxOutput?: number;
+    };
+    tracing?: {
+        enabled?: boolean;
+        dbPath?: string;
+    };
+    initContext?: {
+        requestId?: string;
+        sessionId?: string;
+    };
+}>;
+export type LogTraceConfig = z.infer<typeof LogTraceConfigSchema>;
+/**
+ * LogTraceComponent 配置选项（通过 options 传递）
+ *
+ * 配置加载顺序（优先级从低到高）：
+ * 1. File - 配置文件（通过 configPath 指定）
+ * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+ * 3. Object - 直接传入的 config 对象（最高优先级）
+ */
+export interface LogTraceComponentOptions {
+    /** ConfigComponent 实例（必填） */
+    configComponent: ConfigComponent;
+    /** 配置文件相对路径（可选，基于 XDG_DATA_HOME） */
+    configPath?: string;
+    /** 环境变量前缀（可选，默认 "LOG"） */
+    envPrefix?: string;
+    /** 回调函数 */
+    callbacks?: {
+        onLogLevelChange?: (level: LogLevel) => void;
+    };
+    /** 直接传入的配置对象（可选，优先级最高） */
+    config?: Partial<LogTraceConfig>;
+}
+/**
+ * Log & Trace Component
+ *
+ * 提供统一的日志和追踪能力
+ * 配置通过 ConfigComponent 实时获取，支持配置热更新
+ *
+ * @example
+ * // 通过 ConfigComponent 初始化
+ * const configComponent = new ConfigComponent();
+ * const component = new LogTraceComponent();
+ * await component.init({
+ *   env,  // Environment 实例（必填）
+ *   options: { configComponent }
+ * });
+ *
+ * // 配置更新后，日志级别会自动热更新
+ * configComponent.set("log-trace.logging.level", "debug");
+ *
+ * // 初始化追踪上下文
+ * component.initContext("request-123", "session-456");
+ *
+ * // 使用日志
+ * component.getLogger().info("Hello, world!");
+ *
+ * // 使用追踪
+ * const span = component.getTracer().startSpan("my-span");
+ * component.getTracer().endSpan(span);
+ */
+export declare class LogTraceComponent extends BaseComponent {
+    readonly name = "log-trace";
+    readonly version = "1.0.0";
+    private config?;
+    private configComponent?;
+    private tracer?;
+    private traceContext?;
+    /** 配置变更 watcher 清理函数 */
+    private configWatcher?;
+    constructor();
+    /**
+     * 初始化组件
+     *
+     * 配置加载优先级（从高到低）：
+     * 1. Object - 直接传入的 config 对象
+     * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+     * 3. File - 配置文件（通过 configPath 指定）
+     */
+    init(config: ComponentConfig): Promise<void>;
+    /**
+     * 注册配置到 ConfigComponent
+     *
+     * 遵循 SessionComponent 模式：
+     * 1. 使用 registerComponent 注册配置结构
+     * 2. 使用 load 加载配置
+     * 3. 设置默认值
+     * 4. 处理环境变量后备方案
+     * 5. 处理 config 对象
+     *
+     * 配置加载顺序（优先级从低到高）：
+     * 1. FileSource - 从配置文件加载（最低）
+     * 2. EnvSource - 从环境变量加载（中等）
+     * 3. MemorySource - 直接配置对象（最高）
+     */
+    private registerConfig;
+    /**
+     * 将配置对象展平为点号路径
+     */
+    private flattenConfig;
+    /**
+     * 注册配置热更新监听
+     */
+    private registerConfigWatcher;
+    /**
+     * 处理配置变更
+     */
+    protected onConfigChange(event: {
+        key: string;
+        oldValue?: unknown;
+        newValue?: unknown;
+    }): void;
+    /**
+     * 创建存储实例
+     *
+     * @throws Error 如果未配置 dbPath
+     */
+    private createStorage;
+    /**
+     * 配置日志系统
+     */
+    private configureLogging;
+    /**
+     * 初始化追踪上下文
+     *
+     * @param requestId 请求 ID
+     * @param sessionId 会话 ID（可选）
+     */
+    initContext(requestId: string, sessionId?: string): void;
+    /**
+     * 创建新的追踪上下文（返回清理函数）
+     *
+     * @param requestId 请求 ID
+     * @param sessionId 会话 ID（可选）
+     */
+    startContext(requestId: string, sessionId?: string): () => void;
+    /**
+     * 获取 Logger
+     *
+     * @param prefix 日志前缀
+     */
+    getLogger(prefix?: string): ReturnType<typeof createLogger>;
+    /**
+     * 获取 Tracer
+     */
+    getTracer(): OTelTracer;
+    /**
+     * 获取 Trace Context
+     */
+    getTraceContext(): ITraceContext | undefined;
+    /**
+     * 获取当前 requestId
+     */
+    getRequestId(): string | undefined;
+    /**
+     * 停止组件
+     */
+    onStop(): Promise<void>;
+}
+/**
+ * Log & Trace Component Schema
+ */
+export declare const logTraceComponentSchema: ComponentSchema;
+//# sourceMappingURL=log-trace-component.d.ts.map

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

@@ -0,0 +1,405 @@
+/**
+ * @fileoverview Log & Trace Component
+ *
+ * 提供日志和追踪的统一组件封装
+ *
+ * 配置通过 ConfigComponent 实时获取，支持配置热更新
+ */
+import { BaseComponent, } from "../component.js";
+import { z } from "zod";
+import { join } from "path";
+import { createLogger, setQuietMode, setConfigComponent } from "./logger.js";
+import { getTracerProvider } from "./opentelemetry/tracer-provider.js";
+import { SQLiteSpanStorage } from "./span-storage.js";
+import { initTraceContext } from "./trace-context.js";
+import { envKeyToConfigKey } from "../../config/env-key.js";
+import { LOG_TRACE_CONFIG_REGISTRATION, LOG_TRACE_DEFAULTS } from "./log-trace-config-registration.js";
+// ============================================================================
+// Default Paths (based on XDG_DATA_HOME)
+// ============================================================================
+/**
+ * 获取默认数据目录（基于 XDG 标准）
+ */
+function getDefaultDataDir() {
+    // 尝试使用 xdg-basedir
+    try {
+        const xdg = require("xdg-basedir");
+        if (xdg.xdgData) {
+            return xdg.xdgData;
+        }
+    }
+    catch { }
+    // 回退到 ~/.local/share
+    const home = process.env.HOME || process.env.USERPROFILE || "/tmp";
+    return join(home, ".local", "share");
+}
+/**
+ * 获取默认日志目录（基于 XDG 标准）
+ * 存储在 XDG_DATA_HOME/roy-agent/logs/
+ */
+export function getDefaultLogDir() {
+    return join(getDefaultDataDir(), "roy-agent", "logs");
+}
+/**
+ * 获取默认的 span 数据库路径（基于 XDG 标准）
+ * 存储在 XDG_DATA_HOME/roy-agent/traces.db
+ */
+export function getDefaultSpanDbPath() {
+    return join(getDefaultDataDir(), "roy-agent", "traces.db");
+}
+// ============================================================================
+// Config Schema
+// ============================================================================
+/**
+ * Log & Trace Component 配置 Schema
+ */
+export const LogTraceConfigSchema = z.object({
+    /** 是否启用日志 */
+    logging: z.object({
+        enabled: z.boolean().default(true),
+        level: z.enum(["debug", "info", "warn", "error"]).default("info"),
+        quiet: z.boolean().default(false),
+        file: z.string().default("app.log"),
+        dir: z.string().default(getDefaultLogDir()),
+        /** 日志输出最大长度（0 表示不限制） */
+        maxOutput: z.number().default(0),
+    }).default({}),
+    /** 是否启用追踪 */
+    tracing: z.object({
+        enabled: z.boolean().default(true),
+        dbPath: z.string().optional(),
+    }).default({}),
+    /** 初始化请求上下文 */
+    initContext: z.object({
+        requestId: z.string().optional(),
+        sessionId: z.string().optional(),
+    }).optional(),
+});
+// ============================================================================
+// Component
+// ============================================================================
+/**
+ * Log & Trace Component
+ *
+ * 提供统一的日志和追踪能力
+ * 配置通过 ConfigComponent 实时获取，支持配置热更新
+ *
+ * @example
+ * // 通过 ConfigComponent 初始化
+ * const configComponent = new ConfigComponent();
+ * const component = new LogTraceComponent();
+ * await component.init({
+ *   env,  // Environment 实例（必填）
+ *   options: { configComponent }
+ * });
+ *
+ * // 配置更新后，日志级别会自动热更新
+ * configComponent.set("log-trace.logging.level", "debug");
+ *
+ * // 初始化追踪上下文
+ * component.initContext("request-123", "session-456");
+ *
+ * // 使用日志
+ * component.getLogger().info("Hello, world!");
+ *
+ * // 使用追踪
+ * const span = component.getTracer().startSpan("my-span");
+ * component.getTracer().endSpan(span);
+ */
+export class LogTraceComponent extends BaseComponent {
+    name = "log-trace";
+    version = "1.0.0";
+    config;
+    configComponent;
+    tracer;
+    traceContext;
+    /** 配置变更 watcher 清理函数 */
+    configWatcher;
+    constructor() {
+        super();
+    }
+    /**
+     * 初始化组件
+     *
+     * 配置加载优先级（从高到低）：
+     * 1. Object - 直接传入的 config 对象
+     * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+     * 3. File - 配置文件（通过 configPath 指定）
+     */
+    async init(config) {
+        // 调用基类 init，注入 env
+        await super.init(config);
+        // 从 options 获取 ConfigComponent
+        const options = config.options;
+        if (!options?.configComponent) {
+            throw new Error("ConfigComponent is required for LogTraceComponent initialization");
+        }
+        this.configComponent = options.configComponent;
+        await this.registerConfig(options);
+        // 初始化 Trace Context
+        this.traceContext = initTraceContext();
+        // 初始化 Tracer (OTel)
+        const provider = getTracerProvider();
+        // TODO: 这里后续要统一使用 "roy-tracer"，但需要先重构为单例模式
+        // 目前保留原有 tracer 名称以避免破坏现有功能
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const _unused = provider;
+        await provider.initialize();
+        this.tracer = provider.getTracer("roy-tracer");
+        // 配置日志
+        this.configureLogging();
+        // 初始化请求上下文（如果配置了）
+        if (this.config?.initContext?.requestId) {
+            this.traceContext.initContext(this.config.initContext.requestId, this.config.initContext.sessionId);
+        }
+        this.setStatus("running");
+    }
+    /**
+     * 注册配置到 ConfigComponent
+     *
+     * 遵循 SessionComponent 模式：
+     * 1. 使用 registerComponent 注册配置结构
+     * 2. 使用 load 加载配置
+     * 3. 设置默认值
+     * 4. 处理环境变量后备方案
+     * 5. 处理 config 对象
+     *
+     * 配置加载顺序（优先级从低到高）：
+     * 1. FileSource - 从配置文件加载（最低）
+     * 2. EnvSource - 从环境变量加载（中等）
+     * 3. MemorySource - 直接配置对象（最高）
+     */
+    async registerConfig(options) {
+        const configComponent = options.configComponent;
+        if (!configComponent)
+            return;
+        const { configPath, envPrefix, config } = options;
+        const prefix = envPrefix !== undefined ? envPrefix : "LOG_TRACE";
+        // 1. 使用 registerComponent 注册配置结构（keys 和 sources）
+        configComponent.registerComponent(LOG_TRACE_CONFIG_REGISTRATION);
+        // 2. 注册 FileSource（如果提供了 configPath）
+        if (configPath) {
+            configComponent.registerSource({
+                type: "file",
+                relativePath: configPath,
+                optional: true,
+                watch: false
+            });
+        }
+        // 3. 注册 EnvSource
+        configComponent.registerSource({
+            type: "env",
+            envPrefix: prefix,
+            priority: 20,
+            watch: false
+        });
+        // 4. 从 sources 加载配置（FileSource 和 EnvSource）
+        await configComponent.load("log-trace");
+        // 5. 后备方案：直接读取环境变量（确保所有环境变量都被处理）
+        for (const envKey of Object.keys(process.env)) {
+            const configKey = envKeyToConfigKey(envKey, prefix, "log-trace");
+            if (!configKey)
+                continue;
+            const value = process.env[envKey];
+            if (value !== undefined) {
+                await configComponent.set(configKey, value);
+            }
+        }
+        // 6. 设置静态默认值（只有当配置不存在时）
+        for (const [key, value] of Object.entries(LOG_TRACE_DEFAULTS)) {
+            if (configComponent.get(key) === undefined) {
+                await configComponent.set(key, value);
+            }
+        }
+        // 7. 特殊处理动态默认值（这些无法在 defaults 中定义）
+        if (configComponent.get("log-trace.logging.dir") === undefined) {
+            await configComponent.set("log-trace.logging.dir", getDefaultLogDir());
+        }
+        if (configComponent.get("log-trace.logging.file") === undefined) {
+            await configComponent.set("log-trace.logging.file", "app.log");
+        }
+        if (configComponent.get("log-trace.logging.maxOutput") === undefined) {
+            await configComponent.set("log-trace.logging.maxOutput", 0);
+        }
+        if (configComponent.get("log-trace.tracing.dbPath") === undefined) {
+            await configComponent.set("log-trace.tracing.dbPath", getDefaultSpanDbPath());
+        }
+        // 8. 直接配置对象（最高优先级）
+        if (config) {
+            const flatConfig = this.flattenConfig(config);
+            for (const [key, value] of Object.entries(flatConfig)) {
+                await configComponent.set(key, value);
+            }
+        }
+        // 9. 注册配置热更新监听
+        this.registerConfigWatcher(configComponent);
+        // 10. 设置全局 ConfigComponent（让 logger 可以读取配置）
+        setConfigComponent(configComponent);
+        // 11. 解析最终配置
+        // 如果 tracing.dbPath 未配置，使用默认值
+        const tracingDbPath = configComponent.get("log-trace.tracing.dbPath");
+        this.config = {
+            logging: {
+                enabled: configComponent.get("log-trace.logging.enabled") ?? true,
+                level: configComponent.get("log-trace.logging.level") ?? "info",
+                quiet: configComponent.get("log-trace.logging.quiet") ?? false,
+                file: configComponent.get("log-trace.logging.file") ?? "app.log",
+                dir: configComponent.get("log-trace.logging.dir") ?? getDefaultLogDir(),
+                maxOutput: configComponent.get("log-trace.logging.maxOutput") ?? 0,
+            },
+            tracing: {
+                enabled: configComponent.get("log-trace.tracing.enabled") ?? true,
+                dbPath: tracingDbPath ?? getDefaultSpanDbPath(),
+            },
+        };
+    }
+    /**
+     * 将配置对象展平为点号路径
+     */
+    flattenConfig(obj, prefix = "log-trace") {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            const fullKey = `${prefix}.${key}`;
+            if (value && typeof value === "object" && !Array.isArray(value)) {
+                Object.assign(result, this.flattenConfig(value, fullKey));
+            }
+            else {
+                result[fullKey] = value;
+            }
+        }
+        return result;
+    }
+    /**
+     * 注册配置热更新监听
+     */
+    registerConfigWatcher(configComponent) {
+        if (typeof configComponent.watch !== "function") {
+            return;
+        }
+        this.configWatcher = configComponent.watch("log-trace.*", (event) => {
+            this.onConfigChange(event);
+        });
+    }
+    /**
+     * 处理配置变更
+     */
+    onConfigChange(event) {
+        if (event.key === "log-trace.logging.quiet") {
+            setQuietMode(event.newValue);
+        }
+    }
+    /**
+     * 创建存储实例
+     *
+     * @throws Error 如果未配置 dbPath
+     */
+    createStorage() {
+        // 优先从 ConfigComponent 获取 dbPath
+        if (this.configComponent) {
+            const dbPath = this.configComponent.get("log-trace.tracing.dbPath");
+            if (dbPath) {
+                return new SQLiteSpanStorage(dbPath);
+            }
+        }
+        // 降级到本地配置
+        if (this.config?.tracing?.dbPath) {
+            return new SQLiteSpanStorage(this.config.tracing.dbPath);
+        }
+        // 最后使用默认值
+        return new SQLiteSpanStorage(getDefaultSpanDbPath());
+    }
+    /**
+     * 配置日志系统
+     */
+    configureLogging() {
+        if (!this.config?.logging)
+            return;
+        if (this.config.logging.quiet) {
+            setQuietMode(true);
+        }
+    }
+    /**
+     * 初始化追踪上下文
+     *
+     * @param requestId 请求 ID
+     * @param sessionId 会话 ID（可选）
+     */
+    initContext(requestId, sessionId) {
+        if (!this.traceContext) {
+            throw new Error("Component not initialized");
+        }
+        this.traceContext.initContext(requestId, sessionId);
+    }
+    /**
+     * 创建新的追踪上下文（返回清理函数）
+     *
+     * @param requestId 请求 ID
+     * @param sessionId 会话 ID（可选）
+     */
+    startContext(requestId, sessionId) {
+        if (!this.traceContext) {
+            throw new Error("Component not initialized");
+        }
+        return this.traceContext.startNewContext(requestId, sessionId);
+    }
+    /**
+     * 获取 Logger
+     *
+     * @param prefix 日志前缀
+     */
+    getLogger(prefix) {
+        return createLogger(prefix || "app");
+    }
+    /**
+     * 获取 Tracer
+     */
+    getTracer() {
+        if (!this.tracer) {
+            throw new Error("Component not initialized");
+        }
+        return this.tracer;
+    }
+    /**
+     * 获取 Trace Context
+     */
+    getTraceContext() {
+        return this.traceContext;
+    }
+    /**
+     * 获取当前 requestId
+     */
+    getRequestId() {
+        return this.traceContext?.getRequestId();
+    }
+    /**
+     * 停止组件
+     */
+    async onStop() {
+        // 清理配置 watcher
+        this.configWatcher?.();
+        this.configWatcher = undefined;
+        // 清理 tracer
+        this.tracer = undefined;
+        this.setStatus("stopped");
+    }
+}
+// ============================================================================
+// Component Schema
+// ============================================================================
+/**
+ * Log & Trace Component Schema
+ */
+export const logTraceComponentSchema = {
+    name: "log-trace",
+    schema: LogTraceConfigSchema,
+    defaults: {
+        logging: { enabled: true, level: "info", quiet: false, file: "app.log" },
+        tracing: { enabled: true },
+    },
+    metadata: {
+        description: "Log & Trace Component - Unified logging and tracing",
+        version: "1.0.0",
+        author: "roy-agent",
+    },
+};
+//# sourceMappingURL=log-trace-component.js.map

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

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview LogTraceComponent Tests
+ *
+ * 使用 TDD 方法测试 LogTraceComponent 配置加载
+ */
+export {};
+//# sourceMappingURL=log-trace-component.test.d.ts.map