@lark-apaas/miaoda-cli 0.1.2-alpha.4d0ff57 → 0.1.2-alpha.9eeb185

package/dist/api/db/api.js

@@ -5,6 +5,7 @@ exports.getSchema = getSchema;
 exports.importData = importData;
 exports.exportData = exportData;
 exports.listDDLChangelog = listDDLChangelog;
+exports.getAuditStatus = getAuditStatus;
 exports.setAuditConfig = setAuditConfig;
 exports.migrationInit = migrationInit;
 exports.migrate = migrate;
@@ -332,13 +333,35 @@ async function listDDLChangelog(opts) {
         hasMore: Boolean(data.hasMore),
     };
 }
-// ── db audit → InnerAdminSetAuditConfig ──
+// ── db audit → InnerAdminGetAuditStatus / InnerAdminSetAuditConfig ──
+/**
+ * 后端：GET /v1/dataloom/app/{appId}/db/audit/status?table=&dbBranch=
+ * 查表审计开关状态。table 非空 → 单表过滤；空 → 返当前 workspace 全部已配置表。
+ */
+async function getAuditStatus(opts) {
+    const client = (0, http_1.getHttpClient)();
+    const url = (0, client_1.buildInnerUrl)(opts.appId, "/db/audit/status", {
+        table: opts.table,
+        dbBranch: opts.dbBranch,
+    });
+    const start = Date.now();
+    let response;
+    try {
+        response = await client.get(url);
+        (0, client_1.traceHttp)("GET", url, start, response);
+    }
+    catch (err) {
+        (0, client_1.traceHttp)("GET", url, start, err instanceof http_client_1.HttpError ? err.response : undefined, err);
+        await mapDbHttpError(err, url, "Failed to get audit status");
+        throw err; // 不可达
+    }
+    const respBody = (await response.json());
+    const data = (0, client_1.extractData)(respBody);
+    return data.items ?? [];
+}
 /**
  * 后端：POST /v1/dataloom/app/{appId}/db/audit/config
  * 写：enabled=true 开启 / false 关闭。retention 仅 enabled=true 生效。
- *
- * 读路径（status / log）不在此模块——CLI handler 走 execSql 直接 SELECT
- * `_dl_audit_config` / `_dl_audit_log` 元数据表。
  */
 async function setAuditConfig(opts) {
     const client = (0, http_1.getHttpClient)();

package/dist/api/db/client.js

@@ -140,7 +140,7 @@ const BIZ_ERR_MAP = new Map(Object.entries({
     },
     k_dl_1310003: {
         code: "INVALID_RETENTION",
-        hint: "Allowed values: 7d / 30d / 180d / 360d.",
+        hint: "Allowed values: 7d, 30d, 180d, 360d, forever.",
     },
     // migration
     k_dl_1320001: {

package/dist/api/db/index.js

@@ -1,12 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pickTableDetail = exports.flattenSchemaList = exports.parseSqlResult = exports.SQLSTATE_MAP = exports.ensureInnerSuccess = exports.buildInnerUrl = exports.getDbQuota = exports.recover = exports.migrate = exports.migrationInit = exports.setAuditConfig = exports.listDDLChangelog = exports.exportData = exports.importData = exports.getSchema = exports.execSql = void 0;
+exports.pickTableDetail = exports.flattenSchemaList = exports.parseSqlResult = exports.SQLSTATE_MAP = exports.ensureInnerSuccess = exports.buildInnerUrl = exports.getDbQuota = exports.recover = exports.migrate = exports.migrationInit = exports.setAuditConfig = exports.getAuditStatus = exports.listDDLChangelog = exports.exportData = exports.importData = exports.getSchema = exports.execSql = void 0;
 var api_1 = require("./api");
 Object.defineProperty(exports, "execSql", { enumerable: true, get: function () { return api_1.execSql; } });
 Object.defineProperty(exports, "getSchema", { enumerable: true, get: function () { return api_1.getSchema; } });
 Object.defineProperty(exports, "importData", { enumerable: true, get: function () { return api_1.importData; } });
 Object.defineProperty(exports, "exportData", { enumerable: true, get: function () { return api_1.exportData; } });
 Object.defineProperty(exports, "listDDLChangelog", { enumerable: true, get: function () { return api_1.listDDLChangelog; } });
+Object.defineProperty(exports, "getAuditStatus", { enumerable: true, get: function () { return api_1.getAuditStatus; } });
 Object.defineProperty(exports, "setAuditConfig", { enumerable: true, get: function () { return api_1.setAuditConfig; } });
 Object.defineProperty(exports, "migrationInit", { enumerable: true, get: function () { return api_1.migrationInit; } });
 Object.defineProperty(exports, "migrate", { enumerable: true, get: function () { return api_1.migrate; } });

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

@@ -251,7 +251,7 @@ Examples:
         .summary("启用表审计")
         .usage("<table> [flags]")
         .argument("<table>", "目标表名")
-        .option("--retention <ttl>", "保留时长 7d / 30d / 180d / 360d", "7d")
+        .option("--retention <ttl>", "保留时长 7d / 30d / 180d / 360d / forever", "7d")
         .action(async function (table) {
         await (0, index_1.handleDbAuditEnable)(table, this.optsWithGlobals());
     });

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

@@ -44,79 +44,71 @@ const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 const render_1 = require("../../../utils/render");
 const index_2 = require("../../../api/db/index");
-// "forever" 不在后端支持范围（pg_audit ValidDay 只接 int64 天数），CLI 提前拦截
-const VALID_RETENTION = new Set(["7d", "30d", "180d", "360d"]);
+const VALID_RETENTION = new Set(["7d", "30d", "180d", "360d", "forever"]);
 async function handleDbAuditStatus(table, opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
-    const sql = table !== undefined && table !== ""
-        ? `SELECT "table", enabled, enabled_at, retention FROM _dl_audit_config WHERE "table" = '${escapeSqlLiteral(table)}'`
-        : `SELECT "table", enabled, enabled_at, retention FROM _dl_audit_config ORDER BY "table"`;
-    const results = await api.db.execSql({ appId, sql, dbBranch: opts.env });
-    const rows = collectSelectRows(results);
-    // 单表查询：表未配置时给个 enabled=false 占位项，让 CLI 输出语义统一
+    const items = await api.db.getAuditStatus({ appId, table, dbBranch: opts.env });
+    const rows = items.map(toAuditStatus);
+    // 单表查询但后端没记录 → 占位 enabled=false
     if (table !== undefined && table !== "" && rows.length === 0) {
-        rows.push({ table, enabled: false });
+        rows.push({ table, enabled: false, enabled_at: null, retention: null });
     }
-    const items = rows.map(toAuditStatus);
+    // PRD JSON：单表返 object，多表返 array
     if ((0, output_1.isJsonMode)()) {
-        (0, output_1.emitOk)({ items });
+        if (table !== undefined && rows.length === 1) {
+            (0, output_1.emitOk)((0, output_1.snakeCaseKeys)(rows[0]));
+        }
+        else {
+            (0, output_1.emitOk)((0, output_1.snakeCaseKeys)(rows));
+        }
         return;
     }
-    if (items.length === 0) {
+    if (rows.length === 0) {
         (0, output_1.emit)("No audit configuration found.");
         return;
     }
     const tty = (0, render_1.isStdoutTty)();
-    // 单表显式查询（rows.length=1 且对应输入 table）走 key/value 形态，更可读
-    if (table !== undefined && items.length === 1) {
-        const it = items[0];
+    // 单表 → key:value 形态
+    if (table !== undefined && rows.length === 1) {
+        const it = rows[0];
         (0, output_1.emit)((0, render_1.renderKeyValue)([
-            ["table", it.table],
-            ["enabled", String(it.enabled)],
-            ["enabled_at", it.enabled_at ? (0, render_1.formatTime)(it.enabled_at, tty) : "—"],
-            ["retention", it.retention ?? "—"],
+            ["Table", it.table],
+            ["Enabled", boolToYesNo(it.enabled)],
+            ["Enabled at", it.enabled_at ? (0, render_1.formatTime)(it.enabled_at, tty) : "—"],
+            ["Retention", it.retention ?? "—"],
         ], tty));
         return;
     }
+    // 列表 → table 形态
     const headers = ["table", "enabled", "enabled_at", "retention"];
-    const out = items.map((it) => [
+    const out = rows.map((it) => [
         it.table,
-        String(it.enabled),
+        boolToYesNo(it.enabled),
         it.enabled_at ? (0, render_1.formatTime)(it.enabled_at, tty) : "—",
         it.retention ?? "—",
     ]);
     (0, output_1.emit)(tty ? (0, render_1.renderAlignedTable)(headers, out) : (0, render_1.renderTsv)(headers, out));
 }
-function toAuditStatus(row) {
+function toAuditStatus(s) {
     return {
-        table: asString(row.table),
-        enabled: Boolean(row.enabled),
-        enabled_at: row.enabled_at == null ? null : asString(row.enabled_at),
-        retention: row.retention == null ? null : asString(row.retention),
+        table: s.table,
+        enabled: s.enabled,
+        enabled_at: s.enabledAt ?? null,
+        retention: s.retention ?? null,
     };
 }
-// asString 把 SELECT 结果里的列值（unknown）安全地转成字符串。SQL 返回值通常是
-// string / number / boolean / null，但极端情况下也可能是 JSON 反序列化出的对象。
-// 直接 String(obj) 会得到 "[object Object]"，这里改用 typeof 分类避免。
-function asString(v, fallback = "") {
-    if (v == null)
-        return fallback;
-    if (typeof v === "string")
-        return v;
-    if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint")
-        return String(v);
-    return JSON.stringify(v);
-}
 async function handleDbAuditEnable(table, opts) {
     if (!table) {
         throw new error_1.AppError("ARGS_INVALID", "table name is required", {
-            next_actions: ["Usage: miaoda db audit enable <table> [--retention 7d|30d|180d|360d]"],
+            next_actions: [
+                "Usage: miaoda db audit enable <table> [--retention 7d|30d|180d|360d|forever]",
+            ],
         });
     }
     const retention = opts.retention ?? "7d";
     if (!VALID_RETENTION.has(retention)) {
-        throw new error_1.AppError("INVALID_RETENTION", `invalid retention: ${retention}`, {
-            next_actions: ["Allowed values: 7d / 30d / 180d / 360d."],
+        throw new error_1.AppError("INVALID_RETENTION", `Invalid retention '${retention}'`, {
+            next_actions: ["Allowed values: 7d, 30d, 180d, 360d, forever."],
         });
     }
     const appId = (0, shared_1.resolveAppId)(opts);
@@ -127,11 +119,18 @@ async function handleDbAuditEnable(table, opts) {
         retention,
         dbBranch: opts.env,
     });
+    // PRD JSON：{"data": {"table": "...", "enabled": true, "retention": "..."}}
     if ((0, output_1.isJsonMode)()) {
-        (0, output_1.emitOk)({ status });
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
+            table: status.table,
+            enabled: status.enabled,
+            retention: status.retention ?? retention,
+        }));
         return;
     }
-    (0, output_1.emit)(`✓ Audit enabled for '${status.table}' (retention=${status.retention ?? retention})`);
+    const tty = (0, render_1.isStdoutTty)();
+    const prefix = tty ? "✓" : "OK";
+    (0, output_1.emit)(`${prefix} Audit enabled for table '${status.table}' (retention: ${status.retention ?? retention})`);
 }
 async function handleDbAuditDisable(table, opts) {
     if (!table) {
@@ -147,10 +146,15 @@ async function handleDbAuditDisable(table, opts) {
         dbBranch: opts.env,
     });
     if ((0, output_1.isJsonMode)()) {
-        (0, output_1.emitOk)({ status });
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
+            table: status.table,
+            enabled: status.enabled,
+        }));
         return;
     }
-    (0, output_1.emit)(`✓ Audit disabled for '${status.table}'`);
+    const tty = (0, render_1.isStdoutTty)();
+    const prefix = tty ? "✓" : "OK";
+    (0, output_1.emit)(`${prefix} Audit disabled for table '${status.table}'`);
 }
 async function handleDbAuditList(tables, opts) {
     if (tables.length === 0) {
@@ -161,7 +165,7 @@ async function handleDbAuditList(tables, opts) {
         });
     }
     const appId = (0, shared_1.resolveAppId)(opts);
-    const limit = opts.limit ?? 50;
+    const limit = opts.limit ?? 20;
     // since 优先级：opts.cursor（前一页末条 event_time）> opts.since
     const sinceRaw = opts.cursor ?? opts.since;
     const since = normalizeTime(sinceRaw, "--since/--cursor");
@@ -176,21 +180,29 @@ async function handleDbAuditList(tables, opts) {
         `FROM _dl_audit_log WHERE ${whereParts.join(" AND ")} ORDER BY event_time DESC LIMIT ${String(limit + 1)}`;
     const results = await api.db.execSql({ appId, sql, dbBranch: opts.env });
     const allRows = collectSelectRows(results);
-    // 多取一条用于判断 hasMore；最终只展示 limit 行
     const hasMore = allRows.length > limit;
     const visible = hasMore ? allRows.slice(0, limit) : allRows;
     const nextCursor = hasMore && visible.length > 0 ? asString(visible[visible.length - 1].event_time) : null;
-    // 多表混合时统计哪些表无记录，PRD 要求末尾汇总
+    // 多表混合时统计哪些表无记录
     const seen = new Set();
     for (const r of visible)
         seen.add(asString(r.target_table));
     const skipped = tables.filter((t) => !seen.has(t));
+    // PRD JSON：data 是数组，元素是事件对象（snake_case），分页信封 next_cursor / has_more
     if ((0, output_1.isJsonMode)()) {
-        (0, output_1.emitPaged)(visible, nextCursor, hasMore);
+        const items = visible.map((r) => ({
+            event_id: asString(r.event_id),
+            event_time: asString(r.event_time),
+            target_table: asString(r.target_table),
+            type: asString(r.type),
+            operator: asString(r.operator),
+            summary: asString(r.summary),
+            details: r.details, // 已经是结构化 JSON，透传
+        }));
+        (0, output_1.emitPaged)(items, nextCursor, hasMore);
         if (skipped.length > 0) {
             process.stderr.write(`(${String(skipped.length)} table(s) skipped: ${skipped.join(", ")})\n`);
         }
-        // 退出码：任一表有数据 → 0；全空 → 1（PRD 约定）
         if (visible.length === 0)
             process.exitCode = 1;
         return;
@@ -204,14 +216,23 @@ async function handleDbAuditList(tables, opts) {
         return;
     }
     const tty = (0, render_1.isStdoutTty)();
-    const headers = ["event_time", "target_table", "type", "operator", "summary"];
-    const rows = visible.map((it) => [
-        (0, render_1.formatTime)(asString(it.event_time), tty),
-        asString(it.target_table),
-        asString(it.type),
-        asString(it.operator, "—"),
-        asString(it.summary),
-    ]);
+    // PRD：多表渲染时第一列是 target_table，单表时去掉这一列
+    const isMultiTable = tables.length > 1;
+    const headers = isMultiTable
+        ? ["target_table", "event_time", "type", "event_id", "operator", "summary"]
+        : ["event_time", "type", "event_id", "operator", "summary"];
+    const rows = visible.map((it) => {
+        const eventTime = (0, render_1.formatTime)(asString(it.event_time), tty);
+        const eventId = truncateId(asString(it.event_id));
+        const cells = [
+            eventTime,
+            asString(it.type),
+            eventId,
+            asString(it.operator, "—"),
+            asString(it.summary),
+        ];
+        return isMultiTable ? [asString(it.target_table), ...cells] : cells;
+    });
     (0, output_1.emit)(tty ? (0, render_1.renderAlignedTable)(headers, rows) : (0, render_1.renderTsv)(headers, rows));
     if (skipped.length > 0) {
         process.stderr.write(`(${String(skipped.length)} table(s) skipped: ${skipped.join(", ")})\n`);
@@ -224,8 +245,7 @@ async function handleDbAuditList(tables, opts) {
 function normalizeTime(input, flagName) {
     if (input === undefined || input === "")
         return undefined;
-    // ISO 8601 形如 2026-05-07T08:00:00Z 直接透传，避免 parseTimeFilterMs 在
-    // 严格 ISO 上重做一次会损精度
+    // ISO 8601 直接透传，避免 parseTimeFilterMs 在严格 ISO 上重做一次损精度
     if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/.test(input)) {
         return new Date(input).toISOString();
     }
@@ -241,10 +261,26 @@ function collectSelectRows(results) {
     }
     return out;
 }
-/**
- * SQL 字符串字面量转义。仅处理单引号；表名 / 时间戳由调用方控制范围（白名单或
- * 严格 ISO 8601 正则），不在此函数内做。
- */
+// SQL 字面量转义。表名 / 时间戳由调用方控制范围（白名单或严格 ISO 8601 正则）。
 function escapeSqlLiteral(s) {
     return s.replace(/'/g, "''");
 }
+// PRD 输出 enabled 列用 yes/no 而非 true/false
+function boolToYesNo(b) {
+    return b ? "yes" : "no";
+}
+function asString(v, fallback = "") {
+    if (v == null)
+        return fallback;
+    if (typeof v === "string")
+        return v;
+    if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint")
+        return String(v);
+    return JSON.stringify(v);
+}
+// audit list 的 event_id 在 TTY 视图里截断展示（PRD 示例 "01525416B44F..."）
+function truncateId(id) {
+    if (id.length <= 12)
+        return id;
+    return id.slice(0, 12) + "...";
+}

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

@@ -39,6 +39,17 @@ const index_1 = require("../../../api/file/index");
 const shared_1 = require("../../../cli/commands/shared");
 const output_1 = require("../../../utils/output");
 const render_1 = require("../../../utils/render");
+function toRow(it) {
+    return {
+        change_id: it.changeId,
+        changed_at: it.changedAt,
+        operator: it.operator,
+        target_table: it.targetTable,
+        change_type: it.changeType,
+        summary: it.summary,
+        statement: it.statement,
+    };
+}
 /** 把用户传入的 since/until 归一成 ISO 8601 UTC 字符串；空串返 undefined。 */
 function normalizeTime(input, flagName) {
     if (input === undefined || input === "")
@@ -74,12 +85,13 @@ async function handleDbChangelog(opts) {
         cursor = page.nextCursor;
     }
     if ((0, output_1.isJsonMode)()) {
+        const rows = allItems.map(toRow);
         // --all 时已经把所有页合一起返，has_more=false / next_cursor=null
         if (opts.all) {
-            (0, output_1.emitPaged)(allItems, null, false);
+            (0, output_1.emitPaged)((0, output_1.snakeCaseKeys)(rows), null, false);
         }
         else {
-            (0, output_1.emitPaged)(allItems, lastCursor, lastHasMore);
+            (0, output_1.emitPaged)((0, output_1.snakeCaseKeys)(rows), lastCursor, lastHasMore);
         }
         return;
     }
@@ -88,7 +100,8 @@ async function handleDbChangelog(opts) {
         return;
     }
     const tty = (0, render_1.isStdoutTty)();
-    const headers = ["change_id", "changed_at", "operator", "target_table", "type", "summary"];
+    // PRD: change_id / changed_at / operator / target_table / change_type / summary
+    const headers = ["change_id", "changed_at", "operator", "target_table", "change_type", "summary"];
     const rows = allItems.map((it) => [
         it.changeId,
         (0, render_1.formatTime)(it.changedAt, tty),

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

@@ -46,7 +46,7 @@ const output_1 = require("../../../utils/output");
 const render_1 = require("../../../utils/render");
 async function handleDbMigrationInit(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
-    // PRD：不可逆操作，TTY 默认要求 y/N；--yes 跳过
+    // 不可逆操作，TTY 默认要求 y/N；--yes 跳过
     if (!opts.yes && !(0, output_1.isJsonMode)()) {
         const ok = await confirm(`? Initialize multi-env (single → dev/online), this is IRREVERSIBLE${opts.syncData ? " and will copy existing data to dev" : ""}? (y/N) `);
         if (!ok) {
@@ -56,48 +56,73 @@ async function handleDbMigrationInit(opts) {
     }
     const result = await api.db.migrationInit({ appId, syncData: opts.syncData });
     if ((0, output_1.isJsonMode)()) {
-        (0, output_1.emitOk)(result);
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)(result));
         return;
     }
     const tty = (0, render_1.isStdoutTty)();
     (0, output_1.emit)((0, render_1.renderKeyValue)([
-        ["status", result.status],
-        ["environments", result.environments.join(", ")],
-        ["data_synced", String(result.dataSynced)],
+        ["Status", result.status],
+        ["Environments", result.environments.join(", ")],
+        ["Data synced", String(result.dataSynced)],
     ], tty));
 }
 async function handleDbMigrationDiff(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     const result = await api.db.migrate({ appId, dryRun: true });
-    renderMigrate(result);
+    renderDiff(result);
 }
 async function handleDbMigrationApply(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
-    // 先 diff 一次给用户确认
-    const preview = await api.db.migrate({ appId, dryRun: true });
-    if (preview.changes.length === 0) {
-        if ((0, output_1.isJsonMode)()) {
-            (0, output_1.emitOk)({ ...preview, status: "no_pending_changes" });
-        }
-        else {
-            (0, output_1.emit)("No pending changes from dev to online.");
-        }
-        return;
-    }
+    // TTY 下先 diff 给用户审；--yes 直接打到 online
     if (!opts.yes && !(0, output_1.isJsonMode)()) {
-        renderMigrate(preview);
-        const ok = await confirm(`? Apply ${String(preview.changes.length)} change(s) from ${preview.from} to ${preview.to}? (y/N) `);
+        const preview = await api.db.migrate({ appId, dryRun: true });
+        if (preview.changes.length === 0) {
+            (0, output_1.emit)(`Error: No pending changes between ${preview.from} and ${preview.to}`);
+            (0, output_1.emit)(`  hint: Make schema changes in dev first.`);
+            process.exitCode = 1;
+            return;
+        }
+        renderDiff(preview);
+        const ok = await confirm(`? Apply ${String(preview.changes.length)} change(s) to ${preview.to}? (y/N) `);
         if (!ok) {
             (0, output_1.emit)("Aborted.");
             return;
         }
     }
     const result = await api.db.migrate({ appId, dryRun: false });
-    renderMigrate(result);
+    if ((0, output_1.isJsonMode)()) {
+        // PRD：{"status": "applied", "from": "dev", "to": "online", "changes_applied": 2}
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
+            status: result.status ?? "applied",
+            from: result.from,
+            to: result.to,
+            changesApplied: result.changesApplied ?? result.changes.length,
+        }));
+        return;
+    }
+    const tty = (0, render_1.isStdoutTty)();
+    const prefix = tty ? "✓" : "OK";
+    const arrow = tty ? "→" : "->";
+    const applied = result.changesApplied ?? result.changes.length;
+    (0, output_1.emit)(`${prefix} Applied ${result.from} ${arrow} ${result.to} (${String(applied)} changes)`);
 }
-function renderMigrate(result) {
+// ── helpers ──
+// PRD diff 输出：
+//   dev → online (2 changes):
+//
+//     ALTER TABLE users ADD COLUMN avatar_url text;
+//     CREATE INDEX idx_users_avatar ON users(avatar_url);
+function renderDiff(result) {
     if ((0, output_1.isJsonMode)()) {
-        (0, output_1.emitOk)(result);
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
+            from: result.from,
+            to: result.to,
+            changes: result.changes.map((c) => ({
+                type: c.type,
+                table: c.table,
+                statement: c.statement,
+            })),
+        }));
         return;
     }
     const tty = (0, render_1.isStdoutTty)();
@@ -105,17 +130,10 @@ function renderMigrate(result) {
         (0, output_1.emit)(`No pending changes from ${result.from} to ${result.to}.`);
         return;
     }
-    const headers = ["type", "table", "statement"];
-    const rows = result.changes.map((c) => [c.type, c.table, c.statement]);
-    (0, output_1.emit)(tty ? (0, render_1.renderAlignedTable)(headers, rows) : (0, render_1.renderTsv)(headers, rows));
-    if (result.dryRun) {
-        (0, output_1.emit)(`(dry-run: ${String(result.changes.length)} change(s) preview, run \`db migration apply\` to commit)`);
-    }
-    else {
-        (0, output_1.emit)(`✓ Applied ${String(result.changesApplied ?? result.changes.length)} change(s) from ${result.from} to ${result.to}`);
-    }
+    const arrow = tty ? "→" : "->";
+    (0, output_1.emit)(`${result.from} ${arrow} ${result.to} (${String(result.changes.length)} changes):\n\n` +
+        result.changes.map((c) => `  ${c.statement}`).join("\n"));
 }
-// ── confirm ──
 async function confirm(prompt) {
     const rl = node_readline_1.default.createInterface({ input: process.stdin, output: process.stderr });
     return new Promise((resolve) => {

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

@@ -42,19 +42,27 @@ async function handleDbQuota(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     const data = await api.db.getDbQuota({ appId, dbBranch: opts.env });
     if ((0, output_1.isJsonMode)()) {
-        (0, output_1.emitOk)(data);
+        // 配额未对接（storageQuotaBytes=0）时，quota / usage_percent 字段都不输出
+        const out = {
+            storageUsedBytes: data.storageUsedBytes,
+            tables: data.tables,
+            views: data.views,
+        };
+        if (data.storageQuotaBytes > 0) {
+            out.storageQuotaBytes = data.storageQuotaBytes;
+            out.usagePercent = data.usagePercent;
+        }
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)(out));
         return;
     }
+    // PRD：单行 "Storage: 14.9 MB / 1 GB (1.5%)"；配额未对接时只显示 used
     const tty = (0, render_1.isStdoutTty)();
-    // quota=0 表示后端未对接配额上限，按 PRD 渲染 "—"
-    const used = (0, render_1.formatSize)(data.storageUsedBytes);
-    const total = data.storageQuotaBytes > 0 ? (0, render_1.formatSize)(data.storageQuotaBytes) : "—";
-    const pct = data.storageQuotaBytes > 0 ? `${data.usagePercent.toFixed(1)}%` : "—";
+    const storageLine = data.storageQuotaBytes > 0
+        ? `${(0, render_1.formatSize)(data.storageUsedBytes)} / ${(0, render_1.formatSize)(data.storageQuotaBytes)} (${data.usagePercent.toFixed(1)}%)`
+        : (0, render_1.formatSize)(data.storageUsedBytes);
     (0, output_1.emit)((0, render_1.renderKeyValue)([
-        ["used", used],
-        ["quota", total],
-        ["usage", pct],
-        ["tables", String(data.tables)],
-        ["views", String(data.views)],
+        ["Storage", storageLine],
+        ["Tables", String(data.tables)],
+        ["Views", String(data.views)],
     ], tty));
 }

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

@@ -49,23 +49,36 @@ async function handleDbRecoveryDiff(target, opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     const ts = normalizeTimestamp(target);
     const result = await api.db.recover({ appId, target: ts, dryRun: true });
-    renderRecover(result);
+    renderDiff(result);
 }
 async function handleDbRecoveryApply(target, opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     const ts = normalizeTimestamp(target);
-    // PITR 高危：apply 之前先强制 diff 给用户审；--yes 才能跳过
-    const preview = await api.db.recover({ appId, target: ts, dryRun: true });
+    // PITR 高危：TTY 下先 diff 给用户审；--yes 直接执行
     if (!opts.yes && !(0, output_1.isJsonMode)()) {
-        renderRecover(preview);
-        const ok = await confirm(`? Restore ${String(preview.tablesAffected)} table(s) to ${preview.target}? This is IRREVERSIBLE. (y/N) `);
+        const preview = await api.db.recover({ appId, target: ts, dryRun: true });
+        renderDiff(preview);
+        const ok = await confirm(`? Restore database to ${preview.target}? This will overwrite current data. (y/N) `);
         if (!ok) {
             (0, output_1.emit)("Aborted.");
             return;
         }
     }
     const result = await api.db.recover({ appId, target: ts, dryRun: false });
-    renderRecover(result);
+    if ((0, output_1.isJsonMode)()) {
+        // PRD：{"status": "restored", "target": "...", "tables_affected": 2, "elapsed_seconds": 30}
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
+            status: result.status ?? "restored",
+            target: result.target,
+            tablesAffected: result.tablesAffected,
+            elapsedSeconds: result.elapsedSeconds ?? 0,
+        }));
+        return;
+    }
+    const tty = (0, render_1.isStdoutTty)();
+    const prefix = tty ? "✓" : "OK";
+    (0, output_1.emit)(`${prefix} Database restored to ${result.target} ` +
+        `(${String(result.tablesAffected)} tables affected, ${String(result.elapsedSeconds ?? 0)}s elapsed)`);
 }
 // ── helpers ──
 /**
@@ -79,56 +92,90 @@ function normalizeTimestamp(input) {
             next_actions: ["Usage: miaoda db recovery diff|apply <timestamp>"],
         });
     }
-    // YYYY-MM-DD：按 UTC 00:00:00
     if (/^\d{4}-\d{2}-\d{2}$/.test(input)) {
         return new Date(`${input}T00:00:00Z`).toISOString();
     }
-    // YYYY-MM-DD HH:MM[:SS]：本地时间，让 Date 自己解析
     if (/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}(:\d{2})?$/.test(input)) {
         const d = new Date(input.replace(" ", "T"));
         if (Number.isNaN(d.getTime())) {
-            throw new error_1.AppError("INVALID_TIMESTAMP", `invalid timestamp: ${input}`, {
+            throw new error_1.AppError("INVALID_TIMESTAMP", `Invalid timestamp format '${input}'`, {
                 next_actions: [FORMAT_HINT],
             });
         }
         return d.toISOString();
     }
-    // 完整 ISO 8601
     const d = new Date(input);
     if (Number.isNaN(d.getTime())) {
-        throw new error_1.AppError("INVALID_TIMESTAMP", `invalid timestamp: ${input}`, {
+        throw new error_1.AppError("INVALID_TIMESTAMP", `Invalid timestamp format '${input}'`, {
             next_actions: [FORMAT_HINT],
         });
     }
     return d.toISOString();
 }
-function renderRecover(result) {
+// PRD diff 输出（结构化 prose）：
+//   Recovery preview (→ 2026-04-15T10:00:00Z):
+//
+//     tables affected: 2
+//     users:   +3 rows, -1 row, ~5 rows modified
+//     orders:  table will be restored (was dropped at 10:25:00)
+//
+//     estimated time: ~30s
+function renderDiff(result) {
     if ((0, output_1.isJsonMode)()) {
-        (0, output_1.emitOk)(result);
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
+            target: result.target,
+            tablesAffected: result.tablesAffected,
+            changes: result.changes.map((c) => ({
+                table: c.table,
+                inserted: c.inserted,
+                deleted: c.deleted,
+                modified: c.modified,
+                action: c.action,
+                droppedAt: c.droppedAt,
+            })),
+            estimatedSeconds: result.estimatedSeconds ?? 0,
+        }));
         return;
     }
     const tty = (0, render_1.isStdoutTty)();
+    const arrow = tty ? "→" : "->";
     if (result.changes.length === 0) {
-        (0, output_1.emit)(`No tables affected at ${result.target}.`);
+        (0, output_1.emit)(`Recovery preview (${arrow} ${result.target}):\n\n` +
+            `  No changes — database is already at this state.`);
         return;
     }
-    const headers = ["table", "action", "inserted", "deleted", "modified", "dropped_at"];
-    const rows = result.changes.map((c) => [
-        c.table,
-        c.action ?? "—",
-        c.inserted !== undefined ? String(c.inserted) : "—",
-        c.deleted !== undefined ? String(c.deleted) : "—",
-        c.modified !== undefined ? String(c.modified) : "—",
-        c.droppedAt ?? "—",
-    ]);
-    (0, output_1.emit)(tty ? (0, render_1.renderAlignedTable)(headers, rows) : (0, render_1.renderTsv)(headers, rows));
-    if (result.dryRun) {
-        const eta = result.estimatedSeconds !== undefined ? `, eta ~${String(result.estimatedSeconds)}s` : "";
-        (0, output_1.emit)(`(dry-run: ${String(result.tablesAffected)} table(s) affected${eta}; run \`db recovery apply\` to commit)`);
+    const lines = [
+        `Recovery preview (${arrow} ${result.target}):`,
+        "",
+        `  tables affected: ${String(result.tablesAffected)}`,
+    ];
+    for (const c of result.changes) {
+        lines.push(`  ${c.table}:  ${describeChange(c)}`);
+    }
+    if (result.estimatedSeconds !== undefined) {
+        lines.push("");
+        lines.push(`  estimated time: ~${String(result.estimatedSeconds)}s`);
+    }
+    (0, output_1.emit)(lines.join("\n"));
+}
+function describeChange(c) {
+    if (c.action === "restore_table" || c.action === "drop" || c.action === "create") {
+        const ts = c.droppedAt ? ` (was dropped at ${c.droppedAt})` : "";
+        if (c.action === "restore_table")
+            return `table will be restored${ts}`;
+        if (c.action === "drop")
+            return `table will be dropped${ts}`;
+        return `table will be created${ts}`;
     }
-    else {
-        (0, output_1.emit)(`✓ Restored ${String(result.tablesAffected)} table(s) to ${result.target} in ${String(result.elapsedSeconds ?? 0)}s`);
+    const parts = [];
+    if (c.inserted !== undefined && c.inserted !== 0)
+        parts.push(`+${String(c.inserted)} rows`);
+    if (c.deleted !== undefined && c.deleted !== 0) {
+        parts.push(`-${String(c.deleted)} ${c.deleted === 1 ? "row" : "rows"}`);
     }
+    if (c.modified !== undefined && c.modified !== 0)
+        parts.push(`~${String(c.modified)} rows modified`);
+    return parts.length === 0 ? "no changes" : parts.join(", ");
 }
 async function confirm(prompt) {
     const rl = node_readline_1.default.createInterface({ input: process.stdin, output: process.stderr });

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

@@ -42,17 +42,25 @@ async function handleFileQuota(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     const data = await api.file.getStorageQuota({ appId });
     if ((0, output_1.isJsonMode)()) {
-        (0, output_1.emitOk)(data);
+        // 配额未对接（storageQuotaBytes=0）时，quota / usage_percent 字段都不输出
+        const out = {
+            storageUsedBytes: data.storageUsedBytes,
+            files: data.files,
+        };
+        if (data.storageQuotaBytes > 0) {
+            out.storageQuotaBytes = data.storageQuotaBytes;
+            out.usagePercent = data.usagePercent;
+        }
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)(out));
         return;
     }
+    // PRD：单行 "Storage: 150 MB / 1 GB (15%)"；配额未对接时只显示 used
     const tty = (0, render_1.isStdoutTty)();
-    const used = (0, render_1.formatSize)(data.storageUsedBytes);
-    const total = data.storageQuotaBytes > 0 ? (0, render_1.formatSize)(data.storageQuotaBytes) : "—";
-    const pct = data.storageQuotaBytes > 0 ? `${data.usagePercent.toFixed(1)}%` : "—";
+    const storageLine = data.storageQuotaBytes > 0
+        ? `${(0, render_1.formatSize)(data.storageUsedBytes)} / ${(0, render_1.formatSize)(data.storageQuotaBytes)} (${data.usagePercent.toFixed(1)}%)`
+        : (0, render_1.formatSize)(data.storageUsedBytes);
     (0, output_1.emit)((0, render_1.renderKeyValue)([
-        ["used", used],
-        ["quota", total],
-        ["usage", pct],
-        ["files", String(data.files)],
+        ["Storage", storageLine],
+        ["Files", String(data.files)],
     ], tty));
 }

package/dist/utils/output.js

@@ -5,6 +5,7 @@ exports.emit = emit;
 exports.emitError = emitError;
 exports.emitOk = emitOk;
 exports.emitPaged = emitPaged;
+exports.snakeCaseKeys = snakeCaseKeys;
 const config_1 = require("./config");
 const error_1 = require("./error");
 const colors_1 = require("./colors");
@@ -118,6 +119,27 @@ function emitOk(data) {
 function emitPaged(items, nextCursor, hasMore) {
     emit({ data: items, next_cursor: nextCursor, has_more: hasMore });
 }
+/**
+ * 把对象 / 数组里所有字符串 key 从 camelCase 转成 snake_case，递归处理嵌套对象。
+ * 后端 IDL 返回的 JSON 字段是 camelCase（`storageUsedBytes`），CLI 对外（PRD）
+ * 统一 snake_case（`storage_used_bytes`）；emit JSON 前过一遍这个函数。
+ */
+function snakeCaseKeys(input) {
+    if (Array.isArray(input)) {
+        return input.map((item) => snakeCaseKeys(item));
+    }
+    if (input !== null && typeof input === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(input)) {
+            out[camelToSnake(k)] = snakeCaseKeys(v);
+        }
+        return out;
+    }
+    return input;
+}
+function camelToSnake(s) {
+    return s.replace(/[A-Z]/g, (m) => "_" + m.toLowerCase());
+}
 function toErrorInfo(err) {
     if (err instanceof error_1.AppError)
         return err.toJSON();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.2-alpha.4d0ff57",
+  "version": "0.1.2-alpha.9eeb185",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {