Asfmq 5db4cc5998 refactor: 全栈架构重构与质量硬化——API 错误统一、工具域重组、安全加固、前端组件化

后端核心变更:
  - API 层: 新增 AppError 枚举统一错误类型，替代散落的 (StatusCode, String)
  - Agent 工具域: 重组为 astro/system/ 和 astro/research/ 两级域，新增 ProcessPaperTool 流水线工具
  - 安全: 新增 SSRF 双层防护 (同步字符串级 + 异步 DNS 解析级)，覆盖 IPv4/IPv6 私网段
  - 弱密码检测: 扩展弱密码列表并增加最小长度检查
  - LLM 客户端: 新增 ChatCompleter/Embedder trait，支持依赖注入与批量向量化 embed_batch
  - 批量处理: AssetBatch 从串行改为 Semaphore 并发池 (BATCH_CONCURRENCY=3)
  - 分块器: 重写为三阶段结构化管线 (章节解析→短节合并→带标题路径子块)
  - RAG: embedding 计算移出事务，RetrievalResult 新增 headings/section_index 字段
  - 检索: ADS/arXiv 并行检索 (tokio::join!)，去重改用 HashSet，本地库回填批量 IN 查询
  - 天体查询: Sesame API 升级到 v4，新增视差误差/自行/视向速度/多波段测光字段
  - 迁移: 14 个增量文件合并为单一 init.sql，支持 sqlx::migrate! 内存库集成测试
  - 测试: circuit_breaker/hooks/task_board/session/memory/streaming_executor 新增修正 15+ 测试

  前端架构重构:
  - 目录重组: features/ → pages/ + components/ + hooks/ 三层分离
  - App.tsx 从 1181 行压缩至 ~174 行 (逻辑抽入 9 个自定义 Hook)
  - Agent 面板拆分为 AgentSessionSidebar/AgentMessageList/AgentInputArea 子组件
  - 新增 GlobalDialog/PaperDetailModal/UncachedPaperModal 通用对话框组件
  - 工具函数抽取: celestial.ts (天体坐标格式), paper.tsx (文献信息渲染)

2026-06-25 23:45:37 +08:00

7.8 KiB

Raw Blame History

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：

cp .env.example .env

用编辑器打开填入你的 ADS_API_KEY、LLM_API_KEY、QINIU_ 等第三方服务的认证 Token。

2.2 运行服务 (Run)

方案一：本地开发调试模式 (Development Mode)

开发模式下分别启动后端 API 服务和前端 HMR 热更新服务：

启动后端 (Rust Axum)：
```
cargo run
```
后端服务默认运行在 http://localhost:8000，并会自动初始化本地 SQLite 数据库及运行 migrations 迁移。
启动前端 (React Vite)：
```
cd dashboard
npm install
npm run dev
```
前端开发服务器默认运行在 http://localhost:5173。前端的所有 /api 接口请求已配置反向代理，会自动转发到后端的 8000 端口。

方案二：生产打包与单程序部署模式 (Production Mode)

生产模式下需要先编译前端静态文件，随后由后端进程统一托管分发：

打包编译前端：
```
cd dashboard
npm install
npm run build
```
静态资源将打包并输出在项目根目录下的 dashboard/dist/ 目录。
运行后端服务：
- 方式一：外部命令行模式（默认）：
```
cd ..
cargo run --release
```
  注意：默认模式下需下载 Obscura 二进制文件并放置在项目根目录的 bin/ 目录下。
- 方式二：进程内浏览器模式（免外部二进制分发）：
```
cd ..
cargo run --release --features obscura-inprocess
```
  此时无头浏览器将直接编译进主二进制中，首次编译较慢但能一键运行。
运行后直接访问 http://localhost:8000 即可使用，此时所有 React 网页和后台 API 均由 Rust 进程统一分发托管，无需额外启动 Vite。详细配置说明参见编译与部署指南。

2.3 馆藏文献健康度检查与修复 (Health Check)

系统提供内置的健康度校验脚本，可用于排查与自动修复数据库状态和物理磁盘文件的不一致问题：

只读扫描模式：检测损坏文件、丢失文件、报错记录和孤立 Markdown，不改动任何数据。
```
cargo run --bin health_check
```
自动修复模式：物理清理磁盘损坏/无源文件，将失效路径重置为 NULL（安全保留 error: 报错诊断日志）。
```
cargo run --bin health_check -- --fix
```

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

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

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/                     #   pages/ components/ hooks/ types/ utils/ assets/
├── skills/                      # Agent Skills (Markdown 知识模块)
├── migrations/                  # SQLite 迁移脚本
├── library/                     # 本地文献存储 (PDF/HTML/Markdown/Translation)
├── docs/                        # 技术文档 (架构/API/数据库/开发/部署/排障)
└── dictionary.txt               # 天文学双语名词词典

7.8 KiB Raw Blame History Unescape Escape