@lark-apaas/miaoda-cli 0.1.2 → 0.1.3-alpha.4bf312e

package/dist/cli/handlers/file/rm.js

@@ -40,7 +40,6 @@ exports.handleFileRm = handleFileRm;
 const api = __importStar(require("../../../api/index"));
 const output_1 = require("../../../utils/output");
 const error_1 = require("../../../utils/error");
-const shared_1 = require("../../../cli/commands/shared");
 const index_1 = require("../../../api/file/index");
 const render_1 = require("../../../utils/render");
 const colors_1 = require("../../../utils/colors");
@@ -133,7 +132,7 @@ async function handleFileRm(paths, opts) {
     if (totalCount > MAX_BATCH) {
         throw new error_1.AppError("FILE_BATCH_TOO_MANY", `Batch size ${String(totalCount)} exceeds the 100 limit`);
     }
-    const appId = (0, shared_1.resolveAppId)(opts);
+    const appId = opts.appId;
     // destructive guardrail
     const tty = (0, render_1.isStdoutTty)();
     if (tty && !opts.yes) {

package/dist/cli/handlers/file/sign.js

@@ -38,7 +38,6 @@ const api = __importStar(require("../../../api/index"));
 const output_1 = require("../../../utils/output");
 const render_1 = require("../../../utils/render");
 const error_1 = require("../../../utils/error");
-const shared_1 = require("../../../cli/commands/shared");
 const index_1 = require("../../../api/file/index");
 const MAX_EXPIRES_SECONDS = 30 * 86400;
 const DEFAULT_EXPIRES_SECONDS = 86400; // 1d（PRD 规定）
@@ -64,7 +63,7 @@ async function resolveFilePath(appId, input) {
     return resolved.file.path;
 }
 async function handleFileSign(file, opts) {
-    const appId = (0, shared_1.resolveAppId)(opts);
+    const appId = opts.appId;
     let expiresSec = DEFAULT_EXPIRES_SECONDS;
     if (opts.expires) {
         expiresSec = (0, render_1.parseDuration)(opts.expires);

package/dist/cli/handlers/file/stat.js

@@ -38,7 +38,6 @@ const api = __importStar(require("../../../api/index"));
 const output_1 = require("../../../utils/output");
 const render_1 = require("../../../utils/render");
 const error_1 = require("../../../utils/error");
-const shared_1 = require("../../../cli/commands/shared");
 const index_1 = require("../../../api/file/index");
 /**
  * 解析 `<file>` 为后端 head 可用的 filePath。
@@ -67,7 +66,7 @@ async function resolveFile(appId, input) {
     return head;
 }
 async function handleFileStat(file, opts) {
-    const appId = (0, shared_1.resolveAppId)(opts);
+    const appId = opts.appId;
     const info = await resolveFile(appId, file);
     if ((0, output_1.isJsonMode)()) {
         (0, output_1.emitOk)(info);

package/dist/cli/handlers/observability/analytics.js

@@ -0,0 +1,212 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleObservabilityAnalytics = handleObservabilityAnalytics;
+const api = __importStar(require("../../../api/index"));
+const output_1 = require("../../../utils/output");
+const args_1 = require("../../../utils/args");
+const helpers_1 = require("./helpers");
+const GRANULARITY_TO_UNIT = {
+    day: "DAY",
+    daily: "DAY",
+    "1d": "DAY",
+    "1h": "HOUR",
+    hour: "HOUR",
+    week: "WEEK",
+    weekly: "WEEK",
+    "1w": "WEEK",
+    month: "MONTH",
+    monthly: "MONTH",
+    "1M": "MONTH",
+};
+/**
+ * <analytics-name> + --series → metricType → 表头列名（=对应 --series 取值）。
+ *
+ * - users 缺省返回 active/new/total 三条线（多线视图）。
+ * - page-view 当前 BAM 只有一个 PAGE_VIEW metricType；不同 series 通过 device_type 过滤区分；
+ *   表头 label 直接对应 --series 取值（all-view / desktop-view / mobile-view）。
+ */
+const ANALYTICS_LABELS = {
+    users: {
+        ACTIVE_USER: "active-users",
+        NEW_USER: "new-users",
+        TOTAL_USER: "total-users",
+    },
+};
+/** miaoda observability analytics <analytics-name> */
+async function handleObservabilityAnalytics(opts) {
+    if (!opts.analyticsName)
+        (0, args_1.failArgs)("<analytics-name> 必填");
+    const appID = opts.appId;
+    const { metricTypes, labelByMetric, extraFilters } = resolveAnalyticsSelection(opts.analyticsName, opts.series);
+    const timeAggregationUnit = opts.granularity
+        ? (GRANULARITY_TO_UNIT[opts.granularity] ?? opts.granularity.toUpperCase())
+        : "DAY";
+    const nowMs = Date.now();
+    const sinceMs = (0, helpers_1.parseToMs)(opts.since) ?? nowMs - 30 * 86_400_000;
+    const untilMs = (0, helpers_1.parseToMs)(opts.until) ?? nowMs;
+    const bucket = timeAggregationUnit;
+    const fieldFilters = (0, helpers_1.buildFieldFilters)([
+        { key: "path", value: opts.page ? (0, helpers_1.eqFilter)(opts.page) : undefined },
+        ...extraFilters,
+    ]);
+    const req = {
+        appID,
+        metricTypes,
+        startTimestampNs: (0, helpers_1.msToNs)(sinceMs),
+        endTimestampNs: (0, helpers_1.msToNs)((0, helpers_1.ceilMsToBucket)(untilMs, bucket)),
+        timeAggregationUnit,
+        fieldFilters,
+    };
+    const resp = await api.observability.queryAnalyticsData(req);
+    emitAnalyticsResponse(resp, labelByMetric);
+}
+// ── 渲染 ────────────
+//
+// BAM v1.0.123 起返回 points: [{timestampNs, dimensions, values: {metricType: v}}]——
+// 服务端已把多 metricType 合并到同 timestampNs 的 row，下游直接平铺即可。
+// JSON 模式：原样透传 points（保留 BAM 原 metricType 作为 values 的 key）。
+// Pretty 模式：把 values 里的 metricType 重命名成 CLI label（active-users 等），
+//   再走 buildAnalyticsPivotSchema 渲染。
+function emitAnalyticsResponse(resp, labelByMetric) {
+    const points = resp.points ?? [];
+    // analytics 不分页，但补齐 has_more / next_cursor 与 log/trace 信封形状对齐
+    if ((0, output_1.isJsonMode)()) {
+        (0, output_1.emit)({ data: points, next_cursor: null, has_more: false });
+        return;
+    }
+    const { rows, seriesLabels } = renameAndSort(points, labelByMetric);
+    if (rows.length === 0) {
+        (0, output_1.emit)({ data: [], next_cursor: null, has_more: false });
+        return;
+    }
+    (0, output_1.emit)({ data: rows, next_cursor: null, has_more: false }, buildAnalyticsPivotSchema(seriesLabels));
+}
+function renameAndSort(points, labelByMetric) {
+    // 列顺序按 labelByMetric 声明顺序，避免 BAM 返回顺序波动影响表头
+    const seriesLabels = Object.values(labelByMetric);
+    const rows = points.map((point) => {
+        const row = { timestampNs: point.timestampNs };
+        for (const [metricType, value] of Object.entries(point.values)) {
+            const label = labelByMetric[metricType] ?? metricType;
+            row[label] = value;
+        }
+        return row;
+    });
+    rows.sort((a, b) => b.timestampNs - a.timestampNs);
+    return { rows, seriesLabels };
+}
+function buildAnalyticsPivotSchema(seriesLabels) {
+    return {
+        columns: [
+            { key: "timestampNs", label: "time", format: output_1.fmt.ns() },
+            ...seriesLabels.map((label) => ({ key: label, label })),
+        ],
+        strict: true,
+    };
+}
+/**
+ * <analytics-name> + --series → metricTypes[] + label 映射 + 附加过滤
+ *
+ * users:
+ *   - 缺省 series → 三条线全返回（active-users/new-users/total-users）
+ *   - 单值 series → 对应单条线
+ * page-view:
+ *   - 缺省/all-view → 单条 PAGE_VIEW，无 device 过滤，label = "all-view"
+ *   - desktop-view / mobile-view → 单条 PAGE_VIEW + device_type 过滤，label = --series 值
+ */
+function resolveAnalyticsSelection(cliName, series) {
+    const extras = [];
+    const normalizedSeries = normalizeAnalyticsSeries(cliName, series);
+    if (cliName === "users") {
+        if (normalizedSeries === "active-users")
+            return single("ACTIVE_USER", "active-users", extras);
+        if (normalizedSeries === "new-users")
+            return single("NEW_USER", "new-users", extras);
+        if (normalizedSeries === "total-users")
+            return single("TOTAL_USER", "total-users", extras);
+        // 缺省：三条线
+        return all(ANALYTICS_LABELS.users, extras);
+    }
+    if (cliName === "page-view") {
+        if (normalizedSeries === "desktop-view") {
+            extras.push({ key: "device_type", value: (0, helpers_1.eqFilter)("desktop") });
+            return single("PAGE_VIEW", "desktop-view", extras);
+        }
+        if (normalizedSeries === "mobile-view") {
+            extras.push({ key: "device_type", value: (0, helpers_1.eqFilter)("mobile") });
+            return single("PAGE_VIEW", "mobile-view", extras);
+        }
+        // 缺省 / all-view → 不附加 device 过滤
+        return single("PAGE_VIEW", "all-view", extras);
+    }
+    // 兜底：CLI 名直接当 metricType + label
+    return single(cliName, cliName, extras);
+}
+function normalizeAnalyticsSeries(cliName, series) {
+    if (series === undefined)
+        return undefined;
+    if (cliName === "users") {
+        if (series === "active")
+            return "active-users";
+        if (series === "new")
+            return "new-users";
+        if (series === "total")
+            return "total-users";
+    }
+    if (cliName === "page-view") {
+        if (series === "all")
+            return "all-view";
+        if (series === "desktop")
+            return "desktop-view";
+        if (series === "mobile")
+            return "mobile-view";
+    }
+    return series;
+}
+function single(metricType, label, extras) {
+    return {
+        metricTypes: [metricType],
+        labelByMetric: { [metricType]: label },
+        extraFilters: extras,
+    };
+}
+function all(labelByMetric, extras) {
+    return {
+        metricTypes: Object.keys(labelByMetric),
+        labelByMetric,
+        extraFilters: extras,
+    };
+}

package/dist/cli/handlers/observability/helpers.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ceilMsToBucket = exports.floorMsToBucket = exports.msToSec = exports.msToNs = exports.parseToSec = exports.parseToNs = exports.parseToMs = exports.parseTimeToMs = void 0;
+exports.eqFilter = eqFilter;
+exports.rangeFilter = rangeFilter;
+exports.fuzzyFilter = fuzzyFilter;
+exports.buildFieldFilters = buildFieldFilters;
+exports.validateLimit = validateLimit;
+const args_1 = require("../../../utils/args");
+const index_1 = require("../../../api/observability/index");
+// 时间解析助手已抽到 utils/time.ts；这里 re-export 维持 observability handler 的旧 import 路径。
+var time_1 = require("../../../utils/time");
+Object.defineProperty(exports, "parseTimeToMs", { enumerable: true, get: function () { return time_1.parseTimeToMs; } });
+Object.defineProperty(exports, "parseToMs", { enumerable: true, get: function () { return time_1.parseToMs; } });
+Object.defineProperty(exports, "parseToNs", { enumerable: true, get: function () { return time_1.parseToNs; } });
+Object.defineProperty(exports, "parseToSec", { enumerable: true, get: function () { return time_1.parseToSec; } });
+Object.defineProperty(exports, "msToNs", { enumerable: true, get: function () { return time_1.msToNs; } });
+Object.defineProperty(exports, "msToSec", { enumerable: true, get: function () { return time_1.msToSec; } });
+Object.defineProperty(exports, "floorMsToBucket", { enumerable: true, get: function () { return time_1.floorMsToBucket; } });
+Object.defineProperty(exports, "ceilMsToBucket", { enumerable: true, get: function () { return time_1.ceilMsToBucket; } });
+// ── filter 构造 ──
+//
+// BAM FieldFilter 是「类型分桶 + 算子」结构（str/i64/double），不是扁平字段；
+// 字符串字段无 server-side contains，模糊匹配走 fuzzyFilter。
+/** 字符串字段等值过滤 → { str: { eq } } */
+function eqFilter(value, type = "str") {
+    const v = type !== "str" ? Number(value) : value;
+    return { [type]: { eq: v } };
+}
+/** i64 数值范围过滤 → { i64: { gte, lte } }；输入接受 string（CLI flag）或 number */
+function rangeFilter(opts) {
+    const i64 = {};
+    if (opts.gte !== undefined)
+        i64.gte = Number(opts.gte);
+    if (opts.lte !== undefined)
+        i64.lte = Number(opts.lte);
+    return { i64 };
+}
+/** 模糊搜索过滤器；默认 AND 运算符 */
+function fuzzyFilter(keyword, operator = index_1.WordOperator.AND) {
+    return { include: { words: [keyword], operator } };
+}
+/**
+ * 把若干条件按 key 装到 fieldFilters。值为 undefined 的条目跳过；
+ * 全部跳过时返回 undefined（避免传空 map）。
+ */
+function buildFieldFilters(entries) {
+    const out = {};
+    let added = false;
+    for (const { key, value } of entries) {
+        if (value === undefined)
+            continue;
+        out[key] = value;
+        added = true;
+    }
+    return added ? out : undefined;
+}
+// ── 校验 ──
+/** limit 校验（API 限制 1~100） */
+function validateLimit(limit, defaultLimit = 50) {
+    const n = Number.isFinite(limit) ? limit : defaultLimit;
+    if (n <= 0 || n > 100) {
+        (0, args_1.failArgs)(`--limit 必须在 1~100 之间，收到 ${String(n)}`);
+    }
+    return n;
+}

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

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleObservabilityAnalytics = exports.handleObservabilityMetric = exports.handleObservabilityTraceGet = exports.handleObservabilityTraceList = exports.handleObservabilityLog = void 0;
+var log_1 = require("./log");
+Object.defineProperty(exports, "handleObservabilityLog", { enumerable: true, get: function () { return log_1.handleObservabilityLog; } });
+var trace_1 = require("./trace");
+Object.defineProperty(exports, "handleObservabilityTraceList", { enumerable: true, get: function () { return trace_1.handleObservabilityTraceList; } });
+Object.defineProperty(exports, "handleObservabilityTraceGet", { enumerable: true, get: function () { return trace_1.handleObservabilityTraceGet; } });
+var metric_1 = require("./metric");
+Object.defineProperty(exports, "handleObservabilityMetric", { enumerable: true, get: function () { return metric_1.handleObservabilityMetric; } });
+var analytics_1 = require("./analytics");
+Object.defineProperty(exports, "handleObservabilityAnalytics", { enumerable: true, get: function () { return analytics_1.handleObservabilityAnalytics; } });

package/dist/cli/handlers/observability/log.js

@@ -0,0 +1,94 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleObservabilityLog = handleObservabilityLog;
+const api = __importStar(require("../../../api/index"));
+const output_1 = require("../../../utils/output");
+const index_1 = require("../../../api/observability/index");
+const helpers_1 = require("./helpers");
+/** miaoda observability log */
+async function handleObservabilityLog(opts) {
+    const appID = opts.appId;
+    const appEnv = "runtime";
+    const limit = (0, helpers_1.validateLimit)(opts.limit ?? 50);
+    // 过滤 key 对齐 BAM 查询字段名：
+    //   - 顶层字段：severity_text / trace_id（输出仍映射成 severityText / traceID）
+    //   - attributes 里的业务字段：module / user_id / page / api / ob_data_id（snake_case，
+    //     依据 BAM IDL 的 LogItem.attributes 描述："包括 tenant_id, module, user_id, page, api 等"）
+    //   - duration_ms 暂未在 BAM 描述里明确列出，留 TODO 等 e2e 验证
+    const fieldFilters = (0, helpers_1.buildFieldFilters)([
+        { key: "severity_text", value: opts.level ? (0, helpers_1.eqFilter)(opts.level) : undefined },
+        { key: "attributes.ob_data_id", value: opts.logId ? (0, helpers_1.eqFilter)(opts.logId) : undefined },
+        { key: "trace_id", value: opts.traceId ? (0, helpers_1.eqFilter)(opts.traceId) : undefined },
+        { key: "module", value: opts.module ? (0, helpers_1.eqFilter)(opts.module) : undefined },
+        { key: "user_id", value: opts.userId ? (0, helpers_1.eqFilter)(opts.userId, "i64") : undefined },
+        { key: "page", value: opts.page ? (0, helpers_1.eqFilter)(opts.page) : undefined },
+        { key: "api", value: opts.api ? (0, helpers_1.eqFilter)(opts.api) : undefined },
+        {
+            // TODO: 确认 BAM 是否真用 duration_ms 作为 attribute key
+            key: "duration_ms",
+            value: opts.minDuration !== undefined || opts.maxDuration !== undefined
+                ? (0, helpers_1.rangeFilter)({ gte: opts.minDuration, lte: opts.maxDuration })
+                : undefined,
+        },
+    ]);
+    const fuzzyFilter = opts.grep
+        ? {
+            include: {
+                words: [opts.grep],
+                operator: 1, // AND
+            },
+        }
+        : undefined;
+    const req = {
+        appID,
+        appEnv,
+        startTimestampNs: (0, helpers_1.parseToNs)(opts.since),
+        endTimestampNs: (0, helpers_1.parseToNs)(opts.until),
+        limit,
+        pageToken: opts.cursor,
+        fieldFilters,
+        fuzzyFilter,
+    };
+    const resp = await api.observability.searchLogs(req);
+    emitSearchLogsResponse(resp);
+}
+function emitSearchLogsResponse(resp) {
+    (0, output_1.emit)({
+        data: resp.logItems ?? [],
+        next_cursor: resp.hasMore ? resp.nextPageToken : null,
+        has_more: resp.hasMore,
+    }, index_1.logItemSchema);
+}

package/dist/cli/handlers/observability/metric.js

@@ -0,0 +1,208 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleObservabilityMetric = handleObservabilityMetric;
+const api = __importStar(require("../../../api/index"));
+const output_1 = require("../../../utils/output");
+const args_1 = require("../../../utils/args");
+const helpers_1 = require("./helpers");
+/**
+ * PRD <metric-name> + --series → 服务端 metric name → 表头列名（=对应 --series 取值）。
+ *
+ * - 缺省 --series 时返回该 cliName 下所有相关线。
+ * - latency / requests 的 error 线 v1.0.122 起由独立 metric 提供（不再 is_error filter）。
+ *
+ * 表头标签直接用 --series 名（"total"/"error"/"p50"/"p99"）；单一指标则用 cliName。
+ */
+const METRIC_LABELS = {
+    cpu: { cpu_usage: "cpu" },
+    memory: { mem_usage: "memory" },
+    requests: {
+        client_api_request_count: "total",
+        client_api_request_error_count: "error",
+    },
+    latency: {
+        client_api_request_latency_p50: "p50",
+        client_api_request_latency_p99: "p99",
+    },
+};
+/** miaoda observability metric <metric-name> */
+async function handleObservabilityMetric(opts) {
+    if (!opts.metricName)
+        (0, args_1.failArgs)("<metric-name> 必填");
+    const appID = opts.appId;
+    const { metricNames, labelByMetric, extraFilters } = resolveMetricSelection(opts.metricName, opts.series);
+    const filters = (0, helpers_1.buildFieldFilters)([
+        { key: "referer_path", value: opts.page ? (0, helpers_1.eqFilter)(opts.page) : undefined },
+        { key: "api", value: opts.api ? (0, helpers_1.eqFilter)(opts.api) : undefined },
+        ...extraFilters,
+    ]);
+    // since/until 直接以秒透传到 BAM；当前未做桶对齐（如需开启把 until
+    // 用 ceilMsToBucket(untilMs, downSample as GranularityBucket) 包一层即可）。
+    const downSample = opts.downSample ?? "1m";
+    const nowMs = Date.now();
+    const sinceMs = (0, helpers_1.parseToMs)(opts.since) ?? nowMs - 30 * 86_400_000;
+    const untilMs = (0, helpers_1.parseToMs)(opts.until) ?? nowMs;
+    const req = {
+        appID,
+        appEnv: "runtime",
+        metricNames,
+        startTimestamp: (0, helpers_1.msToSec)(sinceMs),
+        endTimestamp: (0, helpers_1.msToSec)(untilMs),
+        filters,
+        downSample,
+        needPackLackPoint: false,
+    };
+    const resp = await api.observability.queryMetricsData(req);
+    // requests 的 count / error_count：
+    //   - BAM 在该时间点无数据时会传 null，或者 values 里干脆缺 key
+    //   - CLI 按"请求过的 metricNames"逐一兜底为 0，让"没有请求"和"没有数据"
+    //     在表格 / JSON 里都显式呈现成 0，避免空格 / 缺字段被误解为缺失
+    // latency / cpu / memory 不做这个兜底——p50 没数据 ≠ 延迟为 0。
+    if (opts.metricName === "requests") {
+        fillRequestedMetricsWithZero(resp, metricNames);
+    }
+    emitMetricsResponse(resp, labelByMetric);
+}
+/**
+ * 按"客户端请求过的 metricNames"兜底缺失/为 null 的值为 0；不去动 BAM 多返回的
+ * 其他字段（防御性，避免误改不属于本次查询的数据）。
+ */
+function fillRequestedMetricsWithZero(resp, requestedMetricNames) {
+    for (const point of resp.points ?? []) {
+        for (const name of requestedMetricNames) {
+            point.values[name] ??= 0;
+        }
+    }
+}
+// ── 渲染 ─────────
+//
+// BAM v1.0.123 起返回 points: [{timestamp, dimensions, values: {metricName: v}}]——
+// 服务端已把多 metric 合并到同 timestamp 的 row，下游直接平铺即可。
+// JSON 模式：原样透传 points（保留 BAM 原 metricName 作为 values 的 key）。
+// Pretty 模式：把 values 里的 metricName 重命名成 CLI label（p50/p99/total 等），
+//   再走 buildPivotSchema 渲染。
+function emitMetricsResponse(resp, labelByMetric) {
+    const points = resp.points ?? [];
+    // metric 不分页，但仍补齐 has_more / next_cursor 以对齐 log/trace 的信封形状
+    if ((0, output_1.isJsonMode)()) {
+        (0, output_1.emit)({ data: points, next_cursor: null, has_more: false });
+        return;
+    }
+    const { rows, seriesLabels } = renameAndSort(points, labelByMetric);
+    if (rows.length === 0) {
+        (0, output_1.emit)({ data: [], next_cursor: null, has_more: false });
+        return;
+    }
+    const hasLatency = Object.keys(labelByMetric).some((n) => n.includes("latency"));
+    (0, output_1.emit)({ data: rows, next_cursor: null, has_more: false }, buildPivotSchema(seriesLabels, hasLatency));
+}
+function renameAndSort(points, labelByMetric) {
+    // 列顺序按 labelByMetric 声明顺序，避免 BAM 返回顺序波动影响表头
+    const seriesLabels = Object.values(labelByMetric);
+    // TODO: 当 dimensions 非空（groupBy 多 series）时，把 dimensions 也并入 row
+    const rows = points.map((point) => {
+        const row = { timestamp: point.timestamp };
+        for (const [metricName, value] of Object.entries(point.values)) {
+            const label = labelByMetric[metricName] ?? metricName;
+            row[label] = value;
+        }
+        return row;
+    });
+    // 按时间倒序，与 log/trace 的"最新在前"风格一致
+    rows.sort((a, b) => b.timestamp - a.timestamp);
+    return { rows, seriesLabels };
+}
+function buildPivotSchema(seriesLabels, hasLatency) {
+    const valueFormat = hasLatency ? output_1.fmt.durationMs() : undefined;
+    return {
+        columns: [
+            { key: "timestamp", label: "time", format: output_1.fmt.sec() },
+            ...seriesLabels.map((label) => ({
+                key: label,
+                label,
+                ...(valueFormat ? { format: valueFormat } : {}),
+            })),
+        ],
+        strict: true,
+    };
+}
+/**
+ * 解析 <metric-name> + --series 的组合：决定最终 metricNames、表头 label 映射、附加过滤。
+ *
+ * label 直接用 --series 取值（"total"/"error"/"p50"/"p99"）；单一指标 cliName 也作为 label。
+ */
+function resolveMetricSelection(cliName, series) {
+    const extras = [];
+    if (cliName === "latency") {
+        if (series === "p99") {
+            return single("client_api_request_latency_p99", "p99", extras);
+        }
+        if (series === "p50") {
+            return single("client_api_request_latency_p50", "p50", extras);
+        }
+        return all(METRIC_LABELS.latency, extras);
+    }
+    if (cliName === "requests") {
+        // v1.0.122 起 error 线由独立 metric 提供，不再走 is_error filter
+        if (series === "total") {
+            return single("client_api_request_count", "total", extras);
+        }
+        if (series === "error") {
+            return single("client_api_request_error_count", "error", extras);
+        }
+        return all(METRIC_LABELS.requests, extras);
+    }
+    if (cliName === "cpu")
+        return all(METRIC_LABELS.cpu, extras);
+    if (cliName === "memory")
+        return all(METRIC_LABELS.memory, extras);
+    // 兜底：CLI 名直接作为 metric name + label
+    return single(cliName, cliName, extras);
+}
+function single(metricName, label, extras) {
+    return {
+        metricNames: [metricName],
+        labelByMetric: { [metricName]: label },
+        extraFilters: extras,
+    };
+}
+function all(labelByMetric, extras) {
+    return {
+        metricNames: Object.keys(labelByMetric),
+        labelByMetric,
+        extraFilters: extras,
+    };
+}