@guandata/guancli 1.0.52 → 1.0.54

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 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 登录与安全凭据管理，提升企业统一身份认证、多环境切换和登录状态恢复的稳定性。
+- SuperApp 支持列出应用和整包下载；创建应用时可识别重名资源并给出可继续处理的信息。
+- `ds execute-sql` 支持从文件或标准输入读取多行 SQL，并完整保留后端 SQL 解析错误，复杂查询更易编写和排查。
+- 改进下载原子写入、超时和服务端错误解析，避免失败下载留下不完整文件。
+- 自动关联卡片可继承筛选条件，卡片预览和联动结果更符合页面实际配置。
+
 ## @guandata/guancli 1.0.52 - 2026-08-20
 
 - 新增资源全局搜索与资源 URL 获取能力，便于快速定位并访问 BI 资源。

package/README.md

@@ -26,6 +26,8 @@ guancli etl get <resource_id>
 guancli ds search <keyword>
 guancli ds preview <ds_id>
 guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20'  # 需目标 BI 满足 8.2.0-hf12+，并在 BI 管理后台 - 域设置打开高级 SQL 查询开关
+guancli ds execute-sql -inputs <ds_id> --sql-file query.sql    # 从文件读取多行 SQL，避免 Shell 多层引号
+guancli ds execute-sql -inputs <ds_id> --sql-file - < query.sql # 从 stdin 读取 SQL
 guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20' -f json
 guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20' --raw
 # SQL 中请使用数据集名称作为临时表名；名称包含中文、空格或特殊字符时，请使用反引号包裹。
@@ -41,6 +43,20 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.54
+
+- SuperApp 发布支持复用可信、已验证的 `dist`，避免服务端因缺少项目本地构建工具而发布失败。
+- 覆盖线上 SuperApp 配置前会明确确认，未确认时保留线上 `setting.json`。
+- 指标问数命令、筛选与列选择更稳定，非法格式或拼错子命令会明确失败。
+- 结构化错误会保留请求位置、状态码和后端业务原因，排障更直接。
+
+### @guandata/guancli 1.0.53
+
+- 新增 OIDC 登录与安全凭据管理，企业统一身份认证和多环境切换更稳定。
+- SuperApp 支持列出应用和整包下载，重名应用也能得到明确的后续处理提示。
+- `ds execute-sql` 支持从文件或标准输入读取多行 SQL，并改进解析错误展示。
+- 改进文件下载的完整性、超时和错误处理，并支持自动关联卡片继承筛选条件。
+
 ### @guandata/guancli 1.0.52
 
 - 新增资源全局搜索与资源 URL 获取能力，定位和访问 BI 资源更便捷。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guancli",
-  "version": "1.0.52",
+  "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 模板项目”时，也要使用这个 skill，并引导使用 `guancli app create`。即使用户只说"看一下这个 page""贴一下这个 ETL 的 SQL""搜个叫 X 的数据集""这个数据集长啥样""页面卡片用了哪些 ds""帮我查这个指标""生成指标泛化查询命令""帮我创建一个超级应用"，也要触发。它直接调用 BI HTTP API 拉数据并整理成 AI 友好的中文结论，定位是 BI 查询分析 + 表单填报 CRUD + 指标查询分析 + SuperApp 模板项目创建。创建/编辑/删除指标、指标主题、指标目录或公共维度走 guanmetric；修改 ETL 走 guanetl；新建/改 Card/Page 走 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 模板项目创建。
+guancli 是 BI 资源的查询分析入口，并支持 Form 表单填报 CRUD、指标查询分析和 SuperApp 模板项目创建、发布与整包下载。页面本身的删除/改名/移动在 `guanvis page`。
 
 ## 何时优先使用
 
@@ -18,36 +18,42 @@ guancli 是 BI 资源的查询分析入口，并支持 Form 表单填报 CRUD、
 - 用户要直接用 ChatBI 主题做 L1 问数或 L2 洞察，而不是打开网页手工操作。
 - 用户要搜索指标、获取指标详情、查询指标数据、查看指标目录、执行指标树归因，或让你生成/解释指标泛化查询命令。
 - 用户给出数据集 ID，想查看该数据集创建或影响到的所有指标，包括直接原子指标以及下游复合指标、衍生指标。
-- 用户要创建超级应用 / SuperApp / SuperApp 模板项目。
+- 用户要创建、发布或更新超级应用 / SuperApp，或要把平台上的 SuperApp 整包下载成本地 zip。
+- 用户要删除、重命名、移动页面（本 skill 只负责把用户路由到 `guanvis page`，命令不在 guancli）。
 - 用户要为已有仪表板或智能洞察卡片生成智能洞察结果。
 
 如果用户只想生成页面 PNG 截图成品，不要用本 skill，改用 `guanvis screenshot`。
 
 ## 能力边界
 
-guancli 是 BI 资源的**查询分析入口**，并支持 Form 表单填报 CRUD 和 SuperApp 模板项目创建。其他写入类任务由专用 skill 负责：
+guancli 是 BI 资源的**查询分析入口**，并支持 Form 表单填报 CRUD 和 SuperApp 模板项目创建、发布与整包下载。其他写入类任务由专用 skill 负责：
 
 | 任务 | 应使用的工具 |
 |---|---|
 | ETL 新建 / 编辑 / 保存 / 执行 | `guanetl` |
 | 数据源 / 数据集 CRUD / 增量 / 调度 | `guands` |
-| 看板 / 卡片构建 / 页面发布 / 截图 | `guanvis` |
+| 看板 / 卡片构建 / 页面**内容**修改 / 页面发布 / 截图 | `guanvis` |
+| 页面**本身**的删除 / 改名 / 移动 | `guanvis page` |
+| 页面目录（PAGE 目录树）创建 / 改名 / 移动 / 删除 | `guanvis dir` |
 | 指标创建 / 编辑 / 删除、指标主题 / 目录创建、公共维度管理、指标 Excel 标准化 | `guanmetric` |
 
 > guancli 能显示 ETL 的节点定义和 SQL，但 ETL 的新建、修改、保存、执行闭环应通过 `guanetl` 完成。
+>
+> 页面的**内容**（卡片、布局、筛选器）和页面**本身**的删除、改名、移动都归 `guanvis`（见「页面写操作不在 guancli」）。页面所在的**目录**归 `guanvis dir`——guancli 只提供只读的 `page get/search/tree`。
 
-**编辑红线（编辑 ≠ 删除重建）**：用户要求编辑/重命名已有 BI 资源（账号、数据集、表单、ETL、页面、卡片、指标等）时，必须路由到对应专用 skill 的**原地更新**能力；对应能力不存在时直接告知用户 CLI 暂不支持。**禁止**用"删除旧资源 + 新建同名资源"来模拟编辑——资源 ID 变化会导致下游引用断链，权限配置、调度、历史数据会静默丢失。表单**数据行**更新用 `form update`，不要用"删行 + 插行"代替（除非用户明确要求）。
+**编辑红线（编辑 ≠ 删除重建）**：用户要求编辑/重命名已有 BI 资源（账号、数据集、表单、ETL、页面、卡片、指标等）时，必须使用**原地更新**能力：页面的改名和移动路由到 guanvis（`guanvis page rename` / `guanvis page move`，硬约束见 guanvis skill），其余路由到对应专用 skill；对应能力不存在时直接告知用户 CLI 暂不支持。**禁止**用"删除旧资源 + 新建同名资源"来模拟编辑——资源 ID 变化会导致下游引用断链，权限配置、调度、历史数据会静默丢失。改名不要用"删页面 + 重新发布"，换目录不要用"删掉再发到新目录"。表单**数据行**更新用 `form update`，不要用"删行 + 插行"代替（除非用户明确要求）。
 
 ## 先做判断
 
 1. 认证检查和 BI 查询都会联网，密码 profile 或服务端轮换 token 时可能更新本地 token；只在当前任务允许认证刷新时执行。
-2. 多 profile 且已知登录 Domain 或 BI/页面 URL 时，先用 `auth list --domain <domain>` 或 `auth list --url <url>` 找候选；0 个候选时报告无匹配，并让用户明确现有 profile 或授权新建/更新哪个 profile，不能自动登录。多个候选时让用户按 profile 名称明确选择。选定 profile 后，用 `guancli --profile <name> auth status` 验证，并在后续查询中保留同一 `--profile <name>`；只有用户明确要求切换机器级默认环境时才用 `auth use`。
-3. 未指定 profile 线索时，用 `auth status` 确认当前默认环境的认证是否有效；首次配置、PAT、profile 和配置文件细节见 `references/auth-and-config.md`。
-4. 如果 Token 过期，密码登录方式会自动刷新；Token 方式需重新登录。
-5. 先判断资源类型：ETL 用 `etl`，数据集用 `ds`，页面/仪表板用 `page`，卡片用 `card`，表单填报用 `form`。
-6. 信息不全时先 `tree` 或 `search`，拿到 ID 后再 `get`；目录名能出现在 `ds tree`，不代表同词一定能命中 `ds search`。三棵 `tree` 都支持 `--max-depth N` / `--keyword 词`（客户环境目录树可达数千节点，全量输出会被截断，默认先 `--max-depth 2` 再按需加深）。
-7. 用户给的是业务目录名而不是数据集名时，先 `ds tree` 定位目录，再在目录内按真实表名搜索，或从已有 `page/card` 反查 `dsId`。
-8. 用户要求查询卡片数据，但没有说明是否沿用页面筛选上下文时，主动询问“是否应用该卡片关联筛选器的默认筛选条件”。用户确认后使用 `card preview <cd_id> --with-default-filters`；用户明确不要、已经给出筛选条件或已明确要求使用默认条件时，不重复询问。卡片属于多个页面时，根据报错列出的候选页面请用户确认，再传 `--page-id <pg_id>`。
+2. 当前进程同时提供 `GUANCLI_OIDC_BASE_URL` 和 `GUANCLI_OIDC_ACCESS_TOKEN` 时，外部 OIDC 环境是本次进程的唯一有效目标，会覆盖本地 profile；直接用 `auth status` 验证，不要求先创建、选择或切换本地 profile。CLI 不接收外部 RefreshToken，也不刷新这组上游托管 Token。
+3. 未启用外部 OIDC 时，多 profile 且已知登录 Domain 或 BI/页面 URL，先用 `auth list --domain <domain>` 或 `auth list --url <url>` 找候选；0 个候选时报告无匹配，并让用户明确现有 profile 或授权新建/更新哪个 profile，不能自动登录。多个候选时让用户按 profile 名称明确选择。选定 profile 后，用 `guancli --profile <name> auth status` 验证，并在后续查询中保留同一 `--profile <name>`；只有用户明确要求切换机器级默认环境时才用 `auth use`。
+4. 未指定 profile 线索且未启用外部 OIDC 时，用 `auth status` 确认当前默认环境的认证是否有效；首次配置、PAT、profile 和配置文件细节见 `references/auth-and-config.md`。
+5. 如果 Token 过期，密码登录方式会自动刷新；Token 方式需重新登录。
+6. 先判断资源类型：ETL 用 `etl`，数据集用 `ds`，页面/仪表板用 `page`，卡片用 `card`，表单填报用 `form`。
+7. 信息不全时先 `tree` 或 `search`，拿到 ID 后再 `get`；目录名能出现在 `ds tree`，不代表同词一定能命中 `ds search`。三棵 `tree` 都支持 `--max-depth N` / `--keyword 词`（客户环境目录树可达数千节点，全量输出会被截断，默认先 `--max-depth 2` 再按需加深）。
+8. 用户给的是业务目录名而不是数据集名时，先 `ds tree` 定位目录，再在目录内按真实表名搜索，或从已有 `page/card` 反查 `dsId`。
+9. 用户要求查询卡片数据，但没有说明是否沿用页面筛选上下文时，主动询问“是否应用该卡片关联筛选器的默认筛选条件”。用户确认后使用 `card preview <cd_id> --with-default-filters`；用户明确不要、已经给出筛选条件或已明确要求使用默认条件时，不重复询问。卡片属于多个页面时，根据报错列出的候选页面请用户确认，再传 `--page-id <pg_id>`。
 
 ## 按需读取资料
 
@@ -89,6 +95,8 @@ guancli url metric-dir <metric_dir_id> --project-id <metric_project_id>
 # 数据集详情 Web URL 格式为 /data-center/data-sets/<dataset_dir_id>/<ds_id>/details/overview?limit=50
 # 数据集目录 Web URL 格式为 /data-center/data-sets/<dataset_dir_id>
 guancli ds preview <ds_id> --limit 20
+# 多行或含复杂引号的 SQL 优先写入文件并使用 --sql-file；需要管道输入时显式使用 --sql-file -。
+guancli ds execute-sql -inputs <ds_id> --sql-file query.sql
 guancli card get <cd_id>
 guancli card preview <cd_id> --value-format raw -f csv
 guancli card preview <cd_id> --with-default-filters
@@ -103,6 +111,19 @@ guancli insight card <cd_id> --page-id <page_id>
 
 详细筛选、输出、动态参数和复杂报表 Pro 行为见 `references/preview-and-output.md`。
 
+## 页面写操作不在 guancli
+
+guancli 的 `page` 只有 `get` / `search` / `tree` 三个**只读**子命令，没有任何页面写命令。
+用户要删除、改名、移动页面时不要在 guancli 里找命令，直接路由到 guanvis skill 的
+`guanvis page delete` / `guanvis page rename` / `guanvis page move`；确认闸门、`--force`
+语义和目录 ID 要求写在 guanvis 的 SKILL.md，这里不复述，以免两处漂移。
+
+**被删页面没有任何命令行恢复入口**：页面删除是软删，页面会进 BI 网页端的回收站，但要
+还原只能人工登录网页端操作。用户问"刚删的页面能找回来吗"时如实这么回答，不要编造恢复命令。
+
+guancli 在这条链路上只出只读的那一环：`guancli page search` / `page get` 确认目标 pgId，
+`guancli page tree --type dir` 查 `guanvis page move` 要传的目标目录 ID。
+
 ## Form 关键规则
 
 - `form query --filter` 在**服务端**执行，格式 `"列名 操作符 [值]"`，可重复；多条件默认
@@ -120,6 +141,12 @@ guancli insight card <cd_id> --page-id <page_id>
 
 ## 指标关键规则
 
+- **先按下面的命令契约生成，不要猜 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、指标名称、命中条件/字段、命中优先级、命中关键词；不要把用户输入默认解释为指标名称精确匹配。如果结果中有“命中条件”“命中优先级”“命中关键词”列，必须原样纳入结论。
@@ -127,7 +154,7 @@ guancli insight card <cd_id> --page-id <page_id>
 - 只要传入 `--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 模板初始化项目时，使用：
 
@@ -139,6 +166,37 @@ 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
+guancli app list --name <名称片段>              # 用户只给名称时先拿 appId
+guancli app download <appId>                    # 默认写到 ./<appId>.zip
+guancli app download <appId> --output ./build/app.zip
+guancli app download <appId> --output ./build/  # 传目录则在目录下生成 <appId>.zip
+guancli app download <appId> -f json            # {appId,appName,version,output,bytes,entries,sha256}
+GUANCLI_DOWNLOAD_TIMEOUT=1200 guancli app download <appId>   # 大包/慢网络时调大下载超时
+```
+
+- **权限**：该端点要求 `STATIC_OPEN_APP` 的 **UPDATE**（不是 READ），只读账号用不了。返回 401/403 时命令会直接点明是登录态失效或缺这项更新权限，不要当成 appId 写错反复重试。
+- **超时**：下载默认超时 600 秒（区别于普通请求和 `GUANCLI_UPLOAD_TIMEOUT`）。大包在慢网络上仍可能超时，用 `GUANCLI_DOWNLOAD_TIMEOUT=<整数秒>` 调大后重试。
+- 命令会先用 `app list` 预检 appId 是否在本环境存在（顺带取回 appName/version），下载完再校验产物确实是非空 zip 并给出条目数与 sha256——认证失效时静态层可能回 200 + HTML，只看字节数分辨不出来。
+- 已知 caveat：`settings.json` 在远端是独立对象，如果经 app settings 接口改过，zip 里的那份可能仍是旧版本。
+- `-f` 只支持 `auto`（默认）和 `json`。
+
 ## 仪表板、卡片智能洞察
 
 ```bash
@@ -150,7 +208,7 @@ guancli insight card <cd_id> --page-id <page_id>
 guancli insight card <cd_id> --page-id <page_id> --selector "<selector_id>=<value>" --locale zh-CN
 ```
 
-- 复用当前 profile 的 uIdToken，当前等待完整非流式结果。
+- 复用当前 profile 的 uIdToken 或 OIDC Access Token，当前等待完整非流式结果。
 - `insight inspect` 输出洞察开关、分析思路 ID/名称和页面关联的 LLM 配置；不输出提示词正文，筛选器继续通过 `page get` / `card get` 查看。
 - 页面洞察仅支持已开启智能洞察的普通仪表板（`pgType=PAGE`）；数据大屏、智能归因、分析报告等页面类型不支持。
 - 卡片洞察必须同时提供卡片所属页面 ID，且仅支持 `cdType=INTELLIGENT_INSIGHT` 的智能洞察卡片。

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/auth-and-config.md

@@ -2,7 +2,23 @@
 
 ## 首次配置（认证）
 
-### 方式一：用户名密码登录（推荐）
+### 方式一：浏览器 OIDC 登录（推荐）
+
+```bash
+guancli auth login --url https://bi.example.com --oidc
+```
+
+CLI 自主执行浏览器 OIDC 登录前，必须先在 BI 管理后台注册 Confidential Client 应用，再把生成的 Client ID 和 Client Secret 输入 CLI（也可分别使用 `--client-id` / `GUANCLI_OIDC_CLIENT_ID` 与 `--client-secret` / `GUANCLI_OIDC_CLIENT_SECRET`）。当前仅支持 Confidential Client，不提供客户端类型选择。交互登录会显示当前回调地址，直接回车保持不变，也可输入新地址；非交互场景使用 `--redirect-uri`。回调地址当前仅支持 HTTP loopback，默认登记地址为 `http://127.0.0.1/auth/oidc/callback`；CLI 会保留登记地址的 host/path，并始终将端口替换成本次本地 listener 的随机端口。回调地址必须存在于 BI OIDC 应用的回调地址配置中，否则授权请求会被拒绝。Token 默认与 Client ID、Client Secret 一起写入权限为 `0600` 的配置文件；使用 `--token-store keyring` 时，Token、Client ID 和 Client Secret 会一起保存到 macOS Keychain、Windows Credential Manager 或 Linux Secret Service，配置文件只保留凭据引用和非敏感 OIDC 元数据。已有 profile 重新登录时会沿用原存储方式，只有显式传入 `--token-store` 才切换。
+
+Access Token 到期后自动使用 Refresh Token 刷新。Refresh Token 不可用时，macOS 和 Windows 会自动输出新的登录 URL、尝试打开系统默认浏览器并等待回调；Linux 和尚未适配的平台不会让普通 CLI 请求突然进入浏览器交互，而是明确提示执行 `guancli auth login --profile <name> --oidc`。用户在 Linux 主动执行 `auth login --oidc` 时仍会尝试通过 `xdg-open` 打开浏览器，失败后可复制终端中的 URL。当前 callback listener 仅支持本机 loopback，不支持公开 HTTPS 回调或跨设备 callback relay。
+
+OIDC Base URL 支持 HTTP 和 HTTPS。传入 BI Web 根地址时，若根路径没有返回有效 Discovery，CLI 会兼容尝试 `/backend/.well-known/openid-configuration`；传入带路径的 URL 时则严格使用该路径。HTTPS 环境的 Discovery 不允许把 authorization/token/JWKS 等端点降级到 HTTP；测试环境可以直接使用 HTTP Base URL。CLI 不提供忽略自签名 HTTPS 证书校验的开关。浏览器打开前，CLI 会用一个不会成功兑换 Token 的占位授权码向 token endpoint 预检 Confidential Client 凭据：`invalid_grant` 表示 client_id/client_secret 已通过认证并继续登录；错误 client_id 或 client_secret 返回的 `invalid_client` 会立即结束，不再打开浏览器等待 callback；其他未覆盖的 OAuth 错误原样返回。
+
+如果 BI 对 Discovery 返回业务状态 `5001` 且提示 `No static resource .well-known/openid-configuration`，CLI 会明确提示“目标 BI 环境不支持 OIDC”，并建议管理员开启 OIDC 功能或升级 BI 版本，不再只暴露底层 HTTP 500。对于已部署 OIDC 但当前用户域或应用在功能层面禁用登录的环境，兼容版本服务端会通过 loopback callback 立即返回 `access_denied`；CLI 将该稳定错误转换为同一“不支持 OIDC”提示，不再等待 callback 超时。其他未覆盖的 OAuth 授权错误保留服务端返回的 `error` 和 `error_description`，不静默改写。
+
+上游 Agent 平台只需通过 `GUANCLI_OIDC_BASE_URL` 和 `GUANCLI_OIDC_ACCESS_TOKEN` 注入目标 BI 环境和托管 Token。Base URL 与 Access Token 是不可拆分的一组配置，缺少任意一个都会明确报错，不会回退或混用本地 profile。检测到完整配置后，普通业务命令可直接使用这组环境变量，不要求本地预先存在 profile；执行 `auth login` 或 `auth login --oidc` 时也会直接创建 external OIDC profile，不再要求 client_id/client_secret，不打开浏览器，并以环境变量 Base URL 覆盖已有 profile URL。完整 external OIDC 配置与 `--token`、`--pat`、账密参数不能同时使用，CLI 会立即提示参数冲突，避免保存一个实际不会被当前请求使用的本地身份。未检测到 Access Token 时才进入正常浏览器认证流程。命中上游 Token 后 guancli 只消费 Access Token，不接收外部 RefreshToken、不保存任何 Token，Access Token 过期或收到 401 时也不会回退到本地身份或触发浏览器登录，只提示由上游更新 AccessToken 后重试。
+
+### 方式二：用户名密码登录
 
 ```bash
 guancli auth login
@@ -11,20 +27,20 @@ guancli auth login
 交互式输入：
 1. 环境名称（默认 `default`，可自定义如 `staging`、`prod`）
 2. BI 系统 URL（如 `https://bi.example.com`）
-3. 选择登录方式：`1` 用户名密码
+3. 选择登录方式：`2` 用户名密码
 4. Domain（如 `demo`）
 5. 用户名（邮箱）
 6. 密码
 
 账号或密码错误时，交互式登录会保留已输入的环境、URL、Domain 和 Login ID，直接提示重新输入密码。登录成功后 Token 自动保存在系统标准配置目录下的 `guancli/config.json`，并自动切换到刚登录的环境；无需再执行 `auth use`。密码方式支持 Token 过期后自动刷新。
 
-### 方式二：直接输入 uIdToken
+### 方式三：直接输入 uIdToken
 
 ```bash
 guancli auth login
 ```
 
-选择登录方式 `2`，直接粘贴已有的 uIdToken。适用于已从 Web 界面或其他途径获取 uIdToken 的场景。
+选择登录方式 `3`，直接粘贴已有的 uIdToken。适用于已从 Web 界面或其他途径获取 uIdToken 的场景。
 
 如需按登录 Domain 筛选这个 profile，可在非交互式登录时同时保存：
 
@@ -32,15 +48,15 @@ guancli auth login
 guancli auth login --url https://bi.example.com --domain demo --token <uid-token>
 ```
 
-### 方式三：Personal Access Token
+### 方式四：Personal Access Token
 
 ```bash
 guancli auth login --url https://bi.example.com --pat <pat>
 ```
 
-交互式登录时选择登录方式 `3`，直接粘贴 Personal Access Token。`--personal-token` 仍可作为长参数使用。PAT 请求会自动携带 `X-Personal-Token`，`X-Guandata-Client` 沿用请求来源（默认 `guancli`；高层 skill 经内部请求通道调用时保留其自身来源），`auth status` 会通过 `/api/pat/introspect` 做自检，且仅在响应明确返回 `usable: true`（兼容历史 `active: true`）时判定有效。
+交互式登录时选择登录方式 `4`，直接粘贴 Personal Access Token。`--personal-token` 仍可作为长参数使用。PAT 请求会自动携带 `X-Personal-Token`，`X-Guandata-Client` 沿用请求来源（默认 `guancli`；高层 skill 经内部请求通道调用时保留其自身来源），`auth status` 会通过 `/api/pat/introspect` 做自检，且仅在响应明确返回 `usable: true`（兼容历史 `active: true`）时判定有效。
 
-`chatbi` 子命令仍要求 uIdToken 登录。
+`chatbi` 子命令支持 uIdToken 或 OIDC Access Token；PAT 仍不支持。
 
 ### 多环境管理
 
@@ -55,6 +71,7 @@ guancli auth use staging                         # 切换默认环境为 staging
 guancli auth use --domain demo                   # 按登录 Domain 切换
 guancli auth use --url https://bi.example.com/page/123  # 按页面 URL 切换
 guancli auth remove staging                      # 删除 staging 环境
+guancli auth logout staging                      # 吊销并清理 OIDC 自管 Token，保留 profile
 ```
 
 `auth list` 可用 `--domain` 或 `--url` 只读筛选 profile；`auth use` 使用相同筛选条件切换默认 profile。`--domain` 只匹配 profile 保存的登录 Domain，忽略大小写；`--url` 必须为不含 userinfo 的 HTTP(S) URL，且编码路径不得把 `/`、`.` 或 `..` 作为 path segment；它按相同协议、主机和最长的 `base_url` 路径前缀匹配，因此可直接传页面深链。`auth use` 遇到多个候选会拒绝切换，需改用 profile 名称明确选择。
@@ -72,7 +89,7 @@ GUANCLI_PROFILE=staging guancli etl tree
 
 ### ChatBI 配置
 
-ChatBI 统一复用当前 profile 的 `base_url` 和 `uIdToken`。
+ChatBI 统一复用当前 profile 的 `base_url` 和 uIdToken/OIDC Access Token。
 
 - 不需要单独配置 ChatBI URL
 - 不需要第二套 token / cookie
@@ -81,6 +98,8 @@ ChatBI 统一复用当前 profile 的 `base_url` 和 `uIdToken`。
 ## Token 管理
 
 - 密码登录方式：Token 过期后自动调用 sign-in API 刷新。
+- OIDC 自管 Token：请求前主动刷新；Refresh Token 失效时 macOS/Windows 自动进行浏览器登录，Linux/未适配平台提示手动执行 `auth login --oidc`。读请求遇到 401 最多刷新并重试一次，写请求只刷新不重放。
+- OIDC 上游 Token：环境变量优先于上游钥匙串和本地凭据；过期或 401 时提示上游刷新，不使用上游 Refresh Token。
 - 每次 API 响应中如果包含新 Token，且距上次签发超过可配置间隔（默认 10 分钟），会自动更新缓存。
 - Token 的签发时间和过期时间记录在配置文件中。
 - 可通过修改 `config.json` 中的 `token_refresh_interval_seconds` 调整刷新间隔。

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/preview-and-output.md

@@ -7,10 +7,14 @@ guancli ds preview <ds_id>              # 预览数据集数据 (表格格式)
 guancli ds preview <ds_id> --limit 20   # 限制预览行数
 guancli ds preview <ds_id> --raw        # 输出原始 JSON
 guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20'  # 用 SQL 查询数据集（需目标 BI 满足 8.2.0-hf12+，并在 BI 管理后台 - 域设置打开高级 SQL 查询开关）
+guancli ds execute-sql -inputs <ds_id> --sql-file query.sql     # 从文件读取 SQL
+guancli ds execute-sql -inputs <ds_id> --sql-file - < query.sql # 从 stdin 读取 SQL
 # SQL 中请使用数据集名称作为临时表名；名称包含中文、空格或特殊字符时，请使用反引号包裹。可先执行 `ds get <ds_id> --brief` 查看数据集名称和字段列表。
 `execute-sql` 的旧版 public-api fallback 不支持 disable-cache；`--limit` 在非 raw 输出渲染前本地截断，`--raw` 保持后端原始响应。
 ```
 
+`--sql` 与 `--sql-file` 二选一。SQL 较长、包含多层引号或由模型生成时，优先写入 `.sql` 文件再传 `--sql-file`；传 `--sql-file -` 时从 stdin 读取，不会把终端中的普通空输入当作 SQL。
+
 数据集 ID (dsId) 可通过 `ds tree` 或 `ds search` 获取。
 
 如果用户给的是业务目录名而不是数据集名，优先先 `ds tree` 定位目录，再在目录内按真实表名搜索，或从已有 `page/card` 反查 `dsId`。
@@ -114,7 +118,7 @@ guancli card preview <complex_report_pro_cd_id> --filter "周 toWeek EQ 2026-W01
 
 ### 应用页面关联筛选器的默认条件
 
-图表卡片默认只按卡片自身配置取数，不会隐式继承页面筛选上下文。需要得到与页面首次打开时一致的结果，可显式传入 `--with-default-filters`。CLI 会读取卡片所属页面，找出通过 `asFilter.columnMappings` 关联到该卡片的选择器，并将默认字段筛选或动态参数一并传给卡片数据接口；整个过程只依赖卡片和页面元信息，不会查询需要数据集管理权限的全局动态参数接口。
+图表卡片默认只按卡片自身配置取数，不会隐式继承页面筛选上下文。需要得到与页面首次打开时一致的结果，可显式传入 `--with-default-filters`。CLI 会读取卡片所属页面，优先找出通过 `asFilter.columnMappings` 关联到该卡片的选择器；若选择器启用 `autoLink`（或 `asFilter` 未显式关闭 autoLink），则按选择器源字段与目标卡片字段的同名匹配推断目标字段，并将默认字段筛选或动态参数一并传给卡片数据接口；整个过程只依赖卡片和页面元信息，不会查询需要数据集管理权限的全局动态参数接口。
 
 ```bash
 guancli card preview <cd_id> --with-default-filters
@@ -126,7 +130,7 @@ guancli card preview <cd_id> --with-default-filters --dynamic-param "结束日
 - 卡片元信息只关联一个页面时自动使用该页面；关联多个页面时必须用 `--page-id` 明确上下文。
 - 显式 `--filter` 或 `--dynamic-param` 会覆盖相同 `fdId` 或 `dpId` 的页面默认值，其他默认条件仍然保留。
 - 首版支持普通固定值、多选、日期范围、后端已经解析出实际区间的时间宏，以及动态参数选择器。
-- 树、组合、`FIRST_PICK`、`autoLink`、聚合/结果级映射、依赖其他选择器的级联运行态、必填但无默认值，以及无法从页面元信息确定实际值或目标映射的默认条件均 fail closed：CLI 在查询卡片数据前明确报错，不会静默忽略后继续执行。
+- 树、组合、`FIRST_PICK`、聚合/结果级映射、依赖其他选择器的级联运行态、必填但无默认值，以及无法从页面元信息确定实际值或目标映射的默认条件均 fail closed：CLI 在查询卡片数据前明确报错，不会静默忽略后继续执行。`autoLink` 会先按同名字段推断目标字段，推断不到时才 fail closed。
 - 多个选择器写入同一字段或动态参数、时间宏目标形态不明确、动态参数默认值包含逗号等可能产生歧义的情况同样会停止查询。
 - 该参数仅适用于 CHART 图表卡片；复杂报表 Pro、选择器和其他卡片类型暂不支持。
 

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、数据融合等资源。