@ohos-cpf/3rdloop 0.0.8 → 0.0.9

package/vendor/MCP/src/library/KBToolProvider.js

@@ -0,0 +1,229 @@
+/**
+ * KBToolProvider —— 知识库工具提供者
+ *
+ * 封装 Archive 的 DocSearchEngine，将其搜索/文档管理/索引管理能力
+ * 以 MCP 内置工具形式（前缀 `kb_`）注册到 ToolRegistry。
+ *
+ * 设计原则：
+ *   - 高内聚：所有知识库相关的工具定义、引擎生命周期、调用分发集中于此。
+ *   - 低耦合：不直接依赖 MCP SDK，只产出纯数据（工具定义 + handler），
+ *     由 Gateway 负责注册到 MCP Server。
+ *   - 延迟初始化：引擎在 register() 时仅注册工具定义（不启动引擎），
+ *     首次调用搜索类工具时才惰性 init()，避免 Gateway 启动阻塞。
+ *
+ * 工具清单（前缀 kb_）：
+ *   - kb_search          全文搜索（FTS5 + BM25 Rerank + jieba 中文分词）
+ *   - kb_add_document    添加/更新文档
+ */
+
+import path from 'node:path';
+import { createLogger } from '../library/logger.js';
+
+const log = createLogger('KBToolProvider');
+
+/** 知识库工具前缀 */
+const KB_PREFIX = 'kb_';
+
+class KBToolProvider {
+    /**
+     * @param {import('../types.js').KnowledgeBaseConfig} config
+     */
+    constructor(config) {
+        this._config = config;
+        /** @type {import('../../Archive/src/engine.js').default | null} */
+        this._engine = null;
+        this._initialized = false;
+        this._initPromise = null;
+    }
+
+    // ─── 生命周期 ──────────────────────────────────────────────────────────────
+
+    /**
+     * 惰性初始化引擎（并发安全：多次调用复用同一 Promise）。
+     * @returns {Promise<void>}
+     */
+    async _ensureInit() {
+        if (this._initialized) return;
+        if (!this._initPromise) {
+            this._initPromise = this._doInit();
+        }
+        await this._initPromise;
+    }
+
+    /**
+     * 实际执行引擎初始化。
+     * @private
+     */
+    async _doInit() {
+        // 动态导入 Archive 引擎，避免未启用知识库时加载失败
+        const { DocSearchEngine } = await import(this._config.enginePath);
+
+        this._engine = new DocSearchEngine();
+
+        const initOptions = {
+            dataDir: this._config.dataDir,
+            catalogs: this._config.catalogs,
+        };
+
+        await this._engine.init(initOptions);
+        this._initialized = true;
+
+        const status = await this._engine.getStatus();
+        log.info('知识库引擎已初始化', {
+            dataDir: this._config.dataDir,
+            documentCount: status.documentCount,
+            segmentCount: status.segmentCount,
+            dbSizeBytes: status.dbSizeBytes,
+        });
+    }
+
+    /**
+     * 关闭引擎，释放资源。
+     * @returns {Promise<void>}
+     */
+    async shutdown() {
+        if (this._engine) {
+            try {
+                await this._engine.close();
+            } catch (err) {
+                log.warn('关闭知识库引擎时出错', { error: err.message });
+            }
+            this._engine = null;
+            this._initialized = false;
+            this._initPromise = null;
+        }
+    }
+
+    // ─── 工具注册 ──────────────────────────────────────────────────────────────
+
+    /**
+     * 返回所有知识库工具定义（含 handler）。
+     * 每个工具包含 name / source / description / inputSchema / _handler。
+     *
+     * @returns {Array<{name:string, source:'builtin', description:string, inputSchema:Object, _handler:(args:Object)=>Promise<Object>}>}
+     */
+    getTools() {
+        return [
+            this._searchTool(),
+            this._addDocumentTool(),
+        ];
+    }
+
+    // ─── 工具定义 ──────────────────────────────────────────────────────────────
+
+    /**
+     * kb_search — 全文搜索。
+     * @private
+     */
+    _searchTool() {
+        return {
+            name: `${KB_PREFIX}search`,
+            source: 'builtin',
+            description: '知识库全文搜索（FTS5 + BM25 Rerank + jieba 中文分词）。支持按目录过滤、同义词扩展。返回相关度排序的文档片段摘要。',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: {
+                        type: 'string',
+                        description: '搜索关键词（空格分隔多词）',
+                    },
+                    catalog: {
+                        type: 'string',
+                        description: '限定搜索的目录 ID（如 guides/references/best-practices/faqs/releases/roadmap）。不传则全局搜索。',
+                    },
+                    limit: {
+                        type: 'number',
+                        description: '返回结果数量上限，默认 10',
+                    },
+                    includeSnippet: {
+                        type: 'boolean',
+                        description: '是否包含摘要片段，默认 true',
+                    },
+                    snippetMaxChars: {
+                        type: 'number',
+                        description: '摘要最大字符数，默认 200',
+                    },
+                    preferAnd: {
+                        type: 'boolean',
+                        description: '是否优先 AND（全部匹配）策略，默认 false（OR 任一匹配）',
+                    },
+                },
+                required: ['query'],
+            },
+            _handler: async (args) => {
+                await this._ensureInit();
+                const results = await this._engine.search(
+                    { query: args.query },
+                    {
+                        catalog: args.catalog,
+                        limit: args.limit,
+                        includeSnippet: args.includeSnippet,
+                        snippetMaxChars: args.snippetMaxChars,
+                        preferAnd: args.preferAnd,
+                    }
+                );
+                return _textResult(JSON.stringify(results, null, 2));
+            },
+        };
+    }
+
+    /**
+     * kb_add_document — 添加或更新文档。
+     * @private
+     */
+    _addDocumentTool() {
+        return {
+            name: `${KB_PREFIX}add_document`,
+            source: 'builtin',
+            description: '向知识库添加或更新文档（自动分词建索引）。若文档已存在则覆盖更新。',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    documentId: {
+                        type: 'string',
+                        description: '文档唯一标识（如 guides/intro）。禁止包含 .. 或绝对路径。',
+                    },
+                    catalog: {
+                        type: 'string',
+                        description: '所属目录 ID（如 guides/references/best-practices/faqs/releases/roadmap）',
+                    },
+                    title: {
+                        type: 'string',
+                        description: '文档标题（可选，不传则从 Markdown 首个标题提取）',
+                    },
+                    content: {
+                        type: 'string',
+                        description: '文档 Markdown 原文',
+                    },
+                },
+                required: ['documentId', 'catalog', 'content'],
+            },
+            _handler: async (args) => {
+                await this._ensureInit();
+                await this._engine.addDocument({
+                    documentId: args.documentId,
+                    catalog: args.catalog,
+                    title: args.title,
+                    content: args.content,
+                });
+                return _textResult(`文档已添加: ${args.documentId} (catalog: ${args.catalog})`);
+            },
+        };
+    }
+}
+
+// ─── 内部工具函数 ──────────────────────────────────────────────────────────────
+
+/**
+ * 构造文本类型的 CallToolResult。
+ * @param {string} text
+ * @returns {Object}
+ * @private
+ */
+function _textResult(text) {
+    return {
+        content: [{ type: 'text', text }]
+    };
+}
+
+export default KBToolProvider;

package/vendor/MCP/src/library/logger.js

@@ -0,0 +1,60 @@
+/**
+ * 轻量日志工具
+ *
+ * 为 MCP Gateway 各模块提供统一日志接口。
+ * 所有日志输出到 stderr（MCP stdio 协议要求 stdout 仅用于 JSON-RPC）。
+ *
+ * 日志级别通过环境变量 LOG_LEVEL 控制（debug/info/warn/error）。
+ */
+
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+const MIN_LEVEL = LEVELS[process.env.LOG_LEVEL ?? 'info'] ?? LEVELS.info;
+
+const COLORS = {
+    debug: '\x1b[90m',
+    info:  '\x1b[36m',
+    warn:  '\x1b[33m',
+    error: '\x1b[31m',
+    reset: '\x1b[0m'
+};
+
+/**
+ * 格式化日志行。
+ * @param {string} level
+ * @param {string} tag
+ * @param {string} message
+ * @param {object} [meta]
+ * @returns {string}
+ */
+function format(level, tag, message, meta) {
+    const time = new Date().toISOString();
+    const prefix = `${COLORS[level]}${time} [${tag}] ${level.toUpperCase()}${COLORS.reset} ${message}`;
+    if (meta && Object.keys(meta).length > 0) {
+        return `${prefix} ${JSON.stringify(meta)}`;
+    }
+    return prefix;
+}
+
+/**
+ * 创建带标签的日志实例。
+ * @param {string} tag - 模块标签（如 'Gateway'、'ClientPool'）
+ * @returns {{ debug: Function, info: Function, warn: Function, error: Function }}
+ */
+export function createLogger(tag) {
+    return {
+        debug: (msg, meta) => {
+            if (LEVELS.debug >= MIN_LEVEL) console.error(format('debug', tag, msg, meta));
+        },
+        info: (msg, meta) => {
+            if (LEVELS.info >= MIN_LEVEL) console.error(format('info', tag, msg, meta));
+        },
+        warn: (msg, meta) => {
+            if (LEVELS.warn >= MIN_LEVEL) console.error(format('warn', tag, msg, meta));
+        },
+        error: (msg, meta) => {
+            if (LEVELS.error >= MIN_LEVEL) console.error(format('error', tag, msg, meta));
+        }
+    };
+}
+
+export default createLogger;

package/vendor/MCP/src/registry/ScriptRegistry.js

@@ -0,0 +1,238 @@
+/**
+ * ScriptRegistry —— 脚本注册表 + 自动发现
+ *
+ * 职责：
+ *   1. 扫描脚本目录，解析脚本头部 @tool 注释，提取元数据。
+ *   2. 维护脚本工具注册表（toolName → ScriptMeta）。
+ *   3. 支持文件监听（chokidar），脚本增删时自动更新注册表并回调通知。
+ *
+ * 设计原则：
+ *   - 高内聚：所有脚本发现/解析/监听逻辑集中在此模块。
+ *   - 低耦合：不执行脚本，不注册 MCP 工具，只输出 ScriptMeta 数据。
+ *
+ * 脚本头部注释约定：
+ *   # @tool <名称>              — 必填，工具名（中文可用）
+ *   # @description <描述>        — 工具描述，给 AI 理解用途
+ *   # @param <名>: <类型> - <说明>  — 参数定义（类型: string/number/boolean）
+ *   # @example <调用示例>        — 调用示例
+ *
+ * 示例：
+ *   #!/bin/bash
+ *   # @tool git操作
+ *   # @description 执行 Git 操作
+ *   # @param action: string - 操作类型 (clone|pull|push)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import chokidar from 'chokidar';
+import { createLogger } from '../library/logger.js';
+
+const log = createLogger('ScriptRegistry');
+
+/** 只解析脚本前 N 行的注释 */
+const MAX_SCAN_LINES = 20;
+
+class ScriptRegistry {
+    /**
+     * @param {string} scriptsDir       - 脚本目录绝对路径
+     * @param {string[]} allowedExtensions - 允许的扩展名（如 ['.sh', '.py']）
+     */
+    constructor(scriptsDir, allowedExtensions) {
+        this._scriptsDir = scriptsDir;
+        this._allowedExtensions = allowedExtensions;
+        /** @type {Map<string, import('../types.js').ScriptMeta>} */
+        this._scripts = new Map();
+        /** @type {chokidar.FSWatcher | null} */
+        this._watcher = null;
+    }
+
+    /**
+     * 扫描脚本目录，解析所有脚本的元数据并注册。
+     * @returns {Promise<import('../types.js').ScriptMeta[]>}
+     */
+    async scanAll() {
+        this._scripts.clear();
+
+        let files;
+        try {
+            files = fs.readdirSync(this._scriptsDir);
+        } catch (err) {
+            if (err.code === 'ENOENT') {
+                log.warn(`脚本目录不存在: ${this._scriptsDir}`);
+                return [];
+            }
+            throw err;
+        }
+
+        const metas = [];
+        for (const file of files) {
+            const filePath = path.join(this._scriptsDir, file);
+            const meta = this._parseAndRegister(filePath);
+            if (meta) metas.push(meta);
+        }
+
+        log.info(`脚本扫描完成`, { count: metas.length, dir: this._scriptsDir });
+        return metas;
+    }
+
+    /**
+     * 解析单个脚本的元数据并注册到注册表。
+     * @param {string} filePath - 脚本文件绝对路径
+     * @returns {import('../types.js').ScriptMeta | null}
+     * @private
+     */
+    _parseAndRegister(filePath) {
+        let stat;
+        try {
+            stat = fs.statSync(filePath);
+        } catch {
+            return null;
+        }
+        if (!stat.isFile()) return null;
+
+        const ext = path.extname(filePath);
+        if (!this._allowedExtensions.includes(ext)) return null;
+
+        const meta = this._parseScriptMeta(filePath);
+        if (!meta) return null;
+
+        this._scripts.set(meta.toolName, meta);
+        return meta;
+    }
+
+    /**
+     * 解析脚本头部注释，提取 @tool / @description / @param。
+     * @param {string} filePath
+     * @returns {import('../types.js').ScriptMeta | null} 无 @tool 注释返回 null
+     * @private
+     */
+    _parseScriptMeta(filePath) {
+        let content;
+        try {
+            content = fs.readFileSync(filePath, 'utf-8');
+        } catch (err) {
+            log.warn(`读取脚本失败: ${filePath}`, { error: err.message });
+            return null;
+        }
+
+        const lines = content.split('\n').slice(0, MAX_SCAN_LINES);
+
+        let rawName = '';
+        let description = '';
+        const params = [];
+
+        for (const line of lines) {
+            // @tool <名称>
+            const toolMatch = line.match(/@tool\s+(.+)/);
+            if (toolMatch) {
+                rawName = toolMatch[1].trim();
+                continue;
+            }
+
+            // @description <描述>
+            const descMatch = line.match(/@description\s+(.+)/);
+            if (descMatch) {
+                description = descMatch[1].trim();
+                continue;
+            }
+
+            // @param <名>: <类型> - <说明>
+            const paramMatch = line.match(/@param\s+(\w+):\s*(\w+)\s*-\s*(.+)/);
+            if (paramMatch) {
+                params.push({
+                    name: paramMatch[1],
+                    type: paramMatch[2],
+                    description: paramMatch[3].trim(),
+                    required: true
+                });
+                continue;
+            }
+        }
+
+        if (!rawName) return null; // 无 @tool 注释的脚本跳过
+
+        return {
+            toolName: `script_${rawName}`,
+            rawName,
+            description: description || `Script: ${rawName}`,
+            filePath,
+            extension: path.extname(filePath),
+            params
+        };
+    }
+
+    /**
+     * 启动文件监听。脚本增删时自动更新注册表并回调。
+     * @param {(meta: import('../types.js').ScriptMeta, action: 'add'|'remove') => void} onChange
+     */
+    startWatch(onChange) {
+        this._watcher = chokidar.watch(this._scriptsDir, {
+            ignoreInitial: true,
+            persistent: true
+        });
+
+        this._watcher.on('add', (filePath) => {
+            const meta = this._parseAndRegister(filePath);
+            if (meta) {
+                log.info(`脚本新增: ${meta.toolName}`);
+                onChange(meta, 'add');
+            }
+        });
+
+        this._watcher.on('unlink', (filePath) => {
+            for (const [name, meta] of this._scripts) {
+                if (meta.filePath === filePath) {
+                    this._scripts.delete(name);
+                    log.info(`脚本移除: ${name}`);
+                    onChange(meta, 'remove');
+                    break;
+                }
+            }
+        });
+
+        this._watcher.on('error', (err) => {
+            log.error('脚本监听错误', { error: err.message });
+        });
+
+        log.info('脚本热加载监听已启动');
+    }
+
+    /**
+     * 停止文件监听。
+     */
+    async stopWatch() {
+        if (this._watcher) {
+            await this._watcher.close();
+            this._watcher = null;
+            log.info('脚本热加载监听已停止');
+        }
+    }
+
+    /**
+     * 根据 toolName 获取脚本元数据。
+     * @param {string} toolName
+     * @returns {import('../types.js').ScriptMeta | undefined}
+     */
+    get(toolName) {
+        return this._scripts.get(toolName);
+    }
+
+    /**
+     * 获取所有已注册脚本。
+     * @returns {import('../types.js').ScriptMeta[]}
+     */
+    getAll() {
+        return Array.from(this._scripts.values());
+    }
+
+    /**
+     * 获取脚本数量。
+     * @returns {number}
+     */
+    size() {
+        return this._scripts.size;
+    }
+}
+
+export default ScriptRegistry;

package/vendor/MCP/src/registry/ToolRegistry.js

@@ -0,0 +1,111 @@
+/**
+ * ToolRegistry —— 统一工具注册表
+ *
+ * 职责：
+ *   1. 维护所有聚合工具的注册表（下游工具 + 脚本工具 + 内置工具）。
+ *   2. 提供工具的增删查接口，供 Gateway 核心调用。
+ *   3. 检测工具名冲突，后注册同名工具时跳过并记录警告。
+ *
+ * 设计原则：
+ *   - 高内聚：工具注册/查找/删除逻辑集中在此模块。
+ *   - 低耦合：只存储数据，不执行工具调用，不感知 MCP SDK。
+ *
+ * 工具命名规范：
+ *   - 下游工具：{serverName}_{originalToolName}（如 fetch_url）
+ *   - 脚本工具：script_{rawName}（如 script_git操作）
+ *   - 内置工具：gateway_{action}（如 gateway_health）
+ */
+
+import { createLogger } from '../library/logger.js';
+
+const log = createLogger('ToolRegistry');
+
+class ToolRegistry {
+    constructor() {
+        /** @type {Map<string, import('../types.js').AggregatedTool>} */
+        this._tools = new Map();
+    }
+
+    /**
+     * 注册一个工具。若名称已存在则跳过并记录警告。
+     * @param {import('../types.js').AggregatedTool} tool
+     * @returns {boolean} 是否注册成功（false 表示名称冲突被跳过）
+     */
+    register(tool) {
+        if (this._tools.has(tool.name)) {
+            log.warn(`工具名冲突，跳过注册: "${tool.name}"`);
+            return false;
+        }
+        this._tools.set(tool.name, tool);
+        return true;
+    }
+
+    /**
+     * 移除一个工具。
+     * @param {string} name
+     * @returns {boolean} 是否移除成功
+     */
+    unregister(name) {
+        return this._tools.delete(name);
+    }
+
+    /**
+     * 按名称查找工具。
+     * @param {string} name
+     * @returns {import('../types.js').AggregatedTool | undefined}
+     */
+    get(name) {
+        return this._tools.get(name);
+    }
+
+    /**
+     * 判断工具是否已注册。
+     * @param {string} name
+     * @returns {boolean}
+     */
+    has(name) {
+        return this._tools.has(name);
+    }
+
+    /**
+     * 获取所有已注册工具。
+     * @returns {import('../types.js').AggregatedTool[]}
+     */
+    getAll() {
+        return Array.from(this._tools.values());
+    }
+
+    /**
+     * 获取所有工具名。
+     * @returns {string[]}
+     */
+    names() {
+        return Array.from(this._tools.keys());
+    }
+
+    /**
+     * 获取工具总数。
+     * @returns {number}
+     */
+    size() {
+        return this._tools.size;
+    }
+
+    /**
+     * 按来源过滤工具。
+     * @param {import('../types.js').ToolSource} source
+     * @returns {import('../types.js').AggregatedTool[]}
+     */
+    filterBySource(source) {
+        return this.getAll().filter(t => t.source === source);
+    }
+
+    /**
+     * 清空注册表。
+     */
+    clear() {
+        this._tools.clear();
+    }
+}
+
+export default ToolRegistry;