@xgjktech/xg_cwork_im 1.19.21 → 1.19.23

package/dist/src/workspace/resource-file.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 资源中心整文件上传 + OpenClaw deliver 媒体 URL 拉取
+ *
+ * 上传地址固定为 `baseUrl + /file/upDownload/uploadWholeFile`，与 IM 同域，使用与发消息相同的 access-token。
+ */
+import type { Log } from "../plugin/auth.js";
+/** 沙箱/项目常见根段：`/project/...`、`/xg-cwork-im/...` 等伪绝对路径会按 workspace 相对段解析 */
+export declare const WORKSPACE_MEDIA_ROOT_SEGMENTS: Set<string>;
+/** IM 整文件上传超时（毫秒）；超时后抛错，由 send-service 降级为纯文本并提示用户。 */
+export declare const IM_FILE_UPLOAD_TIMEOUT_MS = 60000;
+/** HTTP(S) 媒体下载超时（毫秒）；超时后入站保留原始 URL 交给 OpenClaw，出站降级为带链接的文本。 */
+export declare const IM_FILE_DOWNLOAD_TIMEOUT_MS = 90000;
+/** 整文件上传接口路径（拼在 channels.xg_cwork_im.baseUrl 上） */
+export declare const RESOURCE_UPLOAD_PATH = "/file/upDownload/uploadWholeFile";
+export declare function resolveResourceUploadUrl(baseUrl: string): string;
+/** 从上传接口 JSON 中解析 fileId（兼容常见嵌套 data） */
+export declare function extractFileIdFromUploadResponse(data: unknown): string | undefined;
+export declare function formatFromFilename(filename: string): string;
+/** 仅当含 %XX 序列时 decodeURIComponent，避免对已解码的 Unicode 再 decode 抛错 */
+export declare function safeDecodeUriFilenameSegment(segment: string): string;
+/**
+ * 从 HTTP Content-Disposition 解析文件名（优先 RFC 5987 `filename*=` UTF-8，再普通 filename=）。
+ */
+export declare function parseFilenameFromContentDisposition(header: string | undefined): string | undefined;
+export declare function displayNameFromUrl(url: string): string;
+/** 日志用：截断过长路径/URL */
+export declare function summarizeMediaRef(ref: string, maxLen?: number): string;
+/**
+ * 将字符串解析为可交给 readFile 的本机路径（兼容 Windows / macOS / Linux）。
+ * - 使用当前进程的 path.isAbsolute（各 OS 语义正确）。
+ * - Windows：Git Bash / MSYS 的 `/c/Users/...`、Cygwin `/cygdrive/c/...`。
+ * - 非 Windows：若传入 `D:\...` 形式仍做一次规范化（多用于日志/失败提示，读文件通常会失败）。
+ */
+export declare function resolveLocalFsPath(ref: string): {
+    fsPath: string;
+    via: string;
+} | null;
+/**
+ * 将 Agent 常写的 workspace 相对媒体引用规范为「相对 workspace 根」的段（不含 `/workspace/` 前缀）。
+ *
+ * 支持：`project/...`、`./xg-cwork-im/...`、`/project/...`（沙箱内伪绝对，非本机根目录）。
+ * 不处理：`/workspace/...`（另见 resolveWorkspaceCandidatePaths）、`file://`、`http(s)://`、本机真实绝对路径。
+ */
+export declare function parseWorkspaceRelativeMediaRef(raw: string): string | null;
+/**
+ * 将 workspace 相对段解析为宿主机候选绝对路径（优先 agentWorkspaceDir，其次 cwd、容器 `/workspace`）。
+ */
+export declare function resolveWorkspaceRelativeCandidatePaths(rel: string, agentWorkspaceDir?: string): string[];
+/**
+ * 将 OpenClaw 约定的 `/workspace/<rel>` 路径解析为本机绝对路径列表（通常 1 条）。
+ *
+ * **已能定位 agent 时（传入非空的 agentWorkspaceDir）**：
+ * 只返回该 agent 在宿主机上的 workspace 根目录拼出的唯一路径，不再尝试 `cwd` 或字面量 `/workspace`，
+ * 避免多个 agent 存在相同相对路径（如都叫 `output/report.pdf`）时误读他人文件。
+ *
+ * **无法解析出 agentWorkspaceDir 时**（例如 SDK 解析失败、或未传入）：
+ * 退化为依次尝试 `process.cwd()` 与 `/workspace`（容器挂载），由调用方 readFile 试错；
+ * 此模式下存在跨会话路径混淆的理论风险，应尽量保证上游传入 agentWorkspaceDir。
+ *
+ * 返回空数组表示路径不符合 /workspace/ 格式。
+ */
+export declare function resolveWorkspaceCandidatePaths(raw: string, agentWorkspaceDir?: string): string[];
+/**
+ * @deprecated 使用 resolveWorkspaceCandidatePaths 替代（支持多沙箱 agent）。
+ * 保留此函数避免外部直接引用时编译报错，内部逻辑已切换到多候选方式。
+ */
+export declare function resolveWorkspacePrefixPath(raw: string): string | null;
+export declare function downloadMediaBuffer(url: string, maxBytes: number, log?: Log, 
+/** Agent workspace 宿主机路径（由 resolveAgentWorkspaceDir 得到），用于多沙箱场景下准确解析 /workspace/ 路径 */
+agentWorkspaceDir?: string, timeoutMs?: number): Promise<{
+    buffer: Buffer;
+    filename: string;
+}>;
+/**
+ * multipart 上传整文件，返回 fileId 与字节数。
+ */
+export declare function uploadWholeResourceFile(args: {
+    fileUploadUrl: string;
+    token: string;
+    buffer: Buffer;
+    filename: string;
+    formField: string;
+    log?: Log;
+    /** 默认 {@link IM_FILE_UPLOAD_TIMEOUT_MS}（60s） */
+    timeoutMs?: number;
+}): Promise<{
+    fileId: string;
+    size: number;
+}>;
+export declare function resolveMaxAttachmentBytes(config: {
+    maxAttachmentBytes?: number;
+}): number;
+/**
+ * 资源整文件上传错误：携带 HTTP 状态与是否可重试标记。
+ *
+ * 判定规则（与 send-service 的消息重试对齐）：
+ * - 网络错误 / 超时 / 408 / 429 / 5xx → 可重试
+ * - 其它 4xx / 业务 resultCode 错误 / 缺少 fileId → 永久失败，不重试
+ */
+export declare class ResourceUploadError extends Error {
+    readonly status?: number;
+    readonly retryable: boolean;
+    constructor(message: string, opts: {
+        status?: number;
+        retryable: boolean;
+    });
+}
+/**
+ * 带重试的整文件上传：默认最多 3 次（首次 + 2 次重试），间隔 1s、3s。
+ * 仅对 {@link ResourceUploadError.retryable} 为真的错误重试；业务错误、非可重试 4xx、缺少 fileId 立即抛出。
+ */
+export declare function uploadWholeResourceFileWithRetry(args: Parameters<typeof uploadWholeResourceFile>[0], retry?: {
+    maxAttempts?: number;
+    delaysMs?: number[];
+}): Promise<{
+    fileId: string;
+    size: number;
+}>;
+//# sourceMappingURL=resource-file.d.ts.map

package/dist/src/workspace/resource-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-file.d.ts","sourceRoot":"","sources":["../../../src/workspace/resource-file.ts"],"names":[],"mappings":"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"}

package/dist/src/workspace/resource-file.js

@@ -0,0 +1,533 @@
+/**
+ * 资源中心整文件上传 + OpenClaw deliver 媒体 URL 拉取
+ *
+ * 上传地址固定为 `baseUrl + /file/upDownload/uploadWholeFile`，与 IM 同域，使用与发消息相同的 access-token。
+ */
+import axios from "axios";
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { normalizeWorkspaceRelativeSegment } from "./project-path-normalize.js";
+/** 沙箱/项目常见根段：`/project/...`、`/xg-cwork-im/...` 等伪绝对路径会按 workspace 相对段解析 */
+export const WORKSPACE_MEDIA_ROOT_SEGMENTS = new Set(["project", "xg-cwork-im", "xg_im_inbound"]);
+/** 容器内常见的 workspace 挂载点（无 agentWorkspaceDir 时的兜底） */
+const CONTAINER_WORKSPACE_MOUNT = "/workspace";
+const DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
+/** IM 整文件上传超时（毫秒）；超时后抛错，由 send-service 降级为纯文本并提示用户。 */
+export const IM_FILE_UPLOAD_TIMEOUT_MS = 60_000;
+/** HTTP(S) 媒体下载超时（毫秒）；超时后入站保留原始 URL 交给 OpenClaw，出站降级为带链接的文本。 */
+export const IM_FILE_DOWNLOAD_TIMEOUT_MS = 90_000;
+/** 整文件上传接口路径（拼在 channels.xg_cwork_im.baseUrl 上） */
+export const RESOURCE_UPLOAD_PATH = "/file/upDownload/uploadWholeFile";
+export function resolveResourceUploadUrl(baseUrl) {
+    const b = baseUrl.trim();
+    if (!b)
+        throw new Error("[cwork_im] baseUrl is required for resource upload");
+    return new URL(RESOURCE_UPLOAD_PATH, b.endsWith("/") ? b : `${b}/`).href;
+}
+/** 从上传接口 JSON 中解析 fileId（兼容常见嵌套 data） */
+export function extractFileIdFromUploadResponse(data) {
+    if (data == null)
+        return undefined;
+    if (typeof data === "string" && data.trim().length > 0)
+        return data.trim();
+    if (typeof data !== "object")
+        return undefined;
+    const o = data;
+    for (const key of ["fileId", "id", "resourceId", "file_id"]) {
+        const v = o[key];
+        if (typeof v === "string" && v.length > 0)
+            return v;
+    }
+    if (o.data != null) {
+        const nested = extractFileIdFromUploadResponse(o.data);
+        if (nested)
+            return nested;
+    }
+    return undefined;
+}
+export function formatFromFilename(filename) {
+    const ext = path.extname(filename).replace(/^\./, "").toLowerCase();
+    if (ext && ext.length <= 16 && /^[a-z0-9]+$/i.test(ext))
+        return ext;
+    return "bin";
+}
+/** 仅当含 %XX 序列时 decodeURIComponent，避免对已解码的 Unicode 再 decode 抛错 */
+export function safeDecodeUriFilenameSegment(segment) {
+    const s = segment.trim();
+    if (!s)
+        return s;
+    if (!/%[0-9A-Fa-f]{2}/.test(s))
+        return s;
+    try {
+        return decodeURIComponent(s.replace(/\+/g, " "));
+    }
+    catch {
+        return s;
+    }
+}
+/**
+ * 从 HTTP Content-Disposition 解析文件名（优先 RFC 5987 `filename*=` UTF-8，再普通 filename=）。
+ */
+export function parseFilenameFromContentDisposition(header) {
+    if (header == null || typeof header !== "string")
+        return undefined;
+    const h = header.trim();
+    if (!h)
+        return undefined;
+    const star = /filename\*\s*=\s*(?:UTF-8|utf-8)''([^;\r\n]+)/i.exec(h);
+    if (star?.[1]) {
+        const v = star[1].trim();
+        const decoded = safeDecodeUriFilenameSegment(v);
+        if (decoded)
+            return decoded;
+    }
+    const quoted = /filename\s*=\s*"((?:[^"\\]|\\.)*)"/i.exec(h);
+    if (quoted?.[1]) {
+        const inner = quoted[1].replace(/\\(.)/g, "$1").trim();
+        if (inner)
+            return safeDecodeUriFilenameSegment(inner);
+    }
+    const unquoted = /filename\s*=\s*([^;\r\n]+)/i.exec(h);
+    if (unquoted?.[1]) {
+        let v = unquoted[1].trim().replace(/^["']|["']$/g, "");
+        if (v.toLowerCase().startsWith("utf-8''"))
+            v = v.slice(7);
+        if (v)
+            return safeDecodeUriFilenameSegment(v);
+    }
+    return undefined;
+}
+export function displayNameFromUrl(url) {
+    try {
+        if (url.startsWith("file://")) {
+            return path.basename(fileURLToPath(url)) || "file";
+        }
+        const u = new URL(url);
+        const qName = u.searchParams.get("filename") ?? u.searchParams.get("name");
+        if (qName?.trim()) {
+            return safeDecodeUriFilenameSegment(qName.trim()) || "attachment";
+        }
+        const pathname = u.pathname || "/";
+        const last = pathname.split("/").filter(Boolean).pop() ?? "";
+        const base = safeDecodeUriFilenameSegment(last.split("?")[0] || "");
+        return base || "attachment";
+    }
+    catch {
+        return "attachment";
+    }
+}
+/** 日志用：截断过长路径/URL */
+export function summarizeMediaRef(ref, maxLen = 160) {
+    const t = ref.trim().replace(/\s+/g, " ");
+    if (t.length <= maxLen)
+        return t;
+    return `${t.slice(0, maxLen)}…(len=${t.length})`;
+}
+function isHttpOrHttps(ref) {
+    try {
+        const u = new URL(ref.trim());
+        return u.protocol === "http:" || u.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 将字符串解析为可交给 readFile 的本机路径（兼容 Windows / macOS / Linux）。
+ * - 使用当前进程的 path.isAbsolute（各 OS 语义正确）。
+ * - Windows：Git Bash / MSYS 的 `/c/Users/...`、Cygwin `/cygdrive/c/...`。
+ * - 非 Windows：若传入 `D:\...` 形式仍做一次规范化（多用于日志/失败提示，读文件通常会失败）。
+ */
+export function resolveLocalFsPath(ref) {
+    const raw = ref.trim();
+    if (!raw)
+        return null;
+    if (process.platform === "win32") {
+        // MSYS/Git Bash: /c/Users/foo → C:\Users\foo（要求 /<盘符>/ 后仍有路径，避免误伤 /Users）
+        const msys = /^\/([a-zA-Z])\/(.+)$/.exec(raw.replace(/\\/g, "/"));
+        if (msys) {
+            const letter = msys[1].toUpperCase();
+            const rest = msys[2].split("/").join(path.win32.sep);
+            const fsPath = path.win32.normalize(`${letter}:${path.win32.sep}${rest}`);
+            return { fsPath, via: "git-bash-msys" };
+        }
+        const cyg = /^\/cygdrive\/([a-zA-Z])\/(.+)$/i.exec(raw.replace(/\\/g, "/"));
+        if (cyg) {
+            const letter = cyg[1].toUpperCase();
+            const rest = cyg[2].split("/").join(path.win32.sep);
+            const fsPath = path.win32.normalize(`${letter}:${path.win32.sep}${rest}`);
+            return { fsPath, via: "cygwin" };
+        }
+    }
+    if (path.isAbsolute(raw)) {
+        return { fsPath: path.normalize(raw), via: `native-${process.platform}` };
+    }
+    // Linux/macOS 上 WSL 互操作常见：/mnt/c/... 已是 posix 绝对路径，上面已命中
+    if (process.platform !== "win32" && /^[a-zA-Z]:[/\\]/.test(raw)) {
+        return { fsPath: path.win32.normalize(raw), via: "win-style-path" };
+    }
+    return null;
+}
+async function readLocalFsIntoBuffer(fsPath, maxBytes, log) {
+    const st = await stat(fsPath);
+    if (st.size > maxBytes) {
+        throw new Error(`local file size ${st.size} exceeds maxAttachmentBytes=${maxBytes}`);
+    }
+    const buffer = await readFile(fsPath);
+    const filename = path.basename(fsPath) || "file";
+    log?.info(`[cwork_im:media] local ok bytes=${buffer.length} name=${filename}`);
+    return { buffer, filename };
+}
+function formatHttpDownloadError(err, timeoutMs) {
+    if (axios.isAxiosError(err)) {
+        if (err.code === "ECONNABORTED" || err.message.toLowerCase().includes("timeout")) {
+            return `文件下载超时（${Math.round(timeoutMs / 1000)}秒）`;
+        }
+        const parts = [err.message];
+        if (err.code)
+            parts.push(`axiosCode=${err.code}`);
+        if (err.response?.status != null)
+            parts.push(`httpStatus=${err.response.status}`);
+        return parts.join(" ");
+    }
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+function resolveUnderWorkspaceRoot(workspaceRoot, rel) {
+    const rootResolved = path.resolve(workspaceRoot);
+    const candidate = rel ? path.resolve(rootResolved, rel) : rootResolved;
+    const relToRoot = path.relative(rootResolved, candidate);
+    if (relToRoot.startsWith("..") || path.isAbsolute(relToRoot)) {
+        throw new Error(`[cwork_im:media] /workspace/ path escapes workspace root (${summarizeMediaRef(workspaceRoot)}): ${summarizeMediaRef(rel)}`);
+    }
+    return candidate;
+}
+function isNativeHostAbsoluteRef(ref) {
+    const t = ref.trim();
+    if (!t)
+        return false;
+    if (/^[a-zA-Z]:[/\\]/.test(t) || t.startsWith("\\\\"))
+        return true;
+    if (path.isAbsolute(t)) {
+        const posix = t.replace(/\\/g, "/");
+        const withoutLeading = posix.replace(/^\/+/, "");
+        const firstSeg = withoutLeading.split("/").filter(Boolean)[0] ?? "";
+        if (WORKSPACE_MEDIA_ROOT_SEGMENTS.has(firstSeg))
+            return false;
+        return true;
+    }
+    return false;
+}
+/**
+ * 将 Agent 常写的 workspace 相对媒体引用规范为「相对 workspace 根」的段（不含 `/workspace/` 前缀）。
+ *
+ * 支持：`project/...`、`./xg-cwork-im/...`、`/project/...`（沙箱内伪绝对，非本机根目录）。
+ * 不处理：`/workspace/...`（另见 resolveWorkspaceCandidatePaths）、`file://`、`http(s)://`、本机真实绝对路径。
+ */
+export function parseWorkspaceRelativeMediaRef(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed || isHttpOrHttps(trimmed) || trimmed.startsWith("file://"))
+        return null;
+    if (trimmed.startsWith("/workspace/") || trimmed === "/workspace")
+        return null;
+    if (/^[a-zA-Z]:[/\\]/.test(trimmed) || trimmed.startsWith("\\\\"))
+        return null;
+    let normalized;
+    try {
+        normalized = normalizeWorkspaceRelativeSegment(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (isNativeHostAbsoluteRef(trimmed)) {
+        const firstSeg = normalized.split("/").filter(Boolean)[0] ?? "";
+        return WORKSPACE_MEDIA_ROOT_SEGMENTS.has(firstSeg) ? normalized : null;
+    }
+    return normalized;
+}
+/**
+ * 将 workspace 相对段解析为宿主机候选绝对路径（优先 agentWorkspaceDir，其次 cwd、容器 `/workspace`）。
+ */
+export function resolveWorkspaceRelativeCandidatePaths(rel, agentWorkspaceDir) {
+    const trimmed = agentWorkspaceDir?.trim();
+    const bases = [];
+    if (trimmed) {
+        bases.push(trimmed);
+    }
+    else {
+        bases.push(process.cwd());
+        if (!bases.includes(CONTAINER_WORKSPACE_MOUNT)) {
+            bases.push(CONTAINER_WORKSPACE_MOUNT);
+        }
+    }
+    const seen = new Set();
+    const out = [];
+    for (const base of bases) {
+        const candidate = resolveUnderWorkspaceRoot(base, rel);
+        const key = path.normalize(candidate);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(candidate);
+    }
+    return out;
+}
+async function tryReadLocalCandidates(candidates, label, maxBytes, log) {
+    if (candidates.length === 0) {
+        throw new Error(`[cwork_im:media] ${label}: no candidates`);
+    }
+    log?.info(`[cwork_im:media] ${label} candidates(${candidates.length}): ${candidates.map((p) => summarizeMediaRef(p)).join(" | ")}`);
+    let lastErr;
+    for (const fsPath of candidates) {
+        try {
+            const result = await readLocalFsIntoBuffer(fsPath, maxBytes, log);
+            log?.info(`[cwork_im:media] ${label} resolved via ${summarizeMediaRef(fsPath)}`);
+            return result;
+        }
+        catch (err) {
+            lastErr = err;
+            log?.info(`[cwork_im:media] ${label} miss ${summarizeMediaRef(fsPath)}: ${String(err)}`);
+        }
+    }
+    log?.error(`[cwork_im:media] ${label} all ${candidates.length} candidates failed`);
+    throw lastErr;
+}
+/**
+ * 将 OpenClaw 约定的 `/workspace/<rel>` 路径解析为本机绝对路径列表（通常 1 条）。
+ *
+ * **已能定位 agent 时（传入非空的 agentWorkspaceDir）**：
+ * 只返回该 agent 在宿主机上的 workspace 根目录拼出的唯一路径，不再尝试 `cwd` 或字面量 `/workspace`，
+ * 避免多个 agent 存在相同相对路径（如都叫 `output/report.pdf`）时误读他人文件。
+ *
+ * **无法解析出 agentWorkspaceDir 时**（例如 SDK 解析失败、或未传入）：
+ * 退化为依次尝试 `process.cwd()` 与 `/workspace`（容器挂载），由调用方 readFile 试错；
+ * 此模式下存在跨会话路径混淆的理论风险，应尽量保证上游传入 agentWorkspaceDir。
+ *
+ * 返回空数组表示路径不符合 /workspace/ 格式。
+ */
+export function resolveWorkspaceCandidatePaths(raw, agentWorkspaceDir) {
+    if (!raw.startsWith("/workspace/") && raw !== "/workspace")
+        return [];
+    const rel = raw.startsWith("/workspace/") ? raw.slice("/workspace/".length) : "";
+    const trimmed = agentWorkspaceDir?.trim();
+    if (trimmed) {
+        return [resolveUnderWorkspaceRoot(trimmed, rel)];
+    }
+    const bases = [];
+    const cwd = process.cwd();
+    bases.push(cwd);
+    if (!bases.includes("/workspace"))
+        bases.push("/workspace");
+    return bases.map((base) => resolveUnderWorkspaceRoot(base, rel));
+}
+/**
+ * @deprecated 使用 resolveWorkspaceCandidatePaths 替代（支持多沙箱 agent）。
+ * 保留此函数避免外部直接引用时编译报错，内部逻辑已切换到多候选方式。
+ */
+export function resolveWorkspacePrefixPath(raw) {
+    const candidates = resolveWorkspaceCandidatePaths(raw);
+    return candidates[0] ?? null;
+}
+export async function downloadMediaBuffer(url, maxBytes, log, 
+/** Agent workspace 宿主机路径（由 resolveAgentWorkspaceDir 得到），用于多沙箱场景下准确解析 /workspace/ 路径 */
+agentWorkspaceDir, timeoutMs = IM_FILE_DOWNLOAD_TIMEOUT_MS) {
+    const raw = url.trim();
+    log?.info(`[cwork_im:media] resolve ref=${summarizeMediaRef(raw)}`);
+    // Handle OpenClaw /workspace/ convention: try multiple host-side candidates.
+    const workspaceCandidates = resolveWorkspaceCandidatePaths(raw, agentWorkspaceDir);
+    if (workspaceCandidates.length > 0) {
+        return tryReadLocalCandidates(workspaceCandidates, "/workspace/", maxBytes, log);
+    }
+    const wsRel = parseWorkspaceRelativeMediaRef(raw);
+    if (wsRel) {
+        if (!agentWorkspaceDir?.trim()) {
+            log?.warn?.(`[cwork_im:media] workspace-relative ref without agentWorkspaceDir; ` +
+                `trying cwd and ${CONTAINER_WORKSPACE_MOUNT} fallbacks ref=${summarizeMediaRef(raw)}`);
+        }
+        const relCandidates = resolveWorkspaceRelativeCandidatePaths(wsRel, agentWorkspaceDir);
+        return tryReadLocalCandidates(relCandidates, "workspace-relative", maxBytes, log);
+    }
+    if (raw.startsWith("file://")) {
+        let fsPath;
+        try {
+            fsPath = fileURLToPath(raw);
+        }
+        catch (e) {
+            log?.error(`[cwork_im:media] invalid file:// URL: ${summarizeMediaRef(raw)} ${String(e)}`);
+            throw e;
+        }
+        log?.info(`[cwork_im:media] read file:// -> ${summarizeMediaRef(fsPath)}`);
+        try {
+            return await readLocalFsIntoBuffer(fsPath, maxBytes, log);
+        }
+        catch (err) {
+            log?.error(`[cwork_im:media] readFile failed file:// ${summarizeMediaRef(fsPath)}: ${String(err)}`);
+            throw err;
+        }
+    }
+    if (isHttpOrHttps(raw)) {
+        log?.info(`[cwork_im:media] GET ${summarizeMediaRef(raw)} timeoutMs=${timeoutMs}`);
+        try {
+            const res = await axios.get(raw, {
+                responseType: "arraybuffer",
+                timeout: timeoutMs,
+                maxContentLength: maxBytes,
+                maxBodyLength: maxBytes,
+                validateStatus: (s) => s >= 200 && s < 300,
+            });
+            const buffer = Buffer.from(res.data);
+            let filename = displayNameFromUrl(raw);
+            const cdRaw = res.headers["content-disposition"];
+            const cd = Array.isArray(cdRaw) ? cdRaw[0] : cdRaw;
+            if (typeof cd === "string") {
+                const fromCd = parseFilenameFromContentDisposition(cd);
+                if (fromCd)
+                    filename = fromCd;
+            }
+            log?.info(`[cwork_im:media] http ok bytes=${buffer.length} name=${filename}`);
+            return { buffer, filename };
+        }
+        catch (err) {
+            const detail = formatHttpDownloadError(err, timeoutMs);
+            log?.error(`[cwork_im:media] http failed ref=${summarizeMediaRef(raw)}: ${detail}`);
+            throw new Error(detail);
+        }
+    }
+    const resolved = resolveLocalFsPath(raw);
+    if (resolved) {
+        log?.info(`[cwork_im:media] local via=${resolved.via} -> ${summarizeMediaRef(resolved.fsPath)}`);
+        try {
+            return await readLocalFsIntoBuffer(resolved.fsPath, maxBytes, log);
+        }
+        catch (err) {
+            log?.error(`[cwork_im:media] readFile failed ${summarizeMediaRef(resolved.fsPath)}: ${String(err)}`);
+            throw err;
+        }
+    }
+    const hint = "请使用 http(s)、file://（三系统通用），或本机绝对路径：Windows C:\\\\... / UNC；macOS/Linux /Users、/home、/mnt/c/...（WSL）；Windows 下 Git Bash 可用 /c/...";
+    log?.error(`[cwork_im:media] unsupported ref=${summarizeMediaRef(raw)} (${hint})`);
+    throw new Error(`[cwork_im] 无法读取媒体（${hint}）: ${summarizeMediaRef(raw)}`);
+}
+/**
+ * multipart 上传整文件，返回 fileId 与字节数。
+ */
+export async function uploadWholeResourceFile(args) {
+    const { fileUploadUrl, token, buffer, filename, formField, log } = args;
+    const timeoutMs = args.timeoutMs ?? IM_FILE_UPLOAD_TIMEOUT_MS;
+    const form = new FormData();
+    // multipart 第三参携带 UTF-8 文件名（与 Web File 等价；避免 TS 下 File 与 FormData Blob  overload 不匹配）
+    const blob = new Blob([new Uint8Array(buffer)], { type: "application/octet-stream" });
+    form.append(formField, blob, filename);
+    log?.info(`[cwork_im:upload] POST ${fileUploadUrl} field=${formField} name=${filename} bytes=${buffer.length} timeoutMs=${timeoutMs}`);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    let res;
+    try {
+        res = await fetch(fileUploadUrl, {
+            method: "POST",
+            headers: {
+                "access-token": token,
+            },
+            body: form,
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+            const msg = `文件上传超时（${Math.round(timeoutMs / 1000)}秒），请稍后重试或缩小文件`;
+            log?.error(`[cwork_im:upload] ${msg} name=${filename} bytes=${buffer.length}`);
+            throw new ResourceUploadError(msg, { retryable: true });
+        }
+        // fetch 抛错通常是网络层瞬时问题（DNS/连接/断流）→ 可重试
+        throw new ResourceUploadError(err instanceof Error ? err.message : String(err), { retryable: true });
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+    const rawText = await res.text();
+    let json;
+    try {
+        json = rawText ? JSON.parse(rawText) : undefined;
+    }
+    catch {
+        json = undefined;
+    }
+    if (!res.ok) {
+        log?.error(`[cwork_im:upload] HTTP ${res.status} body=${rawText.slice(0, 500)}`);
+        throw new ResourceUploadError(`upload HTTP ${res.status}: ${rawText.slice(0, 500)}`, {
+            status: res.status,
+            retryable: isRetryableHttpStatus(res.status),
+        });
+    }
+    // Unified IM API response: { data, resultCode: 1, resultMsg: "" } — resultCode=1 means success.
+    if (json && typeof json === "object") {
+        const j = json;
+        if (j.resultCode !== undefined && j.resultCode !== 1) {
+            const msg = `upload IM API error resultCode=${j.resultCode}${j.resultMsg ? ` resultMsg=${j.resultMsg}` : ""}`;
+            log?.error(`[cwork_im:upload] ${msg} body=${rawText.slice(0, 500)}`);
+            throw new ResourceUploadError(msg, { retryable: false });
+        }
+    }
+    const fileId = extractFileIdFromUploadResponse(json ?? rawText);
+    if (!fileId) {
+        log?.error(`[cwork_im:upload] missing fileId in body=${rawText.slice(0, 500)}`);
+        throw new ResourceUploadError(`upload response missing fileId: ${rawText.slice(0, 500)}`, {
+            retryable: false,
+        });
+    }
+    return { fileId, size: buffer.length };
+}
+export function resolveMaxAttachmentBytes(config) {
+    return config.maxAttachmentBytes ?? DEFAULT_MAX_BYTES;
+}
+/**
+ * 资源整文件上传错误：携带 HTTP 状态与是否可重试标记。
+ *
+ * 判定规则（与 send-service 的消息重试对齐）：
+ * - 网络错误 / 超时 / 408 / 429 / 5xx → 可重试
+ * - 其它 4xx / 业务 resultCode 错误 / 缺少 fileId → 永久失败，不重试
+ */
+export class ResourceUploadError extends Error {
+    status;
+    retryable;
+    constructor(message, opts) {
+        super(message);
+        this.name = "ResourceUploadError";
+        this.status = opts.status;
+        this.retryable = opts.retryable;
+    }
+}
+function isRetryableHttpStatus(status) {
+    return status >= 500 || status === 408 || status === 429;
+}
+/**
+ * 带重试的整文件上传：默认最多 3 次（首次 + 2 次重试），间隔 1s、3s。
+ * 仅对 {@link ResourceUploadError.retryable} 为真的错误重试；业务错误、非可重试 4xx、缺少 fileId 立即抛出。
+ */
+export async function uploadWholeResourceFileWithRetry(args, retry) {
+    const maxAttempts = retry?.maxAttempts ?? 3;
+    const delaysMs = retry?.delaysMs ?? [1_000, 3_000];
+    const log = args.log;
+    let lastErr;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await uploadWholeResourceFile(args);
+        }
+        catch (err) {
+            lastErr = err;
+            const retryable = err instanceof ResourceUploadError ? err.retryable : false;
+            const isLast = attempt >= maxAttempts;
+            if (!retryable || isLast) {
+                log?.error(`[cwork_im:upload] give up (attempt=${attempt}/${maxAttempts}, retryable=${retryable}): ${String(err)}`);
+                throw err;
+            }
+            const waitMs = delaysMs[attempt - 1] ?? delaysMs[delaysMs.length - 1] ?? 1_000;
+            log?.warn?.(`[cwork_im:upload] retrying (attempt=${attempt}/${maxAttempts}) in ${waitMs}ms: ${String(err)}`);
+            await new Promise((resolve) => setTimeout(resolve, waitMs));
+        }
+    }
+    throw lastErr ?? new Error("[cwork_im:upload] upload failed after retries");
+}
+//# sourceMappingURL=resource-file.js.map