Claw Chat Hub

智能体实时通讯模块 - 支持 Provider 和 Consumer 双向消息、频道管理、消息历史

Security Scan

The skill appears to implement a WebSocket chat client consistent with its description, but there are mismatches between declared requirements and the actual code/instructions (notably a required HUB_URL env var and missing dependency declaration), which deserve clarification before installing.

Purpose & Capability

The name/description match the included code: this is a WebSocket-based chat client for agent-to-agent messaging. Requiring python3 is sensible. However, the registry metadata declares a required environment variable HUB_URL that is never read by the SKILL.md examples or the code (the client accepts hub_url as a constructor argument). The constructor also accepts api_key but the code never uses it for authentication. These mismatches are unnecessary and reduce coherence.

Instruction Scope

SKILL.md only instructs the agent to install the package locally and to connect/send/listen over a WebSocket hub. It does not instruct reading arbitrary files, system credentials, or exfiltrating unrelated data. The primary network behavior (connecting to a hub_url you supply) is expected for this skill, but users must trust the remote hub because all messages go there.

Install Mechanism

There is no remote download/install spec in the registry (lowest risk). SKILL.md suggests 'pip install -e /path/to/...' which is a local editable install. However, the code imports the 'websockets' package but the package dependency list is not provided in the metadata or SKILL.md — an omitted dependency declaration is a packaging/integrity concern (it may break at runtime or hide required network-capable libs).

Credentials

The skill declares HUB_URL as a required environment variable but neither SKILL.md examples nor chat_client.py read HUB_URL from the environment; hub URL is passed explicitly to the constructor instead. This suggests either the metadata is incorrect or the runtime will expect an env var that the code doesn't use. Additionally, api_key is accepted but unused. Declaring secrets (env vars) that aren't needed is disproportionate and confusing — clarify why HUB_URL is required and whether any credential env vars are actually read.

Persistence & Privilege

The skill does not request always:true, system-level config paths, or other skills' credentials. It is user-invocable and can be invoked autonomously (platform default), which is expected for a messaging client.

What to consider before installing

This skill is a WebSocket chat client and mostly behaves as described, but there are a few red flags to resolve before installation: (1) The registry lists HUB_URL as a required env var, yet neither the README examples nor the code read HUB_URL from the environment — ask the author to explain or fix this mismatch. (2) The code imports the 'websockets' library but the skill metadata or SKILL.md do not declare dependencies; confirm that installing the package will pull required dependencies. (3) Confirm whether api_key is intended to be used for auth; currently it is accepted but unused. Finally, remember that the client will connect to whatever hub_url you provide and send/receive messages there — only supply hub endpoints you trust. If you cannot get clarifications or an updated package that fixes the metadata and dependency declarations, treat the skill cautiously (suspicious) and avoid giving it access to production credentials or sensitive hubs.

实现智能体之间的双向实时通讯

概述

claw-chat-hub 提供智能体之间的实时消息通讯能力，让服务提供者和服务使用者可以通过 Hub 进行双向实时对话。

功能

• 服务绑定通讯 - 服务注册时自动创建通讯频道
• 双向实时消息 - 支持 Provider 和 Consumer 之间实时交流
• 消息历史 - 获取历史会话记录
• 频道管理 - 创建、绑定、结束通讯会话

安装

pip install -e /path/to/Claw-Service-Hub/claw-chat-hub

快速开始

Provider 端（服务提供者）

from claw_chat_hub import ChatClient

# 创建客户端
chat = ChatClient(
    hub_url="ws://localhost:8765",
    agent_id="weather-provider"
)

# 监听消息
async def on_message(msg):
    print(f"收到消息 from {msg['sender_id']}: {msg['content']}")
    
    # 回复消息
    await chat.send_message(
        target_agent=msg['sender_id'],
        content="消息已收到！"
    )

# 启动监听
await chat.connect()
await chat.listen_for_messages(on_message)

Consumer 端（服务使用者）

from claw_chat_hub import ChatClient

# 创建客户端
chat = ChatClient(
    hub_url="ws://localhost:8765",
    agent_id="weather-consumer"
)

# 连接到 Hub
await chat.connect()

# 发送消息
await chat.send_message(
    target_agent="weather-provider",
    content="查询北京天气"
)

# 监听回复
async for msg in chat.messages():
    print(f"收到: {msg['content']}")

API 参考

ChatClient

初始化

chat = ChatClient(
    hub_url="ws://localhost:8765",  # Hub 地址
    agent_id="my-agent",             # 智能体 ID
    api_key=None                     # API 密钥（可选）
)

连接与断开

await chat.connect()      # 连接到 Hub
await chat.disconnect()   # 断开连接

发送消息

result = await chat.send_message(
    target_agent="other-agent",  # 目标智能体
    content="Hello!",            # 消息内容
    service_id="weather-svc"     # 服务 ID（可选）
)

请求通讯

# Consumer 请求与 Provider 通讯
result = await chat.request_chat(
    service_id="weather-svc"
)
# result = {"status": "accepted", "channel_id": "ch_xxx"}

接受/拒绝通讯

# Provider 接受
await chat.accept_chat(consumer_id="consumer-agent")

# Provider 拒绝
await chat.reject_chat(consumer_id="consumer-agent", reason="Busy")

结束通讯

await chat.end_chat(channel_id="ch_xxx")

获取历史

history = await chat.get_history(
    channel_id="ch_xxx",      # 频道 ID
    service_id="weather-svc", # 服务 ID
    limit=50                  # 数量限制
)

便捷函数

from claw_chat_hub import quick_send

# 快速发送消息（单次）
result = await quick_send(
    hub_url="ws://localhost:8765",
    agent_id="sender",
    target_agent="receiver",
    content="Hello!"
)

消息协议

消息类型	方向	说明
chat_request	Consumer → Hub → Provider	发起通讯请求
chat_accept	Provider → Hub → Consumer	接受通讯
chat_reject	Provider → Hub → Consumer	拒绝通讯
chat_message	双向	消息内容
chat_end	任意	结束通讯
chat_history	Consumer → Hub	获取历史

数据结构

频道 (Channel)

{
    "channel_id": "ch_xxx",
    "provider_id": "weather-provider",
    "consumer_id": "weather-consumer",
    "service_id": "weather-svc",
    "created_at": "2024-01-01T00:00:00Z"
}

消息 (Message)

{
    "message_id": "msg_xxx",
    "channel_id": "ch_xxx",
    "sender_id": "weather-provider",
    "content": "北京今天晴，25°C",
    "timestamp": "2024-01-01T00:00:00Z"
}

与其他模块的关系

claw-chat-hub
    │
    ├── 需要: hub-client (连接 Hub)
    ├── 需要: server/chat_* (Hub 端支持)
    └── 可选: claw-trade-hub (交易 + 通讯)

示例

See examples/chat_example.py for complete examples.