foliko 1.1.93 → 2.0.0

package/src/context/session.js

@@ -0,0 +1,33 @@
+'use strict';
+
+/**
+ * SessionContext - 会话级上下文
+ * 管理会话范围内的状态和元数据
+ */
+
+class SessionContext {
+  constructor(options = {}) {
+    this.sessionId = options.sessionId;
+    this.userId = options.userId || null;
+    this.metadata = options.metadata || {};
+    this.createdAt = Date.now();
+    this._data = new Map();
+  }
+
+  set(key, value) { this._data.set(key, value); }
+  get(key) { return this._data.get(key); }
+  has(key) { return this._data.has(key); }
+  delete(key) { return this._data.delete(key); }
+  clear() { this._data.clear(); }
+
+  toJSON() {
+    return {
+      sessionId: this.sessionId,
+      userId: this.userId,
+      metadata: this.metadata,
+      createdAt: this.createdAt,
+    };
+  }
+}
+
+module.exports = { SessionContext };

package/src/context/storage.js

@@ -0,0 +1,30 @@
+'use strict';
+
+/**
+ * ContextStorage - 集中管理所有 AsyncLocalStorage 实例
+ * 提供 Request / Session / Agent 三层上下文隔离
+ */
+
+const { AsyncLocalStorage } = require('async_hooks');
+
+class ContextStorage {
+  constructor() {
+    this._request = new AsyncLocalStorage();
+    this._session = new AsyncLocalStorage();
+    this._agent = new AsyncLocalStorage();
+  }
+
+  // === Request Context ===
+  runRequest(ctx, fn) { return this._request.run(ctx, fn); }
+  getRequest() { return this._request.getStore(); }
+
+  // === Session Context ===
+  runSession(ctx, fn) { return this._session.run(ctx, fn); }
+  getSession() { return this._session.getStore(); }
+
+  // === Agent Context ===
+  runAgent(ctx, fn) { return this._agent.run(ctx, fn); }
+  getAgent() { return this._agent.getStore(); }
+}
+
+module.exports = new ContextStorage();

package/src/executors/mcp-client.js

@@ -0,0 +1,153 @@
+'use strict';
+
+/**
+ * MCP Client Wrapper
+ * 管理 MCP 服务器连接和工具调用
+ */
+
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { createMCPClient } = require('@ai-sdk/mcp');
+const { StdioClientTransport } = require('@modelcontextprotocol/sdk/client/stdio.js');
+const { logger } = require('../common/logger');
+
+const log = logger.child('MCPClient');
+
+class MCPClientWrapper {
+  constructor(options = {}) {
+    this.serverName = options.serverName || 'unknown';
+    this.command = options.command;
+    this.args = options.args || [];
+    this.env = options.env || {};
+    this.timeout = options.timeout || 30000;
+    this.priority = 11;
+    this.client = null;
+    this.connected = false;
+    this.tools = [];
+  }
+
+  async connect() {
+    if (this.connected) return;
+
+    const controller = new AbortController();
+    const timeoutMs = this.timeout || 30000;
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+      let createMCPClientFn;
+      try {
+        const mcpModule = require('@ai-sdk/mcp');
+        createMCPClientFn = mcpModule.createMCPClient || mcpModule.experimental_createMCPClient;
+      } catch (err) {
+        throw new Error('@ai-sdk/mcp not installed. Please run: npm install @ai-sdk/mcp');
+      }
+
+      if (!createMCPClientFn) {
+        throw new Error('createMCPClient not available');
+      }
+
+      const { which, shellResolve } = this._resolveCommand(this.command);
+
+      try {
+        const { Experimental_StdioMCPTransport } = require('@ai-sdk/mcp/mcp-stdio');
+        const transport = new Experimental_StdioMCPTransport({
+          command: which || this.command,
+          args: shellResolve ? [shellResolve, ...this.args] : this.args,
+          env: { ...process.env, ...this.env },
+        });
+        this.client = await createMCPClientFn({
+          transport,
+          signal: controller.signal,
+        });
+      } catch (transportErr) {
+        log.error(` Transport error:`, transportErr.message);
+        throw transportErr;
+      }
+
+      if (typeof this.client.tools === 'function') {
+        const toolsObject = await this.client.tools();
+        this.tools = Object.entries(toolsObject)
+          .filter(([, tool]) => tool != null)
+          .map(([name, tool]) => ({ ...tool, name }));
+      } else if (this.client.tools && typeof this.client.tools.list === 'function') {
+        const listResult = await this.client.tools.list();
+        this.tools = listResult.tools || [];
+      }
+
+      this.connected = true;
+    } catch (err) {
+      if (controller.signal.aborted) {
+        log.error(` Connection timeout (${timeoutMs}ms) for ${this.serverName}`);
+        throw new Error(`连接超时 (${timeoutMs}ms): ${this.serverName}`);
+      }
+      log.error(` Failed to connect to ${this.serverName}:`, err.message);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  _resolveCommand(cmd) {
+    const isWindows = process.platform === 'win32';
+    const ext = isWindows ? '.cmd' : '';
+    const withExt = cmd + ext;
+
+    try {
+      const result = spawn.sync(withExt, ['--version'], {
+        stdio: 'ignore',
+        timeout: 2000,
+      });
+      if (result.error?.code !== 'ENOENT') {
+        return { which: withExt, shellResolve: null };
+      }
+    } catch (e) { /* ignore */ }
+
+    const globalCommands = isWindows
+      ? [
+          path.join(process.env.APPDATA || '', 'npm', withExt),
+          path.join(process.env.PROGRAMDATA || 'C:\\ProgramData', 'npm', withExt),
+        ]
+      : ['/usr/local/bin/' + cmd, '/usr/bin/' + cmd];
+
+    for (const cmdPath of globalCommands) {
+      try {
+        if (fs.existsSync(cmdPath)) {
+          return { which: cmdPath, shellResolve: null };
+        }
+      } catch (e) { /* ignore */ }
+    }
+
+    return { which: cmd, shellResolve: null };
+  }
+
+  async callTool(toolName, args) {
+    if (!this.connected) await this.connect();
+    if (!this.client) throw new Error('MCP client not initialized');
+
+    let toolsObject;
+    if (typeof this.client.tools === 'function') {
+      toolsObject = await this.client.tools();
+    } else if (this.client.tools && typeof this.client.tools.list === 'function') {
+      const listResult = await this.client.tools.list();
+      toolsObject = listResult.tools || {};
+    } else {
+      throw new Error('Cannot get tools from MCP client');
+    }
+
+    const tool = toolsObject[toolName];
+    if (!tool) throw new Error(`Tool not found: ${toolName}`);
+
+    return await tool.execute(args);
+  }
+
+  async disconnect() {
+    if (this.client) {
+      try { await this.client.destroy(); } catch (e) { /* ignore */ }
+      this.client = null;
+      this.connected = false;
+      this.tools = [];
+    }
+  }
+}
+
+module.exports = { MCPClientWrapper };

package/src/executors/mcp-desc.js

@@ -0,0 +1,236 @@
+'use strict';
+
+/**
+ * MCP 描述构建和 Schema 格式化
+ * 为 Agent 系统提示词构建 MCP 工具描述，及参数 schema 的 Markdown 文档生成
+ */
+
+const { z } = require('zod');
+const { zodSchemaToMarkdown } = require('@chnak/zod-to-markdown');
+const { jsonSchemaToZod } = require('../tool/schema');
+const { logger } = require('../common/logger');
+
+const log = logger.child('MCPDesc');
+
+/**
+ * 从 inputSchema 中提取实际 schema
+ */
+function extractSchema(inputSchema) {
+  if (!inputSchema) return {};
+  if (inputSchema.jsonSchema) return inputSchema.jsonSchema;
+  if (inputSchema.inputSchema) return inputSchema.inputSchema;
+  return inputSchema;
+}
+
+/**
+ * 构建 MCP 服务器描述文本
+ * @param {Map} clients - MCP 客户端 Map
+ */
+function buildMCPServersDescription(clients) {
+  if (clients.size === 0) return '';
+
+  let desc = '## 【MCP Servers】 工具合集\n\n';
+  desc += 'MCP 服务器工具已注册为 `服务器_工具名` 格式（如 github_search）。\n';
+  desc += '通过 `ext_call` 调用：\n\n';
+
+  for (const [serverName, info] of clients) {
+    desc += `### ${serverName}\n\n`;
+    for (const tool of info.tools) {
+      const fullName = `${serverName}_${tool.name}`;
+      desc += `- **${fullName}**: ${tool.description || '无描述'}\n`;
+      desc += bindMcpParamsDesc(tool.inputSchema);
+    }
+    desc += '\n';
+  }
+
+  desc += '**调用格式:**\n';
+  desc += '```\next_call({ plugin: "mcp", tool: "服务器_工具名", args: {参数} })\n';
+  desc += '```\n';
+  return desc.trim();
+}
+
+/**
+ * 为单个 MCP 工具生成参数描述 Markdown
+ */
+function bindMcpParamsDesc(rawSchema) {
+  let desc = '';
+  const schema = extractSchema(rawSchema);
+  if (!schema) return desc;
+
+  try {
+    let schemaResult = null;
+    let zodSchemaForFallback = null;
+
+    const isZodSchema =
+      typeof schema.shape === 'function' || (schema._def && schema._def.typeName);
+    if (isZodSchema) {
+      schemaResult = zodSchemaToMarkdown(schema);
+      zodSchemaForFallback = schema;
+    } else if (schema.jsonSchema) {
+      const zodSchema = jsonSchemaToZod(schema.jsonSchema || schema);
+      if (zodSchema) {
+        schemaResult = zodSchemaToMarkdown(zodSchema);
+        zodSchemaForFallback = zodSchema;
+      }
+    } else if (schema.properties) {
+      const zodSchema = jsonSchemaToZod(schema);
+      if (zodSchema) {
+        schemaResult = zodSchemaToMarkdown(zodSchema);
+        zodSchemaForFallback = zodSchema;
+      }
+    }
+
+    if (schemaResult) {
+      const hasUnparsedTypes = /\|.*\bZod\w+\b.*\|/.test(schemaResult);
+      const hasOnlyType =
+        /^-\s+\w+:\s+.+\n?$/.test(schemaResult.trim()) && !schemaResult.includes('`');
+      if (hasUnparsedTypes || hasOnlyType) {
+        desc += fallbackParamsDesc(zodSchemaForFallback || schema);
+      } else {
+        desc += `**参数:**\n\n${schemaResult}\n\n`;
+      }
+    }
+  } catch (e) {
+    try { desc += fallbackParamsDesc(zodSchemaForFallback || schema); } catch (e2) { /* ignore */ }
+  }
+  return desc;
+}
+
+/**
+ * 回退的参数描述（当 zodSchemaToMarkdown 失败时）
+ */
+function fallbackParamsDesc(schema) {
+  const props = schema.properties || {};
+  const required = schema.required || [];
+
+  if (Object.keys(props).length > 0) {
+    let desc = '**参数:**\n\n';
+    for (const [key, prop] of Object.entries(props)) {
+      const isRequired = required.includes(key);
+      const type = prop.type || 'any';
+      const desc_text = prop.description || '';
+      desc += `- \`${key}\`${isRequired ? ' (必填)' : ''}: ${type} ${desc_text}\n`;
+    }
+    return desc + '\n';
+  }
+
+  if (typeof schema.shape === 'function' || (schema._def && schema._def.shape)) {
+    const shape = typeof schema.shape === 'function' ? schema.shape() : schema._def.shape();
+    if (shape && typeof shape === 'object') {
+      let desc = '**参数:**\n\n';
+      for (const [key, field] of Object.entries(shape)) {
+        const typeInfo = extractZodFieldType(field);
+        const isOptional = typeInfo.isOptional ? ' (可选)' : ' (必填)';
+        desc += `- \`${key}\`${isOptional}: ${typeInfo.type}\n`;
+      }
+      return desc + '\n';
+    }
+  }
+
+  return '';
+}
+
+/**
+ * 从 Zod schema 字段提取类型信息
+ */
+function extractZodFieldType(field) {
+  if (!field) return { type: 'unknown', isOptional: false, description: '' };
+
+  const typeName = field._def?.typeName || field.constructor?.name || '';
+  const description = field.description || field._def?.description || '';
+
+  switch (typeName) {
+    case 'ZodOptional': {
+      const inner = field._def?.innerType;
+      if (!inner) return { type: 'optional', isOptional: true, description };
+      const innerInfo = extractZodFieldType(inner);
+      return { ...innerInfo, isOptional: true };
+    }
+    case 'ZodArray': {
+      const inner = field._def?.type;
+      if (!inner) return { type: 'array', isOptional: false, description };
+      const innerInfo = extractZodFieldType(inner);
+      return { type: `${innerInfo.type}[]`, isOptional: false, description };
+    }
+    case 'ZodObject': {
+      const shapeFn = field._def?.shape;
+      if (typeof shapeFn !== 'function') return { type: 'object', isOptional: false, description };
+      const shape = shapeFn();
+      if (!shape) return { type: 'object', isOptional: false, description };
+      return { type: `object{${Object.keys(shape).join(', ')}}`, isOptional: false, description };
+    }
+    case 'ZodString':
+      return { type: 'string', isOptional: false, description };
+    case 'ZodNumber':
+      return { type: 'number', isOptional: false, description };
+    case 'ZodBoolean':
+      return { type: 'boolean', isOptional: false, description };
+    case 'ZodEnum': {
+      const values = field._def?.values;
+      return values
+        ? { type: values.map((v) => `"${v}"`).join(' | '), isOptional: false, description }
+        : { type: 'enum', isOptional: false, description };
+    }
+    case 'ZodUnion': {
+      const options = field._def?.options;
+      return options
+        ? { type: `union(${options.map((opt) => extractZodFieldType(opt).type).join(' | ')})`, isOptional: false, description }
+        : { type: 'union', isOptional: false, description };
+    }
+    case 'ZodLiteral':
+      return { type: JSON.stringify(field._def?.value), isOptional: false, description };
+    case 'ZodRecord': {
+      const keyType = extractZodFieldType(field._def?.keyType);
+      const valueType = extractZodFieldType(field._def?.valueType);
+      return { type: `record<${keyType?.type || 'any'}, ${valueType?.type || 'any'}>`, isOptional: false, description };
+    }
+    case 'ZodMap': {
+      const keyType = extractZodFieldType(field._def?.keyType);
+      const valueType = extractZodFieldType(field._def?.valueType);
+      return { type: `map<${keyType?.type || 'any'}, ${valueType?.type || 'any'}>`, isOptional: false, description };
+    }
+    case 'ZodSet': {
+      const valueType = extractZodFieldType(field._def?.valueType);
+      return { type: `set<${valueType?.type || 'any'}>`, isOptional: false, description };
+    }
+    case 'ZodAny':
+      return { type: 'any', isOptional: false, description };
+    case 'ZodUnknown':
+      return { type: 'unknown', isOptional: false, description };
+    case 'ZodNever':
+      return { type: 'never', isOptional: false, description };
+    case 'ZodNull':
+      return { type: 'null', isOptional: false, description };
+    case 'ZodUndefined':
+      return { type: 'undefined', isOptional: false, description };
+    case 'ZodDate':
+      return { type: 'date', isOptional: false, description };
+    case 'ZodBigInt':
+      return { type: 'bigint', isOptional: false, description };
+    case 'ZodFunction':
+      return { type: 'function', isOptional: false, description };
+    case 'ZodLazy':
+      return { type: 'lazy', isOptional: false, description };
+    case 'ZodNativeEnum':
+      return { type: 'nativeEnum', isOptional: false, description };
+    case 'ZodDefault': {
+      const inner = field._def?.innerType;
+      if (!inner) return { type: 'default', isOptional: false, description };
+      return extractZodFieldType(inner);
+    }
+    case 'ZodEffects':
+      return { type: 'effects', isOptional: false, description };
+    case 'ZodPipeline':
+      return { type: 'pipeline', isOptional: false, description };
+    default:
+      return { type: typeName.replace('Zod', '').toLowerCase() || 'any', isOptional: false, description };
+  }
+}
+
+module.exports = {
+  extractSchema,
+  buildMCPServersDescription,
+  bindMcpParamsDesc,
+  fallbackParamsDesc,
+  extractZodFieldType,
+};