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

package/scripts/import-prompts.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module'
+import { realpathSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+import { parseArgs } from 'node:util'
+
+const require = createRequire(import.meta.url)
+const { dashboardWorkspacePrompts } = require('../dist/lib/prompt-workflows.js')
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/** Create-only import: no Assistant edits, broad associations, replacement or automatic publication. */
+export async function importPrompts({ apiUrl, organizationId, assistantId, token, apply = false, request = fetch, log = console.log }) {
+  const base = new URL(apiUrl.endsWith('/') ? apiUrl : `${apiUrl}/`)
+  if (base.username || base.password || base.search || base.hash ||
+      !['http:', 'https:'].includes(base.protocol)) throw new Error('Use an HTTP(S) API base URL without credentials, query or fragment.')
+  if (base.protocol === 'http:' && !['localhost', '127.0.0.1', '[::1]'].includes(base.hostname))
+    throw new Error('Use HTTPS for a remote API. TLS certificate verification must remain enabled.')
+  if (!uuid.test(organizationId) || !uuid.test(assistantId)) throw new Error('Organization and Assistant IDs must be UUIDs.')
+  const bearer = token?.trim().replace(/^Bearer\s+/i, '')
+  if (!bearer) throw new Error('Set XPERT_TOKEN to a platform login token.')
+  const headers = { Authorization: `Bearer ${bearer}`, 'organization-id': organizationId, 'Content-Type': 'application/json' }
+  async function api(path, body) {
+    const response = await request(new URL(path, base), {
+      method: body ? 'POST' : 'GET', headers, redirect: 'error', signal: AbortSignal.timeout(30000),
+      ...(body ? { body: JSON.stringify(body) } : {})
+    })
+    if (!response.ok) throw new Error(`API ${body ? 'POST' : 'GET'} failed (${response.status}). No existing data was overwritten. Rerun to inspect partial progress.`)
+    return response.json()
+  }
+  const assistant = await api(`xpert/${assistantId}`)
+  if (assistant?.id !== assistantId || !uuid.test(assistant.workspaceId ?? '') ||
+      assistant.organizationId !== organizationId || assistant.latest === false)
+    throw new Error('The Assistant must be the current version in the selected organization and an authoring workspace.')
+  const nodes = assistant.graph?.nodes
+  if (!Array.isArray(nodes)) throw new Error('The Assistant has no published graph. Configure and publish LiveDashboard first.')
+  const middlewares = nodes.filter(node => node?.type === 'workflow' && node.entity?.type === 'middleware' && node.entity.provider === 'LiveDashboard')
+  // Required middleware is always active, so prompts need no stale per-Assistant node keys.
+  if (middlewares.length !== 1 || middlewares[0].entity.required !== true)
+    throw new Error('Configure one LiveDashboard middleware as required (System middleware), publish, then rerun.')
+  async function runtimeCommands() {
+    const runtime = await api(`xpert/${assistantId}/runtime-capabilities`)
+    if (!Array.isArray(runtime?.commands)) throw new Error('Unexpected runtime command response; import stopped.')
+    return runtime.commands
+  }
+  const commands = await runtimeCommands()
+  if (!commands.some(command => command.source?.type === 'middleware' && command.source.provider === 'LiveDashboard' && command.source.nodeKey === middlewares[0].key))
+    throw new Error('Published LiveDashboard commands are unavailable. Connect the middleware to the main Agent and load the updated plugin first.')
+  function available(workflow, existing, catalog) {
+    return catalog.some(command => command.name === workflow.name && command.kind === 'prompt_workflow' &&
+      command.source?.type === 'workspace_prompt_workflow' && command.source.workflowId === existing.id &&
+      command.action?.type === 'insert_text' && command.action.template === workflow.template)
+  }
+  const workspace = encodeURIComponent(assistant.workspaceId)
+  const creates = []
+  const skipped = []
+  const conflicts = []
+  for (const workflow of dashboardWorkspacePrompts) {
+    const data = encodeURIComponent(JSON.stringify({ where: { name: workflow.name }, take: 2 }))
+    const page = await api(`prompt-workflow/by-workspace/${workspace}?data=${data}`)
+    if (!Array.isArray(page?.items) || page.total !== page.items.length || page.total > 1 ||
+        page.items.some(item => item?.name !== workflow.name)) throw new Error('Unexpected prompt lookup result; import stopped.')
+    const existing = page.items[0]
+    if (existing) {
+      const applicable = !existing.associatedXpertIds?.length || existing.associatedXpertIds.includes(assistantId)
+      if (existing.archivedAt || existing.actionType === 'insert_invocation' || existing.actionType === 'submit_prompt' ||
+          existing.template !== workflow.template || !applicable || !available(workflow, existing, commands)) conflicts.push(workflow.name)
+      else skipped.push(workflow.name)
+    } else {
+      if (commands.some(command => command.name === workflow.name)) conflicts.push(workflow.name)
+      creates.push({ ...workflow, associatedXpertIds: [assistantId] })
+    }
+  }
+  if (conflicts.length) throw new Error(`Resolve existing prompts in the workspace prompt library before importing (no writes made): ${[...new Set(conflicts)].join(', ')}. Associate the existing prompt with this Assistant if appropriate; user edits and archived prompts are preserved.`)
+  log(`${apply ? 'Apply' : 'Preview'}: create ${creates.length}, already available ${skipped.length}. Assistant ${assistantId}.`)
+  const created = []
+  const savedWorkflows = []
+  if (apply) for (const body of creates) {
+    const saved = await api(`prompt-workflow/workspace/${workspace}`, body)
+    if (!uuid.test(saved?.id ?? '') || saved.name !== body.name ||
+        saved.template !== body.template || !saved.associatedXpertIds?.includes(assistantId))
+      throw new Error(`Creation response did not confirm ${body.name}; inspect the prompt library before retrying.`)
+    created.push(body.name)
+    savedWorkflows.push(saved)
+    log(`Created ${body.name}`)
+  }
+  if (savedWorkflows.length) {
+    const updated = await runtimeCommands()
+    if (savedWorkflows.some(workflow => !available(workflow, workflow, updated)))
+      throw new Error('Prompts were created but runtime shortcuts are not confirmed. Inspect the Assistant command settings; existing data was not overwritten.')
+    log('Created shortcuts confirmed by the published Assistant runtime.')
+  }
+  return { planned: creates.map(item => item.name), created, skipped }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  try {
+    const { values } = parseArgs({ options: {
+      'api-url': { type: 'string' }, 'organization-id': { type: 'string' },
+      'assistant-id': { type: 'string' }, apply: { type: 'boolean', default: false }, help: { type: 'boolean' }
+    } })
+    if (values.help) console.log('Set XPERT_TOKEN, then run import-prompts.mjs --api-url https://host/api --organization-id UUID --assistant-id UUID [--apply]. Default: read-only preview. Requires Node 20+.')
+    else if (!values['api-url'] || !values['organization-id'] || !values['assistant-id']) throw new Error('Required: --api-url, --organization-id, --assistant-id. See --help.')
+    else await importPrompts({ apiUrl: values['api-url'], organizationId: values['organization-id'], assistantId: values['assistant-id'], token: process.env.XPERT_TOKEN, apply: values.apply })
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : 'Prompt import failed.')
+    process.exitCode = 1
+  }
+}

package/skills/live-dashboard/SKILL.md

@@ -7,9 +7,18 @@ description: Create and continuously edit saved live dashboards, including free-
 
 Use the platform SandboxFile tools to author source files. Use the dashboard tools to validate and save the business document. This skill belongs to the Live Dashboard plugin; data-source-specific query formats remain owned by each provider.
 
+## Quick start and examples
+
+For a first dashboard or a request for examples, read [examples/catalog.json](examples/catalog.json), [the shared workflow](examples/README.md), and only the selected recipe. Offer regional-sales (standard chart), sales-overview (HTML/ECharts), or production-quality (HTML/ECharts). Keep all files and drafts in the currently selected ChatKit Project. Explicit demo requests use labeled synthetic fixtures through a real registered file.table source; otherwise establish demo versus real data before writing. Never silently fill real-data gaps with sample values. Reuse existing authoring and draft tools; sample updates never overwrite existing dashboards.
+
+For enterprise BI, offer [Superstore](examples/superstore/README.md): three full dashboards over the authorized **published Data Xpert SuperstoreOrders model**. This recipe uses `data-xpert.ontology`, not the file workflow above. Keep its fictional teaching-data label. Do not read the entire orders.csv into model context; follow its administrator setup and source discovery. Missing authorization/model is a setup gap, never permission to substitute another sample. Preserve its independent backend totals for distinct orders/customers.
+
+When `dashboard_open` or `dashboard_history` returns `selection_required`, display its message and wait for the user to select a dashboard. This is a normal empty-selection state: do not retry, restore a target from conversation history, or create a replacement.
+
 ## Avoid preventable retries
 
 - New independent dashboards use an unused source-file path. Inspect the target directory when needed; do not overwrite an existing candidate or switch to editing a historical Artifact merely because its title or filename matches.
+- Continue the selected or checkpointed Artifact across turns. Explicit Workbench selection and New override the checkpoint; never infer identity from title or recency. If a target exists, new/copy creation requires the user's explicit request and `creationIntent: "new"` or `"copy"`.
 - A successful save receipt already confirms persistence. Opening or reading the saved dashboard only prepares an unchanged copy; it does not require another save. Update only for an actual requested change or an observed defect. Never save an unchanged copy merely to verify that the previous save worked.
 
 - After preview, execute every `validation.checks[].suggestedCall` before writing HTML. These suggestions use observed rows; only a successful `dashboard_test_filter` is evidence. If no value is suggested, inspect the source for a real value. A changed Binding needs fresh evidence.
@@ -28,10 +37,25 @@ Use the installed SKILL.md path shown in the skill catalog with `read_skill_file
 
 Read [data-validation.md](references/data-validation.md) when creating a dashboard or changing its data/Binding. Read [html-runtime.md](references/html-runtime.md) and its lifecycle example when authoring or changing HTML/JavaScript. Style-only edits preserve the saved Bindings and do not need to reconstruct upstream queries.
 
+## Reusable visual themes
+
+Read the [style selection guide](themes/README.md) before choosing a visual system.
+Trend Workspace is the pale-blue trend overview; Profit Atlas is the dark
+profitability desk; Customer Brief is the warm editorial customer report. They
+have different layouts and chart emphasis, not just different colors. Honor the
+user's choice and preserve an existing theme unless redesign is requested.
+Read the selected theme's guide and complete example, then author and save the
+business page yourself using its installed components and exactly one pinned theme
+library with ECharts. Do not depend on a developer, repository checkout, screenshot
+or an already-created Artifact.
+Use the complete Superstore pages as worked examples, not as a substitute for
+discovering another dataset's fields and validating its metrics. For style-only
+upgrades, follow the theme's existing-Artifact procedure and keep saved bindings.
+
 ## One file editing interface
 
 - Create a new file with `sandbox_write_file({"file_path":"dashboards/sales.html","content":"<!doctype html>..."})`.
-- Read an existing file with `sandbox_read_file({"file_path":"..."})`.
+- Read an existing file with `sandbox_read_file({"file_path":"..."})`. If a long HTML line is truncated, use `dashboard_read_html` with the opened `editId` and follow `nextOffset` until `null` to inspect the saved source; do not repeat the same truncated read or overwrite the editing file with its preview. Apply exact replacements to the existing `htmlPath`.
 - Change existing text with `sandbox_edit_file({"file_path":"...","old_string":"exact old text","new_string":"replacement"})`; use `sandbox_multi_edit_file` for multiple changes.
 - `sandbox_write_file` does not overwrite existing files. Repair the current candidate with edits. If replacing an unsaved creation candidate with a new named file, include the earlier exact path in `supersedesPaths` on `dashboard_create_html` (or `dashboard_create` when choosing standard charts instead); only a successful save abandons that candidate, and files remain in Workspace. Do not abandon editing copies from `dashboard_open`. For a long new document, append subsequent complete segments with `sandbox_append_file` before saving the dashboard.
 - Paths are relative to the current sandbox working directory. Use a real filename (`dashboards/sales.html`), never `.html`, whitespace-only names, absolute paths or guessed host paths. Copy returned paths exactly.
@@ -40,7 +64,7 @@ Read [data-validation.md](references/data-validation.md) when creating a dashboa
 ## Create a new dashboard
 
 1. Call `dashboard_list_sources` before searching raw files, reading old scripts or creating transformations. For a named governed source, inspect that source/provider contract first; file-backed sources do not automatically require a script. Discover the authorized source and business schema. Validate the metric, period, grain, units and filters through real preview results; follow the data-validation reference.
-2. For HTML mode, read the HTML runtime reference and call `dashboard_libraries` before using ECharts, Three.js or online dependencies such as Tailwind CDN. Use only its allowed HTTPS resource origins; online URLs are not entries in the packaged `libraries` array. Write a complete HTML page using SandboxFile. First declare `const live = window.xpertLiveArtifact` inside the page script; `live` is not a host global. Then register `live.subscribe(bindingId, renderDataset)`, await `live.ready()`, then call `live.query(bindingId, typedControls)`. There is no `window.subscribe` or `window.__datasets`. Shared filters must query every affected Binding, not just call `bindSelect` for the first one.
+2. For HTML mode, read the HTML runtime reference and call `dashboard_libraries` before using ECharts, Three.js or online dependencies such as Tailwind CDN. Network access is temporarily unrestricted for functional acceptance, including CDN scripts/styles/fonts, images and fetch/XHR. Browser CORS and mixed-content rules still apply. Online URLs are not entries in the packaged `libraries` array; business data must still use saved Bindings and credentials must never be embedded in HTML. Write a complete HTML page using SandboxFile. First declare `const live = window.xpertLiveArtifact` inside the page script; `live` is not a host global. Then register `live.subscribe(bindingId, renderDataset)`, await `live.ready()`, then call `live.query(bindingId, typedControls)`. There is no `window.subscribe` or `window.__datasets`. Shared filters must query every affected Binding, not just call `bindSelect` for the first one.
 3. Call `dashboard_create_html` with `title`, the relative `path`, verified `previewIds`, matching `controls` and the complete required `libraries` list. Standard charts instead use `dashboard_create`.
 4. Correct validation errors and retry the domain save. A file write, screenshot or `present_files` receipt does not save a live dashboard. Do not present the HTML as a static deliverable.
 5. Check the returned `dashboard.artifactId`, `dashboard.status: "draft"` and `dashboard.draftRevision`. The successful domain receipt opens/refreshes the Workbench preview.
@@ -49,7 +73,7 @@ Read [data-validation.md](references/data-validation.md) when creating a dashboa
 
 1. Call `dashboard_open({})` for the selected Workbench dashboard, or provide an exact Artifact ID from `dashboard_list`. Do not choose the most recent dashboard by guesswork or create a replacement Artifact.
 2. Inspect `presentation.type`. For a standard dashboard, update definition fields directly; a rename needs only `title`, `editId`, `expectedRevision` and `expectedCurrentVersionId`. No HTML file exists: omit `htmlPath` and `libraries`. For a current HTML dashboard, the result includes a new `htmlPath` editing copy of the latest saved draft, plus `editId`, `expectedRevision` and `expectedCurrentVersionId`. Read this copy with SandboxFile before editing. Each open prepares a separate copy, preserving any uncommitted earlier files.
-3. For HTML pages, apply requested changes with SandboxFile edits. Preserve data semantics, controls, query/subscription lifecycle and library locks unless the request changes them.
+3. For HTML pages, apply requested changes with SandboxFile edits. Preserve data semantics, controls, query/subscription lifecycle, existing element IDs and library locks unless the request changes them. Assign stable IDs to new KPI/chart/table/filter components. Standard arrays and preview Bindings upsert by stable ID: omitted components remain. Use `removals` with exact binding/control/view/HTML element IDs only for user-requested deletions. HTML ID preservation checks deletion, not arbitrary semantic equivalence.
 4. Automatically call `dashboard_update({"editId":"<returned ID>","expectedRevision":<returned revision>,"expectedCurrentVersionId":<returned UUID or null>,"title":"<new title if requested>"})` with the changed definition fields. When saving edited HTML, also supply the exact `htmlPath` of the editing file. Omit unchanged fields. Updating the visible heading does not rename the saved dashboard; pass `title` as well when renaming.
 5. Check the saved draft receipt; for HTML file updates also check its `sourceFile` path/hash. For another batch, reopen the latest draft and use its new revisions. If the save fails, correct the definition or editing file and retry; do not claim success. If a revision conflict occurs, keep the edited file, open/read the latest state and reconcile before saving.
 6. Historical `versionId` reads do not prepare an editable copy. Use `dashboard_read_html` to inspect historical source, then open the current draft to apply an intentional change.

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."
+  ]
+}