@guandata/guancli 1.0.43 → 1.0.45

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## @guandata/guancli 1.0.45 - 2026-07-28
+
+- `auth status` 现在遵循根级 `--profile` 与 `GUANCLI_PROFILE`，可可靠核验高层 skill 当前进程链使用的目标环境。
+- 卡片预览支持应用所在页面的默认筛选条件，覆盖常用选择器、日期粒度和动态参数；遇到多页面或无法确定的映射时会提前提示确认，避免静默返回错误结果。
+- 动态参数会按当前卡片的实际配置解析，多个卡片使用不同参数时不再相互干扰。
+
+## @guandata/guancli 1.0.44 - 2026-07-25
+
+- 指标搜索支持多个关键词，并可同时匹配指标名称、业务口径和业务属性，结果会说明命中位置和优先级。
+- 表单业务字段与系统展示列同名时可正确读取和写入，系统只读列会提前给出明确提示。
+- 优化 Agent 的资源查询策略，优先使用轻量字段查询，减少大型环境中的等待和超时。
+
 ## @guandata/guancli 1.0.43 - 2026-07-23
 
 - Token 登录引导和状态校验更准确，减少配置错误或失效凭证造成的反复排查。

package/README.md

@@ -41,6 +41,18 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.45
+
+- 卡片预览支持应用所在页面的默认筛选条件，覆盖常用选择器、日期粒度和动态参数；遇到多页面或无法确定的映射时会提前提示确认，避免静默返回错误结果。
+- 动态参数会按当前卡片的实际配置解析，多个卡片使用不同参数时不再相互干扰。
+- 认证状态检查会遵循当前 Profile，帮助 Agent 准确确认正在操作的目标环境。
+
+### @guandata/guancli 1.0.44
+
+- 指标搜索支持多个关键词，并可同时匹配指标名称、业务口径和业务属性，结果会说明命中位置和优先级。
+- 表单业务字段与系统展示列同名时可正确读取和写入，系统只读列会提前给出明确提示。
+- 优化 Agent 的资源查询策略，优先使用轻量字段查询，减少大型环境中的等待和超时。
+
 ### @guandata/guancli 1.0.43
 
 - Token 登录引导和状态校验更准确，减少配置错误或失效凭证造成的反复排查。

package/package.json

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

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,13 +74,21 @@ 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` 拉取完整资源详情（默认还会附血缘），在大环境上
+> 可能明显偏慢甚至超时。只想了解数据集字段结构（做卡片/仪表板前的探查）时，
+> 优先用 `guands dataset fields <ds_id>`（轻量、秒回）；详情确需查看时先加
+> `--brief` 跳过血缘。命令超时时不要原样重试——换轻量命令或转后台执行。
+
 详细筛选、输出、动态参数和复杂报表 Pro 行为见 `references/preview-and-output.md`。
 
 ## 指标关键规则
 
 - 普通指标数据查询用 `guancli metric query <metric_id>`，可加 `--dim`、`--filter`、排序、列筛选、输出格式等。
+- 搜索指标支持两种方式：`guancli metric search <keyword>` 按指标名称模糊搜索；`guancli metric search --fuzzy <keyword>` 同时按指标名称、业务口径、自定义业务属性值做 OR 模糊搜索，可多次传参，命中优先级为 name=1、desc=2、bizAttr=3。`[keyword]` 和 `--fuzzy` 互斥。
+- 回答指标搜索结果时，必须逐条说明“命中的指标”和“命中方式”：至少包含指标 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>`。
 - 当用户要创建、编辑、删除指标，创建指标主题/目录，批量标准化指标 Excel，或管理公共维度时，切换到 `guanmetric`。

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/metric-commands.md

@@ -57,7 +57,7 @@ guancli metric project 经营 --profile default --raw
 
 ### metric search
 
-搜索指标；传关键词时后台用 `%keyword%` 模糊匹配，不传关键词返回所有指标。
+搜索指标；传 `[keyword]` 时按指标名称模糊搜索，不传关键词返回所有指标。使用 `--fuzzy` 时，后台会同时按指标名称、业务口径和自定义业务属性值做 OR 模糊搜索。
 
 ```bash
 guancli metric search [keyword] [flags]
@@ -68,13 +68,33 @@ guancli metric search [keyword] [flags]
 | 参数 | 说明 |
 | --- | --- |
 | `-d, --dir-id string` | 限定搜索主题 ID |
+| `--fuzzy strings` | 名称、业务口径、自定义业务属性统一模糊搜索关键词，可多次指定，也支持逗号、中文逗号、顿号分隔；和 `[keyword]` 互斥 |
+
+`--fuzzy` 语义：
+
+- 多个关键词之间是 OR，命中任意关键词即返回。
+- 对每个指标按优先级返回最高优先级命中：`matched by name` = 1，`matched by desc` = 2，`matched by bizAttr` = 3。
+- 自定义业务属性值统一模糊匹配；后端只匹配启用且可搜索的业务属性。
+- 结果会在原有指标字段基础上增加命中条件、命中优先级和命中关键词。
+- `[keyword]` 走旧指标名称搜索接口；`--fuzzy` 走新的统一模糊搜索接口，二者不能同时使用。
+
+回答要求：
+
+- 必须逐条返回命中的指标，至少包含指标 ID、指标名称、状态、类型。
+- 必须明确说明每条结果是通过什么方式命中的：命中条件/字段、命中优先级、命中关键词。
+- 不要把用户输入默认解释为“指标名称精确匹配”。例如用户说“查询 api_test 主题下的啦啦啦指标”，应表述为“用 `--fuzzy 啦啦啦` 在 api_test 主题内搜索，以下指标命中”，再说明是命中名称、业务口径还是业务属性。
+- 如果同一关键词命中多个指标，必须列出所有命中指标，不要只挑一个继续做详情或数据查询，除非用户明确要求。
 
 示例：
 
 ```bash
+guancli metric search --fuzzy 订购 --profile default -d <metric_topic_id>
+guancli metric search --fuzzy 订购 --profile default -f json
 guancli metric search 订购 --profile default -d <metric_topic_id>
 guancli metric search 订购 --profile default -f json
-guancli metric search 订购 --profile default --raw
+guancli metric search --fuzzy "收入,GMV" --profile default -d <metric_topic_id>
+guancli metric search --fuzzy 收入 --fuzzy GMV --profile default -f json
+guancli metric search --fuzzy 订购 --profile default --raw
 ```
 
 ### metric get

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 前端约定，使用英文逗号拼接成一个字符串传入。