@ai-setting/roy-agent-cli 1.3.19 → 1.3.22

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

@@ -1,262 +0,0 @@
-/**
- * @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

@@ -1,405 +0,0 @@
-/**
- * @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

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