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 公開了以下工具：

MCP 工具	等效的 CLI 命令(s)	參數(s)	描述
get_patterns	patterns	無	獲取包含/排除模式的列表。
get_files_tracked	track 然後 list	無	獲取跟蹤的文件列表。
get_files_changed	track 然後 diff	無	獲取更改的文件列表。
get_search_result	search	question	獲取與問題相關的文件列表。
get_answer_rag	query	question	使用 RAG 獲取問題的答案。

📌 注意：這些命令是 只讀 的，防止 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 命令切換到新的或現有的配置文件（請參閱 創建或切換配置文件）。

鍵	描述
config_version	配置版本
mcp_server_port	MCP 服務器端口（默認 8008）
ocr_strategy	中的 OCR 策略
ocr_auto_threshold	auto OCR 策略解析為 relaxed 而不是 strict 的最小字符數
chunk_lines_block	分塊時每個塊的行數
qdrant_server_url	Qdrant 服務器的 URL
qdrant_collection	Qdrant 集合的名稱
retrieve_score_min	檢索的塊的最小相似度分數（0...1）
retrieve_chunks_max	檢索的最大塊數
rerank_chunks_max	重新排序後保留的前幾個塊數
expand_chunks_radius	為每個重新排序的塊前置和追加的前後塊數
ai_provider	中的 AI 提供商
ai_server_url	AI 服務器的 URL
ai_model_chunk	用於分塊的 AI 模型
ai_model_embed	用於嵌入的 AI 模型
ai_model_rerank	用於重新排序的 AI 模型
ai_model_query	用於查詢的 AI 模型
ai_model_vision	用於視覺的 AI 模型（"" 禁用視覺）
ai_vector_size	嵌入的向量大小（用於 Qdrant 集合）
ai_temperature_query	查詢模型的溫度

監視列表

配置文件監視列表包含在配置文件文件夾中的 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 層提取的文本（如果有）。