wechat-openclaw-sdk 0.1.0__py3-none-any.whl

wechat_openclaw/__init__.py

@@ -0,0 +1,50 @@
+"""WeChat OpenClaw SDK —— Python 版微信 iLink OpenClaw 接入 SDK。
+
+核心能力：任意 Agent 对接、单机/分布式部署、主动发消息、二维码登录。
+"""
+from .agent import (
+    AgentEvent,
+    AgentEventType,
+    AgentRunRequest,
+    Attachment,
+    BaseAgent,
+    Dispatcher,
+    EchoAgent,
+    OpenAICompatAgent,
+)
+from .api import OpenClawAPI, OpenClawApiError, SessionExpiredError
+from .client import OpenClawClient, SDKConfig
+from .config import DEFAULT_BASE_URL, DEFAULT_CDN_BASE_URL, ENV_BASE_URL, get_base_url
+from .connection import ConnectionManager, LocalDeduplicator, RedisDeduplicator
+from .coordinator import BaseCoordinator, NoopCoordinator, RedisCoordinator
+from .models import (
+    BaseInfo,
+    CdnMedia,
+    MessageItem,
+    TextItem,
+    TypingStatus,
+    UploadMediaType,
+    WeChatMessage,
+    WeChatMessageItemType,
+    WeChatMessageState,
+    WeChatMessageType,
+)
+from .qrlogin import QrLoginError, QrLoginModule, QrSession, WeChatCredentials
+from .utils.markdown import StreamingMarkdownFilter, markdown_to_plain
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AgentEvent", "AgentEventType", "AgentRunRequest", "Attachment",
+    "BaseAgent", "Dispatcher", "EchoAgent", "OpenAICompatAgent",
+    "OpenClawAPI", "OpenClawApiError", "SessionExpiredError",
+    "OpenClawClient", "SDKConfig",
+    "DEFAULT_BASE_URL", "DEFAULT_CDN_BASE_URL", "ENV_BASE_URL", "get_base_url",
+    "ConnectionManager", "LocalDeduplicator", "RedisDeduplicator",
+    "BaseCoordinator", "NoopCoordinator", "RedisCoordinator",
+    "BaseInfo", "CdnMedia", "MessageItem", "TextItem", "TypingStatus",
+    "UploadMediaType", "WeChatMessage", "WeChatMessageItemType",
+    "WeChatMessageState", "WeChatMessageType",
+    "QrLoginError", "QrLoginModule", "QrSession", "WeChatCredentials",
+    "StreamingMarkdownFilter", "markdown_to_plain",
+]

wechat_openclaw/agent.py

@@ -0,0 +1,223 @@
+"""Agent 对接抽象 —— BaseAgent + AgentEvent + Dispatcher。
+
+编排行为：收到消息后先发占位语，随后消费 Agent 事件流并分段发送回复。
+"""
+from __future__ import annotations
+
+import json
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, AsyncIterator, Optional
+
+from .models import CdnMedia, TypingStatus, WeChatMessage, WeChatMessageItemType
+
+if TYPE_CHECKING:
+    from .client import OpenClawClient
+
+log = logging.getLogger(__name__)
+
+# 收到消息后的占位语与兜底错误文案
+THINKING_PLACEHOLDER = "嗯，我想想🤔。"
+FALLBACK_ERROR_TEXT = "消息处理错误。"
+
+
+class AgentEventType(Enum):
+    """Agent 事件类型"""
+
+    REASONING_START = "REASONING_START"
+    REASONING_DELTA = "REASONING_DELTA"
+    REASONING_END = "REASONING_END"
+    TOOL_RUNNING = "TOOL_RUNNING"
+    TOOL_COMPLETED = "TOOL_COMPLETED"
+    TOOL_FAILED = "TOOL_FAILED"
+    TEXT_DELTA = "TEXT_DELTA"
+    MESSAGE_COMPLETED = "MESSAGE_COMPLETED"
+    MESSAGE_FAILED = "MESSAGE_FAILED"
+
+
+# 步骤完成事件：触发 typing 翻转 / 全文发送
+STEP_COMPLETE_EVENTS = {AgentEventType.REASONING_END,
+                        AgentEventType.TOOL_COMPLETED,
+                        AgentEventType.MESSAGE_COMPLETED}
+
+
+@dataclass
+class AgentEvent:
+    """Agent 事件"""
+
+    event_type: AgentEventType
+    data: dict = field(default_factory=dict)
+
+    def to_markdown(self) -> str:
+        """渲染为可累积的文本片段：TEXT_DELTA 返回增量文本，其余事件默认空串"""
+        return self.data.get("text", "")
+
+
+@dataclass
+class Attachment:
+    """入站附件（图片/文件等，含 CdnMedia 引用）"""
+
+    item_type: int
+    media: Optional[CdnMedia] = None
+    file_name: Optional[str] = None
+
+
+@dataclass
+class AgentRunRequest:
+    """Agent 运行请求"""
+
+    user_input: str
+    user_id: str
+    user_nickname: Optional[str] = None
+    # 会话标识，用 WeChatMessage.session_id 填充
+    session_id: str = ""
+    attachments: list[Attachment] = field(default_factory=list)
+    # 扩展上下文（原始消息、context_token 等透传数据）
+    context: dict = field(default_factory=dict)
+
+
+class BaseAgent(ABC):
+    """智能体抽象：任何后端实现 run 返回异步事件流即可插拔接入"""
+
+    @abstractmethod
+    def run(self, request: AgentRunRequest) -> AsyncIterator[AgentEvent]:
+        """运行智能体，返回异步事件流。实现方通常写成 async generator。"""
+        ...
+
+
+def build_agent_request(msg: WeChatMessage) -> AgentRunRequest:
+    """从入站消息构造 AgentRunRequest：提取文本/语音 ASR 文本与媒体附件"""
+    texts: list[str] = []
+    attachments: list[Attachment] = []
+    for item in msg.item_list or []:
+        if item.type == WeChatMessageItemType.TEXT and item.text_item:
+            if item.text_item.text:
+                texts.append(item.text_item.text)
+        elif item.type == WeChatMessageItemType.VOICE and item.voice_item:
+            # 语音消息不下载音频：直接使用微信 ASR 转文字结果
+            if item.voice_item.text:
+                texts.append(item.voice_item.text)
+        elif item.type == WeChatMessageItemType.IMAGE and item.image_item:
+            attachments.append(Attachment(item_type=item.type,
+                                          media=item.image_item.media))
+        elif item.type == WeChatMessageItemType.FILE and item.file_item:
+            attachments.append(Attachment(item_type=item.type,
+                                          media=item.file_item.media,
+                                          file_name=item.file_item.file_name))
+    return AgentRunRequest(
+        user_input="\n".join(texts),
+        user_id=msg.from_user_id or "",
+        session_id=msg.session_id or "",
+        attachments=attachments,
+        context={"message": msg, "context_token": msg.context_token})
+
+
+class Dispatcher:
+    """消息 -> Agent 编排（行为序列转录自 WeChatMessageListener.onMessage）。
+
+    typing 翻转规则：步骤完成事件先关 typing；MESSAGE_COMPLETED 时发送缓冲全文，
+    其余完成事件重开 typing 让"输入中"重新闪烁；文本增量只缓冲不逐条发送。
+    """
+
+    def __init__(self, client: "OpenClawClient", agent: BaseAgent,
+                 send_placeholder: bool = True) -> None:
+        self._client = client
+        self._agent = agent
+        self._send_placeholder = send_placeholder
+
+    async def on_message(self, msg: WeChatMessage) -> None:
+        request = build_agent_request(msg)
+        user_id = request.user_id
+        token = msg.context_token
+        buffer: list[str] = []
+        is_typing = True
+        await self._client.send_typing(user_id, token, TypingStatus.TYPING)
+        if self._send_placeholder:
+            try:
+                await self._client.send_text(user_id, THINKING_PLACEHOLDER, token)
+            except Exception:
+                log.warning("failed to send thinking placeholder, message_id=%s",
+                            msg.message_id)
+        try:
+            async for event in self._agent.run(request):
+                if event.event_type in STEP_COMPLETE_EVENTS:
+                    if is_typing:
+                        await self._client.send_typing(user_id, token,
+                                                       TypingStatus.CANCEL)
+                        is_typing = False
+                    if event.event_type is AgentEventType.MESSAGE_COMPLETED:
+                        await self._client.send_text(user_id, "".join(buffer), token)
+                    else:
+                        await self._client.send_typing(user_id, token,
+                                                       TypingStatus.TYPING)
+                        is_typing = True
+                    buffer.clear()
+                else:
+                    if not is_typing:
+                        await self._client.send_typing(user_id, token,
+                                                       TypingStatus.TYPING)
+                        is_typing = True
+                    buffer.append(event.to_markdown())
+        except Exception:
+            log.exception("agent stream error, message_id=%s", msg.message_id)
+            try:
+                await self._client.send_text(user_id, FALLBACK_ERROR_TEXT, token)
+            except Exception:
+                log.exception("failed to send fallback error text, message_id=%s",
+                              msg.message_id)
+
+
+class EchoAgent(BaseAgent):
+    """参考实现一：回声机器人"""
+
+    async def run(self, request: AgentRunRequest) -> AsyncIterator[AgentEvent]:
+        yield AgentEvent(AgentEventType.TEXT_DELTA,
+                         {"text": f"你说的是：{request.user_input}"})
+        yield AgentEvent(AgentEventType.MESSAGE_COMPLETED)
+
+
+class OpenAICompatAgent(BaseAgent):
+    """参考实现二：对接任意 OpenAI 兼容 /chat/completions 流式接口。
+
+    映射：SSE delta.content -> TEXT_DELTA，流结束 -> MESSAGE_COMPLETED；
+    若接口带 reasoning_content 可映射为 REASONING_DELTA / REASONING_END。
+    """
+
+    def __init__(self, base_url: str, api_key: str, model: str) -> None:
+        import httpx
+        self._http = httpx.AsyncClient(
+            base_url=base_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=60.0)
+        self._model = model
+
+    async def run(self, request: AgentRunRequest) -> AsyncIterator[AgentEvent]:
+        messages = [{"role": "user", "content": request.user_input}]
+        async for event in self.stream_chat(messages):
+            yield event
+        yield AgentEvent(AgentEventType.MESSAGE_COMPLETED)
+
+    async def stream_chat(self, messages: list[dict]) -> AsyncIterator[AgentEvent]:
+        """按 OpenAI 格式 messages 流式调用（支持图文混合 content），
+        产出 TEXT_DELTA 事件；末尾 MESSAGE_COMPLETED 由调用方自行补发。
+        """
+        payload = {"model": self._model, "stream": True, "messages": messages}
+        async with self._http.stream("POST", "/chat/completions",
+                                     json=payload) as resp:
+            if resp.is_error:
+                # 流式响应默认不读 body，出错时先读出来让异常信息带上服务端原文
+                await resp.aread()
+                resp.raise_for_status()
+            async for line in resp.aiter_lines():
+                if not line.startswith("data: ") or line == "data: [DONE]":
+                    continue
+                chunk = json.loads(line[6:])
+                # usage 统计块等场景 choices 为空数组，跳过以免下标越界
+                choices = chunk.get("choices") or []
+                if not choices:
+                    continue
+                delta = (choices[0].get("delta") or {}).get("content")
+                if delta:
+                    yield AgentEvent(AgentEventType.TEXT_DELTA, {"text": delta})

wechat_openclaw/api.py

@@ -0,0 +1,222 @@
+"""OpenClawAPI —— OpenClaw HTTP 协议封装。
+
+5 个 POST JSON 端点 + CDN octet-stream 上传：
+- /ilink/bot/getupdates   长轮询拉取消息，超时 35s（客户端超时视为正常空响应）
+- /ilink/bot/sendmessage  发送消息，超时 15s
+- /ilink/bot/getuploadurl 获取 CDN 上传 URL，超时 15s
+- /ilink/bot/getconfig    获取配置（typing_ticket），超时 10s
+- /ilink/bot/sendtyping   发送输入状态，超时 10s
+"""
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Optional
+
+import httpx
+
+from .config import get_base_url
+from .models import (
+    GetConfigRequest,
+    GetConfigResponse,
+    GetUpdatesRequest,
+    GetUpdatesResponse,
+    GetUploadUrlRequest,
+    GetUploadUrlResponse,
+    SendMessageRequest,
+    SendTypingRequest,
+)
+from .utils.ids import random_wechat_uin, redact_url
+from .utils.retry import retry_async
+
+log = logging.getLogger(__name__)
+
+# SDK 内部异常分类标识
+ERR_API_FAILURE = "ERR_API_FAILURE"
+ERR_SESSION_EXPIRED = "ERR_SESSION_EXPIRED"
+
+
+class OpenClawApiError(RuntimeError):
+    """一般 API 失败（业务错误，不重试）"""
+
+    def __init__(self, error_code: str, message: str,
+                 api_errcode: Optional[int] = None,
+                 raw_text: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.error_code = error_code
+        self.api_errcode = api_errcode
+        self.raw_text = raw_text
+
+
+class SessionExpiredError(OpenClawApiError):
+    """errcode == -14 会话过期（bot_token 失效），不可重试，需重新扫码登录"""
+
+    def __init__(self, message: str, raw_text: Optional[str] = None) -> None:
+        super().__init__(ERR_SESSION_EXPIRED, message,
+                         api_errcode=OpenClawAPI.SESSION_EXPIRED_ERRCODE,
+                         raw_text=raw_text)
+
+
+class OpenClawAPI:
+    """OpenClaw HTTP 协议客户端，与单个 bot_token 绑定"""
+
+    LONG_POLL_TIMEOUT = 35.0
+    API_TIMEOUT = 15.0
+    CONFIG_TIMEOUT = 10.0
+    SESSION_EXPIRED_ERRCODE = -14
+    UPLOAD_MAX_RETRIES = 3
+
+    def __init__(self, bot_token: str,
+                 base_url: str | None = None,
+                 http: httpx.AsyncClient | None = None,
+                 verify_ssl: bool = True) -> None:
+        self._bot_token = bot_token
+        self._base_url = (base_url or get_base_url()).rstrip("/")
+        # 默认超时按普通 API 配置，长轮询请求单独覆盖 read 超时
+        # 跟随重定向以兼容网关侧 302；verify_ssl=False 供裸 IP 部署（证书 hostname
+        # 不匹配）使用，仅作用于自持有客户端，外部传入的 http 不受影响
+        self._http = http or httpx.AsyncClient(
+            timeout=httpx.Timeout(connect=10.0, read=self.API_TIMEOUT,
+                                  write=15.0, pool=10.0),
+            follow_redirects=True, verify=verify_ssl)
+        self._own_http = http is None
+
+    async def aclose(self) -> None:
+        """关闭自持有的 HTTP 连接池"""
+        if self._own_http:
+            await self._http.aclose()
+
+    def _headers(self) -> dict[str, str]:
+        """公共请求头；X-WECHAT-UIN 每次请求随机生成"""
+        headers = {
+            "Content-Type": "application/json",
+            "AuthorizationType": "ilink_bot_token",
+            "X-WECHAT-UIN": random_wechat_uin(),
+        }
+        # bot_token 为空时不携带 Authorization 头
+        if self._bot_token:
+            headers["Authorization"] = f"Bearer {self._bot_token}"
+        return headers
+
+    @staticmethod
+    def _ensure_api_success(label: str, text: str) -> None:
+        """统一响应校验。
+
+        空体视为成功；ret != 0 或 errcode != 0 即失败；errcode == -14 会话过期。
+        """
+        if not text:
+            return
+        try:
+            body: dict[str, Any] = json.loads(text)
+        except (json.JSONDecodeError, ValueError) as e:
+            raise OpenClawApiError(
+                ERR_API_FAILURE, f"{label} returned non-JSON response",
+                raw_text=text[:200]) from e
+        ret = body.get("ret") or 0
+        errcode = body.get("errcode") or 0
+        if ret == 0 and errcode == 0:
+            return
+        errmsg = body.get("errmsg") or f"{label} failed with ret={ret}, errcode={errcode}"
+        if errcode == OpenClawAPI.SESSION_EXPIRED_ERRCODE:
+            raise SessionExpiredError(errmsg, raw_text=text[:200])
+        raise OpenClawApiError(ERR_API_FAILURE, errmsg,
+                               api_errcode=errcode, raw_text=text[:200])
+
+    async def _post(self, path: str, payload: dict, timeout: float, label: str) -> str:
+        """发送 POST JSON 请求并做统一校验，返回原始响应体文本"""
+        url = self._base_url + path
+        resp = await self._http.post(url, json=payload,
+                                     headers=self._headers(), timeout=timeout)
+        resp.raise_for_status()
+        text = resp.text
+        if log.isEnabledFor(logging.DEBUG):
+            log.debug("%s response: %s", label, text[:200])
+        self._ensure_api_success(label, text)
+        return text
+
+    async def _post_with_retry(self, path: str, payload: dict,
+                               timeout: float, label: str) -> str:
+        """带重试的 POST：会话过期与业务错误不重试，仅网络层异常重试"""
+        return await retry_async(
+            lambda: self._post(path, payload, timeout, label),
+            no_retry=(OpenClawApiError,), label=label)
+
+    async def get_updates(self, req: GetUpdatesRequest) -> GetUpdatesResponse:
+        """长轮询拉取消息。客户端超时属正常现象（服务端无消息时持有请求），
+        此时合成空响应（ret=0, msgs=[], buf 原样），不抛异常。
+        """
+        try:
+            text = await self._post("/ilink/bot/getupdates", req.to_payload(),
+                                    self.LONG_POLL_TIMEOUT, "getupdates")
+        except httpx.TimeoutException:
+            log.debug("getupdates client timeout, treat as empty response")
+            return GetUpdatesResponse(ret=0, errcode=0, msgs=[],
+                                      get_updates_buf=req.get_updates_buf)
+        if not text:
+            return GetUpdatesResponse(ret=0, errcode=0, msgs=[],
+                                      get_updates_buf=req.get_updates_buf)
+        return GetUpdatesResponse.model_validate_json(text)
+
+    async def send_message(self, req: SendMessageRequest) -> None:
+        """发送消息（文本/媒体统一入口）"""
+        await self._post_with_retry("/ilink/bot/sendmessage", req.to_payload(),
+                                    self.API_TIMEOUT, "sendmessage")
+
+    async def get_upload_url(self, req: GetUploadUrlRequest) -> GetUploadUrlResponse:
+        """获取 CDN 上传 URL"""
+        text = await self._post_with_retry("/ilink/bot/getuploadurl", req.to_payload(),
+                                           self.API_TIMEOUT, "getuploadurl")
+        return GetUploadUrlResponse.model_validate_json(text) if text \
+            else GetUploadUrlResponse()
+
+    async def get_config(self, ilink_user_id: str, context_token: str) -> GetConfigResponse:
+        """获取配置（typing_ticket）"""
+        req = GetConfigRequest(ilink_user_id=ilink_user_id, context_token=context_token)
+        text = await self._post_with_retry("/ilink/bot/getconfig", req.to_payload(),
+                                           self.CONFIG_TIMEOUT, "getconfig")
+        return GetConfigResponse.model_validate_json(text) if text \
+            else GetConfigResponse()
+
+    async def send_typing(self, req: SendTypingRequest) -> None:
+        """发送输入状态"""
+        await self._post_with_retry("/ilink/bot/sendtyping", req.to_payload(),
+                                    self.CONFIG_TIMEOUT, "sendtyping")
+
+    async def upload_to_cdn(self, cdn_url: str, encrypted_data: bytes,
+                            file_key: str) -> str:
+        """CDN 上传：POST octet-stream 密文，返回响应头 x-encrypted-param。
+
+        只携带 Content-Type: application/octet-stream，不携带任何公共认证头；
+        4xx 客户端错误立即失败不重试，5xx / 网络异常最多重试 3 次，每次超时 15s。
+        """
+        last_exc: Exception | None = None
+        for attempt in range(1, self.UPLOAD_MAX_RETRIES + 1):
+            try:
+                resp = await self._http.post(
+                    cdn_url, content=encrypted_data,
+                    headers={"Content-Type": "application/octet-stream"},
+                    timeout=self.API_TIMEOUT)
+                if 400 <= resp.status_code < 500:
+                    err = resp.headers.get("x-error-message", "")
+                    raise OpenClawApiError(
+                        ERR_API_FAILURE,
+                        f"cdn upload client error, status={resp.status_code}, "
+                        f"error={err}, file_key={file_key}")
+                resp.raise_for_status()
+                param = resp.headers.get("x-encrypted-param")
+                if not param:
+                    err = resp.headers.get("x-error-message", "")
+                    raise httpx.HTTPError(
+                        f"cdn upload missing x-encrypted-param, error={err}")
+                log.info("cdn upload succeeded, file_key=%s, url=%s",
+                         file_key, redact_url(cdn_url))
+                return param
+            except OpenClawApiError:
+                raise
+            except Exception as e:
+                last_exc = e
+                log.warning("cdn upload failed (attempt %d/%d), url=%s: %s",
+                            attempt, self.UPLOAD_MAX_RETRIES,
+                            redact_url(cdn_url), type(e).__name__)
+        assert last_exc is not None
+        raise last_exc