Skip to content

LeoYeAI/agent-master-skills / skills/agent-comm-hub

agent-comm-hub

Flagged

多智能体协同通信基础设施——基于 MCP+SSE 的实时消息、任务调度、记忆共享与进化引擎。支持 WorkBuddy、Hermes、QClaw 及任意 MCP 兼容 Agent 接入。53 个 MCP 工具、4 级权限、零外部依赖 Python SDK。触发词:agent通信、智能体通信、hub通信、多智能体、跨agent通信、任务调度、assign_task、send_message、hermes通信、workbuddy通信、agent hub、通信hub、mcp通信、记忆共享、进化引擎、策略共享、经验分享、共享记忆,共同进化

FileKindSize
.clawhub/origin.jsonconfig146 B
API_REFERENCE.mdmarkdown18.4 KB
HERMES-SETUP.mdmarkdown5.5 KB
README.mdmarkdown8.8 KB
SKILL.mdskill md16.4 KB
_meta.jsonconfig133 B
client-sdk/agent-client.d.tsscript11.6 KB
client-sdk/agent-client.jsscript28.6 KB
client-sdk/agent-client.tsscript29.8 KB
client-sdk/hermes-integration.d.tsscript785 B
client-sdk/hermes-integration.jsscript6.3 KB
client-sdk/hermes-integration.tsscript6.1 KB
client-sdk/hub_client.pyscript50.8 KB
client-sdk/workbuddy-integration.d.tsscript11 B
client-sdk/workbuddy-integration.jsscript4.3 KB
client-sdk/workbuddy-integration.tsscript4.2 KB
deploy/docker-compose.ymlconfig2.0 KB
deploy/grafana/dashboard.jsonconfig16.4 KB
deploy/grafana/provisioning/dashboards/dashboards.ymlconfig258 B
deploy/grafana/provisioning/datasources/prometheus.ymlconfig186 B
deploy/prometheus.ymlconfig408 B
docs/advanced-orchestration-guide.mdmarkdown11.8 KB
docs/evolution-engine-guide.mdmarkdown16.6 KB
docs/hermes-integration-guide.mdmarkdown22.3 KB
package-lock.jsonmanifest139.0 KB
package.jsonmanifest861 B
scripts/hub_task_runner.pyscript6.0 KB
scripts/hub_watcher.pyscript13.9 KB
scripts/install.shscript549 B
scripts/migrate_evolution_db.pyscript6.5 KB
scripts/migrate_from_agent.jsscript2.5 KB
scripts/wb_task_trigger.pyscript2.2 KB
src/db.d.tsscript3.7 KB
src/db.jsscript34.0 KB
src/db.tsscript37.4 KB
src/dedup.d.tsscript2.4 KB
src/dedup.jsscript8.5 KB
src/dedup.tsscript8.7 KB
src/errors.tsscript3.4 KB
src/evolution.d.tsscript6.6 KB
src/evolution.jsscript26.4 KB
src/evolution.tsscript31.0 KB
src/identity.d.tsscript3.4 KB
src/identity.jsscript15.9 KB
src/identity.tsscript17.1 KB
src/logger.d.tsscript1.1 KB
src/logger.jsscript2.8 KB
src/logger.tsscript3.5 KB
src/memory.d.tsscript2.1 KB
src/memory.jsscript13.0 KB
src/memory.tsscript14.3 KB
src/metrics.d.tsscript1.8 KB
src/metrics.jsscript8.4 KB
src/metrics.tsscript9.1 KB
src/orchestrator.d.tsscript6.1 KB
src/orchestrator.jsscript30.4 KB
src/orchestrator.tsscript33.4 KB
src/repo/interfaces.d.tsscript3.6 KB
src/repo/interfaces.jsscript49 B
src/repo/interfaces.tsscript4.2 KB
src/repo/sqlite-impl.d.tsscript225 B
src/repo/sqlite-impl.jsscript7.7 KB
src/repo/sqlite-impl.tsscript8.8 KB
src/repo/types.d.tsscript1021 B
src/repo/types.jsscript116 B
src/repo/types.tsscript1.6 KB
src/security.d.tsscript3.7 KB
src/security.jsscript15.0 KB
src/security.tsscript16.4 KB
src/server.d.tsscript11 B
src/server.jsscript24.7 KB
src/server.tsscript24.7 KB
src/sse.d.tsscript1.6 KB
src/sse.jsscript3.3 KB
src/sse.tsscript3.6 KB
src/stdio.d.tsscript11 B
src/stdio.jsscript1.7 KB
src/stdio.tsscript1.6 KB
src/tokenizer.d.tsscript1.3 KB
src/tokenizer.jsscript3.4 KB
src/tokenizer.tsscript3.2 KB
src/tools.d.tsscript474 B
src/tools.jsscript1.1 KB
src/tools.tsscript1.3 KB
src/tools/consumed.d.tsscript361 B
src/tools/consumed.jsscript5.5 KB
src/tools/consumed.tsscript5.3 KB
src/tools/evolution.d.tsscript660 B
src/tools/evolution.jsscript19.3 KB
src/tools/evolution.tsscript17.6 KB
src/tools/file.d.tsscript348 B
src/tools/file.jsscript7.1 KB
src/tools/file.tsscript6.5 KB
src/tools/identity.d.tsscript438 B
src/tools/identity.jsscript9.8 KB
src/tools/identity.tsscript9.3 KB
src/tools/memory.d.tsscript410 B
src/tools/memory.jsscript11.9 KB
src/tools/memory.tsscript10.8 KB
src/tools/message.d.tsscript467 B
src/tools/message.jsscript17.2 KB
src/tools/message.tsscript15.8 KB
src/tools/orchestrator.d.tsscript746 B
src/tools/orchestrator.jsscript27.8 KB
src/tools/orchestrator.tsscript24.3 KB
src/tools/security.d.tsscript386 B
src/tools/security.jsscript9.0 KB
src/tools/security.tsscript7.8 KB
src/types.tsscript5.9 KB
src/utils.d.tsscript421 B
src/utils.jsscript1.3 KB
src/utils.tsscript3.0 KB
tsconfig.jsonconfig337 B
vitest.config.tsscript1.2 KB

src/tools/message.ts

View on GitHub
/**
 * message.ts — MCP 工具:消息通信模块
 * 包含:send_message, broadcast_message, acknowledge_message, batch_acknowledge_messages, search_messages
 * 来源:tools.ts 第 324-426 + 581-659 + 878-931 + 2195-2251 + 2323-2420 行
 */
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
import { randomUUID } from "crypto";
import { type Message, db } from "../db.js";
import { messageRepo } from "../repo/sqlite-impl.js";
import { pushToAgent } from "../sse.js";
import { auditLog, type AuthContext } from "../security.js";
import { resolveAgentId } from "../identity.js";
import { dedupMessage, validateMessageBody } from "../dedup.js";
import { logError } from "../logger.js";
import { withRetry, requireAuth, mcpError } from "../utils.js";
import { getErrorMessage } from "../types.js";

export function registerMessageTools(server: McpServer, authContext?: AuthContext): void {

  // ────────────────────────────────────────────────────
  // Tool 5: send_message (原有,添加权限检查)
  // ────────────────────────────────────────────────────
  server.tool(
    "send_message",
    "向另一个 Agent 发送即时消息。对方在线时实时送达(<50ms),离线时持久化存储,上线后自动补发。",
    {
      from:     z.string().describe("发送方 Agent ID,如 workbuddy 或 hermes"),
      to:       z.string().describe("接收方 Agent ID"),
      content:  z.string().describe("消息正文,支持 Markdown"),
      type:     z.enum(["message", "task_assign", "task_update", "ack"])
                  .default("message")
                  .describe("消息类型"),
      metadata: z.record(z.unknown()).optional()
                  .describe("附加结构化数据,如 taskId、priority 等"),
    },
    async ({ from, to, content, type, metadata }) => {
      const ctx = requireAuth(authContext, "send_message");

      // ── from_agent 格式规范化(Phase 2.1) ────────────────
      const resolvedFrom = resolveAgentId(from);
      if (!resolvedFrom) {
        return {
          content: [{
            type: "text",
            text: JSON.stringify({
              success: false,
              error: `无效的发件人标识: '${from}'。请使用完整的 agent_id 或已注册的 agent 名称。`,
              code: "INVALID_FROM_AGENT",
            }),
          }],
          isError: true,
        };
      }

      const resolvedTo = resolveAgentId(to);
      if (!resolvedTo) {
        return {
          content: [{
            type: "text",
            text: JSON.stringify({
              success: false,
              error: `无效的收件人标识: '${to}'。请使用完整的 agent_id 或已注册的 agent 名称。`,
              code: "INVALID_TO_AGENT",
            }),
          }],
          isError: true,
        };
      }

      // 消息去重 + 完整性校验
      const dedupResult = dedupMessage(from, to, content);
      if (!dedupResult.ok) {
        return {
          content: [{
            type: "text",
            text: JSON.stringify({
              success: false,
              error: dedupResult.reason,
              code: "DEDUP_REJECTED",
            }),
          }],
        };
      }

      const msg: Message = {
        id:         randomUUID(),
        from_agent: resolvedFrom,
        to_agent:   resolvedTo,
        content,
        type,
        metadata:   metadata ? JSON.stringify(metadata) : null,
        status:     "unread",
        created_at: Date.now(),
      };

      messageRepo.insert(msg);

      // 审计日志
      auditLog("tool_send_message", ctx.agentId, resolvedTo,
        `msg_id=${msg.id}, hash=${dedupResult.msgHash.slice(0, 12)}, nonce=${dedupResult.nonce}`);

      const delivered = pushToAgent(resolvedTo, {
        event:   "new_message",
        message: { ...msg, metadata, msg_hash: dedupResult.msgHash, nonce: dedupResult.nonce },
      });

      if (delivered) messageRepo.markDelivered(msg.id);

      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            success:           true,
            messageId:         msg.id,
            msg_hash:          dedupResult.msgHash,
            nonce:             dedupResult.nonce,
            delivered_realtime: delivered,
            note: delivered
              ? `✅ ${resolvedTo} 在线,已实时送达`
              : `📦 ${resolvedTo} 离线,消息已存储,上线后自动补发`,
          }, null, 2),
        }],
      };
    }
  );

  // ────────────────────────────────────────────────────
  // Tool 9: broadcast_message (原有,添加权限检查)
  // ────────────────────────────────────────────────────
  server.tool(
    "broadcast_message",
    "向多个 Agent 广播消息,适用于任务协调、状态同步、紧急通知。",
    {
      from:      z.string(),
      agent_ids: z.array(z.string()).describe("接收方 Agent ID 列表"),
      content:   z.string(),
      metadata:  z.record(z.unknown()).optional(),
    },
    async ({ from, agent_ids, content, metadata }) => {
      const ctx = requireAuth(authContext, "broadcast_message");

      // 消息体校验
      const validation = validateMessageBody(content);
      if (!validation.safe) {
        return {
          content: [{
            type: "text",
            text: JSON.stringify({
              success: false,
              error: validation.reason,
              code: "VALIDATION_REJECTED",
            }),
          }],
        };
      }

      const results: Record<string, boolean> = {};
      const errors: string[] = [];
      let deliveredCount = 0;

      for (const to of agent_ids) {
        // 每个接收者独立去重
        const dedupResult = dedupMessage(from, to, content);
        if (!dedupResult.ok) {
          errors.push(`${to}: ${dedupResult.reason}`);
          results[to] = false;
          continue;
        }

        const msg: Message = {
          id:         randomUUID(),
          from_agent: from,
          to_agent:   to,
          content,
          type:       "message",
          metadata:   metadata ? JSON.stringify(metadata) : null,
          status:     "unread",
          created_at: Date.now(),
        };
        messageRepo.insert(msg);
        const delivered = pushToAgent(to, {
          event: "new_message",
          message: { ...msg, metadata, msg_hash: dedupResult.msgHash, nonce: dedupResult.nonce },
        });
        if (delivered) {
          messageRepo.markDelivered(msg.id);
          deliveredCount++;
        }
        results[to] = delivered;
      }

      auditLog("tool_broadcast_message", ctx.agentId, agent_ids.join(","),
        `total=${agent_ids.length}, delivered=${deliveredCount}, errors=${errors.length}`);

      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            broadcast:       true,
            delivery_status: results,
            delivered_count: deliveredCount,
            duplicate_count: errors.length,
            errors:          errors.length > 0 ? errors : undefined,
          }, null, 2),
        }],
      };
    }
  );

  // ────────────────────────────────────────────────────
  // Tool 11: acknowledge_message (原有,添加权限检查)
  // ────────────────────────────────────────────────────
  server.tool(
    "acknowledge_message",
    "标记消息为已处理(acknowledged)。调用此工具后该消息不会再出现在未处理消息列表中。Hermes 处理完 WorkBuddy 发来的消息并回复后,必须调用此工具。",
    {
      message_id: z.string().describe("消息 ID"),
      agent_id:   z.string().describe("确认方 Agent ID,如 hermes"),
    },
    async ({ message_id, agent_id }) => {
      requireAuth(authContext, "acknowledge_message");

      try {
        const msg = await withRetry(
          () => messageRepo.getById(message_id),
          "acknowledge_message:lookup"
        );
        if (!msg) {
          return {
            content: [{
              type: "text",
              text: JSON.stringify({ error: `Message ${message_id} not found`, suggestion: "请检查 message_id 是否正确" }),
            }],
          };
        }
        await withRetry(
          () => messageRepo.markAcknowledged(message_id),
          "acknowledge_message:update"
        );
        return {
          content: [{
            type: "text",
            text: JSON.stringify({
              success:    true,
              message_id,
              agent_id,
              status:     "acknowledged",
              note:       "此消息已标记为已处理,不会重复出现在待处理列表中",
            }, null, 2),
          }],
        };
      } catch (err: unknown) {
        logError("acknowledge_message_error", err);
        return {
          content: [{
            type: "text",
            text: JSON.stringify({
              success: false,
              error: getErrorMessage(err),
              fallback: "标记失败,消息仍为当前状态,请稍后重试",
            }),
          }],
        };
      }
    }
  );

  // ────────────────────────────────────────────────────
  // Tool S1: search_messages — member 及以上
  // ────────────────────────────────────────────────────
  server.tool(
    "search_messages",
    "全文搜索消息内容。支持按 Agent ID 筛选。使用 SQL LIKE 模糊匹配(暂无 FTS5 索引)。",
    {
      query:    z.string().describe("搜索关键词"),
      agent_id: z.string().optional().describe("限定 Agent ID(按发送方或接收方过滤)"),
      limit:    z.number().min(1).max(50).optional().default(10).describe("最大返回数量"),
    },
    async ({ query, agent_id, limit }) => {
      const ctx = requireAuth(authContext, "search_messages");

      try {
        const conditions: string[] = ["content LIKE ?"];
        const params: (string | number)[] = [`%${query}%`];

        if (agent_id) {
          conditions.push("(from_agent = ? OR to_agent = ?)");
          params.push(agent_id, agent_id);
        }

        const where = conditions.join(" AND ");
        const messages = db.prepare(
          `SELECT id, from_agent, to_agent, content, type, status, created_at
           FROM messages WHERE ${where}
           ORDER BY created_at DESC LIMIT ?`
        ).all(...params, limit) as any[];

        return {
          content: [{
            type: "text",
            text: JSON.stringify({
              query,
              agent_id: agent_id ?? null,
              messages: messages.map(m => ({
                id:         m.id,
                from_agent: m.from_agent,
                to_agent:   m.to_agent,
                content:    m.content,
                type:       m.type,
                status:     m.status,
                created_at: m.created_at,
              })),
              count:      messages.length,
              queried_by: ctx.agentId,
            }, null, 2),
          }],
        };
      } catch (err: unknown) {
        return mcpError(err, "search_messages");
      }
    }
  );

  // ────────────────────────────────────────────────────
  // Tool: batch_acknowledge_messages (Phase 1.3)
  // 批量确认消息
  // ────────────────────────────────────────────────────
  server.tool(
    "batch_acknowledge_messages",
    "批量确认消息为已处理。可按 agent_id 和时间范围筛选,将匹配的未确认消息全部标记为 acknowledged。用于清理消息积压。",
    {
      agent_id: z.string().describe("目标 Agent ID(消息接收方),即要清理谁的未读消息"),
      from_agent: z.string().optional().describe("发送方 Agent ID 过滤(可选),只确认来自特定发送方的消息"),
      before: z.number().optional().describe("时间戳上限(毫秒),只确认此时间之前的消息"),
      after: z.number().optional().describe("时间戳下限(毫秒),只确认此时间之后的消息"),
      status: z.enum(["unread", "delivered"]).optional().default("unread").describe("要确认的消息状态,默认 unread"),
      limit: z.number().int().min(1).max(500).default(100).describe("最多确认的消息数量,默认 100,上限 500"),
    },
    async ({ agent_id, from_agent, before, after, status, limit }) => {
      const ctx = requireAuth(authContext, "batch_acknowledge_messages");

      try {
        // 构建查询条件
        const conditions: string[] = ["to_agent = ?"];
        const params: (string | number)[] = [agent_id];

        if (from_agent) {
          conditions.push("from_agent = ?");
          params.push(from_agent);
        }
        if (before !== undefined) {
          conditions.push("created_at < ?");
          params.push(before);
        }
        if (after !== undefined) {
          conditions.push("created_at > ?");
          params.push(after);
        }

        // 只确认非 acknowledged 状态的消息
        if (status === "delivered") {
          conditions.push("status = 'delivered'");
        } else {
          conditions.push("status IN ('unread', 'delivered')");
        }

        const whereClause = conditions.join(" AND ");

        // 先查询匹配的消息数量
        const countResult = db.prepare(
          `SELECT COUNT(*) as cnt FROM messages WHERE ${whereClause}`
        ).get(...params) as any;

        const totalCount = countResult?.cnt ?? 0;
        const actualLimit = Math.min(limit, totalCount);

        if (actualLimit === 0) {
          return {
            content: [{
              type: "text",
              text: JSON.stringify({
                success: true,
                agent_id,
                acknowledged_count: 0,
                total_matching: 0,
                filters: { from_agent, before, after, status },
                note: "没有匹配的未确认消息",
              }, null, 2),
            }],
          };
        }

        // 批量更新:使用子查询限制更新行数
        const updateResult = db.prepare(
          `UPDATE messages SET status = 'acknowledged' WHERE ${whereClause} AND rowid IN (
            SELECT rowid FROM messages WHERE ${whereClause} LIMIT ?
          )`
        ).run(...params, ...params, actualLimit);

        return {
          content: [{
            type: "text",
            text: JSON.stringify({
              success: true,
              agent_id,
              acknowledged_count: updateResult.changes,
              total_matching: totalCount,
              filters: { from_agent, before, after, status },
              note: updateResult.changes < totalCount
                ? `已确认 ${updateResult.changes} 条(达到 limit ${limit} 上限),可再次调用继续清理`
                : `全部 ${totalCount} 条匹配消息已确认`,
            }, null, 2),
          }],
        };
      } catch (err: unknown) {
        logError("batch_acknowledge_messages_error", err);
        return mcpError(err, "batch_acknowledge_messages");
      }
    }
  );

}
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall