@guandata/guancli 1.0.14 → 1.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guancli",
-  "version": "1.0.14",
+  "version": "1.0.15",
   "description": "观远 BI 命令行工具 - 通过 API 操作 ETL、数据集、页面、表单等资源",
   "bin": {
     "guancli": "bin/run.js"

package/skills/guancli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: guancli
-description: 当用户提到观远 BI、ETL、数据集、页面/仪表板分析、血缘、节点 SQL、资源树、页面配置排查、表单填报数据操作，或希望直接分析 BI 项目而不是手工点页面时，主动使用这个 skill。它通过直接调用 BI API 获取数据，并把结果整理成适合 AI 消费的中文结论。支持表单 CRUD（类似 Airtable 风格）。
+description: 当用户要分析观远 BI / Guandata 的 ETL、数据集、页面/仪表板、卡片、血缘、节点 SQL、资源树、目录、表单填报数据，或给出 ETL ID、dsId、page ID、card ID 想看现有内容时，主动使用这个 skill。即使用户只说"看一下这个 page""贴一下这个 ETL 的 SQL""搜个叫 X 的数据集""这个数据集长啥样""页面卡片用了哪些 ds"，也要触发。它直接调用 BI HTTP API 拉数据并整理成 AI 友好的中文结论，定位是只读分析（Form 表单填报例外，支持 CRUD）。修改 ETL 走 guanetl-skill；新建/改 Card/Page 走 guanvis-skill；数据源/数据集 CRUD/增量/调度走 guands-skill；导出 PNG/PDF 走 guanexport-skill；管理员级 SVC SQL / 动态码走 guanadmin-skill。
 compatibility: Requires Node.js 14+. Install via npm install -g @guandata/guancli.
 ---
 
@@ -69,6 +69,7 @@ guancli --profile staging etl tree
 2. 如果 Token 过期，密码登录方式会自动刷新；Token 方式需重新登录。
 3. 先判断资源类型：ETL 用 `etl`，数据集用 `ds`，页面/仪表板用 `page`，表单填报用 `form`。
 4. 信息不全时先 `tree` 或 `search`，拿到 ID 后再 `get`。
+5. `tree` 和 `search` 语义不同：目录名能出现在 `ds tree`，不代表同词一定能命中 `ds search`。
 
 ## 标准分析流程
 
@@ -87,20 +88,27 @@ 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 关键词 --id <dsId>   # 按名称 + ID 组合查找
 guancli page search 关键词             # 搜索页面
 ```
 
+`ds search --id` 使用 `/api/dataset/search` 接口做精确匹配，支持 `--limit` 和 `--offset` 分页。
+
 ### 3. 获取详情（含血缘）
 
 ```bash
 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 page get <resource_id>         # 页面详情（含卡片列表、血缘）
 ```
 
 **`--brief` 模式**：省略 Malloy 数据源定义、血缘关系、计算字段公式等高 token 内容，只保留基本信息和字段名/类型列表。适合 AI 在上下文受限时快速了解数据集结构。所有 `get` 子命令均支持此选项。
 
+**`--assoc` 模式**（仅 `ds get`）：在详情末尾追加数据集关联关系摘要，显示关联的 ETL、数据融合等资源。
+
 ### 4. 预览数据集数据
 
 ```bash
@@ -111,6 +119,8 @@ guancli ds preview <ds_id> --raw        # 输出原始 JSON
 
 数据集 ID (dsId) 可通过 `ds tree` 或 `ds search` 获取。
 
+如果用户给的是业务目录名而不是数据集名，优先先 `ds tree` 定位目录，再在目录内按真实表名搜索，或从已有 `page/card` 反查 `dsId`。
+
 #### 带筛选条件预览
 
 通过 `--filter` 参数传入筛选条件，每个 `--filter` 值的格式为 `"列名 操作符 [值]"`。