@ai-setting/roy-agent-cli 1.3.14 → 1.3.16

package/dist/core/src/env/event-source/types.d.ts

@@ -0,0 +1,213 @@
+/**
+ * EventSource 类型定义
+ *
+ * 定义事件源组件的类型、接口和状态
+ */
+/**
+ * EventSource 状态
+ */
+export type EventSourceStatus = "created" | "starting" | "running" | "stopping" | "stopped" | "error";
+/**
+ * EventSource 类型
+ */
+export type EventSourceType = "lark-cli" | "websocket" | "timer" | "http-webhook" | "file-watcher";
+/**
+ * EventSource 配置
+ */
+export interface EventSourceConfig {
+    /** 事件源 ID */
+    id: string;
+    /** 事件源名称 */
+    name: string;
+    /** 事件源类型 */
+    type: EventSourceType;
+    /** 是否启用 */
+    enabled: boolean;
+    /** 事件类型过滤（支持通配符） */
+    eventTypes?: string[];
+    /** 轮询间隔（毫秒，定时器用） */
+    interval?: number;
+    /** cron 表达式（定时器用） */
+    cron?: string;
+    /** 命令参数（lark-cli 用） */
+    command?: string;
+    /** WebSocket URL */
+    url?: string;
+    /** WebSocket headers */
+    headers?: Record<string, string>;
+    /** 自定义选项 */
+    options?: Record<string, unknown>;
+}
+/**
+ * 事件元信息
+ *
+ * 包含帮助 Agent 决策和回复的关键信息
+ */
+export interface EventMetadata {
+    /** 事件类型，如 im.message.receive_v1 */
+    eventType?: string;
+    /** 应用 ID */
+    appId?: string;
+    /** 会话 ID */
+    chatId?: string;
+    /** 会话类型，如 p2p, group */
+    chatType?: string;
+    /** 消息 ID */
+    messageId?: string;
+    /** 消息类型，如 text, image */
+    messageType?: string;
+    /** 发送者 ID */
+    senderId?: string;
+    /** 租户 key */
+    tenantKey?: string;
+    /** 其他原始字段 */
+    [key: string]: unknown;
+}
+/**
+ * 推荐动作
+ *
+ * 告诉 Agent 应该如何处理这个事件
+ */
+export interface RecommendedAction {
+    /** 动作描述 */
+    action: string;
+    /** 回复目标（如果有） */
+    replyTo?: {
+        appId?: string;
+        chatId?: string;
+        messageId?: string;
+    };
+    /** 原始回复指令（用于调用事件源 API） */
+    rawCommand?: string;
+}
+/**
+ * 反馈通道
+ *
+ * 告诉 Agent 处理完事件后，如何将结果反馈到事件源
+ */
+export interface ReplyChannel {
+    /** 渠道类型，如 lark-cli, websocket */
+    type: string;
+    /** 发送目标的 app ID */
+    appId?: string;
+    /** 发送目标的会话 ID */
+    chatId?: string;
+    /** 原始消息 ID（用于回复） */
+    messageId?: string;
+    /** 原始回复指令 */
+    rawCommand?: string;
+    /** 其他自定义参数 */
+    params?: Record<string, unknown>;
+}
+/**
+ * EventSource 事件负载
+ */
+export interface EventSourceEventPayload {
+    /** 事件源 ID */
+    sourceId: string;
+    /** 事件源类型 */
+    sourceType: EventSourceType;
+    /** 原始事件数据 */
+    rawEvent: unknown;
+    /** 处理后的消息内容 */
+    message: string;
+    /** 事件元信息（帮助 Agent 决策） */
+    metadata: EventMetadata;
+    /** 反馈通道：处理完成后如何将结果返回到事件源 */
+    replyChannel?: ReplyChannel;
+    /** 推荐动作 */
+    recommendedAction?: RecommendedAction;
+    /** 时间戳 */
+    timestamp: number;
+}
+/**
+ * EventSource 事件
+ */
+export interface EventSourceEvent {
+    /** 事件源 ID */
+    sourceId: string;
+    /** 事件类型 */
+    type: string;
+    /** 时间戳 */
+    timestamp: number;
+    /** 事件负载 */
+    payload: EventSourceEventPayload;
+}
+/**
+ * EventSource 事件处理器
+ */
+export type EventSourceEventHandler = (event: EventSourceEvent) => string | undefined | void | Promise<void | string>;
+/**
+ * EventSource 状态变更事件
+ */
+export interface EventSourceStatusChangeEvent {
+    /** 事件源 ID */
+    sourceId: string;
+    /** 事件源类型 */
+    sourceType: EventSourceType;
+    /** 旧状态 */
+    oldStatus: EventSourceStatus;
+    /** 新状态 */
+    newStatus: EventSourceStatus;
+    /** 错误信息（如果有） */
+    error?: string;
+}
+/**
+ * EventSource 持久化配置
+ */
+export interface EventSourcePersistenceConfig {
+    /** 版本 */
+    version: string;
+    /** 事件源列表 */
+    sources: EventSourceConfig[];
+}
+/**
+ * EventSourceComponent 接口
+ *
+ * 定义事件源组件的公共方法
+ */
+export interface EventSourceComponentInterface {
+    /** 组件名称 */
+    readonly name: string;
+    /** 组件版本 */
+    readonly version: string;
+    init(config?: unknown): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getStatus(): unknown;
+    register(config: EventSourceConfig): void;
+    unregister(id: string): boolean;
+    get(id: string): EventSourceConfig | undefined;
+    list(): EventSourceConfig[];
+    getStatus(id: string): EventSourceStatus | undefined;
+    startSource(id: string): Promise<void>;
+    stopSource(id: string): Promise<void>;
+    onEvent(id: string, handler: EventSourceEventHandler): void;
+    offEvent(id: string): void;
+}
+/**
+ * EventSourceAgentHandler 配置
+ */
+export interface EventSourceAgentHandlerConfig {
+    /** 是否启用 */
+    enabled?: boolean;
+    /** 前缀（用于区分事件消息） */
+    prefix?: string;
+    /** 是否包含原始事件 */
+    includeRawEvent?: boolean;
+    /** 是否包含时间戳 */
+    includeTimestamp?: boolean;
+}
+/**
+ * 检查是否为有效的事件源类型
+ */
+export declare function isValidEventSourceType(type: string): type is EventSourceType;
+/**
+ * 获取事件源类型的默认配置
+ */
+export declare function getDefaultConfigForType(type: EventSourceType): Partial<EventSourceConfig>;
+/**
+ * 验证事件源配置
+ */
+export declare function validateEventSourceConfig(config: EventSourceConfig): string[];
+//# sourceMappingURL=types.d.ts.map

package/dist/core/src/env/event-source/types.js

@@ -0,0 +1,57 @@
+/**
+ * EventSource 类型定义
+ *
+ * 定义事件源组件的类型、接口和状态
+ */
+// ============================================================================
+// 辅助函数
+// ============================================================================
+/**
+ * 检查是否为有效的事件源类型
+ */
+export function isValidEventSourceType(type) {
+    return ["lark-cli", "websocket", "timer", "http-webhook", "file-watcher"].includes(type);
+}
+/**
+ * 获取事件源类型的默认配置
+ */
+export function getDefaultConfigForType(type) {
+    switch (type) {
+        case "timer":
+            return { interval: 60000 }; // 默认 1 分钟
+        case "lark-cli":
+            return { command: "lark-cli event +subscribe" };
+        case "websocket":
+            return {};
+        default:
+            return {};
+    }
+}
+/**
+ * 验证事件源配置
+ */
+export function validateEventSourceConfig(config) {
+    const errors = [];
+    if (!config.id) {
+        errors.push("EventSource ID is required");
+    }
+    if (!config.name) {
+        errors.push("EventSource name is required");
+    }
+    if (!isValidEventSourceType(config.type)) {
+        errors.push(`Invalid EventSource type: ${config.type}`);
+    }
+    if (config.type === "timer") {
+        if (!config.interval || config.interval <= 0) {
+            errors.push("Timer interval must be a positive number");
+        }
+    }
+    if (config.type === "lark-cli" && !config.command) {
+        errors.push("lark-cli command is required");
+    }
+    if (config.type === "websocket" && !config.url) {
+        errors.push("WebSocket URL is required");
+    }
+    return errors;
+}
+//# sourceMappingURL=types.js.map

package/dist/core/src/env/hook/global-hook-manager.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview Global HookManager - 全局 Hook 单例
+ *
+ * 所有 Component 的 Hook 都注册到统一的全局实例
+ */
+import { HookManager } from "./hook-manager";
+import type { HookResult } from "./types";
+/**
+ * 全局 HookManager 实例
+ *
+ * 所有 Agent/LLM/Tool hooks 都注册到这个实例
+ */
+export declare const globalHookManager: HookManager<unknown>;
+/**
+ * Agent Hook 点（新版统一命名）
+ */
+export 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 点
+ */
+export declare const LLMHookPoints: {
+    readonly BEFORE_INVOKE: "llm:before.invoke";
+    readonly AFTER_INVOKE: "llm:after.invoke";
+    readonly ON_STREAM: "llm:on.stream";
+};
+/**
+ * Tool Hook 点
+ */
+export 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";
+};
+/**
+ * 旧版 Tool Hook 点别名映射（向后兼容）
+ */
+export declare const LegacyToolHookPoints: {
+    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";
+    readonly BEFORE_TOOL: "before.tool";
+    readonly AFTER_TOOL: "after.tool";
+};
+/**
+ * 执行 Agent Hook（不带干预）
+ */
+export declare function executeAgentHook(hookPoint: string, data: unknown, metadata?: Record<string, unknown>): Promise<void>;
+/**
+ * 执行 Agent Hook（带干预检查）
+ */
+export declare function executeAgentHookWithIntervention(hookPoint: string, data: unknown, metadata?: Record<string, unknown>): Promise<HookResult>;
+/**
+ * 执行 LLM Hook（不带干预）
+ */
+export declare function executeLLMHook(hookPoint: string, data: unknown, metadata?: Record<string, unknown>): Promise<void>;
+/**
+ * 执行 Tool Hook（不带干预）
+ */
+export declare function executeToolHook(hookPoint: string, data: unknown, metadata?: Record<string, unknown>): Promise<void>;
+//# sourceMappingURL=global-hook-manager.d.ts.map

package/dist/core/src/env/hook/global-hook-manager.js

@@ -0,0 +1,126 @@
+/**
+ * @fileoverview Global HookManager - 全局 Hook 单例
+ *
+ * 所有 Component 的 Hook 都注册到统一的全局实例
+ */
+import { HookManager } from "./hook-manager.js";
+// ========================================================================
+// 全局单例
+// ========================================================================
+/**
+ * 全局 HookManager 实例
+ *
+ * 所有 Agent/LLM/Tool hooks 都注册到这个实例
+ */
+export const globalHookManager = new HookManager();
+// ========================================================================
+// Hook 点命名规范
+// ========================================================================
+/**
+ * Agent Hook 点（新版统一命名）
+ */
+export const AgentHookPoints = {
+    BEFORE_START: "agent:before.start",
+    BEFORE_LLM: "agent:before.llm",
+    AFTER_LLM: "agent:after.llm",
+    BEFORE_TOOL: "agent:before.tool",
+    AFTER_TOOL: "agent:after.tool",
+    ON_ITERATION: "agent:on.iteration",
+    ON_THRESHOLD: "agent:on.threshold",
+    AFTER_COMPLETE: "agent:after.complete",
+    ON_ERROR: "agent:on.error",
+};
+/**
+ * LLM Hook 点
+ */
+export const LLMHookPoints = {
+    BEFORE_INVOKE: "llm:before.invoke",
+    AFTER_INVOKE: "llm:after.invoke",
+    ON_STREAM: "llm:on.stream",
+};
+/**
+ * Tool Hook 点
+ */
+export const ToolHookPoints = {
+    BEFORE_EXECUTE: "tool:before.execute",
+    AFTER_EXECUTE: "tool:after.execute",
+    BEFORE_REGISTER: "tool:before.register",
+    AFTER_REGISTER: "tool:after.register",
+    ON_ERROR: "tool:on.error",
+};
+// ========================================================================
+// 旧版 Hook 点别名（兼容）
+// ========================================================================
+/**
+ * 旧版 Tool Hook 点别名映射（向后兼容）
+ */
+export const LegacyToolHookPoints = {
+    BEFORE_EXECUTE: "tool:before.execute",
+    AFTER_EXECUTE: "tool:after.execute",
+    BEFORE_REGISTER: "tool:before.register",
+    AFTER_REGISTER: "tool:after.register",
+    ON_ERROR: "tool:on.error",
+    // 旧版别名
+    BEFORE_TOOL: "before.tool",
+    AFTER_TOOL: "after.tool",
+};
+// ========================================================================
+// 别名注册表（用于自动注册别名）
+// ========================================================================
+const hookPointAliases = {
+    // Tool hooks 别名映射
+    "before.tool": "tool:before.execute",
+    "after.tool": "tool:after.execute",
+    // LLM hooks 别名映射
+    "llm.before-invoke": "llm:before.invoke",
+    "llm.after-invoke": "llm:after.invoke",
+    "llm.stream": "llm:on.stream",
+};
+/**
+ * 初始化别名 HookManager
+ *
+ * 将所有注册到旧版 hook 点的 hooks 自动复制到新版 hook 点
+ */
+function setupAliasHooks() {
+    // 监听 hooks 的注册，自动创建别名
+    const originalRegister = globalHookManager.register.bind(globalHookManager);
+    globalHookManager.register = function (hookPoint, hook) {
+        // 调用原始注册
+        originalRegister(hookPoint, hook);
+        // 如果有别名，也注册到别名点
+        const alias = hookPointAliases[hookPoint];
+        if (alias) {
+            originalRegister(alias, hook);
+        }
+    };
+}
+// 在模块加载时设置别名
+setupAliasHooks();
+// ========================================================================
+// 便捷执行方法
+// ========================================================================
+/**
+ * 执行 Agent Hook（不带干预）
+ */
+export async function executeAgentHook(hookPoint, data, metadata = {}) {
+    await globalHookManager.execute(hookPoint, data, metadata);
+}
+/**
+ * 执行 Agent Hook（带干预检查）
+ */
+export async function executeAgentHookWithIntervention(hookPoint, data, metadata = {}) {
+    return globalHookManager.executeWithIntervention(hookPoint, data, metadata);
+}
+/**
+ * 执行 LLM Hook（不带干预）
+ */
+export async function executeLLMHook(hookPoint, data, metadata = {}) {
+    await globalHookManager.execute(hookPoint, data, metadata);
+}
+/**
+ * 执行 Tool Hook（不带干预）
+ */
+export async function executeToolHook(hookPoint, data, metadata = {}) {
+    await globalHookManager.execute(hookPoint, data, metadata);
+}
+//# sourceMappingURL=global-hook-manager.js.map

package/dist/core/src/env/hook/hook-manager.d.ts

@@ -0,0 +1,133 @@
+/**
+ * @fileoverview Hook Manager - 统一管理 Component 的 Hook
+ *
+ * 提供：
+ * - Hook 注册和管理
+ * - 按优先级排序执行
+ * - 错误隔离
+ * - 动态添加/移除
+ * - 干预机制（executeWithIntervention）
+ */
+import type { Hook, HookResult } from "./types";
+/**
+ * HookManager 配置
+ */
+export 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);
+ * ```
+ */
+export 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;
+}
+//# sourceMappingURL=hook-manager.d.ts.map