hiwork-core 0.0.30 → 0.0.37

package/lib/imagegen.js

@@ -0,0 +1,424 @@
+/**
+ * 生图 Host 服务：调网关中继（`image-config` / `image-generate` / 我的图片）→ 解码 → 写进工作区。
+ *
+ * 形态与 `src/voice-rpc.ts` 同构，两处**刻意的不同**写在这里免得后来的人「对齐」掉：
+ *  1. 本模块是**服务**（有状态：`image-config` 的 ≤5 分钟缓存），RPC 频道（`src/image-rpc.ts`）
+ *     与 Agent 工具（`src/tools.ts`）都建在它上面；
+ *  2. 生图会**落盘**：图片写进 `<工作区>/图片/` 目录后由会话内的卡片经客户端同源文件路由
+ *     （`/api/file?path=…`）显示（设计 §1.3 路径 ①）。写盘用 node `fs` 直写，**不**走
+ *     `ctx.fs`——工具的写盘不是模型可见的文件操作，也不需要沙箱策略参与（设计 §6.2）。
+ *
+ * 三条硬纪律：
+ *  - **凭据/大对象不进日志**：会话 cookie 只出现在 `resolveSession()` 的返回值里，日志只记
+ *    尺寸 / 耗时 / 字节数这类元数据，绝不记 prompt 之外的用户内容、绝不记 base64；
+ *  - **越界校验**：拼出来的路径必须落在工作区根内，否则一律拒绝（`path-outside-workspace`）——
+ *    目录只建 `<工作区>/图片/` 这一层，写盘失败**不回滚**生图（上游已计费）；
+ *  - **不做缓存/去重**：同一 prompt 两次调用 = 两张图（与上游语义一致）。
+ *
+ * 本模块不 import cordis 运行时，只依赖结构化的副作用面（`ImagegenDeps`），便于单测直接伪造。
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { Buffer } from 'node:buffer';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { GatewayError, imageGenerateTimeoutMs, } from "./ai-router-client.js";
+import { DEFAULT_WORKSPACE_DIR } from "./default-workspace.js";
+// ---------------------------------------------------------------------------
+// 冻结契约：尺寸集合 / 体积上限 / 落盘位置
+// ---------------------------------------------------------------------------
+/**
+ * 允许的尺寸三值。**跨仓冻结契约**（与网关 `image.default_size` 的枚举、Agent 工具 schema
+ * 逐项一致）：`defineTool` 在注册期就把 schema 冻死，没法让枚举跟着 `image-config` 走。
+ */
+export const IMAGE_SIZES = ['1024x1024', '1024x1536', '1536x1024'];
+/** 尺寸缺省值（网关 `image-config` 读不到时的兜底）。 */
+export const IMAGE_DEFAULT_SIZE = '1024x1024';
+/** 工作区里存放生成图的目录名（设计 §6.2：`<会话工作区>/图片/`）。 */
+export const IMAGE_DIR_NAME = '图片';
+/**
+ * 单张图上限 20 MiB（与桌面端附件上限同值）。`fetch` 端点超过它直接拒绝——
+ * 绝不把几十 MB 的 base64 塞进 loopback RPC 信封。
+ */
+export const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+/** 本次调用用的工作区根取不到时的兜底（无会话上下文的画廊页 `save` 也用它）。 */
+export const IMAGE_FALLBACK_WORKSPACE = DEFAULT_WORKSPACE_DIR;
+/** `image-config` 的 Host 侧缓存时长（设计 §6.3：≤5 分钟）。 */
+export const IMAGE_CONFIG_CACHE_TTL_MS = 5 * 60_000;
+/** 越出工作区的路径（内部异常，映射成 `path-outside-workspace`）。 */
+export class ImagePathError extends Error {
+    target;
+    constructor(target) {
+        super('图片路径越出了工作区');
+        this.target = target;
+        this.name = 'ImagePathError';
+    }
+}
+// ---------------------------------------------------------------------------
+// 落盘：目录 / slug / 文件名 / 越界校验
+// ---------------------------------------------------------------------------
+/** 工作区里的图片目录。 */
+export function imageDirectory(workspaceRoot) {
+    return join(workspaceRoot, IMAGE_DIR_NAME);
+}
+/**
+ * `target` 是否严格落在 `workspaceRoot` 内（`workspaceRoot` 本身不算）。
+ *
+ * 用 `path.relative` 判定而不是字符串前缀：前缀法会被 `/tmp/ws-other` 这种「同前缀的
+ * 兄弟目录」骗过去。两侧都只做 `resolve`（不做 `realpath`）——拼路径与校验用同一套
+ * 拼法，符号链接的归一化是文件路由那边的事（设计 §1.3 路径 ①）。
+ */
+export function isInsideWorkspace(workspaceRoot, target) {
+    const root = resolve(workspaceRoot);
+    const full = resolve(target);
+    if (full === root)
+        return false;
+    const rel = relative(root, full);
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}
+/**
+ * 拼一张图的落盘绝对路径并做越界校验（**唯一**的拼法，写盘与校验共用它）。
+ * 越界即抛 {@link ImagePathError}。
+ *
+ * **两道都要过**：
+ *  1. 落在工作区根内（设计 §6.2 的前缀校验）；
+ *  2. 落在 `<工作区>/图片/` 内（「只写这个目录」）——`../x.png` 会滑进工作区根，
+ *     虽然没出工作区，但不在约定目录里，同样拒绝。
+ */
+export function imageFilePath(workspaceRoot, fileName) {
+    const directory = imageDirectory(workspaceRoot);
+    const target = join(directory, fileName);
+    if (!isInsideWorkspace(workspaceRoot, target) || !isInsideWorkspace(directory, target)) {
+        throw new ImagePathError(target);
+    }
+    return target;
+}
+/** slug 里不许出现的字符（设计 §6.2）：路径分隔符、Windows 保留符、控制字符与空白。 */
+const SLUG_ILLEGAL = /[\s\u0000-\u001f\u007f/\\:*?"<>|]/gu;
+/** slug 取 prompt 的前 24 个字符（按码点，避免把 emoji 劈成半个代理对）。 */
+const SLUG_MAX_CHARS = 24;
+/**
+ * prompt → 文件名 slug：取前 24 个字符（先 trim，免得名字以 `-` 开头）、非法字符换成 `-`。
+ * 结果为空 / 只剩 `-`（纯标点、纯空白）时用 `image` 兜底。
+ *
+ * 中文与 emoji 是**合法**字符，原样保留（文件系统支持）。
+ */
+export function slugFromPrompt(prompt) {
+    const head = Array.from(prompt.trim()).slice(0, SLUG_MAX_CHARS).join('');
+    const slug = head.replace(SLUG_ILLEGAL, '-');
+    return slug === '' || /^-+$/.test(slug) ? 'image' : slug;
+}
+/** `<yyyyMMdd-HHmmss>`（本地时区，与用户看到的文件时间一致）。 */
+export function imageStamp(when) {
+    const pad = (value) => String(value).padStart(2, '0');
+    return `${when.getFullYear()}${pad(when.getMonth() + 1)}${pad(when.getDate())}`
+        + `-${pad(when.getHours())}${pad(when.getMinutes())}${pad(when.getSeconds())}`;
+}
+/**
+ * 扩展名：**按图片自身的格式**取，未知格式落 `png`。
+ *
+ * 刻意的偏离（设计 §6.2 写的是 `<…>.png`）：客户端同源文件路由按**扩展名**定 MIME
+ * （设计 §1.3），一张 JPEG 存成 `.png` 会被当成 PNG 下发。上游常态是 PNG，
+ * 所以正常路径与文档逐字一致，只有非 PNG 才不同。
+ */
+export function imageExtension(format, mimeType) {
+    const raw = (format.trim() === '' ? mimeType.replace(/^image\//, '') : format).trim().toLowerCase();
+    const normalized = raw === 'jpg' ? 'jpeg' : raw;
+    return /^[a-z0-9]{2,5}$/.test(normalized) && normalized !== 'image' ? normalized : 'png';
+}
+function isAlreadyExists(error) {
+    return typeof error === 'object' && error !== null && error.code === 'EEXIST';
+}
+/**
+ * 写一张图到 `<workspaceRoot>/图片/`：目录只 `mkdir recursive` 一次，同名加 `-2` / `-3` 后缀。
+ *
+ * 用 `flag: 'wx'`（不存在才创建）而不是「先 exists 再写」：两者之间没有 TOCTOU 窗口，
+ * 命名冲突与真正的写盘失败因此能被分开（前者换名字重试，后者如实上报）。
+ *
+ * @returns 写入的**绝对路径**。
+ */
+export async function writeImageBytes(workspaceRoot, baseName, extension, bytes) {
+    await mkdir(imageDirectory(workspaceRoot), { recursive: true });
+    for (let index = 1; index <= 100; index++) {
+        const fileName = index === 1 ? `${baseName}.${extension}` : `${baseName}-${index}.${extension}`;
+        // 越界校验在拼路径里（imageFilePath）：名字来自 slug，正常路径下不可能越界，
+        // 这一层是防线本身而不是装饰。
+        const target = imageFilePath(workspaceRoot, fileName);
+        try {
+            await writeFile(target, bytes, { flag: 'wx' });
+            return target;
+        }
+        catch (error) {
+            if (isAlreadyExists(error))
+                continue;
+            throw error;
+        }
+    }
+    throw new Error('图片同名冲突过多（已尝试 100 个后缀）');
+}
+// ---------------------------------------------------------------------------
+// image-config 读取（带 ≤5 分钟缓存）
+// ---------------------------------------------------------------------------
+/** 直接读网关配置；**永不抛异常**（读不到返回 undefined，调用方落默认值）。 */
+export async function readImageConfig(gateway, sessionCookie, log) {
+    try {
+        return await gateway.getMyImageConfig(sessionCookie);
+    }
+    catch (error) {
+        log?.(`hiwork-core: 生图配置读取失败，回落默认尺寸（${error instanceof Error ? error.name : typeof error}）`);
+        return undefined;
+    }
+}
+/**
+ * 包一层 ≤5 分钟缓存的 `image-config` 读取器（设计 §6.3：工具补默认尺寸时读它）。
+ *
+ * 缓存只存**配置**（开关/模型名/尺寸枚举），不存 cookie、不存任何凭据；同一 Host 进程
+ * 只服务一个登录账号，所以缓存不需要按账号分键。
+ *
+ * 但**要按 `key` 分**：`key` 是调用方给的缓存键（生产传 gateway baseURL）——用户在
+ * 「网关模型」里换了地址之后，旧网关的默认尺寸与模型名不该继续生效 5 分钟。
+ * 只保留最近一个键（换地址是罕见操作，为此维护一张有界 LRU 不值）。
+ */
+export function createCachedImageConfigReader(options = {}) {
+    const ttlMs = options.ttlMs ?? IMAGE_CONFIG_CACHE_TTL_MS;
+    const now = options.now ?? (() => Date.now());
+    let cached;
+    return async (gateway, sessionCookie, log, key = '') => {
+        if (cached !== undefined && cached.key === key && now() - cached.at < ttlMs)
+            return cached.value;
+        const value = await readImageConfig(gateway, sessionCookie, log);
+        if (value === undefined)
+            return undefined;
+        cached = { key, value, at: now() };
+        return value;
+    };
+}
+// ---------------------------------------------------------------------------
+// 生图
+// ---------------------------------------------------------------------------
+/** 通用失败文案（未知 code / message 不可用时的兜底）：不暴露任何网关细节。 */
+export const IMAGE_GENERIC_FAILURE_MESSAGE = '图片生成服务暂时不可用，请稍后重试';
+/** 未登录 / 会话失效的统一文案（用量、语音、生图三条频道同口径）。 */
+export const IMAGE_SESSION_EXPIRED_MESSAGE = '登录状态已过期，请重新登录';
+const IMAGE_GATEWAY_UNCONFIGURED_MESSAGE = '网关地址未配置，请先在「网关模型」里完成登录';
+/**
+ * 各稳定错误码的用户可见文案。
+ *
+ * **唯一的事实源**：`generate` 的失败收敛与 `/hiwork-image` 的消毒（`image-rpc.ts` 从这里
+ * 再导出 {@link displayImageGatewayMessage}）都读它。文案与卡片侧
+ * `src/client/image-cards.tsx` 的 `IMAGE_ERROR_TEXT` **逐字对齐**——卡片按 code 分文案，
+ * 这里只是「网关 message 不可用时的兜底」，两处写着同一句话是有意的：
+ * 卡片不依赖 Host 文案，Host 也不依赖卡片（谁先加载都成立）。
+ */
+export const IMAGE_MESSAGE_FALLBACK = {
+    SESSION_EXPIRED: IMAGE_SESSION_EXPIRED_MESSAGE,
+    GATEWAY_UNREACHABLE: '网关暂时不可用，请稍后重试',
+    IMAGE_BAD_REQUEST: '这个提示词没能生成，换个说法再试',
+    IMAGE_BUDGET_EXCEEDED: '生图暂时不可用：可能是本月额度用尽，也可能是这个模型还没配置好——请联系管理员',
+    IMAGE_TOO_LARGE: '生成的图片太大了，换个小一点的尺寸（如 1024x1024）',
+    IMAGE_DISABLED: '管理员还没开启图片生成',
+    IMAGE_NOT_CONFIGURED: '图片生成还没有配置好，请联系管理员',
+    IMAGE_UPSTREAM_ERROR: IMAGE_GENERIC_FAILURE_MESSAGE,
+    IMAGE_TIMEOUT: '生成超时了，再试一次（复杂画面会比较慢）',
+    IMAGE_NOT_FOUND: '这张图片不存在或已被清理',
+    IMAGE_FORBIDDEN: '这张图片不属于当前账号',
+    IMAGE_WORKSPACE_NOT_FOUND: '这个工作区不存在或已被移除',
+    IMAGE_SAVE_FAILED: '图片已取回但没能保存到工作区',
+    RATE_LIMITED: '请求过于频繁，请稍后再试',
+    AUTH_FAILED: '登录状态异常，请重新登录',
+};
+/**
+ * 网关 message 消毒（与 `voice-rpc.ts` 的 `displayVoiceGatewayMessage` 同实现）：
+ * 含 baseURL / HTTP 状态码 / URL 的原始消息一律换成稳定文案，其余（网关自己写好的
+ * 中文业务文案）原样保留。**code 不受影响**，始终原样透传。
+ *
+ * 放在 `imagegen.ts` 是因为**两条消费路径都要它**（工具的失败收敛 + RPC 的信封），
+ * 而 `image-rpc.ts` 依赖 `imagegen.ts`（反向 import 会成环）。
+ */
+export function displayImageGatewayMessage(code, message) {
+    const text = typeof message === 'string' ? message.trim() : '';
+    if (text === '')
+        return IMAGE_MESSAGE_FALLBACK[code] ?? IMAGE_GENERIC_FAILURE_MESSAGE;
+    const leaksImplementationDetail = /https?:\/\//i.test(text)
+        || /\bHTTP\s*\d{3}\b/i.test(text)
+        || /\bbaseURL\b/i.test(text);
+    if (leaksImplementationDetail)
+        return IMAGE_MESSAGE_FALLBACK[code] ?? IMAGE_GENERIC_FAILURE_MESSAGE;
+    return text;
+}
+function failure(code, message, extra = {}) {
+    return { ok: false, code, message, files: [], ...extra };
+}
+/**
+ * 把网关 `GatewayError` 收敛成失败结果：**code 原样透传**（稳定契约），message 交给
+ * {@link displayImageGatewayMessage} 消毒（含 baseURL / HTTP 细节的换稳定文案）。
+ */
+function gatewayFailure(error, extra = {}) {
+    return failure(error.code, displayImageGatewayMessage(error.code, error.message), extra);
+}
+/** 本次调用的工作区根：request > deps > 默认工作区。 */
+function resolveWorkspaceRoot(deps, request) {
+    const explicit = request.workspaceRoot ?? deps.workspaceRoot;
+    return explicit === undefined || explicit.trim() === '' ? IMAGE_FALLBACK_WORKSPACE : explicit;
+}
+/**
+ * 生图并写盘（设计 §6.2）。
+ *
+ * 顺序：① prompt 校验 → ② 会话 → ③ 网关 → ④ 尺寸缺省时取 `image-config` 的默认值
+ * → ⑤ 调网关（带 timeoutMs 的那一条，见 `ai-router-client.ts`）→ ⑥ 解码写盘 → ⑦ 组装结果。
+ *
+ * 写盘失败**不回滚**：回 `code: 'write-failed'` + 上游信息（prompt/model/size/generationMs），
+ * `files` 置空。越界路径回 `code: 'path-outside-workspace'`。
+ */
+export async function generateImageFile(deps, request) {
+    const prompt = request.prompt.trim();
+    if (prompt === '')
+        return failure('IMAGE_BAD_REQUEST', '生图请求不合法');
+    const sessionCookie = await deps.resolveSession();
+    if (sessionCookie === undefined || sessionCookie === '') {
+        return failure('SESSION_EXPIRED', IMAGE_SESSION_EXPIRED_MESSAGE);
+    }
+    const gateway = deps.gateway();
+    if (gateway === undefined)
+        return failure('GATEWAY_UNREACHABLE', IMAGE_GATEWAY_UNCONFIGURED_MESSAGE);
+    // 配置读一次，两个用途：尺寸缺省值 + 本次调用的等待上限。
+    //
+    // 为什么**无条件**读（原实现只在缺 size 时读）：超时预算也从这里来。配置本身在
+    // Host 侧缓存 ≤5 分钟，多读一次不产生额外往返；读不到只是两处都走兜底。
+    // **quality 一律不下发**（省钱档由网关定）。
+    const config = await (deps.imageConfig ?? ((cookie) => readImageConfig(gateway, cookie, deps.log)))(sessionCookie);
+    let size = request.size;
+    if (size === undefined || size.trim() === '') {
+        size = config?.defaultSize === undefined || config.defaultSize.trim() === '' ? IMAGE_DEFAULT_SIZE : config.defaultSize;
+    }
+    let result;
+    try {
+        result = await gateway.generateImage(sessionCookie, { prompt, size, ...(request.quality === undefined ? {} : { quality: request.quality }) }, undefined, imageGenerateTimeoutMs(config?.timeoutSeconds));
+    }
+    catch (error) {
+        if (error instanceof GatewayError)
+            return gatewayFailure(error, { prompt });
+        deps.log?.(`hiwork-core: 生图失败（${error instanceof Error ? error.name : typeof error}）`);
+        return failure('IMAGE_UPSTREAM_ERROR', IMAGE_GENERIC_FAILURE_MESSAGE, { prompt });
+    }
+    const image = result.images[0];
+    if (image === undefined || image.dataBase64 === '') {
+        // 网关契约违约（恒回 1 张）：不静默回成功，否则卡片会渲染一张空图。
+        deps.log?.('hiwork-core: 生图响应里没有图片数据');
+        return failure('IMAGE_UPSTREAM_ERROR', IMAGE_GENERIC_FAILURE_MESSAGE, {
+            prompt, model: result.model, size: result.size, generationMs: result.generationMs,
+        });
+    }
+    const upstream = {
+        prompt,
+        model: result.model,
+        size: result.size,
+        generationMs: result.generationMs,
+    };
+    let bytes;
+    try {
+        bytes = Buffer.from(image.dataBase64, 'base64');
+    }
+    catch {
+        return failure('IMAGE_UPSTREAM_ERROR', IMAGE_GENERIC_FAILURE_MESSAGE, upstream);
+    }
+    if (bytes.byteLength === 0)
+        return failure('IMAGE_UPSTREAM_ERROR', IMAGE_GENERIC_FAILURE_MESSAGE, upstream);
+    if (bytes.byteLength > MAX_IMAGE_BYTES)
+        return failure('IMAGE_TOO_LARGE', '生成的图片太大了', upstream);
+    const byteSize = image.byteSize > 0 ? image.byteSize : bytes.byteLength;
+    const when = (deps.now ?? (() => new Date()))();
+    const slug = slugFromPrompt(prompt);
+    let path;
+    try {
+        path = await writeImageBytes(resolveWorkspaceRoot(deps, request), `${imageStamp(when)}-${slug}`, imageExtension(image.format, image.mimeType), bytes);
+    }
+    catch (error) {
+        if (error instanceof ImagePathError) {
+            deps.log?.('hiwork-core: 生图落盘路径越出工作区，已拒绝');
+            return failure('path-outside-workspace', '图片路径越出了工作区', upstream);
+        }
+        deps.log?.(`hiwork-core: 生图写盘失败（${error instanceof Error ? error.name : typeof error}）`);
+        return failure('write-failed', '图片已生成但没能保存到工作区', upstream);
+    }
+    return {
+        ok: true,
+        files: [{
+                path,
+                mimeType: image.mimeType,
+                byteSize,
+                ...(image.revisedPrompt === undefined ? {} : { revisedPrompt: image.revisedPrompt }),
+            }],
+        prompt,
+        model: result.model,
+        size: result.size,
+        generationMs: result.generationMs,
+    };
+}
+// ---------------------------------------------------------------------------
+// 我的图片：列表 / 单张 / 存到工作区（画廊页三端点）
+// ---------------------------------------------------------------------------
+/**
+ * 画廊页 `save`（设计 §6.5）：取本体 → 按生图同一套规则落盘 → 回绝对路径。
+ *
+ * 落点是**默认工作区** `~/HiWork/Default`（画廊页是中央页，没有会话上下文）；给了
+ * `workspaceId` 就用注册表里那个工作区的路径，**取不到即拒绝**（绝不落到别处）。
+ *
+ * 文件名沿用 §6.2 的规则，slug 来自该记录的 `prompt`。记录本体在网关，而冻结入参只有
+ * `{ id, workspaceId? }`（页面按契约只传 id），所以这里**尽力**回查一次列表拿 prompt：
+ * 查不到、或第一页里没有这条记录，就用 `image` 兜底——**不为一个文件名把保存变成硬依赖**。
+ *
+ * 失败分两类：网关/会话错误**抛** `GatewayError`（由 RPC 层映射成稳定 code）；
+ * 工作区解析 / 写盘这类业务失败回 `{ok:false, code, reason}`。
+ */
+export async function saveImageToWorkspace(deps, request) {
+    const sessionCookie = await deps.resolveSession();
+    if (sessionCookie === undefined || sessionCookie === '') {
+        throw new GatewayError('SESSION_EXPIRED', IMAGE_SESSION_EXPIRED_MESSAGE, 401);
+    }
+    const gateway = deps.gateway();
+    if (gateway === undefined)
+        throw new GatewayError('GATEWAY_UNREACHABLE', IMAGE_GATEWAY_UNCONFIGURED_MESSAGE);
+    let root = IMAGE_FALLBACK_WORKSPACE;
+    if (request.workspaceId !== undefined && request.workspaceId.trim() !== '') {
+        const resolved = deps.workspaces?.resolveWorkspacePath(request.workspaceId);
+        if (resolved === undefined) {
+            return { ok: false, code: 'IMAGE_WORKSPACE_NOT_FOUND', reason: '这个工作区不存在或已被移除' };
+        }
+        root = resolved;
+    }
+    const file = await gateway.fetchMyImage(sessionCookie, request.id);
+    const bytes = Buffer.from(file.dataBase64, 'base64');
+    if (bytes.byteLength === 0) {
+        return { ok: false, code: 'IMAGE_SAVE_FAILED', reason: '这张图片的内容是空的，请稍后重试' };
+    }
+    const prompt = request.prompt ?? await lookupPrompt(gateway, sessionCookie, request.id, deps.log);
+    const when = (deps.now ?? (() => new Date()))();
+    const slug = slugFromPrompt(prompt);
+    try {
+        const path = await writeImageBytes(root, `${imageStamp(when)}-${slug}`, imageExtension('', file.mimeType), bytes);
+        return { ok: true, path };
+    }
+    catch (error) {
+        if (error instanceof ImagePathError) {
+            return { ok: false, code: 'IMAGE_SAVE_FAILED', reason: '这个位置超出工作区范围，已拒绝保存' };
+        }
+        deps.log?.(`hiwork-core: 图片保存失败（${error instanceof Error ? error.name : typeof error}）`);
+        return { ok: false, code: 'IMAGE_SAVE_FAILED', reason: '图片已取回但没能保存到工作区' };
+    }
+}
+/**
+ * 回查一条记录的 prompt（只为文件名 slug）。**永不抛异常**：查不到返回空串
+ * （`slugFromPrompt('')` → `image`）。
+ *
+ * 只查第一页：`fetch` 的 id 通常就是用户刚在列表里点的那张，命中率足够；
+ * 为了一个文件名去做「遍历所有页」的调用显然不值。
+ */
+async function lookupPrompt(gateway, sessionCookie, id, log) {
+    try {
+        const view = await gateway.getMyImages(sessionCookie, { page: 1, pageSize: 100 });
+        return view.items.find((item) => item.id === id)?.prompt ?? '';
+    }
+    catch (error) {
+        log?.(`hiwork-core: 保存前回查提示词失败，文件名用 image 兜底（${error instanceof Error ? error.name : typeof error}）`);
+        return '';
+    }
+}