@gt-fe/eap-runtime 0.0.30 → 0.0.32

package/dist/tool/static-artifact-url.js

@@ -0,0 +1,561 @@
+/**
+ * 用户产物公开副本：files/ 工作稿 → public/ 时间戳 copy；拼 Hosting /static url。
+ * @see docs/design/user-artifact-delivery.md
+ */
+import { randomBytes } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { chmod, copyFile, cp, link, lstat, mkdir, open, readdir, rename, rm, stat, unlink, } from 'node:fs/promises';
+import path from 'node:path';
+/** 与 contracts `DEFAULT_BUILTIN_MAX_WRITE_BYTES` 同值；本地编译不依赖未发版 contracts */
+export const DEFAULT_MAX_WRITE_BYTES = 50 * 1024 * 1024;
+export const PUBLIC_DIR_MODE = 0o755;
+export const PUBLIC_FILE_MODE = 0o644;
+export const MAX_SNAPSHOT_ENUM = 5000;
+export const MAX_SNAPSHOT_URLS = 20;
+export const MAX_PUBLIC_NAME_ATTEMPTS = 8;
+export const PUBLIC_EXTENSIONS = new Set([
+    'html',
+    'htm',
+    'pdf',
+    'png',
+    'jpg',
+    'jpeg',
+    'gif',
+    'webp',
+    'css',
+    'xlsx',
+    'xls',
+    'csv',
+    'tsv',
+    'docx',
+    'doc',
+    'pptx',
+    'ppt',
+    'zip',
+    'json',
+    'md',
+    'txt',
+    'xml',
+    'js',
+    'svg',
+]);
+const DENY_SEGMENTS = new Set([
+    'preinstall',
+    'skills',
+    'node_modules',
+    'node-compile-cache',
+    'work',
+    'files',
+]);
+const SNAPSHOT_JUNK_NAMES = new Set([
+    'package.json',
+    'package-lock.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+    'bun.lock',
+    'bun.lockb',
+    'tsconfig.json',
+    'jsconfig.json',
+    'go.mod',
+    'go.sum',
+    'Cargo.toml',
+    'Cargo.lock',
+    'requirements.txt',
+    'Pipfile',
+    'Pipfile.lock',
+    'poetry.lock',
+    'pyproject.toml',
+    'setup.py',
+    'setup.cfg',
+    'README',
+    'README.md',
+    'README.txt',
+    'LICENSE',
+    'LICENSE.md',
+    'Makefile',
+    '__init__.py',
+].map((n) => n.toLowerCase()));
+const SUFFIX_RE = /_(\d{12}|\d{15})$/;
+const publishQueues = new Map();
+export function staticBaseUrlFromEnv(env = process.env) {
+    const raw = env.EAP_STATIC_BASE_URL?.trim();
+    if (!raw)
+        return undefined;
+    return raw.replace(/\/+$/, '');
+}
+export function preinstallRootFromEnv(env = process.env) {
+    const raw = env.EAP_PREINSTALL_ROOT?.trim();
+    if (!raw)
+        return undefined;
+    return path.resolve(raw);
+}
+export function encodePublicRel(rel) {
+    return rel
+        .replace(/\\/g, '/')
+        .split('/')
+        .filter((seg) => seg.length > 0)
+        .map((seg) => encodeURIComponent(seg))
+        .join('/');
+}
+export function isPublicUserArtifactRel(rel) {
+    const posix = rel.replace(/\\/g, '/').replace(/^\/+/, '');
+    const m = posix.match(/^agents\/[a-z0-9][a-z0-9-]*\/users\/[A-Za-z0-9][A-Za-z0-9._-]*\/public\/(.+)$/);
+    if (!m)
+        return false;
+    const rest = m[1];
+    const segs = rest.split('/').filter(Boolean);
+    if (segs.length === 0)
+        return false;
+    if (segs.some((seg) => DENY_SEGMENTS.has(seg) || seg.startsWith('.')))
+        return false;
+    const base = segs[segs.length - 1] ?? '';
+    if (base === 'assembly.json')
+        return false;
+    const first = segs[0] ?? '';
+    const firstStem = first.includes('.') ? first.slice(0, first.lastIndexOf('.')) : first;
+    if (!/_[0-9]{12}([0-9]{3})?$/.test(firstStem))
+        return false;
+    const ext = path.extname(base).slice(1).toLowerCase();
+    return PUBLIC_EXTENSIONS.has(ext);
+}
+export function publicArtifactUrl(absPath, env = process.env) {
+    const rootRaw = preinstallRootFromEnv(env);
+    const base = staticBaseUrlFromEnv(env);
+    if (!rootRaw || !base)
+        return undefined;
+    const root = tryRealpath(rootRaw) ?? path.resolve(rootRaw);
+    const abs = tryRealpath(absPath) ?? path.resolve(absPath);
+    const rel = path.relative(root, abs).replace(/\\/g, '/');
+    if (rel.startsWith('..') || path.isAbsolute(rel))
+        return undefined;
+    if (!isPublicUserArtifactRel(rel))
+        return undefined;
+    return `${base}/${encodePublicRel(rel)}`;
+}
+export function publicTimeSuffix(now = new Date(), withMs = false) {
+    const parts = new Intl.DateTimeFormat('en-GB', {
+        timeZone: 'Asia/Shanghai',
+        year: '2-digit',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hourCycle: 'h23',
+    }).formatToParts(now);
+    const pick = (type) => parts.find((p) => p.type === type)?.value ?? '00';
+    const stamp = `${pick('year')}${pick('month')}${pick('day')}${pick('hour')}${pick('minute')}${pick('second')}`;
+    if (!withMs)
+        return stamp;
+    return `${stamp}${String(now.getMilliseconds()).padStart(3, '0')}`;
+}
+export function stripPublicSuffix(name) {
+    const ext = path.extname(name);
+    const stem = ext ? name.slice(0, -ext.length) : name;
+    const stripped = stem.replace(SUFFIX_RE, '');
+    return stripped + ext;
+}
+export function extensionOf(name) {
+    return path.extname(name).slice(1).toLowerCase();
+}
+export function isPublicExtension(name) {
+    return PUBLIC_EXTENSIONS.has(extensionOf(name));
+}
+export function isSnapshotJunkName(name) {
+    return SNAPSHOT_JUNK_NAMES.has(stripPublicSuffix(path.basename(name)).toLowerCase());
+}
+export async function mkdirChmod(dir, mode = PUBLIC_DIR_MODE) {
+    await mkdir(dir, { recursive: true, mode });
+    await chmod(dir, mode);
+}
+/** 四槽 `skills/` `work/` `files/` `public/`，目录 0755（与 Hosting `ensureUserWorkspace` 对齐）。 */
+export async function ensureUserSlots(userDir) {
+    await mkdirChmod(userDir, PUBLIC_DIR_MODE);
+    const filesDir = path.join(userDir, 'files');
+    const workDir = path.join(userDir, 'work');
+    const publicDir = path.join(userDir, 'public');
+    const skillsDir = path.join(userDir, 'skills');
+    await mkdirChmod(filesDir, PUBLIC_DIR_MODE);
+    await mkdirChmod(workDir, PUBLIC_DIR_MODE);
+    await mkdirChmod(publicDir, PUBLIC_DIR_MODE);
+    await mkdirChmod(skillsDir, PUBLIC_DIR_MODE);
+    return { filesDir, workDir, publicDir, skillsDir };
+}
+async function chmodTree(root) {
+    await chmod(root, PUBLIC_DIR_MODE);
+    try {
+        const entries = await readdir(root, { withFileTypes: true });
+        for (const ent of entries) {
+            const child = path.join(root, ent.name);
+            if (ent.isDirectory())
+                await chmodTree(child);
+            else if (ent.isFile())
+                await chmod(child, PUBLIC_FILE_MODE);
+        }
+    }
+    catch {
+        return;
+    }
+}
+function enqueueUserDir(userDir, job) {
+    const key = path.resolve(userDir);
+    const prev = publishQueues.get(key) ?? Promise.resolve();
+    const next = prev.then(job, job);
+    publishQueues.set(key, next.then(() => undefined, () => undefined));
+    return next;
+}
+async function exclusiveTmpFile(publicDir) {
+    for (let i = 0; i < 16; i++) {
+        const tmp = path.join(publicDir, `.tmp-${randomBytes(8).toString('hex')}`);
+        try {
+            const handle = await open(tmp, 'wx', PUBLIC_FILE_MODE);
+            await handle.close();
+            return tmp;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+        }
+    }
+    throw new Error('无法创建公开临时文件');
+}
+async function exclusiveTmpDir(publicDir) {
+    for (let i = 0; i < 16; i++) {
+        const tmp = path.join(publicDir, `.tmp-${randomBytes(8).toString('hex')}`);
+        try {
+            await mkdir(tmp, { recursive: false, mode: PUBLIC_DIR_MODE });
+            await chmod(tmp, PUBLIC_DIR_MODE);
+            return tmp;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+        }
+    }
+    throw new Error('无法创建公开临时目录');
+}
+async function waitNextMs(from) {
+    let now = Date.now();
+    while (now <= from) {
+        await new Promise((r) => setTimeout(r, 1));
+        now = Date.now();
+    }
+    return new Date(now);
+}
+export async function allocPublicBasename(publicDir, srcFile, originalBasename) {
+    const stripped = stripPublicSuffix(originalBasename);
+    const ext = path.extname(stripped);
+    const stem = ext ? stripped.slice(0, -ext.length) : stripped;
+    let withMs = false;
+    let lastMs = Date.now();
+    for (let attempt = 0; attempt < MAX_PUBLIC_NAME_ATTEMPTS; attempt++) {
+        const now = attempt === 0 ? new Date() : await waitNextMs(lastMs);
+        lastMs = now.getTime();
+        const stamp = publicTimeSuffix(now, withMs);
+        const destName = `${stem}_${stamp}${ext}`;
+        const dest = path.join(publicDir, destName);
+        const tmp = await exclusiveTmpFile(publicDir);
+        try {
+            await copyFile(srcFile, tmp);
+            await chmod(tmp, PUBLIC_FILE_MODE);
+            try {
+                await link(tmp, dest);
+            }
+            catch (err) {
+                if (err.code === 'EEXIST') {
+                    withMs = true;
+                    continue;
+                }
+                throw err;
+            }
+            await chmod(dest, PUBLIC_FILE_MODE);
+            return destName;
+        }
+        finally {
+            await unlink(tmp).catch(() => undefined);
+        }
+    }
+    return undefined;
+}
+export async function allocPublicDir(publicDir, srcDir, originalDirName) {
+    const stem = stripPublicSuffix(originalDirName).replace(/\.[^.]+$/, '') || originalDirName;
+    let withMs = false;
+    let lastMs = Date.now();
+    for (let attempt = 0; attempt < MAX_PUBLIC_NAME_ATTEMPTS; attempt++) {
+        const now = attempt === 0 ? new Date() : await waitNextMs(lastMs);
+        lastMs = now.getTime();
+        const stamp = publicTimeSuffix(now, withMs);
+        const destName = `${stem}_${stamp}`;
+        const dest = path.join(publicDir, destName);
+        const tmp = await exclusiveTmpDir(publicDir);
+        try {
+            await cp(srcDir, tmp, { recursive: true });
+            await chmodTree(tmp);
+            try {
+                await rename(tmp, dest);
+            }
+            catch (err) {
+                const code = err.code;
+                if (code === 'EEXIST' || code === 'ENOTEMPTY' || code === 'EPERM') {
+                    withMs = true;
+                    await rm(tmp, { recursive: true, force: true }).catch(() => undefined);
+                    continue;
+                }
+                throw err;
+            }
+            await chmodTree(dest);
+            return destName;
+        }
+        catch (err) {
+            await rm(tmp, { recursive: true, force: true }).catch(() => undefined);
+            throw err;
+        }
+    }
+    return undefined;
+}
+function groupKey(relFromFiles) {
+    const posix = relFromFiles.replace(/\\/g, '/').replace(/^\/+/, '');
+    const slash = posix.indexOf('/');
+    return slash === -1 ? '.' : posix.slice(0, slash);
+}
+async function publishedFromAbs(abs, publicDir, env, sourceRel) {
+    const st = await stat(abs).catch(() => undefined);
+    if (!st?.isFile())
+        return undefined;
+    const fileName = path.relative(publicDir, abs).replace(/\\/g, '/');
+    return {
+        fileName,
+        fileType: extensionOf(abs),
+        size: st.size,
+        url: publicArtifactUrl(abs, env),
+        absPath: abs,
+        sourceRel,
+    };
+}
+async function pickDirUrlFile(dirAbs) {
+    const index = path.join(dirAbs, 'index.html');
+    if ((await stat(index).catch(() => undefined))?.isFile())
+        return index;
+    let newest;
+    async function walk(dir) {
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const ent of entries) {
+            const child = path.join(dir, ent.name);
+            if (ent.isDirectory())
+                await walk(child);
+            else if (ent.isFile() && isPublicExtension(ent.name)) {
+                const st = await stat(child);
+                if (!newest || st.mtimeMs > newest.mtime)
+                    newest = { abs: child, mtime: st.mtimeMs };
+            }
+        }
+    }
+    await walk(dirAbs);
+    return newest?.abs;
+}
+export async function publishFromFiles(userDir, relFromFiles, env = process.env) {
+    return enqueueUserDir(userDir, async () => {
+        const { filesDir, publicDir } = await ensureUserSlots(userDir);
+        const unique = [...new Set(relFromFiles.map((p) => p.replace(/\\/g, '/').replace(/^\/+/, '')))];
+        const groups = new Map();
+        for (const rel of unique) {
+            const key = groupKey(rel);
+            const list = groups.get(key) ?? [];
+            list.push(rel);
+            groups.set(key, list);
+        }
+        const out = [];
+        const rootFiles = groups.get('.') ?? [];
+        groups.delete('.');
+        for (const rel of rootFiles) {
+            const src = path.join(filesDir, rel);
+            const st = await stat(src).catch(() => undefined);
+            if (!st?.isFile())
+                continue;
+            if (!isPublicExtension(rel))
+                continue;
+            const destName = await allocPublicBasename(publicDir, src, path.basename(rel));
+            if (!destName)
+                continue;
+            const published = await publishedFromAbs(path.join(publicDir, destName), publicDir, env, rel);
+            if (published)
+                out.push(published);
+        }
+        for (const [dirName, _rels] of groups) {
+            const srcDir = path.join(filesDir, dirName);
+            const st = await stat(srcDir).catch(() => undefined);
+            if (!st?.isDirectory())
+                continue;
+            const destName = await allocPublicDir(publicDir, srcDir, dirName);
+            if (!destName)
+                continue;
+            const destAbs = path.join(publicDir, destName);
+            const urlFile = await pickDirUrlFile(destAbs);
+            if (!urlFile)
+                continue;
+            const inner = path.relative(destAbs, urlFile).replace(/\\/g, '/');
+            const sourceRel = inner && inner !== '.' ? `${dirName}/${inner}` : dirName;
+            const published = await publishedFromAbs(urlFile, publicDir, env, sourceRel);
+            if (published)
+                out.push(published);
+        }
+        return out;
+    });
+}
+export async function walkFilesTree(filesDir) {
+    const entries = new Map();
+    let truncated = false;
+    async function walk(dir, relBase) {
+        if (entries.size >= MAX_SNAPSHOT_ENUM) {
+            truncated = true;
+            return;
+        }
+        const list = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const ent of list) {
+            if (entries.size >= MAX_SNAPSHOT_ENUM) {
+                truncated = true;
+                return;
+            }
+            if (DENY_SEGMENTS.has(ent.name) || ent.name.startsWith('.'))
+                continue;
+            const rel = relBase ? `${relBase}/${ent.name}` : ent.name;
+            const abs = path.join(dir, ent.name);
+            if (ent.isDirectory()) {
+                await walk(abs, rel);
+                continue;
+            }
+            if (!ent.isFile())
+                continue;
+            const st = await lstat(abs).catch(() => undefined);
+            if (!st?.isFile())
+                continue;
+            entries.set(rel.replace(/\\/g, '/'), {
+                rel: rel.replace(/\\/g, '/'),
+                size: st.size,
+                mtimeMs: st.mtimeMs,
+                ctimeMs: st.ctimeMs,
+            });
+        }
+    }
+    await walk(filesDir, '');
+    return { entries, truncated };
+}
+export function snapshotCandidates(before, after, maxWriteBytes = DEFAULT_MAX_WRITE_BYTES) {
+    const rels = [];
+    let skippedOversize = 0;
+    for (const [rel, now] of after) {
+        if (!isPublicExtension(rel))
+            continue;
+        if (isSnapshotJunkName(rel))
+            continue;
+        if (now.size > maxWriteBytes) {
+            skippedOversize += 1;
+            continue;
+        }
+        const prev = before.get(rel);
+        if (!prev || prev.size !== now.size || prev.mtimeMs !== now.mtimeMs || prev.ctimeMs !== now.ctimeMs) {
+            rels.push(rel);
+        }
+    }
+    rels.sort((a, b) => {
+        const ma = after.get(a).mtimeMs;
+        const mb = after.get(b).mtimeMs;
+        if (mb !== ma)
+            return mb - ma;
+        return a.localeCompare(b);
+    });
+    return { rels, skippedOversize };
+}
+function tryRealpath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolveViaExistingAncestor(abs) {
+    const suffix = [];
+    let cur = abs;
+    while (true) {
+        const real = tryRealpath(cur);
+        if (real)
+            return path.resolve(real, ...suffix);
+        const parent = path.dirname(cur);
+        if (parent === cur)
+            return abs;
+        suffix.unshift(path.basename(cur));
+        cur = parent;
+    }
+}
+function canonPath(p) {
+    const resolved = path.resolve(p);
+    return tryRealpath(resolved) ?? resolveViaExistingAncestor(resolved);
+}
+export function resolveUserProductPath(requested, userDir, kind) {
+    const trimmed = requested.trim();
+    if (!trimmed || trimmed.includes('\0')) {
+        throw new Error('非法路径');
+    }
+    const posix = trimmed.replace(/\\/g, '/');
+    const root = canonPath(userDir);
+    const filesDir = canonPath(path.join(root, 'files'));
+    const skillsDir = canonPath(path.join(root, 'skills'));
+    const workDir = canonPath(path.join(root, 'work'));
+    const publicDir = canonPath(path.join(root, 'public'));
+    const inside = (candidate, dir) => {
+        const rel = path.relative(dir, candidate);
+        return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+    };
+    let abs;
+    let keepPrefix = false;
+    if (path.isAbsolute(posix)) {
+        abs = canonPath(posix);
+    }
+    else if (posix === 'skills' || posix.startsWith('skills/')) {
+        abs = canonPath(path.join(root, posix));
+        keepPrefix = true;
+    }
+    else if (posix === 'files' || posix.startsWith('files/')) {
+        abs = canonPath(path.join(root, posix));
+        keepPrefix = true;
+    }
+    else if (posix === 'work' || posix.startsWith('work/') || posix === 'public' || posix.startsWith('public/')) {
+        throw new Error(`路径超出允许目录：${trimmed}`);
+    }
+    else {
+        abs = canonPath(path.join(filesDir, posix));
+    }
+    if (inside(abs, workDir) || inside(abs, publicDir) || abs === root) {
+        throw new Error(`路径超出允许目录：${trimmed}`);
+    }
+    if (inside(abs, skillsDir)) {
+        if (kind === 'cwd')
+            throw new Error(`路径超出允许目录：${trimmed}`);
+        const rel = path.relative(root, abs).replace(/\\/g, '/');
+        return { abs, jsonPath: rel, slot: 'skills' };
+    }
+    if (inside(abs, filesDir) && abs !== filesDir) {
+        const relFromFiles = path.relative(filesDir, abs).replace(/\\/g, '/');
+        const relFromUser = path.relative(root, abs).replace(/\\/g, '/');
+        return {
+            abs,
+            jsonPath: keepPrefix || path.isAbsolute(posix) ? relFromUser : relFromFiles,
+            slot: 'files',
+            relFromFiles,
+        };
+    }
+    if (kind === 'cwd' && abs === filesDir) {
+        return { abs: filesDir, jsonPath: 'files', slot: 'files', relFromFiles: '' };
+    }
+    throw new Error(`路径超出允许目录：${trimmed}`);
+}
+export function maxWriteBytesFromEnv(env = process.env) {
+    const raw = env.EAP_BUILTIN_MAX_WRITE_BYTES?.trim();
+    if (!raw)
+        return DEFAULT_MAX_WRITE_BYTES;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return DEFAULT_MAX_WRITE_BYTES;
+    return Math.floor(n);
+}

package/dist/tool/system-prompt-builder.js

@@ -166,7 +166,10 @@ export class SystemPromptBuilder {
         const lines = ['## 文件与命令权限'];
         if (workdir) {
             lines.push(`工作目录：${workdir}`);
-            lines.push('`execute_command` 的 cwd **必须**是工作目录或其子目录，不能是预装技能/工具包。');
+            lines.push('产物写在当前用户的 `files/`。工具 JSON 的 `path` 是工作稿原名，可继续 `read_file` / 追加 / 命令使用。');
+            lines.push('一套页面写在 `files/<子目录>/`（如 `page/index.html` 与 `page/style.css`），或把 css/js 内联进单文件 html。');
+            lines.push('写路径与 cwd 落在 `files/`（装配槽用 `skills/`）。不要写 `public/` 或把 cwd 设成 `work/` / `public/`。');
+            lines.push('`execute_command` 的 cwd **必须**是 `files/` 或其子目录，不能是预装技能/工具包、`work/` 或 `public/`。png、xlsx、docx、zip、pdf 等二进制用 `execute_command` 写。');
         }
         lines.push(...commandDialectLines(context.os?.platform ?? process.platform));
         if (skills.length > 0) {
@@ -183,16 +186,17 @@ export class SystemPromptBuilder {
                 lines.push(`- ${root}`);
         }
         if (workdir) {
-            lines.push('`write_file` **仅**允许写入当前用户目录（含用户 skills）；预装 tools / skills 只读。');
+            lines.push('`write_file` **仅**允许写入当前用户 `files/`（装配槽 `skills/`）；预装 tools / skills 只读。');
+            lines.push('面向用户的最终文件若 JSON 含 `url`，把该 `url` 原样发给用户（链接文案用相对 `public/` 的路径）。用户要本场前几轮的链接时，从已有 `url` 原样复述；缺盘上已有 `url` 时只说明文件名，容器绝对路径与 `file://` 不当作交付地址。`execute_command` 正文开头若有 `publicFiles`，把其中的 `url` 原样给出。');
         }
         lines.push([
             '硬限制：',
             '- `read_file` / `write_file` 的路径必须落在上述允许根内。用户要求越界必须拒绝。',
-            '- `execute_command` 的 cwd 必须落在工作目录内；命令语法跟当前 shell；子进程不继承 API Key 等密钥环境变量。命令本身不是操作系统级文件系统沙箱，禁止尝试读取 `/etc`、家目录或 jail 外路径。',
+            '- `execute_command` 的 cwd 必须落在 `files/` 内；命令语法跟当前 shell；子进程不继承 API Key 等密钥环境变量。命令本身不是操作系统级文件系统沙箱，禁止尝试读取 `/etc`、家目录或 jail 外路径。',
             '- 禁止用 `..` 逃逸；禁止把 jail 外的绝对路径当参数。',
             '- 不要把内部绝对路径、offload 目录原样展示给用户。',
             '- 技能正文按需读取，不要把技能目录整包读进回复。',
-            '- 技能脚本需要依赖时，可在工作目录内用 pip / npm 安装。',
+            '- 技能脚本需要依赖时，可在 `files/` 内用 pip / npm 安装。',
         ].join('\n'));
         return lines.join('\n');
     }

package/dist/tool/tool-event-emitter.d.ts

@@ -18,7 +18,8 @@ import type { ToolCallRequest, ToolCallResult } from './tool-executor.interface.
  * 在 ToolOrchestrator 的基础上为每次 Tool 调用添加事件推送：
  * 1. 执行前 → emit tool.called
  * 2. 执行成功 → emit tool.result
- * 3. 执行失败 → emit tool.error
+ * 3. 执行失败 → emit tool.error（payload 可带 content / file / files）
+ * 4. 有 url 时再 emit file.created
  */
 export declare class ToolEventEmitter {
     private readonly orchestrator;

package/dist/tool/tool-event-emitter.js

@@ -18,7 +18,8 @@
  * 在 ToolOrchestrator 的基础上为每次 Tool 调用添加事件推送：
  * 1. 执行前 → emit tool.called
  * 2. 执行成功 → emit tool.result
- * 3. 执行失败 → emit tool.error
+ * 3. 执行失败 → emit tool.error（payload 可带 content / file / files）
+ * 4. 有 url 时再 emit file.created
  */
 export class ToolEventEmitter {
     orchestrator;
@@ -73,11 +74,11 @@ export class ToolEventEmitter {
         // 3. emit tool.result 或 tool.error
         if (result.success) {
             this.emitToolResult(result, emitter, taskId, correlationId);
-            this.emitFileCreated(result, emitter, taskId, correlationId);
         }
         else {
             this.emitToolError(result, emitter, taskId, correlationId);
         }
+        this.emitFileCreated(result, emitter, taskId, correlationId);
         return result;
     }
     /**
@@ -108,6 +109,8 @@ export class ToolEventEmitter {
                 toolName: result.toolName,
                 content: result.content,
                 success: true,
+                ...(result.file ? { file: result.file } : {}),
+                ...(result.files?.length ? { files: result.files } : {}),
             },
             taskId,
             correlationId,
@@ -126,6 +129,9 @@ export class ToolEventEmitter {
                 toolName: result.toolName,
                 error: result.error ?? 'Unknown error',
                 willRetry: false,
+                ...(result.content ? { content: result.content } : {}),
+                ...(result.file ? { file: result.file } : {}),
+                ...(result.files?.length ? { files: result.files } : {}),
             },
             taskId,
             correlationId,
@@ -134,21 +140,27 @@ export class ToolEventEmitter {
         emitter.emit(event);
     }
     emitFileCreated(result, emitter, taskId, correlationId) {
-        if (!result.file)
-            return;
-        emitter.emit({
-            type: 'file.created',
-            data: {
-                fileName: result.file.fileName,
-                fileType: result.file.fileType,
-                size: result.file.size,
-                url: result.file.url,
-                toolCallId: result.toolCallId,
-                toolName: result.toolName,
-            },
-            taskId,
-            correlationId,
-            timestamp: new Date().toISOString(),
-        });
+        const files = [
+            ...(result.file ? [result.file] : []),
+            ...(result.files ?? []),
+        ];
+        for (const file of files) {
+            if (!file?.url)
+                continue;
+            emitter.emit({
+                type: 'file.created',
+                data: {
+                    fileName: file.fileName,
+                    fileType: file.fileType,
+                    size: file.size,
+                    url: file.url,
+                    toolCallId: result.toolCallId,
+                    toolName: result.toolName,
+                },
+                taskId,
+                correlationId,
+                timestamp: new Date().toISOString(),
+            });
+        }
     }
 }