---
pkg: "@nocobase/plugin-ai"
title: "Viz CRM 场景配置指南"
description: "以 CRM 为例配置 Viz 洞察分析师：Overall Analytics 模板化分析引擎、SQL Execution 特化分析、data_analysis 模板表、安全与最佳实践。"
keywords: "Viz,CRM,Overall Analytics,SQL Execution,数据分析,NocoBase"
---

# AI 员工 · Viz：CRM 场景配置指南

> 以 CRM 示例为例，了解如何让你的 AI 洞察分析师真正理解业务、发挥全部潜力。

## 1. 前言：让 Viz 从"看数据"到"懂业务"

在 NocoBase 系统中，**Viz** 是预置的 AI 洞察分析师。
他能识别页面上下文（如 Leads、Opportunities、Accounts），生成趋势图、漏斗图和 KPI 卡。
但默认情况下，他只具备最基础的查询能力：

| 工具                      | 功能说明    | 安全性  |
| ----------------------- | ------- | ---- |
| Get Collection Names    | 获取数据表列表 | ✅ 安全 |
| Get Collection Metadata | 获取字段结构  | ✅ 安全 |

这些工具只让 Viz "认识结构"，还无法真正"理解内容"。
要让他生成洞察、发现异常、分析趋势，你需要为他**扩展更合适的分析工具**。

在官方 CRM Demo 中，我们使用了两种方式：

* **Overall Analytics（通用分析引擎）**：模板化、安全的可复用方案；
* **SQL Execution（特化分析引擎）**：自由度更高，但风险更大。

这两者并不是唯一的选项，它们更像一种**设计范式**：

> 你可以照着它的原理，做出更适合自己业务的实现。

---

## 2. Viz 的结构：稳定人格 + 灵活任务

要理解如何扩展 Viz，先要理解他内部是分层设计的：

| 层级       | 说明                              | 示例    |
| -------- | ------------------------------- | ----- |
| **角色定义** | Viz 的人格与分析方法：理解 → 查询 → 分析 → 可视化 | 固定不变  |
| **任务定义** | 针对某个业务场景的定制提示词和工具组合             | 可修改   |
| **工具配置** | Viz 调用外部数据源或工作流的桥梁              | 可自由替换 |

这样的分层设计，使 Viz 能保持稳定个性（分析逻辑一致），
同时又能快速适配不同业务场景（CRM、医院管理、渠道分析、生产运营……）。

---

## 3. 模式一：模板化分析引擎（推荐）

### 3.1 原理概述

**Overall Analytics** 是 CRM Demo 中的核心分析引擎。
它通过一张 **数据分析模板表（data_analysis）** 管理所有 SQL 查询。
Viz 不直接写 SQL，而是**调用已定义的模板**来生成结果。

运行流程如下：

```mermaid
flowchart TD
    A[Viz 接收任务] --> B[调用 Overall Analytics 工作流]
    B --> C[根据当前页面/任务匹配模板]
    C --> D[执行模板 SQL (只读)]
    D --> E[返回数据结果]
    E --> F[Viz 生成图表 + 简要解读]
```

这样，Viz 就能在几秒内生成安全、标准化的分析结果，
而管理员能统一管理和审查所有 SQL 模板。

---

### 3.2 模板表结构（data_analysis）

| 字段名                                               | 类型       | 说明            | 示例                                                 |
| ------------------------------------------------- | -------- | ------------- | -------------------------------------------------- |
| **id**                                            | Integer  | 主键            | 1                                                  |
| **name**                                          | Text     | 分析模板名称        | Leads Data Analysis                                |
| **collection**                                    | Text     | 对应数据表         | Lead                                               |
| **sql**                                           | Code     | 分析 SQL 语句（只读） | `SELECT stage, COUNT(*) FROM leads GROUP BY stage` |
| **description**                                   | Markdown | 模板说明或口径       | "按阶段统计线索数量"                                        |
| **createdAt / createdBy / updatedAt / updatedBy** | 系统字段     | 审计信息          | 自动生成                                               |

#### CRM Demo 中的模板示例

| Name                             | Collection  | Description |
| -------------------------------- | ----------- | ----------- |
| Account Data Analysis            | Account     | 账户数据分析      |
| Contact Data Analysis            | Contact     | 联系人分析       |
| Leads Data Analysis              | Lead        | 线索趋势分析      |
| Opportunity Data Analysis        | Opportunity | 商机阶段漏斗      |
| Task Data Analysis               | Todo Tasks  | 待办任务状态统计    |
| Users (Sales Reps) Data Analysis | Users       | 销售代表绩效对比    |

---

### 3.3 这种模式的优势

| 维度       | 优势                     |
| -------- | ---------------------- |
| **安全性**  | 所有 SQL 都存储并审核，避免直接生成查询 |
| **可维护性** | 模板集中管理，统一更新            |
| **复用性**  | 同一模板可被多个任务复用           |
| **可移植性** | 可轻松迁移到其他系统，只需同样的表结构    |
| **用户体验** | 业务用户无需关心 SQL，只需发起分析请求  |

> 📘 这张 `data_analysis` 表并不是必须叫这个名字。
> 关键是：**把分析逻辑模板化存储**，由工作流统一调用。

---

### 3.4 如何让 Viz 使用它

在任务定义中，可以明确告诉 Viz：

```markdown
Hi Viz，

请分析当前模块的数据。

**优先使用：** Overall Analytics 工具，从模板表中获取分析结果。
**若未找到匹配模板：** 说明缺少模板，并建议管理员补充。

输出要求：
- 每个结果独立生成图表；
- 图表下方附 2–3 句简要说明；
- 不编造数据或假设。
```

这样，Viz 会自动调用工作流，从模板表中匹配最合适的 SQL 并出图。

---

## 4. 模式二：特化型 SQL 执行器（慎用）

### 4.1 适用场景

当你需要探索性分析、临时查询、或多表 JOIN 聚合时，可以让 Viz 调用一个 **SQL Execution** 工具。

这个工具的特点：

* Viz 可以直接生成 `SELECT` 查询；
* 系统执行后返回结果；
* Viz 负责分析与可视化。

示例任务：

> "请分析近90天内各地区的线索转化率变化趋势。"

在这种情况下，Viz 可能会生成：

```sql
SELECT region, COUNT(id) AS leads, SUM(converted)::float/COUNT(id) AS rate
FROM leads
WHERE created_at > now() - interval '90 day'
GROUP BY region;
```

---

### 4.2 风险与防护建议

| 风险点    | 防护策略            |
| ------ | --------------- |
| 生成写操作  | 强制限制为 `SELECT`  |
| 访问无关表  | 验证表名是否存在        |
| 大表性能风险 | 限制时间范围、LIMIT 条数 |
| 操作可追溯  | 开启查询日志与审计       |
| 用户权限控制 | 仅管理员可使用该工具      |

> 一般建议：
>
> * 普通用户只启用模板化分析（Overall Analytics）；
> * 管理员或高级分析师才可使用 SQL Execution。

---

## 5. 如果你想自己做一个"Overall Analytics"

下面是一个简单的通用思路，你完全可以复制到任何系统中（不依赖 NocoBase）：

### 步骤 1：设计模板表

表名随意（如 `analysis_templates`）。
只要包含字段：`name`、`sql`、`collection`、`description` 即可。

### 步骤 2：写一个"取模板→执行"的服务或工作流

逻辑：

1. 接收任务或页面上下文（如当前 collection）；
2. 匹配模板；
3. 执行模板 SQL（只读）；
4. 返回标准化数据结构（rows + fields）。

### 步骤 3：让 AI 调用这个接口

任务提示词可以这样写：

```
请先调用模板分析工具，如果模板中无匹配分析，再使用 SQL 执行器。
请确保所有查询为只读，并生成图表展示结果。
```

> 这样，你的 AI 员工系统就具备了和 CRM Demo 类似的分析能力，但完全独立、可自定义。

---

## 6. 最佳实践与设计建议

| 建议                     | 说明                                     |
| ---------------------- | -------------------------------------- |
| **优先模板化分析**            | 安全、稳定、可复用                              |
| **SQL Execution 仅作补充** | 仅限内部调试或临时查询                            |
| **一图一重点**              | 输出清晰，避免过度混杂                            |
| **模板命名清晰**             | 对应页面/业务域命名，例如 `Leads-Stage-Conversion` |
| **解释简洁明了**             | 每个图表配 2–3 句总结                          |
| **缺模板要说明**             | 告知用户"未找到对应模板"而非空白输出                    |

---

## 7. 从 CRM Demo 到你的场景

无论你做医院 CRM、生产制造、仓储物流还是教育招生，
只要你能回答以下三个问题，Viz 就能在你的系统中发挥价值：

| 问题             | 示例                  |
| -------------- | ------------------- |
| **1. 你想分析什么？** | 线索趋势 / 成交阶段 / 设备稼动率 |
| **2. 数据在哪？**   | 哪个表、哪些字段            |
| **3. 想怎么呈现？**  | 折线、漏斗、饼图、对比表        |

一旦你定义好这些内容，只需：

* 把分析逻辑写入模板表；
* 把任务提示词挂在页面上；
* Viz 就能"接管"你的报表分析。

---

## 8. 结语：把范式带走

"Overall Analytics" 和 "SQL Execution" 只是两种示例实现。
更重要的是它们背后的思想：

> **让 AI 员工理解你的业务逻辑，而不是只执行提示词。**

无论你用的是 NocoBase、私有系统，还是自己写的工作流，
你都可以复制这种结构：

* 模板集中；
* 工作流调用；
* 只读执行；
* AI 呈现。

这样，Viz 不再只是一个"能出图的 AI"，
而是一位懂你数据、懂你口径、懂你业务的真正分析师。
