foliko 2.0.1 → 2.0.3

package/src/agent/base.js

@@ -2,11 +2,11 @@
 
 /**
  * BaseAgent - 所有 Agent 类型的公共基类
- * 提供事件、状态、prompt 部分注册等公共功能
+ * 提供事件、状态、prompt 等公共功能
  */
 
 const { EventEmitter } = require('../common/events');
-const { SystemPromptBuilder } = require('./prompt');
+const { PromptRegistry } = require('./prompt-registry');
 
 class BaseAgent extends EventEmitter {
   constructor(framework, config = {}) {
@@ -15,7 +15,9 @@ class BaseAgent extends EventEmitter {
     this.config = config;
     this.name = config.name || 'Agent';
     this._status = 'idle';
-    this._promptBuilder = new SystemPromptBuilder();
+    // Agent 私有的 prompt 注册表（新 API）
+    this._promptRegistry = new PromptRegistry();
+    this.promptRegistry = this._promptRegistry;
   }
 
   // === Status ===
@@ -28,23 +30,6 @@ class BaseAgent extends EventEmitter {
     return this;
   }
 
-  // === Prompt Parts ===
-
-  registerPromptPart(name, priority, provider) {
-    this._promptBuilder.register(name, priority, provider);
-    return this;
-  }
-
-  unregisterPromptPart(name) {
-    this._promptBuilder.unregister(name);
-    return this;
-  }
-
-  invalidatePromptPart(name) {
-    this._promptBuilder.invalidate(name);
-    return this;
-  }
-
   // === Destroy ===
 
   destroy() {

package/src/agent/index.js

@@ -5,6 +5,7 @@ const { MainAgent } = require('./main');
 const { SubAgent } = require('./sub');
 const { WorkerAgent } = require('./worker');
 const { SystemPromptBuilder } = require('./prompt');
+const { PromptRegistry } = require('./prompt-registry');
 
 /**
  * Create a MainAgent instance
@@ -51,6 +52,7 @@ function createSubAgent(framework, config = {}) {
     framework,
     maxRetries: config.maxRetries,
     disableTools: config.disableTools,
+    hidden: config.hidden,
   });
   _syncPromptParts(framework, subagent);
   framework._agents.push(subagent);
@@ -84,16 +86,25 @@ function _mergeAIConfig(framework, target) {
 
 /**
  * Sync main agent prompt parts to subagent
+ * 从 framework.promptRegistry 同步到 subagent.promptRegistry
  */
 function _syncPromptParts(framework, subagent) {
-  if (!framework._mainAgent?._systemPromptBuilder?._parts) return;
-  const mainParts = framework._mainAgent._systemPromptBuilder._parts;
-  const registeredNames = new Set(subagent._promptParts?.map(p => p.name) || []);
-  for (const [name, part] of mainParts) {
-    if (['original-prompt', 'shared-prompt', 'datetime', 'metadata', 'capabilities'].includes(name)) continue;
-    if (!registeredNames.has(name)) {
-      subagent.registerPromptPart(name, part.priority, part.provider);
-      registeredNames.add(name);
+  const reg = framework?.promptRegistry;
+  if (!reg || reg.count() === 0) return;
+  const subReg = subagent?.promptRegistry || subagent?._promptRegistry;
+  for (const part of reg.list()) {
+    // 跳过主 Agent 私有的 5 个内置 part
+    if (part.owner === '_main' && ['original-prompt', 'shared-prompt', 'datetime', 'metadata', 'capabilities'].includes(part.name)) {
+      continue;
+    }
+    // 已同步过则跳过
+    if (subReg && subReg.has(part.owner, part.name)) continue;
+    if (subReg) {
+      subReg.register(part.owner, part.name, part.provider, {
+        slot: part.slot,
+        order: part.order,
+        description: part.description,
+      });
     }
   }
 }
@@ -104,6 +115,7 @@ module.exports = {
   SubAgent,
   WorkerAgent,
   SystemPromptBuilder,
+  PromptRegistry,
   createAgent,
   createSubAgent,
   createSessionAgent,

package/src/agent/main.js

@@ -7,7 +7,7 @@
 
 const { BaseAgent } = require('./base');
 const { Logger, LOG_LEVELS } = require('../common/logger');
-const { PROMPT_PRIORITY, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_TEMPERATURE } = require('../common/constants');
+const { PROMPT_PRIORITY, PROMPT_PRIORITY_TO_SLOT, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_TEMPERATURE } = require('../common/constants');
 const { SystemPromptBuilder } = require('./prompt');
 const os = require('os');
 
@@ -44,6 +44,10 @@ class MainAgent extends BaseAgent {
     this._skipSyncTools = config.skipSyncTools || false;
     this._subAgents = new Map();
     this._systemPromptBuilder = new SystemPromptBuilder();
+    this._systemPromptCache = null; // 确保首次调用 _buildSystemPrompt 不走早期返回
+    this._systemPromptDirty = true;
+    // 新注册表：默认 part 注册到 framework.promptRegistry（带 slot）
+    // _systemPromptBuilder 保留为降级兜底
     this._registerDefaultPromptParts();
     this.systemPrompt = this._buildSystemPrompt();
 
@@ -54,25 +58,48 @@ class MainAgent extends BaseAgent {
   }
 
   _registerDefaultPromptParts() {
-    this._systemPromptBuilder.register('original-prompt', PROMPT_PRIORITY.ORIGINAL_PROMPT, () => this._originalPrompt);
-    this._systemPromptBuilder.register('shared-prompt', PROMPT_PRIORITY.SHARED_PROMPT, () => {
+    // 优先注册到 framework.promptRegistry（带 slot 的新路径）
+    // 同时保留 _systemPromptBuilder 的旧路径以兼容老 Plugin.registerPromptPart
+    const reg = this.framework?.promptRegistry;
+    const MAIN = '_main';
+
+    const registerBoth = (name, priority, provider, slot) => {
+      // 旧路径（降级兜底）
+      this._systemPromptBuilder.register(name, priority, provider);
+      // 新路径（slot 排序）
+      // original-prompt 是 per-Agent 的，不走全局注册表（由 _buildSystemPrompt 直接注入）
+      if (name === 'original-prompt') return;
+      if (reg && !reg.has(MAIN, name)) {
+        reg.register(MAIN, name, provider, {
+          slot: slot || PROMPT_PRIORITY_TO_SLOT[name] || 'CUSTOM',
+          order: priority,
+          description: `内置 part: ${name}`,
+        });
+      }
+    };
+
+    registerBoth('original-prompt', PROMPT_PRIORITY.ORIGINAL_PROMPT, () => this._originalPrompt, 'IDENTITY');
+    registerBoth('shared-prompt', PROMPT_PRIORITY.SHARED_PROMPT, () => {
       return this._sharedPrompt ? this._replacePlaceholders(this._sharedPrompt) : null;
-    });
-    this._systemPromptBuilder.register('datetime', PROMPT_PRIORITY.DATETIME, () => {
+    }, 'USER');
+    registerBoth('metadata', PROMPT_PRIORITY.METADATA, () => {
       const now = new Date();
       const timeStr = now.toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' });
       const dateStr = now.toLocaleDateString('zh-CN', { timeZone: 'Asia/Shanghai', weekday: 'long' });
-      return `【当前时间】${timeStr}（${dateStr}）`;
-    });
-    this._systemPromptBuilder.register('metadata', PROMPT_PRIORITY.METADATA, () => {
-      if (this._metadata.size === 0) return null;
-      const metaParts = ['【元数据】'];
-      for (const [key, value] of this._metadata) {
-        metaParts.push(`- ${key}: ${typeof value === 'object' ? JSON.stringify(value) : value}`);
+      const metaParts = ['【运行环境】'];
+      metaParts.push(`- 当前时间: ${timeStr}（${dateStr}）`);
+      metaParts.push(`- 工作目录: ${this.framework?.getCwd?.() ?? process.cwd()}`);
+      metaParts.push(`- 平台: ${os.platform()} ${os.release()}`);
+      metaParts.push(`- 主机: ${os.hostname()}`);
+      // 插件显式设置的元数据
+      if (this._metadata.size > 0) {
+        for (const [key, value] of this._metadata) {
+          metaParts.push(`- ${key}: ${typeof value === 'object' ? JSON.stringify(value) : value}`);
+        }
       }
       return metaParts.join('\n');
-    });
-    this._systemPromptBuilder.register('capabilities', PROMPT_PRIORITY.CAPABILITIES, () => this._buildCapabilitiesDescription());
+    }, 'USER');
+    registerBoth('capabilities', PROMPT_PRIORITY.CAPABILITIES, () => this._buildCapabilitiesDescription(), 'CAPABILITY');
   }
 
   _getMetadataValue(key) {
@@ -97,18 +124,59 @@ class MainAgent extends BaseAgent {
     if (!plugins || plugins.length === 0) return '';
     const keyPlugins = plugins.filter(p => p.name !== 'defaults' && p.name !== 'agent');
     if (keyPlugins.length === 0) return '';
-    const lines = ['## 系统能力', ''];
-    keyPlugins.forEach((plugin, index) => {
-      const name = plugin.instance?.name || plugin.name || 'unknown';
-      const description = plugin.instance?.description || '无描述';
-      lines.push(`${index + 1}. **${name}**：${description}`);
-    });
+
+    // 按类别分组，输出紧凑列表（工具列表已在 API 层描述，这里仅给出概览）
+    // const categories = {
+    //   core: [], executor: [], io: [], messaging: [], other: [],
+    // };
+    // const catMap = {
+    //   ai: 'core', storage: 'core', 'skill-manager': 'core', 'subagent-manager': 'core',
+    //   session: 'core', scheduler: 'core', workflow: 'core', rules: 'core', audit: 'core',
+    //   tools: 'core', 'plugin-manager': 'core', install: 'core', 'python-loader': 'core',
+    //   'data-splitter': 'core', coordinator: 'core',
+    //   shell: 'executor', python: 'executor', extension: 'executor', mcp: 'executor',
+    //   'file-system': 'io', web: 'io',
+    //   telegram: 'messaging', qq: 'messaging', weixin: 'messaging', feishu: 'messaging', email: 'messaging',
+    // };
+    // for (const p of keyPlugins) {
+    //   const name = p.instance?.name || p.name || 'unknown';
+    //   const cat = catMap[name] || 'other';
+    //   categories[cat].push(name);
+    // }
+    const lines = [];
+    // const lines = ['## 插件概览'];
+    // const catLabels = { core: '核心', executor: '执行器', io: '文件/网络', messaging: '消息', other: '其他' };
+    // for (const [cat, names] of Object.entries(categories)) {
+    //   if (names.length === 0) continue;
+    //   lines.push(`- **${catLabels[cat]}**: ${names.sort().join(', ')}`);
+    // }
     return lines.join('\n');
   }
 
   _buildSystemPrompt() {
     if (!this._systemPromptDirty && this._systemPromptCache !== null) return this._systemPromptCache;
-    this._systemPromptCache = this._systemPromptBuilder.build();
+
+    // 1. Agent 自己的 originalPrompt（per-Agent）
+    const parts = [this._originalPrompt];
+
+    // 2. 全局注册表（skills, tools, extensions 等共享部分，跳过 _main 的 original-prompt）
+    const reg = this.framework?.promptRegistry;
+    if (reg && reg.count() > 0) {
+      try {
+        for (const part of reg.list()) {
+          if (part.owner === '_main' && part.name === 'original-prompt') continue;
+          const content = part.get();
+          if (content && content.trim()) parts.push(content.trim());
+        }
+      } catch (err) {
+        // 注册表 build 失败时降级到旧 builder
+        this._systemPromptCache = this._systemPromptBuilder.build();
+        this._systemPromptDirty = false;
+        return this._systemPromptCache;
+      }
+    }
+
+    this._systemPromptCache = parts.join('\n\n');
     this._systemPromptDirty = false;
     return this._systemPromptCache;
   }
@@ -116,6 +184,7 @@ class MainAgent extends BaseAgent {
   _invalidateSystemPromptCache() {
     this._systemPromptDirty = true;
     this._systemPromptBuilder.invalidateAll();
+    this.framework?.promptRegistry?.invalidateAll();
   }
 
   _refreshContext() {
@@ -158,14 +227,22 @@ class MainAgent extends BaseAgent {
   }
 
   registerPromptPart(name, priority, provider) {
-    this._systemPromptBuilder.register(name, priority, provider);
+    // [DEPRECATED] 推荐使用 framework.prompts.register(this.name, ...)
+    const reg = this.framework?.promptRegistry;
+    if (reg && !reg.has(this.name, name)) {
+      reg.register(this.name, name, provider, {
+        slot: PROMPT_PRIORITY_TO_SLOT[name] || 'CUSTOM',
+        order: priority,
+        description: `Legacy registerPromptPart from ${this.name}`,
+      });
+    }
     this._invalidateSystemPromptCache();
     this._refreshContext();
     return this;
   }
 
   unregisterPromptPart(name) {
-    this._systemPromptBuilder.unregister(name);
+    this.framework?.promptRegistry?.unregister(this.name, name);
     this._invalidateSystemPromptCache();
     this._refreshContext();
     return this;

package/src/agent/prompt-registry.js

@@ -0,0 +1,296 @@
+'use strict';
+
+/**
+ * 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 完全切换到本注册表
+ */
+
+const { EventEmitter } = require('../common/events');
+const { PROMPT_SLOT } = require('../common/constants');
+
+/**
+ * 单个 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 默认
+    this.description = options.description || '';
+    this.metadata = options.metadata || {};
+    this._cached = null;
+    this._dirty = true;
+    this._error = null;
+  }
+
+  get() {
+    if (this._dirty || this._cached === null) {
+      try {
+        const result = this.provider();
+        this._cached = result == null ? null : String(result);
+        this._dirty = false;
+        this._error = null;
+      } catch (e) {
+        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);
+      }
+    }
+    return this._cached;
+  }
+
+  invalidate() {
+    this._dirty = true;
+  }
+}
+
+/**
+ * PromptRegistry 主类
+ */
+class PromptRegistry extends EventEmitter {
+  constructor(options = {}) {
+    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 时检测循环依赖
+    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} 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}
+   */
+  register(owner, name, provider, options = {}) {
+    if (!owner || typeof owner !== 'string') {
+      throw new Error('PromptRegistry.register: owner is required');
+    }
+    if (!name || typeof name !== 'string') {
+      throw new Error('PromptRegistry.register: name is required');
+    }
+    if (typeof provider !== 'function') {
+      throw new Error('PromptRegistry.register: provider must be a function');
+    }
+
+    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 });
+    return part;
+  }
+
+  /**
+   * 注销一个 part
+   * @returns {boolean} 是否真的删除了
+   */
+  unregister(owner, name) {
+    const key = `${owner}::${name}`;
+    const existed = this._parts.delete(key);
+    if (existed) this.emit('unregister', { owner, name });
+    return existed;
+  }
+
+  /**
+   * 清空指定 owner 的所有 parts
+   * @returns {number} 删除的 part 数
+   */
+  clearOwner(owner) {
+    const prefix = `${owner}::`;
+    let count = 0;
+    for (const key of Array.from(this._parts.keys())) {
+      if (key.startsWith(prefix)) {
+        this._parts.delete(key);
+        count++;
+      }
+    }
+    if (count > 0) this.emit('clear-owner', { owner, count });
+    return count;
+  }
+
+  /**
+   * 失效指定 part（下次 build 时重新计算）
+   */
+  invalidate(owner, name) {
+    const part = this._parts.get(`${owner}::${name}`);
+    if (part) {
+      part.invalidate();
+      this.emit('invalidate', { owner, name });
+    }
+    return this;
+  }
+
+  /**
+   * 失效所有 parts
+   */
+  invalidateAll() {
+    for (const part of this._parts.values()) part.invalidate();
+    this.emit('invalidate-all');
+    return this;
+  }
+
+  // ==================== 查询 ====================
+
+  /**
+   * 获取单个 part 实例
+   */
+  getPart(owner, name) {
+    return this._parts.get(`${owner}::${name}`) || null;
+  }
+
+  /**
+   * 是否有指定 part
+   */
+  has(owner, name) {
+    return this._parts.has(`${owner}::${name}`);
+  }
+
+  /**
+   * 列出所有 parts（按 order 排序）
+   */
+  list() {
+    return Array.from(this._parts.values()).sort((a, b) => this._compareOrder(a, b));
+  }
+
+  /**
+   * 按 owner 过滤
+   */
+  listByOwner(owner) {
+    return this.list().filter((p) => p.owner === owner);
+  }
+
+  /**
+   * 按 slot 过滤
+   */
+  listBySlot(slot) {
+    return this.list().filter((p) => p.slot === slot);
+  }
+
+  _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);
+  }
+
+  count() {
+    return this._parts.size;
+  }
+
+  // ==================== 渲染 ====================
+
+  /**
+   * 渲染完整 prompt 文本（按 slot order 拼接）
+   */
+  build() {
+    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()) {
+        const content = part.get();
+        if (content && content.trim()) sections.push(content.trim());
+      }
+      return sections.join('\n\n');
+    } finally {
+      this._building = false;
+    }
+  }
+
+  /**
+   * build() 的语义化别名，调试用
+   */
+  preview() {
+    return this.build();
+  }
+
+  /**
+   * 渲染结构化清单（调试 / 文档生成）
+   * 返回 [{ owner, name, slot, order, length, contentPreview }]
+   */
+  inspect() {
+    return this.list().map((part) => {
+      const content = part.get();
+      return {
+        owner: part.owner,
+        name: part.name,
+        slot: part.slot,
+        order: part.order != null ? part.order : this._slots.get(part.slot)?.order ?? 999,
+        description: part.description,
+        hasContent: Boolean(content && content.trim()),
+        length: content ? content.length : 0,
+        contentPreview: content ? content.slice(0, 80).replace(/\n/g, ' ') : null,
+      };
+    });
+  }
+}
+
+module.exports = { PromptRegistry, PromptPart };

package/src/agent/sub-config.js

@@ -6,84 +6,7 @@
 
 const fs = require('fs');
 const path = require('path');
-
-/**
- * 解析 YAML frontmatter
- */
-function parseFrontmatter(content) {
-  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!match) return null;
-
-  const frontmatter = {};
-  const lines = match[1].split('\n');
-  let currentKey = null;
-
-  for (const line of lines) {
-    // 处理 metadata 嵌套
-    if (currentKey === 'metadata') {
-      if (line.match(/^ {2}[a-zA-Z]/)) {
-        const colonIndex = line.indexOf(':');
-        if (colonIndex > 0) {
-          const key = line.substring(2, colonIndex).trim();
-          const value = line
-            .substring(colonIndex + 1)
-            .trim()
-            .replace(/^["']|["']$/g, '');
-          frontmatter[currentKey][key] = value;
-          continue;
-        }
-      } else if (line.match(/^[a-zA-Z]/)) {
-        currentKey = null;
-        continue;
-      }
-    }
-
-    const colonIndex = line.indexOf(':');
-    if (colonIndex === -1) continue;
-
-    const key = line.substring(0, colonIndex).trim();
-    let value = line.substring(colonIndex + 1).trim();
-
-    // 移除引号
-    if (
-      (value.startsWith('"') && value.endsWith('"')) ||
-      (value.startsWith("'") && value.endsWith("'"))
-    ) {
-      value = value.slice(1, -1);
-    }
-
-    if (key === 'metadata') {
-      currentKey = 'metadata';
-      frontmatter.metadata = {};
-    } else if (key === 'allowed-tools') {
-      frontmatter[key] = value
-        .split(',')
-        .map((v) => v.trim())
-        .filter(Boolean);
-    } else if (key === 'skills') {
-      frontmatter[key] = value
-        .split(',')
-        .map((v) => v.trim())
-        .filter(Boolean);
-    } else if (key === 'tools') {
-      frontmatter[key] = value
-        .split(',')
-        .map((v) => v.trim())
-        .filter(Boolean);
-    } else {
-      frontmatter[key] = value;
-    }
-  }
-
-  return frontmatter;
-}
-
-/**
- * 移除 frontmatter，只保留正文内容
- */
-function stripFrontmatter(content) {
-  return content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
-}
+const { parseFrontmatter, stripFrontmatter } = require('../utils');
 
 class SubAgentConfig {
   constructor(name, filePath) {