@lark-apaas/miaoda-cli 0.1.2 → 0.1.3-alpha.09899c4

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,
                 });
@@ -105,11 +104,11 @@ async function resolveDeleteInputs(appId, paths, names) {
     return { resolved, errors };
 }
 /**
- * 删除前 TTY 二次确认。
- * PRD 单文件场景下提示带具体路径：`? Delete '/path'? (y/N)`，
- * 多文件场景汇总条数：`? Delete N files? (y/N)`。
- * `firstInput` 是用户传入的第一个值（可能是 path 或 file_name），
- * 单文件时直接展示给用户，方便核对目标。
+ * 删除前 TTY 二次确认。文案强调"permanently"（删除不可撤销，无回收站）：
+ *   - 单文件：`? Are you sure you want to permanently delete '<input>'? (y/N)`
+ *   - 多文件：`? Are you sure you want to permanently delete N files? (y/N)`
+ * `firstInput` 是用户传入的第一个值（path 或 file_name），单文件时直接展示给
+ * 用户核对目标。
  */
 async function confirm(count, firstInput) {
     const rl = node_readline_1.default.createInterface({
@@ -117,10 +116,12 @@ async function confirm(count, firstInput) {
         output: process.stderr,
     });
     return new Promise((resolve) => {
-        const prompt = count === 1 ? `? Delete '${firstInput}'? (y/N) ` : `? Delete ${String(count)} files? (y/N) `;
+        const prompt = count === 1
+            ? `? Are you sure you want to permanently delete '${firstInput}'? (y/N) `
+            : `? Are you sure you want to permanently delete ${String(count)} files? (y/N) `;
         rl.question(prompt, (answer) => {
             rl.close();
-            resolve(answer.trim().toLowerCase() === "y");
+            resolve(answer.trim().toLowerCase() === 'y');
         });
     });
 }
@@ -128,12 +129,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 +143,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 +169,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 +183,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 +221,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 +229,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 +240,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 +256,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;
+}

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