@finebi/finebi-cli 1.6.0 → 1.6.2

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

@@ -1,13 +1,13 @@
-# 仪表板组件查询结果契约
-
+# 仪表板组件查询结果契约
+
 ## 1. 适用范围
 
 `result` 是插件根据本次 Provider 的预览结果及返回的组件配置生成的独立契约，`schemaVersion` 为 `"1"`。现有顶层字段保持原语义，`dashboard preview` 不使用此契约。未增加过滤生效回显。值表示组件查询结果（可能经过聚合、计算、分组、权限和脱敏处理），不承诺是数据库原始值。
+
+响应中的 `fields/rows` 是兼容投影：交叉表仅左侧分区、复杂图表仅首个模型，不能代替标准化结果。类型专属结构保留在原生 `previewResult` 中，由 `resultType=DETAIL/BIGROUP/BICROSS/CHART` 区分；不要与本契约的 resultType 枚举混用，也不能用旧 rows 猜测填补不可用值。
 
-响应中的 `fields/rows` 是兼容投影：交叉表仅左侧分区、复杂图表仅首个模型，不能代替标准化结果。类型专属结构保留在原生 `previewResult` 中，由 `resultType=DETAIL/BIGROUP/BICROSS/CHART` 区分；不要与本契约的 resultType 枚举混用，也不能用旧 rows 猜测填补不可用值。
-
-## 2. 返回结构与完整性
-
+## 2. 返回结构与完整性
+
 | 字段 | 语义 |
 | --- | --- |
 | `resultType` | `DETAIL_TABLE / GROUP_TABLE / CROSS_TABLE / CHART / UNKNOWN` |
@@ -16,17 +16,17 @@
 | `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、聚合等限制。
+## 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。不根据样例猜类型。数值字符串保留上游已有精度，不能恢复上游浮点误差。
+## 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。
 
@@ -39,181 +39,181 @@
 | 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，不能声称它一定截断。类型缺失、展示专用值、缺少单元格分别标记不可用，不填造业务空值；日期也遵循这些规则及权限、空值规则。
+## 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": []
-}
-```
+## 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

@@ -1,44 +1,44 @@
-# Dashboard DSL API
-
-这份文档只列当前文本 DSL 可以直接使用的 Dashboard API，以及各 API 的业务含义。本语句面同时是
-`dashboard dsl --id <dashboardId>` 回读命令的输出面（响应内嵌数据组件 DSL 回显，见 docs/commands/）。
-
-**回读 warnings 里出现条目级 `*_DROPPED` 留痕（`UNSUPPORTED_WIDGET_DROPPED` /
-`UNREACHABLE_WIDGET_DROPPED` / 整条目跳过的 `UNREACHABLE_IMAGE` / `UNREACHABLE_WEB` /
-`AI_SUBJECT_DROPPED` / `COMBINE_DISSOLVED` 等）时不要整板 `dashboard update`**：这些条目
-不在回读 DSL 里，整板重写会使其从板上消失，写侧防丢守卫会以 `ENTRY_LOSS_BLOCKED`
-拒绝保存。先完成与该条目无关的操作；需要处理时询问用户在 FineBI 设计器中处置
-（删除或修复该条目），不要试图绕过。
-
-**改板前先 `dashboard info --id <dashboardId>`**：板级构成摘要（条目清单 + 悬浮层 +
-板级留痕）与本文语句面的条目一一对应，先清点再按需 `dashboard dsl` 取局部 DSL，
-不必为定位条目拉全量回读；`warnings` 出现条目级 `*_DROPPED` 留痕时按上一段处置。
-只看一个条目时用单条目切片 `dashboard dsl --id <dashboardId> --entry <名>`（重名板
-改用 `--entry-id <entries[].entryId>` 消歧）：`dsl` 只含该条目语句 + 可选 `position`
-（容器成员 position 是容器局部格位），`warnings`/`widgets` 同步过滤到目标条目。
-**只改一个条目时用单条目写**：`dashboard update-entry --id <dashboardId> --file
-<fragment.js>`（fragment 与切片同文法，是条目的完整新定义——读全条 → 改 → 写回；
-重名板带 `--entry-id` 消歧）。未点名条目原样保留，不会丢；widget 引用条目只改板侧面
-（position/title），组件本体走 `widget update`。新增 / 删除条目用 `add-entry` /
-`remove-entry`（被控件圈定或联动的条目删除会被拒，按错误信息先改引用）。`add-entry`
-的 fragment 无切片可抄、需手写：单条目语句（上文各条目语句形态之一）+ 可选
-`position` 行，不包 `DashboardDsl.create` 整板脚本；缺省 position 落首个空位。
-并发编辑（含用户在设计器手改后再让 Agent 续改）带 `--expected-update-time`——基准取
-读板响应（`info` / `dsl` 的 `lastUpdateTime`）或上次写响应的新值，不匹配会报
-`VERSION_CONFLICT`（附当前值），重读后重试。entryId 按条目名稳定：设计器保存与整板
-`update` 下同名条目沿用原值，新增条目的新值从 update 响应 `entries[]` 直接可得。
-
-**写新看板前先取场景样例**：`dashboard template`（默认场景）返回场景目录与通用设计要点，
-`dashboard template --scenario <id>` 取某一个场景的完整可抄脚本 + `guidance` 设计要点
-（场景：`basic` 经营看板 / `kpi` KPI 概览 / `filter` 筛选控件 / `style` 样式面 /
-`screen` 大屏驾驶舱 / `rich-text` 富文本与动态字段 / `linkage-jump` 联动与跳转 /
-`tree-time` 层级与时间筛选 / `blocks` 容器区块）。
-动态合法值（样式预设 id 与全局样式名）
-用 `dashboard style-presets` 查，语句面速查用 `dashboard schema`。API 面拆分为下表文件，
-按需读取当前操作涉及的文件，不一次加载全部；章节编号沿用拆分前原编号。
-
-| 文件 | 章节 | 何时读取 |
-| --- | --- | --- |
-| [dashboard-dsl-core.md](dashboard-dsl-core.md) | §1-§5 根入口、顶层 Builder、内容域（条目挂载、联动与跳转）、布局与样式域、移动端域；§7 字段写法 | 写任何仪表板前必读 |
-| [dashboard-dsl-items.md](dashboard-dsl-items.md) | §6 可构造值对象（6.1-6.14：控件、文本、图片、联动/跳转模型、自适应、移动端配置、富文本、Web、组合、Tab、冻结栏、复合过滤、AI 诊断） | 挂载或配置具体条目类型时 |
-| [dashboard-dsl-examples.md](dashboard-dsl-examples.md) | §8 推荐写法示例、§9 场景模板与设计要点 | 需要可抄写法或场景模板时 |
+# Dashboard DSL API
+
+这份文档只列当前文本 DSL 可以直接使用的 Dashboard API，以及各 API 的业务含义。本语句面同时是
+`dashboard dsl --id <dashboardId>` 回读命令的输出面（响应内嵌数据组件 DSL 回显，见 docs/commands/）。
+
+**回读 warnings 里出现条目级 `*_DROPPED` 留痕（`UNSUPPORTED_WIDGET_DROPPED` /
+`UNREACHABLE_WIDGET_DROPPED` / 整条目跳过的 `UNREACHABLE_IMAGE` / `UNREACHABLE_WEB` /
+`AI_SUBJECT_DROPPED` / `COMBINE_DISSOLVED` 等）时不要整板 `dashboard update`**：这些条目
+不在回读 DSL 里，整板重写会使其从板上消失，写侧防丢守卫会以 `ENTRY_LOSS_BLOCKED`
+拒绝保存。先完成与该条目无关的操作；需要处理时询问用户在 FineBI 设计器中处置
+（删除或修复该条目），不要试图绕过。
+
+**改板前先 `dashboard info --id <dashboardId>`**：板级构成摘要（条目清单 + 悬浮层 +
+板级留痕）与本文语句面的条目一一对应，先清点再按需 `dashboard dsl` 取局部 DSL，
+不必为定位条目拉全量回读；`warnings` 出现条目级 `*_DROPPED` 留痕时按上一段处置。
+只看一个条目时用单条目切片 `dashboard dsl --id <dashboardId> --entry <名>`（重名板
+改用 `--entry-id <entries[].entryId>` 消歧）：`dsl` 只含该条目语句 + 可选 `position`
+（容器成员 position 是容器局部格位），`warnings`/`widgets` 同步过滤到目标条目。
+**只改一个条目时用单条目写**：`dashboard update-entry --id <dashboardId> --file
+<fragment.js>`（fragment 与切片同文法，是条目的完整新定义——读全条 → 改 → 写回；
+重名板带 `--entry-id` 消歧）。未点名条目原样保留，不会丢；widget 引用条目只改板侧面
+（position/title），组件本体走 `widget update`。新增 / 删除条目用 `add-entry` /
+`remove-entry`（被控件圈定或联动的条目删除会被拒，按错误信息先改引用）。`add-entry`
+的 fragment 无切片可抄、需手写：单条目语句（上文各条目语句形态之一）+ 可选
+`position` 行，不包 `DashboardDsl.create` 整板脚本；缺省 position 落首个空位。
+并发编辑（含用户在设计器手改后再让 Agent 续改）带 `--expected-update-time`——基准取
+读板响应（`info` / `dsl` 的 `lastUpdateTime`）或上次写响应的新值，不匹配会报
+`VERSION_CONFLICT`（附当前值），重读后重试。entryId 按条目名稳定：设计器保存与整板
+`update` 下同名条目沿用原值，新增条目的新值从 update 响应 `entries[]` 直接可得。
+
+**写新看板前先取场景样例**：`dashboard template`（默认场景）返回场景目录与通用设计要点，
+`dashboard template --scenario <id>` 取某一个场景的完整可抄脚本 + `guidance` 设计要点
+（场景：`basic` 经营看板 / `kpi` KPI 概览 / `filter` 筛选控件 / `style` 样式面 /
+`screen` 大屏驾驶舱 / `rich-text` 富文本与动态字段 / `linkage-jump` 联动与跳转 /
+`tree-time` 层级与时间筛选 / `blocks` 容器区块）。
+动态合法值（样式预设 id 与全局样式名）
+用 `dashboard style-presets` 查，语句面速查用 `dashboard schema`。API 面拆分为下表文件，
+按需读取当前操作涉及的文件，不一次加载全部；章节编号沿用拆分前原编号。
+
+| 文件 | 章节 | 何时读取 |
+| --- | --- | --- |
+| [dashboard-dsl-core.md](dashboard-dsl-core.md) | §1-§5 根入口、顶层 Builder、内容域（条目挂载、联动与跳转）、布局与样式域、移动端域；§7 字段写法 | 写任何仪表板前必读 |
+| [dashboard-dsl-items.md](dashboard-dsl-items.md) | §6 可构造值对象（6.1-6.14：控件、文本、图片、联动/跳转模型、自适应、移动端配置、富文本、Web、组合、Tab、冻结栏、复合过滤、AI 诊断） | 挂载或配置具体条目类型时 |
+| [dashboard-dsl-examples.md](dashboard-dsl-examples.md) | §8 推荐写法示例、§9 场景模板与设计要点 | 需要可抄写法或场景模板时 |

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

@@ -2,7 +2,7 @@
 
 ## 1. 输入边界
 
-只消费 `finebi-cli-agent` 已校验的 JSON 对象。该对象记录 Widget/Dashboard 的业务语义和资源证据，不包含 JS 源码，也不授权执行任何 FineBI 写命令。
+独立 DSL 编写器只消费规划器已校验的 JSON 对象；完整 Agent 在同一任务内生成 DSL 时，可使用覆盖必要信息的内部记录，并按本契约核验字段来源、关系和引用。跨执行体仍必须传递完整 `contractVersion: "1.0"` JSON。语义输入不包含 JS 源码，也不授权执行任何 FineBI 写命令。
 
 顶层结构：
 

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

@@ -4,6 +4,8 @@
 
 本契约仅记录 `$finebi-cli-agent` 为 Widget/Dashboard JS 制品解析的业务语义。契约不包含 JS 源码；CLI 命令必须另行遵循通用执行流程，其中仅 `delete` 命令需要人工确认。
 
+完整 JSON 用于跨执行体交接。同一 Agent 在一个连续任务内发现资源并生成 DSL 时，可以使用覆盖本次必要信息的结构化记录；下文的字段来源、归属、关系、命名空间和引用校验同样适用。不为内部记录或文件路径增加用户审批。
+
 ## 规划器请求
 
 使用以下 JSON 结构。省略没有实际含义的可选属性；不得臆造占位 ID。
@@ -154,7 +156,7 @@
 1. 对每一对被跨数据集字段引用实际关联的分析表，调用 `relationship info --subject-id <subjectId>` 确认现有关系。
 2. 关系已存在且 `status` 为 `DEFAULT` 时，把该关系写入 `relationships` 数组。
 3. 关系不存在，或存在但 `status` 非 `DEFAULT`（例如 `MISS_FIELD`、`TYPE_NOT_MATCH`）时，不得静默继续；应向用户说明现状。需要新增或替换关系时，按
-   `command-workflows.md` §5.6 走独立的 `relationship add` 计划、复检和执行流程，无需人工确认；写入成功且只读回查通过后，才把该关系补充进
+   [Relationship 工作流](command-workflows.md#77-relationship)走独立的 `relationship add` 计划、复检和执行流程，无需人工确认；写入成功且只读回查通过后，才把该关系补充进
    `relationships` 数组。
 
 `relationships[]` 单条结构：
@@ -184,7 +186,7 @@
 
 ## JS 制品映射
 
-确认交接对象后，调用方、用户或可用的外部生成工作流必须提供一个 JSON 对象：
+跨执行体消费制品时，调用方、用户或可用生成工作流提供以下 JSON。具有 DSL 生成职责的 Agent 在同一任务内自行记录路径并生成文件，文件回读自检后再消费映射；不要求额外的外部生成器或路径确认。
 
 ```json
 {
@@ -201,7 +203,7 @@
 - `files` 必须包含每个 `requestedWidgets[].key`，以及存在时的 `requestedDashboard.key`。
 - 每个值都必须是指向现有 `.js` 文件的绝对路径。
 - 将每个值解析为文件系统的 canonical/real path。所得规范路径必须两两不同，因此两个 artifact key 不得通过不同拼写、相对路径片段或符号链接别名指向同一文件。
-- 规划器仅消费路径。不得消费内联 DSL、从说明性文本推断文件，或改写已生成文件。本契约不要求或指定特定的生成器 Skill。
+- 独立规划器仅消费路径，不从说明性文本推断文件或改写已生成文件；完整 Agent 的生成阶段可按入口职责生成和修复本任务文件，写入计划只消费已校验文件路径，不消费内联 DSL。本契约不要求或指定特定生成器 Skill。
 - 额外且未映射的文件不会生成命令。
 
 ## 前置资源边界
@@ -209,4 +211,4 @@
 主题、自助数据集、字段或跨数据集关系缺失时，可以先通过通用命令流程创建所需前置资源，但不得把尚未创建的资源或占位 ID
 写入本交接对象。搜索命中 `public-ds` 时，必须先以该公共数据集为来源在目标主题内创建 `analysis-ds`，并使用写响应中的实际 ID 完成 `analysis-ds.info` 和必要的 `preview` 回查；不得把公共数据集 ID 写入 `datasets`，也不得因已经命中公共数据集而继续查询数据连接。前置写操作必须单独规划并复检，创建成功且只读回查后，再生成本契约；仅当前置操作为 `delete` 时等待人工确认。
 
-版本 1.0 的制品输入始终是上述 JSON 对象。不得隐式改成自然语言交接，也不得混用两种格式。
+跨执行体的版本 1.0 制品输入始终是上述 JSON 对象，不以自然语言替代。单 Agent 内部记录不改变该外部交接格式。

package/skills/finebi-cli-agent/references/mutation-confirmation-contract.md

@@ -4,6 +4,8 @@
 
 本契约约束所有非只读命令的计划、复检、执行、验证和失败清理。`add`、`update`、`data-update` 及其他非删除命令不需要人工确认；命令名为 `delete` 的计划必须等待人工确认。人工确认只授权一个内容冻结的删除计划，不授权后续变化或自动清理。
 
+用户已明确要求的非删除任务在完成校验后连续执行，不为内部语义对象、临时产物路径或计划生成增加审批。用户要求先审阅时遵循该范围；业务歧义需要澄清；仅生成本地文件的请求不授权远端写入。计划中的 `state` 用于记录执行进度，无需逐步向用户播报状态名。
+
 ## 2. 冻结计划
 
 计划必须使用可见且唯一的 `planId`。非删除计划生成后可以直接复检执行；删除计划必须在一个完整 JSON 代码块中展示并等待确认：