@guandata/guancli 1.0.15 → 1.0.17

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guandata/guancli",
-  "version": "1.0.15",
-  "description": "观远 BI 命令行工具 - 通过 API 操作 ETL、数据集、页面、表单等资源",
+  "version": "1.0.17",
+  "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、资源树、目录、表单填报数据，或给出 ETL ID、dsId、page ID、card ID 想看现有内容时，主动使用这个 skill。即使用户只说"看一下这个 page""贴一下这个 ETL 的 SQL""搜个叫 X 的数据集""这个数据集长啥样""页面卡片用了哪些 ds"，也要触发。它直接调用 BI HTTP API 拉数据并整理成 AI 友好的中文结论，定位是只读分析（Form 表单填报例外，支持 CRUD）。修改 ETL 走 guanetl-skill；新建/改 Card/Page 走 guanvis-skill；数据源/数据集 CRUD/增量/调度走 guands-skill；导出 PNG/PDF 走 guanexport-skill；管理员级 SVC SQL / 动态码走 guanadmin-skill。
+description: 当用户要分析观远 BI / Guandata 的 ETL、数据集、页面/仪表板、卡片、血缘、节点 SQL、资源树、目录、表单填报数据，或给出 ETL ID、dsId、page ID、card ID 想看现有内容时，主动使用这个 skill。即使用户只说"看一下这个 page""贴一下这个 ETL 的 SQL""搜个叫 X 的数据集""这个数据集长啥样""页面卡片用了哪些 ds"，也要触发。它直接调用 BI HTTP API 拉数据并整理成 AI 友好的中文结论，定位是只读分析（Form 表单填报例外，支持 CRUD）。修改 ETL 走 guanetl-skill；新建/改 Card/Page 走 guanvis-skill；数据源/数据集 CRUD/增量/调度走 guands-skill；导出 PNG/PDF 走 guanexport-skill；管理员级 SVC SQL / 动态码走 guanadmin-skill。若用户希望直接分析 BI 项目而不是手工点页面，或希望直接通过 ChatBI 进行主题问数/洞察分析，也应优先使用这个 skill。
 compatibility: Requires Node.js 14+. Install via npm install -g @guandata/guancli.
 ---
 
@@ -13,6 +13,7 @@ compatibility: Requires Node.js 14+. Install via npm install -g @guandata/guancl
 - 用户要快速拿到 ETL 清单、节点 SQL、输入输出数据集血缘。
 - 用户在排查 BI 资源配置、页面卡片定义、接口返回或 lineage 关系。
 - 用户需要对表单填报(Form)数据进行 CRUD 操作（查询/插入/更新/删除）。
+- 用户要直接用 ChatBI 主题做 L1 问数或 L2 洞察，而不是打开网页手工操作。
 
 如果用户只想导出 PNG / PDF 成品，不要用本 skill，改用 `guanexport-skill`。
 
@@ -20,6 +21,8 @@ compatibility: Requires Node.js 14+. Install via npm install -g @guandata/guancl
 
 通过保存的认证信息直接调用 BI HTTP API。
 
+ChatBI 同样复用 `guancli/config.json` 中当前 profile 的认证信息。
+
 ## 首次配置（认证）
 
 ### 方式一：用户名密码登录（推荐）
@@ -61,8 +64,17 @@ guancli auth remove staging                      # 删除 staging 环境
 
 ```bash
 guancli --profile staging etl tree
+guancli --profile staging chatbi list-theme
 ```
 
+### ChatBI 配置
+
+ChatBI 统一复用当前 profile 的 `base_url` 和 `uIdToken`。
+
+- 不需要单独配置 ChatBI URL
+- 不需要第二套 token / cookie
+- `guancli` 会在内部自动推导并探测可用的 ChatBI Public API 地址，默认优先尝试同域名下的 `/api/chat/public-api`
+
 ## 先做判断
 
 1. 先用 `auth status` 确认认证是否有效。
@@ -335,7 +347,29 @@ guancli fetch GET /api/etl/<id>
 guancli fetch POST /api/resource-atlas/<id> '{"resourceTypeName":"DATA_PROCESS_ETL"}'
 ```
 
-### 8. 输出格式控制
+### 8. ChatBI 主题问数 / 洞察
+
+先列主题，再执行问数或洞察；如果用户没有指定主题，不要猜。
+
+```bash
+guancli chatbi list-theme
+guancli chatbi list-theme --insight
+guancli chatbi query --theme-name "经营主题" --message "最近30天营业收入是多少？"
+guancli chatbi query --theme-id "<theme_id>" --message "最近30天营业收入是多少？"
+guancli chatbi insight --theme-name "经营主题" --message "分析最近30天营业收入变化原因"
+guancli chatbi insight --theme-id "<theme_id>" --message "分析最近30天营业收入变化原因" --agent-mode single_agent
+```
+
+规则：
+
+- `list-theme` 输出 markdown 表格
+- `list-theme --insight` 可列出仅用于洞察的主题
+- `query` 输出 L1 markdown，包含解释和结果表格
+- `insight` 输出 L2 markdown；如返回 `GuanViz.json`，CLI 会自动降级成 markdown 表格
+- ChatBI 命令复用当前 profile 的 `uIdToken`
+- 默认超时 300 秒、轮询间隔 2 秒；必要时可传 `--timeout-ms` / `--poll-interval-ms`
+
+### 9. 输出格式控制
 
 `--format` / `-f` 控制 preview 命令的输出格式：
 
@@ -375,6 +409,8 @@ guancli --raw etl get <id>
 - **表单结构**：字段定义表格，包含 fdId、名称、类型、必填/可编辑、选项（LLM 消费核心）；TABLE 类型字段显示 subFmId
 - **表单数据**：表格格式，首列为 rowId（用于 update/delete），后续为字段列；子表查询结果额外包含 `subId` 列（子行主键，update/delete 时用作 rowId 参数）
 - **表单写操作**（add/update/delete）：默认输出 `✓ ...` 文本；`-f json` 时输出结构化 JSON：`{"ok":true,"action":"add","rowId":"...","count":N,"total":N,"failed":N}`。批量插入部分失败时 `ok=false` 且 exit code 非零
+- **ChatBI 主题列表**：markdown 表格，包含 `theme_id`、`theme_name`
+- **ChatBI 问数/洞察**：markdown 文本；图表块会被自动转成表格，便于继续总结
 
 ## 回答风格要求