@lark-apaas/miaoda-cli 0.1.3 → 0.1.4-alpha.abaa17f

package/dist/api/file/api.js

@@ -8,8 +8,10 @@ exports.uploadFile = uploadFile;
 exports.signDownload = signDownload;
 exports.downloadFile = downloadFile;
 exports.deleteFiles = deleteFiles;
+exports.getStorageQuota = getStorageQuota;
 const error_1 = require("../../utils/error");
 const logger_1 = require("../../utils/logger");
+const time_1 = require("../../utils/time");
 const client_1 = require("./client");
 const detect_1 = require("./detect");
 const parsers_1 = require("./parsers");
@@ -19,18 +21,18 @@ const parsers_1 = require("./parsers");
  * 所有进入 API 层的 path 都要 strip 前导 `/`。
  */
 function toApiPath(filePath) {
-    return filePath.replace(/^\/+/, "");
+    return filePath.replace(/^\/+/, '');
 }
 function encodePath(filePath) {
     return toApiPath(filePath)
-        .split("/")
+        .split('/')
         .map((seg) => encodeURIComponent(seg))
-        .join("/");
+        .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");
+        throw new error_1.AppError('INTERNAL_FILE_API_ERROR', 'API returned empty data');
     }
     return body.data;
 }
@@ -49,7 +51,7 @@ async function listOnce(appId, bucketId, opts) {
     if (opts.sortBy && opts.sortBy.length > 0)
         reqBody.sortBy = opts.sortBy;
     const body = await (0, client_1.doPost)(url, reqBody, {
-        errorContext: "list files",
+        errorContext: 'list files',
     });
     return extractEnvelope(body);
 }
@@ -70,29 +72,29 @@ function buildFilterExpr(opts) {
         return opts.filterExpr;
     const conds = [];
     if (opts.name) {
-        conds.push({ field: "name", operator: "eq", value: opts.name });
+        conds.push({ field: 'name', operator: 'eq', value: opts.name });
     }
     if (opts.type) {
-        conds.push({ field: "type", operator: "eq", value: 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) });
+        conds.push({ field: 'size', operator: 'gt', value: String(opts.sizeGt) });
     }
     if (opts.sizeLt !== undefined) {
-        conds.push({ field: "size", operator: "lt", value: String(opts.sizeLt) });
+        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) });
+        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) });
+        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 }] };
+    return { logic: 'and', groups: [{ conditions: conds }] };
 }
 /**
  * 解析时间过滤参数（--uploaded-since / --uploaded-until）的三种输入格式
@@ -107,31 +109,17 @@ function buildFilterExpr(opts) {
  * 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]];
+    try {
+        return (0, time_1.parseTimeToMs)(input);
     }
-    // 绝对时间：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）`);
+    catch (err) {
+        if (err instanceof error_1.AppError) {
+            throw new error_1.AppError(err.code, `${flagName}: ${err.message}`, {
+                next_actions: err.next_actions,
+            });
+        }
+        throw err;
     }
-    return ms;
 }
 /**
  * 列出文件：所有过滤下推到后端 FilterExpression，纯精确匹配，无 glob。
@@ -147,7 +135,7 @@ async function listFiles(opts) {
     let hasMore = false;
     // 分页 cursor 用 raw attachment.id（后端 continuationToken 语义）；
     // CLI 对外不暴露 attachment.id，所以这里单独追踪最后一页的 raw id
-    let lastRawId = "";
+    let lastRawId = '';
     for (;;) {
         const fetchLimit = opts.all ? 200 : pageSize;
         const data = await listOnce(opts.appId, bucketId, {
@@ -159,7 +147,7 @@ async function listFiles(opts) {
         const rawItems = data.attachments ?? [];
         hasMore = Boolean(data.hasMore);
         if (rawItems.length > 0) {
-            lastRawId = rawItems[rawItems.length - 1].id ?? "";
+            lastRawId = rawItems[rawItems.length - 1].id ?? '';
         }
         for (const raw of rawItems) {
             const info = (0, parsers_1.parseAttachment)(raw);
@@ -208,8 +196,8 @@ 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);
+        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 无需反查。 */
@@ -218,17 +206,17 @@ async function resolveByPath(appId, input) {
     const filePath = (0, detect_1.toAbsolutePath)(input);
     try {
         const info = await statFile({ appId, filePath });
-        return { status: "ok", input, file: info };
+        return { status: 'ok', input, file: info };
     }
     catch (err) {
-        if (err instanceof error_1.AppError && err.code === "FILE_NOT_FOUND") {
+        if (err instanceof error_1.AppError && err.code === 'FILE_NOT_FOUND') {
             return {
-                status: "error",
+                status: 'error',
                 input,
                 error: {
-                    code: "FILE_NOT_FOUND",
+                    code: 'FILE_NOT_FOUND',
                     message: `File '${input}' does not exist`,
-                    hint: "Run `miaoda file ls` to see available files.",
+                    hint: 'Run `miaoda file ls` to see available files.',
                 },
             };
         }
@@ -238,38 +226,38 @@ async function resolveByPath(appId, input) {
 /** 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 }] }],
+        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;
+        const basename = i.path.split('/').pop() ?? i.path;
         return i.file_name === input || basename === input;
     });
     if (matches.length === 0) {
         return {
-            status: "error",
+            status: 'error',
             input,
             error: {
-                code: "FILE_NOT_FOUND",
+                code: 'FILE_NOT_FOUND',
                 message: `File '${input}' does not exist`,
-                hint: "Run `miaoda file ls` to see available files.",
+                hint: 'Run `miaoda file ls` to see available files.',
             },
         };
     }
     if (matches.length > 1) {
         return {
-            status: "error",
+            status: 'error',
             input,
             error: {
-                code: "AMBIGUOUS_FILE_NAME",
+                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] };
+    return { status: 'ok', input, file: matches[0] };
 }
 // ── stat ──
 /**
@@ -281,10 +269,10 @@ async function statFile(opts) {
     // 对齐 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",
+        notFoundCode: 'FILE_NOT_FOUND',
         notFoundMessage: `File '${opts.filePath}' does not exist`,
-        notFoundHint: "Run `miaoda file ls` to see available files.",
-        errorContext: "stat file",
+        notFoundHint: 'Run `miaoda file ls` to see available files.',
+        errorContext: 'stat file',
     });
     return (0, parsers_1.parseHead)(extractEnvelope(body), opts.filePath);
 }
@@ -292,7 +280,7 @@ async function statFile(opts) {
 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" });
+    const body = await (0, client_1.doPost)(url, { bucketID: bucketId, appID: appId, ...req }, { errorContext: 'pre-upload' });
     return extractEnvelope(body);
 }
 /**
@@ -308,14 +296,14 @@ async function preUpload(appId, req) {
 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",
+        errorContext: 'upload callback',
     });
     const data = extractEnvelope(body);
     const metadata = data.metadata;
     if (!metadata) {
         return {};
     }
-    if (typeof metadata === "object") {
+    if (typeof metadata === 'object') {
         return metadata;
     }
     // string 形态兜底
@@ -342,10 +330,10 @@ async function uploadFile(opts) {
         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");
+        throw new error_1.AppError('FILE_UPLOAD_FAILED', 'preUpload did not return uploadURL/uploadID');
     }
     const body = await opts.readFile();
-    let etag = "";
+    let etag = '';
     try {
         // Node 20+ 内置 fetch 运行时接受 Buffer，但 TS 的 BodyInit 要求更严格的类型；
         // 这里复制到独立 ArrayBuffer 以满足 lib.dom.d.ts 的 BodyInit 约束
@@ -355,27 +343,27 @@ async function uploadFile(opts) {
         // header 作为对象 metadata 存住，服务端 callback 阶段 HeadObject 读回并解析
         // filename 写入 DB。我们要不传 header，服务端走兜底会把 storage key 当文件名。
         const res = await fetch(pre.uploadURL, {
-            method: "PUT",
+            method: 'PUT',
             headers: {
-                "Content-Type": opts.contentType,
-                "Content-Length": String(opts.fileSize),
-                "Content-Disposition": `attachment; filename="${sanitizeFileName(opts.fileName)}"`,
+                '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)}`);
+            throw new error_1.AppError('FILE_UPLOAD_FAILED', `Upload PUT failed with status ${String(res.status)}`);
         }
-        etag = res.headers.get("ETag") ?? "";
+        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)}`);
+        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");
+        throw new error_1.AppError('FILE_UPLOAD_FAILED', 'Upload PUT returned no ETag');
     }
     // callback 返回服务端实际生成的对象元数据（filePath / file_name / download_url）。
     // path 末段是平台生成的 16 位 GID，CLI 无法靠本地信息推断；callback 失败 /
@@ -389,20 +377,20 @@ async function uploadFile(opts) {
     }
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
-        throw new error_1.AppError("FILE_UPLOAD_CALLBACK_INCOMPLETE", `Upload callback failed: ${reason}; file may already exist in storage`, {
+        throw new error_1.AppError('FILE_UPLOAD_CALLBACK_INCOMPLETE', `Upload callback failed: ${reason}; file may already exist in storage`, {
             next_actions: [
                 `Run \`miaoda file ls --name ${opts.fileName}\` to locate the uploaded file.`,
             ],
         });
     }
     if (!metadata.filePath) {
-        throw new error_1.AppError("FILE_UPLOAD_CALLBACK_INCOMPLETE", "Upload callback returned no filePath; file may already exist in storage", {
+        throw new error_1.AppError('FILE_UPLOAD_CALLBACK_INCOMPLETE', 'Upload callback returned no filePath; file may already exist in storage', {
             next_actions: [
                 `Run \`miaoda file ls --name ${opts.fileName}\` to locate the uploaded file.`,
             ],
         });
     }
-    const path = metadata.filePath.startsWith("/") ? metadata.filePath : "/" + metadata.filePath;
+    const path = metadata.filePath.startsWith('/') ? metadata.filePath : '/' + metadata.filePath;
     const result = {
         // 优先取服务端 ObjectVO.name（来自 PUT 时带的 Content-Disposition），
         // 与后续 file ls / file stat 返回的展示名保持一致；缺失时降级用本地 fileName。
@@ -425,7 +413,7 @@ async function uploadFile(opts) {
  */
 function sanitizeFileName(fileName) {
     const illegalChars = /[:"\\/*?<>|,;]/g;
-    return encodeURIComponent(fileName.replace(illegalChars, "")) || "download_file";
+    return encodeURIComponent(fileName.replace(illegalChars, '')) || 'download_file';
 }
 // ── 预签下载 URL ──
 /**
@@ -441,15 +429,15 @@ async function signDownload(opts) {
         expiresIn: opts.expiresIn,
     };
     const body = await (0, client_1.doPost)(url, reqBody, {
-        errorContext: "sign download URL",
+        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 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;
+    const displayPath = opts.filePath.startsWith('/') ? opts.filePath : `/${opts.filePath}`;
+    const fileName = displayPath.split('/').pop() ?? displayPath;
     return {
         file_name: fileName,
         path: displayPath,
@@ -468,11 +456,11 @@ async function downloadFile(opts) {
     }
     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)}`);
+        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)}`);
+        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);
@@ -492,17 +480,17 @@ async function deleteFiles(opts) {
         filePaths: opts.filePaths.map(toApiPath),
     };
     const body = await (0, client_1.doRequest)({
-        method: "DELETE",
+        method: 'DELETE',
         url,
-        headers: { "Content-Type": "application/json" },
+        headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(reqBody),
-    }, { errorContext: "delete files" });
+    }, { errorContext: 'delete files' });
     const data = extractEnvelope(body);
     // 后端响应里只给出被删除成功的 attachments（无前导 /），没删掉的靠对比输入判断
-    const toDisplay = (p) => (p.startsWith("/") ? p : `/${p}`);
+    const toDisplay = (p) => (p.startsWith('/') ? p : `/${p}`);
     const deletedSet = new Set();
     for (const att of data.attachments ?? []) {
-        const p = att.filePath ?? att.name ?? "";
+        const p = att.filePath ?? att.name ?? '';
         if (p)
             deletedSet.add(toApiPath(p));
     }
@@ -514,8 +502,22 @@ async function deleteFiles(opts) {
             deleted.push(toDisplay(normalized));
         }
         else {
-            failed.push({ path: toDisplay(normalized), error: "file not found or not deleted" });
+            failed.push({ path: toDisplay(normalized), error: 'file not found or not deleted' });
         }
     }
     return { deleted, failed };
 }
+// ── storage quota ──
+/**
+ * 后端：GET /v1/storage/app/{appId}/bucket/{bucketId}/quota
+ * 单 bucket 用量；StorageQuotaBytes 暂未对接，CLI 拿到 0 时按 "—" 渲染。
+ * bucketId 缺省时走默认 bucket（与 ls / stat / cp 等一致）。
+ */
+async function getStorageQuota(opts) {
+    const bucketId = opts.bucketId ?? (await (0, client_1.getDefaultBucketId)(opts.appId));
+    const url = `/v1/storage/app/${encodeURIComponent(opts.appId)}/bucket/${encodeURIComponent(bucketId)}/quota`;
+    const body = await (0, client_1.doGet)(url, {
+        errorContext: `fetch storage quota for app '${opts.appId}' bucket '${bucketId}'`,
+    });
+    return extractEnvelope(body);
+}

package/dist/api/file/client.js

@@ -20,9 +20,9 @@ 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") ?? "-";
+        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);
+            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;
         }
@@ -51,7 +51,7 @@ async function getDefaultBucketId(appId) {
     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}'`);
+        throw new error_1.AppError('BUCKET_NOT_FOUND', `No default bucket for app '${appId}'`);
     }
     bucketCache.set(appId, bucketId);
     return bucketId;
@@ -81,31 +81,53 @@ function resetBucketCache() {
  */
 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.",
+        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`).",
+        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`).',
+    },
+    // k_ec_000040：file-storage 上游引擎层连不上下游服务（依赖抖动 / 远端 RPC 失败）。
+    // 文案不向用户暴露内部 code，统一成 INTERNAL_API_ERROR + 重试引导。
+    k_ec_000040: {
+        code: 'INTERNAL_API_ERROR',
+        message: 'Service temporarily unavailable',
+        hint: 'Please retry the command. If it keeps failing, share the x-tt-logid (via --verbose) with the on-call team.',
     },
 }));
+// k_ec_* 命名空间是 file-storage 引擎层通用错误（基础设施 / 上游 RPC），不是
+// 用户输入问题。无显式条目时统一兜底成 INTERNAL_API_ERROR + 重试 hint，避免
+// 暴露内部 code 给最终用户。
+function isEngineCommonError(code) {
+    return /^k_ec_\d+$/.test(code);
+}
 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 === "")
+    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 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,
         });
     }
+    // k_ec_* 引擎层错误统一兜底：用户视角是"服务暂时不可用"，重试即可，
+    // 不要把 `File API error [k_ec_000xxx]: <内部翻译>` 这种半成品文案抛给用户。
+    if (isEngineCommonError(code)) {
+        throw new error_1.AppError('INTERNAL_API_ERROR', 'Service temporarily unavailable', {
+            next_actions: [
+                `Please retry the command. If it keeps failing, share the x-tt-logid (via --verbose) with the on-call team. (upstream code: ${code})`,
+            ],
+        });
+    }
     throw new error_1.AppError(`FILE_API_${code}`, `File API error [${code}]: ${backendMsg}`);
 }
 /** 从 HttpError 的 response 里尝试读 body，用于拿后端返的业务 ErrorCode。 */
@@ -128,22 +150,40 @@ async function mapHttpError(err, opts) {
         const body = await extractBody(err.response);
         // 1. 先看后端业务 ErrorCode（优先级最高）
         if (body) {
-            const code = body.ErrorCode ?? body.error_code ?? "";
-            if (code && code !== "0") {
+            const code = body.ErrorCode ?? body.error_code ?? '';
+            if (code && code !== '0') {
+                const mapped = BIZ_ERR_MAP.get(code);
+                if (mapped) {
+                    const msg = body.ErrorMessage ??
+                        body.error_message ??
+                        body.Message ??
+                        mapped.message ??
+                        err.message;
+                    throw new error_1.AppError(mapped.code, mapped.message ?? msg, {
+                        next_actions: mapped.hint ? [mapped.hint] : undefined,
+                    });
+                }
+                if (isEngineCommonError(code)) {
+                    throw new error_1.AppError('INTERNAL_API_ERROR', 'Service temporarily unavailable', {
+                        next_actions: [
+                            `Please retry the command. If it keeps failing, share the x-tt-logid (via --verbose) with the on-call team. (upstream code: ${code})`,
+                        ],
+                    });
+                }
                 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", {
+            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());
+        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;
 }
@@ -156,11 +196,11 @@ 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);
+        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);
+        traceHttp('GET', url, start, err instanceof http_client_1.HttpError ? err.response : undefined, err);
         await mapHttpError(err, opts);
         throw err; // 不可达，mapHttpError 必定 throw
     }
@@ -170,11 +210,11 @@ 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);
+        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);
+        traceHttp('POST', url, start, err instanceof http_client_1.HttpError ? err.response : undefined, err);
         await mapHttpError(err, opts);
         throw err;
     }

package/dist/api/file/detect.js

@@ -41,9 +41,9 @@ const BACKEND_KEY_PATTERN = /^\d{16,}(?:\.[a-zA-Z0-9]{1,10}){0,2}$/;
 function looksLikePath(input) {
     if (!input)
         return false;
-    if (input.startsWith("/"))
+    if (input.startsWith('/'))
         return true;
-    if (input.includes("/"))
+    if (input.includes('/'))
         return true;
     return BACKEND_KEY_PATTERN.test(input);
 }
@@ -52,5 +52,5 @@ function looksLikePath(input) {
  * 便于从 auto-detected 的 "abc123...xyz.txt" 回到统一的 `/abc123...xyz.txt`。
  */
 function toAbsolutePath(input) {
-    return input.startsWith("/") ? input : `/${input}`;
+    return input.startsWith('/') ? input : `/${input}`;
 }

package/dist/api/file/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toAbsolutePath = exports.looksLikePath = exports.resetBucketCache = exports.getDefaultBucketId = exports.parseTimeFilterMs = exports.resolveInputs = exports.deleteFiles = exports.downloadFile = exports.signDownload = exports.uploadFile = exports.statFile = exports.listFiles = void 0;
+exports.toAbsolutePath = exports.looksLikePath = exports.resetBucketCache = exports.getDefaultBucketId = exports.getStorageQuota = exports.parseTimeFilterMs = exports.resolveInputs = exports.deleteFiles = exports.downloadFile = exports.signDownload = exports.uploadFile = exports.statFile = exports.listFiles = void 0;
 var api_1 = require("./api");
 Object.defineProperty(exports, "listFiles", { enumerable: true, get: function () { return api_1.listFiles; } });
 Object.defineProperty(exports, "statFile", { enumerable: true, get: function () { return api_1.statFile; } });
@@ -10,6 +10,7 @@ Object.defineProperty(exports, "downloadFile", { enumerable: true, get: function
 Object.defineProperty(exports, "deleteFiles", { enumerable: true, get: function () { return api_1.deleteFiles; } });
 Object.defineProperty(exports, "resolveInputs", { enumerable: true, get: function () { return api_1.resolveInputs; } });
 Object.defineProperty(exports, "parseTimeFilterMs", { enumerable: true, get: function () { return api_1.parseTimeFilterMs; } });
+Object.defineProperty(exports, "getStorageQuota", { enumerable: true, get: function () { return api_1.getStorageQuota; } });
 var client_1 = require("./client");
 Object.defineProperty(exports, "getDefaultBucketId", { enumerable: true, get: function () { return client_1.getDefaultBucketId; } });
 Object.defineProperty(exports, "resetBucketCache", { enumerable: true, get: function () { return client_1.resetBucketCache; } });