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

package/dist/core/src/config/env-key.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 环境变量键名转换工具
+ *
+ * 提供统一的环境变量键名转换逻辑，供 EnvSource 和其他组件使用
+ *
+ * 转换规则（toEnvKey）：
+ * 1. 将点号替换为下划线
+ * 2. 将驼峰命名转换为下划线分隔的大写形式
+ * 3. 拼接前缀（如果前缀不以_结尾则自动添加）
+ *
+ * 转换规则（fromEnvKey - 用于 EnvSource）：
+ * 1. 移除前缀
+ * 2. 保持原始格式（大小写）
+ *
+ * 转换规则（envKeyToConfigKey - 通用）：
+ * 1. 移除前缀
+ * 2. 转小写
+ * 3. 将下划线替换为点号
+ * 4. 拼接组件名前缀
+ *
+ * @example
+ * // toEnvKey
+ * toEnvKey("llm.defaultModel", "LLM") -> "LLM_LLM_DEFAULT_MODEL"
+ * toEnvKey("logTrace.level", "LOG") -> "LOG_LOG_TRACE_LEVEL"
+ *
+ * // fromEnvKey (用于 EnvSource.list)
+ * fromEnvKey("LLM_LLM_DEBUG", "LLM_") -> "DEBUG"
+ *
+ * // envKeyToConfigKey (通用，支持任意组件)
+ * envKeyToConfigKey("LLM_LLM_DEFAULT_MODEL", "LLM", "llm") -> "llm.default.model"
+ * envKeyToConfigKey("LOG_LOG_TRACE_LEVEL", "LOG", "logTrace") -> "logTrace.level"
+ */
+/**
+ * 将点号路径转换为环境变量名（带前缀）
+ *
+ * 规则：
+ * - `.` 和 `-` 都替换为路径分隔符 `_`
+ * - 驼峰转为下划线大写
+ *
+ * 转换示例：
+ * - `llm.defaultModel` + `LLM` -> `LLM_LLM_DEFAULT_MODEL`
+ * - `log-trace.logging.level` + `LOG` -> `LOG_TRACE_LOGGING_LEVEL`
+ *
+ * @example
+ * toEnvKey("llm.defaultModel", "LLM") -> "LLM_LLM_DEFAULT_MODEL"
+ * toEnvKey("log-trace.logging.level", "LOG") -> "LOG_TRACE_LOGGING_LEVEL"
+ */
+export declare function toEnvKey(key: string, prefix: string): string;
+/**
+ * 从环境变量名提取内部键名（移除前缀，保持原始格式）
+ *
+ * 用于 EnvSource.list() 等需要保持原始格式的场景
+ */
+export declare function fromEnvKey(envKey: string, prefix: string): string;
+/**
+ * 将环境变量名转换为配置键名（通用，支持任意组件）
+ *
+ * 规则：
+ * - `_` 转换为 `.` 作为键路径分隔符
+ * - 组件名中的 `-` 在环境变量中也会是 `_`（因为 toEnvKey 会转换）
+ *
+ * 环境变量格式约定:
+ * - PREFIX_KEY: 如 LLM_DEFAULT_MODEL -> llm.default.model
+ * - PREFIX_COMPONENT_KEY: 如 LLM_LLM_DEFAULT_MODEL -> llm.default.model
+ * - 对于带连字符的组件名: 如 LOG_TRACE_LOGGING_LEVEL -> log-trace.logging.level (当组件名为 log-trace)
+ *
+ * @param envKey - 环境变量名（如 LLM_LLM_DEFAULT_MODEL 或 LOG_TRACE_LOGGING_LEVEL）
+ * @param prefix - 环境变量前缀（如 LLM 或 LOG）
+ * @param componentName - 组件名（如 llm, logTrace, log-trace）
+ * @returns 配置键名（如 llm.default.model 或 log-trace.logging.level）
+ *
+ * @example
+ * // 格式1: PREFIX_KEY
+ * envKeyToConfigKey("LLM_DEFAULT_MODEL", "LLM", "llm") -> "llm.default.model"
+ *
+ * // 格式2: PREFIX_COMPONENT_KEY
+ * envKeyToConfigKey("LLM_LLM_DEFAULT_MODEL", "LLM", "llm") -> "llm.default.model"
+ *
+ * // 格式3: 连字符组件名（环境变量中 - 会被转成 _）
+ * envKeyToConfigKey("LOG_TRACE_LOGGING_LEVEL", "LOG", "log-trace") -> "log-trace.logging.level"
+ */
+export declare function envKeyToConfigKey(envKey: string, prefix: string, componentName: string): string | undefined;
+/**
+ * 从环境变量键名提取组件名
+ *
+ * 用于自动发现所有以 prefix 开头的环境变量
+ *
+ * @param envKey - 环境变量名
+ * @param prefix - 前缀
+ * @returns 组件名和剩余部分（如 ["llm", "default.model"]）
+ */
+export declare function extractComponentFromEnvKey(envKey: string, prefix: string): [string, string] | undefined;
+//# sourceMappingURL=env-key.d.ts.map

package/dist/core/src/config/env-key.js

@@ -0,0 +1,189 @@
+/**
+ * 环境变量键名转换工具
+ *
+ * 提供统一的环境变量键名转换逻辑，供 EnvSource 和其他组件使用
+ *
+ * 转换规则（toEnvKey）：
+ * 1. 将点号替换为下划线
+ * 2. 将驼峰命名转换为下划线分隔的大写形式
+ * 3. 拼接前缀（如果前缀不以_结尾则自动添加）
+ *
+ * 转换规则（fromEnvKey - 用于 EnvSource）：
+ * 1. 移除前缀
+ * 2. 保持原始格式（大小写）
+ *
+ * 转换规则（envKeyToConfigKey - 通用）：
+ * 1. 移除前缀
+ * 2. 转小写
+ * 3. 将下划线替换为点号
+ * 4. 拼接组件名前缀
+ *
+ * @example
+ * // toEnvKey
+ * toEnvKey("llm.defaultModel", "LLM") -> "LLM_LLM_DEFAULT_MODEL"
+ * toEnvKey("logTrace.level", "LOG") -> "LOG_LOG_TRACE_LEVEL"
+ *
+ * // fromEnvKey (用于 EnvSource.list)
+ * fromEnvKey("LLM_LLM_DEBUG", "LLM_") -> "DEBUG"
+ *
+ * // envKeyToConfigKey (通用，支持任意组件)
+ * envKeyToConfigKey("LLM_LLM_DEFAULT_MODEL", "LLM", "llm") -> "llm.default.model"
+ * envKeyToConfigKey("LOG_LOG_TRACE_LEVEL", "LOG", "logTrace") -> "logTrace.level"
+ */
+/**
+ * 将点号路径转换为环境变量名（带前缀）
+ *
+ * 规则：
+ * - `.` 和 `-` 都替换为路径分隔符 `_`
+ * - 驼峰转为下划线大写
+ *
+ * 转换示例：
+ * - `llm.defaultModel` + `LLM` -> `LLM_LLM_DEFAULT_MODEL`
+ * - `log-trace.logging.level` + `LOG` -> `LOG_TRACE_LOGGING_LEVEL`
+ *
+ * @example
+ * toEnvKey("llm.defaultModel", "LLM") -> "LLM_LLM_DEFAULT_MODEL"
+ * toEnvKey("log-trace.logging.level", "LOG") -> "LOG_TRACE_LOGGING_LEVEL"
+ */
+export function toEnvKey(key, prefix) {
+    // 1. 将点号和连字符替换为下划线
+    let keyNormalized = key.replace(/[.-]/g, "_");
+    // 2. 将驼峰命名转换为下划线分隔的大写形式
+    keyNormalized = keyNormalized
+        .replace(/([a-z])([A-Z])/g, "$1_$2")
+        .replace(/_+/g, "_")
+        .toUpperCase();
+    // 3. 拼接前缀
+    if (prefix) {
+        // 如果前缀已以下划线结尾，不要重复添加
+        const separator = prefix.endsWith("_") ? "" : "_";
+        return `${prefix}${separator}${keyNormalized}`;
+    }
+    return keyNormalized;
+}
+/**
+ * 从环境变量名提取内部键名（移除前缀，保持原始格式）
+ *
+ * 用于 EnvSource.list() 等需要保持原始格式的场景
+ */
+export function fromEnvKey(envKey, prefix) {
+    if (!prefix) {
+        return envKey;
+    }
+    // 检查前缀匹配
+    if (envKey.startsWith(prefix)) {
+        const afterPrefix = envKey.slice(prefix.length);
+        // 移除开头的下划线（如果有）
+        if (afterPrefix.startsWith("_")) {
+            return afterPrefix.slice(1);
+        }
+        return afterPrefix;
+    }
+    return envKey;
+}
+/**
+ * 将环境变量名转换为配置键名（通用，支持任意组件）
+ *
+ * 规则：
+ * - `_` 转换为 `.` 作为键路径分隔符
+ * - 组件名中的 `-` 在环境变量中也会是 `_`（因为 toEnvKey 会转换）
+ *
+ * 环境变量格式约定:
+ * - PREFIX_KEY: 如 LLM_DEFAULT_MODEL -> llm.default.model
+ * - PREFIX_COMPONENT_KEY: 如 LLM_LLM_DEFAULT_MODEL -> llm.default.model
+ * - 对于带连字符的组件名: 如 LOG_TRACE_LOGGING_LEVEL -> log-trace.logging.level (当组件名为 log-trace)
+ *
+ * @param envKey - 环境变量名（如 LLM_LLM_DEFAULT_MODEL 或 LOG_TRACE_LOGGING_LEVEL）
+ * @param prefix - 环境变量前缀（如 LLM 或 LOG）
+ * @param componentName - 组件名（如 llm, logTrace, log-trace）
+ * @returns 配置键名（如 llm.default.model 或 log-trace.logging.level）
+ *
+ * @example
+ * // 格式1: PREFIX_KEY
+ * envKeyToConfigKey("LLM_DEFAULT_MODEL", "LLM", "llm") -> "llm.default.model"
+ *
+ * // 格式2: PREFIX_COMPONENT_KEY
+ * envKeyToConfigKey("LLM_LLM_DEFAULT_MODEL", "LLM", "llm") -> "llm.default.model"
+ *
+ * // 格式3: 连字符组件名（环境变量中 - 会被转成 _）
+ * envKeyToConfigKey("LOG_TRACE_LOGGING_LEVEL", "LOG", "log-trace") -> "log-trace.logging.level"
+ */
+export function envKeyToConfigKey(envKey, prefix, componentName) {
+    const prefixUpper = prefix.toUpperCase();
+    if (!envKey.startsWith(prefixUpper)) {
+        return undefined;
+    }
+    // 将组件名转换为下划线大写格式用于比较
+    const componentUpperNormalized = componentName
+        .replace(/-/g, "_")
+        .toUpperCase();
+    // 移除前缀
+    let keyPart = envKey.slice(prefixUpper.length);
+    // 移除前缀后的分隔符
+    if (keyPart.startsWith("_")) {
+        keyPart = keyPart.slice(1);
+    }
+    if (!keyPart) {
+        return undefined;
+    }
+    // 找出第一个下划线的位置
+    const firstUnderscore = keyPart.indexOf("_");
+    let restPart;
+    if (firstUnderscore === -1) {
+        // 没有下划线，整个作为 rest
+        restPart = keyPart;
+    }
+    else {
+        const firstPart = keyPart.slice(0, firstUnderscore);
+        const remaining = keyPart.slice(firstUnderscore + 1);
+        // 检查第一段是否等于组件名的大写形式
+        if (firstPart === componentUpperNormalized) {
+            // 匹配成功，移除组件名前缀
+            restPart = remaining;
+        }
+        else {
+            // 第一段不是组件名，整个 keyPart 作为 rest
+            restPart = keyPart;
+        }
+    }
+    if (!restPart) {
+        return undefined;
+    }
+    // 将下划线转换为点号，转小写，拼接组件名
+    const restPartConverted = restPart.replace(/_/g, ".");
+    return `${componentName}.${restPartConverted.toLowerCase()}`;
+}
+/**
+ * 从环境变量键名提取组件名
+ *
+ * 用于自动发现所有以 prefix 开头的环境变量
+ *
+ * @param envKey - 环境变量名
+ * @param prefix - 前缀
+ * @returns 组件名和剩余部分（如 ["llm", "default.model"]）
+ */
+export function extractComponentFromEnvKey(envKey, prefix) {
+    const prefixUpper = prefix.toUpperCase();
+    if (!envKey.startsWith(prefixUpper)) {
+        return undefined;
+    }
+    // 移除前缀
+    let keyPart = envKey.slice(prefixUpper.length);
+    // 移除前缀后的下划线（如果有）
+    if (keyPart.startsWith("_")) {
+        keyPart = keyPart.slice(1);
+    }
+    if (!keyPart) {
+        return undefined;
+    }
+    // 提取组件名（第一段下划线之前的部分）
+    const underscoreIndex = keyPart.indexOf("_");
+    if (underscoreIndex === -1) {
+        // 只有一个部分，如 LLM_DEFAULT_MODEL -> llm.default_model
+        return [keyPart.toLowerCase().replace(/_/g, "."), ""];
+    }
+    const component = keyPart.slice(0, underscoreIndex).toLowerCase();
+    const rest = keyPart.slice(underscoreIndex + 1);
+    return [`${component}.${rest.replace(/_/g, ".")}`, rest];
+}
+//# sourceMappingURL=env-key.js.map

package/dist/core/src/config/env-source.d.ts

@@ -0,0 +1,83 @@
+import { ConfigSource, ConfigSourceType, ConfigChangeEvent } from "./config-component";
+/**
+ * EnvSource 配置
+ */
+export interface EnvSourceOptions {
+    /** 环境变量前缀 */
+    prefix?: string;
+    /** 值转换函数 */
+    transform?: (value: string, key: string) => unknown;
+    /** 轮询间隔（ms），用于检测环境变量变化 */
+    pollInterval?: number;
+    /** 优先级 */
+    priority?: number;
+    /** 是否启用监听（轮询），默认 true */
+    watch?: boolean;
+}
+/**
+ * 环境变量配置源
+ *
+ * 从 process.env 读取配置，支持：
+ * - 前缀过滤
+ * - 值转换
+ * - 环境变量监听（轮询）
+ */
+export declare class EnvSource implements ConfigSource {
+    readonly name: ConfigSourceType;
+    readonly priority = 20;
+    private prefix;
+    private transform?;
+    private pollInterval?;
+    private watchers;
+    private pollTimer?;
+    private lastValues;
+    private watchEnabled;
+    constructor(options?: EnvSourceOptions);
+    /**
+     * 获取环境变量名（带前缀）
+     * 将点号路径转换为下划线分隔的大写形式
+     * 例如: "llm.provider" + prefix "LLM" -> "LLM_LLM_PROVIDER"
+     * 例如: "DEBUG" + prefix "MY_APP_" -> "MY_APP_DEBUG"
+     * 例如: "llm.defaultModel" + prefix "LLM" -> "LLM_LLM_DEFAULT_MODEL"
+     */
+    private getEnvKey;
+    /**
+     * 移除前缀获取内部 key
+     * 注意：保持原始格式（大小写），仅移除前缀
+     */
+    private getInternalKey;
+    /**
+     * 读取环境变量
+     */
+    read(key: string): unknown;
+    /**
+     * 写入环境变量
+     */
+    write(key: string, value: unknown): boolean;
+    /**
+     * 删除环境变量
+     */
+    delete(key: string): boolean;
+    /**
+     * 列出所有环境变量
+     */
+    list(): Array<{
+        key: string;
+        value: unknown;
+    }>;
+    /**
+     * 监听环境变量变化
+     */
+    watch(callback: (event: ConfigChangeEvent) => void): () => void;
+    private ensurePolling;
+    private stopPolling;
+    private recordCurrentValues;
+    private checkForChanges;
+    private transformValue;
+    private notifyWatchers;
+    /**
+     * 关闭并清理资源
+     */
+    close(): void;
+}
+//# sourceMappingURL=env-source.d.ts.map

package/dist/core/src/config/env-source.js

@@ -0,0 +1,240 @@
+import { toEnvKey, fromEnvKey } from "./env-key.js";
+/**
+ * 环境变量配置源
+ *
+ * 从 process.env 读取配置，支持：
+ * - 前缀过滤
+ * - 值转换
+ * - 环境变量监听（轮询）
+ */
+export class EnvSource {
+    name = "env";
+    priority = 20;
+    prefix;
+    transform;
+    pollInterval;
+    watchers = new Set();
+    pollTimer;
+    lastValues = new Map();
+    watchEnabled = true;
+    constructor(options = {}) {
+        this.prefix = options.prefix ?? "";
+        this.transform = options.transform;
+        this.pollInterval = options.pollInterval;
+        this.watchEnabled = options.watch ?? true;
+    }
+    /**
+     * 获取环境变量名（带前缀）
+     * 将点号路径转换为下划线分隔的大写形式
+     * 例如: "llm.provider" + prefix "LLM" -> "LLM_LLM_PROVIDER"
+     * 例如: "DEBUG" + prefix "MY_APP_" -> "MY_APP_DEBUG"
+     * 例如: "llm.defaultModel" + prefix "LLM" -> "LLM_LLM_DEFAULT_MODEL"
+     */
+    getEnvKey(key) {
+        return toEnvKey(key, this.prefix);
+    }
+    /**
+     * 移除前缀获取内部 key
+     * 注意：保持原始格式（大小写），仅移除前缀
+     */
+    getInternalKey(envKey) {
+        return fromEnvKey(envKey, this.prefix);
+    }
+    /**
+     * 读取环境变量
+     */
+    read(key) {
+        const envKey = this.getEnvKey(key);
+        const value = process.env[envKey];
+        if (value === undefined) {
+            return undefined;
+        }
+        if (this.transform) {
+            return this.transform(value, key);
+        }
+        return value;
+    }
+    /**
+     * 写入环境变量
+     */
+    write(key, value) {
+        const envKey = this.getEnvKey(key);
+        const oldValue = process.env[envKey];
+        const stringValue = String(value);
+        // 设置环境变量
+        process.env[envKey] = stringValue;
+        // 通知监听器
+        const event = {
+            type: oldValue === undefined ? "add" : "change",
+            key,
+            oldValue: oldValue !== undefined ? this.transformValue(oldValue, key) : undefined,
+            newValue: this.transformValue(stringValue, key),
+            source: this.name,
+            timestamp: Date.now(),
+        };
+        this.notifyWatchers(event);
+        return true;
+    }
+    /**
+     * 删除环境变量
+     */
+    delete(key) {
+        const envKey = this.getEnvKey(key);
+        const oldValue = process.env[envKey];
+        if (oldValue === undefined) {
+            return false;
+        }
+        delete process.env[envKey];
+        // 通知监听器
+        const event = {
+            type: "delete",
+            key,
+            oldValue: this.transformValue(oldValue, key),
+            newValue: undefined,
+            source: this.name,
+            timestamp: Date.now(),
+        };
+        this.notifyWatchers(event);
+        return true;
+    }
+    /**
+     * 列出所有环境变量
+     */
+    list() {
+        const result = [];
+        const prefix = this.prefix.toUpperCase();
+        for (const envKey of Object.keys(process.env)) {
+            // 检查前缀匹配
+            if (prefix && !envKey.startsWith(prefix)) {
+                continue;
+            }
+            const key = this.getInternalKey(envKey);
+            const value = process.env[envKey];
+            if (value !== undefined) {
+                result.push({
+                    key,
+                    value: this.transformValue(value, key),
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * 监听环境变量变化
+     */
+    watch(callback) {
+        this.watchers.add(callback);
+        // 如果 watch 被禁用，直接返回
+        if (!this.watchEnabled) {
+            return () => {
+                this.watchers.delete(callback);
+            };
+        }
+        // 启动轮询
+        this.ensurePolling();
+        // 记录初始值
+        this.recordCurrentValues();
+        return () => {
+            this.watchers.delete(callback);
+            // 停止轮询如果没有监听器
+            if (this.watchers.size === 0) {
+                this.stopPolling();
+            }
+        };
+    }
+    ensurePolling() {
+        if (this.pollTimer !== undefined) {
+            return;
+        }
+        const interval = this.pollInterval ?? 1000;
+        this.pollTimer = setInterval(() => {
+            this.checkForChanges();
+        }, interval);
+    }
+    stopPolling() {
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = undefined;
+        }
+    }
+    recordCurrentValues() {
+        this.lastValues.clear();
+        const entries = this.list();
+        for (const entry of entries) {
+            const envKey = this.getEnvKey(entry.key);
+            const value = process.env[envKey];
+            if (value !== undefined) {
+                this.lastValues.set(envKey, value);
+            }
+        }
+    }
+    checkForChanges() {
+        const currentEntries = this.list();
+        const currentValues = new Map();
+        for (const entry of currentEntries) {
+            const envKey = this.getEnvKey(entry.key);
+            const value = process.env[envKey];
+            if (value !== undefined) {
+                currentValues.set(envKey, value);
+            }
+        }
+        // 检测删除
+        for (const [envKey, oldValue] of this.lastValues.entries()) {
+            if (!currentValues.has(envKey)) {
+                const key = this.getInternalKey(envKey);
+                this.notifyWatchers({
+                    type: "delete",
+                    key,
+                    oldValue: this.transformValue(oldValue, key),
+                    newValue: undefined,
+                    source: this.name,
+                    timestamp: Date.now(),
+                });
+            }
+        }
+        // 检测添加和变更
+        for (const [envKey, newValue] of currentValues.entries()) {
+            const key = this.getInternalKey(envKey);
+            const oldValue = this.lastValues.get(envKey);
+            if (oldValue === undefined) {
+                this.notifyWatchers({
+                    type: "add",
+                    key,
+                    oldValue: undefined,
+                    newValue: this.transformValue(newValue, key),
+                    source: this.name,
+                    timestamp: Date.now(),
+                });
+            }
+            else if (oldValue !== newValue) {
+                this.notifyWatchers({
+                    type: "change",
+                    key,
+                    oldValue: this.transformValue(oldValue, key),
+                    newValue: this.transformValue(newValue, key),
+                    source: this.name,
+                    timestamp: Date.now(),
+                });
+            }
+        }
+        // 更新记录
+        this.lastValues = currentValues;
+    }
+    transformValue(value, key) {
+        if (this.transform) {
+            return this.transform(value, key);
+        }
+        return value;
+    }
+    notifyWatchers(event) {
+        this.watchers.forEach((cb) => cb(event));
+    }
+    /**
+     * 关闭并清理资源
+     */
+    close() {
+        this.stopPolling();
+        this.watchers.clear();
+    }
+}
+//# sourceMappingURL=env-source.js.map

package/dist/core/src/config/env-source.test.d.ts

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