Discord 频道消息拉取

把指定 Discord 频道的聊天记录拉成干净的结构化 JSON/CSV，每条消息是一行扁平记录，可直接写入飞书多维表格。拉取逻辑（翻页、限流退避、去重）封装在 scripts/discord_fetch.py 里，写入逻辑封装在 scripts/feishu_write.py 里，执行脚本即可，不要自己重写 HTTP 调用。

前置条件（首次使用必读）

用户需要在 Discord 端准备好（详见 references/setup.md）：

一个 Bot Token（开发者后台 → 应用 → Bot → Reset Token）。
已把 bot 邀请进目标服务器。
开启 Message Content Intent，否则拉到的消息正文 content 会是空的——这是最常见的坑。
bot 在目标频道有 "View Channel" + "Read Message History" 权限。
一个 Channel ID（Discord 开启开发者模式 → 右键频道 → 复制频道 ID）。

如需写入飞书，还需要：飞书应用的 FEISHU_APP_ID 和 FEISHU_APP_SECRET，以及目标多维表格的 app_token 和 table_id。

Token 的提供方式（按安全优先级）

环境变量 DISCORD_BOT_TOKEN（推荐）：不进对话上下文、不入日志，最安全。
--token 参数：仅在多 token 临时切换时使用。

绝不要把完整 token 写进回复正文或反复回显。脚本内部只会显示首尾各 4 位的指纹。

操作步骤

第零步：环境自检（推荐首次运行）

python scripts/discord_fetch.py --channel <CHANNEL_ID> --check

一次性验证：token 有效 + bot 能访问频道 + Message Content Intent 已开启。出错时有明确提示。

第一步（可选）：确认能看到频道

python scripts/discord_fetch.py --channel <CHANNEL_ID> --info

第二步：拉取消息

全量（最新 N 条，自动翻页）：

python scripts/discord_fetch.py --channel <CHANNEL_ID> --max 200 --format json

按日期范围过滤：

python scripts/discord_fetch.py --channel <CHANNEL_ID> \
  --after-date 2026-01-01 --before-date 2026-02-01

增量同步（只拉比检查点更新的消息）：

python scripts/discord_fetch.py --channel <CHANNEL_ID> --after <上次的_newest_message_id>

导出 CSV：

python scripts/discord_fetch.py --channel <CHANNEL_ID> --max 500 --format csv > messages.csv

输出 JSON 结构：

{
  "channel_id": "...",
  "count": 123,
  "newest_message_id": "...",
  "oldest_message_id": "...",
  "reached_end": true,
  "messages": [
    {
      "message_id": "...", "channel_id": "...",
      "author_id": "...", "author_username": "...", "author_global_name": "...",
      "is_bot": false, "content": "消息正文",
      "timestamp": "2026-01-01T00:00:00+00:00", "edited_timestamp": null,
      "reply_to_message_id": null,
      "attachment_count": 0, "attachments": [], "embed_count": 0, "embeds": []
    }
  ]
}

第三步：写入飞书多维表格

# 一条命令完成拉取 + 写入
python scripts/discord_fetch.py --channel <CHANNEL_ID> --max 500 \
  | python scripts/feishu_write.py \
      --app-token <BITABLE_APP_TOKEN> \
      --table-id <TABLE_ID>

先 dry-run 预览不写入：

python scripts/discord_fetch.py --channel <CHANNEL_ID> --max 10 \
  | python scripts/feishu_write.py \
      --app-token <BITABLE_APP_TOKEN> --table-id <TABLE_ID> --dry-run

关键约定：多维表格里的 message_id 列设为唯一标识去重；每次拉取后存下 newest_message_id，下次作为 --after 传入做增量同步。

详细字段映射与增量同步编排见 references/feishu-bitable.md，更多用法示例见 examples/。

注意事项

消息正文为空，几乎都是没开 Message Content Intent，先去后台开启（或运行 --check）。
--max 上限 5000，频道很大时建议分批 + 增量同步。
触发 429（限流）脚本会自动退避重试，一般无需干预。
脚本进度和日志输出到 stderr，stdout 只有干净的 JSON/CSV，可以直接管道到下游。