rogee/douyin-pc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
07524a36cdc7daff6259748ea7ea74ba1a6400fa
douyin-pc/docs/2026-09-06-11-05-PLAN.md
T

16 KiB
Raw Blame History

PLAN：Windows 多账号通知监听与任务执行

本文整合已确认产品需求、推荐技术方案、UX 与实施计划，作为后续开发入口。本文是计划，不代表功能已经实现或完成 Windows 验证。原调研文档保留供追溯；如存在冲突，以本文中的最新已确认需求为准。

1. 已确认需求

1.1 运行环境

  • 运行在 Windows，首版使用官方 Chrome。
  • 浏览器可执行路径和附加启动参数必须可配置，为后续切换 fingerprint-chromium 预留入口；暂不实现或启用其指纹功能。
  • 支持多个独立账号浏览器环境，通过 CDP 连接。
  • 支持多个大号同时登录并持续监听通知。
  • 启动多少账号由使用者根据机器性能自行决定；产品不提供容量评估、推荐数量或自动性能定额。
  • 仍需展示实际启动失败、连接异常等错误，不因不做容量评估而隐藏问题。

1.2 角色与归属

  • 大号：监听通知，并根据规则产生关注、私信执行任务。
  • 小号：执行归属大号下发的关注、私信任务。
  • 一个大号可以关联多个小号。
  • 一个小号同一时间只能服务于一个大号，可以按需要切换归属。
  • 大号产生的任务只能派发给其关联的小号，不得跨组派发，也不得交给大号执行。
  • “下发到小号”指下发执行任务，不表示把通知内容作为私信转发给小号。

1.3 登录持久化与恢复

  • 保存每个账号的独立登录环境，关机后保留。
  • 提供一键启动，恢复所选账号环境并检查登录状态。
  • 登录有效时恢复对应监听或执行能力；登录失效时提示用户手动登录，不自动尝试登录。
  • 不承诺 Cookie 永不过期，也不把“一键启动”描述为无条件自动登录成功。

2. 方案建议与边界

以下为推荐实现，区别于上节已确认需求。

2.1 技术栈

模块 推荐技术 职责
核心 Python 3.12 复用现有业务脚本
Chrome 管理 subprocess、pathlib 启动实例，管理目录、端口和进程
浏览器接入 Playwright Python 异步 API、CDP 显式绑定每个账号的连接和页面
调度 asyncio 多大号监听、任务分发、小号串行消费
持久化 SQLite / sqlite3 账号、归属、事件和任务状态
桌面界面 PySide6 账号组管理、状态、启停与日志
日志 logging 错误与操作记录，敏感字段脱敏
Windows 分发 PyInstaller Windows 原生构建，初期使用 onedir

初期单进程调度，各账号独立异步 worker，同一小号串行执行、不同小号可并发。不引入 Redis、Celery、微服务、Docker、Electron，也不先做 Windows Service。

2.2 业务执行方式

  • 最终关注、私信和通知处理不依赖模拟点击或遍历 DOM；页面交互仅用于调研触发请求及用户手动登录。
  • 推荐复用当前浏览器上下文内的接口调用与 IM SDK 逻辑，Playwright 作为 CDP、JS 和网络事件通道。
  • 浏览器内调用接口/SDK 不等于完全脱离浏览器的纯 HTTP 方案。后者涉及签名、令牌和长连接协议验证，不在本计划中承诺。
  • 页面内部 SDK 不是稳定公开契约，需处理页面版本变化导致的不可用。
  • src 中保留可独立运行的 Python 功能脚本；公共能力可复用，不硬编码环境路径、账号或目标页面 ID。

2.3 浏览器可配置启动（已确认方向）

首版验证官方 Chrome，后续可通过配置选择 fingerprint-chromium 等兼容 CDP 的 Chromium 浏览器，不将浏览器路径写死在业务脚本中。

最小配置建议：

{
  "browser": {
    "executable_path": null,
    "extra_args": []
  }
}
  • executable_path 为空时查找本机官方 Chrome；填写时严格使用指定文件，路径无效立即报错，不静默回退到其它浏览器。
  • extra_args 为字符串数组，默认空；使用 subprocess 参数列表启动，不拼接 shell 命令。
  • user-data-dir、CDP 端口及本机访问限制由程序统一管理；附加参数不得覆盖这些隔离设置或关闭必要安全防护，冲突应报错。
  • 配置持久化，一键启动读取同一份配置；设置界面提供可执行文件选择，附加参数放在高级设置。
  • 通知、关注、私信代码只使用显式账号连接，不关心浏览器品牌。不先建立多内核插件或适配框架。
  • 修改配置不热切换正在运行的实例，下次受控启动才生效；存在旧实例时不得把旧连接当成新配置已生效。
  • 更换浏览器内核不自动共用或转换原登录目录，应使用独立目录验证，保留旧环境；不承诺跨内核迁移后仍免登录。
  • fingerprint-chromium 正式启用前另行验证 Windows、CDP、登录恢复、通知与 IM 流程和供应链安全；可配置不等于已经兼容，也不承诺防关联或防封。

3. 账号环境与隔离

大号 A → 独立 Chrome 数据目录 / CDP 连接
  ├─ 小号 A1 → 独立 Chrome 数据目录 / CDP 连接
  └─ 小号 A2 → 独立 Chrome 数据目录 / CDP 连接
大号 B → 独立 Chrome 数据目录 / CDP 连接
  └─ 小号 B1 → 独立 Chrome 数据目录 / CDP 连接
  • 每个账号一个独立 user-data-dir、Chrome 主实例和 CDP 端口。
  • 不仅靠同一 User Data 下的 --profile-directory 实现进程隔离。
  • Chrome 路径、存储根目录和端口可配置或自动发现；检测端口冲突、目录占用，重复启动不得生成重复实例。
  • 使用非默认 Chrome 数据目录；Chrome 136 起默认目录的远程调试限制需在目标版本实测。
  • 账号记录预期 UID；连接及写操作前核验实际身份，不把“第一个标签页”当成账号选择规则。
  • CDP 仅允许本机访问；登录目录与数据库仅供必要的本机用户访问，不记录 Cookie、令牌或完整带签名 URL。
  • 切换归属仅修改关系，不退出登录、不更换数据目录、不创建新的小号实例。

4. UX

4.1 主界面

以“大号及其关联小号”为账号组，另设“未分配小号”。大号不是单独执行池成员。

每组展示：

  • 大号头像、昵称及账号标识。
  • 登录状态、监听状态。
  • 关联小号列表、可用数量、各小号执行状态。
  • 待执行、成功、失败、结果待核对的任务数量与记录。

操作建议：

  • 添加大号、添加小号。
  • 启动/停止单组、启动所选账号组、停止全部。
  • 关联小号、解除关联、切换所属大号。
  • 打开账号浏览器供手动登录或查看。
  • 查看任务记录、异常和日志。

登录、连接、监听/执行状态分别展示，不能把“已登录”等同于“正在监听”或“可执行”。账号数量不做性能推荐。

4.2 小号归属切换（任务处置方案待确认）

建议流程：

  1. 选择“切换所属大号”，选定目标大号。
  2. 展示原归属、新归属、待执行数量与执行中状态。
  3. 若有正在执行的任务，暂不允许切换，等任务结束后再操作；不强制中断已经发出的请求。
  4. 确认后暂停该小号接收和领取任务，在同一事务中取消旧归属待执行任务并更新归属。
  5. 保留历史及取消原因，不把旧任务带入新组，也不自动改派其它小号。
  6. 切换后仅接收新归属大号的任务。

确认提示示例：

将小号 X 从大号 A 切换至大号 B。原有 5 条待执行任务将取消，历史记录保留。是否继续？

后端必须保证切换与任务领取/执行互斥，并校验任务来源与当前归属，不能只在 UI 过滤。执行结果未知的任务保留待核对状态，不因切换而重发。

“解除关联”与“删除登录数据”分开操作；删除登录数据须单独确认。

5. 通知与任务流程

各大号监听通知
  → 事件落库、去重
  → 按规则生成任务
  → 仅派发给所属小号
  → 每个小号串行执行
  → 核验结果、保存状态

5.1 持久化建议

保持最小模型，不使用多对多归属表：

数据 主要内容
账号 内部 ID、角色、预期 UID、显示信息、数据目录、CDP 配置、启用配置
归属 小号上的可空 owner_account_id，仅允许指向大号
事件 来源大号、通知 ID、接收时间、必要内容、处理状态
任务 来源大号/事件、执行小号、目标 UID、动作/步骤、参数、状态、结果和错误

未分配小号不接收任务。数据库保存任务原来源，不因当前归属改变而重写历史。

  • 事件去重至少包含来源大号和通知 ID。
  • 任务去重包含来源事件、执行小号、动作/步骤和目标。
  • SQLite 是任务真源，内存队列只用于调度，不能作为唯一存储。
  • 事件入库与任务生成须支持中断恢复，不能出现事件被标记已处理但任务未生成的永久遗漏。

5.2 状态与恢复

建议任务状态：pending、running、succeeded、failed、unknown、cancelled。

  • 请求超时不等于执行失败；关注需回查，私信需根据消息标识或人工核对。
  • 结果不确定时记录 unknown，禁止无条件重发。
  • 重启遗留 running 任务先核对，不直接重置为 pending。
  • 若规则要求先关注再私信，应显式记录步骤与成功条件，不仅依赖队列顺序。
  • 页面刷新或连接中断后重新连接并安装订阅；断线通知是否能补拉需验证，不承诺零丢失。
  • 登录失效、验证码或风控暂停相关账号并提示用户，不自动登录或绕过验证。

6. 一键启动与 Windows 生命周期

读取所选账号组与归属
  → 复用或启动独立 Chrome 实例
  → 连接对应 CDP
  → 核验实际 UID、登录状态
  ├─ 有效：恢复监听/执行能力并核对遗留任务
  └─ 失效：标记需要登录，等待用户处理
  • 某个账号失败不得把任务错发给其它组；界面分别展示各账号恢复结果。
  • 大号失效时不再产生新任务；小号失效时暂停其执行。
  • 登录目录保存在本机持久位置，与临时文件及打包解压目录分离。
  • 运行在用户交互式会话；如需要开机自启，可采用用户登录后的任务计划，不依赖 Session 0 启动交互式 Chrome。
  • 断网、休眠恢复需显示离线并重连；普通桌面程序不承诺休眠期间持续监听。
  • 不默认提供登录环境跨机器迁移、Cookie 导出或同步。

7. 实施顺序

以下均为待开展工作，不表示已有功能验收通过。

阶段一：账号隔离与恢复

  • 建立账号配置、归属和持久化数据目录。
  • 实现可持久化的浏览器路径与附加参数配置，默认查找官方 Chrome，校验无效路径及受管参数冲突。
  • 支持独立启动、重复启动检测、CDP 连接及 UID 校验。
  • 将现有业务脚本改为显式使用账号连接，保留独立 CLI 入口。
  • 验证 Windows 关机/重启后登录环境恢复及失效暂停。

阶段二：多大号监听与执行

  • 支持多个大号同时订阅通知。
  • 实现事件持久化、去重和可恢复任务生成。
  • 实现按归属派发、每小号串行执行和结果回查。
  • 实现 unknown 处理、断线重连和刷新后重新订阅。

阶段三：桌面 UX 与归属切换

  • 确认任务分配与切换处置规则后实现对应交互。
  • 实现账号组、未分配小号、所选组一键启动和状态展示。
  • 实现安全的归属切换、解除关联和登录数据删除确认。
  • 确保 UI 不阻塞监听调度；Qt 主线程处理界面，异步核心可运行在独立线程并通过信号通信。

阶段四：Windows 交付

  • 在 Windows 验证中文路径、目录权限、端口冲突和 Chrome 版本兼容性。
  • 验证断网、休眠、进程退出、部分账号失效和任务结果未知场景。
  • 用最小可运行测试覆盖去重、归属隔离、切换竞态及重启防重发逻辑。
  • 在 Windows 构建 PyInstaller 包，提供安装、首次登录、启动和恢复说明。

8. 验收要点

  • 多个大号可同时登录并监听，不设置产品侧推荐账号数量。
  • 每个大号的任务只进入其关联小号；大号及其它组小号不可执行。
  • 一个小号最多有一个归属，未分配小号不执行任务。
  • 切换归属保留登录环境；切换后旧组任务不能继续被新领取执行。
  • 同一小号没有并行写操作，重复事件不会重复派发同一任务。
  • 关机后可一键恢复所选环境；有效登录可复用，失效登录明确提示并暂停。
  • 身份不匹配时停止操作，不通过随意选择其它标签页继续执行。
  • 超时及重启不会造成私信盲目重发，历史任务来源可追溯。
  • 页面业务执行不依赖模拟点击；关键功能有可独立运行的 Python 入口。
  • 默认可启动官方 Chrome；配置指定可执行路径与附加参数后，启动器准确使用配置，业务代码无需更改；无效路径和隔离参数冲突明确报错。
  • 配置重启后保留，运行中不热切换内核、不静默回退；第三方内核兼容性单独验收。

9. 开发前仍需确认的业务规则

以下不能从“一个大号关联多个小号”直接推断，不在本次合并中擅自定案：

  1. 一条通知由一个小号执行，还是派发给多个关联小号？若只选一个，采用什么选择规则？
  2. 哪些通知触发关注、私信，目标如何确定，私信内容是什么，动作是否要求顺序？
  3. 是否采用第 4.2 节建议：切换时取消旧待执行任务，执行中阻止切换？
  4. 小号不可用时任务等待、取消还是允许同组改派？大号失效时已排队任务是否继续？
  5. “停止”只暂停监听/执行还是同时关闭 Chrome，以及下次启动恢复哪些账号组？

这些待确认项不影响先开发独立浏览器环境与账号归属存储，但应在实现相关执行策略前确认。

10. 空白 Windows 开发环境安装

安装 Python 3.12 与 Chrome，在 PowerShell 执行：

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install playwright
# 开发桌面界面、打包时增加：
.\.venv\Scripts\python.exe -m pip install PySide6 pyinstaller

仅 connect_over_cdp 接入系统 Chrome 时无需下载 Playwright 自带 Chromium。交付前锁定实测依赖版本。上述命令面向推荐方案，当前脚本仍依赖 browser-harness，尚未完成连接层迁移，不能据此声称现有脚本已可在空白 Windows 运行。

11. 来源与限制

合并来源：

既有调研识别了 src/subscribe_notifications.py、src/follow_user.py、src/douyin_im.py 中可复用的业务逻辑。本次只合并文档，未修改 src 或执行浏览器操作。此前官方资料抓取受网络安全检查阻断，未完成 Windows 实测，Chrome 兼容性和接口稳定性仍需验证。

关注、私信操作限于账号授权与平台规则允许的用途，避免骚扰，不使用多账号切换规避限制。初期不扩展至分布式部署、容量评估或全自动登录。

Reference in New Issue View Git Blame Copy Permalink