@cicctencent/agent-server 0.1.1

package/dist/cjs/kb/embedding-vector-index.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * @file Embedding Vector Index — 基于 Embedding 的向量索引实现
+ * @description 调用 EmbeddingProvider 生成向量，实现 VectorIndex 接口
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmbeddingVectorIndex = void 0;
+/**
+ * 基于 Embedding Provider 的向量索引
+ * - build() 时为每个 item 的文本生成 embedding
+ * - search() 时将查询文本转为 embedding，然后做余弦相似度搜索
+ */
+class EmbeddingVectorIndex {
+    items = [];
+    embeddingProvider;
+    textExtractor;
+    constructor(embeddingProvider, options) {
+        this.embeddingProvider = embeddingProvider;
+        this.textExtractor = options?.textExtractor || ((item) => item.metadata?.['text'] || '');
+    }
+    async build(items) {
+        const needEmbedding = items.filter(i => !i.vector || i.vector.length === 0);
+        if (needEmbedding.length > 0) {
+            const texts = needEmbedding.map(i => this.textExtractor(i));
+            const embeddings = await this.embeddingProvider.embed(texts);
+            needEmbedding.forEach((item, i) => {
+                item.vector = embeddings[i];
+            });
+        }
+        this.items = items;
+    }
+    async search(query, k) {
+        if (this.items.length === 0)
+            return [];
+        return this.items
+            .filter(item => item.vector && item.vector.length > 0)
+            .map(item => ({
+            item,
+            score: cosineSimilarity(query, item.vector),
+        }))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, k);
+    }
+    async searchText(queryText, k) {
+        const embeddings = await this.embeddingProvider.embed([queryText]);
+        return this.search(embeddings[0], k);
+    }
+    async add(item) {
+        this.items.push(item);
+    }
+    remove(id) {
+        this.items = this.items.filter(i => i.id !== id);
+    }
+    clear() {
+        this.items = [];
+    }
+    size() {
+        return this.items.length;
+    }
+    getItems() {
+        return [...this.items];
+    }
+}
+exports.EmbeddingVectorIndex = EmbeddingVectorIndex;
+function cosineSimilarity(a, b) {
+    let dot = 0, normA = 0, normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom > 0 ? dot / denom : 0;
+}
+//# sourceMappingURL=embedding-vector-index.js.map

package/dist/cjs/kb/embedding-vector-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-vector-index.js","sourceRoot":"","sources":["../../../src/kb/embedding-vector-index.ts"],"names":[],"mappings":"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"}

package/dist/cjs/kb/file-knowledge-base.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @file FileKnowledgeBase — 基于文件的知识库实现
+ * @description 文档分块 + embedding 存储（data/kb/），实现 KnowledgeBase 接口
+ */
+import type { KnowledgeBase, TextChunk, SearchResult, DocMeta, EmbeddingProvider } from '@cicctencent/agent-core';
+/**
+ * 基于文件的知识库实现
+ * - 文档元数据存储在 data/kb/docs.json
+ * - 文本块存储在 data/kb/chunks.json
+ * - 搜索：有 embedding 时用余弦相似度，无时用 TF-IDF 关键词匹配
+ */
+export declare class FileKnowledgeBase implements KnowledgeBase {
+    private docStore;
+    private chunkStore;
+    private embeddingProvider?;
+    constructor(options?: {
+        embeddingProvider?: EmbeddingProvider;
+    });
+    ingest(docId: string, chunks: TextChunk[]): Promise<void>;
+    search(query: string, topK?: number): Promise<SearchResult[]>;
+    remove(docId: string): Promise<void>;
+    list(): Promise<DocMeta[]>;
+    private toTextChunk;
+}
+//# sourceMappingURL=file-knowledge-base.d.ts.map

package/dist/cjs/kb/file-knowledge-base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-knowledge-base.d.ts","sourceRoot":"","sources":["../../../src/kb/file-knowledge-base.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAmBlH;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,OAAO,CAAC,QAAQ,CAA2B;IAC3C,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,iBAAiB,CAAC,CAAoB;gBAElC,OAAO,CAAC,EAAE;QAAE,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;KAAE;IAYzD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA6CzD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAqBhE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpC,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAWhC,OAAO,CAAC,WAAW;CASpB"}

package/dist/cjs/kb/file-knowledge-base.js

@@ -0,0 +1,200 @@
+"use strict";
+/**
+ * @file FileKnowledgeBase — 基于文件的知识库实现
+ * @description 文档分块 + embedding 存储（data/kb/），实现 KnowledgeBase 接口
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileKnowledgeBase = void 0;
+const fs = __importStar(require("fs/promises"));
+const fs_1 = require("fs");
+const data_dir_ts_1 = require("../utils/data-dir.js");
+const agent_core_1 = require("@cicctencent/agent-core");
+/**
+ * 基于文件的知识库实现
+ * - 文档元数据存储在 data/kb/docs.json
+ * - 文本块存储在 data/kb/chunks.json
+ * - 搜索：有 embedding 时用余弦相似度，无时用 TF-IDF 关键词匹配
+ */
+class FileKnowledgeBase {
+    docStore;
+    chunkStore;
+    embeddingProvider;
+    constructor(options) {
+        const kbDir = (0, data_dir_ts_1.getProjectDataPath)('kb');
+        this.docStore = new agent_core_1.JsonStore('kb/docs.json', 0, { projectLocal: true });
+        this.chunkStore = new agent_core_1.JsonStore('kb/chunks.json', 0, { projectLocal: true });
+        this.embeddingProvider = options?.embeddingProvider;
+        // 确保目录存在
+        if (!(0, fs_1.existsSync)(kbDir)) {
+            fs.mkdir(kbDir, { recursive: true }).catch(() => { });
+        }
+    }
+    async ingest(docId, chunks) {
+        const docs = this.docStore.read([]);
+        const chunksAll = this.chunkStore.read([]);
+        // 如果文档已存在，先移除旧数据
+        const filteredChunks = chunksAll.filter(c => c.docId !== docId);
+        const filteredDocs = docs.filter(d => d.id !== docId);
+        // 添加新块
+        const newChunks = chunks.map(c => ({
+            id: c.id,
+            docId,
+            content: c.content,
+            embedding: c.embedding,
+            metadata: c.metadata,
+        }));
+        // 如果有 embedding provider，为没有 embedding 的块生成 embedding
+        if (this.embeddingProvider) {
+            const needEmbedding = newChunks.filter(c => !c.embedding);
+            if (needEmbedding.length > 0) {
+                const texts = needEmbedding.map(c => c.content);
+                const embeddings = await this.embeddingProvider.embed(texts);
+                needEmbedding.forEach((c, i) => {
+                    c.embedding = embeddings[i];
+                });
+            }
+        }
+        filteredChunks.push(...newChunks);
+        this.chunkStore.write(filteredChunks);
+        // 添加文档元数据
+        const docMeta = {
+            id: docId,
+            title: chunks[0]?.metadata?.title || docId,
+            filename: chunks[0]?.metadata?.filename || docId,
+            chunkCount: chunks.length,
+            createdAt: (0, agent_core_1.formatLocalDateTime)(),
+            metadata: chunks[0]?.metadata,
+        };
+        filteredDocs.push(docMeta);
+        this.docStore.write(filteredDocs);
+    }
+    async search(query, topK = 5) {
+        const chunks = this.chunkStore.read([]);
+        if (chunks.length === 0)
+            return [];
+        // 如果有 embedding provider，使用向量搜索
+        if (this.embeddingProvider) {
+            const queryEmbedding = (await this.embeddingProvider.embed([query]))[0];
+            return chunks
+                .filter(c => c.embedding)
+                .map(c => ({
+                chunk: this.toTextChunk(c),
+                score: cosineSimilarity(queryEmbedding, c.embedding),
+            }))
+                .sort((a, b) => b.score - a.score)
+                .slice(0, topK);
+        }
+        // 无 embedding：使用 TF-IDF 关键词匹配
+        return tfidfSearch(query, chunks, topK);
+    }
+    async remove(docId) {
+        const docs = this.docStore.read([]);
+        const chunks = this.chunkStore.read([]);
+        this.docStore.write(docs.filter(d => d.id !== docId));
+        this.chunkStore.write(chunks.filter(c => c.docId !== docId));
+    }
+    async list() {
+        const docs = this.docStore.read([]);
+        return docs.map(d => ({
+            id: d.id,
+            title: d.title,
+            chunkCount: d.chunkCount,
+            createdAt: d.createdAt,
+            metadata: d.metadata,
+        }));
+    }
+    toTextChunk(record) {
+        return {
+            id: record.id,
+            docId: record.docId,
+            content: record.content,
+            embedding: record.embedding,
+            metadata: record.metadata,
+        };
+    }
+}
+exports.FileKnowledgeBase = FileKnowledgeBase;
+// ===== 工具函数 =====
+function cosineSimilarity(a, b) {
+    let dot = 0, normA = 0, normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom > 0 ? dot / denom : 0;
+}
+function tfidfSearch(query, chunks, topK) {
+    const queryTerms = tokenize(query);
+    if (queryTerms.length === 0)
+        return [];
+    // 计算 IDF
+    const docFreq = new Map();
+    for (const chunk of chunks) {
+        const terms = new Set(tokenize(chunk.content));
+        for (const t of terms) {
+            docFreq.set(t, (docFreq.get(t) || 0) + 1);
+        }
+    }
+    const N = chunks.length;
+    // 计算每个块的 TF-IDF 得分
+    return chunks
+        .map(chunk => {
+        const terms = tokenize(chunk.content);
+        const tf = new Map();
+        for (const t of terms) {
+            tf.set(t, (tf.get(t) || 0) + 1);
+        }
+        let score = 0;
+        for (const qt of queryTerms) {
+            const tfVal = tf.get(qt) || 0;
+            const idfVal = Math.log((N + 1) / ((docFreq.get(qt) || 0) + 1)) + 1;
+            score += tfVal * idfVal;
+        }
+        return { chunk: { id: chunk.id, docId: chunk.docId, content: chunk.content, metadata: chunk.metadata }, score };
+    })
+        .filter(r => r.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, topK);
+}
+function tokenize(text) {
+    return text.toLowerCase()
+        .replace(/[^\w\u4e00-\u9fff]/g, ' ')
+        .split(/\s+/)
+        .filter(t => t.length > 1);
+}
+//# sourceMappingURL=file-knowledge-base.js.map

package/dist/cjs/kb/file-knowledge-base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-knowledge-base.js","sourceRoot":"","sources":["../../../src/kb/file-knowledge-base.ts"],"names":[],"mappings":"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"}

package/dist/cjs/mcp/api-bridge-client.d.ts

@@ -0,0 +1,36 @@
+import type { MCPClient, MCPServerConfig, ToolDefinition } from '@cicctencent/agent-core';
+import type { RequestBuilderFn, ResponseConfig } from './api-bridge-types.js';
+/** api-bridge 扩展配置（从 MCPServerConfig.extra 中读取） */
+export interface ApiBridgeExtra {
+    /** 请求构建函数（由 mcp.service 根据 requestBuilderId 注入） */
+    buildRequest: RequestBuilderFn;
+    /** 工具名 -> 映射配置（结构由各 connector builder 解释） */
+    apiMapping: Record<string, Record<string, unknown>>;
+    /** 手动定义的工具列表 */
+    toolDefinitions?: Array<{
+        name: string;
+        description: string;
+        parameters?: Record<string, unknown>;
+    }>;
+    /** 全局响应处理配置（可被 mapping 级 response 覆盖） */
+    response?: ResponseConfig;
+}
+/**
+ * API Bridge 客户端
+ *
+ * 纯粹的 fetch 执行器，不含任何请求构建逻辑。
+ * 连接器通过 RequestBuilderFn 定义如何构建 HTTP 请求（URL、headers、body、代理等），
+ * ApiBridgeClient 仅负责：调用 buildRequest → 执行 fetch → 返回结果。
+ */
+export declare class ApiBridgeClient implements MCPClient {
+    private config;
+    private extra;
+    private connected;
+    private proxyUrl?;
+    connect(config: MCPServerConfig): Promise<void>;
+    listTools(): Promise<ToolDefinition[]>;
+    callTool(name: string, args: Record<string, unknown>): Promise<string>;
+    disconnect(): void;
+    isConnected(): boolean;
+}
+//# sourceMappingURL=api-bridge-client.d.ts.map

package/dist/cjs/mcp/api-bridge-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-bridge-client.d.ts","sourceRoot":"","sources":["../../../src/mcp/api-bridge-client.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC1F,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAI9E,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,YAAY,EAAE,gBAAgB,CAAC;IAC/B,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,gBAAgB;IAChB,eAAe,CAAC,EAAE,KAAK,CAAC;QACtB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACtC,CAAC,CAAC;IACH,yCAAyC;IACzC,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,qBAAa,eAAgB,YAAW,SAAS;IAC/C,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,KAAK,CAAkB;IAC/B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,CAAS;IAEpB,OAAO,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB/C,SAAS,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAYtC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IA6F5E,UAAU,IAAI,IAAI;IAKlB,WAAW,IAAI,OAAO;CAGvB"}

package/dist/cjs/mcp/api-bridge-client.js

@@ -0,0 +1,143 @@
+"use strict";
+// ============================================================
+// ApiBridgeClient — 通用 HTTP API → MCP 桥接客户端
+// 属于应用层 MCP 扩展（server/mcp），非 core 协议实现
+//
+// 纯粹的执行器：不包含任何请求构建逻辑，
+// 通过 extra.buildRequest 委托给连接器的 RequestBuilderFn。
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiBridgeClient = void 0;
+const agent_core_1 = require("@cicctencent/agent-core");
+const jsonpath_plus_1 = require("jsonpath-plus");
+/**
+ * API Bridge 客户端
+ *
+ * 纯粹的 fetch 执行器，不含任何请求构建逻辑。
+ * 连接器通过 RequestBuilderFn 定义如何构建 HTTP 请求（URL、headers、body、代理等），
+ * ApiBridgeClient 仅负责：调用 buildRequest → 执行 fetch → 返回结果。
+ */
+class ApiBridgeClient {
+    config;
+    extra;
+    connected = false;
+    proxyUrl;
+    async connect(config) {
+        const extra = config.extra;
+        if (!extra?.buildRequest) {
+            throw new Error('api-bridge transport requires "buildRequest" function in config.extra');
+        }
+        if (!extra?.apiMapping || Object.keys(extra.apiMapping).length === 0) {
+            throw new Error('api-bridge transport requires "apiMapping" in config.extra');
+        }
+        this.config = config;
+        this.extra = extra;
+        // 创建代理 dispatcher（根据 proxySettings.mcp 分类配置解析）
+        this.proxyUrl = (0, agent_core_1.resolveProxyAgentForCategory)(config.proxyCategory, 'ApiBridge');
+        this.connected = true;
+        console.log(`[ApiBridge][${config.name}] connected — mappingKeys=${Object.keys(extra.apiMapping).join(', ')}${this.proxyUrl ? ' (proxy enabled)' : ''}`);
+    }
+    async listTools() {
+        const toolDefs = this.extra.toolDefinitions || [];
+        return toolDefs.map(t => ({
+            type: 'function',
+            function: {
+                name: t.name,
+                description: t.description || '',
+                parameters: (t.parameters || { type: 'object', properties: {} }),
+            },
+        }));
+    }
+    async callTool(name, args) {
+        const mapping = this.extra.apiMapping?.[name];
+        if (!mapping) {
+            console.error(`[ApiBridge][${this.config.name}] callTool('${name}') FAILED — no apiMapping entry`);
+            throw new Error(`Unknown tool: ${name} (no apiMapping entry)`);
+        }
+        // 委托 builder 构建完整的 fetch 请求参数
+        const { url, init } = await this.extra.buildRequest({
+            toolName: name,
+            args,
+            mapping,
+            extra: this.config.extra,
+        });
+        console.log(`[ApiBridge][${this.config.name}] callTool('${name}')`);
+        console.log(`  -> ${init.method || 'POST'} ${url}`);
+        if (init.body) {
+            const bodyStr = typeof init.body === 'string' ? init.body : JSON.stringify(init.body);
+            console.log(`  -> Body: ${bodyStr.length > 500 ? bodyStr.substring(0, 500) + '...' : bodyStr}`);
+        }
+        // 执行 fetch（含超时控制）
+        const timeout = this.config.timeout || 30000;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeout);
+        const startTime = Date.now();
+        try {
+            const fetchOptions = {
+                ...init,
+                signal: controller.signal,
+            };
+            if (this.proxyUrl)
+                fetchOptions.proxy = this.proxyUrl;
+            const res = await fetch(url, fetchOptions);
+            const duration = Date.now() - startTime;
+            console.log(`  <- Status: ${res.status} ${res.statusText} (${duration}ms)`);
+            if (!res.ok) {
+                const errBody = await res.text().catch(() => '');
+                console.error(`  <- Error Body: ${errBody}`);
+                throw new Error(`API request failed: ${res.status} ${res.statusText} — ${errBody}`);
+            }
+            const data = await res.json();
+            // 响应处理管道：业务错误检测 + JSONPath 数据提取
+            const responseConfig = mapping['response'] ?? this.extra.response;
+            let result = data;
+            if (responseConfig) {
+                // 1. 业务错误检测
+                if (responseConfig.errorField) {
+                    const errValues = (0, jsonpath_plus_1.JSONPath)({ path: responseConfig.errorField, json: data, wrap: true });
+                    const errCode = errValues?.[0];
+                    if (errCode !== undefined && errCode !== null && errCode !== 0 && errCode !== '') {
+                        let errMsg = '';
+                        if (responseConfig.errorMessage) {
+                            const msgValues = (0, jsonpath_plus_1.JSONPath)({ path: responseConfig.errorMessage, json: data, wrap: true });
+                            errMsg = msgValues?.[0] || '';
+                        }
+                        throw new Error(`Business error [${errCode}]: ${errMsg}`);
+                    }
+                }
+                // 2. JSONPath 数据提取
+                if (responseConfig.extract) {
+                    const extracted = (0, jsonpath_plus_1.JSONPath)({ path: responseConfig.extract, json: data, wrap: true });
+                    result = extracted?.length === 1 ? extracted[0] : (extracted || []);
+                }
+            }
+            const resultStr = JSON.stringify(result, null, 2);
+            console.log(`  <- Response (${resultStr.length} chars): ${resultStr.substring(0, 500)}${resultStr.length > 500 ? '...' : ''}`);
+            return resultStr;
+        }
+        catch (e) {
+            const duration = Date.now() - startTime;
+            if (e.name === 'AbortError') {
+                console.error(`  [x] Timed out after ${timeout}ms`);
+                throw new Error(`API request timed out after ${timeout}ms`);
+            }
+            console.error(`  [x] Failed (${duration}ms): ${e?.message || e}`);
+            if (e.cause) {
+                console.error(`  [x] Cause: ${e.cause?.message || e.cause}`);
+            }
+            throw e;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    disconnect() {
+        this.proxyUrl = undefined;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected;
+    }
+}
+exports.ApiBridgeClient = ApiBridgeClient;
+//# sourceMappingURL=api-bridge-client.js.map

package/dist/cjs/mcp/api-bridge-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-bridge-client.js","sourceRoot":"","sources":["../../../src/mcp/api-bridge-client.ts"],"names":[],"mappings":"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"}

package/dist/cjs/mcp/api-bridge-types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @file API Bridge 类型定义 — RequestBuilder 接口 + 认证 + 响应处理
+ * @description 定义 ApiBridgeClient 与请求构建函数之间的通用契约。
+ *              连接器通过 requestBuilderId 指定使用哪个 builder 构建 fetch 请求参数。
+ */
+/** 构建请求函数的输入上下文 */
+export interface BuildRequestContext {
+    /** 工具名称 */
+    toolName: string;
+    /** 工具调用参数 */
+    args: Record<string, unknown>;
+    /** apiMapping 中该工具的配置项 */
+    mapping: Record<string, unknown>;
+    /** 扩展配置（从 MCPServerConfig.extra 透传） */
+    extra: Record<string, unknown>;
+}
+/** 构建请求函数的返回值 — fetch 所需的完整参数 */
+export interface FetchRequestOptions {
+    /** 请求 URL */
+    url: string;
+    /** fetch 初始化选项 */
+    init: RequestInit;
+}
+/**
+ * 请求构建函数
+ *
+ * 由连接器定义，负责将工具调用参数转换为完整的 fetch 请求。
+ * ApiBridgeClient 仅作为执行器调用此函数并发送返回的请求。
+ */
+export type RequestBuilderFn = (ctx: BuildRequestContext) => Promise<FetchRequestOptions>;
+/**
+ * 认证配置
+ *
+ * 支持四种认证方式：
+ * - `bearer`: HTTP Bearer Token（Authorization: Bearer xxx）
+ * - `basic`:  HTTP Basic Auth（Authorization: Basic base64(user:pass)）
+ * - `apiKey`: 自定义 API Key Header（如 X-API-Key: xxx）
+ * - `custom`: 完全自定义 Header 名和值
+ *
+ * value 支持 `${env.VAR_NAME}` 模板，运行时从环境变量读取敏感凭证。
+ */
+export interface AuthConfig {
+    /** 认证方式 */
+    type: 'bearer' | 'basic' | 'apiKey' | 'custom';
+    /**
+     * 认证凭证值
+     * - bearer: token 值
+     * - basic: base64(user:pass) 编码值
+     * - apiKey: key 值
+     * - custom: header 值
+     * 支持 `${env.VAR_NAME}` 模板语法
+     */
+    value: string;
+    /** apiKey/custom 模式下的 header 名称（如 X-API-Key） */
+    name?: string;
+    /** 额外自定义 header 列表 */
+    extraHeaders?: {
+        name: string;
+        value: string;
+    }[];
+}
+/**
+ * 响应处理配置
+ *
+ * 控制 ApiBridgeClient 在 fetch 成功后如何加工响应数据：
+ * - `extract`: JSONPath 表达式提取有效数据（丢弃外层包装）
+ * - `errorField` + `errorMessage`: 业务错误码检测
+ *
+ * 示例：
+ * ```json
+ * {
+ *   "extract": "$.data.items",
+ *   "errorField": "$.errCode",
+ *   "errorMessage": "$.errMsg"
+ * }
+ * ```
+ * 当返回 `{ "errCode": 1001, "errMsg": "not found", "data": null }` 时，
+ * 自动抛出 `Business error [1001]: not found`
+ */
+export interface ResponseConfig {
+    /** JSONPath 表达式，提取有效数据（如 $.data.items），留空则返回完整响应 */
+    extract?: string;
+    /**
+     * 错误码字段路径（JSONPath 表达式，如 $.errCode）
+     * 当该字段值不为 0/null/undefined 时，视为业务错误并抛出异常
+     */
+    errorField?: string;
+    /** 错误消息字段路径（JSONPath 表达式，如 $.errMsg），与 errorField 配合使用 */
+    errorMessage?: string;
+}
+//# sourceMappingURL=api-bridge-types.d.ts.map

package/dist/cjs/mcp/api-bridge-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-bridge-types.d.ts","sourceRoot":"","sources":["../../../src/mcp/api-bridge-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,mBAAmB;AACnB,MAAM,WAAW,mBAAmB;IAClC,WAAW;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,iCAAiC;AACjC,MAAM,WAAW,mBAAmB;IAClC,aAAa;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,kBAAkB;IAClB,IAAI,EAAE,WAAW,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,mBAAmB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAI1F;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB,WAAW;IACX,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC/C;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sBAAsB;IACtB,YAAY,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAClD;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}

package/dist/cjs/mcp/api-bridge-types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * @file API Bridge 类型定义 — RequestBuilder 接口 + 认证 + 响应处理
+ * @description 定义 ApiBridgeClient 与请求构建函数之间的通用契约。
+ *              连接器通过 requestBuilderId 指定使用哪个 builder 构建 fetch 请求参数。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=api-bridge-types.js.map

package/dist/cjs/mcp/api-bridge-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-bridge-types.js","sourceRoot":"","sources":["../../../src/mcp/api-bridge-types.ts"],"names":[],"mappings":";AAAA;;;;GAIG"}

package/dist/cjs/mcp/body-template.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file Body 模板引擎 — 通用 ${param|default} 参数解析
+ * @description 将模板对象中的 ${param} / ${param|default} 占位符替换为实际参数值，
+ *              支持递归解析嵌套对象和数组，类型跟随默认值。
+ */
+/**
+ * 解析 body 模板：将 ${param|default} 替换为实际参数值
+ *
+ * 规则：
+ * - ${code}       → args.code（必须提供，否则返回空字符串）
+ * - ${market|0}   → args.market ?? '0'（可选，带默认值）
+ * - 类型跟随默认值：默认值是字符串则结果也是字符串，数字则数字
+ * - 非模板值（number, boolean, null）保持原样
+ */
+export declare function resolveBodyTemplate(template: Record<string, unknown>, args: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=body-template.d.ts.map

package/dist/cjs/mcp/body-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"body-template.d.ts","sourceRoot":"","sources":["../../../src/mcp/body-template.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMzB"}