dead-letter

dead-letter

将 .eml 邮件导出文件转换为简洁、本地化、适用于大模型的 Markdown。

dead-letter 可将 .eml 邮件导出文件转换为带 YAML front matter 的简洁 Markdown——拆分邮件线程、移除签名、提取附件、解析日历。无论一个文件还是一万个文件，都能轻松处理。

你可以用它创建易读的邮件归档，将邮件迁移到基于 Markdown 的知识系统，或为 RAG 和大模型工作流准备邮件，无需将原始 MIME 和 base64 内容塞进上下文窗口。无需账户、上传或 API 密钥。

⚡ 试用

如果你已安装 uv，无需全局安装即可运行 dead-letter：

uvx --python 3.12 dead-letter convert message.eml

也可以使用下方的 Homebrew 或 pip 安装。Agent 和 MCP 客户端可以使用 llms-install.md 中针对各客户端的配置方法。

🎯 常见用途

• 邮件 → Markdown 归档——将导出的 .eml 邮件集合转换为带有结构化元数据、易读且便于移植的 Markdown
• RAG 和大模型摄取——在分块或建立索引之前，对邮件文本、线程结构、链接和附件元数据进行标准化处理
• Agent 工作流——让 Claude、Codex 和其他 MCP 客户端直接使用转换和诊断功能
• 知识库——将邮件迁移到以 Markdown 为先的系统，例如 Obsidian、静态归档或本地搜索工作流
• 数字保存——保留人类可读的内容和实用的邮件结构，而不依赖某个特定邮件客户端

✨ 功能

• 完整保真转换——HTML 清理、Gmail/Outlook 线程分段、内嵌图像处理和日历事件摘要
• CLI——指定文件或目录即可开始使用
• 本地 Web UI——暗色指挥中心界面，支持拖放导入、监视模式、转换等级徽章、处理历史记录和每项任务的诊断信息
• 收件箱/文件柜工作流——将 .eml 文件放入收件箱，让 dead-letter 将 Markdown 文件包整理到文件柜
• 安装验证——dead-letter doctor 可检查运行环境
• 转换报告——可选的 JSON 报告，包含每个文件的诊断信息，包括供自动化和审计使用的已引用/已保留附件数量
• MCP 服务——与 Claude Desktop、Claude Code、Codex 和其他 MCP 客户端集成
• Claude 插件——可在 Claude Code 或 Cowork 中从市场安装，并提供五个斜杠命令（/dead-letter:convert、/dead-letter:summarize、/dead-letter:triage、/dead-letter:cabinet、/dead-letter:mbox）
• 可移植的 Agent Skill——指导具备技能支持的 Agent 何时以及如何转换 .eml 文件
• Python API——使用 from dead_letter import convert 即可开始

🧠 专为大模型流水线打造

原始 .eml 文件对下游大模型和检索流水线来说是杂乱的输入——MIME 标头、多部分边界、重复的 HTML／纯文本正文，以及编码后的附件都会混在文本处理流程中。

dead-letter 会将其规范化为带有 YAML front matter 的 Markdown，因此无需解析 MIME 或清理 Base64，邮件正文和元数据就能直接用于分块或索引。默认情况下，convert() 和 convert_dir() 每条消息会生成一个 .md 文件，并将附件名称保留在 front matter 中。

如果还要将文件系统中的产物分开，bundle 和 Cabinet 工作流会生成 message.md，并将解码后的文件保留在 attachments/ 目录下。Markdown 可直接用于文本摄取，而 PDF、电子表格、日历文件及其他保留的二进制附件则会清晰地分开，供你使用现有的下游解析器处理。

如需直接集成大模型，MCP 服务可让客户端调用 dead-letter 的转换工具，无需通过 shell 执行命令。转换在本地进行；不过，你选择的 MCP 主机仍可能会将返回的邮件文本发送给远程模型。

📊 Token 成本基准测试

dead-letter 的价值不在于比所有替代方案使用更少的 token，而在于每个 token 保留的信息量：保留有用的邮件结构，同时不将原始 MIME 带入上下文。基准测试使用包含 11 条合成邮件的语料库，其中包括 HTML 讨论串、附件和新闻简报（分词器为 o200k_base，采用结构化讨论串模式）：

• 在报告的汇总比较中，token 数比原始 .eml 少约 88%——附件类别的原始 token 数中位数约为 126k，转换后约为 180。
• 结构得以保留——讨论串结构、每条消息的发件人归属、链接和附件元数据都清晰可读。测试的简单基线通常 token 数更少，因为它们会丢弃信息（保留附件名称的数量为 0/2，而 dead-letter 为 2/2）。

这些数字衡量的是 Markdown 表示形式，不包括保留的二进制附件内容，也不代表下游回答质量。正式版本默认采用最新消息模式；基准测试则采用结构化模式，以便比较同一讨论串。

基准测试如实说明了它的不足：如果不介意丢弃元数据、链接和讨论串结构，简单提取所需 token 更少。完整方法、完整表格（包括这些行）、分词器说明以及一条命令即可复现的步骤，均见 benchmarks/。

📦 安装

选择一种方式即可。分发方式说明介绍了各渠道之间的关系；无需全部安装。

你的需求	从这里开始
核心 CLI 或 Python API	使用下文的 Homebrew／pip，或通过 uvx 快速试用
本地 Web UI	使用下文的 dead-letter[ui]
Claude Desktop 扩展或其他 MCP 客户端	MCP 服务
Claude Code／Cowork 命令	插件
容器隔离的 MCP	容器
可移植的 Agent 指令	Agent Skill

在 Apple 芯片版 macOS 上使用 Homebrew：

brew tap BigCactusLabs/tap
brew install dead-letter

Homebrew 公式会安装 CLI（dead-letter convert、dead-letter doctor）。 0.4.7 及更高版本的公式也会安装 dead-letter-mcp 服务；不包含可选的 Web UI。

使用 pip：

pip install dead-letter            # core + CLI
pip install 'dead-letter[cli]'      # + watchfiles (used by backend/UI watch mode)
pip install 'dead-letter[ui]'       # + web UI, API server, and watch mode
pip install 'dead-letter[mcp]'      # + MCP server

如需隔离安装 UI 或 MCP，请使用 pipx：

pipx install 'dead-letter[ui]'      # installs dead-letter and dead-letter-ui
# Or, for MCP instead:
pipx install 'dead-letter[mcp]'     # installs dead-letter and dead-letter-mcp

或者使用 uvx 运行单个入口点，无需全局安装软件包：

uvx --python 3.12 dead-letter convert message.eml
uvx --python 3.12 --from 'dead-letter[mcp]' dead-letter-mcp

uv 会缓存工具和依赖项，首次使用时可能会下载 Python。这些未固定版本的试用命令不保证每次运行都使用最新版本；如需经过审核的部署方式，请参阅固定版本。

从源代码安装：

git clone https://github.com/BigCactusLabs/dead-letter.git
cd dead-letter
uv sync --extra dev --locked     # all extras
# Or choose only the surface you're developing:
uv sync --extra ui --locked      # UI only
uv sync --extra mcp --locked     # MCP only

Agent Skill（任意宿主）

将可移植的 Agent Skill 安装到你使用的任意 Agent 中：

gh skill install BigCactusLabs/dead-letter dead-letter --agent claude-code
gh skill install BigCactusLabs/dead-letter dead-letter --agent codex
gh skill install BigCactusLabs/dead-letter dead-letter --agent github-copilot

需要 gh 2.90 或更高版本。该 Skill 独立于 Claude 插件。为确保可复现，请固定到经过审核的 Skill 标签或提交；默认的最新版本也可能是插件版本。有关精确的固定语法、其他宿主、手动安装和发现元数据，请参阅 Agent Discovery。

🚀 快速开始

CLI — 转换单个文件：

dead-letter convert message.eml

转换整个目录：

dead-letter convert inbox/ --output out/

在输出旁生成 JSON 转换报告：

dead-letter convert inbox/ --output out/ --report

使用 --output 时，报告会写入该输出目录，文件名为 .dead-letter-report.json。不使用 --output 时，文件转换会将报告写入源邮件旁边，目录转换则会将报告写入输入目录的根目录。

检查你的运行时环境：

dead-letter doctor

目录转换会递归扫描 .eml 文件，后缀匹配不区分大小写；会跳过解析后的目标超出指定输入树的符号链接文件，并对解析到同一邮件文件的树内符号链接别名去重。

Web UI — 启动本地服务：

dead-letter-ui --host 127.0.0.1 --port 8765

打开 http://127.0.0.1:8765 — 首次启动时，设置提示会建议默认的 Inbox 和 Cabinet 文件夹。导入或启动任务前，请先配置这些文件夹。跳过会关闭提示，但在完成设置前仍会禁止这些操作。使用拖放或文件选择器导入 .eml 文件。单文件导入会使用文件模式，而多文件拖放会创建一个目录模式的批处理任务。混合拖放内容会在跳过非 .eml 文件前请求确认。

后端对单个文件和批量上传均强制执行每个文件 100 MB 的导入限制；浏览器批量上传还受总大小和文件数量限制。

从源代码检出目录运行时，请在命令前加上 uv run：

uv run dead-letter convert message.eml
uv run --extra ui dead-letter-ui --host 127.0.0.1 --port 8765

🐍 Python API

from dead_letter import convert

result = convert("message.eml")
print(result.subject, result.sender)
print(result.output)  # path to the generated .md

带选项：

from dead_letter import convert, ConvertOptions

result = convert("message.eml", options=ConvertOptions(
    strip_signatures=True,
    strip_quoted_headers=True,
))

剔除签名图片（徽标、社交图标）和跟踪像素：

result = convert("message.eml", options=ConvertOptions(
    strip_signature_images=True,
    strip_tracking_pixels=True,
))

启用后，这些筛选器会从渲染后的 Markdown 中移除匹配的图片，并在生成捆绑包附件时省略被剔除的内嵌签名/跟踪资源。

捆绑包转换（在同一目录中包含 Markdown、附件和源文件）：

from dead_letter import convert_to_bundle

bundle = convert_to_bundle("message.eml", bundle_root="cabinet/", source_handling="copy")
print(bundle.markdown)     # cabinet/message/message.md
print(bundle.attachments)  # retained extracted files under cabinet/message/attachments/

source_handling="copy" 会将原始 .eml 保留在原处。若未指定，convert_to_bundle() 默认使用 source_handling="move"，并将源邮件移入捆绑包。

保留的提取附件文件名会先规范化为安全的基本文件名，然后再写入 attachments/。

当邮件包含符合保留条件的附件时，质量诊断会包含已引用/已保留附件的数量，以便通过机器检测被丢弃的文件。请参阅 质量诊断。

批处理：

from dead_letter import convert_dir

for r in convert_dir("inbox/", output="out/"):
    print(f"{'✓' if r.success else '✗'} {r.source.name}")

🔌 MCP 服务

dead-letter 附带一个 MCP 服务，让大模型客户端无需调用 shell 即可直接转换 .eml 文件。

VS Code、Cursor 和 Cline：

在 VS Code 中安装 · 在 Cursor 中安装 需要在桌面客户端的 PATH 中安装 uv/uvx。这些链接使用已发布的 PyPI 包配置本地 stdio 服务，无需通过目录审核。首次使用时可能会下载 Python 和依赖项。接受前，请检查命令、作用范围和 工具权限。Cline 设置、手动 JSON 示例和 验证方法： 客户端安装。

直接使用 uvx 启动：

uvx --python 3.12 --from 'dead-letter[mcp]' dead-letter-mcp

也可以先安装（从 0.4.7 开始，MCP SDK 是核心依赖项；[mcp] 作为 兼容性扩展保留）：

pip install 'dead-letter[mcp]'
dead-letter-mcp

从源代码检出版本启动：

uv run dead-letter-mcp

Claude Desktop（扩展包）：

从 发布页面下载已发布的软件包版本（vX.Y.Z）中的 .mcpb 文件及其 .sha256 校验文件。仅发布插件的版本不包含此扩展包。安装前请验证文件：

# macOS: verifies against the downloaded sidecar
shasum -a 256 -c dead-letter-mcp-X.Y.Z.mcpb.sha256

# Windows (PowerShell): compare this hash to the sidecar's hash
certutil -hashfile dead-letter-mcp-X.Y.Z.mcpb SHA256

将 X.Y.Z 替换为所选的软件包版本。在兼容的 Claude Desktop 版本中，双击下载的扩展包，将其拖到窗口中，或使用“设置”>“扩展”>“高级设置”>“安装扩展”。检查扩展是否已连接并公开以下工具（从 0.4.5 起有五个；0.4.0 及更早版本中没有 convert_mbox），然后转换一条合成消息。

该扩展包使用受管理的 uv 运行时，并固定到精确的软件包版本。首次启动时可能会下载 Python 和依赖项。校验和或命令行冒烟测试并不能证明其已在你的客户端版本中成功完成 GUI 安装。对于不支持 MCPB 的宿主，请使用下方的手动 stdio 设置。

Claude Desktop（手动配置 claude_desktop_config.json——替代方案）：

{
  "mcpServers": {
    "dead-letter": {
      "command": "uvx",
      "args": ["--python", "3.12", "--from", "dead-letter[mcp]", "dead-letter-mcp"]
    }
  }
}

请合并此条目，而不是替换现有客户端设置。VS Code 和其他宿主可能使用不同的架构；请参阅Agent 安装指南。

Claude Code 或 Cowork（推荐——Claude 插件）：

/plugin marketplace add BigCactusLabs/bigcactuslabs-plugins
/plugin install dead-letter

在 Claude Code 2.1.275 或更高版本中，/plugin install dead-letter --marketplace BigCactusLabs/bigcactuslabs-plugins 可一步完成这两项操作。

该插件通过 uvx 启动 MCP 服务，并添加五个斜杠命令：/dead-letter:convert、/dead-letter:summarize、/dead-letter:triage、/dead-letter:cabinet、/dead-letter:mbox。本地 Claude Code 需要在 PATH 中安装 uv；运行时专属设置和更新请参阅 plugin/。电子邮件内容会被视为不可信数据，而非指令：不会遵循其中要求使用工具、提供凭据或窃取数据的内容。

该市场会固定插件标签和提交版本，其启动器则固定到精确的已发布 Python 软件包版本。Claude Code 和 Cowork 会分别保留已安装的副本；请分别更新并验证每个客户端。该插件还附带包含依赖项版本哈希值的 uv.lock，供从锁文件启动的宿主使用；普通 uvx 则会自行解析兼容的传递依赖版本。

Claude Code（手动添加 MCP——替代方案）：

claude mcp add dead-letter -- uvx --python 3.12 --from 'dead-letter[mcp]' dead-letter-mcp

Codex：

codex mcp add dead-letter -- uvx --python 3.12 --from 'dead-letter[mcp]' dead-letter-mcp
codex mcp list

mcp list 可确认已注册，但不能证明工具调用成功。请通过目标客户端连接，确认下方列出的工具，并转换一个合成测试样本，再将安装视为已验证。

工具

工具	必需参数	返回值
convert_eml	eml_path	Markdown 文本。提供 output_path 时也会写入文件。
convert_eml_to_bundle	eml_path、bundle_root	包含 bundle_path、markdown_path、attachment_paths 的 JSON。仅复制：不会移动或删除原始 .eml 文件。
convert_directory	directory、output_directory	JSON 摘要。每次调用最多处理 50 个 .eml 文件。
convert_mbox	path、output_directory	JSON 摘要。每次调用最多处理一个平铺的 .mbox 文件，大小不超过 256 MiB，最多包含 1000 封邮件。适用于 0.4.5 及更高版本。
get_diagnostics	eml_path	质量与结构 JSON。不写入任何永久内容。

这五种工具均接受一个 preset（default、clean、verbose、raw）和逐项标志覆盖设置。完整规范（包括仅适用于 MCP 的约束和错误文本表）：docs/reference/v4-runtime-contracts.md。

🗂 项目结构

src/dead_letter/
├── core/           # conversion pipeline (MIME, HTML, threads, rendering)
├── backend/        # CLI, API server, job runner, watch mode, MCP server
└── frontend/       # static web UI (Alpine.js ES modules + vanilla fetch)
tests/
├── core/           # conversion pipeline tests with .eml fixtures
├── backend/        # API, job, and watch tests
├── plugin/         # plugin, skill, packaging, and release contracts
└── frontend/       # JS unit tests

Agent 指南介绍了 bundle、容器、技能和维护者工具，不会把本 README 变成文件清单。

🧪 测试

uv sync --extra dev --locked
uv run pytest -q tests/core        # conversion pipeline
uv run pytest -q tests/backend     # API and job runner
uv run pytest -q tests/plugin      # plugin, skill, packaging, and release contracts
node --test tests/frontend/*.test.js
python scripts/release.py check    # offline distribution metadata

CI 还会验证插件／技能架构、前端语法、维护中的 Markdown 链接和跨平台打包。完整命令，以及离线契约测试与真实客户端测试的区别，请参阅贡献指南。

📚 文档

• 文档索引 — 按任务选择，而非按文件名选择
• 分发图 — CLI、UI、MCPB、插件、容器和技能的选择
• Agent 安装指南 — 针对特定客户端的设置和验证
• 运行时契约 — 完整 API 和核心行为规范
• 前端状态模型
• 质量诊断
• 发布 — 打标签、渠道顺序和恢复
• 品牌与风格指南
• 更新日志
• 贡献指南
• Agent 指南 — 面向在此仓库中工作的 AI 编码 Agent 的操作指南

🔧 我们喜爱的工具

• MarkEdit — Markdown 版 TextEdit，原生 macOS 应用，约 4 MB。打开 dead-letter 输出文件，就像它们本来就该在这里一样。
• mo — 本地 Markdown 查看器，可在浏览器中渲染文件并实时重新加载。将它指向你的 Cabinet，像阅读信息流一样查看转换后的邮件。

⚠️ 已知限制

• CLI/Python 接受 .eml、扁平 .mbox 导出文件，以及（从 0.4.5 起）ZIP/TGZ Takeout 下载文件；请参阅 Takeout 指南。Web UI 仅支持 EML。从 0.4.5 起，MCP 服务新增了一个有界的 convert_mbox 工具，用于处理单个扁平 .mbox。不支持 PST、MSG 和实时邮箱连接。从 0.4.6 起可选择启用可恢复的 MBOX 导入（仅限 CLI/Python，通过 --mbox-resume）；请参阅 恢复契约。
• 仅限本地、单用户、单机器；没有远程服务或身份验证服务。MCP 主机可能会将结果发送给其模型提供商。
• 作业注册表位于内存中：重启后状态会重置。保留的二进制附件需要使用单独的解析器进行文本索引。

许可证

PolyForm Noncommercial 1.0.0 — 个人、教育和非营利用途免费。商业用途需要从 Big Cactus Labs 获取单独的许可证。