@guandata/guancli 1.0.32 → 1.0.34

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## @guandata/guancli 1.0.34 - 2026-06-15
+
+- `metric by-dataset` 支持按数据集 ID 反查直接原子指标，并沿指标血缘展开下游复合指标和衍生指标。
+
+## @guandata/guancli 1.0.33 - 2026-06-09
+
+- `ds search` 支持按数据集 ID 精确解析，修复按 ID 搜索时无法稳定命中资源的问题。
+- 资源详情查询补充相关解析兼容处理，提升数据集排查稳定性。
+
 ## @guandata/guancli 1.0.32 - 2026-06-04
 
 - `metric` 增加指标创建、编辑和删除能力，并补充原子指标、派生指标、复合指标等配置参考。

package/README.md

@@ -30,6 +30,7 @@ guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIM
 # 旧版 public-api fallback 不支持 disable-cache；--limit 在非 raw 输出渲染前本地截断，--raw 保持后端原始响应
 guancli metric project
 guancli metric project 经营 -f json
+guancli metric by-dataset <ds_id> -f json  # 查询数据集直接原子指标及下游复合/衍生指标
 guancli page get <page_id>
 guancli card preview <card_id>
 guancli card preview <card_id> --dynamic-param "结束时间={{{today}}}"
@@ -38,6 +39,15 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.34
+
+- `metric by-dataset` 支持按数据集 ID 反查直接原子指标，并沿指标血缘展开下游复合指标和衍生指标。
+
+### @guandata/guancli 1.0.33
+
+- `ds search` 支持按数据集 ID 精确解析，修复按 ID 搜索时无法稳定命中资源的问题。
+- 资源详情查询补充相关解析兼容处理，提升数据集排查稳定性。
+
 ### @guandata/guancli 1.0.32
 
 - `metric` 增加指标创建、编辑和删除能力，并补充原子指标、派生指标、复合指标等配置参考。

package/package.json

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

package/skills/guancli/SKILL.md

@@ -15,6 +15,7 @@ compatibility: Requires Node.js 14+. Install via npm install -g @guandata/guancl
 - 用户需要对表单填报(Form)数据进行 CRUD 操作（查询/插入/更新/删除）。
 - 用户要直接用 ChatBI 主题做 L1 问数或 L2 洞察，而不是打开网页手工操作。
 - 用户要搜索指标、获取指标详情、查询指标数据、查看指标目录、执行指标树归因，或让你生成/解释指标泛化查询命令。
+- 用户给出数据集 ID，想查看该数据集创建或影响到的所有指标，包括直接原子指标以及下游复合指标、衍生指标。
 - 用户要创建、新建、编辑或删除指标；当前指标写操作指引先覆盖原子指标、复合指标、衍生指标的创建和编辑前校验。
 - 用户要查询、新建、编辑、转移责任人或删除指标公共维度。
 
@@ -116,6 +117,7 @@ guancli 是 BI 资源的**查询分析入口**，并支持少量明确边界的
 关键规则：
 
 - 普通指标数据查询用 `guancli metric query <metric_id>`，可加 `--dim`、`--filter`、排序、列筛选、输出格式等。
+- 按数据集反查指标用 `guancli metric by-dataset <ds_id>`；该命令会先定位使用该数据集的原子指标，再沿指标下游血缘展开复合指标和衍生指标，适合回答“这个数据集关联了哪些指标 / 改这个数据集会影响哪些指标”。如果已知指标主题，可加 `-d <metric_topic_id>` 缩小搜索范围；需要结构化结果时用 `-f json`。
 - 只要传入 `--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>`。
 - 当用户要创建或编辑原子指标、复合指标、衍生指标时，先读取 `references/metric-mutation.md` 判断类型，再读取 `references/metric-common-fields.md`，最后只读取对应类型文件：原子指标读 `references/metric-atomic-mutation.md`，复合指标读 `references/metric-composite-mutation.md`，衍生指标读 `references/metric-derived-mutation.md`。如果涉及原子指标表达式 `formulaField.fdFormula`、复合指标 `formula` 或组合衍生 `deriveSetting.formula`，必须同时读取 `references/metric-expression-rules.md`，按当前前后端支持的表达式形态生成。默认使用当前已登录环境，不询问 profile；按必填项、数据格式 `format` 和启用的指标业务属性配置逐步查询/确认，生成 JSON 文件并先做 dry-run/人工摘要。用户确认后仍需按 Web 同款保存前校验执行：原子指标上线前跑 save-precheck，编辑态跑 validate-update-impact；复合指标和衍生指标编辑态跑 validate-update-impact。校验通过或二次确认后才真实提交。
@@ -139,12 +141,13 @@ guancli etl search                     # 搜索所有 ETL
 guancli etl search 关键词              # 按关键词搜索
 guancli etl search 关键词 -d <dir_id>  # 在指定目录中搜索
 guancli ds search 关键词               # 搜索数据集
-guancli ds search --id <dsId>          # 按数据集 ID 精确查找
+guancli ds search --limit 500 --offset 500  # 分页扫描数据集
+guancli ds search --id <dsId>          # 按数据集 ID 精确查找并返回单个数据集详情
 guancli ds search 关键词 --id <dsId>   # 按名称 + ID 组合查找
 guancli page search 关键词             # 搜索页面
 ```
 
-`ds search --id` 使用 `/api/dataset/search` 接口做精确匹配，支持 `--limit` 和 `--offset` 分页。
+`ds search` 默认返回前 500 条，环境数据集较多时用 `--limit` 和 `--offset` 分页扫描；`ds search --id` 会直接按数据集 ID 获取单个数据集详情，`--limit` 和 `--offset` 在 `--id` 模式下忽略。
 
 ### 3. 获取详情（含血缘）
 

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

@@ -32,6 +32,7 @@ guancli metric [command]
 | `project` | 获取指标主题列表 |
 | `search` | 搜索指标 |
 | `get` | 获取指标详情 |
+| `by-dataset` | 按数据集 ID 获取直接和下游关联指标 |
 | `query` | 查询指标数据 |
 | `tree` | 获取指标目录树 |
 | `create` | 新建原子指标（JSON 文件驱动） |
@@ -97,6 +98,29 @@ guancli metric get <metric_id> --profile default -f json
 guancli metric get <metric_id> --profile default --raw
 ```
 
+### metric by-dataset
+
+按数据集 ID 获取关联指标。命令会跨指标主题扫描指标，并结合指标详情和指标血缘判断该数据集关联的指标；结果包含直接使用该数据集的原子指标，也包含继续引用这些指标的复合指标和衍生指标。
+
+```bash
+guancli metric by-dataset <ds_id> [flags]
+```
+
+专属参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `-d, --dir-id string` | 限定搜索主题 ID |
+
+示例：
+
+```bash
+guancli metric by-dataset <ds_id> --profile default
+guancli metric by-dataset <ds_id> --profile default -f json
+guancli metric by-dataset <ds_id> --profile default -d <metric_topic_id>
+guancli metric by-dataset <ds_id> --profile default --raw
+```
+
 ### metric query
 
 查询指标数据，支持维度、筛选、排序、列筛选和行数限制。泛化查询参数见 `metric-generic-query.md`。