# Research Mentor RAG

Research Mentor RAG 不是一个等人提问的论文搜索框。它是一套装进 AI 工作流里的科研导师系统：1200 篇论文被拆成 39,238 条可调用的研究记录，其中 9,697 条是阶段化方法。模型做选题、提出假设、设计实验、制定统计方案、写论文、回应审稿或准备复现时，系统会先检索相似研究和失败边界，再允许它给出判断。

真正负责调度的是 `Research Mentor Workflows` Skill。它识别当前科研阶段，规定每一步要查哪些 RAG 检索头、调用哪些专业能力、产出什么制品，以及何时必须纠错或停在 HOLD。配套的 12-Skill 能力合同覆盖多源文献搜索、全文与图表读取、引文核验、假设生成、实验设计、实验日志、统计分析、论文写作、系统综述和审稿红队。总控 Skill 不会用一段泛泛建议代替这些专业流程，而是把任务路由给对应能力。

运行时通过 6 个 MCP 工具把这套能力直接交给模型：`research_bootstrap` 加载经验包，`research_rag_query` 定向查证据，`research_route` 执行阶段多头检索，`research_mentor` 组合 RAG 与专业 Skill，`research_frontier_search` 实时查询 OpenAlex 和 Crossref，`research_controller` 自动判断阶段并组装回答前的证据包。Codex Hook 会在检测到科研请求时提前触发总控。到了选题阶段，它要求同时查看本地最近邻和实时前沿；到了实验阶段，它检索相似实验的变量、对照、测量和停止规则；到了写作阶段，它拉取论证结构、图表证据和常见审稿风险。检索结果、采用或拒绝的节点、证据边界、纠错条件和下一步会一起注入模型上下文。

底层检索使用 SQLite FTS5，不需要嵌入模型。L0–L5 六层结构把原子记录、单篇论文、方法积木、跨论文经验、科研阶段和完整研究流程连在一起，既能快速给出全局路线，也能一路下钻到具体经验。当前公开版本是 `FAST80 / PROVISIONAL`：它已经能承担导航、方法选择和流程约束，但不会把尚未完成的正式双增量审计写成最终科学验证。

## 现在包含什么

- 1200 篇冻结论文对应的经验记录；
- 39,238 个原子记录与方法记录，其中 9,697 个是阶段化方法；
- L0 原子证据 → L1 单篇论文 → L2 方法积木 → L3 跨论文经验 → L4 科研阶段 → L5 完整流程；
- 7 个阶段：novelty、hypothesis、experiment、statistics、writing、review、reproducibility；
- 6 个 MCP 工具：bootstrap、RAG query、route、mentor、frontier search、controller；
- OpenAlex + Crossref 实时前沿发现，用于新颖性和研究缺口初筛；
- Codex `UserPromptSubmit` Hook 示例，可在科研请求进入模型前注入阶段检索结果。

## 快速开始

要求 Python 3.11+，其余运行依赖均来自标准库。

```bash
python scripts/smoke_test.py
```

直接检索实验设计经验：

```bash
python skill/research-mentor-workflows/scripts/fast80_rag.py route \
  --db data/fast80_research_rag.sqlite3 \
  --stage experiment \
  --text "小样本条件下如何设计可靠的消融实验？"
```

启动 MCP 服务器：

```bash
python -B skill/research-mentor-workflows/scripts/research_mentor_mcp.py
```

完整的 Codex 配置见 [docs/codex-install.md](docs/codex-install.md)。架构与检索规则见 [docs/architecture.md](docs/architecture.md)，真实运行示例见 [docs/examples.md](docs/examples.md)。

## 真实运行示例

下面两张图由 `scripts/generate_examples.py` 从仓库内 SQLite 数据库和 MCP 服务器现场生成，原始 JSON 一并保存在 `docs/examples/`。

| 实验阶段多头检索 | MCP 运行时与 6 个工具 |
|---|---|
| ![Experiment-stage RAG route](docs/examples/experiment-route.png) | ![MCP runtime and tools](docs/examples/mcp-runtime.png) |

## 数据文件与 Git LFS

`data/fast80_research_rag.sqlite3` 约 56 MB，仓库已用 `.gitattributes` 将 SQLite 文件交给 Git LFS：

```bash
git lfs install
git add .
git commit -m "Initial release"
```

原始论文、仓库快照和补充材料不在本仓库中。数据库保存的是机器抽取的研究经验记录及其状态，不等于重新分发原始材料。

## 许可证与重要边界

- 软件代码使用 [Apache License 2.0](LICENSE)。
- `data/` 下的派生 SQLite 数据库与 manifest 使用 [CC BY 4.0](DATA-LICENSE.md)。该许可不覆盖原始论文、图表、补充材料、仓库或其他第三方内容。

- `PROVISIONAL_FAST80` 可用于导航、找相似方法和规划下一步，不应被写成已由人工或最终审计确认的科学事实。
- 实时前沿搜索返回发现候选。正式声称“首创”或“研究空白”前，仍需核验全文、时间范围和最近邻工作。
- 系统不会替代作者对原始数据、伦理、许可、引文、署名和投稿声明的责任。

## 仓库结构

```text
data/                       FAST80 SQLite RAG 与 manifest
skill/research-mentor-workflows/
                            Skill、MCP、路由器、参考规范与测试
scripts/smoke_test.py       一次本地冒烟测试
scripts/install_codex.py    安装预检与配置片段生成器
tests/test_release.py       发布包结构与功能测试
docs/                       安装、架构与项目简介
```

## 项目简介

短版介绍在 [docs/project-intro.zh-CN.md](docs/project-intro.zh-CN.md)。