Data Artifacts

Data Artifacts 是 OpenClaw Native Plugin，用已审阅的结构化 rows 生成可验证、只读、 平台无关的静态产物。

Tools

• artifact_create_table
• artifact_create_chart
• artifact_create_dashboard
• artifact_create_report

每个 Tool 都要求小写 snake_case name 和非空 title。单数据集输入还要求精确 source.sql 和有界 rows。Tool 从可信运行时上下文读取 conversationId，并为每次调用 生成一个全局唯一、时间可排序的 ULID。

artifact_create_report 在单结果场景继续接受 source/rows。多结果报告使用具名 datasets 和 primary_dataset；summary/section 通过 evidence 绑定数据集，chart、table、 metrics 也显式选择数据集。具名数据集既可传内联 source/rows，也可传 SQL Tool 返回的 精确 artifact.datasetRef；后一种方式由 Plugin 校验证据摘要并加载存储中的精确 SQL 和 rows。结构化 summary 应传对象；运行时也会兼容模型误传的 JSON 字符串。Plugin 校验输入结构、引用关系和可渲染性，但不会根据 rows 猜测并拦截 title、 summary、intro、section、caveat 或 data-quality summary 中的数值语义。叙述内容按调用方 提供的文本原样保留。

Headline Metric 优先绑定粒度与指标直接一致的结果；多行数据只有在行粒度已知且聚合语义 成立时才显式使用 sum、avg 等聚合。Plugin 返回实际 computedMetrics，供最终回答引用， 但不会仅根据行数删除合法的 Metric 卡片或强制 Agent 额外执行一条 SQL。

确定性 QA 会在成功结果中返回 qa.repairs[]、qa.warnings[] 和 qa.wouldBlock[]。 安全修复只覆盖不改变数据语义的展示问题，例如唯一字段大小写匹配、横向 Bar 轴规范化、 MaxCompute \\N 空值、序列化边界两侧值完全相同的 Fact 过滤类型，以及非 Bar 图表 误带的 Bar-only 展示选项。密集 leaderboard 会在保留完整证据 DataSet 的同时投影为确定性 Top 8，完全重复 series 也会被去重。字段不存在或数值字段不可绘制时，Tool 返回 ok=false、稳定 errorCode、JSON path、有界 candidates、suggestedPatch 和 repairable=true，由 Agent 最多修正一次；Plugin 不会替 Agent 猜选有歧义的字段。 路径、会话归属、DataSet Digest/行数、证据完整性、敏感字段和 payload 上限错误继续硬失败。 artifact_create_chart 和 artifact_create_report 都可直接绑定 maxquery_sql_execute 返回的 verified datasetRef；Plugin 会读取并校验证据 envelope，避免模型复制或重塑 rows。 被标记为 truncated 的 DataSet 返回 repairable=false、recoveryKind=refresh_dataset，且同一 截断 SQL 不能通过改成 inline rows 绕过完整性门禁。

Report 还可选择性声明 analysis_requirements，并在结构化 summary、ordered block 或 legacy section/chart/table 上用 analysis_ids 标记其覆盖的分析要求。启用后，成功结果额外返回 qa.coverage：declared 保留 requirement 的 id、可选 title 和期望 evidence，covered / missing 给出覆盖闭环，bindings 列出每个结论、metric、chart、table 的输入路径、分析 id 和实际 evidence DataSet。声明了期望 evidence 时，同 analysis id 的 blocks 必须合计覆盖 全部已声明 evidence 才计入 covered；否则仍列入 missing。以下问题只进入 qa.warnings[]，不会让 Tool 失败或改变 qa.wouldBlock：重复 requirement、未声明 analysis id、未覆盖 requirement、requirement 虽被引用但没有 evidence-compatible block、requirement evidence 与实际 block evidence 不相交， 以及 chart/table 左右没有语义相符的 Markdown 解释；双方都有 analysis_ids 时必须 id 相交，任一侧未标 id 时才回退到 evidence 相交。完全相同的 analysis_ids / requirement evidence 重复项可安全去重并记录 QA repair；同 id 但 title/evidence 不同的 requirement 只告警并以首个声明做覆盖核算，不声称 发生了语义安全修复。未提供这些 optional 字段时，原有 Report 输入和输出行为保持兼容。

Chart 和 Table 的非空 title 仍由既有 Report contract 确定性保证；Plugin 不根据措辞做 “标题强弱”等主观判断，也不会根据这些 QA warning 新增 repair/complete Tool。

对于仍有歧义、无法安全自动修复的字段错误，Plugin 返回结构化错误但不注册额外恢复 Tool。 Agent 最多对同一个 create Tool 修正一次，只能根据 path、candidates 和 suggestedPatch 修改被识别的标量字段，并保持 DataSet、Facts、叙述数值和分析契约不变。

输出

artifacts/<conversationId>/<artifactId>.dataset.json
artifacts/<conversationId>/<artifactId>.html
artifacts/<conversationId>/<artifactId>.svg

artifact_create_chart 输出独立 SVG（format=svg, mimeType=image/svg+xml），便于主屏 直接内嵌预览；table、dashboard、report 输出自包含 HTML。

conversationId 通常原样作为目录名；路径分隔符、空格和非 ASCII 字符会做稳定的 UTF-8 percent encoding，避免目录穿越且保持可逆关联。

每个 Artifact 只有一个文件，不按 type 分目录。DataSet 使用紧凑 JSON 保存一次列名和 有序 row arrays，并在同一文件中绑定 SQL、rows 和执行元数据。返回结果包含 ULID、workspace-relative path、bytes、SHA-256 和 verified=true。文件以排他方式原子 创建，并在返回前 read-back 校验；重复名称不会覆盖旧 Artifact。

Renderer

生成文件只包含 semantic HTML、内嵌 CSS 和/或 SVG：

• 含图表的 Report/Dashboard HTML 只允许 renderer 内置的 maxquery-chart-interaction-v2 runtime；源码、版本和 SHA-256 固定，并由 CSP 与持久化前的 canonical re-render byte comparison 双重校验；
• 交互是 progressive enhancement：无脚本时仍保留完整静态图；若高密度 Mark 的交互元数据 会使产物超过既有字节上限，renderer 自动保留视觉内容并降级为静态输出，而不是让 Tool 失败；
• 无图表 HTML 和 standalone SVG 保持无 JavaScript；所有格式均禁止远程资源、网络请求、 存储、导航、动态代码和宿主平台 API；
• 不引用 window.openai 或任何模型厂商；
• 所有不可信文本均 HTML escape；
• 使用系统 sans-serif/monospace 字体栈，不下载或打包字体；
• 不嵌入第三方设计系统、图标库或第三方 chart runtime；
• 可通过 file://、WebView、img/object 或静态服务器展示。

Runtime id 和 hash 一经发布即不可原地修改；后续交互源码变化必须发布新的 runtime id， 由 Reader 显式维护兼容 allowlist。standalone SVG 永远不携带 script。

同一 dashboard 或 report 会在 renderer 内自动建立 artifact 级分类颜色映射。使用相同 分类字段的图表共享稳定的 category-to-color 关系，不受各图表数据行顺序影响；heatmap、 funnel 和 waterfall 继续使用各自的连续色阶或正负语义色。color 输入仍表示分组字段， 不接受调用方传入任意 CSS 色值。

测试

从仓库根目录运行：

OPENCLAW_DIR="$HOME/study/openclaw" ./scripts/test_native_plugins.sh

License

本目录原创源代码使用 Apache License 2.0。生成产物不携带第三方运行时代码。