@guandata/guancli 1.0.59 → 1.0.60

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## @guandata/guancli 1.0.60 - 2026-09-17
+
+- 新增内部 OAuth2 应用认证：整体注入 `GUANCLI_OAUTH2_BASE_URL`、`GUANCLI_OAUTH2_ACCESS_TOKEN` 与用户身份（`GUANCLI_OAUTH2_UID` 或 `GUANCLI_OAUTH2_LOGIN_ID`）；CLI 不保存、不交换也不刷新该 Token，且 OAuth2 与 OIDC 变量同时出现时明确报错，不回退本地 profile。
+- Personal Access Token 登录会保存登录 Domain，多 profile 场景可按 Domain 筛选。
+- 新增 `ds get <ds_id> --validate-downstream`：逐个校验血缘中的下游资源是否仍存在，只有结构化业务状态 `1002` 或 HTTP 404 才判定为不存在，认证/HTTP/解析错误直接失败；单次最多校验 100 个下游资源、总超时 30 秒。
+
 ## @guandata/guancli 1.0.59 - 2026-09-15
 
 - `--filter` 支持符号比较操作符 `=`、`!=`、`<>`、`<`、`<=`、`>`、`>=`，统一归一化为枚举操作符；`--filter-json`、`--filter-file` 和 `metric batch-query` 的 `operator` 同样支持。`BT` 也接受两个不含空格的边界用空格分隔。

package/README.md

@@ -43,6 +43,11 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.60
+
+- 新增内部 OAuth2 应用认证，按 `GUANCLI_OAUTH2_*` 整体注入环境与用户身份，CLI 不保存、不刷新该 Token。
+- PAT 登录会保存登录 Domain；新增 `ds get --validate-downstream` 校验血缘下游资源是否仍存在。
+
 ### @guandata/guancli 1.0.59
 
 - 指标筛选支持 `=`、`!=`、`<>`、`<`、`<=`、`>`、`>=` 符号写法，统一归一化为枚举操作符；`BT` 也支持两个不含空格的边界用空格分隔。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guancli",
-  "version": "1.0.59",
+  "version": "1.0.60",
   "description": "观远 BI 命令行工具 - 通过 API 操作 ETL、数据集、页面、表单等资源，并提供 ChatBI 问数/洞察能力",
   "bin": {
     "guancli": "bin/run.js"

package/skills/guancli/SKILL.md

@@ -47,9 +47,9 @@ guancli 是 BI 资源的**查询分析入口**，并支持 Form 表单填报 CRU
 ## 先做判断
 
 1. 认证检查和 BI 查询都会联网，密码 profile 或服务端轮换 token 时可能更新本地 token；只在当前任务允许认证刷新时执行。
-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`。
+2. 当前进程提供完整外部 OIDC 认证环境时，它是本次进程的唯一有效目标并覆盖本地 profile：使用 `GUANCLI_OIDC_BASE_URL` + `GUANCLI_OIDC_ACCESS_TOKEN`。直接用 `auth status` 验证，不要求先创建、选择或切换本地 profile。
+3. 未启用外部认证时，多 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 线索且未启用外部认证时，用 `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` 再按需加深）。
@@ -86,6 +86,7 @@ guancli etl get <resource_id>
 guancli ds get <resource_id>
 guancli ds get <resource_id> --brief
 guancli ds get <resource_id> --assoc
+guancli ds get <resource_id> --validate-downstream
 guancli page get <resource_id>
 guancli url page <page_id>
 guancli url card <cd_id> --page-id <page_id>
@@ -115,6 +116,8 @@ guancli insight card <cd_id> --page-id <page_id>
 > 优先用 `guands dataset fields <ds_id>`（轻量、秒回）；详情确需查看时先加
 > `--brief` 跳过血缘。命令超时时不要原样重试——换轻量命令或转后台执行。
 
+删除数据集前不要依据 `cardCount` 单独判断引用关系。需要核验血缘中的下游 ID 是否仍存在时，使用 `ds get <ds_id> --validate-downstream`；该选项逐个调用资源详情接口，只有结构化业务状态 `1002` 或 HTTP 404 才标记为“不存在”，认证、HTTP 和 JSON 解析错误会直接失败，避免把查询失败误报成幽灵引用。单次最多验证 100 个下游资源，总超时 30 秒；不支持与 `--brief` 同时使用。
+
 详细筛选、输出、动态参数和复杂报表 Pro 行为见 `references/preview-and-output.md`。
 
 ## 页面写操作不在 guancli

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

@@ -34,6 +34,8 @@ guancli etl get <resource_id>          # ETL 详情（含节点、SQL、血缘
 guancli ds get <resource_id>           # 数据集详情（含字段结构、血缘）
 guancli ds get <resource_id> --brief   # 数据集轻量输出（省略 Malloy、血缘、公式详情，节省 token）
 guancli ds get <resource_id> --assoc   # 附加显示关联关系摘要（ETL、融合等）
+guancli ds get <resource_id> --validate-downstream       # 验证血缘中的下游资源是否仍存在
+guancli ds get <resource_id> --raw --validate-downstream # 在 lineage.downstreamValidation 返回结构化报告
 guancli page get <resource_id>         # 页面详情（含卡片列表、血缘）
 ```
 
@@ -41,6 +43,12 @@ guancli page get <resource_id>         # 页面详情（含卡片列表、血缘
 
 **`--assoc` 模式**（仅 `ds get`）：在详情末尾追加数据集关联关系摘要，显示关联的 ETL、数据融合等资源。
 
+**`--validate-downstream` 模式**（仅 `ds get`）：按血缘返回顺序串行调用数据集、ETL、页面或卡片详情接口，确认每个下游 ID 当前是否仍存在。只有业务状态 `1002` 或 HTTP 404 会记为 `not_found`；认证失败、其他 HTTP 错误、JSON 解析失败和响应 ID 不一致都会让命令失败，不会误报为“不存在”。未知资源类型记为 `unsupported`，并令报告的 `complete=false`。原始 `lineage.downstream` 不会被删除或改写；`--raw` 下新增的 `lineage.downstreamValidation` 包含 `complete`、`allValid`、`checked`、`valid`、`notFound`、`unsupported` 和逐项 `items`。默认不启用，因此现有 `ds get` / `ds get --raw` 输出保持不变。
+
+该验证单次最多处理 100 个下游资源，按服务端血缘顺序执行，单请求超时 10 秒、总超时 30 秒。它验证的是“血缘 ID 对应资源详情当前可读取”，不替代服务端删除接口对真实依赖、权限和并发变化的最终校验；不能与跳过血缘的 `--brief` 同时使用。
+
+使用 Personal Access Token 时，血缘、页面和卡片详情使用 `BASE/read`；数据集详情使用 `DATASET/read`；ETL 详情使用 `ETL/read`。PAT 创建时权限列表默认为空，`BASE` 基础读取仍按账号角色校验，但数据集和 ETL 读取权限必须显式选入 PAT scope；缺少权限时验证会返回真实鉴权错误并终止。
+
 ## 4. 获取资源具体 URL
 
 ```bash