观远 BI · 马甲专版（V2.1.14）

结构说明（V1.5.0 引入 progressive disclosure）：本文档是路由层 + 关键规则，详细操作手册下沉到 references/。每个 Part 的入口章节会指出"何时回到 references/ 查全表"。完整章节索引见末尾的 📚 References 目录。

🧭 Part 选择

你想做	走
查数据、建卡、生成报表、做分析	Part A：数据查询与卡片创建
扫整库 ETL 治理 / 新建/修改/删除 ETL / 字段使用度审计 / 修复 ETL 报错	Part B：ETL 治理与写入
把整条 SmartETL 链改写成 SQL 版 + 页面副本验收 + 差异定位 + 空快照阻塞	Part B-17：全链路重写方法论（拆到 references/part-b17-fullchain-rewrite.md）
30+ 张表批量迁移 / 跨多日工程 / 复杂重构需要项目化追踪	B-17.11 ExecPlan 工作法（同上文件 §11）
自定义图表 HTML/CSS/JS 注入、固定卡片/overlay、payload_json 取数、路由清理	Part C：自定义图表开发与排障
从零生成 HTML 化经营分析应用（用户说"更高级 / 应用化 / 自定义模块 / 最完美 / 不限标准看板"）	Part C-12：HTML 应用化看板生成（拆到 references/part-c-html-dashboard.md）
v7 BI 实例上端到端搭多个 HTML 应用看板 / 手撸 `POST /api/page+/api/card` 被 `60004 此操作只能在草稿页面执行` 卡住 / CSV 散客 `会员ID IS NOT NULL` 算出 100% 假指标 / Spark `WITH 中文别名` 报 `PARSE_SYNTAX_ERROR` / ETL update 报 `1012 输出数据集目录中存在同名文件`	Part D：V7 Page/Card 发布流水线 + 三态硬规则（V2.1.6 新增，拆到 references/v7-page-card-publish-pipeline.md）
SuperApp / 超级应用 / 开放应用开发流水线 / `guancli app create/publish` / `--app-id` 不传变成每次新建 / 数据集异步预览 3 步 / `form_xxx` 建表反向工程（脚手架没暴露建表 API，实测 `POST /survey-engine/api/form/add`）/ BI 中转 LLM 报 NOT_JSON_RES / ILLEGAL_JSON_RES（响应被塞在 error_message）/ `/api/llm-config/list` 返回裸数组被脚手架 unwrap 吞 / 同源 fetch credentials 不带 cookie / 客户端模拟流式打字效果 / 任务池工作台「看 + 想 + 选 + 做 + 留痕」闭环	Part E：SuperApp 开放应用开发流水线（V2.1.12 新增，拆到 references/part-e-superapp-pipeline.md）
客户说"想给现有 BI 接 AI / 上 LLM" / "我们 ETL 治理做了一年还没出活" / 判断是该治理还是该重搭 / 客户预算分配讨论 / 评估底表 schema 是否 AI-friendly / 提案"AI-native 数据底座"	AI-native ADS 设计方法论（V2.1.13 新增，majia-guanyuan 的哲学层文档——不是操作手册而是范式判断，拆到 references/ai-native-ads-design.md）
写餐饮业务公式（AC / ADS / 复购率 / 新老客 / 用餐时段 / 留存流失 / RFM / Comp 老店）/ 查字段口径 / 排数据质量坑 / ETL 工程范式（DWD 宽表 / 双源对账 / 评价 pipeline）	餐饮 BI 公式实战库（references/restaurant-bi-formulas/README.md，V2.1.5 蒸馏自两段餐饮连锁 BI 履职 + 39 个生产 ETL，全脱敏）
不知道用哪个	看 Part B "推荐工作流" 章节，或直接读各 Part 章节末尾的"实战 ID 速查"

作者：马甲（Part A/B 实证）+ 观远 CTO 张进（Part B-17 SmartETL 改写方法论 + Part C 自定义图表经验）+ OpenAI Codex（V1.2 ExecPlan 规范）版本：V2.1.14（2026-05-29）· 环境：Node ≥20 · 依赖：@guandata/guancli@^1.0.29（V2.1.6 起：1.0.24 自带 guanvis-skill 公网分发，guancli install-skill 一键装到 ~/.agents/skills/；V2.1.12 起：guancli app create/publish 用于 SuperApp 开发流水线；V2.1.14 起：对齐 1.0.29 —— ds execute-sql / metric project / server-version 新命令） · 作用域：本地私有 BI 实例安装：git clone https://github.com/maojiebc/majia-guanyuan.git + node bin/install.js install，或 npx github:maojiebc/majia-guanyuan install 兼容工具：Claude Code · OpenClaw · Codex · Hermes (gbrain) · 任何支持 SKILL.md frontmatter 的 agent。详见 README · 兼容性与 AGENTS.md。

🆕 V2.0 升级提示：原名 guanyuan-majia 已重命名为 majia-guanyuan，对齐马甲家族风格。GitHub repo URL 同步迁至 maojiebc/majia-guanyuan（旧地址自动 redirect，老 clone 不影响）。新增命令面与 @guandata/guancli@1.0.19 对齐 —— ChatBI 主题问数 (guancli chatbi) / SuperApp (guancli app) / 多环境 auth (auth list/use/whoami) / 连接探测 (guancli status)。详见 CHANGELOG.md。

🆕 V2.1 升级提示（2026-05-13）：官方 @guandata/guanvis-skill@0.1.13 已通过观远内网 Nexus 私服（https://app.mayidata.com/nexus/repository/guandata-web/）分发，公网 npm 仍 404；内网员工可让同事下 tarball 走 references/internal-nexus-install.md 的"四步法"装上。本 skill Part A 的标准 30+ 图表建卡需求优先路由到 guanvis-skill 的 JS DSL（card_*.js / page.js），本 skill 的 guandata.py / create-card 保留为 fallback + payload 底层参考，便于无 guanvis-skill 的环境继续工作。其他四个兄弟 skill（guanetl-skill / guands-skill / guanexport-skill / guanadmin-skill）公网 + 内网均未确认发包，仍走 guancli fetch + 本 skill Part B。

🅰️ Part A：数据查询与卡片创建

⚠️ 关键规则

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

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

遇到意外的错误以及得到新的教训立即更新： 遇到意外的错误立即把它落到 SKILL.md 对应的章节（Part B 报错走 references/part-b-errors.md，Part C 走 references/part-c-payload-json.md 等）或 ExecPlan 的 Surprises & Discoveries 章节（B-17.11）。格式：

### [YYYY-MM-DD] 简要标题
- **场景**: 什么情况下遇到的
- **问题**: 发生了什么（含 task error 原文、payload 片段）
- **判断**: 应该怎么做

基本信息

路径约定：以下命令假定 cwd 是 skill 安装目录。Skill 路径因 agent 工具不同而异（见 README 的兼容性表）：Claude Code 在 ~/.claude/skills/majia-guanyuan/，OpenClaw 在 ~/.openclaw/skills/majia-guanyuan/，Codex 在 ~/.codex/skills/majia-guanyuan/，Hermes 在 <workspace>/skills/majia-guanyuan/。所有 Part A 命令都用相对路径 scripts/guandata.py，无需修改。

配置文件: config.json（含明文凭据，已被 .gitignore 排除）
脚本: scripts/guandata.py
运行环境：Python 3.8+，依赖 httpx（pip install httpx）

配置说明

编辑 config.json：

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

字段	必填	说明
`version`	✅	观远BI版本：`"6"`（直接保存卡片）或 `"7"`（7.0+ draft/release 机制，自动发布）
`base_url`	✅	观远BI服务器地址，如 `https://bi.company.com:8080`
`domain`	✅	登录域，通常为 `guanbi`，具体咨询你们的BI管理员
`login_id` / `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在「数据管理」→「目录」中查看。

命令骨架（最常用 10 条）

SCRIPT="python3 scripts/guandata.py"

# 探索
$SCRIPT list-datasets [--columns] [--refresh]    # 数据集（默认走缓存）
$SCRIPT get-columns <ds_id> [--with-calc]        # 字段（含计算字段）
$SCRIPT search-values <ds_id> --name "字段名" --search "关键词"   # 枚举值

# 建卡 / 取数
$SCRIPT create-and-get '<json>'   # 建卡 + 取数（一步到位）
$SCRIPT create-card '<json>'      # 仅建卡
$SCRIPT get-card-data <card_id>   # 取已存在卡片的数据

# 页面 / 卡片管理
$SCRIPT list-pages --manageable   # 有编辑权限的页面（日常用这个）
$SCRIPT delete-cards <pg_id> <card_id1> <card_id2> ...

# 诊断 / 认证
$SCRIPT status                    # 查看配置、token、缓存状态
$SCRIPT set-token <jwt> [--expires 7200]   # 手动设置 JWT（从浏览器复制时用）

完整命令清单（含 --task 缓存隔离、create-page / release-page / get-page-cards、缓存清理、CSV 缓存使用规范）见 references/part-a-commands.md。

写卡片前必读

🚦 V2.1 路由提示：如果用户的需求是"做销售仪表板 / 加 KPI 卡片 / 柱状图展示门店排名 / 新建区域筛选器联动"等标准图表/Page 装配 —— 优先用 guanvis-skill 的 JS DSL（card_*.js / selector_*.js / page.js → pack/publish），它的 30+ 图表类型覆盖、selector 联动、主题切换、批量发布都比手拼 JSON 顺手。本节的 create-and-get / create-card 保留作为 fallback（无 guanvis-skill 的环境）+ payload 底层参考（理解 chart_type / metric / filters 字段语义）。guanvis-skill 安装见 references/internal-nexus-install.md，触发关键词见其 SKILL 描述。

反过来，超出官方组件能力的视觉定制（双 Y 轴叠加、ECharts 自定义渲染、图例改圆点、tooltip HTML 重写、固定卡片/overlay）走 Part C，guanvis-skill 不覆盖这些。

create-and-get / create-card 的 JSON 参数有 13 个字段，2 种格式（metric/filters/sorting/字段名/filterType），26 种 chart_type，6 种日期粒度。写卡前先回到参考表：

📖 references/part-a-cards.md — 完整参数表 + 26 种图表类型 + metric/filters/sorting/字段名/filterType 全格式 + 6 个建卡示例（指标卡 / 柱状图 / 交叉表 / 多线图 / 组合图 / 气泡图）+ 完整工作流示例 + 自定义公式字段 custom_fields。

guancli 补充：只读探索 + 表单 CRUD

guandata.py vs guancli 分工：

guandata.py → 建卡、取数、删卡、发布页面（写操作）
guancli → 搜索、探索、ETL/指标/任务/表单（读操作 + 表单 CRUD）

何时用 guancli 替代 list-datasets / list-pages：

库里数据集/页面很多 → `guancli ds search

majia-guanyuan