AI 能力

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

一、AI 对话（vjchat）

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

集成（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）

npm i vjchat

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

支持的模型类型

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）。
2. svc.updateMap({ mapid: vjmap.getTempMapId(30), filedoc, mapopenway }) 创建临时图。
3. 前端 map.switchMap({ mapid }) 切过去显示。

详见 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。

内置工具（后端）

内置工具（前端 SDK 注册）

前端 SDK（vjmap-mcp-sdk）

npm i vjmcpsdk

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 里加：

{
  "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 / 流式。