@wubaoqi/guancopilot 0.0.0-stage → 0.2.0

package/skills-bundle/guancli/evals/fixtures/metric-consumption-metadata.json

@@ -0,0 +1,36 @@
+{
+  "search": {
+    "schemaVersion": "1.0",
+    "resultMode": "inline",
+    "rowCount": 1,
+    "command": "metric.search",
+    "data": [
+      {
+        "id": "fixture-sales",
+        "name": "销售额",
+        "dimensions": [
+          {
+            "name": "地区",
+            "id": "region"
+          }
+        ]
+      }
+    ]
+  },
+  "get": {
+    "schemaVersion": "1.0",
+    "resultMode": "inline",
+    "rowCount": 1,
+    "command": "metric.get",
+    "data": {
+      "id": "fixture-sales",
+      "name": "销售额",
+      "dimensions": [
+        {
+          "name": "地区",
+          "id": "region"
+        }
+      ]
+    }
+  }
+}

package/skills-bundle/guancli/evals/fixtures/metric-consumption-query.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": "1.0",
+  "resultMode": "inline",
+  "rowCount": 1,
+  "command": "metric.query",
+  "columns": [
+    "区域",
+    "组织"
+  ],
+  "data": [
+    {
+      "区域": "华东",
+      "组织": {
+        "名称": "杭州"
+      }
+    }
+  ]
+}

package/skills-bundle/guancli/references/analysis-primitives.md

@@ -0,0 +1,95 @@
+# 本地分析原语
+
+`guancli analyze` 是无网络、无业务语义的本地表格处理入口。输入必须是明确的 CSV/JSON 文件，输出统一为 `analysis/v1` JSON envelope：
+
+```json
+{
+  "schemaVersion": "analysis/v1",
+  "operation": "normalize",
+  "columns": ["区域", "金额"],
+  "rowCount": 1,
+  "rows": [{"区域": "华东", "金额": "10"}],
+  "metadata": {"input": "raw.csv"}
+}
+```
+
+## 适用边界
+
+- CLI 只提供 loader、字段对齐、安全四则运算、分组排序、TopN 和占比。
+- “本期/同期/预算”“同比/达成率”“毛利贡献”“价格/成本效应”等属于上层分析 recipe。调用方应显式选择字段并组合通用原语，禁止假设 CLI 内置这些业务口径。
+- 每一步都写到明确文件再进入下一步。命令失败后读取错误并修正字段或策略，不用临时 Python 脚本绕过契约。
+
+## 规范化
+
+```bash
+guancli analyze normalize raw.csv -o normalized.json
+guancli analyze normalize raw.json --input-format json -o normalized.json
+```
+
+- 自动识别 CSV/JSON，也可以用 `--input-format` 明确指定。
+- 去除 UTF-8 BOM；JSON 嵌套对象扁平化为 `父字段.子字段`。
+- CSV 按记录读取，JSON 对象数组以及 `rows`/`data` 数组按元素读取；最终规范化表仍会保留在内存中，超大结果应在上游先过滤。
+- JSON 数字按原始十进制文本解析并原样写回，超过 JavaScript 安全整数范围的 ID 不会先转成浮点数而丢失精度。
+- CSV/JSON 字符串中的空字符串、`null`、`None`、`<nil>` 默认转成 JSON `null`。需要其他契约时可重复传 `--null-value`；一旦显式传入，就只使用调用方给出的集合。
+- JSON 顶层支持对象数组、单个对象、`rows` 数组或 `data` 数组。
+- 使用 `-o` 时先写同目录临时文件并同步，成功后再原子替换目标；写入、同步或关闭失败时保留原输出文件。
+
+## 对齐
+
+```bash
+guancli analyze align \
+  --left current.json \
+  --right reference.json \
+  --key 区域 --key 产品 \
+  --join full \
+  --left-prefix current \
+  --right-prefix reference \
+  -o aligned.json
+```
+
+- `--join` 支持 `full`、`inner`、`left`、`right`。
+- 键字段只输出一份，非键字段统一加左右前缀；缺失的一侧显式输出 `null`。
+- 任一输入出现重复组合键时直接失败。CLI 不猜测聚合方式，也不静默执行多对多连接；调用方必须先按明确口径聚合。
+
+## 安全基础计算
+
+```bash
+guancli analyze calculate aligned.json \
+  --operator subtract \
+  --left-field current.金额 \
+  --right-field reference.金额 \
+  --output-field difference \
+  --null-policy propagate \
+  -o calculated.json
+
+guancli analyze calculate aligned.json \
+  --operator divide \
+  --left-field current.金额 \
+  --right-field reference.金额 \
+  --output-field ratio \
+  --zero-divisor null \
+  -o ratio.json
+```
+
+- `--operator` 支持 `add`、`subtract`、`multiply`、`divide`。
+- `--null-policy propagate` 保留空值；只有调用方明确要求时才使用 `zero`。
+- 除数为 0 默认输出 `null`；需要严格失败时使用 `--zero-divisor error`。
+- 非空但不可解析为有限数值的字段（包括 `NaN`/`Inf`）直接报错并定位行号，不使用默认值吞错。
+
+## 分组 TopN 与占比
+
+```bash
+guancli analyze topn calculated.json \
+  --group-by 区域 \
+  --value-field difference \
+  --limit 10 \
+  --order desc \
+  --rank-field rank \
+  --share-field share \
+  -o topn.json
+```
+
+- `--group-by` 是分区字段，不指定时对全表排序。
+- 占比分母是该分区全部非空行的数值之和，不是 TopN 截断后的合计。
+- 空值排在有效数值之后，占比为 `null`；分区合计为 0 时占比同样为 `null`。
+- `topn` 不做隐式聚合。存在重复粒度时，先使用具备明确聚合口径的上游查询或工具处理。

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

@@ -0,0 +1,131 @@
+# guancli 认证与配置
+
+## 首次配置（认证）
+
+### 方式一：用户名密码登录
+
+```bash
+guancli auth login
+```
+
+交互式输入：
+1. 环境名称（默认 `default`，可自定义如 `staging`、`prod`）
+2. BI 系统 URL（如 `https://bi.example.com`）
+3. 选择登录方式：`1` 用户名密码
+4. Domain（如 `demo`）
+5. 用户名（邮箱）
+6. 密码
+
+账号或密码错误时，交互式登录会保留已输入的环境、URL、Domain 和 Login ID，直接提示重新输入密码。登录成功后 Token 自动保存在系统标准配置目录下的 `guancli/config.json`，并自动切换到刚登录的环境；无需再执行 `auth use`。密码方式支持 Token 过期后自动刷新。
+
+### 方式二：直接输入 uIdToken
+
+```bash
+guancli auth login
+```
+
+选择登录方式 `2`，直接粘贴已有的 uIdToken。适用于已从 Web 界面或其他途径获取 uIdToken 的场景。
+
+如需按登录 Domain 筛选这个 profile，可在非交互式登录时同时保存：
+
+```bash
+guancli auth login --url https://bi.example.com --domain demo --token <uid-token>
+```
+
+### 方式三：Personal Access Token
+
+```bash
+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 经内部请求通道调用时保留其自身来源），`auth status` 会通过 `/api/pat/introspect` 做自检，且仅在响应明确返回 `usable: true`（兼容历史 `active: true`）时判定有效。
+
+`chatbi` 子命令支持 uIdToken 或 OIDC Access Token；PAT 仍不支持。
+
+### 方式四：浏览器 OIDC 登录
+
+```bash
+guancli auth login --url https://bi.example.com --oidc
+```
+
+CLI 自主执行浏览器 OIDC 登录前，必须先在 BI 管理后台注册 Confidential Client 应用，再把生成的 Client ID 和 Client Secret 输入 CLI（也可分别使用 `--client-id` / `GUANCLI_OIDC_CLIENT_ID` 与 `--client-secret` / `GUANCLI_OIDC_CLIENT_SECRET`）。当前仅支持 Confidential Client，不提供客户端类型选择。交互登录会显示当前回调地址，直接回车保持不变，也可输入新地址；非交互场景使用 `--redirect-uri`。回调地址当前仅支持 HTTP loopback，默认登记地址为 `http://127.0.0.1/auth/oidc/callback`；CLI 会保留登记地址的 host/path，并始终将端口替换成本次本地 listener 的随机端口。回调地址必须存在于 BI OIDC 应用的回调地址配置中，否则授权请求会被拒绝。Token 默认与 Client ID、Client Secret 一起写入权限为 `0600` 的配置文件；使用 `--token-store keyring` 时，Token、Client ID 和 Client Secret 会一起保存到 macOS Keychain、Windows Credential Manager 或 Linux Secret Service，配置文件只保留凭据引用和非敏感 OIDC 元数据。已有 profile 重新登录时会沿用原存储方式，只有显式传入 `--token-store` 才切换。
+
+Access Token 到期后自动使用 Refresh Token 刷新。Refresh Token 不可用时，macOS 和 Windows 会自动输出新的登录 URL、尝试打开系统默认浏览器并等待回调；Linux 和尚未适配的平台不会让普通 CLI 请求突然进入浏览器交互，而是明确提示执行 `guancli auth login --profile <name> --oidc`。用户在 Linux 主动执行 `auth login --oidc` 时仍会尝试通过 `xdg-open` 打开浏览器，失败后可复制终端中的 URL。当前 callback listener 仅支持本机 loopback，不支持公开 HTTPS 回调或跨设备 callback relay。
+
+OIDC Base URL 支持 HTTP 和 HTTPS。传入 BI Web 根地址时，若根路径没有返回有效 Discovery，CLI 会兼容尝试 `/backend/.well-known/openid-configuration`；传入带路径的 URL 时则严格使用该路径。HTTPS 环境的 Discovery 不允许把 authorization/token/JWKS 等端点降级到 HTTP；测试环境可以直接使用 HTTP Base URL。CLI 不提供忽略自签名 HTTPS 证书校验的开关。浏览器打开前，CLI 会用一个不会成功兑换 Token 的占位授权码向 token endpoint 预检 Confidential Client 凭据：`invalid_grant` 表示 client_id/client_secret 已通过认证并继续登录；错误 client_id 或 client_secret 返回的 `invalid_client` 会立即结束，不再打开浏览器等待 callback；其他未覆盖的 OAuth 错误原样返回。
+
+如果 BI 对 Discovery 返回业务状态 `5001` 且提示 `No static resource .well-known/openid-configuration`，CLI 会明确提示“目标 BI 环境不支持 OIDC”，并建议管理员开启 OIDC 功能或升级 BI 版本，不再只暴露底层 HTTP 500。对于已部署 OIDC 但当前用户域或应用在功能层面禁用登录的环境，兼容版本服务端会通过 loopback callback 立即返回 `access_denied`；CLI 将该稳定错误转换为同一“不支持 OIDC”提示，不再等待 callback 超时。其他未覆盖的 OAuth 授权错误保留服务端返回的 `error` 和 `error_description`，不静默改写。
+
+上游 Agent 平台只需通过 `GUANCLI_OIDC_BASE_URL` 和 `GUANCLI_OIDC_ACCESS_TOKEN` 注入目标 BI 环境和托管 Token。Base URL 与 Access Token 是不可拆分的一组配置，缺少任意一个都会明确报错，不会回退或混用本地 profile。检测到完整配置后，普通业务命令可直接使用这组环境变量，不要求本地预先存在 profile；执行 `auth login` 或 `auth login --oidc` 时也会直接创建 external OIDC profile，不再要求 client_id/client_secret，不打开浏览器，并以环境变量 Base URL 覆盖已有 profile URL。完整 external OIDC 配置与 `--token`、`--pat`、账密参数不能同时使用，CLI 会立即提示参数冲突，避免保存一个实际不会被当前请求使用的本地身份。未检测到 Access Token 时才进入正常浏览器认证流程。命中上游 Token 后 guancli 只消费 Access Token，不接收外部 RefreshToken、不保存任何 Token，Access Token 过期或收到 401 时也不会回退到本地身份或触发浏览器登录，只提示由上游更新 AccessToken 后重试。
+
+### 多环境管理
+
+```bash
+guancli auth login --profile staging            # 添加 staging 并切换为当前环境
+guancli auth login --profile prod               # 添加 prod 并切换为当前环境
+guancli auth list                                # 列出所有环境
+guancli auth list --domain demo                  # 按登录 Domain 筛选
+guancli auth list --url https://bi.example.com/page/123  # 按页面 URL 筛选
+guancli auth status                              # 查看当前认证状态
+guancli auth use staging                         # 切换默认环境为 staging
+guancli auth use --domain demo                   # 按登录 Domain 切换
+guancli auth use --url https://bi.example.com/page/123  # 按页面 URL 切换
+guancli auth remove staging                      # 删除 staging 环境
+guancli auth logout staging                      # 吊销并清理 OIDC 自管 Token，保留 profile
+```
+
+`auth list` 可用 `--domain` 或 `--url` 只读筛选 profile；`auth use` 使用相同筛选条件切换默认 profile。`--domain` 只匹配 profile 保存的登录 Domain，忽略大小写；`--url` 必须为不含 userinfo 的 HTTP(S) URL，且编码路径不得把 `/`、`.` 或 `..` 作为 path segment；它按相同协议、主机和最长的 `base_url` 路径前缀匹配，因此可直接传页面深链。`auth use` 遇到多个候选会拒绝切换，需改用 profile 名称明确选择。
+
+使用特定环境（不切换默认）：
+
+```bash
+guancli --profile staging etl tree
+guancli --profile staging chatbi list-theme
+GUANCLI_PROFILE=staging guancli auth status
+GUANCLI_PROFILE=staging guancli etl tree
+```
+
+显式的子命令 `--profile` 优先于根级 `--profile` / `GUANCLI_PROFILE`；未指定时才使用配置中的默认环境。高层 skill（如 `guanetl`）使用 `GUANCLI_PROFILE` 绑定当前进程链，不修改机器级默认环境。
+
+### ChatBI 配置
+
+ChatBI 统一复用当前 profile 的 `base_url` 和 uIdToken/OIDC Access Token。
+
+- 不需要单独配置 ChatBI URL
+- 不需要第二套 token / cookie
+- `guancli` 会在内部自动推导并探测可用的 ChatBI Public API 地址，默认优先尝试同域名下的 `/api/chat/public-api`
+
+## Token 管理
+
+- 密码登录方式：Token 过期后自动调用 sign-in API 刷新。
+- OIDC 自管 Token：请求前主动刷新；Refresh Token 失效时 macOS/Windows 自动进行浏览器登录，Linux/未适配平台提示手动执行 `auth login --oidc`。读请求遇到 401 最多刷新并重试一次，写请求只刷新不重放。
+- OIDC 上游 Token：环境变量优先于上游钥匙串和本地凭据；过期或 401 时提示上游刷新，不使用上游 Refresh Token。
+- 每次 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-bundle/guancli/references/examples/metric-date-in.json

@@ -0,0 +1,7 @@
+{
+  "combineType": "AND",
+  "conditions": [
+    {"field": "日期", "operator": "BT", "values": ["2026-01-01", "2026-01-31"]},
+    {"field": "城市", "operator": "IN", "values": ["杭州", "上海"]}
+  ]
+}

package/skills-bundle/guancli/references/examples/metric-query-rows.py

@@ -0,0 +1,83 @@
+"""Read a successful metric.query envelope; emit its row array for processing."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def query_rows(envelope):
+    if not isinstance(envelope, dict) or envelope.get("schemaVersion") != "1.0":
+        raise ValueError("expected metric envelope schemaVersion 1.0")
+    if envelope.get("command") != "metric.query":
+        raise ValueError("expected metric.query, not metadata or a dry-run plan")
+    count = envelope.get("rowCount")
+    if type(count) is not int or count < 0:
+        raise ValueError("invalid rowCount")
+    if not isinstance(envelope.get("columns"), list):
+        raise ValueError("missing query columns")
+    if envelope.get("resultMode") == "inline":
+        rows = envelope["data"]
+    elif envelope.get("resultMode") == "file":
+        path = Path(envelope["path"])
+        if not path.is_absolute():
+            raise ValueError("expected absolute output path")
+        with path.open(encoding="utf-8") as source:
+            rows = json.load(source)
+    else:
+        raise ValueError("unsupported resultMode")
+    if not isinstance(rows, list) or len(rows) != count:
+        raise ValueError("row payload does not match envelope rowCount")
+    if any(not isinstance(row, dict) for row in rows):
+        raise ValueError("expected row objects")
+    return rows
+
+
+def query_columns(envelope):
+    columns = envelope["columns"]
+    if (any(not isinstance(column, str) or not column for column in columns)
+            or len(set(columns)) != len(columns)):
+        raise ValueError("invalid or ambiguous columns: " + json.dumps(columns, ensure_ascii=False))
+    return columns
+
+
+def select_column(columns, rows, candidates):
+    # Candidates must come from observed columns and confirmed business intent.
+    # Never infer meaning from a suffix, approximate spelling or column order.
+    matches = [column for column in columns if column in candidates]
+    available = json.dumps(columns, ensure_ascii=False)
+    if len(matches) != 1:
+        raise ValueError("expected exactly one matching column; actual columns: " + available)
+    column = matches[0]
+    for index, row in enumerate(rows):
+        if column not in row:
+            raise ValueError(f"column missing in row {index}; actual columns: {available}; "
+                             "row keys: " + json.dumps(list(row), ensure_ascii=False))
+    return [{column: row[column]} for row in rows]
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("envelope", help="stdout JSON from a successful metric query -f json")
+    selection = parser.add_mutually_exclusive_group()
+    selection.add_argument("--list-columns", action="store_true", help="inspect actual column names first")
+    selection.add_argument("--column", action="append", help="exact candidate; repeat only for confirmed alternatives")
+    args = parser.parse_args()
+    try:
+        with open(args.envelope, encoding="utf-8") as source:
+            envelope = json.load(source)
+        rows = query_rows(envelope)
+        result = rows
+        if args.list_columns or args.column:
+            columns = query_columns(envelope)
+            result = columns if args.list_columns else select_column(columns, rows, args.column)
+    except (ValueError, KeyError, TypeError, OSError) as error:
+        print(f"Cannot consume metric query: {error}", file=sys.stderr)
+        return 1
+    json.dump(result, sys.stdout, ensure_ascii=False)
+    print()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills-bundle/guancli/references/examples/metric-query.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Usage: bash metric-query.sh METRIC_ID PROFILE
+set -euo pipefail
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+guancli metric query "$1" --profile "$2" -f json > query-envelope.json 2> query-error.log
+python3 "$script_dir/metric-query-rows.py" query-envelope.json > query-rows.json

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

@@ -0,0 +1,199 @@
+# guancli 表单填报与 ChatBI
+
+## 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 风格竖排
+```
+
+#### 筛选（`--filter`，服务端执行）
+
+格式 `"列名 操作符 [值]"`，可重复指定；多个条件默认 `AND` 组合，用 `--combine-type OR`
+改成 `OR`。多值操作符（`IN`、`BT` 系列、`CONTAIN_ALL`/`CONTAIN_ANY`，以及多选字段上的 `EQ`）的值用**逗号**
+分隔；单值操作符的值原样保留其中的空格和逗号（`"姓名 EQ 张 三"` 匹配 `张 三`，`"姓名 EQ a,b"`
+匹配字面量 `a,b`，都不会被拆开）。
+
+操作符可用性取决于字段的控件类型（用 `form schema` 查看 `type` 列）：
+
+| 操作符 | 含义 | 适用字段类型 |
+|--------|------|-------------|
+| `EQ` | 等于；多选字段上是**集合相等**（`标签 EQ 红,黄` 匹配恰好选了这两项的行） | 全部 |
+| `NE` | 不等于 | 除多选外 |
+| `IN` | 属于给定值之一（逗号分隔） | 仅文本类（STRING/TEXT/VALUE_CHOOSER…） |
+| `CONTAINS` | 包含子串 | 全部 |
+| `NOT_CONTAINS` | 不包含子串 | 仅 NUMBER / DATE_TIME |
+| `GT` / `GE` / `LT` / `LE` | 大于 / 大于等于 / 小于 / 小于等于 | 仅 NUMBER / DATE_TIME |
+| `BT` | 闭区间 `lo,hi`（lo ≤ x ≤ hi） | 仅 NUMBER / DATE_TIME |
+| `OPEN_BT_OPEN` | 开区间（lo < x < hi） | 仅 NUMBER / DATE_TIME |
+| `OPEN_BT_CLOSE` | 左开右闭（lo < x ≤ hi） | 仅 NUMBER / DATE_TIME |
+| `CLOSE_BT_OPEN` | 左闭右开（lo ≤ x < hi） | 仅 NUMBER / DATE_TIME |
+| `CONTAIN_ALL` | 多选包含全部给定选项 | 仅 MULTI_VALUE_CHOOSER |
+| `CONTAIN_ANY` | 多选包含任一给定选项 | 仅 MULTI_VALUE_CHOOSER |
+| `IS_NULL` | 为空 | 全部 |
+| `NOT_NULL` | 不为空 | 除多选外 |
+
+```bash
+guancli form query <fmId> --filter "姓名 CONTAINS 张"                  # 子串匹配
+guancli form query <fmId> --filter "金额 BT 100,200"                   # 数值区间
+guancli form query <fmId> --filter "创建时间 GE 2026-01-01"            # 日期比较
+guancli form query <fmId> --filter "标签 CONTAIN_ANY 红,黄"            # 多选
+guancli form query <fmId> --filter "状态 IN 待审,已审"                 # 文本 IN
+guancli form query <fmId> --filter "姓名 EQ 张三" --filter "金额 GT 100"        # AND
+guancli form query <fmId> --filter "姓名 EQ 张三" --filter "姓名 EQ 李四" --combine-type OR
+```
+
+注意：
+
+- **不支持 `STARTSWITH` / `ENDSWITH`**（后端无对应实现）。CLI 会直接报错并提示改用
+  `CONTAINS`——注意 `CONTAINS` 语义更宽，匹配任意位置的子串。历史版本会把这两个操作符
+  发给后端并**静默返回未筛选的全量数据**。
+- 操作符用在不支持的字段类型上会**直接报错**，不会静默返回未筛选的数据。
+- `DATE_TIME` 的比较由后端按「天」截断（忽略时分秒），`BT` 两端都含端点。
+- 子表（`TABLE` / `MATRIX_TABLE`）字段不能作为筛选列，请直接查询子表。
+
+#### 排序（`--sort-asc` / `--sort-desc`）
+
+**只对当前页已取回的行排序，不是全表排序。** 后端 `form query` 接口不接受排序参数
+（固定按更新时间倒序返回），排序在 Go 端完成。因此
+`--limit 50 --sort-desc 金额` 得到的是「这 50 行里金额最大的」，**不是**「全表金额最大的
+50 行」——**不要把它当 Top-N 用**。命中总行数超过本页时 CLI 会在 stderr 输出警告。
+
+需要全表 Top-N 时，先用 `--filter` 把结果收敛到能一次取回的范围，或用 `--limit` /
+`--offset` 取回全部数据后再排序。
+
+**重要**：`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 "主键字段=当前主键值" --set "字段名=新值"
+```
+
+`rowId` 和未编辑主键的当前值通过 `form query` 获取。更新载荷必须包含表单配置的全部业务主键字段（内置
+`c_uid` 除外）；CLI 只负责字段名映射和请求透传，不读取当前行、不补齐主键，也不在本地重复后端校验。
+
+### 删除数据
+
+```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 会分页读取已有子行并通过主表 update 全量回写以保留已有行；非并发安全
+- `--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 "名称=当前名称" --set "值=99"
+
+# 6. 删除
+guancli form delete <fmId> <rowId>
+```
+
+## 7. ChatBI 主题问数 / 洞察
+
+先列主题，再执行问数或洞察；如果用户没有指定主题，不要猜。
+
+```bash
+guancli chatbi list-theme
+guancli chatbi list-theme --insight
+guancli chatbi query --theme-name "经营主题" --message "最近30天营业收入是多少？"
+guancli chatbi query --theme-id "<theme_id>" --message "最近30天营业收入是多少？"
+guancli chatbi insight --theme-name "经营主题" --message "分析最近30天营业收入变化原因"
+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`