nao 图表可视化深入解析：在聊天中生成、分享可交互数据故事的完整指南-育师

【免费下载链接】nao

👾 nao is an open source analytics agent. (1) Create context with nao-core cli, (2) deploy nao chat interface for everyone

项目地址：https://gitcode.com/gh_mirrors/nao4/nao

点击查看免费下载

nao 是一款开源分析智能体（Analytics Agent）：先用nao-coreCLI 为智能体构建数据上下文，再部署一个所有人可用的聊天界面。它最吸引人的能力之一，就是nao Stories 与图表可视化——你在聊天里问一句“帮我看看近 90 天的收入趋势”，智能体不仅回答，还会直接生成可交互图表，并把多个图表、表格和文字组合成一份可分享、可下载、可离线打开的数据故事（Story）。本文带你完整拆解这套能力的实现原理与使用方法。

为什么要在聊天中生成数据故事？

传统 BI 工具的痛点很典型：分析师写好仪表盘，业务同学要等排期；换个问题，又要重新建模。nao 的思路是把「问数」和「呈现」合并在同一个聊天会话里完成：

自然语言提问→ 智能体生成并执行 SQL；
结果自动变成图表→ 柱状图、折线、KPI 卡片等 15 种内置可视化，即问即得；
图表升级为故事→ 多个图表 + 表格 + 叙述文本，组合成一份完整的数据报告；
一键分享→ 生成链接、嵌入页面，或导出 PDF / HTML 离线文件。

对业务用户来说，这意味着不需要学会任何仪表盘工具，就能把一次聊天对话沉淀为可复用的数据分析成果。📊

一键生成：在聊天中创建交互式图表

当智能体回答数据问题时，内部会调用display_chart工具把查询结果渲染成图表。该工具的参数定义在 apps/shared/src/tools/display-chart.ts 中，几个值得了解的设计：

15 种内置图表类型：柱状、堆叠柱状（含百分比）、横向条形、折线、面积图、混合图、饼图、环形图、KPI 卡片、散点图、雷达图等，完整清单见 apps/shared/src/chart-types.ts；
数值格式化：支持货币前缀（$、€、¥）、百分号后缀、K/B 等紧凑单位，KPI 卡片还能展示环比变化；
条件格式：可对表格单元格按阈值或色阶着色，异常值一眼可见；
双轴混合图：同一图表里柱子表示金额、折线表示比率，适配量级差异大的指标对比。

生成的图表都是可交互的：悬停查看 tooltip 明细、切换系列、缩放坐标轴，而不是一张静态图片。

深入解析 Stories：classic 与 custom 两种格式

故事是 nao 的「可视化容器」。故事工具的输入输出 schema 定义在 apps/shared/src/tools/story.ts，它支持create / update / replace / publish / revert等操作，且每个故事都有版本管理——改坏了可以回滚到任意历史版本。

classic 格式：Markdown + 图表块

默认的经典故事是「Markdown 里的组件化文档」，智能体只需写出少量声明式块即可：

<chart query_id="..." />：嵌入一次查询结果的图表；
<table query_id="..." />：嵌入 SQL 结果表格；
<grid widths="2,1">...</grid>：把 2~4 个图表/表格并排布局，支持不等宽列；
<tab title="...">...</tab>：标签页式分区，把一份报告拆成多个视图。

比如一句“做一个收入仪表盘”的提示，智能体会自行决定用 KPI 卡片展示总额、用grid并排两张趋势图、再配一段文字结论，结构化的报告就此成形。

custom 格式：用 React 写故事应用

对于更复杂的交互需求，故事还可以是源代码级的 React 应用，文件放在/stories/<id>/下，从 story-kit starter 应用（nao.json、app.jsx、app.css）起步。可用的组件库定义在 apps/frontend/src/story-runtime/story-kit/ 中，包括：

组件	用途
`KpiCard`	带环比变化胶囊的核心指标卡
`LineChart`/`BarChart`/`Chart`	折线、柱状及通用图表
`DataTable`	可排序的查询结果表
`Narrative`	自动生成的数据叙述文本
`Slides`/`Slide`	幻灯片式分页展示
`PointMap`/`MapTiles`	基于 Leaflet 的地图可视化

出于安全考虑，custom 故事只允许导入白名单内的模块（react、recharts、leaflet、@nao/story-kit等），白名单定义在 apps/shared/src/story-app.ts，编译不通过的版本不会被发布，错误会直接反馈给智能体继续修复。

分享与导出：把数据故事发给团队

故事做好后，nao 提供了三条分享路径：

分享链接：前端路由 apps/frontend/src/routes/_sidebar-layout.stories.shared.$shareId.tsx 支持将故事分享给同组织成员，也有独立的 embed 路由embed.story.$storyId.tsx供嵌入外部页面；
下载导出：后端路由/story/:storyId/download（见 apps/backend/src/routes/embed-story-download.ts）支持pdf与html两种格式（格式定义见 apps/shared/src/types.ts）；
离线 HTML 故事：导出的 HTML 由 apps/shared/src/story-document.ts 构建——故事运行时、代码包和查询数据全部内嵌进文件，并附带严格的 CSP 安全策略。断网打开依然有 tooltip、翻页等完整交互，适合在邮件或会议中直接传递。

此外，live类型的故事（服务见 apps/backend/src/services/live-story.ts）支持按调度自动刷新数据，让仪表盘始终保持最新。