🧠

🧠 Archive Agent

本地服务

wilhelm.devAI 与智能体633 周前更新

关于 🧠 Archive Agent

Archive Agent 是一个本地文件索引器与 RAG 引擎，可用自然语言搜索和提问文件内容，并通过内置 MCP 服务接入其他工具。它面向希望在命令行中管理本地文档的用户，支持 OpenAI、OpenRouter、Ollama 和 LM Studio。

主要功能

01自然语言语义搜索与问答
02基于 glob 模式跟踪本地文件
03PDF 与图片的 OCR 及实体提取
04变更文件自动同步至 Qdrant 向量数据库
05内置 MCP 服务
06支持多种 AI 提供商

适用场景

01在本地文档中按语义查找资料
02对 PDF、图片等文件内容进行提问
03将本地文件索引作为 MCP 工具供 Agent 调用

MCP 相关

Archive Agent 内置 MCP 服务，向 MCP 客户端暴露文件搜索与查询功能。

#python #ocr #openai #rag #ollama #lm-studio #mcp-server

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

暂未收录安装方式

我们还没有获取到这个服务的安装包或远程地址，请按项目 README 中的说明安装。

代码仓库

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Archive Agent 徽标

Archive Agent

智能文件索引器，具备强大的 AI 搜索（RAG 引擎）、自动 OCR 和无缝 MCP 接口。

GitHub 发布版本 GitHub 许可证

Archive Agent 将 RAG 带到命令行，并通过 MCP 连接到你的工具——它不是聊天机器人。

用自然语言查找所需内容

通过语义 AI 搜索和查询，解锁文档的价值
文件会通过带上下文标题的语义分块进行拆分，并存入本地数据库。
RAG 引擎¹会对检索到的分块进行重排序和扩展

¹ 检索增强生成是一种将预先生成的信息片段与查询进行匹配的方法。

在设备上原生索引文档

内置本地 AI 文件系统索引器
原生摄取 PDF、图片、Markdown、纯文本等……
使用模式选择并跟踪文件，例如 ~/Documents/*.pdf
使用自动 OCR转录图片（实验性功能），并提取实体
变更会自动同步到本地 Qdrant 向量数据库。

你的 AI，由你选择

支持多种 AI 提供商和 MCP
OpenAI 或兼容 API ¹，性能最佳
OpenRouter，可访问所有提供商的 400 多种模型
Ollama 和 LM Studio，隐私保护最佳（本地 LLM）
通过内置的 MCP 服务集成到你的工作流中**。

¹ 包括 xAI / Grok 和 Claude 的 OpenAI 兼容 API。只需调整 URL 设置，并覆盖 OPENAI_API_KEY。

可扩展的性能

完全可恢复的并行处理
使用经过优化的多线程技术同时处理多个文件。
对所有网络请求使用 AI 缓存和宽松的请求重试机制。
利用 AI 结构化输出，以及高质量的提示词和模式。

架构

（[如果看不到下方图表，请在 Mermaid.live 上查看](https://mermaid.live/edit#pako:eNqFU9tu2kAQ_ZXRSnkDamwDiRUhEYcQEmgT6EVqycPanpgV9q61XieQKP_evUBuqtQX5J1z5sycmeGZpCJDEpFc0moNs8WKrzjA0RFMeY61YoLDDauwYBwNUDeJY77CJgow-nOaDL9Lmm6A8gxiUZZMwQUrsD79kgxPEzlcNlUlpKrhRop7A9xBuz2EM5Pp1D7yR40SJVUshW_xApZKUoX5ziDTkuYIY66Y2sF4q5HUdHLnWjmzsrGRXWJJuVGI1w3fMJ4ftB-ZWusmucKtgkukGcraxGfaZg0VSjgrRLqJoOt5Jv5LyMzFrVIEvufty8W23LkpNy4TzBzj1cVcj7eIwBRqo8Ez3UY7aBdU5mgIPzFVQsKSPWEEgTfw97rnVndsbWgCftKdiZQWcJtJbRAyqmhCa7SpyLPXJd42KHf_XqCFXKkLU2RUb0zM7tQUcduZvPl6D_7X2d7ExIpcGpEFKsnwAeErUmmW_dHPMjUe54xH4HW6JuJwmNOtmctecOwE3ePSPqZOXQ9iA8kOFljgA-UpHpTf6xzvZaY288qa21buYu0xfEpa0Iw1tT6Dfd6Vzbs2eRPkaE4SRrx-RGlH5kjXljRzJPUON8KMQzybtmDyQ__M45vDykhL_wVZRiIlG2yREmVJzZM8G8KKqDWWuCKR_syo3KzIir_oHN37byHKQ5oUTb4m0T0tav1qKn0YeM6o3vgbRRdDGYuGKxKdWAUSPZMtifqDTs_vhqHve4HX94OwRXYk8sOwc-ydhN7xwO8O-v0weGmRJ1uz2wl6vYEX9sLeySAcBN3w5S8sgV42）]

graph LR

  %% Ingestion Pipeline
  subgraph Ingestion
    A[<b>Track and Commit Files</b><br>Supports Profiles] --> B[<b>Ingest Files</b><br>Automatic OCR Strategy<br>Image Entity Extraction]
    B --> C[<b>Semantic Chunking</b><br>with Context Headers<br>Lines per Block: 100<br>Words per Chunk: 200]
    C --> D[<b>Embed Chunks</b><br>Model: text-embedding-3-large<br>Vector Size: 3072]
    D --> E[<b>Store Chunks</b><br>Local Qdrant database]
  end

  %% Query Pipeline
  subgraph Query
    F[<b>Ask Question</b>] --> G[<b>Embed Question</b><br>Model: text-embedding-3-large]
    G --> H[<b>Retrieve Nearest Chunks</b><br>Score Min: 0.1<br>Chunks Max: 30]
    E --> H
    H --> I[<b>Rerank by Relevance</b><br>Chunks Max: 8]
    I --> J[<b>Expand Context</b><br>Chunks Radius: 1]
    J --> K[<b>Generate Answer</b>]
    K --> L[<b>Get Answer</b><br>in CLI, GUI, MCP]
  end

文档

Archive Agent

支持的操作系统

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

Ubuntu 24.04（PC x64）
Ubuntu 22.04（PC x64）

如果你已在其他配置中成功安装并测试 Archive Agent，请告诉我，我会将其添加到此处！

安装 Archive Agent

请先安装以下依赖，再继续操作：

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

Ubuntu / Linux Mint

此安装方法适用于任何基于 Ubuntu 的 Linux 发行版（例如 Linux Mint）。

📌 注意： GUI、MCP 服务和 Qdrant 服务受同一个密码保护，该密码从环境变量 LOCAL_AUTH_PASSWORD 读取。安装或运行 Archive Agent 前，请先导出该变量（例如在 shell 配置文件中）—— 否则，archive-agent gui、archive-agent mcp 和 manage-qdrant.sh 将拒绝启动：

export LOCAL_AUTH_PASSWORD='your-password'

要在所选的当前目录中安装 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 镜像，并配置持久化存储、自动重启以及将 LOCAL_AUTH_PASSWORD 用作其 API 密钥
为当前用户安装全局 archive-agent 命令

Archive Agent 已安装！

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

AI 提供商设置

Archive Agent 支持在不同的 AI 提供商之间进行选择：

远程 API （性能和成本较高，隐私性较低）：
- OpenAI：需要 OpenAI API 密钥。
- OpenRouter：需要 OpenRouter API 密钥。可访问 400 多种模型。
本地 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 不会使用你的数据进行训练。

OpenRouter 提供商设置

如果选择了 OpenRouter 提供商，Archive Agent 需要 OpenRouter API 密钥。

OpenRouter 提供统一 API，可通过单一端点访问来自多个提供商（OpenAI、Google、Anthropic、Meta 等）的 400 多种模型。

要导出你的 OpenRouter API 密钥，请将 sk-or-... 替换为你的实际密钥，然后运行一次：

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

这会为当前用户持久保存该导出设置。

使用默认的 Archive Agent 设置时，会使用以下 OpenRouter 模型：

任务	默认模型	输入/输出成本
分块	`google/gemini-2.5-flash-lite`	每 M 个 token $0.10 / $0.40
重排	`google/gemini-2.5-flash-lite`	每 M 个 token $0.10 / $0.40
查询	`google/gemini-2.5-flash`	每 M 个 token $0.30 / $2.50
视觉	`google/gemini-2.5-flash`	每 M 个 token $0.30 / $2.50
嵌入	`openai/text-embedding-3-large`	每 M 个 token $0.13

💡 了解更多： 你可以在 Archive Agent 设置中自定义模型。OpenRouter 支持多种模型的结构化输出、嵌入和视觉。浏览 openrouter.ai/models 查看所有可用模型。

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 目前支持以下文件类型：

文本：
- 纯文本：.txt、.md、.markdown
- 文档：
  - ASCII 文档：.html、.htm（不支持图像）
  - 二进制文档：.odt、.docx（包括图像）
- PDF 文档：.pdf（包括图像；请参阅 OCR 策略）
图像：.jpg、.jpeg、.png、.gif、.webp、.bmp

📌 注意： 目前不支持 HTML 文档中的图像。

📌 注意： 目前不支持旧版 .doc 文件。

📌 注意： 不支持的文件会被记录，但不会处理。

文件的处理方式

最终，Archive Agent 会将所有内容解码为文本，处理方式如下：

纯文本文件会解码为 UTF-8。
文档会转换为纯文本，图像会被提取。
PDF 文档会根据 OCR 策略进行解码。
图像会使用 AI 视觉解码为文本。
- 使用 OCR、实体提取，或两者结合（默认）。
- 视觉模型会拒绝无法辨认的图像。
- 实体提取会从图像中提取结构化信息。
- 结构化信息会格式化为图像描述。

请参阅 Archive Agent 设置：image_ocr、image_entity_extract

Archive Agent 会以优化后的性能处理文件：

精准同步：
- PDF 分析阶段采用串行处理（由于 PyMuPDF 的线程限制）。
- 其他所有阶段（视觉处理、分块、嵌入）均采用并行处理，以实现最高性能。
视觉操作会在文件内及文件之间，对图像和页面进行并行处理。
嵌入操作会在文本块和文件之间并行处理。
智能分块因依赖传递机制而采用串行处理。

请参阅 Archive Agent 设置：max_workers_ingest、max_workers_vision、max_workers_embed

OCR 策略

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

strict OCR 策略（推荐）：
- 忽略 PDF OCR 文本层。
- 将 PDF 页面视为图像，且仅使用 OCR 进行处理。
- 成本高、速度慢，但准确度更高。
relaxed OCR 策略：
- 提取 PDF OCR 文本层。
- 使用 OCR 解码 PDF 前景图像，但忽略背景图像。
- 成本低、速度快，但准确度较低。
auto OCR 策略：
- 根据从 PDF OCR 文本层提取的字符数（如果有），尝试为每个页面选择最佳 OCR 策略。
- 根据 ocr_auto_threshold 决定：该值是让 auto OCR 策略选择 relaxed 而非 strict 的最小字符数。
- 在成本、速度和准确度之间进行权衡。

⚠️ 警告：auto OCR 策略仍处于实验阶段。 PDF 文档通常包含与页面样式或布局相关的细小或零散图像，这些图像会增加开销，却几乎不提供信息，甚至会使结果杂乱。

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

智能分块的工作方式

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

对解码后的文本进行清理，并拆分为句子。
将句子分组为大小适中的文本块。
使用 AI 模型将每个文本块拆分为更小的文本块。
- 妥善处理文本块边界（最后一个文本块会延续到下一个文本块）。
为每个文本块添加上下文标头（以改进搜索）。
使用 AI 嵌入将每个文本块转换为向量。
将每个向量连同文件元数据转换为一个点。
将每个点存储在 Qdrant 数据库中。

请参阅 Archive Agent 设置：chunk_lines_block、chunk_words_target

💡 提示：这种智能分块可以提高检索的准确度和效果。

📌 **注意：**在极少数情况下，如果文本块超出嵌入模型的令牌限制（通常为 8192 个令牌），Archive Agent 会自动将其截断作为最后手段，每次递减 10%，最多尝试 10 次，直至符合限制。

📌 **注意：**对于超大型文档，句子拆分可能需要一些时间。目前无法显示此步骤的进度。

分块引用的工作原理

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

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

📌 **注意：**由于分块过程中会拆分或合并段落和句子，引用仅为近似值。

分块的检索方式

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

使用 AI 嵌入将问题转换为向量。
从 Qdrant 数据库中检索向量相似的点。
仅保留分数足够高的点所对应的分块。
如果启用了 retrieve_knee_enable，当分数出现明显下降时，自适应截断会剔除相关性较低的分块。

参见 Archive Agent 设置：retrieve_score_min、retrieve_chunks_max、retrieve_knee_enable、retrieve_knee_sensitivity、retrieve_knee_min_chunks

📌 **注意：**自适应截断会对排序后的相似度分数使用 Kneedle 算法。设置较高的 retrieve_knee_sensitivity，可使截断更加保守；使用 retrieve_knee_min_chunks 可设置最小数量下限。

💡 调优建议：

如果检索结果太少或缺少上下文，请增大 retrieve_knee_min_chunks（例如，3–5），或提高 retrieve_knee_sensitivity。
如果检索结果太多或噪声较大，请略微降低 retrieve_knee_sensitivity（例如，0.8–1.0），或减小 retrieve_knee_min_chunks。
如果要完全禁用自适应截断，请将 retrieve_knee_enable 设置为 false。

分块的重排与扩展方式

Archive Agent 会筛选检索到的分块。

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

参见 Archive Agent 设置：rerank_chunks_max、expand_chunks_radius

答案的生成方式

Archive Agent 会按以下方式使用经过重排和扩展的分块回答你的问题：

大模型会接收这些分块，作为问题的上下文。
大模型的回答会以结构化输出的形式返回并进行格式化。

💡 了解更多： Archive Agent 使用旨在普遍适用的答案模板。

用于跟踪的文件选择方式

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

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

模式分为包含模式和排除模式：

从已解析的包含文件集合中移除已解析的排除文件集合。
Archive Agent 仅跟踪剩余的文件（包含但未排除的文件）。
始终忽略隐藏文件！

这种方式让你可以灵活控制要跟踪的特定文件或文件类型。

运行 Archive Agent

💡 **了解更多：**启动时，系统会提示你选择以下内容：

配置名称
AI 提供商（参见 AI 提供商设置）
OCR 策略（参见 OCR 策略）

命令行界面（CLI）截图：

README 配图

在命令行（CLI）中快速入门

例如，要跟踪文档和图片，请运行：

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

要启动 GUI，请运行：

archive-agent

或者，通过命令行提问：

archive-agent query "Which files mention donuts?"

CLI 命令参考

查看命令列表

要查看支持的命令列表，请运行：

archive-agent

创建或切换配置文件

要切换到新的或已有的配置文件，请运行：

archive-agent switch "My Other Profile"

📌 注意：配置文件名称参数务必使用引号， 或跳过该参数以进入交互式提示。

💡 **实用提示：**配置文件可用于管理相互独立的 Qdrant 集合（参见 Qdrant 数据库）和 Archive Agent 设置。

在 nano 中打开当前配置文件的配置

要在 nano 编辑器中打开当前配置文件的配置（JSON），请运行：

archive-agent config

详情请参见 Archive Agent 设置。

添加包含模式

要添加一个或多个包含模式，请运行：

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

📌 注意：模式参数务必使用引号（以防 shell 执行通配符展开）， 或跳过该参数以进入交互式提示。

添加排除模式

要添加一个或多个排除模式，请运行：

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

📌 注意：模式参数务必使用引号（以防 shell 执行通配符展开）， 或跳过该参数以进入交互式提示。

移除包含 / 排除模式

要移除一个或多个先前添加的包含 / 排除模式，请运行：

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

📌 注意：模式参数务必使用引号（以防 shell 执行通配符展开）， 或跳过该参数以进入交互式提示。

列出包含 / 排除模式

要查看包含 / 排除模式列表，请运行：

archive-agent patterns

解析模式并跟踪文件

要解析所有模式并跟踪文件变更，请运行：

archive-agent track

列出已跟踪的文件

要查看已跟踪的文件列表，请运行：

archive-agent list

📌 **注意：**请先使用 track 跟踪文件。

列出已更改的文件

要查看已更改的文件列表，请运行：

archive-agent diff

📌 **注意：**请先使用 track 跟踪文件。

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

要将文件变更同步到 Qdrant 数据库，请运行：

archive-agent commit

要查看额外信息（视觉分析、分块、嵌入），请传入 --verbose 选项。

要在本次提交中绕过 AI 缓存（视觉分析、分块、嵌入），请传入 --nocache 选项。

要自动确认从数据库中删除未跟踪的文件，请传入 --confirm-delete 选项。

💡 **实用提示：**以下情况会触发变更：

添加文件
移除文件
更改文件：
- 文件大小不同
- 修改日期不同

所有文件摄取完成后，Qdrant 数据库会更新。

📌 **注意：**请先使用 track 跟踪文件。

合并跟踪和提交

要一次性执行 track，然后执行 commit，请运行：

archive-agent update

要查看额外信息（视觉分析、分块、嵌入），请传入 --verbose 选项。

要在本次提交中绕过 AI 缓存（视觉分析、分块、嵌入），请传入 --nocache 选项。

要自动确认从数据库中删除未跟踪的文件，请传入 --confirm-delete 选项。

搜索文件

archive-agent search "Which files mention donuts?"

列出与问题相关的文件。

📌 注意：问题参数务必使用引号，或跳过该参数以进入交互式提示。

要查看额外信息（嵌入、检索、重排），请传入 --verbose 选项。

要在本次搜索中绕过 AI 缓存（嵌入、重排），请传入 --nocache 选项。

查询你的文件

archive-agent query "Which files mention donuts?"

使用 RAG 回答你的问题。

📌 注意： 问题参数始终要使用引号，或者省略该参数以获取交互式提示。

要查看更多信息（嵌入、检索、重排、查询），请传入 --verbose 选项。

要在本次查询中绕过 AI 缓存（嵌入、重排），请传入 --nocache 选项。

要将查询结果保存到 JSON 文件，请运行以下任一命令：

使用 --to-json 并指定文件名：

archive-agent query "Which files mention donuts?" --to-json answer.json

使用 --to-json-auto [DIR] 根据问题自动生成简洁的文件名（最多 160 个字符，如有需要会使用 [...] 截断），并写入目录 DIR（如果已提供；默认为当前目录 .；如果路径中的目录不存在，则会创建）：
```
archive-agent query "Which files mention donuts?" --to-json-auto Output/
# Creates: Output/Which_files_mention_donuts_.json
```

📌 注意： 从 Archive Agent v12.2.0 起，使用 --to-json 或 --to-json-auto 选项时，也会创建包含答案的对应 Markdown 文件（.md）。（目前无法选择不创建该文件。）

启动 Archive Agent GUI

要在浏览器中启动 Archive Agent GUI，请运行：

archive-agent gui

要查看更多信息（嵌入、检索、重排、查询），请传入 --verbose 选项。

要在本次查询中绕过 AI 缓存（嵌入、重排），请传入 --nocache 选项。

要将查询结果保存到 JSON 文件，请运行：

使用 --to-json-auto [DIR] 根据问题自动生成简洁的文件名（最多 160 个字符，如有需要会使用 [...] 截断），并写入目录 DIR（如果已提供；默认为当前目录 .；如果路径中的目录不存在，则会创建）：
```
archive-agent gui --to-json-auto Output/
```

📌 注意： 从 Archive Agent v12.2.0 起，使用 --to-json-auto 选项时，也会创建包含答案的对应 Markdown 文件（.md）。（目前无法选择不创建该文件。）

📌 注意： 在控制台中按 CTRL+C 可关闭 GUI 服务。

📌 注意： GUI 会监听所有 IPv4 接口（端口 8501），并会在显示或查询任何内容前要求输入 LOCAL_AUTH_PASSWORD。

启动 MCP 服务

要启动 Archive Agent MCP 服务，请运行：

archive-agent mcp

要查看更多信息（嵌入、检索、重排、查询），请传入 --verbose 选项。

要在本次查询中绕过 AI 缓存（嵌入、重排），请传入 --nocache 选项。

要将查询结果保存到 JSON 文件，请运行：

使用 --to-json-auto [DIR] 根据问题自动生成简洁的文件名（最多 160 个字符，如有需要会使用 [...] 截断），并写入目录 DIR（如果已提供；默认为当前目录 .；如果路径中的目录不存在，则会创建）：
```
archive-agent mcp --to-json-auto Output/
```

📌 注意： 从 Archive Agent v12.2.0 起，使用 --to-json-auto 选项时，也会创建包含答案的对应 Markdown 文件（.md）。（目前无法选择不创建该文件。）

📌 注意： 在控制台中按 CTRL+C 可关闭 MCP 服务。

📌 注意： 对 MCP 服务的每个请求（/sse 流和 /messages/）都必须携带 LOCAL_AUTH_PASSWORD，可以使用 Authorization: Bearer <password>（MCP 客户端、脚本），也可以使用带任意用户名的 HTTP Basic 身份验证（浏览器、curl -u x:<password>）。其他任何请求都会收到 401 响应。

独立 STRICT OCR

要使用 STRICT 策略对 PDF 文件进行 OCR 并输出 Markdown 文件，请运行：

archive-agent standalone-ocr-strict "~/Documents/scan.pdf"

每一页都会渲染为整页图像，并通过 AI 视觉 OCR 进行处理。结果会写入 PDF 旁边的 .md 文件（例如 scan.md）。

要设置自定义渲染分辨率，请传入 --dpi 选项（默认值：150）。

要查看更多信息，请传入 --verbose 选项。

要在此操作中绕过 AI 缓存，请传入 --nocache 选项。

📌 注意： 此命令不需要运行中的 Qdrant 数据库。

💡 提示： 使用这些 MCP 配置，让 IDE 或 AI 扩展自动化 Archive Agent：

.vscode/mcp.json 用于 GitHub Copilot Agent 模式（VS Code）：
.roo/mcp.json 用于 Roo Code（VS Code 扩展）

MCP 工具

Archive Agent 通过 MCP 提供以下工具：

MCP 工具	对应的 CLI 命令	参数	实现方式	描述
`get_patterns`	`patterns`	无	同步	获取包含 / 排除模式列表。
`get_files_tracked`	`track` and then `list`	无	同步	获取已跟踪文件列表。
`get_files_changed`	`track` and then `diff`	无	同步	获取已更改文件列表。
`get_collections`	无	无	同步	获取可用的 Qdrant 集合列表。
`get_chunk_headers`	无	`file_path` [, `collection`]	异步	获取文件的分块标题列表。
`get_search_result`	`search`	`question` [, `collection`]	异步	获取与问题相关的文件列表。
`get_answer_rag`	`query`	`question` [, `collection`]	异步	使用 RAG 获取问题的答案。

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

💡 提示： 可选的 collection 参数允许你按名称查询任意 Qdrant 集合。如果省略，则使用当前配置的集合。使用 #get_collections 可查看可用集合。

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

💡 提示： #get_answer_rag 的输出遵循 AiQuery.py 中定义的 QuerySchema 格式。

💡 提示： #get_chunk_headers 工具会返回指定文件的所有分块标题（语义摘要），快速概览文档结构。无需检索全文，即可了解文档内容。

更新 Archive Agent

如果你刚安装了 Archive Agent，则暂时无需执行此步骤。不过，要使用最新功能，建议定期更新安装。

要更新 Archive Agent 安装，请在安装目录中运行：

./update.sh

📌 注意： 如果更新失败，请尝试删除安装目录，然后重新安装 Archive Agent。你的配置和数据安全地存储在其他位置；详情请参阅 Archive Agent 设置和 Qdrant 数据库。

💡 实用提示： 如需同时更新 Qdrant Docker 镜像，请运行：

sudo --preserve-env=LOCAL_AUTH_PASSWORD ./manage-qdrant.sh update

📌 注意： sudo 会清除环境变量，因此需要使用 --preserve-env=LOCAL_AUTH_PASSWORD；manage-qdrant.sh 没有该变量时会拒绝创建容器。

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 命令，可切换到新的或现有的配置文件（参见创建或切换配置文件）。

Key	Description
`config_version`	配置版本
`mcp_server_host`	MCP 服务主机（默认为 `http://127.0.0.1`；设为 `http://0.0.0.0` 可在局域网中公开访问）
`mcp_server_port`	MCP 服务端口（默认为 `8008`）
`ocr_strategy`	`DecoderSettings.py` 中的 OCR 策略
`ocr_auto_threshold`	`auto` OCR 策略选择 `relaxed` 而非 `strict` 所需的最少字符数
`image_ocr`	图像处理：`true` 启用 OCR，`false` 禁用 OCR。
`image_entity_extract`	图像处理：`true` 启用实体提取，`false` 禁用实体提取。
`chunk_lines_block`	分块时每个块的行数
`chunk_words_target`	每个块的目标词数
`qdrant_server_url`	Qdrant 服务的 URL
`qdrant_collection`	Qdrant 集合的名称
`retrieve_score_min`	检索到的块的最低相似度分数（`0`...`1`）
`retrieve_chunks_max`	检索到的块的最大数量
`retrieve_knee_enable`	检索的自适应截断（`true` 启用基于拐点的截断，`false` 禁用）
`retrieve_knee_sensitivity`	拐点检测灵敏度（Kneedle `S` 参数；值越高，策略越保守）
`retrieve_knee_min_chunks`	应用自适应截断时保留的最少块数
`rerank_chunks_max`	重排序后保留的排名靠前的块数
`expand_chunks_radius`	在每个重排序后的块前后添加的相邻块数量
`max_workers_ingest`	并行处理的最大文件数，每个文件创建一个线程
`max_workers_vision`	每个文件可并行处理的最大视觉请求数，每个请求创建一个线程
`max_workers_embed`	每个文件可并行处理的最大嵌入请求数，每个请求创建一个线程
`ai_provider`	`ai_provider_registry.py` 中的 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`	查询模型的温度（GPT-5 不适用）
📌 注意：使用 GPT-5（自 Archive Agent v14.0.0 起为默认模型）时，`ai_temperature_query` 会被忽略。
目前无法在配置中设置 GPT-5 的推理力度和详细程度，
但可以直接在 `OpenAiProvider.py` 中自定义。

📌 注意： 由于 max_workers_vision 和 max_workers_embed 请求会针对每个文件并行处理，而 max_workers_ingest 个文件也会并行处理，因此请求总数会迅速增加。请根据系统资源和 AI 提供商的速率限制进行调整。

监视列表

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

监视列表只能通过以下命令进行管理：

include / exclude / remove
track / commit / update

AI 缓存

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

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

同一张图片只进行一次 OCR。
同一段文本只进行一次分块。
同一段文本只进行一次嵌入。
同一组分块只进行一次重排序。

这样，如果提交中断，Archive Agent 可以快速从中断处继续。

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

💡 提示： 查询永远不会缓存，因此你始终能获得最新答案。

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

📌 技术说明： Archive Agent 使用由文本／图片字节以及用于分块、嵌入、重排序和视觉处理的 AI 模型名称组成的复合哈希作为缓存键。缓存键具有确定性；更改用于分块、嵌入或视觉处理的 AI 模型名称时，生成的缓存键也会改变。由于缓存条目会永久保留，切换回先前的 AI 模型名称组合时，将再次访问“旧”键。

Qdrant 数据库

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

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

Qdrant 服务仅监听 127.0.0.1:6333，并要求使用 LOCAL_AUTH_PASSWORD 作为 API 密钥（manage-qdrant.sh 将其作为 QDRANT__SERVICE__API_KEY 传递给容器）。Archive Agent 会自动发送该密钥。

💡 提示： 访问你的 Qdrant 控制面板以管理集合和快照。控制面板会要求输入 API 密钥（LOCAL_AUTH_PASSWORD）。直接调用 REST 接口时需要使用 api-key 标头：

curl -H "api-key: $LOCAL_AUTH_PASSWORD" http://127.0.0.1:6333/collections

📌 注意： 创建时未设置 API 密钥（或密钥已过期）的 Qdrant 容器必须重新创建一次； manage-qdrant.sh start 会拒绝启动未设置 API 密钥的容器。存储内容会保留：

sudo --preserve-env=LOCAL_AUTH_PASSWORD ./manage-qdrant.sh recreate

开发者指南

Archive Agent 是从零开始编写的，旨在用于软件两端的教育目的。

💡 提示： 跟踪 test_data/ 即可开始使用某种测试数据。

重要模块

如需开始使用，请查看以下出色的模块：

文件在 archive_agent/data/FileData.py 中处理
应用上下文在 archive_agent/core/ContextManager.py 中初始化
默认配置在 archive_agent/config/ConfigManager.py 中定义
CLI 命令在 archive_agent/__main__.py 中定义
提交逻辑在 archive_agent/core/CommitManager.py 中实现
CLI 详细程度由 archive_agent/core/CliManager.py 处理
GUI 在 archive_agent/core/GuiManager.py 中实现
用于分块、嵌入、视觉和查询的 AI API 提示词在 archive_agent/ai/AiManager.py 中定义
AI 提供商注册表位于 archive_agent/ai_provider/ai_provider_registry.py

如果你发现遗漏或不佳的模式，欢迎贡献代码并进行重构！

网络与重试处理

Archive Agent 实现了全面的重试逻辑，包含指数退避和智能故障检测：

AI 提供商操作：针对网络超时和 API 错误，最多重试 10 次并采用指数退避（最大延迟 60 秒）
数据库操作：针对 Qdrant 连接问题，最多重试 10 次并采用指数退避（最大延迟 10 秒）
架构验证：AI 响应解析失败时最多重试 10 次，每次失败都会使缓存失效
MAX_TOKENS 检测：模型达到令牌上限时立即跳过（避免对必然发生的截断进行无效重试）
块级容错：跳过分块失败的块并记录 CRITICAL 日志，继续处理文件
双层策略：网络层重试处理基础设施故障，架构层重试处理 AI 响应质量问题

所有并行处理器（分块、视觉、嵌入）都会正确传递致命错误，而不是在数据损坏时静默继续。

代码测试与分析

如需运行单元测试、检查类型和检查代码风格，请运行：

./audit.sh

使用内存存储运行 Qdrant

如需使用内存存储运行 Qdrant（例如，在无法使用 Docker 的 OpenAI Codex 环境中），请在运行 install.sh 和 archive-agent 之前导出此环境变量：

export ARCHIVE_AGENT_QDRANT_IN_MEMORY=1

install.sh 会检查此环境变量，以跳过 manage-qdrant.sh。
QdrantManager.py 会检查此环境变量，以忽略服务器 URL 和 API 密钥，改用内存存储。

📌 **注意：**Qdrant 内存存储具有易失性（不会持久化到磁盘）。

工具

重命名块元数据中的文件路径

如需批量重命名当前活动 Qdrant 集合中块元数据的文件路径，请运行：

cd tools/

./qdrant-rename-paths-in-chunk-metadata.py
# OR
uv run python qdrant-rename-paths-in-chunk-metadata.py

当你移动文件或重命名文件夹后，如果不想再次运行 update 命令，此工具会很有用。

📌 注意：

此工具会直接修改 Qdrant 数据库 — 如果处理重要数据，请务必备份。
此工具不会更新受跟踪的文件。你需要使用手动查找和替换来更新监视列表（请参阅 Archive Agent 设置）。

从上下文标头中移除文件路径

在 v11.0.0 之前，Archive Agent 会在块上下文标头中包含文件路径；这是一个糟糕的设计决定，导致检索结果出现偏差。

如需批量移除当前活动 Qdrant 集合中上下文标头的所有文件路径，请运行：

cd tools/

./qdrant-remove-paths-from-chunk-headers.py
# OR
uv run python qdrant-remove-paths-from-chunk-headers.py

📌 注意：

此工具会直接修改 Qdrant 数据库 — 如果处理重要数据，请务必备份。

已知问题

基于 GNU GPL v3.0 授权

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。

欢迎协作者

欢迎为这个开源项目贡献力量！随时可以提交问题和提交拉取请求。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

🧠 Archive Agent

关于 🧠 Archive Agent

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

Archive Agent

用自然语言查找所需内容

在设备上原生索引文档

你的 AI，由你选择

可扩展的性能

架构

刚开始使用？

文档

支持的操作系统

安装 Archive Agent

Ubuntu / Linux Mint

AI 提供商设置

OpenAI 提供商设置

OpenRouter 提供商设置

Ollama 提供商设置

LM Studio 提供商设置

处理哪些文件

文件的处理方式

OCR 策略

智能分块的工作方式

分块引用的工作原理

分块的检索方式

分块的重排与扩展方式

答案的生成方式

用于跟踪的文件选择方式

运行 Archive Agent

在命令行（CLI）中快速入门

CLI 命令参考

查看命令列表

创建或切换配置文件

在 nano 中打开当前配置文件的配置

添加包含模式

添加排除模式

移除包含 / 排除模式

列出包含 / 排除模式

解析模式并跟踪文件

列出已跟踪的文件

列出已更改的文件

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

合并跟踪和提交

搜索文件

查询你的文件

启动 Archive Agent GUI

启动 MCP 服务

独立 STRICT OCR

MCP 工具

更新 Archive Agent

Archive Agent 设置

配置文件配置

监视列表

AI 缓存

Qdrant 数据库

开发者指南

重要模块

网络与重试处理

代码测试与分析

使用内存存储运行 Qdrant

工具

重命名块元数据中的文件路径

从上下文标头中移除文件路径

已知问题

基于 GNU GPL v3.0 授权

欢迎协作者

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？