唯杰地图 logo唯杰地图
VJMAP
EN

AI / MCP 集成（检索、校验、实时操作页面）

vjvp/references/platform/mcp-and-ai.md 8.1 KB96 行
原文

1. 开启（后端配置）

内置 AI 问答（编辑器右下角）：在 server/vp_config.json 的 ai 段填写 baseURL / apiKey / models / visionModels（对应旧 VJAGENT_LLM_*），重启后端即可（种子化成固定名 default 的平台端点）；也可在 AI 设置里添加 BYO 端点。输入栏相机按钮会截当前大屏并打开标注编辑器（矩形 / 箭头 / 画笔），确认后作为图片附件发给多模态模型；点附件缩略图可查看大图或再编辑。

模型解析优先级：会话已定格 → 用户 BYO 端点 → 平台 default → 文件/环境变量兜底。配置文件的 apiKey 只属于 default，不会补给自建端点；自建端点漏填 Key 会得到 unauthorized: You didn't provide an API key，而两边常提供同名模型（都叫 qwen3.6-plus）看不出差别。AI 设置的端点列表会标「未设 Key」、只给真正生效的那条标「默认」，并可逐条删除；模型药丸显示的是本会话实际所用模型。会话模型首次发言即定格，换端点后要新建会话。

server/vp_config.json（或环境变量 VP_MCP_ENABLED=true 等）：

{
  "mcp": {
    "enabled": true,
    "dataDir": "./vp_mcp_data",
    "cacheDir": "./pb_data/mcp-cache",
    "publicURL": "https://your-host",
    "localValidateRoots": [],
    "liveEnabled": true,
    "liveSecret": "<32+位稳定密钥>"
  }
}
  • MCP 数据目录 vp_mcp_data/ 不打包进二进制，与后端放在一起；更新数据后重启后端即可。
  • liveSecret 决定工程 MCP 地址里的 token；不设则每次重启随机、旧地址失效。
  • 端点：POST/GET https://<host>/mcp（Streamable HTTP）；GET /llms.txt 索引。
  • 反代（nginx proxy_pass 到 127.0.0.1 且保留对外 Host）开箱可用：SDK 的 DNS 重绑定保护已关（否则 /mcp 全部 403 invalid Host header），Host 准入看 allowedHosts（留空=全放行）。publicURL 留空时对外地址按请求推导。

2. 静态工具（检索 / 文档 / 校验）

Tool 作用
search_widgets / get_widget_metadata 检索组件、取 options 元数据；搭建型组件返回 childPieces
search_documentation / get_doc 检索文档章节；get_doc 传 type 取组件文档（scene-3d 等 builder 绑子系统总览）、传 docId 取文档页
list_examples / get_example 白名单示例
validate_project 校验工程 JSON（内联对象）
validate_project_file 按服务器本地路径校验（需配 localValidateRoots，省 token：{ "path": "D:/out/demo.vpproj.json" }）

与本技能的分工：查 API/文档/校验走 MCP；按规范拼整份 JSON 用本技能 references/（envelope/data/interactions）+ scripts/validate-project-json.mjs 自检。

3. Cursor 配置（静态工具）

{ "mcpServers": { "vjappvisual": { "url": "http://127.0.0.1:8090/mcp" } } }

需 stdio 代理时用 npx -y mcp-remote http://127.0.0.1:8090/mcp。改数据/配置后重启后端再刷新 Cursor MCP 面板。

4. live 实时页面控制（AI 直接操作打开的工程）

编辑态：完整结构编辑（撤销/保存）；运行态：读取/交互/临时改属性（reload 还原，不写回工程）。

两种接入：

  • 工程地址（配到 Cursor）：编辑器右下角「AI」面板复制 http://<host>/mcp/p/<projectId>?token=… 写入 mcp.json。多标签同工程时 page_sessions → page_attach(sessionId)（仅一个时自动附着）。
  • 本标签地址（应用内 AI 面板）：http://<host>/mcp/s/<token> 精确指向当前标签。

工具面已收敛：同族合并为带 action 的单工具、单/批只留批量；会话端点不注册 page_attach，运行态会话不注册编辑工具。

Tool 组 能力
page_sessions / page_attach 会话总览（含当前目标）/ 选定（仅工程端点）
page_get_screens / page_list_elements 结构（摘要省 token）；page_list_elements 传 query 即模糊查找
page_get_elements 元素详情：uids 批量（≤50，fields 限定选项）；uid/elementUID 单个。两种读法互斥，同传会报错
page_get_schemas 可写属性清单（真实 path/类型/门控 enabled），按 type 去重
page_list_widget_types / page_screenshot 组件类型目录 / 页面截图（视觉核对）
page_get_selection / page_get_data / page_get_params 读选中/数据/参数
page_interact / page_emit 交互（action=select/highlight/click）/ 事件
page_batch_set_options 改属性（编辑态持久+可撤销；运行态临时；单条=长度 1 的 changes）；返回以 FAILED 开头须先修正
page_set_data / page_set_params / page_set_active_screen / page_window 数据/参数/切页/画面（action=open/close）
page_add_element / page_remove_element / page_move_element / page_history / page_save 结构编辑与撤销重做（action=undo/redo）；仅编辑态
page_export_tsx / page_apply_project VP-TSX 环路（仅编辑态）：export_tsx({ path, screenUid? }) 把当前页/指定屏导出为 .vp.tsx；`apply_project({ path }

live 端点同时挂载知识子集（search_documentation / get_doc / get_widget_metadata）；示例与校验类工具只在独立 /mcp 生成端点。

推荐工作流（schema-first）：page_list_elements → page_get_schemas(uids) 取真实属性 path（绝不臆造）→ 一次 page_batch_set_options（检查 failed/warnings）→ page_screenshot 核对 → page_save。写属性的 path 权威 = live page_get_schemas（或生成 JSON 时的 get_widget_metadata）；get_doc 是人读向导，不可作为 path 依据。批量读优先 page_get_elements(uids)/page_get_schemas(uids)，不要逐 uid 串行单读。

容易踩的语义（照描述用会踩坑的地方）

  • 只回已写入的选项：page_get_elements(uid) 不返回仍是默认值的项（默认值没落库）。要默认值查 page_get_schemas。
  • page_set_data 是整表替换，不是追加；空数组 = 清表。列以表结构为准，多余列会被丢掉。
  • page_set_params 只在顶层合并：嵌套对象整段替换，null 是存 JSON null 而不是删键。
  • page_window 分模式：运行态才真的开关浮层；编辑态 open 等于把编辑画布切过去、close 回 applied:false。切页面用 page_set_active_screen。
  • query 只搜当前屏，是普通子串（不是正则），也不搜 uid。要搜别的页先切过去。
  • 写不了的东西：interactions、地图/三维/组态的 pieces、data-repeater 的 unitTemplate、选项卡/视图分页——这些是结构字段，只能改 VP-TSX 再 page_apply_project。name/visible/locked 是列表里的只读元数据，不是属性 path。
  • 字体是整对象：写 text-font 会覆盖整段，要把 size 一并带上，否则原有字号丢失。
  • 新增页面不能靠单屏 apply：单屏 envelope 按 uid 合并进现有工程，uid 必须已存在；要加页就导出整工程、在里面加好再整体 apply。
  • 未知 uid 一律报错：page_emit 的 targetUid、page_interact 的 uid、page_set_active_screen 的 screenUid、page_list_elements 的 screenUid 都不再静默兜底。limit 必须 ≥1，limit=0 是错误而不是「不限」。

5. 安全要点

  • WS 注册强制鉴权：编辑态验登录+工程 owner；运行态验工程 token，且需页面浮层手动「允许 AI 交互」。
  • 仅暴露公开文档与白名单示例；请求体/超时/并发/频率受限；命令按会话串行。
  • validate_project_file 只读 localValidateRoots 白名单目录（防目录穿越）；公网部署慎开。