@xpert-ai/plugin-live-dashboard 0.0.0-stage → 0.1.0

package/docs/file-datasets-acceptance.mdx

@@ -0,0 +1,65 @@
+---
+title: 文件数据看板闭环验收
+description: 2026-10-18 的 CSV、JSON、XLSX 真实模型生成、持续编辑和查询边界验收范围。
+---
+
+## 范围与运行方式
+
+2026-10-18，在本地 xpert-pro 中使用现有真实模型，从 Chat 输入业务请求，经平台 SandboxFile 编写 HTML、看板工具预检并保存工作草稿。文件插件继续通过 WorkspaceFiles 和 Dataset/Binding 查询 CSV、JSON、XLSX；平台没有新增文件格式判断或看板专用查询分支。
+
+本次更新看板插件后重启 API，并核对 Assistant 工作区已安装技能与源码一致。没有提供预制页面、脚本或预期金额给 Agent，也没有手工修补生成 HTML。本次不是新一轮 data-xpert SSO、人工发布或正式发布验证。账号、资源身份、原始回执和截图仅保存在本地。
+
+## 一句话生成与页面闭环
+
+独立业务基准为 7 条输入、6 个月份/区域分组：总额 5,700 元、华东 3,500 元、华西 2,200 元。页面采用已打包的 ECharts 5.6.0。
+
+| 场景 | 实际结果 |
+| --- | --- |
+| CSV 单来源 | 一句话生成并保存蓝色 HTML/ECharts 看板；总额、月度区域趋势和明细一致。 |
+| JSON 单来源 | 一句话生成并保存深色金色页面，保留真实区域筛选及刷新。 |
+| XLSX 单来源 | 一句话生成并保存浅色绿色页面，聚合趋势与原始明细分别查询，合计一致。 |
+| 三来源新会话 | 补强说明后，新开会话一次业务请求生成三个独立面板，共同区域筛选查询全部三个 Binding，不重复合并三个来源的金额。 |
+| 筛选与系列 | 全部、华东、华西均逐一核对 KPI、明细和 ECharts 实际系列；被排除区域不残留零值系列。 |
+| 源文件更新 | 分别增加 CSV/JSON/XLSX 首条金额 100/200/300 元；保留华东筛选刷新后分别显示 3,600/3,700/3,800 元。工具栏和页面内刷新均实际发起查询。 |
+| 重开恢复 | 资源卡片在 ChatKit Workbench 打开；关闭重开和刷新浏览器后恢复保存的草稿、标题和默认筛选。刷新不替换已挂载 HTML 文档。 |
+
+源文件在测试结束后恢复。以上数值来自独立测试数据，不是根据页面结果反推期望值。
+
+## 跨轮编辑
+
+对同一个三来源看板连续发出两次修改请求：第一轮改成深蓝金色并修正筛选后的系列，第二轮修改标题并添加金额及不重复合计说明。Agent 通过 `dashboard_open` 读取独立编辑副本，使用平台文件工具编辑，再调用 `dashboard_update`。
+
+检查时点的草稿修订为 r1 → r3 → r5：两轮均分别保存页面与标题，因此每轮产生两次修订。Artifact ID、草稿 ID、Bindings、controls 和依赖快照全部保持一致；实际保存 HTML 的散列与最近一次 HTML 保存回执一致。正式版本数保持为零。
+
+第一轮修改后的筛选、两种刷新、资源卡片重开和浏览器恢复均通过。最终 r5 修改稿的源文件更新、筛选、两种刷新、资源卡片重开与浏览器恢复也全部通过，确认后续编辑没有破坏查询逻辑。
+
+## 查询与权限边界
+
+- 保持同一访问者 JWT，撤销 Assistant 文件访问或 DATA_SOURCE_VIEW 后，CSV/JSON/XLSX 的发现与查询均拒绝；恢复权限后下一次请求成功。测试者不继承工作区成员权限，临时授权已清理。
+- 已保存查询拒绝未知 Binding、未知控件、文件路径与身份、读取配置、URL、Provider、Binding 内容及 payload 覆盖。测试覆盖新建与持续修改后的看板。
+- HTML 不能直接请求后端或读取父 DOM；页面始终通过已保存 Binding 及声明的控件取数。
+- 本次没有放宽版本并发、文件授权或数据查询规则。
+
+## 发现与处理
+
+1. 初轮 XLSX 页面的刷新按钮调用 `live.refresh()` 时遗漏 Binding ID；工具栏刷新正常，但页面内刷新没有查询。预检新增有界原生按钮交互，工具返回与技能明确每个刷新必须传入 Binding ID。重新生成后两种刷新均通过。
+2. 初轮三来源页面只过滤浏览器已有数据。原生数据下拉现在用 `data-dashboard-control` 显式声明关联控件；纯展示下拉用 `data-dashboard-presentation`。预检检查实际查询及共享控件传播，不根据控件名称猜测用途。
+3. 后续首稿虽正确查询，但仍把排除区域绘制成零值系列。真实 UI 验收发现后，经同一 Artifact 的后续编辑修复；图库工具说明和技能强调从本次 Dataset 派生系列。新会话生成的三来源看板再次独立通过完整闭环。
+4. 生成过程中的渲染回调错误被保存预检拦截，Agent 在同一轮中自行修复。跨轮编辑时，平台文件工具拒绝覆盖已有文件，Agent 改用编辑工具后成功保存。失败调用不计为保存成功。
+
+预检使用真实默认预览数据，验证初始 Binding 查询、控件类型与联动及运行错误；它不认证业务语义，也不穷举全部自定义交互。已有保存页面仍可打开；编辑后重新保存时需补齐原生控件标记。上述结果证明本次真实用例，不保证任意模型、输入或页面都能一次正确生成。
+
+## 自动化与文档检查
+
+- 文件适配器：20 项测试通过。
+- 上述本地闭环阶段的看板插件：60 项单元测试、33 项真实 Chromium 预检通过；包括每个初始 Binding、延迟面板、错误刷新回调、缺少 Binding ID、仅本地筛选、共享筛选、类型与枚举、ECharts 和 Three.js 核心对象。
+- 构建、产物一致性、元数据及 dist-first 生命周期检查通过；实际 tarball 中的 Action 和技能示例与源码一致。构建使用当前 xpert-pro 配套 SDK 产物，不代表独立 npm 发布兼容性验证。
+- 平台与官网中英文功能文档同步更新；20 份变更文档的链接及 frontmatter、2 项官网导航测试均通过，官网 `mint validate --disable-openapi` 构建校验通过。
+
+## 2026-10-18 提交前代码复验
+
+后续代码检查复现了一个预检遗漏：数据下拉误查不声明该控件的另一个 Binding，仍可能通过检查。修复后按 Binding 参数中的 `controlId` 核对查询归属，并新增回归用例；现有独立筛选和共享筛选用例继续通过。后端查询权限规则保持不变。
+
+该次复验在隔离源码快照中完成，60 项单元测试和 34 项 Chromium 预检通过，类型检查、构建、Action 与依赖产物一致性、插件元数据及模拟生命周期检查通过。构建仍使用配套平台 SDK 产物。这次代码复验没有替换运行环境的插件、重新执行上述 Agent/UI 闭环或增加新的 SSO、正式发布验收范围。
+
+相关流程见[HTML 看板](./html-mode)、[文件编辑与技能](./file-authoring)及[构建与验证](./verification)。

package/docs/fixed-build-multimodel-acceptance.mdx

@@ -0,0 +1,129 @@
+---
+title: "2026-10-19 固定构建与多模型回归"
+description: "固定运行代码和构建字节，区分模型可用性、工具恢复与页面业务结果。"
+---
+
+## 范围
+
+本轮在本地 xpert-pro 源码环境执行 CSV、JSON、XLSX 的真实 Chat 生成、同一草稿连续修改、
+区域筛选、源文件更新刷新、资源卡片重开和整页恢复。只使用独立合成数据与现有模型连接，
+不发布看板正式版本，不执行 SDK npm 或正式发布包认证，也不建立新的外部 SSO 撤销结论。
+
+平台基线为 xpert `6df7d17f0`、xpert-pro `17d05673d`，插件为 `7f83906b` 加本轮工作区修改。
+平台及文件适配器没有新增业务代码；页面约束、HTML 预检、技能和验收流程由看板插件维护。
+WorkspaceFiles、Dataset/Binding、Artifacts、权限与文档隔离仍由平台提供。
+
+## 固定构建与模型证明
+
+诊断构建 A、B 的结果独立保留。最终构建 C 经构建、测试、本地插件部署、API 重启、
+严格环境检查及四个已安装技能文件的字节核对后，才记录不可覆盖的构建清单。
+清单覆盖平台版本与运行代码差异、SDK/contracts 产物、插件运行源码、技能、Sandbox Action 和 dist。
+每轮生成前后及最终汇总再次比较摘要；代码或产物变化必须另建基线。
+文档和回归检查器可以补充，但不能修改被测运行代码后沿用旧的成功结论。
+
+模型选择必须在 Chat 输入框明确完成，并由每轮根执行记录的主模型 ID、名称、连接和参数快照核对。
+只有模型选择器标签或 API 偏好不够。两组接受基线使用同一已配置通义连接的 Qwen 3.6 Plus 与
+Qwen 3.5 Plus；参数均为 temperature 0.1、max_tokens 16384、enable_thinking true、
+thinking_budget 4096、maxRetries 1。工具重试统计来自实际工具回执，不代表供应商内部重试次数。
+
+## 本轮修复
+
+- 打开编辑副本明确标记 `hasUnsavedChanges: false`，不再暗示查看回执后必须原样保存。
+- 新看板应选择未使用的 Workspace 路径；文件同名不代表可以改写历史 Artifact。
+- 同一筛选口径的 KPI、趋势和明细应从同一个完整 Dataset 渲染，避免未筛选总额订阅覆盖 KPI。
+- HTML 预检拒绝可见、启用、已声明为数据筛选却没有可用选项的 select；禁用控件和纯展示控件仍可合法存在。
+- 验收确认初次生成确实调用创建工具，不能把历史 Artifact 的更新算作新生成。
+- 查询证据必须在 UI 操作之后发起，并携带相应的筛选值，不能拿初始加载的迟到响应证明筛选成功。
+- 明细表的合计行独立核对，避免双计，也不能静默忽略合计错误。
+
+以上约束没有放宽文件覆盖、草稿 CAS、数据源授权或 Binding 查询边界。生成指引不能代替独立业务验收。
+
+## 结果
+
+两组使用同一个构建摘要 `feef1fe8724ffe05e56961b4e2aa48bde10ec0d436eab4ba42add8a4f87f6b63`。
+最终六份看板均通过生成后修正、两轮持续修改、筛选、源文件更新刷新和保存重开。
+
+| 模型 | 真实 Chat 轮次 | 首次数据交互通过 | 首次业务及视觉通过 | 工具错误 | 保存调用 | 完整数据交互检查 |
+| --- | --- | --- | --- | --- | --- | --- |
+| Qwen 3.6 Plus | 11（含两次额外业务修复） | 1 / 3 | 1 / 3 | 8 | 15 | 72 |
+| Qwen 3.5 Plus | 9（CSV 第二次修改包含视觉修复） | 3 / 3 | 2 / 3 | 4 | 10 | 72 |
+
+“首次”指第一次生成请求结束后的页面结果，允许同一轮内发生工具错误和自动恢复，
+不代表零工具重试。两组共 20 个模型轮次、25 次保存调用，其中 5 次被拒绝后恢复。
+18 个页面轮次的数据交互检查通过，合计 144 项；其中 Qwen 3.5 CSV 的初版和第一次修改版
+仍有视觉缺陷，因此只有 16 个页面轮次同时没有已记录的视觉失败，不能把 18 全部称为业务验收通过。
+当前六个最终页面均已复核，数据和已发现的视觉问题均通过。
+
+| 模型 / 来源 | 接受的数据基线 → 第一次修改 → 第二次修改 | 原始失败与修复 |
+| --- | --- | --- |
+| Qwen 3.6 / CSV | r1 → r2 → r3 | 创建期间恢复文件冲突及预检错误 |
+| Qwen 3.6 / JSON | r2 → r3 → r4 | 原始 r1 筛选后 KPI 和趋势仍显示全部区域；Chat 修复到 r2 |
+| Qwen 3.6 / XLSX | r2 → r3 → r4 | 原始 r1 筛选后保留另一地区系列；Chat 修复到 r2 |
+| Qwen 3.5 / CSV | r1 → r2 → r3 | r1/r2 数据正确但加载占位挤出图表；第二次修改到 r3 时修复 |
+| Qwen 3.5 / JSON | r1 → r2 → r3 | 恢复 Binding 参数结构、契约摘要及正式基准 UUID 错误 |
+| Qwen 3.5 / XLSX | r1 → r2 → r3 | 三轮没有工具错误 |
+
+每轮检查初始值、华东、更新源文件后的宿主刷新、页面刷新、华西、恢复源文件后全部区域、
+资源卡片重开、整页刷新恢复。核对 KPI、逐行金额、逐月趋势、地区系列与查询筛选值，
+宿主刷新保留页面实例。源文件最终 SHA-256 与初始值一致。
+
+全部持续修改保持同一 Artifact 和草稿、递增 revision、不变的 Binding、控件及依赖锁，
+并核对保存回执中的 HTML 摘要。正式版本数量均为零。
+Qwen 3.5 的标题在中英文交界增加空格；标题文字和修订后缀按忽略展示空白比较，
+原始与期望标题差异完整保留，不将其表述为逐字节相同。
+
+## 权限、边界与恢复
+
+- 两组各使用一个临时非管理员，覆盖三种格式，共六组同 JWT 撤销场景。
+  授权时查询为 201；撤销 `DATA_SOURCE_VIEW` 后查询及发现为 403；恢复后为 201。
+  撤销临时用户的 Assistant 分享和独立工作区授权后，文件查询为 403，恢复授权后再验证可读。
+- 最终七个已保存 Binding 各执行九种覆盖尝试，63 次全部拒绝：路径、文件目录、Reader、URL、
+  Provider、完整 Binding、payload、未知控件和未知 Binding。
+- 六个最终页面对可访问的本地健康接口发起直接 fetch，均观察到 `connect-src` 违规和请求拒绝。
+  页面交互检查还覆盖未知 Binding、未知控件及父页面 DOM 访问。
+- 临时分享、用户、权限和角色通过公共接口完成清理。测试结束后恢复 Assistant 原来的模型允许范围
+  与默认选择，核对 graph 和 draft 未变。保留验收草稿、诊断样本和截图。
+- 最后再次核对固定构建清单与严格环境 ready 状态。没有提交或推送代码。
+
+## 自动检查与剩余限制
+
+匹配平台源码的 SDK 构建通过；平台参数校验与文件恢复 10 项、文件中间件 10 项、
+PermissionGuard 22 项通过。插件 68 项测试（包含 5 项回归证据反例检查）、真实 Chromium 预检 36 项、
+元数据核对、远程 bundle 与 Action/图库摘要检查、plugin-dev-harness 生命周期通过。
+本轮修改的 MDX 与导航 JSON 校验通过。
+
+仍观察到模型参数结构错误、错误字段、文件同名、非唯一编辑文本和字符串形式的空版本值，
+均按实际错误记录并恢复；不是零重试保证。Qwen 3.6 JSON 第二次修改还发生一次
+`DOCUMENT_BUTTON_INTERACTION_FAILED`，相同 HTML 和保存参数在只读检查后重试通过。
+保留为已恢复的瞬态预检失败，尚不能从单次样本确认原因或认定已消除。
+浏览器验收另有三次卡片等待超时，均发生在发送提示之前；保留失败日志，确认卡片存在后
+将等待上限调整为 60 秒并复跑，没有重复发送模型请求。
+
+这是两个 Qwen 版本、每种格式一次新建和两次连续修改的小样本基线。
+业务修复请求和 CSV 的额外视觉修复说明均单独记录，不能据此推断某模型整体优于另一模型，
+也没有完成跨供应商、DeepSeek、并发压力、长时间运行或正式发布兼容性验证。
+
+## 保留的诊断记录
+
+构建 A 暴露了旧文件碰撞后修改历史测试 Artifact、部分文件编辑失败和无变化重复保存。
+构建 B 暴露了启用但没有选项的区域筛选，以及刷新时未筛选查询覆盖筛选后 KPI。
+这些样本用于推动修复，不计作构建 C 的成功样本。B 中存在与源文件变更重叠的生成及构建变化，
+因此不能拿它建立固定构建成功率。
+
+构建 C 的模型配置诊断中，API 偏好已切换但 ChatKit 实际提交默认 Qwen；执行记录识别后取消三次诊断，
+验收脚本改为每轮从可见模型菜单明确选择。随后实际 DeepSeek V3.2 请求均返回供应商
+`404 Model not exist`，没有进入工具调用。它是当前连接的可用性失败，不是看板业务或工具恢复成功。
+失败记录保留，第二组可运行基线改用现有连接中的 Qwen 3.5 Plus。
+
+## 复跑与证据
+
+见 `tests/acceptance/README.md`。每个模型使用独立私有输出目录与唯一标题，同一构建清单不可覆盖。
+先完成生成或编辑阶段，再执行源文件变更检查；同一文件不能并行修改。
+原始工具状态、保存回执、执行模型快照、DOM、截图、源文件备份和错误均保存在仓库外。
+
+独立业务口径为全部 5700、华东 3500、华西 2200；CSV、JSON、XLSX 的首笔金额分别增加
+100、200、300，刷新后的华东应为 3600、3700、3800。最终汇总必须核对源文件恢复摘要、
+权限实体清理和每个接受页面的完整八步交互，`read-only` 诊断不能替代源文件更新验收。
+
+参见[构建与验证](./verification)、[文件编写流程](./file-authoring)和
+[前一轮生成重试与持续编辑回归](./retry-regression-acceptance)。

package/docs/frontend-libraries-acceptance.mdx

@@ -0,0 +1,86 @@
+---
+title: "前端图库与版本快照验收"
+description: "2026-10-16：通用依赖注入、ECharts SSO 生成与改版、不可变快照和查询隔离。"
+---
+
+## 实现范围
+
+平台 `@xpert-ai/plugin-sdk/artifact-document` 增加通用依赖锁与源码校验，
+锁包含 ID、精确版本、脚本格式、全局名称与 SHA-256。
+宿主在 CSP 和页面 SDK 之后、作者脚本之前注入校验后的代码，保持原有 iframe 隔离与查询协议。
+这些能力同步至 Xpert Pro；平台没有引入 ECharts、Three.js 或看板专属的数据源逻辑。
+
+Live Dashboard 插件负责图库允许列表、构建与许可证，目前打包 ECharts 5.6.0 和 Three.js 0.185.1 核心库。
+使用图库的版本以 `xpert.live-dashboard.package/v1` 保存完整 HTML、Binding、控件、依赖锁和实际库源码。
+源码与定义共享 Artifact Version 的内容校验；省略 `libraries` 的修改保留原始依赖字节。
+历史版本无需当前插件继续提供相同版本的库，无图库的旧定义保持兼容。
+
+Agent 新增 `dashboard_libraries` 工具，只读取元数据与使用说明，不向模型传递库源码。
+`dashboard_create_html` 和 `dashboard_update` 接受允许的图库 ID 列表；
+发现数据、真实预览、筛选证据、版本 CAS 与后台浏览器预检继续适用。
+预检与实际页面使用完全相同的依赖快照。
+用法和限制见[固定前端图库](frontend-libraries.mdx)。
+
+## 真实 SSO 验收
+
+在本地 Xpert Pro 与 data-xpert SSO Workbench 使用真实 ChatKit 和已配置模型，
+通过一句话要求创建 ECharts HTML 看板。业务来源为 PostgreSQL 验收订单，
+指标是 2026 年第三季度已支付订单的实付减退款，单位人民币元，按月和区域汇总。
+本轮验证 ECharts 的展示与版本能力；数据源适配器本身未修改，
+此前本体与 Workspace 脚本的 HTML 验收记录见[持续修改验收](evolution-acceptance.mdx)。
+
+| 检查 | 实际结果 |
+| --- | --- |
+| 一句话生成 | Agent 发现、预览、验证筛选，调用图库发现工具，以 `libraries:["echarts"]` 保存 v1 |
+| 后台预检 | 真实 Sandbox Browser Job 成功，执行同一份 ECharts 源码和默认 Dataset |
+| 持续修改 | 选中当前作品后提出自然语言修改；`dashboard_open({})` 取得正确目标，`dashboard_update` 保存 v2 |
+| 页面变化 | 浅色销售驾驶舱的折线图改为深蓝金色经营指挥屏的分组柱状图 |
+| 身份与依赖 | Artifact ID、Binding、ECharts 版本及源码摘要保持不变，修改工具未传入 `libraries` |
+| 保存重开 | 刷新浏览器后打开当前版本，再通过版本菜单打开 v1/v2，均正确渲染 |
+
+生成过程中曾选错文件写入工具的参数字段，工具拒绝该请求；
+Agent 在同一轮自行更正后继续保存，未手工改写生成 HTML 或伪造成功回执。
+初始汇总表被标成“订单明细”；修改请求明确纠正为“月度区域汇总明细”。
+这也说明浏览器预检不能替代业务标签与展示语义验收。
+
+## 数据与刷新 oracle
+
+独立预期沿用验收订单定义，不从被测查询返回值反推：
+
+| 月份 | 华东 | 华西 |
+| --- | ---: | ---: |
+| 2026-07 | 1,000 | 800 |
+| 2026-08 | 1,500 | 900 |
+| 2026-09 | 1,000 | 500 |
+| 合计 | 3,500 | 2,200 |
+
+两个版本均验证默认合计 5,700、华东 3,500、华西 2,200。
+除了页面数字和表格，还读取真实 ECharts 实例的 series，验证线图／柱图的数据与独立预期一致。
+临时把华西七月的一笔实付增加 100 后，刷新使图表数值 800 → 900、合计 2,200 → 2,300；
+恢复来源后再次刷新回到原值。筛选值和 HTML 文档实例均保留，全部临时金额已恢复。
+
+两版接口共验证 12 次成功查询／刷新与 12 次拒绝请求；
+初始版本的定义摘要、两版的依赖源码与锁定摘要均逐一核验。
+历史版本保存的是页面与查询定义，打开时仍查询当前授权的最新业务数据。
+
+## 查询与资源边界
+
+- ECharts 已加载时，浏览器尝试直接 fetch 后端、读取父页面 DOM、查询未声明 Binding，均被拒绝。
+- 服务端继续拒绝额外 SQL payload、替换 Provider、替代 Binding、替换数据源、未知控件；未声明 Binding 返回 403。
+- 回归验证未知图库、伪造版本、缺失快照、源码摘要不符、重复全局名称、保留的 SDK 全局名称和超限源码。
+- 在受控测试中移除当前图库目录解析器后，已保存版本仍从自身快照取得原始依赖。
+- 没有开放 CDN、动态模块导入、任意网络、宿主存储、跨 View Action 或额外数据访问权限。
+
+## 构建、打包和回归
+
+- Core 与 Pro SDK 构建通过；通用协议／依赖单元测试 8 项通过。
+- 平台真实 Chromium 检查 26 项通过，其中包含库源码中 `</script>` 字符串的精确注入，及原有 CSP、请求重放、并发、销毁和重挂载检查。
+- Live Dashboard 工具与领域测试 29 项通过；生产远程 bundle 的 Workbench 浏览器检查 10 项通过。
+- HTML 预检 6 项通过：真实 Dataset、未声明 Binding、渲染异常、实际 ECharts SVG、缺少图库阻止保存、Three.js Scene/Geometry/Mesh。
+- 原生插件生命周期加载／关闭通过；发布包解包后核验 Action 内容、图库源码、精确版本和许可证文件。
+- 本地部署验证成功；私有执行回执、Job ID、版本记录与截图保留在验收环境。
+
+Three.js 目前完成核心库与场景对象验证，未完成真实 SSO 中的 WebGL GPU 页面验收；
+不包含 addons、外部模型、纹理、WebGPU 或 worker。
+刷新仍是重新执行声明式查询，没有新增后台推送或自动轮询。
+该结果是本地集成验收，不代表生产发布、任意页面语义正确性或多租户压力验证。

package/docs/frontend-libraries.mdx

@@ -0,0 +1,57 @@
+---
+title: "固定前端图库"
+description: "ECharts、Three.js 的受控注入、版本快照和 Binding 边界。"
+---
+
+## Agent 使用方式
+
+调用 `dashboard_libraries` 读取可用库的精确版本、全局名称、摘要和能力说明。
+当前打包 ECharts 5.6.0（`window.echarts`）与 Three.js 0.185.1（`window.THREE`）。
+创建 HTML 看板时传入 `libraries: ["echarts"]`；不使用库时省略。
+已有看板先 `dashboard_open`，读取原 HTML，再 `dashboard_update`。
+修改工具省略 `libraries` 会保留原依赖；显式传入完整列表表示增加、移除或升级依赖。
+库在作者代码执行前已加载，不要写 CDN 标签、ES module import 或复制库源码。
+
+```javascript
+const chart = echarts.init(document.querySelector('#chart'), null, { renderer: 'svg' })
+const live = window.xpertLiveArtifact
+live.subscribe('sales', dataset => {
+  chart.setOption({
+    xAxis: { type: 'category', data: dataset.rows.map(row => row.month) },
+    yAxis: { type: 'value' },
+    series: [{ type: 'bar', data: dataset.rows.map(row => Number(row.net_sales)) }]
+  }, { notMerge: true })
+})
+new ResizeObserver(() => chart.resize()).observe(document.querySelector('#chart'))
+live.query('sales', { region: null }).catch(showError)
+```
+
+示例中的字段、粒度、Binding 和控件必须替换为实际预览结果；元素需有非零尺寸。
+复用图表实例，通过订阅更新筛选和刷新结果，不要反复初始化。
+ECharts 支持 Canvas/SVG；见 [官方引入说明](https://echarts.apache.org/handbook/en/basics/import/)。
+
+Three.js 提供核心库、Scene、Geometry、Material 与 WebGLRenderer。
+WebGLRenderer 需要浏览器提供 WebGL2，必须处理 GPU 不可用并释放资源。
+未打包 addons/loaders、外部模型/纹理、WebGPU 或 worker；
+参见 [Three.js WebGLRenderer](https://threejs.org/docs/pages/WebGLRenderer)。
+
+## 分层与历史版本
+
+平台 SDK 负责通用依赖锁、SHA-256 校验、代码大小限制和隔离注入。
+本插件负责允许列表、打包、许可证、Agent 工具和看板版本语义，数据源插件无需感知图库。
+
+带图库的保存文件采用 `xpert.live-dashboard.package/v1`：`manifest` 存 HTML、Binding 和依赖锁，
+`dependencies` 存库的实际代码。它们共享一个不可变 Artifact Version 和文件摘要。
+旧的无图库 JSON 定义继续兼容。Agent 读取工具只返回依赖元数据，避免把库源码塞进上下文。
+历史版本从自身快照读取库，不依赖当前插件仍保留相同版本；修改默认继承该快照。
+包最大 9 MB；HTML 仍限制为 300 KB，库代码单包 4 MB、合计 8 MB。
+
+生成预检与实际 View 使用同一 SDK、相同 HTML 和同一份库源码。
+未知库、缺失的依赖锁或被篡改的源码会被拒绝，运行时异常会阻止保存。
+包中附带 ECharts 的 LICENSE/NOTICE 和 Three.js LICENSE。
+
+## 查询权限
+
+图库只处理已返回的 Dataset。页面仍只能通过 `xpertLiveArtifact` 指定已保存的 Binding ID 和控件值。
+库注入不会开放 CDN、网络请求、Provider 覆盖、SQL、宿主存储或其他 View Actions。
+服务端继续按当前用户授权查询，旧版本不能恢复已撤销的数据访问权限。

package/docs/html-acceptance.md

@@ -0,0 +1,86 @@
+---
+title: "HTML 模式历史验收"
+---
+
+> 历史验收记录：本次分批提交审核未重新执行其中的模型、SSO、部署或源数据变更场景；当前本地检查见 [构建与验证](verification)。
+
+# HTML / JavaScript 自由看板：实现与验收
+
+日期：2026-10-16。结果：本地 xpert-pro + data-xpert SSO 环境通过本次验收。
+
+## 实现边界
+
+| 归属 | 实现 | 作用 |
+| --- | --- | --- |
+| xpert 平台 SDK（同步至 xpert-pro） | `artifact-document` 子入口：protocol / runtime / host | 通用 HTML 隔离宿主、CSP、独立 MessageChannel、严格查询协议、Binding 白名单、请求限额、最新响应优先、刷新及类型保持的 select 绑定 |
+| Live Dashboard 插件 | schema / service / middleware / remote view | 可选 HTML presentation、Agent 写文件/保存工具、版本绑定查询、数据与页面原子保存、模式选择 |
+| Live Dashboard 插件 | html-validation + Sandbox Action | 用真实预览 Dataset 执行页面，失败时返回可修复诊断；通过后才创建 Artifact |
+| 平台现有能力 | Analytics Runtime、Dataset/Binding、WorkspaceFiles、Artifacts、Managed Queue、Sandbox Jobs | 权限、数据源适配、文件访问、版本与 CAS、后台执行及资源隔离 |
+| 现有插件 | data-xpert Provider、PostgreSQL、Workspace Script Provider、Data Analytics renderer | 继续独立、可替换，不进入 HTML 宿主实现 |
+
+HTML 页只调用 `query(bindingId, controls)`；Artifact/版本由宿主闭包提供，Provider、原生查询和凭据由后端保存的 Binding 解析。HTML、Controls、Bindings 位于同一内容哈希版本。页面不能指定替代数据源或查询体。
+
+## 一句话真实生成
+
+通过 data-xpert 的 SSO ChatKit 入口，使用测试助理 `live-dashboard-acceptance`、已授权本地模型 `qwen3.6-plus`，输入一条消息：
+
+> 请基于 data-xpert 验收数据源的本体净销售额，生成并保存两份2026年第三季度按月份和区域分析的 HTML/JavaScript 实时看板：一份是深色经营驾驶舱，另一份是浅色杂志式分析页面；两份使用同一数据口径，都要有区域筛选、图表、明细和实时刷新。
+
+执行 ID：`53385433-ac36-4793-b1cd-cc0b86dbe30c`，状态 `success`，只有 1 条 human 消息。该助理仅启用 Live Dashboard middleware。Agent 自行发现本体、修正一次预览参数错误、取得真实 Dataset、编写并修正 HTML，然后保存两份看板；没有人工补写这两份页面。
+
+| 页面 | Artifact ID | Version ID | 预检 Sandbox Job |
+| --- | --- | --- | --- |
+| 2026年Q3 本体净销售额 · 经营驾驶舱 | `dd53f0f7-2e5e-45a7-80d8-943c52dc0e16` | `a6352d3d-05e9-4c80-ab82-a1ddeac65e23` | `bfbadff5-ac26-4669-9d75-f9db49ab22f8` |
+| 2026年Q3 本体净销售额 · 杂志式分析 | `d68d2a80-2031-4cdd-a002-5e3b6614de9f` | `56a428a5-c9fc-4280-b978-5a1a9f8217ff` | `d230c6c8-94a3-4a2f-bc20-958b92466cbe` |
+
+两个版本均为 v1，HTML 不同，Binding 完全一致：`netsales_q3_2026`，Provider 为 `data-xpert.ontology`，来源为 NetSales 本体。两个 Browser Job 均 `succeeded`，容器均已回收。版本 metadata 保留 `htmlValidation.status=passed` 和 Job ID。
+
+## 业务与浏览器验收
+
+数据口径：2026 年 7–9 月，已支付订单扣除退款，人民币元；粒度为月份 × 区域。
+
+| 检查 | 真实结果 |
+| --- | --- |
+| 两种样式 | 深色驾驶舱使用 KPI 卡片、分组柱图、环形图；浅色杂志页使用导语、衬线标题、折线图、结构图及明细。均经截图检查 |
+| 全部区域 | 6 行，合计 5,700；月度合计 1,800 / 2,400 / 1,500 |
+| 华东筛选 | API 核对 3 行，合计 3,500 |
+| 华西筛选 | 两份真实页面均为 3 行、2,200，图表/KPI/明细同步，筛选候选项仍保留全部区域/华东/华西 |
+| 实时刷新 | 将验收源表 `dashboard_sales_orders_acceptance` 的 `ld-02` 金额增加 100；两份页面保持华西筛选，点击宿主刷新后变为 2,300，7 月变为 900 |
+| 状态保留 | 刷新前后选项不变；页面中设置的验证标记仍在，证明刷新没有重载整个 HTML 文档 |
+| 恢复 | 每次变更均在 finally 中恢复；两份页面回到 2,200，最终全量查询回到 5,700 |
+| 保存重开 | 重启 xpert-pro API、重新加载 data-xpert，再从选择器打开两份页面；原 Artifact/Version 不变，重新查询得到 6 行、5,700 |
+| 标准模式兼容 | 既有“2026年第三季度净销售额看板（人民币元）”仍由 Data Analytics 渲染，柱图及 6 行明细正确 |
+
+HTTP 验收对每份页面执行全量/华东/华西及重复刷新，共 12 次成功查询；每次重新执行得到不同 executionId。保存重开同时核对定义完全一致。
+
+截图（本地验收输出，不含凭据）：
+
+- [深色页](../output/playwright/html-dark-all.png)
+- [浅色页](../output/playwright/html-light-all.png)
+- [深色页实时刷新](../output/playwright/html-dark-live-refresh.png)
+- [浅色页实时刷新](../output/playwright/html-light-live-refresh.png)
+- [Data Analytics 回归](../output/playwright/html-standard-renderer-regression.png)
+
+## 声明式查询边界
+
+真实 SSO 页面中尝试未知 Binding、修改 `ready()` 返回的客户端白名单后再查询、伪造父窗口 View Action 消息、读取父页面 DOM/Storage、直接 fetch 后端接口。全部被拒绝，越权尝试产生的 `query-binding` 后端请求为 0。
+
+另外通过已认证 HTTP 客户端，对每份页面分别注入 `payload.sql`、`providerId`、完整 `binding`、替代 `dataSourceId`、未知 Binding、未知 control：共 12 次拒绝，前四种及未知 control 为 400，未知 Binding 为 403。服务端从已保存版本取 Binding，不信任页面提供的查询体。
+
+平台真实 Chromium 测试还覆盖原始 MessagePort 请求注入、旧响应覆盖、资源加载、自导航、eval 和网络阻断；单元测试覆盖其他用户/组织/host、文件篡改和来源权限撤销。该边界针对受隔离的生成页面，不改变已认证用户通过平台其他授权接口访问数据的能力。
+
+## 验收中发现并修复的问题
+
+前两轮生成分别暴露了“筛选选项未初始化”和“查询了未保存的辅助 Binding”；它们不计入通过结果。新增通用 `bindSelect`，强化单一完整 Dataset 指导，并增加保存前隔离浏览器预检。用真实后台任务重放缺失 Binding 页面，返回 `DASHBOARD_HTML_PREFLIGHT_FAILED`，没有创建 Artifact。另有 Chromium 回归用例确认渲染回调异常也会阻止保存。
+
+四份失败实验 Artifact 已归档，保留调查记录；最终两个通过版本仍可在实时看板中选择。
+
+## 验证命令与范围
+
+- 插件构建及 19 项测试通过；平台协议 3 项测试通过。
+- 平台浏览器边界测试 13 个场景通过；预检浏览器回归 3 个场景通过。
+- `verify:dist`、插件 lifecycle harness、真实 npm tarball Action 文件树哈希验证通过。
+- 实际插件 `loadStatus=loaded`；平台健康检查无异常；xpert / xpert-pro 通用文档宿主源码一致。
+- 可复用脚本：`tests/verify-installed-html.mjs`（外部私有上下文 + Keychain 登录）、`tests/html-preflight-browser.mjs`、平台 `packages/plugin-sdk/tests/artifact-document-browser.cjs`。
+
+本轮证明一条业务需求生成两份可用页面，以及上述具体交互和边界。预检只覆盖初始执行，不证明任意业务定义、延迟分支和所有 UI 交互都正确。当前刷新是按当前筛选重新查询最新来源，不含自动推送。HTML 保存需要可用 Browser Runtime；此次为本地构建和部署，尚未发布 SDK/插件 npm 包。更多协议与能力边界见 [HTML 模式说明](html-mode.md)。

package/docs/html-mode.md

@@ -0,0 +1,76 @@
+---
+title: "HTML 模式协议"
+---
+
+# HTML / JavaScript 自由看板
+
+## 数据与展示解耦
+
+平台 Dataset/Binding 和 Analytics Runtime 继续作为唯一数据查询路径。HTML 页面不参与 Provider 选择、凭据处理、SQL 执行或本体 Action 授权。
+
+```text
+Agent → 发现/预览 → previewId
+      → sandbox_write_file / sandbox_edit_file → 授权 Workspace 文件
+      → dashboard_create_html → 隔离浏览器预检 → HTML + Controls + Bindings → 同一 Artifact 工作草稿 → 人工确认 → ArtifactVersion
+
+HTML iframe → 专属 MessagePort → Live Dashboard View → query-binding
+           → 服务端读取保存的版本 → 当前用户权限 → Analytics Runtime → Dataset
+```
+
+## 平台接口
+
+`@xpert-ai/plugin-sdk/artifact-document` 是浏览器安全子入口。`mountArtifactDocument` 封装 HTML 格式验证、CSP、script-only sandbox、独立 MessageChannel、Binding ID 白名单、请求限额、销毁和刷新。`installArtifactDocumentFramePolicy` 在专用宿主文档安装 frame-src 策略，禁止子文档自行跳转到外部 URL。
+
+平台不依赖 `live-dashboard`、data-xpert、图表库或任何业务页面。插件可以替换渲染器与数据源，而不复制平台权限和隔离逻辑。
+
+## 插件协议
+
+保存格式沿用 `xpert.live-dashboard/v1`，向后兼容可选字段：
+
+```json
+{ "presentation": { "type": "html", "html": "<html>…</html>" }, "charts": [], "tables": [] }
+```
+
+HTML 字节、数据 Binding 和 Controls 处于同一内容哈希和版本中。工作区原文件后续编辑不会改变已保存页面。草稿修订号与正式版本基准的 CAS、当前用户及 host 归属检查继续适用。
+
+使用打包图库时，`presentation.dependencies` 保存精确版本与 SHA-256，外层 `xpert.live-dashboard.package/v1` 同时保存实际库源码。无依赖的旧定义仍可读取；详见[固定前端图库](frontend-libraries.mdx)。
+
+`query-binding` View Action 严格接受 `{artifactId, versionId?, draftRevision?, bindingId, controls}`。宿主选择草稿修订或正式版本，服务端打开对应已保存定义并从中取 Binding。额外的 `binding`、`payload`、`providerId`、`dataSourceId` 均被拒绝。未知 Binding、未知控件、非法值、其他用户/host/组织、已撤销来源权限均不能执行查询。HTML 只能向消息桥提交 bindingId 和 controls；Artifact ID/版本由宿主持有。
+
+## Agent 与浏览器
+
+HTML 模式复用标准看板的 discovery/preview 证据，不允许通过编写 HTML 绕开预览或最终 Provider 策略。`sandbox_write_file` / `sandbox_edit_file` 只编辑文件；已有看板通过 `dashboard_update` 保存草稿，新看板的 `dashboard_create_html` 读取真实文件、验证格式及大小并保存。所有文件访问通过平台 WorkspaceFiles 能力。保存前由 `HtmlDashboardValidation` 检查 Browser Action 与后台执行池健康，将真实默认查询结果和 HTML 放入私有临时文件；队列只携带验证任务 ID。插件 Action 在平台 Browser Runtime 中执行相同的页面宿主，禁用网络，检测初始查询、未声明 Binding、脚本异常和空页面。失败结果返回 Agent，当轮修复后可重试，Artifact 创建发生在校验通过之后。标准 JSON 看板不经过此步骤。
+
+验证任务在 `sandbox-browser` 池执行，使用平台资源限制、超时、取消和销毁。短期任务引用与小型报告存于插件独立 Redis 键（5 分钟 TTL），HTML/数据不进入队列；输入/输出临时文件在完成后删除。保存版本的 metadata 保留 Sandbox Job ID 和已请求 Binding ID。真实数据权限仍由保存/查询时的 Analytics Runtime 重新检查。
+
+页面 SDK：
+
+```javascript
+const live = window.xpertLiveArtifact
+live.bindSelect(document.querySelector('select'), {
+  bindingId: 'sales', controlId: 'region', fieldId: 'region', allLabel: '全部区域'
+})
+live.subscribe('sales', dataset => render(dataset))
+await live.ready()
+await live.query('sales', { region: null })
+```
+
+页面可以使用任意内联 HTML/CSS/JS、DOM/SVG/Canvas。字段、精度、粒度、单位和完整性来自 Dataset；业务事实不能硬编码在页面里。外部 CDN、fetch/WebSocket、eval、宿主 DOM、Web Storage、嵌套 iframe 和自导航不开放。宿主的查询权限检查独立于前端限制。
+
+页面滤镜触发带控件值的新查询；宿主刷新沿用各 Binding 最近的值，订阅重绘并保留页面状态。同一 Binding 的过期响应不覆盖新响应。保存重开使用固定页面版本并执行最新数据查询。
+
+平台 `bindSelect` 辅助函数负责类型保持的选项填充、保留完整候选值及 change → query，减少 Agent 漏接事件/忘记调用初始化函数的问题。它不带业务语义或页面样式，不增加数据权限。页面负责关联 label 和显示 `xpert-query-error`。
+
+## 验收
+
+已完成真实 xpert-pro + data-xpert SSO 一句话生成、两种样式、筛选、源数据变更后刷新、服务重启后保存重开及查询绕过验收。结果、Artifact/Job ID、截图和限制见 [验收报告](html-acceptance.md)。
+
+## 当前范围
+
+- 单文件 HTML（300 KB）、含依赖的版本包最大 9 MB；8 个 Binding、24 个控件。
+- 支持原生绘图与插件打包的 ECharts、Three.js 核心库；不开放任意 CDN。
+- 刷新为查询最新来源，未提供服务端推送/定时轮询。
+- Artifact 当前仍为 owner-only；没有扩大分享权限。
+- 保存预检覆盖初始渲染与查询协议；不证明任意图表业务口径、延迟执行分支或所有交互都正确，仍需真实浏览器验收。
+- 预检通过平台 Browser Runtime 约束 CPU/内存与时长；用户浏览器中的页面仍不能保证任意 JavaScript 都不会卡顿。后端 Workspace 数据脚本使用独立 Sandbox Jobs。
+- HTML 保存要求可用的 Browser Runtime Provider 和执行池；不提供 API 进程内执行或权限放宽的降级。

package/docs/index.mdx

@@ -0,0 +1,47 @@
+---
+title: "Live Dashboard"
+description: "使用统一 Dataset/Binding，在标准图表或 HTML 页面中展示实时数据。"
+---
+
+## 分层与责任
+
+| 层 | 责任 |
+| --- | --- |
+| Xpert 平台 | 当前用户授权、Dataset/Binding 协议、数据源插件分发、Artifacts 草稿与版本、Workspace Files、Sandbox Jobs、HTML 文档隔离 |
+| 数据源插件 | PostgreSQL、本体资源或 Workspace 脚本的发现、原生查询和结果适配 |
+| Live Dashboard 插件 | 看板定义、控件与图表绑定、Agent 工具、保存前验证、Workbench 视图 |
+
+看板插件不解析 SQL 或本体查询语法。数据源 Provider 只需返回统一 Dataset；
+标准模式与 HTML 模式共享同一 Binding，不要求来源实现页面接口。
+
+## 接入
+
+使用包含新增协议的本地 SDK/contracts 构建产物，安装来源插件及本插件。
+将 `LiveDashboard` middleware 连接到 Assistant；专用看板助理应使用必需连接，
+使工具与对应 Feature 门控视图同时可用。参考包内 `examples/assistant-middleware.yaml`。
+
+Agent 按“发现来源 → 检查业务语义 → 预览真实数据 → 保存”工作。
+创建工具仅接受本次运行的成功预览回执，并在保存时重新查询验证。
+无法从数据确认指标口径时需要业务澄清，结构校验不证明业务结论。
+
+## 两种展示方式
+
+- 标准模式：用 `charts` / `tables` 映射 Dataset 字段，复用 Data Analytics renderer。
+- HTML 模式：Agent 在授权 Workspace 编写 HTML/CSS/JS，保存时将页面和 Binding 纳入同一工作草稿，人工确认后形成不可变正式版本。
+
+HTML 页面通过 `window.xpertLiveArtifact.query(bindingId, controls)` 请求数据。
+后端只读取保存版本中的 Binding，拒绝查询体、Provider 或数据源替换。
+完整 API 见 [HTML 模式协议](html-mode)。
+
+## 保存与刷新
+
+保存的是定义与 HTML，不是查询结果。草稿采用内容摘要、修订号与正式版本基准的 CAS 防止覆盖；
+成功草稿回执驱动预览，人工确认发布才生成正式版本。
+每次筛选或手动刷新都重新授权和查询；这里的实时刷新不包含自动推送或定时调度。
+
+打开看板后可让 Agent 持续修改同一作品。页面样式修改保留 Binding，数据修改需要新的预览回执；
+自动保存保留 Artifact ID 并增加草稿修订号。Workbench 支持选择历史版本，详见[持续修改与版本历史](editing)。
+
+HTML 保存前需要可用 Browser Runtime 和 `sandbox-browser` 队列。
+初始页面预检失败会阻止保存；标准模式不依赖浏览器任务。
+预检不穷举全部交互、延迟分支或筛选组合。