@guandata/guanvis 0.1.41 → 0.1.42

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## @guandata/guanvis 0.1.42 - 2026-08-27
+
+- 主题偏好会校验目标主题真实存在；`pack` 不再把隐藏文件带入发布产物。
+- 修复计算字段去重键错误，补齐字段展示类型，减少合法计算字段被覆盖或误判。
+- 页面布局支持 `flow`；上传后会恢复页面归位，父目录设置失败不再静默忽略。
+- preview、checkout 和实时项目校验失败会正确返回非零退出，示例工程与 eval 退化会被测试及时发现。
+- 页面目录与页面操作约束拆分为按需参考文档，Skill 主文档更精简且保持完整操作边界。
+- 统一结构化错误与拼错子命令的非零退出行为。
+
 ## @guandata/guanvis 0.1.41 - 2026-08-25
 
 - 新增页面目录创建、改名、移动和删除能力，并支持页面本身的删除、改名和移动。

package/README.md

@@ -55,6 +55,13 @@ guanvis publish ./my_dashboard/ --allow-overwrite
 
 ## 版本更新
 
+### @guandata/guanvis 0.1.42
+
+- 主题偏好会校验真实主题，打包时不再携带隐藏文件。
+- 修复计算字段去重与展示类型，页面布局新增 `flow` 支持。
+- 上传后页面归位和父目录设置更可靠，preview、checkout 校验失败会正确非零退出。
+- 精简 Skill 主文档并保留完整的页面目录与页面操作约束。
+
 ### @guandata/guanvis 0.1.41
 
 - 新增页面目录创建、改名、移动和删除，以及页面删除、改名和移动能力。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guanvis",
-  "version": "0.1.41",
+  "version": "0.1.42",
   "description": "观远 BI Card/Page 生成工具 - 通过 JS DSL 创建图表和仪表板",
   "bin": {
     "guanvis": "bin/run.js"

package/skills/guanvis/SKILL.md

@@ -8,8 +8,7 @@ compatibility: "Requires Node.js 14+. Install via npm link --foreground-scripts
 
 执行型 skill：通过 AI 编写的 JS 脚本创建/修改 BI Card 和 Page 资源。
 
-- AI 生成 `card_*.js` 定义 Card；`page.js` 组装仪表板。`schema.js` 由 `init`/`checkout` 生成（不允许 AI 修改，checkout 生成是 best-effort）；指标卡片用 `metric-init` 生成 `metrics.js`。
-- 框架在 preview/pack/publish 时内置验证（字段数量、zone 兼容性、必填字段等）；认证复用 `guancli` 共享配置。
+AI 生成 `card_*.js` 定义 Card、`page.js` 组装仪表板（`schema.js`/`metrics.js` 是生成的事实快照，见下）；框架在 preview/pack/publish 时内置验证（字段数量、zone 兼容性、必填字段等），认证复用 `guancli` 共享配置。
 
 ## Harness 化工作法
 
@@ -28,7 +27,7 @@ compatibility: "Requires Node.js 14+. Install via npm link --foreground-scripts
 - 每次生成都针对明确目录或明确子目录；不要把 unrelated 示例、旧包或临时 ZIP 混入同一个发布目标。
 - Card/Page/Selector 的 `.setId(...)` 必须用 `guanvis genid` 生成（保证字母开头）；数字开头 ID 会触发 BI 前端 CSS selector 语法错误，新建资源校验直接报 error 拦截（checkout/attach 的已有资源保留原 ID 不受限）。
 - 先 `preview` 做本地结构验证，再 `publish`（publish 自带构建打包上传，**发布前不需要单独 `pack`**；`pack` 只用于生成离线 ZIP 走 `upload`）。仅修复描述用 `card/page set-description` 并同步 JS 中的 `.setDescription(...)`；改看板内容按「线上仪表板更新红线」处理。
-- **编辑红线（编辑 ≠ 删除重建）**：修改/改名已发布 Page 或 Card 必须保留原 pgId/cdId 原地覆盖发布。本地源工程还在且线上未被网页端改动 → 直接改本地 JS 同 ID 重新 publish；否则 → `checkout` 后编辑，且**不得**把 `attachCard` 改写成 `createCard()`（绕过 base JSON 会丢线上配置）。**禁止**用"新建 + 删除旧的"模拟编辑——资源 ID 变化会让收藏、分享、订阅、门户引用和页面权限全部失效且无法迁移；"保留旧页面出新版本"用 `guanvis page save-as`。全局参数同理只能 `parameter update <dpId>` 原地更新，禁止 delete 后重建同名参数（dpId 断链）。**页面本身**的改名和换目录已有原地能力（`guanvis page rename` / `guanvis page move`，都保留 pgId、都不需要 `--yes`），要改页面名或挪页面位置一律用它们，**不必也不允许**"删掉页面再发一个新的"——重发拿到的是新 pgId，而 `guanvis page delete` 是软删且 CLI 没有恢复命令，删错只能人工去 BI 网页端回收站还原。**页面目录**同样已有原地能力（`guanvis dir rename` / `guanvis dir move`），要改目录名或挪目录位置一律用它们，不要"新建目录 + 逐个搬页面 + 删旧目录"。各资源的原地更新入口见下方「编辑红线速查」。分流决策见 `references/checkout-editing.md` §4。
+- **编辑红线（编辑 ≠ 删除重建）**：修改/改名已发布 Page 或 Card 必须保留原 pgId/cdId 原地覆盖发布。本地源工程还在且线上未被网页端改动 → 直接改本地 JS 同 ID 重新 publish；否则 → `checkout` 后编辑，且**不得**把 `attachCard` 改写成 `createCard()`（绕过 base JSON 会丢线上配置）。**禁止**用"新建 + 删除旧的"模拟编辑——资源 ID 变化会让收藏、分享、订阅、门户引用和页面权限全部失效且无法迁移；"保留旧页面出新版本"用 `guanvis page save-as`。全局参数同理只能 `parameter update <dpId>` 原地更新，禁止 delete 后重建同名参数（dpId 断链）。**页面壳与页面目录**的改名/换位置已有原地命令（`guanvis page rename/move`、`guanvis dir rename/move`，保留原 ID、可逆、不需要 `--yes`），一律用它们，**禁止**"删掉重发页面 / 新建目录搬内容删旧目录"模拟改名挪位。各资源的原地更新入口见下方「编辑红线速查」。分流决策见 `references/checkout-editing.md` §4。
 - **资源包安全红线**：Agent 只编辑 DSL 源文件；资源包 ZIP 是 `guanvis pack/publish` 的派生产物，不手工生成、解包修改或重打包。`guanvis upload` 只允许上传 `guanvis pack` 原样生成的 ZIP。若用户要求批量重绑资源、迁移已有页面或复用线上页面结构，先停下来说明风险并确认方案，不要直接改 ZIP。
 - 发布后优先用 `guancli page get/card get` 回读结构与配置；`guanvis screenshot` 仅在明确需要视觉质量判断且模型支持图像理解时使用（额外消耗 token），不作默认闭环步骤。**例外**：自定义图表的视觉验收按速查第 24 条执行。
 
@@ -63,7 +62,7 @@ compatibility: "Requires Node.js 14+. Install via npm link --foreground-scripts
 12. **同环比默认**：未指定输出值时默认增长率；未指定模式时默认 `ComparativeMode.FILTER_BASED`（普通模式需显式 `NORMAL`）。日期字段已是预聚合周期字段（如 `月开始日期`）时必须声明 `{ granularity: Granularity.NONE }`，避免按 DAY 筛选窗口计算为空
 13. **placeCard 入参**：优先用 card/selector ID 字符串（checkout 工程与子目录工程必须用），如 `placeCard("cardId", x, y, w, h)`。数字 index 仅限新建工程，按可布局资源（registerCard/MetricChart/TextCard/ImageCard/CustomChart/DuPontChart）的注册顺序累加，文件按文件名排序加载；**registerSelector 不参与 card index 计数**——selector 进画布/布局组件一律用其 ID 字符串。
 14. **publish 认证**：由底层 CLI 负责——普通 guancli profile 先 `guancli auth use <profile>`；上游托管 OIDC Token 时在当前进程同时设置 `GUANCLI_OIDC_BASE_URL`/`GUANCLI_OIDC_ACCESS_TOKEN`，无需本地 profile；guancli-lite 使用 `GUANCLI_BASE_URL`/`GUANCLI_TOKEN`
-15. **更新线上仪表板**：checkout 工程 = 修改指定线上 Page，保留原资源 ID；CLI 检测到同 ID Page 时必须先向用户说明覆盖影响并取得明确确认，才可加 `--allow-overwrite`（自带覆盖备份兜底）。要"保留原页面出新版本"用 `guanvis page save-as <pgId> --suffix _guanvis`（BI 原生整页另存为，服务端重映射全部卡片间引用），不要复制 checkout JSON 改 ID；细节见 `references/checkout-editing.md` §5
+15. **更新线上仪表板**：checkout 工程 = 修改指定线上 Page，保留原资源 ID；同 ID 覆盖必须先经用户确认才可加 `--allow-overwrite`，"保留原页面出新版本"用 `guanvis page save-as <pgId> --suffix _guanvis`；完整红线见下文「线上仪表板更新红线」与 `references/checkout-editing.md` §5
 16. **描述维护**：仅修复已发布资源描述时保留原 ID，用 `guanvis card/page set-description`；本地有 JS 工程时同步更新 `.setDescription(...)`
 17. **主题切换**：用户描述风格 → 工程目录里 `guanvis theme preference --keywords "..." --sync`；不要选租户默认"浅色"/"深色"，没有合适主题就保持/清空偏好用内置"简约"兜底；改版未提风格时普通工程由 `.applied.json` 继承上次主题，checkout 工程按 Page base 保留线上主题。多子目录工程主题按子目录独立配置和执行；详见 `references/theme.md`
 18. **设计规则**：preview/pack/publish 自动应用内置设计规则；自定义时在工程目录新建 `design-rule.json`，不手改 `themes/<themeId>.json`；详见 `references/theme.md`
@@ -81,8 +80,7 @@ compatibility: "Requires Node.js 14+. Install via npm link --foreground-scripts
 - 基于指标平台已有指标创建指标卡片（MetricChart，后端 `cdType=13`）。
 - 创建或 checkout/edit 复杂报表 Pro——**仅当用户明确点名"复杂报表 / 复杂报表 Pro"或被修改卡片已是 Pro**（需单独授权；泛化"做个表格/报表"用原生卡片）；旧版复杂报表明确拒绝并建议外部迁移后新建 Pro。
 - 创建筛选器并配置联动；组装 Card 和筛选器为仪表板/Page（grid layout + 筛选器面板）。
-- 创建、改名、移动或删除**页面目录**（`guanvis dir`），包括为 `publish --page-parent-dir` 准备目标目录。
-- 改名、移动或删除**页面本身**（`guanvis page rename` / `page move` / `page delete`）。删除需要 `--yes`，页面上有卡片时还要 `--force`；被删页面没有命令行恢复入口，只能人工登录 BI 网页端回收站还原。
+- 页面目录（`guanvis dir`）与页面壳（`guanvis page rename/move/delete`）的创建、改名、移动、删除；红线见下方「页面目录与页面壳管理」。
 - 用户提到 `card.js`、`page.js`、CardPayload、图表类型、zone spec、筛选器联动。
 
 ## 固定工作方式
@@ -122,11 +120,11 @@ var card = createMetricChart(ChartType.PIVOT_TABLE, "销售指标分析")
 registerMetricChart(card.build());
 ```
 
-`metrics.js`、`dynamic-parameters.js` 和 `theme-colors.js` 必须在 `card_*.js` 前加载；目录模式会自动按 `schema.js` → `metrics.js` → `dynamic-parameters.js` → `theme-colors.js` → `card_*.js` → `selector_*.js` → `page.js` 的顺序执行。
+目录模式自动按「文件结构约定」的顺序加载：`metrics.js` 等快照文件先于 `card_*.js` 执行。
 
 ### 3. 设置仪表板主题（按需）
 
-如果用户**明确提到了视觉风格**（"深色科技风"、"蓝色简约"、"科技蓝T004" 或具体 themeId 等），在编写 card/page 之前把意图落到 `.preference.json`。不要把租户默认的“浅色”/“深色”当作可选主题；如果候选里没有合适风格，跳过这一步或执行 `theme preference --clear`，让命令自动使用内置“简约”：
+如果用户**明确提到了视觉风格**（"深色科技风"、"蓝色简约"、"科技蓝T004" 或具体 themeId 等），在编写 card/page 之前把意图落到 `.preference.json`：
 
 ```bash
 cd ./my_dashboard
@@ -171,9 +169,9 @@ var page = createPage("销售仪表板")
 registerPage(page.build());
 ```
 
-**仪表板主题**：新建工程没配 `themes/` 时 `preview`/`pack`/`publish` 自动使用内置简约主题（不依赖租户线上主题列表）；`checkout` 工程未明确切换主题时保留线上主题或“无主题”状态。普通图表与指标平台 MetricChart 都会自动应用主题视觉配置（只写 `settings` 与 `meta.chartMain.props`，不改 `zoneData` 等查询字段）。**JS DSL 不提供主题接口**——`setDashboardTheme(...)` / `page.setTheme(...)` 会因函数未定义而报错，主题一律走 `guanvis theme preference`（见 `references/theme.md`）。
+**仪表板主题**：新建工程没配 `themes/` 时 `preview`/`pack`/`publish` 自动使用内置简约主题（不依赖租户线上主题列表）；`checkout` 工程未明确切换主题时保留线上主题或“无主题”状态。**JS DSL 不提供主题接口**——`setDashboardTheme(...)` / `page.setTheme(...)` 会因函数未定义而报错，主题一律走 `guanvis theme preference`（见 `references/theme.md`）。
 
-**单张图表主题色**：用 `.setThemeColor(tcId, colors?, options?)` 切换主题色、修改颜色覆盖或选择分类/顺序色板，`options.useSequentialPalette` 用于显式选择色板模式。只修改当前主题时 `tcId` 传 `null`；编写配置前必须检查项目根目录的 `theme-colors.js`，不存在时先运行 `guanvis theme-color sync -d <project>`，非空 `tcId` 必须取自快照。多页面和多子目录共用这一份快照，构建阶段的自动生成只作兜底。完整语义见 `references/chart-properties.md`。
+**单张图表主题色**：用 `.setThemeColor(tcId, colors?, options?)` 切换主题色、修改颜色覆盖或选择分类/顺序色板（`options.useSequentialPalette` 显式选色板模式；只改当前主题时 `tcId` 传 `null`）。`tcId` 必须取自 `theme-colors.js` 快照（快照约束见「Harness 化工作法」），完整语义见 `references/chart-properties.md`。
 
 **多页面支持**：同一项目可多次 `registerPage`。两种组织方式：
 
@@ -206,19 +204,14 @@ guanvis publish ./my_dashboard/ [--page-parent-dir <dir_id>]
 guanvis pack [-o output.zip] ./my_dashboard/
 guanvis upload output.zip             # 只允许上传 guanvis pack 原样生成的 ZIP
 
-# 页面目录（增删改；查看目录树用 guancli page tree --type dir）
+# 页面目录与页面壳（只动壳，改页面内容仍走 checkout+publish；红线见「页面目录与页面壳管理」）
 guanvis dir create --name <名称> --parent <父目录 dirId>
 guanvis dir rename <dirId> --name <新名称>
 guanvis dir move <dirId> --parent <新父目录 dirId>
-guanvis dir delete <dirId> --yes      # 目录必须为空；物理删除，不进回收站
-
-# 页面本身（改名/换目录/删除；改页面内容仍走 checkout + publish）
-guanvis page rename <pgId> --name <新名称>          # 保留 pgId；可逆，不需要 --yes
-guanvis page move <pgId> --parent-dir <dirId>       # 保留 pgId；可逆，不需要 --yes
-guanvis page delete <pgId>                          # 无 --yes：只打印目标信息并取消
-guanvis page delete <pgId> --yes                    # 删除空页面（软删，进回收站）
-guanvis page delete <pgId> --yes --force            # 连同页面上的卡片一起删除（--force 不是二级确认，仍需 --yes）
-# 删除后没有 CLI 恢复命令，要找回只能人工登录 BI 网页端在回收站里还原
+guanvis dir delete <dirId> --yes                    # 只删空目录；物理删除不进回收站
+guanvis page rename <pgId> --name <新名称>           # rename/move 保留 pgId、可逆、不需 --yes
+guanvis page move <pgId> --parent-dir <dirId>
+guanvis page delete <pgId> --yes [--force]          # 软删进回收站但 CLI 无恢复命令；有卡片需 --force
 
 # 修复已发布资源描述（保留原 ID；本地有 JS 工程时同步更新 .setDescription(...)）
 guanvis card set-description <cd_id> --description "..."   # 或 --file ./story.md
@@ -242,67 +235,19 @@ guanvis icon list
 guanvis icon list --group default_line -f json
 ```
 
-**多子目录工程**：每个子目录是独立工程，preview/pack/publish/`theme *` 必须 `cd` 进各子目录分别执行、各出各的资源包；根目录直接运行时若任一子目录有 `themes/` 会拒绝执行并打印 cd 提示。
-
 **发布机制**：`publish`/`upload` 走 BI transfer API，`needIdMapping=false` 同 ID 覆盖、发布前强制校验 Page 归属（Card-only 与孤儿 Card/Selector 包直接拒绝）、覆盖检查只探测 Page ID；接口/认证/header 细节见 `references/publish-and-constraints.md`。
 
 **线上仪表板更新红线**：checkout 工程发布 = 覆盖式修改指定 Page。CLI 检测到同 ID Page 时，**Agent 禁止未经用户确认自行加 `--allow-overwrite`**——必须先说明将覆盖的 Page ID/名称与影响，用户明确确认后才可重跑加该参数（CLI 会先做覆盖备份，备份失败则中止；`--dry-run` 可预查覆盖对象）。要"保留原页面出新版本"用 `guanvis page save-as`，不要复制 JSON 改 ID。备份/回滚/save-as 细节见 `references/checkout-editing.md` §5。
 
-## 页面目录管理（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` 子命令。
+## 页面目录与页面壳管理（guanvis dir / guanvis page）
 
-## 页面本身的改名/移动/删除（guanvis page）
-
-改**页面内容**（卡片、布局、筛选器）仍然走 checkout + publish；下面三个命令只动页面这个"壳"，保留 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`，并确认没顺带改掉另一个字段），回读不一致一律判为失败。
+命令清单见上方「执行命令」。红线：删除都有 `--yes` 闸门（不加只打印并取消）；**目录删除是物理删除不可恢复且只删空目录，页面删除是软删进回收站但 CLI 无恢复命令**；rename/move 保留原 ID、可逆、不需要 `--yes`。`--parent`/`--parent-dir` 必填（根目录也有真实 `dirId`，用 `guancli page tree --type dir` 查）。完整硬约束（`--force` 语义、服务端硬阻断、预检/回读规则、成环拦截等）动手前读 `references/dir-and-page-management.md`。
 
 ## 复杂报表 Pro 工作方式
 
 **进入前提**：用户明确点名"复杂报表 / 复杂报表 Pro"，或 checkout 的目标卡片已是 Pro（未点名的表格/报表需求回「固定工作方式」用原生卡片）。只支持 `COMPLEX_REPORT_PRO`，旧版复杂报表拒绝并建议外部迁移后新建 Pro。
 
-与「固定工作方式」同体系（auth → init → 写脚本 → preview/pack → publish），差异只在脚本形态和验证闭环。**动手前先读 `references/complex-report-pro-patterns.md`**：
-
-- **新建**：§0 选型门槛 → §2.0 最小工程骨架（init/`--alias`/genid + 数据视图/workbook/注册三段式）→ §2 结构配方 → §3 数据视图规则。Pro 卡必须与引用它的 Page 同包发布。
-- **编辑已有 Pro**：checkout 后统一走 `.setWorkbook()`；decompile 产物形态、`editSheet` 原语、templateVersion 生命周期、stale-base 防护全在 §5。
-- **报错修复**：对照 §4 修复表。
-- **验证闭环（发布后必做）**：`pack`/`preview` 只验证结构，发布后必须 `guancli card preview <proCardId> -o result.xlsx` 检查无 `{{...}}` 残留，详见 §6。
+与「固定工作方式」同体系（auth → init → 写脚本 → preview/pack → publish），差异只在脚本形态和验证闭环，**动手前先读 `references/complex-report-pro-patterns.md`**（新建走 §0 选型 → §2 骨架与配方 → §3 数据视图规则；编辑已有 Pro 统一 `.setWorkbook()` 见 §5；报错对照 §4 修复表）。两条硬红线：Pro 卡必须与引用它的 Page 同包发布；`pack`/`preview` 只验证结构，发布后必须 `guancli card preview <proCardId> -o result.xlsx` 检查无 `{{...}}` 残留（§6）。
 
 ## 文件结构约定
 
@@ -338,6 +283,7 @@ guanvis page delete <pgId> --yes --force               # 连同页面上的卡
 | 各类 Builder API 与枚举（含 ComplexReportProBuilder 权威定义） | `references/builder-reference.md` | 写或改 JS DSL builder 调用时 |
 | 图表属性配置 | `references/chart-properties.md` | 创建或修改图表属性时 |
 | checkout 编辑闭环：生成物、attachCard 操作语义、覆盖发布与备份 | `references/checkout-editing.md` | checkout 工程动手前、改线上仪表板时 |
+| 页面目录与页面壳管理完整硬约束 | `references/dir-and-page-management.md` | `guanvis dir` / `page rename/move/delete` 动手前 |
 | 复杂报表 Pro 选型/骨架/配方/报错/编辑/验证 | `references/complex-report-pro-patterns.md` | 创建或修改 Pro 前必读 |
 | zone 校验、图表选型、地图/拆分图、字段对象细节 | `references/validation-and-chart-patterns.md` | pack 报错、选型不确定时 |
 | 仪表板主题机制与 theme 排错 | `references/theme.md` | 指定视觉风格、主题异常时 |

package/skills/guanvis/evals/china_map/schema.js

@@ -7,4 +7,4 @@ defineDataset("s1234567890abcdef12345678", [
     { fdId: "a2222222222222222222222", name: "销售额", fdType: "DOUBLE", metaType: "METRIC" },
     { fdId: "a3333333333333333333333", name: "利润率", fdType: "DOUBLE", metaType: "METRIC" },
     { fdId: "a4444444444444444444444", name: "订单数", fdType: "INT", metaType: "METRIC" }
-]);
+], { displayType: "CSV" });

package/skills/guanvis/evals/custom_chart_echarts/schema.js

@@ -6,4 +6,4 @@ defineDataset("s9ded2338f43807b095fbb4f", [
     { fdId: "o7093aaf2b2f32c9e964c41a", name: "产品", fdType: "STRING", metaType: "DIM" },
     { fdId: "lb1c31b4dc86511a27049a98", name: "营收", fdType: "DOUBLE", metaType: "METRIC" },
     { fdId: "aece10cd6806966be56f52ff", name: "成本", fdType: "DOUBLE", metaType: "METRIC" }
-]);
+], { displayType: "CSV" });

package/skills/guanvis/evals/sales_dashboard/card_04_pie.js

@@ -4,6 +4,6 @@ var card = createCard(ChartType.PIE, "产品分布")
     .addRow(f("产品"))
     .addMetric(f("营收", { aggrType: AggrType.SUM }))
     .setDataLabel({ show: true, showPercentage: true, showCategory: true })
-    .setPieSetting({ innerRadius: 0 });
+    .setPieSetting({ innerSize: 0 });
 
 registerCard(card.build());

package/skills/guanvis/evals/sales_dashboard/schema.js

@@ -11,4 +11,4 @@ defineDataset("s9ded2338f43807b095fbb4f", [
     { fdId: "aece10cd6806966be56f52ff", name: "成本", fdType: "DOUBLE", metaType: "METRIC" },
     { fdId: "g1b16b52a16eb10c5e26d4bb", name: "数量", fdType: "INT", metaType: "METRIC" },
     { fdId: "eae7cae6fbdcde68acdf5d1f", name: "利润率", fdType: "DOUBLE", metaType: "METRIC" }
-]);
+], { displayType: "CSV" });

package/skills/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`，并确认没顺带改掉另一个字段），回读不一致一律判为失败。