---
title: AI 助手
source: https://vjmap.com/guide/visual/ai.html
---

---
group: AI 与发布
description: 用编辑器里的 AI 助手一句话搭大屏、针对选中组件修改、截图标注提问，以及在 Cursor、Claude Code 等外部 AI 工具里通过 MCP 使用可视化平台。
---

# AI 助手

编辑器右下角的「AI」按钮打开 AI 助手。它能看懂当前页面，也能直接动手改：一句话从空白页搭出整块大屏，选中一个组件让它单独调整，或者截一张图圈出问题让它修。AI 的每次改动都在编辑器里实时生效，可以撤销，也可以接着手工精修。

本篇用一个「智慧园区能耗监控大屏」演示完整用法，最后介绍怎样在 Cursor、Claude Code 等外部 AI 工具里接入可视化平台。

## 打开 AI 助手

在编辑器里点右下角紫色的「AI」按钮（可以拖动换位置），打开「AI 助手」窗口。窗口标题下面是当前工程的名称，AI 只操作这个工程。

![AI 助手窗口](./images/ai-panel.webp)

1. **窗口按钮**：从左到右是「会话列表」「新会话」「桥接设置」「放大」「最小化」「关闭」。对话开始后，最左边还会多一个「运行记录」。窗口可以拖动、拉大小，「放大」让它居中铺满，再点一次还原。
2. **推荐问题**：新会话里给出几个常用问法，点一下就发送，如「这个页面有哪些组件？」「创建一个高科技大屏」。
3. **输入框**：写下要求，`Enter` 发送，`Shift+Enter` 换行。
4. **附件按钮**：「添加图片」上传参考图（如设计稿、别人的大屏截图），「截图并标注」截取当前大屏后在图上圈画，「展开输入框」写长段要求。
5. **模型**：显示本次会话使用的模型，点开可以换。会话的模型在第一次发言时定下来，中途换模型要点「新会话」。
6. **发送**：AI 工作时变成红色的停止按钮，点它可以随时中断。

::: tip 提示
AI 生成的内容仅供参考，改完记得看一眼画布。输入框右下的百分比是当前会话占用的上下文，对话很长时会自动压缩；换一个话题时，点「新会话」效果更好，以前的对话在「会话列表」里能找回。
:::

## 一句话搭一块大屏

1. 在首页点「+ 新建」，选「固定大屏」，工程名填「文档示例·AI 搭大屏」，点「创建」。
2. 打开 AI 助手，在输入框写下要求，越具体越好：要哪些区域、放什么图表、什么风格。本例是：

   > 帮我做一个智慧园区能耗监控大屏：顶部标题；左侧 3 个指标卡（今日用电、今日用水、碳排放）；中间一个近 7 天用电趋势折线图；右侧各楼栋能耗排行柱状图；底部一张设备告警表。深蓝科技风，先用演示数据。

3. 按 `Enter` 发送。AI 会先查阅组件说明，再写出整页、校验、应用到画布，最后截图检查效果。对话里每一步都是一张可展开的卡片：

![AI 搭建过程：每一步都能看到](./images/ai-steps.webp)

1. **工具卡片**：AI 每次动手都显示一张卡片，如「write_file」写出整页、「vp_validate_tsx」校验、「page_apply_project」应用到页面、「page_screenshot」截图查看效果。右边标着「完成」或「失败」，点开能看到具体内容。
2. **AI 的说明**：AI 会说明做了什么、截图里发现了什么问题、下一步打算怎么改。
3. **画布**：应用后大屏立刻出现在画布上，和手工搭的一样，可以继续拖动、改属性。
4. **图层**：AI 给每个组件起了中文名（如「今日用电面板」「近7天用电趋势」），并按面板分好组，方便在图层树里找。

本例 AI 用了大约 3 分钟搭出标题、3 个指标卡、折线图、柱状图和告警表，并把工程名改成了「智慧园区能耗监控」。

::: warning 注意
AI 每轮的步数有上限。要求很多时，它可能做完一部分就停下（最后一张卡片停在「失败」或没有总结）。这时看一眼画布，直接用一句话告诉它还差什么，例如「底部告警表还是空的，请补上演示数据」，它会接着做。
:::

## 接着对话，逐步修改

第一轮做完后，告警表还没有数据，表头也是英文字段名。接着发一句：

> 底部告警表还是空的：请新建一张 6 行的演示数据表，字段直接用中文（时间、设备、位置、类型、等级、状态），绑定到告警表。

AI 新建了一个数据连接、填好 6 条告警，并绑定到表格，表头随之变成中文。约 1 分半后，大屏变成这样：

![AI 搭好的智慧园区能耗监控大屏](./images/ai-result.webp)

1. **指标卡**：今日用电、今日用水、碳排放，数字和单位分开设置字号与颜色。
2. **近 7 天用电趋势**：平滑折线加渐变面积。
3. **各楼栋能耗排行**：横向柱状图，按数值排序。
4. **设备告警**：6 行演示数据，列名是中文。

AI 建的数据连接和手工建的一样，可以在「数据 → 编辑数据」里查看、改成接口数据，做法见[数据接入](./data.html)。

::: tip 小技巧
- 描述要求时，说清楚「区域 + 组件 + 风格 + 数据」，比「做一个好看的大屏」有效得多。
- 想让 AI 参考现成样式，可以用「添加图片」上传一张截图，再写「照这个风格做」。
- 也可以只问不改，例如「这个页面有哪些组件？」「告警表的数据从哪来？」。
:::

## 选中组件，「拖给 AI」

只想改某一个组件时，先让 AI 知道是哪一个，回答会更准、也更快：

1. 在画布或图层里选中组件（本例是「近7天用电趋势」折线图）。
2. AI 助手打开时，组件上方的选区工具栏里会多出「拖给AI」按钮。按住它拖到 AI 输入框里松开，输入框上方出现一枚组件标签。
3. 在标签后面写要求，如「把这个折线图换成青绿色，并在数据点上显示数值」，按 `Enter` 发送。

![把选中的组件拖给 AI](./images/ai-drag.webp)

1. **选中的组件**：画布上带虚线框和手柄的折线图。
2. **拖给AI**：选区工具栏里的按钮，只有 AI 助手打开时才出现。按住拖到输入框。
3. **组件标签**：显示组件名和类型，如「近7天用电趋势（chart-line）」，点右边的 × 可以去掉。
4. **要求**：针对这个组件写的修改要求。

这类小改动 AI 通常直接改属性，几十秒就完成：

![AI 只改了选中的折线图](./images/ai-edit-result.webp)

1. **修改结果**：折线变成青绿色，数据点上显示了数值。
2. **你的消息**：带着组件标签，AI 只处理这个组件。
3. **AI 的操作**：先「page_get_schemas」查这个组件有哪些可改的属性，再用「page_batch_set_options」一次改好。
4. **AI 的总结**：说明改了哪几项（折线颜色、显示数值）。
5. **撤销**：顶栏的撤销按钮（`Ctrl+Z`）。AI 的一次批量修改算一步，点一下就整体还原，再按恢复（`Ctrl+Y`）又回来。

## 截图并标注

有些问题用文字很难说清，比如「这里多了个东西」。可以截一张图、圈出来再问：

1. 点输入框下方的「截图并标注」（相机图标），平台截取当前大屏，打开「截图标注」窗口。
2. 选「矩形」「箭头」或「画笔」，挑一个颜色，在图上拖动画出要说的地方。
3. 点「添加到对话」，截图作为图片附件放进输入框，再写上要求发送。

![截图标注窗口](./images/ai-annotate.webp)

1. **标注工具**：「矩形」「箭头」「画笔」。图中用红色矩形圈出了折线图下方多余的「文本」两个字，再用箭头指过去。
2. **颜色**：红、橙、绿、蓝、紫、白、黑。
3. **撤销与清空**：撤掉上一笔，或清空全部标注重画。
4. **添加到对话**：把标好的截图放进输入框；旁边的「取消」放弃这次截图。

![截图附件和要求](./images/ai-attach.webp)

1. **截图附件**：点缩略图可以查看大图、重新编辑标注，点 × 去掉。
2. **要求**：说明截图里标的是什么、想怎么改。
3. **截图并标注**：随时可以再截一张。
4. **发送**：发送后 AI 对照截图，在页面里查找对应的组件再修改。

截图适合指出「哪里不对」，但 AI 仍要在页面里找到对应的组件才能改。如果圈出的内容不是一个独立组件，而是某个组件自带的一部分（比如本例的「文本」其实是「用电趋势面板」这个面板组件的标题文字），AI 可能找不准。这时在画布上点一下那个位置，看属性面板里选中的是哪个组件，再用「拖给AI」把它交给 AI，或者直接在属性面板里改掉。

## 撤销、保存与查看 AI 做了什么

- **撤销**：AI 的改动和手工改动在同一个撤销记录里，按 `Ctrl+Z` 或顶栏的撤销按钮还原。AI 整页重写后，紧接着撤销一次也能回到重写前。
- **保存**：AI 改完后一般不会自己保存（除非你让它保存），和手工编辑一样，满意了再点顶栏「保存」（`Ctrl+S`）存到服务器；不满意就撤销，或者不保存直接刷新页面放弃。保存与历史版本见[保存、发布与嵌入](./publish.html)。
- **AI 活动**：点 AI 窗口的「桥接设置」（齿轮图标），在下方「AI 活动」里按时间列出 AI 对页面做过的每个操作。鼠标悬停在某一条上，画布上会高亮它改动的组件。

![桥接设置与 AI 活动](./images/ai-bridge.webp)

1. **连接状态**：「桥已连接」表示 AI 与这个页面连上了，旁边是本页连接的编号；「关闭」收起这个面板。
2. **允许 AI 控制本页面**：取消勾选后，AI（包括外部 AI 工具）就不能再读取和操作这个页面。
3. **模型端点**：列出可用的模型，标「默认」的那一项是实际使用的；「+ 添加」可以填入自己的端点名、模型 id、OpenAI 兼容地址和 API Key。
4. **MCP 地址**：「工程」和「本页」两个地址，给外部 AI 工具用，见下一节。
5. **AI 活动**：AI 的操作记录，最新的在最上面，失败的操作标成红色。
6. **画布高亮**：悬停在「getElement table-alerts」上，画布上的告警表被框出并标上「AI」。

::: warning 注意
访客账号是大家共用的，不要在访客身份下添加自己的模型 API Key。私有化部署时，平台默认使用的模型由管理员配置，用户一般不用改。
:::

## 在 Cursor、Claude Code 里使用（MCP）

可视化平台提供 MCP 服务，Cursor、Claude Code、VS Code 等支持 MCP 的 AI 工具接上后，就能查组件和文档、取示例、校验工程文件，或者直接操作你在浏览器里打开的大屏。

### 查文档、生成工程：公共地址

公共地址是 `https://vjmap.com/server/vp/mcp`，不需要登录，提供这些工具：

| 工具 | 作用 |
|---|---|
| `search_widgets` | 按关键词找组件、地图图层、三维元素、组态图元 |
| `get_widget_metadata` | 取某个组件的全部属性、取值和数据字段 |
| `search_documentation` / `get_doc` | 检索、阅读平台文档 |
| `list_examples` / `get_example` | 列出、获取示例工程 |
| `validate_project` | 校验 AI 写出的工程 JSON 是否合法 |

在 Cursor 里，打开设置的 MCP 页，或编辑项目里的 `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "vjvp": {
      "url": "https://vjmap.com/server/vp/mcp"
    }
  }
}
```

在 Claude Code 里执行：

```bash
claude mcp add --transport http vjvp https://vjmap.com/server/vp/mcp
```

在 VS Code 里，编辑项目里的 `.vscode/mcp.json`：

```json
{
  "servers": {
    "vjvp": {
      "type": "http",
      "url": "https://vjmap.com/server/vp/mcp"
    }
  }
}
```

接好后可以这样问：「用唯杰 AI 可视化平台做一个水厂调度大屏的工程文件，先查组件属性，写完用 validate_project 校验」。生成的 `*.vpproj.json` 在首页「导入项目文件」导入就能打开，见[项目管理](./projects.html)。

### 直接改浏览器里的大屏：工程地址

想让外部 AI 直接操作正在编辑的大屏，在编辑器里打开 AI 窗口的「桥接设置」，复制「MCP 地址」里的「工程」地址（形如 `https://vjmap.com/server/vp/mcp/p/<工程ID>?token=<令牌>`），按上面的格式配到 AI 工具里。之后保持这个工程在浏览器里打开、「允许 AI 控制本页面」处于勾选状态，外部 AI 就能读取页面结构、截图、改属性、增删组件并保存，效果和内置 AI 助手一样，改动同样可以撤销。

- **工程**地址固定指向这个工程，同一个工程开了多个浏览器标签时，AI 会先列出会话让你选。
- **本页**地址只指向当前这个浏览器标签，标签关掉就失效。

::: warning 注意
工程地址里带着令牌，拿到地址的人就能修改这个工程，只配在自己的 AI 工具里，不要发给别人或写进公开仓库。
:::

::: tip 小技巧
做二次开发（把大屏嵌入自己的系统、用 SDK 推数据）时，可以再给 AI 工具装上唯杰的 Agent Skills：下载 https://vjmap.com/download/skills.zip ，其中的 `vjvp` 技能教 AI 正确使用可视化平台的 SDK 和工程格式。
:::

## 相关文档

- [新手入门](./quickstart.html)：不用 AI，手工搭一块销售看板，熟悉编辑器的基本操作。
- [编辑器界面](./editor.html)：选区工具栏、图层、属性面板等各区域的说明。
- [数据接入](./data.html)：把 AI 生成的演示数据换成接口、模拟或平台数据。
- [保存、发布与嵌入](./publish.html)：保存、历史版本、发布和嵌入到自己的系统。