@guandata/guanvis 0.1.40 → 0.1.42

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## @guandata/guanvis 0.1.42 - 2026-08-27
+
+- 主题偏好会校验目标主题真实存在；`pack` 不再把隐藏文件带入发布产物。
+- 修复计算字段去重键错误，补齐字段展示类型，减少合法计算字段被覆盖或误判。
+- 页面布局支持 `flow`；上传后会恢复页面归位，父目录设置失败不再静默忽略。
+- preview、checkout 和实时项目校验失败会正确返回非零退出，示例工程与 eval 退化会被测试及时发现。
+- 页面目录与页面操作约束拆分为按需参考文档，Skill 主文档更精简且保持完整操作边界。
+- 统一结构化错误与拼错子命令的非零退出行为。
+
+## @guandata/guanvis 0.1.41 - 2026-08-25
+
+- 新增页面目录创建、改名、移动和删除能力，并支持页面本身的删除、改名和移动。
+- `publish` 支持指定页面目标目录，并会拒绝仍含生成器占位符的项目，减少误发布。
+- 修复卡片或筛选器自有计算字段被误判为无效绑定的问题。
+- 自动关联卡片可接收筛选条件，页面联动结果更符合实际配置。
+- 支持企业 OIDC 认证上下文，并同步升级底层请求兼容能力。
+
 ## @guandata/guanvis 0.1.40 - 2026-08-20
 
 - 完善自定义图表布局与视觉验收指引：使用结构化布局和运行时实测保证对齐，并明确避免通过像素解析做几何量化。

package/README.md

@@ -55,6 +55,20 @@ guanvis publish ./my_dashboard/ --allow-overwrite
 
 ## 版本更新
 
+### @guandata/guanvis 0.1.42
+
+- 主题偏好会校验真实主题，打包时不再携带隐藏文件。
+- 修复计算字段去重与展示类型，页面布局新增 `flow` 支持。
+- 上传后页面归位和父目录设置更可靠，preview、checkout 校验失败会正确非零退出。
+- 精简 Skill 主文档并保留完整的页面目录与页面操作约束。
+
+### @guandata/guanvis 0.1.41
+
+- 新增页面目录创建、改名、移动和删除，以及页面删除、改名和移动能力。
+- 发布时可指定页面目标目录，并拦截仍含生成器占位符的项目。
+- 修复自有计算字段误判，自动关联卡片可正确接收筛选条件。
+- 支持企业 OIDC 认证上下文，并升级底层请求兼容能力。
+
 ### @guandata/guanvis 0.1.40
 
 - 完善自定义图表布局与视觉验收指引，减少依赖手工数值微调造成的反复发布验证。

package/package.json

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

package/skills/guanvis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: guanvis
-description: 当用户要新建、修改、组装观远 BI / Guandata 的 Card（图表/报表卡片）、复杂报表 Pro（COMPLEX_REPORT_PRO）、用指标平台指标创建的指标卡片、文本卡片、图片卡片、筛选器（selector，含日历/时间宏/区间/离散值）或仪表板（Page），或给出 Card ID、数据集 ID、指标 ID、card.js/page.js、图表类型关键词（柱状/折线/饼/KPI/表格/漏斗/地图/散点等 30+ 种）时，优先使用这个 skill。即使用户只说"做个销售仪表板""创建一个复杂报表 Pro""用这个指标做张卡片""加个 KPI 卡片""新建一个区域筛选器联动所有图""帮我改一下这个图的图例""把这几个 card 拼成一个 page""加一个本月/近 7 天的快捷日期筛选"，也要主动使用。它通过 AI 编写简洁的 JS 脚本（card_*.js / selector_*.js / page.js）定义卡片、筛选器和页面布局，再 pack/publish 上传到目标 BI。认证复用 guancli 共享配置。只想查现有 Card/Page 内容走 guancli。旧版复杂报表不支持创建或编辑。
+description: 当用户要新建、修改、组装观远 BI / Guandata 的 Card（图表/报表卡片）、复杂报表 Pro（COMPLEX_REPORT_PRO）、用指标平台指标创建的指标卡片、文本卡片、图片卡片、筛选器（selector，含日历/时间宏/区间/离散值）或仪表板（Page），或给出 Card ID、数据集 ID、指标 ID、card.js/page.js、图表类型关键词（柱状/折线/饼/KPI/表格/漏斗/地图/散点等 30+ 种）时，优先使用这个 skill。即使用户只说"做个销售仪表板""创建一个复杂报表 Pro""用这个指标做张卡片""加个 KPI 卡片""新建一个区域筛选器联动所有图""帮我改一下这个图的图例""把这几个 card 拼成一个 page""加一个本月/近 7 天的快捷日期筛选"，也要主动使用。它通过 AI 编写简洁的 JS 脚本（card_*.js / selector_*.js / page.js）定义卡片、筛选器和页面布局，再 pack/publish 上传到目标 BI。认证复用 guancli 共享配置。页面目录（PAGE 目录树）的创建/改名/移动/删除也在这个 skill（`guanvis dir`），用户说"给看板建个目录""把这个页面目录改个名"时触发。页面本身的删除/改名/移动同样在这个 skill（`guanvis page delete/rename/move`），用户说"删掉这个页面""把这个页面挪到 XX 目录""给这个看板改个名"时触发。只想查现有 Card/Page 内容或目录树走 guancli。旧版复杂报表不支持创建或编辑。
 compatibility: "Requires Node.js 14+. Install via npm link --foreground-scripts (local) or npm install -g --foreground-scripts @guandata/guanvis (from internal Nexus registry) so the AI skill refresh result is visible. CLI command: guanvis."
 ---
 
@@ -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,10 +27,19 @@ 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 断链）。分流决策见 `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 条执行。
 
+### 编辑红线速查
+
+| 资源 | 编辑用什么 | 删除重建会丢什么 |
+|---|---|---|
+| 页面 Page | 内容改本地 JS 后同 pgId 重新 `publish`（线上被网页端改过则先 `checkout`）；只改描述用 `guanvis page set-description`；要保留旧版另出新版用 `guanvis page save-as`；页面本身的改名/换目录/删除用 `guanvis page rename/move/delete` | pgId 变化，收藏、分享、订阅、门户与 SuperApp 引用、页面权限全部断链且无法迁移 |
+| 卡片 Card | `checkout` 后 `attachCard(cdId, jsonPath)` 链式操作（不得改写成 `createCard()`）；只改描述用 `guanvis card set-description` | cdId 变化，`/page/<pgId>?anchor=<cdId>` 锚点链接、卡片级订阅与下游引用断链；网页端做过的线上配置丢失 |
+| 全局参数 Dynamic Parameter | `guanvis parameter update <dpId>` 原地更新 | dpId 变化，引用该参数的卡片与筛选器断链 |
+| 页面目录 Dir | 改名用 `guanvis dir rename <dirId> --name`；换位置用 `guanvis dir move <dirId> --parent <新父目录 dirId>` | 目录 ID 变化，需逐个把页面和子目录搬到新目录，目录权限配置丢失；且目录删除是**物理删除、不进回收站**，删错无从恢复 |
+
 ## AI Quick Reference（速查，详细说明见按需参考资料）
 
 **Checkout/attachCard 速记**：`attachCard(cardId, jsonPath)` 是"base JSON + 链式 DSL 操作 = 目标 JSON"，不修改 base JSON，重复执行产出相同 payload。zone 修改优先 `update*/patch*/add*/remove*/move*`（整 zone 重建的 `set*/clear*` 会触发 warning）；已有 selector 用 `.setSelectorSetting()` 修改筛选器配置，用 `.addLink()/.removeLink()/.clearLinks()` 修改联动，禁止借配置入口改变 selector 类型或重新绑定字段；自定义图表内容编辑仅限 SDK/ECHARTS_LITE（编辑 `charts/` 下反编译源文件），COMPLEX_REPORT/PLUGIN/PLUGIN_LITE/REPORT_FORM 调内容编辑 API 直接报错。发布前用 `guanvis diff <dir>` 或 preview 的 `changeSummary` 查看影响面；没有 DSL 操作覆盖的需求先扩展 DSL，不改 `.guanvis` JSON。完整操作语义（zone/筛选区/筛选栏画布互移等）见 `references/checkout-editing.md` §3。
@@ -53,8 +61,8 @@ compatibility: "Requires Node.js 14+. Install via npm link --foreground-scripts
 11. **selector 类型**：离散值 → `DS_ELEMENTS`（默认）；连续数值 → `SelectorType.DS_INTERVAL`；日期 → `CALENDAR`；快捷日期区间（本月/近7天等）→ `.setSelectorSetting({ type: SelectorType.TIME_MACRO, timeMacro: { options, defaultName } })`（旧 `.setTimeMacroOptions()` 仅保留兼容）
 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 先 `guancli auth use <profile>`，guancli-lite 用环境变量
-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
+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；同 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`
@@ -72,6 +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`）与页面壳（`guanvis page rename/move/delete`）的创建、改名、移动、删除；红线见下方「页面目录与页面壳管理」。
 - 用户提到 `card.js`、`page.js`、CardPayload、图表类型、zone spec、筛选器联动。
 
 ## 固定工作方式
@@ -111,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
@@ -160,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`。两种组织方式：
 
@@ -189,9 +198,21 @@ guanvis diff ./existing_dashboard/    # checkout/attach 工程的路径级变更
 
 # 发布（publish 自带构建打包上传；pack 只用于生成离线 ZIP 走 upload）
 guanvis publish ./my_dashboard/ [--page-parent-dir <dir_id>]
+# --page-parent-dir 要求目录已存在（也可在 page.js 里 .setParentDir()）；
+# 目标目录还不存在时先 guanvis dir create --name <名称> --parent <父目录 dirId> 建出来，
+# 用它输出的 dirId 再 publish；查已有目录 ID 用 guancli page tree --type dir
 guanvis pack [-o output.zip] ./my_dashboard/
 guanvis upload output.zip             # 只允许上传 guanvis pack 原样生成的 ZIP
 
+# 页面目录与页面壳（只动壳，改页面内容仍走 checkout+publish；红线见「页面目录与页面壳管理」）
+guanvis dir create --name <名称> --parent <父目录 dirId>
+guanvis dir rename <dirId> --name <新名称>
+guanvis dir move <dirId> --parent <新父目录 dirId>
+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
 guanvis page set-description <pg_id> --description "..."   # 支持 --visible=false
@@ -214,22 +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 page）
+
+命令清单见上方「执行命令」。红线：删除都有 `--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）。
 
 ## 文件结构约定
 
@@ -265,6 +283,7 @@ guanvis icon list --group default_line -f json
 | 各类 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/checkout-editing.md

@@ -42,6 +42,7 @@ checkout 读到的是"当前账号视角"的卡片定义，publish 会把它整
 - **禁止**用"新建一个新 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. 发布：覆盖确认、备份与"另存新版本"
 

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