> **本文回答**：AI 对话 / AI 绘 CAD / 地图 MCP 协议的 SDK 用法与集成方式。

# AI 能力

## 一、AI 对话（vjchat）

自然语言 → 检索知识库 → 大模型生成代码 → 前端执行并操作地图。

### 集成（HTML）

```html
<script src="https://vjmap.com/demo/js/vjmap/vjmap.min.js"></script>
<!-- 打开 map 之后 -->
<script>
(async () => {
  // 假设 map 已初始化
  window.vjmap = vjmap;        // vjchat 需要全局 vjmap

  if (typeof vjchat !== "object") {
    await vjmap.addScript([{ src: "https://vjmap.com/server/_cloud/lib/vjchat.umd.js" }]);
  }

  const aiChat = vjchat.attachMap(map, vjmap, {
    title: "唯杰地图 AI 对话",
    theme: { mode: "dark" },
    size: { width: 420, height: 500 },
    position: { right: 10, top: 100 },
    historyChatNum: 0,             // 默认不关联历史对话
    topK: 5,                        // 检索知识库条数
    scoreThreshold: 0.5,            // 相关性阈值
    chat: {                          // 可选：自定义大模型
      type: "openai",
      model: "gpt-4o",
      apiKey: "sk-...",
      baseUrl: "https://api.openai.com/v1"
    },
    onClose: () => { /* closed */ }
  });

  // aiChat.destroy();
})();
</script>
```

### 集成（npm）

```bash
npm i vjchat
```

```js
import { attachMap } from "vjchat";
attachMap(map, vjmap, { title: "AI 对话" });
```

### 支持的模型类型

```ts
type ChatOptions =
  | { type: "openai", model, apiKey, baseUrl? }
  | { type: "ollama", model, baseUrl };
```

### 提问技巧

- 命中知识库中的函数说明（例如 `addMarker`、`getMapGeoBounds`）。
- 多需求用逗号分开。
- 复杂任务分步骤（1. ... 2. ...）。

## 二、AI 绘 CAD（aidraw）

把"自然语言 → CAD 图形"，通过 `createMap` 生成一张临时图。

1. 提示 AI 生成 `filedoc` JSON（格式见 [upload-create-map](upload-create-map.md)）。
2. `svc.updateMap({ mapid: vjmap.getTempMapId(30), filedoc, mapopenway })` 创建临时图。
3. 前端 `map.switchMap({ mapid })` 切过去显示。

详见 [https://vjmap.com/guide/aidraw.html](https://vjmap.com/guide/aidraw.html)。

## 三、地图 MCP 协议

基于标准 MCP (Model Context Protocol) 的地图工具集。Cursor / Trae / Cherry Studio 等通用 AI IDE 可直接通过 URL 接入。

### MCP URL

```
https://vjmap.com/server/ai/mcp
  ?sessionId={sessionId}
  &include_categories=query,map,draw,custom
  &token={token}
```

无前端交互时 `sessionId` 可省。

### 后台服务 MCP（`/server/mcp`）

另一个独立入口：`https://vjmap.com/server/mcp`（Streamable HTTP），把图纸管理/查询/导出能力以 `cad_*` 工具直接给 AI 客户端，不依赖前端页面。

- 鉴权：`Authorization: Bearer <token>`、头 `token` 或 `?token=`。
- 工具筛选：`?tools=query,map`（白名单，分类或工具名）、`?exclude=admin`（黑名单）；默认加载 map/query/export/admin，draw/geom/symbol/workspace 需显式写进 `tools`。
- `?workspace=<名称>` 绑定本次连接的默认工作区。
- 私有化部署默认关闭，需在服务配置里 `mcp.enable=true`；写操作工具另需 `mcp.enable_write=true`。详见官方 [aimcp](https://vjmap.com/guide/aimcp.html)。

### 内置工具（后端）

| 工具 | 作用 |
|---|---|
| `listmaps` | 列出地图 |
| `createMap` | 创建地图 |
| `deletemap` | 删除地图 |
| `getMapImage` | 生成 PNG |
| `fullSearch` | 全文搜索 |
| `queryFeatures` | 四种查询模式 |
| `extractTable` | 自动提表格 |
| `sqlDocHelper` | 提供 SQL 辅助文档 |
| `createDwgDocHelper` | 提供图形定义辅助 |

### 内置工具（前端 SDK 注册）

| 工具 | 作用 |
|---|---|
| `map_get_info` | 当前地图信息 |
| `map_open_or_switch` | 打开 / 切图 |
| `map_view_control` | 缩放 / 平移 / 旋转 |
| `map_execute_code` | 执行任意 JS（沙箱） |
| `map_draw_geojson` | 绘制 GeoJSON |
| `map_delete_drawn_features` | 删绘制 |
| `map_create_markers` | 批量建 Marker |
| `map_delete_markers` | 删 Marker |

### 前端 SDK（vjmap-mcp-sdk）

```bash
npm i vjmcpsdk
```

```js
import vjmap from "vjmap";
import { initializeMCP, createTool, z } from "vjmcpsdk";

const mcp = await initializeMCP({
  apiBase: map.getService().baseUrl(),
  autoConnect: true,
  mapInstance: map
});
await mcp.registerMapTools();

// 自定义工具
const schema = z.object({
  bounds: z.array(z.number()).length(4).describe("[minX,minY,maxX,maxY]")
});
const tool = createTool("map_flash_position", "闪烁显示指定范围", schema, "custom");
mcp.registerTool(tool, async ({ bounds }) => {
  await flashPos(bounds);     // 自己实现的动画
  return { content: [{ type: "text", text: "已闪烁" }] };
}, "custom");

await mcp.getServiceManager().registerToolsToServer();
```

### Cursor / Trae 接入

在 `mcpServers` 里加：

```json
{
  "mcpServers": {
    "vjmap": {
      "url": "https://vjmap.com/server/ai/mcp?include_categories=query,map&token=eyJhbGci..."
    }
  }
}
```

然后直接在 IDE 聊天窗说："找出图里所有半径 > 10 的红色圆并在地图上闪烁显示"。

## 四、后端 AI 配置

`data/ai/aisvr_config.yaml` 配置模型、API Key、知识库路径、速率限制。

## 五、权限 / 安全

MCP 支持 `include_categories` / `exclude_categories` / `include_tools` / `exclude_tools` 精细控制工具开放度。生产环境建议 `exclude_categories=delete` 禁止删除。

## 六、常见坑

1. **vjchat 提问 AI 回答代码执行失败** → 提问不够精确，AI 匹配错了知识。打开"知识库搜索结果确认"手动选相关文档。
2. **MCP sessionId 没有** → 前端工具（`map_*`）无法工作；服务端工具正常。
3. **自定义工具注册后 IDE 看不到** → 忘了 `registerToolsToServer()`。
4. **OpenAI 自定义 baseUrl 但走代理超时** → 检查代理是否支持 SSE / 流式。