@guandata/guancli 1.0.38 → 1.0.40

package/skills/guancli/references/auth-and-config.md

@@ -0,0 +1,96 @@
+# guancli 认证与配置
+
+## 首次配置（认证）
+
+### 方式一：用户名密码登录（推荐）
+
+```bash
+go run ./cmd/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 过期后自动刷新。
+
+### 方式二：直接输入 uIdToken
+
+```bash
+go run ./cmd/guancli auth login
+```
+
+选择登录方式 `2`，直接粘贴已有的 uIdToken。适用于已从 Web 界面或其他途径获取 uIdToken 的场景。
+
+### 方式三：Personal Access Token
+
+```bash
+go run ./cmd/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 通过 `fetch` 调用时保留其自身来源），`auth status` 会通过 `/pat/introspect` 做自检。
+
+`chatbi` 子命令仍要求 uIdToken 登录；管理员动态码、管理员登录、SVC 查询等管理员能力由 `guanadmin` 提供，不使用 PAT。
+
+### 多环境管理
+
+```bash
+go run ./cmd/guancli auth login --profile staging            # 添加 staging 环境
+go run ./cmd/guancli auth login --profile prod --default     # 添加 prod 并设为默认
+go run ./cmd/guancli auth list                                # 列出所有环境
+go run ./cmd/guancli auth status                              # 查看当前认证状态
+go run ./cmd/guancli auth use staging                         # 切换默认环境为 staging
+go run ./cmd/guancli auth remove staging                      # 删除 staging 环境
+```
+
+使用特定环境（不切换默认）：
+
+```bash
+go run ./cmd/guancli --profile staging etl tree
+go run ./cmd/guancli --profile staging chatbi list-theme
+```
+
+### ChatBI 配置
+
+ChatBI 统一复用当前 profile 的 `base_url` 和 `uIdToken`。
+
+- 不需要单独配置 ChatBI URL
+- 不需要第二套 token / cookie
+- `guancli` 会在内部自动推导并探测可用的 ChatBI Public API 地址，默认优先尝试同域名下的 `/api/chat/public-api`
+
+## Token 管理
+
+- 密码登录方式：Token 过期后自动调用 sign-in API 刷新。
+- 每次 API 响应中如果包含新 Token，且距上次签发超过可配置间隔（默认 10 分钟），会自动更新缓存。
+- Token 的签发时间和过期时间记录在配置文件中。
+- 可通过修改 `config.json` 中的 `token_refresh_interval_seconds` 调整刷新间隔。
+
+## 配置文件位置
+
+- 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
+}
+```

package/skills/guancli/references/form-chatbi.md

@@ -0,0 +1,146 @@
+# guancli 表单填报与 ChatBI
+
+## 6. 表单填报操作 (Form CRUD)
+
+类似 Airtable 风格的表单数据 CRUD，用户始终用**字段名**操作，CLI 内部自动映射到 fdId。
+
+### 列出表单
+
+```bash
+go run ./cmd/guancli form list                       # 列出所有表单
+go run ./cmd/guancli form list 关键词                # 搜索表单
+go run ./cmd/guancli form list --tree                # 目录树形式展示
+```
+
+### 查看表单结构
+
+```bash
+go run ./cmd/guancli form schema <fmId>              # 查看字段结构（LLM 消费核心）
+go run ./cmd/guancli form schema <fmId> -f json      # JSON 格式
+```
+
+### 查询数据
+
+```bash
+go run ./cmd/guancli form query <fmId>                          # 查询数据（默认 50 行）
+go run ./cmd/guancli form query <fmId> --limit 100              # 指定行数
+go run ./cmd/guancli form query <fmId> --filter "姓名 EQ 张三"  # 筛选
+go run ./cmd/guancli form query <fmId> --sort-asc 值            # 按值升序
+go run ./cmd/guancli form query <fmId> --columns "姓名,值"      # 只显示指定列
+go run ./cmd/guancli form query <fmId> -f json                  # JSON 格式（rowId 完整）
+go run ./cmd/guancli form query <fmId> -f expanded              # PG 风格竖排
+```
+
+筛选操作符：`EQ`（等于）、`CONTAINS`（包含）、`STARTSWITH`、`ENDSWITH`、`IS_NULL`、`NOT_NULL`。
+
+**重要**：`rowId` 在 auto 表格格式中可能被截断，使用 `-f json` 或 `-f expanded` 获取完整 rowId。
+
+### 插入数据
+
+```bash
+go run ./cmd/guancli form add <fmId> --data '{"字段名": "值", "数字字段": 42}'
+go run ./cmd/guancli form add <fmId> --set "字段名=值" --set "数字字段=42"
+echo '[{"字段名":"a"},{"字段名":"b"}]' | go run ./cmd/guancli form add <fmId> --stdin
+```
+
+### 更新数据
+
+```bash
+go run ./cmd/guancli form update <fmId> <rowId> --data '{"主键字段": "当前主键值", "字段名": "新值"}'
+go run ./cmd/guancli form update <fmId> <rowId> --set "主键字段=当前主键值" --set "字段名=新值"
+```
+
+`rowId` 和未编辑主键的当前值通过 `form query` 获取。更新载荷必须包含表单配置的全部业务主键字段（内置
+`c_uid` 除外）；CLI 只负责字段名映射和请求透传，不读取当前行、不补齐主键，也不在本地重复后端校验。
+
+### 删除数据
+
+```bash
+go run ./cmd/guancli form delete <fmId> <rowId>                 # 删除单行
+go run ./cmd/guancli form delete <fmId> <rowId1> <rowId2>       # 删除多行
+go run ./cmd/guancli form delete <fmId> --all --yes             # 删除全部（需确认）
+```
+
+### 子表操作
+
+主表中 `TABLE` / `MATRIX_TABLE` 类型字段对应子表。子表有独立的 `subFmId`，可以用 `schema` 查看其字段结构。
+
+```bash
+# 1. 查看主表 schema，找到 TABLE 字段的 subFmId
+go run ./cmd/guancli form schema <mainFmId>
+# 输出中 TABLE 字段的备注列显示 "子表 subFmId=..."
+
+# 2. 查看子表字段结构
+go run ./cmd/guancli form schema <subFmId>
+
+# 3. 查询子表数据（返回结果包含主表字段，rowId 为主表行 ID，subId 为子行 ID）
+go run ./cmd/guancli form query <subFmId>
+
+# 4. 向子表插入行（需指定主表行的 rowId）
+go run ./cmd/guancli form add <subFmId> --parent-row <主表rowId> --set "字段名=值"
+
+# 5. 更新子表行（使用 subId 作为 rowId）
+go run ./cmd/guancli form update <subFmId> <subId> --set "字段名=新值"
+
+# 6. 删除子表行
+go run ./cmd/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. 找到表单
+go run ./cmd/guancli form list 测试
+
+# 2. 查看结构
+go run ./cmd/guancli form schema <fmId>
+
+# 3. 插入数据
+go run ./cmd/guancli form add <fmId> --data '{"测试1": "hello", "值": 42}'
+
+# 4. 查询并获取 rowId
+go run ./cmd/guancli form query <fmId> -f json
+
+# 5. 更新（同时携带业务主键）
+go run ./cmd/guancli form update <fmId> <rowId> --set "名称=当前名称" --set "值=99"
+
+# 6. 删除
+go run ./cmd/guancli form delete <fmId> <rowId>
+```
+
+## 7. ChatBI 主题问数 / 洞察
+
+先列主题，再执行问数或洞察；如果用户没有指定主题，不要猜。
+
+```bash
+go run ./cmd/guancli chatbi list-theme
+go run ./cmd/guancli chatbi list-theme --insight
+go run ./cmd/guancli chatbi query --theme-name "经营主题" --message "最近30天营业收入是多少？"
+go run ./cmd/guancli chatbi query --theme-id "<theme_id>" --message "最近30天营业收入是多少？"
+go run ./cmd/guancli chatbi insight --theme-name "经营主题" --message "分析最近30天营业收入变化原因"
+go run ./cmd/guancli chatbi insight --theme-id "<theme_id>" --message "分析最近30天营业收入变化原因" --agent-mode single_agent
+```
+
+规则：
+
+- `list-theme` 输出 markdown 表格
+- `list-theme --insight` 可列出仅用于洞察的主题
+- `query` 输出 L1 markdown，包含解释和结果表格
+- `insight` 输出 L2 markdown；如返回 `GuanViz.json`，CLI 会自动降级成 markdown 表格
+- ChatBI 命令复用当前 profile 的 `uIdToken`
+- 默认超时 300 秒、轮询间隔 2 秒；必要时可传 `--timeout-ms` / `--poll-interval-ms`

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

@@ -35,12 +35,6 @@ guancli metric [command]
 | `by-dataset` | 按数据集 ID 获取直接和下游关联指标 |
 | `query` | 查询指标数据 |
 | `tree` | 获取指标目录树 |
-| `project-create` | 创建指标主题 |
-| `dir-create` | 创建指标目录 |
-| `create` | 新建原子指标（JSON 文件驱动） |
-| `edit` | 编辑原子指标（JSON patch / replace） |
-| `delete` | 删除指标（先执行删除影响校验） |
-| `public-dim` | 公共维度查询、新建、编辑、删除 |
 
 ### metric project
 
@@ -61,30 +55,6 @@ guancli metric project 经营 --profile default -f json
 guancli metric project 经营 --profile default --raw
 ```
 
-### metric project-create
-
-创建指标主题。主题创建成功后，后端会同步创建该主题根目录。默认图标和颜色与 Web 新建主题一致，可按需覆盖。
-
-```bash
-guancli metric project-create <name> [flags]
-```
-
-专属参数：
-
-| 参数 | 默认值 | 说明 |
-| --- | --- | --- |
-| `--icon string` | `finance_subject` | 主题图标 |
-| `--icon-color string` | `#1A827F` | 主题图标颜色 |
-| `--dry-run` | `false` | 只输出请求方法和请求体，不提交 |
-
-示例：
-
-```bash
-guancli metric project-create 经营指标 --profile default --dry-run
-guancli metric project-create 经营指标 --profile default
-guancli metric project-create 经营指标 --profile default --icon finance_subject --icon-color '#1A827F'
-```
-
 ### metric search
 
 搜索指标；传关键词时后台用 `%keyword%` 模糊匹配，不传关键词返回所有指标。
@@ -209,125 +179,7 @@ guancli metric tree --profile default -f json
 guancli metric tree --profile default --raw
 ```
 
-### metric dir-create
-
-创建指标目录。默认在指定主题根目录下创建；可用 `--project-id` 指定主题 ID，也可用 `--project-name` 按主题名称解析。创建子目录时可用 `--parent-dir-id` 指定父目录 ID，也可用 `--parent-dir-name` 按父目录名称解析。
-如果当前环境下存在多个同名主题，CLI 会阻断创建并列出候选 ID，此时应让用户指定 `--project-id`。
-如果同一主题下存在多个同名父目录，CLI 会阻断创建并列出候选路径和 ID，此时应让用户指定 `--parent-dir-id`。
-
-```bash
-guancli metric dir-create <name> (--project-id <metric_topic_id> | --project-name <metric_topic_name>) [flags]
-```
-
-专属参数：
-
-| 参数 | 默认值 | 说明 |
-| --- | --- | --- |
-| `--project-id string` | 无 | 指标主题 ID；与 `--project-name` 二选一 |
-| `--project-name string` | 无 | 指标主题名称；同名主题重复时改用 `--project-id` |
-| `--parent-dir-id string` | 无 | 父目录 ID；为空时 CLI 自动使用主题根目录 |
-| `--parent-dir-name string` | 无 | 父目录名称；同名目录重复时改用 `--parent-dir-id` |
-| `--dry-run` | `false` | 只输出请求方法和请求体，不提交 |
-
-示例：
-
-```bash
-guancli metric dir-create 广告分析 --profile default --project-id <metric_topic_id> --dry-run
-guancli metric dir-create 广告分析 --profile default --project-id <metric_topic_id>
-guancli metric dir-create 广告分析 --profile default --project-name 经营指标
-guancli metric dir-create 投放效果 --profile default --project-id <metric_topic_id> --parent-dir-id <dir_id>
-guancli metric dir-create 投放效果 --profile default --project-name 经营指标 --parent-dir-name 广告分析
-```
-
-### metric create
-
-新建原子指标。写入流程先读 `metric-mutation.md` 和 `metric-common-fields.md`，原子字段、问询流程和 JSON 模板见 `metric-atomic-mutation.md`。复合指标和衍生指标创建当前使用 `guancli fetch POST /api/metric-platform/metrics/<type>-metrics --stdin`，分别见 `metric-composite-mutation.md` 和 `metric-derived-mutation.md`。
-
-```bash
-guancli metric create --profile default --file atomic_metric.json --dry-run
-guancli metric create --profile default --file atomic_metric.json -f json
-```
-
-专属参数：
-
-| 参数 | 说明 |
-| --- | --- |
-| `--file string` | 指标请求体 JSON 文件 |
-| `--stdin` | 从 stdin 读取指标请求体 JSON |
-| `--set key=value` | 覆盖字段；支持点路径；可重复 |
-| `--dry-run` | 只输出请求方法、路径和请求体，不提交 |
-
-### metric edit
-
-编辑原子指标。默认先读取现有详情，再将 JSON 文件/stdin 和 `--set` 作为 patch 合并；`--replace` 直接提交输入 JSON。复合指标和衍生指标编辑当前使用 `guancli fetch POST /api/metric-platform/metrics/<type>-metrics/<metric_id> --stdin`，写入流程先读 `metric-mutation.md` 和 `metric-common-fields.md`，再按类型读取对应细节文档。
-
-```bash
-guancli metric edit <metric_id> --profile default --file patch.json --dry-run
-guancli metric edit <metric_id> --profile default --set name=新名称
-guancli metric edit <metric_id> --profile default --file full.json --replace
-```
-
-专属参数：
-
-| 参数 | 说明 |
-| --- | --- |
-| `--file string` | 指标 patch/full JSON 文件 |
-| `--stdin` | 从 stdin 读取指标 patch/full JSON |
-| `--set key=value` | 覆盖字段；支持点路径；可重复 |
-| `--replace` | 直接提交输入 JSON，不先读取现有详情并合并 |
-| `--dry-run` | 只输出请求方法、路径和请求体，不提交 |
-
-### metric delete
-
-删除指标。命令与 Web 删除弹窗一致：先调用删除影响校验；如果存在下游指标或卡片，则阻断删除并输出影响列表。未传 `--confirm` 时只输出校验结果，不真实删除。详细流程见 `metric-delete-mutation.md`。
-
-```bash
-guancli metric delete <metric_id> --profile default
-guancli metric delete <metric_id> --profile default --confirm
-guancli metric delete <metric_id> --profile default --confirm --dry-run
-```
-
-专属参数：
-
-| 参数 | 说明 |
-| --- | --- |
-| `--confirm` | 确认删除；未设置时只执行删除影响校验 |
-| `--dry-run` | 只输出将执行的删除校验和删除请求，不提交 |
-
-### metric public-dim
-
-公共维度相关操作。详细字段、问询流程和 JSON 模板见 `metric-public-dimension.md`。
-
-```bash
-guancli metric public-dim list [keyword]
-guancli metric public-dim get <public_dim_id>
-guancli metric public-dim fd-map <ds_id>
-guancli metric public-dim create --file public_dim.json --dry-run
-guancli metric public-dim edit <public_dim_id> --file patch.json
-guancli metric public-dim owner <public_dim_id> --business-owner <user_id>
-guancli metric public-dim delete <public_dim_id>
-guancli metric public-dim delete <public_dim_id> --confirm
-```
-
-别名：
-
-```bash
-guancli metric public-dimension ...
-guancli metric pubdim ...
-```
-
-常用参数：
-
-| 子命令 | 参数 | 说明 |
-| --- | --- | --- |
-| `list` | `--limit` | 返回条数，默认 50 |
-| `list` | `--offset` | 分页偏移，默认 0 |
-| `list` | `--order-by` | `utimeDesc` 或 `utimeAsc` |
-| `create/edit` | `--file`、`--stdin`、`--set`、`--dry-run` | JSON 文件驱动写入 |
-| `edit` | `--replace` | 直接提交输入 JSON，不读取详情合并 |
-| `owner` | `--business-owner` | 新责任人用户 ID |
-| `delete` | `--confirm` | 确认删除；未设置时只执行依赖检查 |
-| `delete` | `--dry-run` | 输出依赖检查和删除请求，不提交 |
+> 指标创建、编辑、删除、指标主题/目录创建、公共维度管理、Excel 标准化已迁移到 `guanmetric`。
 
 ## metric_attribution
 

package/skills/guancli/references/preview-and-output.md

@@ -0,0 +1,166 @@
+# guancli 数据预览、卡片预览与输出格式
+
+## 4. 预览数据集数据
+
+```bash
+go run ./cmd/guancli ds preview <ds_id>              # 预览数据集数据 (表格格式)
+go run ./cmd/guancli ds preview <ds_id> --limit 20   # 限制预览行数
+go run ./cmd/guancli ds preview <ds_id> --raw        # 输出原始 JSON
+go run ./cmd/guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20'  # 用 SQL 查询数据集（需目标 BI 满足 8.2.0-hf12+，并在 BI 管理后台 - 域设置打开高级 SQL 查询开关）
+# SQL 中请使用数据集名称作为临时表名；名称包含中文、空格或特殊字符时，请使用反引号包裹。可先执行 `ds get <ds_id> --brief` 查看数据集名称和字段列表。
+`execute-sql` 的旧版 public-api fallback 不支持 disable-cache；`--limit` 在非 raw 输出渲染前本地截断，`--raw` 保持后端原始响应。
+```
+
+数据集 ID (dsId) 可通过 `ds tree` 或 `ds search` 获取。
+
+如果用户给的是业务目录名而不是数据集名，优先先 `ds tree` 定位目录，再在目录内按真实表名搜索，或从已有 `page/card` 反查 `dsId`。
+
+### 带筛选条件预览
+
+通过 `--filter` 参数传入筛选条件，每个 `--filter` 值的格式为 `"列名 操作符 [值]"`。
+列名中包含空格时无需特殊处理，解析器会智能定位操作符。
+
+```bash
+go run ./cmd/guancli ds preview <ds_id> --filter "name EQ 张三"
+go run ./cmd/guancli ds preview <ds_id> --filter "age GT 18" --filter "city IN 北京,上海,广州"
+go run ./cmd/guancli ds preview <ds_id> --filter "score BT 60,100"
+go run ./cmd/guancli ds preview <ds_id> --filter "status IS_NULL"
+go run ./cmd/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`/`toWeek`/`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 "日期字段 toWeek EQ 2026-W01"
+guancli card preview <cd_id> --filter "日期字段 toDate EQ 2026-01-15"
+```
+
+值格式规范：
+
+| 粒度 | 修饰符 | 值格式 | 示例 |
+|------|--------|--------|------|
+| 年 | `toYear` | `YYYY` | `2026` |
+| 季度 | `toQuarter` | `YYYY-QN` | `2026-Q1` |
+| 月 | `toMonth` | `YYYY-MM` | `2026-01` |
+| 周 | `toWeek` | `YYYY-WNN` 或 `YYYY WNN` | `2026-W01` |
+| 日期 | `toDate` | `YYYY-MM-DD` | `2026-01-15` |
+
+可配合 `--filter "维度字段 EQ 值"` 同时使用多个筛选条件。
+
+### 排序和列筛选
+
+所有 preview 命令（ds/card）都支持排序和列筛选：
+
+```bash
+go run ./cmd/guancli ds preview <ds_id> --sort-asc name                    # 按 name 升序 (API 层面排序)
+go run ./cmd/guancli ds preview <ds_id> --sort-desc id                     # 按 id 降序 (API 层面排序)
+go run ./cmd/guancli ds preview <ds_id> --columns "id,name,status"         # 只显示指定列
+go run ./cmd/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 端对本次取数范围执行，排序取数下限为 10000 行，若卡片总行数超过本次取数范围，不承诺全量 Top N。
+- `--columns`: 逗号分隔的列名列表，只显示指定列（Go 端执行）。
+
+## 5. 获取卡片数据
+
+```bash
+guancli card get <cd_id>                # 获取卡片元信息
+guancli card preview <cd_id>            # 预览卡片数据 (图表默认最多 10000 行；选择器未排序时保留服务端默认)
+guancli card preview <cd_id> --limit 20 # 限制预览行数
+guancli card preview <cd_id> -f csv     # 导出 CSV 到 stdout
+guancli card preview <cd_id> -f csv -o card.csv # 导出 CSV 到文件
+guancli card preview <cd_id> -f excel -o card.xls # 导出 Excel 可打开文件
+guancli card preview <cd_id> --value-format raw -f csv # 保留原始数值，适合 AI 后续计算
+```
+
+卡片 ID (cdId) 可通过 `page get` 命令查看页面详情获取。
+图表卡片内部会按 BI 预览接口的分页能力自动取数；选择器/树状选择器仍使用服务端单次返回。图表卡片数值默认使用 `--value-format formatted`，按卡片返回的数值格式输出（小数位、千分位、货币、百分比、单位等）；需要保留原始数值用于 AI 后续计算时，使用 `--value-format raw`。无卡片格式时 `--precision` 作为兜底最大精度，默认 6 位。任意卡片预览结果在未指定 `-o/--output` 且超过 1000 行时，默认写入 `card_<cdId>_<timestamp>.<ext>` 文件，避免把大结果直接塞入上下文。该能力不对接 BI 导出任务接口。
+
+当图表卡片返回同环比、日期层级或其他多层列表头时，默认输出和 `-f table` 会逐层显示完整表头。JSON、CSV、Excel 等结构化输出使用 `父级 > 子级 > 叶子` 形式的完整路径作为列名，避免只保留末级标题后出现重名或含义丢失。标题自身包含的每个 `>` 会编码为 `\>`，从而与层级分隔符区分；完整路径仍重复时，后续列会追加稳定后缀（如 ` [2]`），保证结构化键唯一且可被筛选、排序。`--columns` 和 `--sort-*` 优先接受大小写精确的完整路径；为了兼容旧命令，末级标题唯一时仍可使用末级标题，存在同名末级标题时会明确提示改用完整路径。
+
+复杂报表 Pro 卡片会自动切换为 xlsx 下载模式，只支持写入文件，不支持 `--raw`、`-f/--format`、`--limit`、排序、列筛选、精度、数值输出格式、动态参数和动态维度。未指定 `-o/--output` 时默认写入 `complex_report_pro_<cdId>_<timestamp>.xlsx`。
+
+### 带筛选条件预览卡片
+
+卡片 preview 同样支持 `--filter` 参数，语法与数据集 preview 一致（含日期粒度筛选）。
+筛选条件会通过 API 传递给后端，适用于 CHART、SELECTOR、TREE_SELECTOR 三种卡片类型。复杂报表 Pro 首版也使用 `--filter`，CLI 会基于页面普通选择器的 `asFilter.columnMappings` 自动映射为子卡 `childFilters`；映射不唯一、树/组合筛选器、动态参数 target 等复杂情况会直接报错。
+
+```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"
+guancli card preview <complex_report_pro_cd_id> --filter "周 toWeek EQ 2026-W01" -o report.xlsx
+```
+
+字段类型会自动从卡片关联的数据集 schema 推断。日期粒度筛选需配合 `card get` 查看字段配置中的筛选器字段名和粒度。
+
+### 带动态参数预览图表卡片
+
+图表卡片 preview 支持通过 `--dynamic-param` 覆盖 BI 全局动态参数，格式为 `参数名=值` 或 `dpId=值`，可多次指定。
+CLI 会查询 `/api/dynamic-parameter/query` 补全参数元数据，并把完整 `dynamicParams` 传给 `/api/card/{cdId}/data`。
+该能力仅支持 CHART 图表卡片；数据集 preview 当前后端接口不消费动态参数，暂不支持。
+多选参数值沿用 BI 前端约定，使用英文逗号拼接成一个字符串传入。
+
+```bash
+guancli card preview <cd_id> --dynamic-param "结束时间={{{today}}}"
+guancli card preview <cd_id> --dynamic-param "11=999" --raw
+guancli card preview <cd_id> --dynamic-param "品类=鞋,服,包"
+guancli card preview <cd_id> --dynamic-param "DATE_RANGE_PARAM_LEFT=2026-05-01" --dynamic-param "DATE_RANGE_PARAM_RIGHT={{{today}}}"
+```
+
+### 带动态维度预览图表卡片
+
+图表卡片 preview 支持通过 `--dynamic-field` 覆盖当前卡片自身的动态维度选择；参数名沿用历史/API 命名，语义上表示动态维度。
+格式为 `动态维度名=字段名`、`dzId=fdId`、`dzId=key`，也兼容旧写法 `dzId:key`。
+动态维度名、dzId、字段名、fdId、key 先用 `card get <cd_id>` 查看；如果动态维度没有配置名称，只能使用 dzId。
+单选动态维度只能指定一个字段；`multiSelect: true` 的动态维度可用英文逗号传多个字段，或重复指定同一个动态维度，CLI 会合并去重。
+字段名本身包含英文逗号时，CLI 会优先按完整字段名匹配；也可用 CSV 引号写法，例如 `"维度=\"门店,二店\""`。
+该能力仅支持当前卡片自身的动态维度，不支持带 `sourceDzIds` 的来源动态维度；参数只影响本次运行态取数，不修改卡片配置。
+
+```bash
+guancli card get <cd_id> # 查看动态维度配置、dzId、可选字段、fdId、key
+guancli card preview <cd_id> --dynamic-field "维度=区域"
+guancli card preview <cd_id> --dynamic-field "维度=区域,门店" --dynamic-field "数值=销售额,利润"
+guancli card preview <cd_id> --dynamic-field "维度=区域" --dynamic-field "维度=门店"
+guancli card preview <cd_id> --dynamic-field "dz_region=province_fd,city_fd"
+guancli card preview <cd_id> --dynamic-field "dz_region=province_key,city_key"
+guancli card preview <cd_id> --dynamic-field "dz_region:city_key"
+```
+
+## 8. 输出格式控制
+
+`--format` / `-f` 控制 preview 命令的输出格式：
+
+```bash
+go run ./cmd/guancli ds preview <ds_id>                 # auto: 对齐表格，列>10 或行>20 时自动截断
+go run ./cmd/guancli ds preview <ds_id> -f csv           # CSV 格式
+go run ./cmd/guancli ds preview <ds_id> -f excel         # Excel 2003 XML 格式
+go run ./cmd/guancli ds preview <ds_id> -f expanded      # PG 风格竖排
+go run ./cmd/guancli ds preview <ds_id> -f table         # 对齐表格
+go run ./cmd/guancli ds preview <ds_id> -f json          # JSON 行记录数组
+go run ./cmd/guancli ds preview <ds_id> -f json | jq '.[0]'  # 配合 jq
+```
+
+`--raw` 输出 API 原始 JSON（不经过解析）：
+
+```bash
+go run ./cmd/guancli --raw etl tree
+go run ./cmd/guancli --raw etl get <id>
+```

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

@@ -0,0 +1,70 @@
+# guancli 资源查询与标准分析流程
+
+## 1. 拉取目录树
+
+```bash
+go run ./cmd/guancli etl tree
+go run ./cmd/guancli ds tree
+go run ./cmd/guancli page tree
+```
+
+## 2. 搜索资源
+
+```bash
+go run ./cmd/guancli etl search                     # 搜索所有 ETL
+go run ./cmd/guancli etl search 关键词              # 按关键词搜索
+go run ./cmd/guancli etl search 关键词 -d <dir_id>  # 在指定目录中搜索
+go run ./cmd/guancli ds search 关键词               # 搜索数据集
+go run ./cmd/guancli ds search --limit 500 --offset 500  # 分页扫描数据集
+go run ./cmd/guancli ds search --id <dsId>          # 按数据集 ID 精确查找并返回单个数据集详情
+go run ./cmd/guancli ds search 关键词 --id <dsId>   # 按名称 + ID 组合查找
+go run ./cmd/guancli page search 关键词             # 搜索页面
+```
+
+`ds search` 默认返回前 500 条，环境数据集较多时用 `--limit` 和 `--offset` 分页扫描；`ds search --id` 会直接按数据集 ID 获取单个数据集详情，`--limit` 和 `--offset` 在 `--id` 模式下忽略。
+
+## 3. 获取详情（含血缘）
+
+```bash
+go run ./cmd/guancli etl get <resource_id>          # ETL 详情（含节点、SQL、血缘）
+go run ./cmd/guancli ds get <resource_id>           # 数据集详情（含字段结构、血缘）
+go run ./cmd/guancli ds get <resource_id> --brief   # 数据集轻量输出（省略 Malloy、血缘、公式详情，节省 token）
+go run ./cmd/guancli ds get <resource_id> --assoc   # 附加显示关联关系摘要（ETL、融合等）
+go run ./cmd/guancli page get <resource_id>         # 页面详情（含卡片列表、血缘）
+```
+
+**`--brief` 模式**：省略 Malloy 数据源定义、血缘关系、计算字段公式等高 token 内容，只保留基本信息和字段名/类型列表。适合 AI 在上下文受限时快速了解数据集结构。所有 `get` 子命令均支持此选项。
+
+**`--assoc` 模式**（仅 `ds get`）：在详情末尾追加数据集关联关系摘要，显示关联的 ETL、数据融合等资源。
+
+## 输出说明
+
+- **目录树**：树形结构（├── └──），包含名称和 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 非零
+- **ChatBI 主题列表**：markdown 表格，包含 `theme_id`、`theme_name`
+- **ChatBI 问数/洞察**：markdown 文本；图表块会被自动转成表格，便于继续总结
+
+## 故障排查
+
+### ETL preview 返回 0 行
+
+0 行是合法结果，不一定是错误。排查顺序：
+1. 确认输入数据集有数据：`guancli ds preview <dsId> --limit 5`
+2. 如果节点有 FILTER_ROWS 或 WHERE 条件，临时简化后再 preview
+
+### Token 过期 / API 401
+
+密码登录方式会自动刷新。如果仍然失败，重新登录：
+
+```bash
+go run ./cmd/guancli auth login
+```