@ohos-cpf/3rdloop 0.0.7 → 0.0.9

package/vendor/MCP/src/client/MCPClientPool.js

@@ -0,0 +1,220 @@
+/**
+ * MCPClientPool —— 下游 MCP Server 连接池
+ *
+ * 职责：
+ *   1. 管理与下游 MCP Server 的 Client 连接（stdio + remote 两种传输）。
+ *   2. 拉取下游 Server 的工具列表。
+ *   3. 转发工具调用到下游 Server。
+ *   4. 维护连接状态，支持断开与重连。
+ *
+ * 设计原则：
+ *   - 高内聚：所有下游 MCP Client 的连接/调用/断开逻辑集中在此模块。
+ *   - 低耦合：不感知工具注册表和脚本执行器，只提供 connect/listTools/callTool 接口。
+ *   - 错误隔离：单个下游 Server 连接失败不影响其他 Server。
+ *
+ * 支持的传输方式：
+ *   - stdio：spawn 子进程，通过 stdin/stdout 通信 JSON-RPC
+ *   - remote：Streamable HTTP，连接远程 MCP Server URL
+ */
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { createLogger } from '../library/logger.js';
+
+const log = createLogger('ClientPool');
+
+class MCPClientPool {
+    constructor() {
+        /** @type {Map<string, Client>} */
+        this._clients = new Map();
+        /** @type {Map<string, StdioClientTransport | StreamableHTTPClientTransport>} */
+        this._transports = new Map();
+        /** @type {Map<string, import('../types.js').ServerConnectionStatus>} */
+        this._statuses = new Map();
+        /** @type {Map<string, string[]>} 下游原始工具名列表 */
+        this._toolNames = new Map();
+    }
+
+    /**
+     * 连接一个下游 MCP Server。
+     * - 根据 type 选择传输方式（stdio / remote）
+     * - 建立 Client session
+     * - 自动完成 MCP 握手（connect 内部会发送 initialize）
+     *
+     * @param {string} name - Server 名称（用作工具前缀）
+     * @param {import('../types.js').DownstreamServerConfig} config
+     * @returns {Promise<void>}
+     */
+    async connect(name, config) {
+        const transport = _createTransport(name, config);
+        if (!transport) return; // 创建失败已记录错误
+
+        const client = new Client(
+            { name: 'mcp-gateway', version: '1.0.0' },
+            { capabilities: {} }
+        );
+
+        try {
+            // connect() 内部会启动 transport 并完成 initialize 握手
+            await client.connect(transport);
+        } catch (err) {
+            _setStatus(this._statuses, name, false, 0, err.message);
+            log.error(`连接下游 Server "${name}" 失败`, { error: err.message });
+            // 清理已创建但连接失败的资源
+            try { await client.close(); } catch { /* 忽略 */ }
+            return;
+        }
+
+        this._clients.set(name, client);
+        this._transports.set(name, transport);
+        _setStatus(this._statuses, name, true, 0);
+        log.info(`下游 Server "${name}" 连接成功`);
+    }
+
+    /**
+     * 拉取下游 Server 的工具列表。
+     * @param {string} name - Server 名称
+     * @returns {Promise<Array<{ name: string, description: string, inputSchema: Object }>>}
+     *   MCP SDK 的 Tool 对象数组
+     * @throws {Error} Server 未连接或拉取失败
+     */
+    async listTools(name) {
+        const client = this._clients.get(name);
+        if (!client) {
+            throw new Error(`下游 Server "${name}" 未连接`);
+        }
+
+        const result = await client.listTools();
+        const tools = result.tools || [];
+        this._toolNames.set(name, tools.map(t => t.name));
+        _updateStatus(this._statuses, name, { toolCount: tools.length });
+        return tools;
+    }
+
+    /**
+     * 转发工具调用到下游 Server。
+     * @param {string} serverName - Server 名称
+     * @param {string} toolName   - 原始工具名（不含前缀）
+     * @param {Object} args       - 工具参数
+     * @returns {Promise<Object>} MCP CallToolResult
+     * @throws {Error} Server 未连接或调用失败
+     */
+    async callTool(serverName, toolName, args) {
+        const client = this._clients.get(serverName);
+        if (!client) {
+            throw new Error(`下游 Server "${serverName}" 未连接`);
+        }
+
+        const result = await client.callTool({
+            name: toolName,
+            arguments: args
+        });
+
+        // 返回 CallToolResult：{ content: [{ type, text }], isError? }
+        return result;
+    }
+
+    /**
+     * 断开指定 Server 的连接。
+     * @param {string} name
+     * @returns {Promise<void>}
+     */
+    async disconnect(name) {
+        const client = this._clients.get(name);
+        if (client) {
+            try { await client.close(); } catch { /* 忽略关闭错误 */ }
+        }
+        this._clients.delete(name);
+        this._transports.delete(name);
+        this._toolNames.delete(name);
+        _setStatus(this._statuses, name, false, 0, '已断开');
+        log.info(`下游 Server "${name}" 已断开`);
+    }
+
+    /**
+     * 断开所有下游连接。
+     * @returns {Promise<void>}
+     */
+    async disconnectAll() {
+        const names = Array.from(this._clients.keys());
+        await Promise.allSettled(names.map(n => this.disconnect(n)));
+        log.info('所有下游 Server 连接已断开');
+    }
+
+    /**
+     * 获取所有 Server 连接状态。
+     * @returns {import('../types.js').ServerConnectionStatus[]}
+     */
+    getStatuses() {
+        return Array.from(this._statuses.values());
+    }
+
+    /**
+     * 获取已连接的 Server 名称列表。
+     * @returns {string[]}
+     */
+    getConnectedNames() {
+        return Array.from(this._clients.keys());
+    }
+}
+
+// ─── 内部工具函数 ──────────────────────────────────────────────────────────────
+
+/**
+ * 根据 config.type 创建对应的 Transport。
+ * @param {string} name - Server 名称（日志用）
+ * @param {import('../types.js').DownstreamServerConfig} config
+ * @returns {StdioClientTransport | StreamableHTTPClientTransport | null}
+ * @private
+ */
+function _createTransport(name, config) {
+    const type = config.type || 'stdio';
+
+    if (type === 'stdio') {
+        log.info(`连接下游 Server: ${name}`, { type, command: config.command });
+        return new StdioClientTransport({
+            command: config.command,
+            args: config.args,
+            env: { ...process.env, ...config.env }
+        });
+    }
+
+    if (type === 'remote') {
+        log.info(`连接下游 Server: ${name}`, { type, url: config.url });
+        return new StreamableHTTPClientTransport(
+            new URL(config.url),
+            { requestInit: { headers: config.headers || {} } }
+        );
+    }
+
+    log.error(`下游 Server "${name}" 传输类型未知: ${type}`);
+    return null;
+}
+
+/**
+ * 设置/更新 Server 连接状态。
+ * @param {Map} statuses
+ * @param {string} name
+ * @param {boolean} connected
+ * @param {number} [toolCount]
+ * @param {string} [error]
+ * @private
+ */
+function _setStatus(statuses, name, connected, toolCount, error) {
+    statuses.set(name, { name, connected, toolCount: toolCount ?? 0, error });
+}
+
+/**
+ * 部分更新 Server 连接状态。
+ * @param {Map} statuses
+ * @param {string} name
+ * @param {Object} patch
+ * @private
+ */
+function _updateStatus(statuses, name, patch) {
+    const current = statuses.get(name) || { name, connected: false, toolCount: 0 };
+    statuses.set(name, { ...current, ...patch });
+}
+
+export default MCPClientPool;

package/vendor/MCP/src/config/ConfigLoader.js

@@ -0,0 +1,189 @@
+/**
+ * ConfigLoader —— 配置加载与校验
+ *
+ * 职责：
+ *   1. 从 JSON 文件加载 Gateway 配置。
+ *   2. 校验配置字段完整性，缺失字段使用默认值。
+ *   3. 解析相对路径（scriptsDir 相对于配置文件目录）。
+ *
+ * 设计原则：
+ *   - 高内聚：所有配置解析逻辑集中在此模块。
+ *   - 低耦合：只输出纯数据对象，不依赖任何业务模块。
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve, dirname, isAbsolute } from 'node:path';
+import { createLogger } from '../library/logger.js';
+
+const log = createLogger('ConfigLoader');
+
+/** 默认脚本配置 */
+const DEFAULT_SCRIPTS_CONFIG = {
+    enabled: true,
+    hotReload: true,
+    timeout: 30000,
+    allowedExtensions: ['.sh', '.py', '.js']
+};
+
+/** 默认 Gateway 元信息 */
+const DEFAULT_GATEWAY_META = {
+    name: 'mcp-gateway',
+    version: '1.0.0',
+    transport: 'stdio'
+};
+
+/**
+ * 加载并校验 Gateway 配置。
+ *
+ * @param {string} configPath - 配置文件路径（绝对或相对）
+ * @returns {import('../types.js').GatewayConfig}
+ * @throws {Error} 配置文件不存在或格式非法时抛出
+ */
+export function loadConfig(configPath) {
+    const absPath = resolve(configPath);
+
+    let raw;
+    try {
+        raw = readFileSync(absPath, 'utf-8');
+    } catch (err) {
+        throw new Error(`无法读取配置文件: ${absPath} (${err.message})`);
+    }
+
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (err) {
+        throw new Error(`配置文件 JSON 解析失败: ${absPath} (${err.message})`);
+    }
+
+    // 校验必需的顶层结构
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error('配置根节点必须是 JSON 对象');
+    }
+
+    // 合并默认值
+    const config = {
+        downstreamServers: _normalizeDownstreamServers(parsed.downstreamServers),
+        scriptsDir: _normalizeScriptsDir(parsed.scriptsDir, absPath),
+        scripts: { ...DEFAULT_SCRIPTS_CONFIG, ...(parsed.scripts || {}) },
+        knowledgeBase: _normalizeKnowledgeBase(parsed.knowledgeBase, absPath),
+        gateway: { ...DEFAULT_GATEWAY_META, ...(parsed.gateway || {}) }
+    };
+
+    log.info('配置加载完成', {
+        downstreamCount: Object.keys(config.downstreamServers).length,
+        scriptsDir: config.scriptsDir,
+        scriptsEnabled: config.scripts.enabled,
+        kbEnabled: config.knowledgeBase ? config.knowledgeBase.enabled : false
+    });
+
+    return config;
+}
+
+/**
+ * 规范化下游 Server 配置：过滤无效配置、补全默认字段。
+ * 支持两种传输类型：
+ *   - stdio（默认）：本地子进程，需要 command + args
+ *   - remote：远程 HTTP，需要 url，可选 headers
+ * @param {Object} [raw]
+ * @returns {Object<string, import('../types.js').DownstreamServerConfig>}
+ * @private
+ */
+function _normalizeDownstreamServers(raw) {
+    if (!raw || typeof raw !== 'object') return {};
+
+    const result = {};
+    for (const [name, cfg] of Object.entries(raw)) {
+        if (!cfg || typeof cfg !== 'object') {
+            log.warn(`下游 Server "${name}" 配置无效，跳过`);
+            continue;
+        }
+
+        const type = cfg.type || 'stdio';
+
+        if (type === 'stdio') {
+            if (!cfg.command || !Array.isArray(cfg.args)) {
+                log.warn(`下游 Server "${name}" (stdio) 缺少 command 或 args，跳过`);
+                continue;
+            }
+            result[name] = {
+                type: 'stdio',
+                command: cfg.command,
+                args: cfg.args,
+                env: cfg.env || {},
+                enabled: cfg.enabled !== false
+            };
+        } else if (type === 'remote') {
+            if (!cfg.url || typeof cfg.url !== 'string') {
+                log.warn(`下游 Server "${name}" (remote) 缺少 url，跳过`);
+                continue;
+            }
+            result[name] = {
+                type: 'remote',
+                url: cfg.url,
+                headers: cfg.headers || {},
+                enabled: cfg.enabled !== false
+            };
+        } else {
+            log.warn(`下游 Server "${name}" 未知 type: ${type}，跳过`);
+        }
+    }
+    return result;
+}
+
+/**
+ * 规范化脚本目录路径：相对于配置文件目录解析。
+ * @param {string} [raw]
+ * @param {string} configPath
+ * @returns {string}
+ * @private
+ */
+function _normalizeScriptsDir(raw, configPath) {
+    const fallback = resolve(dirname(configPath), 'scripts');
+    if (!raw) return fallback;
+    return isAbsolute(raw) ? raw : resolve(dirname(configPath), raw);
+}
+
+/**
+ * 规范化知识库配置。
+ * 未配置时返回 null（不启用）。配置后解析相对路径并补全默认值。
+ * @param {Object} [raw]
+ * @param {string} configPath - 配置文件绝对路径（用于解析相对路径）
+ * @returns {import('../types.js').KnowledgeBaseConfig | null}
+ * @private
+ */
+function _normalizeKnowledgeBase(raw, configPath) {
+    if (!raw || typeof raw !== 'object') return null;
+
+    const enabled = raw.enabled !== false;
+
+    // enginePath: Archive 引擎入口路径，相对路径基于配置文件目录解析
+    let enginePath = raw.enginePath;
+    if (!enginePath) {
+        log.warn('knowledgeBase.enginePath 未指定，知识库工具将无法加载');
+        enginePath = '';
+    } else if (!isAbsolute(enginePath)) {
+        enginePath = resolve(dirname(configPath), enginePath);
+    }
+
+    // dataDir: 知识库数据目录，相对路径基于配置文件目录解析
+    let dataDir = raw.dataDir;
+    if (!dataDir) {
+        log.warn('knowledgeBase.dataDir 未指定，使用引擎内置默认路径');
+        dataDir = '';
+    } else if (!isAbsolute(dataDir)) {
+        dataDir = resolve(dirname(configPath), dataDir);
+    }
+
+    // catalogs: 目录配置（透传，不校验细节）
+    const catalogs = Array.isArray(raw.catalogs) ? raw.catalogs : undefined;
+
+    return {
+        enabled,
+        enginePath,
+        dataDir,
+        catalogs,
+    };
+}
+
+export default loadConfig;

package/vendor/MCP/src/executor/ScriptExecutor.js

@@ -0,0 +1,110 @@
+/**
+ * ScriptExecutor —— 脚本执行器
+ *
+ * 职责：
+ *   1. 根据脚本扩展名选择解释器（.sh→bash, .py→python3, .js→node）。
+ *   2. 通过 child_process.spawn 执行脚本，参数以 JSON 字符串形式传入。
+ *   3. 捕获 stdout/stderr，超时自动终止。
+ *
+ * 设计原则：
+ *   - 高内聚：所有脚本执行逻辑集中在此模块。
+ *   - 低耦合：不感知工具注册表和 MCP 协议，只接收路径+参数，返回输出。
+ *   - 安全：执行超时自动 SIGTERM，避免僵尸进程。
+ *
+ * 参数传递方式：
+ *   Gateway 将 MCP 工具参数序列化为 JSON 字符串，作为脚本的第一个参数传入。
+ *   脚本内通过 $1（bash）或 sys.argv[1]（python）获取后自行解析。
+ */
+
+import { spawn } from 'node:child_process';
+import { createLogger } from '../library/logger.js';
+
+const log = createLogger('ScriptExecutor');
+
+/** 扩展名 → 解释器映射 */
+const INTERPRETERS = {
+    '.sh': 'bash',
+    '.py': 'python3',
+    '.js': 'node',
+    '.cjs': 'node',
+    '.ts': 'npx',
+    '.mjs': 'node'
+};
+
+class ScriptExecutor {
+    /**
+     * @param {number} timeout - 执行超时（ms）
+     */
+    constructor(timeout) {
+        this._timeout = timeout;
+    }
+
+    /**
+     * 执行脚本，返回 stdout + stderr。
+     *
+     * - 退出码为 0 时，返回 stdout（trim）
+     * - 退出码非 0 时，返回 stdout + stderr + 退出码（便于 AI 排查）
+     * - 超时时自动终止子进程并 reject
+     *
+     * @param {string} filePath   - 脚本文件绝对路径
+     * @param {string} extension  - 文件扩展名
+     * @param {Object} args       - 工具参数（序列化为 JSON 传入脚本）
+     * @returns {Promise<string>} 脚本输出
+     */
+    async execute(filePath, extension, args) {
+        const interpreter = _getInterpreter(extension);
+        const argsJson = JSON.stringify(args);
+
+        log.debug(`执行脚本: ${filePath}`, { interpreter, args: argsJson });
+
+        // .ts 需要通过 npx tsx 执行
+        const cmd = extension === '.ts'
+            ? spawn(interpreter, ['tsx', filePath, argsJson], { stdio: ['pipe', 'pipe', 'pipe'] })
+            : spawn(interpreter, [filePath, argsJson], { stdio: ['pipe', 'pipe', 'pipe'] });
+
+        return new Promise((resolve, reject) => {
+            let stdout = '';
+            let stderr = '';
+
+            cmd.stdout.on('data', (data) => { stdout += data.toString(); });
+            cmd.stderr.on('data', (data) => { stderr += data.toString(); });
+
+            const timer = setTimeout(() => {
+                cmd.kill('SIGTERM');
+                reject(new Error(`脚本执行超时 (${this._timeout}ms): ${filePath}`));
+            }, this._timeout);
+
+            cmd.on('close', (code) => {
+                clearTimeout(timer);
+                if (code === 0) {
+                    resolve(stdout.trim());
+                } else {
+                    // 非零退出码：拼接 stdout + stderr + 退出码，便于 AI 排查
+                    const output = [
+                        stdout.trim(),
+                        stderr.trim() ? `[STDERR]\n${stderr.trim()}` : '',
+                        `[Exit Code: ${code}]`
+                    ].filter(Boolean).join('\n');
+                    resolve(output);
+                }
+            });
+
+            cmd.on('error', (err) => {
+                clearTimeout(timer);
+                reject(new Error(`脚本启动失败: ${err.message}`));
+            });
+        });
+    }
+}
+
+/**
+ * 根据扩展名获取解释器命令。
+ * @param {string} extension
+ * @returns {string}
+ * @private
+ */
+function _getInterpreter(extension) {
+    return INTERPRETERS[extension] || 'bash';
+}
+
+export default ScriptExecutor;