@lark-apaas/miaoda-cli 0.1.0-alpha.08508f4

package/dist/api/file/api.js

@@ -0,0 +1,425 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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 = Date.parse(opts.uploadedSince);
+        if (!Number.isNaN(ms)) {
+            conds.push({ field: "createdAt", operator: "gte", value: String(ms) });
+        }
+    }
+    if (conds.length === 0)
+        return undefined;
+    return { logic: "and", groups: [{ conditions: conds }] };
+}
+/**
+ * 列出文件：所有过滤下推到后端 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);
+}
+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" });
+    (0, client_1.ensureSuccess)(body);
+}
+/**
+ * 上传文件（3 步：preUpload → PUT uploadURL → callback）。
+ * PUT 步骤直接 fetch uploadURL（对象存储直传，绕开框架 HttpClient）。
+ */
+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();
+        const res = await fetch(pre.uploadURL, {
+            method: "PUT",
+            headers: {
+                "Content-Type": opts.contentType,
+                "Content-Length": String(opts.fileSize),
+            },
+            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 失败仅 warning，文件已经上传到对象存储
+    try {
+        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 remotePath = opts.remotePath ?? `/${opts.fileName}`;
+    const result = {
+        file_name: opts.fileName,
+        path: remotePath,
+        size: opts.fileSize,
+        type: opts.contentType,
+    };
+    // 上传完成后补一次 stat，拿到后端返回的 download_url（preUpload/callback 都不返）
+    // 非关键路径：拿不到就降级，只是 JSON 输出里缺 download_url 字段
+    try {
+        const info = await statFile({ appId: opts.appId, filePath: remotePath });
+        if (info.download_url)
+            result.download_url = info.download_url;
+        if (info.file_name)
+            result.file_name = info.file_name;
+    }
+    catch (err) {
+        (0, logger_1.debug)(`post-upload stat failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return result;
+}
+// ── 预签下载 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 };
+}

package/dist/api/file/client.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultBucketId = getDefaultBucketId;
+exports.resetBucketCache = resetBucketCache;
+exports.ensureSuccess = ensureSuccess;
+exports.doGet = doGet;
+exports.doPost = doPost;
+exports.doRequest = doRequest;
+const http_1 = require("../../utils/http");
+const error_1 = require("../../utils/error");
+const logger_1 = require("../../utils/logger");
+const http_client_1 = require("@lark-apaas/http-client");
+/**
+ * 输出一条 HTTP 调试日志（仅 --verbose 模式生效）。
+ *
+ * 主要用于把后端返回的 `x-tt-logid` 透出给用户，方便拿这个 id 去 server / 网关日志里
+ * 直接定位本次请求的 `[MiaodaCLI.metric]` 行与上下游 trace。
+ */
+function traceHttp(method, url, start, response, err) {
+    try {
+        const cost = Date.now() - start;
+        const status = response?.status ?? 0;
+        const logid = response?.headers?.get?.("x-tt-logid") ?? "-";
+        if (err !== undefined) {
+            const errMsg = err instanceof Error
+                ? err.message
+                : typeof err === "string"
+                    ? err
+                    : JSON.stringify(err);
+            (0, logger_1.debug)(`http ${method} ${url} ${String(status)} cost=${String(cost)}ms x-tt-logid=${logid} err=${errMsg}`);
+            return;
+        }
+        (0, logger_1.debug)(`http ${method} ${url} ${String(status)} cost=${String(cost)}ms x-tt-logid=${logid}`);
+    }
+    catch {
+        // debug 失败不应影响业务，吞掉
+    }
+}
+/** 进程内 bucket 缓存：{appId: bucketId}。不跨进程。 */
+const bucketCache = new Map();
+/**
+ * 获取默认 bucket（首次调用懒加载，进程内缓存）。
+ *
+ * 后端：GET /b/{appId}/get_published_v2
+ *
+ * 注意：这个接口属于运行端 innerapi（不是 admin 管理端），必须用
+ * getRuntimeHttpClient()；其余 /v1/storage/app/... 六条 admin 接口走 admin client。
+ */
+async function getDefaultBucketId(appId) {
+    const cached = bucketCache.get(appId);
+    if (cached)
+        return cached;
+    const url = `/b/${encodeURIComponent(appId)}/get_published_v2`;
+    const body = await doGet(url, { errorContext: `fetch default bucket for app '${appId}'` }, (0, http_1.getRuntimeHttpClient)());
+    ensureSuccess(body);
+    const bucketId = body.data?.app_runtime_extra?.bucket?.default_bucket_id;
+    if (!bucketId) {
+        throw new error_1.AppError("BUCKET_NOT_FOUND", `No default bucket for app '${appId}'`);
+    }
+    bucketCache.set(appId, bucketId);
+    return bucketId;
+}
+/** 仅测试用：重置 bucket 缓存 */
+function resetBucketCache() {
+    bucketCache.clear();
+}
+/**
+ * 校验 file-storage inner API 响应信封。
+ * 成功条件：`ErrorCode == "0"` 或 `error_code == "0"`，或都未返回视为成功。
+ * 失败时抛 AppError（映射到 CLI 错误码由 handler 层决定）。
+ */
+/**
+ * 后端 file-storage 业务错误码 → CLI 错误码映射。
+ *
+ * 约定：后端业务错误**全部**通过 HTTP 200 返回，靠 `status_code` 字段区分
+ * （`"0"` = 成功；`"k_img_ec_xxxxxx"` 等 = 业务错误）。CLI 这份映射表是
+ * **长期维护**的（后端历史码不会迁移到语义化 code），发现新 code 在此增补。
+ *
+ * 增补流程：
+ *   1. 观察后端响应 `{status_code: "k_img_ec_xxx", error_msg: "..."}`
+ *   2. 确认 code 对应的业务语义（查后端代码 / 问同事）
+ *   3. 在此表加一行，选一个语义化的 CLI code（参考命名：`FILE_NOT_FOUND`
+ *      / `FILE_ALREADY_EXISTS` / `INVALID_*` / `PERMISSION_DENIED` 等）
+ *   4. 未映射的 code 会 fallback 到 `FILE_API_<原 code>`，不影响功能，但 Agent 不易识别
+ */
+const BIZ_ERR_MAP = new Map(Object.entries({
+    k_img_ec_000034: {
+        code: "FILE_NOT_FOUND",
+        message: "File does not exist",
+        hint: "Run `miaoda file ls` to see available files.",
+    },
+    k_img_ec_000035: {
+        code: "FILE_ALREADY_EXISTS",
+        message: "A file at this path already exists",
+        hint: "Rename the target or delete the existing file first (`miaoda file rm`).",
+    },
+}));
+function ensureSuccess(body) {
+    // 后端 envelope 字段历史遗留多种命名：
+    //   - ErrorCode / error_code: 部分接口
+    //   - status_code: delete / sign / head / preUpload 等新接口
+    const code = body.ErrorCode ?? body.error_code ?? body.status_code ?? "0";
+    if (code === "0" || code === "")
+        return;
+    // 错误 message 字段同样散：ErrorMessage / error_message / error_msg / Message
+    const backendMsg = body.ErrorMessage ?? body.error_message ?? body.error_msg ?? body.Message ?? "unknown error";
+    const mapped = BIZ_ERR_MAP.get(code);
+    if (mapped) {
+        throw new error_1.AppError(mapped.code, mapped.message ?? backendMsg, {
+            next_actions: mapped.hint ? [mapped.hint] : undefined,
+        });
+    }
+    throw new error_1.AppError(`FILE_API_${code}`, `File API error [${code}]: ${backendMsg}`);
+}
+/** 从 HttpError 的 response 里尝试读 body，用于拿后端返的业务 ErrorCode。 */
+async function extractBody(resp) {
+    if (!resp)
+        return null;
+    try {
+        return (await resp.json());
+    }
+    catch {
+        return null;
+    }
+}
+/** 把 SDK 抛出的 HttpError 统一映射成 CLI AppError（404 / 业务 ErrorCode / 兜底）。 */
+async function mapHttpError(err, opts) {
+    if (err instanceof error_1.AppError)
+        throw err;
+    if (err instanceof http_client_1.HttpError) {
+        const status = err.response?.status ?? 0;
+        const body = await extractBody(err.response);
+        // 1. 先看后端业务 ErrorCode（优先级最高）
+        if (body) {
+            const code = body.ErrorCode ?? body.error_code ?? "";
+            if (code && code !== "0") {
+                const msg = body.ErrorMessage ?? body.error_message ?? body.Message ?? err.message;
+                throw new error_1.AppError(`FILE_API_${code}`, `File API error [${code}]: ${msg}`);
+            }
+        }
+        // 2. 404 常见情况 —— 路径不存在，映射到业务语义
+        if (status === 404 && opts.notFoundCode) {
+            throw new error_1.AppError(opts.notFoundCode, opts.notFoundMessage ?? "resource not found", {
+                next_actions: opts.notFoundHint ? [opts.notFoundHint] : undefined,
+            });
+        }
+        // 3. 兜底：保留原始 status 的 HttpError（给上层看到真实状态码）
+        const ctx = opts.errorContext ?? "HTTP request failed";
+        const statusText = err.response?.statusText ?? "";
+        throw new error_1.HttpError(status, err.config.url ?? "", `${ctx}: ${String(status)} ${statusText}`.trim());
+    }
+    throw err;
+}
+/**
+ * 包一层 client.get + HttpError 统一映射，成功时直接返回 body 的 json。
+ * 默认走 admin innerapi 客户端；个别接口（如 get_published_v2）属于运行端，
+ * 通过第三个参数显式传入 getRuntimeHttpClient() 切换。
+ */
+async function doGet(url, opts = {}, client = (0, http_1.getHttpClient)()) {
+    const start = Date.now();
+    try {
+        const response = await client.get(url);
+        traceHttp("GET", url, start, response);
+        return (await response.json());
+    }
+    catch (err) {
+        traceHttp("GET", url, start, err instanceof http_client_1.HttpError ? err.response : undefined, err);
+        await mapHttpError(err, opts);
+        throw err; // 不可达，mapHttpError 必定 throw
+    }
+}
+/** 包一层 client.post + HttpError 统一映射。默认 admin innerapi，可显式切 runtime。 */
+async function doPost(url, body, opts = {}, client = (0, http_1.getHttpClient)()) {
+    const start = Date.now();
+    try {
+        const response = await client.post(url, body);
+        traceHttp("POST", url, start, response);
+        return (await response.json());
+    }
+    catch (err) {
+        traceHttp("POST", url, start, err instanceof http_client_1.HttpError ? err.response : undefined, err);
+        await mapHttpError(err, opts);
+        throw err;
+    }
+}
+/** 包一层 client.request + HttpError 统一映射（DELETE 带 body 的场景）。 */
+async function doRequest(cfg, opts = {}, client = (0, http_1.getHttpClient)()) {
+    const start = Date.now();
+    try {
+        const response = await client.request(cfg);
+        traceHttp(cfg.method, cfg.url, start, response);
+        return (await response.json());
+    }
+    catch (err) {
+        traceHttp(cfg.method, cfg.url, start, err instanceof http_client_1.HttpError ? err.response : undefined, err);
+        await mapHttpError(err, opts);
+        throw err;
+    }
+}

package/dist/api/file/detect.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * 判断用户输入应当作为 **path**（后端存储 key）还是 **file_name** 处理。
+ *
+ * 背景：
+ * - file-storage 的 `filePath` 是 bucket 内 unique 的对象存储 key，既可能是用户在
+ *   upload 时指定的自定义路径（如 `logs/2026/data.csv`），也可能是后端 preUpload
+ *   自动生成的 fileKey（固定长度的 alphanumeric，可带扩展名，如 `abcdef1234567890.png`）
+ * - `file_name` 是上传时随文件一起登记的人类可读名字（可以含空格 / 中文 / 重复）
+ *
+ * CLI 默认让用户直接传一个字符串，不强制加 `--name`。当字符串"看起来像后端 key"时
+ * 走 path 语义（HEAD 直连），否则走 file_name 语义（FilterExpression `name eq`）。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.looksLikePath = looksLikePath;
+exports.toAbsolutePath = toAbsolutePath;
+/**
+ * 后端 preUpload 生成的 fileKey 特征（实测 file-storage 响应）：
+ *   - base 段是 **16+ 位纯十进制数字**（snowflake ID，如 `1863152526384148`）
+ *   - 可选 1~2 段扩展名（`.ext` / `.tar.gz`），每段 ≤ 10 位字母或数字
+ *
+ * 例：
+ *   - `1863152526384148`              ✓  （16 位 snowflake）
+ *   - `1863152526384148.jpg`          ✓
+ *   - `1858533158493259.tar.gz`       ✓  （2 段扩展）
+ *   - `618a80ddb3b7e1496.jpg`         ✗  （含字母，是用户起的 file_name）
+ *   - `1234`                          ✗  （位数不够）
+ *   - `报告.xlsx` / `my file.doc`     ✗  （非 ASCII / 含空格）
+ *
+ * 修紧到纯数字是为了避开"用户上传时把文件命成 16+ 位 hex"的真实场景 ——
+ * 后端 fileKey 至今都是纯十进制，二者不重叠。
+ */
+const BACKEND_KEY_PATTERN = /^\d{16,}(?:\.[a-zA-Z0-9]{1,10}){0,2}$/;
+/**
+ * 输入"看起来像 path"的判断：
+ * 1. 以 `/` 开头 → 显式绝对路径
+ * 2. 含 `/`（但不以 `/` 开头）→ 命名空间形式的 key，如 `logs/2026/data.csv`
+ * 3. 匹配 `BACKEND_KEY_PATTERN` → 后端生成的 fileKey
+ * 其他情况一律视为 file_name。
+ */
+function looksLikePath(input) {
+    if (!input)
+        return false;
+    if (input.startsWith("/"))
+        return true;
+    if (input.includes("/"))
+        return true;
+    return BACKEND_KEY_PATTERN.test(input);
+}
+/**
+ * 规整为带前导 `/` 的展示/HEAD 形式。
+ * 便于从 auto-detected 的 "abc123...xyz.txt" 回到统一的 `/abc123...xyz.txt`。
+ */
+function toAbsolutePath(input) {
+    return input.startsWith("/") ? input : `/${input}`;
+}