@gt-fe/eap-runtime 0.0.19 → 0.0.21

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

@@ -11,8 +11,12 @@ import { StateGraph, START, END, } from '@langchain/langgraph';
 import { resolveCheckpointThreadId } from '../../session/persist-turn-messages.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';
@@ -30,8 +34,10 @@ import { AppError, ErrorCodes } from '@gt-fe/eap-contracts';
 import { pickContextFields } from '../../token/context-window.js';
 import { isHitlDecision, lastAssistantHasUnansweredToolCalls } from '../hitl/hitl-handler.js';
 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;
 /**
@@ -60,6 +66,7 @@ function langGraphRunOptions(dsl, extra) {
  * 3. 提供 Checkpoint 提取与恢复能力
  */
 export class LangGraphAdapter {
+    auditReporter;
     checkpointer;
     subGraphCompiler;
     llmProvider;
@@ -76,17 +83,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();
@@ -124,7 +143,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);
     }
     /**
      * 注册自定义条件评估函数
@@ -132,6 +151,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）。
@@ -171,6 +194,7 @@ export class LangGraphAdapter {
      * Tool 节点执行旁路：started → tool.called + tool.progress；
      * completed/error → 对应终态 + tool.progress。同一 toolCallId。
      * 读 SKILL.md / 技能包内文件：成功后再发 skill.loaded / skill.resource_read，同时保留 tool.*。
+     * 读 SKILL.md 另发 skill.started / skill.completed（与 Trace type=skill Span 对齐）；子图内不重复。
      */
     emitToolExecutionEvents(progress) {
         const stream = getExecutionStream();
@@ -185,16 +209,48 @@ export class LangGraphAdapter {
         const skillRead = classifySkillRead(progress.toolName, progress.arguments, progress.skillDirs);
         if (skillRead && progress.status === 'completed') {
             if (skillRead.kind === 'loaded') {
+                const skillId = skillRead.skillId || loc.skillId || skillRead.path;
                 stream.sink({
                     type: 'skill.loaded',
                     taskId,
                     correlationId,
                     timestamp,
                     payload: {
-                        skillId: skillRead.skillId || loc.skillId || skillRead.path,
+                        skillId,
                         path: skillRead.path,
                     },
                 });
+                const catalogSkill = skillEntryInvocationFromTool({
+                    toolName: progress.toolName,
+                    arguments: progress.arguments,
+                    skillDirs: progress.skillDirs,
+                    alreadyInSkillSpan: progress.inSkillSubgraph,
+                });
+                if (catalogSkill) {
+                    stream.sink({
+                        type: 'skill.started',
+                        taskId,
+                        correlationId,
+                        timestamp,
+                        payload: {
+                            skillId: catalogSkill.skillId,
+                            skillName: progress.skillName || catalogSkill.skillId,
+                            path: catalogSkill.path,
+                            ...(progress.skillSpace ? { skillSpace: progress.skillSpace } : {}),
+                            ...(progress.skillVersion ? { skillVersion: progress.skillVersion } : {}),
+                        },
+                    });
+                    stream.sink({
+                        type: 'skill.completed',
+                        taskId,
+                        correlationId,
+                        timestamp,
+                        payload: {
+                            skillId: catalogSkill.skillId,
+                            skillName: catalogSkill.skillId,
+                        },
+                    });
+                }
             }
             else {
                 stream.sink({
@@ -216,6 +272,7 @@ export class LangGraphAdapter {
                     toolCallId: progress.toolCallId,
                     toolName: progress.toolName,
                     ...(progress.toolset ? { toolset: progress.toolset } : {}),
+                    ...(progress.toolVersion ? { toolVersion: progress.toolVersion } : {}),
                     arguments: progress.arguments ?? {},
                     ...loc,
                 },
@@ -255,7 +312,7 @@ export class LangGraphAdapter {
                     toolName: progress.toolName,
                     ...(progress.toolset ? { toolset: progress.toolset } : {}),
                     error: progress.error ?? 'Unknown error',
-                    willRetry: false,
+                    willRetry: progress.willRetry === true,
                     ...loc,
                 },
             });
@@ -277,6 +334,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));
@@ -317,6 +375,7 @@ export class LangGraphAdapter {
                 correlationId: ephemeral(''),
                 taskId: ephemeral(''),
                 sessionId: ephemeral(''),
+                skillIsolateContext: ephemeral(undefined),
                 loadedTools: ephemeral(undefined),
                 loadedSkills: ephemeral(undefined),
                 skillDefinitions: ephemeral(undefined),
@@ -329,9 +388,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 节点追加一条使用明细
@@ -343,7 +408,6 @@ export class LangGraphAdapter {
                     },
                     default: () => [],
                 },
-                __parallelResults: ephemeral(undefined),
                 __codeResult: ephemeral(undefined),
                 __codeError: ephemeral(undefined),
                 __conditionResult: ephemeral(undefined),
@@ -415,7 +479,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;
@@ -488,7 +552,7 @@ 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 袋经 ?? 保留。
@@ -616,23 +680,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) {
@@ -709,7 +776,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) {
@@ -732,7 +799,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,
@@ -740,7 +807,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))
@@ -752,6 +837,7 @@ export class LangGraphAdapter {
                     arguments: defaultArgs,
                     content: result.content,
                     error: result.error,
+                    willRetry: false,
                     executionTime,
                     node: node.id,
                     ...(skillDirs.length > 0 ? { skillDirs } : {}),
@@ -856,6 +942,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 ?? {})
@@ -937,7 +1026,7 @@ export class LangGraphAdapter {
                             },
                         });
                     }
-                    : undefined);
+                    : undefined, this.interceptors);
                 const next = await llmNode.execute(state);
                 const hydratedUpdate = loadedTools && loadedTools !== loadedToolsBase ? { loadedTools } : {};
                 if (!silent)
@@ -955,6 +1044,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。
@@ -965,7 +1079,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 ??
@@ -976,70 +1093,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',
-            };
-        };
-    }
     /**
      * 代码执行节点：在受限沙箱中执行用户代码
      *
@@ -1215,6 +1275,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,

package/dist/graph/adapters/skill-entry-span.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 成功读 SKILL.md 时写 Trace `type=skill` Span。
+ *
+ * 假设：Skill 被调用 = 一次成功读取技能包入口（SKILL.md），
+ * 与子图激活走同一 collector.createNode({ type: 'skill' })。
+ * 声明版本在 createNode.version；skillSpace 只在 input。
+ * 子图已有 skillSpanId 时不记第二条。write_file / 包内附属读 / 失败读不是调用。
+ */
+import { type SkillDirRef, type SkillSpace } from './skill-read.js';
+export interface SkillTraceIdentity {
+    skillId: string;
+    skillName?: string;
+    skillVersion?: string;
+    skillSpace?: SkillSpace;
+}
+export declare function skillTraceIdentity(state: Record<string, unknown>, skillId: string, fallbackPath?: string): SkillTraceIdentity;
+export declare function skillSpanFields(identity: SkillTraceIdentity, extra?: {
+    path?: string;
+    source?: string;
+}): {
+    version?: string;
+    input: Record<string, unknown>;
+};
+export declare function skillEntryInvocationFromTool(input: {
+    toolName: string;
+    arguments?: Record<string, unknown>;
+    skillDirs?: SkillDirRef[];
+    alreadyInSkillSpan?: boolean;
+}): {
+    skillId: string;
+    path: string;
+} | null;
+export declare function recordSkillEntrySpan(state: Record<string, unknown>, input: {
+    toolName: string;
+    arguments?: Record<string, unknown>;
+    skillDirs?: SkillDirRef[];
+}): Promise<void>;

package/dist/graph/adapters/skill-entry-span.js

@@ -0,0 +1,78 @@
+/**
+ * 成功读 SKILL.md 时写 Trace `type=skill` Span。
+ *
+ * 假设：Skill 被调用 = 一次成功读取技能包入口（SKILL.md），
+ * 与子图激活走同一 collector.createNode({ type: 'skill' })。
+ * 声明版本在 createNode.version；skillSpace 只在 input。
+ * 子图已有 skillSpanId 时不记第二条。write_file / 包内附属读 / 失败读不是调用。
+ */
+import { classifySkillRead, classifySkillSpace } from './skill-read.js';
+import { completeGraphSpan, startGraphSpan } from '../trace-span.js';
+function declaredSkillVersion(skillId, version) {
+    const raw = version?.trim();
+    if (!raw || raw === skillId)
+        return undefined;
+    return raw;
+}
+export function skillTraceIdentity(state, skillId, fallbackPath) {
+    const defs = state['skillDefinitions'];
+    const info = defs?.[skillId];
+    const exec = state['executionContext'];
+    const userId = (typeof exec?.userId === 'string' && exec.userId.trim()) ||
+        (typeof state['userId'] === 'string' && state['userId'].trim()) ||
+        undefined;
+    const agentDir = typeof state['agentDir'] === 'string' ? state['agentDir'] : undefined;
+    const bundle = info?.bundlePath || fallbackPath;
+    const skillSpace = bundle ? classifySkillSpace(bundle, { agentDir, userId }) : undefined;
+    const skillVersion = declaredSkillVersion(skillId, info?.version);
+    return {
+        skillId,
+        ...(info?.name ? { skillName: info.name } : {}),
+        ...(skillVersion ? { skillVersion } : {}),
+        ...(skillSpace ? { skillSpace } : {}),
+    };
+}
+export function skillSpanFields(identity, extra) {
+    return {
+        ...(identity.skillVersion ? { version: identity.skillVersion } : {}),
+        input: {
+            skillId: identity.skillId,
+            ...(identity.skillSpace ? { skillSpace: identity.skillSpace } : {}),
+            ...(extra?.path ? { path: extra.path } : {}),
+            ...(extra?.source ? { source: extra.source } : {}),
+        },
+    };
+}
+export function skillEntryInvocationFromTool(input) {
+    if (input.alreadyInSkillSpan)
+        return null;
+    const hit = classifySkillRead(input.toolName, input.arguments, input.skillDirs);
+    if (!hit || hit.kind !== 'loaded' || !hit.skillId)
+        return null;
+    return { skillId: hit.skillId, path: hit.path };
+}
+export async function recordSkillEntrySpan(state, input) {
+    const alreadyInSkillSpan = typeof state['skillSpanId'] === 'string' && Boolean(state['skillSpanId']);
+    const hit = skillEntryInvocationFromTool({
+        toolName: input.toolName,
+        arguments: input.arguments,
+        skillDirs: input.skillDirs,
+        alreadyInSkillSpan,
+    });
+    if (!hit)
+        return;
+    const identity = skillTraceIdentity(state, hit.skillId, hit.path);
+    const fields = skillSpanFields(identity, { path: hit.path, source: 'skill_md' });
+    const spanId = await startGraphSpan(state, {
+        name: hit.skillId,
+        type: 'skill',
+        extra: {
+            ...(fields.version ? { version: fields.version } : {}),
+            input: fields.input,
+        },
+    });
+    await completeGraphSpan(state, spanId, {
+        status: 'completed',
+        output: { skillId: hit.skillId, path: hit.path },
+    });
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Skill 子图可选隔离（实验口）。仅节点 `isolateContext: true`。
+ * 只把本轮输入给子图，回写最后一条带正文的 assistant；没有则不回写。
+ * 隔离时不写父 session Checkpoint。
+ * 子图内 HITL 未按隔离线程设计：skillIsolateContext 为 true 时禁止 interrupt。
+ */
+import type { GraphMessage } from '../contracts/executable-graph.js';
+import type { GraphNode } from '../contracts/executable-graph.js';
+export declare const SKILL_ISOLATE_HITL_MESSAGE = "Skill isolateContext \u4E0D\u80FD\u4E0E\u5B50\u56FE\u5185\u4EBA\u5DE5\u786E\u8BA4\u4E00\u8D77\u4F7F\u7528\u3002\u5173\u6389 isolate\uFF0C\u6216\u4E0D\u8981\u5728\u8BE5 Skill \u91CC\u4F7F\u7528 require_confirmation / beforeTool ask\u3002";
+/** 只认节点配置。进程环境变量不会给所有 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;
+/** 隔离子图即将 HITL 时拒绝，避免写错父线程 Checkpoint。 */
+export declare function assertIsolatedSkillAllowsHitl(state: Record<string, unknown> | undefined): void;

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

@@ -0,0 +1,50 @@
+/**
+ * Skill 子图可选隔离（实验口）。仅节点 `isolateContext: true`。
+ * 只把本轮输入给子图，回写最后一条带正文的 assistant；没有则不回写。
+ * 隔离时不写父 session Checkpoint。
+ * 子图内 HITL 未按隔离线程设计：skillIsolateContext 为 true 时禁止 interrupt。
+ */
+import { AppError, ErrorCodes } from '@gt-fe/eap-contracts';
+export const SKILL_ISOLATE_HITL_MESSAGE = 'Skill isolateContext 不能与子图内人工确认一起使用。关掉 isolate，或不要在该 Skill 里使用 require_confirmation / beforeTool ask。';
+/** 只认节点配置。进程环境变量不会给所有 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;
+}
+/** 隔离子图即将 HITL 时拒绝，避免写错父线程 Checkpoint。 */
+export function assertIsolatedSkillAllowsHitl(state) {
+    if (!isIsolatedSkillState(state))
+        return;
+    throw new AppError(ErrorCodes.GRAPH_EXECUTION_ERROR, SKILL_ISOLATE_HITL_MESSAGE, {
+        exposeMessage: true,
+    });
+}