@finebi/finebi-cli 1.4.0 → 1.6.0

package/README.md

@@ -27,6 +27,7 @@ finebi-cli capabilities --help
 finebi-cli config --help
 finebi-cli auth --help
 finebi-cli capability --help
+finebi-cli app --help
 ```
 
 Dynamic resource help, such as `finebi-cli <resource> --help`, is loaded from the FineBI capability cache. Login refreshes this cache automatically:
@@ -40,8 +41,38 @@ finebi-cli <resource> --help
 finebi-cli <resource> <command> [options]
 ```
 
+Create and inspect a local dynamic web app project without connecting to FineBI:
+
+```powershell
+finebi-cli app create --name sales-dashboard --path D:\work
+finebi-cli app inspect --path D:\work\sales-dashboard
+```
+
+`app create` copies the bundled `web-app` template, sets the project npm name, and records the template version in `public/app-config.json`. It rejects an existing destination and does not install dependencies or run project scripts. `app inspect` checks the local configuration and reports `remoteValidated: false`; use the generated project to perform the real login and data request checks in a browser.
+
 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 +123,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.6.0",
   "description": "FineBI dynamic capability command line client.",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -14,7 +14,8 @@
   "files": [
     "src",
     "skills",
-    "README.md"
+    "README.md",
+    "templates"
   ],
   "engines": {
     "node": ">=18.17"
@@ -23,9 +24,9 @@
     "prepack": "node ../scripts/build-finebi-cli-agent.mjs",
     "test:pack": "node ../scripts/test-cli-package.mjs",
     "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:unit": "node --test tests/unit/access-key.test.js tests/unit/app.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/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: finebi-cli-agent
-description: 使用 FineBI CLI 查询和管理 FineBI 资源，生成并应用组件（Widget）和仪表板（Dashboard）DSL，优先使用内置 CLI，也支持已安装的全局 @finebi/finebi-cli。用户需要查看或操作分析主题、数据集、计算字段、图表组件、仪表板，或配置 FineBI CLI 连接与认证时使用。
+description: 使用 FineBI CLI 查询和管理 FineBI 资源，生成并应用组件（Widget）和仪表板（Dashboard）DSL，优先使用内置 CLI，也支持已安装的全局 @finebi/finebi-cli。用户需要查看或操作分析主题、数据集、计算字段、图表组件、仪表板，配置 FineBI CLI 连接与认证，或生成动态 HTML 看板、数据 Web 应用时使用。
 ---
 
 # FineBI CLI Agent
@@ -18,12 +18,14 @@ description: 使用 FineBI CLI 查询和管理 FineBI 资源，生成并应用
 
 ## 按需读取参考
 
+- 生成动态 HTML 页面或数据 Web 应用时，读取 [应用模板工作流](references/web-app.md)，通过本地 app create 创建工程，再遵循项目 AGENTS.md。
+
 - 首次处理业务命令时，读取 [命令工作流](references/command-workflows.md) 的公共约束和目标命令族章节。
 - 包含非只读动作时，读取 [变更计划与删除确认契约](references/mutation-confirmation-contract.md) 的计划、复检和验证规则；包含 `delete` 或失败清理时再读对应章节。
 - 规划 Widget/Dashboard 时按当前场景读取 [场景工作流](references/scenario-workflows.md)；构造或消费交接对象时读取 [语义交接契约](references/handoff-contract.md) 和 [DSL 输入契约](references/dsl-handoff-contract.md) 的公共结构及当前场景字段。
-- 生成 Widget DSL 时，读取 [映射规则](references/mapping-rules.md) 和 [Widget DSL API](references/widget-dsl-api.md) 的公共约束及所用组件、字段类型和 API 章节。
+- 生成 Widget DSL 时，读取 [映射规则](references/mapping-rules.md)，并按需读取 [Widget DSL API](references/widget-dsl-api.md) 导航的拆分文件，不一次加载全部：写组件前读 [widget-dsl-core.md](references/widget-dsl-core.md)（根入口/字段工厂/Builder）；配置图表类型与通道编码读 [widget-dsl-encodings.md](references/widget-dsl-encodings.md)；调整样式、视觉通道、轴或排序读 [widget-dsl-styles.md](references/widget-dsl-styles.md)；配置过滤、配色、数值格式或查枚举读 [widget-dsl-contexts.md](references/widget-dsl-contexts.md)。
 - 需要可运行的推荐写法示例（分区折线/双轴/表格属性等）时，读取 [Widget DSL 写法示例](references/widget-dsl-api-examples.md)。
-- 生成 Dashboard DSL 时，读取 [Dashboard DSL API](references/dashboard-dsl-api.md) 的公共约束和所用布局、引用及 API 章节；仅引用已有组件时无需加载 Widget API。产物顺序不清楚时读取 [产物顺序](references/artifact-ordering.md)。
+- 生成 Dashboard DSL 时，按需读取 [Dashboard DSL API](references/dashboard-dsl-api.md) 导航的拆分文件，不一次加载全部：写板前读 [dashboard-dsl-core.md](references/dashboard-dsl-core.md)（根入口/布局/移动端/字段写法）；挂载或配置具体条目类型读 [dashboard-dsl-items.md](references/dashboard-dsl-items.md)；需要可抄写法或场景模板读 [dashboard-dsl-examples.md](references/dashboard-dsl-examples.md)。仅引用已有组件时无需加载 Widget API。产物顺序不清楚时读取 [产物顺序](references/artifact-ordering.md)。
 - 解释或生成公式时，先用 `formula functions` 查询当前 FineBI 公式面板；绑定真实字段后，用 `calculated-field validate` 执行原生校验。
 - 同一连续任务内复用未变化的已读内容；只有文件变化、进入未读能力，或上下文压缩后所需规则已不可用时，才补读相关部分。实时 capability、目标和文件摘要校验仍按变更契约执行，不以文档复用代替。
 
@@ -89,7 +91,9 @@ node "<skill-dir>/scripts/finebi-cli-runner.mjs" run <resource> <command> ... --
 
 需要生成 JSON Definition 时，先 `inspect` 对应的 `template` 命令；实时 capability 为 `mutation:false` 时执行它，并以返回的 `definitionSchema`、`definitionTemplate` 和填写指引生成文件。不得凭经验猜测 Definition 结构。
 
-模型指标集不走分析表或公共数据集搜索。先调用 `subject info` 查看 `resources.models` 主题模型摘要，再用 `model search --subject-id <subjectId>` 消歧主题内模型，并用 `model info --subject-id <subjectId> --id <modelId>` 获取具体指标、数据集字段和模型计算字段。若用户要求的指标集尚未属于主题，单独以 `public-ds search` 确认唯一的 `type=METRIC_SET` 来源和可编辑目标主题；`model add` 返回的主题内模型 ID 才可用于 `model info/delete` 和字段回查，来源 ID 不得写进 DSL。模型目录命令未出现在实时 capability 时，既有 `widget dsl` 输出中的 `model(...)` 仍可作为只读证据；两类证据都不存在时进入 `BLOCKED`。不得把同名分析表改写成模型指标集。
+模型来源探查先用 `public-ds search` 确认 `type=METRIC_SET` 来源，再调用 `model source-info --id <sourceId>` 获取字段目录和来源展示提示，无需主题。字段状态、来源文本与后续命名空间确认按 [Model 工作流](references/command-workflows.md#76-model-metric-set) 判读。
+
+生成制品时，先调用 `subject info` 查看 `resources.models` 主题模型摘要，再用 `model search --subject-id <subjectId>` 消歧主题内模型，并用 `model info --subject-id <subjectId> --id <modelId>` 获取具体指标、数据集字段和模型计算字段。若用户要求的指标集尚未属于主题，确认唯一来源和可编辑目标主题；`model add` 返回的主题内模型 ID 才可用于 `model info/delete` 和字段回查，来源探查不能替代该确认，来源 ID 不得写进 DSL。模型目录命令未出现在实时 capability 时，既有 `widget dsl` 输出中的 `model(...)` 仍可作为只读证据；两类证据都不存在时进入 `BLOCKED`。不得把同名分析表改写成模型指标集。
 
 ### 4. 生成 Widget/Dashboard DSL
 

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

@@ -16,15 +16,17 @@
 
 ## 2. 当前命令矩阵
 
+动态 HTML 看板与数据 Web 应用使用本地 `app create/inspect`，不属于远端 capability；具体开发流程见[应用模板工作流](web-app.md)。
+
 以下矩阵仅列出常见资源命令示例；实际可执行范围以实时 capability 为准。
 
 | 资源 | 只读（`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` | — |
-| `model` | `info`, `search` | `add`, `delete` |
+| `model` | `info`, `search`, `source-info` | `add`, `delete` |
 | `metric-condition` | `dsl` | `update` |
 | `measure` | `info`, `search` | `copy`, `transform`, `delete` |
 | `geographic-role` | `info`、`dsl`、`catalog`、`match`（显式输入值） | `set`、`clear` |
@@ -70,13 +72,14 @@
 - `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 的源数据效果。
 - `operator-schema`：返回分析数据集 DSL 语句面（可写步骤类型 + 表级声明 + 签名 + 约束；`--type` 过滤单个类型）。
 - `validate`：编译并验证计算字段 JavaScript，不执行保存。
 - `data-connection.tables`：仅在数据集层没有合理候选后，列出指定数据连接下的表。
-- `model.search`：在已确认主题内定位当前用户可查询的模型指标集；`model.info`：展开选定模型的指标、数据集字段和模型计算字段目录；`model.add`：将 `public-ds.search` 中已确认的 `type=METRIC_SET` 来源 ID 挂入可编辑主题，返回的主题内模型 ID 才可用于 `model.info/delete`；`model.delete`：移除该主题内模型并保留来源指标集。
+- `model.source-info`：使用 `public-ds.search` 的 `type=METRIC_SET` 来源 ID，无主题探查来源字段目录和来源展示提示；`model.search`：在已确认主题内定位当前用户可查询的模型指标集；`model.info`：展开选定模型的指标、数据集字段和模型计算字段目录；`model.add`：将已确认来源挂入可编辑主题，返回的主题内模型 ID 才可用于 `model.info/delete`；`model.delete`：移除该主题内模型并保留来源指标集。
 - `metric-condition.dsl`：按 `--field-id` 回读主题共享指标条件的可编辑 `MetricConditionModel` DSL；字段无条件时返回 `clear()` 形态，写回即幂等。
 - `public-ds-folder.search`：定位公共数据目录。
 - `relationship.info`：确认当前关系；执行 add/delete 前必须调用。
@@ -87,7 +90,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 +118,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 +137,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）。
 
@@ -145,12 +152,16 @@ DSL 语句面与 `widget template` / `dashboard template` 一致（见 handoff-d
 
 ### 7.6 Model Metric Set
 
-先用 `subject.info` 或 `model.search` 确认目标主题中的既有模型。需要将公共来源指标集加入主题时，先用 `public-ds.search` 确认唯一的 `type=METRIC_SET` 候选和来源 ID，再确认目标主题可编辑；`model.add --subject-id <subjectId> --id <sourceId>` 成功后必须使用响应中的主题内模型 ID 调用 `model.info` 回查名称、归属与字段目录。来源 ID 不能用于 `model.info` 或 `model.delete`，也不能写入 DSL。
+仅探查来源或尚无主题时，先用 `public-ds.search` 确认 `type=METRIC_SET` 候选和来源 ID，再执行 `model.source-info --id <sourceId>`。它只读返回 `fields` 字段目录、来源展示提示与原生已报告的无效/缺失项，不返回数据行，也不自动创建或修改主题。读取字段时检查 `valid`、`invalidFieldIds` 和 `missingFieldIds`；缺失清单不保证穷尽所有断链。`sourceName` 是原生来源展示文本，可能是表名、维度来源或本地化分组；不能据此推断 DSL 命名空间或数据集 ID。`aggregate` 仅表示已经聚合，不能据此选择 `SUM`/`AVG` 等函数。
+
+需要生成组件或仪表板 DSL 时，先用 `subject.info` 或 `model.search` 确认目标主题中的既有模型。需要将公共来源指标集加入主题时，先确认唯一来源和目标主题可编辑；`model.add --subject-id <subjectId> --id <sourceId>` 成功后必须使用响应中的主题内模型 ID 调用 `model.info` 回查名称、归属与字段目录，取得最终命名空间和真实 ID。只有来源探查结果时尚不能构建主题内模型交接对象。来源 ID 不能用于 `model.info` 或 `model.delete`，也不能写入 DSL。
 
 `model.delete` 前重新用 `model.search` 或 `model.info` 确认主题内模型 ID、名称和归属。它只移除主题关联，保留来源指标集；因此必须按删除确认流程执行。模型字段生成 DSL 时，根级指标使用 `model(name).metrics()`，模型表字段使用 `model(name).dataset(datasetName)`，模型计算字段使用 `model(name).calculated()`；模型根级维度和记录数不支持。
 
 ### 7.7 Relationship
 
+`info/add/delete` 均由服务器内部试用开关控制，默认不开放。执行前检查能力清单；缺少所需命令时报告能力未开放，不调用或绕过门禁。
+
 `add` 是新增或替换语义。执行前用 `info` 判断关系是否已存在：不存在时可把 `delete` 作为创建后的清理命令；已存在时必须保存完整旧关系并以 `relationship.add` 作为恢复方案，不能把 `delete` 当作回滚。`delete` 前也要用 `info` 确认精确关系。
 
 ### 7.8 Subject
@@ -163,6 +174,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": []
+}
+```