故障排查

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 保持数据向前兼容，新版本打开旧版本资源库会自动完成数据库迁移；旧版本客户端打开由新版本创建的资源库也会以宽容模式可写打开，不提供只读锁死状态。如果提示版本不支持，请更新到最新版 Serpent。
• 提示“资源库已打开”：同一资源库目录已被当前应用实例打开，或通过不同的路径（例如网络共享路径与盘符映射）打开了同一份库。直接切换到已打开的窗口即可。
• 自动恢复与抢救：如果遇到数据库损坏提示，不要手动删除 .serpent/ 目录。Serpent 内置轮换备份机制，打开时会自动尝试使用最近的有效备份恢复；极端损坏情况下会进入 Assets 目录自动抢救流程，尽可能保留全部源文件与元数据。
• 权限与空间：确认资源库所在磁盘及临时目录具备充足的读写权限与可用磁盘空间。
• 从归档导入：从 ZIP / Eagle / Billfish 导入时，确保系统临时目录与目标磁盘均有足够解压和存储空间；解压完成后缩略图与元数据会在后台逐步重建。

快捷键无反应

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

仍有问题

可以在「主菜单 → 关于 → 查看诊断日志」查看当前日志（亦可在该窗口中点击「显示日志文件」，或通过「主菜单 → 关于 → 在文件管理器中显示日志文件」定位日志文件）。

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