douyin-pc/docs/2026-09-05-23-27-notifications-pagination.md

通知多页获取

目标和范围

在现有通知脚本上增加自动翻页，作为后续提取未读通知的基础。本次按要求不筛选 has_read、不遇到已读就停止；保留已读字段及发送者 douyin_id。未实现“获取全部未读”。

方案

• src/get_notifications.py 增加 --pages，默认最多 3 页；--max-time 指定起始游标，默认 0（最新）。页数必须为正数，时间游标不能为负数。
• 复用现有单页请求，每页固定 count=10、is_mark_read=0。页间暂停 0.5 秒，顺序请求、不并发、不自动重试。
• 第一页之后将上一响应 max_time 作为下一请求游标。不自行计算时间偏移，也不根据返回条数判断结束。
• has_more=0 提前结束，否则达到页数上限停止。短页或空页只要游标有效且推进，就继续。
• 每页校验通知归属当前账号；has_more 异常、游标无效/不向历史推进、接口异常时退出，不覆盖旧结果，不自动登录。
• 按 nid_str（回退为 nid 的字符串形式）去重，保留先遇到的数据与接口顺序；原始页面仍保留重复记录。
• 所有请求成功后一次性写临时文件，再原子替换输出。失败批次不保存部分数据；原文件保留。

输出变更

文件仍为 src/notifications.json：

• notifications：多页去重后的摘要，保留 users[].douyin_id。
• count：去重后总条数。
• pages_fetched：实际请求页数。
• stop_reason：page_limit（达到页数上限，仍有更多）或 exhausted（接口表示结束）。
• has_more / max_time：最后一页分页状态，供下一批继续获取。
• 原单页 raw 改为 raw_pages 数组，逐页保存完整原始响应。读取旧 raw 字段的外部代码需要相应调整；仓库的旧调研文档仅反映当时单页格式。

每次运行替换指定输出文件，不自动合并上次运行结果。若分批抓取需保留多批，请使用不同 --output 路径。

安装与运行

无新增依赖，仍使用 Python 标准库与 browser-harness；需要将 get_current_user.py 与通知脚本放在同一目录。空白环境安装和 CDP/手动登录步骤见 2026-09-05-23-15-current-user-notifications.md。不绑定账号或环境。

# 默认 3 页
python3 src/get_notifications.py
# 最多 10 页；若服务端没有更多则提前结束
python3 src/get_notifications.py --pages 10
# 兼容只取一页
python3 src/get_notifications.py --pages 1
# 继续上一批，另存文件；游标必须使用实际响应值
python3 src/get_notifications.py --pages 3 --max-time 1777630376 --output src/notifications-next.json
# 离线检查
python3 src/test_notifications.py

实测记录

2026-09-05 23:27，执行 python3 src/get_notifications.py --pages 3：

• 成功抓取 3 页，分别 10、7、2 条。
• 去重后 19 条，保存到 src/notifications.json。
• has_more=1，max_time=1777630376，stop_reason=page_limit；仍有历史数据，不能称为全部。
• 实际返回 19 条 has_read 均为 true，全部保留，证明本次未启用未读过滤。
• 与前次快照相比新增一条肉宝儿通知，属于实时数据变化，本次并未触发点赞操作。
• 离线检查通过，覆盖游标传递、短页/空页继续、去重、页数上限、无更多时提前结束、游标停滞/逆向/缺失、账号不匹配和中途请求失败停止。
• 保存后的 JSON 再经标准库解析和断言验证：页面数、总数、ID 唯一性及每位发送者包含 douyin_id 字段均通过。