agent-mail

Agent 邮件系统

用于协调多个 Agent 的通信系统。

概述

Agent 邮件支持：

• Agent 之间传递消息
• 文件预留以防止冲突
• 跨 Agent 的会话跟踪
• 基于线程的对话

会话管理

启动 Agent 会话

注册 Agent 并获取收件箱：

# Initialize session
curl -X POST http://localhost:3847/api/session/start \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/project",
    "program": "claude-code",
    "model": "opus-4",
    "agent_name": "agent-1",
    "task_description": "Working on auth module"
  }'

列出 Agent

curl http://localhost:3847/api/agents?project_path=/path/to/project

Agent 信息

curl http://localhost:3847/api/agents/agent-1?project_path=/path/to/project

消息传递

发送消息

curl -X POST http://localhost:3847/api/mail/send \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/project",
    "sender_name": "agent-1",
    "to": ["agent-2"],
    "subject": "Auth module complete",
    "body_md": "## Summary\nAuth implementation is done.\n\n## Files changed\n- src/auth/*",
    "importance": "normal",
    "ack_required": false
  }'

查看收件箱

curl "http://localhost:3847/api/mail/inbox?project_path=/path/to/project&agent_name=agent-1"

回复消息

curl -X POST http://localhost:3847/api/mail/reply \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/project",
    "message_id": 123,
    "sender_name": "agent-2",
    "body_md": "Thanks! I'\''ll start on the API integration."
  }'

确认消息

curl -X POST http://localhost:3847/api/mail/ack \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/project",
    "agent_name": "agent-2",
    "message_id": 123
  }'

搜索消息

curl "http://localhost:3847/api/mail/search?project_path=/path/to/project&query=authentication"

文件预留

在多个 Agent 编辑文件时防止冲突。

预留文件

curl -X POST http://localhost:3847/api/files/reserve \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/project",
    "agent_name": "agent-1",
    "paths": ["src/auth/*.ts", "src/config.ts"],
    "exclusive": true,
    "reason": "Implementing authentication",
    "ttl_seconds": 3600
  }'

查看预留

curl "http://localhost:3847/api/files/reservations?project_path=/path/to/project"

释放文件

curl -X POST http://localhost:3847/api/files/release \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/project",
    "agent_name": "agent-1",
    "paths": ["src/auth/*.ts"]
  }'

线程管理

获取线程摘要

curl "http://localhost:3847/api/mail/thread/THREAD_ID/summary?project_path=/path/to/project"

线程操作

回复消息时会自动创建线程。

协调模式

任务交接

Agent 1 completes task:
1. Reserve output files
2. Complete work
3. Send message to Agent 2 with handoff details
4. Release file reservations

Agent 2 receives:
1. Get inbox
2. Reserve input files
3. Continue work
4. Acknowledge receipt

并行工作

Coordinator:
1. Reserve coordination files
2. Send tasks to agents
3. Wait for completion messages
4. Merge results

Workers:
1. Reserve assigned files
2. Complete task
3. Send completion message
4. Release files

审查请求

Author:
1. Complete code
2. Send review request to reviewer agents
3. Wait for feedback

Reviewers:
1. Get inbox
2. Review code (read-only, no reservation needed)
3. Send feedback message

健康检查

curl http://localhost:3847/api/health

消息重要级别

级别	使用场景
low	仅供参考、状态更新
normal	标准通信
high	需要尽快关注
urgent	阻塞性问题，需要立即响应

最佳实践

1. 编辑前先预留 - 防止冲突
2. 使用有意义的主题 - 便于快速浏览收件箱
3. 确认重要消息 - 当 ack_required 时确认收到
4. 及时释放 - 不要无必要地持有预留
5. 使用线程 - 将相关消息保持在一起
6. 定期查看收件箱 - 不要错过消息
7. 干净地交接 - 包含所有所需上下文