MailFathom

MailFathom

邮件的智慧中枢——可自托管、原生支持 AI，且只属于你。

警告

**MailFathom 正在积极开发中，在 1.0.0 版本发布前，任何两个版本之间都不保证兼容。**此之前的任何版本都可能以破坏兼容性的方式更改 MCP 工具、配置、数据库架构或部署方式，甚至可能导致新版本完全无法使用旧版本的配置或数据。每次升级前请阅读变更日志，并保留一份可供回退的备份。

MailFathom 会将你的 IMAP 账户同步到由你运行的 PostgreSQL 数据库中，为副本建立索引，并通过模型上下文协议将其作为工具提供给 AI Agent。读取操作会从你的副本中获取答案，而不是从邮件服务端读取，也绝不会在服务端将邮件标记为已读。写入操作——标记、撰写草稿、发送——需要为每个账户和每项凭据单独授权，而且默认全部关闭，只有你主动启用后才会生效。

在普通聊天客户端中，只需提问一次，答案就来自本地副本。这些截图中的 *** 是在文件进入公开仓库前手动遮挡的——在你启用 SensitiveContent 之前，MailFathom 不会在内容传给客户端的过程中遮盖任何信息。

安装

推荐首次安装时使用 Docker Compose。 这是唯一会为你配置 PostgreSQL 的方式，并且默认将两个端口都绑定到 loopback，因此在你决定开放访问之前，其他机器都无法连接。

git clone https://github.com/fathomise/MailFathom.git
cd MailFathom
scripts/quick-start-compose.sh

第三行是快速试用的方法，不是运行它的方法：该脚本会询问你的邮箱位于何处、写入配置、启动整个服务栈、提供执行架构步骤的选项、记录你的信息和邮箱，并交给你聊天客户端连接所需的密钥——而它准备的服务仅通过普通 HTTP 为这台机器提供服务，将凭据保存在代码库检出目录下的文件中，也不会备份任何内容。脚本结束时会打印这份清单。

安装 MailFathom才是正式安装方式：它介绍了所有部署方式都需要的内容，并提供 Compose、Podman Quadlet、Kubernetes 或原生 systemd 进程的安装指南。接着，入门指南将带你从已安装的实例开始，完成首次成功的工具调用。如果你想直接从代码库检出内容进行评估，本地 Aspire 编排会自动配置 PostgreSQL 并应用架构——本地开发介绍了这条路径。

从这里开始

你要做什么	从这里开始
决定 MailFathom 是否适合你	先看下文的功能亮点，再看用户指南
安装或运维它	安装 MailFathom，然后阅读入门指南
将 Agent 连接到正在运行的实例	使用工具
在 AI 助手的协助下阅读上述内容	阅读下文的将文档交给你的 Agent
参与贡献	CONTRIBUTING.md

将文档交给你的 Agent

如果 AI 助手正在帮助你安装、配置或使用 MailFathom，请把文档交给它，而不是让它搜索整个网站。只需一行：

Read https://fathomise.github.io/MailFathom/docs/llms.txt and follow it to the pages that answer my question.

该地址是当前版本的导航索引：列出每个已发布页面、页面解答的问题以及对应的源文件链接，这样 Agent 就能获取与你的问题对应的页面，而不是从多个页面中拼凑零散内容。MailFathom 也可以在 Context7 中通过 /fathomise/mailfathom 查找；它镜像的是默认分支，而不是某个版本。

→ 将本指南交给你自己的 Agent

Agent 可用的功能

二十一个工具，构成了全部功能。

读取邮件	list_accounts、list_emails、search_emails — 按词汇相关性排序，配置模型后还会按嵌入相似度排序 — get_email_content 可完整读取最多十封邮件；ask_mail 可根据邮件回答问题，并引用所依据的每封邮件
标记邮件	set_mail_flags 可将邮件标记为已读或未读、加星标，并写入客户端显示为标签的关键字
发送邮件	send_email 发送一封邮件；reply_to_email 和 forward_email 回复或转发你已收到的邮件，并从存储的副本中提取收件人、主题、线程信息、引用内容和附件；get_outgoing_email 和 cancel_outgoing_email 可报告邮件发送结果，并停止尚未发出的邮件
起草邮件	save_draft、update_draft 和 delete_draft 会将邮件写入你自己的“草稿”文件夹，绝不会发送；发送草稿则使用 send_draft
联系人	六个工具，用于管理 MailFathom 自有的联系人簿——存储的是人员，而非地址；联系人簿位于你的数据库中，而不是邮件服务提供商处

以下两项特性适用于所有场景，许多设计也由此而来：

• 读取在本地进行。 读取操作从你的副本中获取信息，绝不会联系邮件服务，因此速度快，服务宕机时也能正常工作，并且不会在远程造成任何更改。每个结果都会说明本地副本的新鲜程度。
• 未经你的要求，不会写入任何内容。 检索操作完全无法设置远程 \Seen 标记。可能更改邮箱内容的，只有你配置的规则（如邮件规则、垃圾邮件处理操作），或明确授予凭据权限的工具。发送操作的限制更严格：所有账户默认关闭发送功能；部署处于只读状态时会直接拒绝发送；此外还受你设置的收件人策略和每个周期的发送上限约束。

调用方等待期间不会执行任何发送操作。每封邮件都会先记录下来，并返回记录标识，然后由即使在崩溃后也能继续运行的投递流程发送。因此，MailFathom 告知你已排队的邮件，都会实际尝试投递；邮件发出前的几秒，是唯一可以撤回的时机。客户端发送的任何内容都无法决定邮件的发件人。

除工具返回的内容外，MailFathom 还会记录它能确认的每封邮件信息：发件人经由谁验证、你是否认识该作者、邮件文本有多像机器生成，以及邮件所属的对话。各工具会回答什么、拒绝什么，以及绝不会重复返回什么，就是本系统的约定。

项目状态

0.8.0 是当前版本。在这个版本中，部署不再只是某个人的邮箱配置文件，而是由数据库中的记录来管理所服务的人员、他们的邮件账户、凭据，以及决定每个人能执行哪些操作的角色。部署运行期间可通过 mfctl 管理这些记录，因此单个部署可以服务多个人、由他们共用一个邮箱，并以多个副本运行。

从 0.7.0 升级需要先备份，再进行全新安装，不能原地升级。 应用架构会丢弃已存储的邮件，之后由同步重新获取；同时，也不会导入 0.7.0 配置中声明的邮箱或凭据：每项都必须通过 mfctl 重新录入。变更日志会说明每项变更会影响哪些接口，以及相应的处理方法。

Nightly 镜像基于 main 构建，并与正式版本一同发布。Nightly 不是正式版本：其架构可能领先于任何已发布的迁移，无法向前或向后升级，并且随着更新版本累积，旧版本会被删除。Nightly 构建的风险说明了全部风险。

发布的构件

构件	发布位置
容器镜像	ghcr.io/fathomise/mailfathom 和 docker.io/fathomise/mailfathom
Helm chart	oci://ghcr.io/fathomise/charts/mailfathom
数据库架构脚本	随每个正式版本一同发布
mfctl，管理命令	随每个正式版本一同发布；每个平台各提供一个独立二进制文件，可通过同目录中的校验和文件验证；Linux 上可使用一条命令完成验证和安装

两个镜像仓库在相同摘要下提供相同的清单列表，因此可从环境已能访问的任一仓库拉取。服务本身没有二进制构件：原生安装需要从代码检出开始。

擅长之处

MailFathom 从第一行代码起就以企业级系统为目标构建，即使目前功能范围仍然有限。以下各项声明均描述了当前代码和部署资源的实际特性。

• **每项操作都需要单独授权，任何授权都不意味着其他授权。**读取邮件、更改标记、撰写草稿和发送邮件是四项独立权限，列出工具时和调用工具时都会分别检查；管理路由也采用同样的检查方式。端点还可以限制可提供的工具类型，因此部署可以允许读取和撰写草稿，同时禁止所有凭据发送邮件。→ 权限
• **默认安全，并明确说明每项安全性弱化。**MCP 端点默认关闭，启用时必须说明是否需要凭据；允许不进行身份验证的配置，但启动时会发出警告，而且这绝不是默认设置。客户端证书和每个客户端的速率限制由端点本身负责，而非代理。IMAP 使用连接时 TLS；如果配置会削弱传输安全性，除非明确声明，否则启动会失败。→ MCP 端点
• **凭据绝不存放在配置中。**包含密钥的设置保存的是一个引用——文件路径、systemd 凭据或环境变量——因此配置文件可以安全地审阅、比较差异和备份：泄露配置文件只会泄露路径，而不会泄露密码。MailFathom 读取的文件绝不会被写回；管理员在运行期间所做的更改会持久化到数据库中，并受其专属权限保护。→ 密钥配置、配置来源
• **处理邮件的代码会将邮件视为个人数据。**内容、元数据、提取的文本和搜索摘录绝不会写入日志，也绝不会包含在错误消息中；每次调用都有上限，因此部署方可以决定单次调用最多提取多少邮件内容。部署是否符合 GDPR，仍取决于运行方式；MailFathom 提供的是一种让这些选择保持开放的架构，并为数据主体工作流设置了明确的衔接点。→ 使用工具
• **快速失败，并说明原因。**启动时会解析所有密钥引用，并在提供任何服务之前验证数据库架构；拒绝启动时会指出导致问题的配置键或待处理迁移。任何环境下，启动期间都绝不会应用迁移。→ 健康检查端点、遥测
• **部署资源经过加固，而非仅供示例。**镜像经过裁剪，不含 shell、包管理器或 HTTP 客户端；它以非特权身份在只读根文件系统上运行，所有功能权限均已移除，也不包含任何可应用迁移的工具。Compose、Quadlet 单元和 Helm chart 默认都采用这种安全配置，且该 chart 符合 Restricted Pod Security Standard。→ 容器镜像、Kubernetes
• **供应链可验证。**多架构镜像基于固定到确切补丁版本的基础镜像构建，发布前会经过扫描，并带有签名的构建来源信息，将摘要与生成该镜像的提交和工作流关联起来。软件包版本在中央统一固定，并提交锁定文件；每个第三方组件都会依据许可政策接受审查，以确保项目可以在商业场景中重新分发。→ 验证、THIRD_PARTY_LICENSES.md
• **专为长期维护而构建。**采用 .NET 10 的整洁架构模块化单体，边界受到强制约束，编译器和分析器诊断均视为错误，每项行为变更都配有测试，设计决策记录为 ADR，而非仅靠记忆保存。→ 解决方案结构、设计决策

文档

此处的所有文档链接都指向**文档网站**，这是便于阅读的版本：同样的页面，带有搜索功能、根据源代码生成的 API 参考，以及版本选择器。网站会打开当前版本；此处的链接地址不指定版本，因此在不同版本中都能继续使用。docs/ 是在代码库中阅读同一批页面的索引。

用户指南	安装、配置、运行和使用 MailFathom
配置参考	所有可由用户设置的选项、默认值，以及更改后是否需要重启
权限	凭据可以执行哪些操作，以及拒绝请求时会显示什么
MCP 工具	工具契约、参数和结果，以及稳定的错误代码
邮件投递	邮件发出前会经过哪些环节，以及有哪些限制
架构	各层的边界、各个项目，以及这样划分的原因

docs/ 中的文档描述的是已经实现的行为。对于计划中的功能，我们会通过问题跟踪，而不会把它写成仿佛已经可用的功能。

存在的意义

邮箱是大多数人拥有的最大档案库，却也是最难使用的档案库。合同、决策、发票、没有结论的邮件往来、再也没人能找到的附件：所有这些都在里面，却只能通过滚动邮件来查找。邮件客户端的设计目标是让你一次查看一封最新邮件。积累了二十年邮件后，这种方式就完全不合适了。

MailFathom 正在构建之中，旨在改变邮件对软件而言的意义：保持本地副本最新，将其编入索引，让整个邮箱都能被查找，而不只是最近的一部分，并将其作为工具提供给 Agent。Agent 通过 MCP 访问邮件；但 MCP 并不是 MailFathom 本身。MailFathom 不依赖任何第三方服务——副本归你所有，数据库归你所有，部署也归你所有；AI 能力则通过你选择并指定的提供方接入，而不是编译进产品。

未来方向

工具是基础，而不是产品。发送是第一个让影响触及此邮箱用户以外之人的能力；Agent 仍无法对邮箱执行的操作是移动、归档和删除。此后的每项能力都会沿用这些能力采用的路径：明确的权限、记录在案的更改，以及由其自身负责管理邮件服务器的专属流程。

我们正在构建 MailFathom 自有客户端，目前处于 Alpha 阶段。 Web 客户端随镜像一起发布，在部署提供服务前处于关闭状态；同一客户端也会随每个版本作为 Linux 和 Windows 桌面应用发布。它供人试用，而非依赖：功能尚不完整，每个版本都会变化，而上方的工具仍是访问邮件的受支持方式。→ 客户端端点、桌面客户端

构想，尚未纳入范围——这些问题都已记录为待讨论事项，每一项都在等待决策，而非等待投入精力。Discussions 是讨论这些问题的地方，Ideas 分类也欢迎你提出想法：加密和签名邮件、扫描已存储附件中的病毒、用于出站 IMAP 和 SMTP 的 OAuth，以及基于技能的作业，其内容是一条由 Agent 对你邮件中的一部分执行的指令，而不是一条确定性规则。

贡献

欢迎贡献，起点是 CONTRIBUTING.md：它将引导你从克隆仓库到通过验证，并说明拉取请求必须满足的几条规则。每项更改都从一个 issue 开始，因此请先创建一个 issue——或在现有 issue 下评论——再编写代码；如果更改不只是修正错别字，请等候回复。

MailFathom 采用 AI 优先、近乎零接触的开发方式。 这里几乎每一行代码都由自主编码 Agent 根据 issue 和 AGENTS.md 中的规则编写，并在合并前经过审查。我们鼓励你以同样的方式参与，而不只是容许这种做法；手写的补丁也会得到同等评估。无论采用哪种方式，你都必须在提交前阅读自己的差异内容，并遵守相同的检查要求和许可义务。

Fork 此仓库，克隆你的 fork，并将它指向此仓库——所有验证关卡都会以实际将要合并到的基准分支为参照，检查你的分支：

git clone https://github.com/<you>/MailFathom.git
cd MailFathom
git remote add upstream https://github.com/fathomise/MailFathom.git
git fetch upstream main

如果你使用编码 Agent，请将剩余步骤交给 get-started-contributors，这是专为初次参与者编写的工作流技能；在 Claude Code 中，它的命令是 /get-started-contributors，你也可以将该文件提供给其他 Agent。手动设置的步骤相同，详见从克隆仓库到验证通过。开发在 Linux 上进行；我们尚未在其他环境中验证。

Discussions 中的 Q&A 分类用于提问，Ideas 分类用于提案。缺陷或范围相关事项应提交到 issues——安全漏洞除外，请通过下方的私密渠道报告。CODE_OF_CONDUCT.md 适用于所有参与者。

安全

MailFathom 保存邮箱凭据、OAuth 令牌、证书材料，以及某人的邮件本地副本。请通过 SECURITY.md 私下报告漏洞，而不是在公开问题中披露。

隐私政策。 除非用户或安装或运营 MailFathom 的人员明确提出请求，否则 MailFathom 不会向其他联网系统传输任何信息。它只会访问邮件服务器、数据库，以及部署配置的模型提供商，不会访问其他任何系统：它不收集遥测数据、不向外发送信号，也只会将 OpenTelemetry 数据导出到运营人员设置的端点。邮件存储在哪里、谁能访问，以及由哪个模型接收结果，均由部署决定。

验证下载内容。 在任何平台上，mfctl 二进制文件都没有代码签名，因此 Windows 会警告发布者身份未知。随文件附带的校验和文件可用于判断下载内容是否为正版、是否遭到篡改：

sha256sum --check --ignore-missing 'mfctl-<version>.sha256'

容器镜像和 Helm chart 则各自附带签名的构建来源证明，因此无需信任注册表，使用 gh attestation verify 即可查明它们的来源。容器镜像中记录了如何进行验证。

许可证

MailFathom 采用 GNU Affero 通用公共许可证第 3 版授权，SPDX 标识符为 AGPL-3.0-only。源文件的头部会重复注明该授权，且构建过程会强制执行；发布的制品会将 LICENSE 和 NOTICE 与二进制文件一同附上。该标识符使用的是 -only 版本：此版本仅依据许可证第 3 版发布，不依据自由软件基金会尚未撰写的任何后续版本发布。

MailFathom 最初由 Krzysztof Kasprowicz 创建。根目录中的 NOTICE 记录了这一署名；根据许可证第 7(b) 条，分发方可以要求保留该署名。该声明不会增加任何使用限制，也不声称其他版权持有者撰写的贡献归其所有。贡献者只需接受一次贡献者许可协议，该协议便会将其贡献置于此许可证之下——AGPL 本身并没有这样的条款，而 Apache-2.0 的第 5 条有。它是许可协议，而非版权转让——贡献者保留其所写内容的版权——此外还带来两点：未来在无需追溯每位过往贡献者的情况下，按其他条款发布 MailFathom 的自由，以及贡献者本人声明代码由其提供。由 Apache-2.0 转为 AGPL-3.0-only 时，正是基于这项自由；这不会改变此版本授予你的任何权利。

MailFathom 使用的第三方组件会在 THIRD_PARTY_LICENSES.md 中单独审查。该清单记录了 MailFathom 依赖的组件及其适用条款；它不会授予你对 MailFathom 本身的任何权利，只有 LICENSE 才会。位于 assets/ 中的应用图标是 MailFathom 自有的资源，同样适用此授权。

如果你运行 MailFathom，许可证对你的要求。 你自己或你的组织运行未经修改的已发布版本，无须履行本仓库已发布内容之外的其他义务：源代码就在这里，制品也指向该代码。第 13 条是 AGPL 与 GPL 的不同之处；当你修改 MailFathom，并通过网络让其他人使用修改后的版本时（例如通过其 MCP 接口、客户端端点或任何其他监听器），该条款便适用。此时，你必须向这些用户提供他们实际使用的版本对应的源代码。通常的做法是发布你的分支，并在用户访问该服务的入口处提供链接。仅为自己修改并运行，不会触发任何义务；运行未经修改的部署也不会，无论有多少人使用。

许可证授予的权利，并不包含软件能够正常工作的承诺。第 15 条和第 16 条规定，MailFathom 按原样提供，不附带任何形式的保证或条件；并声明，任何版权持有者均不对因使用软件或无法使用软件而产生的损害承担责任——无论是同步延迟、搜索遗漏了原本存在的内容，还是部署本应不可访问却可被访问而导致邮件泄露。适用的是许可证正文，而非本摘要：在将 MailFathom 连接到重要邮箱之前，请阅读第 13、15 和 16 条。