@guandata/guancli 1.0.52 → 1.0.53

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## @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,13 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @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.53",
   "description": "观远 BI 命令行工具 - 通过 API 操作 ETL、数据集、页面、表单等资源，并提供 ChatBI 问数/洞察能力",
   "bin": {
     "guancli": "bin/run.js"

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 整包”时，也要使用这个 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。
 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 模板项目，或要把平台上的 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` 在**服务端**执行，格式 `"列名 操作符 [值]"`，可重复；多条件默认
@@ -127,7 +148,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 +160,23 @@ 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 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 +188,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/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/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、选择器和其他卡片类型暂不支持。