@gt-fe/eap-runtime 0.0.10 → 0.0.12

package/README.md

@@ -28,6 +28,7 @@ Enterprise Agent Platform **执行引擎**（LangGraph.js）：Agent Graph 编
 | 环境变量总表 | [`docs/governance/governance-env-config.md`](../docs/governance/governance-env-config.md) |
 | 预装联调契约 | [`docs/contracts/preload-hosting-runtime-contract.md`](../docs/contracts/preload-hosting-runtime-contract.md) |
 | 预装加载与请求流转 | [`docs/contracts/runtime-preinstall-load-flow.md`](../docs/contracts/runtime-preinstall-load-flow.md) |
+| 技能 FS 待办 | [`docs/TODO-skill-fs.md`](./docs/TODO-skill-fs.md) |
 | 本地 Agent 闭环 | [`docs/workflows/local-agent-dev-loop.md`](../docs/workflows/local-agent-dev-loop.md) |
 
 ---
@@ -197,8 +198,7 @@ node ../fixtures/eap-preinstall-sample/scripts/seal-snapshot.mjs
 
 | 模式 | 何时 | 说明 |
 |------|------|------|
-| `mock` | 本地默认 | 不调真实 Tool |
-| `mcp` / DevMcp | `eap chat --tool-mode mcp` | 本机直连 MCP（`EAP_TOOL_EXECUTION_MODE`，仅 createDevRuntime） |
+| `mcp` / DevToolExecutor | 本地默认（`dev` + `mcp`） | 按清单直连 MCP / HTTP / 本机 code |
 | Gateway | 生产 / Hosting | `EAP_TOOL_GATEWAY_TRANSPORT=mcp`（生产）；`http` 仅调试 |
 
 - 编排：`ToolOrchestrator` + `ToolExecutionRouter`（`deploymentContext`: `server` \| `desktop` \| `dev`）
@@ -254,7 +254,7 @@ FOUNDATION_SERVICE_URL=...
 EAP_DEPLOYMENT_CONTEXT=dev
 EAP_PREINSTALL_ROOT=/abs/path/to/preinstall   # 或 Agent 工程内预装树
 EAP_RUNTIME_STORAGE_PROFILE=dev
-EAP_TOOL_EXECUTION_MODE=mock                 # 或 mcp
+EAP_TOOL_EXECUTION_MODE=mcp                  # 本地默认；http-debug 走 Gateway 调试口
 # OPENAI_BASE_URL / OPENAI_API_KEY / EAP_DEFAULT_MODEL
 ```
 

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

@@ -178,6 +178,9 @@ export class InvokeOrchestrator {
             const promptRoots = this.graphLoader
                 ? await this.graphLoader.resolvePromptRoots(agentCode, req.agentVersion)
                 : [];
+            const agentDir = this.graphLoader
+                ? (await this.graphLoader.resolveAgentDir(agentCode, req.agentVersion)) ?? undefined
+                : undefined;
             // 组装 GraphState：有 Checkpoint 历史则只追加本轮 user，避免双重 append
             const history = messageRecordsToGraphMessages(sessionContext.messages);
             const messages = await buildTurnGraphMessages({
@@ -204,6 +207,7 @@ export class InvokeOrchestrator {
                 skillDefinitions,
                 skillInput,
                 promptRoots,
+                agentDir,
                 traceId: resolveTraceId(req),
                 traceCollector: this.traceCollector,
             });

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

@@ -200,6 +200,9 @@ export class StreamOrchestrator {
         const promptRoots = this.graphLoader
             ? await this.graphLoader.resolvePromptRoots(agentCode, req.agentVersion)
             : [];
+        const agentDir = this.graphLoader
+            ? (await this.graphLoader.resolveAgentDir(agentCode, req.agentVersion)) ?? undefined
+            : undefined;
         // 组装 GraphState：有 Checkpoint 历史则只追加本轮 user，避免双重 append
         const history = messageRecordsToGraphMessages(sessionContext.messages);
         const messages = await buildTurnGraphMessages({
@@ -232,6 +235,7 @@ export class StreamOrchestrator {
                 skillDefinitions,
                 skillInput,
                 promptRoots,
+                agentDir,
                 traceId: resolveTraceId(req),
                 traceCollector: this.traceCollector,
             });

package/dist/contracts/trace-collector.d.ts

@@ -84,7 +84,7 @@ export interface ExecutionNodeEvent {
     /** 节点类型 */
     type: 'start' | 'llm' | 'tool' | 'skill' | 'condition' | 'hitl' | 'end';
     /** 工具运行环境（type=tool） */
-    toolRuntime?: 'local' | 'server' | 'both' | 'mock';
+    toolRuntime?: 'local' | 'server' | 'both';
     /** Agent 对外主键 */
     agentCode?: string;
     /** 输入数据 */

package/dist/governance/governance-client.js

@@ -40,25 +40,29 @@ export class HttpGovernanceClient {
             if (response.status === 503 || response.status >= 500) {
                 return { allowed: false, reason: 'GOVERNANCE_UNAVAILABLE' };
             }
+            if (response.status === 403) {
+                return { allowed: false, reason: await readDenyReason(response, 'NO_PERMISSION') };
+            }
             if (!response.ok) {
-                if (response.status === 403) {
-                    try {
-                        const errBody = (await response.json());
-                        const errData = errBody.data ?? errBody;
-                        return { allowed: false, reason: errData.reason ?? 'NO_PERMISSION' };
-                    }
-                    catch {
-                        return { allowed: false, reason: 'NO_PERMISSION' };
-                    }
-                }
-                return { allowed: false, reason: 'NO_PERMISSION' };
+                // 401/404/400 等是 Runtime→Foundation hop 失败，不是 C2「没工具权」
+                return { allowed: false, reason: 'GOVERNANCE_UNAVAILABLE' };
+            }
+            let body;
+            try {
+                body = (await response.json());
+            }
+            catch {
+                return { allowed: false, reason: 'GOVERNANCE_UNAVAILABLE' };
             }
-            const body = (await response.json());
             const data = body.data ?? body;
-            return {
-                allowed: data.allowed === true,
-                reason: data.allowed ? undefined : (data.reason ?? 'NO_PERMISSION'),
-            };
+            if (data.allowed === true) {
+                return { allowed: true };
+            }
+            const reason = asDenyReason(data.reason);
+            if (data.allowed === false && reason && reason !== 'GOVERNANCE_UNAVAILABLE') {
+                return { allowed: false, reason };
+            }
+            return { allowed: false, reason: 'GOVERNANCE_UNAVAILABLE' };
         }
         catch {
             clearTimeout(timeoutId);
@@ -66,6 +70,26 @@ export class HttpGovernanceClient {
         }
     }
 }
+const DENY_REASONS = new Set([
+    'NO_PERMISSION',
+    'DATA_SCOPE_DENIED',
+    'GOVERNANCE_UNAVAILABLE',
+]);
+function asDenyReason(value) {
+    return typeof value === 'string' && DENY_REASONS.has(value)
+        ? value
+        : undefined;
+}
+async function readDenyReason(response, fallback) {
+    try {
+        const errBody = (await response.json());
+        const errData = errBody.data ?? errBody;
+        return asDenyReason(errData.reason) ?? fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
 /** 本地/测试：跳过远程校验 */
 export class AllowAllGovernanceClient {
     async checkPermission(_ctx, _params) {

package/dist/governance/index.d.ts

@@ -4,4 +4,4 @@
 export type { CallerType, ExecutionContext, GovernancePermissionCheckParams, GovernancePermissionCheckResult, PermissionAction, PermissionDenyReason, PermissionResourceType, } from '@gt-fe/eap-contracts';
 export type { IGovernanceClient } from './governance-client.js';
 export { HttpGovernanceClient, AllowAllGovernanceClient, resolveExecutionContext, } from './governance-client.js';
-export { assertToolPermission, assertSkillPermission, PermissionDeniedError, GovernanceUnavailableError, } from './permission-guard.js';
+export { assertToolPermission, assertSkillPermission, permissionMessage, PermissionDeniedError, GovernanceUnavailableError, } from './permission-guard.js';

package/dist/governance/index.js

@@ -2,4 +2,4 @@
  * 权限校验 — 对齐 06-governance R16.8
  */
 export { HttpGovernanceClient, AllowAllGovernanceClient, resolveExecutionContext, } from './governance-client.js';
-export { assertToolPermission, assertSkillPermission, PermissionDeniedError, GovernanceUnavailableError, } from './permission-guard.js';
+export { assertToolPermission, assertSkillPermission, permissionMessage, PermissionDeniedError, GovernanceUnavailableError, } from './permission-guard.js';

package/dist/governance/permission-guard.d.ts

@@ -11,6 +11,7 @@ export declare class PermissionDeniedError extends Error {
     readonly reason: PermissionDenyReason;
     constructor(reason?: PermissionDenyReason, message?: string);
 }
+export declare function permissionMessage(kind: 'tool' | 'skill', reason: PermissionDenyReason): string;
 export declare function assertToolPermission(client: IGovernanceClient | undefined, ctx: ExecutionContext, toolId: string, options?: {
     dataScope?: 'user-bound' | 'department-bound' | 'global';
     resourceOwnerId?: string;

package/dist/governance/permission-guard.js

@@ -3,7 +3,7 @@
  */
 export class GovernanceUnavailableError extends Error {
     reason = 'GOVERNANCE_UNAVAILABLE';
-    constructor(message = 'Governance service unavailable') {
+    constructor(message = '治理服务不可用') {
         super(message);
         this.name = 'GovernanceUnavailableError';
     }
@@ -11,11 +11,18 @@ export class GovernanceUnavailableError extends Error {
 export class PermissionDeniedError extends Error {
     reason;
     constructor(reason = 'NO_PERMISSION', message) {
-        super(message ?? reason);
+        super(message ?? permissionMessage('tool', reason));
         this.name = 'PermissionDeniedError';
         this.reason = reason;
     }
 }
+export function permissionMessage(kind, reason) {
+    if (reason === 'DATA_SCOPE_DENIED')
+        return '数据范围不足';
+    if (reason === 'GOVERNANCE_UNAVAILABLE')
+        return '治理服务不可用';
+    return kind === 'skill' ? '用户无该 Skill 使用权限' : '用户无该 Tool 执行权限';
+}
 export async function assertToolPermission(client, ctx, toolId, options) {
     if (!client) {
         return;
@@ -34,7 +41,8 @@ export async function assertToolPermission(client, ctx, toolId, options) {
         throw new GovernanceUnavailableError();
     }
     if (!result.allowed) {
-        throw new PermissionDeniedError(result.reason ?? 'NO_PERMISSION');
+        const reason = result.reason ?? 'NO_PERMISSION';
+        throw new PermissionDeniedError(reason, permissionMessage('tool', reason));
     }
 }
 /** Skill 激活守卫（04 R15.3） */
@@ -54,6 +62,7 @@ export async function assertSkillPermission(client, ctx, skillId) {
         throw new GovernanceUnavailableError();
     }
     if (!result.allowed) {
-        throw new PermissionDeniedError(result.reason ?? 'NO_PERMISSION');
+        const reason = result.reason ?? 'NO_PERMISSION';
+        throw new PermissionDeniedError(reason, permissionMessage('skill', reason));
     }
 }

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

@@ -19,7 +19,7 @@ import { fileArtifactFromToolOutput } from '../../tool/file-artifact.js';
 import { EchoLLMProvider } from '../../providers/echo-llm-provider.js';
 import { ConditionEvaluator } from '../condition-evaluator.js';
 import { SystemPromptBuilder, buildToolCatalog, loadedToolsToApiTools } from '../../tool/system-prompt-builder.js';
-import { resolveJailRoots } from '../../tool/harness-primitives.js';
+import { resolveJailFromState, resolveJailRoots } from '../../tool/harness-primitives.js';
 import os from 'node:os';
 import { bindSelectedSkill } from '../nodes/skill-bind-node.js';
 import { resolveGraphPrompt } from '../resolve-graph-prompt.js';
@@ -305,6 +305,7 @@ export class LangGraphAdapter {
                 skillRoute: ephemeral(undefined),
                 silentOutput: ephemeral(undefined),
                 promptRoots: ephemeral(undefined),
+                agentDir: ephemeral(undefined),
                 executionContext: ephemeral(undefined),
                 forceToolServer: ephemeral(undefined),
                 traceCollector: ephemeral(undefined),
@@ -799,7 +800,15 @@ export class LangGraphAdapter {
                 const toolCatalog = disableTools ? undefined : buildToolCatalog(loadedTools);
                 const execCtx = state['executionContext'];
                 const userId = (typeof execCtx?.userId === 'string' && execCtx.userId) || state['userId'];
-                const workingDirectory = typeof process.cwd === 'function' ? process.cwd() : undefined;
+                const jail = resolveJailFromState({
+                    agentDir: state['agentDir'],
+                    userId,
+                    executionContext: execCtx,
+                    loadedTools,
+                    skillDefinitions: skillDefs,
+                });
+                const workingDirectory = jail.workdir;
+                const jailRoots = resolveJailRoots(jail);
                 const skillDirs = Object.values(skillDefs ?? {})
                     .filter((skill) => Boolean(skill.bundlePath))
                     .map((skill) => ({
@@ -807,10 +816,6 @@ export class LangGraphAdapter {
                     bundlePath: skill.bundlePath,
                     entryFile: skill.entryFile,
                 }));
-                const jailRoots = resolveJailRoots({
-                    workdir: workingDirectory,
-                    extraRoots: skillDirs.map((s) => s.bundlePath),
-                });
                 const assembled = this.systemPromptBuilder.build({
                     developerPrompt: resolvedPrompt || undefined,
                     skillCatalog: catalog,

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

@@ -195,6 +195,8 @@ export interface GraphState {
     silentOutput?: string;
     /** 解析 graph 内 ./prompts/*.md 的根目录（agentDir + 工程根） */
     promptRoots?: string[];
+    /** 预装 Agent 包目录：`{EAP_PREINSTALL_ROOT}/agents/<code>/<ver>` */
+    agentDir?: string;
     activatedSkill?: string | null;
     skillRoute?: string;
     /** bind / invoke 解析出的 Skill 入参；子图 IO 校验读取 */

package/dist/graph/hitl/hitl-handler.d.ts

@@ -16,6 +16,9 @@ import type { ISSEEmitter } from '../../sse/contracts/sse-emitter.contract.js';
 import type { GraphState } from '../contracts/executable-graph.js';
 /** HITL 默认等待时长（毫秒）= 300 秒。SSE `hitl.waited.timeout` 对外用秒。 */
 export declare const DEFAULT_HITL_TIMEOUT_MS = 300000;
+/** 超时收口对外文案（Task / Trace / AppError）；枚举走 `hitl_timeout`。 */
+export declare const HITL_TIMEOUT_MESSAGE = "HITL \u786E\u8BA4\u8D85\u65F6";
+export declare const HITL_TIMEOUT_ERROR_CODE = "hitl_timeout";
 /** HITL 超时行为 */
 export type HitlTimeoutBehavior = 'error' | 'cancel' | 'auto-confirm';
 /** HITL 中断配置 */

package/dist/graph/hitl/hitl-handler.js

@@ -17,6 +17,9 @@ import { startGraphSpan, completeGraphSpan } from '../trace-span.js';
 // ─────────────────────────────────────────────
 /** HITL 默认等待时长（毫秒）= 300 秒。SSE `hitl.waited.timeout` 对外用秒。 */
 export const DEFAULT_HITL_TIMEOUT_MS = 300_000;
+/** 超时收口对外文案（Task / Trace / AppError）；枚举走 `hitl_timeout`。 */
+export const HITL_TIMEOUT_MESSAGE = 'HITL 确认超时';
+export const HITL_TIMEOUT_ERROR_CODE = 'hitl_timeout';
 /** HITL 超时错误（保留类型；timer 不再 throw，resume 逾期改走 AppError） */
 export class HitlTimeoutError extends Error {
     taskId;
@@ -444,7 +447,7 @@ export class HitlHandler {
                     const hitlSpanId = waiting.hitlSpanId ?? persisted.hitlSpanId;
                     await completeGraphSpan(checkpoint.state, hitlSpanId, {
                         status: 'failed',
-                        error: 'hitl_timeout',
+                        error: HITL_TIMEOUT_MESSAGE,
                     }, liveCollector);
                 }
                 return timeoutEvent;

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

@@ -9,6 +9,7 @@
  * @see design.md §1.4 ToolNode: LangGraph的ToolNode封装
  * @see requirements.md Requirement 8 AC1, AC3, AC5
  */
+import { resolveJailFromState } from '../../tool/harness-primitives.js';
 import { isHitlDecision, unwrapHitlPaused } from '../hitl/hitl-handler.js';
 import { ToolConfirmationInterceptor } from '../../tool/tool-confirmation.js';
 import { resolveCheckpointThreadId } from '../../session/persist-turn-messages.js';
@@ -19,6 +20,19 @@ function skillDirsFromState(state) {
         .filter((skill) => Boolean(skill.bundlePath))
         .map((skill) => ({ skillId: skill.skillId, bundlePath: skill.bundlePath }));
 }
+function resolveActiveSkillDir(state) {
+    const defs = state['skillDefinitions'];
+    if (!defs)
+        return undefined;
+    const activated = state['activatedSkill'];
+    if (typeof activated === 'string' && defs[activated]?.bundlePath) {
+        return defs[activated].bundlePath;
+    }
+    const paths = Object.values(defs)
+        .map((skill) => skill.bundlePath)
+        .filter((p) => Boolean(p));
+    return paths.length === 1 ? paths[0] : undefined;
+}
 export class ToolNode {
     orchestrator;
     injector;
@@ -53,7 +67,15 @@ export class ToolNode {
         }
         const loadedTools = state['loadedTools'];
         const skillDirs = skillDirsFromState(state);
-        const jailExtraRoots = skillDirs.map((dir) => dir.bundlePath);
+        const jail = resolveJailFromState({
+            agentDir: state['agentDir'],
+            userId: state['userId'],
+            executionContext: state['executionContext'],
+            loadedTools,
+            skillDefinitions: state['skillDefinitions'],
+        });
+        const jailExtraRoots = jail.extraRoots ?? [];
+        const skillDir = resolveActiveSkillDir(state);
         // 4. 转换为 ToolCallRequest[]（附带 manifest 路由字段）
         const requests = lastAssistantMessage.toolCalls.map((tc) => {
             const loaded = loadedTools?.[tc.name];
@@ -73,7 +95,9 @@ export class ToolNode {
                 ...(loaded?.manifest.version ? { toolVersion: loaded.manifest.version } : {}),
                 correlationId,
                 taskId,
+                ...(jail.workdir ? { jailWorkdir: jail.workdir } : {}),
                 ...(jailExtraRoots.length > 0 ? { jailExtraRoots } : {}),
+                ...(skillDir ? { skillDir } : {}),
             };
         });
         const executionContext = state['executionContext'];
@@ -161,7 +185,8 @@ export class ToolNode {
                                 toolName: req.toolName,
                                 content: `用户拒绝执行工具 ${req.toolName}`,
                                 success: false,
-                                error: 'hitl_rejected',
+                                error: `用户拒绝执行工具 ${req.toolName}`,
+                                errorCode: 'hitl_rejected',
                             };
                 }
                 else {

package/dist/index.d.ts

@@ -17,7 +17,7 @@ export * from './registry/index.js';
 export * from './providers/index.js';
 export type { ITraceCollector, TraceEvent, TraceSession, ExecutionFlowEvent, ExecutionNodeEvent, TraceLinkEvent, TraceLinkNodeEvent, } from './contracts/trace-collector.js';
 export type { ExecutionContext, CallerType, GovernancePermissionCheckParams, GovernancePermissionCheckResult, PermissionDenyReason, } from '@gt-fe/eap-contracts';
-export { HttpGovernanceClient, AllowAllGovernanceClient, resolveExecutionContext, assertToolPermission, assertSkillPermission, PermissionDeniedError, GovernanceUnavailableError, } from './governance/index.js';
+export { HttpGovernanceClient, AllowAllGovernanceClient, resolveExecutionContext, assertToolPermission, assertSkillPermission, permissionMessage, PermissionDeniedError, GovernanceUnavailableError, } from './governance/index.js';
 export type { IGovernanceClient } from './governance/index.js';
 export { FileLlmTurnLog, InMemoryLlmTurnLog, createFileLlmTurnLogFromEnv, maskApiKey, resolveLlmTurnDir, } from './debug/llm-turn-log.js';
 export { PostgresLlmTurnLog } from './debug/pg-llm-turn-log.js';

package/dist/index.js

@@ -29,6 +29,6 @@ export * from './common/index.js';
 export * from './registry/index.js';
 // LLM Providers
 export * from './providers/index.js';
-export { HttpGovernanceClient, AllowAllGovernanceClient, resolveExecutionContext, assertToolPermission, assertSkillPermission, PermissionDeniedError, GovernanceUnavailableError, } from './governance/index.js';
+export { HttpGovernanceClient, AllowAllGovernanceClient, resolveExecutionContext, assertToolPermission, assertSkillPermission, permissionMessage, PermissionDeniedError, GovernanceUnavailableError, } from './governance/index.js';
 export { FileLlmTurnLog, InMemoryLlmTurnLog, createFileLlmTurnLogFromEnv, maskApiKey, resolveLlmTurnDir, } from './debug/llm-turn-log.js';
 export { PostgresLlmTurnLog } from './debug/pg-llm-turn-log.js';

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

@@ -7,8 +7,8 @@
  * - `call:echo-tool {"text":"hi"}` → arguments 使用解析后的 JSON
  * - `call:echo-tool hi` → arguments 兜底为 `{ text: 'hi' }`
  *
- * 仅用于本地闭环 (`EAP_TOOL_EXECUTION_MODE=mock`) 下驱动 ToolNode，
- * 让开发者无需接入真实 LLM 即可完成 tool 调用链路验证。
+ * 仅用于本地闭环（无真实 LLM）下驱动 ToolNode，
+ * 让开发者无需接入模型即可完成 tool 调用链路验证。
  */
 function parseSyntheticToolCall(content) {
     if (!content)

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

@@ -73,13 +73,25 @@ export interface IDeploymentSnapshot {
 }
 /** 规范化摘要：去 sha256: 前缀、空白，转小写 hex */
 export declare function normalizeDigest(value: unknown): string | null;
+/**
+ * Agent 清单装配读取：现行 `skills`，兼容 CLI `skillRefs`。
+ * 项身份：`code` / `skill` / `skillId`。两边都有时现行字段先写入；同名只补 version/name 等空位。
+ */
+export declare function skillRefsFromManifest(manifest: Record<string, unknown>): SnapshotSkillRef[];
 /**
  * 装配引用 vs 内联完整 ToolManifest。
- * 含 type/execution 的视为内联定义；仅 toolset/name/version/enabledTools 等视为引用。
+ * 含 type/execution 的视为内联定义；仅 code/toolset/version/enabled 等视为引用。
  */
 export declare function isInlineToolDeclaration(item: unknown): boolean;
 /**
- * 将 agent.manifest.toolsets 上的 enabled/autoApprove 叠到 snapshot.tools[]（snapshot 未带时）。
+ * 从 Agent 清单收集工具集装配引用。
+ * 现行 `toolsets`；兼容 CLI `toolRefs` 与更旧的 `tools`（内联完整 manifest 会跳过）。
+ * 项身份：`code` / `toolset`（字符串项即 code）。不用展示名 `name`。白名单：`enabled` / `enabledTools`。
+ * 两边都有时现行字段先写入；同名条目的 enabled/autoApprove 以先写入为准。
+ */
+export declare function toolsetsFromManifest(manifest: Record<string, unknown>): SnapshotToolRef[];
+/**
+ * 将 agent.manifest 装配项上的 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

@@ -140,29 +140,51 @@ async function pickLatestVersionDir(parent) {
     dirs.sort();
     return path.join(parent, dirs[dirs.length - 1]);
 }
-function skillRefsFromManifest(manifest) {
-    const raw = manifest.skills;
-    if (!Array.isArray(raw))
-        return [];
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+/**
+ * Agent 清单装配读取：现行 `skills`，兼容 CLI `skillRefs`。
+ * 项身份：`code` / `skill` / `skillId`。两边都有时现行字段先写入；同名只补 version/name 等空位。
+ */
+export function skillRefsFromManifest(manifest) {
     const out = [];
-    for (const item of raw) {
+    const byId = new Map();
+    const upsert = (ref) => {
+        const prev = byId.get(ref.skillId);
+        if (!prev) {
+            byId.set(ref.skillId, ref);
+            out.push(ref);
+            return;
+        }
+        if (!prev.version && ref.version)
+            prev.version = ref.version;
+        if (!prev.name && ref.name)
+            prev.name = ref.name;
+        if (!prev.description && ref.description)
+            prev.description = ref.description;
+        if (!prev.sha256 && ref.sha256)
+            prev.sha256 = ref.sha256;
+    };
+    for (const item of [...asArray(manifest.skills), ...asArray(manifest.skillRefs)]) {
         if (typeof item === 'string') {
-            out.push({ skillId: item });
+            if (item)
+                upsert({ skillId: item });
             continue;
         }
-        if (item && typeof item === 'object') {
-            const o = item;
-            const skillId = String(o.code ?? '');
-            if (!skillId)
-                continue;
-            out.push({
-                skillId,
-                name: o.name != null ? String(o.name) : undefined,
-                version: o.version != null ? String(o.version) : undefined,
-                description: o.description != null ? String(o.description) : undefined,
-                sha256: typeof o.sha256 === 'string' ? o.sha256 : undefined,
-            });
-        }
+        if (!item || typeof item !== 'object')
+            continue;
+        const o = item;
+        const skillId = String(o.code ?? o.skill ?? o.skillId ?? '');
+        if (!skillId)
+            continue;
+        upsert({
+            skillId,
+            name: o.name != null ? String(o.name) : undefined,
+            version: o.version != null ? String(o.version) : undefined,
+            description: o.description != null ? String(o.description) : undefined,
+            sha256: typeof o.sha256 === 'string' ? o.sha256 : undefined,
+        });
     }
     return out;
 }
@@ -174,7 +196,7 @@ function parseStringList(value) {
 }
 /**
  * 装配引用 vs 内联完整 ToolManifest。
- * 含 type/execution 的视为内联定义；仅 toolset/name/version/enabledTools 等视为引用。
+ * 含 type/execution 的视为内联定义；仅 code/toolset/version/enabled 等视为引用。
  */
 export function isInlineToolDeclaration(item) {
     if (!item || typeof item !== 'object' || Array.isArray(item))
@@ -191,7 +213,7 @@ function parseToolAssemblyRef(item) {
     if (isInlineToolDeclaration(item))
         return null;
     const o = item;
-    const name = String(o.code ?? o.name ?? '');
+    const name = String(o.code ?? o.toolset ?? '');
     if (!name)
         return null;
     return {
@@ -199,13 +221,17 @@ 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.enabled),
+        enabledTools: parseStringList(o.enabled) ?? parseStringList(o.enabledTools),
         autoApprove: parseStringList(o.autoApprove),
     };
 }
 /**
-/** 从 agent.manifest.toolsets 收集工具集装配引用。 */
-function toolsetsFromManifest(manifest) {
+ * 从 Agent 清单收集工具集装配引用。
+ * 现行 `toolsets`；兼容 CLI `toolRefs` 与更旧的 `tools`（内联完整 manifest 会跳过）。
+ * 项身份：`code` / `toolset`（字符串项即 code）。不用展示名 `name`。白名单：`enabled` / `enabledTools`。
+ * 两边都有时现行字段先写入；同名条目的 enabled/autoApprove 以先写入为准。
+ */
+export function toolsetsFromManifest(manifest) {
     const out = [];
     const byName = new Map();
     const upsert = (ref) => {
@@ -215,10 +241,6 @@ function toolsetsFromManifest(manifest) {
             out.push(ref);
             return;
         }
-        if (!prev.enabledTools && ref.enabledTools)
-            prev.enabledTools = ref.enabledTools;
-        if (!prev.autoApprove && ref.autoApprove)
-            prev.autoApprove = ref.autoApprove;
         if (!prev.version && ref.version)
             prev.version = ref.version;
         if (!prev.sha256 && ref.sha256)
@@ -226,7 +248,11 @@ function toolsetsFromManifest(manifest) {
         if (!prev.toolId && ref.toolId)
             prev.toolId = ref.toolId;
     };
-    for (const item of Array.isArray(manifest.toolsets) ? manifest.toolsets : []) {
+    for (const item of [
+        ...asArray(manifest.toolsets),
+        ...asArray(manifest.toolRefs),
+        ...asArray(manifest.tools),
+    ]) {
         const ref = parseToolAssemblyRef(item);
         if (ref)
             upsert(ref);
@@ -234,7 +260,7 @@ function toolsetsFromManifest(manifest) {
     return out;
 }
 /**
- * 将 agent.manifest.toolsets 上的 enabled/autoApprove 叠到 snapshot.tools[]（snapshot 未带时）。
+ * 将 agent.manifest 装配项上的 enabled/autoApprove 叠到 snapshot.tools[]（snapshot 未带时）。
  */
 export function overlayToolRefPolicies(snapTools, manifest) {
     if (!manifest)

package/dist/registry/graph-loader.js

@@ -7,6 +7,7 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { resolveAgentModelAllowlist, resolveAgentDefaultModel } from './agent-models.js';
+import { DEFAULT_HTTP_TOOL_TIMEOUT_SEC, DEFAULT_TOOL_TIMEOUT_SEC } from '../tool/timeout.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';
@@ -300,7 +301,7 @@ function expandPreinstallToolset(pre, options) {
                 baseUrl: st.baseUrl ?? gateway.baseUrl,
                 pathTemplate: st.pathTemplate,
                 allowedHosts: gateway.allowedHosts,
-                timeout: st.timeout ?? gateway.timeout ?? 10000,
+                timeout: st.timeout ?? gateway.timeout ?? DEFAULT_HTTP_TOOL_TIMEOUT_SEC,
             };
         }
         else if (setType === 'mcp') {
@@ -310,7 +311,7 @@ function expandPreinstallToolset(pre, options) {
                 transport: server?.transport ?? (server?.url ? 'streamable_http' : 'stdio'),
                 server,
                 toolName: name,
-                timeout: st.timeout ?? server?.timeout ?? 30000,
+                timeout: st.timeout ?? server?.timeout ?? DEFAULT_TOOL_TIMEOUT_SEC,
             };
         }
         else {
@@ -319,7 +320,7 @@ function expandPreinstallToolset(pre, options) {
                 runtime: st.runtime ?? 'node',
                 handler: st.handler,
                 args: st.args,
-                timeout: st.timeout ?? 30000,
+                timeout: st.timeout ?? DEFAULT_TOOL_TIMEOUT_SEC,
                 sandbox: st.sandbox ?? pkg?.sandbox ?? false,
                 bundlePath: pre.bundlePath,
             };
@@ -839,7 +840,6 @@ export class GraphLoader {
                 const workflow = asGraphDsl(pre.manifest.workflow) ??
                     asGraphDsl(pre.manifest.graph) ??
                     asGraphDsl(pre.manifest.definitionSnapshot);
-                // 解析 prompt：支持文件路径引用（./ 开头）
                 const prompt = await resolveSkillPrompt(pre.manifest, pre.bundlePath);
                 const entryFile = typeof pre.manifest.skillEntryFile === 'string' ? pre.manifest.skillEntryFile : undefined;
                 skills.push({

package/dist/registry/index.d.ts

@@ -3,7 +3,7 @@ export { createAgentRegistryClient, type AgentRegistryClient, type AgentRegistry
 export { GraphLoader, type GraphLoaderConfig, type LoadToolDefinitionsOptions, type LoadAgentOptions } from './graph-loader.js';
 export { PreinstallDefinitionCache, resolveDefinitionCacheEnabled, type CachedAgentDefinitions, } from './definition-cache.js';
 export { inspectAgentSkillTree, readSkillAssembly, resolveSkillHotReload, skillAssemblyStamp, watchAgentSkillDirs, watchPreinstallSkillRoot, watchSkillRoots, } from './skill-tree.js';
-export { FileSystemDeploymentSnapshot, createDeploymentSnapshotFromEnv, normalizeDigest, isInlineToolDeclaration, overlayToolRefPolicies, type IDeploymentSnapshot, type AgentSnapshotMeta, type SnapshotToolRef, type SnapshotSkillRef, type PreinstallToolManifest, type PreinstallSkillManifest, type DeploymentSnapshotOptions, } from './deployment-snapshot.js';
+export { FileSystemDeploymentSnapshot, createDeploymentSnapshotFromEnv, normalizeDigest, isInlineToolDeclaration, overlayToolRefPolicies, toolsetsFromManifest, skillRefsFromManifest, type IDeploymentSnapshot, type AgentSnapshotMeta, type SnapshotToolRef, type SnapshotSkillRef, type PreinstallToolManifest, type PreinstallSkillManifest, type DeploymentSnapshotOptions, } from './deployment-snapshot.js';
 export { preloadError, preloadMissing, preloadManifestNotFound, preloadGraphNotFound, preloadToolNotFound, preloadSkillNotFound, preloadPackageCorrupt, isRequireReady, } from './preload-errors.js';
 export { resolvePreloadBehaviorFlags, isValidateSkillIo, isRequireChecksum, type PreloadBehaviorFlags, } from './preload-flags.js';
 export { assertSkillIoIfEnabled, coerceSkillInputFromMessages, resolveSkillInputFromInvokeInput, } from './skill-io-guard.js';

package/dist/registry/index.js

@@ -3,7 +3,7 @@ export { createAgentRegistryClient } from './agent-registry-client.js';
 export { GraphLoader } from './graph-loader.js';
 export { PreinstallDefinitionCache, resolveDefinitionCacheEnabled, } from './definition-cache.js';
 export { inspectAgentSkillTree, readSkillAssembly, resolveSkillHotReload, skillAssemblyStamp, watchAgentSkillDirs, watchPreinstallSkillRoot, watchSkillRoots, } from './skill-tree.js';
-export { FileSystemDeploymentSnapshot, createDeploymentSnapshotFromEnv, normalizeDigest, isInlineToolDeclaration, overlayToolRefPolicies, } from './deployment-snapshot.js';
+export { FileSystemDeploymentSnapshot, createDeploymentSnapshotFromEnv, normalizeDigest, isInlineToolDeclaration, overlayToolRefPolicies, toolsetsFromManifest, skillRefsFromManifest, } from './deployment-snapshot.js';
 export { preloadError, preloadMissing, preloadManifestNotFound, preloadGraphNotFound, preloadToolNotFound, preloadSkillNotFound, preloadPackageCorrupt, isRequireReady, } from './preload-errors.js';
 export { resolvePreloadBehaviorFlags, isValidateSkillIo, isRequireChecksum, } from './preload-flags.js';
 export { assertSkillIoIfEnabled, coerceSkillInputFromMessages, resolveSkillInputFromInvokeInput, } from './skill-io-guard.js';