@guandata/guancli 1.0.21 → 1.0.22

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## @guandata/guancli 1.0.22 - 2026-05-15
+
+- 增强文件下载类 API 能力，支持页面截图等二进制结果稳定写入本地文件。
+- 补充能力边界与 ETL preview 0 行排查说明，便于区分只读分析、看板构建、ETL 编辑和数据集管理等使用场景。
+- 优化命令执行稳定性，避免后台辅助任务影响主命令响应。
+
 ## @guandata/guancli 1.0.21 - 2026-05-14
 
 - 修复 CLI 运行时错误输出会附带 usage 帮助的问题，使实际错误信息更清晰。

package/README.md

@@ -0,0 +1,52 @@
+# @guandata/guancli
+
+观远 BI 命令行工具，用于查看、搜索、预览和诊断 BI 资源，并提供 ChatBI 问数/洞察能力。
+
+## 安装
+
+```bash
+npm install -g @guandata/guancli
+```
+
+也可以直接使用：
+
+```bash
+npx @guandata/guancli auth login
+```
+
+## 常用命令
+
+```bash
+guancli auth login
+guancli auth whoami
+guancli etl tree
+guancli etl get <resource_id>
+guancli ds search <keyword>
+guancli ds preview <ds_id>
+guancli page get <page_id>
+guancli card preview <card_id>
+guancli chatbi query --theme-name "经营主题" --message "最近30天营业收入是多少？"
+```
+
+## 版本更新
+
+### 1.0.22
+
+- 增强文件下载类 API 能力，支持页面截图等二进制结果稳定写入本地文件。
+- 补充能力边界与 ETL preview 0 行排查说明，便于区分只读分析、看板构建、ETL 编辑和数据集管理等使用场景。
+- 优化命令执行稳定性，避免后台辅助任务影响主命令响应。
+
+### 1.0.21
+
+- 修复 CLI 运行时错误输出会附带 usage 帮助的问题，使实际错误信息更清晰。
+- 补充相关命令测试，提升错误输出行为的稳定性。
+
+### 1.0.20
+
+- 指标 API 与 `guancli metric` 增加泛化查询能力，支持更灵活的指标查询场景。
+- 卡片预览能力增强，提高预览数据量上限，并新增 Excel 导出支持。
+
+### 1.0.19
+
+- 支持显式指定配置目录，便于在脚本、多环境或隔离运行场景中加载指定配置。
+- 补充配置目录相关测试，提升配置加载行为的稳定性。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guancli",
-  "version": "1.0.21",
+  "version": "1.0.22",
   "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。若用户希望直接分析 BI 项目而不是手工点页面，或希望直接通过 ChatBI 进行主题问数/洞察分析，也应优先使用这个 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 视觉验证走 guanvis-skill screenshot；管理员级 SVC SQL / 动态码走 guanadmin-skill。若用户希望直接分析 BI 项目而不是手工点页面，或希望直接通过 ChatBI 进行主题问数/洞察分析，也应优先使用这个 skill。
 compatibility: Requires Node.js 14+. Install via npm install -g @guandata/guancli.
 ---
 
@@ -15,7 +15,7 @@ compatibility: Requires Node.js 14+. Install via npm install -g @guandata/guancl
 - 用户需要对表单填报(Form)数据进行 CRUD 操作（查询/插入/更新/删除）。
 - 用户要直接用 ChatBI 主题做 L1 问数或 L2 洞察，而不是打开网页手工操作。
 
-如果用户只想导出 PNG / PDF 成品，不要用本 skill，改用 `guanexport-skill`。
+如果用户只想生成页面 PNG 截图成品，不要用本 skill，改用 `guanvis-skill screenshot`。页面截图不要再走 `guanexport-skill`；移动端页面/卡片导出仍暂用 `guanexport-skill` legacy 功能。
 
 ## 数据获取方式
 
@@ -75,6 +75,18 @@ ChatBI 统一复用当前 profile 的 `base_url` 和 `uIdToken`。
 - 不需要第二套 token / cookie
 - `guancli` 会在内部自动推导并探测可用的 ChatBI Public API 地址，默认优先尝试同域名下的 `/api/chat/public-api`
 
+## 能力边界
+
+guancli 是 BI 资源的**只读分析入口**（Form 表单填报例外）。写入类任务由专用 skill 负责：
+
+| 任务 | 应使用的工具 |
+|------|-------------|
+| ETL 新建 / 编辑 / 保存 / 执行 | `guanetl-skill` |
+| 数据源 / 数据集 CRUD / 增量 / 调度 | `guands-skill` |
+| 看板 / 卡片构建 / 页面发布 / 截图 | `guanvis-skill` |
+
+> guancli 能显示 ETL 的节点定义和 SQL，但 ETL 的新建、修改、保存、执行闭环应通过 `guanetl-skill` 完成。
+
 ## 先做判断
 
 1. 先用 `auth status` 确认认证是否有效。
@@ -416,6 +428,12 @@ guancli --raw etl get <id>
 
 ## 故障排查
 
+### ETL preview 返回 0 行
+
+0 行是合法结果，不一定是错误。排查顺序：
+1. 确认输入数据集有数据：`guancli ds preview <dsId> --limit 5`
+2. 如果节点有 FILTER_ROWS 或 WHERE 条件，临时简化后再 preview
+
 ### Token 过期 / API 401
 
 密码登录方式会自动刷新。如果仍然失败，重新登录：