@finebi/finebi-cli 2.0.0 → 2.0.1

package/README.md

@@ -147,7 +147,9 @@ finebi-cli install-skill --list
 finebi-cli install-skill --agents codex,cursor
 ```
 
-Run `finebi-cli install-skill` in an interactive terminal to choose Agents. Non-interactive use requires `--agents`. Supported IDs are `claude-code`, `codex`, `dsh`, `cursor`, `gemini-cli`, `github-copilot`, `opencode`, `cline`, `windsurf`, `trae`, `trae-cn`, `openclaw`, `roo`, and `qwen-code`. Custom `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, `DSH_HOME`, and `XDG_CONFIG_HOME` directories are respected. For DeepSeek Harness, use `finebi-cli install-skill --agents dsh`; Skills are installed to `~/.dsh/skills` by default, or `<DSH_HOME>/skills` when `DSH_HOME` is set.
+Run `finebi-cli install-skill` in an interactive terminal to choose Agents. Non-interactive use requires `--agents`. Supported IDs are `claude-code`, `codex`, `dsh`, `cursor`, `gemini-cli`, `github-copilot`, `opencode`, `cline`, `windsurf`, `workbuddy`, `trae`, `trae-cn`, `openclaw`, `roo`, and `qwen-code`. Custom `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, `DSH_HOME`, `WORKBUDDY_HOME`, and `XDG_CONFIG_HOME` directories are respected. For DeepSeek Harness, use `finebi-cli install-skill --agents dsh`; Skills are installed to `~/.dsh/skills` by default, or `<DSH_HOME>/skills` when `DSH_HOME` is set.
+
+For WorkBuddy, use `finebi-cli install-skill --agents workbuddy`; Skills are installed to `~/.workbuddy/skills` by default, or `<WORKBUDDY_HOME>/skills` when `WORKBUDDY_HOME` is set. Set `WORKBUDDY_HOME` to match the configuration root used by your WorkBuddy installation.
 
 Skill installation is local and does not require a server connection or credentials. It copies the Skill included in this installed npm version, including its own CLI runtime. Restart your Agent or refresh its Skills after installation. npm installation alone does not install Skills into Agent directories.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finebi/finebi-cli",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "FineBI dynamic capability command line client.",
   "license": "UNLICENSED",
   "publishConfig": {

package/skills/finebi-cli-agent/SKILL.md

@@ -36,7 +36,7 @@ node "<skill-dir>/scripts/finebi-cli-runner.mjs" run <resource> <command> ... --
 | 新建或修改 Widget | [场景工作流](references/scenario-workflows.md)＋[Widget API 导航](references/widget-dsl-api.md) | [映射规则](references/mapping-rules.md)仅查本次图表、字段与通道；需要推荐写法时读[示例](references/widget-dsl-api-examples.md) |
 | 新建或修改 Dashboard | [场景工作流](references/scenario-workflows.md)＋[Dashboard API 导航](references/dashboard-dsl-api.md) | 仅引用已有组件时无需读 Widget API；来源与顺序见[产物顺序](references/artifact-ordering.md) |
 | 解释、生成或排查公式 | [公式入口](references/formula.md) | 教学/离线模板声明假设；实际主题落地前查询目标主题面板，再以同一份 JS 做 `calculated-field validate` |
-| 动态 HTML 看板、数据 Web 应用 | [应用模板工作流](references/web-app.md) | 本地 `app create` 不需要登录；绑定真实数据时再检查连接与业务能力，开发遵循生成项目 AGENTS.md |
+| 动态 HTML 看板、数据 Web 应用 | [应用模板工作流](references/web-app.md) | 本地 `app create` 不需要登录；缺开发身份及时请求补充，一个组件真实查询通过后再扩展整页，不自行降级为回放；开发遵循生成项目 AGENTS.md |
 | FineBI 非只读命令或失败清理 | [变更计划与删除确认](references/mutation-confirmation-contract.md) | 读取本次计划、复检、验证及适用的清理章节 |
 | 跨执行体交接 DSL 任务 | [语义交接](references/handoff-contract.md)＋[DSL 输入契约](references/dsl-handoff-contract.md) | 完整 JSON 与文件映射用于外部交接；同一 Agent 连续执行按场景流程记录必要语义即可 |
 

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/web-app.md

@@ -4,10 +4,13 @@
 
 1. `finebi-cli app create --name <name> --path <parent> [--layout retail]` 创建工程，不安装/运行/发布。米白横向经营简报可选 retail，绿色驾驶舱可选 cockpit；默认 overview，另有 workbench。
 2. 用dashboard search/info/data确认唯一来源、板内entryId、结果字段dId、真实控件filterName；按生成项目 docs/acceptance.md 记录指标口径、单位/时区、筛选范围和数据完整性。样本仅用于理解和测试。
-3. 按生成项目 AGENTS.md 的“阅读路径”分阶段读取文档，不要求开场通读全部说明。先按 docs/acceptance.md 的“最小真实查询”只配置一个真实组件，按 README 安装依赖、配置开发身份并启动实际页面，验证开发代理查询与页面值。CLI 成功不能替代这一步；优先复用已有会话，不重复索要可用身份的密码。
+3. 按生成项目 AGENTS.md 的“阅读路径”分阶段读取文档，不要求开场通读全部说明。先检查开发身份：优先复用目标环境的有效会话或已有登录配置；只有 CLI Access Key 不算开发身份。缺少可用身份且需要用户补充凭据或完成授权时，立即说明阻断点并请求最小补充，按项目 docs/auth-and-deploy.md 配置；不要等整页做完才询问，也不重复索要可用身份的密码。
+   身份具备后，按 docs/acceptance.md 的“最小真实查询”只配置一个真实组件，按 README 安装依赖并启动实际页面。留下目标环境、组件请求参数、真实业务响应和页面值的脱敏证据，核对一致后才进入下一阶段；CLI 成功、HTTP 200 或合成测试通过均不能替代这一步。
 4. 最小真实查询及适用的代表性图表、筛选链路通过后，再扩展整页绑定。按 docs/design.md 对应章节确定首屏、导航、图表分组和风格差异；请求、认证、解析复用模板src/finebi，图表库和UI组件库按页面需求选择。需要查看绑定摘要时可运行 `finebi-cli app inspect --path <project>`，默认不校验模板字段或展示格式，也不证明应用可用。只有需要检查与 CLI 内置模板的兼容性时才显式使用 `--strict`；定制应用无需通过该检查，不要为消除 strict 报错而删除自定义能力或反复修改应用。验收以项目自身测试、构建和真实浏览器验证为准。
 5. 按生成项目 docs/acceptance.md 分别完成自动测试、构建、test:browser 合成数据验收和真实页面验收，检查整页及窄屏，记录 CLI、开发身份、生产 Cookie 各自的已验证与未验证项。生产部署必须用访问者Cookie，不携带开发身份。
 
+阶段阻断时只继续不依赖真实数据的设计或测试，暂停扩展整页绑定。不得自行将开发代理切到 mock、历史响应回放或静态数据来交付或启动预览；注明“回放”或“真实查询未验证”也不等于完成动态应用。用户明确要求离线演示时才单独提供，并说明其不通过真实查询阶段；恢复动态应用开发仍须先完成上述验证。
+
 内置CLI同样通过 `node "<skill-dir>/scripts/finebi-cli/src/index.js" app ...` 调用，不走动态业务runner。生产页面不调用CLI。禁止将开发时查到的业务数据或token写入HTML/JS/config；无筛选控件不能伪造服务端过滤。pageLimit不是分页，hasNext和warnings必须呈现。不提供发布上传或服务端续页。目录来源显式配置 directoryEntryId，由原生 reportEntryId 透传；目标平台需支持 HTTP 目录权限预检与 MOUNT 查询，不能失败后回退“我的分析”。
 
 cockpit 的 examples/cockpit.config.json 仅包含占位绑定，必须替换成真实资源和结果 fieldId；多模型显式 datasetId。布局含可配置 KPI、多系列趋势、分类对比、通栏表格及可选观察/口径。年月为自定义十二月/年份网格面板，选中只改 YYYY-MM 草稿。表格搜索、精确排序、筛选、分页、CSV 只处理已加载结果；观察不内置销售公式。widgets[].filterNames 来自真实映射，[] 表示不传覆盖，省略由源看板决定，不宣称未知映射为全局联动。请求/认证仍复用 src/finebi，不能复制个人 CLI 子进程后端。

package/skills/finebi-cli-agent/scripts/finebi-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finebi/finebi-cli",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "private": true,
   "description": "FineBI dynamic capability command line client.",
   "license": "UNLICENSED",