@wandox/payload-renderer

面向 React 应用的结构化内容渲染器，用于统一呈现 AI 输出中的 Markdown、表格、卡片、执行步骤、Mermaid 图表和 Dashboard。组件同时提供剧本按钮、动态参数表单与文件上传的宿主接入能力。

安装

npm install @wandox/payload-renderer

宿主项目需要提供 React、Ant Design 及其图标库，具体版本范围见兼容性。

快速开始

在应用入口导入组件样式，并将接口返回的 payload 直接传给组件：

import PayloadRenderer from '@wandox/payload-renderer'
import '@wandox/payload-renderer/style.css'

const payload = {
  type: 'card',
  content: '## 分析完成\n\n本次共识别 **12** 条有效记录。',
}

export function ResultPanel() {
  return <PayloadRenderer payload={payload} />
}

payload 接受字符串、基础类型、数组和结构化对象。对象数组与完整的 JSON 对象数组文本会自动渲染为表格；未知结构会提取 content、text、body、message 或 summary 字段，并按 Markdown 渲染。

支持的内容

| 输入 | 展示能力 | | --- | --- | | 字符串与普通对象 | Markdown、GFM 表格、链接、图片和代码块 | | 对象数组 / JSON 对象数组文本 | 自动推断列并渲染为表格 | | card / markdown | Markdown 内容、字段映射卡片或对象数组表格 | | table | 排序、分页、复杂字段展开、图片预览、CSV 与 PDF 导出 | | mermaid | 流程图、时序图、状态图等 Mermaid 图表 | | echarts / Markdown echarts 代码块 | 使用 ECharts option，支持 JSON 和常见对象字面量语法 | | dashboard | KPI、图表、表格、筛选器等 Dashboard 内容 | | step | 可折叠的执行步骤与嵌套输出 | | debug | 调试内容格式化展示 | | input_params | 输入参数与过滤条件快照 |

表格

const payload = {
  type: 'table',
  title: '商品表现',
  content: [
    { asin: 'B0ABC123', sales: 128, conversion_rate: '8.4%' },
    { asin: 'B0DEF456', sales: 96, conversion_rate: '7.1%' },
  ],
  fields_map: [
    { name: 'asin', label: 'ASIN' },
    { name: 'sales', label: '销量' },
    { name: 'conversion_rate', label: '转化率' },
  ],
}

<PayloadRenderer payload={payload} />

字段卡片

const payload = {
  type: 'card',
  title: '任务信息',
  content: {
    status: 'completed',
    duration: '18.6s',
  },
  fields_map: [
    { name: 'status', label: '状态' },
    { name: 'duration', label: '耗时' },
  ],
}

Mermaid

const payload = {
  type: 'mermaid',
  mermaid: `flowchart LR
    Input[输入] --> Analyze[分析]
    Analyze --> Result[结果]`,
}

Markdown 中的 mermaid 代码块也会自动转换为图表。

Chart

echarts 代码块的内容直接使用 ECharts option。前端支持严格 JSON，也支持 ECharts 示例常见的未加引号 key、单引号字符串及 option = {...}; 外壳。AI 可以按图表类型自由组合 series、dataset、tooltip、legend、dataZoom 等官方配置；鼠标悬停、图例筛选和缩放由 ECharts 原生处理。

```echarts
{
  "title": { "text": "近 7 日销售额" },
  "tooltip": { "trigger": "axis" },
  "xAxis": {
    "type": "category",
    "data": ["周一", "周二", "周三", "周四", "周五", "周六", "周日"]
  },
  "yAxis": { "type": "value" },
  "series": [{
    "name": "销售额",
    "type": "line",
    "smooth": true,
    "data": [120, 132, 101, 134, 90, 230, 210]
  }]
}
```

结构化输出也支持同一份配置：

const payload = {
  type: 'echarts',
  option: {
    tooltip: { trigger: 'item' },
    series: [{ type: 'pie', data: [{ name: '已完成', value: 80 }, { name: '待处理', value: 20 }] }],
  },
}

配置必须是对象，函数和变量引用不会执行。解析失败时页面显示错误信息和原始配置，消息中的其他内容继续正常渲染。

执行步骤

const payload = {
  type: 'step',
  title: '分析商品数据',
  status: 'done',
  input_params: [
    { key: 'marketplace', label: '站点', value: 'US' },
  ],
  children: [
    { type: 'card', content: '已处理 **128** 条记录。' },
  ],
}

剧本交互

Markdown 中可以包含 Wandox 剧本按钮。宿主应用通过 PlaybookContext 注入详情查询、参数补充、执行和上传能力：

import PayloadRenderer, {
  PlaybookContext,
  type PlaybookExecuteRequest,
} from '@wandox/payload-renderer'
import '@wandox/payload-renderer/style.css'

export function InteractiveResult({ payload }: { payload: unknown }) {
  const executePlaybook = (request: PlaybookExecuteRequest) => {
    return apiClient.post('/playbooks/execute', request)
  }

  return (
    <PlaybookContext.Provider
      value={{
        onExecutePlaybook: executePlaybook,
        getPlaybookDetail: async (playbookId) => {
          return apiClient.get(`/playbooks/${playbookId}`)
        },
        uploadFile: async (file) => {
          const body = new FormData()
          body.append('file', file)
          const result = await apiClient.post('/files', body)
          return { url: result.data.url }
        },
        auth: {
          accessToken,
          tenantId,
          domain,
        },
      }}
    >
      <PayloadRenderer payload={payload} />
    </PlaybookContext.Provider>
  )
}

推荐通过 uploadFile 适配器复用宿主项目的请求客户端、登录态、令牌刷新和错误处理。组件也支持通过 ossUploadUrl 使用内置上传请求，此时 auth 会生成相应的鉴权请求头。

PlaybookContext 的主要配置：

| 字段 | 类型 | 说明 | | --- | --- | --- | | onExecutePlaybook | (request) => void | 接收已完成参数归一化的剧本执行请求 | | onFillPlaybookParams | (playbook) => void | 将参数填写流程交给宿主应用处理 | | getPlaybookDetail | (id) => Promise<response> | 获取剧本定义和动态参数 | | uploadFile | (file, auth) => Promise<result> | 自定义文件上传适配器，返回 URL 或 { url } | | ossUploadUrl | string | 内置文件上传请求地址 | | auth | PayloadRendererAuth | 包含 accessToken、tenantId、domain 或自定义 headers |

组件 API

PayloadRenderer

| 属性 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | payload | unknown | 是 | 待渲染的内容 | | className | string | 否 | 根容器类名 | | style | React.CSSProperties | 否 | 根容器行内样式 | | errorFallback | ReactNode \| ((error) => ReactNode) | 否 | 渲染异常时的替代内容 | | onError | (error, info) => void | 否 | 渲染异常回调 |

<PayloadRenderer
  payload={payload}
  className="report-output"
  errorFallback={(error) => <ResultError message={error.message} />}
  onError={(error) => logger.captureException(error)}
/>

公共导出

包提供以下扩展入口及其 TypeScript 类型：

| 导出 | 用途 | | --- | --- | | PayloadRendererContent | 在自定义容器中使用纯渲染逻辑 | | DashboardRenderer | 单独渲染 Dashboard 数据 | | ProposalRenderer | 渲染方案选择和动态参数表单 | | ActionTableRenderer | 渲染带单项或批量动作的表格 | | HoverImagePreview | 图片链接悬浮预览 | | InputParamsRenderer | 输入参数快照 | | PayloadErrorBoundary | 独立使用渲染错误边界 | | buildPayloadRequestHeaders | 根据鉴权上下文生成请求头 | | normalizePayloadAuth | 归一化鉴权配置 |

完整类型定义可直接从包入口导入，例如 TablePayload、CardPayload、MermaidPayload、EChartsPayload、StepPayload、PlaybookContextType 和 DashboardData。

样式定制

组件根节点使用 .wandox-payload-renderer。业务项目可以通过 className 建立作用域，并在包样式之后加载覆盖规则：

<PayloadRenderer className="order-analysis" payload={payload} />

.order-analysis {
  font-size: 14px;
  color: #1f2329;
}

兼容性

• React 18.x 或 19.x
• React DOM 18.x 或 19.x
• Ant Design 5.25+ 或 6.x
• @ant-design/icons 5.6+ 或 6.x
• Node.js 18+
• ESM 构建环境，例如 Vite、Webpack 5 或 Rspack