@guandata/guancli 1.0.44 → 1.0.45

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## @guandata/guancli 1.0.45 - 2026-07-28
+
+- `auth status` 现在遵循根级 `--profile` 与 `GUANCLI_PROFILE`，可可靠核验高层 skill 当前进程链使用的目标环境。
+- 卡片预览支持应用所在页面的默认筛选条件，覆盖常用选择器、日期粒度和动态参数；遇到多页面或无法确定的映射时会提前提示确认，避免静默返回错误结果。
+- 动态参数会按当前卡片的实际配置解析，多个卡片使用不同参数时不再相互干扰。
+
 ## @guandata/guancli 1.0.44 - 2026-07-25
 
 - 指标搜索支持多个关键词，并可同时匹配指标名称、业务口径和业务属性，结果会说明命中位置和优先级。

package/README.md

@@ -41,6 +41,12 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.45
+
+- 卡片预览支持应用所在页面的默认筛选条件，覆盖常用选择器、日期粒度和动态参数；遇到多页面或无法确定的映射时会提前提示确认，避免静默返回错误结果。
+- 动态参数会按当前卡片的实际配置解析，多个卡片使用不同参数时不再相互干扰。
+- 认证状态检查会遵循当前 Profile，帮助 Agent 准确确认正在操作的目标环境。
+
 ### @guandata/guancli 1.0.44
 
 - 指标搜索支持多个关键词，并可同时匹配指标名称、业务口径和业务属性，结果会说明命中位置和优先级。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guancli",
-  "version": "1.0.44",
+  "version": "1.0.45",
   "description": "观远 BI 命令行工具 - 通过 API 操作 ETL、数据集、页面、表单等资源，并提供 ChatBI 问数/洞察能力",
   "bin": {
     "guancli": "bin/run.js"

package/skills/guancli/SKILL.md

@@ -44,6 +44,7 @@ guancli 是 BI 资源的**查询分析入口**，并支持 Form 表单填报 CRU
 3. 先判断资源类型：ETL 用 `etl`，数据集用 `ds`，页面/仪表板用 `page`，卡片用 `card`，表单填报用 `form`。
 4. 信息不全时先 `tree` 或 `search`，拿到 ID 后再 `get`；目录名能出现在 `ds tree`，不代表同词一定能命中 `ds search`。
 5. 用户给的是业务目录名而不是数据集名时，先 `ds tree` 定位目录，再在目录内按真实表名搜索，或从已有 `page/card` 反查 `dsId`。
+6. 用户要求查询卡片数据，但没有说明是否沿用页面筛选上下文时，主动询问“是否应用该卡片关联筛选器的默认筛选条件”。用户确认后使用 `card preview <cd_id> --with-default-filters`；用户明确不要、已经给出筛选条件或已明确要求使用默认条件时，不重复询问。卡片属于多个页面时，根据报错列出的候选页面请用户确认，再传 `--page-id <pg_id>`。
 
 ## 按需读取资料
 
@@ -73,6 +74,7 @@ guancli page get <resource_id>
 guancli ds preview <ds_id> --limit 20
 guancli card get <cd_id>
 guancli card preview <cd_id> --value-format raw -f csv
+guancli card preview <cd_id> --with-default-filters
 ```
 
 > `ds get` / `page get` / `etl get` 拉取完整资源详情（默认还会附血缘），在大环境上

package/skills/guancli/references/auth-and-config.md

@@ -52,8 +52,12 @@ guancli auth remove staging                      # 删除 staging 环境
 ```bash
 guancli --profile staging etl tree
 guancli --profile staging chatbi list-theme
+GUANCLI_PROFILE=staging guancli auth status
+GUANCLI_PROFILE=staging guancli etl tree
 ```
 
+显式的子命令 `--profile` 优先于根级 `--profile` / `GUANCLI_PROFILE`；未指定时才使用配置中的默认环境。高层 skill（如 `guanetl`）使用 `GUANCLI_PROFILE` 绑定当前进程链，不修改机器级默认环境。
+
 ### ChatBI 配置
 
 ChatBI 统一复用当前 profile 的 `base_url` 和 `uIdToken`。

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

@@ -88,6 +88,7 @@ guancli card preview <cd_id> -f csv     # 导出 CSV 到 stdout
 guancli card preview <cd_id> -f csv -o card.csv # 导出 CSV 到文件
 guancli card preview <cd_id> -f excel -o card.xls # 导出 Excel 可打开文件
 guancli card preview <cd_id> --value-format raw -f csv # 保留原始数值，适合 AI 后续计算
+guancli card preview <cd_id> --with-default-filters # 应用所在页面关联选择器的默认条件
 ```
 
 卡片 ID (cdId) 可通过 `page get` 命令查看页面详情获取。
@@ -111,10 +112,28 @@ guancli card preview <complex_report_pro_cd_id> --filter "周 toWeek EQ 2026-W01
 
 字段类型会自动从卡片关联的数据集 schema 推断。日期粒度筛选需配合 `card get` 查看字段配置中的筛选器字段名和粒度。
 
+### 应用页面关联筛选器的默认条件
+
+图表卡片默认只按卡片自身配置取数，不会隐式继承页面筛选上下文。需要得到与页面首次打开时一致的结果，可显式传入 `--with-default-filters`。CLI 会读取卡片所属页面，找出通过 `asFilter.columnMappings` 关联到该卡片的选择器，并将默认字段筛选或动态参数一并传给卡片数据接口；整个过程只依赖卡片和页面元信息，不会查询需要数据集管理权限的全局动态参数接口。
+
+```bash
+guancli card preview <cd_id> --with-default-filters
+guancli card preview <cd_id> --with-default-filters --page-id <pg_id>
+guancli card preview <cd_id> --with-default-filters --filter "区域 EQ 华南"
+guancli card preview <cd_id> --with-default-filters --dynamic-param "结束日期=2026-07-24"
+```
+
+- 卡片元信息只关联一个页面时自动使用该页面；关联多个页面时必须用 `--page-id` 明确上下文。
+- 显式 `--filter` 或 `--dynamic-param` 会覆盖相同 `fdId` 或 `dpId` 的页面默认值，其他默认条件仍然保留。
+- 首版支持普通固定值、多选、日期范围、后端已经解析出实际区间的时间宏，以及动态参数选择器。
+- 树、组合、`FIRST_PICK`、`autoLink`、聚合/结果级映射、依赖其他选择器的级联运行态、必填但无默认值，以及无法从页面元信息确定实际值或目标映射的默认条件均 fail closed：CLI 在查询卡片数据前明确报错，不会静默忽略后继续执行。
+- 多个选择器写入同一字段或动态参数、时间宏目标形态不明确、动态参数默认值包含逗号等可能产生歧义的情况同样会停止查询。
+- 该参数仅适用于 CHART 图表卡片；复杂报表 Pro、选择器和其他卡片类型暂不支持。
+
 ### 带动态参数预览图表卡片
 
 图表卡片 preview 支持通过 `--dynamic-param` 覆盖 BI 全局动态参数，格式为 `参数名=值` 或 `dpId=值`，可多次指定。
-CLI 会查询 `/api/dynamic-parameter/query` 补全参数元数据，并把完整 `dynamicParams` 传给 `/api/card/{cdId}/data`。
+CLI 优先从当前卡片元数据补全参数，并把完整 `dynamicParams` 传给 `/api/card/{cdId}/data`。卡片已声明动态参数时，只接受当前卡片实际使用的参数；仅对完全没有内嵌参数元数据的旧卡片，才兼容回退查询 `/api/dynamic-parameter/query`。因此普通查看账号可直接覆盖当前卡片实际使用的动态参数，不依赖全局参数管理权限，也不会把同名或近似名称的无关全局参数静默传给卡片。
 该能力仅支持 CHART 图表卡片；数据集 preview 当前后端接口不消费动态参数，暂不支持。
 多选参数值沿用 BI 前端约定，使用英文逗号拼接成一个字符串传入。