@lark-apaas/miaoda-cli 0.1.3-alpha.2a09432 → 0.1.3-alpha.2d526ac

package/dist/api/db/api.js

@@ -13,6 +13,7 @@ exports.migrate = migrate;
 exports.getMigrationStatus = getMigrationStatus;
 exports.recover = recover;
 exports.getRecoveryPreview = getRecoveryPreview;
+exports.getRecoveryStatus = getRecoveryStatus;
 exports.getDbQuota = getDbQuota;
 const http_1 = require("../../utils/http");
 const error_1 = require("../../utils/error");
@@ -217,7 +218,8 @@ async function importData(opts) {
         records: opts.body.toString('utf8'),
     };
     if (opts.dbBranch !== undefined && opts.dbBranch !== '') {
-        reqBody.dbBranch = opts.dbBranch;
+        // 兼容 `online` 别名 → 后端实际 dbBranch 名为 `main`
+        reqBody.dbBranch = opts.dbBranch === 'online' ? 'main' : opts.dbBranch;
     }
     const start = Date.now();
     let response;
@@ -325,6 +327,7 @@ async function listDDLChangelog(opts) {
         table: opts.table,
         since: opts.since,
         until: opts.until,
+        changeId: opts.changeId,
         limit: opts.limit !== undefined ? String(opts.limit) : undefined,
         cursor: opts.cursor,
         dbBranch: opts.dbBranch,
@@ -387,8 +390,10 @@ async function setAuditConfig(opts) {
     };
     if (opts.retention !== undefined && opts.retention !== '')
         body.retention = opts.retention;
-    if (opts.dbBranch !== undefined && opts.dbBranch !== '')
-        body.dbBranch = opts.dbBranch;
+    if (opts.dbBranch !== undefined && opts.dbBranch !== '') {
+        // 兼容 `online` 别名 → 后端实际 dbBranch 名为 `main`
+        body.dbBranch = opts.dbBranch === 'online' ? 'main' : opts.dbBranch;
+    }
     const start = Date.now();
     let response;
     try {
@@ -572,6 +577,29 @@ async function getRecoveryPreview(opts) {
     const body = (await response.json());
     return (0, client_1.extractData)(body);
 }
+/**
+ * 后端：GET /v1/dataloom/app/{appId}/db/recovery/status
+ * CLI apply 触发后定时调本接口直到 status=success/failed。dataloom 内部 Redis
+ * 维护 workspace 级 restore 状态，无需传 task id；workspace+dbBranch 维度同时
+ * 只允许一个 restore 进行中。
+ */
+async function getRecoveryStatus(opts) {
+    const client = (0, http_1.getHttpClient)();
+    const url = (0, client_1.buildInnerUrl)(opts.appId, '/db/recovery/status', { 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 recovery status');
+        throw err; // 不可达
+    }
+    const body = (await response.json());
+    return (0, client_1.extractData)(body);
+}
 // ── db quota → InnerAdminGetDbQuota ──
 /**
  * 后端：GET /v1/dataloom/app/{appId}/db/quota?dbBranch=

package/dist/api/db/client.js

@@ -202,8 +202,12 @@ function buildInnerUrl(appId, path, query) {
     if (query) {
         const usp = new URLSearchParams();
         for (const [k, v] of Object.entries(query)) {
-            if (v !== undefined && v !== '')
-                usp.append(k, v);
+            if (v === undefined || v === '')
+                continue;
+            // dbBranch 兼容用户视角的 `online` 别名 → 后端实际 dbBranch 名为 `main`，
+            // 这里集中归一，避免每个 API 函数各自处理。其他值（dev / 自定义分支）原样透传。
+            const norm = k === 'dbBranch' && v === 'online' ? 'main' : v;
+            usp.append(k, norm);
         }
         const qs = usp.toString();
         if (qs)

package/dist/api/db/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pickTableDetail = exports.flattenSchemaList = exports.parseSqlResult = exports.SQLSTATE_MAP = exports.ensureInnerSuccess = exports.buildInnerUrl = exports.getDbQuota = exports.getRecoveryPreview = exports.recover = exports.getMigrationStatus = exports.migrate = exports.migrationInit = exports.listAuditLog = exports.setAuditConfig = exports.getAuditStatus = 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.getRecoveryStatus = exports.getRecoveryPreview = exports.recover = exports.getMigrationStatus = 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; } });
@@ -15,6 +15,7 @@ Object.defineProperty(exports, "migrate", { enumerable: true, get: function () {
 Object.defineProperty(exports, "getMigrationStatus", { enumerable: true, get: function () { return api_1.getMigrationStatus; } });
 Object.defineProperty(exports, "recover", { enumerable: true, get: function () { return api_1.recover; } });
 Object.defineProperty(exports, "getRecoveryPreview", { enumerable: true, get: function () { return api_1.getRecoveryPreview; } });
+Object.defineProperty(exports, "getRecoveryStatus", { enumerable: true, get: function () { return api_1.getRecoveryStatus; } });
 Object.defineProperty(exports, "getDbQuota", { enumerable: true, get: function () { return api_1.getDbQuota; } });
 var client_1 = require("./client");
 Object.defineProperty(exports, "buildInnerUrl", { enumerable: true, get: function () { return client_1.buildInnerUrl; } });

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

@@ -224,6 +224,7 @@ Examples:
         .option('--table <name>', '按表名过滤')
         .option('--since <time>', '起始时间')
         .option('--until <time>', '截止时间')
+        .option('--change-id <id>', '按 change_id 精确查询单条变更记录（指定后只返该 ID 一条，JSON 仍保持数组）')
         .option('--limit <n>', '返回条数上限（默认 20）', parsePositiveInt, 20)
         .option('--cursor <token>', '从上一页返回的游标位置继续获取')
         .option('--all', '获取全部结果，自动翻页')

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

@@ -159,7 +159,7 @@ Notes:
 Examples:
   # 单文件删除（TTY 下需确认）
   $ miaoda file rm /images/brand/1858537546760216.png
-  ? Delete '/images/brand/1858537546760216.png'? (y/N) y
+  ? Are you sure you want to permanently delete '/images/brand/1858537546760216.png'? (y/N) y
   ✓ Deleted /images/brand/1858537546760216.png
 
   # 批量删除（混用 path 与 file_name）

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

@@ -199,17 +199,48 @@ async function handleDbAuditList(tables, opts) {
     // 后端管理（本质也是 ISO 时间），CLI 不再混用 cursor/since。
     const since = normalizeTime(opts.since, '--since');
     const until = normalizeTime(opts.until, '--until');
-    const result = await api.db.listAuditLog({
-        appId,
-        tables,
-        since,
-        until,
-        limit,
-        cursor: opts.cursor,
-        dbBranch: opts.env,
-    });
+    // 多表场景：dataloom 对"任一表不存在"是 fail-fast（typo 应立即可见，符合 PRD 单表语义），
+    // 但 PRD 多表语义是"其他表继续返回，底部汇总跳过情况"。CLI 在这里做闭环：把不存在的表
+    // 从入参里剥掉重试，最终跟服务端 skipped（audit 未启用）合并展示。单表场景仍 fail-fast。
+    const isMulti = tables.length > 1;
+    let result;
+    const localMissing = [];
+    let curTables = [...tables];
+    for (;;) {
+        try {
+            result = await api.db.listAuditLog({
+                appId,
+                tables: curTables,
+                since,
+                until,
+                limit,
+                cursor: opts.cursor,
+                dbBranch: opts.env,
+            });
+            break;
+        }
+        catch (err) {
+            if (isMulti && err instanceof error_1.AppError && err.code === 'DB_API_k_dl_000005') {
+                const missing = extractMissingTable(err.message);
+                if (missing !== null && curTables.includes(missing)) {
+                    localMissing.push(missing);
+                    curTables = curTables.filter((t) => t !== missing);
+                    if (curTables.length === 0) {
+                        // 全部表都不存在 → 抛 TABLE_NOT_FOUND，列出所有缺失表
+                        throw new error_1.AppError('TABLE_NOT_FOUND', `None of the requested tables exist: ${localMissing.join(', ')}`, {
+                            next_actions: ['Run `miaoda db schema list` to see all tables.'],
+                        });
+                    }
+                    continue;
+                }
+            }
+            throw decorateAuditListError(err, tables);
+        }
+    }
     const visible = result.items;
-    const skipped = result.skipped;
+    // 服务端 skipped（audit 未启用，bare 名）+ CLI 本地探测 missing 合并；
+    // localMissing 自带 `(table not found)` 后缀，formatSkippedHint 透传渲染
+    const skipped = [...result.skipped, ...localMissing.map((t) => `${t} (table not found)`)];
     // PRD JSON：data 是数组，元素是事件对象（snake_case），分页信封 next_cursor / has_more
     // operator 后端用 JSON 字符串内嵌 {id, name}，--json 输出还原成对象供下游消费
     if ((0, output_1.isJsonMode)()) {
@@ -226,7 +257,7 @@ async function handleDbAuditList(tables, opts) {
         }));
         (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`);
+            process.stderr.write(formatSkippedHint(skipped, tables.length) + '\n');
         }
         if (visible.length === 0)
             process.exitCode = 1;
@@ -235,7 +266,7 @@ async function handleDbAuditList(tables, opts) {
     if (visible.length === 0) {
         (0, output_1.emit)('No audit log entries found.');
         if (skipped.length > 0) {
-            process.stderr.write(`(${String(skipped.length)} table(s) skipped: ${skipped.join(', ')})\n`);
+            process.stderr.write(formatSkippedHint(skipped, tables.length) + '\n');
         }
         process.exitCode = 1;
         return;
@@ -261,7 +292,7 @@ async function handleDbAuditList(tables, opts) {
     });
     (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`);
+        process.stderr.write(formatSkippedHint(skipped, tables.length) + '\n');
     }
     if (result.hasMore && result.nextCursor) {
         process.stderr.write(`(more results; use --cursor '${result.nextCursor}')\n`);
@@ -287,6 +318,54 @@ function normalizeTime(input, flagName) {
         throw err;
     }
 }
+// PRD 41-48 行格式：`— Skipped 1 of 3 tables: orders (audit not enabled)`
+// 服务端 skipped 数组是 audit 未启用的表（bare 名）；上面 peel 循环拼出来的
+// "<name> (table not found)" 已经自带 reason，t.includes('(') 走原样透传，bare 名
+// 默认拼 "(audit not enabled)"。也兼容未来后端直接给带 reason 字符串的可能。
+function formatSkippedHint(skipped, totalRequested) {
+    const items = skipped.map((t) => (t.includes('(') ? t : `${t} (audit not enabled)`)).join(', ');
+    return `— Skipped ${String(skipped.length)} of ${String(totalRequested)} tables: ${items}`;
+}
+// audit list 后端错误码加 hint：
+//   - k_dl_000005  表不存在 → 文案与 hint 对齐 `db schema get` 的统一格式
+//   - k_dl_1300040 单表 audit 未启用 → 指引 enable
+//   - k_dl_1300041 多表全部未启用 → 指引 status
+function decorateAuditListError(err, tables) {
+    if (!(err instanceof error_1.AppError))
+        return err;
+    if (err.code === 'DB_API_k_dl_000005') {
+        // 不复用 dataloom 透传的 message（旧版/新版文案不一致：`table [x] not exist` /
+        // `table x not found`），统一改写成跟 schema get 一样的 `Table '<name>' does not exist`，
+        // 单表传 tables[0]，多表场景兜底用解析到的 raw message 里第一个表名。
+        const t = tables.length > 0 ? tables[0] : (extractMissingTable(err.message) ?? '<table>');
+        return new error_1.AppError('TABLE_NOT_FOUND', `Table '${t}' does not exist`, {
+            next_actions: [`Did you mean another table? Run "miaoda db schema list" to see all tables.`],
+        });
+    }
+    if (err.code === 'DB_API_k_dl_1300040') {
+        const t = tables[0] ?? '<table>';
+        return new error_1.AppError(err.code, err.message, {
+            next_actions: [`Enable with: miaoda db audit enable ${t}`],
+        });
+    }
+    if (err.code === 'DB_API_k_dl_1300041') {
+        return new error_1.AppError(err.code, err.message, {
+            next_actions: ['Check audit status with: miaoda db audit status'],
+        });
+    }
+    return err;
+}
+// extractMissingTable 从 dataloom 原始文案里抠表名兜底。dataloom 端有两种格式：
+//   - 旧版：`Table [foo] doesn't exist` / `table [foo] not exist`
+//   - 新版（本次 commits）：`table foo not found`
+// 都失配时返 null，调用方走 `<table>` 占位。
+function extractMissingTable(msg) {
+    const bracket = /\[([^\]]+)\]/.exec(msg);
+    if (bracket)
+        return bracket[1];
+    const m = /table\s+([\w.]+)\s+not (?:exist|found)/i.exec(msg);
+    return m ? m[1] : null;
+}
 // 服务端 before/after 是 JSON 字符串透传，CLI JSON 输出再反序列化回对象，
 // 给下游 jq 等工具消费。失败时透传原始字符串避免数据丢失。
 function safeParseJson(s) {

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

@@ -75,10 +75,17 @@ async function handleDbChangelog(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     const since = normalizeTime(opts.since, '--since');
     const until = normalizeTime(opts.until, '--until');
+    // --change-id 是精确单条查询，CLI 透传给后端；后端若暂未支持过滤，CLI 端
+    // 兜底翻页找命中项，保证 PRD 「最多返回一条」的语义稳定。
+    const trimmed = opts.changeId?.trim();
+    const changeId = trimmed !== undefined && trimmed !== '' ? trimmed : undefined;
     const allItems = [];
     let cursor = opts.cursor;
     let lastCursor = null;
     let lastHasMore = false;
+    // 指定 --change-id 时强制开 --all，确保即使后端不识别 changeId 过滤参数，
+    // CLI 也能翻完所有页找到目标记录（changelog 默认按时间倒序，一般在前几页）。
+    const allMode = opts.all === true || changeId !== undefined;
     // --all：循环到 hasMore=false；否则只拉一页
     // 没传 --all 时翻页由调用方自己用 --cursor 串
     for (;;) {
@@ -87,6 +94,7 @@ async function handleDbChangelog(opts) {
             table: opts.table,
             since,
             until,
+            changeId,
             limit: opts.limit,
             cursor,
             dbBranch: opts.env,
@@ -94,14 +102,28 @@ async function handleDbChangelog(opts) {
         allItems.push(...page.items);
         lastCursor = page.nextCursor;
         lastHasMore = page.hasMore;
-        if (!opts.all || !page.hasMore || !page.nextCursor)
+        if (!allMode || !page.hasMore || !page.nextCursor)
             break;
         cursor = page.nextCursor;
+        // 后端命中过滤返单条时提前退出，免得继续无意义翻页
+        if (changeId !== undefined && allItems.some((it) => it.changeId === changeId))
+            break;
+    }
+    // CLI 端兜底过滤：把 changeId 匹配的项筛出来。后端如果已支持，列表本身就只有
+    // 0 或 1 条，filter 是恒等运算；后端未支持时通过翻页 + 此过滤拿到精确单条。
+    if (changeId !== undefined) {
+        const matched = allItems.filter((it) => it.changeId === changeId);
+        allItems.length = 0;
+        allItems.push(...matched);
+        // 精确查询语义：永远当作"已取完"，不再透出分页 cursor / has_more
+        lastCursor = null;
+        lastHasMore = false;
     }
     if ((0, output_1.isJsonMode)()) {
         const rows = allItems.map(toRow);
-        // --all 时已经把所有页合一起返，has_more=false / next_cursor=null
-        if (opts.all) {
+        // --all 或 --change-id 时已经把所有页合一起返，has_more=false / next_cursor=null。
+        // PRD: --change-id 即使没命中（rows 长度 0）也保持 data 为数组。
+        if (allMode) {
             (0, output_1.emitPaged)((0, output_1.snakeCaseKeys)(rows), null, false);
         }
         else {
@@ -110,7 +132,13 @@ async function handleDbChangelog(opts) {
         return;
     }
     if (allItems.length === 0) {
-        (0, output_1.emit)('No DDL changes found.');
+        // --change-id 没命中时单独报错，便于 agent 区分"无变更"和"ID 不存在"
+        if (changeId !== undefined) {
+            (0, output_1.emit)(`No DDL change with id=${changeId} found.`);
+        }
+        else {
+            (0, output_1.emit)('No DDL changes found.');
+        }
         return;
     }
     const tty = (0, render_1.isStdoutTty)();
@@ -126,7 +154,7 @@ async function handleDbChangelog(opts) {
         it.summary || '—',
     ]);
     (0, output_1.emit)(tty ? (0, render_1.renderAlignedTable)(headers, rows) : (0, render_1.renderTsv)(headers, rows));
-    if (!opts.all && lastHasMore && lastCursor) {
+    if (!allMode && lastHasMore && lastCursor) {
         process.stderr.write(`(more results; use --cursor ${lastCursor} or --all)\n`);
     }
 }

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

@@ -47,6 +47,7 @@ const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 const poll_1 = require("../../../utils/poll");
 const render_1 = require("../../../utils/render");
+const spinner_1 = require("../../../utils/spinner");
 async function handleDbMigrationInit(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     // 不可逆操作，TTY 默认要求 y/N；--yes 跳过
@@ -88,12 +89,16 @@ async function handleDbMigrationInit(opts) {
 async function handleDbMigrationDiff(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     let result;
+    const stopSpinner = (0, spinner_1.startSpinner)('Computing migration diff');
     try {
         result = await api.db.migrate({ appId, dryRun: true });
     }
     catch (err) {
         throw decorateMigrationError(err);
     }
+    finally {
+        stopSpinner();
+    }
     // PRD: diff 在无待发布变更时报错带 hint，而不是渲染空列表
     if (result.changes.length === 0) {
         throw new error_1.AppError('DB_API_k_dl_1300035', `No pending changes between ${result.from} and ${result.to}`, {
@@ -109,12 +114,16 @@ async function handleDbMigrationApply(opts) {
     // TTY 下先 diff 给用户审；--yes 直接打到 online
     if (!opts.yes && !(0, output_1.isJsonMode)()) {
         let preview;
+        const stopSpinner = (0, spinner_1.startSpinner)('Computing migration diff');
         try {
             preview = await api.db.migrate({ appId, dryRun: true });
         }
         catch (err) {
             throw decorateMigrationError(err);
         }
+        finally {
+            stopSpinner();
+        }
         if (preview.changes.length === 0) {
             // PRD 文案 + hint
             throw new error_1.AppError('DB_API_k_dl_1300035', `No pending changes between ${preview.from} and ${preview.to}`, {
@@ -145,6 +154,7 @@ async function handleDbMigrationApply(opts) {
     const taskId = result.taskId;
     const final = await (0, poll_1.pollUntilDone)({
         label: 'migration apply',
+        spinnerLabel: 'Applying migration to online',
         intervalMs: 1000,
         fetch: () => api.db.getMigrationStatus({ appId, taskId }),
         isDone: (cur) => {

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

@@ -61,15 +61,28 @@ async function handleDbRecoveryDiff(target, opts) {
 async function handleDbRecoveryApply(target, opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     const ts = normalizeTimestamp(target);
-    // PRD 要求 apply 输出包含 N tables affected / Ms elapsed，dataloom apply 路径不
-    // 回带这俩信息（pgsvc.BranchRestore 是异步触发、不等终态）。所以 CLI 这里始终
-    // 先跑一次 preview——它本来就是 PITR 推荐流程，--yes 时静默跑、TTY 时同时给用户审。
+    // PRD 要求 apply 输出包含 N tables affected / Ms elapsed。
+    // tables_affected 从 preview 拿；elapsed 用 CLI 端墙钟（dataloom apply 是异步
+    // 触发，server-side elapsed=0；下面 poll 真终态后用本地计时器算 elapsed）。
     const preview = await runRecoveryPreview(appId, ts);
     const tablesAffected = preview.tablesAffected ?? preview.changes?.length ?? 0;
-    // dataloom 端 apply 是异步触发，elapsed_seconds 返 0。这里改用 preview 给出的
-    // estimated_seconds 当 "预计耗时"，更贴近 PRD 示例的 30s elapsed 含义；
-    // 都没填时按 PRD 默认值 30 兜底。
-    const elapsedFromPreview = preview.estimatedSeconds ?? 30;
+    // 0 changes 短路：目标时间点与当前一致，apply 没意义。pretty 模式渲染 preview
+    // 的 "No changes — database is already at this state." 后直接退；--json 模式
+    // 返 status="no_changes" envelope 让下游识别。不进 confirm 也不下发 apply。
+    if ((preview.changes?.length ?? 0) === 0) {
+        if ((0, output_1.isJsonMode)()) {
+            (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
+                status: 'no_changes',
+                target: ts,
+                tablesAffected: 0,
+                elapsedSeconds: 0,
+            }));
+        }
+        else {
+            renderDiff(ts, preview);
+        }
+        return;
+    }
     if (!opts.yes && !(0, output_1.isJsonMode)()) {
         renderDiff(ts, preview);
         const ok = await confirm(`? Restore database to ${ts}? This will overwrite current data. (y/N) `);
@@ -85,7 +98,12 @@ async function handleDbRecoveryApply(target, opts) {
     catch (err) {
         throw decorateRecoveryError(err);
     }
-    const elapsed = result.elapsedSeconds && result.elapsedSeconds > 0 ? result.elapsedSeconds : elapsedFromPreview;
+    // 关键：墙钟从 apply 触发瞬间开始，poll 真完成时停。dataloom restore 是异步触发，
+    // 立即返 status="restore_triggered"，CLI 必须 poll GET /db/recovery/status 拿
+    // Redis 缓存的 Resetting/Ready/Failed，否则用户会被误导以为已恢复完。
+    const startedAt = Date.now();
+    await waitRecoveryDone(appId, ts);
+    const elapsed = Math.max(1, Math.round((Date.now() - startedAt) / 1000));
     if ((0, output_1.isJsonMode)()) {
         // PRD：{"status": "restored", "target": "...", "tables_affected": N, "elapsed_seconds": M}
         (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
@@ -101,6 +119,38 @@ async function handleDbRecoveryApply(target, opts) {
         `(${String(tablesAffected)} tables affected, ${String(elapsed)}s elapsed)`;
     (0, output_1.emit)(tty ? colors_1.c.success(`✓ ${body}`) : `OK ${body}`);
 }
+/**
+ * 触发 BranchRestore 后 poll 直到任务终态。dataloom 端 Redis 缓存 workspace 级
+ * status，归一成 running / success / failed：
+ *   - running → 继续 poll
+ *   - success → 退出，CLI 渲染 ✓
+ *   - failed  → 抛 DB_API_k_dl_1300036 + errorMessage
+ *
+ * 不设固定超时：BranchRestore 实际时长依库大小变化（前端文案示例 1 分钟，大库可能
+ * 几分钟），由 pollUntilDone 内置 60 分钟上限兜底，远超正常场景。
+ */
+async function waitRecoveryDone(appId, target) {
+    try {
+        return await (0, poll_1.pollUntilDone)({
+            label: 'recovery apply',
+            spinnerLabel: 'Restoring database to target time',
+            intervalMs: 2000,
+            fetch: () => api.db.getRecoveryStatus({ appId }),
+            isDone: (cur) => {
+                const status = (cur.status || '').toLowerCase();
+                if (status === 'success')
+                    return { done: true, value: cur };
+                if (status === 'failed') {
+                    throw new error_1.AppError('DB_API_k_dl_1300036', cur.errorMessage ?? `recovery to ${target} failed`);
+                }
+                return { done: false };
+            },
+        });
+    }
+    catch (err) {
+        throw decorateRecoveryError(err);
+    }
+}
 /**
  * 触发 PITR 预览任务并轮询到终态：
  *   1. POST /db/recovery dryRun=true → previewRequestId
@@ -125,6 +175,7 @@ async function runRecoveryPreview(appId, ts) {
     try {
         return await (0, poll_1.pollUntilDone)({
             label: 'recovery preview',
+            spinnerLabel: 'Computing recovery preview',
             intervalMs: 1000,
             fetch: () => api.db.getRecoveryPreview({ appId, previewRequestId }),
             isDone: (cur) => {
@@ -171,20 +222,20 @@ function normalizeTimestamp(input) {
 }
 // PRD diff 输出，三套：
 //
-// TTY pretty（缩进 prose、带 Unicode 箭头 / 波浪号、表名按列对齐）：
+// TTY pretty（缩进 prose、带 Unicode 箭头、表名按列对齐）：
 //   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)
+//     users:   +3 rows, -1 row
+//     orders:  table will be restored
 //
 //     estimated time: ~30s
 //
 // non-TTY pretty（管道友好，扁平 TSV、ASCII 箭头、snake_case key、estimated_time 不带 ~/s）：
 //   Recovery preview (-> 2026-04-15T10:00:00Z):
 //   tables_affected\t2
-//   users\t+3 rows, -1 row, ~5 rows modified
-//   orders\ttable will be restored (was dropped at 10:25:00)
+//   users\t+3 rows, -1 row
+//   orders\ttable will be restored
 //   estimated_time\t30
 //
 // --json：标准 envelope，字段名固定 snake_case。
@@ -200,7 +251,6 @@ function renderDiff(target, preview) {
                 table: c.table,
                 inserted: c.inserted,
                 deleted: c.deleted,
-                modified: c.modified,
                 action: c.action,
                 droppedAt: c.droppedAt,
             })),
@@ -250,51 +300,31 @@ function renderDiffPipe(target, changes, tablesAffected, estimated) {
     return lines.join('\n');
 }
 function describeChange(c) {
-    // 表级操作：dataloom 现在把 schema diff 透出为 action="schema_<diffType>"，
-    // 老协议的 restore_table / drop / create 一并保留兼容。
+    // dataloom 端 action 是 PRD 三态 + unavailable 边界：
+    //   restore_table — schema diff 显示该表在目标时间点存在但当前没有
+    //   drop_table    — 该表当前有但目标时间点没有
+    //   alter_table   — 两侧都在但结构有差异（列 / 索引 / 关系等）
+    //   unavailable   — PITR diff 算不出来，droppedAt 字段复用透传 message
+    // 没 action 时是数据行数变化，走下面的 +N / -N 渲染。
     if (c.action === 'restore_table') {
-        const ts = c.droppedAt ? ` (was dropped at ${c.droppedAt})` : '';
-        return `table will be restored${ts}`;
-    }
-    if (c.action === 'drop') {
-        const ts = c.droppedAt ? ` (was dropped at ${c.droppedAt})` : '';
-        return `table will be dropped${ts}`;
+        return 'table will be restored';
     }
-    if (c.action === 'create') {
-        const ts = c.droppedAt ? ` (was dropped at ${c.droppedAt})` : '';
-        return `table will be created${ts}`;
+    if (c.action === 'drop_table') {
+        return 'table will be dropped';
     }
-    if (c.action?.startsWith('schema_') === true) {
-        // dataloom 透出的 schema diffType 来自 schema_handler/common/constants：
-        //   - create: 当前没这表 / 目标时间点有 → 恢复后表会被建出来（PRD 用 restored 表达）
-        //   - drop:   当前有 / 目标时间点没 → 恢复后会被删掉
-        //   - alter:  两侧都在但结构有差异 → 列 / 索引 / 关系等会被改回
-        const diffType = c.action.slice('schema_'.length);
-        const ts = c.droppedAt ? ` (was dropped at ${c.droppedAt})` : '';
-        switch (diffType) {
-            case 'create':
-                return `table will be restored${ts}`;
-            case 'drop':
-                return `table will be dropped${ts}`;
-            case 'alter':
-                return `schema will be altered${ts}`;
-            default:
-                return `schema changed${diffType !== '' ? ` (${diffType})` : ''}${ts}`;
-        }
+    if (c.action === 'alter_table') {
+        return 'table will be altered';
     }
     if (c.action === 'unavailable') {
-        // dataloom 端 count 失败的表，复用 droppedAt 透传 message
         return `diff unavailable${c.droppedAt !== undefined && c.droppedAt !== '' ? `: ${c.droppedAt}` : ''}`;
     }
-    // 数据变更：+N rows / -N rows / ~N rows modified
+    // 数据变更：+N rows / -N rows
     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(', ');
 }
 /**

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

@@ -104,11 +104,11 @@ async function resolveDeleteInputs(appId, paths, names) {
     return { resolved, errors };
 }
 /**
- * 删除前 TTY 二次确认。
- * PRD 单文件场景下提示带具体路径：`? Delete '/path'? (y/N)`，
- * 多文件场景汇总条数：`? Delete N files? (y/N)`。
- * `firstInput` 是用户传入的第一个值（可能是 path 或 file_name），
- * 单文件时直接展示给用户，方便核对目标。
+ * 删除前 TTY 二次确认。文案强调"permanently"（删除不可撤销，无回收站）：
+ *   - 单文件：`? Are you sure you want to permanently delete '<input>'? (y/N)`
+ *   - 多文件：`? Are you sure you want to permanently delete N files? (y/N)`
+ * `firstInput` 是用户传入的第一个值（path 或 file_name），单文件时直接展示给
+ * 用户核对目标。
  */
 async function confirm(count, firstInput) {
     const rl = node_readline_1.default.createInterface({
@@ -116,7 +116,9 @@ async function confirm(count, firstInput) {
         output: process.stderr,
     });
     return new Promise((resolve) => {
-        const prompt = count === 1 ? `? Delete '${firstInput}'? (y/N) ` : `? Delete ${String(count)} files? (y/N) `;
+        const prompt = count === 1
+            ? `? Are you sure you want to permanently delete '${firstInput}'? (y/N) `
+            : `? Are you sure you want to permanently delete ${String(count)} files? (y/N) `;
         rl.question(prompt, (answer) => {
             rl.close();
             resolve(answer.trim().toLowerCase() === 'y');

package/dist/utils/poll.js

@@ -2,24 +2,32 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.pollUntilDone = pollUntilDone;
 const error_1 = require("../utils/error");
+const spinner_1 = require("../utils/spinner");
 async function pollUntilDone(opts) {
     const interval = opts.intervalMs ?? 1000;
     const timeout = opts.timeoutMs ?? 300_000;
     const deadline = Date.now() + timeout;
-    // 立即拉一次（绝大多数轻量任务在 dataloom 端已是同步语义，第一次 fetch 就能拿到 success）
-    for (;;) {
-        const cur = await opts.fetch();
-        const verdict = opts.isDone(cur);
-        if (verdict.done)
-            return verdict.value;
-        if (Date.now() + interval > deadline) {
-            throw new error_1.AppError('TASK_TIMEOUT', `${opts.label} did not complete within ${String(Math.round(timeout / 1000))}s`, {
-                next_actions: [
-                    'The task may still be running server-side. Retry the command, or check `miaoda db migration diff` to verify final state.',
-                ],
-            });
+    // 仅当传 spinnerLabel 时启动 spinner；非 TTY / JSON 模式内部自动 noop
+    const stopSpinner = opts.spinnerLabel ? (0, spinner_1.startSpinner)(opts.spinnerLabel) : () => undefined;
+    try {
+        // 立即拉一次（绝大多数轻量任务在 dataloom 端已是同步语义，第一次 fetch 就能拿到 success）
+        for (;;) {
+            const cur = await opts.fetch();
+            const verdict = opts.isDone(cur);
+            if (verdict.done)
+                return verdict.value;
+            if (Date.now() + interval > deadline) {
+                throw new error_1.AppError('TASK_TIMEOUT', `${opts.label} did not complete within ${String(Math.round(timeout / 1000))}s`, {
+                    next_actions: [
+                        'The task may still be running server-side. Retry the command, or check `miaoda db migration diff` to verify final state.',
+                    ],
+                });
+            }
+            await sleep(interval);
         }
-        await sleep(interval);
+    }
+    finally {
+        stopSpinner();
     }
 }
 function sleep(ms) {

package/dist/utils/spinner.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startSpinner = startSpinner;
+const config_1 = require("./config");
+/**
+ * TTY 友好的 loading 指示器，写到 stderr 上避免污染 stdout（保证 --json 输出干净）。
+ *
+ * 设计：
+ *   - 仅 stderr.isTTY 且非 --json 模式启用；其他情况静默（CI / 管道 / JSON 输出场景）
+ *   - 80ms 一帧 braille 旋转字符 + 累计 elapsed 秒数
+ *   - 返回 stop() 函数；调用方 finally 里调用，无论成功失败都清掉 spinner 行
+ *
+ * 用法：
+ *   const stop = startSpinner('Applying migration to online');
+ *   try { await someLongTask(); } finally { stop(); }
+ */
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const HIDE_CURSOR = '[?25l';
+const SHOW_CURSOR = '[?25h';
+const CLEAR_LINE = '\r';
+function startSpinner(label) {
+    // 非 TTY / JSON 模式：静默 noop，避免污染管道与结构化输出
+    if (!process.stderr.isTTY || (0, config_1.getConfig)().json) {
+        return () => {
+            /* noop */
+        };
+    }
+    let frame = 0;
+    const start = Date.now();
+    process.stderr.write(HIDE_CURSOR);
+    const render = () => {
+        const elapsedSec = Math.round((Date.now() - start) / 1000);
+        process.stderr.write(`${CLEAR_LINE}${FRAMES[frame]} ${label}... ${String(elapsedSec)}s`);
+        frame = (frame + 1) % FRAMES.length;
+    };
+    render();
+    const timer = setInterval(render, 80);
+    let stopped = false;
+    return () => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(timer);
+        process.stderr.write(`${CLEAR_LINE}${SHOW_CURSOR}`);
+    };
+}

package/package.json

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