@gt-fe/eap-runtime 0.0.31 → 0.0.33

package/dist/api/handlers/invoke.handler.js

@@ -27,7 +27,7 @@ import { classifyRuntimeError } from '../../utils/http-error.js';
 import { DEFAULT_GRAPH_TIMEOUT_MS } from '../../common/types.js';
 import { resolveTaskTimeoutMs } from '../../task/resolve-task-timeout.js';
 import { runWithExecutionTrace } from '../../graph/execution-trace-context.js';
-import { resolveAgentSystemPromptFromLoader } from '../../registry/graph-loader.js';
+import { resolveAgentDisplayNameFromLoader, resolveAgentSystemPromptFromLoader, } from '../../registry/graph-loader.js';
 import { toLoadedToolMap } from '../../tool/loaded-tool-definition.js';
 import { toLoadedSkillMap } from '../../tool/system-prompt-builder.js';
 import { assembleLoadedTools } from '../../tool/harness-primitives.js';
@@ -204,6 +204,7 @@ export class InvokeOrchestrator {
                 ? (await this.graphLoader.resolveAgentDir(agentCode, req.agentVersion)) ?? undefined
                 : undefined;
             const agentSystemPrompt = await resolveAgentSystemPromptFromLoader(this.graphLoader, agentCode, req.agentVersion);
+            const agentName = await resolveAgentDisplayNameFromLoader(this.graphLoader, agentCode, req.agentVersion);
             // 模型上下文：Checkpoint 已有 messages 则压它；压成功用 __set 写回最新 Checkpoint。Message 库不改。
             const facing = await loadModelFacingHistory({
                 sessionHistory: messageRecordsToGraphMessages(sessionContext.messages),
@@ -261,6 +262,7 @@ export class InvokeOrchestrator {
                 promptRoots,
                 agentDir,
                 agentSystemPrompt,
+                agentName,
                 traceId: resolveTraceId(req),
                 traceCollector: this.traceCollector,
                 abortSignal,

package/dist/api/handlers/stream.handler.js

@@ -31,7 +31,7 @@ import { SSEEmitter } from '../../sse/sse-emitter.js';
 import { resolveExecutionContext } from '../../governance/governance-client.js';
 import { resolveSkillInputFromInvokeInput } from '../../registry/skill-io-guard.js';
 import { ErrorCodes } from '@gt-fe/eap-contracts';
-import { resolveAgentSystemPromptFromLoader } from '../../registry/graph-loader.js';
+import { resolveAgentDisplayNameFromLoader, resolveAgentSystemPromptFromLoader, } from '../../registry/graph-loader.js';
 import { classifyRuntimeError } from '../../utils/http-error.js';
 import { toLoadedToolMap } from '../../tool/loaded-tool-definition.js';
 import { toLoadedSkillMap } from '../../tool/system-prompt-builder.js';
@@ -222,6 +222,7 @@ export class StreamOrchestrator {
             ? (await this.graphLoader.resolveAgentDir(agentCode, req.agentVersion)) ?? undefined
             : undefined;
         const agentSystemPrompt = await resolveAgentSystemPromptFromLoader(this.graphLoader, agentCode, req.agentVersion);
+        const agentName = await resolveAgentDisplayNameFromLoader(this.graphLoader, agentCode, req.agentVersion);
         // 模型上下文：Checkpoint 已有 messages 则压它；压成功用 __set 写回最新 Checkpoint。Message 库不改。
         const facing = await loadModelFacingHistory({
             sessionHistory: messageRecordsToGraphMessages(sessionContext.messages),
@@ -293,6 +294,7 @@ export class StreamOrchestrator {
                 promptRoots,
                 agentDir,
                 agentSystemPrompt,
+                agentName,
                 traceId: resolveTraceId(req),
                 traceCollector: this.traceCollector,
                 abortSignal,

package/dist/graph/adapters/langgraph.adapter.d.ts

@@ -127,7 +127,6 @@ export declare class LangGraphAdapter implements IStateGraphEngine {
     private createNodeFunction;
     private createNodeFunctionBody;
     private createSkillBindNodeFunction;
-    private buildSkillCatalog;
     private createToolNodeFunction;
     private createLLMNodeFunction;
     /**

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

@@ -23,7 +23,7 @@ import { ToolResultInjector } from '../../tool/tool-result-injector.js';
 import { fileArtifactFromToolOutput } from '../../tool/file-artifact.js';
 import { EchoLLMProvider } from '../../providers/echo-llm-provider.js';
 import { ConditionEvaluator } from '../condition-evaluator.js';
-import { SystemPromptBuilder, buildToolCatalog, loadedToolsToApiTools, resolveLlmPromptInputs } from '../../tool/system-prompt-builder.js';
+import { SystemPromptBuilder, buildSkillCatalog, buildToolCatalog, loadedToolsToApiTools, resolveLlmPromptInputs, spokenName } from '../../tool/system-prompt-builder.js';
 import { resolveJailFromState, resolveJailRoots } from '../../tool/harness-primitives.js';
 import os from 'node:os';
 import { bindSelectedSkill } from '../nodes/skill-bind-node.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,11 +301,12 @@ export class LangGraphAdapter {
                 });
                 const catalogSkill = skillEntryInvocationFromTool({
                     toolName: progress.toolName,
-                    arguments: progress.arguments,
+                    resolvedPath: progress.resolvedPath,
                     skillDirs: progress.skillDirs,
                     alreadyInSkillSpan: progress.inSkillSubgraph,
                 });
                 if (catalogSkill) {
+                    const skillName = spokenName(progress.skillName, catalogSkill.skillId) ?? catalogSkill.skillId;
                     stream.sink({
                         type: 'skill.started',
                         taskId,
@@ -311,7 +314,7 @@ export class LangGraphAdapter {
                         timestamp,
                         payload: {
                             skillId: catalogSkill.skillId,
-                            skillName: progress.skillName || catalogSkill.skillId,
+                            skillName,
                             path: catalogSkill.path,
                             ...(progress.skillSpace ? { skillSpace: progress.skillSpace } : {}),
                             ...(progress.skillVersion ? { skillVersion: progress.skillVersion } : {}),
@@ -324,7 +327,7 @@ export class LangGraphAdapter {
                         timestamp,
                         payload: {
                             skillId: catalogSkill.skillId,
-                            skillName: catalogSkill.skillId,
+                            skillName,
                         },
                     });
                 }
@@ -355,12 +358,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({
@@ -456,6 +461,7 @@ export class LangGraphAdapter {
                 // agentId 已废弃：channel 保留仅为旧 Checkpoint 反序列化兼容，新代码只写 agentCode
                 agentId: ephemeral(''),
                 agentCode: ephemeral(''),
+                agentName: ephemeral(undefined),
                 agentVersion: ephemeral(undefined),
                 delegationToken: ephemeral(''),
                 correlationId: ephemeral(''),
@@ -852,7 +858,7 @@ export class LangGraphAdapter {
                     correlationId: undefined,
                     timestamp: new Date().toISOString(),
                     payload: {
-                        skillName: patch.skillName || patch.activatedSkill,
+                        skillName: spokenName(patch.skillName, patch.activatedSkill) ?? patch.activatedSkill,
                         skillId: patch.activatedSkill,
                         confidence: 1,
                     },
@@ -894,20 +900,6 @@ export class LangGraphAdapter {
             };
         };
     }
-    buildSkillCatalog(defs) {
-        if (!defs)
-            return undefined;
-        const rows = Object.values(defs).map((skill) => {
-            const desc = (skill.description ?? '').replace(/\s+/g, ' ').trim();
-            const entry = skill.entryFile ?? (skill.bundlePath ? `${skill.bundlePath}/SKILL.md` : '');
-            const title = skill.name && skill.name !== skill.skillId ? `${skill.skillId}（${skill.name}）` : skill.skillId;
-            const pathLine = entry ? `\n  SKILL.md: ${entry}` : '';
-            return `- **${title}**${desc ? `：${desc}` : ''}${pathLine}`;
-        });
-        if (rows.length === 0)
-            return undefined;
-        return `# 可用技能\n要用某个技能时，调用 read_file 读取其 SKILL.md。脚本和参考文档默认在同一目录。\n${rows.join('\n')}`;
-    }
     createToolNodeFunction(node) {
         const toolName = node.config?.['tool'] ?? node.id;
         const defaultArgs = node.config?.['arguments'] ?? {};
@@ -936,6 +928,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 +945,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 +981,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,
@@ -1041,6 +1049,7 @@ export class LangGraphAdapter {
             const resolvedPrompt = resolveGraphPrompt(baseConfig.systemPrompt, promptRoots);
             const loadedToolsBase = state['loadedTools'];
             const agentCode = typeof state['agentCode'] === 'string' ? state['agentCode'] : undefined;
+            const agentName = typeof state['agentName'] === 'string' ? state['agentName'] : undefined;
             const skillDefs = state['skillDefinitions'];
             const execCtx = state['executionContext'];
             const userId = (typeof execCtx?.userId === 'string' && execCtx.userId) || state['userId'];
@@ -1072,7 +1081,7 @@ export class LangGraphAdapter {
                 const toolNames = loadedTools ? Object.keys(loadedTools) : [];
                 console.log(`[LLM-DEBUG] node=${node.id} loadedTools=${toolNames.length}:`, toolNames);
             }
-            const catalog = includeSkillCatalog ? this.buildSkillCatalog(skillDefs) : undefined;
+            const catalog = includeSkillCatalog ? buildSkillCatalog(skillDefs) : undefined;
             const toolCatalog = disableTools ? undefined : buildToolCatalog(loadedTools);
             const jail = resolveJailFromState({
                 agentDir: state['agentDir'],
@@ -1103,6 +1112,7 @@ export class LangGraphAdapter {
                 nodePrompt: promptInputs.nodePrompt,
                 skillCatalog: catalog,
                 toolCatalog,
+                agentName,
                 agentCode,
                 userId,
                 workingDirectory,

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,12 +2,15 @@
  * 成功读 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';
+import { spokenName } from '../../tool/system-prompt-builder.js';
 function declaredSkillVersion(skillId, version) {
     const raw = version?.trim();
     if (!raw || raw === skillId)
@@ -25,9 +28,10 @@ export function skillTraceIdentity(state, skillId, fallbackPath) {
     const bundle = info?.bundlePath || fallbackPath;
     const skillSpace = bundle ? classifySkillSpace(bundle, { agentDir, userId }) : undefined;
     const skillVersion = declaredSkillVersion(skillId, info?.version);
+    const skillName = spokenName(info?.name, undefined);
     return {
         skillId,
-        ...(info?.name ? { skillName: info.name } : {}),
+        ...(skillName ? { skillName } : {}),
         ...(skillVersion ? { skillVersion } : {}),
         ...(skillSpace ? { skillSpace } : {}),
     };
@@ -37,6 +41,7 @@ export function skillSpanFields(identity, extra) {
         ...(identity.skillVersion ? { version: identity.skillVersion } : {}),
         input: {
             skillId: identity.skillId,
+            ...(identity.skillName ? { skillName: identity.skillName } : {}),
             ...(identity.skillSpace ? { skillSpace: identity.skillSpace } : {}),
             ...(extra?.path ? { path: extra.path } : {}),
             ...(extra?.source ? { source: extra.source } : {}),
@@ -46,7 +51,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 +65,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/adapters/subgraph-compiler.js

@@ -13,7 +13,7 @@ import { LangGraphAdapter } from './langgraph.adapter.js';
 import { assertSkillGraphHasNoSubgraphNodes } from './graph-nesting.js';
 import { resolveExecutionTrace, warnTraceSpanFailure, } from '../execution-trace-context.js';
 import { skillSpanFields, skillTraceIdentity } from './skill-entry-span.js';
-import { filterLoadedToolsForSkill, } from '../../tool/system-prompt-builder.js';
+import { filterLoadedToolsForSkill, spokenName, } from '../../tool/system-prompt-builder.js';
 import { unwrapHitlPaused } from '../hitl/hitl-handler.js';
 import { pickContextFields } from '../../token/context-window.js';
 import { assertSkillIoIfEnabled, coerceSkillInputFromMessages, } from '../../registry/skill-io-guard.js';
@@ -65,11 +65,14 @@ export class SubGraphCompiler {
                 ? state['skillSpanId']
                 : '';
             const resuming = Boolean(existingSpanId);
+            const identity = skillTraceIdentity(state, resolvedSkillId);
+            const spanName = resolvedSkillId || dsl.name || 'skill';
+            const skillName = spokenName(identity.skillName, resolvedSkillId) ?? spanName;
             const auditCtx = resuming
                 ? undefined
                 : this.skillAuditRecorder?.startInvocation({
                     skillId: resolvedSkillId,
-                    skillName: dsl.name,
+                    skillName,
                     agentCode: (state['agentCode'] ?? state['agentId']),
                     userId: state['userId'] ?? '',
                     taskId: state['taskId'],
@@ -77,8 +80,6 @@ export class SubGraphCompiler {
                 });
             // 用父图这次调用上的 collector；内层 invoke 只补 collector/traceId，沿用外层流式袋。
             const { collector: traceCollector, traceId } = resolveExecutionTrace(state);
-            const skillName = dsl.name || resolvedSkillId;
-            const identity = skillTraceIdentity(state, resolvedSkillId);
             if (!resuming) {
                 adapter.emitStreamEvent({
                     type: 'skill.started',
@@ -87,7 +88,7 @@ export class SubGraphCompiler {
                     timestamp: new Date().toISOString(),
                     payload: {
                         skillId: resolvedSkillId,
-                        skillName: identity.skillName || skillName,
+                        skillName,
                         ...(identity.skillSpace ? { skillSpace: identity.skillSpace } : {}),
                         ...(identity.skillVersion ? { skillVersion: identity.skillVersion } : {}),
                     },
@@ -99,7 +100,7 @@ export class SubGraphCompiler {
                     const fields = skillSpanFields(identity, { source: 'subgraph' });
                     skillSpanId = await traceCollector.createNode({
                         traceId,
-                        name: resolvedSkillId || dsl.name || 'skill',
+                        name: spanName,
                         type: 'skill',
                         agentCode: state['agentCode'] ?? state['agentId'],
                         ...(fields.version ? { version: fields.version } : {}),
@@ -111,7 +112,7 @@ export class SubGraphCompiler {
                     });
                 }
                 catch (err) {
-                    warnTraceSpanFailure('createNode', { type: 'skill', name: resolvedSkillId || dsl.name || 'skill', traceId }, err);
+                    warnTraceSpanFailure('createNode', { type: 'skill', name: spanName, traceId }, err);
                     skillSpanId = null;
                 }
             }
@@ -154,6 +155,7 @@ export class SubGraphCompiler {
                     userId,
                     delegationToken,
                     agentCode,
+                    agentName: typeof state['agentName'] === 'string' ? state['agentName'] : undefined,
                     taskId: state['taskId'],
                     correlationId: state['correlationId'],
                     sessionId: state['sessionId'],
@@ -194,7 +196,7 @@ export class SubGraphCompiler {
                         });
                     }
                     catch (err) {
-                        warnTraceSpanFailure('completeNode', { type: 'skill', name: skillName, traceId, spanId: skillSpanId }, err);
+                        warnTraceSpanFailure('completeNode', { type: 'skill', name: spanName, traceId, spanId: skillSpanId }, err);
                     }
                 }
                 // 4. 只回写子图本步新增消息（含内部 tool 回合），禁止把入口历史再 append
@@ -269,7 +271,7 @@ export class SubGraphCompiler {
                         });
                     }
                     catch (completeErr) {
-                        warnTraceSpanFailure('completeNode', { type: 'skill', name: skillName, traceId, spanId: skillSpanId }, completeErr);
+                        warnTraceSpanFailure('completeNode', { type: 'skill', name: spanName, traceId, spanId: skillSpanId }, completeErr);
                     }
                 }
                 adapter.emitStreamEvent({

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

@@ -181,6 +181,8 @@ export interface GraphState {
     agentId?: string;
     /** Agent 对外主键 */
     agentCode?: string;
+    /** Agent 展示名（manifest.name）；身份段对用户说话用，缺省回退 agentCode */
+    agentName?: string;
     /** Hosting 路由选定的预装版本（AR-3b；写入 Checkpoint 供 HITL/Fork 恢复） */
     agentVersion?: string;
     correlationId?: string;

package/dist/graph/nodes/skill-bind-node.d.ts

@@ -2,7 +2,7 @@
  * 可选图胶水：把 silent LLM 的结构化输出写成 skillRoute / activatedSkill。
  * 不是 Graph 节点类型。技能正文走短目录 + read_file，不灌 system。
  */
-import type { LoadedSkillInfo, LoadedSkillMap } from '../../tool/system-prompt-builder.js';
+import { type LoadedSkillInfo, type LoadedSkillMap } from '../../tool/system-prompt-builder.js';
 export type SkillRoute = 'skill' | 'clarify' | 'none';
 export interface SkillBindPatch {
     skillRoute: SkillRoute;

package/dist/graph/nodes/skill-bind-node.js

@@ -1,3 +1,8 @@
+/**
+ * 可选图胶水：把 silent LLM 的结构化输出写成 skillRoute / activatedSkill。
+ * 不是 Graph 节点类型。技能正文走短目录 + read_file，不灌 system。
+ */
+import { spokenName } from '../../tool/system-prompt-builder.js';
 function lastAssistantText(messages) {
     for (let i = messages.length - 1; i >= 0; i--) {
         const msg = messages[i];
@@ -89,7 +94,7 @@ export function bindSelectedSkill(state) {
     return {
         skillRoute: 'skill',
         activatedSkill: skill.skillId,
-        skillName: skill.name || skill.skillId,
+        skillName: spokenName(skill.name, skill.skillId),
         skillInput: params,
         messages: nextMessages(),
     };

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

@@ -203,6 +203,7 @@ export class ToolNode {
                         correlationId: req.correlationId,
                         skillId,
                         ...(identity.toolset ? { toolset: identity.toolset } : {}),
+                        ...(identity.toolDisplayName ? { toolDisplayName: identity.toolDisplayName } : {}),
                     },
                 });
             }
@@ -295,7 +296,7 @@ export class ToolNode {
                 if (result.success) {
                     const catalog = skillEntryInvocationFromTool({
                         toolName: req.toolName,
-                        arguments: req.arguments,
+                        resolvedPath: result.resolvedPath,
                         skillDirs,
                         alreadyInSkillSpan: inSkillSubgraph,
                     });
@@ -312,6 +313,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 +348,7 @@ export class ToolNode {
                 if (result.success) {
                     await recordSkillEntrySpan(state, {
                         toolName: req.toolName,
-                        arguments: req.arguments,
+                        resolvedPath: result.resolvedPath,
                         skillDirs,
                     });
                 }

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

@@ -20,8 +20,13 @@ export interface LoadAgentOptions {
 export declare function resolveAgentSystemPromptFromLoader(loader: {
     resolveAgentSystemPrompt?: (agentCode: string, version?: string) => Promise<string | undefined>;
 } | undefined, agentCode: string, version?: string): Promise<string | undefined>;
+export declare function resolveAgentDisplayNameFromLoader(loader: {
+    resolveAgentDisplayName?: (agentCode: string, version?: string) => Promise<string | undefined>;
+} | undefined, agentCode: string, version?: string): Promise<string | undefined>;
 /** manifest.prompts.system；空白视为缺省。 */
 export declare function extractAgentSystemPrompt(manifest: unknown): string | undefined;
+/** manifest.name；空白视为缺省。身份段对用户说话用，不当路由键。 */
+export declare function extractAgentDisplayName(manifest: unknown): string | undefined;
 export interface GraphLoaderConfig {
     registryClient?: AgentRegistryClient;
     deploymentContext?: DeploymentContext;
@@ -116,6 +121,12 @@ export declare class GraphLoader {
      * 每轮 execute/stream 注入 GraphState.agentSystemPrompt；不写进节点 config。
      */
     resolveAgentSystemPrompt(agentCode: string, version?: string): Promise<string | undefined>;
+    /**
+     * Agent 展示名（manifest.name）。
+     * 每轮 execute/stream 注入 GraphState.agentName；身份段对用户说话用。
+     */
+    resolveAgentDisplayName(agentCode: string, version?: string): Promise<string | undefined>;
+    private fromAgentManifest;
     /**
      * 解析 agent tools[] + graph tool 节点 union；
      * server+预装：以预装 manifest 为准；desktop 合并 ILocalToolInstallStore。

package/dist/registry/graph-loader.js

@@ -64,6 +64,11 @@ export async function resolveAgentSystemPromptFromLoader(loader, agentCode, vers
         return undefined;
     return loader.resolveAgentSystemPrompt(agentCode, version);
 }
+export async function resolveAgentDisplayNameFromLoader(loader, agentCode, version) {
+    if (!loader || typeof loader.resolveAgentDisplayName !== 'function')
+        return undefined;
+    return loader.resolveAgentDisplayName(agentCode, version);
+}
 /** manifest.prompts.system；空白视为缺省。 */
 export function extractAgentSystemPrompt(manifest) {
     if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest))
@@ -77,6 +82,16 @@ export function extractAgentSystemPrompt(manifest) {
     const trimmed = system.trim();
     return trimmed ? trimmed : undefined;
 }
+/** manifest.name；空白视为缺省。身份段对用户说话用，不当路由键。 */
+export function extractAgentDisplayName(manifest) {
+    if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest))
+        return undefined;
+    const name = manifest.name;
+    if (typeof name !== 'string')
+        return undefined;
+    const trimmed = name.trim();
+    return trimmed ? trimmed : undefined;
+}
 function extractSkillPrompt(manifest) {
     const prompt = manifest.prompt;
     if (typeof prompt === 'string' && prompt.trim())
@@ -769,18 +784,27 @@ export class GraphLoader {
      * 每轮 execute/stream 注入 GraphState.agentSystemPrompt；不写进节点 config。
      */
     async resolveAgentSystemPrompt(agentCode, version) {
+        return this.fromAgentManifest(agentCode, version, extractAgentSystemPrompt);
+    }
+    /**
+     * Agent 展示名（manifest.name）。
+     * 每轮 execute/stream 注入 GraphState.agentName；身份段对用户说话用。
+     */
+    async resolveAgentDisplayName(agentCode, version) {
+        return this.fromAgentManifest(agentCode, version, extractAgentDisplayName);
+    }
+    async fromAgentManifest(agentCode, version, extract) {
         if (this.deploymentSnapshot) {
             const snap = await this.deploymentSnapshot.loadAgentSnapshot(agentCode, version);
-            if (snap) {
-                return extractAgentSystemPrompt(snap.manifest);
-            }
+            if (snap)
+                return extract(snap.manifest);
             if (this.blockRegistryDefinitions)
                 return undefined;
         }
         if (this.blockRegistryDefinitions || !this.registryClient)
             return undefined;
         const record = await this.registryClient.getAgent(agentCode);
-        return extractAgentSystemPrompt(record?.manifest);
+        return extract(record?.manifest);
     }
     /**
      * 解析 agent tools[] + graph tool 节点 union；

package/dist/runtime/agent-runtime.js

@@ -11,7 +11,7 @@ import { DEFAULT_GRAPH_TIMEOUT_MS } from '../common/types.js';
 import { resolveTaskTimeoutMs } from '../task/resolve-task-timeout.js';
 import { runWithExecutionTrace } from '../graph/execution-trace-context.js';
 import { HITL_TIMEOUT_ERROR_CODE, HITL_TIMEOUT_MESSAGE, HitlAlreadyTimedOutError, HitlNotWaitingError, buildHitlWaitedPayload, isHitlDeadlinePassed, loadHitlCheckpoint, readPersistedHitlWaiting, unwrapHitlPaused, } from '../graph/hitl/hitl-handler.js';
-import { resolveAgentSystemPromptFromLoader } from '../registry/graph-loader.js';
+import { resolveAgentDisplayNameFromLoader, resolveAgentSystemPromptFromLoader, } from '../registry/graph-loader.js';
 import { toLoadedSkillMap } from '../tool/system-prompt-builder.js';
 import { assembleLoadedTools } from '../tool/harness-primitives.js';
 import { createFileLlmTurnLogFromEnv, } from '../debug/llm-turn-log.js';
@@ -330,6 +330,7 @@ export class AgentRuntime {
             ? (await this.deps.graphLoader.resolveAgentDir(agentCode, params.agentVersion)) ?? undefined
             : undefined;
         const agentSystemPrompt = await resolveAgentSystemPromptFromLoader(this.deps.graphLoader, agentCode, params.agentVersion);
+        const agentName = await resolveAgentDisplayNameFromLoader(this.deps.graphLoader, agentCode, params.agentVersion);
         const facing = await loadModelFacingHistory({
             sessionHistory: messageRecordsToGraphMessages(sessionContext.messages),
             checkpointSaver: this.deps.checkpointSaver,
@@ -402,6 +403,7 @@ export class AgentRuntime {
                 promptRoots,
                 agentDir,
                 agentSystemPrompt,
+                agentName,
                 skillInput: resolveSkillInputFromInvokeInput(params.input),
                 traceId: resolveTraceId(params),
                 traceCollector: this.deps.traceCollector,
@@ -617,6 +619,9 @@ export class AgentRuntime {
             agentSystemPrompt: (await resolveAgentSystemPromptFromLoader(this.deps.graphLoader, agentCode, agentVersion)) ?? (typeof resumedState.agentSystemPrompt === 'string'
                 ? resumedState.agentSystemPrompt
                 : undefined),
+            agentName: (await resolveAgentDisplayNameFromLoader(this.deps.graphLoader, agentCode, agentVersion)) ?? (typeof resumedState.agentName === 'string' && resumedState.agentName.trim()
+                ? resumedState.agentName.trim()
+                : undefined),
             activatedSkill: resumedState.activatedSkill,
             skillRoute: resumedState.skillRoute ??
                 (typeof resumedState.activatedSkill === 'string' && resumedState.activatedSkill
@@ -814,6 +819,9 @@ export class AgentRuntime {
         const agentSystemPrompt = (await resolveAgentSystemPromptFromLoader(this.deps.graphLoader, agentCode, agentVersion)) ?? (typeof forkedCheckpoint.state.agentSystemPrompt === 'string'
             ? forkedCheckpoint.state.agentSystemPrompt
             : undefined);
+        const agentName = (await resolveAgentDisplayNameFromLoader(this.deps.graphLoader, agentCode, agentVersion)) ?? (typeof forkedCheckpoint.state.agentName === 'string' && forkedCheckpoint.state.agentName.trim()
+            ? forkedCheckpoint.state.agentName.trim()
+            : undefined);
         const abortDeadlineMs = Date.now() + timeout;
         try {
             const forkState = { ...forkedCheckpoint.state };
@@ -827,6 +835,7 @@ export class AgentRuntime {
                 agentVersion,
                 agentDir,
                 agentSystemPrompt,
+                agentName,
                 userId,
                 delegationToken: overrides.executionContext?.delegationToken,
                 executionContext: overrides.executionContext,

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/index.d.ts

@@ -22,4 +22,4 @@ export { expandSkillScriptRefs, isSkillEntryFile, EAP_SKILL_DIR_ENV, } from './s
 export { ToolResultInjector, type ToolMessage, } from './tool-result-injector.js';
 export { ToolEventEmitter } from './tool-event-emitter.js';
 export { ToolConfirmationInterceptor } from './tool-confirmation.js';
-export { SystemPromptBuilder, naturalTimeWindows, loadedToolsToApiTools, toLoadedSkillMap, filterLoadedToolsForSkill, type PromptBuildContext, type PromptSection, type AssembledSystemPrompt, type ApiToolDefinition, type LoadedSkillInfo, type LoadedSkillMap, } from './system-prompt-builder.js';
+export { SystemPromptBuilder, naturalTimeWindows, buildSkillCatalog, buildToolCatalog, catalogEntryTitle, spokenName, loadedToolsToApiTools, toLoadedSkillMap, filterLoadedToolsForSkill, type PromptBuildContext, type PromptSection, type AssembledSystemPrompt, type ApiToolDefinition, type LoadedSkillInfo, type LoadedSkillMap, } from './system-prompt-builder.js';

package/dist/tool/index.js

@@ -21,4 +21,4 @@ export { expandSkillScriptRefs, isSkillEntryFile, EAP_SKILL_DIR_ENV, } from './s
 export { ToolResultInjector, } from './tool-result-injector.js';
 export { ToolEventEmitter } from './tool-event-emitter.js';
 export { ToolConfirmationInterceptor } from './tool-confirmation.js';
-export { SystemPromptBuilder, naturalTimeWindows, loadedToolsToApiTools, toLoadedSkillMap, filterLoadedToolsForSkill, } from './system-prompt-builder.js';
+export { SystemPromptBuilder, naturalTimeWindows, buildSkillCatalog, buildToolCatalog, catalogEntryTitle, spokenName, loadedToolsToApiTools, toLoadedSkillMap, filterLoadedToolsForSkill, } from './system-prompt-builder.js';

package/dist/tool/mcp-list.d.ts

@@ -53,17 +53,19 @@ export declare function mcpToolsetCode(loaded: {
         execution?: unknown;
     };
 } | undefined): string | undefined;
-/** Tool Span：工具集 code + 声明版本。与 Skill 的 skillSpace/version 同一假设。 */
+/** Tool Span：工具集 code + 声明版本 + 展示名（与函数名不同才写）。 */
 export declare function toolTraceIdentity(loaded: {
     toolId?: string;
     name?: string;
     manifest?: {
         id?: string;
+        name?: string;
         version?: string;
     };
 } | undefined, toolName: string): {
     toolset?: string;
     toolVersion?: string;
+    toolDisplayName?: string;
 };
 export interface HydrateMcpToolsAuth {
     authContext: AuthContext;

package/dist/tool/mcp-list.js

@@ -130,13 +130,16 @@ function declaredToolVersion(toolName, version) {
         return undefined;
     return raw;
 }
-/** Tool Span：工具集 code + 声明版本。与 Skill 的 skillSpace/version 同一假设。 */
+/** Tool Span：工具集 code + 声明版本 + 展示名（与函数名不同才写）。 */
 export function toolTraceIdentity(loaded, toolName) {
     const toolset = toolsetCodeFromLoaded(loaded);
     const toolVersion = declaredToolVersion(toolName, loaded?.manifest?.version);
+    const display = loaded?.manifest?.name?.trim();
+    const toolDisplayName = display && display !== toolName ? display : undefined;
     return {
         ...(toolset ? { toolset } : {}),
         ...(toolVersion ? { toolVersion } : {}),
+        ...(toolDisplayName ? { toolDisplayName } : {}),
     };
 }
 /**

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/system-prompt-builder.d.ts

@@ -7,8 +7,8 @@
  * ```
  * [平台规则常量]          ← 代码内置，安全约束 + 行为准则（最高优先级）
  * [当前时间]              ← 运行时动态注入（自然周等时间规则的判定基准）
- * [Agent 身份]            ← agentName / agentCode（目录身份，不是 prompts.system）
- * [可用工具短目录]        ← 名称 + 一句话用途；完整 schema 仍走 API tools
+ * [Agent 身份]            ← 展示名 agentName，缺省 agentCode（对用户说话，不是路由键）
+ * [可用工具短目录]        ← 展示名 + 调用名 + 一句话用途；完整 schema 仍走 API tools
  * [Agent 基线]            ← agent.manifest.json prompts.system；非 silent LLM
  * [节点提示词]            ← Graph LLM 节点 config.systemPrompt / systemPromptFile
  * ```
@@ -109,6 +109,10 @@ export interface AssembledSystemPrompt {
     text: string;
     sections: PromptSection[];
 }
+/** 对人展示的名称。有展示名用展示名，否则用编码。 */
+export declare function spokenName(displayName: string | undefined, code: string | undefined): string | undefined;
+/** 短目录标题：展示名在前，调用键在行内。名称与编码相同则只写编码。 */
+export declare function catalogEntryTitle(code: string, displayName: string | undefined, codePhrase: string): string;
 /**
  * 非 silent LLM 才带 Agent 基线；节点提示词空则省略。
  * silent 只保留节点增量（选技能 / JSON）。
@@ -166,4 +170,6 @@ export type ApiToolDefinition = LLMToolDefinition;
  */
 /** 名称 + 一句话用途，供 system「可用工具」段。schema 仍走 loadedToolsToApiTools。 */
 export declare function buildToolCatalog(loadedTools: LoadedToolMap | undefined): string | undefined;
+/** 展示名 + skillId，供 system「可用技能」段。read_file 仍用 skillId。 */
+export declare function buildSkillCatalog(defs: LoadedSkillMap | undefined): string | undefined;
 export declare function loadedToolsToApiTools(loadedTools: LoadedToolMap | undefined, skillTools?: string[]): ApiToolDefinition[];

package/dist/tool/system-prompt-builder.js

@@ -7,8 +7,8 @@
  * ```
  * [平台规则常量]          ← 代码内置，安全约束 + 行为准则（最高优先级）
  * [当前时间]              ← 运行时动态注入（自然周等时间规则的判定基准）
- * [Agent 身份]            ← agentName / agentCode（目录身份，不是 prompts.system）
- * [可用工具短目录]        ← 名称 + 一句话用途；完整 schema 仍走 API tools
+ * [Agent 身份]            ← 展示名 agentName，缺省 agentCode（对用户说话，不是路由键）
+ * [可用工具短目录]        ← 展示名 + 调用名 + 一句话用途；完整 schema 仍走 API tools
  * [Agent 基线]            ← agent.manifest.json prompts.system；非 silent LLM
  * [节点提示词]            ← Graph LLM 节点 config.systemPrompt / systemPromptFile
  * ```
@@ -86,6 +86,22 @@ function trimPrompt(value) {
     const trimmed = value.trim();
     return trimmed ? trimmed : undefined;
 }
+/** 对人展示的名称。有展示名用展示名，否则用编码。 */
+export function spokenName(displayName, code) {
+    const name = displayName?.trim();
+    if (name)
+        return name;
+    const id = code?.trim();
+    return id || undefined;
+}
+/** 短目录标题：展示名在前，调用键在行内。名称与编码相同则只写编码。 */
+export function catalogEntryTitle(code, displayName, codePhrase) {
+    const id = code.trim();
+    const name = displayName?.trim();
+    if (name && name !== id)
+        return `**${name}**（${codePhrase}）`;
+    return `**${id}**`;
+}
 /**
  * 非 silent LLM 才带 Agent 基线；节点提示词空则省略。
  * silent 只保留节点增量（选技能 / JSON）。
@@ -154,7 +170,7 @@ export class SystemPromptBuilder {
         return lines.join('\n');
     }
     buildAgentIdentity(context) {
-        const name = context.agentName ?? context.agentCode;
+        const name = spokenName(context.agentName, context.agentCode);
         return name ? `## Agent 身份\n你的名称是「${name}」。` : '';
     }
     buildJail(context) {
@@ -262,11 +278,8 @@ export function buildToolCatalog(loadedTools) {
         return undefined;
     const rows = Object.values(loadedTools).map((tool) => {
         const desc = (tool.manifest.description ?? '').replace(/\s+/g, ' ').trim();
-        const displayName = tool.manifest.name?.trim();
-        const title = displayName && displayName !== tool.name
-            ? `${tool.name}（${displayName}）`
-            : tool.name;
-        return `- **${title}**${desc ? `：${desc}` : ''}`;
+        const title = catalogEntryTitle(tool.name, tool.manifest.name, `调用名 ${tool.name}`);
+        return `- ${title}${desc ? `：${desc}` : ''}`;
     });
     if (rows.length === 0)
         return undefined;
@@ -276,6 +289,21 @@ export function buildToolCatalog(loadedTools) {
         rows.join('\n'),
     ].join('\n');
 }
+/** 展示名 + skillId，供 system「可用技能」段。read_file 仍用 skillId。 */
+export function buildSkillCatalog(defs) {
+    if (!defs)
+        return undefined;
+    const rows = Object.values(defs).map((skill) => {
+        const desc = (skill.description ?? '').replace(/\s+/g, ' ').trim();
+        const entry = skill.entryFile ?? (skill.bundlePath ? `${skill.bundlePath}/SKILL.md` : '');
+        const title = catalogEntryTitle(skill.skillId, skill.name, `skillId ${skill.skillId}`);
+        const pathLine = entry ? `\n  SKILL.md: ${entry}` : '';
+        return `- ${title}${desc ? `：${desc}` : ''}${pathLine}`;
+    });
+    if (rows.length === 0)
+        return undefined;
+    return `# 可用技能\n要用某个技能时，调用 read_file 读取其 SKILL.md。脚本和参考文档默认在同一目录。\n${rows.join('\n')}`;
+}
 export function loadedToolsToApiTools(loadedTools, skillTools) {
     if (!loadedTools)
         return [];

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.33",
   "description": "Enterprise Agent Platform — Runtime核心：Graph执行引擎、Task生命周期、Session管理、Checkpoint持久化",
   "type": "module",
   "main": "dist/index.js",