# 图表与数据分析

在 [对话](/agent/chat) 中，助手可以通过隔离组件、流程图或数据图为你展示信息。当你向助手询问数据时，助手可以按照你的数据读权限运行分析查询（最多 200 行），并提供进入 [分析](/apps/analysis) 应用探索页的链接。聊天界面中没有单独的「指标卡」组件，关键大数字需要前往探索页或看板查看。

## 谁能用

- **在对话中查看图表**：组织内所有能使用助手的成员均可查看。
- **画隔离组件**：需要组织管理员未关闭「允许助手生成组件」设置（入口在「我的组织」→「Skill 与连接」）。此项默认开启。开启时显示「开：必要时画图。」；关闭时显示「关：只用文字和表格回答。」。
- **运行分析查询**：需要组织已安装 [分析](/apps/analysis) 应用，且你对对应的数据源具有读权限。
- **保存为图表与加入看板**：在「探索」页中执行「保存为图表」或「加入看板」，需要具备 [分析](/apps/analysis) 应用中的搭建权限。
- **定时任务与外部客户端限制**：定时任务和外部客户端没有操作屏幕，系统不会调用「画一个组件」。

## 怎么打开

- **在对话中发起提问**：在 [对话](/agent/chat) 界面直接向助手发送看数要求，例如：画一张本月到店趋势。
- **从图表下方入口进入**：当组织已安装 [分析](/apps/analysis) 应用且图表附带合格的查询时，数据图下方会显示「在分析中打开」与「加入看板」按钮。
- **点击探索链接**：点击对话中的探索链接或点击「在分析中打开」，界面会在右侧打开「探索」页（链接不会自动打开，需要你手动点击）。
- **点击加入看板**：点击数据图下方的「加入看板」，系统会打开同一探索地址，并附带自动弹出对话框的标记（该标记只生效一次）。
- **管理员设置入口**：组织管理员在左侧进入「我的组织」，依次进入「Skill 与连接」→「图表与组件」→「允许助手生成组件」。

## 界面一览

在对话与数据分析过程中，共有四条主要的画图通道，以及分析应用中的看板关注卡：

### 1. 隔离组件

在独立沙箱环境中运行的交互组件，无网络访问权限，读不到组织的数据：

| 元素 / 状态 | 界面原文 / 展示形式 | 说明 |
|---|---|---|
| 工具调用行 | 「画一个组件」 | 助手调用组件生成能力时的提示状态。 |
| 绘制中提示 | 「正在画」加上标题或「一个组件」，再接「…」 | 正在生成组件时的提示文案（有标题时标题会包在「」里）。 |
| 容器标题 | 「组件」 | 隔离容器的读屏与标识名称。 |
| 绘制失败 | 「这个组件没能显示：」+ 原因 | 组件加载失败时的提示文案与具体原因。 |
| 脚本错误 | 「组件里的脚本出错：」 | 组件内部执行脚本发生错误时的提示文案。 |
| 查看源码 | 「查看代码」 | 点击可展开并查看组件的代码内容。 |
| 下载源码 | 「保存为文件」 | 点击可将组件源码下载为 HTML 或 SVG 文件。 |
| 组件内按钮交互 | 点击组件内按钮 | 点击后会作为你本人的一条消息直接发送到对话中（需要真实点击，短时间内有发送次数限制）。 |

### 2. 流程图等（围栏代码）

通过围栏代码直接渲染的结构逻辑图：

![对话里画出的流程图](/shots/agent-chart-flow.webp)

图：对话里画出的流程图

1. 围栏图类型：「流程图」（还有时序图、状态图等）
2. 画出来的 SVG 图
3. 「查看代码」：展开原始图代码

| 元素 / 状态 | 界面原文 / 展示形式 | 说明 |
|---|---|---|
| 图表类型标识 | 「流程图」「时序图」「类图」「状态图」「实体关系图」「图表」「图」 | 根据代码声明的图表类型在卡片顶部展示。 |
| 绘制中提示 | 「正在画图」 | 正在生成与加载图表时的读屏提示。 |
| 查看源码 | 「查看代码」 | 点击可展开查看图表的原始代码。 |
| 绘制失败 | 「图表无法绘制：」+ 原因 | 绘制失败时退回显示代码块，并附带错误原因（如「图太大」「语法不对」「没有内容」等）。 |

> **提示**
>
> 系统要求助手主要使用流程图、状态图、时序图、类图与实体关系图解释业务逻辑；饼图、甘特图、用户旅程图与思维导图不在推荐之列。遇到数值数据时，助手会优先使用数据图。

### 3. 数据图

通过内联数据渲染的数据统计图表：

![对话里的数据图（内联数据）](/shots/agent-chart-data.webp)

图：对话里的数据图（内联数据）

1. 内联数据渲染的柱状图（禁止从网址拉数）
2. 卡片标题「图表」或「图表：……」
3. 「查看代码」：数据图没有「保存为文件」

| 元素 / 状态 | 界面原文 / 展示形式 | 说明 |
|---|---|---|
| 卡片标题 | 「图表」或「图表：……」 | 图表顶部标题（可附带具体图表名称）。 |
| 查看源码 | 「查看代码」 | 点击展开查看图表的规格配置数据。 |
| 外部跳转 | 「在分析中打开」「加入看板」 | 当图表规格合格且已安装 [分析](/apps/analysis) 应用时显示。 |
| 校验失败提示 | 「不是有效的 JSON」<br>「规格太大（超过 …… KB）」<br>「不支持图片标记」<br>「序列数据太长」<br>「不允许 ……（数据只能内联在 data.values 里）」<br>「数据行太多（…… 行，最多 ……）」 | 数据格式或规格不符合要求时的报错（如包含 url、href、customFormatTypes、loader 或 baseURL 等外部键名）。 |
| 渲染失败回落 | 「规格有误」或「渲染出错」 | 图表渲染失败时的降级提示。 |
| 加载器拦截 | 「不允许从地址加载数据」 | 尝试从外部网址加载数据时被安全机制拦截。 |

> **注意**
>
> 数据图严格禁止从外部网址拉取数据，数据只能内联在规格配置中。数据图下方仅提供「查看代码」，**没有**「保存为文件」按钮。

### 4. 分析查询与探索页

助手执行数据分析并跳转至 [分析](/apps/analysis) 应用深度探索的通道：

| 元素 / 区域 | 界面原文 / 展示形式 | 说明 |
|---|---|---|
| 工具调用行 | 「运行分析查询」 | 助手调用只读分析查询时的状态提示。 |
| 探索链接 | 探索页对象链接 | 查询结果中附带的配置链接，点击在右侧打开「探索」页（不会自动打开）。 |
| 页面标题 | 「探索」 | 右侧分析探索面板的顶部标题。 |
| 顶部横幅 | 「来自对话的临时配置，尚未保存」 | 提醒当前图表为对话生成的草稿态配置。 |
| 保存图表 | 「保存为图表」 | 将临时配置保存为独立图表，保存成功提示「已保存为图表」。 |
| 加入看板 | 「加入看板」 | 弹出配置面板，将临时图表保存并放置到指定看板。 |
| 辅助操作 | 「复制链接」「恢复默认」「查看配置内容」「导出 CSV」 | 快捷操作工具项；导出 CSV 时的默认文件名为「探索结果」。 |
| 坏配置提示 | 「链接里的配置无法使用：」+ 原因 +「知道了」 | 链接中携带的配置损坏时弹出的提示与确认按钮。 |

#### 「加入看板」对话框

在探索页点击「加入看板」后弹出的设置面板：

| 字段 / 元素 | 界面原文 | 必填 | 说明 |
|---|---|---|---|
| 标题与说明 | 「加入看板」<br>「把这个临时配置保存为图表，并放到看板上。」 | — | 对话框顶部标题与功能说明。 |
| 图表名称 | 「图表名称」 | 是 | 填写图表保存后的名称；未填写点保存会提示「请填写图表名称」。 |
| 目标看板 | 「加入哪个看板」 | 是 | 选择目标看板。可选择已有看板，或选择「新建看板」。若无权限修改看板，提示「你还没有可以修改的看板，会新建一个只有你能看到的看板」。 |
| 新建看板 | 「新建看板」「新看板的名称」 | 条件必填 | 选择新建看板时需填写看板名称，默认名为「探索看板」；未填写会提示「请填写看板名称」。 |
| 可见范围 | 「图表谁能看到」 | 是 | 设置保存后图表的访问权限范围。 |
| 保存成功提示 | 「已保存为图表并加入看板「……」」 | — | 图表保存并成功放置到看板后的提示。 |
| 部分失败处理 | 「图表「……」已保存，但没能加入看板：……」 | — | 图表已保存但看板挂载失败时显示，附带「查看这张图表」与「重试加入」按钮。 |

### 5. 看板关注卡

在 [分析](/apps/analysis) 应用看板中展示的核心监控卡片（非聊天原生组件）：

| 元素 / 状态 | 界面原文 / 展示形式 | 说明 |
|---|---|---|
| 默认标题 | 「关注」 | 关注卡顶部的默认名称。 |
| 可视化类型 | 「数字」「指标卡」「排行条」 | [分析](/apps/analysis) 应用内的展示形式，「数字」表示单个关键数字。 |
| 语气标识 | 「风险」「向好」「提示」 | 用于屏幕阅读器及界面状态的重点语气标识。 |
| 审核脚注 | 「Agent 起草 · …… 审核于 ……」或「…… 编辑于 ……」 | 标明卡片由助手起草并经过指定成员审核，或由指定成员直接编辑。 |
| 数据刷新异常 | 「刷新失败，显示的是上一次的内容」 | 数据刷新遇到异常时的兜底提示。 |
| 缺失占位 | 「—」 | 无法取到数值时的占位符，鼠标悬浮提示「数字暂时取不到」。 |
| 草稿预览提示 | 「正在准备预览…」「这次会清空这张关注卡」「关注的条目」「这张图表暂时画不出来」 | 在草稿中预览关注卡时的各类状态与异常提示。 |
| 行数与数据源 | 「只画了前 …… 行（共 …… 行结果）」或「…… 行结果」<br>「数据源：」 | 标注实际展示的行数、总结果行数及底层数据源名称。 |

> **提示**
>
> 写关注卡必须走草稿流程（详见 [草稿：审阅与应用](/agent/drafts)），必须由你在草稿中审核并确认应用，助手无法预签或自动生效。卡片内部的对象链接在应用内直接打开，普通网页链接则在浏览器新标签页打开。

## 常用操作

### 在对话中生成图表

1. 在左侧导航点击 [对话](/agent/chat)，进入对话界面。
2. 在底部输入框说明要看的数据和图表类型（例如：画一张本月到店趋势），点击发送。
3. 在消息区域等待助手生成并展示图表：
   - 结构或逻辑解释：展示流程图、时序图、类图、状态图或实体关系图。
   - 统计数据展示：展示数据图（卡片顶部显示「图表」或「图表：……」）。
   - 复杂交互展示：当组织未关闭开关时，工具行显示「画一个组件」，随后渲染隔离组件。
4. 在图表底部按需查看源码：
   - 点击「查看代码」，展开查看生成的代码或规格内容。
   - 若为隔离组件，点击「保存为文件」，将组件源码下载为 HTML 或 SVG 文件。

### 将临时配置保存为独立图表

1. 在数据图下方点击「在分析中打开」，或在对话消息中点击探索链接，在右侧打开「探索」页（顶部显示横幅「来自对话的临时配置，尚未保存」）。
2. 在页面顶部点击「保存为图表」。
3. 系统将临时配置保存为独立图表，保存成功后提示「已保存为图表」。

### 将分析图表保存到看板

1. 在数据图下方点击「在分析中打开」，或在对话消息中点击探索链接，在右侧打开「探索」页（顶部显示横幅「来自对话的临时配置，尚未保存」）。
2. 在页面顶部点击「加入看板」，弹出「加入看板」对话框。对话框显示说明「把这个临时配置保存为图表，并放到看板上。」。
3. 在对话框中填写以下配置：
   | 字段 | 必填 | 说明 |
   |---|---|---|
   | 「图表名称」 | 是 | 输入保存后的图表名称。若未填写，系统提示「请填写图表名称」。 |
   | 「加入哪个看板」 | 是 | 选择目标看板。可选择已有看板，或选择「新建看板」。若你暂无可修改的看板，系统会提示「你还没有可以修改的看板，会新建一个只有你能看到的看板」。 |
   | 「新看板的名称」 | 条件必填 | 选择「新建看板」时需填写看板名称，默认名称为「探索看板」。若未填写，系统提示「请填写看板名称」。 |
   | 「图表谁能看到」 | 是 | 选择图表的可见范围。 |
4. 在对话框底部点击保存。保存成功后，系统提示「已保存为图表并加入看板「……」」。若图表保存成功但挂载看板失败，系统提示「图表「……」已保存，但没能加入看板：……」，此时可点击「查看这张图表」查看图表详情，或点击「重试加入」重新挂载。

### 导出分析查询数据

1. 在数据图下方点击「在分析中打开」或点击探索链接，在右侧打开「探索」页。
2. 在页面顶部工具栏点击「导出 CSV」。
3. 浏览器下载表格文件，文件名默认为「探索结果」。

### 调整与还原图表配置

1. 在数据图下方点击「在分析中打开」或点击探索链接，在右侧打开「探索」页。
2. 在页面顶部工具栏按需点击操作按钮：
   - 点击「复制链接」：复制当前探索页面的配置访问地址。
   - 点击「查看配置内容」：展开查看当前图表的原始配置内容。
   - 点击「恢复默认」：放弃临时调整，将配置还原为对话生成时的初始参数。

### 管理员配置组件生成开关

1. 组织管理员在左侧导航点击「我的组织」，进入组织管理界面。
2. 在页面导航中依次进入「Skill 与连接」→「图表与组件」。
3. 在页面中找到「允许助手生成组件」开关并调整：
   - 切换为开启：界面显示「开：必要时画图。」，允许助手在对话中调用「画一个组件」。
   - 切换为关闭：界面显示「关：只用文字和表格回答。」，助手停止生成隔离组件，仅使用文字和表格回答。

## 状态说明

### 配置流转与草稿生效

- **探索图表流转**：
  `对话中的临时配置（未保存） → 「保存为图表」/「加入看板」 → 已保存的图表 / 挂载到看板`
  在「探索」页中，临时配置顶部始终显示横幅「来自对话的临时配置，尚未保存」。坏配置会弹出「链接里的配置无法使用：」+ 原因 +「知道了」。保存成功后，系统提示「已保存为图表」或「已保存为图表并加入看板「……」」。
- **看板关注卡审核流转**：
  `助手起草关注卡草稿 → 人工在「Agent」草稿中审阅 → 应用生效（展示脚注「Agent 起草 · …… 审核于 ……」）`
  写关注卡必须走草稿流程，不能预签自动应用。若直接由人工编辑，脚注则展示「…… 编辑于 ……」。

### 校验与渲染状态对照表

| 状态阶段 | 界面提示 | 说明 |
|---|---|---|
| 组件生成中 | 「正在画」加上标题或「一个组件」，再接「…」 | 隔离组件处于绘制阶段。 |
| 组件渲染失败 | 「这个组件没能显示：」+ 原因 | 隔离组件由于格式或代码问题无法展示。 |
| 组件脚本异常 | 「组件里的脚本出错：」 | 组件在沙箱执行脚本时报错。 |
| 流程图生成中 | 「正在画图」 | 读屏提示，代码围栏图表绘制中。 |
| 流程图绘制失败 | 「图表无法绘制：」+（「图太大」/「语法不对」/「没有内容」等） | 围栏图表校验失败，退回代码块展示。 |
| 数据图规格超限或非法 | 「不是有效的 JSON」<br>「规格太大（超过 …… KB）」<br>「不支持图片标记」<br>「序列数据太长」<br>「不允许 ……（数据只能内联在 data.values 里）」<br>「数据行太多（…… 行，最多 ……）」 | 数据图规格在校验时被拒绝。 |
| 数据图渲染异常 | 「规格有误」或「渲染出错」 | 图表数据无法成功渲染。 |
| 数据源外链拒绝 | 「不允许从地址加载数据」 | 图表尝试加载外部网络地址时被安全机制拦截。 |
| 探索配置损坏 | 「链接里的配置无法使用：」+ 原因 +「知道了」 | 打开探索页时链接中的配置参数无法解析。 |
| 看板关注卡异常 | 「刷新失败，显示的是上一次的内容」<br>数字显示「—」（悬停提示「数字暂时取不到」） | 关注卡后台数据源无法刷新或取不到数值。 |
| 关注卡草稿预览状态 | 「正在准备预览…」<br>「这次会清空这张关注卡」<br>「关注的条目」<br>「这张图表暂时画不出来」 | 在草稿预览关注卡时的各类状态与异常提示。 |

## 让助手帮你做

你可以在 [对话](/agent/chat) 中向助手提出数据分析和图表绘制要求。例如：

> 画一张本月到店趋势。

> 用流程图展示新员工入职审批的流转过程。

> 用状态图梳理合同审批的状态变化。

> 帮我起草经营看板本周的关注卡内容。

> **提示**
>
> - **分析查询为只读**：助手调用「运行分析查询」只具有只读权限，单次查询结果最多返回 200 行数据，助手无法修改底层业务数据。
> - **操作权限分工**：助手可以运行查询并在对话中给出探索链接，但助手**不能自己打开探索页**、**不能自己保存图表**。所有图表的保存和加入看板动作必须由你手动操作完成。
> - **图表展示效果**：助手在分析查询中输出的画法参数只影响探索页面的渲染，不会在聊天气泡中自动变成 [分析](/apps/analysis) 应用的原生图表控件。
> - **关注卡必须人工审阅**：当助手起草看板「关注」卡时（例如「起草本周关注」），产出均为草稿，必须由你在 [草稿：审阅与应用](/agent/drafts) 中亲自审阅并点击应用，不支持预签自动应用。

## 设置

组织管理员可在后台调整组件生成功能：

| 设置项 | 入口路径 | 作用 | 默认值 | 谁能修改 | 状态文案 |
|---|---|---|---|---|---|
| 「允许助手生成组件」 | 「我的组织」→「Skill 与连接」→「图表与组件」 | 控制助手能否在对话中调用「画一个组件」 | 开 | 「我的组织」管理员 | 开：「开：必要时画图。」<br>关：「关：只用文字和表格回答。」 |

> **提示**
>
> 系统对组件运行环境的说明为：「组件在隔离环境运行，无网络，读不到你们的数据。」

## 注意事项

- **组件环境安全隔离**：隔离组件运行在独立的沙箱环境中，无网络访问权限，无法读取组织的数据。
- **数据图禁止外链数据**：数据图只许内联数据，禁止从网址拉数。规格中不得包含 url、href、customFormatTypes、loader 或 baseURL 等外部键名。
- **查询数据行数上限**：助手运行的分析查询最多返回 200 行结果；超过规格或行数上限时图表将无法绘制。
- **规格大小限制**：组件代码与图表规格均有大小上限，超出体积上限时系统不予绘制。
- **组件交互频率限制**：点击隔离组件内部的按钮会作为你本人的一条消息直接发送到对话中。必须为人工真实点击，且短时间内发送次数受到限制。
- **探索链接非自动弹出**：助手执行分析查询后给出的探索链接不会自动弹窗打开，必须由你手动点击跳转。
- **链接跳转行为**：关注卡内的对象链接在应用内打开，普通网页链接则在浏览器新标签页打开。
- **无看板权限时的默认处理**：若你在 [分析](/apps/analysis) 应用中尚无可以修改的看板，在点击「加入看板」时，系统会提示「你还没有可以修改的看板，会新建一个只有你能看到的看板」，并自动创建名为「探索看板」的新看板。

## 目前不支持

- **聊天原生指标卡**：对话聊天气泡中目前不支持原生的「指标卡」或「数字」组件；大数字与关键指标需前往「探索」页或看板查看。
- **数据图与流程图保存为文件**：数据图与流程图目前仅支持「查看代码」，不支持「保存为文件」（仅隔离组件支持「保存为文件」）。
- **图片格式下载**：隔离组件的「保存为文件」仅下载 HTML 或 SVG 源码文件，目前不支持导出或保存为 PNG 等光栅图片文件。
- **聊天提示图种范围有限**：对话中助手推荐使用的图表类型不包含 [分析](/apps/analysis) 应用中的「指标卡」和「排行条」（此类可视化图种仅存在于探索页与看板中）。

## 常见问题

### 为什么在对话消息中看不到大数字指标卡？

对话消息流中没有单独的原生「指标卡」组件。助手在回答数据问题时主要使用数据图、表格或文字。如果需要查看单个关键数字、「指标卡」或「排行条」，需要点击进入 [分析](/apps/analysis) 应用的「探索」页，或将图表保存到看板中查看。

### 为什么点击数据图下方的「在分析中打开」后，没有直接自动保存到看板？

点击「在分析中打开」或探索链接只会打开右侧的「探索」页，并显示横幅「来自对话的临时配置，尚未保存」。助手不能自己打开探索页，也不能自己保存图表。如果你需要将图表放到看板上，需要在探索页中手动点击「加入看板」对话框并确认。

### 为什么图表有时会显示「图表无法绘制：」或「这个组件没能显示：」？

这通常是因为图表内容或规格超出了系统限制。例如：流程图代码出现「图太大」「语法不对」或「没有内容」；数据图超出了体积限制（提示「规格太大」）、数据行数超限（提示「数据行太多」），或者尝试从外部地址拉取数据（提示「不允许从地址加载数据」）；隔离组件在沙箱中出错或脚本异常。你可以点击「查看代码」检查图表代码与配置。

### 为什么点击隔离组件里的按钮后，对话框自动以我的名义发出了消息？

这是隔离组件的交互机制。当你真实点击组件内部的按钮时，系统会将该操作作为你本人的一条消息发送到对话中。为防止频繁操作，系统对短时间内的连续点击发送次数进行了频率限制。

### 助手起草的看板「关注」卡为什么没有直接更新到看板上？

写关注卡必须走草稿流程。助手起草看板关注卡后，需要你在 [草稿：审阅与应用](/agent/drafts) 中亲自审阅并点击应用后才会正式生效，系统不支持预签自动应用。生效后卡片会显示脚注「Agent 起草 · …… 审核于 ……」。