@gt-fe/eap-runtime 0.0.31 → 0.0.32

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

@@ -34,8 +34,8 @@ import { preloadSkillNotFound } from '../../registry/preload-errors.js';
 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 { classifySkillFile, isReadTool } from './skill-read.js';
+import { recordSkillEntrySpan, skillEntryInvocationFromTool } from './skill-entry-span.js';
 import { llmSpanInput, llmSpanOutputFromResult, withGraphSpan } from '../trace-span.js';
 import { executionTraceFromState, getExecutionStream, getExecutionTrace, runWithExecutionTrace, } from '../execution-trace-context.js';
 import { isRetryableToolFailure, resolveToolRetryConfig, sleepToolRetry, toolRetryDelayMs, } from '../../tool/tool-retry.js';
@@ -283,8 +283,10 @@ export class LangGraphAdapter {
             ...(progress.node ? { node: progress.node } : {}),
             ...(progress.skillId ? { skillId: progress.skillId } : {}),
         };
-        const skillRead = classifySkillRead(progress.toolName, progress.arguments, progress.skillDirs);
-        if (skillRead && progress.status === 'completed') {
+        const skillRead = progress.status === 'completed' && progress.resolvedPath && isReadTool(progress.toolName)
+            ? classifySkillFile(progress.resolvedPath, progress.skillDirs)
+            : null;
+        if (skillRead) {
             if (skillRead.kind === 'loaded') {
                 const skillId = skillRead.skillId || loc.skillId || skillRead.path;
                 stream.sink({
@@ -299,7 +301,7 @@ export class LangGraphAdapter {
                 });
                 const catalogSkill = skillEntryInvocationFromTool({
                     toolName: progress.toolName,
-                    arguments: progress.arguments,
+                    resolvedPath: progress.resolvedPath,
                     skillDirs: progress.skillDirs,
                     alreadyInSkillSpan: progress.inSkillSubgraph,
                 });
@@ -355,12 +357,14 @@ export class LangGraphAdapter {
                 },
             });
         }
+        // resolvedPath / skillDirs 只给上面 classifySkillFile；inSkillSubgraph 只给 skill.started 去重。不进对话流。
+        const { resolvedPath: _resolvedPath, skillDirs: _skillDirs, inSkillSubgraph: _inSkillSubgraph, ...progressView } = progress;
         stream.sink({
             type: 'tool.progress',
             taskId,
             correlationId,
             timestamp,
-            payload: { ...progress },
+            payload: progressView,
         });
         if (progress.status === 'completed') {
             stream.sink({
@@ -936,6 +940,13 @@ export class LangGraphAdapter {
                     node: node.id,
                 });
                 const skillDefs = state['skillDefinitions'];
+                const jail = resolveJailFromState({
+                    agentDir: state['agentDir'],
+                    userId: state['userId'],
+                    executionContext: state['executionContext'],
+                    loadedTools: state['loadedTools'],
+                    skillDefinitions: skillDefs,
+                });
                 const jailExtraRoots = Object.values(skillDefs ?? {})
                     .map((skill) => skill.bundlePath)
                     .filter((p) => Boolean(p));
@@ -946,6 +957,7 @@ export class LangGraphAdapter {
                     authContext: { userId, delegationToken, agentCode },
                     correlationId,
                     taskId,
+                    ...(jail.workdir ? { jailWorkdir: jail.workdir } : {}),
                     ...(jailExtraRoots.length > 0 ? { jailExtraRoots } : {}),
                 };
                 const retry = resolveToolRetryConfig(node.retry);
@@ -981,13 +993,21 @@ export class LangGraphAdapter {
                     executionTime,
                     node: node.id,
                     ...(skillDirs.length > 0 ? { skillDirs } : {}),
+                    ...(result.resolvedPath ? { resolvedPath: result.resolvedPath } : {}),
                 });
+                if (result.success) {
+                    await recordSkillEntrySpan(state, {
+                        toolName: result.toolName,
+                        resolvedPath: result.resolvedPath,
+                        skillDirs,
+                    });
+                }
                 // 重要：messages channel 的 reducer 是 append 语义，只返回新增消息
                 return {
                     messages: [
                         {
                             role: 'tool',
-                            content: result.content || JSON.stringify(result),
+                            content: result.content ?? '',
                             toolCallId,
                             toolName,
                             success: result.success ?? true,

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

@@ -2,6 +2,8 @@
  * 成功读 SKILL.md 时写 Trace `type=skill` Span。
  *
  * 假设：Skill 被调用 = 一次成功读取技能包入口（SKILL.md），
+ * 入口是执行器返回的实际文件（resolvedPath）对已装配 skillDirs。
+ * 没有实际路径不记，不再用 arguments.path 猜。
  * 与子图激活走同一 collector.createNode({ type: 'skill' })。
  * 声明版本在 createNode.version；skillSpace 只在 input。
  * 子图已有 skillSpanId 时不记第二条。write_file / 包内附属读 / 失败读不是调用。
@@ -23,7 +25,7 @@ export declare function skillSpanFields(identity: SkillTraceIdentity, extra?: {
 };
 export declare function skillEntryInvocationFromTool(input: {
     toolName: string;
-    arguments?: Record<string, unknown>;
+    resolvedPath?: string;
     skillDirs?: SkillDirRef[];
     alreadyInSkillSpan?: boolean;
 }): {
@@ -32,6 +34,6 @@ export declare function skillEntryInvocationFromTool(input: {
 } | null;
 export declare function recordSkillEntrySpan(state: Record<string, unknown>, input: {
     toolName: string;
-    arguments?: Record<string, unknown>;
+    resolvedPath?: string;
     skillDirs?: SkillDirRef[];
 }): Promise<void>;

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

@@ -2,11 +2,13 @@
  * 成功读 SKILL.md 时写 Trace `type=skill` Span。
  *
  * 假设：Skill 被调用 = 一次成功读取技能包入口（SKILL.md），
+ * 入口是执行器返回的实际文件（resolvedPath）对已装配 skillDirs。
+ * 没有实际路径不记，不再用 arguments.path 猜。
  * 与子图激活走同一 collector.createNode({ type: 'skill' })。
  * 声明版本在 createNode.version；skillSpace 只在 input。
  * 子图已有 skillSpanId 时不记第二条。write_file / 包内附属读 / 失败读不是调用。
  */
-import { classifySkillRead, classifySkillSpace } from './skill-read.js';
+import { classifySkillFile, classifySkillSpace, isReadTool, } from './skill-read.js';
 import { completeGraphSpan, startGraphSpan } from '../trace-span.js';
 function declaredSkillVersion(skillId, version) {
     const raw = version?.trim();
@@ -46,7 +48,12 @@ export function skillSpanFields(identity, extra) {
 export function skillEntryInvocationFromTool(input) {
     if (input.alreadyInSkillSpan)
         return null;
-    const hit = classifySkillRead(input.toolName, input.arguments, input.skillDirs);
+    if (!isReadTool(input.toolName))
+        return null;
+    const resolved = input.resolvedPath?.trim();
+    if (!resolved)
+        return null;
+    const hit = classifySkillFile(resolved, input.skillDirs);
     if (!hit || hit.kind !== 'loaded' || !hit.skillId)
         return null;
     return { skillId: hit.skillId, path: hit.path };
@@ -55,7 +62,7 @@ export async function recordSkillEntrySpan(state, input) {
     const alreadyInSkillSpan = typeof state['skillSpanId'] === 'string' && Boolean(state['skillSpanId']);
     const hit = skillEntryInvocationFromTool({
         toolName: input.toolName,
-        arguments: input.arguments,
+        resolvedPath: input.resolvedPath,
         skillDirs: input.skillDirs,
         alreadyInSkillSpan,
     });

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

@@ -12,10 +12,26 @@ export declare function classifySkillSpace(bundleOrFilePath: string, opts?: {
     agentDir?: string;
     userId?: string;
 }): SkillSpace | undefined;
+/** 与 Harness `read_file` 相同的相对路径定位（workdir / skillDir / overlay extraRoots）。 */
+export interface SkillReadLocate {
+    workdir?: string;
+    skillDir?: string;
+    extraRoots?: string[];
+}
+export declare function isReadTool(toolName: string): boolean;
+/**
+ * 实际读到的文件是否落在已装配技能包内。不解析定位符。
+ */
+export declare function classifySkillFile(absPath: string, skillDirs?: SkillDirRef[]): {
+    kind: 'loaded' | 'resource';
+    path: string;
+    skillId: string;
+} | null;
 /**
- * 判断 harness 读操作是否命中技能包，并用 bundlePath 最长前缀解析 skillId。
+ * 给 EAP_SKILL_DIR 推断：把 `arguments.path` 按 Harness 规则落到文件再对 skillDirs。
+ * Trace / SSE 入口判定走 `classifySkillFile`（实际读到的文件），不走这里。
  */
-export declare function classifySkillRead(toolName: string, args: Record<string, unknown> | undefined, skillDirs?: SkillDirRef[]): {
+export declare function classifySkillRead(toolName: string, args: Record<string, unknown> | undefined, skillDirs?: SkillDirRef[], locate?: SkillReadLocate): {
     kind: 'loaded' | 'resource';
     path: string;
     skillId: string;

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

@@ -1,6 +1,7 @@
 import { realpathSync } from 'node:fs';
 import path from 'node:path';
 import { userRoot } from '../../common/user-root.js';
+import { resolveSkillReadTarget } from '../../tool/skill-relative-read.js';
 function tryRealpath(p) {
     try {
         return realpathSync(p);
@@ -30,10 +31,6 @@ function longestSkillMatch(filePath, skillDirs) {
     }
     return best;
 }
-function skillIdFromSkillsSegment(norm) {
-    const match = norm.match(/(?:^|\/)(?:preinstall\/)?skills\/([^/]+)(?:\/|$)/i);
-    return match?.[1] ?? '';
-}
 /**
  * 按实际 bundle 路径判定空间。有 agentDir 时相对预装根与 users/ 判定；
  * 否则看路径段 `preinstall/skills` / `users/<id>/skills`。
@@ -72,34 +69,63 @@ export function classifySkillSpace(bundleOrFilePath, opts) {
         return 'user';
     return undefined;
 }
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+function extraRootsForSkillRead(skillDirs, locate) {
+    const out = [];
+    for (const dir of skillDirs ?? []) {
+        if (dir.bundlePath)
+            out.push(dir.bundlePath);
+    }
+    for (const root of locate?.extraRoots ?? []) {
+        if (root)
+            out.push(root);
+    }
+    return out;
+}
+export function isReadTool(toolName) {
+    const n = toolName.toLowerCase().replace(/-/g, '_');
+    return n === 'read_file' || n === 'read_skill_file' || n === 'readfile';
 }
 /**
- * 判断 harness 读操作是否命中技能包，并用 bundlePath 最长前缀解析 skillId。
+ * 实际读到的文件是否落在已装配技能包内。不解析定位符。
  */
-export function classifySkillRead(toolName, args, skillDirs) {
-    const n = toolName.toLowerCase().replace(/-/g, '_');
-    if (n !== 'read_file' && n !== 'read_skill_file' && n !== 'readfile')
+export function classifySkillFile(absPath, skillDirs) {
+    const trimmed = absPath.trim();
+    if (!trimmed)
+        return null;
+    const matched = longestSkillMatch(trimmed, skillDirs);
+    if (!matched)
+        return null;
+    const resolved = normalizeForMatch(trimmed);
+    const isEntry = /(^|\/)(SKILL\.md|skill.md)$/i.test(resolved);
+    return {
+        kind: isEntry ? 'loaded' : 'resource',
+        path: resolved,
+        skillId: matched.skillId,
+    };
+}
+/**
+ * 给 EAP_SKILL_DIR 推断：把 `arguments.path` 按 Harness 规则落到文件再对 skillDirs。
+ * Trace / SSE 入口判定走 `classifySkillFile`（实际读到的文件），不走这里。
+ */
+export function classifySkillRead(toolName, args, skillDirs, locate) {
+    if (!isReadTool(toolName))
         return null;
     const filePath = String(args?.path ?? args?.file ?? '');
     if (!filePath)
         return null;
-    const norm = filePath.replace(/\\/g, '/');
-    const matched = longestSkillMatch(filePath, skillDirs);
-    const isEntry = /(^|\/)(SKILL\.md|skill\.md)$/i.test(norm);
-    if (matched) {
-        return {
-            kind: isEntry ? 'loaded' : 'resource',
-            path: filePath,
-            skillId: matched.skillId,
-        };
-    }
-    if (isEntry) {
-        return { kind: 'loaded', path: filePath, skillId: skillIdFromSkillsSegment(norm) };
-    }
-    if (/(^|\/)(?:preinstall\/)?skills\//i.test(norm)) {
-        return { kind: 'resource', path: filePath, skillId: skillIdFromSkillsSegment(norm) };
-    }
-    return null;
+    const target = resolveSkillReadTarget(filePath, {
+        workdir: locate?.workdir,
+        skillDir: locate?.skillDir,
+        extraRoots: extraRootsForSkillRead(skillDirs, locate),
+    });
+    const matched = longestSkillMatch(target, skillDirs);
+    if (!matched)
+        return null;
+    const slash = target.replace(/\\/g, '/');
+    const isEntry = /(^|\/)(SKILL\.md|skill.md)$/i.test(slash);
+    return {
+        kind: isEntry ? 'loaded' : 'resource',
+        path: target,
+        skillId: matched.skillId,
+    };
 }

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

@@ -48,6 +48,8 @@ export interface ToolNodeProgress {
     node?: string;
     skillId?: string;
     skillDirs?: SkillDirRef[];
+    /** read_file 实际读到的文件；与 ToolCallResult.resolvedPath 相同 */
+    resolvedPath?: string;
     /** 已在 Skill 子图内（state.skillSpanId）；读 SKILL.md 不再发 skill.started */
     inSkillSubgraph?: boolean;
     skillSpace?: 'agent' | 'user' | 'local';

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

@@ -295,7 +295,7 @@ export class ToolNode {
                 if (result.success) {
                     const catalog = skillEntryInvocationFromTool({
                         toolName: req.toolName,
-                        arguments: req.arguments,
+                        resolvedPath: result.resolvedPath,
                         skillDirs,
                         alreadyInSkillSpan: inSkillSubgraph,
                     });
@@ -312,6 +312,7 @@ export class ToolNode {
                         content: result.content,
                         ...toolArtifactFields(result),
                         executionTime,
+                        ...(result.resolvedPath ? { resolvedPath: result.resolvedPath } : {}),
                         ...(skillIdentity?.skillSpace ? { skillSpace: skillIdentity.skillSpace } : {}),
                         ...(skillIdentity?.skillVersion ? { skillVersion: skillIdentity.skillVersion } : {}),
                         ...(skillIdentity?.skillName ? { skillName: skillIdentity.skillName } : {}),
@@ -346,7 +347,7 @@ export class ToolNode {
                 if (result.success) {
                     await recordSkillEntrySpan(state, {
                         toolName: req.toolName,
-                        arguments: req.arguments,
+                        resolvedPath: result.resolvedPath,
                         skillDirs,
                     });
                 }

package/dist/tool/harness-primitives.d.ts

@@ -9,6 +9,7 @@
  * `createToolExecutor` 时钉进执行器 extraRoots；SDK `createAgent` 构造完会恢复 process.env，
  * 请求时不再读这两项。相对 `read_file` 会把 overlay 根下直接子目录里带 SKILL.md 的包纳入唯一命中。
  */
+export { locateSkillRelativeRead } from './skill-relative-read.js';
 import type { LoadedToolMap } from './loaded-tool-definition.js';
 import type { IToolExecutor, ToolCallRequest, ToolCallResult } from './tool-executor.interface.js';
 export declare function mergeHarnessPrimitives(loadedTools: LoadedToolMap | undefined): LoadedToolMap | undefined;
@@ -42,13 +43,6 @@ export declare function captureOverlayJailOptions(env?: NodeJS.ProcessEnv): Pick
 export declare function resolveJailRoots(options?: HarnessJailOptions): string[];
 /** 路径落在写根外的 extraRoot 时，返回该 extraRoot。 */
 export declare function extraRootContaining(abs: string, extraRoots: string[], workdir: string): string | undefined;
-/**
- * 相对 read_file：`技能名/文件`、全库唯一命中、显式 skillDir，否则用户目录。
- */
-export declare function locateSkillRelativeRead(filePath: string, workdir: string | undefined, skillDir: string | undefined, extraRoots?: string[]): {
-    path: string;
-    relativeBase: string | undefined;
-};
 export declare function resolveJailedPath(requested: string, roots: string[], opts?: {
     mustExist?: boolean;
     relativeBase?: string;

package/dist/tool/harness-primitives.js

@@ -10,10 +10,12 @@
  * 请求时不再读这两项。相对 `read_file` 会把 overlay 根下直接子目录里带 SKILL.md 的包纳入唯一命中。
  */
 import { spawn } from 'node:child_process';
-import { constants as fsConstants, existsSync, readdirSync, realpathSync } from 'node:fs';
+import { constants as fsConstants, realpathSync } from 'node:fs';
 import { chmod, mkdir, open, readFile, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { MISSING_USER_DIR, userRoot } from '../common/user-root.js';
+import { locateSkillRelativeRead, userReadBase } from './skill-relative-read.js';
+export { locateSkillRelativeRead } from './skill-relative-read.js';
 import { MAX_SNAPSHOT_ENUM, MAX_SNAPSHOT_URLS, PUBLIC_FILE_MODE, ensureUserSlots, maxWriteBytesFromEnv, publishFromFiles, resolveUserProductPath, snapshotCandidates, walkFilesTree, } from './static-artifact-url.js';
 import { BUILTIN_TOOL_SOURCE, DEFAULT_BUILTIN_TIMEOUT_MS, MAX_BUILTIN_TIMEOUT_MS, clampBuiltinTimeout, isBuiltinToolExecution, resolveBuiltinToolsConfig, } from '@gt-fe/eap-contracts';
 import { ensureInterpreterShims, formatSpawnError, killProcessTree, resolveShellSpawn, sandboxEnv, spawnOptionsFor, substituteSkillDir, } from './harness-command.js';
@@ -316,74 +318,6 @@ function resolveViaExistingAncestor(abs) {
         cur = parent;
     }
 }
-function userReadBase(workdir) {
-    return workdir?.trim()
-        ? (tryRealpath(path.resolve(workdir)) ?? path.resolve(workdir))
-        : undefined;
-}
-function isSkillPackageDir(dir) {
-    return existsSync(path.join(dir, 'SKILL.md')) || existsSync(path.join(dir, 'skill.md'));
-}
-function skillPackageRoots(roots) {
-    const out = [];
-    const seen = new Set();
-    const add = (dir) => {
-        if (seen.has(dir))
-            return;
-        seen.add(dir);
-        out.push(dir);
-    };
-    for (const root of roots) {
-        const resolved = path.resolve(root);
-        if (isSkillPackageDir(resolved)) {
-            add(resolved);
-            continue;
-        }
-        let entries;
-        try {
-            entries = readdirSync(resolved, { withFileTypes: true });
-        }
-        catch {
-            continue;
-        }
-        for (const ent of entries) {
-            if (!ent.isDirectory())
-                continue;
-            const child = path.join(resolved, ent.name);
-            if (isSkillPackageDir(child))
-                add(child);
-        }
-    }
-    return out;
-}
-/**
- * 相对 read_file：`技能名/文件`、全库唯一命中、显式 skillDir，否则用户目录。
- */
-export function locateSkillRelativeRead(filePath, workdir, skillDir, extraRoots) {
-    const trimmed = filePath.trim();
-    const userBase = userReadBase(workdir);
-    if (!trimmed || path.isAbsolute(trimmed))
-        return { path: trimmed, relativeBase: userBase };
-    const packages = skillPackageRoots([
-        ...(skillDir?.trim() ? [skillDir] : []),
-        ...(extraRoots ?? []),
-    ]);
-    const slash = trimmed.replace(/\\/g, '/');
-    const segs = slash.split('/').filter(Boolean);
-    if (segs.length >= 2) {
-        const hit = packages.find((pkg) => path.basename(pkg) === segs[0]);
-        if (hit)
-            return { path: segs.slice(1).join('/'), relativeBase: hit };
-    }
-    const matches = packages.filter((pkg) => existsSync(path.resolve(pkg, trimmed)));
-    if (matches.length === 1)
-        return { path: trimmed, relativeBase: matches[0] };
-    const skillBase = skillDir?.trim() ? path.resolve(skillDir) : undefined;
-    if (skillBase && existsSync(path.resolve(skillBase, trimmed))) {
-        return { path: trimmed, relativeBase: skillBase };
-    }
-    return { path: trimmed, relativeBase: userBase };
-}
 export function resolveJailedPath(requested, roots, opts) {
     const trimmed = requested.trim();
     if (!trimmed || trimmed.includes('\0')) {
@@ -530,7 +464,7 @@ export class HarnessPrimitiveExecutor {
         if (isSkillEntryFile(target)) {
             text = expandSkillScriptRefs(text, path.dirname(target));
         }
-        return ok(request, text);
+        return { ...ok(request, text), resolvedPath: target };
     }
     async writeFile(request, append) {
         const filePath = String(request.arguments.path ?? '');

package/dist/tool/skill-relative-read.d.ts

@@ -0,0 +1,14 @@
+export declare function userReadBase(workdir: string | undefined): string | undefined;
+/**
+ * 相对 read_file：`技能名/文件`、全库唯一命中、显式 skillDir，否则用户目录。
+ */
+export declare function locateSkillRelativeRead(filePath: string, workdir: string | undefined, skillDir: string | undefined, extraRoots?: string[]): {
+    path: string;
+    relativeBase: string | undefined;
+};
+/** 定位符落到实际文件：绝对路径原样；相对路径按 locateSkillRelativeRead 的包根拼接。 */
+export declare function resolveSkillReadTarget(filePath: string, opts?: {
+    workdir?: string;
+    skillDir?: string;
+    extraRoots?: string[];
+}): string;

package/dist/tool/skill-relative-read.js

@@ -0,0 +1,98 @@
+/**
+ * read_file 相对路径如何落到技能包：Harness 读文件与 Trace 判定入口共用。
+ */
+import { existsSync, readdirSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+function tryRealpath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function userReadBase(workdir) {
+    return workdir?.trim()
+        ? (tryRealpath(path.resolve(workdir)) ?? path.resolve(workdir))
+        : undefined;
+}
+function isSkillPackageDir(dir) {
+    return existsSync(path.join(dir, 'SKILL.md')) || existsSync(path.join(dir, 'skill.md'));
+}
+function skillPackageRoots(roots) {
+    const out = [];
+    const seen = new Set();
+    const add = (dir) => {
+        if (seen.has(dir))
+            return;
+        seen.add(dir);
+        out.push(dir);
+    };
+    for (const root of roots) {
+        const resolved = path.resolve(root);
+        if (isSkillPackageDir(resolved)) {
+            add(resolved);
+            continue;
+        }
+        let entries;
+        try {
+            entries = readdirSync(resolved, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const ent of entries) {
+            if (!ent.isDirectory())
+                continue;
+            const child = path.join(resolved, ent.name);
+            if (isSkillPackageDir(child))
+                add(child);
+        }
+    }
+    return out;
+}
+/**
+ * 相对 read_file：`技能名/文件`、全库唯一命中、显式 skillDir，否则用户目录。
+ */
+export function locateSkillRelativeRead(filePath, workdir, skillDir, extraRoots) {
+    const trimmed = filePath.trim();
+    const userBase = userReadBase(workdir);
+    if (!trimmed || path.isAbsolute(trimmed))
+        return { path: trimmed, relativeBase: userBase };
+    const packages = skillPackageRoots([
+        ...(skillDir?.trim() ? [skillDir] : []),
+        ...(extraRoots ?? []),
+    ]);
+    const slash = trimmed.replace(/\\/g, '/');
+    const segs = slash.split('/').filter(Boolean);
+    if (segs.length >= 2) {
+        const hit = packages.find((pkg) => path.basename(pkg) === segs[0]);
+        if (hit)
+            return { path: segs.slice(1).join('/'), relativeBase: hit };
+    }
+    const matches = packages.filter((pkg) => existsSync(path.resolve(pkg, trimmed)));
+    if (matches.length === 1)
+        return { path: trimmed, relativeBase: matches[0] };
+    const skillBase = skillDir?.trim() ? path.resolve(skillDir) : undefined;
+    if (skillBase && existsSync(path.resolve(skillBase, trimmed))) {
+        return { path: trimmed, relativeBase: skillBase };
+    }
+    return { path: trimmed, relativeBase: userBase };
+}
+/** 定位符落到实际文件：绝对路径原样；相对路径按 locateSkillRelativeRead 的包根拼接。 */
+export function resolveSkillReadTarget(filePath, opts) {
+    const trimmed = filePath.trim();
+    if (!trimmed)
+        return '';
+    const located = locateSkillRelativeRead(trimmed, opts?.workdir, opts?.skillDir, opts?.extraRoots);
+    if (path.isAbsolute(trimmed)) {
+        const resolved = path.resolve(trimmed);
+        return (tryRealpath(resolved) ?? resolved).replace(/\\/g, '/').replace(/\/+$/, '');
+    }
+    if (located.relativeBase) {
+        const resolved = path.resolve(located.relativeBase, located.path);
+        return (tryRealpath(resolved) ?? resolved).replace(/\\/g, '/').replace(/\/+$/, '');
+    }
+    const resolved = path.resolve(trimmed);
+    return (tryRealpath(resolved) ?? resolved).replace(/\\/g, '/').replace(/\/+$/, '');
+}

package/dist/tool/tool-executor.interface.d.ts

@@ -122,6 +122,11 @@ export interface ToolCallResult {
         size: number;
         url: string;
     }>;
+    /**
+     * `read_file` 实际读到的文件。只给 Runtime 记 Skill 节点 / SSE，不进模型正文。
+     * 没有该字段时不记 Skill 节点，不再用 `arguments.path` 猜。
+     */
+    resolvedPath?: string;
 }
 export interface LLMToolCall {
     id: string;

package/package.json

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