{"skill":{"slug":"lark-bot-listener","displayName":"Pywayne Lark Bot Listener","summary":"Feishu/Lark message listener for real-time message processing via WebSocket. Use when users need to listen for incoming Feishu messages (text, image, file, p...","description":"---\nname: pywayne-lark-bot-listener\ndescription: Feishu/Lark message listener for real-time message processing via WebSocket. Use when users need to listen for incoming Feishu messages (text, image, file, post) with automatic deduplication and async handling. Provides convenient decorators (text_handler, image_handler, file_handler) that handle message download/cleanup and optional automatic reply.\n---\n\n# Pywayne Lark Bot Listener\n\n飞书消息监听器，通过 WebSocket 实时接收和处理飞书消息。\n\n## Quick Start\n\n```python\nfrom pywayne.lark_bot_listener import LarkBotListener\n\n# 初始化监听器\nlistener = LarkBotListener(\n    app_id=\"your_app_id\",\n    app_secret=\"your_app_secret\",\n    message_expiry_time=60  # 消息去重过期时间（秒）\n)\n\n# 处理文本消息\n@listener.text_handler()\nasync def handle_text(text: str):\n    print(f\"收到消息: {text}\")\n\n# 启动监听\nlistener.run()\n```\n\n## Decorators - 消息处理装饰器\n\n### text_handler\n\n文本消息处理装饰器，直接传递文本内容。\n\n```python\n@listener.text_handler(group_only=False, user_only=False)\nasync def handle_text(text: str, chat_id: str, is_group: bool, group_name: str, user_name: str):\n    print(f\"收到来自 {user_name} 的消息: {text}\")\n    listener.send_message(chat_id, f\"已收到：{text}\")\n```\n\n**参数说明**（除 `text` 外均为可选）：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `text` | str | 文本内容（必需） |\n| `chat_id` | str | 会话 ID |\n| `is_group` | bool | 是否群组消息 |\n| `group_name` | str | 群组名称（私聊时为空） |\n| `user_name` | str | 发送消息的用户姓名 |\n\n**装饰器参数**：\n- `group_only=True`: 只处理群组消息\n- `user_only=True`: 只处理私聊消息\n\n### image_handler\n\n图片消息处理装饰器，自动下载图片到临时文件并清理。\n\n```python\nfrom pathlib import Path\nimport cv2\nimport tempfile\n\n@listener.image_handler()\nasync def handle_image(image_path: Path, user_name: str) -> Path:\n    # 处理图片\n    img = cv2.imread(str(image_path))\n    # ...处理逻辑...\n    # 返回新图片路径会自动发送回去，返回 None 则不发送\n    return image_path\n```\n\n**参数说明**（除 `image_path` 外均为可选）：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `image_path` | Path | 临时图片文件路径（必需） |\n| `chat_id` | str | 会话 ID |\n| `is_group` | bool | 是否群组消息 |\n| `group_name` | str | 群组名称 |\n| `user_name` | str | 发送消息的用户姓名 |\n\n**返回值**：\n- 返回 `Path`: 自动上传并发送新图片\n- 返回 `None`: 不发送任何图片\n\n### file_handler\n\n文件消息处理装饰器，自动下载文件到临时文件并清理。\n\n```python\n@listener.file_handler()\nasync def handle_file(file_path: Path, user_name: str) -> Path:\n    # 处理文件\n    with open(file_path, 'r') as f:\n        content = f.read()\n    # ...处理逻辑...\n    return file_path  # 返回文件路径会自动发送回去\n```\n\n**参数说明**（除 `file_path` 外均为可选）：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `file_path` | Path | 临时文件路径（必需） |\n| `chat_id` | str | 会话 ID |\n| `is_group` | bool | 是否群组消息 |\n| `group_name` | str | 群组名称 |\n| `user_name` | str | 发送消息的用户姓名 |\n\n## listen - 通用消息监听器\n\n用于监听任意类型消息（包括富文本 post）。\n\n```python\n@listener.listen(message_type=\"post\")\nasync def handle_post(ctx: MessageContext):\n    print(f\"收到富文本消息: {ctx.content}\")\n```\n\n**MessageContext 属性**：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `chat_id` | str | 会话 ID |\n| `user_id` | str | 用户 ID |\n| `message_type` | str | 消息类型 |\n| `content` | str | 消息内容（文本消息为字符串，其他类型为 JSON 字符串） |\n| `is_group` | bool | 是否群组消息 |\n| `chat_type` | str | 会话类型 |\n| `message_id` | str | 消息 ID |\n\n## send_message - 发送消息\n\n发送 Markdown 格式的消息到飞书。\n\n```python\nlistener.send_message(chat_id, \"**这是加粗文本**\")\nlistener.send_message(chat_id, \"普通文本\\n[链接](https://example.com)\")\n```\n\n## 完整示例\n\n```python\nfrom pywayne.lark_bot_listener import LarkBotListener\nfrom pathlib import Path\n\nlistener = LarkBotListener(\n    app_id=\"your_app_id\",\n    app_secret=\"your_app_secret\"\n)\n\n# 文本消息 - AI 回复示例\n@listener.text_handler()\nasync def handle_text(text: str, chat_id: str, user_name: str):\n    # 处理逻辑...\n    listener.send_message(chat_id, f\"收到来自 {user_name} 的消息\")\n\n# 图片消息 - 自动下载和清理\n@listener.image_handler()\nasync def handle_image(image_path: Path):\n    # image_path 是临时文件，处理完会自动清理\n    print(f\"处理图片: {image_path}\")\n\n# 文件消息 - 自动下载和清理\n@listener.file_handler(group_only=True)\nasync def handle_file(file_path: Path, group_name: str):\n    print(f\"收到文件: {file_path} 来自 {group_name}\")\n\n# 富文本消息\n@listener.listen(message_type=\"post\")\nasync def handle_post(ctx: MessageContext):\n    import json\n    post_content = json.loads(ctx.content)\n    print(f\"收到富文本: {post_content}\")\n\n# 启动监听\nlistener.run()\n```\n\n## 注意事项\n\n1. **异步处理**: 所有处理函数使用 `async/await` 语法\n2. **消息去重**: 每个处理函数独立去重，默认 60 秒过期\n3. **临时文件**: 图片和文件下载到 `系统临时目录/lark_bot_temp`，处理完自动清理\n4. **错误隔离**: 每个处理函数异常独立捕获，不影响其他函数\n5. **多注册**: 同一消息可被多个处理函数处理\n","tags":{"latest":"0.1.0"},"stats":{"comments":0,"downloads":1056,"installsAllTime":40,"installsCurrent":1,"stars":0,"versions":1},"createdAt":1771230214770,"updatedAt":1778491552996},"latestVersion":{"version":"0.1.0","createdAt":1771230214770,"changelog":"Initial release of pywayne-lark-bot-listener.\n\n- Provides real-time Feishu/Lark message listening via WebSocket with async handling and deduplication.\n- Convenient decorators for handling text, image, file, and post messages.\n- Automatic download, cleanup, and optional reply for image/file handlers.\n- Unified send_message API for sending Markdown messages.\n- Includes robust async and error isolation features, with support for group/private messages.\n- Rich documentation and code examples provided for rapid integration.","license":null},"metadata":null,"owner":{"handle":"wangyendt","userId":"s172p3g61c0j9vy0sa1bs01b7x885y52","displayName":"wangyendt","image":"https://avatars.githubusercontent.com/u/18455758?v=4"},"moderation":null}