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

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/cli/commands/db/index.js

@@ -5,65 +5,197 @@ const index_1 = require("../../../cli/handlers/db/index");
 function registerDbCommands(program) {
     const dbCmd = program
         .command("db")
-        .description("数据库操作：执行 SQL、查看表结构、导入导出数据");
+        .description("数据库操作：执行 SQL、查看表结构、批量导入与导出数据")
+        .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("执行 SQL 语句")
-        .argument("[query]", "要执行的 SQL 语句")
-        .option("--env <env>", "目标环境（main / dev）")
+        .description("执行任意 PostgreSQL 语句（DDL / DML / SELECT 等）")
+        .usage("[query] [flags]")
+        .argument("[query]", "要执行的 SQL 语句；省略时从标准输入读取")
+        .option("--env <env>", "目标环境（main / dev），未指定时按应用的多环境配置自动选择")
         .action(async (query, opts) => {
         await (0, index_1.handleDbSql)(query, opts);
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - 单条语句影响或返回的数据行数上限为 1000；超出会被拒绝执行
+  - 多条语句以分号分隔；任一语句失败时响应中会标明失败语句的位置（statement_index）
+  - 支持手写 BEGIN / COMMIT / ROLLBACK 自定义事务边界；事务执行中报错时服务端会自动回滚
+
+Examples:
+  $ miaoda db sql "SELECT * FROM users LIMIT 3"
+  ✓ 3 rows
+
+  $ miaoda db sql "CREATE TABLE t(id int)"
+  ✓ Statement executed
+
+  $ cat migration.sql | miaoda db sql
+  ✓ 5 statements executed
+
+  $ miaoda db sql "SELECT count(*) FROM orders" --json
+  [{"count": 1234}]
+
+  # 报错：多语句中第 1 条失败
+  $ miaoda db sql "CREATE TABLE t(id int); SELECT * FROM no_such"
+  Error: TABLE_NOT_FOUND at statement 1
+    hint: Run \`miaoda db schema list\` to see existing tables.
+`);
     // 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
+  $ miaoda db schema get users --json
+`);
     schemaCmd
         .command("list")
-        .description("列出当前应用的所有表（含行数估算、占用大小、列数）")
-        .option("--env <env>", "目标环境（main / dev）")
+        .description("列出当前应用的所有表，包含行数、占用大小、列数等概要信息")
+        .usage("[flags]")
+        .option("--env <env>", "目标环境（main / dev），未指定时按应用的多环境配置自动选择")
         .action(async (opts) => {
         await (0, index_1.handleDbSchemaList)(opts);
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - rows 与 size_bytes 由 PostgreSQL 统计信息估算得出，与实际值可能存在偏差
+
+Examples:
+  $ miaoda db schema list
+  name      rows  size_bytes  columns
+  users     120   65536       6
+  orders    5400  327680      9
+
+  $ miaoda db schema list --json | jq '.[].name'
+  "users"
+  "orders"
+
+  $ miaoda db schema list --env main
+`);
     schemaCmd
         .command("get")
-        .description("查看单张表的字段、索引与建表语句")
-        .argument("<table>", "表名")
-        .option("--ddl", "输出完整建表语句而非概要")
-        .option("--env <env>", "目标环境（main / dev）")
+        .description("查看单张表的字段、索引和建表语句，也可用来检测表是否存在")
+        .usage("<table> [flags]")
+        .argument("<table>", "表名（无需带 schema 前缀）")
+        .option("--ddl", "仅输出 CREATE TABLE 建表语句")
+        .option("--env <env>", "目标环境（main / dev），未指定时按应用的多环境配置自动选择")
         .action(async (table, opts) => {
         await (0, index_1.handleDbSchemaGet)(table, opts);
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - 检测表是否存在：成功返回（退出码 0）即为存在；错误码 TABLE_NOT_FOUND 即为不存在
+
+Examples:
+  $ miaoda db schema get users
+  CREATE TABLE users (
+    id uuid NOT NULL DEFAULT gen_random_uuid(),
+    ...
+  );
+
+  $ miaoda db schema get users --ddl
+  CREATE TABLE users ( ... );
+
+  $ miaoda db schema get users --json
+  {"name":"users","columns":[...],"indexes":[...]}
+
+  # 报错：表不存在
+  $ miaoda db schema get no_such
+  Error: TABLE_NOT_FOUND
+    hint: 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 文件导入到表（单次最多 5000 行 / 1 MB，全部成功或全部回滚）")
-        .argument("<file>", "本地文件路径")
-        .option("--table <name>", "目标表名（缺省按文件名推断）")
-        .option("--format <fmt>", "文件格式 csv / json（缺省按扩展名推断）")
+        .description("将本地 CSV / JSON 文件批量导入到指定表")
+        .usage("<file> [flags]")
+        .argument("<file>", "本地文件路径（CSV 或 JSON 格式）")
+        .option("--table <name>", "目标表名；未指定时按文件名（不含扩展名）推断")
+        .option("--format <fmt>", "文件格式 csv / json；未指定时按文件扩展名推断")
         .action(async (file, opts) => {
         await (0, index_1.handleDbDataImport)(file, opts);
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - CSV 文件首行需为列名表头，与目标表字段名一一对应
+  - JSON 文件需为对象数组，每个对象的 key 与目标表字段名一一对应
+  - 单次最多 5000 行 / 1 MB；超出请分批导入
+  - 整批原子写入：任意一行失败时全部回滚，响应中包含失败行号和原因
+
+Examples:
+  $ miaoda db data import users.csv
+  ✓ Imported 120 rows into 'users'
+
+  $ miaoda db data import data.json --table customers
+  ✓ Imported 240 rows into 'customers'
+
+  $ miaoda db data import dump --table orders --format csv
+  ✓ Imported 80 rows into 'orders'
+
+  # 报错：第 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.
+`);
     dataCmd
         .command("export")
-        .description("把整张表导出为 CSV / JSON 文件（单次最多 5000 行 / 1 MB）")
-        .argument("<table>", "表名")
-        .option("--format <fmt>", "导出格式 csv / json（默认 csv）")
-        .option("-f, --file <path>", "输出文件路径（默认 <table>.<format>）")
+        .description("将指定表的数据导出为 CSV / JSON 文件")
+        .usage("<table> [flags]")
+        .argument("<table>", "表名（无需带 schema 前缀）")
+        .option("--format <fmt>", "导出格式 csv / json，默认 csv")
+        .option("-f, --file <path>", "输出文件路径，默认 <table>.<format>")
         .option("--limit <n>", "最多导出行数（不超过 5000）")
         .action(async (table, opts) => {
         await (0, index_1.handleDbDataExport)(table, opts);
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - 单次最多导出 5000 行 / 1 MB；超出请使用 --limit 控制或分批导出
+  - 按表的物理存储顺序导出，无固定排序；如需固定顺序，请改用 miaoda db sql 加 ORDER BY 自行写出文件
+
+Examples:
+  $ miaoda db data export users
+  ✓ Exported 120 rows to ./users.csv
+
+  $ miaoda db data export users --format json
+  ✓ Exported 120 rows to ./users.json
+
+  $ miaoda db data export users -f /tmp/u.csv
+  ✓ Exported 120 rows to /tmp/u.csv
+
+  $ miaoda db data export users --limit 1000
+  ✓ Exported 1000 rows to ./users.csv
+`);
 }

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

@@ -19,57 +19,159 @@ function parsePositiveInt(raw) {
 function registerFileCommands(program) {
     const fileCmd = program
         .command("file")
-        .description("文件操作:上传、下载、删除、查询");
+        .description("文件操作:上传、下载、删除、查询")
+        .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("列出应用下的文件")
-        .argument("[query]", "可选筛选值：以 / 开头视为路径（精确匹配），否则按文件名匹配")
+        .description("列出应用下的文件，可按名称、路径、MIME 类型、大小、上传时间筛选")
+        .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>", "上传时间下限（ISO 8601 格式）")
+        .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", `
+Notes:
+  - 默认按上传时间倒序展示
+  - --all 会自动翻页拉取全部结果，文件较多时耗时较长，建议先用筛选条件缩小范围
+
+Examples:
+  $ miaoda file ls
+  path                       size      uploaded_at
+  /uploads/report.pdf        1.2 MB    2026-04-20 10:00
+  /uploads/photo.png         800 KB    2026-04-21 14:30
+
+  $ miaoda file ls report.pdf
+  $ miaoda file ls /uploads/report.pdf
+  $ miaoda file ls --type image/png --size-gt 1MB
+  $ miaoda file ls --uploaded-since 2026-04-01
+
+  $ miaoda file ls --all --json | jq '.[].name'
+  "report.pdf"
+  "photo.png"
+`);
     fileCmd
         .command("stat")
-        .description("查看文件的元数据（不含下载链接，需要链接请用 sign）")
-        .argument("<file>", "文件的路径或文件名")
+        .description("查看文件元数据；获取下载链接请使用 miaoda file sign")
+        .usage("<file> [flags]")
+        .argument("<file>", "文件的路径或文件名（自动识别）")
         .action(async (file, opts) => {
         await (0, index_1.handleFileStat)(file, opts);
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - 仅返回元数据，不包含下载链接；如需分享或下载请使用 miaoda file sign 生成临时链接
+
+Examples:
+  $ miaoda file stat report.pdf
+  path:        /uploads/report.pdf
+  size:        1.2 MB
+  type:        application/pdf
+  uploaded_at: 2026-04-20 10:00
+
+  $ miaoda file stat /uploads/report.pdf
+  $ miaoda file stat report.pdf --json
+  {"path":"/uploads/report.pdf","size":1258291,...}
+
+  # 报错：文件不存在
+  $ miaoda file stat no_such.pdf
+  Error: FILE_NOT_FOUND
+    hint: Run \`miaoda file ls\` to see available files.
+`);
     fileCmd
         .command("cp")
-        .description("上传或下载文件（按 src/dst 自动判断方向）")
-        .argument("<src>", "源：本地文件路径 或 远程文件路径/名")
-        .argument("<dst>", "目标：本地路径 或 远程路径")
+        .description("上传或下载文件，根据源和目标自动判断方向")
+        .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:
+  - 源是本地存在的文件时，执行上传
+  - 源不是本地文件、目标是本地路径时，执行下载
+
+Examples:
+  $ miaoda file cp ./report.pdf /uploads/
+  ✓ Uploaded report.pdf → /uploads/report.pdf
+
+  $ miaoda file cp ./report.pdf /uploads/ --rename r.pdf
+  ✓ Uploaded report.pdf → /uploads/r.pdf
+
+  $ miaoda file cp /uploads/report.pdf .
+  ✓ Downloaded /uploads/report.pdf → ./report.pdf
+
+  $ miaoda file cp /uploads/report.pdf ./local.pdf
+  ✓ Downloaded /uploads/report.pdf → ./local.pdf
+`);
     fileCmd
         .command("rm")
-        .description("批量删除文件（单次最多 100 个，部分失败不影响其他）")
+        .description("批量删除文件，单条失败不影响其他文件")
+        .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:
+  - 删除后无法恢复，请确认目标文件正确再执行
+  - 单次最多 100 个；超出请分批删除
+  - 单条失败不会影响整体执行；响应中会列出每条文件的成功 / 失败状态
+
+Examples:
+  $ miaoda file rm /uploads/a.pdf /uploads/b.pdf -y
+  ✓ Deleted 2 files
+
+  $ miaoda file rm a.pdf b.pdf -y
+  ✓ Deleted 2 files
+
+  $ miaoda file rm -n a.pdf -n b.pdf -y
+  ✓ Deleted 2 files
+`);
     fileCmd
         .command("sign")
-        .description("生成可分享的临时下载链接")
+        .description("为文件生成可分享的临时下载链接")
+        .usage("<file> [flags]")
         .argument("<file>", "文件的路径或文件名")
-        .option("--expires <duration>", "链接有效期，支持 30m / 24h / 7d 单位（默认 7d，最长 30d）")
+        .option("--expires <duration>", "链接有效期，支持 30m / 24h / 7d 等单位（默认 7d，最长 30d）")
         .action(async (file, opts) => {
         await (0, index_1.handleFileSign)(file, opts);
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - 链接生成后立即生效
+  - 有效期最长 30 天，超过会被拒绝；不传 --expires 默认 7 天
+  - 链接持有者即可下载文件，请仅分享给信任的对象
+
+Examples:
+  $ miaoda file sign report.pdf
+  https://...?expires=...    (valid 7d)
+
+  $ miaoda file sign report.pdf --expires 30m
+  $ miaoda file sign report.pdf --expires 24h
+`);
 }

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

@@ -0,0 +1,84 @@
+"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 → Flags → Global Flags → Commands → addHelpText('after')
+ *
+ * Notes / Examples 段由各命令通过 addHelpText('after', ...) 自行追加，
+ * 本类不直接生成 —— 框架与文案分层。
+ */
+class MiaodaHelp extends commander_1.Help {
+    // 全局默认开启：所有子命令 --help 都展示 Global Flags 段
+    showGlobalOptions = true;
+    /**
+     * 父级 --help 的 Commands 列表里展示子命令调用形态。规范要求 "<args> [flags]"
+     * 顺序，但 commander 默认 subcommandTerm 是 "name [options] <args>"。
+     *
+     *   - 子命令是分组（含下级 subcommand）→ 只显示 name，不带 args/flags
+     *   - 子命令是 leaf 且配置了 usage()  → "name <usage>"，对齐 args 在前 / flags 在后
+     *   - leaf 没配置 usage              → 退回 commander 默认行为
+     */
+    subcommandTerm(cmd) {
+        if (cmd.commands.length > 0) {
+            return cmd.name();
+        }
+        const usage = cmd.usage();
+        if (usage) {
+            return `${cmd.name()} ${usage}`.trim();
+        }
+        return super.subcommandTerm(cmd);
+    }
+    formatHelp(cmd, helper) {
+        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. Arguments
+        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（仅父级命令组有）
+        const subs = helper.visibleCommands(cmd).map((c) => formatItem(helper.subcommandTerm(c), helper.subcommandDescription(c)));
+        if (subs.length) {
+            out.push("Commands:", formatList(subs), "");
+        }
+        // 保留末尾换行：commander 用 join('\n') 拼 addHelpText('after') 段，
+        // 这里多留一个 \n，让 Notes / Examples 段与 Flags / Global Flags 段之间空一行。
+        return out.join("\n").replace(/\n+$/, "\n");
+    }
+}
+exports.MiaodaHelp = MiaodaHelp;

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("妙搭平台命令行工具")
+    .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.fccd72b",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {