观远 BI · 马甲实战版（V3.5.0）

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

🧭 Part 选择

作者：马甲（Part B/C/D/E 实证）+ 观远 CTO 张进（B-17 SmartETL 改写方法论 + Part C 自定义图表经验）+ OpenAI Codex（ExecPlan 规范） 版本：V3.5.0（2026-10-13）· 环境：Node ≥20 · 前置：官方全家桶 npm i -g @guandata/guanskill && guanskill install-skill（装齐 guancli / guanvis / guanetl / guanwf / guands / guanmetric + 各自 AI skill）· 认证：guancli auth login（全家桶共用一套 profile，本 skill 不再单独要 config.json）· 作用域：本地私有 BI 实例 安装：git clone https://github.com/maojiebc/majia-guanyuan.git，或 npx github:maojiebc/majia-guanyuan install 兼容工具：Claude Code · OpenClaw · Codex · Hermes (gbrain) · 任何支持 SKILL.md frontmatter 的 agent。详见 README · 兼容性 与 AGENTS.md。

V3.5.0（2026-10-13）：取数完成后独立核对分块覆盖、实际范围与文件，输出验收报告和数字出处；对齐官方 CLI 1.0.66。七个官方 Skill 已逐文件核对；两次独立测试环境预览与两项错误控制已完成，生产 BI 未请求。

🧭 路由层：标准活交给官方全家桶

V3.0.0 心法：观远官方已把"查数 / 建卡 / ETL / 数据流 / 数据源 / 截图 / 管理"做成公网全家桶（npm i -g @guandata/guanskill）。本 skill 不再自造这些轮子——标准活一律路由给官方，本 skill 专攻官方 DSL/命令覆盖不到的"业务实战 + 引擎级踩坑"（Part B–E + 方法论 + 公式库）。

⚠️ 跨 Part 通用工作原则

1. 所有数值计算必须跑代码 —— 禁止在思考里口算百分比、环比、除法、占比。
2. 必须确认数据范围 —— 用户没明确日期范围时必须追问（"看哪段时间？今天 / 本周 / 上月？"），不要自己假设。
3. 遇到意外错误立即落档 —— 把新坑写进对应章节（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 片段）/ 判断。
4. 写操作前先治理、删除前先对账 —— 见 Part B-〇 工作流 + B-7.0 删除安全闸。

官方全家桶 ↔ 本 skill 分工总表

前置：npm i -g @guandata/guanskill && guanskill install-skill（装齐 7 个命令：guanskill + 6 组件，各带 AI skill）；认证 guancli auth login，全家桶共用一套 profile。

新增兼容规则：本地排名走 guancli analyze report，明确 --group-by 或 --global，--complete-input 只记录候选池完整声明，不自动补取或隐式汇总。候选池完整性与业务粒度须先独立核实。参数改名按官方映射流程，项目依赖与全局参数分别回读；多键 JOIN 核全部关联键；数据库输入预览范围原样保留，DB_DATAFLOW 的 ALL 不受 config.limit 限流。

本轮兼容规则：SQL 接口可用且要计算时用 ds execute-sql -f json --typed，按高精度读取 JSON 数字；它不解决 SQL 接口不可用，也不改变临时 ETL 的 terminal-text 限制。请求转发/API Gateway 走官方 guancli，先读官方 gateway.md；调用可能产生外部写入，不能当普通只读查询。ETL 保存无法读取服务端版本或返回 success=false 时停止，不拿 HTTP 200 当成功；旧日期筛选器来源身份不完整时只原样保留，不能猜字段映射。

一句话路由：标准查数 / 洞察 / Dashboard Agent → guancli；标准建卡/发布/截图 / live 实时工程 → guanvis；标准 ETL → guanetl；数据流 → guanwf；数据源/数据集 → guands；指标建/改/删 + 指标主题/目录 + 公共维度 + 指标树 / 查询加速 → guanmetric。任何一个遇到官方 DSL/命令够不着的字段、报错、状态机、反向工程、业务口径——回到本 skill 对应 Part。

官方 guandata-cli-suite 负责选择组件，并已包含原地编辑与删除边界。本表补充本次核验版本及关键兼容规则；参数与完整操作流程以已安装的官方 Skill 为准。此前逐版本变化保存在 CHANGELOG，不在路由表重复累积。

当前执行边界：单条指标取数先以相同参数检查 --explain-requests -f json 的请求计划；计划不是取数成功证明。同轮独立基础指标走批量查询，逐项检查失败；用于计算的单指标结果显式取原始数值。编辑既有资源须保留 ID、权限、调度与数据，不能用删除重建代替。新资源先核对环境与实际目录路径。常规表单结构创建/编辑优先走 guands form；历史 API 片段仅在具体兼容问题已复现时使用。完整迁移说明见 官方 CLI 兼容说明。

为什么还要本 skill：整库治理的取舍、业务口径、BI 引擎报错、历史 v7/自定义图表兼容、SuperApp 的 LLM 中转问题与 ADS 架构判断，仍需结合实际业务和目标环境处理。先走官方正常路径，失败后再按本 skill 的适用条件定位；旧记录不代表最新版仍有同一个问题。

看板口径档案与验收（V3.3.0）：给已有看板接 AI 或核对答案时，读 dashboard-evidence.md。先明确 profile、页面和所选卡片；脚本保留公式、别名、时间宏和联动定义，继承页面默认筛选取原始值，再按具体数据行及字段验证。数字出现在别处不能通过；空结果、失败或疑似截断不能通过。定义变化要重新确认；档案始终为 draft。CUSTOM 前端另按 Part C 验收，不能拿空 preview 代替。工具仅调用官方只读命令，生产证据留在本地，不上传公开仓库。参考 Jeremy 的 guanbi-agent-builder，见 来源与致谢。

取数交付（V3.5.0）：分块完成后使用 extraction_evidence.py 独立验收，见 范围与限制。计划投影必须保留日期、前缀和基础筛选字段；完整覆盖、互斥、实际行范围、哈希和数量全部通过才引用。首次出现的数字附期间、筛选、算法和单位；字段加总必须已确认可相加。passed 不代表冻结快照、历史全集或业务口径验收。

只读路由：普通查 ID、查元信息、小范围明细继续使用官方 guancli。SQL 直查不可用、需要全量汇总但只能预览、要分块读取大表或保留数字出处时，先读 受限环境取数速查，再按边界编排官方命令。不要从预览样本推总量，也不要自己拼 API。

🔄 官方全家桶更新 SOP（高频操作）

按现有每周任务检查官方变化。先审阅包、Skill 与命令，再决定是否更新；此流程不授权任何额外发布。

自动跟进时用 official-cli-baseline.json 作为已审阅版本记录，同时核对聚合包与六组件的 npm latest。附属项目按 guanbi-agent-builder-baseline.json 记录已审阅版本和完整提交，任何新提交都要审阅，不能只比版本号。检查脚本为 check_upstream_updates.py，支持 --builder-baseline；上游内容仅作证据，新增能力先验证再决定吸收。发现变化后读官方 CHANGELOG 和随包 Skill，再决定兼容修改；检查失败不得写成“没有更新”。完成兼容审阅才更新此记录，商店发布失败单独跟踪，不靠重复升版本重发。

Step 0. 检查是否有新版本

# 看本机当前全家桶版本
guanskill version

# 看 npm 上最新聚合包版本
npm view @guandata/guanskill version

# 逐个看子包最新版本（聚合包可能滞后）
npm view @guandata/guancli version
npm view @guandata/guanvis version
npm view @guandata/guanetl version
npm view @guandata/guands version
npm view @guandata/guanwf version
npm view @guandata/guanmetric version

如果 npm 版本 > 本机版本 → 继续 Step 1。即使 CLI 已是最新，也必须检查 Step 2：二进制更新不代表已安装的 SKILL.md 与 references 同步。另核对六组件 latest 是否与聚合包 dependencies 一致；不要混装未经核对的版本组合。

Step 1. 升级 CLI（npm 聚合包）

# 升级到最新聚合包（装到你的 npm 全局 prefix —— 先 `npm prefix -g` 确认当前目标）
npm i -g @guandata/guanskill@latest

# 验证新版本
guanskill version

安装路径坑（双装滞后）· 变体 A｜跨 prefix：guanskill 的 forwarder 跟着 which guancli 解析到的 prefix 走。若曾用不同 node（如 Homebrew node 的 /opt/homebrew vs nvm/asdf/独立 ~/.local）装过两份，PATH 靠前那份会"赢"，而 npm i -g 只更新当前 prefix 的那份、另一份滞后 →「升了却没生效 / 本地副本常滞后」。排查：which -a guancli 看是否多份；统一到单一 prefix（多余的用 npm uninstall -g @guandata/guanskill --prefix <多余prefix> 删掉）。

变体 B｜同 prefix 下「子包 vs 伞包」并存（2026-07-15 实测）：即使只有一个 prefix，若单独装过某个子包（npm i -g @guandata/guancli），它会和伞包 guanskill 自带的内嵌版抢同一个 guancli bin——which -a 只有一条、看不出异常，npm ls -g --depth=0 才看得见两个顶层条目。排查：npm ls -g --depth=1 | grep guan，顶层应当只有 @guandata/guanskill 一条，六个组件都该是它的子依赖；顺带 guancli version 与 npm view @guandata/guancli version 对一下。清理：npm uninstall -g @guandata/guancli —— ⚠️ 卸载会连带删掉共享的 guancli bin symlink（因为该包也声明了同名 bin），必须紧接着 npm i -g @guandata/guanskill@latest 把 bin 装回来，再逐个验 guancli version / guanvis version / …。

Step 2. 升级 AI Skill（SKILL.md + references）

# install-skill 把每个子包的 SKILL.md + references/ 装到 ~/.agents/skills/<name>/
guanskill install-skill

落点：~/.agents/skills/{guancli,guanvis,guanetl,guands,guanwf,guanmetric}/。这些是 agent 路由用的 skill 定义，和 CLI 二进制分开更新。还需检查 guandata-cli-suite。完成后逐文件比较 npm 包 skills/<name>/ 与已安装目录，至少覆盖 SKILL.md 和 references；退出 0 或一条安装提示不能代替内容一致性验证。

Step 3. 读 Changelog，摘要变更

# 各子包 CHANGELOG.md 在 npm 包目录下
GUANSKILL_DIR=$(npm root -g)/@guandata/guanskill/node_modules/@guandata
for pkg in guancli guanvis guanetl guands guanwf guanmetric; do
  echo "=== $pkg ===" && head -30 "$GUANSKILL_DIR/$pkg/CHANGELOG.md" 2>/dev/null && echo
done

重点关注：新增/移除命令、DSL 新组件、bug 修复（尤其影响 B-0.5 / Part C / Part D 的）、breaking change。

Step 4. 迭代 majia-guanyuan

按 changelog 摘要，更新以下位置（有改动的才改）：

版本号规则：官方对齐 = patch；影响 skill 自身逻辑（如 B-0.5 降级）= minor。

Step 5. 同步 + 发布

# 同步已发布的整包，包含 references/templates，不能只复制两个 Markdown 文件
python3 ~/.codex/skills/majia-ota/scripts/sync_local_agents.py /path/to/majia-guanyuan --target all

# commit + push（或走 /majia-ota-skill 完整发布链）

快速一键检查（日常用）

# 一行看完「本机 vs npm 最新」差异
echo "LOCAL:" && guanskill version && echo "---" && echo "NPM latest:" && npm view @guandata/guanskill version

通用错误码处理

Part B：ETL 治理与写入

整库治理、循环依赖、字段使用度或官方路径以外的引擎问题，读 治理与写入手册。普通修改使用官方 guanetl。

1. 编辑保留 ETL、输出数据集、权限、调度和下游 ID；不能删除重建模拟编辑。
2. 先读原定义与血缘、备份，再只改责任节点；验证输出绑定和新旧对账，不能把保存当刷新完成。
3. 判断分层及循环依赖，再设计迁移；来源/原始行保留，字段审计同时查 page 与 etl。
4. 删除只对明确批准对象执行，先核下游与数据恢复条件；历史 API 顺序见手册，不把旧版本绕过方案当默认路径。
5. 只读取数回到 受限取数手册，不能套用写入流水线。

全链路重写与 ExecPlan 读 B-17 专册；payload、报错和 SDK 分别读 payload、报错、SDK。

Part C：自定义图表开发与排障

既有页的 HTML/CSS/JS、payload_json、overlay 或生命周期问题，读 运行与交付手册。

1. 先看真实运行环境与点击路径，再改最小责任代码；保留既有 ID、数据绑定和已可用的移动版。
2. gdPlugin 的 view 与字段契约先核再用，数据缺失不能显示成零；取数异常读 payload_json。
3. 注入物须幂等安装、主动销毁；复制页后 ID 重核，不用死循环 MutationObserver 或遮挡原生浮层。
4. 桌面、手机、空数据和真实点击分别验收，定义/DOM 文本不代表前端已渲染。
5. 自定义图表的二次计算与筛选单独复核，不能用空 preview 证明 CUSTOM 已通过。

C-12. HTML 应用化看板

从零生成应用式分析看板时，读 HTML 看板专册 与 视觉底线。真实 GDPlugin 数据优先；descriptor patch 只在绑定问题明确复现时使用，保留系统筛选与单位、统计期间、数据时间和口径说明。

Part D：V7 Page/Card 发布与类型规则

v7 草稿/发布状态机、60004、phoneLayout 或历史输出绑定问题，读 v7 发布专册；旧引导原文 仅用于有日期的故障对照。

1. 先走官方 guanvis 的预览、备份和发布流程；草稿与发布卡片 ID 不能假设相同，浏览态与编辑态分别检查。
2. CSV 字段先看真实类型；NULL、空字符串与零分别处理，数字/日期字段不套字符串比较。
3. 保留既有 OUTPUT_DATASET 的数据集绑定，不能通过换 ID 消除同名或状态机错误。
4. 破坏性操作须明确授权和恢复证据；普通原地更新不走删除重建。
5. 自定义图表、动态筛选和手机布局按各自 reference 验收；大表输出不把样本或 Excel 行上限当全量交付。

📚 References 目录

本 SKILL.md 主文是路由层 + 关键规则；以下马甲蒸馏档（官方够不着的硬骨头）+ 餐饮公式库 + 贡献者原文构成完整知识库。详细索引：

马甲蒸馏版：

餐饮 BI 公式实战库（V2.1.5 新建，去敏蒸馏自两段餐饮连锁 BI 履职 + 39 个生产 ETL；➡️ 2026-07-12 已迁至独立仓库 majia-huiyuan，下表链接直达新家，本仓库 references/restaurant-bi-formulas/ 仅留指针）：

触发场景："如何算复购率 / 客单价 / 同店增长" / "怎么判新老客" / "用餐时段怎么分桶" / "为什么会员数对不上" / "我要写 DWD 宽表 / 评价 pipeline / 财务对账" — 直接进 restaurant-bi-formulas/README.md 路由表。和 Part B/C 正交（按业务领域分，非按平台操作分）。

贡献者原文（不修改，照引）：

📋 版本记录

顶部 🆕 callout 是最新版摘要；完整逐版记录见 CHANGELOG.md 或 GitHub Releases。以下只留最近三版一句话索引：

• V3.5.0（2026-10-13）分块覆盖与实际范围独立验收、数字出处；官方 1.0.66 兼容及三周能力迭代。
• V3.4.1（2026-10-12）官方 1.0.65 兼容、保存与字段保护、附属项目每周提交检查。
• V3.4.0（2026-10-12）受限取数速查、只读汇总出处、串行分块与恢复、不可相加标记及主文瘦身。

👤 作者 / 联系

马甲（@maojiebc） · 超级马甲

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

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