# AstroResearch 天文科研辅助系统

AstroResearch 是一个基于 **Rust (Axum)** 后端与 **React (Vite + TypeScript)** 前端的天文文献一体化科研辅助系统。

---

## 1. 功能概述 (Overview)

AstroResearch 为天文领域的学者与研究人员提供一站式的文献管理与智能阅读解决方案，核心功能包括：

- 🌌 **统一学术检索**：一键跨源检索 NASA ADS 与 arXiv 数据库，支持去重元数据卡片式展示、高级组合条件检索与多种排序方式。
- 📥 **多通道文献同步与防爬绕过**：支持智能后台下载（官方 HTML / ar5iv 回退）、网页端本地 PDF/HTML 手动离线上传，以及浏览器书签脚本一键直推同步（无惧 Cloudflare 等高强度 WAF 拦截）。
- 🏷️ **下载错误诊断与无资源标记**：自动记录每篇文献 PDF/HTML 下载失败的具体原因（数据库 `error:` 前缀字段），支持一键标记"无有效全文资源"并从批量任务中排除。
- 📝 **结构化文献解析**：解析 HTML 或调用 MinerU (PDF 降级解析) 输出标准 GFM Markdown，对 LaTeX 公式实施占位符保护。
- 🗣️ **大模型双语翻译**：基于本地天文学词汇库 (Trie 树最长匹配) 构建翻译 Glossary，指导大模型进行公式级精准中英翻译。
- 🪐 **引文网络星系图**：基于 HTML5 Canvas 的高性能力导向拓扑渲染，双击节点支持引文深度探索。
- ✍️ **划词高亮与笔记**：在双语阅读器中自由划词、多色高亮并记录学术心得，数据与文献双向绑定。
- 🩺 **馆藏健康度检查**：内置诊断与修复工具，检测数据库与物理文件的不一致性并支持一键自动修复。

---

## 2. 快速启动 (Quickstart)

### 2.1 配置环境变量
将根目录下的 `.env.example` 复制并重命名为 `.env`：
```bash
cp .env.example .env
```
用编辑器打开填入你的 `ADS_API_KEY`、`LLM_API_KEY`、`QINIU_` 等第三方服务的认证 Token。

### 2.2 运行服务 (Run)

#### 方案一：本地开发调试模式 (Development Mode)
开发模式下分别启动后端 API 服务和前端 HMR 热更新服务：
1. **启动后端 (Rust Axum)**：
   ```bash
   cargo run
   ```
   后端服务默认运行在 `http://localhost:8000`，并会自动初始化本地 SQLite 数据库及运行 migrations 迁移。
2. **启动前端 (React Vite)**：
   ```bash
   cd dashboard
   npm install
   npm run dev
   ```
   前端开发服务器默认运行在 `http://localhost:5173`。前端的所有 `/api` 接口请求已配置反向代理，会自动转发到后端的 `8000` 端口。

#### 方案二：生产打包与单程序部署模式 (Production Mode)
生产模式下需要先编译前端静态文件，随后由后端进程统一托管分发：
1. **打包编译前端**：
   ```bash
   cd dashboard
   npm install
   npm run build
   ```
   静态资源将打包并输出在项目根目录下的 `dashboard/dist/` 目录。
2. **运行后端服务**：
   * **方式一：外部命令行模式**（默认）：
     ```bash
     cd ..
     cargo run --release
     ```
     *注意：默认模式下需下载 Obscura 二进制文件并放置在项目根目录的 `bin/` 目录下。*
   * **方式二：进程内浏览器模式**（免外部二进制分发）：
     ```bash
     cd ..
     cargo run --release --features obscura-inprocess
     ```
     *此时无头浏览器将直接编译进主二进制中，首次编译较慢但能一键运行。*

   运行后直接访问 `http://localhost:8000` 即可使用，此时所有 React 网页和后台 API 均由 Rust 进程统一分发托管，无需额外启动 Vite。详细配置说明参见 [编译与部署指南](docs/deployment.md#4-obscura-两种抓取后备部署模式选择-obscura-deployment-modes)。

### 2.3 馆藏文献健康度检查与修复 (Health Check)
系统提供内置的健康度校验脚本，可用于排查与自动修复数据库状态和物理磁盘文件的不一致问题：
- **只读扫描模式**：检测损坏文件、丢失文件、报错记录和孤立 Markdown，不改动任何数据。
  ```bash
  cargo run --bin health_check
  ```
- **自动修复模式**：物理清理磁盘损坏/无源文件，将失效路径重置为 `NULL`（安全保留 `error:` 报错诊断日志）。
  ```bash
  cargo run --bin health_check -- --fix
  ```

---

## 3. 技术文档结构 (Documentation Directory)

- 🏗️ **[架构设计](docs/architecture.md)** — 系统宏观架构、Agent 子系统、Mermaid 流程图
- 🌐 **[API 接口规范](docs/api.md)** — 全部 Axum REST 端点与 SSE 事件
- 🗄️ **[数据库设计](docs/database.md)** — SQLite 表结构、ER 图、迁移历史
- 🛠️ **[开发指南](docs/development.md)** — 构建/测试/环境变量/项目结构
- 🎨 **[视觉设计](docs/design.md)** — UI 设计系统与交互体验
- 🚀 **[部署指南](docs/deployment.md)** — 生产构建与发布
- 🔧 **[排障指南](docs/troubleshooting.md)** — 常见问题与解决方案
- 🤝 **[参与贡献](docs/contributing.md)** — 代码规范与测试要求

---

## 4. 项目目录结构 (Project Structure)

```
AstroResearch/
├── src/
│   ├── main.rs                  # Axum 服务入口：路由、中间件、静态资源托管
│   ├── lib.rs                   # Config 配置加载
│   ├── api/                     # HTTP handlers + AppState
│   │   ├── agent.rs             #   SSE 智能体对话、会话管理、指标、审计
│   │   ├── papers.rs            #   文献检索/下载/解析/翻译/引文/导出
│   │   ├── notes.rs             #   笔记 CRUD
│   │   ├── sync.rs              #   批量同步
│   │   ├── targets.rs           #   天体目标识别
│   │   └── helpers.rs           #   共享工具函数
│   ├── agent/                   # ReAct 智能体引擎 (参考 Claude Code 分层设计)
│   │   ├── runtime/             #   ReAct 循环、流式执行、Token 管理、权限、熔断
│   │   ├── tools/               #   工具系统 (filesystem/ astro/ memory/ team/)
│   │   ├── compact/             #   三层上下文压缩
│   │   ├── memory/              #   项目记忆管理 (提取/去重/衰减/保活/护栏)
│   │   ├── team/                #   多 Agent 团队协作
│   │   ├── hooks.rs             #   生命周期事件系统
│   │   ├── skills.rs            #   技能注册表 (热加载)
│   │   ├── subagent.rs          #   上下文隔离子代理
│   │   └── terminal.rs          #   循环终止信号
│   ├── clients/                 # 外部 API 客户端 (ADS, arXiv, LLM, Qiniu)
│   ├── services/                # 业务逻辑
│   │   ├── parser/              #   HTML/PDF → Markdown 解析器 (A&A, IOP, ar5iv, MinerU)
│   │   ├── batch/               #   批量同步引擎
│   │   ├── download.rs          #   文献下载器 (反爬伪装、多级回退)
│   │   ├── translation.rs       #   LLM 翻译 + Trie 天文词典
│   │   └── rag.rs               #   向量检索增强生成
│   └── bin/                     # 独立二进制 (cli, health_check, reparse)
├── dashboard/                   # React 19 + Vite + TypeScript 前端
│   └── src/features/            #   search/ library/ reader/ citation/ agent/ sync/ settings/
├── skills/                      # Agent Skills (Markdown 知识模块)
├── migrations/                  # SQLite 迁移脚本
├── library/                     # 本地文献存储 (PDF/HTML/Markdown/Translation)
├── docs/                        # 技术文档 (架构/API/数据库/开发/部署/排障)
└── dictionary.txt               # 天文学双语名词词典
```