@lark-apaas/miaoda-cli 0.1.1 → 0.1.2

package/dist/api/db/api.js

@@ -16,7 +16,13 @@ const client_1 = require("./client");
  * 配合调用点的 try/catch + traceHttp，让 --verbose 在错误路径上也能拿到
  * x-tt-logid 与 status，方便定位线上问题。
  */
-async function mapDbHttpError(err, url, ctx) {
+async function mapDbHttpError(err, url, ctx, 
+/**
+ * 可选 hook：解析到响应 body 后，如果 envelope 命中业务错误并抛出 AppError，
+ * 调用方可以借此把 body 里的额外字段（如 multi-statement 的 partial results）
+ * 挂到 AppError 上。
+ */
+onErrorBody) {
     if (err instanceof error_1.AppError)
         throw err;
     if (err instanceof http_client_1.HttpError) {
@@ -24,8 +30,17 @@ async function mapDbHttpError(err, url, ctx) {
         const statusText = err.response?.statusText ?? "";
         try {
             const body = (await err.response?.json());
-            if (body)
-                (0, client_1.extractData)(body); // 业务 code 命中 → 抛 AppError；不命中走兜底
+            if (body) {
+                try {
+                    (0, client_1.extractData)(body); // 业务 code 命中 → 抛 AppError；不命中走兜底
+                }
+                catch (appErr) {
+                    if (appErr instanceof error_1.AppError && onErrorBody) {
+                        onErrorBody(body, appErr);
+                    }
+                    throw appErr;
+                }
+            }
         }
         catch (innerErr) {
             if (innerErr instanceof error_1.AppError)
@@ -36,6 +51,20 @@ async function mapDbHttpError(err, url, ctx) {
     }
     throw err;
 }
+/**
+ * 多语句 SQL 失败时把已成功 statement 的 results 挂到 AppError.partial_results 上，
+ * 供上层 handler 构造 PRD 要求的 `completed` 数组。
+ *
+ * 注意参数顺序：(body, appErr) — 与 mapDbHttpError 的 onErrorBody hook 签名对齐。
+ */
+function attachSqlPartialResults(body, appErr) {
+    const data = body.data;
+    if (!data)
+        return;
+    if (!Array.isArray(data.results) || data.results.length === 0)
+        return;
+    appErr.partial_results = data.results;
+}
 // CLI 不再为 dbBranch 设默认值：
 // 用户没传 --env 就完全不携带 dbBranch query 参数，由后端 admin-inner 中间件
 // 按 workspace 多环境状态决定（多环境 → dev / 单环境 → main）。
@@ -61,12 +90,60 @@ async function execSql(opts) {
     }
     catch (err) {
         (0, client_1.traceHttp)("POST", url, start, err instanceof http_client_1.HttpError ? err.response : undefined, err);
-        await mapDbHttpError(err, url, "Failed to execute SQL");
+        await mapDbHttpError(err, url, "Failed to execute SQL", attachSqlPartialResults);
         throw err; // 不可达
     }
     const body = (await response.json());
-    const data = (0, client_1.extractData)(body);
-    return data.results ?? [];
+    try {
+        const data = (0, client_1.extractData)(body);
+        const results = data.results ?? [];
+        // 新协议（dataloom 端 InnerAdminExecuteSQL 错误统一走 success envelope）：
+        // results 末尾追加一条 SqlType="ERROR" 的哨兵，data 字段是 {code,message} JSON。
+        // 这样网关在错误路径不会吞业务字段，CLI 拿到完整 partial_results + statement_index。
+        const last = results.at(-1);
+        if (last?.sqlType === "ERROR") {
+            const appErr = parseSqlErrorSentinel(last.data);
+            appErr.partial_results = results.slice(0, -1);
+            const stmtIdx = data.errorStatementIndex;
+            if (typeof stmtIdx === "number")
+                appErr.statement_index = stmtIdx;
+            throw appErr;
+        }
+        return results;
+    }
+    catch (appErr) {
+        // 旧协议兼容（dataloom 服务端未部署新协议时）：HTTP 2xx 但 envelope status_code != 0
+        // 走 mapDbHttpError → AppError，partial_results 已被网关吞，仅保留 code+message。
+        //
+        // 新协议下上面的 try 块里已经手动 slice 设置了 partial_results（剥离了 ERROR 哨兵），
+        // 这里必须跳过 attach，否则会被 body.data.results 完整数组（含哨兵）覆盖回去。
+        if (appErr instanceof error_1.AppError && appErr.partial_results === undefined) {
+            attachSqlPartialResults(body, appErr);
+        }
+        throw appErr;
+    }
+}
+/**
+ * 解析 InnerAdminExecuteSQL 错误哨兵（results 末尾那条 SqlType="ERROR" 项）的 data 字段。
+ * 服务端约定：data 是 `{"code":"k_dl_xxx","message":"..."}` 形态的 JSON 字符串。
+ *
+ * 拿到 code+message 后复用 mapDataloomBizError 走与旧协议（ensureInnerSuccess）
+ * 完全一致的映射规则——k_dl_1300015 → RESULT_SET_TOO_LARGE、SQLSTATE 透传等
+ * hint / 语义 code 重写不能丢。否则新协议下 SERVER_ERROR_HINTS 会因为 code key
+ * 不匹配而 miss，CLI 用户看不到 LIMIT 引导这种关键 hint。
+ *
+ * 解析失败则降级为 INTERNAL_DB_ERROR + 原始字符串，避免哨兵格式异常时整条调用炸掉。
+ */
+function parseSqlErrorSentinel(payload) {
+    try {
+        const parsed = JSON.parse(payload);
+        const code = typeof parsed.code === "string" && parsed.code !== "" ? parsed.code : "INTERNAL_DB_ERROR";
+        const message = typeof parsed.message === "string" ? parsed.message : payload;
+        return (0, client_1.mapDataloomBizError)(code, message);
+    }
+    catch {
+        return new error_1.AppError("INTERNAL_DB_ERROR", payload);
+    }
 }
 // ── db schema → InnerGetSchema ──
 /**

package/dist/api/db/client.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SQLSTATE_MAP = void 0;
 exports.traceHttp = traceHttp;
 exports.ensureInnerSuccess = ensureInnerSuccess;
+exports.mapDataloomBizError = mapDataloomBizError;
 exports.extractData = extractData;
 exports.buildInnerUrl = buildInnerUrl;
 const error_1 = require("../../utils/error");
@@ -26,11 +27,7 @@ function traceHttp(method, url, start, response, err) {
         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);
+            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;
         }
@@ -54,40 +51,48 @@ function ensureInnerSuccess(body) {
     const code = body.status_code ?? body.ErrorCode ?? "0";
     if (code === "0" || code === "")
         return;
-    const message = stripPgPrefix(body.error_msg ?? body.ErrorMessage ?? `dataloom API error [${code}]`);
+    const appErr = mapDataloomBizError(code, body.error_msg ?? body.ErrorMessage ?? `dataloom API error [${code}]`);
     // PRD 多语句失败：后端在 envelope 顶层透出 errorStatementIndex（从 0 起计），
-    // 单语句 / 单元执行不会带这个字段。下面的 AppError 都把它带上，让最终
-    // CLI JSON envelope 写到 error.statement_index。
-    const stmtIdx = typeof body.errorStatementIndex === "number" ? body.errorStatementIndex : undefined;
-    // k_dl_1300002 是 PG 执行透传错误；error_msg 里常带 SQLSTATE，优先按 SQLSTATE 映射
+    // 单语句 / 单元执行不会带这个字段。挂到 AppError 上让 emitError 落到错误信封
+    // statement_index 字段。
+    if (typeof body.errorStatementIndex === "number") {
+        appErr.statement_index = body.errorStatementIndex;
+    }
+    throw appErr;
+}
+/**
+ * 把 dataloom 业务错误码 + 原始 message 映射为语义化 AppError。
+ *
+ * 同时被两条错误路径共用：
+ *   - ensureInnerSuccess（旧协议：BaseResp.status_code != "0"）
+ *   - api.ts 的 parseSqlErrorSentinel（新协议：success envelope + ERROR 哨兵）
+ *
+ * 优先级：
+ *   1. k_dl_1300002 + SQLSTATE 透传     → SQLSTATE_MAP
+ *   2. k_dl_1600000 + "Invalid DB Branch" → MULTI_ENV_NOT_INITIALIZED
+ *   3. BIZ_ERR_MAP 命中 → 语义 code（可能带 hint）
+ *   4. 兜底 DB_API_<code>
+ *
+ * stripPgPrefix 在这里做一次，调用方传 raw message 即可。
+ */
+function mapDataloomBizError(code, rawMessage) {
+    const message = stripPgPrefix(rawMessage);
     if (code === "k_dl_1300002") {
         const sqlstate = extractSqlstate(message);
         if (sqlstate && exports.SQLSTATE_MAP[sqlstate]) {
-            throw new error_1.AppError(exports.SQLSTATE_MAP[sqlstate], message, { statement_index: stmtIdx });
+            return new error_1.AppError(exports.SQLSTATE_MAP[sqlstate], message);
         }
     }
-    // k_dl_1600000 是 dataloom 通用参数错误，不能整体映射；
-    // message 以 "Invalid DB Branch" 开头的两种触发场景：
-    //   1) 单环境应用使用 --env（多环境未初始化）
-    //   2) 多环境应用传入了不存在的 env 名（如 --env staging）
-    // 两者外部表象一致：dbBranch 在 db_branch 表里查不到，固定映射为 MULTI_ENV_NOT_INITIALIZED。
     if (code === "k_dl_1600000" && message.startsWith("Invalid DB Branch")) {
-        throw new error_1.AppError("MULTI_ENV_NOT_INITIALIZED", "--env is not available (multi-env not initialized)", {
-            next_actions: [
-                "Verify the --env value matches an existing dbBranch.",
-            ],
-        });
+        return new error_1.AppError("MULTI_ENV_NOT_INITIALIZED", "--env is not available (multi-env not initialized)", { next_actions: ["Verify the --env value matches an existing dbBranch."] });
     }
-    // 业务 code 优先映射到语义 CLI code；未知 code 透传为 DB_API_<code> 样式
     const mapped = BIZ_ERR_MAP.get(code);
     if (mapped) {
-        throw new error_1.AppError(mapped.code, mapped.message ?? message, {
+        return new error_1.AppError(mapped.code, mapped.message ?? message, {
             next_actions: mapped.hint ? [mapped.hint] : undefined,
-            statement_index: stmtIdx,
         });
     }
-    // 兜底：dataloom 未映射的 code 原样透传
-    throw new error_1.AppError(`DB_API_${code}`, message, { statement_index: stmtIdx });
+    return new error_1.AppError(`DB_API_${code}`, message);
 }
 /**
  * 剥掉 PG 透传错误的 "ERROR:" 前缀：CLI 输出本身就会前缀 "Error:"，
@@ -111,13 +116,19 @@ function extractSqlstate(msg) {
 const BIZ_ERR_MAP = new Map(Object.entries({
     // 来源：真实环境探测（dataloom InnerExecuteSQL / InnerGetSchema）
     // k_dl_000001：DB 连接 / QPS 限流 等基础设施层错误
-    "k_dl_000001": { code: "INTERNAL_DB_ERROR", hint: "检查 dbBranch 与应用 PG 实例状态，或稍后重试" },
+    k_dl_000001: {
+        code: "INTERNAL_DB_ERROR",
+        hint: "检查 dbBranch 与应用 PG 实例状态，或稍后重试",
+    },
     // k_dl_000002：SQL 解析 / 不支持的 SQL 类型（VACUUM、COPY、SET、SHOW 等）
-    "k_dl_000002": { code: "SQL_SYNTAX_ERROR" },
+    k_dl_000002: { code: "SQL_SYNTAX_ERROR" },
     // k_dl_000003：查询命中系统表（pg_tables / pg_user 等）被拒
-    "k_dl_000003": { code: "SQL_OPERATION_FORBIDDEN" },
+    k_dl_000003: { code: "SQL_OPERATION_FORBIDDEN" },
     // k_dl_1300002：PG 执行错误；实际 SQLSTATE 由 extractSqlstate 单独映射
     // 未匹配到 SQLSTATE 时走下面兜底 DB_API_<code>
+    // k_dl_1300015：SELECT 结果超过 1000 行硬拦；多行 hint 由 output.ts 的
+    // SERVER_ERROR_HINTS 按语义 code 兜底，这里只做 code 改名
+    k_dl_1300015: { code: "RESULT_SET_TOO_LARGE" },
 }));
 /** PG SQLSTATE → CLI code（当前 dataloom 不一定透传，预留未来使用） */
 exports.SQLSTATE_MAP = {

package/dist/api/db/parsers.js

@@ -117,11 +117,35 @@ function toDetail(t, stats) {
     // 优先用 tableStats.indexes（PRIMARY + UNIQUE + INDEX 统一视图）；
     // 回退到 TableVO.indexes（仅二级索引，老后端没返回 tableStats 时使用）
     const rawIndexes = stats?.indexes ?? t.indexes ?? [];
+    const constraints = [];
+    const indexes = [];
+    for (const i of rawIndexes) {
+        const cols = i.indexColumns ?? [];
+        // 过滤掉空列条目（后端偶发返 indexColumns=[] 的占位项），渲染成 "UNIQUE ()" 看起来像 bug
+        if (cols.length === 0)
+            continue;
+        const kind = i.indexType.toLowerCase();
+        if (kind === "primary") {
+            constraints.push({ type: "PRIMARY KEY", columns: cols });
+        }
+        else if (kind === "unique") {
+            constraints.push({ type: "UNIQUE", columns: cols });
+        }
+        else {
+            // foreign / normal / 其它统一进 indexes 段；method 从 indexDef 的 USING 段解析
+            indexes.push({
+                name: i.indexName,
+                columns: cols,
+                method: parseIndexMethod(i.indexDef) ?? "btree",
+            });
+        }
+    }
     return {
         name: t.tableName,
         description: t.comment && t.comment.length > 0 ? t.comment : null,
         columns: (t.fields ?? []).map(toColumn),
-        indexes: rawIndexes.map(toIndex),
+        constraints,
+        indexes,
         estimated_row_count: typeof stats?.estimatedRowCount === "number" ? stats.estimatedRowCount : null,
         size_bytes: typeof stats?.sizeBytes === "number" ? stats.sizeBytes : null,
     };
@@ -137,25 +161,14 @@ function toColumn(f) {
         comment: f.comment && f.comment.length > 0 ? f.comment : null,
     };
 }
-function toIndex(i) {
-    return {
-        name: i.indexName,
-        type: translateIndexType(i.indexType),
-        columns: i.indexColumns ?? [],
-    };
-}
 /**
- * 把后端原始 IndexType（小写：primary / unique / normal / foreign）翻译为 PRD 约定的展示值。
- * 规则：
- *   primary  → "PRIMARY KEY"
- *   unique   → "UNIQUE"
- *   其它    → "INDEX"（foreign 外键通过 relationships 表达，不进 indexes；真的遇到也归 INDEX）
+ * 从 PG 的 CREATE INDEX 语句里提取访问方法（btree / gin / gist / hash 等）。
+ * indexDef 示例: "CREATE INDEX idx_users_name ON public.users USING btree (name)"
+ * 解析失败返 null，由调用方兜底成 PG 默认的 "btree"。
  */
-function translateIndexType(raw) {
-    const s = raw.toLowerCase();
-    if (s === "primary")
-        return "PRIMARY KEY";
-    if (s === "unique")
-        return "UNIQUE";
-    return "INDEX";
+function parseIndexMethod(indexDef) {
+    if (!indexDef)
+        return null;
+    const m = /USING\s+(\w+)/i.exec(indexDef);
+    return m ? m[1].toLowerCase() : null;
 }

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

@@ -0,0 +1,123 @@
+"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/file/api.js

@@ -209,9 +209,7 @@ async function resolveInputs(opts) {
         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);
+        return kind === "path" ? resolveByPath(opts.appId, input) : resolveByName(opts.appId, input);
     }));
 }
 /** path 输入：HEAD 判存在性，path 在 bucket 内 unique 无需反查。 */
@@ -297,14 +295,44 @@ async function preUpload(appId, req) {
     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" });
-    (0, client_1.ensureSuccess)(body);
+    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, {
@@ -323,11 +351,15 @@ async function uploadFile(opts) {
         // 这里复制到独立 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,
         });
@@ -345,34 +377,56 @@ async function uploadFile(opts) {
     if (!etag) {
         throw new error_1.AppError("FILE_UPLOAD_FAILED", "Upload PUT returned no ETag");
     }
-    // callback 失败仅 warning，文件已经上传到对象存储
+    // callback 返回服务端实际生成的对象元数据（filePath / file_name / download_url）。
+    // path 末段是平台生成的 16 位 GID，CLI 无法靠本地信息推断；callback 失败 /
+    // metadata.filePath 缺失时直接抛 FILE_UPLOAD_CALLBACK_INCOMPLETE：对象已落
+    // TOS（PUT 已成功 + ETag 拿到），但 CLI 拿不到真实 path。把 fileName 写到
+    // hint 里引导用户走 `file ls --name` 查实际 path，避免返一个假 path 让后续
+    // stat/download/rm 全部 FILE_NOT_FOUND。
+    let metadata;
     try {
-        await uploadCallback(opts.appId, { uploadID: pre.uploadID, eTag: etag });
+        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 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`, {
+            next_actions: [
+                `Run \`miaoda file ls --name ${opts.fileName}\` to locate the uploaded file.`,
+            ],
+        });
     }
-    const remotePath = opts.remotePath ?? `/${opts.fileName}`;
+    if (!metadata.filePath) {
+        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 result = {
-        file_name: opts.fileName,
-        path: remotePath,
-        size: opts.fileSize,
-        type: opts.contentType,
+        // 优先取服务端 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,
     };
-    // 上传完成后补一次 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)}`);
+    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。

package/dist/api/file/client.js

@@ -22,11 +22,7 @@ function traceHttp(method, url, start, response, err) {
         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);
+            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;
         }

package/dist/api/file/parsers.js

@@ -16,11 +16,7 @@ function int(value) {
 function readSize(meta) {
     if (!meta)
         return 0;
-    const v = meta.size ??
-        meta.fileSize ??
-        meta.file_size ??
-        meta.contentLength ??
-        0;
+    const v = meta.size ?? meta.fileSize ?? meta.file_size ?? meta.contentLength ?? 0;
     return int(v);
 }
 /**

package/dist/api/plugin/api.js

@@ -38,7 +38,9 @@ async function getPluginVersion(pluginKey, requestedVersion) {
     const versions = await getPluginVersions([pluginKey], isLatest);
     const pluginVersions = versions[pluginKey];
     if (!pluginVersions || pluginVersions.length === 0) {
-        throw new error_1.AppError("PLUGIN_NOT_FOUND", `Plugin not found: ${pluginKey}`, { next_actions: ["检查包名拼写，或确认该插件已在插件市场发布"] });
+        throw new error_1.AppError("PLUGIN_NOT_FOUND", `Plugin not found: ${pluginKey}`, {
+            next_actions: ["检查包名拼写，或确认该插件已在插件市场发布"],
+        });
     }
     if (isLatest) {
         return pluginVersions[0];
@@ -53,7 +55,9 @@ async function getPluginVersion(pluginKey, requestedVersion) {
 function parsePluginKey(key) {
     const match = /^(@[^/]+)\/(.+)$/.exec(key);
     if (!match) {
-        throw new error_1.AppError("INVALID_PLUGIN_KEY", `Invalid plugin key format: ${key}`, { next_actions: ["插件 key 必须形如 @scope/name"] });
+        throw new error_1.AppError("INVALID_PLUGIN_KEY", `Invalid plugin key format: ${key}`, {
+            next_actions: ["插件 key 必须形如 @scope/name"],
+        });
     }
     return { scope: match[1], name: match[2] };
 }
@@ -91,7 +95,8 @@ async function withRetry(operation, description, maxRetries = MAX_RETRIES) {
             }
         }
     }
-    throw lastError ?? new error_1.AppError("INTERNAL_RETRY_EXHAUSTED", `${description} failed after ${String(maxRetries)} retries`, { retryable: true, next_actions: ["检查网络后重试，--verbose 可查看重试日志"] });
+    throw (lastError ??
+        new error_1.AppError("INTERNAL_RETRY_EXHAUSTED", `${description} failed after ${String(maxRetries)} retries`, { retryable: true, next_actions: ["检查网络后重试，--verbose 可查看重试日志"] }));
 }
 /** 插件缓存目录 */
 const PLUGIN_CACHE_DIR = "node_modules/.cache/miaoda-cli/plugins";

package/dist/cli/commands/db/index.js

@@ -179,6 +179,7 @@ Examples:
         .option("--format <fmt>", "导出格式 csv / json / sql，默认 csv（sql 输出 INSERT 语句，可用 db sql < file.sql 回放）")
         .option("-f, --file <path>", "输出文件路径，默认 <表名>.<格式>")
         .option("--limit <n>", "最多导出行数（不超过 5000）")
+        .option("--force", "输出文件已存在时覆盖（默认报错）")
         .action(async function (table) {
         await (0, index_1.handleDbDataExport)(table, this.optsWithGlobals());
     })