@xpert-ai/plugin-live-dashboard 0.4.1 → 0.6.0

package/docs/large-dashboards-acceptance.mdx

@@ -0,0 +1,74 @@
+---
+title: 大型看板验收记录
+description: 2026-11-05 容量边界、调度、后台保存、真实 BW 数据与 Workbench 浏览器验证。
+---
+
+## 环境与结果
+
+本次升级已实现，并在本地 Xpert Pro / Data Xpert 中验证。原采购、库存、销售演示定义未修改；容量验收使用既有隔离项目中的新草稿，不发布或新增数据权限。
+
+- 插件源基线：`xpert-plugins` develop `4fd9fea0`，插件包版本仍为 `0.4.1`，新增 minor changeset。
+- 平台源基线：`xpert-pro` develop `ed7d53b03`，配套 Artifact Document SDK 修改及 minor changeset。
+- Data Xpert：develop `670163c`；ChatKit：develop `4e4907e`。
+- 相关仓库已检查工作区、快进拉取并冻结安装依赖；API 3000、API 3001、Web 5174、ChatKit 5173 已重启并完成健康检查。
+- 插件使用正常登录及 `plugin:deploy:local` 部署，重启平台后执行真实 View action，证明不是仅构建或 staged 状态。
+
+## 自动化验证
+
+| 层次 | 实际结果 |
+| --- | --- |
+| Live Dashboard 最终构建与测试 | 259 项通过，0 失败 |
+| SDK 完整回归 | 70 suites / 453 项通过 |
+| SDK 最后一次宿主修正后定向回归 | 6 suites / 37 项通过 |
+| 产物一致性 | `verify:dist` 通过，包含远程组件、Action 和前端库 |
+| 插件注册 | 元数据检查、dist-first 生命周期加载及关闭通过 |
+| Data Xpert 依赖与 Analysis App | contracts 编译通过；单文档构建 2,080,476 字节，低于保留的 2 MiB 上限 |
+
+覆盖 8/9/16/32/64 的 schema、Sources 关联和档案往返；65 拒绝；降低策略后的历史维护；相同请求复用、4 并发、分钟限额、慢请求、超时、快速筛选、旧结果隔离、部分失败、卸载及结果内存限制。HTML 快照预检使用受控浏览器桩覆盖 4/8/9/16/32/64 的控件与刷新回放；这不是 64 个真实数据库来源的浏览器性能实测。
+
+后台任务覆盖幂等、跨作用域拒绝、权限撤销、观察者取消、入队中断恢复、CAS 成功后的状态恢复，以及批量预览凭证与原重试规则。
+
+前一轮 Nx 构建/测试通过。最终 UI 观察者清理及重复刷新状态修正后，工作区 Nx 项目图被其他插件中三个无名称模板 package 阻挡，改为执行同一插件的 `pnpm -F @xpert-ai/plugin-live-dashboard test`（含完整 build）。没有通过忽略测试或修改其他模板绕过验证。
+
+## 真实后台与数据验收
+
+在已有 `Sources 导入验收｜2026-11-05` 项目创建 `容量验收 · 9 Sources · 公网库存（查询复用场景）`。这九个 Binding 复用已授权的公网 BW 库存查询，专门检验来源容量与调度，不代表九个独立业务指标。
+
+- requestId：`5f37c13b-8ade-4230-9f8d-877ac1352d4c`。
+- 新 Artifact：`a45d0fbf-8818-4897-bb08-285bae9fcea2`，草稿修订 `1`，9 个来源。
+- 观察到 queued → queries 0/9 → 2/9 → 6/9 → saved；提交、验证、读取和后续查询共约 13.7 秒。
+- 重复提交返回同一个 requestId，没有第二次草稿修订。
+- 保存后单来源真实查询返回 100 行，`truncated=false`、`totalAccuracy=exact`。
+- 默认策略下提交 33 个 Binding 返回 HTTP 400 / `DASHBOARD_BINDING_CAPACITY`，未启动新保存任务。
+
+## Workbench 浏览器验收
+
+在本地 Bosi 工作台打开九来源草稿，确认九张表均有真实数据。Sources 的完成时间显示 4、4、1 的加载批次。
+
+- 搜索“来源 9”后只保留对应来源；自定义 Select 选择“已更新”状态正常。
+- 来源详情显示对应 Binding、Dataset、Provider、请求配置、排队时间和执行时间。
+- 单独刷新来源 9：经历查询中 → 已更新，运行约 2.2 秒，其余来源不随之重查。
+- 使用原始库存查询返回的真实工厂成员 `[2CIPLANT].[0018]` 应用筛选，九个相关来源全部更新；来源 1 的结果从 100 行变为 2 行，完整性仍为 exact / 未截断，当前参数和审计引用可在结果详情中核对。
+- 私有验收截图及机器可读记录保存在本地 `.xpert-local-environment/dashboard-scale-20261105/`，不将业务数据或登录信息加入插件仓库。
+
+## 验证边界
+
+64 是协议上限；本次真实数据宿主验收到 9 个 Binding。32/64 的边界和调度行为由自动化测试覆盖，未对 64 个独立外部数据库或多用户同时访问作性能承诺。分钟额度、源系统速度、返回体大小都会影响首屏时间。自动刷新隐藏页行为、故障和队列恢复的异常路径以自动化测试证据为主。
+
+本次没有运行一个新的完整 LLM 对话来覆盖所有批量工具；Agent 工具路径由集成测试验证，真实保存通过同一领域服务和 Managed Queue 完成。以上首次验收时，配套 SDK 尚待发布，插件使用临时 pnpm patch；当时的本地成功不等同于已完成 npm 发布。后续正式 SDK 依赖迁移见下文。
+
+联调额外修复 Data Xpert 的两个启动阻塞：contracts 依赖升级至提供现有源码所需类型的 3.32.0；Analysis App 使用显式 Terser 压缩。没有扩大文件传输上限、关闭鉴权或复用过期产物。
+
+## 正式 SDK 依赖迁移（2026-11-05）
+
+插件仓库快进更新至 develop `6fc3fe99`，保留原暂存改动。确认 npm 已发布 `@xpert-ai/plugin-sdk@3.33.0` 与 `@xpert-ai/contracts@3.33.0` 后，将 `xpertai` 工作区和 Live Dashboard 的开发依赖升级至 3.33.0，本插件 peer 依赖同步要求 `^3.33.0`。移除 SDK 3.31.0 临时 patch、工作区配置及锁文件中的 patch 引用；独立的 Changesets CLI patch 保留。
+
+| 检查 | 实际结果 |
+| --- | --- |
+| 正式包解析 | 工作区与插件均解析到 SDK/contracts 3.33.0；正式包提供调度器、宿主与 `queryMany` 运行时 |
+| 依赖安装 | 更新锁文件后 `pnpm install --frozen-lockfile` 通过 |
+| Nx 构建与回归 | 跳过缓存运行 Live Dashboard `test`，完整构建及 259 项测试通过，0 失败 |
+| 产物一致性 | Nx `verify:dist` 通过，viewer、Action 与前端库已重建并校验 |
+| 插件注册 | 元数据检查通过，dist-first 生命周期加载及关闭通过（Harness 基础设施 mock） |
+
+本次是正式包依赖迁移与构建回归，未重新部署插件或重跑真实数据、浏览器及 LLM 验收。以上真实宿主记录仍对应首次部署，不能作为 3.33.0 已部署的证明。

package/docs/large-dashboards.mdx

@@ -0,0 +1,80 @@
+---
+title: 大型实时看板
+description: 32 个默认来源、64 个协议容量、有界查询调度、Sources 管理与后台保存验证。
+---
+
+## 容量与安装配置
+
+Live Dashboard 不再把一个看板限制为 8 个 Binding。Binding 表示一次可复用的数据查询；图表、指标和表格可以共享同一 Binding，独立的筛选候选查询也占用一个名额。
+
+| 边界 | 当前值 |
+| --- | --- |
+| 默认新建、导入、扩容 | 32 个 Binding |
+| 协议和存储硬上限 | 64 个 Binding |
+| 安装配置 `maxBindings` | 1–64 的整数，默认 32 |
+| 图表 / 表格 / 控件 | 分别最多 20 / 20 / 24 |
+| HTML 组件来源关联 | 最多 64 个 Binding；组件总数最多 160 |
+| Agent 保存的 `previewIds` | 最多 64 个 |
+
+插件安装配置示例：
+
+```json
+{ "maxBindings": 32 }
+```
+
+服务端统一检查新建、导入、View 保存和 Agent 保存。降低安装策略后，历史看板仍可打开；不增加 Binding 数量的编辑仍可保存。新建副本、导入和新增来源必须满足当前策略，超过 64 永远拒绝。不会自动拆分看板、调整业务口径或扩大数据权限。
+
+## 查询与刷新
+
+标准页面和 HTML 页面共用 SDK 调度器：默认并发 4，调度器并发硬上限 8；每个文档会话每分钟最多启动 60 次真实查询。此额度不是整个租户共享的总配额。筛选请求优先于初次加载，初次加载优先于刷新。
+
+- 相同 Binding、相同参数的进行中请求复用同一个任务。
+- 参数变化取代旧排队请求，旧运行请求返回后不覆盖新结果。只有底层真实结束才释放并发槽；丢弃结果不代表数据库查询已取消。
+- 排队最多 180 秒，开始执行后最多 45 秒；最多保留 64 个排队任务。
+- 标准页面逐来源呈现结果，筛选只查询参数变化的来源，先移除所有受影响的旧结果；失败来源独立显示并可重试。
+- 页面切换或卸载清除会话及等待队列，不保留跨用户、项目或版本缓存。
+- 自动刷新至少间隔 `max(用户所选周期, Binding 数 × 2 秒)`，页面隐藏、编辑或上一轮尚未完成时跳过；自动和手动刷新共用调度额度。
+
+64 个来源不意味着 64 个并发请求，也不是首屏延迟承诺。全新会话的第 61 个实际请求需要等待分钟窗口；连续筛选和刷新也会消耗额度。大结果集应在数据源聚合，标准页面结果总量仍受 3 MB 限制。
+
+### HTML 的一致更新
+
+旧页面的 `query()` 继续兼容。需要多个来源一起更新指标时使用 `window.dashboard.queryMany(bindingIds, controls)`，等待一组来源结束后再统一向订阅者投递成功结果。返回值包含 `datasets` 和独立的 `failures`，页面应展示失败状态。旧轮次被取代时不再提交其结果。页面自行调用多个独立 `query()` 不会自动获得整组原子更新语义。
+
+宿主全页刷新使用分组调度，单来源刷新保持独立。HTML 不能通过消息提高并发或分钟额度。Sandbox HTML 验证只重放已经取得的不可变快照，每个 Binding 最多重放 16 次；其单独预算不增加真实源查询额度。HTML 安全检查及验证总时限继续保留。
+
+## Sources 管理
+
+右侧 Sources 面板支持按名称、Binding ID、说明搜索，按 Provider 和执行状态过滤。来源详情显示排队/执行时间、当前配置、参数及有界结果预览；可单独刷新失败或需要检查的来源。页面查询繁忙时暂时禁用单来源刷新，避免与整组更新交叉。
+
+Inspect 仍按组件声明定位来源；多个组件共享的查询只占一个来源。详情是只读配置，不能在浏览器中绕过服务端更换源、查询文本或权限。
+
+单个预览最多 50 行 / 64 KB，全部来源预览数据最多约 2 MB；超过预算时释放较早预览，并显示明确提示。释放预览不会改变图表结果或已保存定义。
+
+## Agent 批量验证
+
+增加 `dashboard_preview_batch` 和 `dashboard_test_filter_batch`，每次最多 8 项，最多 4 项并行；逐项返回成功凭证或错误，部分失败不会抹去其他成功项。批量预览每项最多展示 5 行 / 8 KB，保留完整性信息。
+
+单项预览工具继续兼容。相同失败输入最多执行两次、连续六次失败停止尝试、参数真实验证及精确预览凭证要求均保留。凭证只属于当前运行、当前 actor；保存时重新检查权限。普通模型工具轮次仍为 24；后台等待另有最多 40 次观察限制。
+
+## 后台保存与恢复
+
+超过 8 个 Binding 的创建、更新和导入通过平台 Managed Queue 执行；8 个及以下保留同步路径。现有创建/更新工具就是提交入口，无需另一个手工提交步骤。
+
+1. 可信服务端冻结定义和依赖文件，记录输入哈希、actor、租户、组织、宿主和项目。
+2. 同一幂等键和相同内容复用任务；相同键但不同内容拒绝。
+3. 队列恢复当前执行身份，依次执行权限检查、真实查询、筛选验证、HTML 验证和最终修订 CAS。
+4. View 展示阶段和进度；Agent 使用 `dashboard_wait_request` / `dashboard_get_request` 获得结果。
+5. 只有真实 CAS 成功后才返回保存凭证和成功卡片；不会自动发布正式版本。
+
+等待工具单次最多 20 秒、内部每 2 秒观察进度，不在等待调用中执行领域工作。关闭页面停止继续观察，不取消已提交的保存任务；可凭 requestId 在原作用域继续查询。跨用户或项目的状态读取被拒绝。
+
+每个任务验证时限 10 分钟，任务记录保留约 24 小时，队列验证并发 2。进程在入队边界中断时使用同一 jobId 恢复；若 CAS 已成功而状态写入失败，按当前草稿的 requestId 和修订号恢复凭证，不重复创建修订。其持久性依赖平台 Redis/Managed Queue 和 Workspace Files 的部署；记录过期后应先查看当前草稿再决定重试。
+
+## 构建与发布配套
+
+Artifact Document 调度、宿主和运行时已随 `@xpert-ai/plugin-sdk@3.33.0` 正式发布，配套使用 `@xpert-ai/contracts@3.33.0`。工作区与本插件的开发依赖固定为 3.33.0，本插件的 peer 依赖要求 `^3.33.0`，直接使用正式包中的调度器与分组查询接口。原 SDK 3.31.0 临时 pnpm patch 及其锁文件引用已移除。
+
+使用工作区声明的 Corepack/pnpm 和已提交锁文件冻结安装依赖；升级 SDK 后重新构建 viewer 与 HTML preflight 产物，并运行测试、`verify:dist` 及插件生命周期验证。部署与真实数据宿主验收单独记录，依赖升级不代表正在运行的插件已更新。插件服务端仍使用平台已有 Analytics、Artifacts、Workspace Files 与 Managed Queue 能力。
+
+原升级计划在实现和验收后转为本功能说明。实际测试与尚未覆盖的性能边界见[验收记录](./large-dashboards-acceptance)。

package/docs/sources-inspect-portability-acceptance.mdx

@@ -0,0 +1,67 @@
+---
+title: Sources、Inspect 与迁移验收记录
+description: 2026-11-05 的自动化、真实部署、查询及浏览器导入闭环验证。
+---
+
+## 当前结论
+
+2026-11-05：实现已部署到本地 Xpert / Data Xpert 联调环境。自动化、真实数据查询、服务端档案往返及浏览器导入闭环通过；浏览器验证了来源侧栏、组件 Inspect、文件上传、资源与实体映射、提交并打开独立草稿。
+
+实施计划已转换为[功能文档](./sources-inspect-portability)。本记录不替代历史验收，也不声明完成新的 Agent 生成、SSO、Sandbox 或跨服务器部署验收。
+
+## 自动化与产物
+
+| 范围 | 结果 |
+| --- | --- |
+| Live Dashboard Nx 构建及测试 | 227 项通过，0 失败 |
+| Data Xpert Analytics Provider Nx 构建及测试 | 21 项通过，0 失败 |
+| 最终只读投影断言复验 | 项目成员及共享展示相关 18 项通过；属于上述测试的重复执行，不另计总数 |
+| 产物一致性 | `verify:dist` 通过，包含远程组件、Action 与固定图库依赖 |
+| 插件元数据 | 两个插件检查均通过 |
+| Lifecycle harness | 两个插件均成功加载并关闭；此项使用 harness mocks，不代表真实业务查询 |
+| 差异格式 | `git diff --check` 通过 |
+
+覆盖来源引用和静态 DOM 锚点、只读 payload 投影、过期响应丢弃、失败时保留上次结果、Inspect Window/nonce/组件校验、动态标准图表、键盘恢复，以及档案损坏/超限/未知条目/版本/依赖字节校验。导入测试覆盖当前权限复验、失败不创建草稿、新身份、会话隔离及重复提交幂等。
+
+## 已部署环境与真实数据
+
+联调前已检查相关仓库分支与工作区、执行快进拉取及冻结锁文件安装，保留原有未提交修改。插件通过平台正常认证部署并重启 API，核验实际实例与健康检查。
+
+| 真实看板 | Sources | 声明组件 | 本次保存验证 |
+| --- | ---: | ---: | --- |
+| 采购执行 | 2 | 21 | 所有绑定真实查询与 HTML 保存验证通过 |
+| 销售经营 | 3 | 19 | 所有绑定真实查询与 HTML 保存验证通过 |
+| 库存数量与价值 | 2 | 16 | 所有绑定真实查询与 HTML 保存验证通过 |
+
+三个看板补充显式来源/组件关联。自定义筛选替换标签时同步保留容器 ID，避免静态校验通过但运行时 Inspect 无法定位。没有新增资源授权或自动发布。
+
+库存档案通过真实 View 文件协议导出，大小为 376,981 字节；在独立验收项目中重新导入并执行真实查询、控件与 HTML 校验。验证新 dashboard 身份、完整 Manifest 除身份外相同、依赖字节保留，以及同会话重复提交返回同一草稿。该证据来自正常认证 API，不冒充浏览器下载事件或浏览器提交验收。
+
+Data Xpert 迁移发现接口已验证资源 → 实体 → 显式 payloadPatch，重映射保留原参数和路径。此验证在同环境的另一项目完成，不等同于独立服务器迁移验收。
+
+## 浏览器已验证项
+
+| 场景 | 证据及边界 |
+| --- | --- |
+| 真实 Bosi 库存来源侧栏 | 两个绑定与保存定义一致；来源详情、查询配置、折叠组件列表可见 |
+| 真实 KPI Inspect | 点击指标打开对应来源详情 |
+| 真实筛选多来源 Inspect | 定位保留的筛选容器，显示两个来源；不改变原筛选值或触发业务查询 |
+| 面板开关 | iframe 保持，已有查询时间不变 |
+| 标准图表/表格 Inspect | Chrome 测试宿主验证，使用模拟结果；依据真实渲染 DOM 的 `chart:id` / `table:id` 定位 |
+| 标准筛选与刷新 | 模拟区域筛选改变图表/表格及详情参数、结果行，刷新更新时间 |
+| 键盘和窄屏 | Esc 退出 Inspect；600px 视图使用抽屉；测试后恢复视口 |
+| 浏览器导出入口 | 显示档案已准备和下载链接；完整文件获取另由上述 API 验证 |
+| 浏览器文件导入 | 原生文件选择成功，ZIP 解析、标题、两个请求及资源映射入口显示正常 |
+| 浏览器映射与提交 | 选择库存模型及其目标实体，验证并导入为新的 r1 草稿；真实库存指标返回，两个 Sources、16 个组件关联和来源详情保留 |
+
+## 验收边界
+
+浏览器首次映射遇到会话 HTTP 401，正常重新登录后由用户处理 Chrome 密码安全提示，随后重新上传、映射及提交成功。未绕过认证或浏览器安全提示。
+
+标准看板交互使用明确标识的模拟测试宿主；真实业务查询与浏览器导入使用库存语义模型。真实迁移发生在同一部署的不同项目，未据此宣称另一台服务器上的部署验收。浏览器已确认导出生成下载链接，完整文件字节和完整性由正常认证 API 验证；未将浏览器自动化的下载事件记为通过。
+
+## 提交前同步上游后的回归
+
+2026-11-05 提交前同步 `develop` 的 Analytics 公共诊断修复，保留其诊断处理和本功能的导入发现。重新执行冻结依赖安装与两个插件的 Nx 测试：Live Dashboard 227 项通过；Data Xpert Provider 在构建阶段受配套 Contracts/SDK 依赖阻挡，当前锁定版本没有 `AnalyticsProviderError`、`parseAnalyticsDiagnostic` 和 `AnalyticsDiagnostic` 导出。
+
+该前置条件已由上游 `analytics-public-diagnostics` changeset 与 Provider README 明确记录：先发布配套 Contracts/SDK，再更新依赖和锁文件。上述 Provider 21 项及真实部署记录属于同步该修复之前的已验证版本，不能当作合入上游后 Provider 再次通过的证据。本次代码提交不代表完成依赖升级或插件发布。

package/docs/sources-inspect-portability.mdx

@@ -0,0 +1,115 @@
+---
+title: Sources、Inspect 与看板迁移
+description: 查看真实查询来源，从页面组件追溯配置，并通过完整档案迁移看板。
+---
+
+Live Dashboard 支持查询来源侧栏、组件 Inspect、ZIP 档案导出与跨项目导入。本页由 2026-11-04 的实施计划在验收后转换，实际验证范围见[验收记录](./sources-inspect-portability-acceptance)。
+
+## 查看来源
+
+有定义编辑权限时，工具栏显示“数据来源”和来源数量。每个已保存 `binding` 对应一个来源；同一物理数据源上的多条请求分别列出，筛选候选项请求也包含在内。
+
+点击来源进入详情，返回按钮回到列表。桌面端使用约 380px 的右侧栏；视图宽度小于 900px 时使用抽屉。开关面板保留当前 iframe 和筛选状态，不额外发起查询。界面使用共享 shadcn 组件与宿主主题，提供英文、简体中文、繁体中文文本。
+
+| 分组 | 内容 |
+| --- | --- |
+| 概览 | 名称、说明、bindingId、datasetId、执行状态 |
+| 使用此来源的组件 | 可展开的指标、图表、表格和筛选组件列表 |
+| 查询配置 | 资源引用、providerId、operation、contractVersion、完整原生 payload；可复制 |
+| 筛选与参数 | controlId/name 映射、类型、必填、保存的默认值、最近提交值、允许值 |
+| 输出字段 | 字段标识、来源字段、标签、类型、单位、可空性、粒度 |
+| 最近查询结果 | 请求时间、完整性、获取时间、执行标识、对应筛选值、最多 50 行预览 |
+
+`null`、空字符串、零分别展示。重新查询失败时保留上次成功预览，并标明它是旧结果。每个 binding 按 requestId 接受最新响应，晚到的旧响应不会覆盖新请求。切换看板或版本会清理运行状态；结果预览只保存在页面内存中，不写入定义或导出档案。
+
+这里展示 Provider 实际接收的配置。语义查询不会被虚构成 SQL；没有显式转换定义时，不生成 Transform 分组。首版来源配置只读，修改仍通过原有定义编辑或 Agent 更新流程。
+
+## 从页面检查组件
+
+点击“检查组件来源”开启 Inspect，悬停或键盘聚焦会高亮已关联组件：
+
+- 单来源组件直接打开详情。
+- 多来源组件先列出使用的请求。
+- 未关联区域显示未声明来源提示，不猜测数据来源。
+- Inspect 中的点击不触发原组件的筛选或导航；按 Esc 或再次点击工具栏按钮退出。
+
+HTML 模式使用显式组件声明，Canvas 图表定位到其容器。标准模式自动按 chart/table → datasetId → bindingId 建立关联，适配渲染器实际的 `chart:id` / `table:id` DOM 标记。
+
+### HTML 作者与 Agent 的声明
+
+Manifest 可选字段：
+
+```json
+{
+  "sourceMetadata": [
+    { "bindingId": "sales", "title": "销售汇总", "description": "按当前区域汇总销售额" }
+  ],
+  "components": [
+    {
+      "id": "sales-total",
+      "elementId": "sales-total-card",
+      "title": "销售额",
+      "kind": "metric",
+      "sources": [{ "bindingId": "sales", "fieldIds": ["amount"] }]
+    }
+  ]
+}
+```
+
+查询仅保存在 `bindings`，组件声明只保存引用。`kind` 可为 `metric`、`chart`、`table`、`filter`、`text`。校验重复 ID、未知 binding/field，以及 HTML 中缺失或重复的静态容器 ID。最多 8 条来源元数据、160 个组件。ID 以字母开头，允许字母、数字、下划线、点和连字符，最长 80 字符。
+
+容器必须在运行时保持稳定。自定义筛选若用新 DOM 替换原标签，应把原容器 ID 转移到新容器；不能只把 ID 留在被删除的标签或隐藏的原生 select 上。静态校验不能替代实际渲染验收。
+
+`dashboard_create` / `dashboard_create_html` 接受这些可选声明；`dashboard_update` 以 bindingId/component id 合并，省略时保留，删除组件使用 `removals.componentIds`。删除绑定会移除对应来源元数据；剩余组件不能引用已删除的绑定。作者说明见插件技能的 `references/source-inspection.md`。
+
+## 导出与导入
+
+在“更多操作”中选择“导出看板”。导出固定当前已保存草稿 revision 或发布版本；草稿在导出期间已变化时会报冲突，需要重新打开最新版。下载链接在准备完成后显示。
+
+```text
+看板.xpert-dashboard.zip
+  package.json       档案格式版本、条目大小、SHA-256
+  dashboard.json     权威文档包：Manifest、HTML、依赖锁和依赖字节
+  dashboard.html     HTML 模式的便于查看副本
+  requirements.json  Provider、资源引用、外部资源说明
+```
+
+标准模式不合成 HTML。HTML 的固定图库依赖随包保留，导入不要求目标环境安装同版本图库。档案不额外带入查询结果、连接凭据、访问策略或发布权限；已有 HTML/原生 payload 是作者定义的一部分。
+
+`dashboard.html` 不是脱离平台运行的离线应用。实时查询仍需要授权宿主；在线 CDN、图片、动态资源不自动下载。`requirements.json` 列出静态 src/href 外部引用，并提示 HTML 可能包含动态资源。
+
+导入流程：
+
+1. 先选择目标项目，在“更多操作”中选择“导入看板文件”。
+2. 上传 ZIP、原始 Manifest JSON 或已有文档包 JSON。
+3. 检查每个数据请求的目标来源；同环境有效引用可以直接保留。
+4. 跨环境时使用“映射目标环境中的资源”。没有迁移扩展的 Provider 可以通过“高级请求配置”填写其原生 payload。
+5. 点击“验证并导入草稿”。服务器按当前账号重新查询并执行已有控件与 HTML 页面校验；全部通过后才创建独立草稿。
+
+内部 binding/control/component ID 保留，新的 dashboard 身份由服务器生成。原看板不被覆盖，不自动发布，也不复制授权。查询、字段或目标资源不匹配时保留准备界面，可修正后重试。同一导入会话成功后再次提交相同配置返回同一结果。
+
+### 格式与会话限制
+
+- 上传档案最大 12,000,000 字节；权威文档包最大 9,000,000 字节。
+- 解压同时限制条目与实际展开总量，不向文件系统解压路径。
+- 只允许约定条目；重复路径、未知条目、不支持版本、哈希/大小不符、HTML 副本或 requirements 不一致、缺失/损坏依赖均拒绝。
+- 导入准备会话保存在进程内，30 分钟过期，最多 16 个；绑定租户、组织、用户、宿主及项目。服务重启或项目切换后需重新选择文件。
+
+## Provider 迁移边界
+
+看板层不判断 SQL 或 MDX，也不按名称猜测、替换字符串。迁移通过现有 Analytics discovery 的显式扩展完成：
+
+- `queryContract.payloadSchema["x-xpert-import"]` 声明 `{ version: 1, request: {...} }`。
+- 初次迁移请求在该声明上附加原始 `payload`；后续使用返回的 `inspectRequest` / `nextRequest`。
+- 可选目标的 metadata 为 `{ schema: "xpert.analytics.import-target", version: 1, payloadPatch: {...} }`。
+- `payloadPatch` 对原 payload 做顶层字段替换，不是递归合并或任意字符串替换。
+
+Data Xpert Provider 实现资源和实体浏览，返回明确的 `resourceId`、`target` 替换值；保留原生 Action、参数和参数路径。是否可查询、Action/字段是否兼容仍以保存阶段的真实验证为准。
+
+## 权限与隔离
+
+完整查询配置、Inspect、导入、导出沿用定义编辑权限。服务器检查权限；只读视图与共享展示中的 binding payload 被投影为空对象，不能仅依靠隐藏按钮保护配置。实时查询仍按当前 actor 执行，不扩大资源权限。
+
+Inspect 使用插件内的只读元数据通道，每代 iframe 使用随机 nonce，并校验消息 Window 身份。宿主只接受声明的 componentId，不接受页面传来的查询配置。查询仍走原有隔离文档 MessagePort；本功能没有新增 SDK API 或放宽页面查询权限。
+
+实现按来源声明、运行状态、Inspect 协议、来源面板、档案解析、导入服务和 UI 分文件维护。历史验收文档保留，当前验证证据单独记录。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-live-dashboard",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Versioned live dashboards using platform analytics and Data Analytics renderer",
   "main": "./index.cjs",
   "types": "./dist/index.d.ts",
@@ -33,12 +33,12 @@
   },
   "peerDependencies": {
     "@langchain/core": ">=0.3.0",
+    "@langchain/langgraph": "^0.4.7",
     "@nestjs/common": "^11.1.6",
     "@nestjs/core": "^11.1.6",
-    "@xpert-ai/contracts": "^3.30.0",
-    "@xpert-ai/plugin-sdk": "^3.30.0",
-    "zod": "3.25.67",
-    "@langchain/langgraph": "^0.4.7"
+    "@xpert-ai/contracts": "^3.33.0",
+    "@xpert-ai/plugin-sdk": "^3.33.0",
+    "zod": "3.25.67"
   },
   "devDependencies": {
     "@langchain/core": "0.3.72",
@@ -50,8 +50,8 @@
     "@types/react": "^18.3.24",
     "@types/react-dom": "^18.3.7",
     "@xpert-ai/community-data-analytics": "0.1.35",
-    "@xpert-ai/contracts": "^3.30.0",
-    "@xpert-ai/plugin-sdk": "^3.30.0",
+    "@xpert-ai/contracts": "3.33.0",
+    "@xpert-ai/plugin-sdk": "3.33.0",
     "echarts": "5.6.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
@@ -72,6 +72,7 @@
     "access": "public"
   },
   "dependencies": {
+    "fflate": "0.8.3",
     "parse5": "7.2.1"
   },
   "scripts": {

package/skills/live-dashboard/SKILL.md

@@ -65,7 +65,7 @@ upgrades, follow the theme's existing-Artifact procedure and keep saved bindings
 
 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. 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`.
+3. Declare readable `sourceMetadata` for each Binding and `components` for each HTML KPI/chart/table/filter. Read [source inspection](references/source-inspection.md); preserve the mapping when updating HTML. 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.
 
@@ -74,9 +74,10 @@ upgrades, follow the theme's existing-Artifact procedure and keep saved bindings
 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, 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.
+4. To add filters or change a saved query, copy the complete `dashboard_open.bindings[]` entry, preserve its `id` and existing `parameters[].controlId`, then preview the edited Binding using `dashboard_preview_binding({"bindingJson":"<complete canonical Binding JSON>"})`. Binding `id` and `output.datasetId` are separate identities. The simplified `dashboard_preview` derives the Binding ID from `datasetId`; using a new probe dataset name can add a Binding instead of replacing the intended one. HTML `query`/`subscribe` calls use Binding IDs. Preview changes to query parameters/defaults again and perform any filter tests required by the preview receipt.
+5. 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. Include **all intended changed/new Binding `previewIds` from this run**, matching `controls`, and the exact edited `htmlPath` together. Unchanged bindings remain saved. Updating the visible heading does not rename the saved dashboard; pass `title` as well when renaming.
+6. 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. On `DASHBOARD_HTML_PREFLIGHT_FAILED`, inspect the reported expected/requested Binding IDs and page errors. Observed requests are not a static inventory of every reference; a page error can prevent a query from reaching the host. Repair the file or binding previews, retaining every intended `previewId`, control, title and `htmlPath` in the retry. Omitting previews does not adopt new queries from HTML. Never remove saved bindings merely to bypass validation, and do not claim success without a save receipt. On a revision conflict, keep the edited file, open/read the latest state and reconcile before saving.
+7. 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.
 
 ## Save, preview and human publication
 

package/skills/live-dashboard/references/source-inspection.md

@@ -0,0 +1,17 @@
+# Source inspection
+
+For each Binding, author `sourceMetadata: [{bindingId,title,description?}]`. Use business names, not invented SQL summaries. Include option-catalog/filter queries too.
+
+HTML pages declare `components: [{id,elementId,title,kind,sources:[{bindingId,fieldIds?}]}]`. `kind` is metric, chart, table, filter or text. The HTML must contain exactly one element with each `elementId`; put IDs on static containers (including canvas parents) rather than dynamically generated children. IDs start with a letter and use letters, digits, dot, underscore or hyphen, at most 80 characters. A multi-query metric lists all of its Binding dependencies. A static element can declare an empty sources array. Field IDs refer to Binding output field IDs, not provider column guesses.
+
+Example (as JSON text in Agent tools):
+
+```json
+[{"id":"revenue","elementId":"revenue-card","title":"Revenue","kind":"metric","sources":[{"bindingId":"sales","fieldIds":["amount"]}]}]
+```
+
+The declared Binding owns the only query payload. Do not embed payloads, credentials or query results in component metadata. Standard chart/table definitions already associate their dataset with its Binding and need no extra component mapping.
+
+`dashboard_update` merges source metadata by bindingId and components by id. Omitted declarations stay unchanged. Use `removals.componentIds` for deliberate removal; changing a DOM ID also requires updating elementId. Removing a Binding requires updating/removing any component references to it. Sources and Inspect read the exact saved revision. Inspect is read-only; its click does not trigger a business filter.
+
+Export/import is a Workbench file operation. An imported dashboard is a new draft, retaining internal Binding/control/component IDs and verified dependency bytes. It must pass current-user data and HTML validation; importing does not grant access or publish a version.