Pywayne Lark Bot

Pywayne Lark Bot

飞书机器人模块，提供完整飞书 API 交互功能，包括消息发送、文件管理、用户/群组查询和消息监听。

Quick Start

from pywayne.lark_bot import LarkBot, TextContent # 初始化 bot = LarkBot(app_id="your_app_id", app_secret="your_app_secret") # 发送文本消息到用户 bot.send_text_to_user(user_open_id="user_xxx", text="Hello!") # 发送文本消息到群聊 bot.send_text_to_chat(chat_id="oc_xxx", text="Group message")

TextContent - 文本格式化工具

创建各种文本格式，用于发送带格式的文本消息。

Mentions

# @所有人 at_all = TextContent.make_at_all_pattern() # @指定用户 at_user = TextContent.make_at_someone_pattern(user_open_id="user_xxx", username="张三", id_type="open_id")

Text Styles

# 加粗、斜体、下划线、删除线 bold = TextContent.make_bold_pattern("粗体") italic = TextContent.make_italian_pattern("斜体") underline = TextContent.make_underline_pattern("下划线") strikethrough = TextContent.make_delete_line_pattern("删除线") # 超链接 link = TextContent.make_url_pattern("https://example.com", "点击访问")

推荐路径：发送 Markdown（优先使用）

• 优先使用 send_markdown_to_chat，它会自动处理大文本分包，并支持两种路由：
• prefer="card_v2"（默认）：发送 schema 2.0 interactive 卡片，适合绝大多数 Markdown 场景
• prefer="post"：发送 post 富文本；可设置 table_fallback="code_block" 将 Markdown 表格稳定降级
• md = """
• # 发布说明
• 新增对账接口
• 修复支付重试逻辑
• | 模块 | 状态 |
• | --- | --- |
• | API | 完成 |
• | FE | 测试中 |
• """
• # 默认走 card_v2（推荐）
• bot.send_markdown_to_chat(
• chat_id="oc_xxx",
• md_text=md,
• title="版本进度",
• prefer="card_v2"
• )
• # 需要 post 时切换路由
• bot.send_markdown_to_chat(
• chat_id="oc_xxx",
• md_text=md,
• title="版本进度",
• prefer="post",
• table_fallback="code_block"
• )

发送消息

Text Message bot.send_text_to_user(user_open_id, "私聊消息") bot.send_text_to_chat(chat_id, "群聊消息") Image Message # 上传图片 image_key = bot.upload_image("/path/to/image.jpg") # 发送图片 bot.send_image_to_user(user_open_id, image_key) bot.send_image_to_chat(chat_id, image_key) Audio / Media / File Message # 上传文件 file_key = bot.upload_file("/path/to/file.pdf", file_type="pdf") # 发送音频 bot.send_audio_to_user(user_open_id, file_key) # 发送多媒体 bot.send_media_to_chat(chat_id, file_key) # 发送文件 bot.send_file_to_user(user_open_id, file_key) Post (Rich Text) Message from pywayne.lark_bot import PostContent post = PostContent(title="富文本标题") # 添加内容 line = post.make_text_content("这是粗体文本", styles=["bold"]) post.add_content_in_new_line(line) # 发送 bot.send_post_to_user(user_open_id, post.get_content()) bot.send_post_to_chat(chat_id, post.get_content()) Interactive Card Message # 直接传原始 interactive 卡片 card = { "header": {"title": {"content": "卡片标题", "tag": "plain_text"}}, "elements": [...] } bot.send_interactive_to_user(user_open_id, card) bot.send_interactive_to_chat(chat_id, card) CardContentV2（schema 2.0 卡片构造器） from pywayne.lark_bot import CardContentV2 card = CardContentV2(title="日报", template="blue") card.add_markdown("# 今日进展\n\n- 完成接口联调\n- 修复2个问题") card.add_hr() card.add_image(img_key="img_xxx") bot.send_interactive_to_chat(chat_id, card.get_card()) Share Message # 分享群聊 bot.send_shared_chat_to_user(user_open_id, shared_chat_id) bot.send_shared_chat_to_chat(chat_id, shared_chat_id) # 分享用户 bot.send_shared_user_to_user(user_open_id, shared_user_id) bot.send_shared_user_to_chat(chat_id, shared_user_id)

PostContent - 富文本构建器

post = PostContent(title="标题") # 可用内容类型 text = post.make_text_content("文本", styles=["bold", "underline"]) link = post.make_link_content("链接文字", "https://example.com") at = post.make_at_content(user_open_id) img = post.make_image_content(image_key="img_xxx") media = post.make_media_content(file_key="file_xxx", image_key="thumb_xxx") emoji = post.make_emoji_content(emoji_type="OK") hr = post.make_hr_content() code_block = post.make_code_block_content(language="python", text="print('hello')") markdown = post.make_markdown_content("**Markdown**") # 添加内容 post.add_content_in_new_line(text) post.add_contents_in_line([link, at]) # 同一行添加多个元素 # 推荐：直接添加 markdown，支持分块与表格降级 md = """ ## 迭代计划 | 任务 | 状态 | | --- | --- | | A | done | | B | doing | """ post.add_markdown(md, table_as="code_block", max_chunk_bytes=8000)

文件操作

# 上传 image_key = bot.upload_image("/path/to/image.jpg") file_key = bot.upload_file("/path/to/file.pdf", file_type="pdf") # 下载 bot.download_image(image_key, "/save/path/image.jpg") bot.download_file(file_key, "/save/path/file.pdf") # 下载消息中的所有资源 resources = bot.download_message_resources( message_id="msg_xxx", message_content='{"image_key":"img_xxx"}', save_dir="/save/dir" )

用户与群组查询

# 获取用户信息 users = bot.get_user_info(emails=["test@example.com"], mobiles=["13800138000"]) # 获取群组列表 groups = bot.get_group_list() # 通过群名获取群ID chat_ids = bot.get_group_chat_id_by_name("项目讨论组") # 获取群成员 members = bot.get_members_in_group_by_group_chat_id(chat_id) # 通过群成员名获取 open_id member_ids = bot.get_member_open_id_by_name(chat_id, "张三") # 获取群名和用户名 chat_name, user_name = bot.get_chat_and_user_name(chat_id, user_id)

LarkBotListener - 消息监听

飞书消息监听器，用于实时接收和处理消息。 from pywayne.lark_bot_listener import LarkBotListener from pathlib import Path listener = LarkBotListener( app_id="your_app_id", app_secret="your_app_secret" )

文本消息处理

@listener.text_handler(group_only=False, user_only=False) async def handle_text(text: str, chat_id: str, is_group: bool, group_name: str, user_name: str): print(f"收到来自 {user_name} 的消息: {text}") # 回复 listener.send_message(chat_id, f"已收到：{text}")

图片消息处理

@listener.image_handler(group_only=True) async def handle_image(image_path: Path, chat_id: str, user_name: str): print(f"收到图片: {image_path}") # 处理图片...

文件消息处理

@listener.file_handler() async def handle_file(file_path: Path, chat_id: str, user_name: str): print(f"收到文件: {file_path}") # 处理文件...

通用消息监听

@listener.listen(message_type="post") async def handle_post(ctx): print(f"收到富文本消息: {ctx.content}")

启动监听

listener.run()

监听器参数说明

Handler 参数（除必需参数外均为可选）： Handler必需参数可选参数text_handlertextchat_id, is_group, group_name, user_nameimage_handlerimage_pathchat_id, is_group, group_name, user_namefile_handlerfile_pathchat_id, is_group, group_name, user_name 装饰器参数： message_type: 消息类型（"text", "image", "file", "post"） group_only=True: 只监听群组消息 user_only=True: 只监听私聊消息

注意事项

所有处理函数使用 async/await 语法 消息会去重（默认 60 秒） 图片和文件下载到临时目录，处理完及时清理 每个处理函数异常独立捕获，不影响其他函数