@guandata/guanvis 0.1.28 → 0.1.30

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## @guandata/guanvis 0.1.30 - 2026-07-08
+
+- 支持 checkout 线上页面到本地工程，并增强已有仪表板的编辑、差异查看和回写流程。
+- 支持动态维度、动态指标和拆分图表相关构建能力，提升复杂图表生成覆盖面。
+- 新增筛选器分组和开关类检查能力，页面交互配置更容易验证。
+- `pack` / `preview` / `lint` 诊断增强，可提前发现资源 ID、布局、联动和覆盖相关问题。
+
+## @guandata/guanvis 0.1.29 - 2026-07-01
+
+- 支持筛选器级联联动，页面中的筛选器可以按上游筛选结果继续约束下游筛选项。
+- 画布布局支持放置筛选器，复杂仪表板可把筛选器和图表一起纳入布局管理。
+- 自定义图表的数据视图可作为点击联动来源，并支持页面筛选器过滤自定义图表。
+- 表格卡片支持只配置维度字段，`init` 支持多数据集页面中的数据集别名，降低多数据集页面配置成本。
+- 比较卡支持本期/对比期输出，发布覆盖保护可识别并修复异常线上资源，必要时可跳过覆盖备份。
+
 ## @guandata/guanvis 0.1.28 - 2026-06-24
 
 - 修复自定义图表重复生成数据视图卡片的问题，减少资源包中的冗余或冲突配置。

package/LICENSE

@@ -0,0 +1,133 @@
+Guandata Developer Tools Free Evaluation License
+
+Copyright (c) Hangzhou Guandata Co., Ltd.
+
+This software and its related source code, documentation, examples, packages,
+configuration files, command-line tools, MCP servers, SDKs, plugins, and tool
+integrations are proprietary software of Hangzhou Guandata Co., Ltd. or its
+licensors.
+
+This license applies to Guandata developer tools, including but not limited to
+Guandata CLI, Guandata MCP Server, related npm packages, source code,
+documentation, examples, configuration files, and tool integrations.
+
+1. Free Personal Evaluation Use
+
+Hangzhou Guandata Co., Ltd. grants you a limited, non-exclusive,
+non-transferable, revocable license to use this software free of charge solely
+for personal learning, local testing, technical evaluation, and non-production
+experiments.
+
+This free license does not permit enterprise, commercial, production, internal
+business, team, organizational, hosted, customer-facing, or revenue-generating
+use.
+
+2. Enterprise and Commercial Use
+
+Any use by or for a company, organization, institution, government entity, team,
+client, or other non-individual entity requires a separate commercial license
+from Hangzhou Guandata Co., Ltd.
+
+Enterprise or commercial use includes, but is not limited to:
+
+- use in production, staging, shared, or hosted environments;
+- use for internal business operations or automated business workflows;
+- use by employees, contractors, consultants, service providers, or
+  representatives on behalf of an organization;
+- integration into commercial products, services, platforms, workflows, AI
+  agents, MCP clients, or customer deliverables;
+- connection to, access to, processing of, exposure of, or operation on
+  enterprise data, business systems, customer data, or production data;
+- redistribution, hosting, resale, sublicensing, or provision of this software
+  as part of a paid or unpaid service.
+
+To obtain an enterprise or commercial license, please contact Hangzhou Guandata
+Co., Ltd. through its official sales, support, or business channels.
+
+3. MCP Server and Agent Integration
+
+For Guandata MCP Server or any MCP-compatible tool integration, the free license
+is limited to local personal testing, learning, and non-production evaluation.
+
+The free license does not permit use of the MCP Server in enterprise agent
+platforms, production AI applications, shared team environments,
+customer-facing systems, hosted services, automated business workflows, or
+integrations that access, process, expose, or operate on enterprise data.
+
+Any organizational, commercial, hosted, production, or data-connected use of the
+MCP Server requires a separate commercial license from Hangzhou Guandata Co., Ltd.
+
+4. Restrictions
+
+Unless expressly permitted by this license, reasonably necessary to install and
+use the software as allowed by this license, or expressly permitted by a
+separate written agreement with Hangzhou Guandata Co., Ltd., you may not:
+
+- copy, distribute, sublicense, sell, lease, host, or provide this software to
+  third parties;
+- modify, adapt, translate, create derivative works of, or otherwise alter this
+  software;
+- reverse engineer, decompile, disassemble, or attempt to derive the source
+  code, structure, sequence, organization, or underlying ideas of this software,
+  except to the extent such restriction is prohibited by applicable law;
+- remove or alter copyright, trademark, license, or proprietary notices;
+- use Guandata names, logos, trademarks, product names, or brand assets without
+  permission;
+- use this software in violation of applicable laws, regulations, or third-party
+  rights;
+- circumvent license, access control, usage limitation, telemetry, audit, or
+  security mechanisms, if any.
+
+5. Ownership
+
+Hangzhou Guandata Co., Ltd. and its licensors retain all rights, title, and
+interest in and to this software. No rights are granted except as expressly
+stated in this license.
+
+6. Third-Party Components
+
+Third-party open source components, if any, are licensed under their respective
+licenses. This license applies only to software owned by Hangzhou Guandata Co., Ltd.
+and does not modify any third-party license terms.
+
+7. No Warranty
+
+This software is provided "as is" and "as available", without warranties of any
+kind, whether express, implied, statutory, or otherwise, including but not
+limited to warranties of merchantability, fitness for a particular purpose,
+accuracy, availability, security, and non-infringement.
+
+8. Limitation of Liability
+
+To the maximum extent permitted by applicable law, Hangzhou Guandata Co., Ltd.
+shall not be liable for any indirect, incidental, special, consequential,
+exemplary, or punitive damages, or for any loss of profits, revenue, data,
+goodwill, business opportunity, or business interruption arising from or related
+to this software, even if Hangzhou Guandata Co., Ltd. has been advised of the
+possibility of such damages.
+
+9. Termination
+
+Your rights under this license terminate automatically if you violate any term of
+this license. Upon termination, you must stop using the software and delete all
+copies in your possession or control.
+
+10. Governing Law and Dispute Resolution
+
+This license shall be governed by the laws of the People's Republic of China,
+without regard to its conflict of laws principles.
+
+Any dispute arising from or related to this license or the software shall be
+submitted to the competent court with jurisdiction in Hangzhou, Zhejiang
+Province, China, unless otherwise required by applicable law.
+
+11. Contact
+
+For enterprise licensing, commercial authorization, partnership, procurement, or
+other questions, please contact Hangzhou Guandata Co., Ltd. through its official
+website or official business channels.
+
+12. Language
+
+If this license is provided in multiple languages, the English version controls
+unless Hangzhou Guandata Co., Ltd. expressly states otherwise in writing.

package/LICENSE.zh-CN

@@ -0,0 +1,82 @@
+观远开发者工具免费评估许可协议
+
+版权所有 (c) 杭州观远数据有限公司。
+
+本软件及其相关源代码、文档、示例、软件包、配置文件、命令行工具、MCP Server、SDK、插件和工具集成，属于杭州观远数据有限公司或其授权方的专有软件。
+
+本协议适用于观远开发者工具，包括但不限于观远 CLI、观远 MCP Server、相关 npm 包、源代码、文档、示例、配置文件和工具集成。
+
+1. 免费个人评估使用
+
+杭州观远数据有限公司授予你一项有限的、非独占的、不可转让的、可撤销的许可，允许你免费使用本软件，但仅限于个人学习、本地测试、技术评估和非生产环境实验。
+
+本免费许可不允许企业使用、商业使用、生产环境使用、内部业务使用、团队使用、组织使用、托管使用、面向客户的使用，或任何直接或间接产生商业收益的使用。
+
+2. 企业及商业使用
+
+任何由公司、组织、机构、政府单位、团队、客户或其他非个人主体进行的使用，或代表上述主体进行的使用，均需事先取得杭州观远数据有限公司的单独商业授权。
+
+企业或商业使用包括但不限于：
+
+- 在生产环境、预发布环境、共享环境或托管环境中使用；
+- 用于内部业务运营或自动化业务流程；
+- 由员工、承包商、顾问、服务商或代理人代表组织使用；
+- 集成到商业产品、服务、平台、工作流、AI 智能体、MCP 客户端或客户交付物中；
+- 连接、访问、处理、暴露或操作企业数据、业务系统、客户数据或生产数据；
+- 对本软件进行分发、托管、转售、再许可，或作为任何付费或免费的服务的一部分提供。
+
+如需企业或商业授权，请通过观远官方销售、支持或商务渠道联系杭州观远数据有限公司。
+
+3. MCP Server 与智能体集成
+
+对于观远 MCP Server 或任何兼容 MCP 的工具集成，免费许可仅限于个人本地测试、学习和非生产环境评估。
+
+免费许可不允许将 MCP Server 用于企业级智能体平台、生产环境 AI 应用、团队共享环境、面向客户的系统、托管服务、自动化业务流程，或任何访问、处理、暴露、操作企业数据的集成场景。
+
+任何组织用途、商业用途、托管用途、生产用途，或涉及企业数据连接的 MCP Server 使用，均需取得杭州观远数据有限公司的单独商业授权。
+
+4. 限制
+
+除非本协议明确允许、为按照本协议安装和使用本软件所合理必需，或杭州观远数据有限公司通过单独书面协议明确允许，你不得：
+
+- 复制、分发、再许可、销售、出租、托管本软件，或向第三方提供本软件；
+- 修改、改编、翻译本软件，创作本软件的衍生作品，或以其他方式变更本软件；
+- 对本软件进行反向工程、反编译、反汇编，或试图获取本软件的源代码、结构、顺序、组织方式或底层思想，但适用法律禁止限制的情形除外；
+- 删除或修改版权、商标、许可或专有权利声明；
+- 未经许可使用杭州观远数据有限公司或观远品牌的名称、标识、商标、产品名称或品牌资产；
+- 以违反适用法律法规或第三方权利的方式使用本软件；
+- 绕过任何许可、访问控制、使用限制、遥测、审计或安全机制。
+
+5. 权利归属
+
+本软件的所有权利、所有权和利益均归杭州观远数据有限公司及其授权方所有。除本协议明确授予的权利外，不授予任何其他权利。
+
+6. 第三方组件
+
+本软件中如包含第三方开源组件，该等组件适用其各自的许可协议。本协议仅适用于杭州观远数据有限公司拥有权利的软件部分，并不修改任何第三方许可条款。
+
+7. 无担保
+
+本软件按“现状”和“现有”基础提供，不作任何明示、默示、法定或其他形式的担保，包括但不限于适销性、特定用途适用性、准确性、可用性、安全性和不侵权担保。
+
+8. 责任限制
+
+在适用法律允许的最大范围内，杭州观远数据有限公司不对因本软件引起或与本软件相关的任何间接、附带、特殊、后果性、惩罚性或惩戒性损害承担责任，也不对利润、收入、数据、商誉、商业机会损失或业务中断承担责任，即使杭州观远数据有限公司已被告知可能发生该等损害。
+
+9. 终止
+
+如果你违反本协议的任何条款，你在本协议项下的权利将自动终止。终止后，你必须停止使用本软件，并删除你持有或控制的所有副本。
+
+10. 适用法律与争议解决
+
+本协议适用中华人民共和国法律，但不包括其冲突法规则。
+
+因本协议或本软件引起或与之相关的任何争议，应提交中国浙江省杭州市有管辖权的人民法院解决，除非适用法律另有强制性规定。
+
+11. 联系方式
+
+如需企业授权、商业许可、合作、采购或有其他问题，请通过观远官方网站或官方商务渠道联系杭州观远数据有限公司。
+
+12. 语言
+
+如本协议提供多个语言版本，除非杭州观远数据有限公司另有明确书面说明，以英文版本为准。

package/README.md

@@ -51,6 +51,21 @@ guanvis publish ./my_dashboard/ --allow-overwrite
 
 ## 版本更新
 
+### @guandata/guanvis 0.1.30
+
+- 支持 checkout 线上页面到本地工程，并增强已有仪表板的编辑、差异查看和回写流程。
+- 支持动态维度、动态指标和拆分图表相关构建能力，提升复杂图表生成覆盖面。
+- 新增筛选器分组和开关类检查能力，页面交互配置更容易验证。
+- `pack` / `preview` / `lint` 诊断增强，可提前发现资源 ID、布局、联动和覆盖相关问题。
+
+### @guandata/guanvis 0.1.29
+
+- 支持筛选器级联联动，页面中的筛选器可以按上游筛选结果继续约束下游筛选项。
+- 画布布局支持放置筛选器，复杂仪表板可把筛选器和图表一起纳入布局管理。
+- 自定义图表的数据视图可作为点击联动来源，并支持页面筛选器过滤自定义图表。
+- 表格卡片支持只配置维度字段，`init` 支持多数据集页面中的数据集别名，降低多数据集页面配置成本。
+- 比较卡支持本期/对比期输出，发布覆盖保护可识别并修复异常线上资源，必要时可跳过覆盖备份。
+
 ### @guandata/guanvis 0.1.28
 
 - 修复自定义图表重复生成数据视图卡片的问题，减少资源包中的冗余或冲突配置。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guanvis",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "观远 BI Card/Page 生成工具 - 通过 JS DSL 创建图表和仪表板",
   "bin": {
     "guanvis": "bin/run.js"
@@ -17,6 +17,8 @@
     "binaries/",
     "skills/",
     "CHANGELOG.md",
+    "LICENSE",
+    "LICENSE.zh-CN",
     "README.md"
   ],
   "keywords": [
@@ -27,7 +29,7 @@
     "cli",
     "agent-skill"
   ],
-  "license": "UNLICENSED",
+  "license": "SEE LICENSE IN LICENSE",
   "os": [
     "darwin",
     "linux",

package/skills/guanvis/SKILL.md

@@ -9,7 +9,7 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 这是一个执行型 skill，用于通过 AI 生成的 JS 脚本创建 BI Card 和 Page 资源。
 
 - AI 生成 `card_*.js` 定义各个 Card 图表；`page.js` 将多个 Card 组装成仪表板。
-- `schema.js` 由 `init` 命令自动生成，定义数据集字段信息（不允许 AI 修改）；指标卡片使用 `metric-init` 生成 `metrics.js`。
+- `schema.js` 由 `init` 或 `checkout` 命令生成，定义数据集字段信息（不允许 AI 修改）；checkout 生成 schema 是 best-effort，失败不会阻断 checkout。指标卡片使用 `metric-init` 生成 `metrics.js`。
 - 框架内置验证规则，在 pack/publish 时检查字段数量、zone 兼容性、必填字段等。
 - 认证通过 `guancli` 共享配置自动获取。
 
@@ -17,8 +17,10 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 
 把可视化生成当作源文件驱动的构建流程：本地 JS DSL 是可编辑事实源，payload、ZIP、线上 Card/Page 都是从源文件生成的派生产物。
 
-- `schema.js` 是由 `init` 生成的数据集事实快照，不手改；数据集字段变化时重新运行 `init`。`metrics.js` 是由 `metric-init` 生成的指标事实快照，不手改；指标口径、适用维度或格式变化时重新运行 `metric-init`。
+- `schema.js` 是由 `init` / `checkout` 生成的数据集事实快照，不手改；数据集字段变化时重新运行对应命令。`metrics.js` 是由 `metric-init` 生成的指标事实快照，不手改；指标口径、适用维度或格式变化时重新运行 `metric-init`。
 - `card_*.js`、`selector_*.js`、`page.js` 是可编辑源文件；`*_package.zip`、preview JSON、publish 后线上资源都是派生产物。
+- 已有线上仪表板用 `guanvis checkout <pgId> -d <dir>` 拉成可编辑工程：checkout 会尽量生成 `schema.js`，但数据集无权限/已删除/跨环境残留时只 warning 并继续生成可编辑工程；Card 用 `attachCard(cdId, ".guanvis/base/cards/<cdId>.json")` 接受线上 JSON 作为基线；Page 生成 `createPage(...).setBasePath(...).placeCard("cdId", ...)` 脚本，尽量反编译根布局里的 Tab/CardGroup/AreaTitle/SelGroup 和快捷筛选组，并保留 parentDirId。checkout 工程只用于修改指定 Page，不用于复制新 Page；遇到嵌套布局组件等当前 DSL 不能安全表达的结构，checkout 会直接失败，不生成会清结构的工程。
+- **Checkout JSON 红线**：`.guanvis/raw/**`、`.guanvis/base/**`、`.guanvis/manifest.json` 是 checkout 生成物和只读快照，不是可编辑源文件。Agent 不得修改这些 JSON，也不得复制一份 checkout JSON 后改副本来创建新资源；`attachCard(cardId, jsonPath)` 只能引用 manifest 记录的原始 base-card，且 `cardId` 必须与该 JSON 的资源 ID 一致。现有卡片修改必须通过 `attachCard(...).setName()/updateMetric()/addMetric()/removeMetric()/addLink()` 等 DSL 操作表达；字段整体重建才用 `setRows()` / `setMetrics()`，这些整 zone 替换会触发 warning，默认应优先用 `update*/patch*/add*/remove*/move*`。Page 快捷筛选区修改用 `createPage(...).setBasePath(...).setFilterLayout()/clearFilterLayout()/addFilterLayoutItem()/insertFilterSelector()/removeFilterSelector()/moveFilterSelector()` 表达；筛选器在快捷筛选区和画布之间移动时优先用 `moveFilterSelectorToCanvas()` / `moveCanvasSelectorToFilter()`，筛选器组用 `moveSelectorGroupToCanvas()` / `moveCanvasSelectorGroupToFilter()`。新增卡片必须使用 `createCard()` / `createSelector()` 等工厂函数。
 - Card/Page 描述也是 JS 源文件的一部分：新建看板或改版时，在 `card_*.js` / `page.js` 中写 `.setDescription(...)`，再通过 `preview`/`pack`/`publish` 从 JS 源文件生成并发布资源。
 - 写脚本前先形成 dashboard contract：目标用户、业务问题、使用的数据集、核心指标、维度拆解、筛选器、页面结构和验证方式。
 - 每次生成都针对明确目录或明确子目录；不要把 unrelated 示例、旧包或临时 ZIP 混入同一个发布目标。
@@ -29,7 +31,9 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 
 ## AI Quick Reference（速查，详细说明见按需参考资料）
 
-1. **工厂函数**：数据集图表用 `createCard()`；指标平台指标卡片用 `createMetricChart()`；筛选器/文本/图片/杜邦/Tab/页面用 `createSelector()` / `createTextCard()` / `createImageCard()` / `createDuPontChart()` / `createAreaTitle()` / `createCardGroup()` / `createTab()` / `createPage()`，不要 `new XxxBuilder()`
+**Checkout/attachCard 速记**：`attachCard(cardId, jsonPath)` 是“base JSON + 链式 DSL 操作 = 目标 JSON”。它不会修改 base JSON，重复执行同一组 JS 操作应产出相同 payload。已有卡片可继续串接常用 `createCard` 后续操作，包括标题/描述、`setRawSettings`、图例/标签/坐标轴/表格/拆分等视觉设置。Zone 操作按链式顺序真实执行：`addRow/addMetric/...` 追加字段，`insertMetric(index, field)` 插入字段，`removeMetric(selector)` 删除字段并保守清理其它 zone 中同字段引用，`moveMetric(selector, index)` 调整顺序，`updateMetric(selector, patch)` / `patchMetric(...)` 修改已有字段属性并保留未设置字段配置；`setRows/setMetrics/...` 和 `clearRows/clearMetrics/...` 是整 zone 重建，不会继承被替换字段的格式，并会在验证时提示 warning。已有 selector 额外用 `.addLink(cardIdOrIndex, targetFieldName?)` / `.removeLink(cardIdOrIndex)` / `.clearLinks()` 修改联动。Page 筛选区也按有序操作执行：`setFilterLayout` 整体设置，`clearFilterLayout` 清空，`addFilterLayoutItem` 追加去重，`insert/remove/moveFilterSelector` 局部调整；筛选器在快捷筛选区和画布间移动优先用动作级 API：`moveFilterSelectorToCanvas(selectorId, x, y, w, h)` / `moveCanvasSelectorToFilter(selectorId, index?)`，筛选器组用 `moveSelectorGroupToCanvas(group, x, y, w, h)` / `moveCanvasSelectorGroupToFilter(group, index?)`。checkout 生成的 page 布局默认用 card/selector ID 字符串；发布前可用 `guanvis diff <dir>` 或 `preview` 输出里的 `changeSummary` 查看 base JSON 到最终 payload 的路径级影响面；没有 DSL 操作覆盖的需求，先扩展 DSL，不要改 `.guanvis` JSON。
+
+1. **工厂函数**：数据集图表用 `createCard()`；已有线上卡片用 `attachCard(cardId, jsonPath)`；指标平台指标卡片用 `createMetricChart()`；筛选器/筛选器组/文本/图片/杜邦/Tab/页面用 `createSelector()` / `createSelectorGroup()` / `createTextCard()` / `createImageCard()` / `createDuPontChart()` / `createAreaTitle()` / `createCardGroup()` / `createTab()` / `createPage()`，不要 `new XxxBuilder()`；checkout JSON 不可复制改造，新卡片必须 create，老卡片才 attach
 2. **注册函数**：`registerCard(card.build())` / `registerMetricChart(card.build())` / `registerSelector(sel.build())` / `registerTextCard(text.build())` / `registerImageCard(image.build())` / `registerDuPontChart(dupont.build())` / `registerPage(page.build())`
 3. **字段引用**：单数据集用 `f("字段名")`，多数据集用 `field(DS, "字段名")`
 4. **zone maxCount**：`BASIC_COLUMN/BAR/LINE` metric=1；`GROUPED_*/STACKED_*` metric=∞；`KPI_CARD` metric=1；组合图 `*_WITH_LINE` row=1
@@ -38,19 +42,20 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 7. **calcField 命名**：不能与数据集物理字段同名，否则 BI 默认取数据集字段
 8. **calcField 类型**：`aggregation`（默认）公式必须含聚合函数；纯算术用 `{ calculationType: "normal" }`；窗口函数用 `{ calculationType: "window" }`
 9. **明细/滚动表 calcField**：`DETAIL_TABLE` / `SCROLL_TABLE` 只做逐行展示；如需行级计算，必须写 `{ calculationType: "normal" }`，且不要写任何 SQL 聚合函数或窗口函数。汇总需求改用非明细图表 `aggrType` / aggregation calcField，或 ETL 预计算
-10. **联动/下钻**：筛选器联动必须调用 `.linkToAll()` 或 `.linkTo(cardIndex)`；普通图表卡片联动普通图表用 `card.linkTo(layoutCardIndex, { fields: [{ source, target }] })`；固定路径下钻用 `registerDrillPath(parentCardIndex, [child.build()], { position: DrillPathPosition.BOTTOM })`；详细规则见 `references/builder-reference.md`
+10. **联动/下钻**：新建筛选器联动图表必须调用 `.linkToAll()` 或 `.linkTo(cardIndex)`；checkout attach 回来的已有筛选器用 `attachCard(selectorId, jsonPath).addLink(cardIdOrIndex, targetFieldName?)` / `.removeLink(cardIdOrIndex)` / `.clearLinks()` 叠加修改现有 `settings.asFilter`，不要反向改 JSON；筛选器级联筛选器用 `.linkToSelector(selectorId, targetFieldName?)`，目标为 ALL/空默认值时会自动启用 FIRST_PICK + firstPickLink，固定默认值会保留；普通图表卡片联动普通图表用 `card.linkTo(layoutCardIndex, { fields: [{ source, target }] })`；固定路径下钻用 `registerDrillPath(parentCardIndex, [child.build()], { position: DrillPathPosition.BOTTOM })`；详细规则见 `references/builder-reference.md`
 11. **selector 类型选择**：离散值（区域/类别）→ `DS_ELEMENTS`（默认）；连续数值（利润率/金额）→ `.setSelectorType(SelectorType.DS_INTERVAL)`；日期 → `CALENDAR`；快捷日期区间（本月/近7天等）→ `.setTimeMacroOptions(options)`
-12. **同环比默认**：用户说同比/环比/同环比/年同比/月环比且未指定输出值时，默认用增长率；未指定模式时默认按日期筛选模式（`ComparativeMode.FILTER_BASED`），普通模式需显式指定 `ComparativeMode.NORMAL`
-13. **placeCard 索引**：按 `registerCard` / `registerMetricChart` / `registerTextCard` 的实际调用顺序累加，文件按文件名排序加载。**registerSelector 不参与 card index 计数**
+12. **同环比默认**：用户说同比/环比/同环比/年同比/月环比且未指定输出值时，默认用增长率；未指定模式时默认按日期筛选模式（`ComparativeMode.FILTER_BASED`），普通模式需显式指定 `ComparativeMode.NORMAL`。如果日期字段已经是预聚合周期字段（如 `周开始日期` / `月开始日期`），必须把日期字段声明为 `f("周开始日期", { granularity: Granularity.NONE })`，builder 会生成不带筛选窗口和 `mode` 的同环比，避免按 DAY 筛选窗口计算为空
+13. **placeCard 入参**：优先使用 card/selector ID 字符串，尤其是 checkout 工程和子目录工程，如 `placeCard("cardId", x, y, w, h)`。数字 index 仍可用于新建工程，按 `registerCard` / `registerMetricChart` / `registerTextCard` / `registerImageCard` / `registerCustomChart` / `registerDuPontChart` 等可布局资源的注册顺序累加，文件按文件名排序加载；**registerSelector 不参与 card index 计数**。要把 selector 放进画布或者布局组件时，使用 selector 字符串 ID，如 `placeCard("selectorId", x, y, w, h)` 或 `addFullWidthCard("selectorId", h)`。
 14. **publish 环境**：认证由底层 CLI 负责——guancli 需先 `guancli auth use <profile>`，guancli-lite 需设置环境变量
-15. **更新线上仪表板**：已发布过或线上正在使用的仪表板，若调整图表、布局、筛选器、字段等看板内容，默认创建新版本仪表板，不覆盖原仪表板；新版本使用新的 Page/Card/Selector ID，名称追加版本号（如 `销售仪表板 v2` / `销售仪表板 20260430`），保留多个版本。只有用户明确要求覆盖时，才复用原 ID；遇到覆盖提示时，Agent 必须先向用户说明将覆盖哪些线上资源并取得明确确认，确认前不得自行加 `--allow-overwrite`
+15. **更新线上仪表板**：checkout 工程默认表示“修改指定线上 Page”，保留原 Page/Card/Selector ID；发布时如 CLI 检测到同 ID Page，必须先向用户说明将覆盖哪些线上资源并取得明确确认，确认后才可加 `--allow-overwrite`，由现有覆盖备份机制兜底。不要把 checkout JSON 复制后改 ID 来做“新版本”。若用户明确要保留原页面并生成新版本，应优先调用 BI 自身 Page Save/复制能力让 BI 处理 ID 映射，再基于新页面 checkout/edit；不要在 guanvis CLI 里手写复杂 ID map。
 16. **描述维护**：仅修复已发布 Card/Page 的描述时，保留原资源 ID，使用 `guanvis card/page set-description` 更新线上描述；如果本地有对应 JS 工程，也同步更新 `.setDescription(...)`，让源文件与线上描述一致
 17. **主题切换**：用户描述风格（深色科技风/科技蓝/蓝色简约等）→ 在工程目录里 `guanvis theme preference --keywords "..." --sync`（`[dir]` 可省，默认当前目录）；不要选择租户默认的“浅色”/“深色”主题，找不到合适主题时保持/清空偏好，让 preview/pack/publish 自动使用内置“简约”兜底。普通数据集图表与指标平台 MetricChart 都会自动应用主题视觉配置；改版未提风格时 `.applied.json` 会自动继承上次主题，preview/pack/publish 不需要重复指定。**多子目录工程**：每个子目录是独立工程，主题要在子目录里配置 + preview/pack/publish 也必须 `cd` 进对应子目录运行（在根目录直接跑会被命令显式拒绝并给出 cd 提示）；详见 `references/theme.md`
 18. **设计规则**：`preview`/`pack`/`publish` 会自动应用内置设计规则；需要自定义静态卡片默认规则或主题已开放配置时，在工程目录新建 `design-rule.json`，不要手改 `themes/<themeId>.json`；详见 `references/theme.md`
 19. **图表选型**：用户说“指标卡片”时先区分语义：如果是数据集字段做单值/KPI，用 `SINGLE_VALUE` / `KPI_CARD`；如果是“用指标平台已有指标创建卡片”，必须先 `guanvis metric-init <metricId>`，再用 `createMetricChart()` + `metric()` / `metricDim()`，生成后端 `CARD_TYPE.METRIC_CHART`。复杂指标卡片参数先读 `references/metric-chart-reference.md`
 20. **杜邦分析图**：杜邦不是普通 `ChartType`，用 `createDuPontChart()` 创建 `LAYOUT` 卡片；节点通常放 `KPI_CARD` 子卡片，并通过 `.setRoot()` / `.addChild()` 组织树。页面布局只放杜邦父卡片，不单独放子卡片；筛选器 `linkToAll()` 会覆盖杜邦子卡片。
-21. **布局组件**：支持了布局组件 `小标题(AreaTitle)`/ `卡片组(CardGroup)`/ `标签页(Tab)`， 目前布局组件只支持放在画布的根布局，不支持嵌套组合使用，用法见 `references/builder-reference.md`。
-22. **资源包禁止手改**：只改 DSL，不改 ZIP 内部文件；`upload` 只用于上传 `guanvis pack` 原样生成的包。批量重绑、迁移页面等需求先讨论方案。
+21. **布局组件**：支持 `小标题(AreaTitle)` / `卡片组(CardGroup)` / `筛选器组(SelGroup)` / `标签页(Tab)`。布局组件本身只支持放在画布根布局，不支持嵌套组合使用；SelGroup 内只能放 selector；checkout 会反编译根布局组件，无法安全表达的嵌套结构会失败；内部布局能力详见 `references/builder-reference.md`。
+22. **资源包/checkout JSON 禁止手改**：只改 DSL，不改 ZIP 内部文件，也不改 `.guanvis/raw` / `.guanvis/base` / `.guanvis/manifest.json`；`upload` 只用于上传 `guanvis pack` 原样生成的包。批量重绑、迁移页面、补缺失操作符等需求先讨论方案，必要时扩展 DSL 操作，不手工改生成物。
+23. **动态字段**：普通卡支持动态维度/动态数值，指标平台卡支持动态维度/动态指标；用户明确需要字段切换时使用 `.addDynamicRow()` / `.addDynamicMetric()` 等 API，细节见 `references/builder-reference.md`。
 
 ## 何时使用
 
@@ -270,9 +275,18 @@ guanvis gen-layout-id tab                 # 生成 1 个 tab_ + 默认 6 位字
 guanvis gen-layout-id panel 3 --length 8  # 生成 3 个 panel_ + 8 位字母；length 只计算下划线后的随机字母，超出 6~10 时自动收敛
 guanvis gen-layout-id areaTitle           # 生成 1 个 areaTitle_ + 默认 6 位字母
 guanvis gen-layout-id cardGroup           # 生成 1 个 cardGroup_ + 默认 6 位字母
+guanvis gen-layout-id selGroup            # 生成 1 个 selGroup_ + 默认 6 位字母
+
+# 拉取已有线上仪表板为可编辑工程（只读 BI，不发布；尽量生成 schema.js）
+guanvis checkout <pageId> -d ./existing_dashboard
+# checkout 后只编辑 schema 外的 card_*.js / selector_*.js / page.js；不要修改或复制 .guanvis/raw、.guanvis/base、.guanvis/manifest.json
+# 若 schema.js 未生成或缺字段，后续可手动 guanvis init <dsId> -d ./existing_dashboard --force 补齐
+# checkout --overwrite 会清理输出目录下所有根级 .js 和旧 .guanvis，避免 schema/selector/metrics/other.js 残留混入运行
 
 # 预览生成结果（JSON 输出到 stdout，含 payload 验证，用于调试）
 guanvis preview ./my_dashboard/
+# checkout/attach 工程的路径级变更摘要（也会出现在 preview JSON 的 changeSummary 中）
+guanvis diff ./existing_dashboard/
 
 # 打包为 ZIP 资源包
 guanvis pack ./my_dashboard/
@@ -298,6 +312,12 @@ guanvis screenshot <pageId>                                     # 截图页面 P
 guanvis screenshot <pageId> -o /tmp/dashboard.png               # 指定输出路径
 guanvis screenshot <pageId> --orientation horizontal            # 横向截图
 
+# 数据集/指标切换后的检查（仅梳理）
+guanvis check-dataset-usage . --ds <dsId>         # 盘点某个 dsId 在工程中的引用
+guanvis check-dataset-switch . --from <oldDs> --to <newDs> --mode full # 整页/整包数据集切换后检查
+guanvis check-dataset-switch . --from <oldDs> --to <newDs> --mode linked --changed-cards <cdId> # 局部切数据集后检查一跳关联资源
+guanvis check-metric-switch . --from <oldMetric> --to <newMetric> --mode linked --changed-cards <cdId> # 局部切指标后检查一跳关联资源
+
 # 仪表板主题（详见 `references/theme.md`，[dir] 缺省为当前目录）
 guanvis theme preference --keywords "深色 科技" --sync          # 在当前目录写入偏好并同步主题列表
 guanvis theme preference ./my_dashboard --theme-id custom_blue  # 显式指定工程目录
@@ -331,12 +351,12 @@ guanvis pack ./project
 
 **资源包安全约束**：`upload` 只是上传器，不是制作自定义资源包的入口。除非用户明确批准，否则不得上传手工生成、解包修改、重打包或批量替换内部内容后的 ZIP。需要批量重绑数据集、字段、卡片或页面 ID 时，先讨论方案，不要直接改 ZIP。
 
-**线上仪表板更新策略**：为了保护已经发布过的仪表板和线上仪表板，默认不要复用原 Page/Card/Selector ID 做覆盖更新。需要调整线上看板时，应先生成一组新的 ID，复制并修改 DSL/JS，给 Page 名称追加版本号（例如 `v2`、`v20260430` 或业务约定版本），再 `publish` 到目标目录。旧版本保留用于回滚和对比。仅当用户明确要求“覆盖原仪表板/复用原 ID”时，才允许同 ID 发布，并且命令必须显式加 `--allow-overwrite` 允许同 ID Page 覆盖；发布前可用 `--dry-run` 查看会覆盖哪些线上 Page。Card/Selector ID 不做在线覆盖检查。**Agent 禁止在未确认的情况下自行加 `--allow-overwrite`**：当 CLI 提示将覆盖线上 Page 时，必须先停止发布，向用户说明将覆盖的 Page ID、名称和覆盖后可能替换原页面布局，等用户明确确认“覆盖”后才可以重跑并加 `--allow-overwrite`。使用 `--allow-overwrite` 时，CLI 会先为冲突 Page 发起资源包导出备份并等待导出成功；备份未成功则中止覆盖。CLI 只记录备份导出记录和 packageId，不自动下载资源包；需要回滚时，到 BI 资源迁移导出记录中手动下载该资源包后再导入覆盖回去。
+**线上仪表板更新策略**：新建工程发布的是新 Page；checkout 工程发布的是对 checkout 指定 Page 的覆盖式修改，不承担“复制新版本”职责。需要保留原页面并生成新版本时，不要在 guanvis CLI 内手工复制 JSON 或改 ID map；应先使用 BI 自身 Page Save/复制能力生成新 Page，让 BI 处理 ID 映射，再 checkout 新 Page 继续编辑。对 checkout 工程同 ID 发布时，命令必须显式加 `--allow-overwrite` 允许同 ID Page 覆盖；发布前可用 `--dry-run` 查看会覆盖哪些线上 Page。Card/Selector ID 不做在线覆盖检查。**Agent 禁止在未确认的情况下自行加 `--allow-overwrite`**：当 CLI 提示将覆盖线上 Page 时，必须先停止发布，向用户说明将覆盖的 Page ID、名称和覆盖后可能替换原页面布局，等用户明确确认“覆盖”后才可以重跑并加 `--allow-overwrite`。使用 `--allow-overwrite` 时，CLI 会先为冲突 Page 发起资源包导出备份并等待导出成功；备份未成功则中止覆盖。CLI 只记录备份导出记录和 packageId，不自动下载资源包；需要回滚时，到 BI 资源迁移导出记录中手动下载该资源包后再导入覆盖回去。
 
 ## 文件结构约定
 
 目录模式下文件加载顺序：
-1. `schema.js` — 数据集定义（自动生成，不可修改）
+1. `schema.js` — 数据集定义（init 生成；checkout 尽量生成，不可修改）
 2. `metrics.js` — 指标定义（仅指标卡片需要，自动生成，不可修改）
 3. `card_01_xxx.js` ~ `card_NN_xxx.js` — Card 定义（按文件名排序）
 4. `selector_01_xxx.js` ~ `selector_NN_xxx.js` — 筛选器定义（在 card 之后执行，因为联动需要引用 card 索引）
@@ -351,6 +371,7 @@ guanvis pack ./project
 | 示例 | 路径 | 说明 |
 |------|------|------|
 | 基础仪表板 | `evals/sales_dashboard/` | 普通卡片（柱状图、折线图、KPI、饼图）+ 筛选器 + 页面布局 |
+| 拆分图 | `evals/split_charts/` | 柱形等图表按字段拆分 |
 | 自定义图表 | `evals/custom_chart_echarts/` | ECharts Lite 自定义图表：柱状图 + 饼图，使用 `loadContent()` 文件模式 |
 | Tab 布局 | `evals/tab_layout/` | 单页面 tab 示例，含根布局指标卡、图表卡片、文本卡片、筛选器和 panel 内卡片布局 |
 

package/skills/guanvis/evals/dynamic_fields/card_01_dynamic_dataset.js

@@ -0,0 +1,20 @@
+var region = f("区域");
+var city = f("城市");
+var sales = f("销售额", { aggrType: AggrType.SUM });
+var profit = f("利润", { aggrType: AggrType.SUM });
+
+var card = createCard(ChartType.GROUPED_COLUMN, "动态维度与动态数值")
+    .setId("dfcarddataset00000000000")
+    .bindDataset(DS)
+    .addDynamicRow("分析维度", [region, city], {
+        defaultValue: [region],
+        multiSelect: false
+    })
+    .addDynamicMetric("分析数值", [sales, profit], {
+        defaultValue: [sales],
+        multiSelect: true,
+        orderType: DynamicFieldOrder.CLICK
+    })
+    .setShowLegend(true, "bottom");
+
+registerCard(card.build());

package/skills/guanvis/evals/dynamic_fields/card_02_dynamic_metric_chart.js

@@ -0,0 +1,16 @@
+var region = metricDim("销售额", "区域");
+var city = metricDim("销售额", "城市");
+var sales = metric("销售额");
+var profit = metric("利润");
+
+var card = createMetricChart(ChartType.PIVOT_TABLE, "指标平台动态维度与动态指标")
+    .setId("dfmetriccard000000000000")
+    .addDynamicRow("分析维度", [region, city], {
+        defaultValue: [region]
+    })
+    .addDynamicMetric("分析指标", [sales, profit], {
+        defaultValue: [sales],
+        multiSelect: true
+    });
+
+registerMetricChart(card.build());

package/skills/guanvis/evals/dynamic_fields/metrics.js

@@ -0,0 +1,19 @@
+defineMetric({
+    id: "metric_sales_eval_000001",
+    name: "销售额",
+    subType: "ATOMIC",
+    applicableDims: [
+        { fdId: "region_fd", dsId: "ds_dynamic_fields_eval", name: "区域", fdType: "STRING", metaType: "DIM" },
+        { fdId: "city_fd", dsId: "ds_dynamic_fields_eval", name: "城市", fdType: "STRING", metaType: "DIM" }
+    ]
+});
+
+defineMetric({
+    id: "metric_profit_eval_00001",
+    name: "利润",
+    subType: "ATOMIC",
+    applicableDims: [
+        { fdId: "region_fd", dsId: "ds_dynamic_fields_eval", name: "区域", fdType: "STRING", metaType: "DIM" },
+        { fdId: "city_fd", dsId: "ds_dynamic_fields_eval", name: "城市", fdType: "STRING", metaType: "DIM" }
+    ]
+});

package/skills/guanvis/evals/dynamic_fields/page.js

@@ -0,0 +1,9 @@
+var page = createPage("动态字段示例")
+    .setId("dfpage000000000000000000")
+    .setDescription("验证动态维度、动态数值和指标平台动态指标的资源包结构。")
+    .setBackgroundColor("#f5f5f5")
+    .setCardMargin(8)
+    .addFullWidthCard(0, 7)
+    .addFullWidthCard(1, 7);
+
+registerPage(page.build());

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

@@ -0,0 +1,7 @@
+defineDataset("ds_dynamic_fields_eval", [
+    { fdId: "region_fd", name: "区域", fdType: "STRING", metaType: "DIM" },
+    { fdId: "city_fd", name: "城市", fdType: "STRING", metaType: "DIM" },
+    { fdId: "month_fd", name: "月份", fdType: "DATE", metaType: "DIM" },
+    { fdId: "sales_fd", name: "销售额", fdType: "DOUBLE", metaType: "METRIC" },
+    { fdId: "profit_fd", name: "利润", fdType: "DOUBLE", metaType: "METRIC" }
+], { displayType: "CSV" });