mchat-client 0.1.0__tar.gz

mchat_client-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: mchat-client
+Version: 0.1.0
+Summary: MChat Python 客户端 SDK
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: paho-mqtt>=2.0.0
+Provides-Extra: dev
+
+# MChat Python 客户端
+
+Python 版 MChat 客户端 SDK，与《技术设计方案》及《消息交互接口与示例》一致。封装 MQTT 连接、请求-响应、收件箱/群消息订阅与事件。
+
+## 要求
+
+- Python >= 3.10
+- 依赖：paho-mqtt >= 2.0.0
+
+## 安装
+
+```bash
+cd client/python
+pip install -e .
+# 或从项目外：pip install -e /path/to/MChat/client/python
+```
+
+## 连接参数
+
+与 `employee.create` 返回的 `mqtt_connection` 对应，构造 `MChatClient` 时传入：
+
+- `broker_host` / `broker_port` / `use_tls`
+- `username`（如 employee_id）/ `password`
+- `employee_id`：当前员工 ID，用于 auth.bind、收件箱订阅、在线状态
+- 可选：`client_id`、`device_id`、`request_timeout_ms`、`skip_auth_bind`
+
+## 使用示例
+
+```python
+from mchat_client import (
+    MChatClient,
+    send_private_message,
+    get_org_tree,
+    get_storage_config,
+    get_agent_capability_list,
+)
+
+client = MChatClient(
+    broker_host="broker.example.com",
+    broker_port=1883,
+    use_tls=False,
+    username="emp_zhangsan_001",
+    password="your_mqtt_password",
+    employee_id="emp_zhangsan_001",
+)
+
+client.connect()
+
+client.on("inbox", lambda payload: print("收件箱:", payload))
+client.on("group", lambda group_id, payload: print("群消息", group_id, payload))
+
+# 发单聊
+send_private_message(client, "emp_lisi_002", "你好")
+
+# 获取组织树
+tree = get_org_tree(client)
+print(tree.get("data", {}).get("employees"))
+
+# 订阅某群（需已知 group_id）
+client.subscribe_group("grp_xxx")
+
+client.disconnect()
+```
+
+## API 概览
+
+- **MChatClient**
+  - `connect()` / `disconnect()`
+  - `request(action, params)`：通用请求，成功返回完整响应体（含 code、message、data），失败抛异常
+  - `subscribe_group(group_id)` / `unsubscribe_group(group_id)`
+  - `on("inbox" | "group" | "connect" | "offline" | "error", callback)`
+- **便捷方法**（见 `api.py`）：`send_private_message`、`send_group_message`、`get_org_tree`、`get_storage_config`、`get_agent_capability_list`
+
+## 示例
+
+同目录下 **example/** 为可运行示例（连接、拉取组织架构与 Agent、收件箱/群消息、可选发测试消息）。详见 [example/README.md](example/README.md)。
+
+## 发布到 PyPI
+
+在 `client/python` 目录下构建并上传（需先安装 `build`、`twine`）：
+
+```bash
+cd client/python
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+发布前请将 `pyproject.toml` 中的 `version` 更新为待发布版本号。

mchat_client-0.1.0/README.md

@@ -0,0 +1,89 @@
+# MChat Python 客户端
+
+Python 版 MChat 客户端 SDK，与《技术设计方案》及《消息交互接口与示例》一致。封装 MQTT 连接、请求-响应、收件箱/群消息订阅与事件。
+
+## 要求
+
+- Python >= 3.10
+- 依赖：paho-mqtt >= 2.0.0
+
+## 安装
+
+```bash
+cd client/python
+pip install -e .
+# 或从项目外：pip install -e /path/to/MChat/client/python
+```
+
+## 连接参数
+
+与 `employee.create` 返回的 `mqtt_connection` 对应，构造 `MChatClient` 时传入：
+
+- `broker_host` / `broker_port` / `use_tls`
+- `username`（如 employee_id）/ `password`
+- `employee_id`：当前员工 ID，用于 auth.bind、收件箱订阅、在线状态
+- 可选：`client_id`、`device_id`、`request_timeout_ms`、`skip_auth_bind`
+
+## 使用示例
+
+```python
+from mchat_client import (
+    MChatClient,
+    send_private_message,
+    get_org_tree,
+    get_storage_config,
+    get_agent_capability_list,
+)
+
+client = MChatClient(
+    broker_host="broker.example.com",
+    broker_port=1883,
+    use_tls=False,
+    username="emp_zhangsan_001",
+    password="your_mqtt_password",
+    employee_id="emp_zhangsan_001",
+)
+
+client.connect()
+
+client.on("inbox", lambda payload: print("收件箱:", payload))
+client.on("group", lambda group_id, payload: print("群消息", group_id, payload))
+
+# 发单聊
+send_private_message(client, "emp_lisi_002", "你好")
+
+# 获取组织树
+tree = get_org_tree(client)
+print(tree.get("data", {}).get("employees"))
+
+# 订阅某群（需已知 group_id）
+client.subscribe_group("grp_xxx")
+
+client.disconnect()
+```
+
+## API 概览
+
+- **MChatClient**
+  - `connect()` / `disconnect()`
+  - `request(action, params)`：通用请求，成功返回完整响应体（含 code、message、data），失败抛异常
+  - `subscribe_group(group_id)` / `unsubscribe_group(group_id)`
+  - `on("inbox" | "group" | "connect" | "offline" | "error", callback)`
+- **便捷方法**（见 `api.py`）：`send_private_message`、`send_group_message`、`get_org_tree`、`get_storage_config`、`get_agent_capability_list`
+
+## 示例
+
+同目录下 **example/** 为可运行示例（连接、拉取组织架构与 Agent、收件箱/群消息、可选发测试消息）。详见 [example/README.md](example/README.md)。
+
+## 发布到 PyPI
+
+在 `client/python` 目录下构建并上传（需先安装 `build`、`twine`）：
+
+```bash
+cd client/python
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+发布前请将 `pyproject.toml` 中的 `version` 更新为待发布版本号。

mchat_client-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mchat-client"
+version = "0.1.0"
+description = "MChat Python 客户端 SDK"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "paho-mqtt>=2.0.0",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications :: Chat",
+]
+[project.optional-dependencies]
+dev = []
+
+[tool.setuptools.packages.find]
+where = ["src"]

mchat_client-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mchat_client-0.1.0/src/mchat_client/__init__.py

@@ -0,0 +1,21 @@
+"""
+MChat Python 客户端 SDK
+"""
+
+from mchat_client.client import MChatClient
+from mchat_client.api import (
+    send_private_message,
+    send_group_message,
+    get_org_tree,
+    get_storage_config,
+    get_agent_capability_list,
+)
+
+__all__ = [
+    "MChatClient",
+    "send_private_message",
+    "send_group_message",
+    "get_org_tree",
+    "get_storage_config",
+    "get_agent_capability_list",
+]

mchat_client-0.1.0/src/mchat_client/api.py

@@ -0,0 +1,54 @@
+"""
+便捷 API：基于 request 封装的常用方法
+"""
+
+from typing import Any, Dict, Optional, Union
+
+from mchat_client.client import MChatClient
+
+
+def send_private_message(
+    client: MChatClient,
+    to_employee_id: str,
+    content: Union[str, Dict[str, Any]],
+    quote_msg_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    """发送私聊消息。"""
+    params: Dict[str, Any] = {"to_employee_id": to_employee_id, "content": content}
+    if quote_msg_id is not None:
+        params["quote_msg_id"] = quote_msg_id
+    return client.request("msg.send_private", params)
+
+
+def send_group_message(
+    client: MChatClient,
+    group_id: str,
+    content: Union[str, Dict[str, Any]],
+    quote_msg_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    """发送群消息。"""
+    params: Dict[str, Any] = {"group_id": group_id, "content": content}
+    if quote_msg_id is not None:
+        params["quote_msg_id"] = quote_msg_id
+    return client.request("msg.send_group", params)
+
+
+def get_org_tree(client: MChatClient) -> Dict[str, Any]:
+    """获取组织架构（部门、员工）。"""
+    return client.request("org.tree")
+
+
+def get_storage_config(client: MChatClient) -> Dict[str, Any]:
+    """获取存储配置。"""
+    return client.request("config.storage")
+
+
+def get_agent_capability_list(
+    client: MChatClient,
+    skill: Optional[str] = None,
+) -> Dict[str, Any]:
+    """获取 Agent 能力列表。"""
+    params: Dict[str, Any] = {}
+    if skill is not None:
+        params["skill"] = skill
+    return client.request("agent.capability_list", params)

mchat_client-0.1.0/src/mchat_client/client.py

@@ -0,0 +1,258 @@
+"""
+MChat Python 客户端：MQTT 连接、请求-响应、收件箱/群订阅与事件
+"""
+
+import json
+import random
+import string
+import threading
+import time
+from typing import Any, Callable, Dict, List, Optional
+
+import paho.mqtt.client as mqtt
+
+REQ_PREFIX = "mchat/msg/req/"
+RESP_PREFIX = "mchat/msg/resp/"
+INBOX_PREFIX = "mchat/inbox/"
+GROUP_PREFIX = "mchat/group/"
+STATUS_PREFIX = "mchat/status/"
+
+
+def _gen_seq_id() -> str:
+    return "seq_" + "".join(random.choices(string.ascii_lowercase + string.digits, k=10)) + "_" + str(int(time.time() * 1000))
+
+
+def _gen_client_id(employee_id: str, device_id: Optional[str] = None) -> str:
+    dev = device_id or "py"
+    uid = "".join(random.choices(string.ascii_lowercase + string.digits, k=8))
+    return f"{employee_id}_{dev}_{uid}"
+
+
+class MChatClient:
+    """MChat 客户端，与《消息交互接口与示例》一致。"""
+
+    def __init__(
+        self,
+        broker_host: str,
+        broker_port: int,
+        username: str,
+        password: str,
+        employee_id: str,
+        use_tls: bool = False,
+        client_id: Optional[str] = None,
+        device_id: Optional[str] = None,
+        request_timeout_ms: int = 30000,
+        skip_auth_bind: bool = False,
+    ):
+        self._broker_host = broker_host
+        self._broker_port = broker_port
+        self._use_tls = use_tls
+        self._username = username
+        self._password = password
+        self._employee_id = employee_id
+        self._client_id = (client_id or "").strip() or _gen_client_id(employee_id, device_id)
+        self._request_timeout_ms = request_timeout_ms
+        self._skip_auth_bind = skip_auth_bind
+
+        self._client: Optional[mqtt.Client] = None
+        self._pending: Dict[str, Dict[str, Any]] = {}
+        self._pending_lock = threading.Lock()
+        self._connect_event = threading.Event()
+        self._connect_error: Optional[Exception] = None
+
+        self._listeners: Dict[str, List[Callable[..., None]]] = {
+            "inbox": [],
+            "group": [],
+            "connect": [],
+            "offline": [],
+            "error": [],
+        }
+
+    @property
+    def connected(self) -> bool:
+        return self._client is not None and self._client.is_connected()
+
+    def get_client_id(self) -> str:
+        return self._client_id
+
+    def connect(self) -> None:
+        """连接 Broker，订阅 resp/inbox，可选 auth.bind，发布 online。"""
+        self._connect_event.clear()
+        self._connect_error = None
+
+        try:
+            client = mqtt.Client(
+                callback_api_version=getattr(mqtt.CallbackAPIVersion, "VERSION1", None) or mqtt.CallbackAPIVersion.VERSION1,
+                client_id=self._client_id,
+                protocol=mqtt.MQTTv311,
+            )
+            client.username_pw_set(self._username, self._password)
+
+            will_payload = json.dumps({"status": "offline", "updated_at": time.strftime("%Y-%m-%dT%H:%M:%S.000Z", time.gmtime())})
+            client.will_set(
+                f"{STATUS_PREFIX}{self._employee_id}",
+                will_payload,
+                qos=1,
+                retain=True,
+            )
+
+            client.on_connect = self._on_connect
+            client.on_message = self._on_message
+            client.on_disconnect = self._on_disconnect
+            if hasattr(client, "on_connect_fail"):
+                client.on_connect_fail = self._on_connect_fail
+
+            if self._use_tls:
+                client.tls_set()
+
+            client.connect(self._broker_host, self._broker_port, 60)
+            self._client = client
+            client.loop_start()
+
+            if not self._connect_event.wait(timeout=15):
+                raise TimeoutError("Connection timeout")
+            if self._connect_error:
+                raise self._connect_error
+
+        except Exception:
+            self._client = None
+            raise
+
+    def _on_connect(self, client: mqtt.Client, userdata: Any, flags: Any, rc: int) -> None:
+        if rc != 0:
+            self._connect_error = ConnectionError(f"Connect failed: {rc}")
+            self._connect_event.set()
+            return
+        try:
+            client.subscribe(f"{RESP_PREFIX}{self._client_id}/+", qos=1)
+            client.subscribe(f"{INBOX_PREFIX}{self._employee_id}", qos=1)
+            online_payload = json.dumps({"status": "online", "updated_at": time.strftime("%Y-%m-%dT%H:%M:%S.000Z", time.gmtime())})
+            client.publish(f"{STATUS_PREFIX}{self._employee_id}", online_payload, qos=1, retain=True)
+            if not self._skip_auth_bind:
+                try:
+                    r = self._request_impl(client, "auth.bind", {"employee_id": self._employee_id})
+                    if r.get("code") != 0:
+                        print(f"[mchat] auth.bind failed: {r.get('message')}")
+                except Exception as e:
+                    print(f"[mchat] auth.bind error: {e}")
+            for fn in self._listeners["connect"]:
+                try:
+                    fn()
+                except Exception:
+                    pass
+        except Exception as e:
+            self._connect_error = e
+        finally:
+            self._connect_event.set()
+
+    def _on_message(self, client: mqtt.Client, userdata: Any, msg: Any) -> None:
+        topic = msg.topic
+        try:
+            payload_str = msg.payload.decode("utf-8") if isinstance(msg.payload, bytes) else msg.payload
+        except Exception:
+            return
+        if topic.startswith(RESP_PREFIX + self._client_id + "/"):
+            seq_id = topic[len(RESP_PREFIX + self._client_id + "/") :]
+            with self._pending_lock:
+                p = self._pending.pop(seq_id, None)
+            if p:
+                try:
+                    body = json.loads(payload_str)
+                    p["event"].set()
+                    p["result"] = body
+                except Exception:
+                    p["event"].set()
+                    p["error"] = ValueError("Invalid response JSON")
+            return
+        if topic == f"{INBOX_PREFIX}{self._employee_id}":
+            try:
+                body = json.loads(payload_str)
+                for fn in self._listeners["inbox"]:
+                    try:
+                        fn(body)
+                    except Exception:
+                        pass
+            except Exception:
+                pass
+            return
+        if topic.startswith(GROUP_PREFIX):
+            group_id = topic[len(GROUP_PREFIX) :]
+            try:
+                body = json.loads(payload_str)
+                for fn in self._listeners["group"]:
+                    try:
+                        fn(group_id, body)
+                    except Exception:
+                        pass
+            except Exception:
+                pass
+
+    def _on_disconnect(self, client: mqtt.Client, userdata: Any, rc: int) -> None:
+        for fn in self._listeners["offline"]:
+            try:
+                fn()
+            except Exception:
+                pass
+
+    def _on_connect_fail(self, client: mqtt.Client, userdata: Any) -> None:
+        self._connect_error = ConnectionError("Connect failed")
+        self._connect_event.set()
+
+    def _request_impl(self, client: mqtt.Client, action: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        seq_id = _gen_seq_id()
+        topic = f"{REQ_PREFIX}{self._client_id}/{seq_id}"
+        payload = json.dumps({"action": action, **params})
+        event = threading.Event()
+        with self._pending_lock:
+            self._pending[seq_id] = {"event": event, "result": None, "error": None}
+        client.publish(topic, payload, qos=1)
+        timeout_s = self._request_timeout_ms / 1000.0
+        if not event.wait(timeout=timeout_s):
+            with self._pending_lock:
+                self._pending.pop(seq_id, None)
+            raise TimeoutError("Request timeout")
+        with self._pending_lock:
+            p = self._pending.get(seq_id)
+        if p and p.get("error"):
+            raise p["error"]
+        if p and p.get("result") is not None:
+            return p["result"]
+        raise RuntimeError("No response")
+
+    def request(self, action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """发起一次请求，成功时返回 data 在其中的响应体；code!=0 或异常时抛错。"""
+        if not self._client or not self._client.is_connected():
+            raise RuntimeError("Not connected")
+        params = params or {}
+        r = self._request_impl(self._client, action, params)
+        if r.get("code") != 0:
+            raise RuntimeError(r.get("message") or f"code {r.get('code')}")
+        return r
+
+    def subscribe_group(self, group_id: str) -> None:
+        """订阅群消息。"""
+        if not self._client or not self._client.is_connected():
+            raise RuntimeError("Not connected")
+        self._client.subscribe(f"{GROUP_PREFIX}{group_id}", qos=1)
+
+    def unsubscribe_group(self, group_id: str) -> None:
+        """取消订阅群。"""
+        if self._client:
+            self._client.unsubscribe(f"{GROUP_PREFIX}{group_id}")
+
+    def on(self, event: str, fn: Callable[..., None]) -> None:
+        """注册事件：inbox, group, connect, offline, error。"""
+        if event in self._listeners:
+            self._listeners[event].append(fn)
+
+    def disconnect(self) -> None:
+        """断开连接。"""
+        if self._client:
+            with self._pending_lock:
+                for p in self._pending.values():
+                    p["event"].set()
+                    p["error"] = RuntimeError("Disconnected")
+                self._pending.clear()
+            self._client.loop_stop()
+            self._client.disconnect()
+            self._client = None

mchat_client-0.1.0/src/mchat_client.egg-info/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: mchat-client
+Version: 0.1.0
+Summary: MChat Python 客户端 SDK
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: paho-mqtt>=2.0.0
+Provides-Extra: dev
+
+# MChat Python 客户端
+
+Python 版 MChat 客户端 SDK，与《技术设计方案》及《消息交互接口与示例》一致。封装 MQTT 连接、请求-响应、收件箱/群消息订阅与事件。
+
+## 要求
+
+- Python >= 3.10
+- 依赖：paho-mqtt >= 2.0.0
+
+## 安装
+
+```bash
+cd client/python
+pip install -e .
+# 或从项目外：pip install -e /path/to/MChat/client/python
+```
+
+## 连接参数
+
+与 `employee.create` 返回的 `mqtt_connection` 对应，构造 `MChatClient` 时传入：
+
+- `broker_host` / `broker_port` / `use_tls`
+- `username`（如 employee_id）/ `password`
+- `employee_id`：当前员工 ID，用于 auth.bind、收件箱订阅、在线状态
+- 可选：`client_id`、`device_id`、`request_timeout_ms`、`skip_auth_bind`
+
+## 使用示例
+
+```python
+from mchat_client import (
+    MChatClient,
+    send_private_message,
+    get_org_tree,
+    get_storage_config,
+    get_agent_capability_list,
+)
+
+client = MChatClient(
+    broker_host="broker.example.com",
+    broker_port=1883,
+    use_tls=False,
+    username="emp_zhangsan_001",
+    password="your_mqtt_password",
+    employee_id="emp_zhangsan_001",
+)
+
+client.connect()
+
+client.on("inbox", lambda payload: print("收件箱:", payload))
+client.on("group", lambda group_id, payload: print("群消息", group_id, payload))
+
+# 发单聊
+send_private_message(client, "emp_lisi_002", "你好")
+
+# 获取组织树
+tree = get_org_tree(client)
+print(tree.get("data", {}).get("employees"))
+
+# 订阅某群（需已知 group_id）
+client.subscribe_group("grp_xxx")
+
+client.disconnect()
+```
+
+## API 概览
+
+- **MChatClient**
+  - `connect()` / `disconnect()`
+  - `request(action, params)`：通用请求，成功返回完整响应体（含 code、message、data），失败抛异常
+  - `subscribe_group(group_id)` / `unsubscribe_group(group_id)`
+  - `on("inbox" | "group" | "connect" | "offline" | "error", callback)`
+- **便捷方法**（见 `api.py`）：`send_private_message`、`send_group_message`、`get_org_tree`、`get_storage_config`、`get_agent_capability_list`
+
+## 示例
+
+同目录下 **example/** 为可运行示例（连接、拉取组织架构与 Agent、收件箱/群消息、可选发测试消息）。详见 [example/README.md](example/README.md)。
+
+## 发布到 PyPI
+
+在 `client/python` 目录下构建并上传（需先安装 `build`、`twine`）：
+
+```bash
+cd client/python
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+发布前请将 `pyproject.toml` 中的 `version` 更新为待发布版本号。

mchat_client-0.1.0/src/mchat_client.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+src/mchat_client/__init__.py
+src/mchat_client/api.py
+src/mchat_client/client.py
+src/mchat_client.egg-info/PKG-INFO
+src/mchat_client.egg-info/SOURCES.txt
+src/mchat_client.egg-info/dependency_links.txt
+src/mchat_client.egg-info/requires.txt
+src/mchat_client.egg-info/top_level.txt

mchat_client-0.1.0/src/mchat_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mchat_client-0.1.0/src/mchat_client.egg-info/requires.txt

@@ -0,0 +1,3 @@
+paho-mqtt>=2.0.0
+
+[dev]

mchat_client-0.1.0/src/mchat_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+mchat_client