@ai-setting/roy-agent-core 1.0.0

package/src/env/errors.test.ts

@@ -0,0 +1,165 @@
+import { describe, test, expect } from "bun:test";
+import { 
+  AgentError, 
+  ToolError, 
+  LLMError, 
+  ComponentError,
+  ContextError,
+  ErrorCodes,
+  isRoyError,
+  getErrorCode 
+} from "./errors";
+
+describe("错误类型体系", () => {
+  
+  describe("AgentError", () => {
+    test("应该包含 code 和 details 属性", () => {
+      const error = new AgentError(
+        "Agent not found",
+        ErrorCodes.AGENT_NOT_FOUND,
+        { agentName: "test-agent" }
+      );
+      
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(AgentError);
+      expect(error.name).toBe("AgentError");
+      expect(error.message).toBe("Agent not found");
+      expect(error.code).toBe("AGENT_001");
+      expect(error.details).toEqual({ agentName: "test-agent" });
+    });
+    
+    test("应该支持不传 details", () => {
+      const error = new AgentError("Test error", ErrorCodes.AGENT_RUN_FAILED);
+      expect(error.details).toBeUndefined();
+    });
+  });
+  
+  describe("ToolError", () => {
+    test("应该包含 code 和 toolName 属性", () => {
+      const error = new ToolError(
+        "Tool execution failed",
+        ErrorCodes.TOOL_EXECUTION_FAILED,
+        "readFile"
+      );
+      
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(ToolError);
+      expect(error.name).toBe("ToolError");
+      expect(error.code).toBe("TOOL_003");
+      expect(error.toolName).toBe("readFile");
+    });
+  });
+  
+  describe("LLMError", () => {
+    test("应该包含 code 和 provider 属性", () => {
+      const error = new LLMError(
+        "LLM invocation failed",
+        ErrorCodes.LLM_INVOCATION_FAILED,
+        "openai"
+      );
+      
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(LLMError);
+      expect(error.name).toBe("LLMError");
+      expect(error.code).toBe("LLM_002");
+      expect(error.provider).toBe("openai");
+    });
+  });
+  
+  describe("ComponentError", () => {
+    test("应该包含 code 和 componentName 属性", () => {
+      const error = new ComponentError(
+        "Component init failed",
+        ErrorCodes.COMPONENT_INIT_FAILED,
+        "agent"
+      );
+      
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(ComponentError);
+      expect(error.name).toBe("ComponentError");
+      expect(error.code).toBe("COMP_002");
+      expect(error.componentName).toBe("agent");
+    });
+  });
+  
+  describe("isRoyError", () => {
+    test("应该识别 AgentError", () => {
+      const error = new AgentError("test", ErrorCodes.AGENT_NOT_FOUND);
+      expect(isRoyError(error)).toBe(true);
+    });
+    
+    test("应该识别 ToolError", () => {
+      const error = new ToolError("test", ErrorCodes.TOOL_NOT_FOUND, "tool");
+      expect(isRoyError(error)).toBe(true);
+    });
+    
+    test("不应该识别普通 Error", () => {
+      const error = new Error("test");
+      expect(isRoyError(error)).toBe(false);
+    });
+  });
+  
+  describe("getErrorCode", () => {
+    test("应该返回 RoyError 的 code", () => {
+      const error = new AgentError("test", ErrorCodes.AGENT_NOT_FOUND);
+      expect(getErrorCode(error)).toBe("AGENT_001");
+    });
+    
+    test("应该返回 undefined 对于普通 Error", () => {
+      const error = new Error("test");
+      expect(getErrorCode(error)).toBeUndefined();
+    });
+  });
+  
+  describe("ContextError", () => {
+    test("应该包含 code、sessionId、usage 和 contextWindow 属性", () => {
+      const usage = {
+        promptTokens: 10000,
+        completionTokens: 500,
+        totalTokens: 10500,
+      };
+      const error = new ContextError(
+        "Context threshold exceeded",
+        ErrorCodes.CONTEXT_THRESHOLD_EXCEEDED,
+        "session-123",
+        usage,
+        128000
+      );
+      
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(ContextError);
+      expect(error.name).toBe("ContextError");
+      expect(error.message).toBe("Context threshold exceeded");
+      expect(error.code).toBe("CTX_001");
+      expect(error.sessionId).toBe("session-123");
+      expect(error.usage).toEqual(usage);
+      expect(error.contextWindow).toBe(128000);
+    });
+    
+    test("应该支持不传可选参数", () => {
+      const error = new ContextError(
+        "Context error",
+        ErrorCodes.CONTEXT_THRESHOLD_EXCEEDED
+      );
+      
+      expect(error.sessionId).toBeUndefined();
+      expect(error.usage).toBeUndefined();
+      expect(error.contextWindow).toBeUndefined();
+    });
+    
+    test("应该使用默认错误码", () => {
+      const error = new ContextError("Context error");
+      expect(error.code).toBe("CTX_001");
+    });
+  });
+  
+  describe("ErrorCodes - Context errors", () => {
+    test("应该包含 CONTEXT_THRESHOLD_EXCEEDED", () => {
+      expect(ErrorCodes.CONTEXT_THRESHOLD_EXCEEDED).toBe("CTX_001");
+    });
+    
+    test("应该包含 CONTEXT_COMPACTION_FAILED", () => {
+      expect(ErrorCodes.CONTEXT_COMPACTION_FAILED).toBe("CTX_002");
+    });
+  });
+});

package/src/env/errors.ts

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview 统一错误类型体系
+ * 
+ * 提供 AgentError, ToolError, LLMError, ComponentError, ContextError 等错误类型
+ * 每个错误包含 code（错误码）和 details（额外信息）
+ */
+
+/**
+ * 错误码枚举
+ */
+export const ErrorCodes = {
+  // Agent 错误 (AGENT_xxx)
+  AGENT_NOT_FOUND: "AGENT_001",
+  AGENT_RUN_FAILED: "AGENT_002",
+  AGENT_TIMEOUT: "AGENT_003",
+  AGENT_CONFIG_INVALID: "AGENT_004",
+  
+  // Tool 错误 (TOOL_xxx)
+  TOOL_NOT_FOUND: "TOOL_001",
+  TOOL_DISABLED: "TOOL_002",
+  TOOL_EXECUTION_FAILED: "TOOL_003",
+  TOOL_VALIDATION_FAILED: "TOOL_004",
+  
+  // LLM 错误 (LLM_xxx)
+  LLM_PROVIDER_NOT_FOUND: "LLM_001",
+  LLM_INVOCATION_FAILED: "LLM_002",
+  LLM_TIMEOUT: "LLM_003",
+  LLM_CONFIG_INVALID: "LLM_004",
+  
+  // Component 错误 (COMP_xxx)
+  COMPONENT_NOT_FOUND: "COMP_001",
+  COMPONENT_INIT_FAILED: "COMP_002",
+  COMPONENT_NOT_RUNNING: "COMP_003",
+  
+  // Config 错误 (CONFIG_xxx)
+  CONFIG_NOT_FOUND: "CONFIG_001",
+  CONFIG_INVALID: "CONFIG_002",
+  CONFIG_SOURCE_ERROR: "CONFIG_003",
+  
+  // Context 错误 (CTX_xxx)
+  CONTEXT_THRESHOLD_EXCEEDED: "CTX_001",
+  CONTEXT_COMPACTION_FAILED: "CTX_002",
+  
+  // MCP 错误 (MCP_xxx)
+  MCP_INIT_FAILED: "MCP_001",
+  MCP_SERVER_ERROR: "MCP_002",
+  MCP_TOOL_ERROR: "MCP_003",
+} as const;
+
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
+
+/**
+ * RoyError 基类
+ */
+export class RoyError extends Error {
+  constructor(
+    message: string,
+    public readonly code: ErrorCode,
+    public readonly details?: unknown
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * Agent 相关错误
+ */
+export class AgentError extends RoyError {
+  constructor(
+    message: string,
+    code: ErrorCode = ErrorCodes.AGENT_NOT_FOUND,
+    details?: unknown
+  ) {
+    super(message, code, details);
+  }
+}
+
+/**
+ * Tool 相关错误
+ */
+export class ToolError extends RoyError {
+  constructor(
+    message: string,
+    code: ErrorCode = ErrorCodes.TOOL_NOT_FOUND,
+    public readonly toolName?: string,
+    details?: unknown
+  ) {
+    super(message, code, details);
+  }
+}
+
+/**
+ * LLM 相关错误
+ */
+export class LLMError extends RoyError {
+  constructor(
+    message: string,
+    code: ErrorCode = ErrorCodes.LLM_INVOCATION_FAILED,
+    public readonly provider?: string,
+    details?: unknown
+  ) {
+    super(message, code, details);
+  }
+}
+
+/**
+ * Component 相关错误
+ */
+export class ComponentError extends RoyError {
+  constructor(
+    message: string,
+    code: ErrorCode = ErrorCodes.COMPONENT_NOT_FOUND,
+    public readonly componentName?: string,
+    details?: unknown
+  ) {
+    super(message, code, details);
+  }
+}
+
+/**
+ * Context 相关错误
+ */
+export class ContextError extends RoyError {
+  constructor(
+    message: string,
+    code: ErrorCode = ErrorCodes.CONTEXT_THRESHOLD_EXCEEDED,
+    public readonly sessionId?: string,
+    public readonly usage?: {
+      promptTokens: number;
+      completionTokens: number;
+      totalTokens: number;
+    },
+    public readonly contextWindow?: number,
+    details?: unknown
+  ) {
+    super(message, code, details);
+  }
+}
+
+/**
+ * 检查是否是 RoyError
+ */
+export function isRoyError(error: unknown): error is RoyError {
+  return error instanceof RoyError;
+}
+
+/**
+ * 获取错误码
+ */
+export function getErrorCode(error: unknown): ErrorCode | undefined {
+  if (error instanceof RoyError) {
+    return error.code;
+  }
+  return undefined;
+}

package/src/env/event-source/event-source-agent-handler.test.ts

@@ -0,0 +1,193 @@
+import { describe, test, expect } from "bun:test";
+import { EventSourceAgentHandler, type EventSourceAgentHandlerConfig } from "./event-source-agent-handler";
+import type { EventSourceEvent } from "./types";
+
+describe("EventSourceAgentHandler", () => {
+  const createTestEvent = (overrides: Partial<EventSourceEvent> = {}): EventSourceEvent => ({
+    sourceId: "test-source-1",
+    type: "lark.im.message.receive_v1",
+    timestamp: new Date("2026-04-07T12:00:00.000Z").getTime(),
+    payload: {
+      sourceId: "test-source-1",
+      sourceType: "lark-cli",
+      rawEvent: {
+        schema: "im.message.receive_v1",
+        message_id: "msg_123",
+        content: "Hello, Agent!",
+      },
+      message: "[飞书消息] user_abc: Hello, Agent!",
+      timestamp: new Date("2026-04-07T12:00:00.000Z").getTime(),
+    },
+    ...overrides,
+  });
+
+  describe("constructor", () => {
+    test("should create handler with default config", () => {
+      const handler = new EventSourceAgentHandler();
+      expect(handler).toBeDefined();
+      expect(handler.getConfig().enabled).toBe(true);
+      expect(handler.getConfig().prefix).toBe("[事件源]");
+      expect(handler.getConfig().includeTimestamp).toBe(true);
+      expect(handler.getConfig().includeRawEvent).toBe(false);
+    });
+
+    test("should create handler with custom config", () => {
+      const config: EventSourceAgentHandlerConfig = {
+        enabled: false,
+        prefix: "[通知]",
+        includeTimestamp: false,
+        includeRawEvent: true,
+      };
+      const handler = new EventSourceAgentHandler(config);
+      const cfg = handler.getConfig();
+      expect(cfg.enabled).toBe(false);
+      expect(cfg.prefix).toBe("[通知]");
+      expect(cfg.includeTimestamp).toBe(false);
+      expect(cfg.includeRawEvent).toBe(true);
+    });
+  });
+
+  describe("formatEventForAgent", () => {
+    test("should format event with all fields", () => {
+      const handler = new EventSourceAgentHandler();
+      const event = createTestEvent();
+      const result = handler.formatEventForAgent(event);
+
+      expect(result).toContain("[事件源]");
+      expect(result).toContain("来源: lark-cli");
+      expect(result).toContain("类型: lark.im.message.receive_v1");
+      expect(result).toContain("内容: [飞书消息] user_abc: Hello, Agent!");
+    });
+
+    test("should include timestamp when enabled", () => {
+      const handler = new EventSourceAgentHandler({ includeTimestamp: true });
+      const event = createTestEvent();
+      const result = handler.formatEventForAgent(event);
+
+      expect(result).toContain("2026/4/7");
+    });
+
+    test("should exclude timestamp when disabled", () => {
+      const handler = new EventSourceAgentHandler({ includeTimestamp: false });
+      const event = createTestEvent();
+      const result = handler.formatEventForAgent(event);
+
+      expect(result).not.toContain("2026/4/7");
+    });
+
+    test("should include raw event when enabled", () => {
+      const handler = new EventSourceAgentHandler({ includeRawEvent: true });
+      const event = createTestEvent();
+      const result = handler.formatEventForAgent(event);
+
+      expect(result).toContain("原始数据:");
+      expect(result).toContain("Hello, Agent!");
+    });
+
+    test("should exclude raw event when disabled", () => {
+      const handler = new EventSourceAgentHandler({ includeRawEvent: false });
+      const event = createTestEvent();
+      const result = handler.formatEventForAgent(event);
+
+      expect(result).not.toContain("原始数据:");
+    });
+
+    test("should use custom prefix", () => {
+      const handler = new EventSourceAgentHandler({ prefix: "[通知]" });
+      const event = createTestEvent();
+      const result = handler.formatEventForAgent(event);
+
+      expect(result).toContain("[通知]");
+      expect(result).not.toContain("[事件源]");
+    });
+
+    test("should handle timer event", () => {
+      const handler = new EventSourceAgentHandler();
+      const event = createTestEvent({
+        type: "timer.tick",
+        payload: {
+          sourceId: "timer-1",
+          sourceType: "timer",
+          rawEvent: { message: "定时任务触发" },
+          message: "[定时任务] 定时任务触发",
+          timestamp: Date.now(),
+        },
+      });
+      const result = handler.formatEventForAgent(event);
+
+      expect(result).toContain("来源: timer");
+      expect(result).toContain("类型: timer.tick");
+      expect(result).toContain("内容: [定时任务] 定时任务触发");
+    });
+
+    test("should handle websocket event", () => {
+      const handler = new EventSourceAgentHandler();
+      const event = createTestEvent({
+        type: "ws.message",
+        payload: {
+          sourceId: "ws-1",
+          sourceType: "websocket",
+          rawEvent: { data: "websocket message" },
+          message: "[WebSocket] {\"data\":\"websocket message\"}",
+          timestamp: Date.now(),
+        },
+      });
+      const result = handler.formatEventForAgent(event);
+
+      expect(result).toContain("来源: websocket");
+      expect(result).toContain("类型: ws.message");
+    });
+  });
+
+  describe("createHandler", () => {
+    test("should create a handler function", () => {
+      const handler = new EventSourceAgentHandler();
+      const fn = handler.createHandler();
+      expect(typeof fn).toBe("function");
+    });
+
+    test("should return formatted message when enabled", () => {
+      const handler = new EventSourceAgentHandler({ enabled: true });
+      const fn = handler.createHandler();
+      const event = createTestEvent();
+      const result = fn(event);
+
+      expect(result).toBeDefined();
+      expect(typeof result).toBe("string");
+      expect(result).toContain("[事件源]");
+    });
+
+    test("should return undefined when disabled", () => {
+      const handler = new EventSourceAgentHandler({ enabled: false });
+      const fn = handler.createHandler();
+      const event = createTestEvent();
+      const result = fn(event);
+
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe("updateConfig", () => {
+    test("should update config partially", () => {
+      const handler = new EventSourceAgentHandler();
+      handler.updateConfig({ prefix: "[更新]" });
+      
+      expect(handler.getConfig().prefix).toBe("[更新]");
+      expect(handler.getConfig().enabled).toBe(true); // 保持不变
+    });
+
+    test("should update multiple config values", () => {
+      const handler = new EventSourceAgentHandler();
+      handler.updateConfig({
+        prefix: "[新前缀]",
+        includeRawEvent: true,
+        enabled: false,
+      });
+      
+      const cfg = handler.getConfig();
+      expect(cfg.prefix).toBe("[新前缀]");
+      expect(cfg.includeRawEvent).toBe(true);
+      expect(cfg.enabled).toBe(false);
+    });
+  });
+});

package/src/env/event-source/event-source-agent-handler.ts

@@ -0,0 +1,111 @@
+/**
+ * EventSourceAgentHandler
+ * 
+ * 将事件源事件转换为 Agent 输入的处理器
+ */
+
+import type { EventSourceEvent, EventSourceEventHandler } from "./types";
+import { createLogger } from "../log-trace/logger";
+
+const logger = createLogger("event-source-agent-handler");
+
+/**
+ * EventSourceAgentHandler 配置
+ */
+export interface EventSourceAgentHandlerConfig {
+  /** 是否启用 */
+  enabled?: boolean;
+  /** 前缀（用于区分事件消息） */
+  prefix?: string;
+  /** 是否包含原始事件 */
+  includeRawEvent?: boolean;
+  /** 是否包含时间戳 */
+  includeTimestamp?: boolean;
+}
+
+/**
+ * EventSourceAgentHandler
+ * 
+ * 将事件源事件转换为 Agent 可读的文本消息
+ */
+export class EventSourceAgentHandler {
+  private config: Required<EventSourceAgentHandlerConfig>;
+
+  constructor(config: EventSourceAgentHandlerConfig = {}) {
+    this.config = {
+      enabled: config.enabled ?? true,
+      prefix: config.prefix ?? "[事件源]",
+      includeRawEvent: config.includeRawEvent ?? false,
+      includeTimestamp: config.includeTimestamp ?? true,
+    };
+  }
+
+  /**
+   * 创建事件处理器
+   */
+  createHandler(): EventSourceEventHandler {
+    return (event: EventSourceEvent) => {
+      if (!this.config.enabled) {
+        return;
+      }
+
+      const message = this.formatEventForAgent(event);
+      logger.debug(`[AgentHandler] Formatted event: ${message.substring(0, 100)}`);
+      
+      // 这里返回格式化后的消息，供调用方使用
+      return message;
+    };
+  }
+
+  /**
+   * 格式化事件为 Agent 消息
+   */
+  formatEventForAgent(event: EventSourceEvent): string {
+    const parts: string[] = [];
+
+    // 前缀
+    parts.push(this.config.prefix);
+
+    // 时间戳
+    if (this.config.includeTimestamp) {
+      const time = new Date(event.timestamp).toLocaleString("zh-CN");
+      parts.push(`[${time}]`);
+    }
+
+    // 来源信息
+    parts.push(`来源: ${event.payload.sourceType}`);
+
+    // 事件类型
+    parts.push(`类型: ${event.type}`);
+
+    // 消息内容
+    parts.push(`内容: ${event.payload.message}`);
+
+    // 原始事件（可选）
+    if (this.config.includeRawEvent) {
+      const rawStr = typeof event.payload.rawEvent === "string" 
+        ? event.payload.rawEvent 
+        : JSON.stringify(event.payload.rawEvent);
+      parts.push(`原始数据: ${rawStr}`);
+    }
+
+    return parts.join(" ");
+  }
+
+  /**
+   * 更新配置
+   */
+  updateConfig(config: Partial<EventSourceAgentHandlerConfig>): void {
+    this.config = {
+      ...this.config,
+      ...config,
+    };
+  }
+
+  /**
+   * 获取配置
+   */
+  getConfig(): Readonly<Required<EventSourceAgentHandlerConfig>> {
+    return { ...this.config };
+  }
+}