@gt-fe/eap-runtime 0.0.20 → 0.0.22

package/dist/graph/adapters/langgraph.adapter.js

@@ -9,10 +9,15 @@
  */
 import { StateGraph, START, END, } from '@langchain/langgraph';
 import { resolveCheckpointThreadId } from '../../session/persist-turn-messages.js';
+import { checkpointStorageThreadId } from './langgraph-checkpointer.js';
 import { LangGraphCheckpointer } from './langgraph-checkpointer.js';
 import { SubGraphCompiler } from './subgraph-compiler.js';
+import { assertEmbeddedSubgraphsAreFlat } from './graph-nesting.js';
+import { isSkillContextIsolated } from './skill-isolate.js';
 import { LLMNode } from '../nodes/llm-node.js';
 import { ToolNode } from '../nodes/tool-node.js';
+import { RagNode, RAG_SEARCH_TOOL_NAME, RagSearchToolExecutor } from '../nodes/rag/index.js';
+import { resolveRagSources, appendSourceCatalog } from '../nodes/rag/tools.js';
 import { ToolOrchestrator } from '../../tool/tool-orchestrator.js';
 import { ToolResultInjector } from '../../tool/tool-result-injector.js';
 import { fileArtifactFromToolOutput } from '../../tool/file-artifact.js';
@@ -33,12 +38,31 @@ import { classifySkillRead } from './skill-read.js';
 import { skillEntryInvocationFromTool } from './skill-entry-span.js';
 import { withGraphSpan } from '../trace-span.js';
 import { executionTraceFromState, getExecutionStream, runWithExecutionTrace, } from '../execution-trace-context.js';
+import { isRetryableToolFailure, resolveToolRetryConfig, sleepToolRetry, toolRetryDelayMs, } from '../../tool/tool-retry.js';
 /** 图未写 `config.maxIterations` 时的 recursionLimit。`agent ⇄ tools` 一圈约 2，50 ≈ 24 次工具往返。 */
 export const DEFAULT_GRAPH_RECURSION_LIMIT = 50;
 /**
  * LangGraph `recursionLimit` 计 superstep（每进一个节点 +1），不是 ReAct 圈数。
  * 图上 `config.maxIterations` 优先；缺省 {@link DEFAULT_GRAPH_RECURSION_LIMIT}。
  */
+/** 并行节点各自返回 [id] 时合并进同一路径；末项相同不重复。 */
+export function mergeHistoryPath(current, update) {
+    const path = Array.isArray(current)
+        ? current.filter((id) => typeof id === 'string' && id.trim().length > 0)
+        : [];
+    const add = Array.isArray(update) ? update : [];
+    for (const raw of add) {
+        if (typeof raw !== 'string')
+            continue;
+        const id = raw.trim();
+        if (!id)
+            continue;
+        if (path[path.length - 1] === id)
+            continue;
+        path.push(id);
+    }
+    return path.length > 1000 ? path.slice(path.length - 1000) : path;
+}
 function langGraphRunOptions(dsl, extra) {
     const raw = dsl.config?.maxIterations;
     const recursionLimit = typeof raw === 'number' && Number.isFinite(raw) && raw > 0
@@ -61,6 +85,7 @@ function langGraphRunOptions(dsl, extra) {
  * 3. 提供 Checkpoint 提取与恢复能力
  */
 export class LangGraphAdapter {
+    auditReporter;
     checkpointer;
     subGraphCompiler;
     llmProvider;
@@ -77,17 +102,29 @@ export class LangGraphAdapter {
      */
     governanceClient;
     hitlHandler;
-    constructor(checkpointSaver, llmProvider, toolExecutor, governanceClient, hitlHandler) {
+    ragNodeDeps;
+    interceptors;
+    /** 开发 overlay 根；createDevRuntime 在恢复 process.env 之前钉死 */
+    overlayExtraRoots = [];
+    constructor(checkpointSaver, llmProvider, toolExecutor, governanceClient, hitlHandler, ragNodeDeps, interceptors, auditReporter) {
+        this.auditReporter = auditReporter;
         this.governanceClient = governanceClient;
         this.hitlHandler = hitlHandler;
+        this.ragNodeDeps = ragNodeDeps;
+        this.interceptors = interceptors;
         this.checkpointer = checkpointSaver
             ? new LangGraphCheckpointer(checkpointSaver)
             : undefined;
         this.llmProvider = llmProvider ?? new EchoLLMProvider();
         this.toolExecutor = toolExecutor;
         this.toolOrchestrator = toolExecutor
-            ? new ToolOrchestrator(toolExecutor, governanceClient)
+            ? new ToolOrchestrator(toolExecutor, governanceClient, this.auditReporter)
             : undefined;
+        // rag_search 装饰器注入同款编排器（内层 kb 派发与 tool 节点同一链路；
+        // 装饰器 deps 已显式提供 orchestrator 时不覆盖）
+        if (toolExecutor instanceof RagSearchToolExecutor && this.toolOrchestrator) {
+            toolExecutor.attachToolOrchestrator(this.toolOrchestrator);
+        }
         this.toolResultInjector = new ToolResultInjector();
         this.conditionEvaluator = new ConditionEvaluator();
         this.systemPromptBuilder = new SystemPromptBuilder();
@@ -125,7 +162,7 @@ export class LangGraphAdapter {
             return 'none';
         });
         // 必须在其他依赖初始化后再创建 SubGraphCompiler（它持有 adapter 引用）
-        this.subGraphCompiler = new SubGraphCompiler(this, governanceClient, this.skillAuditRecorder);
+        this.subGraphCompiler = new SubGraphCompiler(this, governanceClient, this.skillAuditRecorder, this.auditReporter);
     }
     /**
      * 注册自定义条件评估函数
@@ -133,6 +170,10 @@ export class LangGraphAdapter {
     registerConditionEvaluator(name, fn) {
         this.conditionEvaluator.register(name, fn);
     }
+    /** SDK 恢复 env 之后仍要把 overlay 算进 LLM jail 根，不能再读 process.env。 */
+    bindOverlayExtraRoots(roots) {
+        this.overlayExtraRoots = (roots ?? []).filter((root) => root.trim());
+    }
     /**
      * 节点旁路推送 RuntimeEvent（子图 Skill 生命周期、Tool 执行）。
      * 无本次执行流式袋时为空操作（纯 invoke）。
@@ -290,7 +331,7 @@ export class LangGraphAdapter {
                     toolName: progress.toolName,
                     ...(progress.toolset ? { toolset: progress.toolset } : {}),
                     error: progress.error ?? 'Unknown error',
-                    willRetry: false,
+                    willRetry: progress.willRetry === true,
                     ...loc,
                 },
             });
@@ -312,6 +353,7 @@ export class LangGraphAdapter {
      */
     async buildGraph(dsl) {
         this.assertShouldContinueTargetsTool(dsl);
+        assertEmbeddedSubgraphsAreFlat(dsl);
         const silentNodeIds = new Set(dsl.nodes
             .filter((node) => node.type === 'llm' && node.config?.['silent'] === true)
             .map((node) => node.id));
@@ -342,6 +384,10 @@ export class LangGraphAdapter {
                     value: (_current, update) => update,
                     default: () => '',
                 },
+                historyPath: {
+                    value: (current, update) => mergeHistoryPath(current, update),
+                    default: () => [],
+                },
                 // ── 运行期上下文（ephemeral）：由 invoke/stream 入口注入，节点只读 ──
                 userId: ephemeral(''),
                 // agentId 已废弃：channel 保留仅为旧 Checkpoint 反序列化兼容，新代码只写 agentCode
@@ -352,6 +398,8 @@ export class LangGraphAdapter {
                 correlationId: ephemeral(''),
                 taskId: ephemeral(''),
                 sessionId: ephemeral(''),
+                checkpointNs: ephemeral(undefined),
+                skillIsolateContext: ephemeral(undefined),
                 loadedTools: ephemeral(undefined),
                 loadedSkills: ephemeral(undefined),
                 skillDefinitions: ephemeral(undefined),
@@ -364,9 +412,15 @@ export class LangGraphAdapter {
                 agentDir: ephemeral(undefined),
                 executionContext: ephemeral(undefined),
                 forceToolServer: ephemeral(undefined),
+                // 请求级检索范围（前端圈定 fileIds/dirPaths；rag 节点读取，仅本地检索源生效）
+                ragScope: ephemeral(undefined),
+                // 会话级数据源勾选（数据源 id 列表，undefined=全部启用；rag 节点读取）
+                ragSources: ephemeral(undefined),
                 traceCollector: ephemeral(undefined),
                 traceId: ephemeral(undefined),
                 skillSpanId: ephemeral(undefined),
+                toolSpanId: ephemeral(undefined),
+                hitlToolCallId: ephemeral(undefined),
                 lastSpanId: ephemeral(undefined),
                 hitlChoice: ephemeral(undefined),
                 // ── LLM Token 使用量：数组累加器 reducer，每次 LLM 节点追加一条使用明细
@@ -378,7 +432,6 @@ export class LangGraphAdapter {
                     },
                     default: () => [],
                 },
-                __parallelResults: ephemeral(undefined),
                 __codeResult: ephemeral(undefined),
                 __codeError: ephemeral(undefined),
                 __conditionResult: ephemeral(undefined),
@@ -450,7 +503,7 @@ export class LangGraphAdapter {
      */
     async *stream(graph, state) {
         const ref = this.getCompiledRef(graph);
-        const input = this.graphStateToLangGraphInput(state);
+        const input = this.graphStateToLangGraphInput(this.applyDeclaredSearchFace(state, ref.dsl));
         const queue = [];
         const waiter = { fn: null };
         let finished = false;
@@ -482,13 +535,7 @@ export class LangGraphAdapter {
         const producer = runWithExecutionTrace({ ...traceCtx, stream: streamBag }, () => (async () => {
             try {
                 const streamIterator = await ref.compiled.stream(input, langGraphRunOptions(ref.dsl, {
-                    configurable: {
-                        thread_id: resolveCheckpointThreadId({
-                            sessionId: typeof state.sessionId === 'string' ? state.sessionId : undefined,
-                            taskId: state.taskId,
-                            graphId: graph.id,
-                        }),
-                    },
+                    configurable: this.checkpointConfigurable(state, graph),
                     streamMode: 'updates',
                 }));
                 for await (const update of streamIterator) {
@@ -523,18 +570,12 @@ export class LangGraphAdapter {
      */
     async invoke(graph, state) {
         const ref = this.getCompiledRef(graph);
-        const input = this.graphStateToLangGraphInput(state);
+        const input = this.graphStateToLangGraphInput(this.applyDeclaredSearchFace(state, ref.dsl));
         const startTime = Date.now();
         const traceCtx = executionTraceFromState(state);
         // 只补 collector/traceId。子图套娃时外层 stream 袋经 ?? 保留。
         const result = await runWithExecutionTrace(traceCtx, () => ref.compiled.invoke(input, langGraphRunOptions(ref.dsl, {
-            configurable: {
-                thread_id: resolveCheckpointThreadId({
-                    sessionId: typeof state.sessionId === 'string' ? state.sessionId : undefined,
-                    taskId: state.taskId,
-                    graphId: graph.id,
-                }),
-            },
+            configurable: this.checkpointConfigurable(state, graph),
         })));
         const duration = Date.now() - startTime;
         const messages = Array.isArray(result['messages']) ? result['messages'] : [];
@@ -627,10 +668,35 @@ export class LangGraphAdapter {
     // ─────────────────────────────────────────────
     // Private helpers
     // ─────────────────────────────────────────────
+    checkpointConfigurable(state, graph) {
+        const thread_id = resolveCheckpointThreadId({
+            sessionId: typeof state.sessionId === 'string' ? state.sessionId : undefined,
+            taskId: state.taskId,
+            graphId: graph.id,
+        });
+        const ns = typeof state.checkpointNs === 'string' ? state.checkpointNs.trim() : '';
+        // 子图是独立 compile 再 invoke，LangGraph put 不一定带回 checkpoint_ns；槽位编进 thread_id。
+        return { thread_id: checkpointStorageThreadId(thread_id, ns) };
+    }
     /**
      * 根据节点类型创建对应的执行函数
      */
     createNodeFunction(node) {
+        const impl = this.createNodeFunctionBody(node);
+        return async (state) => {
+            const update = await impl(state);
+            const patch = update && typeof update === 'object' ? { ...update } : {};
+            const currentNode = typeof patch['currentNode'] === 'string' && String(patch['currentNode']).trim()
+                ? String(patch['currentNode']).trim()
+                : node.id;
+            if (!Array.isArray(patch['historyPath'])) {
+                patch['historyPath'] = [currentNode];
+            }
+            patch['currentNode'] = currentNode;
+            return patch;
+        };
+    }
+    createNodeFunctionBody(node) {
         switch (node.type) {
             case 'llm':
                 return this.createLLMNodeFunction(node);
@@ -651,23 +717,26 @@ export class LangGraphAdapter {
             case 'subgraph':
                 return this.createSubGraphNodeFunction(node);
             case 'human':
-                return async (state) => {
-                    return { currentNode: node.id };
-                };
-            case 'parallel':
-                return this.createParallelNodeFunction(node);
+                throw new AppError(ErrorCodes.GRAPH_BUILD_FAILED, `Graph 节点 "${node.id}" type=human 未实现；人工确认请用 require_confirmation`, { exposeMessage: true });
             case 'code':
                 if (node.config?.['bindSkill'] === true) {
                     return this.createSkillBindNodeFunction(node);
                 }
                 return this.createCodeNodeFunction(node);
-            default:
+            case 'rag':
+                return this.createRagNodeFunction(node);
+            default: {
                 if (node.config?.['bindSkill'] === true) {
                     return this.createSkillBindNodeFunction(node);
                 }
-                return async (state) => {
-                    return { ...state, currentNode: node.id };
-                };
+                const type = String(node.type);
+                if (type === 'start' || type === 'end') {
+                    return async (state) => {
+                        return { ...state, currentNode: node.id };
+                    };
+                }
+                throw new AppError(ErrorCodes.GRAPH_BUILD_FAILED, `Graph 节点 "${node.id}" type=${type} 不是合法类型`, { exposeMessage: true });
+            }
         }
     }
     createSkillBindNodeFunction(node) {
@@ -744,7 +813,7 @@ export class LangGraphAdapter {
                 userId: 'system',
                 delegationToken: '',
                 agentCode: '',
-            }, (progress) => this.emitToolExecutionEvents(progress), this.hitlHandler, node.id);
+            }, (progress) => this.emitToolExecutionEvents(progress), this.hitlHandler, node.id, this.interceptors, node.config?.['retrievalSources'], node.config?.['totalK'], node.retry);
             return (state) => toolNode.execute(state);
         }
         if (this.toolExecutor) {
@@ -767,7 +836,7 @@ export class LangGraphAdapter {
                 const jailExtraRoots = Object.values(skillDefs ?? {})
                     .map((skill) => skill.bundlePath)
                     .filter((p) => Boolean(p));
-                const result = await this.toolExecutor.execute({
+                const request = {
                     toolCallId,
                     toolName,
                     arguments: defaultArgs,
@@ -775,7 +844,25 @@ export class LangGraphAdapter {
                     correlationId,
                     taskId,
                     ...(jailExtraRoots.length > 0 ? { jailExtraRoots } : {}),
-                });
+                };
+                const retry = resolveToolRetryConfig(node.retry);
+                const maxRetries = retry?.maxRetries ?? 0;
+                let result = await this.toolExecutor.execute(request);
+                for (let attempt = 0; !result.success && attempt < maxRetries; attempt++) {
+                    if (!isRetryableToolFailure(result))
+                        break;
+                    this.emitToolExecutionEvents({
+                        toolCallId: result.toolCallId,
+                        toolName: result.toolName,
+                        status: 'error',
+                        arguments: defaultArgs,
+                        error: result.error,
+                        willRetry: true,
+                        node: node.id,
+                    });
+                    await sleepToolRetry(toolRetryDelayMs(attempt, retry.backoff));
+                    result = await this.toolExecutor.execute(request);
+                }
                 const executionTime = Date.now() - startedAt;
                 const skillDirs = Object.values(skillDefs ?? {})
                     .filter((skill) => Boolean(skill.bundlePath))
@@ -787,6 +874,7 @@ export class LangGraphAdapter {
                     arguments: defaultArgs,
                     content: result.content,
                     error: result.error,
+                    willRetry: false,
                     executionTime,
                     node: node.id,
                     ...(skillDirs.length > 0 ? { skillDirs } : {}),
@@ -891,6 +979,9 @@ export class LangGraphAdapter {
                     loadedTools,
                     skillDefinitions: skillDefs,
                 });
+                if (this.overlayExtraRoots.length > 0) {
+                    jail.extraRoots = [...(jail.extraRoots ?? []), ...this.overlayExtraRoots];
+                }
                 const workingDirectory = jail.workdir;
                 const jailRoots = resolveJailRoots(jail);
                 const skillDirs = Object.values(skillDefs ?? {})
@@ -972,7 +1063,7 @@ export class LangGraphAdapter {
                             },
                         });
                     }
-                    : undefined);
+                    : undefined, this.interceptors);
                 const next = await llmNode.execute(state);
                 const hydratedUpdate = loadedTools && loadedTools !== loadedToolsBase ? { loadedTools } : {};
                 if (!silent)
@@ -990,6 +1081,31 @@ export class LangGraphAdapter {
             });
         };
     }
+    /**
+     * RAG 节点：编译期 fail-fast（deps 缺失），请求级状态经 execute(state) 流转
+     */
+    createRagNodeFunction(node) {
+        if (!this.ragNodeDeps) {
+            throw new Error(`图使用了 type:rag 节点 "${node.id}"，但宿主未注入 ragNodeDeps（LangGraphAdapter 第 6 参）`);
+        }
+        const ragNode = new RagNode(node.id, (node.config ?? {}), {
+            ...this.ragNodeDeps,
+            // 未显式提供时复用 adapter 已组装的 orchestrator（§9.3：toolExecutor+governance 透传）
+            toolOrchestrator: this.ragNodeDeps.toolOrchestrator ?? this.toolOrchestrator,
+            // rag.* 事件接 SSE 旁路（请求级执行流存活期间有效；宿主/测试注入的 emitEvent 优先）
+            emitEvent: this.ragNodeDeps.emitEvent ??
+                ((type, payload) => {
+                    this.emitStreamEvent({
+                        type,
+                        taskId: undefined,
+                        correlationId: undefined,
+                        timestamp: new Date().toISOString(),
+                        payload,
+                    });
+                }),
+        });
+        return (state) => ragNode.execute(state);
+    }
     /**
      * 子图节点：优先 config.subgraphDsl；否则按 skillId 从 state.skillDefinitions.workflow 解析。
      * 技能正文用短目录 + read_file，不灌 system。
@@ -1000,7 +1116,10 @@ export class LangGraphAdapter {
             node.config?.['skillId'] ??
             embeddedDsl?.name;
         if (embeddedDsl) {
-            return this.subGraphCompiler.compileSubGraph(embeddedDsl, configuredSkillId);
+            return this.subGraphCompiler.compileSubGraph(embeddedDsl, configuredSkillId, {
+                isolateContext: isSkillContextIsolated(node),
+                parentNodeId: node.id,
+            });
         }
         return async (state) => {
             const skillId = configuredSkillId ??
@@ -1011,70 +1130,13 @@ export class LangGraphAdapter {
             if (!workflow?.nodes?.length) {
                 throw preloadSkillNotFound(`子图节点无法解析 Skill workflow: node=${node.id}, skillId=${skillId ?? '(none)'}`, { nodeId: node.id, skillId });
             }
-            const fn = this.subGraphCompiler.compileSubGraph(workflow, skillId ?? def?.skillId);
+            const fn = this.subGraphCompiler.compileSubGraph(workflow, skillId ?? def?.skillId, {
+                isolateContext: isSkillContextIsolated(node),
+                parentNodeId: node.id,
+            });
             return fn(state);
         };
     }
-    /**
-     * 并行节点：并行执行多个子任务分支
-     *
-     * 支持两种并行模式：
-     * 1. branches 模式：node.branches 列出要并行执行的节点 ID，每个节点的执行函数由 DSL 定义
-     * 2. tasks 模式：node.config.tasks 列出要并行执行的异步任务函数
-     *
-     * 执行结果合并到 state.__parallelResults 中。
-     */
-    createParallelNodeFunction(node) {
-        return async (state) => {
-            const branchNodeIds = node.branches ?? node.config?.['branches'] ?? [];
-            const tasks = node.config?.['tasks'];
-            const results = [];
-            if (tasks?.length) {
-                // tasks 模式：并行执行配置的任务
-                const promises = tasks.map(async (task) => {
-                    try {
-                        // 任务结果由外部注入的 task executor 处理
-                        // 此处仅记录任务 ID，实际执行依赖外部编排
-                        return { branchId: task.id, success: true, result: { taskId: task.id, status: 'dispatched' } };
-                    }
-                    catch (err) {
-                        return {
-                            branchId: task.id,
-                            success: false,
-                            error: err instanceof Error ? err.message : String(err),
-                        };
-                    }
-                });
-                results.push(...await Promise.all(promises));
-            }
-            else if (branchNodeIds.length) {
-                // branches 模式：并行执行分支节点
-                const promises = branchNodeIds.map(async (branchId) => {
-                    try {
-                        // 每个分支节点的实际执行由 LangGraph 编排层驱动
-                        // 并行节点仅负责触发并汇总状态
-                        return { branchId, success: true, result: { dispatched: true } };
-                    }
-                    catch (err) {
-                        return {
-                            branchId,
-                            success: false,
-                            error: err instanceof Error ? err.message : String(err),
-                        };
-                    }
-                });
-                results.push(...await Promise.all(promises));
-            }
-            const allSuccess = results.every((r) => r.success);
-            return {
-                ...state,
-                currentNode: node.id,
-                __parallelResults: results,
-                __parallelAllSuccess: allSuccess,
-                __conditionResult: allSuccess ? 'success' : 'partial_failure',
-            };
-        };
-    }
     /**
      * 代码执行节点：在受限沙箱中执行用户代码
      *
@@ -1250,6 +1312,41 @@ export class LangGraphAdapter {
      * 否则多轮回放时 DeepSeek thinking 会因缺少 reasoning_content 而 400，
      * tool 消息也会丢掉 tool_call_id。
      */
+    /**
+     * 工具形态检索面白名单（图声明即真相）：tool 节点 config.retrievalSources 声明的
+     * 数据源目录 → 本图工具白名单（声明源解析出的工具 + rag_search）。未声明的检索类
+     * 工具对主 LLM 工具表与执行链整体不可见/不可用；图未声明 = 不收敓名单（通用形态）。
+     *
+     * 约束——单检索面假设：find 只取全图首个带 retrievalSources 的 tool 节点、按它过滤
+     * 全图 loadedTools。多 tool 节点各声明检索面属未支持场景：第二面的工具会被当成
+     * 未声明而过滤，无法各自收敛；如需支持须改为 per-node 收敛（在节点边界分别过滤
+     * loadedTools，而非此处全图一次性收敛）。
+     */
+    applyDeclaredSearchFace(state, dsl) {
+        const face = dsl?.nodes?.find((n) => n.type === 'tool' && n.config?.['retrievalSources']);
+        const declaration = face?.config?.['retrievalSources'];
+        const loaded = state.loadedTools;
+        if (!declaration || !loaded || typeof loaded !== 'object')
+            return state;
+        const resolved = resolveRagSources({ retrievalSources: declaration });
+        const allowed = new Set([...(resolved.toolScope ?? []), RAG_SEARCH_TOOL_NAME]);
+        const filtered = {};
+        for (const [name, def] of Object.entries(loaded)) {
+            if (!allowed.has(name))
+                continue;
+            // 数据源目录写进保留工具的 description（幂等）——主 LLM 直调时与 rag 内核
+            // 同一份目录，杜绝瞎猜 datasetCode；内核组表侧 appendSourceCatalog 幂等不重复
+            const catalog = resolved.sourceCatalog[name];
+            if (catalog?.length) {
+                const desc = appendSourceCatalog(def.manifest.description, catalog);
+                filtered[name] = { ...def, manifest: { ...def.manifest, description: desc } };
+            }
+            else {
+                filtered[name] = def;
+            }
+        }
+        return { ...state, loadedTools: filtered };
+    }
     graphStateToLangGraphInput(state) {
         const mapped = (state.messages ?? []).map((msg) => ({
             role: msg.role,
@@ -1306,7 +1403,10 @@ export class LangGraphAdapter {
                 if (msg.role === 'assistant' && Array.isArray(msg.toolCalls) && msg.toolCalls.length > 0) {
                     // tool.called 由 Tool 节点在真正执行时发出，此处不再把 LLM function-call 当执行开始
                     // 子图节点的 updates 是内层已 stream 过的回写，不要再发空 reasoning chunk
-                    if (subgraphNodeIds.has(nodeId) || silentNodeIds.has(nodeId)) {
+                    if (silentNodeIds.has(nodeId)) {
+                        continue;
+                    }
+                    if (subgraphNodeIds.has(nodeId) && streamedTextThisTurn) {
                         continue;
                     }
                     const hasText = typeof msg.content === 'string' && msg.content.trim().length > 0;
@@ -1333,7 +1433,9 @@ export class LangGraphAdapter {
                     continue;
                 }
                 if (msg.role === 'assistant' && typeof msg.content === 'string' && msg.content.length > 0) {
-                    if (silentNodeIds.has(nodeId) || subgraphNodeIds.has(nodeId))
+                    if (silentNodeIds.has(nodeId))
+                        continue;
+                    if (subgraphNodeIds.has(nodeId) && streamedTextThisTurn)
                         continue;
                     // 已通过 onChunk 推送过 token，避免整段重复
                     if (streamedTextThisTurn) {

package/dist/graph/adapters/skill-isolate.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Skill 子图可选隔离（实验口）。仅节点 `isolateContext: true`。
+ * 只把本轮输入给子图，回写最后一条带正文的 assistant；没有则不回写。
+ * 子图 Checkpoint / HITL 走 `sessionId#父节点id`，不写父 latest。
+ */
+import type { GraphMessage } from '../contracts/executable-graph.js';
+import type { GraphNode } from '../contracts/executable-graph.js';
+/** 只认节点配置。进程环境变量不会给所有 subgraph 开隔离。 */
+export declare function isSkillContextIsolated(node: GraphNode | undefined): boolean;
+export declare function isolatedSkillMessages(parentMessages: GraphMessage[], skillInput: unknown): GraphMessage[];
+/** 只回写最后一条带正文的 assistant；没有则空数组，避免把 tool 行丢给父图。 */
+export declare function isolatedSkillOutput(added: GraphMessage[]): GraphMessage[];
+export declare function isIsolatedSkillState(state: Record<string, unknown> | undefined): boolean;

package/dist/graph/adapters/skill-isolate.js

@@ -0,0 +1,39 @@
+/**
+ * Skill 子图可选隔离（实验口）。仅节点 `isolateContext: true`。
+ * 只把本轮输入给子图，回写最后一条带正文的 assistant；没有则不回写。
+ * 子图 Checkpoint / HITL 走 `sessionId#父节点id`，不写父 latest。
+ */
+/** 只认节点配置。进程环境变量不会给所有 subgraph 开隔离。 */
+export function isSkillContextIsolated(node) {
+    return node?.config?.['isolateContext'] === true;
+}
+export function isolatedSkillMessages(parentMessages, skillInput) {
+    let text = '';
+    if (typeof skillInput === 'string' && skillInput.trim()) {
+        text = skillInput.trim();
+    }
+    else if (skillInput && typeof skillInput === 'object' && 'text' in skillInput) {
+        text = String(skillInput.text ?? '').trim();
+    }
+    if (!text) {
+        for (let i = parentMessages.length - 1; i >= 0; i--) {
+            if (parentMessages[i]?.role === 'user' && parentMessages[i]?.content) {
+                text = parentMessages[i].content;
+                break;
+            }
+        }
+    }
+    return [{ role: 'user', content: text || '' }];
+}
+/** 只回写最后一条带正文的 assistant；没有则空数组，避免把 tool 行丢给父图。 */
+export function isolatedSkillOutput(added) {
+    for (let i = added.length - 1; i >= 0; i--) {
+        if (added[i]?.role === 'assistant' && added[i]?.content) {
+            return [{ role: 'assistant', content: added[i].content }];
+        }
+    }
+    return [];
+}
+export function isIsolatedSkillState(state) {
+    return state?.['skillIsolateContext'] === true;
+}

package/dist/graph/adapters/subgraph-compiler.d.ts

@@ -3,6 +3,7 @@
  *
  * 将 Skill DSL 编译为子图节点函数，嵌入父 Graph 执行。
  * 子图作为独立 StateGraph 编译，父图通过节点函数调用子图并合并输出。
+ * Skill 子图不得再含 type=subgraph（G-3 / B14）。
  *
  * @see design.md §1.4 子图嵌套: Skill作为子图嵌入主Graph
  * @see requirements.md Requirement 1 AC2 — 子图嵌套（Skill作为子图）
@@ -24,16 +25,20 @@ type LangGraphState = Record<string, unknown>;
  * 4. 执行时，子图内部运行完整的 graph invoke 流程，输出合并回父图 state
  */
 export declare class SubGraphCompiler {
+    private readonly auditReporter?;
     private readonly adapter;
     private readonly governanceClient?;
     private readonly skillAuditRecorder?;
-    constructor(adapter?: LangGraphAdapter, governanceClient?: IGovernanceClient, skillAuditRecorder?: SkillAuditRecorder);
+    constructor(adapter?: LangGraphAdapter, governanceClient?: IGovernanceClient, skillAuditRecorder?: SkillAuditRecorder, auditReporter?: import("../../governance/audit-reporter.js").IAuditReporter | undefined);
     /**
      * 将 Skill DSL 编译为可嵌入父图的 NodeFunction
      *
      * @param dsl - Skill 的 GraphDSL 定义
      * @param skillId - Skill 资源 ID（用于 checkPermission skill:use）
      */
-    compileSubGraph(dsl: GraphDSL, skillId?: string): NodeFunction<LangGraphState>;
+    compileSubGraph(dsl: GraphDSL, skillId?: string, options?: {
+        isolateContext?: boolean;
+        parentNodeId?: string;
+    }): NodeFunction<LangGraphState>;
 }
 export {};