核心定位
majia-guanyuan 是架在观远官方全家桶（guancli/guanvis/guanetl/guanwf/guands）之上的实战增益层 Agent Skill，版本 3.1.4。官方工具覆盖标准查数、建卡、ETL CRUD 等「表层操作」，本 skill 专攻官方 DSL/命令够不着的硬骨头：整库 ETL 治理判断、BI 引擎运行期报错、状态机绕过、反向工程、业务口径沉淀。
五大实战模块（Part B–E + 方法论）
| 模块 | 解决什么问题 | 典型场景 |
|:---|:---|:---|
| **Part B** ETL 治理与写入 | 整库扫描、循环依赖拆解、字段使用度审计、SmartETL 全链路重写 | 「ETL 治理做了一年没出活」「60+ 张表批量迁移」 |
| **Part C** 自定义图表开发 | HTML/CSS/JS 注入、payload_json 取数排障、固定卡片/overlay | 「自定义图表拿不到数据」「页面要做 overlay」 |
| **Part C-12** HTML 应用化看板 | descriptor patch 联 selector 到 custom chart dataView、视觉设计底线 | 「要更高级/应用化/不限标准看板」「太丑/AI 味重」 |
| **Part D** V7 发布流水线 | 草稿-发布状态机绕过、CSV 三态判断、Spark 中文别名、节点化静默坑 | `60004 此操作只能在草稿页面执行`、`PARSE_SYNTAX_ERROR` |
| **Part E** SuperApp 开发 | form 建表反向工程、LLM 中转 ILLEGAL_JSON_RES 三路径解析、原生 fetch 绕过 | 开放应用开发、脚手架未暴露的 API |
| **AI-native ADS** 方法论 | 治理 vs 重搭判断、7 字段约束、30+30+40 预算 | 「想给 BI 接 AI，先治理还是先重搭」 |
| **餐饮 BI 公式库** | AC/ADS/复购/RFM/新老客/用餐时段/DWD 宽表范式 | 餐饮连锁业务口径、39 个生产 ETL 沉淀 |
显著优点
- 实战实证：所有 API 路径、payload 字段、报错码均来自真实跑通的请求，非文档推测
- 分层治理：拒绝「跳过治理直接重建」，提供 8 维 ETL + 4 维字段判断框架
- 状态机绕过：V7 BI 草稿-发布分离机制的官方银弹（
guanvis publish）+ 手工 API 的完整避坑手册 - 反向工程：SuperApp form 建表、LLM 中转 bug 等脚手架未暴露能力的实测路径
- ExecPlan 工作法：30+ 表跨多日工程的标准化管理方法（来自 OpenAI Codex 规范）
潜在局限
- 环境绑定：针对观远 BI 私有实例（8.2.1+ / v7），公有云 SaaS 部分接口可能差异
- 版本敏感：官方全家桶迭代快（周更节奏），需持续对齐（本 skill 提供完整 SOP）
- 权限前置：写操作需
guancli auth login后的有效会话，无管理员级 bypass 方案 - 删除风险：ETL/数据集/页面删除有严格顺序约束（ds-first）和级联影响，需逐项确认
适合人群
- 观远 BI 高级用户（已熟悉官方全家桶基础命令）
- 数据工程师（需批量迁移/重构 10+ 张 ETL）
- 前端开发者（自定义图表 HTML/JS 注入、SuperApp 开放应用）
- BI 产品经理（治理决策、AI-native 数据架构提案）
- 餐饮连锁行业数据团队（复购/RFM/同店增长等业务口径）
常规风险
- 误删风险：未经逐项确认执行 DELETE → 下游看板/ETL 跑挂（B-7.0 安全闸强制拦截）
- 数据漂移：新旧链路并行期未对账 → 指标口径不一致
- 版本滞后：本地 guanskill 副本未更新 → 命令行为与文档不符（提供一键检查脚本）
- 权限失效：cookie/session 过期 → 写操作 401（需重登）
- 视觉验收缺口：管道通了但「AI 味」重 → 需配合 C-12 设计底线和
guanvis screenshot验收
与官方全家桶的关系
| 需求 | 路由到 | 何时回 majia-guanyuan |
|:---|:---|:---|
| 标准查数、ETL 读取 | `guancli` | 报错码不在官方文档、需治理判断 |
| 标准建卡、发布、截图 | `guanvis` | 自定义图表 dataView 联 selector、HTML 应用化 |
| 标准 ETL 新建/修改 | `guanetl` | `edit` 失效、整库治理、全链路重写 |
| 数据流/工作流 | `guanwf` | 复杂 DAG 重构、Python 节点 |
| 数据源/数据集 CRUD | `guands` | 字段审计、批量别名修改、跨目录迁移 |