@gt-fe/eap-runtime 0.0.20 → 0.0.22

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

@@ -0,0 +1,85 @@
+/**
+ * LocalSqliteRetriever — 本地向量检索 IRetriever 实现（design-v2 §7.4）
+ *
+ * 两跳：embedder.embed(query)（远程向量化，统一走 gateway）→
+ * engine.search（后台线程 KNN，用户隔离 + 软删除过滤）→ 归一化 RetrievalDoc。
+ * 引擎实例与 embedder 均由宿主构造注入——runtime 不 import 引擎包，服务端
+ * 形态不挂本 retriever（部署差异零分支，§8）。
+ */
+export class LocalSqliteRetriever {
+    sourceId;
+    engine;
+    embedder;
+    modelVersion;
+    constructor(opts) {
+        this.sourceId = opts.sourceId ?? 'local';
+        this.engine = opts.engine;
+        this.embedder = opts.embedder;
+        this.modelVersion = opts.modelVersion ?? opts.embedder.model;
+    }
+    async retrieve(query, opts) {
+        const [vector] = await this.embedder.embed([query]);
+        if (this.engine.assertQueryModel) {
+            await this.engine.assertQueryModel(this.modelVersion);
+        }
+        const rows = await this.engine.search(vector, { ...opts, fileIds: await this.resolveFileIds(opts.scope) });
+        // distance 越小越相关（与其他源 score 越大越好语义相反）→ 不进 score、进 metadata；
+        // 源内顺序由引擎 ORDER BY distance 给出，fuse 依赖此序（§6.2）
+        return rows.map((r) => ({
+            content: r.content,
+            sourceId: this.sourceId,
+            rawId: String(r.id),
+            metadata: {
+                fileId: r.fileId,
+                fileName: r.fileName,
+                filePath: r.filePath,
+                chunkId: r.chunkId,
+                distance: r.distance,
+            },
+        }));
+    }
+    /** 关键词精确检索（FTS5 bm25）：端口未提供该能力时不暴露（上层不会把 keyword_search 进工具表） */
+    async retrieveByKeyword(query, opts) {
+        if (!this.engine.searchByKeyword)
+            return [];
+        const rows = await this.engine.searchByKeyword(query, {
+            ...opts,
+            fileIds: await this.resolveFileIds(opts.scope),
+        });
+        // rank 同 distance 语义（越小越相关）→ 进 metadata 不进 score；源内顺序 = bm25 序
+        return rows.map((r) => ({
+            content: r.content,
+            sourceId: this.sourceId,
+            rawId: String(r.id),
+            metadata: {
+                fileId: r.fileId,
+                fileName: r.fileName,
+                filePath: r.filePath,
+                chunkId: r.chunkId,
+                rank: r.rank,
+            },
+        }));
+    }
+    /**
+     * 请求级范围 → 引擎过滤键。语义三分：
+     * undefined（无 scope / 空对象）= 未圈定，不传 filter；
+     * fileIds 空数组且无 dirPaths = 圈定了但无本地源（会话勾选未含 local-file）→
+     *   引擎两路直接回空；fileIds 空数组与 dirPaths 并存是"无文件过滤、只圈目录"的
+     *   自然编码（契约并集语义），须走并集解析而非整体关闭；
+     * fileIds/dirPaths 有值 → dirPaths 经引擎解析（可选能力，未实现则仅 fileIds 生效）后并集。
+     */
+    async resolveFileIds(scope) {
+        if (!scope || (scope.fileIds === undefined && !scope.dirPaths?.length))
+            return undefined;
+        if (scope.fileIds?.length === 0 && !scope.dirPaths?.length)
+            return [];
+        if (this.engine.resolveScopeFileIds) {
+            const ids = await this.engine.resolveScopeFileIds({
+                fileIds: scope.fileIds,
+                dirPathPrefixes: scope.dirPaths,
+            });
+            return ids ?? undefined;
+        }
+        return scope.fileIds?.length ? scope.fileIds : [];
+    }
+}

package/dist/graph/nodes/rag/tools.d.ts

@@ -0,0 +1,90 @@
+/**
+ * RAG 工具表组装 — LLM 眼中只有一张工具表
+ *
+ * 四类工具拼成一张 apiTools：
+ * ① 注册工具：config.tools 圈定的 loadedTools 子集（缺省全部），复用 runtime 现成的
+ *    loadedToolsToApiTools（schema 单一真相源在 manifest，DSL 只做名字引用）
+ * ② local_search：内置伪工具，schema 代码定义，执行直连 IRetriever（不经 ToolOrchestrator）
+ * ②' keyword_search：可选伪工具（至少一个 retriever 实现retrieveByKeyword 才进表），
+ *     FTS5 精确匹配——数字/编号/专有名词是 embedding 短板，交给 LLM 按查询形态自选
+ * ③ rag_finish：终止信号，不执行任何东西
+ *
+ * @see design-v2 §5.4 / 前置讨论「工具定义放节点内」结论
+ */
+import type { LLMToolDefinition } from '../llm-node.js';
+import type { LoadedToolMap } from '../../../tool/loaded-tool-definition.js';
+import type { RagNodeConfig, IRetriever, RetrievalDoc } from './types.js';
+export declare const RAG_FINISH_TOOL_NAME = "rag_finish";
+export declare const LOCAL_SEARCH_TOOL_NAME = "local_search";
+export declare const KEYWORD_SEARCH_TOOL_NAME = "keyword_search";
+/**
+ * resolveRagSources — 检索面解析的单一入口（RagNode / rag_search 装饰器共用）
+ *
+ * 三种声明位（优先级递降）：sources（描述符/字符串混排）→ retrievalTools → tools；
+ * 均未声明 = 全未圈定（全部 loadedTools + 本地源不限）。
+ * selectedIds 为会话级勾选（请求 ragSources）：按 id 过滤目录条目，undefined = 全部启用。
+ * 字符串条目是外部源简写（id = 注册工具名）；local-file 条目进本地目录白名单。
+ */
+export interface ResolvedRagSources {
+    /** 外部工具面：undefined = 未圈定（全部 loadedTools）；[] = 圈定但无外部源 */
+    toolScope?: string[];
+    /** 目录是否声明了 local-file 数据源（决定"未勾选本地"是关还是不限） */
+    hasLocal: boolean;
+    /** sources 描述符目录是否声明（声明了 = 图即完整检索面：无 local-file 条目则本地不可用） */
+    hasCatalog: boolean;
+    /** 勾选后生效的本地文件夹路径（local-file source，旧式无 source 取 id），进检索 scope */
+    localDirs: string[];
+    /** 声明的本地目录全量面（不受 ragSources 勾选影响）——请求带 ragScope.dirPaths 时作为交集基准 */
+    localDirsAll: string[];
+    /**
+     * 工具名 → 该工具下生效的资源目录（仅含带 source 的描述符）。
+     * 一型一工具、源是参数：dw 的表/maxkb 的 appid 等资源值经工具 description
+     * 暴露给 LLM，由 LLM 决策调用时选参（会话勾选后目录同步收窄）
+     */
+    sourceCatalog: Record<string, Array<{
+        id: string;
+        source: string;
+    }>>;
+}
+/**
+ * sourceToolName — 外部源描述符 → 工具名（type 约定解析）
+ *
+ * ref 显式指定 > `${type}_search` 约定；local-file 非工具源（undefined）；
+ * 字符串简写（type 'external'）工具名即字符串本身。约定名未注册由
+ * buildRagTools fail-fast 提示 ref 兜底。
+ */
+export declare function sourceToolName(e: {
+    type: string;
+    id: string;
+    ref?: string;
+}): string | undefined;
+export declare function resolveRagSources(config: RagNodeConfig | undefined, selectedIds?: string[]): ResolvedRagSources;
+export declare function mergeLocalDirs(hasLocal: boolean, localDirs: string[], requestScope?: import('./types.js').RagScope): import('./types.js').RagScope | undefined;
+export declare function appendSourceCatalog(description: string | undefined, entries: Array<{
+    id: string;
+    source: string;
+}>): string;
+/** RagToolSet — react-loop 派发所需的工具表元数据 */
+export interface RagToolSet {
+    /** 传给 LLM 的 API tools 参数（①+②+③） */
+    apiTools: LLMToolDefinition[];
+    /** 注册工具名集合（派发路 B 用：命中才走 ToolOrchestrator） */
+    kbToolNames: Set<string>;
+    /** config.tools 声明了但 loadedTools 未注册的名字（execute 首轮 fail-fast 用） */
+    missingToolNames: string[];
+    /** config.tools 显式点名了 requireConfirmation 工具（execute 首轮 fail-fast 用） */
+    excludedConfirmToolNames: string[];
+}
+export declare function buildRagTools(config: RagNodeConfig, loadedTools: LoadedToolMap | undefined, retrievers: IRetriever[] | undefined, opts?: {
+    toolScope?: string[];
+    sourceCatalog?: ResolvedRagSources['sourceCatalog'];
+    localEnabled?: boolean;
+}): RagToolSet;
+/**
+ * briefList — 给 LLM 的精简结果清单
+ *
+ * 关键设计：检索全文只进 perSource（供 fuse/denoise），决策上下文只放
+ * 标题+短摘录——避免数万 token 检索结果把 ReAct 决策上下文撑爆。
+ */
+export declare function briefList(docs: RetrievalDoc[], maxExcerpt?: number): string;
+export declare function docTitle(d: RetrievalDoc): string;

package/dist/graph/nodes/rag/tools.js

@@ -0,0 +1,260 @@
+/**
+ * RAG 工具表组装 — LLM 眼中只有一张工具表
+ *
+ * 四类工具拼成一张 apiTools：
+ * ① 注册工具：config.tools 圈定的 loadedTools 子集（缺省全部），复用 runtime 现成的
+ *    loadedToolsToApiTools（schema 单一真相源在 manifest，DSL 只做名字引用）
+ * ② local_search：内置伪工具，schema 代码定义，执行直连 IRetriever（不经 ToolOrchestrator）
+ * ②' keyword_search：可选伪工具（至少一个 retriever 实现retrieveByKeyword 才进表），
+ *     FTS5 精确匹配——数字/编号/专有名词是 embedding 短板，交给 LLM 按查询形态自选
+ * ③ rag_finish：终止信号，不执行任何东西
+ *
+ * @see design-v2 §5.4 / 前置讨论「工具定义放节点内」结论
+ */
+import { loadedToolsToApiTools } from '../../../tool/system-prompt-builder.js';
+import { readFileSync } from 'node:fs';
+export const RAG_FINISH_TOOL_NAME = 'rag_finish';
+export const LOCAL_SEARCH_TOOL_NAME = 'local_search';
+export const KEYWORD_SEARCH_TOOL_NAME = 'keyword_search';
+const RAG_FINISH_TOOL = {
+    type: 'function',
+    function: {
+        name: RAG_FINISH_TOOL_NAME,
+        description: '结束检索循环并整理结果。满足任一即调用：各子问题均有高相关片段覆盖 / 新一轮结果与已有高度重复 / 已收集足够高相关片段。',
+        parameters: { type: 'object', properties: {} },
+    },
+};
+function localSearchTool(retrievers) {
+    return {
+        type: 'function',
+        function: {
+            name: LOCAL_SEARCH_TOOL_NAME,
+            description: `检索用户本机已向量化的文档（本地知识库）。可用本地源：${retrievers
+                .map((r) => r.sourceId)
+                .join('、')}。`,
+            parameters: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: '自包含的检索查询' },
+                    topK: { type: 'number', description: '每个源返回的条数，默认 10' },
+                },
+                required: ['query'],
+            },
+        },
+    };
+}
+function keywordSearchTool(retrievers) {
+    return {
+        type: 'function',
+        function: {
+            name: KEYWORD_SEARCH_TOOL_NAME,
+            description: `本地文档关键词精确匹配（FTS5 全文检索，可用源：${retrievers
+                .map((r) => r.sourceId)
+                .join('、')}）。适合语义检索难以命中的查询：精确数字（金额/日期）、编号（单号/工号）、专有名词、文件名等。`,
+            parameters: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: '关键词（可含空格分隔的多个词，须与原文精确一致）' },
+                    topK: { type: 'number', description: '每个源返回的条数，默认 10' },
+                },
+                required: ['query'],
+            },
+        },
+    };
+}
+/**
+ * sourceToolName — 外部源描述符 → 工具名（type 约定解析）
+ *
+ * ref 显式指定 > `${type}_search` 约定；local-file 非工具源（undefined）；
+ * 字符串简写（type 'external'）工具名即字符串本身。约定名未注册由
+ * buildRagTools fail-fast 提示 ref 兜底。
+ */
+export function sourceToolName(e) {
+    if (e.type === 'local-file')
+        return undefined;
+    if (e.type === 'external')
+        return e.id;
+    return e.ref ?? `${e.type}_search`;
+}
+/**
+ * local-file source 展开 —— 三种写法：
+ * ① 目录路径：原样进 scope（引擎前缀匹配，含子目录）
+ * ② 单文件路径：原样进 scope（引擎 LIKE 精确匹配行命中该文件）
+ * ③ .json 结尾：授权清单文件（`{dirs:[...]}` 或字符串数组），展开为目录列表——
+ *    每次解析现读（清单热更新随之生效）；缺文件/坏格式 = 空集（宁空不越界）
+ */
+function expandLocalSource(src) {
+    if (!src.toLowerCase().endsWith('.json'))
+        return [src];
+    try {
+        const parsed = JSON.parse(readFileSync(src, 'utf-8'));
+        const dirs = Array.isArray(parsed) ? parsed : parsed?.dirs;
+        // 清单项类型约束：非字符串项（null/数字/对象）直接丢弃——String() 强转会把垃圾
+        // 变 "null"/"1"/"[object Object]" 路径穿透，破坏"坏格式=空集"的宁空不越界语义
+        return Array.isArray(dirs)
+            ? dirs.filter((s) => typeof s === 'string').map((s) => s.trim()).filter(Boolean)
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function resolveRagSources(config, selectedIds) {
+    const rs = config?.retrievalSources;
+    const entries = [];
+    if (rs?.sources) {
+        for (const e of rs.sources) {
+            if (typeof e === 'string')
+                entries.push({ type: 'external', id: e });
+            else
+                entries.push(e);
+        }
+    }
+    else {
+        const legacy = rs?.retrievalTools ?? config?.tools;
+        if (!legacy)
+            return { toolScope: undefined, hasLocal: false, hasCatalog: false, localDirs: [], localDirsAll: [], sourceCatalog: {} };
+        for (const n of legacy)
+            entries.push({ type: 'external', id: n });
+    }
+    const active = selectedIds ? entries.filter((e) => selectedIds.includes(e.id)) : entries;
+    const sourceCatalog = {};
+    for (const e of active) {
+        const tool = sourceToolName(e);
+        if (tool === undefined || !e.source)
+            continue;
+        (sourceCatalog[tool] ??= []).push({ id: e.id, source: e.source });
+    }
+    // local-file 展开单次读盘约束：localDirsAll（声明全量面）与 localDirs（勾选后子集）必须
+    // 同源——双读除多一次同步 I/O 外，.json 清单恰好被并发改写时两者会读到不同内容错位
+    const localDirsAll = [];
+    const localDirs = [];
+    for (const e of entries) {
+        if (e.type !== 'local-file')
+            continue;
+        const dirs = expandLocalSource(e.source ?? e.id);
+        localDirsAll.push(...dirs);
+        if (!selectedIds || selectedIds.includes(e.id))
+            localDirs.push(...dirs);
+    }
+    return {
+        toolScope: [...new Set(active.map(sourceToolName).filter((n) => n !== undefined))],
+        hasLocal: entries.some((e) => e.type === 'local-file'),
+        // sources 描述符声明了 = 图即完整检索面（legacy 字符串位仍是纯工具清单语义）。
+        // 空数组也算声明：检索面为空、本地不可用（fail-closed），不能当未声明放开本地全库
+        hasCatalog: Array.isArray(rs?.sources),
+        localDirs,
+        localDirsAll,
+        sourceCatalog,
+    };
+}
+/**
+ * 数据源目录的 local-file 白名单与请求级 ragScope 合成（参数只收窄不扩面）：
+ * 声明过 local-file 但本次未勾选（勾选后 localDirs 空）→ fileIds:[]（本地源关闭）；
+ * 请求 dirPaths 圈定 → 在勾选后的声明面内取交集（面板逐授权目录勾选走这条路，
+ * 交集为空 = 关本地）；请求未圈定 → 勾选面原样。路径比较分隔符正反/尾斜杠归一。
+ * 目录未声明本地源 → 请求 scope 原样（本地全库，检索器由宿主装配）。
+ * 节点形态（RagNode）与工具形态（RagSearchToolExecutor）共用。
+ */
+const normDirPath = (p) => p.replace(/\\/g, '/').replace(/\/+$/, '');
+export function mergeLocalDirs(hasLocal, localDirs, requestScope) {
+    if (!hasLocal)
+        return requestScope;
+    if (!localDirs.length)
+        return { fileIds: [] };
+    const declared = [...new Set(localDirs.map(normDirPath))];
+    if (requestScope?.dirPaths === undefined) {
+        return { dirPaths: declared, fileIds: requestScope?.fileIds };
+    }
+    // 交集比较键统一 toLowerCase：Windows 路径大小写不敏感，声明 D:/Docs 请求 d:/docs
+    // 须命中（大小写敏感会交集空误关本地）；仅比较用，dirPaths 保留声明原样传引擎
+    const requested = new Set(requestScope.dirPaths.map((p) => normDirPath(p).toLowerCase()));
+    const dirPaths = declared.filter((d) => requested.has(d.toLowerCase()));
+    if (!dirPaths.length)
+        return { fileIds: [] }; // 圈定与声明面交集为空 → 关本地
+    return { dirPaths, fileIds: requestScope?.fileIds };
+}
+/**
+ * 资源目录注入工具 description（替换语义）：带 source 的外部源把合法资源值
+ * （表名/appid/collection…）前置给 LLM 选参——内核不猜参数名，按工具 schema 由 LLM 填。
+ * 节点形态内核组表与工具形态 adapter 白名单收敛两处共用：adapter 先注入全量目录、
+ * 内核再注入会话勾选后的收窄目录，既有 `（可用数据源：…）` 后缀须整体摘除再追加——
+ * 逐字相同才跳过的幂等挡不住全量+收窄两份并存（全量份会让内层 LLM 选到未勾选源）。
+ * 摘除用 lastIndexOf 而非 `[^）]*` 正则：目录名可含中文、括号，只有"最后一个标记到
+ * 句尾"才是本函数拼出的后缀整体形态。
+ */
+const SOURCE_CATALOG_MARKER = '（可用数据源：';
+export function appendSourceCatalog(description, entries) {
+    if (!entries?.length)
+        return description ?? '';
+    const list = entries.map((c) => `${c.id}=${c.source}`).join('、');
+    const suffix = `（可用数据源：${list}）`;
+    let base = description ?? '';
+    const at = base.lastIndexOf(SOURCE_CATALOG_MARKER);
+    if (at !== -1 && base.endsWith('）'))
+        base = base.slice(0, at);
+    return `${base}${suffix}`.trim();
+}
+export function buildRagTools(config, loadedTools, retrievers, opts) {
+    const available = new Set(Object.keys(loadedTools ?? {}));
+    // requireConfirmation 工具不进 rag 工具表：HITL 确认流挂在图级 ToolNode，
+    // rag 直调 orchestrator 会绕过确认（LLM 自主执行需确认操作是合规硬伤），
+    // 宁可不见——缺省静默剔除；数据源目录显式点名则 fail-fast（见 RagNode）
+    const requireConfirm = (name) => Boolean(loadedTools?.[name]?.manifest.requireConfirmation);
+    // 三 opts 齐备时跳过内部解析约束：调用方已显式传入勾选后的解析结果，再 resolve 一次
+    // 是对 .json 清单的重复同步读盘，且可能读到与调用方不一致的内容（目录与工具表错位）
+    const needsResolve = opts?.toolScope === undefined || opts?.sourceCatalog === undefined || opts?.localEnabled === undefined;
+    const resolved = needsResolve ? resolveRagSources(config) : undefined;
+    const toolScope = opts?.toolScope !== undefined ? opts.toolScope : resolved?.toolScope;
+    // ?? {} 仅为类型收窄：跳过解析时 opts.sourceCatalog 必有值，实际不会落到空目录
+    const sourceCatalog = opts?.sourceCatalog ?? resolved?.sourceCatalog ?? {};
+    // 本地源可用性：图声明了 sources（完整检索面）→ 必须含 local-file 条目才可用；
+    // 未声明 sources（legacy 位/无目录）→ 本地内置可用（宿主装配形态）
+    const localEnabled = opts?.localEnabled ?? (resolved?.hasCatalog ? resolved.hasLocal : true);
+    const effectiveRetrievers = localEnabled ? retrievers : undefined;
+    const requested = toolScope ?? [...available];
+    const allowed = requested.filter((n) => available.has(n) && !requireConfirm(n));
+    const excludedConfirmToolNames = toolScope?.filter((n) => available.has(n) && requireConfirm(n)) ?? [];
+    // 注意：loadedToolsToApiTools 的既有语义是"空名单=全部"（llm 节点 skillTools 在用）；
+    // rag 语义相反——圈定了但为空（会话勾选剔除全部外部源）就是没有外部工具
+    const apiTools = allowed.length ? loadedToolsToApiTools(loadedTools, allowed) : [];
+    // 资源目录注入 description：带 source 的外部源把合法资源值（表名/appid/collection…）
+    // 前置到工具描述，LLM 据此选参——内核不猜参数名，按工具 schema 由 LLM 填
+    for (const t of apiTools) {
+        const catalog = sourceCatalog[t.function.name];
+        if (catalog?.length) {
+            t.function.description = appendSourceCatalog(t.function.description, catalog);
+        }
+    }
+    const kbToolNames = new Set(allowed);
+    const missingToolNames = toolScope?.filter((n) => !available.has(n)) ?? [];
+    if (effectiveRetrievers?.length) {
+        apiTools.push(localSearchTool(effectiveRetrievers));
+        const kwRetrievers = effectiveRetrievers.filter((r) => typeof r.retrieveByKeyword === 'function');
+        if (kwRetrievers.length)
+            apiTools.push(keywordSearchTool(kwRetrievers));
+    }
+    apiTools.push(RAG_FINISH_TOOL);
+    return { apiTools, kbToolNames, missingToolNames, excludedConfirmToolNames };
+}
+/**
+ * briefList — 给 LLM 的精简结果清单
+ *
+ * 关键设计：检索全文只进 perSource（供 fuse/denoise），决策上下文只放
+ * 标题+短摘录——避免数万 token 检索结果把 ReAct 决策上下文撑爆。
+ */
+export function briefList(docs, maxExcerpt = 80) {
+    if (!docs.length)
+        return '(无结果)';
+    return docs
+        .map((d, i) => {
+        const title = docTitle(d);
+        const excerpt = d.content.slice(0, maxExcerpt).replace(/\s+/g, ' ');
+        return `${i + 1}. [${d.sourceId}] ${title}：${excerpt}…`;
+    })
+        .join('\n');
+}
+export function docTitle(d) {
+    const meta = d.metadata ?? {};
+    return String(meta['title'] ?? meta['fileName'] ?? d.rawId);
+}

package/dist/graph/nodes/rag/types.d.ts

@@ -0,0 +1,226 @@
+/**
+ * RAG 节点类型定义 — 检索子智能体
+ *
+ * RagNode 是黑盒节点（type: rag）：query 进、降噪上下文出，
+ * 内部跑 ReAct 循环（LLM 决策 + 三路工具派发）。
+ *
+ * @see mt-docs/1-requirements/specs/agentic-rag/design-v2.md §5
+ */
+import type { ILLMProvider } from '../llm-node.js';
+import type { NodeRetryConfig } from '../../contracts/executable-graph.js';
+import type { ToolOrchestrator } from '../../../tool/tool-orchestrator.js';
+import type { IGovernanceClient } from '../../../governance/governance-client.js';
+/**
+ * RetrievalDoc — 融合唯一输入的统一结构
+ *
+ * 知识库 tool 的字符串结果经 normalize 转成此结构；
+ * 本地 retriever 直返此结构（这是本地源不走工具系统的核心理由）。
+ * @see design-v2 §6.1
+ */
+export interface RetrievalDoc {
+    /** 文本内容（必需） */
+    content: string;
+    /** 来源标识：'kb' | 'local' | 自定义源 id */
+    sourceId: string;
+    /** 源内原始 ID（跨源配额内去重键 sourceId:rawId 用） */
+    rawId: string;
+    /** 原始分数（仅记录，融合不跨源比较） */
+    score?: number;
+    /** 源特有信息（标题/文件路径/时间等） */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * IRetriever — 本地检索内置接口
+ *
+ * 向量引擎（SQLite 向量库 / 文件解析 / 分片 / embed）整体封装在这一个方法之后，
+ * react-loop 只面向本接口编程；正式实现为 LocalSqliteRetriever（design-v2 §7）。
+ */
+export interface IRetriever {
+    readonly sourceId: string;
+    retrieve(query: string, opts: {
+        topK: number;
+        userId: string;
+        scope?: RagScope;
+    }): Promise<RetrievalDoc[]>;
+    /**
+     * 关键词精确检索（可选能力，FTS5 bm25）：适合编号/数字/专有名词等 embedding 短板查询。
+     * 实现方缺省不提供——react-loop 检测到至少一个源支持才把 keyword_search 伪工具进表。
+     */
+    retrieveByKeyword?(query: string, opts: {
+        topK: number;
+        userId: string;
+        scope?: RagScope;
+    }): Promise<RetrievalDoc[]>;
+}
+/**
+ * IEmbedder — query 向量化端口（design-v2 §7.3）
+ *
+ * 配置经构造参数注入（宿主装配）：
+ * gateway embedding（Qwen3-Embedding-8B，OpenAI 兼容 /v1/embeddings）；
+ * token 计量由实现侧落到 runtime 统一记账。
+ */
+export interface IEmbedder {
+    /** embedding 模型标识（对应引擎 model_version 锁，不一致引擎会拒） */
+    readonly model: string;
+    /** 向量维度（须与建库 dims 一致；引擎侧另有一致性校验兜底） */
+    readonly dims: number;
+    /** 批量向量化（结果与入参顺序一致） */
+    embed(texts: string[]): Promise<number[][]>;
+}
+/**
+ * RagScope — 请求级检索范围（前端圈定，随对话请求传入）
+ *
+ * fileIds/dirPaths 并集语义；dirPaths 由引擎按路径前缀解析成 fileIds（REPLACE
+ * 统一分隔符 + 尾分隔符锚定防前缀误中）。过滤叠加在 userId 隔离之内——圈到
+ * 他人属主的文件只会空结果，无越权读。仅作用于本地检索源（local/keyword）。
+ */
+export interface RagScope {
+    /** 圈定的文件 id 集合（查询面 listFiles 的 file_id） */
+    fileIds?: string[];
+    /** 圈定的目录路径前缀（按目录整棵圈定，含子目录） */
+    dirPaths?: string[];
+}
+/** 引擎返回的原始行（runtime 侧自持类型，不 import 引擎包） */
+export interface VectorRow {
+    id: number | string;
+    distance: number;
+    content: string;
+    fileId: string;
+    fileName: string;
+    filePath: string;
+    chunkId: string;
+}
+/** 引擎关键词检索行（rank 为 FTS5 bm25，越小越相关；id 与向量检索同源——溯源对齐） */
+export interface KeywordRow {
+    id: number | string;
+    rank: number;
+    content: string;
+    fileId: string;
+    fileName: string;
+    filePath: string;
+    chunkId: string;
+}
+/**
+ * VectorEnginePort — 向量引擎窄端口（design-v2 §7.3 去服务化版）
+ *
+ * 宿主用引擎包实例满足（如 createAsyncEngine 产物：全 Promise、同步 SQLite
+ * 隔离在后台线程）；runtime 对 native 零接触，服务端形态不装引擎包。
+ */
+export interface VectorEnginePort {
+    search(vector: number[], opts: {
+        topK: number;
+        userId: string;
+        fileIds?: string[];
+    }): Promise<VectorRow[]>;
+    /** 关键词检索（可选能力：引擎包已内置 FTS5；旧端口实现不提供即无 keyword_search 工具） */
+    searchByKeyword?(query: string, opts: {
+        topK: number;
+        userId: string;
+        fileIds?: string[];
+    }): Promise<KeywordRow[]>;
+    /** 请求级范围解析：目录前缀 → fileIds（可选能力；未实现时仅 fileIds 圈定生效） */
+    resolveScopeFileIds?(scope: {
+        fileIds?: string[];
+        dirPathPrefixes?: string[];
+    }): Promise<string[] | null>;
+    /** 查询侧模型标识校验（可选能力：引擎锁定 model_version 且请求不一致即拒） */
+    assertQueryModel?(modelVersion: string): Promise<void> | void;
+}
+/**
+ * RagEventSink — rag 内部事件出口（SSE 旁路，rag.* 五事件）
+ *
+ * adapter 接线到 streamSink（stream() 存活期间有效，缺省静默）；
+ * 测试与宿主可直接注入收集器。黑盒内部过程经此对外可见。
+ */
+export type RagEventSink = (type: 'rag.round' | 'rag.search' | 'rag.denoise' | 'rag.rewrite' | 'rag.finish', payload: Record<string, unknown>) => void;
+/**
+ * RagSourceDescriptor — 数据源描述符（统一"数据源"抽象，避免与主智能体 tools 混淆）
+ *
+ * 三字段模型：type 定接入实现、id 对外唯一标识、source 定资源定位。
+ * type 是开放集合（无缝扩展契约：新数据源类型零内核改动接入）：
+ * - 'local-file'：本地引擎方法，source = 目录路径（旧式无 source 时 id 即路径，兼容）
+ * - 其余任意 type（kb/dw/api/maxkb/milvus/…）：工具面实现，工具名 = ref 显式指定
+ *   ?? `${type}_search` 约定；source = 工具内资源定位（dw=表/库、maxkb=appid、
+ *   milvus=collection…），经工具 description 的资源目录暴露给 LLM——一型一工具、
+ *   源是参数，同型多源（两张数仓表）由 LLM 按目录选参调用
+ */
+export interface RagSourceDescriptor {
+    /** 数据源类别（开放集合）：'local-file' | 'kb' | 'dw' | 'maxkb' | 'milvus' | … */
+    type: string;
+    /** 对外唯一标识：会话级勾选（请求 ragSources）按此过滤，亦作展示名 */
+    id: string;
+    /** 资源定位：local-file→目录路径；dw→表/库；maxkb→appid；milvus→collection（可选） */
+    source?: string;
+    /** 外部源显式工具名；缺省按约定 `${type}_search` 解析（local-file 非工具源，无此字段） */
+    ref?: string;
+}
+/**
+ * RagRetrievalSources — 检索源配置（DSL config.retrievalSources）
+ *
+ * 产品概念只有"数据源"（文件夹/知识库/数仓…）；本地向量库是宿主实现细节
+ * （单库，由装配注入检索器），不经 DSL 暴露路径。
+ * 会话级勾选（请求 ragSources 传 id 列表）在此基础上过滤，无需改图。
+ */
+export interface RagRetrievalSources {
+    /** 预定义数据源目录：外部源（字符串=注册工具名的简写，或描述符）+ 本地文件夹（描述符） */
+    sources?: Array<string | RagSourceDescriptor>;
+    /** @deprecated 旧位：外部工具名清单，等价 sources 全字符串简写（过渡期保留） */
+    retrievalTools?: string[];
+}
+/** RagNodeConfig — DSL config（全部可选，均有缺省） */
+export interface RagNodeConfig {
+    /** 模型（决策/判分/重写共用同一主力模型，与 llm 节点同体系），缺省 'default' */
+    model?: string;
+    /** 融合后总条数，缺省 10 */
+    totalK?: number;
+    /** ReAct 决策轮硬上限（按决策轮计次，同轮并发多个 tool_call 只计 1），缺省 5 */
+    maxIterations?: number;
+    /** 近重判定阈值（字符 n-gram Jaccard，M4 启用），缺省 0.8 */
+    nearDupThreshold?: number;
+    /** 检索源：数据源目录 + 本地向量库（与旧 tools 字段同现时以本字段为准） */
+    retrievalSources?: RagRetrievalSources;
+    /** @deprecated 旧位：本节点可见的工具名清单，等价 retrievalSources.sources 字符串简写（过渡期保留） */
+    tools?: string[];
+    /** 工具名 → 融合源桶映射（如 { 'kb-search': 'kb', 'dw-query': 'dw' }），缺省全部工具归 'kb' 桶 */
+    toolSources?: Record<string, string>;
+    /** 决策调用重试（与 llm 节点同语义：3 次 + 指数退避，可覆盖） */
+    retry?: NodeRetryConfig;
+}
+/**
+ * RagNodeDeps — 宿主装配时注入的依赖（LangGraphAdapter 第 6 参）
+ *
+ * 实例均为无状态单例，可跨请求复用；请求级数据（query/userId/loadedTools 等）
+ * 一律经 execute(state) 流转，节点实例上不放请求级状态。
+ */
+export interface RagNodeDeps {
+    /** LLM 调用提供者（与 llm 节点同一实例体系） */
+    llmProvider: ILLMProvider;
+    /** 调知识库等注册工具（缺省回退 adapter 已组装的 orchestrator） */
+    toolOrchestrator?: ToolOrchestrator;
+    /** 工具权限治理（预留：当前权限校验经 ToolOrchestrator 内置 governance） */
+    governanceClient?: IGovernanceClient;
+    /** 内置检索器（本地 SQLite 单库，宿主装配；服务端为空数组/缺省） */
+    retrievers?: IRetriever[];
+    /** rag.* 事件出口：adapter 接线 streamSink（宿主无需提供，测试可注入） */
+    emitEvent?: RagEventSink;
+}
+/** RagTokenUsage — 循环内单次 LLM 调用明细，写入 __llmTokenUsage 数组累加器 */
+export interface RagTokenUsage {
+    nodeId: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    durationMs?: number;
+}
+/**
+ * DenoiseVerdict — 相关性判定输出契约（design-v2 §6.3，一次结构化 LLM 调用产出）
+ */
+export interface DenoiseVerdict {
+    /** 复合键 sourceId:rawId（与候选文档标签同构；rawId 仅源内唯一，裸 id 跨源会碰撞） */
+    rawId: string;
+    relevant: boolean;
+    /** 一句话理由（进 trace / 空结果重写定向用） */
+    reason: string;
+    /** relevant 时保留的句子编号集合（缺省 / 无有效编号 = 整篇保留） */
+    keepSentences?: number[];
+}

package/dist/graph/nodes/rag/types.js

@@ -0,0 +1,9 @@
+/**
+ * RAG 节点类型定义 — 检索子智能体
+ *
+ * RagNode 是黑盒节点（type: rag）：query 进、降噪上下文出，
+ * 内部跑 ReAct 循环（LLM 决策 + 三路工具派发）。
+ *
+ * @see mt-docs/1-requirements/specs/agentic-rag/design-v2.md §5
+ */
+export {};