为 AI Agent 配置邮件全文搜索索引

最近给家人的 AI Agent 搭建了一套邮件全文搜索系统。背景是这样的：她的工作邮件量很大（月均 500+ 封），之前用 offlineimap 同步到本地后，搜索只能靠 grep 原始邮件文件，效率极低，Agent 经常在搜索时超时卡死。

问题分析

原方案用的是 Python 脚本直接遍历 Maildir 文件夹，逐个解析邮件文件。问题是：

邮件文件是 quoted-printable/Base64 编码，直接 grep 容易漏匹配
搜索只能匹配 Subject 和 From，无法搜正文内容
没有增量更新机制，每次都要全量扫描

技术选型

考虑过几种方案：

向量数据库：语义搜索能力强，但对关键词精确匹配（客户名、订单号）反而不如传统方案，且引入额外依赖
Elasticsearch：功能强大，但对家庭服务器来说太重了
SQLite + FTS5：零依赖、性能好、支持全文搜索，完美匹配需求

最终选择了 SQLite FTS5，理由：

系统自带 SQLite，无需额外安装
FTS5 支持中文分词（unicode61）
查询速度毫秒级
可以覆盖 subject、from、to、body 等多个字段

实现方案

1. 数据库设计

sql 复制代码

-- 主表：存储邮件元数据
CREATE TABLE emails (
    id INTEGER PRIMARY KEY,
    file_path TEXT UNIQUE,
    folder TEXT,
    folder_cn TEXT,
    subject TEXT,
    from_name TEXT,
    from_addr TEXT,
    to_addrs TEXT,
    date TEXT,
    body TEXT,           -- 完整正文（去 HTML 标签）
    preview TEXT,        -- 正文摘要
    is_read INTEGER
);

-- FTS5 全文索引
CREATE VIRTUAL TABLE emails_fts USING fts5(
    subject,
    from_name,
    from_addr,
    to_addrs,
    body,
    folder_cn,
    content='emails',
    content_rowid='id',
    tokenize='unicode61'
);

2. 增量更新机制

邮件同步脚本（offlineimap）完成后，自动调用 email_index.py update：

遍历所有邮件文件
计算文件 MD5 判断是否已索引
只处理新邮件或内容变化的邮件
批量提交数据库（每 200 封一批）

3. 搜索接口

支持多维度筛选：

bash 复制代码

# 全文搜索
python3 email_index.py search "sample"

# 按收件人筛选
python3 email_index.py search "price" --to ruth@woolovers.com

# 按时间筛选
python3 email_index.py search "order" --after 2026-01-01

# 按文件夹筛选
python3 email_index.py search "" --folder 订单

踩坑记录

1. IMAP UTF-7 编码

IMAP 协议规定文件夹名用 modified UTF-7 编码，中文文件夹名会变成 &bNVW,Q- 这种乱码。解决方案是在索引时维护一个映射表：

python 复制代码

FOLDER_MAP = {
    "&bNVW,Q-": "报修",
    "&bNVW,Y0nTuM-": "报价",
    # ...
}

2. HTML 邮件正文提取

大部分邮件是 HTML 格式，需要去标签提取纯文本。用正则简单处理：

python 复制代码

body = re.sub(r"<[^>]+>", " ", html)
body = re.sub(r"&nbsp;", " ", body)
body = re.sub(r"\s+", " ", body).strip()

3. FTS5 搜索语法

FTS5 的 unicode61 分词器对中文支持不错，但有些细节：

撇号 ' 会被自动移除（won't → 搜 wont）
连字符 - 自动加引号（WO-2880 正常搜索）
英文搜索效果最好，中文可以用单字或关键词

效果对比

场景	优化前	优化后
搜索某客户邮件	30s+（grep 遍历）	<100ms
搜正文内容	不支持	支持
增量更新	全量扫描	只处理新邮件

现在 Agent 搜索邮件基本是秒出结果，再也不用担心超时卡死了。

总结

SQLite FTS5 是一个被低估的神器，特别适合这种本地全文搜索场景。零依赖、高性能、支持中文，比引入 Elasticsearch 轻量太多。如果你也有类似的邮件搜索需求，不妨试试这个方案。

站长按：这是给家人搭的 AI Agent 系统的一部分，后面还会分享更多优化经验。