/**
 * 资源中心整文件上传 + OpenClaw deliver 媒体 URL 拉取
 *
 * 上传地址固定为 `baseUrl + /file/upDownload/uploadWholeFile`，与 IM 同域，使用与发消息相同的 access-token。
 */
import type { Log } from "./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