@ai-setting/roy-agent-core 1.5.17-beta.1 → 1.5.22

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

@@ -1,279 +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[];
-}
-/**
-* 创建 Hook 的工厂函数
-* 
-* @param meta Hook 元信息
-* @param fn 执行函数
-* @returns Hook 实例
-* 
-* @example
-* ```typescript
-* const hook = createHook(
-*   { name: "my-hook", priority: 10 },
-*   async (ctx) => { console.log(ctx.data); }
-* );
-* ```
-*/
-declare function createHook<T = unknown>(meta: HookMeta, fn: HookFn<T>): Hook<T>;
-/**
-* 创建带优先级的 Hook 的便捷函数
-*/
-declare function createPriorityHook<T = unknown>(name: string, fn: HookFn<T>, priority: number): Hook<T>;
-/**
-* 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;
-}
-/**
-* 全局 HookManager 实例
-* 
-* 所有 Agent/LLM/Tool hooks 都注册到这个实例
-*/
-declare const globalHookManager: unknown;
-/**
-* Agent Hook 点（新版统一命名）
-*/
-declare const AgentHookPoints: {
-	readonly BEFORE_START: "agent:before.start";
-	readonly BEFORE_LLM: "agent:before.llm";
-	readonly AFTER_LLM: "agent:after.llm";
-	readonly BEFORE_TOOL: "agent:before.tool";
-	readonly AFTER_TOOL: "agent:after.tool";
-	readonly ON_ITERATION: "agent:on.iteration";
-	readonly ON_THRESHOLD: "agent:on.threshold";
-	readonly AFTER_COMPLETE: "agent:after.complete";
-	readonly ON_ERROR: "agent:on.error";
-};
-/**
-* LLM Hook 点
-*/
-declare const LLMHookPoints: {
-	readonly BEFORE_INVOKE: "llm:before.invoke";
-	readonly AFTER_INVOKE: "llm:after.invoke";
-	readonly ON_STREAM: "llm:on.stream";
-};
-/**
-* Tool Hook 点
-*/
-declare const ToolHookPoints: {
-	readonly BEFORE_EXECUTE: "tool:before.execute";
-	readonly AFTER_EXECUTE: "tool:after.execute";
-	readonly BEFORE_REGISTER: "tool:before.register";
-	readonly AFTER_REGISTER: "tool:after.register";
-	readonly ON_ERROR: "tool:on.error";
-};
-/**
-* 执行 Agent Hook（不带干预）
-*/
-declare function executeAgentHook(hookPoint: string, data: unknown, metadata?: Record<string, unknown>): Promise<void>;
-/**
-* 执行 Agent Hook（带干预检查）
-*/
-declare function executeAgentHookWithIntervention(hookPoint: string, data: unknown, metadata?: Record<string, unknown>): Promise<HookResult>;
-/**
-* 执行 LLM Hook（不带干预）
-*/
-declare function executeLLMHook(hookPoint: string, data: unknown, metadata?: Record<string, unknown>): Promise<void>;
-/**
-* 执行 Tool Hook（不带干预）
-*/
-declare function executeToolHook(hookPoint: string, data: unknown, metadata?: Record<string, unknown>): Promise<void>;
-export { globalHookManager, executeToolHook, executeLLMHook, executeAgentHookWithIntervention, executeAgentHook, createPriorityHook, createHook, ToolHookPoints, LLMHookPoints, HookResult, HookPhase, HookMeta, HookManagerOptions, HookManager, HookFn, HookContext, HookActionType, HookAction, Hook, HookFn as BaseHookFn, HookContext as BaseHookContext, Hook as BaseHook, AgentHookPoints };