@lark-apaas/miaoda-cli 0.1.0-alpha.465bdb8 → 0.1.0-alpha.5f650e8

package/dist/api/db/api.js

@@ -24,7 +24,9 @@ async function execSql(opts) {
     const url = (0, client_1.buildInnerUrl)(opts.appId, "/db/sql", {
         dbBranch: opts.dbBranch,
     });
+    const start = Date.now();
     const response = await client.post(url, { sql: opts.sql });
+    (0, client_1.traceHttp)("POST", url, start, response);
     if (!response.ok) {
         // 4xx / 5xx：尝试解析 body 取 status_code 映射业务错误
         let body = null;
@@ -57,7 +59,9 @@ async function getSchema(opts) {
         includeStats: opts.includeStats ? "true" : undefined,
         dbBranch: opts.dbBranch,
     });
+    const start = Date.now();
     const response = await client.get(url);
+    (0, client_1.traceHttp)("GET", url, start, response);
     if (!response.ok) {
         let body = null;
         try {
@@ -73,28 +77,32 @@ async function getSchema(opts) {
     const body = (await response.json());
     return (0, client_1.extractData)(body);
 }
-// ── db data import → InnerImportData ──
+// ── db data import → InnerAdminImportData ──
 /**
  * 导入文件。
- * 后端：POST /v1/dataloom/app/{appId}/data/import?tableName=...&format=csv|json&dbBranch=main
+ * 后端：POST /v1/dataloom/app/{appId}/data/import
  *
- * Body 为原始文件字节（不走 JSON envelope）。
+ * 全字段走 JSON body envelope（idl-larkgw 36125a2f）：
+ *   {tableName, format, records, dbBranch?}
+ *
+ * `records` 字段携带 CSV / JSON 文本内容（utf8 字符串），与 dataloom 上
+ * Import/ExportAdminRecords 命名风格对齐。CLI 端把 Buffer 解码成 utf8
+ * 字符串后塞进 envelope 即可。
  */
 async function importData(opts) {
     const client = (0, http_1.getHttpClient)();
-    const url = (0, client_1.buildInnerUrl)(opts.appId, "/data/import", {
+    const url = (0, client_1.buildInnerUrl)(opts.appId, "/data/import");
+    const reqBody = {
         tableName: opts.tableName,
         format: opts.format,
-        dbBranch: opts.dbBranch,
-    });
-    const contentType = opts.format === "csv" ? "text/csv" : "application/json";
-    const ab = opts.body.buffer.slice(opts.body.byteOffset, opts.body.byteOffset + opts.body.byteLength);
-    const response = await client.request({
-        method: "POST",
-        url,
-        headers: { "Content-Type": contentType },
-        body: ab,
-    });
+        records: opts.body.toString("utf8"),
+    };
+    if (opts.dbBranch !== undefined && opts.dbBranch !== "") {
+        reqBody.dbBranch = opts.dbBranch;
+    }
+    const start = Date.now();
+    const response = await client.post(url, reqBody);
+    (0, client_1.traceHttp)("POST", url, start, response);
     if (!response.ok) {
         let body = null;
         try {
@@ -107,31 +115,37 @@ async function importData(opts) {
             (0, client_1.extractData)(body);
         throw new error_1.HttpError(response.status, url, `Failed to import data: ${String(response.status)} ${response.statusText}`);
     }
-    // 后端 InnerImportData 响应里 data 直接返 {tableName, rows, durationMs}
+    // 后端 InnerAdminImportData 响应里 data 直接返 {tableName, recordCount, durationMs}
     const body = (await response.json());
     const data = (0, client_1.extractData)(body);
     return {
         tableName: data.tableName ?? opts.tableName,
-        rows: data.rows ?? 0,
+        recordCount: data.recordCount ?? 0,
         durationMs: data.durationMs ?? 0,
     };
 }
-// ── db data export → InnerExportData ──
+// ── db data export → InnerAdminExportData ──
 /**
  * 导出数据。
- * 后端：POST /v1/dataloom/app/{appId}/data/export?tableName=...&format=csv|json&dbBranch=main
+ * 后端：POST /v1/dataloom/app/{appId}/data/export?tableName=...&format=csv|json&limit=5000&dbBranch=main
  *
- * 响应 body 为原始 CSV/JSON 字节（不走 envelope）。错误仍通过 HTTP 4xx/5xx + BaseResp 传达。
+ * 所有参数（含 limit）均按 IDL `api.query` 走 query string；HTTP 方法是 POST（对齐
+ * inner_api 网关插件路由约定，与 InnerAdminExecuteSQL 同 method）。请求体为空。
+ * 响应 body 为原始 CSV/JSON 字节，RecordCount 通过响应头 `X-Miaoda-Record-Count`
+ * 回传，错误仍走 HTTP 4xx/5xx + envelope。
  */
 async function exportData(opts) {
     const client = (0, http_1.getHttpClient)();
     const url = (0, client_1.buildInnerUrl)(opts.appId, "/data/export", {
         tableName: opts.tableName,
         format: opts.format,
+        limit: String(opts.limit ?? 5000),
         dbBranch: opts.dbBranch,
     });
-    const reqBody = { limit: opts.limit ?? 5000 };
-    const response = await client.post(url, reqBody);
+    // POST + 空 body：所有业务参数都在 query 里
+    const start = Date.now();
+    const response = await client.request({ method: "POST", url });
+    (0, client_1.traceHttp)("POST", url, start, response);
     if (!response.ok) {
         // 错误路径：body 是 JSON envelope
         let body = null;
@@ -145,7 +159,8 @@ async function exportData(opts) {
             (0, client_1.extractData)(body);
         throw new error_1.HttpError(response.status, url, `Failed to export data: ${String(response.status)} ${response.statusText}`);
     }
-    // 成功路径：响应 body 是原始 CSV/JSON 字节
+    // 成功路径：响应 body 通常是原始 CSV/JSON 字节，但部分错误场景下网关会返
+    // HTTP 200 + JSON envelope（status_code != "0"），需要在这里嗅探兜底。
     const contentType = response.headers.get("Content-Type") ??
         (opts.format === "csv" ? "text/csv" : "application/json");
     const ab = await response.arrayBuffer();
@@ -153,10 +168,33 @@ async function exportData(opts) {
     if (buf.length === 0) {
         throw new error_1.AppError("INTERNAL_DB_ERROR", "Empty export response body");
     }
+    // Envelope sniff：HTTP 200 + Content-Type 为 application/json + body 解析得到
+    // InnerEnvelope 且 status_code 非 "0" 时，按业务错误抛出。
+    // 仅 CSV 格式做 sniff —— JSON 格式正常成功响应也是 application/json，会误判。
+    if (opts.format === "csv" && /application\/json/i.test(contentType)) {
+        try {
+            const parsed = JSON.parse(buf.toString("utf8"));
+            if (parsed.status_code != null && parsed.status_code !== "0") {
+                // 复用 extractData 的错误映射逻辑（throw AppError）
+                (0, client_1.extractData)(parsed);
+            }
+        }
+        catch (err) {
+            // 已经被 extractData 抛成 AppError → 透传；否则 JSON.parse 失败说明 body
+            // 真的是 CSV 文本，继续按成功流程走
+            if (err instanceof error_1.AppError)
+                throw err;
+        }
+    }
+    // 后端通过响应头回传记录数（避免污染 body）；header 缺失或解析失败 → undefined
+    const recordCountHeader = response.headers.get("X-Miaoda-Record-Count");
+    const parsedCount = recordCountHeader != null ? Number(recordCountHeader) : NaN;
+    const recordCount = Number.isFinite(parsedCount) && parsedCount >= 0 ? parsedCount : undefined;
     return {
         tableName: opts.tableName,
         format: opts.format,
         contentType,
         body: buf,
+        recordCount,
     };
 }

package/dist/api/db/client.js

@@ -1,10 +1,45 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SQLSTATE_MAP = void 0;
+exports.traceHttp = traceHttp;
 exports.ensureInnerSuccess = ensureInnerSuccess;
 exports.extractData = extractData;
 exports.buildInnerUrl = buildInnerUrl;
 const error_1 = require("../../utils/error");
+const logger_1 = require("../../utils/logger");
+/**
+ * 输出一条 HTTP 调试日志（仅 --verbose 模式生效）。
+ *
+ * 主要用于把后端返回的 `x-tt-logid` 透出给用户，方便拿这个 id 去 server / 网关日志里
+ * 直接定位本次请求的 `[MiaodaCLI.metric]` 行与上下游 trace。
+ *
+ * 使用约定：
+ *   const start = Date.now();
+ *   const response = await client.post(url, body);
+ *   traceHttp("POST", url, start, response);
+ *   // 或错误路径：traceHttp("POST", url, start, err.response, err)
+ */
+function traceHttp(method, url, start, response, err) {
+    // debug() 内部已判断 verbose 开关，这里不重复判断；保持调用点轻量
+    try {
+        const cost = Date.now() - start;
+        const status = response?.status ?? 0;
+        const logid = response?.headers?.get?.("x-tt-logid") ?? "-";
+        if (err !== undefined) {
+            const errMsg = err instanceof Error
+                ? err.message
+                : typeof err === "string"
+                    ? err
+                    : JSON.stringify(err);
+            (0, logger_1.debug)(`http ${method} ${url} ${String(status)} cost=${String(cost)}ms x-tt-logid=${logid} err=${errMsg}`);
+            return;
+        }
+        (0, logger_1.debug)(`http ${method} ${url} ${String(status)} cost=${String(cost)}ms x-tt-logid=${logid}`);
+    }
+    catch {
+        // debug 失败不应影响业务，吞掉
+    }
+}
 /**
  * 校验 dataloom InnerAPI 响应的 envelope。
  *

package/dist/api/file/api.js

@@ -280,6 +280,7 @@ async function uploadFile(opts) {
         // Node 20+ 内置 fetch 运行时接受 Buffer，但 TS 的 BodyInit 要求更严格的类型；
         // 这里复制到独立 ArrayBuffer 以满足 lib.dom.d.ts 的 BodyInit 约束
         const ab = body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength);
+        const uploadStart = Date.now();
         const res = await fetch(pre.uploadURL, {
             method: "PUT",
             headers: {
@@ -288,6 +289,7 @@ async function uploadFile(opts) {
             },
             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)}`);
         }
@@ -364,12 +366,15 @@ async function signDownload(opts) {
  */
 async function downloadFile(opts) {
     let res;
+    const downloadStart = Date.now();
     try {
         res = await fetch(opts.signedURL);
     }
     catch (err) {
+        (0, logger_1.debug)(`http GET <download-cdn> 0 cost=${String(Date.now() - downloadStart)}ms err=${err instanceof Error ? err.message : String(err)}`);
         throw new error_1.AppError("FILE_DOWNLOAD_FAILED", `Download GET failed: ${err instanceof Error ? err.message : String(err)}`);
     }
+    (0, logger_1.debug)(`http GET <download-cdn> ${String(res.status)} cost=${String(Date.now() - downloadStart)}ms`);
     if (!res.ok) {
         throw new error_1.AppError("FILE_DOWNLOAD_FAILED", `Download failed with status ${String(res.status)}`);
     }

package/dist/api/file/client.js

@@ -8,7 +8,34 @@ exports.doPost = doPost;
 exports.doRequest = doRequest;
 const http_1 = require("../../utils/http");
 const error_1 = require("../../utils/error");
+const logger_1 = require("../../utils/logger");
 const http_client_1 = require("@lark-apaas/http-client");
+/**
+ * 输出一条 HTTP 调试日志（仅 --verbose 模式生效）。
+ *
+ * 主要用于把后端返回的 `x-tt-logid` 透出给用户，方便拿这个 id 去 server / 网关日志里
+ * 直接定位本次请求的 `[MiaodaCLI.metric]` 行与上下游 trace。
+ */
+function traceHttp(method, url, start, response, err) {
+    try {
+        const cost = Date.now() - start;
+        const status = response?.status ?? 0;
+        const logid = response?.headers?.get?.("x-tt-logid") ?? "-";
+        if (err !== undefined) {
+            const errMsg = err instanceof Error
+                ? err.message
+                : typeof err === "string"
+                    ? err
+                    : JSON.stringify(err);
+            (0, logger_1.debug)(`http ${method} ${url} ${String(status)} cost=${String(cost)}ms x-tt-logid=${logid} err=${errMsg}`);
+            return;
+        }
+        (0, logger_1.debug)(`http ${method} ${url} ${String(status)} cost=${String(cost)}ms x-tt-logid=${logid}`);
+    }
+    catch {
+        // debug 失败不应影响业务，吞掉
+    }
+}
 /** 进程内 bucket 缓存：{appId: bucketId}。不跨进程。 */
 const bucketCache = new Map();
 /**
@@ -130,33 +157,42 @@ async function mapHttpError(err, opts) {
  * 通过第三个参数显式传入 getRuntimeHttpClient() 切换。
  */
 async function doGet(url, opts = {}, client = (0, http_1.getHttpClient)()) {
+    const start = Date.now();
     try {
         const response = await client.get(url);
+        traceHttp("GET", url, start, response);
         return (await response.json());
     }
     catch (err) {
+        traceHttp("GET", url, start, err instanceof http_client_1.HttpError ? err.response : undefined, err);
         await mapHttpError(err, opts);
         throw err; // 不可达，mapHttpError 必定 throw
     }
 }
 /** 包一层 client.post + HttpError 统一映射。默认 admin innerapi，可显式切 runtime。 */
 async function doPost(url, body, opts = {}, client = (0, http_1.getHttpClient)()) {
+    const start = Date.now();
     try {
         const response = await client.post(url, body);
+        traceHttp("POST", url, start, response);
         return (await response.json());
     }
     catch (err) {
+        traceHttp("POST", url, start, err instanceof http_client_1.HttpError ? err.response : undefined, err);
         await mapHttpError(err, opts);
         throw err;
     }
 }
 /** 包一层 client.request + HttpError 统一映射（DELETE 带 body 的场景）。 */
 async function doRequest(cfg, opts = {}, client = (0, http_1.getHttpClient)()) {
+    const start = Date.now();
     try {
         const response = await client.request(cfg);
+        traceHttp(cfg.method, cfg.url, start, response);
         return (await response.json());
     }
     catch (err) {
+        traceHttp(cfg.method, cfg.url, start, err instanceof http_client_1.HttpError ? err.response : undefined, err);
         await mapHttpError(err, opts);
         throw err;
     }

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

@@ -2,74 +2,177 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerDbCommands = registerDbCommands;
 const index_1 = require("../../../cli/handlers/db/index");
-const shared_1 = require("../../../cli/commands/shared");
 function registerDbCommands(program) {
     const dbCmd = program
         .command("db")
-        .description("数据操作：SQL 执行、表结构查询、数据导入导出");
+        .description("数据库操作：执行 SQL、查看表结构、导入导出数据")
+        .usage("<command> [flags]");
     dbCmd.action(() => {
         dbCmd.outputHelp();
     });
+    dbCmd.addHelpText("after", `
+Examples:
+  $ miaoda db sql "SELECT * FROM users LIMIT 5"
+  $ miaoda db schema list
+  $ miaoda db schema get users
+  $ miaoda db data import users.csv
+  $ miaoda db data export users
+`);
     dbCmd
         .command("sql")
-        .description("执行任意 SQL（SELECT / DML / DDL / TCL / EXPLAIN）；query 省略时读 stdin")
-        .argument("[query]", "要执行的 SQL 语句；省略时从 stdin 读取")
-        .addOption((0, shared_1.appIdOption)())
-        .option("--env <env>", "目标环境（main / dev）；不传由后端按多环境状态兜底")
+        .description("执行 SQL 语句（DDL/DML/SELECT 任意 PG 语句）")
+        .usage("[query] [flags]")
+        .argument("[query]", "SQL 语句；省略时从 stdin 读取")
+        .option("--env <env>", "目标环境（main / dev），缺省按多环境状态兜底")
         .action(async (query, opts) => {
         await (0, index_1.handleDbSql)(query, opts);
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - DML 单语句 affectedRows 与 SELECT 单语句返回行数上限均为 1000，超过即拒绝
+  - 多语句以 ; 分隔，失败时错误响应携带 statement_index 定位失败位置
+  - 支持用户自管事务 BEGIN / COMMIT / ROLLBACK；事务中途失败服务端会自动 ROLLBACK
+
+Examples:
+  $ miaoda db sql "SELECT * FROM users LIMIT 3"
+  ✓ 3 rows
+
+  $ miaoda db sql "CREATE TABLE t(id int)"
+  ✓ Statement executed
+
+  $ cat migration.sql | miaoda db sql
+  ✓ 5 statements executed
+
+  $ miaoda db sql "SELECT count(*) FROM orders" --json
+  [{"count": 1234}]
+
+  # 报错：多语句中第 1 条失败
+  $ miaoda db sql "CREATE TABLE t(id int); SELECT * FROM no_such"
+  Error: TABLE_NOT_FOUND at statement 1
+    hint: Run \`miaoda db schema list\` to see existing tables.
+`);
     // schema 二级资源分组
     const schemaCmd = dbCmd
         .command("schema")
-        .description("表结构查询");
+        .description("查看表结构（list / get）")
+        .usage("<command> [flags]");
     schemaCmd.action(() => {
         schemaCmd.outputHelp();
     });
     schemaCmd
         .command("list")
-        .description("列出应用所有表（rows / size / columns / updated_at）")
-        .addOption((0, shared_1.appIdOption)())
-        .option("--env <env>", "目标环境（main / dev）；不传由后端按多环境状态兜底")
+        .description("列出当前应用的所有表（含行数估算、占用大小、列数）")
+        .usage("[flags]")
+        .option("--env <env>", "目标环境（main / dev），缺省按多环境状态兜底")
         .action(async (opts) => {
         await (0, index_1.handleDbSchemaList)(opts);
-    });
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda db schema list
+  name      rows  size_bytes  columns
+  users     120   65536       6
+  orders    5400  327680      9
+
+  $ miaoda db schema list --json | jq '.[].name'
+  "users"
+  "orders"
+
+  $ miaoda db schema list --env main
+`);
     schemaCmd
         .command("get")
-        .description("查看单表结构（字段 / 索引 / DDL）")
-        .argument("<table>", "表名")
-        .addOption((0, shared_1.appIdOption)())
-        .option("--ddl", "TTY 下强制输出完整 DDL 而非结构化概览")
-        .option("--env <env>", "目标环境（main / dev）；不传由后端按多环境状态兜底")
+        .description("查看单张表的字段、索引与建表语句；判断表是否存在也用这条")
+        .usage("<table> [flags]")
+        .argument("<table>", "表名（不带 schema 前缀）")
+        .option("--ddl", "只输出 CREATE TABLE 语句，便于复制 / 备份")
+        .option("--env <env>", "目标环境（main / dev），缺省按多环境状态兜底")
         .action(async (table, opts) => {
         await (0, index_1.handleDbSchemaGet)(table, opts);
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - 用作"判断表是否存在"探针时：退出码 0 → 表存在；错误码 TABLE_NOT_FOUND → 表不存在
+
+Examples:
+  $ miaoda db schema get users
+  CREATE TABLE users (
+    id uuid NOT NULL DEFAULT gen_random_uuid(),
+    ...
+  );
+
+  $ miaoda db schema get users --ddl
+  CREATE TABLE users ( ... );
+
+  $ miaoda db schema get users --json
+  {"name":"users","columns":[...],"indexes":[...]}
+
+  # 报错：表不存在
+  $ miaoda db schema get no_such
+  Error: TABLE_NOT_FOUND
+    hint: Run \`miaoda db schema list\` to see all tables.
+`);
     // data 二级资源分组
     const dataCmd = dbCmd
         .command("data")
-        .description("数据导入 / 导出");
+        .description("批量导入与导出数据（import / export）")
+        .usage("<command> [flags]");
     dataCmd.action(() => {
         dataCmd.outputHelp();
     });
     dataCmd
         .command("import")
-        .description("从 CSV / JSON 文件导入数据（P0：≤ 1 MB / ≤ 5000 行，单事务原子）")
-        .argument("<file>", "本地文件路径")
-        .addOption((0, shared_1.appIdOption)())
-        .option("--table <name>", "目标表名；省略时按文件名推断")
-        .option("--format <fmt>", "csv | json；省略时按文件扩展名推断")
+        .description("把本地 CSV / JSON 文件导入到表（单次最多 5000 行 / 1 MB，全部成功或全部回滚）")
+        .usage("<file> [flags]")
+        .argument("<file>", "本地文件路径（CSV 或 JSON）")
+        .option("--table <name>", "目标表名；缺省按文件名（去扩展名）推断")
+        .option("--format <fmt>", "文件格式 csv / json；缺省按文件扩展名推断")
         .action(async (file, opts) => {
         await (0, index_1.handleDbDataImport)(file, opts);
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - 单次最多 5000 行 / 1 MB；超过请拆批
+  - 任一行失败 → 整批回滚，错误响应给出失败行号 + 原因
+
+Examples:
+  $ miaoda db data import users.csv
+  ✓ Imported 120 rows into 'users'
+
+  $ miaoda db data import data.json --table customers
+  ✓ Imported 240 rows into 'customers'
+
+  $ miaoda db data import dump --table orders --format csv
+  ✓ Imported 80 rows into 'orders'
+
+  # 报错：第 5 行格式错误，整批回滚
+  $ miaoda db data import broken.csv
+  Error: ROW_PARSE_FAILED at row 5
+    hint: Check column count and value types match the table schema.
+`);
     dataCmd
         .command("export")
-        .description("导出整表到 CSV / JSON（P0：≤ 1 MB / ≤ 5000 行）")
-        .argument("<table>", "表名")
-        .addOption((0, shared_1.appIdOption)())
-        .option("--format <fmt>", "csv | json；默认 csv")
-        .option("-f, --file <path>", "输出文件路径；默认 <table>.<format>")
-        .option("--limit <n>", "最多导出行数（≤ 5000）")
+        .description("把整张表导出为 CSV / JSON 文件（单次最多 5000 行 / 1 MB）")
+        .usage("<table> [flags]")
+        .argument("<table>", "表名（不带 schema 前缀）")
+        .option("--format <fmt>", "导出格式 csv / json，默认 csv")
+        .option("-f, --file <path>", "输出文件路径，默认 <table>.<format>")
+        .option("--limit <n>", "最多导出行数（不超过 5000）")
         .action(async (table, opts) => {
         await (0, index_1.handleDbDataExport)(table, opts);
-    });
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda db data export users
+  ✓ Exported 120 rows to ./users.csv
+
+  $ miaoda db data export users --format json
+  ✓ Exported 120 rows to ./users.json
+
+  $ miaoda db data export users -f /tmp/u.csv
+  ✓ Exported 120 rows to /tmp/u.csv
+
+  $ miaoda db data export users --limit 1000
+  ✓ Exported 1000 rows to ./users.csv
+`);
 }

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

@@ -2,66 +2,163 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerFileCommands = registerFileCommands;
 const index_1 = require("../../../cli/handlers/file/index");
-const shared_1 = require("../../../cli/commands/shared");
+const error_1 = require("../../../utils/error");
+/**
+ * commander option 校验器：把 --limit <n> 解析成正整数（≥1）。
+ * 默认值（如 "50"）会先经过这里被规范化成 number。
+ * 非整数 / 负数 / 0 抛 AppError("ARGS_INVALID")，由 main.ts 的全局 catch
+ * 走 emitError，同时 process.exitCode 由 commander 自然为 1。
+ */
+function parsePositiveInt(raw) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1) {
+        throw new error_1.AppError("ARGS_INVALID", `--limit must be a positive integer (got '${raw}')`);
+    }
+    return n;
+}
 function registerFileCommands(program) {
     const fileCmd = program
         .command("file")
-        .description("文件操作：上传、下载、删除、查询");
+        .description("文件操作：上传、下载、删除、查询")
+        .usage("<command> [flags]");
     fileCmd.action(() => {
         fileCmd.outputHelp();
     });
+    fileCmd.addHelpText("after", `
+Examples:
+  $ miaoda file ls
+  $ miaoda file stat report.pdf
+  $ miaoda file cp report.pdf /uploads/
+  $ miaoda file cp /uploads/report.pdf .
+  $ miaoda file sign report.pdf
+  $ miaoda file rm a.txt b.txt -y
+`);
     fileCmd
         .command("ls")
-        .description("列出应用下的文件")
-        .argument("[query]", "可选筛选值：形似 /path、包含 / 或 16+位 fileKey 时按 path 精确匹配；否则按 file_name 精确匹配")
-        .addOption((0, shared_1.appIdOption)())
-        .option("--path <path>", "按 path 精确匹配（跳过自动识别）")
-        .option("--name <name>", "按 file_name 精确匹配（跳过自动识别）")
-        .option("--type <mime>", "按 MIME 类型过滤（精确匹配）")
-        .option("--size-gt <size>", "大小大于，支持 B/KB/MB/GB")
-        .option("--size-lt <size>", "大小小于")
-        .option("--uploaded-since <time>", "上传时间晚于（ISO 8601）")
-        .option("--limit <n>", "返回条数上限", "50")
-        .option("--cursor <token>", "分页游标")
-        .option("--all", "自动翻页聚合全部结果")
+        .description("列出应用下的文件，支持名称 / 路径 / MIME / 大小 / 时间多维筛选")
+        .usage("[query] [flags]")
+        .argument("[query]", "可选筛选值：以 / 开头视为路径（精确匹配），否则按文件名匹配")
+        .option("--path <path>", "按路径精确匹配")
+        .option("--name <name>", "按文件名精确匹配")
+        .option("--type <mime>", "按 MIME 类型筛选（如 image/png）")
+        .option("--size-gt <size>", "文件大小下限（支持 B/KB/MB/GB）")
+        .option("--size-lt <size>", "文件大小上限（支持 B/KB/MB/GB）")
+        .option("--uploaded-since <time>", "上传时间下限（ISO 8601）")
+        .option("--limit <n>", "单次返回上限（正整数，默认 50）", parsePositiveInt, 50)
+        .option("--cursor <token>", "分页游标，从上次响应的 next_cursor 取值")
+        .option("--all", "自动翻页返回全部结果")
         .action(async (query, opts) => {
         await (0, index_1.handleFileLs)({ ...opts, query });
-    });
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda file ls
+  path                       size      uploaded_at
+  /uploads/report.pdf        1.2 MB    2026-04-20 10:00
+  /uploads/photo.png         800 KB    2026-04-21 14:30
+
+  $ miaoda file ls report.pdf
+  $ miaoda file ls /uploads/report.pdf
+  $ miaoda file ls --type image/png --size-gt 1MB
+  $ miaoda file ls --uploaded-since 2026-04-01
+
+  $ miaoda file ls --all --json | jq '.[].name'
+  "report.pdf"
+  "photo.png"
+`);
     fileCmd
         .command("stat")
-        .description("查看指定文件的元数据")
-        .argument("<file>", "path 或 file_name：自动识别（见 ls 命令说明）")
-        .addOption((0, shared_1.appIdOption)())
+        .description("查看文件元数据（不含下载链接，需要链接用 sign）")
+        .usage("<file> [flags]")
+        .argument("<file>", "文件的路径或文件名（自动识别）")
         .action(async (file, opts) => {
         await (0, index_1.handleFileStat)(file, opts);
-    });
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda file stat report.pdf
+  path:        /uploads/report.pdf
+  size:        1.2 MB
+  type:        application/pdf
+  uploaded_at: 2026-04-20 10:00
+
+  $ miaoda file stat /uploads/report.pdf
+  $ miaoda file stat report.pdf --json
+  {"path":"/uploads/report.pdf","size":1258291,...}
+
+  # 报错：文件不存在
+  $ miaoda file stat no_such.pdf
+  Error: FILE_NOT_FOUND
+    hint: Run \`miaoda file ls\` to see available files.
+`);
     fileCmd
         .command("cp")
-        .description("上传或下载文件（方向由 src/dst 自动判断）")
-        .argument("<src>", "源：本地路径 或 远程 /path / file_name")
+        .description("上传或下载文件，按 src/dst 自动判断方向")
+        .usage("<src> <dst> [flags]")
+        .argument("<src>", "源：本地文件路径 或 远程文件路径/名")
         .argument("<dst>", "目标：本地路径 或 远程路径")
-        .addOption((0, shared_1.appIdOption)())
-        .option("--rename <name>", "上传后使用的新文件名")
+        .option("--rename <name>", "上传后在远端使用的新文件名")
         .action(async (src, dst, opts) => {
         await (0, index_1.handleFileCp)(src, dst, opts);
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - src 是本地存在的文件 → 上传
+  - src 不是本地文件而 dst 看起来是本地路径 → 下载
+
+Examples:
+  $ miaoda file cp ./report.pdf /uploads/
+  ✓ Uploaded report.pdf → /uploads/report.pdf
+
+  $ miaoda file cp ./report.pdf /uploads/ --rename r.pdf
+  ✓ Uploaded report.pdf → /uploads/r.pdf
+
+  $ miaoda file cp /uploads/report.pdf .
+  ✓ Downloaded /uploads/report.pdf → ./report.pdf
+
+  $ miaoda file cp /uploads/report.pdf ./local.pdf
+  ✓ Downloaded /uploads/report.pdf → ./local.pdf
+`);
     fileCmd
         .command("rm")
-        .description("删除一个或多个文件（best-effort）")
-        .argument("[paths...]", "path 或 file_name：形似 /path、含 / 或 16+位 fileKey 时按 path 精确删除，其余按 file_name 查找后删除")
-        .addOption((0, shared_1.appIdOption)())
-        .option("-n, --name <name>", "强制按 file_name 查找后删除（跳过自动识别）；可重复指定；多匹配报 AMBIGUOUS_FILE_NAME", (value, prev) => [...(prev ?? []), value])
-        .option("-y, --yes", "跳过交互确认")
+        .description("批量删除文件（单次最多 100 个，部分失败不影响其他）")
+        .usage("[paths...] [flags]")
+        .argument("[paths...]", "要删除的文件，每项可填路径或文件名（自动识别）")
+        .option("-n, --name <name>", "按文件名删除（可重复指定）", (value, prev) => [...(prev ?? []), value])
+        .option("-y, --yes", "跳过交互确认（脚本 / agent 调用必加）")
         .action(async (paths, opts) => {
         await (0, index_1.handleFileRm)(paths, opts);
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - 单次最多 100 个；超过请拆批
+  - 部分失败响应里会列出每条 success / failed 状态，整批仍 exit 0
+
+Examples:
+  $ miaoda file rm /uploads/a.pdf /uploads/b.pdf -y
+  ✓ Deleted 2 files
+
+  $ miaoda file rm a.pdf b.pdf -y
+  ✓ Deleted 2 files
+
+  $ miaoda file rm -n a.pdf -n b.pdf -y
+  ✓ Deleted 2 files
+`);
     fileCmd
         .command("sign")
-        .description("生成文件临时下载链接")
-        .argument("<file>", "path 或 file_name：自动识别（见 ls 命令说明）")
-        .addOption((0, shared_1.appIdOption)())
-        .option("--expires <duration>", "过期时长（默认 7d，最长 30d）")
+        .description("生成可分享的临时下载链接")
+        .usage("<file> [flags]")
+        .argument("<file>", "文件的路径或文件名")
+        .option("--expires <duration>", "链接有效期，支持 30m / 24h / 7d 单位（默认 7d，最长 30d）")
         .action(async (file, opts) => {
         await (0, index_1.handleFileSign)(file, opts);
-    });
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda file sign report.pdf
+  https://...?expires=...    (valid 7d)
+
+  $ miaoda file sign report.pdf --expires 30m
+  $ miaoda file sign report.pdf --expires 24h
+`);
 }

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

@@ -5,7 +5,8 @@ const index_1 = require("../../../cli/handlers/plugin/index");
 function registerPluginCommands(program) {
     const pluginCmd = program
         .command("plugin")
-        .description("插件管理：安装/更新/移除插件包，查询 capability 实例");
+        .description("插件管理：安装/更新/移除插件包，查询 capability 实例")
+        .usage("<command> [flags]");
     pluginCmd.action(() => {
         pluginCmd.outputHelp();
     });

package/dist/cli/commands/shared.js

@@ -1,18 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.appIdOption = appIdOption;
 exports.softRequiredOption = softRequiredOption;
 exports.resolveAppId = resolveAppId;
 exports.withHelp = withHelp;
 exports.failArgs = failArgs;
 const commander_1 = require("commander");
 const error_1 = require("../../utils/error");
-/** --app-id option，需要应用上下文的命令自行 .addOption(appIdOption())。
- * Commander 的 .env() 只接受单个变量名，第二个兜底 `app_id` 在 resolveAppId 里手动检查。
- */
-function appIdOption() {
-    return new commander_1.Option("--app-id <id>", "指定目标应用").env("MIAODA_APP_ID");
-}
 /**
  * soft-required: Commander 类型上 optional，runtime 校验必填。
  */
@@ -20,15 +13,16 @@ function softRequiredOption(name, desc) {
     return new commander_1.Option(name, desc);
 }
 /**
- * 解析 appId，优先级：CLI flag > MIAODA_APP_ID > app_id > 抛错。
- * app_id 是部分外部沙箱环境注入应用 ID 的别名，作为兜底兼容（小写下划线形态）。
+ * 解析 appId，从环境变量 MIAODA_APP_ID 或 app_id（小写下划线，部分外部沙箱注入）读取。
+ * 缺失时抛 APP_ID_MISSING，由全局 catch 处理。
+ *
+ * opts 里仍保留 appId（可选），用于测试 / 高级场景显式注入；正常 CLI 不暴露此 flag。
  */
 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: [
-                "传入 --app-id <id>",
                 "设置 export MIAODA_APP_ID=<id>",
             ],
         });

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

@@ -82,15 +82,15 @@ async function handleDbDataImport(file, opts) {
             data: {
                 file,
                 table: result.tableName,
-                rows: result.rows,
+                rows: result.recordCount,
             },
         });
         return;
     }
     const tty = (0, render_1.isStdoutTty)();
     (0, output_1.emit)(tty
-        ? `✓ Imported ${file} → table '${result.tableName}' (${String(result.rows)} rows)`
-        : `OK Imported ${file} -> table '${result.tableName}' (${String(result.rows)} rows)`);
+        ? `✓ Imported ${file} → table '${result.tableName}' (${String(result.recordCount)} rows)`
+        : `OK Imported ${file} -> table '${result.tableName}' (${String(result.recordCount)} rows)`);
 }
 async function handleDbDataExport(table, opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
@@ -110,7 +110,8 @@ async function handleDbDataExport(table, opts) {
         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);
-    const rows = countRows(result.body, format);
+    // 优先信任后端 X-Miaoda-Record-Count header；header 缺失时再用 body 行数兜底
+    const rows = result.recordCount ?? countRows(result.body, format);
     if ((0, output_1.isJsonMode)()) {
         (0, output_1.emit)({
             data: {

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

@@ -37,6 +37,7 @@ exports.handleDbSql = handleDbSql;
 const api = __importStar(require("../../../api/index"));
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
+const config_1 = require("../../../utils/config");
 const shared_1 = require("../../../cli/commands/shared");
 const render_1 = require("../../../utils/render");
 const index_1 = require("../../../api/db/index");
@@ -125,8 +126,8 @@ function renderSingle(raw) {
 }
 function toJson(parsed) {
     if (parsed.kind === "select") {
-        // PRD 单 SELECT：data 直接是行数组
-        return { data: parsed.rows };
+        // PRD 单 SELECT：data 直接是行数组（按 --json 字段投影裁剪）
+        return { data: projectRows(parsed.rows) };
     }
     if (parsed.kind === "dml") {
         // PRD 单 DML：data = {command, rows_affected}
@@ -147,7 +148,7 @@ function toJson(parsed) {
  */
 function toMultiElement(parsed) {
     if (parsed.kind === "select") {
-        return { command: "SELECT", rows: parsed.rows };
+        return { command: "SELECT", rows: projectRows(parsed.rows) };
     }
     if (parsed.kind === "dml") {
         return { command: parsed.sqlType, rows_affected: parsed.affectedRows };
@@ -155,6 +156,30 @@ function toMultiElement(parsed) {
     // DDL：用后端给的细粒度 command
     return { command: parsed.sqlType };
 }
+/**
+ * PRD：`--json id,name` 字段投影。--json 不带值（boolean true）等价于不裁剪。
+ * 字段不存在时按 undefined 处理（JSON.stringify 会忽略 undefined value 的 key），
+ * 这样 Agent 拿到的 row 永远只含请求过的列。
+ */
+function projectRows(rows) {
+    const fields = parseJsonFields();
+    if (!fields)
+        return rows;
+    return rows.map((r) => {
+        const out = {};
+        for (const f of fields) {
+            out[f] = r[f];
+        }
+        return out;
+    });
+}
+/** 读取 --json [fields]：返回字段列表；boolean true 或 undefined 返回 null（不裁剪）。 */
+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);
+}
 /** 多语句 pretty：逐条 `Statement N: ...` + 末尾 `✓ N statements executed`。 */
 function renderMultiPretty(results) {
     const tty = (0, render_1.isStdoutTty)();

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

@@ -66,7 +66,8 @@ function resolveQueryRouting(opts) {
 }
 async function handleFileLs(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
-    const limit = opts.limit ? Number(opts.limit) : undefined;
+    // commander 已经把 --limit 解析为 number；保留 ?? undefined 兼容老调用
+    const limit = opts.limit;
     const sizeGt = opts.sizeGt ? (0, render_1.parseSize)(opts.sizeGt) : undefined;
     const sizeLt = opts.sizeLt ? (0, render_1.parseSize)(opts.sizeLt) : undefined;
     const { path, name } = resolveQueryRouting(opts);

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

@@ -44,7 +44,7 @@ const shared_1 = require("../../../cli/commands/shared");
 const index_1 = require("../../../api/file/index");
 const render_1 = require("../../../utils/render");
 const node_readline_1 = __importDefault(require("node:readline"));
-const MAX_BATCH = 1000;
+const MAX_BATCH = 100;
 /**
  * 解析位置参数（自动识别 path / file_name）与 `--name`（强制 file_name）两类输入。
  *
@@ -130,7 +130,7 @@ async function handleFileRm(paths, opts) {
         throw new error_1.AppError("ARGS_INVALID", "No file specified (give a /path or --name <name>)");
     }
     if (totalCount > MAX_BATCH) {
-        throw new error_1.AppError("FILE_BATCH_TOO_MANY", `Batch size ${String(totalCount)} exceeds the 1000 limit`);
+        throw new error_1.AppError("FILE_BATCH_TOO_MANY", `Batch size ${String(totalCount)} exceeds the 100 limit`);
     }
     const appId = (0, shared_1.resolveAppId)(opts);
     // destructive guardrail

package/dist/cli/help.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MiaodaHelp = void 0;
+const commander_1 = require("commander");
+/**
+ * MiaodaHelp 重写 commander 默认的 --help 输出，使之对齐 CLI 文档规范：
+ *
+ *   1. 描述放在最前（commander 默认是 Usage 在前、描述在后）
+ *   2. "Options:" 重命名为 "Flags:"，"Global Options:" 重命名为 "Global Flags:"
+ *   3. Usage 段独占一行 Heading + 缩进展示 usage 行
+ *   4. 段落顺序：描述 → Usage → Arguments → Flags → Global Flags → Commands → addHelpText('after')
+ *
+ * Notes / Examples 段由各命令通过 addHelpText('after', ...) 自行追加，
+ * 本类不直接生成 —— 框架与文案分层。
+ */
+class MiaodaHelp extends commander_1.Help {
+    // 全局默认开启：所有子命令 --help 都展示 Global Flags 段
+    showGlobalOptions = true;
+    /**
+     * 父级 --help 的 Commands 列表里展示子命令调用形态。规范要求 "<args> [flags]"
+     * 顺序，但 commander 默认 subcommandTerm 是 "name [options] <args>"。
+     *
+     *   - 子命令是分组（含下级 subcommand）→ 只显示 name，不带 args/flags
+     *   - 子命令是 leaf 且配置了 usage()  → "name <usage>"，对齐 args 在前 / flags 在后
+     *   - leaf 没配置 usage              → 退回 commander 默认行为
+     */
+    subcommandTerm(cmd) {
+        if (cmd.commands.length > 0) {
+            return cmd.name();
+        }
+        const usage = cmd.usage();
+        if (usage) {
+            return `${cmd.name()} ${usage}`.trim();
+        }
+        return super.subcommandTerm(cmd);
+    }
+    formatHelp(cmd, helper) {
+        const termWidth = helper.padWidth(cmd, helper);
+        const helpWidth = helper.helpWidth ?? 80;
+        const formatItem = (term, description) => {
+            if (description) {
+                const padding = " ".repeat(Math.max(termWidth - term.length, 0) + 2);
+                return `${term}${padding}${description}`;
+            }
+            return term;
+        };
+        const formatList = (lines) => lines.map((l) => "  " + l).join("\n");
+        void helpWidth; // 保留以备后续按宽度自动 wrap，当前直接透传 description
+        const out = [];
+        // 1. 描述
+        const desc = helper.commandDescription(cmd);
+        if (desc) {
+            out.push(desc, "");
+        }
+        // 2. Usage：独立 heading + 缩进
+        out.push("Usage:", `  ${helper.commandUsage(cmd)}`, "");
+        // 3. Arguments
+        const args = helper.visibleArguments(cmd).map((a) => formatItem(helper.argumentTerm(a), helper.argumentDescription(a)));
+        if (args.length) {
+            out.push("Arguments:", formatList(args), "");
+        }
+        // 4. Flags（原 Options）
+        const opts = helper.visibleOptions(cmd).map((o) => formatItem(helper.optionTerm(o), helper.optionDescription(o)));
+        if (opts.length) {
+            out.push("Flags:", formatList(opts), "");
+        }
+        // 5. Global Flags（原 Global Options，showGlobalOptions=true 时启用）
+        if (this.showGlobalOptions) {
+            const globals = helper.visibleGlobalOptions(cmd).map((o) => formatItem(helper.optionTerm(o), helper.optionDescription(o)));
+            if (globals.length) {
+                out.push("Global Flags:", formatList(globals), "");
+            }
+        }
+        // 6. Commands（仅父级命令组有）
+        const subs = helper.visibleCommands(cmd).map((c) => formatItem(helper.subcommandTerm(c), helper.subcommandDescription(c)));
+        if (subs.length) {
+            out.push("Commands:", formatList(subs), "");
+        }
+        // 保留末尾换行：commander 用 join('\n') 拼 addHelpText('after') 段，
+        // 这里多留一个 \n，让 Notes / Examples 段与 Flags / Global Flags 段之间空一行。
+        return out.join("\n").replace(/\n+$/, "\n");
+    }
+}
+exports.MiaodaHelp = MiaodaHelp;

package/dist/main.js

@@ -5,15 +5,23 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const index_1 = require("./cli/commands/index");
+const help_1 = require("./cli/help");
 const config_1 = require("./utils/config");
 const log_id_1 = require("./utils/log_id");
 const output_1 = require("./utils/output");
 const package_json_1 = __importDefault(require("../package.json"));
+// MiaodaHelp 对齐 CLI 规范（描述置顶 / Flags / Global Flags / 段顺序）：
+// 在 Command.prototype 上 patch createHelp，让所有命令实例（含动态注册的
+// 子命令）统一走 MiaodaHelp 渲染，避免在每个子命令上重复 configureHelp。
+commander_1.Command.prototype.createHelp = function () {
+    return Object.assign(new help_1.MiaodaHelp(), this.configureHelp());
+};
 const program = new commander_1.Command();
 const { version } = package_json_1.default;
 program
     .name("miaoda")
     .description("妙搭平台命令行工具")
+    .usage("<command> [flags]")
     .version(version, "-v, --version", "显示版本号")
     .option("--json [fields]", "JSON 输出，可选字段级选择")
     .option("--output <format>", "输出格式（pretty|json）", "pretty")

package/dist/utils/http.js

@@ -12,7 +12,7 @@ let runtimeClient;
 /**
  * 获取单例 HttpClient（默认：管理端 innerapi）。
  *
- * 管理端链路仅适用于妙搭开发态——baseURL 从 `MIAODA_DEV_INNER_DOMAIN` 读取，
+ * 管理端链路仅适用于妙搭开发态——baseURL 从 `MIAODA_DEV_INNER_DOMAIN_WITH_PREFIX` 读取，
  * 每次请求自动从 `MIAODA_AUTHN_CODE` 读取用户凭证并注入 `X-Miaoda-Client-Token`。
  * AK/SK 的 `Authorization` / `x-api-key` 照旧叠加。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.0-alpha.465bdb8",
+  "version": "0.1.0-alpha.5f650e8",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {
@@ -25,7 +25,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@lark-apaas/http-client": "^0.1.4",
+    "@lark-apaas/http-client": "^0.1.5",
     "commander": "^13.1.0"
   },
   "devDependencies": {