butubb/auto_control
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c29516cff57563c016e3e71e20042a7b8791d476
auto_control/doc/README.md
T
butubb c29516cff5 feat(任务): 任务级「公共巡检」——独立于步骤画布的守护条件（含 webhook 通知） 
需求：任务编辑器里能单独配"这个任务每隔 N 秒检查一次"——熄屏就点亮、某个元素
出现就通知、掉出 App 就停本设备；通知标题正文要能自己写。

配置与执行分离（这是本次的关键设计）：
- **配置是任务级的**（`params.watchers`），在任务编辑器单独一块，不进步骤画布；
- **执行是穿插的**：worker 每执行完一步、以及长等待的每个分片，看一眼哪个巡检
  到点了。不起线程 → 不需要并发模型，也不会和主流程抢屏幕（两边同时点屏幕会
  互相打断）。代价是精度受步长影响（某步卡 30s，巡检最多晚 30s），已在文档写明。

- core/patrol.py（新）：检查项/动作注册表（CHECKS/ACTIONS）+ evaluate/act。
  检查：屏幕熄灭/亮着、元素存在/不存在、前台是/不是某 App；
  动作：只通知、点亮、息屏、停止本设备。屏幕走 `dumpsys power`（0.3s，
  不用 d.info——那玩意在部分设备要 14s），前台走 d.app_current()（0.7s）。
- tasks/generic/task.py：`_maybe_patrol` / `_run_patrol`（冷却、命中记一条
  步骤明细、发通知）；**文案在动作之前渲染**——点亮后 {screen} 就成了"亮屏"，
  用户要看的是"发现熄屏，已点亮"。
- 任务编辑器新增「公共巡检」块（static/admin/tasks.js）+ 样式；保存进 params.watchers。
- 通知：新增事件 `task.patrol.hit`（巡检命中）与 `task.notify.custom`（步骤发通知）；
  给了 title 就用它当标题（不再拼前缀），level 字段可点名级别。

顺带（巡检需要的原语，也可单独用）：
- if_el 条件判断支持 `selector_type=screen`（亮/熄）与 `foreground`（前台包名）；
  非元素条件不参与「选择器健康」统计（否则会攒出假的"选择器失效"告警）。
- 新增两个步骤：`notify`（发自定义通知）、`stop_self`（停本设备，记"被停止"
  而不是失败，不触发重试）。步骤类型 18 → 20，相关文档计数一并更新。

修 bug：`wait` 步骤在巡检耗时超过剩余时间后 `sleep(负数)` 抛
"sleep length must be non-negative"（真机联调抓到，已 clamp 到 0）。

自测：假设备单测 12 组（命中/冷却/间隔/元素/前台/停止/静默/异常不炸）；
真机联调：熄屏→点亮（False→True）+ 通知文案正确、掉出抖音按间隔命中 5 次、
长等待里穿插生效且步骤回到 ok、清理后用户通知配置原样恢复。
文档：TASK_DEV §4.5（含两个可抄的例子）与步骤表/条件类型、NOTIFY §3、README。
2026-09-16 13:02:40 +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 概念、20 种步骤全表、公共巡检、选择器与定位、自定义动作、新增任务类型模板 | 写任务的开发 |
| [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