常见问题
先在索引中找到你的症状，对照可能原因，再按链接处理。先看可见的任务状态和错误信息：上游缓慢、任务排队和浏览器断线需要不同的处理方式。
症状索引
| 症状 | 可能原因 | 前往 |
|---|---|---|
| 检索耗时很长 | 任务排队、预算较大或上游阶段缓慢 | 检索问题 |
| HTTP 401 / 403 | 密钥错误或服务商账户权限不足 | HTTP 错误 |
| HTTP 404 | 基础地址、协议、路由或模型错误 | HTTP 错误 |
| HTTP 429 | 服务商速率限制或余额不足 | HTTP 错误 |
| 连接失败 / 超时 | 网络可达性或服务商可用性 | HTTP 错误 |
| 在线版拒绝了接口地址 | 非公开地址（localhost、内网） | 在线版拒绝了模型地址 |
| 没有结果、缺摘要或数量不一致 | 查询限制过严或来源记录有缺口 | 没有结果 |
| 引用图谱为空 | 数据源不支持扩展，或预算内没有可用链接 | 引用图谱为空 |
| 综述大纲或正文失败 | 模型可用性或服务商错误 | 综述大纲或正文生成失败 |
| 本地服务无法启动 | Python 版本、数据库路径或端口冲突 | 本地服务无法启动 |
| 登录或邮件验证码问题 | 垃圾邮件、验证码过期或已被替换 | 账户与登录 |
检索问题
检索耗时很长
先区分排队中与执行中。执行期间，检索式改写、数据源请求、引用扩展和模型评分都可能耗时。更大预算允许更多工作，但不保证得到更多有用结果。
页面断线时，先重新打开已保存的运行查看状态，再决定是否重新提交。在线匿名检索的结果是临时的，见数据与隐私。
没有结果、缺摘要或数量不一致
放宽问题、去掉过严的领域限制，或换用更合适的数据源。数据源命中数量不等于已下载数量，已下载的候选也不等于最终排序结果。
摘要、引用数或 PDF 缺失可能来自来源记录本身。PaperSeek 不会从其他来源独立补全缺失的摘要。
引用图谱为空
确认运行使用了支持引用扩展的数据源，并且启用了扩展。即便如此，来源也可能在当前预算内没有提供可用引用关系。
HTTP 与服务商错误
HTTP 401、403、404 或 429
| 错误 | 检查 |
|---|---|
| 401 / 403 | 密钥是否正确、服务商账户权限、所选模型 |
| 404 | API 基础地址、协议、路由、模型可用性，或任务/资源是否存在 |
| 429 | 服务商速率限制，或结构化的余额不足错误 |
| 连接失败 / 超时 | 网络可达性与服务商可用性 |
OpenAlex 运行中显示的 404，并不证明一定是 OpenAlex 返回的：任务中还会调用模型和应用接口。请记录阶段、安全错误码、任务 ID 和时间。
PaperSeek 服务的积分与上游服务商的余额是两套限制，增加其中一个不会改变另一个。
在线版拒绝了模型地址
在线版自带密钥模式会拦截 localhost、内网地址等非公开目标。请使用公开的服务商接口地址，或在社区版中连接自己电脑上的模型。地址有效之外，还必须实现所选的 API 协议。
综述问题
综述大纲或正文生成失败
综述写作是实验性功能，取决于选中的证据和模型可用性。优先选择摘要完整的文献，查看当前项目/任务状态，解决报告的服务商问题后再重试失败环节。避免反复创建重复项目。
更长的正文需要模型输出更多内容。大纲完成不代表下一次写作请求一定成功。重新生成前保留手工修改并检查版本。
本地服务
本地服务无法启动
执行 paperseek doctor --json。检查 Python 3.12+、所选数据库路径、写权限、端口冲突和模型设置。执行日志请在启动终端或服务管理器中查看；Web 界面刻意聚焦状态，不显示原始执行日志。
分开运行时，确认 API 和 worker 使用同一个数据库。
反馈可复现的问题
在 GitHub Issues 提交：
- 安装版本或在线模式、浏览器及系统、复现步骤。
- 数据源、协议、排序方式和预算。
- 期望行为、实际错误、适当的任务 ID 和大致时间。
- 不含敏感信息的最小示例，必要时附裁剪后的截图。
删除 API 密钥、密码、验证码、Cookie、私人检索问题和身份信息。安全问题请走仓库的安全反馈流程。