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

package/dist/env/debug/index.js

@@ -0,0 +1,26 @@
+import {
+  DebugComponent,
+  LogReader,
+  RegexParser,
+  SpanBuilder,
+  SpanDbReader
+} from "../../shared/@ai-setting/roy-agent-core-g99pxzn5.js";
+import {
+  ReplFormatter,
+  TraceFormatter,
+  TreeFormatter
+} from "../../shared/@ai-setting/roy-agent-core-rvv6ydff.js";
+import"../../shared/@ai-setting/roy-agent-core-kkbwepqb.js";
+import"../../shared/@ai-setting/roy-agent-core-2dhd60aw.js";
+import"../../shared/@ai-setting/roy-agent-core-gjq1yk68.js";
+import"../../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";
+export {
+  TreeFormatter,
+  TraceFormatter,
+  SpanDbReader,
+  SpanBuilder,
+  ReplFormatter,
+  RegexParser,
+  LogReader,
+  DebugComponent
+};

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

@@ -0,0 +1,279 @@
+/**
+* @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 };

package/dist/env/hook/index.js

@@ -0,0 +1,29 @@
+import {
+  createHook,
+  createPriorityHook
+} from "../../shared/@ai-setting/roy-agent-core-2dhd60aw.js";
+import {
+  AgentHookPoints,
+  HookManager,
+  LLMHookPoints,
+  ToolHookPoints,
+  executeAgentHook,
+  executeAgentHookWithIntervention,
+  executeLLMHook,
+  executeToolHook,
+  globalHookManager
+} from "../../shared/@ai-setting/roy-agent-core-gjq1yk68.js";
+import"../../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";
+export {
+  globalHookManager,
+  executeToolHook,
+  executeLLMHook,
+  executeAgentHookWithIntervention,
+  executeAgentHook,
+  createPriorityHook,
+  createHook,
+  ToolHookPoints,
+  LLMHookPoints,
+  HookManager,
+  AgentHookPoints
+};