Skip to main content
Glama
README.md
# HistoryRAG

许可证:AGPL-3.0-only,全文见 [LICENSE](LICENSE)。发行包附应用源码与构建脚本;第三方组件各自保留原许可证。

面向历史研究资料的本地 RAG 项目,默认适配 Windows 11 和 16 GB 内存。RAGFlow 负责文档解析、索引和混合检索,Ollama 提供本地 Embedding,Codex 通过 `history_rag` MCP 读取证据。

## 普通使用者从这里开始

在本仓库的 **Releases** 下载 `HistoryRAG-0.4.0-Windows-x64.zip`,完整解压后双击 `HistoryRAG.exe`,按中文首次安装向导操作。无需 Git、Python 或单独安装 Ollama。自己的文献、笔记和账号都留在自己的电脑。

**Code → Download ZIP 下载的是源代码,不是可双击运行的安装包。** 非开发者请使用 Releases 中的 Windows 包。首次需联网下载后端和模型,并按提示完成 Docker、本地资料库账号及自己的 Codex 登录。包内 `README-START.txt` 有完整说明。

当前是首次安装试用版,已完成本机自动测试、独立运行和敏感信息检查,尚未在全新电脑完成整套首装验收。

## 给另一台电脑首次安装(0.4.0)

向朋友提供 Windows x64 发行 ZIP,完整解压后运行 `HistoryRAG.exe`。中文向导会选择专用目录、检查软件、按本人选择安装 Docker Desktop、下载模型/镜像、启动独立后端。无需 Python、Git 或单独安装 Ollama;检索模型运行在同一套容器中。首次仍需本人完成 Docker 的必要授权/重启、本地 RAGFlow 注册和生成 API Key,以及 Codex 登录。

提供本地 API Key 后,向导自动添加 Ollama 检索模型、创建或复用唯一的“历史资料库”、合并 Codex 的 history_rag 连接并创建桌面快捷方式。已有连接冲突时不自动覆盖,只有勾选替换才修改,修改前自动备份。不会复制作者账号、密钥、文献或运行状态。

向导使用专用 Compose 项目、独立随机密码和本机回环端口,不复用或删除已有 Docker 数据卷。支持失败后原目录重试。停止服务保留数据。新电脑的镜像和模型需要联网下载,不是离线包;Infinity 镜像要求兼容 x86-64-v3/AVX2 的 CPU。

接入方式采用 [OpenAI 官方 MCP 配置](https://learn.chatgpt.com/docs/extend/mcp#configure-with-configtoml) 中的 STDIO command/args。把安装目录下 `research`(桌面“历史研究工作区”)添加为 Codex 项目,以加载研究规则;不修改用户全局 AGENTS.md 或替他登录。

开发者构建:安装 `.[build]`,然后运行 `python scripts/build-release.py --output <输出目录>`。发行包附带应用源代码、AGPLv3 许可证和第三方许可说明,不包含 config/app.json、数据、日志、模型或作者环境。再分发时应保留许可证、依赖声明和对应源码。本机与模拟测试不替代新电脑的完整首次安装验收。

## 日常使用

1. 双击 `START-HistoryRAG.cmd`,打开中文“历史资料库”窗口。窗口会自动启动并检查后端服务。
2. 点击“放入文献”,把 PDF 或 DOCX **复制**到打开的文件夹。
3. 窗口保持打开,每 10 秒自动扫描一次。只有解析完成且生成分块后,才显示“可检索”;原文件随后保存在“查看原文件”目录。
4. 在 Codex 中直接要求检索“历史资料库”。无需另外点击同步。
5. 关闭窗口会停止自动导入,但保留查询服务。若需要释放服务资源,关闭窗口后双击 `STOP-HistoryRAG.cmd`。

窗口支持查看文档状态、手动重新扫描和重试失败。失败原件保留在 `data/failed`,不会每 10 秒无限重试。相同内容不会重复上传,重复副本保留在 `data/originals/duplicates`。导入任务进行中暂不关闭窗口,避免中途打断。

重复打开入口不会重复启动导入器;手动同步与自动导入也不会同时处理同一批文件。启动日志在 `logs/startup.log`,窗口日志在 `logs/desktop.log` 和 `logs/desktop-error.log`。

支持 PDF、DOCX、Markdown、TXT(具体以配置中的 supported_extensions 为准)。

点击“放入笔记”可打开专门的个人笔记目录;通过该目录收录的文件带有个人笔记标记,避免把自己的解释当作史料。历史文献仍使用“放入文献”。需要桌面入口时运行一次 `scripts/create-shortcuts.ps1`,会创建“历史资料库”和“放入历史文献”两个快捷方式;不会覆盖同名已有快捷方式。

导入使用文件快照。若原件在解析过程中被继续修改,已上传版本独立归档,新内容留在导入目录供下一轮处理,不会把新内容误认成旧版。关闭窗口后需再次打开才能继续自动收录;目前不安装开机启动项或系统后台服务。

## 章节阅读、原页核对和课题记录

新增 MCP 工具在重新加载 Codex 后可用:

- `history_document_outline`:读取 PDF 物理页数和内嵌书签目录。没有书签时,应先查看目录页定位章节。
- `history_read_pages`:每次按实际页序连续读取最多 20 页,逐批读取完整章节;返回覆盖范围和稀疏文本提示。扫描件没有可用文本层时,需查看原页,不能声称已经全文阅读。
- `history_verify_page`:返回原始 PDF 页面的图像,核对异体字、引文、注释和印刷页码。
- `history_document_versions`:查看原文件位置和新旧版本。将修改后同名文件再次复制到导入文件夹,新版本成功收录后才替代旧版成为默认检索来源;失败时旧版继续可用。不同作品请使用不同文件名。旧版文件和远程记录均保留,可指定文档 ID 查询旧版。
- `history_research_save` / `history_research_read`:按用户要求保存、继续或查看课题记录,保留每次修订。记录在 `data/state/research.db`;不是史料证据,也不会自动混入文献检索。

原页读取目前要求本地状态库能够定位原文件。直接在 RAGFlow 网页上传、未由本程序登记的文件暂不支持此功能。PDF 页序从 1 开始;不得未经核实把 RAGFlow 的 page_index 换算成印刷页码。

常用辅助入口:

- `CHECK-HistoryRAG.cmd`:检查服务、资料库、Embedding 和解析状态。
- `RETRY-Failed.cmd`:重试 `data/failed` 中的失败文档;已经上传过的文件会直接重试解析,不重复上传。

## 文档状态

本地状态库位于 `data/state/history-rag.db`:

- `uploading`:正在上传。
- `parsing`:RAGFlow 正在解析和生成向量。
- `indexed`:RAGFlow 返回 `DONE`,并且至少生成了一个分块。
- `failed`:上传或解析失败;错误详情保存在状态库中,原文件移入 `data/failed`。

旧版产生的 `uploaded` 记录只代表文件曾上传,不能证明已完成索引。可通过 `CHECK-HistoryRAG.cmd` 对照远程解析统计。

升级旧版后可运行以下命令,用 RAGFlow 的实际状态修正本地记录:

```powershell
.\.venv\Scripts\python.exe -m history_rag.cli --config .\config\app.json --reconcile-state
```

## MCP 工具

自带的 stdio MCP bridge 提供:

- `ragflow_retrieval`:检索史料证据片段。
- `ragflow_list_datasets`:列出资料库。
- `ragflow_list_documents`:查看文档、解析进度、分块数量和文档 ID。
- `ragflow_health`:检查资料库、Embedding 与解析数量。
- `ragflow_list_chats`:列出 RAGFlow 助手。

修改 MCP bridge 后需要重新加载 Codex,工具列表才会刷新。

## 首次安装

在 PowerShell 中运行:

```powershell
Set-Location E:\Git\HistoryRAG
.\scripts\install-ollama.ps1
.\scripts\start-ollama.ps1
ollama pull bge-m3
.\scripts\bootstrap.ps1
.\scripts\prepare-images.ps1
.\scripts\start-ragflow.ps1
```

然后:

1. 打开 `http://127.0.0.1`。
2. 在 RAGFlow 中添加 Ollama,地址为 `http://host.docker.internal:11434`。
3. 添加 `bge-m3` Embedding 模型并创建“历史资料库”。
4. 生成 RAGFlow API Key。
5. 复制 `config/app.example.json` 为 `config/app.json`,填写 API Key 和资料库 ID。
6. 运行 `SYNC-Documents.cmd` 前可先执行 `scripts/sync-once.ps1 -DryRun`。

`config/app.json` 包含密钥,已被 `.gitignore` 排除,不要提交或分享。

## 配置要点

- `request_timeout_seconds`:单次 RAGFlow 请求超时。
- `parse_timeout_seconds`:等待一篇文档完成解析的最长时间,默认 1800 秒。
- `parse_poll_interval_seconds`:解析状态轮询间隔,默认 3 秒。
- `move_after_upload`:索引完成后是否移动原文件。

默认采用内置 chunking pipeline,并通过 `/api/v1/datasets/{dataset_id}/chunks` 触发解析。若资料库改用 ingestion pipeline,需要改为 RAGFlow 的 `/api/v1/documents/ingest` 接口。

## 诊断和测试

```powershell
.\scripts\diagnose.ps1
.\.venv\Scripts\python.exe -m history_rag.cli --config .\config\app.json --health
.\.venv\Scripts\python.exe -m pytest -q
```

如果 MCP 提示无法连接后端,先运行 `START-HistoryRAG.cmd`;网页能够打开不等于检索已经就绪,以启动末尾的系统自检结果为准。

## 目录

```text
codex/          Codex 规则与 MCP 配置示例
config/         本地配置模板
data/inbox/     待入库文档
data/originals/ 已成功索引的原文件
data/failed/    失败文档
data/state/     SQLite 状态库与进程记录
scripts/        Windows 管理脚本与 MCP bridge
src/            增量同步程序
tests/          自动测试
```