@ai-setting/roy-agent-core 1.3.9 → 1.3.11

package/src/env/component.ts

@@ -1,335 +0,0 @@
-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

@@ -1,72 +0,0 @@
-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

@@ -1,123 +0,0 @@
-/**
- * @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

@@ -1,114 +0,0 @@
-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);
-    });
-  });
-});