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

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

@@ -0,0 +1,25 @@
+# Example authoring workflow
+
+Use `read_skill_file` with paths resolved relative to the catalog SKILL.md to read `catalog.json`, then only the selected recipe. Supporting files can be read with the same tool; do not search sandbox directories or pass an absolute skill path to SandboxFile. Each recipe has a stable key and version, source, a preview, semantic field requirements, synthetic CSV/JSON and expected checks. Previews are illustrations of the bundled demo fixture, never evidence of a user's business data. The catalog is bundled with the skill, not a remote marketplace.
+
+The Superstore enterprise suite is an exception to the small file workflow below: read `superstore/README.md` and use its published Data Xpert model, independent totals and multiple Bindings. Do not run file registration for that suite.
+
+## Select the data mode first
+
+An explicit request to “try demo” authorizes copying synthetic fixture data into the currently selected Project. If the mode is unspecified, ask whether to use the demo or real sources. Never put example data into an existing production file or silently use it when a real query fails. Do not create a new Project implicitly; let ChatKit's Project picker establish the scope.
+
+## Execute, do not just return a page
+
+1. Read the recipe's README, `definition.json`, `query.json` and source. Read HTML lifecycle guidance for HTML recipes. `demo.csv` and `demo.json` are alternatives, not two datasets to combine.
+2. Use SandboxFile to write the demo fixture to a new file in the current Project. Inspect an existing path before reusing it; identical bytes may be reused, different bytes need a new path. Registration resolves the current Project from trusted runtime context.
+3. Call `analytics_definition_connections`. Select the actual `file.table` connection, then `analytics_definition_inspect` with that returned selection. Follow the returned schemas. Use `definition.json` with the actual runtime path for `analytics_definition_register`; use a stable requestId for this exact file/definition. Reuse an existing matching authorized definition when available. Do not invent connectionKey, definitionId or versionId.
+4. Refresh `dashboard_list_sources`, discover the registered source, and use its current `bindingPayload`. Merge `query.json.payloadFields` into that payload. Bind query parameter names to the same control IDs. Output fields map to the recipe column keys, with the actual declared types/units/nullability and explicit grain.
+5. Use `dashboard_preview` for defaults and at least two filter values. Compare real returned rows, completeness, totals and weighted ratios with `expected.json`. Use `dashboard_test_filter` from the preview checks for the two filter values; keep the original default/null Binding. Use exactly one current successful preview receipt for the one saved Binding, not a duplicate Binding per tested filter. Keep the returned datasetId in standard chart/table definitions. An HTML example expects exactly one saved complete Binding and resolves its ID from the SDK's declared bindingIds.
+6. Standard recipe: call `dashboard_create` using `dashboard-create.json` with this run's previewId and datasetId. HTML: call `dashboard_libraries`, write the complete HTML file, then `dashboard_create_html` with this run's previewIds, declared controls and `libraries:["echarts"]`. Do not publish automatically. Fix preflight errors before claiming success.
+7. Stop authoring after the successful draft receipt and report it with the checked values. Do not call dashboard_open/update to confirm an unchanged save. The emitted card lets the user open the exact dashboard. UI acceptance verifies the persisted draft in Live Dashboard: all → option A → option B → all, chart, totals, details and toolbar refresh. A successful query alone is not proof of visible correct charts. Check Project synchronization and report the actual draft receipt. Publication is a separate human action.
+
+## Adapt to business data
+
+Use authorized files, database sources or published Data Xpert ontology resources. Discover and preview the actual source first. Map fields explicitly; confirm grain, currency, units and date semantics. Missing fields or denied access are blockers for the affected panel, not permission to invent data. For quality, weighted yield is sum(good)/sum(produced); a zero denominator displays “—”. These examples use safe integer counts and whole currency units; fractional or high-precision monetary data requires exact decimal aggregation and formatting rather than silently coercing to Number.
+
+Never copy demonstration IDs, old preview receipts, file scope, credentials or backend SQL into HTML. Remove the visible demo label only after replacing and verifying all demo bindings. Preserve loading, empty, incomplete and error states; clear stale charts when a query fails. Keep every panel on the same filter. Existing saved dashboards are independent Artifacts: updating this example pack must not modify them. To edit one, use `dashboard_open` and its exact revision followed by the existing update workflow.

package/skills/live-dashboard/examples/catalog.json

@@ -0,0 +1,79 @@
+{
+  "schemaVersion": 1,
+  "examples": [
+    {
+      "key": "regional-sales",
+      "version": 1,
+      "title": "区域销售",
+      "mode": "standard",
+      "recipe": "regional-sales/README.md",
+      "source": "regional-sales/dashboard-create.json",
+      "preview": "regional-sales/preview.png",
+      "data": [
+        "demo.csv",
+        "demo.json"
+      ],
+      "dataMode": "synthetic-demo",
+      "libraries": []
+    },
+    {
+      "key": "sales-overview",
+      "version": 1,
+      "title": "销售总览",
+      "mode": "html",
+      "recipe": "sales-overview/README.md",
+      "source": "sales-overview/dashboard.html",
+      "preview": "sales-overview/preview.png",
+      "data": [
+        "demo.csv",
+        "demo.json"
+      ],
+      "dataMode": "synthetic-demo",
+      "libraries": [
+        "echarts"
+      ]
+    },
+    {
+      "key": "production-quality",
+      "version": 1,
+      "title": "生产质量",
+      "mode": "html",
+      "recipe": "production-quality/README.md",
+      "source": "production-quality/dashboard.html",
+      "preview": "production-quality/preview.png",
+      "data": [
+        "demo.csv",
+        "demo.json"
+      ],
+      "dataMode": "synthetic-demo",
+      "libraries": [
+        "echarts"
+      ]
+    },
+    {
+      "key": "superstore",
+      "version": 1,
+      "title": "Superstore 企业 BI",
+      "mode": "html-suite",
+      "recipe": "superstore/README.md",
+      "sources": [
+        "superstore/overview.html",
+        "superstore/profitability.html",
+        "superstore/customers.html"
+      ],
+      "previews": [
+        "superstore/overview.png",
+        "superstore/profitability.png",
+        "superstore/customers.png"
+      ],
+      "data": [
+        "orders.csv"
+      ],
+      "dataMode": "tableau-teaching-data",
+      "providerId": "data-xpert.ontology",
+      "libraries": [
+        "echarts"
+      ]
+    }
+  ]
+}

package/skills/live-dashboard/examples/production-quality/README.md

@@ -0,0 +1,25 @@
+# 生产质量 / production-quality — v1
+
+这是可复制的制作配方，演示数据是人为构造的，不代表任何客户或业务。`preview.png` 是这份演示数据的页面预览。
+
+## 数据与口径
+
+- 粒度：`date, line`，同一粒度不重复。产量、良品数和不良品数的单位为件，均为非负整数。
+- 筛选：`line`，默认 `null` 表示全部；不要用字符串 `"null"`。
+- 良品率 = sum(good) / sum(produced)，不能平均每行百分比；无产量时显示“—”。defects 为不良品数量，不是缺陷事件数。
+- `definition.json` 给出列类型和业务说明；`query.json` 给出查询字段、参数和控件；`expected.json` 给出验收结果。
+
+## 用演示数据制作
+
+1. 读取主技能及 `../README.md`。确认当前 ChatKit 项目已选定，用户明确要求演示数据。
+2. 读取 `demo.csv`，以 SandboxFile 工具写入当前项目的 `live-dashboard-examples/production-quality/demo-v1.csv`。如果已存在，先读内容；不同则使用新文件名，不覆盖。`demo.json` 是同一数据的替代输入，使用时 reader 应为 `{"format":"json","rowsPath":[]}`，列 path 保持相同。
+3. 按共享制作流程注册实际文件并取得当前 source / discovery / bindingPayload；不要把文件路径放进 Binding payload。
+4. 基于 `query.json`，使用发现结果的 datasetId、revision 和 contractHash 构造查询。预览全部、至少两个筛选值，逐项比对 `expected.json`。输出字段 id 必须与本样例列 key 一致；logicalType/nullable/unit 必须与发现结果一致。
+5. 读取 `dashboard.html`，仅使用本次唯一的完整 Dataset Binding。保留注释中的数据与生命周期约束。调用 dashboard_libraries，写入当前项目文件，再使用本次 previewIds、query.json 的 controls 和 libraries:["echarts"] 调用 dashboard_create_html。
+6. 检查成功保存回执，报告看板及草稿修订，结束制作；不要为了确认保存而再调用 dashboard_open/update。用户通过回执卡片打开看板核对筛选、刷新与项目归属。保存失败不得宣布完成，发布仍需人工确认。
+
+## 换成真实数据
+
+先使用已授权来源发现与真实预览，将业务字段映射到本配方列（或同步改写页面字段和控件）。确认粒度、单位、日期和指标口径。缺少必要字段时说明缺口，不插入演示行、不补零、不复制旧 source/preview/Artifact ID。移除演示标识仅限绑定和所有可见数值均来自已验证真实来源之后。
+
+配方更新不迁移或覆盖已创建的看板。编辑现有看板必须先 dashboard_open，保持 Artifact、组件 ID 和预期修订。

package/skills/live-dashboard/examples/production-quality/dashboard.html

@@ -0,0 +1,129 @@
+<!doctype html>
+<html lang="zh-Hans">
+<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>生产质量 · 演示数据</title>
+<style>
+:root{color-scheme:light;--bg:#f5f7fa;--paper:#fff;--ink:#172d42;--muted:#526579;--line:#d8e0e8;--accent:#22649a;--second:#16847d}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--ink);font:15px/1.5 system-ui,"PingFang SC",sans-serif}
+body.dark{color-scheme:dark;--bg:#142433;--paper:#1c3042;--ink:#ecf2f8;--muted:#b0c2d1;--line:#3b5266;--accent:#75b7ee;--second:#65cabc}
+main{max-width:1320px;margin:auto;padding:28px}
+header{display:flex;justify-content:space-between;align-items:flex-start;gap:20px;border-bottom:1px solid var(--line);padding-bottom:20px}
+h1{font-size:26px;line-height:1.3;margin:4px 0 8px}
+h2{font-size:17px;margin:0 0 8px}
+p{margin:0}
+.muted{color:var(--muted)}
+.demo{display:inline-block;border:1px solid var(--line);border-radius:4px;padding:2px 7px;font-size:12px}
+.filter{display:grid;gap:6px;min-width:160px}
+select{font:inherit;color:var(--ink);background:var(--paper);border:1px solid var(--line);border-radius:6px;padding:9px}
+select:focus-visible{outline:2px solid var(--accent);outline-offset:3px}
+.metrics{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:24px;padding:25px 0}
+.metric{border-left:3px solid var(--accent);padding-left:16px}
+.metric p{color:var(--muted)}
+.metric output{font-size:32px;font-weight:650;font-variant-numeric:tabular-nums;display:block}
+.plots{display:grid;grid-template-columns:3fr 2fr;gap:20px}
+.panel{min-width:0;background:var(--paper);padding:20px;border:1px solid var(--line);border-radius:8px}
+.chart{height:300px}
+.details{margin-top:20px;overflow:auto}
+table{width:100%;border-collapse:collapse;white-space:nowrap;font-variant-numeric:tabular-nums}
+caption{text-align:left;font-size:17px;font-weight:600;margin-bottom:10px}
+th,td{padding:10px 12px;border-bottom:1px solid var(--line);text-align:right}
+th:first-child,td:first-child{text-align:left}
+th{color:var(--muted);font-weight:500}
+#feedback{min-height:28px;margin-top:16px}
+footer{display:flex;justify-content:space-between;gap:16px;margin-top:20px;font-size:12px;color:var(--muted)}
+@media(max-width:700px){main{padding:16px}
+header{flex-direction:column}
+.filter{width:100%}
+.metrics{gap:12px}
+.metric{padding-left:8px}
+.metric output{font-size:24px}
+.plots{grid-template-columns:1fr}
+.panel{padding:14px}
+footer{flex-direction:column}
+}
+@media(prefers-reduced-motion:reduce){*{scroll-behavior:auto}
+}
+
+</style></head>
+<body><main>
+<header><div><span class="demo">演示数据 · 人为构造</span><h1>生产质量</h1><p class="muted">同一产线口径下核对产量与质量</p></div><label class="filter" for="scope">产线<select id="scope" data-dashboard-control="line" disabled></select></label></header>
+<section class="metrics" aria-label="主要指标"><div class="metric"><p>产量</p><output id="produced">—</output></div><div class="metric"><p>加权良品率（%）</p><output id="yield">—</output></div><div class="metric"><p>不良品数</p><output id="defects">—</output></div></section>
+<div class="plots"><section class="panel"><h2>每日产量趋势</h2><p class="muted">产量（件）</p><div id="trend" class="chart" role="img" aria-label="每日产量趋势，同一数据详见下表"></div></section><section class="panel"><h2>产线不良品对比</h2><p class="muted">不良品数（件）</p><div id="breakdown" class="chart" role="img" aria-label="产线不良品对比，同一数据详见下表"></div></section></div>
+<p id="feedback" role="status">正在查询…</p>
+<section class="panel details"><table><caption>数据明细</caption><thead><tr><th scope="col">日期</th><th scope="col">产线</th><th scope="col">产量</th><th scope="col">良品数</th><th scope="col">不良品数</th></tr></thead><tbody id="rows"></tbody></table></section>
+<footer><span>良品率 = 良品数合计 ÷ 产量合计；不良品数 = 产量 − 良品数。</span><span id="freshness">尚未取得查询结果</span></footer>
+</main><script>
+// Example v1. One complete Dataset drives every panel. Adapt explicit field IDs after real preview.
+// No business rows, source IDs, query text or credentials belong in this HTML.
+(async () => {
+  const live = window.xpertLiveArtifact;
+  const filter = document.getElementById('scope');
+  const feedback = document.getElementById('feedback');
+  const fields = ["date", "line", "produced", "good", "defects"];
+  const measures = ["produced", "good", "defects"];
+  const fmt = new Intl.NumberFormat('zh-CN', {maximumFractionDigits: 2});
+  let trend, breakdown;
+  function clear(message) {
+    document.querySelectorAll('output').forEach(el => { el.textContent = '—'; });
+    document.getElementById('rows').replaceChildren();
+    trend?.clear(); breakdown?.clear();
+    feedback.textContent = message;
+    document.getElementById('freshness').textContent = '当前结果不可用';
+  }
+  function total(rows, field) {
+    const values = rows.map(row => {
+      const raw = row[field];
+      if (typeof raw !== 'string' && typeof raw !== 'number' || !/^\d+$/.test(String(raw))) throw Error('计数字段或金额单位不符合样例口径');
+      const n = Number(raw); if (!Number.isSafeInteger(n)) throw Error('数值超过本样例安全整数范围');
+      return n;
+    });
+    const sum = values.reduce((a,b) => a+b,0);
+    if (!Number.isSafeInteger(sum)) throw Error('合计超过本样例安全整数范围');
+    return sum;
+  }
+  function group(rows, dimension, measure) {
+    const groups = new Map();
+    for (const row of rows) {
+      if (typeof row[dimension] !== 'string') throw Error('维度字段缺失');
+      const key = row[dimension]; if (!groups.has(key)) groups.set(key,[]); groups.get(key).push(row);
+    }
+    return [...groups].sort(([a],[b])=>a.localeCompare(b)).map(([key,items])=>[key,total(items,measure)]);
+  }
+  function render(dataset) {
+    try {
+      if (!dataset.completeness || dataset.completeness.truncated) { clear('结果不完整，请缩小范围后重试；当前不显示汇总值。'); return; }
+      const rows = dataset.rows;
+      if (!rows.length) { clear('此筛选下没有数据。'); return; }
+      for (const row of rows) for (const field of fields) if (row[field] === null || row[field] === undefined) throw Error('必要字段为空，无法展示完整指标');
+      const totals = Object.fromEntries(measures.map(field => [field,total(rows,field)]));
+      if(totals.good>totals.produced || totals.defects!==totals.produced-totals.good) throw Error('产量、良品与不良品数量不一致');document.getElementById('produced').textContent=fmt.format(totals.produced);document.getElementById('defects').textContent=fmt.format(totals.defects);document.getElementById('yield').textContent=totals.produced ? fmt.format(totals.good/totals.produced*100) : '—';
+      const daily = group(rows,'date','produced');
+      const groups = group(rows,'line','defects');
+      const color = getComputedStyle(document.body).getPropertyValue('--ink').trim();
+      const line = getComputedStyle(document.body).getPropertyValue('--line').trim();
+      const axis = {axisLabel:{color},axisLine:{lineStyle:{color:line}},splitLine:{lineStyle:{color:line}}};
+      trend.setOption({animation:false,aria:{enabled:true},color:['#3984bd'],grid:{left:60,right:18,top:28,bottom:35},tooltip:{trigger:'axis'},xAxis:{...axis,type:'category',data:daily.map(([k])=>k)},yAxis:{...axis,type:'value'},series:[{id:'daily',name:'产量（件）',type:'line',symbolSize:7,areaStyle:{opacity:0.08},data:daily.map(([,v])=>v)}]},{notMerge:true});
+      breakdown.setOption({animation:false,aria:{enabled:true},color:['#16847d'],grid:{left:65,right:30,top:20,bottom:35},tooltip:{trigger:'axis'},xAxis:{...axis,type:'value'},yAxis:{...axis,type:'category',data:groups.map(([k])=>k)},series:[{id:'breakdown',name:'不良品数（件）',type:'bar',barMaxWidth:38,label:{show:true,position:'right',color},data:groups.map(([,v])=>v)}]},{notMerge:true});
+      document.getElementById('rows').replaceChildren(...rows.map(row => { const tr=document.createElement('tr'); for(const field of fields){const td=document.createElement('td');td.textContent=String(row[field]);tr.append(td);}return tr;}));
+      feedback.textContent = '已显示 '+ rows.length +' 行，所有图表与指标使用同一筛选结果。';
+      document.getElementById('freshness').textContent = '查询时间：'+(dataset.freshness?.sourceFetchedAt ?? '未提供');
+    } catch (error) { clear(error.message || '数据无法展示'); }
+  }
+  try {
+    const context = await live.ready();
+    document.body.classList.toggle('dark', context.theme === 'dark');
+    if (context.bindingIds.length !== 1) throw Error('本样例要求一个已验证的完整数据集');
+    const bindingId = context.bindingIds[0];
+    trend=window.echarts.init(document.getElementById('trend'),null,{renderer:'svg'});
+    breakdown=window.echarts.init(document.getElementById('breakdown'),null,{renderer:'svg'});
+    new ResizeObserver(()=>{trend.resize();breakdown.resize();}).observe(document.querySelector('.plots'));
+    // Subscribe before bindSelect/query so toolbar refresh uses this same render function.
+    live.subscribe(bindingId,render);
+    filter.addEventListener('change',()=>clear('正在查询…'));
+    filter.addEventListener('xpert-query-error',()=>clear('查询失败，请检查访问权限或重试。'));
+    live.bindSelect(filter,{bindingId,controlId:'line',fieldId:'line',allLabel:'全部'});
+    await live.query(bindingId,{...context.defaults});
+    filter.disabled=false;
+  } catch(error) { clear(error.message || '查询失败，请重试'); }
+})();
+</script></body></html>

package/skills/live-dashboard/examples/production-quality/definition.json

@@ -0,0 +1,67 @@
+{
+  "path": "live-dashboard-examples/production-quality/demo-v1.csv",
+  "name": "生产质量 · 演示数据 v1",
+  "description": "Synthetic example data; not business results. Yield = sum(good)/sum(produced); defects = produced-good. Rows are disjoint.",
+  "reader": {
+    "format": "csv",
+    "delimiter": ",",
+    "headerRow": 1
+  },
+  "columns": [
+    {
+      "key": "date",
+      "path": [
+        "date"
+      ],
+      "label": "日期",
+      "description": "Synthetic demonstration only. Unique daily dimension grain.",
+      "logicalType": "date",
+      "nullable": false,
+      "role": "time"
+    },
+    {
+      "key": "line",
+      "path": [
+        "line"
+      ],
+      "label": "产线",
+      "description": "Synthetic demonstration only. Unique daily dimension grain.",
+      "logicalType": "string",
+      "nullable": false,
+      "role": "dimension"
+    },
+    {
+      "key": "produced",
+      "path": [
+        "produced"
+      ],
+      "label": "产量",
+      "description": "Synthetic demonstration only. Nonnegative whole-item count.",
+      "logicalType": "int64",
+      "nullable": false,
+      "role": "measure"
+    },
+    {
+      "key": "good",
+      "path": [
+        "good"
+      ],
+      "label": "良品数",
+      "description": "Synthetic demonstration only. Nonnegative whole-item count.",
+      "logicalType": "int64",
+      "nullable": false,
+      "role": "measure"
+    },
+    {
+      "key": "defects",
+      "path": [
+        "defects"
+      ],
+      "label": "不良品数",
+      "description": "Synthetic demonstration only. Nonnegative whole-item count.",
+      "logicalType": "int64",
+      "nullable": false,
+      "role": "measure"
+    }
+  ]
+}

package/skills/live-dashboard/examples/production-quality/demo.csv

@@ -0,0 +1,7 @@
+date,line,produced,good,defects
+2026-01-01,Line A,100,96,4
+2026-01-01,Line B,120,114,6
+2026-01-02,Line A,110,104,6
+2026-01-02,Line B,130,126,4
+2026-01-03,Line A,120,117,3
+2026-01-03,Line B,140,133,7

package/skills/live-dashboard/examples/production-quality/demo.json

@@ -0,0 +1,44 @@
+[
+  {
+    "date": "2026-01-01",
+    "line": "Line A",
+    "produced": 100,
+    "good": 96,
+    "defects": 4
+  },
+  {
+    "date": "2026-01-01",
+    "line": "Line B",
+    "produced": 120,
+    "good": 114,
+    "defects": 6
+  },
+  {
+    "date": "2026-01-02",
+    "line": "Line A",
+    "produced": 110,
+    "good": 104,
+    "defects": 6
+  },
+  {
+    "date": "2026-01-02",
+    "line": "Line B",
+    "produced": 130,
+    "good": 126,
+    "defects": 4
+  },
+  {
+    "date": "2026-01-03",
+    "line": "Line A",
+    "produced": 120,
+    "good": 117,
+    "defects": 3
+  },
+  {
+    "date": "2026-01-03",
+    "line": "Line B",
+    "produced": 140,
+    "good": 133,
+    "defects": 7
+  }
+]

package/skills/live-dashboard/examples/production-quality/expected.json

@@ -0,0 +1,26 @@
+{
+  "all": {
+    "produced": 720,
+    "good": 690,
+    "defects": 30,
+    "yieldPercent": 95.83333333333333
+  },
+  "filtered": {
+    "Line A": {
+      "produced": 330,
+      "good": 317,
+      "defects": 13
+    },
+    "Line B": {
+      "produced": 390,
+      "good": 373,
+      "defects": 17
+    }
+  },
+  "checks": [
+    "All \u2192 first option \u2192 second option \u2192 all; chart, KPI and detail agree.",
+    "Refresh uses the current filter.",
+    "Empty results clear charts and show no-data; errors never show old totals as current.",
+    "Saved draft remains unpublished and belongs to current Project."
+  ]
+}

package/skills/live-dashboard/examples/production-quality/query.json

@@ -0,0 +1,53 @@
+{
+  "payloadFields": {
+    "select": [
+      "date",
+      "line",
+      "produced",
+      "good",
+      "defects"
+    ],
+    "filters": [
+      {
+        "column": "line",
+        "operator": "eq",
+        "value": {
+          "type": "parameter",
+          "name": "line"
+        },
+        "skipWhenNull": true
+      }
+    ],
+    "orderBy": [
+      {
+        "column": "date",
+        "direction": "asc"
+      },
+      {
+        "column": "line",
+        "direction": "asc"
+      }
+    ]
+  },
+  "parameters": [
+    {
+      "name": "line",
+      "controlId": "line",
+      "type": "string",
+      "required": false,
+      "defaultValue": null
+    }
+  ],
+  "grain": [
+    "date",
+    "line"
+  ],
+  "controls": [
+    {
+      "controlId": "line",
+      "label": "产线",
+      "type": "string",
+      "defaultValue": null
+    }
+  ]
+}

package/skills/live-dashboard/examples/regional-sales/README.md

@@ -0,0 +1,25 @@
+# 区域销售 / regional-sales — v1
+
+这是可复制的制作配方，演示数据是人为构造的，不代表任何客户或业务。`preview.png` 是这份演示数据的页面预览。
+
+## 数据与口径
+
+- 粒度：`region`，同一粒度不重复。金额单位为整元 CNY；数量为非负整数。
+- 筛选：`region`，默认 `null` 表示全部；不要用字符串 `"null"`。
+- 金额可按互斥粒度求和；订单数同一粒度不可重复计算。
+- `definition.json` 给出列类型和业务说明；`query.json` 给出查询字段、参数和控件；`expected.json` 给出验收结果。
+
+## 用演示数据制作
+
+1. 读取主技能及 `../README.md`。确认当前 ChatKit 项目已选定，用户明确要求演示数据。
+2. 读取 `demo.csv`，以 SandboxFile 工具写入当前项目的 `live-dashboard-examples/regional-sales/demo-v1.csv`。如果已存在，先读内容；不同则使用新文件名，不覆盖。`demo.json` 是同一数据的替代输入，使用时 reader 应为 `{"format":"json","rowsPath":[]}`，列 path 保持相同。
+3. 按共享制作流程注册实际文件并取得当前 source / discovery / bindingPayload；不要把文件路径放进 Binding payload。
+4. 基于 `query.json`，使用发现结果的 datasetId、revision 和 contractHash 构造查询。预览全部、至少两个筛选值，逐项比对 `expected.json`。输出字段 id 必须与本样例列 key 一致；logicalType/nullable/unit 必须与发现结果一致。
+5. 读取 `dashboard-create.json`，将 previewIds 替换为本次预览凭证，图表/table 的 datasetId 替换为预览返回值，再调用 dashboard_create。
+6. 检查成功保存回执，报告看板及草稿修订；打开看板核对筛选、刷新与项目归属。保存失败不得宣布完成，发布仍需人工确认。
+
+## 换成真实数据
+
+先使用已授权来源发现与真实预览，将业务字段映射到本配方列（或同步改写页面字段和控件）。确认粒度、单位、日期和指标口径。缺少必要字段时说明缺口，不插入演示行、不补零、不复制旧 source/preview/Artifact ID。移除演示标识仅限绑定和所有可见数值均来自已验证真实来源之后。
+
+配方更新不迁移或覆盖已创建的看板。编辑现有看板必须先 dashboard_open，保持 Artifact、组件 ID 和预期修订。

package/skills/live-dashboard/examples/regional-sales/dashboard-create.json

@@ -0,0 +1,35 @@
+{
+  "title": "区域销售 · 演示数据",
+  "previewIds": [
+    "<current-preview-id>"
+  ],
+  "controls": [
+    {
+      "controlId": "region",
+      "label": "区域",
+      "type": "string",
+      "defaultValue": null
+    }
+  ],
+  "charts": [
+    {
+      "id": "region-sales",
+      "title": "区域销售额 · CNY",
+      "type": "bar",
+      "datasetId": "<preview-dataset-id>",
+      "x": "region",
+      "y": "amount"
+    }
+  ],
+  "tables": [
+    {
+      "id": "sales-details",
+      "title": "销售明细 · 演示数据",
+      "datasetId": "<preview-dataset-id>",
+      "fields": [
+        "region",
+        "amount"
+      ]
+    }
+  ]
+}

package/skills/live-dashboard/examples/regional-sales/definition.json

@@ -0,0 +1,35 @@
+{
+  "path": "live-dashboard-examples/regional-sales/demo-v1.csv",
+  "name": "区域销售 · 演示数据 v1",
+  "description": "Synthetic example data; not business results. Rows have disjoint grain; amount is whole CNY and orders are counts.",
+  "reader": {
+    "format": "csv",
+    "delimiter": ",",
+    "headerRow": 1
+  },
+  "columns": [
+    {
+      "key": "region",
+      "path": [
+        "region"
+      ],
+      "label": "区域",
+      "description": "Synthetic demonstration only. Unique daily dimension grain.",
+      "logicalType": "string",
+      "nullable": false,
+      "role": "dimension"
+    },
+    {
+      "key": "amount",
+      "path": [
+        "amount"
+      ],
+      "label": "销售额",
+      "description": "Synthetic demonstration only. Whole CNY, no fractional currency.",
+      "logicalType": "int64",
+      "nullable": false,
+      "role": "measure",
+      "unit": "CNY"
+    }
+  ]
+}

package/skills/live-dashboard/examples/regional-sales/demo.csv

@@ -0,0 +1,5 @@
+region,amount
+East,12000
+West,18000
+North,9000
+South,11000

package/skills/live-dashboard/examples/regional-sales/demo.json

@@ -0,0 +1,18 @@
+[
+  {
+    "region": "East",
+    "amount": 12000
+  },
+  {
+    "region": "West",
+    "amount": 18000
+  },
+  {
+    "region": "North",
+    "amount": 9000
+  },
+  {
+    "region": "South",
+    "amount": 11000
+  }
+]

package/skills/live-dashboard/examples/regional-sales/expected.json

@@ -0,0 +1,19 @@
+{
+  "all": {
+    "amount": 50000
+  },
+  "filtered": {
+    "East": {
+      "amount": 12000
+    },
+    "West": {
+      "amount": 18000
+    }
+  },
+  "checks": [
+    "All \u2192 first option \u2192 second option \u2192 all; chart, KPI and detail agree.",
+    "Refresh uses the current filter.",
+    "Empty results clear charts and show no-data; errors never show old totals as current.",
+    "Saved draft remains unpublished and belongs to current Project."
+  ]
+}