Archive Agent

🚀 ⚡ Archive Agent

Archive Agent 是一款智能文件索引器，具备 AI 搜索（RAG 引擎）、自动 OCR 以及 MCP 接口等功能。它能让你使用自然语言查找文件并提问，支持对多种文件类型进行索引和处理。

https://github.com/user-attachments/assets/1cd8211e-6e5b-4e61-8ccc-74c140697abc

🚀 快速开始

请先安装以下依赖：

• 🐳 Docker（用于运行 Qdrant 服务器）
• 🐍 Python >= 3.10（核心运行时，通常已安装）

Ubuntu / Linux Mint

在你选择的当前目录中安装 Archive Agent，运行以下命令：

git clone https://github.com/shredEngineer/Archive-Agent
cd Archive-Agent
chmod +x install.sh
./install.sh

install.sh 脚本将按顺序执行以下步骤：

• 下载并安装 uv（用于 Python 环境管理）
• 安装自定义 Python 环境
• 安装 spaCy 分词器模型（用于分块）
• 安装 pandoc（用于文档解析）
• 下载并安装带有持久存储和自动重启功能的 Qdrant Docker 镜像
• 为当前用户安装全局 archive-agent 命令

🚀 Archive Agent 已安装完成！

👉 请接下来完成 AI 提供商设置。
（之后，你就可以 运行 Archive Agent 了！）

✨ 主要特性

• 多文件类型索引：支持对纯文本、文档、PDF、图像等多种文件类型进行索引。
• 自动 OCR 与实体提取：利用自动 OCR 和实体提取技术处理图像。
• AI 搜索与查询：可使用 AI（如 OpenAI、Ollama、LM Studio）搜索和查询文件。
• MCP 服务器集成：包含用于通过 IDE 或 AI 扩展实现自动化的 MCP 服务器。

📦 安装指南

安装要求

请在继续之前安装以下依赖：

• 🐳 Docker（用于运行 Qdrant 服务器）
• 🐍 Python >= 3.10（核心运行时，通常已安装）

Ubuntu / Linux Mint

此安装方法适用于任何基于 Ubuntu 的 Linux 发行版（如 Linux Mint）。在你选择的当前目录中安装 Archive Agent，运行以下命令：

git clone https://github.com/shredEngineer/Archive-Agent
cd Archive-Agent
chmod +x install.sh
./install.sh

install.sh 脚本将按顺序执行以下步骤：

• 下载并安装 uv（用于 Python 环境管理）
• 安装自定义 Python 环境
• 安装 spaCy 分词器模型（用于分块）
• 安装 pandoc（用于文档解析）
• 下载并安装带有持久存储和自动重启功能的 Qdrant Docker 镜像
• 为当前用户安装全局 archive-agent 命令

🚀 Archive Agent 已安装完成！

👉 请接下来完成 AI 提供商设置。
（之后，你就可以 运行 Archive Agent 了！）

💻 使用示例

基础用法

跟踪文件

archive-agent include "~/Documents/**" "~/Images/**"
archive-agent update

启动 GUI

archive-agent 

从命令行提问

archive-agent query "Which files mention donuts?"

高级用法

查看命令列表

archive-agent

创建或切换配置文件

archive-agent switch "My Other Profile"

打开当前配置文件的配置

archive-agent config

添加包含模式

archive-agent include "~/Documents/*.txt"

添加排除模式

archive-agent exclude "~/Documents/*.txt"

删除包含/排除模式

archive-agent remove "~/Documents/*.txt"

列出包含/排除模式

archive-agent patterns

解析模式并跟踪文件

archive-agent track

列出跟踪的文件

archive-agent list

列出更改的文件

archive-agent diff

将更改的文件提交到数据库

archive-agent commit

组合跟踪和提交

archive-agent update

搜索文件

archive-agent search "Which files mention donuts?"

查询文件

archive-agent query "Which files mention donuts?"

启动 Archive Agent GUI

archive-agent gui

启动 MCP 服务器

archive-agent mcp

📚 详细文档

AI 提供商设置

Archive Agent 允许你在不同的 AI 提供商之间进行选择：

• 远程 API（性能较高但成本较高，隐私性较差）：
  • OpenAI：需要 OpenAI API 密钥。
• 本地 API（性能较低但成本较低，隐私性最佳）：
  • Ollama：需要本地运行 Ollama。
  • LM Studio：需要本地运行 LM Studio。

💡 提示：启动时会提示你选择 AI 提供商；请参阅：运行 Archive Agent。

📌 注意：你可以在 Archive Agent 设置 中自定义 AI 提供商使用的特定 模型。但是，你不能更改 现有 配置文件的 AI 提供商，因为嵌入将不兼容；若要选择不同的 AI 提供商，请创建一个新的配置文件。

OpenAI 提供商设置

如果选择 OpenAI 提供商，Archive Agent 需要 OpenAI API 密钥。导出你的 OpenAI API 密钥，将 sk-... 替换为你的实际密钥并运行以下命令：

echo "export OPENAI_API_KEY='sk-...'" >> ~/.bashrc && source ~/.bashrc

这将为当前用户持久化导出。

💡 提示：OpenAI 不会使用你的数据进行训练。

Ollama 提供商设置

如果选择 Ollama 提供商，Archive Agent 需要 Ollama 在 http://localhost:11434 上运行。

• 如何安装 Ollama

使用默认的 Archive Agent 设置，预计需要安装以下 Ollama 模型：

ollama pull llama3.1:8b             # for chunk/rerank/query
ollama pull llava:7b-v1.6           # for vision
ollama pull nomic-embed-text:v1.5   # for embed

💡 提示：Ollama 在没有 GPU 的情况下也能工作。建议至少有 32 GiB 内存以确保性能流畅。

LM Studio 提供商设置

如果选择 LM Studio 提供商，Archive Agent 需要 LM Studio 在 http://localhost:1234 上运行。

• 如何安装 LM Studio

使用默认的 Archive Agent 设置，预计需要安装以下 LM Studio 模型：

meta-llama-3.1-8b-instruct              # for chunk/rerank/query
llava-v1.5-7b                           # for vision
text-embedding-nomic-embed-text-v1.5    # for embed

💡 提示：LM Studio 在没有 GPU 的情况下也能工作。建议至少有 32 GiB 内存以确保性能流畅。

支持的操作系统

Archive Agent 已在以下配置中进行了测试：

• Ubuntu 24.04（PC x64）

如果你已成功在不同的设置中安装并测试了 Archive Agent，请告知我，我会将其添加到此列表中！

如何选择要跟踪的文件

Archive Agent 使用 模式 来选择文件：

• 模式可以是实际的文件路径。
• 模式可以是包含通配符的路径，解析为实际的文件路径。

💡 模式必须指定为（或解析为）绝对 路径，例如 /home/user/Documents/*.txt（或 ~/Documents/*.txt）。 💡 使用通配符 * 匹配给定目录中的任何文件。 💡 使用通配符 ** 匹配任何文件以及零个或多个目录、子目录和目录的符号链接。

有 包含模式 和 排除模式：

• 解析后的排除文件集将从解析后的包含文件集中移除。
• Archive Agent 仅跟踪剩余的文件集（包含但不排除）。
• 隐藏文件始终被忽略！

这种方法让你对要跟踪的特定文件或文件类型有最佳的控制。

MCP 工具

Archive Agent 通过 MCP 公开了以下工具：

📌 注意：这些命令是 只读 的，防止 AI 更改你的 Qdrant 数据库。

💡 提示：只需在你的 IDE 或 AI 扩展中输入 #get_answer_rag（例如）即可直接调用该工具。

更新 Archive Agent

如果你刚刚安装了 Archive Agent，则无需立即执行此步骤。但是，为了获得最新功能，你应该定期更新你的安装。

在安装目录中运行以下命令来更新你的 Archive Agent 安装：

./update.sh

📌 注意：如果更新不起作用，请尝试删除安装目录，然后再次 安装 Archive Agent。 你的配置和数据安全地存储在其他位置； 有关详细信息，请参阅 Archive Agent 设置 和 Qdrant 数据库。

💡 提示：若要同时更新 Qdrant Docker 镜像，请运行以下命令：

sudo ./manage-qdrant.sh update

Archive Agent 设置

Archive Agent 设置以配置文件文件夹的形式组织在 ~/.archive-agent-settings/ 中。 例如，default 配置文件位于 ~/.archive-agent-settings/default/。 当前使用的配置文件存储在 ~/.archive-agent-settings/profile.json 中。

📌 注意：要删除配置文件，只需删除配置文件文件夹。 这不会删除 Qdrant 集合（请参阅 Qdrant 数据库）。

配置文件配置

配置文件配置包含在配置文件文件夹中的 config.json 中。

💡 提示：使用 config CLI 命令在 nano 编辑器中打开当前配置文件的配置（JSON）（请参阅 在 nano 中打开当前配置文件的配置）。 💡 提示：使用 switch CLI 命令切换到新的或现有的配置文件（请参阅 创建或切换配置文件）。

监视列表

配置文件监视列表包含在配置文件文件夹中的 watchlist.json 中。

监视列表仅由以下命令管理：

• include / exclude / remove
• track / commit / update

AI 缓存

每个配置文件文件夹还包含一个 ai_cache 文件夹。

AI 缓存确保在给定的配置文件中：

• 同一图像仅进行一次 OCR。
• 同一文本仅进行一次分块。
• 同一文本仅进行一次嵌入。
• 同一块组合仅进行一次重新排序。

这样，如果提交被中断，Archive Agent 可以快速从上次中断的地方继续。

要在单次提交中绕过 AI 缓存，请在 commit 或 update 命令中传递 --nocache 选项（请参阅 将更改的文件提交到数据库 和 组合跟踪和提交）。

💡 提示：查询从不缓存，因此你始终可以获得最新的答案。

📌 注意：要清除整个 AI 缓存，只需删除配置文件的缓存文件夹。

📌 技术说明：Archive Agent 使用由文本/图像字节以及用于分块、嵌入、重新排序和视觉的 AI 模型名称组成的复合哈希来键控缓存。缓存键是确定性的，并且每当你更改 分块、嵌入 或 视觉 AI 模型名称时都会生成更改。由于缓存条目会永久保留，切换回先前的 AI 模型名称组合将再次访问“旧”键。

Qdrant 数据库

Qdrant 数据库存储在 ~/.archive-agent-qdrant-storage/ 中。

📌 注意：此文件夹由以 root 身份运行的 Qdrant Docker 镜像创建。

💡 提示：访问你的 Qdrant 仪表板 以管理集合和快照。

开发者指南

Archive Agent 是为教育目的从头编写的（软件的两端）。

💡 提示：跟踪 test_data/ 可以让你从 一些 测试数据开始。

重要模块

要开始开发，请查看以下重要模块：

• 文件处理：
• 应用上下文初始化：
• 默认配置定义：
• CLI 命令定义：
• 提交逻辑实现：
• CLI 详细程度处理：
• GUI 实现：
• AI API 提示定义：
• AI 提供商注册表：

如果你发现缺少某些内容或不良模式，请随时贡献并进行重构！

代码测试和分析

运行以下命令以运行单元测试、检查类型和检查样式：

./audit.sh

🔧 技术细节

处理的文件类型

Archive Agent 当前支持以下文件类型：

• 文本：
  • 纯文本：.txt, .md
  • 文档：
    • ASCII 文档：.html, .htm
    • 二进制文档：.odt, .docx（包括图像）
  • PDF 文档：.pdf（包括图像，参见 OCR 策略）
• 图像：.jpg, .jpeg, .png, .gif, .webp, .bmp

文件处理方式

最终，Archive Agent 将所有内容解码为文本：

• 纯文本文件解码为 UTF-8。
• 文档转换为纯文本，提取图像。
• PDF 文档根据 OCR 策略进行解码。
• 图像使用 AI 视觉解码为文本。
  • 视觉模型将拒绝无法识别的图像。

使用 Pandoc 处理文档，PyMuPDF4LLM 处理 PDF，Pillow 处理图像。

📌 注意：不支持的文件会被跟踪但不处理。

OCR 策略

对于 PDF 文档，Archive Agent 支持不同的 OCR 策略：

• strict OCR 策略：
  • 忽略 PDF OCR 文本层。
  • 将 PDF 页面视为图像。
  • 成本高且速度慢，但更准确。
• relaxed OCR 策略：
  • 提取 PDF OCR 文本层。
  • 解码 PDF 前景图像，但忽略背景图像。
  • 成本低且速度快，但准确性较低。
• auto OCR 策略：
  • 根据从 PDF OCR 文本层提取的字符数为每个页面选择最佳 OCR 策略。
  • 根据 ocr_auto_threshold 决定，即 auto OCR 策略解析为 relaxed 而不是 strict 的最小字符数。
  • 在成本、速度和准确性之间进行权衡。

请参阅 Archive Agent 设置：ocr_strategy, ocr_auto_threshold

📌 注意：建议使用 strict OCR 策略以获得最佳结果。 PDF 文档通常包含与页面样式/布局相关的小图像，这些图像会增加开销，同时提供的信息很少，甚至会使结果混乱。

💡 提示：启动时会提示你选择 OCR 策略（请参阅 运行 Archive Agent）。

智能分块的工作原理

Archive Agent 按以下方式处理解码后的文本：

• 解码后的文本进行清理并拆分为句子。
• 句子分组为合理大小的块。
• 每个块使用 AI 模型拆分为更小的块。
  • 优雅处理块边界（最后一个块延续）。
• 每个块前缀一个 上下文标题（提高搜索效果）。
• 每个块使用 AI 嵌入转换为向量。
• 每个向量转换为带有文件元数据的 点。
• 每个 点 存储在 Qdrant 数据库中。

请参阅 Archive Agent 设置：chunk_lines_block

💡 提示：这种 智能分块 提高了检索的准确性和有效性。

块引用的工作原理

为了确保每个块都能追溯到其来源，Archive Agent 将每个块的文本内容映射到源文件的相应行号或页码。

• 基于行的文件（例如 .txt）使用行号范围作为引用。
• 基于页的文件（例如 .pdf）使用页码范围作为引用。

📌 注意：由于分块过程中的段落/句子拆分/合并，引用只是 近似 的。

块的检索方式

Archive Agent 按以下方式检索与你的问题相关的块：

• 问题使用 AI 嵌入转换为向量。
• 从 Qdrant 数据库中检索具有相似向量的点。
• 仅保留得分足够的点的块。

请参阅 Archive Agent 设置：retrieve_score_min, retrieve_chunks_max

块的重新排序和扩展方式

Archive Agent 过滤检索到的块：

• 根据与你的问题的相关性对检索到的块进行重新排序。
• 仅保留最相关的块（其他块丢弃）。
• 每个选定的块进行扩展以从相关文档中获取更大的上下文。

请参阅 Archive Agent 设置：rerank_chunks_max, expand_chunks_radius

答案的生成方式

Archive Agent 使用重新排序和扩展后的块回答你的问题：

• LLM 将块作为问题的上下文接收。
• LLM 的答案作为结构化输出返回并格式化。

💡 提示：Archive Agent 使用旨在普遍有用的答案模板。

📄 许可证

本项目采用 GNU GPL v3.0 许可证。

Copyright © 2025 Dr.-Ing. Paul Wilhelm <paul@wilhelm.dev>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

详情请参阅 LICENSE。

已知问题

• [ ] 虽然 track 最初将文件报告为 已添加，但后续的 track 调用将其报告为 已更改。
• [ ] 在跟踪阶段移除并恢复跟踪的文件目前处理不当：
  • 移除跟踪的文件会设置 {size=0, mtime=0, diff=removed}。
  • 恢复跟踪的文件会设置 {size=X, mtime=Y, diff=added}。
  • 由于 size 和 mtime 被清除，我们丢失了检测恢复文件的信息。
• [ ] AI 视觉也会应用于空图像，尽管它们可以在本地轻松检测并跳过。
• [ ] 由于缺少测试，PDF 矢量图像可能无法按预期转换。（在此期间使用 strict OCR 策略肯定会有帮助。）
• [ ] 二进制文档页码（例如 .docx）目前不支持。
• [ ] 由于分块过程中的段落/句子拆分/合并，引用只是 近似 的。
• [ ] AI 缓存目前不处理 AiResult 模式迁移。（如果你遇到错误，传递 --nocache 标志或删除所有 AI 缓存文件夹在此期间肯定会有帮助。）
• [ ] 在 strict OCR 模式下，从 PDF 页面中拒绝的图像（例如，由于违反 OpenAI 内容过滤策略）目前保持为空，而不是采用从 PDF OCR 层提取的文本（如果有）。