@ai-setting/roy-agent-core 1.5.5 → 1.5.7

package/dist/env/mcp/index.d.ts

@@ -0,0 +1,1331 @@
+/**
+* @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 { z } from "zod";
+/**
+* Local MCP Server 配置（stdio 传输）
+*/
+declare const McpServerLocalConfigSchema: unknown;
+type McpServerLocalConfig = z.infer<typeof McpServerLocalConfigSchema>;
+/**
+* Remote MCP Server 配置（HTTP 传输）
+*/
+declare const McpServerRemoteConfigSchema: unknown;
+type McpServerRemoteConfig = z.infer<typeof McpServerRemoteConfigSchema>;
+/**
+* MCP Server 配置（联合类型）
+*/
+declare const McpServerConfigSchema: unknown;
+type McpServerConfig = z.infer<typeof McpServerConfigSchema>;
+/**
+* 扫描发现的 MCP 服务器信息
+*/
+interface DiscoveredMcpServer {
+	/** 服务器名称（目录名） */
+	name: string;
+	/** 入口脚本路径 */
+	entryPath?: string;
+	/** 配置文件路径 */
+	configPath?: string;
+	/** package.json 路径 */
+	packagePath?: string;
+	/** 目录中的配置 */
+	directoryConfig?: Record<string, unknown>;
+	/** 解析后的默认命令（兼容不同路径） */
+	defaultCommand?: string[];
+}
+/**
+* MCP 服务器状态
+*/
+interface McpServerStatus {
+	/** 服务器名称 */
+	name: string;
+	/** 连接状态 */
+	status: "connecting" | "connected" | "disconnected" | "error";
+	/** 错误信息 */
+	error?: string;
+	/** 工具数量 */
+	toolsCount?: number;
+}
+import { z as z3 } from "zod";
+import { ZodType as ZodType4, ZodTypeDef as ZodTypeDef2 } from "zod";
+import { ZodType as ZodType3, 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>;
+}
+import { z as z2, ZodType as ZodType2, ZodError } from "zod";
+/**
+* 沙箱配置
+*/
+interface SandboxConfig {
+	/** 是否启用沙箱 */
+	enabled: boolean;
+	/** 沙箱类型 */
+	type: "native" | "docker";
+	/** 动作过滤 */
+	actionFilter?: {
+		/** 包含的动作 */
+		include?: string[];
+		/** 排除的动作 */
+		exclude?: string[];
+	};
+	/** 文件系统限制 */
+	filesystem?: {
+		/** 允许读取 */
+		allowRead?: string[];
+		/** 禁止读取 */
+		denyRead?: string[];
+		/** 允许写入 */
+		allowWrite?: string[];
+		/** 禁止写入 */
+		denyWrite?: string[];
+	};
+	/** 网络限制 */
+	network?: {
+		/** 允许的域名 */
+		allowedDomains?: string[];
+		/** 禁止的域名 */
+		deniedDomains?: string[];
+	};
+	/** Docker 配置 */
+	docker?: {
+		/** 镜像 */
+		image?: string;
+		/** 网络模式 */
+		networkMode?: "bridge" | "host" | "none";
+		/** 卷挂载 */
+		volumes?: Record<string, string>;
+	};
+}
+/**
+* 工具执行上下文
+*/
+interface ToolContext {
+	/** 工作目录 */
+	workdir?: string;
+	/** 用户 ID */
+	user_id?: string;
+	/** 会话 ID */
+	session_id?: string;
+	/** 消息 ID */
+	message_id?: string;
+	/** 中断信号 */
+	abort?: AbortSignal;
+	/** 额外元数据 */
+	metadata?: Record<string, unknown>;
+	/** 沙箱配置 */
+	sandbox?: SandboxConfig;
+	/** 沙箱 Provider */
+	sandboxProvider?: unknown | null;
+}
+/**
+* 工具结果元数据
+*/
+interface ToolResultMetadata {
+	/** 执行时间（毫秒） */
+	execution_time_ms: number;
+	/** 输出大小（字节） */
+	output_size?: number;
+	/** 标准输出 */
+	stdout?: string;
+	/** 标准错误 */
+	stderr?: string;
+	/** 退出码 */
+	exit_code?: number;
+	/** Token 使用量 */
+	usage?: {
+		inputTokens: number;
+		outputTokens: number;
+		totalTokens?: number;
+	};
+	/** 额外元数据 */
+	[key: string]: unknown;
+}
+/**
+* 工具执行结果
+*/
+interface ToolResult2 {
+	/** 是否成功 */
+	success: boolean;
+	/** 输出内容 */
+	output: string | Record<string, unknown>;
+	/** 错误信息 */
+	error?: string;
+	/** 结果元数据 */
+	metadata?: ToolResultMetadata;
+}
+/**
+* 工具元数据
+*/
+interface ToolMetadata {
+	/** 分类 */
+	category?: string;
+	/** 标签 */
+	tags?: string[];
+	/** 版本 */
+	version?: string;
+	/** 作者 */
+	author?: string;
+	/** 是否实验性 */
+	experimental?: boolean;
+	/** MCP 工具信息（MCP adapter 使用） */
+	mcpTool?: {
+		originalName: string;
+		originalDescription: string;
+		inputSchema?: unknown;
+	};
+}
+/**
+* 工具沙箱配置
+*/
+interface ToolSandboxConfig {
+	/** 是否启用沙箱 */
+	enabled: boolean;
+	/** 沙箱配置 */
+	config?: Partial<SandboxConfig>;
+}
+/**
+* 工具权限配置
+*/
+interface ToolPermissionConfig {
+	/** 是否需要用户确认 */
+	requireConfirmation?: boolean;
+	/** 权限级别 */
+	level?: "safe" | "dangerous" | "critical";
+}
+/**
+* 工具信息
+*/
+interface ToolInfo<Parameters extends ZodType2 = ZodType2> {
+	/** 工具名称 */
+	name: string;
+	/** 工具描述 */
+	description: string;
+	/** 参数 Schema */
+	parameters: Parameters;
+	/** 初始化函数（可选） */
+	init?: (ctx?: ToolContext) => Promise<void>;
+	/** 执行函数 */
+	execute: (args: z2.infer<Parameters>, ctx: ToolContext) => Promise<ToolResult2>;
+	/** 参数验证错误格式化（可选） */
+	formatValidationError?: (error: ZodError) => string;
+	/** 沙箱配置 */
+	sandbox?: ToolSandboxConfig;
+	/** 权限配置 */
+	permission?: ToolPermissionConfig;
+	/** 工具元数据 */
+	metadata?: ToolMetadata;
+}
+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: ZodType3<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?: ZodType4<unknown, ZodTypeDef2, unknown>;
+	/** 默认值 */
+	defaults?: Record<string, unknown>;
+}
+/**
+* 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;
+}
+/**
+* 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[];
+}
+/**
+* MCP 路径配置
+*/
+interface McpPath {
+	/** 来源类型 */
+	type: "user" | "project" | "custom";
+	/** 路径 */
+	path: string;
+}
+/**
+* McpComponent 配置
+*/
+interface McpComponentConfig {
+	/** 扫描路径列表 */
+	mcpPaths: McpPath[];
+	/** 显式配置的服务器 */
+	servers?: Record<string, z3.infer<typeof McpServerConfigSchema>>;
+	/** 默认超时（毫秒） */
+	timeout?: number;
+	/** 是否启用 */
+	enabled?: boolean;
+}
+/**
+* McpComponentOptions（通过 options 传递）
+*/
+interface McpComponentOptions {
+	/** ConfigComponent 实例（必填） */
+	configComponent: ConfigComponent;
+	/** 配置文件相对路径 */
+	configPath?: string;
+	/** 环境变量前缀 */
+	envPrefix?: string;
+	/** 直接传入的配置对象（最高优先级） */
+	config?: Partial<McpComponentConfig>;
+}
+/**
+* 默认 MCP 配置
+*/
+declare const DEFAULT_MCP_CONFIG: McpComponentConfig;
+/**
+* 配置 Key 列表（用于 ConfigComponent 注册）
+*/
+declare const MCP_CONFIG_KEYS: readonly ["mcp.enabled", "mcp.timeout", "mcp.mcpPaths", "mcp.servers"];
+/**
+* 获取路径优先级
+*/
+declare function getMcpPathPriority(type: string): number;
+/**
+* McpComponent
+* 
+* MCP 客户端管理组件
+* 
+* 功能：
+* 1. 配置管理（支持 file/env/object 三层配置）
+* 2. 扫描 MCP 服务器
+* 3. 连接/断开 MCP 服务器
+* 4. 注册 MCP tools 到 ToolComponent
+*/
+declare class McpComponent extends BaseComponent {
+	readonly name = "mcp";
+	readonly version = "1.0.0";
+	private config;
+	private toolComponent?;
+	private configComponent?;
+	private scanner?;
+	private loader?;
+	private serverStatus;
+	private registeredTools;
+	constructor();
+	init(config?: ComponentConfig): Promise<void>;
+	start(): Promise<void>;
+	stop(): Promise<void>;
+	private registerConfig;
+	private flattenConfig;
+	private loadServers;
+	private registerServerTools;
+	/**
+	* 获取服务器状态
+	*/
+	getServerStatus(name: string): McpServerStatus | undefined;
+	/**
+	* 列出所有服务器
+	*/
+	listServers(): McpServerStatus[];
+	/**
+	* 列出所有 MCP 工具
+	*/
+	listTools(): ToolInfo[];
+	/**
+	* 重新加载所有服务器
+	*/
+	reload(): Promise<void>;
+}
+/**
+* MCP 服务器扫描器
+* 
+* 扫描多个路径下的 MCP 服务器子目录
+*/
+declare class McpScanner {
+	private mcpPaths;
+	private serversMap;
+	constructor(mcpPaths: McpPath[]);
+	/**
+	* 扫描所有 mcpPaths
+	*/
+	scan(): Promise<Map<string, DiscoveredMcpServer>>;
+	/**
+	* 扫描单个路径
+	*/
+	private scanPath;
+	/**
+	* 发现单个 MCP 服务器
+	*/
+	private discoverServer;
+	/**
+	* 查找入口脚本
+	*/
+	private findEntryScript;
+	/**
+	* 获取扫描结果
+	*/
+	getServers(): Map<string, DiscoveredMcpServer>;
+}
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+/**
+* MCP 客户端条目
+*/
+interface McpClientEntry {
+	name: string;
+	client: Client;
+	transport: StdioClientTransport | StreamableHTTPClientTransport;
+	config: McpServerConfig;
+}
+/**
+* MCP 服务器加载器
+* 
+* 负责：
+* 1. 构建默认配置
+* 2. 合并显式配置
+* 3. 连接/断开 MCP 服务器
+*/
+declare class McpLoader {
+	private clients;
+	private defaultTimeout;
+	constructor(defaultTimeout?: number);
+	/**
+	* 构建默认配置（从扫描结果）
+	* 
+	* @param server - 扫描发现的 MCP 服务器信息
+	* @returns MCP 服务器配置
+	*/
+	buildDefaultConfig(server: DiscoveredMcpServer): McpServerConfig;
+	/**
+	* 合并配置（显式配置覆盖默认配置）
+	*/
+	mergeConfig(defaultConfig: McpServerConfig, explicitConfig?: Partial<McpServerConfig>): McpServerConfig;
+	/**
+	* 连接到 MCP 服务器
+	*/
+	connect(name: string, config: McpServerConfig): Promise<McpClientEntry>;
+	/**
+	* 断开连接
+	*/
+	disconnect(name: string): Promise<void>;
+	/**
+	* 断开所有连接
+	*/
+	disconnectAll(): Promise<void>;
+	/**
+	* 获取客户端
+	*/
+	getClient(name: string): McpClientEntry | undefined;
+	/**
+	* 获取所有客户端
+	*/
+	getAllClients(): Map<string, McpClientEntry>;
+	/**
+	* 检查是否已连接
+	*/
+	isConnected(name: string): boolean;
+}
+import { z as z4 } from "zod";
+import { Tool as McpTool } from "@modelcontextprotocol/sdk/types.js";
+import { Client as Client2 } from "@modelcontextprotocol/sdk/client/index.js";
+/**
+* 将 MCP 工具转换为 Environment Tool
+*
+* 命名策略: mcp_{serverName}_{toolName}
+*/
+declare function adaptMcpTool(mcpTool: McpTool, mcpClient: Client2, serverName: string): ToolInfo;
+/**
+* 转换 MCP inputSchema 为 Zod schema
+*
+* 关键：保留参数描述，让 LLM 知道每个参数的用途
+*/
+declare function convertInputSchemaToZod(inputSchema: McpTool["inputSchema"]): z4.ZodType<unknown>;
+/**
+* 创建 MCP 工具描述
+*/
+declare function createMcpToolsDescription(tools: ToolInfo[]): string;
+export { getMcpPathPriority, createMcpToolsDescription, convertInputSchemaToZod, adaptMcpTool, McpServerStatus, McpServerRemoteConfigSchema, McpServerRemoteConfig, McpServerLocalConfigSchema, McpServerLocalConfig, McpServerConfigSchema, McpServerConfig, McpScanner, McpPath, McpLoader, McpComponentOptions, McpComponentConfig, McpComponent, McpClientEntry, MCP_CONFIG_KEYS, DiscoveredMcpServer, DEFAULT_MCP_CONFIG };