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

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

@@ -1,1652 +0,0 @@
-/**
-* @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;
-}
-/**
-* @fileoverview Debug Component Types
-* 
-* Type definitions for trace parsing, formatting, and debugging utilities.
-*/
-/**
-* Trace action type
-*/
-type TraceAction = "enter" | "quit" | "error";
-/**
-* Log level type
-*/
-type LogLevel = "debug" | "info" | "warn" | "error";
-/**
-* Trace entry representing a single log line with trace info
-*/
-interface TraceEntry {
-	/** Unique request/trace identifier */
-	traceId: string;
-	/** Timestamp of the entry (ISO format) */
-	timestamp: string;
-	/** Function/method name */
-	function: string;
-	/** Action type: enter, quit, or error */
-	action: TraceAction;
-	/** Parameters (for enter action) */
-	params?: unknown[];
-	/** Result (for quit action) */
-	result?: unknown;
-	/** Error message (for error action) */
-	error?: string;
-	/** Calculated duration in milliseconds (for quit action) */
-	durationMs?: number;
-	/** Span ID (for SQLite spans) */
-	spanId?: string;
-	/** Parent span ID (for SQLite spans) */
-	parentSpanId?: string;
-}
-/**
-* Call tree node for hierarchical trace visualization
-*/
-interface TraceTreeNode {
-	/** Unique request/trace identifier */
-	traceId: string;
-	/** Function/method name */
-	function: string;
-	/** Start timestamp */
-	startTime: string;
-	/** End timestamp (for completed nodes) */
-	endTime?: string;
-	/** Duration in milliseconds */
-	durationMs?: number;
-	/** Child nodes */
-	children: TraceTreeNode[];
-	/** Original trace entry (optional for programmatically created nodes) */
-	entry?: TraceEntry;
-	/** Span ID (for SQLite spans) */
-	spanId?: string;
-	/** Parent span ID (for SQLite spans) */
-	parentSpanId?: string;
-}
-/**
-* Options for parsing logs
-*/
-interface ParserOptions {
-	/** Log file path to read */
-	logFile?: string;
-	/** Filter by trace ID */
-	traceId?: string;
-	/** Filter by function name (supports partial match) */
-	function?: string;
-	/** Start time filter (ISO format or relative like "1h") */
-	since?: string;
-	/** End time filter (ISO format) */
-	until?: string;
-	/** Log level filter */
-	level?: LogLevel;
-}
-/**
-* Options for log discovery
-*/
-interface LogDiscoveryOptions {
-	/** Log directory to search */
-	logDir?: string;
-	/** File pattern to match */
-	pattern?: string;
-}
-/**
-* Parsed log line with extracted fields
-*/
-interface ParsedLogLine {
-	/** Original log line */
-	raw: string;
-	/** Timestamp extracted from log */
-	timestamp: string;
-	/** Log level (INFO, DEBUG, WARN, ERROR) */
-	level: string;
-	/** Source file/location */
-	source: string;
-	/** Category (traced:...) */
-	category: string;
-	/** Action symbol (>>> or <<< or !!!) */
-	action: string;
-	/** Method/function name */
-	method: string;
-	/** Action type (enter, quit, error) */
-	actionType: TraceAction;
-	/** Raw arguments string */
-	rawArgs: string;
-	/** Request ID extracted from log (if present) */
-	requestId: string | null;
-}
-/**
-* Trace ID information summary
-*/
-interface TraceIdInfo {
-	/** Trace ID */
-	traceId: string;
-	/** First occurrence timestamp */
-	firstTime: string;
-	/** Last occurrence timestamp */
-	lastTime?: string;
-	/** Number of entries for this trace */
-	count: number;
-}
-/**
-* Output format options
-*/
-interface FormatOptions {
-	/** Use pretty printing */
-	pretty?: boolean;
-	/** Maximum depth for recursive objects */
-	maxDepth?: number;
-	/** Include raw data */
-	includeRaw?: boolean;
-}
-/**
-* Trace summary for list output
-*/
-interface TraceSummary {
-	/** List of trace ID info */
-	traceIds: TraceIdInfo[];
-	/** Total count */
-	count: number;
-}
-/**
-* Formats trace entries for human-readable output
-*/
-declare class TraceFormatter {
-	/**
-	* Format a single trace entry
-	*/
-	formatEntry(entry: TraceEntry, options?: FormatOptions): string;
-	/**
-	* Indent all lines after the first one
-	*/
-	private indentMultilineContent;
-	/**
-	* Format multiple trace entries
-	*/
-	formatEntries(entries: TraceEntry[], options?: FormatOptions): string;
-	/**
-	* Format data with proper indentation for multi-line content
-	*/
-	private formatData;
-	/**
-	* Format data with pretty printing and indentation
-	*/
-	private formatPretty;
-	/**
-	* Output as JSON
-	*/
-	toJSON(entries: TraceEntry[]): string;
-	/**
-	* Generate a summary of trace entries
-	*/
-	toSummary(entries: TraceEntry[]): string;
-}
-/**
-* Options for tree formatting
-*/
-interface TreeFormatOptions {
-	/** Show duration percentage (default: true) */
-	showPercent?: boolean;
-	/** Show time bar (default: false) */
-	showTimeBar?: boolean;
-	/** Width of time bar (default: 10) */
-	barWidth?: number;
-}
-/**
-* Formats trace call trees for human-readable output
-*/
-declare class TreeFormatter {
-	private options;
-	constructor(options?: TreeFormatOptions);
-	/**
-	* Color function based on percentage
-	*/
-	private colorByPercent;
-	/**
-	* Format a single trace tree
-	*/
-	formatTree(node: TraceTreeNode): string;
-	/**
-	* Format a single node
-	*/
-	private formatNode;
-	/**
-	* Recursively format children
-	*/
-	private formatChildren;
-	/**
-	* Render a time bar showing relative duration
-	*/
-	private renderTimeBar;
-	/**
-	* Format duration in human-readable form
-	*/
-	private formatDuration;
-	/**
-	* Format multiple trace trees
-	*/
-	formatTrees(trees: TraceTreeNode[]): string;
-	/**
-	* Output as JSON
-	*/
-	toJSON(trees: TraceTreeNode[]): string;
-	/**
-	* Generate a summary table of all spans sorted by duration
-	*/
-	formatSummary(node: TraceTreeNode): string;
-	/**
-	* Format tree with timeline visualization
-	*/
-	formatTimeline(node: TraceTreeNode): string;
-	/**
-	* Build timeline visualization with absolute positioning
-	*/
-	private buildTimeline;
-}
-interface ReplContext {
-	traceId?: string;
-	function?: string;
-	limit?: number;
-}
-interface ParsedCommand {
-	command: string;
-	args: Record<string, string>;
-}
-/**
-* Formats output for REPL interface and provides command parsing
-*/
-declare class ReplFormatter {
-	private context;
-	private history;
-	/**
-	* Get welcome message for REPL
-	*/
-	getWelcomeMessage(): string;
-	/**
-	* Format prompt with current context
-	*/
-	formatPrompt(context?: Partial<ReplContext>): string;
-	/**
-	* Get help text
-	*/
-	getHelpText(): string;
-	/**
-	* Format command result
-	*/
-	formatCommandResult(command: string, data: unknown): string;
-	/**
-	* Format list command result
-	*/
-	private formatListResult;
-	/**
-	* Format trace command result
-	*/
-	private formatTraceResult;
-	/**
-	* Format tree command result
-	*/
-	private formatTreeResult;
-	/**
-	* Format a single tree node recursively
-	*/
-	private formatTreeNode;
-	/**
-	* Format JSON in compact form
-	*/
-	private formatJsonCompact;
-	/**
-	* Parse command string
-	*/
-	parseCommand(input: string): ParsedCommand;
-	/**
-	* Update context
-	*/
-	setContext(context: Partial<ReplContext>): void;
-	/**
-	* Get current context
-	*/
-	getContext(): ReplContext;
-	/**
-	* Add to history
-	*/
-	addToHistory(command: string): void;
-	/**
-	* Get history
-	*/
-	getHistory(): string[];
-}
-import { ZodType as ZodType3, ZodTypeDef as ZodTypeDef2 } 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;
-}
-import { ZodType as ZodType2, ZodTypeDef } from "zod";
-/**
-* 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?: ZodType2<unknown, ZodTypeDef, 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[];
-}
-/**
-* 服务配置接口
-*/
-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, ZodTypeDef2, 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;
-}
-/**
-* Log Reader for reading and parsing log files
-*/
-declare class LogReader {
-	private logDir;
-	constructor(options?: {
-		logDir?: string;
-	});
-	/**
-	* Get the full path to a log file
-	*/
-	getLogPath(filename?: string): string;
-	/**
-	* Find log files matching a pattern
-	* 
-	* Uses forward slashes for glob patterns to ensure cross-platform compatibility.
-	* The glob library requires forward slashes regardless of OS.
-	*/
-	findLogFiles(pattern?: string): Promise<string[]>;
-	/**
-	* Get default log directory
-	*/
-	getDefaultLogDir(): string;
-	/**
-	* Read lines from a log file with optional filtering
-	*/
-	readLines(filepath: string, options?: ParserOptions): AsyncGenerator<string>;
-	/**
-	* Extract timestamp from a log line
-	*/
-	extractTimestamp(line: string): number | null;
-	/**
-	* Parse time string to timestamp
-	* Supports ISO format and relative time like "1h", "30m"
-	*/
-	parseTime(timeStr: string): number;
-	/**
-	* Read file content directly (for small files)
-	*/
-	readFile(filepath: string): Promise<string>;
-	/**
-	* Check if a log file exists
-	*/
-	exists(filepath: string): boolean;
-}
-/**
-* Span 属性
-*/
-interface SpanAttributes {
-	[key: string]: string | number | boolean | undefined | Record<string, unknown>;
-}
-/**
-* Span
-*/
-interface Span {
-	traceId: string;
-	spanId: string;
-	parentSpanId?: string;
-	name: string;
-	kind: SpanKind;
-	status: SpanStatus;
-	startTime: number;
-	endTime?: number;
-	attributes: SpanAttributes;
-	result?: unknown;
-	error?: string;
-	children?: Span[];
-}
-/**
-* Span 类型
-*/
-declare enum SpanKind {
-	CLIENT = "client",
-	SERVER = "server",
-	INTERNAL = "internal"
-}
-/**
-* Span 状态
-*/
-declare enum SpanStatus {
-	OK = "ok",
-	ERROR = "error"
-}
-/**
-* Trace 信息
-*/
-interface TraceInfo {
-	traceId: string;
-	rootSpanName: string;
-	startTime: number;
-	endTime?: number;
-	duration?: number;
-	spanCount: number;
-	status: "ok" | "error" | "mixed";
-}
-/**
-* SpanStorage 接口
-*/
-interface SpanStorage {
-	initialize(): Promise<void>;
-	save(span: Span): void;
-	saveBatch(spans: Span[]): void;
-	findByTraceId(traceId: string): Span[];
-	findBySpanId(spanId: string): Span | undefined;
-	listTraces(limit?: number): TraceInfo[];
-	deleteByTraceId(traceId: string): void;
-	close(): void;
-}
-/**
-* Options for SpanDbReader
-*/
-interface SpanDbReaderOptions {
-	/** Database path (for file-based SQLite) */
-	dbPath?: string;
-	/** Storage instance to use directly */
-	storage?: SpanStorage;
-}
-/**
-* Span Database Reader
-* 
-* Reads span data from SQLite storage for trace debugging and analysis.
-*/
-declare class SpanDbReader {
-	private storage;
-	private dbPath;
-	private sqliteDb;
-	constructor(options?: SpanDbReaderOptions);
-	/**
-	* Initialize the reader with storage
-	*/
-	initialize(): Promise<void>;
-	/**
-	* Initialize SQLite storage directly
-	*/
-	private initSqliteStorage;
-	/**
-	* Get trace entries for a specific traceId
-	*/
-	getTraceEntries(traceId: string): Promise<TraceEntry[]>;
-	/**
-	* List all trace IDs
-	*/
-	listTraceIds(limit?: number): Promise<TraceSummary>;
-	/**
-	* Convert spans to TraceEntry format
-	* 
-	* Now properly extracts spanId and parentSpanId for tree building
-	*/
-	private spansToEntries;
-	/**
-	* Convert span attributes to params format
-	*/
-	private attributesToParams;
-	/**
-	* Get the underlying storage
-	*/
-	getStorage(): SpanStorage | null;
-	/**
-	* Close the reader and cleanup resources
-	*/
-	close(): void;
-}
-/**
-* Regex Parser for trace log lines
-*/
-declare class RegexParser {
-	/**
-	* Parse a single log line
-	*/
-	parseLogLine(line: string): ParsedLogLine | null;
-	/**
-	* Parse arguments from raw args string
-	*/
-	parseArgs(raw: string): unknown | unknown[] | null;
-	/**
-	* Check if a line is a trace line
-	*/
-	isTraceLine(line: string): boolean;
-	/**
-	* Filter lines by log level
-	*/
-	filterByLevel(lines: string[], level?: LogLevel): string[];
-	/**
-	* Filter lines by function name
-	*/
-	filterByFunction(lines: string[], functionName?: string): string[];
-	/**
-	* Extract trace ID from log line
-	* Checks for requestId in two places:
-	* 1. Category field: [source][requestId=req_123]
-	* 2. After method name: [requestId=req_abc]
-	*/
-	extractTraceId(line: string): string | null;
-	/**
-	* Extract trace IDs from multiple lines
-	*/
-	extractTraceIds(lines: string[]): Map<string, string[]>;
-	/**
-	* Parse multiple lines
-	*/
-	parseLines(lines: string[]): ParsedLogLine[];
-}
-/**
-* Paired enter/quit entries
-*/
-interface PairedSpan {
-	enter: TraceEntry;
-	quit: TraceEntry;
-	durationMs: number;
-}
-/**
-* Span Builder for constructing trace entries and call trees
-*/
-declare class SpanBuilder {
-	private parser;
-	constructor();
-	/**
-	* Build trace entries from parsed log lines
-	*/
-	buildTraceEntries(lines: ParsedLogLine[]): TraceEntry[];
-	/**
-	* Build a single trace entry from a parsed log line
-	*/
-	private buildTraceEntry;
-	/**
-	* Generate a virtual trace ID when no real traceId is present
-	* Uses function name and timestamp to create a pseudo-traceId
-	*/
-	generateVirtualTraceId(functionName: string, timestamp: string): string;
-	/**
-	* Extract trace ID from log line
-	*/
-	private extractTraceId;
-	/**
-	* Calculate duration between enter and quit entries
-	*/
-	calculateDuration(enter: TraceEntry, quit: TraceEntry): number;
-	/**
-	* Pair enter and quit entries
-	*/
-	pairEnterQuit(entries: TraceEntry[]): PairedSpan[];
-	/**
-	* Build a call tree from trace entries using call stack tracking
-	* 
-	* Enhanced to support both:
-	* 1. Traditional enter/quit pair-based tree building (from log files)
-	* 2. Parent-child hierarchy-based tree building (from SQLite spans)
-	*/
-	buildCallTree(entries: TraceEntry[]): TraceTreeNode | null;
-	/**
-	* Build call tree from parent-child span hierarchy (for SQLite spans)
-	*/
-	buildCallTreeFromHierarchy(entries: TraceEntry[]): TraceTreeNode | null;
-	/**
-	* Build call tree from traditional enter/quit pairs (for log files)
-	*/
-	buildCallTreeFromPairs(entries: TraceEntry[]): TraceTreeNode | null;
-	/**
-	* Build a tree node from a paired span
-	*/
-	private buildNodeFromPaired;
-	/**
-	* Merge entries from multiple functions into a single call tree
-	*/
-	buildMergedTree(entriesByFunction: Map<string, TraceEntry[]>): TraceTreeNode | null;
-	/**
-	* Get duration summary for entries
-	*/
-	getDurationSummary(entries: TraceEntry[]): Map<string, {
-		count: number;
-		totalMs: number;
-		avgMs: number;
-	}>;
-}
-/**
-* Data source type for trace retrieval
-*/
-type TraceDataSource = "log" | "sqlite";
-/**
-* Extended parser options with data source support
-*/
-interface TraceParserOptions extends ParserOptions {
-	/** Data source type: 'log' (default) or 'sqlite' */
-	source?: TraceDataSource;
-	/** SQLite database path (required when source is 'sqlite') */
-	dbPath?: string;
-}
-/**
-* DebugComponent configuration options
-*/
-interface DebugComponentOptions {
-	/** Log directory path */
-	logDir?: string;
-	/** Default log file */
-	defaultLogFile?: string;
-}
-/**
-* Debug Component for trace analysis and debugging
-*/
-declare class DebugComponent extends BaseComponent {
-	name: string;
-	version: string;
-	private reader;
-	private spanDbReader;
-	private parser;
-	private spanBuilder;
-	private traceFormatter;
-	private treeFormatter;
-	private options;
-	constructor(options?: DebugComponentOptions);
-	/**
-	* Initialize the span database reader
-	*/
-	initSpanDbReader(dbPath?: string): Promise<void>;
-	/**
-	* Get the span database reader
-	*/
-	getSpanDbReader(): SpanDbReader | null;
-	/**
-	* Get trace by ID from live Tracer storage
-	* 
-	* This method retrieves traces directly from the Tracer's span storage,
-	* which includes spans from the current session that may not yet be persisted
-	* to log files.
-	*/
-	getLiveTrace(traceId: string): Promise<any | null>;
-	/**
-	* List all available traces from live Tracer storage
-	*/
-	listLiveTraces(limit?: number): Promise<any>;
-	/**
-	* Format a live trace for display
-	*/
-	formatLiveTrace(traceId: string): Promise<string>;
-	/**
-	* Initialize the component
-	*/
-	init(config?: ComponentConfig): Promise<void>;
-	/**
-	* Stop the component
-	*/
-	stop(): Promise<void>;
-	/**
-	* Get traces matching the options
-	*/
-	getTraces(options?: TraceParserOptions): Promise<TraceEntry[]>;
-	/**
-	* Get traces from SQLite database
-	*/
-	private getTracesFromSqlite;
-	/**
-	* List available trace IDs
-	*/
-	listTraceIds(options?: TraceParserOptions & {
-		limit?: number;
-	}): Promise<TraceSummary>;
-	/**
-	* List trace IDs from SQLite database
-	*/
-	private listTraceIdsFromSqlite;
-	/**
-	* Get call tree for a specific trace
-	*/
-	getCallTree(options?: TraceParserOptions): Promise<TraceTreeNode | null>;
-	/**
-	* Get the log reader instance
-	*/
-	getReader(): LogReader;
-	/**
-	* Get the parser instance
-	*/
-	getParser(): RegexParser;
-	/**
-	* Get the span builder instance
-	*/
-	getSpanBuilder(): SpanBuilder;
-	/**
-	* Get the trace formatter instance
-	*/
-	getTraceFormatter(): TraceFormatter;
-	/**
-	* Get the tree formatter instance
-	*/
-	getTreeFormatter(): TreeFormatter;
-	/**
-	* Format traces for display
-	*/
-	formatTraces(entries: TraceEntry[], options?: FormatOptions): string;
-	/**
-	* Format a single trace entry
-	*/
-	formatTraceEntry(entry: TraceEntry, options?: FormatOptions): string;
-	/**
-	* Format traces as JSON
-	*/
-	tracesToJSON(entries: TraceEntry[]): string;
-	/**
-	* Format traces as summary
-	*/
-	tracesToSummary(entries: TraceEntry[]): string;
-	/**
-	* Format call tree for display
-	*/
-	formatTree(node: TraceTreeNode): string;
-	/**
-	* Format multiple call trees
-	*/
-	formatTrees(trees: TraceTreeNode[]): string;
-	/**
-	* Format trees as JSON
-	*/
-	treesToJSON(trees: TraceTreeNode[]): string;
-	/**
-	* Format tree summary (sorted by duration)
-	*/
-	formatTreeSummary(node: TraceTreeNode): string;
-	/**
-	* Format tree with timeline visualization
-	*/
-	formatTreeTimeline(node: TraceTreeNode): string;
-}
-export { TreeFormatter, TraceTreeNode, TraceSummary, TraceParserOptions, TraceIdInfo, TraceFormatter, TraceEntry, TraceDataSource, TraceAction, SpanDbReader, SpanBuilder, ReplFormatter, RegexParser, ParserOptions, ParsedLogLine, LogReader, LogLevel, LogDiscoveryOptions, FormatOptions, DebugComponent };