@lark-apaas/miaoda-cli 0.1.2 → 0.1.3-alpha.2a09432

package/dist/cli/handlers/file/ls.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");
 /**
  * 把位置参数 `query` 路由到 `--path` 或 `--name`：
@@ -56,7 +55,7 @@ function resolveQueryRouting(opts) {
     if (!opts.query)
         return explicit;
     if (explicit.path || explicit.name) {
-        throw new error_1.AppError("ARGS_INVALID", "Do not mix positional <query> with --path / --name; pick one.");
+        throw new error_1.AppError('ARGS_INVALID', 'Do not mix positional <query> with --path / --name; pick one.');
     }
     if ((0, index_1.looksLikePath)(opts.query)) {
         // 补齐前导 `/`，对齐 ls sidecar 比较逻辑（info.path 永远带前导 `/`）
@@ -65,7 +64,7 @@ function resolveQueryRouting(opts) {
     return { name: opts.query };
 }
 async function handleFileLs(opts) {
-    const appId = (0, shared_1.resolveAppId)(opts);
+    const appId = opts.appId;
     // commander 已经把 --limit 解析为 number；保留 ?? undefined 兼容老调用
     const limit = opts.limit;
     const sizeGt = opts.sizeGt ? (0, render_1.parseSize)(opts.sizeGt) : undefined;
@@ -89,13 +88,13 @@ async function handleFileLs(opts) {
         return;
     }
     if (result.items.length === 0) {
-        (0, output_1.emit)("No files found.");
+        (0, output_1.emit)('No files found.');
         return;
     }
     const tty = (0, render_1.isStdoutTty)();
-    const headers = ["file_name", "path", "size", "type", "uploaded_at"];
+    const headers = ['file_name', 'path', 'size', 'type', 'uploaded_at'];
     const rows = result.items.map((info) => [
-        info.file_name || "—",
+        info.file_name || '—',
         info.path,
         tty ? (0, render_1.formatSize)(info.size_bytes) : String(info.size_bytes),
         info.type,
@@ -104,6 +103,6 @@ async function handleFileLs(opts) {
     const table = tty ? (0, render_1.renderAlignedTable)(headers, rows) : (0, render_1.renderTsv)(headers, rows);
     const hint = result.has_more && result.next_cursor
         ? `\n— ${String(result.items.length)} results. Next: --cursor ${result.next_cursor}`
-        : "";
+        : '';
     (0, output_1.emit)(table + hint);
 }

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

@@ -0,0 +1,66 @@
+"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.handleFileQuota = handleFileQuota;
+const api = __importStar(require("../../../api/index"));
+const shared_1 = require("../../../cli/commands/shared");
+const output_1 = require("../../../utils/output");
+const render_1 = require("../../../utils/render");
+async function handleFileQuota(opts) {
+    const appId = (0, shared_1.resolveAppId)(opts);
+    const data = await api.file.getStorageQuota({ appId });
+    if ((0, output_1.isJsonMode)()) {
+        // 配额未对接（storageQuotaBytes=0）时，quota / usage_percent 字段都不输出
+        const out = {
+            storageUsedBytes: data.storageUsedBytes,
+            files: data.files,
+        };
+        if (data.storageQuotaBytes > 0) {
+            out.storageQuotaBytes = data.storageQuotaBytes;
+            out.usagePercent = data.usagePercent;
+        }
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)(out));
+        return;
+    }
+    // PRD：单行 "Storage: 150 MB / 1 GB (15%)"；配额未对接时只显示 used
+    const tty = (0, render_1.isStdoutTty)();
+    const storageLine = data.storageQuotaBytes > 0
+        ? `${(0, render_1.formatSize)(data.storageUsedBytes)} / ${(0, render_1.formatSize)(data.storageQuotaBytes)} (${data.usagePercent.toFixed(1)}%)`
+        : (0, render_1.formatSize)(data.storageUsedBytes);
+    (0, output_1.emit)((0, render_1.renderKeyValue)([
+        ['Storage', storageLine],
+        ['Files', String(data.files)],
+    ], tty));
+}

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");
@@ -74,7 +73,7 @@ async function resolveDeleteInputs(appId, paths, names) {
     // 1a. path 分支：直接进删除队列，file_name 取 basename 先占位
     for (const p of positionalAsPath) {
         const abs = (0, index_1.toAbsolutePath)(p);
-        const basename = abs.split("/").pop() ?? abs;
+        const basename = abs.split('/').pop() ?? abs;
         resolved.push({ input: p, path: abs, file_name: basename });
     }
     // 1b. name 分支（来自位置参数的非 path）：和 --name 合并走 resolveInputs
@@ -83,10 +82,10 @@ async function resolveDeleteInputs(appId, paths, names) {
         const results = await api.file.resolveInputs({
             appId,
             inputs: allNames,
-            forceAs: "name",
+            forceAs: 'name',
         });
         for (const r of results) {
-            if (r.status === "ok") {
+            if (r.status === 'ok') {
                 resolved.push({
                     input: r.input,
                     path: r.file.path,
@@ -95,7 +94,7 @@ async function resolveDeleteInputs(appId, paths, names) {
             }
             else {
                 errors.push({
-                    status: "error",
+                    status: 'error',
                     input: r.input,
                     error: r.error,
                 });
@@ -120,7 +119,7 @@ async function confirm(count, firstInput) {
         const prompt = count === 1 ? `? Delete '${firstInput}'? (y/N) ` : `? Delete ${String(count)} files? (y/N) `;
         rl.question(prompt, (answer) => {
             rl.close();
-            resolve(answer.trim().toLowerCase() === "y");
+            resolve(answer.trim().toLowerCase() === 'y');
         });
     });
 }
@@ -128,12 +127,12 @@ async function handleFileRm(paths, opts) {
     const names = opts.name ?? [];
     const totalCount = paths.length + names.length;
     if (totalCount === 0) {
-        throw new error_1.AppError("ARGS_INVALID", "No file specified (give a /path or --name <name>)");
+        throw new error_1.AppError('ARGS_INVALID', 'No file specified (give a /path or --name <name>)');
     }
     if (totalCount > MAX_BATCH) {
-        throw new error_1.AppError("FILE_BATCH_TOO_MANY", `Batch size ${String(totalCount)} exceeds the 100 limit`);
+        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) {
@@ -142,11 +141,11 @@ async function handleFileRm(paths, opts) {
         const firstInput = paths.length > 0 ? paths[0] : names[0];
         const ok = await confirm(totalCount, firstInput);
         if (!ok) {
-            throw new error_1.AppError("DESTRUCTIVE_CANCELLED", "Cancelled by user");
+            throw new error_1.AppError('DESTRUCTIVE_CANCELLED', 'Cancelled by user');
         }
     }
     else if (!tty && !opts.yes) {
-        throw new error_1.AppError("DESTRUCTIVE_REQUIRES_CONFIRM", "This operation is destructive. Rerun with --yes to confirm.");
+        throw new error_1.AppError('DESTRUCTIVE_REQUIRES_CONFIRM', 'This operation is destructive. Rerun with --yes to confirm.');
     }
     const { resolved, errors } = await resolveDeleteInputs(appId, paths, names);
     // path → entry 映射（用于 delete 响应归档回原始 input 和 file_name）
@@ -168,9 +167,9 @@ async function handleFileRm(paths, opts) {
         for (const p of deleted) {
             const entry = pathToEntry.get(p);
             results.push({
-                status: "ok",
+                status: 'ok',
                 input: entry?.input ?? p,
-                file_name: entry?.file_name ?? p.split("/").pop() ?? p,
+                file_name: entry?.file_name ?? p.split('/').pop() ?? p,
                 path: p,
             });
         }
@@ -182,31 +181,31 @@ async function handleFileRm(paths, opts) {
                 await api.file.statFile({ appId, filePath: f.path });
                 return {
                     input,
-                    code: "INTERNAL_ERROR",
-                    message: "Delete request returned success but file still exists (server-side issue)",
+                    code: 'INTERNAL_ERROR',
+                    message: 'Delete request returned success but file still exists (server-side issue)',
                     hint: undefined,
                 };
             }
             catch (err) {
-                if (err instanceof error_1.AppError && err.code === "FILE_NOT_FOUND") {
+                if (err instanceof error_1.AppError && err.code === 'FILE_NOT_FOUND') {
                     return {
                         input,
-                        code: "FILE_NOT_FOUND",
+                        code: 'FILE_NOT_FOUND',
                         message: `File '${input}' does not exist at delete time`,
-                        hint: "Run `miaoda file ls` to see available files.",
+                        hint: 'Run `miaoda file ls` to see available files.',
                     };
                 }
                 return {
                     input,
-                    code: "INTERNAL_ERROR",
-                    message: err instanceof Error ? err.message : "verification failed",
+                    code: 'INTERNAL_ERROR',
+                    message: err instanceof Error ? err.message : 'verification failed',
                     hint: undefined,
                 };
             }
         }));
         for (const c of classified) {
             results.push({
-                status: "error",
+                status: 'error',
                 input: c.input,
                 error: c.hint
                     ? { code: c.code, message: c.message, hint: c.hint }
@@ -220,7 +219,7 @@ async function handleFileRm(paths, opts) {
     names.forEach((n, i) => orderIndex.set(n, paths.length + i));
     results = results.sort((a, b) => (orderIndex.get(a.input) ?? Number.MAX_SAFE_INTEGER) -
         (orderIndex.get(b.input) ?? Number.MAX_SAFE_INTEGER));
-    const okCount = results.filter((r) => r.status === "ok").length;
+    const okCount = results.filter((r) => r.status === 'ok').length;
     const failCount = results.length - okCount;
     if ((0, output_1.isJsonMode)()) {
         (0, output_1.emit)({ data: results });
@@ -228,7 +227,7 @@ async function handleFileRm(paths, opts) {
     else if (tty) {
         const lines = [];
         for (const r of results) {
-            if (r.status === "ok")
+            if (r.status === 'ok')
                 lines.push(colors_1.c.success(`✓ Deleted ${r.input}`));
             else
                 lines.push(colors_1.c.fail(`✗ ${r.input}: ${r.error.message}`));
@@ -239,12 +238,12 @@ async function handleFileRm(paths, opts) {
         else {
             lines.push(`Deleted ${String(okCount)} of ${String(totalCount)} files (${String(failCount)} failed)`);
         }
-        (0, output_1.emit)(lines.join("\n"));
+        (0, output_1.emit)(lines.join('\n'));
     }
     else {
         const lines = [];
         for (const r of results) {
-            if (r.status === "ok")
+            if (r.status === 'ok')
                 lines.push(`OK\t${r.input}`);
             else
                 lines.push(`FAIL\t${r.input}\t${r.error.message}`);
@@ -255,7 +254,7 @@ async function handleFileRm(paths, opts) {
         else {
             lines.push(`Deleted ${String(okCount)} of ${String(totalCount)} files (${String(failCount)} failed)`);
         }
-        (0, output_1.emit)(lines.join("\n"));
+        (0, output_1.emit)(lines.join('\n'));
     }
     // 退出码：任一失败 → 1；全成功 → 0
     if (failCount > 0) {

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 规定）
@@ -54,9 +53,9 @@ async function resolveFilePath(appId, input) {
     const [resolved] = await api.file.resolveInputs({
         appId,
         inputs: [input],
-        forceAs: "name",
+        forceAs: 'name',
     });
-    if (resolved.status === "error") {
+    if (resolved.status === 'error') {
         throw new error_1.AppError(resolved.error.code, resolved.error.message, {
             next_actions: resolved.error.hint ? [resolved.error.hint] : undefined,
         });
@@ -64,12 +63,12 @@ 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);
         if (expiresSec > MAX_EXPIRES_SECONDS) {
-            throw new error_1.AppError("FILE_SIGN_DURATION_EXCEEDED", `Expires duration '${opts.expires}' exceeds the maximum of 30d`, {
+            throw new error_1.AppError('FILE_SIGN_DURATION_EXCEEDED', `Expires duration '${opts.expires}' exceeds the maximum of 30d`, {
                 next_actions: [
                     `Maximum allowed value is 30d. Use \`--expires 30d\` for the longest link.`,
                 ],

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。
@@ -53,9 +52,9 @@ async function resolveFile(appId, input) {
     const [resolved] = await api.file.resolveInputs({
         appId,
         inputs: [input],
-        forceAs: "name",
+        forceAs: 'name',
     });
-    if (resolved.status === "error") {
+    if (resolved.status === 'error') {
         throw new error_1.AppError(resolved.error.code, resolved.error.message, {
             next_actions: resolved.error.hint ? [resolved.error.hint] : undefined,
         });
@@ -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);
@@ -75,23 +74,24 @@ async function handleFileStat(file, opts) {
     }
     const tty = (0, render_1.isStdoutTty)();
     const pairs = [
-        ["file_name", info.file_name || "—"],
-        ["path", info.path],
+        ['file_name', info.file_name || '—'],
+        ['path', info.path],
         [
-            "size",
+            'size',
             tty
                 ? `${(0, render_1.formatSize)(info.size_bytes)} (${String(info.size_bytes)} bytes)`
                 : String(info.size_bytes),
         ],
-        ["type", info.type || "—"],
-        ["uploaded_at", (0, render_1.formatTime)(info.uploaded_at, tty)],
+        ['type', info.type || '—'],
+        ['uploaded_at', (0, render_1.formatTime)(info.uploaded_at, tty)],
     ];
     if (info.uploaded_by) {
+        // pretty 模式只展示 name；id 仅在 --json 下保留（避免 TTY 输出冒出一长串 userID）。
         // uploaded_by 紧跟 uploaded_at 前插入（index = "uploaded_at" 之前）
-        pairs.splice(pairs.length - 1, 0, ["uploaded_by", info.uploaded_by]);
+        pairs.splice(pairs.length - 1, 0, ['uploaded_by', info.uploaded_by.name]);
     }
     if (info.download_url) {
-        pairs.push(["download_url", info.download_url]);
+        pairs.push(['download_url', info.download_url]);
     }
     (0, output_1.emit)((0, render_1.renderKeyValue)(pairs, tty));
 }

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;
+}