feishu-chat-history

name	feishu_chat_history
description	飞书会话历史消息的获取、分页拉取与导出。当需要「获取/下载/访问/查找历史聊天记录」、按时间范围或关键词梳理对话、将会话记录导出到本地时使用。基于飞书开放平台「获取会话历史消息」API（im v1 message list），独立于主代码，避免 butler_bot 臃肿。
family_id	feishu-history
family_label	飞书历史族
family_summary	面向飞书会话历史消息的抓取、分页导出与复盘整理。
family_trigger_examples	飞书历史, 聊天记录导出, 会话复盘
risk_level	low
variant_rank	10
metadata	{"category":"feishu"}

飞书历史聊天记录 (Feishu Chat History)

基于 飞书开放平台 - 获取会话历史消息 实现：获取、分页拉取、导出 指定会话（单聊/群聊）的历史消息，供 Agent 或主程序按需调用，不污染主代码。

使用场景

• 获取某单聊/群聊的历史消息列表（含分页）
• 按时间范围（start_time / end_time）筛选历史记录
• 分页拉取全部历史并合并为一份列表或导出到本地文件
• 查找、统计、复盘某会话的对话内容

快速开始

依赖

• Python 3.8+
• requests（与 butler_bot 主项目一致）

配置来源

凭证与会话 ID 的真实来源与解析顺序如下：

• 应用凭证 (app_id / app_secret)

  • 若函数入参中显式传入 app_id / app_secret，优先使用入参。
  • 否则，若传入 config_provider() -> dict，且返回字典中包含 app_id / app_secret，则复用该配置；推荐直接复用主进程的 CONFIG。
  • 否则，尝试从环境变量 FEISHU_APP_ID / FEISHU_APP_SECRET 读取。
  • 若以上都未命中，兜底从 Butler 主体配置 butler_main/butler_bot_code/configs/butler_bot.json 中读取 app_id / app_secret，与 agent.py / 飞书长连接使用的是同一份配置。
  • 若最终仍无法获得完整的 app_id + app_secret，才会抛出错误提示。

• 会话 ID (container_id / chat_id)

  • 若函数入参中显式传入 container_id，则直接使用该值（推荐传入具体 chat_id，形如 oc_xxx）。
  • 否则，尝试从环境变量 FEISHU_CHAT_ID 读取默认会话 ID，用于在本地或后台巡检脚本中与主进程对齐同一个会话。
  • 若两者都为空，会抛出显式错误，提示调用方补全 container_id 或配置 FEISHU_CHAT_ID。

小结：在本地与生产环境中，只要主进程已经通过 butler_bot.json 正常运行飞书长连接，feishu_chat_history 在不传任何 app_id/app_secret 参数的情况下，也能自动复用同一套飞书应用凭证，避免出现「本地拿不到凭证」的错误结论。

在代码中调用

from butler_bot_agent.skills.feishu_chat_history import (
    get_tenant_token,
    list_messages,
    list_all_messages,
    download_messages_to_file,
)

# 方式一：直接传 app_id / app_secret
token = get_tenant_token(app_id=, app_secret=)
page = list_messages(
    container_id=,  
    container_id_type=,
    app_id=,
    app_secret=,
    page_size=,
)



all_items, summary = list_all_messages(
    container_id=,
    app_id=,
    app_secret=,
    start_time=,  
    end_time=,    
)
path = download_messages_to_file(
    container_id=,
    app_id=,
    app_secret=,
    output_path=,
    start_time=,
    end_time=,
)