foliko 2.0.3 → 2.0.5

package/src/framework/framework.js

@@ -117,6 +117,9 @@ class Framework extends EventEmitter {
     // Coordinator
     this._coordinatorManager = null;
 
+    // Global abort controller for framework.stop()
+    this._abortController = null;
+
     // Session TTL
     this._sessionTTL = new SessionTTL({
       getSessionContexts: () => this._sessionContexts,
@@ -255,7 +258,400 @@ class Framework extends EventEmitter {
 
   // prompts 对象别名（系统提示词注册表）
   get prompts() {
-    return this.promptRegistry;
+    const reg = this.promptRegistry;
+    return {
+      available: true,
+      /**
+       * 注册 prompt part
+       * @param {string} owner 拥有者
+       * @param {string} name part 名
+       * @param {Function} provider () => string|null
+       * @param {Object} [options]
+       * @param {string} [options.scope='global'] 作用域: 'global'|'main'|agentId
+       * @param {number} [options.priority=100] 优先级（越小越靠前）
+       * @param {string} [options.description] 描述
+       */
+      register: (owner, name, provider, options) => reg.register(owner, name, provider, options),
+      /**
+       * 从文件注册 prompt（支持变量插值）
+       * @param {string} owner 拥有者
+       * @param {string} filePath 文件路径
+       * @param {Object} [vars] 变量对象，模板中用 {{varName}} 引用
+       * @param {Object} [options] 同 register 选项
+       */
+      registerFile: (owner, filePath, vars, options) => reg.registerFile(owner, filePath, vars, options),
+      /**
+       * 注销 prompt part
+       */
+      unregister: (owner, name) => reg.unregister(owner, name),
+      /**
+       * 清空指定 owner 的所有 parts
+       */
+      clearOwner: (owner) => reg.clearOwner(owner),
+      /**
+       * 检查是否存在
+       */
+      has: (owner, name) => reg.has(owner, name),
+      /**
+       * 获取单个 part
+       */
+      getPart: (owner, name) => reg.getPart(owner, name),
+      /**
+       * 列出所有 parts（按 priority 排序）
+       */
+      list: () => reg.list(),
+      /**
+       * 按 scope 过滤
+       */
+      listByScope: (scope) => reg.listByScope(scope),
+      /**
+       * 获取适用于指定 agent 的 parts
+       */
+      listForAgent: (agentId) => reg.listForAgent(agentId),
+      /**
+       * 结构化检查（调试用）
+       */
+      inspect: () => reg.inspect(),
+      /**
+       * 渲染完整提示词
+       */
+      build: () => reg.build(),
+      /**
+       * 渲染适用于指定 agent 的 prompt
+       * @param {string|null} agentId agent ID，null 表示主 agent
+       */
+      buildForAgent: (agentId) => reg.buildForAgent(agentId),
+      /**
+       * build() 的语义别名
+       */
+      preview: () => reg.preview(),
+      /**
+       * 失效指定 part
+       */
+      invalidate: (owner, name) => reg.invalidate(owner, name),
+      /**
+       * 失效所有 parts
+       */
+      invalidateAll: () => reg.invalidateAll(),
+      /**
+       * 获取 part 数量
+       */
+      count: () => reg.count(),
+    };
+  }
+
+  // skills 对象别名（技能管理器）
+  get skills() {
+    const self = this;
+    const skillManager = this.pluginManager?.get('skill-manager');
+    if (!skillManager) {
+      return {
+        available: false,
+        list: () => [],
+        get: () => null,
+        has: () => false,
+        register: () => null,
+        remove: () => false,
+        details: () => null,
+        listCommands: () => [],
+        getCommand: () => null,
+        listReferences: () => [],
+        getReference: () => null,
+        listScripts: () => [],
+        getScript: () => null,
+        reload: () => {},
+      };
+    }
+    return {
+      available: true,
+      /**
+       * 列出所有已加载的技能
+       */
+      list: () => skillManager.getAllSkills() || [],
+      /**
+       * 获取单个技能
+       * @param {string} name 技能名称
+       */
+      get: (name) => skillManager.getSkill(name) || null,
+      /**
+       * 检查技能是否存在
+       */
+      has: (name) => skillManager.hasSkill(name) || false,
+      /**
+       * 获取技能详情（包含 metadata、content、path 等）
+       */
+      details: (name) => {
+        const skill = skillManager.getSkill(name);
+        if (!skill) return null;
+        return {
+          name: skill.name,
+          description: skill.metadata?.description || '',
+          content: skill.content || '',
+          path: skill.path || null,
+          metadata: skill.metadata || null,
+          references: skill.references ? Array.from(skill.references.keys()) : [],
+          scripts: skill.scripts ? Array.from(skill.scripts.keys()) : [],
+          fromPlugin: skill.fromPlugin || false,
+        };
+      },
+      /**
+       * 注册一个新 skill（程序化注册，不依赖文件）
+       * @param {string} name 技能名称
+       * @param {string} content 技能内容（markdown）
+       * @param {Object} [metadata] 技能元数据 { description, license, compatibility, allowedTools }
+       * @param {Object} [options] 选项
+       * @param {Array} [options.commands] 命令定义数组
+       * @param {string} [options.path] 技能路径
+       */
+      register: (name, content, metadata = {}, options = {}) => skillManager.register(name, content, metadata, options),
+      /**
+       * 移除 skill
+       * @param {string} name 技能名称
+       */
+      remove: (name) => skillManager.remove(name),
+      /**
+       * 列出技能的所有命令
+       * @param {string} name 技能名称
+       */
+      listCommands: (name) => {
+        const skill = skillManager.getSkill(name);
+        if (!skill || !skill.instance?._commands) return [];
+        return skill.instance._commands.map(cmd => {
+          const extExecutor = self.pluginManager?.get('extension-executor');
+          const toolDef = extExecutor?.getExtensionTool?.('skill', `${name}:${cmd}`);
+          return {
+            name: cmd,
+            description: toolDef?.description || '',
+            options: toolDef?._options || null,
+          };
+        });
+      },
+      /**
+       * 获取技能的单个命令详情
+       * @param {string} name 技能名称
+       * @param {string} command 命令名（不含技能名前缀）
+       */
+      getCommand: (name, command) => {
+        const fullName = `${name}:${command}`;
+        const extExecutor = self.pluginManager?.get('extension-executor');
+        const toolDef = extExecutor?.getExtensionTool?.('skill', fullName);
+        if (!toolDef) return null;
+        return {
+          name: fullName,
+          description: toolDef.description || '',
+          options: toolDef._options || null,
+          inputSchema: toolDef.inputSchema || null,
+        };
+      },
+      /**
+       * 列出技能的所有 reference 文件
+       * @param {string} name 技能名称
+       */
+      listReferences: (name) => skillManager.listReferences(name) || [],
+      /**
+       * 获取 reference 文件内容（按需加载）
+       * @param {string} name 技能名称
+       * @param {string} refName reference 名（不含 .md）
+       */
+      getReference: (name, refName) => skillManager.loadReference(name, refName),
+      /**
+       * 列出技能的所有脚本
+       * @param {string} name 技能名称
+       */
+      listScripts: (name) => skillManager.listScripts(name) || [],
+      /**
+       * 获取脚本内容
+       * @param {string} name 技能名称
+       * @param {string} scriptName 脚本名（含扩展名）
+       */
+      getScript: (name, scriptName) => skillManager.loadScript(name, scriptName),
+      /**
+       * 重载所有技能
+       */
+      reload: () => skillManager.reload(self),
+    };
+  }
+
+  // workflows 对象别名（工作流引擎）
+  get workflows() {
+    const self = this;
+    const workflowPlugin = this.pluginManager?.get('workflow');
+    if (!workflowPlugin) {
+      return {
+        available: false,
+        list: () => [],
+        get: () => null,
+        has: () => false,
+        execute: async () => ({ success: false, error: 'workflow plugin not loaded' }),
+        register: () => null,
+        remove: () => false,
+        reload: () => {},
+      };
+    }
+    return {
+      available: true,
+      /**
+       * 列出所有已加载的工作流
+       */
+      list: () => {
+        const workflows = [];
+        for (const [name, workflow] of workflowPlugin._workflows) {
+          workflows.push({
+            name,
+            description: workflow.description || '',
+            stepCount: workflow.steps?.length || 0,
+            type: workflow.type || 'sequential',
+          });
+        }
+        return workflows;
+      },
+      /**
+       * 获取单个工作流定义
+       */
+      get: (name) => workflowPlugin._workflows.get(name) || null,
+      /**
+       * 检查工作流是否存在
+       */
+      has: (name) => workflowPlugin._workflows.has(name),
+      /**
+       * 执行工作流
+       * @param {string|Object} workflowDef 工作流定义（名称/JSON/JS 代码）
+       * @param {Object} input 工作流输入参数
+       * @param {string} sessionId 会话 ID（可选）
+       */
+      execute: (workflowDef, input = {}, sessionId = null) =>
+        workflowPlugin.executeWorkflow(workflowDef, input, sessionId),
+      /**
+       * 注册工作流定义（程序化注册）
+       * @param {string} name 工作流名称
+       * @param {Object} workflowDef 工作流定义
+       */
+      register: (name, workflowDef) => {
+        if (workflowPlugin._workflows.has(name)) {
+          return { success: false, error: `Workflow "${name}" already exists` };
+        }
+        if (!workflowDef || !workflowDef.steps) {
+          return { success: false, error: 'Invalid workflow: missing steps' };
+        }
+        workflowPlugin._workflows.set(name, workflowDef);
+        // 注册为工具
+        const toolName = `workflow_${name}`;
+        const description = workflowDef.description || `执行工作流: ${name}`;
+        self.registerTool({
+          name: toolName,
+          description,
+          inputSchema: require('zod').object({
+            input: require('zod').object({}).optional().describe('工作流输入参数'),
+          }),
+          execute: async (args, framework) => {
+            let sid = null;
+            const ctx = framework?.getExecutionContext?.();
+            if (ctx?.sessionId) sid = ctx.sessionId;
+            return await workflowPlugin.executeWorkflow(workflowDef, args.input || {}, sid);
+          },
+        });
+        workflowPlugin._workflowTools.set(name, toolName);
+        return { success: true, data: { name, toolName } };
+      },
+      /**
+       * 移除工作流
+       * @param {string} name 工作流名称
+       */
+      remove: (name) => workflowPlugin.remove(name),
+      /**
+       * 获取工作流引擎
+       */
+      getEngine: () => workflowPlugin.getEngine(),
+      /**
+       * 重载工作流
+       */
+      reload: () => workflowPlugin.reload(self),
+    };
+  }
+
+  // rules 对象别名（规则引擎）
+  get rules() {
+    const self = this;
+    const rulesPlugin = this.pluginManager?.get('rules');
+    if (!rulesPlugin) {
+      return {
+        available: false,
+        list: () => [],
+        add: () => null,
+        remove: () => false,
+        test: () => null,
+        stats: () => null,
+      };
+    }
+    return {
+      available: true,
+      /**
+       * 列出所有规则
+       */
+      list: () => rulesPlugin._rules.map(r => ({
+        name: r.name,
+        type: r.type,
+        target: r.target,
+        description: r.description,
+        enabled: r.enabled,
+      })),
+      /**
+       * 添加规则
+       * @param {Object} rule 规则定义
+       */
+      add: (rule) => {
+        const newRule = {
+          name: rule.name,
+          type: rule.type,
+          target: rule.target,
+          pattern: rule.pattern ? new RegExp(rule.pattern) : null,
+          description: rule.description || '',
+          action: rule.action || {},
+          enabled: rule.enabled !== false,
+        };
+        rulesPlugin._rules.push(newRule);
+        return newRule;
+      },
+      /**
+       * 移除规则
+       */
+      remove: (name) => rulesPlugin.removeRule(name),
+      /**
+       * 测试规则匹配
+       * @param {string} target 目标（工具名或事件类型）
+       * @param {Object} input 输入参数
+       */
+      test: (target, input = {}) => {
+        const result = rulesPlugin.evaluate(target, input);
+        return {
+          allowed: result.allowed,
+          ruleName: result.rule?.name || null,
+          ruleType: result.rule?.type || null,
+        };
+      },
+      /**
+       * 获取规则统计
+       */
+      stats: () => ({ ...rulesPlugin._ruleStats }),
+      /**
+       * 检查工具调用
+       */
+      checkToolCall: (toolName, args) => {
+        const result = rulesPlugin.checkToolCall(toolName, args);
+        return { allowed: result.allowed, rule: result.rule };
+      },
+      /**
+       * 检查消息
+       */
+      checkMessage: (message, context) => {
+        const result = rulesPlugin.checkMessage(message, context);
+        return { allowed: result.allowed, rule: result.rule };
+      },
+      /**
+       * 重载规则
+       */
+      reload: () => rulesPlugin.reload(self),
+    };
   }
 
   // plugins 对象别名
@@ -295,7 +691,7 @@ class Framework extends EventEmitter {
   }
 
   // Extension 对象别名
-  get extension() {
+  get extensions() {
     const self = this;
     return {
       tool: (pluginName, tools) => self.registerExtensionTools(pluginName, tools),
@@ -328,6 +724,227 @@ class Framework extends EventEmitter {
     return this.executeTool('ext_call', { plugin, tool, args });
   }
 
+  // storage 对象别名（键值存储）
+  get storage() {
+    const storagePlugin = this.pluginManager?.get('storage');
+    if (!storagePlugin) {
+      return {
+        available: false,
+        get: () => null,
+        set: () => null,
+        delete: () => null,
+        list: () => [],
+        clear: () => null,
+        stats: () => null,
+        compact: () => null,
+      };
+    }
+    return {
+      available: true,
+      /**
+       * 获取存储的值
+       */
+      get: (key, namespace) => {
+        storagePlugin._initStorage();
+        const ns = namespace ? `${namespace}:` : '';
+        return storagePlugin._storageManager.get(`${ns}${key}`);
+      },
+      /**
+       * 设置存储的值
+       */
+      set: (key, value, namespace) => {
+        storagePlugin._initStorage();
+        const ns = namespace ? `${namespace}:` : '';
+        return storagePlugin._storageManager.set(`${ns}${key}`, value);
+      },
+      /**
+       * 删除存储的键（软删除）
+       */
+      delete: (key, namespace) => {
+        storagePlugin._initStorage();
+        const ns = namespace ? `${namespace}:` : '';
+        return storagePlugin._storageManager.delete(`${ns}${key}`);
+      },
+      /**
+       * 列出命名空间下的所有键
+       */
+      list: (namespace) => {
+        storagePlugin._initStorage();
+        const ns = namespace ? `${namespace}:` : '';
+        return storagePlugin._storageManager.list(ns).map(k => k.substring(ns.length));
+      },
+      /**
+       * 清空命名空间下的所有数据
+       */
+      clear: (namespace) => {
+        storagePlugin._initStorage();
+        const ns = namespace ? `${namespace}:` : '';
+        const keys = storagePlugin._storageManager.list(ns);
+        let count = 0;
+        for (const key of keys) {
+          if (storagePlugin._storageManager.delete(key)) count++;
+        }
+        return { cleared: count };
+      },
+      /**
+       * 获取存储统计信息
+       */
+      stats: () => {
+        storagePlugin._initStorage();
+        return storagePlugin._storageManager.getCompactionStats();
+      },
+      /**
+       * 手动触发 compaction
+       */
+      compact: () => storagePlugin._storageManager.compact(),
+      /**
+       * 获取底层 StorageManager
+       */
+      getStore: () => storagePlugin.getStore(),
+    };
+  }
+
+  // sessions 对象别名（会话管理）
+  get sessions() {
+    const self = this;
+    return {
+      /**
+       * 列出所有会话 ID
+       */
+      list: () => Array.from(this._sessionContexts.keys()),
+      /**
+       * 获取会话上下文
+       */
+      get: (sessionId) => this.getSessionContext(sessionId),
+      /**
+       * 创建或获取会话
+       */
+      getOrCreate: (sessionId, options) => this.getOrCreateSessionContext(sessionId, options),
+      /**
+       * 销毁会话
+       */
+      destroy: (sessionId) => this.destroySessionContext(sessionId),
+      /**
+       * 获取当前会话 ID
+       */
+      currentId: () => this.getCurrentSessionId(),
+      /**
+       * 在会话中执行代码
+       */
+      runIn: (sessionId, options, fn) => this.runInSession(sessionId, options, fn),
+    };
+  }
+
+  // mcps 对象别名（MCP 服务器管理）
+  get mcps() {
+    const self = this;
+    const mcpPlugin = this.pluginManager?.get('mcp');
+    if (!mcpPlugin) {
+      return {
+        available: false,
+        list: () => [],
+        get: () => null,
+        has: () => false,
+        addServer: async () => ({ success: false, error: 'mcp plugin not loaded' }),
+        removeServer: async () => false,
+        call: async () => ({ success: false, error: 'mcp plugin not loaded' }),
+        getToolSchema: async () => null,
+        setEnabled: async () => null,
+        reload: async () => null,
+      };
+    }
+    return {
+      available: true,
+      /**
+       * 列出所有已连接的 MCP 服务器
+       */
+      list: () => {
+        const servers = [];
+        for (const [name, info] of mcpPlugin._clients) {
+          servers.push({
+            name,
+            enabled: true,
+            connected: true,
+            tools: info.tools.map((t) => ({ name: t.name, description: t.description })),
+          });
+        }
+        for (const [name, config] of mcpPlugin._serverConfigs) {
+          if (!mcpPlugin._clients.has(name)) {
+            servers.push({ name, enabled: false, connected: false, tools: [] });
+          }
+        }
+        return servers;
+      },
+      /**
+       * 获取 MCP 服务器信息
+       */
+      get: (name) => {
+        const clientInfo = mcpPlugin._clients.get(name);
+        if (!clientInfo) {
+          const config = mcpPlugin._serverConfigs.get(name);
+          return config ? { name, enabled: false, connected: false, tools: [] } : null;
+        }
+        return {
+          name,
+          enabled: true,
+          connected: true,
+          tools: clientInfo.tools.map((t) => ({ name: t.name, description: t.description })),
+        };
+      },
+      /**
+       * 检查 MCP 服务器是否存在
+       */
+      has: (name) => mcpPlugin._clients.has(name) || mcpPlugin._serverConfigs.has(name),
+      /**
+       * 添加 MCP 服务器
+       * @param {Object} config 服务器配置 { name, command, args, env, type, url, headers }
+       */
+      add: (config) => mcpPlugin.addServer(config),
+      /**
+       * 添加 MCP 服务器（add 的别名）
+       */
+      addServer: (config) => mcpPlugin.addServer(config),
+      /**
+       * 移除 MCP 服务器
+       */
+      removeServer: async (name) => {
+        await mcpPlugin.removeServer(name);
+        return true;
+      },
+      /**
+       * 调用 MCP 工具
+       * @param {string} server 服务器名
+       * @param {string} tool 工具名
+       * @param {Object} args 参数
+       */
+      call: async (server, tool, args) => {
+        return await self.executeTool('mcp_call', {
+          server,
+          tool,
+          args_json: JSON.stringify(args || {}),
+        });
+      },
+      /**
+       * 获取工具调用示例
+       */
+      getToolSchema: async (server, tool) => {
+        return await self.executeTool('mcp_tool_schema', { server, tool });
+      },
+      /**
+       * 动态开启/关闭 MCP 服务器
+       */
+      setEnabled: async (server, enabled) => {
+        return await self.executeTool('mcp_set_enabled', { server, enabled });
+      },
+      /**
+       * 重载 MCP 配置
+       */
+      reload: async () => {
+        return await self.executeTool('mcp_reload', {});
+      },
+    };
+  }
+
   getMainAgent() { return this._mainAgent; }
   getSystemPrompt() { return this._mainAgent?._buildSystemPrompt?.() || ''; }
   getPluginInstance(name) { return this.pluginManager.get(name) || null; }
@@ -336,6 +953,36 @@ class Framework extends EventEmitter {
 
   getCwd() { return this._cwd; }
 
+  /**
+   * 获取全局 abort signal，用于中断正在运行的对话
+   */
+  getAbortSignal() {
+    if (!this._abortController || this._abortController.signal.aborted) {
+      this._abortController = new AbortController();
+    }
+    return this._abortController.signal;
+  }
+
+  /**
+   * 立即中断所有正在运行的 Agent 对话
+   */
+  stop() {
+    if (this._abortController) {
+      this._abortController.abort(new Error('用户中断'));
+      this._abortController = null;
+    }
+    // 清空消息队列
+    for (const agent of this._agents) {
+      if (agent._chatHandler?.queueManager) {
+        agent._chatHandler.queueManager.clear();
+      }
+      if (typeof agent.cancelSession === 'function') {
+        agent.cancelSession('default');
+      }
+    }
+    this.emit('framework:stopped');
+  }
+
   registerEventDescription(eventType, description, schema = null) { this.pluginManager.registerEventDescription(eventType, description, schema); return this; }
   getEventDescriptions() { return this.pluginManager.getEventDescriptions(); }
   getEventDescription(eventType) { return this.pluginManager.getEventDescription(eventType); }

package/src/plugin/base.js

@@ -29,10 +29,10 @@ class Plugin {
    *   prompts = [
    *     {
    *       name: 'my-part',
-   *       slot: 'BEHAVIOR',       // 可选，PROMPT_SLOT 中的一个；默认 CUSTOM
-   *       order: 50,              // 可选，覆盖 slot 默认 order
+   *       scope: 'global',         // 可选：'global'|'main'|agentId，默认 'global'
+   *       priority: 50,           // 可选，数字越小越靠前，默认 100
    *       description: '描述',     // 可选
-   *       provider() {            // 'this' 绑定到 plugin 实例；不要用箭头函数
+   *       provider() {             // 'this' 绑定到 plugin 实例；不要用箭头函数
    *         return this._buildSomething();
    *       },
    *     },
@@ -99,8 +99,8 @@ class Plugin {
         // bind 让 provider 中的 this 指向 plugin 实例
         const boundProvider = entry.provider.bind(this);
         reg.register(this.name, entry.name, boundProvider, {
-          slot: entry.slot,
-          order: entry.order,
+          scope: entry.scope,
+          priority: entry.priority,
           description: entry.description,
         });
       } catch (err) {