miti-agent-sdk 0.1.0__tar.gz

miti_agent_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: miti-agent-sdk
+Version: 0.1.0
+Summary: Miti Agent SDK – connect third-party agents to Miti IM
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+
+# miti-agent-sdk
+
+Connect third-party agents (Hermes, OpenClaw, Claude Code, etc.) to the Miti IM platform.
+
+## Installation
+
+```bash
+pip install miti-agent-sdk
+```
+
+## Quick Start
+
+```python
+from miti_agent_sdk import MitiAgent
+
+agent = MitiAgent(
+    app_id="cli_xxx",
+    app_secret="secret_xxx",
+)
+
+# 单聊消息
+@agent.on_message
+async def handle(event):
+    user_text = event.event.message.content.get("text", "")
+    await event.reply(f"收到：{user_text}")
+
+# 群 @ 消息
+@agent.on_group_at
+async def handle_group(event):
+    text = event.event.message.content.get("text", "")
+    await event.reply(f"群收到：{text}")
+
+agent.run()
+```
+
+SDK 内部自动处理：Token 获取/刷新、WebSocket 保活、指数退避重连。
+
+## 环境配置
+
+`base_url` 按以下优先级决定（先找到先用）：
+
+| 优先级 | 来源 | 示例 |
+|--------|------|------|
+| 1（最高） | 构造函数 `base_url=` 参数 | `MitiAgent(base_url="https://...")` |
+| 2 | 环境变量 `MITI_API_BASE_URL` | `export MITI_API_BASE_URL="https://..."` |
+| 3（默认） | 正式环境 | `https://www.miti.chat/chat` |
+
+大多数场景下**不需要配置任何东西**，SDK 自动连接正式环境。
+
+本地开发调试时，通过环境变量指向本地 appserver 即可，无需改业务代码：
+
+```bash
+export MITI_API_BASE_URL="http://localhost:10006/chat"
+```
+
+也可以在初始化时显式传入：
+
+```python
+agent = MitiAgent(
+    app_id="cli_xxx",
+    app_secret="secret_xxx",
+    base_url="http://localhost:10006/chat",
+)
+```
+
+## 拉取历史记录
+
+```python
+@agent.on_message
+async def handle(event):
+    history = await agent.get_history(
+        event.event.message.conversation_id, limit=10
+    )
+    # history: list[HistoryMessage]  each has .role and .content
+```
+
+## 日志 & 问题排查
+
+SDK 使用 Python 标准 `logging` 模块，logger 层级为 `miti_agent_sdk.*`。
+
+### 快速开启日志
+
+```python
+import miti_agent_sdk
+
+# INFO 级别：token 获取/刷新、WebSocket 连接/断开/重连、事件收发、消息发送
+miti_agent_sdk.enable_logging()
+
+# DEBUG 级别：额外输出每次 HTTP 请求 URL/参数、自动刷新 sleep 倒计时
+miti_agent_sdk.enable_logging(logging.DEBUG)
+```
+
+日志输出到 **stderr**（默认），格式示例：
+
+```
+2026-06-18 18:00:01 [miti_agent_sdk.auth] INFO token acquired, expires_in=7200s
+2026-06-18 18:00:01 [miti_agent_sdk.gateway] INFO connecting to wss://www.miti.chat/chat/agent/gateway
+2026-06-18 18:00:02 [miti_agent_sdk.gateway] INFO gateway connected
+2026-06-18 18:00:05 [miti_agent_sdk.gateway] INFO event received: type=im.message.receive id=evt-xxx
+2026-06-18 18:00:05 [miti_agent_sdk.message] INFO send_message success: target=user-abc message_id=msg-xxx
+```
+
+### 日志存储
+
+SDK 本身不写日志文件。日志的最终存储取决于宿主进程：
+
+| 方式 | 配置 | 适用场景 |
+|------|------|----------|
+| 控制台 | `miti_agent_sdk.enable_logging()` | 本地开发调试 |
+| 文件 | `logging.basicConfig(filename="agent.log", level=logging.INFO)` | 单机部署 |
+| 结构化日志 | 宿主框架的 JSON handler（如 `python-json-logger`） | 生产环境 / 接入 ELK 等 |
+| 容器 stdout | 不做额外配置，`enable_logging()` 输出到 stderr 即可 | Docker / K8s |
+
+### 排查常见问题
+
+| 现象 | 排查方向 | 关键日志 |
+|------|----------|----------|
+| 启动后无反应 | Token 获取失败 | `auth token API error: code=... msg=...` |
+| 连接后收不到消息 | WebSocket 断开或无事件推送 | `gateway connection lost` / `no handler for event_type` |
+| 回复消息失败 | 权限不足或目标不存在 | `send_message API error: code=10012 msg=no permission` |
+| Token 过期后断连 | 自动刷新失败 | `auto-refresh failed, will retry in ...s` |
+| WebSocket 频繁重连 | 网络不稳或服务端问题 | `reconnecting in Xs`（观察退避时间是否递增） |
+
+## 安全注意事项
+
+### 日志安全
+
+SDK 自身**不会**在日志中输出 `app_secret` 或 `access_token`。但如果你开启了
+`aiohttp` 的 trace/debug 日志（如 `AIOHTTP_TRACE=1`），HTTP 请求体会被底层框架
+打印出来，其中包含 `app_secret`。**生产环境请勿开启 aiohttp trace 日志。**
+
+### 凭证内存存储
+
+`app_secret` 和 `access_token` 在 SDK 运行期间以明文存储在进程内存中。
+这是 Python SDK 的通用模式（与飞书 SDK、Slack SDK 一致），无法避免。
+请确保：
+
+- 不要在多租户共享环境中运行 agent 进程
+- 不要将进程 memory dump 输出到不安全的位置
+- 进程退出后凭证自动释放，无需手动清理
+
+### TLS 要求
+
+SDK 强制要求 `base_url` 使用 `https://`（对应 WebSocket `wss://`）。
+本地开发调试时 `localhost` / `127.0.0.1` 可使用 `http://`，其他地址会被拒绝。
+
+## Requirements
+
+- Python 3.9+
+- `aiohttp >= 3.9`
+- `websockets >= 12.0`

miti_agent_sdk-0.1.0/README.md

@@ -0,0 +1,151 @@
+# miti-agent-sdk
+
+Connect third-party agents (Hermes, OpenClaw, Claude Code, etc.) to the Miti IM platform.
+
+## Installation
+
+```bash
+pip install miti-agent-sdk
+```
+
+## Quick Start
+
+```python
+from miti_agent_sdk import MitiAgent
+
+agent = MitiAgent(
+    app_id="cli_xxx",
+    app_secret="secret_xxx",
+)
+
+# 单聊消息
+@agent.on_message
+async def handle(event):
+    user_text = event.event.message.content.get("text", "")
+    await event.reply(f"收到：{user_text}")
+
+# 群 @ 消息
+@agent.on_group_at
+async def handle_group(event):
+    text = event.event.message.content.get("text", "")
+    await event.reply(f"群收到：{text}")
+
+agent.run()
+```
+
+SDK 内部自动处理：Token 获取/刷新、WebSocket 保活、指数退避重连。
+
+## 环境配置
+
+`base_url` 按以下优先级决定（先找到先用）：
+
+| 优先级 | 来源 | 示例 |
+|--------|------|------|
+| 1（最高） | 构造函数 `base_url=` 参数 | `MitiAgent(base_url="https://...")` |
+| 2 | 环境变量 `MITI_API_BASE_URL` | `export MITI_API_BASE_URL="https://..."` |
+| 3（默认） | 正式环境 | `https://www.miti.chat/chat` |
+
+大多数场景下**不需要配置任何东西**，SDK 自动连接正式环境。
+
+本地开发调试时，通过环境变量指向本地 appserver 即可，无需改业务代码：
+
+```bash
+export MITI_API_BASE_URL="http://localhost:10006/chat"
+```
+
+也可以在初始化时显式传入：
+
+```python
+agent = MitiAgent(
+    app_id="cli_xxx",
+    app_secret="secret_xxx",
+    base_url="http://localhost:10006/chat",
+)
+```
+
+## 拉取历史记录
+
+```python
+@agent.on_message
+async def handle(event):
+    history = await agent.get_history(
+        event.event.message.conversation_id, limit=10
+    )
+    # history: list[HistoryMessage]  each has .role and .content
+```
+
+## 日志 & 问题排查
+
+SDK 使用 Python 标准 `logging` 模块，logger 层级为 `miti_agent_sdk.*`。
+
+### 快速开启日志
+
+```python
+import miti_agent_sdk
+
+# INFO 级别：token 获取/刷新、WebSocket 连接/断开/重连、事件收发、消息发送
+miti_agent_sdk.enable_logging()
+
+# DEBUG 级别：额外输出每次 HTTP 请求 URL/参数、自动刷新 sleep 倒计时
+miti_agent_sdk.enable_logging(logging.DEBUG)
+```
+
+日志输出到 **stderr**（默认），格式示例：
+
+```
+2026-06-18 18:00:01 [miti_agent_sdk.auth] INFO token acquired, expires_in=7200s
+2026-06-18 18:00:01 [miti_agent_sdk.gateway] INFO connecting to wss://www.miti.chat/chat/agent/gateway
+2026-06-18 18:00:02 [miti_agent_sdk.gateway] INFO gateway connected
+2026-06-18 18:00:05 [miti_agent_sdk.gateway] INFO event received: type=im.message.receive id=evt-xxx
+2026-06-18 18:00:05 [miti_agent_sdk.message] INFO send_message success: target=user-abc message_id=msg-xxx
+```
+
+### 日志存储
+
+SDK 本身不写日志文件。日志的最终存储取决于宿主进程：
+
+| 方式 | 配置 | 适用场景 |
+|------|------|----------|
+| 控制台 | `miti_agent_sdk.enable_logging()` | 本地开发调试 |
+| 文件 | `logging.basicConfig(filename="agent.log", level=logging.INFO)` | 单机部署 |
+| 结构化日志 | 宿主框架的 JSON handler（如 `python-json-logger`） | 生产环境 / 接入 ELK 等 |
+| 容器 stdout | 不做额外配置，`enable_logging()` 输出到 stderr 即可 | Docker / K8s |
+
+### 排查常见问题
+
+| 现象 | 排查方向 | 关键日志 |
+|------|----------|----------|
+| 启动后无反应 | Token 获取失败 | `auth token API error: code=... msg=...` |
+| 连接后收不到消息 | WebSocket 断开或无事件推送 | `gateway connection lost` / `no handler for event_type` |
+| 回复消息失败 | 权限不足或目标不存在 | `send_message API error: code=10012 msg=no permission` |
+| Token 过期后断连 | 自动刷新失败 | `auto-refresh failed, will retry in ...s` |
+| WebSocket 频繁重连 | 网络不稳或服务端问题 | `reconnecting in Xs`（观察退避时间是否递增） |
+
+## 安全注意事项
+
+### 日志安全
+
+SDK 自身**不会**在日志中输出 `app_secret` 或 `access_token`。但如果你开启了
+`aiohttp` 的 trace/debug 日志（如 `AIOHTTP_TRACE=1`），HTTP 请求体会被底层框架
+打印出来，其中包含 `app_secret`。**生产环境请勿开启 aiohttp trace 日志。**
+
+### 凭证内存存储
+
+`app_secret` 和 `access_token` 在 SDK 运行期间以明文存储在进程内存中。
+这是 Python SDK 的通用模式（与飞书 SDK、Slack SDK 一致），无法避免。
+请确保：
+
+- 不要在多租户共享环境中运行 agent 进程
+- 不要将进程 memory dump 输出到不安全的位置
+- 进程退出后凭证自动释放，无需手动清理
+
+### TLS 要求
+
+SDK 强制要求 `base_url` 使用 `https://`（对应 WebSocket `wss://`）。
+本地开发调试时 `localhost` / `127.0.0.1` 可使用 `http://`，其他地址会被拒绝。
+
+## Requirements
+
+- Python 3.9+
+- `aiohttp >= 3.9`
+- `websockets >= 12.0`

miti_agent_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "miti-agent-sdk"
+version = "0.1.0"
+description = "Miti Agent SDK – connect third-party agents to Miti IM"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+dependencies = [
+    "aiohttp>=3.9",
+    "websockets>=12.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

miti_agent_sdk-0.1.0/setup.cfg

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

miti_agent_sdk-0.1.0/src/miti_agent_sdk/__init__.py

@@ -0,0 +1,67 @@
+"""Miti Agent SDK – connect third-party agents to Miti IM."""
+
+import logging
+
+from .agent import MitiAgent
+from .auth import AuthClient, AuthError
+from .gateway import GatewayClient
+from .message import ApiError, HistoryClient, MessageClient
+from .models import (
+    AgentEvent,
+    EventHeader,
+    EventMessage,
+    EventSender,
+    GroupAtEvent,
+    HistoryMessage,
+    MessageEvent,
+)
+from .stream import build_stream_full_markdown
+
+__all__ = [
+    "MitiAgent",
+    "AuthClient",
+    "AuthError",
+    "GatewayClient",
+    "MessageClient",
+    "HistoryClient",
+    "ApiError",
+    "AgentEvent",
+    "EventHeader",
+    "EventMessage",
+    "EventSender",
+    "GroupAtEvent",
+    "HistoryMessage",
+    "MessageEvent",
+    "build_stream_full_markdown",
+    "enable_logging",
+]
+
+__version__ = "0.1.0"
+
+# Library best practice: NullHandler prevents "No handlers found" warnings.
+# Users must configure logging themselves or call enable_logging() below.
+logging.getLogger("miti_agent_sdk").addHandler(logging.NullHandler())
+
+
+def enable_logging(
+    level: int = logging.INFO,
+    fmt: str = "%(asctime)s [%(name)s] %(levelname)s %(message)s",
+) -> None:
+    """Enable SDK logging to stderr with a human-readable format.
+
+    Call this before ``agent.run()`` to see SDK internal activity::
+
+        import miti_agent_sdk
+        miti_agent_sdk.enable_logging()           # INFO level
+        miti_agent_sdk.enable_logging(logging.DEBUG)  # verbose
+
+    If you already have ``logging.basicConfig()`` or a framework logger
+    configured, you don't need this — SDK logs will flow through the
+    ``miti_agent_sdk.*`` logger hierarchy automatically.
+    """
+    root = logging.getLogger("miti_agent_sdk")
+    root.setLevel(level)
+    if not any(isinstance(h, logging.StreamHandler) for h in root.handlers):
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter(fmt))
+        root.addHandler(handler)

miti_agent_sdk-0.1.0/src/miti_agent_sdk/agent.py

@@ -0,0 +1,272 @@
+"""MitiAgent – top-level facade that wires AuthClient, GatewayClient,
+MessageClient, and HistoryClient together."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import re
+import signal
+from typing import Any, Callable, Optional
+
+import aiohttp
+
+from .auth import AuthClient
+from .gateway import EventHandler, GatewayClient
+from .message import HistoryClient, MessageClient
+from .models import AgentEvent, HistoryMessage
+
+logger = logging.getLogger("miti_agent_sdk")
+
+_BASE_URL_ENV = "MITI_API_BASE_URL"
+_DEFAULT_BASE_URL = "https://www.miti.chat/chat"
+
+
+class MitiAgent:
+    """One-stop entry point for third-party agents connecting to Miti.
+
+    Usage::
+
+        agent = MitiAgent(app_id="cli_xxx", app_secret="secret_xxx")
+
+        @agent.on_message
+        async def handle(event: AgentEvent):
+            await event.reply("got it!")
+
+        agent.run()
+
+    Parameters
+    ----------
+    app_id : str
+        Agent application ID.
+    app_secret : str
+        Agent application secret.
+    base_url : str
+        Miti API base URL. Defaults to the ``MITI_API_BASE_URL`` environment
+        variable when set, otherwise ``https://www.miti.chat/chat``.
+    """
+
+    def __init__(
+        self,
+        app_id: str,
+        app_secret: str,
+        base_url: Optional[str] = None,
+    ):
+        self._base_url = (
+            base_url or os.getenv(_BASE_URL_ENV) or _DEFAULT_BASE_URL
+        ).rstrip("/")
+
+        if not _is_tls_or_localhost(self._base_url):
+            raise ValueError(
+                f"base_url must use https:// (got {self._base_url!r}). "
+                f"Only localhost / 127.0.0.1 is allowed over http:// for local development."
+            )
+
+        self._session: Optional[aiohttp.ClientSession] = None
+
+        self._auth = AuthClient(
+            app_id=app_id,
+            app_secret=app_secret,
+            base_url=self._base_url,
+        )
+        self._gateway = GatewayClient(auth=self._auth, base_url=self._base_url)
+        self._msg_client: Optional[MessageClient] = None
+        self._history_client: Optional[HistoryClient] = None
+
+    # ------------------------------------------------------------------
+    # Decorator API
+    # ------------------------------------------------------------------
+
+    def on_message(self, fn: EventHandler) -> EventHandler:
+        """Decorator: register *fn* as the handler for single-chat messages
+        (``im.message.receive``).
+
+        ::
+
+            @agent.on_message
+            async def handle(event):
+                await event.reply("hello")
+        """
+        self._gateway.on("im.message.receive", fn)
+        return fn
+
+    def on_group_at(self, fn: EventHandler) -> EventHandler:
+        """Decorator: register *fn* as the handler for group-chat @ messages
+        (``im.message.group_at``).
+
+        ::
+
+            @agent.on_group_at
+            async def handle(event):
+                await event.reply("group reply")
+        """
+        self._gateway.on("im.message.group_at", fn)
+        return fn
+
+    def on(self, event_type: str) -> Callable[[EventHandler], EventHandler]:
+        """Generic decorator for any event type::
+
+            @agent.on("im.message.receive")
+            async def handle(event):
+                ...
+        """
+        def decorator(fn: EventHandler) -> EventHandler:
+            self._gateway.on(event_type, fn)
+            return fn
+        return decorator
+
+    # ------------------------------------------------------------------
+    # REST helpers
+    # ------------------------------------------------------------------
+
+    async def send_message(
+        self,
+        *,
+        to_user_id: Optional[str] = None,
+        to_group_id: Optional[str] = None,
+        msg_type: str = "text",
+        content: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Send a message via ``POST /agent/v1/messages/send``.
+
+        Supported ``msg_type`` values:
+
+        - ``text`` — plain text (contentType 101)
+        - ``stream_full`` — Markdown reply (contentType 125); use
+          :func:`miti_agent_sdk.build_stream_full_markdown` or pass
+          ``{"markdown": "...", "ask_msg_id": "..."}``
+
+        Returns the ``data`` dict from the response.
+        """
+        client = self._ensure_msg_client()
+        return await client.send(
+            to_user_id=to_user_id,
+            to_group_id=to_group_id,
+            msg_type=msg_type,
+            content=content,
+        )
+
+    async def send_markdown_reply(
+        self,
+        markdown: str,
+        *,
+        to_user_id: Optional[str] = None,
+        to_group_id: Optional[str] = None,
+        ask_msg_id: str = "",
+    ) -> dict[str, Any]:
+        """Send a Markdown reply as ``stream_full`` (contentType 125)."""
+        from .stream import build_stream_full_markdown
+
+        return await self.send_message(
+            to_user_id=to_user_id,
+            to_group_id=to_group_id,
+            msg_type="stream_full",
+            content=build_stream_full_markdown(markdown, ask_msg_id),
+        )
+
+    async def get_history(
+        self,
+        conversation_id: str,
+        limit: int = 10,
+    ) -> list[HistoryMessage]:
+        """Fetch conversation history via ``GET /agent/v1/messages/history``."""
+        client = self._ensure_history_client()
+        return await client.get(conversation_id=conversation_id, limit=limit)
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def run(self) -> None:
+        """Blocking entry point.  Starts the event loop, connects the
+        WebSocket gateway, and runs until interrupted (Ctrl-C / SIGTERM).
+
+        Internally calls :meth:`run_async`.
+        """
+        try:
+            asyncio.run(self.run_async())
+        except KeyboardInterrupt:
+            logger.info("interrupted, shutting down")
+
+    async def run_async(self, *, register_signals: bool = True) -> None:
+        """Async entry point – call this if you already own the event loop.
+
+        Parameters
+        ----------
+        register_signals : bool
+            When *True* (default), register SIGINT/SIGTERM handlers to
+            gracefully stop the gateway.  Set to *False* when embedding
+            the agent inside a host process (e.g. Hermes) that manages
+            its own signal handling.
+        """
+        if register_signals:
+            loop = asyncio.get_running_loop()
+            for sig in (signal.SIGINT, signal.SIGTERM):
+                try:
+                    loop.add_signal_handler(sig, self._gateway.stop)
+                except NotImplementedError:
+                    pass  # Windows
+
+        logger.info("MitiAgent starting")
+        self._auth.set_shared_session(self._ensure_session())
+        await self._auth.start_auto_refresh()
+        try:
+            await self._gateway.run_forever(inject_agent=self)
+        finally:
+            await self.close()
+            logger.info("MitiAgent stopped")
+
+    async def close(self) -> None:
+        """Release all resources (HTTP sessions, refresh tasks, WebSocket).
+
+        Safe to call multiple times — subsequent calls are no-ops.
+        """
+        await self._auth.close()
+        if self._msg_client:
+            await self._msg_client.close()
+        if self._history_client:
+            await self._history_client.close()
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _ensure_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+        return self._session
+
+    def _ensure_msg_client(self) -> MessageClient:
+        if self._msg_client is None:
+            self._msg_client = MessageClient(
+                auth=self._auth,
+                base_url=self._base_url,
+                session=self._ensure_session(),
+            )
+        return self._msg_client
+
+    def _ensure_history_client(self) -> HistoryClient:
+        if self._history_client is None:
+            self._history_client = HistoryClient(
+                auth=self._auth,
+                base_url=self._base_url,
+                session=self._ensure_session(),
+            )
+        return self._history_client
+
+
+_LOCAL_HOST_RE = re.compile(
+    r"^https?://(localhost|127\.0\.0\.1)(:\d+)?(/|$)", re.IGNORECASE,
+)
+
+
+def _is_tls_or_localhost(url: str) -> bool:
+    """Return True if *url* uses https:// or targets localhost over http://."""
+    if url.startswith("https://"):
+        return True
+    if url.startswith("http://") and _LOCAL_HOST_RE.match(url):
+        return True
+    return False