vectorcraft

VectorCraft

通过其结构化自动化接口操作 VectorCraft，同时保留用户所选的文档和预期的可编辑性。

参考资料

构造桌面调用前，请阅读 references/control-protocol.md 中的相关部分。这是于 2026-10-08 下载的未修改上游快照。

来源：VectorCraft control protocol。上游文档根据随附的 MIT 许可证分发。

参考文档从方法表开始；需要时，请搜索特定工具、对话框或格式。可用的搜索词包括 Background Save / Export、SVG Options、Import PDF、gradientStop、Effect dialogs、Native save options 和 Modifiers on synthetic input。相对链接以 https://github.com/storytold/vectorcraft/blob/main/docs/ 为基准解析。

需要了解 MCP 工具架构、无头批处理语法和引擎命令示例时，请参阅上游 MCP 文档。如果行为不一致，请检查已安装的命令注册表和工具架构；不要借用其他 ArtCraft 应用的参数或身份验证标志。

选择会话

首先发现可用的 VectorCraft 工具、已安装的可执行文件和现有会话。若有已连接的 MCP 服务，优先使用它。

• 要编辑用户当前应用中的文档，请使用桌面控制，或明确连接到该应用的 MCP：vectorcraft-cli mcp --connect 127.0.0.1:7979。
• 要独立处理文件，请使用 vectorcraft-cli mcp --headless，或先阅读 MCP 文档中的语法，再使用批处理 CLI。
• 不带模式标志时，vectorcraft-cli mcp 会尝试连接端口 7979，失败后切换到无头模式。目标会话很重要时，请明确指定模式：无头会话不会编辑用户打开的应用窗口。

可使用 vectorcraft --control 7979 启动所需的桌面会话；请根据环境调整可执行文件和可用端口。尽可能复用现有会话。该端口仅监听回环地址，且没有身份验证；仅在使用期间启用它。如果可执行文件或连接不可用，请报告缺少的前置条件。此技能不会安装 VectorCraft 或配置 MCP 服务。

桌面传输

控制端口使用原始 TCP，而非 HTTP 或 MCP JSON-RPC。发送 UTF-8 JSON 对象，每行一个，并为每个请求读取一条回复。使用唯一的请求 ID，匹配回复，并在执行依赖操作前检查 ok：

{"id":1,"method":"ui.inspect","params":{}}
{"id":2,"method":"document.inspect","params":{"depth":1,"childLimit":20}}
{"id":3,"method":"engine.commands","params":{}}

engine.execute 接受 {command, params}。其中的 command 是从 engine.commands 发现的引擎命令 ID，与传输 method 不同。对于 MCP，请使用 list_commands 和 run_command {command, params}，或适当的专用工具。

格式错误的请求行会关闭连接；请求行长度不得超过 4 MiB。服务器最多支持 16 个并发连接。收到错误回复后请重新连接。如果某项修改操作超时或未收到回复，请先检查文档状态和历史记录，再决定是否重试；如果无法安全确定操作结果，请停止并报告不确定性。

检查和编辑

编辑前，请检查当前文档、画板、选区、绘制目标、当前工具以及任何已打开的对话框。桌面端使用 document.inspect 和 ui.inspect；MCP 使用 inspect_document，在远程模式下使用 inspect_ui。

对于大型文档，使用 depth 和 childLimit 限制检查范围。使用或查找 document.find 来定位相关对象，并使用 document.node {id, summary: true, depth?, childLimit?} 深入查看。定位编辑目标前，请先获取实际对象 ID；新对象会成为选区，许多命令会对其执行操作。使用 select.set {ids} 显式设置选区，或在支持时使用命令专用的 ids。

使用引擎命令或专用 MCP 工具来精确处理形状、路径、文本、绘制属性、变换和效果。MCP 提供 draw_path、draw_shape、add_text、set_paint、transform、pathfinder 和 apply_effect；调用前请检查它们的架构。若可满足所需效果，请保留可编辑文字、实时效果、混合和信封变形；仅在实现目标确有需要时才扩展、转轮廓或栅格化。

对于手势，文档坐标的单位为点，y 轴向下递增，原点位于第一个画板的左上角。桌面端的 ui.pointer 事件支持显式指定 space: "doc" 或 space: "screen"；请谨慎选择坐标空间，并在操作屏幕控件前检查视图和画布矩形。MCP 的 pointer_gesture 使用文档坐标。绘制前，请设置当前工具并检查吸附和工具选项。ui.text 和远程 MCP 的 type_text 依赖焦点；如需确定性地编辑内容，请使用文本命令。

使用 ui.menu.list / ui.menu.invoke 操作应用菜单。调用可能会返回 pending，或打开对话框，而不是直接完成操作。请检查对话框，使用 ui.dialog.set {field, value} 设置文档规定的字段，并根据需要确认或取消。预览对话框可能会临时修改画布；确认会保留编辑，取消则会回滚预览。未经授权，不要在 saveChanges 或恢复对话框中丢弃未保存的工作。

保存、导出和验证

桌面文件操作包括 app.open、app.save 和 app.export；MCP 提供 open_file、save_file 和 export。查询 document.formats，了解已安装的格式支持和选项。检查导入/导出的 warnings，包括回退栅格预览和丢失的格式功能。

在适当情况下，将可编辑交付件保存为 .vectorcraft，并另行导出所需的交付格式。保存操作使用文档自身的格式：已打开或保存的 SVG/PDF 可以再次以该格式保存。需要原生格式副本时，请使用明确的原生格式路径。导出不会更改文档路径。如果未提供明确的 SVG 选项，SVG 保存操作可能会打开 svgOptions。

检查画板范围和索引：MCP 导出的 artboard 从零开始计数，而其 range 使用从 1 开始的值，例如 "1-3, 5"。桌面端的 useArtboards 可以生成多个文件；请检查返回的 files，不要假设只会生成请求的路径。未指定路径时，导出可能会返回 dataBase64，而非写入文件。设置分辨率、文本轮廓化、颜色模式、透明度或链接资源之前，请先阅读对应格式的选项。

默认情况下，桌面端的保存和导出会在后台运行。包含 background: true 的响应表示已确认排队写入快照，并不表示操作已完成。检查 ui.inspect 中的 background 作业，直到相关写入完成，然后验证输出存在且可读取，再报告成功。后续编辑不会包含在先前的快照中。重试失败或状态不明确的写入之前，请先检查状态。

验证生成的对象结构和视觉效果。桌面端的 ui.render 无需呈现窗口即可渲染画板；ui.screenshot 会捕获窗口，需要可见且已呈现的画面。MCP 的 screenshot 默认会渲染作品，而 window: true 会捕获远程窗口，并且在无头模式下不可用。查看返回的图像或本地预览，并检查构图、裁切、文本和效果。报告实际保存/导出的路径以及重要警告。