@wubaoqi/guancopilot 0.0.0-stage → 0.2.0

package/skills-bundle/guanvis/references/checkout-editing.md

@@ -0,0 +1,53 @@
+# 编辑已有线上仪表板（checkout 工作流）
+
+SKILL.md 正文只保留 checkout 编辑的红线速记；本文件是 `checkout → 编辑 → diff → publish` 闭环的完整参考：生成物形态、attachCard 编辑模型、DSL 操作语义、覆盖发布与备份机制。
+
+## 1. Checkout 生成物形态
+
+`guanvis checkout <pgId> -d <dir>` 把线上 Page 拉成可编辑工程：
+
+- **schema.js**：best-effort 生成——数据集无权限/已删除/跨环境残留时只 warning 并继续生成可编辑工程；后续可手动 `guanvis init <dsId> -d <dir> --force` 补齐。
+- **普通 Card**：生成 `attachCard(cdId, ".guanvis/base/cards/<cdId>.json")`，接受线上 JSON 作为基线。
+- **自定义图表（SDK/ECHARTS_LITE）**：脚本/HTML/CSS 反编译到 `charts/<cdId>.js|.html|.css`；超长内联资源（GeoJSON、base64 图片）抽取到 `charts/<cdId>_assets/` + `__asset_text/__asset_base64` 占位符（逐字节往返验证，未编辑时 diff 恒为空）。card JS 用 `attachCard(...).loadContent("charts/<cdId>")` 引用，直接编辑内容文件即可改图表。
+- **复杂报表 Pro**：额外下载可编辑 xlsx 到 `templates/`，生成 `createComplexReportPro()` 父卡和嵌套的 attached data view，并使用下一模板版本；旧版复杂报表 checkout 直接拒绝。编辑闭环见 `complex-report-pro-patterns.md` §5。
+- **Page**：生成 `createPage(...).setBasePath(...).placeCard("cdId", ...)` 脚本，尽量反编译根布局里的 Tab/CardGroup/AreaTitle/SelGroup 和快捷筛选组，并保留 parentDirId。checkout 生成的 page 布局默认用 card/selector ID 字符串。
+- **适用范围**：checkout 工程只用于修改指定 Page，不用于复制新 Page；遇到嵌套布局组件等当前 DSL 不能安全表达的结构，checkout 会直接失败，不生成会清结构的工程。只支持普通仪表板（pgType=PAGE），自助取数/数据大屏/清单页等特殊页面会在 checkout 入口直接报错。
+- `checkout --overwrite` 会清理输出目录下所有根级 `.js` 和旧 `.guanvis`，避免 schema/selector/metrics/other.js 残留混入运行。
+
+## 2. 账号与语言要求
+
+checkout 读到的是"当前账号视角"的卡片定义，publish 会把它整体回写。必须用对页面涉及数据集拥有**完整列权限、无脱敏限制**的账号（推荐资源 owner 或管理员）执行 checkout/publish，否则读接口会按该账号权限裁剪 zone 字段/脱敏字段，回写后这些字段会从线上卡片中**永久丢失**。租户启用多语言时，操作账号语言应与卡片原始语言一致，避免把翻译后的字段显示名固化回卡片。
+
+## 3. attachCard 编辑模型与 DSL 操作语义
+
+`attachCard(cardId, jsonPath)` 是"base JSON + 链式 DSL 操作 = 目标 JSON"。它不会修改 base JSON，重复执行同一组 JS 操作应产出相同 payload。`attachCard` 只能引用 manifest 记录的原始 base-card，且 `cardId` 必须与该 JSON 的资源 ID 一致。
+
+- **通用操作**：已有卡片可继续串接常用 `createCard` 后续操作，包括标题/描述（`setName`/`setDescription`）、`setRawSettings`、图例/标签/坐标轴/表格/拆分等视觉设置。
+- **Zone 操作按链式顺序真实执行**：`addRow/addMetric/...` 追加字段；`insertMetric(index, field)` 插入；`removeMetric(selector)` 删除字段并保守清理其它 zone 中同字段引用；`moveMetric(selector, index)` 调整顺序；`updateMetric(selector, patch)` / `patchMetric(...)` 修改已有字段属性并保留未设置字段配置。`setRows/setMetrics/...` 和 `clearRows/clearMetrics/...` 是整 zone 重建，不会继承被替换字段的格式，并会在验证时提示 warning——默认优先用 `update*/patch*/add*/remove*/move*`。
+- **自定义图表内容编辑**：仅限 subType 为 **SDK / ECHARTS_LITE**。checkout 自动反编译出 `charts/<cdId>.js`（含内嵌资源抽取），card JS 里 `attachCard(...).loadContent("charts/<cdId>")`；也可用 `.setScript()/.setHtml()/.setCss()/.setLibs()/.addLib()` 内联修改。COMPLEX_REPORT（走 Pro 流程）、PLUGIN/PLUGIN_LITE（事实源是插件市场资源）、REPORT_FORM（填报模板配置）调用这些内容编辑 API 会直接报错，不要对它们生成此类修改；详见 `builder-reference.md` 自定义图表章节。
+- **已有 selector 配置**：仅能力矩阵中标记可编辑的类型可用 `.setSelectorSetting()` 修改配置；禁止原地改变 selector 类型或重新绑定字段。已有 `PARAMETER` selector 可用 `.bindParameter()` 原地更新参数绑定；已有 `TEXT_MATCH` selector 可更新文本操作符、筛选级别、默认文本、`canClear` 和列名显示；树状筛选器、层级树状筛选器和组合条件筛选器分别使用 `.setTreeSetting()`、`.setLayerTreeSetting()` 和 `.setCombinationSetting()` 修改专属配置。自定义等未提供专用 DSL 的类型只能保留已有专属配置。完整能力边界、配置结构和适用规则见 `selector-reference.md`。
+- **已有 selector 联动**：`cdType=SELECTOR` 的筛选器可用 `.addLink(cardIdOrIndex, targetFieldName?)` / `.removeLink(cardIdOrIndex)` / `.clearLinks()` 叠加修改现有 `settings.asFilter`。这些方法不支持 `TREE_SELECTOR`、`CUSTOM_SELECTOR` 等其他 selector 类型；不要把有顺序的联动增删混进 `.setSelectorSetting()`，也不要反向改 JSON。
+- **Page 快捷筛选区**：按有序操作执行——`setFilterLayout` 整体设置，`clearFilterLayout` 清空，`addFilterLayoutItem` 追加去重，`insert/remove/moveFilterSelector` 局部调整；筛选栏布局、名称/控件/按钮字体、控件风格、按钮色、背景色和背景图用 `setFilterPanelLayout()`。省略字段保留 base，显式 `null` 删除对应覆盖并恢复产品/主题默认。
+- **筛选器在筛选栏和画布间移动**：优先用动作级 API：`moveFilterSelectorToCanvas(selectorId, x, y, w, h)` / `moveCanvasSelectorToFilter(selectorId, index?)`；筛选器组用 `moveSelectorGroupToCanvas(group, x, y, w, h)` / `moveCanvasSelectorGroupToFilter(group, index?)`。
+- **新增卡片**必须使用 `createCard()` / `createSelector()` 等工厂函数（新建资源 ID 用 `guanvis genid` 生成）。
+- **影响面检查**：发布前用 `guanvis diff <dir>` 或 `preview` 输出里的 `changeSummary` 查看 base JSON 到最终 payload 的路径级影响面。
+- 没有 DSL 操作覆盖的需求，先扩展 DSL，不要改 `.guanvis` JSON。
+
+## 4. 编辑红线的完整依据（编辑 ≠ 删除重建）
+
+用户要求修改/改名已发布 Page 或 Card 时，必须保留原 pgId/cdId 原地覆盖发布，先按工程来源分流：
+
+- **本地有源工程**（该 Page 就是当前 guanvis 工程创建并发布的，`card_*.js` / `page.js` 还在，且线上没有在发布后被网页端改动过）：直接修改本地 JS 源文件（改名即改 `createCard(...)` / `createPage(...)` 标题）重新 publish 同 ID 覆盖。
+- **线上在发布后被网页端修改过、本地没有原始 JS 工程、或不确定线上是否已被改动**：用 `checkout` 拉取线上版本编辑——Page 改 checkout 生成的 `createPage(...)` 标题，已 checkout 的 Card 用 `attachCard(...).setName(...)`。**不得**把 `attachCard` 改写成 `createCard()`：那会绕过 base JSON，未被 DSL 表达的线上配置会在覆盖发布时丢失（`createCard()` 只用于新增卡片）。
+- **禁止**用"新建一个新 Page/Card + 删除或废弃旧的"来模拟编辑——资源 ID 变化会让收藏、分享链接、订阅推送、门户菜单引用和页面权限配置全部失效，这些状态 guanvis 无法迁移。
+- **全局参数同理**：只能 `parameter update <dpId>` 原地更新，禁止 delete 后重建同名参数（dpId 变化会让所有引用它的卡片/筛选器断链）；`parameter delete` 只用于用户明确要求删除参数本身。
+- **描述修复**：仅修复已发布 Card/Page 的描述时保留原资源 ID，用 `guanvis card/page set-description` 更新线上描述；本地有对应 JS 工程时同步更新 `.setDescription(...)`。
+- **只改 Page 名称或所在目录时不必走 checkout**：`guanvis page rename <pgId> --name` 和 `guanvis page move <pgId> --parent-dir <dirId>` 直接原地改，保留 pgId 且不动页面内容；目标目录不存在时先 `guanvis dir create`。需要连内容一起改才按上面的分流走 checkout。删除页面本身用 `guanvis page delete <pgId> --yes`（页面上还有卡片时再加 `--force`，`--force` 是"连卡片一起删"的开关、不是二级确认，单给 `--force` 仍会被 `--yes` 拦住）。页面删除是软删，页面连同卡片与权限进回收站，但**CLI 没有恢复命令**，要找回只能人工登录 BI 网页端在回收站里还原；页面目录的删除（`guanvis dir delete`）则是物理删，不进回收站、无从恢复。
+
+## 5. 发布：覆盖确认、备份与"另存新版本"
+
+checkout 工程发布的是对 checkout 指定 Page 的**覆盖式修改**，不承担"复制新版本"职责。
+
+- **覆盖确认（Agent 红线）**：对 checkout 工程同 ID 发布时，CLI 检测到同 ID Page 必须显式加 `--allow-overwrite` 才会覆盖。**Agent 禁止在未确认的情况下自行加 `--allow-overwrite`**：CLI 提示将覆盖线上 Page 时，必须先停止发布，向用户说明将覆盖的 Page ID、名称和覆盖后可能替换原页面布局，等用户明确确认"覆盖"后才可以重跑并加该参数。发布前可用 `--dry-run` 查看会覆盖哪些线上 Page。Card/Selector ID 不做在线覆盖检查。
+- **覆盖备份机制**：使用 `--allow-overwrite` 时，CLI 会先为冲突 Page 发起资源包导出备份并等待导出成功；备份包含 Page 及其组成资源，但不会沿血缘额外导出数据集、数据账户等上游资源（避免普通用户因缺少上游资源所有者权限而无法备份）。备份未成功则中止覆盖。CLI 只记录备份导出记录和 packageId，不自动下载资源包；需要回滚时，到 BI 资源迁移导出记录中手动下载该资源包后再导入覆盖回去。
+- **保留原页面、出一个新版本**：不要把 checkout JSON 复制后改 ID 做"新版本"，也不要在 guanvis CLI 里手写复杂 ID map 或用浏览器手工复制页面。用 `guanvis page save-as <pgId> --suffix _guanvis`（或 `--name <新名>`，可加 `--parent-dir <dirId>`）做 BI 原生整页另存为：服务端事务复制全部卡片并重映射联动/下钻/父子/指标关系等 ID，命令自动 release 发布副本（7.2.0 之前无草稿态会自动跳过），然后基于副本页面 checkout/edit。命令会回读副本核对卡片数（无指标平台 license 时指标卡会被服务端过滤）并扫描是否残留源页卡片 ID 引用，出现 ⚠ 警告时先排查再继续。

package/skills-bundle/guanvis/references/complex-report-pro-patterns.md

@@ -0,0 +1,398 @@
+# 复杂报表 Pro 配方与排错（AI 优先阅读）
+
+本文件是复杂报表 Pro 的"使用手册"：结构模式配方、校验红线和报错修复。API 权威定义见 `builder-reference.md` 的 ComplexReportProBuilder 章节；本文不重复 API 表，只回答"这个需求怎么写、报这个错怎么改"。
+
+## 0. 选型：什么时候用 Pro
+
+**先过门槛，再看形态。** 复杂报表 Pro 不是观远 BI 的默认功能（`COMPLEX_REPORT_PRO` 需要单独开通授权，导入未授权环境会被拒：`请先联系管理员开通COMPLEX_REPORT_PRO权限`）。只有满足以下任一条件才允许选 Pro：
+
+1. 用户**明确说了**"复杂报表"或"复杂报表 Pro"（含"创建复杂报表""做一张复杂报表 Pro"等点名表述）；
+2. **修改场景**：checkout 下来的目标卡片本身已经是 Pro（保持原类型，不要改成普通卡片）。
+
+用户只说"做个表格/报表/明细表/透视表/仪表板"时**一律用原生卡片**（`DATA_GRID`/`SCROLL_TABLE`/`PIVOT_TABLE` 等）。如果需求形态确实是原生卡片表达不了的（多级小计版式、票据套打、段落块），先用原生卡片尽量逼近，并在结果说明中**告知用户**"该版式用复杂报表 Pro 可以完整实现，但 Pro 需要单独授权，如需请明确说明"——由用户决定，不要自作主张升级。
+
+确认走 Pro 之后，按形态选结构：
+
+| 需求形态 | 用什么 |
+|---|---|
+| 平面明细列表、可交互排序/滚动 | 普通卡片 `DATA_GRID` / `SCROLL_TABLE`（即使已授权 Pro 也不要用 Pro） |
+| 行列交叉 + 自动小计，无格子级版式要求 | 普通卡片 `PIVOT_TABLE`（同上） |
+| 多级分组展开、显式小计/合计行、格子级样式版式（中国式报表） | Pro |
+| 横纵双向交叉且要控制每个格子 | Pro |
+| 每条记录一个多行卡片块（段落明细/档案/票据） | Pro（`beginBlock`） |
+| 固定 Excel 版式套数据（发票/单据） | Pro（外部 xlsx `.setTemplate()`） |
+| 多数据集 JOIN 后出一张表 | Pro（`setDataSourceRelations`）；也可先 ETL 合表再用普通卡片 |
+| 按组分页浏览/导出 | Pro（`setPagination` + `countPerPage`） |
+
+从零创建优先 **Workbook DSL**（`.setWorkbook()`，可文本审阅、pack 全量校验）；只有拿到现成 xlsx 模板文件时才用 `.setTemplate()`。
+
+只支持 `COMPLEX_REPORT_PRO`：旧版复杂报表（COMPLEX_REPORT）不支持创建或编辑，一律拒绝并建议外部迁移后新建 Pro；Pro 父卡也不能用泛化 `attachCard()` 修改——checkout 会生成 `createComplexReportPro()` 工程，编辑走 §5。
+
+## 1. 模板心智模型（读懂再写）
+
+Pro 模板 = Excel 网格上放"模板格"。每个模板格要么绑定数据（`bindDimension/bindMetric/...`），要么是随分组重复的标签（`setContextText`），要么是随扩展复制的公式（`setDynamicFormula`）。**父格（`context`）决定重复结构**：
+
+- 纵向维度格是"锚点"：每个取值向下复制一行（或一块）。
+- 子格挂 `context: 锚点`，表示"在锚点的每个分组内展开/计算"。
+- GcExcel 按父格树把模板行展开成最终表格；小计/总计是挂在标签格上的聚合。
+
+**父格位置规则**（pack 本地强校验，dev29 实证语义）：
+
+| 关系 | 要求 |
+|---|---|
+| 左父格（纵向扩展维度） | 位于子格**左上方位**即可：同行左、同列上、左上区域都合法（覆盖组标题独占一行的"阶梯布局"） |
+| 上父格（横向扩展维度） | 必须**同列上方**（交叉表专用） |
+| 双父格 | `context: "A4*B3"`，左父格+上父格各最多一个 |
+| `setContextText` 标签的父格 | 必须是**维度绑定**，位于左上方位 |
+| `bindSubtotal` 的父格 | 必须是**同行左侧的 `setContextText` 标签** |
+| 小计行公式聚合（`setDynamicFormula` 挂标签） | 标签必须**同行左侧** |
+| `bindGrandTotal` | **禁止**传 `context`（自动 `E=N,C=None`） |
+
+**同一数据视图内只写 `context`，绝不写 `filterBy`**（同源 filterBy 会编译成嵌套 `LP(...)`，后端 500；pack 已本地拒绝）。`filterBy` 仅用于跨数据视图父格映射，且 cell 必须同时出现在 `context` 中。
+
+**`filterBy` 与横向扩展同在一个 Sheet 时按格三条规则**（pack 已本地拒绝，报错前缀 `cross-view filterBy on a sheet with a horizontal expansion`）。原因：Sheet 上只要有一个 `filterBy`，Pro 后端就把整张 Sheet 切成"两遍渲染"——第一遍只做纵向扩展（横向扩展格先占位、带 filterBy 的格改成 lookup 且只保留左父格），第二遍才还原横向扩展并给 lookup 格补上父格；lookup 按列取值的键来自 `filterBy`，不来自 `context`。这些错误后端都不报，只出错数，所以本地必须硬拒绝：
+
+1. 带 `filterBy` 的格若 `context` 里有横向父格，`filterBy` 必须同时包含该横向父格（只给纵向键 → 每列重复同一个值）。
+2. 同一 Sheet 上，凡 `context`（含默认推断）挂在横向父格下、自身不是 `expansion: "horizontal"`、又没有 `filterBy` 的绑定或动态公式，一律拒绝（第一遍就被消费，不随列扩展，输出一个总量）。要么给它补含横向父格的 `filterBy`，要么整表改 §2.8 JOIN 虚拟视图 + 只写 `context`。
+3. `filterBy` 不能写在横向扩展格自身上（lookup 改写会丢掉它的 E=H），横向列头单独放一格，过滤放在值格。
+4. 第 1 行和 A 列都必须有格（值、模板或带样式的格），让工作表已用区域从 A1 开始：渲染器还原横向表头时按已用区域相对坐标定位，模板从 B 列或第 2 行起步时表头整体错位一格、占位符残留、查值全空。把标题放在 A1 即可；A 列纯留白时放一个空格值。
+
+满足规则的形态实测按列正确：三视图交叉表（行轴视图 / 列轴视图 / 度量视图）度量格 `context: "A3*B2"` + `filterBy: [{行键, A3}, {列键, B2}]`；两级列头（国家→是否已付）时 `filterBy` 可以额外带 `context` 祖先格 `B2`（`context` 每个方向只写最近父格，`filterBy` 允许写祖先），合并列头与空值列都正确。与 §2.8 JOIN 形态的取舍：filterBy 形态行/列成员各来自自己的视图、无交点为空，JOIN 形态是 INNER JOIN、关联不到的成员直接消失。
+
+**多段带的顶层锚点写 `context: "None"`**：同一列里第二段带的顶层维度（如第 7 行的 `A7`）会被默认父格推断挂到上一段的同列维度（`guanvis report inspect` 显示 `A3 (inherited)`），第二段就嵌进第一段的分组里；显式 `None` 才是独立的一段。
+
+## 2. 结构模式配方
+
+每个配方给最小正确形态；完整可运行工程见 `evals/complex_report_pro/`（最小 Workbook DSL 工程）。
+
+### 2.0 最小工程骨架（从零创建）
+
+```bash
+guanvis init <dsId> -d ./pro_report/                    # 单数据集
+guanvis init <ds1> <ds2> -d ./x/ --alias ORDERS,SALES   # 多数据集必须用 --alias 命名全局变量
+cd ./pro_report && guanvis genid 3                      # 父卡 + 每个数据视图 + page 各一个 ID
+```
+
+多数据集时**不要**手写 `var X = defineDataset(...)`（schema.js 的顶层 var 不会进入其他脚本的作用域），一律用 `--alias`；单数据集裸引用可用 `f("字段")`，多数据集用 `field(SALES, "字段")` 指明归属（`f()` 永远取第一个数据集）。
+
+`card_01_xxx.js` 三段式：数据视图 + workbook + 注册（下例为分组小计形态，其他结构套本节配方）：
+
+```javascript
+var orders = createCard(ChartType.DATA_GRID, "orders")   // 数据视图：模板引用的字段都必须进 row/metric
+    .setId("<genid>")
+    .bindDataset(DS)
+    .addRow(f("区域"))
+    .addMetric(f("金额", { aggrType: AggrType.SUM }));
+
+var workbook = createReportWorkbook().addSheet("月报", function (sheet) {
+    sheet.merge("A1:B1")
+        .setValue("A1", "销售月报", { fontSize: 16, bold: true, horizontalAlignment: "center", verticalAlignment: "center" })
+        .setRowHeight(1, 34)
+        .setValue("A2", "区域", { bold: true }).setValue("B2", "金额", { bold: true })
+        .bindDimension("A3", reportField("orders", "区域"))
+        .bindMetric("B3", reportField("orders", "金额"), { aggregate: "SUM", context: "A3", numberFormat: "#,##0.00" })
+        .setContextText("A4", "小计", { context: "A3" })
+        .bindSubtotal("B4", reportField("orders", "金额"), { aggregate: "SUM", context: "A4" })
+        .bindGrandTotal("B5", reportField("orders", "金额"), { aggregate: "SUM" });
+});
+
+registerComplexReportPro(createComplexReportPro("销售月报")
+    .setId("<genid>")
+    .setWorkbook(workbook)
+    .addDataView("orders", orders)
+    .setColumnWidthStretch(true)
+    .build());
+```
+
+`page.js` 正常 `registerPage`（Pro 卡按注册顺序参与 card index，或用 ID 字符串）；**Pro 卡必须与引用它的 Page 同包 pack/publish**。之后与普通流程一致：`preview` → `pack`/`publish`。
+
+### 2.1 层级分组（区域→客户 两级）
+
+```javascript
+sheet.bindDimension("A2", reportField("v", "区域"))                        // 顶层锚点，无 context
+    .bindDimension("B2", reportField("v", "客户"), { context: "A2" })     // 嵌套维度
+    .bindMetric("C2", reportField("v", "金额"), { aggregate: "SUM", context: "B2" });
+```
+
+维度默认纵向扩展 + 相邻同值合并（`group` 缺省即 merge）；行级不去重列表用 `group: "list"`。排序 `sort: "asc" | "desc"`。
+
+### 2.2 横纵交叉（行=城市，列=类别）
+
+```javascript
+sheet.bindDimension("A4", reportField("v", "城市"))                                  // 纵向
+    .bindDimension("B3", reportField("v", "类别"), { expansion: "horizontal" })      // 横向
+    .bindMetric("B4", reportField("v", "金额"), { aggregate: "SUM", context: "A4*B3" });
+```
+
+### 2.3 分组小计 + 全表总计（三件套）
+
+```javascript
+sheet.bindDimension("A2", reportField("v", "区域"))
+    .bindMetric("C2", reportField("v", "金额"), { aggregate: "SUM", context: "A2" })
+    .setContextText("A3", "小计", { context: "A2" })                                  // ① 标签挂维度
+    .bindSubtotal("C3", reportField("v", "金额"), { aggregate: "SUM", context: "A3" }) // ② 值挂标签（同行左）
+    .bindGrandTotal("C4", reportField("v", "金额"), { aggregate: "SUM" });             // ③ 总计不带 context
+```
+
+不要把老复杂报表的 `G_SUBTOTAL/G_GRANDTOTAL` 写进 Pro 模板。多级分组下给**内层维度**做小计时，标签列必须 ≤ 该维度所在列（如三级分组 B 地区/C 省份/D 城市，省份小计标签放 `C4` 挂 `C3`，不能放 A4——校验报 `must be in its column or to the left`）；标签行可 `merge("C4:D4")` 横跨到城市列补齐版式。
+
+### 2.4 小计行公式聚合（对公式列/数据列求和均可）
+
+小计行需要聚合"动态公式列"（如费率）或再聚合数据列时，`setDynamicFormula` 挂小计标签，GcExcel 会把引用改写成整组区域（`SUM(D2)` → `SUM(D2,D4,...)` 或 `SUM(C3:C103)`）：
+
+```javascript
+sheet.setDynamicFormula("E2", "IFERROR(D2/C2,0)", { context: "B2" })     // 明细行公式列
+    .setContextText("B3", "城市小计", { context: "B2" })
+    .setDynamicFormula("D3", "SUM(D2)", { context: "B3" })               // 小计行聚合数据列
+    .setDynamicFormula("E3", "AVERAGE(E2)", { context: "B3" });          // 小计行聚合公式列
+```
+
+小计公式格的数字格式来自它**自己的 style**，不继承明细列。
+
+### 2.5 阶梯分组（组标题独占一行）
+
+```javascript
+sheet.bindDimension("A2", reportField("v", "国家"))                        // 组标题行锚点
+    .bindDimension("B3", reportField("v", "城市"), { context: "A2" })     // 明细行跨行挂锚点
+    .bindMetric("C3", reportField("v", "金额"), { aggregate: "SUM", context: "B3" })
+    .setContextText("B4", "小计", { context: "A2" })                      // 小计标签也跨行挂锚点
+    .setDynamicFormula("C4", "SUM(C3)", { context: "B4" });
+```
+
+### 2.6 段落明细块（每条记录一个多行块）
+
+```javascript
+sheet.beginBlock("A2", reportField("orders", "订单ID"))     // 锚点=块左上角，通常是记录 ID（METRIC 可作锚点）
+    .text("B2", "货主名称")
+    .dimension("C2", reportField("orders", "货主名称"))
+    .text("B3", "运货费")
+    .metric("D3", reportField("orders", "运货费"), { aggregate: "SUM", numberFormat: "#,##0.00" })
+    .spacer("A4")                                            // 块间留白行
+    .end();
+```
+
+块内禁小计/总计；其他模板格不得落入块矩形；**锚点格自动成为维度绑定，不要再对锚点格写 `.text()`/`.dimension()`**（报 `contains multiple template operations`）——锚点直接显示维度值，标签放旁边格。
+
+### 2.7 分页（按顶层分组分页）
+
+```javascript
+sheet.bindDimension("A3", reportField("v", "客户"), { countPerPage: 20 });  // 唯一 countPerPage，顶层无 context
+report.setPagination(true);
+```
+
+约束：单 Sheet；全模板禁 `filter/filterBy`；`countPerPage` 只能放在无 `context` 的顶层维度（嵌套子维度会截断祖先合并格，pack 拒绝）。
+
+### 2.8 多数据源 JOIN（虚拟视图）
+
+```javascript
+report.setDataSourceRelations([{
+    tableName: "产品供应商",                                   // 模板里用 产品供应商.字段 引用
+    relations: [
+        { leftId: "products", rightId: "suppliers",
+          leftColumnKey: "供应商ID", rightColumnKey: "供应商ID", joinType: "INNER" }
+    ],
+    selectedCols: [
+        { viewId: "suppliers", key: "公司名称", name: "" },
+        { viewId: "products", key: "订购量", name: "" }
+    ]
+}]);
+```
+
+`leftId/rightId/viewId` 写数据视图别名，字段写显示名，pack 自动翻译成子卡 ID/zone key；同组 relations 必须连成连通图。JOIN 键是 METRIC 型 ID 时在子视图用 `AggrType.MAX` 带出。模板只能引用该组 `selectedCols` 输出的字段；`name` 非空即输出列别名（不同视图的同名字段用 `订单_雇员ID` 这类别名区分，模板按别名引用）。虚拟视图是行级明细：只有度量的视图要在 `addRow` 里放关联键（METRIC 键先加 STRING 计算字段），否则 DATA_GRID 聚成一行、JOIN 只剩一条。"行轴、列轴、度量来自不同数据视图的交叉表"有两种形态：度量格 `filterBy` 同时带行键和列键（§1 三条规则，行/列成员各来自自己的视图、无交点为空），或本节 JOIN 虚拟视图；当 Sheet 上还有其它挂在横向父格下、无法加 `filterBy` 的格（例如列头下方按列的计数行、动态公式）时只能走 JOIN。JOIN 的代价是 INNER JOIN 关联不到的成员不出现、空交点为空白、展开顺序以关联结果为准。
+
+### 2.9 条件格式 / 冻结 / 图片
+
+```javascript
+sheet.setFreeze(1, 0)                                                       // 冻结首行
+    .setConditionalFormat("C2:C10000", [                                    // 区域写大，GcExcel 自动裁剪到数据区
+        { op: ">", value: "1000", backgroundColor: "#FFC7CE", fontColor: "#9C0006" },
+        { formula: "MOD(ROW(),2)=0", backgroundColor: "#EAF3FB" }           // 斑马纹
+    ])
+    .bindImage("D2", reportField("v", "图片URL"), { context: "A2" });
+```
+
+条件格式 op 限 `> < >= <= == !=`，颜色必须 `#RRGGBB`；`value` 是公式片段——数字直接写，文本常量带引号（`value: "\"缺货\""`）；多规则可用 `stopIfTrue: true` 命中即停。超链接按位置选形态：**静态格**（标题/说明/返回目录）用 `setHyperlink(cell, url, { tooltip? })`，GcExcel 渲染保留；**扩展区行级链接**必须用 `HYPERLINK()` 动态公式（worksheet 超链条目按固定 ref 定位，不随模板行复制——给扩展区格挂 setHyperlink 只有第一行有链接）。图片导出上限 1000 格，配合 `.setColumnWidthStretch(true)` 控制版式。
+
+### 2.9b 打印版式 / 静态资产 / 序号列
+
+```javascript
+sheet.setImage("A1", "assets/logo.png")                        // 本地 logo/印章嵌入（png/jpg/gif，工程内路径）
+    .setValue("A2", "序号", { diagonalDown: true })            // 斜线表头
+    .setPrintTitleRows(2)                                      // 打印/导出每页重复表头行
+    .setHeaderFooter({ footer: "&C第 &P 页 / 共 &N 页" })      // 页脚页码
+    .setDynamicFormula("A3", "ROW()-2", { context: "B3" })     // 序号列（父格是同行右侧维度）
+    .bindDimension("B3", reportField("v", "城市"), { context: "None" });
+```
+
+序号列是唯一允许"动态公式挂同行**右侧**父格"的形态；注意此时右侧维度要显式 `context: "None"`（或其真实父格），避免它按默认推断反挂序号格形成环。
+
+### 2.9c 排序 / 行级链接 / 涨跌着色（dev29 实证）
+
+```javascript
+// "按销售额降序展示城市"：排序放数据视图，模板展开顺序跟随数据视图返回顺序
+var v = createCard(ChartType.DATA_GRID, "orders")
+    .bindDataset(DS)
+    .addRow(f("货主城市"))
+    .addMetric(f("应付金额", { aggrType: AggrType.SUM }))
+    .addSort(f("应付金额", { aggrType: AggrType.SUM, sortType: SortOrder.DESC }));
+
+// 行级可点击链接：HYPERLINK 动态公式随扩展逐行复制（模板格超链接不会复制，别用）
+sheet.setDynamicFormula("C2", 'HYPERLINK("https://bi.example.com/detail","查看")', { context: "A2" })
+// 涨跌着色（正红↑负绿↓）：条件数字格式即可，无需 setConditionalFormat
+    .bindMetric("D2", reportField("orders", "环比"), {
+        aggregate: "SUM", context: "A2",
+        numberFormat: '[Red]#,##0.00"↑";[Green]#,##0.00"↓";0.00'
+    });
+```
+
+- 排序只能放数据视图（`addSort`），模板 props 里没有排序语法；聚合值排序用与 metric 相同的 `aggrType` + `sortType`。
+- `HYPERLINK("url","文本")` 里的 URL 含点号不会被误判为数据字段（校验器已处理字符串字面量）；URL 可用 `CONCATENATE("https://.../", B3)` 拼单元格值。
+- `.setLimit(n)` 不影响 Pro 导出行数（复验），"前 N 名"需求用数据过滤或让用户在 BI 端配置，不要用 setLimit。
+
+### 2.10 计算放哪层：BI 优先，GcExcel 只做排版级（dev29 实证）
+
+优先级从高到低，能用上层就不要下沉：
+
+| 计算类型 | 放哪 | 写法 |
+|---|---|---|
+| 行级公式（`[利润]/[销售额]`、CASE WHEN、日期函数） | 数据集普通计算字段 | `guands dataset calc-field add <dsId> --name .. --formula ..`，然后 `guanvis init --force` 刷新 schema 直接 `f("字段")` 引用 |
+| 比率/均值/占比等**非可加**指标（`SUM(a)/COUNT(b)`） | 数据集聚合计算字段 | `--calc-type aggregation`；卡片/子视图直接 `f("字段")`（不写 aggrType），BI 按当前维度组自动重算 |
+| 可加指标的小计/总计（SUM/COUNT/MAX...） | Pro 模板 | `bindSubtotal`/`bindGrandTotal` 三件套（§2.3） |
+| **非可加**指标的小计/总计 | 每个展示粒度一个数据视图 | 明细=细粒度视图；小计=组粒度视图 + `context: 组维度格` + `filterBy: [{field, cell: 组维度格}]`；总计=无维度视图 + `context: "None", expansion: "none"` |
+| 排版级算术（序号 `ROW()-n`、单格单位换算、`HYPERLINK` 拼链接） | GcExcel 动态公式 | `setDynamicFormula`，仅当 BI 查询无法逐格表达时使用 |
+
+三个实证反模式（实验踩过，数值都是错的）：
+
+- **对聚合计算字段用 `bindSubtotal`/`bindGrandTotal`**：GcExcel 把各明细行的比率求和（各城市单均之和 26661 vs 正确组内重算 62.42）。非可加指标的小计必须走"组粒度视图"。
+- **模板 `aggregate: "COUNT"` 当计数用**：模板聚合作用在**视图返回行**上（明细行恒为 1，小计=组内行数），不是订单数。计数放子视图 zone（`f("订单ID", { aggrType: AggrType.COUNT })`），模板格用 `aggregate: "SUM"` 透传。
+- **派生视图（组粒度/无维度）漏掉基视图的过滤**：明细视图有 `.addFilter(...)` 时，小计/总计视图必须加**同样的过滤**，否则同一行里比率与可加列口径不一致（dev29 实测：总计占比无过滤 1.0575 vs 同行过滤后口径 1.1202）。selector childFilters 会同时作用于全部子视图，无此问题；只有写死的 addFilter 需要手动复制。
+
+### 2.11 固定科目表 / 分列常量对比（利润表、资产负债表式）
+
+```javascript
+// 每个对比列一个数据视图（addFilter 常量过滤），科目行全是固定行
+var all   = createCard(ChartType.DATA_GRID, "all").bindDataset(DS)
+    .addMetric(f("应付金额", { aggrType: AggrType.SUM }));
+var north = createCard(ChartType.DATA_GRID, "north").bindDataset(DS)
+    .addMetric(f("应付金额", { aggrType: AggrType.SUM }))
+    .addFilter(filterField(DS, "货主地区", FilterType.EQ, ["华北"]));
+
+var money = { aggregate: "SUM", context: "None", expansion: "none", numberFormat: "#,##0.00" };
+sheet.setValue("A3", "一、营业收入", { bold: true })
+    .bindMetric("B3", reportField("all", "应付金额"), money)      // 全国列
+    .bindMetric("C3", reportField("north", "应付金额"), money)    // 华北列
+    .setValue("A5", "二、运营净额", { bold: true })
+    .setDynamicFormula("B5", "B3-B4", {}, { numberFormat: "#,##0.00" })   // 派生科目行
+    .setDynamicFormula("B6", "IF(B3=0,0,B4/B3)", {}, { numberFormat: "0.00%" });  // 比率行
+```
+
+要点（dev29 实证）：
+- **绑定级 `filter` option 不是常量过滤**——它是 checkout 保真通道（`F=view.field*Cell` 跨视图映射语法）。写 `filter: "字段=值"` 能过 pack，但后端导出直接 500（SearchEngine NPE）。分列对比一律"每列一个数据视图 + addFilter"。
+- 固定单元格全用 `context: "None", expansion: "none"` 的 `bindMetric`；派生科目（净额/比率）用引用固定格的动态公式。
+- 月份/季度桶**不要用 `granularity` 日期粒度**（zone 会生成后端查不到的 SUB_DATE 虚字段"月"，pack 现已本地拒绝）——先加 `DATE_FORMAT([日期], 'yyyy-MM')` 计算字段再绑定，横向展开月份列 + `.addSort` 升序。
+
+### 2.12 筛选器联动 Pro
+
+```javascript
+var sel = createSelector("产品筛选")
+    .setId("...")
+    .bindField(f("产品名称"))
+    .linkTo(0, "产品名称");    // 可联动目标序列包含 Pro 子视图（按 addDataView 顺序）
+registerSelector(sel.build());
+```
+
+运行时走 childFilters，小计/总计随筛选重算。发布后可用 `guancli card preview <proId> --filter "字段 EQ 值"` 无头验证。
+
+## 3. 数据视图规则
+
+- 每个 `addDataView(alias, cardBuilder)` 是一个 `DATA_GRID` 子卡：维度进 `addRow`，聚合值进 `addMetric`。
+- **模板引用的每个字段都必须出现在对应子视图的查询区**（row/metric），否则 pack 拒绝。
+- `bindDimension` 的字段必须是 DIM；数值列（METRIC）不能做维度绑定——需要按数值分组时先在数据集加计算字段转 STRING。
+- 子视图 `.setLimit(n)` **不会**限制 Pro 导出行数，别用它裁数据。
+- 聚合计算字段（schema 里 `calculationType: "aggregation"`）进 `addMetric` 时**不要**写 `aggrType`，BI 按视图维度自动聚合；配套的分层用法见 §2.10。
+- **日期字段不要带 `granularity` 进 Pro 数据视图**（后端查不到派生的 SUB_DATE 字段，pack 已本地拒绝）——月/季分桶用 `DATE_FORMAT` 计算字段。
+- 样式规范：主标题行高 32–36pt、表头 22–26pt、明细 18–22pt，标题 `verticalAlignment: "center"`；宽表/图片表优先 `.setColumnWidthStretch(true)`。
+
+## 4. 校验报错 → 修复
+
+pack/publish 阶段（本地校验，改 DSL 即可）：
+
+| 报错关键词 | 原因 | 修复 |
+|---|---|---|
+| `context parent ... must be in its column or to the left` | 父格在子格右侧 | 纵向父格允许**任意行**（其列或左侧）——"汇总在上"（总计/小计在明细上方、标签挂下方维度）已实证合法；同行右侧仅序号列动态公式形态放行 |
+| `must be a vertical parent in the upper-left area or a horizontal parent above in the same column` | 上父格不是横向维度，或横向父格不在同列上方 | 交叉表列头加 `expansion: "horizontal"` 且放子格正上方；层级分组只用左父格 |
+| `subtotal parent ... must be a setContextText cell` / `must be on the same row to the left` | `bindSubtotal` 没挂同行左侧标签 | 按 §2.3 三件套补 `setContextText`，值与标签同行 |
+| `redundantly filters the same view ... use context only` | 同数据视图写了 `filterBy` | 删掉 filterBy，同源层级/交叉只写 `context` |
+| `filter and filterBy cannot be combined` | 两者并用 | 只留一个 |
+| `cross-view filterBy on a sheet with a horizontal expansion: filterBy on cell X must include its horizontal parent Y` | 带 `filterBy` 的格挂在横向父格下，但 `filterBy` 只给了纵向键 | 在 `filterBy` 里补 `{ field: 列键字段, cell: Y }`（§1 规则 1） |
+| `cross-view filterBy on a sheet with a horizontal expansion: cell X (...) hangs off horizontal parent Y without a filterBy` | Sheet 上有 `filterBy`，而 X 只用 `context`（或默认推断）挂在横向父格下 | 给 X 补含 Y 的 `filterBy`；无法补（同视图计数行、动态公式）时整表改 §2.8 JOIN 虚拟视图 + 只写 `context` |
+| `cross-view filterBy on a sheet with a horizontal expansion: filterBy on cell X cannot be combined with expansion "horizontal" on the same cell` | 把 `filterBy` 写在了横向扩展的列头格上 | 列头格只保留 `expansion: "horizontal"`，过滤放到值格 |
+| `cross-view filterBy on a sheet with a horizontal expansion: row 1 and column A must both hold a cell` | 模板从 B 列或第 2 行起步，已用区域不从 A1 开始 | 标题放 A1，或 `setValue("A1", " ")` 放一个空格值（§1 规则 4） |
+| `filterBy[i] cell X must also be listed in context (or be a context ancestor of a listed parent)` | `filterBy` 引用的格既不是 `context` 父格，也不是父格的 `context` 祖先 | 多级表头按祖先链写（`context: "A4*B2"` 可带 `B2` 的父格 `B1`），其它格不能当过滤键 |
+| `unknown option "context"`（出现在 bindGrandTotal 上） | `bindGrandTotal` 传了 context | 删 context；总计只支持 `aggregate/numberFormat/style` |
+| `unsupported aggregate "COUNTA"; supported aggregates: ...` | 聚合不在白名单 | 换 `SUM/COUNT/AVERAGE/MAX/MIN/PRODUCT/STDDEV/STDDEVP/VAR/VARP`；`AVG` 会自动规范化为 `AVERAGE` |
+| `pagination requires exactly one worksheet` / `countPerPage ... must use a top-level dimension without context` / `pagination cannot be combined with filter` | 分页约束违规 | 见 §2.7：单 Sheet、去掉 filter/filterBy、countPerPage 移到顶层维度 |
+| `block anchor ... must be at the block's top-left` / `subtotal/grand-total bindings are not supported inside a repeated block` / `template cell ... overlaps block` | 块规则违规 | 锚点放块左上角；小计移出块；外部格移出块矩形 |
+| `dimension binding "X" ... must reference a dimension, got metaType=METRIC` | 数值列做维度 | 见 §3：换 DIM 字段或加计算字段 |
+| `unknown data view "X"` / `unknown column "X" in data view` / `Field 'MISSING_X' ... was not found in dataset schema` | 模板引用字段没进子视图查询区，或视图别名拼错 | 把字段加进对应 `addDataView` 子卡的 row/metric；核对别名与 `dataSourceRelations.tableName` |
+| `relations do not connect all joined data views into one graph` | 多源 JOIN 断图 | 补 relations 使所有视图连通 |
+| `parent graph cycle`（环路径 `A1->B2->A2->B2`） | 外部模板父格循环依赖：值格省略 `C=` 被默认推断挂左侧标签，标签又显式挂回值格 | 给块内所有值格显式写 `C=锚点`；用 `guanvis report inspect <xlsx>` 看推断父格链 |
+| `unknown option "X"` | 绑定 options 拼错 | 只用 `expansion/fillMode/context/countPerPage/filter/filterBy/numberFormat/style`（维度另有 `group/sort`，度量另有 `aggregate`） |
+
+发布后/线上阶段：
+
+| 现象 | 原因 | 修复 |
+|---|---|---|
+| 导入成功但 `GET /api/card` 报"找不到相关卡片"或 `None.get` | Pro 卡没和引用它的 Page 同包发布；或卡 ID 不是"首字母+23 位 hex"形态 | Pro 必须与 Page 一起 pack/publish；ID 一律用 `guanvis genid` 生成 |
+| 同包发布、ID 形态正确，Import succeeded 后 preview 仍持续"找不到相关卡片" | 该 ID 此前经历过"失败发布→成功导入"混合序列，后端残留坏状态（dev29 两次复现） | 不要调 payload：`guanvis genid` 换全新 card/page ID 重发，立即恢复 |
+| `dynamic formula cannot reference data fields` 但公式里只有 URL/中文句号 | 旧版校验器把字符串字面量内的点号 token 误判为 `view.field`（已修复） | 升级 guanvis；`HYPERLINK("https://...","文本")` 等含点字符串现在直接可用 |
+| 发布成功但导出 500 `SearchEngine` NPE | 绑定级 `filter` 写了自创语法（如 `"字段=值"`）——F= 是跨视图映射通道不是常量过滤 | 分列常量对比改"每列一个数据视图 + addFilter"（§2.11） |
+| `field ... is a date-granularity zone field, which the Pro backend cannot query` | Pro 数据视图里的日期字段带了 `granularity` | 加 `DATE_FORMAT([日期],'yyyy-MM')` 计算字段并绑定它 |
+| `unsupported option(s): filter`（bindGrandTotal 上） | `bindGrandTotal` 只接受 aggregate/numberFormat/style | 需要过滤的固定值格改 `bindMetric` + `context:"None", expansion:"none"`，过滤放数据视图 |
+| `card preview` 结果残留 `{{...}}` | 模板表达式没被 GcExcel 识别（语法/字段/视图名错） | 用 `guanvis report inspect` 核对表达式；核对字段是否在子视图查询区 |
+| 后端 500 `父格设置存在循环依赖` | 同 pack 表的 parent graph cycle（旧包未经过本地校验） | 重新 pack（本地环检测已覆盖），按上表修复 |
+| 后端 500 嵌套 `LP(...)` | 旧包同源 filterBy | 删同源 filterBy 重发 |
+| 导入报 `该应用具有 COMPLEX_REPORT_PRO，请先联系管理员开通...` | 目标环境未开 Pro license | 换有授权的环境或联系管理员，不是脚本问题 |
+| 页面上 Pro 卡渲染空白但 preview xlsx 正常 | 前端渲染波动 | 稍候刷新或 `guanvis screenshot` 复核；以 preview xlsx 为准 |
+
+## 5. 编辑已有 Pro（checkout 闭环）
+
+```bash
+guanvis checkout <pageId> -d ./work        # 下载 templates/<cdId>.xlsx + 生成 createComplexReportPro 脚本（templateVersion 自增）
+guanvis report inspect ./work/templates/<cdId>.xlsx     # 看模板格/父格链/环检测（不打开 Excel）
+guanvis report decompile ./work/templates/<cdId>.xlsx -o wb.js   # 反编译为 Workbook DSL 或 patch 脚手架
+```
+
+- 创建与编辑共用一套 Workbook DSL，仅基底不同：`createReportWorkbook()` 从零构建（`addSheet`），`createReportWorkbook(templatePath)` 基底增量编辑（`editSheet`）；挂载入口统一 `.setWorkbook(workbook)`。
+- decompile 全量可表达（冻结窗格、单元格比较/公式条件格式、序号列、阶梯布局都在覆盖内）→ 输出从零构建源码，把 card JS 的 `.setTemplate(...)` 换成 `.setWorkbook(workbook)`，模板即文本化，直接改 DSL。
+- 模板含 DSL 无法表达部件（内嵌图片/数据验证等）→ 自动输出基底编辑脚手架：只写增量操作叠加在原模板上，未触及部件（图片、条件格式、冻结、样式）原样保留。`editSheet` 内方法与 `addSheet` 完全同名，另加仅编辑模式合法的原语：`clearCell(cell)` / `unmerge(range)` / `insertRows(row, n?)` / `removeRows(row, n?)` / `insertCols(col, n?)` / `removeCols(col, n?)`（结构移动会自动重写模板表达式里的单元格引用与 `C=`/`F=` 父格，删除被引用的模板格会拒绝）/ `setCellStyle(cellOrRange, style)`（合并语义，只改给出的属性）；落点已是模板表达式时须 `{ overwrite: true }` 显式声明替换。插入行列后，后续操作坐标按移位后的最终位置书写。
+- **多轮编辑防护**：基底编辑的发布结果 = 本地 templates/ 快照 + JS 里全部 editSheet 操作，多轮修改必须在原操作序列后**累积追加**（只保留最后一轮会丢掉之前的修改）。preview/diff/pack/publish 检测到本地基底落后于线上（JS templateVersion 比 base 快照 version 大超过 1）时会打印 stale-base warning。想改写干净增量时运行 `guanvis checkout <pgId> -d <dir> --refresh-base`：只刷新 .guanvis/raw、.guanvis/base、templates/、schema.js，不动 card_*.js / page.js；刷新后**必须删除已发布过的旧操作**（它们已包含在新基底里，保留会重复应用，如 insertRows 插两次行）。
+- 批量/样式增强（addSheet/editSheet 通用）：`setRow(startCell, values, style?)` / `setColumn(...)` 一次写一行/一列（`null` 跳格）；`setColumnWidth("C:E", 14)` 范围列宽；`setSheetDefaults({...})` 默认宽高；样式对象支持 `underline`（合计线）、`strikeout`、`fontFamily`、`indent`（科目缩进）、`border`/`borderTop`…（`{ style: "double", color }`，会计"下双线"= `borderBottom: { style: "double" }`）。dev29 已实证 GcExcel 全部保留。
+- **基底编辑最小形态**：
+
+```javascript
+var workbook = createReportWorkbook("templates/<cdId>.xlsx")
+    .editSheet("Sheet1", function (sheet) {
+        sheet.setValue("A1", "新标题", { bold: true });                       // 覆盖静态格
+        sheet.setDynamicFormula("D3", "AVERAGE(B3)", { context: "A3" });      // 新增模板格
+        sheet.bindMetric("E3", reportField("v", "金额"),
+            { aggregate: "SUM", context: "A3", overwrite: true });            // 替换已有模板格需显式 overwrite
+    });
+    // 需要新增 Sheet 时同一 workbook 上继续 .addSheet("说明", fn)
+report.setWorkbook(workbook);   // 与 .setTemplate() 二选一
+```
+
+- 改完 `guanvis diff ./work` 看影响面（基底编辑的每条指令会以 `card.template["Sheet"].op[i]` 逐条列出）→ `pack` → 发布覆盖线上 Page 前必须向用户确认后 `publish --allow-overwrite`。
+- **templateVersion 自动管理**：publish 成功后 CLI 自动把工程 JS 的 `.setTemplateVersion(N)` 改写为 N+1（服务端按 version 缓存模板附件，同版本重发模板变更会静默不生效）。若提示未找到该调用，下轮改模板前必须手动补 `.setTemplateVersion(N+1)`。
+
+## 6. 验证闭环（必须走完）
+
+`pack` 通过、`preview` 有 xlsx **都不等于语义正确**——只有 GcExcel 才能验证模板展开。发布后必须：
+
+```bash
+guancli card preview <proCardId> -o result.xlsx   # 1. 导出真实渲染结果
+# 2. 检查 result.xlsx：无残留 {{...}}；行数/分组结构符合预期；抽 1-2 个小计值人工核对
+guancli card preview <proCardId> --filter "字段 EQ 值" -o filtered.xlsx   # 3.（有筛选联动时）验证 childFilters
+```
+
+需要视觉判断再用 `guanvis screenshot <pageId>`（消耗图像 token，不作默认步骤）。

package/skills-bundle/guanvis/references/dir-and-page-management.md

@@ -0,0 +1,48 @@
+# 页面目录与页面壳管理（guanvis dir / guanvis page）
+
+本文是 `guanvis dir`（页面目录树）与 `guanvis page rename/move/delete`（页面壳）的完整硬约束。改**页面内容**（卡片、布局、筛选器）不在本文范围，仍走 checkout + publish（见 `checkout-editing.md`）。
+
+## 1. 页面目录管理（guanvis dir）
+
+`guanvis dir` 管的是**页面（PAGE）目录树**——发布时 `--page-parent-dir` / `.setParentDir()` 要传的那个 `dirId`。
+
+```bash
+guanvis dir create --name "季度经营" --parent <父目录 dirId>   # 输出的 dirId 可直接用于 publish --page-parent-dir
+guanvis dir rename <dirId> --name "新名称"                     # 保留 dirId 与目录内容
+guanvis dir move <dirId> --parent <新父目录 dirId>             # 保留 dirId 与目录名
+guanvis dir delete <dirId>                                     # 不加 --yes 时只打印目标信息并取消
+guanvis dir delete <dirId> --yes                               # 真正删除
+```
+
+硬约束：
+
+- **`dir delete` 必须显式加 `--yes`**：不加时只打印目标目录（dirId、路径、父目录、是否为空）与警告，然后以「操作已取消」返回，不发删除请求。
+- **删除目标必须是空目录**：只要还有子目录或页面就一律拒绝并列出内容，本命令**不提供任何级联删除开关**；先手动清空或把内容移走（页面用 `guanvis page move`，子目录用 `guanvis dir move`）。
+- **目录删除是物理删除，不进回收站、不可恢复**——与页面删除（软删，进回收站）语义相反，不要把页面那边"删了还能捞回来"的经验套到目录上。删错只能重建目录再把内容搬回去，而目录权限配置搬不回来。
+- **`--parent` 必填且不能用空串表示根目录**：根目录也有真实 `dirId`，用 `guancli page tree --type dir` 查。
+- **根目录不可改名、移动或删除**，命令在写前直接拦截。
+- **不能把目录移进它自己的子树**（成环）：命令在写前检测并说清是成环，不依赖服务端那句看不出成因的 500。
+- 四个子命令都做写前预检（目标存在、是目录不是页面）+ 写后回读目录树比对（名称/父目录/存在性），回读不一致一律判为失败。`rename` 与 `move` 走同一个服务端接口且 `name` 与 `parentDirId` 必须同时提交，CLI 会自动回填未改动的那个并确认它没被顺带改掉。
+- 只读查看目录树用 `guancli page tree --type dir`，`guanvis dir` 不提供 `tree` 子命令。
+
+## 2. 页面本身的改名/移动/删除（guanvis page）
+
+下面三个命令只动页面这个"壳"，保留 pgId。
+
+```bash
+guanvis page rename <pgId> --name "月度销售看板"       # 保留 pgId 与页面内容
+guanvis page move <pgId> --parent-dir <dirId>          # 换目录，保留 pgId
+guanvis page delete <pgId>                             # 不加 --yes 时只打印目标信息并取消
+guanvis page delete <pgId> --yes                       # 删除（页面上不能有卡片）
+guanvis page delete <pgId> --yes --force               # 连同页面上的卡片一起删除
+```
+
+硬约束：
+
+- **`page delete` 必须显式加 `--yes`**：不加时只打印目标（pgId、名称、页面类型、目录路径、卡片数）与警告，然后以「操作已取消」返回，不发删除请求。
+- **`--force` 不是二级确认**，它是后端 force 参数的直通，语义只有"连页面上的卡片一起删"；单独给 `--force` 而不给 `--yes` 仍会被 `--yes` 闸门拦住。页面上有卡片却不加 `--force` 时，服务端会以 1004 拒绝，CLI 把它翻译成"还有 N 张卡片，请追加 --force"。
+- **页面删除是软删**：页面连同卡片与权限进回收站——但 **CLI 不提供任何恢复命令**，要找回只能人工登录 BI 网页端，在回收站里找到该页面并还原。不要向用户承诺一条能撤销的命令。
+- **被 SuperApp/门户引用的页面、概览页之类的特殊页面由服务端硬阻断**，`--force` 也绕不过；这类报错原样带出，需要先在 BI 网页端解除引用或改用对应入口删除。
+- **`--parent-dir` 必填且不能用空串**：后端收到空值只回一句"目录不存在"，CLI 在写前就拦下并提示根目录也有真实 `dirId`。
+- **rename / move 是可逆操作，不需要 `--yes`**；改名超出服务端长度上限（实测 50 个字符）时后端会截断后仍返回成功，写后回读会把它判为失败并点明截断后的实际名称。
+- 三个子命令都做写前预检（目标在页面树里存在、是页面不是目录——传目录 `dirId` 会被拦下并指回 `guanvis dir`）+ 写后回读比对（delete 查页面树里已消失，rename 查名称、move 查 `parentDirId`，并确认没顺带改掉另一个字段），回读不一致一律判为失败。