douyin-pc/docs/2026-09-05-23-30-notifications-unread.md

--unread 筛选未读通知

方案与语义

src/get_notifications.py 新增 --unread（store_true），默认关闭，保持原多页获取行为。分页、账号校验、去重完成后，仅保留 has_read 为布尔 false 的通知。缺失、null、数字 0 或字符串 "false" 不当作确定未读。

• notifications 与控制台列表只包含筛选后的未读通知，count 为筛选后条数。
• unread_only 标识是否开启筛选，scope 同步说明范围。
• raw_pages 仍是完整原始响应，可能包含已读消息；用于调研核查，不是未读结果列表。消费未读数据请读取 notifications。
• 不因为一页全已读就停止，防止遗漏后页未读；仍受 --pages 限制（默认 3 页），依据 has_more 提前结束。
• has_more、max_time、stop_reason 均描述原接口分页状态，不代表还有多少未读。即使 count=0，只要 has_more=1，也不能宣称完整历史无未读。
• 请求保持 is_mark_read=0，不打开通知面板、不主动标记已读。

安装与运行

无新依赖，原 browser-harness、Python、CDP 和手动登录前置条件不变。完整安装说明见 2026-09-05-23-15-current-user-notifications.md。

# 最多扫描 3 页，仅返回其中的未读通知
python3 src/get_notifications.py --unread
# 扫描更多页；另存文件，避免覆盖原完整列表
python3 src/get_notifications.py --unread --pages 10 --output src/notifications-unread.json
# 继续扫描：传入上一批返回的 max_time
python3 src/get_notifications.py --unread --pages 10 --max-time <上一批max_time>
# 不带 --unread 时仍输出所有已读状态
python3 src/get_notifications.py --pages 3

验证

执行 python3 src/test_notifications.py，通过。新增 mock CLI 检查实际文件输出：

1. 不带 --unread 保留所有状态。
2. 带 --unread 只保留布尔 false，排除 true、null、0、字符串和缺失值。
3. 第一页全已读仍扫描第二页并返回其未读记录。
4. 页数上限为 1 且第一页全已读时输出空列表，但保留 has_more=1 与 page_limit。
5. raw_pages 保持原始内容，计数和 unread_only 正确。

CLI --help 已验证。此次只做离线验证，未重新请求真实账号；没有改写已有 src/notifications.json。