排错手册

按症状找。装不上的在最前面，生成质量的在后面。

装不上

pnpm install 报 EBADENGINE

Node 大版本不对。OpenDesign 要 Node 24，Node 22 不支持。

nvm install 24 && nvm use 24
node -v   # 确认是 v24.x
corepack enable

Windows 上 better-sqlite3 编译卡住

Node 24 上的已知情况。先装 Visual Studio Build Tools（要包含 C++ 桌面开发工作负载），再重跑 pnpm install。

三个替代方案，从简单到麻烦：

1. 直接用 Windows 安装包，跳过源码。
2. 在 WSL 里跑源码版。
3. 装完 Build Tools 再来。

pnpm 版本不对

用 Corepack，别全局装：

corepack enable
# 之后 pnpm 会按 lockfile 里锁定的 10.33.2 走

端口被占

上一次没停干净：

pnpm tools-dev stop

还不行就换端口：

pnpm tools-dev --daemon-port 27456 --web-port 27573

别在脚本里写死端口。

不知道缺什么

pnpm tools-dev check

这条比读日志快。它会把环境里缺的东西直接列出来。

Agent 接不上

界面里看不到 Agent

按这个顺序查：

1. CLI 在 PATH 里吗？ 终端里敲一下它的名字（claude、codex、cursor-agent……），能不能起来。
2. 登录了吗？ CLI 自己先跑通一次。
3. 用 API key 的话，.od/media-config.json 写对了吗？
4. pnpm tools-dev check 看看它怎么说。

一直弹权限确认

环境没配全。跑 pnpm tools-dev check，它会指出缺的那一项。

生成卡在「等待」不动

• 检查那个 Agent 的额度还有没有。
• 检查网络能不能到模型厂商。
• 换一个 Agent 试试，能区分是 OpenDesign 的问题还是那个 Agent 的问题。

换了 Agent 之后技能不工作

技能本身跟 Agent 无关，所以这种情况通常是新 Agent 的能力边界不同——比如它不能联网、不能生成图。看那个技能依赖了什么能力。

生成结果不对

输出是一堆图片，文字选不中

有些 Agent 会取巧，把参考图切片贴进 HTML。补一句：

所有文字必须是真实文本节点，能被选中和编辑。不允许把文字渲染成图片。

风格完全没跟上参考图

两个可能：

1. 参考图没真的传进去。确认附件在。
2. 描述太笼统。把选中方向的特征写具体——具体的配色倾向、字体性格、质感、留白程度。

内容被裁掉了

指出具体页码，让它按骨架补回来。不要说「有些内容丢了」。

第 5 页现在只剩标题。请按内容方案里第 5 页的完整内容补回来，
版式跟第 4、6 页保持一致。

改一处，坏了另一处

分轮改，每轮聚焦一两个维度，并且加上：

只改上面说的这些，其余不要动。

越改越花

明确排优先级：

优先级：可读性 > 信息层次 > 视觉冲击。
如果三者冲突，牺牲视觉冲击。

数字是编的

在提示词里写死：

所有数字如果没有真实来源，写占位符并明确标注为示意，不要估算，
不要编。哪些数字需要我提供，列出来。

已经生成的，让它逐个标出来源：

把页面里所有数字列出来，逐个说明来源。你自己生成的、没有来源的，
标为待核实。

状态没做全

这是 AI 设计最常见的失败。直接要求：

按 state coverage 补全：空态、加载态、错误态、单条数据、大量数据。
错误态要说明怎么恢复，空态要给出下一步动作。

一眼能看出是 AI 做的

跑 反 AI 味自查。常见成分：紫蓝渐变、通用图标、默认三栏、编造的用户数、均匀的信息密度。

导出

PPTX 转过去很多东西没了

正常。Three.js 场景、依赖 JS 的交互、CSS 高级特性都过不去。

如果最终交付一定是 PPTX，倒推着做：动效那一步少做，别上 3D，功夫花在排版和图表上。

PDF 里图表糊了

要求矢量渲染：

导出 PDF 时图表用 SVG 渲染，不要位图。

内联 HTML 太大发不出去

图片是 base64 塞进去的。两个办法：先压缩图片，或者改成外链加 ZIP 打包。

深色页面导出 PDF 变成大黑块

打印场景通常要浅色版：

导出 PDF 之前生成一个打印版本：浅色底、深色字，去掉背景动效和
装饰性渐变，图表改成浅色底。

演示现场

投影上掉帧

Three.js 场景在外接投影和屏幕共享时经常撑不住。上台前必须在真机真投影上测一遍。撑不住就换 CSS 动画。

投影上字太小

浏览器里合适的字号，投影到大屏、观众坐在后排时经常不够。全屏预览之后退到房间最后一排的距离看一眼。

远程共享时动效变糊

视频编码会毁掉细腻的动效。远程场合就把动效减到最少，或者干脆用 PDF。

现场打不开

永远导一份 PDF 备份。不是因为 OpenDesign 不稳，是因为现场的电脑、转接头、网络都不归你管。

还是不行

• pnpm tools-dev check 的输出是最快的第一手信息。
• GitHub Issues 搜一下同样的症状。
• Discord 里问。
• 官方快速开始页有一份简短的排错清单：open-design.ai/quickstart。