RootMind

RootMind

English | 德语

安装 · 连接 MCP 客户端 · 工作原理 · 为何采用工具循环 · 安全性 · 限制

向你的文档提问，并获取附有出处页码的答案。

RootMind 会在你的电脑上为你选定的文件夹建立索引（PDF、Word、Excel、 PowerPoint、CSV、Markdown 和文本文件）。你提出问题时，大模型会搜索该索引， 并读取它所需的段落，然后给出答案，并标注到具体的页面、幻灯片或工作表。它不使用 嵌入模型或向量数据库：索引采用 SQLite 中的普通全文搜索，检索由大模型驱动。

https://github.com/user-attachments/assets/d3cc0249-a550-4de5-ae6b-55c1291a282f

• 答案附有引用。 每个答案都会列出文件名；在可解析的情况下，还会标注页码、幻灯片或工作表。
• 文件留在你的电脑上。 索引和搜索都在本地进行，不需要大模型或 API 密钥。回答问题时，会将问题和大模型读取的摘录发送给你配置的服务提供商（Anthropic、OpenAI 或 xAI）。如果使用本地的 Ollama 服务作为提供商，任何内容都不会离开你的电脑（参见使用 Ollama 的本地模型）。
• 按需读取，不会塞入整篇文档。 大模型不会将整篇文档粘贴到聊天中，而是搜索并读取目标内容窗口，每一步都会显示为工具调用。与经典 RAG 相比，这会增加大模型往返调用的次数；参见为何采用工具循环而非嵌入式 RAG。
• 可通过其他工具使用。 同一组只读工具也通过 MCP 提供，可供 Claude Desktop、Claude Code、n8n 和其他 Agent 使用。
• 支持 Windows 和 Linux。 桌面应用提供英语和德语界面；许可证为 MIT。

几分钟内开始体验

1. 下载 RootMind-Setup-x64.exe （Windows 10 或 11），或下载 .deb、.rpm 或 AppImage （Linux）。
2. 启动 RootMind，然后在 Folders 下添加一个包含文档的文件夹。
3. 打开 Chat，勾选 Search only 并进行搜索。此操作不需要 API 密钥。若要获取答案，请在 Settings 中添加密钥，然后取消勾选 Search only。

快速入门指南包含详细说明。

项目简介

此仓库包含两部分：

• 后端（Python、FastAPI）：索引器、全文搜索、Agent 循环、localhost REST API，以及通过 stdio 和 HTTP 提供的 MCP 服务。
• 桌面应用（基于 React 和 TypeScript 的 Tauri 2，加上 Rust 外壳）：适用于 Windows 和 Linux 的聊天与搜索界面，支持英语和德语。在 Windows 上，安装程序会将后端配置为 Windows 服务；在 Linux 上，应用会将后端配置为你账户的 systemd 用户服务。应用会与该服务通信。

**状态：**这是一个个人项目，不以商业方式维护，也不承诺提供支持。欢迎提交问题和拉取请求，我们会尽力回应。

安装

每个发布版本都提供以下 Windows（x64）下载；Linux 安装包请参阅 在 Linux 上安装：

• RootMind-Setup-x64.exe， 适用于大多数使用 Windows 10 或 11 的用户：包含桌面应用及其 Windows 服务。运行安装程序并批准一次管理员提示即可；无需安装 Python。它会将应用安装到 %ProgramFiles%\RootMind，并为当前登录 Windows 的账户设置 RootMind 服务。
• rootmind-backend-windows-x64.zip， 适用于命令行和服务器：仅包含后端，不含应用（请参阅 为开发者和服务器安装）。
• rootmind.mcpb， 用于 Claude Desktop 的 RootMind，请在安装应用后安装（请参阅 在 Claude Desktop 中使用 RootMind）。

安装需要管理员账户。服务属于使用 RootMind 的账户，因此安装程序仅会在以当前登录 Windows 的账户运行时设置服务。安装目录始终为 %ProgramFiles%\RootMind，且只有管理员可以更改此文件夹；安装程序会拒绝使用其他目录（例如通过 /D= 指定，退出代码为 10）。

静默安装和托管安装。 winget、Intune、Configuration Manager 等工具通常会以 SYSTEM 身份静默运行安装程序（/S）。在这种情况下，以及管理员在另一个账户登录时批准提示的情况下，安装程序会安装应用，但不会安装服务，并以 0 退出。使用 RootMind 的账户首次打开应用时会设置服务：RootMind 会提示“The RootMind service is not set up yet”，点击 Set up 并批准一次管理员提示，即可为该账户完成设置。标准账户无法设置服务；必须使用实际使用 RootMind 的管理员账户。如果安装程序因其他原因无法设置服务，也会以 0 退出，RootMind 会显示问题和 Repair。结果会记录在卸载项 HKLM\Software\Microsoft\Windows\CurrentVersion\Uninstall\RootMind 中（RootMindServiceSetup 的值为 installed、skipped 或 failed，并包含 RootMindServiceSetupReason；如果失败，还会包含 RootMindServiceSetupCode）。以 SYSTEM 身份运行的更新会就地更新现有服务。

安装程序目前尚未进行代码签名。Windows SmartScreen 可能会显示“Windows 已保护你的电脑”：选择 更多信息，然后选择 仍要运行。如果启用了 Smart App Control，它可能会在没有此选项的情况下阻止安装程序或 RootMind 的服务程序。Smart App Control 不支持为单个应用设置例外；计划推出的签名版本将解决此问题（请参阅 代码签名政策）。

接下来启动 RootMind，并在 Folders 下添加一个文件夹。大约一分钟内便会开始编制索引；文件夹建立索引后，无需 API 密钥即可搜索。若要提问，请在 Settings 下添加 Anthropic、OpenAI 或 xAI 的 API 密钥并保存，或者选择 Ollama 使用本地模型。应用关闭时，服务仍会保持索引最新。

应用会遵循 Windows 的显示语言（英语或德语）；前往 Settings → Appearance → Language 可更改语言。Settings → About 会显示应用和后端版本，并提供发布版本和问题页面的链接。

在 Linux 上安装

每个发行版还提供适用于 Linux x86-64 的应用，要求 glibc 2.35 或更高版本 （Ubuntu 22.04、Debian 12、Fedora 38、openSUSE Tumbleweed 及更新版本）。选择 适合你所用发行版的软件包：

发行版	下载	安装
Ubuntu、Debian 及其衍生版本	RootMind-amd64.deb	sudo apt install ./RootMind-amd64.deb
Fedora、openSUSE Tumbleweed	RootMind-x86_64.rpm	sudo dnf install ./RootMind-x86_64.rpm（openSUSE：sudo zypper install ./RootMind-x86_64.rpm）
其他任何发行版	RootMind-x86_64.AppImage	chmod +x RootMind-x86_64.AppImage，然后运行

软件包会将应用及其后端安装到 /usr/lib/RootMind，并安装 WebKitGTK 4.1；只有这一步需要 root 权限。AppImage 无需安装，但需要 FUSE 2（Ubuntu 24.04 上的软件包为 libfuse2t64，其他系统为 libfuse2）。使用 sha256sum --check --ignore-missing SHA256SUMS.txt 检查下载文件（参见 验证下载文件）。

启动 RootMind：从应用菜单中启动，或在终端中运行：

rootmind-desktop

安装 .deb 和 .rpm 时会显示此命令。运行 AppImage 文件即可启动。

Windows Subsystem for Linux。 在 Windows 11 上，RootMind 也能在 WSL 中运行，窗口会显示在 Windows 桌面上（WSLg）。WSL 需要 systemd 才能运行服务：将以下内容添加到 /etc/wsl.conf，然后在 Windows 中运行 wsl --shutdown，再重新打开该发行版。没有 systemd 时，RootMind 会提示无法设置其服务。

[boot]
systemd=true

首次启动时会发生什么。 RootMind 会为你的账户设置后台服务，无需询问，也无需 root 权限：两个 systemd 用户服务，rootmind-backend.service（REST API 和索引）以及 rootmind-mcp-http.service（通过 HTTP 提供 MCP），位于 ~/.config/systemd/user/。这些服务会运行一份位于 ~/.local/share/rootmind/runtime/ 的后端副本，因此即使关闭或移动 AppImage，服务也会继续运行；服务数据保存在 ~/.local/share/rootmind 中。启动较新版本的应用时，它会将服务更新到自身版本。如果设置失败，RootMind 会说明原因；点击 Set up（或 Repair）可重试。前往 Settings → RootMind service → Details，可以查看服务状态以及 logs/install.log 的末尾内容。然后像在 Windows 上一样，在 Folders 下添加文件夹。

服务会在你登录时启动，并在最后一个会话结束时停止。若要在无人登录时仍让服务运行（例如，为同一台计算机上的 n8n 提供服务），请为你的账户启用一次 lingering：

loginctl enable-linger "$USER"

更新：安装新版本的软件包（如上所述，或运行 sudo dnf upgrade ./RootMind-x86_64.rpm），或者替换 AppImage；RootMind 会在启动时更新其服务。

卸载：先卸载服务，再卸载应用：

# the .deb and .rpm (from the AppImage: ~/.local/share/rootmind/runtime/*/rootmind-backend)
/usr/lib/RootMind/backend/rootmind-backend service uninstall
sudo apt remove root-mind        # or: sudo dnf remove root-mind

service uninstall 会停止并移除这两个用户服务及程序副本，但会保留 ~/.local/share/rootmind 中的设置、API 密钥、索引和 MCP 令牌；service uninstall --purge 则会一并删除这些数据。聊天记录位于 ~/.local/share/io.github.cgaeking.rootmind。

从 1.x 升级

RootMind 1.x 按账户安装；除非启用了后台服务，否则后端会在应用内部运行。2.0 安装程序会自动移除你账户下的 1.x 安装。1.x 内置后端的文件夹、设置、API 密钥和索引不会迁移：你需要重新添加文件夹并再次输入 API 密钥。如果在 1.x 中启用了后台服务，该服务会更新，并保留其文件夹、设置和索引。无论哪种情况，聊天记录都会保留。

验证下载文件

每个版本都会在说明中列出安装程序的大小，并为每个文件提供 SHA256SUMS.txt 和构建来源证明。哈希值必须与 SHA256SUMS.txt 中对应文件的哈希值一致：

(Get-FileHash .\RootMind-Setup-x64.exe -Algorithm SHA256).Hash.ToLower()

sha256sum --check --ignore-missing SHA256SUMS.txt
gh attestation verify RootMind-Setup-x64.exe --repo cgaeking/rootmind

更新和卸载

要更新，请运行新版本的安装程序并确认提示。安装程序会直接替换已安装的版本，不再询问其他问题，并更新服务；端口、令牌、设置、索引和聊天记录都会保留。如果应用正在运行，安装程序会先提示你将其关闭。

在 Windows 设置 → 应用中卸载 RootMind。这会移除 RootMind 服务。除非勾选删除应用程序数据，否则服务数据（设置、API 密钥、索引、令牌和日志）会保留在 %ProgramData%\RootMind 中；勾选后会删除这些数据以及聊天记录。静默卸载（/S，由包管理器运行）也会移除服务，但绝不会删除数据。要稍后删除数据，请在提升权限的命令提示符中删除 %ProgramData%\RootMind。

RootMind 服务

RootMind 的后端以 Windows 服务 RootMind-Backend 的形式运行。即使应用关闭，它也会保持索引最新，并随 Windows 一起启动；应用是它的客户端。“设置” → RootMind 服务会显示其状态、地址和版本；如果尚未设置服务（例如静默安装或托管安装后），这里会提供设置；如果服务已停止或无响应，则会提供修复（每项操作都需要一次管理员批准）。当服务的版本低于应用版本时，更新服务会将其更新到应用的版本。这些操作都会运行应用安装在 %ProgramFiles%\RootMind\backend 中的后端，只有管理员可以修改此目录。

• 此服务属于安装 RootMind 的账户。同一台计算机上的其他账户无法使用它；如需将 RootMind 转移到另一个账户，请先卸载，然后从该账户重新安装。
• 服务以 LocalSystem 身份运行，但只会读取你的账户无需管理员权限即可打开的文件夹和文件。它无法访问网络驱动器和共享、系统文件夹以及其他用户的配置文件；“文件夹”屏幕会标记它无法读取的文件夹。
• 其 REST API 需要令牌。令牌位于 %ProgramData%\RootMind\data\rest_token.txt，只有你的账户、SYSTEM 和管理员可以读取。应用仅在确认服务自身的进程正在该端口上侦听后才会使用令牌。
• 另一个服务 RootMind-MCP-HTTP 会在 127.0.0.1 上通过 HTTP 提供 MCP 服务，并使用其自身的 bearer 令牌（请参阅连接 MCP 客户端）。该服务默认启用；勾选框通过 HTTP 提供 MCP 服务可将其关闭或重新开启（需要一次管理员批准）。下方的**远程访问（ngrok）**会为云助手提供一个公开的 HTTPS 地址（默认关闭；请参阅远程访问）。
• 这些服务从 %ProgramFiles%\RootMind Service\ 下各自的程序副本运行，只有管理员可以修改此目录；数据保存在 %ProgramData%\RootMind 中。

在 Linux 上，同一服务由你账户的两个 systemd 用户服务组成（请参阅在 Linux 上安装），无需 root 权限或批准：

• 服务以你的账户身份运行，并读取该账户有权读取的内容，包括已挂载的网络共享。同一台计算机上的其他账户启动 RootMind 时，会在其他端口运行各自的服务。
• REST 令牌位于 ~/.local/share/rootmind/data/rest_token.txt，只有你的账户可以读取（文件权限为 0600，所在文件夹权限为 0700）。应用仅在确认单元自身的进程正在该端口上侦听后才会使用令牌。
• MCP over HTTP 和远程访问的工作方式与 Windows 上相同；通过 HTTP 提供 MCP 服务会在无需提示的情况下添加或移除 rootmind-mcp-http.service。
• systemctl --user status rootmind-backend 和 journalctl --user -u rootmind-backend 可显示单元及其 systemd 日志；RootMind 自身的日志位于 ~/.local/share/rootmind/logs。

“设置” → 高级可将应用连接到其他地址上的 RootMind 后端。SECURITY.md介绍了安全模型。

连接 MCP 客户端

MCP 客户端可使用与应用的 Agent 相同的只读工具，并使用自己的模型。将它们连接到服务的 MCP over HTTP：在“设置” →“RootMind 服务”中可查看 MCP 端点并复制端点和令牌（复制令牌）。Claude Desktop 有一个无需上述信息的程序包（请参阅在 Claude Desktop 中使用 RootMind）。Claude Code：

claude mcp add --transport http rootmind http://127.0.0.1:<port>/mcp \
  --header "Authorization: Bearer <token>"

如果端口 3000 可用，就会使用该端口；否则会从 18400–18499 中选择一个端口。令牌会在更新后保留，服务器会在无需重启的情况下应用文件夹变更。

在 Claude Desktop 中使用 RootMind

1. 从最新版本下载 rootmind.mcpb。
2. 双击该文件。Claude Desktop 会打开它，显示 RootMind 的工具，并在你确认后安装。

无需进行任何配置。该扩展会在这台计算机上查找 RootMind 服务，从中读取 MCP 端口和令牌，并通过 HTTP 连接到 127.0.0.1 上的 MCP。你需要安装 RootMind，并开启 Serve MCP over HTTP（默认开启；位于 Settings → RootMind service）。Claude Desktop 还必须在使用 RootMind 的账户下运行，因为只有该账户可以读取令牌。在 Linux 上，它会通过 ~/.local/share/rootmind/service.json 查找服务；该文件会指定服务运行的程序副本（不含密钥）。如果缺少某项内容，扩展的错误信息会说明该怎么做，例如安装 RootMind 或开启 MCP over HTTP；问题解决后，无需重新安装扩展，下次请求即可正常工作。修复后，扩展会自动跟随服务切换到新端口。要更新扩展，请安装较新版本中的 rootmind.mcpb。该安装包尚未签名，因此 Claude Desktop 会将其标记为未签名。源代码及其工作方式请见：packaging/mcpb。

Claude Desktop 只会启动本地（stdio）MCP 服务；该扩展就是此类服务，会将请求转发到服务的 HTTP 端点。应用文件夹中的程序（rootmind-backend.exe mcp）无法作为已安装应用的 stdio 服务运行：它无法打开服务的索引。stdio 服务适用于使用自有 config.yaml 的源码或 uv 设置（参见 3. 从 MCP 客户端使用工具）。

通过 n8n 连接 MCP

在 n8n 中使用 MCP Client Tool 节点，并填写 Settings → RootMind service 中显示的值；点击 n8n (MCP Client Tool) 旁边的 Copy，即可复制已填入令牌的配置：

字段	值
端点	http://127.0.0.1:<port>/mcp
服务传输方式	HTTP Streamable
身份验证	Header Auth
标头名称	Authorization
标头值	Bearer <token>

• **n8n 与 RootMind 位于同一台计算机上：**使用显示的端点。
• **n8n 在同一台计算机的 Docker 中运行：**在容器内，127.0.0.1 指向容器本身。请使用 http://host.docker.internal:<port>/mcp。Docker Desktop 会将该名称转发到主机。如果连接被拒绝，请在主机上运行反向代理，让它监听容器可访问的地址，并将请求转发到 127.0.0.1:<port>；同时确保其他计算机无法访问该地址。
• **n8n 在另一台计算机上运行：**只能通过位于 127.0.0.1:<port> 前面的 TLS 终止反向代理或隧道（例如远程访问）连接。切勿暴露未加密的 HTTP 端口：该服务使用未加密的 HTTP，任何持有令牌的人都能读取所有已索引文档。请参阅从云端助手连接 RootMind。

从云端助手连接 RootMind

在他人服务器上运行的助手，例如 Grok Bot、云端 n8n 或其他 Web Agent，无法访问你计算机上的 127.0.0.1。它们需要一个转发到 MCP 端点的公开 HTTPS 地址，可通过你计算机上的隧道实现：使用 RootMind 内置的 Remote access（ngrok），或自行运行隧道（Tailscale Funnel、ngrok agent）。无论哪种方式，隧道都只会将请求转发到使用 HTTP 的 MCP，客户端发送的令牌不变。

远程访问

RootMind 可以自行运行隧道。RootMind 服务的 MCP 服务 （RootMind-MCP-HTTP）使用 ngrok 的开源 SDK 建立隧道，因此无需安装 ngrok 程序。默认情况下，此功能处于关闭状态。

1. 在 ngrok.com 创建免费账户，并从控制面板复制 authtoken（Your Authtoken）。在 Domains 下，你可以预留一个免费的固定域名；如果没有预留，ngrok 会分配一个可能会变化的地址。
2. 在“设置” → RootMind 服务下的 Remote access (ngrok) 中，粘贴 authtoken，并在有域名时一并填写，然后选择 Save。authtoken 之后不会再显示：此字段只会显示 Saved （通过 Replace 和 Remove 可更改）。
3. 勾选 Reach MCP from the internet through ngrok 并确认。状态会变为 Connected，并显示 Public MCP endpoint （https://<domain>/mcp），旁边有 Copy。在助手中使用此地址和 MCP 令牌（Copy token），请参阅在助手中。

远程访问需要开启 Serve MCP over HTTP；关闭此选项也会关闭远程访问。更改无需管理员批准，几秒内即可生效，并且在重启和更新后仍会保留：隧道会随服务一同启动。取消勾选此框会立即关闭公共地址。如果与 ngrok 的连接断开，服务会重新连接；连接被拒绝（authtoken 错误、域名不属于你或已被占用）时，状态会显示 ngrok 返回的消息，并逐渐延长重试间隔（最长为五分钟）。

• ngrok 每个域名只允许一个端点。如果你已在同一域名上运行自己的 ngrok 隧道，请先停止该隧道，再开启远程访问。
• authtoken 存储在 %ProgramData%\RootMind\data\ngrok_authtoken.txt 中，只有 SYSTEM、管理员和 MCP 服务账户可以读取；它不会写入 config.yaml，不会通过应用的 API 返回，也不会写入日志。卸载时如果不选择 Delete the application data，该文件会保留。
• ngrok 免费账户有流量限制；请参阅 ngrok 的定价页面。

自建隧道

使用 ngrok agent（免费账户，一个免费的固定域名）：

1. 在 ngrok.com 创建账户，然后安装 agent 并添加 authtoken：

   winget install ngrok.ngrok
   ngrok config add-authtoken <your-ngrok-authtoken>
   

2. 在 ngrok 控制面板的 Domains 下查看你的免费域名，然后启动通往 MCP 端口的隧道（除非“设置”中显示其他端口，否则为 3000）：

   ngrok http 3000 --url https://<your-free-domain>
   

   若要在重启后继续运行，请在 ngrok 配置文件中定义隧道，并将其安装为服务（ngrok service install； 请参阅 ngrok 文档）。

使用 Tailscale Funnel（免费 Tailscale 账户和应用）：

tailscale funnel --bg 3000

此命令会输出公共地址（https://<computer>.<tailnet>.ts.net），并在后台保持 Funnel 运行，重启后也会继续运行。首次运行时，系统会提示你为 tailnet 启用 Funnel。

在助手中

使用以下信息添加自定义 MCP 连接器（或 n8n 的 MCP Client Tool）：

字段	值
URL	https://<your-public-address>/mcp
传输方式	HTTP Streamable
身份验证	标头 Authorization: Bearer <token>（“设置” → RootMind 服务 → Copy token）

只提供 OAuth 登录且无法发送 bearer token 的客户端无法通过此方式连接。

请注意：

• 任何拥有该令牌的人都能通过隧道读取所有已索引文档。请妥善保管令牌；停止隧道（或关闭远程访问）即可关闭公共访问。
• 云端助手通过 RootMind 读取的内容（搜索结果和文档文本）会发送给该助手的提供商。
• RootMind 会拒绝网页在浏览器中发出的请求（带有非本地 Origin 标头的请求）；这不会影响来自助手的服务器到服务器请求。

工作原理

flowchart LR
    desktop["Desktop app<br/>Tauri + React"]
    mcpclient["MCP client<br/>e.g. Claude Desktop, Claude Code, n8n"]

    subgraph backend["Backend (Python)"]
        rest["REST API<br/>127.0.0.1 + bearer token"]
        mcp["MCP servers<br/>stdio, HTTP + bearer token"]
        engine["Agent loop<br/>rlm_engine/engine.py"]
        tools["Tool layer<br/>tools.py"]
        repo[("SQLite<br/>FTS5 + trigrams")]
        indexer["Indexer + scheduler"]
    end

    folders[("Your folders")]
    llm(["LLM provider<br/>Anthropic, OpenAI or xAI"])

    desktop -- "/query, /search, /config" --> rest
    mcpclient --> mcp
    rest --> engine
    rest -- "search, documents" --> repo
    engine <--> llm
    engine --> tools
    mcp --> tools
    tools --> repo
    indexer -- "read files" --> folders
    indexer -- "extracted text" --> repo

1. 索引过程不使用 LLM。 连接器会遍历每个已配置的文件夹。解析器会从 PDF、DOCX、XLSX、PPTX、CSV、Markdown 和其他文本文件中提取文本。文本会存入 SQLite：一个文档表、一个 FTS5 索引，以及一个用于容错搜索的三元组表。PDF 页面、幻灯片和工作表会在文本中保留标记，因此可以按位置引用搜索结果。内容哈希未变的文件会被跳过。
2. 由模型决定要读取什么。 对于 POST /query，引擎会向模型提供五种只读工具：search_documents、search_fuzzy、list_documents、read_document 和 get_statistics。典型流程如下：搜索、读取命中位置附近的文本，必要时用其他词再次搜索，然后作答。
3. 循环有上限。 循环最多进行 10 次可能请求工具的模型调用。如果模型仍在搜索，会再进行一次不启用工具的最终调用，要求它根据已找到的内容作答。每轮模型调用最多运行 8 次工具调用；单个问题的工具结果总计最多 200,000 个字符，超出上限的调用会返回错误结果，而不会运行。每次 LLM 调用都有超时限制；每次读取最多返回 50,000 个字符；工具错误会作为错误结果返回给模型，而不会终止循环；如果答案因输出令牌数达到上限而被截断，也会注明这一点。
4. 答案附带来源。 响应会列出模型读取过的文档，并在可确定时注明页码、幻灯片或工作表；还会列出每次工具调用，以及每次 LLM 调用停止的原因。
5. MCP 客户端使用自己的模型。 通过 MCP，RootMind 提供相同的工具定义，由客户端的模型决定如何处理。搜索和索引从不需要 API 密钥；只有问题（POST /query）、聊天标题和设置调用中的模型列表会调用服务提供商。

桌面应用会与同一台计算机上的 RootMind 服务通信，也可以与在 Settings → Advanced 中输入地址的自定义后端通信。开发版本不会使用该服务，并会要求输入后端地址。详情请参阅 ARCHITECTURE.md。

为什么使用工具循环，而不是嵌入式 RAG

典型的 RAG 流程会将文档切分成文本块，为文本块生成嵌入向量，根据向量相似度检索最匹配的文本块，并将这些文本块放入提示词中。模型只能看到该检索步骤选出的内容。

RootMind 会将每份文档的完整文本保存在全文索引中，并让模型主导检索。模型可以搜索、查看片段、读取命中位置附近的文本，并在首次查询未命中时使用不同术语再次搜索。这有时称为 RLM 风格或 Agent 式检索。引擎模块以这一理念命名为 rlm_engine；在此代码库中，它是一个有上限的工具使用循环，并不是会递归调用自身的模型。

效果较好	效果较差
精确术语：发票编号、产品代码、姓名、金额	同义词和释义：“vacation”无法匹配“paid time off”，除非模型尝试使用另一个词
无需嵌入模型或向量存储；索引过程只解析文本，且可离线运行	问题所用语言与文档语言不同
模型会读取命中位置附近的上下文，例如数字上方的表头，而不是孤立的文本块	每个问题需要更多次 LLM 往返调用，因此延迟和令牌成本更高
每个检索步骤都会显示为工具调用	答案质量取决于模型的搜索策略

三元组模糊搜索可以处理拼写错误，但不能处理同义词。Eval 用例 c09（同义词陷阱）会持续体现这一弱点。

为开发者和服务器安装

使用 uv 安装（适用于 Python 3.12 或更高版本的任意操作系统；如果需要，uv 会安装 Python）：

uv tool install "git+https://github.com/cgaeking/[email protected]#subdirectory=backend"
rootmind --help        # api, index, rebuild-trigrams, mcp, mcp-http, service

这会安装 rootmind、rootmind-mcp 和 rootmind-mcp-http 命令。 在 Windows 上，通过这种方式安装后，rootmind service status 和 rootmind service uninstall 可以正常使用，但 rootmind service install 会被拒绝，并显示发布版本构建的下载地址。该服务以 SYSTEM 身份运行，因此只能运行位于仅管理员可更改文件夹中的程序；service install 会将发布版本构建复制到这样的文件夹，而 uv 或 pip 环境则位于你的账户可以更改的文件夹中。

Windows 服务器或未安装应用的计算机。 发布包还包含仅有后端的版本 rootmind-backend-windows-x64.zip。下载并在 PowerShell 中验证：

$base = "https://github.com/cgaeking/rootmind/releases/latest/download"
Invoke-WebRequest "$base/rootmind-backend-windows-x64.zip" -OutFile rootmind-backend-windows-x64.zip -UseBasicParsing
Invoke-WebRequest "$base/SHA256SUMS.txt" -OutFile SHA256SUMS.txt -UseBasicParsing
$line = Select-String -Path SHA256SUMS.txt -SimpleMatch "rootmind-backend-windows-x64.zip"
$expected = ($line.Line -split '\s+')[0]
$actual = (Get-FileHash rootmind-backend-windows-x64.zip -Algorithm SHA256).Hash.ToLower()
if ($actual -ne $expected) { throw "Checksum mismatch: $actual" }

然后，以需要由 RootMind 建立索引的文件夹所属账户（该账户必须是本地管理员）打开提升权限的 PowerShell，将压缩包解压到仅管理员可更改的文件夹中，并从该处安装服务。 如果程序位于其他账户也能更改的文件夹（例如下载文件夹）中，service install 会拒绝安装并返回退出代码 10：

$dir = Join-Path $env:ProgramFiles "RootMind Backend"
Expand-Archive rootmind-backend-windows-x64.zip -DestinationPath $dir -Force
$exe = Join-Path $dir "rootmind-backend\rootmind-backend.exe"
# install, or update an installed service
& $exe service install
# state, port, version and token files (works without elevation)
& $exe service status
# remove the service; --purge also deletes its data
& $exe service uninstall

service install 会将程序复制到 %ProgramFiles%\RootMind Service\<version>-<id>\，因此之后不再需要解压后的文件夹。它使用端口 8000，以及用于 MCP over HTTP 的端口 3000；如果这些端口已被占用，--port auto 和 --mcp-port auto 会回退到 18300–18399 和 18400–18499。全新安装默认启用 MCP over HTTP；使用 --no-mcp-http 可将其关闭。再次运行 service install 会更新服务，并保留其端口、MCP 设置、令牌和数据；service install --help 会列出所有选项。REST 令牌位于 %ProgramData%\RootMind\data\rest_token.txt，MCP 令牌位于 %ProgramData%\RootMind\data\api_token.txt。

新服务启动时不包含任何文件夹。请在 %ProgramData%\RootMind\config.yaml 的 connectors 下添加文件夹（参见 backend/config.example.yaml；只能通过提升权限的提示符修改该文件），然后使用 Restart-Service RootMind-Backend 重启服务；或者使用 REST 令牌，通过服务的 REST API 向其发送配置，调用 POST /config。

压缩包也可以在不安装服务的情况下运行，例如运行 rootmind-backend.exe api --require-token 或 rootmind-backend.exe mcp-http。

Linux 服务器或未安装应用的计算机。 发布包包含仅有 Linux 后端的版本 rootmind-backend-linux-x64.tar.gz（x86-64，glibc 2.35 或更高版本）。以需要由 RootMind 建立索引的文件夹所属账户（而非 root）解压到仅你可以更改的文件夹中，并从该处安装服务：

base=https://github.com/cgaeking/rootmind/releases/latest/download
curl -L -O "$base/rootmind-backend-linux-x64.tar.gz" -O "$base/SHA256SUMS.txt"
sha256sum --check --ignore-missing SHA256SUMS.txt
mkdir -p ~/opt && tar -xzf rootmind-backend-linux-x64.tar.gz -C ~/opt
exe=~/opt/rootmind-backend/rootmind-backend
"$exe" service install      # install, or update the installed services
"$exe" service status       # state, port, version and token files
"$exe" service uninstall    # remove them; --purge also deletes the data
loginctl enable-linger "$USER"   # keep them running without a login

service install 会将程序复制到 ~/.local/share/rootmind/runtime/<version>-<id>/，并将两个单元文件写入 ~/.config/systemd/user/；该操作需要该账户的 systemd 用户管理器，桌面登录或 SSH 登录会启动此管理器（如果没有管理器，则返回退出代码 11，例如在 su 或 sudo 环境下）。端口、选项和令牌与 Windows 版本相同；数据位于 ~/.local/share/rootmind（config.yaml、data/rest_token.txt、data/api_token.txt）。编辑 config.yaml 后，使用 systemctl --user restart rootmind-backend 重启服务。

使用 Ollama 运行本地模型

在 Settings → LLM 中选择 Ollama（或在 config.yaml 的 llm 下设置 provider: ollama），即可针对本机上的模型运行问答循环。无需 API 密钥；基础 URL 默认为 http://localhost:11434，也可以指向网络中的另一台计算机。

llm:
  provider: ollama
  model: qwen3:8b          # any model you pulled that supports tools
  base_url: http://localhost:11434

• **哪些内容会留在本地：**如果 Ollama 运行在这台计算机上，问题、模型读取的摘录和答案都不会离开这台计算机。如果基础 URL 指向另一台计算机，这些内容会以未加密的普通 http:// 方式发送到那台计算机。
• **必须支持工具调用。**选择 Ollama 列为支持工具的模型（ollama show <model>）。不支持工具调用的模型会显示明确的错误信息。
• **上下文长度：**问答循环会读取文档窗口，而 Ollama 的默认上下文长度较短。请调高该值（例如，为服务设置 OLLAMA_CONTEXT_LENGTH=16384，或使用包含 PARAMETER num_ctx 16384 的 Modelfile），否则长文档会被截断且不会报错。
• **先搜索：**由于并非所有模型都支持工具调用，Ollama 模型在第一轮不会被强制要求调用工具。如果第一轮回答完全没有查看文档，RootMind 会通过明确指示再询问一次。
• 小型本地模型对工具调用循环的遵循情况不如托管模型稳定。在一张 8 GB 显卡上使用 granite4.1:8b 测得：16 个评估用例中有 10 个在三次运行中全部通过，平均通过率为 71%（详情见 backend/evals）。 使用 scripts/run_evals.py --mode live --provider ollama --model <name> 测试你使用的模型（参见 backend/evals）。

从源代码运行

你需要安装 uv；如果需要，它会安装 Python 3.12。桌面应用还需要 Node 24、pnpm 11、Rust 1.96 或更高版本；在 Windows 上还需要 MSVC 构建工具和 WebView2。

1. 无需 API 密钥即可索引和搜索

cd backend
uv sync
cp config.example.yaml config.yaml   # indexes the fictional demo corpus in evals/corpus
uv run rootmind index                # builds data/index.db; no LLM involved
uv run rootmind api                  # REST API on http://127.0.0.1:8000, no token

在第二个终端中：

curl "http://127.0.0.1:8000/search?q=total%20due&limit=3&snippets=true"

首个匹配结果是 invoice_INV-2026-0142.pdf，其中包含 "page": "Page 2"，以及匹配项附近的片段。不使用 snippets=true 时，搜索只返回排序后的列表，在大型索引上速度更快。

交互式 API 文档位于 http://127.0.0.1:8000/docs。API 运行期间，会在启动约 30 秒后重新索引，之后每隔 24 小时重新索引一次（indexer.sync_interval_hours）。若要索引自己的文件，请在 config.yaml 的 connectors 下添加条目。请使用绝对路径：相对连接器路径会以工作目录为基准解析。

以这种方式启动的 rootmind api 不需要令牌。若要启用令牌验证，请设置 RLM_API_TOKEN 或传入 --require-token；这会创建 data/rest_token.txt。并在每个请求中发送 Authorization: Bearer <token>。启用令牌验证后，文档页面将不可用。

2. 提出问题

在环境变量或 backend/.env 中为一个提供方设置密钥（ANTHROPIC_API_KEY、OPENAI_API_KEY 或 XAI_API_KEY；Ollama 无需密钥，参见 使用 Ollama 运行本地模型）（另见 .env.example）。在 config.yaml 的 llm 下选择提供方和模型，然后重启 API，接着：

curl -X POST http://127.0.0.1:8000/query \
  -H "Content-Type: application/json" \
  -d '{"question": "What is the total amount due on invoice INV-2026-0142?"}'

响应包含 answer、sources（已知时包含 page）、tool_calls 和 tokens_used。问题、搜索片段和文档摘录会发送到你配置的提供方；请参见 SECURITY.md。

3. 在 MCP 客户端中使用工具

MCP 服务读取与 REST API 相同的 config.yaml 和数据库。 它们只提供服务，不会建立索引，因此请使用 rootmind index 或运行中的 REST API 保持索引最新。

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "rootmind": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/rootmind/backend", "run", "rootmind-mcp"]
    }
  }
}

如果 Claude Desktop 找不到 uv，请将 uv 可执行文件的绝对路径填入 command。在 Windows 上，路径请使用正斜杠或 转义反斜杠（C:\\...）。

Claude Code：

claude mcp add --transport stdio rootmind -- \
  uv --directory /absolute/path/to/rootmind/backend run rootmind-mcp

通过 HTTP 连接，适用于无法启动本地进程的 MCP 客户端：

cd backend
uv run rootmind-mcp-http             # http://127.0.0.1:3000/mcp

首次启动时，服务会生成一个令牌并将其保存到 data/api_token.txt（位于 RLM_HOME 下；若未设置，则位于工作目录下）；你也可以设置 MCP_API_TOKEN。服务会打印令牌的来源及其简短指纹，但绝不会打印令牌本身。然后：

claude mcp add --transport http rootmind http://127.0.0.1:3000/mcp \
  --header "Authorization: Bearer <token from data/api_token.txt>"

stdio 服务会在启动时读取文件夹列表，因此添加或移除文件夹后，请重启它（MCP 客户端）。当 config.yaml 更改时，HTTP 服务会重新读取文件夹列表。HTTP 服务绑定到 127.0.0.1 并使用纯 HTTP；若要从另一台机器访问，请将其置于终止 TLS 的代理或隧道后面，切勿暴露纯 HTTP 端口。rootmind-mcp-http --index 还会在该进程中运行后台索引器。仅当没有 REST API 为同一数据库建立索引时才使用它：每个索引进程都会移除其自身配置副本中缺失的文件夹所对应的文档。

4. 运行桌面应用（开发）

# terminal 1: backend, with the Vite dev origin allowed by CORS
cd backend
RLM_DEV=1 uv run rootmind api        # PowerShell: $env:RLM_DEV=1; uv run rootmind api

# terminal 2: desktop
cd desktop
pnpm install
pnpm tauri dev

开发版本不会使用 RootMind 服务，因此应用会要求提供后端地址：请确认是 http://127.0.0.1:8000。更多信息请参阅 desktop/README.md。

自行构建安装程序

在 Windows 上，从仓库根目录运行：

# 1. Backend: PyInstaller onedir build -> backend/dist/rootmind-backend/
cd backend
uv sync --locked --no-dev --group build
uv run --no-sync pyinstaller packaging/rootmind-backend.spec --noconfirm --clean --distpath dist
cd ..

# 2. Copy it to desktop/src-tauri/binaries/rootmind-backend/ and check it
python scripts/prepare_backend.py

# 3. Installer with the release overlay, which adds the backend
cd desktop
pnpm install
pnpm tauri build --config src-tauri/tauri.release.conf.json

安装程序会写入 desktop/src-tauri/target/release/bundle/nsis/。 之后在 backend/ 中运行 uv sync，以恢复开发工具。 如果没有 overlay，pnpm tauri build 会构建不含后端的应用。

仓库结构

backend/
  src/rootmind/
    rlm_engine/engine.py   agent loop
    tools.py               tool registry, argument validation, result formatting
    mcp_stdio.py           MCP server over stdio
    mcp_http.py            MCP server over HTTP with a bearer token
    api/                   REST API (FastAPI)
    auth.py, access.py     REST token handling; folder access policy interface
    winaccess.py           folder access policy of the Windows service (AuthZ)
    service/               background service: install, uninstall, status, service host;
                           Windows services and Linux systemd user units (linux*.py, systemd.py)
    database/              SQLite models, FTS5 and trigram search
    indexer/               parsers, indexer, sync scheduler
    connectors/            local folder connector
  tests/                   offline test suite with fake LLM clients; e2e/ service test
  evals/                   fictional corpus and eval cases
  scripts/                 eval runner and corpus generator
  packaging/               PyInstaller spec, smoke test, tree hash
  deploy/windows/          run-backend.bat: the REST API from source in a console window
desktop/
  src/                     React + TypeScript UI
  src-tauri/               Rust shell: service connection and commands, chat history;
                           installer/ with the NSIS template and the service hooks;
                           linux/ and tauri.linux.conf.json for the Linux service and packages
  scripts/                 installer smoke test
packaging/winget/          winget manifest templates
packaging/mcpb/            Claude Desktop bundle (rootmind.mcpb): stdio-to-HTTP bridge, manifest, tests
scripts/                   version check, release notes, backend preparation, winget rendering,
                           NSIS template refresh
.github/workflows/         CI and release

设计决策、护栏和权衡请参阅 ARCHITECTURE.md，威胁模型请参阅 SECURITY.md， 各版本的变更请参阅 CHANGELOG.md。

测试与评估

两者均可离线运行，无需 API 密钥：

cd backend
uv sync
uv run pytest -q                      # fake LLM clients, generated test corpus
uv run python scripts/run_evals.py    # retrieval regression: scripted policy, no model

测试。 自动使用的 fixture 会将 Anthropic 和 OpenAI 客户端构造函数替换为会抛出异常的函数，并从环境中移除 API 密钥。测试通过引擎的 client 参数注入脚本化的模拟客户端 （tests/fakes.py）。每项测试都会使用各自独立的 RLM_HOME 和工作目录。需要文档的测试会生成一个小型语料库，其中各包含一个 PDF、DOCX、XLSX、PPTX、CSV、Markdown 和文本文件。Windows 文件夹访问策略及服务文件夹权限相关测试仅在 Windows 上运行；Linux 文件模式相关测试仅在 Linux 上运行（使用模拟 systemctl 的 Linux 服务逻辑本身可在所有平台运行）；真实服务的安装则留给 CI 端到端测试。

评估。 scripts/run_evals.py 使用真实索引器为 backend/evals/corpus/ 中的虚构语料库建立索引，并通过真实引擎运行 16 个问题。

• 实时模式是评测：它会针对每个案例多次运行真实模型，并报告通过率（是否引用预期来源、是否包含必需字符串、是否不含禁用字符串）、工具路径差异、工具调用、令牌数、延迟和停止原因。它只从环境变量读取密钥，且不会在 CI 中运行。
• 干运行模式是检索回归测试，而非对 Agent 的评测：脚本化策略会替代模型，使用为每个案例手动编写的查询（数据集中的 dry_search）进行搜索，读取建议的窗口，并根据摘录作答。它会检查索引和工具层是否仍将正确文档排在第一位（hit@1）、排在前五条结果中（hit@5），并引用正确的页面、幻灯片或工作表。对于手动挑选的查询，15 个门控案例达到 1.0 是预期结果；同义词陷阱 c09 是已知未命中项。如果 hit@5 低于 1.0，CI 将失败。这不能说明答案质量。

详情：backend/evals/README.md。

CI。 GitHub Actions 工作流使用固定到提交 SHA 的 Actions，且不使用密钥。只有发布任务可以写入仓库：

工作流	运行内容
backend.yml	ruff 检查和格式检查；检查 backend、desktop 和 Claude Desktop bundle 的版本；在 Ubuntu 和 Windows 上测试发布脚本；在 Ubuntu（Python 3.12 和 3.14）及 Windows（Python 3.12）上运行带覆盖率的 pytest；干运行检索回归测试
backend-exe.yml	在 Windows 和 Ubuntu 22.04 上构建 PyInstaller onedir；对每个可执行文件进行冒烟测试（REST、通过 HTTP 和 stdio 运行的 MCP、对所有文件类型进行索引）并计算其目录树哈希；然后对服务进行端到端测试：在提升权限的 Windows 运行器上测试 Windows 服务（安装、权限、令牌、读取限制、更新和卸载）；在 Ubuntu 上测试运行器账户的 systemd 用户单元（拒绝操作、安装、文件模式、令牌、索引、重启、更新、启用和关闭 MCP、卸载）。拉取请求仅在服务相关代码发生更改时运行服务测试
desktop.yml	ESLint、TypeScript 类型检查、vitest、Vite 构建、Windows 上的 cargo fmt、cargo clippy、cargo check、cargo test；Ubuntu 22.04 上的 cargo clippy 和 cargo test
release.yml	对于版本标签 v*：通过 backend-exe.yml 构建 backend；构建包含该 backend 的逐计算机安装程序，检查其能否原位更新已安装版本而不显示重新安装页面，并在提升权限的运行器上进行冒烟测试：安装、更新、重新安装和卸载带有 Windows 服务的 RootMind，并以 SYSTEM 身份静默安装（仅应用），按应用程序的方式设置服务并以 SYSTEM 身份更新服务；根据架构验证 winget 清单；构建供 Claude Desktop 使用的 rootmind.mcpb，并进行测试、验证和打包；使用 Linux backend 构建 Linux 软件包（.deb、.rpm、AppImage），在运行器上安装 .deb 并启动两个打包后的 backend；然后创建 GitHub Release，包含安装程序、Linux 软件包、bundle、两个 backend 压缩包、SHA256SUMS.txt 和证明。手动运行以及更改打包内容的拉取请求都只进行干运行，不会发布任何内容
mcpb.yml	Claude Desktop bundle：在 Ubuntu 和 Windows 上运行桥接的 node:test 测试，然后使用 mcpb CLI 验证清单并打包 bundle
secrets.yml	使用 detect-secrets 检查所有已跟踪文件，并与经过审计的基线 .secrets.baseline 对照

Dependabot（.github/dependabot.yml）每月为全部四个生态系统提出依赖项更新建议。

简要安全模型

• RootMind 专为个人在自己的计算机上使用而构建。REST API 绑定到 127.0.0.1，拒绝来自其他计算机的连接，拒绝外部的 Host 标头，并且只允许桌面应用发起跨源请求。
• RootMind 服务的 REST API 需要持有者令牌。从源代码运行 rootmind api 时，除非你要求使用令牌，否则不会启用令牌；没有令牌时，任何本地进程都可以调用它。
• 该服务以 LocalSystem 身份运行，但只读取安装账户在没有管理员权限的情况下可以读取的内容。安装和修复需要一次管理员批准。在 Linux 上，它以你自己账户的 systemd 用户服务运行，无需 root；文件权限会确保数据和令牌仅对该账户可见。
• MCP HTTP 服务默认启用；它需要持有者令牌，并绑定到 127.0.0.1。远程访问（ngrok）默认关闭；开启后，任何持有 MCP 令牌的人都可以通过公共地址读取所有已索引文档。
• 索引过程在你的计算机上进行。回答问题时，会将问题、搜索片段和文档摘录发送给你配置的大模型提供商。
• 已索引文档是不可信输入。所有工具均为只读，文档文本会标记为数据，每个问题可使用的工具数量也有限制，但提示词注入问题尚未解决。

完整的威胁模型请参阅 SECURITY.md。

限制

• 桌面应用和 RootMind 服务可在 Windows 和 Linux（x86-64）上运行；目前没有 macOS 版本。后端使用跨平台的 Python；CI 会在 Ubuntu 和 Windows 上运行测试。
• 发布的二进制文件尚未进行代码签名（请参阅安装）。RootMind 尚未加入 winget 仓库；首次提交正在进行中。
• 不支持 OCR：没有文本层的扫描版 PDF 不会产生文本。
• 旧版 .doc 和 .xls 文件会交由 DOCX 和 XLSX 解析器处理，通常无法解析。
• 不支持流式传输：桌面应用会等待完整答案。
• 全文搜索不支持同义词匹配或跨语言匹配（请参阅上方的权衡表）。
• 在 Windows 上，安装需要管理员账户，并且每台计算机上的服务只为一个账户提供服务：安装 RootMind 的账户。在 Linux 上，每个启动 RootMind 的账户都会拥有自己的服务。
• Windows 服务无法为网络驱动器或共享建立索引。
• 在 Linux 上，除非启用了延迟运行（loginctl enable-linger），否则服务只会在你登录时运行。
• 每个数据库只应由一个进程建立索引。MCP 服务默认只提供服务；对于任何共享该数据库的其他 REST API，请设置 RLM_DISABLE_SCHEDULER=1。
• MCP stdio 服务会在启动时读取文件夹列表；更改文件夹后需要重启该服务。
• 增量同步会对每个已配置文件夹中的每个文件进行哈希处理，文件夹非常大时会很慢。

贡献

开发环境设置、检查、约定和发布步骤请参阅 CONTRIBUTING.md。请按照 SECURITY.md 中的说明，私下报告安全问题。

许可证

MIT，版权所有 (c) 2026 Christian Gäking。

打包后的后端和安装程序会捆绑第三方依赖项，这些依赖项各自遵循其许可证。

代码签名政策

目前发布版本尚未进行代码签名；每个版本都会提供校验和及构建来源证明（请参阅验证下载）。 CODE_SIGNING.md 介绍了将要签名的内容、团队角色和隐私政策。