cadcraft

CADCraft

通过其结构化自动化接口操作 CADCraft。保留用户要求的制图工作流和目标图纸。

协议参考

构造调用前，请阅读 references/control-protocol.md 中的相关章节。这是下载的上游协议，记录于 2026-11-09。

来源：CADCraft control protocol。

有用的章节：方法表（文档顶部）、面板停靠、命令行回复和界面语言。下载文档中的相对链接（例如 localization.md）指向上游文档；如有需要，请将其解析为 https://github.com/storytold/cadcraft/blob/main/docs/ 下的链接。该文档很短，未列出各个绘图命令：请在运行时通过 engine.commands 发现这些命令，不要臆造命令 ID 或参数。

查找可执行文件

即使已安装 CADCraft，cadcraft 和 cadcraft-cli 也可能不在 PATH 中。请先查找它们，不要想当然地认定它们不存在，也不要臆造路径：

1. PATH： command -v cadcraft cadcraft-cli（POSIX）或 where cadcraft cadcraft-cli（Windows）。
2. macOS： 在 /Applications 和 ~/Applications 中查找 CADCraft.app，或运行 mdfind -name CADCraft.app；Contents/MacOS/ 中的二进制文件就是桌面应用。
3. Linux / Windows： 检查常见安装位置，以及桌面快捷方式或开始菜单快捷方式指向的目标。
4. 缺少 cadcraft-cli 并不妨碍操作。 控制端口通过回环 TCP 使用纯文本、按行分隔的 JSON，无需桥接：每行发送一个请求，例如 {"id":1,"method":"cmdline.input","params":{"text":"circle 0,0 5"}}，并根据 id 和 ok 匹配回复。用任何语言编写一段简短脚本即可涵盖所有方法。

选择会话

• 对于用户已打开的图纸或可见应用，请使用现有的 CADCraft MCP 桥接或控制会话。无头会话拥有独立的进程内图纸，无法编辑用户当前窗口中的内容。
• 对于无人值守的文件处理，请使用无头 MCP（cadcraft-cli mcp）。
• 请先发现可用的 CADCraft 工具和已安装的可执行文件。如果缺少所需的连接或可执行文件，请说明具体的前置条件；创建此技能不会安装 CADCraft，也不会注册 MCP 服务。

使用 --control PORT（或 CADCRAFT_CONTROL_PORT=PORT）启动桌面会话；它会监听 127.0.0.1:PORT。通过以下方式桥接：

cadcraft-cli mcp --connect 127.0.0.1:PORT

尽可能复用正在运行的会话，并确保 TCP 连接仅使用回环地址。上游协议未说明身份验证握手或文件访问根目录；如果已安装的版本要求令牌或根目录，请遵循其 --help 输出，不要猜测。

使用 CADCRAFT_CONFIG_DIR 将应用指向一个私有、隔离的自动化配置目录（设置为空值可禁用工作区的读写）。不要直接编辑用户的 workspace.json。

检查、编辑和验证

编辑前先检查：使用 drawing.inspect 查看计数、范围、图层、样式、块、布局、选择内容和撤销状态；使用 ui.inspect 查看 UI 状态、活动视图，以及是否存在待处理的“保存更改？”提示（closePrompt）；使用 cmdline.state 查看当前提示。应用可能会恢复或已载入你未创建的图形。

有两种编辑方式：

• 命令行 — cmdline.input {text} 的行为与用户输入完全相同：按名称或别名启动命令，并响应提示（点 x,y、相对坐标 @dx,dy、极坐标 @d<a、距离、关键字；留空 = Enter）。除文本提示外，空格等同于 Enter。cmdline.script {text} 运行多行脚本；cmdline.key 发送 Enter 或 Escape。进行下一项无关操作前，务必先让命令行返回空闲的 Command: 提示（按 Escape）。
• 引擎命令 — engine.execute {command, params} 使用 JSON 参数运行任意命令，且不会打开对话框。通过 engine.commands 查询 ID、参数文档和启用状态。

被拒绝的命令行输入（未知命令、无效输入）仍会返回 "ok": true；务必检查回复中的 error 字段和 output。 不带字符串 path 的 app.open 会失败并返回 "missing path"。

仅在需要交互式菜单行为时使用 ui.menu.invoke。ui.pointer 默认使用世界坐标；ui.click、ui.move 和 ui.drag 使用屏幕坐标，并可操作所有控件。ui.key 只会将按键事件加入队列 — 在执行下一项操作前，轮询 ui.inspect 或 ui.elements，确认焦点或状态变化。使用 ui.elements（对 label、role、focused 进行精确匹配筛选）查找控件，不要猜测坐标。

面板布局（ui.dock、ui.dock.reset，面板 ID：toolSets、layers、properties、externalReferences；canvas 受保护）通过 engine.execute 调用，不会编辑文档内容。仅在任务需要时更改布局、主题或界面语言。

通过视觉和结构方式验证：重新运行 drawing.inspect（实体包含句柄和几何信息），并使用 ui.render 渲染 — 默认会将整个图形纳入画面的无头渲染（fit: false 保留当前视图，window 仅显示指定区域），返回 pngBase64；也可以传入 path。background 用于指定画布颜色，plot_style 用于应用绘图样式表，例如 monochrome.ctb。ui.screenshot 会截取应用窗口，需要已有呈现的帧。

文件访问和输出

• 桌面控制：app.open {path} / app.save {path} / app.quit。
• 将输出保存为 DXF 或 DWG：使用 ui.set 设置 saveFormat: "dxf"|"dwg" 和 saveVersion: "2000"…"2018"，以指定新图形的“另存为”建议格式；SAVEAS 也可直接接受 version 和 binary。
• 报告保存成功情况，以及确切的输出路径和格式/版本。除非用户要求，否则不要覆盖其源图形；请使用新名称另存副本。

超时和结果不确定

服务器最多等待应用 60 s。超时回复包含 state：

• "not-run" — 请求已取消，之后不会运行；可以安全地重新发送。
• "may-have-run" — 应用已开始执行请求，可能仍会更改图形（其延迟返回结果会被丢弃）。重新发送任何修改操作前，先使用 drawing.inspect 检查。

断开连接或发生其他不明确的失败后，重试前先检查图形和撤销状态。如果检查无法确定重放是否安全，请停止并报告未解决的状态。