@ai-setting/roy-agent-core 1.5.15-test → 1.5.16-test

package/dist/config/index.d.ts

@@ -0,0 +1,1250 @@
+/**
+* @fileoverview Hook 系统统一类型定义
+* 
+* 提供所有 Component 使用的统一 Hook 接口
+*/
+/**
+* Hook 执行阶段
+*/
+type HookPhase = "before" | "after" | "error";
+/**
+* Hook 元信息
+*/
+interface HookMeta {
+	/** Hook 唯一名称 */
+	name: string;
+	/** 执行优先级，默认 0，数值越小越先执行 */
+	priority?: number;
+	/** 描述 */
+	description?: string;
+}
+/**
+* 统一 Hook 上下文
+* 
+* 泛型参数 T 表示该 Component 的上下文数据类型
+*/
+interface HookContext<T = unknown> {
+	/** 当前组件信息 */
+	component: {
+		/** 组件名称 */
+		name: string;
+		/** 组件版本 */
+		version: string;
+	};
+	/** 上下文数据（Component 特定） */
+	data: T;
+	/** 元数据（可用于传递额外信息） */
+	metadata: Record<string, unknown>;
+	/** 执行阶段 */
+	phase: HookPhase;
+	/** 关联的 hook 点名称 */
+	hookPoint: string;
+}
+/**
+* 统一 Hook 接口
+* 
+* 所有 Component 的 Hook 都应实现此接口
+*/
+interface Hook<T = unknown> extends HookMeta {
+	/** 执行 Hook
+	* @param ctx 上下文
+	*/
+	execute(ctx: HookContext<T>): void | Promise<void>;
+}
+/**
+* Hook 函数类型（便捷别名）
+*/
+type HookFn<T = unknown> = (ctx: HookContext<T>) => void | Promise<void>;
+/**
+* Hook 干预动作类型
+*/
+type HookActionType = "stop" | "retry" | "compress" | "extract_memory" | "inject_message" | "skip_tool" | "custom";
+/**
+* Hook 干预动作
+*/
+interface HookAction {
+	/** 动作类型 */
+	type: HookActionType;
+	/** 动作参数 */
+	params?: Record<string, unknown>;
+	/** 动作描述 */
+	description?: string;
+}
+/**
+* Hook 执行结果
+*/
+interface HookResult {
+	/** 是否被停止 */
+	stopped?: boolean;
+	/** 干预动作（如果有） */
+	action?: HookAction;
+	/** 执行结果数据 */
+	results?: unknown[];
+}
+/**
+* HookManager 配置
+*/
+interface HookManagerOptions {
+	/** 组件名称（用于上下文） */
+	componentName?: string;
+	/** 组件版本（用于上下文） */
+	componentVersion?: string;
+	/** 默认优先级 */
+	defaultPriority?: number;
+}
+/**
+* HookManager
+* 
+* 统一管理 Component 的 Hook
+* 
+* @example
+* ```typescript
+* const manager = new HookManager<MyContext>();
+* 
+* // 注册 Hook
+* manager.register("before-action", {
+*   name: "my-hook",
+*   priority: 10,
+*   execute: async (ctx) => { /* ... *\/ }
+* });
+* 
+* // 执行 Hooks
+* await manager.execute("before-action", data);
+* ```
+*/
+declare class HookManager<T = unknown> {
+	private _hooks;
+	private componentName;
+	private componentVersion;
+	private defaultPriority;
+	constructor(options?: HookManagerOptions);
+	/**
+	* 注册 Hook 到指定 hook 点
+	*/
+	register(hookPoint: string, hook: Hook<T>): void;
+	/**
+	* 注册多个 Hook
+	*/
+	registerMany(hookPoint: string, hooks: Hook<T>[]): void;
+	/**
+	* 按名称取消注册 Hook
+	* @returns 是否成功取消注册
+	*/
+	unregister(hookPoint: string, name: string): boolean;
+	/**
+	* 取消注册所有指定 hook 点的 Hook
+	*/
+	unregisterAll(hookPoint: string): void;
+	/**
+	* 执行指定 hook 点的所有 Hook
+	*/
+	execute(hookPoint: string, data: T, metadata?: Record<string, unknown>): Promise<void>;
+	/**
+	* 执行指定 hook 点的所有 Hook 并收集返回值
+	*/
+	executeAndCollect<R>(hookPoint: string, data: T, metadata?: Record<string, unknown>): Promise<R[]>;
+	/**
+	* 获取指定 hook 点的 Hook 数量
+	*/
+	count(hookPoint: string): number;
+	/**
+	* 清空所有 Hook
+	*/
+	clear(): void;
+	/**
+	* 获取所有已注册的 hook 点
+	*/
+	getHookPoints(): string[];
+	/**
+	* 检查 hook 点是否有任何 Hook
+	*/
+	hasHooks(hookPoint: string): boolean;
+	/**
+	* 设置组件信息
+	*/
+	setComponentInfo(name: string, version: string): void;
+	/**
+	* 获取所有注册的 hooks（只读副本）
+	*/
+	get hooks(): ReadonlyMap<string, Hook<T>[]>;
+	/**
+	* 执行 Hook 并支持干预机制
+	* 
+	* 如果任何一个 Hook 返回 { stop: true }，执行会停止
+	* Hook 可以通过返回 HookResult 来执行干预动作
+	* 
+	* @param hookPoint Hook 点
+	* @param data 数据
+	* @param metadata 元数据
+	* @returns 执行结果
+	*/
+	executeWithIntervention(hookPoint: string, data: T, metadata?: Record<string, unknown>): Promise<HookResult>;
+	/**
+	* 获取或创建 hook 列表
+	*/
+	private getOrCreateHooks;
+	/**
+	* 按优先级排序 Hook
+	* 
+	* 优先级相同时保持原顺序（稳定排序）
+	*/
+	private sortHooks;
+	/**
+	* 创建 Hook 上下文
+	*/
+	private createContext;
+	/**
+	* 安全执行 Hook（错误隔离）
+	*/
+	private safeExecute;
+	/**
+	* 安全执行 Hook 并返回结果
+	*/
+	private safeExecuteAndReturn;
+}
+import { ZodType as ZodType3, ZodTypeDef as ZodTypeDef2 } from "zod";
+import { ZodType as ZodType2, ZodTypeDef } from "zod";
+/**
+* @fileoverview Environment types and interfaces
+* 
+* 定义 Environment 的核心类型，包括：
+* - Environment 配置
+* - EnvEvent 事件类型
+*/
+/**
+* Environment Config
+*/
+interface EnvironmentConfig {
+	/** 环境名称 */
+	name: string;
+	/** 环境版本 */
+	version: string;
+	/** 是否启用 */
+	enabled: boolean;
+}
+/**
+* EnvEvent 元信息
+*/
+interface EnvEventMetadata {
+	/** 触发事件的 session ID */
+	trigger_session_id?: string;
+	/** 触发事件的 agent ID */
+	trigger_agent_id?: string;
+	/** Agent 名称 */
+	trigger_agent_name?: string;
+	/** 环境名称 */
+	env_name?: string;
+	/** 事件来源 */
+	source?: string;
+	/** 其他元数据 */
+	[key: string]: unknown;
+}
+/**
+* EnvEvent
+* 
+* 统一的事件机制，用于：
+* - Stream 事件（stream.start, stream.text, stream.completed 等）
+* - 工具调用事件（tool.call, tool.result 等）
+* - 会话事件（session.created, session.updated 等）
+* - Agent 事件（agent.thinking, agent.acting 等）
+*/
+interface EnvEvent<T = unknown> {
+	/** 事件 ID */
+	id: string;
+	/** 事件类型 */
+	type: string;
+	/** 时间戳 */
+	timestamp: number;
+	/** 元信息 */
+	metadata: EnvEventMetadata;
+	/** 事件负载 */
+	payload: T;
+}
+/**
+* EnvEvent Handler
+*/
+type EnvEventHandler = (event: EnvEvent) => void | Promise<void>;
+/**
+* EnvEvent 创建参数（部分属性，可选）
+* 
+* 用于 pushEnvEvent 方法，允许传入部分属性，自动补全必填字段
+*/
+interface EnvEventInput {
+	/** 事件类型（必填） */
+	type: string;
+	/** 事件 ID（可选，自动生成） */
+	id?: string;
+	/** 时间戳（可选，自动生成） */
+	timestamp?: number;
+	/** 元信息（可选，自动创建） */
+	metadata?: EnvEventMetadata;
+	/** 事件负载（可选） */
+	payload?: unknown;
+}
+/**
+* Action 类型
+*/
+interface Action {
+	/** Action 类型 */
+	type: string;
+	/** Action 参数 */
+	params?: Record<string, unknown>;
+}
+/**
+* Tool Result
+*/
+interface ToolResult {
+	/** 是否成功 */
+	success: boolean;
+	/** 输出内容 */
+	output: string | Record<string, unknown>;
+	/** 错误信息 */
+	error?: string;
+}
+/**
+* Context
+*/
+interface Context {
+	/** 会话 ID */
+	sessionId?: string;
+	/** 用户 ID */
+	userId?: string;
+	/** 工作目录 */
+	workdir?: string;
+	/** 中断信号 */
+	abort?: AbortSignal;
+	/** 元数据 */
+	metadata?: Record<string, unknown>;
+}
+type AbortSignalType = AbortSignal;
+/**
+* Agent 执行上下文
+*/
+interface AgentContext {
+	/** 会话 ID */
+	sessionId?: string;
+	/** 消息 ID */
+	messageId?: string;
+	/** 中断信号 */
+	abort?: AbortSignalType;
+	/** 额外的上下文信息（会添加到 system prompt） */
+	additionInfo?: string;
+	/** 元数据 */
+	metadata?: Record<string, unknown>;
+	/** Agent 类型（用于选择 Behavior Spec） */
+	agentType?: string;
+	/** 使用的模型 */
+	model?: string;
+	/** 允许的工具列表（上下文级别，会覆盖 agent 配置） */
+	allowedTools?: string[];
+	/** 拒绝的工具列表（上下文级别，会覆盖 agent 配置） */
+	deniedTools?: string[];
+	/** 是否过滤 history 中的 tool 消息（上下文级别，会覆盖 agent 配置） */
+	filterHistory?: boolean;
+}
+/**
+* 服务配置接口
+*/
+interface ServiceConfig {
+	/** 环境配置 */
+	environment?: {
+		name?: string;
+		version?: string;
+	};
+	/** 组件配置映射 */
+	components?: Record<string, ComponentConfigEntry>;
+}
+/**
+* 组件配置项
+*/
+interface ComponentConfigEntry {
+	/** 配置文件路径（可选） */
+	configPath?: string;
+	/** 环境变量前缀（可选） */
+	envPrefix?: string;
+	/** 直接配置对象（可选） */
+	config?: Record<string, unknown>;
+	/** 是否启用（可选，默认 true） */
+	enabled?: boolean;
+}
+/**
+* 组件初始化选项（由 generateComponentOptions 生成）
+*/
+interface GeneratedComponentOptions {
+	/** ConfigComponent 实例 */
+	configComponent: ConfigComponent;
+	/** 配置文件路径 */
+	configPath?: string;
+	/** 环境变量前缀 */
+	envPrefix?: string;
+	/** 直接配置对象 */
+	config?: Record<string, unknown>;
+	/** 允许的其他属性 */
+	[key: string]: unknown;
+}
+/**
+* Environment 接口
+* 
+* 定义 Agent 运行时的核心能力接口。
+*/
+interface Environment {
+	/** 环境名称 */
+	readonly name: string;
+	/** 环境版本 */
+	readonly version: string;
+	/** 获取环境配置 */
+	getConfig(): EnvironmentConfig;
+	/**
+	* 注册组件
+	*/
+	registerComponent(component: Component): void;
+	/**
+	* 注销组件
+	*/
+	unregisterComponent(name: string): void;
+	/**
+	* 获取组件
+	*/
+	getComponent<T extends Component>(name: string): T | undefined;
+	/**
+	* 列出所有组件
+	*/
+	listComponents(): Component[];
+	/**
+	* 处理自然语言查询（核心入口）
+	* 
+	* @param query 用户查询文本
+	* @param context 执行上下文（可选）
+	* @returns 完整的文本响应
+	*/
+	handle_query(query: string, context?: AgentContext): Promise<string>;
+	/**
+	* 处理动作
+	*/
+	handle_action(action: Action, context: Context): Promise<ToolResult>;
+	/**
+	* 订阅 EnvEvent（返回取消订阅函数）
+	*/
+	subscribe(handler: EnvEventHandler): () => void;
+	/**
+	* 订阅指定类型事件
+	*/
+	subscribeTo(eventType: string | string[], handler: EnvEventHandler): () => void;
+	/**
+	* 订阅所有事件（通配符）
+	*/
+	subscribeAll(handler: EnvEventHandler): () => void;
+	/**
+	* 推送事件
+	* 
+	* @param event EnvEvent 或 EnvEventInput（部分属性）
+	*/
+	pushEnvEvent(event: EnvEvent | EnvEventInput): void;
+	/**
+	* 从配置文件加载服务配置
+	* 
+	* @param configPath 配置文件路径（基于 XDG_DATA_HOME）
+	* @returns 解析后的服务配置对象
+	*/
+	loadServiceConfig(configPath: string): Promise<ServiceConfig>;
+	/**
+	* 生成组件初始化选项
+	* 
+	* 根据组件配置项生成可用于初始化的选项对象。
+	* 
+	* @param componentName 组件名称
+	* @param configEntry 组件配置项
+	* @returns 生成的组件初始化选项
+	*/
+	generateComponentOptions(componentName: string, configEntry: ComponentConfigEntry): GeneratedComponentOptions;
+	/**
+	* 注册组件并用配置初始化
+	* 
+	* 便捷方法：注册组件并通过 ConfigComponent 初始化。
+	* 
+	* @param component 要注册的组件实例
+	* @param configEntry 组件配置项
+	*/
+	registerComponentWithConfig(component: Component, configEntry: ComponentConfigEntry): Promise<void>;
+	/**
+	* 从配置文件初始化整个环境
+	* 
+	* 加载服务配置，注册并初始化所有配置的组件。
+	* 
+	* @param configPath 配置文件路径（基于 XDG_DATA_HOME）
+	*/
+	initFromConfig(configPath: string): Promise<void>;
+}
+/**
+* Component 状态
+*/
+type ComponentStatus = "created" | "initializing" | "running" | "stopping" | "stopped" | "error";
+/**
+* Component 配置
+*/
+interface ComponentConfig {
+	name: string;
+	version: string;
+	enabled: boolean;
+	options?: Record<string, unknown>;
+	/**
+	* Environment 实例（可选）
+	* 
+	* 推荐在 init 时接收 env 实例，以便：
+	* - 通过 env.getComponent() 获取其他组件
+	* - 通过 env.pushEnvEvent() 发布事件
+	* - 通过 env.handle_query() 处理查询
+	* 
+	* 如果未提供，部分 Component 仍可正常工作（如测试场景）
+	* 
+	* @example
+	* ```typescript
+	* async onInit(): Promise<void> {
+	*   if (this.env) {
+	*     const configComp = this.env.getComponent("config");
+	*   }
+	* }
+	* ```
+	*/
+	env?: Environment;
+}
+/**
+* Component 路径声明
+*/
+interface ComponentPaths {
+	base: "config" | "state" | "data" | "cache";
+	subPath: string;
+	isDirectory: boolean;
+}
+/**
+* Component Schema（注册配置）
+*/
+interface ComponentSchema {
+	/** Component 名称 */
+	name: string;
+	/** 配置 Schema（Zod） */
+	schema: ZodType2<unknown, ZodTypeDef, unknown>;
+	/** 默认值（从 Schema 提取） */
+	defaults: Record<string, unknown>;
+	/** 路径声明 */
+	paths?: Record<string, ComponentPaths>;
+	/** 元信息 */
+	metadata?: {
+		description?: string;
+		version?: string;
+		author?: string;
+	};
+}
+/**
+* Component 配置变更事件
+*/
+interface ComponentConfigChangeEvent {
+	/** Component 名称 */
+	component: string;
+	/** 变更的配置键 */
+	key: string;
+	/** 旧值 */
+	oldValue: unknown;
+	/** 新值 */
+	newValue: unknown;
+	/** 是否持久化 */
+	persisted: boolean;
+	/** 时间戳 */
+	timestamp: number;
+}
+/**
+* Component 配置监听回调
+*/
+type ComponentWatchCallback = (event: ComponentConfigChangeEvent) => void | Promise<void>;
+/**
+* Component 基类接口
+*/
+interface Component {
+	/** Component 名称 */
+	readonly name: string;
+	/** Component 版本 */
+	readonly version: string;
+	/** 获取状态 */
+	getStatus(): ComponentStatus;
+	/** 获取配置 */
+	getConfig(): ComponentConfig;
+	/** 初始化 */
+	init(config: ComponentConfig): Promise<void>;
+	/** 启动 */
+	start(): Promise<void>;
+	/** 停止 */
+	stop(): Promise<void>;
+}
+/**
+* Component 基类实现
+*/
+declare abstract class BaseComponent implements Component {
+	abstract readonly name: string;
+	abstract readonly version: string;
+	protected _status: ComponentStatus;
+	protected _enabled: boolean;
+	protected env: Environment;
+	/** Hook 管理器 - 子类初始化时由构造函数设置 */
+	readonly hookManager: HookManager;
+	constructor();
+	getStatus(): ComponentStatus;
+	getConfig(): ComponentConfig;
+	/**
+	* 检查 Environment 是否已初始化
+	*/
+	protected isEnvInitialized(): boolean;
+	protected setStatus(status: ComponentStatus): void;
+	/**
+	* 获取 Environment 实例
+	*/
+	protected getEnv(): Environment;
+	init(config?: ComponentConfig): Promise<void>;
+	start(): Promise<void>;
+	stop(): Promise<void>;
+	/**
+	* 子类可覆盖的钩子方法
+	*/
+	protected onInit(): Promise<void>;
+	protected onStart(): Promise<void>;
+	protected onStop(): Promise<void>;
+	/**
+	* 注册 Hook
+	* 
+	* @param hookPoint Hook 点名称
+	* @param hook Hook 实例
+	*/
+	protected registerHook<T = unknown>(hookPoint: string, hook: Hook<T>): void;
+	/**
+	* 便捷方法：快速注册 Hook
+	*/
+	protected addHook<T = unknown>(hookPoint: string, name: string, fn: HookFn<T>, priority?: number): void;
+	/**
+	* 便捷方法：按名称取消注册 Hook
+	*/
+	protected removeHook(hookPoint: string, name: string): boolean;
+	/**
+	* 执行 Hook
+	*/
+	protected executeHooks<T = unknown>(hookPoint: string, data: T, metadata?: Record<string, unknown>): Promise<void>;
+	/**
+	* 获取 ConfigComponent 实例
+	* 
+	* 子类可使用此方法获取配置组件，支持热更新
+	*/
+	protected getConfigComponent(): {
+		get(key: string): unknown;
+	} | undefined;
+	/**
+	* 动态获取运行时配置值
+	* 
+	* 优先从 ConfigComponent 获取（支持热更新），否则返回默认值
+	* 适用于运行时可能变化的配置（如 API Keys、模型参数）
+	* 
+	* @param key 配置键（支持点号分隔的路径，如 "llm.temperature"）
+	* @param defaultValue 默认值
+	* @returns 配置值或默认值
+	* 
+	* @example
+	* ```typescript
+	* // 获取 LLM 温度配置（可能支持热更新）
+	* const temperature = this.getRuntimeConfig("llm.temperature", 0.7);
+	* 
+	* // 获取 API Key
+	* const apiKey = this.getRuntimeConfig<string>("llm.providers.openai.apiKey");
+	* ```
+	*/
+	protected getRuntimeConfig<T>(key: string, defaultValue: T): T;
+}
+/**
+* ConfigSource 类型
+*/
+type ConfigSourceType = "memory" | "file" | "env" | "remote";
+/**
+* SourceRegistration - Source 注册配置
+*/
+interface SourceRegistration {
+	/** Source 类型 */
+	type: ConfigSourceType;
+	/** 相对路径（file 类型使用，基于 XDG_DATA_HOME） */
+	relativePath?: string;
+	/** 环境变量前缀（env 类型使用） */
+	envPrefix?: string;
+	/** 优先级，默认值：memory=0, file=10, env=20 */
+	priority?: number;
+	/** 是否可选（file 类型使用，文件不存在时不报错） */
+	optional?: boolean;
+	/** 是否启用文件监听（file 类型使用，默认 true） */
+	watch?: boolean;
+}
+/**
+* KeyRegistration - 配置 Key 注册
+*/
+interface KeyRegistration {
+	/** 配置 Key（支持点号嵌套，如 "llm.provider"） */
+	key: string;
+	/** 优先使用的 Source 列表（按优先级从低到高） */
+	sources: ConfigSourceType[];
+	/** 自定义优先级（覆盖默认优先级） */
+	priority?: number;
+	/** 默认值 */
+	default?: unknown;
+}
+/**
+* ComponentRegistration - Component 注册配置
+*/
+interface ComponentRegistration {
+	/** Component 名称 */
+	name: string;
+	/** 声明需要的 Source */
+	sources: SourceRegistration[];
+	/** 声明需要的配置 Key */
+	keys: KeyRegistration[];
+	/** 配置 Schema（用于验证，可选） */
+	schema?: ZodType3<unknown, ZodTypeDef2, unknown>;
+	/** 默认值 */
+	defaults?: Record<string, unknown>;
+}
+/**
+* 配置源不存在错误
+*/
+declare class ConfigSourceNotFoundError extends Error {
+	constructor(sourceType: string, path?: string);
+}
+/**
+* 配置文件不存在错误
+*/
+declare class ConfigFileNotFoundError extends Error {
+	constructor(filePath: string);
+}
+/**
+* ConfigSource 接口
+*/
+interface ConfigSource {
+	readonly name: ConfigSourceType;
+	readonly priority: number;
+	read(key: string): unknown | undefined;
+	write?(key: string, value: unknown): boolean;
+	delete?(key: string): boolean;
+	list(): Array<{
+		key: string;
+		value: unknown;
+	}>;
+	watch?(callback: (event: ConfigChangeEvent) => void): () => void;
+}
+/**
+* Config 变更事件
+*/
+interface ConfigChangeEvent {
+	type: "change" | "add" | "delete";
+	key: string;
+	oldValue: unknown;
+	newValue: unknown;
+	source: ConfigSourceType;
+	timestamp: number;
+}
+/**
+* MemorySource 实现
+*/
+declare class MemorySource implements ConfigSource {
+	readonly name: ConfigSourceType;
+	readonly priority = 0;
+	private store;
+	private watchers;
+	read(key: string): unknown | undefined;
+	write(key: string, value: unknown): boolean;
+	delete(key: string): boolean;
+	list(): Array<{
+		key: string;
+		value: unknown;
+	}>;
+	watch(callback: (event: ConfigChangeEvent) => void): () => void;
+	private notifyWatchers;
+}
+/**
+* ConfigComponent 配置
+*/
+interface ConfigComponentOptions {
+	/** 持久化文件路径 */
+	persistFile?: string;
+	/** 防抖延迟（ms） */
+	debounceMs?: number;
+	/** 最大批量大小 */
+	maxBatchSize?: number;
+}
+/**
+* ConfigComponent
+*/
+declare class ConfigComponent extends BaseComponent {
+	readonly name = "config";
+	readonly version = "1.0.0";
+	private memorySource;
+	private sources;
+	private componentSchemas;
+	private componentPaths;
+	private watchers;
+	/** Source watch unsubscribe 函数 */
+	private sourceUnwatchFns;
+	private persistQueue;
+	private persistFile?;
+	/** Key 注册表：key -> KeyRegistration */
+	private keyRegistry;
+	/** Component 注册表：name -> ComponentRegistration */
+	private componentRegistrations;
+	/** 协议解析器 */
+	private protocolResolver?;
+	/** XDG_DATA_HOME 缓存（用于测试注入） */
+	private __xdgDataHome?;
+	/** Source 注册配置（延迟创建） */
+	private pendingSources;
+	/** Source 唯一标识缓存：type:relativePath -> true */
+	private sourceKeys;
+	/**
+	* 获取 XDG_DATA_HOME（动态获取，支持运行时覆盖）
+	*/
+	getXdgDataHome(): string;
+	/**
+	* 设置 XDG_DATA_HOME（用于测试）
+	*/
+	setXdgDataHome(path: string): void;
+	constructor(options?: ConfigComponentOptions);
+	/**
+	* 注册 Component Schema
+	*/
+	register(schema: ComponentSchema): void;
+	/**
+	* 注销 Component
+	*/
+	unregister(name: string): boolean;
+	/**
+	* 检查是否已注册
+	*/
+	isRegistered(name: string): boolean;
+	/**
+	* 列出所有注册的 Component
+	*/
+	listComponents(): string[];
+	/**
+	* 获取配置值（支持 xxx.yyy.zzz 嵌套访问）
+	* 支持两种模式：
+	* 1. 完整 key：直接查找，如 "component.key" -> 读取 "component.key"
+	* 2. 嵌套对象：查找 component 对象后从中获取属性，如 "component.nested.deep" 
+	*    -> 先找 "component.nested"，再获取其 "deep" 属性
+	*/
+	get(key: string): unknown;
+	/**
+	* 批量获取
+	*/
+	getMany(keys: string[]): Record<string, unknown>;
+	/**
+	* 设置配置值（内存级别 + 异步持久化）
+	*/
+	set(key: string, value: unknown): Promise<void>;
+	/**
+	* 批量设置
+	*/
+	setMany(config: Record<string, unknown>): Promise<void>;
+	/**
+	* 获取 Component 的路径
+	*/
+	getPath(component: string, subPath?: string): string;
+	/**
+	* 手动持久化
+	*/
+	save(key?: string): Promise<void>;
+	/**
+	* 重置到默认值
+	*/
+	reset(key: string): Promise<void>;
+	/**
+	* 监听配置变更
+	*/
+	watch(pattern: string, callback: ComponentWatchCallback): () => void;
+	/**
+	* 添加配置源
+	*/
+	addSource(source: ConfigSource): void;
+	/**
+	* 获取 Source 唯一标识
+	*/
+	private getSourceKey;
+	/**
+	* 移除配置源
+	*/
+	removeSource(name: ConfigSourceType): boolean;
+	/**
+	* 关闭所有配置源的 watcher（用于优雅退出）
+	*/
+	unwatchAll(): void;
+	/**
+	* 获取配置源列表
+	*/
+	getSources(): ConfigSource[];
+	private getNestedValue;
+	private notifyWatchers;
+	private persistToFile;
+	/**
+	* 注册配置 Source
+	* 
+	* Source 会在首次 load() 时被创建
+	* 
+	* @example
+	* config.registerSource({ type: "file", relativePath: "llm-config.jsonc" });
+	* config.registerSource({ type: "env", envPrefix: "LLM" });
+	*/
+	registerSource(registration: SourceRegistration): void;
+	/**
+	* 创建 Source 实例
+	*/
+	private createSource;
+	/**
+	* 确保所有待创建的 Source 已被创建
+	*/
+	private ensureSourcesCreated;
+	/**
+	* 注册配置 Key
+	* 
+	* @example
+	* config.registerKeys([
+	*   { key: "llm.provider", sources: ["file", "memory"], default: "openai" },
+	*   { key: "llm.model", sources: ["file"] },
+	* ]);
+	*/
+	registerKeys(keys: KeyRegistration[]): void;
+	/**
+	* 注册 Component（一次性注册 Source 和 Keys）
+	* 
+	* @example
+	* config.registerComponent({
+	*   name: "llm",
+	*   sources: [
+	*     { type: "file", relativePath: "llm-config.jsonc" },
+	*     { type: "env", envPrefix: "LLM" },
+	*   ],
+	*   keys: [
+	*     { key: "llm.provider", sources: ["file", "env", "memory"] },
+	*   ],
+	* });
+	*/
+	registerComponent(registration: ComponentRegistration): void;
+	/**
+	* 按需加载配置
+	* 
+	* 从注册的 Source 加载已注册 Keys 的配置值到内存中
+	* 
+	* @param componentName - 可选，指定要加载的 Component 名称
+	* 
+	* @example
+	* // 加载所有已注册的 Keys
+	* await config.load();
+	* 
+	* // 只加载指定 Component 的 Keys
+	* await config.load("llm");
+	*/
+	load(componentName?: string): Promise<void>;
+	/**
+	* 获取已注册的 Source 列表
+	*/
+	getRegisteredSources(): ConfigSource[];
+}
+/**
+* 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}
+*/
+type ProtocolType = "file" | "env";
+/**
+* Protocol reference structure
+*/
+interface ProtocolRef {
+	protocol: ProtocolType;
+	path: string;
+	key: string;
+	defaultValue?: string;
+	raw: string;
+}
+/**
+* Resolve result
+*/
+interface ResolveResult {
+	value: unknown;
+	source: ProtocolType;
+}
+/**
+* ProtocolResolver 配置
+*/
+interface ProtocolResolverOptions {
+	/** XDG 数据目录，默认 ~/.local/share */
+	xdgDataHome?: string;
+	/** 文件读取函数（用于测试注入） */
+	readFileFn?: (path: string) => string;
+}
+/**
+* 协议解析器
+* 
+* 解析配置中的协议引用，支持：
+* - ${file://path#key} - 从文件读取（相对路径基于 XDG_DATA_HOME）
+* - ${env://varName} - 从环境变量读取
+*/
+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;
+}
+/**
+* FileSource 配置
+*/
+interface FileSourceOptions {
+	/** 文件路径 */
+	filePath: string;
+	/** 写入防抖延迟（ms），默认 100ms */
+	debounceMs?: number;
+	/** 协议解析器（可选），用于解析 file://, env:// 协议 */
+	resolver?: ProtocolResolver;
+	/** 是否可选，文件不存在时不报错（默认 false） */
+	optional?: boolean;
+	/** 是否启用文件监听（默认 true） */
+	watch?: boolean;
+}
+/**
+* 文件配置源
+* 
+* 从 JSON 文件读取/写入配置，支持：
+* - 点号访问嵌套值（user.profile.name）
+* - 文件监听
+* - 异步批量写入
+* - 协议引用解析 (file://, env://)
+*/
+declare class FileSource implements ConfigSource {
+	readonly name: ConfigSourceType;
+	readonly priority = 10;
+	private filePath;
+	private data;
+	private watchers;
+	private watcherHandle?;
+	private debounceMs;
+	private pendingWrite?;
+	private lastFileContent;
+	private resolver?;
+	private optional;
+	private watchEnabled;
+	constructor(options: FileSourceOptions | string, resolver?: ProtocolResolver);
+	/**
+	* 同步初始化：加载文件内容
+	*/
+	private initSync;
+	/**
+	* 异步初始化
+	*/
+	private ensureInit;
+	/**
+	* 获取嵌套值
+	*/
+	private getNestedValue;
+	/**
+	* 设置嵌套值
+	*/
+	private setNestedValue;
+	/**
+	* 删除嵌套值
+	*/
+	private deleteNestedValue;
+	/**
+	* 扁平化嵌套对象为点号路径
+	*/
+	private flattenObject;
+	read(key: string): unknown | undefined;
+	readAsync(key: string): Promise<unknown | undefined>;
+	write(key: string, value: unknown): boolean;
+	private scheduleWrite;
+	private persistToFile;
+	delete(key: string): boolean;
+	list(): Array<{
+		key: string;
+		value: unknown;
+	}>;
+	listAsync(): Promise<Array<{
+		key: string;
+		value: unknown;
+	}>>;
+	watch(callback: (event: ConfigChangeEvent) => void): () => void;
+	private ensureWatch;
+	private stopWatch;
+	private reloadFromFile;
+	private notifyWatchers;
+	refresh(): Promise<void>;
+	close(): Promise<void>;
+}
+/**
+* EnvSource 配置
+*/
+interface EnvSourceOptions {
+	/** 环境变量前缀 */
+	prefix?: string;
+	/** 值转换函数 */
+	transform?: (value: string, key: string) => unknown;
+	/** 轮询间隔（ms），用于检测环境变量变化 */
+	pollInterval?: number;
+	/** 优先级 */
+	priority?: number;
+	/** 是否启用监听（轮询），默认 true */
+	watch?: boolean;
+}
+/**
+* 环境变量配置源
+* 
+* 从 process.env 读取配置，支持：
+* - 前缀过滤
+* - 值转换
+* - 环境变量监听（轮询）
+*/
+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;
+}
+/**
+* Parse JSONC (JSON with Comments) content
+* Supports single-line comments (//) and multi-line comments
+* 
+* @param content - JSONC content string
+* @returns Parsed JSON object
+*/
+declare function parseJSONC(content: string): Record<string, unknown>;
+/**
+* Substitute environment variables in a value
+* Supports ${VAR} and ${VAR:-default} syntax
+* 
+* @param value - Value to substitute (string, object, array, or primitive)
+* @returns Value with environment variables substituted
+*/
+declare function substituteEnvVars(value: unknown): unknown;
+/**
+* Parse JSONC content and substitute environment variables
+* 
+* @param content - JSONC content string
+* @returns Parsed JSON object with env vars substituted
+*/
+declare function parseJSONCWithEnv(content: string): Record<string, unknown>;
+/**
+* Substitute protocol references in a value using the provided resolver
+* 
+* Supports:
+* - ${file://path#key} - Read from file
+* - ${env://varName} - Read from environment variable
+* - All above with default values: ${protocol://...:-default}
+* 
+* @param value - Value to substitute (string, object, array, or primitive)
+* @param resolver - ProtocolResolver instance
+* @returns Value with protocol references substituted
+*/
+declare function substituteProtocolRefs(value: unknown, resolver: ProtocolResolver): unknown;
+/**
+* Parse JSONC content and substitute protocol references
+* 
+* @param content - JSONC content string
+* @param resolver - ProtocolResolver instance
+* @returns Parsed JSON object with protocol refs substituted
+*/
+declare function parseJSONCWithProtocols(content: string, resolver: ProtocolResolver): Record<string, unknown>;
+export { substituteProtocolRefs, substituteEnvVars, parseJSONCWithProtocols, parseJSONCWithEnv, parseJSONC, SourceRegistration, MemorySource, KeyRegistration, FileSourceOptions, FileSource, EnvSourceOptions, EnvSource, ConfigSourceType, ConfigSourceNotFoundError, ConfigSource, ConfigFileNotFoundError, ConfigComponentOptions, ConfigComponent, ConfigChangeEvent, ComponentRegistration };