@lark-apaas/miaoda-cli 0.1.2 → 0.1.3

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

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAppCommands = registerAppCommands;
+const shared_1 = require("../../../cli/commands/shared");
+const index_1 = require("../../../cli/handlers/app/index");
+function registerAppCommands(program) {
+    const appCmd = program.command("app").description("应用元数据管理：查看 / 修改");
+    appCmd.action(() => {
+        appCmd.outputHelp();
+    });
+    appCmd.addHelpText("after", `
+作用范围
+  仅供 Agent 在妙搭沙箱内调用。
+  应用上下文：沙箱内的默认应用。
+`);
+    registerAppGet(appCmd);
+    registerAppUpdate(appCmd);
+}
+function registerAppGet(parent) {
+    const cmd = parent
+        .command("get")
+        .description("查看应用元数据（status / type / mode / branch / 时间戳 等）")
+        .addOption((0, shared_1.appIdOption)().hideHelp())
+        .addHelpText("after", `
+JSON 输出
+  {"data": {"appID": "...", "name": "...", ...}}
+
+示例
+  $ miaoda app get
+  $ miaoda app get --json
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
+        (0, shared_1.rejectCliOverride)(cmd, "appId");
+        await (0, index_1.handleAppGet)({
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
+        });
+    }));
+}
+function registerAppUpdate(parent) {
+    const cmd = parent
+        .command("update")
+        .description("修改应用名称 / 描述（至少传 --name 或 --description）")
+        .addOption((0, shared_1.appIdOption)().hideHelp())
+        .option("--name <name>", "新应用名称")
+        .option("--description <desc>", "新应用描述")
+        .addHelpText("after", `
+JSON 输出
+  与 'app get' 一致：{"data": {...新 meta...}}
+
+示例
+  $ miaoda app update --name my-store
+  $ miaoda app update --description "在线商城应用"
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
+        (0, shared_1.rejectCliOverride)(cmd, "appId");
+        await (0, index_1.handleAppUpdate)({
+            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

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDeployCommands = registerDeployCommands;
+const commander_1 = require("commander");
+const shared_1 = require("../../../cli/commands/shared");
+const index_1 = require("../../../cli/handlers/deploy/index");
+const COMMON_TIME_HELP = `
+时间格式：
+  - 相对时间：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")
+        .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
+  $ miaoda deploy --wait --timeout 600
+  $ miaoda deploy get 12345
+  $ miaoda deploy history --status failed
+`);
+    deployCmd.action((0, shared_1.withHelp)(deployCmd, async (rawOpts) => {
+        (0, shared_1.rejectCliOverride)(deployCmd, "appId", "branch");
+        await (0, index_1.handleDeploy)({
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
+            branch: rawOpts.branch,
+            wait: rawOpts.wait,
+            timeout: rawOpts.timeout,
+        });
+    }));
+    registerDeployGet(deployCmd);
+    registerDeployHistory(deployCmd);
+    registerDeployErrorLog(deployCmd);
+}
+function registerDeployGet(parent) {
+    const cmd = parent
+        .command("get")
+        .description("查看指定发布单的详情")
+        .argument("<deploy-id>", "发布单 ID")
+        .addOption((0, shared_1.appIdOption)().hideHelp())
+        .addHelpText("after", `
+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
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (deployId, rawOpts) => {
+        (0, shared_1.rejectCliOverride)(cmd, "appId");
+        await (0, index_1.handleDeployGet)({
+            deployId,
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
+        });
+    }));
+}
+function registerDeployHistory(parent) {
+    const cmd = parent
+        .command("history")
+        .description("查询发布历史（按时间倒序，分页）")
+        .addOption((0, shared_1.appIdOption)().hideHelp())
+        .addOption(new commander_1.Option("--status <status>", "状态过滤（pipeline 节点状态，大小写不敏感）")
+        .choices(["todo", "running", "success", "failed", "canceled", "hold_on"])
+        .argParser((0, shared_1.caseInsensitiveChoice)(["todo", "running", "success", "failed", "canceled", "hold_on"])))
+        .option("--since <time>", "起始时间")
+        .option("--until <time>", "截止时间")
+        .option("--limit <n>", "返回条数上限（1~100）", parseLimit, 50)
+        .option("--cursor <token>", "下一页游标")
+        .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: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
+            status: rawOpts.status,
+            since: rawOpts.since,
+            until: rawOpts.until,
+            limit: rawOpts.limit,
+            cursor: rawOpts.cursor,
+        });
+    }));
+}
+function registerDeployErrorLog(parent) {
+    const cmd = parent
+        .command("error-log")
+        .description("查询指定发布的错误日志")
+        .argument("<deploy-id>", "发布单 ID")
+        .addOption((0, shared_1.appIdOption)().hideHelp())
+        .addHelpText("after", `
+JSON 输出
+  {"data": [{"jobID": ..., "componentName": ..., "errorMsg": ...}], "next_cursor": null, "has_more": false}
+
+示例
+  $ miaoda deploy error-log 12345 --json
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (deployId, rawOpts) => {
+        (0, shared_1.rejectCliOverride)(cmd, "appId");
+        await (0, index_1.handleDeployErrorLog)({
+            deployId,
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
+        });
+    }));
+}
+function parseLimit(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n)) {
+        throw new Error(`--limit 必须是数字，收到 '${value}'`);
+    }
+    return n;
+}
+function parseTimeout(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new Error(`--timeout 必须是正数，收到 '${value}'`);
+    }
+    return n;
+}

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,11 +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_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_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

@@ -0,0 +1,240 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerObservabilityCommands = registerObservabilityCommands;
+const commander_1 = require("commander");
+const shared_1 = require("../../../cli/commands/shared");
+const index_1 = require("../../../cli/handlers/observability/index");
+const COMMON_TIME_HELP = `
+时间格式：
+  - 相对时间：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
+        .command("observability")
+        .description("可观测性：查询线上日志、链路、监控指标、运营指标");
+    obCmd.action(() => {
+        obCmd.outputHelp();
+    });
+    obCmd.addHelpText("after", `
+作用范围
+  仅供 Agent 在妙搭沙箱内调用，查询当前应用的线上观测数据。所有命令为只读。
+  应用上下文：--app-id <id> 或环境变量 MIAODA_APP_ID。
+
+应用环境
+  目前只支持线上环境。
+`);
+    registerLog(obCmd);
+    registerTrace(obCmd);
+    registerMetric(obCmd);
+    registerAnalytics(obCmd);
+}
+// ── log ──
+function registerLog(parent) {
+    const cmd = parent
+        .command("log")
+        .description("查询线上运行日志（按时间倒序，分页）")
+        .addOption((0, shared_1.appIdOption)().hideHelp())
+        .addOption(new commander_1.Option("--level <level>", "日志级别（大小写不敏感）")
+        .choices(["DEBUG", "INFO", "WARN", "ERROR"])
+        .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>", "按模块名过滤")
+        .option("--user-id <user-id>", "按触发用户 ID 过滤")
+        .option("--page <path>", "按页面路径过滤")
+        .option("--api <path>", "按接口路径过滤")
+        .option("--min-duration <ms>", "最小耗时过滤（毫秒）")
+        .option("--max-duration <ms>", "最大耗时过滤（毫秒）")
+        .option("--limit <n>", "返回条数上限（1~100）", parseLimit, 50)
+        .option("--cursor <token>", "下一页游标，从上一次返回的 next_cursor 取值")
+        .addHelpText("after", `${COMMON_TIME_HELP}
+JSON 输出
+  {"data": [...], "next_cursor": "...", "has_more": true|false}
+
+示例
+  $ 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: (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,
+            userId: rawOpts.userId,
+            page: rawOpts.page,
+            api: rawOpts.api,
+            minDuration: rawOpts.minDuration,
+            maxDuration: rawOpts.maxDuration,
+            limit: rawOpts.limit,
+            cursor: rawOpts.cursor,
+        });
+    }));
+}
+// ── trace ──
+function registerTrace(parent) {
+    const traceCmd = parent.command("trace").description("链路追踪：列表 / 详情");
+    traceCmd.action(() => {
+        traceCmd.outputHelp();
+    });
+    const listCmd = traceCmd
+        .command("list")
+        .description("查询线上链路列表（按链路时间倒序，分页）")
+        .addOption((0, shared_1.appIdOption)().hideHelp())
+        .option("--since <time>", "开始时间")
+        .option("--until <time>", "截止时间")
+        .option("--trace-id <id>", "按 trace ID 过滤")
+        .option("--root-span <span-name>", "按入口节点关键词过滤")
+        .option("--user-id <user-id>", "按触发用户 ID 过滤")
+        .option("--limit <n>", "返回条数上限（1~100）", parseLimit, 50)
+        .option("--cursor <token>", "下一页游标")
+        .addHelpText("after", `${COMMON_TIME_HELP}
+JSON 输出
+  {"data": [...], "next_cursor": "...", "has_more": true|false}
+
+示例
+  $ miaoda observability trace list --since 1h --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: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
+            since: rawOpts.since,
+            until: rawOpts.until,
+            traceId: rawOpts.traceId,
+            rootSpan: rawOpts.rootSpan,
+            userId: rawOpts.userId,
+            limit: rawOpts.limit,
+            cursor: rawOpts.cursor,
+        });
+    }));
+    const getCmd = traceCmd
+        .command("get")
+        .description("查询指定链路的完整详情")
+        .argument("<trace-id>", "链路 ID")
+        .addOption((0, shared_1.appIdOption)().hideHelp())
+        .option("--with-log-severity-count", "返回每个 Span 各日志级别的数量", false)
+        .addHelpText("after", `
+JSON 输出
+  {"data": {"spans": [...], "isBreak": false}}
+
+示例
+  $ miaoda observability trace get 140ebb5ac9b55ed50d6ed1090cad4d --json
+
+  # 报错：链路不存在
+  $ miaoda observability trace get not-exist
+  Error: Failed to get trace: 500 ...
+    hint: 检查 trace-id 是否正确，或链路已超出保留时长
+`);
+    getCmd.action((0, shared_1.withHelp)(getCmd, async (traceId, rawOpts) => {
+        (0, shared_1.rejectCliOverride)(getCmd, "appId");
+        await (0, index_1.handleObservabilityTraceGet)({
+            traceId,
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
+            withLogSeverityCount: rawOpts.withLogSeverityCount,
+        });
+    }));
+}
+// ── metric ──
+function registerMetric(parent) {
+    const cmd = parent
+        .command("metric")
+        .description("查询监控指标：requests / latency / cpu / memory")
+        .argument("<metric-name>", "指标名：requests | latency | cpu | memory")
+        .addOption((0, shared_1.appIdOption)().hideHelp())
+        .option("--page <path>", "按页面路径过滤（仅对 requests/latency 生效）")
+        .option("--api <path>", "按接口路径过滤（仅对 requests/latency 生效）")
+        .option("--series <name>", "过滤图表中的某条线：latency 取 p50/p99；requests 取 total/error；缺省返回所有相关线")
+        .option("--since <time>", "开始时间")
+        .option("--until <time>", "截止时间")
+        .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("1m"))
+        .addHelpText("after", `${COMMON_TIME_HELP}
+JSON 输出
+  {"data": [{"metricName": "...", "dimensions": {...}, "dataPoints": [...]}], "next_cursor": null, "has_more": false}
+
+示例
+  $ miaoda observability metric latency --since 1h --json
+  $ miaoda observability metric latency --since 1h --series p99 --json
+  $ miaoda observability metric requests --api /api/users --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: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
+            page: rawOpts.page,
+            api: rawOpts.api,
+            series: rawOpts.series,
+            since: rawOpts.since,
+            until: rawOpts.until,
+            downSample: rawOpts.downSample,
+        });
+    }));
+}
+// ── analytics ──
+function registerAnalytics(parent) {
+    const cmd = parent
+        .command("analytics")
+        .description("查询运营指标：users（用户数）/ page-view（页面访问）")
+        .argument("<analytics-name>", "指标名：users | page-view")
+        .addOption((0, shared_1.appIdOption)().hideHelp())
+        .option("--page <path>", "按页面路径过滤（仅对 page-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")
+        .addHelpText("after", `${COMMON_TIME_HELP}
+JSON 输出
+  {"data": [{"metricType": "...", "points": [{"timestampNs": "...", "value": ..., "dimensions": {...}}]}], "next_cursor": null, "has_more": false}
+
+示例
+  $ miaoda observability analytics users --json                      # 同时返回 active/new/total 三条线
+  $ 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: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
+            env: rawOpts.env,
+            page: rawOpts.page,
+            series: rawOpts.series,
+            since: rawOpts.since,
+            until: rawOpts.until,
+            granularity: rawOpts.granularity,
+        });
+    }));
+}
+function parseLimit(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n)) {
+        throw new Error(`--limit 必须是数字，收到 '${value}'`);
+    }
+    return n;
+}