@guandata/guanvis 0.1.28 → 0.1.29

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## @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,14 @@ guanvis publish ./my_dashboard/ --allow-overwrite
 
 ## 版本更新
 
+### @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.29",
   "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

@@ -38,10 +38,10 @@ 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)`；筛选器级联筛选器用 `.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 入参**：数字 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`
 16. **描述维护**：仅修复已发布 Card/Page 的描述时，保留原资源 ID，使用 `guanvis card/page set-description` 更新线上描述；如果本地有对应 JS 工程，也同步更新 `.setDescription(...)`，让源文件与线上描述一致
@@ -49,7 +49,7 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 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`。
+21. **布局组件**：支持 `小标题(AreaTitle)` / `卡片组(CardGroup)` / `标签页(Tab)`。布局组件本身只支持放在画布根布局，不支持嵌套组合使用；内部布局能力详见 `references/builder-reference.md`。
 22. **资源包禁止手改**：只改 DSL，不改 ZIP 内部文件；`upload` 只用于上传 `guanvis pack` 原样生成的包。批量重绑、迁移页面等需求先讨论方案。
 
 ## 何时使用

package/skills/guanvis/evals/tab_layout/card_03_story.js

@@ -4,8 +4,8 @@ var text = createTextCard("Tab 使用说明")
         "### Tab 布局示例\n\n" +
         "- `createTab()` 创建容器\n" +
         "- `addPanel(name, callback)` 创建页面上可切换的标签\n" +
-        "- panel 内通过 cardIndex 放置图表卡片或文本卡片\n\n" +
-        "> 筛选器仍然注册为 selector，自动进入页面筛选器区。"
+        "- panel 内通过 cardIndex 放置图表/文本等卡片，也可以用 selector 字符串 ID 放置筛选器\n\n" +
+        "> 未放入画布布局的筛选器会进入筛选器栏；用 `placeCard(\"selectorId\")` 放入 panel/root/cardGroup 后，同页筛选器栏不再重复展示。"
     );
 
 registerTextCard(text.build());

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

@@ -15,7 +15,7 @@ var salesTab = createTab("销售分析")
 
 var page = createPage("Tab Layout 示例")
     .setId("pppppppppppppppppppppppp")
-    .setDescription("展示根布局指标卡、tab 容器、panel 内图表/文本卡片，以及 selector 仍进入筛选器区。")
+    .setDescription("展示根布局指标卡、tab 容器、panel 内图表/文本卡片，以及 selector 可默认进入筛选器栏或用字符串 ID 放入画布。")
     .setCardMargin(8)
     .addRow([{ card: 0, w: 4 }], 3)
     .addTab(salesTab);

package/skills/guanvis/references/api-reference.md

@@ -129,11 +129,26 @@ f("订单日期", { granularity: Granularity.DAY })     // 按天
 - 时间类型：日环比、周同比、月同比、季同比、年同比、年同比(按周)
 - 期末值：上月末、上季度末、上年末
 - 自定义：后移 1 个月
-- 输出值：增长值、增长率、对比值
+- 输出值：增长值、增长率、对比值、本期/对比期（内置自定义公式预设）
 - 增长率类型：普通增长率、绝对增长率
 
 默认规则：同比、环比、同环比、年同比、月环比等语义未指定输出值时默认生成增长率；未指定模式时默认生成日期筛选模式（`ComparativeMode.FILTER_BASED`），保证页面日期筛选器联动生效。需要普通模式时显式传 `{ mode: ComparativeMode.NORMAL }`；需要增长值或对比值时显式传 `ComparativeOutput.GROWTH_VALUE` / `ComparativeOutput.COMPARE_VALUE`。
 
+预聚合周期字段（例如数据集中已经按周产出的 `周开始日期`、按月产出的 `月开始日期`）不能按默认 DAY 筛选窗口计算。使用这类字段做周环比/月环比时，把日期字段声明为 `Granularity.NONE`，builder 会自动生成不带筛选窗口和 `mode` 的同环比：
+
+```javascript
+var weekStart = f("周开始日期", { granularity: Granularity.NONE });
+
+createCard(ChartType.PIVOT_TABLE, "周报")
+    .bindDataset(DS)
+    .addRow(weekStart)
+    .addMetric(f("GMV", {
+        alias: "GMV周环比",
+        aggrType: AggrType.SUM,
+        advCalc: comparative.weekOverWeek(weekStart)
+    }));
+```
+
 示例：
 
 ```javascript
@@ -159,6 +174,11 @@ createCard(ChartType.PIVOT_TABLE, "销售同环比")
         aggrType: AggrType.SUM,
         advCalc: comparative.monthOverMonth(dateField, ComparativeOutput.COMPARE_VALUE)
     }))
+    .addMetric(f("销售额", {
+        alias: "本期除以去年同期",
+        aggrType: AggrType.SUM,
+        advCalc: comparative.yearOverYear(dateField, ComparativeOutput.CURRENT_OVER_COMPARE)
+    }))
     .addMetric(f("销售额", {
         alias: "上月末增长值",
         aggrType: AggrType.SUM,
@@ -192,6 +212,7 @@ createCard(ChartType.KPI_CARD, "销售额 KPI")
 - `ComparativeOutput.GROWTH_VALUE`：增长值
 - `ComparativeOutput.GROWTH_RATE`：增长率
 - `ComparativeOutput.COMPARE_VALUE`：对比值
+- `ComparativeOutput.CURRENT_OVER_COMPARE`：本期 / 对比期，底层生成 `valueType: "CUSTOM"` 与公式 `[orig]/[shifted]`
 - `GrowthRateType.NORMAL`：普通增长率，默认值
 - `GrowthRateType.ABS`：绝对增长率
 - `ComparativeMode.FILTER_BASED`：日期筛选模式，默认值，用于复现前端「对比」槽位 + 日期筛选的高级计算

package/skills/guanvis/references/builder-reference.md

@@ -164,8 +164,8 @@ registerMetricChart(card.build());
 
 #### Card Linkage（图表卡片点击联动）
 
-`CardBuilder.linkTo(target, config)` 用于让一个普通图表卡片或固定路径下钻子卡，在点击维度值后过滤同一页面内的目标图表卡片。
-通过 `settings.asFilter` 配置联动关系，通过 `settings.interaction`配置默认交互，不是 selector 联动。
+`CardBuilder.linkTo(target, config)` 用于让一个普通图表卡片、固定路径下钻子卡，或自定义图表的 data view（子卡片），在点击维度值后过滤同一页面内的目标图表卡片。
+通过 `settings.asFilter` 配置联动关系，通过 `settings.interaction`配置默认交互，不是 selector 联动。自定义图表作为联动源时还需在 `renderChart` 里回传 `clickFunc`（见 Custom Chart 章节）。
 
 ```javascript
 // card_00_region_sales.js
@@ -293,18 +293,19 @@ overview.linkTo("bbbbbbbbbbbbbbbbbbbbbbbb", {
 3. `addRow()` 及其快捷方法的 `height` 省略或为 0 时使用默认行高（普通 6，精细 18）。
 4. 区域小标题用 `createAreaTitle(...).setId(...).build()` 定义，并通过 `page.addAreaTitle(title)` 放在 Page 根布局；不要放进 tab panel。
 5. 卡片组用 `createCardGroup(...).setId(...)` 定义，并通过 `page.addCardGroup(group)` 放在 Page 根布局。
+6. 下文布局 API 中的 `cardRef` 表示：非 selector 卡片的数字 index，或已注册 selector 的字符串 ID。`registerSelector()` 不参与数字 index 计数；被布局引用的 selector 不再进入同页筛选器栏。
 
 | 方法 | 说明 |
 |------|------|
 | `createPage(name)` | 创建 Page |
 | `.setId(pgId)` | 设置 Page ID |
 | `.setParentDir(dirId)` | 设置页面所在目录 ID（不设置则在根目录），目录 ID 可通过 `guancli page tree` 获取 |
-| `.addRow(specs, height?)` | **推荐**：灵活行布局，specs = `[{ card: index, w: colSpan }, ...]`；不传 w 时自动等分当前栅格 |
-| `.addFullWidthCard(cardIndex, height?)` | 全宽行，等价于 `addRow([{ card }], height)` |
-| `.addHalfWidthCards(ci1, ci2, height?)` | 左右各半 |
-| `.addThirdWidthCards(ci1, ci2, ci3, height?)` | 三等分 |
-| `.addQuarterWidthCards(ci1, ci2, ci3, ci4, height?)` | 四等分 |
-| `.placeCard(cardIndex, x, y, w, h)` | 精确放置 Card，`w/h` 必须大于 0， `x/y/w/h` 必须显式填写 |
+| `.addRow(specs, height?)` | **推荐**：灵活行布局，specs = `[{ card: cardRef, w: colSpan }, ...]`；不传 w 时自动等分当前栅格 |
+| `.addFullWidthCard(cardRef, height?)` | 全宽行，等价于 `addRow([{ card }], height)` |
+| `.addHalfWidthCards(a, b, height?)` | 左右各半 |
+| `.addThirdWidthCards(a, b, c, height?)` | 三等分 |
+| `.addQuarterWidthCards(a, b, c, d, height?)` | 四等分 |
+| `.placeCard(cardRef, x, y, w, h)` | 精确放置 Card，`w/h` 必须大于 0， `x/y/w/h` 必须显式填写 |
 | `.addTab(tab, height?)` | 添加一个满宽 tab 容器；不传 height 时按第一个 panel 内容自动推导 |
 | `.addAreaTitle(areaTitle, height?)` | 添加一个满宽区域小标题|
 | `.addCardGroup(group, height?)` | 添加一个满宽卡片组；不传 height 时按标题和组内布局自动推导 |
@@ -359,8 +360,10 @@ registerPage(page.build());
 | `.setId(cardGroupId)` | **必填**。设置卡片组 ID，必须以 `cardGroup_` 开头 |
 | `.setShowTitle(boolean)` | 是否显示标题，默认 `true` |
 | `.addRow(specs, height?)` | 在组内按行放置卡片，写法同 `PageBuilder.addRow()` |
-| `.addFullWidthCard(cardIndex, height?)` | 在组内放一张满宽卡片 |
-| `.placeCard(cardIndex, x, y, w, h)` | 在组内精确放置卡片 |
+| `.addFullWidthCard(cardRef, height?)` | 在组内放一张满宽卡片 |
+| `.placeCard(cardRef, x, y, w, h)` | 在组内精确放置卡片 |
+
+卡片组内布局方法同 `PageBuilder`，使用 `cardRef`。
 
 ```javascript
 var salesGroup = createCardGroup("销售概览")
@@ -407,8 +410,8 @@ tab 用于把页面中的卡片分到多个 panel。适合同一主题下多组
 | `.setTabSize(size)` | 设置标签宽度：`TabSizeType.MAX_CONTENT`（默认）或 `FLEX` |
 | `panel.setId(panelId)` | **必填**。设置 panel ID，必须以 `panel_` 开头且同一页面内唯一。建议用 `guanvis gen-layout-id panel` 生成 |
 | `panel.addRow(specs, height?)` | 在 panel 内按行放置卡片，写法同 `PageBuilder.addRow()` |
-| `panel.addFullWidthCard(cardIndex, height?)` | 在 panel 内放一张满宽卡片 |
-| `panel.placeCard(cardIndex, x, y, w, h)` | 在 panel 内精确放置卡片 |
+| `panel.addFullWidthCard(cardRef, height?)` | 在 panel 内放一张满宽卡片 |
+| `panel.placeCard(cardRef, x, y, w, h)` | 在 panel 内精确放置卡片 |
 
 **使用示例**：
 
@@ -438,13 +441,17 @@ registerPage(page.build());
 注意：
 
 - tab 必须有 panel，panel 必须有卡片；不要创建空 tab 或空 panel。
-- panel 内放置非 selector 卡片（图表、文本、图片、自定义图表等）。selector 仍通过 `registerSelector()` 进入页面筛选器区。
+- panel 内布局方法同 `PageBuilder`，使用 `cardRef`。
 - panel 布局跟随页面精细模式：`page.setFineMode(true)` 后，panel 也使用 60 列栅格和精细模式默认行高。
 - 不需要手工设置 tab 高度；只有明确要固定高度时才给 `page.addTab(tab, height)` 传第二个参数。
 
 ### SelectorBuilder（筛选器）
 
-筛选器是特殊的卡片（`cdType=6`），放在页面顶部的筛选器面板中，可联动影响其他图表卡片。
+筛选器是特殊的卡片（`cdType=6`），可联动影响其他图表卡片。默认情况下，注册后未被页面布局引用的 selector 会进入页面筛选器栏；如需把筛选器作为画布内容展示，在 `page.js` 中使用 selector 字符串 ID 作为 `cardRef`。
+
+**布局归属**：
+- 全局筛选器可进入页面筛选器栏，并按需使用 `.linkToAll()`。
+- 凡是作为画布内容或隶属于某个分区、Tab、CardGroup 的筛选器，必须跟随所属布局放置，不进入筛选栏。局部筛选器使用 `.linkTo(...)` 明确联动所属分区内图表，不默认 `.linkToAll()`。
 
 | 方法 | 说明 |
 |------|------|
@@ -458,7 +465,7 @@ registerPage(page.build());
 | `.setGranularityOptions(options, defaultGranularity?)` | 设置 `CALENDAR` 可选日期粒度列表和默认粒度，例如 `[Granularity.MONTH, Granularity.QUARTER]`。未显式设置时会从目标卡片日期字段粒度自动推断 |
 | `.setTimeMacroOptions(options, defaultMacroName?)` | 设置快捷日期选项（自动设置 `selectorType` 为 `TIME_MACRO`）。`options`: `[{ name, expr }]`，`expr` 使用内置宏名（见示例）。`defaultMacroName` 默认选中的宏名，传 `null` 则不选（页面打开时无默认值），不传则取第一项。不需要 `bindField` 和 `bindDataset` |
 | `.setMultiSelect(bool)` | 是否多选（默认 false） |
-| `.setDefaultType(type)` | 默认值类型：`SelectorDefaultType.FIRST_PICK`（默认）、`FIXED_VALUE` 或 `ALL` |
+| `.setDefaultType(type)` | 默认值类型：`SelectorDefaultType.FIRST_PICK`、`FIXED_VALUE` 或 `ALL`。未显式设置时按 `ALL`/空值生成；作为级联目标且默认是 `ALL`/空值时会自动改为 `FIRST_PICK` |
 | `.setDefaultAll()` | 设置默认"全部"（不筛选），等价于 `setDefaultType(SelectorDefaultType.ALL)` |
 | `.setDefaultValue(values, displayValues?)` | 设置固定默认值，自动切换为 FIXED_VALUE 类型 |
 | `.setDefaultDateRange(start, end, displayValues?)` | 设置 `CALENDAR` 日期区间默认值，自动切换为 FIXED_VALUE；比手写数组更不容易漏填区间端点 |
@@ -467,6 +474,7 @@ registerPage(page.build());
 | `.setShowSelectAll(bool)` | 是否显示"全选"（默认 true） |
 | `.setCanClear(bool)` | 是否可清空（默认 true） |
 | `.linkTo(cardIndex, targetFieldName?)` | 联动指定卡片（cardIndex 为过滤后的可联动目标序列：普通图表和 MetricChart 按注册/布局顺序，杜邦子图追加在末尾），可指定目标字段名（默认同名匹配） |
+| `.linkToSelector(selectorId, targetFieldName?)` | 联动指定筛选器（用于省→市→区等级联）。`selectorId` 为目标筛选器 ID；`targetFieldName` 默认按源字段名匹配目标筛选器数据集字段。目标筛选器为 `ALL`/空默认值时会自动启用 `FIRST_PICK + firstPickLink`，固定默认值会保留 |
 | `.linkToAll()` | 自动联动所有普通图表卡片、MetricChart 和杜邦子卡片（按同名字段匹配） |
 | `.build()` | 构建（触发验证） |
 
@@ -535,13 +543,35 @@ registerSelector(sel);
 //   QUARTER_TO_DAY, QUARTER_TO_YESTERDAY, YEAR_TO_LAST_MONTH, YEAR_TO_LAST_QUARTER
 ```
 
+```javascript
+// selector_04_cascade.js — 筛选器级联（省 -> 市）
+var city = createSelector("市")
+    .setId("bbbbbbbbbbbbbbbbbbbbbbbb")
+    .bindField(f("市"))
+    .build();
+registerSelector(city);
+
+var province = createSelector("省")
+    .setId("aaaaaaaaaaaaaaaaaaaaaaaa")
+    .bindField(f("省"))
+    .linkToSelector("bbbbbbbbbbbbbbbbbbbbbbbb") // 默认用“省”过滤“市”筛选器的数据集
+    .linkToAll()
+    .build();
+registerSelector(province);
+// 若目标筛选器“市”是 ALL/空默认值（包括显式 setDefaultAll()），
+// 会自动启用 FIRST_PICK + firstPickLink，省变化后自动重选第一项并继续向下游联动。
+// 若目标筛选器已显式 setDefaultValue([...]) 固定默认值，则保持用户设置。
+// 如果目标筛选器数据集中的上游字段不是同名字段，可传第二个参数：
+// .linkToSelector("bbbbbbbbbbbbbbbbbbbbbbbb", "所属省份")
+```
+
 **筛选器类型选择指南**：
 - **离散值**（区域、类别、客户名等文本字段）→ `DS_ELEMENTS`（默认），配合 `setDisplayType` 选择展示样式
 - **连续数值范围**（利润率、金额区间等）→ `SelectorType.DS_INTERVAL`，默认区间输入（起始值-结束值）
 - **日期选择**（精确日期范围）→ `SelectorType.CALENDAR`，需要 `bindField` 绑定日期字段。默认会从联动目标卡片推断日期粒度；如需固定月/季度等粒度，可用 `.setGranularity(Granularity.MONTH)` 或 `.setGranularityOptions([...], default)`
 - **快捷日期区间**（本月/上月/近7天等预设区间）→ `.setTimeMacroOptions(options, default)`，不需要 `bindField`，自动匹配目标卡片日期字段联动。`default` 传 `null` 表示无默认值
 
-**联动机制**：筛选器通过 `settings.asFilter` 配置联动关系。`linkTo(cardIndex)` 会自动构建 `columnMappings`，将筛选器字段映射到目标卡片的同名字段；cardIndex 只统计普通图表、MetricChart 和杜邦子卡片，文本/图片等不可联动资源不占序号。`linkToAll()` 会自动匹配所有普通图表卡片、MetricChart 和杜邦子卡片中的同名字段。
+**联动机制**：筛选器通过 `settings.asFilter` 配置联动关系。`linkTo(cardIndex)` 会自动构建 `columnMappings`，将筛选器字段映射到目标卡片的同名字段；cardIndex 只统计普通图表、MetricChart 和杜邦子卡片，文本/图片等不可联动资源不占序号。`linkToSelector(selectorId, targetFieldName?)` 用于筛选器联动筛选器，目标必须是已注册的 DS_ELEMENTS/TREE 筛选器，构建时会检查 selector 级联成环；目标为 ALL/空默认值时会自动改为 `FIRST_PICK + firstPickLink`，目标已有固定默认值时保留用户设置。`linkToAll()` 会自动匹配所有普通图表卡片、MetricChart 和杜邦子卡片中的同名字段，不自动包含筛选器。若同一个筛选器同时写了 `linkTo(index, "自定义字段")` 和 `linkToAll()`，显式 `linkTo` 的目标字段映射优先。
 
 **文件命名**：筛选器脚本建议命名为 `selector_NN_xxx.js`，会在 `card_*.js` 之后、`page.js` 之前执行。
 
@@ -759,6 +789,8 @@ registerImageCard(img2.build());
 
 **数据流**：BI 前端查询子卡片（data view）的数据 → 将结果按列组织为 `data` → 传给自定义图表的 `renderChart(data, clickFunc, config)` 函数（SDK）或直接可用 `data` 变量（ECHARTS_LITE）。
 
+**点击联动（custom chart 作为联动源）**：在 data view（子卡片 `CardBuilder`）上调用 `.linkTo(target, { fields: [{ source, target }] })`，即可让自定义图表成为同页联动源——图表内部点击某维度时，按映射过滤目标卡片。`target` 仍按布局 index 或 cardId 解析（不能指向自身所在的自定义图表）。校验、字段匹配、同页与联动环检查与普通图表卡片完全一致，结果写为 data view 的 `settings.asFilter` + `interaction=LINK`。SDK 子类型必须在 `renderChart` 里用第二个入参 `clickFunc` 回传点击：`clickFunc({ clickedItems: [{ idx: [viewIndex, columnIndex], colName: '列名', value: ['选中值'] }] })`；`idx[1]` 指向 data view 行字段的列序号。ECHARTS_LITE 也用同样的 `clickFunc`。
+
 `data` 格式（二维数组，外层每个元素对应一个数据视图，内层每个元素对应一个字段列）：
 ```javascript
 // data[viewIndex][columnIndex] = { name: "字段名", data: [...值], numberFormat: ... }
@@ -1053,7 +1085,7 @@ option = {
 | `NumberFormat` | `.number()`, `.currency()`, `.percentage()`, `.auto()`, `.custom()` | 数值格式化工厂 |
 | `SelectorType` | `DS_ELEMENTS`（默认）, `DS_INTERVAL`, `CALENDAR`, `TIME_MACRO` | 筛选器类型 |
 | `SelectorDisplay` | `SEARCH_LIST`（单选下拉）, `SEARCH_BOX`（多选下拉）, `CHECKBOX`（复选框）, `RADIO`（单选框）, `BUTTON_GROUP`（按钮组） | 筛选器展示类型，不设置时根据 multiSelect 自动推断 |
-| `SelectorDefaultType` | `FIRST_PICK`（默认）, `FIXED_VALUE`, `ALL`（全部/不筛选） | 筛选器默认值类型 |
+| `SelectorDefaultType` | `FIRST_PICK`, `FIXED_VALUE`, `ALL`（默认，全部/不筛选） | 筛选器默认值类型 |
 | `CardType` | `CHART`(0), `TEXT`(1), `IFRAME`(2), `PICTURE`(4), `SELECTOR`(6), `LAYOUT`(9) | 卡片类型（内部使用，通常不需要直接引用） |
 | `ImageSourceType` | `OUTSIDE_LINK`(1), `LOCAL_IMAGE`(2) | 图片来源类型 |
 | `ImageRenderType` | `RATIO`(1，原比例), `STRETCH`(2，拉伸填满), `FIT_TO_CONTENT`(3，自适应内容) | 图片渲染模式 |