@lark-apaas/miaoda-cli 0.1.0 → 0.1.1-alpha.07b4fd5

package/dist/api/db/sql-keywords.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SQL_KEYWORDS = void 0;
+/**
+ * 常见 PG SQL 关键字白名单，用于 db sql 拼写错误的 did-you-mean 提示。
+ *
+ * # 选词原则
+ *
+ * PG 的关键字总数 700+（见 [pg_keyword 系统视图]），但 CLI 用户实际打错的几乎
+ * 都集中在核心动词 / 子句 / 类型 / 事务关键字。这里**少而精**，约 70 个：
+ *
+ *   - DML 动词：SELECT / INSERT / UPDATE / DELETE / MERGE
+ *   - 子句：FROM / WHERE / JOIN / GROUP / ORDER / HAVING / LIMIT / ...
+ *   - 操作符词：AND / OR / NOT / IN / IS / NULL / LIKE / ...
+ *   - DDL：CREATE / ALTER / DROP / TABLE / INDEX / VIEW / ...
+ *   - 约束：PRIMARY / UNIQUE / FOREIGN / REFERENCES / CHECK / DEFAULT / ...
+ *   - 事务：BEGIN / COMMIT / ROLLBACK / SAVEPOINT / TRANSACTION
+ *   - 控制：IF / EXISTS / CASE / WHEN / THEN / ELSE / END / WITH / ...
+ *
+ * **不要往里加冷僻关键字**——候选集越大，短词越容易 false-positive 错配。
+ */
+exports.SQL_KEYWORDS = [
+    // DML 动词
+    "SELECT", "INSERT", "UPDATE", "DELETE", "MERGE",
+    // FROM / JOIN 系列
+    "FROM", "WHERE", "JOIN", "LEFT", "RIGHT", "INNER", "OUTER", "FULL", "CROSS", "USING",
+    // 聚合 / 排序 / 分页
+    "GROUP", "ORDER", "BY", "HAVING", "LIMIT", "OFFSET", "FETCH",
+    // 集合操作
+    "UNION", "INTERSECT", "EXCEPT", "DISTINCT", "ALL",
+    // 别名 / 关联
+    "AS", "ON",
+    // 操作符词
+    "AND", "OR", "NOT", "IN", "IS", "NULL", "TRUE", "FALSE",
+    "BETWEEN", "LIKE", "ILIKE", "SIMILAR",
+    // DDL
+    "CREATE", "ALTER", "DROP", "TRUNCATE", "RENAME",
+    "TABLE", "INDEX", "VIEW", "DATABASE", "SCHEMA", "COLUMN", "CONSTRAINT", "SEQUENCE",
+    // 约束
+    "PRIMARY", "KEY", "FOREIGN", "REFERENCES", "UNIQUE", "CHECK", "DEFAULT",
+    // 写入
+    "VALUES", "SET", "RETURNING", "INTO",
+    // 事务
+    "BEGIN", "COMMIT", "ROLLBACK", "SAVEPOINT", "TRANSACTION",
+    // 控制流 / CTE
+    "IF", "EXISTS", "REPLACE", "WITH", "RECURSIVE",
+    "CASE", "WHEN", "THEN", "ELSE", "END",
+    // 类型转换 / 时间提取
+    "CAST", "EXTRACT",
+    // 排序方向
+    "ASC", "DESC", "NULLS", "FIRST", "LAST",
+];

package/dist/api/db/types.js

@@ -0,0 +1,10 @@
+"use strict";
+// ── dataloom InnerAPI 响应信封 ──
+//
+// 实际响应结构（与 file-storage 类似）：
+//   { "data": { ...业务字段... }, "status_code": "0", "error_msg": "..." }
+//
+// - `status_code == "0"` 成功
+// - `status_code != "0"` 业务错误（如 PG SQLSTATE 映射后的 code）
+// - 业务字段统一在 `data` 下：`results` / `schema` / `ddl` 等
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/file/api.js

@@ -0,0 +1,509 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTimeFilterMs = parseTimeFilterMs;
+exports.listFiles = listFiles;
+exports.resolveInputs = resolveInputs;
+exports.statFile = statFile;
+exports.uploadFile = uploadFile;
+exports.signDownload = signDownload;
+exports.downloadFile = downloadFile;
+exports.deleteFiles = deleteFiles;
+const error_1 = require("../../utils/error");
+const logger_1 = require("../../utils/logger");
+const client_1 = require("./client");
+const detect_1 = require("./detect");
+const parsers_1 = require("./parsers");
+// ── 内部 helper ──
+/**
+ * 后端存储 path 是无前导 `/` 的，CLI 对外使用带前导 `/` 的表示。
+ * 所有进入 API 层的 path 都要 strip 前导 `/`。
+ */
+function toApiPath(filePath) {
+    return filePath.replace(/^\/+/, "");
+}
+function encodePath(filePath) {
+    return toApiPath(filePath)
+        .split("/")
+        .map((seg) => encodeURIComponent(seg))
+        .join("/");
+}
+function extractEnvelope(body) {
+    (0, client_1.ensureSuccess)(body);
+    if (!body.data) {
+        throw new error_1.AppError("INTERNAL_FILE_API_ERROR", "API returned empty data");
+    }
+    return body.data;
+}
+// ── list ──
+/** 底层单次 list 调用（一页）。支持 filterExpr / sortBy 下推。 */
+async function listOnce(appId, bucketId, opts) {
+    const url = `/v1/storage/app/${encodeURIComponent(appId)}/bucket/${encodeURIComponent(bucketId)}/list`;
+    const reqBody = {
+        bucketID: bucketId,
+        maxKeys: opts.limit,
+    };
+    if (opts.cursor)
+        reqBody.continuationToken = opts.cursor;
+    if (opts.filterExpr)
+        reqBody.filterExpr = opts.filterExpr;
+    if (opts.sortBy && opts.sortBy.length > 0)
+        reqBody.sortBy = opts.sortBy;
+    const body = await (0, client_1.doPost)(url, reqBody, {
+        errorContext: "list files",
+    });
+    return extractEnvelope(body);
+}
+/**
+ * 把 ls 的过滤字段合并为一个 FilterExpression 下推到后端。
+ *
+ * 所有字段**精确匹配**（后端不支持 glob / 前缀）。后端支持的 field × operator 矩阵：
+ *   name     → eq / ne
+ *   type     → eq / ne / in / notIn
+ *   size     → eq / ne / gt / gte / lt / lte
+ *   createdAt→ gt / gte / lt / lte（value 要毫秒 timestamp）
+ *   createdBy→ eq / ne / isNull / isNotNull
+ * （`--path` 字段后端不支持，走 sidecar 过滤）
+ */
+function buildFilterExpr(opts) {
+    // 用户直接传 filterExpr（高级用法）→ 原样透传
+    if (opts.filterExpr)
+        return opts.filterExpr;
+    const conds = [];
+    if (opts.name) {
+        conds.push({ field: "name", operator: "eq", value: opts.name });
+    }
+    if (opts.type) {
+        conds.push({ field: "type", operator: "eq", value: opts.type });
+    }
+    if (opts.sizeGt !== undefined) {
+        conds.push({ field: "size", operator: "gt", value: String(opts.sizeGt) });
+    }
+    if (opts.sizeLt !== undefined) {
+        conds.push({ field: "size", operator: "lt", value: String(opts.sizeLt) });
+    }
+    if (opts.uploadedSince) {
+        // 后端期望毫秒 timestamp（strconv.ParseInt → time.UnixMilli）
+        const ms = parseTimeFilterMs(opts.uploadedSince, "--uploaded-since");
+        conds.push({ field: "createdAt", operator: "gte", value: String(ms) });
+    }
+    if (opts.uploadedUntil) {
+        const ms = parseTimeFilterMs(opts.uploadedUntil, "--uploaded-until");
+        conds.push({ field: "createdAt", operator: "lte", value: String(ms) });
+    }
+    if (conds.length === 0)
+        return undefined;
+    return { logic: "and", groups: [{ conditions: conds }] };
+}
+/**
+ * 解析时间过滤参数（--uploaded-since / --uploaded-until）的三种输入格式
+ * （→ ms timestamp）：
+ *   1. 相对时间："30s" / "10m" / "1h" / "2d" / "1w"  → 当前时间往前推 N 单位
+ *   2. 日期：    "2026-04-01"                       → 按当日 00:00:00 UTC
+ *   3. ISO 8601："2026-04-01T10:00:00Z"             → 严格解析（推荐用 Z 结尾标识 UTC）
+ *
+ * 三种格式都不命中时抛 AppError("ARGS_INVALID")，避免之前 Date.parse=NaN
+ * 时静默跳过过滤、用户却以为筛选生效的悄然失败问题。
+ *
+ * flagName 用于错误信息，调用方传 "--uploaded-since" 或 "--uploaded-until"。
+ */
+function parseTimeFilterMs(input, flagName) {
+    // 相对时间：<positive int><unit>，单位 s/m/h/d/w
+    const RELATIVE = /^(\d+)([smhdw])$/;
+    const rel = RELATIVE.exec(input);
+    if (rel) {
+        const n = parseInt(rel[1], 10);
+        if (n <= 0) {
+            throw new error_1.AppError("ARGS_INVALID", `${flagName} "${input}" 必须是正整数 + 单位（s / m / h / d / w）`);
+        }
+        const UNIT_MS = {
+            s: 1_000,
+            m: 60_000,
+            h: 3_600_000,
+            d: 86_400_000,
+            w: 604_800_000,
+        };
+        return Date.now() - n * UNIT_MS[rel[2]];
+    }
+    // 绝对时间：date / ISO 8601。Date.parse 对 "YYYY-MM-DD" 按 UTC 00:00:00 解析，
+    // 对带 Z 的 ISO 8601 也直接出 UTC ms。
+    const ms = Date.parse(input);
+    if (Number.isNaN(ms)) {
+        throw new error_1.AppError("ARGS_INVALID", `${flagName} "${input}" 格式无法识别。支持：` +
+            `相对时间（如 1h / 2d / 1w）、日期（YYYY-MM-DD）、ISO 8601（如 2026-04-01T10:00:00Z）`);
+    }
+    return ms;
+}
+/**
+ * 列出文件：所有过滤下推到后端 FilterExpression，纯精确匹配，无 glob。
+ *
+ * 后端：POST /v1/storage/app/{appId}/bucket/{bucketId}/list
+ */
+async function listFiles(opts) {
+    const bucketId = await (0, client_1.getDefaultBucketId)(opts.appId);
+    const pageSize = Math.min(Math.max(opts.limit ?? 50, 1), 200);
+    const filterExpr = buildFilterExpr(opts);
+    const collected = [];
+    let cursor = opts.cursor;
+    let hasMore = false;
+    // 分页 cursor 用 raw attachment.id（后端 continuationToken 语义）；
+    // CLI 对外不暴露 attachment.id，所以这里单独追踪最后一页的 raw id
+    let lastRawId = "";
+    for (;;) {
+        const fetchLimit = opts.all ? 200 : pageSize;
+        const data = await listOnce(opts.appId, bucketId, {
+            limit: fetchLimit,
+            cursor,
+            filterExpr,
+            sortBy: opts.sortBy,
+        });
+        const rawItems = data.attachments ?? [];
+        hasMore = Boolean(data.hasMore);
+        if (rawItems.length > 0) {
+            lastRawId = rawItems[rawItems.length - 1].id ?? "";
+        }
+        for (const raw of rawItems) {
+            const info = (0, parsers_1.parseAttachment)(raw);
+            // 后端 FilterExpression 不支持 fileKey 字段，--path 精准匹配靠 sidecar
+            // （PRD：按文件路径精准匹配，path 在 bucket 内 unique → 0 或 1 条命中）
+            if (opts.path && info.path !== opts.path)
+                continue;
+            collected.push(info);
+            if (!opts.all && collected.length >= pageSize)
+                break;
+        }
+        if (!opts.all)
+            break;
+        if (!hasMore || rawItems.length === 0)
+            break;
+        cursor = lastRawId;
+        if (!cursor)
+            break;
+    }
+    const next = !opts.all && hasMore && lastRawId ? lastRawId : null;
+    return {
+        items: collected,
+        next_cursor: next,
+        has_more: opts.all ? false : Boolean(next),
+    };
+}
+/**
+ * 把一批 CLI 输入（path 或 file_name）批量解析成 FileInfo。
+ *
+ * 受限于后端 FilterExpression 能力（只支持 `name eq` / `type eq|in` / `size/createdAt` 范围查，
+ * 不支持 `fileKey` 字段、不支持 `name in`），CLI 按输入类型走两条路径：
+ *
+ * - path 输入（`looksLikePath(input) === true`）：后端 head 接口直接接 path → 单次 HEAD 判存在性
+ * - file_name 输入：后端 list 支持 `name eq X` → 单次 list 精确匹配 → 多匹配 AMBIGUOUS_FILE_NAME
+ *
+ * path 识别规则见 `./detect.ts#looksLikePath`，涵盖：
+ * 1) `/` 开头的绝对路径
+ * 2) 含 `/` 的命名空间 key（如 `logs/2026/data.csv`）
+ * 3) 后端生成的 fileKey 形态（16+ 位 alphanumeric 可带扩展名）
+ *
+ * 需要强制指定类型时调用方可通过 `forceAs` 跳过自动识别。
+ *
+ * N 个 input 并发 N 个请求，每个 O(1)。
+ */
+async function resolveInputs(opts) {
+    if (opts.inputs.length === 0)
+        return [];
+    return Promise.all(opts.inputs.map((input) => {
+        const kind = opts.forceAs ?? ((0, detect_1.looksLikePath)(input) ? "path" : "name");
+        return kind === "path"
+            ? resolveByPath(opts.appId, input)
+            : resolveByName(opts.appId, input);
+    }));
+}
+/** path 输入：HEAD 判存在性，path 在 bucket 内 unique 无需反查。 */
+async function resolveByPath(appId, input) {
+    // 后端 head 接口要求 path 以 `/` 开头。auto-detected 的 "abc123...xyz.txt" 这里补齐。
+    const filePath = (0, detect_1.toAbsolutePath)(input);
+    try {
+        const info = await statFile({ appId, filePath });
+        return { status: "ok", input, file: info };
+    }
+    catch (err) {
+        if (err instanceof error_1.AppError && err.code === "FILE_NOT_FOUND") {
+            return {
+                status: "error",
+                input,
+                error: {
+                    code: "FILE_NOT_FOUND",
+                    message: `File '${input}' does not exist`,
+                    hint: "Run `miaoda file ls` to see available files.",
+                },
+            };
+        }
+        throw err;
+    }
+}
+/** file_name 输入：list + FilterExpression `name eq X`，多匹配 AMBIGUOUS。 */
+async function resolveByName(appId, input) {
+    const filterExpr = {
+        logic: "and",
+        groups: [{ conditions: [{ field: "name", operator: "eq", value: input }] }],
+    };
+    const result = await listFiles({ appId, filterExpr, limit: 200 });
+    // 后端返 name 精确匹配的所有 attachments。basename fallback 防御（后端某些场景 name 可能为空）
+    const matches = result.items.filter((i) => {
+        const basename = i.path.split("/").pop() ?? i.path;
+        return i.file_name === input || basename === input;
+    });
+    if (matches.length === 0) {
+        return {
+            status: "error",
+            input,
+            error: {
+                code: "FILE_NOT_FOUND",
+                message: `File '${input}' does not exist`,
+                hint: "Run `miaoda file ls` to see available files.",
+            },
+        };
+    }
+    if (matches.length > 1) {
+        return {
+            status: "error",
+            input,
+            error: {
+                code: "AMBIGUOUS_FILE_NAME",
+                message: `Multiple files match name '${input}' (${String(matches.length)} found)`,
+                hint: `Use path instead. Run \`miaoda file ls --name ${input}\` to see candidates.`,
+            },
+        };
+    }
+    return { status: "ok", input, file: matches[0] };
+}
+// ── stat ──
+/**
+ * 查看文件元数据。
+ * 后端：GET /v1/storage/app/{appId}/object/{bucketId}/{filePath}/head
+ */
+async function statFile(opts) {
+    const bucketId = await (0, client_1.getDefaultBucketId)(opts.appId);
+    // 对齐 file-storage-skill Py 版：URL 顺序是 .../object/{bucket}/head/{path}
+    const url = `/v1/storage/app/${encodeURIComponent(opts.appId)}/object/${encodeURIComponent(bucketId)}/head/${encodePath(opts.filePath)}`;
+    const body = await (0, client_1.doGet)(url, {
+        notFoundCode: "FILE_NOT_FOUND",
+        notFoundMessage: `File '${opts.filePath}' does not exist`,
+        notFoundHint: "Run `miaoda file ls` to see available files.",
+        errorContext: "stat file",
+    });
+    return (0, parsers_1.parseHead)(extractEnvelope(body), opts.filePath);
+}
+// ── 预签上传 URL ──
+async function preUpload(appId, req) {
+    const bucketId = await (0, client_1.getDefaultBucketId)(appId);
+    const url = `/v1/storage/app/${encodeURIComponent(appId)}/bucket/${encodeURIComponent(bucketId)}/preUpload`;
+    const body = await (0, client_1.doPost)(url, { bucketID: bucketId, appID: appId, ...req }, { errorContext: "pre-upload" });
+    return extractEnvelope(body);
+}
+/**
+ * 调用 upload callback 拿到对象元数据。
+ *
+ * 网关 IDL 在 metadata 字段加了 api.response.converter = "decode"，正常路径下
+ * HTTP 响应里的 metadata 已经被网关从字符串解码成对象；这里两种形态都兼容：
+ *   - object → 直接当 CallbackObjectVO 用（网关解码场景）
+ *   - string → JSON.parse 出来用（后端原始形态 / 网关行为变化兜底）
+ *
+ * 解析失败 / metadata 缺失时返回空对象，由 uploadFile 用本地兜底字段填充。
+ */
+async function uploadCallback(appId, req) {
+    const url = `/v1/storage/app/${encodeURIComponent(appId)}/object/callback`;
+    const body = await (0, client_1.doPost)(url, req, { errorContext: "upload callback" });
+    const data = extractEnvelope(body);
+    const metadata = data.metadata;
+    if (!metadata) {
+        return {};
+    }
+    if (typeof metadata === "object") {
+        return metadata;
+    }
+    // string 形态兜底
+    try {
+        return JSON.parse(metadata);
+    }
+    catch (err) {
+        (0, logger_1.debug)(`upload callback metadata json parse failed: ${err instanceof Error ? err.message : String(err)}`);
+        return {};
+    }
+}
+/**
+ * 上传文件（3 步：preUpload → PUT uploadURL → callback）。
+ * PUT 步骤直接 fetch uploadURL（对象存储直传，绕开框架 HttpClient）。
+ *
+ * 注意：opts.remotePath 仅作为目录前缀传给服务端；最终对象 key 由服务端唯一生成
+ * （形如 "<前缀>/<16位ID>.<扩展名>"），从 preUpload 响应的 filePath 字段取回。
+ */
+async function uploadFile(opts) {
+    const pre = await preUpload(opts.appId, {
+        fileName: opts.fileName,
+        fileSize: opts.fileSize,
+        contentType: opts.contentType,
+        filePath: opts.remotePath ? toApiPath(opts.remotePath) : undefined,
+    });
+    if (!pre.uploadURL || !pre.uploadID) {
+        throw new error_1.AppError("FILE_UPLOAD_FAILED", "preUpload did not return uploadURL/uploadID");
+    }
+    const body = await opts.readFile();
+    let etag = "";
+    try {
+        // Node 20+ 内置 fetch 运行时接受 Buffer，但 TS 的 BodyInit 要求更严格的类型；
+        // 这里复制到独立 ArrayBuffer 以满足 lib.dom.d.ts 的 BodyInit 约束
+        const ab = body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength);
+        const uploadStart = Date.now();
+        // Content-Disposition 用 attachment + filename 编码原始文件名。TOS 会把这个
+        // header 作为对象 metadata 存住，服务端 callback 阶段 HeadObject 读回并解析
+        // filename 写入 DB。我们要不传 header，服务端走兜底会把 storage key 当文件名。
+        const res = await fetch(pre.uploadURL, {
+            method: "PUT",
+            headers: {
+                "Content-Type": opts.contentType,
+                "Content-Length": String(opts.fileSize),
+                "Content-Disposition": `attachment; filename="${sanitizeFileName(opts.fileName)}"`,
+            },
+            body: ab,
+        });
+        (0, logger_1.debug)(`http PUT <upload-cdn> ${String(res.status)} cost=${String(Date.now() - uploadStart)}ms size=${String(opts.fileSize)}`);
+        if (!res.ok) {
+            throw new error_1.AppError("FILE_UPLOAD_FAILED", `Upload PUT failed with status ${String(res.status)}`);
+        }
+        etag = res.headers.get("ETag") ?? "";
+    }
+    catch (err) {
+        if (err instanceof error_1.AppError)
+            throw err;
+        throw new error_1.AppError("FILE_UPLOAD_FAILED", `Upload PUT failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!etag) {
+        throw new error_1.AppError("FILE_UPLOAD_FAILED", "Upload PUT returned no ETag");
+    }
+    // callback 返回服务端实际生成的对象元数据（filePath / file_name / download_url）。
+    // 这是 CLI 拿到真实存储路径的唯一来源——preUpload 不暴露 path，避免客户端再做拼接。
+    // callback 网络失败 / metadata 解析失败时仍按"上传成功"处理：文件已经在对象存储里，
+    // 缺失的字段（如 download_url）只是展示降级；用本地已知信息兜底。
+    let metadata = {};
+    try {
+        metadata = await uploadCallback(opts.appId, { uploadID: pre.uploadID, eTag: etag });
+    }
+    catch (err) {
+        (0, logger_1.debug)(`upload callback failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const path = metadata.filePath
+        ? (metadata.filePath.startsWith("/") ? metadata.filePath : "/" + metadata.filePath)
+        : (opts.remotePath ?? "/" + opts.fileName);
+    const result = {
+        // 优先取服务端 ObjectVO.name（来自 PUT 时带的 Content-Disposition），
+        // 与后续 file ls / file stat 返回的展示名保持一致；缺失时降级用本地 fileName。
+        file_name: metadata.name ?? opts.fileName,
+        path,
+        size: metadata.metadata?.contentLength ?? opts.fileSize,
+        type: metadata.metadata?.mimeType ?? opts.contentType,
+    };
+    if (metadata.downloadURL) {
+        result.download_url = metadata.downloadURL;
+    }
+    return result;
+}
+/**
+ * 把文件名清理成可安全放进 Content-Disposition `filename="..."` 的形态。
+ * 与 fullstack-plugin 的 sanitizeFileName 行为一致：
+ *   1. 去掉对 TOS / 文件系统不友好的字符 [: " \ / * ? < > | , ;]
+ *   2. encodeURIComponent 把非 ASCII（中文等）做百分号编码，保证 header 合法
+ *   3. 处理后为空时退回 "download_file" 兜底
+ */
+function sanitizeFileName(fileName) {
+    const illegalChars = /[:"\\/*?<>|,;]/g;
+    return encodeURIComponent(fileName.replace(illegalChars, "")) || "download_file";
+}
+// ── 预签下载 URL ──
+/**
+ * 获取预签下载 URL。
+ * 后端：POST /v1/storage/app/{appId}/object/sign/{bucketId}/{filePath}
+ */
+async function signDownload(opts) {
+    const bucketId = await (0, client_1.getDefaultBucketId)(opts.appId);
+    const url = `/v1/storage/app/${encodeURIComponent(opts.appId)}/object/sign/${encodeURIComponent(bucketId)}/${encodePath(opts.filePath)}`;
+    const reqBody = {
+        bucketID: bucketId,
+        filePath: toApiPath(opts.filePath),
+        expiresIn: opts.expiresIn,
+    };
+    const body = await (0, client_1.doPost)(url, reqBody, {
+        errorContext: "sign download URL",
+    });
+    // 后端对不存在文件走业务 ErrorCode（status_code=k_img_ec_000034），
+    // 由 ensureSuccess → BIZ_ERR_MAP 统一抛出 FILE_NOT_FOUND，此处无需兜底
+    const data = extractEnvelope(body);
+    const signed = data.signedURL ?? "";
+    const expiresAt = new Date(Date.now() + opts.expiresIn * 1000).toISOString();
+    const displayPath = opts.filePath.startsWith("/") ? opts.filePath : `/${opts.filePath}`;
+    const fileName = displayPath.split("/").pop() ?? displayPath;
+    return {
+        file_name: fileName,
+        path: displayPath,
+        signed_url: signed,
+        expires_at: expiresAt,
+    };
+}
+/**
+ * 下载文件到本地。直接 GET signedURL（对象存储直取，绕开框架 HttpClient）。
+ */
+async function downloadFile(opts) {
+    let res;
+    const downloadStart = Date.now();
+    try {
+        res = await fetch(opts.signedURL);
+    }
+    catch (err) {
+        (0, logger_1.debug)(`http GET <download-cdn> 0 cost=${String(Date.now() - downloadStart)}ms err=${err instanceof Error ? err.message : String(err)}`);
+        throw new error_1.AppError("FILE_DOWNLOAD_FAILED", `Download GET failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    (0, logger_1.debug)(`http GET <download-cdn> ${String(res.status)} cost=${String(Date.now() - downloadStart)}ms`);
+    if (!res.ok) {
+        throw new error_1.AppError("FILE_DOWNLOAD_FAILED", `Download failed with status ${String(res.status)}`);
+    }
+    const array = new Uint8Array(await res.arrayBuffer());
+    const buf = Buffer.from(array);
+    await opts.writeFile(buf);
+    return buf.length;
+}
+// ── 批量删除（best-effort） ──
+/**
+ * 批量删除文件。
+ * 后端：DELETE /v1/storage/app/{appId}/bucket/{bucketId}/delete
+ */
+async function deleteFiles(opts) {
+    const bucketId = await (0, client_1.getDefaultBucketId)(opts.appId);
+    const url = `/v1/storage/app/${encodeURIComponent(opts.appId)}/bucket/${encodeURIComponent(bucketId)}/delete`;
+    const reqBody = {
+        bucketID: bucketId,
+        filePaths: opts.filePaths.map(toApiPath),
+    };
+    const body = await (0, client_1.doRequest)({
+        method: "DELETE",
+        url,
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(reqBody),
+    }, { errorContext: "delete files" });
+    const data = extractEnvelope(body);
+    // 后端响应里只给出被删除成功的 attachments（无前导 /），没删掉的靠对比输入判断
+    const toDisplay = (p) => (p.startsWith("/") ? p : `/${p}`);
+    const deletedSet = new Set();
+    for (const att of data.attachments ?? []) {
+        const p = att.filePath ?? att.name ?? "";
+        if (p)
+            deletedSet.add(toApiPath(p));
+    }
+    const deleted = [];
+    const failed = [];
+    for (const p of opts.filePaths) {
+        const normalized = toApiPath(p);
+        if (deletedSet.has(normalized)) {
+            deleted.push(toDisplay(normalized));
+        }
+        else {
+            failed.push({ path: toDisplay(normalized), error: "file not found or not deleted" });
+        }
+    }
+    return { deleted, failed };
+}