HTML 转 Sketch

必须执行的入口

触发本技能后，直接定位技能根目录，也就是当前 SKILL.md 所在目录，使用 Node.js 执行技能包内脚本：

node <skill-dir>/scripts/convert.js <input.html> <output.sketch> [--ignore-errors] [--validate] [--split-top-level]

如果当前工作目录已经是技能根目录，也可以执行：

node scripts/convert.js <input.html> <output.sketch> [--ignore-errors] [--validate] [--split-top-level]

不要安装全局 html2sketch。不要执行 npm install -g html2sketch。不要用 npx html2sketch。不要临时下载其他转换器。

本技能已经携带转换所需的打包产物：

bin/index.js
vendor/html2sketch.min.js

convert.js 会检查这些文件，并把请求转交给 bin/index.js 执行转换。转换任务默认只读取输入 HTML，并写入输出 .sketch、可选 .validation.md 和必要时的 .conversion.log，不修改输入 HTML。

何时使用

• 用户要求将 .html 或 .htm 文件转换为 .sketch
• 用户提到 HTML to Sketch、html2sketch、Sketch 导入、MasterGo 导入、设计稿转换
• 用户需要从本地静态 HTML 生成可导入设计工具的 Sketch 文件
• 用户需要转换后附带结构诊断报告

不适用场景

• 用户只需要截图、PNG、PDF 或网页预览
• 页面依赖登录态、远程接口数据或复杂交互步骤后才完整渲染，且用户未提供可离线渲染的静态 HTML
• 输入不是本地 HTML 文件，或无法在本机浏览器中正常打开

环境要求

| 项目 | 要求 | 不满足时怎么处理 |

| --- | --- | --- |

| Node.js | 建议 18 或更高版本 | 提示用户安装 Node.js 后重试 |

| 浏览器 | 已安装 Chrome、Chromium、Microsoft Edge 之一 | 提示用户安装 Chrome、Chromium 或 Microsoft Edge 后重试 |

| 打包 CLI | 技能包内存在 bin/index.js | 提示用户获取完整技能包或让维护者重新生成发布包 |

| 浏览器资源 | 技能包内存在 vendor/html2sketch.min.js | 提示用户获取完整技能包或让维护者重新生成发布包 |

不需要用户安装 html2sketch npm 包；转换器已经打包在技能包内。

参数说明

| 参数 | 说明 |

| --- | --- |

| | 输入 HTML 文件路径，支持相对当前工作目录路径或绝对路径 |

| | 输出 Sketch 文件路径，扩展名必须为 .sketch |

| --ignore-errors | 跳过失败节点并继续生成文件，适合复杂 CSS 或局部节点失败时兜底；可能生成同名 .conversion.log 记录失败节点、CSS 路径和浏览器日志 |

| --validate | 生成同名 .validation.md 诊断报告，检查结构、文本原点坐标、负坐标等问题；如果发现结构错误，命令会以失败状态退出 |

| --split-top-level | 将 body 一级子节点拆成 Sketch 页面顶层图层，减少单个大组嵌套 |

路径包含空格、中文或特殊字符时，命令中使用引号包裹完整路径。

产出物与用户反馈

转换完成后，必须向用户说明可查看或交付的产出物路径。不要只回复“转换完成”。

必须反馈：

• Sketch 文件路径：

按实际生成情况反馈：

• 使用 --validate 时，反馈诊断报告路径：
  .validation.md
• 生成失败日志时，反馈转换日志路径：
  .conversion.log
• 命令失败但已经生成诊断报告或日志时，也要反馈这些已生成文件路径

如果运行环境支持文件回传或附件交付，优先交付 .sketch 文件；.validation.md 和 .conversion.log 作为辅助产物交付。

建议反馈格式：

转换完成：

- Sketch 文件：<output.sketch>
- 诊断报告：<output>.validation.md（如有）
- 转换日志：<output>.conversion.log（如有）

推荐命令

常规转换：

node <skill-dir>/scripts/convert.js ./page.html ./page.sketch

生成诊断报告：

node <skill-dir>/scripts/convert.js ./page.html ./page.sketch --validate

减少大组嵌套并生成诊断报告：

node <skill-dir>/scripts/convert.js ./page.html ./page.sketch --split-top-level --validate

复杂页面兜底转换：

node <skill-dir>/scripts/convert.js ./page.html ./page.sketch --ignore-errors --split-top-level --validate

Windows 中文或空格路径示例：

node <skill-dir>/scripts/convert.js "C:/Users/name/Documents/page demo.html" "D:/output/page demo.sketch" --split-top-level --validate

Agent 执行流程

1. 从已加载技能的 Base directory 或当前 SKILL.md 文件路径推导技能根目录。
2. 组装命令：node /scripts/convert.js 。
3. 路径包含空格、中文或特殊字符时，使用引号包裹完整路径。
4. 按用户需要追加 --validate、--split-top-level 或 --ignore-errors。
5. 执行命令。
6. 如果命令提示缺少 Node.js 或浏览器，只向用户说明需要安装对应环境。
7. 如果命令提示缺少 bin/index.js 或 vendor/html2sketch.min.js，说明技能包不完整，让用户获取完整包或让维护者重新生成。
8. 不要改用全局安装、npm 包安装、npx 下载或其他转换方案。
9. 不要修改输入 HTML，除非用户明确要求为了转换兼容性进行修复。
10. 转换完成后，向用户列出输出 .sketch 文件路径。
11. 如果生成 .validation.md 或 .conversion.log，一并列出这些辅助文件路径。

常见问题

| 问题 | 处理方式 |

| --- | --- |

| 未检测到 Node.js | 提示用户安装 Node.js 18+，重新打开终端后再运行 |

| 未找到 Chrome、Chromium 或 Microsoft Edge 浏览器 | 提示用户安装 Chrome、Chromium 或 Microsoft Edge |

| 输入 HTML 文件不存在 | 检查输入路径；路径含空格、中文或特殊字符时使用引号包裹 |

| 输出文件扩展名不是 .sketch | 将输出路径改为 .sketch 结尾 |

| 技能包缺少打包后的 CLI 入口 | 技能包不完整；重新获取完整包或让维护者重新生成 |

| 技能包缺少 html2sketch 浏览器端资源 | 技能包不完整；重新获取完整包或让维护者重新生成 |

| 转换中断于复杂 CSS | 尝试添加 --ignore-errors，或简化 HTML 中的复杂 CSS |

| 生成了 .conversion.log | 查看失败节点、CSS 路径和浏览器日志，判断是否需要简化 CSS 或使用兜底转换 |

| --validate 后命令失败 | 打开 .validation.md 查看结构错误；结构错误会导致命令失败，普通诊断警告不会阻止输出 |

| 导入设计工具后图层过深 | 尝试添加 --split-top-level |

| MasterGo 或 Sketch 导入异常 | 添加 --validate，查看 .validation.md 并定位结构或文本坐标问题 |

使用边界

• 转换结果是设计稿初稿，不保证与浏览器像素级完全一致。
• 复杂 CSS 可能被降级或跳过，例如伪元素、阴影、滤镜、复杂渐变、clip-path 等。
• --ignore-errors 会尽量生成文件，但可能缺失部分节点；用于兜底，不应作为高保真交付默认选项。
• 不要直接修改源 HTML，除非用户明确要求为了转换兼容性进行修复。
• 不要绕过技能包内 CLI 手写 Sketch ZIP 结构，否则容易生成设计工具无法导入的文件。