跳到主要内容

故障排查

macOS 无法验证开发者 / Windows SmartScreen​

开发版可能未签名公证。确认安装包来源后，macOS 右键应用选择「打开」；Windows 选择「更多信息 → 仍要运行」。不要为未知来源的包绕过系统安全提示。

缩略图或预览失败​

Serpent 会为部分图像、RAW、视频、音频和 3D 格式生成预览。先确认源文件仍可读取、资源库目录有读写权限，然后完全退出并重新打开资源库，让后台任务重试。若错误持续，打开「窗口 → 后台任务」查看提示和诊断日志。

不同格式的预览方式可能不同，例如视频可能使用兼容播放版本，音频会先生成波形。损坏或编码不受支持的源文件无法仅靠重试修复。

AI 分析失败或没有入队​

到「设置 → AI」确认 API 格式、模型和 API Key，点击「测试连接」，并确认已打开「新增资产自动进行 AI 分析」。该开关默认关闭；音频、文本和不在图像/视频/模型注册表中的格式不支持 AI。

视频 AI 需要联系表，3D AI 需要四视图；先在后台任务中重试媒体预览，再重试 AI。失败通知会显示简短原因。网络、限流和超时通常可以重试；认证、权限、额度或不支持格式需要修正配置/文件。已有 AI 结果可以再次手动分析，使用「AI 分析」而不是「AI 分析未分析项」。

搜索不到已导入资产​

检查过滤器是否仍启用，并查看过滤标签；按住 Shift 的多选值可能让结果范围更窄。搜索只在当前文件夹/合集范围内运行，悬停或聚焦输入框右侧 ? 可查看高级语法。忽略规则会同时影响浏览、搜索和扫描，到「资源库设置 → 忽略规则」检查忽略配置文件。

插件无法启用​

打开「设置 → 插件」查看插件状态和信任提示。资源库插件在每台设备首次启用时需要信任；全局插件通常自动信任。可以先关闭再重新启用插件，或点击「重载」。如果仍然无法使用，请联系插件作者，并提供 Serpent 版本、操作系统和插件名称。

自动化脚本或 MCP 无法使用​

脚本请确认已经打开资源库，并从「更多工具 → 自动化脚本」进入。MCP 请在「设置 → MCP」确认服务已启用并已启动，然后把 Serpent 复制的最新配置粘贴到客户端。默认地址为 http://127.0.0.1:47342/mcp；如果撤销过 Token，需要重新添加客户端并复制新的配置。只连接信任的本地 AI 工具。

资源库打不开​

  • “只读”通常表示库由更新版本创建、目录权限不足或迁移仍在进行；先备份目录并使用当前版本重试。
  • “损坏”时不要删除原目录，保留 .serpent/ 和日志并联系开发者。
  • 从 ZIP 导入时，先确保临时解压位置和目标位置可写；缩略图、代理和 AI 临时文件会在导入后后台重建。

快捷键无反应​

快捷键会根据当前焦点和上层窗口处理。设置、查看器和菜单打开时，它们优先处理 Esc 等快捷键；关闭这些窗口后再在画布上重试。右键菜单关闭后若 F2 未生效，先单击资产或文件夹恢复焦点。

仍有问题​

通过 GitHub Issues 反馈时附上：操作系统和版本、Serpent 版本、资源库类型、可复现步骤、错误提示/错误码，以及 .serpent/ 中相关日志。不要上传 API Key、完整 Token 或未脱敏的个人文件路径。