pgwxauto 0.1.2__py3-none-any.whl

pgwxauto/__init__.py

@@ -0,0 +1,62 @@
+# -*- coding: utf-8 -*-
+"""
+pgwxauto - Python 微信自动化工具
+
+基于 UIAutomation 的微信自动化 Python 库，支持 Windows Qt 版本微信客户端。
+"""
+
+from ._version import __version__
+from .ai import AIClient, AIConfig, AIResponder
+from .client import WeChatClient
+from .features.messaging.forwarder import (
+    ForwardPayload,
+    ForwardRuleHandler,
+    ForwardTarget,
+    GroupForwardRule,
+)
+from .features.messaging.listener import MessageEvent, WeChatGroupListener
+from .features.messaging.processor import (
+    AsyncCallbackHandler,
+    CallbackHandler,
+    ForwardAction,
+    MessageAction,
+    MessageHandler,
+    ReplyAction,
+    WeChatGroupProcessor,
+)
+from .core.exceptions import (
+    WeChatError,
+    WeChatNotFoundError,
+    WeChatNotConnectedError,
+    ControlNotFoundError,
+    TargetNotFoundError,
+    RegistryError,
+)
+
+__author__ = "盘古科技"
+
+__all__ = [
+    "WeChatClient",
+    "AIClient",
+    "AIConfig",
+    "AIResponder",
+    "MessageEvent",
+    "WeChatGroupListener",
+    "MessageAction",
+    "ReplyAction",
+    "ForwardAction",
+    "MessageHandler",
+    "CallbackHandler",
+    "AsyncCallbackHandler",
+    "WeChatGroupProcessor",
+    "ForwardTarget",
+    "ForwardPayload",
+    "GroupForwardRule",
+    "ForwardRuleHandler",
+    "WeChatError",
+    "WeChatNotFoundError",
+    "WeChatNotConnectedError",
+    "ControlNotFoundError",
+    "TargetNotFoundError",
+    "RegistryError",
+]

pgwxauto/_version.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+"""包版本号的唯一来源。"""
+
+__version__ = "0.1.2"

pgwxauto/ai.py

@@ -0,0 +1,292 @@
+# -*- coding: utf-8 -*-
+"""通用 AI 调用模块。
+
+目标：
+    让自动回复场景只需要传入 base_url、api_format、model、api_key 即可使用。
+
+支持格式：
+    - completions: OpenAI-compatible /chat/completions
+    - responses: OpenAI Responses API
+    - anthropic: Anthropic-compatible /messages
+"""
+
+from __future__ import annotations
+
+import json
+import socket
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Dict, List, Literal, Optional
+
+from .features.messaging.listener import MessageEvent
+
+ApiFormat = Literal["completions", "responses", "anthropic"]
+
+
+DEFAULT_SYSTEM_PROMPT = """你正在微信群聊里回复消息。
+要求：
+1. 回复自然、简短，像真人聊天。
+2. 不要说自己是 AI。
+3. 不要每次都解释太多。
+4. 如果消息不需要回复，可以只返回空字符串。
+"""
+
+
+@dataclass(frozen=True)
+class AIConfig:
+    """AI 接口配置。"""
+
+    base_url: str
+    model: str
+    api_key: str
+    api_format: ApiFormat = "completions"
+    system_prompt: str = DEFAULT_SYSTEM_PROMPT
+    temperature: float = 0.7
+    max_tokens: int = 300
+    timeout: float = 60.0
+    enable_thinking: Optional[bool] = False
+
+
+class AIClient:
+    """轻量级 AI 客户端。"""
+
+    def __init__(self, config: AIConfig):
+        self.config = config
+        self.api_format = self._normalize_api_format(config.api_format)
+        self.url = self._build_endpoint(config.base_url, self.api_format)
+
+    def chat(self, messages: List[dict], system_prompt: Optional[str] = None) -> str:
+        """发送对话并返回文本回复。"""
+        request = self._build_request(messages, system_prompt or self.config.system_prompt)
+        headers = self._build_headers()
+
+        http_request = urllib.request.Request(
+            url=self.url,
+            data=json.dumps(request, ensure_ascii=False).encode("utf-8"),
+            headers=headers,
+            method="POST",
+        )
+
+        try:
+            with urllib.request.urlopen(http_request, timeout=self.config.timeout) as response:
+                data = json.loads(response.read().decode("utf-8"))
+        except urllib.error.HTTPError as exc:
+            body = exc.read().decode("utf-8", errors="replace")
+            raise RuntimeError(self._format_http_error(exc.code, body)) from exc
+        except urllib.error.URLError as exc:
+            reason = exc.reason
+            if isinstance(reason, socket.gaierror):
+                raise RuntimeError(
+                    f"AI 接口域名解析失败，请检查网络、DNS、代理或 base_url: {self.config.base_url}"
+                ) from exc
+            raise RuntimeError(f"AI 接口网络请求失败: {reason}") from exc
+
+        result = self._extract_text(data)
+        if not result:
+            raise RuntimeError(f"AI 接口返回为空: {json.dumps(data, ensure_ascii=False)}")
+        return self._sanitize_output(result)
+
+    def _build_request(self, messages: List[dict], system_prompt: str) -> dict:
+        if self.api_format == "completions":
+            request = {
+                "model": self.config.model,
+                "messages": [
+                    {"role": "system", "content": system_prompt},
+                    *messages,
+                ],
+                "temperature": self.config.temperature,
+                "max_tokens": self.config.max_tokens,
+            }
+            if self.config.enable_thinking is not None:
+                request["enable_thinking"] = self.config.enable_thinking
+            return request
+
+        if self.api_format == "responses":
+            return {
+                "model": self.config.model,
+                "input": [
+                    {
+                        "role": "system",
+                        "content": [{"type": "input_text", "text": system_prompt}],
+                    },
+                    *[
+                        {
+                            "role": message["role"],
+                            "content": [{"type": "input_text", "text": message["content"]}],
+                        }
+                        for message in messages
+                    ],
+                ],
+                "temperature": self.config.temperature,
+                "max_output_tokens": self.config.max_tokens,
+            }
+
+        if self.api_format == "anthropic":
+            return {
+                "model": self.config.model,
+                "system": system_prompt,
+                "messages": messages,
+                "max_tokens": self.config.max_tokens,
+                "temperature": self.config.temperature,
+            }
+
+        raise ValueError(f"不支持的 api_format: {self.api_format}")
+
+    def _build_headers(self) -> Dict[str, str]:
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "Cache-Control": "no-cache",
+            "User-Agent": (
+                "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+                "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36"
+            ),
+            "Authorization": f"Bearer {self.config.api_key}",
+        }
+
+        if self.api_format == "anthropic":
+            headers.pop("Authorization", None)
+            headers["x-api-key"] = self.config.api_key
+            headers["anthropic-version"] = "2023-06-01"
+
+        return headers
+
+    def _extract_text(self, data: dict) -> str:
+        if self.api_format == "completions":
+            return (
+                data.get("choices", [{}])[0]
+                .get("message", {})
+                .get("content", "")
+            )
+
+        if self.api_format == "responses":
+            if data.get("output_text"):
+                return data["output_text"]
+            for item in data.get("output", []) or []:
+                for content in item.get("content", []) or []:
+                    if content.get("type") == "output_text" and content.get("text"):
+                        return content["text"]
+            return ""
+
+        if self.api_format == "anthropic":
+            return "\n".join(
+                item.get("text", "")
+                for item in data.get("content", []) or []
+                if item.get("type") == "text" and item.get("text")
+            )
+
+        return ""
+
+    def _format_http_error(self, status: int, body: str) -> str:
+        lower = body.lower()
+        if status in (401, 403) and any(word in lower for word in ("api key", "apikey", "auth", "unauthorized", "permission")):
+            return f"AI 认证失败，请检查 api_key。HTTP {status}: {body}"
+        if status == 404:
+            return f"AI endpoint 不存在，请检查 base_url 或 api_format。URL={self.url} HTTP {status}: {body}"
+        if "model" in lower and any(word in lower for word in ("not found", "invalid", "not exist", "unsupported")):
+            return f"AI 模型不可用，请检查 model。HTTP {status}: {body}"
+        return f"AI HTTP 请求失败。URL={self.url} HTTP {status}: {body}"
+
+    @staticmethod
+    def _normalize_api_format(api_format: str) -> ApiFormat:
+        if api_format == "response":
+            return "responses"
+        if api_format not in {"completions", "responses", "anthropic"}:
+            raise ValueError("api_format must be one of: completions, responses, anthropic")
+        return api_format  # type: ignore[return-value]
+
+    @staticmethod
+    def _build_endpoint(base_url: str, api_format: ApiFormat) -> str:
+        if not base_url or not base_url.strip():
+            raise ValueError("base_url must not be empty")
+
+        normalized = base_url.strip()
+        if not normalized.lower().startswith(("http://", "https://")):
+            normalized = f"https://{normalized}"
+        normalized = normalized.rstrip("/")
+        path = AIClient._get_url_path(normalized)
+
+        if api_format == "completions":
+            if AIClient._has_path_suffix(path, ["/chat/completions", "/v1/chat/completions", "/completions", "/v1/completions"]):
+                return normalized
+            if AIClient._has_path_suffix(path, ["/v1"]):
+                return f"{normalized}/chat/completions"
+            return f"{normalized}/v1/chat/completions"
+
+        if api_format == "responses":
+            if AIClient._has_path_suffix(path, ["/responses", "/v1/responses"]):
+                return normalized
+            if AIClient._has_path_suffix(path, ["/v1"]):
+                return f"{normalized}/responses"
+            return f"{normalized}/v1/responses"
+
+        if api_format == "anthropic":
+            if AIClient._has_path_suffix(path, ["/messages", "/v1/messages"]):
+                return normalized
+            if AIClient._has_path_suffix(path, ["/v1"]):
+                return f"{normalized}/messages"
+            return f"{normalized}/v1/messages"
+
+        raise ValueError(f"不支持的 api_format: {api_format}")
+
+    @staticmethod
+    def _get_url_path(url: str) -> str:
+        marker = "://"
+        if marker not in url:
+            return ""
+        path_start = url.find("/", url.find(marker) + len(marker))
+        return url[path_start:] if path_start >= 0 else ""
+
+    @staticmethod
+    def _has_path_suffix(path: str, suffixes: List[str]) -> bool:
+        return any(path == suffix or path.endswith(suffix) for suffix in suffixes)
+
+    @staticmethod
+    def _sanitize_output(text: str) -> str:
+        return str(text or "").strip().strip("\"'")
+
+
+class AIResponder:
+    """面向微信群自动回复的 AI 回调封装。"""
+
+    def __init__(
+        self,
+        client: AIClient,
+        *,
+        context_size: int = 8,
+        reply_on_at: bool = True,
+    ):
+        self.client = client
+        self.context_size = context_size
+        self.reply_on_at = reply_on_at
+        self.contexts: Dict[str, List[dict]] = {}
+
+    def __call__(self, event: MessageEvent) -> str:
+        if self.reply_on_at and not event.is_at_me:
+            return ""
+
+        content = self._strip_at(event.content, event.group_nickname)
+        if not content:
+            return ""
+
+        context = self.contexts.setdefault(event.group, [])
+        context.append({"role": "user", "content": content})
+        del context[:-self.context_size]
+
+        reply = self.client.chat(context)
+        if reply:
+            context.append({"role": "assistant", "content": reply})
+            del context[:-self.context_size]
+        return reply
+
+    @staticmethod
+    def _strip_at(content: str, nickname: Optional[str]) -> str:
+        if not nickname:
+            return content.strip()
+        return (
+            content
+            .replace(f"@{nickname}\u2005", "")
+            .replace(f"@{nickname}", "")
+            .strip()
+        )

pgwxauto/client.py

@@ -0,0 +1,164 @@
+# -*- coding: utf-8 -*-
+"""
+pgwxauto 客户端
+
+pgwxauto 的主入口。
+"""
+from .core.exceptions import WeChatNotFoundError
+from .core.window import WeChatWindow
+from .features.chat import ChatWindow
+from .features.groups import GroupManager
+from .features.messaging.listener import OutgoingMessageRegistry
+from .features.messaging.processor import MessageHandler, WeChatGroupProcessor
+from .utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class WeChatClient:
+    """
+    pgwxauto 客户端
+
+    用于在 Windows 上自动化操作微信的主类。
+
+    用法:
+        wx = WeChatClient()
+        wx.connect()
+
+        # 发送消息给联系人
+        wx.chat_window.send_to("大号", "Hello!")
+
+        # 发送消息给群聊
+        wx.chat_window.send_to("测试群", "Hello!", target_type='group')
+
+        # 批量发送
+        wx.chat_window.batch_send(["群1", "群2"], "Hello!")
+    """
+
+    def __init__(self, auto_connect: bool = False):
+        """
+        初始化微信客户端。
+
+        Args:
+            auto_connect: 如果为 True，则在初始化时自动连接
+        """
+        self._window = WeChatWindow()
+        self._chat_window: ChatWindow = None
+        self._group_manager: GroupManager = None
+        self._services = []
+        self._outgoing_registry = OutgoingMessageRegistry(120.0)
+
+        if auto_connect:
+            self.connect()
+
+    def connect(self) -> bool:
+        """
+        连接微信窗口。
+
+        流程：
+        1. 检查并修复注册表（RunningState）
+        2. 查找并绑定微信窗口
+        3. 初始化 UIAutomation
+
+        Returns:
+            bool: 连接成功返回 True
+
+        Raises:
+            WeChatNotFoundError: 未找到微信时抛出
+        """
+        logger.info("正在连接微信...")
+        result = self._window.connect()
+        if result:
+            self._chat_window = ChatWindow(self._window)
+            self._group_manager = GroupManager(self._window)
+        return result
+
+    def disconnect(self) -> None:
+        """断开微信连接"""
+        for service in list(self._services):
+            service.stop()
+        self._services.clear()
+        self._window.disconnect()
+        self._chat_window = None
+        self._group_manager = None
+        logger.info("已断开微信连接")
+
+    def process_groups(
+        self,
+        groups,
+        handlers,
+        *,
+        ignore_client_sent: bool = True,
+        block: bool = False,
+        **options,
+    ) -> WeChatGroupProcessor:
+        """统一处理多个群聊消息。
+
+        Args:
+            groups: 群聊名称列表。
+            handlers: 一个或多个 MessageHandler。
+            ignore_client_sent: 是否忽略本库发送后回流的消息。
+            block: 是否阻塞当前线程运行监听循环。
+            **options: 传给监听器的调度参数，例如 tick、batch_size、tail_size、
+                reply_on_at、group_nicknames。
+
+        Returns:
+            WeChatGroupProcessor: 处理器实例，可调用 stop() 停止。
+        """
+        if not self.is_connected:
+            self.connect()
+
+        if isinstance(handlers, MessageHandler):
+            normalized_handlers = [handlers]
+        else:
+            normalized_handlers = list(handlers)
+
+        processor = WeChatGroupProcessor(
+            self,
+            groups,
+            normalized_handlers,
+            ignore_client_sent=ignore_client_sent,
+            **options,
+        )
+        self._services.append(processor)
+        return processor.start(block=block)
+
+    @property
+    def window(self) -> WeChatWindow:
+        """获取窗口管理器"""
+        return self._window
+
+    @property
+    def chat_window(self) -> ChatWindow:
+        """获取聊天窗口页面，用于发送消息"""
+        if not self._chat_window:
+            raise WeChatNotFoundError("未连接到微信")
+        return self._chat_window
+
+    @property
+    def group_manager(self) -> GroupManager:
+        """获取群组管理器，用于群操作"""
+        if not self._group_manager:
+            raise WeChatNotFoundError("未连接到微信")
+        return self._group_manager
+
+    @property
+    def is_connected(self) -> bool:
+        """检查是否已连接微信"""
+        return self._window.is_connected
+
+    @property
+    def outgoing_registry(self) -> OutgoingMessageRegistry:
+        """获取客户端级共享的已发送消息注册表。"""
+        return self._outgoing_registry
+
+    def __enter__(self):
+        """上下文管理器入口"""
+        if not self.is_connected:
+            self.connect()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """上下文管理器出口"""
+        self.disconnect()
+        return False

pgwxauto/config.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+"""配置项"""
+import os
+from pathlib import Path
+
+# 超时设置（秒）
+SEARCH_TIMEOUT = 5
+OPERATION_INTERVAL = 0.3
+SEARCH_RETRY_COUNT = 3
+SEARCH_RETRY_DELAY_MIN = 0.8
+SEARCH_RETRY_DELAY_MAX = 1.5
+SEND_RETRY_COUNT = 2
+SEND_RECONNECT_RETRY_COUNT = 1
+BATCH_SEND_INTERVAL_MIN = 2.0
+BATCH_SEND_INTERVAL_MAX = 3.0
+SEND_JITTER_MIN = 0.2
+SEND_JITTER_MAX = 0.6
+SEND_DEDUP_WINDOW_SECONDS = 60
+
+# 目标验证
+ALLOWED_GROUPS = tuple(
+    item.strip()
+    for item in os.environ.get("WECHAT_ALLOWED_GROUPS", "").split(",")
+    if item.strip()
+)
+
+# 日志配置
+LOG_LEVEL = os.environ.get('WECHAT_LOG_LEVEL', 'INFO')
+LOG_FORMAT = '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+LOG_FILE = os.environ.get("WECHAT_LOG_FILE", str(Path.cwd() / "pgwxauto.log"))
+SEND_AUDIT_LOG_FILE = os.environ.get(
+    "WECHAT_SEND_AUDIT_LOG_FILE",
+    str(Path.cwd() / "pgwxauto_send_audit.jsonl"),
+)

pgwxauto/core/__init__.py

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+"""Windows 平台与 UIAutomation 底层能力。"""
+
+from .exceptions import (
+    ControlNotFoundError,
+    RegistryError,
+    TargetNotFoundError,
+    UIAError,
+    WeChatError,
+    WeChatNotConnectedError,
+    WeChatNotFoundError,
+)
+from .uia_wrapper import UIAWrapper
+from .window import WeChatWindow
+
+__all__ = [
+    "WeChatWindow",
+    "UIAWrapper",
+    "WeChatError",
+    "WeChatNotFoundError",
+    "WeChatNotConnectedError",
+    "UIAError",
+    "ControlNotFoundError",
+    "TargetNotFoundError",
+    "RegistryError",
+]