页面打不开或任务一直排队
| 现象 | 先检查 | 怎么处理 |
|---|---|---|
| 浏览器无法连接 | 启动 RepoCare 的终端是否已退出；访问的端口是否与启动时一致 | 按部署与运维重新启动，使用终端显示的实际地址 |
| 端口被占用 | 是否已经运行了另一个 RepoCare | 复用已有实例或换一个空闲端口；不要结束身份不明的进程 |
| 页面正常，但体检一直“等待执行” | 打开 /api/health，看 worker 是否为 true | 用 npm run dev 或 npm start 启动完整服务；只运行 npm run start:web 不会启动 Worker。确认 Web 和 Worker 使用同一个数据库 |
| PR 审查或维护调查一直排队 | 维护 Agent Worker 的日志 | 确认 Agent Worker 正在运行。健康检查接口不检查它 |
| 复现或贡献路径验证一直排队 | 复现 Worker 是否在线、Docker 是否运行 | 见下方隔离验证无法执行 |
| 进度迟迟不刷新 | 任务的持久状态；反向代理是否缓冲了实时事件 | 重新打开任务查看保存的状态；管理员检查代理是否支持不缓冲的 SSE |
仓库或分支读取失败
- 地址或分支错误：核对仓库 URL、所有者、仓库名和分支名是否存在。
- 私有仓库：确认当前身份已在GitHub 账户中授权仓库访问，并且你的 GitHub 账户本身有该仓库的权限。
- GitHub 限流：未登录时 GitHub 对匿名请求的额度很低，频繁刷新可能触发 403。等待额度恢复，或登录 GitHub，或由管理员配置
REPOCARE_GITHUB_TOKEN。 - 连错了项目：先切换回正确的项目再查看任务，不能用旧项目的报告解释新项目。
找不到某个 Issue 或 PR？ 列表搜索和筛选只作用于当前页（每页最多 30 条）。检查分页、筛选条件和 PR 的目标分支，不要立即判断数据丢失。草稿搜索则覆盖当前项目的全部草稿。
常见错误提示
| 提示 | 原因 | 处理 |
|---|---|---|
| 无法连接外部服务（GitHub 或模型接口） | 服务端访问 GitHub 或模型接口时网络超时、连接中断或被代理拦截 | 检查服务器网络和代理设置。浏览器能打开网站不代表服务端能访问 API |
| 模型服务拒绝授权（HTTP 401 / 403） | API Key 无效、过期，或没有该模型的权限 | 在模型连接中更新密钥，并核对 Key 与地址属于同一平台 |
| 模型服务返回余额不足或付费限制（HTTP 402） | 账户余额或付费状态问题 | 在服务商后台核对 |
| 模型服务限流或额度受限（HTTP 429） | 请求过于频繁或额度用尽 | 稍后重试，核对服务商限制 |
| 模型服务未找到接口或模型（HTTP 404） | 协议、基础地址或模型 ID 不匹配 | 基础地址不要包含 /chat/completions 等路径；核对模型 ID 拼写 |
| 模型请求超过 60 秒未完成 | 服务响应慢或任务过大 | 稍后重试，或换用响应更快的模型 |
| 模型输出达到本次长度上限，结果不完整 | 输出被截断；推理内容也可能占用输出预算 | 缩小输入范围，或在高级设置中核对最大输出 |
| 模型请求结束但没有可用文本 | 模型只返回了推理内容、工具调用或不兼容的响应 | 核对模型与协议是否兼容，主动测试连接 |
| 当前 GitHub 账户没有该仓库的写入权限 | 发布需要写权限 | 换用有写权限的账户，或下载草稿交给有权限的维护者 |
| PR 已有新提交，请重新分析后再发布 | 审查结论对应的 head 已经过时 | 重新审查后再生成草稿 |
| 默认分支已更新，请重新体检并生成草稿 | 文档改进基于旧提交 | 重新体检，再生成草稿 |
| GitHub Checks 无法读取 | 权限、额度或服务暂时不可用 | 稍后刷新；这不代表检查已通过 |
模型保存成功但调用失败
保存连接只说明配置已经写入，不代表能用。依次检查服务地址、协议、模型名称、API Key 权限和服务商额度，然后在模型连接中点击“测试连接”。测试通过后再重试业务任务；测试本身也可能计费。
网络超时、限流、协议不兼容和工具调用失败需要分别处理。模型连接页的“最近模型请求诊断”会列出本账户最近 5 次请求的结果，可以帮助判断是哪一类。
提示密钥无法解密？ 检查是否更换了 REPOCARE_MASTER_KEY，或恢复数据库时遗漏了配套的 .model-key 文件。不要删除旧密钥重新生成，那样旧连接将永远无法解密。见备份与恢复。
登录、邮件或授权异常
- GitHub 回调失败：核对浏览器访问地址、
REPOCARE_APP_URL和 GitHub OAuth 应用中的回调地址/api/auth/github/callback，协议和端口都要一致。 - 收不到邮件：检查垃圾邮件文件夹、SMTP 配置和服务端的发送错误，避免连续申请造成混淆。
- 切换登录方式后看不到历史数据：匿名、邮箱和 GitHub 是不同的身份，数据不会自动合并。确认你进入的是原来的身份。
审查结果不完整或已经过时
打开任务的覆盖范围，区分失败块、截断文件和未审文件。有失败块时先排查模型错误，再点击“仅重试失败块”。PR 有新提交后，旧 head 的结果只能作为历史参考，需要重新审查。
CI 未知不等于成功；AI 审查完成也不等于 CI 通过，两者要分别查看。
隔离验证无法执行
按顺序检查：
- Docker Engine 或 Docker Desktop 正在运行；
- 执行镜像已构建（
npm run repro:image）； .env.local中REPOCARE_REPRO_ENABLED=true，并且修改后重启过服务；- 复现 Worker 在线。
附带的 Docker Compose 不包含复现 Worker，只启动 Compose 无法完成隔离验证。
依赖准备受阻时，先看日志中缺少哪个依赖、是否被网络限制拦截，再调整经过审阅的计划。超时、环境缺失和测试断言失败含义不同，请保留原始结果；不要把环境错误记为“Bug 已修复”或“Bug 不存在”。
草稿无法保存或发布
- 保存冲突：提示“服务端版本已变化”时，先比较当前服务端版本，合并需要的内容后再保存。
- 发布按钮不可用：查看“交付准备”中列出的原因——未保存修改、内容检查阻断、已归档、缺少写入权限等。
- 结果待核对：先点击“读取 GitHub 最新状态”，再到 GitHub 核对是否已经出现对应的 PR 或评论，避免重复创建。仍然无法确认时，保留任务标识和错误信息交给管理员。
向管理员反馈
请提供：发生问题的页面、操作步骤、预期结果、实际结果、发生时间、任务标识，以及脱敏后的错误摘要。
不要提供 API Key、Cookie、Authorization 请求头或完整的 .env.local。管理员应先查看对应服务的日志，再决定重试还是恢复。