GhostPaw Email

@ghostpaw/email

Agent 邮件：在进程内使用 IMAP 和 SMTP，通过 SQLite 缓存，并将读取和发送作为独立工具。

npm install @ghostpaw/email

一个基于 SQLite 构建的独立 Node.js 邮件引擎。

它将 IMAP 同步、SMTP 发送、本地缓存、邮件会话、搜索和传输错误整合为一个统一模型，而非一堆协议适配器。它以单个预打包文件的形式发布，运行时零依赖，同时面向三类用户：直接编写代码的人类开发者、通过结构化的 soul / tools / skills 运行时操作的大模型 Agent，以及希望直接使用 email CLI 二进制文件、无需编写任何连接代码的 Agent 操作人员。

MCP 服务

以下每种客户端配置都会启动同一个 stdio 服务：npx -y @ghostpaw/email mcp。缓存的邮件保存在 ~/.ghostpaw/email.db，除非通过环境变量 GHOSTPAW_EMAIL_DB（绝对路径）或 --db <path> 指定其他位置。

Claude Code

claude mcp add ghostpaw-email -- npx -y @ghostpaw/email mcp

也可以作为插件安装，该插件还会安装技能：

/plugin marketplace add GhostPawJS/email
/plugin install ghostpaw-email@ghostpaw-email

邮件 CLI（~/.email/config.toml）

[mcp_servers.ghostpaw-email]
command = "npx"
args = ["-y", "@ghostpaw/email", "mcp"]

Cursor（.cursor/mcp.json）、Claude Desktop（claude_desktop_config.json） 或项目的 .mcp.json：

{
  "mcpServers": {
    "ghostpaw-email": {
      "command": "npx",
      "args": ["-y", "@ghostpaw/email", "mcp"]
    }
  }
}

Claude Desktop 用户也可以从最新的 GitHub 版本安装 server.mcpb。 项目包含用于容器主机的 Dockerfile： docker build -t ghostpaw-email . && docker run -i --rm -v email:/data ghostpaw-email。

服务支持 MCP 2026-07-28（无状态，server/discover）以及基于 initialize 的版本 2025-11-25、2025-06-18、2025-03-26 和 2024-11-05。

网络操作使用现有 CLI 账户配置（email account add），或使用 EMAIL_IMAP_HOST、EMAIL_SMTP_HOST、EMAIL_USER 和 EMAIL_PASS（或 EMAIL_ACCESS_TOKEN）。发现和读取缓存无需账户或凭据。 界面数据库默认位于 ~/.ghostpaw/email.db；将 --db 指向现有账户缓存即可读取。每次网络调用都会打开并关闭 IMAP 会话。连接命令不会在调用之间保留会话。

工具 CLI

npx -y @ghostpaw/email tools
npx -y @ghostpaw/email call mail_read '{"view":"folders"}' --db :memory:
npx -y @ghostpaw/email call mail_search '{"query":"invoice"}'

email 和 ghostpaw-email 都运行相同的 CLI。现有的账户、读取、搜索、撰写、整理和同步命令仍可使用。完整指南保留在 skills/email/references/cli.md 中。

Agent 技能：软件包内附带 SKILL.md 和 skills/email/；运行 npx -y @ghostpaw/email skill 可打印技能内容。

安装

npm install @ghostpaw/email        # as a library
npm install -g @ghostpaw/email     # as a global CLI
npx @ghostpaw/email --help         # one-off, no install needed

需要 Node.js 24+（使用内置的 node:sqlite 模块）。

快速开始

import { Mailbox } from '@ghostpaw/email';

const mailbox = new Mailbox({
  imap: { host: 'imap.example.com', port: 993, tls: true },
  smtp: { host: 'smtp.example.com', port: 465, tls: true },
  auth: { user: '[email protected]', pass: 'secret' },
  storage: 'mail.db',
});

await mailbox.connect();

const folders = mailbox.read.folders();
await mailbox.network.sync();
const messages = mailbox.read.messages('INBOX', { limit: 20 });

await mailbox.write.send({
  to: [{ address: '[email protected]' }],
  subject: 'Hello',
  text: 'Sent from @ghostpaw/email.',
});

await mailbox.disconnect();

connect() 会打开 SQLite 数据库、初始化架构、更新账户，并验证 IMAP 会话——一次调用即可完成所有操作。

模型

七个存储概念和三个派生概念：

概念	用途
Account	一个电子邮件身份及其 IMAP/SMTP 连接配置
Folder	一个 IMAP 邮箱路径，包含同步元数据和角色检测信息
Message	本地缓存的电子邮件标头记录，包含标志、标签和信封信息
Body	一封邮件经过解码的 text/html 内容和原始 RFC 2822 字节
Attachment	经过解码的 MIME 部分，可按需获取二进制数据
SyncLog	每个文件夹一次已完成同步过程的记录
Thread	根据 References/In-Reply-To 标头派生的 JWZ 对话树

该模型让每种邮件状态都有自己的归属：

表面上是什么	实际上是什么
一个电子邮件收件箱	一个包含已同步邮件且 role: 'inbox' 的 Folder
一段对话	根据 References 和 In-Reply-To 链计算得出的 Thread
一封未读邮件	flags 数组中没有 \Seen 的 Message
一封已加星标的邮件	flags 中包含 \Flagged 的 Message
附在邮件上的 PDF	一个包含来自 BODYSTRUCTURE 的元数据、且数据按需获取的 Attachment
“同步发现 12 封新邮件”	一条记录策略、数量和耗时的 SyncLog 行

状态是派生出来的，而非切换设置的。线程 ID 会在同步时根据标头链计算，文件夹角色会根据 IMAP 特殊用途属性检测，附件元数据会从 BODYSTRUCTURE 中提取——这些内容都在同步期间生成，不会作为手动状态字段存储。

两类用户

人类开发者

使用 Mailbox 类及类型化的 read、write 和 network 接口，直接通过代码访问所有邮件操作：

import { Mailbox } from '@ghostpaw/email';

const mailbox = new Mailbox(config);
await mailbox.connect();

const threads = mailbox.read.threads('INBOX', { limit: 20 });
const detail = await mailbox.read.getMessage('INBOX', uid);
await mailbox.write.reply('INBOX', uid, { text: 'Acknowledged.' });
await mailbox.write.archive('INBOX', [uid]);

完整的人类用户指南及示例请参阅 HUMAN.md。

LLM Agent

使用 tools、skills 和 soul 命名空间，获得结构化的运行时接口，以尽量降低 LLM 的认知负担：

import { skills, soul, tools } from '@ghostpaw/email';

// 5 intent-shaped tools covering the full mailbox lifecycle
const allTools = tools.aligned.emailTools;
const readTool = tools.aligned.getEmailToolByName('mail_read');

// 8 reusable workflow skills for multi-step scenarios
const triageSkill = skills.getEmailSkillByName('triage-inbox');

// Thinking foundation for system prompts
const systemPrompt = soul.renderEmailSoulPromptFoundation();

共享 facade 提供 name、description、whenToUse、whenNotToUse、inputSchema、readOnly 和 sideEffects。处理器接收一个上下文，其中包含 read、write 和 network 接口以及现有的工具输入。它们返回 { ok, outcome, summary, next, data }；data.entities 包含邮件或邮箱引用，next 包含后续操作提示。错误会映射为 ok: false。读取操作可能会刷新本地缓存，因此元数据会保守地将所有工具都标记为会写入状态。

const definitions = tools.aligned.listEmailToolDefinitions();
const tool = tools.aligned.getEmailToolByName('mail_read');
if (!tool) throw new Error('mail_read is unavailable');
const result = await tool.handler(
  { read: mailbox.read, write: mailbox.write, network: mailbox.network },
  { view: 'folders' },
);
console.log(result.ok, result.summary);

已弃用的 tools.emailTools 和 tools.getEmailToolByName() 仍然可用，保留原有的 { outcome, summary, entities, nextSteps } 结果和不变的输入。迁移到 tools.aligned 即可使用共享结构。

完整的 AI 指南涵盖 soul、工具和技能，请参阅 LLM.md。

CLI（bash）

该软件包提供独立的 email 二进制文件。账户存储在 ~/.config/email/accounts.json 中，每条命令都支持 --json，用于输出机器可读内容。

# Add an account once
email account add --name work \
  --imap-host imap.example.com --smtp-host smtp.example.com \
  --user [email protected] --pass secret

# Then use it
email sync                              # pull latest from server
email read                             # check inbox
email search "invoice"                 # FTS5 search
email compose send --to [email protected] --subject "Hi" --body "Hello"

# Machine-readable output for agents and scripts
email read queue --json | jq '.entities[].title'
echo "body text" | email compose send --to [email protected] --subject "Hi"

所有命令返回与工具层相同的 { outcome, summary, entities, nextSteps } 结构，并使用一致的退出代码（0 表示成功，1 表示用户错误，2 表示配置错误，3 表示身份验证错误，4 表示网络错误，5 表示工具错误）。

面向 Agent 操作者和 Claude Code / OpenClaw 用户的完整 CLI 参考请参阅 SKILL.md。

工具

五种工具围绕操作者意图设计，而非原始协议操作：

工具	功能
mail_read	读取文件夹列表、邮件队列、线程、邮件正文、附件或原始 EML
mail_search	使用 FTS5 进行本地搜索，或在服务端执行 IMAP SEARCH
mail_compose	发送、回复、转发、保存/更新/发送草稿
mail_organize	标志、标签、复制、移动、归档、移至垃圾箱、标记为垃圾邮件、文件夹管理
mail_sync	连接、断开、重新连接、同步、刷新文件夹、监视

关键特性

• 零运行时依赖。 仅使用 node:sqlite、node:tls、node:net、 node:zlib、node:crypto（Node 24+ 内置模块）。
• 单个预打包文件。 dist/ 中包含一个 ESM 和一个 CJS 入口。不提供子路径 导出，也不拆分代码。
• 纯 SQLite 存储。 使用 FTS5 全文搜索、六张表和确定性的派生读取。Mailbox 会创建并管理自己的 DatabaseSync 实例。
• 完整的 IMAP 引擎。 流式分词器、响应解析器、COMPRESS=DEFLATE、 IDLE（RFC 2177）、CONDSTORE/QRESYNC（RFC 7162）、XOAUTH2/OAUTHBEARER。
• 完整的 SMTP 客户端。 支持 TLS/STARTTLS/明文、PLAIN/LOGIN/XOAUTH2、点 填充，以及发送后将邮件 APPEND 到已发送文件夹。
• 按需获取正文。 初始同步只获取邮件头和 BODYSTRUCTURE。 仅在实际读取邮件正文和附件字节时才会获取。
• JWZ 线程整理。 根据 References/In-Reply-To 邮件头计算会话树，按深度顺序渲染并支持跨文件夹。
• 意图明确的写入操作。 send、reply、forward、archive、trash、 saveDraft、sendDraft——操作名称描述实际行为，而非通用的 CRUD。
• 可扩展的 AI 运行时。 soul 用于定义行为方式，tools 用于执行操作，skills 用于 提供工作流指导——全部可选且结构化。
• 测试与模块并置。 每个非类型模块都有一个并置的 .test.ts 文件。 文档中描述的行为均有可执行测试覆盖。

包接口

import {
  Mailbox,      // porcelain class — the primary entry point
  initSchema,   // schema setup (called automatically by Mailbox.connect())
  read,         // read surface factory
  write,        // write surface factory
  network,      // network surface factory
  tools,        // LLM tool definitions + registry
  skills,       // LLM workflow skills + registry
  soul,         // thinking foundation for system prompts
} from '@ghostpaw/email';

所有领域类型和运行时类型也都可供 TypeScript 使用者从根入口导入：

import type {
  EmailConfig,
  AuthConfig,
  EmailReadSurface,
  EmailWriteSurface,
  EmailNetworkSurface,
  EmailToolDefinition,
  EmailToolResult,
  EmailSkill,
  EmailSoul,
  ComposeInput,
  ReplyInput,
  ForwardInput,
  Message,
  MessageDetail,
  Thread,
  Folder,
  Attachment,
  AttachmentMeta,
  SyncResult,
  WatchEvent,
} from '@ghostpaw/email';

文档

文档	适用对象
SKILL.md	使用 email 作为 bash 工具的 Agent 运维人员和 Claude Code 用户
HUMAN.md	使用 read / write / network 调用 Mailbox API 的开发者
LLM.md	将 soul、tools 和 skills 接入大模型系统的 Agent 构建者
docs/README.md	架构概述：模型、不变量、协议边界和源代码布局
docs/entities/	各实体手册，包含架构、操作和不变量

开发

npm install
npm test            # node:test runner
npm run typecheck   # tsc --noEmit
npm run lint        # biome check
npm run build       # ESM + CJS + declarations via tsup

仓库通过 .nvmrc / .node-version / .tool-versions / mise.toml / Volta 固定使用 Node 24.14.0。可使用你 偏好的任意版本管理器。

支持

如果此包对你的项目有帮助，可以考虑赞助其维护工作：

---

Anonyfox • MIT 许可证