Cross Agent Mailbox

文件信箱方案 - 跨框架Agent通信（适用于任何框架）

Security Scan

This is an instruction-only skill that describes a local file-based mailbox for cross-agent communication; its requirements and instructions are generally consistent with that purpose, but there are small documentation/metadata mismatches and operational security considerations you should review before use.

Purpose & Capability

The name/description (file mailbox for cross-framework agent communication) matches the instructions: creating ~/.shared-mailbox, writing/reading .md files, polling or using watchdog. Nothing requested (no env vars, no binaries) appears out of scope for a file-based mailbox.

Instruction Scope

Instructions are limited to creating and using a shared directory, implementing read-status bookkeeping, and optionally running a cron job or a watchdog-based listener. They do not request unrelated files, environment variables, or external endpoints. Operational risks: sharing files across agents can expose sensitive data to any agent/user with filesystem access; instructions don't mention secure permissions, symlink/TOCTOU protections, or handling untrusted input.

Install Mechanism

The skill is instruction-only and has no install spec in the registry (lowest install risk). However, SKILL.md metadata includes an 'install.localPath' pointing to a GitHub repo—this is a minor metadata/documentation mismatch (the platform shows no install). Also the docs recommend using the Python 'watchdog' package but the metadata does not declare that dependency.

Credentials

No credentials, environment vars, or config paths are requested. The skill operates on files under the user's home directory, which is appropriate for the stated purpose. Still verify that this directory is not shared with other untrusted users/agents on the host.

Persistence & Privilege

always:false and no system-wide modifications are requested. The skill does propose long-running processes (watchdog) or cron jobs, which is expected for this use case and does not imply elevated platform privileges.

Assessment

This skill is essentially documentation and examples for a local file-mailbox pattern — it's coherent with that purpose. Before installing/using it: 1) confirm whether your platform will follow the SKILL.md 'install.localPath' (registry shows no install) and review the GitHub repo if you plan to clone/run code from it; 2) only use the mailbox with trusted agents/users — any agent with access to ~/.shared-mailbox can read/write messages and exfiltrate data; 3) set strict filesystem permissions (chmod 700 on the mailbox), consider running agents under isolated/unprivileged accounts, and validate or sanitize message contents to avoid command injection or malicious payloads; 4) if you use watchdog, install and pin the Python dependency yourself and run long‑running listeners in controlled environments; 5) if you need stronger guarantees (confidentiality, integrity, non-repudiation), use a purpose-built messaging system (e.g., authenticated/authorized IPC, message broker) instead of a shared filesystem.

📬 Cross-Agent Mailbox - 文件信箱通信

跨框架Agent通信的最简单方案。适用于任何AI框架之间的通信（Hermes、OpenClaw、Claude等）。

核心理念

两个Agent共享一个文件目录，通过写信/读信方式通信。简单、可靠、无依赖。

工作原理

Agent A → 写信到 → shared-mailbox/a-to-b/ → Agent B 读取
Agent B → 写信到 → shared-mailbox/b-to-a/ → Agent A 读取

安装

1. 创建信箱目录

mkdir -p ~/.shared-mailbox/{agent-a-to-b,agent-b-to-a}/{archive}

2. 创建通信协议文件

cat > ~/.shared-mailbox/README.md << 'EOF'
# 跨Agent通信信箱

## 目录结构
- agent-a-to-b/: Agent A 发给 Agent B 的信件
- agent-b-to-a/: Agent B 发给 Agent A 的信件
- archive/: 已处理的信件

## 信件格式
文件名: YYYY-MM-DD_NNN_主题.md
内容: Markdown格式，包含发件人、收件人、时间、内容
EOF

信件格式模板

# 📬 主题

**发件人**：Agent名称
**收件人**：Agent名称  
**时间**：YYYY-MM-DD HH:MM
**类型**：通知/回复/请求

---

信件内容...

**签名**
时间

使用方法

发送信件

import os
from datetime import datetime

def send_letter(to_agent, content, subject="通信"):
    # 根据目标选择目录
    if to_agent == "agent-b":
        mailbox = os.path.expanduser("~/.shared-mailbox/agent-a-to-b/")
    else:
        mailbox = os.path.expanduser("~/.shared-mailbox/agent-b-to-a/")
    
    # 生成文件名
    timestamp = datetime.now().strftime("%Y-%m-%d_%H%M")
    filename = f"{timestamp}_{subject}.md"
    
    # 写入信件
    with open(os.path.join(mailbox, filename), "w") as f:
        f.write(content)
    
    return filename

检查新信件

import os

def check_mail(my_mailbox):
    """检查是否有新信件（排除archive目录）"""
    mailbox = os.path.expanduser(f"~/.shared-mailbox/{my_mailbox}/")
    
    new_letters = []
    for f in os.listdir(mailbox):
        if f.endswith(".md") and not f.startswith("."):
            new_letters.append(f)
    
    return sorted(new_letters)

归档信件

import shutil

def archive_letter(mailbox, filename):
    """处理完后归档"""
    src = os.path.expanduser(f"~/.shared-mailbox/{mailbox}/{filename}")
    dst = os.path.expanduser(f"~/.shared-mailbox/{mailbox}/archive/{filename}")
    shutil.move(src, dst)

触发机制选择

方案A：定时轮询（简单）

创建cron任务，每5-10分钟检查一次信箱：

# 每5分钟检查
*/5 * * * * cd /path/to/scripts && python3 check_mail.py

优点：简单，任何框架都能用 缺点：有延迟，消耗token

方案B：文件监控（推荐）

使用 watchdog 监控文件变化：

from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler

class MailHandler(FileSystemEventHandler):
    def on_created(self, event):
        if event.src_path.endswith(".md"):
            print(f"📬 新信件: {event.src_path}")
            # 触发处理

observer = Observer()
observer.schedule(MailHandler(), mailbox_path, recursive=False)
observer.start()

优点：实时，几乎零token 缺点：需要常驻进程

通信规范

命名约定

• Agent A → Agent B: agent-a-to-b/
• Agent B → Agent A: agent-b-to-a/

文件命名

YYYY-MM-DD_NNN_简短主题.md
例: 2026-04-15_001_打招呼.md

处理流程

1. 检查信箱目录
2. 读取新信件
3. 处理内容
4. 回复信件（可选）
5. 归档已处理信件

⚠️ 已读机制（必须！避免重复读取）

踩坑经验（2026-04-18）：没有已读机制时，每次检查信箱都会重新读取所有历史消息，导致效率低下。

创建已读状态文件

{
  "version": 1,
  "lastUpdated": "2026-04-18T22:55:00+08:00",
  "readStatus": {
    "hermes-to-chanel": {
      "lastReadFile": "2026-04-17_013_回复-Workspace目录评估.md",
      "readFiles": ["2026-04-17_001_身份提醒.md"],
      "lastReadAt": "2026-04-18T22:38:00+08:00"
    },
    "chanel-to-hermes": {
      "lastReadFile": "2026-04-17_010_紧急-Workspace目录检查结果.md",
      "readFiles": [],
      "lastReadAt": null
    }
  }
}

使用规则

1. 读信件前：先读 read-status.json 获取上次读到哪个文件
2. 只读新信件：跳过已读文件，只读新增的 .md 文件
3. 读完后：更新 read-status.json 记录最新已读状态

Python实现

import json
import os
from pathlib import Path

def get_unread_letters(mailbox_dir: str, status_file: str) -> list:
    """获取未读信件列表"""
    # 读取已读状态
    status = {}
    if os.path.exists(status_file):
        with open(status_file, 'r') as f:
            status = json.load(f)
    
    mailbox_name = os.path.basename(mailbox_dir)
    read_status = status.get('readStatus', {}).get(mailbox_name, {})
    read_files = set(read_status.get('readFiles', []))
    
    # 获取所有信件
    all_letters = []
    for f in os.listdir(mailbox_dir):
        if f.endswith('.md') and not f.startswith('.'):
            all_letters.append(f)
    
    # 过滤已读
    unread = [l for l in sorted(all_letters) if l not in read_files]
    return unread

def mark_as_read(mailbox_dir: str, status_file: str, filename: str):
    """标记信件为已读"""
    # 读取现有状态
    status = {}
    if os.path.exists(status_file):
        with open(status_file, 'r') as f:
            status = json.load(f)
    
    mailbox_name = os.path.basename(mailbox_dir)
    if 'readStatus' not in status:
        status['readStatus'] = {}
    if mailbox_name not in status['readStatus']:
        status['readStatus'][mailbox_name] = {'readFiles': [], 'lastReadFile': None}
    
    # 更新状态
    read_status = status['readStatus'][mailbox_name]
    if filename not in read_status['readFiles']:
        read_status['readFiles'].append(filename)
    read_status['lastReadFile'] = filename
    read_status['lastReadAt'] = datetime.now().isoformat()
    status['lastUpdated'] = datetime.now().isoformat()
    
    # 保存
    with open(status_file, 'w') as f:
        json.dump(status, f, indent=2, ensure_ascii=False)

快捷命令

# 查看未读信件
cat ~/.shared-mailbox/read-status.json | jq '.readStatus."hermes-to-chanel".lastReadFile'

# 对比已读状态
ls -1t ~/.shared-mailbox/hermes-to-chanel/*.md | head -5

---

故障排除

信件没收到

1. 检查目录权限
2. 确认文件名格式正确
3. 查看archive目录是否已归档

信件重复处理

• 使用已读机制避免重复
• 处理后更新 read-status.json

适用场景

• ✅ 跨框架通信（Hermes ↔ OpenClaw）
• ✅ 简单可靠的通信需求
• ✅ 不需要实时性的场景
• ✅ 无额外依赖要求

不适用场景

• ❌ 需要实时通信（用 CFM Redis）
• ❌ 高频消息（>10条/分钟）
• ❌ 需要消息持久化和查询

与其他方案对比

方案	实时性	依赖	复杂度	token消耗
文件信箱	🐢 延迟	无	低	按轮询频率
CFM Redis	⚡ 实时	Redis	中	~0
Webhook	⚡ 实时	HTTP服务	高	~0

---

简单、可靠、无依赖 — 跨框架通信的第一选择！ 📬