@lark-apaas/miaoda-cli 0.1.2-alpha.c7d0c89 → 0.1.2-alpha.ccfdc05

package/README.md

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

package/dist/api/deploy/schemas.js

@@ -97,7 +97,7 @@ exports.errorJobSchema = {
     columns: [
         { key: "jobID", label: "job-id" },
         { key: "componentName", label: "component" },
-        { key: "errorMsg", label: "error", format: output_1.fmt.truncate(120) },
+        { key: "errorMsg", label: "error" },
     ],
     strict: true,
 };

package/dist/api/observability/schemas.js

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

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

@@ -6,9 +6,13 @@ const shared_1 = require("../../../cli/commands/shared");
 const index_1 = require("../../../cli/handlers/deploy/index");
 const COMMON_TIME_HELP = `
 时间格式：
-  - 相对时间：1h（1 小时前）、2d（2 天前）、1w（1 周前）、30m（30 分钟前）
-  - 日期：2026-04-01（按当日 00:00:00 UTC）
-  - ISO 8601：2026-04-01T10:00:00Z
+  - 相对时间：30m（30 分钟前）、1h、2d、1w
+  - 日期：2026-04-01（本地时区当日 00:00:00）
+  - 本地日期+时间：2026-04-01T10:00:00（按本地时区，T 分隔）
+  - 带时区 ISO：2026-04-01T10:00:00Z（UTC）或 2026-04-01T10:00:00+08:00（指定偏移）
+  备注：
+    1) 不带时区的形式与 pretty 输出闭环（同机器复制粘贴稳定）；跨机器请带显式时区。
+    2) 必须用 T 分隔日期与时间，禁止空格——shell 会把不带引号的 'YYYY-MM-DD HH:mm:ss' 拆成两个参数。
 `;
 function registerDeployCommands(program) {
     // PRD：`miaoda deploy` 自身即为触发发布；get / history / error-log 是子命令
@@ -20,6 +24,12 @@ function registerDeployCommands(program) {
         .option("--wait", "阻塞直到流水线终态", false)
         .option("--timeout <sec>", "--wait 最长等待秒数（默认 300）", parseTimeout, 300)
         .addHelpText("after", `
+部署前置检查（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 终态）
@@ -70,14 +80,9 @@ function registerDeployHistory(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",
-    ]))
+        .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)
@@ -91,6 +96,7 @@ JSON 输出
   $ miaoda deploy history --since 7d
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
+        (0, shared_1.validateTimeOptions)(rawOpts, "since", "until");
         (0, shared_1.rejectCliOverride)(cmd, "appId");
         await (0, index_1.handleDeployHistory)({
             appId: rawOpts.appId,

package/dist/cli/commands/index.js

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

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

@@ -6,9 +6,13 @@ const shared_1 = require("../../../cli/commands/shared");
 const index_1 = require("../../../cli/handlers/observability/index");
 const COMMON_TIME_HELP = `
 时间格式：
-  - 相对时间：1h（1 小时前）、2d（2 天前）、1w（1 周前）、30m（30 分钟前）
-  - 日期：2026-04-01（按当日 00:00:00 UTC）
-  - ISO 8601：2026-04-01T10:00:00Z
+  - 相对时间：30m（30 分钟前）、1h、2d、1w
+  - 日期：2026-04-01（本地时区当日 00:00:00）
+  - 本地日期+时间：2026-04-01T10:00:00（按本地时区，T 分隔）
+  - 带时区 ISO：2026-04-01T10:00:00Z（UTC）或 2026-04-01T10:00:00+08:00（指定偏移）
+  备注：
+    1) 不带时区的形式与 pretty 输出闭环（同机器复制粘贴稳定）；跨机器请带显式时区。
+    2) 必须用 T 分隔日期与时间，禁止空格——shell 会把不带引号的 'YYYY-MM-DD HH:mm:ss' 拆成两个参数。
 `;
 function registerObservabilityCommands(program) {
     const obCmd = program
@@ -23,8 +27,7 @@ function registerObservabilityCommands(program) {
   应用上下文：--app-id <id> 或环境变量 MIAODA_APP_ID。
 
 应用环境
-  log/trace 命令需要 --env <dev|online>，默认 online，可设置 MIAODA_APP_ENV 覆盖。
-  metric/analytics 不需要 --env。
+  目前只支持线上环境。
 `);
     registerLog(obCmd);
     registerTrace(obCmd);
@@ -37,7 +40,9 @@ function registerLog(parent) {
         .command("log")
         .description("查询线上运行日志（按时间倒序，分页）")
         .addOption((0, shared_1.appIdOption)().hideHelp())
-        .addOption(new commander_1.Option("--level <level>", "日志级别").choices(["DEBUG", "INFO", "WARN", "ERROR"]))
+        .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("--trace-id <id>", "按 trace ID 过滤")
@@ -60,6 +65,7 @@ JSON 输出
   $ miaoda observability log --api /api/orders --min-duration 200 --json
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
+        (0, shared_1.validateTimeOptions)(rawOpts, "since", "until");
         (0, shared_1.rejectCliOverride)(cmd, "appId");
         await (0, index_1.handleObservabilityLog)({
             appId: rawOpts.appId,
@@ -105,6 +111,7 @@ JSON 输出
   $ miaoda observability trace list --root-span api-gateway --limit 20 --json
 `);
     listCmd.action((0, shared_1.withHelp)(listCmd, async (rawOpts) => {
+        (0, shared_1.validateTimeOptions)(rawOpts, "since", "until");
         (0, shared_1.rejectCliOverride)(listCmd, "appId");
         await (0, index_1.handleObservabilityTraceList)({
             appId: rawOpts.appId,
@@ -156,9 +163,10 @@ function registerMetric(parent) {
         .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天）")
+        .addOption(new commander_1.Option("--down-sample <duration>", "降采样粒度（1m=1分钟 / 1h=1小时 / 1d=1天，大小写不敏感）")
         .choices(["1m", "1h", "1d"])
-        .default("1h"))
+        .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}
@@ -170,6 +178,7 @@ 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,
@@ -191,7 +200,7 @@ function registerAnalytics(parent) {
         .argument("<analytics-name>", "指标名：users | page-view")
         .addOption((0, shared_1.appIdOption)().hideHelp())
         .option("--page <path>", "按页面路径过滤（仅对 page-view 生效）")
-        .option("--series <name>", "过滤图表中的某条线：users 取 active-users/new-users/total-users；page-view 取 all-view/desktop-view/mobile-view；缺省返回所有相关线")
+        .option("--series <name>", "过滤图表中的某条线：users 取 active/new/total（兼容 active-users/new-users/total-users）；page-view 取 all/desktop/mobile（兼容 all-view/desktop-view/mobile-view）")
         .option("--since <time>", "开始时间")
         .option("--until <time>", "截止时间")
         .option("--granularity <duration>", "时间粒度：day | week | month", "day")
@@ -201,10 +210,11 @@ JSON 输出
 
 示例
   $ miaoda observability analytics users --json                      # 同时返回 active/new/total 三条线
-  $ miaoda observability analytics users --series new-users --since 7d --json
+  $ miaoda observability analytics users --series new --since 7d --json
   $ miaoda observability analytics page-view --granularity week --json
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (analyticsName, rawOpts) => {
+        (0, shared_1.validateTimeOptions)(rawOpts, "since", "until");
         (0, shared_1.rejectCliOverride)(cmd, "appId");
         await (0, index_1.handleObservabilityAnalytics)({
             analyticsName,

package/dist/cli/commands/shared.js

@@ -6,9 +6,12 @@ exports.softRequiredOption = softRequiredOption;
 exports.resolveAppId = resolveAppId;
 exports.withHelp = withHelp;
 exports.failArgs = failArgs;
+exports.caseInsensitiveChoice = caseInsensitiveChoice;
+exports.validateTimeOptions = validateTimeOptions;
 exports.rejectCliOverride = rejectCliOverride;
 const commander_1 = require("commander");
 const error_1 = require("../../utils/error");
+const time_1 = require("../../utils/time");
 /** --app-id option，需要应用上下文的命令自行 .addOption(appIdOption()) */
 function appIdOption() {
     return new commander_1.Option("--app-id <id>", "指定目标应用").env("MIAODA_APP_ID");
@@ -62,6 +65,47 @@ function withHelp(cmd, handler) {
 function failArgs(message) {
     throw new error_1.AppError("ARGS_INVALID", message);
 }
+/**
+ * 大小写不敏感的 choice argParser：把用户输入按 lowerCase 匹配回 canonical 数组里
+ * 的同名值（保留 canonical 大小写），未命中抛 Commander 的 InvalidArgumentError
+ * （exit code 1，自带友好错误）。
+ *
+ * 必须先 .choices(canonical)、再 .argParser()——Commander 内部 .choices() 会
+ * 重置 parseArg，反过来调会让 argParser 失效。.choices() 仅留给 help 渲染
+ * "choices: A, B, C"，实际白名单校验由 argParser 接管。
+ *
+ *   new Option("--level <level>", "日志级别（不区分大小写）")
+ *     .choices(["DEBUG", "INFO", "WARN", "ERROR"])
+ *     .argParser(caseInsensitiveChoice(["DEBUG", "INFO", "WARN", "ERROR"]));
+ */
+function caseInsensitiveChoice(canonical) {
+    const map = new Map(canonical.map((v) => [v.toLowerCase(), v]));
+    return (raw) => {
+        const hit = map.get(raw.toLowerCase());
+        if (hit === undefined) {
+            throw new commander_1.InvalidArgumentError(`Allowed choices are ${canonical.join(", ")} (case-insensitive).`);
+        }
+        return hit;
+    };
+}
+/**
+ * --since / --until 等时间参数的 action 阶段校验。
+ *
+ * Commander 的 argParser 会在 action 前直接按 parser error 退出（exit 1），
+ * 绕过 withHelp 的 ARGS_INVALID → exit 2 路径；所以时间参数在 action 内先
+ * 校验一遍，再把原始字符串交给 handler 解析成接口需要的单位。
+ */
+function validateTimeOptions(opts, ...names) {
+    for (const name of names) {
+        const value = opts[name];
+        if (value === undefined)
+            continue;
+        if (typeof value !== "string") {
+            failArgs(`--${name.replace(/([A-Z])/g, "-$1").toLowerCase()} 必须是时间字符串`);
+        }
+        (0, time_1.parseTimeToMs)(value);
+    }
+}
 /**
  * 拒绝 CLI 显式覆盖：用于 hideHelp() + .env() 的"沙箱注入参数"（如 --app-id / --branch）。
  *

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

@@ -149,22 +149,23 @@ function buildAnalyticsPivotSchema(seriesLabels) {
  */
 function resolveAnalyticsSelection(cliName, series) {
     const extras = [];
+    const normalizedSeries = normalizeAnalyticsSeries(cliName, series);
     if (cliName === "users") {
-        if (series === "active-users")
+        if (normalizedSeries === "active-users")
             return single("ACTIVE_USER", "active-users", extras);
-        if (series === "new-users")
+        if (normalizedSeries === "new-users")
             return single("NEW_USER", "new-users", extras);
-        if (series === "total-users")
+        if (normalizedSeries === "total-users")
             return single("TOTAL_USER", "total-users", extras);
         // 缺省：三条线
         return all(ANALYTICS_LABELS.users, extras);
     }
     if (cliName === "page-view") {
-        if (series === "desktop-view") {
+        if (normalizedSeries === "desktop-view") {
             extras.push({ key: "device_type", value: (0, helpers_1.eqFilter)("desktop") });
             return single("PAGE_VIEW", "desktop-view", extras);
         }
-        if (series === "mobile-view") {
+        if (normalizedSeries === "mobile-view") {
             extras.push({ key: "device_type", value: (0, helpers_1.eqFilter)("mobile") });
             return single("PAGE_VIEW", "mobile-view", extras);
         }
@@ -174,6 +175,27 @@ function resolveAnalyticsSelection(cliName, series) {
     // 兜底：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],

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

@@ -71,7 +71,7 @@ async function handleObservabilityMetric(opts) {
     ]);
     // since/until 直接以秒透传到 BAM；当前未做桶对齐（如需开启把 until
     // 用 ceilMsToBucket(untilMs, downSample as GranularityBucket) 包一层即可）。
-    const downSample = opts.downSample ?? "1h";
+    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;

package/dist/cli/version.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRootVersionArg = resolveRootVersionArg;
+function resolveRootVersionArg(args) {
+    if (args.length === 1 && (args[0] === "-v" || args[0] === "--version"))
+        return "show";
+    if (args.some(isLooseVersionArg))
+        return "invalid-variant";
+    if (args.includes("-v") || args.includes("--version"))
+        return "invalid-placement";
+    return "none";
+}
+function isLooseVersionArg(arg) {
+    return ((arg.startsWith("-v") && arg !== "-v") || (arg.startsWith("--version") && arg !== "--version"));
+}

package/dist/main.js

@@ -5,10 +5,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const index_1 = require("./cli/commands/index");
+const shared_1 = require("./cli/commands/shared");
 const help_1 = require("./cli/help");
 const config_1 = require("./utils/config");
 const log_id_1 = require("./utils/log_id");
 const output_1 = require("./utils/output");
+const error_1 = require("./utils/error");
+const version_1 = require("./cli/version");
 const package_json_1 = __importDefault(require("../package.json"));
 // MiaodaHelp 对齐 CLI 规范（描述置顶 / Flags / Global Flags / 段顺序）：
 // 在 Command.prototype 上 patch createHelp，让所有命令实例（含动态注册的
@@ -20,11 +23,14 @@ const program = new commander_1.Command();
 const { version } = package_json_1.default;
 program
     .name("miaoda")
-    .description("妙搭平台 CLI，提供数据服务、文件存储、插件管理等命令行操作。")
+    .description("妙搭平台 CLI，提供数据服务、文件存储等命令行操作。")
     .usage("<command> [flags]")
-    .version(version, "-v, --version", "显示版本号")
+    .option("-v, --version", "显示版本号")
     .option("--json [fields]", "JSON 输出，可选字段级选择")
-    .option("--output <format>", "输出格式（pretty|json）", "pretty")
+    .addOption(new commander_1.Option("--output <format>", "输出格式（pretty | json，大小写不敏感）")
+    .choices(["pretty", "json"])
+    .argParser((0, shared_1.caseInsensitiveChoice)(["pretty", "json"]))
+    .default("pretty"))
     .option("--verbose", "debug 日志到 stderr")
     .helpOption("-h, --help", "显示帮助信息")
     .hook("preAction", (_thisCmd, actionCmd) => {
@@ -33,7 +39,21 @@ program
     (0, config_1.initConfigFromOpts)(opts);
 });
 (0, index_1.registerCommands)(program);
-program.parseAsync(process.argv).catch((err) => {
-    (0, output_1.emitError)(err);
-    process.exitCode = 1;
-});
+const versionArg = (0, version_1.resolveRootVersionArg)(process.argv.slice(2));
+if (versionArg === "show") {
+    process.stdout.write(`${version}\n`);
+}
+else if (versionArg === "invalid-variant") {
+    (0, output_1.emitError)(new error_1.AppError("ARGS_INVALID", "版本参数仅支持精确的 -v 或 --version"));
+    process.exitCode = 2;
+}
+else if (versionArg === "invalid-placement") {
+    (0, output_1.emitError)(new error_1.AppError("ARGS_INVALID", "-v / --version 仅可在根命令单独使用，不能与其他命令或参数混用"));
+    process.exitCode = 2;
+}
+else {
+    program.parseAsync(process.argv).catch((err) => {
+        (0, output_1.emitError)(err);
+        process.exitCode = 1;
+    });
+}

package/dist/utils/http.js

@@ -10,6 +10,8 @@ exports.postInnerApi = postInnerApi;
 exports.getInnerApi = getInnerApi;
 const http_client_1 = require("@lark-apaas/http-client");
 const error_1 = require("./error");
+const config_1 = require("./config");
+const logger_1 = require("./logger");
 let adminClient;
 let runtimeClient;
 /**
@@ -70,11 +72,31 @@ function applyCanaryHeader(reqConfig) {
 }
 /** 走管理端 innerapi 的 POST + 信封解析 */
 async function postInnerApi(url, body, opts) {
-    return handleInnerEnvelope(await getHttpClient().post(url, body), url, opts);
+    const startMs = logRequestStart("POST", url, body);
+    let response;
+    try {
+        response = await getHttpClient().post(url, body);
+    }
+    catch (err) {
+        logResponseFailure("POST", url, err, startMs);
+        throw err;
+    }
+    logResponseEnd("POST", url, response, startMs);
+    return handleInnerEnvelope(response, url, opts);
 }
 /** 走管理端 innerapi 的 GET + 信封解析 */
 async function getInnerApi(url, opts) {
-    return handleInnerEnvelope(await getHttpClient().get(url), url, opts);
+    const startMs = logRequestStart("GET", url);
+    let response;
+    try {
+        response = await getHttpClient().get(url);
+    }
+    catch (err) {
+        logResponseFailure("GET", url, err, startMs);
+        throw err;
+    }
+    logResponseEnd("GET", url, response, startMs);
+    return handleInnerEnvelope(response, url, opts);
 }
 async function handleInnerEnvelope(response, url, opts) {
     if (!response.ok) {
@@ -85,6 +107,10 @@ async function handleInnerEnvelope(response, url, opts) {
         const env = result;
         if (env.status_code !== undefined && env.status_code !== "0") {
             const msg = env.message ?? env.error_msg ?? "unknown error";
+            // verbose: 把完整业务错误信封打到 stderr，便于追溯
+            if ((0, config_1.getConfig)().verbose) {
+                (0, logger_1.debug)(`  envelope: ${truncateForLog(safeStringify(env), 1000)}`);
+            }
             const mapped = opts.mapErr?.(env.status_code, msg);
             if (mapped)
                 throw mapped;
@@ -97,3 +123,63 @@ async function handleInnerEnvelope(response, url, opts) {
     }
     return result;
 }
+// ── verbose 调试日志 ────────────
+//
+// 仅作用于 inner-api 链路（postInnerApi / getInnerApi），即 app / deploy /
+// observability 三个域。--verbose 关闭时所有 helper 都直接退出，零开销。
+function logRequestStart(method, url, body) {
+    const startMs = Date.now();
+    if (!(0, config_1.getConfig)().verbose)
+        return startMs;
+    (0, logger_1.debug)(`→ ${method} ${url}`);
+    if (body !== undefined) {
+        (0, logger_1.debug)(`  body: ${truncateForLog(safeStringify(body), 1000)}`);
+    }
+    return startMs;
+}
+function logResponseEnd(method, url, response, startMs) {
+    if (!(0, config_1.getConfig)().verbose)
+        return;
+    const elapsedMs = Date.now() - startMs;
+    const logid = pickLogid(response.headers);
+    const tail = logid ? ` logid=${logid}` : "";
+    (0, logger_1.debug)(`← ${method} ${url} ${String(response.status)} ${String(elapsedMs)}ms${tail}`);
+}
+/**
+ * http-client 在 4xx/5xx / 网络错误时直接 reject（不返回 Response）；
+ * 这条路径下 logResponseEnd 不会跑——这里专门补一行，尽可能从 HttpError
+ * 上抠出 status / logid，让 verbose 仍能看到失败请求的关键信息。
+ */
+function logResponseFailure(method, url, err, startMs) {
+    if (!(0, config_1.getConfig)().verbose)
+        return;
+    const elapsedMs = Date.now() - startMs;
+    // @lark-apaas/http-client 的 HttpError.response: Response | undefined
+    const e = err;
+    const status = e.response?.status;
+    const logid = e.response?.headers ? pickLogid(e.response.headers) : null;
+    const statusPart = status !== undefined ? String(status) : "ERR";
+    const logidPart = logid ? ` logid=${logid}` : "";
+    const msgPart = e.message ? ` (${e.message})` : "";
+    (0, logger_1.debug)(`✗ ${method} ${url} ${statusPart} ${String(elapsedMs)}ms${logidPart}${msgPart}`);
+}
+/** BAM gateway 在不同 PSM/版本上 logid 落在不同 header；按命中顺序取第一个非空。 */
+function pickLogid(headers) {
+    return (headers.get("x-tt-logid") ??
+        headers.get("x-logid") ??
+        headers.get("logid") ??
+        headers.get("x-tt-trace-tag"));
+}
+function safeStringify(v) {
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+function truncateForLog(s, n) {
+    if (s.length <= n)
+        return s;
+    return `${s.slice(0, n)}...(truncated, ${String(s.length)} chars)`;
+}

package/dist/utils/time.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TIMESTAMP_HELP = void 0;
 exports.parseTimeToMs = parseTimeToMs;
 exports.msToNs = msToNs;
 exports.msToSec = msToSec;
@@ -9,16 +10,28 @@ exports.parseToSec = parseToSec;
 exports.floorMsToBucket = floorMsToBucket;
 exports.ceilMsToBucket = ceilMsToBucket;
 const error_1 = require("./error");
-const TIMESTAMP_HELP = "支持格式：相对时间 1h/2d/1w；日期 2026-04-01；ISO 2026-04-01T10:00:00Z";
+exports.TIMESTAMP_HELP = "支持格式：" +
+    "相对时间 30m/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（指定偏移）。" +
+    "禁止用空格分隔：'YYYY-MM-DD HH:mm:ss' 不带引号会被 shell 拆成两个参数。";
 /**
- * 解析 PRD 时间格式。返回毫秒时间戳。
- *   - 相对时间：`1h`、`2d`、`1w`、`30m`（h=小时, d=天, w=周, m=分钟）
- *   - 日期：`2026-04-01`（按当日 00:00:00 UTC）
- *   - ISO 8601：`2026-04-01T10:00:00Z`
+ * 解析时间字符串到毫秒时间戳；不匹配任一支持格式抛 ARGS_INVALID。
+ *
+ * 时区约定（重要）：
+ *   - 不带显式时区的形式（YYYY-MM-DD、YYYY-MM-DDTHH:mm:ss）一律按
+ *     **本地时区**解释，与 pretty 输出（output.ts:renderDate 用 getFullYear 等本地方法）形成
+ *     输入/输出闭环：用户复制输出文本作为 --since 不会差时区。
+ *   - 带显式时区（结尾 Z 或 ±HH:MM / ±HHMM）按显式时区解析，跨机器一致。
+ *   - 因此跨机器同步使用时建议带显式时区；同机器复制粘贴 pretty 输出更省事。
+ *
+ * 拒绝 Date.parse 松散接受的形式：YYYY/MM/DD、自然语言（'April 1 2026'）、单独年份等。
  *
  * 失败抛 AppError("ARGS_INVALID", ...)；CLI 层用 withHelp 自动转 exit 2 + help。
  */
 function parseTimeToMs(input, now = new Date()) {
+    // 1. 相对时间：30m / 1h / 2d / 1w
     const relative = /^(\d+)([mhdw])$/.exec(input);
     if (relative) {
         const n = Number(relative[1]);
@@ -32,19 +45,77 @@ function parseTimeToMs(input, now = new Date()) {
                     : /* w */ 604_800_000;
         return now.getTime() - n * factor;
     }
-    if (/^\d{4}-\d{2}-\d{2}$/.test(input)) {
-        const ms = Date.parse(input + "T00:00:00Z");
+    // 2. 纯日期：YYYY-MM-DD → 本地当日 00:00:00
+    const date = /^(\d{4})-(\d{2})-(\d{2})$/.exec(input);
+    if (date) {
+        return localDateMs(input, date[1], date[2], date[3], "00", "00", "00", "0");
+    }
+    // 3. 本地日期+时间：YYYY-MM-DDTHH:mm:ss[.SSS]（不带时区，T 分隔）。
+    //    不接受空格分隔——'YYYY-MM-DD HH:mm:ss' 不带引号会被 shell 拆成两个参数，
+    //    宁可不支持也不要让 agent 踩"看起来传了 since 实际只传了一半"的坑。
+    const localDt = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?$/.exec(input);
+    if (localDt) {
+        // capture 7 是可选 .SSS 组，运行时可能 undefined；TS lib 的 RegExp match 索引
+        // 类型把它标成 string，所以这里显式 cast 让 ?? 在 lint 视角下也"必要"。
+        const msPart = localDt[7] ?? "0";
+        return localDateMs(input, localDt[1], localDt[2], localDt[3], localDt[4], localDt[5], localDt[6], msPart);
+    }
+    // 4. 带显式时区的 ISO 8601：YYYY-MM-DDTHH:mm:ss[.SSS](Z|±HH:MM|±HHMM)
+    const iso = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,9})?(Z|[+-](\d{2}):?(\d{2}))$/.exec(input);
+    if (iso) {
+        validateDateTimeParts(input, iso[1], iso[2], iso[3], iso[4], iso[5], iso[6]);
+        if (iso[7] !== "Z")
+            validateOffset(input, iso[8], iso[9]);
+        const ms = Date.parse(input);
         if (Number.isNaN(ms))
             failInvalidTimestamp(input);
         return ms;
     }
-    const ms = Date.parse(input);
-    if (Number.isNaN(ms))
+    failInvalidTimestamp(input);
+}
+function localDateMs(input, y, mo, d, h, mi, s, msPart) {
+    validateDateTimeParts(input, y, mo, d, h, mi, s);
+    // 毫秒位补齐到 3 位再截断（"5" → 500，"12" → 120，"123" → 123）
+    const ms = Number(msPart.padEnd(3, "0").slice(0, 3));
+    const date = new Date(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s), ms);
+    if (date.getFullYear() !== Number(y) ||
+        date.getMonth() !== Number(mo) - 1 ||
+        date.getDate() !== Number(d) ||
+        date.getHours() !== Number(h) ||
+        date.getMinutes() !== Number(mi) ||
+        date.getSeconds() !== Number(s) ||
+        date.getMilliseconds() !== ms) {
+        failInvalidTimestamp(input);
+    }
+    return date.getTime();
+}
+function validateDateTimeParts(input, y, mo, d, h, mi, s) {
+    const year = Number(y);
+    const month = Number(mo);
+    const day = Number(d);
+    const hour = Number(h);
+    const minute = Number(mi);
+    const second = Number(s);
+    if (month < 1 || month > 12 || hour > 23 || minute > 59 || second > 59) {
+        failInvalidTimestamp(input);
+    }
+    const utc = new Date(Date.UTC(year, month - 1, day));
+    if (utc.getUTCFullYear() !== year ||
+        utc.getUTCMonth() !== month - 1 ||
+        utc.getUTCDate() !== day) {
+        failInvalidTimestamp(input);
+    }
+}
+function validateOffset(input, h, mi) {
+    if (h === undefined || mi === undefined)
+        failInvalidTimestamp(input);
+    const hour = Number(h);
+    const minute = Number(mi);
+    if (hour > 23 || minute > 59)
         failInvalidTimestamp(input);
-    return ms;
 }
 function failInvalidTimestamp(input) {
-    throw new error_1.AppError("ARGS_INVALID", `无法解析时间 '${input}'。${TIMESTAMP_HELP}`);
+    throw new error_1.AppError("ARGS_INVALID", `无法解析时间 '${input}'。${exports.TIMESTAMP_HELP}`);
 }
 /** 毫秒 → 纳秒（字符串，避免 JS Number 精度丢失） */
 function msToNs(ms) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.2-alpha.c7d0c89",
+  "version": "0.1.2-alpha.ccfdc05",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {