@gt-fe/eap-runtime 0.0.20 → 0.0.21

package/dist/graph/nodes/rag/rag-search-tool.d.ts

@@ -0,0 +1,48 @@
+/**
+ * rag_search — 工具封装入口（design-v2 §5.3「工具封装形态」开放形态之一）
+ *
+ * 主 Agent 的 llm 节点发 tool_calls: [rag_search(query)] → 本执行器拦截，
+ * 内部跑同一个 runReactLoop——内核同一，入口不同。query 已由主 LLM 结合
+ * 对话上下文整定（§5.4：工具封装入口拿到的已是整定过的查询，内核首轮
+ * 职责自动退化为直接检索，history 传空）。
+ *
+ * 装配（宿主三步）：
+ *   const ragSearch = new RagSearchToolExecutor(真实 executor, ragNodeDeps, ragConfig, registryTools);
+ *   new LangGraphAdapter(checkpointer, llmProvider, ragSearch, ...);   // 第 3 参
+ *   loadedTools 里 merge ragSearchLoadedTool();                          // 主 LLM 工具表可见
+ *
+ * 防递归：rag_search 永不进入内层工具表——config.tools 显式圈定时自动剔除
+ * rag_search 自身；未圈定时内层工具表退化为 local_search + rag_finish
+ * （registryTools 不传即无注册工具），杜绝套娃。
+ */
+import type { IToolExecutor, ToolCallRequest, ToolCallResult } from '../../../tool/tool-executor.interface.js';
+import type { ToolOrchestrator } from '../../../tool/tool-orchestrator.js';
+import type { LoadedToolMap, LoadedToolDefinition } from '../../../tool/loaded-tool-definition.js';
+import type { RagNodeConfig, RagNodeDeps } from './types.js';
+export declare const RAG_SEARCH_TOOL_NAME = "rag_search";
+/** 合成 loadedTools 条目：主 agent 的 llm 节点工具表由此看到 rag_search */
+export declare function ragSearchLoadedTool(): LoadedToolDefinition;
+export interface RagSearchToolOptions {
+    /** rag 内核配置（totalK/quota/maxIterations/nearDupThreshold…） */
+    config?: RagNodeConfig;
+    /**
+     * 注册表快照：config.tools 显式圈定注册工具源（如 kb-search）时必传
+     * （内层路 B 路由元数据来源）；未传时内层工具表 = local_search + rag_finish。
+     */
+    registryTools?: LoadedToolMap;
+}
+export declare class RagSearchToolExecutor implements IToolExecutor {
+    private readonly inner;
+    private readonly deps;
+    private readonly config;
+    private readonly registryTools;
+    /** 装配期检索面的门禁映射（请求带图声明时按请求重建） */
+    private readonly sourceIdsByTool;
+    constructor(inner: IToolExecutor, deps: RagNodeDeps, options?: RagSearchToolOptions);
+    /** adapter 注入的编排器（节点形态同款回退链：deps 显式 > adapter 注入 > inner 直执） */
+    private attachedOrchestrator?;
+    /** 宿主装配（LangGraphAdapter）注入图级 ToolOrchestrator——kb 派发走与 tool 节点同一编排 */
+    attachToolOrchestrator(orchestrator: ToolOrchestrator): void;
+    private resolveOrchestrator;
+    execute(req: ToolCallRequest): Promise<ToolCallResult>;
+}

package/dist/graph/nodes/rag/rag-search-tool.js

@@ -0,0 +1,230 @@
+/**
+ * rag_search — 工具封装入口（design-v2 §5.3「工具封装形态」开放形态之一）
+ *
+ * 主 Agent 的 llm 节点发 tool_calls: [rag_search(query)] → 本执行器拦截，
+ * 内部跑同一个 runReactLoop——内核同一，入口不同。query 已由主 LLM 结合
+ * 对话上下文整定（§5.4：工具封装入口拿到的已是整定过的查询，内核首轮
+ * 职责自动退化为直接检索，history 传空）。
+ *
+ * 装配（宿主三步）：
+ *   const ragSearch = new RagSearchToolExecutor(真实 executor, ragNodeDeps, ragConfig, registryTools);
+ *   new LangGraphAdapter(checkpointer, llmProvider, ragSearch, ...);   // 第 3 参
+ *   loadedTools 里 merge ragSearchLoadedTool();                          // 主 LLM 工具表可见
+ *
+ * 防递归：rag_search 永不进入内层工具表——config.tools 显式圈定时自动剔除
+ * rag_search 自身；未圈定时内层工具表退化为 local_search + rag_finish
+ * （registryTools 不传即无注册工具），杜绝套娃。
+ */
+import { buildRagTools, resolveRagSources, mergeLocalDirs, sourceToolName } from './tools.js';
+import { runReactLoop } from './react-loop.js';
+export const RAG_SEARCH_TOOL_NAME = 'rag_search';
+/** 合成 loadedTools 条目：主 agent 的 llm 节点工具表由此看到 rag_search */
+export function ragSearchLoadedTool() {
+    return {
+        toolId: 'tool-rag-search',
+        name: RAG_SEARCH_TOOL_NAME,
+        manifest: {
+            id: 'tool-rag-search',
+            name: RAG_SEARCH_TOOL_NAME,
+            version: '1.0.0',
+            // http/server：无论 server/desktop 部署都锁定 httpExecutor 路径（装饰器位置），
+            // 避免被 local 安装分流绕过拦截
+            type: 'http',
+            toolRuntime: 'server',
+            dataScope: 'global',
+            description: '检索企业知识库与本地文档，返回压缩后的高相关证据上下文（内部运行 RAG 检索子智能体）。',
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: '自包含的检索查询' },
+                topK: { type: 'number', description: '融合后返回条数上限（可选）' },
+            },
+            required: ['query'],
+        },
+    };
+}
+/**
+ * 工具名 → 数据源 id 列表（会话勾选门禁用）——从检索面声明构建。
+ * 解析序必须与 resolveRagSources 一致（sources 优先，无 sources 再看
+ * retrievalTools/tools）：只遍历 sources 会让 legacy 声明位不进门禁映射，
+ * 直调放行而内层按 ragSources 过滤，同图两路口径分裂。legacy 字符串条目的
+ * id 即工具名本身——映射为 {工具名:[工具名]}，勾选该名才放行。
+ */
+function buildSourceIdsByTool(config) {
+    const map = new Map();
+    const rs = config.retrievalSources;
+    const entries = rs?.sources
+        ? rs.sources.map((e) => (typeof e === 'string' ? { type: 'external', id: e } : e))
+        : ((rs?.retrievalTools ?? config.tools)?.map((n) => ({ type: 'external', id: n })) ?? []);
+    for (const e of entries) {
+        const tool = sourceToolName(e);
+        if (!tool || tool === RAG_SEARCH_TOOL_NAME)
+            continue;
+        const ids = map.get(tool) ?? [];
+        ids.push(e.id);
+        map.set(tool, ids);
+    }
+    return map;
+}
+export class RagSearchToolExecutor {
+    inner;
+    deps;
+    config;
+    registryTools;
+    /** 装配期检索面的门禁映射（请求带图声明时按请求重建） */
+    sourceIdsByTool;
+    constructor(inner, deps, options = {}) {
+        this.inner = inner;
+        this.deps = deps;
+        // 防递归前置：解析到 rag_search 自身的源条目剔除，描述符原样保留
+        // （三字段模型下字符串化会丢 source 资源目录）；三种声明位按原位回写
+        const config = { ...options.config };
+        const rs = config.retrievalSources;
+        if (rs?.sources) {
+            config.retrievalSources = {
+                ...rs,
+                sources: rs.sources.filter((e) => sourceToolName(typeof e === 'string' ? { type: 'external', id: e } : e) !== RAG_SEARCH_TOOL_NAME),
+            };
+        }
+        else if (rs?.retrievalTools) {
+            config.retrievalSources = { ...rs, retrievalTools: rs.retrievalTools.filter((n) => n !== RAG_SEARCH_TOOL_NAME) };
+        }
+        else if (config.tools) {
+            config.tools = config.tools.filter((n) => n !== RAG_SEARCH_TOOL_NAME);
+        }
+        this.config = config;
+        this.registryTools = options.registryTools;
+        this.sourceIdsByTool = buildSourceIdsByTool(config);
+    }
+    /** adapter 注入的编排器（节点形态同款回退链：deps 显式 > adapter 注入 > inner 直执） */
+    attachedOrchestrator;
+    /** 宿主装配（LangGraphAdapter）注入图级 ToolOrchestrator——kb 派发走与 tool 节点同一编排 */
+    attachToolOrchestrator(orchestrator) {
+        if (!this.deps.toolOrchestrator)
+            this.attachedOrchestrator = orchestrator;
+    }
+    resolveOrchestrator() {
+        if (this.deps.toolOrchestrator)
+            return this.deps.toolOrchestrator;
+        if (this.attachedOrchestrator)
+            return this.attachedOrchestrator;
+        // 兜底：kb 调用直经 inner 执行器（与 tool 节点同一条执行链，缺省编排层记账）
+        this.attachedOrchestrator = {
+            executeAll: async (reqs) => Promise.all(reqs.map(async (r) => {
+                try {
+                    return await this.inner.execute(r);
+                }
+                catch (err) {
+                    return {
+                        toolCallId: r.toolCallId,
+                        toolName: r.toolName,
+                        content: '',
+                        success: false,
+                        error: err instanceof Error ? err.message : String(err),
+                    };
+                }
+            })),
+        };
+        return this.attachedOrchestrator;
+    }
+    async execute(req) {
+        // 图声明的检索面（tool 节点 config.retrievalSources）覆盖装配期配置——图即真相；
+        // 图声明的 totalK（config.totalK）同为该请求缺省（调用级 topK 参数在下方仍可覆盖）
+        const faceConfig = {
+            ...this.config,
+            ...(req.ragSourcesConfig ? { retrievalSources: req.ragSourcesConfig } : {}),
+            ...(req.ragTotalK !== undefined ? { totalK: req.ragTotalK } : {}),
+        };
+        const gateMap = req.ragSourcesConfig ? buildSourceIdsByTool(faceConfig) : this.sourceIdsByTool;
+        if (req.toolName !== RAG_SEARCH_TOOL_NAME) {
+            // 会话勾选激活时，目录内工具按勾选放行（主 LLM 直调与 rag_search 内层同规则）：
+            // 一型多源（同工具多资源）任一 id 勾选即放行；目录外工具不受影响
+            if (req.ragSources !== undefined) {
+                const ids = gateMap.get(req.toolName);
+                if (ids && !ids.some((id) => req.ragSources?.includes(id))) {
+                    // 失败返回必须带 error：上层失败时丢弃 content 只读 error，缺 error 会被渲染成 unknown error
+                    return {
+                        toolCallId: req.toolCallId,
+                        toolName: req.toolName,
+                        content: `[Tool Error] 数据源（${ids.join('、')}）本次会话未勾选启用（ragSources），如需使用请在面板勾选该数据源`,
+                        success: false,
+                        error: `数据源（${ids.join('、')}）本次会话未勾选启用（ragSources），如需使用请在面板勾选该数据源`,
+                    };
+                }
+            }
+            return this.inner.execute(req);
+        }
+        const query = String(req.arguments['query'] ?? '');
+        if (!query.trim()) {
+            return {
+                toolCallId: req.toolCallId,
+                toolName: req.toolName,
+                content: '[Tool Error] rag_search 缺少必填参数 query',
+                success: false,
+                error: 'rag_search 缺少必填参数 query',
+            };
+        }
+        const topK = typeof req.arguments['topK'] === 'number' ? req.arguments['topK'] : undefined;
+        const config = topK !== undefined ? { ...faceConfig, totalK: topK } : faceConfig;
+        // 会话级控制（tool 节点从 GraphState 转递，与节点形态同语义）：
+        // 勾选按 id 过滤检索面（资源目录同步收窄）；请求 ragScope 与 local-file
+        // 白名单合并（声明过但未勾 = fileIds:[] 显式关本地）
+        const { toolScope, sourceCatalog, hasLocal, hasCatalog, localDirs, localDirsAll } = resolveRagSources(faceConfig, req.ragSources);
+        // 图声明了 sources = 完整检索面：无 local-file 条目则本地源整体不可用（不进工具表）。
+        // 本地选择权与 RagNode 同规则：请求带 ragScope.dirPaths 时以声明全量面为交集基准
+        const localEnabled = hasCatalog ? hasLocal : true;
+        const ragScope = localEnabled
+            ? mergeLocalDirs(hasLocal, req.ragScope?.dirPaths !== undefined ? localDirsAll : localDirs, req.ragScope)
+            : undefined;
+        // 内层工具表优先用本轮 loadedTools（请求级，含会话勾选后的完整注册面）；
+        // 剥掉 rag_search 自身防递归；缺省回退构造期 registryTools 快照
+        const reqTools = req.loadedTools;
+        const innerTools = reqTools && RAG_SEARCH_TOOL_NAME in reqTools
+            ? Object.fromEntries(Object.entries(reqTools).filter(([n]) => n !== RAG_SEARCH_TOOL_NAME))
+            : (reqTools ?? this.registryTools);
+        const { apiTools, kbToolNames, missingToolNames, excludedConfirmToolNames } = buildRagTools(config, innerTools, localEnabled ? this.deps.retrievers : undefined, { toolScope, sourceCatalog, localEnabled });
+        if (missingToolNames.length > 0 || excludedConfirmToolNames.length > 0) {
+            return {
+                toolCallId: req.toolCallId,
+                toolName: req.toolName,
+                content: `[Tool Error] rag_search 检索源 tools 引用了不可用工具: ${[
+                    ...missingToolNames,
+                    ...excludedConfirmToolNames,
+                ].join(', ')}`,
+                success: false,
+                error: `rag_search 检索源 tools 引用了不可用工具: ${[...missingToolNames, ...excludedConfirmToolNames].join(', ')}`,
+            };
+        }
+        // 已知限制（与图级工具派发的差异）：tool 节点/llm 链路把 state.executionContext
+        // （含 delegationToken）透传给 ToolOrchestrator.executeAll/executeSingle，治理断言
+        // （assertToolPermission）可命中；工具形态的内层 kb 派发只能从 ToolCallRequest 取参，
+        // 而该结构无执行上下文转递位，此处未传 executionContext → orchestrator 因
+        // delegationToken 缺失跳过治理断言。后续 ToolCallRequest 增加执行上下文转递后此处透传。
+        const loop = await runReactLoop({
+            nodeId: `rag-search:${req.toolCallId}`,
+            query,
+            history: [], // 主 LLM 已整定 query，无需对话上下文（§5.4）
+            config,
+            apiTools,
+            kbToolNames,
+            llmProvider: this.deps.llmProvider,
+            toolOrchestrator: this.resolveOrchestrator(),
+            retrievers: this.deps.retrievers,
+            loadedTools: innerTools,
+            authContext: req.authContext ?? {},
+            userId: req.authContext?.userId ?? '',
+            ragScope,
+            emitEvent: this.deps.emitEvent,
+        });
+        return {
+            toolCallId: req.toolCallId,
+            toolName: req.toolName,
+            // 空结果是合法业务结果（"查了，没查到"），不是执行失败：success 恒 true，
+            // 空手体现在 content 文案。此前 success:!loop.empty 且无 error 字段，会被
+            // tool-node 渲染成 "[Tool Error] unknown error"，误导主 LLM 判定服务故障。
+            content: loop.contextText || `[rag] 未找到高相关结果（query: ${query}）。可换个关键词重试，或确认目标内容已入库。`,
+            success: true,
+        };
+    }
+}

package/dist/graph/nodes/rag/react-loop.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 type { ILLMProvider, LLMToolDefinition } from '../llm-node.js';
+import type { GraphMessage } from '../../contracts/executable-graph.js';
+import type { AuthContext, ToolOrchestrator } from '../../../tool/tool-orchestrator.js';
+import type { LoadedToolMap } from '../../../tool/loaded-tool-definition.js';
+import type { ExecutionContext } from '@gt-fe/eap-contracts';
+import type { ITraceCollector } from '../../../contracts/trace-collector.js';
+import type { IRetriever, RagEventSink, RagNodeConfig, RagScope, RagTokenUsage } from './types.js';
+export interface RagLoopInput {
+    nodeId: string;
+    query: string;
+    /** 对话上下文（首轮整定指代/省略用） */
+    history: GraphMessage[];
+    config: RagNodeConfig;
+    /** 壳已圈定好的工具表（①注册工具 + ②local_search + ③rag_finish） */
+    apiTools: LLMToolDefinition[];
+    kbToolNames: Set<string>;
+    llmProvider: ILLMProvider;
+    toolOrchestrator?: ToolOrchestrator;
+    retrievers?: IRetriever[];
+    loadedTools?: LoadedToolMap;
+    authContext: AuthContext;
+    executionContext?: ExecutionContext;
+    forceToolServer?: string[];
+    userId: string;
+    /** 请求级检索范围（前端圈定 fileIds/dirPaths 并集；缺省不限）——只作用于本地检索源 */
+    ragScope?: RagScope;
+    /** rag.* 事件出口（SSE 旁路，缺省静默；adapter 接线 streamSink） */
+    emitEvent?: RagEventSink;
+    /** Trace 采集器 + 执行流 ID（缺省不建 span，照 ToolNode 模式：resolveTraceId） */
+    traceCollector?: ITraceCollector;
+    traceId?: string;
+}
+export interface RagLoopOutput {
+    /** 降噪上下文（近重去重 + LLM 判定 + 句子抽取后的拼装结果） */
+    contextText: string;
+    /** 空手标识（检索全失败/全被滤，含重查后仍空） */
+    empty: boolean;
+    iterations: number;
+    tokenUsage: RagTokenUsage[];
+}
+export declare function runReactLoop(input: RagLoopInput): Promise<RagLoopOutput>;