@finebi/finebi-cli 1.4.0 → 1.5.0

package/README.md

@@ -42,6 +42,27 @@ finebi-cli <resource> <command> [options]
 
 Run `finebi-cli capability refresh` manually when backend commands changed, the cache expired, or you want to force a reload.
 
+For dashboard component queries, use repeatable inline filters or a JSON file (mutually exclusive):
+
+```powershell
+finebi-cli dashboard data --id <dashboardId> --entry-id <entryId> --filter "合同付款类型=分期付款" --filter "是否已经交货=是" --page-size 5
+finebi-cli dashboard data --id <dashboardId> --entry-id <entryId> --filters-file filters.json --page-size 5
+```
+
+Filter names come from `dashboard info` control entries' `filterName`. Queries return only the first page or initial view; `--page-size` controls the first-page size for tables with a pager. There is no `--page` or continuation support. A native `hasNext=true` is preserved and accompanied by `result.warnings: ["NEXT_PAGE_UNSUPPORTED"]`. Parameter and result details are defined in the [dashboard data contract](../docs/dashboard-command-design.md#73-dashboard-data). Both the client and the server capability must support the inline option; refresh capabilities after updating the plugin.
+
+For temporary field selection, first read the target instance's field directory:
+
+```powershell
+finebi-cli dashboard info --id <dashboardId>
+finebi-cli dashboard data --id <dashboardId> --entry-id <entryId> --dimension-ids '["<dId>"]' --filter "合同付款类型=分期付款"
+finebi-cli dashboard data --id <dashboardId> --entry-id <entryId> --dimension-ids '[]'
+```
+
+Use `entries[].queryFields[].dId` where `selectable=true`; this is a component-local key, not a dataset `fieldId` or field name. `queryFields` includes disabled fields and reports their saved `used` flag. Omit `--dimension-ids` to keep the saved selection. An explicit `[]` removes selectable dimensions while retaining summary/chart metrics; a detail table returns no columns or rows. Existing filters remain effective. Empty output columns do not imply that native pagination totals are zero.
+
+For a published dashboard, pass the same `--directory-entry-id` to `dashboard info` and `dashboard data`, and use dIds from that source. Installing this npm package updates only the client and bundled Skill. These commands require a compatible server plugin and platform Provider; the plugin directly depends on the dimension-selection and published-source APIs. Refresh capabilities after the server update.
+
 ### Multiple environments
 
 Create an environment by logging in with its name and address:
@@ -92,10 +113,13 @@ Agent discovery flow:
 finebi-cli --help --json
 finebi-cli config set base-url http://localhost:37799/webroot/decision
 finebi-cli auth login --from-env
-finebi-cli <resource> --help --json
+finebi-cli system command-index --json
+finebi-cli <resource> <command> --help --json
 finebi-cli <resource> <command> [options] --json
 ```
 
+`system command-index` returns the whole command surface as one compact index grouped by resource (`[write]` marks mutations, `[creates]` additionally marks resource creation; output is bounded to 8KB). Start with it instead of enumerating every resource's help, and open `--help` only for the commands you actually invoke.
+
 For complex file-based resources, do not expect command help to contain a complete source example. `widget template` returns a Widget JS DSL source template selected by chart type and scenario; `dashboard template` returns a Dashboard JS DSL example script with named placeholders and a variable contract. Their `add` and `update` commands accept JS DSL source files. Other resources may still expose writable JSON templates according to their dynamic command help.
 
 ## Agent Skills

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finebi/finebi-cli",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "FineBI dynamic capability command line client.",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -25,7 +25,7 @@
     "test": "npm run test:unit && npm run test:process && npm run test:contract && npm run test:integration:stub",
     "test:unit": "node --test tests/unit/access-key.test.js tests/unit/auth.test.js tests/unit/capability.test.js tests/unit/config-permissions.test.js tests/unit/config.test.js tests/unit/dynamic-command-forwarding.test.js tests/unit/dynamic-command-multipart.test.js tests/unit/dynamic-command-preflight.test.js tests/unit/error-catalog-loader.test.js tests/unit/error-catalog.test.js tests/unit/error-construction-guard.test.js tests/unit/help.test.js tests/unit/http-stub.test.js tests/unit/index-auth-login.test.js tests/unit/index-auth-session.test.js tests/unit/index-browser-auth.test.js tests/unit/index-config.test.js tests/unit/index-dynamic-errors.test.js tests/unit/index-dynamic-render.test.js tests/unit/index-help.test.js tests/unit/index-profiles.test.js tests/unit/install-skill.test.js tests/unit/output-limits.test.js tests/unit/output.test.js tests/unit/package.test.js tests/unit/schema-options-capability.test.js tests/unit/schema-options-file-input.test.js tests/unit/schema-options-scalar.test.js",
     "test:process": "node --test tests/process/bench-cli-runner.test.js tests/process/process-cli.test.js tests/process/profiles-cli.test.js",
-    "test:contract": "node --test tests/contract/capability-contract.test.js",
+    "test:contract": "node --test tests/contract/capability-contract.test.js tests/contract/dashboard-data.test.js tests/contract/subject-publication.test.js",
     "test:integration:stub": "node --test tests/integration/analysis-ds-workflows.test.js tests/integration/assertions.test.js tests/integration/auth-system.test.js tests/integration/case-loader.test.js tests/integration/cli-process.test.js tests/integration/config.test.js tests/integration/dashboard-workflows.test.js tests/integration/entry.test.js tests/integration/failure-security.test.js tests/integration/file-template.test.js tests/integration/mutating-file-input.test.js tests/integration/mutating-resource-ledger.test.js tests/integration/mutating-workflow-guards.test.js tests/integration/readonly-assertions.test.js tests/integration/readonly-file-input.test.js tests/integration/readonly-workflow-contract.test.js tests/integration/report-directory.test.js tests/integration/report-entry.test.js tests/integration/report-secrets.test.js tests/integration/report-summary-artifacts.test.js tests/integration/runner.test.js",
     "test:integration:readonly": "node tests/integration/entry.js readonly",
     "test:integration:mutating": "node tests/integration/entry.js mutating",

package/skills/finebi-cli-agent/references/command-workflows.md

@@ -20,7 +20,7 @@
 
 | 资源 | 只读（`mutation:false`） | 非只读（`mutation:true`） |
 |---|---|---|
-| `analysis-ds` | `dsl`†, `info`, `operator-schema`†, `preview`, `search` | `add`, `update`†, `data-update`, `delete`, `publish` |
+| `analysis-ds` | `dsl`†, `info`, `operator-schema`†, `preview`, `search` | `add`, `update`†, `data-update`, `delete`, `publish`, `unpublish` |
 | `calculated-field` | `context`, `dsl`, `info`, `validate` | `add`, `delete`, `update` |
 | `dashboard` | `search`, `info`, `preview` | `add`, `delete`, `update` |
 | `data-connection` | `search`, `tables` | — |
@@ -70,6 +70,7 @@
 - `search`：定位候选资源；在宣称唯一前遍历全部分页。
 - `info`：确认准确 ID、名称、归属、状态和字段/关系元数据。
 - `preview`：预览已有资源（`--id`），不代表写入。
+- `dashboard.data`：查询仪表板内单个数据组件，命令 `dashboard data --id <dashboardId> --entry-id <entryId> [--filter "名称=值" ... | --filters-file <filters.json>] [--page-size 100]`。先读 `dashboard info`，取 `entries[].entryId`（不能用底层 widgetId）及控件实际 `filterName`。`--filter` 可重复，按第一个 `=` 分隔且保留原始名称和值，拒绝空/全空白名称或值、缺少 `=`、同名重复；与 `--filters-file` 互斥。名称含 `=` 时使用文件。过滤 JSON 形如 `{"地区":["上海,北京"]}`，每个值严格为单元素非空字符串数组；日期区间键加 `_s/_e`，时间按钮组传已配置标签。未传控件保留保存值，未知/重名/树控件/清空覆盖均拒绝，不得失败后丢弃过滤重试。只返回首页或初始视图，不支持 --page、续页或 all-data；--page-size 控制有分页器表格的首页大小，默认保存页大小，图表及表头展开模式拒绝该参数。返回数据优先读取 `result`；使用前按[仪表板组件查询结果契约](dashboard-data-result.md)检查 normalization、单元格 state、行 kind、range 与 warnings，并参考明细表、分组表与 KPI 脱敏示例。NEXT_PAGE_UNSUPPORTED 表示原生结果仍有后续数据且 CLI 无法续页，不得将当前结果视作全量或将 totalRows 当作总数。缺少平台查询能力时回 UNSUPPORTED_FEATURE，不改用主题 widget.data 代替仪表板上下文。
 - `widget.data`：组件取数，用于数据核对与探查。`--id` 核对已保存组件的数据；`--subject-id` + `--file` 用临时 DSL 探查未落地的组件形态，不创建组件。与 `widget preview` 都返回字段与行数据，分工在：`preview` 附组件类型与后端摘要、仅限已保存组件；`widget.data` 可控取数范围（`--page`/`--page-size` 按页取数、`--all-data`/`--expand-all` 全量/展开档位），适合逐行核对与大数据量的分页检查。范围参数依赖平台构件提供取数范围 API：旧构件回 `UNSUPPORTED_FEATURE`，改用默认全量取数。
 - `definition`：回读公共数据集 Definition，常用于 update 前审查或恢复设计。
 - `source-preview`：验证公共数据集 JSON Definition 的源数据效果。
@@ -87,7 +88,7 @@
 
 | 文件类型 | 命令 |
 |---|---|
-| JSON | `public-ds.add`, `public-ds.source-preview`, `public-ds.update` |
+| JSON | `public-ds.add`, `public-ds.source-preview`, `public-ds.update`, `dashboard.data`（`--filters-file`） |
 | JavaScript 文本 | `analysis-ds.add`, `analysis-ds.update`, `calculated-field.validate`, `calculated-field.add`, `calculated-field.update`, `widget.add`, `widget.update`, `dashboard.add`, `dashboard.update` |
 | Model DSL 文本 | `metric-condition.update`, `drill-directory.update` |
 
@@ -115,6 +116,10 @@
 
 ### 7.3 Dashboard 与 Widget
 
+查询仪表板组件时，先从同一来源的 `dashboard info` 读取目标条目的 `queryFields`，用 `selectable=true` 的 `dId` 构造 `dashboard data --dimension-ids '["<dId>"]'`。这些 ID 是组件内部键，不是数据集 fieldId；目录包含关闭的字段，`used` 表示保存状态。省略参数沿用配置，`[]` 关闭全部可选维度；汇总组件的指标保留，明细表按列选择。可同时传 `--filter` 或 `--filters-file`；选择不清除过滤、不保存配置。插件直接依赖支持维度选择和发布来源查询的 Provider；编译构件与部署平台需具备相同接口契约。字段目录、空列表与兼容语义见 `docs/dashboard-command-design.md` 的查询契约。
+
+查询目录发布版时，从 `dashboard search` 的候选位置选定 `locations[].entryId`，对 `dashboard info` 和 `dashboard data` 都携带同一 `--directory-entry-id <directoryEntryId>`。先从该来源的 `info` 获取组件实例 `entries[].entryId` 和控件实际 `filterName`，再查询该组件。检查响应 `source=PUBLISHED_DIRECTORY` 及 `directoryEntryId`；普通来源为 `MY_ANALYSIS`。目录入口不能当作组件实例 ID，平台不支持或目录授权失败时不得丢弃入口参数后重试普通看板。
+
 仅知道仪表板名称时，用 `dashboard search "关键词"` 搜索「我的分析」和发布目录中有预览权限的仪表板；结果按 ID 合并并通过 `locations` 保留命中的来源。目录挂载的是主题，只有发布清单中的仪表板参与搜索，匹配仪表板名而非挂载主题名。用名称、主题、目录位置消歧；仅目录来源须保留 `id/entryId/publishId`，不能据此假定可使用原主题的 `info/dsl/preview` 或写命令，也不能自行拼接预览 URL。
 
 组件名称使用 `widget search "关键词"`，只搜索「我的分析」。两类搜索均支持省略关键词分页枚举，`--limit` 默认 100（1–500），`--offset` 默认 0 且必须为 limit 的整数倍，遍历 `pagination.hasNext/nextOffset`。仪表板的 total 和分页以合并后的结果为准。已知主题时用 `subject info` 枚举主题内资源，搜索命令不接受 `--subject-id`。搜索失败不能解释为没有资源。
@@ -130,8 +135,8 @@
 **按修改对象选择写入命令**：
 
 - 仅修改数据组件的字段、指标、聚合或图表配置时，从上述回显或 `widget dsl` 取得目标组件的完整 DSL，保留无关配置，修改后用 `widget update --id <widgetId> --file <widget.js>` 写回原组件。例如把“销售额”改成“利润”，只更新对应 Widget；仪表板布局和引用不变时无需执行 `dashboard update`。写后回查组件配置与数据，并核对仪表板中的目标组件。
-- 仅修改仪表板上一个条目（控件 / 文本 / 图片 / web / 复合过滤 / 组件引用条目的板侧面）时，用单条目写：`dashboard update-entry --id <dashboardId> --file <fragment.js>`（fragment 与 `dsl --entry` 切片同文法，是条目的完整新定义——切片读全条 → 改 → 写回；重名板带 `--entry-id` 消歧）。未点名条目原样保留；省略 `position` 沿用原槽位。新增 / 删除条目用 `dashboard add-entry` / `remove-entry`（被控件圈定或联动的条目删除会被拒，按错误信息先改引用）；`add-entry` 的 fragment 无切片可抄、需手写——单条目语句 + 可选 `position` 行，不包整板脚本，缺省 position 落首个空位。并发编辑带 `--expected-update-time`（上次写响应的 `lastUpdateTime`），不匹配报 `VERSION_CONFLICT`，重读后重试。
-- 修改仪表板布局、组件引用或板级配置时，保留完整仪表板 DSL 中的其他条目和配置，用 `dashboard update --id <dashboardId> --file <dashboard.js>` 写回；不能用只含目标条目的局部片段覆盖整板。若同时修改数据组件，先完成 `widget update` 并回查，再执行必要的仪表板更新。`dashboard update` 不接受内联数据组件定义，不能代替 `widget update` 修改组件字段。
+- 仅修改仪表板上一个条目（控件 / 文本 / 图片 / web / 复合过滤 / 组件引用条目的板侧面）时，用单条目写：`dashboard update-entry --id <dashboardId> --file <fragment.js>`（fragment 与 `dsl --entry` 切片同文法，是条目的完整新定义——切片读全条 → 改 → 写回；重名板带 `--entry-id` 消歧）。未点名条目原样保留；省略 `position` 沿用原槽位。新增 / 删除条目用 `dashboard add-entry` / `remove-entry`（被控件圈定或联动的条目删除会被拒，按错误信息先改引用）；`add-entry` 的 fragment 无切片可抄、需手写——单条目语句 + 可选 `position` 行，不包整板脚本，缺省 position 落首个空位。并发编辑带 `--expected-update-time`（读板响应或上次写响应的 `lastUpdateTime`），不匹配报 `VERSION_CONFLICT`，重读后重试。
+- 修改仪表板布局、组件引用或板级配置时，保留完整仪表板 DSL 中的其他条目和配置，用 `dashboard update --id <dashboardId> --file <dashboard.js>` 写回；不能用只含目标条目的局部片段覆盖整板。同名条目沿用原 entryId（名字即身份键；widget 引用条目跟随组件当前名，同组件改名后重声明仍沿用），新增条目的新 entryId 在响应 `entries[]` 直接给出。若同时修改数据组件，先完成 `widget update` 并回查，再执行必要的仪表板更新。`dashboard update` 不接受内联数据组件定义，不能代替 `widget update` 修改组件字段。并发编辑（用户手改后续改同理）带 `--expected-update-time`（读板响应 `info` / `dsl` 的 `lastUpdateTime`，或上次写响应的新值），不匹配报 `VERSION_CONFLICT`，重读后重试。
 
 DSL 语句面与 `widget template` / `dashboard template` 一致（见 handoff-dsl-writer 的 api 文档）；主题模型字段会按作用域保持根级指标、数据集字段或模型计算字段路径，该回显可作为模型名/字段名证据。回读含 warnings 字段（Bean 上文本 DSL 无法表达、被丢弃的配置会带出登记），改动前应审视 warnings，避免把不可达配置覆盖丢失——条目级 `*_DROPPED` 留痕的条目整板 `dashboard update` 会被写侧防丢守卫以 `ENTRY_LOSS_BLOCKED` 拒绝（处置口径见 handoff-dsl-writer 的 dashboard-dsl-api）。
 
@@ -151,6 +156,8 @@ DSL 语句面与 `widget template` / `dashboard template` 一致（见 handoff-d
 
 ### 7.7 Relationship
 
+`info/add/delete` 均由服务器内部试用开关控制，默认不开放。执行前检查能力清单；缺少所需命令时报告能力未开放，不调用或绕过门禁。
+
 `add` 是新增或替换语义。执行前用 `info` 判断关系是否已存在：不存在时可把 `delete` 作为创建后的清理命令；已存在时必须保存完整旧关系并以 `relationship.add` 作为恢复方案，不能把 `delete` 当作回滚。`delete` 前也要用 `info` 确认精确关系。
 
 ### 7.8 Subject
@@ -163,6 +170,49 @@ DSL 语句面与 `widget template` / `dashboard template` 一致（见 handoff-d
 
 执行 `subject add` 前通过实时 help 确认 `analysisType` 对应的 CLI 参数名和枚举值，并显式传参；省略参数的服务端默认值不能代替上述选择。创建后使用响应实际 ID 调用 `info`，核对名称、位置及 `analysisType` 与计划一致。`data-update` 不具备通用逆操作。`delete` 必须独立确认，并在计划中列出其包含资源影响。
 
+发布主题中的指定仪表板时，先用 `subject info` 确认主题和仪表板 ID，再按用户是否指定目录处理：指定目录先用 `directory list --privilege VIEW` 消歧；用户明确要求可直接发布时再用 `--privilege EDIT` 确认目录管理模块权限和目标编辑权限。发布请求使用 `--id`、`--name` 等普通参数，`--dashboard-ids '["d1","d2"]'` 传入 inline JSON 数组。省略 `parentEntryId` 时始终提交发布申请，不因用户管理其他目录而代选目录。响应为 `PUBLISHED` 才能告知已发布；`PENDING_APPROVAL` 只能告知申请已提交并保留申请 ID，不能当作目录已可访问。随后用 `subject publications --id <subjectId>` 回查；待审批结果没有入口地址，审批完成后再回查实际目录入口。发布挂载与仪表板内容保存分开，不能通过重复首次发布或无条件清快照声称完成同步；已有快照时遵循原生主题保存与数据更新结束后的生命周期。
+
+### 7.8.1 Directory
+
+`directory list` 是发布前的只读目录发现命令。省略 `parentId` 查询全部真实可见目录；指定时只查询该可见父目录的直接子目录。先完成权限过滤，再做关键词和分页；`EDIT` 只返回同时具备目录管理模块权限和目标编辑权限的目录。不要把主题内文件夹 ID、Dora 资源库文件夹 ID 或仅能查看的目录当作可直接发布目标。使用返回的 `id` 作为 `--parent-entry-id` 参数，用户未指定目录时省略该参数以保留申请语义。
+
+**完整示例：发布到指定目录**
+
+以下以用户指定的「经营分析 / 销售」目录为例。命令中的 `<主题ID>`、`<看板ID>`、`<目录ID>` 必须替换为查询确认的真实 ID；示例中的目录名称和路径不代表当前环境存在该资源。执行前按本 Skill 的固定入口检查实时 capability/help，并完成写入前复检。
+
+1. 查询用户可见的候选目录：
+
+   ```text
+   finebi-cli directory list "销售" --privilege VIEW --limit 50 --offset 0
+   ```
+
+   从返回的 `data.items` 中核对 `name`、完整 `path` 和 `id`；存在同名候选时让用户按路径选择。若 `hasMore=true`，递增 `--offset` 继续查询。选中目标条目的 `id` 作为 `<目录ID>`，不要取该条目的 `parentId`。已知父目录时，可用 `directory list --parent-id <父目录ID> --privilege VIEW` 查看其直接子目录。
+
+2. 用户要求直接发布时，检查同一个目标目录是否可直接发布：
+
+   ```text
+   finebi-cli directory list "销售" --privilege EDIT --limit 50 --offset 0
+   ```
+
+   完成分页后按第 1 步选定的 `id` 匹配，并核对 `canPublishDirectly`。目标不可直接发布时，说明需要审批，按用户意图继续申请；不要自动改选其他目录。
+
+3. 确认主题和看板归属，再携带目标目录 ID 发布：
+
+   ```text
+   finebi-cli subject info --id <主题ID>
+   finebi-cli subject publish --id <主题ID> --dashboard-ids '["<看板ID>"]' --name "销售分析看板" --parent-entry-id <目录ID>
+   ```
+
+   `--dashboard-ids` 是单个 JSON 数组参数。`--parent-entry-id` 使用第 1 步选定的目录 `id`；省略它不表示发布到默认目录。
+
+4. 回查发布记录：
+
+   ```text
+   finebi-cli subject publications --id <主题ID>
+   ```
+
+   按本次响应的 `publishId` 对照记录：`PUBLISHED` 才表示已发布，`PENDING_APPROVAL` 表示等待审批。调用超时或结果不明时先回查，不直接重试发布。
+
 ### 7.9 Metric Condition
 
 主题共享指标条件是挂在原始数值字段或模型指标上的聚合前过滤，保存后**影响主题内所有使用该指标的组件**；向用户确认时必须透出这一影响面。工作流：`metric-condition.dsl` 回读当前条件 → 与用户确认期望条件 → `metric-condition.update` 提交 DSL 文件 → 再次 `metric-condition.dsl` 验证。`update` 是整份替换：请求 DSL 的 `where(...)` 列表就是保存后的完整条件，修改前必须先回读完整现状；清空用显式 `clear()`。字段定位必须使用实际字段 ID（`analysis-ds info`、`model info` 或 `metric-condition.update` 响应返回），展示名不进命令。计算字段、记录数、带分组/别名/快速计算的引用和跨引擎条件字段会被拒绝，条件固定 AND 合并；保存后服务端回读比对不一致时返回 `UPDATE_FAILED`，按失败处理而不是当作已生效。

package/skills/finebi-cli-agent/references/dashboard-data-result.md

@@ -0,0 +1,219 @@
+# 仪表板组件查询结果契约
+
+## 1. 适用范围
+
+`result` 是插件根据本次 Provider 的预览结果及返回的组件配置生成的独立契约，`schemaVersion` 为 `"1"`。现有顶层字段保持原语义，`dashboard preview` 不使用此契约。未增加过滤生效回显。值表示组件查询结果（可能经过聚合、计算、分组、权限和脱敏处理），不承诺是数据库原始值。
+
+响应中的 `fields/rows` 是兼容投影：交叉表仅左侧分区、复杂图表仅首个模型，不能代替标准化结果。类型专属结构保留在原生 `previewResult` 中，由 `resultType=DETAIL/BIGROUP/BICROSS/CHART` 区分；不要与本契约的 resultType 枚举混用，也不能用旧 rows 猜测填补不可用值。
+
+## 2. 返回结构与完整性
+
+| 字段 | 语义 |
+| --- | --- |
+| `resultType` | `DETAIL_TABLE / GROUP_TABLE / CROSS_TABLE / CHART / UNKNOWN` |
+| `normalization` | `COMPLETE` 完整转换本次返回的数据结构；`PARTIAL` 有结构未覆盖；`UNSUPPORTED` 无适配。与单元格值是否可用、是否取得所有页独立 |
+| `range` | `mode/page/pageSize/pageUnit/hasNext/hasPrevious/total`，未知或不适用字段保留 JSON null |
+| `datasets[]` | 独立数据模型，含 `id/columns/rows/returnedRowCount`；图表共用同一模型对象时去重，不同模型不能直接拼接求和 |
+| `warnings[]` | 稳定原因码；结构未完整转换时必须检查原生 `previewResult`，不能把空 datasets 解释为业务无数据 |
+
+## 3. 分页与数量
+
+命令仅返回首页或初始视图，支持 `--page-size` 控制有分页器表格的首页大小，不支持指定页码或续页。`range.mode` 为 `PAGE / INITIAL_VIEW / UNPAGED / UNKNOWN`；PAGE 描述本次返回的是表格首页（page=1），不声明续页能力。明细表 pageUnit 为 ROW，普通分组表为 GROUP，展开后的 `returnedRowCount` 不必等于 pageSize。表头展开模式为 INITIAL_VIEW，不暴露普通页码和续页标志；图表为 UNPAGED。交叉表标准化范围为 UNKNOWN，原生纵向状态由现有顶层字段表达，横向状态需读取 previewResult。
+
+原生 `hasNext=true` 保持真实值，仅表示仍有后续数据；此时 `warnings` 包含 `NEXT_PAGE_UNSUPPORTED`，不得尝试续页或将当前结果宣称为全量。交叉表任一方向有后续数据也返回该警告；表头展开模式的 range 不提供续页标志，但原生结果标记仍有下一页时同样警告。该警告不改变 normalization：COMPLETE 只说明本次结构完整转换。
+
+`total` 结构为 `{value,unit}`，仅明细表采用有效的原生总数（unit=DETAIL_ROW）；普通分组总数未知（value=null、unit=GROUP），INITIAL_VIEW 的 total.value/unit 均为 null，图表不把模型行数当作查询总数。没有下一页不代表取得底层明细全集，也不排除组件自身 Top N、聚合等限制。
+
+## 4. 列、行与单元格
+
+列包含 `key/fieldId/name/type/encoding`。key 是当前 dataset 内唯一位置键（c0、c1…），不承诺跨查询稳定；fieldId 是结果字段 ID，不是底层数据集列 ID。类型仅采用可核实的结果/组件元数据：STRING 使用 STRING 编码，数值统一 DECIMAL + DECIMAL_STRING（支持规范科学计数法），明细表日期使用 DATE + EPOCH_MILLIS_STRING，未知类型为 UNKNOWN、encoding=null。不根据样例猜类型。数值字符串保留上游已有精度，不能恢复上游浮点误差。
+
+行结构为 `{kind,cells}`，cells 与 columns 位置对应。`kind` 为 DATA、SUBTOTAL、GRAND_TOTAL、UNKNOWN；正常聚合分组仍为 DATA，额外小计/总计用独立类型。明细行是 DATA，分组行依据原生 rowSumInfo；缺失或冲突为 UNKNOWN，不按“合计”等文本猜测。父节点的合计与子节点都保留，汇总时必须区分 kind；图表行没有统一的合计标记时为 UNKNOWN。
+
+单元格结构为 `{value,display,state,reason}`，null 不省略：
+
+| state | value 的含义 |
+| --- | --- |
+| AVAILABLE | 按列 type/encoding 可使用的查询值 |
+| NULL | 确认的结果空值，不承诺能区别数据库 NULL 与平台转换出的空值 |
+| UNAVAILABLE | 无法可靠取得值；展示文本独立保留，reason 指出原因 |
+| RESTRICTED | 原生权限标记或明确权限占位表明值受限，value=null；不区分无权限与脱敏的具体原因 |
+
+## 5. 各类型的值来源与限制
+
+明细表使用 value 通道，authority=false 时不暴露加密值。日期元数据明确为 DATE、DATE_DIMENSION、DATE_CREATED_BY_CALC 或 DATE_FROM_AGG_CALC 时，value 保留平台返回的 Unix epoch 毫秒整数文本（有符号 64 位范围），display 保留 formatText，缺失时采用 text。插件不转换时区，不从展示文本反推时间戳，也不承诺展示日期对应 UTC 零点。消费者应保留时间戳字符串或使用支持 64 位整数的解析方式，避免 JavaScript Number 精度损失；浮点数、日期标签、小数、科学计数法、空白及越界值标为 UNAVAILABLE / INVALID_TIMESTAMP_VALUE。此规则仅适用于明细表，不能套用到分组或图表的日期标签。
+
+分组指标使用 value，缺失时使用主工程保留的规范数值 text，绝不解析 formatText 的千分位、百分号、单位。分组字符串维度提供查询分组键；数值/日期分组键语义不能确认时为 UNAVAILABLE。字符串达到当前平台 cellCharLimit 时保守标记 POSSIBLY_TRUNCATED，不能声称它一定截断。类型缺失、展示专用值、缺少单元格分别标记不可用，不填造业务空值；日期也遵循这些规则及权限、空值规则。
+
+图表遍历 geom 模型和 shared 模型；已由平台处理的数值型指标可计算，字符串指标不反解析；维度字符串作为分组键，不能当作原始字段值。图表没有可直接采用的指标展示文本时 display=null。计算/缓存态未覆盖时为 PARTIAL，无内联模型时为 UNSUPPORTED。交叉表 v1 标记 UNSUPPORTED、warnings 包含 CROSS_TABLE_NORMALIZATION_UNSUPPORTED，完整原生数据继续保存在 previewResult。
+
+## 6. Agent 消费顺序
+
+消费顺序：检查 schemaVersion 和 normalization → 选择 dataset → 按列解释 AVAILABLE 单元格 → 根据 kind 区分汇总行 → 检查 range 与 warnings 并说明取数范围。出现 NEXT_PAGE_UNSUPPORTED 时必须说明仍有数据且命令不支持获取后续页。UNKNOWN 行不能自动当作明细累加。存在 PARTIAL、UNSUPPORTED 或 UNAVAILABLE 时应说明缺口，不能转用旧 rows 猜测填补。
+
+KPI 的单个 AVAILABLE 指标可以直接读取；其 kind=UNKNOWN 表示缺少统一的行分类依据，不表示指标值不可用。不要因为 kind 未知而自动丢弃这个指标，也不要把它与其他未知行直接累加。
+
+命令参数、实例发现和过滤方式见[命令工作流](command-workflows.md)。此参考文档随 Skill 分发，无需访问工程源码即可解释结果。
+
+## 7. 脱敏返回示例
+
+以下只展示 `data.result`，不是整个响应 envelope。示例沿用实际查询的结构和状态，字段 ID、业务 ID、日期及统计数值均已替换为虚构内容，业务分类使用通用示例值，不可作为真实业务结论。三个示例代表同一示例看板：共 10 份合同、金额 50,000、购买数量 12；明细仅取前 2 行。
+
+### 7.1 明细表
+
+PAGE 模式，第 1 页共 2 行，hasNext=true，NEXT_PAGE_UNSUPPORTED 表明仍有数据且无法续页。合同编号保留字符串语义；金额的 value 与带千分位的 display 分离。签约时间的 value 为毫秒时间戳字符串，display 为平台日期文本，state=AVAILABLE。COMPLETE 不代表拿到了全部 10 行或每个单元格都有可计算值。
+
+```json
+{
+  "schemaVersion": "1",
+  "resultType": "DETAIL_TABLE",
+  "normalization": "COMPLETE",
+  "range": {
+    "mode": "PAGE",
+    "page": 1,
+    "pageSize": 2,
+    "pageUnit": "ROW",
+    "hasNext": true,
+    "hasPrevious": false,
+    "total": {"value":10,"unit":"DETAIL_ROW"}
+  },
+  "datasets": [
+    {
+      "id": "main",
+      "columns": [
+        {"key":"c0","fieldId":"example_detail_c0","name":"合同ID","type":"STRING","encoding":"STRING"},
+        {"key":"c1","fieldId":"example_detail_c1","name":"客户ID","type":"STRING","encoding":"STRING"},
+        {"key":"c2","fieldId":"example_detail_c2","name":"合同类型","type":"STRING","encoding":"STRING"},
+        {"key":"c3","fieldId":"example_detail_c3","name":"合同付款类型","type":"STRING","encoding":"STRING"},
+        {"key":"c4","fieldId":"example_detail_c4","name":"合同金额","type":"DECIMAL","encoding":"DECIMAL_STRING"},
+        {"key":"c5","fieldId":"example_detail_c5","name":"购买数量","type":"DECIMAL","encoding":"DECIMAL_STRING"},
+        {"key":"c6","fieldId":"example_detail_c6","name":"合同签约时间","type":"DATE","encoding":"EPOCH_MILLIS_STRING"},
+        {"key":"c7","fieldId":"example_detail_c7","name":"是否已经交货","type":"STRING","encoding":"STRING"}
+      ],
+      "rows": [
+        {
+          "kind": "DATA",
+          "cells": [
+            {"value":"CONTRACT-001","display":"CONTRACT-001","state":"AVAILABLE","reason":null},
+            {"value":"CUSTOMER-001","display":"CUSTOMER-001","state":"AVAILABLE","reason":null},
+            {"value":"示例合同","display":"示例合同","state":"AVAILABLE","reason":null},
+            {"value":"一次性付款","display":"一次性付款","state":"AVAILABLE","reason":null},
+            {"value":"1000.0","display":"1,000","state":"AVAILABLE","reason":null},
+            {"value":"1.0","display":"1","state":"AVAILABLE","reason":null},
+            {"value":"1767571200000","display":"2026-01-05","state":"AVAILABLE","reason":null},
+            {"value":"否","display":"否","state":"AVAILABLE","reason":null}
+          ]
+        },
+        {
+          "kind": "DATA",
+          "cells": [
+            {"value":"CONTRACT-002","display":"CONTRACT-002","state":"AVAILABLE","reason":null},
+            {"value":"CUSTOMER-002","display":"CUSTOMER-002","state":"AVAILABLE","reason":null},
+            {"value":"示例合同","display":"示例合同","state":"AVAILABLE","reason":null},
+            {"value":"一次性付款","display":"一次性付款","state":"AVAILABLE","reason":null},
+            {"value":"2000.0","display":"2,000","state":"AVAILABLE","reason":null},
+            {"value":"2.0","display":"2","state":"AVAILABLE","reason":null},
+            {"value":"1767657600000","display":"2026-01-06","state":"AVAILABLE","reason":null},
+            {"value":"是","display":"是","state":"AVAILABLE","reason":null}
+          ]
+        }
+      ],
+      "returnedRowCount": 2
+    }
+  ],
+  "warnings": ["NEXT_PAGE_UNSUPPORTED"]
+}
+```
+
+### 7.2 分组表
+
+表头展开模式为 INITIAL_VIEW，page/hasNext/total 不提供普通分页含义。GRAND_TOTAL 与 DATA 都包含 50,000，不能相加成 100,000；总计行的分类单元格为 MISSING_CELL，不应把它当作业务 NULL 分组。
+
+```json
+{
+  "schemaVersion": "1",
+  "resultType": "GROUP_TABLE",
+  "normalization": "COMPLETE",
+  "range": {
+    "mode": "INITIAL_VIEW",
+    "page": null,
+    "pageSize": null,
+    "pageUnit": null,
+    "hasNext": null,
+    "hasPrevious": null,
+    "total": {"value":null,"unit":null}
+  },
+  "datasets": [
+    {
+      "id": "main",
+      "columns": [
+        {"key":"c0","fieldId":"example_group_c0","name":"合同类型","type":"STRING","encoding":"STRING"},
+        {"key":"c1","fieldId":"example_group_c1","name":"合同数","type":"DECIMAL","encoding":"DECIMAL_STRING"},
+        {"key":"c2","fieldId":"example_group_c2","name":"合同金额","type":"DECIMAL","encoding":"DECIMAL_STRING"},
+        {"key":"c3","fieldId":"example_group_c3","name":"购买数量","type":"DECIMAL","encoding":"DECIMAL_STRING"}
+      ],
+      "rows": [
+        {
+          "kind": "GRAND_TOTAL",
+          "cells": [
+            {"value":null,"display":null,"state":"UNAVAILABLE","reason":"MISSING_CELL"},
+            {"value":"10.0","display":"10","state":"AVAILABLE","reason":null},
+            {"value":"5.0E+4","display":"50,000","state":"AVAILABLE","reason":null},
+            {"value":"12.0","display":"12","state":"AVAILABLE","reason":null}
+          ]
+        },
+        {
+          "kind": "DATA",
+          "cells": [
+            {"value":"示例合同","display":"示例合同","state":"AVAILABLE","reason":null},
+            {"value":"10.0","display":"10","state":"AVAILABLE","reason":null},
+            {"value":"5.0E+4","display":"50,000","state":"AVAILABLE","reason":null},
+            {"value":"12.0","display":"12","state":"AVAILABLE","reason":null}
+          ]
+        }
+      ],
+      "returnedRowCount": 2
+    }
+  ],
+  "warnings": []
+}
+```
+
+### 7.3 KPI
+
+KPI 使用 CHART 结果，UNPAGED 不提供查询总行数。5.0E+4 是十进制字符串，表示 50,000；display=null 表示没有可直接采用的展示文本。kind=UNKNOWN 不妨碍读取单个 AVAILABLE 指标，但不能据此跨行自动累加。
+
+```json
+{
+  "schemaVersion": "1",
+  "resultType": "CHART",
+  "normalization": "COMPLETE",
+  "range": {
+    "mode": "UNPAGED",
+    "page": null,
+    "pageSize": null,
+    "pageUnit": null,
+    "hasNext": null,
+    "hasPrevious": null,
+    "total": {"value":null,"unit":null}
+  },
+  "datasets": [
+    {
+      "id": "model0",
+      "columns": [
+        {"key":"c0","fieldId":"example_kpi_c0","name":"合同总金额","type":"DECIMAL","encoding":"DECIMAL_STRING"}
+      ],
+      "rows": [
+        {
+          "kind": "UNKNOWN",
+          "cells": [
+            {"value":"5.0E+4","display":null,"state":"AVAILABLE","reason":null}
+          ]
+        }
+      ],
+      "returnedRowCount": 1
+    }
+  ],
+  "warnings": []
+}
+```

package/skills/finebi-cli-agent/references/dashboard-dsl-api.md

@@ -23,8 +23,10 @@
 `remove-entry`（被控件圈定或联动的条目删除会被拒，按错误信息先改引用）。`add-entry`
 的 fragment 无切片可抄、需手写：单条目语句（上文各条目语句形态之一）+ 可选
 `position` 行，不包 `DashboardDsl.create` 整板脚本；缺省 position 落首个空位。
-并发编辑带 `--expected-update-time`（上次写响应的 `lastUpdateTime`），不匹配会报
-`VERSION_CONFLICT`，重读后重试。
+并发编辑（含用户在设计器手改后再让 Agent 续改）带 `--expected-update-time`——基准取
+读板响应（`info` / `dsl` 的 `lastUpdateTime`）或上次写响应的新值，不匹配会报
+`VERSION_CONFLICT`（附当前值），重读后重试。entryId 按条目名稳定：设计器保存与整板
+`update` 下同名条目沿用原值，新增条目的新值从 update 响应 `entries[]` 直接可得。
 
 **写新看板前先取场景样例**：`dashboard template`（默认场景）返回场景目录与通用设计要点，
 `dashboard template --scenario <id>` 取某一个场景的完整可抄脚本 + `guidance` 设计要点
@@ -342,13 +344,28 @@ TextItem.of("标题", "销售概览")
 |------------------------------------------------------|---------------|
 | `.withTitle("标题")`                                   | 设置文本组件标题。     |
 | `.withShowTitle(true)`                               | 设置是否显示文本组件标题。 |
-| `.withStyle({"fontSize":"20px", "color":"#333333"})` | 设置文本样式。       |
+| `.withStyle({"backgroundColor":"#fffbe6"})` | 设置组件背景色；不设置正文字体样式。 |
 
 业务补充：
 
 - `name` 是文本组件业务名。
-- `content` 是文本正文内容（纯文本），或 `RichText.of()...build()` 富文本（动态字段值，见 §6.8）。
-- `style` 是样式键值对，可用于字体大小、颜色、字重、背景色等。
+- 纯文本正文使用 `TextItem.of(name, text)`；带样式的静态文本或动态字段使用 `TextItem.ofRichText(name, RichText.of()...build())`，见 §6.8。
+- `withStyle` 是组件级样式，前端只消费 `backgroundColor`。正文的字号、颜色、加粗和字体使用 `styled(...)`，不能放在 `withStyle` 中。
+
+静态标题也通过富文本设置字体样式：
+
+```js
+TextItem.ofRichText("看板标题", RichText.of()
+    .line(styled("经营目标达成分析看板", {
+        "font-size": "32px",
+        "color": "#76b7b2",
+        "font-weight": "bold",
+        "font-family": "STKaiti, Kai, KaiTi, 楷体"
+    }))
+    .build())
+```
+
+`styled` 使用 CSS 属性名（如 `font-size`，不能写 `fontSize`）；字体能否呈现取决于浏览器所在设备可用的字体。完整富文本 API 和样式规则见 §6.8。
 
 ### 6.3 ImageItem
 
@@ -449,7 +466,7 @@ w/h 取值 100~10000（整数）；省略 `.adaptive(...)` 语句 = 自动适应
 | `.line("文本", fieldRef, styled(...))` | 追加一行：静态文本 / 字段引用 / 行内样式文本段混排（字段引用见 §7 字段写法，dim/sum/avg/count 均可；也支持已保存计算字段 `measureID("配置 ID").dim()` 与业务模型字段 `model("模型").dataset("数据集").dim("字段")`）。 |
 | `styled(fieldRef, {"font-weight": "bold"})` | 行内样式**字段值**段：给动态字段值加行内样式（对齐编辑器里选中已插入的字段再点加粗/改色）。样式规则与下面的 `styled("文本", ...)` 完全一致。 |
 | `styled("文本", {"font-size": "20px"})` | 行内样式文本段：key 必须是 CSS 属性名（小写字母+连字符，如 font-size / color / font-weight），写入内联 `<span style="...">`；camelCase（如 fontSize）前端会静默丢弃，编译期直接报错。 |
-| `formatted(fieldRef, NumberFormatModel.number(...))` | 数值格式字段值：`formatted(from("销售表").sum("销售额"), NumberFormatModel.number(2))`。格式工厂：`NumberFormatModel.number(小数位[, NumberFormatModelScale.THOUSAND, "单位", 千分位])` / `NumberFormatModel.percentage(小数位, 千分位)`。**只作用于指标/数值值（sum/count 等聚合），dim 引用按维度文本处理格式不生效**；`auto()` 等于未设置会被编译期拒绝（用裸字段引用）。 |
+| `formatted(fieldRef, NumberFormatModel.number(...))` | 数值格式字段值：`formatted(from("销售表").sum("销售额"), NumberFormatModel.number(2))`。格式工厂：`NumberFormatModel.number(小数位[, NumberFormatModelScale.THOUSAND, "单位", 千分位])` / `NumberFormatModel.percentage(小数位, 千分位)`。**只作用于指标/数值值（sum/count 等聚合），dim 引用按维度文本处理格式不生效**；默认 `auto()` 等于未设置会被编译期拒绝（用裸字段引用）；带参数的自动格式可用，参数与单位规则见 [数值格式工厂](widget-dsl-api.md#8-数值格式工厂)。 |
 | `fieldValue(fieldRef)` | 带字段级配置的动态字段值（可选链，全部可省 = 平台默认）：`.sort(SortOrder.ASC/DESC)` / `.sortByField(fieldRef, SortOrder.*)`（跨字段排序）/ `.dateFormat(FieldValue.SPLIT/CHINESE/SLASH)`（日期显示格式）/ `.numberFormat(NumberFormatModel...)` / `.where(fieldRef, "eq"\|"in"\|"between"\|"not_null", [值...])`（指标条件，可多次 AND 叠加；数值 between 前可用 `.closeRange(includeMin, includeMax)` 声明端点开闭，省略 = 全闭）/ `.showDefaultData()`，末尾 `.build()`。例：`fieldValue(from("销售表").dim("签约时间")).dateFormat(FieldValue.CHINESE).sort(SortOrder.DESC).build()`。**分组/汇总语义不在这里写**——由字段引用本身承载（`dim(名, DimensionGrouping.dateGranularity("YEAR_MONTH"))` / `sum(...)` / `avg(...)`）。字段类型门禁与前端字段面板一致：排序/显示默认数据限文本/日期字段，时间格式限日期字段，数值格式与指标条件限数值字段。指标条件的算子族按**被过滤字段**类型分派（数值：eq/between/not_null；文本：eq/in/not_null；日期：eq/between/not_null），过滤值必须是静态值（公式过滤平台不支持）。 |
 | `link("文本", "https://...")` | 超链接文本段：`line("详见 ", link("官网", "https://www.finebi.com"))`。查看态渲染为可点击链接；`javascript:` 协议编译期拒绝。只包静态文本——字段值/行内样式不能带链接（反读遇该形态丢弃链接保内容并给 `RICH_TEXT_LINK_DROPPED` 提示）。 |
 | `widgetName()` | 组件自身名称：查看态解析为组件在主题里的名字（组件改名后自动跟随）。**只有组件标题可用**——文本组件没有「组件名」插入项（写进文本组件会编译期报错，前端查看态也只会渲染成「元素被删除」）。 |
@@ -777,7 +794,7 @@ DashboardDsl.create("销售总览")
 ```js
 DashboardDsl.create("经营速览")
     .content()
-    .text(TextItem.of("核心指标", RichText.of()
+    .text(TextItem.ofRichText("核心指标", RichText.of()
             .line("总销售额：", from("销售表").sum("销售额"), " 元")
             .line("订单数：", count(from("销售表").dim("订单号")))
             .build()))

package/skills/finebi-cli-agent/references/file-to-dashboard.md

@@ -20,7 +20,7 @@
 | 上传 | `analysis-ds upload-excel --file "<原始文件绝对路径>"` | `data.attachId`；不是表 ID | `ok=true` 且 attachId 非空；上传没有独立 info，建表验证其可消费性 |
 | 主题 | 按 [Subject 工作流](command-workflows.md#78-subject) 确认来源兼容性后复用主题，或 `subject add` 显式指定分析类型；参数以实时 help 为准 | 实际 subject ID | `subject info` 回查名称、位置和分析类型；省略 name 使用默认名称；失败但含 data.id 时先检查该资源，不重复创建 |
 | 分析表 | `analysis-ds template` 后生成 JS；`analysis-ds add --subject-id <实际主题ID> --file <table.js>` | 每张表的实际 ID、name 和字段 | `analysis-ds info/preview`，核对字段、类型、行数和样本 |
-| 关联 | `relationship info`；核对两侧键、粒度及唯一性后 `relationship add` | 真实关联及基数 | `relationship info` 与跨表查询验证，防止多对多重复累计 |
+| 关联 | 先按 [Relationship 工作流](command-workflows.md#77-relationship) 检查能力开放；`relationship info`；核对两侧键、粒度及唯一性后 `relationship add` | 真实关联及基数 | `relationship info` 与跨表查询验证，防止多对多重复累计 |
 | 公式 | `calculated-field context --subject-id <实际主题ID>`；必须使用 `formula functions --subject-id <实际主题ID>` 查询目标主题面板（见 command-workflows.md §7.2）；生成 `CalculatedFieldModel` JS，`validate` 后 `add` | 计算字段配置 ID、依赖与预期值 | info/dsl 回查；表达式通过还需在组件出数中核对结果 |
 | 组件 | 按 widget template/API 生成 JS，再 `widget add`；物理数值字段作维度/分类/粒度时先 `measure copy --as dimension` 注册副本（缺副本时 add 报错并指路该命令） | 实际组件 ID、准确名称 | `widget info/preview`；核对指标、分组、筛选和排序 |
 | 仪表板 | 按 dashboard template/schema/API 生成引用组件的 JS，再 `dashboard add` | 实际仪表板 ID/链接 | `dashboard dsl/preview`；核对组件、布局、筛选及关键数字 |

package/skills/finebi-cli-agent/references/handoff-contract.md

@@ -146,6 +146,8 @@
 
 ## 跨数据集关系
 
+关系命令的可用性先按 [Relationship 工作流](command-workflows.md#77-relationship) 检查；需要关系证据但缺少 `relationship info` 时进入 `BLOCKED`，不得假定关系存在或继续生成依赖该关系的制品。
+
 当某个 `requestedWidgets[]`（通过其 `encodings[].datasetKey`）或 `requestedDashboard` 基于字段的过滤器，引用了归属于不同
 `datasets[].key` 的字段时，这些数据集背后的分析表之间必须存在已确认的关系，FineBI 才能正确关联对应数据。解析器必须：
 

package/skills/finebi-cli-agent/references/mapping-rules.md

@@ -325,7 +325,7 @@ presentation()
 文本组件 content 支持动态字段值（见 `docs/dsl/dynamic-field-value-design.md`）：
 
 ```
-TextItem.of("kpi", RichText.of()
+TextItem.ofRichText("kpi", RichText.of()
         .line("总销售额：", from("Sales").sum("amount"), " 元")
         .line("按地区：", from("Sales").dim("region"))
         .build())

package/skills/finebi-cli-agent/references/widget-dsl-api-examples.md

@@ -455,3 +455,21 @@ WidgetDsl.create("手机参数对比").chart().radar()
     .radarOptions(RadarOptions.polygon().marker(true).symbol("triangle"))
     .build();
 ```
+
+### 隐藏展示字段
+
+设计器"展示字段"开关的 DSL 表达：维度绑定进轴但查看态不展示（`used=false`，槽位保留）。
+`.hidden()` 叠加在维度表达式末尾，可与分组、别名、经纬度组合；回读输出同一后缀。
+
+```js
+WidgetDsl.create("区域销售表")
+    .chart().table()
+    .dimension(from("销售表").dim("地区"))
+    .dimension(from("销售表").dim("月份",
+        DimensionGrouping.dateGranularity("YEAR_MONTH"), "月份").hidden())
+    .measure(from("销售表").sum("销售额"))
+    .build()
+```
+
+适用场景：按隐藏粒度参与分组/计算，但界面只展示地区一级；或反读设计器组件时
+保留其"已关闭展示"的字段设置。同一字段多处引用须 hidden 状态一致，否则保存报错（明细表例外：同字段多列按列独立生效）。