⚡

AIMaestroAgentMessagingSkill ai-maestro-agent-messaging

AI Maestro Agent Messaging 是一个用于AI代理间通信的技能，支持发送和接收消息，适用于需要代理间协作的场景，如软件开发、自动化运维等。

AI智能体 0 次安装 0 次浏览 更新于 2/28/2026

AI Maestro Agent Messaging

目的

使用 AI Maestro 的双通道消息系统，实现 AI 编码代理之间的通信。当用户要求“发送消息”、“检查收件箱”、“阅读消息”、“通知[代理]”、“告诉[代理]”或任何代理间通信时，使用此技能。

临界：代理间通信

你是代理 - 此技能用于代理到代理通信，非人-代理通信。

重要：理解“你的消息”

当操作员说“检查你的消息”或“阅读你的消息”：

  • 你的收件箱 = 向你的代理发送的消息（来自任何人 - 操作员、其他代理等）
  • 不是操作员的收件箱 = 你检查你的收件箱，不是操作员的

示例：

  • 人类说：“检查你的消息”
  • 你是代理：backend-api
  • 你检查：~/.aimaestro/messages/inbox/backend-api/（你的收件箱）
  • 这些是向backend-api发送的消息（来自任何发送者）
  • 你不检查：操作员的收件箱或其他代理的收件箱

代理身份

  • 你的收件箱 = 向你的代理发送的消息（来自任何发送者）
  • 你的代理 ID = 此代理的唯一标识符（也可以使用代理名称作为回退）
  • 你的代理名称 = 你运行的 tmux 会话名称（使用tmux display-message -p '#S'获取）
  • 你的收件箱位置 = ~/.aimaestro/messages/inbox/YOUR-AGENT-ID/或~/.aimaestro/messages/inbox/YOUR-AGENT-NAME/

你不阅读：

  • ❌ 操作员的收件箱
  • ❌ 其他代理的收件箱
  • ❌ 未向您的代理发送的消息

你确实阅读：

  • ✅ 向你的代理发送的消息
  • ✅ 只阅读你自己的收件箱
  • ✅ 你的代理的收件箱：~/.aimaestro/messages/inbox/YOUR-AGENT-ID/

何时使用此技能

发送（代理到代理）：

  • 用户（操作员）说“向[另一个代理]发送消息”
  • 用户说“通知[另一个代理]”或“提醒[另一个代理]”
  • 用户希望你与另一个代理通信
  • 你需要向其他代理发送紧急警报或请求

接收（检查你自己的收件箱）：

  • 用户说“检查我的收件箱”或“检查我的消息” = 使用 check-aimaestro-messages.sh
  • 用户说“阅读我的消息”或“阅读消息 X” = 使用 read-aimaestro-message.sh <id>
  • 用户问“有新消息吗？” = 使用 check-aimaestro-messages.sh
  • 代理刚刚启动（最佳实践：首先检查你自己的收件箱）
  • 你想要查看其他代理发送到你的消息

推荐工作流程：

  1. 首先检查未读消息：check-aimaestro-messages.sh
  2. 然后阅读特定消息：read-aimaestro-message.sh <message-id>
  3. 阅读后消息自动标记为已读

可用工具

第一部分：接收消息（你自己的收件箱）

📖 快速开始 - 检查和阅读消息：

# 第 1 步：检查你有什么未读消息
check-aimaestro-messages.sh

# 输出显示：
# [msg-1234...] 🔴 来自：backend-api | 2025-10-29 14:30
#     主题：Authentication endpoint ready
#     预览：The /api/auth/login endpoint is now...

# 第 2 步：阅读特定消息（自动标记为已读）
read-aimaestro-message.sh msg-1234...

# 第 3 步：再次检查 - 该消息现在已从未读中消失
check-aimaestro-messages.sh
# 输出："📭 无未读消息"

⚠️ 临界：什么是“你的收件箱”：

  • YOU = 在这个 tmux 会话中运行的 AI 代理
  • YOUR inbox = ~/.aimaestro/messages/inbox/YOUR-AGENT-ID/（或代理名称作为回退）
  • 你的收件箱中的消息 = 其他代理发送给你的消息
  • 不是操作员的消息，不是其他代理的私人消息

重要： 这些命令只检查你的代理的收件箱。它们自动：

  1. 检测你当前的代理 ID 或代理名称
  2. 从 ~/.aimaestro/messages/inbox/YOUR-AGENT-ID/ 读取
  3. 显示其他代理发送给你的消息
  4. 不访问任何人的收件箱

1. 检查你的收件箱是否有未读消息（推荐）

命令：

check-aimaestro-messages.sh [--mark-read]

它的作用：

  • 仅显示你的收件箱中的未读消息（发送给你的代理的消息）
  • 自动检测你的代理会话
  • 显示：优先级指示器、发送者、主题、预览、时间戳
  • 可选的 --mark-read 标志在查看后将所有消息标记为已读
  • 这是推荐的方式来检查消息 - 避免重新阅读旧消息

示例：

# 检查未读消息而不标记为已读
check-aimaestro-messages.sh

# 检查并标记所有为已读
check-aimaestro-messages.sh --mark-read

输出格式：

📬 你有 3 条未读消息
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[msg-167...] 🔴 来自：backend-architect | 2025-10-29 13:45
    主题：API endpoint ready
    预览：The POST /api/auth/login endpoint is now...

[msg-168...] 🔵 来自：frontend-dev | 2025-10-29 14:20
    主题：Need help with styling
    预览：Can you review the CSS for the navigation...

2. 阅读特定消息并标记为已读

命令：

read-aimaestro-message.sh <message-id> [--no-mark-read]

它的作用：

  • 检索并显示完整消息内容
  • 自动将消息标记为已读（除非使用 --no-mark-read 标志）
  • 显示所有消息详细信息：内容、上下文、转发信息
  • 适合在检查列表后阅读特定消息

示例：

# 阅读消息（自动标记为已读）
read-aimaestro-message.sh msg-1234567890-abc

# 偷看消息而不标记为已读
read-aimaestro-message.sh msg-1234567890-abc --no-mark-read

输出格式：

═══════════════════════════════════════════════════════════════
📧 消息：API endpoint ready
═════════════════════════════════════════════════════════════

来自：     backend-architect
至：        frontend-dev
日期：     2025-10-29 13:45:00
优先级：  🔴 紧急
类型：     响应

───────────────────────────────────────────────────────────────

The POST /api/auth/login endpoint is now deployed and ready...

───────────────────────────────────────────────────────────────
📎 上下文：
{
  "endpoint": "/api/auth/login"
}

✅ 消息标记为已读
═════════════════════════════════════════════════════════════

3. 代理启动时自动显示（遗留 - 手动不要使用）

命令：

check-and-show-messages.sh

它的作用：

  • 当你附加到 tmux 会话时自动运行
  • 显示未读消息的摘要
  • 不要手动运行这个命令 - 它仅用于自动显示
  • 手动检查时，使用 check-aimaestro-messages.sh 代替

为什么不手动使用这个：

  • 它设计为自动显示（在 tmux attach 上运行）
  • 输出格式优化为快速浏览，不适合交互式阅读
  • 使用上面的新命令（#1 和 #2）以获得更好的体验

输出格式：

消息：msg_1234567890_abcde
来自： backend-architect          ← 另一个代理发送此消息给**你**
至： frontend-dev                 ← 你的会话名称
主题：Need API endpoint
优先级：高
类型：请求
状态：未读
时间戳：2025-01-17 14:23:45
内容：Please implement POST /api/users with pagination...

4. 快速检查新消息计数（快速）

命令：

check-new-messages-arrived.sh

它的作用：

  • 显示你的收件箱中未读消息的计数
  • 自动检查你的会话收件箱
  • 快速检查，无需详细信息
  • 返回“无新消息”或“你有 X 条新消息”

示例：

check-new-messages-arrived.sh
# 输出："你有 3 条新消息"  ← 向**你**发送的消息

5. 直接从你的收件箱中阅读特定消息（直接文件访问 - 高级）

命令：

cat ~/.aimaestro/messages/inbox/$(tmux display-message -p '#S')/<message-id>.json | jq

它的作用：

  • 从你的收件箱中读取特定消息文件
  • $(tmux display-message -p '#S') = 你的会话名称（自动检测）
  • 使用 jq 进行漂亮格式化
  • 当你知道消息 ID 时很有用

目录结构：

~/.aimaestro/messages/
├── inbox/YOUR-SESSION-NAME/     # 向**你**发送的消息
│   └── msg_*.json
├── sent/YOUR-SESSION-NAME/      # 你发送的消息
│   └── msg_*.json
└── archived/YOUR-SESSION-NAME/  # 你归档的消息
    └── msg_*.json

示例：

# 获取你的会话名称
tmux display-message -p '#S'
# 输出：frontend-dev  ← 这是**你**

# 列出你的收件箱中的所有消息
ls ~/.aimaestro/messages/inbox/$(tmux display-message -p '#S')/

# 阅读发送给你的特定消息
cat ~/.aimaestro/messages/inbox/$(tmux display-message -p '#S')/msg_1234567890_abcde.json | jq

4. 通过 API 标记消息为已读

命令：

# 获取当前会话名称
SESSION_NAME=$(tmux display-message -p '#S')

# 标记消息为已读
curl -X PATCH "http://localhost:23000/api/messages?agent=$SESSION_NAME&id=<message-id>&action=read" \
  -H 'Content-Type: application/json'

第二部分：发送消息（给其他代理）

⚠️ 临界：什么是“发送消息”：

  • 操作员告诉你向另一个代理发送消息
  • 不是向操作员发送消息
  • 消息发送到另一个代理的收件箱
  • 目标 = 另一个代理（通过他们的 tmux 会话名称识别）

5. 文件基础消息（持久性，结构化）

用于详细、非紧急的通信，需要其他代理以后参考。

命令：

send-aimaestro-message.sh <to_agent[@host]> <subject> <message> [priority] [type]

参数：

  • to_agent[@host]（必需） - 目标代理，可选主机：
    • backend-api - 在同一主机上发送给代理（本地）
    • backend-api@mac-mini - 发送到远程主机“mac-mini”上的代理
    • backend-api@local - 明确发送给本地代理
  • subject（必需） - 简短的主题行
  • message（必需） - 发送给其他代理的消息内容
  • priority（可选） - 低 | 正常 | 高 | 紧急（默认：正常）
  • type（可选） - 请求 | 响应 | 通知 | 更新（默认：请求）

示例：

# 简单请求（本地代理）
send-aimaestro-message.sh backend-architect "Need API endpoint" "Please implement POST /api/users with pagination"

# 跨主机消息（远程机器上的代理）
send-aimaestro-message.sh crm-api@mac-mini "Customer data sync" "Please sync customer records from CRM" high request

# 紧急通知（本地）
send-aimaestro-message.sh frontend-dev "Production issue" "API returning 500 errors" urgent notification

# 响应请求
send-aimaestro-message.sh orchestrator "Re: Task complete" "User dashboard finished at components/Dashboard.tsx" normal response

# 进度更新
send-aimaestro-message.sh project-lead "Payment integration: 60% done" "Stripe API integrated. Working on webhooks. ETA: 2 hours." normal update

第 2.5 部分：跨主机消息

AI Maestro 支持向在不同机器（主机）上运行的代理发送消息。这使得跨基础设施的分布式代理工作流程成为可能。

主机配置

主机在 ~/.aimaestro/hosts.json 中配置：

{
  "hosts": [
    {
      "id": "local",
      "name": "macbook-pro",
      "url": "http://localhost:23000",
      "type": "local",
      "enabled": true
    },
    {
      "id": "mac-mini",
      "name": "mac-mini-server",
      "url": "http://100.80.12.6:23000",
      "type": "remote",
      "enabled": true
    }
  ]
}

在远程主机上寻址代理

使用 agent@host 格式向远程代理发送消息：

# 发送给主机“mac-mini”上的代理“crm-api”
send-aimaestro-message.sh crm-api@mac-mini "Sync request" "Please sync customer data"

# 发送给主机“cloud-server”上的代理“data-processor”
send-aimaestro-message.sh data-processor@cloud-server "Process batch" "Run nightly ETL" high request

跨主机消息的工作方式

  1. 解析目的地：脚本解析 agent@host 格式
  2. 解析主机 URL：从 ~/.aimaestro/hosts.json 查找主机 URL
  3. 解析代理：查询远程主机的 API 以验证代理是否存在
  4. 直接发送：将消息 POST 到远程主机的 /api/messages 端点
  5. 本地副本：在发送者的已发送文件夹中保存副本

带有主机的消息显示

当查看消息时，发送者信息包括他们的主机：

来自： backend-api@macbook-pro
至： crm-api@mac-mini
主题：数据同步完成

跨主机消息的故障排除

找不到主机：

# 列出可用主机
source ~/.local/share/aimaestro/shell-helpers/common.sh
list_hosts

远程主机无法访问：

  • 检查 ~/.aimaestro/hosts.json 中的主机 URL
  • 验证网络连接：curl http://<host-url>/api/sessions
  • 确保 AI Maestro 在远程主机上运行

远程主机上的代理未找到：

  • 验证远程上的代理存在：curl http://<host-url>/api/agents
  • 检查代理别名拼写

6. 即时通知（实时，短暂）

用于需要立即从其他代理那里引起注意的紧急警报。

命令：

send-tmux-message.sh <target_session> <message> [method]

参数：

  • target_session（必需） - 目标代理的名称（另一个代理，不是操作员）
  • message（必需） - 发送到其他代理的警报文本
  • method（可选） - display | inject | echo（默认：display）

方法：

  • display - 弹出通知（不干扰，自动消失）
  • inject - 注入到终端历史记录（可见但中断）
  • echo - 格式化输出（最可见，最干扰）

示例：

# 快速警报（弹出）
send-tmux-message.sh backend-architect "Check your inbox!"

# 紧急可见警报
send-tmux-message.sh frontend-dev "Build failed! Check logs" inject

# 严重格式化警报
send-tmu