@guandata/guancli 1.0.28 → 1.0.29

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## @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
 
 - 卡片预览支持动态参数默认值，可在预览时自动带入可验证的动态字段选择。

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,6 +38,13 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### 1.0.29
+
+- `card preview` 支持复杂报表 Pro 卡片预览，适配复杂报表筛选条件和数据输出。
+- `card preview --dynamic-field` 支持按动态维度名和字段名指定预览选择，同时保留 dzId/key 等精确写法。
+- `card preview -o` 输出大结果文件时补充字段 schema 提示，便于后续读取和处理导出的卡片数据。
+- `ds execute-sql` 文档和提示补充数据集名称作为临时表名的说明。
+
 ### 1.0.28
 
 - 卡片预览支持动态参数默认值，可在预览时自动带入可验证的动态字段选择。

package/package.json

@@ -1,16 +1,10 @@
 {
   "name": "@guandata/guancli",
-  "version": "1.0.28",
+  "version": "1.0.29",
   "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/",
@@ -35,7 +29,6 @@
     "node": ">=14"
   },
   "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
     "access": "public"
   }
 }

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` 查看字段配置中的筛选器字段名和粒度。