@guandata/guancli 1.0.53 → 1.0.54

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## @guandata/guancli 1.0.54 - 2026-08-26
+
+- `app publish` 新增 `--skip-build`，可直接发布可信、已验证的 `dist`，避免服务端重复执行项目构建脚本。
+- SuperApp 发布会在覆盖线上 `setting.json` 前明确确认，未确认时保留线上配置；发布包同时携带预构建产物。
+- 改进指标问数命令说明和资源筛选解析，减少参数生成不稳定、列名未命中却返回全量结果等误导行为。
+- `page get --brief` 会真正省略较大的模型定义；非法输出格式和拼错的二级子命令会明确报错并非零退出。
+- 统一结构化错误输出，保留请求方法、路径、状态码和后端业务错误，自动化流程更容易准确判断失败原因。
+
 ## @guandata/guancli 1.0.53 - 2026-08-25
 
 - 新增 OIDC 登录与安全凭据管理，提升企业统一身份认证、多环境切换和登录状态恢复的稳定性。

package/README.md

@@ -43,6 +43,13 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.54
+
+- SuperApp 发布支持复用可信、已验证的 `dist`，避免服务端因缺少项目本地构建工具而发布失败。
+- 覆盖线上 SuperApp 配置前会明确确认，未确认时保留线上 `setting.json`。
+- 指标问数命令、筛选与列选择更稳定，非法格式或拼错子命令会明确失败。
+- 结构化错误会保留请求位置、状态码和后端业务原因，排障更直接。
+
 ### @guandata/guancli 1.0.53
 
 - 新增 OIDC 登录与安全凭据管理，企业统一身份认证和多环境切换更稳定。

package/package.json

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

package/skills/guancli/SKILL.md

@@ -1,12 +1,12 @@
 ---
 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 模板项目”“下载 SuperApp 整包”时，也要使用这个 skill，并引导使用 `guancli app create` / `guancli app download`。用户要删除、重命名、移动页面时，本 skill 只负责把用户路由到 guanvis（`guanvis page delete/rename/move`），这些命令不在 guancli；被删页面没有任何命令行恢复入口，只能人工登录 BI 网页端还原。即使用户只说"看一下这个 page""贴一下这个 ETL 的 SQL""搜个叫 X 的数据集""这个数据集长啥样""页面卡片用了哪些 ds""帮我查这个指标""生成指标泛化查询命令""帮我创建一个超级应用""把这个页面挪到 XX 目录""删掉这个页面""刚删的页面能找回来吗"，也要触发。它直接调用 BI HTTP API 拉数据并整理成 AI 友好的中文结论，定位是 BI 查询分析 + 表单填报 CRUD + 指标查询分析 + SuperApp 模板项目创建与整包下载。创建/编辑/删除指标、指标主题、指标目录或公共维度走 guanmetric；修改 ETL 走 guanetl；页面**内容**（卡片、布局、筛选器）的新建与修改、以及页面**本身**的删除/改名/移动都走 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 模板项目”“发布 SuperApp”“下载 SuperApp 整包”时，也要使用这个 skill，并引导使用 `guancli app create` / `guancli app publish` / `guancli app download`。用户要删除、重命名、移动页面时，本 skill 只负责把用户路由到 guanvis（`guanvis page delete/rename/move`），这些命令不在 guancli；被删页面没有任何命令行恢复入口，只能人工登录 BI 网页端还原。即使用户只说"看一下这个 page""贴一下这个 ETL 的 SQL""搜个叫 X 的数据集""这个数据集长啥样""页面卡片用了哪些 ds""帮我查这个指标""生成指标泛化查询命令""帮我创建一个超级应用""把这个页面挪到 XX 目录""删掉这个页面""刚删的页面能找回来吗"，也要触发。它直接调用 BI HTTP API 拉数据并整理成 AI 友好的中文结论，定位是 BI 查询分析 + 表单填报 CRUD + 指标查询分析 + SuperApp 模板项目创建、发布与整包下载。创建/编辑/删除指标、指标主题、指标目录或公共维度走 guanmetric；修改 ETL 走 guanetl；页面**内容**（卡片、布局、筛选器）的新建与修改、以及页面**本身**的删除/改名/移动都走 guanvis；数据源/数据集 CRUD/增量/调度走 guands；页面 PNG 视觉验证走 guanvis screenshot。若用户希望直接分析 BI 项目而不是手工点页面，或希望直接通过 ChatBI 进行主题问数/洞察分析，也应优先使用这个 skill。
 compatibility: Requires Node.js 14+. Install via npm install -g --foreground-scripts @guandata/guancli so the AI skill refresh result is visible.
 ---
 
 # guancli
 
-guancli 是 BI 资源的查询分析入口，并支持 Form 表单填报 CRUD、指标查询分析和 SuperApp 模板项目创建与整包下载。页面本身的删除/改名/移动在 `guanvis page`。
+guancli 是 BI 资源的查询分析入口，并支持 Form 表单填报 CRUD、指标查询分析和 SuperApp 模板项目创建、发布与整包下载。页面本身的删除/改名/移动在 `guanvis page`。
 
 ## 何时优先使用
 
@@ -18,7 +18,7 @@ guancli 是 BI 资源的查询分析入口，并支持 Form 表单填报 CRUD、
 - 用户要直接用 ChatBI 主题做 L1 问数或 L2 洞察，而不是打开网页手工操作。
 - 用户要搜索指标、获取指标详情、查询指标数据、查看指标目录、执行指标树归因，或让你生成/解释指标泛化查询命令。
 - 用户给出数据集 ID，想查看该数据集创建或影响到的所有指标，包括直接原子指标以及下游复合指标、衍生指标。
-- 用户要创建超级应用 / SuperApp / SuperApp 模板项目，或要把平台上的 SuperApp 整包下载成本地 zip。
+- 用户要创建、发布或更新超级应用 / SuperApp，或要把平台上的 SuperApp 整包下载成本地 zip。
 - 用户要删除、重命名、移动页面（本 skill 只负责把用户路由到 `guanvis page`，命令不在 guancli）。
 - 用户要为已有仪表板或智能洞察卡片生成智能洞察结果。
 
@@ -26,7 +26,7 @@ guancli 是 BI 资源的查询分析入口，并支持 Form 表单填报 CRUD、
 
 ## 能力边界
 
-guancli 是 BI 资源的**查询分析入口**，并支持 Form 表单填报 CRUD 和 SuperApp 模板项目创建与整包下载。其他写入类任务由专用 skill 负责：
+guancli 是 BI 资源的**查询分析入口**，并支持 Form 表单填报 CRUD 和 SuperApp 模板项目创建、发布与整包下载。其他写入类任务由专用 skill 负责：
 
 | 任务 | 应使用的工具 |
 |---|---|
@@ -141,6 +141,12 @@ guancli 在这条链路上只出只读的那一环：`guancli page search` / `pa
 
 ## 指标关键规则
 
+- **先按下面的命令契约生成，不要猜 shell、jq 或筛选语法**：
+  - jq 访问中文 JSON key 必须写成 `.["字段名"]`，嵌套字段逐级写成 `.["指标详情"]["适用维度"]`；禁止 `.字段名`。
+  - `metric query --filter` 只接受 `EQ`、`NE`、`LT`、`LE`、`GT`、`GE`、`BT`、`IN`、`IS_NULL`、`NOT_NULL`、`CONTAINS`、`NOT_CONTAINS`、`STARTSWITH`、`NOT_STARTSWITH`、`ENDSWITH`、`NOT_ENDSWITH`，禁止使用 `=`、`>=`、`<=`。例如日期下界写 `--filter "日期 GE 2026-01-01"`。
+  - 必须解析的命令不得用 `2>/dev/null` 隐藏 stderr。不要用会让末端命令成功掩盖上游失败的管道；优先拆成“guancli 输出到文件 → 确认命令成功 → jq 读取文件”，必须使用管道时先启用 `set -o pipefail`。
+  - 同类语法错误只允许出现一次；第一次失败后先执行对应命令的 `--help` 或读取本 Skill 的参考文档，再按真实契约纠正，不连续尝试相近写法。
+- 搜索并同时查看业务口径、数据集和适用维度等详情时，优先使用 `guancli metric search --fuzzy <keyword> --limit <N> --with-detail --brief -f json`，不要先 search 再逐个 get，也不要为终端阅读额外拼 jq。只查单个指标详情时优先使用 `guancli metric get <metric_id> --brief`；只裁剪指标查询结果列时使用 `metric query --columns`。可复制模板见 `references/metric-commands.md`。
 - 普通指标数据查询用 `guancli metric query <metric_id>`，可加 `--dim`、`--filter`、排序、列筛选、输出格式等；未指定 `-o/--output` 且结果超过 1000 行时会自动写入 `metric_<metricId>_<timestamp>.<ext>`。回答指标数据查询结果时，必须检查输出中的 `查询加速` summary 或 `_queryAccelerate` 列：命中时明确说明“本次查询命中查询加速”，并列出源指标 ID、加速指标 ID 和页面查询顺序；未命中时说明“未命中查询加速”；如果显示 `未知: 后端未返回`，说明当前后端未返回命中 metadata，不能推断是否命中。注意：输出中的 `优先级N` 来自后端 `acceleratePriority` 排序权重，数字越大越先尝试；不要把它直接解释成页面“查询顺序”。需要和页面对齐时，额外执行 `guancli metric accelerate list <metric_id>`，按 `acceleratePriority` 倒序排列后换算页面查询顺序（倒序第 1 个即页面查询顺序 1）。
 - 搜索指标支持两种方式：`guancli metric search <keyword>` 按指标名称模糊搜索；`guancli metric search --fuzzy <keyword>` 同时按指标名称、业务口径、自定义业务属性值做 OR 模糊搜索，可多次传参，命中优先级为 name=1、desc=2、bizAttr=3。`[keyword]` 和 `--fuzzy` 互斥。需要同时查看每个命中指标的 `metric get` 详情时加 `--with-detail`；默认包含血缘，加 `--brief` 可跳过血缘，结构化详情优先使用 `-f json`。此模式不兼容 `--raw`、CSV 和 Excel 输出，结果很多时先用 search 的 `--limit` 收窄指标数量。指标取数仍单独使用 `metric query`。
 - 回答指标搜索结果时，必须逐条说明“命中的指标”和“命中方式”：至少包含指标 ID、指标名称、命中条件/字段、命中优先级、命中关键词；不要把用户输入默认解释为指标名称精确匹配。如果结果中有“命中条件”“命中优先级”“命中关键词”列，必须原样纳入结论。
@@ -148,7 +154,7 @@ guancli 在这条链路上只出只读的那一环：`guancli page search` / `pa
 - 只要传入 `--compare`、`--compare-value`、`--xtd`、`--last`、`--recent`、`--recent-base`、`--percentage`、`--percentage-dim`、`--rank-top`、`--rank-order`、`--rank-dim`、`--adv-calc-json` 任一参数，就进入指标泛化查询模式。泛化查询要求 BI 版本 `>= 8.2.1`；如需确认环境版本，先执行 `guancli server-version --profile <profile>`。
 - 当用户要创建、编辑、删除指标，创建指标主题/目录，批量标准化指标 Excel，或管理公共维度时，切换到 `guanmetric`。
 
-## SuperApp 项目创建与整包下载
+## SuperApp 项目创建、发布与整包下载
 
 当用户提到创建超级应用、创建 SuperApp、新建 SuperApp 项目或基于 SuperApp 模板初始化项目时，使用：
 
@@ -160,6 +166,20 @@ 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`。
 
+当用户要发布或更新 SuperApp 时，使用：
+
+```bash
+guancli app publish --path <project_dir> --app-id <appId>
+guancli app publish --path <project_dir> --update-if-exists
+guancli app publish --path <project_dir> --app-id <appId> --overwrite-settings
+```
+
+- 更新已有 SuperApp 时，CLI 会在构建后检查实际 `dist/settings.json`。交互终端会询问：“是否覆盖线上 `settings.json`？”发布应用的授权不等于覆盖线上设置的授权。
+- 只有用户明确回答要覆盖时才传 `--overwrite-settings`，或在 CLI 交互提示中回答 `y`。不要仅因为用户要求“发布应用”就自动追加该参数。
+- 用户回答不明确、没有反馈、非交互任务无法取得确认或确认流程异常时，一律按“不覆盖”处理。CLI 在非交互环境默认从待上传 zip 排除根目录的 `dist/settings.json`，继续发布其他静态资源，并在结果的 `settingsAction` 中返回 `preserved`。
+- 创建全新 SuperApp 时线上尚无 `settings.json`，无需询问覆盖；但通过 `--app-id` 更新，或 `--update-if-exists` 命中同名线上应用时，都必须执行上述确认。
+- 如果运行的是不支持该保护的旧版 guancli，不要冒险发布包含 `settings.json` 的更新产物；应先升级 CLI，不能把缺少确认当作同意。
+
 当用户要把平台上已有的 SuperApp 取回本地（备份、比对、排查线上产物）时，使用：
 
 ```bash

package/skills/guancli/evals/evals.json

@@ -0,0 +1,51 @@
+{
+  "skill_name": "guancli",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "帮我查销售额指标。先搜索指标并告诉我适用维度，再按订单日期大于等于 2026-01-01、地区等于华东查询，只保留日期、地区和销售额三列。",
+      "expected_output": "代理应优先用 metric search --with-detail --brief 获取搜索结果及适用维度，metric query 的筛选分别使用 GE 和 EQ，并用 --columns 裁剪结果，不为已有稳定能力额外拼 jq。",
+      "files": [],
+      "expectations": [
+        "搜索命令使用 --with-detail --brief；需要结构化输出时使用 -f json",
+        "日期筛选使用 GE，不使用 >=",
+        "地区筛选使用 EQ，不使用 = 或 ==",
+        "结果列裁剪使用 metric query --columns"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "metric_search.json 是 guancli metric search --with-detail --brief -f json 的结果。请用 jq 提取每个指标的指标 ID、指标名称和指标详情里的适用维度。",
+      "expected_output": "代理生成的 jq 应对所有中文 JSON key 使用方括号加引号的访问方式，并逐级访问指标详情和适用维度。",
+      "files": [],
+      "expectations": [
+        "使用 .[\"指标ID\"] 和 .[\"名称\"]",
+        "嵌套字段使用 .[\"指标详情\"][\"适用维度\"]",
+        "不出现 .指标ID、.名称、.指标详情 或 .适用维度"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "我刚执行 guancli metric query metric_xxx --filter \"日期 >= 2026-01-01\" 失败了。继续帮我查，但不要反复猜语法。",
+      "expected_output": "代理应先查看 metric query --help 或指标命令参考，识别符号操作符应改为 GE，然后只重试正确写法。",
+      "files": [],
+      "expectations": [
+        "失败后先执行 guancli metric query --help 或读取 references/metric-commands.md",
+        "纠正后的筛选为 日期 GE 2026-01-01",
+        "不继续尝试 =、==、> 或 >= 等相近符号写法"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "用 guancli 搜索指标后通过 jq 解析结果。命令或 jq 失败时必须让我看到真实错误，不能把失败当成功。",
+      "expected_output": "代理应保留 stderr 和非零退出码，优先把 guancli JSON 输出保存到文件并确认成功后再运行 jq；若使用管道则启用 pipefail。",
+      "files": [],
+      "expectations": [
+        "必要解析不使用 2>/dev/null",
+        "优先拆开执行 guancli 和 jq 并检查前一步是否成功",
+        "若使用管道，先启用 set -o pipefail",
+        "不会因 jq 或管道末端成功而宣称上游 guancli 成功"
+      ]
+    }
+  ]
+}

package/skills/guancli/references/metric-commands.md

@@ -108,6 +108,23 @@ guancli metric search --fuzzy 收入 --profile default --limit 5 --with-detail -
 guancli metric search --fuzzy 订购 --profile default --raw
 ```
 
+#### 可复制模板：搜索并查看适用维度
+
+优先让 guancli 直接返回标准化详情，终端阅读不需要 jq：
+
+```bash
+guancli metric search --fuzzy <关键词> --profile <profile> --limit 5 --with-detail --brief
+```
+
+确实需要机器处理 JSON 时，先保存成功输出再单独执行 jq，避免管道末端成功掩盖 guancli 失败：
+
+```bash
+guancli metric search --fuzzy <关键词> --profile <profile> --limit 5 --with-detail --brief -f json > metric_search.json &&
+  jq '.[] | {"指标ID": .["指标ID"], "名称": .["名称"], "适用维度": .["指标详情"]["适用维度"]}' metric_search.json
+```
+
+中文 key 必须使用 `.["字段名"]`，嵌套 key 必须逐级引用；不要写 `.指标详情.适用维度`。必要解析不要添加 `2>/dev/null`。如果命令失败，先保留 stderr 和非零退出码并查看 `guancli metric search --help`，不要继续猜参数。
+
 ### metric get
 
 获取指标详情，包括元数据、数据口径、数据集、权限、统计信息、自定义属性、查询加速和血缘关系。
@@ -127,6 +144,21 @@ guancli metric get <metric_id> --profile default -f json
 guancli metric get <metric_id> --profile default --raw
 ```
 
+#### 可复制模板：单个指标详情与适用维度
+
+只供 Agent 阅读时直接使用 brief 输出：
+
+```bash
+guancli metric get <metric_id> --profile <profile> --brief
+```
+
+需要结构化提取时拆成两步：
+
+```bash
+guancli metric get <metric_id> --profile <profile> --brief -f json > metric_detail.json &&
+  jq '.["适用维度"] | map({"名称": .["名称"], "字段ID": .["字段ID"], "字段类型": .["字段类型"]})' metric_detail.json
+```
+
 ### metric accelerate
 
 查询指标的查询加速配置。后端取数时会按 `acceleratePriority` 从高到低尝试加速指标；只有当查询维度和筛选维度都能被加速指标适用维度覆盖时才会命中。
@@ -215,6 +247,8 @@ guancli metric query <metric_id> [flags]
 | 空值 | `IS_NULL`、`NOT_NULL` |
 | 字符串 | `CONTAINS`、`NOT_CONTAINS`、`STARTSWITH`、`NOT_STARTSWITH`、`ENDSWITH`、`NOT_ENDSWITH` |
 
+`--filter` 不接受 SQL/数学符号。固定映射为 `= -> EQ`、`>= -> GE`、`<= -> LE`；其他条件同样从上表选择 CLI 操作符。符号写法会直接报错并给出纠正提示。
+
 示例：
 
 ```bash
@@ -230,6 +264,19 @@ guancli metric query <metric_id> --profile default --dim 省份 --limit 10000 -f
 guancli metric query <metric_id> --profile default --dim 省份 --raw
 ```
 
+#### 可复制模板：筛选并裁剪查询结果
+
+```bash
+guancli metric query <metric_id> --profile <profile> \
+  --dim <维度名> \
+  --filter "日期 GE 2026-01-01" \
+  --filter "地区 EQ 华东" \
+  --columns "日期,地区,<指标名>" \
+  --limit 100
+```
+
+出现筛选语法错误后，先执行 `guancli metric query --help` 并按帮助纠正；不要连续尝试 `=`、`==`、`>=` 等相近符号写法。`--columns` 已能在 Go 端稳定裁剪结果列，不要为这一步额外拼 jq。
+
 ### metric tree
 
 获取指标目录树。默认输出树形结构，最外层展示指标主题。

package/skills/guancli/references/resource-query.md

@@ -37,7 +37,7 @@ guancli ds get <resource_id> --assoc   # 附加显示关联关系摘要（ETL、
 guancli page get <resource_id>         # 页面详情（含卡片列表、血缘）
 ```
 
-**`--brief` 模式**：省略 Malloy 数据源定义、血缘关系、计算字段公式等高 token 内容，只保留基本信息和字段名/类型列表。适合 AI 在上下文受限时快速了解数据集结构。所有 `get` 子命令均支持此选项。
+**`--brief` 模式**：省略 Malloy 定义、血缘关系、计算字段公式等高 token 内容。`ds get` 省略 Malloy/血缘/公式详情；`page get` 省略各卡片的 Malloy 定义与血缘；`etl get` 仅省略血缘；`card get` 输出本身已精简，该选项无额外效果。
 
 **`--assoc` 模式**（仅 `ds get`）：在详情末尾追加数据集关联关系摘要，显示关联的 ETL、数据融合等资源。