@lark-apaas/miaoda-cli 0.1.1-alpha.d20f110 → 0.1.1-alpha.e70b415

package/dist/api/db/api.js

@@ -16,7 +16,13 @@ const client_1 = require("./client");
  * 配合调用点的 try/catch + traceHttp，让 --verbose 在错误路径上也能拿到
  * x-tt-logid 与 status，方便定位线上问题。
  */
-async function mapDbHttpError(err, url, ctx) {
+async function mapDbHttpError(err, url, ctx, 
+/**
+ * 可选 hook：解析到响应 body 后，如果 envelope 命中业务错误并抛出 AppError，
+ * 调用方可以借此把 body 里的额外字段（如 multi-statement 的 partial results）
+ * 挂到 AppError 上。
+ */
+onErrorBody) {
     if (err instanceof error_1.AppError)
         throw err;
     if (err instanceof http_client_1.HttpError) {
@@ -24,8 +30,17 @@ async function mapDbHttpError(err, url, ctx) {
         const statusText = err.response?.statusText ?? "";
         try {
             const body = (await err.response?.json());
-            if (body)
-                (0, client_1.extractData)(body); // 业务 code 命中 → 抛 AppError；不命中走兜底
+            if (body) {
+                try {
+                    (0, client_1.extractData)(body); // 业务 code 命中 → 抛 AppError；不命中走兜底
+                }
+                catch (appErr) {
+                    if (appErr instanceof error_1.AppError && onErrorBody) {
+                        onErrorBody(body, appErr);
+                    }
+                    throw appErr;
+                }
+            }
         }
         catch (innerErr) {
             if (innerErr instanceof error_1.AppError)
@@ -36,6 +51,20 @@ async function mapDbHttpError(err, url, ctx) {
     }
     throw err;
 }
+/**
+ * 多语句 SQL 失败时把已成功 statement 的 results 挂到 AppError.partial_results 上，
+ * 供上层 handler 构造 PRD 要求的 `completed` 数组。
+ *
+ * 注意参数顺序：(body, appErr) — 与 mapDbHttpError 的 onErrorBody hook 签名对齐。
+ */
+function attachSqlPartialResults(body, appErr) {
+    const data = body.data;
+    if (!data)
+        return;
+    if (!Array.isArray(data.results) || data.results.length === 0)
+        return;
+    appErr.partial_results = data.results;
+}
 // CLI 不再为 dbBranch 设默认值：
 // 用户没传 --env 就完全不携带 dbBranch query 参数，由后端 admin-inner 中间件
 // 按 workspace 多环境状态决定（多环境 → dev / 单环境 → main）。
@@ -61,12 +90,20 @@ 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");
+        await mapDbHttpError(err, url, "Failed to execute SQL", attachSqlPartialResults);
         throw err; // 不可达
     }
     const body = (await response.json());
-    const data = (0, client_1.extractData)(body);
-    return data.results ?? [];
+    try {
+        const data = (0, client_1.extractData)(body);
+        return data.results ?? [];
+    }
+    catch (appErr) {
+        // HTTP 2xx 但 envelope status_code != 0 的多语句失败路径：同样挂 partial_results
+        if (appErr instanceof error_1.AppError)
+            attachSqlPartialResults(body, appErr);
+        throw appErr;
+    }
 }
 // ── db schema → InnerGetSchema ──
 /**

package/dist/api/db/client.js

@@ -118,6 +118,9 @@ const BIZ_ERR_MAP = new Map(Object.entries({
     "k_dl_000003": { code: "SQL_OPERATION_FORBIDDEN" },
     // k_dl_1300002：PG 执行错误；实际 SQLSTATE 由 extractSqlstate 单独映射
     // 未匹配到 SQLSTATE 时走下面兜底 DB_API_<code>
+    // k_dl_1300015：SELECT 结果超过 1000 行硬拦；多行 hint 由 output.ts 的
+    // SERVER_ERROR_HINTS 按语义 code 兜底，这里只做 code 改名
+    "k_dl_1300015": { code: "RESULT_SET_TOO_LARGE" },
 }));
 /** PG SQLSTATE → CLI code（当前 dataloom 不一定透传，预留未来使用） */
 exports.SQLSTATE_MAP = {

package/dist/api/db/parsers.js

@@ -117,11 +117,35 @@ function toDetail(t, stats) {
     // 优先用 tableStats.indexes（PRIMARY + UNIQUE + INDEX 统一视图）；
     // 回退到 TableVO.indexes（仅二级索引，老后端没返回 tableStats 时使用）
     const rawIndexes = stats?.indexes ?? t.indexes ?? [];
+    const constraints = [];
+    const indexes = [];
+    for (const i of rawIndexes) {
+        const cols = i.indexColumns ?? [];
+        // 过滤掉空列条目（后端偶发返 indexColumns=[] 的占位项），渲染成 "UNIQUE ()" 看起来像 bug
+        if (cols.length === 0)
+            continue;
+        const kind = i.indexType.toLowerCase();
+        if (kind === "primary") {
+            constraints.push({ type: "PRIMARY KEY", columns: cols });
+        }
+        else if (kind === "unique") {
+            constraints.push({ type: "UNIQUE", columns: cols });
+        }
+        else {
+            // foreign / normal / 其它统一进 indexes 段；method 从 indexDef 的 USING 段解析
+            indexes.push({
+                name: i.indexName,
+                columns: cols,
+                method: parseIndexMethod(i.indexDef) ?? "btree",
+            });
+        }
+    }
     return {
         name: t.tableName,
         description: t.comment && t.comment.length > 0 ? t.comment : null,
         columns: (t.fields ?? []).map(toColumn),
-        indexes: rawIndexes.map(toIndex),
+        constraints,
+        indexes,
         estimated_row_count: typeof stats?.estimatedRowCount === "number" ? stats.estimatedRowCount : null,
         size_bytes: typeof stats?.sizeBytes === "number" ? stats.sizeBytes : null,
     };
@@ -137,25 +161,14 @@ function toColumn(f) {
         comment: f.comment && f.comment.length > 0 ? f.comment : null,
     };
 }
-function toIndex(i) {
-    return {
-        name: i.indexName,
-        type: translateIndexType(i.indexType),
-        columns: i.indexColumns ?? [],
-    };
-}
 /**
- * 把后端原始 IndexType（小写：primary / unique / normal / foreign）翻译为 PRD 约定的展示值。
- * 规则：
- *   primary  → "PRIMARY KEY"
- *   unique   → "UNIQUE"
- *   其它    → "INDEX"（foreign 外键通过 relationships 表达，不进 indexes；真的遇到也归 INDEX）
+ * 从 PG 的 CREATE INDEX 语句里提取访问方法（btree / gin / gist / hash 等）。
+ * indexDef 示例: "CREATE INDEX idx_users_name ON public.users USING btree (name)"
+ * 解析失败返 null，由调用方兜底成 PG 默认的 "btree"。
  */
-function translateIndexType(raw) {
-    const s = raw.toLowerCase();
-    if (s === "primary")
-        return "PRIMARY KEY";
-    if (s === "unique")
-        return "UNIQUE";
-    return "INDEX";
+function parseIndexMethod(indexDef) {
+    if (!indexDef)
+        return null;
+    const m = /USING\s+(\w+)/i.exec(indexDef);
+    return m ? m[1].toLowerCase() : null;
 }

package/dist/api/db/sql-keywords.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SQL_KEYWORDS = void 0;
+/**
+ * 常见 PG SQL 关键字白名单，用于 db sql 拼写错误的 did-you-mean 提示。
+ *
+ * # 选词原则
+ *
+ * PG 的关键字总数 700+（见 [pg_keyword 系统视图]），但 CLI 用户实际打错的几乎
+ * 都集中在核心动词 / 子句 / 类型 / 事务关键字。这里**少而精**，约 70 个：
+ *
+ *   - DML 动词：SELECT / INSERT / UPDATE / DELETE / MERGE
+ *   - 子句：FROM / WHERE / JOIN / GROUP / ORDER / HAVING / LIMIT / ...
+ *   - 操作符词：AND / OR / NOT / IN / IS / NULL / LIKE / ...
+ *   - DDL：CREATE / ALTER / DROP / TABLE / INDEX / VIEW / ...
+ *   - 约束：PRIMARY / UNIQUE / FOREIGN / REFERENCES / CHECK / DEFAULT / ...
+ *   - 事务：BEGIN / COMMIT / ROLLBACK / SAVEPOINT / TRANSACTION
+ *   - 控制：IF / EXISTS / CASE / WHEN / THEN / ELSE / END / WITH / ...
+ *
+ * **不要往里加冷僻关键字**——候选集越大，短词越容易 false-positive 错配。
+ */
+exports.SQL_KEYWORDS = [
+    // DML 动词
+    "SELECT", "INSERT", "UPDATE", "DELETE", "MERGE",
+    // FROM / JOIN 系列
+    "FROM", "WHERE", "JOIN", "LEFT", "RIGHT", "INNER", "OUTER", "FULL", "CROSS", "USING",
+    // 聚合 / 排序 / 分页
+    "GROUP", "ORDER", "BY", "HAVING", "LIMIT", "OFFSET", "FETCH",
+    // 集合操作
+    "UNION", "INTERSECT", "EXCEPT", "DISTINCT", "ALL",
+    // 别名 / 关联
+    "AS", "ON",
+    // 操作符词
+    "AND", "OR", "NOT", "IN", "IS", "NULL", "TRUE", "FALSE",
+    "BETWEEN", "LIKE", "ILIKE", "SIMILAR",
+    // DDL
+    "CREATE", "ALTER", "DROP", "TRUNCATE", "RENAME",
+    "TABLE", "INDEX", "VIEW", "DATABASE", "SCHEMA", "COLUMN", "CONSTRAINT", "SEQUENCE",
+    // 约束
+    "PRIMARY", "KEY", "FOREIGN", "REFERENCES", "UNIQUE", "CHECK", "DEFAULT",
+    // 写入
+    "VALUES", "SET", "RETURNING", "INTO",
+    // 事务
+    "BEGIN", "COMMIT", "ROLLBACK", "SAVEPOINT", "TRANSACTION",
+    // 控制流 / CTE
+    "IF", "EXISTS", "REPLACE", "WITH", "RECURSIVE",
+    "CASE", "WHEN", "THEN", "ELSE", "END",
+    // 类型转换 / 时间提取
+    "CAST", "EXTRACT",
+    // 排序方向
+    "ASC", "DESC", "NULLS", "FIRST", "LAST",
+];

package/dist/api/file/api.js

@@ -299,18 +299,28 @@ async function preUpload(appId, req) {
 }
 /**
  * 调用 upload callback 拿到对象元数据。
- * 后端把对象 VO 序列化成 JSON 字符串放在 data.metadata 字段里，这里解析出实际
- * filePath / file_name / download_url 给 uploadFile 调用方使用，避免 CLI 自己拼路径。
+ *
+ * 网关 IDL 在 metadata 字段加了 api.response.converter = "decode"，正常路径下
+ * HTTP 响应里的 metadata 已经被网关从字符串解码成对象；这里两种形态都兼容：
+ *   - object → 直接当 CallbackObjectVO 用（网关解码场景）
+ *   - string → JSON.parse 出来用（后端原始形态 / 网关行为变化兜底）
+ *
+ * 解析失败 / metadata 缺失时返回空对象，由 uploadFile 用本地兜底字段填充。
  */
 async function uploadCallback(appId, req) {
     const url = `/v1/storage/app/${encodeURIComponent(appId)}/object/callback`;
     const body = await (0, client_1.doPost)(url, req, { errorContext: "upload callback" });
     const data = extractEnvelope(body);
-    if (!data.metadata) {
+    const metadata = data.metadata;
+    if (!metadata) {
         return {};
     }
+    if (typeof metadata === "object") {
+        return metadata;
+    }
+    // string 形态兜底
     try {
-        return JSON.parse(data.metadata);
+        return JSON.parse(metadata);
     }
     catch (err) {
         (0, logger_1.debug)(`upload callback metadata json parse failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -341,11 +351,15 @@ async function uploadFile(opts) {
         // 这里复制到独立 ArrayBuffer 以满足 lib.dom.d.ts 的 BodyInit 约束
         const ab = body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength);
         const uploadStart = Date.now();
+        // Content-Disposition 用 attachment + filename 编码原始文件名。TOS 会把这个
+        // header 作为对象 metadata 存住，服务端 callback 阶段 HeadObject 读回并解析
+        // filename 写入 DB。我们要不传 header，服务端走兜底会把 storage key 当文件名。
         const res = await fetch(pre.uploadURL, {
             method: "PUT",
             headers: {
                 "Content-Type": opts.contentType,
                 "Content-Length": String(opts.fileSize),
+                "Content-Disposition": `attachment; filename="${sanitizeFileName(opts.fileName)}"`,
             },
             body: ab,
         });
@@ -378,6 +392,8 @@ async function uploadFile(opts) {
         ? (metadata.filePath.startsWith("/") ? metadata.filePath : "/" + metadata.filePath)
         : (opts.remotePath ?? "/" + opts.fileName);
     const result = {
+        // 优先取服务端 ObjectVO.name（来自 PUT 时带的 Content-Disposition），
+        // 与后续 file ls / file stat 返回的展示名保持一致；缺失时降级用本地 fileName。
         file_name: metadata.name ?? opts.fileName,
         path,
         size: metadata.metadata?.contentLength ?? opts.fileSize,
@@ -388,6 +404,17 @@ async function uploadFile(opts) {
     }
     return result;
 }
+/**
+ * 把文件名清理成可安全放进 Content-Disposition `filename="..."` 的形态。
+ * 与 fullstack-plugin 的 sanitizeFileName 行为一致：
+ *   1. 去掉对 TOS / 文件系统不友好的字符 [: " \ / * ? < > | , ;]
+ *   2. encodeURIComponent 把非 ASCII（中文等）做百分号编码，保证 header 合法
+ *   3. 处理后为空时退回 "download_file" 兜底
+ */
+function sanitizeFileName(fileName) {
+    const illegalChars = /[:"\\/*?<>|,;]/g;
+    return encodeURIComponent(fileName.replace(illegalChars, "")) || "download_file";
+}
 // ── 预签下载 URL ──
 /**
  * 获取预签下载 URL。

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

@@ -40,6 +40,7 @@ const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 const render_1 = require("../../../utils/render");
 const shared_1 = require("../../../cli/commands/shared");
+const colors_1 = require("../../../utils/colors");
 const index_1 = require("../../../api/db/index");
 // ── schema list ──
 async function handleDbSchemaList(opts) {
@@ -127,7 +128,8 @@ function renderDetail(d, tty) {
     // 构造的伪时间戳（baseTime=2020-01-01 + OID 秒偏移），仅保排序意义、绝对值
     // 误导性强，先去掉。后续如果接 ddl_change_log 取真实时间再加回。
     const header = [
-        ["Name", d.name],
+        // 表名做 cyan 强调（spec：spec 里的"命令名/表名"类强调值都走 highlight）
+        ["Name", tty ? colors_1.c.highlight(d.name) : d.name],
         ["Description", d.description ?? "—"],
         [
             "Columns",
@@ -150,12 +152,21 @@ function renderDetail(d, tty) {
     parts.push((0, render_1.renderKeyValue)(header, tty));
     parts.push("");
     parts.push(tty ? (0, render_1.renderAlignedTable)(colHeaders, colRows) : (0, render_1.renderTsv)(colHeaders, colRows));
+    // Constraints 段（PRIMARY KEY / UNIQUE）：表级约束独立成段，与普通索引分离展示
+    if (d.constraints.length > 0) {
+        parts.push("");
+        parts.push(tty ? "  Constraints:" : "Constraints:");
+        for (const c of d.constraints) {
+            const line = `${c.type} (${c.columns.join(", ")})`;
+            parts.push(tty ? `    ${line}` : line);
+        }
+    }
+    // Indexes 段：普通索引，格式 "<name> ON <col1, col2> USING <method>"
     if (d.indexes.length > 0) {
         parts.push("");
         parts.push(tty ? "  Indexes:" : "Indexes:");
-        // PRD 格式: "TYPE (col1, col2)"，不展示索引名
         for (const idx of d.indexes) {
-            const line = `${idx.type} (${idx.columns.join(", ")})`;
+            const line = `${idx.name} ON ${idx.columns.join(", ")} USING ${idx.method}`;
             parts.push(tty ? `    ${line}` : line);
         }
     }

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

@@ -44,7 +44,10 @@ const config_1 = require("../../../utils/config");
 const logger_1 = require("../../../utils/logger");
 const shared_1 = require("../../../cli/commands/shared");
 const render_1 = require("../../../utils/render");
+const colors_1 = require("../../../utils/colors");
+const fuzzy_match_1 = require("../../../utils/fuzzy-match");
 const index_1 = require("../../../api/db/index");
+const sql_keywords_1 = require("../../../api/db/sql-keywords");
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
@@ -64,7 +67,20 @@ async function handleDbSql(query, opts) {
     if (!sql.trim()) {
         throw new error_1.AppError("ARGS_INVALID", "Empty SQL (no inline query and stdin is empty)");
     }
-    const results = await api.db.execSql({ appId, sql, dbBranch: opts.env });
+    let results;
+    try {
+        results = await api.db.execSql({ appId, sql, dbBranch: opts.env });
+    }
+    catch (err) {
+        // 错误抛出前富化 next_actions：识别"语法错误"/"表不存在"/"列不存在"
+        // 三类常见 PG 错误，做 fuzzy match 给 did-you-mean 提示。
+        // 富化失败任何环节都静默吞掉，不破坏原始错误信息。
+        await enrichSqlError(err, { appId, env: opts.env, sql });
+        // PRD 多语句失败：把服务端给的 partial_results 转成 `completed`，推断 `rolled_back`，
+        // 并把 pretty 模式的 `Statement N: ✓ ... / Statement K: ✗ ...` 立即打到 stderr。
+        enrichMultiStatementError(err, sql);
+        throw err;
+    }
     if (results.length === 0) {
         // 后端未返回任何结果，通常不会发生
         if ((0, output_1.isJsonMode)()) {
@@ -225,19 +241,19 @@ function renderSingle(raw) {
             return;
         }
         const cols = collectColumns(parsed.rows);
-        const rows = parsed.rows.map((r) => cols.map((c) => formatCell(r[c], tty)));
+        const rows = parsed.rows.map((r) => cols.map((col) => formatCell(r[col], tty)));
         (0, output_1.emit)(tty ? (0, render_1.renderAlignedTable)(cols, rows) : (0, render_1.renderTsv)(cols, rows));
         return;
     }
     if (parsed.kind === "dml") {
         const verb = dmlVerb(parsed.sqlType);
         (0, output_1.emit)(tty
-            ? `✓ ${String(parsed.affectedRows)} row${parsed.affectedRows === 1 ? "" : "s"} ${verb}`
+            ? colors_1.c.success(`✓ ${String(parsed.affectedRows)} row${parsed.affectedRows === 1 ? "" : "s"} ${verb}`)
             : `OK ${String(parsed.affectedRows)} rows ${verb}`);
         return;
     }
     // DDL
-    (0, output_1.emit)(tty ? "✓ DDL executed" : "OK DDL executed");
+    (0, output_1.emit)(tty ? colors_1.c.success("✓ DDL executed") : "OK DDL executed");
 }
 function toJson(parsed) {
     if (parsed.kind === "select") {
@@ -307,7 +323,7 @@ function renderMultiPretty(results) {
             lines.push(`Statement ${String(idx)}: SELECT (${String(n)} row${n === 1 ? "" : "s"})`);
             if (n > 0) {
                 const cols = collectColumns(parsed.rows);
-                const tbl = parsed.rows.map((r) => cols.map((c) => formatCell(r[c], tty)));
+                const tbl = parsed.rows.map((r) => cols.map((col) => formatCell(r[col], tty)));
                 lines.push(tty ? (0, render_1.renderAlignedTable)(cols, tbl) : (0, render_1.renderTsv)(cols, tbl));
             }
             // 块间空行（最后一条不留）
@@ -318,15 +334,16 @@ function renderMultiPretty(results) {
         if (parsed.kind === "dml") {
             const verb = dmlVerb(parsed.sqlType);
             const n = parsed.affectedRows;
-            lines.push(`Statement ${String(idx)}: ${tty ? "✓ " : ""}${String(n)} row${n === 1 ? "" : "s"} ${verb}`);
+            const body = `${String(n)} row${n === 1 ? "" : "s"} ${verb}`;
+            lines.push(`Statement ${String(idx)}: ${tty ? colors_1.c.success("✓ " + body) : body}`);
             continue;
         }
         // DDL
-        lines.push(`Statement ${String(idx)}: ${tty ? "✓ " : ""}DDL executed`);
+        lines.push(`Statement ${String(idx)}: ${tty ? colors_1.c.success("✓ DDL executed") : "DDL executed"}`);
     }
     // 汇总行：所有 statement 都跑完了
     lines.push(tty
-        ? `✓ ${String(results.length)} statements executed`
+        ? colors_1.c.success(`✓ ${String(results.length)} statements executed`)
         : `OK ${String(results.length)} statements executed`);
     (0, output_1.emit)(lines.join("\n"));
 }
@@ -356,12 +373,275 @@ function collectColumns(rows) {
  */
 function formatCell(v, tty) {
     if (v === null || v === undefined) {
-        return tty ? "\u001b[2;90mNULL\u001b[0m" : "NULL";
+        return tty ? colors_1.c.muted("NULL") : "NULL";
     }
-    if (typeof v === "string")
+    if (typeof v === "string") {
+        // TTY 下检测到 ISO 8601 时间字符串 → 转成相对时间（"3h ago" / "2d ago" /
+        // "2026-03-15"），方便 _created_at / _updated_at 等列直观可读
+        if (tty && ISO_TIMESTAMP_RE.test(v) && !Number.isNaN(Date.parse(v))) {
+            return (0, render_1.formatTime)(v, tty);
+        }
         return v;
+    }
     if (typeof v === "number" || typeof v === "boolean")
         return String(v);
     // object / array → JSON
     return JSON.stringify(v);
 }
+/**
+ * 匹配 PG / ISO 8601 形态的日期时间字符串：
+ *   2026-04-29
+ *   2026-04-29 19:07:43           （PG 默认 timestamp 形态）
+ *   2026-04-29T19:07:43
+ *   2026-04-29T19:07:43.882+08:00
+ *   2026-04-29T19:07:43.882Z
+ * 时间部分 / 毫秒 / 时区可选。
+ */
+const ISO_TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+// ──────────────────────────────────────────────────────────────────────
+// db sql 错误富化：识别 PG 常见报错形态 → fuzzy match → 加 did-you-mean hint
+// ──────────────────────────────────────────────────────────────────────
+const SYNTAX_RE = /syntax error at or near "([^"]+)"/i;
+const RELATION_RE = /relation "([^"]+)" does not exist/i;
+const COLUMN_RE = /column "([^"]+)"(?: of relation "([^"]+)")? does not exist/i;
+/**
+ * 在错误抛出前富化 next_actions（最多 1 条 hint），按 PG 报错形态分发：
+ *
+ *   表 / 列不存在路径：
+ *     - `column "X" of relation "Y" does not exist`     → 在 Y 表的列里 fuzzy
+ *     - `column "X" does not exist`（未指定表）         → 跨表所有列合集 fuzzy
+ *     - `relation "X" does not exist`                   → 在所有表名里 fuzzy
+ *
+ *   语法错误路径（`syntax error at or near "X"`）三条互斥子路径：
+ *     a. X 字面就是保留字（用户拿 keyword 当标识符，如 `FROM order`，
+ *        但 `order` 是 PG 保留字）→ 当作"想引用的表名"，远程 schema fuzzy。
+ *        **不要建议 keyword 自己**，那只是把用户输入大写返还，毫无价值。
+ *     b. X 接近某 keyword（典型拼写错误，如 SELCT）→ suggest keyword
+ *     c. X 是数字 / 标点（如 `LIMITT 1` 报错点到 `1`）→ fallback 扫整段
+ *        SQL 找看似拼错的 keyword token
+ *
+ * 任一环节失败（pattern 不匹配 / 远程拉表失败 / 没 fuzzy 候选）都静默吞掉，
+ * 不破坏原始错误信息——原则："只在我们高置信能帮上忙时才插嘴"。
+ */
+async function enrichSqlError(err, ctx) {
+    if (!(err instanceof error_1.AppError))
+        return;
+    const msg = err.message;
+    // ── 表 / 列不存在路径 ──
+    // 注意：列报错 'column "X" of relation "Y"' 也含 'relation "Y"' 子串，
+    // 会同时命中 RELATION_RE。先 colMatch（更精确），命中后不再走 relation 分支。
+    const colMatch = COLUMN_RE.exec(msg);
+    const relMatch = colMatch ? null : RELATION_RE.exec(msg);
+    if (relMatch || colMatch) {
+        const tableMap = await loadTableMap(ctx);
+        if (!tableMap)
+            return;
+        if (relMatch) {
+            enrichRelationNotExist(err, relMatch[1], tableMap);
+        }
+        else if (colMatch) {
+            enrichColumnNotExist(err, colMatch, tableMap);
+        }
+        return;
+    }
+    // ── 语法错误路径 ──
+    const kwMatch = SYNTAX_RE.exec(msg);
+    if (!kwMatch)
+        return;
+    const token = kwMatch[1];
+    const upper = token.toUpperCase();
+    // 子路径 a：token 字面就是 keyword → 用户拿保留字当标识符
+    if (sql_keywords_1.SQL_KEYWORDS.includes(upper)) {
+        const tableMap = await loadTableMap(ctx);
+        if (!tableMap)
+            return;
+        const guess = (0, fuzzy_match_1.suggest)(token, Object.keys(tableMap));
+        if (guess) {
+            err.next_actions.push(`Did you mean table '${guess}'? '${token}' is a reserved keyword; ` +
+                `quote it as "${token}" if you really mean a table named '${token}'.`);
+        }
+        return;
+    }
+    // 子路径 b：token 接近 keyword（拼写错误）
+    const guess = (0, fuzzy_match_1.suggest)(upper, sql_keywords_1.SQL_KEYWORDS);
+    if (guess && guess !== upper) {
+        err.next_actions.push(`Check SQL keyword spelling. Did you mean "${guess}"?`);
+        return;
+    }
+    // 子路径 c：PG 错误位置点到了下一个 token（如 `LIMITT 1` → 报错指向 "1"），
+    //          扫整段 SQL 找看似拼错的 keyword
+    const typo = findKeywordTypo(ctx.sql);
+    if (typo) {
+        err.next_actions.push(`Check SQL keyword spelling. '${typo.input}' looks like '${typo.suggest}'.`);
+    }
+}
+/** 远程拉一次 schema 并扁平化为 `tableName → fieldName[]`。失败返 null（调用方静默不加 hint）。 */
+async function loadTableMap(ctx) {
+    try {
+        const resp = await api.db.getSchema({
+            appId: ctx.appId,
+            format: "schema",
+            dbBranch: ctx.env,
+        });
+        return extractTableFieldMap(resp.schema);
+    }
+    catch {
+        return null;
+    }
+}
+function enrichRelationNotExist(err, relation, tableMap) {
+    const guess = (0, fuzzy_match_1.suggest)(relation, Object.keys(tableMap));
+    if (guess) {
+        err.next_actions.push(`Did you mean '${guess}'? Run \`miaoda db schema list\` to see all tables.`);
+    }
+}
+function enrichColumnNotExist(err, colMatch, tableMap) {
+    const colName = colMatch[1];
+    // TS RegExpMatchArray 数字索引类型 = string，但 optional capture group `(...)?`
+    // 没匹配时运行时返 undefined；as cast 把这个事实告诉类型系统。
+    const relation = colMatch[2];
+    const relationCols = relation !== undefined
+        ? tableMap[relation]
+        : undefined;
+    if (relation !== undefined && relationCols !== undefined) {
+        // 指定了表 → 在该表的列里找
+        const guess = (0, fuzzy_match_1.suggest)(colName, relationCols);
+        if (guess) {
+            err.next_actions.push(`Did you mean column '${guess}' in table '${relation}'?`);
+        }
+    }
+    else {
+        // 没指定表（CTE / 别名 / 子查询场景）→ 在所有表的列合集里找
+        const allCols = Array.from(new Set(Object.values(tableMap).flat()));
+        const guess = (0, fuzzy_match_1.suggest)(colName, allCols);
+        if (guess) {
+            err.next_actions.push(`Did you mean '${guess}'? Run \`miaoda db schema get <table>\` to see columns.`);
+        }
+    }
+}
+/**
+ * 扫整段 SQL 找一个看似"拼错的关键字"token：纯字母 + 长度 ≥ 3 + 不是已知 keyword
+ * + fuzzy 命中某个 keyword（且距离 > 0）。返第一个命中的 token。
+ *
+ * 用于 `syntax error at or near "<X>"` 的 X 是数字 / 标点的兜底场景——例如
+ * `... LIMITT 1` 报错点到 `1`，但用户真正的拼写错误在 LIMITT。
+ *
+ * 阈值复用 suggest()，候选词越短匹配越严，避免把 `userid` / `usrname` 这种
+ * 用户标识符误抓为关键字 typo。
+ */
+function findKeywordTypo(sql) {
+    const tokens = sql.split(/[\s,;()'"`*=<>+\-./]+/).filter((t) => /^[A-Za-z_]{3,}$/.test(t));
+    for (const tok of tokens) {
+        const upper = tok.toUpperCase();
+        if (sql_keywords_1.SQL_KEYWORDS.includes(upper))
+            continue; // 写对的关键字
+        const guess = (0, fuzzy_match_1.suggest)(upper, sql_keywords_1.SQL_KEYWORDS);
+        if (guess && guess !== upper) {
+            return { input: tok, suggest: guess };
+        }
+    }
+    return null;
+}
+/** 从 InnerSchemaRespVO 提取 `tableName → fieldName[]` 映射，扁平化 tables/views/mvs 三池。 */
+function extractTableFieldMap(s) {
+    const out = {};
+    if (!s)
+        return out;
+    const pools = [s.tables?.data, s.views?.data, s.materializedViews?.data];
+    for (const pool of pools) {
+        if (!pool)
+            continue;
+        for (const t of pool) {
+            out[t.tableName] = (t.fields ?? []).map((f) => f.fieldName);
+        }
+    }
+    return out;
+}
+/**
+ * 多语句 SQL 失败时把服务端透传的 partial_results 包装成 PRD 期望形态：
+ *   - 用现有 toMultiElement 把每条 SQLExecuteResult 转成 `{command, ...}` 元素，
+ *     与正常 multi-statement 成功路径的 data[] 结构完全一致
+ *   - 推断 rolled_back：扫 completed 数组里 BEGIN/COMMIT/ROLLBACK 计数；失败时
+ *     还在 user tx 内 ⇒ 服务端 closeUserTxIfOpen 已发 ROLLBACK，标 true
+ *   - rolled_back=true 时给 next_actions 追加一句 spec 文案
+ *   - pretty 模式（非 JSON）把 `Statement N: ✓ ... / K: ✗ ...` 立即打到 stderr，
+ *     与 emitError 的 Error/hint 行连成一段 PRD 期望的 multi-statement 报告
+ */
+function enrichMultiStatementError(err, sql) {
+    if (!(err instanceof error_1.AppError))
+        return;
+    const partial = err.partial_results;
+    if (!Array.isArray(partial) || partial.length === 0)
+        return;
+    // 把 SQLExecuteResult[] 转成 PRD 兼容的 completed 数组
+    const completed = partial.map((r) => toMultiElement((0, index_1.parseSqlResult)(r)));
+    err.completed = completed;
+    err.rolled_back = inferRolledBack(completed);
+    err.total_statements = countStatements(sql);
+    // pretty 模式（非 JSON）打 per-statement breakdown 到 stderr
+    if (!(0, output_1.isJsonMode)()) {
+        writeMultiStatementBreakdown(err, completed);
+    }
+    // rolled_back=true 时追加 spec hint："Transaction rolled back; no changes persisted."
+    if (err.rolled_back) {
+        err.next_actions.push("Transaction rolled back; no changes persisted.");
+    }
+}
+/**
+ * 推断本次多语句执行最终是否处于"事务被回滚"状态：
+ *   遍历 completed[] 数组，BEGIN +1 / COMMIT|ROLLBACK -1；
+ *   失败时 depth > 0 → 用户事务还开着 → 服务端 closeUserTxIfOpen 发了 ROLLBACK
+ *   失败时 depth = 0 → 失败语句在 autocommit 模式 → 已成功的 statement 真实落库
+ */
+function inferRolledBack(completed) {
+    let depth = 0;
+    for (const e of completed) {
+        if (e.command === "BEGIN")
+            depth++;
+        else if (e.command === "COMMIT" || e.command === "ROLLBACK")
+            depth--;
+    }
+    return depth > 0;
+}
+/**
+ * 数 SQL 里有几条独立语句：先去掉单 / 双引号字面量（防止 'a;b' 里的分号被算成
+ * 分隔符），再按分号 split，过滤空条。CLI 用户场景几乎都是简单 SQL，不处理
+ * dollar-quoted（$$..$$）等高级形态——估错 ±1 不影响 hint 可读性。
+ */
+function countStatements(sql) {
+    const stripped = sql
+        .replace(/'(?:''|[^'])*'/g, "''")
+        .replace(/"(?:""|[^"])*"/g, '""');
+    return stripped.split(/;+/).filter((s) => s.trim().length > 0).length;
+}
+/**
+ * 写 `Statement N: ✓ ... / Statement K: ✗ ...` 到 stderr，对齐 PRD spec 的
+ * 多语句失败 pretty 输出形态。
+ */
+function writeMultiStatementBreakdown(err, completed) {
+    const tty = (0, render_1.isStdoutTty)();
+    const lines = [];
+    for (let i = 0; i < completed.length; i++) {
+        const e = completed[i];
+        const verb = e.command === "BEGIN" || e.command === "COMMIT" || e.command === "ROLLBACK"
+            ? e.command
+            : describeCompleted(e);
+        lines.push(`Statement ${String(i + 1)}: ${tty ? colors_1.c.success("✓ ") : "✓ "}${verb}`);
+    }
+    // 失败那条
+    const failedIdx = err.statement_index ?? completed.length;
+    lines.push(`Statement ${String(failedIdx + 1)}: ${tty ? colors_1.c.fail("✗ ") : "✗ "}${err.message}`);
+    process.stderr.write(lines.join("\n") + "\n\n");
+}
+/** completed 单条结果的人类可读描述（用于 stderr breakdown 行尾）。 */
+function describeCompleted(e) {
+    const r = e;
+    if (r.command === "SELECT" && Array.isArray(r.rows)) {
+        return `SELECT (${String(r.rows.length)} row${r.rows.length === 1 ? "" : "s"})`;
+    }
+    if (typeof r.rows_affected === "number") {
+        const verb = dmlVerb(r.command);
+        return `${String(r.rows_affected)} row${r.rows_affected === 1 ? "" : "s"} ${verb}`;
+    }
+    return `${r.command} executed`;
+}

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

@@ -45,6 +45,7 @@ const output_1 = require("../../../utils/output");
 const render_1 = require("../../../utils/render");
 const error_1 = require("../../../utils/error");
 const shared_1 = require("../../../cli/commands/shared");
+const colors_1 = require("../../../utils/colors");
 const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
 /**
  * 判断 src 是本地文件还是远程引用：
@@ -147,7 +148,7 @@ async function handleUpload(appId, localRaw, remoteRaw, rename) {
     const tty = (0, render_1.isStdoutTty)();
     const lines = [];
     if (tty) {
-        lines.push(`✓ Uploaded ${node_path_1.default.basename(localPath)} → ${result.path}`);
+        lines.push(colors_1.c.success(`✓ Uploaded ${node_path_1.default.basename(localPath)} → ${result.path}`));
         lines.push(`   file_name:     ${result.file_name}`);
         lines.push(`   path:          ${result.path}`);
         lines.push(`   size:          ${(0, render_1.formatSize)(result.size)} (${String(result.size)} bytes)`);
@@ -204,7 +205,7 @@ async function handleDownload(appId, remoteRaw, localRaw) {
     }
     const tty = (0, render_1.isStdoutTty)();
     if (tty) {
-        (0, output_1.emit)(`✓ Downloaded ${baseName} → ${localTarget} (${(0, render_1.formatSize)(writtenBytes)})`);
+        (0, output_1.emit)(colors_1.c.success(`✓ Downloaded ${baseName} → ${localTarget} (${(0, render_1.formatSize)(writtenBytes)})`));
     }
     else {
         (0, output_1.emit)(`OK Downloaded ${baseName} -> ${localTarget} (${String(writtenBytes)} bytes)`);

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

@@ -43,6 +43,7 @@ const error_1 = require("../../../utils/error");
 const shared_1 = require("../../../cli/commands/shared");
 const index_1 = require("../../../api/file/index");
 const render_1 = require("../../../utils/render");
+const colors_1 = require("../../../utils/colors");
 const node_readline_1 = __importDefault(require("node:readline"));
 const MAX_BATCH = 100;
 /**
@@ -228,9 +229,9 @@ async function handleFileRm(paths, opts) {
         const lines = [];
         for (const r of results) {
             if (r.status === "ok")
-                lines.push(`✓ Deleted ${r.input}`);
+                lines.push(colors_1.c.success(`✓ Deleted ${r.input}`));
             else
-                lines.push(`✗ ${r.input}: ${r.error.message}`);
+                lines.push(colors_1.c.fail(`✗ ${r.input}: ${r.error.message}`));
         }
         if (failCount === 0) {
             lines.push(`Deleted ${String(okCount)} of ${String(totalCount)} files`);

package/dist/utils/colors.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * 终端彩色高亮的语义层封装。
+ *
+ * 三层结构（自上而下：稳定→灵活）：
+ *
+ *   1. **ColorAdapter**（公共契约）：6 个语义方法 string → string，业务代码
+ *      只接触这层，对底层库 0 感知。
+ *   2. **ColorFactory**（适配器签名）：`(useColor: boolean) => ColorAdapter`，
+ *      把"是否染色"参数化，便于按需构造。一个三方库对应一个 factory 实现。
+ *   3. **当前底层库实现**：picocolors（[picocolors npm](https://www.npmjs.com/package/picocolors)，~3KB）。
+ *      切换到 chalk / kleur 等只需新增一个 ColorFactory 实现，并改最下方的
+ *      `factory =` 一行赋值，业务代码与 ColorAdapter contract 0 改动。
+ *
+ * # 色谱（对齐 spec）
+ *
+ *   - header     表头 / 命令名 / key 标签：bold + cyan
+ *   - highlight  强调值（表名等）：cyan
+ *   - success    ✓ Uploaded / ✓ Deleted：green
+ *   - fail       ✗ / Error:：red
+ *   - warn       ⚠ Approaching quota：yellow
+ *   - muted      NULL / 辅助 hint / 次要信息：dim + gray
+ *
+ * # 染色判定（NO_COLOR / FORCE_COLOR / TTY，[no-color.org](https://no-color.org/) 业界标准）
+ *
+ *   - `NO_COLOR=1`            强制关颜色（任何非空值生效）
+ *   - `FORCE_COLOR=1`         强制开颜色（管道 / CI 场景）
+ *   - 否则按 `process.stdout.isTTY` 判定
+ *
+ * 每次调用 `c.xxx(s)` 时按当前状态实时构造 adapter——避免模块加载时缓存的
+ * `process.stdout.isTTY` 与测试 / pipe 切换脱节。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.c = void 0;
+exports.shouldColorize = shouldColorize;
+const picocolors_1 = require("picocolors");
+// ──────────────────────────────────────────────────────────────────────
+// 2. 库无关的染色判定：哪个 factory 都能复用
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * 当前是否应当染色。读取的是**调用时**的状态，而非模块加载时缓存——
+ * 测试经常 `Object.defineProperty(process.stdout, "isTTY", ...)` 实时切换，
+ * 这里直接每次问 process。
+ *
+ * 优先级：FORCE_COLOR > NO_COLOR > TTY。
+ */
+function shouldColorize() {
+    const env = process.env;
+    const noColor = env.NO_COLOR != null && env.NO_COLOR !== "";
+    const forceColor = env.FORCE_COLOR != null && env.FORCE_COLOR !== "";
+    const isTTY = process.stdout.isTTY === true;
+    return forceColor || (!noColor && isTTY);
+}
+/** picocolors 实现：当前生产用 factory。~3KB，业界 CLI 标准之一。 */
+const picocolorsFactory = (useColor) => {
+    const x = (0, picocolors_1.createColors)(useColor);
+    return {
+        header: (s) => x.bold(x.cyan(s)),
+        highlight: (s) => x.cyan(s),
+        success: (s) => x.green(s),
+        fail: (s) => x.red(s),
+        warn: (s) => x.yellow(s),
+        muted: (s) => x.dim(x.gray(s)),
+    };
+};
+// ──────────────────────────────────────────────────────────────────────
+// 4. 唯一切换点：换库改这一行（其它都不用动）
+// ──────────────────────────────────────────────────────────────────────
+//
+// 切换示例：
+//
+//   import chalk, { Chalk } from "chalk";
+//   const chalkFactory: ColorFactory = (useColor) => {
+//     const k = new Chalk({ level: useColor ? 1 : 0 });
+//     return {
+//       header:    (s) => k.bold.cyan(s),
+//       highlight: (s) => k.cyan(s),
+//       success:   (s) => k.green(s),
+//       fail:      (s) => k.red(s),
+//       warn:      (s) => k.yellow(s),
+//       muted:     (s) => k.dim.gray(s),
+//     };
+//   };
+//   const factory: ColorFactory = chalkFactory;   // ← 改这里
+//
+const factory = picocolorsFactory;
+// ──────────────────────────────────────────────────────────────────────
+// 5. 公共出口：业务代码 import { c } from "../utils/colors"
+// ──────────────────────────────────────────────────────────────────────
+/** 语义染色器：业务代码唯一接触的对象。底层库切换 0 感知。 */
+exports.c = {
+    header: (s) => factory(shouldColorize()).header(s),
+    highlight: (s) => factory(shouldColorize()).highlight(s),
+    success: (s) => factory(shouldColorize()).success(s),
+    fail: (s) => factory(shouldColorize()).fail(s),
+    warn: (s) => factory(shouldColorize()).warn(s),
+    muted: (s) => factory(shouldColorize()).muted(s),
+};

package/dist/utils/error.js

@@ -6,6 +6,14 @@ class AppError extends Error {
     retryable;
     next_actions;
     statement_index;
+    total_statements;
+    /**
+     * 多语句失败时由 api.db.execSql 透传服务端 results（已成功的 statement 原始结构）。
+     * 由 db sql handler 转成 PRD 友好的 `completed` 数组 + 推断 `rolled_back` 后挂回到本对象。
+     */
+    partial_results;
+    completed;
+    rolled_back;
     constructor(code, message, opts) {
         super(message);
         this.name = "AppError";
@@ -21,6 +29,9 @@ class AppError extends Error {
             retryable: this.retryable,
             next_actions: this.next_actions,
             statement_index: this.statement_index,
+            total_statements: this.total_statements,
+            completed: this.completed,
+            rolled_back: this.rolled_back,
         };
     }
 }

package/dist/utils/fuzzy-match.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * 模糊匹配：基于 Levenshtein 编辑距离的"did-you-mean"建议器。
+ *
+ * 用于 CLI 错误路径的拼写纠错提示——当用户输入的 token（关键字 / 表名 / 列名）
+ * 与某个有效候选词"接近"时，给出 "Did you mean X?" 类的 hint。
+ *
+ * # 设计取舍
+ *
+ *   - **算法**：Damerau-Levenshtein DP（在标准 Levenshtein 基础上把"相邻字符
+ *     交换"算 1 步编辑——SQL 用户最常见的拼写错误就是 FORM/FROM、SELCT/SELECT
+ *     这类 transposition；纯 Levenshtein 把它们算 2 步会过严，触发不到 hint）。
+ *     约 30 行二维 DP 实现，不引第三方库；业界 CLI 拼写纠错事实标准。
+ *   - **大小写不敏感**：CLI 用户混用 SELECT / select 是常态，统一 lowercase 比较
+ *   - **阈值按候选词长度自适应**：避免短词过度匹配（"id" 不应该建议成 "in"）
+ *       len ≤ 4：max 1 编辑（短词严）
+ *       len 5-8：max 2 编辑
+ *       len ≥ 9：max 3 编辑（长词宽）
+ *   - **同分多候选**：返第一个；调用方负责候选词列表的稳定排序
+ *   - **找不到不强凑**：阈值外返 null，不"硬贴"无关建议
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.levenshtein = levenshtein;
+exports.suggest = suggest;
+/**
+ * 计算两个字符串的 Damerau-Levenshtein 编辑距离（不区分大小写）。
+ *
+ * 在标准 Levenshtein（增 / 删 / 替换）基础上加"相邻字符交换"作为单步编辑。
+ * 二维 DP 实现（transposition 需要回看 dp[i-2][j-2]，所以不再用单行优化）。
+ * 候选词通常 < 30 字符，二维 DP 的常数空间开销可忽略。
+ */
+function levenshtein(a, b) {
+    const aa = a.toLowerCase();
+    const bb = b.toLowerCase();
+    const m = aa.length;
+    const n = bb.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = aa[i - 1] === bb[j - 1] ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, // 删除
+            dp[i][j - 1] + 1, // 插入
+            dp[i - 1][j - 1] + cost);
+            // transposition: 当前字符 = 对方前一字符 && 我方前一字符 = 对方当前字符
+            // 例：aa="form", bb="from"，i=2,j=2 时 aa[1]=o=bb[0]=f? 不命中；i=3,j=3
+            // 时 aa[2]=r=bb[1]=r? bb[2]=o, aa[1]=o → 命中 → dp[3][3] = dp[1][1] + 1 = 1
+            if (i > 1 && j > 1 && aa[i - 1] === bb[j - 2] && aa[i - 2] === bb[j - 1]) {
+                dp[i][j] = Math.min(dp[i][j], dp[i - 2][j - 2] + 1);
+            }
+        }
+    }
+    return dp[m][n];
+}
+/** 默认阈值：候选词越短匹配越严，越长越宽。避免 "id" 错配 "in" 这种 false positive。 */
+function defaultThreshold(len) {
+    if (len <= 4)
+        return 1;
+    if (len <= 8)
+        return 2;
+    return 3;
+}
+/**
+ * 在候选词列表里找与 input 最相近的一个。
+ *
+ * 距离 ≤ 阈值时按"距离最小"返回；多个候选词相同距离时返"列表中最先出现"的；
+ * 阈值外没有命中返 null（调用方按 null 静默不加 hint，不要强凑）。
+ */
+function suggest(input, candidates, opts) {
+    if (!input || candidates.length === 0)
+        return null;
+    const threshold = opts?.maxDistance ?? defaultThreshold;
+    let best = null;
+    let bestDist = Number.POSITIVE_INFINITY;
+    for (const cand of candidates) {
+        const d = levenshtein(input, cand);
+        const limit = threshold(cand.length);
+        if (d <= limit && d < bestDist) {
+            best = cand;
+            bestDist = d;
+        }
+    }
+    return best;
+}

package/dist/utils/output.js

@@ -7,6 +7,27 @@ exports.emitOk = emitOk;
 exports.emitPaged = emitPaged;
 const config_1 = require("./config");
 const error_1 = require("./error");
+const colors_1 = require("./colors");
+/**
+ * 服务端错误码 → CLI 兜底 hint 文案。
+ *
+ * 服务端错误协议只有 `{code, msg}` 两个字段（dataloom InnerExecuteSQL 等 IDL
+ * 没有 hint / next_actions 通道），所以服务端给的错误本身永远没有 hint。
+ * 这里是 CLI 展示层为常见错误码补一份 spec 一致的 actionable 引导，按错误码
+ * 落到 next_actions。
+ *
+ * 仅在 next_actions 已经为空时介入——保留 handler / enrichSqlError 自己塞过的
+ * 具体 hint（如 did-you-mean、shared.resolveAppId 等），它们优先级更高。
+ */
+const SERVER_ERROR_HINTS = {
+    // SELECT 结果集超过 1000 行硬拦：spec 多行引导。
+    // key 用 BIZ_ERR_MAP 映射后的语义 code（不是原始服务端 k_dl_xxx），保持
+    // 与 help / 文档里宣传的 RESULT_SET_TOO_LARGE 一致。
+    "RESULT_SET_TOO_LARGE": [
+        "Add `LIMIT <n>` to your SQL to narrow the result.",
+        "For counts, use `SELECT count(*) FROM ...`; for aggregation, use GROUP BY with filters.",
+    ],
+};
 function isJsonMode() {
     const cfg = (0, config_1.getConfig)();
     return cfg.output === "json" || Boolean(cfg.json);
@@ -36,23 +57,55 @@ function emit(data) {
  */
 function emitError(err) {
     const info = toErrorInfo(err);
+    // 没人给过 next_actions 才走错误码兜底；handler 已经塞过具体 hint 时不覆盖
+    const hints = info.next_actions && info.next_actions.length > 0
+        ? info.next_actions
+        : (SERVER_ERROR_HINTS[info.code] ?? []);
     if (isJsonMode()) {
         const errObj = {
             code: info.code,
             message: info.message,
         };
-        if (info.next_actions && info.next_actions.length > 0) {
-            errObj.hint = info.next_actions.join(" ");
+        if (hints.length > 0) {
+            // JSON 输出压平成单行，更便于机器消费（脚本 / agent 拼字符串）
+            errObj.hint = hints.join(" ");
         }
         if (typeof info.statement_index === "number") {
             errObj.statement_index = info.statement_index;
         }
+        // PRD 多语句失败 envelope 额外字段：completed / rolled_back
+        if (Array.isArray(info.completed)) {
+            errObj.completed = info.completed;
+        }
+        if (typeof info.rolled_back === "boolean") {
+            errObj.rolled_back = info.rolled_back;
+        }
         process.stderr.write(JSON.stringify({ error: errObj }) + "\n");
     }
     else {
-        process.stderr.write(`Error: ${info.message}\n`);
-        if (info.next_actions && info.next_actions.length > 0) {
-            process.stderr.write(`  hint: ${info.next_actions.join(" ")}\n`);
+        // stderr 染色：picocolors 默认按 stdout.isTTY 判断；stderr 通常也是 tty，
+        // 这里复用 stdout 探测保持简单（stderr only-pipe 的极端场景留作后续优化）
+        // 多语句失败时 Error 行末尾追加 "(at statement K of N)"，与 PRD spec 对齐
+        let errorLine = `${colors_1.c.fail("Error:")} ${info.message}`;
+        if (typeof info.statement_index === "number") {
+            const k = info.statement_index + 1;
+            const n = info.total_statements;
+            errorLine += typeof n === "number" && n > 0
+                ? ` (at statement ${String(k)} of ${String(n)})`
+                : ` (at statement ${String(k)})`;
+        }
+        process.stderr.write(errorLine + "\n");
+        // 多行 hint：第一行带 "hint:" 标签，后续行用 8 空格缩进对齐 "  hint: " 之后的列。
+        // 对应 spec 期望的格式：
+        //   Error: ...
+        //     hint: 第一条建议
+        //           第二条建议
+        if (hints.length > 0) {
+            const [first, ...rest] = hints;
+            process.stderr.write(`  ${colors_1.c.muted("hint:")} ${first}\n`);
+            for (const line of rest) {
+                process.stderr.write(`        ${line}\n`);
+            }
         }
     }
 }

package/dist/utils/render.js

@@ -1,4 +1,14 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatSize = formatSize;
+exports.formatTime = formatTime;
+exports.visibleWidth = visibleWidth;
+exports.renderAlignedTable = renderAlignedTable;
+exports.renderTsv = renderTsv;
+exports.renderKeyValue = renderKeyValue;
+exports.isStdoutTty = isStdoutTty;
+exports.parseDuration = parseDuration;
+exports.parseSize = parseSize;
 /**
  * CLI 渲染 / 解析工具：跨域共用的格式化、表格渲染、字符串解析。
  *
@@ -9,18 +19,12 @@
  *   - 终端探测：isStdoutTty
  *   - 字符串解析：parseDuration / parseSize
  *
+ * 彩色高亮的语义层封装见 ./colors.ts。表头 / key 标签等结构性元素由本文件
+ * 主动调用 colors.c 染色；业务文案的染色（成功/失败 prefix 等）由 handler 自治。
+ *
  * JSON envelope 输出（emit / emitOk / emitPaged / emitError）见 ./output.ts。
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatSize = formatSize;
-exports.formatTime = formatTime;
-exports.visibleWidth = visibleWidth;
-exports.renderAlignedTable = renderAlignedTable;
-exports.renderTsv = renderTsv;
-exports.renderKeyValue = renderKeyValue;
-exports.isStdoutTty = isStdoutTty;
-exports.parseDuration = parseDuration;
-exports.parseSize = parseSize;
+const colors_1 = require("./colors");
 /** 将字节数格式化为人类可读（`24 KB` / `2.1 MB` / `1.5 GB`）。 */
 function formatSize(bytes) {
     if (!Number.isFinite(bytes) || bytes < 0)
@@ -109,7 +113,8 @@ function padVisibleEnd(s, targetWidth) {
     const w = visibleWidth(s);
     return w >= targetWidth ? s : s + " ".repeat(targetWidth - w);
 }
-/** 渲染 TTY 对齐表格（多行，列宽按最长内容；ANSI 转义不计入列宽）。 */
+/** 渲染 TTY 对齐表格（多行，列宽按最长内容；ANSI 转义不计入列宽）。
+ *  表头按 spec 用 bold + cyan 染色；ANSI 序列由 visibleWidth 剥离不影响列宽。 */
 function renderAlignedTable(headers, rows) {
     const colWidths = headers.map((h, i) => {
         let w = visibleWidth(h);
@@ -121,7 +126,7 @@ function renderAlignedTable(headers, rows) {
         return w;
     });
     const lines = [];
-    lines.push(headers.map((h, i) => padVisibleEnd(h, colWidths[i])).join("  ").trimEnd());
+    lines.push(headers.map((h, i) => colors_1.c.header(padVisibleEnd(h, colWidths[i]))).join("  ").trimEnd());
     for (const row of rows) {
         lines.push(row.map((cell, i) => padVisibleEnd(cell || "", colWidths[i])).join("  ").trimEnd());
     }
@@ -136,7 +141,7 @@ function renderTsv(headers, rows) {
     }
     return lines.join("\n");
 }
-/** 渲染 key-value 多行（用于 stat 等单条详情）。key 右对齐。 */
+/** 渲染 key-value 多行（用于 stat 等单条详情）。key 右对齐 + bold cyan 染色。 */
 function renderKeyValue(pairs, isTty) {
     if (pairs.length === 0)
         return "";
@@ -145,7 +150,7 @@ function renderKeyValue(pairs, isTty) {
     }
     const keyWidth = Math.max(...pairs.map(([k]) => k.length));
     return pairs
-        .map(([k, v]) => `${k.padStart(keyWidth)}:  ${v}`)
+        .map(([k, v]) => `${colors_1.c.header(k.padStart(keyWidth))}:  ${v}`)
         .join("\n");
 }
 /** 通用 isTTY 判定（stdout 是否交互终端）。Node 运行时 isTTY 为 true 或 undefined；TS 类型上 tty.WriteStream 定义为固定 true，绕开做运行时判断。 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.1-alpha.d20f110",
+  "version": "0.1.1-alpha.e70b415",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {
@@ -26,7 +26,8 @@
   },
   "dependencies": {
     "@lark-apaas/http-client": "^0.1.5",
-    "commander": "^13.1.0"
+    "commander": "^13.1.0",
+    "picocolors": "^1.1.1"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",