@lark-apaas/miaoda-cli 0.1.2-alpha.dd636c5 → 0.1.2-alpha.fb3be7a

package/README.md

@@ -14,22 +14,22 @@ pnpm add -g @lark-apaas/miaoda-cli
 # 设置默认应用（需要应用上下文的命令可用 --app-id 覆盖）
 export MIAODA_APP_ID=app_demo_xxx
 
-# 插件管理
-miaoda plugin list-packages
-miaoda plugin install @demo/example-plugin
+# 文件操作
+miaoda file ls
+miaoda file upload ./local/path
 ```
 
 JSON 结构化输出（Agent 推荐）：
 
 ```bash
 # 输出全部字段
-miaoda plugin list --json
+miaoda file ls --json
 
 # 可选字段级选择
-miaoda plugin list --json id,name
+miaoda file ls --json id,name
 
 # 或通过 --output 指定格式
-miaoda plugin list --output json
+miaoda file ls --output json
 ```
 
 ## 命令树
@@ -38,7 +38,8 @@ miaoda plugin list --output json
 
 | 域 | 用途 |
 |---|---|
-| `miaoda plugin ...` | 插件管理：安装、更新、移除、插件实例查询 |
+| `miaoda file ...` | 文件操作：上传、下载、元数据、签名下载、批量删除 |
+| `miaoda db ...` | 数据操作：SQL 执行、表结构查询、数据导入导出 |
 
 完整命令通过 `miaoda --help` 或 `miaoda <domain> --help` 查看。
 

package/dist/api/deploy/schemas.js

@@ -15,6 +15,8 @@ const NODE_STATUS_TEXT = {
     [types_1.NodeStatus.HOLD_ON]: "hold_on",
 };
 function nodeStatusText(v) {
+    if (typeof v === "string")
+        return v;
     if (typeof v !== "number")
         return undefined;
     return NODE_STATUS_TEXT[v];
@@ -97,7 +99,7 @@ exports.errorJobSchema = {
     columns: [
         { key: "jobID", label: "job-id" },
         { key: "componentName", label: "component" },
-        { key: "errorMsg", label: "error", format: output_1.fmt.truncate(120) },
+        { key: "errorMsg", label: "error" },
     ],
     strict: true,
 };

package/dist/api/observability/schemas.js

@@ -6,7 +6,28 @@ const output_1 = require("../../utils/output");
 exports.logItemSchema = {
     columns: [
         { key: "timestampNs", label: "time", format: output_1.fmt.ns("yyyy-MM-dd HH:mm:ss.SSS") },
-        { key: "severityText", label: "level" },
+        {
+            key: "module",
+            derive: (row) => {
+                return row.attributes?.module;
+            },
+        },
+        {
+            key: "user-id",
+            derive: (row) => {
+                return row.attributes?.user_id;
+            },
+        },
+        { key: "severityText", label: "severity-text" },
+        {
+            key: "duration",
+            format: output_1.fmt.durationMs(),
+            derive: (row) => {
+                return row.attributes?.duration_ms;
+            },
+        },
+        { key: "traceID", label: "trace-id" },
+        { key: "id", label: "log-id" },
         { key: "body" },
     ],
     strict: true,

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

@@ -32,7 +32,7 @@ JSON 输出
     cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
         (0, shared_1.rejectCliOverride)(cmd, "appId");
         await (0, index_1.handleAppGet)({
-            appId: rawOpts.appId,
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
         });
     }));
 }
@@ -45,7 +45,7 @@ function registerAppUpdate(parent) {
         .option("--description <desc>", "新应用描述")
         .addHelpText("after", `
 JSON 输出
-  与 'app get' 一致：{"data": {...新 meta...}, "next_cursor": null, "has_more": false}
+  与 'app get' 一致：{"data": {...新 meta...}}
 
 示例
   $ miaoda app update --name my-store
@@ -54,7 +54,7 @@ JSON 输出
     cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
         (0, shared_1.rejectCliOverride)(cmd, "appId");
         await (0, index_1.handleAppUpdate)({
-            appId: rawOpts.appId,
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
             name: rawOpts.name,
             description: rawOpts.description,
         });

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerDbCommands = registerDbCommands;
 const index_1 = require("../../../cli/handlers/db/index");
+const shared_1 = require("../../../cli/commands/shared");
 function registerDbCommands(program) {
     const dbCmd = program
         .command("db")
@@ -22,7 +23,7 @@ function registerDbCommands(program) {
         .usage("<query> [flags]")
         .argument("[query]", "要执行的 SQL 语句；省略时从标准输入读取")
         .action(async function (query) {
-        await (0, index_1.handleDbSql)(query, this.optsWithGlobals());
+        await (0, index_1.handleDbSql)(query, { ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
     })
         .addHelpText("after", `
 Notes:
@@ -73,7 +74,7 @@ Examples:
         "查看单表完整结构请用 `schema get`；查看 DDL 变更历史请用 `changelog`（P1）。")
         .usage("[flags]")
         .action(async function () {
-        await (0, index_1.handleDbSchemaList)(this.optsWithGlobals());
+        await (0, index_1.handleDbSchemaList)({ ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
     })
         .addHelpText("after", `
 Examples:
@@ -103,7 +104,7 @@ Examples:
         .argument("<table>", "表名（无需带 schema 前缀）")
         .option("--ddl", "强制输出 CREATE TABLE 建表语句（pretty 默认就是 DDL，--json 时配合此 flag 返 SQL 文本）")
         .action(async function (table) {
-        await (0, index_1.handleDbSchemaGet)(table, this.optsWithGlobals());
+        await (0, index_1.handleDbSchemaGet)(table, { ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
     })
         .addHelpText("after", `
 Examples:
@@ -144,7 +145,7 @@ Examples:
         .option("--table <name>", "目标表名；未指定时按文件名（不含扩展名）推断（如 users.csv → users）")
         .option("--format <fmt>", "文件格式 csv / json；未指定时按文件扩展名推断")
         .action(async function (file) {
-        await (0, index_1.handleDbDataImport)(file, this.optsWithGlobals());
+        await (0, index_1.handleDbDataImport)(file, { ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
     })
         .addHelpText("after", `
 Notes:
@@ -181,7 +182,7 @@ Examples:
         .option("--limit <n>", "最多导出行数（不超过 5000）")
         .option("--force", "输出文件已存在时覆盖（默认报错）")
         .action(async function (table) {
-        await (0, index_1.handleDbDataExport)(table, this.optsWithGlobals());
+        await (0, index_1.handleDbDataExport)(table, { ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
     })
         .addHelpText("after", `
 Notes:

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

@@ -6,27 +6,41 @@ const shared_1 = require("../../../cli/commands/shared");
 const index_1 = require("../../../cli/handlers/deploy/index");
 const COMMON_TIME_HELP = `
 时间格式：
-  - 相对时间：1h（1 小时前）、2d（2 天前）、1w（1 周前）、30m（30 分钟前）
-  - 日期：2026-04-01（按当日 00:00:00 UTC）
-  - ISO 8601：2026-04-01T10:00:00Z
+  - 相对时间：30m（30 分钟前）、1h、2d、1w
+  - 日期：2026-04-01（本地时区当日 00:00:00）
+  - 本地日期+时间：2026-04-01T10:00:00（按本地时区，T 分隔）
+  - 带时区 ISO：2026-04-01T10:00:00Z（UTC）或 2026-04-01T10:00:00+08:00（指定偏移）
+  备注：
+    1) 不带时区的形式与 pretty 输出闭环（同机器复制粘贴稳定）；跨机器请带显式时区。
+    2) 必须用 T 分隔日期与时间，禁止空格——shell 会把不带引号的 'YYYY-MM-DD HH:mm:ss' 拆成两个参数。
 `;
 function registerDeployCommands(program) {
     // PRD：`miaoda deploy` 自身即为触发发布；get / history / error-log 是子命令
     const deployCmd = program
         .command("deploy")
-        .description(`触发发布；支持 --wait 阻塞到终态。子命令：get / history / error-log。 特别注意：
-    1.触发发布前，Agent 必须先前置检查工作区状态：因为 miaoda deploy 跑的是当前分支的远端 HEAD——本地未 commit / 未 push 的代码不会进发布产物。调用前先 \`git status\` + \`git rev-list --count @{u}..HEAD\` 确认；有未提交 / 未推送时：
-      - 是本次任务的产物 → 先 commit + push 再 deploy
-      - 不能确定意图 → 用 AskUser 跟用户确认（不要默默继续）
-      `)
+        .description("触发发布；支持 --wait 阻塞到终态。子命令：get / history / error-log")
         .addOption((0, shared_1.appIdOption)().hideHelp())
         .addOption((0, shared_1.branchOption)().hideHelp())
         .option("--wait", "阻塞直到流水线终态", false)
         .option("--timeout <sec>", "--wait 最长等待秒数（默认 300）", parseTimeout, 300)
         .addHelpText("after", `
+不要用异步模式或后台模式调用 deploy（例如 &、nohup、后台 task、detached run，或任何会让命令提前返回的包装方式），否则调用可能提前结束，Agent 会误判发布已完成。
+部署前置检查（Agent 必须执行）
+  miaoda deploy 跑的是当前分支的远端 HEAD——本地未 commit / 未 push 的代码不会进发布产物。
+  调用前先 \`git status\` + \`git rev-list --count @{u}..HEAD\` 确认；有未提交 / 未推送时：
+    - 是本次任务的产物 → 先 commit + push 再 deploy
+    - 不能确定意图 → 用 AskUser 跟用户确认（不要默默继续）
+
 JSON 输出
   不带 --wait：{"data": {"pipelineTaskID": "..."}}（pipelineTaskID 即 deploy-id）
   带 --wait：data 额外包含 detail（pipeline 终态）
+  detail/status 字段为可读字符串；对应 *_code 字段保留 BAM 原始数字枚举。
+
+状态确认（Agent 必须执行）
+  优先使用 --wait，但无论是否传 --wait，只要 deploy 调用后没有明确的 success / failed / canceled 终态，
+  都必须每 2s 轮询一次当前发布状态：拿到 pipelineTaskID 就执行 \`miaoda deploy get <pipelineTaskID> --json\`；
+  如果没有拿到 deploy-id 或输出为空，先执行 \`miaoda deploy history --limit 1 --json\` 找到对应发布记录并取得 ID，
+  再用这个 ID 每 2s 执行一次 \`miaoda deploy get <ID> --json\`，直到 status 进入终态。
 
 示例
   $ miaoda deploy
@@ -37,7 +51,7 @@ JSON 输出
     deployCmd.action((0, shared_1.withHelp)(deployCmd, async (rawOpts) => {
         (0, shared_1.rejectCliOverride)(deployCmd, "appId", "branch");
         await (0, index_1.handleDeploy)({
-            appId: rawOpts.appId,
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
             branch: rawOpts.branch,
             wait: rawOpts.wait,
             timeout: rawOpts.timeout,
@@ -57,6 +71,7 @@ function registerDeployGet(parent) {
 JSON 输出
   {"data": {"ID": ..., "status": ..., "creator": "...", "createdAt": ..., "updatedAt": ..., ...}, "next_cursor": null, "has_more": false}
   ID 即 deploy-id（== pipelineTaskID）
+  data.status 为可读字符串；data.status_code 为 BAM 原始数字枚举。
 
 示例
   $ miaoda deploy get 12345
@@ -65,7 +80,7 @@ JSON 输出
         (0, shared_1.rejectCliOverride)(cmd, "appId");
         await (0, index_1.handleDeployGet)({
             deployId,
-            appId: rawOpts.appId,
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
         });
     }));
 }
@@ -84,15 +99,17 @@ function registerDeployHistory(parent) {
         .addHelpText("after", `${COMMON_TIME_HELP}
 JSON 输出
   {"data": [...], "next_cursor": "...", "has_more": true|false}
+  data[].status 为可读字符串；data[].status_code 为 BAM 原始数字枚举。
 
 示例
   $ miaoda deploy history --status failed
   $ miaoda deploy history --since 7d
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
+        (0, shared_1.validateTimeOptions)(rawOpts, "since", "until");
         (0, shared_1.rejectCliOverride)(cmd, "appId");
         await (0, index_1.handleDeployHistory)({
-            appId: rawOpts.appId,
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
             status: rawOpts.status,
             since: rawOpts.since,
             until: rawOpts.until,
@@ -118,7 +135,7 @@ JSON 输出
         (0, shared_1.rejectCliOverride)(cmd, "appId");
         await (0, index_1.handleDeployErrorLog)({
             deployId,
-            appId: rawOpts.appId,
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
         });
     }));
 }

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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerFileCommands = registerFileCommands;
 const index_1 = require("../../../cli/handlers/file/index");
 const error_1 = require("../../../utils/error");
+const shared_1 = require("../../../cli/commands/shared");
 /**
  * commander option 校验器：把 --limit <n> 解析成正整数（≥1）。
  * 默认值（如 "50"）会先经过这里被规范化成 number。
@@ -43,7 +44,7 @@ function registerFileCommands(program) {
         .option("--cursor <token>", "分页游标，从上次响应的 next_cursor 取值")
         .option("--all", "自动翻页返回全部结果")
         .action(async (query, opts) => {
-        await (0, index_1.handleFileLs)({ ...opts, query });
+        await (0, index_1.handleFileLs)({ ...opts, appId: (0, shared_1.resolveAppId)({}), query });
     })
         .addHelpText("after", `
 Examples:
@@ -68,7 +69,7 @@ Examples:
         .usage("<file> [flags]")
         .argument("<file>", "文件的路径或文件名（自动识别）")
         .action(async (file, opts) => {
-        await (0, index_1.handleFileStat)(file, opts);
+        await (0, index_1.handleFileStat)(file, { ...opts, appId: (0, shared_1.resolveAppId)({}) });
     })
         .addHelpText("after", `
 Notes:
@@ -101,7 +102,7 @@ Examples:
         .argument("<dst>", "目标：本地路径或远程路径")
         .option("--rename <name>", "上传后在远端使用的新文件名")
         .action(async (src, dst, opts) => {
-        await (0, index_1.handleFileCp)(src, dst, opts);
+        await (0, index_1.handleFileCp)(src, dst, { ...opts, appId: (0, shared_1.resolveAppId)({}) });
     })
         .addHelpText("after", `
 Notes:
@@ -147,7 +148,7 @@ Examples:
         .option("-n, --name <name>", "按文件名删除（可重复指定）", (value, prev) => [...(prev ?? []), value])
         .option("-y, --yes", "跳过交互确认；非交互场景必加")
         .action(async (paths, opts) => {
-        await (0, index_1.handleFileRm)(paths, opts);
+        await (0, index_1.handleFileRm)(paths, { ...opts, appId: (0, shared_1.resolveAppId)({}) });
     })
         .addHelpText("after", `
 Notes:
@@ -190,7 +191,7 @@ Examples:
         .argument("<file>", "文件的路径或文件名")
         .option("--expires <duration>", "链接有效期，支持 30m / 24h / 7d 等单位（默认 1d，最长 30d）")
         .action(async (file, opts) => {
-        await (0, index_1.handleFileSign)(file, opts);
+        await (0, index_1.handleFileSign)(file, { ...opts, appId: (0, shared_1.resolveAppId)({}) });
     })
         .addHelpText("after", `
 Notes:

package/dist/cli/commands/index.js

@@ -1,17 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerCommands = registerCommands;
-const index_1 = require("../../cli/commands/plugin/index");
-const index_2 = require("../../cli/commands/file/index");
-const index_3 = require("../../cli/commands/db/index");
-const index_4 = require("../../cli/commands/observability/index");
-const index_5 = require("../../cli/commands/app/index");
-const index_6 = require("../../cli/commands/deploy/index");
+const index_1 = require("../../cli/commands/file/index");
+const index_2 = require("../../cli/commands/db/index");
+const index_3 = require("../../cli/commands/observability/index");
+const index_4 = require("../../cli/commands/app/index");
+const index_5 = require("../../cli/commands/deploy/index");
 function registerCommands(program) {
-    (0, index_1.registerPluginCommands)(program);
-    (0, index_2.registerFileCommands)(program);
-    (0, index_3.registerDbCommands)(program);
-    (0, index_4.registerObservabilityCommands)(program);
-    (0, index_5.registerAppCommands)(program);
-    (0, index_6.registerDeployCommands)(program);
+    (0, index_1.registerFileCommands)(program);
+    (0, index_2.registerDbCommands)(program);
+    (0, index_3.registerObservabilityCommands)(program);
+    (0, index_4.registerAppCommands)(program);
+    (0, index_5.registerDeployCommands)(program);
 }

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

@@ -6,9 +6,13 @@ const shared_1 = require("../../../cli/commands/shared");
 const index_1 = require("../../../cli/handlers/observability/index");
 const COMMON_TIME_HELP = `
 时间格式：
-  - 相对时间：1h（1 小时前）、2d（2 天前）、1w（1 周前）、30m（30 分钟前）
-  - 日期：2026-04-01（按当日 00:00:00 UTC）
-  - ISO 8601：2026-04-01T10:00:00Z
+  - 相对时间：30m（30 分钟前）、1h、2d、1w
+  - 日期：2026-04-01（本地时区当日 00:00:00）
+  - 本地日期+时间：2026-04-01T10:00:00（按本地时区，T 分隔）
+  - 带时区 ISO：2026-04-01T10:00:00Z（UTC）或 2026-04-01T10:00:00+08:00（指定偏移）
+  备注：
+    1) 不带时区的形式与 pretty 输出闭环（同机器复制粘贴稳定）；跨机器请带显式时区。
+    2) 必须用 T 分隔日期与时间，禁止空格——shell 会把不带引号的 'YYYY-MM-DD HH:mm:ss' 拆成两个参数。
 `;
 function registerObservabilityCommands(program) {
     const obCmd = program
@@ -23,8 +27,7 @@ function registerObservabilityCommands(program) {
   应用上下文：--app-id <id> 或环境变量 MIAODA_APP_ID。
 
 应用环境
-  log/trace 命令需要 --env <dev|online>，默认 online，可设置 MIAODA_APP_ENV 覆盖。
-  metric/analytics 不需要 --env。
+  目前只支持线上环境。
 `);
     registerLog(obCmd);
     registerTrace(obCmd);
@@ -42,6 +45,7 @@ function registerLog(parent) {
         .argParser((0, shared_1.caseInsensitiveChoice)(["DEBUG", "INFO", "WARN", "ERROR"])))
         .option("--since <time>", "开始时间")
         .option("--until <time>", "截止时间")
+        .option("--log-id <id>", "按请求 logid 过滤（attributes.ob_data_id）")
         .option("--trace-id <id>", "按 trace ID 过滤")
         .option("--grep <pattern>", "按关键字模糊搜索 body")
         .option("--module <name>", "按模块名过滤")
@@ -58,16 +62,19 @@ JSON 输出
 
 示例
   $ miaoda observability log --since 1h --level error --json
+  $ miaoda observability log --log-id log_abc123 --json
   $ miaoda observability log --trace-id 140ebb5ac9b... --json
   $ miaoda observability log --api /api/orders --min-duration 200 --json
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
+        (0, shared_1.validateTimeOptions)(rawOpts, "since", "until");
         (0, shared_1.rejectCliOverride)(cmd, "appId");
         await (0, index_1.handleObservabilityLog)({
-            appId: rawOpts.appId,
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
             level: rawOpts.level,
             since: rawOpts.since,
             until: rawOpts.until,
+            logId: rawOpts.logId,
             traceId: rawOpts.traceId,
             grep: rawOpts.grep,
             module: rawOpts.module,
@@ -107,9 +114,10 @@ JSON 输出
   $ miaoda observability trace list --root-span api-gateway --limit 20 --json
 `);
     listCmd.action((0, shared_1.withHelp)(listCmd, async (rawOpts) => {
+        (0, shared_1.validateTimeOptions)(rawOpts, "since", "until");
         (0, shared_1.rejectCliOverride)(listCmd, "appId");
         await (0, index_1.handleObservabilityTraceList)({
-            appId: rawOpts.appId,
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
             since: rawOpts.since,
             until: rawOpts.until,
             traceId: rawOpts.traceId,
@@ -141,7 +149,7 @@ JSON 输出
         (0, shared_1.rejectCliOverride)(getCmd, "appId");
         await (0, index_1.handleObservabilityTraceGet)({
             traceId,
-            appId: rawOpts.appId,
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
             withLogSeverityCount: rawOpts.withLogSeverityCount,
         });
     }));
@@ -161,7 +169,7 @@ function registerMetric(parent) {
         .addOption(new commander_1.Option("--down-sample <duration>", "降采样粒度（1m=1分钟 / 1h=1小时 / 1d=1天，大小写不敏感）")
         .choices(["1m", "1h", "1d"])
         .argParser((0, shared_1.caseInsensitiveChoice)(["1m", "1h", "1d"]))
-        .default("1h"))
+        .default("1m"))
         .addHelpText("after", `${COMMON_TIME_HELP}
 JSON 输出
   {"data": [{"metricName": "...", "dimensions": {...}, "dataPoints": [...]}], "next_cursor": null, "has_more": false}
@@ -173,10 +181,11 @@ JSON 输出
   $ miaoda observability metric cpu --since 1d --down-sample 1d --json
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (metricName, rawOpts) => {
+        (0, shared_1.validateTimeOptions)(rawOpts, "since", "until");
         (0, shared_1.rejectCliOverride)(cmd, "appId");
         await (0, index_1.handleObservabilityMetric)({
             metricName,
-            appId: rawOpts.appId,
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
             page: rawOpts.page,
             api: rawOpts.api,
             series: rawOpts.series,
@@ -194,7 +203,7 @@ function registerAnalytics(parent) {
         .argument("<analytics-name>", "指标名：users | page-view")
         .addOption((0, shared_1.appIdOption)().hideHelp())
         .option("--page <path>", "按页面路径过滤（仅对 page-view 生效）")
-        .option("--series <name>", "过滤图表中的某条线：users 取 active-users/new-users/total-users；page-view 取 all-view/desktop-view/mobile-view；缺省返回所有相关线")
+        .option("--series <name>", "过滤图表中的某条线：users 取 active/new/total（兼容 active-users/new-users/total-users）；page-view 取 all/desktop/mobile（兼容 all-view/desktop-view/mobile-view）")
         .option("--since <time>", "开始时间")
         .option("--until <time>", "截止时间")
         .option("--granularity <duration>", "时间粒度：day | week | month", "day")
@@ -204,14 +213,15 @@ JSON 输出
 
 示例
   $ miaoda observability analytics users --json                      # 同时返回 active/new/total 三条线
-  $ miaoda observability analytics users --series new-users --since 7d --json
+  $ miaoda observability analytics users --series new --since 7d --json
   $ miaoda observability analytics page-view --granularity week --json
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (analyticsName, rawOpts) => {
+        (0, shared_1.validateTimeOptions)(rawOpts, "since", "until");
         (0, shared_1.rejectCliOverride)(cmd, "appId");
         await (0, index_1.handleObservabilityAnalytics)({
             analyticsName,
-            appId: rawOpts.appId,
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
             env: rawOpts.env,
             page: rawOpts.page,
             series: rawOpts.series,

package/dist/cli/commands/shared.js

@@ -1,15 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.failArgs = void 0;
 exports.appIdOption = appIdOption;
 exports.branchOption = branchOption;
 exports.softRequiredOption = softRequiredOption;
 exports.resolveAppId = resolveAppId;
 exports.withHelp = withHelp;
-exports.failArgs = failArgs;
 exports.caseInsensitiveChoice = caseInsensitiveChoice;
+exports.validateTimeOptions = validateTimeOptions;
 exports.rejectCliOverride = rejectCliOverride;
 const commander_1 = require("commander");
 const error_1 = require("../../utils/error");
+const time_1 = require("../../utils/time");
+const args_1 = require("../../utils/args");
+Object.defineProperty(exports, "failArgs", { enumerable: true, get: function () { return args_1.failArgs; } });
 /** --app-id option，需要应用上下文的命令自行 .addOption(appIdOption()) */
 function appIdOption() {
     return new commander_1.Option("--app-id <id>", "指定目标应用").env("MIAODA_APP_ID");
@@ -59,10 +63,6 @@ function withHelp(cmd, handler) {
         }
     };
 }
-/** 参数校验失败时抛出，配合 withHelp 自动打 help */
-function failArgs(message) {
-    throw new error_1.AppError("ARGS_INVALID", message);
-}
 /**
  * 大小写不敏感的 choice argParser：把用户输入按 lowerCase 匹配回 canonical 数组里
  * 的同名值（保留 canonical 大小写），未命中抛 Commander 的 InvalidArgumentError
@@ -86,6 +86,24 @@ function caseInsensitiveChoice(canonical) {
         return hit;
     };
 }
+/**
+ * --since / --until 等时间参数的 action 阶段校验。
+ *
+ * Commander 的 argParser 会在 action 前直接按 parser error 退出（exit 1），
+ * 绕过 withHelp 的 ARGS_INVALID → exit 2 路径；所以时间参数在 action 内先
+ * 校验一遍，再把原始字符串交给 handler 解析成接口需要的单位。
+ */
+function validateTimeOptions(opts, ...names) {
+    for (const name of names) {
+        const value = opts[name];
+        if (value === undefined)
+            continue;
+        if (typeof value !== "string") {
+            (0, args_1.failArgs)(`--${name.replace(/([A-Z])/g, "-$1").toLowerCase()} 必须是时间字符串`);
+        }
+        (0, time_1.parseTimeToMs)(value);
+    }
+}
 /**
  * 拒绝 CLI 显式覆盖：用于 hideHelp() + .env() 的"沙箱注入参数"（如 --app-id / --branch）。
  *
@@ -102,7 +120,7 @@ function rejectCliOverride(cmd, ...optNames) {
     for (const name of optNames) {
         if (cmd.getOptionValueSource(name) === "cli") {
             const flag = "--" + name.replace(/([A-Z])/g, "-$1").toLowerCase();
-            failArgs(`${flag} 由沙箱/本地配置注入，不允许显式传递`);
+            (0, args_1.failArgs)(`${flag} 由沙箱/本地配置注入，不允许显式传递`);
         }
     }
 }

package/dist/cli/handlers/app/get.js

@@ -36,13 +36,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleAppGet = handleAppGet;
 const api = __importStar(require("../../../api/index"));
 const output_1 = require("../../../utils/output");
-const shared_1 = require("../../../cli/commands/shared");
 const index_1 = require("../../../api/app/index");
 /** miaoda app get [--app-id <id>] */
 async function handleAppGet(opts) {
-    const appID = (0, shared_1.resolveAppId)({ appId: opts.appId });
+    const appID = opts.appId;
     const resp = await api.app.getAppInfo(appID);
     // BAM 在 status_code=0 时 data 字段含 appInfo；不存在则 fallback 空对象
     const meta = resp.appInfo?.appMeta ?? {};
-    (0, output_1.emit)({ data: meta, next_cursor: null, has_more: false }, index_1.appMetaSchema);
+    (0, output_1.emit)({ data: meta }, index_1.appMetaSchema);
 }

package/dist/cli/handlers/app/update.js

@@ -36,14 +36,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleAppUpdate = handleAppUpdate;
 const api = __importStar(require("../../../api/index"));
 const output_1 = require("../../../utils/output");
-const shared_1 = require("../../../cli/commands/shared");
+const args_1 = require("../../../utils/args");
 const index_1 = require("../../../api/app/index");
 /** miaoda app update [--app-id <id>] [--name <n>] [--description <d>] */
 async function handleAppUpdate(opts) {
     if (opts.name === undefined && opts.description === undefined) {
-        (0, shared_1.failArgs)("至少需要 --name 或 --description 中的一个");
+        (0, args_1.failArgs)("至少需要 --name 或 --description 中的一个");
     }
-    const appID = (0, shared_1.resolveAppId)({ appId: opts.appId });
+    const appID = opts.appId;
     await api.app.updateAppMeta({
         appID,
         name: opts.name,
@@ -55,5 +55,5 @@ async function handleAppUpdate(opts) {
     if (!(0, output_1.isJsonMode)()) {
         process.stdout.write("✓ App updated successfully\n");
     }
-    (0, output_1.emit)({ data: meta, next_cursor: null, has_more: false }, index_1.appMetaSchema);
+    (0, output_1.emit)({ data: meta }, index_1.appMetaSchema);
 }

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

@@ -40,13 +40,12 @@ const path = __importStar(require("node:path"));
 const api = __importStar(require("../../../api/index"));
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
-const shared_1 = require("../../../cli/commands/shared");
 const render_1 = require("../../../utils/render");
 // P0 规格（对齐技术方案关键决策 2）
 const MAX_SIZE_BYTES = 1 * 1024 * 1024; // 1 MB
 const MAX_ROWS = 5000;
 async function handleDbDataImport(file, opts) {
-    const appId = (0, shared_1.resolveAppId)(opts);
+    const appId = opts.appId;
     const ext = path.extname(file).toLowerCase();
     const format = resolveFormat(opts.format, ext, "import");
     let body;
@@ -95,7 +94,7 @@ async function handleDbDataImport(file, opts) {
         : `OK Imported ${file} -> table '${result.tableName}' (${String(result.recordCount)} rows)`);
 }
 async function handleDbDataExport(table, opts) {
-    const appId = (0, shared_1.resolveAppId)(opts);
+    const appId = opts.appId;
     const format = resolveFormat(opts.format, undefined, "export", "csv");
     const outputPath = opts.file ?? `${table}.${format}`;
     const limit = opts.limit ? Number(opts.limit) : MAX_ROWS;

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

@@ -39,12 +39,11 @@ const api = __importStar(require("../../../api/index"));
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 const render_1 = require("../../../utils/render");
-const shared_1 = require("../../../cli/commands/shared");
 const colors_1 = require("../../../utils/colors");
 const index_1 = require("../../../api/db/index");
 // ── schema list ──
 async function handleDbSchemaList(opts) {
-    const appId = (0, shared_1.resolveAppId)(opts);
+    const appId = opts.appId;
     const resp = await api.db.getSchema({
         appId,
         format: "schema",
@@ -80,7 +79,7 @@ async function handleDbSchemaList(opts) {
     (0, output_1.emit)(tty ? (0, render_1.renderAlignedTable)(headers, rows) : (0, render_1.renderTsv)(headers, rows));
 }
 async function handleDbSchemaGet(table, opts) {
-    const appId = (0, shared_1.resolveAppId)(opts);
+    const appId = opts.appId;
     const tty = (0, render_1.isStdoutTty)();
     const forceDdl = Boolean(opts.ddl);
     const wantsStructured = (0, output_1.isJsonMode)() || (tty && !forceDdl);

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

@@ -42,7 +42,6 @@ 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 colors_1 = require("../../../utils/colors");
 const fuzzy_match_1 = require("../../../utils/fuzzy-match");
@@ -62,7 +61,7 @@ const node_path_1 = __importDefault(require("node:path"));
  *   末尾汇总，--json 输出 data 数组。
  */
 async function handleDbSql(query, opts) {
-    const appId = (0, shared_1.resolveAppId)(opts);
+    const appId = opts.appId;
     const sql = await readSql(query);
     if (!sql.trim()) {
         throw new error_1.AppError("ARGS_INVALID", "Empty SQL (no inline query and stdin is empty)");