Merge feat/v0.2-transport-layer: two-layer architecture (Transport + Bot)

Author: DDU1222

README.md

@@ -0,0 +1,84 @@
+"""
+Builder 模式 + 中间件示例。
+
+演示：
+- WeChatBot.builder() 流式构建
+- 自定义中间件（日志、限流）
+- 自定义错误处理
+
+Usage:
+    python examples/builder_bot.py
+"""
+
+import asyncio
+import time
+
+from wechat_agent_sdk import (
+    Agent,
+    ChatRequest,
+    ChatResponse,
+    Context,
+    WeChatBot,
+    make_error_middleware,
+)
+
+
+class SmartAgent(Agent):
+    async def chat(self, request: ChatRequest) -> ChatResponse:
+        if "error" in request.text:
+            raise ValueError("Simulated error for testing")
+        return ChatResponse(text=f"Reply: {request.text}")
+
+
+# ── Middleware examples ──
+
+async def logging_middleware(ctx: Context, next_fn):
+    """Log inbound and outbound messages."""
+    print(f"[LOG] ← {ctx.request.conversation_id}: {ctx.request.text[:50]}")
+    start = time.time()
+    await next_fn()
+    elapsed = time.time() - start
+    reply = ctx.response.text[:50] if ctx.response and ctx.response.text else "None"
+    print(f"[LOG] → {reply} ({elapsed:.2f}s)")
+
+
+_last_message_time: dict[str, float] = {}
+
+async def rate_limit_middleware(ctx: Context, next_fn):
+    """Simple per-user rate limiter (1 message per second)."""
+    user = ctx.request.conversation_id
+    now = time.time()
+    last = _last_message_time.get(user, 0)
+    if now - last < 1.0:
+        ctx.response = ChatResponse(text="Too fast, please wait a moment.")
+        return  # short-circuit
+    _last_message_time[user] = now
+    await next_fn()
+
+
+async def custom_error_handler(ctx: Context, error: Exception):
+    """Custom error handler: log and return friendly message."""
+    print(f"[ERROR] {error}")
+    return ChatResponse(text=f"Oops: {error}")
+
+
+# ── Main ──
+
+async def main():
+    bot = (
+        WeChatBot.builder()
+        .agent(SmartAgent())
+        .on_error(custom_error_handler)
+        .middleware(logging_middleware)
+        .middleware(rate_limit_middleware)
+        .build()
+    )
+
+    try:
+        await bot.run()
+    except KeyboardInterrupt:
+        await bot.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

README_zh.md

@@ -0,0 +1,52 @@
+"""
+多账号管理示例。
+
+WeChatBotManager 管理多个 bot 实例，支持独立启停和自动重启。
+
+Usage:
+    python examples/multi_bot.py
+"""
+
+import asyncio
+
+from wechat_agent_sdk import (
+    Agent,
+    ChatRequest,
+    ChatResponse,
+    WeChatBotManager,
+)
+
+
+class TaggedAgent(Agent):
+    """An agent that prefixes replies with its tag."""
+
+    def __init__(self, tag: str):
+        self._tag = tag
+
+    async def chat(self, request: ChatRequest) -> ChatResponse:
+        return ChatResponse(text=f"[{self._tag}] {request.text}")
+
+
+async def main():
+    manager = WeChatBotManager(auto_restart=True, max_restart_attempts=3)
+
+    # Register multiple bots
+    manager.add_bot("bot_alice", agent=TaggedAgent("Alice"))
+    manager.add_bot("bot_bob", agent=TaggedAgent("Bob"))
+
+    print(f"Registered {manager.bot_count} bots")
+    print(f"Status: {manager.get_status()}")
+
+    # Each bot needs to login separately
+    # In a real scenario, you'd call bot.login() or use the web login API
+
+    try:
+        await manager.start_all()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        await manager.stop_all()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/builder_bot.py

@@ -0,0 +1,51 @@
+"""
+Transport 层独立使用示例 — 平台集成场景。
+
+Transport 层不管 Agent、不管中间件，只做传输：
+连接、收消息、解析、发送。
+
+平台自己管权限、会话、Agent 调用、SSE 流式。
+
+Usage:
+    python examples/transport_demo.py
+"""
+
+import asyncio
+
+from wechat_agent_sdk import WeChatTransport
+
+
+async def main():
+    transport = WeChatTransport(account_id="demo")
+
+    # Terminal login (or use request_login() + check_login() for web UI)
+    await transport.login_terminal()
+
+    # Connect and receive messages
+    await transport.connect()
+    print("[transport] Connected, waiting for messages...")
+
+    try:
+        async for raw_msg in transport.messages():
+            parsed = transport.parse(raw_msg)
+            if not parsed:
+                continue
+
+            print(f"[transport] From: {parsed.conversation_id}")
+            print(f"[transport] Text: {parsed.text}")
+            print(f"[transport] Media count: {len(parsed.media)}")
+
+            # Echo reply via transport
+            await transport.send_text(
+                parsed.conversation_id,
+                f"[Transport 模式] 收到: {parsed.text}",
+                parsed.context_token,
+            )
+    except KeyboardInterrupt:
+        pass
+    finally:
+        await transport.disconnect()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/multi_bot.py

@@ -26,12 +26,16 @@ classifiers = [
 ]
 dependencies = [
     "httpx>=0.27",
+    "cryptography>=42.0",
 ]
 
 [project.optional-dependencies]
 qr = ["qrcode[pil]>=7.0"]
 acp = ["agent-client-protocol>=0.8"]
 openai = ["openai>=1.0"]
+redis = ["redis>=5.0"]
+sqlite = ["aiosqlite>=0.20"]
+all = ["qrcode[pil]>=7.0", "agent-client-protocol>=0.8", "openai>=1.0", "redis>=5.0", "aiosqlite>=0.20"]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.24",

examples/transport_demo.py

@@ -1,10 +1,18 @@
 """
 wechat-agent-sdk — WeChat AI Agent bridge framework.
 
-Provides a simple Agent interface to connect any AI backend to WeChat
-via the iLink Bot API, with optional ACP (Agent Client Protocol) support.
+Two-layer architecture:
 
-Quick start::
+**Transport layer** (platform integration)::
+
+    from wechat_agent_sdk import WeChatTransport, ParsedMessage
+
+    transport = WeChatTransport(account_id="bot_1")
+    async for msg in transport.messages():
+        parsed = transport.parse(msg)
+        await transport.send_text(parsed.conversation_id, "reply")
+
+**Bot layer** (standalone developers)::
 
     from wechat_agent_sdk import Agent, ChatRequest, ChatResponse, WeChatBot
 
@@ -16,18 +24,43 @@ async def chat(self, request: ChatRequest) -> ChatResponse:
     await bot.run()
 """
 
+# === Transport layer (platform integration) ===
+from .transport import WeChatTransport, ParsedMessage, LoginRequiredError
+
+# === Bot layer (standalone developers) ===
 from .agent import Agent
 from .types import ChatRequest, ChatResponse, MediaInfo, MediaResponseInfo
-from .account.manager import WeChatBot
+from .account.manager import WeChatBot, WeChatBotBuilder
+from .middleware import Context, Middleware, MiddlewareChain, make_error_middleware
+from .account.bot_manager import WeChatBotManager, BotStatus
+
+# === Shared infrastructure ===
 from .account.storage import AccountStorage, JsonFileStorage
+from .api.auth import LoginSession, LoginResult, LoginStatus
 
 __all__ = [
+    # Transport
+    "WeChatTransport",
+    "ParsedMessage",
+    "LoginRequiredError",
+    # Bot
     "Agent",
     "ChatRequest",
     "ChatResponse",
     "MediaInfo",
     "MediaResponseInfo",
     "WeChatBot",
+    "WeChatBotBuilder",
+    "WeChatBotManager",
+    "BotStatus",
+    "Context",
+    "Middleware",
+    "MiddlewareChain",
+    "make_error_middleware",
+    # Shared
     "AccountStorage",
     "JsonFileStorage",
+    "LoginSession",
+    "LoginResult",
+    "LoginStatus",
 ]