@dmsfe/data-agent-sdk

面向 DMS Data Agent 的前端无框架 UI SDK：用于解析 Data Agent SSE 响应，并在任意前端技术栈（React、Vue、Svelte、Vanilla JS 等）中渲染 task_finish 图表。

状态：0.x 实验版本。 Minor 版本中 API 仍可能调整。变更记录见 CHANGES.md。

安装

pnpm add @dmsfe/data-agent-sdk
# 或 npm install / yarn add

# 如果使用 /render 子路径，需要同时安装：
pnpm add echarts

快速开始

import {
  parseDataAgentSSE,
  parseTaskFinishContent,
} from '@dmsfe/data-agent-sdk';
import { renderTaskFinishCharts } from '@dmsfe/data-agent-sdk/render';

const response = await fetch('/openapi/SendChatMessage', { /* ... */ });
const container = document.getElementById('charts')!;

for await (const event of parseDataAgentSSE(response.body!)) {
  if (event.type !== 'task_finish') continue;
  const parsed = parseTaskFinishContent(event.payload.content, event.payload.content_type);
  if (parsed.type === 'charts') {
    renderTaskFinishCharts(container, parsed.charts, { chartHeight: 320 });
  }
}

框架集成

React

import { useEffect, useMemo, useRef } from 'react';
import { parseTaskFinishContent, type TaskFinishToolArgs } from '@dmsfe/data-agent-sdk';
import { renderTaskFinishCharts, type ChartsInstance } from '@dmsfe/data-agent-sdk/render';

export function TaskFinishView({ payload }: { payload: TaskFinishToolArgs }) {
  const ref = useRef<HTMLDivElement>(null);
  const parsed = useMemo(
    () => parseTaskFinishContent(payload.content, payload.content_type),
    [payload.content, payload.content_type],
  );
  useEffect(() => {
    if (parsed.type !== 'charts' || !ref.current) return;
    const inst: ChartsInstance = renderTaskFinishCharts(ref.current, parsed.charts, {
      chartHeight: 320,
    });
    return () => inst.destroy();
  }, [parsed]);
  if (parsed.type === 'markdown') return <pre>{parsed.content}</pre>;
  return <div ref={ref} />;
}

Vue 3

<script setup lang="ts">
import { ref, computed, watchEffect, onBeforeUnmount } from 'vue';
import { parseTaskFinishContent, type TaskFinishToolArgs } from '@dmsfe/data-agent-sdk';
import { renderTaskFinishCharts, type ChartsInstance } from '@dmsfe/data-agent-sdk/render';

const props = defineProps<{ payload: TaskFinishToolArgs }>();
const parsed = computed(() => parseTaskFinishContent(props.payload.content, props.payload.content_type));
const el = ref<HTMLElement>();
let inst: ChartsInstance | undefined;

watchEffect(() => {
  inst?.destroy(); inst = undefined;
  if (parsed.value.type === 'charts' && el.value) {
    inst = renderTaskFinishCharts(el.value, parsed.value.charts, {
      chartHeight: 320,
    });
  }
});
onBeforeUnmount(() => inst?.destroy());
</script>
<template>
  <pre v-if="parsed.type === 'markdown'">{{ parsed.content }}</pre>
  <div v-else ref="el" />
</template>

Vanilla JS

参考上面的“快速开始”示例。

其他输入方式：parseDataAgentChunks

如果你的 HTTP 层已经把 SSE 响应解码成 JSON 对象，或者你手里有一组已捕获的日志对象，可以直接使用 parseDataAgentChunks，不需要再使用 parseDataAgentSSE：

import { parseDataAgentChunks } from '@dmsfe/data-agent-sdk';

const events = parseDataAgentChunks(myDecodedChunkArray);    // 同步数组输入，返回数组
// 或
for await (const e of parseDataAgentChunks(myAsyncIterable, { signal })) { /* ... */ }

独立渲染：renderTaskFinishChartData

用于测试、Storybook fixture，或回放已经解码好的结构化 payload：

import { renderTaskFinishChartData } from '@dmsfe/data-agent-sdk/render';

renderTaskFinishChartData(document.getElementById('chart')!, {
  title: 'Monthly Sales',
  chart_type: 'bar',
  data: { columns: ['m', 'v'], data: [['Jan', 10], ['Feb', 20]] },
});

使用单图渲染器（renderTaskFinishChart 或 renderTaskFinishChartData）时，需要在渲染前给目标容器设置非零高度：

<div id="chart" style="height: 320px"></div>

多图渲染器（renderTaskFinishCharts 和 renderTaskFinishChartsData）会为每张图创建一个子容器，默认每个子容器高度为 300px。可以通过 options.chartHeight 覆盖。

适用范围说明：该渲染入口面向 Data Agent 已解码的 payload。SDK 不是通用图表库；chart_type 枚举和字段推断规则都跟随 Data Agent 的 task_finish 协议。如果要渲染任意业务图表，建议直接使用 echarts。

API 参考

Layer 1：类型

• ChartType = string | null
• ChartData：{ columns: string[], data: (string|number|null)[][] }
• ContentType = 'str' | 'json' | undefined
• TaskFinishChart：wire 格式，data 字段是 JSON 字符串
• TaskFinishCharts = TaskFinishChart[]
• TaskFinishChartData：结构化格式，data 字段是 ChartData
• TaskFinishToolArgs：{ content: string, content_type? }
• DataAgentEvent = { type: 'task_finish'; payload } | { type: 'unknown'; raw }
• ParsedTaskFinishContent = { type: 'markdown'; content } | { type: 'charts'; charts }

Layer 2：解析器

• parseDataAgentSSE(stream, { signal? }) → AsyncIterable<DataAgentEvent>
• parseDataAgentChunks(chunks) → DataAgentEvent[]（数组重载）
• parseDataAgentChunks(iterable, { signal? }) → AsyncIterable<DataAgentEvent>
• parseTaskFinishContent(content, contentType?) → ParsedTaskFinishContent
• parseChartData(jsonString) → ChartData | null

Layer 3：渲染器（从 /render 子路径导入）

• renderTaskFinishChart(container, chart, options?) → ChartInstance
• renderTaskFinishCharts(container, charts, options?) → ChartsInstance
• renderTaskFinishChartData(container, input, options?) → RendererInstance<TaskFinishChartData>
• renderTaskFinishChartsData(container, inputs, options?) → RendererInstance<TaskFinishChartData[]>

渲染选项

interface TaskFinishRenderOptions {
  theme?: 'light' | 'dark';
  locale?: 'zh-CN' | 'en-US';
  chartHeight?: number | string;
  onUnknownChartType?: (chartType: string | null) => void;
}

| 选项 | 适用范围 | 默认值 | 说明 | |---|---|---|---| | theme | 所有渲染器 | 浏览器 / echarts 默认主题 | 预留给渲染器主题选择。 | | locale | 所有渲染器 | 根据浏览器语言自动判断 | 控制内置兜底文案，例如空数据提示。 | | chartHeight | 多图渲染器 | 300 | renderTaskFinishCharts / renderTaskFinishChartsData 创建的每个子图表容器高度。数字会按 px 处理；字符串会作为 CSS 高度值使用，例如 '24rem'。 | | onUnknownChartType | 所有渲染器 | undefined | 当 chart_type 为 null 或不支持的类型时触发。 |

图表类型

| chart_type | 渲染结果 | |---|---| | 'bar' | echarts 柱状图 | | 'line' | echarts 折线图 | | 'pie' | echarts 饼图 | | 'table' | 原生 HTML <table>，不创建 echarts 实例 | | 'number' | 原生 DOM 指标卡，不创建 echarts 实例 | | null 或其他值 | 不渲染图表，可通过 onUnknownChartType 回调感知 |

CSS 变量（主题）

可以在图表容器的任意祖先节点上覆盖以下 CSS 变量：

• --dmsfe-chart-category-1 到 --dmsfe-chart-category-12：分类色板，默认是阿里云蓝色系与辅助色
• --dmsfe-chart-sequential-1 到 --dmsfe-chart-sequential-8：连续色板，默认是品牌蓝色系

限制（Phase 1）

• 目前只有 task_finish SSE 事件会被解析成强类型；其他 category 会作为 { type: 'unknown', raw } 返回。
• 暂不提供 React/Vue 组件层，当前使用命令式 API。
• 暂不支持 notebook cell output、plan progress、mission report 等渲染器，这些会放到后续阶段。
• ParsedTaskFinishContent.type === 'markdown' 分支暂不提供内置 Markdown 渲染器。

路线图

• Phase 2：框架适配包、更多事件类型和渲染器（例如 output_conclusion Markdown 卡片、plan_update 进度可视化等），并完成与 apps/data-agent 的依赖反转。

License

Apache-2.0