⚠️

重要前提

安装AI Skills的关键前提是：必须科学上网，且开启TUN模式，这一点至关重要，直接决定安装能否顺利完成，在此郑重提醒三遍：科学上网，科学上网，科学上网。查看完整安装教程 →

Agent Mail：AI智能体邮件协调层，解决多智能体协作冲突与上下文丢失问题

agent-mail by dicklesworthstone/agent_flywheel_clawdbot_skills_and_integrations

63 周安装量

62 GitHub Stars

安装命令

npx skills add https://github.com/dicklesworthstone/agent_flywheel_clawdbot_skills_and_integrations --skill agent-mail

AI/机器学习团队协作开发运维

🇨🇳中文介绍

MCP Agent Mail

一个面向编码智能体的类邮件协调层，以仅限 HTTP 的 FastMCP 服务器形式提供。提供易记的身份标识、收件箱/发件箱、文件预留租约、联系人策略、可搜索的消息历史记录以及人类监督者消息功能。后端基于 Git（可供人类审计的产物）和 SQLite（支持 FTS5 的快速查询）。

为何存在此项目

在没有协调机制的情况下，多个智能体会：

相互覆盖对方的编辑内容，或在遇到意外差异时陷入混乱
错过并行工作流中的关键上下文
需要人类在不同工具之间传递消息

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

易记的身份标识（形容词+名词的名称，如 "GreenCastle"）
建议性的文件预留，用于表明编辑意图
支持重要性级别和确认回执的线程化消息
提交前守卫，在提交时强制执行预留规则
人类监督者，用于直接的人类到智能体通信

启动服务器

# 最快的方式（安装时添加的别名）
am

# 或手动启动
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

核心概念

项目

每个工作目录（绝对路径）都是一个项目。同一目录下的智能体共享一个项目命名空间。对于需要协调的智能体，请使用相同的 project_key。

智能体身份

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

文件预留（租约）

对文件路径或通配符的建议性锁定。在编辑文件之前，先预留它们以表明意图。其他智能体可以看到预留信息，并可以选择不同的工作。可选的提交前守卫会阻止与其他人独占预留冲突的提交。

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

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

支持 GitHub 风格的 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="bd-123"
)

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

即使存在冲突也会报告，但预留仍会被授予。请检查冲突并根据需要进行协调。

3. 宣布您的工作

send_message(
  project_key="/abs/path/to/project",
  sender_name="GreenCastle",
  to=["BlueLake"],
  subject="[bd-123] Starting auth refactor",
  body_md="Reserving src/auth/**. Will update session handling.",
  thread_id="bd-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`	引导：确保项目存在 → 注册智能体 → 可选的文件预留 → 获取收件箱
`macro_prepare_thread`	加入现有对话：注册 → 总结线程 → 获取收件箱上下文
`macro_file_reservation_cycle`	预留文件，执行工作，完成后可选自动释放
`macro_contact_handshake`	请求联系人权限，可选自动接受，发送欢迎消息

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

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

1. 选择就绪的工作：     bd ready --json → 选择 bd-123
2. 预留文件：           file_reservation_paths(..., reason="bd-123")
3. 宣布开始：           send_message(..., thread_id="bd-123", subject="[bd-123] Starting...")
4. 工作并更新：        在主题中回复进度
5. 完成：              bd close bd-123
                        release_file_reservations(...)
                        send_message(..., subject="[bd-123] Completed")

将 bd-### 用作：

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

Beads 查看器 (bv) 集成

使用 bv 的机器人标志进行智能任务选择：

标志	输出	用例
`bv --robot-insights`	PageRank、关键路径、循环	"什么影响最大？"
`bv --robot-plan`	并行轨道、解除阻塞	"什么可以并行运行？"
`bv --robot-priority`	带有置信度的推荐	"我接下来应该做什么？"
`bv --robot-diff --diff-since <ref>`	自提交/日期以来的更改	"发生了什么变化？"

经验法则： 使用 bd 进行任务操作，使用 bv 获取任务智能。

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

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

选项 B：具有联系人链接的独立项目

# 后端智能体请求与前端智能体建立联系
request_contact(
  project_key="/abs/path/backend",
  from_agent="GreenCastle",
  to_agent="BlueLake",
  to_project="/abs/path/frontend",
  reason="API contract coordination"
)

# 前端智能体接受
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"
)

组合安全：链式运行器会保留 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)`	获取智能体配置文件及最近提交
`create_agent_identity(project_key, program, model)`	始终创建新的唯一智能体

工具	用途
`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')

在 http://127.0.0.1:8765/mail 浏览：

统一收件箱，跨所有项目
按项目搜索，支持 FTS5
线程查看器，支持 Markdown 渲染
文件预留 浏览器
人类监督者：从 Web UI 向智能体发送高优先级消息
相关项目发现：AI 驱动的链接仓库建议

向智能体发送带有自动前言说明的直接消息：

消息标记为 high 重要性
绕过联系人策略
指示智能体暂停当前工作，完成请求，然后恢复

将项目导出为便携式、只读的捆绑包，供审计员、利益相关者或存档使用：

# 交互式向导（推荐）
uv run python -m mcp_agent_mail.cli share wizard

# 手动导出
uv run python -m mcp_agent_mail.cli share export --output ./bundle

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

# 本地预览
uv run python -m mcp_agent_mail.cli share preview ./bundle

Ed25519 加密签名
使用 Age 加密进行保密分发
清理预设：standard（移除密钥）或 strict（编辑正文）
通过向导部署到 GitHub Pages 或 Cloudflare Pages

# 保存当前状态
uv run python -m mcp_agent_mail.cli archive save --label nightly

# 列出恢复点
uv run python -m mcp_agent_mail.cli archive list --json

# 灾难后恢复
uv run python -m mcp_agent_mail.cli archive restore <file>.zip --force

邮箱健康检查（医生）

# 运行诊断
uv run python -m mcp_agent_mail.cli doctor check

# 预览修复
uv run python -m mcp_agent_mail.cli doctor repair --dry-run

# 应用修复（首先创建备份）
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`，确认智能体名称完全匹配

# 单行命令（推荐）
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh?$(date +%s)" | bash -s -- --yes

# 自定义端口
curl -fsSL ... | bash -s -- --port 9000 --yes

# 安装后更改端口
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`	—	用于身份验证的静态承载令牌
`LLM_ENABLED`	`true`	启用 LLM 进行摘要/发现
`CONTACT_ENFORCEMENT_ENABLED`	`true`	强制执行联系人策略

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

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

🇺🇸English

MCP Agent Mail

A mail-like coordination layer for coding agents exposed as an HTTP-only FastMCP server. Provides memorable identities, inbox/outbox, file reservation leases, contact policies, searchable message history, and Human Overseer messaging. Backed by Git (human-auditable artifacts) and SQLite (fast queries with FTS5).

Why This Exists

Without coordination, multiple agents:

Overwrite each other's edits or panic on unexpected diffs
Miss critical context from parallel workstreams
Require humans to relay messages between tools

Agent Mail solves this with:

Memorable identities (adjective+noun names like "GreenCastle")
Advisory file reservations to signal editing intent
Threaded messaging with importance levels and acknowledgments
Pre-commit guard to enforce reservations at commit time
Human Overseer for direct human-to-agent communication

Starting the Server

# Quickest way (alias added during install)
am

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

Default: http://127.0.0.1:8765 Web UI for humans: http://127.0.0.1:8765/mail

Core Concepts

Projects

Each working directory (absolute path) is a project. Agents in the same directory share a project namespace. Use the same project_key for agents that need to coordinate.

Agent Identity

Agents register with adjective+noun names (GreenCastle, BlueLake). Names are unique per project, memorable, and appear in inboxes, commit logs, and the web UI.

File Reservations (Leases)

Advisory locks on file paths or globs. Before editing files, reserve them to signal intent. Other agents see the reservation and can choose different work. The optional pre-commit guard blocks commits that conflict with others' exclusive reservations.

Contact Policies

Per-agent policies control who can message whom:

Policy	Behavior
`open`	Accept any message in the project
`auto` (default)	Allow if shared context exists (same thread, overlapping reservations, recent contact)
`contacts_only`	Require explicit contact approval first
`block_all`	Reject all new contacts

Messages

GitHub-Flavored Markdown with threading, importance levels (low, normal, high, urgent), and optional acknowledgment requirements. Images are auto-converted to WebP.

Essential Workflow

1. Start Session (One-Call Bootstrap)

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

Returns: {project, agent, file_reservations, inbox}

This single call: ensures project exists, registers your identity, optionally reserves files, fetches your inbox.

2. Reserve Files Before Editing

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="bd-123"
)

Returns: {granted: [...], conflicts: [...]}

Conflicts are reported but reservations are still granted. Check conflicts and coordinate if needed.

3. Announce Your Work

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

4. Check Inbox Periodically

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

Or use resources for fast reads:

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

5. Release Reservations When Done

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

The Four Macros

Prefer macros for speed and smaller models. Use granular tools when you need fine control.

Macro	Purpose
`macro_start_session`	Bootstrap: ensure project → register agent → optional file reservations → fetch inbox
`macro_prepare_thread`	Join existing conversation: register → summarize thread → fetch inbox context
`macro_file_reservation_cycle`	Reserve files, do work, optionally auto-release when done
`macro_contact_handshake`	Request contact permission, optionally auto-accept, send welcome message

Beads Integration (bd-### Workflow)

When using Beads for task management, keep identifiers aligned:

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

Use bd-### as:

Mail thread_id
Message subject prefix [bd-###]
File reservation reason
Commit message reference

Beads Viewer (bv) Integration

Use bv's robot flags for intelligent task selection:

Flag	Output	Use Case
`bv --robot-insights`	PageRank, critical path, cycles	"What's most impactful?"
`bv --robot-plan`	Parallel tracks, unblocks	"What can run in parallel?"
`bv --robot-priority`	Recommendations with confidence	"What should I work on next?"
`bv --robot-diff --diff-since <ref>`	Changes since commit/date	"What changed?"

Rule of thumb: Use bd for task operations, use bv for task intelligence.

Cross-Project Coordination

For frontend/backend or multi-repo projects:

Option A: Shared project_key Both repos use the same project_key. Agents coordinate automatically.

Option B: Separate projects with contact links

# 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
)

Pre-Commit Guard

Install the guard to block commits that conflict with others' exclusive reservations:

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

Guard Features

Composition-safe : Chain-runner preserves existing hooks in hooks.d/
Rename-aware : Checks both old and new paths for renames/moves
NUL-safe : Handles paths with special characters
Git-native matching : Uses Git wildmatch pathspec semantics

Set AGENT_NAME environment variable so the guard knows who you are.

Bypass in emergencies: AGENT_MAIL_BYPASS=1 git commit ...

Tools Reference

Project & Identity

Tool	Purpose
`ensure_project(human_key)`	Create/ensure project exists
`register_agent(project_key, program, model, name?, task_description?)`	Register identity
`whois(project_key, agent_name)`	Get agent profile with recent commits
`create_agent_identity(project_key, program, model)`	Always create new unique agent

Messaging

Tool	Purpose
`send_message(project_key, sender, to, subject, body_md, ...)`	Send message
`reply_message(project_key, message_id, sender, body_md)`	Reply (preserves thread)
`fetch_inbox(project_key, agent, limit?, since_ts?, urgent_only?)`	Get messages
`mark_message_read(project_key, agent, message_id)`	Mark as read
`acknowledge_message(project_key, agent, message_id)`	Acknowledge receipt

File Reservations

Tool	Purpose
`file_reservation_paths(project_key, agent, paths, ttl?, exclusive?)`	Reserve files
`release_file_reservations(project_key, agent, paths?)`	Release reservations
`renew_file_reservations(project_key, agent, extend_seconds?)`	Extend TTL
`force_release_file_reservation(project_key, agent, reservation_id)`	Clear stale reservation

Contact Management

Tool	Purpose
`request_contact(project_key, from_agent, to_agent, reason?)`	Request permission to message
`respond_contact(project_key, to_agent, from_agent, accept)`	Accept/deny contact request
`list_contacts(project_key, agent_name)`	List contact links
`set_contact_policy(project_key, agent_name, policy)`	Set open/auto/contacts_only/block_all

Resources (Fast Reads)

Use resources for quick, non-mutating reads:

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}

Search Syntax (FTS5)

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

Example: search_messages(project_key, '"auth module" AND error NOT legacy')

Web UI Features

Browse at http://127.0.0.1:8765/mail:

Unified inbox across all projects
Per-project search with FTS5
Thread viewer with markdown rendering
File reservations browser
Human Overseer : Send high-priority messages to agents from the web UI
Related Projects Discovery : AI-powered suggestions for linking repos

Human Overseer

Send direct messages to agents with automatic preamble:

Messages marked as high importance
Bypasses contact policies
Agents are instructed to pause current work, complete request, then resume

Static Mailbox Export

Export projects to portable, read-only bundles for auditors, stakeholders, or archives:

# 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

Export Features

Ed25519 cryptographic signing
Age encryption for confidential distribution
Scrub presets: standard (removes secrets) or strict (redacts bodies)
Deploy to GitHub Pages or Cloudflare Pages via wizard

Disaster Recovery

# 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

Mailbox Health (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

Checks: stale locks, database integrity, orphaned records, FTS sync, expired reservations.

Common Pitfalls

Error	Fix
"sender_name not registered"	Call `register_agent` or `macro_start_session` first
"FILE_RESERVATION_CONFLICT"	Wait for expiry, coordinate, or use non-exclusive
"CONTACT_BLOCKED"	Use `request_contact` and wait for approval
Empty inbox	Check `since_ts`, `urgent_only`, verify agent name matches exactly

Installation

# 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

Key Environment Variables

Variable	Default	Description
`STORAGE_ROOT`	`~/.mcp_agent_mail_git_mailbox_repo`	Root for repos and SQLite DB
`HTTP_PORT`	`8765`	Server port
`HTTP_BEARER_TOKEN`	—	Static bearer token for auth
`LLM_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

Integration with Flywheel

Tool	Integration
NTM	Agent panes coordinate via mail, dashboard shows inbox
BV	Task IDs become thread IDs, robot flags inform task selection
CASS	Search mail threads across sessions
CM	Extract procedural memory from mail archives
DCG	Mail notifies agents of blocked commands
RU	Coordinate multi-repo updates via cross-project mail

Weekly Installs

Repository

dicklesworthsto…grations

GitHub Stars

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykFail

Installed on

gemini-cli31

opencode30

codex28

claude-code25

cursor24

amp24

search_messages(project_key, query)

Agent Mail：AI智能体邮件协调层，解决多智能体协作冲突与上下文丢失问题

🇨🇳中文介绍

MCP Agent Mail

为何存在此项目

启动服务器

核心概念

项目

智能体身份

相关 Skills

文件预留（租约）

联系人策略

消息

基本工作流程

1. 启动会话（单次调用引导）

2. 编辑前预留文件

3. 宣布您的工作

4. 定期检查收件箱

5. 完成后释放预留

四个宏

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

Beads 查看器 (bv) 集成

跨项目协调

提交前守卫

守卫特性

工具参考

项目与身份

消息传递

文件预留

联系人管理

资源（快速读取）

搜索语法（FTS5）

Web UI 特性

人类监督者

静态邮箱导出

导出特性

灾难恢复

邮箱健康检查（医生）

常见陷阱

安装

关键环境变量

Docker

与 Flywheel 集成

🇺🇸English

MCP Agent Mail

Why This Exists

Starting the Server

Core Concepts

Projects

Agent Identity

File Reservations (Leases)

Contact Policies

Messages

Essential Workflow

1. Start Session (One-Call Bootstrap)

2. Reserve Files Before Editing

3. Announce Your Work

4. Check Inbox Periodically

5. Release Reservations When Done

The Four Macros

Beads Integration (bd-### Workflow)

Beads Viewer (bv) Integration

Cross-Project Coordination

Pre-Commit Guard

Guard Features

Tools Reference

Project & Identity

Messaging

File Reservations

Contact Management

Resources (Fast Reads)

Search Syntax (FTS5)

Web UI Features

Human Overseer

Static Mailbox Export

Export Features

Disaster Recovery

Mailbox Health (Doctor)

Common Pitfalls

Installation

Key Environment Variables