核心用法
feishu-forward-reader 是飞书生态专用的消息解析工具，核心功能是破解合并转发消息（merge_forward）的内容封装，提取被转发的原始子消息列表。
典型使用场景：
- 在 OpenClaw 等自动化平台中，飞书合并转发消息默认只显示 "Merged and Forwarded Message" 占位文本，无法查看实际内容
- 通过此工具传入
message_id，调用飞书 Open API 获取完整的消息层级结构
三种调用方式：
1. Python脚本（推荐）：python3 scripts/parse_forward.py <message_id>，支持 JSON 输出、自定义凭证
2. Shell脚本：./scripts/read_forward.sh，直接返回原始 API 响应
3. 原生API调用：手动获取 tenant_access_token 后请求 /im/v1/messages/<message_id>
消息解析逻辑：
- API 返回的
items数组中，首条为转发消息本体（msg_type: merge_forward） - 后续条目为被转发的原始消息，通过
upper_message_id关联父消息 - 支持文本、富文本、卡片、图片/文件/音视频等多种格式的内容还原
显著优点
- 解决平台兼容性痛点：针对性修复 OpenClaw 等工具对飞书合并转发消息的解析缺陷
- 多格式完整支持：覆盖 text/post/interactive/image/file/audio/video 全量消息类型
- 灵活凭证管理：支持命令行参数传入、环境变量等多种认证方式
- 结构化输出：提供人类可读格式与 JSON 机器格式两种输出选项
潜在缺点与局限性
- 权限门槛较高：依赖
im:message:readonly敏感权限，需企业管理员审批开通 - 凭证依赖：必须持有有效的飞书应用
app_id和app_secret，个人用户难以独立使用 - 无内置缓存：每次调用均实时请求飞书 API，高频场景可能触发速率限制
- 功能单一：仅专注合并转发消息解析，不涵盖普通单条消息处理
适合人群
- 企业飞书管理员：需审计或归档群聊转发内容
- OpenClaw/自动化平台用户：解决工作流中的消息解析障碍
- 飞书应用开发者：调试消息结构或开发衍生功能
常规风险
- 权限滥用风险：
im:message:readonly可读取群组全部历史消息，凭证泄露可能导致企业数据大规模暴露 - Token 安全：
tenant_access_token有效期较短，但脚本中可能以明文形式临时存储 - 隐私合规：解析后的消息内容可能包含敏感信息，需确保存储与传输符合企业数据安全规范
- API 稳定性：依赖飞书 Open API 版本迭代，存在接口变更导致解析失败的维护风险