@guandata/guancli 1.0.46 → 1.0.48

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## @guandata/guancli 1.0.48 - 2026-08-04
+
+- 支持直接基于已有仪表板或智能洞察卡片生成洞察结果，可应用筛选条件并选择分析思路。
+- 新增仪表板智能体问答，可选择专家、继续追问并查看历史会话。
+- 修复指标查询排序，升序和降序配置可正确生效。
+
+## @guandata/guancli 1.0.47 - 2026-07-29
+
+- 卡片预览筛选支持使用卡片内重命名后的表头，也可继续使用数据集原始字段名。
+
 ## @guandata/guancli 1.0.46 - 2026-07-29
 
 - 指标树支持按树名称和指标名称定位拆解子树，可直接查看指定指标下已配置的关联指标。

package/README.md

@@ -41,6 +41,16 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.48
+
+- 支持直接基于已有仪表板或智能洞察卡片生成洞察结果，可应用筛选条件并选择分析思路。
+- 新增仪表板智能体问答，可选择专家、继续追问并查看历史会话。
+- 修复指标查询排序，升序和降序配置可正确生效。
+
+### @guandata/guancli 1.0.47
+
+- 卡片预览筛选支持使用卡片内重命名后的表头，也可继续使用数据集原始字段名。
+
 ### @guandata/guancli 1.0.46
 
 - 指标树支持按树名称和指标名称定位拆解子树，可直接查看指定指标下已配置的关联指标。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guancli",
-  "version": "1.0.46",
+  "version": "1.0.48",
   "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。若用户希望直接分析 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.
 ---
 
@@ -19,6 +19,7 @@ guancli 是 BI 资源的查询分析入口，并支持 Form 表单填报 CRUD、
 - 用户要搜索指标、获取指标详情、查询指标数据、查看指标目录、执行指标树归因，或让你生成/解释指标泛化查询命令。
 - 用户给出数据集 ID，想查看该数据集创建或影响到的所有指标，包括直接原子指标以及下游复合指标、衍生指标。
 - 用户要创建超级应用 / SuperApp / SuperApp 模板项目。
+- 用户要为已有仪表板或智能洞察卡片生成智能洞察结果。
 
 如果用户只想生成页面 PNG 截图成品，不要用本 skill，改用 `guanvis screenshot`。
 
@@ -75,6 +76,8 @@ 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
+guancli insight page <page_id>
+guancli insight card <cd_id> --page-id <page_id>
 ```
 
 > `ds get` / `page get` / `etl get` 拉取完整资源详情（默认还会附血缘），在大环境上
@@ -105,6 +108,58 @@ guancli app create --name <project_name> --path <parent_dir>
 - 该命令会下载 SuperApp 模板并创建项目目录，随后尝试复制 `.env.template`、更新 `package.json` 名称、初始化 git，并根据模板情况执行 `setup.sh` 或 `npm install` + 启动本地 dev server。
 - 如果用户只是要创建本地 SuperApp 模板项目，不需要先做 BI 资源查询；直接给出或执行 `guancli app create`。
 
+## 仪表板、卡片智能洞察
+
+```bash
+guancli insight inspect <page_id>
+guancli insight page <page_id>
+guancli insight page <page_id> --selector "<selector_id>=<value>" --locale zh-CN
+guancli insight page <page_id> --analysis-id <analysis_id>
+guancli insight card <cd_id> --page-id <page_id>
+guancli insight card <cd_id> --page-id <page_id> --selector "<selector_id>=<value>" --locale zh-CN
+```
+
+- 复用当前 profile 的 uIdToken，当前等待完整非流式结果。
+- `insight inspect` 输出洞察开关、分析思路 ID/名称和页面关联的 LLM 配置；不输出提示词正文，筛选器继续通过 `page get` / `card get` 查看。
+- 页面洞察仅支持已开启智能洞察的普通仪表板（`pgType=PAGE`）；数据大屏、智能归因、分析报告等页面类型不支持。
+- 卡片洞察必须同时提供卡片所属页面 ID，且仅支持 `cdType=INTELLIGENT_INSIGHT` 的智能洞察卡片。
+- `--selector` 使用页面筛选器 ID；同一 ID 需要多个值时重复传入。CLI 会先确认该 ID 是页面筛选器，再生成洞察。
+- 页面洞察可通过 `--analysis-id` 或 `--analysis-name` 指定分析，两者不能同时使用。
+- CLI 会先校验页面权限与类型、洞察开关、卡片归属与类型、筛选器和指定分析，预检通过后才发起生成请求。
+- 页面或卡片智能洞察 `/generate` 接口明确返回 404/405 时，CLI 会提示升级 BI。
+- 默认只输出洞察正文；需要完整响应时使用 `--raw`。
+
+主流程：
+
+1. 先执行 `guancli auth status`；认证失效时重新登录。
+2. 没有页面 ID 时执行 `guancli page search <页面关键词>` 确定页面。
+3. 执行 `guancli insight inspect <page_id>` 查看洞察开关、分析思路和 LLM 配置。
+4. 需要筛选器或卡片 ID 时，执行 `guancli page get <page_id> --brief` 查看页面资源 ID。
+5. 调用页面或卡片洞察命令；需要指定输出语言时增加 `--locale`。
+
+## 仪表板智能体（Dashboard Agent）
+
+```bash
+guancli insight agent list
+guancli insight agent get <agent_id>
+guancli --raw insight agent ask <agent_id> --expert-id <expert_id> --message "分析本月销售额下降的原因"
+guancli insight agent sessions <agent_id>
+guancli insight agent messages <session_id>
+guancli --raw insight agent ask <agent_id> --session-id <session_id> --expert-id <expert_id> --message "继续分析华东区域"
+```
+
+- 与 `chatbi insight` 基于数据集主题的洞察能力相互独立。
+- Agent 和专家均使用 ID 调用；guancli 不负责按名称选择 Agent 或专家。
+- `ask` 会创建消息、等待任务并返回最终回答；默认只输出正文，使用 `--raw` 可取得 `sessionId` 等完整信息。
+- 追问时复用已有 `sessionId`，可以继续使用原专家，也可以指定其他专家。
+
+流程：
+
+1. 用 `list` 获取 Agent，再用 `get <agent_id>` 获取专家并选择对应 ID。
+2. 用 `ask` 发起提问并等待结果；需要继续追问时，使用 `--raw` 保存返回的 `sessionId`。
+3. 用 `sessions` 和 `messages` 查找、查看已有会话。
+4. 携带已有 `sessionId` 再次执行 `ask` 继续追问。
+
 ## 回答风格要求
 
 - 用中文输出，优先给“可执行结论”。