@lark-apaas/miaoda-cli 0.1.0 → 0.1.1-alpha.07b4fd5

package/dist/api/file/client.js

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

package/dist/api/file/detect.js

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

package/dist/api/file/index.js

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

package/dist/api/file/parsers.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAttachment = parseAttachment;
+exports.parseHead = parseHead;
+/** 安全读取字符串字段（空字符串回退为默认值） */
+function str(value, fallback = "") {
+    return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+/** 安全读取数字字段（非正值回退到 0） */
+function int(value) {
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+        return Math.trunc(value);
+    }
+    return 0;
+}
+function readSize(meta) {
+    if (!meta)
+        return 0;
+    const v = meta.size ??
+        meta.fileSize ??
+        meta.file_size ??
+        meta.contentLength ??
+        0;
+    return int(v);
+}
+/**
+ * 展示层 path 统一带前导 `/`（对齐 PRD / SKILL 里的示例）。
+ * 后端存储的 path 实际是无前导 `/` 的，这里补齐。
+ */
+function toDisplayPath(p) {
+    if (!p)
+        return p;
+    return p.startsWith("/") ? p : `/${p}`;
+}
+/** 将后端 attachment 结构映射为 CLI FileInfo（用于 ls） */
+function parseAttachment(att) {
+    const rawPath = str(att.filePath, str(att.name));
+    const info = {
+        file_name: str(att.name),
+        path: toDisplayPath(rawPath),
+        size_bytes: readSize(att.metadata),
+        type: str(att.metadata?.mimeType),
+        uploaded_at: str(att.createdAt),
+    };
+    const downloadUrl = str(att.downloadURL);
+    if (downloadUrl)
+        info.download_url = downloadUrl;
+    // uploaded_by 从 createdBy.name 映射（后端返 {userID, name, email, ...}，空代表匿名）
+    const uploader = str(att.createdBy?.name);
+    if (uploader)
+        info.uploaded_by = uploader;
+    return info;
+}
+/** 将后端 head 响应映射为 CLI FileInfo（用于 stat） */
+function parseHead(data, filePath) {
+    const outer = data?.metadata ?? {};
+    const inner = outer.metadata ?? {};
+    const info = {
+        file_name: str(outer.name),
+        path: toDisplayPath(filePath || str(outer.name)),
+        size_bytes: readSize(inner),
+        type: str(inner.mimeType),
+        uploaded_at: str(inner.lastModified),
+    };
+    const downloadUrl = str(outer.downloadURL);
+    if (downloadUrl)
+        info.download_url = downloadUrl;
+    const uploader = str(outer.createdBy?.name);
+    if (uploader)
+        info.uploaded_by = uploader;
+    return info;
+}

package/dist/api/file/types.js

@@ -0,0 +1,3 @@
+"use strict";
+// ── API 响应外层信封（file-storage inner API 统一结构） ──
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/index.js

@@ -33,6 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.plugin = void 0;
+exports.db = exports.file = exports.plugin = void 0;
 const _plugin = __importStar(require("../api/plugin/index"));
+const _file = __importStar(require("../api/file/index"));
+const _db = __importStar(require("../api/db/index"));
 exports.plugin = { ..._plugin };
+exports.file = { ..._file };
+exports.db = { ..._db };

package/dist/api/plugin/api.js

@@ -22,7 +22,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 // ── Plugin Version API ──
 async function getPluginVersions(keys, latestOnly = true) {
-    const client = (0, http_1.getHttpClient)();
+    const client = (0, http_1.getRuntimeHttpClient)();
     const response = await client.post(`/api/v1/studio/innerapi/plugins/-/versions/batch_get?keys=${keys.join(",")}&latest_only=${String(latestOnly)}`);
     if (!response.ok) {
         throw new error_1.HttpError(response.status, response.url, `Failed to get plugin versions: ${String(response.status)} ${response.statusText}`);
@@ -58,7 +58,7 @@ function parsePluginKey(key) {
     return { scope: match[1], name: match[2] };
 }
 async function downloadFromInner(pluginKey, version) {
-    const client = (0, http_1.getHttpClient)();
+    const client = (0, http_1.getRuntimeHttpClient)();
     const { scope, name } = parsePluginKey(pluginKey);
     const url = `/api/v1/studio/innerapi/plugins/${scope}/${name}/versions/${version}/package`;
     const response = await client.get(url);
@@ -203,7 +203,7 @@ async function reportEvents(events) {
     if (events.length === 0)
         return true;
     try {
-        const client = (0, http_1.getHttpClient)();
+        const client = (0, http_1.getRuntimeHttpClient)();
         const response = await client.post("/api/v1/studio/innerapi/resource_events", { events });
         if (!response.ok) {
             (0, logger_1.log)("telemetry", `Failed to report events: ${String(response.status)} ${response.statusText}`);

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

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDbCommands = registerDbCommands;
+const index_1 = require("../../../cli/handlers/db/index");
+function registerDbCommands(program) {
+    const dbCmd = program
+        .command("db")
+        .description("应用数据库（PostgreSQL）的命令行操作集合。")
+        .usage("<command> [flags]")
+        // --env 注册在 db 父级，spec 把它列入 db --help 的 Global Flags；
+        // leaf 命令仍各自接收 --env 值（commander 解析时父级 option 自动适用于子命令）
+        .option("--env <name>", "指定目标环境（dev / online，仅专家模式应用支持）");
+    dbCmd.action(() => {
+        dbCmd.outputHelp();
+    });
+    dbCmd
+        .command("sql")
+        .summary("执行任意 SQL（SELECT / DML / DDL，支持多条分号分隔）")
+        .description("执行 SQL 语句，支持 SELECT、DML、DDL 等所有标准 PostgreSQL 操作。\n" +
+        "支持通过 stdin 读取（miaoda db sql < file.sql），多条语句以分号分隔。\n" +
+        "事务控制使用 PG 原生的 BEGIN / COMMIT / ROLLBACK 语法。")
+        .usage("<query> [flags]")
+        .argument("[query]", "要执行的 SQL 语句；省略时从标准输入读取")
+        .action(async function (query) {
+        await (0, index_1.handleDbSql)(query, this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Notes:
+  - SELECT 结果超过 1000 行直接报错（RESULT_SET_TOO_LARGE），不做隐式截断。
+    需要分页时请在 SQL 中用 LIMIT / OFFSET。
+  - 多条语句不自动包事务：失败时后续不执行、已成功的不回滚。
+    需要原子性请显式 BEGIN; ...; COMMIT;
+  - --env 仅在专家模式应用且已 migration init 后可用。
+  - NULL 值在 --json 中是 JSON 原生 null，pretty / 管道中是字面字符串 NULL。
+
+Examples:
+  $ miaoda db sql "SELECT id, name, age FROM users LIMIT 10"
+  id    name     age
+  1001  Alice    28
+  1002  Bob      35
+
+  $ miaoda db sql "INSERT INTO users (name, age) VALUES ('Dave', 25)"
+  ✓ 1 row inserted
+
+  $ miaoda db sql < migration.sql
+  Statement 1: ✓ CREATE TABLE orders
+  Statement 2: ✓ 10 rows inserted
+  ✓ 2 statements executed
+
+  # 报错：SQL 语法错误
+  $ miaoda db sql "SELCT * FROM users"
+  Error: Syntax error at or near "SELCT"
+    hint: Check SQL keyword spelling. Did you mean "SELECT"?
+
+  # 报错：结果超过 1000 行
+  $ miaoda db sql "SELECT * FROM users"
+  Error: Result set exceeds the 1000-row limit (query would return 15234 rows)
+    hint: Add \`LIMIT <n>\` to your SQL to narrow the result.
+`);
+    // schema 二级资源分组
+    const schemaCmd = dbCmd
+        .command("schema")
+        .summary("查看数据库表结构")
+        .description("查看应用数据库的表结构信息。")
+        .usage("<command> [flags]");
+    schemaCmd.action(() => {
+        schemaCmd.outputHelp();
+    });
+    schemaCmd
+        .command("list")
+        .summary("列出所有表的概览（表名、行数、大小等）")
+        .description("列出当前应用所有表的概览信息：表名、描述、行数、大小、列数、最近更新时间。\n" +
+        "查看单表完整结构请用 `schema get`；查看 DDL 变更历史请用 `changelog`（P1）。")
+        .usage("[flags]")
+        .action(async function () {
+        await (0, index_1.handleDbSchemaList)(this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda db schema list
+  name      description   rows   size      columns   updated_at
+  users     用户信息          1523   2.1 MB    5         3h ago
+  orders    订单记录          8891   12.4 MB   8         2d ago
+  products  商品目录          342    512 KB    6         2026-03-15
+
+  $ miaoda db schema list --json name,rows
+  {
+    "data": [
+      {"name": "users", "rows": 1523},
+      {"name": "orders", "rows": 8891},
+      {"name": "products", "rows": 342}
+    ],
+    "next_cursor": null,
+    "has_more": false
+  }
+`);
+    schemaCmd
+        .command("get")
+        .summary("查看单表完整结构（列定义、索引、约束）")
+        .description("查看指定表的完整结构：列定义（含类型、可空、默认值、注释）、索引、行数、大小。\n" +
+        "默认 pretty 输出 CREATE TABLE 的 SQL 文本；--json 输出结构化字段。")
+        .usage("<table> [flags]")
+        .argument("<table>", "表名（无需带 schema 前缀）")
+        .option("--ddl", "强制输出 CREATE TABLE 建表语句（pretty 默认就是 DDL，--json 时配合此 flag 返 SQL 文本）")
+        .action(async function (table) {
+        await (0, index_1.handleDbSchemaGet)(table, this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda db schema get users
+  CREATE TABLE users (
+    id uuid DEFAULT gen_random_uuid() NOT NULL,
+    name varchar(100) NOT NULL,
+    email varchar(255),
+    age integer,
+    PRIMARY KEY (id),
+    UNIQUE (email)
+  );
+  COMMENT ON TABLE users IS '用户信息';
+  ...
+
+  # 报错：表不存在
+  $ miaoda db schema get userss
+  Error: Table 'userss' does not exist
+    hint: Did you mean 'users'? Run \`miaoda db schema list\` to see all tables.
+`);
+    // data 二级资源分组
+    const dataCmd = dbCmd
+        .command("data")
+        .summary("表数据导入导出")
+        .description("表数据的批量导入导出，适合数据备份、跨环境迁移、外部分析。")
+        .usage("<command> [flags]");
+    dataCmd.action(() => {
+        dataCmd.outputHelp();
+    });
+    dataCmd
+        .command("import")
+        .summary("从本地 CSV / JSON 文件导入数据到表")
+        .description("从本地 CSV / JSON 文件导入数据到表。整个导入是原子的——遇到任何错误（主键冲突、\n" +
+        "类型不匹配、列名不匹配等）会回滚已插入的所有行。\n" +
+        "不支持 SQL 文件，SQL 备份请用 `miaoda db sql < <文件>.sql` 回放。")
+        .usage("<file> [flags]")
+        .argument("<file>", "本地文件路径（CSV 或 JSON 格式）")
+        .option("--table <name>", "目标表名；未指定时按文件名（不含扩展名）推断（如 users.csv → users）")
+        .option("--format <fmt>", "文件格式 csv / json；未指定时按文件扩展名推断")
+        .action(async function (file) {
+        await (0, index_1.handleDbDataImport)(file, this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Notes:
+  - 目标表必须已存在；CSV 表头 / JSON 顶层 key 必须与表字段名完全一致。
+  - 导入为原子操作：遇到错误回滚所有已插入行，不会出现部分导入的中间状态。
+  - 仅支持 .csv 和 .json 文件扩展名。
+
+Examples:
+  $ miaoda db data import users.csv
+  ✓ Imported users.csv → table 'users' (1523 rows)
+
+  $ miaoda db data import data.csv --table users
+  ✓ Imported data.csv → table 'users' (1523 rows)
+
+  # 报错：CSV 表头与字段不匹配
+  $ miaoda db data import users.csv
+  Error: Column 'full_name' in CSV does not match any column in table 'users'
+    hint: Expected columns: id, name, email, age. Check CSV header row.
+
+  # 报错：主键冲突（已回滚）
+  $ miaoda db data import users.csv
+  Error: Primary key conflict at row 42 (id=1001 already exists), 0 rows imported
+    hint: Deduplicate input data, or remove conflicting rows first with
+          \`miaoda db sql "DELETE FROM users WHERE id IN (...)"\`.
+`);
+    dataCmd
+        .command("export")
+        .summary("导出表数据到本地 CSV / JSON / SQL 文件")
+        .description("把指定表的所有数据导出到本地文件，支持 CSV / JSON / SQL 三种格式。")
+        .usage("<table> [flags]")
+        .argument("<table>", "表名（无需带 schema 前缀）")
+        .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());
+    })
+        .addHelpText("after", `
+Notes:
+  - SQL 格式生成 INSERT 语句，可用 \`miaoda db sql < <文件>.sql\` 在其他环境回放。
+  - 文件已存在时默认报错（FILE_ALREADY_EXISTS），用 --force 覆盖或 -f 改路径。
+
+Examples:
+  $ miaoda db data export users
+  ✓ Exported users → users.csv (1523 rows)
+
+  $ miaoda db data export users --format json
+  ✓ Exported users → users.json (1523 rows)
+
+  $ miaoda db data export users --format sql -f users_backup.sql
+  ✓ Exported users → users_backup.sql (1523 rows)
+
+  $ miaoda db data export users -f ~/Desktop/users.csv
+  ✓ Exported users → ~/Desktop/users.csv (1523 rows)
+
+  # 报错：文件已存在
+  $ miaoda db data export users
+  Error: Output file 'users.csv' already exists
+    hint: Use -f to specify a different path, or --force to overwrite.
+`);
+}