wxpy4 0.2.2__py3-none-any.whl

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 wx4py Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,160 @@
+# wx4py
+
+Python 微信自动化工具 — 基于 UIAutomation 的 Windows Qt 版微信桌面客户端自动化库。
+
+## 功能
+
+| 模块 | 功能 |
+|------|------|
+| **消息发送** | 向联系人或群聊发送文本消息、文件，支持批量发送 |
+| **消息监听** | 实时监听群聊消息，基于轮询模式的稳定监听器 |
+| **自动回复** | 处理器管线（Handler/Action），支持多 handler 组合 |
+| **消息转发** | 跨群转发文本/图片/卡片消息，含转发规则引擎 |
+| **AI 集成** | 内置 OpenAI 兼容接口的 AI 客户端，支持流式回复 |
+| **群组管理** | 获取群列表、搜索群聊、管理群成员 |
+| **剪贴板** | Markdown → HTML → 剪贴板，支持富文本发送 |
+| **窗口控制** | 自动连接微信窗口、注册表修复、托盘恢复 |
+
+## 安装
+
+```bash
+pip install wxpy4
+```
+
+**系统要求**: Windows 10+，Qt 版微信客户端（WeChat.exe）。
+
+## 快速开始
+
+```python
+from wx4py import WeChatClient
+
+# 连接微信
+wx = WeChatClient()
+wx.connect()
+
+# 发送消息给联系人
+wx.chat_window.send_to("张三", "你好！")
+
+# 发送文件到群聊
+wx.chat_window.send_file_to("测试群", "report.xlsx", target_type="group")
+
+# 批量发送
+wx.chat_window.batch_send(["群1", "群2"], "通知：明天 9 点开会")
+
+# 使用上下文管理器（自动 disconnect）
+with WeChatClient() as wx:
+    wx.chat_window.send_to("张三", "Hello from context manager")
+```
+
+## 群消息监听与自动回复
+
+```python
+from wx4py import WeChatClient, MessageHandler, ReplyAction
+
+class EchoHandler(MessageHandler):
+    def handle(self, msg):
+        if "你好" in msg.text:
+            return ReplyAction(f"你好 {msg.sender}！")
+        return None
+
+wx = WeChatClient()
+wx.connect()
+processor = wx.process_groups(["测试群"], EchoHandler())
+# processor.run_forever()  # 阻塞运行
+processor.stop()  # 或按需停止
+```
+
+## 消息转发
+
+```python
+from wx4py import WeChatClient, GroupForwardRule, ForwardRuleHandler
+
+rule = GroupForwardRule(
+    source_groups=["源群A"],
+    target_groups=["目标群B"],
+    text_only=True,
+)
+handler = ForwardRuleHandler(rule)
+
+wx = WeChatClient()
+wx.connect()
+processor = wx.process_groups(["源群A"], handler)
+```
+
+## AI 自动回复
+
+```python
+from wx4py import WeChatClient, AIResponder, AIConfig
+
+config = AIConfig(
+    base_url="https://api.openai.com/v1",
+    api_key="sk-xxx",
+    model="gpt-4o",
+)
+responder = AIResponder(config, system_prompt="你是一个友好的助手")
+
+wx = WeChatClient()
+wx.connect()
+processor = wx.process_groups(["客服群"], responder.to_handler())
+```
+
+## API 概览
+
+### 核心类
+
+| 类 | 说明 |
+|----|------|
+| `WeChatClient` | 主入口：连接微信、获取聊天窗口和群管理器 |
+| `ChatWindow` | 聊天窗口：发送消息、文件、搜索 |
+| `GroupManager` | 群管理器：获取群列表、搜索群 |
+| `WeChatGroupListener` | 群消息监听器：轮询新消息 |
+| `WeChatGroupProcessor` | 消息处理器：管理监听生命周期 |
+
+### 消息处理
+
+| 类 | 说明 |
+|----|------|
+| `MessageHandler` | 抽象处理器基类 |
+| `CallbackHandler` | 回调式处理器（函数式风格） |
+| `AsyncCallbackHandler` | 异步回调处理器 |
+| `ReplyAction` | 回复动作 |
+| `ForwardAction` | 转发动作 |
+
+### 消息转发
+
+| 类 | 说明 |
+|----|------|
+| `GroupForwardRule` | 转发规则定义 |
+| `ForwardRuleHandler` | 转发规则处理器 |
+| `ForwardTarget` | 转发目标 |
+| `ForwardPayload` | 转发载荷 |
+
+### AI 集成
+
+| 类 | 说明 |
+|----|------|
+| `AIClient` | OpenAI 兼容 API 客户端 |
+| `AIConfig` | AI 配置（base_url, api_key, model） |
+| `AIResponder` | AI 自动回复器 |
+| `MessageEvent` | 消息事件数据类 |
+
+## 技术栈
+
+- **UIAutomation**: Windows UI 自动化框架
+- **COM (comtypes)**: Windows 组件对象模型交互
+- **pywin32**: Windows API 调用
+- **BeautifulSoup**: HTML 解析（聊天内容解析）
+- **Pillow**: 图片处理
+- **Markdown**: Markdown → HTML 转换
+
+## 注意事项
+
+1. **仅支持 Windows** — 依赖 UIAutomation、pywin32、comtypes 等 Windows 专用库
+2. **仅支持 Qt 版微信** — 不支持 UWP 版（Microsoft Store 版本）
+3. **微信需要保持前台运行** — 自动化通过 UI 操作实现，微信窗口不能被最小化到系统托盘
+4. **首次使用需要管理员权限** — 用于注册 COM 组件
+5. **Python 3.8+** — 使用了 `from __future__ import annotations`
+
+## License
+
+MIT

__init__.py

@@ -0,0 +1,62 @@
+# -*- coding: utf-8 -*-
+"""
+wx4py - 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__ = "wx4py Team"
+
+__all__ = [
+    "WeChatClient",
+    "AIClient",
+    "AIConfig",
+    "AIResponder",
+    "MessageEvent",
+    "WeChatGroupListener",
+    "MessageAction",
+    "ReplyAction",
+    "ForwardAction",
+    "MessageHandler",
+    "CallbackHandler",
+    "AsyncCallbackHandler",
+    "WeChatGroupProcessor",
+    "ForwardTarget",
+    "ForwardPayload",
+    "GroupForwardRule",
+    "ForwardRuleHandler",
+    "WeChatError",
+    "WeChatNotFoundError",
+    "WeChatNotConnectedError",
+    "ControlNotFoundError",
+    "TargetNotFoundError",
+    "RegistryError",
+]

_version.py

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

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()
+        )