疑难排解

Agent 没有使用 Skill

• 确认 Skill 已安装到当前 Agent 可发现的位置。
• 重新启动会话。
• 在提示词中明确写 huashu-design 或对应的 Skill 调用语法。
• 确认 SKILL.md 的相对引用路径完整。

页面白屏

先检查浏览器控制台。常见原因包括 React / ReactDOM 版本不匹配、JSX 转换失败、外部 CDN 无法访问和模块路径错误。

file:// 下资源无法加载

外部 JSX、ES Module 和部分字体会受到浏览器 CORS 限制。使用本地 HTTP 服务，或按单文件交付要求把依赖内联。

python3 -m http.server 8000

字体或布局不稳定

等待 document.fonts.ready 后再测量和截图。为图片和媒体预留尺寸，避免字体或图片加载后改变布局。

视频开头有黑帧

使用 window.__ready、确定性 seek 渲染或调整录制准备流程。不要只靠任意延迟猜测字体和动画已就绪。

视频里出现播放器控件

检查页面是否包含真实或伪造的 Chrome 控件。录制模式应隐藏调试和播放 UI。

可编辑 PPTX 导出报错

检查文本是否包在 <p> 或标题标签中、文字标签是否错误承载背景/边框、是否使用 CSS 渐变，以及背景图是否应改成 <img>。

图片或 Logo 不可信

回到品牌资产协议。优先官方品牌页、press kit、Wikimedia 和可信素材源，并记录来源和本地路径。

验证命令

python3 scripts/verify.py path/to/design.html \
  --viewports 1440x900,390x844 \
  --output ./screenshots

更多细节见 验证流程 与 动画避坑。