majia-guanyuan · 观远 BI 通用 Agent Skill

工具无关的观远 BI / Guandata Agent Skill — 数据查询 / ETL 治理与写入 / 自定义图表开发，全栈三合一。 兼容 Claude Code · OpenClaw · Codex · Hermes (gbrain) 等所有支持 SKILL.md 的 agent 工具。 60+ 张 ETL 创建/重构/修复 + 治理扫描 + 自定义图表注入排障的真实战场记录。

English README · 中文文档 ↓

概述

本 Skill 整合了观远 BI 的三大类操作能力到一份 Claude Code Skill 里，让 AI 既能日常查数据出报表，又能做严肃的 ETL 治理与写入，还能处理自定义图表的前端注入排障。

| Part | 能力 | 触发场景 | |---|---|---| | 🅰️ A | 数据查询与卡片创建 | "查 2 月各城市营业额" / "做一张交叉表" / "删掉这张卡片" | | 🅱️ B | ETL 治理与写入 | "扫一遍 ETL 看哪些可以删" / "建一个 ETL" / "direct-save 报错怎么修" | | 🅱️ B-17 | 全链路重写方法论 | "把这条 SmartETL 链整个改成 SQL 版" / "副本页验收 / 卡片级对比" | | 🆎 C | 自定义图表开发与排障 | "payload_json 解析失败" / "固定卡片错位" / "overlay 切页残留" |

✨ 效果

数据分析侧（Part A）

• ✅ 26 种图表类型一键建卡 + 取数（柱状图、折线图、交叉表、组合图、气泡图……）
• ✅ 自定义公式字段（动态 SUM(x)/SUM(y)*100 类计算列，无需提前在 BI 界面建好）
• ✅ 多表 / 多页面 / 多字段缓存机制（按任务隔离 --task 名）
• ✅ 26 种聚合 + 13 种筛选操作符 + 6 种日期粒度（年/季/月/周/日/星期）
• ✅ 自动处理观远 7.0+ 的 draft-release 机制

ETL 治理写入侧（Part B）

• ✅ 11 个已实测 BI HTTP API endpoint（POST/GET/DELETE/OPTIONS 全覆盖）
• ✅ 批量治理扫描：构建依赖图 → 检测循环依赖 → 计算复杂度 → 8 维 ETL + 4 维字段去留判断
• ✅ ODS/DIM/DWD/DWS/APP 五层架构重组指引
• ✅ 字段使用度双源审计（page + etl 双源 grep，避免仅看板会高估 8 倍可裁字段）
• ✅ POST /api/etl/direct-save create + update 同接口的完整 payload schema
• ✅ task error 真错误定位（status:FINISHED 是任务触发结果，真错误在 GET /api/task/<id>.response.result.error）
• ✅ 删除拓扑：DELETE /api/data-source/ 必须先于 DELETE /api/etl/
• ✅ v2→v3 批量改造 SDK：transformV2ToV3() 7 步重写 + 节点 ID 重映射
• ✅ CTO 张进的全链路重写方法论：4 件交付 + 8 条硬规则 + 5 步标准工作流 + 三层验收 + 差异追踪 5 步法 + 空快照处理标准

自定义图表侧（Part C）

• ✅ renderChart 4 参数 runtime 契约详解（不是把第一个参数当 DOM 根节点）
• ✅ 5 种 data 形态识别
• ✅ payload_json 截断判断 3 步（Unterminated string → 优先改数据方案，不堆兼容逻辑）
• ✅ 拆列推荐方案（替代单字段长 JSON）
• ✅ z-index 基线（容器 8 / mask 1 / 固定卡 20）
• ✅ 生命周期管理（URL 不匹配/编辑态/phoneView/路由离开 → 销毁注入物）
• ✅ MutationObserver 死循环陷阱（用低频轮询 + 精准 rect 比较替代）
• ✅ 复制页 card id 重定位（不会显式报错，只会悄悄失效）
• ✅ 真实浏览器验收 8 项

报错修复手册

• 🔧 10 类 ETL 高频报错：请输入ETL名称 / 保存路径无效 / 上游运行权限不足 / 字段隐藏换行 / <> NULL / relativeFieldAlias 错位 / CTE 内 ; / self-join 别名同名 / UNION 列差 / 字符串字面量与 DATE 比较

✅ 适合 / ❌ 不适合

✅ 适合

• 在观远 BI（Guandata 6.x / 7.x）上做日常数据分析、出报表
• 做 ETL 治理（识别循环依赖、判断字段去留、重新分层）
• 批量重建 ETL（30+ 张 v2→v3 改造）
• 做副本页验收 / 卡片级对比 / 差异追踪
• 自定义图表 HTML/CSS/JS 注入开发与排障
• 不会写代码但想让 AI 帮你完成上面这些事

❌ 不适合

• 用其他 BI 平台（Tableau / Power BI / Superset）—— 本 skill 只针对观远 BI / Guandata
• 完全不允许调用底层 HTTP API 的合规环境
• 没有 BI 账号 + 写权限（Part B 写入需要 ETL 创建权限 + 数据集运行权限）

🔌 兼容性 / Compatibility

本 skill 工具无关，凡是支持 SKILL.md frontmatter 标准的 agent 都能加载。已在以下工具上验证：

| 工具 | 状态 | 安装路径 | 入口文件 | 备注 | |---|:---:|---|---|---| | Claude Code | ✅ 已验证 | ~/.claude/skills/majia-guanyuan/ | SKILL.md | 原生支持 | | OpenClaw | ✅ 已验证 | ~/.openclaw/skills/majia-guanyuan/ 或 <workspace>/skills/majia-guanyuan/ | SKILL.md | 大小写敏感 | | Codex (OpenAI) | ✅ 已验证 | ~/.codex/skills/majia-guanyuan/ 或 <repo>/.codex/skills/majia-guanyuan/ | SKILL.md + 仓库根 AGENTS.md（项目指令） | 见 Codex skills docs | | Hermes / gbrain | ✅ 已验证 | <workspace>/skills/majia-guanyuan/ | SKILL.md + 仓库根 AGENTS.md（resolver） | 见 garrytan/gbrain | | Cursor / Aider 等 AGENTS.md-aware | 🟡 理论兼容 | 任意 | AGENTS.md 作项目指令 | 仅会用到 Part A/B/C 的 navigation pointer | | 其他 | 🟡 通用清单 | 任意 | manifest.json 作工具无关元数据 | frontmatter + manifest 双保险 |

📦 安装

本仓库以 git 为唯一 source of truth，未发布到 npm registry。但保留了一行 install 体验——通过 node bin/install.js 或 npx github: 直接走 GitHub。

方式 0：GitHub CLI gh skill（GitHub CLI 2.90.0+）

# 安装到用户级 Codex / Claude Code / OpenClaw / Qoder 等 agent
gh skill install maojiebc/majia-guanyuan majia-guanyuan --agent codex --scope user
gh skill install maojiebc/majia-guanyuan majia-guanyuan --agent claude-code --scope user
gh skill install maojiebc/majia-guanyuan majia-guanyuan --agent openclaw --scope user
gh skill install maojiebc/majia-guanyuan majia-guanyuan --agent qoder --scope user

# 安装前预览
gh skill preview maojiebc/majia-guanyuan majia-guanyuan

⭐ 方式 1：克隆 + 内置 install CLI（推荐）

# 一键克隆 + 自动安装到当前机器上所有已装的 agent 工具
git clone https://github.com/maojiebc/majia-guanyuan.git ~/majia-guanyuan
cd ~/majia-guanyuan
node bin/install.js install                  # 自动检测全装
node bin/install.js install --tool claude-code
node bin/install.js install --tool openclaw
node bin/install.js install --tool codex
node bin/install.js install --tool hermes
node bin/install.js install --tool all       # 4 个全装

# 其他命令
node bin/install.js list                     # 列出当前安装情况
node bin/install.js uninstall --tool codex   # 移除（自动备份你的 config.json）

方式 2：npx 直接走 GitHub URL（不需要 clone）

# 一行装，npx 自动从 GitHub 拉取并跑 bin/install.js
npx github:maojiebc/majia-guanyuan install --tool claude-code
npx github:maojiebc/majia-guanyuan install --tool all

bin/install.js 行为（两种方式相同）：

• 自动复制 SKILL.md / AGENTS.md / manifest.json / scripts/ / references/ 等到目标工具的 skill 目录
• 自动 cp config.example.json → config.json，提示你编辑填凭据
• 永远不覆盖你已有的 config.json（保留真凭据，再装一次也不丢）
• 已装时默认跳过，要 --force 才覆盖

方式 3：手动 git clone 直接放到工具 skill 目录

# Claude Code
git clone https://github.com/maojiebc/majia-guanyuan.git ~/.claude/skills/majia-guanyuan

# OpenClaw（个人级）
git clone https://github.com/maojiebc/majia-guanyuan.git ~/.openclaw/skills/majia-guanyuan

# Codex（个人级）
git clone https://github.com/maojiebc/majia-guanyuan.git ~/.codex/skills/majia-guanyuan

# Codex（项目级）
git clone https://github.com/maojiebc/majia-guanyuan.git <your-repo>/.codex/skills/majia-guanyuan

# Hermes / gbrain（workspace 级）
git clone https://github.com/maojiebc/majia-guanyuan.git <your-workspace>/skills/majia-guanyuan

然后配置凭据（所有工具相同）：

cd <安装路径>
cp config.example.json config.json
vim config.json  # 填入 BI base_url / login_id / password / default_pg_id / default_folder_id

方式 4：OpenClaw / ClawHub 一键安装

openclaw skills install majia-guanyuan
clawhub install majia-guanyuan

ClawHub 可能显示安全扫描提醒：本 skill 包含一个本地 Python 客户端，会按观远接口要求把登录凭据编码后发送到用户自己配置的 base_url。安装前可先阅读 SECURITY.md 并检查 scripts/guandata.py。

方式 5：Hermes skillpack 安装（如发布到 gbrain registry）

gbrain skillpack install majia-guanyuan

依赖（所有工具相同）

# Python 依赖（Part A）
pip install httpx

# guancli（Part B/C 必需）
npm install -g @guandata/guancli
guancli auth login   # 配置 BI 登录

⚙️ 配置

把 config.example.json 复制为 config.json 后填入真实凭据：

{
  "version": "6",
  "base_url": "https://your-bi-instance.example.com/",
  "domain": "guanbi",
  "login_id": "[email protected]",
  "password": "<BI_LOGIN_PASSWORD>",
  "default_pg_id": "your_default_page_id",
  "default_folder_id": "your_default_folder_id"
}

| 字段 | 必填 | 说明 | |------|:----:|------| | version | ✅ | "6"（观远 BI 6.x）或 "7"（观远 BI 7.0+，支持 draft/release） | | base_url | ✅ | BI 实例地址，如 https://bi.company.com:8080 | | domain | ✅ | 登录域，通常为 guanbi（具体咨询 BI 管理员） | | login_id | ✅ | BI 登录账号 | | password | ✅ | BI 登录密码（明文，仅供本地使用，已被 .gitignore 排除） | | default_pg_id | | 默认页面 ID（建卡时不传 pg_id 用这个） | | default_folder_id | | 默认文件夹 ID（创建新页面时使用） |

⚠️ config.json 已被 .gitignore 排除，不会被 commit 到仓库。但请仍然小心保管，不要在公开环境分享。

🚀 快速开始

Part A：建卡取数（数据分析）

# cwd 切到 skill 安装目录，所有命令用相对路径
cd <skill_install_path>  # 例如 ~/.claude/skills/majia-guanyuan/

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

# 1. 列数据集
$SCRIPT list-datasets

# 2. 看字段
$SCRIPT get-columns <ds_id>

# 3. 一步建卡 + 取数
$SCRIPT create-and-get '{
  "name": "2 月各城市营业额",
  "ds_id": "<dataset_id>",
  "chart_type": "BASIC_COLUMN",
  "pg_id": "<page_id>",
  "row": ["城市"],
  "metric": [{"name": "销售额", "aggr": "SUM"}],
  "filters": [{"name": "营业日期", "op": "BT", "value": ["2026-02-01", "2026-02-28"]}],
  "sorting": [{"name": "销售额", "order": "DESC"}]
}'

Part B：建 ETL（数据建模）

# 1. 治理扫描
guancli etl tree
guancli --raw etl get <id> > raw/<id>.json
# 本地脚本分析依赖图、循环组、复杂度 → analysis.json + governance-report.md

# 2. 建 v2 目录（ETL + DATA_SET 各一个）
guancli fetch POST /api/directory \
  '{"name":"warehouse_v2","parentDirId":"<父>","dirType":"ETL"}'
guancli fetch POST /api/directory \
  '{"name":"warehouse_v2","parentDirId":"<父>","dirType":"DATA_SET"}'

# 3. 写入 + 执行
guancli fetch POST /api/etl/direct-save --stdin < payload.json
guancli fetch POST /api/etl/execute '{"dataFlowId":"<id>"}'

# 4. 失败定位（关键！别只看 status:FINISHED）
guancli fetch GET /api/task/<taskId> | jq '.response.result.error'

Part C：自定义图表（前端排障）

// 观远 runtime 真实签名（不是把第一个参数当 DOM 根节点！）
function renderChart(data, clickFunc, config, helpers) {
  // data 常见形态：
  // [[ {name:"payload_json",data:["{...}"]}, {name:"report_date",data:["2026-03-18"]} ]]

  // 关键：如果 JSON.parse(payload_json) 报 Unterminated string
  //  → 优先判断为"数据链路截断"，改数据方案（拆列），不堆前端兼容逻辑
}

new GDPlugin().init(renderChart);

📁 目录结构

majia-guanyuan/
├── SKILL.md                          # AI 读的主文档（Part A + B + C）
├── AGENTS.md                         # Codex 项目指令 / Hermes resolver（V1.3 新增）
├── manifest.json                     # 工具无关 skill 元数据（V1.3 新增）
├── README.md                         # 本文件（中文）
├── README.en.md                      # English README
├── ATTRIBUTIONS.md                   # 致谢与来源
├── LICENSE                           # MIT
├── config.example.json               # 配置模板（公开版）
├── config.json                       # 你的真实凭据（gitignore 排除，不会 commit）
├── .gitignore
├── scripts/
│   ├── guandata.py                   # Part A 主脚本（建卡 / 取数 / 删卡 / 发布页面）
│   └── zonedata_builder/             # zoneData 构建模块
└── references/                       # 深度参考资料 (V1.5.0 progressive disclosure 重构后 12 份)
    ├── part-a-commands.md            # Part A 完整命令清单 + 缓存机制（V1.5.0）
    ├── part-a-cards.md               # 卡片参数 + 26 图表类型 + 6 示例（V1.5.0）
    ├── part-b-errors.md              # Part B 10 类报错详方案（V1.5.0）
    ├── part-b-payload.md             # ETL payload schema 详解（V1.5.0）
    ├── part-b-sdk.md                 # v2→v3 批量改造 SDK（V1.5.0）
    ├── part-b17-fullchain-rewrite.md # B-17 全链路重写方法论全章节（V1.5.0）
    ├── part-c-payload-json.md        # C-3 payload_json 排障详解（V1.5.0）
    ├── guancli-commands.md           # guancli 9 大类命令速查（V1.5.0）
    ├── custom-chart-playbook.md      # CTO 张进自定义图表完整排障手册原文（V1.1）
    ├── etl-rewrite-original.md       # CTO 张进 SmartETL 改写经验原文（V1.1）
    ├── execplan-spec.md              # OpenAI Codex ExecPlan 规范（V1.2）
    └── agents-rule.md                # OpenAI Codex 极简调度规则（V1.2）

🎯 何时用 Part A / B / C

| 用户需求 | 走 | |---|---| | "查一下 2 月各城市营业额" | A | | "做一张交叉表给我" | A | | "删掉这张卡片" | A | | "扫一遍 BI 的 ETL 看哪些可以删" | B | | "ETL 之间有循环依赖怎么办" | B | | "帮我新建一个 ETL" | B | | "direct-save 报错怎么修" | B | | "字段使用度审计" | B | | "把这条 SmartETL 链整个改成 SQL 版" | B-17 | | "做副本页验收 / 卡片级对比" | B-17 | | "上游空快照怎么写结论" | B-17 | | "差异定位到底在 SQL 还是执行时点" | B-17 | | "30+ 表跨多日工程怎么管 / 给我 ExecPlan 骨架" | B-17.11 | | "自定义图表脚本不执行 / payload_json 报错" | C | | "固定卡片错位 / overlay 切页残留" | C | | "renderChart 第一个参数到底是啥" | C |

👤 作者 / 联系

马甲（@maojiebc） · 超级马甲

如果这份 skill 帮到你，欢迎在以下任意渠道找我交流踩坑实录、提需求、报 bug，也欢迎切磋用户运营 / 数据中台 / BI 工程的实战经验：

| 渠道 | 链接 | |---|---| | 📧 Email | [email protected] | | 🐙 GitHub | github.com/maojiebc | | 🪝 ClawHub | clawhub.ai/p/maojiebc | | 🐦 X | @maojiebc | | 📕 小红书 | 超级马甲 | | 📰 微信公众号 | 超级马甲 |

这份 skill 是 14 年用户运营 + 观远 BI 实战 + 60+ 张 ETL 写入实证沉淀出来的，问题/合作随时聊。

❤️ 致谢与来源

本 skill 站在多个前辈项目和经验贡献者的肩膀上，详细致谢见 ATTRIBUTIONS.md：

• guandata-bi @ ClawHub — 观远 BI 通用版 skill，本项目最早的灵感来源
• zhengyuhe123/guandata — guandata 原始 GitHub 项目
• 小小郑3号 · guandata70 — 观远 7.0+ 适配版（draft/release 机制），本项目 Part A 的直接前身
• 观远 BI CTO 张进 — Part B-17（SmartETL 全链路重写方法论）+ Part C（自定义图表开发与排障）的核心经验贡献者
• OpenAI Codex — V1.2 引入的 ExecPlan 规范（自包含活文档 + 四章节项目管理结构），用于 30+ 张表跨多日 SmartETL 重写工程的项目化追踪
• 马甲（@maojiebc） — Part A/B 实战整合与 60+ 张 ETL 写入实证记录

没有 ClawHub / 张进 / 小小郑3号 / OpenAI Codex 的开源精神，这份 skill 不可能存在。

📋 版本记录

最新：V2.1.4 (2026-05-15) — 命令面同步 @guandata/[email protected]：① metric query 泛化查询（1.0.20 新增）完整接入 —— --compare yoy|mom|qoq|wow|dod、--xtd ytd|qtd|mtd|wtd|dtd、--recent 7d|4w|3m（带 --recent-base）、--percentage --percentage-dim、--rank-top N --rank-dim ... --rank-order、--last、兜底 --adv-calc-json，业务侧"同比/累计/最近 N 天/各城市占比/Top 10"一行命令出数，不必去 BI 后台建派生指标实例；② card preview -f excel（1.0.20）—— Excel 2003 XML 直接重定向 .xls，同时 --limit 默认抬到 10000、--sort-asc/desc 取数下限 10000；③ 错误输出更干净（1.0.21），guancli ... 2>&1 | head -n 5 不再被 Usage: / Available Commands: 长串覆盖，Part B 报错速查脚本更可靠。manifest 依赖约束 ^1.0.19 → ^1.0.21；命令面与判断表写进 references/guancli-commands.md。

V2.1.3 (2026-05-14) — 纯文档 patch：刷新 docs/architecture.svg 功能说明图，从 v1.5 "三块拼图"升级到 v2.1.x 现实——新增"三件套生态"条带（guancli 1.0.19 / guanvis-skill 0.1.13 / majia-guanyuan 2.1.3）+ Part C-12 HTML 应用化看板 NEW 高亮模块（粉紫渐变 + glow）+ 底部数字校准。同步生成 2880×1840 @2x DPI PNG 渲染产物（docs/architecture.png，供 npm/ClawHub 页面 fallback）。package.json#files 把 docs/ 也补进 npm tarball。

V2.1.2 (2026-05-14) — V2.1.1 的纯打包 hotfix：package.json#files 字段补上 templates/，让 npm install 的用户也能拿到 templates/html-dashboard/ 起手模板包；其他安装路径（GitHub clone / gh skill install / ClawHub）从 V2.1.1 起就已经包含 templates/。

V2.1.1 (2026-05-14) — 新增 Part C-12：HTML 应用化看板生成（references/part-c-html-dashboard.md + templates/html-dashboard/ 模板包，含 GDHTML runtime 12 个 API + 2 个起手模块 + patch_selector_linkage.js）。用户说"更高级/应用化/不限标准看板"时自动切到 SDK 子类型 + DATA_GRID dataView 数据层架构，弥补 guanvis-skill .linkToAll() 联不到 custom chart 内部 dataView 的盲区。guancli card preview 命令面同步纠正（不再有 --pg-id），新增 .data // .response jq 兼容写法。

V2.1.0 (2026-05-13) — [email protected] 内网 Nexus 上线，Part A 标准建卡路由优先指向它；新增 references/internal-nexus-install.md 内网 tarball 安装手册（含 macOS com.apple.quarantine 坑）；与官方 skill 共存表升级为三件套分工。

完整变更历史见 CHANGELOG.md 或 GitHub Releases。

🤝 贡献

欢迎 issue 和 PR：

• 🐛 发现报错没在手册里的：欢迎提交 issue 描述报错信息 + payload + 真实错误（/api/task/<id>.response.result.error）
• 📝 你跑通了新的 BI HTTP API endpoint：欢迎补充到 Part B 的 API 全图
• 🎨 自定义图表新场景：欢迎补充到 Part C
• 📚 文档优化、翻译、错别字修正：直接 PR

📄 License

MIT © 2026 maojiebc and contributors.

本 skill 基于他人开源工作整合而成，详细 attribution 见 ATTRIBUTIONS.md。