butubb
97cec6e211
平台此前出了问题只能靠人盯页面。现在各组件统一走 `notifier.notify(事件, **字段)`， 推到企业微信 / 自建服务；**所有可通知点都登记进事件目录，默认全关，用户按 webhook 勾选**。 ## 架构（`core/notifier.py` + `core/notify_events.py`） 业务线程调 `notify()` → 只做内存操作（读配置快照/匹配订阅/入队）→ 返回； 后台 1 个 dispatcher（聚合 + 每 hook 限流 + 折叠摘要）+ 3 个 sender（真实 HTTP、退避重试） 负责真正发出去。硬约束：**notify 零 DB、零 HTTP、零阻塞、异常不冒泡**——所以任务线程里 可以直接调（不用 app_context、不用 try/except），但**必须放在所有 `with self._lock` 之外**。 - **事件目录 36 条**（任务批次/单设备/设备/Worker/业务/安装/系统/AI），支持 `task.*` 通配订阅； 语义分工避免重复告警：`worker.*` 是单次尝试级，`task.device.success/failed` 是唯一权威结论。 - **适配器可插拔**：`wecom`（markdown，按 4096 **字节**截断、超限不截半个汉字）+ `json`（模板占位符，替换值按 JSON 转义，保存前干跑校验）；钉钉/飞书留了插槽（前端置灰）。 - **防打爆四层**：聚合窗口（默认 30s，同批次合并成一条并带样本）→ 令牌桶限流（默认 18/分， 对齐企微硬限 20）→ 被限流的**折叠成摘要不丢弃** → 有界队列背压。取舍：失败通知最多延迟 一个窗口，换来群不被刷屏。 ## 安全与存储 - 配置只落 `app_meta.notify_webhooks` 一个键（**不建表** → 不涉及备份覆盖红线）。 - URL 本身就是凭据（企微 `?key=`）→ 接口回显/发送记录/日志一律 `mask_url()/scrub()`； 编辑时留空即不修改；secret 永不回显。DATA_MODEL 的明文凭据告警补上了这一条。 - 发送记录：内存环形缓冲 200 条（重启清空）+ 独立 `logs/notify.log`。 ## 接入点（每个都放在锁外、不改 return 顺序） task_manager（批次开始/结束用新增的 `_BatchTracker` 统一在 finally 计数、单设备成功/失败/ 离线/重试/停止/抢占/归还/cron 停止）、device_worker 心跳看门狗、generic 任务选择器连续失效、 apk 安装开始/完成、设备上下线（**状态沿检测**，只报新变化）、备份导出/恢复、经验巡检、 用户登录、服务启停。 ## 前端 系统 Tab 新增「通知 / Webhook」子分栏：多条 webhook 列表（URL 打码）+ 编辑弹窗（格式/URL/ 密钥/事件勾选树带 ★建议/聚合/限流/自定义模板/预览）+ 发送测试 + 发送记录。 ## 自测 - 进程内逻辑 10 组断言全绿：聚合合并、限流+折叠、无配置/全局关静默丢弃、未知事件、 内部异常不外泄、JSON 转义（标题含引号换行仍合法）、URL/异常消息脱敏、配置校验。 - 端到端（假 webhook 接收端）17 项断言全绿：真实事件投递（user.login / task.batch.no_device）、 企微请求体形状、**HTTP 200 + errcode 93000 判为失败**、500 重试 3 次、记录里 URL 打码。 - 韧性：webhook 指向黑洞地址时登录耗时 100~114ms（基线 107~133ms，**异步隔离生效**）； 配置写成坏 JSON 服务照常启动、通知静默不发、日志有 error（服务端实测后已复原）。 - 页面：系统 → 通知 面板/弹窗/36 个事件复选框/预览全部正常，无 JS 报错。 - 自测数据已清理（webhook、自建任务、写坏又复原的配置键）。 文档：新增 doc/NOTIFY.md（事件表/配置/格式约束/防刷屏/加事件三步骤/排障）并登记进 doc/README； API.md §2.11；DATA_MODEL 的 app_meta 键表与明文凭据告警；ARCHITECTURE 线程表/分层/扩展点； 根 README 功能索引与日志表。
5.9 KiB
5.9 KiB
auto_control 文档总索引
本目录是 auto_control（Android 多设备自动化任务平台）的唯一权威文档源。代码即事实，文档与代码不一致时以代码为准，并顺手把文档改对（见文末维护约定）。
项目名称统一为 auto_control（历史文档里出现过的
platform-tools均为旧名，已全部改名）。
1. 文档地图
| 文档 | 内容 | 主要读者 |
|---|---|---|
| ARCHITECTURE.md | 架构详解：分层、启动装配顺序、线程与并发模型、设备生命周期、任务调度链路、状态机、关键设计决策与扩展点 | 所有开发者（先读这篇） |
| DATA_MODEL.md | 数据模型：SQLite 表与字段、schema 迁移、非模型表、app_meta 配置键、数据目录、备份覆盖清单 |
后端开发、运维 |
| API.md | HTTP 接口全量：按蓝图分组的路由表、鉴权、请求/响应示例、非 JSON 响应、错误分支 | 前端开发、外部接入 |
| TASK_DEV.md | 任务与步骤开发：TaskType/TaskJob 概念、18 种步骤全表、选择器与定位、自定义动作、新增任务类型模板 | 写任务的开发 |
| MCP.md | MCP 手机控制手册：20 个 de_* 工具用法、写操作门控、坐标换算、接入示例 |
接入方、数字员工 |
| MCP_DESIGN.md | MCP 设计文档：边界划分、错误码、白名单/审计设计、演进方向 | 平台开发者 |
| AI_CONSOLE.md | AI 控制台：会话/SSE、经验库、动作库、巡检、Markdown 渲染、推理链、token 统计 | 使用者、平台开发者 |
| AI_TASK_GEN.md | AI 建任务：AI 自己在真机探索 → 写出可调度任务 → 人工确认入库（P0 已实现；契约与红线） | 平台开发者、使用者 |
| NOTIFY.md | 通知 / Webhook：事件目录、企业微信/通用 JSON 适配、防刷屏（聚合/限流/折叠）、排障、怎么加事件 | 运维、平台开发者 |
| DEVICE_AGENT.md | 设备端 Agent 接口契约：应用商店的设备专用接口（清单/下载/上报）、adb 指令协议、版本约定 —— 与设备端 APK 仓库共享的契约 | 设备端开发者、平台开发者 |
| DEPLOY.md | 部署与运维：环境准备、生产容器、数据备份导出/导入、故障排查 | 运维、部署者 |
| DEVELOPMENT.md | 开发手册：git 流程、技术红线、本地开发与调试、常见开发任务、文档同步约定 | 所有开发者 |
| STF_REMOVAL.md | 历史记录：摘除 OpenSTF 的迁移过程（阶段 0-3） | 追溯背景时参考 |
| staffdeck/KNOWLEDGE_BASE.md | 给 StaffDeck 数字员工的知识库（MCP 接入/工具/约定/红线） | 外部 AI 接入方 |
| staffdeck/JOB_SPEC.md | 数字员工岗位说明（岗位描述/看板摘要/执行约束） | 外部 AI 接入方 |
| research/U2_ELEMENT_SELECTORS.md | 元素选择器研究：「点不到按钮」的根因（序号型选择器随界面变形而错位）与语义选择器解法 | 写任务/抓元素的开发 |
| backlog/TODO.md | 已确认但暂缓的待办（含已知问题） | 所有开发者 |
项目根目录的 README.md 是项目总览与快速上手（面向第一次接触项目的人），细节都在本目录。
2. 推荐的阅读路径
| 你的目的 | 按顺序读 |
|---|---|
| 第一次接触项目 | 根 README.md → ARCHITECTURE.md → DATA_MODEL.md |
| 搭环境跑起来 | 根 README.md 的「快速上手」→ DEPLOY.md |
| 写/改任务 | TASK_DEV.md → ARCHITECTURE.md §任务调度 |
| 改后端/前端 | DEVELOPMENT.md（流程+红线+本地开发）→ ARCHITECTURE.md → API.md |
| 对外提供手机控制 | MCP.md → staffdeck/KNOWLEDGE_BASE.md |
| 排故障 | DEPLOY.md §故障排查 → DEVELOPMENT.md §调试 |
3. 文档维护约定（红线）
与「doc 同步红线」一致：任何功能/配置/接口/表结构的增删改，必须在同一个 commit 里同步更新对应文档。
| 改动类型 | 必须同步的文档 |
|---|---|
| HTTP 接口（新增/改参数/改返回/改鉴权） | API.md |
| 数据库表/字段/迁移 | DATA_MODEL.md + ARCHITECTURE.md |
| 新增持久化表 | 还要登记进 core/system_backup.py 的 SUMMARY_TABLES + DEPLOY.md §3.5（备份覆盖红线） |
config.py / .env 键 |
DEVELOPMENT.md 配置速查 + DEPLOY.md + .env.example |
| 页面 Tab / 子分栏 / 前端 JS 拆分 | ARCHITECTURE.md §前端 + DEVELOPMENT.md |
| 任务类型 / 步骤 schema | TASK_DEV.md |
| 常驻线程 / 进程装配 | ARCHITECTURE.md §线程与并发 |
| MCP 工具 | MCP.md + MCP_DESIGN.md |
| 设备端 Agent（APK） | DEVICE_AGENT.md |
| 对外接入约定 | staffdeck/KNOWLEDGE_BASE.md |
| 暂缓项 / 已知问题 | backlog/TODO.md（完成时移出并同步相关文档） |
新增文档时：在本文 §1 表格里登记一行，并在根 README 的「更多文档」里加链接——否则等于没写。
历史文档不追改：STF_REMOVAL.md 是迁移阶段的历史记录，只增不改，不随现状改写。