项目架构与能力

AstroLib 是什么

AstroLib 是一个以 Astro 和 Starlight 为基础的学术数字书库。它把教材正文、公式、图像、习题和章节关系组织成可阅读、可检索、可导出的内容系统，而不是只生成一组静态网页。

面向读者的主要能力

Material You 风格：界面使用 Material 3 组件和动态主题，支持亮暗模式、字体选择与窄屏布局。
数学排版：Markdown/MDX 中的 LaTeX 数学公式由 KaTeX 渲染，并可复制源码或导出为图片。
章节 LaTeX / PDF 导出：当前章节可以导出学术排版的 .tex、离线编译 ZIP，或在本机调用 XeLaTeX 生成 PDF。
全书 EPUB 导出：scripts/generate-epub.mjs 将书籍 MDX、图片、KaTeX 样式和字体组装为离线电子书。
配套习题册：题库源数据经过构建脚本转换为静态数据，阅读页中的习题侧栏可按章节筛选、查看解析并请求 AI 讲解。
跨页引用：正文中的章节、定理和卡片引用可定位到目标原文；构建期会生成跨引用数据。
知识体系框架：关系图谱、模块索引和章节检索由构建期索引支持，便于从一处概念回到相关章节。
Agent / MCP 与 AI 问答融合：AI 问答使用书内索引做检索，再由用户自己的 API Key 调用 Gemini、DeepSeek 或自定义 OpenAI 兼容模型。项目不替用户托管密钥。

数据流

MDX 正文 + images/
        │
        ├─ collections.config.mjs   书籍元数据、章节入口、卡片规则
        ├─ features.config.mjs      功能开关与 AI 模型清单
        │
        ├─ build-ai-index.mjs       public/ai-index/
        ├─ build-exercise-data.mjs  public/data/exercises/
        ├─ build-cross-ref-data.mjs public/cross-ref/
        ├─ build-relation-graphs.mjs
        └─ Astro build              dist/

生成数据可以删除并重建，不能反过来当作原始内容编辑。正文只在 src/content/docs/collections/ 维护。

重要边界

UI 组件不作为书籍或题库模型的来源；模型放在配置、src/data 或对应服务层。
发布器只处理输入和输出，不依赖阅读页组件。
开发期编辑器可以写回 MDX，但生产运行时不应修改源文件。
AI 索引、关系图和题库数据都是派生物；修改正文后应重新运行对应构建脚本。