@finebi/finebi-cli 1.6.3 → 2.0.1

package/README.md

@@ -12,6 +12,8 @@ npm install -g @finebi/finebi-cli --registry=https://registry.npmjs.org/
 
 This package includes the CLI and the complete `finebi-cli-agent` Skill. Contact service personnel to obtain the FineBI server plugin and have an administrator install or enable it before connecting to FineBI.
 
+For the five-step installation, authentication and verification flow, see the bundled [Agent installation guide](agent-installation-guide.md).
+
 ## Usage
 
 Built-in help is always available and does not require server config, login, or a capability refresh:
@@ -145,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`, `cursor`, `gemini-cli`, `github-copilot`, `opencode`, `cline`, `windsurf`, `trae`, `trae-cn`, `openclaw`, `roo`, and `qwen-code`. Custom `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, and `XDG_CONFIG_HOME` directories are respected.
+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/agent-installation-guide.md

@@ -0,0 +1,70 @@
+# FineBI CLI 安装指南
+
+以下步骤面向 AI Agent，登录授权需要用户配合完成。执行前确认已安装 Node.js 18.17 或更高版本（含 npm）。
+
+## 第 1 步 安装 CLI
+
+```shell
+npm install -g @finebi/finebi-cli@latest --registry=https://registry.npmjs.org/
+finebi-cli version
+```
+
+## 第 2 步 安装 Skill
+
+查询当前版本支持的 Agent，将示例中的 `codex` 替换为实际目标，如 `claude-code`、`cursor`、`dsh`（DeepSeek Harness）；多个目标用逗号分隔。WorkBuddy 仅在列表中出现 `workbuddy` 时选用。目录及环境变量约定见 [CLI 使用说明](README.md#agent-skills)。
+
+```shell
+finebi-cli install-skill --list
+finebi-cli install-skill --agents codex
+```
+
+安装后刷新技能或重启 Agent，确认已加载 `finebi-cli-agent`。若提示本地 Skill 有修改，保留并告知用户，不自动覆盖。
+
+升级时重复第 1、2 步：更新 npm 包不会自动更新已安装到 Agent 目录的 Skill；重新安装 Skill 后再次刷新技能或重启 Agent。
+
+## 第 3 步 确认插件依赖
+
+请用户联系服务人员获取与 FineBI 环境匹配的 **FineBI CLI Agent Interface** 插件（`com.finebi.plugin.finebi.cli`），由管理员在 FineBI 插件管理中安装并启用。本机 npm 和 Skill 安装不包含服务端插件部署。
+
+## 第 4 步 登录认证
+
+向用户获取 FineBI 决策平台根地址，先查看已有环境：
+
+```shell
+finebi-cli auth list --json
+```
+
+已有目标环境时，使用 `finebi-cli config get --profile <名称>` 核对地址，再复用该名称；新服务器使用新的环境名。不要直接改写现有环境的 `base-url`，它会清除该环境的凭据和能力缓存。以下以 `bi` 为示例，将名称和地址替换为已确认的目标；`--no-use` 保留原默认环境，后续命令显式指定同一 profile。
+
+```shell
+finebi-cli auth login --profile bi --base-url https://bi.example.com/webroot/decision --browser --no-use
+```
+
+将命令返回的授权链接和确认码展示给用户，请用户在同一 FineBI 服务的网页中登录并确认授权。保持命令运行，等待授权结果。
+
+若无法使用浏览器授权，让用户在自己的交互终端执行以下命令，并按提示输入密码；不要让用户把密码发到聊天中。
+
+```shell
+finebi-cli auth login --profile bi --base-url https://bi.example.com/webroot/decision --username your-user --no-use
+```
+
+浏览器授权成功后保存 CLI Access Key；账号密码登录默认也尝试签发 Key，签发失败会警告并降级为会话 Token。登录成功后会自动尝试刷新能力；应逐项检查 warning，不能把登录成功等同于业务命令已可用。认证与凭据安全说明见 [CLI 使用说明](README.md#access-key)。
+
+## 第 5 步 验证
+
+```shell
+finebi-cli auth info --profile bi --json
+finebi-cli capability refresh --profile bi --json
+finebi-cli system command-index --profile bi --json
+finebi-cli subject search --help --profile bi --json
+```
+
+`auth info` 仅展示本地凭据状态，不验证服务端有效性；在线 `capability refresh` 成功才说明当前连接能取得服务端能力。命令帮助来自能力缓存，也不证明业务资源可访问。
+
+需要确认业务访问时，在用户授权范围内执行一条实际只读查询，例如：
+
+```shell
+finebi-cli subject search --profile bi --limit 1 --json
+```
+
+分别报告 CLI 版本、Skill 加载状态、在线能力发现和实际业务查询结果；未执行业务查询时明确注明。查询零命中只能说明本次没有找到可见主题，不能推断其他业务权限。失败时说明未完成项，不将本地缓存视为在线连接成功。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finebi/finebi-cli",
-  "version": "1.6.3",
+  "version": "2.0.1",
   "description": "FineBI dynamic capability command line client.",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -15,6 +15,7 @@
     "src",
     "skills",
     "README.md",
+    "agent-installation-guide.md",
     "templates"
   ],
   "engines": {

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": []
+}
+```