@ai-setting/roy-agent-core 1.0.0

package/src/env/hook/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Hook 系统统一导出
+ * 
+ * 注意：HookContext 泛型版本从 ./types 导出
+ * Agent 特有的 HookContext 包含 iteration, maxIterations 等字段，在 ./agent/types.ts 中
+ */
+
+export {
+  type HookPhase,
+  type HookMeta,
+  type HookContext,
+  type Hook,
+  type HookFn,
+  type HookActionType,
+  type HookAction,
+  type HookResult,
+  // 导出别名供内部使用
+  type HookContext as BaseHookContext,
+  type Hook as BaseHook,
+  type HookFn as BaseHookFn,
+  createHook,
+  createPriorityHook,
+} from "./types";
+
+// HookManager
+export { HookManager, type HookManagerOptions } from "./hook-manager";
+
+// GlobalHookManager
+export {
+  globalHookManager,
+  AgentHookPoints,
+  LLMHookPoints,
+  ToolHookPoints,
+  executeAgentHook,
+  executeAgentHookWithIntervention,
+  executeLLMHook,
+  executeToolHook,
+} from "./global-hook-manager";

package/src/env/hook/types.ts

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview Hook 系统统一类型定义
+ * 
+ * 提供所有 Component 使用的统一 Hook 接口
+ */
+
+/**
+ * Hook 执行阶段
+ */
+export type HookPhase = "before" | "after" | "error";
+
+/**
+ * Hook 元信息
+ */
+export interface HookMeta {
+  /** Hook 唯一名称 */
+  name: string;
+  /** 执行优先级，默认 0，数值越小越先执行 */
+  priority?: number;
+  /** 描述 */
+  description?: string;
+}
+
+/**
+ * 统一 Hook 上下文
+ * 
+ * 泛型参数 T 表示该 Component 的上下文数据类型
+ */
+export interface HookContext<T = unknown> {
+  /** 当前组件信息 */
+  component: {
+    /** 组件名称 */
+    name: string;
+    /** 组件版本 */
+    version: string;
+  };
+  /** 上下文数据（Component 特定） */
+  data: T;
+  /** 元数据（可用于传递额外信息） */
+  metadata: Record<string, unknown>;
+  /** 执行阶段 */
+  phase: HookPhase;
+  /** 关联的 hook 点名称 */
+  hookPoint: string;
+}
+
+/**
+ * 统一 Hook 接口
+ * 
+ * 所有 Component 的 Hook 都应实现此接口
+ */
+export interface Hook<T = unknown> extends HookMeta {
+  /** 执行 Hook
+   * @param ctx 上下文
+   */
+  execute(ctx: HookContext<T>): void | Promise<void>;
+}
+
+/**
+ * Hook 函数类型（便捷别名）
+ */
+export type HookFn<T = unknown> = (ctx: HookContext<T>) => void | Promise<void>;
+
+// ========================================================================
+// Hook 干预机制
+// ========================================================================
+
+/**
+ * Hook 干预动作类型
+ */
+export type HookActionType =
+  | "stop"          // 停止执行
+  | "retry"         // 重试
+  | "compress"      // 压缩上下文
+  | "extract_memory" // 提取记忆
+  | "inject_message" // 注入消息
+  | "skip_tool"     // 跳过工具调用
+  | "custom";       // 自定义动作
+
+/**
+ * Hook 干预动作
+ */
+export interface HookAction {
+  /** 动作类型 */
+  type: HookActionType;
+  /** 动作参数 */
+  params?: Record<string, unknown>;
+  /** 动作描述 */
+  description?: string;
+}
+
+/**
+ * Hook 执行结果
+ */
+export interface HookResult {
+  /** 是否被停止 */
+  stopped?: boolean;
+  /** 干预动作（如果有） */
+  action?: HookAction;
+  /** 执行结果数据 */
+  results?: unknown[];
+}
+
+/**
+ * 创建 Hook 的工厂函数
+ * 
+ * @param meta Hook 元信息
+ * @param fn 执行函数
+ * @returns Hook 实例
+ * 
+ * @example
+ * ```typescript
+ * const hook = createHook(
+ *   { name: "my-hook", priority: 10 },
+ *   async (ctx) => { console.log(ctx.data); }
+ * );
+ * ```
+ */
+export function createHook<T = unknown>(
+  meta: HookMeta,
+  fn: HookFn<T>
+): Hook<T> {
+  return {
+    ...meta,
+    execute: fn,
+  };
+}
+
+/**
+ * 创建带优先级的 Hook 的便捷函数
+ */
+export function createPriorityHook<T = unknown>(
+  name: string,
+  fn: HookFn<T>,
+  priority: number
+): Hook<T> {
+  return createHook({ name, priority }, fn);
+}

package/src/env/index.ts

@@ -0,0 +1,144 @@
+/**
+ * @fileoverview Environment Module
+ * 
+ * 导出 Environment 相关的类型和实现。
+ */
+
+// Environment 接口
+export type { Environment } from "./interface";
+
+// Environment 类型
+export type {
+  EnvironmentConfig,
+  BaseEnvironmentConfig,
+  EnvEvent,
+  EnvEventMetadata,
+  EnvEventHandler,
+  Action,
+  ToolResult,
+  Context,
+} from "./types";
+
+// BaseEnvironment 实现
+export { BaseEnvironment } from "./environment";
+
+// Component
+export {
+  type Component,
+  type ComponentConfig,
+  type ComponentSchema,
+  type ComponentPaths,
+  type ComponentStatus,
+  type ComponentConfigChangeEvent,
+  type ComponentWatchCallback,
+  BaseComponent,
+} from "./component";
+
+// Hook 系统
+export {
+  type Hook,
+  type HookContext,
+  type HookPhase,
+  type HookMeta,
+  type HookFn,
+  type HookManagerOptions,
+  createHook,
+  createPriorityHook,
+  HookManager,
+} from "./hook";
+
+// Paths
+export {
+  type XDGPaths,
+  type XDGDirType,
+  XDG_PATHS,
+  getXDGPaths,
+  getXDGPath,
+} from "./paths";
+
+// Agent Component
+export {
+  AgentComponent,
+  type AgentComponentConfig,
+  AgentComponentConfigSchema,
+  type AgentInstance,
+  type AgentInstanceConfig,
+  type AgentRunResult,
+  type AgentContext,
+  type Plugin,
+  type HookContext as AgentHookContext,
+  type HookPoint,
+  type HookResult,
+  type HookActionType,
+  type Tool,
+  type ToolCall,
+  type ToolResult as AgentToolResult,
+  type ToolCallResult,
+  type LLMOutput,
+} from "./agent";
+
+// Task Component
+export {
+  TaskComponent,
+  type TaskComponentOptions,
+} from "./task";
+export type {
+  Task,
+  TaskOperation,
+  TaskStatus,
+  TaskPriority,
+  ActionType,
+  CreateTaskOptions,
+  UpdateTaskOptions,
+  ListTasksOptions,
+  CreateOperationOptions,
+  ListOperationsOptions,
+  TaskConfig,
+} from "./task/types";
+
+// MCP Component
+export {
+  McpComponent,
+} from "./mcp";
+export type {
+  McpComponentConfig,
+  McpComponentOptions,
+  McpPath,
+  McpServerConfig,
+  McpServerStatus,
+  DiscoveredMcpServer,
+} from "./mcp";
+
+// EventSource Component
+export {
+  EventSourceComponent,
+} from "./event-source/event-source-component";
+
+export {
+  EventSourceAgentHandler,
+} from "./event-source/event-source-agent-handler";
+export type {
+  EventSourceConfig,
+  EventSourceStatus,
+  EventSourceType,
+  EventSourceEvent,
+  EventSourceEventPayload,
+  EventSourceEventHandler,
+  EventSourceStatusChangeEvent,
+  EventSourcePersistenceConfig,
+  EventSourceComponentInterface,
+  EventSourceAgentHandlerConfig,
+} from "./event-source/types";
+export {
+  isValidEventSourceType,
+  getDefaultConfigForType,
+  validateEventSourceConfig,
+} from "./event-source/types";
+
+// Workflow Component
+export {
+  WorkflowComponent,
+} from "./workflow/workflow-component";
+export type {
+  WorkflowComponentConfig,
+} from "./workflow/workflow-component";

package/src/env/interface.ts

@@ -0,0 +1,203 @@
+/**
+ * @fileoverview Environment Interface
+ * 
+ * Environment 是智能体运行时的核心抽象。
+ * 
+ * 设计原则：
+ * 1. Environment 只做两件事：
+ *    - 组件管理：持有、注册、获取组件
+ *    - 核心调度：handle_query / handle_action / EnvEvent
+ * 2. 其他能力归属到对应 Component
+ * 
+ * 服务配置能力：
+ * - loadServiceConfig(): 从配置文件加载服务配置
+ * - generateComponentOptions(): 生成组件初始化选项
+ * - registerComponentWithConfig(): 注册并用配置初始化组件
+ * - initFromConfig(): 从配置文件初始化整个环境
+ */
+
+import type { Component } from "./component";
+import type { EnvEvent, EnvEventHandler, EnvEventInput, EnvironmentConfig, Action, ToolResult, Context } from "./types";
+import type { AgentContext } from "./agent/types";
+import type { ConfigComponent } from "../config/config-component";
+
+// Re-export for convenience
+export type { AgentContext };
+
+/**
+ * 服务配置接口
+ */
+export interface ServiceConfig {
+  /** 环境配置 */
+  environment?: {
+    name?: string;
+    version?: string;
+  };
+  /** 组件配置映射 */
+  components?: Record<string, ComponentConfigEntry>;
+}
+
+/**
+ * 组件配置项
+ */
+export interface ComponentConfigEntry {
+  /** 配置文件路径（可选） */
+  configPath?: string;
+  /** 环境变量前缀（可选） */
+  envPrefix?: string;
+  /** 直接配置对象（可选） */
+  config?: Record<string, unknown>;
+  /** 是否启用（可选，默认 true） */
+  enabled?: boolean;
+}
+
+/**
+ * 组件初始化选项（由 generateComponentOptions 生成）
+ */
+export interface GeneratedComponentOptions {
+  /** ConfigComponent 实例 */
+  configComponent: ConfigComponent;
+  /** 配置文件路径 */
+  configPath?: string;
+  /** 环境变量前缀 */
+  envPrefix?: string;
+  /** 直接配置对象 */
+  config?: Record<string, unknown>;
+  /** 允许的其他属性 */
+  [key: string]: unknown;
+}
+
+/**
+ * Environment 接口
+ * 
+ * 定义 Agent 运行时的核心能力接口。
+ */
+export interface Environment {
+  // ============ 标识 ============
+  
+  /** 环境名称 */
+  readonly name: string;
+  
+  /** 环境版本 */
+  readonly version: string;
+  
+  /** 获取环境配置 */
+  getConfig(): EnvironmentConfig;
+  
+  // ============ 组件管理（核心职责） ============
+  
+  /**
+   * 注册组件
+   */
+  registerComponent(component: Component): void;
+  
+  /**
+   * 注销组件
+   */
+  unregisterComponent(name: string): void;
+  
+  /**
+   * 获取组件
+   */
+  getComponent<T extends Component>(name: string): T | undefined;
+  
+  /**
+   * 列出所有组件
+   */
+  listComponents(): Component[];
+  
+  // ============ 核心能力（Agent 调度） ============
+  
+  /**
+   * 处理自然语言查询（核心入口）
+   * 
+   * @param query 用户查询文本
+   * @param context 执行上下文（可选）
+   * @returns 完整的文本响应
+   */
+  handle_query(
+    query: string,
+    context?: AgentContext
+  ): Promise<string>;
+  
+  /**
+   * 处理动作
+   */
+  handle_action(
+    action: Action,
+    context: Context
+  ): Promise<ToolResult>;
+  
+  // ============ EnvEvent 机制 ============
+  
+  /**
+   * 订阅 EnvEvent（返回取消订阅函数）
+   */
+  subscribe(handler: EnvEventHandler): () => void;
+  
+  /**
+   * 订阅指定类型事件
+   */
+  subscribeTo(
+    eventType: string | string[],
+    handler: EnvEventHandler
+  ): () => void;
+  
+  /**
+   * 订阅所有事件（通配符）
+   */
+  subscribeAll(handler: EnvEventHandler): () => void;
+  
+  /**
+   * 推送事件
+   * 
+   * @param event EnvEvent 或 EnvEventInput（部分属性）
+   */
+  pushEnvEvent(event: EnvEvent | EnvEventInput): void;
+  
+  // ============ 服务配置能力 ============
+  
+  /**
+   * 从配置文件加载服务配置
+   * 
+   * @param configPath 配置文件路径（基于 XDG_DATA_HOME）
+   * @returns 解析后的服务配置对象
+   */
+  loadServiceConfig(configPath: string): Promise<ServiceConfig>;
+  
+  /**
+   * 生成组件初始化选项
+   * 
+   * 根据组件配置项生成可用于初始化的选项对象。
+   * 
+   * @param componentName 组件名称
+   * @param configEntry 组件配置项
+   * @returns 生成的组件初始化选项
+   */
+  generateComponentOptions(
+    componentName: string,
+    configEntry: ComponentConfigEntry
+  ): GeneratedComponentOptions;
+  
+  /**
+   * 注册组件并用配置初始化
+   * 
+   * 便捷方法：注册组件并通过 ConfigComponent 初始化。
+   * 
+   * @param component 要注册的组件实例
+   * @param configEntry 组件配置项
+   */
+  registerComponentWithConfig(
+    component: Component,
+    configEntry: ComponentConfigEntry
+  ): Promise<void>;
+  
+  /**
+   * 从配置文件初始化整个环境
+   * 
+   * 加载服务配置，注册并初始化所有配置的组件。
+   * 
+   * @param configPath 配置文件路径（基于 XDG_DATA_HOME）
+   */
+  initFromConfig(configPath: string): Promise<void>;
+}