douyin-pc/AGENTS.md

项目开发与操作约束

这是一个抖音PC页面相关数据监听和操作的项目。不考虑工程化，当前阶段快速实现初期功能的开发 我已经在浏览器登录了账号，且CDP 可以访问 localhost:9222 直接操作定位 如果登录状态丢失不要自己尝试登录，而是停止任务让我来登录账号。

工作方式

• 详细保存相关调研日志和最终方案到docs目录下，文件名格式 YYYY-MM-DD-HH-II-<topic>.md
• 要求相关操作可复用，不绑定环境、账号等其它因素，如需要在空白环境安装相关包，给出安装说明书
• 页面操作只用于触发相关请求调研,不作为下述产出目标方案

产出目标

• 在src中输出自动化处理的python脚本，要求每个功能的脚本可独立运行
• 能用的功能、函数可使用公共包来实现，不需要独立实现

多账号实现与验收约束

• 后续 UI、生命周期和任务安全设计以 docs/plan01.md 为准；评审合并记录见 docs/2026-09-08-16-02-plan01-review-integration.md；其中人工核定相关建议已由 docs/2026-09-08-16-40-unknown-readonly.md 撤回。文档中的新约束是待实现/待验收目标，不得据此宣称功能完成；不一致的早期计划只作追溯。
• 必须在任何 worker 启动前完成数据库迁移和中断恢复：遗留 running 转 unknown；恢复上次选择不启动业务。大号本次身份及监听能力就绪后，所属小号才可领取；停止后的迟到回调不得重新放行。
• 停止优先关闭调度/领取入口，不得排在历史/作品同步或登录等待之后；按方案的有限总预算收尾，重复停止幂等。不确定的在途结果保持 unknown，不把取消本地等待当作远端回滚。
• 任务不可跨组；单通知只分配一个小号，同一小号串行处理通知批次，批内关注/私信独立并行、分别保存结果。动作快照不改写，但规则总开关及当前安全限制必须在领取/发送前重查；旧 pending 恢复需可见确认，取消仅作用于确认时仍为 pending 的任务。
• unknown 仅为结果不确定的只读记录，按持久化 task ID 在已删除/已转移账号之外仍可查询；不提供人工核定、成功/失败结论提交或人工改状态操作，不要求用户核实结果。移除人工操作不解除已有去重/占用保护，不自动判定、重发、重置 pending 或改派。软删除后同 UID 只能显式恢复原身份记录，不清空 UID、去重、冷却或原任务来源来绕过限制。
• 领取状态未成功落库不得发送关注/私信；动作后的结果落库失败必须停止继续领取，不自动重放。普通文件日志可以降级，SQLite 任务账本失败不得忽略，也不得为清日志删除任务安全记录。
• 删除登录目录/小号前必须停止收尾、确认范围并持久化删除意图；只清理属于该账号的受管路径，禁止符号链接/junction 越界。目录与数据库部分成功时保留禁止启动状态，仅显式重试，不自动登录或恢复规则。
• 实时缓存非空不等于完成历史全量；同步基线、游标和完整标记必须与数据落库一致，失败/截断不得称为全部。历史入队须二次确认且校验规则/作品配置基线；相同通知由数据库去重。
• 异步 UI 回包按 account ID/request ID 隔离，选中项、启动勾选和未保存草稿分开；状态刷新不覆盖草稿，列表先按账号/原组过滤再分页。旧任务缺失的时间显示未知，不伪造阶段时间。
• 实现变更先用现有测试、临时 SQLite、假 session/执行器覆盖启停竞态、分页、迁移、unknown 只读查询和存储故障；验收矩阵见 docs/plan01.md。不以真实关注、私信或标记已读作为回归测试，不新增无必要的调度/状态机框架。

Windows 远程部署与连接

• 优先使用项目级 .pi/mcp.json 中的 windows-ui MCP 操作 Windows 主机；该连接用于启动、停止、查看和人工验收 Windows 应用。
• Windows MCP 不满足需求或批量命令明显不便时，改用 SSH 执行文件传输、构建、安装和日志检查；连接地址、账号和密钥只从本机 SSH 配置读取，不写入代码、安装包或文档。
• Windows 原生构建必须在 Windows x64 主机执行 build_windows.py，不要把 Linux 构建产物伪装成 Windows 安装包。
• 部署顺序：先在本地完成测试，再将源码或构建产物传到 Windows；执行构建/安装后通过 Windows MCP 做 GUI 冒烟和人工验收。
• 远程操作前先确认目标程序当前状态；不要自动登录、恢复业务规则或执行真实关注/私信等写操作。登录状态丢失时停止并交给用户登录。
• 远程部署记录写入 docs/YYYY-MM-DD-HH-II-<topic>.md，记录连接方式、执行命令、产物路径和验证结果，但不记录密码、Cookie、UID 或登录目录内容。