@gt-fe/eap-runtime 0.0.19 → 0.0.21

package/dist/providers/routing-llm-provider.js

@@ -11,9 +11,22 @@
  * - 支持任意 OpenAI 兼容 API（OpenAI / DeepSeek / 本地 Ollama 等）
  * - 连接配置由 Foundation 统一管理，Runtime 无感知
  */
-import { mergeModelCallParams } from '@gt-fe/eap-contracts';
+import { AppError, ErrorCodes, mergeModelCallParams } from '@gt-fe/eap-contracts';
 import { EchoLLMProvider } from './echo-llm-provider.js';
 import { DEFAULT_LLM_HTTP_TIMEOUT_MS, HttpLLMProvider } from './http-llm-provider.js';
+export const MODELS_INVOKE_STREAM_MESSAGE = 'EAP_RUNTIME_MODELS_INVOKE 实验口只支持同步 invoke（POST /models/invoke），不支持 stream。关掉该开关，或改走 Foundation /models/select + 本机 HTTP。';
+export function isFoundationModelsInvokeEnabled(env = process.env) {
+    const raw = env.EAP_RUNTIME_MODELS_INVOKE;
+    return raw === '1' || raw === 'true';
+}
+/** `/models/invoke` 无真流式；开了该开关时 RoutingLLMProvider.stream 必须失败。 */
+export function assertFoundationModelsInvokeAllowsStream(env = process.env) {
+    if (!isFoundationModelsInvokeEnabled(env))
+        return;
+    throw new AppError(ErrorCodes.GRAPH_EXECUTION_ERROR, MODELS_INVOKE_STREAM_MESSAGE, {
+        exposeMessage: true,
+    });
+}
 export class RoutingLLMProvider {
     foundationUrl;
     fallback;
@@ -29,6 +42,7 @@ export class RoutingLLMProvider {
         return provider.invoke(messages, this.withCallDefaults(config, selected));
     }
     async *stream(messages, config) {
+        assertFoundationModelsInvokeAllowsStream();
         const selected = await this.selectModel(config);
         const provider = this.createProviderForModel(selected);
         yield* provider.stream(messages, this.withCallDefaults(config, selected));
@@ -72,7 +86,13 @@ export class RoutingLLMProvider {
         }
         return { name: config.model ?? 'echo', provider: 'local', connection: null };
     }
+    useFoundationInvoke() {
+        return isFoundationModelsInvokeEnabled();
+    }
     createProviderForModel(selected) {
+        if (this.useFoundationInvoke()) {
+            return new FoundationModelsInvokeProvider(this.foundationUrl, selected.name, this.turnLog);
+        }
         // 优先使用 Foundation 返回的连接配置
         if (selected.connection) {
             return new HttpLLMProvider({
@@ -96,3 +116,48 @@ export class RoutingLLMProvider {
         return this.fallback;
     }
 }
+/**
+ * Foundation `/models/invoke` 实验口。默认关。
+ * 只实现同步 invoke；stream 拒绝（无真流式、无鉴权头）。
+ * Foundation 未提供该接口时不要开 EAP_RUNTIME_MODELS_INVOKE。
+ */
+class FoundationModelsInvokeProvider {
+    foundationUrl;
+    model;
+    turnLog;
+    constructor(foundationUrl, model, turnLog) {
+        this.foundationUrl = foundationUrl;
+        this.model = model;
+        this.turnLog = turnLog;
+    }
+    async invoke(messages, config) {
+        const res = await fetch(`${this.foundationUrl}/api/v1/models/invoke`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                model: config.model ?? this.model,
+                messages,
+                temperature: config.temperature,
+                maxTokens: config.maxTokens,
+            }),
+        });
+        if (!res.ok) {
+            throw new Error(`Foundation /models/invoke HTTP ${res.status}`);
+        }
+        const body = (await res.json());
+        const content = body.data?.content ?? body.content ?? '';
+        void this.turnLog;
+        return {
+            content,
+            inputTokens: body.data?.inputTokens ?? 0,
+            outputTokens: body.data?.outputTokens ?? 0,
+            model: body.data?.model ?? config.model ?? this.model,
+        };
+    }
+    async *stream(_messages, _config) {
+        assertFoundationModelsInvokeAllowsStream();
+        throw new AppError(ErrorCodes.GRAPH_EXECUTION_ERROR, MODELS_INVOKE_STREAM_MESSAGE, {
+            exposeMessage: true,
+        });
+    }
+}

package/dist/runtime/agent-runtime.d.ts

@@ -16,6 +16,7 @@ import type { SessionContextService } from '../session/session-context.service.j
 import type { MessageService } from '../session/message.service.js';
 import type { SessionService, SessionRecord, MessageRecord } from '../session/session.service.js';
 import { type ILlmTurnLog, type LlmTurnIndexEntry, type LlmTurnLogKind, type LlmTurnRecord } from '../debug/llm-turn-log.js';
+import { type SessionCompressionOptions } from '../session/apply-session-compression.js';
 import type { SSEEvent } from '../sse/contracts/sse-emitter.contract.js';
 import type { TaskService } from '../task/task.service.js';
 import type { ExecuteParams, ExecuteResult, ForkParams, ForkOverrides, ForkResult, HitlResponse, ResumeHitlResult, SeedSessionMessagesParams, SeedSessionMessagesResult } from './types.js';
@@ -46,6 +47,10 @@ export interface AgentRuntimeDeps {
      */
     traceCollector?: ITraceCollector;
     recordForkRelation?: RecordForkRelation;
+    /** 历史压缩；默认关。见 EAP_RUNTIME_COMPRESSION */
+    sessionCompression?: SessionCompressionOptions;
+    /** 长期记忆注入；默认关。见 EAP_RUNTIME_MEMORY */
+    sessionMemory?: import('../session/apply-session-memory.js').SessionMemoryOptions;
 }
 /** 一次对话详情：消息 + 每步 LLM 入参/响应。File / 内存 / Postgres 同一套结构。 */
 export interface ConversationDetail {

package/dist/runtime/agent-runtime.js

@@ -12,11 +12,15 @@ import { resolveAgentSystemPromptFromLoader } from '../registry/graph-loader.js'
 import { toLoadedSkillMap } from '../tool/system-prompt-builder.js';
 import { assembleLoadedTools } from '../tool/harness-primitives.js';
 import { createFileLlmTurnLogFromEnv, } from '../debug/llm-turn-log.js';
-import { buildHitlWaitingTaskOutput, buildTurnGraphMessages, buildTurnTranscriptFromStreamEvents, extractHitlThreadId, extractStreamReasoning, extractStreamTextDelta, messageRecordsToGraphMessages, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, } from '../session/persist-turn-messages.js';
+import { buildHitlWaitingTaskOutput, buildTurnGraphMessages, buildTurnTranscriptFromStreamEvents, extractHitlThreadId, extractStreamReasoning, applyStreamTextDelta, createStreamAssistantBuckets, visibleStreamAssistantText, streamAssistantTexts, messageRecordsToGraphMessages, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, resolveCheckpointThreadId, appendTerminalToolResult, } from '../session/persist-turn-messages.js';
+import { iterSessionCompression, } from '../session/apply-session-compression.js';
+import { applySessionMemory } from '../session/apply-session-memory.js';
+import { resolveTokenDetail, shouldEmitTokenSse } from '../token/token-detail.js';
 import { AppError, ErrorCodes } from '@gt-fe/eap-contracts';
 import { resolveExecutionContext } from '../governance/governance-client.js';
 import { resolveAgentCode } from '../common/agent-code.js';
 import { resolveTraceId } from '../common/trace-id.js';
+import { collectStreamNodeTokenUsage, recordTaskTokenUsages, tokenUsagesFromLlmChannel, } from '../token/record-task-token-usage.js';
 import { resolveSkillInputFromInvokeInput } from '../registry/skill-io-guard.js';
 const HITL_TERMINAL_STATUSES = [
     'success',
@@ -207,6 +211,8 @@ export class AgentRuntime {
             executionContext: ctx,
             userId,
             traceId: resolveTraceId(params),
+            ragScope: params.ragScope,
+            ragSources: params.ragSources,
         }, userId);
         return response.data;
     }
@@ -273,7 +279,31 @@ export class AgentRuntime {
             ? (await this.deps.graphLoader.resolveAgentDir(agentCode, params.agentVersion)) ?? undefined
             : undefined;
         const agentSystemPrompt = await resolveAgentSystemPromptFromLoader(this.deps.graphLoader, agentCode, params.agentVersion);
-        const history = messageRecordsToGraphMessages(sessionContext.messages);
+        let history = messageRecordsToGraphMessages(sessionContext.messages);
+        for await (const step of iterSessionCompression({
+            history,
+            sessionId,
+            userId,
+            taskId: task.id,
+            options: {
+                ...this.deps.sessionCompression,
+                turnLog: this.deps.sessionCompression?.turnLog ?? this.deps.turnLog,
+            },
+        })) {
+            if (step.kind === 'history') {
+                history = step.messages;
+                continue;
+            }
+            yield this.toSSE(step.kind === 'started' ? 'session.compression.started' : 'session.compression.completed', correlationId, task.id, { ...step.payload });
+        }
+        history = await applySessionMemory({
+            history,
+            userId,
+            agentCode,
+            query: typeof params.input === 'string' ? params.input : undefined,
+            options: this.deps.sessionMemory,
+        });
+        const tokenDetail = resolveTokenDetail(params.config?.tokenDetail);
         const messages = await buildTurnGraphMessages({
             history,
             input: params.input,
@@ -281,11 +311,12 @@ export class AgentRuntime {
             threadId: sessionId,
         });
         const startTime = Date.now();
-        let assistantText = '';
+        const assistantBuckets = createStreamAssistantBuckets();
         let toolCallReasoningContent;
         let assistantReasoningContent;
         const pendingToolCalls = [];
         const toolResults = [];
+        const nodeTokenUsages = [];
         try {
             for await (const runtimeEvent of this.deps.graphEngine.stream(graph, {
                 messages,
@@ -298,6 +329,8 @@ export class AgentRuntime {
                 sessionId,
                 executionContext: ctx,
                 forceToolServer: params.config?.forceToolServer,
+                ragScope: params.ragScope,
+                ragSources: params.ragSources,
                 loadedTools,
                 loadedSkills,
                 skillDefinitions,
@@ -321,32 +354,18 @@ export class AgentRuntime {
                         toolCallReasoningContent = p.reasoningContent;
                     }
                 }
-                if (runtimeEvent.type === 'tool.result') {
-                    const p = runtimeEvent.payload;
-                    if (p.toolCallId && p.toolName) {
-                        toolResults.push({
-                            toolCallId: p.toolCallId,
-                            toolName: p.toolName,
-                            content: p.content,
-                            success: p.success !== false,
-                        });
-                    }
-                }
+                // 终态 tool.result / tool.error 回填历史；willRetry 的 error 不进 transcript
+                appendTerminalToolResult(runtimeEvent.type, runtimeEvent.payload, toolResults);
                 const streamedReasoning = extractStreamReasoning(runtimeEvent.type, runtimeEvent.payload);
                 if (streamedReasoning)
                     assistantReasoningContent = streamedReasoning;
-                const delta = extractStreamTextDelta(runtimeEvent.type, runtimeEvent.payload);
-                if (delta) {
-                    if (runtimeEvent.type === 'response.final') {
-                        if (delta.trim())
-                            assistantText = delta;
-                    }
-                    else {
-                        assistantText += delta;
-                    }
+                applyStreamTextDelta(assistantBuckets, runtimeEvent.type, runtimeEvent.payload);
+                collectStreamNodeTokenUsage(runtimeEvent, nodeTokenUsages);
+                if (shouldEmitTokenSse(tokenDetail, runtimeEvent.type)) {
+                    yield this.runtimeEventToSSE(runtimeEvent, correlationId, task.id);
                 }
-                yield this.runtimeEventToSSE(runtimeEvent, correlationId, task.id);
             }
+            await recordTaskTokenUsages(this.deps.taskService, task.id, nodeTokenUsages);
             await this.deps.taskService.updateStatus(task.id, 'success');
             await persistTurnTranscript(this.deps.messageService, {
                 sessionId,
@@ -355,7 +374,9 @@ export class AgentRuntime {
                 messages: buildTurnTranscriptFromStreamEvents({
                     pendingToolCalls,
                     toolResults,
-                    assistantText,
+                    assistantTexts: streamAssistantTexts(assistantBuckets),
+                    assistantText: visibleStreamAssistantText(assistantBuckets),
+                    finishPoints: graph.finishPoints,
                     toolCallReasoningContent,
                     assistantReasoningContent,
                 }),
@@ -368,6 +389,7 @@ export class AgentRuntime {
         catch (err) {
             const hitlPaused = unwrapHitlPaused(err);
             if (hitlPaused) {
+                await recordTaskTokenUsages(this.deps.taskService, task.id, nodeTokenUsages);
                 await this.deps.taskService.updateStatus(task.id, 'waiting_hitl', buildHitlWaitingTaskOutput({
                     threadId: hitlPaused.threadId,
                     question: hitlPaused.question,
@@ -385,6 +407,7 @@ export class AgentRuntime {
                 return;
             }
             const message = err instanceof Error ? err.message : 'Unknown error';
+            await recordTaskTokenUsages(this.deps.taskService, task.id, nodeTokenUsages);
             await this.deps.taskService.updateStatus(task.id, 'failed', message);
             yield this.toSSE('task.error', correlationId, task.id, {
                 code: 'runtime.graph.execution_error',
@@ -404,7 +427,7 @@ export class AgentRuntime {
         let output = '';
         let waiting;
         let sawWait = false;
-        let assistantText = '';
+        const assistantBuckets = createStreamAssistantBuckets();
         for await (const event of this.streamResumeHitl(taskId, response)) {
             if (event.type === 'hitl.waited') {
                 sawWait = true;
@@ -416,21 +439,12 @@ export class AgentRuntime {
                 };
                 output = waiting.question;
             }
-            const delta = extractStreamTextDelta(event.type, event.data);
-            if (delta) {
-                if (event.type === 'response.final') {
-                    if (delta.trim())
-                        assistantText = delta;
-                }
-                else {
-                    assistantText += delta;
-                }
-            }
+            applyStreamTextDelta(assistantBuckets, event.type, event.data);
         }
         if (sawWait) {
             return { taskId, status: 'waiting_hitl', output, hitl: waiting };
         }
-        return { taskId, status: 'success', output: assistantText || output };
+        return { taskId, status: 'success', output: visibleStreamAssistantText(assistantBuckets) || output };
     }
     /**
      * HITL 恢复的流式入口：新开一条 SSE（第一条 stream 在 `hitl.waited` 后已结束）。
@@ -460,6 +474,7 @@ export class AgentRuntime {
         if (!claimed) {
             throw new AppError(ErrorCodes.TASK_HITL_INVALID_STATE, `Task ${taskId} is no longer waiting for HITL`, { exposeMessage: true });
         }
+        const tokenDetail = resolveTokenDetail(response.tokenDetail);
         yield this.toSSE('hitl.resumed', correlationId, taskId, {
             choice: response.choice,
             userId: response.userId,
@@ -511,11 +526,12 @@ export class AgentRuntime {
             traceCollector: this.deps.traceCollector,
         };
         const startTime = Date.now();
-        let assistantText = '';
+        const assistantBuckets = createStreamAssistantBuckets();
         let toolCallReasoningContent;
         let assistantReasoningContent;
         const pendingToolCalls = [];
         const toolResults = [];
+        const nodeTokenUsages = [];
         try {
             for await (const runtimeEvent of this.deps.graphEngine.stream(graph, continueState)) {
                 if (runtimeEvent.type === 'tool.called') {
@@ -531,33 +547,18 @@ export class AgentRuntime {
                         toolCallReasoningContent = p.reasoningContent;
                     }
                 }
-                if (runtimeEvent.type === 'tool.result' || runtimeEvent.type === 'tool.error') {
-                    const p = runtimeEvent.payload;
-                    if (p.toolCallId && p.toolName) {
-                        toolResults.push({
-                            toolCallId: p.toolCallId,
-                            toolName: p.toolName,
-                            content: p.content ?? p.error,
-                            success: runtimeEvent.type === 'tool.result' && p.success !== false,
-                        });
-                    }
-                }
+                appendTerminalToolResult(runtimeEvent.type, runtimeEvent.payload, toolResults);
                 const streamedReasoning = extractStreamReasoning(runtimeEvent.type, runtimeEvent.payload);
                 if (streamedReasoning)
                     assistantReasoningContent = streamedReasoning;
-                const delta = extractStreamTextDelta(runtimeEvent.type, runtimeEvent.payload);
-                if (delta) {
-                    if (runtimeEvent.type === 'response.final') {
-                        if (delta.trim())
-                            assistantText = delta;
-                    }
-                    else {
-                        assistantText += delta;
-                    }
+                applyStreamTextDelta(assistantBuckets, runtimeEvent.type, runtimeEvent.payload);
+                collectStreamNodeTokenUsage(runtimeEvent, nodeTokenUsages);
+                if (shouldEmitTokenSse(tokenDetail, runtimeEvent.type)) {
+                    yield this.runtimeEventToSSE(runtimeEvent, correlationId, taskId);
                 }
-                yield this.runtimeEventToSSE(runtimeEvent, correlationId, taskId);
             }
-            await this.deps.taskService.updateStatus(taskId, 'success', assistantText || undefined);
+            await recordTaskTokenUsages(this.deps.taskService, taskId, nodeTokenUsages);
+            await this.deps.taskService.updateStatus(taskId, 'success', visibleStreamAssistantText(assistantBuckets) || undefined);
             if (sessionId) {
                 await persistTurnTranscript(this.deps.messageService, {
                     sessionId,
@@ -566,7 +567,9 @@ export class AgentRuntime {
                     messages: buildTurnTranscriptFromStreamEvents({
                         pendingToolCalls,
                         toolResults,
-                        assistantText,
+                        assistantTexts: streamAssistantTexts(assistantBuckets),
+                        assistantText: visibleStreamAssistantText(assistantBuckets),
+                        finishPoints: graph.finishPoints,
                         toolCallReasoningContent,
                         assistantReasoningContent,
                     }),
@@ -580,6 +583,7 @@ export class AgentRuntime {
         catch (err) {
             const hitlPaused = unwrapHitlPaused(err);
             if (hitlPaused) {
+                await recordTaskTokenUsages(this.deps.taskService, taskId, nodeTokenUsages);
                 await this.deps.taskService.updateStatus(taskId, 'waiting_hitl', buildHitlWaitingTaskOutput({
                     threadId: hitlPaused.threadId,
                     question: hitlPaused.question,
@@ -600,6 +604,7 @@ export class AgentRuntime {
             }
             const appErr = err instanceof AppError ? err : AppError.fromUnknown(err);
             const failMsg = appErr.exposeMessage ? appErr.message : '系统内部错误';
+            await recordTaskTokenUsages(this.deps.taskService, taskId, nodeTokenUsages);
             await this.deps.taskService.updateStatus(taskId, 'failed', failMsg);
             yield this.toSSE('task.error', correlationId, taskId, {
                 code: appErr.code,
@@ -662,8 +667,14 @@ export class AgentRuntime {
             ? forkedCheckpoint.state.agentSystemPrompt
             : undefined);
         try {
+            const forkState = { ...forkedCheckpoint.state };
+            delete forkState.toolSpanId;
+            delete forkState.hitlToolCallId;
             const result = await this.deps.graphEngine.invoke(graph, {
-                ...forkedCheckpoint.state,
+                messages: Array.isArray(forkState.messages)
+                    ? forkState.messages
+                    : [],
+                ...forkState,
                 agentVersion,
                 agentDir,
                 agentSystemPrompt,
@@ -676,6 +687,19 @@ export class AgentRuntime {
                 traceId,
                 traceCollector: this.deps.traceCollector,
             });
+            if (result.tokenUsage.perNode && result.tokenUsage.perNode.length > 0) {
+                await recordTaskTokenUsages(this.deps.taskService, task.id, result.tokenUsage.perNode);
+            }
+            else if (result.tokenUsage.total > 0) {
+                await recordTaskTokenUsages(this.deps.taskService, task.id, [
+                    {
+                        nodeId: 'graph',
+                        model: 'unknown',
+                        inputTokens: result.tokenUsage.input,
+                        outputTokens: result.tokenUsage.output,
+                    },
+                ]);
+            }
             await this.deps.taskService.updateStatus(task.id, 'success', result.output);
             if (this.deps.recordForkRelation) {
                 try {
@@ -707,6 +731,20 @@ export class AgentRuntime {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : 'Unknown error';
+            const sessionId = typeof forkedCheckpoint.state.sessionId === 'string'
+                ? forkedCheckpoint.state.sessionId
+                : undefined;
+            const threadId = resolveCheckpointThreadId({
+                sessionId,
+                taskId: task.id,
+            });
+            const ck = await this.deps.checkpointSaver.load(threadId);
+            const baseline = tokenUsagesFromLlmChannel(forkedCheckpoint.state);
+            const latest = tokenUsagesFromLlmChannel(ck?.state ?? forkedCheckpoint.state);
+            const usages = latest.length >= baseline.length ? latest.slice(baseline.length) : latest;
+            await recordTaskTokenUsages(this.deps.taskService, task.id, usages);
+            const input_tokens = usages.reduce((sum, row) => sum + row.inputTokens, 0);
+            const output_tokens = usages.reduce((sum, row) => sum + row.outputTokens, 0);
             await this.deps.taskService.updateStatus(task.id, 'failed', message);
             return {
                 newTraceId: traceId,
@@ -715,7 +753,11 @@ export class AgentRuntime {
                 checkpointId,
                 status: 'failed',
                 output: message,
-                tokenUsage: { input_tokens: 0, output_tokens: 0, total_tokens: 0 },
+                tokenUsage: {
+                    input_tokens,
+                    output_tokens,
+                    total_tokens: input_tokens + output_tokens,
+                },
             };
         }
     }

package/dist/runtime/dev-rag-deps.d.ts

@@ -0,0 +1,21 @@
+/**
+ * dev 装配的 rag 依赖 — createDevRuntime 检测显式配置后自动注入
+ *
+ * 启用条件：EAP_EMBED_API_KEY 存在（缺省不注入，行为与无 rag 的 master 一致）。
+ * retriever 惰性初始化：vector-engine（better-sqlite3+sqlite-vec，native 依赖）
+ * 只在首次检索时动态 import——装配期零 native 加载，服务端部署不受影响。
+ * import 目标可用 EAP_VECTOR_ENGINE_PATH 指定绝对路径（默认解析 @eap/vector-engine；
+ * eap-cli 发版链等无该包的环境走绝对路径注入）。
+ *
+ * 环境变量（与 .local 演示脚本同一套）：
+ * - EAP_EMBED_API_KEY / EAP_EMBED_BASE_URL / EAP_EMBED_MODEL / EAP_EMBED_DIMS：embedding 网关
+ * - RAG_DB：向量库路径（缺省 ~/.eap/rag/agent.db）
+ */
+import type { IRetriever, RagNodeDeps } from '../graph/nodes/rag/index.js';
+/**
+ * dev rag 装配：EAP_EMBED_API_KEY 显式配置才启用，否则 undefined（不注入）。
+ * llmProvider 复用 dev 装配已构造的实例（与 llm 节点同一体系）。
+ * EAP_RAG_TRACE=1 时接 console 观测 rag.* 事件流（轮次决策/各源检索/降噪/收束），
+ * 供多源融合行为观察；缺省静默。
+ */
+export declare function createDevRagNodeDeps(llmProvider: RagNodeDeps['llmProvider'], loadFn?: () => Promise<IRetriever>): RagNodeDeps | undefined;

package/dist/runtime/dev-rag-deps.js

@@ -0,0 +1,186 @@
+/**
+ * dev 装配的 rag 依赖 — createDevRuntime 检测显式配置后自动注入
+ *
+ * 启用条件：EAP_EMBED_API_KEY 存在（缺省不注入，行为与无 rag 的 master 一致）。
+ * retriever 惰性初始化：vector-engine（better-sqlite3+sqlite-vec，native 依赖）
+ * 只在首次检索时动态 import——装配期零 native 加载，服务端部署不受影响。
+ * import 目标可用 EAP_VECTOR_ENGINE_PATH 指定绝对路径（默认解析 @eap/vector-engine；
+ * eap-cli 发版链等无该包的环境走绝对路径注入）。
+ *
+ * 环境变量（与 .local 演示脚本同一套）：
+ * - EAP_EMBED_API_KEY / EAP_EMBED_BASE_URL / EAP_EMBED_MODEL / EAP_EMBED_DIMS：embedding 网关
+ * - RAG_DB：向量库路径（缺省 ~/.eap/rag/agent.db）
+ */
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, watchFile } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { appendFileSync } from 'node:fs';
+// 惰性读 env：模块顶层读不到（runtime 经 sdk import 链早于 CLI 灌 .env.local 执行）
+const trace = (line) => {
+    console.log(line);
+    const f = process.env.EAP_RAG_TRACE_FILE;
+    if (f)
+        appendFileSync(f, line + '\n', 'utf-8');
+};
+/** 入库日志环形缓冲（globalThis 桥接：Playground 服务同进程读，GET /api/rag-ingest-log） */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const ingestLogBuf = (globalThis.__ragIngestLog ??= []);
+const ingestLog = (line) => {
+    const ts = new Date().toISOString().slice(11, 19);
+    ingestLogBuf.push(`[${ts}] ${line}`);
+    if (ingestLogBuf.length > 200)
+        ingestLogBuf.splice(0, ingestLogBuf.length - 200);
+};
+import { HttpEmbedder, LocalSqliteRetriever } from '../graph/nodes/rag/index.js';
+/** 惰性 IRetriever：首次调用才加载真实现；加载失败不缓存，允许下轮重试 */
+class LazyLocalRetriever {
+    load;
+    sourceId = 'local';
+    implPromise;
+    constructor(load) {
+        this.load = load;
+    }
+    ensure() {
+        this.implPromise ??= this.load().catch((err) => {
+            this.implPromise = undefined; // 失败不缓存，下次调用重试加载
+            throw err;
+        });
+        return this.implPromise;
+    }
+    async retrieve(query, opts) {
+        return (await this.ensure()).retrieve(query, opts);
+    }
+    async retrieveByKeyword(query, opts) {
+        const impl = await this.ensure();
+        if (!impl.retrieveByKeyword)
+            return [];
+        return impl.retrieveByKeyword(query, opts);
+    }
+}
+/** 默认加载器：HttpEmbedder + vector-engine + LocalSqliteRetriever（单库：RAG_DB） */
+async function loadLocalRetriever() {
+    const dims = Number(process.env.EAP_EMBED_DIMS ?? 1024);
+    const embedder = new HttpEmbedder({
+        baseUrl: String(process.env.EAP_EMBED_BASE_URL ?? 'https://gtaiapi.gtcloud.cn'),
+        model: String(process.env.EAP_EMBED_MODEL ?? 'Qwen3-Embedding-8B'),
+        apiKey: String(process.env.EAP_EMBED_API_KEY ?? ''),
+        dims,
+        dimensions: dims,
+    });
+    const moduleName = process.env.EAP_VECTOR_ENGINE_PATH ?? '@eap/vector-engine';
+    // Windows 绝对路径须转 file:// URL（盘符字母否则被解析为 URL scheme）
+    const spec = /^[a-zA-Z]:[\\/]/.test(moduleName) ? pathToFileURL(moduleName).href : moduleName;
+    const mod = (await import(spec));
+    const dbPath = process.env.RAG_DB ?? join(homedir(), '.eap', 'rag', 'agent.db');
+    mkdirSync(dirname(dbPath), { recursive: true });
+    const engine = await mod.createAsyncEngine({ dbPath, dims });
+    // 自动向量化：EAP_RAG_AUTO_INGEST=1 时常驻调度器扫授权目录，文件放入即入库
+    // （写入侧归宿主/桌面语义；dev 演示用轮询，生产为授权事件触发）。
+    // RAG_DOCS_DIR 支持 `;` 分隔多目录——"授权一个新文件夹" = 追加一个路径。
+    //
+    // 授权清单热更新（客户端授权动作的 dev 模拟）：RAG_AUTHORIZED_DIRS_FILE（json
+    // {"dirs":[...]}，缺省 <库目录>/authorized-dirs.json）存在则覆盖 RAG_DOCS_DIR，
+    // 文件变更 → scheduler.updateDirs 即时生效（新目录入库/移除软删），全程不重启。
+    if (process.env.EAP_RAG_AUTO_INGEST) {
+        const envDirs = (process.env.RAG_DOCS_DIR ?? join(dirname(dbPath), 'docs'))
+            .split(';')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        const authFile = process.env.RAG_AUTHORIZED_DIRS_FILE ?? join(dirname(dbPath), 'authorized-dirs.json');
+        const readAuthDirs = () => {
+            try {
+                const parsed = JSON.parse(readFileSync(authFile, 'utf-8'));
+                if (Array.isArray(parsed.dirs) && parsed.dirs.every((d) => typeof d === 'string')) {
+                    const dirs = parsed.dirs.map((d) => d.trim()).filter(Boolean);
+                    return dirs.length ? dirs : undefined; // 空清单视为无效，防误清库
+                }
+            }
+            catch {
+                // 文件不存在/解析失败：保持现清单
+            }
+            return undefined;
+        };
+        let currentDirs = readAuthDirs() ?? envDirs;
+        const scheduler = new mod.IngestScheduler({
+            engine,
+            embedder,
+            userId: process.env.RAG_USER ?? 'anonymous',
+            dirs: currentDirs,
+            intervalMs: Number(process.env.EAP_RAG_SCAN_INTERVAL_MS ?? 30_000),
+            watch: process.env.EAP_RAG_SCAN_MODE !== 'interval',
+            onEvent: (e) => {
+                if (e.type === 'file.ingested') {
+                    const line = `[rag-ingest] 📥 ${String(e['filePath']).split('\\').pop()} → ${e['chunks']} 片`;
+                    console.log(line);
+                    ingestLog(line);
+                }
+                else if (e.type === 'file.failed') {
+                    const line = `[rag-ingest] ✗ ${String(e['filePath']).split('\\').pop()}: ${e['error']}`;
+                    console.log(line);
+                    ingestLog(line);
+                }
+            },
+        });
+        scheduler.start();
+        ingestLog(`🚀 自动向量化已启动：${currentDirs.length} 个授权目录`);
+        console.log(`[rag-ingest] 自动向量化已启动：目录 ${currentDirs.join('; ')}（${Number(process.env.EAP_RAG_SCAN_INTERVAL_MS ?? 30_000) / 1000}s 轮询${existsSync(authFile) ? `，授权清单 ${authFile} 热更新` : ''}）`);
+        // 授权清单文件变更 → updateDirs（编辑器保存/前端写入均触发；stat 轮询最稳）
+        watchFile(authFile, { interval: 2000 }, () => {
+            const next = readAuthDirs();
+            if (next && next.join(';') !== currentDirs.join(';')) {
+                currentDirs = next;
+                scheduler.updateDirs(next);
+                const line = `[rag-ingest] 🔑 授权目录更新（免重启生效）：${next.length} 个目录`;
+                console.log(line + `（${next.join('; ')}）`);
+                ingestLog(line);
+            }
+        });
+    }
+    return new LocalSqliteRetriever({ engine, embedder });
+}
+/**
+ * dev rag 装配：EAP_EMBED_API_KEY 显式配置才启用，否则 undefined（不注入）。
+ * llmProvider 复用 dev 装配已构造的实例（与 llm 节点同一体系）。
+ * EAP_RAG_TRACE=1 时接 console 观测 rag.* 事件流（轮次决策/各源检索/降噪/收束），
+ * 供多源融合行为观察；缺省静默。
+ */
+export function createDevRagNodeDeps(llmProvider, loadFn = loadLocalRetriever) {
+    if (!process.env.EAP_EMBED_API_KEY)
+        return undefined;
+    const fmt = (v, n = 40) => String(v ?? '').replace(/\s+/g, ' ').slice(0, n);
+    const emitEvent = process.env.EAP_RAG_TRACE
+        ? (type, p) => {
+            if (type === 'rag.round') {
+                const calls = (p['toolCalls'] ?? [])
+                    .map((t) => `${t.name}(${JSON.stringify(t.arguments)})`).join('  ');
+                trace(`[rag] 第${p['round']}轮: ${calls}`);
+            }
+            else if (type === 'rag.search') {
+                const head = p['kind'] === 'kb' ? `kb:${p['toolName']}` : `local:"${fmt(p['query'], 20)}"`;
+                trace(`[rag]   search ${head} topK=${p['topK']} → hits=${p['hits']} ${p['durationMs']}ms${p['success'] ? '' : ` ✗${p['error']}`}${p['scope'] ? ` scope=${p['scope']}` : ''}`);
+            }
+            else if (type === 'rag.denoise') {
+                trace(`[rag]   降噪 候选${p['candidates']} → 保留${p['kept']}`);
+                for (const f of p['filtered'] ?? [])
+                    trace(`[rag]     滤 ${fmt(f.rawId, 30)}（${fmt(f.reason, 30)}）`);
+            }
+            else if (type === 'rag.rewrite') {
+                trace(`[rag]   空结果重写 "${fmt(p['from'], 20)}" → "${fmt(p['to'], 20)}"`);
+            }
+            else if (type === 'rag.finish') {
+                trace(`[rag] 收束: ${p['rounds']}轮 最终${p['docs']}条${p['empty'] ? '（空）' : ''}`);
+            }
+        }
+        : undefined;
+    // 预热：自动向量化开启时立即后台装配一次——调度器/授权热更新/入库日志不等到首次
+    // local_search 才启动（演示"先授权后提问"场景需要授权即生效）。失败静默，检索时重试。
+    if (process.env.EAP_RAG_AUTO_INGEST) {
+        void Promise.resolve(loadFn()).catch(() => undefined);
+    }
+    return {
+        llmProvider,
+        retrievers: [new LazyLocalRetriever(loadFn)],
+        emitEvent,
+    };
+}