AstroResearch/docs/database.md

AstroResearch Database Schema / 数据库设计

AstroResearch 使用轻量级、零配置的 SQLite 数据库作为持久化存储。数据库文件默认保存在项目根目录下的 astro_research.db（可通过 .env 中的 DATABASE_URL 配置），由 Rust 中的 sqlx 驱动管理并自动执行迁移。

---

1. 实体关系图 (Entity-Relationship Diagram)

erDiagram
    PAPERS {
        text bibcode PK
        text title
        text authors "JSON Array"
        text year
        text pub "Journal/Publisher"
        text keywords "JSON Array"
        text abstract
        text doi
        text arxiv_id
        integer citation_count
        integer reference_count
        text doctype "文献类型"
        text pdf_path "PDF 物理路径 或 error:诊断"
        text html_path "HTML 物理路径 或 error:诊断"
        text markdown_path "Markdown 物理路径"
        text translation_path "翻译文件物理路径"
        datetime created_at
    }

    NOTES {
        integer id PK
        text bibcode FK
        integer paragraph_index
        text note_text
        text highlight_color
        text selected_text
        datetime created_at
    }

    CITATIONS_REFERENCES {
        text source_bibcode PK
        text target_bibcode PK
    }

    SYNC_QUERIES {
        integer id PK
        text query "检索关键词"
        text source "数据源"
        integer limit_count "拉取上限"
        datetime last_run "最近运行时间"
        datetime created_at "创建时间"
    }

    PAPER_CHUNKS_CONTENT {
        integer rowid PK
        text bibcode FK
        integer paragraph_index
        text content
        text headings "章节路径"
        integer section_index "章节编号"
    }

    PAPER_TARGETS {
        integer id PK
        text bibcode FK
        text target_name "标准化天体名称"
        text ra "赤经"
        text dec "赤纬"
        real parallax "视差 mas"
        text spectral_type "光谱分类"
        real v_magnitude "视星等"
        text aliases "JSON Array"
        text otype "天体类型"
        text oname "SIMBAD 主名称"
        real pm_ra "自行 RA"
        real pm_de "自行 Dec"
        real radial_velocity "视向速度"
        real parallax_err "视差误差"
        text photometry "测光数据 JSON"
    }

    AGENT_SESSIONS {
        text session_id PK
        text title
        text model
        integer turn_count
        text last_error
        text summary
        text metadata
        datetime deleted_at
        integer rewind_count "回退计数"
        text parent_session_id FK "分支来源"
        text branch_metadata "分支元数据"
        text mode "模式标识符"
    }

    AGENT_MESSAGES {
        integer id PK
        text session_id FK
        integer turn_index
        integer step_index
        text role "system/user/assistant/tool"
        text content
        text thought "思考链"
        text tool_calls "工具调用 JSON"
        text tool_call_id "工具调用 ID"
        integer token_count
        text metadata
        text raw_json
        text agent_name "消息归属"
        integer active "软删除标记"
    }

    AGENT_TASKS {
        integer id PK
        text session_id FK
        text task_id
        text content
        text status "pending/in_progress/completed"
        text blocked_by "JSON Array — DAG 依赖"
        text owner "分配目标 agent 名称"
    }

    AGENT_AUDIT_LOG {
        integer id PK
        text session_id FK
        integer step
        text tool_name
        text status "OK / FAIL / SESSION_STOP"
        integer elapsed_ms
        text output_preview
        text agent_name
    }

    AGENT_TEAM_MEMBERS {
        integer id PK
        text session_id FK
        text agent_name
        text agent_role
        text status "spawning / active / idle / shutdown"
    }

    PAPERS ||--o{ NOTES : "has"
    PAPERS ||--o{ CITATIONS_REFERENCES : "cites / cited_by"
    PAPERS ||--o{ PAPER_CHUNKS_CONTENT : "chunked into"
    PAPERS ||--o{ PAPER_TARGETS : "contains"
    AGENT_SESSIONS ||--o{ AGENT_MESSAGES : "contains"
    AGENT_SESSIONS ||--o{ AGENT_TASKS : "owns"
    AGENT_SESSIONS ||--o{ AGENT_AUDIT_LOG : "records"
    AGENT_SESSIONS ||--o{ AGENT_TEAM_MEMBERS : "members"
    AGENT_SESSIONS ||--o| AGENT_SESSIONS : "branches from"

---

2. 数据表结构详述 (Table Schema Details)

2.1 papers 表 (文献元数据)

存储文献的核心元数据和本地物理存储路径。

• 特殊字段说明：
  • pdf_path / html_path：正常情况下存储相对路径（如 library/PDF/2024arXiv.pdf）。当下载失败时，会以 error: 前缀存储诊断信息（如 error:Cloudflare 拦截）。特殊值 error:no_resource 表示用户手动标记了"无有效全文资源"。
  • doctype：文献类型标识，如 article、eprint、proceedings、phdthesis、catalog、software、circular、book 等。
• 索引：
  • idx_papers_doi -> 基于 doi
  • idx_papers_arxiv_id -> 基于 arxiv_id

2.2 citations_references 表 (引文与参考文献拓扑)

多对多关联表，存储文献之间的引用网络（即拓扑星系图的基础数据）。

• 复合主键：(source_bibcode, target_bibcode)
• 索引：
  • idx_citations_ref_source -> 优化以 source_bibcode 查询参考文献
  • idx_citations_ref_target -> 优化以 target_bibcode 查询被引文献

2.3 notes 表 (高亮与阅读笔记)

存储学者在阅读器中对特定段落创建的高亮和笔记。

• 外键：bibcode 级联删除 (ON DELETE CASCADE)。
• 索引：
  • idx_notes_bibcode -> 优化单篇文献的笔记列表查询。

2.4 sync_queries 表 (同步检索条件)

存储用户保存的批量同步检索条件，支持快速重新同步。

• 唯一约束：UNIQUE(query, source, limit_count) 确保相同条件的检索不会重复保存。

2.5 paper_chunks_content 表 (RAG 文本切片)

存储文献 Markdown 段落的文本切片，用于向量嵌入和混合检索。

• rowid：自增主键，与 vec_paper_chunks 虚拟表的 rowid 保持 1:1 对齐。
• headings：章节路径，如 "Introduction > Background"，用于结构化检索。
• section_index：章节内的段落编号。
• 外键：bibcode 级联删除 (ON DELETE CASCADE)。
• 关联 FTS5：paper_chunks_fts 虚拟表通过触发器自动同步 content 字段。

2.6 paper_targets 表 (天体目标缓存)

存储从文献中提取并通过 CDS Sesame 解析的天体物理参数。

• target_name：标准化天体名称（如 GD 358）。
• ra / dec：赤道坐标（赤经/赤纬）。
• parallax：视差（mas，毫角秒）。
• spectral_type：光谱分类（如 DA1）。
• otype / oname：Sesame v4 返回的天体类型和 SIMBAD 官方主名称。
• pm_ra / pm_de：自行分量（mas/yr）。
• radial_velocity：视向速度。
• photometry：多波段测光数据（JSON 文本）。
• 唯一约束：UNIQUE(bibcode, target_name)。
• 索引：idx_paper_targets_name。

2.7 agent_sessions 表 (Agent 会话)

存储 ReAct 智能体对话会话的元数据。

• deleted_at：软删除时间戳（NULL 表示活跃会话）。
• rewind_count：会话回退（undo）次数，用于追踪重做历史。
• parent_session_id：分支来源会话 ID，支持会话分叉（branch）。
• branch_metadata：分支元数据（JSON 文本）。
• mode：会话模式标识符（default、deep-research、literature-reader），控制 Agent 的行为配置。
• 索引：idx_agent_sessions_updated（WHERE deleted_at IS NULL，仅索引活跃会话）。

2.8 agent_messages 表 (Agent 消息)

存储 Agent 会话的完整对话历史，包括思考链和工具调用。

• role：system / user / assistant / tool。
• thought：LLM 思考链内容（CoT）。
• tool_calls：工具调用 JSON（函数名 + 参数）。
• tool_call_id：工具调用唯一标识（用于 SSE 流中 tool_call ↔ tool_result 配对）。
• agent_name：消息归属（lead / 子代理名 / teammate 名），支持身份隔离。
• active：软删除标记（0 = 已回退隐藏，1 = 正常可见），用于 session rewind。
• 索引：idx_agent_messages_session、idx_agent_messages_turn、idx_agent_messages_agent、idx_agent_messages_active。
• 关联 FTS5：agent_messages_fts 虚拟表通过触发器自动同步 content、thought、tool_calls 字段。

2.9 agent_tasks 表 (Agent 任务追踪)

持久化智能体的结构化待办任务，支持 DAG 依赖模式。

• blocked_by：JSON 数组，前置任务 ID 列表。
• status 生命周期：pending → in_progress → completed。
• owner：分配目标 agent 名称（多 Agent 团队协作路由）。
• 索引：idx_agent_tasks_session、idx_agent_tasks_status、idx_agent_tasks_session_task (UNIQUE)。

2.10 agent_audit_log 表 (Agent 工具审计)

记录所有工具调用的审计信息：工具名称、执行状态、耗时 (ms)、输出预览。

• status：OK / FAIL / SESSION_STOP。
• agent_name：区分 lead/子代理/teammate 的调用来源。
• 用途：GET /api/chat/metrics 聚合指标、会话审计回溯。

2.11 agent_team_members 表 (多 Agent 团队)

管理多智能体团队中每个成员的生命周期。

• status：spawning → active → idle → shutdown。
• agent_role：区分 team lead / teammate 等角色。
• 唯一约束：UNIQUE(session_id, agent_name)。

2.12 全文搜索 (FTS5)

系统在以下实体表上建立了 FTS5 全文索引，通过触发器自动保持同步：

FTS5 虚拟表	实体表	索引字段	用途
papers_fts	papers	title, authors, keywords, abstract, pub	本地文献 BM25 全文检索
paper_chunks_fts	paper_chunks_content	content	段落级稀疏检索，配合 vec_paper_chunks 向量做混合搜索
agent_sessions_fts	agent_sessions	session_id, title, summary, metadata	会话历史搜索
agent_messages_fts	agent_messages	session_id, role, content, thought, tool_calls	对话内容搜索

每个 FTS5 虚拟表通过 content='<实体表>' 声明为外部内容表，并配套 _insert、_update、_delete 三个触发器保持数据同步。

---

3. 数据库迁移说明

3.1 迁移机制

迁移脚本存放在 migrations/ 目录下，使用 sqlx 的 change-based 迁移 模型：

• 编译期嵌入：sqlx::migrate!("./migrations") 宏在编译时将 .sql 文件嵌入二进制
• 启动时自动执行：src/main.rs、src/bin/cli.rs 以及所有测试的 in-memory 数据库在启动时调用 .run(&pool)，对比 _sqlx_migrations 追踪表，按版本号顺序执行未应用的迁移
• 版本号规则：文件名格式 YYYYMMDDHHMMSS_description.sql，时间戳前缀保证全局唯一排序
• 幂等性：所有 DDL 必须使用 IF NOT EXISTS / IF EXISTS，确保可重复执行
• checksum 校验：sqlx 对每个迁移文件计算 SHA-256 校验和并存入 _sqlx_migrations；若文件内容在已应用后被修改，启动时将拒绝执行（防止 schema 漂移）

3.2 当前迁移

迁移文件	说明
00000000000000_init.sql	完整初始化：包含所有表、索引、FTS5 虚拟表及同步触发器，详见第 2 节各表结构。

注意：vec_paper_chunks 向量虚拟表由 src/main.rs 在迁移之后动态创建，维度由 EMBEDDING_DIM 环境变量控制（默认 1536），不在迁移文件中管理。

3.3 新增迁移

开发新功能需要变更数据库 schema 时：

1. 在 migrations/ 下新建文件，命名 YYYYMMDDHHMMSS_<简短描述>.sql（取当前时间）
2. 编写增量 SQL（ALTER TABLE ADD COLUMN、CREATE TABLE IF NOT EXISTS 等）
3. 运行 cargo build && cargo test 验证
4. 更新本文档的 3.2 节和对应的表结构说明

SQLite 约束：SQLite 不支持事务性 DDL 的全部语义，且 ALTER TABLE 能力有限（不支持 DROP COLUMN、RENAME COLUMN 等旧版本的常见操作）。新增字段时务必使用 DEFAULT 值以保证向后兼容。

3.4 迁移 Squash

开发期产生的增量迁移应在 首次正式发布前 squash 为单一 init.sql，避免迁移文件线性膨胀。Squash 流程：

1. 导出完整 schema：sqlite3 library/astro_research.db .schema
2. 移除以下内容：
   • _sqlx_migrations 表（sqlx 自动管理）
   • sqlite_sequence 表（SQLite 内部表）
   • vec_paper_chunks 及其关联内部表（由 main.rs 运行时创建）
   • 所有 FTS5 内部表（_data、_idx、_docsize、_config，由 FTS5 自动管理）
3. 写入 migrations/00000000000000_init.sql：确保所有 DDL 带 IF NOT EXISTS / IF EXISTS
4. 删除所有旧迁移文件
5. 重建二进制：cargo build（新迁移文件需嵌入）
6. 更新已有数据库（保留数据）：

   DELETE FROM _sqlx_migrations;
   -- 重启应用后 sqlx 自动应用新的 init 迁移（所有 IF NOT EXISTS 均为 no-op）
   

7. 验证：cargo test --lib && cargo run

本项目在 2026-06-25 执行了一次 squash，将 18 个开发期增量迁移合并为 1 个 00000000000000_init.sql，同时保留了已有的 1341 条文献记录和 6477 条引用关系。

---

4. 错误诊断存储约定

系统使用 papers 表的 pdf_path 和 html_path 字段的双重语义来同时存储正常路径和错误诊断：

字段值模式	含义	前端展示
NULL	尚未尝试下载	琥珀色"未下载"角标
library/PDF/xxx.pdf	下载成功，正常物理路径	蓝色"已下载"角标
error:具体原因	下载失败，原因为前缀后的文本	红色"下载失败"角标，悬浮显示原因
error:no_resource	用户手动标记为无有效全文资源	灰色"无资源"角标

health_check 工具在 --fix 模式下会清理损坏文件并将路径重置为 NULL，但不会清除 error: 前缀的记录（以保留诊断线索）。