@ai-setting/roy-agent-core 1.0.0

package/src/env/component.ts

@@ -0,0 +1,335 @@
+import { z, ZodType, ZodTypeDef } from "zod";
+
+// 前向声明 Environment（避免循环依赖）
+import type { Environment } from "./interface";
+
+// 导入 Hook 系统
+import { HookManager, createHook, createPriorityHook } from "./hook";
+import type { Hook, HookContext, HookPhase, HookMeta, HookFn, HookManagerOptions } from "./hook";
+
+// 导出 Hook 系统
+export type { Hook, HookContext, HookPhase, HookMeta, HookFn, HookManagerOptions };
+export { HookManager, createHook, createPriorityHook };
+
+/**
+ * Component 状态
+ */
+export type ComponentStatus =
+  | "created"
+  | "initializing"
+  | "running"
+  | "stopping"
+  | "stopped"
+  | "error";
+
+/**
+ * Component 配置
+ */
+export interface ComponentConfig {
+  name: string;
+  version: string;
+  enabled: boolean;
+  options?: Record<string, unknown>;
+  /**
+   * Environment 实例（可选）
+   * 
+   * 推荐在 init 时接收 env 实例，以便：
+   * - 通过 env.getComponent() 获取其他组件
+   * - 通过 env.pushEnvEvent() 发布事件
+   * - 通过 env.handle_query() 处理查询
+   * 
+   * 如果未提供，部分 Component 仍可正常工作（如测试场景）
+   * 
+   * @example
+   * ```typescript
+   * async onInit(): Promise<void> {
+   *   if (this.env) {
+   *     const configComp = this.env.getComponent("config");
+   *   }
+   * }
+   * ```
+   */
+  env?: Environment;
+}
+
+/**
+ * Component 路径声明
+ */
+export interface ComponentPaths {
+  base: "config" | "state" | "data" | "cache";
+  subPath: string;
+  isDirectory: boolean;
+}
+
+/**
+ * Component Schema（注册配置）
+ */
+export interface ComponentSchema {
+  /** Component 名称 */
+  name: string;
+
+  /** 配置 Schema（Zod） */
+  schema: ZodType<unknown, ZodTypeDef, unknown>;
+
+  /** 默认值（从 Schema 提取） */
+  defaults: Record<string, unknown>;
+
+  /** 路径声明 */
+  paths?: Record<string, ComponentPaths>;
+
+  /** 元信息 */
+  metadata?: {
+    description?: string;
+    version?: string;
+    author?: string;
+  };
+}
+
+/**
+ * Component 配置变更事件
+ */
+export interface ComponentConfigChangeEvent {
+  /** Component 名称 */
+  component: string;
+
+  /** 变更的配置键 */
+  key: string;
+
+  /** 旧值 */
+  oldValue: unknown;
+
+  /** 新值 */
+  newValue: unknown;
+
+  /** 是否持久化 */
+  persisted: boolean;
+
+  /** 时间戳 */
+  timestamp: number;
+}
+
+/**
+ * Component 配置监听回调
+ */
+export type ComponentWatchCallback = (
+  event: ComponentConfigChangeEvent
+) => void | Promise<void>;
+
+/**
+ * Component 基类接口
+ */
+export interface Component {
+  /** Component 名称 */
+  readonly name: string;
+
+  /** Component 版本 */
+  readonly version: string;
+
+  /** 获取状态 */
+  getStatus(): ComponentStatus;
+
+  /** 获取配置 */
+  getConfig(): ComponentConfig;
+
+  /** 初始化 */
+  init(config: ComponentConfig): Promise<void>;
+
+  /** 启动 */
+  start(): Promise<void>;
+
+  /** 停止 */
+  stop(): Promise<void>;
+}
+
+/**
+ * Component 基类实现
+ */
+export abstract class BaseComponent implements Component {
+  abstract readonly name: string;
+  abstract readonly version: string;
+
+  protected _status: ComponentStatus = "created";
+  protected _enabled: boolean = true;
+  protected env!: Environment;  // 非可选，使用 definite assignment assertion
+
+  /** Hook 管理器 - 子类初始化时由构造函数设置 */
+  public readonly hookManager: HookManager;
+
+  constructor() {
+    // 创建 HookManager，稍后在 init 中更新组件信息
+    this.hookManager = new HookManager();
+  }
+
+  getStatus(): ComponentStatus {
+    return this._status;
+  }
+
+  getConfig(): ComponentConfig {
+    return {
+      name: this.name,
+      version: this.version,
+      enabled: this._enabled,
+      env: this.env,
+    };
+  }
+  
+  /**
+   * 检查 Environment 是否已初始化
+   */
+  protected isEnvInitialized(): boolean {
+    return this._status !== "created";
+  }
+
+  protected setStatus(status: ComponentStatus): void {
+    this._status = status;
+  }
+
+  /**
+   * 获取 Environment 实例
+   */
+  protected getEnv(): Environment {
+    return this.env;
+  }
+
+  async init(config?: ComponentConfig): Promise<void> {
+    // 如果提供了 env，则注入
+    if (config?.env) {
+      this.env = config.env;
+    }
+    
+    this.setStatus("initializing");
+    
+    // 只有当 name/version 未在子类中定义时才从 config 注入
+    // 注意：如果子类已定义这些属性，Object.defineProperty 会失败
+    try {
+      if (config?.name) Object.defineProperty(this, "name", { value: config.name, writable: false });
+      if (config?.version) Object.defineProperty(this, "version", { value: config.version, writable: false });
+    } catch {
+      // 忽略错误（属性可能已在子类中定义）
+    }
+    if (config?.enabled !== undefined) this._enabled = config.enabled;
+    
+    // 更新 HookManager 的组件信息
+    this.hookManager.setComponentInfo(this.name, this.version);
+    
+    await this.onInit();
+    this.setStatus("running");
+  }
+
+  async start(): Promise<void> {
+    // 使用内部标志跟踪 start() 是否已调用
+    // 这是必要的，因为 init() 会将状态设为 "running"，但组件的 start() 仍需被调用
+    if ((this as any)._started) return;
+    (this as any)._started = true;
+    
+    await this.onStart();
+    this.setStatus("running");
+  }
+
+  async stop(): Promise<void> {
+    this.setStatus("stopping");
+    
+    // 清理 Hooks
+    this.hookManager.clear();
+    
+    await this.onStop();
+    this.setStatus("stopped");
+  }
+
+  /**
+   * 子类可覆盖的钩子方法
+   */
+  protected async onInit(): Promise<void> {}
+  protected async onStart(): Promise<void> {}
+  protected async onStop(): Promise<void> {}
+
+  // ========================================================================
+  // Hook 便捷方法
+  // ========================================================================
+
+  /**
+   * 注册 Hook
+   * 
+   * @param hookPoint Hook 点名称
+   * @param hook Hook 实例
+   */
+  protected registerHook<T = unknown>(hookPoint: string, hook: Hook<T>): void {
+    this.hookManager.register(hookPoint, hook);
+  }
+
+  /**
+   * 便捷方法：快速注册 Hook
+   */
+  protected addHook<T = unknown>(
+    hookPoint: string,
+    name: string,
+    fn: HookFn<T>,
+    priority?: number
+  ): void {
+    this.hookManager.register(
+      hookPoint,
+      createHook({ name, priority }, fn)
+    );
+  }
+
+  /**
+   * 便捷方法：按名称取消注册 Hook
+   */
+  protected removeHook(hookPoint: string, name: string): boolean {
+    return this.hookManager.unregister(hookPoint, name);
+  }
+
+  /**
+   * 执行 Hook
+   */
+  protected async executeHooks<T = unknown>(
+    hookPoint: string,
+    data: T,
+    metadata?: Record<string, unknown>
+  ): Promise<void> {
+    await this.hookManager.execute(hookPoint, data, metadata);
+  }
+
+  // ========================================================================
+  // 配置统一管理方法
+  // ========================================================================
+
+  /**
+   * 获取 ConfigComponent 实例
+   * 
+   * 子类可使用此方法获取配置组件，支持热更新
+   */
+  protected getConfigComponent(): { get(key: string): unknown } | undefined {
+    return this.env?.getComponent("config") as unknown as { get(key: string): unknown } | undefined;
+  }
+
+  /**
+   * 动态获取运行时配置值
+   * 
+   * 优先从 ConfigComponent 获取（支持热更新），否则返回默认值
+   * 适用于运行时可能变化的配置（如 API Keys、模型参数）
+   * 
+   * @param key 配置键（支持点号分隔的路径，如 "llm.temperature"）
+   * @param defaultValue 默认值
+   * @returns 配置值或默认值
+   * 
+   * @example
+   * ```typescript
+   * // 获取 LLM 温度配置（可能支持热更新）
+   * const temperature = this.getRuntimeConfig("llm.temperature", 0.7);
+   * 
+   * // 获取 API Key
+   * const apiKey = this.getRuntimeConfig<string>("llm.providers.openai.apiKey");
+   * ```
+   */
+  protected getRuntimeConfig<T>(key: string, defaultValue: T): T {
+    const configComponent = this.getConfigComponent();
+    if (configComponent) {
+      const value = configComponent.get(key);
+      if (value !== undefined) {
+        return value as T;
+      }
+    }
+    return defaultValue;
+  }
+}

package/src/env/constants.test.ts

@@ -0,0 +1,72 @@
+import { describe, test, expect } from "bun:test";
+import { 
+  AgentEvents,
+  AgentErrorMessages,
+  ToolEvents,
+  ToolErrorMessages,
+  LLMErrorMessages,
+  ComponentEvents,
+  isAgentEvent,
+  isToolEvent,
+} from "./constants";
+
+describe("常量定义", () => {
+  
+  describe("AgentEvents", () => {
+    test("应该定义正确的事件名称", () => {
+      expect(AgentEvents.RUN_START).toBe("agent.run.start");
+      expect(AgentEvents.RUN_COMPLETE).toBe("agent.run.complete");
+      expect(AgentEvents.RUN_ERROR).toBe("agent.run.error");
+      expect(AgentEvents.TOOL_CALLED).toBe("agent.tool.called");
+      expect(AgentEvents.TOOL_RESULT).toBe("agent.tool.result");
+      expect(AgentEvents.LLM_REQUEST).toBe("agent.llm.request");
+      expect(AgentEvents.LLM_RESPONSE).toBe("agent.llm.response");
+    });
+  });
+  
+  describe("ToolEvents", () => {
+    test("应该定义正确的事件名称", () => {
+      expect(ToolEvents.EXECUTE_START).toBe("tool.execute.start");
+      expect(ToolEvents.EXECUTE_COMPLETE).toBe("tool.execute.complete");
+      expect(ToolEvents.EXECUTE_ERROR).toBe("tool.execute.error");
+      expect(ToolEvents.REGISTERED).toBe("tool.registered");
+    });
+  });
+  
+  describe("ComponentEvents", () => {
+    test("应该定义正确的事件名称", () => {
+      expect(ComponentEvents.INIT_START).toBe("component.init.start");
+      expect(ComponentEvents.INIT_COMPLETE).toBe("component.init.complete");
+      expect(ComponentEvents.STOP).toBe("component.stop");
+    });
+  });
+  
+  describe("错误消息函数", () => {
+    test("AgentErrorMessages 应该生成正确的消息", () => {
+      expect(AgentErrorMessages.notFound("my-agent")).toBe("Agent not found: my-agent");
+      expect(AgentErrorMessages.alreadyRunning("my-agent")).toBe("Agent my-agent is already running");
+    });
+    
+    test("ToolErrorMessages 应该生成正确的消息", () => {
+      expect(ToolErrorMessages.notFound("readFile")).toBe("Tool not found: readFile");
+      expect(ToolErrorMessages.disabled("writeFile")).toBe("Tool writeFile is disabled");
+    });
+    
+    test("LLMErrorMessages 应该生成正确的消息", () => {
+      expect(LLMErrorMessages.providerNotFound("openai")).toBe("LLM provider not found: openai");
+      expect(LLMErrorMessages.apiKeyMissing("anthropic")).toBe("API key missing for provider: anthropic");
+    });
+  });
+  
+  describe("类型守卫", () => {
+    test("isAgentEvent 应该正确识别 Agent 事件", () => {
+      expect(isAgentEvent("agent.run.start")).toBe(true);
+      expect(isAgentEvent("tool.execute.start")).toBe(false);
+    });
+    
+    test("isToolEvent 应该正确识别 Tool 事件", () => {
+      expect(isToolEvent("tool.execute.start")).toBe(true);
+      expect(isToolEvent("agent.run.start")).toBe(false);
+    });
+  });
+});

package/src/env/constants.ts

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview 统一常量定义
+ * 
+ * 定义事件名称和错误消息常量，避免硬编码字符串
+ */
+
+/**
+ * Agent 相关事件名称
+ */
+export const AgentEvents = {
+  RUN_START: "agent.run.start",
+  RUN_COMPLETE: "agent.run.complete",
+  RUN_ERROR: "agent.run.error",
+  TOOL_CALLED: "agent.tool.called",
+  TOOL_RESULT: "agent.tool.result",
+  LLM_REQUEST: "agent.llm.request",
+  LLM_RESPONSE: "agent.llm.response",
+  ITERATION_START: "agent.iteration.start",
+  ITERATION_COMPLETE: "agent.iteration.complete",
+} as const;
+
+/**
+ * Tool 相关事件名称
+ */
+export const ToolEvents = {
+  EXECUTE_START: "tool.execute.start",
+  EXECUTE_COMPLETE: "tool.execute.complete",
+  EXECUTE_ERROR: "tool.execute.error",
+  REGISTERED: "tool.registered",
+  UNREGISTERED: "tool.unregistered",
+} as const;
+
+/**
+ * Component 生命周期事件名称
+ */
+export const ComponentEvents = {
+  INIT_START: "component.init.start",
+  INIT_COMPLETE: "component.init.complete",
+  START: "component.start",
+  STOP: "component.stop",
+} as const;
+
+/**
+ * Session 相关事件名称
+ */
+export const SessionEvents = {
+  CREATED: "session.created",
+  DELETED: "session.deleted",
+  MESSAGE_ADDED: "session.message.added",
+} as const;
+
+/**
+ * Agent 错误消息
+ */
+export const AgentErrorMessages = {
+  notFound: (name: string) => `Agent not found: ${name}`,
+  alreadyRunning: (name: string) => `Agent ${name} is already running`,
+  notRunning: (name: string) => `Agent ${name} is not running`,
+  runFailed: (name: string, reason?: string) => 
+    reason ? `Agent ${name} run failed: ${reason}` : `Agent ${name} run failed`,
+} as const;
+
+/**
+ * Tool 错误消息
+ */
+export const ToolErrorMessages = {
+  notFound: (name: string) => `Tool not found: ${name}`,
+  disabled: (name: string) => `Tool ${name} is disabled`,
+  executionFailed: (name: string, reason?: string) =>
+    reason ? `Tool ${name} execution failed: ${reason}` : `Tool ${name} execution failed`,
+  validationFailed: (name: string, reason?: string) =>
+    reason ? `Tool ${name} validation failed: ${reason}` : `Tool ${name} validation failed`,
+} as const;
+
+/**
+ * LLM 错误消息
+ */
+export const LLMErrorMessages = {
+  providerNotFound: (provider: string) => `LLM provider not found: ${provider}`,
+  apiKeyMissing: (provider: string) => `API key missing for provider: ${provider}`,
+  invocationFailed: (provider: string, reason?: string) =>
+    reason ? `LLM ${provider} invocation failed: ${reason}` : `LLM ${provider} invocation failed`,
+  timeout: (provider: string) => `LLM ${provider} invocation timeout`,
+} as const;
+
+/**
+ * Component 错误消息
+ */
+export const ComponentErrorMessages = {
+  notFound: (name: string) => `Component not found: ${name}`,
+  notRegistered: (name: string) => `Component ${name} is not registered`,
+  notRunning: (name: string) => `Component ${name} is not running`,
+  initFailed: (name: string, reason?: string) =>
+    reason ? `Component ${name} init failed: ${reason}` : `Component ${name} init failed`,
+} as const;
+
+/**
+ * 检查是否是 Agent 事件
+ */
+export function isAgentEvent(event: string): event is typeof AgentEvents[keyof typeof AgentEvents] {
+  return event.startsWith("agent.");
+}
+
+/**
+ * 检查是否是 Tool 事件
+ */
+export function isToolEvent(event: string): event is typeof ToolEvents[keyof typeof ToolEvents] {
+  return event.startsWith("tool.");
+}
+
+/**
+ * 检查是否是 Component 事件
+ */
+export function isComponentEvent(event: string): event is typeof ComponentEvents[keyof typeof ComponentEvents] {
+  return event.startsWith("component.");
+}
+
+/**
+ * 检查是否是 Session 事件
+ */
+export function isSessionEvent(event: string): event is typeof SessionEvents[keyof typeof SessionEvents] {
+  return event.startsWith("session.");
+}

package/src/env/debug/debug-component.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, test, beforeEach } from 'bun:test';
+import { DebugComponent } from './debug-component';
+import type { TraceEntry, TraceTreeNode, ParserOptions } from './types';
+
+describe('DebugComponent', () => {
+  let component: DebugComponent;
+
+  beforeEach(() => {
+    component = new DebugComponent();
+  });
+
+  describe('initialization', () => {
+    test('should have correct name and version', () => {
+      expect(component.name).toBe('debug');
+      expect(component.version).toBe('1.0.0');
+    });
+
+    test('should initialize with running status', async () => {
+      await component.init();
+      expect(component.getStatus()).toBe('running');
+    });
+  });
+
+  describe('getTraces', () => {
+    test('should return traces from log file', async () => {
+      await component.init();
+      
+      // Note: Without proper file mocking, we test the structure
+      const traces = await component.getTraces({
+        logFile: '/nonexistent/app.log',
+      });
+
+      expect(Array.isArray(traces)).toBe(true);
+      // Non-existent file returns empty array
+      expect(traces).toEqual([]);
+    });
+
+    test('should filter by function name', async () => {
+      await component.init();
+      
+      const traces = await component.getTraces({
+        logFile: '/real/app.log',
+        function: 'llm.invoke',
+      });
+
+      expect(traces.every(t => t.function.includes('llm'))).toBe(true);
+    });
+
+    test('should return empty array for non-existent file', async () => {
+      await component.init();
+      
+      const traces = await component.getTraces({
+        logFile: '/nonexistent/file.log',
+      });
+
+      expect(traces).toEqual([]);
+    });
+  });
+
+  describe('listTraceIds', () => {
+    test('should return trace ID list', async () => {
+      await component.init();
+      
+      const result = await component.listTraceIds({
+        logFile: '/real/app.log',
+      });
+
+      expect(result).toHaveProperty('traceIds');
+      expect(result).toHaveProperty('count');
+      expect(Array.isArray(result.traceIds)).toBe(true);
+    });
+
+    test('should respect limit parameter', async () => {
+      await component.init();
+      
+      const result = await component.listTraceIds({
+        logFile: '/real/app.log',
+        limit: 5,
+      });
+
+      expect(result.traceIds.length).toBeLessThanOrEqual(5);
+    });
+  });
+
+  describe('getCallTree', () => {
+    test('should return call tree for trace', async () => {
+      await component.init();
+      
+      const tree = await component.getCallTree({
+        logFile: '/real/app.log',
+        traceId: 'req_123',
+      });
+
+      if (tree) {
+        expect(tree).toHaveProperty('traceId');
+        expect(tree).toHaveProperty('function');
+        expect(tree).toHaveProperty('children');
+        expect(Array.isArray(tree.children)).toBe(true);
+      }
+    });
+
+    test('should return null for non-existent trace', async () => {
+      await component.init();
+      
+      const tree = await component.getCallTree({
+        logFile: '/real/app.log',
+        traceId: 'nonexistent',
+      });
+
+      // May return null or empty tree depending on implementation
+      expect(tree === null || tree.traceId !== 'nonexistent').toBe(true);
+    });
+  });
+});