mcpField
D
designcraft

designcraft

github.com/mroxso文档处理959 次安装2 天前更新
代码仓库

关于 designcraft

通过桌面控制、CLI 或 MCP 接口操作 DesignCraft 的技能。它指导 Agent 检查和编辑文档、保留可编辑布局，并验证保存与导出结果。

主要功能

  1. 01发现可用工具与会话
  2. 02检查文档和界面状态
  3. 03编辑文本、框架、样式和图像
  4. 04运行脚本与数据合并
  5. 05保存、导出并检查页面渲染

适用场景

  1. 01编辑正在运行的应用中的文档
  2. 02在无界面会话中处理文件
  3. 03将数据合并到新文档
  4. 04交付前检查页面布局

MCP 相关

该技能可使用 DesignCraft MCP 工具进行文档检查、编辑、批处理、渲染和文件操作；如有可用连接，建议优先使用 MCP 服务。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mroxso/artcraft-skills --skill designcraft

安装后在 Claude Code 中输入/designcraft确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
references/
control-protocol.md
LICENSE-MIT

详细介绍

DesignCraft

通过其结构化自动化接口操作 DesignCraft，同时保留可编辑布局和用户选择的文档。

参考资料

在构造桌面请求前，请阅读 references/control-protocol.md。该文件是未经修改的上游快照，于 2026-11-02 下载。

来源：DesignCraft 控制协议。该文档依据随附的 MIT 许可证分发。快照中的相对链接均以 https://github.com/storytold/designcraft/blob/main/docs/ 为基准解析。

有关工具架构、会话模式和坐标，请参阅上游 MCP 文档。有关 CLI 脚本语法、结果引用和数据合并，请参阅 Agent 指南。如果已安装命令的参数与快照不同，请查询其参数；不要借用其他 ArtCraft 应用的标志或架构。

选择会话

首先查找可用的 DesignCraft 工具、可执行文件和现有会话。若有已连接的 MCP 服务，请优先使用。

  • 若要编辑用户正在运行的应用，请使用桌面控制，或使用 designcraft-cli mcp --connect PORT（也接受 HOST:PORT）。
  • 若要独立处理文件，designcraft-cli mcp 会启动一个进程内无头引擎，并创建一个空白 Letter 文档。编辑前请打开目标文件。此模式不会更改用户的实时窗口。
  • CLI 脚本可以处理文件，也可以连接到正在运行的应用。选择参数前，请检查 designcraft-cli --help 和相关子命令。

使用 designcraft --control <port> 或 DESIGNCRAFT_CONTROL_PORT 启动所需的桌面控制会话；7979 是上游示例端口，并非必需端口。尽可能重用现有会话。服务器绑定到回环地址，且没有身份验证；仅在使用期间启用它。如果应用或连接不可用，请报告缺少的前提条件。此技能不会安装 DesignCraft 或配置 MCP 服务。

控制传输和发现

桌面控制通道使用原始 TCP 和 UTF-8 JSON 行，而非 HTTP 或 MCP JSON-RPC。每行发送一个请求，每个请求读取一条回复，使用唯一 ID，并在执行依赖操作前检查 ok：

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

engine.execute 接受 {command, params}；通过 engine.commands 发现命令 ID、参数和启用状态。使用 MCP 时，请使用 list_commands 和 execute，或先检查专用工具的架构再使用。MCP 故障可能以 isError: true 的工具结果形式返回。

格式错误的行会关闭 TCP 连接；请求不得超过 4 MiB，且服务器最多允许 16 个并发连接。收到错误回复后请重新连接。如果某项修改未收到回复或发生超时，请先检查生成的文档，再决定是否重试。若无法确定操作是否已执行，请停止并报告不确定性；重复创建或合并可能导致工作重复。

布局和文本编辑

在定位编辑目标前，检查页面、跨页、项目 ID 和边界、文本串、溢出文本、样式、色板、图层及所选内容。MCP 提供 inspect_document 和 get_story；桌面端提供 document.inspect。当焦点、工具或对话框会影响操作时，需单独检查 UI 状态。

对于精确的文本框、文本、样式和图像放置，优先使用引擎命令或专用 MCP 工具。后续编辑使用实际返回的项目 ID 和文本串 ID；如果命令依赖选区，则先建立选区或文本范围。set_story_text 会替换文本串中的文本；仅在预期结果是完整替换后的文本时使用它，不要将其用于部分插入。若符合所需布局，请保留文本串链接和可编辑样式。

坐标单位为点（1/72 英寸），y 轴向下递增，坐标采用跨页空间。在对页跨页中，右页从 x = 页面宽度处开始；请检查页面边界，不要假设每页都从零开始。MCP render_page 和 export_png 使用从零开始的页面索引。在解释文本框的 rect 或其他几何数组前，先检查命令参数。

使用工具手势时，请明确选择当前工具。桌面端 ui.pointer 支持显式指定 space: "canvas" 或 "screen"；进行屏幕交互前，先检查缩放比例、原点和画布矩形。MCP 已连接模式下的 pointer 也支持屏幕坐标。键盘和文本输入取决于插入点或当前焦点字段；需要确定性定位时，优先使用文本串或引擎编辑。

使用 ui.menu.list 和 ui.menu.invoke 操作菜单。调用带参数的菜单命令时若未提供参数，可能会打开对话框，而不是执行编辑。检查对话框，使用 ui.dialog.set 填写文档说明的字段，然后确认或取消。不要假设调用菜单命令后文档更改已完成。

脚本和数据合并

对于包含多条命令的 CLI 任务，请先阅读 Agent 指南。脚本接受命令行、JSON 行或 {command, params} 数组。"$0.story" 和 "$last.id" 等结果引用可让后续步骤定位先前结果。MCP batch 支持命令或脚本文本，并会在遇到第一个错误时停止。继续操作前请检查 failedIndex 和部分结果；不要盲目重放已部分执行的整个批处理。

对于数据合并，请先了解 data.source.select、data.fields、data.placeholder.add、data.options、data.preview、data.preview.stop 和 data.merge。添加占位符前先检查源字段，并预览有代表性的记录，以检查文本溢出和图像适配情况。data.merge 会创建并激活新文档，同时保留模板不变；请将合并后的文档保存到预期输出路径。已弃用的 spread 合并参数会导致错误。

保存、导出和验证

使用桌面端 app.open、app.save 和 app.export，或使用 MCP 的 open_document / save_document 操作原生 .designcraft 文件，并使用已安装的导出命令。请先了解特定格式的参数，不要猜测文件操作的参数结构。适当情况下，保存可编辑的原生文档，并单独导出所需的交付格式。

检查生成的文档结构和溢出文本，然后使用 ui.render 或 MCP render_page 渲染相关页面并查看图像。检查页边距、出血、文本流、裁切和图像位置。窗口截图显示 UI 状态；页面渲染显示图稿，即使没有呈现窗口也可使用。MCP 窗口工具需要连接模式。参考文档还介绍了源代码树中的 ui_shot 示例，可在需要时用于离屏捕获整个窗口。

确认保存和导出均已成功，并检查实际输出文件是否存在且可读取，然后再报告完成情况。返回保存路径，并说明任何重要的布局或导出问题。

评论

支持 Markdown