@guandata/guancli 1.0.28 → 1.0.30

package/CHANGELOG.md

@@ -1,9 +1,22 @@
 # Changelog
 
+## @guandata/guancli 1.0.30 - 2026-05-29
+
+- `card preview --dynamic-field` 支持当前卡片自身的多选动态维度覆盖，可用逗号分隔字段或重复传参合并。
+- `card preview` 动态维度参数校验与输出诊断增强，便于确认实际预览使用的动态维度选择。
+- 简版资源详情减少非必要血缘明细加载，提升资源信息查询速度和稳定性。
+
+## @guandata/guancli 1.0.29 - 2026-05-28
+
+- `card preview` 支持复杂报表 Pro 卡片预览，适配复杂报表筛选条件和数据输出。
+- `card preview --dynamic-field` 支持按动态维度名和字段名指定预览选择，同时保留 dzId/key 等精确写法。
+- `card preview -o` 输出大结果文件时补充字段 schema 提示，便于后续读取和处理导出的卡片数据。
+- `ds execute-sql` 文档和提示补充数据集名称作为临时表名的说明。
+
 ## @guandata/guancli 1.0.28 - 2026-05-26
 
-- 卡片预览支持动态参数默认值，可在预览时自动带入可验证的动态字段选择。
-- 增强动态字段配置校验，对缺少来源卡片、字段映射不完整或无法确认的配置提前报错。
+- 卡片预览支持动态参数默认值，可在预览时自动带入可验证的动态维度选择。
+- 增强动态维度配置校验，对缺少来源卡片、字段映射不完整或无法确认的配置提前报错。
 - 卡片信息输出补充动态参数相关摘要，便于排查筛选器和图表联动配置。
 
 ## @guandata/guancli 1.0.27 - 2026-05-26

package/README.md

@@ -23,9 +23,10 @@ guancli etl tree
 guancli etl get <resource_id>
 guancli ds search <keyword>
 guancli ds preview <ds_id>
-guancli ds execute-sql -inputs <ds_id> -sql "SELECT * FROM input1 LIMIT 20"  # 需目标 BI 支持该接口并开启高级 SQL 查询
-guancli ds execute-sql -inputs <ds_id> -sql "SELECT * FROM input1 LIMIT 20" -f json
-guancli ds execute-sql -inputs <ds_id> -sql "SELECT * FROM input1 LIMIT 20" --raw
+guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20'  # 需目标 BI 支持该接口并开启高级 SQL 查询
+guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20' -f json
+guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20' --raw
+# SQL 中请使用数据集名称作为临时表名；名称包含中文、空格或特殊字符时，请使用反引号包裹。
 # 旧版 public-api fallback 不支持 disable-cache；--limit 在非 raw 输出渲染前本地截断，--raw 保持后端原始响应
 guancli metric project
 guancli metric project 经营 -f json
@@ -37,10 +38,23 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### 1.0.30
+
+- `card preview --dynamic-field` 支持当前卡片自身的多选动态维度覆盖，可用逗号分隔字段或重复传参合并。
+- `card preview` 动态维度参数校验与输出诊断增强，便于确认实际预览使用的动态维度选择。
+- 简版资源详情减少非必要血缘明细加载，提升资源信息查询速度和稳定性。
+
+### 1.0.29
+
+- `card preview` 支持复杂报表 Pro 卡片预览，适配复杂报表筛选条件和数据输出。
+- `card preview --dynamic-field` 支持按动态维度名和字段名指定预览选择，同时保留 dzId/key 等精确写法。
+- `card preview -o` 输出大结果文件时补充字段 schema 提示，便于后续读取和处理导出的卡片数据。
+- `ds execute-sql` 文档和提示补充数据集名称作为临时表名的说明。
+
 ### 1.0.28
 
-- 卡片预览支持动态参数默认值，可在预览时自动带入可验证的动态字段选择。
-- 增强动态字段配置校验，对缺少来源卡片、字段映射不完整或无法确认的配置提前报错。
+- 卡片预览支持动态参数默认值，可在预览时自动带入可验证的动态维度选择。
+- 增强动态维度配置校验，对缺少来源卡片、字段映射不完整或无法确认的配置提前报错。
 - 卡片信息输出补充动态参数相关摘要，便于排查筛选器和图表联动配置。
 
 ### 1.0.27

package/package.json

@@ -1,16 +1,10 @@
 {
   "name": "@guandata/guancli",
-  "version": "1.0.28",
+  "version": "1.0.30",
   "description": "观远 BI 命令行工具 - 通过 API 操作 ETL、数据集、页面、表单等资源，并提供 ChatBI 问数/洞察能力",
   "bin": {
     "guancli": "bin/run.js"
   },
-  "scripts": {
-    "build": "node scripts/build.js && node scripts/sync-skill.js",
-    "changelog": "node ../../scripts/generate-release-changelog.js .",
-    "check-changelog": "node ../../scripts/check-release-changelog.js .",
-    "prepublishOnly": "npm run check-changelog && npm run build && node scripts/preflight.js"
-  },
   "files": [
     "bin/",
     "binaries/",

package/skills/guancli/SKILL.md

@@ -153,7 +153,8 @@ guancli page get <resource_id>         # 页面详情（含卡片列表、血缘
 guancli ds preview <ds_id>              # 预览数据集数据 (表格格式)
 guancli ds preview <ds_id> --limit 20   # 限制预览行数
 guancli ds preview <ds_id> --raw        # 输出原始 JSON
-guancli ds execute-sql -inputs <ds_id> -sql "SELECT * FROM input1 LIMIT 20"  # 用 SQL 查询数据集（需目标 BI 支持该接口并开启高级 SQL 查询）
+guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20'  # 用 SQL 查询数据集（需目标 BI 支持该接口并开启高级 SQL 查询）
+# SQL 中请使用数据集名称作为临时表名；名称包含中文、空格或特殊字符时，请使用反引号包裹。可先执行 `ds get <ds_id> --brief` 查看数据集名称和字段列表。
 `execute-sql` 的旧版 public-api fallback 不支持 disable-cache；`--limit` 在非 raw 输出渲染前本地截断，`--raw` 保持后端原始响应。
 ```
 
@@ -186,7 +187,7 @@ guancli ds preview <ds_id> --filter "销售 金额 GT 100" --combine-type OR
 
 #### 日期粒度筛选（SUB_DATE）
 
-对 DATE/TIMESTAMP 字段，可用 `toYear`/`toQuarter`/`toMonth`/`toDate` 修饰符按粒度筛选。
+对 DATE/TIMESTAMP 字段，可用 `toYear`/`toQuarter`/`toMonth`/`toWeek`/`toDate` 修饰符按粒度筛选。
 语法：`"列名 toGranularity OPERATOR value"`，值使用标准格式，CLI 自动转换为 BI API 格式。
 
 ```bash
@@ -194,6 +195,7 @@ guancli card preview <cd_id> --filter "日期字段 toQuarter IN 2026-Q1"
 guancli card preview <cd_id> --filter "日期字段 toQuarter IN 2026-Q1,2026-Q2"
 guancli card preview <cd_id> --filter "日期字段 toYear EQ 2026"
 guancli card preview <cd_id> --filter "日期字段 toMonth EQ 2026-01"
+guancli card preview <cd_id> --filter "日期字段 toWeek EQ 2026-W01"
 guancli card preview <cd_id> --filter "日期字段 toDate EQ 2026-01-15"
 ```
 
@@ -204,6 +206,7 @@ guancli card preview <cd_id> --filter "日期字段 toDate EQ 2026-01-15"
 | 年 | `toYear` | `YYYY` | `2026` |
 | 季度 | `toQuarter` | `YYYY-QN` | `2026-Q1` |
 | 月 | `toMonth` | `YYYY-MM` | `2026-01` |
+| 周 | `toWeek` | `YYYY-WNN` 或 `YYYY WNN` | `2026-W01` |
 | 日期 | `toDate` | `YYYY-MM-DD` | `2026-01-15` |
 
 可配合 `--filter "维度字段 EQ 值"` 同时使用多个筛选条件。
@@ -236,15 +239,18 @@ guancli card preview <cd_id> -f excel -o card.xls # 导出 Excel 可打开文件
 卡片 ID (cdId) 可通过 `page get` 命令查看页面详情获取。
 图表卡片内部会按 BI 预览接口的分页能力自动取数；选择器/树状选择器仍使用服务端单次返回。任意卡片预览结果在未指定 `-o/--output` 且超过 1000 行时，默认写入 `card_<cdId>_<timestamp>.<ext>` 文件，避免把大结果直接塞入上下文。该能力不对接 BI 导出任务接口。
 
+复杂报表 Pro 卡片会自动切换为 xlsx 下载模式，只支持写入文件，不支持 `--raw`、`-f/--format`、`--limit`、排序、列筛选、精度、动态参数和动态维度。未指定 `-o/--output` 时默认写入 `complex_report_pro_<cdId>_<timestamp>.xlsx`。
+
 #### 带筛选条件预览卡片
 
 卡片 preview 同样支持 `--filter` 参数，语法与数据集 preview 一致（含日期粒度筛选）。
-筛选条件会通过 API 传递给后端，适用于 CHART、SELECTOR、TREE_SELECTOR 三种卡片类型。
+筛选条件会通过 API 传递给后端，适用于 CHART、SELECTOR、TREE_SELECTOR 三种卡片类型。复杂报表 Pro 首版也使用 `--filter`，CLI 会基于页面普通选择器的 `asFilter.columnMappings` 自动映射为子卡 `childFilters`；映射不唯一、树/组合筛选器、动态参数 target 等复杂情况会直接报错。
 
 ```bash
 guancli card preview <cd_id> --filter "name EQ 张三"
 guancli card preview <cd_id> --filter "age GT 18" --filter "city IN 北京,上海"
 guancli card preview <cd_id> --filter "利润中心 EQ 华南" --filter "季度(日期) toQuarter IN 2026-Q1"
+guancli card preview <complex_report_pro_cd_id> --filter "周 toWeek EQ 2026-W01" -o report.xlsx
 ```
 
 字段类型会自动从卡片关联的数据集 schema 推断。日期粒度筛选需配合 `card get` 查看字段配置中的筛选器字段名和粒度。
@@ -263,6 +269,25 @@ guancli card preview <cd_id> --dynamic-param "品类=鞋,服,包"
 guancli card preview <cd_id> --dynamic-param "DATE_RANGE_PARAM_LEFT=2026-05-01" --dynamic-param "DATE_RANGE_PARAM_RIGHT={{{today}}}"
 ```
 
+#### 带动态维度预览图表卡片
+
+图表卡片 preview 支持通过 `--dynamic-field` 覆盖当前卡片自身的动态维度选择；参数名沿用历史/API 命名，语义上表示动态维度。
+格式为 `动态维度名=字段名`、`dzId=fdId`、`dzId=key`，也兼容旧写法 `dzId:key`。
+动态维度名、dzId、字段名、fdId、key 先用 `card get <cd_id>` 查看；如果动态维度没有配置名称，只能使用 dzId。
+单选动态维度只能指定一个字段；`multiSelect: true` 的动态维度可用英文逗号传多个字段，或重复指定同一个动态维度，CLI 会合并去重。
+字段名本身包含英文逗号时，CLI 会优先按完整字段名匹配；也可用 CSV 引号写法，例如 `"维度=\"门店,二店\""`。
+该能力仅支持当前卡片自身的动态维度，不支持带 `sourceDzIds` 的来源动态维度；参数只影响本次运行态取数，不修改卡片配置。
+
+```bash
+guancli card get <cd_id> # 查看动态维度配置、dzId、可选字段、fdId、key
+guancli card preview <cd_id> --dynamic-field "维度=区域"
+guancli card preview <cd_id> --dynamic-field "维度=区域,门店" --dynamic-field "数值=销售额,利润"
+guancli card preview <cd_id> --dynamic-field "维度=区域" --dynamic-field "维度=门店"
+guancli card preview <cd_id> --dynamic-field "dz_region=province_fd,city_fd"
+guancli card preview <cd_id> --dynamic-field "dz_region=province_key,city_key"
+guancli card preview <cd_id> --dynamic-field "dz_region:city_key"
+```
+
 ### 6. 表单填报操作 (Form CRUD)
 
 类似 Airtable 风格的表单数据 CRUD，用户始终用**字段名**操作，CLI 内部自动映射到 fdId。