@gt-fe/eap-runtime 0.0.20 → 0.0.22

package/dist/graph/nodes/tool-node.d.ts

@@ -9,11 +9,13 @@
  * @see design.md §1.4 ToolNode: LangGraph的ToolNode封装
  * @see requirements.md Requirement 8 AC1, AC3, AC5
  */
+import type { NodeRetryConfig } from '../contracts/executable-graph.js';
 import type { AuthContext } from '../../tool/tool-executor.interface.js';
 import type { ToolOrchestrator } from '../../tool/tool-orchestrator.js';
 import type { ToolResultInjector } from '../../tool/tool-result-injector.js';
 import type { SkillDirRef } from '../adapters/skill-read.js';
 import type { HitlHandler } from '../hitl/hitl-handler.js';
+import { type ExecutionInterceptors } from '../../execution/interceptors.js';
 /**
  * LangGraphState — LangGraph 内部状态（与 LLMNode 对齐）
  */
@@ -49,6 +51,8 @@ export interface ToolNodeProgress {
     skillVersion?: string;
     skillName?: string;
     toolVersion?: string;
+    /** 本失败后是否还会再试。缺省 false */
+    willRetry?: boolean;
 }
 export declare class ToolNode {
     private readonly orchestrator;
@@ -57,7 +61,20 @@ export declare class ToolNode {
     private readonly onProgress?;
     private readonly hitlHandler?;
     private readonly nodeId?;
-    constructor(orchestrator: ToolOrchestrator, injector: ToolResultInjector, defaultAuthContext: AuthContext, onProgress?: ((data: ToolNodeProgress) => void) | undefined, hitlHandler?: HitlHandler | undefined, nodeId?: string | undefined);
+    private readonly interceptors?;
+    /** 图声明的 rag 检索面（config.retrievalSources，工具形态声明位）——随请求转递给 rag_search 装饰器 */
+    private readonly ragSourcesConfig?;
+    /** 图声明的融合总条数（config.totalK，工具形态声明位）——同路转递 */
+    private readonly ragTotalK?;
+    /** 节点 `retry`；未设则只试一次 */
+    private readonly retry?;
+    constructor(orchestrator: ToolOrchestrator, injector: ToolResultInjector, defaultAuthContext: AuthContext, onProgress?: ((data: ToolNodeProgress) => void) | undefined, hitlHandler?: HitlHandler | undefined, nodeId?: string | undefined, interceptors?: ExecutionInterceptors | undefined, 
+    /** 图声明的 rag 检索面（config.retrievalSources，工具形态声明位）——随请求转递给 rag_search 装饰器 */
+    ragSourcesConfig?: import("../nodes/rag/types.js").RagRetrievalSources | undefined, 
+    /** 图声明的融合总条数（config.totalK，工具形态声明位）——同路转递 */
+    ragTotalK?: number | undefined, 
+    /** 节点 `retry`；未设则只试一次 */
+    retry?: NodeRetryConfig | undefined);
     /**
      * execute — StateGraph 节点函数
      *
@@ -71,6 +88,7 @@ export declare class ToolNode {
      * 从 state 中提取 messages 数组
      */
     private extractMessages;
+    private executeSingleWithRetry;
     /**
      * 从 messages 中找到最后一条 assistant 消息
      */

package/dist/graph/nodes/tool-node.js

@@ -9,6 +9,7 @@
  * @see design.md §1.4 ToolNode: LangGraph的ToolNode封装
  * @see requirements.md Requirement 8 AC1, AC3, AC5
  */
+import { AppError, ErrorCodes } from '@gt-fe/eap-contracts';
 import { resolveJailFromState } from '../../tool/harness-primitives.js';
 import { recordSkillEntrySpan, skillEntryInvocationFromTool, skillTraceIdentity } from '../adapters/skill-entry-span.js';
 import { inferHarnessSkillDir } from '../../tool/skill-dir-infer.js';
@@ -17,6 +18,10 @@ import { ToolConfirmationInterceptor } from '../../tool/tool-confirmation.js';
 import { resolveCheckpointThreadId } from '../../session/persist-turn-messages.js';
 import { toolTraceIdentity } from '../../tool/mcp-list.js';
 import { resolveExecutionTrace, warnTraceSpanFailure, } from '../execution-trace-context.js';
+import { emitRuntimeLog } from '../../common/logger.js';
+import { decideBeforeTool, } from '../../execution/interceptors.js';
+import { isRetryableToolFailure, resolveToolRetryConfig, sleepToolRetry, toolRetryDelayMs, } from '../../tool/tool-retry.js';
+import { isIsolatedSkillState } from '../adapters/skill-isolate.js';
 function skillDirsFromState(state) {
     const defs = state['skillDefinitions'];
     return Object.values(defs ?? {})
@@ -30,13 +35,27 @@ export class ToolNode {
     onProgress;
     hitlHandler;
     nodeId;
-    constructor(orchestrator, injector, defaultAuthContext, onProgress, hitlHandler, nodeId) {
+    interceptors;
+    ragSourcesConfig;
+    ragTotalK;
+    retry;
+    constructor(orchestrator, injector, defaultAuthContext, onProgress, hitlHandler, nodeId, interceptors, 
+    /** 图声明的 rag 检索面（config.retrievalSources，工具形态声明位）——随请求转递给 rag_search 装饰器 */
+    ragSourcesConfig, 
+    /** 图声明的融合总条数（config.totalK，工具形态声明位）——同路转递 */
+    ragTotalK, 
+    /** 节点 `retry`；未设则只试一次 */
+    retry) {
         this.orchestrator = orchestrator;
         this.injector = injector;
         this.defaultAuthContext = defaultAuthContext;
         this.onProgress = onProgress;
         this.hitlHandler = hitlHandler;
         this.nodeId = nodeId;
+        this.interceptors = interceptors;
+        this.ragSourcesConfig = ragSourcesConfig;
+        this.ragTotalK = ragTotalK;
+        this.retry = retry;
     }
     /**
      * execute — StateGraph 节点函数
@@ -100,6 +119,12 @@ export class ToolNode {
                 ...(jail.workdir ? { jailWorkdir: jail.workdir } : {}),
                 ...(jailExtraRoots.length > 0 ? { jailExtraRoots } : {}),
                 ...(skillDir ? { skillDir } : {}),
+                // rag 会话级控制与工具表快照（rag_search 装饰器消费；普通工具执行器忽略）
+                ...(state['ragSources'] ? { ragSources: state['ragSources'] } : {}),
+                ...(state['ragScope'] ? { ragScope: state['ragScope'] } : {}),
+                ...(this.ragSourcesConfig ? { ragSourcesConfig: this.ragSourcesConfig } : {}),
+                ...(this.ragTotalK !== undefined ? { ragTotalK: this.ragTotalK } : {}),
+                ...(loadedTools ? { loadedTools } : {}),
             };
         });
         const executionContext = state['executionContext'];
@@ -120,8 +145,31 @@ export class ToolNode {
                 ...(inSkillSubgraph ? { inSkillSubgraph: true } : {}),
             });
         };
+        // require_confirmation 工具走 HITL 拦截：改为顺序执行，thread_id 与 Checkpoint 对齐
+        const confirmationTools = new Set(Object.entries(loadedTools ?? {})
+            .filter(([, def]) => Boolean(def?.manifest.requireConfirmation))
+            .map(([name]) => name));
+        const needsHitl = Boolean(this.hitlHandler) &&
+            (requests.some((req) => confirmationTools.has(req.toolName)) ||
+                Boolean(this.interceptors?.beforeTool));
+        const resumingHitl = isHitlDecision(state['hitlChoice']);
+        const resumeToolSpanId = resumingHitl && typeof state['toolSpanId'] === 'string' && state['toolSpanId']
+            ? state['toolSpanId']
+            : undefined;
+        const resumeToolCallId = typeof state['hitlToolCallId'] === 'string' && state['hitlToolCallId']
+            ? state['hitlToolCallId']
+            : undefined;
+        const confirmationCount = requests.filter((req) => confirmationTools.has(req.toolName)).length;
         // 5. 并行执行所有 Tool 调用（附 Trace span）
         const spanIds = await Promise.all(requests.map(async (req) => {
+            const reusePausedSpan = Boolean(resumeToolSpanId) &&
+                ((resumeToolCallId && req.toolCallId === resumeToolCallId) ||
+                    (!resumeToolCallId &&
+                        confirmationTools.has(req.toolName) &&
+                        confirmationCount === 1));
+            if (reusePausedSpan) {
+                return resumeToolSpanId ?? null;
+            }
             if (!traceCollector || !traceId)
                 return null;
             try {
@@ -153,17 +201,9 @@ export class ToolNode {
                 return null;
             }
         }));
-        // 并行执行，但各自独立计时（避免共用 startedAt 导致时长不准/看起来像“写死”）
-        // require_confirmation 工具走 HITL 拦截：改为顺序执行，thread_id 与 Checkpoint 对齐
-        const confirmationTools = new Set(Object.entries(loadedTools ?? {})
-            .filter(([, def]) => Boolean(def?.manifest.requireConfirmation))
-            .map(([name]) => name));
-        const needsHitl = Boolean(this.hitlHandler) &&
-            requests.some((req) => confirmationTools.has(req.toolName));
         const runOne = async (req, i) => {
             const toolIdentity = toolTraceIdentity(loadedTools?.[req.toolName], req.toolName);
             const toolset = toolIdentity.toolset;
-            const resumingHitl = isHitlDecision(state['hitlChoice']);
             if (!resumingHitl) {
                 emitProgress({
                     toolCallId: req.toolCallId,
@@ -177,32 +217,69 @@ export class ToolNode {
             const startedAt = Date.now();
             try {
                 let result;
-                if (needsHitl && this.hitlHandler && confirmationTools.has(req.toolName)) {
-                    const interceptor = new ToolConfirmationInterceptor(confirmationTools, this.hitlHandler, {
-                        execute: (r) => this.orchestrator.executeSingle(r, executionContext),
-                    });
-                    const graphState = this.toGraphState(state);
-                    const threadId = resolveCheckpointThreadId({
-                        sessionId: typeof state['sessionId'] === 'string' ? state['sessionId'] : undefined,
-                        taskId: req.taskId,
-                    });
-                    const confirmed = await interceptor.executeWithConfirmation(req, graphState, req.taskId ?? String(state['taskId'] ?? req.toolCallId), threadId, {
-                        toolSpanId: spanIds[i] ?? undefined,
-                        skillSpanId: typeof state['skillSpanId'] === 'string' ? state['skillSpanId'] : undefined,
-                    });
-                    result =
-                        confirmed ??
-                            {
-                                toolCallId: req.toolCallId,
-                                toolName: req.toolName,
-                                content: `用户拒绝执行工具 ${req.toolName}`,
-                                success: false,
-                                error: `用户拒绝执行工具 ${req.toolName}`,
-                                errorCode: 'hitl_rejected',
-                            };
+                const gate = await decideBeforeTool(this.interceptors?.beforeTool, req, executionContext);
+                if (gate.action === 'deny') {
+                    result = {
+                        toolCallId: req.toolCallId,
+                        toolName: req.toolName,
+                        content: '',
+                        success: false,
+                        error: gate.reason,
+                        errorCode: 'interceptor_denied',
+                    };
                 }
                 else {
-                    result = await this.orchestrator.executeSingle(req, executionContext);
+                    const askHitl = gate.action === 'ask' || (needsHitl && confirmationTools.has(req.toolName));
+                    if (askHitl && this.hitlHandler) {
+                        const confirmSet = new Set(confirmationTools);
+                        if (gate.action === 'ask')
+                            confirmSet.add(req.toolName);
+                        const interceptor = new ToolConfirmationInterceptor(confirmSet, this.hitlHandler, {
+                            execute: (r) => this.orchestrator.executeSingle(r, executionContext),
+                        });
+                        const graphState = this.toGraphState(state);
+                        const threadId = resolveCheckpointThreadId({
+                            sessionId: typeof state['sessionId'] === 'string' ? state['sessionId'] : undefined,
+                            taskId: req.taskId,
+                        });
+                        const confirmed = await interceptor.executeWithConfirmation(req, graphState, req.taskId ?? String(state['taskId'] ?? req.toolCallId), threadId, {
+                            toolSpanId: spanIds[i] ?? undefined,
+                            skillSpanId: typeof state['skillSpanId'] === 'string' ? state['skillSpanId'] : undefined,
+                        });
+                        result =
+                            confirmed ??
+                                {
+                                    toolCallId: req.toolCallId,
+                                    toolName: req.toolName,
+                                    content: `用户拒绝执行工具 ${req.toolName}`,
+                                    success: false,
+                                    error: `用户拒绝执行工具 ${req.toolName}`,
+                                    errorCode: 'hitl_rejected',
+                                };
+                    }
+                    else if (gate.action === 'ask') {
+                        result = {
+                            toolCallId: req.toolCallId,
+                            toolName: req.toolName,
+                            content: '',
+                            success: false,
+                            error: '需要人工确认',
+                            errorCode: 'interceptor_ask',
+                        };
+                    }
+                    else {
+                        result = await this.executeSingleWithRetry(req, executionContext, emitProgress, toolset, toolIdentity);
+                    }
+                }
+                try {
+                    await this.interceptors?.afterTool?.(req, result);
+                }
+                catch (err) {
+                    emitRuntimeLog('warn', 'runtime.intercept', 'afterTool failed', {
+                        event: 'runtime.intercept.after_tool_failed',
+                        toolName: req.toolName,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
                 }
                 const executionTime = Date.now() - startedAt;
                 if (result.success) {
@@ -274,6 +351,23 @@ export class ToolNode {
                             (typeof state['skillSpanId'] === 'string' ? state['skillSpanId'] : undefined);
                     throw hitlPaused;
                 }
+                if (err instanceof AppError &&
+                    err.code === ErrorCodes.GRAPH_EXECUTION_ERROR &&
+                    isIsolatedSkillState(state)) {
+                    const failedSpanId = spanIds[i];
+                    if (traceCollector && failedSpanId) {
+                        try {
+                            await traceCollector.completeNode(failedSpanId, {
+                                status: 'failed',
+                                error: err.message,
+                            });
+                        }
+                        catch (completeErr) {
+                            warnTraceSpanFailure('completeNode', { type: 'tool', name: req.toolName, traceId, spanId: failedSpanId }, completeErr);
+                        }
+                    }
+                    throw err;
+                }
                 const executionTime = Date.now() - startedAt;
                 const message = err instanceof Error ? err.message : String(err);
                 emitProgress({
@@ -362,6 +456,37 @@ export class ToolNode {
             return { role: 'user', content: String(msg) };
         });
     }
+    async executeSingleWithRetry(req, executionContext, emitProgress, toolset, toolIdentity) {
+        const retry = resolveToolRetryConfig(this.retry);
+        const maxRetries = retry?.maxRetries ?? 0;
+        let last;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            last = await this.orchestrator.executeSingle(req, executionContext);
+            if (last.success)
+                return last;
+            const willRetry = attempt < maxRetries && isRetryableToolFailure(last);
+            if (!willRetry)
+                return last;
+            emitProgress({
+                toolCallId: req.toolCallId,
+                toolName: req.toolName,
+                ...(toolset ? { toolset } : {}),
+                ...(toolIdentity.toolVersion ? { toolVersion: toolIdentity.toolVersion } : {}),
+                status: 'error',
+                arguments: req.arguments,
+                error: last.error ?? 'unknown error',
+                willRetry: true,
+            });
+            await sleepToolRetry(toolRetryDelayMs(attempt, retry.backoff));
+        }
+        return last ?? {
+            toolCallId: req.toolCallId,
+            toolName: req.toolName,
+            content: '',
+            success: false,
+            error: 'unknown error',
+        };
+    }
     /**
      * 从 messages 中找到最后一条 assistant 消息
      */

package/dist/index.d.ts

@@ -19,6 +19,8 @@ export type { ITraceCollector, CompleteNodeParams, TraceEvent, TraceSession, Exe
 export type { ExecutionContext, CallerType, GovernancePermissionCheckParams, GovernancePermissionCheckResult, PermissionDenyReason, } from '@gt-fe/eap-contracts';
 export { HttpGovernanceClient, AllowAllGovernanceClient, resolveExecutionContext, assertToolPermission, assertSkillPermission, permissionMessage, PermissionDeniedError, GovernanceUnavailableError, } from './governance/index.js';
 export type { IGovernanceClient } from './governance/index.js';
+export { decideBeforeModel, decideBeforeTool, } from './execution/index.js';
+export type { AfterModelInterceptor, AfterToolInterceptor, BeforeModelInput, BeforeModelInterceptor, BeforeToolInterceptor, ExecutionInterceptors, ModelInterceptorDecision, ToolInterceptorDecision, } from './execution/index.js';
 export { FileLlmTurnLog, InMemoryLlmTurnLog, createFileLlmTurnLogFromEnv, maskApiKey, resolveLlmTurnDir, } from './debug/llm-turn-log.js';
 export { PostgresLlmTurnLog } from './debug/pg-llm-turn-log.js';
 export type { ILlmTurnLog, LlmTurnRecord, LlmTurnIndexEntry, LlmTurnContext, LlmTurnLogKind, } from './debug/llm-turn-log.js';

package/dist/index.js

@@ -30,5 +30,6 @@ export * from './registry/index.js';
 // LLM Providers
 export * from './providers/index.js';
 export { HttpGovernanceClient, AllowAllGovernanceClient, resolveExecutionContext, assertToolPermission, assertSkillPermission, permissionMessage, PermissionDeniedError, GovernanceUnavailableError, } from './governance/index.js';
+export { decideBeforeModel, decideBeforeTool, } from './execution/index.js';
 export { FileLlmTurnLog, InMemoryLlmTurnLog, createFileLlmTurnLogFromEnv, maskApiKey, resolveLlmTurnDir, } from './debug/llm-turn-log.js';
 export { PostgresLlmTurnLog } from './debug/pg-llm-turn-log.js';

package/dist/memory/semantic-retrieval.service.d.ts

@@ -98,7 +98,7 @@ export type EmbeddingFunction = (text: string) => Promise<number[]>;
 export declare class SemanticRetrievalService {
     private readonly config;
     private readonly vectorStore?;
-    private readonly embedding;
+    private readonly embedding?;
     constructor(config?: Partial<RetrievalConfig>, vectorStore?: IVectorStore, embedding?: EmbeddingFunction);
     /**
      * 检索相关记忆

package/dist/memory/semantic-retrieval.service.js

@@ -20,21 +20,6 @@ export const DEFAULT_RETRIEVAL_CONFIG = {
     keywordWeight: 0.3,
     vectorWeight: 0.7,
 };
-/**
- * 默认 Embedding 函数（占位）
- *
- * 实际使用时应注入真实的 Embedding 函数（如 OpenAI Embedding）。
- */
-async function defaultEmbedding(text) {
-    // 简单的哈希向量（占位，实际应使用真实的 Embedding 模型）
-    const vector = new Array(128).fill(0);
-    for (let i = 0; i < text.length; i++) {
-        vector[i % 128] += text.charCodeAt(i) / 1000;
-    }
-    // 归一化
-    const norm = Math.sqrt(vector.reduce((sum, v) => sum + v * v, 0));
-    return vector.map((v) => v / norm);
-}
 // ─────────────────────────────────────────────
 // 语义检索服务
 // ─────────────────────────────────────────────
@@ -48,7 +33,7 @@ export class SemanticRetrievalService {
     constructor(config, vectorStore, embedding) {
         this.config = { ...DEFAULT_RETRIEVAL_CONFIG, ...config };
         this.vectorStore = vectorStore;
-        this.embedding = embedding ?? defaultEmbedding;
+        this.embedding = embedding;
     }
     /**
      * 检索相关记忆
@@ -106,11 +91,9 @@ export class SemanticRetrievalService {
      * 基于向量相似度的检索。
      */
     async vectorRetrieve(query, memories) {
-        if (!this.vectorStore) {
-            // 如果没有向量存储，回退到关键词检索
+        if (!this.vectorStore || !this.embedding) {
             return this.keywordRetrieve(query, memories);
         }
-        // 生成查询向量
         const queryVector = await this.embedding(query);
         // 查询相似向量
         const vectorResults = await this.vectorStore.query(queryVector, this.config.limit, this.config.similarityThreshold);
@@ -183,12 +166,19 @@ export class SemanticRetrievalService {
             'under', 'again', 'further', 'then', 'once',
         ]);
         // 分词（简单按空格和标点分割）
-        const words = text
-            .toLowerCase()
-            .replace(/[^\w\u4e00-\u9fff]/g, ' ')
+        const cleaned = text.toLowerCase().replace(/[^\w\u4e00-\u9fff]/g, ' ');
+        const words = cleaned
             .split(/\s+/)
             .filter((word) => word.length > 1 && !stopWords.has(word));
-        return [...new Set(words)];
+        const grams = [];
+        for (const word of words) {
+            if (/[\u4e00-\u9fff]/.test(word) && word.length > 2) {
+                for (let i = 0; i < word.length - 1; i++) {
+                    grams.push(word.slice(i, i + 2));
+                }
+            }
+        }
+        return [...new Set([...words, ...grams])];
     }
 }
 // ─────────────────────────────────────────────

package/dist/providers/index.d.ts

@@ -1,7 +1,7 @@
 export { EchoLLMProvider, createDefaultLLMProvider } from './echo-llm-provider.js';
 export { HttpLLMProvider, DEFAULT_LLM_HTTP_TIMEOUT_MS, type HttpLLMProviderConfig } from './http-llm-provider.js';
-export { RoutingLLMProvider, type RoutingLLMProviderConfig } from './routing-llm-provider.js';
+export { RoutingLLMProvider, type RoutingLLMProviderConfig, assertFoundationModelsInvokeAllowsStream, isFoundationModelsInvokeEnabled, MODELS_INVOKE_STREAM_MESSAGE, } from './routing-llm-provider.js';
 export { resolveLlmModelName, canOverrideGraphModel } from './resolve-llm-model.js';
-export { createLocalLlmProvider, requireLocalLlmConnections, resolveLocalLlmConnection, parseLocalLlmConnectionRefs, hydrateLocalLlmConnections, LLM_CONNECTIONS_ENV, } from './local-llm-provider.js';
+export { createLocalLlmProvider, createOptionalLocalLlmProvider, requireLocalLlmConnections, resolveLocalLlmConnection, parseLocalLlmConnectionRefs, hydrateLocalLlmConnections, hasLocalLlmConnection, LLM_CONNECTIONS_ENV, } from './local-llm-provider.js';
 export type { LocalLlmConnection, LocalLlmConnectionRef, LocalLlmConnectionRefs, LocalLlmConnections, } from './local-llm-provider.js';
 export type { LLMToolDefinition } from '../graph/nodes/llm-node.js';

package/dist/providers/index.js

@@ -1,5 +1,5 @@
 export { EchoLLMProvider, createDefaultLLMProvider } from './echo-llm-provider.js';
 export { HttpLLMProvider, DEFAULT_LLM_HTTP_TIMEOUT_MS } from './http-llm-provider.js';
-export { RoutingLLMProvider } from './routing-llm-provider.js';
+export { RoutingLLMProvider, assertFoundationModelsInvokeAllowsStream, isFoundationModelsInvokeEnabled, MODELS_INVOKE_STREAM_MESSAGE, } from './routing-llm-provider.js';
 export { resolveLlmModelName, canOverrideGraphModel } from './resolve-llm-model.js';
-export { createLocalLlmProvider, requireLocalLlmConnections, resolveLocalLlmConnection, parseLocalLlmConnectionRefs, hydrateLocalLlmConnections, LLM_CONNECTIONS_ENV, } from './local-llm-provider.js';
+export { createLocalLlmProvider, createOptionalLocalLlmProvider, requireLocalLlmConnections, resolveLocalLlmConnection, parseLocalLlmConnectionRefs, hydrateLocalLlmConnections, hasLocalLlmConnection, LLM_CONNECTIONS_ENV, } from './local-llm-provider.js';

package/dist/providers/local-llm-provider.d.ts

@@ -29,6 +29,12 @@ export interface LocalLlmConnections {
 export declare const LLM_CONNECTIONS_ENV = "EAP_LLM_CONNECTIONS";
 export declare function parseLocalLlmConnectionRefs(env?: NodeJS.ProcessEnv): LocalLlmConnectionRefs;
 export declare function hydrateLocalLlmConnections(refs: LocalLlmConnectionRefs, env?: NodeJS.ProcessEnv): LocalLlmConnections;
+export declare function hasLocalLlmConnection(connections: LocalLlmConnections): boolean;
 export declare function requireLocalLlmConnections(env?: NodeJS.ProcessEnv): LocalLlmConnections;
+/**
+ * Routing 的可选 fallback：有可用本地连接才返回 Provider。
+ * 连接表 JSON 损坏仍抛错；解不出密钥则视为没有本地网关。
+ */
+export declare function createOptionalLocalLlmProvider(turnLog?: ILlmTurnLog, env?: NodeJS.ProcessEnv): ILLMProvider | undefined;
 export declare function resolveLocalLlmConnection(connections: LocalLlmConnections, model?: string): LocalLlmConnection;
 export declare function createLocalLlmProvider(connections?: LocalLlmConnections, turnLog?: ILlmTurnLog): ILLMProvider;

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

@@ -63,10 +63,13 @@ export function hydrateLocalLlmConnections(refs, env = process.env) {
     }
     return { default: hydrate(refs.default), byModel };
 }
+export function hasLocalLlmConnection(connections) {
+    return Boolean(connections.default?.apiKey) || Object.keys(connections.byModel ?? {}).length > 0;
+}
 export function requireLocalLlmConnections(env = process.env) {
     const refs = parseLocalLlmConnectionRefs(env);
     const connections = hydrateLocalLlmConnections(refs, env);
-    if (!connections.default && Object.keys(connections.byModel ?? {}).length === 0) {
+    if (!hasLocalLlmConnection(connections)) {
         const wanted = [
             refs.default?.apiKeyEnv,
             ...Object.values(refs.byModel ?? {}).map((ref) => ref.apiKeyEnv),
@@ -75,13 +78,34 @@ export function requireLocalLlmConnections(env = process.env) {
     }
     return connections;
 }
+/**
+ * Routing 的可选 fallback：有可用本地连接才返回 Provider。
+ * 连接表 JSON 损坏仍抛错；解不出密钥则视为没有本地网关。
+ */
+export function createOptionalLocalLlmProvider(turnLog, env = process.env) {
+    const refs = parseLocalLlmConnectionRefs(env);
+    const connections = hydrateLocalLlmConnections(refs, env);
+    if (!hasLocalLlmConnection(connections))
+        return undefined;
+    return createLocalLlmProvider(connections, turnLog);
+}
+function namedLocalModel(model) {
+    const trimmed = model?.trim();
+    if (!trimmed || trimmed.toLowerCase() === 'default')
+        return undefined;
+    return trimmed;
+}
 export function resolveLocalLlmConnection(connections, model) {
-    const named = model ? connections.byModel?.[model] : undefined;
+    const wanted = namedLocalModel(model);
+    const named = wanted ? connections.byModel?.[wanted] : undefined;
     const connection = named ?? connections.default;
     if (!connection?.apiKey) {
-        throw new Error(model
-            ? `No local LLM gateway for model ${model}. Set runtime.llm.models["${model}"] in eap.config.json.`
-            : 'No local LLM gateway. Set runtime.llm in eap.config.json.');
+        const available = Object.keys(connections.byModel ?? {}).sort();
+        const availableHint = available.length > 0 ? ` Available: ${available.join(', ')}.` : '';
+        if (wanted) {
+            throw new Error(`No local LLM gateway for model ${wanted}. Set runtime.llm.models["${wanted}"] in eap.config.json.${availableHint}`);
+        }
+        throw new Error(`No local LLM gateway. Set runtime.llm.models.default or runtime.llm.baseUrl in eap.config.json.${availableHint}`);
     }
     return connection;
 }

package/dist/providers/routing-llm-provider.d.ts

@@ -7,13 +7,17 @@
  * 3. 用返回的连接配置创建 HttpLLMProvider，发送请求
  *
  * 设计原则：
- * - Runtime 不存任何 LLM 凭证，全部从 Foundation 获取
+ * - 生产路径：Foundation `/models/select` 返回连接，本机 HTTP
+ * - select 失败或没有连接：走构造时注入的 fallback（dev 为 LocalLlmProvider / `resolveLocalLlmConnection`）
  * - 支持任意 OpenAI 兼容 API（OpenAI / DeepSeek / 本地 Ollama 等）
- * - 连接配置由 Foundation 统一管理，Runtime 无感知
  */
 import type { GraphMessage } from '../graph/contracts/executable-graph.js';
 import type { ILLMProvider, LLMNodeConfig, LLMResponse, LLMChunk } from '../graph/nodes/llm-node.js';
 import type { ILlmTurnLog } from '../debug/llm-turn-log.js';
+export declare const MODELS_INVOKE_STREAM_MESSAGE = "EAP_RUNTIME_MODELS_INVOKE \u5B9E\u9A8C\u53E3\u53EA\u652F\u6301\u540C\u6B65 invoke\uFF08POST /models/invoke\uFF09\uFF0C\u4E0D\u652F\u6301 stream\u3002\u5173\u6389\u8BE5\u5F00\u5173\uFF0C\u6216\u6539\u8D70 Foundation /models/select + \u672C\u673A HTTP\u3002";
+export declare function isFoundationModelsInvokeEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** `/models/invoke` 无真流式；开了该开关时 RoutingLLMProvider.stream 必须失败。 */
+export declare function assertFoundationModelsInvokeAllowsStream(env?: NodeJS.ProcessEnv): void;
 export interface RoutingLLMProviderConfig {
     foundationUrl: string;
     fallbackProvider?: ILLMProvider;
@@ -28,5 +32,6 @@ export declare class RoutingLLMProvider implements ILLMProvider {
     stream(messages: GraphMessage[], config: LLMNodeConfig): AsyncIterableIterator<LLMChunk>;
     private withCallDefaults;
     private selectModel;
+    private useFoundationInvoke;
     private createProviderForModel;
 }