@guandata/guancli 1.0.44 → 1.0.46

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## @guandata/guancli 1.0.46 - 2026-07-29
+
+- 指标树支持按树名称和指标名称定位拆解子树，可直接查看指定指标下已配置的关联指标。
+- 页面、ETL 等资源目录树支持按关键词和最大深度缩小范围，大型环境中更容易定位目标资源。
+- 更新底层依赖，提升安全性和运行稳定性。
+
+## @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,18 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.46
+
+- 指标树支持按树名称和指标名称定位拆解子树，可直接查看指定指标下已配置的关联指标。
+- 页面、ETL 等资源目录树支持按关键词和最大深度缩小范围，大型环境中更容易定位目标资源。
+- 更新底层依赖，提升安全性和运行稳定性。
+
+### @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.46",
   "description": "观远 BI 命令行工具 - 通过 API 操作 ETL、数据集、页面、表单等资源，并提供 ChatBI 问数/洞察能力",
   "bin": {
     "guancli": "bin/run.js"

package/skills/guancli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: guancli
-description: 当用户要分析观远 BI / Guandata 的 ETL、数据集、页面/仪表板、卡片、血缘、节点 SQL、资源树、目录、表单填报数据、指标 metric 查询、指标树归因 metric_attribution、指标泛化查询参数，或给出 ETL ID、dsId、page ID、card ID、metric ID、metric tree ID 想看现有内容/查询数据时，主动使用这个 skill。用户提到“创建超级应用”“创建 SuperApp”“新建 SuperApp 项目”“SuperApp 模板项目”时，也要使用这个 skill，并引导使用 `guancli app create`。即使用户只说"看一下这个 page""贴一下这个 ETL 的 SQL""搜个叫 X 的数据集""这个数据集长啥样""页面卡片用了哪些 ds""帮我查这个指标""生成指标泛化查询命令""帮我创建一个超级应用"，也要触发。它直接调用 BI HTTP API 拉数据并整理成 AI 友好的中文结论，定位是 BI 查询分析 + 表单填报 CRUD + 指标查询分析 + SuperApp 模板项目创建。创建/编辑/删除指标、指标主题、指标目录或公共维度走 guanmetric；修改 ETL 走 guanetl；新建/改 Card/Page 走 guanvis；数据源/数据集 CRUD/增量/调度走 guands；页面 PNG 视觉验证走 guanvis screenshot；管理员级 SVC SQL / 动态码走 guanadmin。若用户希望直接分析 BI 项目而不是手工点页面，或希望直接通过 ChatBI 进行主题问数/洞察分析，也应优先使用这个 skill。
+description: 当用户要分析观远 BI / Guandata 的 ETL、数据集、页面/仪表板、卡片、血缘、节点 SQL、资源树、目录、表单填报数据、指标 metric 查询、指标树归因 metric_attribution、指标泛化查询参数，或给出 ETL ID、dsId、page ID、card ID、metric ID、metric tree ID 想看现有内容/查询数据时，主动使用这个 skill。用户提到“创建超级应用”“创建 SuperApp”“新建 SuperApp 项目”“SuperApp 模板项目”时，也要使用这个 skill，并引导使用 `guancli app create`。即使用户只说"看一下这个 page""贴一下这个 ETL 的 SQL""搜个叫 X 的数据集""这个数据集长啥样""页面卡片用了哪些 ds""帮我查这个指标""生成指标泛化查询命令""帮我创建一个超级应用"，也要触发。它直接调用 BI HTTP API 拉数据并整理成 AI 友好的中文结论，定位是 BI 查询分析 + 表单填报 CRUD + 指标查询分析 + SuperApp 模板项目创建。创建/编辑/删除指标、指标主题、指标目录或公共维度走 guanmetric；修改 ETL 走 guanetl；新建/改 Card/Page 走 guanvis；数据源/数据集 CRUD/增量/调度走 guands；页面 PNG 视觉验证走 guanvis screenshot。若用户希望直接分析 BI 项目而不是手工点页面，或希望直接通过 ChatBI 进行主题问数/洞察分析，也应优先使用这个 skill。
 compatibility: Requires Node.js 14+. Install via npm install -g @guandata/guancli.
 ---
 
@@ -42,8 +42,9 @@ guancli 是 BI 资源的**查询分析入口**，并支持 Form 表单填报 CRU
 1. 先用 `auth status` 确认认证是否有效；首次配置、PAT、profile 和配置文件细节见 `references/auth-and-config.md`。
 2. 如果 Token 过期，密码登录方式会自动刷新；Token 方式需重新登录。
 3. 先判断资源类型：ETL 用 `etl`，数据集用 `ds`，页面/仪表板用 `page`，卡片用 `card`，表单填报用 `form`。
-4. 信息不全时先 `tree` 或 `search`，拿到 ID 后再 `get`；目录名能出现在 `ds tree`，不代表同词一定能命中 `ds search`。
+4. 信息不全时先 `tree` 或 `search`，拿到 ID 后再 `get`；目录名能出现在 `ds tree`，不代表同词一定能命中 `ds search`。三棵 `tree` 都支持 `--max-depth N` / `--keyword 词`（客户环境目录树可达数千节点，全量输出会被截断，默认先 `--max-depth 2` 再按需加深）。
 5. 用户给的是业务目录名而不是数据集名时，先 `ds tree` 定位目录，再在目录内按真实表名搜索，或从已有 `page/card` 反查 `dsId`。
+6. 用户要求查询卡片数据，但没有说明是否沿用页面筛选上下文时，主动询问“是否应用该卡片关联筛选器的默认筛选条件”。用户确认后使用 `card preview <cd_id> --with-default-filters`；用户明确不要、已经给出筛选条件或已明确要求使用默认条件时，不重复询问。卡片属于多个页面时，根据报错列出的候选页面请用户确认，再传 `--page-id <pg_id>`。
 
 ## 按需读取资料
 
@@ -59,9 +60,9 @@ guancli 是 BI 资源的**查询分析入口**，并支持 Form 表单填报 CRU
 ## 常用查询入口
 
 ```bash
-guancli etl tree
-guancli ds tree
-guancli page tree
+guancli etl tree --max-depth 2
+guancli ds tree --max-depth 2
+guancli page tree --max-depth 2
 guancli etl search 关键词
 guancli ds search 关键词
 guancli page search 关键词
@@ -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

@@ -32,9 +32,9 @@ guancli auth login
 guancli auth login --url https://bi.example.com --pat <pat>
 ```
 
-交互式登录时选择登录方式 `3`，直接粘贴 Personal Access Token。`--personal-token` 仍可作为长参数使用。PAT 请求会自动携带 `X-Personal-Token`，`X-Guandata-Client` 沿用请求来源（默认 `guancli`；高层 skill 通过 `fetch` 调用时保留其自身来源），`auth status` 会通过 `/api/pat/introspect` 做自检，且仅在响应明确返回 `usable: true`（兼容历史 `active: true`）时判定有效。
+交互式登录时选择登录方式 `3`，直接粘贴 Personal Access Token。`--personal-token` 仍可作为长参数使用。PAT 请求会自动携带 `X-Personal-Token`，`X-Guandata-Client` 沿用请求来源（默认 `guancli`；高层 skill 经内部请求通道调用时保留其自身来源），`auth status` 会通过 `/api/pat/introspect` 做自检，且仅在响应明确返回 `usable: true`（兼容历史 `active: true`）时判定有效。
 
-`chatbi` 子命令仍要求 uIdToken 登录；管理员动态码、管理员登录、SVC 查询等管理员能力由 `guanadmin` 提供，不使用 PAT。
+`chatbi` 子命令仍要求 uIdToken 登录。
 
 ### 多环境管理
 
@@ -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

@@ -216,6 +216,7 @@ guancli metric_attribution [command]
 | `tree` | 获取指标树目录树 |
 | `search` | 搜索指标树 |
 | `get` | 获取指标树详情 |
+| `subtree` | 获取指标树中指定指标的拆解子树 |
 | `query` | 查询指标树贡献数据 |
 
 ### metric_attribution tree
@@ -262,6 +263,33 @@ guancli metric_attribution get <metric_tree_id> --profile test43 -f json
 guancli metric_attribution get <metric_tree_id> --profile test43 --raw
 ```
 
+### metric_attribution subtree
+
+获取某棵指标树已保存配置中的指标拆解子树。该命令只裁剪 `metricRelationTree` 中已有的拆解关系，不会沿全局资源血缘动态推导额外下游指标。
+
+```bash
+guancli metric_attribution subtree [metric_tree_id] [metric_id] [flags]
+```
+
+专属参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `--tree-id string` | 指标树 ID |
+| `--tree-name string` | 指标树名称，需唯一匹配 |
+| `--metric-id string` | 指标拆解起点指标 ID；未指定时默认使用指标树根指标 |
+| `--metric-name string` | 指标拆解起点指标名称，需在该指标树拆解配置中唯一匹配 |
+
+示例：
+
+```bash
+guancli metric_attribution subtree --tree-id <metric_tree_id> --metric-id <metric_id> --profile test43
+guancli metric_attribution subtree <metric_tree_id> <metric_id> --profile test43
+guancli metric_attribution subtree --tree-name "销售额指标树" --metric-name "订单数" --profile test43
+guancli metric_attribution subtree --tree-id <metric_tree_id> -f json --profile test43
+guancli metric_attribution subtree --tree-id <metric_tree_id> --raw --profile test43
+```
+
 ### metric_attribution query
 
 对指定指标树执行贡献分析，支持指标拆解、单维度拆解和全维扫描。

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