@ai-setting/roy-agent-core 1.0.0

package/src/env/event-source/types.ts

@@ -0,0 +1,298 @@
+/**
+ * EventSource 类型定义
+ * 
+ * 定义事件源组件的类型、接口和状态
+ */
+
+// ============================================================================
+// 类型别名
+// ============================================================================
+
+/**
+ * EventSource 状态
+ */
+export type EventSourceStatus = 
+  | "created"    // 已创建
+  | "starting"   // 启动中
+  | "running"    // 运行中
+  | "stopping"   // 停止中
+  | "stopped"    // 已停止
+  | "error";     // 错误状态
+
+/**
+ * EventSource 类型
+ */
+export type EventSourceType = 
+  | "lark-cli"        // 飞书 CLI 事件源
+  | "websocket"        // WebSocket 事件源
+  | "timer"            // 定时器事件源
+  | "http-webhook"     // 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;
+
+  // 组件生命周期（Component 接口）
+  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 function isValidEventSourceType(type: string): type is EventSourceType {
+  return ["lark-cli", "websocket", "timer", "http-webhook", "file-watcher"].includes(type);
+}
+
+/**
+ * 获取事件源类型的默认配置
+ */
+export function getDefaultConfigForType(type: EventSourceType): Partial<EventSourceConfig> {
+  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: EventSourceConfig): string[] {
+  const errors: string[] = [];
+
+  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;
+}

package/src/env/hook/global-hook-manager.ts

@@ -0,0 +1,162 @@
+/**
+ * @fileoverview Global HookManager - 全局 Hook 单例
+ * 
+ * 所有 Component 的 Hook 都注册到统一的全局实例
+ */
+
+import { HookManager } from "./hook-manager";
+import type { HookContext, HookResult } from "./types";
+
+// ========================================================================
+// 全局单例
+// ========================================================================
+
+/**
+ * 全局 HookManager 实例
+ * 
+ * 所有 Agent/LLM/Tool hooks 都注册到这个实例
+ */
+export const globalHookManager = new HookManager<unknown>();
+
+// ========================================================================
+// 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",
+} as const;
+
+/**
+ * LLM Hook 点
+ */
+export const LLMHookPoints = {
+  BEFORE_INVOKE: "llm:before.invoke",
+  AFTER_INVOKE: "llm:after.invoke",
+  ON_STREAM: "llm:on.stream",
+} as const;
+
+/**
+ * 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",
+} as const;
+
+// ========================================================================
+// 旧版 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",
+} as const;
+
+// ========================================================================
+// 别名注册表（用于自动注册别名）
+// ========================================================================
+
+const hookPointAliases: Record<string, string> = {
+  // 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(): void {
+  // 监听 hooks 的注册，自动创建别名
+  const originalRegister = globalHookManager.register.bind(globalHookManager);
+  
+  globalHookManager.register = function(hookPoint: string, hook: any): void {
+    // 调用原始注册
+    originalRegister(hookPoint, hook);
+    
+    // 如果有别名，也注册到别名点
+    const alias = hookPointAliases[hookPoint];
+    if (alias) {
+      originalRegister(alias, hook);
+    }
+  };
+}
+
+// 在模块加载时设置别名
+setupAliasHooks();
+
+// ========================================================================
+// 便捷执行方法
+// ========================================================================
+
+/**
+ * 执行 Agent Hook（不带干预）
+ */
+export async function executeAgentHook(
+  hookPoint: string,
+  data: unknown,
+  metadata: Record<string, unknown> = {}
+): Promise<void> {
+  await globalHookManager.execute(hookPoint, data, metadata);
+}
+
+/**
+ * 执行 Agent Hook（带干预检查）
+ */
+export async function executeAgentHookWithIntervention(
+  hookPoint: string,
+  data: unknown,
+  metadata: Record<string, unknown> = {}
+): Promise<HookResult> {
+  return globalHookManager.executeWithIntervention(hookPoint, data, metadata);
+}
+
+/**
+ * 执行 LLM Hook（不带干预）
+ */
+export async function executeLLMHook(
+  hookPoint: string,
+  data: unknown,
+  metadata: Record<string, unknown> = {}
+): Promise<void> {
+  await globalHookManager.execute(hookPoint, data, metadata);
+}
+
+/**
+ * 执行 Tool Hook（不带干预）
+ */
+export async function executeToolHook(
+  hookPoint: string,
+  data: unknown,
+  metadata: Record<string, unknown> = {}
+): Promise<void> {
+  await globalHookManager.execute(hookPoint, data, metadata);
+}