@gt-fe/eap-runtime 0.0.13 → 0.0.14

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

@@ -4,8 +4,8 @@
  * 优先 ILocalToolInstallStore；若无安装记录但 request.execution 带
  * 或 request.execution 带可解析的 code bundlePath+handler，则直接本机执行。
  */
-import type { ILocalToolInstallStore } from '@gt-fe/eap-contracts';
-import type { IToolExecutor, ToolCallRequest, ToolCallResult } from './tool-executor.interface.js';
+import type { ILocalToolInstallStore } from '@eap/contracts';
+import type { IToolExecutor, McpListedTool, ToolCallRequest, ToolCallResult } from './tool-executor.interface.js';
 import { type ILocalMcpClient } from './local-mcp-client.js';
 export interface LocalToolExecutorOptions {
     installStore: ILocalToolInstallStore;
@@ -30,6 +30,7 @@ export declare class LocalToolExecutor implements IToolExecutor {
     private readonly mcpClient;
     constructor(options: LocalToolExecutorOptions);
     execute(request: ToolCallRequest): Promise<ToolCallResult>;
+    listTools(request: ToolCallRequest): Promise<McpListedTool[]>;
     private executeCodeSpec;
     private executeCode;
     private executeMcp;

package/dist/tool/local-tool-executor.js

@@ -7,10 +7,11 @@
 import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { ErrorCodes, resolveReadyInstallByToolName, resolveMcpExecutionFromInstall, resolveCodeHandlerFromInstall, } from '@gt-fe/eap-contracts';
+import { ErrorCodes, resolveReadyInstallByToolName, resolveMcpExecutionFromInstall, resolveCodeHandlerFromInstall, } from '@eap/contracts';
 import { isAbortError, toToolTimeoutMs, toolTimeoutErrorMessage } from './timeout.js';
 import { fileArtifactFromToolOutput, fileBasesFromEnv } from './file-artifact.js';
 import { LocalMcpClient } from './local-mcp-client.js';
+import { normalizeMcpExecution } from './dev-mcp-executor.js';
 /**
  * 根据 execution.runtime 解析执行命令：
  * - node（默认）→ process.execPath + [handlerPath]
@@ -171,6 +172,20 @@ export class LocalToolExecutor {
             runtime: 'local',
         };
     }
+    async listTools(request) {
+        const fromRequest = normalizeMcpExecution(request.execution, request.toolName);
+        if (fromRequest) {
+            return this.mcpClient.list(fromRequest, { userId: request.authContext?.userId });
+        }
+        const install = resolveReadyInstallByToolName(this.options.installStore, request.toolName);
+        if (install && install.installStatus === 'ready' && (install.type ?? request.toolType) === 'mcp') {
+            const execution = resolveMcpExecutionFromInstall(install);
+            if (execution) {
+                return this.mcpClient.list(execution, { userId: request.authContext?.userId });
+            }
+        }
+        throw new Error(`MCP tools/list: no mcp execution for "${request.toolName}"`);
+    }
     async executeCodeSpec(request, spec) {
         try {
             const stdout = await runHandler(spec.handlerPath, request.arguments, spec.timeoutMs ?? this.options.timeoutMs ?? 30_000, { runtime: spec.runtime, args: spec.args });

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

@@ -0,0 +1,53 @@
+/**
+ * MCP tools/list 解析、discover stub 判定、hydrate。
+ *
+ * type: mcp 的预装工具集不展开清单 tools[]，先产出 discover stub；
+ * 有 ExecutionContext 后由同一执行器 tools/list，再写入 LLM tools。
+ */
+import type { LoadedToolDefinition, LoadedToolMap } from './loaded-tool-definition.js';
+import type { AuthContext, IToolExecutor, McpListedTool } from './tool-executor.interface.js';
+export declare function parseListedTools(result: unknown): McpListedTool[];
+export declare function nextListCursor(result: unknown): string | undefined;
+export interface McpDiscoverExecution {
+    protocol?: string;
+    discover?: boolean;
+    transport?: string;
+    server?: Record<string, unknown>;
+    timeout?: number;
+    bundlePath?: string;
+    enabledTools?: string[];
+    autoApprove?: string[];
+}
+export declare function readMcpDiscoverExecution(raw: unknown): McpDiscoverExecution | null;
+export declare function isMcpDiscoverStub(def: LoadedToolDefinition): boolean;
+export declare function mcpEndpointKey(execution: unknown, fallback?: string): string;
+export declare const MCP_LIST_TOOL_NAME = "tools/list";
+/** 展示用：`tl-data-035/get_dataset_by_code`；无名工具集则只返回工具名。 */
+export declare function formatToolsetToolName(toolset: string | undefined, toolName: string): string;
+/** 从 hydrate 后的 toolId（`toolset:toolName`）取出工具集编码。 */
+export declare function toolsetCodeFromLoaded(loaded: {
+    toolId?: string;
+    name?: string;
+    manifest?: {
+        id?: string;
+    };
+} | undefined): string | undefined;
+export interface HydrateMcpToolsAuth {
+    authContext: AuthContext;
+    correlationId?: string;
+    taskId?: string;
+    onListFailure?: (failure: {
+        toolset: string;
+        endpoint: string;
+        error: string;
+    }) => void;
+}
+/**
+ * 将 MCP discover stub 替换为 tools/list 结果。
+ * 无 stub 时原样返回（同一引用）。按 endpoint+user+agent 在执行器内缓存 list。
+ * enabledTools 为可选白名单；autoApprove 的子工具 requireConfirmation=false。
+ * 单个 endpoint 的 list 失败只跳过该工具集；全部失败才抛错（错误含工具集名）。
+ */
+export declare function hydrateMcpTools(loadedTools: LoadedToolMap | undefined, executor: IToolExecutor | undefined, auth: HydrateMcpToolsAuth): Promise<LoadedToolMap | undefined>;
+/** 测试与 HITL 续跑：从已 hydrate 的 map 判断是否还要 list */
+export declare function needsMcpHydration(loadedTools: LoadedToolMap | undefined): boolean;

package/dist/tool/mcp-list.js

@@ -0,0 +1,199 @@
+/**
+ * MCP tools/list 解析、discover stub 判定、hydrate。
+ *
+ * type: mcp 的预装工具集不展开清单 tools[]，先产出 discover stub；
+ * 有 ExecutionContext 后由同一执行器 tools/list，再写入 LLM tools。
+ */
+import { emitRuntimeLog } from '../common/logger.js';
+export function parseListedTools(result) {
+    const tools = result?.tools;
+    if (!Array.isArray(tools))
+        return [];
+    const out = [];
+    for (const raw of tools) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            continue;
+        const t = raw;
+        if (typeof t.name !== 'string' || !t.name.trim())
+            continue;
+        const inputSchema = t.inputSchema && typeof t.inputSchema === 'object' && !Array.isArray(t.inputSchema)
+            ? t.inputSchema
+            : undefined;
+        out.push({
+            name: t.name,
+            description: typeof t.description === 'string' ? t.description : undefined,
+            inputSchema,
+        });
+    }
+    return out;
+}
+export function nextListCursor(result) {
+    const cursor = result?.nextCursor;
+    return typeof cursor === 'string' && cursor.trim() ? cursor : undefined;
+}
+export function readMcpDiscoverExecution(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const e = raw;
+    if (e.protocol !== 'mcp' || e.discover !== true)
+        return null;
+    return e;
+}
+export function isMcpDiscoverStub(def) {
+    return def.manifest.type === 'mcp' && readMcpDiscoverExecution(def.manifest.execution) != null;
+}
+export function mcpEndpointKey(execution, fallback = 'gateway') {
+    if (!execution || typeof execution !== 'object' || Array.isArray(execution))
+        return fallback;
+    const e = execution;
+    const server = e.server;
+    if (server && typeof server === 'object') {
+        if (typeof server.url === 'string' && server.url.trim()) {
+            return `http:${server.url.trim()}`;
+        }
+        if (typeof server.command === 'string' && server.command.trim()) {
+            const args = Array.isArray(server.args)
+                ? server.args.map((a) => String(a)).join('\0')
+                : '';
+            return `stdio:${server.command.trim()}:${args}`;
+        }
+    }
+    return fallback;
+}
+export const MCP_LIST_TOOL_NAME = 'tools/list';
+/** 展示用：`tl-data-035/get_dataset_by_code`；无名工具集则只返回工具名。 */
+export function formatToolsetToolName(toolset, toolName) {
+    const set = toolset?.trim() ?? '';
+    const name = toolName.trim() || 'tool';
+    if (!set || set === name)
+        return name;
+    if (name.startsWith(`${set}/`))
+        return name;
+    return `${set}/${name}`;
+}
+/** 从 hydrate 后的 toolId（`toolset:toolName`）取出工具集编码。 */
+export function toolsetCodeFromLoaded(loaded) {
+    if (!loaded)
+        return undefined;
+    const id = loaded.toolId || loaded.manifest?.id || '';
+    const sep = id.indexOf(':');
+    if (sep > 0) {
+        const prefix = id.slice(0, sep);
+        if (prefix && prefix !== loaded.name)
+            return prefix;
+    }
+    return undefined;
+}
+/**
+ * 将 MCP discover stub 替换为 tools/list 结果。
+ * 无 stub 时原样返回（同一引用）。按 endpoint+user+agent 在执行器内缓存 list。
+ * enabledTools 为可选白名单；autoApprove 的子工具 requireConfirmation=false。
+ * 单个 endpoint 的 list 失败只跳过该工具集；全部失败才抛错（错误含工具集名）。
+ */
+export async function hydrateMcpTools(loadedTools, executor, auth) {
+    if (!loadedTools)
+        return loadedTools;
+    const stubs = Object.values(loadedTools).filter(isMcpDiscoverStub);
+    if (stubs.length === 0)
+        return loadedTools;
+    if (typeof executor?.listTools !== 'function') {
+        throw new Error('MCP 工具集需要 tools/list，当前执行器不支持 listTools');
+    }
+    const result = { ...loadedTools };
+    for (const stub of stubs) {
+        delete result[stub.name];
+    }
+    const groups = new Map();
+    for (const stub of stubs) {
+        const key = mcpEndpointKey(stub.manifest.execution);
+        const list = groups.get(key);
+        if (list)
+            list.push(stub);
+        else
+            groups.set(key, [stub]);
+    }
+    const emitted = new Set();
+    const failures = [];
+    for (const [, group] of groups) {
+        const primary = group[0];
+        const endpoint = mcpEndpointKey(primary.manifest.execution, primary.name);
+        let listed;
+        try {
+            listed = await executor.listTools({
+                toolCallId: `mcp-list:${primary.toolId}`,
+                toolName: primary.name,
+                arguments: {},
+                authContext: auth.authContext,
+                correlationId: auth.correlationId,
+                taskId: auth.taskId,
+                toolType: 'mcp',
+                toolRuntime: primary.manifest.toolRuntime,
+                execution: primary.manifest.execution,
+            });
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            const ref = formatToolsetToolName(primary.name, MCP_LIST_TOOL_NAME);
+            const message = `MCP ${ref} 失败 (${endpoint}): ${detail}`;
+            failures.push(message);
+            emitRuntimeLog('warn', 'tool', message, {
+                agentCode: auth.authContext.agentCode,
+                taskId: auth.taskId,
+                correlationId: auth.correlationId,
+            });
+            auth.onListFailure?.({ toolset: primary.name, endpoint, error: detail });
+            continue;
+        }
+        for (const stub of group) {
+            const exec = readMcpDiscoverExecution(stub.manifest.execution);
+            const enabled = exec?.enabledTools;
+            const enabledSet = enabled && enabled.length > 0 ? new Set(enabled) : null;
+            const autoApprove = new Set(exec?.autoApprove ?? []);
+            const picked = enabledSet ? listed.filter((t) => enabledSet.has(t.name)) : listed;
+            for (const tool of picked) {
+                if (emitted.has(tool.name))
+                    continue;
+                emitted.add(tool.name);
+                result[tool.name] = listedToolToDefinition(tool, stub, autoApprove.has(tool.name));
+            }
+        }
+    }
+    if (emitted.size === 0 && failures.length > 0) {
+        throw new Error(failures.join('\n'));
+    }
+    return result;
+}
+function listedToolToDefinition(tool, stub, autoApprove) {
+    const exec = { ...(readMcpDiscoverExecution(stub.manifest.execution) ?? {}) };
+    delete exec.discover;
+    delete exec.enabledTools;
+    delete exec.autoApprove;
+    const rest = exec;
+    return {
+        toolId: `${stub.toolId}:${tool.name}`,
+        name: tool.name,
+        manifest: {
+            id: `${stub.manifest.id}:${tool.name}`,
+            name: tool.name,
+            version: stub.manifest.version,
+            type: 'mcp',
+            status: 'active',
+            description: tool.description,
+            toolRuntime: stub.manifest.toolRuntime,
+            dataScope: stub.manifest.dataScope,
+            requireConfirmation: autoApprove ? false : Boolean(stub.manifest.requireConfirmation),
+            execution: {
+                ...rest,
+                protocol: 'mcp',
+                toolName: tool.name,
+            },
+        },
+        inputSchema: tool.inputSchema ?? { type: 'object', properties: {} },
+    };
+}
+/** 测试与 HITL 续跑：从已 hydrate 的 map 判断是否还要 list */
+export function needsMcpHydration(loadedTools) {
+    if (!loadedTools)
+        return false;
+    return Object.values(loadedTools).some(isMcpDiscoverStub);
+}

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

@@ -3,7 +3,7 @@
  *
  * @see docs/contracts/tool-execution.md §2.0
  */
-import type { IToolExecutor, ToolCallRequest, ToolCallResult } from './tool-executor.interface.js';
+import type { IToolExecutor, McpListedTool, ToolCallRequest, ToolCallResult } from './tool-executor.interface.js';
 export interface McpToolExecutorOptions {
     baseUrl: string;
     timeout?: number;
@@ -16,8 +16,13 @@ export declare class McpToolExecutor implements IToolExecutor {
     private readonly mcpUrl;
     private rpcId;
     private initialized;
+    /** endpoint+user+agent → in-flight / completed tools/list */
+    private readonly listCache;
     constructor(options: McpToolExecutorOptions);
     execute(request: ToolCallRequest): Promise<ToolCallResult>;
+    listTools(request: ToolCallRequest): Promise<McpListedTool[]>;
+    private listAllTools;
+    private rpcResult;
     private ensureInitialized;
     private postRpc;
 }

package/dist/tool/mcp-tool-executor.js

@@ -3,8 +3,9 @@
  *
  * @see docs/contracts/tool-execution.md §2.0
  */
-import { ErrorCodes } from '@gt-fe/eap-contracts';
+import { ErrorCodes } from '@eap/contracts';
 import { abortOrTimeoutMessage, isAbortError } from './timeout.js';
+import { nextListCursor, parseListedTools } from './mcp-list.js';
 function resolveAgentCode(request) {
     return request.authContext.agentCode;
 }
@@ -45,6 +46,8 @@ export class McpToolExecutor {
     mcpUrl;
     rpcId = 1;
     initialized = false;
+    /** endpoint+user+agent → in-flight / completed tools/list */
+    listCache = new Map();
     constructor(options) {
         this.baseUrl = options.baseUrl.replace(/\/+$/, '');
         this.timeout = options.timeout ?? 30_000;
@@ -125,6 +128,55 @@ export class McpToolExecutor {
             };
         }
     }
+    async listTools(request) {
+        const key = `${this.mcpUrl}\0${request.authContext.userId}\0${request.authContext.agentCode}`;
+        const cached = this.listCache.get(key);
+        if (cached)
+            return cached;
+        const pending = this.listAllTools(request);
+        this.listCache.set(key, pending);
+        try {
+            return await pending;
+        }
+        catch (err) {
+            this.listCache.delete(key);
+            throw err;
+        }
+    }
+    async listAllTools(request) {
+        await this.ensureInitialized(request);
+        const tools = [];
+        let cursor;
+        do {
+            const result = await this.rpcResult(request, 'tools/list', cursor ? { cursor } : {});
+            tools.push(...parseListedTools(result));
+            cursor = nextListCursor(result);
+        } while (cursor);
+        return tools;
+    }
+    async rpcResult(request, method, params) {
+        const agentCode = resolveAgentCode(request);
+        const correlationId = request.correlationId ?? request.toolCallId;
+        const id = this.rpcId++;
+        const response = await this.postRpc({ jsonrpc: '2.0', id, method, params }, request, agentCode, correlationId);
+        if (!response.ok) {
+            let body = null;
+            try {
+                body = (await response.json());
+            }
+            catch {
+                body = null;
+            }
+            const mapped = mapMcpError(response.status, body);
+            throw new Error(mapped.error ?? `MCP ${method} failed: HTTP ${response.status}`);
+        }
+        const body = (await response.json());
+        if (body.error) {
+            const mapped = mapMcpError(500, body);
+            throw new Error(mapped.error ?? `MCP ${method} failed`);
+        }
+        return body.result;
+    }
     async ensureInitialized(request) {
         if (this.initialized)
             return;

package/dist/tool/skill-dir-infer.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 推断 harness 用的技能包根：命令里的绝对路径、本批/历史 read_file、bind、唯一技能。
+ * 不写 GraphState.activatedSkill。
+ */
+import { type SkillDirRef } from '../graph/adapters/skill-read.js';
+import type { GraphMessage } from '../graph/contracts/executable-graph.js';
+export declare function longestSkillDirInText(text: string, skillDirs: SkillDirRef[]): string | undefined;
+export declare function inferHarnessSkillDir(opts: {
+    command?: string;
+    toolCalls?: Array<{
+        name?: string;
+        arguments?: Record<string, unknown>;
+    }>;
+    messages?: GraphMessage[];
+    skillDirs: SkillDirRef[];
+    activatedSkill?: string | null;
+}): string | undefined;

package/dist/tool/skill-dir-infer.js

@@ -0,0 +1,81 @@
+/**
+ * 推断 harness 用的技能包根：命令里的绝对路径、本批/历史 read_file、bind、唯一技能。
+ * 不写 GraphState.activatedSkill。
+ */
+import { classifySkillRead } from '../graph/adapters/skill-read.js';
+import { normalizeSkillDir } from './skill-script-refs.js';
+export function longestSkillDirInText(text, skillDirs) {
+    const hay = text.replace(/\\/g, '/');
+    let best;
+    for (const dir of skillDirs) {
+        if (!dir.bundlePath)
+            continue;
+        const root = normalizeSkillDir(dir.bundlePath);
+        if (root && hay.includes(root) && (!best || root.length > best.len)) {
+            best = { bundlePath: dir.bundlePath, len: root.length };
+        }
+    }
+    return best?.bundlePath;
+}
+function bundleForSkillId(skillId, skillDirs) {
+    return skillDirs.find((dir) => dir.skillId === skillId)?.bundlePath;
+}
+function lastReadSkillDir(toolCalls, skillDirs) {
+    if (!toolCalls?.length)
+        return undefined;
+    let found;
+    for (const tc of toolCalls) {
+        const hit = classifySkillRead(tc.name ?? '', tc.arguments, skillDirs);
+        if (hit?.skillId) {
+            const bundle = bundleForSkillId(hit.skillId, skillDirs);
+            if (bundle)
+                found = bundle;
+        }
+    }
+    return found;
+}
+function inferFromMessages(messages, skillDirs) {
+    if (!messages?.length)
+        return undefined;
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const msg = messages[i];
+        if (msg.role === 'assistant' && msg.toolCalls?.length) {
+            const found = lastReadSkillDir(msg.toolCalls.map((tc) => ({ name: tc.name, arguments: tc.arguments })), skillDirs);
+            if (found)
+                return found;
+        }
+        if (msg.role === 'tool' && typeof msg.content === 'string') {
+            const tagged = msg.content.match(/技能包根（只读）([^\s。]+)|EAP_SKILL_DIR=([^\s。]+)/);
+            const dir = tagged?.[1] ?? tagged?.[2];
+            if (dir) {
+                const norm = normalizeSkillDir(dir);
+                const hit = skillDirs.find((d) => d.bundlePath && normalizeSkillDir(d.bundlePath) === norm);
+                if (hit?.bundlePath)
+                    return hit.bundlePath;
+            }
+            const fromBody = longestSkillDirInText(msg.content, skillDirs);
+            if (fromBody)
+                return fromBody;
+        }
+    }
+    return undefined;
+}
+export function inferHarnessSkillDir(opts) {
+    const dirs = opts.skillDirs.filter((dir) => Boolean(dir.bundlePath));
+    if (opts.command) {
+        const fromCommand = longestSkillDirInText(opts.command, dirs);
+        if (fromCommand)
+            return fromCommand;
+    }
+    const fromBatch = lastReadSkillDir(opts.toolCalls, dirs);
+    if (fromBatch)
+        return fromBatch;
+    const fromHistory = inferFromMessages(opts.messages, dirs);
+    if (fromHistory)
+        return fromHistory;
+    if (dirs.length === 1)
+        return dirs[0].bundlePath;
+    if (opts.activatedSkill)
+        return bundleForSkillId(opts.activatedSkill, dirs);
+    return undefined;
+}

package/dist/tool/skill-script-refs.d.ts

@@ -6,15 +6,8 @@
  */
 export declare const EAP_SKILL_DIR_ENV = "EAP_SKILL_DIR";
 export interface ExpandSkillRefsOptions {
-    platform?: string;
     exists?: (absPath: string) => boolean;
 }
 export declare function normalizeSkillDir(skillDir: string): string;
-export declare function skillEnvRef(platform?: string): string;
-/**
- * 包内相对脚本路径 → 技能目录绝对路径。
- * 带目录或 `./` 的（`bin/foo.py`、`./main.py`、`scripts/a.py`）一律展开。
- * 根上的裸文件名（`main.py`）仅当包内确实有该文件才展开，以免改写「写到用户目录再跑」的例子。
- */
-export declare function expandSkillScriptRefs(body: string, skillDir: string, platformOrOpts?: string | ExpandSkillRefsOptions): string;
+export declare function expandSkillScriptRefs(body: string, skillDir: string, opts?: ExpandSkillRefsOptions): string;
 export declare function isSkillEntryFile(filePath: string): boolean;

package/dist/tool/skill-script-refs.js

@@ -13,14 +13,6 @@ const RELATIVE_CODE_PATH = new RegExp(`(^|[^$\\w./\\\\:%])(\\.\\/)?((?:[\\w.-]+[
 export function normalizeSkillDir(skillDir) {
     return skillDir.replace(/\\/g, '/').replace(/\/+$/, '');
 }
-export function skillEnvRef(platform = process.platform) {
-    return platform === 'win32' ? `%${EAP_SKILL_DIR_ENV}%` : `$${EAP_SKILL_DIR_ENV}`;
-}
-function asOptions(platformOrOpts) {
-    if (typeof platformOrOpts === 'string')
-        return { platform: platformOrOpts };
-    return platformOrOpts ?? {};
-}
 function defaultExists(absPath) {
     try {
         return existsSync(absPath);
@@ -34,12 +26,37 @@ function defaultExists(absPath) {
  * 带目录或 `./` 的（`bin/foo.py`、`./main.py`、`scripts/a.py`）一律展开。
  * 根上的裸文件名（`main.py`）仅当包内确实有该文件才展开，以免改写「写到用户目录再跑」的例子。
  */
-export function expandSkillScriptRefs(body, skillDir, platformOrOpts) {
-    const opts = asOptions(platformOrOpts);
-    const platform = opts.platform ?? process.platform;
-    const exists = opts.exists ?? defaultExists;
+function resolvePackageRelativePath(rel, skillDir, exists = defaultExists) {
+    const raw = rel.trim();
+    if (!raw || raw.startsWith('#') || raw.includes('://'))
+        return undefined;
+    if (path.isAbsolute(raw) || /^[A-Za-z]:[\\/]/.test(raw))
+        return undefined;
+    if (raw.startsWith('$') || raw.startsWith('%'))
+        return undefined;
+    const relNorm = raw.replace(/\\/g, '/').replace(/^\.\//, '');
+    if (!relNorm || !/\.[A-Za-z0-9]{1,8}$/.test(relNorm))
+        return undefined;
+    const abs = path.resolve(skillDir, relNorm);
+    if (!exists(abs))
+        return undefined;
+    return normalizeSkillDir(abs);
+}
+function expandPackageFileRefs(body, skillDir, exists) {
+    return body.replace(/\]\(([^)]+)\)|`([^`\n]+)`/g, (full, linkDest, tickDest) => {
+        const raw = (linkDest ?? tickDest ?? '').trim();
+        const abs = resolvePackageRelativePath(raw, skillDir, exists);
+        if (!abs)
+            return full;
+        if (linkDest != null)
+            return `](${abs})`;
+        return `\`${abs}\``;
+    });
+}
+export function expandSkillScriptRefs(body, skillDir, opts) {
+    const exists = opts?.exists ?? defaultExists;
     const dir = normalizeSkillDir(skillDir);
-    const expanded = body.replace(RELATIVE_CODE_PATH, (full, prefix, dotSlash, rel) => {
+    let expanded = body.replace(RELATIVE_CODE_PATH, (full, prefix, dotSlash, rel) => {
         const relNorm = rel.replace(/\\/g, '/');
         const packageRelative = Boolean(dotSlash) || relNorm.includes('/');
         if (!packageRelative && !exists(path.join(skillDir, relNorm))) {
@@ -47,15 +64,10 @@ export function expandSkillScriptRefs(body, skillDir, platformOrOpts) {
         }
         return `${prefix}${dir}/${relNorm}`;
     });
-    const envRef = skillEnvRef(platform);
-    const envPath = platform === 'win32' ? `${envRef}\\<相对路径>` : `${envRef}/<相对路径>`;
-    const note = `技能目录（只读）环境变量 ${EAP_SKILL_DIR_ENV}=${dir}。` +
-        `包内任意文件用 ${envPath}（不限 scripts/）。` +
-        `读入正文里像包内脚本的相对路径已展开为绝对路径。` +
-        `当前工作目录是用户目录，相对路径写出在用户目录。\n\n`;
+    expanded = expandPackageFileRefs(expanded, skillDir, exists);
     if (body.includes(`${EAP_SKILL_DIR_ENV}=`))
         return expanded;
-    return note + expanded;
+    return `技能包根（只读）${dir}。\n\n` + expanded;
 }
 export function isSkillEntryFile(filePath) {
     return /(^|[\\/])(SKILL\.md|skill\.md)$/i.test(filePath);