@gt-fe/eap-runtime 0.0.20 → 0.0.22

package/dist/graph/nodes/rag/react-loop.js

@@ -0,0 +1,467 @@
+/**
+ * react-loop — RagNode 内部 ReAct 循环（纯逻辑，不依赖 LangGraph）
+ *
+ * 输入输出均为普通对象，可脱离图引擎单独单测。
+ * 循环：LLM 决策（原生 function-calling）→ 三路派发 → 累积 perSource →
+ * 达终止条件后 fuse + denoise（近重去重 + LLM 判定 + 句子抽取）→ 输出；
+ * 判定存活集为空且未重写过 → QUERY_REWRITE 重写 query 清空重查（仅一次，§5.4）。
+ * 空转换源反馈：上一轮零产出 / 产出全被滤除的工具，下一轮决策上下文注入换源提示
+ * （只进决策输入，不落消息历史与最终输出），配合 RAG_REACT 行为规则防同源反复重查。
+ * LLM 永远只"点名"（name + arguments），执行全在代码侧：
+ *   路 A local_search → 进程内直连 IRetriever（结构化 RetrievalDoc[]，零转换）
+ *   路 B 注册工具     → ToolOrchestrator（权限 → 路由 → 执行器），字符串结果归一化
+ *   路 C 未知工具     → 错误 tool 消息回给 LLM（不中断循环）
+ *
+ * @see design-v2 §5.4 / §6
+ */
+import { NodeRetryExecutor, DEFAULT_LLM_RETRY_CONFIG } from '../../retry/index.js';
+import { RAG_REACT } from './prompts.js';
+import { KEYWORD_SEARCH_TOOL_NAME, LOCAL_SEARCH_TOOL_NAME, RAG_FINISH_TOOL_NAME, briefList, } from './tools.js';
+import { normalizeToolResult } from './fusion/normalize.js';
+import { fuse } from './fusion/fuse.js';
+import { dedupExact, sameContent } from './dedup.js';
+import { denoise, rewriteQuery } from './denoise.js';
+const DEFAULT_MAX_ITERATIONS = 5;
+export async function runReactLoop(input) {
+    const maxIterations = input.config.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+    const perSource = new Map();
+    const loopMessages = []; // 循环私有消息，不进主对话
+    const tokenUsage = [];
+    // 空转追踪（换源反馈）：工具 → 本次累计产出文档键集（sourceId:rawId），
+    // 供 rewrite 边界把"产出全被滤"归因到工具
+    const toolDocKeys = new Map();
+    // 上一轮空转的来源（只看上一轮，不累积历史；被提示来源再空转则下一轮继续提示，自然递进）
+    let idleSources = [];
+    let iteration = 0;
+    let query = input.query;
+    let rewritten = false;
+    let outcome;
+    let finalDocs = 0;
+    search: while (true) {
+        while (true) {
+            // 达硬上限必须先于 decide 判：上限轮的决策结果只会被丢弃，再烧一次纯费 token；
+            // 带着已有结果走融合收束，不报错中断
+            if (iteration >= maxIterations)
+                break;
+            // ① 决策调用（主力模型，原生 function-calling）；空转换源提示只进决策上下文
+            const toolCalls = await decide(input, query, loopMessages, tokenUsage, idleHint(idleSources));
+            // 兜底：LLM 既没调工具也没调 rag_finish（不守格式）→ 视为已足够
+            if (!toolCalls || toolCalls.length === 0)
+                break;
+            // rag_finish 是控制信号，不执行任何东西
+            if (toolCalls.some((tc) => tc.name === RAG_FINISH_TOOL_NAME))
+                break;
+            // ② 三路派发（本轮所有 tool_call），先发 rag.round 事件供外部观测
+            emit(input, 'rag.round', {
+                nodeId: input.nodeId,
+                round: iteration + 1,
+                toolCalls: toolCalls.map((tc) => ({ name: tc.name, arguments: tc.arguments })),
+            });
+            const { messages: toolMessages, emptyTools } = await dispatchToolCalls(toolCalls, input, perSource, toolDocKeys);
+            // function-calling 协议：先 assistant（带 toolCalls）再 tool 消息
+            loopMessages.push({ role: 'assistant', content: '', toolCalls }, ...toolMessages);
+            // ③ 空转反馈（返回空子 case）：本轮成功执行但零产出的工具，下一轮提示换源；
+            // "结果全被滤除"子 case 在 rewrite 边界降噪判定后回填（见 ⑦）
+            idleSources = emptyTools.map((tool) => ({ tool, note: '未检索到任何结果' }));
+            // ④ 决策轮 +1（同轮并发多个调用只计 1 次）
+            iteration += 1;
+        }
+        // ⑤ 融合：源内精确去重 → 配额切分
+        const perSourceDeduped = new Map([...perSource.entries()].map(([sourceId, docs]) => [sourceId, dedupExact(docs)]));
+        const merged = fuse(perSourceDeduped, input.config.totalK);
+        // ⑥ 降噪（M4 管线）：近重去重 → LLM 相关性判定 → 句子编号抽取 → 拼装
+        const denoiseSpanId = await startTraceSpan(input, {
+            name: 'rag.denoise',
+            type: 'llm',
+            input: { query, candidates: merged.length },
+        });
+        const denoised = await denoise({
+            query,
+            docs: merged,
+            llmProvider: input.llmProvider,
+            model: input.config.model ?? 'default',
+            nodeId: input.nodeId,
+            nearDupThreshold: input.config.nearDupThreshold,
+            tokenUsage,
+        });
+        await endTraceSpan(input, denoiseSpanId, {
+            status: 'completed',
+            output: { kept: denoised.docs.length, candidates: merged.length },
+        });
+        emit(input, 'rag.denoise', {
+            nodeId: input.nodeId,
+            candidates: merged.length,
+            kept: denoised.docs.length,
+            filtered: denoised.filtered,
+        });
+        // ⑦ 空结果兜底：判定存活集为空且未重写过且有余量 → 重写 query 清空重查一次
+        if (denoised.verdictEmpty && !rewritten && iteration < maxIterations) {
+            const rewrittenQuery = await rewriteQuery({
+                query,
+                reasons: denoised.filtered.map((f) => f.reason),
+                llmProvider: input.llmProvider,
+                model: input.config.model ?? 'default',
+                nodeId: input.nodeId,
+                tokenUsage,
+            });
+            if (rewrittenQuery && rewrittenQuery !== query) {
+                emit(input, 'rag.rewrite', { nodeId: input.nodeId, from: query, to: rewrittenQuery });
+                query = rewrittenQuery;
+                // 空转反馈（全被滤除子 case）：verdictEmpty ⇒ 存活集为空，本次产出过文档的工具
+                // 均为"结果全被滤除"空转；此前"返回空"的工具提示保留，重查轮同样享受
+                idleSources = rewriteIdleSources(toolDocKeys, denoised, idleSources);
+                perSource.clear(); // 判过无关的结果不参与下轮融合（§5.4）
+                toolDocKeys.clear(); // 归因已折算进 idleSources，随 perSource 一起清
+                rewritten = true;
+                continue search;
+            }
+        }
+        outcome = { contextText: denoised.contextText, empty: denoised.docs.length === 0 };
+        finalDocs = denoised.docs.length;
+        break;
+    }
+    emit(input, 'rag.finish', {
+        nodeId: input.nodeId,
+        rounds: iteration,
+        empty: outcome.empty,
+        docs: finalDocs,
+    });
+    return {
+        contextText: outcome.contextText,
+        empty: outcome.empty,
+        iterations: iteration,
+        tokenUsage,
+    };
+}
+// ─────────────────────────────────────────────
+// 决策调用
+// ─────────────────────────────────────────────
+async function decide(input, query, loopMessages, tokenUsage, idleHint) {
+    const config = {
+        model: input.config.model ?? 'default',
+        systemPrompt: RAG_REACT, // provider 统一注入 system，不手动拼消息（与 LLMNode 同约定）
+        tools: input.apiTools,
+        toolChoice: 'auto',
+    };
+    // 任务行去重约束：history 末条 user 消息就是检索任务原文时不再追加"检索任务："行
+    // （同文重复两份白占决策上下文）；query 已被改写或来自别处（末条不同）时必须追加，
+    // RAG_REACT 对"检索任务"的指代不断供
+    const lastHistory = input.history.at(-1);
+    const taskInHistory = lastHistory?.role === 'user' && lastHistory.content.trim() === query.trim();
+    const messages = [
+        ...input.history,
+        ...loopMessages,
+        // 空转换源提示：仅决策上下文可见（不落 loopMessages、不进最终输出），每轮按最新空转重算
+        ...(idleHint ? [{ role: 'user', content: idleHint }] : []),
+        ...(taskInHistory ? [] : [{ role: 'user', content: `检索任务：${query}` }]),
+    ];
+    const startedAt = Date.now();
+    // 决策调用带重试（与 LLMNode 同语义：缺省 3 次 + 指数退避，config.retry 可覆盖）
+    const retryExecutor = new NodeRetryExecutor(input.nodeId, DEFAULT_LLM_RETRY_CONFIG);
+    const { result: response } = await retryExecutor.executeWithRetry(() => input.llmProvider.invoke(messages, config), input.config.retry);
+    tokenUsage.push({
+        nodeId: input.nodeId,
+        model: response.model,
+        inputTokens: response.inputTokens,
+        outputTokens: response.outputTokens,
+        durationMs: Date.now() - startedAt,
+    });
+    return response.toolCalls;
+}
+// ─────────────────────────────────────────────
+// 三路派发
+// ─────────────────────────────────────────────
+async function dispatchToolCalls(toolCalls, input, perSource, toolDocKeys) {
+    const outgoing = [];
+    const kbRequests = [];
+    const emptyTools = []; // 本轮零产出工具（空转：返回空子 case，失败不算）
+    for (const tc of toolCalls) {
+        if (tc.name === LOCAL_SEARCH_TOOL_NAME) {
+            const { message, idle } = await runLocalSearch(tc, input, perSource, toolDocKeys, 'semantic');
+            outgoing.push(message);
+            if (idle)
+                emptyTools.push(LOCAL_SEARCH_TOOL_NAME);
+        }
+        else if (tc.name === KEYWORD_SEARCH_TOOL_NAME) {
+            const { message, idle } = await runLocalSearch(tc, input, perSource, toolDocKeys, 'keyword');
+            outgoing.push(message);
+            if (idle)
+                emptyTools.push(KEYWORD_SEARCH_TOOL_NAME);
+        }
+        else if (input.kbToolNames.has(tc.name)) {
+            kbRequests.push(toKbRequest(tc, input));
+        }
+        else {
+            outgoing.push(toolMsg(tc.id, tc.name, `[Tool Error] 未注册的工具 "${tc.name}"，请只调用工具列表中的工具`, false));
+        }
+    }
+    if (kbRequests.length === 0)
+        return { messages: outgoing, emptyTools };
+    if (!input.toolOrchestrator) {
+        for (const req of kbRequests) {
+            outgoing.push(toolMsg(req.toolCallId, req.toolName, '[Tool Error] runtime 未装配 ToolOrchestrator', false));
+        }
+        return { messages: outgoing, emptyTools };
+    }
+    // executeAll 内部 allSettled：权限拒绝/执行失败均为结构化结果，不抛异常
+    // Trace span 照 ToolNode 模式：每次 kb 调用一个 span，span 类型用 tool + metadata.rag 标记
+    const spanIds = await Promise.all(kbRequests.map((req) => startTraceSpan(input, {
+        name: req.toolName,
+        type: 'tool',
+        input: req.arguments,
+        metadata: { toolCallId: req.toolCallId, toolType: req.toolType },
+    })));
+    const startedAt = Date.now();
+    const results = await input.toolOrchestrator.executeAll(kbRequests, input.executionContext);
+    const durationMs = Date.now() - startedAt;
+    for (const [i, r] of results.entries()) {
+        let hits = 0;
+        if (r.success) {
+            // 源桶可配：多工具源（知识库/数仓…）可分桶独立计配额，缺省同归 'kb'
+            const sourceId = input.config.toolSources?.[r.toolName] ?? 'kb';
+            const docs = normalizeToolResult(r.content, r.toolName, sourceId);
+            hits = docs.length;
+            const stored = pushDocs(perSource, sourceId, docs);
+            // 归因键用入桶后的 docs（撞号已重编号），与 perSource/filtered 复合键同源
+            recordDocKeys(toolDocKeys, r.toolName, stored);
+            if (hits === 0)
+                emptyTools.push(r.toolName);
+            outgoing.push(toolMsg(r.toolCallId, r.toolName, briefList(docs), true));
+        }
+        else {
+            // 失败也回给 LLM，让它下一轮自主决定换源重试还是收手
+            outgoing.push(toolMsg(r.toolCallId, r.toolName, `[Tool Error] ${r.error ?? '未知错误'}`, false));
+        }
+        emit(input, 'rag.search', {
+            nodeId: input.nodeId,
+            kind: 'kb',
+            toolName: r.toolName,
+            hits,
+            success: r.success,
+            ...(r.error ? { error: r.error } : {}),
+            durationMs, // 批次时长（executeAll 整批计时，批内共享）
+        });
+        await endTraceSpan(input, spanIds[i] ?? null, {
+            status: r.success ? 'completed' : 'failed',
+            output: r.success ? { hits } : undefined,
+            error: r.error,
+        });
+    }
+    return { messages: outgoing, emptyTools };
+}
+/** 路 A：内置伪工具（local_search 语义 / keyword_search 精确）→ 直连 retriever（多源并发），结果保持结构化零转换 */
+async function runLocalSearch(tc, input, perSource, toolDocKeys, mode) {
+    const retrievers = input.retrievers ?? [];
+    const query = String(tc.arguments['query'] ?? '');
+    // topK 非法值防御：LLM 可能回 "abc"/0/负数，NaN/非正数进 sqlite LIMIT 会抛错白费一轮 → 回退缺省 10
+    const rawTopK = Number(tc.arguments['topK'] ?? 10);
+    const topK = Number.isFinite(rawTopK) && rawTopK > 0 ? rawTopK : 10;
+    const toolName = mode === 'keyword' ? KEYWORD_SEARCH_TOOL_NAME : LOCAL_SEARCH_TOOL_NAME;
+    // keyword 模式只发到实现了 retrieveByKeyword 的源；semantic 全源
+    const targets = mode === 'keyword' ? retrievers.filter((r) => typeof r.retrieveByKeyword === 'function') : retrievers;
+    if (targets.length === 0) {
+        emit(input, 'rag.search', {
+            nodeId: input.nodeId,
+            kind: mode === 'keyword' ? 'keyword' : 'local',
+            query,
+            topK,
+            hits: 0,
+            success: false,
+            error: mode === 'keyword' ? '当前部署无关键词检索源' : '当前部署无本地检索源',
+            durationMs: 0,
+        });
+        return {
+            message: toolMsg(tc.id, toolName, `[Tool Error] ${mode === 'keyword' ? '当前部署无关键词检索源' : '当前部署无本地检索源'}`, false),
+            idle: true, // 部署形态性缺席：永远零产出，按空转提示换源
+        };
+    }
+    const spanId = await startTraceSpan(input, {
+        name: toolName,
+        type: 'tool',
+        input: { query, topK, userId: input.userId, mode },
+    });
+    const startedAt = Date.now();
+    const settled = await Promise.allSettled(targets.map((r) => mode === 'keyword'
+        ? r.retrieveByKeyword(query, { topK, userId: input.userId, scope: input.ragScope })
+        : r.retrieve(query, { topK, userId: input.userId, scope: input.ragScope })));
+    const durationMs = Date.now() - startedAt;
+    const roundDocs = [];
+    let failCount = 0;
+    settled.forEach((s, i) => {
+        if (s.status === 'fulfilled') {
+            pushDocs(perSource, targets[i].sourceId, s.value);
+            roundDocs.push(...s.value);
+        }
+        else {
+            failCount += 1;
+        }
+    });
+    recordDocKeys(toolDocKeys, toolName, roundDocs);
+    const summary = failCount > 0 ? `（${failCount} 个源失败）` : '';
+    // 本次实际生效的本地检索范围摘要（与传给 retriever 的 scope 同源；缺省不限则不打字段）
+    const scopeSummary = summarizeScope(input.ragScope);
+    emit(input, 'rag.search', {
+        nodeId: input.nodeId,
+        kind: mode === 'keyword' ? 'keyword' : 'local',
+        query,
+        topK,
+        hits: roundDocs.length,
+        success: failCount === 0,
+        ...(failCount > 0 ? { error: `${failCount} 个源失败` } : {}),
+        durationMs,
+        ...(scopeSummary ? { scope: scopeSummary } : {}),
+    });
+    await endTraceSpan(input, spanId, {
+        status: failCount === 0 ? 'completed' : 'failed',
+        output: { hits: roundDocs.length },
+        ...(failCount > 0 ? { error: `${failCount} 个源失败` } : {}),
+    });
+    return {
+        message: toolMsg(tc.id, toolName, `${briefList(roundDocs)}${summary}`, roundDocs.length > 0),
+        // 空转（返回空子 case）：全部源成功执行但零产出（失败已有 Tool Error 反馈，语义不同不混计）
+        idle: failCount === 0 && roundDocs.length === 0,
+    };
+}
+/** 路 B 请求组装：照 ToolNode 惯例从 manifest 取路由元数据（Router 选路依据，缺了会退化默认分支） */
+function toKbRequest(tc, input) {
+    const loaded = input.loadedTools?.[tc.name];
+    return {
+        toolCallId: tc.id,
+        toolName: tc.name,
+        arguments: tc.arguments,
+        authContext: input.authContext,
+        forceServer: input.forceToolServer?.includes(tc.name),
+        toolType: loaded?.manifest.type,
+        toolRuntime: loaded?.manifest.toolRuntime,
+        dataScope: loaded?.manifest.dataScope,
+        execution: loaded?.manifest.execution,
+    };
+}
+/**
+ * 收集侧入桶（跨轮累计）。约束：同 sourceId+rawId 撞号且 content 不同时必须对
+ * 后来者重编号 `${rawId}#r${n}`（n 为该键冲突序号）——外部工具可能返回不含参数
+ * 区分的恒定 id（dw 恒 `dw-${code}`、normalize 位置 fallback 每次调用都从 0 编号），
+ * ReAct 对同一工具 ≥2 次调用是常态，id 冲突 ≠ 内容重复，不重编号会被融合前精确
+ * 去重当重复静默丢弃（briefList 已给决策 LLM 看过、最终 contextText 却缺失）。
+ * content 相同才按重复跳过（归一化口径与 dedupExact 同源，见 sameContent）。
+ * 重编号只动 rawId 去重键链路，metadata/title 等展示字段原样；briefList 仍用
+ * 原始 docs，决策上下文展示不受重编号影响。
+ * 返回实际入桶的 docs（重编号副本）：空转归因键（toolDocKeys）必须与桶内键
+ * 同源，否则 rewrite 边界整键匹配会漏掉重编号条目。
+ */
+function pushDocs(perSource, sourceId, docs) {
+    const bucket = perSource.get(sourceId) ?? [];
+    const stored = [];
+    for (const d of docs) {
+        // 同 id 且内容相同 → 真重复跳过；内容不同 → 走下方重编号保内容
+        if (bucket.some((b) => b.rawId === d.rawId && sameContent(b.content, d.content)))
+            continue;
+        let doc = d;
+        if (bucket.some((b) => b.rawId === d.rawId)) {
+            let n = 1;
+            while (bucket.some((b) => b.rawId === `${d.rawId}#r${n}`))
+                n++;
+            doc = { ...d, rawId: `${d.rawId}#r${n}` };
+        }
+        bucket.push(doc);
+        stored.push(doc);
+    }
+    perSource.set(sourceId, bucket);
+    return stored;
+}
+/** 工具产出登记（空转归因用）：sourceId:rawId 为键（rawId 仅源内唯一），跨轮累计去重 */
+function recordDocKeys(toolDocKeys, tool, docs) {
+    if (docs.length === 0)
+        return;
+    const keys = toolDocKeys.get(tool) ?? new Set();
+    for (const d of docs)
+        keys.add(`${d.sourceId}:${d.rawId}`);
+    toolDocKeys.set(tool, keys);
+}
+/** 决策上下文的换源提示文案：只描述上一轮空转的来源，不累积历史 */
+function idleHint(sources) {
+    if (sources.length === 0)
+        return undefined;
+    const list = sources.map((s) => `${s.tool}（${s.note}）`).join('、');
+    return `上一轮以下来源无高相关结果：${list}。请改用其他数据源工具或多源并行，不要继续重查这些来源。`;
+}
+/**
+ * rewrite 边界的空转归因：触发重写即存活集为空，本次产出过文档的工具全部是
+ * "结果全被滤除"空转，附一条最有代表性的被滤原因（融合序靠前优先）；
+ * 此前"返回空"的工具不在产出集里（无产出），提示原样保留，重查轮同样享受。
+ * filtered 项与工具产出键同为复合键 sourceId:rawId，须整键精确匹配
+ * （rawId 仅源内唯一，按尾段匹配跨源碰撞会张冠李戴）。
+ */
+function rewriteIdleSources(toolDocKeys, denoised, prevIdle) {
+    const keptKeys = new Set(denoised.docs.map((d) => `${d.sourceId}:${d.rawId}`));
+    const idle = [];
+    for (const [tool, keys] of toolDocKeys) {
+        if ([...keys].some((k) => keptKeys.has(k)))
+            continue; // 有产出存活 → 非空转（防御：重写触发时实际恒空）
+        const reason = [...keys]
+            .map((k) => denoised.filtered.find((f) => f.rawId === k && f.reason))
+            .find(Boolean)?.reason;
+        idle.push({ tool, note: `结果全被滤除${reason ? `，原因示例：${reason}` : ''}` });
+    }
+    return [...idle, ...prevIdle.filter((p) => !toolDocKeys.has(p.tool))];
+}
+/**
+ * rag.search 的本地 scope 摘要（仅 local/keyword 路径）：与传给 retriever 的 scope 同源，
+ * 形如 `dirs=2[共享资料,月报] files=3`（目录取末段名、超长截断）；显式空集
+ * （会话勾选关闭本地源）给 'closed'；undefined（不限）不打字段。kb 路径不受 ragScope 约束，无此字段。
+ */
+function summarizeScope(scope) {
+    if (!scope)
+        return undefined;
+    const dirs = scope.dirPaths ?? [];
+    const files = scope.fileIds ?? [];
+    if (dirs.length === 0 && files.length === 0)
+        return 'closed';
+    let names = dirs
+        .map((d) => d.split(/[\\/]/).filter(Boolean).at(-1) ?? d)
+        .join(',');
+    if (names.length > 40)
+        names = `${names.slice(0, 40)}…`;
+    const dirPart = dirs.length ? `dirs=${dirs.length}[${names}]` : 'dirs=0';
+    return `${dirPart} files=${files.length}`;
+}
+// ─────────────────────────────────────────────
+// 观测出口（rag.* 事件 + Trace span）
+// ─────────────────────────────────────────────
+function emit(input, type, payload) {
+    input.emitEvent?.(type, payload);
+}
+/**
+ * Trace span 创建：照 ToolNode 模式（state.traceCollector + resolveTraceId）。
+ * span 类型枚举无 'rag'（foundation 契约），借用 tool/llm + metadata.rag 标记。
+ * 采集器缺失或异常 → 返回 null，不影响主路径。
+ */
+async function startTraceSpan(input, event) {
+    if (!input.traceCollector || !input.traceId)
+        return null;
+    try {
+        return await input.traceCollector.createNode({
+            traceId: input.traceId,
+            name: event.name,
+            type: event.type,
+            input: event.input,
+            metadata: { rag: true, ...event.metadata },
+        });
+    }
+    catch {
+        return null;
+    }
+}
+async function endTraceSpan(input, spanId, params) {
+    if (!input.traceCollector || !spanId)
+        return;
+    try {
+        await input.traceCollector.completeNode(spanId, params);
+    }
+    catch {
+        // Trace 失败不影响主路径（照 ToolNode 惯例）
+    }
+}
+function toolMsg(toolCallId, toolName, content, success) {
+    return { role: 'tool', content, toolCallId, toolName, success };
+}

package/dist/graph/nodes/rag/retrievers/http-embedder.d.ts

@@ -0,0 +1,29 @@
+/**
+ * HttpEmbedder — OpenAI 兼容 /v1/embeddings 客户端（IEmbedder 实现）
+ *
+ * embedding 统一走 gateway（design-v2 §7.3 实配：Qwen3-Embedding-8B @
+ * gtaiapi.gtcloud.cn，Bearer 认证，dimensions=1024 截断）；配置经构造参数
+ * 注入（baseUrl/model/apiKey/dims/dimensions），换模型 = 换构造参数
+ * （库文件需配套，引擎 model_version/dims 锁会拦住混用）。
+ */
+import type { IEmbedder } from '../types.js';
+export interface HttpEmbedderOptions {
+    baseUrl: string;
+    model: string;
+    dims: number;
+    apiKey?: string;
+    /** 请求侧显式指定输出维度（Matryoshka 截断，如 gateway Qwen3-Embedding-8B 支持 1024–4096）；不支持该参数的服务会忽略 */
+    dimensions?: number;
+    /** 单次批量上限（超出分多次请求，结果按序拼接）；缺省 64 */
+    batchSize?: number;
+}
+export declare class HttpEmbedder implements IEmbedder {
+    readonly model: string;
+    readonly dims: number;
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly dimensions?;
+    private readonly batchSize;
+    constructor(opts: HttpEmbedderOptions);
+    embed(texts: string[]): Promise<number[][]>;
+}

package/dist/graph/nodes/rag/retrievers/http-embedder.js

@@ -0,0 +1,66 @@
+/**
+ * HttpEmbedder — OpenAI 兼容 /v1/embeddings 客户端（IEmbedder 实现）
+ *
+ * embedding 统一走 gateway（design-v2 §7.3 实配：Qwen3-Embedding-8B @
+ * gtaiapi.gtcloud.cn，Bearer 认证，dimensions=1024 截断）；配置经构造参数
+ * 注入（baseUrl/model/apiKey/dims/dimensions），换模型 = 换构造参数
+ * （库文件需配套，引擎 model_version/dims 锁会拦住混用）。
+ */
+export class HttpEmbedder {
+    model;
+    dims;
+    baseUrl;
+    apiKey;
+    dimensions;
+    batchSize;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        this.model = opts.model;
+        this.dims = opts.dims;
+        this.apiKey = opts.apiKey;
+        this.dimensions = opts.dimensions;
+        this.batchSize = opts.batchSize ?? 64;
+    }
+    async embed(texts) {
+        if (texts.length === 0)
+            return [];
+        const out = [];
+        for (let i = 0; i < texts.length; i += this.batchSize) {
+            const batch = texts.slice(i, i + this.batchSize);
+            const headers = { 'content-type': 'application/json' };
+            if (this.apiKey)
+                headers['authorization'] = `Bearer ${this.apiKey}`;
+            const res = await fetch(`${this.baseUrl}/v1/embeddings`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({
+                    input: batch.length === 1 ? batch[0] : batch,
+                    model: this.model,
+                    // dimensions 缺省发 dims：请求维度与返回校验期望必须同源，否则网关按原生维度返回必炸校验
+                    dimensions: this.dimensions ?? this.dims,
+                }),
+            });
+            if (!res.ok) {
+                const text = (await res.text()).slice(0, 200);
+                throw new Error(`HttpEmbedder "${this.model}" HTTP ${res.status}: ${text}`);
+            }
+            const json = (await res.json());
+            const vectors = (json.data ?? []).map((d) => d.embedding);
+            if (vectors.length !== batch.length) {
+                throw new Error(`HttpEmbedder "${this.model}" 返回 ${vectors.length} 条向量 ≠ 请求 ${batch.length} 条`);
+            }
+            // 维度必须在 embed 侧断言：缺失/长度不符立即抛带模型名与期望/实际的明确错误。
+            // 掩成空数组会把错配延迟到 engine.search 才爆（无法归因为模型与库 dims 不配套）
+            const checked = [];
+            for (let j = 0; j < vectors.length; j++) {
+                const v = vectors[j];
+                if (!Array.isArray(v) || v.length !== this.dims) {
+                    throw new Error(`HttpEmbedder "${this.model}" 第 ${j + 1} 条向量维度不符：期望 ${this.dims}，实际 ${Array.isArray(v) ? v.length : '缺失/非数组'}（embedding 模型与向量库 dims 必须配套）`);
+                }
+                checked.push(v);
+            }
+            out.push(...checked);
+        }
+        return out;
+    }
+}

package/dist/graph/nodes/rag/retrievers/in-memory-retriever.d.ts

@@ -0,0 +1,17 @@
+/**
+ * InMemoryRetriever — 内存桩检索器（M1）
+ *
+ * 只为跑通/测试调用链，不做真检索；正式实现 LocalSqliteRetriever
+ * （gateway embed → 本机向量引擎 /search → 归一化，design-v2 §7.4）
+ * 面向同一 IRetriever 接口替换，react-loop 零改动。
+ */
+import type { IRetriever, RetrievalDoc } from '../types.js';
+export declare class InMemoryRetriever implements IRetriever {
+    readonly sourceId: string;
+    private readonly docs;
+    constructor(sourceId: string, docs: RetrievalDoc[]);
+    retrieve(_query: string, opts: {
+        topK: number;
+        userId: string;
+    }): Promise<RetrievalDoc[]>;
+}

package/dist/graph/nodes/rag/retrievers/in-memory-retriever.js

@@ -0,0 +1,18 @@
+/**
+ * InMemoryRetriever — 内存桩检索器（M1）
+ *
+ * 只为跑通/测试调用链，不做真检索；正式实现 LocalSqliteRetriever
+ * （gateway embed → 本机向量引擎 /search → 归一化，design-v2 §7.4）
+ * 面向同一 IRetriever 接口替换，react-loop 零改动。
+ */
+export class InMemoryRetriever {
+    sourceId;
+    docs;
+    constructor(sourceId, docs) {
+        this.sourceId = sourceId;
+        this.docs = docs;
+    }
+    async retrieve(_query, opts) {
+        return this.docs.slice(0, opts.topK);
+    }
+}

package/dist/graph/nodes/rag/retrievers/local-sqlite-retriever.d.ts

@@ -0,0 +1,46 @@
+/**
+ * LocalSqliteRetriever — 本地向量检索 IRetriever 实现（design-v2 §7.4）
+ *
+ * 两跳：embedder.embed(query)（远程向量化，统一走 gateway）→
+ * engine.search（后台线程 KNN，用户隔离 + 软删除过滤）→ 归一化 RetrievalDoc。
+ * 引擎实例与 embedder 均由宿主构造注入——runtime 不 import 引擎包，服务端
+ * 形态不挂本 retriever（部署差异零分支，§8）。
+ */
+import type { IEmbedder, IRetriever, RagScope, RetrievalDoc, VectorEnginePort } from '../types.js';
+export interface LocalSqliteRetrieverOptions {
+    /** 引擎端口实例（宿主 createAsyncEngine 产物即满足） */
+    engine: VectorEnginePort;
+    /** query 向量化（统一走 gateway embedding） */
+    embedder: IEmbedder;
+    /** 查询侧模型标识校验用；缺省取 embedder.model */
+    modelVersion?: string;
+    /** 源标识，缺省 'local' */
+    sourceId?: string;
+}
+export declare class LocalSqliteRetriever implements IRetriever {
+    readonly sourceId: string;
+    private readonly engine;
+    private readonly embedder;
+    private readonly modelVersion;
+    constructor(opts: LocalSqliteRetrieverOptions);
+    retrieve(query: string, opts: {
+        topK: number;
+        userId: string;
+        scope?: RagScope;
+    }): Promise<RetrievalDoc[]>;
+    /** 关键词精确检索（FTS5 bm25）：端口未提供该能力时不暴露（上层不会把 keyword_search 进工具表） */
+    retrieveByKeyword(query: string, opts: {
+        topK: number;
+        userId: string;
+        scope?: RagScope;
+    }): Promise<RetrievalDoc[]>;
+    /**
+     * 请求级范围 → 引擎过滤键。语义三分：
+     * undefined（无 scope / 空对象）= 未圈定，不传 filter；
+     * fileIds 空数组且无 dirPaths = 圈定了但无本地源（会话勾选未含 local-file）→
+     *   引擎两路直接回空；fileIds 空数组与 dirPaths 并存是"无文件过滤、只圈目录"的
+     *   自然编码（契约并集语义），须走并集解析而非整体关闭；
+     * fileIds/dirPaths 有值 → dirPaths 经引擎解析（可选能力，未实现则仅 fileIds 生效）后并集。
+     */
+    private resolveFileIds;
+}