butubb/auto_control
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(去重): 跨设备「已做过」账本 —— 同一个号不会做两次 + 「谁做过了」看得见

Browse Source 
用户场景（他原话）：一台手机登录 5 个抖音号、一共 5 台手机，每个任务只让其中一个
目标号评论；每天跑一次但不知道什么时候跑完，于是"一直重复跑" → 结果
"一个手机还没评论到，一个手机都评论两次了"。

**根因不是"单设备重复"，是跨设备没有共享的判断 + 进度不可见。** 所以做两件事：
① 幂等；② 把"谁做过了、还差谁"摆到台面上（不然只能靠重跑确认，而重跑又在制造重复）。

- `core/models.py`：新表 `done_mark`（迁移账本补 v7）。**判据只有 `scope_key` 的
  唯一索引**——多台设备会同时判断"没做过"，"先查后插"有竞态（两台都插），
  唯一索引 + `INSERT ... ON DUPLICATE KEY`/`INSERT OR IGNORE` 的**受影响行数**才原子。
- `core/dedup.py`（新）：`build_key`（`任务|身份|时间桶`）/ `check` / `mark` /
  `list_marks`（带"今天做了几台/几个号"统计）/ `delete_mark` / `clear_job` / `purge_old`。
  自建 app context（照 device_pool 的 `_ctx()`），任务线程/Web/清理都不用关心。
- 任务侧两个部件（**检查在前、记账在后**）：
  · `if_el` 新增条件类型 `selector_type="dedup"`：命中=这个身份做过了 → 走 then 分支。
    身份元素在 `ident_type`/`ident_value`（留空 = 用设备 serial，一号一机场景）。
  · 新步骤 `mark_done`「记为已做」（22 种步骤）：放动作**成功之后**。
  拆两步的用意：动作失败就不记账，下次重跑还会重试该设备 —— 失败不丢。
- 有效期（`dedup_reset` = day/all/hours）放**任务级**：检查与记账两处各填一份的话，
  填不一致就算出两个 key、去重会**静默失效**，所以强制只配一处（编辑器顶部下拉）。
- 三条防误伤规则（都有测试兜着）：
  · 身份读不到 / 身份值过长 → **不去重、当没做过照常执行**。绝不能把"读不到"
    当成空身份——那会让所有设备共用一个 key、第一台记账后其余全被误判成"做过"。
  · `kind='all'`（只做一次）的记录**永不清理**（清了等于语义失效）；清理只删 day/hours。
  · 去重的两个易错点在保存时直接告警：身份元素两边不一致、有检查没记账/有记账没检查。
- 「任务 → 去重记录」新子分栏（`static/admin/dedup.js`）：统计行 + 明细表 +
  删单条（那个号重跑）/ 清空任务（整批重跑）。接口 3 个（GET/delete/clear，PERM_TASKS）。
- 每日 04:23 清理（挂现有 APScheduler），`TABLE_LABELS` 补中文名（备份覆盖自动派生）。
- AI 建任务草稿校验同步：`dedup` 走自己的规则（要 ident_value、xpath 前缀校验），
  没填身份元素只警告不拦（用设备当身份是合法用法）；普通条件空选择器仍然拦。
- 文档：TASK_DEV §4.6（去重专章 + App 内检测的兜底配方与它的三个局限）、
  DATA_MODEL §2.9、API 三个接口、ARCHITECTURE（分层/装配/子分栏/JS 分工/清理）、
  DEPLOY §5.2（15 张表）、步骤数 21→22 全库同步。

自测：单元 + 集成 33 项（**含 8 线程抢同一个身份、恰好一个成功**的原子性断言，
以及"all 记录不被清理""身份读不到不去重""清了能重跑"）、
**真机端到端**（cs1 上"检查→动作→记账"跑两遍：第二遍被拦、换 serial 的"另一台设备"
同样被拦、删记录后能重跑）、草稿校验 5 项、GET 冒烟 56 路由 0 个 500。

（注：本分支基于 feat/if-el-multi-value，因为它俩都要改 task.py 的 STEP_TYPES 与
editor.js 的 STEP_LIB 同一区域，分开从 dev 拉必然冲突——这份是超集，合一次两份都进。）
This commit is contained in:
butubb
2026-09-24 10:55:29 +08:00
parent 5c88cc6384
commit 876224f876
21 changed files with 803 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/TASK_DEV.md
+61 -4
View File
@@ -10,7 +10,7 @@
- [1. 核心概念](#1-核心概念)
- [2. 通用步骤任务 generic_steps](#2-通用步骤任务-generic_steps)
- [3. 21 种步骤全表](#3-21-种步骤全表)（含 [3.1 步骤默认值与动作录制](#31-步骤默认值与动作录制任务--动作配置)）
- [3. 22 种步骤全表](#3-22-种步骤全表)（含 [3.1 步骤默认值与动作录制](#31-步骤默认值与动作录制任务--动作配置)）
- [4. 容器步骤与公共参数](#4-容器步骤与公共参数)（含 [4.5 公共巡检](#45-公共巡检任务级独立于步骤画布)）
- [5. 选择器与元素定位](#5-选择器与元素定位)
- [6. 自定义动作](#6-自定义动作)
@@ -97,7 +97,8 @@ from .generic import task # 触发 @register_task（当前唯一任务类型）
}
```
- **任务级参数**：`DEFAULT_PARAMS = {"max_duration": 0}`（0 = 不限时）
- **任务级参数**：`DEFAULT_PARAMS = {"max_duration": 0, "dedup_reset": "day", "dedup_hours": 6}`
（`max_duration` 0 = 不限时；`dedup_reset` 是去重有效期，见 §4.6）
- **没有默认步骤**：`steps` 只能由编辑器产出；为空时 worker 立即报错「通用步骤任务没有可执行步骤：请在「任务」页编辑该任务并添加步骤」（设备「最近错误」可见），**不会静默空跑**
- **顶层 steps 只顺序执行一次**——需要重复的动作必须显式放进 `loop` 步骤
- **每步 schema**：`{id, type, label, params}`；`id` 由前端生成保证唯一（导出为自定义动作时会剥掉 id）
@@ -108,7 +109,7 @@ from .generic import task # 触发 @register_task（当前唯一任务类型）
---
## 3. 21 种步骤全表
## 3. 22 种步骤全表
> 参数与默认值以 `tasks/generic/task.py` 为准；前端 `STEP_LIB`（`static/admin/editor.js`）负责在编辑器里呈现这些字段。
@@ -131,10 +132,11 @@ from .generic import task # 触发 @register_task（当前唯一任务类型）
| 15 | `wait` | 等待 | — | `min`(1.0)、`max`(3.0)、`vary_pace`(False) | — | 随机时长；**分片 sleep**（每 ≤0.5s 检查停止/超时），可被抢占打断；勾了 `vary_pace` 再按**本设备节奏**缩放 0.8~1.35 倍（批量跑时设备之间会逐渐错开） |
| 16 | `loop` | 循环块 | — | `loop_mode`("rounds")、`max_iterations`(10)、`loop_duration`(600) | `children` | 见 §4.1 |
| 17 | `group` | 动作组 | — | — | `children` | 子步骤**按序执行一次**（不循环）；自定义动作拖入画布就是展开成 group |
| 18 | `if_el` | 条件判断 | `selector_type`、`selector_value`、`timeout`(3) | `ocr_click`(False)、`cmp_op`("")、`cmp_value`("") | `then` / `else` | 见 §4.2；条件类型除元素/OCR 外还支持 **屏幕状态**、**前台App**；填 `cmp_op` 则改成**比元素的文本**（等于/不等于/包含/不包含） |
| 18 | `if_el` | 条件判断 | `selector_type`、`selector_value`、`timeout`(3) | `ocr_click`(False)、`cmp_op`("")、`cmp_value`("")、`ident_type`/`ident_value`（去重身份） | `then` / `else` | 见 §4.2；条件类型除元素/OCR 外还支持 **屏幕状态**、**前台App**、**去重**（见 §4.6）；填 `cmp_op` 则改成**比元素的文本**（等于/不等于/包含/不包含，多值任一命中） |
| 19 | `notify` | 发通知 | — | `title`("")、`message`("")、`level`("info") | — | 推一条**自定义**通知（事件 `task.notify.custom`）：标题正文自己写，支持 `{device} {serial} {job} {time} {app} {screen}`；谁收到取决于 webhook 的事件订阅。两者都空则跳过 |
| 20 | `stop_self` | 停止本设备 | — | `reason`("") | — | 只停**本设备**的任务（其它设备照跑）：置 worker 停止位，后续步骤不再执行，任务记成**被停止而不是失败**（不触发重试） |
| 21 | `gesture` | 录制手势 | `points`（录出来的） | `speed`(1.0) | — | **纯录制回放**：把录下的轨迹点列 `[[x,y,t_ms],…]` 按原路径与时长交给设备插值，不做弧线/抖动/手速加工。与「滑动」是两套东西，见 §3.2 |
| 22 | `mark_done` | 记为已做 | —（身份元素可选填 `selector_type`/`selector_value`） | — | — | 把身份值记进**去重账本**（跨设备共享）。放动作**成功之后**——失败不记账，下次重跑会重试。留空 = 用设备 `serial` 当身份。**配套「条件判断 → 去重」用**，见 §4.6 |
### 3.2 录制手势：**纯录制、纯回放**（`core/gesture.py`）
@@ -353,6 +355,61 @@ from .generic import task # 触发 @register_task（当前唯一任务类型）
- 巡检命中会往「日志 → 步骤明细」记一行（`step_type=patrol`，只记命中不记"没事发生"）。
- 巡检内部异常只记日志、**绝不影响任务主流程**（同 `notifier.notify` 的口径）。
### 4.6 去重：同一个号不要做两次（跨设备幂等）
**场景**（真实需求）：一台手机登录多个账号、一共好几台手机，每个任务只让**其中一个目标号**做事
（如评论）。每天跑一次，但不知道什么时候跑完 → 会反复重跑 → **同一个号被做两次、有的号还没做**。
平台为此提供一张**「已做过」账本**（表 `done_mark`，见 [DATA_MODEL.md](DATA_MODEL.md) §2.9），
**所有设备共享一份判断**：任何一台设备做过了，其余设备的检查都会命中。
| 组件 | 放哪 | 作用 |
|---|---|---|
| 条件判断，`选择器类型 = 去重` | 动作**之前** | 命中 = 这个身份在这个任务里做过了 → 走 `then` 分支 |
| 步骤「记为已做」 | 动作**成功之后** | 把身份值记进账本 |
```json
{"type": "if_el", "params": {
"selector_type": "dedup",
"ident_type": "resourceId", "ident_value": "com.ss.android.ugc.aweme:id/506",
"then": [{"type": "stop_self", "params": {"reason": "这个号今天已经评过了"}}],
"else": [
{"type": "click", "params": {"selector_type": "text", "selector_value": "发送"}},
{"type": "mark_done", "params": {"selector_type": "resourceId",
"selector_value": "com.ss.android.ugc.aweme:id/506"}}
]}}
```
**身份值**（去重的"谁"）＝ 身份元素读出来的文本（上例＝抖音号）。
留空则该步骤用**设备 `serial`** 当身份（适合"一号一机"）。
**有效期**（去重多久算"新的一轮"）在**任务级**配一次：`dedup_reset` = `day`（默认，每天一次）
/ `all`（只做一次）/ `hours`（每 `dedup_hours` 小时）。任务编辑器顶部有「去重有效期」下拉。
> ⚠ **为什么有效期和身份元素都强制"只配一处"**：检查与记账两边算的是同一个 key，
> 一边填得不一样就会算出两个 key → **去重静默失效**（最难查的那种 bug）。
> 编辑器保存时会直接告警：「身份元素不一致」「有去重检查但没有记为已做」等。
**四条必须知道的语义**：
| 情况 | 行为 | 为什么 |
|---|---|---|
| 身份元素**读不到值** | **不去重**，当"没做过"照常执行（日志告警） | 读不到若当成空身份，所有设备会共用一个 key，第一台记账后其余全被误跳过——宁可重复一次，也不能漏做 |
| 身份值**过长** | 同上，不去重 | 截断会让两个身份撞成同一个 key（同样是误跳过） |
| 「记为已做」放在动作失败路径上 | **不会执行** | 拆成"检查在前、记账在后"就是为了**失败不记账、下次重试** |
| `dedup_reset='all'` | 记录**永不被清理** | 清了就等于"只做一次"失效（清理任务只删 `day`/`hours` 桶） |
**看进度 / 让它重跑**：「任务 → 去重记录」页能看到"谁做过了、今天做了几个号"，
可以删单条（那个号/那台设备重跑）或清空整个任务。**这一页的价值就是让你不必靠"一直重跑"来确认。**
**第二种办法（兜底，不用账本）**：进 App 的评论区后用
**条件判断 + 文本比对（包含）**，候选值填本账号的评论标识（昵称/「我」标签），命中就跳过。
它的局限要说清楚，别指望它万能：
- 依赖 App 的评论区结构，**改版就失效**
- 自己的评论常常要**滑动加载**才出现在元素树里（可能要滑几次、慢）
- 多台设备并发时可能**同时**判"没评过"（没有原子性）——所以**账本才是主拦**，这个只做兜底
---
## 5. 选择器与元素定位