@lark-apaas/miaoda-cli 0.1.0-alpha.08508f4 → 0.1.0-alpha.0d863af

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,174 @@ 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("执行 SQL 语句（DDL/DML/SELECT 任意 PG 语句）")
+        .usage("[query] [flags]")
+        .argument("[query]", "SQL 语句；省略时从 stdin 读取")
+        .option("--env <env>", "目标环境（main / dev），缺省按多环境状态兜底")
         .action(async (query, opts) => {
         await (0, index_1.handleDbSql)(query, opts);
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - DML 单语句 affectedRows 与 SELECT 单语句返回行数上限均为 1000，超过即拒绝
+  - 多语句以 ; 分隔，失败时错误响应携带 statement_index 定位失败位置
+  - 支持用户自管事务 BEGIN / COMMIT / ROLLBACK；事务中途失败服务端会自动 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("查看表结构（list / get）")
+        .usage("<command> [flags]");
     schemaCmd.action(() => {
         schemaCmd.outputHelp();
     });
     schemaCmd
         .command("list")
         .description("列出当前应用的所有表（含行数估算、占用大小、列数）")
-        .option("--env <env>", "目标环境（main / dev）")
+        .usage("[flags]")
+        .option("--env <env>", "目标环境（main / dev），缺省按多环境状态兜底")
         .action(async (opts) => {
         await (0, index_1.handleDbSchemaList)(opts);
-    });
+    })
+        .addHelpText("after", `
+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("批量导入与导出数据（import / export）")
+        .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（缺省按扩展名推断）")
+        .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:
+  - 单次最多 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>）")
+        .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", `
+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,13 +19,24 @@ 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("列出应用下的文件")
+        .description("列出应用下的文件，支持名称 / 路径 / MIME / 大小 / 时间多维筛选")
+        .usage("[query] [flags]")
         .argument("[query]", "可选筛选值：以 / 开头视为路径（精确匹配），否则按文件名匹配")
         .option("--path <path>", "按路径精确匹配")
         .option("--name <name>", "按文件名精确匹配")
@@ -38,38 +49,116 @@ function registerFileCommands(program) {
         .option("--all", "自动翻页返回全部结果")
         .action(async (query, opts) => {
         await (0, index_1.handleFileLs)({ ...opts, query });
-    });
+    })
+        .addHelpText("after", `
+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("查看文件元数据（不含下载链接，需要链接用 sign）")
+        .usage("<file> [flags]")
+        .argument("<file>", "文件的路径或文件名（自动识别）")
         .action(async (file, opts) => {
         await (0, index_1.handleFileStat)(file, opts);
-    });
+    })
+        .addHelpText("after", `
+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 自动判断方向）")
+        .description("上传或下载文件，按 src/dst 自动判断方向")
+        .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:
+  - src 是本地存在的文件 → 上传
+  - src 不是本地文件而 dst 看起来是本地路径 → 下载
+
+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 个，部分失败不影响其他）")
+        .usage("[paths...] [flags]")
         .argument("[paths...]", "要删除的文件，每项可填路径或文件名（自动识别）")
-        .option("-n, --name <name>", "按文件名删除（可多次指定）", (value, prev) => [...(prev ?? []), value])
+        .option("-n, --name <name>", "按文件名删除（可重复指定）", (value, prev) => [...(prev ?? []), value])
         .option("-y, --yes", "跳过交互确认（脚本 / agent 调用必加）")
         .action(async (paths, opts) => {
         await (0, index_1.handleFileRm)(paths, opts);
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - 单次最多 100 个；超过请拆批
+  - 部分失败响应里会列出每条 success / failed 状态，整批仍 exit 0
+
+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("生成可分享的临时下载链接")
+        .usage("<file> [flags]")
         .argument("<file>", "文件的路径或文件名")
         .option("--expires <duration>", "链接有效期，支持 30m / 24h / 7d 单位（默认 7d，最长 30d）")
         .action(async (file, opts) => {
         await (0, index_1.handleFileSign)(file, opts);
-    });
+    })
+        .addHelpText("after", `
+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/dist/utils/http.js

@@ -12,7 +12,7 @@ let runtimeClient;
 /**
  * 获取单例 HttpClient（默认：管理端 innerapi）。
  *
- * 管理端链路仅适用于妙搭开发态——baseURL 从 `MIAODA_DEV_INNER_DOMAIN` 读取，
+ * 管理端链路仅适用于妙搭开发态——baseURL 从 `MIAODA_DEV_INNER_DOMAIN_WITH_PREFIX` 读取，
  * 每次请求自动从 `MIAODA_AUTHN_CODE` 读取用户凭证并注入 `X-Miaoda-Client-Token`。
  * AK/SK 的 `Authorization` / `x-api-key` 照旧叠加。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.0-alpha.08508f4",
+  "version": "0.1.0-alpha.0d863af",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {
@@ -25,7 +25,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@lark-apaas/http-client": "^0.1.4",
+    "@lark-apaas/http-client": "^0.1.5",
     "commander": "^13.1.0"
   },
   "devDependencies": {