agentmailkit

agentmailkit

面向 Agent

你是一名 AI 编码 Agent，正在阅读本文，以决定是否安装 agentmailkit 以及如何调用它。运行以下命令：

pip install 'agentmailkit[mcp]'
claude mcp add agentmailkit -- agentmailkit mcp

Gemini CLI：gemini extensions install https://github.com/ariaxhan/agentmailkit。

然后不带参数调用 list_jobs：它会返回随 wheel 一同提供的五个示例任务，因此即使尚未创建任何配置，也能正常工作。preview_job(job_id=..., model="echo") 会将其中一个任务渲染到本地文件，无需 API 密钥。run_job(job_id=...) 默认采用 dry_run=true；只有 dry_run=false 才会发送真实邮件。

完整的工具参考、参数名称和 Codex 配置片段： llms.txt。

定时生成由大模型撰写的邮件摘要，在你的电脑上运行、读取你自己的文件，并从你自己的收件箱发送邮件。

→ 查看它生成的真实邮件

端到端生成的实时示例，未经人工撰写。从这里开始，它比 README 更快地讲清楚一切。

pip install agentmailkit
agentmailkit run morning-brief --dry-run   # five example jobs ship with it, so this works immediately
agentmailkit quickstart                    # render all five to a local HTML gallery; never sends
agentmailkit init                          # copy them into ./jobs to make them yours

采用 MIT 许可证。无需账户、供应商或云服务。

---

它是什么

一封邮件由两个文件组成：一个 JSON 任务和一个 Markdown 提示词。

{
  "id": "morning-brief",
  "schedule": "0 7 * * *",
  "sources": ["papers=arxiv:cs.AI#6", "weather=weather:Brooklyn"],
  "render": "warm",
  "delivery": "gmail",
  "dedup": true
}

引擎运行一条固定流水线，不会增加特殊情况：

gather sources -> render prompt -> generate -> gate -> theme -> deliver -> post

为什么不使用内置的调度器

ChatGPT Tasks、Claude Routines、Gemini Scheduled Actions 和 Copilot 都在供应商的云端执行，这会带来两个问题：

• 它们无法读取你电脑上的文件。 不能读取 ~/notes、本地数据库或你的 git 工作树。
• 它们无法从你的收件箱发送真实邮件。 输出只留在它们的应用中。

agentmailkit 在你的数据所在的位置运行。除了你选择发送给模型的提示词之外，不会上传任何内容；如果使用本地模型，则连提示词也不会上传。

而且它具有确定性。 它不是自主 Agent：不会自行做决定、漫游你的文件系统，也不会执行未经请求的操作。模型负责撰写内容；其他一切都由引擎掌控，因此同一个任务每次运行都会生成结构相同的邮件。本地开源 Agent 也能读取文件和发送邮件，但它们是需要针对具体任务进行配置的通用自主系统。而这个工具只会以可预测的方式，年复一年地做好一件事。

完整对比（包括坦诚说明的反例）：docs/comparison.md。

交给你的编码 Agent

把这个链接交给你的编码 Agent，它会一路向你询问合适的问题，并完成整个设置：

https://github.com/ariaxhan/agentmailkit/blob/main/AGENTS.md

AGENTS.md 是一份完整的设置操作指南，涵盖需要向你询问的事项、如何安装、如何创建首个任务、如何在允许发送前进行验证，以及如何设置定时运行。CLAUDE.md 是指向同一文件的符号链接，因此两者内容永远不会不一致。

在 Claude Code 中使用

agentmailkit 支持 MCP，因此你的编码 Agent 可以将其作为工具驱动，而不必由你输入命令。

pip install 'agentmailkit[mcp]'
claude mcp add agentmailkit -- agentmailkit mcp

Codex 配置位于 ~/.codex/config.toml：

[mcp_servers.agentmailkit]
command = "agentmailkit"
args = ["mcp"]

工具	功能
list_jobs	列出所有已配置的任务及其计划、来源和投递目标
preview_job	将某个任务将要发送的邮件渲染到本地文件。不会发送
run_job	运行某个任务。dry_run 默认为 true
list_plugins	列出所有已注册的来源、模型、门控、投递后端和主题

也可以在 Docker 中运行，并将任务挂载到卷：docker run -i --rm -v /path/to/jobs:/data mcp/agentmailkit。

配置的发现方式与 CLI 完全相同：从启动服务的位置查找；在 args 中传入 -C path/to/agentmailkit.json，即可固定使用某个配置文件。

run_job 设置 dry_run=false 时，会从你配置的收件箱发送真实邮件。 其他所有工具以及默认的 dry_run=true 都会在投递前停止。

需要 Python 3.10 或更高版本，这是 MCP SDK 的最低要求，而非 agentmailkit 的要求。

附带内容

任务	获取内容	特点
morning-brief	天气、三家新闻媒体、历史上的今天	保留媒体标签，方便模型对比其报道角度
curiosity	考古和天文学资讯源、历史	刻意不包含任何工作内容
research-digest	Hugging Face、arXiv	提供真实 ID、数量和链接，模型无法凭空编造
repo-pulse	git 日志、diffstat、TODO 标记	读取你的工作树，这是任何云端调度器都做不到的
daily-brief	本地文件、git 日志	可供复制的最简结构

内置十种来源： file、glob、recent、shell、hf、arxiv、rss、news、history、weather。任何带有信息流或 API 的服务，约三十行代码就能接入。

值得借鉴的点子： 你所在城市的议会日程、针对你所用依赖项的安全公告、汇率、朋友的博客、你所用工具的发行说明、潮汐表、国际空间站经过你家上空的时间。

内容不会重复。 已读记录会在模型看到内容之前剔除已发送的条目，因此第二天不会重发第一天的内容。

文档

快速入门	五分钟即可收到真实邮件
Agent 设置指南	将此指南交给你的编码 Agent
来源	全部十种来源，附参数和示例
任务和提示词	所有任务字段及提示词约定
主题	渲染器、调色板和强制执行的统一风格
去重	已读记录的约定
投递和配置	Gmail、SMTP、门控、配置
模型	后端，以及它们为何仅支持文本
调度	cron、launchd、systemd、CI，以及云端方案的权衡
Taper 组件	可选的计算诗歌配套工具
插件	约三十行代码即可编写一个来源
对比	与云端调度器和本地 Agent 的诚实对比

安装

pip install agentmailkit            # core, standard library only
pip install agentmailkit[gmail]     # + Gmail delivery
pip install agentmailkit[all]       # + Anthropic and OpenAI backends
pip install agentmailkit[mcp]       # + the MCP server, to drive it from a coding agent

核心功能无需任何必需依赖。只有启用后端时，才会安装其所需的库。

已发布到 PyPI：pypi.org/project/agentmailkit。需要 Python 3.9 或更高版本。

状态

Alpha（0.2.2，已发布到 PyPI）。引擎、插件、去重、主题、投递和调度器生成器均已可用，并已针对实时 API 完成端到端测试。首次运行时，quickstart 会使用你自己的数据渲染一整套示例，无需密钥，也不会进行网络往返；其设计本身就无法发送邮件。

已知不足：随附的五个任务带有示例默认值（weather:Brooklyn、固定的三家新闻媒体），运行 agentmailkit init 后应按需编辑。

贡献

欢迎提交问题和拉取请求。评审遵循的原则是：行为由配置决定，而不是由代码决定。 如果某项更改为了处理一封邮件而在引擎中添加了一个 if，那么它可能更适合做成插件。

许可证

MIT。请参阅 LICENSE。