故障排查
本页解决：客户端出现错误时，先看哪里、先做什么，以及哪些操作会让问题变大。
通用排查顺序
- 看清错误发生在哪一步。登录、读取项目、模型回合、生成、预览、打包、上传是不同链路。
- 确认账号。看账户菜单里的账号和陶泥号是否属于你当前要使用的账号。
- 确认项目目录仍在。项目可能被移动、重命名、删除，或当前账号没有读写权限。
- 先重试一次。网络类失败可以重试；付费生成和“结果未知”不要连续重复提交。
- 保留现场再反馈。记录错误原文、时间、项目名、模型和操作步骤。
登录与账号
一直停在登录或提示未登录
- 检查网络是否能正常访问登录服务。
- 切换过账号后，重新登录一次；不要复用旧窗口里的会话。
- 如果客户端时间明显不准，先校准系统时间，再重试。
账号正确，但项目或余额不对
先看账户菜单里的账号身份。不同账号的数据是隔离的。退出后重新登录不会自动迁移本地项目。
邀请码、兑换码不可用
核对大小写、有效期、适用账号和使用次数。提示“已使用”时不要换账号重复尝试；先确认这个码是否属于当前账号。
模型与对话
模型列表为空或模型不可选
- 确认登录状态和会员/模型权限。
- 点输入区的模型选择器重新打开，或重启客户端刷新目录。
- 检查当前是「做游戏」还是「做方案」，两条分支允许的模型可能不同。
- 如果刚切换账号，等账户信息刷新完再选模型。
提示模型不可用
选中的模型可能已下架、当前账号无权使用，或与当前分支协议不兼容。重新选一个可用模型再发送。不要通过修改本地配置文件强行使用未授权模型。
提示泥点不足
打开账户菜单确认余额。充值到账后重新发送。余额不足时不要反复点发送，客户端不会因为重试而免除扣费。
模型服务暂时不可用
这通常是上游服务或平台额度同步的临时故障。等待后重试，或换一个可用模型。不要连续重发同一轮长任务；先看上一轮是否已经产生了结果。
回合一直不结束
先点输入区的「终止」结束当前回合。终止后保留已经产生的正文、工具记录和文件变化，不代表所有步骤都成功。需要继续时，先看执行过程和文件变化，再发一条明确的补充指令。
切换会话后看不到原来的回合
会话切换不会中断正在运行的回合，但不同会话的历史是分开的。用对话栏顶部的会话列表切回对应会话；历史读取失败时，列表顶部会给出重试入口。
项目目录
打不开项目
- 确认目录还存在。
- 确认目录不是快捷方式、网络盘断开或权限不足。
- 确认没有被另一个程序独占。
- 如果项目是从别处复制来的，检查
.agent目录是否完整。
提示项目布局变化
项目结构变了，.agent/layout.json 记录的位置可能不一致。客户端会弹窗让你按当前目录重新识别。确认后只更新项目配置，不会改工程文件。识别失败时先确认目录可读。
从项目组移除项目后，磁盘上的文件还在吗
「从列表移除」只把项目从最近列表移除，不删除磁盘目录。要彻底删除，请在文件管理器里删除项目文件夹，并确认没有正在运行的预览或生成任务。
生成与资源
生成失败
打开「生成任务」侧栏看失败原因。失败占位可以原地重试，重试会沿用原来的参考图和请求身份。不要删除占位后再新建一条相同请求，否则可能变成新的付费提交。
生成一直停在排队或生成中
- 确认网络和账号仍然有效。
- 查看生成任务侧栏，不要只看画布占位。
- 切换项目或关闭面板不会取消后台任务。
- 重启客户端后，已提交任务会从恢复队列重新读取。
提示结果未知或需要核对
这表示请求可能已经到达服务端，但客户端没有拿到确定结果。不要直接重新提交。先等待对账或查看恢复面板；需要重试时按面板给出的明确入口操作。
参考图不能用
参考图必须是同一项目里已登记、当前账号可访问的图片。以下资源不能作为参考：
- 文档、音频、视频、3D 模型。
- 尚未登记的本地文件。
- 其他项目的素材。
- 已删除或权限失效的素材。
图标素材和 UI 设计图可能要求先生成或绑定规范图。缺规范图时，先在对应栏目生成规范，再回来提交。
图片/音频/模型显示无法解码
文件可能损坏、扩展名和内容不匹配，或使用了当前运行环境不支持的编码。先重新生成或替换素材；如果原始文件在磁盘上还能打开，再检查格式并重新导入。
运行与预览
运行失败时会弹出一个带现场日志的面板。按钮不是每次都一样：
| 按钮 | 什么时候出现 | 作用 |
|---|---|---|
| 重试 | 所有失败 | 按当前配置再启动一次 |
| 识别项目布局 / 更新项目配置 | 布局识别失败 | 按当前目录重新识别，不改工程文件 |
| 允许安装脚本后重试 | 依赖安装或启动命令失败 | 重新安装依赖并允许依赖执行安装脚本 |
| 清理依赖并重装 | 上一轮允许脚本后仍失败 | 删除 node_modules 后整棵重装 |
如果提示端口被占用、Node/npm 不可用或工程缺少入口，先修环境和工程，再重试。清理依赖只影响依赖目录，但安装过程可能更新锁文件。
预览窗口是空白
- 看运行失败面板是否给出了真实原因。
- 点「在浏览器打开」确认是项目页面问题还是客户端内嵌页面问题。
- 确认构建产物存在，开发服务器已经启动。
- 检查项目是否用了外部网络、动态代码生成或不允许的嵌套文档；这类内容可能被发行沙箱拦截。
打包与发布
没有打包脚本
首次使用某个导出目标时，先让陶泥儿帮你调通。它会补构建入口并实际产出一个包。之后每次点「打包」都重新运行构建。
打包命令失败
看失败面板里的构建日志尾部。常见原因：
- 依赖没有安装。
- 构建脚本名不对。
- 工程入口文件缺失。
- 打包产物没有生成在约定位置。
- 包体超过平台上限。
能让陶泥儿修的内容，点「让陶泥儿修复」并把现场交给它；平台登录、账号权限和提审资料仍要你自己处理。
发布到陶泥儿平台失败
先区分是打包失败、上传失败还是审核未通过。打包失败看构建日志；上传失败看网络、登录和包体限制；审核未通过看后台审核意见。不要为了绕过审核反复发布相同版本。
第三方平台上传失败
确认对应的 CLI 或平台账号已经登录，并且当前账号有发布权限。客户端不保存第三方平台的登录凭据；需要登录时按提示在浏览器完成。也可以先下载产物，手动到平台后台上传。
更新与启动
检查更新失败
先确认网络和当前安装版本。更新失败不会影响当前版本使用，但不要手工替换安装目录里的单个文件。
客户端启动后白屏
先完全退出客户端再启动。仍失败时检查是否有损坏的本地配置。保留版本号和启动时间，提交反馈。
反馈时请带上
- 客户端名称和版本。
- 账号陶泥号（不要发密码或验证码）。
- 发生时间与操作步骤。
- 错误提示原文或截图。
- 如果是项目问题：项目名、项目目录是否可读、是否复制/移动过。
- 如果是生成问题：任务类型、模型、是否已扣费、任务侧栏状态。
不要提交 .env、API Key、Token、Cookie、私钥、完整对话记录或包含个人路径的日志。