> ## Documentation Index
> Fetch the complete documentation index at: https://docs.redbit.one/llms.txt
> Use this file to discover all available pages before exploring further.

# 排障手册

> 覆盖生成失败、视频慢、模型不一致、Agent 无法完成、i18n 异常和供应商错误的实用排障表。

# 排障手册

当用户已经选择 Redbit 工作表面和供应商路线，但流程失败时，用本页排查。先从可见症状开始，再检查路线、模型、输入、存储和 Agent/runtime 边界。

## 谁应该阅读本文

| 读者      | 适合在什么时候使用                                   |
| ------- | ------------------------------------------- |
| 第一次使用者  | 生成、视频、供应商或 Agent 任务失败                       |
| 支持或成功团队 | 客户沟通时需要结构化恢复表                               |
| 技术执行者   | 需要区分 Redbit 工作区状态、供应商、中继、浏览器和 Local Core 问题 |

## 排障前

先记录卡片或 Agent 错误、所选模型家族和变体、直接供应商或中继路线、输入参考、可用的浏览器 console 错误，以及是否配对 Local Core。不要把真实 API key 粘贴到支持记录中。

## 排障表

| 症状               | 可能原因                                            | 检查项                                                               | 恢复方式                                                                              |
| ---------------- | ----------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| 生成立即失败           | 缺少 key、endpoint 错误、不支持的模型变体、输入无效，或浏览器网络/CORS 问题 | Settings 供应商路线、API key 类型、base URL、所选变体、卡片输入要求、供应商控制台             | 重新填写 Settings，选择受支持模型，移除无效参考，先重试单张卡片再批量生成                                         |
| 供应商返回明确错误        | 供应商额度、计费、地区、安全拒绝、中继映射或 payload 不匹配              | 供应商控制台、响应信息、中继能力提示、所选媒体类型、payload 要求                              | 处理供应商账号问题，降低输入复杂度，切换路线，或选择中继支持的模型                                                 |
| 视频很慢或像是卡住        | 供应商排队、时长过长、分辨率过高、首尾帧处理或轮询延迟                     | 时长、分辨率、变体、供应商状态、卡片是否有 task ID 或 pending 状态                        | 等待供应商轮询，尝试更短时长、更低分辨率、fast 变体或排队压力更小的路线                                            |
| Seedance 参考错误    | 缺少必需首帧、尾帧或多参考输入，或参考角色混用                         | 所选 Seedance 模式、参考角色、prompt 引用 token、卡片校验信息                        | text-to-video 不带参考；image-to-video 带首帧；first/last 带两个端点帧；multi-reference 至少带一个自由参考 |
| 模型输出不一致          | 模型家族、变体、安全过滤、参考强度、prompt 理解或供应商后处理不同            | 模型家族、变体、比例、可用 seed 或设置、源参考、prompt 改动                              | 在相同设置下对比，置顶偏好的输出，收紧 prompt/参考规则，不期待供应商完全一致                                        |
| 开启中继后模型消失        | 中继能力过滤不包含该家族或变体                                 | 中继供应商、自定义中继模型列表、媒体类型、Model Registry 支持                            | 切到直接供应商，选择中继支持的模型，或加入已验证自定义中继 ID                                                  |
| Agent 说完成但没有媒体   | 工具只返回文本、工具内部生成失败、目标卡片不存在，或 runtime 缺少工具能力       | Agent 工具记录、归一化 `{ success: boolean }` 结果、新建 Cards、当前标签、能力 profile | 明确要求创建/生成卡片，运行 capability test，检查卡片错误，或手动生成                                       |
| Agent 无法完成任务     | 请求模糊、具有破坏性、包含外部副作用，或当前工具/runtime 不支持            | 原始请求、目标 ID、工具可用性、确认要求、Agent runtime profile                       | 缩小目标，确认风险动作，选择有能力的 runtime，或拆成手动步骤                                                |
| i18n 或语言显示异常     | locale store 不一致、缺少翻译 key、key 路径错误或浏览器状态陈旧      | 当前语言设置、可见 key 文本、相邻翻译 key、浏览器刷新                                   | 切换语言并刷新，报告准确 key/path，后续 UI 编辑避免 inline language branching                        |
| 素材消失或无法选择        | 未置顶最近素材被清理、浏览器存储清除、配额压力，或项目/全局 picker 范围不匹配     | Asset Dock 置顶状态、SmartPicker 模式、浏览器站点数据、项目上下文                      | 重新导入源素材，置顶重要输出，切换 picker 范围，导出重要项目                                                |
| Local Core 功能无响应 | 本地引擎未运行、配对失败、端口被阻塞、二进制错误或功能未启用                  | Local Core 进程、pairing code、本地 endpoint、浏览器/网络错误                   | 重启可信本地引擎，重新配对，确认确实需要该功能，或改用浏览器侧流程                                                 |
| 导出缺少预期文件         | Workshop 阶段未完成、输出未生成、导出模式不匹配，或包路径未支持            | Workshop 项目场景、选中媒体、导出模式、已有生成资产                                    | 补齐缺失阶段，选择最终资产，重试导出，或交接已下载 Card 输出                                                 |

## 升级排查包

需要支持继续调查时，请包含：

| 字段    | 包含内容                                                         |
| ----- | ------------------------------------------------------------ |
| 工作表面  | Cards、Series、Workshop、Agent、Seedance、Model Registry/Settings |
| 路线    | 直接供应商、中继供应商、自定义中继、Local Core 或浏览器侧                           |
| 模型选择  | 家族、变体、比例、时长、分辨率；相关时包含 Agent runtime profile                  |
| 输入形态  | prompt、文件类型、参考角色，以及参考来自上传、Asset Dock 还是 SmartPicker          |
| 错误证据  | 卡片错误文本、供应商响应摘要、Agent 工具结果、浏览器 console 摘要                     |
| 已尝试恢复 | Settings 更新、重试、路线切换、输入简化、Local Core 重启、语言刷新                  |

## 下一步

安全敏感问题请看 [安全与凭据](./security-credentials.mdx)。Seedance 参考规则请看 [Seedance 视频工作流](./seedance-video.mdx)。