foliko 2.0.4 → 2.0.5

package/src/agent/prompt-registry.js

@@ -3,40 +3,29 @@
 /**
  * PromptRegistry — 全局系统提示词注册表
  *
- * 设计目标：
- *  - 单一注册入口（替代散落在各 Plugin 的 registerPromptPart 调用）
- *  - owner 命名空间隔离（避免 part 名冲突）
- *  - 用语义槽位（PROMPT_SLOT）排序，替代魔法数字
- *  - 可观测：list / preview / getPart / getSlots
- *
- * 与旧 API 的关系：
- *  - 完全独立的新 API，不破坏 MainAgent._systemPromptBuilder
- *  - 旧 registerPromptPart 调用继续工作（写入各 agent 自己的 builder）
- *  - 新代码推荐使用 framework.prompts.register(owner, name, provider, { slot })
- *
- * 渐进迁移路径：
- *  - P0：注册表可独立使用（plugins 主动注册，外部可预览）
- *  - P2：Plugin 基类支持声明式 prompts 字段
- *  - P5：MainAgent 完全切换到本注册表
+ * 简化设计：
+ * - priority: 数字越小越靠前（默认 100）
+ * - scope: 'global'（公用）| 'main'（主 agent）| agentId（特定子 agent）
+ * - 去掉槽位概念
  */
 
 const { EventEmitter } = require('../common/events');
-const { PROMPT_SLOT } = require('../common/constants');
+const fs = require('fs');
+const path = require('path');
 
 /**
  * 单个 prompt part
- * - provider 是 () => string|null，返回 null/空串时被 build 跳过
- * - 内部带缓存，失效后才重新计算
  */
 class PromptPart {
   constructor(owner, name, provider, options = {}) {
     this.owner = owner;
     this.name = name;
     this.provider = provider;
-    this.slot = options.slot || 'CUSTOM';
-    this.order = options.order ?? null; // 显式 order 覆盖 slot 默认
+    // scope: 'global' | 'main' | string (agentId)
+    this.scope = options.scope || 'global';
+    // priority: 数字越小越靠前，默认 100
+    this.priority = options.priority ?? 100;
     this.description = options.description || '';
-    this.metadata = options.metadata || {};
     this._cached = null;
     this._dirty = true;
     this._error = null;
@@ -53,8 +42,6 @@ class PromptPart {
         this._error = e;
         this._cached = null;
         this._dirty = false;
-        // 警告但不抛错 — 避免单个 part 失败导致整个 prompt 渲染失败
-        // eslint-disable-next-line no-console
         console.warn(`[PromptRegistry:${this.owner}::${this.name}] provider failed:`, e.message);
       }
     }
@@ -70,61 +57,25 @@ class PromptPart {
  * PromptRegistry 主类
  */
 class PromptRegistry extends EventEmitter {
-  constructor(options = {}) {
+  constructor() {
     super();
-
     // key = "owner::name"
     this._parts = new Map();
-
-    // slot 名称 → { order, label }
-    this._slots = new Map();
-
-    // 注入 slots：优先用参数，否则用全局 PROMPT_SLOT
-    const slots = options.slots || PROMPT_SLOT;
-    for (const [name, def] of Object.entries(slots)) {
-      if (!def || typeof def.order !== 'number') continue;
-      this._slots.set(name, {
-        order: def.order,
-        label: def.label || name,
-      });
-    }
-
-    // 用于 render 时检测循环依赖
+    // 用于 build 时检测循环依赖
     this._building = false;
   }
 
-  // ==================== 槽位管理 ====================
-
-  /**
-   * 定义/覆盖一个槽位
-   */
-  defineSlot(name, order, label) {
-    if (typeof order !== 'number') throw new Error('slot order must be a number');
-    this._slots.set(name, { order, label: label || name });
-    this.emit('slot-defined', { name, order, label });
-    return this;
-  }
-
-  /**
-   * 获取所有槽位定义
-   */
-  getSlots() {
-    return new Map(this._slots);
-  }
-
   // ==================== 注册/注销 ====================
 
   /**
    * 注册一个 prompt part
-   * @param {string} owner 拥有者标识（通常是 plugin name 或 '_main'）
+   * @param {string} owner 拥有者标识
    * @param {string} name part 名（在 owner 内唯一）
    * @param {Function} provider () => string|null
    * @param {Object} [options]
-   * @param {string} [options.slot='CUSTOM'] 槽位名
-   * @param {number} [options.order] 自定义 order（覆盖 slot 默认）
-   * @param {string} [options.description] 描述（用于 list/debug）
-   * @param {Object} [options.metadata] 额外元数据
-   * @returns {PromptPart}
+   * @param {string} [options.scope='global'] 作用域: 'global'|'main'|agentId
+   * @param {number} [options.priority=100] 优先级（越小越靠前）
+   * @param {string} [options.description] 描述
    */
   register(owner, name, provider, options = {}) {
     if (!owner || typeof owner !== 'string') {
@@ -140,13 +91,53 @@ class PromptRegistry extends EventEmitter {
     const key = `${owner}::${name}`;
     const part = new PromptPart(owner, name, provider, options);
     this._parts.set(key, part);
-    this.emit('register', { owner, name, slot: part.slot });
+    this.emit('register', { owner, name, scope: part.scope, priority: part.priority });
     return part;
   }
 
+  /**
+   * 注册一个 prompt part（从文件读取，支持变量插值）
+   * @param {string} owner 拥有者标识
+   * @param {string} filePath 文件路径
+   * @param {Object} [vars] 变量对象，模板中用 {{varName}} 引用
+   * @param {Object} [options] 同 register 选项
+   */
+  registerFile(owner, filePath, vars = {}, options = {}) {
+    if (!owner || typeof owner !== 'string') {
+      throw new Error('PromptRegistry.registerFile: owner is required');
+    }
+    if (!filePath || typeof filePath !== 'string') {
+      throw new Error('PromptRegistry.registerFile: filePath is required');
+    }
+
+    // 读取文件内容
+    const fullPath = path.resolve(filePath);
+    if (!fs.existsSync(fullPath)) {
+      throw new Error(`PromptRegistry.registerFile: file not found: ${fullPath}`);
+    }
+    let content = fs.readFileSync(fullPath, 'utf-8');
+
+    // 变量插值
+    if (vars && typeof vars === 'object') {
+      content = content.replace(/\{\{(\w+)\}\}/g, (match, varName) => {
+        if (Object.prototype.hasOwnProperty.call(vars, varName)) {
+          return String(vars[varName]);
+        }
+        return match; // 未找到的变量保留原样
+      });
+    }
+
+    // 转为 provider
+    const provider = () => content;
+
+    // 从文件名生成 name
+    const name = options.name || path.basename(filePath, path.extname(filePath));
+
+    return this.register(owner, name, provider, options);
+  }
+
   /**
    * 注销一个 part
-   * @returns {boolean} 是否真的删除了
    */
   unregister(owner, name) {
     const key = `${owner}::${name}`;
@@ -157,7 +148,6 @@ class PromptRegistry extends EventEmitter {
 
   /**
    * 清空指定 owner 的所有 parts
-   * @returns {number} 删除的 part 数
    */
   clearOwner(owner) {
     const prefix = `${owner}::`;
@@ -173,7 +163,7 @@ class PromptRegistry extends EventEmitter {
   }
 
   /**
-   * 失效指定 part（下次 build 时重新计算）
+   * 失效指定 part
    */
   invalidate(owner, name) {
     const part = this._parts.get(`${owner}::${name}`);
@@ -210,10 +200,14 @@ class PromptRegistry extends EventEmitter {
   }
 
   /**
-   * 列出所有 parts（按 order 排序）
+   * 列出所有 parts（按 priority 排序）
    */
   list() {
-    return Array.from(this._parts.values()).sort((a, b) => this._compareOrder(a, b));
+    return Array.from(this._parts.values()).sort((a, b) => {
+      if (a.priority !== b.priority) return a.priority - b.priority;
+      if (a.owner !== b.owner) return a.owner.localeCompare(b.owner);
+      return a.name.localeCompare(b.name);
+    });
   }
 
   /**
@@ -224,19 +218,24 @@ class PromptRegistry extends EventEmitter {
   }
 
   /**
-   * 按 slot 过滤
+   * 按 scope 过滤
    */
-  listBySlot(slot) {
-    return this.list().filter((p) => p.slot === slot);
+  listByScope(scope) {
+    return this.list().filter((p) => p.scope === scope);
   }
 
-  _compareOrder(a, b) {
-    const oa = a.order != null ? a.order : this._slots.get(a.slot)?.order ?? 999;
-    const ob = b.order != null ? b.order : this._slots.get(b.slot)?.order ?? 999;
-    if (oa !== ob) return oa - ob;
-    // 同 order 时按 owner → name 字母序，保证稳定
-    if (a.owner !== b.owner) return a.owner.localeCompare(b.owner);
-    return a.name.localeCompare(b.name);
+  /**
+   * 获取适用于指定 agent 的 parts
+   * @param {string|null} agentId agent ID，null 表示主 agent
+   */
+  listForAgent(agentId = null) {
+    const isMain = agentId === null || agentId === 'main';
+    return this.list().filter((p) => {
+      if (p.scope === 'global') return true;
+      if (p.scope === 'main' && isMain) return true;
+      if (p.scope === agentId) return true;
+      return false;
+    });
   }
 
   count() {
@@ -246,16 +245,24 @@ class PromptRegistry extends EventEmitter {
   // ==================== 渲染 ====================
 
   /**
-   * 渲染完整 prompt 文本（按 slot order 拼接）
+   * 渲染完整 prompt（按 priority 拼接）
    */
   build() {
+    return this.buildForAgent(null);
+  }
+
+  /**
+   * 渲染适用于指定 agent 的 prompt
+   * @param {string|null} agentId agent ID
+   */
+  buildForAgent(agentId = null) {
     if (this._building) {
       throw new Error('PromptRegistry.build() re-entered — check provider for circular calls');
     }
     this._building = true;
     try {
       const sections = [];
-      for (const part of this.list()) {
+      for (const part of this.listForAgent(agentId)) {
         const content = part.get();
         if (content && content.trim()) sections.push(content.trim());
       }
@@ -266,15 +273,14 @@ class PromptRegistry extends EventEmitter {
   }
 
   /**
-   * build() 的语义化别名，调试用
+   * build() 的别名
    */
   preview() {
     return this.build();
   }
 
   /**
-   * 渲染结构化清单（调试 / 文档生成）
-   * 返回 [{ owner, name, slot, order, length, contentPreview }]
+   * 渲染结构化清单（调试用）
    */
   inspect() {
     return this.list().map((part) => {
@@ -282,8 +288,8 @@ class PromptRegistry extends EventEmitter {
       return {
         owner: part.owner,
         name: part.name,
-        slot: part.slot,
-        order: part.order != null ? part.order : this._slots.get(part.slot)?.order ?? 999,
+        scope: part.scope,
+        priority: part.priority,
         description: part.description,
         hasContent: Boolean(content && content.trim()),
         length: content ? content.length : 0,
@@ -293,4 +299,4 @@ class PromptRegistry extends EventEmitter {
   }
 }
 
-module.exports = { PromptRegistry, PromptPart };
+module.exports = { PromptRegistry, PromptPart };