@guandata/guanvis 0.1.39 → 0.1.41

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## @guandata/guanvis 0.1.41 - 2026-08-25
+
+- 新增页面目录创建、改名、移动和删除能力，并支持页面本身的删除、改名和移动。
+- `publish` 支持指定页面目标目录，并会拒绝仍含生成器占位符的项目，减少误发布。
+- 修复卡片或筛选器自有计算字段被误判为无效绑定的问题。
+- 自动关联卡片可接收筛选条件，页面联动结果更符合实际配置。
+- 支持企业 OIDC 认证上下文，并同步升级底层请求兼容能力。
+
+## @guandata/guanvis 0.1.40 - 2026-08-20
+
+- 完善自定义图表布局与视觉验收指引：使用结构化布局和运行时实测保证对齐，并明确避免通过像素解析做几何量化。
+
 ## @guandata/guanvis 0.1.39 - 2026-08-20
 
 - 修复 `attachCard` 场景下计算字段的序列化问题，减少附加卡片发布/导出时字段配置异常的情况。

package/README.md

@@ -55,6 +55,17 @@ guanvis publish ./my_dashboard/ --allow-overwrite
 
 ## 版本更新
 
+### @guandata/guanvis 0.1.41
+
+- 新增页面目录创建、改名、移动和删除，以及页面删除、改名和移动能力。
+- 发布时可指定页面目标目录，并拦截仍含生成器占位符的项目。
+- 修复自有计算字段误判，自动关联卡片可正确接收筛选条件。
+- 支持企业 OIDC 认证上下文，并升级底层请求兼容能力。
+
+### @guandata/guanvis 0.1.40
+
+- 完善自定义图表布局与视觉验收指引，减少依赖手工数值微调造成的反复发布验证。
+
 ### @guandata/guanvis 0.1.39
 
 - 修复 `attachCard` 计算字段序列化问题，减少附加卡片配置异常。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guanvis",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "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."
 ---
 
@@ -28,10 +28,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` / `guanvis page move`，都保留 pgId、都不需要 `--yes`），要改页面名或挪页面位置一律用它们，**不必也不允许**"删掉页面再发一个新的"——重发拿到的是新 pgId，而 `guanvis page delete` 是软删且 CLI 没有恢复命令，删错只能人工去 BI 网页端回收站还原。**页面目录**同样已有原地能力（`guanvis dir rename` / `guanvis dir move`），要改目录名或挪目录位置一律用它们，不要"新建目录 + 逐个搬页面 + 删旧目录"。各资源的原地更新入口见下方「编辑红线速查」。分流决策见 `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,7 +62,7 @@ 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 用环境变量
+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
 16. **描述维护**：仅修复已发布资源描述时保留原 ID，用 `guanvis card/page set-description`；本地有 JS 工程时同步更新 `.setDescription(...)`
 17. **主题切换**：用户描述风格 → 工程目录里 `guanvis theme preference --keywords "..." --sync`；不要选租户默认"浅色"/"深色"，没有合适主题就保持/清空偏好用内置"简约"兜底；改版未提风格时普通工程由 `.applied.json` 继承上次主题，checkout 工程按 Page base 保留线上主题。多子目录工程主题按子目录独立配置和执行；详见 `references/theme.md`
@@ -63,7 +72,7 @@ compatibility: "Requires Node.js 14+. Install via npm link --foreground-scripts
 21. **布局组件**：AreaTitle/CardGroup/SelGroup/Tab 只支持放画布根布局、不支持嵌套组合；SelGroup 内只能放 selector；详见 `references/builder-reference.md`
 22. **资源包/checkout JSON 禁止手改**：只改 DSL 源文件，不改 ZIP 内部文件与 `.guanvis/**` JSON；批量重绑、迁移页面等需求先讨论方案，必要时扩展 DSL，不手工改生成物。
 23. **动态字段**：用户明确需要字段切换时用 `.addDynamicRow()` / `.addDynamicMetric()` 等（普通卡动态维度/数值，指标卡动态维度/指标）；细节见 `references/builder-reference.md`。
-24. **自定义图表（HTML/CSS/JS 自绘）**：内置图表满足不了的可视化才走 `createCustomChart()`。子类型选型：纯 ECharts 配置能画 → `CustomChartSubType.ECHARTS_LITE`（脚本给 `option` 赋值，禁用 `GDPlugin`）；需要自定义 DOM/CSS 布局或第三方库（节点图、进度轴、Vega 等）→ `CustomChartSubType.SDK`（`charts/<name>.{html,css,js}` 三件套 + `loadContent("charts/<name>")`，js 里实现 `renderChart(data, clickFunc, config)` 并 `new GDPlugin().init(renderChart)`）。数据用 `.addDataView(createCard(ChartType.DATA_GRID, ...))` 传入。最小可运行工程直接抄 `evals/custom_chart_sdk/`（SDK）或 `evals/custom_chart_echarts/`（ECHARTS_LITE）。**视觉验收**：preview 只校验结构不渲染 HTML/CSS，本地 file:// 打开也不可靠——正确闭环是发布（可先发到测试目录）后 `guanvis screenshot <pgId>` 读图确认（这是总则"screenshot 不作默认闭环"的例外：自定义图表视觉由手写 HTML/CSS 决定，结构回读覆盖不到）；模型不支持图像理解时，改为把 publish 成功后输出的 `Page URL` 交给用户人工确认。不要浪费时间做本地渲染验证。完整 API 见 `references/builder-reference.md` 的 CustomChartBuilder 章节。
+24. **自定义图表（HTML/CSS/JS 自绘）**：内置图表满足不了的可视化才走 `createCustomChart()`。子类型选型：纯 ECharts 配置能画 → `CustomChartSubType.ECHARTS_LITE`（脚本给 `option` 赋值，禁用 `GDPlugin`）；需要自定义 DOM/CSS 布局或第三方库（节点图、进度轴、Vega 等）→ `CustomChartSubType.SDK`（`charts/<name>.{html,css,js}` 三件套 + `loadContent("charts/<name>")`，js 里实现 `renderChart(data, clickFunc, config)` 并 `new GDPlugin().init(renderChart)`）。数据用 `.addDataView(createCard(ChartType.DATA_GRID, ...))` 传入。最小可运行工程直接抄 `evals/custom_chart_sdk/`（SDK）或 `evals/custom_chart_echarts/`（ECHARTS_LITE）。**布局写法**：对齐/等比类要求用结构性保证而非数值手调——固定尺寸容器 + flex 居中让几何天然成立，关键坐标（如贯穿线端点）在渲染 JS 里 `getBoundingClientRect()` 实测反写并挂 resize 重算；手调 top/margin 意味着每发布一次才能验一次。**视觉验收**：preview 只校验结构不渲染 HTML/CSS，本地 file:// 打开也不可靠——正确闭环是发布（可先发到测试目录）后 `guanvis screenshot <pgId>` 读图确认（这是总则"screenshot 不作默认闭环"的例外：自定义图表视觉由手写 HTML/CSS 决定，结构回读覆盖不到）；读图判断即可，不要解析 PNG 像素做几何量化，也不要为验收安装图像处理依赖；模型不支持图像理解时，改为把 publish 成功后输出的 `Page URL` 交给用户人工确认。不要浪费时间做本地渲染验证。完整 API 见 `references/builder-reference.md` 的 CustomChartBuilder 章节。
 25. **复杂报表 Pro**：非默认功能，需单独授权——只有用户明确点名"复杂报表 / 复杂报表 Pro"或被修改卡片已是 Pro 才选 Pro；用户只说"表格/报表/透视表"一律用原生卡片（DATA_GRID/PIVOT_TABLE 等），版式做不到时告知"Pro 可实现但需授权"由用户决定。动手前必读 `references/complex-report-pro-patterns.md`（§0 选型、§2 配方、§3 数据视图规则、§4 报错修复、§5 编辑闭环、§6 验证闭环），全部结构红线与修复表以该文件为准；工作流程见下文「复杂报表 Pro 工作方式」
 
 ## 何时使用
@@ -72,6 +81,8 @@ 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 网页端回收站还原。
 - 用户提到 `card.js`、`page.js`、CardPayload、图表类型、zone spec、筛选器联动。
 
 ## 固定工作方式
@@ -189,9 +200,26 @@ 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
 
+# 页面目录（增删改；查看目录树用 guancli page tree --type dir）
+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 网页端在回收站里还原
+
 # 修复已发布资源描述（保留原 ID；本地有 JS 工程时同步更新 .setDescription(...)）
 guanvis card set-description <cd_id> --description "..."   # 或 --file ./story.md
 guanvis page set-description <pg_id> --description "..."   # 支持 --visible=false
@@ -220,6 +248,51 @@ guanvis icon list --group default_line -f json
 
 **线上仪表板更新红线**：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 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`，并确认没顺带改掉另一个字段），回读不一致一律判为失败。
+
 ## 复杂报表 Pro 工作方式
 
 **进入前提**：用户明确点名"复杂报表 / 复杂报表 Pro"，或 checkout 的目标卡片已是 Pro（未点名的表格/报表需求回「固定工作方式」用原生卡片）。只支持 `COMPLEX_REPORT_PRO`，旧版复杂报表拒绝并建议外部迁移后新建 Pro。

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. 发布：覆盖确认、备份与"另存新版本"