@lark-apaas/miaoda-cli 0.1.0-alpha.d98ea14 → 0.1.0-alpha.dcd5e2e

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

@@ -5,22 +5,16 @@ const index_1 = require("../../../cli/handlers/db/index");
 function registerDbCommands(program) {
     const dbCmd = program
         .command("db")
-        .description("数据库操作：执行 SQL、查看表结构、批量导入与导出数据")
+        .description("应用数据库（PostgreSQL）的命令行操作集合。")
         .usage("<command> [flags]");
     dbCmd.action(() => {
         dbCmd.outputHelp();
     });
-    dbCmd.addHelpText("after", `
-Examples:
-  $ miaoda db sql "SELECT * FROM users LIMIT 5"
-  $ miaoda db schema list
-  $ miaoda db schema get users
-  $ miaoda db data import users.csv
-  $ miaoda db data export users
-`);
     dbCmd
         .command("sql")
-        .description("执行任意 PostgreSQL 语句（DDL / DML / SELECT 等）")
+        .description("执行 SQL 语句，支持 SELECT、DML、DDL 等所有标准 PostgreSQL 操作。\n" +
+        "支持通过 stdin 读取（miaoda db sql < file.sql），多条语句以分号分隔。\n" +
+        "事务控制使用 PG 原生的 BEGIN / COMMIT / ROLLBACK 语法。")
         .usage("[query] [flags]")
         .argument("[query]", "要执行的 SQL 语句；省略时从标准输入读取")
         .option("--env <env>", "目标环境（main / dev），未指定时按应用的多环境配置自动选择")
@@ -29,9 +23,12 @@ Examples:
     })
         .addHelpText("after", `
 Notes:
-  - 单条语句影响或返回的数据行数上限为 1000；超出会被拒绝执行
-  - 多条语句以分号分隔；任一语句失败时响应中会标明失败语句的位置（statement_index）
-  - 支持手写 BEGIN / COMMIT / ROLLBACK 自定义事务边界；事务执行中报错时服务端会自动回滚
+  - SELECT 结果超过 1000 行直接报错（RESULT_SET_TOO_LARGE），不做隐式截断；需要分页请在 SQL 中加 LIMIT / OFFSET
+  - 单条语句执行时间上限 30 秒，超时返回 STATEMENT_TIMEOUT 并中断整批
+  - 多条语句不自动包事务：autocommit 模式下任一失败时，已成功的不回滚；需要原子性请显式 BEGIN; ...; COMMIT;
+  - 用户自管事务（BEGIN..COMMIT）中途报错时服务端会自动 ROLLBACK 整批
+  - --env 仅在专家模式应用且已 migration init 后可用
+  - NULL 值在 --json 中是 JSON 原生 null，pretty / 管道中是字面字符串 NULL
 
 Examples:
   $ miaoda db sql "SELECT * FROM users LIMIT 3"
@@ -51,20 +48,15 @@ Examples:
     // schema 二级资源分组
     const schemaCmd = dbCmd
         .command("schema")
-        .description("查看表结构：列出所有表、查看单张表的字段与索引")
+        .description("查看应用数据库的表结构信息。")
         .usage("<command> [flags]");
     schemaCmd.action(() => {
         schemaCmd.outputHelp();
     });
-    schemaCmd.addHelpText("after", `
-Examples:
-  $ miaoda db schema list
-  $ miaoda db schema get users
-  $ miaoda db schema get users --ddl
-`);
     schemaCmd
         .command("list")
-        .description("列出当前应用的所有表，包含行数、占用大小、列数等概要信息")
+        .description("列出当前应用所有表的概览信息：表名、描述、行数、大小、列数、最近更新时间。\n" +
+        "查看单表完整结构请用 `schema get`。")
         .usage("[flags]")
         .option("--env <env>", "目标环境（main / dev），未指定时按应用的多环境配置自动选择")
         .action(async (opts) => {
@@ -76,113 +68,127 @@ Notes:
 
 Examples:
   $ miaoda db schema list
-  name      rows  size_bytes  columns
-  users     120   65536       6
-  orders    5400  327680      9
-
-  $ miaoda db schema list --env main
+  name      description   rows   size      columns   updated_at
+  users     用户信息          1523   2.1 MB    5         3h ago
+  orders    订单记录          8891   12.4 MB   8         2d ago
+
+  $ miaoda db schema list --json name,rows
+  {
+    "data": [
+      {"name": "users", "rows": 1523},
+      {"name": "orders", "rows": 8891}
+    ],
+    "next_cursor": null,
+    "has_more": false
+  }
 `);
     schemaCmd
         .command("get")
-        .description("查看单张表的字段、索引和建表语句，也可用来检测表是否存在")
+        .description("查看指定表的完整结构：列定义（含类型、可空、默认值、注释）、索引、行数、大小。\n" +
+        "默认 pretty 输出 CREATE TABLE 的 SQL 文本；--json 输出结构化字段。")
         .usage("<table> [flags]")
         .argument("<table>", "表名（无需带 schema 前缀）")
-        .option("--ddl", "仅输出 CREATE TABLE 建表语句")
+        .option("--ddl", "强制输出 CREATE TABLE 建表语句（pretty 默认就是 DDL，--json 时配合此 flag 返 SQL 文本）")
         .option("--env <env>", "目标环境（main / dev），未指定时按应用的多环境配置自动选择")
         .action(async (table, opts) => {
         await (0, index_1.handleDbSchemaGet)(table, opts);
     })
         .addHelpText("after", `
 Notes:
-  - 检测表是否存在：成功返回（退出码 0）即为存在；错误码 TABLE_NOT_FOUND 即为不存在
+  - 也可用作"检测表是否存在"探针：成功返回（退出码 0）即存在；错误码 TABLE_NOT_FOUND 即不存在
 
 Examples:
   $ miaoda db schema get users
   CREATE TABLE users (
-    id uuid NOT NULL DEFAULT gen_random_uuid(),
-    ...
+    id uuid DEFAULT gen_random_uuid() NOT NULL,
+    name varchar(100) NOT NULL,
+    email varchar(255),
+    age integer,
+    PRIMARY KEY (id),
+    UNIQUE (email)
   );
-
-  $ miaoda db schema get users --ddl
-  CREATE TABLE users ( ... );
+  COMMENT ON TABLE users IS '用户信息';
 
   # 报错：表不存在
-  $ miaoda db schema get no_such
-  Error: TABLE_NOT_FOUND
-    hint: Run \`miaoda db schema list\` to see all tables.
+  $ 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("批量导入与导出表数据")
+        .description("表数据的批量导入导出，适合数据备份、跨环境迁移、外部分析。")
         .usage("<command> [flags]");
     dataCmd.action(() => {
         dataCmd.outputHelp();
     });
-    dataCmd.addHelpText("after", `
-Examples:
-  $ miaoda db data import users.csv
-  $ miaoda db data import data.json --table customers
-  $ miaoda db data export users
-  $ miaoda db data export users --format json
-`);
     dataCmd
         .command("import")
-        .description("将本地 CSV / JSON 文件批量导入到指定表")
+        .description("从本地 CSV / JSON 文件导入数据到表。\n" +
+        "整个导入是原子的——遇到任何错误（主键冲突、类型不匹配、列名不匹配等）\n" +
+        "会回滚已插入的所有行。\n" +
+        "不支持 SQL 文件，SQL 备份请用 `miaoda db sql < <文件>.sql` 回放。")
         .usage("<file> [flags]")
         .argument("<file>", "本地文件路径（CSV 或 JSON 格式）")
-        .option("--table <name>", "目标表名；未指定时按文件名（不含扩展名）推断")
+        .option("--table <name>", "目标表名；未指定时按文件名（不含扩展名）推断（如 users.csv → users）")
         .option("--format <fmt>", "文件格式 csv / json；未指定时按文件扩展名推断")
         .action(async (file, opts) => {
         await (0, index_1.handleDbDataImport)(file, opts);
     })
         .addHelpText("after", `
 Notes:
-  - CSV 文件首行需为列名表头，与目标表字段名一一对应
-  - JSON 文件需为对象数组，每个对象的 key 与目标表字段名一一对应
+  - 目标表必须已存在；CSV 表头 / JSON 顶层 key 必须与表字段名完全一致
+  - 导入为原子操作：遇到错误回滚所有已插入行，不会出现部分导入的中间状态
   - 单次最多 5000 行 / 1 MB；超出请分批导入
-  - 整批原子写入：任意一行失败时全部回滚，响应中包含失败行号和原因
+  - 仅支持 .csv / .json 文件扩展名
 
 Examples:
   $ miaoda db data import users.csv
-  ✓ Imported 120 rows into 'users'
+  ✓ Imported users.csv → table 'users' (1523 rows)
 
-  $ miaoda db data import data.json --table customers
-  ✓ Imported 240 rows into 'customers'
+  $ miaoda db data import data.csv --table users
+  ✓ Imported data.csv → table 'users' (1523 rows)
 
-  $ miaoda db data import dump --table orders --format csv
-  ✓ Imported 80 rows into 'orders'
+  # 报错：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.
 
-  # 报错：第 5 行格式错误，整批回滚
-  $ miaoda db data import broken.csv
-  Error: ROW_PARSE_FAILED at row 5
-    hint: Check column count and value types match the table schema.
+  # 报错：主键冲突（已回滚）
+  $ 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 文件")
+        .description("把指定表的数据导出到本地文件，支持 CSV / JSON / SQL 三种格式。")
         .usage("<table> [flags]")
         .argument("<table>", "表名（无需带 schema 前缀）")
-        .option("--format <fmt>", "导出格式 csv / json，默认 csv")
-        .option("-f, --file <path>", "输出文件路径，默认 <table>.<format>")
+        .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);
     })
         .addHelpText("after", `
 Notes:
+  - SQL 格式生成 INSERT 语句，可用 \`miaoda db sql < <文件>.sql\` 在其他环境回放
   - 单次最多导出 5000 行 / 1 MB；超出请使用 --limit 控制或分批导出
   - 按表的物理存储顺序导出，无固定排序；如需固定顺序，请改用 miaoda db sql 加 ORDER BY 自行写出文件
 
 Examples:
   $ miaoda db data export users
-  ✓ Exported 120 rows to ./users.csv
+  ✓ Exported users → users.csv (1523 rows)
 
   $ miaoda db data export users --format json
-  ✓ Exported 120 rows to ./users.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 /tmp/u.csv --limit 1000
-  ✓ Exported 1000 rows to /tmp/u.csv
+  $ miaoda db data export users -f ~/Desktop/users.csv
+  ✓ Exported users → ~/Desktop/users.csv (1523 rows)
 
   # 报错：表不存在
   $ miaoda db data export no_such

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

@@ -19,23 +19,16 @@ function parsePositiveInt(raw) {
 function registerFileCommands(program) {
     const fileCmd = program
         .command("file")
-        .description("文件操作:上传、下载、删除、查询")
+        .description("应用文件存储（TOS）的命令行操作集合。操作对象是 UGC 资源（用户上传的文件、应用运行时\n" +
+        "生成的报表 / 导出文件等），不涉及代码仓库里的本地文件。")
         .usage("<command> [flags]");
     fileCmd.action(() => {
         fileCmd.outputHelp();
     });
-    fileCmd.addHelpText("after", `
-Examples:
-  $ miaoda file ls
-  $ miaoda file stat report.pdf
-  $ miaoda file cp report.pdf /uploads/
-  $ miaoda file cp /uploads/report.pdf .
-  $ miaoda file sign report.pdf
-  $ miaoda file rm a.txt b.txt -y
-`);
     fileCmd
         .command("ls")
-        .description("列出应用下的文件，可按名称、路径、MIME 类型、大小、上传时间筛选")
+        .description("列出当前应用存储里的文件，支持按文件名、大小、上传时间筛选，以及游标分页。\n" +
+        "默认 pretty 输出省略 download_url（列宽限制），需获取请用 --json。")
         .usage("[query] [flags]")
         .argument("[query]", "筛选值：以 / 开头视为路径精确匹配，否则按文件名精确匹配")
         .option("--path <path>", "按路径精确匹配")
@@ -69,7 +62,8 @@ Examples:
 `);
     fileCmd
         .command("stat")
-        .description("查看文件元数据；获取下载链接请使用 miaoda file sign")
+        .description("查看单文件完整元数据，含 download_url（应用内消费）。\n" +
+        "需要公网可访问的临时链接请用 `file sign` 生成 signed_url。")
         .usage("<file> [flags]")
         .argument("<file>", "文件的路径或文件名（自动识别）")
         .action(async (file, opts) => {
@@ -95,7 +89,9 @@ Examples:
 `);
     fileCmd
         .command("cp")
-        .description("上传或下载文件，根据源和目标自动判断方向")
+        .description("上传或下载文件，方向由 src/dst 路径前缀自动判断：\n" +
+        "  / 开头           → 远程 TOS 路径\n" +
+        "  ./、~/、裸文件名  → 本地路径")
         .usage("<src> <dst> [flags]")
         .argument("<src>", "源：本地文件路径或远程文件路径 / 文件名")
         .argument("<dst>", "目标：本地路径或远程路径")
@@ -105,8 +101,10 @@ Examples:
     })
         .addHelpText("after", `
 Notes:
-  - 源是本地存在的文件时，执行上传
-  - 源不是本地文件、目标是本地路径时，执行下载
+  - 单文件上限 100 MB，超过请拆分或用 web console 上传
+  - 同目录下允许同 file_name 并存（每次上传生成新的 path），不会因重名失败
+  - 下载时 src 必须是完整 path（裸 file_name 会被识别为本地路径）
+  - 上传成功返回 download_url，可写入数据库 / 应用代码作为永久引用
 
 Examples:
   $ miaoda file cp ./report.pdf /uploads/
@@ -125,7 +123,8 @@ Examples:
 `);
     fileCmd
         .command("rm")
-        .description("批量删除文件，单条失败不影响其他文件")
+        .description("删除一个或多个文件。<file> 可传 path（推荐）或 file_name，可混用。\n" +
+        "操作不可撤销（不进回收站），TTY 下默认会要求二次确认。")
         .usage("[paths...] [flags]")
         .argument("[paths...]", "要删除的文件，每项可填路径或文件名（自动识别）")
         .option("-n, --name <name>", "按文件名删除（可重复指定）", (value, prev) => [...(prev ?? []), value])
@@ -135,9 +134,10 @@ Examples:
     })
         .addHelpText("after", `
 Notes:
-  - 删除后无法恢复，请确认目标文件正确再执行
+  - 删除不可撤销，没有回收站；请确认目标文件正确再执行
   - 单次最多 100 个；超出请分批删除
-  - 单条失败不会影响整体执行；响应中会列出每条文件的成功 / 失败状态
+  - 批量场景下失败项不影响其他项；全部成功退出码 0，任意一项失败退出码 1
+  - --json 输出每项保留输入顺序，含 status: "ok" | "error" 字段
 
 Examples:
   $ miaoda file rm /uploads/a.pdf /uploads/b.pdf -y
@@ -151,25 +151,27 @@ Examples:
 `);
     fileCmd
         .command("sign")
-        .description("为文件生成可分享的临时下载链接")
+        .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:
-  - 链接生成后立即生效
-  - 有效期最长 30 天，超过会被拒绝；不传 --expires 默认 7 天
-  - 链接持有者即可下载文件，请仅分享给信任的对象
+  - <file> 可传 path（推荐）或 file_name；重名报 AMBIGUOUS_FILE_NAME
+  - signed_url 会过期，不要持久化到数据库；永久引用请用 download_url
+  - 链接生成后立即生效；不传 --expires 默认 1 天，最长 30 天
 
 Examples:
   $ miaoda file sign report.pdf
-  https://...?expires=...    (valid 7d)
+  https://...?expires=...    (valid 1d)
 
   $ miaoda file sign report.pdf --expires 30m
-  $ miaoda file sign report.pdf --expires 24h
+  $ miaoda file sign report.pdf --expires 7d
 
   # 报错：文件不存在
   $ miaoda file sign no_such.pdf

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/help.js

@@ -8,7 +8,11 @@ const commander_1 = require("commander");
  *   1. 描述放在最前（commander 默认是 Usage 在前、描述在后）
  *   2. "Options:" 重命名为 "Flags:"，"Global Options:" 重命名为 "Global Flags:"
  *   3. Usage 段独占一行 Heading + 缩进展示 usage 行
- *   4. 段落顺序：描述 → Usage → Arguments → Flags → Global Flags → Commands → addHelpText('after')
+ *   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', ...) 自行追加，
  * 本类不直接生成 —— 框架与文案分层。
@@ -17,11 +21,11 @@ class MiaodaHelp extends commander_1.Help {
     // 全局默认开启：所有子命令 --help 都展示 Global Flags 段
     showGlobalOptions = true;
     /**
-     * 父级 --help 的 Commands 列表里展示子命令调用形态。规范要求 "<args> [flags]"
-     * 顺序，但 commander 默认 subcommandTerm 是 "name [options] <args>"。
+     * 父级 --help 的 Commands 列表里展示子命令调用形态。spec 要求只展示
+     * `name <args>` 不带 `[flags]` 尾巴：
      *
-     *   - 子命令是分组（含下级 subcommand）→ 只显示 name，不带 args/flags
-     *   - 子命令是 leaf 且配置了 usage()  → "name <usage>"，对齐 args 在前 / flags 在后
+     *   - 子命令是分组（含下级 subcommand）→ 只显示 name
+     *   - 子命令是 leaf 且配置了 usage()  → "name <args>"（usage 末尾的 [flags] 去掉）
      *   - leaf 没配置 usage              → 退回 commander 默认行为
      */
     subcommandTerm(cmd) {
@@ -30,11 +34,41 @@ class MiaodaHelp extends commander_1.Help {
         }
         const usage = cmd.usage();
         if (usage) {
-            return `${cmd.name()} ${usage}`.trim();
+            // 去掉末尾的 [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 列表里只展示子命令描述的首行，避免多行 description
+     * 把列表撑乱。叶子命令自身 --help 仍展示完整 description。
+     */
+    subcommandDescription(cmd) {
+        const desc = super.subcommandDescription(cmd);
+        const idx = desc.indexOf("\n");
+        return idx === -1 ? desc : desc.slice(0, idx);
+    }
+    /**
+     * 子命令 --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) => {
@@ -54,31 +88,58 @@ class MiaodaHelp extends commander_1.Help {
         }
         // 2. Usage：独立 heading + 缩进
         out.push("Usage:", `  ${helper.commandUsage(cmd)}`, "");
-        // 3. Arguments
+        // 3. Arguments（仅 leaf 有）
         const args = helper.visibleArguments(cmd).map((a) => formatItem(helper.argumentTerm(a), helper.argumentDescription(a)));
         if (args.length) {
             out.push("Arguments:", formatList(args), "");
         }
-        // 4. Flags（原 Options）
-        const opts = helper.visibleOptions(cmd).map((o) => formatItem(helper.optionTerm(o), helper.optionDescription(o)));
-        if (opts.length) {
-            out.push("Flags:", formatList(opts), "");
-        }
-        // 5. Global Flags（原 Global Options，showGlobalOptions=true 时启用）
-        if (this.showGlobalOptions) {
-            const globals = helper.visibleGlobalOptions(cmd).map((o) => formatItem(helper.optionTerm(o), helper.optionDescription(o)));
-            if (globals.length) {
-                out.push("Global Flags:", formatList(globals), "");
-            }
-        }
-        // 6. Commands（仅父级命令组有）
+        // 4. Commands（仅父级命令组有，spec 要求 Commands 在 Flags 前）
         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 没有 command-specific flag（--json / --output / --verbose / -h / --version
+        //      在 spec 里都属于 Global Flags），统一渲染到下一段
+        //    - 非 root 命令的 local options 渲染为 Flags（如 db sql 的 --env、db data export 的 --format 等）
+        if (!isRoot) {
+            const opts = helper.visibleOptions(cmd).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：commander 的 visibleGlobalOptions（已在上面 override 过滤掉 --version）
+        let globals = [];
+        if (isRoot) {
+            globals = helper.visibleOptions(cmd);
+        }
+        else if (this.showGlobalOptions) {
+            globals = helper.visibleGlobalOptions(cmd);
+        }
+        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 段与 Flags / Global Flags 段之间空一行。
+        // 这里多留一个 \n，让 Notes / Examples 段与上面段落之间空一行。
         return out.join("\n").replace(/\n+$/, "\n");
     }
 }
 exports.MiaodaHelp = MiaodaHelp;
+/** 拼接命令完整路径，例如 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

@@ -20,7 +20,7 @@ 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 输出，可选字段级选择")

package/package.json

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