@guandata/guanvis 0.1.33 → 0.1.34

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## @guandata/guanvis 0.1.34 - 2026-07-25
+
+- 预览默认返回精简摘要，并把完整结果保存到工程目录，复杂仪表板的校验结论更容易查看；依赖旧版完整输出的脚本可使用 `--full`。
+- 发布成功后可直接返回页面访问地址，并增强临时目录缺失场景的兼容性。
+- 必填筛选器会保留不可清空设置，避免发布后出现无效的清空操作。
+- 优化 Agent 发布流程和内置主题提示，减少重复操作与无效排查。
+
 ## @guandata/guanvis 0.1.33 - 2026-07-23
 
 - 指标图表支持主次指标组和数字分组，可构建层次更清晰的指标展示。

package/README.md

@@ -24,9 +24,12 @@ guanvis gen-layout-id cardGroup
 # 初始化：从 BI 获取数据集结构
 guanvis init <dsId> -d ./my_dashboard/
 
-# 预览生成结果（JSON 输出）
+# 预览生成结果（默认输出摘要，完整结果写入工程目录的 .preview.json）
 guanvis preview ./my_dashboard/
 
+# 兼容旧版：完整结果输出到终端
+guanvis preview ./my_dashboard/ --full
+
 # 打包为 ZIP 资源包
 guanvis pack ./my_dashboard/
 
@@ -51,6 +54,13 @@ guanvis publish ./my_dashboard/ --allow-overwrite
 
 ## 版本更新
 
+### @guandata/guanvis 0.1.34
+
+- 预览默认返回精简摘要，并把完整结果保存到工程目录，复杂仪表板的校验结论更容易查看；依赖旧版完整输出的脚本可使用 `--full`。
+- 发布成功后可直接返回页面访问地址，并增强临时目录缺失场景的兼容性。
+- 必填筛选器会保留不可清空设置，避免发布后出现无效的清空操作。
+- 优化 Agent 发布流程和内置主题提示，减少重复操作与无效排查。
+
 ### @guandata/guanvis 0.1.33
 
 - 指标图表支持主次指标组和数字分组，可构建层次更清晰的指标展示。

package/package.json

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

package/skills/guanvis/SKILL.md

@@ -19,7 +19,7 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 
 - `schema.js` 是由 `init` / `checkout` 生成的数据集事实快照，不手改；数据集字段变化时重新运行对应命令。`metrics.js` 是由 `metric-init` 生成的指标事实快照，不手改；指标口径、适用维度或格式变化时重新运行 `metric-init`。
 - 全局参数先用 `guanvis parameter` 创建或复用，再通过 `dynamic-parameters.js` 按 `dpId` 引用；`pack`/`publish` 不会隐式写入参数。创建前必须按名称查询；若系统已有同名有效参数，立即停止并让用户明确选择“更新已有参数”或“换名创建”，不得自动复用或修改。只有用户明确选择更新后，才可按该参数的 `dpId` 执行 `update`。
-- `card_*.js`、`selector_*.js`、`page.js` 是可编辑源文件；`*_package.zip`、preview JSON、publish 后线上资源都是派生产物。
+- `card_*.js`、`selector_*.js`、`page.js` 是可编辑源文件；`*_package.zip`、`.preview.json`（preview 落盘的全量 payload）、publish 后线上资源都是派生产物，不要手工编辑。
 - **Page 归属红线**：任何包含 Card 或 Selector 的资源包都必须同时包含 Page，且包内每个 Card/Selector 都必须被至少一个 Page 引用。禁止发布只有 Card/Selector、没有 Page 的资源包，也禁止留下未放入任何 Page 的 Card/Selector；否则后端会产生 `pg_id` 为空、无法访问且可能阻塞后续页面发布的孤儿卡片。校验失败时在 `page.js` 中放置对应资源，再将 Page 与 Card/Selector 同包 `pack`/`publish`。
 - 已有线上仪表板用 `guanvis checkout <pgId> -d <dir>` 拉成可编辑工程：checkout 会尽量生成 `schema.js`，但数据集无权限/已删除/跨环境残留时只 warning 并继续生成可编辑工程；普通 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 直接拒绝；Page 生成 `createPage(...).setBasePath(...).placeCard("cdId", ...)` 脚本，尽量反编译根布局里的 Tab/CardGroup/AreaTitle/SelGroup 和快捷筛选组，并保留 parentDirId。checkout 工程只用于修改指定 Page，不用于复制新 Page；遇到嵌套布局组件等当前 DSL 不能安全表达的结构，checkout 会直接失败，不生成会清结构的工程。只支持普通仪表板（pgType=PAGE），自助取数/数据大屏/清单页等特殊页面会在 checkout 入口直接报错。
 - **Checkout 账号要求**：checkout 读到的是"当前账号视角"的卡片定义，publish 会把它整体回写。必须用对页面涉及数据集拥有**完整列权限、无脱敏限制**的账号（推荐资源 owner 或管理员）执行 checkout/publish，否则读接口会按该账号权限裁剪 zone 字段/脱敏字段，回写后这些字段会从线上卡片中永久丢失。租户启用多语言时，操作账号语言应与卡片原始语言一致，避免把翻译后的字段显示名固化回卡片。
@@ -28,7 +28,7 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 - 写脚本前先形成 dashboard contract：目标用户、业务问题、使用的数据集、核心指标、维度拆解、筛选器、页面结构和验证方式。
 - 每次生成都针对明确目录或明确子目录；不要把 unrelated 示例、旧包或临时 ZIP 混入同一个发布目标。
 - Card/Page/Selector 的 `.setId(...)` 建议使用 `guanvis genid` 生成（保证字母开头）。数字开头的 24 位 ID 会让 BI 前端把 ID 拼成 CSS selector（如 `#5bef...`）时触发 `querySelector` 语法错误，`preview`/`pack`/`publish` 会对**新建资源**直接报 error 拦截；checkout/attach 的已有线上资源不受此限制（保留原 ID 原地更新）。
-- 先 `preview/pack` 做本地结构验证，再 `publish/upload`；修改已发布资源前先判断变更类型：仅修复 Card/Page 描述时应保留原资源 ID，使用 `card/page set-description` 并同步维护 JS 中的 `.setDescription(...)`；调整图表、布局、筛选器、字段等看板内容时，按线上仪表板更新策略处理。
+- 先 `preview` 做本地结构验证，再 `publish`（publish 自带构建打包上传，**发布前不需要单独 `pack`**；`pack` 只用于生成离线 ZIP 交付物走 `upload`）；修改已发布资源前先判断变更类型：仅修复 Card/Page 描述时应保留原资源 ID，使用 `card/page set-description` 并同步维护 JS 中的 `.setDescription(...)`；调整图表、布局、筛选器、字段等看板内容时，按线上仪表板更新策略处理。
 - **编辑红线（编辑 ≠ 删除重建）**：用户要求修改/改名已发布 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 无法迁移。需要"保留旧页面、出一个新版本"时用 `guanvis page save-as`。全局参数编辑同理：只能 `parameter update <dpId>` 原地更新，禁止 delete 后重建同名参数（dpId 变化会让所有引用它的卡片/筛选器断链）；`parameter delete` 只用于用户明确要求删除参数本身。
 - **资源包安全红线**：Agent 只编辑 DSL 源文件；资源包 ZIP 是 `guanvis pack/publish` 的派生产物，不手工生成、解包修改或重打包。`guanvis upload` 只允许上传 `guanvis pack` 原样生成的 ZIP。若用户要求批量重绑资源、迁移已有页面或复用线上页面结构，先停下来说明风险并确认方案，不要直接改 ZIP。
 - 发布后优先用 `guancli page get/card get` 回读结构与配置。只有在明确需要视觉质量判断、且当前大模型支持图像理解时，才使用 `guanvis screenshot <pageId>` 生成 PNG 并交给模型分析；不要把截图作为默认闭环步骤，因为图像理解会额外消耗 token/费用。
@@ -305,7 +305,8 @@ guanvis checkout <pageId> -d ./existing_dashboard
 # 若 schema.js 未生成或缺字段，后续可手动 guanvis init <dsId> -d ./existing_dashboard --force 补齐
 # checkout --overwrite 会清理输出目录下所有根级 .js 和旧 .guanvis，避免 schema/selector/metrics/other.js 残留混入运行
 
-# 预览生成结果（JSON 输出到 stdout，含 payload 验证，用于调试）
+# 预览生成结果（默认输出摘要 JSON：卡片/页面清单 + changeSummary + 验证状态；
+# 全量 payload 写入工程目录 .preview.json，需要时用 read_file 按需查看，或加 --full 全量输出）
 guanvis preview ./my_dashboard/
 # checkout/attach 工程的路径级变更摘要（也会出现在 preview JSON 的 changeSummary 中）
 guanvis diff ./existing_dashboard/

package/skills/guanvis/references/theme.md

@@ -14,7 +14,7 @@ AI 选择主题时不要把租户主题列表里的默认“浅色”/“深色
 - `keywords` 在 `.index.json` 上没有任何命中
 - `.applied.json` 引用的 `themeId` 本地快照已被删除（applied 步骤**只读本地、不再发起 sync**）
 
-执行命令时 stderr 会打印决策结果。命中线上主题时形如 `Theme: <name> [<id>] (source=preference|applied)`；落到自带兜底时形如 `Theme: 简约 (source=fallback, built-in simple.json)`，特意不打印 themeId 是因为那只是 skill 与 BI 默认值对齐的实现细节，不是租户主题列表里能查到的 ID。fallback 横幅只在 `pack`/`publish` 打印；`preview`/`diff` 是高频只读命令，落到兜底时不再重复打印（命中真实主题时仍会打印）。
+执行命令时 stderr 会打印决策结果。命中线上主题时形如 `Theme: <name> [<id>] (source=preference|applied)`；落到自带兜底时形如 `Theme: 简约 (source=built-in simple.json)`（内置默认与 BI 默认主题对齐，属正常行为而非降级），特意不打印 themeId 是因为那只是 skill 与 BI 默认值对齐的实现细节，不是租户主题列表里能查到的 ID。built-in 横幅只在 `pack`/`publish` 打印；`preview`/`diff` 是高频只读命令，落到兜底时不再重复打印（命中真实主题时仍会打印）。
 
 普通数据集图表和指标平台 MetricChart 都会应用主题视觉配置。MetricChart 只注入 `settings` 与 `meta.chartMain.props`：透视表补表格/合计样式，柱线饼等补坐标轴、图例、数据标签和主题色；不会修改 `zoneData`、`dsInfo`、`defaultView` 等查询相关字段。
 
@@ -70,7 +70,7 @@ AI 选择主题时不要把租户主题列表里的默认“浅色”/“深色
 
 - `theme show` 打印当前决策（`source` / `themeId` / `themeName` / `themeType`），只读。
 - `theme list` 列出 `.index.json` 中候选；`.index.json` 缺失时提示先 `sync`。
-- 看到 `Theme: 简约 (source=fallback, built-in simple.json)` 但用户期望非简约：检查 `.preference.json` 是否写好、对应 `themes/<id>.json` 是否存在；如果是 keywords 路径，跑 `theme list` 看候选名字是否真的包含关键词；联网命令还要看 stderr 是否打印了 `theme: sync failed: ...`。
+- 看到 `Theme: 简约 (source=built-in simple.json)` 但用户期望非简约：检查 `.preference.json` 是否写好、对应 `themes/<id>.json` 是否存在；如果是 keywords 路径，跑 `theme list` 看候选名字是否真的包含关键词；联网命令还要看 stderr 是否打印了 `theme: sync failed: ...`。
 - 看到 `multi-subdir project under <root> contains per-subdir themes/ in [...]`：你在多子目录工程的**根目录**直接跑了 preview/pack/publish，但子目录里有自己的 `themes/`。按提示 `cd` 进每个子目录单独执行；或如果不想用各子目录的主题，删除子目录下的 `themes/` 后再回到根目录运行。
 
 ## 设计规则

package/skills/guanvis/references/troubleshooting.md

@@ -14,7 +14,7 @@
 | `placeCard index out of range` | placeCard 的 cardIndex 超出已注册卡片数量 | 检查 registerCard/registerTextCard 的调用顺序和总数 |
 | `page has no cards` | page.js 中没有 placeCard | 确保 page.js 中为每个已注册的卡片调用了 placeCard |
 | `selector not linked to any card` | selector 没有调用 linkTo/linkToAll | 添加 `.linkToAll()` 或 `.linkTo(cardIndex)` |
-| `Theme: 简约 (source=fallback, built-in simple.json)` 但用户要求别的风格 | 偏好缺失 / themeId 在环境中不存在 / sync 失败 / keywords 没命中 | `theme list` 看候选 → `theme preference --theme-id ...` 或 `--keywords ... --sync`；联网命令注意 stderr 是否有 `theme: sync failed: ...` |
+| `Theme: 简约 (source=built-in simple.json)` 但用户要求别的风格 | 偏好缺失 / themeId 在环境中不存在 / sync 失败 / keywords 没命中 | `theme list` 看候选 → `theme preference --theme-id ...` 或 `--keywords ... --sync`；联网命令注意 stderr 是否有 `theme: sync failed: ...` |
 | publish 后 `.applied.json` 没更新 | 本次实际用的就是 skill 自带 `simple.json`（按设计 fallback 不写 applied） | 检查 stderr 的 `theme: ... falling back ...` 警告；确保对应 `themes/<id>.json` 存在或先 `theme sync` |
 | `invalid themeId "..." (...)` | themeId 不是合法的单段文件名（见 `publish-and-constraints.md` 中的约束） | 使用 `theme list` 里出现的 id；避免 `/`、`\`、`..`；或用 `theme preference --keywords` |
 | `theme: keywords "..." matched no theme` | 关键词与候选 themeName 没有公共子串 | `theme list` 核对候选名字；调整 keywords，或换成 `--theme-id` |