@xpert-ai/plugin-live-dashboard 0.5.0 → 0.6.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-live-dashboard",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Versioned live dashboards using platform analytics and Data Analytics renderer",
   "main": "./index.cjs",
   "types": "./dist/index.d.ts",
@@ -36,8 +36,8 @@
     "@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",
+    "@xpert-ai/contracts": "^3.33.0",
+    "@xpert-ai/plugin-sdk": "^3.33.0",
     "zod": "3.25.67"
   },
   "devDependencies": {
@@ -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.31.0",
-    "@xpert-ai/plugin-sdk": "3.31.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",