@gt-fe/eap-runtime 0.0.8 → 0.0.10

package/dist/providers/http-llm-provider.js

@@ -7,16 +7,63 @@
  * - tool_calls 解析（同步 & 流式）
  */
 import { resolveLlmModelName } from './resolve-llm-model.js';
+import { createFileLlmTurnLogFromEnv, maskApiKey } from '../debug/llm-turn-log.js';
 export class HttpLLMProvider {
     apiKey;
     baseUrl;
     defaultModel;
     timeoutMs;
+    turnLog;
     constructor(config) {
         this.apiKey = config.apiKey;
         this.baseUrl = (config.baseUrl ?? 'https://api.openai.com/v1').replace(/\/$/, '');
         this.defaultModel = config.defaultModel ?? 'DeepSeek-V4-Pro';
         this.timeoutMs = config.timeoutMs ?? 60000;
+        this.turnLog = 'turnLog' in config ? config.turnLog : createFileLlmTurnLogFromEnv();
+    }
+    async writeTurn(args) {
+        if (!this.turnLog)
+            return;
+        const model = resolveLlmModelName(args.config.model, this.defaultModel);
+        try {
+            await this.turnLog.record({
+                ...args.config.turn,
+                url: args.url,
+                model,
+                temperature: args.config.temperature,
+                maxTokens: args.config.maxTokens,
+                apiKey: maskApiKey(this.apiKey),
+                systemPrompt: args.config.systemPrompt,
+                systemSections: args.config.systemSections?.map((section) => ({
+                    id: section.id,
+                    title: section.title,
+                    chars: section.body.length,
+                    body: section.body,
+                })),
+                tools: args.config.tools?.map((tool) => tool.function.name),
+                messages: args.messages.map((message) => ({
+                    role: message.role,
+                    content: message.content,
+                    toolCallId: message.toolCallId,
+                    toolCalls: message.toolCalls,
+                })),
+                response: {
+                    content: args.response.content,
+                    toolCalls: args.response.toolCalls,
+                    reasoningContent: args.response.reasoningContent,
+                    inputTokens: args.response.inputTokens,
+                    outputTokens: args.response.outputTokens,
+                    finishReason: args.response.finishReason,
+                    error: args.response.error,
+                },
+                latencyMs: Date.now() - args.startedAt,
+            });
+        }
+        catch (err) {
+            if (process.env.EAP_LLM_DEBUG === '1') {
+                console.warn('[LLM-TURN] write failed', err);
+            }
+        }
     }
     async invoke(messages, config) {
         const body = this.buildRequestBody(messages, config, false);
@@ -52,6 +99,7 @@ export class HttpLLMProvider {
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
         const url = `${this.baseUrl}/chat/completions`;
+        const startedAt = Date.now();
         try {
             let response;
             try {
@@ -90,7 +138,7 @@ export class HttpLLMProvider {
                     usage: data.usage,
                 }, null, 2));
             }
-            return {
+            const result = {
                 content,
                 toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
                 ...(reasoningContent ? { reasoningContent } : {}),
@@ -99,6 +147,37 @@ export class HttpLLMProvider {
                 // model 字段优先级：config（用户显式配置） > data.model（网关返回，可能是路由别名如 "/mnt/fast"） > defaultModel
                 model: config.model ?? (typeof data.model === 'string' && !data.model.includes('/') ? data.model : undefined) ?? this.defaultModel,
             };
+            await this.writeTurn({
+                url,
+                messages,
+                config,
+                startedAt,
+                response: {
+                    content: result.content,
+                    toolCalls: result.toolCalls,
+                    reasoningContent: result.reasoningContent,
+                    inputTokens: result.inputTokens,
+                    outputTokens: result.outputTokens,
+                    finishReason: choice?.finish_reason,
+                },
+            });
+            return result;
+        }
+        catch (err) {
+            await this.writeTurn({
+                url,
+                messages,
+                config,
+                startedAt,
+                response: {
+                    content: '',
+                    inputTokens: 0,
+                    outputTokens: 0,
+                    finishReason: 'error',
+                    error: err instanceof Error ? err.message : String(err),
+                },
+            });
+            throw err;
         }
         finally {
             clearTimeout(timeout);
@@ -136,6 +215,13 @@ export class HttpLLMProvider {
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
         const url = `${this.baseUrl}/chat/completions`;
+        const startedAt = Date.now();
+        const contentChunks = [];
+        const reasoningChunks = [];
+        const toolCallAccumulators = new Map();
+        let inputTokens = 0;
+        let outputTokens = 0;
+        let lastFinishReason;
         try {
             let response;
             try {
@@ -163,9 +249,6 @@ export class HttpLLMProvider {
             const reader = response.body.getReader();
             const decoder = new TextDecoder();
             let buffer = '';
-            const toolCallAccumulators = new Map();
-            let inputTokens = 0;
-            let outputTokens = 0;
             let usageEmitted = false;
             let model = config.model ?? this.defaultModel;
             while (true) {
@@ -200,6 +283,8 @@ export class HttpLLMProvider {
                     }
                     const delta = chunk.choices?.[0]?.delta;
                     const finishReason = chunk.choices?.[0]?.finish_reason;
+                    if (finishReason)
+                        lastFinishReason = finishReason;
                     // 累积 tool_calls delta
                     if (delta?.tool_calls) {
                         for (const tc of delta.tool_calls) {
@@ -223,6 +308,10 @@ export class HttpLLMProvider {
                     // 产出内容 / reasoning chunk
                     const content = delta?.content ?? '';
                     const reasoningContent = typeof delta?.reasoning_content === 'string' ? delta.reasoning_content : '';
+                    if (content)
+                        contentChunks.push(content);
+                    if (reasoningContent)
+                        reasoningChunks.push(reasoningContent);
                     const isEnd = finishReason === 'stop' || finishReason === 'tool_calls';
                     const hasUsage = Boolean(chunk.usage);
                     if (content || reasoningContent || isEnd) {
@@ -281,6 +370,42 @@ export class HttpLLMProvider {
                     outputTokens,
                 }, null, 2));
             }
+            await this.writeTurn({
+                url,
+                messages,
+                config,
+                startedAt,
+                response: {
+                    content: contentChunks.join(''),
+                    toolCalls: toolCallAccumulators.size > 0
+                        ? this.finalizeToolCalls(toolCallAccumulators)
+                        : undefined,
+                    reasoningContent: reasoningChunks.length > 0 ? reasoningChunks.join('') : undefined,
+                    inputTokens,
+                    outputTokens,
+                    finishReason: lastFinishReason,
+                },
+            });
+        }
+        catch (err) {
+            await this.writeTurn({
+                url,
+                messages,
+                config,
+                startedAt,
+                response: {
+                    content: contentChunks.join(''),
+                    toolCalls: toolCallAccumulators.size > 0
+                        ? this.finalizeToolCalls(toolCallAccumulators)
+                        : undefined,
+                    reasoningContent: reasoningChunks.length > 0 ? reasoningChunks.join('') : undefined,
+                    inputTokens,
+                    outputTokens,
+                    finishReason: 'error',
+                    error: err instanceof Error ? err.message : String(err),
+                },
+            });
+            throw err;
         }
         finally {
             clearTimeout(timeout);

package/dist/providers/local-llm-provider.d.ts

@@ -3,13 +3,17 @@
  * 连接表里只带 apiKeyEnv，密钥从 process.env 读取，不进 JSON。
  */
 import type { ILLMProvider } from '../graph/nodes/llm-node.js';
+import type { ILlmTurnLog } from '../debug/llm-turn-log.js';
+import { type ModelCallDefaults } from '@gt-fe/eap-contracts';
 export interface LocalLlmConnection {
     baseUrl: string;
     apiKey: string;
+    defaults?: ModelCallDefaults;
 }
 export interface LocalLlmConnectionRef {
     baseUrl: string;
     apiKeyEnv: string;
+    defaults?: ModelCallDefaults;
 }
 export interface LocalLlmConnectionRefs {
     default?: LocalLlmConnectionRef;
@@ -24,4 +28,4 @@ export declare function parseLocalLlmConnectionRefs(env?: NodeJS.ProcessEnv): Lo
 export declare function hydrateLocalLlmConnections(refs: LocalLlmConnectionRefs, env?: NodeJS.ProcessEnv): LocalLlmConnections;
 export declare function requireLocalLlmConnections(env?: NodeJS.ProcessEnv): LocalLlmConnections;
 export declare function resolveLocalLlmConnection(connections: LocalLlmConnections, model?: string): LocalLlmConnection;
-export declare function createLocalLlmProvider(connections?: LocalLlmConnections): ILLMProvider;
+export declare function createLocalLlmProvider(connections?: LocalLlmConnections, turnLog?: ILlmTurnLog): ILLMProvider;

package/dist/providers/local-llm-provider.js

@@ -2,6 +2,7 @@
  * 本地多模型 LLM：按节点 model 选网关。仅 dev。
  * 连接表里只带 apiKeyEnv，密钥从 process.env 读取，不进 JSON。
  */
+import { mergeModelCallParams } from '@gt-fe/eap-contracts';
 import { HttpLLMProvider } from './http-llm-provider.js';
 export const LLM_CONNECTIONS_ENV = 'EAP_LLM_CONNECTIONS';
 export function parseLocalLlmConnectionRefs(env = process.env) {
@@ -41,7 +42,7 @@ export function hydrateLocalLlmConnections(refs, env = process.env) {
         const apiKey = env[ref.apiKeyEnv]?.trim();
         if (!apiKey)
             return undefined;
-        return { baseUrl: ref.baseUrl, apiKey };
+        return { baseUrl: ref.baseUrl, apiKey, defaults: ref.defaults };
     };
     const byModel = {};
     for (const [name, ref] of Object.entries(refs.byModel ?? {})) {
@@ -73,20 +74,26 @@ export function resolveLocalLlmConnection(connections, model) {
     }
     return connection;
 }
-export function createLocalLlmProvider(connections = requireLocalLlmConnections()) {
-    return new LocalLlmProvider(connections);
+export function createLocalLlmProvider(connections = requireLocalLlmConnections(), turnLog) {
+    return new LocalLlmProvider(connections, turnLog);
 }
 class LocalLlmProvider {
     connections;
+    turnLog;
     cache = new Map();
-    constructor(connections) {
+    constructor(connections, turnLog) {
         this.connections = connections;
+        this.turnLog = turnLog;
     }
     invoke(messages, config) {
-        return this.providerFor(config.model).invoke(messages, config);
+        const connection = resolveLocalLlmConnection(this.connections, config.model);
+        const merged = mergeModelCallParams(config, connection.defaults);
+        return this.providerFor(config.model).invoke(messages, { ...config, ...merged });
     }
     stream(messages, config) {
-        return this.providerFor(config.model).stream(messages, config);
+        const connection = resolveLocalLlmConnection(this.connections, config.model);
+        const merged = mergeModelCallParams(config, connection.defaults);
+        return this.providerFor(config.model).stream(messages, { ...config, ...merged });
     }
     providerFor(model) {
         const connection = resolveLocalLlmConnection(this.connections, model);
@@ -98,6 +105,7 @@ class LocalLlmProvider {
             apiKey: connection.apiKey,
             baseUrl: connection.baseUrl,
             defaultModel: model,
+            turnLog: this.turnLog,
         });
         this.cache.set(cacheKey, provider);
         return provider;

package/dist/providers/routing-llm-provider.d.ts

@@ -13,16 +13,20 @@
  */
 import type { GraphMessage } from '../graph/contracts/executable-graph.js';
 import type { ILLMProvider, LLMNodeConfig, LLMResponse, LLMChunk } from '../graph/nodes/llm-node.js';
+import type { ILlmTurnLog } from '../debug/llm-turn-log.js';
 export interface RoutingLLMProviderConfig {
     foundationUrl: string;
     fallbackProvider?: ILLMProvider;
+    turnLog?: ILlmTurnLog;
 }
 export declare class RoutingLLMProvider implements ILLMProvider {
     private readonly foundationUrl;
     private readonly fallback;
+    private readonly turnLog?;
     constructor(config: RoutingLLMProviderConfig);
     invoke(messages: GraphMessage[], config: LLMNodeConfig): Promise<LLMResponse>;
     stream(messages: GraphMessage[], config: LLMNodeConfig): AsyncIterableIterator<LLMChunk>;
+    private withCallDefaults;
     private selectModel;
     private createProviderForModel;
 }

package/dist/providers/routing-llm-provider.js

@@ -11,24 +11,31 @@
  * - 支持任意 OpenAI 兼容 API（OpenAI / DeepSeek / 本地 Ollama 等）
  * - 连接配置由 Foundation 统一管理，Runtime 无感知
  */
+import { mergeModelCallParams } from '@gt-fe/eap-contracts';
 import { EchoLLMProvider } from './echo-llm-provider.js';
 import { HttpLLMProvider } from './http-llm-provider.js';
 export class RoutingLLMProvider {
     foundationUrl;
     fallback;
+    turnLog;
     constructor(config) {
         this.foundationUrl = config.foundationUrl.replace(/\/$/, '');
         this.fallback = config.fallbackProvider ?? new EchoLLMProvider();
+        this.turnLog = config.turnLog;
     }
     async invoke(messages, config) {
         const selected = await this.selectModel(config);
         const provider = this.createProviderForModel(selected);
-        return provider.invoke(messages, { ...config, model: selected.name });
+        return provider.invoke(messages, this.withCallDefaults(config, selected));
     }
     async *stream(messages, config) {
         const selected = await this.selectModel(config);
         const provider = this.createProviderForModel(selected);
-        yield* provider.stream(messages, { ...config, model: selected.name });
+        yield* provider.stream(messages, this.withCallDefaults(config, selected));
+    }
+    withCallDefaults(config, selected) {
+        const merged = mergeModelCallParams(config, selected.defaults);
+        return { ...config, ...merged, model: selected.name };
     }
     async selectModel(config) {
         try {
@@ -47,6 +54,7 @@ export class RoutingLLMProvider {
                         name: body.data.name,
                         provider: body.data.provider,
                         connection: body.data.connection ?? null,
+                        defaults: body.data.defaults ?? null,
                     };
                 }
             }
@@ -64,6 +72,7 @@ export class RoutingLLMProvider {
                 baseUrl: selected.connection.baseUrl,
                 defaultModel: selected.name,
                 timeoutMs: selected.connection.timeoutMs,
+                turnLog: this.turnLog,
             });
         }
         // Fallback: 兼容旧逻辑（直接读 env）—— 开发环境快速启动用
@@ -72,6 +81,7 @@ export class RoutingLLMProvider {
                 apiKey: process.env.OPENAI_API_KEY,
                 baseUrl: process.env.OPENAI_BASE_URL,
                 defaultModel: selected.name,
+                turnLog: this.turnLog,
             });
         }
         return this.fallback;

package/dist/registry/agent-models.d.ts

@@ -1 +1 @@
-export { resolveDeclaredModels, resolveAgentPrimaryModel, resolveAgentModelAllowlist, } from '@gt-fe/eap-contracts';
+export { resolveDeclaredModels, resolveAgentDefaultModel, resolveAgentModelAllowlist, } from '@gt-fe/eap-contracts';

package/dist/registry/agent-models.js

@@ -1 +1 @@
-export { resolveDeclaredModels, resolveAgentPrimaryModel, resolveAgentModelAllowlist, } from '@gt-fe/eap-contracts';
+export { resolveDeclaredModels, resolveAgentDefaultModel, resolveAgentModelAllowlist, } from '@gt-fe/eap-contracts';

package/dist/registry/agent-registry-client.d.ts

@@ -12,8 +12,8 @@ export interface AgentManifest {
     skills: string[];
     prompts: Record<string, string>;
     models?: {
-        primary: string;
-        alternatives?: string[];
+        default: string;
+        allowed?: string[];
     };
     config?: {
         timeout?: number;

package/dist/registry/deployment-snapshot.d.ts

@@ -7,7 +7,7 @@
  *   {root}/agents/<agentCode>/<version>/users/<userId>/skills/<skillCode>/
  *
  * 命名：agentCode / toolsetCode / skillCode / toolName 均为语义化小写标识；
- * Skill 目录无版本层（维护形态为 ZIP 上传整包替换，包内必含 skill.md）。
+ * Skill 目录无版本层：包内必含 SKILL.md（Agent Skills）。
  */
 export interface SnapshotToolRef {
     toolId?: string;
@@ -17,7 +17,7 @@ export interface SnapshotToolRef {
     sha256?: string;
     /**
      * 可选白名单：列出则仅启用所列子工具；省略 = 启用该 toolset 下全部子工具。
-     * @see agent.manifest toolRefs[].enabledTools
+     * @see agent.manifest toolsets[].enabled
      */
     enabledTools?: string[];
     /** 免 HITL 确认的子工具名（覆盖子工具 requireConfirmation） */
@@ -74,12 +74,12 @@ export interface IDeploymentSnapshot {
 /** 规范化摘要：去 sha256: 前缀、空白，转小写 hex */
 export declare function normalizeDigest(value: unknown): string | null;
 /**
- * 装配引用（toolRefs / 简写 tools[]）vs 内联完整 ToolManifest。
+ * 装配引用 vs 内联完整 ToolManifest。
  * 含 type/execution 的视为内联定义；仅 toolset/name/version/enabledTools 等视为引用。
  */
 export declare function isInlineToolDeclaration(item: unknown): boolean;
 /**
- * 将 agent.manifest.toolRefs 上的 enabledTools/autoApprove 叠到 snapshot.tools[]（snapshot 未带时）。
+ * 将 agent.manifest.toolsets 上的 enabled/autoApprove 叠到 snapshot.tools[]（snapshot 未带时）。
  */
 export declare function overlayToolRefPolicies(snapTools: SnapshotToolRef[], manifest?: Record<string, unknown>): SnapshotToolRef[];
 export declare class FileSystemDeploymentSnapshot implements IDeploymentSnapshot {

package/dist/registry/deployment-snapshot.js

@@ -7,12 +7,14 @@
  *   {root}/agents/<agentCode>/<version>/users/<userId>/skills/<skillCode>/
  *
  * 命名：agentCode / toolsetCode / skillCode / toolName 均为语义化小写标识；
- * Skill 目录无版本层（维护形态为 ZIP 上传整包替换，包内必含 skill.md）。
+ * Skill 目录无版本层：包内必含 SKILL.md（Agent Skills）。
  */
 import { readdir, readFile, access } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
 import { constants as fsConstants } from 'node:fs';
+import { parseSkillMd } from '@gt-fe/eap-contracts';
+import { findSkillEntryFile } from './skill-tree.js';
 import { preloadMissing, preloadPackageCorrupt, } from './preload-errors.js';
 import { isRequireChecksum, resolvePreloadBehaviorFlags, } from './preload-flags.js';
 async function pathExists(p) {
@@ -139,7 +141,7 @@ async function pickLatestVersionDir(parent) {
     return path.join(parent, dirs[dirs.length - 1]);
 }
 function skillRefsFromManifest(manifest) {
-    const raw = manifest.skillRefs ?? manifest.skills;
+    const raw = manifest.skills;
     if (!Array.isArray(raw))
         return [];
     const out = [];
@@ -150,7 +152,7 @@ function skillRefsFromManifest(manifest) {
         }
         if (item && typeof item === 'object') {
             const o = item;
-            const skillId = String(o.skill ?? o.skillId ?? o.skillCode ?? o.id ?? '');
+            const skillId = String(o.code ?? '');
             if (!skillId)
                 continue;
             out.push({
@@ -171,7 +173,7 @@ function parseStringList(value) {
     return out.length > 0 ? out : undefined;
 }
 /**
- * 装配引用（toolRefs / 简写 tools[]）vs 内联完整 ToolManifest。
+ * 装配引用 vs 内联完整 ToolManifest。
  * 含 type/execution 的视为内联定义；仅 toolset/name/version/enabledTools 等视为引用。
  */
 export function isInlineToolDeclaration(item) {
@@ -189,7 +191,7 @@ function parseToolAssemblyRef(item) {
     if (isInlineToolDeclaration(item))
         return null;
     const o = item;
-    const name = String(o.toolset ?? o.name ?? o.toolId ?? o.id ?? '');
+    const name = String(o.code ?? o.name ?? '');
     if (!name)
         return null;
     return {
@@ -197,14 +199,13 @@ function parseToolAssemblyRef(item) {
         toolId: o.toolId != null ? String(o.toolId) : undefined,
         version: o.version != null ? String(o.version) : undefined,
         sha256: typeof o.sha256 === 'string' ? o.sha256 : undefined,
-        enabledTools: parseStringList(o.enabledTools),
+        enabledTools: parseStringList(o.enabled),
         autoApprove: parseStringList(o.autoApprove),
     };
 }
 /**
- * 从 agent.manifest 收集工具集装配引用：优先 toolRefs[]，再合并简写 tools[]（非内联项）。
- */
-function toolRefsFromManifest(manifest) {
+/** 从 agent.manifest.toolsets 收集工具集装配引用。 */
+function toolsetsFromManifest(manifest) {
     const out = [];
     const byName = new Map();
     const upsert = (ref) => {
@@ -214,7 +215,6 @@ function toolRefsFromManifest(manifest) {
             out.push(ref);
             return;
         }
-        // 后写补全白名单等字段，不覆盖已有显式值
         if (!prev.enabledTools && ref.enabledTools)
             prev.enabledTools = ref.enabledTools;
         if (!prev.autoApprove && ref.autoApprove)
@@ -226,12 +226,7 @@ function toolRefsFromManifest(manifest) {
         if (!prev.toolId && ref.toolId)
             prev.toolId = ref.toolId;
     };
-    for (const item of Array.isArray(manifest.toolRefs) ? manifest.toolRefs : []) {
-        const ref = parseToolAssemblyRef(item);
-        if (ref)
-            upsert(ref);
-    }
-    for (const item of Array.isArray(manifest.tools) ? manifest.tools : []) {
+    for (const item of Array.isArray(manifest.toolsets) ? manifest.toolsets : []) {
         const ref = parseToolAssemblyRef(item);
         if (ref)
             upsert(ref);
@@ -239,12 +234,12 @@ function toolRefsFromManifest(manifest) {
     return out;
 }
 /**
- * 将 agent.manifest.toolRefs 上的 enabledTools/autoApprove 叠到 snapshot.tools[]（snapshot 未带时）。
+ * 将 agent.manifest.toolsets 上的 enabled/autoApprove 叠到 snapshot.tools[]（snapshot 未带时）。
  */
 export function overlayToolRefPolicies(snapTools, manifest) {
     if (!manifest)
         return snapTools;
-    const fromManifest = toolRefsFromManifest(manifest);
+    const fromManifest = toolsetsFromManifest(manifest);
     if (fromManifest.length === 0)
         return snapTools;
     const byName = new Map(fromManifest.map((r) => [r.name, r]));
@@ -259,6 +254,12 @@ export function overlayToolRefPolicies(snapTools, manifest) {
         };
     });
 }
+function nonemptyRefs(refs) {
+    return refs && refs.length > 0 ? refs : undefined;
+}
+function nonemptySkillRefs(refs) {
+    return refs && refs.length > 0 ? refs : undefined;
+}
 function normalizeSnapshotToolRefs(raw) {
     if (!Array.isArray(raw))
         return undefined;
@@ -281,7 +282,7 @@ function normalizeSnapshotSkillRefs(raw) {
         }
         if (item && typeof item === 'object') {
             const o = item;
-            const skillId = String(o.skill ?? o.skillId ?? o.code ?? o.skillCode ?? o.id ?? '');
+            const skillId = String(o.code ?? o.skillId ?? '');
             if (!skillId)
                 continue;
             out.push({
@@ -417,8 +418,8 @@ export class FileSystemDeploymentSnapshot {
             return {
                 agentCode,
                 version: String(snap.version ?? resolvedVersion),
-                tools: normalizeSnapshotToolRefs(snap.tools) ?? toolRefsFromManifest(manifest ?? {}),
-                skills: normalizeSnapshotSkillRefs(snap.skills) ?? skillRefsFromManifest(manifest ?? {}),
+                tools: nonemptyRefs(normalizeSnapshotToolRefs(snap.tools)) ?? toolsetsFromManifest(manifest ?? {}),
+                skills: nonemptySkillRefs(normalizeSnapshotSkillRefs(snap.skills)) ?? skillRefsFromManifest(manifest ?? {}),
                 graph,
                 agentDir,
                 manifest: manifest ?? undefined,
@@ -428,7 +429,7 @@ export class FileSystemDeploymentSnapshot {
         return {
             agentCode,
             version: resolvedVersion,
-            tools: toolRefsFromManifest(manifest ?? {}),
+            tools: toolsetsFromManifest(manifest ?? {}),
             skills: skillRefsFromManifest(manifest ?? {}),
             graph,
             agentDir,
@@ -497,10 +498,9 @@ export class FileSystemDeploymentSnapshot {
             if (!(await pathExists(bundlePath)))
                 continue;
             await this.assertReadyIfRequired(bundlePath, `skill ${ref.skillId}`);
+            const entryFile = await findSkillEntryFile(bundlePath);
             const manifestPathCandidates = [
                 path.join(bundlePath, 'skill.manifest.json'),
-                path.join(bundlePath, 'skill.definition.json'),
-                path.join(bundlePath, 'manifest.json'),
             ];
             let manifest = null;
             let manifestPath = null;
@@ -512,22 +512,44 @@ export class FileSystemDeploymentSnapshot {
                     break;
                 }
             }
+            if (!manifest && entryFile) {
+                const parsed = parseSkillMd(await readFile(entryFile, 'utf8'));
+                if (!parsed)
+                    continue;
+                manifest = {
+                    code: parsed.frontmatter.name,
+                    name: parsed.frontmatter.name,
+                    description: parsed.frontmatter.description,
+                    ...(parsed.frontmatter.license ? { license: parsed.frontmatter.license } : {}),
+                };
+                manifestPath = entryFile;
+            }
             if (!manifest || !manifestPath)
                 continue;
-            // 用户装配层跳过 sha256 校验（用户覆盖版本与预装快照散列不同是正常行为）
+            if (!manifest.description && entryFile) {
+                const parsed = parseSkillMd(await readFile(entryFile, 'utf8'));
+                if (parsed?.frontmatter.description) {
+                    manifest = { ...manifest, description: parsed.frontmatter.description };
+                    if (!manifest.name)
+                        manifest.name = parsed.frontmatter.name;
+                }
+            }
             const isUserOverridePath = bundlePath.includes('/users/') || bundlePath.includes('\\users\\');
             const isAuthorOverlay = extraRoots.some((root) => root && isPathInside(root, bundlePath));
-            if (ref.sha256 && !isUserOverridePath && !isAuthorOverlay) {
+            if (ref.sha256 && !isUserOverridePath && !isAuthorOverlay && manifestPath.endsWith('.json')) {
                 const actual = await sha256OfFile(manifestPath);
                 await assertDigestMatch(ref.sha256, actual, `skill ${ref.skillId}`, { path: manifestPath });
             }
-            const skillId = String(manifest.code ?? manifest.skillId ?? manifest.skillCode ?? manifest.id ?? ref.skillId);
+            const skillId = String(manifest.code ?? ref.skillId);
             return {
                 skillId,
                 name: String(manifest.name ?? ref.name ?? skillId),
                 version: String(manifest.version ?? ref.version ?? path.basename(bundlePath)),
                 description: manifest.description ?? ref.description,
-                manifest,
+                manifest: {
+                    ...manifest,
+                    ...(entryFile ? { skillEntryFile: entryFile } : {}),
+                },
                 bundlePath,
             };
         }

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

@@ -111,7 +111,7 @@ export declare class GraphLoader {
     loadToolDefinitions(agentCode: string, options?: LoadToolDefinitionsOptions): Promise<LoadedToolDefinition[]>;
     private loadToolDefinitionsFromSource;
     /**
-     * 从预装快照加载已装配 Skill 完整定义（workflow / prompt / toolRefs）
+     * 加载已装配 Skill：SKILL.md 目录（Agent Skills）或可选 skill.manifest.json。
      * @param options.userId 用于解析 users/<userId>/skills（优先于 preinstall/skills）
      * @param options.allowMissingSkills 缺失时跳过而非抛错（warm 预热用）
      */