@guandata/guancli 1.0.45 → 1.0.47

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## @guandata/guancli 1.0.47 - 2026-07-29
+
+- 卡片预览筛选支持使用卡片内重命名后的表头，也可继续使用数据集原始字段名。
+
+## @guandata/guancli 1.0.46 - 2026-07-29
+
+- 指标树支持按树名称和指标名称定位拆解子树，可直接查看指定指标下已配置的关联指标。
+- 页面、ETL 等资源目录树支持按关键词和最大深度缩小范围，大型环境中更容易定位目标资源。
+- 更新底层依赖，提升安全性和运行稳定性。
+
 ## @guandata/guancli 1.0.45 - 2026-07-28
 
 - `auth status` 现在遵循根级 `--profile` 与 `GUANCLI_PROFILE`，可可靠核验高层 skill 当前进程链使用的目标环境。

package/README.md

@@ -41,6 +41,16 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.47
+
+- 卡片预览筛选支持使用卡片内重命名后的表头，也可继续使用数据集原始字段名。
+
+### @guandata/guancli 1.0.46
+
+- 指标树支持按树名称和指标名称定位拆解子树，可直接查看指定指标下已配置的关联指标。
+- 页面、ETL 等资源目录树支持按关键词和最大深度缩小范围，大型环境中更容易定位目标资源。
+- 更新底层依赖，提升安全性和运行稳定性。
+
 ### @guandata/guancli 1.0.45
 
 - 卡片预览支持应用所在页面的默认筛选条件，覆盖常用选择器、日期粒度和动态参数；遇到多页面或无法确定的映射时会提前提示确认，避免静默返回错误结果。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guancli",
-  "version": "1.0.45",
+  "version": "1.0.47",
   "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,7 +42,7 @@ 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>`。
 
@@ -60,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 关键词

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 登录。
 
 ### 多环境管理
 

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
 
 对指定指标树执行贡献分析，支持指标拆解、单维度拆解和全维扫描。