@guandata/guancli 1.0.9

package/bin/run.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { execFileSync, spawnSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const PLATFORM_MAP = {
+  "darwin-arm64": "guancli-darwin-arm64",
+  "darwin-x64": "guancli-darwin-x64",
+  "win32-x64": "guancli-win32-x64.exe",
+};
+
+function getBinaryPath() {
+  const key = `${process.platform}-${process.arch}`;
+  const binaryName = PLATFORM_MAP[key];
+  if (!binaryName) {
+    console.error(
+      `Unsupported platform: ${key}\nSupported: ${Object.keys(PLATFORM_MAP).join(", ")}`
+    );
+    process.exit(1);
+  }
+
+  const binaryPath = path.join(__dirname, "..", "binaries", binaryName);
+  if (!fs.existsSync(binaryPath)) {
+    console.error(
+      `Binary not found: ${binaryPath}\nRun 'npm run build' to compile binaries.`
+    );
+    process.exit(1);
+  }
+
+  return binaryPath;
+}
+
+if (process.argv[2] === "install-skill") {
+  const pkgRoot = path.join(__dirname, "..");
+  const extraArgs = process.argv.slice(3);
+  const args = [
+    "skills",
+    "add",
+    pkgRoot,
+    "--skill",
+    "guancli",
+    "-g",
+    "-y",
+    ...extraArgs,
+  ];
+  console.log("Installing guancli to AI coding assistants...");
+  const result = spawnSync("npx", args, { stdio: "inherit", env: process.env, shell: true });
+  if (result.error) throw result.error;
+  process.exit(result.status || 0);
+}
+
+const binary = getBinaryPath();
+
+try {
+  if (process.platform !== "win32") {
+    fs.chmodSync(binary, 0o755);
+  }
+} catch (_) {
+  // chmod may fail in read-only environments; binary might already be executable
+}
+
+try {
+  execFileSync(binary, process.argv.slice(2), {
+    stdio: "inherit",
+    env: { ...process.env, GUANCLI_PROG_NAME: "guancli" },
+  });
+} catch (err) {
+  if (err.status != null) {
+    process.exit(err.status);
+  }
+  throw err;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@guandata/guancli",
+  "version": "1.0.9",
+  "description": "观远 BI 命令行工具 - 通过 API 操作 ETL、数据集、页面、表单等资源",
+  "bin": {
+    "guancli": "bin/run.js"
+  },
+  "scripts": {
+    "build": "node scripts/build.js && node scripts/sync-skill.js",
+    "prepublishOnly": "node scripts/preflight.js"
+  },
+  "files": [
+    "bin/",
+    "binaries/",
+    "skills/",
+    "README.md"
+  ],
+  "keywords": [
+    "guandata",
+    "bi",
+    "cli",
+    "etl",
+    "agent-skill"
+  ],
+  "license": "UNLICENSED",
+  "os": [
+    "darwin",
+    "win32"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/skills/guancli/SKILL.md

@@ -0,0 +1,410 @@
+---
+name: guancli
+description: 当用户提到观远 BI、ETL、数据集、页面/仪表板分析、血缘、节点 SQL、资源树、页面配置排查、表单填报数据操作，或希望直接分析 BI 项目而不是手工点页面时，主动使用这个 skill。它通过直接调用 BI API 获取数据，并把结果整理成适合 AI 消费的中文结论。支持表单 CRUD（类似 Airtable 风格）。
+compatibility: Requires Node.js 14+. Install via npm install -g @guandata/guancli.
+---
+
+# guancli
+
+## 何时优先使用
+
+- 用户希望分析观远 BI 项目的 ETL 逻辑、数据集结构、页面/仪表板内容。
+- 用户提供了 BI 系统 URL，需要连接并获取数据。
+- 用户要快速拿到 ETL 清单、节点 SQL、输入输出数据集血缘。
+- 用户在排查 BI 资源配置、页面卡片定义、接口返回或 lineage 关系。
+- 用户需要对表单填报(Form)数据进行 CRUD 操作（查询/插入/更新/删除）。
+
+如果用户只想导出 PNG / PDF 成品，不要用本 skill，改用 `guanexport-skill`。
+
+## 数据获取方式
+
+通过保存的认证信息直接调用 BI HTTP API。
+
+## 首次配置（认证）
+
+### 方式一：用户名密码登录（推荐）
+
+```bash
+guancli auth login
+```
+
+交互式输入：
+1. 环境名称（默认 `default`，可自定义如 `staging`、`prod`）
+2. BI 系统 URL（如 `https://bi.example.com`）
+3. 选择登录方式：`1` 用户名密码
+4. Domain（如 `demo`）
+5. 用户名（邮箱）
+6. 密码
+
+登录成功后 Token 自动保存在系统标准配置目录下的 `guancli/config.json`。密码方式支持 Token 过期后自动刷新。
+
+### 方式二：直接输入 Token
+
+```bash
+guancli auth login
+```
+
+选择登录方式 `2`，直接粘贴已有的 Auth Token。适用于已从 Web 界面或其他途径获取 Token 的场景。
+
+### 多环境管理
+
+```bash
+guancli auth login --profile staging            # 添加 staging 环境
+guancli auth login --profile prod --default     # 添加 prod 并设为默认
+guancli auth list                                # 列出所有环境
+guancli auth status                              # 查看当前认证状态
+guancli auth use staging                         # 切换默认环境为 staging
+guancli auth remove staging                      # 删除 staging 环境
+```
+
+使用特定环境（不切换默认）：
+
+```bash
+guancli --profile staging etl tree
+```
+
+## 先做判断
+
+1. 先用 `auth status` 确认认证是否有效。
+2. 如果 Token 过期，密码登录方式会自动刷新；Token 方式需重新登录。
+3. 先判断资源类型：ETL 用 `etl`，数据集用 `ds`，页面/仪表板用 `page`，表单填报用 `form`。
+4. 信息不全时先 `tree` 或 `search`，拿到 ID 后再 `get`。
+
+## 标准分析流程
+
+### 1. 拉取目录树
+
+```bash
+guancli etl tree
+guancli ds tree
+guancli page tree
+```
+
+### 2. 搜索资源
+
+```bash
+guancli etl search                     # 搜索所有 ETL
+guancli etl search 关键词              # 按关键词搜索
+guancli etl search 关键词 -d <dir_id>  # 在指定目录中搜索
+guancli ds search 关键词               # 搜索数据集
+guancli page search 关键词             # 搜索页面
+```
+
+### 3. 获取详情（含血缘）
+
+```bash
+guancli etl get <resource_id>          # ETL 详情（含节点、SQL、血缘）
+guancli ds get <resource_id>           # 数据集详情（含字段结构、血缘）
+guancli ds get <resource_id> --brief   # 数据集轻量输出（省略 Malloy、血缘、公式详情，节省 token）
+guancli page get <resource_id>         # 页面详情（含卡片列表、血缘）
+```
+
+**`--brief` 模式**：省略 Malloy 数据源定义、血缘关系、计算字段公式等高 token 内容，只保留基本信息和字段名/类型列表。适合 AI 在上下文受限时快速了解数据集结构。所有 `get` 子命令均支持此选项。
+
+### 4. 预览数据集数据
+
+```bash
+guancli ds preview <ds_id>              # 预览数据集数据 (表格格式)
+guancli ds preview <ds_id> --limit 20   # 限制预览行数
+guancli ds preview <ds_id> --raw        # 输出原始 JSON
+```
+
+数据集 ID (dsId) 可通过 `ds tree` 或 `ds search` 获取。
+
+#### 带筛选条件预览
+
+通过 `--filter` 参数传入筛选条件，每个 `--filter` 值的格式为 `"列名 操作符 [值]"`。
+列名中包含空格时无需特殊处理，解析器会智能定位操作符。
+
+```bash
+guancli ds preview <ds_id> --filter "name EQ 张三"
+guancli ds preview <ds_id> --filter "age GT 18" --filter "city IN 北京,上海,广州"
+guancli ds preview <ds_id> --filter "score BT 60,100"
+guancli ds preview <ds_id> --filter "status IS_NULL"
+guancli ds preview <ds_id> --filter "销售 金额 GT 100" --combine-type OR
+```
+
+支持的操作符：
+- 比较：`EQ`（等于）、`NE`（不等于）、`LT`（小于）、`LE`（小于等于）、`GT`（大于）、`GE`（大于等于）
+- 区间：`BT`（between，两个值逗号分隔）
+- 集合：`IN`（多值逗号分隔）
+- 空值：`IS_NULL`、`NOT_NULL`
+- 字符串：`CONTAINS`、`NOT_CONTAINS`、`STARTSWITH`、`NOT_STARTSWITH`、`ENDSWITH`、`NOT_ENDSWITH`
+
+`--combine-type` 控制多条件组合方式，默认 `AND`，可设为 `OR`。
+字段类型会自动从数据集 schema 推断，无需手动指定。
+
+#### 日期粒度筛选（SUB_DATE）
+
+对 DATE/TIMESTAMP 字段，可用 `toYear`/`toQuarter`/`toMonth`/`toDate` 修饰符按粒度筛选。
+语法：`"列名 toGranularity OPERATOR value"`，值使用标准格式，CLI 自动转换为 BI API 格式。
+
+```bash
+guancli card preview <cd_id> --filter "日期字段 toQuarter IN 2026-Q1"
+guancli card preview <cd_id> --filter "日期字段 toQuarter IN 2026-Q1,2026-Q2"
+guancli card preview <cd_id> --filter "日期字段 toYear EQ 2026"
+guancli card preview <cd_id> --filter "日期字段 toMonth EQ 2026-01"
+guancli card preview <cd_id> --filter "日期字段 toDate EQ 2026-01-15"
+```
+
+值格式规范：
+
+| 粒度 | 修饰符 | 值格式 | 示例 |
+|------|--------|--------|------|
+| 年 | `toYear` | `YYYY` | `2026` |
+| 季度 | `toQuarter` | `YYYY-QN` | `2026-Q1` |
+| 月 | `toMonth` | `YYYY-MM` | `2026-01` |
+| 日期 | `toDate` | `YYYY-MM-DD` | `2026-01-15` |
+
+可配合 `--filter "维度字段 EQ 值"` 同时使用多个筛选条件。
+
+#### 排序和列筛选
+
+所有 preview 命令（ds/card）都支持排序和列筛选：
+
+```bash
+guancli ds preview <ds_id> --sort-asc name                    # 按 name 升序 (API 层面排序)
+guancli ds preview <ds_id> --sort-desc id                     # 按 id 降序 (API 层面排序)
+guancli ds preview <ds_id> --columns "id,name,status"         # 只显示指定列
+guancli ds preview <ds_id> --filter "status EQ FAILED" --sort-desc id --columns "id,task_name"
+```
+
+- `--sort-asc` / `--sort-desc`: 互斥，只能指定一个列。ds preview 的排序通过 API 在数据库层面执行；card preview 的排序在 Go 端对返回数据执行。
+- `--columns`: 逗号分隔的列名列表，只显示指定列（Go 端执行）。
+
+### 5. 获取卡片数据
+
+```bash
+guancli card get <cd_id>                # 获取卡片元信息
+guancli card preview <cd_id>            # 预览卡片数据 (表格格式)
+guancli card preview <cd_id> --limit 20 # 限制预览行数
+```
+
+卡片 ID (cdId) 可通过 `page get` 命令查看页面详情获取。
+
+#### 带筛选条件预览卡片
+
+卡片 preview 同样支持 `--filter` 参数，语法与数据集 preview 一致（含日期粒度筛选）。
+筛选条件会通过 API 传递给后端，适用于 CHART、SELECTOR、TREE_SELECTOR 三种卡片类型。
+
+```bash
+guancli card preview <cd_id> --filter "name EQ 张三"
+guancli card preview <cd_id> --filter "age GT 18" --filter "city IN 北京,上海"
+guancli card preview <cd_id> --filter "利润中心 EQ 华南" --filter "季度(日期) toQuarter IN 2026-Q1"
+```
+
+字段类型会自动从卡片关联的数据集 schema 推断。日期粒度筛选需配合 `card get` 查看字段配置中的筛选器字段名和粒度。
+
+### 6. 表单填报操作 (Form CRUD)
+
+类似 Airtable 风格的表单数据 CRUD，用户始终用**字段名**操作，CLI 内部自动映射到 fdId。
+
+#### 列出表单
+
+```bash
+guancli form list                       # 列出所有表单
+guancli form list 关键词                # 搜索表单
+guancli form list --tree                # 目录树形式展示
+```
+
+#### 查看表单结构
+
+```bash
+guancli form schema <fmId>              # 查看字段结构（LLM 消费核心）
+guancli form schema <fmId> -f json      # JSON 格式
+```
+
+#### 查询数据
+
+```bash
+guancli form query <fmId>                          # 查询数据（默认 50 行）
+guancli form query <fmId> --limit 100              # 指定行数
+guancli form query <fmId> --filter "姓名 EQ 张三"  # 筛选
+guancli form query <fmId> --sort-asc 值            # 按值升序
+guancli form query <fmId> --columns "姓名,值"      # 只显示指定列
+guancli form query <fmId> -f json                  # JSON 格式（rowId 完整）
+guancli form query <fmId> -f expanded              # PG 风格竖排
+```
+
+筛选操作符：`EQ`（等于）、`CONTAINS`（包含）、`STARTSWITH`、`ENDSWITH`、`IS_NULL`、`NOT_NULL`。
+
+**重要**：`rowId` 在 auto 表格格式中可能被截断，使用 `-f json` 或 `-f expanded` 获取完整 rowId。
+
+#### 插入数据
+
+```bash
+guancli form add <fmId> --data '{"字段名": "值", "数字字段": 42}'
+guancli form add <fmId> --set "字段名=值" --set "数字字段=42"
+echo '[{"字段名":"a"},{"字段名":"b"}]' | guancli form add <fmId> --stdin
+```
+
+#### 更新数据
+
+```bash
+guancli form update <fmId> <rowId> --data '{"字段名": "新值"}'
+guancli form update <fmId> <rowId> --set "字段名=新值"
+```
+
+`rowId` 通过 `form query` 获取。
+
+#### 删除数据
+
+```bash
+guancli form delete <fmId> <rowId>                 # 删除单行
+guancli form delete <fmId> <rowId1> <rowId2>       # 删除多行
+guancli form delete <fmId> --all --yes             # 删除全部（需确认）
+```
+
+#### 子表操作
+
+主表中 `TABLE` / `MATRIX_TABLE` 类型字段对应子表。子表有独立的 `subFmId`，可以用 `schema` 查看其字段结构。
+
+```bash
+# 1. 查看主表 schema，找到 TABLE 字段的 subFmId
+guancli form schema <mainFmId>
+# 输出中 TABLE 字段的备注列显示 "子表 subFmId=..."
+
+# 2. 查看子表字段结构
+guancli form schema <subFmId>
+
+# 3. 查询子表数据（返回结果包含主表字段，rowId 为主表行 ID，subId 为子行 ID）
+guancli form query <subFmId>
+
+# 4. 向子表插入行（需指定主表行的 rowId）
+guancli form add <subFmId> --parent-row <主表rowId> --set "字段名=值"
+
+# 5. 更新子表行（使用 subId 作为 rowId）
+guancli form update <subFmId> <subId> --set "字段名=新值"
+
+# 6. 删除子表行
+guancli form delete <subFmId> <subId>
+```
+
+**子表 ID 映射规则**（AI 调用时注意区分）：
+
+| 操作 | fmId 参数 | 行 ID 参数 | 额外参数 |
+|------|-----------|-----------|---------|
+| schema | subFmId | - | - |
+| query | subFmId | - | 返回 rowId(主表行) + subId(子行) |
+| add | subFmId | - | `--parent-row <主表rowId>` |
+| update | subFmId | **subId** (作为 rowId 位置参数) | - |
+| delete | subFmId | **subId** (作为 rowId 位置参数) | - |
+
+**注意**：
+- 子表 add 内部通过主表 update API 间接完成（后端限制），CLI 自动保留已有子行
+- add 需全量读取子表以保留已有行，子表总行数上限 10000；非并发安全
+- `--stdin` 批量插入部分失败时 CLI 返回非零退出码，summary 中显示成功/失败计数
+
+#### 典型工作流
+
+```bash
+# 1. 找到表单
+guancli form list 测试
+
+# 2. 查看结构
+guancli form schema <fmId>
+
+# 3. 插入数据
+guancli form add <fmId> --data '{"测试1": "hello", "值": 42}'
+
+# 4. 查询并获取 rowId
+guancli form query <fmId> -f json
+
+# 5. 更新
+guancli form update <fmId> <rowId> --set "值=99"
+
+# 6. 删除
+guancli form delete <fmId> <rowId>
+```
+
+### 7. 通用 API 调用（原始 JSON）
+
+```bash
+guancli fetch GET /api/health
+guancli fetch GET /api/etl/<id>
+guancli fetch POST /api/resource-atlas/<id> '{"resourceTypeName":"DATA_PROCESS_ETL"}'
+```
+
+### 8. 输出格式控制
+
+`--format` / `-f` 控制 preview 命令的输出格式：
+
+```bash
+guancli ds preview <ds_id>                 # auto: 对齐表格，列>10 或行>20 时自动截断
+guancli ds preview <ds_id> -f csv           # CSV 格式
+guancli ds preview <ds_id> -f expanded      # PG 风格竖排
+guancli ds preview <ds_id> -f table         # 对齐表格
+guancli ds preview <ds_id> -f json          # JSON 行记录数组
+guancli ds preview <ds_id> -f json | jq '.[0]'  # 配合 jq
+```
+
+`--raw` 输出 API 原始 JSON（不经过解析）：
+
+```bash
+guancli --raw etl tree
+guancli --raw etl get <id>
+```
+
+## Token 管理
+
+- 密码登录方式：Token 过期后自动调用 sign-in API 刷新。
+- 每次 API 响应中如果包含新 Token，且距上次签发超过可配置间隔（默认 10 分钟），会自动更新缓存。
+- Token 的签发时间和过期时间记录在配置文件中。
+- 可通过修改 `config.json` 中的 `token_refresh_interval_seconds` 调整刷新间隔。
+
+## 输出说明
+
+- **目录树**：树形结构（├── └──），包含名称和 ID
+- **搜索结果**：表格式列表，包含名称、ID、状态、路径、调度信息、时间
+- **ETL 详情**：流程摘要 + 节点详细信息（含 Sources/UsedBy 引用）+ 等价 SQL + 血缘关系
+- **数据集详情**：基本信息 + 字段结构（维度/度量/计算字段分类）+ Malloy source 定义 + 血缘关系
+- **页面详情**：页面信息 + 卡片列表（含筛选器配置、交互联动、Malloy 查询）+ 血缘关系
+- **数据集预览**：表格格式预览（列名 + 数据行），显示数据集基本信息和行列统计
+- **卡片数据**：表格格式预览（维度 + 度量），自动检测卡片类型（图表/筛选器/树状筛选器）
+- **表单列表**：表格式列表，包含 fmId、名称、类型、创建者、更新时间
+- **表单结构**：字段定义表格，包含 fdId、名称、类型、必填/可编辑、选项（LLM 消费核心）；TABLE 类型字段显示 subFmId
+- **表单数据**：表格格式，首列为 rowId（用于 update/delete），后续为字段列；子表查询结果额外包含 `subId` 列（子行主键，update/delete 时用作 rowId 参数）
+- **表单写操作**（add/update/delete）：默认输出 `✓ ...` 文本；`-f json` 时输出结构化 JSON：`{"ok":true,"action":"add","rowId":"...","count":N,"total":N,"failed":N}`。批量插入部分失败时 `ok=false` 且 exit code 非零
+
+## 回答风格要求
+
+- 用中文输出，优先给"可执行结论"。
+- 不只贴原始命令结果，必须做逻辑归纳（按链路/主题）。
+- 涉及时间相关信息时给出明确日期。
+- 如果用户给的是模糊对象名，先说明你是如何定位到具体资源 ID 的。
+
+## 故障排查
+
+### Token 过期 / API 401
+
+密码登录方式会自动刷新。如果仍然失败，重新登录：
+
+```bash
+guancli auth login
+```
+
+## 配置文件位置
+
+- macOS: `~/Library/Application Support/guancli/config.json`
+- Linux: `~/.config/guancli/config.json`
+- Windows: `%AppData%\\guancli\\config.json`
+
+```json
+{
+  "profiles": {
+    "default": {
+      "name": "default",
+      "base_url": "https://bi.example.com",
+      "domain": "demo",
+      "login_id": "user@example.com",
+      "password": "yourpassword",
+      "auth_method": "password",
+      "token": "...",
+      "issued_at": 1711234567,
+      "expires_at": 0,
+      "is_default": true
+    }
+  },
+  "token_refresh_interval_seconds": 600
+}
+```