auto_control/doc/NOTIFY.md

通知 / Webhook（NOTIFY）

面向：要给平台接告警的运维、以及往各组件加通知点的开发。 相关：API.md（接口）、DATA_MODEL.md（配置存哪）、 ARCHITECTURE.md（线程模型）。

---

1. 它是什么

平台各组件（任务、设备、安装、备份、AI 巡检…）在关键时刻调一个统一入口：

from core import notifier
notifier.notify("task.device.failed", serial="192.168.20.71:5555",
                device_name="A02", job_name="抖音养号", cause="选择器连续 10 次未命中")

notify() 只做内存操作（读配置快照 → 匹配订阅 → 丢进队列），真正发 HTTP 的是后台 daemon 线程。所以：

• 任务线程里可以直接调，不用包 app_context、不用 try/except（内部全兜住了）
• 但必须放在所有 with self._lock 之外——别让通知拖住调度锁
• 通知模块自己出问题（地址写错、对方挂了、配置坏了）绝不影响任务/设备/备份， 最多在日志里留一条警告

业务线程 notify() ──入队──▶ dispatcher（1 线程）──▶ sender ×3 ──▶ 企业微信/自建服务
                                ① 聚合  ② 限流  ③ 折叠
                                         └─▶ 发送记录（内存 200 条 + logs/notify.log）

---

2. 快速上手（企业微信）

1. 企业微信群里 → 群机器人 → 添加 → 复制 Webhook 地址（形如 https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxx）
2. 后台 → 系统 → 通知 / Webhook → ＋ 新建 Webhook：名称随便起、格式选「企业微信」、 粘贴地址、在事件树里勾上关心的事件（★ 是建议开的）
3. 点该行的 发送测试 —— 群里立刻能收到一条 markdown；收不到就看返回的 HTTP/errcode

---

3. 事件目录

权威定义在 core/notify_events.py（后台「通知」页也是从它渲染的，不会漂移）。 所有事件默认不启用——登记不等于推送，勾了才发。

类别	事件
任务批次	task.batch.started · .finished · .no_device · .unknown_type · task.cron.stopped
任务·单设备	task.device.success · .failed · .offline · .error · .retry · .stopped · .preempted · .preempt_timeout · .released
业务	task.selector.invalid（选择器连续 10 次未命中——"任务成功但什么都没做"的隐蔽故障）
业务	task.video.published（视频发布成功，带作品分享链接）/ task.video.failed（发布失败或结果未知——结果未知意味着可能已经发出去了，要到计划页人工确认，平台不会自动重发）
业务·任务自己发	task.notify.custom（步骤「发通知」）/ task.patrol.hit（任务「公共巡检」命中）——标题正文由任务自己写，见下
Worker	worker.connected · .attempt.done · .attempt.error（单次尝试级，噪音大，默认没人勾）
设备	device.online · .offline · .discovered · .claimed · device.heartbeat_timeout · device.battery.low · .battery.recovered
安装	apk.install.started · .finished
系统	system.backup.exported · .imported · .restored · .restore_failed · service.started · .stopping · user.login
AI	ai.audit.finished · .failed · .skipped
其它	notify.test（测试按钮专用）

订阅支持通配：*（全部）、task.*、device.*。

语义分工（避免重复告警）：worker.* 是单次尝试层面；task.device.success/failed 是"这台设备最终成功/失败"的唯一权威点。所以一个设备重试 3 次后失败，只会收到 1 条 task.device.failed，不会收到 3 条噪音。

多设备批次怎么发（设备一多，逐台发就等于刷屏）：

事件	多设备批次（>1 台）	单台任务
task.batch.started	发 1 条（N 台）	发
task.device.success	不发（批次汇总里已有成功台数）	发
task.device.failed / .offline	逐台发（失败是少数，且要知道是哪台）	发
task.batch.finished	发 1 条汇总	发

批次汇总长这样（有失败时才会多出一行「失败设备」，列出名字（型号）：原因，最多 5 条）：

### ✅ 任务批次结束：抖音养号
> **任务ID**：b370bbbc
> **总数**：13
> **成功**：13
> **失败**：0
> **停止**：0
> **跳过**：0
> **耗时(秒)**：1347
> **时间**：2026-09-16 09:22:57

单设备事件里的设备一律显示名字（cs1）而不是地址；只有设备没命名时才退回 IP。 型号 取自设备池的快照（后台统一采集的那份），比 worker 每次连接时现采的稳。

任务自己发的通知（两种，文案都由任务侧提供）：

事件	谁发	文案从哪来
task.notify.custom	步骤「发通知」	步骤参数 title / message
task.patrol.hit	任务「公共巡检」命中	巡检项 title / message（留空则用默认：巡检命中：<巡检名> + 检查结果）

• 两者都支持占位符 {device} {serial} {job} {time} {app} {screen} （见 TASK_DEV.md §4.5；{app}/{screen} 要查设备，不用就别写）。
• 给了 title 就用它做消息标题（不再拼"任务通知：" 前缀），level 字段可点名级别 （info/success/warning/error → 决定 emoji，默认按事件名猜）。
• 谁能收到仍然只看 webhook 的事件订阅：想让某个群收任务自定义消息，就在那条 webhook 上勾 task.notify.custom / task.patrol.hit。

3.1 设备电量告警（device.battery.low / .battery.recovered）

采集与判定都在 core/device_battery.py（后台线程 device-battery，默认 60s 一轮， adb -s <serial> shell dumpsys battery 只读查询）。阈值配置在 「工具 → 设备发现 → 电量监控」，存在 app_meta.device_battery（见 DATA_MODEL.md §5）。

阈值语义（这是唯一判定处，前端只读后端算好的 tier 上色）：

档位	条件	通知
0 正常	电量 >= 低电量阈值 + 5（迟滞）或 充电中	从低/严重回到 0 → 发 device.battery.recovered
1 低	严重阈值 < 电量 <= 低电量阈值	掉到这一档才发 device.battery.low（warning）
2 严重	电量 <= 严重阈值	掉到这一档再发一次（error），阈值字段是严重阈值

• 迟滞 +5：回升要到 低电量阈值 + 5 才算恢复。没有它，电量在阈值上下浮动 （充电器接触不良）会反复告警。
• "充电中"看的是 status: 行（2 充电中 / 5 已充满），不是"插着电"。 所以**"插着却没充电"**（劣质线、温控停充、满电停充 status:4）仍然会告警—— 那正是最该让人知道的情况。想连充电中一起报，把「充电中不告警」勾掉即可。
• 重复提醒：同一档位持续不恢复时，每 6 小时再提醒一次（core/device_battery.RE_NOTIFY_S）。
• 只对**「设备池 ∩ 在线」**的设备告警：adb 里能看到但不归平台管的设备不吵人。
• 一周内改了阈值不用重启：采集线程每轮重读配置，档位下一轮就按新阈值算。

排查：logs/core.log 搜 core.battery（每轮一行「电量采集完成: N/M 台」）。

---

4. 配置

存在 app_meta.notify_webhooks 一个键里（JSON，不建表，因此不涉及备份覆盖清单）：

{
  "version": 1,
  "settings": {"global_enabled": true, "default_agg_window": 30,
               "default_rate_limit": 18, "log_keep": 200, "http_timeout": 5},
  "webhooks": [
    {"id": "wh_ab12cd34", "name": "运维群", "enabled": true, "format": "wecom",
     "url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=…",
     "secret": "", "events": ["task.device.failed", "device.*"],
     "agg_window": 30, "rate_limit_per_min": 18,
     "title_template": "", "body_template": "", "headers": {}}
  ]
}

上限（超了拒绝保存，不静默截断）：webhook ≤ 20 条、整体 JSON ≤ 60000 字符、URL ≤ 2048。

安全：URL 里带凭据（企微 ?key=、钉钉 ?access_token=、飞书 /hook/<token>、 Bark /…/<key>、Slack /services/T…/B…/X…）→ 接口回显、发送记录、日志一律打码 （mask_url 同时处理 query 与路径里的 token；异常消息过 scrub）； 编辑时留空即不修改；secret 永不回显（只回"已配置"）。

---

5. 推送格式

格式	请求体	URL 怎么填	成功判定 / 关键约束
wecom 企业微信	{"msgtype":"markdown","markdown":{"content":"…"}}	群机器人 → 复制的 Webhook 地址（含 ?key=）	errcode==0；content ≤4096 字节（按字节截断、不会截出半个汉字）；每机器人每分钟 20 条，超限 45009
dingtalk 钉钉	{"msgtype":"markdown","markdown":{"title","text"}}	群设置 → 智能群助手 → 添加机器人 → 自定义 → 复制的 Webhook 地址（含 ?access_token=）	errcode==0；正文 ≤20000 字节；官方 20 条/分，超限会被限流 10 分钟（这里默认 15 留余量）；机器人安全设置选「加签」时密钥必填
feishu 飞书	{"msg_type":"interactive","card":{header + markdown 元素[,"timestamp","sign"]}}	群设置 → 群机器人 → 添加 → 自定义机器人 → 复制的 Webhook 地址（…/bot/v2/hook/<token>）	code==0；请求体 ≤20KB；官方 100 条/分（这里默认 60）；开了「签名校验」时密钥必填
bark iOS 推送	{"title","body","markdown","group","level"[,"device_key"]}	Bark App 里复制的那串（https://api.day.app/<key>）或 https://api.day.app/push + 设备 Key 填到「设备 Key」	code==200（注意和企业微信不一样！）；走 APNs，正文按 2048 字节截断；markdown 传富文本、body 传纯文本兜底
json 通用 / Slack	由 body_template 决定	你自己的接收端；Slack 填它的 Incoming Webhook URL	HTTP 200（响应体里有 code/errcode 时必须为 0）；模板保存前干跑校验；secret 会作为 X-Webhook-Secret 头发出

成功码按格式判定（企微/钉钉/飞书 = 0，Bark = 200），写在适配器的 ok_codes 上—— 加新格式时别忘了一起定。

加签：钉钉和飞书算法不一样，别互相照抄

	钉钉	飞书
key（HMAC 的密钥）	secret	"{timestamp}\n{secret}"
message（被签内容）	"{timestamp}\n{secret}"	空
timestamp 单位	毫秒	秒
拼在哪	URL query（&timestamp=…&sign=…）	JSON body 的 timestamp/sign
结果编码	Base64 后再 urlencode	Base64
出错码	errcode 310000 invalid signature	code 19021 sign match fail

实现见 core/notifier.py 的 DingtalkAdapter.sign_request / FeishuAdapter.sign_request； 两家的算法都用官方示例代码对拍过（钉钉逐字节一致，含 urlencode）。

字段一律渲染成 > **字段**：值 引用行，不用 Markdown 表格——企业微信/钉钉的 markdown 子集不支持表格，表格会原样吐出来。

通用 JSON 的占位符：{{event}} {{title}} {{summary}} {{ts}} {{level}} {{markdown}} {{fields}} {{fields_json}} {{hook_name}} {{field.<字段名>}}。 替换值按 JSON 字符串转义，所以标题里带引号/换行也不会打坏请求体。Slack 直接写 {"text":"{{markdown}}"} 就行。

格式相关的提示文案（URL 示例/说明、密钥叫什么、限流上限）都挂在适配器上 （BaseAdapter.url_hint/url_help/secret_label/secret_help/limit_help），界面按当前格式渲染、 切格式即时更新——新增格式时把这些一起填上，别把某个平台的说明写死在页面上。

再加新格式：写一个 BaseAdapter 子类（render + 可选 sign_request）并把元信息 （byte_limit/ok_codes/limit_default/url_hint/url_help/secret_*/limit_help）填全， 然后注册进 ADAPTERS —— 界面上的下拉项与提示文案会自动跟着出来，不用改前端。 PLANNED_FORMATS 是"还没实现、下拉里置灰"的占位表（目前为空）。

---

6. 防打爆（四层）

100 台设备同时失败 = 100 条消息，群里会被刷到静音——刷屏会让通知彻底失效。所以：

层	机制	默认
L1 聚合	同 webhook、同事件、同聚合键（如 job_id）在一个窗口内合并成一条，保留前 3 个样本	30s（事件声明 agg_window=0 的一律立即发，如批次结束 / 服务启停 / 备份恢复）
L2 限流	每 webhook 一个令牌桶	18 条/分（企业微信硬限 20，留余量）
L3 折叠	被限流的事件不丢弃，压成一条「被限流折叠 N 条」摘要	最多 60s 一条
L4 背压	有界队列（event 2000 / send 1000），满了丢弃并计数	溢出会告警一次

取舍写明白：失败通知最多延迟一个聚合窗口（默认 30s），换来群不被刷屏。

窗口口径（代码在 core/notifier.py 的 notify()）：

• 事件自己写了 agg_window=0 → 立即发，不受 webhook 的窗口影响；
• 其余事件 → 用该 webhook 配置的 agg_window（它表示"这个群最多等多久合并"）。

「样本」行只在真的合并了多条（>1）时出现，且按设备维度写（cs1 · 超时）—— 合并多台设备时写任务名每条都一样，等于没写。

⚠️ 保存通知配置（save_config）会清空待发聚合与限流令牌桶。清理 hook 时 顺手丢掉的正是还没到窗口的聚合事件——排障时别把它当成"没发"。

---

7. 开发：给新功能加通知

1. 在 core/notify_events.py 的 EVENTS 里加一条 _e("模块.对象.动作", "中文标签", "分类", ["字段1", "字段2"], "什么时候发", agg_window=…, recommend=…)
2. 在触发点调 notifier.notify("模块.对象.动作", 字段1=…, 字段2=…) —— 放在所有 with self._lock 之外，且不要改变原有 return 的顺序
3. 把事件补进本文档 §3 的表格

约定：

• notify() 不阻塞、不抛异常、不碰 DB——这是硬约束，别在它里面加 HTTP 或查库
• 事件的 fields 是前端字段表与模板占位符的白名单，只写真正有用的
• 高频事件（每台设备/每次尝试都会发生的）把 agg_window 设大一点或 recommend=False

设备一律只传 serial，名字自动补（不用每个调用点自己去查名字）：

群消息里没人想看 192.168.20.110:5555，要看「A09」。这件事在通知链路里 统一做掉，调用点照旧只传 serial 就行：

环节	做什么
core/device_pool.py	维护一份 serial → 名称 的内存快照：启动刷一次、池子增删改名/迁址时刷一次、每 60s 兜底刷一次（覆盖整库恢复这类进程外改动）
web_server.py	notifier.set_device_name_resolver(device_pool.name_of) 把快照接给通知
core/notifier.py	fill_device_names() 在 notify() 与 build_message() 里把 serial 补成 device_name、把 serials/devices 列表逐项换成名字

为什么绕这一圈：notify() 的红线是零 DB，不能为了取个名字去查库（那等于在业务 线程里加一次阻塞查询）。所以名字由 device_pool 预先算好放内存，notifier 只读。

降级规则（绝不把内容弄丢）：调用点自己传了 device_name 就用它的；查不到名字 （设备没命名 / 已不在池里）就保留原来的地址。解析器缺失或抛异常都只是降级，不影响发送。

---

8. 排障

现象	看哪里
完全没收到	① 全局开关是不是关了（列表页「启用通知」）② 该 webhook 是否启用 ③ 事件勾了没（task.device.failed 是单设备最终失败，不是每次尝试）
收到但内容不全	消息被 4096 字节截断了（末尾有「…(已截断)」）；把 cause 之类长字段在事件侧截短
只在群里看到「被限流折叠」	短时间内同类事件太多，触发了 L2/L3；调大该 webhook 的限流值（企微上限 20）或调大聚合窗口
失败原因	后台「通知」页的发送记录（内存，重启清空）或 logs/notify.log（完整历史）。errcode 45009=企微限流、93000=Webhook 地址无效、HTTP 200 + errcode≠0 也算失败
配置坏了	服务照常启动（启动日志有 error），通知静默不发；在后台删掉坏配置或直接改 app_meta.notify_webhooks

---

9. 已知限制

• 发送记录在内存（最近 200 条，重启清空）；持久历史只有 logs/notify.log 文本
• 不支持自定义 webhook 请求头（headers 字段留着但界面没暴露）——需要的话说一声
• 只做 http/https，不做内网 IP 黑名单（内网自建 webhook 是合法用法），但禁止重定向 （allow_redirects=False）
• system.backup.restored 是重启后才发（恢复本身就是重启生效的）