@lark-apaas/miaoda-cli 0.1.3-alpha.fc1e1a9 → 0.1.3-beta.33b7ba5

package/dist/api/db/api.js

@@ -48,8 +48,13 @@ async function mapDbHttpError(err, url, ctx, opts) {
                     (0, client_1.extractData)(body); // 业务 code 命中 → 抛 AppError；不命中走兜底
                 }
                 catch (appErr) {
-                    if (appErr instanceof error_1.AppError && opts?.onErrorBody) {
-                        opts.onErrorBody(body, appErr);
+                    if (appErr instanceof error_1.AppError) {
+                        // env 上下文存在时把"env not exist"系列错误统一重写成 UNKNOWN_ENV_VALUE
+                        // —— 用户视角 vocab 错和 state 错都是「这个 env 不能用」，文案统一更好理解。
+                        const decorated = (0, client_1.decorateEnvError)(appErr, opts?.env);
+                        if (opts?.onErrorBody)
+                            opts.onErrorBody(body, decorated);
+                        throw decorated;
                     }
                     throw appErr;
                 }
@@ -104,6 +109,7 @@ async function execSql(opts) {
     catch (err) {
         (0, client_1.traceHttp)('POST', url, start, err instanceof http_client_1.HttpError ? err.response : undefined, err);
         await mapDbHttpError(err, url, 'Failed to execute SQL', {
+            env: opts.dbBranch,
             onErrorBody: attachSqlPartialResults,
             // SQL 路径单独的超时文案：PG 的 statement_timeout 会回滚整条事务，所以这里
             // 明示「事务已回滚、没有改动落地」，并把 hint 引导到「简化 SQL / 加 LIMIT / 拆条」。
@@ -191,7 +197,7 @@ async function getSchema(opts) {
     }
     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 schema');
+        await mapDbHttpError(err, url, 'Failed to get schema', { env: opts.dbBranch });
         throw err; // 不可达
     }
     const body = (await response.json());
@@ -218,7 +224,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;
@@ -228,7 +235,7 @@ async function importData(opts) {
     }
     catch (err) {
         (0, client_1.traceHttp)('POST', url, start, err instanceof http_client_1.HttpError ? err.response : undefined, err);
-        await mapDbHttpError(err, url, 'Failed to import data');
+        await mapDbHttpError(err, url, 'Failed to import data', { env: opts.dbBranch });
         throw err; // 不可达
     }
     // 后端 InnerAdminImportData 响应里 data 直接返 {tableName, recordCount, durationMs}
@@ -267,7 +274,7 @@ async function exportData(opts) {
     }
     catch (err) {
         (0, client_1.traceHttp)('POST', url, start, err instanceof http_client_1.HttpError ? err.response : undefined, err);
-        await mapDbHttpError(err, url, 'Failed to export data');
+        await mapDbHttpError(err, url, 'Failed to export data', { env: opts.dbBranch });
         throw err; // 不可达
     }
     // 成功路径：响应 body 通常是原始 CSV/SQL/JSON 字节，但部分错误场景下网关会返
@@ -326,6 +333,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,
@@ -338,7 +346,7 @@ async function listDDLChangelog(opts) {
     }
     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 DDL changelog');
+        await mapDbHttpError(err, url, 'Failed to list DDL changelog', { env: opts.dbBranch });
         throw err; // 不可达
     }
     const body = (await response.json());
@@ -368,7 +376,7 @@ async function getAuditStatus(opts) {
     }
     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');
+        await mapDbHttpError(err, url, 'Failed to get audit status', { env: opts.dbBranch });
         throw err; // 不可达
     }
     const respBody = (await response.json());
@@ -388,8 +396,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 {
@@ -398,7 +408,7 @@ async function setAuditConfig(opts) {
     }
     catch (err) {
         (0, client_1.traceHttp)('POST', url, start, err instanceof http_client_1.HttpError ? err.response : undefined, err);
-        await mapDbHttpError(err, url, 'Failed to set audit config');
+        await mapDbHttpError(err, url, 'Failed to set audit config', { env: opts.dbBranch });
         throw err; // 不可达
     }
     const respBody = (await response.json());
@@ -426,7 +436,9 @@ async function listAuditLog(opts) {
     }
     const client = (0, http_1.getHttpClient)();
     const url = (0, client_1.buildInnerUrl)(opts.appId, '/db/audit/log', {
-        tables: opts.tables.join(','),
+        // IDL `Tables list<string>` 走重复 query key（?tables=A&tables=B）—— join(',')
+        // 会让 Hertz/Kitex 网关绑成 ["A,B"] 单元素切片，命中单表错误分支报错文案错乱。
+        tables: opts.tables,
         since: opts.since,
         until: opts.until,
         limit: opts.limit !== undefined ? String(opts.limit) : undefined,
@@ -441,7 +453,7 @@ async function listAuditLog(opts) {
     }
     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');
+        await mapDbHttpError(err, url, 'Failed to list audit log', { env: opts.dbBranch });
         throw err; // 不可达
     }
     const body = (await response.json());
@@ -518,7 +530,7 @@ async function getMigrationStatus(opts) {
     }
     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 migration status');
+        await mapDbHttpError(err, url, 'Failed to get migration status', { env: opts.dbBranch });
         throw err; // 不可达
     }
     const body = (await response.json());
@@ -567,7 +579,7 @@ async function getRecoveryPreview(opts) {
     }
     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 preview');
+        await mapDbHttpError(err, url, 'Failed to get recovery preview', { env: opts.dbBranch });
         throw err; // 不可达
     }
     const body = (await response.json());
@@ -590,7 +602,7 @@ async function getRecoveryStatus(opts) {
     }
     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');
+        await mapDbHttpError(err, url, 'Failed to get recovery status', { env: opts.dbBranch });
         throw err; // 不可达
     }
     const body = (await response.json());
@@ -611,7 +623,7 @@ async function getDbQuota(opts) {
     }
     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 db quota');
+        await mapDbHttpError(err, url, 'Failed to get db quota', { env: opts.dbBranch });
         throw err; // 不可达
     }
     const respBody = (await response.json());

package/dist/api/db/client.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SQLSTATE_MAP = void 0;
+exports.SQLSTATE_MAP = exports.ENV_CTX_TYPO = void 0;
 exports.traceHttp = traceHttp;
 exports.ensureInnerSuccess = ensureInnerSuccess;
 exports.mapDataloomBizError = mapDataloomBizError;
+exports.buildUnknownEnvError = buildUnknownEnvError;
+exports.decorateEnvError = decorateEnvError;
 exports.extractData = extractData;
 exports.buildInnerUrl = buildInnerUrl;
 const error_1 = require("../../utils/error");
@@ -69,7 +71,8 @@ function ensureInnerSuccess(body) {
  *
  * 优先级：
  *   1. k_dl_1300002 + SQLSTATE 透传     → SQLSTATE_MAP
- *   2. k_dl_1600000 + "Invalid DB Branch" → MULTI_ENV_NOT_INITIALIZED
+ *   2. k_dl_1600000 + "Invalid DB Branch" → UNKNOWN_ENV_VALUE 占位（mapDbHttpError
+ *      会用用户实际 --env 值通过 decorateEnvError 重写）
  *   3. BIZ_ERR_MAP 命中 → 语义 code（可能带 hint）
  *   4. 兜底 DB_API_<code>
  *
@@ -84,7 +87,13 @@ function mapDataloomBizError(code, rawMessage) {
         }
     }
     if (code === 'k_dl_1600000' && message.startsWith('Invalid DB Branch')) {
-        return new error_1.AppError('MULTI_ENV_NOT_INITIALIZED', '--env is not available (multi-env not initialized)', { next_actions: ['Verify the --env value matches an existing dbBranch.'] });
+        // 这里没有 user-facing --env 值（client 层不知道 CLI 入参），先用 server 侧返回的
+        // 分支名占位；mapDbHttpError 在拿到 env 上下文后会通过 decorateEnvError 重写成
+        // 用户传入的实际值。dataloom 错误文案历史上同时存在英文冒号和中文冒号「：」格式，
+        // 这里两种都接。
+        const m = /Invalid DB Branch[:：\s]+([^\s]+)/i.exec(message);
+        const branch = m?.[1] ?? '<branch>';
+        return buildUnknownEnvError(branch);
     }
     const mapped = BIZ_ERR_MAP.get(code);
     if (mapped) {
@@ -94,6 +103,71 @@ function mapDataloomBizError(code, rawMessage) {
     }
     return new error_1.AppError(`DB_API_${code}`, message);
 }
+/**
+ * typo / CLI vocab violation 路径用：state 未知，列双 env 让用户在 dev/online 之间选，
+ * 不引导 init（init 不会创建 typo 出来的分支）。
+ */
+exports.ENV_CTX_TYPO = {
+    available: ['dev', 'online'],
+    suggestInit: false,
+};
+/**
+ * 统一构造"--env 值不可用"错误。两类入口共用：
+ *   - CLI vocab 校验（_env.ts validateEnv）：用户传 dev/main/online 以外值
+ *   - backend state 错（decorateEnvError）：vocab 合法但 db 实际状态对不上
+ *
+ * `available` 跟 `suggestInit` 由调用方按错误码归类传入；user-facing 不展示 `main`
+ * 内部别名，统一用 `online`。
+ */
+function buildUnknownEnvError(env, ctx = exports.ENV_CTX_TYPO) {
+    const hints = [
+        `--env must match an existing database branch. Available: ${ctx.available.join(', ')}.`,
+    ];
+    if (ctx.suggestInit) {
+        hints.push(`Run \`miaoda db migration init\` before using '${env}'.`);
+    }
+    return new error_1.AppError('UNKNOWN_ENV_VALUE', `Unknown --env value '${env}'`, {
+        next_actions: hints,
+    });
+}
+/**
+ * 把 backend env 相关错误统一重写成 UNKNOWN_ENV_VALUE 文案，按错误码做 state 推断：
+ *
+ *   - DB_API_k_dl_1300033（非专家应用）→ 单 env (online)，不建议 init
+ *   - DB_API_k_dl_1300039（专家未 init）→ 单 env (online)，建议 init
+ *   - DB_API_k_dl_000007 + "db branch not found"（pg connection 兜底）→ 单 env，建议 init
+ *   - UNKNOWN_ENV_VALUE（mapDataloomBizError 对 k_dl_1600000 的占位）→ typo path
+ *
+ * env 未传时不改写：避免把 backend 兜底文案（如 "Multi-env is not initialized"）
+ * 改成 `Unknown --env value ''` 这种空字符串错误。
+ */
+function decorateEnvError(err, env) {
+    if (env === undefined || env === '')
+        return err;
+    const ctx = classifyEnvError(err);
+    if (!ctx)
+        return err;
+    return buildUnknownEnvError(env, ctx);
+}
+function classifyEnvError(err) {
+    if (err.code === 'DB_API_k_dl_1300033') {
+        // 非专家应用：init 也会被同一 guard 拒掉，建议 init 是误导
+        return { available: ['online'], suggestInit: false };
+    }
+    if (err.code === 'DB_API_k_dl_1300039') {
+        // 专家未 init：init 会创建 dev 分支
+        return { available: ['online'], suggestInit: true };
+    }
+    if (err.code === 'DB_API_k_dl_000007' && /db branch not found/i.test(err.message)) {
+        // pg connection 层 ErrParamsInvalid：大概率 pre-init；建议 init（非专家会被 init 路径拦）
+        return { available: ['online'], suggestInit: true };
+    }
+    if (err.code === 'UNKNOWN_ENV_VALUE') {
+        // mapDataloomBizError 对 k_dl_1600000 的占位：typo path，state 未知，列双 env
+        return exports.ENV_CTX_TYPO;
+    }
+    return null;
+}
 /**
  * 剥掉 PG 透传错误的 "ERROR:" 前缀：CLI 输出本身就会前缀 "Error:"，
  * 不去掉就会变成 `Error: ERROR: relation ...` 双重前缀，PRD 不要这种冗余。
@@ -201,9 +275,26 @@ function buildInnerUrl(appId, path, query) {
     let url = `/v1/dataloom/app/${encodeURIComponent(appId)}${normalized}`;
     if (query) {
         const usp = new URLSearchParams();
-        for (const [k, v] of Object.entries(query)) {
-            if (v !== undefined && v !== '')
-                usp.append(k, v);
+        for (const [k, rawV] of Object.entries(query)) {
+            if (rawV === undefined)
+                continue;
+            // 数组值 → 重复 key 编码（?k=v1&k=v2）。IDL 里 list<string> 类型经
+            // Hertz/Kitex HTTP→Thrift 网关绑定 slice 字段需要重复 key；如果改成
+            // join(',') 单串，后端会拿到 ["v1,v2"] 单元素切片而非 ["v1","v2"]。
+            if (typeof rawV !== 'string') {
+                for (const item of rawV) {
+                    if (item === '')
+                        continue;
+                    usp.append(k, item);
+                }
+                continue;
+            }
+            if (rawV === '')
+                continue;
+            // dbBranch 兼容用户视角的 `online` 别名 → 后端实际 dbBranch 名为 `main`，
+            // 这里集中归一，避免每个 API 函数各自处理。其他值（dev / 自定义分支）原样透传。
+            const norm = k === 'dbBranch' && rawV === 'online' ? 'main' : rawV;
+            usp.append(k, norm);
         }
         const qs = usp.toString();
         if (qs)

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

@@ -4,6 +4,7 @@ exports.registerDbCommands = registerDbCommands;
 const error_1 = require("../../../utils/error");
 const index_1 = require("../../../cli/handlers/db/index");
 const shared_1 = require("../../../cli/commands/shared");
+const _env_1 = require("../../../cli/handlers/db/_env");
 function parsePositiveInt(raw) {
     const n = Number(raw);
     if (!Number.isInteger(n) || n < 1) {
@@ -19,6 +20,13 @@ function registerDbCommands(program) {
         // --env 注册在 db 父级，spec 把它列入 db --help 的 Global Flags；
         // leaf 命令仍各自接收 --env 值（commander 解析时父级 option 自动适用于子命令）
         .option('--env <name>', '指定目标环境（dev / online，仅专家模式应用支持）');
+    // 任意 leaf action 执行前先做 --env vocab 校验：用户拼错（'onlin'/'prod' 等）立即报
+    // UNKNOWN_ENV_VALUE 避免后端无意义被打到。preAction hook 拿父级 dbCmd 的 --env 值
+    // —— commander 把父级 option 自动 propagate 给子命令的 optsWithGlobals。
+    dbCmd.hook('preAction', () => {
+        const env = dbCmd.opts().env;
+        (0, _env_1.validateEnv)(typeof env === 'string' ? env : undefined);
+    });
     dbCmd.action(() => {
         dbCmd.outputHelp();
     });
@@ -224,6 +232,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/_destructive.js

@@ -0,0 +1,67 @@
+"use strict";
+// db 域内不可逆 / destructive 操作的统一确认门。
+//
+// 设计要点：
+//   1. --yes：放行（CI / 脚本显式确认场景）
+//   2. 非 TTY 且无 --yes：抛 DESTRUCTIVE_REQUIRES_CONFIRM，不要默认放行。
+//      非 TTY 通常是 CI / agent / 管道场景，无人能交互回答 y/N，必须靠 --yes 显式确认。
+//   3. TTY 且无 --yes：交互式 y/N（prompt 写 stderr，避免污染 --json 模式 stdout）
+//
+// 反例（已修复，见这次 commit）：把 !isJsonMode() 拿来做确认门 —— --json 只改输出
+// 格式，跟"用户已确认"不是同一语义。CI / agent 几乎总会带 --json 解析输出，等价于
+// 把不可逆操作的确认变成了空门，跟 file rm 的模型也不一致。
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.confirmDestructive = confirmDestructive;
+exports.assertDestructiveAllowedInTty = assertDestructiveAllowedInTty;
+exports.askYesNo = askYesNo;
+const node_readline_1 = __importDefault(require("node:readline"));
+const render_1 = require("../../../utils/render");
+const error_1 = require("../../../utils/error");
+const DESTRUCTIVE_REQUIRES_CONFIRM_MSG = 'This operation is destructive. Rerun with --yes to confirm.';
+/**
+ * 完整的"yes/tty/交互"决策门。直接用于无需 fetch 预览的简单确认场景（如 migration init）。
+ *
+ * 返回值：
+ *   - true  → 已确认，可执行
+ *   - false → TTY 下用户输了 n，调用方应渲染 Aborted 并退出
+ *
+ * 异常：
+ *   - DESTRUCTIVE_REQUIRES_CONFIRM：非 TTY 且无 --yes
+ */
+async function confirmDestructive(prompt, yes) {
+    if (yes === true)
+        return true;
+    if (!(0, render_1.isStdoutTty)()) {
+        throw new error_1.AppError('DESTRUCTIVE_REQUIRES_CONFIRM', DESTRUCTIVE_REQUIRES_CONFIRM_MSG);
+    }
+    return askYesNo(prompt);
+}
+/**
+ * 给"需要在 confirm 之前先 fetch 预览"的场景（migration apply / recovery apply 可选优化）用：
+ * 在非 TTY 无 --yes 时提前抛错，避免无意义触发后端 dry-run RPC。
+ *
+ * 调用后 TTY 路径仍需自行调 askYesNo / confirmDestructive 完成交互。
+ */
+function assertDestructiveAllowedInTty(yes) {
+    if (yes === true)
+        return;
+    if (!(0, render_1.isStdoutTty)()) {
+        throw new error_1.AppError('DESTRUCTIVE_REQUIRES_CONFIRM', DESTRUCTIVE_REQUIRES_CONFIRM_MSG);
+    }
+}
+/**
+ * 交互式 y/N。输入读 stdin，prompt 写 stderr —— stderr 避免污染 --json 模式 stdout 的 envelope。
+ * 仅 'y'（忽略大小写）算确认；其余一律视为否决。
+ */
+async function askYesNo(prompt) {
+    const rl = node_readline_1.default.createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        rl.question(prompt, (answer) => {
+            rl.close();
+            resolve(answer.trim().toLowerCase() === 'y');
+        });
+    });
+}

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

@@ -0,0 +1,26 @@
+"use strict";
+// db 域内 --env 参数的 CLI vocab 校验。
+//
+// 用户视角的 vocab：
+//   - dev    → 多环境沙箱分支
+//   - online → 生产分支（向后端发请求时映射成 main，client.ts/api.ts 已处理）
+//   - main   → online 的别名，兼容历史脚本
+//
+// 配合 client.ts::buildUnknownEnvError，把 vocab 错（这里）跟 backend state 错
+// （client.ts 处理）统一成同一类 UNKNOWN_ENV_VALUE，避免用户在两种失败之间困惑。
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateEnv = validateEnv;
+const client_1 = require("../../../api/db/client");
+const VOCAB = ['dev', 'main', 'online'];
+const VOCAB_SET = new Set(VOCAB);
+/**
+ * CLI vocab 校验。空值（未传 --env）放行，由后端按 workspace 默认 branch 处理。
+ * 不在 vocab 内 → 抛 UNKNOWN_ENV_VALUE，preAction hook 兜底，避免无意义触发 RPC。
+ */
+function validateEnv(env) {
+    if (env === undefined || env === '')
+        return;
+    if (VOCAB_SET.has(env))
+        return;
+    throw (0, client_1.buildUnknownEnvError)(env);
+}

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

@@ -45,6 +45,7 @@ const output_1 = require("../../../utils/output");
 const render_1 = require("../../../utils/render");
 const time_1 = require("../../../utils/time");
 const _operator_1 = require("../../../cli/handlers/db/_operator");
+const index_1 = require("../../../api/db/index");
 const VALID_RETENTION = new Set(['7d', '30d', '180d', '360d', 'forever']);
 async function handleDbAuditStatus(table, opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
@@ -199,11 +200,34 @@ async function handleDbAuditList(tables, opts) {
     // 后端管理（本质也是 ISO 时间），CLI 不再混用 cursor/since。
     const since = normalizeTime(opts.since, '--since');
     const until = normalizeTime(opts.until, '--until');
+    // 多表场景：dataloom 对"任一表不存在"是 fail-fast（typo 应立即可见，符合 PRD 单表语义），
+    // 但 PRD 多表语义是"其他表继续返回，底部汇总跳过情况"。CLI 在这里前置校验：用 getSchema
+    // 的 tableNames 过滤模式（dataloom 端内存过滤，不存在的表静默忽略，不报错）拿到存在的
+    // 表集合，本地 diff 出缺失表，再用过滤后的表去查 listAuditLog。单表场景跳过预校验。
+    const isMulti = tables.length > 1;
+    let queryTables = tables;
+    const localMissing = [];
+    if (isMulti) {
+        const schemaResp = await api.db.getSchema({
+            appId,
+            tableNames: tables.join(','),
+            dbBranch: opts.env,
+        });
+        const existing = new Set((0, index_1.flattenSchemaList)(schemaResp.schema).map((t) => t.name));
+        for (const t of tables) {
+            if (!existing.has(t))
+                localMissing.push(t);
+        }
+        queryTables = tables.filter((t) => existing.has(t));
+        if (queryTables.length === 0) {
+            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.'] });
+        }
+    }
     let result;
     try {
         result = await api.db.listAuditLog({
             appId,
-            tables,
+            tables: queryTables,
             since,
             until,
             limit,
@@ -215,7 +239,9 @@ async function handleDbAuditList(tables, opts) {
         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)()) {
@@ -239,7 +265,7 @@ async function handleDbAuditList(tables, opts) {
         return;
     }
     if (visible.length === 0) {
-        (0, output_1.emit)('No audit log entries found.');
+        (0, output_1.emit)('No audit events found.');
         if (skipped.length > 0) {
             process.stderr.write(formatSkippedHint(skipped, tables.length) + '\n');
         }
@@ -294,10 +320,11 @@ function normalizeTime(input, flagName) {
     }
 }
 // PRD 41-48 行格式：`— Skipped 1 of 3 tables: orders (audit not enabled)`
-// 服务端约定 skipped 列表 = audit 未启用的表（表不存在直接 raise k_dl_000005），
-// 所以原因固定为 "audit not enabled"，无需带每项 reason。
+// 服务端 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} (audit not enabled)`).join(', ');
+    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：

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

@@ -32,14 +32,10 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleDbMigrationInit = handleDbMigrationInit;
 exports.handleDbMigrationDiff = handleDbMigrationDiff;
 exports.handleDbMigrationApply = handleDbMigrationApply;
-const node_readline_1 = __importDefault(require("node:readline"));
 const api = __importStar(require("../../../api/index"));
 const shared_1 = require("../../../cli/commands/shared");
 const colors_1 = require("../../../utils/colors");
@@ -47,17 +43,17 @@ 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");
+const _destructive_1 = require("../../../cli/handlers/db/_destructive");
 async function handleDbMigrationInit(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
-    // 不可逆操作，TTY 默认要求 y/N；--yes 跳过
-    if (!opts.yes && !(0, output_1.isJsonMode)()) {
-        // 文案对齐 PRD：先讲不可逆，再问是否初始化；syncData 时追加一句而不是塞进同一句话
-        const suffix = opts.syncData ? ' (existing data will be copied to dev)' : '';
-        const ok = await confirm(`? This action is irreversible. Initialize multi-env (dev / online)${suffix}? (y/N) `);
-        if (!ok) {
-            (0, output_1.emit)('Aborted.');
-            return;
-        }
+    // 不可逆操作：--yes 直接放行；非 TTY 抛 DESTRUCTIVE_REQUIRES_CONFIRM；TTY 交互确认。
+    // 不再用 isJsonMode() 做门 —— 见 _destructive.ts 注释。
+    const suffix = opts.syncData ? ' (existing data will be copied to dev)' : '';
+    const ok = await (0, _destructive_1.confirmDestructive)(`? This action is irreversible. Initialize multi-env (dev / online)${suffix}? (y/N) `, opts.yes);
+    if (!ok) {
+        (0, output_1.emit)('Aborted.');
+        return;
     }
     let result;
     try {
@@ -88,12 +84,16 @@ async function handleDbMigrationInit(opts) {
 async function handleDbMigrationDiff(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     let result;
+    const stopSpinner = (0, spinner_1.startSpinner)('Previewing migration diff (dev → online)');
     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}`, {
@@ -106,15 +106,20 @@ async function handleDbMigrationDiff(opts) {
 }
 async function handleDbMigrationApply(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
-    // TTY 下先 diff 给用户审；--yes 直接打到 online
-    if (!opts.yes && !(0, output_1.isJsonMode)()) {
+    // --yes 跳过预览 + 确认；否则 TTY 拉 diff 给用户审，非 TTY 直接拒（避免无意义 dry-run RPC）
+    if (opts.yes !== true) {
+        (0, _destructive_1.assertDestructiveAllowedInTty)(opts.yes);
         let preview;
+        const stopSpinner = (0, spinner_1.startSpinner)('Previewing migration diff (dev → online)');
         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}`, {
@@ -123,8 +128,10 @@ async function handleDbMigrationApply(opts) {
                 ],
             });
         }
-        renderDiff(preview);
-        const ok = await confirm(`? Apply ${String(preview.changes.length)} change(s) to ${preview.to}? (y/N) `);
+        // --json 模式跳过 pretty diff 渲染（污染 stdout envelope），但仍要求 confirm
+        if (!(0, output_1.isJsonMode)())
+            renderDiff(preview);
+        const ok = await (0, _destructive_1.askYesNo)(`? Apply ${String(preview.changes.length)} change(s) to ${preview.to}? (y/N) `);
         if (!ok) {
             (0, output_1.emit)('Aborted.');
             return;
@@ -145,6 +152,7 @@ async function handleDbMigrationApply(opts) {
     const taskId = result.taskId;
     const final = await (0, poll_1.pollUntilDone)({
         label: 'migration apply',
+        spinnerLabel: 'Applying migration (dev → online)',
         intervalMs: 1000,
         fetch: () => api.db.getMigrationStatus({ appId, taskId }),
         isDone: (cur) => {
@@ -224,12 +232,3 @@ function decorateMigrationError(err) {
             return err;
     }
 }
-async function confirm(prompt) {
-    const rl = node_readline_1.default.createInterface({ input: process.stdin, output: process.stderr });
-    return new Promise((resolve) => {
-        rl.question(prompt, (answer) => {
-            rl.close();
-            resolve(answer.trim().toLowerCase() === 'y');
-        });
-    });
-}

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

@@ -32,13 +32,10 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleDbRecoveryDiff = handleDbRecoveryDiff;
 exports.handleDbRecoveryApply = handleDbRecoveryApply;
-const node_readline_1 = __importDefault(require("node:readline"));
+exports.formatRecoveryTargetForDisplay = formatRecoveryTargetForDisplay;
 const api = __importStar(require("../../../api/index"));
 const shared_1 = require("../../../cli/commands/shared");
 const colors_1 = require("../../../utils/colors");
@@ -47,6 +44,7 @@ const output_1 = require("../../../utils/output");
 const poll_1 = require("../../../utils/poll");
 const render_1 = require("../../../utils/render");
 const time_1 = require("../../../utils/time");
+const _destructive_1 = require("../../../cli/handlers/db/_destructive");
 // ── recovery diff ──
 //
 // PITR preview 是异步任务：dataloom 立即返 previewRequestId，CLI 自己 poll 直到 success/failed。
@@ -55,7 +53,7 @@ const time_1 = require("../../../utils/time");
 async function handleDbRecoveryDiff(target, opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     const ts = normalizeTimestamp(target);
-    const preview = await runRecoveryPreview(appId, ts);
+    const preview = await runRecoveryPreview(appId, ts, target);
     renderDiff(ts, preview);
 }
 async function handleDbRecoveryApply(target, opts) {
@@ -64,11 +62,33 @@ async function handleDbRecoveryApply(target, opts) {
     // 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 preview = await runRecoveryPreview(appId, ts, target);
     const tablesAffected = preview.tablesAffected ?? preview.changes?.length ?? 0;
-    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) `);
+    // 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;
+    }
+    // --yes 跳过；非 TTY 抛 DESTRUCTIVE_REQUIRES_CONFIRM；TTY 渲染 diff（pretty）+ 交互确认。
+    // 不再用 isJsonMode() 做门 —— 见 _destructive.ts 注释。
+    if (opts.yes !== true) {
+        (0, _destructive_1.assertDestructiveAllowedInTty)(opts.yes);
+        // --json 模式跳过 pretty diff 渲染避免污染 stdout envelope；TTY pretty 模式渲染
+        if (!(0, output_1.isJsonMode)())
+            renderDiff(ts, preview);
+        const ok = await (0, _destructive_1.askYesNo)(`? Restore database to ${ts}? This will overwrite current data. (y/N) `);
         if (!ok) {
             (0, output_1.emit)('Aborted.');
             return;
@@ -85,7 +105,7 @@ async function handleDbRecoveryApply(target, opts) {
     // 立即返 status="restore_triggered"，CLI 必须 poll GET /db/recovery/status 拿
     // Redis 缓存的 Resetting/Ready/Failed，否则用户会被误导以为已恢复完。
     const startedAt = Date.now();
-    await waitRecoveryDone(appId, ts);
+    await waitRecoveryDone(appId, ts, target);
     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}
@@ -112,10 +132,11 @@ async function handleDbRecoveryApply(target, opts) {
  * 不设固定超时：BranchRestore 实际时长依库大小变化（前端文案示例 1 分钟，大库可能
  * 几分钟），由 pollUntilDone 内置 60 分钟上限兜底，远超正常场景。
  */
-async function waitRecoveryDone(appId, target) {
+async function waitRecoveryDone(appId, target, rawTarget) {
     try {
         return await (0, poll_1.pollUntilDone)({
             label: 'recovery apply',
+            spinnerLabel: `Restoring database (target: ${formatRecoveryTargetForDisplay(rawTarget)})`,
             intervalMs: 2000,
             fetch: () => api.db.getRecoveryStatus({ appId }),
             isDone: (cur) => {
@@ -142,7 +163,7 @@ async function waitRecoveryDone(appId, target) {
  * 补 hint。failed 状态下 dataloom 已把 errorMessage 翻好，CLI 包成 k_dl_1300036
  * 让 decorateRecoveryError 命中窗口超限 hint。
  */
-async function runRecoveryPreview(appId, ts) {
+async function runRecoveryPreview(appId, ts, rawTarget) {
     let triggered;
     try {
         triggered = await api.db.recover({ appId, target: ts, dryRun: true });
@@ -157,6 +178,7 @@ async function runRecoveryPreview(appId, ts) {
     try {
         return await (0, poll_1.pollUntilDone)({
             label: 'recovery preview',
+            spinnerLabel: `Previewing recovery impact (target: ${formatRecoveryTargetForDisplay(rawTarget)})`,
             intervalMs: 1000,
             fetch: () => api.db.getRecoveryPreview({ appId, previewRequestId }),
             isDone: (cur) => {
@@ -180,6 +202,38 @@ async function runRecoveryPreview(appId, ts) {
     }
 }
 // ── helpers ──
+/**
+ * 把用户传入的 recovery target 解析成本地时区的 ISO 8601 字符串，
+ * 如 "2026-05-20T22:32:00+08:00"。无论用户传相对值（30m / 2h / 3d）还是绝对值，
+ * 都统一展示成"具体几点"，让用户一眼看清楚"目标恢复点是我本地几点"——
+ * "30m ago"这种相对描述虽然原样直观，但跟 backend dataloom 收到的实际时间点没有
+ * 显式对照，遇到长 poll 时间过去后会让人怀疑"算的到底是哪个点"。
+ *
+ * 不用 UTC 'Z' 后缀：用户读时间不直观；带 +/-HH:MM offset 一眼即懂时差。
+ * 解析失败 → 原样返回兜底，避免 spinner 渲染崩。
+ */
+function formatRecoveryTargetForDisplay(rawInput) {
+    const trimmed = rawInput.trim();
+    let ms;
+    try {
+        ms = (0, time_1.parseTimeToMs)(trimmed);
+    }
+    catch {
+        return trimmed;
+    }
+    return formatIsoWithLocalOffset(ms);
+}
+function formatIsoWithLocalOffset(ms) {
+    const d = new Date(ms);
+    const pad = (n) => String(n).padStart(2, '0');
+    // getTimezoneOffset 返回本地相对 UTC 的差值（分钟）— UTC 在东八区是 -480
+    const offsetMinutes = -d.getTimezoneOffset();
+    const sign = offsetMinutes >= 0 ? '+' : '-';
+    const absOffset = Math.abs(offsetMinutes);
+    const tz = `${sign}${pad(Math.floor(absOffset / 60))}:${pad(absOffset % 60)}`;
+    return (`${String(d.getFullYear())}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}` +
+        `T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}${tz}`);
+}
 /**
  * 把用户传入的时间统一成 ISO 8601 UTC 字符串发给 dataloom。
  *
@@ -357,12 +411,3 @@ function decorateRecoveryError(err) {
             return err;
     }
 }
-async function confirm(prompt) {
-    const rl = node_readline_1.default.createInterface({ input: process.stdin, output: process.stderr });
-    return new Promise((resolve) => {
-        rl.question(prompt, (answer) => {
-            rl.close();
-            resolve(answer.trim().toLowerCase() === 'y');
-        });
-    });
-}

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.fc1e1a9",
+  "version": "0.1.3-beta.33b7ba5",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {