AgenticMail 是一个面向 AI 智能体的通信基础设施平台，目标是让 AI 智能体拥有真实的邮箱地址和电话号码，并以编程方式完成邮件、短信、验证码的收发，以及由智能体驱动的外呼语音通话。项目以 npm 包形式发布，仓库根目录提供 AGENTS.md 作为完整运行手册，供智能体自主完成安装与配置。
【主要能力】
- 邮件与短信：智能体可发送和接收真实邮件与文本消息，并获取验证码。
- 电话与语音：支持外呼电话控制与实时语音对话。电话传输提供商可选 46elks 或 Twilio，在电话设置时选择；Twilio 与 46elks 功能对等，包含外呼呼叫控制与实时语音。Twilio 外呼通过 Calls.json REST API、TwiML webhook 与状态回调成本跟踪实现；入站 webhook 使用 X-Twilio-Signature 头（HMAC-SHA1、时序安全、失败关闭）验证。实时语音通过 Twilio Media Streams 与 OpenAI Realtime 桥接，Twilio 音频为 G.711 µ-law @ 8 kHz，OpenAI 会话使用 audio/pcmu，因此无需转码。
- 实时语音工具调用：语音智能体可在通话中调用工具。OpenAI Realtime 会话声明 session.tools，RealtimeVoiceBridge 通过注入的 ToolExecutor 分发模型的函数调用并返回 function_call_output，慢工具期间通过安全网超时与在途调用上限保持电话线路。
- ask_operator 人工介入：智能体在实时通话中记录操作员查询，通知操作员（默认邮件，渠道无关），轮询最多约 5 分钟并以答案继续。若来电者在查询待处理时挂断，任务被标记为断线回拨，操作员答复后重新拨号并带连续性任务。
- 查找工具：web_search（无密钥 DuckDuckGo，结果作为不可信内容围栏）、recall_memory（智能体通用记忆）、get_datetime，以及按智能体密钥作用域的操作员查询 API 端点。
- Telegram 频道：用户注册 Telegram 机器人令牌、关联聊天后，可通过 Telegram 向 AgenticMail 智能体发消息并收到回复。入站 webhook 使用常量时间密钥令牌比较进行认证，同时承载 ask_operator 通知与审批。
- 通用记忆：每个智能体拥有持久、演进的记忆，按类别组织、置信度衰减、支持 BM25F 搜索，跨所有对话存活。AgentMemoryManager 提供 CRUD、文本召回、9 种记忆类别、重要性级别、未访问条目的置信度衰减、访问跟踪、修剪，以及 generateMemoryContext() 将记忆排序渲染为 markdown 块用于提示注入。记忆 API 包括 /memory（set/list/search/get/delete）、/memory/reflect、/memory/context、/memory/stats，每个端点都限定于已认证智能体，智能体只能读写自己的记忆。删除智能体会清除其 agent_memory 行。
- 多智能体协作：call_agent 相比传统子智能体生成实现 53 倍更快的响应时间。分层唤醒上下文系统（Layer 1 ThreadCache 共享最近 10 条消息的信封与预览，Layer 2 AgentMemory 每个智能体在唤醒结束时写入的 markdown 文件）将多智能体线程成本从随线程长度线性增长降至大致平坦。唤醒默认从“所有抄送者”改为“仅收件人”，抄送的本地智能体仍收到邮件但不触发 Claude 轮次，除非在 wake 中显式命名；可用 wake: 'all' 恢复旧行为。唤醒合并：同一（智能体，线程）30 秒内的多个唤醒事件合并为一次 Claude 轮次，可通过 wakeCoalesceMs 配置。
- 任务契约：call_agent / POST /tasks/assign 接受 outputSchema（JSON Schema draft-7 子集），submit_result 据此验证，不匹配返回 400 及验证器错误。
- 媒体工具集（未发布）：本地、可选加入的媒体/视频编辑工具集，包含九个媒体工具：media_tts / media_tts_voices（Edge 文本转语音）、media_image_edit、media_video_edit、media_audio_edit、media_info、media_video_understand、media_voice_clone、media_capabilities。以 MCP media_* 工具和 OpenClaw agenticmail_media_* 工具提供，均为核心 MediaManager 上 /media/* API 路由的瘦客户端。支持电影级视频编辑：调色预设、交叉淡化/擦除转场、定时文字叠加、画中画、分屏、Ken Burns、帧插值慢动作、水印、拼接、音频混合，以及 whisper.cpp 驱动的自动字幕。底层二进制（ffmpeg、ffprobe、ImageMagick、whisper.cpp、Python）不捆绑，每个工具会检测所需二进制并在缺失时返回可操作的安装提示，服务器不会崩溃。所有二进制通过 execFile 与参数数组调用，无 shell、无字符串插值；不可信输入路径经过验证；数值选项被钳制；每次调用有界超时与输出缓冲；输出文件仅落在配置的媒体目录内。
- 可见性与运维：check_activity 显示 dispatcher 心跳状态（alive/unhealthy/missing、uptimeMs、channels、coalesceQueueSize 等）；跳过唤醒环形缓冲区记录每个过滤决策及原因，展示最近 100 条；每智能体 wake_on_cc: false 标志；Web UI 将 To/Cc/Bcc 显示为独立标注行；docs/wake-patterns.md 记录所有唤醒形态与 5 种推荐模式。
- 工作器与自主模式：工作器可运行数小时，每轮日志写入 ~/.agenticmail/worker-logs/<id>.log，每 30 秒心跳，独立 cwd；MCP 工具 tail_worker 可实时读取运行中工作器日志。邮件钩子同时注册在 Stop 事件上，长时间无头 Claude Code 运行在轮次边界看到队友回复时返回 decision: 'block' 强制继续。compact-and-continue 在上下文溢出时合成面包屑检查点并循环（上限 4 次）。
【使用方式】 项目以 npm 包发布，安装与设置可通过仓库根目录 AGENTS.md 中的运行手册完成，支持零提示、约 2 分钟、完全自主的方式。提供 MCP 工具与 OpenClaw 工具集成。实时语音需设置 OPENAI_API_KEY（环境变量或 config.json）。电话传输提供商在电话设置时选择 46elks 或 Twilio。
【适用场景】 需要让 AI 智能体拥有真实邮箱与电话号码、以编程方式收发邮件/短信/验证码、发起外呼语音通话、进行多智能体协作与持久记忆管理的场景；也可用于需要人工介入（ask_operator）的实时通话流程。
【限制与注意事项】 媒体工具集尚未发布。底层媒体二进制不捆绑，需自行安装。实时 Twilio ↔ OpenAI 通话路径与实时 Telegram 投递在 npm 发布前仍需操作员冒烟测试。实时语音端到端路径需要有效的 OPENAI_API_KEY 和已配置的 46elks websocket 号码；桥接逻辑、记忆注入与 WebSocket 升级/认证胶水已用模拟套接字进行单元测试，但实时通话必须由操作员冒烟测试。0.9.54 版本 1038 项测试通过，完整构建绿色。
