foliko 1.0.87 → 1.1.0

package/src/core/session-context.js

@@ -0,0 +1,341 @@
+/**
+ * SessionContext - Session 级别的上下文封装
+ *
+ * 职责：
+ * 1. 管理 Per-Session 的消息存储
+ * 2. 管理会话变量（variables）
+ * 3. 跟踪会话元数据
+ * 4. 处理上下文压缩状态
+ * 5. 持久化到文件（可选）
+ */
+
+const { SessionStorageAdapter, getDefaultAdapter } = require('./session-storage');
+
+class SessionContext {
+  /**
+   * @param {string} sessionId - 会话 ID
+   * @param {Framework} framework - 框架实例
+   * @param {Object} options - 配置选项
+   * @param {Object} [options.metadata] - 初始元数据
+   * @param {Object} [options.variables] - 初始变量
+   * @param {Array} [options.initialMessages] - 初始消息
+   * @param {SessionStorageAdapter} [options.storage] - 存储适配器
+   * @param {boolean} [options.autoSave=true] - 是否自动保存
+   */
+  constructor(sessionId, framework, options = {}) {
+    this.sessionId = sessionId;
+    this.framework = framework;
+
+    // 存储适配器
+    this._storage = options.storage || getDefaultAdapter();
+    this._autoSave = options.autoSave !== false;
+
+    // 会话变量（可被工具读写）
+    this.variables = new Map();
+    if (options.variables) {
+      for (const [key, value] of Object.entries(options.variables)) {
+        this.variables.set(key, value);
+      }
+    }
+
+    // 元数据
+    this.metadata = {
+      createdAt: Date.now(),
+      lastActive: Date.now(),
+      messageCount: 0,
+      compressionCount: 0,
+      ...options.metadata,
+    };
+
+    // Per-Session 消息存储
+    this.messageStore = {
+      messages: options.initialMessages || [], // 对话历史
+      historyLoaded: false, // 是否已从持久化加载
+      systemPrompt: null, // 当前系统提示词
+    };
+
+    // 压缩状态
+    this.compressionState = {
+      lastCompressedAt: null,
+      lastTokenCount: 0,
+      pendingCompression: false,
+    };
+
+    // 自定义数据插槽
+    this.customData = new Map();
+  }
+
+  // ==================== 消息管理 ====================
+
+  /**
+   * 获取消息历史
+   * @returns {Array} 消息数组
+   */
+  getMessages() {
+    return this.messageStore.messages;
+  }
+
+  /**
+   * 添加消息
+   * @param {Object} message - 消息对象
+   */
+  addMessage(message) {
+    this.messageStore.messages.push(message);
+    this.metadata.messageCount++;
+    this.metadata.lastActive = Date.now();
+    this._autoSaveIfEnabled();
+  }
+
+  /**
+   * 添加多条消息
+   * @param {Array} messages - 消息数组
+   */
+  addMessages(messages) {
+    for (const msg of messages) {
+      this.messageStore.messages.push(msg);
+      this.metadata.messageCount++;
+    }
+    this.metadata.lastActive = Date.now();
+    this._autoSaveIfEnabled();
+  }
+
+  /**
+   * 替换所有消息（用于压缩后同步）
+   * @param {Array} messages - 新消息数组
+   */
+  replaceMessages(messages) {
+    this.messageStore.messages = messages || [];
+    this._autoSaveIfEnabled();
+  }
+
+  /**
+   * 清空消息历史
+   */
+  clearMessages() {
+    this.messageStore.messages = [];
+    this._autoSaveIfEnabled();
+  }
+
+  /**
+   * 如果启用了自动保存，则保存到存储
+   * @private
+   */
+  _autoSaveIfEnabled() {
+    if (this._autoSave) {
+      this.save();
+    }
+  }
+
+  /**
+   * 手动保存到存储（立即保存，不 debounce）
+   * @returns {Promise}
+   */
+  async save() {
+    const data = this.toJSON();
+    await this._storage.saveImmediate(this.sessionId, data);
+  }
+
+  /**
+   * 同步加载（用于文件存储）
+   * @param {string} sessionId
+   * @param {Framework} framework
+   * @param {Object} options
+   * @returns {SessionContext|null}
+   */
+  static loadSync(sessionId, framework, options = {}) {
+    const storage = options.storage || getDefaultAdapter();
+
+    // 只有 file 类型支持同步加载
+    if (storage.type !== 'file') {
+      return null;
+    }
+
+    const fs = require('fs');
+    const path = require('path');
+    const filePath = path.resolve(process.cwd(), storage.baseDir, `${sessionId}.json`);
+
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const data = JSON.parse(content);
+
+      // 恢复 SessionContext
+      const ctx = new SessionContext(sessionId, framework, {
+        ...options,
+        initialMessages: data.messages || [],
+        variables: data.variables || {},
+        metadata: data.metadata || {},
+        storage,
+      });
+
+      ctx.messageStore.historyLoaded = true;
+      return ctx;
+    } catch (err) {
+      console.error(`[SessionContext] Failed to load sync:`, err.message);
+      return null;
+    }
+  }
+
+  /**
+   * 从存储加载（异步）
+   * @param {string} sessionId
+   * @param {Framework} framework
+   * @param {Object} options
+   * @returns {Promise<SessionContext|null>}
+   */
+  static async load(sessionId, framework, options = {}) {
+    const storage = options.storage || getDefaultAdapter();
+    const data = await storage.load(sessionId);
+
+    if (!data) {
+      return null;
+    }
+
+    // 恢复 SessionContext
+    const ctx = new SessionContext(sessionId, framework, {
+      ...options,
+      initialMessages: data.messages || [],
+      variables: data.variables || {},
+      metadata: data.metadata || {},
+    });
+
+    ctx.messageStore.historyLoaded = true;
+    return ctx;
+  }
+
+  /**
+   * 获取消息数量
+   * @returns {number}
+   */
+  getMessageCount() {
+    return this.messageStore.messages.length;
+  }
+
+  // ==================== 变量管理 ====================
+
+  /**
+   * 获取变量
+   * @param {string} key - 变量名
+   * @param {*} defaultValue - 默认值
+   * @returns {*}
+   */
+  getVariable(key, defaultValue = undefined) {
+    return this.variables.get(key) ?? defaultValue;
+  }
+
+  /**
+   * 设置变量
+   * @param {string} key - 变量名
+   * @param {*} value - 变量值
+   */
+  setVariable(key, value) {
+    this.variables.set(key, value);
+    this.touch();
+    this._autoSaveIfEnabled();
+  }
+
+  /**
+   * 删除变量
+   * @param {string} key - 变量名
+   */
+  deleteVariable(key) {
+    this.variables.delete(key);
+  }
+
+  /**
+   * 获取所有变量
+   * @returns {Object}
+   */
+  getAllVariables() {
+    return Object.fromEntries(this.variables);
+  }
+
+  // ==================== 元数据 ====================
+
+  /**
+   * 更新最后活跃时间
+   */
+  touch() {
+    this.metadata.lastActive = Date.now();
+  }
+
+  /**
+   * 获取会话摘要
+   * @returns {Object}
+   */
+  getSummary() {
+    return {
+      sessionId: this.sessionId,
+      messageCount: this.metadata.messageCount,
+      createdAt: this.metadata.createdAt,
+      lastActive: this.metadata.lastActive,
+      variables: this.getAllVariables(),
+    };
+  }
+
+  // ==================== 压缩状态 ====================
+
+  /**
+   * 更新压缩状态
+   * @param {number} tokenCount - 压缩后的 token 数
+   */
+  recordCompression(tokenCount) {
+    this.compressionState.lastCompressedAt = Date.now();
+    this.compressionState.lastTokenCount = tokenCount;
+    this.metadata.compressionCount++;
+  }
+
+  /**
+   * 获取压缩状态
+   * @returns {Object}
+   */
+  getCompressionState() {
+    return { ...this.compressionState };
+  }
+
+  // ==================== 历史加载状态 ====================
+
+  /**
+   * 标记为已加载历史
+   */
+  markHistoryLoaded() {
+    this.messageStore.historyLoaded = true;
+  }
+
+  /**
+   * 检查是否已加载历史
+   * @returns {boolean}
+   */
+  isHistoryLoaded() {
+    return this.messageStore.historyLoaded;
+  }
+
+  // ==================== 生命周期 ====================
+
+  /**
+   * 销毁会话上下文
+   */
+  destroy() {
+    this.variables.clear();
+    this.customData.clear();
+    this.messageStore.messages = [];
+  }
+
+  /**
+   * 导出为 JSON（用于持久化）
+   * @returns {Object}
+   */
+  toJSON() {
+    return {
+      sessionId: this.sessionId,
+      messages: this.messageStore.messages,
+      variables: this.getAllVariables(),
+      metadata: this.metadata,
+    };
+  }
+}
+
+module.exports = { SessionContext };

package/src/core/session-storage.js

@@ -0,0 +1,274 @@
+/**
+ * SessionStorageAdapter - Session 持久化存储适配器
+ *
+ * 支持多种存储后端：
+ * - Memory: 内存存储（默认）
+ * - File: JSON 文件存储
+ * - Future: Database, Redis 等
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class SessionStorageAdapter {
+  /**
+   * @param {Object} options - 配置选项
+   * @param {string} [options.type='memory'] - 存储类型: 'memory', 'file'
+   * @param {string} [options.baseDir='.agent/sessions'] - 文件存储基础目录
+   */
+  constructor(options = {}) {
+    this.type = options.type || 'memory';
+    this.baseDir = options.baseDir || '.agent/sessions';
+
+    if (this.type === 'file') {
+      this._ensureDirectory();
+    }
+
+    // 内存存储
+    this._memoryStore = new Map();
+
+    // 写回队列（用于 debounce）
+    this._writeQueue = null;
+    this._writeTimeout = null;
+  }
+
+  /**
+   * 确保目录存在
+   * @private
+   */
+  _ensureDirectory() {
+    const dir = path.resolve(process.cwd(), this.baseDir);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  /**
+   * 获取存储文件路径
+   * @param {string} sessionId
+   * @returns {string}
+   * @private
+   */
+  _getFilePath(sessionId) {
+    return path.resolve(process.cwd(), this.baseDir, `${sessionId}.json`);
+  }
+
+  /**
+   * 保存 Session 数据
+   * @param {string} sessionId - 会话 ID
+   * @param {Object} data - 要保存的数据
+   * @returns {Promise}
+   */
+  async save(sessionId, data) {
+    if (this.type === 'memory') {
+      this._memoryStore.set(sessionId, data);
+      return;
+    }
+
+    if (this.type === 'file') {
+      // Debounce 写操作，500ms 内的多次保存合并为一次
+      if (this._writeTimeout) {
+        clearTimeout(this._writeTimeout);
+      }
+
+      return new Promise((resolve, reject) => {
+        this._writeQueue = { sessionId, data };
+        this._writeTimeout = setTimeout(async () => {
+          try {
+            await this._writeToFile(this._writeQueue.sessionId, this._writeQueue.data);
+            resolve();
+          } catch (err) {
+            reject(err);
+          } finally {
+            this._writeQueue = null;
+            this._writeTimeout = null;
+          }
+        }, 500);
+      });
+    }
+  }
+
+  /**
+   * 立即保存（不 debounce）
+   * @param {string} sessionId
+   * @param {Object} data
+   */
+  async saveImmediate(sessionId, data) {
+    if (this._writeTimeout) {
+      clearTimeout(this._writeTimeout);
+      this._writeTimeout = null;
+    }
+
+    if (this.type === 'memory') {
+      this._memoryStore.set(sessionId, data);
+      return;
+    }
+
+    if (this.type === 'file') {
+      await this._writeToFile(sessionId, data);
+    }
+  }
+
+  /**
+   * 写入文件
+   * @param {string} sessionId
+   * @param {Object} data
+   * @private
+   */
+  async _writeToFile(sessionId, data) {
+    const filePath = this._getFilePath(sessionId);
+
+    try {
+      // 确保目录存在
+      const dir = path.dirname(filePath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+
+      const content = JSON.stringify(data, null, 2);
+      fs.writeFileSync(filePath, content, 'utf-8');
+    } catch (err) {
+      console.error(`[SessionStorage] Failed to write ${sessionId}:`, err.message);
+      throw err;
+    }
+  }
+
+  /**
+   * 加载 Session 数据
+   * @param {string} sessionId - 会话 ID
+   * @returns {Promise<Object|null>}
+   */
+  async load(sessionId) {
+    if (this.type === 'memory') {
+      return this._memoryStore.get(sessionId) || null;
+    }
+
+    if (this.type === 'file') {
+      const filePath = this._getFilePath(sessionId);
+
+      if (!fs.existsSync(filePath)) {
+        return null;
+      }
+
+      try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return JSON.parse(content);
+      } catch (err) {
+        console.error(`[SessionStorage] Failed to read ${sessionId}:`, err.message);
+        return null;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * 删除 Session 数据
+   * @param {string} sessionId - 会话 ID
+   * @returns {Promise<boolean>}
+   */
+  async delete(sessionId) {
+    if (this.type === 'memory') {
+      return this._memoryStore.delete(sessionId);
+    }
+
+    if (this.type === 'file') {
+      const filePath = this._getFilePath(sessionId);
+
+      if (fs.existsSync(filePath)) {
+        try {
+          fs.unlinkSync(filePath);
+          return true;
+        } catch (err) {
+          console.error(`[SessionStorage] Failed to delete ${sessionId}:`, err.message);
+          return false;
+        }
+      }
+      return false;
+    }
+
+    return false;
+  }
+
+  /**
+   * 列出所有 Session ID
+   * @returns {Promise<string[]>}
+   */
+  async list() {
+    if (this.type === 'memory') {
+      return Array.from(this._memoryStore.keys());
+    }
+
+    if (this.type === 'file') {
+      const dir = path.resolve(process.cwd(), this.baseDir);
+
+      if (!fs.existsSync(dir)) {
+        return [];
+      }
+
+      try {
+        const files = fs.readdirSync(dir);
+        return files.filter((f) => f.endsWith('.json')).map((f) => f.replace(/\.json$/, ''));
+      } catch (err) {
+        console.error(`[SessionStorage] Failed to list sessions:`, err.message);
+        return [];
+      }
+    }
+
+    return [];
+  }
+
+  /**
+   * 强制刷新所有待处理的写操作
+   */
+  async flush() {
+    if (this._writeTimeout) {
+      clearTimeout(this._writeTimeout);
+      this._writeTimeout = null;
+
+      if (this._writeQueue) {
+        await this._writeToFile(this._writeQueue.sessionId, this._writeQueue.data);
+        this._writeQueue = null;
+      }
+    }
+  }
+
+  /**
+   * 销毁存储适配器
+   */
+  async destroy() {
+    await this.flush();
+    this._memoryStore.clear();
+  }
+}
+
+/**
+ * 全局默认存储适配器实例
+ */
+let _defaultAdapter = null;
+
+/**
+ * 获取默认存储适配器
+ * @param {Object} options - 配置选项
+ * @returns {SessionStorageAdapter}
+ */
+function getDefaultAdapter(options = {}) {
+  if (!_defaultAdapter) {
+    _defaultAdapter = new SessionStorageAdapter(options);
+  }
+  return _defaultAdapter;
+}
+
+/**
+ * 设置默认存储适配器
+ * @param {SessionStorageAdapter} adapter
+ */
+function setDefaultAdapter(adapter) {
+  _defaultAdapter = adapter;
+}
+
+module.exports = {
+  SessionStorageAdapter,
+  getDefaultAdapter,
+  setDefaultAdapter,
+};

package/src/executors/mcp-executor.js

@@ -502,7 +502,7 @@ class MCPExecutorPlugin extends Plugin {
   _refreshAgentMCPPrompt(agent) {
     // 检查是否已刷新过（通过检查系统提示词是否已包含 MCP 描述）
     const existingPrompt = agent._originalPrompt || '';
-    if (existingPrompt.includes('[MCP Servers]')) {
+    if (existingPrompt.includes('【MCP Servers】')) {
       return;
     }
 
@@ -532,7 +532,7 @@ class MCPExecutorPlugin extends Plugin {
       return '';
     }
 
-    let desc = '[MCP Servers]\n\n';
+    let desc = '【MCP Servers】 工具合集\n\n';
     desc += '你可以通过 `mcp_call` 工具调用以下 MCP 服务器的工具。\n\n';
 
     for (const [serverName, info] of this._clients) {