foliko 1.0.87 → 1.1.0

package/src/core/framework.js

@@ -10,6 +10,9 @@ const { PluginManager } = require('./plugin-manager');
 const { ToolRegistry } = require('./tool-registry');
 const { Agent } = require('./agent');
 const { SubAgentConfigManager } = require('./sub-agent-config');
+const { ContextManager } = require('./context-manager');
+const { SessionContext } = require('./session-context');
+const { SessionStorageAdapter, getDefaultAdapter } = require('./session-storage');
 
 // 添加框架目录的 node_modules 到全局搜索路径
 // 让项目插件能 require 框架内置的包（如 zod）
@@ -18,9 +21,14 @@ if (!module.paths.includes(frameworkNodeModules)) {
   module.paths.unshift(frameworkNodeModules);
 }
 
-// AsyncLocalStorage 实现真正的上下文隔离（支持并行处理）
+// 现有的 AsyncLocalStorage（保持向后兼容）
 const asyncLocalStorage = new AsyncLocalStorage();
 
+// 新增：三层 AsyncLocalStorage
+const requestStorage = new AsyncLocalStorage(); // Request 级别
+const sessionStorage = new AsyncLocalStorage(); // Session 级别
+const agentStorage = new AsyncLocalStorage(); // Agent 级别
+
 class Framework extends EventEmitter {
   /**
    * @param {Object} config - 配置
@@ -48,6 +56,20 @@ class Framework extends EventEmitter {
     // 执行上下文（工具调用时可用）
     this._executionContext = null;
 
+    // ========== 分层上下文系统 ==========
+    // Context 管理器
+    this._contextManager = new ContextManager(this);
+
+    // SessionContext 缓存（轻量管理，不依赖 ContextManager）
+    this._sessionContexts = new Map(); // sessionId → SessionContext
+
+    // Session 存储适配器（默认使用文件存储）
+    this._sessionStorage = null;
+    this._sessionStorageConfig = config.sessionStorage || {
+      type: 'file',
+      baseDir: '.agent/sessions',
+    };
+
     // 事件转发 - ToolRegistry 事件
     this.toolRegistry.on('tool:registered', (tool) => {
       this.emit('tool:registered', tool);
@@ -283,6 +305,239 @@ class Framework extends EventEmitter {
    */
   clearExecutionContext() {}
 
+  // ============================================================================
+  // 分层上下文系统 - Session Context
+  // ============================================================================
+
+  /**
+   * 获取或创建 SessionContext
+   * @param {string} sessionId - 会话 ID
+   * @param {Object} options - 配置选项
+   * @returns {SessionContext}
+   */
+  getOrCreateSessionContext(sessionId, options = {}) {
+    if (!sessionId) {
+      return null;
+    }
+
+    // 先检查内存缓存
+    let ctx = this._sessionContexts.get(sessionId);
+    if (ctx) {
+      return ctx;
+    }
+
+    // 尝试从存储同步加载（仅文件存储支持）
+    const storage = this._getSessionStorage();
+    const loadedCtx = SessionContext.loadSync(sessionId, this, { ...options, storage });
+    if (loadedCtx) {
+      this._sessionContexts.set(sessionId, loadedCtx);
+      this.emit('session:context-created', loadedCtx);
+      return loadedCtx;
+    }
+
+    // 创建新的 SessionContext
+    ctx = new SessionContext(sessionId, this, { ...options, storage });
+    this._sessionContexts.set(sessionId, ctx);
+    this.emit('session:context-created', ctx);
+    return ctx;
+  }
+
+  /**
+   * 异步加载 SessionContext（如果存在）
+   * @param {string} sessionId
+   * @param {Object} options
+   * @returns {Promise<SessionContext|null>}
+   */
+  async loadSessionContext(sessionId, options = {}) {
+    if (!sessionId) {
+      return null;
+    }
+
+    // 先检查内存缓存
+    let ctx = this._sessionContexts.get(sessionId);
+    if (ctx) {
+      return ctx;
+    }
+
+    const storage = this._getSessionStorage();
+    ctx = await SessionContext.load(sessionId, this, { ...options, storage });
+    if (ctx) {
+      this._sessionContexts.set(sessionId, ctx);
+      this.emit('session:context-created', ctx);
+    }
+    return ctx;
+  }
+
+  /**
+   * 获取 Session 存储适配器
+   * @returns {SessionStorageAdapter}
+   * @private
+   */
+  _getSessionStorage() {
+    if (!this._sessionStorage) {
+      this._sessionStorage = new SessionStorageAdapter(this._sessionStorageConfig);
+    }
+    return this._sessionStorage;
+  }
+
+  /**
+   * 配置 Session 存储类型
+   * @param {Object} config - 存储配置
+   * @param {string} [config.type='memory'] - 存储类型: 'memory', 'file'
+   * @param {string} [config.baseDir='.agent/sessions'] - 文件存储目录
+   */
+  configureSessionStorage(config) {
+    this._sessionStorageConfig = config;
+    this._sessionStorage = new SessionStorageAdapter(config);
+  }
+
+  /**
+   * 获取当前 Session 存储适配器
+   * @returns {SessionStorageAdapter}
+   */
+  getSessionStorage() {
+    return this._getSessionStorage();
+  }
+
+  /**
+   * 获取 SessionContext
+   * @param {string} sessionId - 会话 ID
+   * @returns {SessionContext|null}
+   */
+  getSessionContext(sessionId) {
+    return this._sessionContexts.get(sessionId) || null;
+  }
+
+  /**
+   * 获取当前 Session 上下文（从 AsyncLocalStorage 获取）
+   * @returns {SessionContext|null}
+   */
+  getCurrentSessionContext() {
+    const store = sessionStorage.getStore();
+    return store?.sessionContext || null;
+  }
+
+  /**
+   * 获取当前 sessionId（从 AsyncLocalStorage 获取）
+   * @returns {string|null}
+   */
+  getCurrentSessionId() {
+    const store = sessionStorage.getStore();
+    return store?.sessionId || null;
+  }
+
+  /**
+   * 在 Session 上下文中执行函数
+   * @param {string} sessionId - 会话 ID
+   * @param {Object} options - Session 选项
+   * @param {Function} fn - 异步函数
+   * @returns {Promise}
+   */
+  runInSession(sessionId, options, fn) {
+    if (!sessionId) {
+      // 无 session，直接执行
+      return fn();
+    }
+
+    const sessionCtx = this.getOrCreateSessionContext(sessionId, options);
+    const context = { sessionContext: sessionCtx, sessionId };
+    return sessionStorage.run(context, fn);
+  }
+
+  /**
+   * 销毁 Session Context
+   * @param {string} sessionId
+   */
+  destroySessionContext(sessionId) {
+    if (this._sessionContexts.has(sessionId)) {
+      const ctx = this._sessionContexts.get(sessionId);
+      ctx.destroy();
+      this._sessionContexts.delete(sessionId);
+
+      // 从存储中删除
+      if (this._sessionStorage) {
+        this._sessionStorage.delete(sessionId).catch(() => {});
+      }
+
+      this.emit('session:context-destroyed', ctx);
+    }
+  }
+
+  /**
+   * 列出所有活跃的 Session ID
+   * @returns {string[]}
+   */
+  listActiveSessions() {
+    return Array.from(this._sessionContexts.keys());
+  }
+
+  // ============================================================================
+  // 分层上下文系统 - Request Context
+  // ============================================================================
+
+  /**
+   * 获取当前 Request 上下文
+   * @returns {Object|null}
+   */
+  getRequestContext() {
+    return requestStorage.getStore() || null;
+  }
+
+  /**
+   * 在 Request 上下文中执行函数
+   * @param {Object} context - Request 上下文
+   * @param {Function} fn - 异步函数
+   * @returns {Promise}
+   */
+  runWithRequestContext(context, fn) {
+    return requestStorage.run(context, fn);
+  }
+
+  // ============================================================================
+  // 分层上下文系统 - Agent Context
+  // ============================================================================
+
+  /**
+   * 获取当前 Agent 上下文
+   * @returns {Object|null}
+   */
+  getAgentContext() {
+    return agentStorage.getStore()?.agentContext || null;
+  }
+
+  /**
+   * 在 Agent 上下文中执行函数
+   * @param {string} agentId - Agent ID
+   * @param {Object} context - Agent 上下文
+   * @param {Function} fn - 异步函数
+   * @returns {Promise}
+   */
+  runWithAgentContext(agentId, context, fn) {
+    return agentStorage.run({ agentId, ...context }, fn);
+  }
+
+  // ============================================================================
+  // 组合上下文
+  // ============================================================================
+
+  /**
+   * 在完整上下文中执行（Request + Session）
+   * @param {Object} requestOptions - Request 选项
+   * @param {string} sessionId - Session ID
+   * @param {Function} fn - 异步函数
+   * @returns {Promise}
+   */
+  async runInContext(requestOptions, sessionId, fn) {
+    const sessionCtx = sessionId ? this.getOrCreateSessionContext(sessionId) : null;
+
+    return requestStorage.run(requestOptions, () => {
+      if (sessionCtx) {
+        return sessionStorage.run({ sessionContext: sessionCtx, sessionId }, fn);
+      }
+      return fn();
+    });
+  }
+
   /**
    * 创建 Agent
    * @param {Object} config - Agent 配置
@@ -484,10 +739,16 @@ class Framework extends EventEmitter {
   }
 
   /**
-   * 销毁框架）
+   * 销毁框架
    */
   async destroy() {
-    // 卸载所有插件）
+    // 刷新所有 Session 存储
+    if (this._sessionStorage) {
+      await this._sessionStorage.flush();
+      await this._sessionStorage.destroy();
+    }
+
+    // 卸载所有插件
     const plugins = this.pluginManager.getAll();
     for (const { name } of plugins) {
       await this.pluginManager.unload(name);

package/src/core/plugin-manager.js

@@ -215,6 +215,13 @@ class PluginManager {
       instance: pluginInstance,
       status: 'registered',
       enabled,
+      // 记录插件来源路径（用于热重载）
+      // 尝试从实例、prototype 或原始 plugin 对象获取
+      sourcePath:
+        pluginInstance._sourcePath ||
+        (plugin.prototype && plugin.prototype._sourcePath) ||
+        plugin._sourcePath ||
+        null,
     });
 
     this.framework.emit('plugin:registered', pluginInstance);
@@ -284,6 +291,11 @@ class PluginManager {
         return pluginInstance;
       }
 
+      // 如果 entry 没有 sourcePath，尝试从 plugin prototype 获取（loadPlugin 直接传入类的情况）
+      if (!entry.sourcePath && typeof plugin === 'function' && plugin.prototype) {
+        entry.sourcePath = plugin.prototype._sourcePath || null;
+      }
+
       // 调用 install
       try {
         await entry.instance.install(this.framework);
@@ -476,6 +488,19 @@ class PluginManager {
           plugin = pluginModule;
         }
 
+        // 记录插件源路径（用于热重载）
+        let sourcePathSet = false;
+        if (typeof plugin === 'function' && plugin.prototype) {
+          plugin.prototype._sourcePath = pluginPath;
+          sourcePathSet = true;
+        } else if (typeof plugin === 'function') {
+          plugin._sourcePath = pluginPath;
+          sourcePathSet = true;
+        }
+        if (sourcePathSet) {
+          this._log.debug(`Set _sourcePath for plugin ${pluginName}: ${pluginPath}`);
+        }
+
         // 获取插件名称
         let resolvedPluginName;
         try {
@@ -639,8 +664,60 @@ class PluginManager {
             await entry.instance.stopBot();
           }
         }
-        // 调用 reload 让插件重新初始化（会调用 install 和 start）
-        await this.reload(name);
+
+        // 如果有 sourcePath，重新 require 文件获取最新代码
+        if (entry.sourcePath) {
+          this._log.info(`Re-requiring plugin '${name}' from ${entry.sourcePath}`);
+          // 清除 require 缓存
+          delete require.cache[require.resolve(entry.sourcePath)];
+          const pluginModule = require(entry.sourcePath);
+
+          let NewPluginClass = pluginModule;
+          if (pluginModule.default) {
+            NewPluginClass = pluginModule.default;
+          }
+
+          // 创建新实例
+          let newInstance;
+          if (typeof NewPluginClass === 'function') {
+            if (NewPluginClass.prototype instanceof require('./plugin-base')) {
+              newInstance = new NewPluginClass();
+            } else {
+              newInstance = NewPluginClass();
+            }
+          } else {
+            newInstance = NewPluginClass;
+          }
+
+          // 复制 sourcePath 到新实例（prototype 上的属性不会自动继承）
+          if (entry.sourcePath) {
+            newInstance._sourcePath = entry.sourcePath;
+          }
+
+          // 复制 config 到新实例（用户配置需要保留）
+          if (entry.instance && entry.instance.config) {
+            newInstance.config = { ...entry.instance.config };
+          }
+
+          // 替换旧实例
+          entry.instance = newInstance;
+
+          // 调用 install
+          await newInstance.install(this.framework);
+
+          // 调用 start
+          await newInstance.start(this.framework);
+          newInstance._started = true;
+
+          // 通知监听器（如 extension-executor-plugin）重新扫描
+          this.framework.emit('plugin:reloaded', newInstance);
+
+          this._log.info(`Plugin '${name}' re-required from ${entry.sourcePath}`);
+        } else {
+          this._log.info(`No sourcePath for plugin '${name}', calling reload() only`);
+          // 没有 sourcePath，只调用 reload
+          await this.reload(name);
+        }
       } catch (err) {
         this._log.error(`Enable/reload failed for '${name}':`, err.message);
       }

package/src/core/request-context.js

@@ -0,0 +1,98 @@
+/**
+ * RequestContext - Request 级别的上下文封装
+ *
+ * 职责：
+ * 1. 追踪请求链路（requestId, traceId）
+ * 2. 管理请求级超时
+ * 3. 传递请求元数据
+ */
+
+const { uuid } = require('../utils/id');
+
+class RequestContext {
+  /**
+   * @param {Object} options - 配置选项
+   * @param {string} [options.requestId] - 请求 ID，默认自动生成
+   * @param {string} [options.traceId] - 追踪 ID，默认自动生成
+   * @param {string} [options.parentSpanId] - 父 span ID
+   * @param {number} [options.timeout] - 超时时间（毫秒），默认 120000
+   * @param {boolean} [options.isStream] - 是否为流式请求
+   * @param {string} [options.userId] - 用户标识
+   */
+  constructor(options = {}) {
+    this.requestId = options.requestId || `req_${uuid()}`;
+    this.traceId = options.traceId || `trace_${uuid()}`;
+    this.traceId = options.traceId || generateId();
+    this.parentSpanId = options.parentSpanId || null;
+
+    this.timeout = options.timeout || 120000; // 默认 2 分钟
+    this.startTime = options.startTime || Date.now();
+
+    this.isStream = options.isStream || false;
+    this.userId = options.userId || null;
+
+    // 请求级状态
+    this.cancelled = false;
+    this.abortController = null;
+
+    // 元数据
+    this.metadata = options.metadata || {};
+  }
+
+  /**
+   * 创建 AbortController（延迟初始化）
+   * @returns {AbortController}
+   */
+  getAbortController() {
+    if (!this.abortController) {
+      this.abortController = new AbortController();
+    }
+    return this.abortController;
+  }
+
+  /**
+   * 检查是否超时
+   * @returns {boolean}
+   */
+  isTimeout() {
+    return Date.now() - this.startTime > this.timeout;
+  }
+
+  /**
+   * 取消请求
+   */
+  cancel() {
+    this.cancelled = true;
+    if (this.abortController) {
+      this.abortController.abort();
+    }
+  }
+
+  /**
+   * 获取请求耗时（毫秒）
+   * @returns {number}
+   */
+  getElapsed() {
+    return Date.now() - this.startTime;
+  }
+
+  /**
+   * 获取请求摘要
+   * @returns {Object}
+   */
+  toJSON() {
+    return {
+      requestId: this.requestId,
+      traceId: this.traceId,
+      parentSpanId: this.parentSpanId,
+      timeout: this.timeout,
+      startTime: this.startTime,
+      elapsed: this.getElapsed(),
+      isStream: this.isStream,
+      userId: this.userId,
+      cancelled: this.cancelled,
+    };
+  }
+}
+
+module.exports = { RequestContext };