@guandata/guancli 1.0.23 → 1.0.24

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## @guandata/guancli 1.0.24 - 2026-05-20
+
+- 新增卡片预览数据分页能力，提升大数据量预览时的可用性与稳定性。
+- 修复 `ds get` 对 `virtualColumns` 计算字段的统计和展示，数据集信息输出更完整。
+- 当 API 返回“资源不存在”时，错误信息会追加当前 `profile` 提示，便于排查环境或账号配置问题。
+- 改进 Windows npm 启动脚本，在执行 Go 二进制前切换控制台为 UTF-8，减少中文输出乱码。
+- 更新文档中的命令命名，适配去除 `-skill` 后缀后的包与 CLI 使用方式。
 ## @guandata/guancli 1.0.23 - 2026-05-18
 
 - 新增 workflow 相关只读分析入口，支持查看和诊断工作流资源。

package/README.md

@@ -30,6 +30,14 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### 1.0.24
+
+- 新增卡片预览数据分页能力，提升大数据量预览时的可用性与稳定性。
+- 修复 `ds get` 对计算字段的统计和展示，数据集信息输出更完整。
+- 当 API 返回“资源不存在”时，错误信息会追加当前 `profile` 提示，便于排查环境或账号配置问题。
+- 改进 Windows npm 启动脚本，减少中文输出乱码。
+- 更新文档中的命令命名，适配去除 `-skill` 后缀后的包与 CLI 使用方式。
+
 ### 1.0.23
 
 - 新增 workflow 相关只读分析入口，支持查看和诊断工作流资源。

package/bin/run.js

@@ -2,7 +2,7 @@
 
 "use strict";
 
-const { execFileSync, spawnSync } = require("child_process");
+const { execFileSync, execSync, spawnSync } = require("child_process");
 const path = require("path");
 const fs = require("fs");
 
@@ -70,6 +70,10 @@ try {
   // chmod may fail in read-only environments; binary might already be executable
 }
 
+if (process.platform === "win32") {
+  try { execSync("chcp 65001", { stdio: "ignore" }); } catch (_) {}
+}
+
 try {
   execFileSync(binary, process.argv.slice(2), {
     stdio: "inherit",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guancli",
-  "version": "1.0.23",
+  "version": "1.0.24",
   "description": "观远 BI 命令行工具 - 通过 API 操作 ETL、数据集、页面、表单等资源，并提供 ChatBI 问数/洞察能力",
   "bin": {
     "guancli": "bin/run.js"
@@ -35,7 +35,7 @@
     "node": ">=14"
   },
   "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
+    "access": "public",
+    "registry": "https://app.mayidata.com/nexus/repository/guandata-web/"
   }
 }

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 视觉验证走 guanvis-skill screenshot；管理员级 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；新建/改 Card/Page 走 guanvis；数据源/数据集 CRUD/增量/调度走 guands；页面 PNG 视觉验证走 guanvis screenshot；管理员级 SVC SQL / 动态码走 guanadmin。若用户希望直接分析 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 截图成品，不要用本 skill，改用 `guanvis-skill screenshot`。页面截图不要再走 `guanexport-skill`；移动端页面/卡片导出仍暂用 `guanexport-skill` legacy 功能。
+如果用户只想生成页面 PNG 截图成品，不要用本 skill，改用 `guanvis screenshot`。页面截图不要再走 `guanexport`；移动端页面/卡片导出仍暂用 `guanexport` legacy 功能。
 
 ## 数据获取方式
 
@@ -81,11 +81,11 @@ guancli 是 BI 资源的**只读分析入口**（Form 表单填报例外）。
 
 | 任务 | 应使用的工具 |
 |------|-------------|
-| ETL 新建 / 编辑 / 保存 / 执行 | `guanetl-skill` |
-| 数据源 / 数据集 CRUD / 增量 / 调度 | `guands-skill` |
-| 看板 / 卡片构建 / 页面发布 / 截图 | `guanvis-skill` |
+| ETL 新建 / 编辑 / 保存 / 执行 | `guanetl` |
+| 数据源 / 数据集 CRUD / 增量 / 调度 | `guands` |
+| 看板 / 卡片构建 / 页面发布 / 截图 | `guanvis` |
 
-> guancli 能显示 ETL 的节点定义和 SQL，但 ETL 的新建、修改、保存、执行闭环应通过 `guanetl-skill` 完成。
+> guancli 能显示 ETL 的节点定义和 SQL，但 ETL 的新建、修改、保存、执行闭环应通过 `guanetl` 完成。
 
 ## 先做判断
 
@@ -203,7 +203,7 @@ guancli ds preview <ds_id> --columns "id,name,status"         # 只显示指定
 guancli ds preview <ds_id> --filter "status EQ FAILED" --sort-desc id --columns "id,task_name"
 ```
 
-- `--sort-asc` / `--sort-desc`: 互斥，只能指定一个列。ds preview 的排序通过 API 在数据库层面执行；card preview 的排序在 Go 端对返回数据执行，排序取数下限为 10000 行，服务端结果仍被截断时会拒绝排序。
+- `--sort-asc` / `--sort-desc`: 互斥，只能指定一个列。ds preview 的排序通过 API 在数据库层面执行；card preview 的排序在 Go 端对本次取数范围执行，排序取数下限为 10000 行，若卡片总行数超过本次取数范围，不承诺全量 Top N。
 - `--columns`: 逗号分隔的列名列表，只显示指定列（Go 端执行）。
 
 ### 5. 获取卡片数据
@@ -213,10 +213,12 @@ guancli card get <cd_id>                # 获取卡片元信息
 guancli card preview <cd_id>            # 预览卡片数据 (图表默认最多 10000 行；选择器未排序时保留服务端默认)
 guancli card preview <cd_id> --limit 20 # 限制预览行数
 guancli card preview <cd_id> -f csv     # 导出 CSV 到 stdout
-guancli card preview <cd_id> -f excel > card.xls # 导出 Excel 可打开文件
+guancli card preview <cd_id> -f csv -o card.csv # 导出 CSV 到文件
+guancli card preview <cd_id> -f excel -o card.xls # 导出 Excel 可打开文件
 ```
 
 卡片 ID (cdId) 可通过 `page get` 命令查看页面详情获取。
+图表卡片内部会按 BI 预览接口的分页能力自动取数；选择器/树状选择器仍使用服务端单次返回。任意卡片预览结果在未指定 `-o/--output` 且超过 1000 行时，默认写入 `card_<cdId>_<timestamp>.<ext>` 文件，避免把大结果直接塞入上下文。该能力不对接 BI 导出任务接口。
 
 #### 带筛选条件预览卡片