@ai-setting/roy-agent-core 1.7.52 → 1.7.53

package/dist/config/protocol-resolver.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Protocol Resolver
+ *
+ * Resolves configuration references using protocols:
+ * - file:// - Read from files, relative paths based on XDG_DATA_HOME
+ * - env:// - Read from environment variables
+ *
+ * Syntax: ${protocol://path#key}
+ */
+export type ProtocolType = "file" | "env";
+declare const PROTOCOL_PATTERN: RegExp;
+/**
+ * Protocol reference structure
+ */
+export interface ProtocolRef {
+    protocol: ProtocolType;
+    path: string;
+    key: string;
+    defaultValue?: string;
+    raw: string;
+}
+/**
+ * Resolve result
+ */
+export interface ResolveResult {
+    value: unknown;
+    source: ProtocolType;
+}
+/**
+ * ProtocolResolver 配置
+ */
+export interface ProtocolResolverOptions {
+    /** XDG 数据目录，默认 ~/.local/share */
+    xdgDataHome?: string;
+    /** 文件读取函数（用于测试注入） */
+    readFileFn?: (path: string) => string;
+}
+/**
+ * 协议解析器
+ *
+ * 解析配置中的协议引用，支持：
+ * - ${file://path#key} - 从文件读取（相对路径基于 XDG_DATA_HOME）
+ * - ${env://varName} - 从环境变量读取
+ */
+export declare class ProtocolResolver {
+    private _xdgDataHome;
+    private readFileFn;
+    constructor(options?: ProtocolResolverOptions);
+    /**
+     * 获取当前的 XDG_DATA_HOME
+     */
+    get xdgDataHome(): string;
+    /**
+     * 设置 XDG_DATA_HOME（用于运行时更新）
+     */
+    set xdgDataHome(value: string);
+    /**
+     * 获取默认 XDG_DATA_HOME
+     */
+    static getDefaultXDGDataHome(): string;
+    /**
+     * 解析协议引用
+     * 支持默认值语法: ${protocol://path#key:-default}
+     */
+    parse(ref: string): ProtocolRef | null;
+    /**
+     * 检查是否是协议引用
+     */
+    isProtocolRef(value: string): boolean;
+    /**
+     * 解析并获取协议引用的值
+     *
+     * @returns 解析结果，包含值和来源；解析失败时返回 null
+     */
+    resolve(ref: string): ResolveResult | null;
+    /**
+     * 解析文件引用
+     */
+    private resolveFileRef;
+    /**
+     * 解析并获取协议引用的值
+     * 返回 null 表示解析失败（如协议不支持、文件不存在等）
+     */
+    private resolveInternal;
+    /**
+     * 解析路径（处理相对路径）
+     */
+    private resolvePath;
+    /**
+     * 获取嵌套值
+     */
+    private getNestedValue;
+}
+export { PROTOCOL_PATTERN };