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

client-sdk/hub_client.py

View on GitHub
#!/usr/bin/env python3
"""
hub_client.py — Agent Synergy Hub Python SDK (Phase 2)

功能:
  1. Agent 注册(邀请码)+ Token 管理
  2. MCP 工具调用封装(HTTP POST /mcp,含 initialize 握手)
  3. SSE 长连接订阅(自动重连 + 客户端去重)
  4. 记忆存储/召回(支持溯源字段 source_agent_id/source_task_id)
  5. 事件路由(new_message / task_assigned / task_updated)
  6. 信任分管理(set_trust_score,admin only)
  7. Agent 查询(支持 role/capability 筛选)

用法:
  from hub_client import SynergyHubClient

  hub = SynergyHubClient(hub_url="http://localhost:3100")

  # 注册
  result = hub.register(invite_code="abc12345", name="my_agent")
  hub.set_token(result["api_token"])

  # 心跳
  hub.heartbeat()

  # 消息
  hub.send_message(to="other_agent", content="Hello!")

  # 记忆
  hub.store_memory(content="重要信息", scope="collective")

  # SSE 订阅
  hub.on_message = lambda msg: print(f"收到: {msg}")
  hub.connect_sse()  # 阻塞

设计原则:
  - 零外部依赖(仅 stdlib)
  - MCP Streamable HTTP Transport 无状态模式
  - 客户端去重(_hub_event_id)
  - SSE 指数退避重连
"""

from __future__ import annotations

import json
import logging
import re
import threading
import time
import uuid
from typing import Any, Callable, Dict, List, Optional
from urllib.request import Request, urlopen
from urllib.error import HTTPError, URLError
import http.client
import socket

# ─── 日志 ──────────────────────────────────────────────────────────

logger = logging.getLogger("hub_client")

# ─── 类型 ──────────────────────────────────────────────────────────

MessageHandler = Callable[[Dict[str, Any]], None]
TaskHandler = Callable[[Dict[str, Any]], None]
TaskUpdateHandler = Callable[[Dict[str, Any]], None]


class HubError(Exception):
    """Hub SDK 错误基类"""
    def __init__(self, message: str, code: int = 0):
        super().__init__(message)
        self.code = code


class AuthError(HubError):
    """认证错误 (401/403)"""
    pass


class RateLimitError(HubError):
    """速率限制 (429)"""
    pass


class ToolError(HubError):
    """MCP 工具调用错误"""
    pass


# ─── SynergyHubClient ──────────────────────────────────────────────

class SynergyHubClient:
    """
    Agent Synergy Hub 客户端

    覆盖 MCP 工具调用 + SSE 事件订阅 + 客户端去重
    """

    def __init__(
        self,
        hub_url: str = "http://localhost:3100",
        agent_id: Optional[str] = None,
        token: Optional[str] = None,
        reconnect_base: float = 2.0,
        reconnect_max: float = 60.0,
        sse_timeout: int = 90,
        mcp_timeout: int = 15,
    ):
        self.hub_url = hub_url.rstrip("/")
        self.agent_id = agent_id
        self._token = token
        self._role: Optional[str] = None

        # SSE 配置
        self._reconnect_base = reconnect_base
        self._reconnect_max = reconnect_max
        self._sse_timeout = sse_timeout
        self._mcp_timeout = mcp_timeout

        # SSE 状态
        self._sse_running = False
        self._sse_thread: Optional[threading.Thread] = None
        self._reconnect_delay = reconnect_base

        # 客户端去重(_hub_event_id)
        self._seen_event_ids: set[int] = set()
        self._seen_event_ids_lock = threading.Lock()
        self._seen_event_ids_ordered: list[int] = []  # 有序列表,用于按插入顺序清理
        self._dedup_max_size = 10000  # 防止内存泄漏

        # SSE 断线重连:Last-Event-ID 跟踪
        self._last_event_id: Optional[str] = None
        self._last_event_id_lock = threading.Lock()

        # 事件回调
        self.on_message: Optional[MessageHandler] = None
        self.on_task_assigned: Optional[TaskHandler] = None
        self.on_task_updated: Optional[TaskUpdateHandler] = None

        # MCP 连接状态(无状态模式,无需 session)
        self._initialized = False
        self._init_lock = threading.Lock()

    # ── 属性 ─────────────────────────────────────────────

    @property
    def token(self) -> Optional[str]:
        return self._token

    @property
    def role(self) -> Optional[str]:
        return self._role

    @property
    def is_connected(self) -> bool:
        return self._sse_running

    # ── Token 管理 ───────────────────────────────────────

    def set_token(self, token: str) -> None:
        """设置 API Token(注册后调用)"""
        self._token = token
        self._initialized = False  # 重新握手

    # ── 底层 HTTP ────────────────────────────────────────

    def _request(
        self,
        method: str,
        path: str,
        data: Optional[dict] = None,
        headers: Optional[dict] = None,
        timeout: Optional[int] = None,
    ) -> bytes:
        """底层 HTTP 请求"""
        url = f"{self.hub_url}{path}"
        req_headers = headers or {}

        if data is not None:
            body = json.dumps(data, ensure_ascii=False).encode("utf-8")
            req_headers.setdefault("Content-Type", "application/json")
        else:
            body = None

        req = Request(url, data=body, method=method, headers=req_headers)
        t = timeout or self._mcp_timeout

        try:
            with urlopen(req, timeout=t) as resp:
                return resp.read()
        except HTTPError as e:
            if e.code in (401, 403):
                raise AuthError(f"Authentication failed: {e.code}", e.code)
            if e.code == 429:
                raise RateLimitError("Rate limit exceeded", 429)
            raise HubError(f"HTTP {e.code}: {e.reason}", e.code)
        except URLError as e:
            raise HubError(f"Connection error: {e.reason}")
        except Exception as e:
            raise HubError(f"Request failed: {e}")

    def _auth_headers(self) -> dict:
        """构建认证请求头"""
        h = {
            "Content-Type": "application/json",
            "Accept": "application/json, text/event-stream",
        }
        if self._token:
            h["Authorization"] = f"Bearer {self._token}"
        return h

    # ── MCP 协议 ─────────────────────────────────────────

    def _ensure_initialized(self) -> None:
        """确保 MCP 握手完成(线程安全)"""
        if self._initialized:
            return

        with self._init_lock:
            if self._initialized:
                return
            self._do_initialize()

    def _do_initialize(self) -> None:
        """执行 MCP initialize 握手"""
        # Step 1: initialize
        init_payload = {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "initialize",
            "params": {
                "protocolVersion": "2025-03-26",
                "capabilities": {},
                "clientInfo": {
                    "name": f"hub-client-python-{self.agent_id or 'unknown'}",
                    "version": "1.0.0",
                },
            },
        }

        resp_body = self._raw_mcp(init_payload)

        if "error" in resp_body:
            raise HubError(f"MCP initialize failed: {resp_body['error']}")

        logger.debug("MCP initialized (stateless)")

        # Step 2: initialized 通知
        notif = {
            "jsonrpc": "2.0",
            "method": "notifications/initialized",
        }
        self._raw_mcp(notif)

        self._initialized = True

    def _raw_mcp(self, payload: dict) -> dict:
        """
        底层 MCP POST 请求
        处理 SSE 格式响应(text/event-stream)和普通 JSON 响应
        """
        raw = self._request("POST", "/mcp", data=payload, headers=self._auth_headers())
        text = raw.decode("utf-8", errors="replace")

        # 尝试 SSE 格式解析
        for line in text.split("\n"):
            line = line.strip()
            if line.startswith("data: "):
                json_str = line[6:]
                try:
                    return json.loads(json_str)
                except json.JSONDecodeError:
                    continue

        # 尝试直接 JSON
        try:
            return json.loads(text)
        except json.JSONDecodeError:
            return {"raw": text}

    def _call_tool(self, tool_name: str, args: dict) -> Any:
        """
        调用 MCP 工具
        自动处理 initialize 握手、响应解析、错误检查
        """
        self._ensure_initialized()

        payload = {
            "jsonrpc": "2.0",
            "id": uuid.uuid4().hex,
            "method": "tools/call",
            "params": {"name": tool_name, "arguments": args},
        }

        resp = self._raw_mcp(payload)

        # 错误处理
        if "error" in resp:
            err = resp["error"]
            msg = err.get("message", str(err))
            code = err.get("code", -1)
            raise ToolError(f"MCP tool [{tool_name}] error: {msg}", code)

        # 从 result.content[0].text 提取结果
        result = resp.get("result")
        if isinstance(result, dict):
            content = result.get("content", [])
            if content and isinstance(content, list) and len(content) > 0:
                item = content[0]
                # 如果 content item 是错误类型
                if isinstance(item, dict) and item.get("type") == "text":
                    text = item.get("text", "")
                    if text:
                        # 检查是否是错误消息(MCP tool handler 抛出的 Error)
                        error_prefixes = ("Error:", "error:", "Permission denied", "Authentication required", "MCP error")
                        if any(text.startswith(p) for p in error_prefixes):
                            raise ToolError(f"MCP tool [{tool_name}] error: {text}")
                        try:
                            return json.loads(text)
                        except json.JSONDecodeError:
                            return text
            return result

        # resp 本身可能是直接的 JSON 结果(某些边缘情况)
        if isinstance(resp, dict) and "raw" in resp and "result" not in resp:
            raw_text = resp.get("raw", "")
            try:
                return json.loads(raw_text)
            except (json.JSONDecodeError, TypeError):
                return raw_text

        return resp

    # ═══════════════════════════════════════════════════════
    # 对外 API — 注册 / 心跳 / 查询
    # ═══════════════════════════════════════════════════════

    def register(self, invite_code: str, name: str, agent_id: Optional[str] = None) -> dict:
        """
        注册新 Agent

        Args:
            invite_code: 管理员生成的邀请码
            name: Agent 显示名称
            agent_id: 可选的自定义 Agent ID(不传则自动生成)

        Returns:
            {"success": true, "agent_id": "...", "api_token": "...", "role": "member"}
        """
        args: dict = {"invite_code": invite_code, "name": name}
        if agent_id:
            args["agent_id"] = agent_id

        result = self._call_tool("register_agent", args)

        if result.get("success"):
            self.agent_id = result.get("agent_id", self.agent_id)
            self.set_token(result.get("api_token", ""))
            self._role = result.get("role")
            logger.info(f"注册成功: {self.agent_id} (role={self._role})")

        return result

    def heartbeat(self) -> dict:
        """
        上报心跳

        Returns:
            {"success": true, "agent_id": "...", "status": "online"}
        """
        return self._call_tool("heartbeat", {"agent_id": self.agent_id})

    def query_agents(
        self,
        status: Optional[str] = None,
        role: Optional[str] = None,
        capability: Optional[str] = None,
    ) -> dict:
        """
        查询已注册 Agent 列表

        Args:
            status: 可选,筛选状态(online/offline/all)
            role: 可选,角色筛选(admin/member)
            capability: 可选,能力筛选

        Returns:
            {"agents": [...], "count": N}
            每个 agent 包含 trust_score 字段
        """
        args: dict = {}
        if status:
            args["status"] = status
        if role:
            args["role"] = role
        if capability:
            args["capability"] = capability
        return self._call_tool("query_agents", args)

    def set_trust_score(self, agent_id: str, delta: int) -> dict:
        """
        调整 Agent 信任分(admin only)

        Args:
            agent_id: 目标 Agent ID
            delta: 信任分增量(-100 到 +100)

        Returns:
            {"ok": true, "new_score": N} 或 {"ok": false, "error": "..."}
        """
        return self._call_tool("set_trust_score", {
            "agent_id": agent_id,
            "delta": delta,
        })

    def get_online_agents(self) -> List[str]:
        """
        获取在线 Agent ID 列表

        Returns:
            在线 Agent ID 列表
        """
        result = self._call_tool("get_online_agents", {})
        return result.get("online_agents", [])

    def revoke_token(self, token_id: str) -> dict:
        """
        吊销 Token(admin only)

        Args:
            token_id: 要吊销的 Token ID
        """
        return self._call_tool("revoke_token", {"token_id": token_id})

    # ═══════════════════════════════════════════════════════
    # 对外 API — 消息
    # ═══════════════════════════════════════════════════════

    def send_message(
        self,
        to: str,
        content: str,
        msg_type: str = "message",
        metadata: Optional[dict] = None,
    ) -> dict:
        """
        发送消息给另一个 Agent

        Args:
            to: 目标 Agent ID
            content: 消息内容
            msg_type: 消息类型(message/task_result/等)
            metadata: 可选的元数据

        Returns:
            {"success": true, "message_id": "..."}
        """
        args: dict = {
            "from": self.agent_id,
            "to": to,
            "content": content,
            "type": msg_type,
        }
        if metadata is not None:
            args["metadata"] = metadata
        return self._call_tool("send_message", args)

    def broadcast_message(
        self,
        agent_ids: List[str],
        content: str,
        metadata: Optional[dict] = None,
    ) -> dict:
        """
        广播消息给多个 Agent

        Args:
            agent_ids: 目标 Agent ID 列表
            content: 消息内容
            metadata: 可选元数据
        """
        args: dict = {
            "from": self.agent_id,
            "agent_ids": agent_ids,
            "content": content,
        }
        # 只在有值时传 metadata,避免 MCP schema 校验 null 为 object 报错
        if metadata is not None:
            args["metadata"] = metadata
        return self._call_tool("broadcast_message", args)

    def acknowledge_message(self, message_id: str) -> dict:
        """确认消息已收到"""
        return self._call_tool("acknowledge_message", {"message_id": message_id})

    # ═══════════════════════════════════════════════════════
    # 对外 API — 任务
    # ═══════════════════════════════════════════════════════

    def assign_task(
        self,
        to: str,
        description: str,
        context: Optional[str] = None,
        priority: str = "normal",
    ) -> dict:
        """
        分配任务给另一个 Agent

        Args:
            to: 目标 Agent ID
            description: 任务描述
            context: 可选上下文
            priority: 优先级(normal/high/low)
        """
        return self._call_tool("assign_task", {
            "from": self.agent_id,
            "to": to,
            "description": description,
            "context": context,
            "priority": priority,
        })

    def update_task_status(
        self,
        task_id: str,
        status: str,
        result: Optional[str] = None,
        progress: int = 0,
    ) -> dict:
        """
        更新任务状态

        Args:
            task_id: 任务 ID
            status: 状态(in_progress/completed/failed)
            result: 可选结果
            progress: 进度(0-100)
        """
        return self._call_tool("update_task_status", {
            "task_id": task_id,
            "agent_id": self.agent_id,
            "status": status,
            "result": result,
            "progress": progress,
        })

    def get_task_status(self, task_id: str) -> dict:
        """查询任务状态"""
        return self._call_tool("get_task_status", {"task_id": task_id})

    # ═══════════════════════════════════════════════════════
    # 对外 API — 记忆
    # ═══════════════════════════════════════════════════════

    def store_memory(
        self,
        content: str,
        title: Optional[str] = None,
        scope: str = "private",
        tags: Optional[List[str]] = None,
        source_task_id: Optional[str] = None,
    ) -> dict:
        """
        存储记忆

        Args:
            content: 记忆内容(最多 10000 字符)
            title: 可选标题
            scope: 可见范围(private/group/collective)
            tags: 可选标签列表
            source_task_id: 可选,关联任务 ID(用于溯源追踪)
              注意:source_agent_id 由服务端自动注入(collective/group 时)

        Returns:
            {"success": true, "memory_id": "...", "scope": "...",
             "source_agent_id": "...", "source_task_id": "..."}
        """
        args: dict = {"content": content, "scope": scope}
        if title:
            args["title"] = title
        if tags:
            args["tags"] = tags
        if source_task_id:
            args["source_task_id"] = source_task_id
        return self._call_tool("store_memory", args)

    def recall_memory(
        self,
        query: str,
        scope: str = "all",
        limit: int = 10,
    ) -> dict:
        """
        全文搜索召回记忆

        Args:
            query: 搜索关键词
            scope: 搜索范围(private/group/collective/all)
            limit: 最大返回数量

        Returns:
            {"results": [...], "count": N}
        """
        return self._call_tool("recall_memory", {
            "query": query,
            "scope": scope,
            "limit": limit,
        })

    def list_memories(
        self,
        scope: str = "all",
        limit: int = 20,
        offset: int = 0,
    ) -> dict:
        """
        列出可访问的记忆

        Args:
            scope: 筛选范围
            limit: 每页数量
            offset: 偏移量
        """
        return self._call_tool("list_memories", {
            "scope": scope,
            "limit": limit,
            "offset": offset,
        })

    def delete_memory(self, memory_id: str) -> dict:
        """删除记忆"""
        return self._call_tool("delete_memory", {"memory_id": memory_id})

    # ═══════════════════════════════════════════════════════
    # 对外 API — Evolution Engine(经验共享 + 策略传播)
    # ═══════════════════════════════════════════════════════

    def share_experience(
        self,
        title: str,
        content: str,
        tags: Optional[List[str]] = None,
        task_id: Optional[str] = None,
    ) -> dict:
        """
        分享经验(直接 approved,无需审批)

        Args:
            title: 经验标题(3-200 字符)
            content: 经验内容(10-5000 字符,Markdown)
            tags: 可选标签列表(最多 10 个)
            task_id: 可选,关联任务 ID

        Returns:
            {"success": true, "strategy_id": N, "status": "approved"}
        """
        args: dict = {"title": title, "content": content}
        if tags is not None:
            args["tags"] = tags
        if task_id:
            args["task_id"] = task_id
        return self._call_tool("share_experience", args)

    def propose_strategy(
        self,
        title: str,
        content: str,
        category: str = "workflow",
        task_id: Optional[str] = None,
    ) -> dict:
        """
        提议策略(需 admin 审批)

        Args:
            title: 策略标题(3-200 字符)
            content: 策略内容(10-5000 字符)
            category: 分类(workflow/fix/tool_config/prompt_template/other)
            task_id: 可选,关联任务 ID

        Returns:
            {"success": true, "strategy_id": N, "status": "pending"}
        """
        args: dict = {"title": title, "content": content, "category": category}
        if task_id:
            args["task_id"] = task_id
        return self._call_tool("propose_strategy", args)

    def list_strategies(
        self,
        status: Optional[str] = None,
        category: Optional[str] = None,
        proposer_id: Optional[str] = None,
        limit: int = 20,
    ) -> dict:
        """
        查询策略列表

        Args:
            status: 筛选状态(pending/approved/rejected/all)
            category: 筛选分类(experience/workflow/fix/tool_config/prompt_template/other/all)
            proposer_id: 筛选提议者
            limit: 最大返回数量(1-50)

        Returns:
            {"strategies": [...], "count": N}
        """
        args: dict = {"limit": limit}
        if status:
            args["status"] = status
        if category:
            args["category"] = category
        if proposer_id:
            args["proposer_id"] = proposer_id
        return self._call_tool("list_strategies", args)

    def search_strategies(
        self,
        query: str,
        category: Optional[str] = None,
        limit: int = 10,
    ) -> dict:
        """
        FTS5 全文搜索策略

        Args:
            query: 搜索关键词(2-200 字符)
            category: 可选分类筛选
            limit: 最大返回数量(1-20)

        Returns:
            {"results": [...], "count": N}
        """
        args: dict = {"query": query, "limit": limit}
        if category:
            args["category"] = category
        return self._call_tool("search_strategies", args)

    def apply_strategy(
        self,
        strategy_id: int,
        context: Optional[str] = None,
    ) -> dict:
        """
        采纳策略(记录到 strategy_applications,apply_count++)

        Args:
            strategy_id: 策略 ID
            context: 可选,应用场景描述(最多 500 字符)

        Returns:
            {"success": true, "application_id": N}
        """
        args: dict = {"strategy_id": strategy_id}
        if context:
            args["context"] = context
        return self._call_tool("apply_strategy", args)

    def feedback_strategy(
        self,
        strategy_id: int,
        feedback: str,
        comment: Optional[str] = None,
        applied: Optional[bool] = None,
    ) -> dict:
        """
        对策略反馈(每个 Agent 对同一策略只能反馈一次)

        Args:
            strategy_id: 策略 ID
            feedback: 反馈类型(positive/negative/neutral)
            comment: 可选备注(最多 500 字符)
            applied: 可选,是否实际采纳到工作中

        Returns:
            {"success": true, "feedback_id": N}
        """
        args: dict = {"strategy_id": strategy_id, "feedback": feedback}
        if comment:
            args["comment"] = comment
        if applied is not None:
            args["applied"] = applied
        return self._call_tool("feedback_strategy", args)

    def approve_strategy(
        self,
        strategy_id: int,
        action: str,
        reason: str,
    ) -> dict:
        """
        审批策略(admin only)

        Args:
            strategy_id: 策略 ID
            action: 审批动作(approve/reject)
            reason: 审批理由(最多 1000 字符)

        Returns:
            {"success": true, "strategy_id": N, "new_status": "approved"/"rejected"}
        """
        return self._call_tool("approve_strategy", {
            "strategy_id": strategy_id,
            "action": action,
            "reason": reason,
        })

    def get_evolution_status(self) -> dict:
        """
        查看进化指标统计

        Returns:
            {
                "total_experiences": N,
                "total_strategies": N,
                "pending_approval": N,
                "approved_rate": "X%",
                "top_contributors": [...],
                "recent_approved": [...],
            }
        """
        return self._call_tool("get_evolution_status", {})

    # ═══════════════════════════════════════════════════════
    # 对外 API — Phase 4b Day 2: 依赖链 + 并行组
    # ═══════════════════════════════════════════════════════

    def add_dependency(
        self,
        upstream_id: str,
        downstream_id: str,
        dep_type: str = "finish_to_start",
    ) -> dict:
        """
        添加任务依赖关系(自动环检测)

        Args:
            upstream_id: 上游任务 ID
            downstream_id: 下游任务 ID
            dep_type: 依赖类型(finish_to_start/start_to_start/finish_to_finish/start_to_finish)
        """
        return self._call_tool("add_dependency", {
            "upstream_id": upstream_id,
            "downstream_id": downstream_id,
            "dep_type": dep_type,
        })

    def remove_dependency(self, upstream_id: str, downstream_id: str) -> dict:
        """删除任务依赖关系"""
        return self._call_tool("remove_dependency", {
            "upstream_id": upstream_id,
            "downstream_id": downstream_id,
        })

    def get_task_dependencies(self, task_id: str) -> dict:
        """查询任务的所有依赖关系"""
        return self._call_tool("get_task_dependencies", {"task_id": task_id})

    def check_dependencies_satisfied(self, task_id: str) -> dict:
        """检查任务依赖是否全部满足"""
        return self._call_tool("check_dependencies_satisfied", {"task_id": task_id})

    def create_parallel_group(self, task_ids: List[str], group_name: str = "parallel_group") -> dict:
        """
        创建并行任务组

        Args:
            task_ids: 并行任务 ID 列表(至少 2 个)
            group_name: 组名
        """
        return self._call_tool("create_parallel_group", {
            "task_ids": task_ids,
            "group_name": group_name,
        })

    # ═══════════════════════════════════════════════════════
    # 对外 API — Phase 4b Day 3: 交接协议 + 质量门
    # ═══════════════════════════════════════════════════════

    def request_handoff(self, task_id: str, target_agent_id: str) -> dict:
        """请求任务交接"""
        return self._call_tool("request_handoff", {
            "task_id": task_id,
            "target_agent_id": target_agent_id,
        })

    def accept_handoff(self, task_id: str) -> dict:
        """接受任务交接"""
        return self._call_tool("accept_handoff", {"task_id": task_id})

    def reject_handoff(self, task_id: str, reason: Optional[str] = None) -> dict:
        """拒绝任务交接"""
        args: dict = {"task_id": task_id}
        if reason:
            args["reason"] = reason
        return self._call_tool("reject_handoff", args)

    def add_quality_gate(
        self,
        pipeline_id: str,
        gate_name: str,
        criteria: str,
        after_order: int,
    ) -> dict:
        """
        在 Pipeline 中添加质量门

        Args:
            pipeline_id: Pipeline ID
            gate_name: 质量门名称
            criteria: 评估规则(JSON 格式)
            after_order: 在哪个 order_index 之后阻塞
        """
        return self._call_tool("add_quality_gate", {
            "pipeline_id": pipeline_id,
            "gate_name": gate_name,
            "criteria": criteria,
            "after_order": after_order,
        })

    def evaluate_quality_gate(
        self,
        gate_id: str,
        status: str,
        result: Optional[str] = None,
    ) -> dict:
        """
        评估质量门(通过/失败)

        Args:
            gate_id: 质量门 ID
            status: 评估结果(passed/failed)
            result: 评估说明
        """
        args: dict = {"gate_id": gate_id, "status": status}
        if result:
            args["result"] = result
        return self._call_tool("evaluate_quality_gate", args)

    # ═══════════════════════════════════════════════════════
    # 对外 API — Phase 4b Day 4: 分级审批
    # ═══════════════════════════════════════════════════════

    def propose_strategy_tiered(
        self,
        title: str,
        content: str,
        category: str = "workflow",
        task_id: Optional[str] = None,
    ) -> dict:
        """
        提议策略(分级审批)
        Hub 自动判定审批等级:
          - auto: 高信任+低风险 → 自动通过 + 72h 观察窗口
          - peer: 中等信任 → peer 审批
          - admin: 默认 → admin 审批
          - super: 高风险 → 人工审批

        Args:
            title: 策略标题(3-200 字符)
            content: 策略内容(10-5000 字符)
            category: 分类(workflow/fix/tool_config/prompt_template/other)
            task_id: 可选,关联任务 ID
        """
        args: dict = {"title": title, "content": content, "category": category}
        if task_id:
            args["task_id"] = task_id
        return self._call_tool("propose_strategy_tiered", args)

    def check_veto_window(self, strategy_id: int) -> dict:
        """
        检查策略的否决窗口状态

        Args:
            strategy_id: 策略 ID
        """
        return self._call_tool("check_veto_window", {"strategy_id": strategy_id})

    def veto_strategy(self, strategy_id: int, reason: str) -> dict:
        """
        撤回处于否决窗口内的策略(admin only)

        Args:
            strategy_id: 策略 ID
            reason: 撤回理由
        """
        return self._call_tool("veto_strategy", {
            "strategy_id": strategy_id,
            "reason": reason,
        })

    # ═══════════════════════════════════════════════════════
    # 对外 API — Phase 5a: Security 增强
    # ═══════════════════════════════════════════════════════

    def set_agent_role(
        self,
        agent_id: str,
        role: str,
        managed_group_id: Optional[str] = None,
    ) -> dict:
        """设置 Agent 角色(admin only)

        Args:
            agent_id: 目标 Agent ID
            role: 新角色(admin / member / group_admin)
            managed_group_id: 管理组 ID(仅 group_admin 需要指定)

        Returns:
            { success, agent_id, old_role, new_role, managed_group_id }
        """
        params: dict = {"agent_id": agent_id, "role": role}
        if managed_group_id is not None:
            params["managed_group_id"] = managed_group_id
        return self._call_tool("set_agent_role", params)

    def recalculate_trust_scores(
        self,
        agent_id: Optional[str] = None,
    ) -> dict:
        """手动重算信任分(admin only)

        基于多因子自动计算:verified capabilities (+3)、approved strategies (+2)、
        positive feedback (+1)、negative feedback (-2)、rejected applications (-3)、
        revoked tokens (-10)。base=50, clamp(0,100)。

        Args:
            agent_id: 指定 Agent ID(可选,不传则全部重算)

        Returns:
            { success, agent_id, new_score } 或 { success, total_agents, scores }
        """
        params: dict = {}
        if agent_id is not None:
            params["agent_id"] = agent_id
        return self._call_tool("recalculate_trust_scores", params)

    # ═══════════════════════════════════════════════════════
    # 对外 API — Phase 6: 搜索 + Pipeline(补齐)
    # ═══════════════════════════════════════════════════════

    def search_messages(
        self,
        query: str,
        *,
        from_agent: Optional[str] = None,
        to_agent: Optional[str] = None,
        limit: int = 50,
    ) -> dict:
        """搜索消息(FTS5 全文检索)"""
        params: dict = {"query": query, "limit": limit}
        if from_agent:
            params["from_agent"] = from_agent
        if to_agent:
            params["to_agent"] = to_agent
        return self._call_tool("search_messages", params)

    def search_memories(
        self,
        query: str,
        *,
        scope: Optional[str] = None,
        agent_id: Optional[str] = None,
        limit: int = 50,
    ) -> dict:
        """搜索记忆(FTS5 全文检索)"""
        params: dict = {"query": query, "limit": limit}
        if scope:
            params["scope"] = scope
        if agent_id:
            params["agent_id"] = agent_id
        return self._call_tool("search_memories", params)

    def create_pipeline(self, name: str, description: str = "") -> dict:
        """创建 Pipeline(任务容器)"""
        return self._call_tool("create_pipeline", {
            "name": name,
            "description": description,
        })

    def get_pipeline(self, pipeline_id: str) -> dict:
        """获取 Pipeline 详情"""
        return self._call_tool("get_pipeline", {"pipeline_id": pipeline_id})

    def list_pipelines(self, *, status: Optional[str] = None) -> dict:
        """列出 Pipelines"""
        params: dict = {}
        if status:
            params["status"] = status
        return self._call_tool("list_pipelines", params)

    def add_task_to_pipeline(
        self,
        pipeline_id: str,
        description: str,
        *,
        assigned_to: Optional[str] = None,
        priority: str = "medium",
        depends_on: Optional[list] = None,
    ) -> dict:
        """向 Pipeline 添加任务"""
        params: dict = {
            "pipeline_id": pipeline_id,
            "description": description,
            "priority": priority,
        }
        if assigned_to:
            params["assigned_to"] = assigned_to
        if depends_on:
            params["depends_on"] = depends_on
        return self._call_tool("add_task_to_pipeline", params)

    def cancel_task(self, task_id: str, reason: str = "") -> dict:
        """取消任务"""
        params: dict = {"task_id": task_id}
        if reason:
            params["reason"] = reason
        return self._call_tool("cancel_task", params)

    # ═══════════════════════════════════════════════════════
    # 对外 API — 消费追踪
    # ═══════════════════════════════════════════════════════

    def mark_consumed(self, resource: str, resource_type: str = "file", action: str = "processed", notes: Optional[str] = None) -> dict:
        """标记资源已消费(去重)"""
        args: dict = {
            "agent_id": self.agent_id,
            "resource": resource,
            "resource_type": resource_type,
            "action": action,
        }
        if notes:
            args["notes"] = notes
        return self._call_tool("mark_consumed", args)

    def check_consumed(self, resource: str) -> dict:
        """检查资源是否已消费"""
        return self._call_tool("check_consumed", {
            "agent_id": self.agent_id,
            "resource": resource,
        })

    # ═══════════════════════════════════════════════════════
    # SSE 订阅 + 自动重连 + 客户端去重
    # ═══════════════════════════════════════════════════════

    def connect_sse(self, blocking: bool = True) -> None:
        """
        连接 SSE 事件流

        Args:
            blocking: True=阻塞当前线程,False=后台线程

        使用方法:
            # 阻塞模式(适合独立脚本)
            hub.connect_sse(blocking=True)

            # 非阻塞模式(适合集成到其他应用)
            hub.connect_sse(blocking=False)
            # 后续可通过 hub.disconnect_sse() 停止
        """
        if self._sse_running:
            logger.warning("SSE 已在运行中")
            return

        if blocking:
            self._sse_loop()
        else:
            self._sse_thread = threading.Thread(
                target=self._sse_loop,
                name=f"sse-{self.agent_id or 'unknown'}",
                daemon=True,
            )
            self._sse_thread.start()

    def disconnect_sse(self) -> None:
        """断开 SSE 连接"""
        self._sse_running = False
        logger.info(f"[{self.agent_id}] SSE 断开请求")

    def _sse_loop(self) -> None:
        """SSE 连接主循环(含自动重连)"""
        self._sse_running = True
        self._reconnect_delay = self._reconnect_base

        while self._sse_running:
            if not self.agent_id:
                logger.error("agent_id 未设置,无法连接 SSE")
                break

            try:
                url = f"{self.hub_url}/events/{self.agent_id}"

                logger.info(f"[{self.agent_id}] SSE 连接: {self.hub_url}")
                conn = self._create_sse_connection(url)
                logger.info(f"[{self.agent_id}] SSE 已连接")
                self._reconnect_delay = self._reconnect_base
                self._read_sse_http_client(conn)

            except AuthError:
                logger.error(f"[{self.agent_id}] SSE 认证失败,停止重连")
                break
            except Exception as e:
                if not self._sse_running:
                    break
                logger.warning(f"[{self.agent_id}] SSE 断线: {e}")
                self._wait_reconnect()

        self._sse_running = False
        logger.info(f"[{self.agent_id}] SSE 主循环退出")

    def _create_sse_connection(self, url: str) -> http.client.HTTPConnection:
        """使用 http.client 建立 SSE 连接(更好控制读取行为)"""
        from urllib.parse import urlparse
        parsed = urlparse(url)
        host = parsed.hostname
        port = parsed.port or 80
        path = parsed.path + ("?" + parsed.query if parsed.query else "")

        conn = http.client.HTTPConnection(host, port, timeout=self._sse_timeout)
        headers = {}
        if self._token:
            headers["Authorization"] = f"Bearer {self._token}"
        # 断线重连时携带 Last-Event-ID
        with self._last_event_id_lock:
            if self._last_event_id is not None:
                headers["Last-Event-ID"] = self._last_event_id

        conn.request("GET", path, headers=headers)
        resp = conn.getresponse()

        if resp.status == 401:
            raise AuthError("SSE authentication failed", 401)
        if resp.status != 200:
            raise HubError(f"SSE connection failed: HTTP {resp.status}", resp.status)

        return conn

    def _read_sse_http_client(self, conn: http.client.HTTPConnection) -> None:
        """使用 http.client 逐行读取 SSE 流"""
        resp = conn.sock  # 底层 socket
        buffer = ""

        while self._sse_running:
            try:
                # 使用 makefile 获取类文件对象,设置小缓冲
                f = conn.sock.makefile("r", encoding="utf-8", errors="replace", newline=None)
                while self._sse_running:
                    line = f.readline()
                    if not line:
                        break
                    buffer += line

                    # 按 \n\n 分割 SSE 事件
                    while "\n\n" in buffer:
                        event_text, buffer = buffer.split("\n\n", 1)
                        self._parse_sse_event(event_text.strip())
                f.close()
                break
            except (socket.timeout, OSError) as e:
                if not self._sse_running:
                    break
                # 超时或连接错误,触发重连
                raise HubError(f"SSE read error: {e}")
            except Exception as e:
                if not self._sse_running:
                    break
                raise

    def _parse_sse_event(self, event_text: str) -> None:
        """解析单个 SSE 事件"""
        lines = event_text.split("\n")
        data = ""
        event_id: Optional[str] = None

        for line in lines:
            if line.startswith("data:"):
                data = line[5:].strip()
            elif line.startswith("id:"):
                # 记录 Last-Event-ID 用于断线重连
                event_id = line[3:].strip()
                with self._last_event_id_lock:
                    self._last_event_id = event_id
            elif line.startswith(":"):
                # SSE 心跳注释
                pass

        if not data:
            return

        try:
            payload = json.loads(data)
        except json.JSONDecodeError:
            logger.debug(f"非 JSON SSE 数据: {data[:80]}")
            return

        # 处理 MCP 包装格式(result.content[0].text)
        if "result" in payload and "jsonrpc" in payload:
            result = payload.get("result", {})
            if isinstance(result, dict) and "content" in result:
                for item in result.get("content", []):
                    if isinstance(item, dict) and item.get("type") == "text":
                        try:
                            inner = json.loads(item["text"])
                            self._handle_event(inner)
                        except (json.JSONDecodeError, TypeError):
                            pass
            return

        # 直接事件格式
        self._handle_event(payload)

    def _handle_event(self, data: dict) -> None:
        """
        事件路由 + 客户端去重
        """
        event_type = data.get("event", "unknown")

        # ── 客户端去重 ─────────────────────────────────
        event_id = data.get("_hub_event_id")
        if event_id is not None:
            with self._seen_event_ids_lock:
                if event_id in self._seen_event_ids:
                    logger.debug(f"去重: event_id={event_id}")
                    return
                self._seen_event_ids.add(event_id)
                self._seen_event_ids_ordered.append(event_id)
                # 防止内存泄漏:保留最新的一半(按插入顺序)
                if len(self._seen_event_ids) > self._dedup_max_size:
                    trim_count = self._dedup_max_size // 2
                    old_ids = self._seen_event_ids_ordered[:trim_count]
                    self._seen_event_ids_ordered = self._seen_event_ids_ordered[trim_count:]
                    for old_id in old_ids:
                        self._seen_event_ids.discard(old_id)

        # ── 事件路由 ───────────────────────────────────
        if event_type == "new_message":
            msg = data.get("message", data)
            logger.info(f"[消息] 来自 {msg.get('from_agent', '?')}: {str(msg.get('content', ''))[:60]}")
            if self.on_message:
                try:
                    self.on_message(msg)
                except Exception as e:
                    logger.error(f"on_message 回调异常: {e}")

        elif event_type == "task_assigned":
            task = data.get("task", data)
            logger.info(f"[任务] 来自 {task.get('assigned_by', '?')}: {str(task.get('description', ''))[:60]}")
            if self.on_task_assigned:
                try:
                    self.on_task_assigned(task)
                except Exception as e:
                    logger.error(f"on_task_assigned 回调异常: {e}")

        elif event_type == "task_updated":
            update = data.get("update", data)
            logger.debug(f"[更新] 任务 {update.get('task_id', '')[:16]} → {update.get('status')}")
            if self.on_task_updated:
                try:
                    self.on_task_updated(update)
                except Exception as e:
                    logger.error(f"on_task_updated 回调异常: {e}")

        elif event_type == "pending_messages":
            messages = data.get("messages", [])
            if messages:
                logger.info(f"[积压] 补发 {len(messages)} 条消息")
                for msg in messages:
                    if self.on_message:
                        try:
                            self.on_message(msg)
                        except Exception as e:
                            logger.error(f"on_message 回调异常: {e}")

        else:
            logger.debug(f"[未知事件] {event_type}: {json.dumps(data, ensure_ascii=False)[:100]}")

    def _wait_reconnect(self) -> None:
        """指数退避等待重连"""
        delay = self._reconnect_delay
        logger.info(f"[{self.agent_id}] {delay:.1f}s 后重连...")
        time.sleep(delay)
        self._reconnect_delay = min(self._reconnect_delay * 2, self._reconnect_max)

    # ═══════════════════════════════════════════════════════
    # REST API(供补充调用)
    # ═══════════════════════════════════════════════════════

    def health_check(self) -> dict:
        """健康检查(免认证)"""
        raw = self._request("GET", "/health", timeout=5)
        return json.loads(raw.decode("utf-8"))

    def generate_invite(self, role: str = "member") -> dict:
        """生成邀请码(admin only)"""
        raw = self._request("POST", "/admin/invite/generate", data={"role": role}, headers=self._auth_headers())
        return json.loads(raw.decode("utf-8"))

    def get_tasks(self, status: str = "pending") -> dict:
        """REST API 获取任务列表"""
        raw = self._request(
            "GET", f"/api/tasks?agent_id={self.agent_id}&status={status}",
            headers=self._auth_headers(),
        )
        return json.loads(raw.decode("utf-8"))

    def get_messages(self, status: str = "unread") -> dict:
        """REST API 获取消息列表"""
        raw = self._request(
            "GET", f"/api/messages?agent_id={self.agent_id}&status={status}",
            headers=self._auth_headers(),
        )
        return json.loads(raw.decode("utf-8"))

    def update_task_via_rest(self, task_id: str, status: str, result: Optional[str] = None, progress: int = 0) -> dict:
        """REST API 更新任务状态"""
        raw = self._request(
            "PATCH", f"/api/tasks/{task_id}/status",
            data={"status": status, "result": result, "progress": progress},
            headers=self._auth_headers(),
        )
        return json.loads(raw.decode("utf-8"))

    # ═══════════════════════════════════════════════════════
    # 辅助方法
    # ═══════════════════════════════════════════════════════

    def __repr__(self) -> str:
        return (
            f"SynergyHubClient(agent_id={self.agent_id!r}, "
            f"hub={self.hub_url!r}, connected={self._sse_running})"
        )


# ─── 便捷入口 ─────────────────────────────────────────────────────

def create_client(
    hub_url: str = "http://localhost:3100",
    invite_code: Optional[str] = None,
    name: Optional[str] = None,
    agent_id: Optional[str] = None,
) -> SynergyHubClient:
    """
    便捷工厂方法:创建并可选注册客户端

    Usage:
        # 仅创建(后续手动注册)
        client = create_client(hub_url="http://localhost:3100")

        # 创建 + 注册
        client = create_client(
            hub_url="http://localhost:3100",
            invite_code="abc12345",
            name="my_agent",
        )
    """
    client = SynergyHubClient(hub_url=hub_url, agent_id=agent_id)

    if invite_code and name:
        client.register(invite_code=invite_code, name=name, agent_id=agent_id)

    return client
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