@ai-setting/roy-agent-core 1.0.0

package/src/env/prompt/prompt-component.ts

@@ -0,0 +1,619 @@
+/**
+ * @fileoverview PromptComponent
+ * 
+ * 管理提示词存储、加载和渲染
+ * - 内置 prompts 在构建时嵌入到 bundle 中（通过 prompts-index.ts）
+ * - 外部 prompts 通过配置从指定路径加载
+ * 
+ * 配置通过 ConfigComponent 实时获取，支持配置热更新
+ */
+
+import { z } from "zod";
+import { BaseComponent, type ComponentConfig, type HookFn } from "../component";
+import { 
+  PromptConfigSchema, 
+  type PromptConfig, 
+  type PromptPath,
+  type PromptEntry, 
+  type PromptHook,
+  type PromptHookContext,
+  PromptHookPoints, 
+} from "./types";
+import { PromptRenderer } from "./renderer";
+import { createLogger } from "../log-trace/logger";
+import { readFile, readdir } from "fs/promises";
+import { join, basename, extname } from "path";
+import { dirname } from "path";
+import type { ConfigComponent } from "../../config/config-component";
+import { PROMPT_CONFIG_REGISTRATION, PROMPT_DEFAULTS } from "./prompt-config-registration";
+import { toEnvKey, envKeyToConfigKey } from "../../config/env-key";
+import { builtInPrompts } from "./prompts-index";
+
+const logger = createLogger("prompt");
+
+/**
+ * PromptComponent 配置选项（通过 options 传递）
+ * 
+ * 配置加载顺序（优先级从低到高）：
+ * 1. File - 配置文件（通过 configPath 指定）
+ * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+ * 3. Object - 直接传入的配置对象（最高优先级）
+ */
+export interface PromptComponentOptions {
+  /** ConfigComponent 实例（必填） */
+  configComponent: ConfigComponent;
+  
+  /** 配置文件相对路径（可选，基于 XDG_DATA_HOME） */
+  configPath?: string;
+  
+  /** 环境变量前缀（可选，默认 "PROMPT"） */
+  envPrefix?: string;
+  
+  /** 默认 prompt 名称 */
+  defaultName?: string;
+  
+  /** 外部 prompt 路径列表 */
+  promptPaths?: PromptPath[];
+  
+  /** 变量前缀（默认 "{{"） */
+  variablePrefix?: string;
+  
+  /** 变量后缀（默认 "}}"） */
+  variableSuffix?: string;
+  
+  /** 直接传入的配置对象（可选，优先级最高） */
+  config?: Partial<PromptConfig>;
+}
+
+/**
+ * PromptComponent
+ * 
+ * 管理提示词存储、加载和渲染
+ * 配置通过 ConfigComponent 实时获取，支持配置热更新
+ */
+export class PromptComponent extends BaseComponent {
+  readonly name = "prompt";
+  readonly version = "1.0.0";
+
+  // 核心存储：name → entry
+  private prompts: Map<string, PromptEntry> = new Map();
+  
+  private config?: PromptConfig;
+  private configComponent?: ConfigComponent;
+  private renderer!: PromptRenderer;
+  
+  /** 配置变更 watcher 清理函数 */
+  private configWatcher?: () => void;
+
+  constructor() {
+    super();
+  }
+
+  // ============================================================================
+  // Component Lifecycle
+  // ============================================================================
+
+  /**
+   * 初始化组件
+   * 
+   * 配置加载优先级（从高到低）：
+   * 1. Object - 直接传入的 config 对象
+   * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+   * 3. File - 配置文件（通过 configPath 指定）
+   */
+  async init(config: ComponentConfig): Promise<void> {
+    // 调用基类 init，注入 env
+    await super.init(config);
+
+    // 从 options 获取 ConfigComponent
+    const options = config.options as unknown as PromptComponentOptions | undefined;
+    if (!options?.configComponent) {
+      throw new Error("ConfigComponent is required for PromptComponent initialization");
+    }
+
+    this.configComponent = options.configComponent;
+    await this.registerConfig(options);
+
+    // 初始化渲染器
+    this.initRenderer();
+
+    // 加载 prompts
+    await this.loadPrompts();
+
+    this.setStatus("running");
+    logger.info(`[PromptComponent] Initialized with ${this.prompts.size} prompts`);
+  }
+
+  /**
+   * 注册配置到 ConfigComponent
+   * 
+   * 配置加载顺序（优先级从低到高）：
+   * 1. Env - 环境变量（通过 load 加载 + 直接读取）
+   * 2. Defaults - 默认值（在环境变量检查之后设置）
+   * 3. Config Object - 直接配置对象（最高优先级）
+   */
+  private async registerConfig(options: PromptComponentOptions): Promise<void> {
+    const configComponent = options.configComponent;
+    if (!configComponent) return;
+
+    const { config, defaultName, promptPaths, variablePrefix, variableSuffix } = options;
+
+    // 1. 使用 registerComponent 注册配置（会自动注册 sources 和 keys）
+    configComponent.registerComponent(PROMPT_CONFIG_REGISTRATION);
+
+    // 2. 使用 load 加载配置（从 env/file source 加载）
+    await configComponent.load("prompt");
+
+    // 3. 后备方案：直接读取环境变量（如果 load 未覆盖）
+    const prefix = "PROMPT";
+    const promptKeys = [
+      "prompt.defaultName",
+      "prompt.promptPaths",
+      "prompt.variablePrefix",
+      "prompt.variableSuffix",
+      "prompt.strictMode",
+    ];
+
+    for (const key of promptKeys) {
+      const envKey = toEnvKey(key, prefix);
+      const value = process.env[envKey];
+      if (value !== undefined) {
+        await configComponent.set(key, value);
+      }
+    }
+
+    // 4. 自动发现其他相关环境变量
+    const loadedKeys = new Set(promptKeys);
+    for (const envKey of Object.keys(process.env)) {
+      const configKey = envKeyToConfigKey(envKey, prefix, "prompt");
+      if (!configKey) continue;
+      if (loadedKeys.has(configKey)) continue;
+      loadedKeys.add(configKey);
+      const value = process.env[envKey];
+      if (value !== undefined) {
+        await configComponent.set(configKey, value);
+      }
+    }
+
+    // 5. 设置默认值（只有当配置不存在时）
+    for (const [key, value] of Object.entries(PROMPT_DEFAULTS)) {
+      if (configComponent.get(key) === undefined) {
+        await configComponent.set(key, value);
+      }
+    }
+
+    // 6. 直接配置对象（最高优先级）
+    if (config) {
+      const flatConfig = this.flattenConfig(config);
+      for (const [key, value] of Object.entries(flatConfig)) {
+        await configComponent.set(key, value);
+      }
+    }
+
+    // 6.5 直接选项（也属于最高优先级）
+    if (defaultName !== undefined) {
+      await configComponent.set("prompt.defaultName", defaultName);
+    }
+    if (promptPaths !== undefined) {
+      await configComponent.set("prompt.promptPaths", promptPaths);
+    }
+    if (variablePrefix !== undefined) {
+      await configComponent.set("prompt.variablePrefix", variablePrefix);
+    }
+    if (variableSuffix !== undefined) {
+      await configComponent.set("prompt.variableSuffix", variableSuffix);
+    }
+
+    // 7. 注册配置热更新监听
+    this.registerConfigWatcher(configComponent);
+
+    // 8. 从 ConfigComponent 获取最终配置
+    // 注意：默认值已通过 registerComponent.defaults 设置到 ConfigComponent
+    this.config = {
+      defaultName: (configComponent.get("prompt.defaultName") as string) || "default",
+      promptPaths: (configComponent.get("prompt.promptPaths") as PromptPath[]) || [],
+      variablePrefix: (configComponent.get("prompt.variablePrefix") as string) || "{{",
+      variableSuffix: (configComponent.get("prompt.variableSuffix") as string) || "}}",
+      strictMode: (configComponent.get("prompt.strictMode") as boolean) || false,
+    };
+  }
+
+  /**
+   * 将配置对象展平为点号路径
+   */
+  private flattenConfig(
+    obj: Record<string, unknown>,
+    prefix = "prompt"
+  ): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      const fullKey = `${prefix}.${key}`;
+      if (value && typeof value === "object" && !Array.isArray(value)) {
+        Object.assign(result, this.flattenConfig(value as Record<string, unknown>, fullKey));
+      } else {
+        result[fullKey] = value;
+      }
+    }
+    return result;
+  }
+
+  /**
+   * 注册配置热更新监听
+   */
+  private registerConfigWatcher(configComponent: ConfigComponent): void {
+    if (typeof configComponent.watch !== "function") {
+      return;
+    }
+    
+    this.configWatcher = configComponent.watch("prompt.*", (event) => {
+      this.onConfigChange(event);
+    });
+  }
+
+  /**
+   * 处理配置变更
+   */
+  private onConfigChange(event: { key: string; oldValue?: unknown; newValue?: unknown }): void {
+    const key = event.key;
+    const value = event.newValue;
+    
+    if (value === undefined) return;
+    
+    logger.debug(`[PromptComponent] Config updated: ${key} = ${JSON.stringify(value)}`);
+
+    // 更新本地配置
+    switch (key) {
+      case "prompt.defaultName":
+        if (this.config) this.config.defaultName = value as string;
+        break;
+      case "prompt.promptPaths":
+        if (this.config) this.config.promptPaths = value as PromptPath[];
+        break;
+      case "prompt.variablePrefix":
+        if (this.config) {
+          this.config.variablePrefix = value as string;
+          this.initRenderer(); // 重新初始化渲染器
+        }
+        break;
+      case "prompt.variableSuffix":
+        if (this.config) {
+          this.config.variableSuffix = value as string;
+          this.initRenderer(); // 重新初始化渲染器
+        }
+        break;
+      case "prompt.strictMode":
+        if (this.config) this.config.strictMode = value as boolean;
+        break;
+    }
+  }
+
+  private initRenderer(): void {
+    const config = this.config || {
+      defaultName: "default",
+      promptPaths: [],
+      variablePrefix: "{{",
+      variableSuffix: "}}",
+      strictMode: false,
+    };
+    
+    this.renderer = new PromptRenderer({
+      prefix: config.variablePrefix,
+      suffix: config.variableSuffix,
+      strict: config.strictMode,
+      onMissingVariable: (name) => {
+        logger.warn(`Undefined variable: ${name}`);
+        return `{{${name}}}`;
+      },
+    });
+  }
+
+  async onStart(): Promise<void> {
+    logger.info("[PromptComponent] Started");
+  }
+
+  async onStop(): Promise<void> {
+    this.prompts.clear();
+    this.setStatus("stopped");
+    logger.info("[PromptComponent] Stopped");
+  }
+
+  // ============================================================================
+  // Config Access
+  // ============================================================================
+
+  private getPromptConfig<T>(key: keyof PromptConfig, defaultValue?: T): T {
+    if (this.config && key in this.config) {
+      return (this.config[key] as T) ?? defaultValue as T;
+    }
+    
+    return defaultValue as T;
+  }
+
+  // ============================================================================
+  // Core Methods
+  // ============================================================================
+
+  /**
+   * 添加 prompt
+   */
+  add(name: string, content: string, source: PromptEntry["source"] = "inline"): void {
+    const entry: PromptEntry = {
+      name,
+      content,
+      source,
+      overridable: true,
+      loadedAt: Date.now(),
+    };
+
+    // 如果已存在且不可覆盖，则跳过
+    const existing = this.prompts.get(name);
+    if (existing && !existing.overridable) {
+      logger.debug(`[PromptComponent] Skip override for non-overridable prompt: ${name}`);
+      return;
+    }
+
+    this.prompts.set(name, entry);
+    logger.debug(`[PromptComponent] Added prompt: ${name} (${source})`);
+  }
+
+  /**
+   * 获取 prompt 原始内容
+   */
+  get(name: string): string | undefined {
+    return this.prompts.get(name)?.content;
+  }
+
+  /**
+   * 获取 prompt 条目
+   */
+  getEntry(name: string): PromptEntry | undefined {
+    return this.prompts.get(name);
+  }
+
+  /**
+   * 检查 prompt 是否存在
+   */
+  has(name: string): boolean {
+    return this.prompts.has(name);
+  }
+
+  /**
+   * 删除 prompt
+   */
+  delete(name: string): boolean {
+    return this.prompts.delete(name);
+  }
+
+  /**
+   * 列出所有 prompt 名称
+   */
+  list(): string[] {
+    return Array.from(this.prompts.keys());
+  }
+
+  /**
+   * 获取数量
+   */
+  size(): number {
+    return this.prompts.size;
+  }
+
+  // ============================================================================
+  // Render Methods
+  // ============================================================================
+
+  /**
+   * 获取并渲染 prompt
+   */
+  async getPrompt(name: string, variables: Record<string, string> = {}): Promise<string> {
+    const defaultName = this.getPromptConfig("defaultName", "default");
+    const targetName = this.has(name) ? name : defaultName;
+    
+    const entry = this.prompts.get(targetName);
+    if (!entry) {
+      logger.warn(`[PromptComponent] Prompt not found: ${name}, using fallback`);
+      return "You are a helpful assistant.";
+    }
+
+    return this.render(entry.content, variables, { name: targetName });
+  }
+
+  /**
+   * 渲染内容（异步方法）
+   */
+  async render(content: string, variables: Record<string, string> = {}, context?: Partial<PromptHookContext>): Promise<string> {
+    const hookContext: PromptHookContext = {
+      name: context?.name || "anonymous",
+      originalContent: content,
+      renderedContent: content,
+      variables,
+    };
+
+    // Hook: before.render
+    await this.executeHooks(PromptHookPoints.BEFORE_RENDER, hookContext);
+
+    // 执行渲染
+    hookContext.renderedContent = this.renderer.render(
+      hookContext.originalContent,
+      variables
+    );
+
+    // Hook: after.render
+    await this.executeHooks(PromptHookPoints.AFTER_RENDER, hookContext);
+
+    return hookContext.renderedContent;
+  }
+
+  /**
+   * 提取内容中的变量
+   */
+  extractVariables(content: string): string[] {
+    return this.renderer.extractVariables(content);
+  }
+
+  // ============================================================================
+  // Loading
+  // ============================================================================
+
+  /**
+   * 加载所有 prompts（内置 + 外部）
+   */
+  private async loadPrompts(): Promise<void> {
+    // 1. 加载内置 prompts
+    await this.loadBuiltInPrompts();
+
+    // 2. 加载外部 prompts（可覆盖内置）
+    await this.loadExternalPrompts();
+  }
+
+  /**
+   * 加载内置 prompts
+   * 
+   * 使用嵌入的 prompts（在构建时打包到 bundle 中）
+   */
+  private async loadBuiltInPrompts(): Promise<void> {
+    // 遍历嵌入的 prompts 并注册
+    for (const [name, content] of Object.entries(builtInPrompts)) {
+      if (content) {
+        this.prompts.set(name, {
+          name,
+          content,
+          source: "built-in",
+          overridable: false,
+          loadedAt: Date.now(),
+        });
+        logger.debug(`[PromptComponent] Loaded built-in prompt: ${name}`);
+      }
+    }
+    
+    logger.info(`[PromptComponent] Loaded ${this.prompts.size} built-in prompts`);
+  }
+
+  /**
+   * 加载外部 prompts
+   */
+  private async loadExternalPrompts(): Promise<void> {
+    const promptPaths = this.getPromptConfig<PromptPath[]>("promptPaths", []);
+      
+    for (const pathConfig of promptPaths) {
+      try {
+        if (pathConfig.type === "file") {
+          await this.loadFromFile(pathConfig.path, pathConfig.name);
+        } else if (pathConfig.type === "directory") {
+          await this.loadFromDirectory(
+            pathConfig.path,
+            pathConfig.extension || ".md",
+            pathConfig.recursive !== false
+          );
+        }
+      } catch (error) {
+        logger.error(`[PromptComponent] Failed to load from ${pathConfig.path}:`, error);
+      }
+    }
+  }
+
+  /**
+   * 从文件加载单个 prompt
+   */
+  async loadFromFile(filePath: string, name?: string): Promise<boolean> {
+    try {
+      const content = await readFile(filePath, "utf-8");
+      const promptName = name || basename(filePath, extname(filePath));
+      
+      this.add(promptName, content.trim(), "file");
+      const entry = this.prompts.get(promptName);
+      if (entry) entry.filePath = filePath;
+      
+      logger.debug(`[PromptComponent] Loaded prompt from file: ${filePath}`);
+      return true;
+    } catch (error) {
+      logger.error(`[PromptComponent] Failed to load file ${filePath}:`, error);
+      return false;
+    }
+  }
+
+  /**
+   * 从目录加载多个 prompt
+   */
+  async loadFromDirectory(directory: string, extension: string = ".md", recursive: boolean = true): Promise<number> {
+    let loaded = 0;
+
+    try {
+      const files = await this.findFiles(directory, extension, recursive);
+      
+      for (const filePath of files) {
+        const relativePath = filePath.replace(directory + "/", "");
+        const promptName = relativePath
+          .replace(/\\/g, "/")
+          .replace(new RegExp(escapeRegex(extension) + "$"), "")
+          .replace(/\//g, "-");
+
+        const content = await readFile(filePath, "utf-8");
+        this.add(promptName, content.trim(), "directory");
+        
+        const entry = this.prompts.get(promptName);
+        if (entry) entry.filePath = filePath;
+        
+        loaded++;
+      }
+
+      logger.info(`[PromptComponent] Loaded ${loaded} prompts from directory: ${directory}`);
+    } catch (error) {
+      logger.error(`[PromptComponent] Failed to load directory ${directory}:`, error);
+    }
+
+    return loaded;
+  }
+
+  private async findFiles(dir: string, extension: string, recursive: boolean): Promise<string[]> {
+    const files: string[] = [];
+    
+    try {
+      const entries = await readdir(dir, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        
+        if (entry.isDirectory() && recursive) {
+          const subFiles = await this.findFiles(fullPath, extension, true);
+          files.push(...subFiles);
+        } else if (entry.isFile() && entry.name.endsWith(extension)) {
+          files.push(fullPath);
+        }
+      }
+    } catch (error) {
+      logger.warn(`[PromptComponent] Cannot read directory ${dir}:`, error);
+    }
+    
+    return files;
+  }
+
+  // ============================================================================
+  // Hooks
+  // ============================================================================
+
+  /**
+   * 注册 Prompt Hook（公开便捷方法，供外部调用）
+   * 
+   * 与 BaseComponent.registerHook 不同，这个方法接受 name + fn 参数
+   */
+  registerPromptHook(
+    hookPoint: string,
+    name: string,
+    fn: HookFn<unknown>,
+    priority?: number
+  ): void {
+    this.addHook(hookPoint, name, fn, priority);
+  }
+
+  /**
+   * 获取 Prompt Hook 点列表
+   */
+  getHookPoints(): string[] {
+    return [PromptHookPoints.BEFORE_RENDER, PromptHookPoints.AFTER_RENDER];
+  }
+}
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}