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`
