@gt-fe/eap-runtime 0.0.8

package/dist/registry/graph-loader.js

@@ -0,0 +1,985 @@
+/**
+ * GraphLoader — 从 Agent Registry / Deployment 预装快照加载 Graph DSL 与 Tool/Skill 定义
+ *
+ * 生产（server + EAP_PREINSTALL_ROOT）：以预装为准，缺失则失败（04 Req 8.1）。
+ * 开发态：Registry + 可选 ./tools 本地 manifest。
+ */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { resolveAgentModelAllowlist, resolveAgentPrimaryModel } from './agent-models.js';
+import { createDeploymentSnapshotFromEnv, isInlineToolDeclaration, overlayToolRefPolicies, } from './deployment-snapshot.js';
+import { preloadGraphNotFound, preloadManifestNotFound, preloadSkillNotFound, preloadToolNotFound, } from './preload-errors.js';
+import { PreinstallDefinitionCache, resolveDefinitionCacheEnabled, } from './definition-cache.js';
+import { inspectAgentSkillTree, readSkillAssembly, resolveSkillHotReload, skillAssemblyStamp, } from './skill-tree.js';
+function applyPrimaryModelToGraph(graph, primary) {
+    if (!primary)
+        return graph;
+    let changed = false;
+    const nodes = graph.nodes.map((node) => {
+        if (node.type !== 'llm')
+            return node;
+        const current = typeof node.config?.model === 'string' ? node.config.model.trim() : '';
+        if (current && current.toLowerCase() !== 'default')
+            return node;
+        changed = true;
+        return { ...node, config: { ...node.config, model: primary } };
+    });
+    return changed ? { ...graph, nodes } : graph;
+}
+function assertGraphModelsAllowed(graph, manifest) {
+    const allowlist = resolveAgentModelAllowlist((manifest ?? {}));
+    if (allowlist.length === 0)
+        return graph;
+    for (const node of graph.nodes) {
+        if (node.type !== 'llm')
+            continue;
+        const model = typeof node.config?.model === 'string' ? node.config.model.trim() : '';
+        if (model && !allowlist.includes(model)) {
+            throw new Error(`Graph llm node "${node.id}" uses undeclared model "${model}". Allowed: ${allowlist.join(', ')}`);
+        }
+    }
+    return graph;
+}
+function finalizeLoadedGraph(graph, manifest) {
+    return assertGraphModelsAllowed(applyPrimaryModelToGraph(graph, resolveAgentPrimaryModel((manifest ?? {}))), manifest);
+}
+function asGraphDsl(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const obj = value;
+    if (Array.isArray(obj.nodes))
+        return obj;
+    const nested = obj.graph;
+    if (nested && typeof nested === 'object' && !Array.isArray(nested) && Array.isArray(nested.nodes)) {
+        return nested;
+    }
+    return undefined;
+}
+function extractSkillPrompt(manifest) {
+    const prompt = manifest.prompt;
+    if (typeof prompt === 'string' && prompt.trim())
+        return prompt;
+    if (prompt && typeof prompt === 'object' && !Array.isArray(prompt)) {
+        const system = prompt.system;
+        if (typeof system === 'string' && system.trim())
+            return system;
+    }
+    if (typeof manifest.systemPrompt === 'string' && manifest.systemPrompt.trim()) {
+        return manifest.systemPrompt;
+    }
+    return undefined;
+}
+/**
+ * 解析 Skill prompt：如果以 ./ 开头则视为相对 bundlePath 的文件路径，同步读取内容。
+ * .md 文件含 YAML frontmatter 时剔除，只取正文（frontmatter 仅供构建期生成 manifest）。
+ * 在 loadSkillDefinitions 中调用（异步版本）。
+ */
+async function resolveSkillPrompt(manifest, bundlePath) {
+    const raw = extractSkillPrompt(manifest);
+    if (!raw)
+        return undefined;
+    if (raw.startsWith('./') || raw.startsWith('.\\')) {
+        try {
+            let content = await readFile(path.resolve(bundlePath, raw), 'utf-8');
+            // 剔除 YAML frontmatter（--- ... --- 头部块）
+            const fmMatch = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/);
+            if (fmMatch)
+                content = content.slice(fmMatch[0].length);
+            return content.trim() || undefined;
+        }
+        catch {
+            // 文件不存在时回退为原始字符串
+            return raw;
+        }
+    }
+    return raw;
+}
+/**
+ * 解析 Skill scripts[] 为虚拟 Tool 定义。
+ * scripts 为可选/非标字段：Skill 包仅强制要求 skill.md，其余文件结构不限；
+ * 存在 scripts 声明时才物化为可调用的本地 Tool。
+ */
+function resolveSkillScripts(manifest, bundlePath) {
+    const scripts = manifest.scripts;
+    if (!Array.isArray(scripts))
+        return [];
+    const tools = [];
+    for (const script of scripts) {
+        if (!script || typeof script !== 'object')
+            continue;
+        const s = script;
+        const name = s.name;
+        const command = s.command;
+        if (!name || !command)
+            continue;
+        const args = Array.isArray(s.args) ? s.args.map(String) : [];
+        tools.push({
+            toolId: `script:${name}`,
+            name,
+            manifest: {
+                id: `script:${name}`,
+                name,
+                version: '0.0.0',
+                type: 'code',
+                status: 'active',
+                description: s.description ?? `Skill script: ${name}`,
+                execution: {
+                    runtime: command === 'python3' || command === 'python' ? 'python'
+                        : command === 'node' ? 'node'
+                            : 'executable',
+                    handler: args[0] ?? command,
+                    args: args.slice(1),
+                    timeout: 30000,
+                    sandbox: false,
+                    bundlePath,
+                    command,
+                    /** 标记为 Skill 虚拟脚本：Router 优先本机执行，不经 Gateway */
+                    localPreferred: true,
+                    source: 'skill-script',
+                },
+            },
+            inputSchema: { type: 'object', properties: {}, additionalProperties: true },
+        });
+    }
+    return tools;
+}
+function extractSkillToolRefs(manifest) {
+    const refs = manifest.toolRefs ?? manifest.tools;
+    if (!Array.isArray(refs))
+        return undefined;
+    const out = [];
+    for (const item of refs) {
+        if (typeof item === 'string') {
+            out.push(item);
+            continue;
+        }
+        if (!item || typeof item !== 'object')
+            continue;
+        const o = item;
+        out.push({
+            toolId: o.toolId != null ? String(o.toolId) : undefined,
+            name: o.name != null ? String(o.name) : o.toolset != null ? String(o.toolset) : undefined,
+            version: o.version != null ? String(o.version) : undefined,
+            toolset: o.toolset != null ? String(o.toolset) : undefined,
+            enabledTools: Array.isArray(o.enabledTools)
+                ? o.enabledTools.filter((x) => typeof x === 'string')
+                : undefined,
+            autoApprove: Array.isArray(o.autoApprove)
+                ? o.autoApprove.filter((x) => typeof x === 'string')
+                : undefined,
+        });
+    }
+    return out.length > 0 ? out : undefined;
+}
+function extractEmbeddedGraph(manifest) {
+    const candidates = [
+        manifest.graph,
+        manifest.graphYaml,
+        manifest.metadata?.graph,
+        manifest.metadata?.graphYaml,
+    ];
+    for (const candidate of candidates) {
+        if (candidate && typeof candidate === 'object' && !Array.isArray(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+const DEFAULT_GRAPH_DSL = {
+    name: 'default-agent-graph',
+    version: '1.0.0',
+    state: { messages: 'array' },
+    nodes: [
+        { id: 'llm', type: 'llm', config: { model: 'default' } },
+    ],
+    edges: [
+        { from: '__start__', to: 'llm' },
+        { from: 'llm', to: '__end__' },
+    ],
+    entryPoint: 'llm',
+    finishPoints: ['__end__'],
+    config: { timeout: 60000 },
+};
+function yamlGraphToDsl(agentCode, graph) {
+    const nodes = graph.nodes ?? [];
+    const edges = graph.edges ?? [];
+    return {
+        name: agentCode,
+        version: '1.0.0',
+        state: { messages: 'array' },
+        nodes,
+        edges,
+        conditionalEdges: graph.conditionalEdges,
+        entryPoint: graph.entryPoint ?? nodes[0]?.id ?? 'llm',
+        finishPoints: ['__end__'],
+        config: { timeout: 60000 },
+    };
+}
+function collectToolNames(agent, graphDsl) {
+    const rawTools = agent?.manifest?.tools ?? [];
+    // 支持 string[] (ID 引用) 和 object[] (完整 ToolManifest 内联声明)
+    const fromAgent = rawTools.map((t) => typeof t === 'string' ? t : t?.name ?? t?.id);
+    const fromGraph = graphDsl.nodes
+        .filter((n) => n.type === 'tool')
+        .map((n) => n.config?.['tool'] ?? n.id);
+    return [...new Set([...fromAgent, ...fromGraph].filter(Boolean))];
+}
+function normalizeDataScope(raw) {
+    if (raw === 'user-bound' || raw === 'department-bound' || raw === 'global')
+        return raw;
+    if (raw === 'department')
+        return 'department-bound';
+    return undefined;
+}
+/** 跨 toolset 子工具同名时保留先到者并告警，避免静默丢弃 */
+function warnDuplicateToolSkip(existing, incoming) {
+    console.warn(`[preload] duplicate tool name "${incoming.name}": keep toolId=${existing.toolId}, skip toolId=${incoming.toolId}`);
+}
+function tryAddLoadedTool(definitions, byName, def) {
+    const existing = byName.get(def.name);
+    if (existing) {
+        if (existing.toolId !== def.toolId) {
+            warnDuplicateToolSkip(existing, def);
+        }
+        return false;
+    }
+    definitions.push(def);
+    byName.set(def.name, def);
+    return true;
+}
+function toLoadedToolDefinition(record) {
+    const manifest = record.manifest;
+    const m = manifest;
+    const permissions = m.permissions;
+    const metadata = m.metadata;
+    const manifestRef = {
+        id: String(m.id ?? record.id),
+        name: String(m.name ?? record.name),
+        version: String(m.version ?? record.version),
+        type: m.type ?? 'code',
+        status: record.status,
+        toolRuntime: (m.toolRuntime ?? m.runtime),
+        dataScope: normalizeDataScope(permissions?.dataScope),
+        requireConfirmation: Boolean(metadata?.require_confirmation ?? m.require_confirmation),
+        execution: m.execution,
+    };
+    return {
+        toolId: record.id,
+        name: record.name,
+        manifest: manifestRef,
+        inputSchema: m.input,
+    };
+}
+function fromPreinstallTool(pre) {
+    const m = pre.manifest;
+    const permissions = m.permissions;
+    const metadata = m.metadata;
+    return {
+        toolId: pre.toolId,
+        name: pre.name,
+        manifest: {
+            id: pre.toolId,
+            name: pre.name,
+            version: pre.version,
+            type: m.type ?? 'code',
+            status: 'active',
+            description: m.description,
+            toolRuntime: (m.toolRuntime ?? m.runtime),
+            dataScope: normalizeDataScope(permissions?.dataScope),
+            requireConfirmation: Boolean(metadata?.require_confirmation ?? m.require_confirmation),
+            execution: {
+                ...((() => {
+                    const raw = m.execution;
+                    return raw && typeof raw === 'object' && !Array.isArray(raw)
+                        ? raw
+                        : {};
+                })()),
+                bundlePath: pre.bundlePath,
+            },
+        },
+        inputSchema: m.input,
+    };
+}
+/**
+ * 展开预装工具集（toolset.manifest.json，含 tools[]）为多个 LoadedToolDefinition。
+ * 以工具集为管理单元：单个 MCP 服务 / 单个代码包 = 一个工具集，可含多个子工具；
+ * 子工具继承集级 server/package 配置，合成各自的 execution。
+ * 无 tools[] 时回退为单工具 manifest（tool.manifest.json 结构）。
+ * enabledTools 为可选白名单（agent.manifest toolRefs）；缺省启用全部子工具。
+ */
+function expandPreinstallToolset(pre, options) {
+    const m = pre.manifest;
+    const tools = m.tools;
+    const enabled = options?.enabledTools;
+    const enabledSet = enabled && enabled.length > 0 ? new Set(enabled) : null;
+    const autoApproveSet = options?.autoApprove && options.autoApprove.length > 0
+        ? new Set(options.autoApprove)
+        : null;
+    if (!Array.isArray(tools) || tools.length === 0 || typeof tools[0] !== 'object') {
+        if (enabledSet && !enabledSet.has(pre.name) && !enabledSet.has(pre.toolId)) {
+            return [];
+        }
+        const single = fromPreinstallTool(pre);
+        if (autoApproveSet?.has(single.name)) {
+            single.manifest.requireConfirmation = false;
+        }
+        return [single];
+    }
+    const setType = m.type;
+    const toolRuntime = (m.toolRuntime ?? m.runtime);
+    const server = m.server;
+    const pkg = m.package;
+    const out = [];
+    for (const raw of tools) {
+        const st = raw;
+        const name = typeof st.name === 'string' ? st.name : '';
+        if (!name)
+            continue;
+        if (enabledSet && !enabledSet.has(name))
+            continue;
+        let type;
+        let execution;
+        if (setType === 'http') {
+            const gateway = (m.gateway ?? {});
+            type = 'http';
+            execution = {
+                protocol: 'http',
+                method: st.method ?? 'GET',
+                baseUrl: st.baseUrl ?? gateway.baseUrl,
+                pathTemplate: st.pathTemplate,
+                allowedHosts: gateway.allowedHosts,
+                timeout: st.timeout ?? gateway.timeout ?? 10000,
+            };
+        }
+        else if (setType === 'mcp') {
+            type = 'mcp';
+            execution = {
+                protocol: 'mcp',
+                transport: server?.transport ?? (server?.url ? 'streamable_http' : 'stdio'),
+                server,
+                toolName: name,
+                timeout: st.timeout ?? server?.timeout ?? 30000,
+            };
+        }
+        else {
+            type = 'code';
+            execution = {
+                runtime: st.runtime ?? 'node',
+                handler: st.handler,
+                args: st.args,
+                timeout: st.timeout ?? 30000,
+                sandbox: st.sandbox ?? pkg?.sandbox ?? false,
+                bundlePath: pre.bundlePath,
+            };
+        }
+        const requireConfirmation = autoApproveSet?.has(name)
+            ? false
+            : Boolean(st.requireConfirmation);
+        out.push({
+            toolId: `${pre.toolId}:${name}`,
+            name,
+            manifest: {
+                id: `${pre.toolId}:${name}`,
+                name,
+                version: pre.version,
+                type,
+                status: 'active',
+                description: st.description,
+                toolRuntime,
+                dataScope: normalizeDataScope(st.dataScope),
+                requireConfirmation,
+                execution,
+            },
+            inputSchema: st.input,
+        });
+    }
+    return out;
+}
+function fromLocalManifestFile(toolName, manifest) {
+    const permissions = manifest.permissions;
+    const metadata = manifest.metadata;
+    const manifestRef = {
+        id: String(manifest.id ?? toolName),
+        name: String(manifest.name ?? toolName),
+        version: String(manifest.version ?? '0.0.0'),
+        type: manifest.type ?? 'code',
+        status: 'active',
+        toolRuntime: (manifest.toolRuntime ?? manifest.runtime),
+        dataScope: normalizeDataScope(permissions?.dataScope),
+        requireConfirmation: Boolean(metadata?.require_confirmation),
+        execution: manifest.execution,
+    };
+    return {
+        toolId: String(manifest.id ?? toolName),
+        name: String(manifest.name ?? toolName),
+        manifest: manifestRef,
+        inputSchema: manifest.input,
+    };
+}
+/**
+ * 从内联 Tool 声明（manifest.tools 中的完整 ToolManifest 对象）
+ * 转为 LoadedToolDefinition。
+ *
+ * 支持 eap.yaml / agent.manifest.json 中直接嵌入工具完整定义（含 execution、input 等），
+ * 适用于本地开发无 Registry / 无预装快照的场景。
+ */
+function fromInlineToolDeclaration(tool) {
+    const permissions = tool.permissions;
+    const metadata = tool.metadata;
+    const id = String(tool.id ?? tool.name ?? 'unknown');
+    const name = String(tool.name ?? tool.id ?? 'unknown');
+    return {
+        toolId: id,
+        name,
+        manifest: {
+            id,
+            name,
+            version: String(tool.version ?? '0.0.0'),
+            type: tool.type ?? 'code',
+            description: tool.description,
+            status: 'active',
+            toolRuntime: (tool.toolRuntime ?? tool.runtime),
+            dataScope: normalizeDataScope(permissions?.dataScope),
+            requireConfirmation: Boolean(metadata?.require_confirmation),
+            execution: tool.execution,
+        },
+        inputSchema: tool.input,
+    };
+}
+async function loadDevLocalManifest(toolName, toolsDir) {
+    const manifestPath = path.join(toolsDir, toolName, 'tool.manifest.json');
+    try {
+        const raw = await readFile(manifestPath, 'utf-8');
+        const manifest = JSON.parse(raw);
+        return fromLocalManifestFile(toolName, manifest);
+    }
+    catch {
+        return null;
+    }
+}
+function fromLocalInstall(install) {
+    return {
+        toolId: install.toolId,
+        name: install.toolName,
+        manifest: {
+            id: install.toolId,
+            name: install.toolName,
+            version: install.version,
+            type: install.type,
+            status: install.installStatus === 'ready' ? 'active' : install.installStatus,
+            toolRuntime: 'both',
+        },
+    };
+}
+export class GraphLoader {
+    registryClient;
+    deploymentContext;
+    localInstallStore;
+    localToolsDir;
+    localSkillsDir;
+    deploymentSnapshot;
+    strictPreinstall;
+    agentVersion;
+    definitionCacheEnabled;
+    definitionCache = new PreinstallDefinitionCache();
+    skillHotReload;
+    constructor(config = {}) {
+        this.registryClient = config.registryClient;
+        this.deploymentContext = config.deploymentContext ?? 'server';
+        this.localInstallStore = config.localInstallStore;
+        this.localToolsDir = config.localToolsDir;
+        this.localSkillsDir = resolveLocalSkillsDir(config.localSkillsDir);
+        this.deploymentSnapshot =
+            config.deploymentSnapshot ??
+                createDeploymentSnapshotFromEnv(config.preinstallRoot, {
+                    requireReady: config.requireReady,
+                    requireChecksum: config.requireChecksum,
+                });
+        this.agentVersion = config.agentVersion ?? process.env.EAP_AGENT_VERSION;
+        const hasPreinstall = Boolean(this.deploymentSnapshot);
+        this.strictPreinstall =
+            config.strictPreinstall ??
+                (this.deploymentContext === 'server' && hasPreinstall);
+        this.definitionCacheEnabled = resolveDefinitionCacheEnabled(hasPreinstall, config.definitionCache);
+        this.skillHotReload = resolveSkillHotReload(this.deploymentContext, config.skillHotReload);
+    }
+    /** 严格预装：禁止用 Registry 拉可执行定义 */
+    get blockRegistryDefinitions() {
+        return this.strictPreinstall && Boolean(this.deploymentSnapshot);
+    }
+    resolveVersion(options) {
+        return options?.agentVersion ?? this.agentVersion;
+    }
+    /**
+     * 缓存主键版本：显式 version 优先；未传时落到 snapshot.version，
+     * 避免 warm(`1.0.0`) 与 load(无 version→@auto) 分属两个键。
+     */
+    async pinCacheVersion(agentCode, requested) {
+        if (requested)
+            return requested;
+        if (!this.deploymentSnapshot)
+            return undefined;
+        try {
+            const snap = await this.deploymentSnapshot.loadAgentSnapshot(agentCode, undefined);
+            return snap?.version;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    useCache(options) {
+        return this.definitionCacheEnabled && !options?.bypassCache;
+    }
+    /** 上线 / 发版后预热进程内定义（模型 C） */
+    async warmAgent(agentCode, options) {
+        const loadOpts = { ...options, bypassCache: true };
+        const version = await this.pinCacheVersion(agentCode, this.resolveVersion(options));
+        const skillWarnings = [];
+        const skippedSkills = [];
+        // 分步落缓存：skills 失败不得拖垮 graph/tools 预热（Hosting 预热通常无 userId）
+        const graph = await this.loadGraph(agentCode, loadOpts);
+        this.definitionCache.setGraph(agentCode, version, graph);
+        const tools = await this.loadToolDefinitions(agentCode, { ...loadOpts, activeOnly: true });
+        this.definitionCache.setTools(agentCode, version, tools);
+        let skillsOk = false;
+        try {
+            const skills = await this.loadSkillDefinitions(agentCode, {
+                ...loadOpts,
+                userId: options?.userId,
+                allowMissingSkills: true,
+                onMissingSkill: (skillId) => {
+                    skippedSkills.push(skillId);
+                    skillWarnings.push(skillId);
+                },
+            });
+            const stamp = await this.skillTreeStamp(agentCode, version, options?.userId);
+            this.definitionCache.setSkills(agentCode, version, options?.userId, skills, stamp);
+            skillsOk = true;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            skillWarnings.push(message);
+            console.warn(JSON.stringify({
+                event: 'runtime.warmAgent.skills_failed',
+                level: 'warn',
+                agentCode,
+                agentVersion: version ?? null,
+                message,
+            }));
+        }
+        // 预期跳过（无 userId 的 users 层 Skill）用 debug，避免单测/生产噪音
+        if (skippedSkills.length > 0) {
+            console.debug(JSON.stringify({
+                event: 'runtime.warmAgent.skills_skipped',
+                level: 'debug',
+                agentCode,
+                agentVersion: version ?? null,
+                userId: options?.userId ?? null,
+                skippedSkillIds: skippedSkills,
+            }));
+        }
+        console.info(JSON.stringify({
+            event: 'runtime.warmAgent.ok',
+            level: 'info',
+            agentCode,
+            agentVersion: version ?? null,
+            graph: true,
+            tools: true,
+            skills: skillsOk,
+            skillWarningCount: skillWarnings.length,
+            skillWarnings,
+        }));
+        return {
+            graph: true,
+            tools: true,
+            skills: skillsOk,
+            skillWarnings,
+        };
+    }
+    /** 版本切换 / 下线时失效缓存 */
+    invalidateAgent(agentCode, agentVersion) {
+        this.definitionCache.invalidate(agentCode, agentVersion);
+    }
+    invalidateAllDefinitions() {
+        this.definitionCache.invalidateAll();
+    }
+    definitionCacheSize() {
+        return this.definitionCache.size();
+    }
+    cloneCached(value) {
+        if (typeof globalThis.structuredClone === 'function') {
+            return globalThis.structuredClone(value);
+        }
+        return JSON.parse(JSON.stringify(value));
+    }
+    async loadGraph(agentCode, options) {
+        const requested = this.resolveVersion(options);
+        const version = await this.pinCacheVersion(agentCode, requested);
+        if (this.useCache(options)) {
+            const hit = this.definitionCache.get(agentCode, version);
+            if (hit?.graph) {
+                return this.cloneCached(hit.graph);
+            }
+        }
+        const graph = await this.loadGraphFromSource(agentCode, requested);
+        if (this.useCache(options)) {
+            this.definitionCache.setGraph(agentCode, version, graph);
+        }
+        return this.cloneCached(graph);
+    }
+    async loadGraphFromSource(agentCode, version) {
+        if (this.deploymentSnapshot) {
+            const snap = await this.deploymentSnapshot.loadAgentSnapshot(agentCode, version);
+            if (!snap) {
+                if (this.blockRegistryDefinitions) {
+                    throw preloadManifestNotFound(`预装 Agent 目录不存在: ${agentCode}${version ? `@${version}` : ''}`);
+                }
+            }
+            else {
+                if (snap.graph && typeof snap.graph === 'object') {
+                    return finalizeLoadedGraph(yamlGraphToDsl(agentCode, snap.graph), snap.manifest ?? {});
+                }
+                if (this.blockRegistryDefinitions) {
+                    throw preloadGraphNotFound(`预装 Graph 定义缺失: agent=${agentCode}`);
+                }
+            }
+        }
+        if (this.blockRegistryDefinitions) {
+            throw preloadGraphNotFound(`严格预装模式下无法加载 Graph: agent=${agentCode}`);
+        }
+        if (!this.registryClient) {
+            return { ...DEFAULT_GRAPH_DSL, name: agentCode };
+        }
+        const record = await this.registryClient.getAgent(agentCode);
+        if (!record?.manifest) {
+            return { ...DEFAULT_GRAPH_DSL, name: agentCode };
+        }
+        const manifest = record.manifest;
+        const graphFromManifest = extractEmbeddedGraph(manifest);
+        if (graphFromManifest && typeof graphFromManifest === 'object') {
+            return finalizeLoadedGraph(yamlGraphToDsl(agentCode, graphFromManifest), manifest);
+        }
+        const model = resolveAgentPrimaryModel(manifest) ?? 'default';
+        return {
+            ...DEFAULT_GRAPH_DSL,
+            name: agentCode,
+            nodes: [
+                {
+                    id: 'llm',
+                    type: 'llm',
+                    config: {
+                        model,
+                        systemPrompt: manifest.prompts?.system,
+                    },
+                },
+            ],
+            config: {
+                timeout: manifest.config?.timeout ?? 60000,
+                maxRetries: manifest.config?.retryCount,
+            },
+        };
+    }
+    /**
+     * 解析 agent tools[] + graph tool 节点 union；
+     * server+预装：以预装 manifest 为准；desktop 合并 ILocalToolInstallStore。
+     */
+    async loadToolDefinitions(agentCode, options = {}) {
+        const requested = this.resolveVersion(options);
+        const version = await this.pinCacheVersion(agentCode, requested);
+        if (this.useCache(options)) {
+            const hit = this.definitionCache.get(agentCode, version);
+            if (hit?.tools !== undefined) {
+                return this.cloneCached(hit.tools);
+            }
+        }
+        const tools = await this.loadToolDefinitionsFromSource(agentCode, options, requested);
+        if (this.useCache(options)) {
+            this.definitionCache.setTools(agentCode, version, tools);
+        }
+        return this.cloneCached(tools);
+    }
+    async loadToolDefinitionsFromSource(agentCode, options, version) {
+        const activeOnly = options.activeOnly !== false;
+        const graphDsl = await this.loadGraph(agentCode, {
+            agentVersion: version,
+            bypassCache: options.bypassCache,
+        });
+        const definitions = [];
+        const byName = new Map();
+        const snap = this.deploymentSnapshot
+            ? await this.deploymentSnapshot.loadAgentSnapshot(agentCode, version)
+            : null;
+        const agentDir = snap?.agentDir
+            ?? (this.deploymentSnapshot
+                ? await this.deploymentSnapshot.resolveAgentDir(agentCode, version)
+                : null);
+        // 本地 agent.manifest 内联完整 ToolManifest（含 type/execution）；装配引用走预装展开
+        const localManifestTools = snap?.manifest?.tools;
+        if (Array.isArray(localManifestTools) && localManifestTools.length > 0) {
+            for (const tool of localManifestTools) {
+                if (!isInlineToolDeclaration(tool))
+                    continue;
+                const def = fromInlineToolDeclaration(tool);
+                tryAddLoadedTool(definitions, byName, def);
+            }
+        }
+        const agent = !this.blockRegistryDefinitions && this.registryClient
+            ? await this.registryClient.getAgent(agentCode)
+            : null;
+        // ── 提取 Registry manifest 内联 tools（非严格预装）──
+        const manifestTools = agent?.manifest?.tools;
+        if (Array.isArray(manifestTools) && manifestTools.length > 0) {
+            for (const tool of manifestTools) {
+                if (!isInlineToolDeclaration(tool))
+                    continue;
+                const def = fromInlineToolDeclaration(tool);
+                tryAddLoadedTool(definitions, byName, def);
+            }
+        }
+        // [DEBUG] 加载链路诊断
+        if (process.env.EAP_LLM_DEBUG === '1') {
+            console.log('[LLM-DEBUG] loadToolDefinitions trace:', JSON.stringify({
+                agentCode,
+                agentVersion: version,
+                deploymentContext: this.deploymentContext,
+                preinstallRoot: process.env.EAP_PREINSTALL_ROOT,
+                localToolsDir: this.localToolsDir,
+                EAP_LOCAL_TOOLS_DIR: process.env.EAP_LOCAL_TOOLS_DIR,
+                hasDeploymentSnapshot: Boolean(this.deploymentSnapshot),
+                snapIsNull: !snap,
+                snapToolsCount: snap?.tools?.length ?? 0,
+                snapTools: (snap?.tools ?? []).map(t => ({ name: t.name, version: t.version })),
+                agentDir,
+            }, null, 2));
+        }
+        const snapToolRefs = overlayToolRefPolicies(snap?.tools ?? [], snap?.manifest);
+        const toolNamesFromSnap = snapToolRefs.map((t) => t.name).filter(Boolean);
+        const collectedFromGraph = collectToolNames(agent, graphDsl);
+        const toolNames = [...new Set([...collectedFromGraph, ...toolNamesFromSnap])];
+        // [DEBUG] 最终 toolNames 决策
+        if (process.env.EAP_LLM_DEBUG === '1') {
+            console.log('[LLM-DEBUG] toolNames:', JSON.stringify({
+                fromGraph: collectedFromGraph,
+                fromSnap: toolNamesFromSnap,
+                final: toolNames,
+            }));
+        }
+        if (this.deploymentSnapshot && (snapToolRefs.length > 0 || toolNames.length > 0)) {
+            const missing = [];
+            const processedToolsetNames = new Set(snapToolRefs.map((r) => r.name));
+            // 1) snapshot 引用的工具集全部加载并展开（enabledTools 白名单过滤）
+            for (const ref of snapToolRefs) {
+                const pre = await this.deploymentSnapshot.loadToolManifest(ref, agentDir);
+                if (!pre) {
+                    missing.push(ref.name);
+                    continue;
+                }
+                for (const def of expandPreinstallToolset(pre, {
+                    enabledTools: ref.enabledTools,
+                    autoApprove: ref.autoApprove,
+                })) {
+                    tryAddLoadedTool(definitions, byName, def);
+                }
+            }
+            // 2) Graph 声明但尚未命中的工具名：按名直查。
+            //    已在步骤 1 处理过的工具集名不再二次展开（避免丢掉 enabledTools 白名单）。
+            for (const toolName of toolNames) {
+                if (byName.has(toolName))
+                    continue;
+                if (processedToolsetNames.has(toolName))
+                    continue;
+                const pre = await this.deploymentSnapshot.loadToolManifest({ name: toolName }, agentDir);
+                if (!pre) {
+                    missing.push(toolName);
+                    continue;
+                }
+                for (const def of expandPreinstallToolset(pre)) {
+                    tryAddLoadedTool(definitions, byName, def);
+                }
+            }
+            if (this.strictPreinstall && missing.length > 0) {
+                throw preloadToolNotFound(`预装快照缺失 Tool: ${missing.join(', ')}（agent=${agentCode}）`, { missing, agentCode });
+            }
+        }
+        if (this.registryClient && !this.blockRegistryDefinitions) {
+            for (const toolName of toolNames) {
+                if (byName.has(toolName))
+                    continue;
+                const record = await this.registryClient.getToolByName(toolName);
+                if (!record)
+                    continue;
+                if (activeOnly && record.status !== 'active')
+                    continue;
+                tryAddLoadedTool(definitions, byName, toLoadedToolDefinition(record));
+            }
+        }
+        if (this.deploymentContext === 'dev') {
+            const toolsDir = this.localToolsDir ?? process.env.EAP_LOCAL_TOOLS_DIR ?? './tools';
+            for (const toolName of toolNames) {
+                if (byName.has(toolName))
+                    continue;
+                const localDef = await loadDevLocalManifest(toolName, toolsDir);
+                if (localDef) {
+                    tryAddLoadedTool(definitions, byName, localDef);
+                }
+            }
+        }
+        if (this.deploymentContext === 'desktop' && this.localInstallStore) {
+            const localRecords = this.localInstallStore.listReady();
+            for (const install of localRecords) {
+                if (install.installStatus !== 'ready')
+                    continue;
+                const existing = byName.get(install.toolName);
+                if (existing) {
+                    if (!existing.manifest.toolRuntime || existing.manifest.toolRuntime === 'server') {
+                        existing.manifest.toolRuntime = 'both';
+                    }
+                    continue;
+                }
+                const localDef = fromLocalInstall(install);
+                definitions.push(localDef);
+                byName.set(localDef.name, localDef);
+            }
+        }
+        // [DEBUG] 最终 definitions 汇总
+        if (process.env.EAP_LLM_DEBUG === '1') {
+            console.log('[LLM-DEBUG] loadToolDefinitions result:', JSON.stringify({
+                count: definitions.length,
+                names: definitions.map(d => d.name),
+            }));
+        }
+        return definitions;
+    }
+    /**
+     * 从预装快照加载已装配 Skill 完整定义（workflow / prompt / toolRefs）
+     * @param options.userId 用于解析 users/<userId>/skills（优先于 preinstall/skills）
+     * @param options.allowMissingSkills 缺失时跳过而非抛错（warm 预热用）
+     */
+    async loadSkillDefinitions(agentCode, options) {
+        const requested = this.resolveVersion(options);
+        const version = await this.pinCacheVersion(agentCode, requested);
+        const stamp = await this.skillTreeStamp(agentCode, version, options?.userId);
+        if (this.useCache(options) && !options?.allowMissingSkills) {
+            const hit = this.definitionCache.getSkills(agentCode, version, options?.userId, stamp);
+            if (hit)
+                return this.cloneCached(hit);
+        }
+        const skills = await this.loadSkillDefinitionsFromSource(agentCode, options, requested);
+        if (this.useCache(options)) {
+            this.definitionCache.setSkills(agentCode, version, options?.userId, skills, stamp);
+        }
+        return this.cloneCached(skills);
+    }
+    async loadSkillDefinitionsFromSource(agentCode, options, version) {
+        if (!this.deploymentSnapshot)
+            return [];
+        const snap = await this.deploymentSnapshot.loadAgentSnapshot(agentCode, version);
+        const agentDir = await this.deploymentSnapshot.resolveAgentDir(agentCode, version);
+        const refs = await this.resolveSkillRefs(snap, agentDir, options?.userId);
+        if (!refs.length)
+            return [];
+        const skills = [];
+        const userId = options?.userId;
+        const allowMissing = options?.allowMissingSkills === true;
+        for (const ref of refs) {
+            const pre = await this.deploymentSnapshot.loadSkillManifest(ref, agentDir, userId, this.localSkillRoots());
+            if (pre) {
+                const workflow = asGraphDsl(pre.manifest.workflow) ??
+                    asGraphDsl(pre.manifest.graph) ??
+                    asGraphDsl(pre.manifest.definitionSnapshot);
+                // 解析 prompt：支持文件路径引用（./ 开头）
+                const prompt = await resolveSkillPrompt(pre.manifest, pre.bundlePath);
+                // 解析 scripts[] 为虚拟 Tool
+                const scriptTools = resolveSkillScripts(pre.manifest, pre.bundlePath);
+                skills.push({
+                    skillId: pre.skillId,
+                    name: pre.name,
+                    description: pre.description,
+                    version: pre.version,
+                    workflow,
+                    prompt,
+                    toolRefs: extractSkillToolRefs(pre.manifest),
+                    inputDef: pre.manifest.inputDef,
+                    outputDef: pre.manifest.outputDef,
+                    scriptTools: scriptTools.length > 0 ? scriptTools : undefined,
+                });
+            }
+            else if (!this.strictPreinstall) {
+                skills.push({
+                    skillId: ref.skillId,
+                    name: ref.name ?? ref.skillId,
+                    description: ref.description,
+                    version: ref.version,
+                });
+            }
+            else if (allowMissing) {
+                options?.onMissingSkill?.(ref.skillId);
+            }
+            else {
+                throw preloadSkillNotFound(`预装快照缺失 Skill: ${ref.skillId}（agent=${agentCode}）`, {
+                    skillId: ref.skillId,
+                    agentCode,
+                    userId,
+                });
+            }
+        }
+        return skills;
+    }
+    async skillTreeStamp(agentCode, version, userId) {
+        if (!this.skillHotReload || !this.deploymentSnapshot)
+            return '';
+        const agentDir = await this.deploymentSnapshot.resolveAgentDir(agentCode, version);
+        if (!agentDir)
+            return '';
+        const tree = await inspectAgentSkillTree(agentDir, userId, this.localSkillRoots());
+        const assembly = await skillAssemblyStamp(agentDir, userId);
+        return `${tree.stamp}:${assembly}`;
+    }
+    /**
+     * 候选集 = 装配白名单，否则 snapshot/manifest 声明。
+     * 磁盘多出来的未声明目录不进选择清单；正文热加载仍看已装配目录的 mtime。
+     */
+    async resolveSkillRefs(snap, agentDir, userId) {
+        if (agentDir) {
+            const assembly = await readSkillAssembly(agentDir, userId);
+            if (assembly && assembly.skills.length > 0) {
+                return assembly.skills.map((skillId) => ({ skillId }));
+            }
+        }
+        const byId = new Map();
+        for (const ref of snap?.skills ?? []) {
+            if (ref.skillId)
+                byId.set(ref.skillId, ref);
+        }
+        return [...byId.values()];
+    }
+    localSkillRoots() {
+        return this.localSkillsDir ? [this.localSkillsDir] : [];
+    }
+    async resolveAgentDir(agentCode, version) {
+        if (!this.deploymentSnapshot)
+            return null;
+        return this.deploymentSnapshot.resolveAgentDir(agentCode, this.resolveVersion({ agentVersion: version }));
+    }
+    /** Agent 包目录 + 工程 prompts/（dev 作者源，与 EAP_LOCAL_SKILLS_DIR 同级） */
+    async resolvePromptRoots(agentCode, version) {
+        const roots = [];
+        const agentDir = await this.resolveAgentDir(agentCode, version);
+        if (agentDir)
+            roots.push(agentDir);
+        if (this.deploymentContext === 'dev' || this.deploymentContext === 'desktop') {
+            const explicit = process.env.EAP_LOCAL_PROMPTS_DIR?.trim();
+            if (explicit) {
+                roots.push(explicit);
+                return roots;
+            }
+            if (this.localSkillsDir)
+                roots.push(path.resolve(this.localSkillsDir, '..'));
+        }
+        return roots;
+    }
+}
+function resolveLocalSkillsDir(explicit) {
+    const candidate = explicit?.trim() || process.env.EAP_LOCAL_SKILLS_DIR?.trim();
+    return candidate || undefined;
+}