@guandata/guancli 1.0.56 → 1.0.57

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## @guandata/guancli 1.0.57 - 2026-09-09
+
+- 统一指标查询的 JSON 输入与输出契约，补充日期维度子类型和日期筛选示例，脚本处理更稳定。
+- `metric search` 支持按指标状态筛选。
+- 卡片预览会标注本次生效的筛选条件及来源，并支持 `FIRST_PICK`、`MAX` 运行态默认值和级联选择器。
+
 ## @guandata/guancli 1.0.56 - 2026-09-03
 
 - 指标查询默认按指标或查询列的格式配置展示数值，支持数值、货币、百分比、小数位、千分位、数量级和前后缀等格式。

package/README.md

@@ -43,6 +43,11 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.57
+
+- 统一指标查询 JSON 契约，补充日期维度与筛选示例，并支持按状态搜索指标。
+- 卡片预览会标注生效筛选及来源，支持运行态默认值和级联选择器。
+
 ### @guandata/guancli 1.0.56
 
 - 指标查询默认遵循指标或查询列的数值格式，覆盖货币、百分比、精度、千分位、数量级和前后缀。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guancli",
-  "version": "1.0.56",
+  "version": "1.0.57",
   "description": "观远 BI 命令行工具 - 通过 API 操作 ETL、数据集、页面、表单等资源，并提供 ChatBI 问数/洞察能力",
   "bin": {
     "guancli": "bin/run.js"
@@ -38,7 +38,7 @@
     "node": ">=14"
   },
   "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
   }
 }

package/skills/guancli/SKILL.md

@@ -54,7 +54,7 @@ guancli 是 BI 资源的**查询分析入口**，并支持 Form 表单填报 CRU
 6. 先判断资源类型：ETL 用 `etl`，数据集用 `ds`，页面/仪表板用 `page`，卡片用 `card`，表单填报用 `form`。
 7. 信息不全时先 `tree` 或 `search`，拿到 ID 后再 `get`；目录名能出现在 `ds tree`，不代表同词一定能命中 `ds search`。三棵 `tree` 都支持 `--max-depth N` / `--keyword 词`（客户环境目录树可达数千节点，全量输出会被截断，默认先 `--max-depth 2` 再按需加深）。
 8. 用户给的是业务目录名而不是数据集名时，先 `ds tree` 定位目录，再在目录内按真实表名搜索，或从已有 `page/card` 反查 `dsId`。
-9. 用户要求查询卡片数据，但没有说明是否沿用页面筛选上下文时，主动询问“是否应用该卡片关联筛选器的默认筛选条件”。用户确认后使用 `card preview <cd_id> --with-default-filters`；用户明确不要、已经给出筛选条件或已明确要求使用默认条件时，不重复询问。卡片属于多个页面时，根据报错列出的候选页面请用户确认，再传 `--page-id <pg_id>`。
+9. 用户要查看/分析某个页面（仪表板）上的卡片数据时，默认所见即所得：用 `card preview <cd_id> --with-default-filters` 应用页面筛选器默认值（含 FIRST_PICK / 日历 MAX 的运行态求值和级联），并把结果页脚 `筛选:` 行（stderr 也有同样说明）里的生效条件原样带进结论，标明数据是筛选后的而非全量；`筛选: 无（未应用页面筛选器默认值…）` 表示裸取数。用户明确不要页面筛选、或已自行给出筛选条件时才裸取数；报错“暂不支持”时如实告知该筛选器未生效，不要静默改成裸取数。卡片属于多个页面时，根据报错列出的候选页面请用户确认，再传 `--page-id <pg_id>`。
 
 ## 按需读取资料
 
@@ -144,15 +144,17 @@ guancli 在这条链路上只出只读的那一环：`guancli page search` / `pa
 ## 指标关键规则
 
 - **先按下面的命令契约生成，不要猜 shell、jq 或筛选语法**：
-  - `metric search/get/tree/query --json-envelope` 返回统一 envelope：先读取 `schemaVersion`、`resultMode` 和 `rowCount`；当前 canonical 契约版本为 `1.0`。`resultMode=inline` 时消费 `data`，`resultMode=file` 时读取 `path`。search/get 直接从后端字段构造稳定英文模型，核心字段包括 `id/name/status/type/description/dataset/dimensions/timeField/measureFields`，`status/type` 使用 `PUBLISHED/ATOMIC` 等机器枚举，不依赖中文展示 key；tree 使用 `id/name/type/children`。后端新增未知字段不会要求 CLI 同步修改，稳定必填字段缺失则明确失败。可选标量和对象的缺失或 `null` 统一省略；`dimensions/timeField/measureFields/customAttributes` 及 `accelerations[].priority` 区分缺失、`null`、空值或零值，`accelerations` 区分未查询与已知空数组，调用方不要把省略解释成已知为空。原 `-f json` 保持旧版对象/数组结构，供已有调用方兼容；envelope 版本由响应体中的 `schemaVersion` 演进，不新增 `json-v2` 一类输出格式。该参数不能与 `--raw`、非 JSON `-f` 或 stderr 输出目标同时使用。
+  - `metric search/get/tree/query -f json` 返回统一 envelope：先读取 `schemaVersion`、`resultMode` 和 `rowCount`；当前 canonical 契约版本为 `1.0`。`resultMode=inline` 时消费 `data`，`resultMode=file` 时读取 `path`。search/get 直接从后端字段构造稳定英文模型，核心字段包括 `id/name/status/type/description/dataset/dimensions/timeField/measureFields`，`status/type` 使用 `PUBLISHED/ATOMIC` 等机器枚举，不依赖中文展示 key；tree 使用 `id/name/type/children`。后端新增未知字段不会要求 CLI 同步修改，稳定必填字段缺失则明确失败。可选标量和对象的缺失或 `null` 统一省略；`dimensions/timeField/measureFields/customAttributes` 及 `accelerations[].priority` 区分缺失、`null`、空值或零值，`accelerations` 区分未查询与已知空数组，调用方不要把省略解释成已知为空。旧脚本按 `references/metric-json-migration.md` 迁移；envelope 版本由响应体中的 `schemaVersion` 演进，不新增 `json-v2` 一类输出格式。JSON envelope 不能输出到 stderr；`--raw` 单独返回后端原始协议。
   - `metric query --filter` 只接受 `EQ`、`NE`、`LT`、`LE`、`GT`、`GE`、`BT`、`IN`、`IS_NULL`、`NOT_NULL`、`CONTAINS`、`NOT_CONTAINS`、`STARTSWITH`、`NOT_STARTSWITH`、`ENDSWITH`、`NOT_ENDSWITH`，禁止使用 `=`、`>=`、`<=`。例如日期下界写 `--filter "日期 GE 2026-01-01"`。
-  - 必须解析的命令不得用 `2>/dev/null` 隐藏 stderr。不要用会让末端命令成功掩盖上游失败的管道；优先拆成“guancli 输出到文件 → 确认命令成功 → jq 读取文件”，必须使用管道时先启用 `set -o pipefail`。
+  - query 的业务列可以是中文，每个中文层级都用 `["字段名"]`：例如 `.data[]["组织"]["名称"]`，不能只改顶层。search/get 的 canonical 英文字段与 query 的业务列名要分开理解。文件模式的 `path` 指向行数组，行数组没有 `rowCount`；先按 `resultMode` 分支再消费，示例见 `references/metric-commands.md`。
+  - 必须解析的命令不得用 `2>/dev/null` 隐藏 stderr，也不得用 `2>&1` 将错误文本送入 JSON 解码器。不要用会让末端命令成功掩盖上游失败的管道；优先拆成“guancli 输出到文件 → 确认命令成功 → jq 读取文件”，必须使用管道时先启用 `set -o pipefail`。
   - 同类语法错误只允许出现一次；第一次失败后先执行对应命令的 `--help` 或读取本 Skill 的参考文档，再按真实契约纠正，不连续尝试相近写法。
-- 复杂筛选优先使用 `--filter-json`（可重复）或 `--filter-file` 条件树，并先加 `--dry-run --json-envelope`；dry-run 只读取指标详情做查询维度、筛选字段和类型校验，不执行指标取数，也不支持普通文件或 stderr 输出目标。不支持的 `--dim` 返回 `METRIC_UNSUPPORTED_DIMENSION`。条件树节点使用 `combineType: AND|OR`，叶子使用 `field/operator/value|values`；`IN` 至少一个值，`BT` 恰好两个值。当前指标取数接口不能无损表达多分支 OR，真实执行会在取数前返回 `FILTER_OR_EXECUTION_UNSUPPORTED`，不得拆成多次聚合查询后拼接。失败时按稳定错误码修正，不猜错误文本。
+- 普通 `--filter`、可重复 `--filter-json`、单个 `--filter-file` 三选一，禁止混用。复杂筛选优先使用 `--filter-json`（可重复）或 `--filter-file` 条件树，并先加 `--dry-run -f json`；dry-run 只读取指标详情做查询维度、筛选字段和类型校验，不执行指标取数，也不支持普通文件或 stderr 输出目标。不支持的 `--dim` 返回 `METRIC_UNSUPPORTED_DIMENSION`。条件树节点使用 `combineType: AND|OR`，叶子使用 `field/operator/value|values`；`IN` 至少一个值，`BT` 恰好两个值。当前指标取数接口不能无损表达多分支 OR，真实执行会在取数前返回 `FILTER_OR_EXECUTION_UNSUPPORTED`，不得拆成多次聚合查询后拼接。失败时按稳定错误码修正，不猜错误文本。
 - 搜索并同时查看业务口径、数据集和适用维度等详情时，优先使用 `guancli metric search --fuzzy <keyword> --limit <N> --with-detail --brief -f json`，不要先 search 再逐个 get，也不要为终端阅读额外拼 jq。只查单个指标详情时优先使用 `guancli metric get <metric_id> --brief`；只裁剪指标查询结果列时使用 `metric query --columns`。可复制模板见 `references/metric-commands.md`。
 - 业务词不能直接命中指标时，候选发现必须遵守单批预算：一次性生成“原词 + 最多 4 个必要同义词/等价表达”，按 trim、空白归一化和大小写不敏感语义去重，保留原词在首位，然后只执行一次 `metric search --fuzzy`。不得把同义词拆成多次查询，不得通过调换顺序、改写等价词或查询子集重复搜索；如果单批无候选，立即结束本轮候选发现并说明已尝试关键词、搜索范围、无结果原因和 `stop_reason=no_candidate_within_budget`。后端最多接受 10 个模糊关键词，但 Agent 候选发现预算默认最多 5 个；不要缓存或跨请求复用“未找到指标”的结论。完整协议见 `references/metric-commands.md`。
-- 普通指标数据查询用 `guancli metric query <metric_id>`，可加 `--dim`、筛选、排序、列筛选、输出格式等。数值默认按指标配置的 `format` 输出（查询响应有更具体的列级格式时优先），没有有效格式时才按 `--precision` 回退；需要标准表格/JSON/CSV/Excel 中保留原始数值时传 `--value-format raw`，不要和直接返回后端响应的全局 `--raw` 混淆。使用 `--json-envelope` 时，未指定 `-o/--output` 且结果超过 1000 行会自动写入 `metric_<metricId>_<timestamp>_<unique>.json`，stdout 返回 `resultMode=file` 和绝对 `path`，不得再从中文提示猜文件名。唯一后缀用于避免同秒并发或重试覆盖已有结果。未启用该参数的默认和 `-f json` 输出保持兼容。回答指标数据查询结果时，必须检查输出中的 `查询加速` summary 或 `_queryAccelerate` 列：命中时明确说明“本次查询命中查询加速”，并列出源指标 ID、加速指标 ID 和页面查询顺序；未命中时说明“未命中查询加速”；如果显示 `未知: 后端未返回`，说明当前后端未返回命中 metadata，不能推断是否命中。注意：输出中的 `优先级N` 来自后端 `acceleratePriority` 排序权重，数字越大越先尝试；不要把它直接解释成页面“查询顺序”。需要和页面对齐时，额外执行 `guancli metric accelerate list <metric_id>`，按 `acceleratePriority` 倒序排列后换算页面查询顺序（倒序第 1 个即页面查询顺序 1）。
-- 搜索指标支持两种方式：`guancli metric search <keyword>` 按指标名称模糊搜索；`guancli metric search --fuzzy <keyword>` 同时按指标名称、业务口径、自定义业务属性值做 OR 模糊搜索，可多次传参，命中优先级为 name=1、desc=2、bizAttr=3。`[keyword]` 和 `--fuzzy` 互斥。需要同时查看每个命中指标的 `metric get` 详情时加 `--with-detail`；旧格式默认包含血缘，加 `--brief` 可跳过血缘。`--json-envelope` 不包含且不请求血缘，需要血缘时使用旧 `-f json`。此模式不兼容 `--raw`、CSV 和 Excel 输出，结果很多时先用 search 的 `--limit` 收窄指标数量。指标取数仍单独使用 `metric query`。
+- 普通指标数据查询用 `guancli metric query <metric_id>`，可加 `--dim`、筛选、排序、列筛选、输出格式等。数值默认按指标配置的 `format` 输出（查询响应有更具体的列级格式时优先），没有有效格式时才按 `--precision` 回退；需要标准表格/JSON/CSV/Excel 中保留原始数值时传 `--value-format raw`，不要和直接返回后端响应的全局 `--raw` 混淆。使用 `-f json` 时，未指定 `-o/--output` 且结果超过 1000 行会自动写入 `metric_<metricId>_<timestamp>_<unique>.json`，stdout 返回 `resultMode=file` 和绝对 `path`，不得再从中文提示猜文件名。唯一后缀用于避免同秒并发或重试覆盖已有结果。默认文本、CSV/Excel 和 `--raw` 保持原行为。回答指标数据查询结果时，必须检查输出中的 `查询加速` summary 或 `_queryAccelerate` 列：命中时明确说明“本次查询命中查询加速”，并列出源指标 ID、加速指标 ID 和页面查询顺序；未命中时说明“未命中查询加速”；如果显示 `未知: 后端未返回`，说明当前后端未返回命中 metadata，不能推断是否命中。注意：输出中的 `优先级N` 来自后端 `acceleratePriority` 排序权重，数字越大越先尝试；不要把它直接解释成页面“查询顺序”。需要和页面对齐时，额外执行 `guancli metric accelerate list <metric_id>`，按 `acceleratePriority` 倒序排列后换算页面查询顺序（倒序第 1 个即页面查询顺序 1）。
+- 指标查数必须区分**时间范围**和**分组粒度**。用户说“本月/上月/2026 年 8 月销售额”时只生成时间筛选，不自动增加月维度；用户说“按月/每月/月度趋势/逐月”时，先从指标详情的 `timeField.name` 取得真实时间维度名，再使用 `--dim "<时间维度> toMonth"`；“近 12 个月每月”同时生成月维度和时间范围筛选。季度、周、日、星期、小时、分钟、秒同理映射到 `toQuarter/toWeek/toDate/toDayOfWeek/toHour/toMinute/toSecond`。用户未表达分组粒度时不得擅自改变日期粒度，也不要猜时间字段名一定叫“日期”。多日期维度且用户明确点名其中一个时，用 `--dim "<该维度> toGranularity"` 消歧；未点名且无法从业务问题确定时先确认。日期粒度排序使用相同表达式，例如 `--sort-asc "订单日期 toMonth"`。执行前可用 `--dry-run -f json` 检查 `resolvedDimensions` 中最终选择的 `fdId/fdType/parentFdName/granularity`。
+- 搜索指标支持两种方式：`guancli metric search <keyword>` 按指标名称模糊搜索；`guancli metric search --fuzzy <keyword>` 同时按指标名称、业务口径、自定义业务属性值做 OR 模糊搜索，可多次传参，命中优先级为 name=1、desc=2、bizAttr=3。`[keyword]` 和 `--fuzzy` 互斥。需要同时查看每个命中指标的 `metric get` 详情时加 `--with-detail`；默认文本包含血缘，加 `--brief` 可跳过血缘。`-f json` 不包含且不请求血缘。此模式不兼容 `--raw`、CSV 和 Excel 输出，结果很多时先用 search 的 `--limit` 收窄指标数量。指标取数仍单独使用 `metric query`。
 - 回答指标搜索结果时，必须逐条说明“命中的指标”和“命中方式”：至少包含指标 ID、指标名称、命中条件/字段、命中优先级、命中关键词；不要把用户输入默认解释为指标名称精确匹配。如果结果中有“命中条件”“命中优先级”“命中关键词”列，必须原样纳入结论。
 - 按数据集反查指标用 `guancli metric by-dataset <ds_id>`；如果已知指标主题，可加 `-d <metric_topic_id>` 缩小范围；需要结构化结果时用 `-f json`。
 - 只要传入 `--compare`、`--compare-value`、`--xtd`、`--last`、`--recent`、`--recent-base`、`--percentage`、`--percentage-dim`、`--rank-top`、`--rank-order`、`--rank-dim`、`--adv-calc-json` 任一参数，就进入指标泛化查询模式。泛化查询要求 BI 版本 `>= 8.2.1`；如需确认环境版本，先执行 `guancli server-version --profile <profile>`。

package/skills/guancli/references/examples/metric-date-in.json

@@ -0,0 +1,7 @@
+{
+  "combineType": "AND",
+  "conditions": [
+    {"field": "日期", "operator": "BT", "values": ["2026-01-01", "2026-01-31"]},
+    {"field": "城市", "operator": "IN", "values": ["杭州", "上海"]}
+  ]
+}

package/skills/guancli/references/examples/metric-query-rows.py

@@ -0,0 +1,39 @@
+"""Read a successful metric.query envelope; emit its row array for processing."""
+
+import json
+import sys
+from pathlib import Path
+
+
+def query_rows(envelope):
+    if not isinstance(envelope, dict) or envelope.get("schemaVersion") != "1.0":
+        raise ValueError("expected metric envelope schemaVersion 1.0")
+    if envelope.get("command") != "metric.query":
+        raise ValueError("expected metric.query, not metadata or a dry-run plan")
+    count = envelope.get("rowCount")
+    if type(count) is not int or count < 0:
+        raise ValueError("invalid rowCount")
+    if not isinstance(envelope.get("columns"), list):
+        raise ValueError("missing query columns")
+    if envelope.get("resultMode") == "inline":
+        rows = envelope["data"]
+    elif envelope.get("resultMode") == "file":
+        path = Path(envelope["path"])
+        if not path.is_absolute():
+            raise ValueError("expected absolute output path")
+        with path.open(encoding="utf-8") as source:
+            rows = json.load(source)
+    else:
+        raise ValueError("unsupported resultMode")
+    if not isinstance(rows, list) or len(rows) != count:
+        raise ValueError("row payload does not match envelope rowCount")
+    if any(not isinstance(row, dict) for row in rows):
+        raise ValueError("expected row objects")
+    return rows
+
+
+if __name__ == "__main__":
+    with open(sys.argv[1], encoding="utf-8") as source:
+        rows = query_rows(json.load(source))
+    json.dump(rows, sys.stdout, ensure_ascii=False)
+    print()

package/skills/guancli/references/examples/metric-query.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Usage: bash metric-query.sh METRIC_ID PROFILE
+set -euo pipefail
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+guancli metric query "$1" --profile "$2" -f json > query-envelope.json 2> query-error.log
+python3 "$script_dir/metric-query-rows.py" query-envelope.json > query-rows.json

package/skills/guancli/references/metric-commands.md

@@ -72,7 +72,7 @@ guancli metric search [keyword] [flags]
 | `--fuzzy strings` | 名称、业务口径、自定义业务属性统一模糊搜索关键词，可多次指定，也支持逗号、中文逗号、顿号分隔；和 `[keyword]` 互斥 |
 | `--offset int` | 搜索结果分页偏移量，默认 `0` |
 | `--limit int` | 搜索结果数量，默认 `0` 表示全部 |
-| `--with-detail` | 同时返回每个命中指标的 `metric get` 详情；旧格式默认包含血缘，`--brief` 或 `--json-envelope` 不请求血缘 |
+| `--with-detail` | 同时返回每个命中指标的 `metric get` 详情；默认文本包含血缘，`--brief` 或 `-f json` 不请求血缘 |
 
 `--fuzzy` 语义：
 
@@ -81,8 +81,8 @@ guancli metric search [keyword] [flags]
 - 自定义业务属性值统一模糊匹配；后端只匹配启用且可搜索的业务属性。
 - 结果会在原有指标字段基础上增加命中条件、命中优先级和命中关键词。
 - 非 `--raw` 输出会额外查询并返回每个指标关联的查询加速摘要，包括查询加速数量和加速指标 ID/优先级/字段摘要。
-- `--with-detail` 会为当前搜索结果中的每个指标补充与 `metric get <metric_id>` 相同的标准化详情；默认终端输出按指标追加详情，`-f json` 则在每条搜索结果的 `指标详情` 中嵌套返回。
-- 旧格式默认详情包含血缘；批量搜索只需业务口径、数据集、字段、权限、统计、自定义属性和查询加速等信息时，加 `--brief` 跳过血缘。`--json-envelope` 不包含且不请求血缘，需要血缘时使用旧 `-f json`。结果较多时先用 `--limit` 收窄指标数量。
+- `--with-detail` 会为当前搜索结果中的每个指标补充与 `metric get <metric_id>` 相同的标准化详情；默认终端输出按指标追加详情，`-f json` 在 envelope 的 `data[]` 中直接返回 canonical 详情字段，不再嵌套中文 `指标详情`。
+- 默认文本详情包含血缘；批量搜索只需业务口径、数据集、字段、权限、统计、自定义属性和查询加速等信息时，加 `--brief` 跳过血缘。`-f json` 不包含且不请求血缘。结果较多时先用 `--limit` 收窄指标数量。
 - `--with-detail` 只补指标详情，不查询指标数据；指标取数仍使用 `metric query`。
 - `--with-detail` 需要组合多个接口的结果，因此不兼容 `--raw`、`-f csv` 和 `-f excel`。
 - `[keyword]` 走旧指标名称搜索接口；`--fuzzy` 走新的统一模糊搜索接口，二者不能同时使用。
@@ -130,7 +130,7 @@ guancli metric search --fuzzy <关键词> --profile <profile> --limit 5 --with-d
 确实需要机器处理 JSON 时，先保存成功输出再单独执行 jq，避免管道末端成功掩盖 guancli 失败：
 
 ```bash
-guancli metric search --fuzzy <关键词> --profile <profile> --limit 5 --with-detail --brief --json-envelope > metric_search.json &&
+guancli metric search --fuzzy <关键词> --profile <profile> --limit 5 --with-detail --brief -f json > metric_search.json &&
   jq '.data[] | {id, name, dimensions, timeField}' metric_search.json
 ```
 
@@ -166,7 +166,7 @@ guancli metric get <metric_id> --profile <profile> --brief
 需要结构化提取时拆成两步：
 
 ```bash
-guancli metric get <metric_id> --profile <profile> --brief --json-envelope > metric_detail.json &&
+guancli metric get <metric_id> --profile <profile> --brief -f json > metric_detail.json &&
   jq '.data.dimensions' metric_detail.json
 ```
 
@@ -239,23 +239,57 @@ guancli metric query <metric_id> [flags]
 | 参数 | 默认值 | 说明 |
 | --- | --- | --- |
 | `--limit int` | `50` | 数据行数限制 |
-| `--dim strings` | 无 | 维度名称，可多次指定，也支持逗号、中文逗号、顿号分隔 |
+| `--dim strings` | 无 | 维度名称，可多次指定，也支持逗号、中文逗号、顿号分隔；日期子类型写作 `"订单日期 toMonth"` |
 | `--filter stringArray` | 无 | 筛选条件，格式：`"列名 操作符 值"`，可多次指定 |
-| `--filter-json stringArray` | 无 | 结构化筛选 JSON，可重复；支持嵌套 AND/OR 条件树 |
+| `--filter-json stringArray` | 无 | 结构化筛选 JSON，可重复；与 --filter/--filter-file 互斥；支持嵌套 AND/OR 条件树 |
 | `--filter-file string` | 无 | 从 JSON 文件读取一棵结构化条件树；与 `--filter`、`--filter-json` 互斥 |
 | `--combine-type string` | `AND` | 多条件组合方式：`AND` 或 `OR` |
-| `--dry-run` | `false` | 只返回规范化查询计划、字段类型和稳定错误码，不执行指标取数；必须同时使用 `--json-envelope`，且不支持普通文件或 stderr 输出目标 |
-| `--json-envelope` | `false` | 输出带 `schemaVersion` 的稳定 JSON envelope；`--dry-run` 必须启用此参数，且不能与 `--raw`、非 JSON `-f` 或 stderr 输出目标同时使用 |
-| `--sort-asc string` | 无 | 按列升序排序，与 `--sort-desc` 互斥 |
-| `--sort-desc string` | 无 | 按列降序排序，与 `--sort-asc` 互斥 |
+| `--dry-run` | `false` | 只返回规范化查询计划、字段类型和稳定错误码，不执行指标取数；必须同时使用 `-f json`，且不支持普通文件或 stderr 输出目标 |
+| `--sort-asc string` | 无 | 按列升序排序；日期子类型使用与 `--dim` 相同的粒度表达式；与 `--sort-desc` 互斥 |
+| `--sort-desc string` | 无 | 按列降序排序；日期子类型使用与 `--dim` 相同的粒度表达式；与 `--sort-asc` 互斥 |
 | `--columns strings` | 无 | 只显示指定列，逗号分隔，在 CLI 端执行 |
 | `--precision int` | `6` | 没有有效指标格式时的数值最大小数位数；传 `-1` 保留原始精度 |
 | `--value-format string` | `formatted` | `formatted` 按指标格式输出；`raw` 保留原始数值 |
 | `-o, --output string` | 无 | 将查询结果写入文件；未指定且结果超过 1000 行时自动写入文件 |
 
-`metric search/get/tree/query --json-envelope` 都返回带版本号的稳定 JSON envelope，当前 canonical 契约版本为 `1.0`，公共字段为 `schemaVersion`、`command`、`resultMode`、`rowCount`。内联结果在 `data`，文件结果在绝对 `path`；query 还返回 `columns`。版本演进读取响应体中的 `schemaVersion`，不会增加 `json-v2` 一类输出格式。原 `-f json` 保持旧版对象/数组结构，避免破坏 Decidex 等既有调用方。未指定 `-o/--output` 且查询结果超过 1000 行时，默认模式仍自动写 CSV 并输出原中文提示；启用 `--json-envelope` 时写 JSON 文件，stdout 返回 `resultMode=file` envelope。自动文件名带唯一后缀，避免同秒并发或重试覆盖已有结果。显式非 JSON `-f` 与 `--json-envelope` 不兼容。
+`metric search/get/tree/query -f json` 都返回带版本号的稳定 JSON envelope，当前 canonical 契约版本为 `1.0`，公共字段为 `schemaVersion`、`command`、`resultMode`、`rowCount`。内联结果在 `data`，文件结果在绝对 `path`；query 还返回 `columns`。版本演进读取响应体中的 `schemaVersion`，不会增加 `json-v2` 一类输出格式。旧对象/数组入口已移除，这是输出契约迁移，旧脚本必须同步适配，详见 [迁移清单](metric-json-migration.md)。未指定 `-o/--output` 且查询结果超过 1000 行时，默认模式仍自动写 CSV 并输出原中文提示；使用 `-f json` 时写 JSON 文件，stdout 返回 `resultMode=file` envelope。自动文件名带唯一后缀，避免同秒并发或重试覆盖已有结果。
 
-search/get 的 `data` 使用直接由后端字段构造的 canonical 模型：`id/name/status/type/description/projectId/directoryId/dataset/dimensions/timeField/measureFields/match/accelerations/statistics/permissions/customAttributes/updatedAt`。`status/type` 保留 `PUBLISHED/ATOMIC` 等机器枚举，不使用“在线/原子指标”等中文展示标签；`match.priority` 保留后端 `name=1/desc=2/bizAttr=3`，精确/模糊由 `match.mode` 单独表达。未知后端字段被忽略，`id/name` 缺失时明确返回契约错误。可选标量和对象的缺失或 `null` 统一省略；`dimensions/timeField/measureFields/customAttributes` 及 `accelerations[].priority` 区分缺失、`null`、空值或零值，`accelerations` 区分未查询与已知空数组，调用方不要把省略解释成已知为空。tree 的节点固定使用 `id/name/type/children`，`--brief` 只省略计数和权限，不省略节点身份。中文展示字段只属于默认输出和旧 `-f json`，不属于 envelope 契约。canonical 模型不包含血缘，因此 `--with-detail --json-envelope` 不请求血缘；确实需要血缘时使用原 `-f json`。query dry-run 不查询加速配置，此时省略 `metric.accelerations`，不能把省略解释成无加速配置。
+search/get 的 `data` 使用直接由后端字段构造的 canonical 模型：`id/name/status/type/description/projectId/directoryId/dataset/dimensions/timeField/measureFields/match/accelerations/statistics/permissions/customAttributes/updatedAt`。`status/type` 保留 `PUBLISHED/ATOMIC` 等机器枚举，不使用“在线/原子指标”等中文展示标签；`match.priority` 保留后端 `name=1/desc=2/bizAttr=3`，精确/模糊由 `match.mode` 单独表达。未知后端字段被忽略，`id/name` 缺失时明确返回契约错误。可选标量和对象的缺失或 `null` 统一省略；`dimensions/timeField/measureFields/customAttributes` 及 `accelerations[].priority` 区分缺失、`null`、空值或零值，`accelerations` 区分未查询与已知空数组，调用方不要把省略解释成已知为空。tree 的节点固定使用 `id/name/type/children`，`--brief` 只省略计数和权限，不省略节点身份。中文展示字段只属于默认输出，不属于 envelope 契约。canonical 模型不包含血缘，因此 `--with-detail -f json` 不请求血缘；文本详情可查看血缘。query dry-run 不查询加速配置，此时省略 `metric.accelerations`，不能把省略解释成无加速配置。
+
+query dry-run 的 `dimensions` 保留用户输入的字符串数组，并额外返回 `resolvedDimensions`。后者是 CLI 最终发送给查询接口的维度对象，可用于确认日期子类型是否解析到了预期的 `fdId`、`fdType=SUB_DATE`、`parentFdName` 和 `granularity`。
+
+### 日期子类型维度
+
+日期维度可在字段名后增加粒度修饰符：
+
+| 用户意图 | 修饰符 | 粒度 |
+| --- | --- | --- |
+| 按年 | `toYear` | `YEAR` |
+| 按季度 | `toQuarter` | `QUARTER` |
+| 按月 | `toMonth` | `MONTH` |
+| 按周 | `toWeek` | `WEEK` |
+| 按星期 | `toDayOfWeek` | `DAYOFWEEK` |
+| 按日 | `toDate` / `toDay` | `DAY` |
+| 按小时 | `toHour` | `HOUR` |
+| 按分钟 | `toMinute` | `MINUTE` |
+| 按秒 | `toSecond` | `SECOND` |
+
+CLI 以指标详情返回的日期子字段为准；目标粒度不存在时返回 `METRIC_UNSUPPORTED_DATE_GRANULARITY`，不会伪造字段 ID。DATE 字段的 DAY 使用基础日期字段，TIMESTAMP 的 DAY 使用日期子字段。完整字段名精确匹配优先，因此不会破坏名称本身以 `toMonth` 等文本结尾的历史维度。
+
+Agent 生成命令时必须区分时间范围与分组粒度：
+
+- “本月/上月/某个月销售额”只表示筛选范围，不自动增加月维度。
+- “按月/每月/月度趋势/逐月销售额”表示分组粒度，使用 `--dim "<时间维度> toMonth"`。
+- “近 12 个月每月销售额”同时使用月维度和时间范围筛选。
+- 时间字段名从指标详情的 `timeField.name` 获取，不要默认写成“日期”。
+
+示例：
+
+```bash
+guancli metric query <metric_id> --profile default --dim "订单日期 toMonth"
+guancli metric query <metric_id> --profile default --dim "订单日期 toMonth" --sort-asc "订单日期 toMonth"
+guancli metric query <metric_id> --profile default --dim "订单日期 toMonth" --dry-run -f json
+```
 
 筛选操作符：
 
@@ -275,10 +309,11 @@ search/get 的 `data` 使用直接由后端字段构造的 canonical 模型：`i
 guancli metric query <metric_id> --profile default
 guancli metric query <metric_id> --profile default --dim 省份 --limit 10
 guancli metric query <metric_id> --profile default --dim "省份、城市" --limit 20
+guancli metric query <metric_id> --profile default --dim "订单日期 toMonth" --sort-asc "订单日期 toMonth"
 guancli metric query <metric_id> --profile default --dim 省份 --filter "省份 EQ 河南省"
-guancli metric query <metric_id> --profile default --dim 省份 --filter "省份 EQ 河南省" --filter "省份 EQ 青海省" --combine-type OR --dry-run --json-envelope
-guancli metric query <metric_id> --profile default --filter-json '{"field":"省份","operator":"IN","values":["河南省","青海省"]}' --dry-run --json-envelope
-guancli metric query <metric_id> --profile default --filter-file filters.json --dry-run --json-envelope
+guancli metric query <metric_id> --profile default --dim 省份 --filter "省份 EQ 河南省" --filter "省份 EQ 青海省" --combine-type OR --dry-run -f json
+guancli metric query <metric_id> --profile default --filter-json '{"field":"省份","operator":"IN","values":["河南省","青海省"]}' --dry-run -f json
+guancli metric query <metric_id> --profile default --filter-file filters.json --dry-run -f json
 guancli metric query <metric_id> --profile default --dim 省份 --sort-desc 订购数量
 guancli metric query <metric_id> --profile default --dim 省份 --columns "省份,订购数量"
 guancli metric query <metric_id> --profile default --dim 省份 -f csv
@@ -472,3 +507,31 @@ guancli metric_attribution query <metric_tree_id> --profile test43 --target dim
 guancli metric_attribution query <metric_tree_id> --profile test43 --target scan -f csv
 guancli metric_attribution query <metric_tree_id> --profile test43 --target dim --dim 业务员 --raw
 ```
+
+### 查询结果消费
+
+机器查询统一用 `-f json`。`query` 的 `data` 和文件载荷都是行对象数组；search 的 `data` 是指标数组，get/tree 的 `data` 是单个对象。`rowCount` 属于 stdout envelope，不能从行数组读取。query 的 `columns` 保留真实业务列名，可以是中文；search/get 的 `id/name/dimensions` 是 canonical 英文字段。
+
+下面示例在 Skill 目录执行；先确认 CLI 成功，再解析 stdout，stderr 单独保存：
+
+```bash
+# 成功后 query-rows.json 统一为行数组，不论原结果是 inline 还是 file。
+bash references/examples/metric-query.sh <metric_id> <profile> &&
+  jq '.[] | .["组织"]["名称"]' query-rows.json
+```
+
+`examples/metric-query-rows.py` 检查 schemaVersion、command、resultMode 和行数；file 模式只从 envelope 的绝对 `path` 读取，不无条件遍历 `data`。上例中文嵌套字段仅演示引用语法，实际字段以 `columns`/数据为准。每一个中文层级都使用 `["字段名"]`。
+
+### 日期与 IN 使用同一种筛选输入
+
+先通过 get 确认日期、城市存在且类型相符。完整条件树见 `examples/metric-date-in.json`：
+
+```bash
+guancli metric query <metric_id> --profile <profile> --filter-file references/examples/metric-date-in.json --dry-run -f json
+# 或把两个条件都放入可重复的 filter-json，不要再混入普通 --filter：
+guancli metric query <metric_id> --profile <profile> \
+  --filter-json '{"field":"日期","operator":"BT","values":["2026-01-01","2026-01-31"]}' \
+  --filter-json '{"field":"城市","operator":"IN","values":["杭州","上海"]}' --dry-run -f json
+```
+
+普通 `--filter`、可重复 `--filter-json`、单个 `--filter-file` 三选一。dry-run 成功只表示计划校验通过，实际执行仍由 BI 决定。

package/skills/guancli/references/metric-generic-query.md

@@ -117,7 +117,7 @@ guancli server-version --profile <profile>
 
 ```bash
 guancli metric query <metric_id> --profile default --dim 日期 --compare yoy --limit 10
-guancli metric query <metric_id> --profile default --dim 日期 --compare mom --limit 10
+guancli metric query <metric_id> --profile default --dim "日期 toMonth" --compare mom --limit 10
 guancli metric query <metric_id> --profile default --dim 日期 --compare yoy --compare-value rate --limit 10
 guancli metric query <metric_id> --profile default --dim 省份 --compare yoy --filter "省份 EQ 河南省" --limit 10
 ```
@@ -197,3 +197,5 @@ guancli metric query <metric_id> --profile default --dim 省份 --compare yoy --
 guancli metric query <metric_id> --profile default --dim 日期 --recent 7d --columns "日期,订购数量_recent_7d" --limit 10
 guancli metric query <metric_id> --profile default --dim 城市 --rank-top 5 --rank-order desc --rank-dim 城市 -f json
 ```
+
+机器输出使用 `-f json`，与普通 query 共享 envelope 契约；先确认 CLI 成功，再按 `resultMode` 读取 `data` 或 `path` 中的行数组。完整可执行消费示例见 [指标命令](metric-commands.md#查询结果消费)。

package/skills/guancli/references/metric-json-migration.md

@@ -0,0 +1,18 @@
+# 指标 JSON 入口迁移（GALAXY-39561）
+
+本次明确将 search/get/tree/query 的 `-f json` 改为已有 schemaVersion 1.0 envelope；旧数组/展示对象与它不兼容。原 `--json-envelope` 参数已移除，调用方统一使用 `-f json`。`--raw`（包括历史 `--raw -f json`）继续返回后端原始协议，不是 envelope。
+
+| 消费者 | 清点与迁移 |
+| --- | --- |
+| guancli SKILL、metric-commands、metric-generic-query、help、设计示例 | 统一 -f json，data/path 分支消费；中文业务列逐层括号引用；可执行本地示例覆盖失败、文件和筛选 |
+| guanmetric 指标树、原子/复合/衍生编辑参考 | 需要完整编辑详情的调用迁移到 --raw 后端 response；仅名称/ID 发现直接消费 envelope.data；formula/format 属于 --raw 后端字段 |
+| guancli-kit / guancli-lite | kit 共用 cmdcore，lite 透传 kit 输出；kit 行为测试覆盖 envelope，文本输出保留血缘预算/探测测试 |
+| Decidex guandata-live/metric-topic | 使用 --raw，协议保持原行为 |
+| Decidex guancli-command-insight | 本次不修改，由用户另行适配：旧行数组行数提取需要同时接受 query envelope 的 inline/file，并保留历史输出读取；CLI 本地验证不代表 Decidex 已完成接入 |
+| guancli project/by-dataset/accelerate、其他资源命令 | 不改变格式 |
+
+不提供旧 JSON 兼容入口：`--json-envelope` 和 `--legacy-json` 均不支持。历史脚本重新执行时按新版帮助迁移参数及 data/path 消费逻辑。guanmetric 编辑消费者使用 --raw 读取完整后端详情。
+
+## Domain and Contract
+
+复用现有独立 canonical adapter 和 1.0 envelope，不新增后端接口/业务裁决/多接口合并。可选字段缺失/null 的原语义不变，稳定必填 id/name 缺失仍报错。query columns 保留业务列；file 载荷是行数组，stdout 才是 envelope。默认文本、CSV/Excel、原始协议、非指标命令和错误退出语义保持原行为。测试覆盖 CLI/kit 输出、移除参数的拒绝行为、空集合、缺失/null、文件与中文列，以及脚本退出码传播。

package/skills/guancli/references/preview-and-output.md

@@ -129,8 +129,9 @@ guancli card preview <cd_id> --with-default-filters --dynamic-param "结束日
 
 - 卡片元信息只关联一个页面时自动使用该页面；关联多个页面时必须用 `--page-id` 明确上下文。
 - 显式 `--filter` 或 `--dynamic-param` 会覆盖相同 `fdId` 或 `dpId` 的页面默认值，其他默认条件仍然保留。
-- 首版支持普通固定值、多选、日期范围、后端已经解析出实际区间的时间宏，以及动态参数选择器。
-- 树、组合、`FIRST_PICK`、聚合/结果级映射、依赖其他选择器的级联运行态、必填但无默认值，以及无法从页面元信息确定实际值或目标映射的默认条件均 fail closed：CLI 在查询卡片数据前明确报错，不会静默忽略后继续执行。`autoLink` 会先按同名字段推断目标字段，推断不到时才 fail closed。
+- 支持普通固定值、多选、日期范围、后端已经解析出实际区间的时间宏，以及动态参数选择器。
+- `FIRST_PICK`（取首个候选值）和日历 `MAX`（取最新日期）在页面详情里没有具体值，CLI 会与 BI 前端打开页面时一样调用 `POST /api/page/first-pick` 运行态求值；选择器级联时按上游→下游分层求值，同一层的选择器合并为一个请求（请求次数等于级联深度，无级联时 1 次），并把上游默认值作为候选值筛选条件传入；单次命令最多运行态求值 20 个选择器，循环级联直接报错。stderr 提示行的 `runtimeResolved=` 列出经运行态求值的选择器。\n- 每次 `card preview` 的表格页脚（写文件时为“已写入”后的一行）都有 `筛选:`，列出本次真正生效的条件及来源：`[--filter]`/`[--dynamic-param]` 为显式指定，`[页面默认·<选择器名>]` 为页面筛选器默认值，带 `·运行态求值` 表示 FIRST_PICK/MAX 求值结果；没有任何条件时写明是否应用了页面默认值（选择器等不支持该参数的卡片只显示“无”）。`-f json/csv/excel` 的 stdout 只含数据，条件说明只在 stderr。
+- 树、组合、聚合/结果级映射、必填但无默认值，以及无法从页面元信息确定实际值或目标映射的默认条件均 fail closed：CLI 在查询卡片数据前明确报错，不会静默忽略后继续执行。`autoLink` 会先按同名字段推断目标字段，推断不到时才 fail closed。
 - 多个选择器写入同一字段或动态参数、时间宏目标形态不明确、动态参数默认值包含逗号等可能产生歧义的情况同样会停止查询。
 - 该参数仅适用于 CHART 图表卡片；复杂报表 Pro、选择器和其他卡片类型暂不支持。