@guandata/guancli 1.0.49 → 1.0.50

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## @guandata/guancli 1.0.50
+
+- 指标查询结果会明确展示是否命中查询加速，命中时可看到相关加速指标信息，便于判断查询效果。
+- 多环境使用时，Agent 可根据 Domain 或 BI 地址定位对应登录环境，减少环境选择错误。
+
 ## @guandata/guancli 1.0.49 - 2026-08-07
 
 - 支持指标查询加速，提升指标查询场景的执行效率与使用体验。

package/README.md

@@ -41,6 +41,11 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.50
+
+- 指标查询结果会明确展示是否命中查询加速，命中时可看到相关加速指标信息，便于判断查询效果。
+- 多环境使用时，Agent 可根据 Domain 或 BI 地址定位对应登录环境，减少环境选择错误。
+
 ### @guandata/guancli 1.0.49
 
 - 支持按 Domain 或 URL 查找 Profile，切换和定位目标环境更方便。

package/package.json

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

package/skills/guancli/SKILL.md

@@ -40,12 +40,14 @@ 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`。三棵 `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>`。
+1. 认证检查和 BI 查询都会联网，密码 profile 或服务端轮换 token 时可能更新本地 token；只在当前任务允许认证刷新时执行。
+2. 多 profile 且已知登录 Domain 或 BI/页面 URL 时，先用 `auth list --domain <domain>` 或 `auth list --url <url>` 找候选；0 个候选时报告无匹配，并让用户明确现有 profile 或授权新建/更新哪个 profile，不能自动登录。多个候选时让用户按 profile 名称明确选择。选定 profile 后，用 `guancli --profile <name> auth status` 验证，并在后续查询中保留同一 `--profile <name>`；只有用户明确要求切换机器级默认环境时才用 `auth use`。
+3. 未指定 profile 线索时，用 `auth status` 确认当前默认环境的认证是否有效；首次配置、PAT、profile 和配置文件细节见 `references/auth-and-config.md`。
+4. 如果 Token 过期，密码登录方式会自动刷新；Token 方式需重新登录。
+5. 先判断资源类型：ETL 用 `etl`，数据集用 `ds`，页面/仪表板用 `page`，卡片用 `card`，表单填报用 `form`。
+6. 信息不全时先 `tree` 或 `search`，拿到 ID 后再 `get`；目录名能出现在 `ds tree`，不代表同词一定能命中 `ds search`。三棵 `tree` 都支持 `--max-depth N` / `--keyword 词`（客户环境目录树可达数千节点，全量输出会被截断，默认先 `--max-depth 2` 再按需加深）。
+7. 用户给的是业务目录名而不是数据集名时，先 `ds tree` 定位目录，再在目录内按真实表名搜索，或从已有 `page/card` 反查 `dsId`。
+8. 用户要求查询卡片数据，但没有说明是否沿用页面筛选上下文时，主动询问“是否应用该卡片关联筛选器的默认筛选条件”。用户确认后使用 `card preview <cd_id> --with-default-filters`；用户明确不要、已经给出筛选条件或已明确要求使用默认条件时，不重复询问。卡片属于多个页面时，根据报错列出的候选页面请用户确认，再传 `--page-id <pg_id>`。
 
 ## 按需读取资料
 
@@ -89,7 +91,7 @@ guancli insight card <cd_id> --page-id <page_id>
 
 ## 指标关键规则
 
-- 普通指标数据查询用 `guancli metric query <metric_id>`，可加 `--dim`、`--filter`、排序、列筛选、输出格式等；未指定 `-o/--output` 且结果超过 1000 行时会自动写入 `metric_<metricId>_<timestamp>.<ext>`。
+- 普通指标数据查询用 `guancli metric query <metric_id>`，可加 `--dim`、`--filter`、排序、列筛选、输出格式等；未指定 `-o/--output` 且结果超过 1000 行时会自动写入 `metric_<metricId>_<timestamp>.<ext>`。回答指标数据查询结果时，必须检查输出中的 `查询加速` summary 或 `_queryAccelerate` 列：命中时明确说明“本次查询命中查询加速”，并列出源指标 ID、加速指标 ID 和优先级；未命中时说明“未命中查询加速”；如果显示 `未知: 后端未返回`，说明当前后端未返回命中 metadata，不能推断是否命中。
 - 搜索指标支持两种方式：`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`。
@@ -164,5 +166,6 @@ guancli --raw insight agent ask <agent_id> --session-id <session_id> --expert-id
 
 - 用中文输出，优先给“可执行结论”。
 - 不只贴原始命令结果，必须做逻辑归纳（按链路/主题）。
+- 对 `guancli metric query` 的结果，必须在结论中单独交代查询加速命中情况；如果命中，必须点名具体加速指标 ID，不能只说“用了加速”。
 - 涉及时间相关信息时给出明确日期。
 - 如果用户给的是模糊对象名，先说明你是如何定位到具体资源 ID 的。

package/skills/guancli/references/metric-commands.md

@@ -163,6 +163,15 @@ guancli metric by-dataset <ds_id> --profile default --raw
 
 查询指标数据，支持维度、筛选、排序、列筛选和行数限制。泛化查询参数见 `metric-generic-query.md`。
 
+非 `--raw` 输出会展示本次查询是否命中查询加速：summary 中有 `查询加速`，数据行中有 `_queryAccelerate`。命中时展示源指标 ID、加速指标 ID 和优先级，例如 `metric_xxx->acc_xxx(优先级1)`；未命中时显示 `否`。若后端版本尚未返回查询加速 metadata，则显示 `未知: 后端未返回`。
+
+回答要求：
+
+- 必须单独说明本次查询加速命中情况。
+- 命中时必须明确列出命中的加速指标 ID、对应源指标 ID 和优先级。
+- 未命中时说明未命中查询加速。
+- 如果是 `未知: 后端未返回`，只能说明后端未返回命中 metadata，不能推断是否命中。
+
 ```bash
 guancli metric query <metric_id> [flags]
 ```