观远BI

🔴 操作前必读（不可跳过）

⚠️ 关键规则

所有数值计算必须跑代码 — 禁止在思考中直接口算百分比、环比、除法等。

必须提供 pg_id — 不保存的卡片无法取数据
先查页面权限 — 用 list-pages --manageable 找有权限的页面，不用翻 JSON
筛选值按需查 — 只有用了分类筛选（IN/EQ/CONTAINS）才需要 search-values；纯日期范围（BT）不需要
图表类型限制 — 超出 metric/row/column 上限会返回空数据
必须确认数据范围 — 用户没有明确指定日期范围时，必须追问，不要自己假设。例如："你想看哪段时间的数据？" 或提供选项："要看今天、本周还是上月？"

每次做分析前，第一步永远是：

cat skills/guandata/分析经验.md

这不是建议，是硬性步骤。跳过 = 重复踩坑。规则都在里面，包括：

数据表选择（哪张表对应什么场景）
字段陷阱
报告规范
计算红线（加权平均、禁止口算）
待处理的bug

遇到意外的错误以及得到新的教训立即更新： 遇到意外的错误以及得到新的教训，当场写入 分析经验.md 的「待确认」区域（第四章），格式：

### 7.N [YYYY-MM-DD] 简要标题
- **场景**: 什么情况下遇到的
- **问题**: 发生了什么
- **我的判断**: 我认为应该怎么做

如果配置了 cron，待确认项可以自动发送给用户确认。

基本信息

配置文件: skills/guandata/config.json（含明文凭据，请勿提交到公开仓库）
脚本: skills/guandata/scripts/guandata.py

运行环境

Python 3.8+
依赖库: httpx（pip install httpx）
凭据存储在 config.json 中（明文），仅供本地使用，切勿提交到公开仓库

配置说明

编辑 config.json：

{
  "version": "6",
  "base_url": "https://your-guandata-instance.com:port",
  "domain": "your_domain",
  "login_id": "your_username",
  "password": "your_password",
  "default_pg_id": "your_default_page_id",
  "default_folder_id": "your_default_folder_id"
}

| 字段 | 必填 | 说明 | |------|------|------| | version | ✅ | 观远BI版本："6" 或 "7"。<br>• "6"：观远BI 6.x，直接保存卡片<br>• "7"：观远BI 7.0+，使用 draft/release 机制（创建卡片后自动发布页面） | | base_url | ✅ | 观远BI服务器地址，如 https://bi.company.com:8080 | | domain | ✅ | 登录域，通常为 guanbi，具体咨询你们的BI管理员 | | login_id | ✅ | 观远BI登录账号 | | password | ✅ | 观远BI登录密码 | | default_pg_id | | 默认页面ID。不传时，create-and-get 需手动指定 pg_id；传入后可省略 | | default_folder_id | | 默认文件夹ID。创建新页面时的存放位置 |

如何获取 pg_id / folder_id

在观远BI网页打开目标页面，URL 中的 pgId=xxx 即为页面ID
文件夹ID在观远BI「数据管理」→「目录」中查看

核心命令

SCRIPT="python3 skills/guandata/scripts/guandata.py"

# 查数据集（默认读本地缓存）
$SCRIPT list-datasets
$SCRIPT list-datasets --columns   # 同时显示每个数据集的字段
$SCRIPT list-datasets --refresh   # 强制刷新缓存（数据源有变更时用）

# 查字段（默认读本地缓存，自动包含计算字段）
$SCRIPT get-columns <ds_id>             # 输出原始字段 + 计算字段
$SCRIPT get-columns <ds_id> --refresh   # 强制刷新缓存
$SCRIPT get-columns <ds_id> --with-calc # 同时显示计算字段（公式字段）

# 查枚举值（筛选前必查，避免值不存在）
# fd_id 从 get-columns 输出第二列拿
$SCRIPT search-values <ds_id> <fd_id> --search "关键词"
$SCRIPT search-values <ds_id> --name "门店名称" --search "某门店"  # 用字段名代替 fd_id

# 建卡+取数（一步到位）
$SCRIPT create-and-get '{"name":"卡片名","ds_id":"数据集ID","chart_type":"SINGLE_VALUE","pg_id":"页面ID","metric":[{"name":"会员id","aggr":"CNT_DISTINCT"}],"filters":[{"name":"营业日期","op":"BT","value":["2026-02-01","2026-02-28"]}]}'
$SCRIPT create-and-get '{...}' --limit 200   # 限制返回200行数据（默认500行上限）

# 建卡+取数（组合图，metric_additional 传折线叠加数据）
$SCRIPT create-and-get '{"name":"达成率趋势","ds_id":"数据集ID","chart_type":"STACKED_COLUMN_WITH_LINE","pg_id":"页面ID","metric":[{"name":"营业额","aggr":"SUM"}],"metric_additional":[{"name":"人数","aggr":"SUM"}],"row":["营业日期(月)"],"column":["销售类型"],"filters":[...]}'

# 仅建卡（不取数）
$SCRIPT create-card '{...}'

# 取卡片数据（含筛选条件）
$SCRIPT get-card-data <card_id>

# 列页面
$SCRIPT list-pages
$SCRIPT list-pages --manageable  # 只显示有编辑权限的页面（日常用这个）

# 注意：list-datasets 默认显示父文件夹ID
# 输出格式示例：
#   数据集名称
#     ID: 数据集ID  |  行数  列数  |  状态
#     父文件夹ID: 父文件夹ID
#     描述: 描述信息
#     路径: 目录路径

# 创建页面
$SCRIPT create-page "页面名称"
$SCRIPT create-page "页面名称" --parent-dir "目录ID" --desc "描述"

# 获取页面卡片列表
$SCRIPT get-page-cards <pg_id>

# 批量删除卡片（需要 pg_id）
$SCRIPT delete-cards <pg_id> <card_id1> <card_id2> ...

💾 数据缓存机制

create-and-get、get-card-data 命令都会自动将数据保存到本地 CSV 缓存文件。

输出末尾会显示缓存路径：📁 缓存: skills/guandata/.cache/data/xxx.csv

缓存目录结构

skills/guandata/.cache/
├── data/                   # 数据查询缓存（CSV），默认共享目录
├── datasets/               # 数据集列表缓存（JSON）
├── columns/                # 字段列表缓存（JSON）
└── tasks/                  # 按任务隔离的缓存（使用 --task 参数时）
    └── {task_name}/
        ├── data/
        ├── datasets/
        └── columns/

按任务隔离缓存（--task）

不同任务的缓存混在一起时，用 --task 参数按任务名分组。--task 放在子命令前面：

# 堂食分析任务 → skills/guandata/.cache/tasks/堂食分析/data/
$SCRIPT --task "品类分析" create-and-get '{"name":"品类","ds_id":"<dataset_id>",...}'

# 查字段也隔离
$SCRIPT --task "会员分析" get-columns <dataset_id>

不加 --task 时，缓存仍在默认的 .cache/data/ 共享目录。

缓存清理

当缓存占用过多空间或数据过期时，需要清理缓存：

# 清理所有数据查询缓存（保留最近7天）
find skills/guandata/.cache/data -name "*.csv" -mtime +7 -delete

# 清理所有缓存（彻底清空）
rm -rf skills/guandata/.cache/*



### 缓存文件格式

CSV，首行为表头，后续行为数据。用 Excel / pandas / csv 模块直接读即可。

### 大模型使用规范

**当拿到取数结果后，必须用缓存文件处理数据，不要把大量数据塞进上下文。**

正确做法：
```python
import csv
# 1. 从输出中提取缓存路径
# 2. 用代码读取缓存
with open('skills/guandata/.cache/data/xxx.csv', encoding='utf-8-sig') as f:
    reader = csv.reader(f)
    headers = next(reader)
    rows = list(reader)
# headers[j] 是第 j 列的字段名
# rows[i][j] 是第 i 行第 j 列的值（字符串）

create-and-get / create-card 参数说明

create-and-get 和 create-card 共用以下参数格式：

| 参数 | 必填 | 类型 | 说明 | 类比 SQL | |------|------|------|------|----------| | name | ✅ | string | 卡片名称 | - | | ds_id | ✅ | string | 数据集 ID（用 list-datasets 查） | FROM 表 | | chart_type | ✅ | string | 图表类型（见下方速查表） | - | | pg_id | ✅ | string | 保存到的页面 ID（用 list-pages --manageable 找） | - | | row | | list | 行维度（分组依据） | GROUP BY | | column | | list | 列维度（横向拆列） | 交叉表列头 | | metric | | list | 数值（要算的指标） | SUM/AVG/COUNT | | metric_additional | | list | 叠加数值（组合图专用：柱+线的线） | - | | color_by | | list | 颜色分组（气泡图/散点图） | - | | size_by | | list | 气泡大小（气泡图专用） | - | | filters | | list | 筛选条件 | WHERE | | sorting | | list | 排序 | ORDER BY | | custom_fields | | list | 自定义公式字段（动态创建计算列） | SELECT ... , SUM(x)/SUM(y) AS 别名 |

举例说明：

{
  "row": ["城市"],                        // 按城市分行
  "column": ["销售类型名称"],              // 堂食/外卖拆成两列
  "metric": [{"name": "毛营业额", "aggr": "SUM"}],  // 每格填营业额总和
  "filters": [{"name": "营业日期", "op": "BT", "value": ["2026-01-01", "2026-02-28"]}],  // 只看1-2月
  "sorting": [{"name": "毛营业额", "order": "DESC"}]  // 按营业额降序排
}
// 等价于: SELECT 城市, 销售类型名称, SUM(毛营业额) FROM 表 WHERE 营业日期 BETWEEN ... GROUP BY 城市, 销售类型名称 ORDER BY SUM(毛营业额) DESC

自定义公式字段（custom_fields）

在创建卡片时动态添加计算字段，无需提前在观远界面建好：

$SCRIPT create-and-get '{
  "name": "成本率分析",
  "ds_id": "数据集ID",
  "chart_type": "GROUPED_COLUMN",
  "pg_id": "页面ID",
  "row": ["门店名称"],
  "metric": [
    {"name": "毛营业额", "aggr": "SUM"},
    {"name": "成本率"}
  ],
  "custom_fields": [
    {"name": "成本率", "fdType": "DOUBLE", "formula": "SUM([实际使用金额])/SUM([毛营业额])*100"}
  ],
  "filters": [{"name": "营业日期", "op": "BT", "value": ["2026-01-01", "2026-02-28"]}]
}'

参数格式：

| 字段 | 必填 | 说明 | |------|------|------| | name | ✅ | 新字段名称 | | fdType | ✅ | 数据类型：DOUBLE（数值）、STRING（文本）等 | | formula | ✅ | 公式表达式，用 [字段名] 引用字段，支持 SUM()/AVG() 等聚合 |

注意：

公式里的字段名必须是数据集中已存在的字段
创建后该字段可直接在 metric/row 中引用（和其他字段一样），如果公式已经聚合无需再写 aggr
仅 create-and-get 和 create-card 支持此参数

图表类型速查（26种）

| 类型 | metric | row | column | metric_additional | color_by | size_by | 备注 | |------|:------:|:---:|:------:|:-----------------:|:--------:|:-------:|------| | SINGLE_VALUE | 1 | 0 | 0 | 0 | 0 | 0 | 指标卡（单值） | | KPI_CARD | n | 0 | 0 | 0 | 0 | 0 | 指标卡（带阈值样式） | | BASIC_COLUMN | 1 | n | 0 | 0 | 0 | 0 | 柱状图 | | GROUPED_COLUMN | n | n | 1 | 0 | 0 | 0 | 簇状柱状图 | | STACKED_COLUMN | n | n | 1 | 0 | 0 | 0 | 堆积柱状图 | | PERCENT_STACKED_COLUMN | n | n | 1 | 0 | 0 | 0 | 百分比堆积柱状图 | | WATERFALL_COLUMN | 1 | n | 0 | 0 | 0 | 0 | 瀑布图 | | BULLET_COLUMN | 2 | n | 0 | 0 | 0 | 0 | 子弹图 | | BASIC_BAR | 1 | n | 0 | 0 | 0 | 0 | 条形图 | | BASIC_LINE | 1 | n | 0 | 0 | 0 | 0 | 折线图 | | MULTI_LINE | n | n | 1 | 0 | 0 | 0 | 多条折线图 | | STACKED_AREA | n | 1 | 1 | 0 | 0 | 0 | 堆积面积图 | | PERCENT_STACKED_AREA | n | 1 | 1 | 0 | 0 | 0 | 百分比堆积面积图 | | STACKED_COLUMN_WITH_LINE | n | 1 | 1 | 1 | 0 | 0 | metric=柱子, metric_additional=折线 | | GROUPED_COLUMN_WITH_LINE | n | 1 | 1 | 1 | 0 | 0 | metric=柱子, metric_additional=折线 | | STACKED_COLUMN_WITH_SYMBOL | n | 1 | 1 | 1 | 0 | 0 | metric=柱子, metric_additional=标记 | | GROUPED_COLUMN_WITH_SYMBOL | n | 1 | 1 | 1 | 0 | 0 | metric=柱子, metric_additional=标记 | | PIE | 1 | 1 | 0 | 0 | 0 | 0 | 饼图 | | TREE_MAP | 1 | n | 0 | 0 | 0 | 0 | 矩形树图 | | FUNNEL | n | 0 | 0 | 0 | 0 | 0 | 漏斗图 | | HEAT_MAP | 1 | 1 | 1 | 0 | 0 | 0 | 热力图 | | MULTIDIMENSIONAL_SANKEY | 1 | n | 0 | 0 | 0 | 0 | 多维桑基图 | | PIVOT_TABLE | n | n | n | 0 | 0 | 0 | 交叉表 | | WORD_CLOUD | 1 | 1 | 0 | 0 | 0 | 0 | 词云 | | BASIC_BUBBLE | 2 | n | 0 | 0 | 1 | 1 |气泡图 x=metric[0], y=metric[1] | | BASIC_SCATTER_PLOT | 2 | 1 | 0 | 0 | 1 | 0 | 散点图 x=metric[0], y=metric[1]|

n = 不限数量, 0 = 不支持, 2 = 最大2个

metric 格式

{"name": "毛营业额", "aggr": "SUM"}                         // SUM

{"name": "订单编码", "aggr": "CNT_DISTINCT", "alias": "订单数"}  // 指定聚合

{"name": "桌单价"}                           // 自定义字段如果在formula的计算公式中已聚合的情况下，就不再需要 aggr了

聚合方式: SUM / AVG / MAX / MIN / CNT / CNT_DISTINCT

filters 格式

// 维度筛选（WHERE）
{"name": "城市", "op": "IN", "value": ["上海市", "南京市"]}

// 日期范围
{"name": "营业日期", "op": "BT", "value": ["2026-01-01", "2026-02-28"]}

// 度量筛选（HAVING，聚合后过滤）
{"name": "毛营业额", "op": "GT", "value": ["1000000"]}

sorting 格式

// 单字段排序
[{"name": "毛营业额", "order": "DESC"}]
[{"name": "门店编号", "order": "ASC"}]

// 多字段排序
[{"name": "城市", "order": "ASC"}, {"name": "毛营业额", "order": "DESC"}]

字段名格式

row、column、metric.name、filters.name、sorting.name、color_by.name、size_by.name 都用字段名。

普通字段 — 直接写平台上的字段名：

"row": ["城市"]
"metric": [{"name": "毛营业额", "aggr": "SUM"}]
"filters": [{"name": "门店名称", "op": "EQ", "value": ["某门店"]}]

日期子字段 — 字段名(粒度)，自动按时间维度拆分：

| 写法 | 效果 | 示例输出 | |------|------|----------| | "营业日期(年)" | 按年汇总 | 2025 | | "营业日期(季度)" | 按季度汇总 | 2025年第4季度 | | "营业日期(月)" | 按月汇总 | 2025-11 | | "营业日期(周)" | 按周汇总 | 2025年第44周 | | "营业日期(星期)" | 按星期几汇总 | 星期六 |

"row": ["营业日期(月)"]   // 按月看趋势
"filters": [{"name": "营业日期(年)", "op": "IN", "value": ["2026"]}]  // 筛选2026年

filterType 速查

| 类型 | 含义 | 示例 | |------|------|------| | EQ | 等于 | ["A品牌"] | | NE | 不等于 | ["闭店"] | | IN | 在列表中 | ["上海市","北京市"] | | NI | 不在列表中 (Not In) | ["闭店","未开业"] | | BT | 范围 | ["2025-01-01","2025-12-31"] | | GT | 大于 | ["100"] | | GE | 大于等于 | ["100"] | | LT | 小于 | ["100"] | | LE | 小于等于 | ["100"] | | CONTAINS | 包含 | ["万达"] | | IS_NULL | 为空 | [] | | NOT_NULL | 不为空 | [] |

建卡示例

示例0：汇总值（row 为空） — 拿总计不拆维度

# row=[] 不分组，直接返回汇总值，不会截断
$SCRIPT create-and-get '{"name":"汇总","ds_id":"<dataset_id>","chart_type":"BASIC_COLUMN","pg_id":"<page_id>","row":[],"metric":[{"name":"毛营业额","aggr":"SUM"}],"filters":[{"name":"日结日期","op":"BT","value":["2026-03-16","2026-03-22"]}]}'
# 输出: 毛营业额: 313230258.42
# 卡片保留供复核，用户要求清理时再 delete-cards

示例1：指标卡 — 2月消费会员数

$SCRIPT create-and-get '{"name":"2月消费会员数","ds_id":"<dataset_id>","chart_type":"SINGLE_VALUE","pg_id":"页面ID","metric":[{"name":"会员id","aggr":"CNT_DISTINCT"}],"filters":[{"name":"营业日期","op":"BT","value":["2026-02-01","2026-02-28"]}]}'
# 输出: 会员id: 252335

示例2：柱状图 — 各城市毛营业额（按营业额降序）

$SCRIPT create-and-get '{"name":"各城市毛营业额","ds_id":"<dataset_id>","chart_type":"BASIC_COLUMN","pg_id":"页面ID","row":["城市"],"metric":[{"name":"毛营业额","aggr":"SUM"}],"filters":[{"name":"营业日期","op":"BT","value":["2026-01-01","2026-02-28"]}],"sorting":[{"name":"毛营业额","order":"DESC"}]}'
# 输出: 毛营业额: ['2323360', '8483271', ...]  维度: ['南京市', '南通市', ...]

示例3：交叉表 — 各城市×月份营业额（按城市+月份排序）

$SCRIPT create-and-get '{"name":"城市×月份营业额","ds_id":"<dataset_id>","chart_type":"PIVOT_TABLE","pg_id":"页面ID","row":["城市"],"column":["营业日期(月)"],"metric":[{"name":"毛营业额","aggr":"SUM"}],"filters":[{"name":"营业日期","op":"BT","value":["2025-01-01","2026-02-28"]}],"sorting":[{"name":"城市","order":"ASC"},{"name":"营业日期(月)","order":"ASC"}]}'
# 输出: [城市 ,月份 ,毛营业额].....['上海','2025-01','123232323'],['上海','2025-02','1230232333'].....
# 排序: 先按城市名正序，再按月份正序

示例4：多条折线图 — 各渠道月趋势

$SCRIPT create-and-get '{"name":"渠道月趋势","ds_id":"<dataset_id>","chart_type":"MULTI_LINE","pg_id":"页面ID","row":["营业日期(月)"],"column":["销售类型名称"],"metric":[{"name":"毛营业额","aggr":"SUM"}],"filters":[{"name":"营业日期","op":"BT","value":["2025-01-01","2026-02-28"]}]}'

示例5：组合图（柱+线） — 营业额柱状+消费人数折线

$SCRIPT create-and-get '{"name":"营业额与用餐人数","ds_id":"<dataset_id>","chart_type":"STACKED_COLUMN_WITH_LINE","pg_id":"页面ID","row":["营业日期(月)"],"column":["销售类型名称"],"metric":[{"name":"毛营业额","aggr":"SUM"}],"metric_additional":[{"name":"用餐人数","aggr":"SUM"}],"filters":[{"name":"营业日期","op":"BT","value":["2026-01-01","2026-02-28"]}]}'

示例6：气泡图 — 各门店营业额vs实收金额（按城市着色，气泡大小=用餐人数）

$SCRIPT create-and-get '{"name":"门店气泡图","ds_id":"<dataset_id>","chart_type":"BASIC_BUBBLE","pg_id":"页面ID","row":["城市","门店"],"metric":[{"name":"毛营业额","aggr":"SUM"},{"name":"菜品实收金额","aggr":"SUM"}],"size_by":[{"name":"用餐人数","aggr":"SUM"}],"color_by":[{"name":"城市"}],"filters":[{"name":"营业日期","op":"BT","value":["2026-01-01","2026-02-28"]}]}'
# row=维度标签, metric[0]=x, metric[1]=y, color_by=颜色分组, size_by=气泡大小

完整工作流示例

需求：做一张「2026年2月各城市外卖销售类型毛营业额 TOP10」交叉表

# Step 1: 通过表id查字段，确认可用字段
$SCRIPT get-columns <dataset_id>
# → 确认: 城市(DIM), 毛营业额(METRIC), 销售类型名称(DIM), 营业日期(DATE)

# Step 2: 查枚举值（因为用了 IN/EQ 筛选，必须查）
$SCRIPT search-values <dataset_id> --name "销售类型名称" --search "外卖"
# → 确认值是 "外卖"

# Step 3: 建交叉表，自动取数
$SCRIPT create-and-get '{"name":"2月外卖各城市毛营业额","ds_id":"<dataset_id>","chart_type":"PIVOT_TABLE","pg_id":"<page_id>","row":["城市"],"column":["销售类型名称"],"metric":[{"name":"毛营业额","aggr":"SUM"}],"filters":[{"name":"营业日期","op":"BT","value":["2026-02-01","2026-02-28"]},{"name":"销售类型名称","op":"EQ","value":["外卖"]}],"sorting":[{"name":"毛营业额","order":"DESC"}]}'

💡 如果只做日期或数值筛选（无分类筛选），跳过 Step 2，两步搞定。

错误处理

| 状态码 | 处理 | |--------|------| | 500 | 终止，服务器问题 | | 401 | 终止，登录失效 | | 403 | 终止，无权限 | | 404 | 终止，资源不存在 |