feat: 初始化 AstroResearch 核心系统代码及重构技术文档

2026-06-08 17:23:27 +08:00
commit 307a1c0cee
53 changed files with 45076 additions and 0 deletions
@@ -0,0 +1,44 @@
+# AstroResearch Troubleshooting / 常见问题与排障指南
+
+在使用 AstroResearch 过程中可能遇到的问题及排障步骤如下：
+
+---
+
+## 1. 文献下载相关问题 (Download Issues)
+
+### 1.1 下载任务遇到 "检测到 Cloudflare / 人机验证页面"
+- **原因**：部分出版商对频繁的自动化下载请求实施了高强度的 IP 拦截与 CF 校验。
+- **解决方法**：
+  1. 系统目前已经实现每两次请求间随机延迟 `maybe_delay()` (500ms~2000ms)，以防行为过于机械化。
+  2. 若拦截频繁，可以尝试在本地配置代理；或者检查 `.env` 中的 `LIBRARY_DIR` 路径是否正确。
+  3. 对于 ADS Link Gateway 路由，若跳转至 `validate.perfdrive.com`，下载器内置了解码 `ssc` 提取直链的策略，该过程自动进行，如果由于其加密机制变更导致提取失效，系统控制台会输出 `warn` 日志。
+
+### 1.2 官方 HTML (arxiv.org/html) 下载返回 404
+- **原因**：arXiv 官方 HTML 正文服务仅在 **2023年12月** 之后提交的论文中默认提供。对于老文献，直接请求官方 HTML 会返回 404。
+- **解决机制**：AstroResearch 的 `download_arxiv_html_with_fallback` 会在官方 HTML 请求失败时，**自动无缝降级回退**到 `ar5iv.labs.arxiv.org` 服务进行拉取。
+
+---
+
+## 2. 文献解析与翻译问题 (Parse & Translation Issues)
+
+### 2.1 翻译请求返回空或报错 "LLM API KEY Missing"
+- **原因**：根目录下没有配置正确的 `.env` 文件，或者 LLM 提供的 Endpoint/Model 有误。
+- **排查步骤**：
+  1. 确认项目根目录下存在 `.env` 且拥有 `LLM_API_KEY` 及 `LLM_API_BASE` 配置。
+  2. 使用终端运行 `cargo run`，检查启动日志中是否有关于读取环境配置的警告信息。
+
+### 2.2 PDF 解析缺少图表或公式损坏
+- **原因**：PDF 格式本身不支持结构化语义。直接提取文本会丢失公式和图表。
+- **解决机制**：
+  1. 如果文献有 HTML/ar5iv 格式，系统会自动优先基于 HTML 解析，保留完美的 LaTeX 公式。
+  2. 若该文献只有 PDF 格式，系统自动降级调用本地或远程的 **MinerU** PDF 图文大模型解析。请确保本地 MinerU 解析服务已按照 API 格式运行并在 `.env` 中正确填入 `MINERU_API_URL`。
+
+---
+
+## 3. 数据库与运行环境问题 (Runtime & DB Issues)
+
+### 3.1 启动提示 "Database Migration Failed"
+- **原因**：本地 SQLite 数据库文件 `astro_research.db` 出现并发锁死或版本 schema 冲突。
+- **解决方法**：
+  1. 备份并临时删除根目录下的 `astro_research.db` 数据库文件。
+  2. 重新启动服务：`cargo run`，系统将重新执行 `migrations/` 下的全部 SQL 迁移脚本以建立最新库结构。