@gt-fe/eap-runtime 0.0.29 → 0.0.31

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

@@ -19,9 +19,17 @@ import { resolveCheckpointThreadId } from '../../session/persist-turn-messages.j
 import { mcpToolsetCode, toolTraceIdentity } from '../../tool/mcp-list.js';
 import { resolveExecutionTrace, warnTraceSpanFailure, } from '../execution-trace-context.js';
 import { emitRuntimeLog } from '../../common/logger.js';
+import { toolResultHasArtifacts } from '../../tool/inject-public-artifact-links.js';
 import { decideBeforeTool, } from '../../execution/interceptors.js';
 import { isRetryableToolFailure, resolveToolRetryConfig, sleepToolRetry, toolRetryDelayMs, } from '../../tool/tool-retry.js';
 import { isIsolatedSkillState } from '../adapters/skill-isolate.js';
+function toolArtifactFields(result) {
+    return {
+        ...(result.content ? { content: result.content } : {}),
+        ...(result.file ? { file: result.file } : {}),
+        ...(result.files?.length ? { files: result.files } : {}),
+    };
+}
 function skillDirsFromState(state) {
     const defs = state['skillDefinitions'];
     return Object.values(defs ?? {})
@@ -302,6 +310,7 @@ export class ToolNode {
                         status: 'completed',
                         arguments: req.arguments,
                         content: result.content,
+                        ...toolArtifactFields(result),
                         executionTime,
                         ...(skillIdentity?.skillSpace ? { skillSpace: skillIdentity.skillSpace } : {}),
                         ...(skillIdentity?.skillVersion ? { skillVersion: skillIdentity.skillVersion } : {}),
@@ -317,6 +326,7 @@ export class ToolNode {
                         status: 'error',
                         arguments: req.arguments,
                         error: result.error ?? 'unknown error',
+                        ...toolArtifactFields(result),
                         executionTime,
                     });
                 }
@@ -421,12 +431,15 @@ export class ToolNode {
             role: 'tool',
             content: result.success
                 ? result.content
-                : `[Tool Error] ${result.error ?? 'unknown error'}`,
+                : toolResultHasArtifacts(result) && result.content
+                    ? `${result.content}\n[Tool Error] ${result.error ?? 'unknown error'}`
+                    : `[Tool Error] ${result.error ?? 'unknown error'}`,
             // 以下字段符合 LLM function-calling 协议（ToolMessage 接口）
             toolCallId: result.toolCallId,
             toolName: result.toolName,
             success: result.success,
             ...('file' in result && result.file ? { file: result.file } : {}),
+            ...('files' in result && result.files?.length ? { files: result.files } : {}),
         }));
         const lastSpanId = [...spanIds].reverse().find((id) => Boolean(id));
         return {
@@ -477,6 +490,7 @@ export class ToolNode {
                 status: 'error',
                 arguments: req.arguments,
                 error: last.error ?? 'unknown error',
+                ...toolArtifactFields(last),
                 willRetry: true,
             });
             await sleepToolRetry(toolRetryDelayMs(attempt, retry.backoff));

package/dist/graph/trace-span.d.ts

@@ -12,4 +12,18 @@ export declare function completeGraphSpan(state: Record<string, unknown>, spanId
 export declare function withGraphSpan(state: Record<string, unknown>, spec: {
     name: string;
     type: ExecutionNodeEvent['type'];
-}, run: () => Promise<Record<string, unknown>>): Promise<Record<string, unknown>>;
+    extra?: Partial<Omit<ExecutionNodeEvent, 'traceId' | 'name' | 'type' | 'parentNodeId'>>;
+}, run: () => Promise<Record<string, unknown>>, complete?: {
+    outputFrom?: (result: Record<string, unknown>) => unknown;
+}): Promise<Record<string, unknown>>;
+/** llm Span create 时的 input：组装后的 system、工具短目录、本回合 messages。 */
+export declare function llmSpanInput(input: {
+    system?: string;
+    tools?: Array<{
+        name: string;
+        description?: string;
+    }>;
+    messages: unknown;
+}): Record<string, unknown>;
+/** llm Span complete 的 output：本回合新增 assistant（含 toolCalls）或 silentOutput。 */
+export declare function llmSpanOutputFromResult(result: Record<string, unknown>): unknown;

package/dist/graph/trace-span.js

@@ -43,15 +43,17 @@ export async function completeGraphSpan(state, spanId, params, collectorOverride
         warnTraceSpanFailure('completeNode', { spanId, traceId: resolveExecutionTrace(state).traceId }, err);
     }
 }
-export async function withGraphSpan(state, spec, run) {
+export async function withGraphSpan(state, spec, run, complete) {
     const spanId = await startGraphSpan(state, spec);
     try {
         const result = await run();
         const usage = Array.isArray(result['__llmTokenUsage'])
             ? result['__llmTokenUsage'].at(-1)
             : undefined;
+        const output = complete?.outputFrom?.(result);
         await completeGraphSpan(state, spanId, {
             status: 'completed',
+            ...(output !== undefined ? { output } : {}),
             inputTokens: usage?.inputTokens,
             outputTokens: usage?.outputTokens,
             totalTokens: usage?.inputTokens != null || usage?.outputTokens != null
@@ -69,3 +71,69 @@ export async function withGraphSpan(state, spec, run) {
         throw err;
     }
 }
+function spanGraphMessages(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.map((msg) => {
+        if (typeof msg !== 'object' || msg === null) {
+            return { role: 'user', content: String(msg) };
+        }
+        const m = msg;
+        const out = {
+            role: typeof m['role'] === 'string' ? m['role'] : 'user',
+            content: typeof m['content'] === 'string' ? m['content'] : '',
+        };
+        const toolCalls = m['toolCalls'] ?? m['tool_calls'];
+        if (toolCalls !== undefined)
+            out.toolCalls = toolCalls;
+        const toolCallId = typeof m['toolCallId'] === 'string'
+            ? m['toolCallId']
+            : typeof m['tool_call_id'] === 'string'
+                ? m['tool_call_id']
+                : undefined;
+        if (toolCallId)
+            out.toolCallId = toolCallId;
+        if (typeof m['toolName'] === 'string')
+            out.toolName = m['toolName'];
+        if (typeof m['success'] === 'boolean')
+            out.success = m['success'];
+        const reasoning = typeof m['reasoningContent'] === 'string'
+            ? m['reasoningContent']
+            : typeof m['reasoning_content'] === 'string'
+                ? m['reasoning_content']
+                : undefined;
+        if (reasoning)
+            out.reasoningContent = reasoning;
+        return out;
+    });
+}
+/** llm Span create 时的 input：组装后的 system、工具短目录、本回合 messages。 */
+export function llmSpanInput(input) {
+    const tools = input.tools?.filter((t) => t.name);
+    return {
+        ...(input.system ? { system: input.system } : {}),
+        ...(tools && tools.length > 0 ? { tools } : {}),
+        messages: spanGraphMessages(input.messages),
+    };
+}
+/** llm Span complete 的 output：本回合新增 assistant（含 toolCalls）或 silentOutput。 */
+export function llmSpanOutputFromResult(result) {
+    if (typeof result['silentOutput'] === 'string') {
+        return { content: result['silentOutput'] };
+    }
+    const messages = Array.isArray(result['messages']) ? result['messages'] : [];
+    const added = messages[0];
+    if (!added || typeof added !== 'object')
+        return undefined;
+    const m = added;
+    const out = {
+        content: typeof m['content'] === 'string' ? m['content'] : '',
+    };
+    const toolCalls = m['toolCalls'] ?? m['tool_calls'];
+    if (Array.isArray(toolCalls) && toolCalls.length > 0)
+        out.toolCalls = toolCalls;
+    if (typeof m['reasoningContent'] === 'string' && m['reasoningContent']) {
+        out.reasoningContent = m['reasoningContent'];
+    }
+    return out;
+}

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

@@ -4,7 +4,7 @@
  * 目录（Agent 自包含，无全局共享层）：
  *   {root}/agents/<agentCode>/<version>/preinstall/tools/<toolsetCode>/
  *   {root}/agents/<agentCode>/<version>/preinstall/skills/<skillCode>/
- *   {root}/agents/<agentCode>/<version>/users/<userId>/skills/<skillCode>/
+ *   {root}/agents/<agentCode>/users/<userId>/skills/<skillCode>/
  *
  * 命名：agentCode / toolsetCode / skillCode / toolName 均为语义化小写标识；
  * Skill 目录无版本层：包内必含 SKILL.md（Agent Skills）。

package/dist/registry/deployment-snapshot.js

@@ -4,7 +4,7 @@
  * 目录（Agent 自包含，无全局共享层）：
  *   {root}/agents/<agentCode>/<version>/preinstall/tools/<toolsetCode>/
  *   {root}/agents/<agentCode>/<version>/preinstall/skills/<skillCode>/
- *   {root}/agents/<agentCode>/<version>/users/<userId>/skills/<skillCode>/
+ *   {root}/agents/<agentCode>/users/<userId>/skills/<skillCode>/
  *
  * 命名：agentCode / toolsetCode / skillCode / toolName 均为语义化小写标识；
  * Skill 目录无版本层：包内必含 SKILL.md（Agent Skills）。
@@ -18,6 +18,7 @@ import { findSkillEntryFile } from './skill-tree.js';
 import { preloadMissing, preloadPackageCorrupt, } from './preload-errors.js';
 import { isRequireChecksum, resolvePreloadBehaviorFlags, } from './preload-flags.js';
 import { emitRuntimeLog } from '../common/logger.js';
+import { userRoot, USERS_DIR_NAME } from '../common/user-root.js';
 async function pathExists(p) {
     try {
         await access(p, fsConstants.F_OK);
@@ -141,7 +142,9 @@ async function pickLatestVersionDir(parent) {
     if (!(await pathExists(parent)))
         return null;
     const entries = await readdir(parent, { withFileTypes: true });
-    const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    const dirs = entries
+        .filter((e) => e.isDirectory() && e.name !== USERS_DIR_NAME)
+        .map((e) => e.name);
     if (dirs.includes('current')) {
         return path.join(parent, 'current');
     }
@@ -534,7 +537,7 @@ export class FileSystemDeploymentSnapshot {
         // 用户装配 → 开发态作者源 extraRoots → Agent 预装
         const candidates = [];
         if (userId != null && userId !== '') {
-            candidates.push(path.join(agentDir, 'users', userId, 'skills', ref.skillId));
+            candidates.push(path.join(userRoot(agentDir, userId), 'skills', ref.skillId));
         }
         for (const root of extraRoots) {
             if (root)

package/dist/registry/skill-tree.d.ts

@@ -25,6 +25,6 @@ export declare function inspectAgentSkillTree(agentDir: string, userId?: string,
  */
 export declare function watchPreinstallSkillRoot(preinstallRoot: string, onChange: () => void, debounceMs?: number): () => void;
 export declare function watchSkillRoots(roots: string[], onChange: () => void, debounceMs?: number): () => void;
-export declare function watchAgentSkillDirs(agentDir: string, onChange: () => void, debounceMs?: number, extraRoots?: string[]): () => void;
+export declare function watchAgentSkillDirs(agentDir: string, onChange: () => void, debounceMs?: number, extraRoots?: string[], userId?: string): () => void;
 /** EAP_SKILL_HOT_RELOAD：dev 默认开；server/desktop 默认关 */
 export declare function resolveSkillHotReload(deploymentContext: string, explicit?: boolean): boolean;

package/dist/registry/skill-tree.js

@@ -2,7 +2,7 @@
  * Agent 自带 Skill 目录扫描（§3.1）
  *
  *   agents/<code>/<ver>/preinstall/skills/<skillCode>/
- *   agents/<code>/<ver>/users/<userId>/skills/<skillCode>/   同名覆盖
+ *   agents/<code>/users/<userId>/skills/<skillCode>/   同名覆盖（写根与 <ver> 平级）
  *
  * 热加载用 stamp：目录/文件 mtime 变化则缓存失效。
  */
@@ -11,6 +11,7 @@ import { watch } from 'node:fs';
 import { constants as fsConstants } from 'node:fs';
 import path from 'node:path';
 import { SKILL_ENTRY_CANDIDATES } from '@gt-fe/eap-contracts';
+import { userRoot } from '../common/user-root.js';
 const SKILL_CODE = /^[a-z0-9][a-z0-9-]*$/;
 async function exists(p) {
     try {
@@ -75,7 +76,7 @@ export async function readSkillAssembly(agentDir, userId) {
     const candidates = [];
     const uid = userId?.trim();
     if (uid)
-        candidates.push(path.join(agentDir, 'users', uid, '.assembly.json'));
+        candidates.push(path.join(userRoot(agentDir, uid), '.assembly.json'));
     candidates.push(path.join(agentDir, '.assembly.json'), path.join(agentDir, 'assembly.json'));
     for (const file of candidates) {
         const parsed = await readAssemblyFile(file);
@@ -102,7 +103,7 @@ export async function skillAssemblyStamp(agentDir, userId) {
     const candidates = [];
     const uid = userId?.trim();
     if (uid)
-        candidates.push(path.join(agentDir, 'users', uid, '.assembly.json'));
+        candidates.push(path.join(userRoot(agentDir, uid), '.assembly.json'));
     candidates.push(path.join(agentDir, '.assembly.json'), path.join(agentDir, 'assembly.json'));
     let latest = 0;
     for (const file of candidates) {
@@ -114,7 +115,7 @@ export function preinstallSkillsDir(agentDir) {
     return path.join(agentDir, 'preinstall', 'skills');
 }
 export function userSkillsDir(agentDir, userId) {
-    return path.join(agentDir, 'users', userId, 'skills');
+    return path.join(userRoot(agentDir, userId), 'skills');
 }
 export async function inspectAgentSkillTree(agentDir, userId, extraRoots = []) {
     const roots = [preinstallSkillsDir(agentDir), ...extraRoots.filter(Boolean)];
@@ -205,8 +206,12 @@ export function watchSkillRoots(roots, onChange, debounceMs = 200) {
             watcher.close();
     };
 }
-export function watchAgentSkillDirs(agentDir, onChange, debounceMs = 200, extraRoots = []) {
-    return watchSkillRoots([preinstallSkillsDir(agentDir), path.join(agentDir, 'users'), ...extraRoots], onChange, debounceMs);
+export function watchAgentSkillDirs(agentDir, onChange, debounceMs = 200, extraRoots = [], userId) {
+    const roots = [preinstallSkillsDir(agentDir), ...extraRoots];
+    const uid = userId?.trim();
+    if (uid)
+        roots.push(userSkillsDir(agentDir, uid));
+    return watchSkillRoots(roots, onChange, debounceMs);
 }
 /** EAP_SKILL_HOT_RELOAD：dev 默认开；server/desktop 默认关 */
 export function resolveSkillHotReload(deploymentContext, explicit) {

package/dist/runtime/agent-runtime.js

@@ -16,6 +16,7 @@ import { toLoadedSkillMap } from '../tool/system-prompt-builder.js';
 import { assembleLoadedTools } from '../tool/harness-primitives.js';
 import { createFileLlmTurnLogFromEnv, } from '../debug/llm-turn-log.js';
 import { buildHitlWaitingTaskOutput, buildTurnTranscriptFromStreamEvents, loadModelFacingHistory, turnGraphMessagesAfterCompression, extractHitlThreadId, extractStreamReasoning, applyStreamTextDelta, createStreamAssistantBuckets, visibleStreamAssistantText, streamAssistantTexts, messageRecordsToGraphMessages, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, resolveCheckpointThreadId, appendTerminalToolResult, } from '../session/persist-turn-messages.js';
+import { collectPublicArtifactLinks, collectPublicArtifactLinksFromEvent, injectPublicArtifactLinks, mergeArtifactLinks, } from '../tool/inject-public-artifact-links.js';
 import { iterSessionCompression, withCompressionSummaryModel, } from '../session/apply-session-compression.js';
 import { applySessionMemory } from '../session/apply-session-memory.js';
 import { buildSessionTitleUserPayload, invokeSessionTitle, } from '../session/session-title.js';
@@ -378,6 +379,7 @@ export class AgentRuntime {
         let assistantReasoningContent;
         const pendingToolCalls = [];
         const toolResults = [];
+        const artifactLinks = [];
         const nodeTokenUsages = [];
         try {
             for await (const runtimeEvent of runWithExecutionTrace({ abortSignal }, () => this.deps.graphEngine.stream(graph, {
@@ -421,6 +423,7 @@ export class AgentRuntime {
                 }
                 // 终态 tool.result / tool.error 回填历史；willRetry 的 error 不进 transcript
                 appendTerminalToolResult(runtimeEvent.type, runtimeEvent.payload, toolResults);
+                collectPublicArtifactLinksFromEvent(runtimeEvent.type, runtimeEvent.payload, artifactLinks);
                 const streamedReasoning = extractStreamReasoning(runtimeEvent.type, runtimeEvent.payload);
                 if (streamedReasoning)
                     assistantReasoningContent = streamedReasoning;
@@ -433,6 +436,19 @@ export class AgentRuntime {
             await recordTaskTokenUsages(this.deps.taskService, task.id, nodeTokenUsages);
             await this.deps.taskService.updateStatus(task.id, 'success');
             const tokenSummary = summarizeTokenUsages(nodeTokenUsages);
+            const visible = visibleStreamAssistantText(assistantBuckets);
+            const links = mergeArtifactLinks(artifactLinks, collectPublicArtifactLinks(toolResults));
+            const { injected, suffix } = injectPublicArtifactLinks(visible, links);
+            if (suffix) {
+                yield this.toSSE('response.chunk', correlationId, task.id, {
+                    content: suffix,
+                    format: 'text',
+                });
+            }
+            yield this.toSSE('response.final', correlationId, task.id, {
+                content: injected,
+                format: 'text',
+            });
             await persistTurnTranscript(this.deps.messageService, {
                 sessionId,
                 taskId: task.id,
@@ -440,8 +456,8 @@ export class AgentRuntime {
                 messages: buildTurnTranscriptFromStreamEvents({
                     pendingToolCalls,
                     toolResults,
-                    assistantTexts: streamAssistantTexts(assistantBuckets),
-                    assistantText: visibleStreamAssistantText(assistantBuckets),
+                    assistantTexts: suffix ? undefined : streamAssistantTexts(assistantBuckets),
+                    assistantText: injected,
                     finishPoints: graph.finishPoints,
                     toolCallReasoningContent,
                     assistantReasoningContent,
@@ -621,6 +637,7 @@ export class AgentRuntime {
         let assistantReasoningContent;
         const pendingToolCalls = [];
         const toolResults = [];
+        const artifactLinks = [];
         const nodeTokenUsages = [];
         try {
             for await (const runtimeEvent of runWithExecutionTrace({ abortSignal, abortDeadlineMs: continueState.abortDeadlineMs }, () => this.deps.graphEngine.stream(graph, continueState))) {
@@ -638,6 +655,7 @@ export class AgentRuntime {
                     }
                 }
                 appendTerminalToolResult(runtimeEvent.type, runtimeEvent.payload, toolResults);
+                collectPublicArtifactLinksFromEvent(runtimeEvent.type, runtimeEvent.payload, artifactLinks);
                 const streamedReasoning = extractStreamReasoning(runtimeEvent.type, runtimeEvent.payload);
                 if (streamedReasoning)
                     assistantReasoningContent = streamedReasoning;
@@ -647,8 +665,21 @@ export class AgentRuntime {
                     yield this.runtimeEventToSSE(runtimeEvent, correlationId, taskId);
                 }
             }
+            const visible = visibleStreamAssistantText(assistantBuckets);
+            const links = mergeArtifactLinks(artifactLinks, collectPublicArtifactLinks(toolResults));
+            const { injected, suffix } = injectPublicArtifactLinks(visible, links);
+            if (suffix) {
+                yield this.toSSE('response.chunk', correlationId, taskId, {
+                    content: suffix,
+                    format: 'text',
+                });
+            }
+            yield this.toSSE('response.final', correlationId, taskId, {
+                content: injected,
+                format: 'text',
+            });
             await recordTaskTokenUsages(this.deps.taskService, taskId, nodeTokenUsages);
-            await this.deps.taskService.updateStatus(taskId, 'success', visibleStreamAssistantText(assistantBuckets) || undefined);
+            await this.deps.taskService.updateStatus(taskId, 'success', injected || undefined);
             const tokenSummary = summarizeTokenUsages(nodeTokenUsages);
             if (sessionId) {
                 await persistTurnTranscript(this.deps.messageService, {
@@ -658,8 +689,8 @@ export class AgentRuntime {
                     messages: buildTurnTranscriptFromStreamEvents({
                         pendingToolCalls,
                         toolResults,
-                        assistantTexts: streamAssistantTexts(assistantBuckets),
-                        assistantText: visibleStreamAssistantText(assistantBuckets),
+                        assistantTexts: suffix ? undefined : streamAssistantTexts(assistantBuckets),
+                        assistantText: injected,
                         finishPoints: graph.finishPoints,
                         toolCallReasoningContent,
                         assistantReasoningContent,

package/dist/session/persist-turn-messages.d.ts

@@ -91,12 +91,7 @@ export declare function sessionVisibleGraphMessages(messages: GraphMessage[], fi
 export declare function extractStreamReasoning(eventType: string, payload: unknown): string | undefined;
 /** 落盘 / 回填历史只收终态：result，或不会再试的 error。willRetry 的 error 只给直播 UI。 */
 export declare function isTerminalToolStreamEvent(eventType: string, payload: unknown): boolean;
-export declare function appendTerminalToolResult(eventType: string, payload: unknown, bucket: Array<{
-    toolCallId: string;
-    toolName: string;
-    content: unknown;
-    success: boolean;
-}>): void;
+export declare function appendTerminalToolResult(eventType: string, payload: unknown, bucket: StreamToolResult[]): void;
 /** 历史 MessageRecord → GraphMessage（保留 tool 元数据与 reasoning） */
 export declare function messageRecordsToGraphMessages(records: MessageRecord[]): GraphMessage[];
 type CheckpointLoad = {
@@ -203,6 +198,18 @@ export type StreamToolResult = {
     toolName: string;
     content: unknown;
     success: boolean;
+    file?: {
+        fileName: string;
+        fileType: string;
+        size: number;
+        url: string;
+    };
+    files?: Array<{
+        fileName: string;
+        fileType: string;
+        size: number;
+        url: string;
+    }>;
 };
 /**
  * 将 stream 侧累加的 tool 事件规范为与 invoke GraphState 增量同序的 messages：

package/dist/session/persist-turn-messages.js

@@ -242,6 +242,8 @@ export function appendTerminalToolResult(eventType, payload, bucket) {
         toolName: p.toolName,
         content: p.content ?? p.error,
         success: eventType === 'tool.result' && p.success !== false,
+        ...(p.file ? { file: p.file } : {}),
+        ...(p.files?.length ? { files: p.files } : {}),
     });
 }
 /** 历史 MessageRecord → GraphMessage（保留 tool 元数据与 reasoning） */
@@ -525,6 +527,8 @@ export function buildTurnTranscriptFromStreamEvents(params) {
             toolCallId: tr.toolCallId,
             toolName: tr.toolName,
             success: tr.success,
+            ...(tr.file ? { file: tr.file } : {}),
+            ...(tr.files?.length ? { files: tr.files } : {}),
         });
     }
     if (texts.length > 0) {

package/dist/sse/events/tool-events.d.ts

@@ -30,6 +30,19 @@ export interface ToolResultPayload {
     content: unknown;
     /** 是否执行成功 */
     success: boolean;
+    /** 与 ToolCallResult.file 同形；SSE / persist / 注入共用 */
+    file?: {
+        fileName: string;
+        fileType: string;
+        size: number;
+        url: string;
+    };
+    files?: Array<{
+        fileName: string;
+        fileType: string;
+        size: number;
+        url: string;
+    }>;
 }
 /** 工具执行进度 */
 export type ToolProgressStatus = 'started' | 'completed' | 'error' | (string & {});
@@ -52,6 +65,8 @@ export interface ToolProgressPayload {
     content?: unknown;
     /** status=error 时可选：错误信息 */
     error?: string;
+    file?: ToolResultPayload['file'];
+    files?: ToolResultPayload['files'];
     /** 执行耗时（毫秒），status=completed|error 时可选 */
     executionTime?: number;
 }
@@ -65,4 +80,18 @@ export interface ToolErrorPayload {
     error: string;
     /** 是否会自动重试 */
     willRetry: boolean;
+    /** 失败且有交付物时保留原正文（与 ToolCallResult.content 同形） */
+    content?: unknown;
+    file?: {
+        fileName: string;
+        fileType: string;
+        size: number;
+        url: string;
+    };
+    files?: Array<{
+        fileName: string;
+        fileType: string;
+        size: number;
+        url: string;
+    }>;
 }

package/dist/tool/harness-command.d.ts

@@ -27,6 +27,6 @@ export declare function ensurePythonShims(workdir: string): string | undefined;
  * spawn 前替换成绝对路径，不依赖壳去展开。
  */
 export declare function substituteSkillDir(command: string, skillDir?: string): string;
-export declare function sandboxEnv(workdir: string, cwd: string, allowlist: string[], shimDir?: string, skillDir?: string): NodeJS.ProcessEnv;
+export declare function sandboxEnv(workdir: string, cwd: string, allowlist: string[], shimDir?: string, skillDir?: string, homeDir?: string): NodeJS.ProcessEnv;
 export declare function formatSpawnError(err: unknown, shellFile: string): Error;
 export declare function killProcessTree(child: ChildProcess): void;

package/dist/tool/harness-command.js

@@ -21,7 +21,7 @@ export function commandDialectLines(platform = process.platform) {
     else {
         lines.push('基础命令：当前目录 `pwd`；列目录 `ls`；环境变量 `$VAR`；串命令用 `&&`。');
     }
-    lines.push('解释器：`python`/`python3`、`node`/`nodejs`、`sh`/`bash`（Windows 上 `sh` 需本机有 Git Bash 等）。', '可执行文件：用绝对路径或相对于 cwd（Windows `.exe`/`.bat`/`.cmd`；Unix 二进制需可执行或用 `sh`）。', '`execute_command` 的 cwd 是用户目录。技能包只读。包内任意文件用 `EAP_SKILL_DIR` 加相对路径（不限 `scripts/`）。读到的 SKILL.md 里本包存在的相对路径已展开为绝对路径。不要把 cwd 设成技能目录。相对写出在用户目录。');
+    lines.push('解释器：`python`/`python3`、`node`/`nodejs`、`sh`/`bash`（Windows 上 `sh` 需本机有 Git Bash 等）。', '可执行文件：用绝对路径或相对于 cwd（Windows `.exe`/`.bat`/`.cmd`；Unix 二进制需可执行或用 `sh`）。', '`execute_command` 的 cwd 默认是用户目录下的 `files/`。技能包只读。包内任意文件用 `EAP_SKILL_DIR` 加相对路径（不限 `scripts/`）。读到的 SKILL.md 里本包存在的相对路径已展开为绝对路径。不要把 cwd 设成技能目录、`work/` 或 `public/`。相对写出在 `files/`。');
     return lines;
 }
 export function resolveShellSpawn(command, platform = process.platform) {
@@ -179,22 +179,23 @@ export function substituteSkillDir(command, skillDir) {
         .replace(/\$EAP_SKILL_DIR\b/g, dir)
         .replace(/%EAP_SKILL_DIR%/gi, dir);
 }
-export function sandboxEnv(workdir, cwd, allowlist, shimDir, skillDir) {
+export function sandboxEnv(workdir, cwd, allowlist, shimDir, skillDir, homeDir) {
     const win = process.platform === 'win32';
     const hostPath = process.env.PATH
         ?? (win
             ? (process.env.SystemRoot ? path.join(process.env.SystemRoot, 'System32') : 'C:\\Windows\\System32')
             : '/usr/bin:/bin:/usr/local/bin');
     const pathValue = shimDir ? `${shimDir}${path.delimiter}${hostPath}` : hostPath;
+    const home = homeDir?.trim() ? path.resolve(homeDir) : workdir;
     const env = {
         PATH: pathValue,
         LANG: process.env.LANG ?? 'C.UTF-8',
         LC_ALL: process.env.LC_ALL ?? process.env.LANG ?? 'C.UTF-8',
-        HOME: workdir,
-        USERPROFILE: workdir,
-        TMPDIR: workdir,
-        TMP: workdir,
-        TEMP: workdir,
+        HOME: home,
+        USERPROFILE: home,
+        TMPDIR: home,
+        TMP: home,
+        TEMP: home,
         PWD: cwd,
         PYTHONUTF8: '1',
         PYTHONIOENCODING: 'utf-8',

package/dist/tool/harness-primitives.d.ts

@@ -2,9 +2,9 @@
  * 平台默认 Harness 原语：read_file / write_file / execute_command。
  *
  * 不写进 agent.manifest.toolsets。同名业务工具优先（问数 file-io 等）。
- * 写：`users/<userId>/`（含用户自己的 skills）。
+ * 写：`dirname(agentDir)/users/<userId>/`（含用户自己的 skills）。产物默认 `files/`，公开副本 `public/`。
  * 读：写根 + 已装配 `preinstall/tools`、`preinstall/skills`。
- * 命令：cwd 仅写根。技能包只读，EAP_SKILL_DIR 为整包绝对根（不限 scripts/）。不把预装拷进用户装配槽。
+ * 命令：cwd 默认 `files/`。技能包只读，EAP_SKILL_DIR 为整包绝对根（不限 scripts/）。不把预装拷进用户装配槽。
  * 开发态 overlay：`EAP_LOCAL_SKILLS_DIR` / `EAP_LOCAL_TOOLS_DIR`（只读）。在 `createDevRuntime` /
  * `createToolExecutor` 时钉进执行器 extraRoots；SDK `createAgent` 构造完会恢复 process.env，
  * 请求时不再读这两项。相对 `read_file` 会把 overlay 根下直接子目录里带 SKILL.md 的包纳入唯一命中。
@@ -19,7 +19,7 @@ export interface HarnessJailOptions {
     workdir?: string;
     extraRoots?: string[];
 }
-/** `{agentDir}/users/<userId>`（写根；含用户 skills） */
+/** `dirname(agentDir)/users/<userId>`（写根；含用户 skills） */
 export declare function resolveUserDir(agentDir: string, userId: string): string;
 export declare function collectToolBundlePaths(loadedTools?: LoadedToolMap): string[];
 export declare function resolveJailFromState(state: {