@guandata/guancli 1.0.14 → 1.0.16

package/package.json

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

package/skills/guancli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: guancli
-description: 当用户提到观远 BI、ETL、数据集、页面/仪表板分析、血缘、节点 SQL、资源树、页面配置排查、表单填报数据操作，或希望直接分析 BI 项目而不是手工点页面时，主动使用这个 skill。它通过直接调用 BI API 获取数据，并把结果整理成适合 AI 消费的中文结论。支持表单 CRUD（类似 Airtable 风格）。
+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,14 +64,24 @@ 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` 确认认证是否有效。
 2. 如果 Token 过期，密码登录方式会自动刷新；Token 方式需重新登录。
 3. 先判断资源类型：ETL 用 `etl`，数据集用 `ds`，页面/仪表板用 `page`，表单填报用 `form`。
 4. 信息不全时先 `tree` 或 `search`，拿到 ID 后再 `get`。
+5. `tree` 和 `search` 语义不同：目录名能出现在 `ds tree`，不代表同词一定能命中 `ds search`。
 
 ## 标准分析流程
 
@@ -87,20 +100,27 @@ guancli etl search                     # 搜索所有 ETL
 guancli etl search 关键词              # 按关键词搜索
 guancli etl search 关键词 -d <dir_id>  # 在指定目录中搜索
 guancli ds search 关键词               # 搜索数据集
+guancli ds search --id <dsId>          # 按数据集 ID 精确查找
+guancli ds search 关键词 --id <dsId>   # 按名称 + ID 组合查找
 guancli page search 关键词             # 搜索页面
 ```
 
+`ds search --id` 使用 `/api/dataset/search` 接口做精确匹配，支持 `--limit` 和 `--offset` 分页。
+
 ### 3. 获取详情（含血缘）
 
 ```bash
 guancli etl get <resource_id>          # ETL 详情（含节点、SQL、血缘）
 guancli ds get <resource_id>           # 数据集详情（含字段结构、血缘）
 guancli ds get <resource_id> --brief   # 数据集轻量输出（省略 Malloy、血缘、公式详情，节省 token）
+guancli ds get <resource_id> --assoc   # 附加显示关联关系摘要（ETL、融合等）
 guancli page get <resource_id>         # 页面详情（含卡片列表、血缘）
 ```
 
 **`--brief` 模式**：省略 Malloy 数据源定义、血缘关系、计算字段公式等高 token 内容，只保留基本信息和字段名/类型列表。适合 AI 在上下文受限时快速了解数据集结构。所有 `get` 子命令均支持此选项。
 
+**`--assoc` 模式**（仅 `ds get`）：在详情末尾追加数据集关联关系摘要，显示关联的 ETL、数据融合等资源。
+
 ### 4. 预览数据集数据
 
 ```bash
@@ -111,6 +131,8 @@ guancli ds preview <ds_id> --raw        # 输出原始 JSON
 
 数据集 ID (dsId) 可通过 `ds tree` 或 `ds search` 获取。
 
+如果用户给的是业务目录名而不是数据集名，优先先 `ds tree` 定位目录，再在目录内按真实表名搜索，或从已有 `page/card` 反查 `dsId`。
+
 #### 带筛选条件预览
 
 通过 `--filter` 参数传入筛选条件，每个 `--filter` 值的格式为 `"列名 操作符 [值]"`。
@@ -325,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 命令的输出格式：
 
@@ -365,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 文本；图表块会被自动转成表格，便于继续总结
 
 ## 回答风格要求