# @ghostpaw/email 中文文档

规范地址：https://npmcn.com/package/%40ghostpaw/email/

版本：0\.5\.11
npm 元数据更新时间：2026-11-10T11:49:24.636Z
中文译文更新时间：2026-11-16T08:12:31.531Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ghostpaw/email
原文对照：https://npmcn.com/package/%40ghostpaw/email/?lang=original
项目主页：https://email.ghostpaw.dev/
源码仓库：https://github.com/GhostPawJS/email

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.8 MB，26 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：0 个
- 首次发布：2026-03-28T13:48:01.452Z
- 最新版本发布：2026-11-10T11:49:24.127Z
- 近 30 天下载量：3261（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

用于 Node.js 的独立 IMAP/SMTP 电子邮件引擎 — SQLite 本地缓存, 线程, 同步, 零依赖, 有内置的 LLM 工具外观

## 安装

```sh
npm install @ghostpaw/email
```

也可以使用：`pnpm add @ghostpaw/email`、`yarn add @ghostpaw/email`、`bun add @ghostpaw/email`

## README

[![GhostPaw email: Your agent can read the inbox. Sending is a separate tool.](https://raw.githubusercontent.com/GhostPawJS/email/main/.github/social-preview.png)](https://email.ghostpaw.dev/)

# @ghostpaw/电子邮件

[![npm](https://img.shields.io/npm/v/@ghostpaw/email?style=flat-square&labelColor=0a1119&color=62e6f2&label=npm)](https://www.npmjs.com/package/@ghostpaw/email) [![CI](https://img.shields.io/github/actions/workflow/status/GhostPawJS/email/ci.yml?branch=main&style=flat-square&labelColor=0a1119&label=CI)](https://github.com/GhostPawJS/email/actions/workflows/ci.yml) [![site](https://img.shields.io/badge/site-email.ghostpaw.dev-62e6f2?style=flat-square&labelColor=0a1119)](https://email.ghostpaw.dev/) [![runtime deps](https://img.shields.io/badge/runtime_deps-0-7af0b4?style=flat-square&labelColor=0a1119)](https://npmcn.com/package/%40ghostpaw/email/package.json) [![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.GhostPawJS%2Femail-b39dff?style=flat-square&labelColor=0a1119)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.GhostPawJS%2Femail/versions/latest) [![node](https://img.shields.io/badge/node-%E2%89%A524-93a5b9?style=flat-square&labelColor=0a1119)](https://nodejs.org/) [![license](https://img.shields.io/npm/l/@ghostpaw/email?style=flat-square&labelColor=0a1119&color=93a5b9)](https://npmcn.com/package/%40ghostpaw/email/LICENSE)

**代理电子邮件:IMAP和SMTP在进程中,被缓存于SQLite,以读取和发送作为单独的工具.**

```bash
curl -fsSL https://raw.githubusercontent.com/GhostPawJS/email/main/install.sh | sh
```

一个针对Node.js的独立电子邮件引擎,由SQLite所建.

电子邮件处理 IMAP 同步, SMTP 发送, 本地缓存, 线程, 搜索,以及 运输错误作为一个连贯的模型,而不是一个抢包协议 适应器. 它作为一个单一的被捆绑 零运行时间依赖, 即刻为三个受众设计: 直接在 代码, LLM 代理通过结构化操作 `soul` 编号 : `tools` 编号 : `skills` 运行时间和想要随时使用代理操作器 `email` CLI 二进制 不写任何线条代码.

## MCP 服务器

下面每个客户端都会启动相同的 stdio 服务器 : `ghostpaw-email mcp`。 。 。 . 对于 npm 环境, 使用 `npx -y @ghostpaw/email mcp` 换句话说. 缓存消息存在 `~/.ghostpaw/email.db` 除非 `GHOSTPAW_EMAIL_DB` 环境变量(绝对路径)或 `--db <path>` 说不然.

**克劳德代码**

```bash
claude mcp add ghostpaw-email -- ghostpaw-email mcp
```

或作为插件,同时安装该技能:

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

**电子邮件 CLI** (单位:千美元)`~/.email/config.toml`(中文(简体) )

```toml
[mcp_servers.ghostpaw-email]
command = "ghostpaw-email"
args = ["mcp"]
```

**光标** (单位:千美元)`.cursor/mcp.json`, (中文(简体) ), **克劳德桌面** (单位:千美元)`claude_desktop_config.json`(中文(简体) ) 或项目 `.mcp.json`数字 :

```json
{
  "mcpServers": {
    "ghostpaw-email": {
      "command": "ghostpaw-email",
      "args": ["mcp"]
    }
  }
}
```

Claude 桌面用户也可以安装 `server.mcpb` 从 [最新 GitHub 发布](https://github.com/GhostPawJS/email/releases/latest)。 。 。 . 容器主机包含一个 Docker 文件 : `docker build -t ghostpaw-email . && docker run -i --rm -v email:/data ghostpaw-email`。 。 。 .

服务器会说MCP 2026-07-28(无状态, `server/discover`)和 以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 届会。 连接命令不保留调用之间的会话 .

在POSIX上,新账户文件和SQLite缓存(包括WAL/SHM侧车)使用模式 `0600`存储目录 `0700`保留现有权限,但改写除外 `accounts.json` 设为 `0600`。 。 。 .

使用 `ghostpaw-email skill --short` 对于一个紧凑的命令作弊表, `ghostpaw-email skill` 供全面参考 `ghostpaw-email skill --list` 以列表向导.

## 在沙盒内跑动

密码CLI内部 `--sandbox workspace-write` 届会、数据库及其 父目录必须在可写入的根内, 包括 SQLite 的 `-wal` 财务报告和审定财务报表 `-shm` 边文件。 默认 DB 下方 `~/.ghostpaw` 这些根的外边可能失败 与 `SQLITE_CANTOPEN` 或者说 `EPERM` (通常退出 70; 目录创建失败) 可能退出 2),即使正常的 shell 权限允许访问. 将 DB 放在工作空间内 `--db ./state/email.db`, (中文(简体) ), 或设置 `GHOSTPAW_EMAIL_DB="$PWD/state/email.db"` 用于CLI/MCP.

要使用外部 DB 目录, 请在启动 OpenAI Codex CLI 时添加 (替换) `<dir-with-db>` 其绝对路径:

```sh
codex exec --sandbox workspace-write --add-dir <dir-with-db> "Run the GhostPaw CLI"
```

或者设置 `sandbox_workspace_write.writable_roots` 内 `~/.codex/config.toml` 在会议开始前:

```toml
[sandbox_workspace_write]
writable_roots = ["/absolute/dir-with-db"]
```

## 名词 CLI

两者 `email` 财务报告和审定财务报表 `ghostpaw-email` 接受此添加剂命令树。 现有 `account`, (中文(简体) ), `read`, (中文(简体) ), `search`, (中文(简体) ), `compose`, (中文(简体) ), `organize` 财务报告和审定财务报表 `sync` 命令保留 他们的旗帜,输出和退出代码。 使用 `mail --help` 新树和 `mail <verb> --help` 参数.

```text
mail read | search
mail send | reply | forward | draft | update-draft | send-draft
mail mark-read | mark-unread | star | unstar | mark-answered
mail copy | move | archive | trash | junk | not-junk
mail set-labels | add-labels | remove-labels
mail create-folder | rename-folder | delete-folder | subscribe-folder | unsubscribe-folder
mail connect | disconnect | reconnect | sync | refresh-folders | watch
```

这33个路径映射到5个对齐的工具. 行动动词设定了工具的动作; `draft` 套装 `save_draft`。搜索作为位置参数接受其查询. 其他领域使用kebab- case 旗帜, 如 `--folder INBOX --uids 1 --uids 2` 财务报告和审定财务报表 `--input @message.json` 为作曲有效载荷。 数组接受重复 旗帜或JSON;对象接受JSON. 价值是字面的,包括领先 `@`。两面旗读取文件 : `--input` 编辑 `mail` 作曲动词和 `--body` 打开 `compose send|reply|draft`关于这些, `@path` 阅读文件, `@-` 读取 静态和 `@@text` 通过 `@text`; 帮助标记它们 `(@file, @- stdin, @@ literal @)`。一个 空或不可读路径出口 2. 单个 `-` 读作Stdin JSON; 清晰的旗帜覆盖了 stdin 字段 . `--` 结束选项解析.

新命令的全球旗帜 : `--db <path>`, (中文(简体) ), `--json`, (中文(简体) ), `-q, --quiet`, (中文(简体) ), `--compact`, (中文(简体) ), `--help`编号 :`-h`, (中文(简体) ), `--version`编号 :`-V`编号 :`-v`, (中文(简体) ), `--no-color`。 。 。 . 管道或管道时输出为 JSON `--json` 已经设定. `-q, --quiet` 压制斯通. `completions bash|zsh|fish` 打印外壳补全设置; `version` 指纹 版本和安装变体。 现有 `tools [--json]`, (中文(简体) ), `describe <tool>`, (中文(简体) ), `call <tool> [JSON|-]`平顶 `mail_<tool> --parameter value`, (中文(简体) ), `mcp` 财务报告和审定财务报表 `skill` 表格仍然可用.

| 新建命令退出代码 | 含义 |
| --- | --- |
| 0 个 | 成功与否 |
| 1个 | 工具错误 |
| 2个 | 用法或计划错误 |
| 3个 | 需要澄清或未查明 |
| 页:1 | 冲突或版本不匹配 |
| 70个 | 意外的内部错误 |

离线示例, 运行到空缓存 :

```sh
ghostpaw-email mail search invoice --db /tmp/email-port-example.db --json
ghostpaw-email mail read --view folders --db /tmp/email-port-example.db --json
ghostpaw-email mail --help
```

搜索返回 0 匹配, 文件夹在空缓存中读取返回 0 文件夹 . `GHOSTPAW_EMAIL_DB` 设置默认缓存路径, 否则 `~/.ghostpaw/email.db` 已使用。 本地搜索和缓存读取不需要 证书。 网络操作使用 `email account add` 配置或 `EMAIL_IMAP_HOST`, (中文(简体) ), `EMAIL_SMTP_HOST`, (中文(简体) ), `EMAIL_USER` 财务报告和审定财务报表 `EMAIL_PASS` (或 `EMAIL_ACCESS_TOKEN`) (中文(简体) ). 每次引用都会结束其网络会话; `mail connect` 不为以后的命令保留会话.

## 工具 CLI

```bash
ghostpaw-email tools
ghostpaw-email call mail_read '{"view":"folders"}' --db :memory:
ghostpaw-email call mail_search '{"query":"invoice"}'
```

两者 `email` 财务报告和审定财务报表 `ghostpaw-email` 运行相同的CLI。 现有账户,改为:, 搜索、编曲、组织和同步命令仍然可用。 整个指南 保存在 [技能/电子邮件/参考资料/cli.md](https://npmcn.com/package/%40ghostpaw/email/skills/email/references/cli.md)。 。 。 .

特工技能: `SKILL.md` 财务报告和审定财务报表 `skills/email/` 包件中的船舶; 打印技能 与 `ghostpaw-email skill`列表指南中 `ghostpaw-email skill --list` 打印一个 `ghostpaw-email skill compose-and-send`。 。 。 .

## 安装

### 释放二进制( 默认)

每行下载最新发行资产,对照发行的SHA256SUMS进行检查,并安装在PATH上(~/.local/bin on Linux/macOS;Windows脚本将其文件夹添加到用户PATH上).

这些行从不编辑 ~/. profile 或其他 shell 启动文件 : `export PATH` 仅适用于当前外壳。 为了保持它的新壳,使用 `~/.profile` 线条下方.

linux-x64: (英语)

```sh
curl -fsSL https://raw.githubusercontent.com/GhostPawJS/email/main/install.sh | sh -s -- --target linux-x64 && export PATH="$HOME/.local/bin:$PATH"
```

linux- arm64 : (原始内容存档于2017-09-31) (英语)

```sh
curl -fsSL https://raw.githubusercontent.com/GhostPawJS/email/main/install.sh | sh -s -- --target linux-arm64 && export PATH="$HOME/.local/bin:$PATH"
```

达文 -阿尔马64:

```sh
curl -fsSL https://raw.githubusercontent.com/GhostPawJS/email/main/install.sh | sh -s -- --target darwin-arm64 && export PATH="$HOME/.local/bin:$PATH"
```

达文-x64:

```sh
curl -fsSL https://raw.githubusercontent.com/GhostPawJS/email/main/install.sh | sh -s -- --target darwin-x64 && export PATH="$HOME/.local/bin:$PATH"
```

窗口- x64( PowerShell; 默认持续将其文件夹添加到用户 PATH 中):

```powershell
irm https://raw.githubusercontent.com/GhostPawJS/email/main/install.ps1 | iex
```

绑入发布会 :

```sh
curl -fsSL https://raw.githubusercontent.com/GhostPawJS/email/main/install.sh | sh -s -- --target linux-x64 --version 0.5.10 && export PATH="$HOME/.local/bin:$PATH"
```

并添加~/. local/ bin 到~. profile( 编辑~. profile一次; 如果它已经提及~/. local/ bin; zsh 登录 shells 读作~. zprofile, 所以使用该文件名 :

```sh
curl -fsSL https://raw.githubusercontent.com/GhostPawJS/email/main/install.sh | sh -s -- --target linux-x64 && { grep -qs '.local/bin' ~/.profile || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile; } && export PATH="$HOME/.local/bin:$PATH"
```

要跳过持续用户 PATH 编辑( 安装器仍然安装并打印要添加的文件夹):

```powershell
$env:GHOSTPAW_NO_MODIFY_PATH=1; irm https://raw.githubusercontent.com/GhostPawJS/email/main/install.ps1 | iex
```

```text
$ ghostpaw-email --version
email 0.5.10 (binary, linux-x64)
```

用于比较版本的脚本 `--version --short` 或者说 `--version --json`。 。 。 .

与 0.5.1 linux- x64 二进制对接 127. 0.0.1 上的本地 GreenMail 测试服务器的会话( 驱动用户, 无真实账户) 和一个新数据库( 输出管道通过) `jq` 保持简短:

![ghostpaw-email 0.5.1 against a local test server: version, account add and show, compose send, sync, read queue, search, organize star and the raw message](https://raw.githubusercontent.com/GhostPawJS/email/main/docs/assets/cli.png)

同一届会议 [动画 GIF](https://raw.githubusercontent.com/GhostPawJS/email/main/docs/assets/cli.gif)。 。 。 .

其他放行安装器 :

```sh
mise use -g github:GhostPawJS/email
ubi --project GhostPawJS/email --exe ghostpaw-email --in ~/.local/bin
eget GhostPawJS/email
```

对于 [水量计](https://aquaproj.github.io/docs/reference/registry-config/),定义 a `github_release` 软件包在 `aqua.yaml`数字 :

```yaml
registries:
  - name: email
    type: local
    path: email-registry.yaml
packages:
  - name: GhostPawJS/email@v<VERSION>
    registry: email
```

`email-registry.yaml`数字 :

```yaml
packages:
  - type: github_release
    repo_owner: GhostPawJS
    repo_name: email
    asset: ghostpaw-email-{{trimV .Version}}-{{.OS}}-{{.Arch}}.tar.gz
    format: tar.gz
    replacements: { amd64: x64 }
    overrides:
      - goos: windows
        asset: ghostpaw-email-{{trimV .Version}}-windows-{{.Arch}}.zip
        format: zip
    files:
      - name: ghostpaw-email
```

安装脚本验证 SHA256SUMS. 校验已下载的归档 [构建证明](https://cli.github.com/manual/gh_attestation_verify)数字 :

```sh
gh attestation verify <archive> -R GhostPawJS/email
```

设定 `GHOSTPAW_VERIFY=attestation` 用于验证 `install.sh`。 。 。 . 二进制是无签名的;macOS 二进制是带有临时签名的. 对于浏览器 在 macOS 上下载,删除隔离 `xattr -d com.apple.quarantine /path/to/ghostpaw-email`。 。 。 . Linux 二进制需要 glibc 2.28+;在高山上使用npx. 见 [二进制构建工作流程](https://npmcn.com/package/%40ghostpaw/email/.github/workflows/release-binaries.yml)。 。 。 .

0.5.1的大小(每个二进制中的26.12.1号):

| 目标 | 存档 | 二进制 |
| --- | --- | --- |
| linux-x64 | 41.7 甲基溴 tar.gz | 117.7甲基溴 |
| linux- arm64 (英语) | 41.2 MB tar.gz | 115.4 溴化二苯乙烯 |
| darwin-arm64 (英语) | 44.9 MB tar.gz | 146.9甲基溴 |
| 达尔文-x64 | 46.4 MB tar.gz | 149.8甲基溴 |
| 窗口-x64 | 38.5 MB 拉链 | 105.8甲基溴 |

在ubuntu-24.04、macos-15和窗口-2025上检查了释放装置.

### npx / npm (针对基于 npm 的环境)

要求数 **节点24+** (使用内置) `node:sqlite` 页:1. Npm包被取出1711个KB解开.

```sh
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
```

### 库(用于将它嵌入代码)

```sh
npm install @ghostpaw/email
```

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

见 [图书馆使用量](https://npmcn.com/package/%40ghostpaw/email/#readme-quick-start)。 。 。 .

## 快速启动

```ts
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: 'user@example.com', 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: 'bob@example.com' }],
  subject: 'Hello',
  text: 'Sent from @ghostpaw/email.',
});

await mailbox.disconnect();
```

`connect()` 打开 SQLite 数据库,将方案设置到 帐号,并认证 IMAP 会话——一个呼叫可以做一切.

## 文档

阅读使用指南手册和存储的电子邮件模式.

-   [概览](https://email.ghostpaw.dev/docs/): 手册涵盖的内容和起点
-   [人类使用](https://email.ghostpaw.dev/docs/human/): 在代码中直接使用库
-   [LLM 组件](https://email.ghostpaw.dev/docs/llm/): 工具、技能和激励代理人的灵魂
-   [账户](https://email.ghostpaw.dev/docs/entities/accounts/): 一个电子邮件身份及其连接
-   [文件夹](https://email.ghostpaw.dev/docs/entities/folders/): 缓存的 IMAP 信箱
-   [信件](https://email.ghostpaw.dev/docs/entities/messages/): 每个文件夹和 UID 页眉记录
-   [机构](https://email.ghostpaw.dev/docs/entities/bodies/): 已解码的信件内容
-   [线索](https://email.ghostpaw.dev/docs/entities/threads/): JWZ 对话树
-   [附录](https://email.ghostpaw.dev/docs/entities/attachments/): 缓存的 MIME 部件
-   [同步](https://email.ghostpaw.dev/docs/entities/sync/): 每个同步通道的日志

仓库参考文献 :

| 文档 | 观众 |
| --- | --- |
| [SKILLL.MD (英语)](https://npmcn.com/package/%40ghostpaw/email/SKILL.md) | 代理操作员和 Claude 代码用户运行 `email` 作为打击工具 |
| [人力资源](https://npmcn.com/package/%40ghostpaw/email/docs/HUMAN.md) | 使用 `Mailbox` API 为 `read` 编号 : `write` 编号 : `network` |
| [法学硕士](https://npmcn.com/package/%40ghostpaw/email/docs/LLM.md) | 代理构建器线条 `soul`, (中文(简体) ), `tools`,以及 `skills` 输入 LLM 系统 |
| [文档/README.md](https://npmcn.com/package/%40ghostpaw/email/docs/README.md) | 架构概览:模型、变量、协议边界、源版式 |
| [文件/实体/](https://npmcn.com/package/%40ghostpaw/email/docs/entities/) | 具有计划、操作和变化因素的实体手册 |

## 模式

7个储存的概念和3个衍生的概念:

| 概念 | 目的 |
| --- | --- |
| **账户** | 一个 IMAP/ SMTP 连接配置的电子邮件身份 |
| **文件夹** | 一个 IMAP 信箱路径,带有同步元数据和角色检测 |
| **消息** | 带有旗帜、标签和信封的本地缓存邮件头记录 |
| **体质** | 一个消息的解码文本/html内容和原始 RFC 2822 字节 |
| **附录** | 用点播二进制获取解码的 MIME 部分 |
| **同步日志** | 每个文件夹完成一次同步通过的记录 |
| **线索** | 一个来自参考文献/In-Reply-to headers的 JWZ 对话树 |

模型意味着每一种邮件状态都有自己的家:

| 看起来像什么 | 其实是什么 |
| --- | --- |
| 一个电子邮件收件箱 | A 类 `Folder` 与 `role: 'inbox'` 和同步消息 |
| 谈话 | A 类 `Thread` 从 `References` 财务报告和审定财务报表 `In-Reply-To` 链条 |
| 未读邮件 | A 类 `Message` 无 `\Seen` 联合国 `flags` 数组 |
| 一个主播邮件 | A 类 `Message` 与 `\Flagged` 联合国 `flags` |
| 信件所附的 PDF | 一个 `Attachment` 根据要求从机构结构获取的元数据 |
| "Sync发现了12条新消息" | A 类 `SyncLog` 行记录策略、计数和持续时间 |

国家是衍生的,而不是切换的。 线索ID从头链中计算 同步时间, 从 IMAP 特殊用途属性中检测到文件夹角色, 以及 从机构结构中提取附件元数据,所有数据都是在 同步, 从未存储为手动状态字段 .

## 两个观众

### 人类开发者

使用 `Mailbox` 类型 `read`, (中文(简体) ), `write`,以及 `network` 表面为 每次邮件操作的直接编码访问 :

```ts
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]);
```

见 [人力资源](https://npmcn.com/package/%40ghostpaw/email/docs/HUMAN.md) 与工作人气的指南 实例.

### LLM 剂

使用 `tools`, (中文(简体) ), `skills`,以及 `soul` 结构化运行时间的命名空间 用于最小化LLM认知负荷的表面:

```ts
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();
```

共享的外观暴露 `name`, (中文(简体) ), `description`, (中文(简体) ), `whenToUse`, (中文(简体) ), `whenNotToUse`, (中文(简体) ), `inputSchema`, (中文(简体) ), `readOnly`,以及 `sideEffects`上下文包含 `read`, (中文(简体) ), `write`,以及 `network` 表面和现有工具输入。 他们回来了 `{ ok, outcome, summary, next, data }`· ; `data.entities` 包含信件或 邮箱参考资料,以及 `next` 包含后续提示。 映射到错误 `ok: false`。 。 。 . 读取操作可能刷新本地缓存, 所以元数据保守标记 所有工具作为写入状态.

```ts
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` 要使用共享形状.

见 [法学硕士](https://npmcn.com/package/%40ghostpaw/email/docs/LLM.md) 对于完整的人工智能指导 覆盖灵魂,工具, 还有技能.

### CLI (巴什语)

包裹船是独立的 `email` 二进制. 账户存储于 `~/.config/email/accounts.json` 每个命令接受 `--json` 页:1 机器可读输出.

```bash
# Add an account once
email account add --name work \
  --imap-host imap.example.com --smtp-host smtp.example.com \
  --user you@example.com --pass secret

# Then use it
email sync                              # pull latest from server
email read                             # check inbox
email search "invoice"                 # FTS5 search
email compose send --to bob@example.com --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 bob@example.com --subject "Hi"
```

`--attach` 联 合 国 `compose send` 财务报告和审定财务报表 `compose reply`)取一个或多个文件 路径, 逗号分隔 :

```bash
email compose send --to bob@example.com --subject "Report" --body "Attached" \
  --attach ./report.pdf,./data.csv
```

每个路径必须是正则文件. 协同效应被跟踪到目标; 目录、设备、 FIFO 和套接字均以退出代码 1 拒绝 (单位:千美元)`invalid_flag_value`)在发送任何信息之前。 MIME类型来自 文件扩展名( 未知扩展名没有明确类型发送) .

所有命令都一样返回 `{ outcome, summary, entities, nextSteps }` 形状为工具层,有一致的退出代码(0成功,1用户出错, 2 配置 3 auth 4 网络 5 工具出错).

见 [SKILLL.MD (英语)](https://npmcn.com/package/%40ghostpaw/email/SKILL.md) 用于代理运算符的完整 CLI 引用 和 Claude 代码/ OpenClaw 用户.

## 工具

围绕操作者意图塑造出五个工具,而不是原始协议操作:

| 工具 | 它会做什么 |
| --- | --- |
| `mail_read` | 读取文件夹列表、 信件队列、 线索、 机构、 附件或原始 EML |
| `mail_search` | FTS5 本地搜索或 IMAP 服务器上的搜索 |
| `mail_compose` | 发送、回复、转发、保存/更新/发送草稿 |
| `mail_organize` | 旗帜、标签、复制、移动、存档、垃圾、垃圾、文件夹管理 |
| `mail_sync` | 连接、 断开、 重新连接、 同步、 刷新文件夹、 监视 |

## 密钥属性

-   **零运行时间依赖关系.** 仅 `node:sqlite`, (中文(简体) ), `node:tls`, (中文(简体) ), `node:net`, (中文(简体) ), `node:zlib`, (中文(简体) ), `node:crypto` (已建为节点24+).
-   **单打包的blob.** 1个无害环境管理+1个CJS条目 `dist/`。无子路径 出口,不拆分代码.
-   **纯SQLite存储.** FTS5 全文搜索,6个表格,以及确定性 来源读取. `Mailbox` 创建和管理自己的 `DatabaseSync` 举个例子.
-   **完整的IMAP引擎.** 流线活化剂 响应解析器 ComPRES=DEFLATE, (英文) IDLE (RFC 2177), CONDSTORE/QRESYNC (RFC 7162), XOUSTH2/OITHBEAR.
-   **完整的SMTP客户端.** TLS/STARTLS/PLAIN/LOGIN/XOITH2,点 填充, 发送后发送 .
-   **取取取取取取取取取取取取取取取取取还取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取.** 初始同步牵引头和机体结构. 信件正文和附件字节在实际读取时被获取 .
-   **JWZ线程.** 根据参考文献/In-Reply-to计算的对话树 头,有深度顺序渲染和交叉文件夹支持.
-   **意为形而作文.** `send`, (中文(简体) ), `reply`, (中文(简体) ), `forward`, (中文(简体) ), `archive`, (中文(简体) ), `trash`, (中文(简体) ), `saveDraft`, (中文(简体) ), `sendDraft` ——说出发生的事情的操作,不是通用的CRUD.
-   **添加AI运行时间.** `soul` 姿势, `tools` 用于采取行动, `skills` 页:1 工作流程指导——全部可选,结构化.
-   **同一地点测试.** 每个非型号模块都有一个合用的位置 `.test.ts` 文档. 记录的行为有可执行的覆盖.

## 软件包表面

```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 的根部也有所有域和运行时类型 消费者:

```ts
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';
```

## 发展

```bash
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
```

重罚被锁定 **节点 24.14.0** 通过 `.nvmrc` 编号 : `.node-version` 编号 : `.tool-versions` 编号 : `mise.toml` /沃尔塔. 使用您的任意版本管理器 更喜欢.

### 支助

如果这个软件包有助于您的项目,请考虑赞助其维护:

[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-EA4AAA?style=for-the-badge&logo=github&logoColor=white)](https://github.com/sponsors/Anonyfox)

* * *

**[无名狐狸](https://anonyfox.com/) 二. 支助 [MIT 许可证](https://npmcn.com/package/%40ghostpaw/email/LICENSE)**

## 常见问题

### @ghostpaw/email 是什么？

用于 Node\.js 的独立 IMAP/SMTP 电子邮件引擎 — SQLite 本地缓存, 线程, 同步, 零依赖, 有内置的 LLM 工具外观

### 如何安装 @ghostpaw/email？

在项目目录运行 npm install @ghostpaw/email，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 email、ghostpaw-email，可以用 npx email 直接运行。

### @ghostpaw/email 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @ghostpaw/email 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @ghostpaw/email 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ghostpaw/email 可以商用吗？

@ghostpaw/email 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ghostpaw/email 的下载量有多少？

根据 npm 官方下载统计，@ghostpaw/email 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,261 次，日均约 109 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ghostpaw/email 还在维护吗？

最新版本 0\.5\.11 发布于 2026/11/10（5 天前）；至今共发布 18 个版本，其中过去 12 个月发布了 18 个；首次发布于 2026/03/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

