@baimingtao/lbs-agent 1.0.0

package/interfaces/gateway/_impl/adapters/feishu/adapter.py

@@ -0,0 +1,575 @@
+"""飞书 (Lark) Gateway Adapter — 真实 IM API 实现。
+
+配置（env 优先，yaml 兜底）：
+  FEISHU_APP_ID
+  FEISHU_APP_SECRET
+  FEISHU_VERIFICATION_TOKEN  (可选, callback 验签)
+  FEISHU_ENCRYPT_KEY         (可选, callback 解密)
+  FEISHU_BOT_NAME            (可选, @mention 检测)
+
+支持的 receive 模式:
+  1. WebSocket (推荐) — lark-oapi SDK，启动后自动接收事件
+  2. Webhook — Flask/HTTP server（需要公网回调地址）
+
+Hermes 经验:
+  - tenant_access_token 2 小时过期，需缓存
+  - 群消息需要 @mention 才回（除非 FEISHU_REQUIRE_MENTION=false）
+  - allowed_chats 不是群准入开关；用 group_rules 配每群策略
+  - send_message 工具用 IM API 直调而非 lark SDK（更可控）
+
+参考 Hermes 实现:
+  https://open.feishu.cn/document/server-docs/im-v1/message/list
+"""
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import time
+from typing import Any, Callable, Optional
+
+import requests
+
+from interfaces.gateway._impl import Gateway, Message
+from runtime.gateway import OutgoingMessage
+
+logger = logging.getLogger(__name__)
+
+
+class FeishuGateway(Gateway):
+    """飞书网关。启动后监听事件，回调 on_message，send() 主动发送。"""
+
+    name = "feishu"
+    FEISHU_BASE = "https://open.feishu.cn/open-apis"
+
+    def __init__(self, config: dict[str, Any] | None = None):
+        super().__init__(config or {})
+        self.app_id: str = self.config.get("app_id", "") or ""
+        self.app_secret: str = self.config.get("app_secret", "") or ""
+        self.bot_name: str = self.config.get("bot_name", "") or ""
+        self.require_mention: bool = self.config.get("require_mention", True)
+        self.allowed_chats: set[str] = set(self.config.get("allowed_chats", []) or [])
+        # 群规则: {chat_id: {"require_mention": bool, "allowed_users": [...]}}
+        self.group_rules: dict[str, dict[str, Any]] = dict(self.config.get("group_rules", {}) or {})
+        self.default_policy: str = self.config.get("default_policy", "mention")
+        self._token: str = ""
+        self._token_expires_at: float = 0.0
+        self._ws_thread: Optional[threading.Thread] = None
+        self._stop_event = threading.Event()
+        self._http_session = requests.Session()
+        self.webhook_url: str = self.config.get("webhook_url", "") or ""
+        self.webhook_secret: str = self.config.get("webhook_secret", "") or ""
+        self._webhook = None  # type: Optional[FeishuWebhook]
+        self._mode = "disabled"
+
+    # ── 凭证 / Token ─────────────────────────────────────────
+
+    def _load_creds_from_env(self) -> None:
+        """如果 config 没填，从 env 加载（用 os.environ 直读，不用 ${} 展开）。"""
+        import os
+        if not self.app_id:
+            self.app_id = os.environ.get("FEISHU_APP_ID", "")
+        if not self.app_secret:
+            self.app_secret = os.environ.get("FEISHU_APP_SECRET", "")
+        if not self.bot_name:
+            self.bot_name = os.environ.get("FEISHU_BOT_NAME", "")
+
+    def _get_tenant_token(self) -> Optional[str]:
+        """获取 tenant_access_token，缓存到过期。"""
+        if self._token and time.time() < self._token_expires_at - 60:
+            return self._token
+        if not (self.app_id and self.app_secret):
+            logger.error("[feishu] missing app_id or app_secret")
+            return None
+        try:
+            r = self._http_session.post(
+                f"{self.FEISHU_BASE}/auth/v3/tenant_access_token/internal",
+                json={"app_id": self.app_id, "app_secret": self.app_secret},
+                timeout=10,
+            )
+            r.raise_for_status()
+            data = r.json()
+            if data.get("code") != 0:
+                logger.error("[feishu] tenant token fail: %s", data)
+                return None
+            self._token = data["tenant_access_token"]
+            self._token_expires_at = time.time() + int(data.get("expire", 7200))
+            return self._token
+        except Exception as e:
+            logger.error("[feishu] tenant token error: %s", e)
+            return None
+
+    # ── 生命周期 ─────────────────────────────────────────────
+
+    def start(self) -> None:
+        """启动飞书网关。
+
+        模式优先级: app (有 app_id/secret) > webhook (有 webhook_url) > disabled
+        """
+        self._load_creds_from_env()
+        self._running = True
+        self._stop_event.clear()
+
+        # webhook 模式（单向 send，无需 app_id）
+        if self.webhook_url:
+            self._webhook = FeishuWebhook(self.webhook_url, self.webhook_secret)
+            self._mode = "webhook"
+            logger.info("[feishu] webhook mode: %s", self.webhook_url[:60])
+            if not (self.app_id and self.app_secret):
+                return  # 只要 webhook 就够了
+
+        # app 模式（receive + 主动 send）
+        if self.app_id and self.app_secret:
+            self._mode = "both" if self.webhook_url else "app"
+            try:
+                self._ws_thread = threading.Thread(
+                    target=self._ws_loop,
+                    name="feishu-ws",
+                    daemon=True,
+                )
+                self._ws_thread.start()
+                logger.info("[feishu] app mode started (ws thread)")
+            except Exception as e:
+                logger.error("[feishu] ws thread failed: %s", e)
+            return
+
+        # 都没配：保持 disabled，不要再启动 ws 线程。
+        # 否则测试/空配置场景会意外 import lark_oapi，触发 ExpiringCache 后台协程，
+        # 最终在 pytest 退出时留下 pending task / Event loop is closed 噪音。
+        logger.warning("[feishu] no app_id/app_secret/webhook, gateway disabled")
+        self._mode = "disabled"
+        return
+
+    def _ws_loop(self) -> None:
+        """WebSocket 接收循环（使用 lark-oapi SDK，可选）。"""
+        try:
+            import lark_oapi as lark  # type: ignore
+        except ImportError:
+            logger.warning("[feishu] lark_oapi not installed, falling back to webhook polling mode")
+            self._polling_loop()
+            return
+
+        client = lark.Client.builder() \
+            .app_id(self.app_id) \
+            .app_secret(self.app_secret) \
+            .build()
+
+        event_handler = lark.EventDispatcherHandler.builder("", "") \
+            .register_p2_im_message_receive_v1(self._on_lark_message) \
+            .build()
+
+        ws_client = lark.ws.Client(
+            self.app_id, self.app_secret,
+            event_handler=event_handler,
+            log_level=lark.LogLevel.INFO,
+        )
+        try:
+            ws_client.start()
+        except Exception as e:
+            logger.error("[feishu] ws start error: %s", e)
+
+    def _on_lark_message(self, data) -> None:
+        """lark-oapi 消息回调。"""
+        try:
+            msg = data.event
+            self._handle_event_message({
+                "message_id": msg.message_id,
+                "chat_id": msg.message.chat_id,
+                "chat_type": msg.message.chat_type,
+                "sender_id": msg.sender.sender_id.open_id if msg.sender and msg.sender.sender_id else "",
+                "sender_name": msg.sender.sender_name or "" if msg.sender else "",
+                "content": msg.message.content,
+                "msg_type": msg.message.message_type,
+                "mentions": [m.to_dict() for m in (msg.message.mentions or [])] if hasattr(msg.message, "mentions") else [],
+            })
+        except Exception as e:
+            logger.error("[feishu] on message error: %s", e)
+
+    def _polling_loop(self) -> None:
+        """无 lark-oapi SDK 时的轮询 fallback（仅用于测试/调试）。"""
+        while not self._stop_event.is_set():
+            time.sleep(1)
+
+    def stop(self) -> None:
+        self._running = False
+        self._stop_event.set()
+        if self._ws_thread and self._ws_thread.is_alive():
+            self._ws_thread.join(timeout=2)
+        self._http_session.close()
+        logger.info("[feishu] gateway stopped")
+
+    # ── 发送消息 ─────────────────────────────────────────────
+
+    def send(self, message: OutgoingMessage) -> bool:
+        """主动发送回复。
+
+        优先级:
+          1. webhook (单向，无需 token)
+          2. IM API (需要 app_id/secret)
+        """
+        # 1. webhook 模式
+        if self._webhook:
+            return self._webhook.send_text(message.content)
+
+        # 2. IM API 模式（默认 text；如要其他类型用 send_with_type）
+        return self.send_with_type(message.channel_id, "text", text=message.content)
+
+    def send_with_type(self, receive_id: str, msg_type: str, **kwargs) -> bool:
+        """IM API 发送指定类型的消息。
+
+        用法:
+            feishu.send_with_type("oc_xxx", "post", title="告警", content=[...])
+            feishu.send_with_type("oc_xxx", "interactive", card={...})
+            feishu.send_with_type("oc_xxx", "text", text="hi")
+            feishu.send_with_type("oc_xxx", "image", image_key="img_xxx")
+        """
+        token = self._get_tenant_token()
+        if not token:
+            logger.error("[feishu] send: no tenant token")
+            return False
+        try:
+            content_json = build_feishu_message(msg_type, **kwargs)
+            r = self._http_session.post(
+                f"{self.FEISHU_BASE}/im/v1/messages",
+                params={"receive_id_type": "chat_id"},
+                headers={
+                    "Authorization": f"Bearer {token}",
+                    "Content-Type": "application/json",
+                },
+                json={
+                    "receive_id": receive_id,
+                    "msg_type": msg_type,
+                    "content": json.dumps(content_json, ensure_ascii=False),
+                },
+                timeout=10,
+            )
+            r.raise_for_status()
+            data = r.json()
+            if data.get("code") != 0:
+                logger.error("[feishu] send fail: %s", data)
+                return False
+            logger.info("[feishu] sent: msg_type=%s msg_id=%s",
+                        msg_type, data.get("data", {}).get("message_id"))
+            return True
+        except Exception as e:
+            logger.error("[feishu] send error: %s", e)
+            return False
+
+    def send_to(self, chat_id: str, text: str) -> bool:
+        """主动发到指定 chat（最常用 API）。"""
+        return self.send(OutgoingMessage(content=text, channel_id=chat_id))
+
+    # ── 入站消息处理 ─────────────────────────────────────────
+
+    def _handle_event_message(self, ev: dict[str, Any]) -> None:
+        """处理一条事件消息 → 调 on_message handler。"""
+        chat_id = ev.get("chat_id", "")
+        chat_type = ev.get("chat_type", "p2p")  # p2p | group
+        sender_id = ev.get("sender_id", "")
+        content_raw = ev.get("content", "{}")
+        msg_type = ev.get("msg_type", "text")
+        mentions = ev.get("mentions", []) or []
+
+        # 提取文本
+        text = ""
+        if msg_type == "text":
+            try:
+                text = json.loads(content_raw).get("text", "")
+            except Exception:
+                text = content_raw
+        else:
+            text = f"[{msg_type}]"  # 非文本消息（image/file/...）暂用占位
+
+        # 准入检查
+        if not self._admit(chat_type, chat_id, sender_id, mentions):
+            logger.debug("[feishu] dropped message from chat=%s sender=%s", chat_id, sender_id)
+            return
+
+        # 构造统一 Message
+        is_mention = self._is_mentioned(mentions)
+        msg = Message(
+            platform="feishu",
+            channel_id=chat_id,
+            user_id=sender_id,
+            user_name=ev.get("sender_name", ""),
+            content=text.strip(),
+            raw=ev,
+            is_mention=is_mention,
+            timestamp=time.time(),
+        )
+
+        if self._on_message:
+            try:
+                reply = self._on_message(msg)
+                if reply:
+                    self.send(reply)
+            except Exception as e:
+                logger.error("[feishu] handler error: %s", e)
+
+    def _admit(self, chat_type: str, chat_id: str, sender_id: str, mentions: list) -> bool:
+        """群消息准入检查（参考 Hermes gate 模型）。"""
+        if chat_type == "p2p":
+            return True  # 私聊默认通过（实际项目可加用户白名单）
+        # 群聊：检查 group_rules / default_policy
+        rule = self.group_rules.get(chat_id, {})
+        policy = rule.get("policy", self.default_policy)
+        if policy == "deny":
+            return False
+        if policy == "allowlist" and sender_id not in set(rule.get("allowed_users", []) or []):
+            return False
+        if chat_id in self.allowed_chats:
+            return True
+        # 默认：必须 mention（除非显式关闭）
+        require = rule.get("require_mention", self.require_mention)
+        if require and not self._is_mentioned(mentions):
+            return False
+        return True
+
+    def _is_mentioned(self, mentions: list) -> bool:
+        """判断 bot 是否被 @。"""
+        if not mentions:
+            return False
+        for m in mentions:
+            name = (m.get("name") if isinstance(m, dict) else getattr(m, "name", "")) or ""
+            if self.bot_name and self.bot_name in name:
+                return True
+        return False
+
+
+
+
+# ── 飞书 Webhook（自定义机器人，单向 send，无需 SDK） ──────
+
+class FeishuWebhook:
+    """飞书自定义机器人 Webhook（单向 send，无 receive）。
+
+    适用场景：不需要收消息，只需往群里推送。
+    配置: https://open.feishu.cn/document/client-docs/bot-v3/add-custom-bot
+
+    安全设置（任选其一）:
+      - 自定义关键词 (FEISHU_WEBHOOK_KEYWORDS, 逗号分隔)
+      - 签名校验 (FEISHU_WEBHOOK_SECRET, timestamp + sign)
+      - IP 白名单 (服务端校验)
+    """
+
+    def __init__(self, webhook_url: str, secret: str = ""):
+        self.webhook_url = webhook_url
+        self.secret = secret
+        self._http = requests.Session()
+
+    def _sign(self) -> str:
+        """生成签名（HMAC-SHA256）。"""
+        if not self.secret:
+            return ""
+        import hmac, hashlib, base64
+        timestamp = str(int(time.time()))
+        string_to_sign = f"{timestamp}\n{self.secret}"
+        hmac_code = hmac.new(string_to_sign.encode("utf-8"), digestmod=hashlib.sha256).digest()
+        sign = base64.b64encode(hmac_code).decode("utf-8")
+        return f"{timestamp},{sign}"
+
+    def send_text(self, text: str) -> bool:
+        """纯文本消息。"""
+        return self._post({"msg_type": "text", "content": {"text": text}})
+
+    def send_post(self, title: str, content_list: list, post_locale: str = "zh_cn") -> bool:
+        """富文本消息（多语言/多字段）。
+
+        content_list 元素示例:
+          [{"tag": "text", "text": "hello "},
+           {"tag": "a", "text": "click here", "href": "https://..."},
+           {"tag": "at", "user_id": "ou_xxx"}]
+        """
+        return self._post({
+            "msg_type": "post",
+            "content": {
+                "post": {
+                    "zh_cn": {
+                        "title": title,
+                        "content": content_list,
+                    }
+                }
+            }
+        })
+
+    def send_card(self, card: dict) -> bool:
+        """消息卡片（Card JSON 2.0）。
+
+        card 是完整 card JSON，例如:
+          {
+            "config": {"wide_screen_mode": True},
+            "header": {"title": {"tag": "plain_text", "content": "标题"}},
+            "elements": [{"tag": "div", "text": {"tag": "plain_text", "content": "..."}}]
+          }
+        """
+        return self._post({"msg_type": "interactive", "card": card})
+
+    def send_image(self, image_key: str) -> bool:
+        """图片消息（需先上传图片拿到 image_key）。"""
+        return self._post({"msg_type": "image", "content": {"image_key": image_key}})
+
+    def send_share_chat(self, chat_id: str) -> bool:
+        """分享群名片。"""
+        return self._post({"msg_type": "share_chat", "content": {"chat_id": chat_id}})
+
+    def send_share_user(self, user_id: str) -> bool:
+        """分享个人名片。"""
+        return self._post({"msg_type": "share_user", "content": {"user_id": user_id}})
+
+    def send_audio(self, file_key: str) -> bool:
+        """语音消息（需先上传拿到 file_key）。"""
+        return self._post({"msg_type": "audio", "content": {"file_key": file_key}})
+
+    def send_media(self, file_key: str, image_key: str = "") -> bool:
+        """视频/媒体消息。"""
+        content = {"file_key": file_key}
+        if image_key:
+            content["image_key"] = image_key
+        return self._post({"msg_type": "media", "content": content})
+
+    def send_file(self, file_key: str) -> bool:
+        """文件消息。"""
+        return self._post({"msg_type": "file", "content": {"file_key": file_key}})
+
+    def _post(self, body: dict) -> bool:
+        """POST 到 webhook URL，自动加签名。"""
+        if self.secret:
+            body["timestamp"], body["sign"] = self._sign().split(",", 1)
+        try:
+            r = self._http.post(self.webhook_url, json=body, timeout=10)
+            r.raise_for_status()
+            data = r.json()
+            if data.get("StatusCode", 0) != 0 and data.get("code", 0) != 0:
+                logger.error("[feishu webhook] send fail: %s", data)
+                return False
+            return True
+        except Exception as e:
+            logger.error("[feishu webhook] send error: %s", e)
+            return False
+
+
+# ── IM API 消息类型组装（用于 receive 后的 reply） ─────────
+
+class FeishuMessageBuilder:
+    """组装各种 msg_type 的 JSON content（用于 IM API 主动 send）。
+
+    参考: https://open.feishu.cn/document/server-docs/im-v1/message/create
+    """
+
+    @staticmethod
+    def text(text: str) -> dict:
+        """text 类型 content。"""
+        return {"text": text}
+
+    @staticmethod
+    def post(title: str, content_list: list) -> dict:
+        """post 类型 content（富文本）。"""
+        return {"post": {"zh_cn": {"title": title, "content": content_list}}}
+
+    @staticmethod
+    def image(image_key: str) -> dict:
+        """image 类型 content。"""
+        return {"image_key": image_key}
+
+    @staticmethod
+    def interactive(card: dict) -> dict:
+        """interactive 类型 content（消息卡片）。"""
+        return card  # 直接传 card JSON
+
+    @staticmethod
+    def share_chat(chat_id: str) -> dict:
+        return {"chat_id": chat_id}
+
+    @staticmethod
+    def share_user(user_id: str) -> dict:
+        return {"user_id": user_id}
+
+    @staticmethod
+    def audio(file_key: str) -> dict:
+        return {"file_key": file_key}
+
+    @staticmethod
+    def media(file_key: str, image_key: str = "") -> dict:
+        content = {"file_key": file_key}
+        if image_key:
+            content["image_key"] = image_key
+        return content
+
+    @staticmethod
+    def file(file_key: str) -> dict:
+        return {"file_key": file_key}
+
+
+def build_feishu_message(msg_type: str, **kwargs) -> dict:
+    """统一入口：根据 msg_type 返回 content JSON。
+
+    用法:
+        build_feishu_message("text", text="hi")
+        build_feishu_message("post", title="告警", content=[{"tag":"text","text":"..."}])
+        build_feishu_message("interactive", card={...})
+    """
+    builder = {
+        "text": lambda: FeishuMessageBuilder.text(kwargs.get("text", "")),
+        "post": lambda: FeishuMessageBuilder.post(kwargs.get("title", ""), kwargs.get("content", [])),
+        "image": lambda: FeishuMessageBuilder.image(kwargs.get("image_key", "")),
+        "interactive": lambda: FeishuMessageBuilder.interactive(kwargs.get("card", {})),
+        "share_chat": lambda: FeishuMessageBuilder.share_chat(kwargs.get("chat_id", "")),
+        "share_user": lambda: FeishuMessageBuilder.share_user(kwargs.get("user_id", "")),
+        "audio": lambda: FeishuMessageBuilder.audio(kwargs.get("file_key", "")),
+        "media": lambda: FeishuMessageBuilder.media(kwargs.get("file_key", ""), kwargs.get("image_key", "")),
+        "file": lambda: FeishuMessageBuilder.file(kwargs.get("file_key", "")),
+    }
+    if msg_type not in builder:
+        raise ValueError(f"unsupported msg_type: {msg_type}")
+    return builder[msg_type]()
+
+
+# ── 飞书文件上传（用于 send_audio / send_file / send_image） ──
+
+class FeishuUploader:
+    """飞书 IM 文件上传（拿 file_key / image_key）。"""
+
+    def __init__(self, tenant_token: str):
+        self.token = tenant_token
+        self._http = requests.Session()
+
+    def upload_image(self, file_path: str) -> Optional[str]:
+        """上传图片（≤10MB，jpg/png）。"""
+        return self._upload("image", file_path)
+
+    def upload_file(self, file_path: str, file_type: str = "stream") -> Optional[str]:
+        """上传文件（mp4/opus/stream）。
+
+        file_type: stream | video | audio | attachment
+        """
+        return self._upload(file_type, file_path)
+
+    def _upload(self, file_type: str, file_path: str) -> Optional[str]:
+        import os
+        if not os.path.exists(file_path):
+            return None
+        url = f"{FeishuGateway.FEISHU_BASE}/im/v1/images" if file_type == "image" else f"{FeishuGateway.FEISHU_BASE}/im/v1/files"
+        try:
+            with open(file_path, "rb") as f:
+                data = {"file_type": file_type if file_type != "image" else "image"}
+                r = self._http.post(
+                    url,
+                    params={"type" if file_type == "image" else "file_type": file_type if file_type != "image" else "stream"},
+                    headers={"Authorization": f"Bearer {self.token}"},
+                    files={"file": (os.path.basename(file_path), f)},
+                    timeout=60,
+                )
+            r.raise_for_status()
+            data = r.json()
+            if data.get("code") != 0:
+                logger.error("[feishu upload] fail: %s", data)
+                return None
+            return data["data"].get("file_key") or data["data"].get("image_key")
+        except Exception as e:
+            logger.error("[feishu upload] error: %s", e)
+            return None
+
+
+def create_feishu_gateway(config: dict[str, Any] | None = None) -> FeishuGateway:
+    """工厂函数。"""
+    return FeishuGateway(config=config)

package/interfaces/gateway/_impl/adapters/qq/__init__.py

@@ -0,0 +1,8 @@
+"""Qq Gateway Adapter。
+
+公开类: QQGateway
+工厂: create_qq_gateway(config)
+"""
+from .adapter import QQGateway, create_qq_gateway
+
+__all__ = ["QQGateway", "create_qq_gateway"]