@lark-apaas/miaoda-cli 0.1.0-alpha.ec1a658 → 0.1.0-alpha.f914906

package/dist/api/db/api.js

@@ -6,7 +6,36 @@ exports.importData = importData;
 exports.exportData = exportData;
 const http_1 = require("../../utils/http");
 const error_1 = require("../../utils/error");
+const http_client_1 = require("@lark-apaas/http-client");
 const client_1 = require("./client");
+/**
+ * 把 SDK 抛出的 HttpError 统一映射成 CLI 层错误：
+ *   1. 先尝试从 response body 解 envelope，命中 dataloom 业务 code → AppError
+ *   2. 兜底返 HttpError，保留真实 status 码与上下文
+ *
+ * 配合调用点的 try/catch + traceHttp，让 --verbose 在错误路径上也能拿到
+ * x-tt-logid 与 status，方便定位线上问题。
+ */
+async function mapDbHttpError(err, url, ctx) {
+    if (err instanceof error_1.AppError)
+        throw err;
+    if (err instanceof http_client_1.HttpError) {
+        const status = err.response?.status ?? 0;
+        const statusText = err.response?.statusText ?? "";
+        try {
+            const body = (await err.response?.json());
+            if (body)
+                (0, client_1.extractData)(body); // 业务 code 命中 → 抛 AppError；不命中走兜底
+        }
+        catch (innerErr) {
+            if (innerErr instanceof error_1.AppError)
+                throw innerErr;
+            // body 解析失败 → 当成无 envelope 的纯 HTTP 错误处理
+        }
+        throw new error_1.HttpError(status, url, `${ctx}: ${String(status)} ${statusText}`.trim());
+    }
+    throw err;
+}
 // CLI 不再为 dbBranch 设默认值：
 // 用户没传 --env 就完全不携带 dbBranch query 参数，由后端 admin-inner 中间件
 // 按 workspace 多环境状态决定（多环境 → dev / 单环境 → main）。
@@ -25,20 +54,15 @@ async function execSql(opts) {
         dbBranch: opts.dbBranch,
     });
     const start = Date.now();
-    const response = await client.post(url, { sql: opts.sql });
-    (0, client_1.traceHttp)("POST", url, start, response);
-    if (!response.ok) {
-        // 4xx / 5xx：尝试解析 body 取 status_code 映射业务错误
-        let body = null;
-        try {
-            body = (await response.json());
-        }
-        catch {
-            // ignore
-        }
-        if (body)
-            (0, client_1.extractData)(body);
-        throw new error_1.HttpError(response.status, url, `Failed to execute SQL: ${String(response.status)} ${response.statusText}`);
+    let response;
+    try {
+        response = await client.post(url, { sql: opts.sql });
+        (0, client_1.traceHttp)("POST", url, start, response);
+    }
+    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");
+        throw err; // 不可达
     }
     const body = (await response.json());
     const data = (0, client_1.extractData)(body);
@@ -60,19 +84,15 @@ async function getSchema(opts) {
         dbBranch: opts.dbBranch,
     });
     const start = Date.now();
-    const response = await client.get(url);
-    (0, client_1.traceHttp)("GET", url, start, response);
-    if (!response.ok) {
-        let body = null;
-        try {
-            body = (await response.json());
-        }
-        catch {
-            // ignore
-        }
-        if (body)
-            (0, client_1.extractData)(body);
-        throw new error_1.HttpError(response.status, url, `Failed to get schema: ${String(response.status)} ${response.statusText}`);
+    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 schema");
+        throw err; // 不可达
     }
     const body = (await response.json());
     return (0, client_1.extractData)(body);
@@ -101,19 +121,15 @@ async function importData(opts) {
         reqBody.dbBranch = opts.dbBranch;
     }
     const start = Date.now();
-    const response = await client.post(url, reqBody);
-    (0, client_1.traceHttp)("POST", url, start, response);
-    if (!response.ok) {
-        let body = null;
-        try {
-            body = (await response.json());
-        }
-        catch {
-            // ignore
-        }
-        if (body)
-            (0, client_1.extractData)(body);
-        throw new error_1.HttpError(response.status, url, `Failed to import data: ${String(response.status)} ${response.statusText}`);
+    let response;
+    try {
+        response = await client.post(url, reqBody);
+        (0, client_1.traceHttp)("POST", url, start, response);
+    }
+    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");
+        throw err; // 不可达
     }
     // 后端 InnerAdminImportData 响应里 data 直接返 {tableName, recordCount, durationMs}
     const body = (await response.json());
@@ -144,20 +160,15 @@ async function exportData(opts) {
     });
     // POST + 空 body：所有业务参数都在 query 里
     const start = Date.now();
-    const response = await client.request({ method: "POST", url });
-    (0, client_1.traceHttp)("POST", url, start, response);
-    if (!response.ok) {
-        // 错误路径：body 是 JSON envelope
-        let body = null;
-        try {
-            body = (await response.json());
-        }
-        catch {
-            // ignore
-        }
-        if (body)
-            (0, client_1.extractData)(body);
-        throw new error_1.HttpError(response.status, url, `Failed to export data: ${String(response.status)} ${response.statusText}`);
+    let response;
+    try {
+        response = await client.request({ method: "POST", url });
+        (0, client_1.traceHttp)("POST", url, start, response);
+    }
+    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");
+        throw err; // 不可达
     }
     // 成功路径：响应 body 通常是原始 CSV/JSON 字节，但部分错误场景下网关会返
     // HTTP 200 + JSON envelope（status_code != "0"），需要在这里嗅探兜底。

package/dist/api/file/api.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTimeFilterMs = parseTimeFilterMs;
 exports.listFiles = listFiles;
 exports.resolveInputs = resolveInputs;
 exports.statFile = statFile;
@@ -82,15 +83,56 @@ function buildFilterExpr(opts) {
     }
     if (opts.uploadedSince) {
         // 后端期望毫秒 timestamp（strconv.ParseInt → time.UnixMilli）
-        const ms = Date.parse(opts.uploadedSince);
-        if (!Number.isNaN(ms)) {
-            conds.push({ field: "createdAt", operator: "gte", value: String(ms) });
-        }
+        const ms = parseTimeFilterMs(opts.uploadedSince, "--uploaded-since");
+        conds.push({ field: "createdAt", operator: "gte", value: String(ms) });
+    }
+    if (opts.uploadedUntil) {
+        const ms = parseTimeFilterMs(opts.uploadedUntil, "--uploaded-until");
+        conds.push({ field: "createdAt", operator: "lte", value: String(ms) });
     }
     if (conds.length === 0)
         return undefined;
     return { logic: "and", groups: [{ conditions: conds }] };
 }
+/**
+ * 解析时间过滤参数（--uploaded-since / --uploaded-until）的三种输入格式
+ * （→ ms timestamp）：
+ *   1. 相对时间："30s" / "10m" / "1h" / "2d" / "1w"  → 当前时间往前推 N 单位
+ *   2. 日期：    "2026-04-01"                       → 按当日 00:00:00 UTC
+ *   3. ISO 8601："2026-04-01T10:00:00Z"             → 严格解析（推荐用 Z 结尾标识 UTC）
+ *
+ * 三种格式都不命中时抛 AppError("ARGS_INVALID")，避免之前 Date.parse=NaN
+ * 时静默跳过过滤、用户却以为筛选生效的悄然失败问题。
+ *
+ * flagName 用于错误信息，调用方传 "--uploaded-since" 或 "--uploaded-until"。
+ */
+function parseTimeFilterMs(input, flagName) {
+    // 相对时间：<positive int><unit>，单位 s/m/h/d/w
+    const RELATIVE = /^(\d+)([smhdw])$/;
+    const rel = RELATIVE.exec(input);
+    if (rel) {
+        const n = parseInt(rel[1], 10);
+        if (n <= 0) {
+            throw new error_1.AppError("ARGS_INVALID", `${flagName} "${input}" 必须是正整数 + 单位（s / m / h / d / w）`);
+        }
+        const UNIT_MS = {
+            s: 1_000,
+            m: 60_000,
+            h: 3_600_000,
+            d: 86_400_000,
+            w: 604_800_000,
+        };
+        return Date.now() - n * UNIT_MS[rel[2]];
+    }
+    // 绝对时间：date / ISO 8601。Date.parse 对 "YYYY-MM-DD" 按 UTC 00:00:00 解析，
+    // 对带 Z 的 ISO 8601 也直接出 UTC ms。
+    const ms = Date.parse(input);
+    if (Number.isNaN(ms)) {
+        throw new error_1.AppError("ARGS_INVALID", `${flagName} "${input}" 格式无法识别。支持：` +
+            `相对时间（如 1h / 2d / 1w）、日期（YYYY-MM-DD）、ISO 8601（如 2026-04-01T10:00:00Z）`);
+    }
+    return ms;
+}
 /**
  * 列出文件：所有过滤下推到后端 FilterExpression，纯精确匹配，无 glob。
  *

package/dist/api/file/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toAbsolutePath = exports.looksLikePath = exports.resetBucketCache = exports.getDefaultBucketId = exports.resolveInputs = exports.deleteFiles = exports.downloadFile = exports.signDownload = exports.uploadFile = exports.statFile = exports.listFiles = void 0;
+exports.toAbsolutePath = exports.looksLikePath = exports.resetBucketCache = exports.getDefaultBucketId = exports.parseTimeFilterMs = exports.resolveInputs = exports.deleteFiles = exports.downloadFile = exports.signDownload = exports.uploadFile = exports.statFile = exports.listFiles = void 0;
 var api_1 = require("./api");
 Object.defineProperty(exports, "listFiles", { enumerable: true, get: function () { return api_1.listFiles; } });
 Object.defineProperty(exports, "statFile", { enumerable: true, get: function () { return api_1.statFile; } });
@@ -9,6 +9,7 @@ Object.defineProperty(exports, "signDownload", { enumerable: true, get: function
 Object.defineProperty(exports, "downloadFile", { enumerable: true, get: function () { return api_1.downloadFile; } });
 Object.defineProperty(exports, "deleteFiles", { enumerable: true, get: function () { return api_1.deleteFiles; } });
 Object.defineProperty(exports, "resolveInputs", { enumerable: true, get: function () { return api_1.resolveInputs; } });
+Object.defineProperty(exports, "parseTimeFilterMs", { enumerable: true, get: function () { return api_1.parseTimeFilterMs; } });
 var client_1 = require("./client");
 Object.defineProperty(exports, "getDefaultBucketId", { enumerable: true, get: function () { return client_1.getDefaultBucketId; } });
 Object.defineProperty(exports, "resetBucketCache", { enumerable: true, get: function () { return client_1.resetBucketCache; } });

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

@@ -5,65 +5,204 @@ const index_1 = require("../../../cli/handlers/db/index");
 function registerDbCommands(program) {
     const dbCmd = program
         .command("db")
-        .description("数据库操作：执行 SQL、查看表结构、导入导出数据");
+        .description("应用数据库（PostgreSQL）的命令行操作集合。")
+        .usage("<command> [flags]")
+        // --env 注册在 db 父级，spec 把它列入 db --help 的 Global Flags；
+        // leaf 命令仍各自接收 --env 值（commander 解析时父级 option 自动适用于子命令）
+        .option("--env <name>", "指定目标环境（dev / online，仅专家模式应用支持）");
     dbCmd.action(() => {
         dbCmd.outputHelp();
     });
     dbCmd
         .command("sql")
-        .description("执行 SQL 语句")
-        .argument("[query]", "要执行的 SQL 语句")
-        .option("--env <env>", "目标环境（main / dev）")
-        .action(async (query, opts) => {
-        await (0, index_1.handleDbSql)(query, opts);
-    });
+        .summary("执行任意 SQL（SELECT / DML / DDL，支持多条分号分隔）")
+        .description("执行 SQL 语句，支持 SELECT、DML、DDL 等所有标准 PostgreSQL 操作。\n" +
+        "支持通过 stdin 读取（miaoda db sql < file.sql），多条语句以分号分隔。\n" +
+        "事务控制使用 PG 原生的 BEGIN / COMMIT / ROLLBACK 语法。")
+        .usage("<query> [flags]")
+        .argument("[query]", "要执行的 SQL 语句；省略时从标准输入读取")
+        .action(async function (query) {
+        await (0, index_1.handleDbSql)(query, this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Notes:
+  - SELECT 结果超过 1000 行直接报错（RESULT_SET_TOO_LARGE），不做隐式截断。
+    需要分页时请在 SQL 中用 LIMIT / OFFSET。
+  - 多条语句不自动包事务：失败时后续不执行、已成功的不回滚。
+    需要原子性请显式 BEGIN; ...; COMMIT;
+  - --env 仅在专家模式应用且已 migration init 后可用。
+  - NULL 值在 --json 中是 JSON 原生 null，pretty / 管道中是字面字符串 NULL。
+
+Examples:
+  $ miaoda db sql "SELECT id, name, age FROM users LIMIT 10"
+  id    name     age
+  1001  Alice    28
+  1002  Bob      35
+
+  $ miaoda db sql "INSERT INTO users (name, age) VALUES ('Dave', 25)"
+  ✓ 1 row inserted
+
+  $ miaoda db sql < migration.sql
+  Statement 1: ✓ CREATE TABLE orders
+  Statement 2: ✓ 10 rows inserted
+  ✓ 2 statements executed
+
+  # 报错：SQL 语法错误
+  $ miaoda db sql "SELCT * FROM users"
+  Error: Syntax error at or near "SELCT"
+    hint: Check SQL keyword spelling. Did you mean "SELECT"?
+
+  # 报错：结果超过 1000 行
+  $ miaoda db sql "SELECT * FROM users"
+  Error: Result set exceeds the 1000-row limit (query would return 15234 rows)
+    hint: Add \`LIMIT <n>\` to your SQL to narrow the result.
+`);
     // schema 二级资源分组
     const schemaCmd = dbCmd
         .command("schema")
-        .description("查看表结构");
+        .summary("查看数据库表结构")
+        .description("查看应用数据库的表结构信息。")
+        .usage("<command> [flags]");
     schemaCmd.action(() => {
         schemaCmd.outputHelp();
     });
     schemaCmd
         .command("list")
-        .description("列出当前应用的所有表（含行数估算、占用大小、列数）")
-        .option("--env <env>", "目标环境（main / dev）")
-        .action(async (opts) => {
-        await (0, index_1.handleDbSchemaList)(opts);
-    });
+        .summary("列出所有表的概览（表名、行数、大小等）")
+        .description("列出当前应用所有表的概览信息：表名、描述、行数、大小、列数、最近更新时间。\n" +
+        "查看单表完整结构请用 `schema get`；查看 DDL 变更历史请用 `changelog`（P1）。")
+        .usage("[flags]")
+        .action(async function () {
+        await (0, index_1.handleDbSchemaList)(this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda db schema list
+  name      description   rows   size      columns   updated_at
+  users     用户信息          1523   2.1 MB    5         3h ago
+  orders    订单记录          8891   12.4 MB   8         2d ago
+  products  商品目录          342    512 KB    6         2026-03-15
+
+  $ miaoda db schema list --json name,rows
+  {
+    "data": [
+      {"name": "users", "rows": 1523},
+      {"name": "orders", "rows": 8891},
+      {"name": "products", "rows": 342}
+    ],
+    "next_cursor": null,
+    "has_more": false
+  }
+`);
     schemaCmd
         .command("get")
-        .description("查看单张表的字段、索引与建表语句")
-        .argument("<table>", "表名")
-        .option("--ddl", "输出完整建表语句而非概要")
-        .option("--env <env>", "目标环境（main / dev）")
-        .action(async (table, opts) => {
-        await (0, index_1.handleDbSchemaGet)(table, opts);
-    });
+        .summary("查看单表完整结构（列定义、索引、约束）")
+        .description("查看指定表的完整结构：列定义（含类型、可空、默认值、注释）、索引、行数、大小。\n" +
+        "默认 pretty 输出 CREATE TABLE 的 SQL 文本；--json 输出结构化字段。")
+        .usage("<table> [flags]")
+        .argument("<table>", "表名（无需带 schema 前缀）")
+        .option("--ddl", "强制输出 CREATE TABLE 建表语句（pretty 默认就是 DDL，--json 时配合此 flag 返 SQL 文本）")
+        .action(async function (table) {
+        await (0, index_1.handleDbSchemaGet)(table, this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda db schema get users
+  CREATE TABLE users (
+    id uuid DEFAULT gen_random_uuid() NOT NULL,
+    name varchar(100) NOT NULL,
+    email varchar(255),
+    age integer,
+    PRIMARY KEY (id),
+    UNIQUE (email)
+  );
+  COMMENT ON TABLE users IS '用户信息';
+  ...
+
+  # 报错：表不存在
+  $ miaoda db schema get userss
+  Error: Table 'userss' does not exist
+    hint: Did you mean 'users'? Run \`miaoda db schema list\` to see all tables.
+`);
     // data 二级资源分组
     const dataCmd = dbCmd
         .command("data")
-        .description("批量导入与导出数据");
+        .summary("表数据导入导出")
+        .description("表数据的批量导入导出，适合数据备份、跨环境迁移、外部分析。")
+        .usage("<command> [flags]");
     dataCmd.action(() => {
         dataCmd.outputHelp();
     });
     dataCmd
         .command("import")
-        .description("把本地 CSV / JSON 文件导入到表（单次最多 5000 行 / 1 MB，全部成功或全部回滚）")
-        .argument("<file>", "本地文件路径")
-        .option("--table <name>", "目标表名（缺省按文件名推断）")
-        .option("--format <fmt>", "文件格式 csv / json（缺省按扩展名推断）")
-        .action(async (file, opts) => {
-        await (0, index_1.handleDbDataImport)(file, opts);
-    });
+        .summary("从本地 CSV / JSON 文件导入数据到表")
+        .description("从本地 CSV / JSON 文件导入数据到表。整个导入是原子的——遇到任何错误（主键冲突、\n" +
+        "类型不匹配、列名不匹配等）会回滚已插入的所有行。\n" +
+        "不支持 SQL 文件，SQL 备份请用 `miaoda db sql < <文件>.sql` 回放。")
+        .usage("<file> [flags]")
+        .argument("<file>", "本地文件路径（CSV 或 JSON 格式）")
+        .option("--table <name>", "目标表名；未指定时按文件名（不含扩展名）推断（如 users.csv → users）")
+        .option("--format <fmt>", "文件格式 csv / json；未指定时按文件扩展名推断")
+        .action(async function (file) {
+        await (0, index_1.handleDbDataImport)(file, this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Notes:
+  - 目标表必须已存在；CSV 表头 / JSON 顶层 key 必须与表字段名完全一致。
+  - 导入为原子操作：遇到错误回滚所有已插入行，不会出现部分导入的中间状态。
+  - 仅支持 .csv 和 .json 文件扩展名。
+
+Examples:
+  $ miaoda db data import users.csv
+  ✓ Imported users.csv → table 'users' (1523 rows)
+
+  $ miaoda db data import data.csv --table users
+  ✓ Imported data.csv → table 'users' (1523 rows)
+
+  # 报错：CSV 表头与字段不匹配
+  $ miaoda db data import users.csv
+  Error: Column 'full_name' in CSV does not match any column in table 'users'
+    hint: Expected columns: id, name, email, age. Check CSV header row.
+
+  # 报错：主键冲突（已回滚）
+  $ miaoda db data import users.csv
+  Error: Primary key conflict at row 42 (id=1001 already exists), 0 rows imported
+    hint: Deduplicate input data, or remove conflicting rows first with
+          \`miaoda db sql "DELETE FROM users WHERE id IN (...)"\`.
+`);
     dataCmd
         .command("export")
-        .description("把整张表导出为 CSV / JSON 文件（单次最多 5000 行 / 1 MB）")
-        .argument("<table>", "表名")
-        .option("--format <fmt>", "导出格式 csv / json（默认 csv）")
-        .option("-f, --file <path>", "输出文件路径（默认 <table>.<format>）")
+        .summary("导出表数据到本地 CSV / JSON / SQL 文件")
+        .description("把指定表的所有数据导出到本地文件，支持 CSV / JSON / SQL 三种格式。")
+        .usage("<table> [flags]")
+        .argument("<table>", "表名（无需带 schema 前缀）")
+        .option("--format <fmt>", "导出格式 csv / json / sql，默认 csv（sql 输出 INSERT 语句，可用 db sql < file.sql 回放）")
+        .option("-f, --file <path>", "输出文件路径，默认 <表名>.<格式>")
         .option("--limit <n>", "最多导出行数（不超过 5000）")
-        .action(async (table, opts) => {
-        await (0, index_1.handleDbDataExport)(table, opts);
-    });
+        .action(async function (table) {
+        await (0, index_1.handleDbDataExport)(table, this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Notes:
+  - SQL 格式生成 INSERT 语句，可用 \`miaoda db sql < <文件>.sql\` 在其他环境回放。
+  - 文件已存在时默认报错（FILE_ALREADY_EXISTS），用 --force 覆盖或 -f 改路径。
+
+Examples:
+  $ miaoda db data export users
+  ✓ Exported users → users.csv (1523 rows)
+
+  $ miaoda db data export users --format json
+  ✓ Exported users → users.json (1523 rows)
+
+  $ miaoda db data export users --format sql -f users_backup.sql
+  ✓ Exported users → users_backup.sql (1523 rows)
+
+  $ miaoda db data export users -f ~/Desktop/users.csv
+  ✓ Exported users → ~/Desktop/users.csv (1523 rows)
+
+  # 报错：文件已存在
+  $ miaoda db data export users
+  Error: Output file 'users.csv' already exists
+    hint: Use -f to specify a different path, or --force to overwrite.
+`);
 }

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

@@ -19,57 +19,194 @@ function parsePositiveInt(raw) {
 function registerFileCommands(program) {
     const fileCmd = program
         .command("file")
-        .description("文件操作:上传、下载、删除、查询");
+        .description("应用文件存储（TOS）的命令行操作集合。操作对象是 UGC 资源（用户上传的文件、应用运行时\n" +
+        "生成的报表 / 导出文件等），不涉及代码仓库里的本地文件。")
+        .usage("<command> [flags]");
     fileCmd.action(() => {
         fileCmd.outputHelp();
     });
     fileCmd
         .command("ls")
-        .description("列出应用下的文件")
-        .argument("[query]", "可选筛选值：以 / 开头视为路径（精确匹配），否则按文件名匹配")
+        .summary("列出 / 筛选文件")
+        .description("列出当前应用存储里的文件，支持按文件名、大小、上传时间筛选，以及游标分页。\n" +
+        "默认 pretty 输出省略 download_url（列宽限制），需获取请用 --json。")
+        .usage("[query] [flags]")
+        .argument("[query]", "筛选值：以 / 开头视为路径精确匹配，否则按文件名精确匹配")
         .option("--path <path>", "按路径精确匹配")
         .option("--name <name>", "按文件名精确匹配")
         .option("--type <mime>", "按 MIME 类型筛选（如 image/png）")
-        .option("--size-gt <size>", "文件大小下限（支持 B/KB/MB/GB）")
-        .option("--size-lt <size>", "文件大小上限（支持 B/KB/MB/GB）")
-        .option("--uploaded-since <time>", "上传时间下限（ISO 8601）")
-        .option("--limit <n>", "单次返回上限（正整数，默认 50）", parsePositiveInt, 50)
+        .option("--size-gt <size>", "文件大小下限（支持 B / KB / MB / GB）")
+        .option("--size-lt <size>", "文件大小上限（支持 B / KB / MB / GB）")
+        .option("--uploaded-since <time>", "上传时间下限（晚于该时间），支持：相对时间 1h / 2d / 1w；日期 YYYY-MM-DD；ISO 8601 如 2026-04-01T10:00:00Z")
+        .option("--uploaded-until <time>", "上传时间上限（早于该时间），支持：相对时间 1h / 2d / 1w；日期 YYYY-MM-DD；ISO 8601 如 2026-04-01T10:00:00Z")
+        .option("--limit <n>", "单次返回上限（正整数,默认 50）", parsePositiveInt, 50)
         .option("--cursor <token>", "分页游标，从上次响应的 next_cursor 取值")
         .option("--all", "自动翻页返回全部结果")
         .action(async (query, opts) => {
         await (0, index_1.handleFileLs)({ ...opts, query });
-    });
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda file ls
+  file_name    path                                size      type              uploaded_at
+  logo.png     /images/brand/1858537546760216.png  24 KB     image/png         3h ago
+  hero.jpg     /images/1858537546760217.jpg        128 KB    image/jpeg        2d ago
+  report.pdf   /docs/1858537546760218.pdf          2.1 MB    application/pdf   2026-04-10
+
+  $ miaoda file ls --name logo.png
+  file_name    path                                size      type        uploaded_at
+  logo.png     /images/brand/1858537546760216.png  24 KB     image/png   3h ago
+
+  $ miaoda file ls --uploaded-since 7d --size-gt 1MB
+  ...
+`);
     fileCmd
         .command("stat")
-        .description("查看文件的元数据（不含下载链接，需要链接请用 sign）")
-        .argument("<file>", "文件的路径或文件名")
+        .summary("查看单文件元数据")
+        .description("查看单文件完整元数据，含 download_url（应用内消费）。\n" +
+        "需要公网可访问的临时链接请用 `file sign` 生成 signed_url。")
+        .usage("<file> [flags]")
+        .argument("<file>", "文件的路径或文件名（自动识别）")
         .action(async (file, opts) => {
         await (0, index_1.handleFileStat)(file, opts);
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - <file> 可传 path（推荐，全局唯一）或 file_name。
+  - file_name 重名时报 AMBIGUOUS_FILE_NAME，需先 \`ls --name\` 拿到 path 再调用。
+
+Examples:
+  $ miaoda file stat /images/brand/1858537546760216.png
+       file_name:  logo.png
+            path:  /images/brand/1858537546760216.png
+            size:  24 KB (24580 bytes)
+            type:  image/png
+     uploaded_by:  alice
+     uploaded_at:  2026-04-15 10:30:00
+    download_url:  /spark/app/.../1858537546760216.png
+
+  # 报错：file_name 多匹配
+  $ miaoda file stat logo.png
+  Error: Multiple files match name 'logo.png' (2 found)
+    hint: Use path instead. Run \`miaoda file ls --name logo.png\` to see candidates.
+`);
     fileCmd
         .command("cp")
-        .description("上传或下载文件（按 src/dst 自动判断方向）")
-        .argument("<src>", "源：本地文件路径 或 远程文件路径/名")
-        .argument("<dst>", "目标：本地路径 或 远程路径")
+        .summary("上传或下载文件（方向由路径前缀自动判断）")
+        .description("上传或下载文件，方向由 src/dst 路径前缀自动判断：\n" +
+        "  / 开头           → 远程 TOS 路径\n" +
+        "  ./、~/、裸文件名  → 本地路径")
+        .usage("<src> <dst> [flags]")
+        .argument("<src>", "源：本地文件路径或远程文件路径 / 文件名")
+        .argument("<dst>", "目标：本地路径或远程路径")
         .option("--rename <name>", "上传后在远端使用的新文件名")
         .action(async (src, dst, opts) => {
         await (0, index_1.handleFileCp)(src, dst, opts);
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - 单文件上限 100 MB，超过请拆分或用 web console 上传。
+  - 同目录下允许同 file_name 并存（每次上传生成新的 path），不会因重名失败。
+  - 下载时 src 必须是完整 path（裸 file_name 会被识别为本地路径）。
+  - 上传成功返回 download_url，可写入数据库 / 应用代码作为永久引用。
+
+Examples:
+  # 上传：本地 → 远程
+  $ miaoda file cp ./logo.png /images/brand/
+  ✓ Uploaded logo.png → /images/brand/1858537546760216.png
+         file_name:  logo.png
+              path:  /images/brand/1858537546760216.png
+              size:  24 KB (24580 bytes)
+              type:  image/png
+      download_url:  /spark/app/.../1858537546760216.png
+
+  # 下载：远程 → 本地
+  $ miaoda file cp /images/brand/1858537546760216.png ~/Desktop/
+  ✓ Downloaded 1858537546760216.png → ~/Desktop/logo.png (24 KB)
+
+  # 上传时改名
+  $ miaoda file cp ./photo.png /images/ --rename avatar.png
+  ✓ Uploaded photo.png → /images/1858537546760301.png
+
+  # 报错：本地源文件不存在
+  $ miaoda file cp ./missing.png /images/
+  Error: Local file './missing.png' does not exist
+
+  # 报错：超过上传上限
+  $ miaoda file cp ./video.mp4 /videos/
+  Error: File size 230 MB exceeds the 100 MB upload limit
+    hint: Split the file, or use the web console for large uploads.
+`);
     fileCmd
         .command("rm")
-        .description("批量删除文件（单次最多 100 个，部分失败不影响其他）")
+        .summary("删除一个或多个文件")
+        .description("删除一个或多个文件。<file> 可传 path（推荐）或 file_name，可混用。\n" +
+        "操作不可撤销（不进回收站），TTY 下默认会要求二次确认。")
+        .usage("[paths...] [flags]")
         .argument("[paths...]", "要删除的文件，每项可填路径或文件名（自动识别）")
-        .option("-n, --name <name>", "按文件名删除（可多次指定）", (value, prev) => [...(prev ?? []), value])
-        .option("-y, --yes", "跳过交互确认（脚本 / agent 调用必加）")
+        .option("-n, --name <name>", "按文件名删除（可重复指定）", (value, prev) => [...(prev ?? []), value])
+        .option("-y, --yes", "跳过交互确认；非交互场景必加")
         .action(async (paths, opts) => {
         await (0, index_1.handleFileRm)(paths, opts);
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - 删除不可撤销，没有回收站。
+  - 批量场景下失败项不影响其他项；全部成功退出码 0，任意一项失败退出码 1。
+  - --json 输出每项保留输入顺序，含 status: "ok" | "error" 字段。
+
+Examples:
+  # 单文件删除（TTY 下需确认）
+  $ miaoda file rm /images/brand/1858537546760216.png
+  ? Delete '/images/brand/1858537546760216.png'? (y/N) y
+  ✓ Deleted /images/brand/1858537546760216.png
+
+  # 批量删除（混用 path 与 file_name）
+  $ miaoda file rm /images/A.png /images/B.png /docs/C.pdf --yes
+  ✓ Deleted /images/A.png
+  ✓ Deleted /images/B.png
+  ✓ Deleted /docs/C.pdf
+  Deleted 3 of 3 files
+
+  # 部分失败（其他项仍会被删除）
+  $ miaoda file rm logo.png missing.png report.pdf --yes
+  ✓ Deleted logo.png
+  ✗ missing.png: File does not exist
+  ✓ Deleted report.pdf
+  Deleted 2 of 3 files (1 failed)
+
+  # 报错：file_name 多匹配
+  $ miaoda file rm logo.png --yes
+  Error: Multiple files match name 'logo.png' (2 found)
+    hint: Use path instead. Run \`miaoda file ls --name logo.png\` to see candidates.
+`);
     fileCmd
         .command("sign")
-        .description("生成可分享的临时下载链接")
+        .summary("生成公网可访问的临时下载链接")
+        .description("生成 signed_url——公网可直接访问的临时下载链接，带过期时间。\n" +
+        "仅在需要浏览器打开 / 公网分享时使用；应用代码内引用文件请用 download_url\n" +
+        "（来自 cp 或 stat），无需 sign。")
+        .usage("<file> [flags]")
         .argument("<file>", "文件的路径或文件名")
-        .option("--expires <duration>", "链接有效期，支持 30m / 24h / 7d 单位（默认 7d，最长 30d）")
+        .option("--expires <duration>", "链接有效期，支持 30m / 24h / 7d 等单位（默认 1d，最长 30d）")
         .action(async (file, opts) => {
         await (0, index_1.handleFileSign)(file, opts);
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - <file> 可传 path（推荐）或 file_name；重名报 AMBIGUOUS_FILE_NAME。
+  - signed_url 会过期，不要持久化到数据库。永久引用请用 download_url。
+
+Examples:
+  $ miaoda file sign /images/brand/1858537546760216.png
+  https://miaoda.feishu.cn/storage/.../1858537546760216.png?token=xxx&expires=86400
+
+  $ miaoda file sign /images/brand/1858537546760216.png --expires 30d
+  https://miaoda.feishu.cn/storage/.../1858537546760216.png?token=xxx&expires=2592000
+
+  # 报错：过期时间超过上限
+  $ miaoda file sign /images/brand/1858537546760216.png --expires 60d
+  Error: Expires duration '60d' exceeds the maximum of 30d
+    hint: Maximum allowed value is 30d. Use \`--expires 30d\` for the longest link.
+`);
 }

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

@@ -5,7 +5,8 @@ const index_1 = require("../../../cli/handlers/plugin/index");
 function registerPluginCommands(program) {
     const pluginCmd = program
         .command("plugin")
-        .description("插件管理：安装/更新/移除插件包，查询 capability 实例");
+        .description("插件管理：安装/更新/移除插件包，查询 capability 实例")
+        .usage("<command> [flags]");
     pluginCmd.action(() => {
         pluginCmd.outputHelp();
     });

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

@@ -135,12 +135,15 @@ function resolveFormat(explicit, ext, scope, fallback) {
         return "csv";
     if (raw === "json")
         return "json";
+    // sql 仅 export 路径接受 —— import 端后端仍只支持 csv/json。
+    if (raw === "sql" && scope === "export")
+        return "sql";
     const code = scope === "import" ? "IMPORT_FORMAT_UNSUPPORTED" : "EXPORT_FORMAT_UNSUPPORTED";
     throw new error_1.AppError(code, `Unrecognized format '${raw || "(unspecified)"}'`, {
         next_actions: [
             scope === "import"
                 ? "Supported formats: .csv, .json. Convert the file first, or rename with the correct extension."
-                : "Supported formats: csv, json. Pass --format csv|json.",
+                : "Supported formats: csv, json, sql. Pass --format csv|json|sql.",
         ],
     });
 }

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

@@ -32,15 +32,22 @@ 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.handleDbSql = handleDbSql;
 const api = __importStar(require("../../../api/index"));
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 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 index_1 = require("../../../api/db/index");
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
 /**
  * miaoda db sql <query> — 执行任意 SQL。
  *
@@ -69,14 +76,122 @@ async function handleDbSql(query, opts) {
     }
     if (results.length === 1) {
         renderSingle(results[0]);
+        await maybeSyncAgentSchema(results);
         return;
     }
     // 多语句：每条 statement 独立结果
     if ((0, output_1.isJsonMode)()) {
         (0, output_1.emit)({ data: results.map((r) => toMultiElement((0, index_1.parseSqlResult)(r))) });
+    }
+    else {
+        renderMultiPretty(results);
+    }
+    await maybeSyncAgentSchema(results);
+}
+/**
+ * 当本次 SQL 包含成功执行的 DDL 时，触发 `npm run gen:db-schema`（实质执行
+ * fullstack-cli gen-db-schema → drizzle-kit introspect）同步 agent 项目的
+ * schema.ts。**弱依赖**：失败不阻塞主流程退出码。
+ *
+ * 行为细节：
+ *   - 仅当 cwd/package.json 定义了 gen:db-schema 脚本时才尝试运行；非 agent
+ *     项目静默跳过
+ *   - 默认静默捕获子进程 stdout/stderr，成功只打一行 "Agent schema synced"，
+ *     失败时把捕获的输出回放给用户排查；--verbose 实时透传方便看进度
+ *   - 加 60s 兜底超时：drizzle-kit introspect 通常 < 30s，超时直接 SIGKILL，
+ *     避免 DB 慢或网络抖动时把 CLI 挂死
+ *   - 子进程的 stdout / stderr 都不会进入当前 CLI 的 stdout，--json 输出干净
+ *
+ * 调用时机：在 SQL 主输出 emit 完成之后；execSql 已经返回意味着所有
+ * statement 都执行成功，无需再校验逐条状态。
+ */
+/** agent runtime 中固定的项目根目录；放在此处便于以后调整。 */
+const AGENT_PROJECT_ROOT = "/home/gem/workspace/code";
+/** drain 子进程 pipe stream：默认静默模式下消费 chunk 防止缓冲区反压。 */
+function drainChunk(_chunk) {
+    // 显式接 chunk 参数让 ESLint 不再当成 empty function；不做任何处理
+}
+async function maybeSyncAgentSchema(results) {
+    if (!hasDdl(results))
+        return;
+    const projectRoot = await resolveAgentProjectRoot();
+    if (!projectRoot) {
+        (0, logger_1.debug)("[db sql] agent project root not found or missing gen:db-schema script, skip schema sync");
         return;
     }
-    renderMultiPretty(results);
+    const verbose = (0, config_1.getConfig)().verbose;
+    // drizzle-kit introspect 通常 < 30s；60s 兜底，超过即认为卡住
+    const TIMEOUT_MS = 60_000;
+    (0, logger_1.debug)(`[db sql] DDL detected, running \`npm run gen:db-schema\` in ${projectRoot}`);
+    try {
+        await new Promise((resolve) => {
+            const proc = (0, node_child_process_1.spawn)("npm", ["run", "gen:db-schema"], {
+                stdio: ["ignore", "pipe", "pipe"],
+                cwd: projectRoot,
+            });
+            // --verbose：实时透传到 stderr 看进度；默认完全静默丢弃。
+            // 任何路径下子进程输出都不会进入当前 CLI 的 stdout，--json 模式安全。
+            // 注：默认路径必须 attach 监听器，否则 pipe 缓冲区写满会反压子进程。
+            if (verbose) {
+                proc.stdout.pipe(process.stderr);
+                proc.stderr.pipe(process.stderr);
+            }
+            else {
+                proc.stdout.on("data", drainChunk);
+                proc.stderr.on("data", drainChunk);
+            }
+            let timedOut = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                proc.kill("SIGKILL");
+            }, TIMEOUT_MS);
+            proc.on("close", (code) => {
+                clearTimeout(timer);
+                if (timedOut) {
+                    (0, logger_1.debug)(`[db sql] gen:db-schema timed out after ${String(TIMEOUT_MS / 1000)}s, killed`);
+                }
+                else if (code !== 0 && code !== null) {
+                    (0, logger_1.debug)(`[db sql] gen:db-schema exited with code ${String(code)}`);
+                }
+                else {
+                    (0, logger_1.debug)("[db sql] gen:db-schema completed");
+                }
+                resolve();
+            });
+            proc.on("error", (err) => {
+                clearTimeout(timer);
+                (0, logger_1.debug)(`[db sql] gen:db-schema spawn error: ${err.message}`);
+                resolve();
+            });
+        });
+    }
+    catch (err) {
+        (0, logger_1.debug)(`[db sql] gen:db-schema unexpected error: ${String(err)}`);
+    }
+}
+/**
+ * 校验 AGENT_PROJECT_ROOT 是否是一个有效的 agent 项目（package.json 含
+ * `gen:db-schema` 脚本）。命中返回路径；缺失任一条件返 null，让调用方静默跳过。
+ *
+ * 这里不再从 process.cwd() 向上查找：agent runtime 里项目根是固定路径，
+ * 在 CLI 之外（本地手动跑 miaoda db sql）也不应触发同步。
+ */
+async function resolveAgentProjectRoot() {
+    try {
+        const pkgPath = node_path_1.default.join(AGENT_PROJECT_ROOT, "package.json");
+        const raw = await node_fs_1.promises.readFile(pkgPath, "utf8");
+        const pkg = JSON.parse(raw);
+        if (pkg.scripts?.["gen:db-schema"])
+            return AGENT_PROJECT_ROOT;
+    }
+    catch {
+        // 路径不存在 / 不可读 / 不是 agent 项目 → 静默跳过
+    }
+    return null;
+}
+/** 是否有任意一条 statement 是 DDL（CREATE / ALTER / DROP / GRANT / TRUNCATE / COMMENT 等）。 */
+function hasDdl(results) {
+    return results.some((r) => (0, index_1.parseSqlResult)(r).kind === "ddl");
 }
 /** 读取 stdin 并返回完整 SQL 文本（stdin 不是 TTY 即认为被 pipe）。 */
 async function readSql(inline) {

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

@@ -82,6 +82,7 @@ async function handleFileLs(opts) {
         sizeGt,
         sizeLt,
         uploadedSince: opts.uploadedSince,
+        uploadedUntil: opts.uploadedUntil,
     });
     if ((0, output_1.isJsonMode)()) {
         (0, output_1.emitPaged)(result.items, result.next_cursor, result.has_more);

package/dist/cli/help.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MiaodaHelp = void 0;
+const commander_1 = require("commander");
+/**
+ * MiaodaHelp 重写 commander 默认的 --help 输出，使之对齐 CLI 文档规范：
+ *
+ *   1. 描述放在最前（commander 默认是 Usage 在前、描述在后）
+ *   2. "Options:" 重命名为 "Flags:"，"Global Options:" 重命名为 "Global Flags:"
+ *   3. Usage 段独占一行 Heading + 缩进展示 usage 行
+ *   4. 段落顺序：描述 → Usage → Arguments → Commands → Flags → Global Flags
+ *      → Notes（addHelpText） → Examples（addHelpText）
+ *      （父命令不带 Examples，由 formatHelp 末尾自动追加 "Use ... --help" 提示）
+ *   5. Root 命令的 local options 视作 Global Flags（root 无 command-specific flag）
+ *   6. 子命令隐藏 -v / --version（仅 root 暴露）和自动生成的 `help` 子命令
+ *
+ * Notes / Examples 段由各命令通过 addHelpText('after', ...) 自行追加，
+ * 本类不直接生成 —— 框架与文案分层。
+ */
+class MiaodaHelp extends commander_1.Help {
+    // 全局默认开启：所有子命令 --help 都展示 Global Flags 段
+    showGlobalOptions = true;
+    /**
+     * 父级 --help 的 Commands 列表里展示子命令调用形态。spec 要求只展示
+     * `name <args>` 不带 `[flags]` 尾巴：
+     *
+     *   - 子命令是分组（含下级 subcommand）→ 只显示 name
+     *   - 子命令是 leaf 且配置了 usage()  → "name <args>"（usage 末尾的 [flags] 去掉）
+     *   - leaf 没配置 usage              → 退回 commander 默认行为
+     */
+    subcommandTerm(cmd) {
+        if (cmd.commands.length > 0) {
+            return cmd.name();
+        }
+        const usage = cmd.usage();
+        if (usage) {
+            // 去掉末尾的 [flags] / [options]，对齐 spec 的 "name <args>" 形态
+            const argsOnly = usage.replace(/\s*\[(?:flags|options)\]\s*$/i, "").trim();
+            return argsOnly ? `${cmd.name()} ${argsOnly}` : cmd.name();
+        }
+        return super.subcommandTerm(cmd);
+    }
+    /**
+     * 父命令的 Commands 列表里：
+     *   - 优先用子命令的 .summary()（短摘要，对齐 spec 父级列表用的简短描述）
+     *   - 否则取 description 首行，避免多行 description 把列表撑乱
+     * 叶子命令自身 --help 仍展示完整 description。
+     */
+    subcommandDescription(cmd) {
+        const summary = cmd.summary();
+        if (summary)
+            return summary;
+        const desc = super.subcommandDescription(cmd);
+        const idx = desc.indexOf("\n");
+        return idx === -1 ? desc : desc.slice(0, idx);
+    }
+    /**
+     * Flags 段里去掉那些已经在父命令注册过的选项（避免在 Flags 与 Global Flags
+     * 里重复展示，例如 --env 在 db 父级注册后，leaf 即使本地也注册一份也只在
+     * Global Flags 里出现一次）。
+     */
+    visibleOptions(cmd) {
+        const opts = super.visibleOptions(cmd);
+        if (!cmd.parent)
+            return opts;
+        const parentLongs = new Set();
+        let p = cmd.parent;
+        while (p) {
+            for (const o of p.options) {
+                if (o.long)
+                    parentLongs.add(o.long);
+            }
+            p = p.parent;
+        }
+        return opts.filter((o) => !o.long || !parentLongs.has(o.long));
+    }
+    /**
+     * 子命令 --help 默认会从父级继承 -v, --version；spec 只在 root 列这条。
+     * 非 root 命令把 --version 从 Global Flags 列表里过滤掉。
+     */
+    visibleGlobalOptions(cmd) {
+        const opts = super.visibleGlobalOptions(cmd);
+        if (cmd.parent) {
+            return opts.filter((o) => o.long !== "--version" && o.short !== "-v");
+        }
+        return opts;
+    }
+    /**
+     * Root 命令默认会列 commander 自动生成的 `help [command]` 子命令；
+     * spec 不展示这一条，过滤掉。
+     */
+    visibleCommands(cmd) {
+        return super.visibleCommands(cmd).filter((c) => c.name() !== "help");
+    }
+    formatHelp(cmd, helper) {
+        const isRoot = cmd.parent == null;
+        const termWidth = helper.padWidth(cmd, helper);
+        const helpWidth = helper.helpWidth ?? 80;
+        const formatItem = (term, description) => {
+            if (description) {
+                const padding = " ".repeat(Math.max(termWidth - term.length, 0) + 2);
+                return `${term}${padding}${description}`;
+            }
+            return term;
+        };
+        const formatList = (lines) => lines.map((l) => "  " + l).join("\n");
+        void helpWidth; // 保留以备后续按宽度自动 wrap，当前直接透传 description
+        const out = [];
+        // 1. 描述
+        const desc = helper.commandDescription(cmd);
+        if (desc) {
+            out.push(desc, "");
+        }
+        // 2. Usage：独立 heading + 缩进
+        out.push("Usage:", `  ${helper.commandUsage(cmd)}`, "");
+        // 3. Commands（仅父级命令组有，spec 要求 Commands 在 Flags 前）
+        //    spec 不展示 Arguments 段，参数说明放在 description 文本里
+        const subs = helper.visibleCommands(cmd).map((c) => formatItem(helper.subcommandTerm(c), helper.subcommandDescription(c)));
+        if (subs.length) {
+            out.push("Commands:", formatList(subs), "");
+        }
+        // 5. Flags（叶子命令专属 options）
+        //    - Root / 父命令组：local options 都视作"会被子命令继承的 globals"，渲染到 Global Flags 段
+        //    - 叶子命令（无子命令）：local options 渲染到 Flags 段（如 db data export 的 --format）
+        //    - `-h, --help` 永远不放 Flags 段，统一放 Global Flags（spec 约定）
+        const isParent = subs.length > 0;
+        if (!isRoot && !isParent) {
+            const opts = helper.visibleOptions(cmd)
+                .filter((o) => !isHelpOption(o))
+                .map((o) => formatItem(helper.optionTerm(o), helper.optionDescription(o)));
+            if (opts.length) {
+                out.push("Flags:", formatList(opts), "");
+            }
+        }
+        // 6. Global Flags
+        //    - Root：local options 当 globals 渲染（root 自己就是 global 来源）
+        //    - 父命令组：继承自祖先的 globals + 自己的 local options（也会被子命令继承）
+        //    - 叶子命令：继承自祖先的 globals + 当前的 -h, --help
+        //    - 末尾确保 -h, --help 一条
+        const localOpts = helper.visibleOptions(cmd);
+        let globals = [];
+        if (isRoot) {
+            globals = localOpts;
+        }
+        else if (isParent) {
+            const inherited = helper.visibleGlobalOptions(cmd);
+            const localNonHelp = localOpts.filter((o) => !isHelpOption(o));
+            const helpOpt = localOpts.find(isHelpOption);
+            globals = [...inherited, ...localNonHelp];
+            if (helpOpt && !globals.includes(helpOpt))
+                globals.push(helpOpt);
+        }
+        else if (this.showGlobalOptions) {
+            const inherited = helper.visibleGlobalOptions(cmd);
+            const helpOpt = localOpts.find(isHelpOption);
+            globals = [...inherited];
+            if (helpOpt && !globals.includes(helpOpt))
+                globals.push(helpOpt);
+        }
+        if (globals.length) {
+            const lines = globals.map((o) => formatItem(helper.optionTerm(o), helper.optionDescription(o)));
+            out.push("Global Flags:", formatList(lines), "");
+        }
+        // 7. 父命令底部追加 "Use <cmd> <subcommand> --help" 提示，对齐 spec
+        if (subs.length > 0) {
+            const path = cmd.name() === "miaoda" ? "miaoda" : commandPath(cmd);
+            out.push(`Use "${path} <command> --help" for more information about a command.`, "");
+        }
+        // 保留末尾换行：commander 用 join('\n') 拼 addHelpText('after') 段，
+        // 这里多留一个 \n，让 Notes / Examples 段与上面段落之间空一行。
+        return out.join("\n").replace(/\n+$/, "\n");
+    }
+}
+exports.MiaodaHelp = MiaodaHelp;
+/** 判断是否为 -h / --help 选项。 */
+function isHelpOption(o) {
+    return o.long === "--help" || o.short === "-h";
+}
+/** 拼接命令完整路径，例如 db schema -> "miaoda db schema"。 */
+function commandPath(cmd) {
+    const names = [];
+    let cur = cmd;
+    while (cur) {
+        names.unshift(cur.name());
+        cur = cur.parent;
+    }
+    return names.join(" ");
+}

package/dist/main.js

@@ -5,15 +5,23 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const index_1 = require("./cli/commands/index");
+const help_1 = require("./cli/help");
 const config_1 = require("./utils/config");
 const log_id_1 = require("./utils/log_id");
 const output_1 = require("./utils/output");
 const package_json_1 = __importDefault(require("../package.json"));
+// MiaodaHelp 对齐 CLI 规范（描述置顶 / Flags / Global Flags / 段顺序）：
+// 在 Command.prototype 上 patch createHelp，让所有命令实例（含动态注册的
+// 子命令）统一走 MiaodaHelp 渲染，避免在每个子命令上重复 configureHelp。
+commander_1.Command.prototype.createHelp = function () {
+    return Object.assign(new help_1.MiaodaHelp(), this.configureHelp());
+};
 const program = new commander_1.Command();
 const { version } = package_json_1.default;
 program
     .name("miaoda")
-    .description("妙搭平台命令行工具")
+    .description("妙搭平台 CLI，提供数据服务、文件存储、插件管理等命令行操作。")
+    .usage("<command> [flags]")
     .version(version, "-v, --version", "显示版本号")
     .option("--json [fields]", "JSON 输出，可选字段级选择")
     .option("--output <format>", "输出格式（pretty|json）", "pretty")

package/package.json

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