agent-mail

MCP Agent Mail

一个类似邮件的协调层，通过仅支持 HTTP 的 FastMCP 服务为编码 Agent 提供服务。提供易记的身份标识、收件箱／发件箱、文件预留租约、联系人策略、可搜索的消息历史记录，以及与人工监督者的消息通信。由 Git（便于人工审查的产物）和 SQLite（通过 FTS5 实现快速查询）提供支持。

为什么要有它

缺乏协调时，多个 Agent 会：

• 覆盖彼此的编辑内容，或对意外差异感到慌乱
• 错过并行工作流中的关键信息
• 需要人类在工具之间转达消息

Agent Mail 通过以下方式解决这些问题：

• 易记的身份标识（例如“GreenCastle”这样的形容词＋名词名称）
• 用于表明编辑意图的建议性文件预留
• 带有重要程度级别和确认机制的线程式消息
• 在提交时强制执行预留规则的提交前防护机制
• 用于人类与 Agent 直接通信的人工监督者

启动服务

# Quickest way (alias added during install)
am

# Or manually
cd ~/projects/mcp_agent_mail
./scripts/run_server_with_token.sh

默认地址：http://127.0.0.1:8765 供人类使用的 Web UI：http://127.0.0.1:8765/mail

核心概念

项目

每个工作目录（绝对路径）都是一个项目。同一目录中的 Agent 共享一个项目命名空间。需要协调的 Agent 应使用相同的 project_key。

Agent 身份

Agent 使用形容词＋名词名称（GreenCastle、BlueLake）注册。名称在每个项目中唯一、易于记忆，并会显示在收件箱、提交日志和 Web UI 中。

文件预留（租约）

针对文件路径或 glob 模式的建议性锁。编辑文件前，请先预留文件以表明意图。其他 Agent 可以看到预留，并选择其他工作。可选的提交前防护机制会阻止与其他 Agent 的独占预留冲突的提交。

联系人策略

每个 Agent 的策略控制谁可以向谁发送消息：

策略	行为
open	接受项目中的任何消息
auto（默认）	存在共享上下文时允许联系（同一线程、预留重叠或近期联系）
contacts_only	需要先明确批准联系人
block_all	拒绝所有新联系人

消息

支持 GitHub Flavored Markdown、线程、重要程度级别（low、normal、high、urgent）以及可选的确认要求。图片会自动转换为 WebP。

基本工作流

1. 启动会话（一次调用完成引导）

macro_start_session(
  human_key="/abs/path/to/project",
  program="claude-code",
  model="opus-4.5",
  task_description="Implementing auth module"
)

返回：{project, agent, file_reservations, inbox}

这一次调用即可完成：确保项目存在、注册你的身份、可选地预留文件，并获取你的收件箱。

2. 编辑前预留文件

file_reservation_paths(
  project_key="/abs/path/to/project",
  agent_name="GreenCastle",
  paths=["src/auth/**/*.ts", "src/middleware/auth.ts"],
  ttl_seconds=3600,
  exclusive=true,
  reason="br-123"
)

返回：{granted: [...], conflicts: [...]}

即使存在冲突，预留仍会获批。请检查冲突，并在需要时进行协调。

3. 宣布你的工作

send_message(
  project_key="/abs/path/to/project",
  sender_name="GreenCastle",
  to=["BlueLake"],
  subject="[br-123] Starting auth refactor",
  body_md="Reserving src/auth/**. Will update session handling.",
  thread_id="br-123",
  importance="normal",
  ack_required=true
)

4. 定期检查收件箱

fetch_inbox(
  project_key="/abs/path/to/project",
  agent_name="GreenCastle",
  limit=20,
  urgent_only=false,
  include_bodies=true
)

也可以使用资源快速读取：

resource://inbox/GreenCastle?project=/abs/path&limit=20&include_bodies=true

5. 完成后释放预留

release_file_reservations(
  project_key="/abs/path/to/project",
  agent_name="GreenCastle"
)

四个宏

为提高速度并适配较小的模型，优先使用宏。需要精细控制时，再使用细粒度工具。

宏	用途
macro_start_session	引导流程：确保项目存在 → 注册 Agent → 可选的文件预留 → 获取收件箱
macro_prepare_thread	加入现有对话：注册 → 汇总线程 → 获取收件箱上下文
macro_file_reservation_cycle	预留文件、开展工作，并可选择在完成后自动释放
macro_contact_handshake	请求联系人权限，可选择自动接受，并发送欢迎消息

Beads 集成（br-### 工作流）

使用 Beads 管理任务时，请保持标识符一致：

1. Pick ready work:     br ready --json → choose br-123
2. Reserve files:       file_reservation_paths(..., reason="br-123")
3. Announce start:      send_message(..., thread_id="br-123", subject="[br-123] Starting...")
4. Work and update:     Reply in thread with progress
5. Complete:            br close br-123
                        release_file_reservations(...)
                        send_message(..., subject="[br-123] Completed")

将 br-### 用作：

• 邮件 thread_id
• 消息主题前缀 [br-###]
• 文件预留 reason
• 提交消息引用

Beads Viewer（bv）集成

使用 bv 的 robot 标志智能选择任务：

标志	输出	使用场景
bv --robot-insights	PageRank、关键路径、循环	“影响最大的是哪个？”
bv --robot-plan	并行轨道、解除阻塞项	“哪些任务可以并行进行？”
bv --robot-priority	附带置信度的建议	“接下来应该处理什么？”
bv --robot-diff --diff-since <ref>	自提交/日期以来的变更	“发生了什么变化？”

经验法则： 使用 br 执行任务操作，使用 bv 获取任务洞察。

跨项目协调

适用于前端/后端或多仓库项目：

选项 A：共享 project_key 两个仓库使用相同的 project_key。Agent 会自动协调。

选项 B：通过联系链接连接独立项目

# Backend agent requests contact with frontend agent
request_contact(
  project_key="/abs/path/backend",
  from_agent="GreenCastle",
  to_agent="BlueLake",
  to_project="/abs/path/frontend",
  reason="API contract coordination"
)

# Frontend agent accepts
respond_contact(
  project_key="/abs/path/frontend",
  to_agent="BlueLake",
  from_agent="GreenCastle",
  accept=true
)

提交前防护

安装防护机制，阻止与其他人的独占预留相冲突的提交：

install_precommit_guard(
  project_key="/abs/path/to/project",
  code_repo_path="/abs/path/to/project"
)

防护功能

• 组合安全：Chain-runner 会保留 hooks.d/ 中现有的钩子
• 支持重命名：检查重命名/移动操作的旧路径和新路径
• NUL 安全：支持包含特殊字符的路径
• Git 原生匹配：使用 Git wildmatch 路径规范语义

设置 AGENT_NAME 环境变量，让防护机制知道你的身份。

紧急情况下可绕过：AGENT_MAIL_BYPASS=1 git commit ...

工具参考

项目与身份

工具	用途
ensure_project(human_key)	创建项目/确保项目存在
register_agent(project_key, program, model, name?, task_description?)	注册身份
whois(project_key, agent_name)	获取包含近期提交记录的 Agent 个人资料
create_agent_identity(project_key, program, model)	始终创建新的唯一 Agent

消息

工具	用途
send_message(project_key, sender, to, subject, body_md, ...)	发送消息
reply_message(project_key, message_id, sender, body_md)	回复（保留会话线程）
fetch_inbox(project_key, agent, limit?, since_ts?, urgent_only?)	获取消息
mark_message_read(project_key, agent, message_id)	标记为已读
acknowledge_message(project_key, agent, message_id)	确认收到
search_messages(project_key, query)	FTS5 搜索
summarize_thread(project_key, thread_id)	提取要点和操作项

文件预留

工具	用途
file_reservation_paths(project_key, agent, paths, ttl?, exclusive?)	预留文件
release_file_reservations(project_key, agent, paths?)	释放预留
renew_file_reservations(project_key, agent, extend_seconds?)	延长 TTL
force_release_file_reservation(project_key, agent, reservation_id)	清除过期预留

联系人管理

工具	用途
request_contact(project_key, from_agent, to_agent, reason?)	请求发送消息的权限
respond_contact(project_key, to_agent, from_agent, accept)	接受/拒绝联系人请求
list_contacts(project_key, agent_name)	列出联系链接
set_contact_policy(project_key, agent_name, policy)	设置 open/auto/contacts_only/block_all

资源（快速读取）

使用资源进行快速、非变更性读取：

resource://inbox/{agent}?project=<path>&limit=20&include_bodies=true
resource://thread/{thread_id}?project=<path>&include_bodies=true
resource://message/{id}?project=<path>
resource://file_reservations/{slug}?active_only=true
resource://project/{slug}
resource://projects
resource://agents/{project_key}

搜索语法（FTS5）

"exact phrase"
prefix*
term1 AND term2
term1 OR term2
subject:login
body:"api key"
(auth OR login) AND NOT admin

示例：search_messages(project_key, '"auth module" AND error NOT legacy')

Web UI 功能

访问 http://127.0.0.1:8765/mail：

• 统一收件箱：跨所有项目
• 按项目搜索：使用 FTS5
• 会话查看器：支持 Markdown 渲染
• 文件预留：浏览预留文件
• 人工监督者：通过 Web UI 向 Agent 发送高优先级消息
• 相关项目发现：AI 驱动的仓库关联建议

人工监督者

向 Agent 发送带有自动前置说明的直接消息：

• 消息会被标记为 high 重要性
• 绕过联系人策略
• 系统会指示 Agent 暂停当前工作、完成请求，然后继续

静态邮箱导出

将项目导出为可移植的只读数据包，供审计人员、利益相关方或归档使用：

# Interactive wizard (recommended)
uv run python -m mcp_agent_mail.cli share wizard

# Manual export
uv run python -m mcp_agent_mail.cli share export --output ./bundle

# With signing
uv run python -m mcp_agent_mail.cli share export \
  --output ./bundle \
  --signing-key ./keys/signing.key

# Preview locally
uv run python -m mcp_agent_mail.cli share preview ./bundle

导出功能

• Ed25519 加密签名
• 使用 Age 加密进行机密分发
• 脱敏预设：standard（移除机密信息）或 strict（隐藏正文）
• 通过向导部署到 GitHub Pages 或 Cloudflare Pages

灾难恢复

# Save current state
uv run python -m mcp_agent_mail.cli archive save --label nightly

# List restore points
uv run python -m mcp_agent_mail.cli archive list --json

# Restore after disaster
uv run python -m mcp_agent_mail.cli archive restore <file>.zip --force

邮箱健康检查（Doctor）

# Run diagnostics
uv run python -m mcp_agent_mail.cli doctor check

# Preview repairs
uv run python -m mcp_agent_mail.cli doctor repair --dry-run

# Apply repairs (creates backup first)
uv run python -m mcp_agent_mail.cli doctor repair

检查项：过期锁、数据库完整性、孤立记录、FTS 同步、过期预留。

常见问题

错误	解决方法
"sender_name not registered"	先调用 register_agent 或 macro_start_session
"FILE_RESERVATION_CONFLICT"	等待预留过期、协调处理，或使用非独占模式
"CONTACT_BLOCKED"	使用 request_contact 并等待批准
收件箱为空	检查 since_ts、urgent_only，并确认 Agent 名称完全一致

安装

# One-liner (recommended)
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh?$(date +%s)" | bash -s -- --yes

# Custom port
curl -fsSL ... | bash -s -- --port 9000 --yes

# Change port after installation
uv run python -m mcp_agent_mail.cli config set-port 9000

关键环境变量

变量	默认值	描述
STORAGE_ROOT	~/.mcp_agent_mail_git_mailbox_repo	仓库和 SQLite DB 的根目录
HTTP_PORT	8765	服务端口
HTTP_BEARER_TOKEN	—	用于身份验证的静态 bearer token
LLM_ENABLED	true	启用大模型进行摘要和发现
CONTACT_ENFORCEMENT_ENABLED	true	强制执行联系策略

Docker

docker build -t mcp-agent-mail .
docker run --rm -p 8765:8765 \
  -e HTTP_HOST=0.0.0.0 \
  -v agent_mail_data:/data \
  mcp-agent-mail

与 Flywheel 集成

工具	集成方式
NTM	Agent 窗格通过邮件协调，仪表板显示收件箱
BV	任务 ID 成为线程 ID，机器人标记用于辅助选择任务
CASS	搜索跨会话的邮件线程
CM	从邮件档案中提取程序性记忆
DCG	邮件会通知 Agent 有命令被阻止
RU	通过跨项目邮件协调多仓库更新