@xpert-ai/plugin-live-dashboard 0.3.0 → 0.4.0

package/skills/live-dashboard/examples/superstore/README.md

@@ -0,0 +1,64 @@
+# Superstore 企业 BI — v1
+
+一个 ChatKit 项目，三个看板：`overview.html`（零售经营总览）、`profitability.html`（商品盈利）、`customers.html`（客户与退货）。这是 Tableau 的虚构教学数据，必须保留页面演示标识。页面参考经典企业经营分析的信息组织，自行实现；不是第三方产品截图。
+
+## 数据准备（管理员一次完成）
+
+1. 阅读 `provenance.json` 和 `THIRD_PARTY_LICENSE.txt`。`orders.csv` 是固定官方工作簿的确定性转换结果，10,194 行；不要把整个文件送入模型上下文。
+2. 在 Data Xpert 中为有权限的工作空间绑定一个 PostgreSQL 演示数据源，通过“导入”上传 `orders.csv`。`import.json` 是字段定义：金额为 NUMERIC(20,6)，邮编为文本，`returned_order_id` 允许 NULL。使用一个尚不存在的表名；不要选择删除/覆盖已有表。API 自动化也必须先检查表是否存在，不能重复追加。
+3. 创建新的 SQL 语义模型，以 `semantic-model.json` 为结构模板，按实际元数据调整数据库/schema/表名；保留技术 Cube 名 `SuperstoreOrders` 和字段名。核对所有度量与维度后执行草稿验证，发布到有权限的业务域。
+4. 将发布后的本体资源授权给当前 Live Dashboard Assistant，配置 Data Xpert integration 和当前查看者的只读查询权限。数据权限不会由安装本样例自动授予。
+5. 通过 Data Xpert 真实查询核对 `expected.json`。全量订单 5,111、客户 804、退货订单 296；金额核对到 6 位小数。未经验证不能宣布“数据准备完成”。
+
+此配方使用 `data-xpert.ontology`，不是 `file.table`。缺少已发布模型时报告这一前置步骤；不得用三个入门配方、小量自造数据或浏览器内嵌数据替代。数据准备不需要增加新的 Project View 或后台定时任务。
+
+## 助理制作步骤
+
+先读 [主题选择说明](../../themes/README.md)，再读目标页的独立主题指南。三个可选风格都使用键盘可用的双层标签选择器；CSS、选择器和图表组件随技能安装，通过版本和内容哈希固定的文档库加载。
+
+| 页面 | 风格及指南 | libraries |
+| --- | --- | --- |
+| `overview.html` | [Trend Workspace](../../themes/trend-workspace/README.md)：浅蓝 KPI 侧栏、上下趋势 | `["echarts","trend-workspace"]` |
+| `profitability.html` | [Profit Atlas](../../themes/profit-atlas/README.md)：深色横向指标、大散点图、带正负号的利润排名 | `["echarts","profit-atlas"]` |
+| `customers.html` | [Customer Brief](../../themes/customer-brief/README.md)：暖纸色、衬线标题、分组退货指标 | `["echarts","customer-brief"]` |
+
+用户要求美化已有看板时，逐个 `dashboard_open` / `dashboard_update`，保留 Artifact、Binding、控件和已有 HTML ID，显式传入目标页对应的 libraries。先读当前编辑副本，用有界精确编辑替换业务布局，不能新建副本。没有要求重设计时保留已有风格。用于其他数据时须重新匹配字段和口径，不能只替换标题而保留 Superstore 字段。
+
+1. 先阅读主技能和 HTML runtime/lifecycle。确认当前 ChatKit Project。用户请求整个案例时制作三个草稿；只请求其中一个时仅制作该页。
+2. 使用 `dashboard_list_sources` 和 Data Xpert analytics definition 的 connections/inspect/register/discover 流程，找到当前 Assistant 已授权的 **SuperstoreOrders**。记录实际 definitionId/versionId、resourceId、entityRef；不能沿用别的 Assistant/项目的 ID。
+3. 用 `read_skill_file` 阅读目标页的 `*.queries.json`（相对技能目录定位）。每个 binding 是查询计划，尚未包含 source；替换 payload 中发现得到的 resourceId/entityRef，并添加本次 source。字段类型、可空性、action schema 以实际发现结果为准；稳定保留 binding.id、output.datasetId、output.fields[].id 和控件 ID，HTML 使用这些名字。
+4. 每个查询包含同样的 year/region/category 参数。空字符串表示全部，通过 contains 匹配；allowedValues 严格限定工作簿中真实存在的枚举。总计 Binding 的 dimensions 必须为空，让后端执行 COUNT DISTINCT；不能把月度、子品类或分群的订单/客户数相加冒充全量。
+5. 使用 `dashboard_preview_binding` 预览每个完整 Binding。先读小文件 `checks.json`，对总计 Binding 用 `dashboard_test_filter` 验证全量、West、East、2024、Furniture 和组合筛选；`controls` 原样传全部三个值，`expectations` 选择实际存在的字段，`fieldId` 设为该字段名，`oneOf` 使用对应 case 的 summary 中原样字符串值。Data Xpert 的 int64/decimal 查询结果是字符串，oneOf 必须同类型。不要把全量计数当成区域计数；不要为验证筛选反复修改 Binding 默认值。分组查询与 `expected.json` 对照，并完成 preview 返回的 validation.suggestedCall。
+6. 调用 `dashboard_libraries`，按上表只选择 ECharts 和该页一个主题。使用 `read_skill_file` 读取目标 HTML **完整内容**（不是只读前一段）；若改用 sandbox_read_file 必须读取全部行。逐页读取、写入并保存，完成一页后再处理下一页，不在一次模型输出中重写三页。原样保留 HTML/CSS/JS，不压缩或简化。写入当前项目的新相对路径，例如 `superstore-v1/overview.html`。若路径已有不同内容，改用新的文件名，不覆盖别的 Artifact。使用 SandboxFile 工具；不需要重写模板代码或复制 10,194 行数据到 Sandbox。
+7. 对三个页面分别调用 `dashboard_create_html`：标题为 `Superstore · 零售经营总览`、`Superstore · 商品盈利分析`、`Superstore · 客户与退货分析`，传入各自全部 previewIds、原样 controls 和 libraries。预检失败则按具体错误修复后重试，不省略 Binding 或控件。**三个页面的 Binding 集合不同，不能只把标题换掉。**
+8. 收到成功的草稿回执后报告三个 Artifact 和修订，用户通过回执卡片/级联选择器打开。不要重新打开未改变的看板来确认保存；不要自动发布。
+
+## 总计筛选基准（当前固定数据版本）
+
+执行 `dashboard_test_filter` 时用下表当前筛选对应的值，不猜测常见 Superstore 版本的计数。int64 和 decimal 都使用字符串。全量参数都是空字符串。先验证 Orders 与 Customers；金额同时与真实返回值核对。
+
+| year | region | category | Orders | Customers | Sales | Profit |
+| --- | --- | --- | --- | --- | --- | --- |
+| `""` | `""` | `""` | `"5111"` | `"804"` | `"2326534.354300"` | `"292296.814600"` |
+| `""` | `"West"` | `""` | `"1635"` | `"686"` | `"739813.608500"` | `"110798.817000"` |
+| `""` | `"East"` | `""` | `"1475"` | `"685"` | `"691828.168000"` | `"94883.260300"` |
+| `"2024"` | `""` | `""` | `"1723"` | `"704"` | `"745567.531200"` | `"95926.347600"` |
+| `""` | `""` | `"Furniture"` | `"1819"` | `"714"` | `"754747.761300"` | `"19729.995600"` |
+| `"2024"` | `"West"` | `"Furniture"` | `"202"` | `"184"` | `"74155.119500"` | `"2892.830000"` |
+
+West 的 Orders 必须为 `"1635"`，不是其他版本的示例计数。若校验失败，读取 `checks.json` 与查询结果查明差异，不要通过更改默认筛选反复重试同一错误期望。
+
+## 指标与交互
+
+- Sales/Profit/Quantity 为订单行求和；Orders/Customers 为当前筛选的不同订单/客户数。
+- 利润率 = 总利润 / 总销售额；客单价 = 总销售额 / 订单数。分母为零不显示伪造比率。
+- Returns 原表 800 行，先按 Order ID 去重成 296 个订单再关联。ReturnedOrders 忽略 NULL，ReturnedSales 是退货订单关联的销售额，**不是退款或损失**。
+- 年份、区域、品类改变时查询当前页的所有 Binding。各看板控件状态独立；同一页所有面板同范围。
+- 查询错误、截断、无结果时清除之前的指标，保留明确状态；不要继续展示上一筛选的数值。
+- 原值以 decimal 字符串传输，金额展示到两位；绘图及比率计算在验证安全数值范围后转换为 Number。
+
+## 重建与验收
+
+开发者安装 `xlrd==2.0.2` 后运行 `python build_data.py --workbook <下载文件>`；哈希不一致会停止。再运行 `python build_pages.py`，将本目录的业务布局与运行时组合成三个 HTML；主题组件由每页对应的受控文档库注入。Agent 直接使用已安装的组件与配方，不需要运行构建器。原始数据版本、CSV 哈希和许可见 `provenance.json`。
+
+验收：全量 → West → East → 全量，2024、Furniture、组合筛选，刷新、空结果、权限失败、截断、窄屏和深色主题。比较所有图表和总计，确认项目双向同步与 Artifact 归属。浏览器模拟检查只证明页面生命周期；真实 Data Xpert 查询与安装后界面验收另行记录。

package/skills/live-dashboard/examples/superstore/THIRD_PARTY_LICENSE.txt

@@ -0,0 +1,207 @@
+Apache License Version 2.0
+
+Copyright (c) 2026 Salesforce, Inc.
+All rights reserved.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/skills/live-dashboard/examples/superstore/build_data.py

@@ -0,0 +1,155 @@
+"""Rebuild the pinned Tableau teaching dataset (requires xlrd==2.0.2).
+
+Usage: python build_data.py --workbook /path/to/Sample-Superstore.xls
+The original workbook is not modified. Only files in this recipe are generated.
+"""
+import argparse
+import csv
+import hashlib
+import json
+from collections import defaultdict
+from datetime import datetime
+from decimal import Decimal
+from pathlib import Path
+
+SHA256 = 'add4e193479cae8e9f22bfa734dd8bb706355dce38353967668f4e2b6643d19c'
+ROOT = Path(__file__).resolve().parent
+FIELDS = [
+    'row_id', 'order_id', 'order_date', 'ship_date', 'ship_mode', 'customer_id',
+    'customer_name', 'segment', 'country', 'city', 'state', 'postal_code', 'region',
+    'product_id', 'category', 'sub_category', 'product_name', 'sales', 'quantity',
+    'discount', 'profit', 'order_year', 'order_month', 'regional_manager',
+    'returned', 'returned_order_id', 'returned_sales',
+]
+NUMERIC = {'sales', 'profit', 'discount', 'returned_sales'}
+INTEGER = {'row_id', 'quantity'}
+
+
+def money(value):
+    # Excel binary floating-point noise is normalized at six decimal places.
+    return Decimal(str(value)).quantize(Decimal('0.000001'))
+
+
+def read_workbook(path):
+    if hashlib.sha256(path.read_bytes()).hexdigest() != SHA256:
+        raise ValueError('Workbook SHA-256 differs from the pinned Tableau release')
+    import xlrd
+    book = xlrd.open_workbook(str(path))
+    orders, returns, people = [book.sheet_by_name(name) for name in ('Orders', 'Returns', 'People')]
+    if orders.nrows - 1 != 10194 or orders.ncols != 21:
+        raise ValueError('Unexpected Orders shape')
+    return_ids = {str(returns.cell_value(i, 1)) for i in range(1, returns.nrows)}
+    if len(return_ids) != 296 or returns.nrows - 1 != 800:
+        raise ValueError('Unexpected Returns shape')
+    managers = {}
+    for i in range(1, people.nrows):
+        name, region = people.row_values(i)
+        if region in managers:
+            raise ValueError('Duplicate region manager would multiply fact rows')
+        managers[region] = name
+    rows = []
+    for i in range(1, orders.nrows):
+        values = orders.row_values(i)
+        row = dict(zip(FIELDS[:21], values))
+        for key in ('order_date', 'ship_date'):
+            row[key] = xlrd.xldate_as_datetime(row[key], book.datemode).date().isoformat()
+        for key in NUMERIC - {'returned_sales'}:
+            row[key] = money(row[key])
+        for key in INTEGER:
+            if row[key] != int(row[key]):
+                raise ValueError('Non-integer identifier or quantity')
+            row[key] = int(row[key])
+        # Postal codes are labels, never numbers or measures.
+        row['postal_code'] = str(int(row['postal_code'])).zfill(5) if isinstance(row['postal_code'], (int, float)) else str(row['postal_code'])
+        row['order_year'], row['order_month'] = row['order_date'][:4], row['order_date'][:7]
+        row['regional_manager'] = managers[row['region']]
+        returned = row['order_id'] in return_ids
+        row['returned'] = 'Yes' if returned else 'No'
+        row['returned_order_id'] = row['order_id'] if returned else None
+        row['returned_sales'] = row['sales'] if returned else Decimal('0.000000')
+        rows.append(row)
+    if len({r['row_id'] for r in rows}) != len(rows):
+        raise ValueError('Duplicate order-line primary key')
+    if return_ids - {r['order_id'] for r in rows}:
+        raise ValueError('Unmatched return order')
+    return rows
+
+
+def aggregate(rows):
+    total = lambda field: str(sum((r[field] for r in rows), Decimal(0)).quantize(Decimal('0.000001')))
+    return {
+        'Sales': total('sales'), 'Profit': total('profit'),
+        'Quantity': sum(r['quantity'] for r in rows),
+        'Orders': len({r['order_id'] for r in rows}),
+        'Customers': len({r['customer_id'] for r in rows}),
+        'ReturnedOrders': len({r['returned_order_id'] for r in rows if r['returned_order_id']}),
+        'ReturnedSales': total('returned_sales'),
+    }
+
+
+def write_json(name, value):
+    (ROOT / name).write_text(json.dumps(value, ensure_ascii=False, indent=2) + '\n')
+
+
+def build(rows):
+    with (ROOT / 'orders.csv').open('w', newline='') as handle:
+        writer = csv.DictWriter(handle, fieldnames=FIELDS, lineterminator='\n')
+        writer.writeheader()
+        writer.writerows(rows)
+    dimensions = {
+        'OrderYear': ('order_year', '年份'), 'OrderMonth': ('order_month', '订单月份'),
+        'Region': ('region', '区域'), 'Category': ('category', '品类'),
+        'SubCategory': ('sub_category', '子品类'), 'Segment': ('segment', '客户分群'),
+        'Returned': ('returned', '退货标记'), 'RegionalManager': ('regional_manager', '区域经理'),
+    }
+    measures = [
+        ('Sales', 'sales', 'sum', '销售额（USD）'),
+        ('Profit', 'profit', 'sum', '利润（USD）'),
+        ('Quantity', 'quantity', 'sum', '商品件数'),
+        ('Orders', 'order_id', 'distinct-count', '订单数'),
+        ('Customers', 'customer_id', 'distinct-count', '客户数'),
+        ('ReturnedOrders', 'returned_order_id', 'distinct-count', '退货订单数'),
+        ('ReturnedSales', 'returned_sales', 'sum', '退货关联销售额（USD，非退款）'),
+    ]
+    write_json('semantic-model.json', {'cubes': [{
+        'name': 'SuperstoreOrders', 'caption': 'Superstore 订单分析（演示）',
+        'fact': {'type': 'table', 'table': {'name': 'superstore_orders_v1', 'schema': 'public'}},
+        'defaultMeasure': 'Sales',
+        'measures': [{'name': n, 'column': c, 'aggregator': a, 'caption': label,
+                      'datatype': 'Numeric', 'visible': True} for n, c, a, label in measures],
+        'dimensions': [{'name': name, 'caption': label, 'hierarchies': [{
+            'name': name, 'hasAll': True,
+            'levels': [{'name': name, 'column': column, 'type': 'String', 'uniqueMembers': True}],
+        }]} for name, (column, label) in dimensions.items()],
+    }]})
+    cases = {'all': {}, 'west': {'region': 'West'}, 'east': {'region': 'East'},
+             'year2024': {'order_year': '2024'}, 'furniture': {'category': 'Furniture'},
+             'west2024furniture': {'region': 'West', 'order_year': '2024', 'category': 'Furniture'},
+             'empty': {'order_year': '1999'}}
+    expected = {'sourceSha256': SHA256, 'orderLines': len(rows), 'cases': {}}
+    for key, filters in cases.items():
+        selected = [r for r in rows if all(r[k] == v for k, v in filters.items())]
+        item = {'filters': filters, 'rows': len(selected), 'totals': aggregate(selected), 'groups': {}}
+        for dim, (column, _) in dimensions.items():
+            groups = defaultdict(list)
+            for row in selected:
+                groups[row[column]].append(row)
+            item['groups'][dim] = [{dim: member, **aggregate(group)} for member, group in sorted(groups.items())]
+        expected['cases'][key] = item
+    write_json('expected.json', expected)
+    write_json('import.json', [{
+        'catalog': 'public', 'name': 'superstore_orders_v1', 'withHeader': 1,
+        'columns': [{'name': f, 'fieldName': f, 'isKey': f == 'row_id',
+                     'type': 'decimal' if f in NUMERIC else 'integer' if f in INTEGER else 'varchar',
+                     **({'precision': 20, 'fraction': 6} if f in NUMERIC else {'length': 512} if f not in INTEGER else {})}
+                    for f in FIELDS],
+    }])
+    print(json.dumps({'rows': len(rows), 'totals': aggregate(rows),
+                      'csvSha256': hashlib.sha256((ROOT / 'orders.csv').read_bytes()).hexdigest()}))
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--workbook', type=Path, required=True)
+    args = parser.parse_args()
+    build(read_workbook(args.workbook))

package/skills/live-dashboard/examples/superstore/build_pages.py

@@ -0,0 +1,129 @@
+"""Generate self-contained, inspectable HTML recipes and query plans. No data rows are embedded."""
+import json
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+THEME = ROOT.parent.parent / 'themes' / 'trend-workspace'
+OPTIONS = {
+    'year': [['', '全部年份']] + [[str(y), str(y)] for y in range(2021, 2025)],
+    'region': [['', '全部区域']] + [[r, r] for r in ['Central', 'East', 'South', 'West']],
+    'category': [['', '全部品类']] + [[c, c] for c in ['Furniture', 'Office Supplies', 'Technology']],
+}
+CONTROLS = [{'controlId': key, 'label': label, 'type': 'string', 'defaultValue': '',
+             'allowedValues': [value for value, _ in OPTIONS[key]]}
+            for key, label in [('year', '年份'), ('region', '区域'), ('category', '品类')]]
+PAGES = [
+    {'key': 'overview', 'title': '零售经营总览', 'description': '从经营结果到区域与品类贡献',
+     'bindings': {'summary': [], 'trend': ['OrderMonth'], 'regions': ['Region'], 'categories': ['Category']},
+     'panels': ['月度销售与利润', '区域销售贡献'], 'notes': ['USD · 独立总计保留订单和客户去重口径', 'USD · 同一筛选范围'],
+     'dimension': '品类', 'table': '品类经营表现'},
+    {'key': 'profitability', 'title': '商品盈利分析', 'description': '找到贡献利润的商品，以及高销售背后的亏损',
+     'bindings': {'summary': [], 'subcategories': ['SubCategory']},
+     'panels': ['子品类利润排序', '销售额与利润关系'], 'notes': ['USD · 红色表示负利润', '每个点代表一个子品类，悬停查看金额'],
+     'dimension': '子品类', 'table': '子品类盈利明细'},
+    {'key': 'customers', 'title': '客户与退货分析', 'description': '客户结构、订单价值与退货订单关联表现',
+     'bindings': {'summary': [], 'segments': ['Segment'], 'regions': ['Region']},
+     'panels': ['客户分群销售贡献', '各区域退货订单数'], 'notes': ['USD · 客户数在当前范围内去重', '按 Order ID 去重；不代表退货商品件数'],
+     'dimension': '客户分群', 'table': '客户分群与退货明细'},
+]
+checks = []
+for name, case in json.loads((ROOT / 'expected.json').read_text())['cases'].items():
+    if name == 'empty':
+        continue  # 1999 is an SDK/data test, outside the page's allowed years.
+    checks.append({'case': name, 'controls': {
+        'year': case['filters'].get('order_year', ''),
+        'region': case['filters'].get('region', ''),
+        'category': case['filters'].get('category', '')},
+        'summary': {key: str(value) for key, value in case['totals'].items()}})
+(ROOT / 'checks.json').write_text(json.dumps(checks, ensure_ascii=False, indent=2) + '\n')
+CSS = '/* Theme CSS is supplied by the pinned trend-workspace document library. */'
+JS = (ROOT / 'page.js').read_text()
+for page in PAGES:
+    key = page['key']
+    measures = ['Sales', 'Orders', 'Customers', 'ReturnedOrders', 'ReturnedSales'] if key == 'customers' else ['Sales', 'Profit', 'Orders', 'Customers']
+    config = {**page, 'bindings': list(page['bindings']), 'options': OPTIONS, 'measures': measures}
+    metrics = [('销售额（USD）', '订单行销售额合计'), ('利润（USD）', '订单行利润合计'),
+               ('利润率', '利润 ÷ 销售额'), ('订单数', 'Order ID 去重'), ('客户数', 'Customer ID 去重')]
+    if key == 'customers':
+        metrics = [('客户数', 'Customer ID 去重'), ('订单数', 'Order ID 去重'),
+                   ('客单价（USD）', '销售额 ÷ 订单数'), ('退货订单数', '退货 Order ID 去重'), ('退货订单占比', '退货订单数 ÷ 订单数')]
+    filters = ''.join(f'<div class="filter-field"><label for="filter-{c["controlId"]}">{c["label"]}</label><select id="filter-{c["controlId"]}" data-dashboard-control="{c["controlId"]}" disabled></select></div>' for c in CONTROLS)
+    metric_blocks = [f'<div class="metric"><p>{label}</p><output id="metric-{i}">—</output><small>{note}</small></div>' for i, (label, note) in enumerate(metrics)]
+    cards = ''.join(metric_blocks)
+    panels = ''.join(f'<section class="panel"><h2>{page["panels"][i]}</h2><p class="note">{page["notes"][i]}</p><div id="chart-{name}" class="chart" role="img" aria-label="{page["panels"][i]}"></div></section>' for i, name in enumerate(['primary', 'secondary']))
+    headings = [page['dimension'], '销售额（USD）', '利润（USD）', '利润率']
+    if key == 'profitability':
+        headings += ['订单数', '客户数']
+    if key == 'customers':
+        headings = [page['dimension'], '销售额（USD）', '订单数', '客户数', '退货订单数', '退货订单占比', '退货关联销售额（USD）']
+    heads = ''.join(f'<th scope="col">{heading}</th>' for heading in headings)
+    table = f'<section class="details"><h2>{page["table"]}</h2><p class="note">USD · 同一筛选范围</p><div class="table-scroll" tabindex="0" role="region" aria-label="{page["table"]}"><table><thead><tr>{heads}</tr></thead><tbody id="details-rows"></tbody></table></div></section>'
+    if key == 'overview':
+        content = f'''<section class="hero"><h2>月度经营趋势</h2><p class="note">2021–2024 · USD · 销售额与利润分别使用独立刻度</p>
+<h3 class="chart-heading">销售额（USD）</h3><div id="chart-primary" class="chart" role="img" aria-label="月度销售额"></div>
+<h3 class="chart-heading profit">利润（USD）</h3><div id="chart-profit" class="chart chart-profit" role="img" aria-label="月度利润"></div></section>
+<div class="lower-grid"><section class="region-panel"><h2>区域销售贡献</h2><p class="note">USD · 按销售额从高到低</p><div id="chart-secondary" class="chart" role="img" aria-label="区域销售贡献"></div></section>{table}</div>'''
+    else:
+        content = f'<div class="plots">{panels}</div><div class="full-details">{table}</div>'
+    html = f'''<!doctype html>
+<html lang="zh-Hans"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Superstore · {page['title']}</title><style>{CSS}</style></head>
+<body data-page="{key}" data-dashboard-theme="trend-workspace@1"><main class="workspace">
+<aside class="metric-rail"><header><span class="demo">Superstore 演示数据</span><h1>{page['title']}</h1><p class="description">{page['description']}</p></header><section class="metrics" aria-label="当前筛选主要指标">{cards}</section></aside>
+<div class="analysis"><div class="filters" aria-label="分析筛选">{filters}</div>{content}
+<p id="status" class="status" role="status">正在加载…</p>
+<details class="methodology"><summary>数据与指标口径</summary><p>来源：Tableau Superstore 虚构教学工作簿，2021–2024 年，金额单位 USD。退货表先按订单去重，再关联订单行。退货关联销售额不等于退款或收入损失。利润率为合计利润除以合计销售额；订单数与客户数由后端在当前范围内去重，不能累加分组计数。各看板筛选状态独立。</p></details></div>
+<footer><span>2021–2024 · 演示数据 · Data Xpert</span><span id="freshness">尚无当前查询结果</span></footer></main>
+<script>const config={json.dumps(config, ensure_ascii=False, indent=2)};
+{JS}</script></body></html>
+'''
+    if key != 'overview':
+        theme = 'profit-atlas' if key == 'profitability' else 'customer-brief'
+        prefix = 'atlas' if key == 'profitability' else 'brief'
+        global_name = 'ProfitAtlas' if key == 'profitability' else 'CustomerBrief'
+        description = '看清销售与利润之间的差距' if key == 'profitability' else '理解客户结构，关注退货表现'
+        header = f'<header class="{prefix}-header"><div><h1>{page["title"]}</h1><p class="description">{description}</p><span class="demo">Superstore 演示数据 · 2021–2024</span></div><div class="filters" aria-label="分析筛选">{filters}</div></header>'
+        if key == 'profitability':
+            summary = f'<section class="atlas-metrics" aria-label="当前筛选主要指标">{cards}</section>'
+            panel_specs = [('secondary', '销售额与利润关系', '每个点代表一个子品类，悬停查看金额'), ('primary', '子品类利润排名', 'USD · 红色表示负利润')]
+            table = table.replace('USD · 同一筛选范围', '按利润升序 · 完整明细可滚动查看')
+        else:
+            summary = f'<section class="brief-metrics" aria-label="当前筛选主要指标"><div class="brief-primary-metrics">{"".join(metric_blocks[:3])}</div><div class="brief-return-metrics">{metric_blocks[4]}{metric_blocks[3]}</div></section>'
+            panel_specs = [('primary', '<span class="section-number" aria-hidden="true">01</span>客户分群销售贡献', 'USD · 客户数在当前范围内去重'), ('secondary', '<span class="section-number" aria-hidden="true">02</span>各区域退货订单数', '按 Order ID 去重；不代表退货商品件数')]
+        variant_panels = ''.join(f'<section class="panel"><h2>{title}</h2><p class="note">{note}</p><div id="chart-{name}" class="chart" role="img" aria-label="{page["panels"][0 if name == "primary" else 1]}"></div></section>' for name, title, note in panel_specs)
+        script = JS.replace('window.TrendWorkspace', f'window.{global_name}').replace('TrendWorkspaceCharts', 'DashboardCharts')
+        if key == 'customers':
+            script = script.replace("dimension:'Segment',measure:'Sales',label:'销售额（USD）'", "dimension:'Segment',measure:'Sales',label:'销售额（USD）',palette:['blue','segment-two','segment-three']")
+            script = script.replace("label:'退货订单数',decimals:0", "label:'退货订单数',decimals:0,palette:['returns']")
+        html = f'''<!doctype html>
+<html lang="zh-Hans"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Superstore · {page['title']}</title></head>
+<body data-page="{key}" data-dashboard-theme="{theme}@1"><main class="workspace">{header}{summary}
+<div class="analysis"><div class="{prefix}-plots">{variant_panels}</div><div class="full-details">{table}</div>
+<p id="status" class="status" role="status">正在加载…</p>
+<details class="methodology"><summary>数据与指标口径</summary><p>来源：Tableau Superstore 虚构教学工作簿，2021–2024 年，金额单位 USD。退货表先按订单去重，再关联订单行。退货关联销售额不等于退款或收入损失。利润率为合计利润除以合计销售额；订单数与客户数由后端在当前范围内去重，不能累加分组计数。各看板筛选状态独立。</p></details></div>
+<footer><span>2021–2024 · 演示数据 · Data Xpert</span><span id="freshness">尚无当前查询结果</span></footer></main>
+<script>const config={json.dumps(config, ensure_ascii=False, indent=2)};
+{script}</script></body></html>
+'''
+    # Sandbox readers bound individual lines: keep the complete recipe inspectable.
+    markup, scripts = html.split('<script>', 1)
+    html = markup.replace('><', '>\n<') + '<script>' + scripts
+    assert max(len(line.encode('utf-8')) for line in html.splitlines()) <= 500
+    (ROOT / (key + '.html')).write_text(html)
+    queries = []
+    for binding_id, dimensions in page['bindings'].items():
+        fields = [{'id': d, 'sourceField': d, 'label': d, 'logicalType': 'string', 'role': 'dimension', 'nullable': False} for d in dimensions]
+        fields += [{'id': m, 'sourceField': m, 'label': m, 'logicalType': 'decimal' if m in ['Sales', 'Profit', 'ReturnedSales'] else 'int64',
+                    'role': 'measure', 'nullable': m in ['Sales', 'Profit', 'ReturnedSales']} for m in measures]
+        queries.append({
+            'id': binding_id, 'providerId': 'data-xpert.ontology', 'operation': 'action', 'contractVersion': 1,
+            'payload': {'resourceId': '<discovered-resource-id>', 'actionTypeCode': 'sql.query_cube_slice',
+                        'target': {'entityTypeCode': 'semantic_cube', 'entityRef': '<published-model-id>::SuperstoreOrders'},
+                        'params': {'dimensions': dimensions, 'measures': measures,
+                                   'filters': [{'field': d, 'op': 'contains', 'value': ''} for d in ['OrderYear', 'Region', 'Category']], 'limit': 100},
+                        'parameterPaths': {c['controlId']: ['filters', str(i), 'value'] for i, c in enumerate(CONTROLS)}},
+            'parameters': [{'name': c['controlId'], 'controlId': c['controlId'], 'type': 'string', 'required': True,
+                            'defaultValue': '', 'allowedValues': c['allowedValues']} for c in CONTROLS],
+            'output': {'datasetId': binding_id, 'fields': fields, 'grain': dimensions},
+        })
+    (ROOT / (key + '.queries.json')).write_text(json.dumps({'controls': CONTROLS, 'bindings': queries}, ensure_ascii=False, indent=2)+'\n')
+print('Generated three HTML recipes and query plans (no embedded data).')