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

package/docs/agent-acceptance.md

@@ -0,0 +1,96 @@
+---
+title: "一句话生成历史验收"
+---
+
+> 历史验收记录：本次分批提交审核未重新执行其中的模型、SSO、部署或源数据变更场景；当前本地检查见 [构建与验证](verification)。
+
+# 一句话生成业务看板：实现与独立验收
+
+日期：2026-10-16。本文补充 [MVP 验收](acceptance.md)，重点验证真实模型与真实聊天入口；不把手写 Binding 的接口测试当成 Agent 验收。
+
+## 验收方式
+
+在 xpert-pro 使用获授权复用的本地 Tongyi `qwen3.6-plus` 模型，通过 xpert-pro ChatKit 和 data-xpert SSO 内嵌 ChatKit 提交业务需求。提示中没有 SQL、字段名、资源 ID、看板 JSON 或预期金额。专用测试 Assistant 的 `LiveDashboard` middleware 为必需节点；模型和数据源凭据保留在平台及本地密钥设施中。
+
+业务需求是：生成并保存 2026 年第三季度净销售额看板，按月份和区域展示，支持区域筛选，金额以人民币元展示。两次分别指定 PostgreSQL、data-xpert 来源。
+
+测试数据包含 9 个订单：6 个季度内已支付订单，以及取消订单、季度前订单和季度后订单。表注释与语义模型明确：净销售额仅包含已支付订单，计算已支付金额减退款；按订单日期归属月份。data-xpert 同时绑定多个模型，Agent 必须发现并选择正确指标。
+
+独立期望值（不提供给模型）：
+
+| 月份 | 华东 | 华西 | 合计 |
+|---|---:|---:|---:|
+| 2026-07 | 1,000 | 800 | 1,800 |
+| 2026-08 | 1,500 | 900 | 2,400 |
+| 2026-09 | 1,000 | 500 | 1,500 |
+| Q3 | 3,500 | 2,200 | 5,700 |
+
+真实查询与保存、全部/华东/华西筛选、重新打开及刷新均按这些期望值校验。每次刷新要求新的平台 executionId；data-xpert 还要求新的上游 Action executionId。金额字符串保留精度，只有渲染副本转换为安全数值。
+
+## 最终结果
+
+| 场景 | 结果 | 保存回执 |
+|---|---|---|
+| xpert-pro ChatKit → PostgreSQL | 一句话生成、自动打开正确看板、筛选、刷新通过 | Artifact `e24cc376-6fcc-4a6f-9b62-2d1a8f72e482`，版本 `e939d81c-4599-4618-a73f-cd7f5bb44803` |
+| data-xpert SSO ChatKit → 本体 Action | 一句话生成、自动打开正确看板、筛选、刷新通过 | Artifact `9aa56192-2498-44a7-8116-d908c427bf56`，版本 `9451ee7f-db38-44fb-99b1-a595c1203838` |
+| 无足够事实的客户终身价值请求 | 复测未保存替代看板，要求补充口径或数据 | 无保存回执 |
+
+两张最终看板分别为“2026年第三季度销售复盘 - 各月各区域净销售额（人民币元）”和“本体销售复盘”。两边真实 UI 均选择/输入“华西”，点击应用筛选后只显示 800、900、500 元，再点击刷新确认结果与查询时间更新。独立脚本对每张最终看板的全部/华东/华西三个场景各执行两次，6 个场景全部通过。
+
+本机截图（保存在忽略目录，未提交）：[PostgreSQL 筛选与刷新](../output/playwright/agent-postgres-filtered.png)、[data-xpert 筛选与刷新](../output/playwright/agent-datax-filtered.png)。前期未通过粒度或筛选验收的两张测试 Artifact 已归档；看板列表只展示 active Artifact，避免把失败试验当成可用结果。
+
+最终 API 重启、两个页面重新加载后，从持久化列表选择各自看板，均恢复默认全区域的 6 条准确数据，随后独立脚本再次通过全部 6 个筛选场景。[PostgreSQL 重新打开](../output/playwright/agent-postgres-reopened.png)、[data-xpert 重新打开](../output/playwright/agent-datax-reopened.png)。
+
+## 本轮完善的模块
+
+| 所属 | 修改模块 | 职责 |
+|---|---|---|
+| Xpert 平台 / SDK | `analytics-query.model.ts`、`plugin-sdk/src/lib/data/analytics`、`server/src/data-source/analytics` | 通用分页发现协议、Provider 发现接口、鉴权、查询分发、Dataset 校验、可修复的安全错误码 |
+| Xpert 平台 / SDK | Workbench adapter / SQL guard | 传递数据库业务注释；支持只读 `DATE_TRUNC` |
+| Xpert 平台 | queued Agent 的 runtime user 恢复 | 重新读取当前用户及组织权限；不信任序列化旧角色，不以 Assistant 创建者替代当前用户 |
+| Xpert 平台 | `xpert-agent/agent.ts` 工具完成事件 | 完成消息携带工具名称，使宿主可独立路由结果；不依赖聊天文本合并之前的开始消息 |
+| PostgreSQL 插件 | `analytics-postgres/discovery.ts`、原生 `postgres-workbench.ts` | 目录/字段/注释/键发现；SQLSTATE 错误及时返回，避免等待查询超时 |
+| data-xpert | analytics discovery/query、semantic model mapper | 当前用户可见资源与 Action 发现；发布时保留指标描述、源列、格式与业务语义；只读 Action 实时执行 |
+| data-xpert 适配插件 | `analytics-data-xpert/provider.ts` | 本体 Action 原生查询契约、参数路径、SSO actor token、统一 Dataset；单值筛选与数组条件的语义由插件说明 |
+| Live Dashboard 插件 | middleware / agent schema | 发现 → 预览 → 保存；本次执行的预览回执、工具调用预算、业务口径与缺失信息澄清 |
+| Live Dashboard 插件 | dashboard schema / service | 图表粒度、控件默认值和类型校验；保存前探测声明的非默认筛选；复用 Artifacts 版本与 CAS |
+| Live Dashboard 插件 | remote bridge / view | 仅从成功保存回执打开精确 Artifact；忽略开始/失败日志并去重；复用原 Data Analytics 渲染器 |
+
+通用协议与权限逻辑同步到 xpert-pro；未把 PostgreSQL SQL、data-xpert 本体语法或看板提示词塞入平台。LLM 边界的 `requestJson`/`payloadJson` 只是函数调用格式适配，解析后仍使用统一 JSON Binding 协议。
+
+## 验收发现及修复
+
+1. ChatKit 使用显式插件允许列表，原可选 middleware 没有被加载。专用看板 Assistant 将其标记为 `required: true`；没有绕过平台能力选择规则。
+2. 同一“月份×区域”数据集曾被用于未编码区域的折线图。新增粒度校验后，合计趋势必须另查月度聚合 Dataset，或保留区域系列。
+3. data-xpert 曾用数组 `in` 条件绑定单值筛选，默认 null 可用但区域选择失败。补充原生契约说明，并在预览/保存时探测声明的非默认值；真实验收另外逐一验证全部、华东、华西。
+4. 扁平 Artifact 回执被宿主自动作为 JSON 文件打开。改为 `{ dashboard: savedReceipt }`，由插件视图负责展示，Artifacts 继续负责持久化。
+5. 宿主通道含有工具开始日志，而平台原完成消息没有工具名，无法被订阅器识别。平台补全完成事件身份；视图不再根据“最新看板”猜测结果，而是验证成功回执，使用其中的 Artifact ID 精确打开。
+6. 负向案例“客户终身价值”最初试图用区域收入替代。加强业务约束后复测：发现销售订单缺客户标识、可关联支付表为空，未调用保存，向用户请求业务澄清。此项不等价于对任意模型和任意指标的正确性保证。
+
+## 自动化回归与复现
+
+- Dashboard：11 项测试通过，涵盖预览回执、权限重新校验、图表粒度、默认与非默认筛选、保存 CAS、文件摘要、防止打开错误看板。
+- PostgreSQL provider：3 项单测通过；真实 PostgreSQL 集成另行显式启用并通过，包含参数绑定、截断、只读拒绝、错误后继续查询、SQLSTATE 在 3 秒内返回。
+- data-xpert provider：4 项测试通过。
+- 平台 analytics HTTP：5 项；SDK 结果规范化 9 项、字段注释 1 项、SQL guard 41 项；运行用户及分发相关 20 项通过。
+- 平台 Agent 流事件：8 项通过，包含工具完成消息携带工具名与结果的回归断言。
+- data-xpert discovery/query/语义映射：19 项通过；两份关联技能文档校验通过。
+- 三个新增插件及原生 PostgreSQL 插件的 dist-first 生命周期验证通过；最终插件元数据来自各自 package.json，静态元数据检查通过。
+- contracts/SDK 构建、插件构建及远程组件类型检查通过；核心变更在 xpert / xpert-pro 的对应文件校验一致。
+
+保存后可使用 `tests/verify-installed-dashboard.mjs` 独立复核。其私有 context 包含 API 地址、Assistant/Artifact/version ID、Keychain 条目名称、各筛选场景及独立期望行；不包含密码或 token。脚本读取持久化定义，重新执行所有场景并比较精确行集，最后再次刷新检查执行记录。
+
+```sh
+node tests/verify-installed-dashboard.mjs \
+  --platform-root /path/to/xpert-pro \
+  --context /private/oracle-context.json \
+  --output /private/verification.json
+```
+
+## 边界
+
+“正确”以本次固定业务口径与独立数据 oracle 为准。真实业务需要可发现的指标定义、日期归属、单位、状态过滤与关联基数；缺失时应澄清。结构校验不能推导缺失的业务事实。模型仍可能出现可修复的参数错误，耗时与重试次数随模型变化。
+
+保存前的筛选探测使用声明的候选值，不会编造自由输入控件的业务值，也不穷举多个筛选器的笛卡尔积。开放输入与复杂组合需要业务场景验收。
+
+本轮没有新增跨源 Join、公开分享、调度刷新或 Workspace Python/JavaScript 执行器；后者继续保留为独立可替换 Provider 方案，见平台 `workspace-dataset-pipelines.md`。

package/docs/chat-resource-cards.mdx

@@ -0,0 +1,60 @@
+---
+title: 对话中的看板资源卡片
+description: 复用平台消息卡片与 Workbench 导航，展示可重开的看板回执
+---
+
+## 使用方式
+
+Agent 成功执行 `dashboard_create`、`dashboard_create_html`、`dashboard_update` 或 `dashboard_open` 后，消息列表自动显示一张资源卡片，包含看板名称、图标、草稿修订号或正式版本号及“打开”按钮。
+
+点击“打开”进入现有 Workbench 实时看板视图并选中对应 Artifact。消息内不运行看板，不复制 HTML、SQL、Dataset 行数据或凭据。标准图表与 HTML/JS 看板共用同一种卡片。
+
+- 草稿卡片是该轮保存状态的快照，点击后读取当前保存内容。
+- 显式读取历史 `versionId` 时，卡片固定打开该正式版本。
+- 同一条回复多次处理同一个 Artifact，平台更新同一张卡片；其他回复保留各自快照。
+- 重开对话恢复已保存卡片。加载消息本身不会自动打开看板。
+- 卡片不授予新的访问权限。点击后仍须通过当前主机、用户和 Artifact 的权限检查。
+
+## 职责与协议
+
+平台负责 `emitResourceCard`、消息/执行绑定、持久化、去重、通用卡片渲染和导航。插件只生成 `live_dashboard / live-dashboard` 资源引用及看板展示快照；不新增消息 API、卡片 Provider 或专用聊天渲染器。
+
+Agent 主机使用 `workbench.view`；Project 主机使用 `assistant.project` 和平台 Project ID。目标 View 为 `live-dashboard__live-dashboard`，`selectionId` 为 Artifact ID，历史版本使用 `parameters.versionId`。
+
+View 用同一个类型校验器解析 `initialQuery` 和后端查询，拒绝不合法 ID、相互冲突的目标及没有 Artifact 的版本参数。重复 `init` 不重复加载，不丢弃本地编辑。手动选择、保存和工具完成后的导航通过公开 `workbench.navigation.open` 同步，避免后续卡片点击仍指向旧选择。
+
+工具只在授权读取或持久化成功后发出卡片。`resourceCard.status` 为 `emitted` 或 `unavailable`，独立于业务保存回执；展示失败不重试创建或回滚已保存内容。Agent 使用安装的 `live-dashboard` 技能，不需要另外调用 `present_files` 或构造链接。
+
+## 验证范围
+
+插件测试覆盖标准/HTML 创建、打开、修改的真实工具回调；失败操作不发卡片；稳定身份、Project 路由、历史版本及拒绝越权/非法目标。生产前端包的 Workbench 测试覆盖卡片切换目标、历史版本、重复初始化保留编辑，并回归筛选、刷新、保存重开与团队分享。
+
+资源卡片默认在 ChatKit 自己的 Workbench 中打开插件 View，复用现有 `workbench.navigation.open`、View 注册及历史恢复能力，无需新增导航模式选项。ChatKit 解析当前授权会话的卡片与可用 View，传递 `selectionId` 和 `parameters`；插件通过 `initialQuery` 读取指定看板。平台继续负责 View 和 Artifact API 的权限检查，跨 Project 等导航仍使用既有平台协议。
+
+## 首轮本地验收记录（2026-10-17，导航方案已调整）
+
+在 `xpert-pro` 的 `http://localhost:4201`、现有已登录测试会话中，使用实际模型完成以下验收：
+
+- 创建 PostgreSQL 标准图表看板，消息持久化一张草稿 r1 卡片；打开进入现有左侧 Workbench，选中正确 Artifact，不再额外打开 ChatKit 内部抽屉。
+- Agent 读取后修改标题，保存同一 Artifact 的草稿 r2。该回复只保留一张更新后的卡片；Bindings、控件、图表及表格定义保持一致，未创建正式版本。
+- 点击旧回复的 r1 快照可以打开当前 r2 草稿；刷新整个页面后，消息卡片、目标选择及图表恢复正常。
+- 标准渲染器显示 6 行区域/月度数据；筛选华东返回 3 行、合计 3500，刷新重新查询并更新取数时间。
+- 已有 ECharts HTML 看板经 `dashboard_open` 发出卡片，点击和重开正确定位该看板。
+
+验收中修正了标准看板编辑说明误导 Agent 使用 HTML 文件的问题；旧失败会话已触发 LoopGuard，未绕过保护，修复后以新会话完成真实修改验收。初次渲染需等待 Data Analytics 子框架完成加载，单看查询完成标记不足以证明页面已显示。
+
+自动检查：插件 53 项测试、生命周期和生产包 Workbench 浏览器测试通过；平台导航相关 119 项测试通过；ChatKit 命令、资源卡片导航与恢复相关 57 项测试及类型检查通过。
+
+以上首轮验收使用了本地构建的宿主接管导航方案。产品方向明确优先使用 ChatKit 自己的 Workbench 后，已撤回 `viewNavigation: 'host'` 及对应平台配置，取消该批提交；资源卡片与插件目标解析协议保留。该功能不再依赖新发版的导航选项。
+
+### ChatKit 原生 Workbench 复核（2026-10-17）
+
+撤回宿主接管逻辑并恢复原 ChatKit 安装包后，在 xpert-pro 关闭原生 View，再点击 ECharts 看板卡片：ChatKit 内部打开“实时看板”标签，查询准确携带该卡片的 Artifact ID；刷新页面后原生标签及同一看板恢复。平台左侧既有 View 未被卡片替换。该复核确认现有 ChatKit 已具备卡片打开插件 View 的能力，插件只需正确消费导航参数。
+
+当前原生导航、Project 导航及历史恢复相关 82 项测试通过，xpert-pro Cloud 类型检查通过。原 ChatKit 接管导航的 7 个文件已撤回，暂存区为空；本次不需要为导航新增 ChatKit 配置或发布版本。
+
+### 分批审核回归（2026-10-17）
+
+补齐卡片切换的请求过期保护：默认列表的迟到响应不能覆盖后来选择的 Artifact，切换目标同时关闭原看板的分享和发布弹窗，防止操作对象混淆。重复相同目标的初始化仍保留本地编辑。技能中的标准看板更新示例不再要求 HTML 文件路径。
+
+本轮 Live Dashboard 54 项测试、Workspace Script 18 项测试、两个插件的生命周期与生产前端 Workbench 浏览器回归通过；新增覆盖来源身份/内容摘要校验、迟到响应和弹窗清理。构建及资源一致性检查使用本地平台配套 SDK；本轮未重新部署或重复真实 Agent/SSO 验收，以上历史记录保留各自验证范围。

package/docs/docs.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "maple",
+  "name": "Live Dashboard",
+  "colors": {
+    "primary": "#0f766e",
+    "light": "#14b8a6",
+    "dark": "#115e59"
+  },
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "文档",
+        "groups": [
+          {
+            "group": "接入与验证",
+            "pages": [
+              "index",
+              "html-mode",
+              "frontend-libraries",
+              "frontend-libraries-acceptance",
+              "drafts",
+              "drafts-acceptance",
+              "team-sharing",
+              "team-sharing-acceptance",
+              "chat-resource-cards",
+              "editing",
+              "file-authoring",
+              "file-authoring-acceptance",
+              "file-datasets-acceptance",
+              "evolution-acceptance",
+              "retry-regression-acceptance",
+              "fixed-build-multimodel-acceptance",
+              "verification"
+            ]
+          },
+          {
+            "group": "历史验收",
+            "pages": [
+              "acceptance",
+              "agent-acceptance",
+              "html-acceptance"
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}

package/docs/drafts-acceptance.mdx

@@ -0,0 +1,42 @@
+---
+title: 草稿与定稿验收（2026-10-17）
+---
+
+本次在 xpert-pro 与 data-xpert 的本地 SSO 环境实际部署验收，使用真实模型、已授权的数据源和 Workbench。测试使用独立验收 Artifact，未覆盖原有手工看板。
+
+## 实际对话和发布
+
+| 场景 | 观察结果 |
+| --- | --- |
+| 第一轮样式修改 | 打开现有工作草稿，读取 HTML，写入页面后自动保存为 r2；仍无正式版本 |
+| 同一会话继续修改 | 读取 r2，将柱形图改为折线图并修改标题，自动保存 r3；Artifact ID 不变，正式版本数仍为 0 |
+| 服务重启与草稿重开 | 重新进入 SSO Workbench，恢复 r3、ECharts 页面、数据绑定和筛选 |
+| 取消定稿 | 打开发布对话框后取消，正式版本数保持 0 |
+| 第一次人工定稿 | 在 data-xpert Workbench 确认 r3，产生 v1；重复同一发布请求返回相同版本 |
+| 已发布后继续修改 | Agent 读取当前看板并保存 r4，Workbench 自动切换到草稿预览；正式历史仍只有 v1 |
+| 第二次人工定稿 | 在 xpert-pro 界面检查旧版和 r4，再确认发布 v2；两边重开均显示同一 v2，v1 定义保持不变 |
+
+模型的完成回复报告实际草稿修订号，并说明尚未发布。另一个真实失败用例中，模型把文件路径错误地传成 `.html`；没有拿到保存回执，执行被明确判定失败，未生成虚假的正式版本。随后增加了已打开页面写入时的自动保存，以及可定位的路径错误提示，重新完成上述成功流程。
+
+## 数据与边界
+
+ECharts 看板使用独立的 PostgreSQL 业务 fixture：全部净销售额 5700、华东 3500、华西 2200。实际切换区域与刷新验证正确。临时将华西七月数据增加 100，刷新观察到对应图表值由 800 变为 900；保留筛选和当前文档，随后恢复来源并再次验证。
+
+data-xpert 本体、Workspace Python 和 Workspace JavaScript 来源分别验证了草稿保存、继续修改、重开、Binding 保留以及重新查询；每份查询均返回 6 行，重复刷新产生不同执行 ID。这部分验证来源兼容性，不替代各来源历史业务语义验收。
+
+并发请求修改同一草稿时，一个提交成功、另一个返回冲突；正式版本数不变。过期修订查询、过期修订发布、缺少人工确认字段的发布、替换原始查询载荷均被拒绝。HTML 内的未声明 Binding、父页面访问和直接网络请求被拒绝。
+
+## 自动检查
+
+- 平台 SDK 构建、服务端 TypeScript 检查通过。
+- SDK 提交回执并发顺序测试通过。
+- 插件 26 项测试通过，覆盖预检、隔离、回执、跨轮编辑、自动保存与正式版本历史。
+- 生产前端构建的浏览器夹具 12 项检查通过，覆盖草稿保存、取消/确认发布、筛选、刷新、回执打开、历史、助理选择上下文、隔离、搜索选择和重开。
+- plugin-dev-harness 加载、初始化和关闭通过。
+
+私有运行上下文、账号、Artifact/执行 ID、模型完整输出和截图留在本地验收记录，不纳入插件发行包。
+
+
+## 后续流程调整（2026-10-17）
+
+上文保留当时的验收经过。文件工具统一后的当前流程是：写入或编辑 HTML 文件后，Agent 显式调用 `dashboard_create_html` / `dashboard_update` 自动保存草稿，并取得对应文件字节的成功回执；文件写入本身不触发 Artifact 保存。人工发布仍是独立步骤。本次分批代码审查没有重新部署或重复 SSO 验收。

package/docs/drafts.mdx

@@ -0,0 +1,35 @@
+---
+title: 草稿与正式版本
+---
+
+## 使用方式
+
+Agent 的创建和修改现在保存为工作草稿。同一个 Artifact 跨多轮保留身份；每次保存增加 `draftRevision`，Workbench 根据成功回执打开草稿预览。关闭页面或重启平台后可重新打开。
+
+修改现有 HTML 时，Agent 先调用 `dashboard_open`，获得独立编辑副本的 `htmlPath` 和当前修订信息，再使用平台 SandboxFile 读取及编辑。每批修改完成后，Agent 自动调用 `dashboard_update` 保存工作草稿，无需人工确认。文件编辑本身不保存看板；只有带有 `status: draft`、`artifactId`、`draftRevision` 的领域回执证明草稿已保存。HTML 保存还返回实际消费文件的 `sourceFile.path/sha256`，用于核对保存内容。打开新的编辑副本不会覆盖此前未保存的文件。
+
+Workbench 的版本菜单区分工作草稿和正式版本。点击“发布草稿”后显示确认对话框，确认的修订才会形成新的正式版本。取消没有写入副作用。正式版本保持不可变，后续 Agent 修改继续保存到草稿。生成页面的筛选和刷新只重新查询数据，不会保存或发布版本。
+
+## 平台与插件的职责
+
+平台提供 `platform.artifact-drafts`：草稿持久化、Workspace 文件校验、批量元数据读取、并发检查和发布事务。新增 `artifact_draft` 表，每个 Artifact 一个当前草稿；`revision`、`baseVersionId`、`publishedRevision`、`publishedVersionId` 与内容引用分别记录编辑和发布状态。发布事务与其他 Artifact 版本写入共用 Artifact 行锁，并记录确认用户和时间。
+
+平台 SDK 的 `createMutationEvidence` 提供通用的待保存操作与提交回执跟踪。插件决定哪些工具属于看板修改、什么回执表示成功；没有保存回执时必须继续工具调用，无法保存时报告失败。Workspace 文件写成功不会被当作看板保存成功。
+
+看板插件负责 Dataset/Binding、HTML 包和依赖快照、数据及浏览器预检、工具说明、草稿预览和发布确认界面。Agent 没有发布工具。
+
+## 并发和查询边界
+
+`dashboard_open` 返回稳定 Artifact ID，以及 `expectedRevision` 和 `expectedCurrentVersionId`。修改以读取时的两个值为基准，不接受自动覆盖；发生冲突需重新读取并合并。自动保存也保留这两个基准。
+
+确认对话框冻结用户正在确认的修订。期间草稿变化会导致发布冲突，不会悄悄发布另一份内容。重复发布同一个已确认修订不会产生多余版本。
+
+页面查询只发送 Artifact 身份、草稿修订号或正式版本 ID、Binding ID 和声明过的筛选值。后端读取已保存的定义并重新检查当前访问权。原始 SQL、数据源替换、任意 Binding 或新增筛选字段仍被拒绝；HTML 沙箱仍禁止直接网络请求和父页面访问。
+
+## 兼容性和范围
+
+历史正式版本无需转换，仍可查看。第一次编辑建立工作草稿，已有 Artifact ID 保持不变。前端图库版本与字节仍随看板内容固定。
+
+当前保存的是最新工作草稿，草稿修订号用于并发控制；可浏览历史的是人工发布的正式版本。草稿修订历史、多人协同分支和自动合并不在本次范围内。
+
+使用外部数据库迁移的部署须先执行平台的 `artifacts/drafts/migrations/20261017-artifact-drafts.sql`，并使用包含新 runtime capability 的平台 SDK 与服务端。

package/docs/editing.mdx

@@ -0,0 +1,63 @@
+---
+title: "持续修改与版本历史"
+description: "Agent 在同一 Artifact 上修改页面或数据配置，保留不可变版本与并发保护。"
+---
+
+## 使用流程
+
+在 Workbench 打开看板后，可直接要求 Assistant“把这个看板改成浅色，保留数据口径”。
+视图通过平台 `assistant.context.set` 发布 `live_dashboard` 上下文，包含协议版本、Artifact ID，以及当前草稿修订号或正式版本 ID。
+这些标识仅用于定位；后端仍检查当前用户、组织和 Assistant／Project 归属。
+
+Agent 的编辑流程如下：
+
+1. `dashboard_open` 读取当前选中或明确指定的看板，获得稳定的 `editId`（Artifact ID）、`expectedRevision` 和 `expectedCurrentVersionId`。
+2. HTML 看板通过 `sandbox_read_file` 读取 `dashboard_open` 准备的 `htmlPath` 副本，再使用 `sandbox_edit_file` / `sandbox_multi_edit_file` 修改；随后显式调用 `dashboard_update` 校验并保存工作草稿。
+3. 其他字段或路径通过 `dashboard_update` 保存，传入稳定 `editId`、读取时的两个并发基准以及实际修改字段。Agent 始终保存草稿，人工确认后才发布正式版本。
+
+未选中看板时，Agent 使用 `dashboard_list` 查找并明确目标，不根据最近更新时间猜测。
+`dashboard_history` 返回可读版本，Workbench 的“版本历史”也可打开指定版本。
+读取、打开和筛选不会创建新版本。
+
+## 页面修改与数据修改
+
+更新工具只允许修改标题、控件、标准图表／表格、HTML 路径及预览回执。
+Artifact ID、定义 ID和原始 Binding 不能由变更字段覆盖；两个预期值只用于并发校验。
+
+- 只改样式时省略 `previewIds`，后端保留原 Binding；未提供的其他字段也保持原值。
+- 修改来源、指标或查询时，重新发现并预览数据，提交完整目标 Binding 集合的成功 `previewIds`，同时调整匹配的控件和页面字段。
+- 所有保存，包括样式修改和重复请求，都重新验证当前数据访问、声明筛选和 HTML 初始页面。
+
+Agent 新建或更换 Binding 时，若控件默认值为 `null`、且同名输出字段是维度，必须先用
+`dashboard_test_filter` 验证一个实际存在的非空选项。例如 `controls: {region: "华东"}`
+配合 `expectations: [{fieldId: "region", oneOf: ["华东"]}]`，检查返回行没有混入其他区域。
+空结果、截断结果、失败检查或旧 Binding 的检查不能取得保存凭证。
+此检查不推断任意业务口径；范围、搜索、不同名字段等语义仍需按来源契约单独验证。
+
+HTML 页面仍然只通过 `query(bindingId, controls)` 取数。增加编辑工具不会让页面获得原始查询、身份或宿主操作权限。
+
+## 版本与冲突
+
+`editId` 是稳定的 Artifact ID，可以跨轮使用。每轮应先读取最新工作草稿，保存时同时检查草稿修订号和正式版本基准。
+其他编辑或发布已经改变基准时，旧修改返回冲突，要求重新读取和处理差异，不自动覆盖或另建作品。
+自动保存不会创建正式版本；人工发布相同修订的重试不会产生重复正式版本。
+同一次 Agent 运行再次创建同名看板、但内容不同时，会要求改用 `dashboard_open` 和
+`dashboard_update`；避免自动纠错在保存后另建一个同名作品。
+
+更新成功的工具回执携带 Artifact、草稿修订号和 `status: draft`，Workbench 打开草稿预览并同步 Assistant 上下文。发布确认会冻结被确认的修订，期间发生变化则拒绝发布。
+旧版本保留原 HTML、控件和 Binding；打开旧版本仍会查询当前有权访问的最新来源数据。
+版本历史保存的是看板定义，不是历史查询结果快照。
+
+## 分层边界
+
+平台继续负责 Workspace Files、Artifacts 版本与授权、上下文消息桥和 HTML 隔离。
+看板选择上下文、编辑工具、数据预览回执及展示规则归 Live Dashboard 插件所有。
+数据源插件保持原来的 Dataset/Binding 接口，无需实现页面编辑或版本接口。
+
+完整生命周期与平台职责见[草稿与正式版本](drafts)，本次实际验证见[草稿验收](drafts-acceptance)。
+
+## SandboxFile 编辑流程
+
+读取插件随附的 `live-dashboard` 技能后，Agent 使用 `dashboard_open` 返回的独立 HTML 副本：先 `sandbox_read_file`，再 `sandbox_edit_file` / `sandbox_multi_edit_file`。修改文件不会自动保存 Artifact。每批完成后调用 `dashboard_update`，同时传入 `editId`、`expectedRevision`、`expectedCurrentVersionId`、`htmlPath` 和需要改变的标题等字段。保存通过 HTML/数据预检后返回草稿回执并更新 Workbench。冲突时保留文件，重新打开最新状态进行合并。
+
+历史版本只读，不准备编辑副本。新建 HTML 使用 `sandbox_write_file({file_path,content})` 后调用 `dashboard_create_html`。`sandbox_write_file` 仅创建新文件；已有文件使用编辑工具。脚本数据处理使用同一套平台文件工具，然后由脚本插件注册 Dataset。

package/docs/evolution-acceptance.mdx

@@ -0,0 +1,98 @@
+---
+title: "HTML 看板持续修改验收"
+description: "2026-10-16：真实 SSO、模型生成、三类来源、同一 Artifact 的版本演进与查询边界。"
+---
+
+## 范围和证据
+
+本轮在本地 Xpert Pro 与 data-xpert SSO Workbench 中部署并运行当前源码，
+使用已配置的模型，通过真实 ChatKit 输入自然语言请求。
+Provider 覆盖 PostgreSQL、本体查询和 Workspace 脚本；脚本分别验证 Python 读取 CSV、
+JavaScript 读取声明的 PostgreSQL Binding。
+私有执行记录、包部署回执和浏览器截图保留在验收环境，不提交凭据或环境身份信息。
+
+## 业务 oracle
+
+指标为 2026 年第三季度已支付订单的实付金额减退款，单位为人民币元，按月、区域聚合。
+固定预期如下；它们来自验收订单定义，不从被测查询响应反推。
+
+| 月份 | 华东 | 华西 |
+| --- | ---: | ---: |
+| 2026-07 | 1,000 | 800 |
+| 2026-08 | 1,500 | 900 |
+| 2026-09 | 1,000 | 500 |
+| 合计 | 3,500 | 2,200 |
+
+刷新测试临时修改一条订单的实付金额，期望对应月份增加 100，再恢复原值。
+CSV 生成复验额外加入上一年度同月订单与同月同区域订单，
+随后把当月 1,000 拆成 900 与 100 两笔，检查页面汇总仍为 1,000，结束后恢复原始文件。
+Python Dataset 合法地保留订单明细，HTML 将完整明细汇总为趋势图；验收同时核对了明细和展示汇总，
+不要求所有数据源都预先返回同一种聚合粒度。
+
+## 修复的实际问题
+
+- **只有默认查询通过，筛选实际无效。** 第一轮 Python 脚本没有使用区域参数。
+  新增 `dashboard_test_filter`，对可空的同名维度控件要求真实非空筛选证据。
+  修复后的真实模型运行再次触发错误时，工具拒绝保存，Agent 自行重写脚本、重新注册和验证。
+  此门槛用于模型质量控制，不替代 Analytics 权限验证，也不推断任意范围或搜索语义。
+- **当前选择没有进入工具上下文。** data-xpert 原先只写入 request state。
+  通用 Workbench 桥现在同时提供 request context，保留原 state 行为；SSO 身份仍由既有认证层合并。
+  插件分别读取执行上下文与请求上下文中的选择，避免空执行上下文遮蔽请求。
+  回归前的误选测试版本保留在测试环境；修复后必须以空参数 `dashboard_open({})` 的实际目标验证。
+- **更新标题后列表仍显示旧名称。** 平台 Artifacts 增加可选的当前版本元数据批量读取，
+  保持原有分页和授权作用域。插件使用当前版本标题，不另建标题存储或逐条读取内容。
+- **保存后的自动纠错另建同名作品。** 同一运行中再次创建同名但不同内容的看板会被拒绝，
+  要求读取已返回的 Artifact 再更新；相同内容的重试仍保持幂等，不影响明确创建不同标题的作品。
+  此新增门槛通过工具级回归验证，真实持续修改另以选中作品后的更新回执验收。
+
+## 分层和持久化
+
+平台负责 Dataset/Binding、数据访问授权、Workspace、Sandbox、Artifacts 的不可变版本与 CAS，
+以及通用文档隔离。新增的版本元数据读取和明确的文档协议类型均同步至 Xpert Pro。
+
+Live Dashboard 插件负责看板定义、选择上下文、编辑回执、筛选验证、版本菜单与渲染接入。
+数据源插件继续只负责发现和执行，未引入页面样式、看板版本或 Workbench 状态。
+data-xpert 只修复通用上下文桥，不包含看板专用字段或逻辑。
+
+历史版本保存原 HTML、控件和 Binding，打开历史版本时仍查询当前可访问的最新来源数据。
+这里的刷新是用户触发的重新查询，没有新增定时轮询、CDC 或服务端推送。
+
+## 验收结果
+
+| 数据路径 | 页面生成 | 持续修改 | 保存身份 |
+| --- | --- | --- | --- |
+| PostgreSQL 直接查询 | 浅色销售分析 | 墨蓝指挥屏，v1 → v2 | Artifact ID、Binding 保持不变 |
+| data-xpert 本体查询 | 深色经营驾驶舱 | 浅色财务报表，v1 → v2 | Artifact ID、Binding 保持不变 |
+| Python + CSV | 暖色文件分析 | 深绿色驾驶舱，v1 → v2 | Artifact ID、脚本版本 Binding 保持不变 |
+| JavaScript + PostgreSQL | 蓝白运营分析 | 黑金经营简报，当前 v3 | Artifact ID、脚本版本 Binding 保持不变 |
+
+四次修改均在真实 Workbench 选中作品后，以不包含 ID 的自然语言提出。
+成功执行的首个 `dashboard_open` 参数均为 `{}`，随后 `dashboard_update` 返回原 Artifact 的新版本。
+JavaScript 案例保留了上下文回归测试阶段的 v2，因此最终为 v3。
+实际界面在更新工具完成后自动打开新标题和精确版本，无需刷新宿主页面。
+
+上述四条路径的生成版与改版均完成浏览器区域筛选、源数据变化后的刷新、原值恢复和保存重开。
+刷新时保留筛选与同一个 HTML 文档实例，明细及 KPI 随真实来源金额变化；未发生页面重载。
+
+跨版本接口检查覆盖 4 个案例、9 个版本、54 次成功查询／刷新和 54 次拒绝请求。
+所有版本的全部／华东／华西结果均匹配独立 oracle，刷新产生新的执行记录；
+修改前捕获的原始定义摘要不变，样式更新保留原 Binding。
+传入 SQL payload、替换 Provider、替代 Binding、替换数据源均被拒绝，
+未知 Binding 返回 403，未声明控件返回 400。
+
+平台 API 重启后，四份看板均从真实 SSO 页面重新打开；版本菜单分别切到初始版本和当前版本，
+每次都展示对应页面及 6 条正常业务数据。版本总数、精确版本 ID、列表标题与持久化回执一致。
+所有临时 PostgreSQL 金额和 CSV 内容均已恢复；失败及重复测试作品归档保留。
+
+## 本地回归与运行范围
+
+- Live Dashboard 构建、类型检查和 25 项工具／领域测试通过。
+- 平台文档协议 5 项测试、Artifact 当前版本元数据 2 项测试通过，Core 与 Pro SDK 均构建成功。
+- data-xpert 通用上下文桥 4 项测试和 Web TypeScript 构建通过。
+- 生产远程 bundle 的 Workbench 浏览器回归包含 9 项检查；HTML 后台预检包含 3 项检查。
+- 通用文档宿主的 25 项真实 Chromium 检查覆盖 CSP、来源校验、隔离、请求重放、并发／速率限制、销毁与重挂载、类型化筛选等。
+- 原有三个数据源插件的测试通过：PostgreSQL 11 项、本体 16 项、Workspace 脚本 17 项；
+  Live Dashboard 的原生插件生命周期加载与关闭通过。
+
+这是当前本地测试环境的验收，不等同于线上发布或多租户压力测试。
+没有新增数据库表、看板专属平台数据源分支、共享发布、定时任务或后台推送。

package/docs/file-authoring-acceptance.mdx

@@ -0,0 +1,62 @@
+---
+title: 统一文件流程验收
+---
+
+## 2026-10-17 验收范围
+
+本次验证移除插件重复文件工具后，Agent 通过平台 SandboxFile 编写脚本和页面，再分别注册 Dataset、保存看板草稿。流程配置见[文件编辑与 Agent 技能](./file-authoring)。插件技能随包分发，通过平台资源安装接口安装到测试 Assistant 的 Workspace，并在已发布 Agent 的 `skillsMiddleware` 中选择。
+
+运行环境为本地 xpert-pro 与 data-xpert SSO，使用已配置的真实 Qwen 模型和默认 Docker 沙箱。代码改动同步到 xpert-pro；插件完成构建、部署及进程重启后再执行验收。凭据、会话信息、原始回执和截图仅保留在本地验收记录中。
+
+## 实际执行结果
+
+| 场景 | 结果 |
+| --- | --- |
+| PostgreSQL 经 Python 处理 | Agent 用 `sandbox_write_file` 创建脚本，成功调用 `workspace_dataset_register`，通过真实预览得到按月份、区域汇总的六行结果；最终 Provider 为 `workspace_script.query`。 |
+| 一句话生成 | 对已注册的 Python Dataset 发出自然语言请求。Agent 实际读取技能及参考资料，使用 `sandbox_write_file` 编写 HTML，调用 `dashboard_create_html` 保存 ECharts 看板为工作草稿修订 1。 |
+| 跨轮修改 | 要求修改标题、配色及筛选后的趋势系列。Agent 调用 `dashboard_open`，用 `sandbox_read_file` 读取独立编辑副本，用 `sandbox_multi_edit_file` 局部修改，然后成功保存页面和标题，最终草稿修订为 3。 |
+| 身份与保存回执 | 保持同一个 Artifact 和草稿 ID；页面保存回执的文件 SHA-256 与后端实际保存的 HTML 一致；没有创建正式版本。 |
+| 数据与依赖 | 修改前后的 Bindings、controls 和依赖快照完全一致；运行的 ECharts 版本为 5.6.0。 |
+| 两端筛选 | xpert-pro 与 data-xpert 页面均验证全部区域 5,700 元、华东 3,500 元、华西 2,200 元；趋势图系列及数据与所选区域一致。 |
+| 两端刷新及重开 | Header 刷新实际发起 Binding 后端查询，保留当前过滤值和 HTML DOM；整页重开加载最新标题及草稿，按已保存默认值显示全部区域。正常加载无查询错误。 |
+| 查询边界 | HTML 查询未声明 Binding、直接访问父页面和自行发起网络请求均被拒绝；后端拒绝附带任意 SQL payload 的 Binding 查询。 |
+
+本次没有发布上述测试草稿；人工确认发布的回归由 Workbench 浏览器用例覆盖，历史人工发布验收见原有记录。
+
+## 发现与处理
+
+- 可选中间件未启用会导致文件工具不在 Agent 的运行工具集中。部署指引明确将此流程依赖的中间件设为 `required`，并使用实际机器标识 `skillsMiddleware`。
+- 默认沙箱 Provider 在获取沙箱时才确定。平台现按实际 Provider 重新解析工作区映射，使通用文件工具与插件 WorkspaceFiles 使用一致路径；不绕过路径和 Volume 授权。
+- 初次模型生成省略了筛选默认值。Agent 创建接口现要求显式 `defaultValue`，包含表示全部的 `null`；页面预检返回明确的初始筛选不匹配原因。旧存储格式保持兼容。
+- 首个生成页面在过滤后仍保留 ECharts 旧系列。真实交互验收发现后，通过同一 Artifact 的后续编辑修复；技能已补充系列替换规则及完整筛选验证步骤。
+- 上游 SQL 预览曾误拒绝合法的带括号 WHERE 表达式，模型调整等价写法后通过。该既有 SQL 校验行为未在本次改动中调整。
+
+验收分别证明了真实脚本注册、基于已注册 Dataset 的一句话生成，以及后续修改和两端交互。最初的 PostgreSQL → Python → HTML 单轮尝试未完整通过，因此本记录不将它计为端到端单轮成功，也不将提示词指导视为任意生成页面的正确性保证。
+
+## 自动化验证
+
+- 平台共享文件协议 2 项、SandboxFile 4 项、Agent 调用与默认 Provider 映射 17 项测试通过。
+- Live Dashboard 29 项、Workspace Script Dataset 18 项测试通过，共计 70 项。
+- 页面预检浏览器 7 项、Workbench 浏览器 12 项通过；覆盖 ECharts/Three.js、声明式查询、草稿、发布确认、筛选、刷新和重开。
+- 两个插件构建、产物校验和 dist-first 生命周期检查通过；技能格式校验及打包内容检查通过。
+
+这些自动化检查与上面的实际模型、已部署浏览器验收分开计数，避免将模拟覆盖误写为真实环境验收。
+
+## 2026-10-17 补验：完整单轮与两端闭环
+
+在上述修复已部署、技能已安装的环境中，新开会话，直接要求从 PostgreSQL 原始销售订单出发，经 Python 按月份和区域计算第三季度净销售额，生成浅色蓝金 ECharts HTML 看板，包含区域筛选和刷新。没有向 Agent 提供预制脚本、HTML、已注册 Dataset 或预期金额，也没有在生成过程中补充纠正指令。
+
+单轮执行成功，19 次工具调用全部成功：5 次实际技能/参考资料读取，完成业务发现、原始数据预览、Python 文件写入、新 Dataset 注册、脚本结果预览、筛选测试、HTML 文件写入和草稿保存。最终 Binding 为 `workspace_script.query`，代码通过声明的上游 PostgreSQL Binding 实时读取订单并使用 Decimal 聚合，没有嵌入静态业务数据。保存回执的 SHA-256 与后端实际保存的 HTML 一致。
+
+| 补验项目 | 实际结果 |
+| --- | --- |
+| 独立金额核算 | 直接查询测试源得到六行月度/区域汇总，总额 5,700 元，华东 3,500 元，华西 2,200 元；与 Agent 预览、页面 KPI 和 ECharts 系列一致。 |
+| 初次生成即可筛选 | 两端分别切换全部、华东、华西并刷新，图表只包含当前区域系列；首次生成使用 `notMerge: true`，没有旧系列残留。 |
+| 输入数据实际变化 | 临时加入一条 100 元的华西测试订单，两端刷新后均显示 2,300 元；删除测试订单后恢复 2,200 元。当前过滤值和 HTML DOM 保持不变。测试行已清理。 |
+| 从 data-xpert 继续修改 | 在 SSO 页面要求修改当前看板名称及墨绿色强调色。Agent 通过 `dashboard_open` → `sandbox_read_file` → `sandbox_multi_edit_file` → `dashboard_update` 保存页面和标题，最终为草稿修订 3。7 次工具调用全部成功。 |
+| 编辑保护 | 修改保持相同 Artifact 和草稿 ID；Bindings、controls、依赖快照未变；文件回执散列与最终保存内容一致；Agent 编辑期间正式版本数保持为零。 |
+| 修改后两端回归 | 重新验证全部/华东/华西金额、ECharts 系列、Header 刷新与整页重开，均通过。 |
+| UI 发布确认 | 针对此次新建的验收看板，点击发布后取消，正式版本仍为零；再次点击并确认发布，产生且仅产生正式版本 1。正式版本的页面、数据声明和依赖快照与已保存草稿完全相同。两端重开可见版本 1。 |
+| Binding 边界 | 初稿及修改稿均验证未声明 Binding、访问父页面、直接网络请求被拒绝；后端拒绝额外的原始 SQL payload。 |
+
+这次补验已覆盖首轮未完成的 PostgreSQL → Python → HTML 单轮流程。发布步骤由浏览器验收操作显式点击确认，Agent 本身只保存草稿。以上结论对应本次真实执行，不表示任意模型、数据源或页面均可免验收。

package/docs/file-authoring.mdx

@@ -0,0 +1,49 @@
+---
+title: 文件编辑与 Agent 技能
+---
+
+## 配置
+
+Assistant 启用 Sandbox，并连接 `SandboxFile`、`skillsMiddleware` 和 `LiveDashboard`。从 Live Dashboard 插件将 `live-dashboard` 技能安装到 Assistant 所在 Workspace，再在该 Agent 的 `skillsMiddleware` 中选择此技能；脚本数据处理同时连接 `WorkspaceScriptDataset` 并安装、选择其 `workspace-script-dataset` 技能。技能通过平台 `read_skill_file` 按需读取，不需要将整份文档粘贴到系统提示中。
+
+通过 API 配置时，调用 `POST /plugin/:name/resources/install-workspace`，请求体使用 `{"workspaceId":"<授权的 Workspace ID>","components":[{"componentType":"skill","componentKey":"live-dashboard"}]}`（脚本插件使用 `workspace-script-dataset`）。将返回安装记录的 `runtimeId` 加入 `skillsMiddleware.options.skills`，连接到同一 Agent，保存并发布 Assistant 草稿。当前平台的 `install-xpert` 仅处理 Hook，不能用于安装技能。无需修改数据库或复制文件到猜测的沙箱路径。
+
+该流程所依赖的中间件节点应设置 `entity.required: true`，尤其是 `SandboxFile`；否则可选插件未在当前会话启用时，Agent 无法调用其工具。技能中间件的机器标识是小写开头的 `skillsMiddleware`，不能用类名 `SkillsMiddleware`。发布后用新会话检查技能读取和文件工具的实际执行记录。
+
+两个原有写文件工具 `dashboard_write_html`、`workspace_dataset_write_file` 已移除；脚本文件读取同样由 `sandbox_read_file` 提供。已有 Assistant 需更新工具连接和技能安装；既有看板 Artifact 与正式版本无需迁移。
+
+## 职责
+
+平台 SandboxFile 提供创建、读取、局部修改、多处修改和追加。文件路径使用当前工作目录下的相对路径，创建工具参数为 `file_path`、`content`；创建不覆盖已有文件。平台校验字符串内容、未知字段、路径段和工作区边界，并声明通用文件修改元数据供插件识别修改意图。
+
+平台在获取沙箱后按实际 Provider 重新解析工作区映射，因此使用默认沙箱配置时，SandboxFile 与插件 WorkspaceFiles 也共享相同的目录语义。该处理复用已注册的 Provider Mapper，不写死容器或主机路径，不放宽 Volume 权限检查。
+
+脚本插件只负责注册、固定代码、输入输出契约和受控执行。看板插件负责数据及页面预检、草稿 CAS、Binding、依赖快照和发布。`present_files` 是文件交付能力，不能替代看板保存。
+
+## 看板编辑
+
+`dashboard_open` 对当前 HTML 准备一个新的可编辑副本，返回 `htmlPath` 和并发基准。副本使用独立路径，不覆盖其他未保存文件。Agent 读取并编辑后自动调用 `dashboard_update`；新建页面则使用 `dashboard_create_html`。完整保存成功后 Workbench 刷新并能重新打开草稿；正式发布仍由人工确认。
+
+看板文件名必须包含有效名称，拒绝 `.html`、前后空白和越界路径。保存回执包含 `sourceFile.path/sha256`，只有匹配 Artifact、文件内容和修改代次的回执才能解除该文件的待保存状态。保存其他看板、保存其他文件或在保存期间再次修改文件，都不能把未保存的修改标记为已保存。
+
+新建页面预检失败时，优先编辑原候选文件。若 Agent 明确改用另一份 HTML，可以在 `dashboard_create_html.supersedesPaths` 列出要放弃的旧候选路径；改用标准图表时由 `dashboard_create.supersedesPaths` 声明。只有新看板保存成功（HTML 还需实际文件摘要一致）时，才解除这些候选的待保存要求；文件仍保留在 Workspace，不能声称它们也被保存为看板。此参数只接受本轮未绑定 Artifact 且没有正在写入的候选，拒绝 `dashboard_open` 的编辑副本；保存期间产生的新修改也不会被清除。系统不根据文件名或标题猜测替代关系。
+
+## 验证
+
+自动化验证覆盖异常参数、编辑副本不覆盖、明确保存、错误回执隔离和现有查询边界。部署验收需要额外验证 Agent 实际读取技能、调用沙箱文件工具、创建/修改看板及重开；仅构建或模拟测试不能代替运行环境验收。
+
+2026-10-17 的真实模型与 xpert-pro / data-xpert SSO 验收结果见[统一文件流程验收](./file-authoring-acceptance)。
+
+## 减少可避免的重试
+
+- 新建独立看板使用未占用的文件路径；同名历史文件或 Artifact 不是转去编辑旧看板的授权。
+- 打开和读取只准备未修改副本，`editingFile.hasUnsavedChanges` 初始为 `false`。成功保存回执已经确认持久化，不能为验证上一次保存而再次提交未修改的副本。
+
+- Provider payload 在调用前按发现契约检查，字段格式错误应先修复，不能重复提交相同值。SDK 校验不代替授权与实际预览。
+- 预览的 `validation.checks` 提前列出需要执行的非默认筛选测试；建议参数来自实际样例，不能把建议当成测试成功。
+- 打开的 HTML 副本已存在，沿用 `editingFile.read` 读取，再使用编辑工具。批量编辑按顺序保存，失败后读取当前内容并只补剩余变更。
+- 沿用 `saveArguments` 的 Artifact ID、修订号和正式基准；无正式版本时使用 JSON `null`，不是字符串 `None`。标题和页面在同一次更新提交，修复错误参数时保留所有请求的变更。
+
+可复用的真实回归命令和独立数据口径位于 `tests/acceptance/README.md`。流程保留失败样本、工具错误、保存回执和源文件恢复证据，不要求所有模型都零重试。
+
+`dashboard_update` 的 Agent 工具要求显式 `title`；未改名时复制当前标题，改名与 HTML 修改应在同一次保存中提交。该约束属于看板编排，平台部分更新接口继续保持通用语义。