@gt-fe/eap-runtime 0.0.39 → 0.0.41

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

@@ -572,6 +572,7 @@ export class LangGraphAdapter {
                 traceCollector: ephemeral(undefined),
                 traceId: ephemeral(undefined),
                 skillSpanId: ephemeral(undefined),
+                llmSpanId: ephemeral(undefined),
                 toolSpanId: ephemeral(undefined),
                 hitlToolCallId: ephemeral(undefined),
                 lastSpanId: ephemeral(undefined),

package/dist/graph/adapters/subgraph-compiler.js

@@ -12,6 +12,7 @@ import { assertSkillPermission } from '../../governance/permission-guard.js';
 import { LangGraphAdapter } from './langgraph.adapter.js';
 import { assertSkillGraphHasNoSubgraphNodes } from './graph-nesting.js';
 import { resolveExecutionTrace, warnTraceSpanFailure, } from '../execution-trace-context.js';
+import { startGraphSpan } from '../trace-span.js';
 import { skillSpanFields, skillTraceIdentity } from './skill-entry-span.js';
 import { filterLoadedToolsForSkill, spokenName, } from '../../tool/system-prompt-builder.js';
 import { unwrapHitlPaused } from '../hitl/hitl-handler.js';
@@ -96,26 +97,16 @@ export class SubGraphCompiler {
                 });
             }
             let skillSpanId = existingSpanId || null;
-            if (!resuming && traceCollector && traceId) {
-                try {
-                    const fields = skillSpanFields(identity, { source: 'subgraph' });
-                    skillSpanId = await traceCollector.createNode({
-                        traceId,
-                        name: spanName,
-                        type: 'skill',
-                        agentCode: state['agentCode'] ?? state['agentId'],
+            if (!resuming) {
+                const fields = skillSpanFields(identity, { source: 'subgraph' });
+                skillSpanId = (await startGraphSpan(state, {
+                    name: spanName,
+                    type: 'skill',
+                    extra: {
                         ...(fields.version ? { version: fields.version } : {}),
                         input: fields.input,
-                        metadata: {
-                            taskId: state['taskId'],
-                            correlationId: state['correlationId'],
-                        },
-                    });
-                }
-                catch (err) {
-                    warnTraceSpanFailure('createNode', { type: 'skill', name: spanName, traceId }, err);
-                    skillSpanId = null;
-                }
+                    },
+                })) ?? null;
             }
             try {
                 // 1. 编译子图（每次执行时编译，确保子图实例独立）

package/dist/graph/contracts/executable-graph.d.ts

@@ -240,6 +240,11 @@ export interface GraphState {
     skillIsolateContext?: boolean;
     /** 当前 Skill 子图 createNode 返回的 span id；子图内 Tool span 的 parentNodeId */
     skillSpanId?: string;
+    /**
+     * 本回合父图模型调用的 span id。父图 tool / 手册技能 / 子图技能入口挂到它下面。
+     * 只在 llm createNode 成功时更新。HITL 等待态一起带上。
+     */
+    llmSpanId?: string;
     /**
      * HITL 续跑：暂停时已 create 的 tool Span id。
      * 按 hitlToolCallId 复用，禁止再 createNode。

package/dist/graph/hitl/hitl-handler.d.ts

@@ -40,6 +40,7 @@ export interface HitlInterruptExtras {
     toolName?: string;
     toolSpanId?: string;
     skillSpanId?: string;
+    llmSpanId?: string;
 }
 /** HITL 等待中状态（内存中维护） */
 export interface HitlWaitingState {
@@ -55,6 +56,7 @@ export interface HitlWaitingState {
     toolName?: string;
     toolSpanId?: string;
     skillSpanId?: string;
+    llmSpanId?: string;
     hitlSpanId?: string;
 }
 /** HITL 超时错误（保留类型；timer 不再 throw，resume 逾期改走 AppError） */
@@ -119,6 +121,7 @@ export interface PersistedHitlWaiting {
     toolName?: string;
     toolSpanId?: string;
     skillSpanId?: string;
+    llmSpanId?: string;
     hitlSpanId?: string;
     /** error/cancel 超时已占用此等待；resume 必须拒绝 */
     timedOut?: boolean;

package/dist/graph/hitl/hitl-handler.js

@@ -194,6 +194,7 @@ function prepareHitlCheckpointState(state) {
         correlationId: state.correlationId ?? raw.correlationId,
         delegationToken: state.delegationToken ?? raw.delegationToken,
         skillSpanId: state.skillSpanId ?? raw.skillSpanId,
+        llmSpanId: state.llmSpanId ?? (typeof raw.llmSpanId === 'string' ? raw.llmSpanId : undefined),
         traceId: state.traceId ?? (typeof raw.traceId === 'string' ? raw.traceId : undefined),
         lastSpanId: state.lastSpanId ?? (typeof raw.lastSpanId === 'string' ? raw.lastSpanId : undefined),
     };
@@ -227,6 +228,7 @@ function waitingFromPersisted(persisted, taskId) {
         toolName: persisted.toolName,
         toolSpanId: persisted.toolSpanId,
         skillSpanId: persisted.skillSpanId,
+        llmSpanId: persisted.llmSpanId,
         hitlSpanId: persisted.hitlSpanId,
     };
 }
@@ -285,6 +287,8 @@ export class HitlHandler {
         const deadlineAt = new Date(Date.now() + timeoutMs).toISOString();
         const skillSpanId = extras.skillSpanId ??
             (typeof state.skillSpanId === 'string' ? state.skillSpanId : undefined);
+        const llmSpanId = extras.llmSpanId ??
+            (typeof state.llmSpanId === 'string' ? state.llmSpanId : undefined);
         const hitlSpanId = await startGraphSpan(state, {
             name: extras.toolName ?? 'hitl',
             type: 'hitl',
@@ -306,6 +310,7 @@ export class HitlHandler {
             toolName: extras.toolName,
             toolSpanId: extras.toolSpanId,
             skillSpanId,
+            llmSpanId,
             hitlSpanId,
         };
         const existing = await this.checkpointSaver.load(threadId);
@@ -392,6 +397,7 @@ export class HitlHandler {
             toolName: extras.toolName,
             toolSpanId: extras.toolSpanId,
             skillSpanId,
+            llmSpanId,
             hitlSpanId,
         });
     }
@@ -448,6 +454,7 @@ export class HitlHandler {
                 hitlRespondedBy: userId,
                 ...(waiting.toolSpanId ? { toolSpanId: waiting.toolSpanId } : {}),
                 ...(waiting.toolCallId ? { hitlToolCallId: waiting.toolCallId } : {}),
+                ...(waiting.llmSpanId ? { llmSpanId: waiting.llmSpanId } : {}),
             };
             const now = new Date().toISOString();
             await this.checkpointSaver.save(waiting.threadId, stripCheckpointCollectors({

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

@@ -8,6 +8,7 @@
  * @see design-v2 §5.2 / §5.3
  */
 import { resolveTraceId } from '../../../common/trace-id.js';
+import { withGraphSpan } from '../../trace-span.js';
 import { buildRagTools, resolveRagSources, mergeLocalDirs } from './tools.js';
 import { runReactLoop } from './react-loop.js';
 export class RagNode {
@@ -49,33 +50,40 @@ export class RagNode {
         if (excludedConfirmToolNames.length > 0) {
             throw new Error(`RagNode "${this.nodeId}" 检索源 tools 引用了需人工确认的工具: ${excludedConfirmToolNames.join(', ')}（requireConfirmation 工具的确认流挂在图级 tool 节点，rag 循环内执行会绕过确认，不支持挂载）`);
         }
-        const result = await runReactLoop({
-            nodeId: this.nodeId,
-            query: extractQuery(state),
-            history: extractHistory(state),
-            config: this.config,
-            apiTools,
-            kbToolNames,
-            llmProvider: this.deps.llmProvider,
-            toolOrchestrator: this.deps.toolOrchestrator,
-            retrievers,
-            loadedTools,
-            authContext: this.buildAuthContext(state),
-            executionContext: state['executionContext'],
-            forceToolServer: state['forceToolServer'],
-            userId: String(state['userId'] ?? ''),
-            ragScope,
-            emitEvent: this.deps.emitEvent,
-            traceCollector: state['traceCollector'],
-            traceId: resolveTraceId(state),
+        return withGraphSpan(state, {
+            name: this.nodeId,
+            type: 'llm',
+            extra: { metadata: { rag: true } },
+        }, async (spanId) => {
+            const result = await runReactLoop({
+                nodeId: this.nodeId,
+                query: extractQuery(state),
+                history: extractHistory(state),
+                config: this.config,
+                apiTools,
+                kbToolNames,
+                llmProvider: this.deps.llmProvider,
+                toolOrchestrator: this.deps.toolOrchestrator,
+                retrievers,
+                loadedTools,
+                authContext: this.buildAuthContext(state),
+                executionContext: state['executionContext'],
+                forceToolServer: state['forceToolServer'],
+                userId: String(state['userId'] ?? ''),
+                ragScope,
+                emitEvent: this.deps.emitEvent,
+                traceCollector: state['traceCollector'],
+                traceId: resolveTraceId(state),
+                parentSpanId: spanId,
+            });
+            // partial state 三连（与 LLMNode 同惯例）：
+            // messages 只返回新增（channel 为 append reducer）；token 走 __llmTokenUsage 累加器
+            return {
+                messages: [{ role: 'assistant', content: result.contextText }],
+                currentNode: this.nodeId,
+                __llmTokenUsage: result.tokenUsage,
+            };
         });
-        // partial state 三连（与 LLMNode 同惯例）：
-        // messages 只返回新增（channel 为 append reducer）；token 走 __llmTokenUsage 累加器
-        return {
-            messages: [{ role: 'assistant', content: result.contextText }],
-            currentNode: this.nodeId,
-            __llmTokenUsage: result.tokenUsage,
-        };
     }
     /** 身份组装照 ToolNode 惯例：executionContext 优先，state 兜底 */
     buildAuthContext(state) {

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

@@ -45,6 +45,8 @@ export interface RagLoopInput {
     /** Trace 采集器 + 执行流 ID（缺省不建 span，照 ToolNode 模式：resolveTraceId） */
     traceCollector?: ITraceCollector;
     traceId?: string;
+    /** 本 RAG 节点 llm Span；内部检索/降噪挂到它下面 */
+    parentSpanId?: string;
 }
 export interface RagLoopOutput {
     /** 降噪上下文（近重去重 + LLM 判定 + 句子抽取后的拼装结果） */

package/dist/graph/nodes/rag/react-loop.js

@@ -444,6 +444,7 @@ async function startTraceSpan(input, event) {
             traceId: input.traceId,
             name: event.name,
             type: event.type,
+            parentNodeId: input.parentSpanId,
             input: event.input,
             metadata: { rag: true, ...event.metadata },
         });

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

@@ -19,6 +19,7 @@ import { resolveCheckpointThreadId } from '../../session/persist-turn-messages.j
 import { mcpToolsetCode, toolTraceIdentity } from '../../tool/mcp-list.js';
 import { exposureScopeId, exposedNamesForScope, isUnloadedDeferredCall, mcpNamesToExpose, mergeExposed, partitionToolSearchCalls, runToolSearch, unloadedCallToolContent, } from '../../tool/mcp-tool-exposure.js';
 import { resolveExecutionTrace, warnTraceSpanFailure, } from '../execution-trace-context.js';
+import { resolveInvokedSpanParent } from '../trace-span.js';
 import { emitRuntimeLog } from '../../common/logger.js';
 import { toolResultHasArtifacts } from '../../tool/inject-public-artifact-links.js';
 import { decideBeforeTool, } from '../../execution/interceptors.js';
@@ -212,19 +213,21 @@ export class ToolNode {
             if (!traceCollector || !traceId)
                 return;
             try {
-                const parentNodeId = typeof state['skillSpanId'] === 'string' && state['skillSpanId']
-                    ? state['skillSpanId']
-                    : undefined;
+                const parentNodeId = resolveInvokedSpanParent(state);
+                const identity = toolTraceIdentity(loadedTools?.[name], name);
                 const spanId = await traceCollector.createNode({
                     traceId,
                     name,
                     type: 'tool',
                     parentNodeId,
                     agentCode: agentCode || undefined,
+                    ...(identity.toolVersion ? { version: identity.toolVersion } : {}),
                     input,
                     metadata: {
                         toolCallId: callId,
                         ...(notExecuted ? { notExecuted: true } : {}),
+                        ...(identity.toolset ? { toolset: identity.toolset } : {}),
+                        ...(identity.toolDisplayName ? { toolDisplayName: identity.toolDisplayName } : {}),
                     },
                 });
                 sideSpanIds.push(spanId);
@@ -293,9 +296,7 @@ export class ToolNode {
             if (!traceCollector || !traceId)
                 return null;
             try {
-                const parentNodeId = typeof state['skillSpanId'] === 'string' && state['skillSpanId']
-                    ? state['skillSpanId']
-                    : undefined;
+                const parentNodeId = resolveInvokedSpanParent(state);
                 const identity = toolTraceIdentity(loadedTools?.[req.toolName], req.toolName);
                 return await traceCollector.createNode({
                     traceId,
@@ -366,6 +367,7 @@ export class ToolNode {
                         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,
+                            llmSpanId: typeof state['llmSpanId'] === 'string' ? state['llmSpanId'] : undefined,
                         });
                         result =
                             confirmed ??

package/dist/graph/trace-span.d.ts

@@ -2,6 +2,11 @@
  * Graph 节点 Span 辅助：createNode / completeNode 失败不挡主路径。
  */
 import type { ITraceCollector, ExecutionNodeEvent, CompleteNodeParams } from '../contracts/trace-collector.js';
+/**
+ * 被这次模型调用出来的 tool / skill：子图内挂技能，否则挂本回合模型调用。
+ * 显式 parent 优先。不用 lastSpanId（工具跑完会把它改成工具自己）。
+ */
+export declare function resolveInvokedSpanParent(state: Record<string, unknown>, explicit?: string): string | undefined;
 export declare function startGraphSpan(state: Record<string, unknown>, input: {
     name: string;
     type: ExecutionNodeEvent['type'];
@@ -13,7 +18,7 @@ export declare function withGraphSpan(state: Record<string, unknown>, spec: {
     name: string;
     type: ExecutionNodeEvent['type'];
     extra?: Partial<Omit<ExecutionNodeEvent, 'traceId' | 'name' | 'type' | 'parentNodeId'>>;
-}, run: () => Promise<Record<string, unknown>>, complete?: {
+}, run: (spanId?: string) => Promise<Record<string, unknown>>, complete?: {
     outputFrom?: (result: Record<string, unknown>) => unknown;
 }): Promise<Record<string, unknown>>;
 /** llm Span create 时的 input：组装后的 system、工具短目录、本回合 messages。 */

package/dist/graph/trace-span.js

@@ -2,15 +2,27 @@
  * Graph 节点 Span 辅助：createNode / completeNode 失败不挡主路径。
  */
 import { resolveExecutionTrace, warnTraceSpanFailure, } from './execution-trace-context.js';
+function pickSpanId(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+/**
+ * 被这次模型调用出来的 tool / skill：子图内挂技能，否则挂本回合模型调用。
+ * 显式 parent 优先。不用 lastSpanId（工具跑完会把它改成工具自己）。
+ */
+export function resolveInvokedSpanParent(state, explicit) {
+    return pickSpanId(explicit) ?? pickSpanId(state['skillSpanId']) ?? pickSpanId(state['llmSpanId']);
+}
 export async function startGraphSpan(state, input) {
     // collector 只从这次调用链取；state 只用来拼 parent/task 元数据。
     const { collector, traceId } = resolveExecutionTrace(state);
     if (!collector || !traceId)
         return undefined;
-    const parentNodeId = input.parentSpanId ??
-        (typeof state['skillSpanId'] === 'string' && state['skillSpanId']
-            ? state['skillSpanId']
-            : undefined);
+    const parentNodeId = input.type === 'tool' || input.type === 'skill'
+        ? resolveInvokedSpanParent(state, input.parentSpanId)
+        : pickSpanId(input.parentSpanId) ?? pickSpanId(state['skillSpanId']);
     try {
         return await collector.createNode({
             traceId,
@@ -23,6 +35,10 @@ export async function startGraphSpan(state, input) {
             metadata: {
                 taskId: state['taskId'],
                 correlationId: state['correlationId'],
+                // 对人展示名；name 仍是图节点 id / 函数名 / skillId。
+                ...(typeof state['agentName'] === 'string' && state['agentName'].trim()
+                    ? { agentName: state['agentName'].trim() }
+                    : {}),
                 ...(input.extra?.metadata ?? {}),
             },
         });
@@ -46,7 +62,7 @@ export async function completeGraphSpan(state, spanId, params, collectorOverride
 export async function withGraphSpan(state, spec, run, complete) {
     const spanId = await startGraphSpan(state, spec);
     try {
-        const result = await run();
+        const result = await run(spanId);
         const usage = Array.isArray(result['__llmTokenUsage'])
             ? result['__llmTokenUsage'].at(-1)
             : undefined;
@@ -61,7 +77,13 @@ export async function withGraphSpan(state, spec, run, complete) {
                 : undefined,
             ...(typeof usage?.model === 'string' && usage.model ? { model: usage.model } : {}),
         });
-        return spanId ? { ...result, lastSpanId: spanId } : result;
+        return spanId
+            ? {
+                ...result,
+                lastSpanId: spanId,
+                ...(spec.type === 'llm' ? { llmSpanId: spanId } : {}),
+            }
+            : result;
     }
     catch (err) {
         await completeGraphSpan(state, spanId, {

package/dist/registry/graph-loader.d.ts

@@ -128,8 +128,8 @@ export declare class GraphLoader {
     resolveAgentDisplayName(agentCode: string, version?: string): Promise<string | undefined>;
     private fromAgentManifest;
     /**
-     * 解析 agent tools[] + graph tool 节点 union；
-     * server+预装：以预装 manifest 为准；desktop 合并 ILocalToolInstallStore。
+     * 装工具只认登记的工具集（snapshot.tools / 清单 toolsets、toolRefs、tools）和内联 manifest。
+     * 图上 config.tool、节点 id 不参与。server 预装优先；dev 再读 ./tools 下与登记 code 同名的目录；desktop 合并本机安装。
      */
     loadToolDefinitions(agentCode: string, options?: LoadToolDefinitionsOptions): Promise<LoadedToolDefinition[]>;
     private loadToolDefinitionsFromSource;

package/dist/registry/graph-loader.js

@@ -5,11 +5,10 @@
  * 开发态：Registry + 可选 ./tools 本地 manifest。
  */
 import { DEFAULT_GRAPH_TIMEOUT_MS } from '../common/types.js';
-import { readdir, readFile } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { resolveAgentModelAllowlist, resolveAgentDefaultModel } from './agent-models.js';
 import { DEFAULT_HTTP_TOOL_TIMEOUT_SEC, DEFAULT_TOOL_TIMEOUT_SEC } from '../tool/timeout.js';
-import { isMcpDiscoverStub } from '../tool/mcp-list.js';
 import { createDeploymentSnapshotFromEnv, isInlineToolDeclaration, overlayToolRefPolicies, } from './deployment-snapshot.js';
 import { preloadGraphNotFound, preloadManifestNotFound, preloadSkillNotFound, preloadToolNotFound, } from './preload-errors.js';
 import { PreinstallDefinitionCache, resolveDefinitionCacheEnabled, } from './definition-cache.js';
@@ -195,14 +194,39 @@ function yamlGraphToDsl(agentCode, graph) {
         config: configFromGraphDocument(graph),
     };
 }
-function collectToolNames(agent, graphDsl) {
-    const rawTools = agent?.manifest?.tools ?? [];
-    // 支持 string[] (ID 引用) 和 object[] (完整 ToolManifest 内联声明)
-    const fromAgent = rawTools.map((t) => typeof t === 'string' ? t : t?.name ?? t?.id);
-    const fromGraph = graphDsl.nodes
-        .filter((n) => n.type === 'tool')
-        .map((n) => n.config?.['tool'] ?? n.id);
-    return [...new Set([...fromAgent, ...fromGraph].filter(Boolean))];
+/** Registry `manifest.tools` 里的字符串 code。内联对象已在前面转成定义，这里不重复取。 */
+function manifestStringToolIds(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const item of raw) {
+        if (typeof item !== 'string')
+            continue;
+        const name = item.trim();
+        if (name)
+            out.push(name);
+    }
+    return out;
+}
+/**
+ * 还要向 Registry / 开发态目录补的登记项。
+ * 图上 `config.tool` 与节点 id 不是登记项。
+ */
+function pendingToolRefs(snapToolRefs, loadedRefNames, loadedNames, registryTools) {
+    const out = [];
+    const seen = new Set();
+    const push = (ref) => {
+        if (!ref.name || seen.has(ref.name) || loadedRefNames.has(ref.name) || loadedNames.has(ref.name)) {
+            return;
+        }
+        seen.add(ref.name);
+        out.push(ref);
+    };
+    for (const ref of snapToolRefs)
+        push(ref);
+    for (const id of manifestStringToolIds(registryTools))
+        push({ name: id });
+    return out;
 }
 function normalizeDataScope(raw) {
     if (raw === 'user-bound' || raw === 'department-bound' || raw === 'global')
@@ -437,27 +461,6 @@ function expandPreinstallToolset(pre, options) {
     }
     return out;
 }
-function fromLocalManifestFile(toolName, manifest) {
-    const permissions = manifest.permissions;
-    const metadata = manifest.metadata;
-    const manifestRef = {
-        id: String(manifest.id ?? toolName),
-        name: String(manifest.name ?? toolName),
-        version: String(manifest.version ?? '0.0.0'),
-        type: manifest.type ?? 'code',
-        status: 'active',
-        toolRuntime: (manifest.toolRuntime ?? manifest.runtime),
-        dataScope: normalizeDataScope(permissions?.dataScope),
-        requireConfirmation: Boolean(metadata?.require_confirmation),
-        execution: manifest.execution,
-    };
-    return {
-        toolId: String(manifest.id ?? toolName),
-        name: String(manifest.name ?? toolName),
-        manifest: manifestRef,
-        inputSchema: manifest.input,
-    };
-}
 /**
  * 从内联 Tool 声明（manifest.tools 中的完整 ToolManifest 对象）
  * 转为 LoadedToolDefinition。
@@ -505,52 +508,24 @@ async function readJsonObject(filePath) {
         return null;
     }
 }
-function loadedToolFromDevDir(dir, toolName, doc, toolsetOnly) {
-    const tools = doc.tools;
-    if (Array.isArray(tools) && tools.length > 0 && typeof tools[0] === 'object') {
+/**
+ * 开发态只读 `./tools/<code>`，展开整个工具集。不按子工具名扫相邻目录。
+ * 找到清单时返回展开结果，白名单把子工具都排除时为空数组。没有清单时返回 null。
+ */
+async function loadDevLocalToolset(toolsetCode, toolsDir, options) {
+    const dir = path.join(toolsDir, toolsetCode);
+    for (const file of DEV_LOCAL_MANIFEST_FILES) {
+        const doc = await readJsonObject(path.join(dir, file));
+        if (!doc)
+            continue;
         const pre = {
-            toolId: String(doc.code ?? path.basename(dir)),
-            name: String(doc.name ?? path.basename(dir)),
+            toolId: String(doc.id ?? doc.code ?? toolsetCode),
+            name: String(doc.code ?? doc.name ?? toolsetCode),
             version: String(doc.version ?? '0.0.0'),
             manifest: doc,
             bundlePath: dir,
         };
-        const expanded = expandPreinstallToolset(pre);
-        return expanded.find((d) => d.name === toolName) ?? null;
-    }
-    if (toolsetOnly)
-        return null;
-    return fromLocalManifestFile(toolName, doc);
-}
-async function loadDevLocalManifestFromDir(dir, toolName, toolsetOnly) {
-    const files = toolsetOnly ? ['toolset.manifest.json'] : DEV_LOCAL_MANIFEST_FILES;
-    for (const file of files) {
-        const doc = await readJsonObject(path.join(dir, file));
-        if (!doc)
-            continue;
-        const hit = loadedToolFromDevDir(dir, toolName, doc, toolsetOnly);
-        if (hit)
-            return hit;
-    }
-    return null;
-}
-async function loadDevLocalManifest(toolName, toolsDir) {
-    const direct = await loadDevLocalManifestFromDir(path.join(toolsDir, toolName), toolName, false);
-    if (direct)
-        return direct;
-    let entries;
-    try {
-        entries = await readdir(toolsDir, { withFileTypes: true });
-    }
-    catch {
-        return null;
-    }
-    for (const ent of entries) {
-        if (!ent.isDirectory() || ent.name === toolName)
-            continue;
-        const hit = await loadDevLocalManifestFromDir(path.join(toolsDir, ent.name), toolName, true);
-        if (hit)
-            return hit;
+        return expandPreinstallToolset(pre, options);
     }
     return null;
 }
@@ -816,8 +791,8 @@ export class GraphLoader {
         return extract(record?.manifest);
     }
     /**
-     * 解析 agent tools[] + graph tool 节点 union；
-     * server+预装：以预装 manifest 为准；desktop 合并 ILocalToolInstallStore。
+     * 装工具只认登记的工具集（snapshot.tools / 清单 toolsets、toolRefs、tools）和内联 manifest。
+     * 图上 config.tool、节点 id 不参与。server 预装优先；dev 再读 ./tools 下与登记 code 同名的目录；desktop 合并本机安装。
      */
     async loadToolDefinitions(agentCode, options = {}) {
         const requested = this.resolveVersion(options);
@@ -836,7 +811,8 @@ export class GraphLoader {
     }
     async loadToolDefinitionsFromSource(agentCode, options, version) {
         const activeOnly = options.activeOnly !== false;
-        const graphDsl = await this.loadGraph(agentCode, {
+        // 缺图时与原先一样失败。图上的 tool 名不加入下面的登记列表。
+        await this.loadGraph(agentCode, {
             agentVersion: version,
             bypassCache: options.bypassCache,
         });
@@ -889,27 +865,16 @@ export class GraphLoader {
             }, null, 2));
         }
         const snapToolRefs = overlayToolRefPolicies(snap?.tools ?? [], snap?.manifest);
-        const toolNamesFromSnap = snapToolRefs.map((t) => t.name).filter(Boolean);
-        const collectedFromGraph = collectToolNames(agent, graphDsl);
-        const toolNames = [...new Set([...collectedFromGraph, ...toolNamesFromSnap])];
-        // [DEBUG] 最终 toolNames 决策
-        if (process.env.EAP_LLM_DEBUG === '1') {
-            console.log('[LLM-DEBUG] toolNames:', JSON.stringify({
-                fromGraph: collectedFromGraph,
-                fromSnap: toolNamesFromSnap,
-                final: toolNames,
-            }));
-        }
-        if (this.deploymentSnapshot && (snapToolRefs.length > 0 || toolNames.length > 0)) {
+        const loadedRefNames = new Set();
+        if (this.deploymentSnapshot && snapToolRefs.length > 0) {
             const missing = [];
-            const processedToolsetNames = new Set(snapToolRefs.map((r) => r.name));
-            // 1) snapshot 引用的工具集全部加载并展开（enabledTools 白名单过滤）
             for (const ref of snapToolRefs) {
                 const pre = await this.deploymentSnapshot.loadToolManifest(ref, agentDir);
                 if (!pre) {
                     missing.push(ref.name);
                     continue;
                 }
+                loadedRefNames.add(ref.name);
                 for (const def of expandPreinstallToolset(pre, {
                     enabledTools: ref.enabledTools,
                     autoApprove: ref.autoApprove,
@@ -917,34 +882,37 @@ export class GraphLoader {
                     tryAddLoadedTool(definitions, byName, def);
                 }
             }
-            // 2) Graph 声明但尚未命中的工具名：按名直查。
-            //    已在步骤 1 处理过的工具集名不再二次展开（避免丢掉 enabledTools 白名单）。
-            for (const toolName of toolNames) {
-                if (byName.has(toolName))
-                    continue;
-                if (processedToolsetNames.has(toolName))
-                    continue;
-                const pre = await this.deploymentSnapshot.loadToolManifest({ name: toolName }, agentDir);
-                if (!pre) {
-                    // MCP 子工具名在 tools/list 后才出现，图内 type:tool 节点不必对应预装目录
-                    if (definitions.some(isMcpDiscoverStub))
-                        continue;
-                    missing.push(toolName);
+            if (this.strictPreinstall && missing.length > 0) {
+                throw preloadToolNotFound(`预装快照缺失 Tool: ${missing.join(', ')}（agent=${agentCode}）`, { missing, agentCode });
+            }
+        }
+        const pendingRefs = pendingToolRefs(snapToolRefs, loadedRefNames, new Set(byName.keys()), agent?.manifest?.tools);
+        if (process.env.EAP_LLM_DEBUG === '1') {
+            console.log('[LLM-DEBUG] toolRefs:', JSON.stringify({
+                fromSnap: snapToolRefs.map((t) => t.name),
+                pending: pendingRefs.map((t) => t.name),
+            }));
+        }
+        if (this.deploymentContext === 'dev') {
+            const toolsDir = this.localToolsDir ?? process.env.EAP_LOCAL_TOOLS_DIR ?? './tools';
+            for (const ref of pendingRefs) {
+                const localDefs = await loadDevLocalToolset(ref.name, toolsDir, {
+                    enabledTools: ref.enabledTools,
+                    autoApprove: ref.autoApprove,
+                });
+                if (!localDefs)
                     continue;
-                }
-                for (const def of expandPreinstallToolset(pre)) {
+                loadedRefNames.add(ref.name);
+                for (const def of localDefs) {
                     tryAddLoadedTool(definitions, byName, def);
                 }
             }
-            if (this.strictPreinstall && missing.length > 0) {
-                throw preloadToolNotFound(`预装快照缺失 Tool: ${missing.join(', ')}（agent=${agentCode}）`, { missing, agentCode });
-            }
         }
         if (this.registryClient && !this.blockRegistryDefinitions) {
-            for (const toolName of toolNames) {
-                if (byName.has(toolName))
+            for (const ref of pendingRefs) {
+                if (loadedRefNames.has(ref.name) || byName.has(ref.name))
                     continue;
-                const record = await this.registryClient.getToolByName(toolName);
+                const record = await this.registryClient.getToolByName(ref.name);
                 if (!record)
                     continue;
                 if (activeOnly && record.status !== 'active')
@@ -952,17 +920,6 @@ export class GraphLoader {
                 tryAddLoadedTool(definitions, byName, toLoadedToolDefinition(record));
             }
         }
-        if (this.deploymentContext === 'dev') {
-            const toolsDir = this.localToolsDir ?? process.env.EAP_LOCAL_TOOLS_DIR ?? './tools';
-            for (const toolName of toolNames) {
-                if (byName.has(toolName))
-                    continue;
-                const localDef = await loadDevLocalManifest(toolName, toolsDir);
-                if (localDef) {
-                    tryAddLoadedTool(definitions, byName, localDef);
-                }
-            }
-        }
         if (this.deploymentContext === 'desktop' && this.localInstallStore) {
             const localRecords = this.localInstallStore.listReady();
             for (const install of localRecords) {

package/dist/tool/tool-confirmation.js

@@ -71,6 +71,8 @@ export class ToolConfirmationInterceptor {
             toolSpanId: extras.toolSpanId,
             skillSpanId: extras.skillSpanId ??
                 (typeof state.skillSpanId === 'string' ? state.skillSpanId : undefined),
+            llmSpanId: extras.llmSpanId ??
+                (typeof state.llmSpanId === 'string' ? state.llmSpanId : undefined),
         };
         await this.hitlHandler.interrupt(taskId, resolvedThreadId, state, {
             question,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gt-fe/eap-runtime",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "description": "Enterprise Agent Platform — Runtime核心：Graph执行引擎、Task生命周期、Session管理、Checkpoint持久化",
   "type": "module",
   "main": "dist/index.js",