@lark-apaas/miaoda-cli 0.1.2-alpha.4d0ff57 → 0.1.2-alpha.55feccd

package/dist/api/db/api.js

@@ -5,7 +5,9 @@ exports.getSchema = getSchema;
 exports.importData = importData;
 exports.exportData = exportData;
 exports.listDDLChangelog = listDDLChangelog;
+exports.getAuditStatus = getAuditStatus;
 exports.setAuditConfig = setAuditConfig;
+exports.listAuditLog = listAuditLog;
 exports.migrationInit = migrationInit;
 exports.migrate = migrate;
 exports.recover = recover;
@@ -332,13 +334,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)();
@@ -369,6 +393,51 @@ async function setAuditConfig(opts) {
     }
     return data.status;
 }
+// ── db audit log → InnerAdminListAuditLog ──
+/**
+ * 后端：GET /v1/dataloom/app/{appId}/db/audit/log?tables=&since=&until=&limit=&cursor=&dbBranch=
+ *
+ * 走 admin-inner 接口而不是 InnerAdminExecuteSQL 直接 SELECT pg_audit：
+ *   - operator 在 details JSONB 内是 user_id，服务端解析成 username
+ *   - summary 后端按 type + before/after diff 合成（pg_audit 表无此列）
+ *   - before/after JSONB 后端 JSON.stringify 后透传字符串，CLI 按需 parse
+ *
+ * 多表用逗号拼接走 query；后端按 target_table IN (...) 一次查。skipped 字段返
+ * 多表中无记录的表名，便于 CLI 展示 hint。
+ */
+async function listAuditLog(opts) {
+    if (opts.tables.length === 0) {
+        throw new error_1.AppError("ARGS_INVALID", "at least one table is required");
+    }
+    const client = (0, http_1.getHttpClient)();
+    const url = (0, client_1.buildInnerUrl)(opts.appId, "/db/audit/log", {
+        tables: opts.tables.join(","),
+        since: opts.since,
+        until: opts.until,
+        limit: opts.limit !== undefined ? String(opts.limit) : undefined,
+        cursor: opts.cursor,
+        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 list audit log");
+        throw err; // 不可达
+    }
+    const body = (await response.json());
+    const data = (0, client_1.extractData)(body);
+    return {
+        items: data.items ?? [],
+        nextCursor: data.nextCursor && data.nextCursor !== "" ? data.nextCursor : null,
+        hasMore: Boolean(data.hasMore),
+        skipped: data.skipped ?? [],
+    };
+}
 // ── db migration → InnerAdminMigrationInit / InnerAdminMigrate ──
 /**
  * 后端：POST /v1/dataloom/app/{appId}/db/enableMultiEnv

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,13 +1,15 @@
 "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.listAuditLog = 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, "listAuditLog", { enumerable: true, get: function () { return api_1.listAuditLog; } });
 Object.defineProperty(exports, "migrationInit", { enumerable: true, get: function () { return api_1.migrationInit; } });
 Object.defineProperty(exports, "migrate", { enumerable: true, get: function () { return api_1.migrate; } });
 Object.defineProperty(exports, "recover", { enumerable: true, get: function () { return api_1.recover; } });

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

@@ -40,98 +40,113 @@ exports.handleDbAuditList = handleDbAuditList;
 const api = __importStar(require("../../../api/index"));
 const index_1 = require("../../../api/file/index");
 const shared_1 = require("../../../cli/commands/shared");
+const colors_1 = require("../../../utils/colors");
 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);
-    const status = await api.db.setAuditConfig({
-        appId,
-        table,
-        enabled: true,
-        retention,
-        dbBranch: opts.env,
-    });
+    let status;
+    try {
+        status = await api.db.setAuditConfig({
+            appId,
+            table,
+            enabled: true,
+            retention,
+            dbBranch: opts.env,
+        });
+    }
+    catch (err) {
+        // PRD: 重复 enable 报错时附带 hint，引导用户去 status 看 retention 或换值更新
+        if (err instanceof error_1.AppError && err.code === "DB_API_k_dl_1300030") {
+            throw new error_1.AppError(err.code, err.message, {
+                next_actions: [
+                    `Use \`miaoda db audit status ${table}\` to check current retention, or run this command with a different --retention to update.`,
+                ],
+            });
+        }
+        throw err;
+    }
+    // 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";
+    // c.highlight 内部按 TTY/NO_COLOR/FORCE_COLOR 自动决定是否染色，无需再判 tty
+    const tableLabel = colors_1.c.highlight(`'${status.table}'`);
+    (0, output_1.emit)(`${prefix} Audit enabled for table ${tableLabel} (retention: ${status.retention ?? retention})`);
 }
 async function handleDbAuditDisable(table, opts) {
     if (!table) {
@@ -140,17 +155,34 @@ async function handleDbAuditDisable(table, opts) {
         });
     }
     const appId = (0, shared_1.resolveAppId)(opts);
-    const status = await api.db.setAuditConfig({
-        appId,
-        table,
-        enabled: false,
-        dbBranch: opts.env,
-    });
+    let status;
+    try {
+        status = await api.db.setAuditConfig({
+            appId,
+            table,
+            enabled: false,
+            dbBranch: opts.env,
+        });
+    }
+    catch (err) {
+        // PRD: 重复 disable / 未启用就 disable 报错时附带 hint，引导用户去看哪些表已开启
+        if (err instanceof error_1.AppError && err.code === "DB_API_k_dl_1300031") {
+            throw new error_1.AppError(err.code, err.message, {
+                next_actions: ["Use `miaoda db audit status` to see which tables have audit enabled."],
+            });
+        }
+        throw err;
+    }
     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 ${colors_1.c.highlight(`'${status.table}'`)}`);
 }
 async function handleDbAuditList(tables, opts) {
     if (tables.length === 0) {
@@ -161,36 +193,39 @@ async function handleDbAuditList(tables, opts) {
         });
     }
     const appId = (0, shared_1.resolveAppId)(opts);
-    const limit = opts.limit ?? 50;
-    // since 优先级：opts.cursor（前一页末条 event_time）> opts.since
-    const sinceRaw = opts.cursor ?? opts.since;
-    const since = normalizeTime(sinceRaw, "--since/--cursor");
+    const limit = opts.limit ?? 20;
+    // 时间字段归一化为 ISO 8601 UTC（服务端按 event_time 字段比较）。cursor 由
+    // 后端管理（本质也是 ISO 时间），CLI 不再混用 cursor/since。
+    const since = normalizeTime(opts.since, "--since");
     const until = normalizeTime(opts.until, "--until");
-    const inList = tables.map((t) => `'${escapeSqlLiteral(t)}'`).join(",");
-    const whereParts = [`target_table IN (${inList})`];
-    if (since !== undefined)
-        whereParts.push(`event_time >= '${since}'`);
-    if (until !== undefined)
-        whereParts.push(`event_time <= '${until}'`);
-    const sql = `SELECT event_id, event_time, target_table, type, operator, summary, details ` +
-        `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));
+    const result = await api.db.listAuditLog({
+        appId,
+        tables,
+        since,
+        until,
+        limit,
+        cursor: opts.cursor,
+        dbBranch: opts.env,
+    });
+    const visible = result.items;
+    const skipped = result.skipped;
+    // 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((it) => ({
+            event_id: it.eventId,
+            event_time: it.eventTime,
+            target_table: it.targetTable,
+            type: it.type,
+            operator: it.operator,
+            summary: it.summary,
+            // before/after 服务端是 JSON 字符串，反序列化回结构化对象供下游消费
+            ...(it.before !== undefined ? { before: safeParseJson(it.before) } : {}),
+            ...(it.after !== undefined ? { after: safeParseJson(it.after) } : {}),
+        }));
+        (0, output_1.emitPaged)(items, result.nextCursor, result.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,47 +239,47 @@ 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)(it.eventTime, tty);
+        // event_id 完整透传——PRD 截图里的 "..." 只是文档省略写法，不是 CLI 行为
+        const cells = [eventTime, it.type, it.eventId, it.operator || "—", it.summary];
+        return isMultiTable ? [it.targetTable, ...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`);
     }
-    if (hasMore && nextCursor) {
-        process.stderr.write(`(more results; use --cursor '${nextCursor}')\n`);
+    if (result.hasMore && result.nextCursor) {
+        process.stderr.write(`(more results; use --cursor '${result.nextCursor}')\n`);
     }
 }
 // ── helpers ──
 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();
     }
     const ms = (0, index_1.parseTimeFilterMs)(input, flagName);
     return new Date(ms).toISOString();
 }
-function collectSelectRows(results) {
-    const out = [];
-    for (const r of results) {
-        const parsed = (0, index_2.parseSqlResult)(r);
-        if (parsed.kind === "select")
-            out.push(...parsed.rows);
-    }
-    return out;
+// 服务端 before/after 是 JSON 字符串透传，CLI JSON 输出再反序列化回对象，
+// 给下游 jq 等工具消费。失败时透传原始字符串避免数据丢失。
+function safeParseJson(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return s;
+    }
 }
-/**
- * SQL 字符串字面量转义。仅处理单引号；表名 / 时间戳由调用方控制范围（白名单或
- * 严格 ISO 8601 正则），不在此函数内做。
- */
-function escapeSqlLiteral(s) {
-    return s.replace(/'/g, "''");
+// PRD 输出 enabled 列用 yes/no 而非 true/false
+function boolToYesNo(b) {
+    return b ? "yes" : "no";
 }

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.55feccd",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {