@finebi/finebi-cli 1.5.0 → 1.6.1

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,6 +41,19 @@ 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 --layout cockpit
+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.
+
+`--layout` accepts `overview` (default), `workbench`, or the green `cockpit` layout. Cockpit shares the existing Cookie query and authentication flow, with configurable KPI/chart/table bindings, independent retries, and a custom month picker. The generated README and `examples/cockpit.config.json` describe the placeholder bindings; no business data or credentials are bundled. Published sources require `directoryEntryId` and a platform HTTP endpoint that supports directory permissions; failed queries never switch sources.
+
+Use `--layout retail` for a warm paper-style retail brief with horizontal navigation, a KPI strip, and blue/orange charts. `examples/retail.config.json` contains placeholder retail bindings; see the generated design guide for explicit KPI and month-label formats. Creation leaves the project unbound and does not query a server.
+
 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):
@@ -55,13 +69,13 @@ 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 '["<dimensionDId>","<measureDId>"]' --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.
+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. The list is a complete whitelist of dimensions and measures: unlisted selectable fields are disabled. Include measure dIds explicitly to keep their output; selecting only measures disables selectable dimensions. An explicit `[]` disables all selectable dimensions and measures; 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.
+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 server plugin and platform Provider supporting the complete dimension-and-measure whitelist; the plugin directly depends on the dimension-selection and published-source APIs. Refresh capabilities after the server update.
 
 ### Multiple environments
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finebi/finebi-cli",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "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,7 +24,7 @@
     "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 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",

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,6 +16,8 @@
 
 ## 2. 当前命令矩阵
 
+动态 HTML 看板与数据 Web 应用使用本地 `app create/inspect`，不属于远端 capability；具体开发流程见[应用模板工作流](web-app.md)。
+
 以下矩阵仅列出常见资源命令示例；实际可执行范围以实时 capability 为准。
 
 | 资源 | 只读（`mutation:false`） | 非只读（`mutation:true`） |
@@ -24,7 +26,7 @@
 | `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` |
@@ -77,7 +79,7 @@
 - `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 前必须调用。
@@ -116,7 +118,7 @@
 
 ### 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 info` 读取目标条目的 `queryFields`，用 `selectable=true` 的 `dId` 构造 `dashboard data --dimension-ids '["<dimensionDId>","<measureDId>"]'`。这些 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，平台不支持或目录授权失败时不得丢弃入口参数后重试普通看板。
 
@@ -150,7 +152,9 @@ 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()`；模型根级维度和记录数不支持。
 

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 猜测填补不可用值。
 
-## 2. 返回结构与完整性
-
+响应中的 `fields/rows` 是兼容投影：交叉表仅左侧分区、复杂图表仅首个模型，不能代替标准化结果。类型专属结构保留在原生 `previewResult` 中，由 `resultType=DETAIL/BIGROUP/BICROSS/CHART` 区分；不要与本契约的 resultType 枚举混用，也不能用旧 rows 猜测填补不可用值。
+
+## 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": []
+}
+```