@lark-apaas/miaoda-cli 0.1.1-alpha.e70b415 → 0.1.1-alpha.eccb0b7

package/dist/api/db/api.js

@@ -96,15 +96,55 @@ async function execSql(opts) {
     const body = (await response.json());
     try {
         const data = (0, client_1.extractData)(body);
-        return data.results ?? [];
+        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) {
-        // HTTP 2xx 但 envelope status_code != 0 的多语句失败路径：同样挂 partial_results
-        if (appErr instanceof error_1.AppError)
+        // 旧协议兼容（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 ──
 /**
  * 查询 schema（admin-inner）。

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,16 +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" },
+    k_dl_1300015: { code: "RESULT_SET_TOO_LARGE" },
 }));
 /** PG SQLSTATE → CLI code（当前 dataloom 不一定透传，预留未来使用） */
 exports.SQLSTATE_MAP = {

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

@@ -21,32 +21,103 @@ exports.SQL_KEYWORDS = void 0;
  */
 exports.SQL_KEYWORDS = [
     // DML 动词
-    "SELECT", "INSERT", "UPDATE", "DELETE", "MERGE",
+    "SELECT",
+    "INSERT",
+    "UPDATE",
+    "DELETE",
+    "MERGE",
     // FROM / JOIN 系列
-    "FROM", "WHERE", "JOIN", "LEFT", "RIGHT", "INNER", "OUTER", "FULL", "CROSS", "USING",
+    "FROM",
+    "WHERE",
+    "JOIN",
+    "LEFT",
+    "RIGHT",
+    "INNER",
+    "OUTER",
+    "FULL",
+    "CROSS",
+    "USING",
     // 聚合 / 排序 / 分页
-    "GROUP", "ORDER", "BY", "HAVING", "LIMIT", "OFFSET", "FETCH",
+    "GROUP",
+    "ORDER",
+    "BY",
+    "HAVING",
+    "LIMIT",
+    "OFFSET",
+    "FETCH",
     // 集合操作
-    "UNION", "INTERSECT", "EXCEPT", "DISTINCT", "ALL",
+    "UNION",
+    "INTERSECT",
+    "EXCEPT",
+    "DISTINCT",
+    "ALL",
     // 别名 / 关联
-    "AS", "ON",
+    "AS",
+    "ON",
     // 操作符词
-    "AND", "OR", "NOT", "IN", "IS", "NULL", "TRUE", "FALSE",
-    "BETWEEN", "LIKE", "ILIKE", "SIMILAR",
+    "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",
+    "CREATE",
+    "ALTER",
+    "DROP",
+    "TRUNCATE",
+    "RENAME",
+    "TABLE",
+    "INDEX",
+    "VIEW",
+    "DATABASE",
+    "SCHEMA",
+    "COLUMN",
+    "CONSTRAINT",
+    "SEQUENCE",
     // 约束
-    "PRIMARY", "KEY", "FOREIGN", "REFERENCES", "UNIQUE", "CHECK", "DEFAULT",
+    "PRIMARY",
+    "KEY",
+    "FOREIGN",
+    "REFERENCES",
+    "UNIQUE",
+    "CHECK",
+    "DEFAULT",
     // 写入
-    "VALUES", "SET", "RETURNING", "INTO",
+    "VALUES",
+    "SET",
+    "RETURNING",
+    "INTO",
     // 事务
-    "BEGIN", "COMMIT", "ROLLBACK", "SAVEPOINT", "TRANSACTION",
+    "BEGIN",
+    "COMMIT",
+    "ROLLBACK",
+    "SAVEPOINT",
+    "TRANSACTION",
     // 控制流 / CTE
-    "IF", "EXISTS", "REPLACE", "WITH", "RECURSIVE",
-    "CASE", "WHEN", "THEN", "ELSE", "END",
+    "IF",
+    "EXISTS",
+    "REPLACE",
+    "WITH",
+    "RECURSIVE",
+    "CASE",
+    "WHEN",
+    "THEN",
+    "ELSE",
+    "END",
     // 类型转换 / 时间提取
-    "CAST", "EXTRACT",
+    "CAST",
+    "EXTRACT",
     // 排序方向
-    "ASC", "DESC", "NULLS", "FIRST", "LAST",
+    "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 无需反查。 */
@@ -309,7 +307,9 @@ 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" });
+    const body = await (0, client_1.doPost)(url, req, {
+        errorContext: "upload callback",
+    });
     const data = extractEnvelope(body);
     const metadata = data.metadata;
     if (!metadata) {
@@ -378,19 +378,31 @@ async function uploadFile(opts) {
         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 = {};
+    // 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 {
         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.`,
+            ],
+        });
+    }
+    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
-        ? (metadata.filePath.startsWith("/") ? metadata.filePath : "/" + metadata.filePath)
-        : (opts.remotePath ?? "/" + opts.fileName);
+    const path = metadata.filePath.startsWith("/") ? metadata.filePath : "/" + metadata.filePath;
     const result = {
         // 优先取服务端 ObjectVO.name（来自 PUT 时带的 Content-Disposition），
         // 与后续 file ls / file stat 返回的展示名保持一致；缺失时降级用本地 fileName。

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/plugin/index.js

@@ -58,7 +58,9 @@ JSON 输出
   Error: Invalid plugin name format: bad-name. Expected: @scope/name or @scope/name@version
     hint: 示例：@demo/example-plugin 或 @demo/example-plugin@1.2.3
 `)
-        .action(async (names) => { await (0, index_1.handlePluginInstall)({ names }); });
+        .action(async (names) => {
+        await (0, index_1.handlePluginInstall)({ names });
+    });
     pluginCmd
         .command("update")
         .description("把已安装插件升级到 latest 版本")
@@ -91,7 +93,9 @@ JSON 输出
   $ miaoda plugin update @demo/not-installed --json
   {"updated":[],"skipped":[],"notInstalled":["@demo/not-installed"],"failed":[]}
 `)
-        .action(async (names) => { await (0, index_1.handlePluginUpdate)({ names }); });
+        .action(async (names) => {
+        await (0, index_1.handlePluginUpdate)({ names });
+    });
     pluginCmd
         .command("remove")
         .description("从当前项目移除一个已安装的插件")
@@ -115,7 +119,9 @@ JSON 输出
   Error: Plugin @demo/not-installed is not installed
     hint: 运行 miaoda plugin list-packages 查看已安装插件
 `)
-        .action((name) => { (0, index_1.handlePluginRemove)({ name }); });
+        .action((name) => {
+        (0, index_1.handlePluginRemove)({ name });
+    });
     pluginCmd
         .command("init")
         .description("按 package.json 的 actionPlugins 批量安装所有插件")
@@ -146,7 +152,9 @@ JSON 输出
   Error: package.json not found in current directory
     hint: 在应用项目根目录运行
 `)
-        .action(async () => { await (0, index_1.handlePluginInit)(); });
+        .action(async () => {
+        await (0, index_1.handlePluginInit)();
+    });
     pluginCmd
         .command("list")
         .description("列出当前项目的 capability 实例（./server/capabilities/*.json）")
@@ -178,7 +186,9 @@ JSON 输出
   Error: server/capabilities directory not found
     hint: 当前目录必须是含 server/capabilities/ 的应用项目
 `)
-        .action(async (opts) => { await (0, index_1.handlePluginList)(opts); });
+        .action(async (opts) => {
+        await (0, index_1.handlePluginList)(opts);
+    });
     pluginCmd
         .command("list-packages")
         .description("列出 package.json actionPlugins 里已声明的插件包")
@@ -201,5 +211,7 @@ JSON 输出
   Error: package.json not found in current directory
     hint: 在应用项目根目录运行
 `)
-        .action(() => { (0, index_1.handlePluginListPlugins)(); });
+        .action(() => {
+        (0, index_1.handlePluginListPlugins)();
+    });
 }

package/dist/cli/commands/shared.js

@@ -22,9 +22,7 @@ function resolveAppId(opts) {
     const id = opts.appId ?? process.env.MIAODA_APP_ID ?? process.env.app_id;
     if (!id) {
         throw new error_1.AppError("APP_ID_MISSING", "未指定应用", {
-            next_actions: [
-                "设置 export MIAODA_APP_ID=<id>",
-            ],
+            next_actions: ["设置 export MIAODA_APP_ID=<id>"],
         });
     }
     return id;

package/dist/cli/handlers/db/data.js

@@ -56,7 +56,9 @@ async function handleDbDataImport(file, opts) {
     catch (err) {
         const code = err.code;
         if (code === "ENOENT") {
-            throw new error_1.AppError("IMPORT_FILE_NOT_FOUND", `Local file '${file}' does not exist`, { next_actions: ["Check the file path."] });
+            throw new error_1.AppError("IMPORT_FILE_NOT_FOUND", `Local file '${file}' does not exist`, {
+                next_actions: ["Check the file path."],
+            });
         }
         throw err;
     }
@@ -103,7 +105,9 @@ async function handleDbDataExport(table, opts) {
     if (!opts.force) {
         try {
             await fs.access(outputPath);
-            throw new error_1.AppError("FILE_ALREADY_EXISTS", `Output file '${outputPath}' already exists`, { next_actions: ["Use -f to specify a different path, or --force to overwrite."] });
+            throw new error_1.AppError("FILE_ALREADY_EXISTS", `Output file '${outputPath}' already exists`, {
+                next_actions: ["Use -f to specify a different path, or --force to overwrite."],
+            });
         }
         catch (err) {
             if (err instanceof error_1.AppError)
@@ -119,7 +123,11 @@ async function handleDbDataExport(table, opts) {
         limit,
     });
     if (result.body.length > MAX_SIZE_BYTES) {
-        throw new error_1.AppError("EXPORT_SIZE_EXCEEDED", `Export exceeds 1 MB limit (body is ${String(result.body.length)} bytes)`, { next_actions: [`Filter the table with "miaoda db sql" (e.g. WHERE/LIMIT) and export smaller subsets.`] });
+        throw new error_1.AppError("EXPORT_SIZE_EXCEEDED", `Export exceeds 1 MB limit (body is ${String(result.body.length)} bytes)`, {
+            next_actions: [
+                `Filter the table with "miaoda db sql" (e.g. WHERE/LIMIT) and export smaller subsets.`,
+            ],
+        });
     }
     await fs.writeFile(outputPath, result.body);
     // 优先信任后端 X-Miaoda-Record-Count header；header 缺失时再用 body 行数兜底

package/dist/cli/handlers/db/schema.js

@@ -45,7 +45,12 @@ const index_1 = require("../../../api/db/index");
 // ── schema list ──
 async function handleDbSchemaList(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
-    const resp = await api.db.getSchema({ appId, format: "schema", includeStats: true, dbBranch: opts.env });
+    const resp = await api.db.getSchema({
+        appId,
+        format: "schema",
+        includeStats: true,
+        dbBranch: opts.env,
+    });
     const tables = (0, index_1.flattenSchemaList)(resp.schema);
     if ((0, output_1.isJsonMode)()) {
         (0, output_1.emit)({ data: tables });
@@ -69,7 +74,7 @@ async function handleDbSchemaList(opts) {
         t.name,
         t.description ?? "—",
         t.estimated_row_count === null ? "—" : String(t.estimated_row_count),
-        t.size_bytes === null ? "—" : (tty ? (0, render_1.formatSize)(t.size_bytes) : String(t.size_bytes)),
+        t.size_bytes === null ? "—" : tty ? (0, render_1.formatSize)(t.size_bytes) : String(t.size_bytes),
         String(t.columns),
     ]);
     (0, output_1.emit)(tty ? (0, render_1.renderAlignedTable)(headers, rows) : (0, render_1.renderTsv)(headers, rows));
@@ -109,9 +114,7 @@ async function handleDbSchemaGet(table, opts) {
     const detail = (0, index_1.pickTableDetail)(resp.schema, table);
     if (!detail) {
         throw new error_1.AppError("TABLE_NOT_FOUND", `Table '${table}' does not exist`, {
-            next_actions: [
-                `Did you mean another table? Run "miaoda db schema list" to see all tables.`,
-            ],
+            next_actions: [`Did you mean another table? Run "miaoda db schema list" to see all tables.`],
         });
     }
     if ((0, output_1.isJsonMode)()) {

package/dist/cli/handlers/db/sql.js

@@ -309,7 +309,10 @@ function parseJsonFields() {
     const v = (0, config_1.getConfig)().json;
     if (typeof v !== "string" || v === "")
         return null;
-    return v.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    return v
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
 }
 /** 多语句 pretty：逐条 `Statement N: ...` + 末尾 `✓ N statements executed`。 */
 function renderMultiPretty(results) {
@@ -349,11 +352,16 @@ function renderMultiPretty(results) {
 }
 function dmlVerb(type) {
     switch (type) {
-        case "INSERT": return "inserted";
-        case "UPDATE": return "updated";
-        case "DELETE": return "deleted";
-        case "MERGE": return "merged";
-        case "DML": return "affected"; // 未识别子类的兜底
+        case "INSERT":
+            return "inserted";
+        case "UPDATE":
+            return "updated";
+        case "DELETE":
+            return "deleted";
+        case "MERGE":
+            return "merged";
+        case "DML":
+            return "affected"; // 未识别子类的兜底
     }
 }
 /** 从第一行收集列顺序；缺失列保留空白（兼容稀疏行）。 */
@@ -491,33 +499,31 @@ async function loadTableMap(ctx) {
 }
 function enrichRelationNotExist(err, relation, tableMap) {
     const guess = (0, fuzzy_match_1.suggest)(relation, Object.keys(tableMap));
-    if (guess) {
-        err.next_actions.push(`Did you mean '${guess}'? Run \`miaoda db schema list\` to see all tables.`);
-    }
+    err.next_actions.push(guess
+        ? `Did you mean '${guess}'? Run \`miaoda db schema list\` to see all tables.`
+        : "Run `miaoda db schema list` to see all tables.");
 }
 function enrichColumnNotExist(err, colMatch, tableMap) {
     const colName = colMatch[1];
     // TS RegExpMatchArray 数字索引类型 = string，但 optional capture group `(...)?`
     // 没匹配时运行时返 undefined；as cast 把这个事实告诉类型系统。
     const relation = colMatch[2];
-    const relationCols = relation !== undefined
-        ? tableMap[relation]
-        : undefined;
+    const relationCols = relation !== undefined ? tableMap[relation] : undefined;
     if (relation !== undefined && relationCols !== undefined) {
         // 指定了表 → 在该表的列里找
         const guess = (0, fuzzy_match_1.suggest)(colName, relationCols);
-        if (guess) {
-            err.next_actions.push(`Did you mean column '${guess}' in table '${relation}'?`);
-        }
-    }
-    else {
-        // 没指定表（CTE / 别名 / 子查询场景）→ 在所有表的列合集里找
-        const allCols = Array.from(new Set(Object.values(tableMap).flat()));
-        const guess = (0, fuzzy_match_1.suggest)(colName, allCols);
-        if (guess) {
-            err.next_actions.push(`Did you mean '${guess}'? Run \`miaoda db schema get <table>\` to see columns.`);
-        }
+        err.next_actions.push(guess
+            ? `Did you mean column '${guess}' in table '${relation}'?`
+            : `Run \`miaoda db schema get ${relation}\` to see all columns.`);
+        return;
     }
+    // 没指定表（CTE / 别名 / 子查询 / 单表 SELECT 但 PG 报错没带 relation 等场景）
+    // → 跨表所有列合集 fuzzy；没命中也给一句通用 hint，让用户知道下一步去哪查。
+    const allCols = Array.from(new Set(Object.values(tableMap).flat()));
+    const guess = (0, fuzzy_match_1.suggest)(colName, allCols);
+    err.next_actions.push(guess
+        ? `Did you mean '${guess}'? Run \`miaoda db schema get <table>\` to see columns.`
+        : "Run `miaoda db schema get <table>` to see all columns.");
 }
 /**
  * 扫整段 SQL 找一个看似"拼错的关键字"token：纯字母 + 长度 ≥ 3 + 不是已知 keyword
@@ -570,14 +576,18 @@ function extractTableFieldMap(s) {
 function enrichMultiStatementError(err, sql) {
     if (!(err instanceof error_1.AppError))
         return;
-    const partial = err.partial_results;
-    if (!Array.isArray(partial) || partial.length === 0)
+    // 用 SQL 文本判断是否多语句，而不是 partial.length——第一条就失败时
+    // partial_results=[]，但仍需输出统一的多语句 envelope 字段保持格式一致。
+    const total = countStatements(sql);
+    if (total <= 1)
         return;
-    // 把 SQLExecuteResult[] 转成 PRD 兼容的 completed 数组
+    const partial = Array.isArray(err.partial_results)
+        ? err.partial_results
+        : [];
     const completed = partial.map((r) => toMultiElement((0, index_1.parseSqlResult)(r)));
     err.completed = completed;
     err.rolled_back = inferRolledBack(completed);
-    err.total_statements = countStatements(sql);
+    err.total_statements = total;
     // pretty 模式（非 JSON）打 per-statement breakdown 到 stderr
     if (!(0, output_1.isJsonMode)()) {
         writeMultiStatementBreakdown(err, completed);
@@ -609,9 +619,7 @@ function inferRolledBack(completed) {
  * dollar-quoted（$$..$$）等高级形态——估错 ±1 不影响 hint 可读性。
  */
 function countStatements(sql) {
-    const stripped = sql
-        .replace(/'(?:''|[^'])*'/g, "''")
-        .replace(/"(?:""|[^"])*"/g, '""');
+    const stripped = sql.replace(/'(?:''|[^'])*'/g, "''").replace(/"(?:""|[^"])*"/g, '""');
     return stripped.split(/;+/).filter((s) => s.trim().length > 0).length;
 }
 /**

package/dist/cli/handlers/file/cp.js

@@ -48,13 +48,20 @@ const shared_1 = require("../../../cli/commands/shared");
 const colors_1 = require("../../../utils/colors");
 const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
 /**
- * 判断 src 是本地文件还是远程引用：
- * - src 本地 fs 可访问 → upload（dst 当 remote）
- * - 其他 → download（src 是 /path 或 file_name，由 resolveRemotePath 解析）
- *
- * `cp` 语义要求 src 必须存在；本地不存在就认为用户指向远程。不需要给 dst 猜方向。
+ * 判断 src 是本地路径还是远程引用——按 PRD `miaoda file cp` 规则的优先级：
+ *   1. `./` / `../` / `~/` 开头 + 裸文件名（不含 `/`）→ 本地路径（即使不存在）
+ *      给 handleUpload 把"不存在"准确抛成 FILE_SRC_NOT_FOUND，
+ *      避免回退到远程 download 输出 `FILE_NOT_FOUND` + "Run miaoda file ls"
+ *      这种与用户意图（上传）背离的引导。
+ *   2. `/` 开头：fs.existsSync 兜底——存在即本地（绝对路径上传），
+ *      不存在即远程 path（download，由 resolveRemotePath 处理）。
  */
 function isLocalSrc(src) {
+    if (src.startsWith("./") || src.startsWith("../") || src.startsWith("~/"))
+        return true;
+    if (!src.includes("/"))
+        return true;
+    // `/` 开头：可能是本地绝对路径，也可能是远程 path；交给 fs 探测。
     const expanded = expandHome(src);
     try {
         return node_fs_1.default.existsSync(expanded);
@@ -105,24 +112,38 @@ async function resolveRemotePath(appId, input) {
 async function handleUpload(appId, localRaw, remoteRaw, rename) {
     const localPath = expandHome(localRaw);
     if (!node_fs_1.default.existsSync(localPath) || !node_fs_1.default.statSync(localPath).isFile()) {
-        throw new error_1.AppError("FILE_SRC_NOT_FOUND", `Local file '${localRaw}' does not exist`);
+        throw new error_1.AppError("FILE_SRC_NOT_FOUND", `Local file '${localRaw}' does not exist`, {
+            // 引导本地路径自检；远程下载请用 `/path` 形态，避免裸名/相对路径误入上传分支
+            next_actions: ["Check the local file path; use `/path` prefix for remote download."],
+        });
     }
     const stat = node_fs_1.default.statSync(localPath);
     if (stat.size > MAX_UPLOAD_BYTES) {
         throw new error_1.AppError("FILE_SIZE_EXCEEDED", `File size ${(0, render_1.formatSize)(stat.size)} exceeds the 100 MB upload limit`, {
-            next_actions: [
-                "Split the file, or use the web console for large uploads.",
-            ],
+            next_actions: ["Split the file, or use the web console for large uploads."],
         });
     }
-    const fileName = rename ?? node_path_1.default.basename(localPath);
-    // remoteRaw 直接透传给服务端，由服务端按"是否以 / 结尾"区分两种语义：
-    //   - 以 / 结尾  → 目录前缀模式，服务端在前缀下生成 "<16位ID>.<扩展名>"
-    //                例：cp ./logo.png /images/  → /images/1858537546760216.png
-    //   - 不以 / 结尾 → 完整对象 key 模式（旧语义，原样落库）
-    //                例：cp ./photo.jpg /uploads/photo.jpg → /uploads/photo.jpg
-    // CLI 不做任何自动改写，避免猜测用户意图导致的 path 形态不可预测。
-    const remotePath = remoteRaw;
+    // PRD：path 末段**始终**由平台生成 16 位 ID 确保唯一，不受 dst 形态或
+    // --rename 影响；用户指定的 file_name 仅作为显示名（同目录下允许重名）。
+    // 因此 CLI 端把 dst 拆成"目录前缀 + file_name"两段：
+    //   - dst 以 / 结尾或为空  → 整段当目录前缀，file_name 用 --rename 或本地 basename
+    //                          例：cp ./logo.png /imgs/        → path=/imgs/<GID>.png, file_name=logo.png
+    //   - dst 不以 / 结尾      → 末段当 file_name，前段（含尾 /）当目录前缀
+    //                          例：cp ./1.jpg /post-covers/cover.jpg → path=/post-covers/<GID>.jpg, file_name=cover.jpg
+    // 这样无论用户怎么写 dst，都走服务端目录前缀模式（PreUpload `filePath`
+    // 末尾带 /），保证 path 全局唯一性，不会因用户指定了完整路径而退化成
+    // 完整对象 key 模式。--rename 始终覆盖 file_name 推断结果（PRD 优先级）。
+    let fileName;
+    let remotePath;
+    if (remoteRaw === "" || remoteRaw.endsWith("/")) {
+        fileName = rename ?? node_path_1.default.basename(localPath);
+        remotePath = remoteRaw;
+    }
+    else {
+        const lastSlash = remoteRaw.lastIndexOf("/");
+        fileName = rename ?? remoteRaw.slice(lastSlash + 1);
+        remotePath = remoteRaw.slice(0, lastSlash + 1);
+    }
     const contentType = detectMime(localPath);
     const result = await api.file.uploadFile({
         appId,

package/dist/cli/handlers/file/ls.js

@@ -101,9 +101,7 @@ async function handleFileLs(opts) {
         info.type,
         (0, render_1.formatTime)(info.uploaded_at, tty),
     ]);
-    const table = tty
-        ? (0, render_1.renderAlignedTable)(headers, rows)
-        : (0, render_1.renderTsv)(headers, rows);
+    const table = tty ? (0, render_1.renderAlignedTable)(headers, rows) : (0, render_1.renderTsv)(headers, rows);
     const hint = result.has_more && result.next_cursor
         ? `\n— ${String(result.items.length)} results. Next: --cursor ${result.next_cursor}`
         : "";

package/dist/cli/handlers/file/rm.js

@@ -170,7 +170,7 @@ async function handleFileRm(paths, opts) {
             results.push({
                 status: "ok",
                 input: entry?.input ?? p,
-                file_name: entry?.file_name ?? (p.split("/").pop() ?? p),
+                file_name: entry?.file_name ?? p.split("/").pop() ?? p,
                 path: p,
             });
         }

package/dist/cli/handlers/plugin/plugin-local.js

@@ -82,7 +82,9 @@ function parsePluginName(input) {
 function readPackageJson() {
     const pkgPath = getPackageJsonPath();
     if (!node_fs_1.default.existsSync(pkgPath)) {
-        throw new error_1.AppError("PKG_JSON_NOT_FOUND", "package.json not found in current directory", { next_actions: ["在应用项目根目录运行"] });
+        throw new error_1.AppError("PKG_JSON_NOT_FOUND", "package.json not found in current directory", {
+            next_actions: ["在应用项目根目录运行"],
+        });
     }
     const content = node_fs_1.default.readFileSync(pkgPath, "utf-8");
     return JSON.parse(content);
@@ -189,9 +191,14 @@ function installMissingDeps(deps) {
     if (deps.length === 0)
         return;
     (0, logger_1.log)("plugin", `Installing missing dependencies: ${deps.join(", ")}`);
-    const result = (0, node_child_process_1.spawnSync)("npm", ["install", ...deps, "--no-save", "--no-package-lock"], { cwd: getProjectRoot(), stdio: "inherit" });
+    const result = (0, node_child_process_1.spawnSync)("npm", ["install", ...deps, "--no-save", "--no-package-lock"], {
+        cwd: getProjectRoot(),
+        stdio: "inherit",
+    });
     if (result.error) {
-        throw new error_1.AppError("INTERNAL_NPM_FAILED", `npm install failed: ${result.error.message}`, { next_actions: ["确认本机已安装 npm，可 --verbose 查看执行详情"] });
+        throw new error_1.AppError("INTERNAL_NPM_FAILED", `npm install failed: ${result.error.message}`, {
+            next_actions: ["确认本机已安装 npm，可 --verbose 查看执行详情"],
+        });
     }
     if (result.status !== 0) {
         throw new error_1.AppError("INTERNAL_NPM_FAILED", `npm install failed with exit code ${String(result.status)}`, { next_actions: ["检查上方 npm 输出日志定位具体错误"] });
@@ -200,7 +207,9 @@ function installMissingDeps(deps) {
 function npmInstall(tgzPath) {
     const result = (0, node_child_process_1.spawnSync)("npm", ["install", tgzPath, "--no-save", "--no-package-lock", "--ignore-scripts"], { cwd: getProjectRoot(), stdio: "inherit" });
     if (result.error) {
-        throw new error_1.AppError("INTERNAL_NPM_FAILED", `npm install failed: ${result.error.message}`, { next_actions: ["确认本机已安装 npm，可 --verbose 查看执行详情"] });
+        throw new error_1.AppError("INTERNAL_NPM_FAILED", `npm install failed: ${result.error.message}`, {
+            next_actions: ["确认本机已安装 npm，可 --verbose 查看执行详情"],
+        });
     }
     if (result.status !== 0) {
         throw new error_1.AppError("INTERNAL_NPM_FAILED", `npm install failed with exit code ${String(result.status)}`, { next_actions: ["检查上方 npm 输出日志定位具体错误"] });
@@ -232,7 +241,9 @@ function listCapabilityIds() {
 function readCapability(id) {
     const filePath = node_path_1.default.join(getCapabilitiesDir(), `${id}.json`);
     if (!node_fs_1.default.existsSync(filePath)) {
-        throw new error_1.AppError("CAPABILITY_NOT_FOUND", `Capability not found: ${id}`, { next_actions: ["运行 miaoda plugin list 查看所有可用 capability id"] });
+        throw new error_1.AppError("CAPABILITY_NOT_FOUND", `Capability not found: ${id}`, {
+            next_actions: ["运行 miaoda plugin list 查看所有可用 capability id"],
+        });
     }
     try {
         const content = node_fs_1.default.readFileSync(filePath, "utf-8");
@@ -240,7 +251,9 @@ function readCapability(id) {
     }
     catch (error) {
         if (error instanceof SyntaxError) {
-            throw new error_1.AppError("INVALID_JSON", `Invalid JSON in capability file: ${id}.json`, { next_actions: [`检查 server/capabilities/${id}.json 的 JSON 语法`] });
+            throw new error_1.AppError("INVALID_JSON", `Invalid JSON in capability file: ${id}.json`, {
+                next_actions: [`检查 server/capabilities/${id}.json 的 JSON 语法`],
+            });
         }
         throw error;
     }
@@ -303,7 +316,9 @@ async function loadPlugin(pluginKey) {
     }
     catch (error) {
         if (error.code === "MODULE_NOT_FOUND") {
-            throw new error_1.AppError("PLUGIN_NOT_FOUND", `Plugin not installed: ${pluginKey}`, { next_actions: [`运行 miaoda plugin install ${pluginKey}`] });
+            throw new error_1.AppError("PLUGIN_NOT_FOUND", `Plugin not installed: ${pluginKey}`, {
+                next_actions: [`运行 miaoda plugin install ${pluginKey}`],
+            });
         }
         throw new error_1.AppError("INTERNAL_PLUGIN_LOAD_FAILED", `Failed to load plugin ${pluginKey}: ${error instanceof Error ? error.message : String(error)}`);
     }
@@ -314,8 +329,7 @@ async function hydrateCapability(capability) {
         if (manifest.actions.length === 0) {
             throw new error_1.AppError("INTERNAL_PLUGIN_LOAD_FAILED", `Plugin ${capability.pluginKey} has no actions defined`);
         }
-        const hasDynamic = manifest.actions.some((action) => isDynamicSchema(action.inputSchema) ||
-            isDynamicSchema(action.outputSchema));
+        const hasDynamic = manifest.actions.some((action) => isDynamicSchema(action.inputSchema) || isDynamicSchema(action.outputSchema));
         let pluginInstance = null;
         if (hasDynamic) {
             const plugin = await loadPlugin(capability.pluginKey);

package/dist/cli/handlers/plugin/plugin.js

@@ -44,7 +44,9 @@ const output_1 = require("../../../utils/output");
 const error_1 = require("../../../utils/error");
 const logger_1 = require("../../../utils/logger");
 const plugin_local_1 = require("./plugin-local");
-const log = (msg) => { (0, logger_1.log)("plugin", msg); };
+const log = (msg) => {
+    (0, logger_1.log)("plugin", msg);
+};
 // ── Install ──
 function syncActionPluginsRecord(name, version) {
     const plugins = (0, plugin_local_1.readActionPlugins)();
@@ -63,7 +65,9 @@ async function installOne(nameWithVersion) {
             if (actualVersion === requestedVersion) {
                 log(`${name}@${requestedVersion} already installed`);
                 syncActionPluginsRecord(name, actualVersion);
-                api.plugin.reportCreateInstanceEvent(name, actualVersion).catch(() => { });
+                api.plugin.reportCreateInstanceEvent(name, actualVersion).catch(() => {
+                    /* fire-and-forget */
+                });
                 return { name, version: actualVersion, success: true, skipped: true };
             }
         }
@@ -74,7 +78,9 @@ async function installOne(nameWithVersion) {
             if (actualVersion === targetVersion) {
                 log(`${name} already up to date (${actualVersion})`);
                 syncActionPluginsRecord(name, actualVersion);
-                api.plugin.reportCreateInstanceEvent(name, actualVersion).catch(() => { });
+                api.plugin.reportCreateInstanceEvent(name, actualVersion).catch(() => {
+                    /* fire-and-forget */
+                });
                 return { name, version: actualVersion, success: true, skipped: true };
             }
             log(`Found newer version: ${targetVersion} (installed: ${actualVersion ?? "none"})`);
@@ -106,8 +112,12 @@ async function installOne(nameWithVersion) {
         (0, plugin_local_1.writeActionPlugins)(plugins);
         const source = fromCache ? "from cache" : "downloaded";
         log(`Installed ${name}@${installedVersion} (${source})`);
-        api.plugin.reportInstallEvent(name, installedVersion).catch(() => { });
-        api.plugin.reportCreateInstanceEvent(name, installedVersion).catch(() => { });
+        api.plugin.reportInstallEvent(name, installedVersion).catch(() => {
+            /* fire-and-forget */
+        });
+        api.plugin.reportCreateInstanceEvent(name, installedVersion).catch(() => {
+            /* fire-and-forget */
+        });
         return { name, version: installedVersion, success: true };
     }
     catch (error) {
@@ -193,7 +203,9 @@ async function handlePluginUpdate(opts) {
 function handlePluginRemove(opts) {
     const { name } = (0, plugin_local_1.parsePluginName)(opts.name);
     if (!(0, plugin_local_1.isPluginInstalled)(name)) {
-        throw new error_1.AppError("PLUGIN_NOT_FOUND", `Plugin ${name} is not installed`, { next_actions: ["运行 miaoda plugin list-packages 查看已安装插件"] });
+        throw new error_1.AppError("PLUGIN_NOT_FOUND", `Plugin ${name} is not installed`, {
+            next_actions: ["运行 miaoda plugin list-packages 查看已安装插件"],
+        });
     }
     (0, plugin_local_1.removePluginDirectory)(name);
     const plugins = (0, plugin_local_1.readActionPlugins)();
@@ -263,7 +275,9 @@ async function handlePluginInit() {
 // ── List (capability configs) ──
 async function handlePluginList(opts) {
     if (!(0, plugin_local_1.capabilitiesDirExists)()) {
-        throw new error_1.AppError("CAPABILITIES_DIR_NOT_FOUND", "server/capabilities directory not found", { next_actions: ["当前目录必须是含 server/capabilities/ 的应用项目"] });
+        throw new error_1.AppError("CAPABILITIES_DIR_NOT_FOUND", "server/capabilities directory not found", {
+            next_actions: ["当前目录必须是含 server/capabilities/ 的应用项目"],
+        });
     }
     if (opts.id) {
         const capability = (0, plugin_local_1.readCapability)(opts.id);

package/dist/cli/help.js

@@ -115,7 +115,9 @@ class MiaodaHelp extends commander_1.Help {
         out.push("Usage:", `  ${helper.commandUsage(cmd)}`, "");
         // 3. Commands（仅父级命令组有，spec 要求 Commands 在 Flags 前）
         //    spec 不展示 Arguments 段，参数说明放在 description 文本里
-        const subs = helper.visibleCommands(cmd).map((c) => formatItem(helper.subcommandTerm(c), helper.subcommandDescription(c)));
+        const subs = helper
+            .visibleCommands(cmd)
+            .map((c) => formatItem(helper.subcommandTerm(c), helper.subcommandDescription(c)));
         if (subs.length) {
             out.push("Commands:", formatList(subs), "");
         }
@@ -125,7 +127,8 @@ class MiaodaHelp extends commander_1.Help {
         //    - `-h, --help` 永远不放 Flags 段，统一放 Global Flags（spec 约定）
         const isParent = subs.length > 0;
         if (!isRoot && !isParent) {
-            const opts = helper.visibleOptions(cmd)
+            const opts = helper
+                .visibleOptions(cmd)
                 .filter((o) => !isHelpOption(o))
                 .map((o) => formatItem(helper.optionTerm(o), helper.optionDescription(o)));
             if (opts.length) {

package/dist/utils/output.js

@@ -23,7 +23,7 @@ const SERVER_ERROR_HINTS = {
     // SELECT 结果集超过 1000 行硬拦：spec 多行引导。
     // key 用 BIZ_ERR_MAP 映射后的语义 code（不是原始服务端 k_dl_xxx），保持
     // 与 help / 文档里宣传的 RESULT_SET_TOO_LARGE 一致。
-    "RESULT_SET_TOO_LARGE": [
+    RESULT_SET_TOO_LARGE: [
         "Add `LIMIT <n>` to your SQL to narrow the result.",
         "For counts, use `SELECT count(*) FROM ...`; for aggregation, use GROUP BY with filters.",
     ],
@@ -90,9 +90,10 @@ function emitError(err) {
         if (typeof info.statement_index === "number") {
             const k = info.statement_index + 1;
             const n = info.total_statements;
-            errorLine += typeof n === "number" && n > 0
-                ? ` (at statement ${String(k)} of ${String(n)})`
-                : ` (at statement ${String(k)})`;
+            errorLine +=
+                typeof n === "number" && n > 0
+                    ? ` (at statement ${String(k)} of ${String(n)})`
+                    : ` (at statement ${String(k)})`;
         }
         process.stderr.write(errorLine + "\n");
         // 多行 hint：第一行带 "hint:" 标签，后续行用 8 空格缩进对齐 "  hint: " 之后的列。

package/dist/utils/render.js

@@ -81,20 +81,21 @@ const ANSI_SGR_RE = /\[[0-9;]*m/g;
  * 不实现合字 / 零宽字符（ZWJ / 变体选择符）等极端情况，CLI 表格场景够用。
  */
 function charWidth(cp) {
-    if ((cp >= 0x1100 && cp <= 0x115F) || // Hangul Jamo
-        cp === 0x2329 || cp === 0x232A ||
-        (cp >= 0x2E80 && cp <= 0x303E) || // CJK Radicals / Punctuation
-        (cp >= 0x3041 && cp <= 0x33FF) || // Hiragana / Katakana / CJK Symbols
-        (cp >= 0x3400 && cp <= 0x4DBF) || // CJK Ext A
-        (cp >= 0x4E00 && cp <= 0x9FFF) || // CJK Unified
-        (cp >= 0xA000 && cp <= 0xA4CF) || // Yi
-        (cp >= 0xAC00 && cp <= 0xD7A3) || // Hangul Syllables
-        (cp >= 0xF900 && cp <= 0xFAFF) || // CJK Compat Ideographs
-        (cp >= 0xFE30 && cp <= 0xFE4F) || // CJK Compat Forms
-        (cp >= 0xFF00 && cp <= 0xFF60) || // Fullwidth Forms
-        (cp >= 0xFFE0 && cp <= 0xFFE6) ||
-        (cp >= 0x20000 && cp <= 0x2FFFD) || // CJK Ext B-F
-        (cp >= 0x30000 && cp <= 0x3FFFD) // CJK Ext G-H
+    if ((cp >= 0x1100 && cp <= 0x115f) || // Hangul Jamo
+        cp === 0x2329 ||
+        cp === 0x232a ||
+        (cp >= 0x2e80 && cp <= 0x303e) || // CJK Radicals / Punctuation
+        (cp >= 0x3041 && cp <= 0x33ff) || // Hiragana / Katakana / CJK Symbols
+        (cp >= 0x3400 && cp <= 0x4dbf) || // CJK Ext A
+        (cp >= 0x4e00 && cp <= 0x9fff) || // CJK Unified
+        (cp >= 0xa000 && cp <= 0xa4cf) || // Yi
+        (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul Syllables
+        (cp >= 0xf900 && cp <= 0xfaff) || // CJK Compat Ideographs
+        (cp >= 0xfe30 && cp <= 0xfe4f) || // CJK Compat Forms
+        (cp >= 0xff00 && cp <= 0xff60) || // Fullwidth Forms
+        (cp >= 0xffe0 && cp <= 0xffe6) ||
+        (cp >= 0x20000 && cp <= 0x2fffd) || // CJK Ext B-F
+        (cp >= 0x30000 && cp <= 0x3fffd) // CJK Ext G-H
     ) {
         return 2;
     }
@@ -126,9 +127,15 @@ function renderAlignedTable(headers, rows) {
         return w;
     });
     const lines = [];
-    lines.push(headers.map((h, i) => colors_1.c.header(padVisibleEnd(h, colWidths[i]))).join("  ").trimEnd());
+    lines.push(headers
+        .map((h, i) => colors_1.c.header(padVisibleEnd(h, colWidths[i])))
+        .join("  ")
+        .trimEnd());
     for (const row of rows) {
-        lines.push(row.map((cell, i) => padVisibleEnd(cell || "", colWidths[i])).join("  ").trimEnd());
+        lines.push(row
+            .map((cell, i) => padVisibleEnd(cell || "", colWidths[i]))
+            .join("  ")
+            .trimEnd());
     }
     return lines.join("\n");
 }
@@ -149,9 +156,7 @@ function renderKeyValue(pairs, isTty) {
         return pairs.map(([k, v]) => `${k}\t${v}`).join("\n");
     }
     const keyWidth = Math.max(...pairs.map(([k]) => k.length));
-    return pairs
-        .map(([k, v]) => `${colors_1.c.header(k.padStart(keyWidth))}:  ${v}`)
-        .join("\n");
+    return pairs.map(([k, v]) => `${colors_1.c.header(k.padStart(keyWidth))}:  ${v}`).join("\n");
 }
 /** 通用 isTTY 判定（stdout 是否交互终端）。Node 运行时 isTTY 为 true 或 undefined；TS 类型上 tty.WriteStream 定义为固定 true，绕开做运行时判断。 */
 function isStdoutTty() {
@@ -167,11 +172,16 @@ function parseDuration(input) {
     const n = Number(m[1]);
     const unit = m[2] || "s";
     switch (unit) {
-        case "s": return n;
-        case "m": return n * 60;
-        case "h": return n * 3600;
-        case "d": return n * 86400;
-        default: return n;
+        case "s":
+            return n;
+        case "m":
+            return n * 60;
+        case "h":
+            return n * 3600;
+        case "d":
+            return n * 86400;
+        default:
+            return n;
     }
 }
 /** 解析 size 字符串 `1MB` / `500KB` / `1GB` → 字节。 */
@@ -183,10 +193,15 @@ function parseSize(input) {
     const n = Number(m[1]);
     const unit = (m[2] || "B").toUpperCase();
     switch (unit) {
-        case "B": return Math.round(n);
-        case "KB": return Math.round(n * 1024);
-        case "MB": return Math.round(n * 1024 * 1024);
-        case "GB": return Math.round(n * 1024 * 1024 * 1024);
-        default: return Math.round(n);
+        case "B":
+            return Math.round(n);
+        case "KB":
+            return Math.round(n * 1024);
+        case "MB":
+            return Math.round(n * 1024 * 1024);
+        case "GB":
+            return Math.round(n * 1024 * 1024 * 1024);
+        default:
+            return Math.round(n);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.1-alpha.e70b415",
+  "version": "0.1.1-alpha.eccb0b7",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {
@@ -35,7 +35,12 @@
     "@typescript-eslint/parser": "^8.58.2",
     "@vitest/coverage-v8": "^4.1.4",
     "eslint": "^9.25.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-boundaries": "^6.0.2",
+    "eslint-plugin-import": "^2.32.0",
     "husky": "^9.1.7",
+    "prettier": "^3.8.3",
     "tsc-alias": "^1.8.11",
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",
@@ -46,6 +51,8 @@
     "build": "bash scripts/build.sh",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "lint": "eslint src/ --max-warnings 0",
+    "format": "prettier --write src/",
+    "format:check": "prettier --check src/",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:integration": "vitest run --config vitest.integration.config.ts",