butubb/auto_control
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e82fd64695db67dafa1f7ff630f284025e4e0a94
auto_control/doc/README.md
T
butubb 876224f876 feat(去重): 跨设备「已做过」账本 —— 同一个号不会做两次 + 「谁做过了」看得见 
用户场景（他原话）：一台手机登录 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 拉必然冲突——这份是超集，合一次两份都进。）
2026-09-24 10:55:29 +08:00

69 lines
5.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# auto_control 文档总索引
本目录是 `auto_control`（Android 多设备自动化任务平台）的**唯一权威文档源**。代码即事实，文档与代码不一致时以代码为准，并**顺手把文档改对**（见文末维护约定）。
> 项目名称统一为 **auto_control**（历史文档里出现过的 `platform-tools` 均为旧名，已全部改名）。
---
## 1. 文档地图
| 文档 | 内容 | 主要读者 |
|------|------|---------|
| [ARCHITECTURE.md](ARCHITECTURE.md) | **架构详解**：分层、启动装配顺序、线程与并发模型、设备生命周期、任务调度链路、状态机、关键设计决策与扩展点 | 所有开发者（先读这篇） |
| [DATA_MODEL.md](DATA_MODEL.md) | **数据模型**：SQLite 表与字段、schema 迁移、非模型表、`app_meta` 配置键、数据目录、备份覆盖清单 | 后端开发、运维 |
| [API.md](API.md) | **HTTP 接口全量**：按蓝图分组的路由表、鉴权、请求/响应示例、非 JSON 响应、错误分支 | 前端开发、外部接入 |
| [TASK_DEV.md](TASK_DEV.md) | **任务与步骤开发**：TaskType/TaskJob 概念、22 种步骤全表、公共巡检、选择器与定位、自定义动作、新增任务类型模板 | 写任务的开发 |
| [MCP.md](MCP.md) | **MCP 手机控制手册**：20 个 `de_*` 工具用法、写操作门控、坐标换算、接入示例 | 接入方、数字员工 |
| [MCP_DESIGN.md](MCP_DESIGN.md) | **MCP 设计文档**：边界划分、错误码、白名单/审计设计、演进方向 | 平台开发者 |
| [AI_CONSOLE.md](AI_CONSOLE.md) | **AI 控制台**：会话/SSE、经验库、动作库、巡检、Markdown 渲染、推理链、token 统计 | 使用者、平台开发者 |
| [AI_TASK_GEN.md](AI_TASK_GEN.md) | **AI 建任务**：AI 自己在真机探索 → 写出可调度任务 → 人工确认入库（P0 已实现；契约与红线） | 平台开发者、使用者 |
| [NOTIFY.md](NOTIFY.md) | **通知 / Webhook**：事件目录、企业微信/通用 JSON 适配、防刷屏（聚合/限流/折叠）、排障、怎么加事件 | 运维、平台开发者 |
| [DEVICE_AGENT.md](DEVICE_AGENT.md) | **设备端 Agent 接口契约**：应用商店的设备专用接口（清单/下载/上报）、adb 指令协议、版本约定 —— 与设备端 APK 仓库共享的契约 | 设备端开发者、平台开发者 |
| [DEPLOY.md](DEPLOY.md) | **部署与运维**：环境准备、生产容器、数据备份导出/导入、故障排查 | 运维、部署者 |
| [DEVELOPMENT.md](DEVELOPMENT.md) | **开发手册**：git 流程、技术红线、本地开发与调试、常见开发任务、文档同步约定 | 所有开发者 |
| [STF_REMOVAL.md](STF_REMOVAL.md) | **历史记录**：摘除 OpenSTF 的迁移过程（阶段 0-3） | 追溯背景时参考 |
| [staffdeck/KNOWLEDGE_BASE.md](staffdeck/KNOWLEDGE_BASE.md) | 给 StaffDeck 数字员工的知识库（MCP 接入/工具/约定/红线） | 外部 AI 接入方 |
| [staffdeck/JOB_SPEC.md](staffdeck/JOB_SPEC.md) | 数字员工岗位说明（岗位描述/看板摘要/执行约束） | 外部 AI 接入方 |
| [research/U2_ELEMENT_SELECTORS.md](research/U2_ELEMENT_SELECTORS.md) | **元素选择器研究**：「点不到按钮」的根因（序号型选择器随界面变形而错位）与语义选择器解法 | 写任务/抓元素的开发 |
| [backlog/TODO.md](backlog/TODO.md) | 已确认但暂缓的待办（含已知问题） | 所有开发者 |
项目根目录的 [README.md](../README.md) 是**项目总览与快速上手**（面向第一次接触项目的人），细节都在本目录。
---
## 2. 推荐的阅读路径
| 你的目的 | 按顺序读 |
|---------|---------|
| **第一次接触项目** | 根 [README.md](../README.md) → [ARCHITECTURE.md](ARCHITECTURE.md) → [DATA_MODEL.md](DATA_MODEL.md) |
| **搭环境跑起来** | 根 [README.md](../README.md) 的「快速上手」→ [DEPLOY.md](DEPLOY.md) |
| **写/改任务** | [TASK_DEV.md](TASK_DEV.md) → [ARCHITECTURE.md](ARCHITECTURE.md) §任务调度 |
| **改后端/前端** | [DEVELOPMENT.md](DEVELOPMENT.md)（流程+红线+本地开发）→ [ARCHITECTURE.md](ARCHITECTURE.md) → [API.md](API.md) |
| **对外提供手机控制** | [MCP.md](MCP.md) → [staffdeck/KNOWLEDGE_BASE.md](staffdeck/KNOWLEDGE_BASE.md) |
| **排故障** | [DEPLOY.md](DEPLOY.md) §故障排查 → [DEVELOPMENT.md](DEVELOPMENT.md) §调试 |
---
## 3. 文档维护约定（红线）
> 与「doc 同步红线」一致：**任何功能/配置/接口/表结构的增删改，必须在同一个 commit 里同步更新对应文档。**
| 改动类型 | 必须同步的文档 |
|---------|--------------|
| HTTP 接口（新增/改参数/改返回/改鉴权） | [API.md](API.md) |
| 数据库表/字段/迁移 | [DATA_MODEL.md](DATA_MODEL.md) + [ARCHITECTURE.md](ARCHITECTURE.md) |
| **新增持久化表** | 还要登记进 `core/system_backup.py` 的 `SUMMARY_TABLES` + [DEPLOY.md](DEPLOY.md) §3.5（**备份覆盖红线**） |
| `config.py` / `.env` 键 | [DEVELOPMENT.md](DEVELOPMENT.md) 配置速查 + [DEPLOY.md](DEPLOY.md) + `.env.example` |
| 页面 Tab / 子分栏 / 前端 JS 拆分 | [ARCHITECTURE.md](ARCHITECTURE.md) §前端 + [DEVELOPMENT.md](DEVELOPMENT.md) |
| 任务类型 / 步骤 schema | [TASK_DEV.md](TASK_DEV.md) |
| 常驻线程 / 进程装配 | [ARCHITECTURE.md](ARCHITECTURE.md) §线程与并发 |
| MCP 工具 | [MCP.md](MCP.md) + [MCP_DESIGN.md](MCP_DESIGN.md) |
| 设备端 Agent（APK） | [DEVICE_AGENT.md](DEVICE_AGENT.md) |
| 对外接入约定 | [staffdeck/KNOWLEDGE_BASE.md](staffdeck/KNOWLEDGE_BASE.md) |
| 暂缓项 / 已知问题 | [backlog/TODO.md](backlog/TODO.md)（完成时移出并同步相关文档） |
**新增文档时**：在本文 §1 表格里登记一行，并在根 README 的「更多文档」里加链接——否则等于没写。
**历史文档不追改**：[STF_REMOVAL.md](STF_REMOVAL.md) 是迁移阶段的历史记录，只增不改，不随现状改写。
Reference in New Issue View Git Blame Copy Permalink