feat(大屏): 顶部加「📤 发布」按钮 —— 选设备直接注入视频/图片、注入剪贴板

用户要求："大屏按钮右边加一个按钮叫发布，就是选择设备号注入视频或者图片，位置就和发布页面的一样，
然后还有在选择设备号注入剪贴板"。

大屏（`/wall`）顶栏「一键亮屏」右边加 **「📤 发布」**，点开是一块面板：
  · **设备**下拉（设备名 + 地址，离线会标注；每次打开现取最新列表）
  · **视频 / 图片**：选文件 → 「注入素材」→ 推到该机相册 `/sdcard/DCIM/Camera`
  · **剪贴板文字**：填一段 → 「注入剪贴板」→ 写进该机剪贴板（发文案用）
  · 面板下方是操作日志（✅/❌ + 原因），失败会写清为什么

后端（`web/tools_api.py`，都按 **设备位** 放行 —— 大屏上随手一推是设备操作，不该要管理员位）：
  · `POST /api/tools/push_material`（form-data：file + serial）：
    保存上传 → `publish_flow.push_video` 推到相册（文件名带 `wall` 前缀、mtime 改成现在，
    保证它在相册里排最前）→ `verify_pushed` 校验进没进相册索引 → 返回 `{ok,msg,remote,verify}`
    · **不占位、不写库**：与「发布计划 → 推送」是两回事（那条按计划走占位/去重/回写状态）；
      这条是"手上有一段素材，想马上在这台机器上发"
    · 扩展名按 `video_plan.MEDIA_EXTS` 校验（视频+图片），不在其中 → 400；设备不在线 → 400
    · 临时目录用完即删（`finally` 里 rmtree）
  · `POST /api/tools/push_clipboard`：与 `/api/tools/clipboard/set` **同一个实现**
    （`_set_device_clipboard`），只是权限位不同

真机验过（A01）：剪贴板注入 ✅；1×1 测试图推到相册 ✅（`verify=no_index` 的 ⚠ 是这张图太小、
媒体库没索引它，真视频/图片是 ✅）；`.txt` 被 400 拦住 ✅；测试文件已从手机删掉、不留痕。

文档：doc/API.md 加两条接口（含请求/返回/错误口径）、README 实时看屏那行补上发布面板。

.env.example

@@ -108,6 +108,35 @@ TAILSCALE_API_KEY=请填写Tailscale_API_key
 # 设置后不启动 cron 调度器（跑测试脚本时避免真实触发任务、占用设备）
 # DISABLE_SCHEDULER=1
 
+# 视频发布计划的素材目录（默认 data/videos）。
+# **自动化测试必须指到临时目录**，否则测试传的视频会落进用户真实数据目录。
+# DATA_VIDEO_DIR=/tmp/videos_test
+
+# 单次上传体积上限（MB，默认 2048）。
+# ⚠ 必须大于「应用管理」里最大的 APK（实测有 336MB 的包），否则 APK 上传会被一起卡死。
+# MAX_UPLOAD_MB=2048
+
+# ==================== 发布计划：抖音「我」页面上的控件（抓一次填这里） ====================
+# 发布任务按**名字**发（名字 = 抖音昵称），所以平台要知道"名字在屏幕上哪个控件里"。
+# 用「抓取元素」抓一次抖音「我」页面上的**昵称**（那个 TextView），填到下面。
+# 一处配置、三处一致：任务骨架的「读取本机账号名字」步骤默认值、切号后的回读校验、
+# 以及「发布计划 → 一键推送（按名字找设备）」的实时探测。
+# 留空 = 还没抓：相关步骤会明确报错并跳过，**绝不会猜一个名字去发**。
+#
+# 2026-10-12 在 A01（抖音 40.6.0）实测可用的值：昵称那个 TextView 的 resource-id 是混淆 id `tk+`，
+# 所以填 resourceId（等价 xpath：//*[@resource-id="com.ss.android.ugc.aweme:id/tk+"]）。
+# 2026-10-12 实测：40.7.0 的昵称 id 是 `tkv`、40.6.0 是 `tk+` —— 用 **xpath 联合**一个值通吃两版
+# DOUYIN_NAME_SELECTOR_TYPE=xpath
+# DOUYIN_NAME_SELECTOR_VALUE=//*[@resource-id="com.ss.android.ugc.aweme:id/tkv"] | //*[@resource-id="com.ss.android.ugc.aweme:id/tk+"]
+
+# 「我」页面 →「切换账号」列表那个入口（自动切号用，同样抓一次填这里）。
+# 它是个只有 content-desc 的 ImageView（desc 就是「切换账号」），所以用 descriptionContains。
+# 留空 = 「切换账号」步骤会明确报错并跳过（不会瞎点）。
+# DOUYIN_SWITCH_SELECTOR_TYPE=descriptionContains
+# DOUYIN_SWITCH_SELECTOR_VALUE=切换账号
+#
+# 细节与结构图见 doc/research/U2_ELEMENT_SELECTORS.md §七（含"为什么不要用 (…b7w)[N]"）。
+
 
 # ==============================================================================
 # 已废弃的历史配置（STF 已从代码层摘除，下列键代码不再使用，保留仅为兼容旧 .env）

.gitignore

@@ -12,7 +12,11 @@ env/
 logs/*.log
 data/*.log
 data/apks/*.apk
+# 视频发布计划的素材（几百 MB 一个，绝不入库）
+data/videos/
 data/*.migrated
+# uiauto.pid 之类的运行时 PID 文件（**注释必须单独一行**：gitignore 不支持行尾注释）
+data/*.pid
 data/*.db-shm
 data/*.db-wal
 

README.md

@@ -45,10 +45,17 @@
 |------|------|
 | **多设备并发任务** | 每设备一个 Worker 线程；同一设备同时只跑一个任务（可配置"抢占"打断其他任务） |
 | **设备池** | SQLite 清单 + adb 在线状态；支持手工添加、网段自动发现、一键重连、型号采集、启用/停用 |
+| **电量监控** | 后台每分钟 `dumpsys battery`（只读）采一次电量，**大屏卡片**与**监控页设备列表**都显示（按档位着色 + ⚡ 充电中）；低于阈值推 webhook 告警（**充电中不报、"插着却没充电"照报**，掉档/恢复各报一次，不刷屏）。电量只放内存不落库（见 [NOTIFY.md](doc/NOTIFY.md) §3.1） |
 | **任务调度** | 手动 / cron 定时 / 定时启停；运行窗口；失败重试（含端口耗尽类的长退避） |
-| **步骤编辑器** | 可视化拖拽编排 18 种步骤（含循环/条件/OCR），可打包成"自定义动作"复用 |
+| **步骤编辑器** | 可视化拖拽编排 24 种步骤（含循环/条件/OCR/通知/录制回放），可打包成"自定义动作"复用 |
+| **拟人化操作** | 滑动默认走弧线轨迹、位置/幅度/时长每次抖动，且**每台设备有自己的手速与习惯**（同设备风格稳定、设备之间明显不同）——批量跑时不像同步机器人（见 [TASK_DEV.md](doc/TASK_DEV.md) §8.4） |
+| **录制回放** | 「录制手势」步骤 = **纯录制**：**用手指在真机上划**（读 getevent 真触屏）或在网页画面上拖，把轨迹点列原样存下来，回放时**照原路径与时长重放**——不套滑动那套方向/幅度/拟人参数 |
+| **动作配置 / 录制** | 「任务 → 动作配置」：① 配**步骤默认值**（新建步骤预填：滑动时长/幅度/抖动/拟人、点击超时、等待区间…）② **录制动作**——在设备画面上点/划/按键，自动翻译成步骤（点元素记选择器、划一下记方向/幅度/时长），可存成可复用动作，也可只取一个手势回填滑动步骤 |
+| **公共巡检** | 任务级的守护条件（**独立于步骤画布**）：每 N 秒检查屏幕亮/熄、元素在不在、前台是不是某 App，命中就点亮/息屏/停本设备/推通知——通知标题正文自己写（见 [TASK_DEV.md](doc/TASK_DEV.md) §4.5） |
+| **去重账本** | 解决"**同一个号被做两次、有的号还没做**"：任务里用「条件判断→去重」+「记为已做」，把"这个身份做过了"记进一张**所有设备共享**的账本——多台手机、反复重跑都不会重复做同一个号。「任务 → 去重记录」页能看"谁做过了、还差谁"，也能删记录让它重跑（见 [TASK_DEV.md](doc/TASK_DEV.md) §4.6） |
+| **视频发布计划** | 「发布计划」页：批量上传**视频/图片**（文件名 `名字_日期_编号`，**名字 = 抖音昵称**；视频和图片同一套规则）与标题 txt（每行 `标题 || 正文_名字_日期_编号`）→ 自动按 (名字,日期,编号) 配对 → **按日期的时间线**看每天谁要发、发到哪一步。**平台只负责把素材推到手机**（推到 `/sdcard/DCIM/Camera/`、触发相册刷新、把标题写进剪贴板），**抖音里怎么发由你自己在任务里写步骤**（步骤顺序：`读取本机账号名字` → `条件判断`校验 → `推送发布视频` → 你的发布步骤 → `标记发布结果`；页顶部有**「发布任务」**块可一键建好骨架 + 看下次运行/启停，`输入文字` 那一步可以选**取值来源＝计划标题/正文**自动填文案并回读校验）；发完可抓作品的**分享链接**存下来（平台不长期囤视频，链接才是长期资产，也方便后续铺评论：可一键复制、按日期/名字导出 CSV）。状态区分"**可重试**"（推送阶段失败，还没到抖音）与"**结果未知、需人工确认**"（推送之后出的岔子，绝不自动重发）（见 [DATA_MODEL.md](doc/DATA_MODEL.md) §2.11、[TASK_DEV.md](doc/TASK_DEV.md) §4.7） |
 | **元素抓取** | 拉取设备 UI 元素树 → 点选回填选择器；支持"点一下"与"测选择器"真机验证 |
-| **实时看屏** | MJPEG 实时流 + 点击/滑动/按键/文字输入；全屏监控大屏（`/wall`） |
+| **实时看屏** | MJPEG 实时流 + 点击/滑动/按键/文字输入；全屏监控大屏（`/wall`）：每个设备卡片点开就能操作，顶部还有 **「📤 发布」面板** —— 选设备直接把视频/图片推到相册、或把文案写进剪贴板（临时手动推，不占发布计划、不写库） |
 | **应用管理** | APK 上传/解析/批量安装；设备已装应用与版本查询；剪贴板注入 |
 | **AI 控制台** | 用自然语言驱动 AI 操作指定设备（MCP 工具 + 截图），流式输出、Markdown 渲染、推理链折叠、token 统计；成功操作自动沉淀「经验库 / 动作库」并在相似任务中召回 |
 | **MCP 接入** | 20 个 `de_*` 工具，把手机控制开放给外部 AI；写操作有开关、设备忙时拒绝、全量审计 |
@@ -127,18 +134,25 @@ auto_control/
 │
 ├── core/                      # 基础设施层
 │   ├── models.py              #   SQLAlchemy 模型 + 建表 + 版本化迁移 + 旧 JSON 迁移
-│   ├── device_pool.py         #   设备池（清单/在线状态/型号）
+│   ├── device_pool.py         #   设备池（清单/在线状态/型号/设备名→当前地址）
 │   ├── device_worker.py       #   BaseWorker + 设备生命周期 + 心跳看门狗 + 全局状态表
 │   ├── task_manager.py        #   调度器：分组/任务/APScheduler/重试/运行控制
 │   ├── adb_helper.py          #   adb 命令封装（全局锁，红线：绝不 kill-server）
 │   ├── device_discovery.py    #   网段扫描发现设备 → 待连接池
+│   ├── device_battery.py      #   设备电量采集（dumpsys 只读）+ 低电量告警
+│   ├── video_plan.py          #   视频发布计划（文件名解析配对 / 时间线 / 幂等占位 / 素材清理）
+│   ├── account_probe.py       #   实时探测设备当前登录的抖音号（按名字找设备用）
 │   ├── u2_helper.py           #   uiautomator2 通用辅助（等首页/安全点击等）
 │   ├── uiauto_helper.py       #   uiautodev 客户端（元素树 + XPath 建议）
 │   ├── ocr.py                 #   屏幕 OCR（RapidOCR，条件判断用）
 │   ├── clipboard_helper.py    #   剪贴板注入（ClipInject 通道）
 │   ├── apk_manager.py         #   APK 上传/解析/批量安装
 │   ├── system_backup.py       #   数据备份导出/导入（重启生效）
+│   ├── humanize.py            #   拟人化：弧线滑动/抖动 + 每台设备的"手感"（按 serial 播种）
 │   ├── notifier.py            #   通知分发（队列/聚合/限流/适配器）+ notify_events.py 事件目录
+│   ├── step_log.py            #   任务步骤明细（异步写线程 + 保留期清理）
+│   ├── patrol.py              #   任务级公共巡检（检查项/动作注册表，穿插执行）
+│   ├── step_defaults.py       #   步骤默认值（app_meta 单键，出厂值 + 用户覆盖）
 │   ├── tailscale_client.py    #   Tailscale API v2 客户端
 │   ├── ssh_client.py          #   SSH 封装（当前无人调用，预留）
 │   ├── logger.py              #   分文件日志（core/task/web/action）
@@ -147,7 +161,7 @@ auto_control/
 ├── tasks/                     # 任务定义层
 │   ├── base.py                #   BaseTask + _TASK_TYPES + register_task
 │   └── generic/               #   通用步骤任务（task_type=generic_steps，当前唯一类型）
-│       └── task.py            #     STEP_TYPES（18 种步骤）+ Worker + 执行器
+│       └── task.py            #     STEP_TYPES（24 种步骤）+ Worker + 执行器
 │
 ├── mcp_server/                # MCP Server（20 个 de_* 工具，:8033）
 │   ├── mcp_server.py          #   工具定义 + 平台登录 + 门控
@@ -184,7 +198,7 @@ auto_control/
 
 ```
 base.js → markdown.js → list.js → monitor.js → editor.js → tasks.js
-        → tools.js → apps.js → admin.js → agent.js → taskgen.js → system.js → notify.js
+        → tools.js → apps.js → admin.js → agent.js → taskgen.js → system.js → notify.js → steplog.js → recorder.js
 ```
 
 ---
@@ -245,8 +259,8 @@ self.set_progress(done=5, total=80, unit="视频", action_counts={"like": 3}, el
 | Tab | 内容 | 可见性 |
 |-----|------|--------|
 | **监控** | 统计卡片 + 设备表（在线/型号/任务状态/进度/前台 App/最近错误，支持排序、搜索、分页、多选批量操作）+ 异常汇总 + **任务运行概况**（每张任务卡：执行任务 / 停用任务 + 覆盖设备彩色 chip）；导航栏「📺 大屏」打开 `/wall` | 所有登录用户（设备操作按钮需"设备控制"） |
-| **任务** | 子分栏：**任务计划**（CRUD / 启停 / 执行 / 下次运行时间 / 离线跳过 / 步骤编辑器）、**自定义动作**（步骤打包复用） | 可看；写操作需"任务管理" |
-| **日志** | 实时日志（按文件切换、可自动刷新） | 需"日志查看" |
+| **任务** | 子分栏：**任务计划**（CRUD / 启停 / 执行 / 下次运行时间 / 离线跳过 / 步骤编辑器 / **公共巡检**）、**自定义动作**（步骤打包复用）、**动作配置**（步骤默认值 + 录制动作） | 可看；写操作需"任务管理" |
+| **日志** | 子分栏：**文件日志**（文件切换含滚动历史、关键字/级别/时间过滤、命中高亮、下载筛选结果、自动刷新）、**步骤明细**（按设备/任务/结果/时间过滤、按运行归组的概览、导出 CSV） | 需"日志查看" |
 | **用户** | 用户 CRUD、改密、分配权限 | 仅管理员 |
 | **工具** | 8 个子分栏：剪贴板注入 / adb 远程终端 / Tailscale 管理 / 应用管理 / 应用版本管理 / 设备已装应用 / **设备池管理**（含自动发现）/ 设备分组 | 仅管理员 |
 | **AI 控制台** | 会话列表 + 对话区（Markdown 渲染、推理链折叠、token 统计）+ 实时画面（MJPEG）+ 目标设备选择；右上角：经验库 / 动作库 / 模型配置 | 仅管理员 |
@@ -273,14 +287,14 @@ self.set_progress(done=5, total=80, unit="视频", action_counts={"like": 3}, el
 
 `generic_steps` 的执行内容全在 `params.steps`（JSON 数组），由步骤编辑器产出。**没有默认步骤**——空步骤任务执行时会明确报错。
 
-**18 种步骤**（完整参数见 [doc/TASK_DEV.md](doc/TASK_DEV.md)）：
+**24 种步骤**（完整参数见 [doc/TASK_DEV.md](doc/TASK_DEV.md)）：
 
 | 类别 | 步骤 |
 |------|------|
 | 屏幕 | `screen_on` 亮屏 · `screen_off` 息屏 · `keep_screen` 保持亮屏 |
 | 应用与输入 | `open_app` 打开 App · `stop_app` 结束 App · `input_text` 输入文字 · `clipboard` 剪贴板注入 · `key_event` 按键 |
 | 交互 | `click` 点击元素 · `click_xy` 点击坐标 · `long_click` 长按 · `swipe` 滑动 · `swipe_until` 滑动直到元素出现 · `wait_el` 等待元素 · `wait` 等待时长 |
-| 流程 | `loop` 循环块 · `group` 动作组 · `if_el` 条件判断（元素或 **OCR 识别**） |
+| 流程 | `loop` 循环块 · `group` 动作组 · `if_el` 条件判断（元素 / **OCR 识别** / 屏幕状态 / 前台App / **去重**）· `mark_done` 记为已做（配套去重） |
 
 要点：
 
@@ -357,7 +371,16 @@ from core.logger import get_logger
 log = get_logger("task.generic")   # → logs/task.log
 ```
 
-「日志」Tab 可在线查看。
+「日志」Tab 可在线查看：文件下拉包含 `.1/.2…` 滚动历史（可回溯更早的日志），
+支持关键字（命中高亮）/最低级别/时间范围过滤，点「下载」导出当前筛选结果
+（无筛选就是整个文件）。读取逻辑在 `core/logger.py` 的 `list_log_files()/query_log()/
+read_log_text()`，`file` 参数走白名单，不接受任意路径。
+
+「日志 → 步骤明细」是**结构化**的另一半：每一次步骤执行落一行 `task_step_log`
+（设备/任务/步骤路径/结果/耗时/选择器），因此能按设备、任务、结果、时间过滤，
+也能按 `run_id` 归组看"这一次运行为什么失败"、导出 CSV。写入是异步的
+（`core/step_log.py`，任务线程只入队，不阻塞执行），保留 14 天、单次运行最多
+2000 条 —— 这两个上限决定这张表（以及备份包）能长多大。
 
 ---
 
@@ -386,7 +409,7 @@ log = get_logger("task.generic")   # → logs/task.log
 | [doc/ARCHITECTURE.md](doc/ARCHITECTURE.md) | 架构详解（分层、装配顺序、线程模型、设备生命周期、调度链路、设计决策） |
 | [doc/DATA_MODEL.md](doc/DATA_MODEL.md) | 数据模型（表结构、迁移、`app_meta`、数据目录、备份覆盖清单） |
 | [doc/API.md](doc/API.md) | HTTP 接口全量说明 |
-| [doc/TASK_DEV.md](doc/TASK_DEV.md) | 任务与步骤开发（18 种步骤、选择器、自定义动作、新增任务类型） |
+| [doc/TASK_DEV.md](doc/TASK_DEV.md) | 任务与步骤开发（24 种步骤、公共巡检、录制回放、去重、选择器、自定义动作） |
 | [doc/MCP.md](doc/MCP.md) · [doc/MCP_DESIGN.md](doc/MCP_DESIGN.md) | MCP 使用手册 / 设计文档 |
 | [doc/AI_CONSOLE.md](doc/AI_CONSOLE.md) · [doc/AI_TASK_GEN.md](doc/AI_TASK_GEN.md) | AI 控制台机制 / AI 建任务设计（规划） |
 | [doc/DEPLOY.md](doc/DEPLOY.md) | 部署与运维（含生产容器、备份导入、故障排查） |

config.py

@@ -87,6 +87,28 @@ DATA_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "data")
 # APK 文件存储目录（应用管理功能）
 APK_DIR = os.path.join(DATA_DIR, "apks")
 
+# 视频发布计划的素材目录（发布计划功能）。**支持 env 覆盖**，理由同下面三个：
+# 自动化测试必须把素材目录指到临时位置，否则测试上传的视频会落进用户真实数据目录。
+VIDEO_DIR = _env("DATA_VIDEO_DIR", "") or os.path.join(DATA_DIR, "videos")
+
+# ================== 抖音「我」页面的昵称控件（发布计划按名字发） ==================
+# **抓一次填这里**（用「抓取元素」抓抖音「我」页面上的昵称那个 TextView）。
+# 一处配置、三处一致：发布任务骨架的「读取本机账号名字」步骤默认值、
+# 「切换账号」的切后校验、以及「发布计划 → 一键推送（按名字找设备）」的实时探测。
+# 任务步骤里仍可单独改（存进那一步的参数），这里只是**默认值**。
+# 留空 = 还没抓：相关步骤会明确报"请抓取元素"，绝不会猜一个名字去发。
+DOUYIN_NAME_SELECTOR_TYPE = _env("DOUYIN_NAME_SELECTOR_TYPE", "xpath")
+DOUYIN_NAME_SELECTOR_VALUE = _env("DOUYIN_NAME_SELECTOR_VALUE", "")
+
+# 「我」页面 →「切换账号」列表那个入口（同样是**抓一次填这里**）：自动切号要用。
+# 留空 = 「切换账号」步骤会明确报"请抓取元素"并跳过（不会瞎点）。
+DOUYIN_SWITCH_SELECTOR_TYPE = _env("DOUYIN_SWITCH_SELECTOR_TYPE", "xpath")
+DOUYIN_SWITCH_SELECTOR_VALUE = _env("DOUYIN_SWITCH_SELECTOR_VALUE", "")
+
+# 单次请求体上限（字节）。**必须大于现有 APK 上传的最大包**（实测 336MB），
+# 否则「应用管理」的 APK 上传会被一起卡死。默认 2GiB：一个视频 + 余量。
+MAX_CONTENT_LENGTH = int(_env("MAX_UPLOAD_MB", "2048")) * 1024 * 1024
+
 # ================== 系统数据备份（导出/导入） ==================
 # 导出 zip 与恢复前快照存放；导入暂存目录；待下次启动生效的恢复目录
 # （运行时产物，不入 git，见 .gitignore data/backups 等）

core/account_probe.py

@@ -0,0 +1,158 @@
+"""实时探测"这台设备现在登的是哪个抖音号"（**按名字找设备**用）。
+
+**谁用它**：人工入口 —— 「发布计划」页的「一键推送（按名字找设备）」要先知道
+"哪台在线设备现在登着这个名字"，才能把素材推过去。
+**自动任务不靠它**：任务里的「读取本机账号名字」永远是现场读屏幕（缓存旧了也不能影响发布正确性）。
+
+它只做**只读/幂等**的动作：连设备 → 需要时把抖音拉到前台 → 点「我」→ 读昵称控件 → 清洗。
+**绝不登录、绝不滑块、绝不改设备设置**；连不上/读不到只报那一台，不影响别的设备。
+也绝不 `kill-server` / `disconnect`（技术约束红线）。
+
+昵称控件在 `config.DOUYIN_NAME_SELECTOR_VALUE`（**抓一次填 .env**，与任务骨架同一处配置）；
+没填就明确报"还没抓"，不去猜。
+"""
+import time
+from concurrent.futures import ThreadPoolExecutor
+
+from config import DOUYIN_NAME_SELECTOR_TYPE, DOUYIN_NAME_SELECTOR_VALUE
+from core import u2_helper
+from core.logger import get_logger
+
+_log = get_logger("core.account_probe")
+
+DOUYIN_PKG = "com.ss.android.ugc.aweme"
+_CONNECT_TIMEOUT = 20        # u2.connect 超时（秒）；设备端 u2 服务没响应时别把请求挂死
+_STEP_WAIT = 2.5             # 进「我」页面后等它渲染完
+
+
+def _connect(serial, timeout=_CONNECT_TIMEOUT):
+    """带超时的 u2.connect。
+
+    ⚠ 用**手动 shutdown(wait=False)** —— `with ThreadPoolExecutor(...)` 退出时会
+    `shutdown(wait=True)`，超时线程不死它就跟着等，30 秒的"超时"会变成真卡住
+    （`core/device_worker` 里踩过这个坑）。
+    """
+    import uiautomator2 as u2
+    pool = ThreadPoolExecutor(max_workers=1)
+    try:
+        return pool.submit(u2.connect, serial).result(timeout=timeout)
+    finally:
+        pool.shutdown(wait=False)
+
+
+def probe_one(serial, click_me=True):
+    """读一台设备当前登录的抖音名字。返回 `{serial, name, error}`。
+
+    `name` 非空 = 读到了；`error` 非空 = 没读到（人话原因，给界面直接显示）。
+    """
+    if not DOUYIN_NAME_SELECTOR_VALUE:
+        return {"serial": serial, "name": "",
+                "error": "还没抓抖音昵称控件：在 .env 里填 DOUYIN_NAME_SELECTOR_VALUE"
+                         "（抓取元素抓一下「我」页面上的昵称）"}
+    d = None
+    try:
+        d = _connect(serial)
+    except Exception as e:
+        return {"serial": serial, "name": "",
+                "error": f"连不上设备（u2 {_CONNECT_TIMEOUT}s 超时）：{type(e).__name__}"}
+    try:
+        pkg = u2_helper.current_package(d)
+        if pkg != DOUYIN_PKG:
+            # 不在抖音 → 拉到前台（幂等：已经在就什么都不做）
+            try:
+                d.app_start(DOUYIN_PKG, wait=True)
+            except Exception as e:
+                return {"serial": serial, "name": "",
+                        "error": f"打不开抖音：{type(e).__name__}: {str(e)[:60]}"}
+            time.sleep(4)
+        if click_me:
+            u2_helper.find_and_click(d, timeout=3,
+                                     **{"descriptionContains": "我"})
+        time.sleep(_STEP_WAIT)
+        from core import video_plan as vp
+        if DOUYIN_NAME_SELECTOR_TYPE == "xpath":
+            el = d.xpath(DOUYIN_NAME_SELECTOR_VALUE)
+            raw = el.get_text() if el.exists else ""
+        else:
+            el = d(**{DOUYIN_NAME_SELECTOR_TYPE: DOUYIN_NAME_SELECTOR_VALUE})
+            raw = el.get_text(timeout=3) if el.exists(timeout=3) else ""
+        name = vp.clean_account_name(raw)
+        if not name:
+            return {"serial": serial, "name": "",
+                    "error": f"读到空（元素原文 {raw!r}）—— 昵称控件的选择器可能抓错了"}
+        return {"serial": serial, "name": name, "error": ""}
+    except Exception as e:
+        return {"serial": serial, "name": "",
+                "error": f"读取失败：{type(e).__name__}: {str(e)[:80]}"}
+    finally:
+        # **不 disconnect、不 kill-server**（红线）：u2 的连接自己会超时回收
+        pass
+
+
+def busy_serials():
+    """正在跑任务/正在连接的设备（探测要跳过它们：抢屏会打断任务）。"""
+    from core import device_worker
+    out = set()
+    try:
+        for s in device_worker.get_all_worker_status():
+            if (s.get("status") or "") in ("running", "connecting"):
+                out.add(s.get("serial") or "")
+    except Exception as e:
+        _log.warning(f"读设备运行状态失败（按「都不忙」处理）: {e}")
+    return {x for x in out if x}
+
+
+def probe_online(serials=None, skip_busy=True, workers=4):
+    """并行探测多台设备。返回 `{serial: {serial, name, error}}`。
+
+    · `serials=None` → 取设备池里**在线且启用**的设备（`device_pool.list_ready()`）
+    · `skip_busy=True`（默认）→ 跳过正在跑任务/连接中的设备（别抢它们的屏）
+    · 单台失败只影响那一台；顺序按传入/池里的顺序
+    """
+    from core import device_pool
+    if serials is None:
+        try:
+            serials = list(device_pool.list_ready())
+        except Exception as e:
+            _log.warning(f"取在线设备失败: {e}")
+            return {}
+    serials = [s for s in (serials or []) if s]
+    if skip_busy:
+        busy = busy_serials()
+        if busy:
+            _log.info(f"探测跳过正在跑任务的设备：{'、'.join(sorted(busy))}")
+        serials = [s for s in serials if s not in busy]
+    out = {}
+    if not serials:
+        return out
+    with ThreadPoolExecutor(max_workers=max(1, min(workers, len(serials)))) as pool:
+        for r in pool.map(probe_one, serials):
+            out[r["serial"]] = r
+    return out
+
+
+def cache_names(result):
+    """把探测结果写进 `device.cur_account_name/cur_name_at`（**只用于人工入口的设备建议**）。
+
+    ⚠ 必须在 **Flask app context** 里调用（web 请求线程本身就有；脚本里自己推）。
+    探测失败的那台**不清空旧值**（旧值好歹是个线索，界面上带时间戳显示）。
+    """
+    from core.models import Device, db
+    try:
+        now = time.strftime("%Y-%m-%d %H:%M:%S")
+        for serial, r in (result or {}).items():
+            name = (r or {}).get("name") or ""
+            if not name:
+                continue
+            row = Device.query.get(serial)
+            if not row:
+                continue
+            row.cur_account_name = name[:80]
+            row.cur_name_at = now
+        db.session.commit()
+    except Exception as e:
+        _log.warning(f"写设备当前账号缓存失败（不影响探测结果）: {e}")
+        try:
+            db.session.rollback()
+        except Exception:
+            pass

core/clipboard_helper.py

@@ -1,10 +1,13 @@
-"""剪贴板注入公共模块（ClipInject APK 通道）。
+"""剪贴板注入公共模块（设备端 Agent 通道）。
 
 背景：Android 10+ 禁止后台（atx-agent/shell）写剪贴板——u2.set_clipboard
-调用"成功"但内容被系统静默丢弃（Android 12/13 实测）。ClipInject
-（com.example.clipinject，用户自研 APK）通过 am start 启动透明 Activity，
-窗口聚焦后 setPrimaryClip；shell 身份启动 Activity 不受后台启动限制
-（广播方式在 MIUI 会被 Background activity start 拦截，必须用 am start）。
+调用"成功"但内容被系统静默丢弃（Android 12/13 实测）。设备端 APK 通过 am start
+启动**透明 Activity**，窗口聚焦后 setPrimaryClip；shell 身份启动 Activity 不受
+后台启动限制（广播方式在 MIUI 会被 Background activity start 拦截，必须用 am start）。
+
+**注入目标按顺序尝试**：先设备端聚合 Agent（`com.example.deviceagent`，现在的标准通道），
+再兜底老设备上可能残留的独立 ClipInject（`com.example.clipinject`）。
+两者只有一个 `--es text_b64` 的契约差异为零，所以是"换个包名再试一次"。
 
 工具页（web/tools_api.py）与任务执行器（tasks/generic/task.py）共用本模块。
 """
@@ -19,17 +22,43 @@ from core.logger import get_logger
 
 _log = get_logger("core.clip")
 
-_CLIP_PACKAGE = "com.example.clipinject"
-_CLIP_ACTIVITY = "com.example.clipinject/.ClipActivity"
+# (包名, am start 目标, 给用户看的名字)；顺序 = 尝试顺序
+_CLIP_TARGETS = (
+    ("com.example.deviceagent", "com.example.deviceagent/.ClipActivity", "设备端 Agent"),
+    ("com.example.clipinject", "com.example.clipinject/.ClipActivity", "旧版 ClipInject"),
+)
+
+
+def _am_start(serial, activity, b64):
+    """拉起透明 Activity 写剪贴板。返回 (输出文本, 是否执行成功)。"""
+    try:
+        r = subprocess.run(
+            [ADB_PATH, "-s", serial, "shell", "am", "start",
+             "-n", activity, "--es", "text_b64", b64],
+            capture_output=True, timeout=30)
+    except subprocess.TimeoutExpired:
+        return "am start 超时（adb 无响应）", False
+    except Exception as e:
+        return f"{type(e).__name__}: {str(e)[:120]}", False
+    out = ((r.stdout or b"") + (r.stderr or b"")).decode(errors="replace")
+    # "Starting: Intent {…}" 后面跟 "Error type 3 / Error: Activity class … does not exist."
+    # 时也是失败——所以不能只看有没有 Starting
+    if "does not exist" in out or "unable to resolve Intent" in out or "Error type 3" in out:
+        return out, False
+    if "Error" in out or ("Starting" not in out and r.returncode != 0):
+        return out, False
+    return out, True
 
 
 def inject_clipboard(serial, text, d=None):
     """向设备剪贴板注入文字，返回 (ok, msg)。
 
+    - 依次尝试 `_CLIP_TARGETS`（设备端 Agent → 旧版 ClipInject）：设备上装哪个用哪个，
+      两个都没有时明确报"需要装设备端 Agent"（不再只说 ClipInject，用户会以为要装老 APK）
     - d：可选，任务执行器已持有 u2 Device 时传入复用（跳过重复连接），
       读回验证直接用它；不传则临时 u2.connect（工具页场景，带超时保护）
     - IP:port 设备先 adb connect（已连接自动跳过；绝不 disconnect，红线）
-    - 未装 ClipInject / 读回不一致都会明确报错（不再静默失败）
+    - 通道缺失 / 读回不一致都会明确报错（不再静默失败）
     """
     import uiautomator2 as u2
     if ":" in serial:
@@ -39,31 +68,45 @@ def inject_clipboard(serial, text, d=None):
             return False, f"adb 连接失败: {e}"
     b64 = base64.b64encode(text.encode("utf-8")).decode()
     # 1. am start 透明 Activity 写剪贴板（shell 身份，不受后台启动限制）
-    try:
-        r = subprocess.run(
-            [ADB_PATH, "-s", serial, "shell", "am", "start",
-             "-n", _CLIP_ACTIVITY, "--es", "text_b64", b64],
-            capture_output=True, timeout=30)
-        out = ((r.stdout or b"") + (r.stderr or b"")).decode(errors="replace")
-        if "does not exist" in out or "unable to resolve Intent" in out:
-            return False, f"设备未安装 ClipInject（{_CLIP_PACKAGE}），请先安装"
-        if "Error" in out or ("Starting" not in out and r.returncode != 0):
-            return False, f"am start 失败: {out.strip()[:120]}"
-    except subprocess.TimeoutExpired:
-        return False, "am start 超时（adb 无响应）"
-    except Exception as e:
-        return False, f"{type(e).__name__}: {str(e)[:120]}"
-    # 2. 读回验证（等透明 Activity 完成写入；u2 读剪贴板在 Android 12 实测可用）
-    time.sleep(0.5)
+    tried = []
+    for pkg, activity, label in _CLIP_TARGETS:
+        out, started = _am_start(serial, activity, b64)
+        if started:
+            if tried:
+                # 走到兜底通道：记一条，好提醒"这台设备该装 Agent 了"
+                _log.info(f"[{serial}] 剪贴板注入：{'、'.join(tried)} 都没有，"
+                          f"改用{label}（{pkg}）成功 —— 建议给这台设备装设备端 Agent")
+            break
+        if "does not exist" in out or "unable to resolve Intent" in out or "Error type 3" in out:
+            tried.append(label)
+            continue
+        # 装了但启动失败：直接报错，不再往下试（下一个包大概率也没装）
+        return False, f"am start 失败（{label}）: {out.strip()[:120]}"
+    else:
+        return False, ("设备未安装剪贴板注入通道：需要设备端 Agent"
+                       "（com.example.deviceagent）——从「应用管理 → 设备端应用商店」安装；"
+                       "旧版独立 ClipInject（com.example.clipinject）也可以，但已不再随平台分发")
+    # 2. 读回验证：**必须轮询**。透明 Activity 要等窗口拿到焦点才写（还有 800ms 兜底），
+    #    只睡一次 0.5s 会读到**上一次的剪贴板内容** → 误报"写入可能被拒"（实测踩过：
+    #    内容明明写进去了，接口却回 1 台失败）。轮询到 ~3 秒：一致即成功；
+    #    一直不一致才算真的被拒。
     try:
         if d is None:
             with ThreadPoolExecutor(max_workers=1) as pool:
                 d = pool.submit(u2.connect, serial).result(timeout=30)
-        with ThreadPoolExecutor(max_workers=1) as pool:
-            got = pool.submit(lambda: d.clipboard).result(timeout=15)
+    except Exception as e:
+        return True, f"已注入（读回验证不可用: {type(e).__name__}: {str(e)[:80]}）"
+    deadline = time.time() + 3.0
+    got = None
+    while True:
+        time.sleep(0.4)
+        try:
+            with ThreadPoolExecutor(max_workers=1) as pool:
+                got = pool.submit(lambda: d.clipboard).result(timeout=15)
+        except Exception as e:
+            # 读回不可用（旧版 u2/连接失败）时按写入成功处理，避免误报，但带上具体原因
+            return True, f"已注入（读回验证不可用: {type(e).__name__}: {str(e)[:80]}）"
         if got == text:
             return True, "已注入"
-        return False, f"剪贴板读回不一致（写入可能被拒）: {str(got)[:60]!r}"
-    except Exception as e:
-        # 读回不可用（旧版 u2/连接失败）时按写入成功处理，避免误报，但带上具体原因
-        return True, f"已注入（读回验证不可用: {type(e).__name__}: {str(e)[:80]}）"
+        if time.time() >= deadline:
+            return False, f"剪贴板读回不一致（写入可能被拒）: {str(got)[:60]!r}"

core/dedup.py

@@ -0,0 +1,235 @@
+"""「已做过」账本：跨设备幂等（评论不重复）+ 进度可见。
+
+**它解决什么**（用户场景）：一台手机登录多个账号、多台手机跑同一个任务，
+每天跑一次但不知道什么时候跑完，于是反复重跑 → 同一个号被做两次、有的号还没做。
+账本给出两个东西：
+  1. `check()` —— "这个身份在这个任务里做过了吗"（跨设备，多台手机共享同一份判断）
+  2. `list_marks()` —— "谁做过了、还差谁"（界面上看得见，就不用靠"一直重跑"来确认）
+
+**为什么必须靠唯一索引**：多台设备可能同时判断"没做过"。
+"先 SELECT 再 INSERT"有竞态——两台都会插进去。唯一索引 + `INSERT ... ON DUPLICATE KEY`
+（MySQL）/ `INSERT OR IGNORE`（SQLite）的**受影响行数**才是原子的判据：
+`1` = 你抢到了首次，`0` = 别人已经做过。
+
+**身份值读不到时绝不去重**（`identity is None`）：宁可漏拦一次，
+也不能让"读不到"退化成"空身份"——那会让所有设备共用一个 key，
+第一台记账后其余全部被误跳过。同理，身份值过长时也不截断（截断会让两个身份撞车）。
+
+有效期策略（`kind`）由任务级参数 `dedup_reset` 决定，**只在一处配**：
+步骤里各填一份的话，两处填不一致就会算出不用的 key、去重静默失效。
+
+DB 访问由本模块自建 app context（照 `core/device_pool.py` 的 `_ctx()`），
+调用方（任务线程 / Web 线程 / 每日清理）都不用关心。
+"""
+import time
+from datetime import datetime, timedelta
+
+from core.logger import get_logger
+from core.models import db
+
+_log = get_logger("core.dedup")
+
+# 有效期策略
+KIND_DAY = "day"        # 每天一次（默认；"每天跑一次"的场景）
+KIND_HOURS = "hours"    # 每 N 小时一次
+KIND_ALL = "all"        # 只做一次（永久）
+RESET_KINDS = (KIND_DAY, KIND_ALL, KIND_HOURS)
+DEFAULT_HOURS = 6
+# 账本保留期：只影响 day/hours 桶（它们过期就没意义了）；
+# **kind='all' 的记录永不清理**——清了就等于"只做一次"失效
+KEEP_DAYS = 180
+# scope_key 上限（= DoneMark.scope_key 列宽）。超了不去重、只告警：
+# 截断会让两个不同身份撞成同一个 key，进而误跳过
+MAX_KEY_LEN = 290
+
+_app = None
+
+
+def init_app(app):
+    """web_server 启动时调用：绑 app（后台线程访问 db 要自推 context）。"""
+    global _app
+    _app = app
+
+
+def _ctx():
+    if _app is None:
+        raise RuntimeError("dedup 未关联 Flask app（web_server 启动时调用 init_app）")
+    return _app.app_context()
+
+
+# ================== 唯一键 ==================
+def build_key(job_id, identity, kind=KIND_DAY, hours=DEFAULT_HOURS, now=None):
+    """算唯一键：`任务 | 身份 | 时间桶`。
+
+    桶只影响"多久之后算新的一轮"：
+      · day   → `|d:2026-09-24`（本地日期，跟着自然日走）
+      · hours → `|h6:4939219`（epoch // (N*3600)，改 N 就换了桶）
+      · all   → `|all`（无桶，永远命中同一个 key）
+    """
+    now = time.time() if now is None else now
+    base = f"{(job_id or '').strip()}|{(identity or '').strip()}"
+    if kind == KIND_ALL:
+        return base + "|all"
+    if kind == KIND_HOURS:
+        h = max(1, int(hours or DEFAULT_HOURS))
+        return f"{base}|h{h}:{int(now // (h * 3600))}"
+    return base + "|d:" + time.strftime("%Y-%m-%d", time.localtime(now))
+
+
+def _key_or_none(job_id, identity, kind, hours):
+    """算 key 并做长度体检；超长返回 None（调用方按"不去重"处理，不截断）。"""
+    if not (identity or "").strip():
+        return None
+    key = build_key(job_id, identity, kind, hours)
+    if len(key) > MAX_KEY_LEN:
+        _log.warning(f"去重键过长（{len(key)} 字符）→ 本次不去重，避免截断后两个身份撞车: {key[:80]}…")
+        return None
+    return key
+
+
+# ================== 查 / 记 ==================
+def check(job_id, identity, kind=KIND_DAY, hours=DEFAULT_HOURS):
+    """这个身份在这个任务里做过了吗？（只读）
+
+    返回 True=做过 / False=没做过。identity 为空时返回 False（不去重，照常执行）。
+    """
+    key = _key_or_none(job_id, identity, kind, hours)
+    if key is None:
+        return False
+    try:
+        with _ctx():
+            row = db.session.execute(
+                db.text("SELECT 1 FROM done_mark WHERE scope_key = :k LIMIT 1"),
+                {"k": key}).fetchone()
+            return row is not None
+    except Exception as e:
+        # 账本读失败不能拦住任务：当"没做过"放行（宁可重复，不可卡死）
+        _log.warning(f"去重检查失败（按未做过放行）: {e}")
+        return False
+
+
+def mark(job_id, identity, kind=KIND_DAY, hours=DEFAULT_HOURS,
+         serial="", device_name="", job_name=""):
+    """原子记账。返回 True=本次是首次（你抢到了）/ False=别人已经记过（或没记成）。
+
+    ⚠ **必须靠唯一索引**：不能先 check 再 insert（多台设备会同时通过）。
+    """
+    key = _key_or_none(job_id, identity, kind, hours)
+    if key is None:
+        return False
+    args = {"k": key, "kind": kind, "jid": job_id or "", "jname": job_name or "",
+            "serial": serial or "", "dname": device_name or "",
+            "ident": (identity or "").strip()[:200],
+            "ts": time.strftime("%Y-%m-%d %H:%M:%S")}
+    try:
+        with _ctx():
+            is_mysql = db.engine.dialect.name == "mysql"
+            cols = ("scope_key, kind, job_id, job_name, serial, device_name, "
+                    "identity, created_at")
+            vals = (":k, :kind, :jid, :jname, :serial, :dname, :ident, :ts")
+            if is_mysql:
+                # 冲突时做一次"无变化"的更新：受影响行数 1=插入、0=已存在（MySQL 语义）
+                sql = (f"INSERT INTO done_mark ({cols}) VALUES ({vals}) "
+                       f"ON DUPLICATE KEY UPDATE scope_key = scope_key")
+            else:
+                sql = f"INSERT OR IGNORE INTO done_mark ({cols}) VALUES ({vals})"
+            r = db.session.execute(db.text(sql), args)
+            db.session.commit()
+            first = (r.rowcount or 0) > 0
+            if first:
+                _log.info(f"[{serial}] 记账：任务『{job_name or job_id}』身份『{args['ident']}』"
+                          f"（{kind}）")
+            return first
+    except Exception as e:
+        _log.warning(f"去重记账失败（本次不记，下次重跑会重试）: {e}")
+        return False
+
+
+# ================== 界面：看 / 清 ==================
+def list_marks(job_id="", limit=200):
+    """去重记录（界面用）：返回 (rows, stats)。
+
+    stats：`total` 本任务全部 · `today_devices` 今天已做的设备数 ·
+    `today_identities` 今天已做的身份值数（== "今天做成了几个号"）。
+    """
+    limit = max(1, min(int(limit or 200), 2000))
+    today0 = time.strftime("%Y-%m-%d 00:00:00")
+    where, args = "", {}
+    if job_id:
+        where = "WHERE job_id = :jid"
+        args["jid"] = job_id
+    with _ctx():
+        rows = db.session.execute(db.text(
+            f"SELECT id, scope_key, kind, job_id, job_name, serial, device_name, "
+            f"identity, created_at FROM done_mark {where} "
+            f"ORDER BY id DESC LIMIT :lim"), {**args, "lim": limit}).fetchall()
+        twhere = where + (" AND " if where else "WHERE ") + "created_at >= :t0"
+        stat = db.session.execute(db.text(
+            f"SELECT COUNT(*) AS total, "
+            f"COUNT(DISTINCT serial) AS devs, "
+            f"COUNT(DISTINCT identity) AS ids "
+            f"FROM done_mark {where}"), args).fetchone()
+        today = db.session.execute(db.text(
+            f"SELECT COUNT(DISTINCT serial) AS devs, "
+            f"COUNT(DISTINCT identity) AS ids "
+            f"FROM done_mark {twhere}"), {**args, "t0": today0}).fetchone()
+    out = [{"id": r[0], "scope_key": r[1], "kind": r[2], "job_id": r[3], "job_name": r[4],
+            "serial": r[5], "device_name": r[6], "identity": r[7], "created_at": r[8]}
+           for r in rows]
+    stats = {"total": stat[0] if stat else 0,
+             "devices": stat[1] if stat else 0,
+             "identities": stat[2] if stat else 0,
+             "today_devices": today[0] if today else 0,
+             "today_identities": today[1] if today else 0}
+    return out, stats
+
+
+def delete_mark(mark_id):
+    """删一条记录（让某个号/某台设备能重跑）。返回是否删掉了。"""
+    try:
+        with _ctx():
+            r = db.session.execute(db.text("DELETE FROM done_mark WHERE id = :i"),
+                                   {"i": int(mark_id)})
+            db.session.commit()
+            return (r.rowcount or 0) > 0
+    except Exception as e:
+        _log.warning(f"删除去重记录失败: {e}")
+        return False
+
+
+def clear_job(job_id):
+    """清空某个任务的全部去重记录（整批重跑）。返回删掉的行数。"""
+    try:
+        with _ctx():
+            r = db.session.execute(db.text("DELETE FROM done_mark WHERE job_id = :j"),
+                                   {"j": job_id or ""})
+            db.session.commit()
+            n = r.rowcount or 0
+            _log.info(f"清空去重记录：任务 {job_id} 共 {n} 条")
+            return n
+    except Exception as e:
+        _log.warning(f"清空去重记录失败: {e}")
+        return 0
+
+
+def purge_old(keep_days=KEEP_DAYS):
+    """清理过期的 day/hours 桶记录。**kind='all' 永不清理**（清了等于去重失效）。
+
+    量级很小（设备数 × 天数），直接一条 DELETE 就行，不用像步骤明细那样分批。
+    """
+    cutoff = (datetime.now() - timedelta(days=max(1, int(keep_days)))
+              ).strftime("%Y-%m-%d %H:%M:%S")
+    try:
+        with _ctx():
+            r = db.session.execute(db.text(
+                "DELETE FROM done_mark WHERE kind <> :all AND created_at < :cut"),
+                {"all": KIND_ALL, "cut": cutoff})
+            db.session.commit()
+            n = r.rowcount or 0
+        if n:
+            _log.info(f"去重记录清理：删除 {n} 条（保留 {keep_days} 天；"
+                      f"kind={KIND_ALL} 的永不清理）")
+        return n
+    except Exception as e:
+        _log.warning(f"去重记录清理失败: {e}")
+        return 0

core/device_battery.py

@@ -0,0 +1,404 @@
+"""设备电量采集 + 低电量告警（大屏/监控展示 + webhook 通知）。
+
+设计要点（都是被现有代码/实测约束逼出来的，改之前先读一遍）：
+
+  - **只读**：`adb -s <serial> shell dumpsys battery`（实测 0.2~0.35s/台）。
+    全模块不 connect / 不 disconnect / 不 kill-server（技术红线，见 doc/DEVELOPMENT.md）。
+    能查到的前提是设备已在 adb server 里（= device_pool.list_online()），
+    所以连"空闲设备"也能查——**不需要 connect**，这是本模块敢每轮扫全量的原因。
+  - **后台独立线程**采集（照 core/device_discovery.py 的 daemon 循环）：`/api/status`
+    只读内存缓存。绝不能把 dumpsys 放进 /api/status——前端 5 秒轮询一次，
+    14 台设备同步查会把 Flask 拖死（`get_status` 的 5s 缓存注释也写了这条）。
+  - **不落库**：电量是易变值，重启重新采一轮即可 → 不建表、**不动备份覆盖清单**。
+  - 告警走 notifier（`device.battery.low` / `device.battery.recovered`），
+    **按档位做状态沿检测**（正常/低/严重），掉档才报，绝不满屏刷。
+  - 配置存 `app_meta.device_battery` 一个键（照 core/step_defaults.py 的做法：
+    出厂默认 + 字段白名单 + 只落"与出厂值不同"的字段）。
+"""
+import json
+import re
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+from config import USB_ADB_HOST, USB_ADB_PORT
+from core import notifier, device_pool
+from core.adb_helper import _adb, _adb_remote
+from core.logger import get_logger
+from core.models import db
+
+_log = get_logger("core.battery")
+
+# 出厂默认（前端「工具 → 设备发现 → 电量监控」的初始内容，也是没配过时的回退）
+FACTORY = {
+    "enabled": True,
+    "low": 20,             # 低电量阈值（%）
+    "critical": 10,        # 严重低电量阈值（%）——通知等级升到 error
+    "skip_charging": True,  # 充电中不告警（插着充电器说明正在补电）
+    "interval": 60,        # 采集间隔（秒）
+}
+
+# 字段规格：("num", 最小, 最大) / ("bool",)。白名单之外的一律丢弃。
+SPEC = {
+    "enabled": ("bool",),
+    "low": ("num", 1, 100),
+    "critical": ("num", 1, 100),
+    "skip_charging": ("bool",),
+    "interval": ("num", 30, 3600),
+}
+
+META_KEY = "device_battery"
+
+# 恢复迟滞：掉到阈值下之后，要回升到 low+HYSTERESIS 才算"恢复"。
+# 没有它的话，电量在阈值上下浮动（充电器接触不良）会反复告警。
+HYSTERESIS = 5
+# 持续低电量的重复提醒间隔（秒）。0 = 只提醒一次（等恢复后才重新武装）。
+RE_NOTIFY_S = 6 * 3600
+# 单台设备读取超时（秒）。正常 0.2~0.35s，8s 已经非常宽松。
+_READ_TIMEOUT = 8
+
+_app = None
+_cache = {}       # serial -> {"level": int, "charging": bool, "at": ts}
+_tiers = {}       # serial -> {"tier": int, "at": ts}  告警档位状态（0 正常/1 低/2 严重）
+_lock = threading.Lock()
+_stop_event = threading.Event()
+_scanning = False
+_last_scan = None   # (时间串, 采集成功数, 在线数)
+
+
+def _ctx():
+    """后台线程访问 db 时自行推 app context（仿 device_pool._ctx）。"""
+    return _app.app_context() if _app else None
+
+
+# ================== 配置读写 ==================
+def factory():
+    """出厂默认的拷贝（别让调用方改到常量）。"""
+    return dict(FACTORY)
+
+
+def _clean(raw):
+    """按 SPEC 校验清洗；非法字段**丢弃**（不让脏值进库）。"""
+    if not isinstance(raw, dict):
+        return {}
+    out = {}
+    for k, rule in SPEC.items():
+        if k not in raw:
+            continue
+        v = raw[k]
+        try:
+            if rule[0] == "bool":
+                out[k] = bool(v)
+            elif rule[0] == "num":
+                out[k] = int(round(max(rule[1], min(rule[2], float(v)))))
+        except (TypeError, ValueError):
+            continue
+    return out
+
+
+def get_settings():
+    """当前生效配置（读库；模块未初始化时回退出厂值，别让调用方炸）。"""
+    ctx = _ctx()
+    if ctx is None:
+        return factory()
+    try:
+        from core.db_config import meta_get
+        with ctx:
+            raw = meta_get(META_KEY) or ""
+        if not raw:
+            return factory()
+        return _merge(json.loads(raw))
+    except Exception:
+        return factory()
+
+
+def _merge(user):
+    """出厂默认 + 用户覆盖（逐字段合并 + 钳制）。"""
+    vals = dict(FACTORY)
+    vals.update(_clean(user))
+    # 严重阈值不能高于低电量阈值，否则"严重"永远先触发，语义反了
+    if vals["critical"] > vals["low"]:
+        vals["critical"] = vals["low"]
+    return vals
+
+
+def save_settings(payload):
+    """保存配置。返回 (ok, msg, saved)。
+
+    与出厂默认**相同的字段不入库**（照 step_defaults）：以后调出厂值时，
+    没配过的字段能跟着更新，库里只留"用户真的改过"的部分。
+    """
+    vals = _merge(payload)
+    diff = {k: v for k, v in vals.items() if FACTORY.get(k) != v}
+    ctx = _ctx()
+    if ctx is None:
+        return False, "电量模块未初始化", {}
+    try:
+        from core.db_config import meta_set
+        with ctx:
+            meta_set(META_KEY, json.dumps(diff, ensure_ascii=False))
+            db.session.commit()
+    except Exception as e:
+        return False, f"保存失败: {e}", {}
+    _log.info(f"电量监控配置已保存: {vals}")
+    return True, "已保存", vals
+
+
+# ================== 单台读取与解析 ==================
+_BAT_LEVEL_RE = re.compile(r"^\s*level:\s*(\d+)", re.M)
+_BAT_SCALE_RE = re.compile(r"^\s*scale:\s*(\d+)", re.M)
+_BAT_STATUS_RE = re.compile(r"^\s*status:\s*(\d+)", re.M)
+# 部分 ROM 没有 status 行时的兜底：插着电就算充电中
+_POWERED_RE = re.compile(r"^\s*(?:AC|USB|Wireless) powered:\s*true", re.M)
+
+
+def _parse_battery(text):
+    """解析 `dumpsys battery` 输出，返回 (level, charging) 或 None。
+
+    status: 2=充电中 5=已充满 → charging；3=放电 4=未充电（插着但不充，
+    例如劣质线/温控/满电停充）→ 不算充电中。所以"插着却掉电"仍然会告警，
+    这正是最该让人知道的情况。
+    """
+    if not text or "level:" not in text:
+        return None
+    m = _BAT_LEVEL_RE.search(text)
+    if not m:
+        return None
+    level = int(m.group(1))
+    ms = _BAT_SCALE_RE.search(text)
+    scale = int(ms.group(1)) if ms else 100
+    if scale > 0 and scale != 100:
+        level = int(round(level * 100.0 / scale))
+    st = _BAT_STATUS_RE.search(text)
+    if st:
+        charging = int(st.group(1)) in (2, 5)
+    else:
+        charging = bool(_POWERED_RE.search(text))
+    return max(0, min(100, level)), charging
+
+
+def _read_battery(serial):
+    """读一台设备的电量，返回 (level, charging) 或 None。
+
+    与 device_pool.refresh_model 同思路：IP:5555 设备走本机 adb server；
+    USB 设备本机看不到，再走 220 远程 adb server 兜底。
+    """
+    out = ""
+    try:
+        out = _adb("-s", serial, "shell", "dumpsys", "battery", timeout=_READ_TIMEOUT)
+    except Exception:
+        out = ""
+    if not out and ":" not in serial:
+        try:
+            out = _adb_remote(USB_ADB_HOST, USB_ADB_PORT, "-s", serial,
+                              "shell", "dumpsys", "battery")
+        except Exception:
+            out = ""
+    return _parse_battery(out)
+
+
+# ================== 告警（档位状态沿） ==================
+def _tier_of(level, charging, spec, prev):
+    """电量档位：0 正常 / 1 低 / 2 严重。
+
+    充电中（且配了「充电中不告警」）直接算 0——正在补电就不用管它。
+    回升要越过 low+HYSTERESIS 才回 0，避免在阈值上下反复告警。
+    """
+    if spec["skip_charging"] and charging:
+        return 0
+    if level <= spec["critical"]:
+        return 2
+    if level <= spec["low"]:
+        return 1
+    if level >= spec["low"] + HYSTERESIS:
+        return 0
+    return prev          # 迟滞带内：维持原档位（不报也不恢复）
+
+
+def _check_alerts(serial, level, charging, spec, dname, model):
+    """比上一轮档位，决定是否发通知。只在档位变化/到重复提醒点时发。"""
+    now = time.time()
+    with _lock:
+        st = _tiers.setdefault(serial, {"tier": 0, "at": 0.0})
+        prev = st["tier"]
+        tier = _tier_of(level, charging, spec, prev)
+        # 掉档（正常→低→严重）立刻报；同一档位停留太久到重复提醒间隔再报一次
+        fire = tier > prev or (tier > 0 and now - st["at"] >= RE_NOTIFY_S)
+        if fire:
+            st["tier"], st["at"] = tier, now
+        recovered = prev > 0 and tier == 0
+        if recovered:
+            st["tier"], st["at"] = 0, now
+    if fire:
+        notifier.notify(
+            "device.battery.low", serial=serial, device_name=dname, model=model,
+            battery=level, charging=charging,
+            threshold=spec["critical"] if tier == 2 else spec["low"],
+            level="error" if tier == 2 else "warning")
+    if recovered:
+        notifier.notify(
+            "device.battery.recovered", serial=serial, device_name=dname,
+            model=model, battery=level, charging=charging, threshold=spec["low"])
+
+
+# ================== 一轮全量采集 ==================
+def _scan_all():
+    """采集池内所有在线设备的电量（后台线程执行）。
+
+    读失败的设备（离线/超时）**保持上一次的读数不动**——大屏上显示的是
+    "最后一次知道的电量"，比直接变成空白有用。
+    """
+    global _scanning, _last_scan
+    if _scanning:
+        return
+    _scanning = True
+    try:
+        spec = get_settings()
+        try:
+            online = list(device_pool.list_online())
+        except Exception as e:
+            _log.warning(f"电量采集: 获取在线设备失败: {e}")
+            return
+        if not online:
+            _last_scan = (time.strftime("%H:%M:%S"), 0, 0)
+            return
+        # 设备名/型号：通知里要显示「A08（Redmi K40）」而不是一串 IP
+        names, models, known = {}, {}, set()
+        try:
+            for d in device_pool.list_devices():
+                s = d.get("serial") or ""
+                if not s:
+                    continue
+                known.add(s)
+                names[s] = d.get("name") or ""
+                models[s] = d.get("model") or ""
+        except Exception:
+            pass
+
+        # 只采集「设备池 ∩ 在线」：平台管的是设备池（与 list_ready 同口径），
+        # 池外的设备不上大屏、也不告警——adb 里能看到但不归平台管的设备不该吵人。
+        # known 为空 = 设备表没读到（不能因此整轮不采），退回按在线设备采。
+        targets = [s for s in online if s in known] if known else list(online)
+        if not targets:
+            _last_scan = (time.strftime("%H:%M:%S"), 0, 0)
+            return
+
+        results = {}
+        try:
+            with ThreadPoolExecutor(max_workers=min(10, len(targets))) as pool:
+                futures = {pool.submit(_read_battery, s): s for s in targets}
+                for fut in as_completed(futures, timeout=_READ_TIMEOUT + 15):
+                    s = futures[fut]
+                    try:
+                        results[s] = fut.result()
+                    except Exception:
+                        results[s] = None
+        except Exception as e:
+            _log.warning(f"电量采集: 部分设备读取超时（保留已取到的）: {e}")
+
+        now = time.time()
+        with _lock:
+            for s, r in results.items():
+                if r:
+                    _cache[s] = {"level": r[0], "charging": r[1], "at": now}
+            # 设备已从池里删除的，连缓存一起清掉（避免大屏上冒出幽灵设备）。
+            # ⚠️ 只在真的读到设备清单时才清理：list_devices 失败时 known 是空的，
+            # 照清下去会把整份缓存抹掉、大屏全体变「—」。
+            if known:
+                for s in [k for k in _cache if k not in known]:
+                    _cache.pop(s, None)
+                    _tiers.pop(s, None)
+
+        for s, r in results.items():
+            if r:
+                _check_alerts(s, r[0], r[1], spec, names.get(s, ""), models.get(s, ""))
+
+        ok = sum(1 for r in results.values() if r)
+        _last_scan = (time.strftime("%H:%M:%S"), ok, len(targets))
+        _log.info(f"电量采集完成: {ok}/{len(targets)} 台（池内在线；adb 可见 {len(online)} 台）")
+    except Exception as e:
+        _log.warning(f"电量采集异常: {e}")
+    finally:
+        _scanning = False
+
+
+def scan_once():
+    """手动触发一轮采集（后台线程执行，不阻塞调用者）。返回是否已启动。
+
+    不看 enabled 开关：用户点了「立即采集」就应该采，开关只管定时循环。
+    """
+    if _scanning:
+        return False
+    threading.Thread(target=_scan_all, name="battery-scan-once", daemon=True).start()
+    return True
+
+
+# ================== 对外读取 ==================
+def get(serial):
+    """设备电量快照（供 /api/status 组装）或 None。
+
+    结构 {"level": int, "charging": bool, "at": ts, "tier": 0|1|2}。
+    **带上 tier 是刻意的**：前端只按档位上色，不在 JS 里重算阈值——
+    否则「工具 → 设备发现」改了阈值，大屏/监控页的判定就和告警对不上了。
+    """
+    with _lock:
+        v = _cache.get(serial)
+        if not v:
+            return None
+        out = dict(v)
+        st = _tiers.get(serial)
+        out["tier"] = st["tier"] if st else 0
+        return out
+
+
+def get_status():
+    """采集器状态（面板显示用）。"""
+    with _lock:
+        cached = len(_cache)
+    return {
+        "settings": get_settings(),
+        "scanning": _scanning,
+        "last_scan": _last_scan,
+        "cached": cached,
+    }
+
+
+# ================== 定时采集线程 ==================
+def _battery_loop():
+    """定时采集 daemon 线程。每轮重读配置（开关/间隔即时生效）。
+
+    启动先等 20s：让开 web_server 的预连接与型号采集（都抢 adb）。
+    等待用 15s 切片，关停/改间隔 ≤15s 生效。
+    """
+    try:
+        _stop_event.wait(20)
+        while not _stop_event.is_set():
+            interval = 60
+            try:
+                spec = get_settings()
+                interval = max(30, int(spec.get("interval", 60)))
+                if spec.get("enabled"):
+                    _scan_all()
+            except Exception as e:
+                _log.warning(f"电量定时采集异常: {e}")
+            waited = 0
+            while waited < interval and not _stop_event.is_set():
+                _stop_event.wait(min(15, interval - waited))
+                waited += min(15, interval - waited)
+    except Exception:
+        pass
+
+
+def init_app(app):
+    """web_server 启动时调用：绑 app + 起定时采集 daemon 线程。"""
+    global _app
+    _app = app
+    _stop_event.clear()
+    t = threading.Thread(target=_battery_loop, name="device-battery", daemon=True)
+    t.start()
+    _log.info("设备电量采集线程已启动（默认 60s 一次）")
+
+
+def shutdown():
+    """优雅退出：置 stop_event，等待中的循环在切片边界退出。"""
+    _stop_event.set()

core/device_pool.py

@@ -39,13 +39,59 @@ def init_app(app):
     并后台刷新一次设备型号（首次启动/设备更换后型号可能变化）。"""
     global _app
     _app = app
+    refresh_names()          # 同步刷一次名称快照，让通知从第一条起就有名字
     try:
         t = threading.Thread(target=_refresh_models_bg, daemon=True)
         t.start()
+        t2 = threading.Thread(target=_names_loop, name="device-names", daemon=True)
+        t2.start()
     except Exception:
         pass
 
 
+# ================== 名称内存快照（给通知用） ==================
+# 为什么单独存一份：webhook 通知里要显示"是哪台设备"（A08）而不是地址（IP），
+# 但 `notifier.notify()` 有一条硬红线——**零 DB 访问**（不能为了取个名字去查库，
+# 更不能在业务线程里阻塞）。所以由这里维护一份 serial→名称 的内存快照：
+# 启动刷一次、池子有变动时刷一次、再兜底每 60s 刷一次（覆盖整库恢复等外部改动）。
+_names = {}
+_names_lock = threading.Lock()
+_NAMES_INTERVAL = 60
+
+
+def refresh_names():
+    """把设备池的 serial→名称刷进内存快照（只查库，不碰 adb）。返回条数。"""
+    try:
+        rows = list_devices()
+    except Exception as e:
+        _log.debug(f"刷新设备名快照失败: {e}")
+        return 0
+    m = {}
+    for d in rows:
+        s = d.get("serial") or ""
+        if s:
+            m[s] = d.get("name") or ""
+    with _names_lock:
+        _names.clear()
+        _names.update(m)
+    return len(m)
+
+
+def name_of(serial):
+    """serial 对应的设备名称（**纯内存，可在通知路径上调用**）。没有则返回 ""。"""
+    if not serial:
+        return ""
+    with _names_lock:
+        return _names.get(str(serial), "")
+
+
+def _names_loop():
+    """兜底定时刷新名称快照（覆盖整库恢复这类进程外改动）。"""
+    while True:
+        time.sleep(_NAMES_INTERVAL)
+        refresh_names()
+
+
 def _refresh_models_bg():
     """后台批量采集在线设备型号（启动时/手动触发）。失败静默，不影响启动。"""
     time.sleep(3)  # 等服务起来再查
@@ -78,6 +124,33 @@ def list_devices():
         return [d.to_dict() for d in Device.query.order_by(Device.serial).all()]
 
 
+def serial_of(device_name):
+    """设备名 → **当前**地址（拿不到返回空串）。
+
+    从已删掉的 `core/ledger.py` 迁过来的（账号台账停用后，那边只剩这一个函数还有用 ——
+    它跟账号无关，只做"设备名 ↔ 地址"）。
+
+    ⚠ 为什么不能直接用计划行里的 `serial` 快照：设备地址会变（换 IP、重连）。
+    快照是"录入时"的值，久了就是错的 —— 要下发操作（推视频等）时必须现查。
+    优先设备池的**内存快照**（零 DB、已经是刷新过的），再退回 DB。
+    """
+    name = (device_name or "").strip()
+    if not name:
+        return ""
+    try:
+        for d in list_devices():
+            if (d.get("name") or "") == name:
+                return d.get("serial") or ""
+    except Exception:
+        pass
+    try:
+        with _ctx():
+            dev = Device.query.filter(Device.name == name).first()
+            return (dev.serial if dev else "") or ""
+    except Exception:
+        return ""
+
+
 # ================== 在线状态 ==================
 def list_online():
     """本机 adb 中 state=device 的设备 + 池内 USB 设备（经 220 远程 adb server）。
@@ -183,6 +256,7 @@ def _move_device_row(old, new_serial, fingerprint=""):
     if fingerprint:
         old.fingerprint = fingerprint
     db.session.commit()
+    refresh_names()          # 键变了（serial → 名称的映射也跟着变）
     if _move_hook is not None:
         try:
             _move_hook(old_serial, new_serial)
@@ -255,11 +329,13 @@ def add_device(serial, name="", note="", enabled=True, fingerprint=""):
             if fingerprint:
                 d.fingerprint = fingerprint
             db.session.commit()
+            refresh_names()          # 名字可能改了：通知里要立刻用新名字
             return False
         db.session.add(Device(serial=serial, name=name or "", note=note or "",
                               enabled=enabled, fingerprint=fingerprint or "",
                               created_at=time.strftime("%Y-%m-%d %H:%M")))
         db.session.commit()
+        refresh_names()
         _log.info(f"设备池新增设备: {serial}")
         return True
 
@@ -274,6 +350,7 @@ def rename_device(serial, name):
         old = d.name or ""
         d.name = name
         db.session.commit()
+        refresh_names()
         _log.info(f"设备池重命名: {old or serial} → {name}（{serial}）")
         return True
 
@@ -301,6 +378,7 @@ def remove_device(serial):
             return False
         db.session.delete(d)
         db.session.commit()
+        refresh_names()
         _log.info(f"设备池删除设备: {serial}")
         return True
 

core/device_worker.py

@@ -275,10 +275,13 @@ class BaseWorker(threading.Thread):
       其他异常           — 可重试
     """
 
-    def __init__(self, serial, params=None, daemon=True):
+    def __init__(self, serial, params=None, daemon=True, ctx=None):
         super().__init__(daemon=daemon)
         self.serial = serial
         self.params = params or {}
+        # 本次运行的上下文（run_id / job_id / job_name / device_name），由
+        # TaskManager 传入，供步骤明细等"结构化记录"标注来源。可空。
+        self.ctx = dict(ctx or {})
         self._stop_flag = threading.Event()
         self.d = None  # u2.Device，run_task 里用
         # 通用进度字段（子类通过 set_progress 上报）

core/gesture.py

@@ -0,0 +1,276 @@
+"""录制手势：**纯录制、纯回放**——录下真实手指的轨迹与时间，回放时一模一样地重放。
+
+和「滑动」步骤的区别（这是两套东西，别混）：
+
+| | `swipe` 步骤 | `gesture` 步骤（本模块） |
+|---|---|---|
+| 内容 | 方向 + 幅度 + 时长区间 | **完整轨迹点列** `[[x, y, t_ms], ...]` |
+| 回放 | 每次重新生成（弧线/抖动/本设备手速） | **照录制的路径与时间逐点重放**，不加任何修饰 |
+| 适合 | 通用滑动，换设备也能用 | 你亲手划的、要求一模一样的手势 |
+
+两个录制来源：
+1. **手机上录**（`PhoneRecorder`）：`getevent` 读**真触屏**设备，抓的是你手指的真实轨迹
+   ——注意合成的注入事件不会出现在真触屏节点上（实测确认），所以录到的只有人手的动作；
+2. **网页上录**：看着设备画面拖鼠标，前端采样路径与时间（见 `static/admin/recorder.js`）。
+
+## 回放怎么做（实测定的，别改回去）
+
+**一次调用把整条轨迹交给设备**（`d.swipe_points(points, duration)`），不是逐点注入。
+原因：实测这台设备上**单次触摸注入 RPC ≈190ms**（`d.touch.move` 25 次平均 190ms），
+逐点回放 20 个点要 3.8 秒——比录的手势慢一个数量级，根本不能用。所以只能让设备
+自己去插值：`swipe_points` 内部按 `steps = duration/0.005` 在轨迹上均匀推进，
+手势的真实速度由设备端决定。
+
+拿到"时间"靠的是**点密度**：手指慢的地方采样点天然更密（单位长度上点更多），
+无论设备是按弧长均匀插值还是按段均匀插值，"点密的段落走得更久"都成立
+——所以把**录制的原始点 + 录制总时长**一起交给设备，速度曲线就能大致还原。
+"""
+import re
+import subprocess
+import threading
+import time
+
+from core.adb_helper import ADB_PATH
+from core.logger import get_logger
+
+_log = get_logger("core.gesture")
+
+# 采样下限：手指在 16ms 内位移极小，比这更密的点只增加注入次数与延迟误差
+MIN_GAP_MS = 16
+MAX_POINTS = 240          # 单条手势的点数上限（约 4s @60Hz，够用且不让步骤 JSON 膨胀）
+MAX_REPLAY_POINTS = 40    # 回放时最多发给设备多少个点（实测每点开销大，40 点是画质/耗时折中）
+MIN_POINTS = 2
+
+# getevent -lt 的行： [   12345.678901] EV_ABS       ABS_MT_POSITION_X    000003e8
+# 第 4 列不能限定十六进制：BTN_TOUCH 的值是 DOWN/UP 这类**键名**（含非十六进制字母），
+# 限定 [0-9a-fA-F]+ 会让这些行整个被跳过 → 老协议解析不出任何手势
+_LINE_RE = re.compile(r"\[\s*([\d.]+)\]\s+(\S+)\s+(\S+)\s+(\S+)")
+
+# "像真触屏"的设备名特征（先挑这些）；明显是合成/虚拟的一律排除
+_TOUCH_HINTS = ("ts", "touch", "goodix", "fts", "synaptics", "novatek", "himax", "sec_touch")
+_VIRTUAL_HINTS = ("uinput", "virtual", "vitural", "sar", "gpio", "pon", "jack", "button")
+
+
+# ================== 点列处理 ==================
+
+def clean_points(points, min_gap_ms=MIN_GAP_MS, max_points=MAX_POINTS):
+    """规范点列：丢掉过密的采样、限制总数，时间归零到第一点。
+
+    输入/输出都是 `[[x, y, t_ms], ...]`（t 为相对第一点的毫秒）。点数不足 2 返回 []。
+    """
+    pts = []
+    for p in points or []:
+        try:
+            pts.append([int(p[0]), int(p[1]), float(p[2])])
+        except (TypeError, ValueError, IndexError):
+            continue
+    if len(pts) < MIN_POINTS:
+        return []
+    out = [pts[0]]
+    for p in pts[1:-1]:
+        if (p[2] - out[-1][2]) >= min_gap_ms:
+            out.append(p)
+    # 末点**必须保留**：它决定手势收尾在哪（快划时中间点稀，终点不能跟着丢）
+    if pts[-1][:2] != out[-1][:2] or pts[-1][2] > out[-1][2]:
+        out.append(pts[-1])
+    if len(out) < MIN_POINTS:
+        return []
+    if len(out) > max_points:                         # 均匀抽稀，保住首尾
+        step = len(out) / float(max_points)
+        out = [out[min(len(out) - 1, int(i * step))] for i in range(max_points)]
+    t0 = out[0][2]
+    for p in out:
+        p[2] = int(round(p[2] - t0))
+    return out
+
+
+def duration_ms(points):
+    return int(points[-1][2]) if points else 0
+
+
+def replay(d, points, speed=1.0):
+    """按录制的轨迹与时长回放（一次调用交给设备插值）。返回发给设备的参数。
+
+    点太多会让设备端逐点开销累积（实测每个点约 1s 量级），所以超过 MAX_REPLAY_POINTS
+    就抽稀——路径形状基本不变，但快得多。首尾点一定保留。
+    """
+    pts = clean_points(points, min_gap_ms=0)          # 回放不再按时间丢点
+    if len(pts) < MIN_POINTS:
+        raise ValueError("手势点列无效（少于 2 个点）")
+    if len(pts) > MAX_REPLAY_POINTS:
+        n = MAX_REPLAY_POINTS
+        step = (len(pts) - 1) / float(n - 1)
+        pts = [pts[min(len(pts) - 1, int(round(i * step)))] for i in range(n)]
+    speed = max(0.1, float(speed or 1.0))
+    dur = max(0.05, duration_ms(pts) / 1000.0 / speed)
+    xy = [[x, y] for x, y, _ in pts]
+    try:
+        d.swipe_points(xy, dur)
+    except Exception as e:                            # 有的设备/agent 不支持多点注入
+        _log.warning("swipe_points 回放失败（%s），退回直线滑动", e)
+        d.swipe(xy[0][0], xy[0][1], xy[-1][0], xy[-1][1], dur)
+    return {"points": len(pts), "duration": round(dur, 3)}
+
+
+# ================== getevent 解析（纯函数，好单测） ==================
+
+def parse_getevent(lines, max_x, max_y, screen_w, screen_h):
+    """把 getevent 行流解析成若干条轨迹 `[[x, y, t_ms], ...]`（屏幕坐标）。
+
+    兼容两套协议：`BTN_TOUCH DOWN/UP`（老）与 `ABS_MT_TRACKING_ID`（新，-1=抬起）。
+    只认 EV_ABS 的 X/Y；Y 到达时才落一个点（X/Y 是先后到达的两个事件）。
+    """
+    strokes, cur = [], None
+    lx = ly = 0
+    t0 = None
+    for ln in lines or []:
+        m = _LINE_RE.search(ln)
+        if not m:
+            continue
+        ts, kind, code, val = float(m.group(1)), m.group(2), m.group(3), m.group(4)
+        if kind == "EV_ABS":
+            if code == "ABS_MT_POSITION_X":
+                lx = int(val, 16)
+            elif code == "ABS_MT_POSITION_Y":
+                ly = int(val, 16)
+                if cur is not None:
+                    if t0 is None:
+                        t0 = ts
+                    cur.append([lx, ly, (ts - t0) * 1000.0])
+            elif code == "ABS_MT_TRACKING_ID":
+                if val.lower().endswith("ffffffff"):     # 抬起
+                    if cur:
+                        strokes.append(cur)
+                    cur = None
+                elif cur is None:                        # 按下
+                    cur = []
+        elif kind == "EV_KEY" and code == "BTN_TOUCH":
+            if val == "DOWN":
+                if cur is None:
+                    cur = []
+            else:
+                if cur:
+                    strokes.append(cur)
+                cur = None
+    if cur:
+        strokes.append(cur)
+
+    sx = float(screen_w) / max_x if max_x else 1.0
+    sy = float(screen_h) / max_y if max_y else 1.0
+    out = []
+    for st in strokes:
+        pts = [[int(round(x * sx)), int(round(y * sy)), t] for x, y, t in st]
+        pts = clean_points(pts)
+        if len(pts) >= MIN_POINTS:
+            out.append(pts)
+    return out
+
+
+def find_touch_device(serial, screen_w=0, screen_h=0):
+    """找真触屏设备，返回 (device_path, max_x, max_y)；找不到返回 (None, 0, 0)。
+
+    设备名里带 uinput/virtual/sar/gpio 的一律排除（那些是合成输入）；
+    多个候选时优先名字像触屏的，其次挑坐标范围最接近屏幕的那个。
+    """
+    from core.adb_helper import _adb
+    out = _adb("-s", serial, "shell", "getevent -pl") or ""
+    cands, dev, name = [], None, ""
+    for ln in out.splitlines():
+        s = ln.strip()
+        if s.startswith("add device"):
+            dev, name = s.split(":", 1)[-1].strip(), ""
+        elif s.startswith("name:"):
+            name = s.split(":", 1)[1].strip().strip('"')
+        elif "ABS_MT_POSITION_X" in s or "ABS_MT_POSITION_Y" in s:
+            m = re.search(r"max (\d+)", s)
+            if not (dev and m):
+                continue
+            key = "x" if "POSITION_X" in s else "y"
+            for c in cands:
+                if c[0] == dev:
+                    c[1 if key == "x" else 2] = int(m.group(1))
+                    break
+            else:
+                mx = int(m.group(1)) if key == "x" else 0
+                my = int(m.group(1)) if key == "y" else 0
+                cands.append([dev, mx, my, name])
+    real = [c for c in cands
+            if not any(h in (c[3] or "").lower() for h in _VIRTUAL_HINTS)]
+    pool = real or cands
+    if not pool:
+        return None, 0, 0
+
+    def score(c):
+        hit = any(h in (c[3] or "").lower() for h in _TOUCH_HINTS)
+        return (0 if hit else 1, abs(c[1] - (screen_w or c[1])) + abs(c[2] - (screen_h or c[2])))
+
+    pool.sort(key=score)
+    best = pool[0]
+    _log.info(f"[{serial}] 录制用手势设备: {best[0]} ({best[3]}) {best[1]}x{best[2]}"
+              f"，候选 {[c[0] + '/' + (c[3] or '?') for c in cands]}")
+    return best[0], best[1], best[2]
+
+
+# ================== 手机端录制 ==================
+
+class PhoneRecorder:
+    """在**手机真触屏**上录手指轨迹（getevent 流式读取）。"""
+
+    def __init__(self, serial, screen_w=0, screen_h=0):
+        self.serial = serial
+        self.screen_w = int(screen_w or 0)
+        self.screen_h = int(screen_h or 0)
+        self.device = None
+        self.max_x = self.max_y = 0
+        self._proc = None
+        self._lines = []
+        self._thread = None
+        self._stop = threading.Event()
+        self._started = 0.0
+        self.error = ""
+
+    def start(self):
+        """起 getevent 子进程并开始收行。失败抛异常（调用方转成用户可读错误）。"""
+        self.device, self.max_x, self.max_y = find_touch_device(
+            self.serial, self.screen_w, self.screen_h)
+        if not self.device or not self.max_x:
+            raise RuntimeError("没找到触屏设备节点，无法在手机上录制")
+        self._proc = subprocess.Popen(
+            [ADB_PATH, "-s", self.serial, "shell", f"getevent -lt {self.device}"],
+            stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
+        self._started = time.time()
+        self._thread = threading.Thread(target=self._pump, daemon=True)
+        self._thread.start()
+        _log.info(f"[{self.serial}] 手机录制已开始（{self.device}）")
+
+    def _pump(self):
+        try:
+            for raw in iter(self._proc.stdout.readline, b""):
+                if self._stop.is_set():
+                    break
+                self._lines.append(raw.decode("utf-8", "replace").rstrip())
+                if len(self._lines) > 20000:             # 防爆：留最近 2 万行足够解析
+                    del self._lines[:5000]
+        except Exception as e:
+            self.error = f"读取事件流失败: {e}"
+
+    def stop(self):
+        """停止并返回 `[[[x,y,t_ms], ...], ...]`（每条手势一段）。"""
+        self._stop.set()
+        try:
+            if self._proc:
+                self._proc.terminate()
+                try:
+                    self._proc.wait(timeout=3)
+                except Exception:
+                    self._proc.kill()
+        except Exception:
+            pass
+        if self._thread:
+            self._thread.join(timeout=2)
+        w = self.screen_w or self.max_x
+        h = self.screen_h or self.max_y
+        gestures = parse_getevent(self._lines, self.max_x, self.max_y, w, h)
+        _log.info(f"[{self.serial}] 手机录制结束：{len(self._lines)} 行事件 → "
+                  f"{len(gestures)} 条手势（{sum(len(g) for g in gestures)} 点）")
+        return gestures

core/humanize.py

@@ -0,0 +1,186 @@
+"""拟人化操作：滑动不机械，且**每台设备有自己的手感**。
+
+分两个层次，别混在一起：
+
+1. **每次都不一样**（抖动）：起点/终点位置、滑动幅度、时长、弧线方向都随机——
+   最容易被识别的特征不是"慢"，而是"同一帧重复播放"。
+2. **每台设备稳定不同**（性格）：由 `serial` 派生一份固定的偏好（手速、幅度、
+   弧度、停顿、常用触点的横向位置）。同一台设备多次运行风格一致，不同设备之间
+   明显不同——批量跑 13 台时看起来像 13 个人各刷各的，而不是 13 台同步机器人。
+
+**性格稳定、抖动随机**，两者都由 serial 播种，不引入全局状态、不做任何 IO。
+
+性格怎么来的：`crc32(serial)` 作种子 → 几个围绕 1.0 的比例因子（见 `profile()`）。
+换设备换风格，改名字**不改**风格（按 serial 而不是设备名），换地址会换风格——
+这符合直觉：地址代表"这一台"。
+
+想手工看一眼某台设备的性格：`python -c "from core import humanize; print(humanize.profile('192.168.20.55:5555'))"`
+"""
+import random
+import time
+import zlib
+
+from core.logger import get_logger
+
+_log = get_logger("core.humanize")
+
+_PROFILE_CACHE = {}
+# serial -> (w, h, ts)：屏幕尺寸缓存（见 screen_size）
+_SIZE_CACHE = {}
+_SIZE_TTL = 120
+
+
+def profile(serial):
+    """设备性格（按 serial 缓存，恒定）。字段都是围绕 1.0 的比例因子。"""
+    key = str(serial or "")
+    p = _PROFILE_CACHE.get(key)
+    if p is not None:
+        return p
+    # 用独立的 Random 实例而不是全局 random：worker 是多线程的，全局 random 的
+    # 取值顺序会被其它线程打乱 —— 那样"每台设备的性格"就串味了
+    r = random.Random(zlib.crc32(("human:" + key).encode("utf-8")))
+    p = {
+        "speed": r.uniform(0.82, 1.32),      # <1 划得快（时长短），>1 划得慢
+        "distance": r.uniform(0.86, 1.16),   # 有人习惯一划到底，有人小步快跑
+        "curve": r.uniform(0.4, 1.6),        # 弧线弯度系数
+        "x_bias": r.uniform(-0.09, 0.09),    # 常用触点的横向偏移（屏幕宽比例）
+        "pause": r.uniform(0.80, 1.35),      # 停顿倍率（wait 步骤可选启用）
+    }
+    _PROFILE_CACHE[key] = p
+    return p
+
+
+def screen_size(d, serial=""):
+    """屏幕尺寸，带缓存。
+
+    为什么不用 `d.info`：它在部分设备上**极慢**（实测 14s，见 doc/backlog），而
+    尺寸在一次运行里根本不会变。`d.window_size()` 快得多（同设备 0.6s）。
+    缓存 120s 过期：够躲开慢调用，又能在屏幕旋转/换分辨率后自愈。
+    """
+    key = str(serial or "")
+    now = time.time()
+    hit = _SIZE_CACHE.get(key)
+    if hit and now - hit[2] < _SIZE_TTL:
+        return hit[0], hit[1]
+    try:
+        w, h = d.window_size()
+    except Exception:                      # 老 agent 没有 window_size 就退回 info
+        info = d.info
+        w, h = info["displayWidth"], info["displayHeight"]
+    w, h = int(w), int(h)
+    if w > 0 and h > 0:
+        _SIZE_CACHE[key] = (w, h, now)
+    return w, h
+
+
+def _bezier(p0, p1, p2, n):
+    """二次贝塞尔采样——手指划出来是弧线，不是尺子画的直线。"""
+    pts = []
+    for i in range(n + 1):
+        t = i / n
+        x = (1 - t) ** 2 * p0[0] + 2 * (1 - t) * t * p1[0] + t * t * p2[0]
+        y = (1 - t) ** 2 * p0[1] + 2 * (1 - t) * t * p1[1] + t * t * p2[1]
+        pts.append((int(round(x)), int(round(y))))
+    # 同样的点会连续出现（曲线很平时）——去掉，免得下发冗余坐标
+    out = [pts[0]]
+    for p in pts[1:]:
+        if p != out[-1]:
+            out.append(p)
+    return out
+
+
+def swipe(d, direction, serial="", duration_min=0.25, duration_max=0.50,
+          distance_ratio=0.6, jitter=0.15, humanize=True):
+    """按人类习惯滑一下（上/下/左/右）。
+
+    参数：
+      direction       上滑 up / 下滑 down / 左滑 left / 右滑 right
+      serial          用来取本设备的性格（不传就是"普通人"）
+      duration_min/max 手指接触屏幕的时长区间（秒），再乘本设备手速系数
+      distance_ratio  滑动幅度占屏幕高（竖滑）或宽（横滑）的比例，默认 0.6
+      jitter          抖动幅度 0~0.4：位置/幅度/时长各抖这么多；0 = 每次都一样
+      humanize        False = 退回老的直线滑动（完全规则，用于对照/排障）
+
+    返回实际参数 dict（时长/起止点），方便日志与排障。异常向上抛，由调用方兜。
+    """
+    w, h = screen_size(d, serial)
+    prof = profile(serial)
+    vertical = direction in ("up", "down")
+    j = max(0.0, min(float(jitter or 0), 0.4))
+
+    # ---- 时长：用户给的范围 × 本设备手速 × 本次抖动 ----
+    dur = random.uniform(float(duration_min), float(duration_max))
+    dur *= prof["speed"]
+    if j:
+        dur *= 1 + random.uniform(-j, j) * 0.6
+    dur = max(0.08, round(dur, 3))
+
+    # ---- 幅度与中心点 ----
+    span = (h if vertical else w) * float(distance_ratio) * prof["distance"]
+    if j:
+        span *= 1 + random.uniform(-j, j)
+    span = max(0.08, min(span, (h if vertical else w) * 0.92))
+
+    # 起点不在正中：人不会每次都在屏幕同一条线上划
+    if vertical:
+        cx = w * (0.5 + prof["x_bias"] + (random.uniform(-j, j) * 0.6 if j else 0))
+        cx = int(max(w * 0.10, min(cx, w * 0.90)))
+        cy = h * 0.5
+        if j:
+            cy += h * random.uniform(-j, j) * 0.5
+        sign = -1 if direction == "up" else 1
+        p0 = (cx, int(max(h * 0.03, min(cy - sign * span / 2, h * 0.97))))
+        p2 = (cx, int(max(h * 0.03, min(cy + sign * span / 2, h * 0.97))))
+    else:
+        cy = int(h * (0.5 + prof["x_bias"] + (random.uniform(-j, j) * 0.6 if j else 0)))
+        cy = int(max(h * 0.10, min(cy, h * 0.90)))
+        cx = w * 0.5
+        if j:
+            cx += w * random.uniform(-j, j) * 0.5
+        sign = -1 if direction == "left" else 1
+        p0 = (int(max(w * 0.03, min(cx - sign * span / 2, w * 0.97))), cy)
+        p2 = (int(max(w * 0.03, min(cx + sign * span / 2, w * 0.97))), cy)
+
+    if not humanize:
+        # 老行为：正中直线、无抖动（点与点之间由设备等分插值）
+        if vertical:
+            s, e = (0.8, 0.2) if direction == "up" else (0.2, 0.8)
+            base = (int(w * 0.5), int(h * s), int(w * 0.5), int(h * e))
+        else:
+            s, e = (0.8, 0.2) if direction == "left" else (0.2, 0.8)
+            base = (int(w * s), int(h * 0.5), int(w * e), int(h * 0.5))
+        d.swipe(*base, random.uniform(float(duration_min), float(duration_max)))
+        return {"duration": dur, "from": base[:2], "to": base[2:], "human": False}
+
+    # ---- 弧线：控制点在中点、垂直于滑动方向偏移 ----
+    amp = span * 0.05 * prof["curve"]
+    if j:
+        amp *= random.uniform(0.3, 1.0)
+        amp *= random.choice((-1, 1))                   # 这次往左弯还是往右弯
+    else:
+        # jitter=0 时不引入任何随机：弯向由设备性格决定，便于对照排障
+        amp *= -1 if prof["curve"] < 1.0 else 1
+    mx, my = (p0[0] + p2[0]) / 2, (p0[1] + p2[1]) / 2
+    if vertical:
+        ctrl = (mx + amp, my)
+    else:
+        ctrl = (mx, my + amp)
+    # 点数刻意压到 4：`swipe_points` 在慢设备上**每多一个点就多约 1s**
+    # （实测 2 点 1.4s / 6 点 6.0s / 10 点 10.6s），而设备自己会在点之间
+    # 插值 70 步，4 个点的贝塞尔已经足够弯
+    pts = _bezier(p0, ctrl, p2, 4)
+    if len(pts) < 2:                                     # 幅度太小时退化成直线
+        pts = [p0, p2]
+    try:
+        d.swipe_points([[x, y] for x, y in pts], dur)
+    except Exception as e:                               # 老设备/agent 不支持曲线就退回直线
+        _log.warning("swipe_points 不可用，退回直线滑动: %s", e)
+        d.swipe(p0[0], p0[1], p2[0], p2[1], dur)
+    return {"duration": dur, "from": p0, "to": p2, "curve": amp, "human": True}
+
+
+def pace(serial, seconds, enabled=True):
+    """按本设备节奏微调一个停顿（wait 步骤可选启用）。enabled=False 原样返回。"""
+    if not enabled:
+        return float(seconds)
+    return float(seconds) * profile(serial)["pause"]

core/logger.py

@@ -16,7 +16,9 @@
 文件按 10MB 滚动，保留 5 个历史文件。
 """
 import os
+import re
 import logging
+from collections import deque
 from logging.handlers import RotatingFileHandler
 
 _LOG_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "logs")
@@ -84,3 +86,192 @@ def log_print(msg, level="info", module="core"):
     """print 的替代品，转发到 logging。"""
     log = get_logger(module)
     getattr(log, level, log.info)(msg)
+
+
+# ================== 日志读取（「日志」页的筛选 / 下载） ==================
+#
+# 读日志的代码放这里而不是 web 层：文件命名与滚动规则归本模块管
+# （_MODULE_FILES + RotatingFileHandler 的 backupCount），**白名单校验必须和
+# 写入侧用同一份事实**，否则改了文件名就会漏掉一处，变成目录穿越。
+
+# 行格式与 _FORMAT 对应：2026-09-16 00:27:11 [INFO] [web.notify] 消息
+_LINE_RE = re.compile(r"^(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) "
+                      r"\[([A-Z]+)\] \[([^\]]*)\] ?(.*)$")
+_LEVEL_ORDER = {"DEBUG": 10, "INFO": 20, "WARNING": 30, "ERROR": 40, "CRITICAL": 50}
+
+# 单次读取的行数上限：文件本身被限在 10MB（约 10 万行），这里再兜一层，
+# 万一将来有人调大 maxBytes，也不会把内存吃爆。
+_MAX_SCAN_LINES = 500000
+
+_MODULE_LABELS = {
+    "core.log": "核心(adb/调度)",
+    "task.log": "任务执行",
+    "web.log": "Web/AI",
+    "action.log": "动作执行",
+    "notify.log": "通知发送",
+}
+
+
+def _rotation_files(base):
+    """基础名 + 磁盘上实际存在的滚动副本（core.log → core.log.1/.2…）。
+
+    RotatingFileHandler 的备份编号**越大越旧**，所以 base 最新，接着 .1/.2…
+    """
+    names = []
+    if os.path.exists(os.path.join(_LOG_DIR, base)):
+        names.append(base)
+    i = 1
+    while i <= 99 and os.path.exists(os.path.join(_LOG_DIR, f"{base}.{i}")):
+        names.append(f"{base}.{i}")
+        i += 1
+    return names
+
+
+def list_log_files():
+    """可查看的日志文件（模块文件 + 滚动历史），最近写入的排前面。
+
+    `file` 参数只能取这里的 name（白名单），杜绝 `../../` 之类的路径穿越。
+    """
+    out = []
+    for base in sorted(set(_MODULE_FILES.values())):
+        label = _MODULE_LABELS.get(base, base)
+        for name in _rotation_files(base):
+            try:
+                st = os.stat(os.path.join(_LOG_DIR, name))
+            except OSError:
+                continue
+            rotated = name != base
+            out.append({
+                "name": name,
+                "label": f"{label} · {name}" + ("（历史）" if rotated else ""),
+                "module": base,
+                "size": st.st_size,
+                "mtime": int(st.st_mtime),
+                "rotated": rotated,
+            })
+    out.sort(key=lambda f: (-f["mtime"], f["name"]))
+    return out
+
+
+def norm_ts(value, end=False):
+    """把前端的时间输入归一成 'YYYY-MM-DD HH:MM:SS'（可比字符串）。
+
+    接受 datetime-local 的 'YYYY-MM-DDTHH:MM'、'YYYY-MM-DD HH:MM' 和纯日期；
+    纯日期按整天算（end=True 取 23:59:59，否则 00:00:00）。
+    """
+    s = (value or "").strip().replace("T", " ")
+    if not s:
+        return ""
+    if len(s) == 10:                      # 只给了日期 → 按整天
+        return s + (" 23:59:59" if end else " 00:00:00")
+    if len(s) == 16:                      # YYYY-MM-DD HH:MM
+        return s + (":59" if end else ":00")
+    return s[:19]
+
+
+def _iter_filtered(fh, keyword, min_level, since, until, stats=None):
+    """逐行读文件，产出命中的 {ts, level, module, msg, cont}。
+
+    过滤口径：
+      - 时间/级别用**继承值**——续行（traceback 的缩进行等）本身没有前缀，
+        继承上一条带前缀的行，这样按 ERROR 筛选时整段堆栈不会被拆散；
+      - 关键字匹配本行原文（续行也参与），大小写不敏感。
+
+    stats（可选 dict）里回填 scanned：本次实际读了多少行（用于告诉用户
+    "是读到文件开头了，还是被行数上限截断的"）。
+    """
+    kw = (keyword or "").strip().lower()
+    floor = _LEVEL_ORDER.get((min_level or "").upper(), 0)
+    cur_ts = cur_level = cur_module = ""
+    for raw in fh:
+        if stats is not None:
+            stats["scanned"] += 1
+        line = raw.rstrip("\r\n")
+        m = _LINE_RE.match(line)
+        if m:
+            cur_ts, cur_level, cur_module, msg = m.groups()
+            cont = False
+        else:
+            # 续行（traceback、被切成多行的长消息）：沿用上一条的元信息
+            msg, cont = line, True
+        if since and (not cur_ts or cur_ts < since):
+            continue
+        if until and (not cur_ts or cur_ts > until):
+            continue
+        if floor and _LEVEL_ORDER.get(cur_level, 0) < floor:
+            continue
+        if kw and kw not in line.lower():
+            continue
+        yield {"ts": cur_ts, "level": cur_level, "module": cur_module,
+               "msg": msg, "cont": cont}
+
+
+def query_log(name, keyword="", min_level="", since="", until="",
+              limit=300, max_scan=_MAX_SCAN_LINES):
+    """取日志文件里**最近** limit 条满足条件的行。
+
+    返回 dict：
+      rows      — [{ts, level, module, msg, cont}]，保持文件原顺序（旧→新）
+      matched   — 命中总数（可能大于 len(rows)：更早的命中没返回）
+      scanned   — 实际读了多少行（达到 max_scan 说明是被上限截断的）
+      truncated — matched > len(rows)，即"还有更早的命中没显示"
+      error     — 出错时的原因（如文件不存在）
+
+    正序读整文件 + deque 保留最后 N 条：文件被 RollingFileHandler 限在 10MB
+    （约 10 万行），整读一次百毫秒级；换来的是续行能正确继承时间戳——倒着
+    读的写法在遇到 traceback 时必须把续行攒着等前面那行，容易出错。
+    """
+    # 白名单：`name` 必须来自 list_log_files()，否则一律拒绝（防目录穿越）
+    if name not in {f["name"] for f in list_log_files()}:
+        return {"rows": [], "matched": 0, "scanned": 0, "truncated": False,
+                "error": "日志文件不存在或不可读取"}
+    since, until = norm_ts(since), norm_ts(until, end=True)
+    try:
+        keep = max(1, min(int(limit or 300), 5000))
+    except (TypeError, ValueError):
+        keep = 300
+    rows, matched, stats = deque(maxlen=keep), 0, {"scanned": 0}
+    try:
+        with open(os.path.join(_LOG_DIR, name), encoding="utf-8",
+                  errors="replace") as fh:
+            for row in _iter_filtered(fh, keyword, min_level, since, until, stats):
+                matched += 1
+                rows.append(row)
+                if stats["scanned"] >= max_scan:
+                    break
+    except OSError as e:
+        return {"rows": [], "matched": 0, "scanned": 0, "truncated": False,
+                "error": f"读取失败: {e}"}
+    return {"rows": list(rows), "matched": matched, "scanned": stats["scanned"],
+            "truncated": matched > len(rows), "error": ""}
+
+
+def read_log_text(name, keyword="", min_level="", since="", until="",
+                  limit=200000):
+    """导出用的整段文本：命中行按原格式拼回去（下载按钮）。
+
+    没给任何条件时直接读整个文件（含滚动历史由调用方选定的那一个）。
+    """
+    if name not in {f["name"] for f in list_log_files()}:
+        return None, "日志文件不存在或不可读取"
+    since, until = norm_ts(since), norm_ts(until, end=True)
+    any_filter = bool((keyword or "").strip() or min_level or since or until)
+    path = os.path.join(_LOG_DIR, name)
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            if not any_filter:
+                return fh.read(), ""
+            buf, n = [], 0
+            for row in _iter_filtered(fh, keyword, min_level, since, until):
+                if row["cont"]:
+                    buf.append(row["msg"])          # 续行原样输出
+                else:
+                    buf.append(f"{row['ts']} [{row['level']}] "
+                               f"[{row['module']}] {row['msg']}")
+                n += 1
+                if n >= limit:
+                    buf.append(f"...（已达导出上限 {limit} 行，请缩小时间范围）")
+                    break
+            return "\n".join(buf) + ("\n" if buf else ""), ""
+    except OSError as e:
+        return None, f"读取失败: {e}"

core/models.py

@@ -250,6 +250,10 @@ class Device(db.Model):
     enabled = db.Column(db.Boolean, default=True)      # 是否参与调度
     note = db.Column(db.Text, default="")              # 备注
     created_at = db.Column(db.String(20), default="")  # 添加时间
+    # 上次探测到的**抖音当前登录账号名字**（「发布计划 → 一键推送（按名字找设备）」用）。
+    # 只是**缓存**：自动任务永远现场读屏幕，不读这两列（缓存旧了也不影响发布正确性）。
+    cur_account_name = db.Column(db.String(80), default="")
+    cur_name_at = db.Column(db.String(20), default="")   # 上面那个名字是什么时候读的
     # 设备指纹（ro.serialno）：识别"同一台物理设备"的稳定标识。
     # 网络设备（serial=IP:5555）换 IP 后靠它认领回原记录，名称/分组/任务引用都不丢。
     fingerprint = db.Column(db.String(120), default="")
@@ -258,7 +262,9 @@ class Device(db.Model):
         return {"serial": self.serial, "name": self.name or "",
                 "model": self.model or "", "enabled": bool(self.enabled),
                 "note": self.note or "", "created_at": self.created_at or "",
-                "fingerprint": self.fingerprint or ""}
+                "fingerprint": self.fingerprint or "",
+                "cur_account_name": self.cur_account_name or "",
+                "cur_name_at": self.cur_name_at or ""}
 
     def __repr__(self):
         return f"<Device {self.serial}>"
@@ -369,6 +375,220 @@ class DeviceInstallLog(db.Model):
     created_at = db.Column(db.String(20), default="")
 
 
+class TaskStepLog(db.Model):
+    """任务步骤明细：每一次步骤执行的落库记录（「日志 → 步骤明细」页）。
+
+    与 `logs/task.log` 的分工：文本日志是**排障时的原始现场**（什么都往里写、
+    10MB 滚动），本表是**结构化的一份**——设备/任务/步骤/结果/耗时都是列，
+    所以能按设备、任务、时间、结果过滤和统计，文本日志只能 grep。
+
+    写入方是 `core/step_log.py` 的专用写线程（异步批量落库），**任务线程不直接
+    写库**：一次运行可能上万步，每步一次 INSERT 会拖慢热路径。
+
+    保留期由 `core/step_log.py` 的清理任务控制（默认 14 天，见该模块常量）。
+    """
+    __tablename__ = "task_step_log"
+    id = db.Column(db.Integer, primary_key=True, autoincrement=True)
+    run_id = db.Column(db.String(24), default="", index=True)   # 一次运行=设备×任务×第几次尝试
+    job_id = db.Column(db.String(32), default="")
+    job_name = db.Column(db.String(120), default="")
+    serial = db.Column(db.String(120), default="")
+    device_name = db.Column(db.String(80), default="")
+    step_path = db.Column(db.String(32), default="")      # 嵌套位置，如 "2.1.3"
+    step_label = db.Column(db.String(120), default="")
+    step_type = db.Column(db.String(40), default="")      # click_el / loop / input_text …
+    selector = db.Column(db.String(300), default="")      # 元素选择器（长选择器截断）
+    result = db.Column(db.String(16), default="")         # ok/skip/miss/error/unknown/cap
+    detail = db.Column(db.String(500), default="")        # 异常消息、跳过原因等
+    duration_ms = db.Column(db.Integer, default=0)
+    created_at = db.Column(db.String(20), default="", index=True)
+
+    __table_args__ = (
+        db.Index("ix_step_log_serial_ts", "serial", "created_at"),
+        db.Index("ix_step_log_job_ts", "job_id", "created_at"),
+    )
+
+
+class DoneMark(db.Model):
+    """「已做过」账本：跨设备幂等的标记（「任务 → 去重记录」页）。
+
+    要解决的问题（用户场景）：一台手机登录多个账号、多台手机跑同一个任务，
+    任务被反复重跑（因为不知道什么时候跑完）→ 同一个号被做两次、有的号还没做。
+
+    **判据只有一条：`scope_key` 的唯一索引。**
+    多台设备可能同时判断"没做过"，"先查后插"会两台都插进去；
+    唯一索引 + `INSERT ... ON DUPLICATE KEY`/`INSERT OR IGNORE` 的**受影响行数**
+    才是原子的（见 `core/dedup.py` 的 `mark()`）。
+
+    写入方是任务步骤 `_exec_mark_done`（**成功之后才记账**）：动作失败就不记账，
+    下次重跑还会重试该设备——这是"失败不丢"的关键。
+
+    `kind` 是有效期策略（`day`/`hours`/`all`），清理时**只删 day/hours**：
+    `all` 代表"只做一次"，删掉就等于去重失效。
+    """
+    __tablename__ = "done_mark"
+    id = db.Column(db.Integer, primary_key=True, autoincrement=True)
+    scope_key = db.Column(db.String(300), unique=True)      # 幂等的全部依据（唯一索引）
+    kind = db.Column(db.String(12), default="day")          # day / hours / all
+    job_id = db.Column(db.String(32), default="", index=True)
+    job_name = db.Column(db.String(120), default="")
+    serial = db.Column(db.String(120), default="")
+    device_name = db.Column(db.String(80), default="")
+    identity = db.Column(db.String(200), default="")        # 身份值（如抖音号）
+    created_at = db.Column(db.String(20), default="", index=True)
+
+    __table_args__ = (
+        db.Index("ix_done_mark_job_ts", "job_id", "created_at"),
+    )
+
+
+class DeviceAccount(db.Model):
+    """账号台账（**2026-10-12 起已停用**：页面/接口/任务依赖全部下线，表和数据保留）。
+
+    保留模型 = 保留表和 42 行历史数据、并继续留在备份清单（`SUMMARY_TABLES` 按模型派生）——
+    停用不等于删数据（删不可逆）。新功能**不要再读写这张表**。
+    历史用途：一台设备上登录着哪些账号（「账号」页维护）。
+
+    要解决的问题（用户场景）：一台手机登好几个抖音号、十几台手机四五十个号，
+    账号信息散在一张电子表格里 —— 换 IP、加号、想查"这台登的是哪几个号"都要翻表。
+    这里把台账落进平台：web 能查能改（支持从表格粘贴导入），
+    手机端 Agent 的「身份大字页」顺带显示本机账号，任务的「条件判断」
+    也可以直接从台账取号（不用再把号一个个手写进 cmp_value）。
+
+    ⚠ **`douyin_id` 是纯号（`35377983067`），而元素原文是 `抖音号：35377983067`。**
+    - 当条件判断的**比对值**可以 ✓（运算符用「包含」，纯号是子串）
+    - **绝不能当去重身份** ✗ —— `done_mark.identity` 存的是元素原文、逐字算 key，
+      格式不一致会让去重**静默失效**（见 `core/dedup.py`）。
+
+    `device_name` 是设备号（平台设备名，如 A01）；`serial` 是**录入时的地址快照**，
+    设备换 IP 或改名后，台账靠任一侧都能找回来（账号管理已停用，这列仅留作历史数据）。
+    同一抖音号不允许两条 —— 唯一性由服务层保证（号可能为空，DB 层要做
+    "部分唯一索引"三处方言适配，人工维护的几十条不值当）。
+    """
+    __tablename__ = "device_account"
+    id = db.Column(db.String(32), primary_key=True)                 # uuid 前 8 位
+    device_name = db.Column(db.String(80), default="", index=True)  # 设备号（平台设备名）
+    serial = db.Column(db.String(120), default="")                  # 录入时的地址快照
+    phone = db.Column(db.String(32), default="", index=True)        # 手机号
+    nickname = db.Column(db.String(80), default="")                 # 账号名称
+    douyin_id = db.Column(db.String(64), default="", index=True)    # 抖音号（纯号，不带前缀）
+    registered_at = db.Column(db.String(20), default="")            # 注册时间（原样存文本）
+    sim_in_device = db.Column(db.Boolean, default=False)            # 卡在机内（空=否）
+    can_post_video = db.Column(db.Boolean, default=False)           # 可发视频（空=否）
+    bio = db.Column(db.Text, default="")                            # 简介
+    note = db.Column(db.Text, default="")                           # 备注
+    created_at = db.Column(db.String(20), default="")
+    updated_at = db.Column(db.String(20), default="")
+
+    def to_dict(self):
+        return {"id": self.id, "device_name": self.device_name or "",
+                "serial": self.serial or "", "phone": self.phone or "",
+                "nickname": self.nickname or "", "douyin_id": self.douyin_id or "",
+                "registered_at": self.registered_at or "",
+                "sim_in_device": bool(self.sim_in_device),
+                "can_post_video": bool(self.can_post_video),
+                "bio": self.bio or "", "note": self.note or "",
+                "created_at": self.created_at or "", "updated_at": self.updated_at or ""}
+
+    def __repr__(self):
+        return f"<DeviceAccount {self.device_name} {self.nickname}>"
+
+
+class VideoPlan(db.Model):
+    """视频发布计划：账号 × 发布日期 × 编号 → 一个视频素材 + 一条标题 + 发布结果。
+
+    一条记录 = **一个账号在某天要发的一个视频**（素材与计划天然 1:1，所以不拆两张表；
+    但上传是分两步的 —— 先视频后标题或反过来 —— 靠 `status` 的 `pending` 态兜住）。
+
+    **状态机**（这是本表的灵魂，不要简化）：
+
+    | status | 含义 |
+    |---|---|
+    | `pending` | 有视频、还没标题 |
+    | `ready` | 素材齐，等发布日期 |
+    | `pushing` | 已原子占位，正在把视频推到手机 |
+    | `publishing` | 已推到手机，正在走抖音发布流程 |
+    | `done` | 发布成功（终态） |
+    | `failed` | 失败在 `push`/`scan` 阶段 —— 还没碰抖音，**可安全重试** |
+    | `unknown` | 失败在 `post`/`verify` 阶段 —— **可能已经发出去了，绝不自动重试**，要人工裁决 |
+    | `skipped` | 人工跳过（终态） |
+
+    ⚠ **`failed` 与 `unknown` 必须分开**：把"不知道自己发没发"混成"知道自己没发"，
+    就是重复发布的来源。`stage` 记录失败发生在哪一步，是这两者互相转换的唯一依据。
+
+    **唯一性**：`(nickname, release_date, seq)` 由服务层（`core/video_plan.py`）保证，
+    **不加 DB 唯一索引** —— `seq` 从 1 起、没有"空值"可言，做部分唯一索引要写三处方言适配
+    （见 §唯一索引那段注释与 `_ensure_unique_indexes`），收益不匹配；违反的代价只是
+    低频人工上传产生的重复行，可见、可删。
+
+    **分享链接**：发布成功后抓作品的分享链接存 `share_url` —— 平台**不长期囤视频**
+    （存不下），链接才是长期资产，也方便后续拿它去铺评论。
+    """
+    __tablename__ = "video_plan"
+    id = db.Column(db.String(32), primary_key=True)                 # uuid 前 8 位
+    account_id = db.Column(db.String(32), default="", index=True)   # 老台账账号 id（已停用，保留列）
+    phone = db.Column(db.String(32), default="", index=True)        # 老台账手机号快照（已停用，保留列）
+    device_name = db.Column(db.String(80), default="", index=True)  # 设备号快照（**已不写入**；实际由谁发的看 posted_device_name）
+    nickname = db.Column(db.String(80), default="")                 # **识别键**：上传文件名里的名字（= 抖音昵称）
+    douyin_id = db.Column(db.String(64), default="")                # 抖音号快照（已停用，保留列）
+    serial = db.Column(db.String(120), default="")                  # 地址快照（已停用，保留列）
+    release_date = db.Column(db.String(10), default="", index=True)  # "YYYY-MM-DD"（纯日期，等值比较）
+    seq = db.Column(db.Integer, default=1)                          # 编号，从 1 起（不用 0 表示"无"）
+    seq_auto = db.Column(db.Boolean, default=True)                  # 编号是自动分配出来的（界面要提示）
+    title = db.Column(db.Text, default="")                          # 标题（抖音发布页的「标题」框）
+    body = db.Column(db.Text, default="")                           # 正文/文案（发布页的文案框；标题 txt 里用 || 分隔）
+    video_file = db.Column(db.String(120), default="")              # 平台落盘文件名（不含绝对路径）
+    video_name = db.Column(db.String(200), default="")              # 原始上传名（排查用）
+    video_size = db.Column(db.Integer, default=0)
+    video_sha1 = db.Column(db.String(40), default="")               # 内容指纹（重复上传的判据）
+    status = db.Column(db.String(16), default="", index=True)
+    stage = db.Column(db.String(16), default="")                    # push/scan/post/verify（决定 failed vs unknown）
+    attempts = db.Column(db.Integer, default=0)                     # 尝试次数（超上限不再自动取）
+    published_at = db.Column(db.String(20), default="")
+    share_url = db.Column(db.String(300), default="")               # 作品分享链接（发布后抓取）
+    link_at = db.Column(db.String(20), default="")                  # 抓到链接的时刻
+    video_deleted_at = db.Column(db.String(20), default="")         # 平台素材文件何时被清理
+    push_verify = db.Column(db.String(16), default="")              # 推送后的相册校验：ok=进索引 / no_index=没进 / nofile=文件不在
+    push_remote = db.Column(db.String(200), default="")             # 推到手机上的绝对路径（删它/排查用）
+    posted_serial = db.Column(db.String(120), default="")           # **实际是哪台设备发的**（地址快照）
+    posted_device_name = db.Column(db.String(80), default="")       # **实际是哪台设备发的**（设备名，界面显示用）
+    last_error = db.Column(db.String(500), default="")
+    note = db.Column(db.Text, default="")
+    created_at = db.Column(db.String(20), default="", index=True)
+    updated_at = db.Column(db.String(20), default="")
+
+    __table_args__ = (
+        db.Index("ix_video_plan_date_status", "release_date", "status"),
+        db.Index("ix_video_plan_acct_date", "account_id", "release_date"),
+        db.Index("ix_video_plan_phone_slot", "phone", "release_date", "seq"),
+        db.Index("ix_video_plan_file", "video_file"),
+        # 主查询路径（按名字取待发计划/查重）——老库靠 _ensure_plain_indexes 补建
+        db.Index("ix_video_plan_name_date", "nickname", "release_date"),
+    )
+
+    def to_dict(self):
+        return {"id": self.id, "account_id": self.account_id or "",
+                "phone": self.phone or "", "device_name": self.device_name or "",
+                "nickname": self.nickname or "", "douyin_id": self.douyin_id or "",
+                "serial": self.serial or "", "release_date": self.release_date or "",
+                "seq": int(self.seq or 1), "seq_auto": bool(self.seq_auto),
+                "title": self.title or "", "body": self.body or "",
+                "video_file": self.video_file or "",
+                "video_name": self.video_name or "", "video_size": int(self.video_size or 0),
+                "video_sha1": self.video_sha1 or "", "status": self.status or "",
+                "stage": self.stage or "", "attempts": int(self.attempts or 0),
+                "published_at": self.published_at or "", "share_url": self.share_url or "",
+                "link_at": self.link_at or "", "video_deleted_at": self.video_deleted_at or "",
+                "push_verify": self.push_verify or "", "push_remote": self.push_remote or "",
+                "posted_serial": self.posted_serial or "",
+                "posted_device_name": self.posted_device_name or "",
+                "last_error": self.last_error or "", "note": self.note or "",
+                "created_at": self.created_at or "", "updated_at": self.updated_at or ""}
+
+    def __repr__(self):
+        return f"<VideoPlan {self.phone} {self.release_date} #{self.seq} {self.status}>"
+
+
 class AgentConversation(db.Model):
     """AI 控制台会话：整个消息序列以 JSON 存在一行里（单会话几十 KB，够用）。"""
     __tablename__ = "agent_conversation"
@@ -393,6 +613,16 @@ SCHEMA_MIGRATIONS = [
     (4, "自动发现：pending_device 待连接池表（扫描发现的设备，用户确认后才入正式池）", None),
     (5, "设备池：device 表新增 fingerprint 列（设备指纹 ro.serialno，换 IP 后认领回原记录）", None),
     (6, "自动发现：pending_device 表新增 fingerprint 列（扫描时读取，用于提示是已有设备换了 IP）", None),
+    (7, "去重账本：done_mark 表（跨设备幂等的「已做过」标记，唯一索引 scope_key）", None),
+    (8, "账号台账：device_account 表（设备号/手机号/账号名称/抖音号/注册时间/卡在机内/可发视频/简介/备注）", None),
+    (9, "视频发布计划：video_plan 表（账号×发布日期×编号 → 素材 + 标题 + 发布状态 + 分享链接）", None),
+    (10, "视频发布计划：video_plan 新增 push_verify（推送后相册校验：ok/no_index/nofile）"
+         "与 push_remote（手机上的绝对路径，删它/排查用）", None),
+    (11, "视频发布计划：video_plan 新增 body（正文）—— 标题 txt 一行里用 || 分隔「标题 || 正文」", None),
+    (12, "发布计划按名字发：计划行以 nickname 为识别键，新增 posted_serial/posted_device_name"
+         "（**实际是哪台设备发的**）；账号台账（device_account）停用但表与数据保留", None),
+    (13, "按名字找设备：device 表新增 cur_account_name/cur_name_at"
+         "（上次探测到的抖音当前账号名字，仅供人工入口做设备建议）", None),
 ]
 
 # 当前 schema 版本（备份/恢复用它判断新旧，也写进 app_meta.schema_version）
@@ -423,13 +653,20 @@ _MYSQL_UNIQUE_INDEXES = (
     ("ux_device_fingerprint", "device", "fingerprint_uq"),
 )
 
+# 普通索引：模型里已经声明了（`__table_args__`），但那对**已有表**不生效 ——
+# `create_all` 只建缺的表，不补已有表的新索引。这里按名字查了再建，老库升级也能有。
+_PLAIN_INDEXES = (
+    ("ix_video_plan_name_date", "video_plan", "nickname, release_date"),
+)
+
 
 def init_db(app):
     """在 Flask app context 里初始化数据库 + 创建默认管理员。
 
     web_server 启动时调用。自动迁移旧 groups.json/jobs.json 到数据库。
 
-    顺序：建表（create_all）→ 补列（_sync_columns）→ 版本账本 → 唯一索引 → 管理员/旧 JSON。
+    顺序：建表（create_all）→ 补列（_sync_columns）→ 版本账本 → 唯一索引 → 普通索引
+          → 管理员/旧 JSON。
     建表与补列都以模型定义为准，SQLite / MySQL 两种方言自动匹配，不再手写 DDL。
     """
     db.init_app(app)
@@ -438,6 +675,7 @@ def init_db(app):
         _sync_columns()
         _migrate_schema()
         _ensure_unique_indexes()
+        _ensure_plain_indexes()
         _ensure_default_admin()
         _migrate_old_json()
 
@@ -570,6 +808,26 @@ def _ensure_unique_indexes_mysql():
             _log.warning(f"唯一索引 {name} 创建失败（历史数据可能有重复）: {e}")
 
 
+def _ensure_plain_indexes():
+    """补建模型里声明、但已有表上还没有的普通索引（幂等）。
+
+    SQLite / MySQL 都能跑同一条 `CREATE INDEX`（MySQL 5.7 没有 `IF NOT EXISTS`，
+    所以先 inspect 查名字再建，不靠方言特有能力）。
+    """
+    from sqlalchemy import inspect
+    for name, table, cols in _PLAIN_INDEXES:
+        try:
+            have = {i["name"] for i in inspect(db.engine).get_indexes(table)}
+            if name in have:
+                continue
+            db.session.execute(text("CREATE INDEX {} ON {}({})".format(name, table, cols)))
+            db.session.commit()
+            _log.info(f"已建索引 {name}")
+        except Exception as e:
+            db.session.rollback()
+            _log.warning(f"索引 {name} 创建失败（不阻塞启动）: {e}")
+
+
 def _ensure_default_admin():
     """首次启动创建默认管理员 admin/admin123。"""
     if not User.query.filter_by(username="admin").first():

core/notifier.py

@@ -310,10 +310,15 @@ _LEVEL_BY_HINT = (
 )
 
 
-def _level_of(event_key):
-    for hints, lv in _LEVEL_BY_HINT:
+def _level_of(event_key, fields=None):
+    """消息级别：**事件自己带的 `level` 优先**（步骤「发通知」/巡检都能自己选），
+    否则按事件 key 猜（failed→error、success→success…），猜不到算 info。"""
+    lv = (fields or {}).get("level")
+    if lv in ("info", "success", "warning", "error"):
+        return lv
+    for hints, lv2 in _LEVEL_BY_HINT:
         if any(h in event_key for h in hints):
-            return lv
+            return lv2
     return "info"
 
 
@@ -329,8 +334,12 @@ _FIELD_LABELS = {
     "error_msg": "错误", "count": "数量", "serials": "设备", "devices": "设备",
     "pairs": "认领", "target": "目标", "selector": "选择器", "miss_count": "连续未命中",
     "timeout_s": "超时(秒)", "task_job": "原任务", "model": "型号",
+    "battery": "电量(%)", "threshold": "告警阈值(%)", "charging": "充电中",
     "apk_name": "应用", "apk_id": "应用ID", "package_name": "包名",
     "success": "成功", "failed": "失败", "skipped": "跳过", "total": "总数",
+    "title": "标题", "message": "内容", "patrol_name": "巡检",
+    "check_label": "检查", "action_label": "动作", "detail": "结果",
+    "stopped": "停止", "failed_devices": "失败设备",
     "failed_items": "失败明细", "filename": "文件", "size": "大小(字节)",
     "tables": "表数", "include_apk": "含APK", "user": "操作人", "operator": "操作人",
     "env": "环境", "db_target": "数据库", "device_count": "设备数",
@@ -348,8 +357,57 @@ def _label(k):
     return _FIELD_LABELS.get(k, k)
 
 
+# ================== 设备名解析（让通知显示名字而不是 IP） ==================
+# 由装配层注册（web_server.py）：`notifier.set_device_name_resolver(device_pool.name_of)`。
+# **刻意做成"纯内存回调"**：notify() 的红线是零 DB——不能为了取个名字去查库。
+# 快照由 device_pool 维护（启动/池子变动/每 60s 兜底刷新）。
+_device_name_fn = None
+
+
+def set_device_name_resolver(fn):
+    """注册 serial → 设备名 的解析器。必须是**纯内存**实现（不得查库/发请求）。"""
+    global _device_name_fn
+    _device_name_fn = fn
+
+
+def _dev_name(serial):
+    """尽力把地址解析成设备名；解析不到返回 ""（调用方保留原值）。"""
+    if not serial or _device_name_fn is None:
+        return ""
+    try:
+        return str(_device_name_fn(str(serial)) or "")
+    except Exception:
+        return ""
+
+
+def fill_device_names(fields):
+    """把 fields 里的设备地址补成设备名（**原地改**，返回同一个 dict）。
+
+    两类字段：
+      · `serial` → 补 `device_name`（原来没填才补）——标题主体、字段表、
+        聚合样本认的都是 `device_name`，补上这一处就全带名字了；
+      · `serials` / `devices`（多设备事件，如设备断联）→ 逐项换成名字，
+        通知里不该出现一串 IP。
+    查不到名字（设备没命名 / 已不在池里）就**保留原值**，绝不把内容弄丢。
+    """
+    if not isinstance(fields, dict):
+        return fields
+    s = fields.get("serial")
+    if s and not fields.get("device_name"):
+        n = _dev_name(s)
+        if n:
+            fields["device_name"] = n
+    for k in ("serials", "devices"):
+        v = fields.get(k)
+        if isinstance(v, (list, tuple)) and v:
+            fields[k] = [_dev_name(x) or x for x in v]
+    return fields
+
+
 def _subject(ev, fields):
-    """标题主体：优先任务名，其次设备名/serial。"""
+    """标题主体：**用户自己写的 title 优先**，其次任务名，再次设备名/serial。"""
+    if fields.get("title"):
+        return str(fields["title"])
     for k in ("job_name", "apk_name", "hook_name"):
         if fields.get(k):
             return str(fields[k])
@@ -363,10 +421,13 @@ def _subject(ev, fields):
 def build_message(ev, fields, hook=None):
     """把事件渲染成统一消息体（title/summary/fields/level/markdown）。"""
     fields = dict(fields or {})
+    fill_device_names(fields)     # 同 notify()：预览/测试发送也要显示设备名
     merged = fields.pop("_merged", None)
-    level = _level_of(ev.key)
+    level = _level_of(ev.key, fields)
     subj = _subject(ev, fields)
-    title = ev.label + (f"：{subj}" if subj else "")
+    # 「发通知」步骤自带标题时**直接用它**：用户写的是"抖音号1 掉线了"，
+    # 前面再挂一个"任务自定义通知："纯属噪音（其它事件照旧带事件名）
+    title = str(fields["title"]) if fields.get("title")         else ev.label + (f"：{subj}" if subj else "")
     if merged and merged.get("merged_count", 0) > 1:
         title = f"{ev.label}：{subj}" if subj else ev.label
         title += f"（{merged['merged_count']} 次）"
@@ -379,13 +440,25 @@ def build_message(ev, fields, hook=None):
         v = fields.get(k)
         if v in (None, "", [], {}):
             continue
+        # 标题里已经写出来的主体（任务名/设备名）不再重复占一行：
+        # "任务批次结束：抖音养号" 下面再来一行 "任务：抖音养号" 是纯噪音
+        if k in ("job_name", "device_name", "apk_name", "hook_name", "title") \
+                and str(v) == str(subj):
+            continue
+        # 设备名优先：两个都带时只显示名字——IP 是给日志看的，通知里没人想读地址
+        if k == "serial" and fields.get("device_name"):
+            continue
         if isinstance(v, (list, tuple)):
             v = "、".join(str(x) for x in list(v)[:6]) + ("…" if len(v) > 6 else "")
         elif isinstance(v, dict):
             v = json.dumps(v, ensure_ascii=False)[:200]
         rows.append((_label(k), str(v)[:400]))
-    if merged and merged.get("samples"):
-        rows.append(("样本", "；".join(merged["samples"][:3])))
+    # 样本只在**真的合并了多条**时才有意义：合并 1 条时样本就是标题主体本身
+    if merged and merged.get("merged_count", 0) > 1:
+        samples = [s for s in (merged.get("samples") or [])[:3]
+                   if s and str(s) != str(subj)]
+        if samples:
+            rows.append(("样本", "；".join(samples)))
     if merged and merged.get("folded"):
         rows.append(("限流折叠", f"另有 {merged['folded']} 条被限流折叠"))
 
@@ -913,7 +986,16 @@ def _dispatcher_loop():
 
 
 def _sample(ev, fields):
-    subj = _subject(ev, fields)
+    """聚合样本：一句话说明"合并进来的是哪几条"。
+
+    **优先设备维度**（与标题相反）：聚合键是 job_id 时，合并的是"同一任务的多台
+    设备"，样本再写任务名就每条都一样（标题里已经有了），写设备名才看得出是哪几台。
+    """
+    subj = ""
+    for k in ("device_name", "serial", "job_name", "apk_name", "hook_name"):
+        if fields.get(k):
+            subj = str(fields[k])
+            break
     reason = fields.get("cause") or fields.get("error") or fields.get("error_msg") or ""
     return f"{subj}{' · ' + str(reason)[:40] if reason else ''}"
 
@@ -974,11 +1056,16 @@ def notify(event, **fields):
                                                  for p in h["events"])]
         if not hooks:
             return
+        fill_device_names(fields)   # 地址 → 设备名（纯内存快照，不查库）
         for h in hooks:
             keys = tuple(str(fields.get(k, "")) for k in (ev.agg_key or ()))
+            # 聚合窗口：事件自己声明「立即发」（agg_window=0，低频高危事件，如批次结束 /
+            # 服务启停 / 备份恢复）时**不受 hook 窗口影响**——否则白等一个窗口，还会
+            # 挂上一行毫无信息量的「样本」（单条事件的样本＝标题主体，纯重复）。
+            # 其余事件听 hook 的：那个值表达的是"这个群最多等多久合并"。
+            window = 0 if ev.agg_window == 0 else int(h.get("agg_window") or 0)
             try:
-                _event_q.put_nowait((h["id"], event, dict(fields), keys,
-                                     int(h.get("agg_window") or 0)))
+                _event_q.put_nowait((h["id"], event, dict(fields), keys, window))
             except queue.Full:
                 _dropped["event_q"] += 1
     except Exception as e:      # 通知出问题绝不能影响业务

core/notify_events.py

@@ -38,8 +38,10 @@ EVENTS = [
        ["job_id", "job_name", "task_type", "device_count", "serials_preview"],
        "一次任务开始铺开到 N 台设备", agg_window=0, recommend=True),
     _e("task.batch.finished", "任务批次结束", "任务批次",
-       ["job_id", "job_name", "total", "success", "failed", "stopped", "duration_s"],
-       "整批跑完（含成功/失败/被停台数与耗时）", agg_window=0, recommend=True),
+       ["job_id", "job_name", "total", "success", "failed", "stopped", "skipped",
+        "failed_devices", "duration_s"],
+       "整批跑完（成功/失败/停止台数 + 耗时；有失败时列出失败设备与型号）",
+       agg_window=0, recommend=True),
     _e("task.batch.no_device", "任务无可用设备", "任务批次",
        ["job_id", "job_name", "target"],
        "触发时一台可用设备都没有（任务空跑）", agg_window=0, recommend=True),
@@ -52,22 +54,25 @@ EVENTS = [
 
     # ---------------- 任务 · 单设备（权威结论点） ----------------
     _e("task.device.success", "设备任务成功", "任务·单设备",
-       ["serial", "device_name", "job_id", "job_name", "attempt", "duration_s"],
-       "某台设备上的任务最终成功", agg_key=_BY_JOB, recommend=True),
+       ["serial", "device_name", "model", "job_id", "job_name", "attempt", "duration_s"],
+       "某台设备上的任务最终成功。**只在目标设备只有 1 台时发送**——多设备批次看"
+       "「任务批次结束」就够了，13 台设备就是 13 条刷屏", agg_key=_BY_JOB),
+
     _e("task.device.failed", "设备任务失败", "任务·单设备",
-       ["serial", "device_name", "job_id", "job_name", "attempts", "cause", "msg"],
-       "某台设备上的任务最终失败（带真实原因）", agg_key=_BY_JOB, recommend=True),
+       ["serial", "device_name", "model", "job_id", "job_name", "attempts",
+        "cause", "msg"],
+       "某台设备上的任务最终失败（带真实原因与型号）", agg_key=_BY_JOB, recommend=True),
     _e("task.device.offline", "设备离线放弃", "任务·单设备",
-       ["serial", "device_name", "job_id", "job_name", "error"],
+       ["serial", "device_name", "model", "job_id", "job_name", "error"],
        "设备离线，不重试直接失败", agg_key=_BY_JOB, recommend=True),
     _e("task.device.error", "单次尝试异常", "任务·单设备",
-       ["serial", "device_name", "job_name", "attempt", "error"],
+       ["serial", "device_name", "model", "job_name", "attempt", "error"],
        "某次尝试抛异常（后面还会重试，噪音较大）", agg_key=_BY_JOB),
     _e("task.device.retry", "设备任务重试", "任务·单设备",
        ["serial", "device_name", "job_name", "attempt", "next_attempt", "delay_s", "reason"],
        "即将重试", agg_key=_BY_JOB),
     _e("task.device.stopped", "设备任务被停止", "任务·单设备",
-       ["serial", "device_name", "job_name", "attempt", "phase"],
+       ["serial", "device_name", "model", "job_name", "attempt", "phase"],
        "用户手动停止 / cron 停止", agg_key=_BY_JOB),
     _e("task.device.preempted", "设备被抢占", "任务·单设备",
        ["serial", "device_name", "job_name", "preempted_job_id", "preempted_job_name"],
@@ -91,10 +96,46 @@ EVENTS = [
        "单次 attempt 抛异常"),
 
     # ---------------- 业务（任务内容） ----------------
+    _e("task.patrol.hit", "任务巡检命中", "业务",
+       ["title", "message", "patrol_name", "check_label", "detail", "action_label",
+        "job_id", "job_name", "serial", "device_name", "model"],
+       "任务里配置的「公共巡检」命中（熄屏/元素/前台…），已执行动作——"
+       "标题正文可在巡检项里自己写，支持 {device}/{job}/{time}/{app}/{screen}",
+       agg_window=0, recommend=True),
+    _e("task.notify.custom", "任务自定义通知", "业务",
+       ["title", "message", "job_id", "job_name", "serial", "device_name", "model"],
+       "任务里的「发通知」步骤被触发——标题与正文由任务自己写，支持 "
+       "{device}/{serial}/{job}/{time}/{app}/{screen} 占位符", agg_window=0,
+       recommend=True),
     _e("task.selector.invalid", "选择器连续失效", "业务",
        ["serial", "device_name", "selector", "miss_count"],
        "某选择器连续 10 次未命中——任务可能显示成功但什么都没做", agg_window=0,
        recommend=True),
+    _e("task.page.mismatch", "页面不对（校验没过）", "业务",
+       ["serial", "device_name", "model", "want", "msg"],
+       "「校验页面」步骤没等到该出现的特征元素 —— **说明上一步没生效**（没进到相册页/剪辑页等）。"
+       "默认会**跳过本轮剩余步骤**（这一条不发、换下一个号），避免在错的页面上继续盲点",
+       agg_window=0, agg_key=_BY_SERIAL, recommend=True),
+    _e("task.account.switch_failed", "切号失败", "业务",
+       ["serial", "device_name", "model", "want", "got", "attempts", "msg"],
+       "想切到某个账号但没切成功（列表里找不到这个名字，或切完读回来的还是别人）——"
+       "**本次不会发这个号的内容**。请人工到设备上确认这个号还在不在抖音的账号列表里",
+       agg_window=0, agg_key=_BY_SERIAL, recommend=True),
+    _e("task.account.need_login", "需要登录/验证码", "业务",
+       ["serial", "device_name", "model", "want", "msg"],
+       "抖音停在登录页或要验证码 —— **需要人工登录**（平台绝不代替登录/过滑块），"
+       "本设备已停止本轮任务", agg_window=0, agg_key=_BY_SERIAL, recommend=True),
+    _e("task.video.published", "视频已发布", "业务",
+       ["serial", "device_name", "model", "phone", "nickname", "release_date", "seq",
+        "title", "share_url"],
+       "「发布视频」步骤把某个账号的视频发出去了（share_url 是作品分享链接，"
+       "没抓到链接时为空——界面上会标「缺链接」）", agg_window=0, recommend=True),
+    _e("task.video.failed", "视频发布失败/结果未知", "业务",
+       ["serial", "device_name", "model", "phone", "nickname", "release_date", "seq",
+        "title", "msg"],
+       "「发布视频」步骤失败：推文件阶段失败=可重试；抖音那一步失败=**可能已经发出去了**，"
+       "要到计划页看状态并人工确认（平台不会自动重发）", agg_window=0,
+       agg_key=_BY_SERIAL, recommend=True),
 
     # ---------------- 设备 ----------------
     _e("device.online", "设备恢复在线", "设备",
@@ -112,6 +153,16 @@ EVENTS = [
     _e("device.heartbeat_timeout", "心跳超时", "设备",
        ["serial", "device_name", "timeout_s", "task_job", "model"],
        "设备卡死（长时间没心跳），任务可能已中断", agg_window=0, recommend=True),
+    _e("device.battery.low", "设备电量低", "设备",
+       ["serial", "device_name", "model", "battery", "charging", "threshold"],
+       "设备电量掉到阈值以下（默认 20%，可在「工具 → 设备发现 → 电量监控」改）。"
+       "充电中的设备不报——插着充电器说明正在补电；"
+       "「插着却没充电」（劣质线/温控/满电停充）仍会报，那正是最该知道的情况",
+       agg_window=0, agg_key=_BY_SERIAL, recommend=True),
+    _e("device.battery.recovered", "设备电量已恢复", "设备",
+       ["serial", "device_name", "model", "battery", "charging", "threshold"],
+       "低电量设备重新充上电，或电量回升到阈值以上（含恢复迟滞）", agg_window=0,
+       agg_key=_BY_SERIAL),
 
     # ---------------- 应用安装 ----------------
     _e("apk.install.started", "应用安装开始", "安装",

core/patrol.py

@@ -0,0 +1,110 @@
+"""任务内**公共巡检**：任务运行期间按间隔穿插检查设备状态，命中就动作 + 通知。
+
+和步骤编辑器的关系（重要，别混）：
+
+| | 步骤（`params.steps`） | 公共巡检（`params.watchers`） |
+|---|---|---|
+| 配置位置 | 步骤画布，拖出来的 | 任务编辑器里单独一块 |
+| 执行方式 | 顺序执行 | **穿插**：每执行完一步（以及长等待的每个分片）看一眼"哪个巡检到点了" |
+| 适合什么 | 一段固定流程 | 全程都要盯的守护条件（熄屏就点亮、掉到桌面就通知） |
+
+为什么用穿插而不是另起线程：不需要并发模型，不会和主流程抢屏幕（否则巡检点屏幕、
+主流程也在点，动作会互相打断）。代价是巡检精度受步长影响——某一步卡 30 秒，
+巡检最多晚 30 秒；这也是刻意的取舍（见 doc/TASK_DEV.md §4.5）。
+
+配置结构（`params.watchers` 数组，每项）：
+
+```json
+{"name": "熄屏点亮", "enabled": true, "interval": 60,
+ "check": "screen_off",                    // 见 CHECKS
+ "selector_type": "xpath", "selector_value": "",   // 元素类检查才用
+ "action": "screen_on",                    // 见 ACTIONS
+ "notify": true, "title": "{device} 熄屏了",
+ "message": "任务 {job} 在 {time} 发现 {screen}，已点亮",
+ "cooldown": 300}                          // 命中后多久内不再重复动作/通知（防刷屏）
+```
+"""
+from core.logger import get_logger
+from core.u2_helper import screen_is_on, current_package
+
+_log = get_logger("task.generic")
+
+# 检查项：need 说明该项还要填什么（selector=元素选择器 / package=包名）
+CHECKS = {
+    "screen_off": {"label": "屏幕熄灭", "need": ""},
+    "screen_on": {"label": "屏幕亮着", "need": ""},
+    "element_exists": {"label": "元素存在", "need": "selector"},
+    "element_missing": {"label": "元素不存在", "need": "selector"},
+    "foreground_is": {"label": "前台是该App", "need": "package"},
+    "foreground_not": {"label": "前台不是该App", "need": "package"},
+}
+
+ACTIONS = {
+    "none": {"label": "只发通知，不动设备"},
+    "screen_on": {"label": "点亮屏幕"},
+    "screen_off": {"label": "熄灭屏幕"},
+    "stop_self": {"label": "停止本设备任务"},
+}
+
+# 通知正文里可用的占位符（前端提示、文档、渲染三处共用一份，避免漂移）
+PLACEHOLDERS = ("device", "serial", "job", "time", "app", "screen")
+
+
+def _element_exists(d, sel_type, sel_val):
+    """元素是否存在（不等超时，立即判定）。一次 UI dump 的代价，慢设备上可能要几秒。"""
+    if sel_type == "xpath":
+        return bool(d.xpath(sel_val).exists())
+    return bool(d(**{sel_type: sel_val}).exists())
+
+
+def evaluate(d, spec):
+    """跑一次检查，返回 (是否命中, 一句人话说明)。异常由调用方兜。"""
+    check = str(spec.get("check") or "")
+    val = str(spec.get("selector_value") or "").strip()
+
+    if check in ("screen_off", "screen_on"):
+        state = screen_is_on(d)
+        if state is None:
+            return False, "屏幕状态读不到"
+        hit = (not state) if check == "screen_off" else state
+        return hit, f"屏幕{'亮着' if state else '熄灭'}"
+
+    if check in ("element_exists", "element_missing"):
+        if not val:
+            return False, "没填选择器"
+        found = _element_exists(d, spec.get("selector_type") or "xpath", val)
+        return (found if check == "element_exists" else not found), \
+            f"元素{'存在' if found else '不存在'}"
+
+    if check in ("foreground_is", "foreground_not"):
+        if not val:
+            return False, "没填包名"
+        cur = current_package(d)
+        return (cur == val) if check == "foreground_is" else (cur != val), \
+            f"前台={cur or '未知'}"
+
+    return False, f"未知检查项 {check}"
+
+
+def act(d, spec, worker=None):
+    """执行命中后的动作，返回一句人话（没动作返回空串）。"""
+    action = str(spec.get("action") or "none")
+    if action == "screen_on":
+        d.unlock()                       # 与 screen_on 步骤同语义：唤醒 + 解锁
+        return "已点亮屏幕"
+    if action == "screen_off":
+        d.screen_off()
+        return "已熄灭屏幕"
+    if action == "stop_self":
+        if worker is not None:
+            worker.stop()                # 置停止位，主流程下一步就退出
+        return "已停止本设备任务"
+    return ""
+
+
+def check_label(check):
+    return (CHECKS.get(check) or {}).get("label", check)
+
+
+def action_label(action):
+    return (ACTIONS.get(action) or {}).get("label", action)

core/step_defaults.py

@@ -0,0 +1,148 @@
+"""步骤默认值：新建步骤时预填的参数（后台「任务 → 动作配置」页可改）。
+
+存在 `app_meta.step_defaults` 一个键里（**不建表** → 不碰备份覆盖红线），
+与 `notify_webhooks` 同一套做法：**出厂默认 + 用户覆盖**，读的时候合并。
+
+为什么是"出厂 + 覆盖"而不是只存用户值：以后调整某个步骤的出厂默认时，
+**没配过的字段**会跟着变好，**配过的字段**不动——这符合直觉。
+
+字段白名单 + 范围校验都在这里（`SPEC`）：写进库的东西必须能校验，否则手改
+JSON 塞个奇怪值进去，之后新建步骤就把它带进任务里了。
+
+⚠️ 这里只管**编辑器预填**；`tasks/generic/task.py` 的 `STEP_TYPES` 仍是执行侧
+的默认值来源（AI/MCP 造步骤也用它）。两处都改了要一起同步。
+"""
+import json
+
+# 出厂默认（前端「动作配置」页的初始内容，也是没配过时的回退）
+FACTORY = {
+    "swipe": {"direction": "up", "duration_min": 0.25, "duration_max": 0.5,
+              "distance_ratio": 0.6, "jitter": 0.15, "humanize": True},
+    "click": {"wait_timeout": 2},
+    "long_click": {"duration": 1.0, "wait_timeout": 2},
+    "wait": {"min": 1.0, "max": 3.0},
+    "key_event": {"key": "back"},
+    "input_text": {"mode": "random", "texts": "你好\n有趣\n支持",
+                   "fixed_text": "", "clear_first": True},
+}
+
+# 字段规格：("num", 最小, 最大) / ("bool",) / ("choice", 可选值) / ("text", 最大长度)
+SPEC = {
+    "swipe": {
+        "direction": ("choice", ("up", "down", "left", "right")),
+        "duration_min": ("num", 0.05, 5.0),
+        "duration_max": ("num", 0.05, 5.0),
+        "distance_ratio": ("num", 0.1, 0.9),
+        "jitter": ("num", 0.0, 0.4),
+        "humanize": ("bool",),
+    },
+    "click": {"wait_timeout": ("num", 0.0, 30.0)},
+    "long_click": {"duration": ("num", 0.2, 10.0),
+                   "wait_timeout": ("num", 0.0, 30.0)},
+    "wait": {"min": ("num", 0.1, 600.0), "max": ("num", 0.1, 600.0)},
+    "key_event": {"key": ("text", 30)},
+    "input_text": {"mode": ("choice", ("random", "fixed")),
+                   "texts": ("text", 2000), "fixed_text": ("text", 200),
+                   "clear_first": ("bool",)},
+}
+
+# 与 notifier 的键同住 app_meta（`key` 是 MySQL 保留字，读写只走 db_config.meta_get/set）
+META_KEY = "step_defaults"
+
+
+def factory():
+    """出厂默认的深拷贝（别让调用方改到常量）。"""
+    return json.loads(json.dumps(FACTORY, ensure_ascii=False))
+
+
+def _clean_one(stype, raw):
+    """校验并清洗单个步骤类型的默认值；非法字段**丢弃**（不让脏值进库）。"""
+    spec = SPEC.get(stype)
+    if not spec or not isinstance(raw, dict):
+        return None
+    out = {}
+    for k, v in raw.items():
+        rule = spec.get(k)
+        if not rule:
+            continue
+        kind = rule[0]
+        try:
+            if kind == "bool":
+                out[k] = bool(v)
+            elif kind == "num":
+                n = float(v)
+                lo, hi = rule[1], rule[2]
+                out[k] = max(lo, min(hi, n))
+            elif kind == "choice":
+                s = str(v)
+                if s in rule[1]:
+                    out[k] = s
+            elif kind == "text":
+                out[k] = str(v)[:rule[1]]
+        except (TypeError, ValueError):
+            continue
+    return out or None
+
+
+def clean(raw):
+    """清洗整份配置（只保留白名单里的步骤类型与字段）。"""
+    if not isinstance(raw, dict):
+        return {}
+    out = {}
+    for stype in SPEC:
+        got = _clean_one(stype, raw.get(stype))
+        if got:
+            out[stype] = got
+    return out
+
+
+def merged(user):
+    """出厂默认 + 用户覆盖（按字段合并）。"""
+    out = factory()
+    for stype, vals in (clean(user) or {}).items():
+        out.setdefault(stype, {}).update(vals)
+    return out
+
+
+def get():
+    """当前生效的默认值（读库，必须在 app context 内调）。"""
+    from core.db_config import meta_get
+    raw = meta_get(META_KEY) or ""
+    if not raw:
+        return factory()
+    try:
+        return merged(json.loads(raw))
+    except (ValueError, TypeError):
+        return factory()
+
+
+def save(raw):
+    """保存（只落用户显式给的字段）。返回 (ok, msg)。
+
+    与出厂默认**相同的字段不入库**：这样以后调出厂值，这些字段能跟着更新
+    ——库里只留"用户真的改过"的部分。
+    """
+    from core.db_config import meta_set
+    cleaned = clean(raw)
+    fac = FACTORY
+    diff = {}
+    for stype, vals in cleaned.items():
+        keep = {k: v for k, v in vals.items()
+                if not (stype in fac and k in fac[stype] and fac[stype][k] == v)}
+        if keep:
+            diff[stype] = keep
+    try:
+        meta_set(META_KEY, json.dumps(diff, ensure_ascii=False))
+    except Exception as e:
+        return False, f"保存失败: {e}"
+    return True, "已保存"
+
+
+def as_payload():
+    """给前端的完整载荷：生效值 + 出厂值 + 字段规格（前端据此画表单与范围）。"""
+    spec = {st: {k: (list(r[1]) if r[0] == "choice" else
+                      (list(r[1:]) if r[0] == "num" else None))
+                 for k, r in fields.items()}
+            for st, fields in SPEC.items()}
+    kinds = {st: {k: r[0] for k, r in fields.items()} for st, fields in SPEC.items()}
+    return {"defaults": get(), "factory": factory(), "spec": spec, "kinds": kinds}

core/step_log.py

@@ -0,0 +1,247 @@
+"""任务步骤明细：异步落库（专用写线程）+ 保留期清理。
+
+为什么不让任务线程直接写库：步骤执行是**热路径**（一次运行可能上万步），每步
+一次 INSERT 要建会话、等 MySQL 往返，还会和业务事务抢连接。这里改成「专用写
+线程 + 有界队列」：任务线程只做一次 put_nowait（微秒级），落库、重排、批量都
+在写线程里做。
+
+铁律（与 `core/notifier.py` 一致）：
+  - `record()` 零阻塞、零 DB、**绝不抛异常** —— 记录绝不影响任务执行；
+  - 落库失败只写日志、丢弃该批，**不重排**（不为补数据把内存撑爆）。
+
+线程用裸 `threading.Thread(daemon=True)`（与项目其它后台线程一致；线程池的
+非 daemon 线程会在退出时被 atexit join 卡住）。
+"""
+import queue
+import threading
+import time
+
+from core.logger import get_logger
+
+_log = get_logger("task.step")
+
+# 一次运行最多记录多少条：防「2 小时无限循环」这类任务把表写爆。
+# 达到上限后本次运行不再逐条记，只补一条 cap 说明行。
+MAX_ROWS_PER_RUN = 2000
+
+# 保留天数：每日清理任务删除更早的记录。**这个值直接决定备份包体积**
+# （task_step_log 会进整库备份，见 doc/DATA_MODEL.md §6），改大前先想清楚。
+KEEP_DAYS = 14
+
+# 队列上限与批量：队列满 = 丢弃并计数（宁可丢明细，也不能拖住任务线程）
+_QUEUE_MAX = 5000
+_BATCH = 200
+_FLUSH_INTERVAL = 1.0
+
+_app = None
+_q = queue.Queue(maxsize=_QUEUE_MAX)
+_writer = None
+_stop = threading.Event()
+_stats = {"queued": 0, "written": 0, "dropped": 0, "failed": 0}
+
+
+# ================== 生命周期 ==================
+
+def init_app(app):
+    """启动写线程（web_server 启动时调用；重复调用安全）。"""
+    global _app, _writer
+    _app = app
+    if _writer is not None and _writer.is_alive():
+        return
+    _stop.clear()
+    _writer = threading.Thread(target=_writer_loop, name="step-log-writer",
+                               daemon=True)
+    _writer.start()
+    _log.info(f"步骤明细写线程已启动（保留 {KEEP_DAYS} 天，单次运行上限 "
+              f"{MAX_ROWS_PER_RUN} 条）")
+
+
+def shutdown(timeout=3.0):
+    """退出前停写线程并尽量排空队列（超时就算了，明细不是关键数据）。"""
+    _stop.set()
+    if _writer is not None:
+        _writer.join(timeout)
+
+
+def stats():
+    """本进程内的计数（排障用：看有没有在丢记录）。"""
+    return dict(_stats, queue_size=_q.qsize())
+
+
+# ================== 写入侧 ==================
+
+def record(run_id="", job_id="", job_name="", serial="", device_name="",
+           step_path="", step_label="", step_type="", selector="",
+           result="", detail="", duration_ms=0):
+    """记录一次步骤执行。**任务线程直接调用**——零阻塞、零 DB、不抛异常。
+
+    队列满时丢弃并计数（dropped），不会阻塞调用方。
+    """
+    try:
+        row = {
+            "run_id": (run_id or "")[:24],
+            "job_id": (job_id or "")[:32],
+            "job_name": (job_name or "")[:120],
+            "serial": (serial or "")[:120],
+            "device_name": (device_name or "")[:80],
+            "step_path": (step_path or "")[:32],
+            "step_label": (step_label or "")[:120],
+            "step_type": (step_type or "")[:40],
+            "selector": (selector or "")[:300],
+            "result": (result or "")[:16],
+            "detail": (detail or "")[:500],
+            "duration_ms": int(duration_ms or 0),
+            "created_at": time.strftime("%Y-%m-%d %H:%M:%S"),
+        }
+        _q.put_nowait(row)
+        _stats["queued"] += 1
+    except queue.Full:
+        _stats["dropped"] += 1
+    except Exception:                      # 截断/类型异常都不该冒泡到任务线程
+        _stats["dropped"] += 1
+
+
+def _collect():
+    """取一批待写记录：最多等 _FLUSH_INTERVAL，凑够 _BATCH 就走。"""
+    rows = []
+    try:
+        rows.append(_q.get(timeout=_FLUSH_INTERVAL))
+    except queue.Empty:
+        return rows
+    while len(rows) < _BATCH:
+        try:
+            rows.append(_q.get_nowait())
+        except queue.Empty:
+            break
+    return rows
+
+
+def _insert(rows):
+    """批量落库。失败只记日志——明细丢了可以接受，任务不能被拖住。"""
+    if not rows or _app is None:
+        return
+    from core.models import TaskStepLog, db
+    try:
+        with _app.app_context():
+            db.session.execute(db.insert(TaskStepLog), rows)
+            db.session.commit()
+        _stats["written"] += len(rows)
+    except Exception as e:
+        _stats["failed"] += len(rows)
+        try:
+            db.session.rollback()
+        except Exception:
+            pass
+        _log.error(f"步骤明细落库失败（丢弃 {len(rows)} 条）: {e}")
+
+
+def _writer_loop():
+    while not _stop.is_set():
+        batch = _collect()
+        if batch:
+            _insert(batch)
+    # 退出前再排空一次，尽量不丢最后几条
+    while True:
+        batch = _collect()
+        if not batch:
+            break
+        _insert(batch)
+
+
+# ================== 查询（给 API 用，在请求线程里跑） ==================
+
+def query(serial="", job_id="", result="", run_id="", keyword="",
+          since="", until="", limit=200, offset=0):
+    """按条件查明细，返回 (rows, total)。**倒序**（最近的在前）。"""
+    from sqlalchemy import or_
+    from core.models import TaskStepLog
+    q = TaskStepLog.query
+    if serial:
+        q = q.filter(TaskStepLog.serial == serial)
+    if job_id:
+        q = q.filter(TaskStepLog.job_id == job_id)
+    if result:
+        q = q.filter(TaskStepLog.result == result)
+    if run_id:
+        q = q.filter(TaskStepLog.run_id == run_id)
+    if since:
+        q = q.filter(TaskStepLog.created_at >= since)
+    if until:
+        q = q.filter(TaskStepLog.created_at <= until)
+    if keyword:
+        kw = f"%{keyword}%"
+        q = q.filter(or_(TaskStepLog.detail.like(kw),
+                         TaskStepLog.step_label.like(kw),
+                         TaskStepLog.step_type.like(kw),
+                         TaskStepLog.selector.like(kw),
+                         TaskStepLog.job_name.like(kw)))
+    total = q.count()
+    rows = (q.order_by(TaskStepLog.id.desc())
+             .offset(max(0, int(offset or 0)))
+             .limit(max(1, min(int(limit or 200), 2000)))
+             .all())
+    return rows, total
+
+
+def runs(serial="", job_id="", since="", until="", limit=100):
+    """按 run_id 归组的一次运行概览（哪次运行失败、失败几步）。
+
+    用一次 GROUP BY 查出来，避免前端按明细自己聚合。
+    """
+    from sqlalchemy import case, func
+    from core.models import TaskStepLog, db
+    q = db.session.query(
+        TaskStepLog.run_id,
+        func.min(TaskStepLog.created_at).label("started_at"),
+        func.max(TaskStepLog.created_at).label("ended_at"),
+        func.max(TaskStepLog.job_name).label("job_name"),
+        func.max(TaskStepLog.job_id).label("job_id"),
+        func.max(TaskStepLog.serial).label("serial"),
+        func.max(TaskStepLog.device_name).label("device_name"),
+        func.count(TaskStepLog.id).label("steps"),
+        func.sum(case((TaskStepLog.result.in_(("error", "miss", "unknown")), 1),
+                      else_=0)).label("failures"),
+    )
+    if serial:
+        q = q.filter(TaskStepLog.serial == serial)
+    if job_id:
+        q = q.filter(TaskStepLog.job_id == job_id)
+    if since:
+        q = q.filter(TaskStepLog.created_at >= since)
+    if until:
+        q = q.filter(TaskStepLog.created_at <= until)
+    q = (q.filter(TaskStepLog.run_id != "")
+          .group_by(TaskStepLog.run_id)
+          .order_by(func.max(TaskStepLog.id).desc())
+          .limit(max(1, min(int(limit or 100), 500))))
+    return q.all()
+
+
+def purge_old(keep_days=None, batch=5000):
+    """删除超过保留期的明细。返回删除行数。
+
+    分批删（先取 id 再按 id 删，**不用 DELETE ... LIMIT**——SQLite 默认编译
+    选项不支持它），避免一条长事务把表锁住。
+    """
+    from core.models import TaskStepLog, db
+    days = KEEP_DAYS if keep_days is None else int(keep_days)
+    cutoff = time.strftime("%Y-%m-%d %H:%M:%S",
+                           time.localtime(time.time() - days * 86400))
+    deleted = 0
+    try:
+        while True:
+            ids = [r.id for r in db.session.query(TaskStepLog.id)
+                   .filter(TaskStepLog.created_at < cutoff).limit(batch).all()]
+            if not ids:
+                break
+            deleted += db.session.query(TaskStepLog) \
+                .filter(TaskStepLog.id.in_(ids)) \
+                .delete(synchronize_session=False)
+            db.session.commit()
+    except Exception as e:
+        db.session.rollback()
+        _log.error(f"步骤明细清理失败（已删 {deleted} 条）: {e}")
+        return deleted
+    if deleted:
+        _log.info(f"步骤明细清理: 删除 {deleted} 条（保留 {days} 天）")
+    return deleted

core/system_backup.py

@@ -56,6 +56,10 @@ TABLE_LABELS = {
     "pending_device": "待连接设备", "agent_conversation": "AI 会话",
     "agent_experience": "经验库", "experience_audit": "经验巡检",
     "agent_action": "动作库", "device_install_log": "设备端安装记录",
+    "task_step_log": "任务步骤明细",
+    "done_mark": "去重记录（已做过）",
+    "device_account": "账号台账",
+    "video_plan": "视频发布计划",
 }
 _STAGE_TTL = 1800  # 导入暂存有效期（秒）
 
@@ -137,6 +141,46 @@ def _summary_info(con):
     return rows
 
 
+def _video_summary():
+    """视频素材目录的概况（写进 manifest；**不进备份包**，但要交代清楚）。
+
+    · `missing`：`video_plan` 引用了、但文件已经不在了的清单 —— 反向自检
+      （与 `coverage_missing` 同一个思路：别让"看起来有其实没有"悄悄发生）
+    """
+    try:
+        from config import VIDEO_DIR
+    except Exception:
+        return {"included": False, "error": "config 读取失败"}
+    count = 0
+    size = 0
+    try:
+        for root, _dirs, files in os.walk(VIDEO_DIR):
+            for fn in files:
+                if fn.startswith(".tmp_"):
+                    continue
+                try:
+                    size += os.path.getsize(os.path.join(root, fn))
+                    count += 1
+                except OSError:
+                    pass
+    except Exception:
+        pass
+    missing = []
+    try:
+        from core.models import VideoPlan
+        with db.app_context():
+            for r in VideoPlan.query.filter(VideoPlan.video_file != "").all():
+                p = os.path.join(VIDEO_DIR, r.video_file)
+                if not os.path.exists(p):
+                    missing.append({"id": r.id, "file": r.video_file})
+    except Exception:
+        pass
+    return {"included": False, "dir": "data/videos", "count": count, "bytes": size,
+            "note": "视频素材不进备份包（体积）。恢复后需重新上传；"
+                    "计划、发布状态与分享链接在 video_plan 表里，已备份。",
+            "missing": missing[:200], "missing_count": len(missing)}
+
+
 def _prune_old_exports(max_age=3600):
     """清理过期的导出临时 zip（下载完成后的 call_on_close 在 Windows 上可能
     因文件锁删不掉，这里按时间兜底清理；保留近 1 小时的便于失败重试）。"""
@@ -296,6 +340,9 @@ def create_export(include_apk=True):
             "include_apk": include_apk,
             "tables": _summary_info(con),
             "apks": apk_meta,
+            # 视频发布计划的素材**不进备份包**（几十 GB 会把备份能力搞坏），
+            # 但必须在 manifest 里交代清楚 —— 否则就是"以为备份了其实没有"（红线）。
+            "videos": _video_summary(),
         }
         # 覆盖自检：登记在册的业务表若在快照里缺失（新增功能忘了登记 / 建表失败），
         # 显式告警并写进 manifest——避免"以为备份了其实没有"（备份覆盖红线）。

core/task_draft.py

@@ -55,11 +55,12 @@ SCHEDULE_MODES = ("once", "cron", "cron_stop")
 TARGET_MODES = ("all", "group", "serial")
 
 # 需要选择器的步骤类型（缺 selector_value 时执行器静默跳过）
-NEED_SELECTOR = ("click", "long_click", "wait_el", "swipe_until", "if_el")
+NEED_SELECTOR = ("click", "long_click", "wait_el", "swipe_until", "if_el", "expect_el",
+                 "read_text")
 # 需要包名的步骤类型
 NEED_PACKAGE = ("open_app", "stop_app")
 # 需要非空 children 的容器
-NEED_CHILDREN = ("loop", "group")
+NEED_CHILDREN = ("loop", "group", "foreach_account")
 
 # 有副作用的动作关键词：命中的步骤在 AI 通道只给 warning（人工复核），不拦
 DESTRUCTIVE_HINTS = ("评论", "发送", "发布", "投稿", "转发", "分享到",
@@ -148,8 +149,10 @@ def validate_steps(steps, depth=1, path="steps", errors=None, warnings=None,
                 errors.append(f"{here}.params.probability: 必须是 0~100 的数字"
                               f"（当前 {prob!r}）")
 
-        # 选择器类步骤
-        if stype in NEED_SELECTOR:
+        # 选择器类步骤（例外：if_el 用「去重」条件时不需要 selector_value，
+        # 它的身份元素在 ident_value 里，按自己的规则校验）
+        if stype in NEED_SELECTOR and not (stype == "if_el"
+                                           and params.get("selector_type") == "dedup"):
             sel = params.get("selector_value")
             if not isinstance(sel, str) or not sel.strip():
                 errors.append(f"{here}.params.selector_value: 不能为空 —— "
@@ -219,6 +222,42 @@ def validate_steps(steps, depth=1, path="steps", errors=None, warnings=None,
             if isinstance(else_, list) and else_:
                 validate_steps(else_, depth + 1, f"{here}.params.else",
                                errors, warnings, types, counter)
+            # 文本比对（可选）：运算符必须认得，且配了运算符就得有值——
+            # 执行器对认不出的运算符是"一律不命中"，写错了会静默走 else，
+            # 所以在这里拦住，别让 AI 草稿悄悄变成"永远不命中"
+            cmp_op = (params.get("cmp_op") or "").strip()
+            cmp_src = (params.get("cmp_source") or "").strip()
+            if cmp_src not in ("", "manual", "release", "account_target", "var"):
+                errors.append(f"{here}.params.cmp_source: 不支持的候选值来源 {cmp_src!r}"
+                              f"（可用：空/manual/release/account_target/var）")
+            if cmp_src == "var" and not (params.get("cmp_var") or "").strip():
+                errors.append(f"{here}.params.cmp_var: 候选值来源选了「变量」就必须填变量名"
+                              f"（默认 account_name —— 由「读取文字」写入）")
+            if cmp_op:
+                from tasks.generic.task import CMP_OPS
+                if cmp_op not in CMP_OPS:
+                    errors.append(f"{here}.params.cmp_op: 不支持的比对运算符 {cmp_op!r}"
+                                  f"（可用：{'、'.join(CMP_OPS)}）")
+                elif not str(params.get("cmp_value") or "").strip() \
+                        and cmp_src not in ("release", "account_target", "var"):
+                    # 候选值来自发布计划 / 本次要发的名字 / 变量时，允许手填留空（候选不是手填的）；
+                    # 其余情况仍要求填值，否则永远不命中
+                    errors.append(f"{here}.params.cmp_value: 选了文本比对"
+                                  f"（{cmp_op}）就必须填比对的值，否则永远不命中")
+                elif (params.get("selector_type") or "xpath") == "screen":
+                    warnings.append(f"{here}: 屏幕状态没有文本可比，"
+                                    "cmp_op/cmp_value 会被忽略")
+            # 去重条件（见 tasks/generic/task.py 的 selector_type="dedup"）：
+            # 不用 selector_value，身份元素填在 ident_value
+            if (params.get("selector_type") or "") == "dedup":
+                iv = (params.get("ident_value") or "").strip()
+                if not iv:
+                    warnings.append(f"{here}: 去重条件没填身份元素，将按「设备」当身份"
+                                    "（一号一机时没问题；一台机器多个号时要填账号那个元素）")
+                elif (params.get("ident_type") or "text") == "xpath" \
+                        and not (iv.startswith("//") or iv.startswith("(//")):
+                    errors.append(f"{here}.params.ident_value: 身份元素的类型是 xpath，"
+                                  f"取值应以 // 或 (// 开头（当前 {iv[:40]!r}）")
 
         if stype == "swipe":
             _check_direction(params, here, errors)
@@ -240,20 +279,24 @@ def validate_steps(steps, depth=1, path="steps", errors=None, warnings=None,
                               f"（当前 min={lo!r} max={hi!r}）")
 
         if stype == "input_text":
-            mode = params.get("mode", "random")
-            if mode not in ("random", "fixed"):
-                errors.append(f"{here}.params.mode: 必须是 random 或 fixed"
-                              f"（当前 {mode!r}）")
-            elif mode == "fixed":
-                if not str(params.get("fixed_text") or "").strip():
-                    errors.append(f"{here}.params.fixed_text: mode=fixed 时不能为空")
-            else:
-                texts = params.get("texts")
-                if not isinstance(texts, str) or not texts.strip():
-                    errors.append(f"{here}.params.texts: mode=random 时必须给候选"
-                                  "文案（换行分隔，如 \"你好\\n不错\"）")
-                elif len([t for t in texts.split("\n") if t.strip()]) > MAX_TEXTS:
-                    errors.append(f"{here}.params.texts: 候选文案最多 {MAX_TEXTS} 条")
+            # 文案来自「发布计划」（`text_source` 不是 manual）时 texts/fixed_text **都不参与输入** ——
+            # 别按"手填"的规则要求候选文案（发布任务骨架里那两步就是这么配的：
+            # mode 留默认、内容由计划给，靠 `release_title`/`release_body` 现取）
+            if str(params.get("text_source") or "manual").strip() == "manual":
+                mode = params.get("mode", "random")
+                if mode not in ("random", "fixed"):
+                    errors.append(f"{here}.params.mode: 必须是 random 或 fixed"
+                                  f"（当前 {mode!r}）")
+                elif mode == "fixed":
+                    if not str(params.get("fixed_text") or "").strip():
+                        errors.append(f"{here}.params.fixed_text: mode=fixed 时不能为空")
+                else:
+                    texts = params.get("texts")
+                    if not isinstance(texts, str) or not texts.strip():
+                        errors.append(f"{here}.params.texts: mode=random 时必须给候选"
+                                      "文案（换行分隔，如 \"你好\\n不错\"）")
+                    elif len([t for t in texts.split("\n") if t.strip()]) > MAX_TEXTS:
+                        errors.append(f"{here}.params.texts: 候选文案最多 {MAX_TEXTS} 条")
 
         if stype == "clipboard":
             if not str(params.get("text") or "").strip():
@@ -279,9 +322,9 @@ def _check_selector(params, here, stype, errors, warnings):
     stype_ok = IF_SELECTOR_TYPES if stype == "if_el" else SELECTOR_TYPES
     sel_type = params.get("selector_type") or "xpath"
     value = (params.get("selector_value") or "").strip()
-    if sel_type not in stype_ok:
+    if sel_type not in stype_ok and not (sel_type == "dedup" and stype == "if_el"):
         errors.append(f"{here}.params.selector_type: 不支持 {sel_type!r}"
-                      f"（可用：{'、'.join(stype_ok)}）")
+                      f"（可用：{'、'.join(stype_ok + ('dedup',))}）")
         return
     if len(value) > MAX_SELECTOR_LEN:
         errors.append(f"{here}.params.selector_value: 太长（>{MAX_SELECTOR_LEN} 字符）")

core/task_manager.py

@@ -32,6 +32,7 @@ from config import DATA_DIR
 from core.logger import get_logger
 from core.models import db, DeviceGroup as GroupRow, TaskJob as JobRow
 from core import device_pool
+from core import device_battery
 from core import notifier
 from .adb_helper import get_foreground_app, get_foreground_app_remote
 from .device_worker import (
@@ -49,6 +50,34 @@ _log = get_logger("core.tm")
 _START_STAGGER_SEC = 0.2
 
 
+def _dev_model(serial, tracker=None):
+    """设备型号：优先用批次开始时查好的设备池快照，退回 worker 上报的状态表。
+
+    为什么优先快照：worker 每次启动都会 `_update_status(model=…)`，但那次采集
+    （`d.info()`）可能超时/失败 → 型号是空；而设备池的型号是后台统一采集的、
+    稳定得多。快照还有个好处：不查库（通知路径上不碰 DB）。
+    """
+    if tracker is not None:
+        m = (tracker.models or {}).get(serial)
+        if m:
+            return m
+    with _WORKERS_LOCK:
+        return _WORKERS.get(serial, {}).get("model") or ""
+
+
+def _dev_fail_note(serial, dname, tracker=None):
+    """失败设备的一行说明：`名字（型号）：原因`——批次汇总里直接列出来。
+
+    型号同上用快照；原因取 worker 上报的 last_error（刚写进去，还在）。
+    """
+    with _WORKERS_LOCK:
+        err = _WORKERS.get(serial, {}).get("last_error") or ""
+    cause = err.strip().splitlines()[0] if err.strip() else ""
+    model = _dev_model(serial, tracker)
+    head = f"{dname}（{model}）" if model else str(dname)
+    return f"{head}：{cause[:60]}" if cause else head
+
+
 class _BatchTracker:
     """一次任务批次的收尾统计：**所有设备都出结果**后发一条 `task.batch.finished`。
 
@@ -59,29 +88,40 @@ class _BatchTracker:
     放在 finally 里是为了保证"任何一个 return 分支都会被计数一次"，不会漏也不会重。
     """
 
-    def __init__(self, job, total, names=None):
+    def __init__(self, job, total, names=None, models=None):
         self.job = job
         self.total = total
         # serial -> 设备名（通知里显示名字而不是裸地址）；取不到就是空
         self.names = dict(names or {})
+        # serial -> 型号（批次开始时从设备池查一次带下来，通知里直接用）
+        self.models = dict(models or {})
         self._lock = threading.Lock()
         self._left = total
         self._stats = Counter()
+        self._failed = []          # 失败设备明细（型号 + 原因），汇总里有失败时列出
         self._t0 = time.time()
 
-    def done(self, serial, outcome="failed"):
-        """登记一台设备的结果（success/failed/stopped/skipped）。"""
+    def done(self, serial, outcome="failed", detail=""):
+        """登记一台设备的结果（success/failed/stopped/skipped）。
+
+        detail 只对 failed 有意义（"设备名（型号）：原因"），最多留 5 条 ——
+        批次汇总里列出来，用户不用再去翻日志。
+        """
         with self._lock:
             self._left -= 1
             self._stats[outcome] += 1
+            if outcome == "failed" and detail and len(self._failed) < 5:
+                self._failed.append(detail)
             left = self._left
             s = dict(self._stats)
+            fails = list(self._failed)
         if left > 0:
             return
         notifier.notify("task.batch.finished", job_id=self.job.id,
                         job_name=self.job.name, total=self.total,
                         success=s.get("success", 0), failed=s.get("failed", 0),
                         stopped=s.get("stopped", 0), skipped=s.get("skipped", 0),
+                        failed_devices=fails,
                         duration_s=int(time.time() - self._t0))
 
 
@@ -722,14 +762,15 @@ class TaskManager:
                         serials_preview=serials[:5])
         # 批次收尾统计：所有设备都出结果后发一条汇总（见 _BatchTracker）
         # 设备名一次查好带下去（worker 线程里没有 app context，查库要显式包 context）
-        names = {}
+        names, models = {}, {}
         try:
             with self._db():
-                names = {d["serial"]: (d.get("name") or "")
-                         for d in device_pool.list_devices()}
+                rows = device_pool.list_devices()
+            names = {d["serial"]: (d.get("name") or "") for d in rows}
+            models = {d["serial"]: (d.get("model") or "") for d in rows}
         except Exception as e:
-            _log.warning(f"读取设备名失败（通知里将显示地址）: {e}")
-        tracker = _BatchTracker(job, len(serials), names)
+            _log.warning(f"读取设备名/型号失败（通知里将显示地址）: {e}")
+        tracker = _BatchTracker(job, len(serials), names, models)
 
         for idx, serial in enumerate(serials):
             # 每台设备一个重试循环线程，互不影响；错峰延迟在各自线程内等待
@@ -825,8 +866,13 @@ class TaskManager:
 
                 worker = None
                 t_attempt = time.time()          # 单次 attempt 耗时（通知里带）
+                # 本次运行的上下文：步骤明细按 run_id 归组，把同一设备同一次尝试
+                # 执行的步骤串起来（重试会生成新的 run_id，两次尝试不混在一起）
+                run_ctx = {"run_id": uuid.uuid4().hex[:12], "job_id": job.id,
+                           "job_name": job.name, "device_name": dname,
+                           "attempt": attempt}
                 try:
-                    worker = task.create_worker(serial, job.params)
+                    worker = task.create_worker(serial, job.params, ctx=run_ctx)
                     with self._lock:
                         self._running[serial]["worker"] = worker
                     _log.info(f"{serial} 开始任务 {job.name} (第{attempt}/{max_attempts}次)")
@@ -843,11 +889,16 @@ class TaskManager:
                     if st == "done":
                         _log.info(f"{serial} 任务 {job.name} 成功完成")
                         outcome = "success"
-                        notifier.notify("task.device.success", serial=serial,
-                                        device_name=dname, job_id=job.id,
-                                        job_name=job.name, attempt=attempt,
-                                        duration_s=int(time.time() - t_attempt),
-                                        is_time_up=bool(worker.is_time_up()))
+                        # 单设备成功：**只在"这一批本来就只有一台设备"时发**。
+                        # 多设备批次里逐台报成功没有信息量（批次汇总里已有成功台数），
+                        # 13 台就是 13 条刷屏；失败仍然逐台发——那是少数且要知道是哪台。
+                        if tracker is None or tracker.total <= 1:
+                            notifier.notify("task.device.success", serial=serial,
+                                            device_name=dname,
+                                            model=_dev_model(serial, tracker),
+                                            job_id=job.id, job_name=job.name,
+                                            attempt=attempt,
+                                            duration_s=int(time.time() - t_attempt))
                         return
                     # 用户请求停止（无论 attempt 第几次、status 是什么）→ 不重试
                     with self._lock:
@@ -859,6 +910,18 @@ class TaskManager:
                                             job_name=job.name, attempt=attempt,
                                             phase="after")
                             return
+                    if worker is not None and worker.stopped():
+                        # 任务**自己**停的（步骤里的「停止本设备」）：不是失败，也不重试。
+                        # 判据是"worker 置了停止位但 _stop_requested 里没有"——上面那个
+                        # 分支已经排除了用户/调度停止的情况。
+                        _log.info(f"{serial} 任务内主动停止本设备 (job={job.name})")
+                        outcome = "stopped"
+                        notifier.notify("task.device.stopped", serial=serial,
+                                        device_name=dname,
+                                        model=_dev_model(serial, tracker),
+                                        job_id=job.id, job_name=job.name,
+                                        attempt=attempt, phase="self")
+                        return
                     _log.warning(f"{serial} 任务未成功(status={st})")
                 except DeviceOfflineError as e:
                     # 设备掉线，立即放弃，不重试
@@ -869,7 +932,9 @@ class TaskManager:
                                    last_error=f"设备离线: {e}")
                     outcome = "failed"
                     notifier.notify("task.device.offline", serial=serial, device_name=dname,
-                                    job_id=job.id, job_name=job.name, error=str(e)[:200])
+                                    model=_dev_model(serial, tracker),
+                                    job_id=job.id, job_name=job.name,
+                                    error=str(e)[:200])
                     return
                 except Exception as e:
                     _log.error(f"{serial} 执行异常: {e}", exc_info=True)
@@ -877,6 +942,7 @@ class TaskManager:
                         self._running.pop(serial, None)
                     _update_status(serial, task_job="")
                     notifier.notify("task.device.error", serial=serial, device_name=dname,
+                                    model=_dev_model(serial, tracker),
                                     job_name=job.name, attempt=attempt,
                                     error=str(e)[:200])
 
@@ -920,7 +986,8 @@ class TaskManager:
             _update_status(serial, status="failed", last_error=msg[:200])
             outcome = "failed"
             notifier.notify("task.device.failed", serial=serial, device_name=dname,
-                            job_id=job.id, job_name=job.name, attempts=max_attempts,
+                            model=_dev_model(serial, tracker), job_id=job.id,
+                            job_name=job.name, attempts=max_attempts,
                             cause=cause, msg=msg)
         finally:
             # 清除停止标志：整个重试循环结束（成功/失败/停止）后允许下次任务
@@ -929,7 +996,9 @@ class TaskManager:
             # 批次统计：**每台设备只在这里上报一次**（所有 return 分支都会走到 finally）
             if tracker is not None:
                 try:
-                    tracker.done(serial, outcome)
+                    tracker.done(serial, outcome,
+                                 detail=_dev_fail_note(serial, dname, tracker)
+                                 if outcome == "failed" else "")
                 except Exception as e:
                     _log.warning(f"批次统计上报失败（不影响任务）: {e}")
             # 归还：本任务是抢占任务，结束后自动重新启动被抢占的原任务
@@ -1054,6 +1123,9 @@ class TaskManager:
                 "owner": "",
                 "worker_status": w.get("status", "idle"),
                 "foreground_app": self._fg_scanner.get(serial),
+                # 电量（后台线程采的缓存，这里只读内存不查 adb）：
+                # {"level":85,"charging":false,"at":ts} 或 None（还没采到）
+                "battery": device_battery.get(serial),
                 # 通用进度字段（任意 app 通用，前端统一解析展示）
                 # 结构：{"done": int, "total": int, "unit": str, "action_counts": dict}
                 "progress": w.get("progress", {}),

core/u2_helper.py

@@ -5,6 +5,7 @@
 """
 import time
 import random
+import re
 
 from core.logger import get_logger
 
@@ -65,6 +66,34 @@ def random_sleep(min_s, max_s):
     time.sleep(random.uniform(min_s, max_s))
 
 
+def screen_is_on(d):
+    """屏幕是否亮着。返回 True/False，取不到返回 None（三态，别当 False 用）。
+
+    为什么不用 `d.info`：它在部分设备上一次要**十几秒**（见 doc/backlog/TODO.md）；
+    `dumpsys power` 经 atx-agent 跑只要 ~0.3s，且 `mWakefulness` 字段全机型都有
+    （MIUI 的 `dumpsys display` 反而没有 mScreenState）。
+    """
+    try:
+        out = d.shell("dumpsys power")
+        out = getattr(out, "output", None) or str(out)
+        m = re.search(r"mWakefulness=(\w+)", out)
+        if m:
+            return m.group(1).lower() != "asleep"
+    except Exception as e:
+        _log.warning(f"读取屏幕状态失败: {e}")
+    return None
+
+
+def current_package(d):
+    """当前前台 App 包名；取不到返回空串。"""
+    try:
+        cur = d.app_current() or {}
+        return cur.get("package") or ""
+    except Exception as e:
+        _log.warning(f"读取前台 App 失败: {e}")
+    return ""
+
+
 def safe_click(el, timeout=1):
     """安全点击：元素存在才点，不抛异常。返回是否点击成功。"""
     try:

doc/AI_CONSOLE.md

@@ -184,7 +184,11 @@ mcp_agent.Agent.run_stream(prompt, serial, history, on_delta, on_tool, on_usage,
 从本轮**成功**的步骤轨迹里提炼命名动作（如「打开抖音」）。硬约束：
 
 - **禁坐标**：带 `click_xy` 的步骤不会被沉淀（坐标换个设备/分辨率就失效）
-- 白名单步骤类型（18 种去掉 `click_xy`、`keep_screen`）
+- 白名单步骤类型（**显式列举 16 种**，见 `web/agent_api.py` 的 `_ACTION_STEP_TYPES`）：
+  `open_app` / `stop_app` / `screen_on` / `screen_off` / `key_event` / `swipe` /
+  `swipe_until` / `click` / `long_click` / `wait_el` / `input_text` / `clipboard` /
+  `wait` / `loop` / `group` / `if_el`——坐标类（`click_xy`）与流程标记类
+  （`keep_screen` / `gesture` / `notify` / `stop_self` / `mark_done`）都不沉淀
 - 每类型有必填参数校验（如 `click` 必须有选择器）
 - 输入/产出限量：最多 10 步输入、最多 3 个动作 × 4 步
 - 保存时服务端**再校验一次**，含坐标的提交直接 400

doc/AI_TASK_GEN.md

@@ -9,7 +9,7 @@
 
 平台已有两套能力，但互不相通：
 - **AI 控制台**：一句话 + 选设备 → 多模态 Agent（DeepSeek）通过 20 个 `de_*` 工具在手机上「边看边做」（截图看屏、`de_ui_tree` 拿元素树、`de_tap_element/de_tap_text` 语义点按），流式回放步骤。
-- **任务系统 + 步骤编辑器**：`generic_steps` 任务 = 一棵可嵌套步骤树（open_app/click/swipe/loop/group/if_el…18 种节点），在编辑器里拖拽编排、单步试跑、定时调度。
+- **任务系统 + 步骤编辑器**：`generic_steps` 任务 = 一棵可嵌套步骤树（open_app/click/swipe/loop/group/if_el…22 种节点），在编辑器里拖拽编排、单步试跑、定时调度。
 
 目标：让**非工程用户用一句自然语言需求**（例：「创建一个每日养号刷视频的任务，每天 8:00-9:00 在 100.100.10.13 跑」）得到**一条可直接调度、可继续在现有步骤编辑器里手改的任务**。AI 先自己在设备上打开 App、看 UI 树、确认可点元素，再直接撰写编辑器的步骤 JSON。
 

doc/API.md

@@ -62,7 +62,9 @@
 
 ## 2. 接口总索引
 
-> 共 **107 条路由**。`鉴权` 列：`—` 无、`L` 登录、`T/D/A/G` = tasks/devices/apks/logs 权限位、`Admin` 仅管理员。
+> 本表列出全部业务路由（页面路由除外；同一路径的不同方法合并成一行）。
+> `鉴权` 列：`—` 无、`L` 登录、`T/D/A/G` = tasks/devices/apks/logs 权限位、`Admin` 仅管理员。
+> 想看实际注册了多少条：`python -c "from web_server import app; print(len([r for r in app.url_map.iter_rules() if r.rule.startswith('/api')]))"`。
 
 ### 2.1 auth（`web/auth.py`）
 
@@ -124,12 +126,34 @@
 | POST | `/api/custom_actions` | T | 新建自定义动作 |
 | PUT | `/api/custom_actions/<action_id>` | T | 更新自定义动作 |
 | DELETE | `/api/custom_actions/<action_id>` | T | 删除自定义动作 |
+| GET | `/api/step_defaults` | L | 步骤默认值（生效值 + 出厂值 + 字段规格，供「动作配置」页画表单） |
+| POST | `/api/step_defaults` | T | 保存步骤默认值（只落与出厂值不同的字段） |
+| POST | `/api/gesture/record/start` | D | 开始录制手势（手机端 getevent，返回 token） |
+| POST | `/api/gesture/record/stop` | D | 停止录制并取回轨迹 `gestures:[[[x,y,t_ms],…]]` |
 | GET | `/api/uiauto/status` | L | uiautodev 服务是否在跑 |
 | GET | `/api/uiauto/devices` | D | 抓元素可选设备 |
 | GET | `/api/uiauto/elements` | D | 设备 UI 元素树 |
 | GET | `/api/uiauto/snapshot` | D | **一次取齐**截图 + 元素树（原生 u2，抓取弹窗用） |
 | GET | `/api/uiauto/screenshot` | D | uiautodev 截图（JPEG） |
 | POST | `/api/steps/test` | D | 真机试执行单个步骤 |
+| GET | `/api/done_marks?job=&limit=` | L | 去重记录列表 + 统计（`{marks, stats{total,devices,identities,today_devices,today_identities}}`） |
+| POST | `/api/done_marks/delete` | T | 删一条去重记录（`{id}`）→ 该设备/身份下次会重新执行 |
+| POST | `/api/done_marks/clear` | T | 清空某任务的全部去重记录（`{job}`）→ 整批重跑 |
+| POST | `/api/video_plan/upload_video` | D | 上传单个素材（**视频或图片**，文件名 `名字_日期_编号`）→ 解析名字 + 入计划 |
+| POST | `/api/video_plan/upload_titles` | D | 上传标题（txt 文本或文件）→ 配到已有计划行 |
+| GET | `/api/video_plan/timeline` | D | 发布计划时间线（按日期分组的卡片 + 统计 + 磁盘） |
+| GET | `/api/video_plan/stats` | D | 今天要发/已发/待标题/过期未发 + 素材占用与磁盘余量 |
+| GET/PUT/DELETE | `/api/video_plan/<id>` | D | 单条计划：查看 / 改标题·正文（`PUT {title,body}`）/ 删除（连素材文件） |
+| GET | `/api/video_plan/<id>/video` | D | 预览平台上的素材（文件清理后 → 410） |
+| POST | `/api/video_plan/<id>/push` | D | **把素材推到手机**（只推送、不发布；后台线程） |
+| POST | `/api/video_plan/push_all` | D | **一键推送**：某天（默认今天）所有待发布/失败的计划 → 各自手机（每台设备一个线程、设备内串行） |
+| POST | `/api/video_plan/<id>/mark` | D | 人工标记结果（`done`/`failed`/`unknown`，推完之后用） |
+| POST | `/api/video_plan/<id>/skip\|retry\|resolve` | D | 跳过 / 重试 / 裁决「结果未知」 |
+| GET | `/api/video_plan/links` | D | 已发布作品的分享链接（`format=csv` 导出，给铺评论用） |
+| GET | `/api/video_plan/tasks` | T | 可编辑的任务列表（全部通用步骤任务 + `is_release` 标记：状态/调度/下次运行 + 完整步骤） |
+| POST | `/api/video_plan/tasks` | T | 一键新建标准发布任务（骨架 18 步：亮屏 → 打开抖音 → 读本机账号名字 → 校验账号 → 推送 → 抖音点击 → 填标题 → 填正文 → 标记） |
+| GET/PUT | `/api/video_plan/tasks/<job_id>` | T | **发布任务的就地编辑**（就在「发布计划」页改名字/目标/时间/启停/步骤） |
+| POST | `/api/video_plan/tasks/<job_id>/adopt` | T | 给已有任务插上平台两步（推送放最前 / 标记放最后，自己的步骤不动） |
 
 ### 2.4 admin（`web/admin_api.py`）
 
@@ -139,7 +163,12 @@
 | POST | `/api/users` | Admin | 新建用户 |
 | PUT | `/api/users/<int:uid>` | Admin | 更新用户（改密/权限/管理员） |
 | DELETE | `/api/users/<int:uid>` | Admin | 删除用户 |
-| GET | `/api/logs` | G | 读日志文件尾部 N 行 |
+| GET | `/api/logs` | G | 读日志（关键字/级别/时间过滤，返回结构化行） |
+| GET | `/api/logs/download` | G | 下载日志（同样支持过滤；无过滤即整个文件） |
+| GET | `/api/step_logs` | G | 任务步骤明细（按设备/任务/结果/时间/关键字过滤，分页） |
+| GET | `/api/step_logs/runs` | G | 按 `run_id` 归组的一次运行概览（几步、失败几步） |
+| GET | `/api/step_logs/filters` | G | 步骤明细的筛选项（明细里出现过的设备/任务 + 结果枚举） |
+| GET | `/api/step_logs/download` | G | 导出步骤明细 CSV（带 UTF-8 BOM，Excel 直接打开） |
 
 ### 2.5 devices（`web/devices_api.py`）
 
@@ -160,6 +189,9 @@
 | POST | `/api/devices/discovery/ignore` | D | 忽略待连接设备 |
 | POST | `/api/devices/discovery/reconnect` | D | 立即重连指定断联设备 |
 | POST | `/api/devices/discovery/settings` | D | 保存发现配置 |
+| GET | `/api/devices/battery` | D | 电量采集器状态 + 生效配置（`{settings, scanning, last_scan:[时间,成功,目标数], cached}`） |
+| POST | `/api/devices/battery/settings` | D | 保存电量监控配置（越界钳制，返回钳制后的生效值） |
+| POST | `/api/devices/battery/scan` | D | 立即采集一次（后台执行；上一轮没跑完返回 409） |
 
 ### 2.6 apks（`web/apks_api.py`）
 
@@ -179,6 +211,8 @@
 | GET | `/api/adb/devices` | Admin | 维护终端设备列表（本机 adb + 设备池） |
 | POST | `/api/adb/cmd` | Admin | 执行 adb 命令（20s 超时；拦截 `kill-server`/`disconnect`） |
 | POST | `/api/tools/clipboard/set` | Admin | 剪贴板注入到多台设备 |
+| POST | `/api/tools/push_clipboard` | D | 同上（**同一个实现**），权限按设备位放行 —— 大屏「发布」面板用 |
+| POST | `/api/tools/push_material` | D | 大屏「发布」面板：把上传的视频/图片**直接推到指定设备**相册（不占发布计划） |
 | POST | `/api/tools/appver` | Admin | 查指定包名在所有在线设备的版本 |
 
 ### 2.8 tailscale（`web/tailscale_api.py`，全部 Admin）
@@ -312,12 +346,19 @@
    "serial": "192.168.20.206:5555", "model": "22120RN86C", "device_name": "", "present": true, "ready": true,
    "worker_status": "running", "task_job": "测试抖音评论", "attempt": 1, "max_attempts": 1,
    "current_action": "点击搜索", "progress": {"done": 5, "total": 0, "unit": "操作", "elapsed": 42},
-   "foreground_app": "抖音", "last_error": "", "last_warning": "", "end_time": 0
+   "foreground_app": "抖音", "last_error": "", "last_warning": "", "end_time": 0,
+   "battery": {"level": 85, "charging": true, "at": 1700000000.0, "tier": 0}
  }]}
 ```
 
 `worker_status`：`idle` / `connecting` / `running` / `done` / `error` / `released` / `failed`。
 
+`battery`：**后台线程采的缓存值**（默认 60s 一轮，`dumpsys battery` 只读），没采到时为 `null`。
+`tier` 是**告警档位**（`0` 正常 / `1` 低电量 / `2` 严重），由后端按配置阈值算好——
+前端只按 `tier` 上色，**不在 JS 里重算阈值**（阈值只在「工具 → 设备发现 → 电量监控」一处定义）。
+设备离线时保留最后一次读数（`at` 是采集时刻），页面置灰显示。详见 [NOTIFY.md](NOTIFY.md) §3 的
+`device.battery.low`。
+
 ### GET /api/summary
 
 ```json
@@ -449,6 +490,51 @@
 
 `steps` 的 schema 与 `generic_steps` 的 `params.steps` 完全一致，见 [TASK_DEV.md](TASK_DEV.md)。
 
+### 去重记录（「任务 → 去重记录」页）
+
+| 接口 | 请求 | 响应要点 |
+|------|------|---------|
+| `GET /api/done_marks` | `?job=<任务ID>&limit=200` | `{ok, marks:[{id,scope_key,kind,job_id,job_name,serial,device_name,identity,created_at}], stats:{total,devices,identities,today_devices,today_identities}}`。`job` 省略 = 全部任务 |
+| `POST /api/done_marks/delete` | `{"id"}` | 删一条 → 该设备/身份下次会重新执行；不存在 → 404；缺 id → 400 |
+| `POST /api/done_marks/clear` | `{"job"}` | 清空该任务的全部记录（整批重跑）→ `{ok,msg,deleted}`；缺 job → 400 |
+
+账本表与语义见 [DATA_MODEL.md](DATA_MODEL.md) §2.9；任务侧怎么用见
+[TASK_DEV.md](TASK_DEV.md) §4.6。
+
+### 视频发布计划（「发布计划」页）
+
+表与状态机见 [DATA_MODEL.md](DATA_MODEL.md) §2.11，任务侧怎么自动发布见
+[TASK_DEV.md](TASK_DEV.md) §4.7；权限 `devices`。
+
+| 接口 | 请求 | 响应要点 |
+|------|------|---------|
+| `POST /api/video_plan/upload_video` | multipart `file`（单文件，**视频或图片**）+ `replace` | `{ok,name,action:add\|skip\|replace,plan,msg}`；解析不通过 → **400 + `error`（人话原因）**。前端**逐文件串行**发（才能给每个文件一条进度与结果） |
+| `POST /api/video_plan/upload_titles` | `{text, dry_run}` 或 multipart `file`（txt） | `{ok, counts:{total,attached,skipped,rejected}, rows:[{line,name,date,seq,title,body,action,error}], msg}`；**一行里可带正文**：`标题 || 正文_名字_日期_编号`（`||` 分隔，正文可省，只切第一处）；**只有这一种写法**（名字在日期前一段，右锚定）；**编号可省略**；标题/正文里可以有下划线和 `#话题`；空行忽略，`#` 开头的行**只有认不出名字/日期时**才当注释；拒收条件：名字里带下划线/是纯数字/是手机号、日期不合法、标题为空或 >100 字、该槽位已有标题、没有对应视频 |
+| `GET /api/video_plan/timeline` | `?range=today\|week\|all&from=&to=&status=&q=&limit=` | `{ok, days:[{date,weekday,total,done,plans:[…]}], stats, disk, today}` |
+| `GET /api/video_plan/stats` | — | `{ok, stats, disk, today}`；`stats` 里**三个口径都给**：`today_ready`（今天要发几个号，按发布日期）/ `today_done`（今天完成）/ `published_today`（今天实际发的，按 `published_at`，补发也算今天） |
+| `GET /api/video_plan/<id>` · `PUT` · `DELETE` | `PUT {"title","body","nickname"}` | `PUT` 改标题/正文/**名字**（名字 = 识别键，走同一套校验：不许含下划线/不许纯数字；改完按"有没有内容"切 `pending↔ready`）；`DELETE` **先删行再删素材文件** |
+| `GET /api/video_plan/<id>/video` | — | 素材预览（`send_file`，支持 Range）；文件已被清理 → **410** |
+| `POST /api/video_plan/<id>/push` | — | **把素材推到手机**（只推送、不发布）：**按名字找设备**（实时探测哪台在线设备登着这条计划的名字）→ 推文件 → 触发相册刷新 → 标题写进剪贴板；已推送/结果未知 → 409；没有设备登着这个名字 → **400 + 人话原因**（先去切号） |
+| `POST /api/video_plan/push_by_account` | `{date?, retry_failed?, serials?}` | **一键推送（按名字找设备）**：某天（默认今天）`ready`/`failed` 且未超尝试上限的计划 → 按 `nickname` 分组 → **实时探测**在线设备当前登的号（跳过正在跑任务的设备）→ 每台设备一个线程、设备内串行。返回 `{ok,count,devices,matched:[{name,count,serial,device_name}],unmatched:[{name,count,reason}],msg}`；**全部 unmatched → 400**（`error` 里逐条说清"没有在线设备登着这个号"）。`serials` 可只探指定设备 |
+| `POST /api/video_plan/push_all` | 同上 | 老入口，语义与 `push_by_account` 完全一致（都按名字找设备） |
+| `POST /api/video_plan/<id>/mark` | `{status: done\|failed\|unknown, why}` | 人工标记结果（推完之后用）：`done` 补 `published_at`；`failed`/`unknown` 把 `why` 记进 `last_error` |
+| `POST /api/video_plan/<id>/skip` | `{reason}` | 人工跳过 |
+| `POST /api/video_plan/<id>/retry` | — | `failed`→`ready`，`attempts` 清零 |
+| `POST /api/video_plan/<id>/resolve` | `{published, note}` | **`unknown` 的人工裁决**：确认真发出去了 → `done`；确认没发 → `failed`（可重试） |
+| `GET /api/video_plan/links` | `?from=&to=&name=&format=csv` | 已发布作品的分享链接；CSV 带 BOM（Excel 打开中文不乱码）。列：发布日期/**名字**/编号/标题/**正文**/分享链接/发布时间 |
+| `GET /api/video_plan/tasks` | — | `{ok, tasks:[{id,name,enabled,mode,cron,next_run,target,steps,step_count,schedule,retry,is_release,has_push}], release_count, other_count}`：**全部通用步骤任务**（不止发布任务 —— 只列发布任务的话，手写的抖音发布流程会一条都不显示，人会以为"这页没有能改的地方"），界面按 `is_release`（有 `push_release` **或** `mark_release`，含嵌套）分两组。带完整 `steps` 是为**就地编辑**（抓选择器）；`step_count` 数的是**含嵌套**的总步数。权限 `T` |
+| `POST /api/video_plan/tasks` | `{"name","target":{"mode":"all\|group\|serial","group_name","serial"},"time":"10:00","enabled"}` | 一键新建：骨架 **4 步 / 含循环体内共 23 步**（亮屏 → 打开抖音(等首页) → 点「我」→ `read_account_name` 读本机账号名字（昵称控件的选择器填在 .env）→ `if_el(cmp_source=account_target)` 校验登的是不是要发的名字 → then: `push_release(account=name)` → 「+」(预填 `descriptionContains=拍摄`) → 相册/第一个视频/下一步/标题框/正文框/发布（**空选择器占位**）→ `input_text(text_source=release_title)` → `input_text(text_source=release_body)` → `mark_release`；else: `notify` 跳过）；**走 TaskManager 建**（内存+库一起更新，直接写库调度器不认）。⚠ `target` 分组键名是 **`group_name`**（写成 `group` 会静默解析出 0 台设备）；分组/单设备没给具体目标 → 400。权限 `T` |
+| `GET/PUT /api/video_plan/tasks/<job_id>` | `PUT {name?, time?, target?, steps?, enabled?}` | **发布任务的就地编辑**（「发布计划」页里改，不用跳任务页）。只放开这几个字段，**没传的字段原样保留**；`steps` 整块替换但 `params` 里的通用参数（去重有效期、抢占…）**深合并保留**。校验：空名字/坏时间/`steps` 不是数组/什么都不传 → 400，未知任务 → 404。权限 `T`。底层仍是 `TaskManager.update_job()`（内存+库一起改） |
+| `POST /api/video_plan/tasks/<job_id>/adopt` | — | 给**已有任务**插上平台那两步：`push_release` 放最前、`mark_release` 放最后（**中间你自己的步骤一步不动**；位置理由见 `core.video_plan.insert_release_steps`）。只对「通用步骤」任务；没有步骤 → 400，已经有这两步 → 409，未知任务 → 404。权限 `T` |
+
+**逐文件上传的幂等**：同一 `(名字,日期,编号)` 已有行时 —— 文件内容相同 → `action=skip`（不重复落盘）；
+内容不同 → **拒收**，前端给「覆盖」按钮（二次确认后带 `replace=1` 重传）。
+标题同理：同槽位已有别的标题 → 拒收（不静默覆盖，文案是发出去就改不了的东西）。
+
+> ⚠ 上传体积：`MAX_CONTENT_LENGTH`（默认 2GiB，`.env` 的 `MAX_UPLOAD_MB` 可调）**必须大于
+> 「应用管理」最大的 APK**（实测 336MB），否则 APK 上传会被一起卡死；超限返回 **JSON 413**。
+> 上反代时 nginx 那侧还要 `client_max_body_size`（见 [DEPLOY.md](DEPLOY.md) §6）。
+
 ---
 
 ## 6. 设备池与自动发现
@@ -558,7 +644,7 @@
 | 接口 | 请求 | 响应要点 |
 |------|------|---------|
 | `GET /api/uiauto/status` | — | uiautodev（:20242）是否在跑，前端据此禁/启用"抓取元素" |
-| `GET /api/uiauto/devices` | — | 可选设备列表（uiautodev 设备 + 池内在线补全） |
+| `GET /api/uiauto/devices` | — | 可选设备列表（uiautodev 设备 + 池内在线补全）。每项 `{serial, name, model, product, status}`；**`name` 是平台给设备起的名字**（`cs1`/`A08`），池外设备退回 `serial`——uiautodev 自带的 name 是设备 codename（实测一柜子全是 `earth`），不能用来认设备 |
 | `GET /api/uiauto/elements?serial=` | — | 扁平元素列表（走 uiautodev），每项带 `suggested`、`bounds`、`depth` |
 | `GET /api/uiauto/snapshot?serial=` | — | **一次取齐**：截图 + 元素树（原生 u2 同一连接背靠背）→ `{image,width,height,elements,unstable,screen_state,cost_ms}`；抓取弹窗与 MCP 的 `de_snapshot` 都用它，失败返回 **502** |
 | `GET /api/uiauto/screenshot?serial=` | — | JPEG |
@@ -615,7 +701,59 @@
 | `POST /api/users` | Admin | `{"username","password","is_admin"?,"perms"?}` | 用户名/密码空、重名 → 400 |
 | `PUT /api/users/<int:uid>` | Admin | `{"password"?,"is_admin"?,"perms"?}` | 取消最后一个管理员 → 400；不存在 404 |
 | `DELETE /api/users/<int:uid>` | Admin | — | 删 `admin`/删自己/删最后一个管理员 → 400 |
-| `GET /api/logs?file=core.log&lines=300` | G | — | 返回日志尾部 + 可选文件清单 |
+| `GET /api/logs?file=core.log&lines=300` | G | `q` 关键字、`level` 最低级别、`since`/`until` 时间 | 见下 §10.1 |
+| `GET /api/logs/download?file=core.log` | G | 同上（参数一致） | 以附件返回 `.txt`，文件名带时间戳 |
+
+#### 10.1 日志查询（`GET /api/logs`）
+
+参数：
+
+| 参数 | 说明 |
+|------|------|
+| `file` | 日志文件名，**白名单校验**（只能取接口返回的 `files[].name`，含 `.1/.2` 滚动历史）；非法值返回 `ok:false` |
+| `lines` | 返回**最近**多少条命中（默认 300，上限 5000） |
+| `q` | 关键字，大小写不敏感，匹配整行原文 |
+| `level` | 最低级别：`ERROR` / `WARNING` / `INFO` / `DEBUG`（含以上）；留空为全部 |
+| `since` / `until` | 时间范围，接受 `YYYY-MM-DDTHH:MM`（datetime-local）或 `YYYY-MM-DD`（按整天） |
+
+返回：
+
+```json
+{"ok": true, "file": "core.log",
+ "files": [{"name": "core.log", "label": "核心(adb/调度) · core.log",
+            "size": 1175910, "mtime": 1789519242, "rotated": false}],
+ "rows": [{"ts": "2026-09-16 08:26:50", "level": "INFO",
+           "module": "core.disc", "msg": "发现: …", "cont": false}],
+ "matched": 11423, "scanned": 11423, "truncated": true}
+```
+
+- `rows` 保持文件原顺序（旧→新），即"最近 N 条命中"按时间正序排列；
+- `cont=true` 是**续行**（traceback 的缩进行等）：它本身没有时间/级别前缀，
+  过滤时**继承上一条带前缀的行**，所以按 ERROR 筛选不会把堆栈拆散；
+- `matched` 是命中总数，`truncated=true` 表示更早的命中没返回（应缩小时间范围或加关键字）；
+- `scanned` 是实际扫描行数（上限 50 万行）。
+
+#### 10.2 任务步骤明细（`/api/step_logs*`）
+
+数据源是 `task_step_log` 表（**结构化**，与上面的文本日志不是一回事）：每一次步骤
+执行一条，能按设备/任务/结果/时间过滤、能按运行归组、能导出 CSV。写入侧见
+[DATA_MODEL.md](DATA_MODEL.md) §2.8 与 `core/step_log.py`。
+
+| 接口 | 参数 | 返回 |
+|------|------|------|
+| `GET /api/step_logs` | `serial` `job_id` `result` `run_id` `q` `since` `until` `limit`(≤2000，默认 200) `offset` | `rows`（**最近的在前**）、`total`、`stats`（本次进程的 queued/written/dropped/failed）、`keep_days`、`max_rows_per_run` |
+| `GET /api/step_logs/runs` | `serial` `job_id` `since` `until` `limit`(≤500) | `runs[]`：`run_id` `started_at` `ended_at` `steps` `failures` |
+| `GET /api/step_logs/filters` | — | `devices[]` / `jobs[]`（**只列明细里真的出现过的**，不依赖设备池与任务表）、`results[]` |
+| `GET /api/step_logs/download` | 同列表接口 | 附件 `.csv`（UTF-8 **带 BOM**），最多 2 万行，按时间正序 |
+
+`result` 取值：`ok` / `miss`（handler 返回 False，如元素没找到）/ `error`（抛异常）/
+`unknown`（未知步骤类型）/ `skip`（概率未触发）/ `cap`（本次运行已达记录上限）。
+
+`run_id` 是"设备 × 任务 × 第几次尝试"，同一行里能拿到 `step_path`（如 `2.1.3`）
+还原嵌套结构——**步骤明细面板的「最近运行概览 → 查看」就是按它过滤**。
+
+> 稳定性：记录走异步队列（`record()` 零阻塞），**队列满会丢弃**（计数在 `stats.dropped`，
+> 页面提示栏会显示），所以明细允许缺条 —— 权威结论仍看任务状态与 [NOTIFY.md](NOTIFY.md) 的事件。
 
 ---
 
@@ -634,7 +772,9 @@
 
 | 接口 | 请求 | 说明 |
 |------|------|------|
-| `POST /api/tools/clipboard/set` | `{"serials":[…],"text":"…"}` | ClipInject 通道写入并读回校验；serials 空或非列表 → 400 |
+| `POST /api/tools/clipboard/set` | `{"serials":[…],"text":"…"}` | 设备端 Agent 通道写入并读回校验（旧版独立 ClipInject 自动兜底）；serials 空或非列表 → 400 |
+| `POST /api/tools/push_clipboard` | `{"serial":"…"}`（或 `serials:[…]`）+ `{"text":"…"}` | 与上一条**同一个实现**（`_set_device_clipboard`），权限**设备位**即可 —— 大屏「发布」面板注入剪贴板用 |
+| `POST /api/tools/push_material` | form-data：`file`（视频/图片）+ `serial` + `album_dir`(可省) | 大屏「发布」面板：推文件到该设备相册（默认 `/sdcard/DCIM/Camera`，文件名带 `wall` 前缀、mtime 改成现在）。**不占位、不写库**；扩展名不在 `MEDIA_EXTS` 或设备不在线 → 400；推完做相册索引校验，返回 `{ok,msg,remote,verify,size}`（`verify=no_index` 时 `ok=true` 但文案带 ⚠） |
 | `POST /api/tools/appver` | `{"package":"com.xxx"}` | 并发查所有在线设备（≤10 并发）；包名须匹配 `^[A-Za-z0-9_.]+$` |
 
 ### Tailscale（全部 Admin）

doc/ARCHITECTURE.md

@@ -26,11 +26,13 @@
 ┌───────────────────────────▼──────────────────────────────────────────┐
 │ 领域层   task_manager（调度）  device_worker（执行）  device_pool（池）  │
 │          system_backup（备份）  apk_manager（应用）  device_discovery   │
+│          device_battery（电量采集 + 低电量告警）  dedup（去重账本）        │
 └───────────────────────────┬──────────────────────────────────────────┘
                             │
 ┌───────────────────────────▼──────────────────────────────────────────┐
 │ 基础层   adb_helper · u2_helper · uiauto_helper · ocr · clipboard      │
 │          notifier（通知分发：队列/聚合/限流/适配器）                      │
+│          step_log（步骤明细：队列 + 批量落库 + 保留期清理）               │
 │          models（SQLite）· logger · config                             │
 └──────────────────────────────────────────────────────────────────────┘
                             ▲
@@ -78,15 +80,14 @@
 |------|------|---------|
 | **B** | `:28-58` | `Flask(__name__)`；会话密钥（`.env` 的 `WEB_SECRET_KEY`，缺失则随机生成并 warning）；`TEMPLATES_AUTO_RELOAD=True`；**数据库目标由 `core/db_config` 装配**（`.env` 的 `DEPLOY_ENV`/`DB_*` → URI + 引擎参数），配置错直接 `SystemExit(2)`；`LoginManager` + `login_view="auth.login"` |
 | **C** | `:60-67` | **恢复任务消费** `consume_pending_restore()`。SQLite 时代它必须在 engine 首次打开 `users.db` **之前**（Windows 无法替换被持有的文件）；改用 MySQL 后这一步的语义会变成"启动期事务替换"，见 §7 |
-| **D** | `:69-80` | `init_db(app)`（建表 → 补列 → 版本账本 → 唯一索引 → 默认管理员 → 旧 JSON 迁移）→ **库环境标签校验 + 启动横幅**（`db_config.verify_deployment_label/print_banner`，不符拒绝启动）；`device_pool.init_app`（**起一次性线程**，3s 后采集型号）；`device_discovery.init_app`（**起常驻扫描线程**）；`TaskManager(app=app)`（APScheduler + 看门狗 + 从库加载分组/任务 + 重注册 cron）；`ApkManager(app=app)` |
-
+| **D** | `:69-88` | `init_db(app)`（建表 → 补列 → 版本账本 → 唯一索引 → 默认管理员 → 旧 JSON 迁移）→ `notifier.init_app`（通知 dispatcher/sender 线程）与 `step_log.init_app`（步骤明细写线程）→ **恢复任务消费** `consume_pending_restore()` → **库环境标签校验 + 启动横幅**（`db_config.verify_deployment_label/print_banner`，不符拒绝启动）；`device_pool.init_app`（**刷一次 `serial→名称` 内存快照** + **起线程**：3s 后采集型号、另起 `device-names` 每 60s 刷名称）；`device_discovery.init_app`（**起常驻扫描线程**）；`device_battery.init_app`（**起常驻电量采集线程**）；`dedup.init_app`（**去重账本绑 app**，供任务线程/Web/清理自推 context）；`TaskManager(app=app)`（APScheduler + 看门狗 + 从库加载分组/任务 + 重注册 cron）；`ApkManager(app=app)`；`notifier.set_device_name_resolver(device_pool.name_of)`（通知里显示设备名而不是 IP，见 [NOTIFY.md](NOTIFY.md) §7） |
 ### 2.3 阶段 E~G：蓝图、巡检调度器、真正启动
 
 | 阶段 | 位置 | 做了什么 |
 |------|------|---------|
 | **E** | `:64-67` | `context.init(...)`；`register_blueprints(app)`（10 个蓝图）；`agent_api.set_app(app)`（供后台线程推 app context） |
-| **F** | `:71-80` | **第二个独立 APScheduler**：`CronTrigger(hour=3, minute=47)` 挂经验库巡检；失败仅 warning |
-| **G** | `:253-265`（`__main__`） | `_ensure_uiauto_running()`（拉起 uiautodev:20242，写 `data/uiauto.pid`，`atexit` 清理）→ `_preconnect_pool_devices()`（后台并发 connect 池内网络设备）→ `_run_server()`（候选端口依次 bind：`0.0.0.0:18050` → `127.0.0.1:18050` → `127.0.0.1:18051..18055`）；退出时 `mgr.shutdown()` + `device_discovery.shutdown()` + 停 uiautodev |
+| **F** | 同上附近 | **第二个独立 APScheduler**：`CronTrigger(hour=3, minute=47)` 挂经验库巡检、`hour=4, minute=13` 挂步骤明细清理（`_purge_step_log`）、`hour=4, minute=23` 挂去重记录清理（`_purge_done_mark`，只清 `day`/`hours` 桶）、`hour=4, minute=41` 挂发布计划清理（`_purge_video_plan`：僵尸占位回收 + 过期行）、`hour=4, minute=47` 挂素材文件清理（`_purge_video_files`）——时间刻意错开（都是删数据的大操作），各任务自建 app context；失败仅 warning。**僵尸回收是必须有的一步**：占位后崩溃的行没有它会永远卡在"推送中"，再也不会被取到 |
+| **G** | `__main__` | `_ensure_uiauto_running()`（拉起 uiautodev:20242，写 `data/uiauto.pid`，`atexit` 清理）→ `_preconnect_pool_devices()`（后台并发 connect 池内网络设备）→ `_purge_step_log_async()`（后台清理超期步骤明细）→ `_run_server()`（候选端口依次 bind：`0.0.0.0:18050` → `127.0.0.1:18050` → `127.0.0.1:18051..18055`）；退出时 `notifier.shutdown()` + `step_log.shutdown()` + `mgr.shutdown()` + `device_discovery.shutdown()` + `device_battery.shutdown()` + 停 uiautodev |
 
 > ⚠️ **阶段 A~F 在 import 期就会起线程/调度器**，只有 uiautodev 拉起与预连接在 `__main__` 分支。以 WSGI 方式 import 本模块会得到"半个启动"的进程——本地调试请直接 `python web_server.py`。
 
@@ -103,7 +104,9 @@
 | **巡检调度器** `BackgroundScheduler` | `web_server.py` | 经验库 AI 巡检 | 每日 03:47 |
 | `worker-watchdog` | `start_watchdog()` | `running/connecting` 心跳超时 → 标 `error` | 30s 检查 / 120s 阈值 |
 | `device-discovery` | `device_discovery.init_app` | 网段扫描 + 断联重连 | 首轮延迟 15s，之后 interval（默认 60s） |
+| `device-names` | `device_pool.init_app` | 刷 `serial → 名称` 内存快照（通知显示设备名用；只查库） | 60s（另有启动/增删改名时主动刷） |
 | `_refresh_models_bg` | `device_pool.init_app` | 启动后采集全部在线设备型号 | 一次性（3s 后） |
+| `device-battery` | `device_battery.init_app` | 采设备电量（`dumpsys battery` 只读）+ 低电量告警 | 首轮延迟 20s，之后 interval（默认 60s） |
 | `BaseWorker` × N | `TaskManager._run_with_retry` | 单设备任务执行 | 任务期 |
 | `_run_with_retry` × N | 同上 | 单设备重试循环 | 任务期 |
 | `fg-scan-once` | `_ForegroundScanner.scan_once` | 前台 App 扫描 | 手动触发，`Event` 防重入 |
@@ -112,6 +115,7 @@
 | 巡检手动线程 | `web/agent_api.py` | 手动触发巡检 | 按需 |
 | **通知 dispatcher** | `core/notifier.init_app` | 通知聚合 + 每 hook 限流 + 折叠摘要 | 常驻 1 个 |
 | **通知 sender ×3** | 同上 | 真实发 webhook（退避重试、环形记录） | 常驻 3 个 |
+| **步骤明细写线程** | `core/step_log.init_app` | 批量落库 `task_step_log`（队列满丢弃并计数） | 常驻 1 个 |
 
 两个 APScheduler 相互独立，时区均固定 `Asia/Shanghai`。
 
@@ -125,6 +129,7 @@
 | `_engine_lock` | `core/ocr.py` | OCR 引擎懒加载 + 推理串行 | 推理 0.2~0.5s，锁开销可忽略 |
 | `_scan_lock` / `_stop_event` | `core/device_discovery.py` | 定时/手动扫描互斥 | `acquire(blocking=False)` |
 | `_status_cache_lock` | `core/task_manager.py` | 状态缓存（TTL 5s） | 避免 `/api/status` 每次都查库 + adb |
+| `device_battery._lock` | `core/device_battery.py` | 电量缓存 `_cache` + 告警档位 `_tiers` | 采集线程 / `/api/status` / 告警状态机共用 |
 
 **无锁部分**：`device_pool` 与 `models` 不持显式锁，依赖"每次操作独立 app context" + 数据库自身的并发控制（MySQL 下是 InnoDB 行锁 + READ COMMITTED，回退 SQLite 时是 WAL + `busy_timeout=5000`）。
 
@@ -265,7 +270,7 @@ connecting ──获取设备──▶ u2 连接 ──▶ running ──▶ set
 
 ### 6.1 单页应用
 
-- 主页面 `templates/admin/monitor.html`：一个内联 `<style>` + 7 个 Tab 面板 + 7 个模态框容器 + 11 个 `<script src>`
+- 主页面 `templates/admin/monitor.html`：一个内联 `<style>` + 8 个 Tab 面板 + 10 个模态框容器 + 17 个 `<script src>`
 - 独立页面：`login.html`（登录）、`wall.html`（监控大屏，**完全自包含**，自带 CSS/JS，不加载 `static/admin/*.js`）
 - 服务端内联页：`GET /locate`（设备端定位大字页，免登录）
 - 响应头强制 `no-store`，避免后台改版后浏览器拿旧页面
@@ -275,12 +280,13 @@ connecting ──获取设备──▶ u2 连接 ──▶ running ──▶ set
 | 顶级 Tab | `data-tab` | 权限 | 子分栏 |
 |---------|-----------|------|--------|
 | 监控 | `monitor` | 登录即可 | — |
-| 任务 | `tasks` | 登录即可（写操作需 `tasks`） | `plan` 任务计划 / `actions` 自定义动作 |
+| **发布计划** | `plan` | `devices` | 上传视频与标题（按**名字**配对）、时间线、推送到手机、导出链接 + **发布任务就地编辑**（见 [DATA_MODEL.md](DATA_MODEL.md) §2.11）。2026-10-12 起「账号台账」整页下线（表保留），本页从「账号」页的子分栏升为一级页签 |
+| 任务 | `tasks` | 登录即可（写操作需 `tasks`） | `plan` 任务计划 / `actions` 自定义动作 / `actioncfg` 动作配置 / `dedup` 去重记录 |
 | 日志 | `logs` | `logs` | — |
 | 用户 | `users` | `admin` | — |
 | 工具 | `tools` | `admin` | `clipboard` / `adb` / `ts` / `apks` / `appver` / `devapps` / `devpool` / `groups` |
 | AI 控制台 | `agent` | `admin` | — |
-| 系统 | `system` | `admin` | `backup` 数据备份 / `restore` 导入恢复 |
+| 系统 | `system` | `admin` | `backup` 数据备份 / `restore` 导入恢复 / `notify` 通知 Webhook |
 
 子分栏会记住上次选中位置（`_activeSubs`）；`devpool` 子分栏自带 10s 轮询，切走即停。
 
@@ -291,10 +297,12 @@ connecting ──获取设备──▶ u2 连接 ──▶ running ──▶ set
 | `base.js` | esc / CSRF / 权限 / API 封装 / Toast / Tab 与子分栏切换 / 模态框 / 常量表 | 所有模块的公共底座 |
 | `markdown.js` | 轻量 Markdown 渲染（`renderMarkdown`） | 无 CDN 依赖；**先转义再套标记** |
 | `list.js` | 统一列表组件：搜索 + 分页 + 排序 | 状态注册表 `_LIST_PAGERS`；`setListPager` **不重置**页码/搜索/排序（避免轮询刷新打断用户） |
-| `monitor.js` | 监控页：设备表、批量操作、异常汇总、任务概况卡片（含覆盖设备 chip） | 5s 轮询 + 脏检查（签名不变不重渲染） |
-| `editor.js` | 步骤编辑器（拖拽 / 参数表单 / 条件分支 / 元素抓取 / 测试此步骤）+ `saveTask` | 最大的前端文件；`_stepEditor` 单例 |
+| `release.js` | 发布计划页（时间线按日期分组 / 多选**素材（视频/图片）**串行上传 + 逐文件进度与结果 / 标题+正文 txt 上传（`标题 || 正文_名字_日期_编号`，卡片与明细**以名字为主**）/ 推送到手机 + **一键推送**（当天全部，**按名字找设备**：实时探测哪台在线设备登着这个号，逐条报出"没有设备登着"的号）、相册校验徽章与裁决 / 链接复制与导出 CSV / **发布任务的就地编辑**） | 服务层 `core/video_plan.py`（实时探测在 `core/account_probe.py`）；上传前把队列**按文件名排序**并让用户确认解析结果（顺序 = "无编号按顺序配"的依据）。就地编辑只放常用字段（名字/目标/时间/启停/逐步参数 + 抓取元素），更复杂的编排走「打开通用编辑器」→ `openTaskModal`；步骤路径里 `then/else/children` 在**步骤的 params 下**（`_rpWalk`），走错这一层会把分支当数组下标用 |
+| `monitor.js` | 监控页：设备表（含**电量列**，按 `battery.tier` 上色）、批量操作、异常汇总、任务概况卡片（含覆盖设备 chip） | 5s 轮询 + 脏检查（签名不变不重渲染） |
+| `editor.js` | 步骤编辑器（拖拽 / 参数表单 / 条件分支 / 元素抓取 / 测试此步骤）+ `saveTask` | 最大的前端文件；`_stepEditor` 单例；设备选择卡 `_devCard` 供「抓取元素」「测试此步骤」共用（**名字优先**，型号·地址作副标题） |
 | `tasks.js` | 任务 Tab：任务 CRUD / 调度解析 / 运行窗口 + 自定义动作 | |
-| `tools.js` | 工具 Tab：剪贴板、adb 终端、Tailscale、设备池、自动发现、远程看屏 | |
+| `tools.js` | 工具 Tab：剪贴板、adb 终端、Tailscale、设备池、自动发现、远程看屏、**电量监控配置**（阈值/间隔/立即采集） | 电量表单只回填一次，10s 轮询不冲掉用户正在输的值 |
+| `dedup.js` | 任务 Tab·**去重记录**：账本列表 + 统计（"今天做了几个号"）+ 删单条/清空任务 | 数据来自 `done_mark` 表，见 [TASK_DEV.md](TASK_DEV.md) §4.6 |
 | `apps.js` | 应用管理：APK 上传/安装/删除、设备已装应用 | |
 | `admin.js` | 分组、日志、用户 + **全局初始化入口**（末尾 `initCsrf(); loadMe(); showTab('monitor')`） | |
 | `agent.js` | AI 控制台·聊天：会话、SSE 流、Markdown / 推理链 / token 渲染、实时画面、经验库 / 动作库 | |

doc/DATA_MODEL.md

@@ -16,7 +16,7 @@
 | SQLite 回退时的 PRAGMA | `journal_mode=WAL`、`busy_timeout=5000`、`synchronous=NORMAL`（监听器按连接类型守卫，MySQL 连接不会执行） |
 | 建表方式 | **唯一真相是模型**：`db.create_all()`（建缺表）+ `_sync_columns()`（补缺列）；`SCHEMA_MIGRATIONS` 只作版本账本与数据回填 |
 | 库位置 | MySQL：由 `DB_HOST/DB_NAME` 指定；SQLite：`data/users.db` |
-| 当前 schema 版本 | `app_meta.schema_version = 6` |
+| 当前 schema 版本 | `app_meta.schema_version = 11`（迁移清单见 `core/models.py` 的 `SCHEMA_MIGRATIONS`：建表/补列以模型为准，这里只作版本账本） |
 
 **环境与库的绑定**（防混库，见 [DEPLOY.md](DEPLOY.md) §2.2）
 
@@ -27,7 +27,7 @@
 
 启动时校验「`.env` 声明」与「库名」「库中登记的 `app_meta.deployment_env`」三方一致，不符**拒绝启动**。
 
-**表清单（12 张，全部是 `core/models.py` 里的 ORM 模型）**
+**表清单（17 张，全部是 `core/models.py` 里的 ORM 模型）**
 
 | # | 表 | 用途 |
 |---|---|------|
@@ -44,6 +44,10 @@
 | 11 | `experience_audit` | 经验巡检结论 |
 | 12 | `agent_action` | 动作库（命名动作） |
 | 13 | `device_install_log` | 设备端应用商店的下载/安装记录（设备上报，见 [DEVICE_AGENT.md](DEVICE_AGENT.md)） |
+| 14 | `task_step_log` | 任务步骤明细（每次步骤执行一条，见 §2.8；**唯一有无界增长风险的表**，靠保留期清理） |
+| 15 | `done_mark` | 去重账本：跨设备"已做过"标记（见 §2.9；本清单此前漏列，2026-09-24 补上） |
+| 16 | `device_account` | **已停用**：账号台账（见 §2.10；2026-10-12 起页面/接口/任务依赖全部下线，**表和 42 行历史数据保留、仍在备份内**，可回滚） |
+| 17 | `video_plan` | 视频发布计划：**名字** × 发布日期 × 编号 → 素材 + 标题/正文 + 发布状态 + 分享链接（见 §2.11） |
 
 > 2026-09-13 之前，`app_meta` 与 4 张 `agent_*` 表是各模块里的裸 `CREATE TABLE`
 > （不进模型层）。迁 MySQL 时那批 SQL 的 `AUTOINCREMENT`/`TEXT DEFAULT ''`/`TEXT PRIMARY KEY`
@@ -124,6 +128,7 @@
 | `note` | Text | `""` | |
 | `created_at` | String(20) | `""` | |
 | `fingerprint` | String(120) | `""` | **设备指纹**（`ro.serialno`，迁移 v5 追加）：同一台物理设备换 IP 后据此认领回原记录 |
+| `cur_account_name` / `cur_name_at` | String(80)/String(20) | `""` | **上次探测到的抖音当前账号名字**（迁移 v13 追加）：只有「按名字找设备」（计划页的推送）会写它。**纯缓存** —— 自动任务永远现场读屏幕，缓存旧了也不影响发布的正确性；界面上带时间戳显示 |
 
 ### 2.7 `pending_device` — 待确认的发现设备
 
@@ -136,6 +141,158 @@
 
 > ⚠️ SQLAlchemy 模型的 `default=` 是 **Python 侧默认值**，SQLite 建表语句里没有 `DEFAULT` 子句；只有原生建表的表才有真正的 SQL DEFAULT。
 
+### 2.8 `task_step_log` — 任务步骤明细
+
+每一次步骤执行一条（`tasks/generic/task.py:_exec_one` 里记录），是「日志 → 步骤明细」
+页的数据源。与 `logs/task.log` 的分工：那边是**排障原文**（什么都写、10MB 滚动），
+这边是**结构化的一份**——设备/任务/步骤/结果/耗时都是列，能过滤、能统计、能导出 CSV。
+
+| 列 | 类型 | 默认 | 说明 |
+|----|------|------|------|
+| `id` | Integer | — | 主键 |
+| `run_id` | String(24) | `""` | 一次运行 = 设备 × 任务 × 第几次尝试；`TaskManager._run_with_retry` 每次尝试生成一个（12 位 hex），把这次尝试的所有步骤串起来 |
+| `job_id` / `job_name` | String(32/120) | `""` | 任务快照（任务删了明细还在，名字仍可读） |
+| `serial` / `device_name` | String(120/80) | `""` | 设备地址与**当时**的名字（快照，改名不影响历史） |
+| `step_path` | String(32) | `""` | 嵌套位置，如 `2.1.3`；容器步骤（loop/group/if_el）会记自己那条，children 追加一级 |
+| `step_label` / `step_type` | String(120/40) | `""` | 步骤标签与类型（`click_el`/`loop`/`wait`…） |
+| `selector` | String(300) | `""` | 元素选择器（长选择器截断） |
+| `result` | String(16) | `""` | `ok` / `miss`（handler 返回 False）/ `error`（抛异常）/ `unknown`（未知步骤类型）/ `skip`（概率未触发）/ `cap`（本次运行已达上限） |
+| `detail` | String(500) | `""` | 异常消息、跳过原因等 |
+| `duration_ms` | Integer | `0` | 本步耗时（慢步骤一眼可辨） |
+| `created_at` | String(20) | `""` | 执行时刻（**保留期按它算**） |
+
+索引：`run_id`、`created_at`、`(serial, created_at)`、`(job_id, created_at)`。
+
+**两条硬边界**（都在 `core/step_log.py`）：
+
+| 常量 | 默认 | 作用 |
+|---|---|---|
+| `MAX_ROWS_PER_RUN` | 2000 | 单次运行最多记 2000 条，超出只补一条 `cap` 说明行。**没有它，`forever` 循环任务会瞬间写爆这张表** |
+| `KEEP_DAYS` | 14 | 保留期：每天 04:13（+ 每次启动）清理更早的记录 |
+
+> ⚠️ **这张表是唯一有无界增长风险的表**，而它会**自动进整库备份**（§6 的派生规则），
+> 所以 `KEEP_DAYS` 直接决定备份包体积。调大之前先想清楚导出的 zip 会有多大。
+
+写入走 `core/step_log.py` 的**专用写线程 + 有界队列**（任务线程只 `put_nowait`，
+微秒级；队列满丢弃并计数）——步骤执行是热路径，绝不能在任务线程里同步写库。
+
+### 2.9 `done_mark` — 去重账本（跨设备"已做过"）
+
+| 列 | 类型 | 说明 |
+|----|------|------|
+| `id` | Integer PK | |
+| `scope_key` | String(300) **UNIQUE** | **幂等的全部依据**：`任务ID \| 身份值 \| 时间桶` |
+| `kind` | String(12) | `day` / `hours` / `all`（有效期策略，任务级 `dedup_reset`） |
+| `job_id` | String(32) idx | 哪个任务 |
+| `job_name` | String(120) | |
+| `serial` / `device_name` | String | 哪台设备（界面上显示"谁做过了"） |
+| `identity` | String(200) | 身份值（如抖音号 `35377983067`） |
+| `created_at` | String(20) idx | |
+
+索引：`job_id`、`created_at`、`(job_id, created_at)`。
+
+**为什么靠唯一索引**：多台设备会同时判断"没做过"，"先查后插"有竞态（两台都插）；
+唯一索引 + `INSERT ... ON DUPLICATE KEY`/`INSERT OR IGNORE` 的**受影响行数**才是原子的。
+实现在 `core/dedup.py`（`check` / `mark` / `list_marks` / `delete_mark` / `clear_job` / `purge_old`）。
+
+**保留期**：每天 04:23 清理过保留期（`core/dedup.KEEP_DAYS`，默认 180 天）的记录，
+但**只清 `day`/`hours` 桶**——`kind='all'`（"只做一次"）清了就等于去重失效，永不清理。
+量级很小（设备数 × 天数），单条 DELETE 足够，不需要像步骤明细那样分批。
+
+⚠️ 这张表**自动进整库备份**（§6 派生规则）；接任务步骤见 [TASK_DEV.md](TASK_DEV.md) §4.6。
+
+### 2.10 `device_account` — 账号台账（**已停用，表保留**）
+
+> **2026-10-12：账号管理整块下线。** 页面（「账号」页）、接口（`/api/ledger*`）、
+> 服务层（`core/ledger.py` 已删）、任务取号（`cmp_source=device/all/group`）、
+> 设备端身份页的账号块（`accounts_b64`）、设备池的「账号 N」列**全部移除**。
+>
+> 为什么留着表和这 42 行数据：**删数据不可逆**，而这张表在备份清单里（红线：功能涉及的数据
+> 必须纳入备份）—— 先停用、确认稳定后再单开一次清理动作。
+> 发布计划改走**名字**（见 §2.11），不再需要台账。
+>
+> 唯一从 `core/ledger.py` 迁走的是 `serial_of(设备名) → 当前地址`（与账号无关），
+> 现在在 `core/device_pool.py`。
+
+历史结构（停用前）：一台设备上登录着哪些账号。「账号」页维护。
+
+| 列 | 类型 | 说明 |
+|----|------|------|
+| `id` | String(32) PK | uuid 前 8 位 |
+| `device_name` | String(80) **index** | 设备号（= 设备池里的**设备名**，如 `A01`） |
+| `serial` | String(120) | 录入时的**地址快照**（设备换 IP / 改名后台账仍能靠任一侧找回） |
+| `phone` | String(32) index | 手机号 |
+| `nickname` | String(80) | 账号名称 |
+| `douyin_id` | String(64) index | **抖音号（纯号）**，如 `35377983067` |
+| `registered_at` | String(20) | 注册时间（**原样存文本**，如 `2026/9/24`） |
+| `sim_in_device` | Boolean | 卡在机内（**空 = 否**） |
+| `can_post_video` | Boolean | 可发视频（**空 = 否**） |
+| `bio` / `note` | Text | 简介 / 备注 |
+| `created_at` / `updated_at` | String(20) | 字符串时间（仓库惯例） |
+
+**（停用前的）三个使用方**：① web「账号」页（列表/增删改/从 Excel 粘贴导入）；
+② 任务「条件判断」取号（`cmp_source=device/all/group`）；③ 手机端 Agent 的身份大字页（`accounts_b64`）。
+**三个都已移除**；发布计划现在按**名字**走（§2.11）。
+
+⚠️ 历史提醒：`douyin_id` 是纯号，**绝不能当去重身份**（`done_mark.identity` 存的是元素原文、
+逐字算 key，格式不一致会让去重静默失效）—— 这是当年 `cmp_source` 取号的边界，
+现在候选值来自"本次要发的名字"，同理不得拿去填 `ident_value`。
+
+这张表**仍在整库备份内**（§6 派生规则）—— 停用不等于删数据。
+
+### 2.11 `video_plan` — 视频发布计划（**一个名字**在某天要发的一个视频）
+
+「发布计划」页维护；服务层 `core/video_plan.py`，接口 `/api/video_plan/*`（见 [API.md](API.md) §2.14），
+任务步骤「发布视频」按它自动发布（见 [TASK_DEV.md](TASK_DEV.md) §4.7）。
+**素材文件（视频/图片）**落在 `data/videos/YYYY-MM/`（文件名 `{sha1[:12]}_{安全原名}`，内容寻址），**不进整库备份**（§6）。
+
+| 列 | 类型 | 说明 |
+|----|------|------|
+| `id` | String(32) PK | uuid 前 8 位 |
+| `nickname` | String(80) | **识别键**：上传文件名里的**名字**（= 抖音昵称）。运行时就按它取计划、找设备/账号 |
+| `account_id` / `phone` / `douyin_id` / `device_name` / `serial` | String | **已停用**（老台账快照，保留列不再写入）：账号 id / 手机号 / 抖音号 / 设备号 / 地址 |
+| `release_date` | String(10) index | **`2026-09-12`** 纯日期（等值比较走索引） |
+| `seq` / `seq_auto` | Integer / Boolean | 编号从 **1** 起（不用 0 表示"无"）；`seq_auto`=号是自动分配的 |
+| `title` | Text | **标题**（发布页的「标题」框；标题 txt 配对写入） |
+| `body` | Text | **正文/文案**（发布页的文案框，可带 `#话题`）—— 标题 txt 一行里用 `||` 分隔：`标题 || 正文_名字_日期_编号`；**标题与正文都为空的行不会被发布** |
+| `video_file` / `video_name` / `video_size` / `video_sha1` | 各自 | **素材**（视频或图片，看扩展名）：落盘相对路径 / 原始名 / 大小 / 内容指纹（重复上传判据）。推送时**扩展名原样带到手机**——抖音按它判断视频还是图文 |
+| `status` | String(16) index | 见下方状态机 |
+| `stage` | String(16) | 失败发生在哪一步：`push`/`scan`/`post`/`verify` |
+| `attempts` | Integer | 尝试次数（上限 3，超了不再自动取） |
+| `published_at` / `share_url` / `link_at` / `video_deleted_at` | String | 发布时刻 / **作品分享链接** / 抓到链接的时刻 / 素材何时清理 |
+| `push_verify` / `push_remote` | String(16)/String(200) | **推送后的相册校验**：`ok`=已进相册索引 / `no_index`=文件在但没进索引（相册里可能看不到）/ `nofile`=文件不在；`push_remote` = 推到手机上的绝对路径（删它、排查用）。**文件推上去了 ≠ 相册里点得到它**，所以单独存一列而不是混进 `last_error` |
+| `posted_serial` / `posted_device_name` | String(120)/String(80) | **实际是哪台设备发的**（推送时现场写）。计划不再绑设备，所以"这条最后是谁发的"只能这么记 —— 排查"怎么发到那台机器上去了"全靠它 |
+| `last_error` / `note` / `created_at` / `updated_at` | | 失败原因 / 人工备注 / 时间 |
+
+**状态机**（本表的灵魂，别简化）：
+
+```
+pending    有视频、还没标题              ready      素材齐，等推送
+pushing    已推到手机（等人/用户的步骤去发）  done       已发布（终态）
+skipped    人工跳过（终态）              failed     推送阶段就失败 —— 还没到抖音，**可安全重试**
+unknown    推送之后出的岔子 —— **可能已经发出去了，绝不自动重试**，要人工裁决
+```
+
+> **平台只负责把素材推到手机**（`push_release` 步骤 / 计划页「推送到手机」）：
+> 推文件 → 触发相册刷新 → 把标题写进手机剪贴板。**抖音里怎么发由用户在任务画布上自己写**，
+> 最后放一个 `mark_release`「标记发布结果」回写这里的状态（`published`→`done`、`failed`、`unknown`）。
+> 这样抖音改版时用户改自己的步骤即可，不用等平台发版。
+
+> ⚠ **`failed` 与 `unknown` 必须分开**：把"不知道自己发没发"混成"知道自己没发"，
+> 就是重复发布的来源。`stage` 是两者互相转换的唯一依据（`core/video_plan.STAGE_STATUS`）。
+> 界面上的 `unknown` 卡片标橙 + 硬提示，人工到抖音确认后点「已发出 / 未发出」裁决。
+
+**唯一性**：`(nickname, release_date, seq)` 由**服务层**保证，**不加 DB 唯一索引** ——
+`seq` 从 1 起、没有"空值"可言，做部分唯一索引要写三处方言适配 + MySQL 生成列（§4.2），
+收益不匹配；违反的代价只是低频人工上传产生的重复行（可见、可删）。
+
+**索引**：`(release_date,status)` 时间线主查询 · `(nickname,release_date)` **按名字取计划/查重**（主路径）·
+`(account_id,release_date)` · `(phone,release_date,seq)` 老台账路径（已停用，保留）· `(video_file)` 清理时反查引用。
+后三个里带 `account_id`/`phone` 的两个是历史遗留（账号台账停用后不再走），等确认稳定后一并清理。
+`ix_video_plan_name_date` 由 `_ensure_plain_indexes()` 在启动时补建（`create_all` 不管已有表的新索引）。
+
+这张表**自动进整库备份**（§6 派生规则）；**素材文件不进备份包**，见 §6 与 §7。
+
 ---
 
 ## 3. 非模型表
@@ -241,6 +398,8 @@ UTF-8 等价于字节序）。
 | `deployment_id` | 库唯一标识（uuid），用于识别"这份备份来自哪个库" | 同上 |
 | `deployment_claimed_at` | 标签写入时间 | 同上 |
 | `notify_webhooks` | **通知 / Webhook 全部配置**（JSON：`{version, settings, webhooks[]}`，见 [NOTIFY.md](NOTIFY.md) §4）。**不建表**——新增/删除 webhook 都只改这一个键 | 系统 → 通知 页 |
+| `step_defaults` | **步骤默认值**（JSON：`{步骤类型: {字段: 值}}`，见 [TASK_DEV.md](TASK_DEV.md) §3.1）。新建步骤时预填用。**只存与出厂值不同的字段**，这样以后调出厂默认能跟着走 | 任务 → 动作配置 页 |
+| `device_battery` | **电量监控配置**（JSON：`{enabled, low, critical, skip_charging, interval}`，见 [NOTIFY.md](NOTIFY.md) §3.1）。**只存与出厂值不同的字段**（出厂：`low=20 critical=10 skip_charging=true interval=60`）。**电量本身不落库**——只放采集线程的内存缓存（重启重新采一轮），所以没有对应表、不动备份覆盖清单 | 工具 → 设备发现 → 电量监控 |
 
 > ⚠️ `agent_api_key` 是**明文存储**，导出备份的 zip 里也含它——备份预览会固定给出"含敏感信息"告警。
 > **同理 `notify_webhooks` 里的 webhook URL 本身就是凭据**（企业微信 `?key=`、钉钉 `?access_token=`、
@@ -268,6 +427,11 @@ SUMMARY_TABLES = tuple(sorted(t.name for t in db.metadata.tables.values()))
 - **导入侧**：备份里出现未登记的表（排除 `sqlite_` 前缀）→ 预览告警（字段 `extra_tables`）
 - `REQUIRED_TABLES = (app_meta, user, task_job, device_group)`：缺任一直接拒绝导入（这四项是"判定这是不是本平台备份"的最小集合，故意手工维护）
 
+> **素材文件不进备份包**：`create_export()` 只打包 `data/apks/*.apk`，**不含 `data/videos/`**
+> （几十 GB 会把"数据库备份"这个核心能力搞坏）。备份的 `manifest.json` 里有
+> `videos.included=false` + 数量/字节数，备份预览页也会提示"素材需另外备份 `data/videos/`"
+> —— **不能让人以为备份了**。恢复后素材要重新上传（计划与发布状态、分享链接都在表里，已备份）。
+
 > **红线**：新增持久化表时**同时补 `TABLE_LABELS` 的中文标签**并更新 [DEPLOY.md](DEPLOY.md) §数据备份。
 > 覆盖清单本身不再需要手工登记（已由 metadata 派生）。历史教训：`agent_action` 曾漏登记，
 > 导致"动作库看起来没备份"（数据其实在快照里，只是清单没列）。
@@ -280,6 +444,7 @@ SUMMARY_TABLES = tuple(sorted(t.name for t in db.metadata.tables.values()))
 |------|------|--------|
 | `data/users.db`(+`-wal`/`-shm`) | SQLite 主库（**仅回退模式用**；连 MySQL 时这些文件不被读写，可留作历史归档） | 否 |
 | `data/apks/*.apk` | 上传的 APK | 否 |
+| `data/videos/YYYY-MM/*` | 视频发布计划的素材（几百 MB 一个；**不进整库备份**，见 §6） | 否 |
 | `data/backups/` | 导出临时 zip、`pre_restore_*.zip`（导入前安全网）、`restore_failed_*` | 否 |
 | `data/restore_staging/<token>/` | 导入暂存（TTL 1800s 自动清理） | 否 |
 | `data/restore_pending/` | 待生效恢复任务（重启时单事务消费） | 否 |

doc/DEPLOY.md

@@ -71,8 +71,17 @@ DB_NAME=auto_control
 # USB_ADB_HOST=100.100.10.1             # USB 设备所在的部署机（默认值通常可用）
 # TAILSCALE_API_KEY=<...>               # 需要 Tailscale 管理功能时
 # MCP_PLATFORM_PASS=<admin 的密码>       # 改过 admin 密码必须同步，否则 MCP 登录失败
+
+# 发布计划按名字发：抖音「我」页面上的**昵称控件**（用「抓取元素」抓一次，见 .env.example）
+# DOUYIN_NAME_SELECTOR_VALUE=
+# 自动切号：进「账号切换」列表那个入口（同样抓一次）
+# DOUYIN_SWITCH_SELECTOR_VALUE=
 ```
 
+> ⚠ **发布计划相关的两个选择器必须抓一次**（`DOUYIN_NAME_SELECTOR_VALUE` /
+> `DOUYIN_SWITCH_SELECTOR_VALUE`）：不填时「读取本机账号名字」「切换账号」会**明确报错并跳过**
+> （不会瞎点、不会发错号），但也就发不出视频。改完 `.env` 要重启容器生效。
+
 **防混库**（`DEPLOY_ENV` 与库名/库标签双向校验，配置项说明见 [DEVELOPMENT.md](DEVELOPMENT.md) §4.2
 与 `.env.example` 的「数据库」段）：启动时若
 「`.env` 声明的环境」与「库名」或「库中登记的 `app_meta.deployment_env`」不符，**直接拒绝启动**并打印
@@ -212,15 +221,31 @@ tail -20 logs/web.log                              # 无 ERROR/Traceback
 SUMMARY_TABLES = tuple(sorted(t.name for t in db.metadata.tables.values()))
 ```
 
-当前 12 张表：`app_meta` / `user` / `device_group` / `task_job` / `custom_action` /
+当前 17 张表：`app_meta` / `user` / `device_group` / `task_job` / `custom_action` /
 `apk_file` / `device` / `pending_device` / `agent_conversation` / `agent_experience` /
-`experience_audit` / `agent_action`。完整说明见 [DATA_MODEL.md](DATA_MODEL.md) §6。
+`experience_audit` / `agent_action` / `device_install_log` / `task_step_log` / `done_mark` /
+`device_account`（账号台账，**已停用但仍在备份内**——停用不等于删数据）/ `video_plan`（视频发布计划）。
+完整说明见 [DATA_MODEL.md](DATA_MODEL.md) §6。
+
+> ⚠ **视频素材（`data/videos/`）不进备份包**（几十 GB 会把备份搞坏）：manifest 里有
+> `videos.included=false` 与数量/字节数，预览页也会提示 —— **素材要另外备份**。
+> 计划、发布状态与分享链接都在 `video_plan` 表里，随备份一起走。
+
+> ⚠️ `task_step_log`（任务步骤明细）是会持续增长的表：它按 `KEEP_DAYS`
+> （默认 14 天，见 `core/step_log.py`）自动清理，但备份包里会带上保留期内的全部行。
+> 设备多、任务密时导出 zip 会明显变大——需要更小的包就调小那个常量。
+> `done_mark`（去重账本）也会增长，但量级是"设备数 × 天数"，可以忽略；它同样有保留期
+> （默认 180 天，且 `kind='all'` 的记录**永不清理**）。
 
 > **新增一张 ORM 表，就自动进了覆盖清单**，不可能再漏（2026-09-10 动作库 `agent_action`
 > 曾因手工维护漏登记，数据其实在快照里，只是清单没列 → 被误判为"没有备份"）。
 > 还需要手工做的只有：给新表补 `TABLE_LABELS` 的中文标签。
 > 导出侧有**覆盖自检**（登记表缺失 → `manifest.coverage_missing` + 日志告警）；
 > 导入侧有**反向自检**（备份含未登记表 → 预览告警）。
+>
+> **回滚注意事项**：把"含新表的备份"导回**旧版本代码**时，旧代码的 `SUMMARY_TABLES`
+> 里没有那张新表 → 导入预览会报 `extra_tables` 告警。**数据仍在快照里、不会丢**，
+> 属于预期行为（升级回新版即可正常识别）。
 
 ### 5.3 目录与手工备份
 
@@ -251,7 +276,13 @@ SUMMARY_TABLES = tuple(sorted(t.name for t in db.metadata.tables.values()))
 - **HTTPS/80 端口**：用 Nginx 反代
 
 ```nginx
-location / { proxy_pass http://127.0.0.1:18050; proxy_set_header Host $host; }
+location / {
+    proxy_pass http://127.0.0.1:18050;
+    proxy_set_header Host $host;
+    # ⚠ 必须加：nginx 默认 client_max_body_size 只有 1m，
+    # 不加的话「应用管理」传 APK（有 336MB 的包）和视频素材上传都会 413。
+    client_max_body_size 2048m;
+}
 ```
 
 ---

doc/DEVELOPMENT.md

@@ -54,9 +54,10 @@
 | 1 | **绝不 `adb kill-server`** | 会断掉所有设备的 adb transport，运行中任务全废 | `core/adb_helper.py` 只 connect 不 kill；Web 层硬拦截 `kill-server`/`disconnect` 字符串 |
 | 2 | **绝不对 `IP:5555` 设备 `adb disconnect`** | 该地址的 adb transport 是共享的 | `adb_disconnect` **全项目零调用方**；`STFDevice.release()` 空实现 |
 | 3 | **空闲设备扫描不主动 connect/disconnect** | 避免扰动共享连接 | 前台扫描对空闲设备直接返回"空闲"；设备发现用 socket 探测 |
+| 3b | （3 的边界）**只读 `adb -s <serial> shell …` 是允许的**，它不建立/断开 transport | 设备已在 `adb devices` 里就说明 transport 现成，读一下不扰动任何人 | 电量采集 `core/device_battery.py` 就是这么读**包括空闲设备在内**的全部在线设备（`dumpsys battery`，实测 0.2~0.35s/台）；**别"顺手"给它加 connect** |
 | 4 | **adb key 保持历史 key 不变** | 设备信任该 key，换 key 全部 `unauthorized` | 部署沿用 `~/.android/adbkey` |
 | 5 | **生产（220）默认只读** | 生产事故成本高 | 任何写操作（pull/重启/改文件）都需负责人确认 |
-| 6 | **新增持久化表必须登记备份覆盖清单** | 漏登记 = 等于没备份 | `core/system_backup.py` 的 `SUMMARY_TABLES` + `TABLE_LABELS`，详见 [DEPLOY.md](DEPLOY.md) §5.2 |
+| 6 | **新增持久化表必须进备份覆盖清单** | 漏登记 = 等于没备份 | `SUMMARY_TABLES` 已由模型元数据自动派生（加了 ORM 表就进清单）；**手工要做的只有补 `TABLE_LABELS` 中文标签**，详见 [DEPLOY.md](DEPLOY.md) §5.2 |
 | 7 | **功能/配置/接口改动必须同步文档** | 文档落后会误导开发与运维 | 见 §6；索引 [doc/README.md](README.md) |
 
 ### 其它开发约束
@@ -106,6 +107,7 @@ MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<密码> \
 | 后端逻辑验证 | 直接 `python -c "…"` 调用 `core/`、`tasks/` 的函数（如构造 worker 检查参数合并） |
 | 前端验证 | 无 npm/构建，改完强刷；浏览器控制台看报错 |
 | 接口 500 巡检 | `python scripts/regression_test.py`（**⚠️ 当前在 Windows 上会因 `signal.alarm` 报错**，Linux/macOS 可用） |
+| 发布计划（按名字发）用例 | `python scripts/tests/run_all.py` —— 6 套：解析 / 上传配标题 / 读名字与作用域 / 切换账号 / 循环本机待发的号 / 按名字找设备推送。**纯临时库 + 假设备，不连真机**（见 `scripts/tests/run_all.py` 顶部） |
 | 停止设备/清异常 | 监控页「停止全部 / 停止选中 / 清除全部异常」 |
 | AI 建任务（designer）验证 | AI 控制台 →「AI 建任务」选**空闲**设备跑一轮；脚本方式见 [AI_TASK_GEN.md](AI_TASK_GEN.md) §10.5。草稿只落 `app_meta.agent_task_draft`（不是任务），验证完 `POST /api/agent/task_draft/clear` 清掉。**注意它会真在设备上点按**（导航类动作），且与聊天共用同一个运行槽 |
 
@@ -139,6 +141,8 @@ MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<密码> \
 | `WEB_HOST` / `WEB_PORT` | `0.0.0.0` / `18050` | 硬编码 | 18050 避开 Windows 动态端口段 |
 | `DATA_DIR` / `APK_DIR` | `data/` / `data/apks/` | 代码计算 | |
 | `BACKUP_DIR` / `RESTORE_STAGING_DIR` / `RESTORE_PENDING_DIR` | `data/backups` / `data/restore_staging` / `data/restore_pending` | 代码计算 | 备份相关 |
+| `VIDEO_DIR` | `data/videos` | `DATA_VIDEO_DIR` | 视频发布计划的素材目录（**不进整库备份**；测试要指到临时目录） |
+| `MAX_CONTENT_LENGTH` | 2 GiB | `MAX_UPLOAD_MB` | 单次上传体积上限；**必须大于最大的 APK（实测 336MB）**，否则 APK 上传会被卡死 |
 | `DEPLOY_ENV` | `dev` | `.env` 可覆盖 | 声明这套配置连哪个环境的库；与库名绑定（dev→`auto_control_dev`，prod→`auto_control`），不符拒绝启动 |
 | `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASSWORD` / `DB_NAME` | 空 / `3306` / 空 / 空 / 空 | `.env` 可覆盖 | MySQL 目标；`DB_HOST` 为空则回退 SQLite（**生产禁止静默回退**，需 `DB_ALLOW_SQLITE_FALLBACK=1`） |
 | `DB_CHARSET` / `DB_COLLATION` | `utf8mb4` / `utf8mb4_bin` | `.env` 可覆盖 | 排序规则必须用 `_bin`（逐码点比较，等价 SQLite 的大小写敏感语义） |
@@ -184,9 +188,10 @@ MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<密码> \
 
 ### 5.2 新增数据库字段/表
 
-- 模型改 `core/models.py`；新表 `create_all()` 会建
+- 模型改 `core/models.py`；新表 `create_all()` 会建（**幂等**：已是模型就会自动建/补列）
 - **老库**要在 `SCHEMA_MIGRATIONS` 里加迁移（版本号递增 + SQL）
-- **新增表**：登记进 `core/system_backup.py` 的 `SUMMARY_TABLES` + `TABLE_LABELS`（**红线**）
+- **新增表**：`SUMMARY_TABLES` 由模型元数据**自动派生**（＝自动进备份覆盖清单），
+  仍需手工做的是补 `TABLE_LABELS` 的中文标签（**红线**）
 - 更新 [DATA_MODEL.md](DATA_MODEL.md) 与 [DEPLOY.md](DEPLOY.md) §5.2
 
 ### 5.3 修改前端
@@ -196,7 +201,7 @@ MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<密码> \
 | 页面结构 / 样式 / 引入脚本 | `templates/admin/monitor.html` |
 | 公共工具（API/权限/Toast/Tab） | `static/admin/base.js` |
 | 列表分页排序 | `static/admin/list.js` |
-| 各功能域逻辑 | `static/admin/{monitor,editor,tasks,tools,apps,admin,agent,system,markdown}.js` |
+| 各功能域逻辑 | `static/admin/{monitor,editor,tasks,tools,apps,admin,agent,system,markdown,dedup,release}.js` |
 
 新增 JS 模块：建文件 → 在 `monitor.html` 里按依赖顺序加 `<script src>` → 更新 [ARCHITECTURE.md](ARCHITECTURE.md) §6.3 与本文 §5.3。
 

doc/DEVICE_AGENT.md

@@ -192,8 +192,18 @@ adb -s <serial> shell am start -n <pkg>/.ClipActivity --es text_b64 <base64(UTF-
 
 - **必须 base64**：adb shell 直传中文/特殊字符会变形
 - 必须用**透明 Activity**（有焦点才能写剪贴板），写完**立即退出**
-- 平台判定失败的方式：`am start` 输出里有 `unable to resolve Intent` / `does not exist`
-  → 视为"设备未安装 Agent"
+- 平台判定失败的方式：`am start` 输出里有 `unable to resolve Intent` / `does not exist` /
+  `Error type 3` → 视为"这台设备没有这个通道"
+
+**平台按顺序试两个包**（`core/clipboard_helper.py` 的 `_CLIP_TARGETS`）：
+
+| 顺序 | 包 | 说明 |
+|---|---|---|
+| 1 | `com.example.deviceagent`（**本 Agent**） | 现在的标准通道；装了就只调它 |
+| 2 | `com.example.clipinject`（早期独立 APK） | 老设备上可能还残留 → 兜底；走这条会在日志里提示"建议装设备端 Agent" |
+
+两个都没有时报"设备未安装剪贴板注入通道：需要设备端 Agent"（不再只说 ClipInject，
+否则用户会去装那个已经不再分发的旧 APK）。**设备端无需为这条改动做任何事**。
 
 ### 5.2 设备身份显示（设备端已实现）
 
@@ -239,6 +249,9 @@ adb -s <serial> shell am start -n <pkg>/.ConfigActivity \
 
 ## 6. 版本与兼容
 
+- 身份页 extras（`name`/`ip`/`serial`/`server`/`close`）是**平台单向下发**：设备端多收/少收
+  都不影响旧行为。（2026-10-12：账号台账下线，原先顺带下发的 `accounts_b64` 已不再发送 ——
+  设备端收到"没有这个 extra"时照旧只显示身份信息即可。）
 - `agent_api_version`（当前 **1**）在每次 `bootstrap` 响应里返回
 - **设备端**：启动时对比自己实现的版本，不一致要在日志里明确记下来（不要静默）
 - **平台端**：

doc/MCP.md

@@ -108,7 +108,7 @@ MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<平台密码> \
 | 工具 | 参数 | 说明 |
 |------|------|------|
 | `de_type_text` | `serial`, `text` | 向当前输入框输入（支持中文，直设 EditText，不依赖剪贴板） |
-| `de_set_clipboard` | `serial`, `text` | 写入设备剪贴板（ClipInject 通道 + 读回验证） |
+| `de_set_clipboard` | `serial`, `text` | 写入设备剪贴板（设备端 Agent 通道 + 读回验证） |
 
 ### 4.5 App 管理（**写操作**，走 adb 直连不建 u2 会话）
 

doc/MCP_DESIGN.md

@@ -58,8 +58,8 @@
 | 点击 | `POST /api/screen/tap {serial,x,y}` | 封装 tool `tap` |
 | 滑动 | `POST /api/screen/swipe` | 封装 `swipe` |
 | 按键 | `POST /api/screen/key` | 封装 `press_key` |
-| 输入文字 | ClipInject 通道（core.clipboard_helper）+ u2 input | 封装 `type_text` |
-| 剪贴板 | `POST /api/tools/clipboard/set`（ClipInject 通道） | 封装 `set_clipboard` |
+| 输入文字 | 设备端 Agent 通道（core.clipboard_helper）+ u2 input | 封装 `type_text` |
+| 剪贴板 | `POST /api/tools/clipboard/set`（设备端 Agent 通道） | 封装 `set_clipboard` |
 | 元素树 | `GET /api/uiauto/...`（uiautodev） | 封装 `get_ui_tree` |
 | OCR | core.ocr（RapidOCR） | 封装 `ocr_screen` |
 | 打开 App | u2 `app_start`（经任务层/直连） | 封装 `open_app`（走 core device 直连） |
@@ -150,11 +150,11 @@
 - key ∈ back/home/recent/menu/power/enter/delete…
 
 #### `de_type_text(serial, text: str, clear_first: bool=True)`
-- 实现：优先 ClipInject 通道（`core.clipboard_helper.inject_clipboard` 语义：写入剪贴板 + paste 到焦点输入框），失败回退 u2 input
-- 中文/emoji 全支持（ClipInject 实测通过）
+- 实现：优先设备端 Agent 通道（`core/clipboard_helper.inject_clipboard` 语义：写入剪贴板 + paste 到焦点输入框），失败回退 u2 input
+- 中文/emoji 全支持（Agent 通道实测通过）
 
 #### `de_set_clipboard(serial, text: str)`
-- 写入设备剪贴板（ClipInject am start 通道），读回验证
+- 写入设备剪贴板（设备端 Agent 的 am start 通道），读回验证
 
 #### `de_open_app(serial, package: str)`
 - 打开指定 App（u2 app_start）；`package` 需在已知清单或完全限定名
@@ -247,7 +247,7 @@
 3. **横竖屏/分辨率异构**：设备多样 → 坐标换算依赖截图 1:1；`de_find_and_tap`（语义层）不受分辨率影响
 4. **图像 content block 兼容性**：Claude 系原生支持；其他多模态客户端需验证（M0 用 Claude Code 验证）
 5. **是否接任务系统**：二期决策——`de_run_task` 语义与"单设备操作"不同（任务面向多设备调度），倾向二期用独立命名空间
-6. **clipboard/input 通道差异**：个别 MIUI 需授权 ClipInject——M0 阶段在受控设备集验证，必要时 fallback 链已在 core 层
+6. **clipboard/input 通道差异**：个别 MIUI 需授权写入剪贴板的透明 Activity——M0 阶段在受控设备集验证，必要时 fallback 链已在 core 层（设备端 Agent → 旧版 ClipInject）
 
 ## 12. 附录：平台 API 映射（MCP → 平台）
 
@@ -262,8 +262,8 @@
 | de_press_key | POST /api/screen/key |
 | de_tap_text | POST /api/screen/tap_text（UI 树子串匹配 → OCR 兜底） |
 | de_tap_element | u2 元素直连（uiautomator2 `d(by=value).click()`，无平台端点） |
-| de_type_text | u2 `EditText.set_text`（direct_ops.type_text，不走 ClipInject） |
-| de_set_clipboard | core.clipboard_helper ClipInject 通道（inject_clipboard，读回验证） |
+| de_type_text | u2 `EditText.set_text`（direct_ops.type_text，不走剪贴板通道） |
+| de_set_clipboard | core.clipboard_helper 设备端 Agent 通道（inject_clipboard，读回验证） |
 | de_read_clipboard | u2 `d.clipboard` |
 | de_open_app | adb monkey 直启（direct_ops.open_app） |
 | de_stop_app | adb `am force-stop`（direct_ops.stop_app） |

doc/NOTIFY.md

@@ -52,8 +52,11 @@ daemon 线程。所以：
 | 任务批次 | `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.page.mismatch`（「校验页面」没等到该出现的特征元素 —— **上一步没生效**，默认跳过本轮剩余步骤，避免在错的页面上继续盲点；见 TASK_DEV §4.7）/ `task.account.switch_failed`（切号失败：账号列表里没这个名字，或切完回读还是别人 —— **本轮不会发这个号的内容**，要人工到设备上确认号还在不在）/ `task.account.need_login`（抖音停在登录/验证码页，**需要人工登录**，平台绝不代替登录/过滑块；本设备已停止本轮任务）—— 都由「切换账号」步骤发出 |
+| 业务·任务自己发 | `task.notify.custom`（步骤「发通知」）/ `task.patrol.hit`（任务「公共巡检」命中）——**标题正文由任务自己写**，见下 |
 | Worker | `worker.connected` · `.attempt.done` · `.attempt.error`（单次尝试级，噪音大，默认没人勾） |
-| 设备 | `device.online` · `.offline` · `.discovered` · `.claimed` · `device.heartbeat_timeout` |
+| 设备 | `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` |
@@ -65,6 +68,71 @@ daemon 线程。所以：
 > 是"这台设备最终成功/失败"的**唯一权威点**。所以一个设备重试 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](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](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. 配置
@@ -147,13 +215,24 @@ Bark `/…/<key>`、Slack `/services/T…/B…/X…`）→ 接口回显、发送
 
 | 层 | 机制 | 默认 |
 |---|---|---|
-| L1 聚合 | 同 webhook、同事件、同聚合键（如 `job_id`）在一个窗口内合并成一条，保留前 3 个样本 | 30s（低频高危事件设 0，立即发） |
+| 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. 开发：给新功能加通知
@@ -170,6 +249,23 @@ Bark `/…/<key>`、Slack `/services/T…/B…/X…`）→ 接口回显、发送
 - 事件的 `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. 排障

doc/README.md

@@ -13,7 +13,7 @@
 | [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 概念、18 种步骤全表、选择器与定位、自定义动作、新增任务类型模板 | 写任务的开发 |
+| [TASK_DEV.md](TASK_DEV.md) | **任务与步骤开发**：TaskType/TaskJob 概念、24 种步骤全表、公共巡检、选择器与定位、自定义动作、新增任务类型模板 | 写任务的开发 |
 | [MCP.md](MCP.md) | **MCP 手机控制手册**：20 个 `de_*` 工具用法、写操作门控、坐标换算、接入示例 | 接入方、数字员工 |
 | [MCP_DESIGN.md](MCP_DESIGN.md) | **MCP 设计文档**：边界划分、错误码、白名单/审计设计、演进方向 | 平台开发者 |
 | [AI_CONSOLE.md](AI_CONSOLE.md) | **AI 控制台**：会话/SSE、经验库、动作库、巡检、Markdown 渲染、推理链、token 统计 | 使用者、平台开发者 |

doc/TASK_DEV.md

@@ -10,8 +10,8 @@
 
 - [1. 核心概念](#1-核心概念)
 - [2. 通用步骤任务 generic_steps](#2-通用步骤任务-generic_steps)
-- [3. 18 种步骤全表](#3-18-种步骤全表)
-- [4. 容器步骤与公共参数](#4-容器步骤与公共参数)
+- [3. 24 种步骤全表](#3-24-种步骤全表)（含 [3.1 步骤默认值与动作录制](#31-步骤默认值与动作录制任务--动作配置)）
+- [4. 容器步骤与公共参数](#4-容器步骤与公共参数)（含 [4.5 公共巡检](#45-公共巡检任务级独立于步骤画布)）
 - [5. 选择器与元素定位](#5-选择器与元素定位)
 - [6. 自定义动作](#6-自定义动作)
 - [7. 步骤编辑器（前端）](#7-步骤编辑器前端)
@@ -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. 18 种步骤全表
+## 3. 29 种步骤全表
 
 > 参数与默认值以 `tasks/generic/task.py` 为准；前端 `STEP_LIB`（`static/admin/editor.js`）负责在编辑器里呈现这些字段。
 
@@ -120,18 +121,147 @@ from .generic import task  # 触发 @register_task（当前唯一任务类型）
 | 4 | `screen_off` | 息屏 | — | — | — | `d.screen_off()` |
 | 5 | `keep_screen` | 保持亮屏 | `mode`("on") | — | — | `mode="off"` → 恢复自动息屏；否则**把系统息屏超时顶到最大**（`screen_off_timeout=2147483647`）+ `svc power stayon true` + 唤醒一次。⚠️ 只发 `svc power stayon true` 对**没插充电器**的设备（走 WiFi 的那些）**完全无效**——它管的是"充电时屏幕常亮"，2026-09-14 就是因此被反馈"保持亮屏没用" |
 | 6 | `key_event` | 按键 | `key`("back") | — | — | `d.press(key)`；**值直传，无白名单校验** |
-| 7 | `swipe` | 滑动 | `direction`("up") | `duration_min`(0.25)、`duration_max`(0.50) | — | 时长取随机值；up = 中轴从 0.8h → 0.2h（down 反向，left/right 同理）；**非法 direction 静默不滑** |
-| 8 | `swipe_until` | 滑动直到元素 | `selector_type`、`selector_value` | `direction`("up")、`max_swipes`(8)、`click_when_found`(True) | — | 每轮滑动后 sleep 0.5s；命中即（可选）点击并返回 True；**只有 `direction="down"` 才是向下滑**，其余按上滑 |
-| 9 | `click` | 点击元素 | `selector_type`、`selector_value` | `wait_timeout`(2) | — | xpath 用 `wait(timeout)`，其它选择器用 `exists(timeout)`；`wait_timeout=0` 为立即判断。**空选择器只告警** |
+| 7 | `swipe` | 滑动 | `direction`("up") | `duration_min`(0.25)、`duration_max`(0.50)、`distance_ratio`(0.6)、`jitter`(0.15)、`humanize`(True) | — | **默认拟人**：弧线轨迹 + 起止点/幅度/时长抖动 + 本设备手速偏好（见 §8.4）；`humanize:false` 还原老的「正中直线」；`jitter:0` 时位置/幅度不抖（时长仍随机）；**非法 direction 静默不滑** |
+| 8 | `swipe_until` | 滑动直到元素 | `selector_type`、`selector_value` | `direction`("up")、`max_swipes`(8)、`click_when_found`(True)、`duration_min`(0.25)、`duration_max`(0.50)、`distance_ratio`(0.6)、`jitter`(0.15)、`humanize`(True) | — | 每次滑动都重新生成轨迹（同 §8.4）；每轮滑动后随机停 0.35~0.75s；命中即（可选）点击并返回 True；**只有 `direction="down"` 才是向下滑**，其余按上滑 |
+| 9 | `click` | 点击元素 | `selector_type`、`selector_value` | `wait_timeout`(2) | — | xpath 用 `wait(timeout)`，其它选择器用 `exists(timeout)`；`wait_timeout=0` 为立即判断。**空选择器只告警**。选择器值里可以写 `{本次要发的名字}` / `{本机账号名字}`（见 §3.3）；按**文本包含**找用 `textContains`（例：账号列表里点 `textContains={本次要发的名字}`） |
 | 10 | `click_xy` | 点击坐标 | — | `x`(50)、`y`(50) | — | **屏幕百分比**（0-100，会夹取），50/50 = 屏幕中心。无选择器时的兜底，**最脆的方式** |
 | 11 | `long_click` | 长按元素 | `selector_type`、`selector_value` | `duration`(1.0)、`wait_timeout`(2) | — | 先等元素出现再 `long_click` |
 | 12 | `wait_el` | 等待元素 | `selector_type`、`selector_value` | `timeout`(10) | — | 等元素出现（条件等待，优于固定 `wait`） |
-| 13 | `input_text` | 输入文字 | — | `mode`("random")、`texts`("你好\n有趣\n支持")、`fixed_text`("")、`clear_first`(True) | — | `mode="fixed"` 用 `fixed_text`，否则从 `texts` 按行随机选一条；**只负责输入，不负责定位输入框**（要先 click 输入框） |
-| 14 | `clipboard` | 剪贴板注入 | `text` | `paste`(True) | — | 走 ClipInject 通道（绕开 Android 10+ 后台写剪贴板限制）；`paste=true` 时再触发一次粘贴 |
-| 15 | `wait` | 等待 | — | `min`(1.0)、`max`(3.0) | — | 随机时长；**分片 sleep**（每 ≤0.5s 检查停止/超时），可被抢占打断 |
+| 13 | `input_text` | 输入文字 | — | `mode`("random")、`texts`("你好\n有趣\n支持")、`fixed_text`("")、`clear_first`(True)、`text_source`("manual")、`release_topics`("") | — | `mode="fixed"` 用 `fixed_text`，否则从 `texts` 按行随机选一条；`text_source` 还可取**本机当前那条发布计划**的内容：`release_title`(±`_topics`) = 标题、`release_body`(±`_topics`) = 正文、`release_title_body` = 标题+正文（配 `release_topics` 自动加话题），**并回读输入框校验**（不校验就可能发出一篇空文案）；**只负责输入，不负责定位输入框**（要先 click 输入框） |
+| 14 | `clipboard` | 剪贴板注入 | `text` | `paste`(True) | — | 走**设备端 Agent** 通道（透明 Activity，绕开 Android 10+ 后台写剪贴板限制）；老设备上只有独立 ClipInject 时自动兜底（见 `core/clipboard_helper.py`）；`paste=true` 时再触发一次粘贴 |
+| 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 |
 | 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) | `then` / `else` | 见 §4.2 |
+| 18 | `if_el` | 条件判断 | `selector_type`、`selector_value`、`timeout`(3) | `ocr_click`(False)、`cmp_op`("")、`cmp_value`("")、`cmp_source`("")、`ident_type`/`ident_value`（去重身份） | `then` / `else` | 见 §4.2；条件类型除元素/OCR 外还支持 **屏幕状态**、**前台App**、**去重**（见 §4.6）；填 `cmp_op` 则改成**比元素的文本**（等于/不等于/包含/不包含，多值任一命中），候选值还可以由平台给：**本次要发的名字**（`cmp_source=account_target`）、**本机要发的那条发布计划**的名字（`cmp_source=release`）或**某个运行期变量**（`cmp_source=var` + `cmp_var=<变量名>`，变量由 `read_text` 写入）。**候选为空（名字读不到/变量是空的）→ 一律不命中**，这是设计如此（不知道登的是谁就不发） |
+| 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 |
+| 23 | `push_release` | 推送发布视频 | `date_source`(today/fixed)、`fixed_date` | `account`(name/phone)、`account_phone`、`album_dir`(/sdcard/DCIM/Camera)、`to_clipboard`(True)、`retry_failed`(True)、`max_same_run`(1) | — | 取**本次要发的那个名字**名下的「发布计划」→ **只把素材推到手机**（+ 触发相册刷新 + 标题写进剪贴板）。**不发布** —— 抖音流程你自己在后面画。`account=name`（默认）时**推送前会重读昵称核对**，对不上就不推。幂等靠原子占位（多设备/重跑不会重复推）。见 §4.7 |
+| 24 | `mark_release` | 标记发布结果 | `result`(published/failed/unknown)、`why` | `capture_link`(True)、`delete_phone`(True)、`album_dir` | — | 放在**你自己发布流程的末尾**：把"发出去了没有"回写到计划行（成功时顺手抓作品分享链接、删手机上的素材）。拿不准就填 `unknown` —— 平台不会自动重发它。见 §4.7 |
+| 25 | `read_account_name` | 读取本机账号名字 | `selector_value`（昵称控件；值填在 `.env` 的 `DOUYIN_NAME_SELECTOR_VALUE`，40.6.0 实测值见 [research/U2_ELEMENT_SELECTORS.md](research/U2_ELEMENT_SELECTORS.md) §七） | `selector_type`(xpath)、`timeout`(8)、`on_missing`(fail) | — | 读抖音「我」页面上的**昵称** → 清洗后存进运行期变量（`account_name`），并记下用的选择器供 `push_release`/`switch_account` 核对。**读不到 = 本机没有号**：条件判断走 `else`、推送跳过（都不发）。`on_missing=fail`(默认) 让这一步直接失败、`skip` 只记一句继续。见 §4.7 |
+| 29 | `read_text` | 读取文字 | `selector_value`（要读的元素，值里可用 `{变量}`） | `selector_type`(xpath)、`timeout`(8)、`var`(account_name)、`clean`(account)、`on_missing`(skip) | — | 把某个元素的文字**读出来存进变量**（通用版；发布专用的那个是 #25 `read_account_name`）。`clean=account` 按账号名清洗（取第一行非标签）/ `strip` 只去首尾空白。变量名叫 `account_name` 时顺手把该控件记给 `push_release`/`switch_account` 复用。存下后：选择器值里写 `{变量名}`、或让「条件判断」的 `cmp_source=var` 取它。读不到默认只记一句（`skip`），`fail` 才算这一步失败 |
+| 26 | `switch_account` | 切换账号 | `switch_selector_value`（进「账号切换」列表那一下；填 `.env` 的 `DOUYIN_SWITCH_SELECTOR_VALUE`，实测值同上） | `target`(`var:target_name`)、`target_value`、`name_selector_*`、`me_selector_*`(descriptionContains=我)、`timeout`(8)、**`wait_after`(15)**、`verify`(True)、`max_attempts`(2)、`on_login_page`(stop) | — | **只在本机已登录过的号之间切**：当前已是目标→直接成功；否则点「我」→ 点切换入口 → **在列表里按名字找控件点击**（**禁 `[N]` 序号**：序号型会随界面变形错位）→ 等重载 → **回读校验**。列表里没这个名字 = 本机没登这个号 → 立刻 False（不重试、不算故障）。**切完先等 `wait_after` 秒（默认 15）再回读** —— 换号会触发抖音整体重启，中途去点任何东西（包括点「我」页签那一下『刷新』）都可能打断它加载。停在登录/验证码页 → 通知 + 默认停本设备（平台不做登录/滑块）。见 §4.7 |
+| 28 | `expect_el` | 校验页面 | `selector_value`（**这一页的特征元素**） | `selector_type`(xpath)、`timeout`(10)、`on_missing`(skip_rest)、`what`("在等什么"，写日志/通知) | — | **只校验、不带副作用**：确认"上一步真的完成了"。等不到时：`skip_rest`(默认，**跳过本轮剩余步骤** —— 这一条不发) / `notify`(只通知继续) / `stop`(停本设备)。紧挨着关键点击**前面**放一个，避免在错的页面上盲点后面一串按钮。见 §4.7 |
+| 27 | `foreach_account` | 循环本机待发的号 | — | `date_source`(today/fixed)、`fixed_date`、`retry_failed`(True)、`max_accounts`(0=不限) | `children` | **一轮把本机待发的号跑完**：数据源 = 计划表里还有待发内容的名字（`pending_names`，**不需要账号台账**），逐个写进运行期变量 `target_name` 后跑 children；试过的名字不回头（防死循环）；内层"这个名字还有待发就一直发"，跑一轮没进展（切号失败/守卫没过）就换下一个。三个干净出口：停止 / 任务时长上限 / `max_accounts`。见 §4.7 |
+
+### 3.2 录制手势：**纯录制、纯回放**（`core/gesture.py`）
+
+「滑动」和「录制手势」是**两套东西**，别混：
+
+| | `swipe` 步骤 | `gesture` 步骤 |
+|---|---|---|
+| 存什么 | 方向 + 幅度 + 时长区间 | **完整轨迹点列** `[[x,y,t_ms], …]` |
+| 回放时 | 每次重新生成（弧线/抖动/本设备手速） | **照录制的路径与时长**，不做任何修饰 |
+| 适合 | 通用滑动，换设备也能用 | 你亲手划的、要求一模一样的手势 |
+
+**为什么录制的不能走滑动那套**：滑动是"参数化"的——它按方向+幅度重新生成轨迹并叠
+拟人抖动，录下来的路径就被丢掉了。要"完全按我划的重放"，就只能存点列、回放点列。
+
+**两个录制来源**（都在「录制手势」步骤的卡片上）：
+
+| 来源 | 做法 | 特点 |
+|---|---|---|
+| ● 手机上录 | 点开始后**用手指在真机上划**，后端读 `getevent` 抓真触屏 | 最真实：录的是人手的原始轨迹。合成注入不会出现在真触屏节点上（实测），所以录到的只有人手 |
+| ● 网页上录 | 在弹窗画面里按住鼠标拖，前端按 8ms/3px 采样 | 不用碰手机，但有鼠标的机械感 |
+
+要点与坑：
+
+- **录制前必须唤醒设备**：息屏时 u2 抓 UI 树会从 3 秒退化到 **65 秒**（实测），截图还是黑的。
+  前端在选好设备后会自动调一次亮屏（`/api/device/screen_all`）。
+- **回放是一次调用**（`d.swipe_points(points, duration)`），不是逐点注入：实测这台设备
+  **单次触摸注入 RPC ≈190ms**，逐点回放 20 个点要 3.8 秒，比录的手势慢一个数量级。
+  所以只能让设备自己插值——"时间"靠**点密度**还原（手指慢的地方采样点更密）。
+- 回放点数**抽稀到 40 个**（`MAX_REPLAY_POINTS`）：这台设备每个点开销大，40 是画质/耗时折中；
+  首尾点一定保留。
+- 轨迹是**屏幕绝对像素**：换分辨率不同的设备可能偏，同型号/同分辨率最稳。
+- 点列存在步骤 JSON 里（一条 0.5s 的手势约 25 点 / 400 字节），不新建表。
+
+### 3.1 步骤默认值与动作录制（任务 → 动作配置）
+
+**步骤默认值**：新建步骤时预填的参数（`core/step_defaults.py`，存 `app_meta.step_defaults`）。
+在「任务 → 动作配置」页改，**只影响之后新建的步骤**，已有步骤里的参数不动。
+
+覆盖范围：`swipe`（方向/时长区间/幅度/抖动/拟人）、`click`（等待超时）、
+`long_click`（长按时长/超时）、`wait`（时长区间）、`key_event`（按键）、
+`input_text`（模式/候选文案/是否清空）。
+
+三条实现口径：
+
+- **只存与出厂值不同的字段**——以后调出厂默认时，没配过的字段能跟着更新；
+- 字段**白名单 + 范围夹取**（`SPEC`）：越界值夹到边界、非法值直接丢弃，
+  不会把手改 JSON 塞进来的脏值带进任务；
+- 前端 `_makeStep` 用 `STEP_LIB` 出厂值打底，再用这里的默认值覆盖，
+  `/api/step_defaults` 在打开「任务」Tab 时加载一次。
+
+**动作录制**（`static/admin/recorder.js`）：在设备画面上点/划/按键/输入，
+自动翻译成步骤。两个入口：
+
+| 入口 | 模式 | 产出 |
+|---|---|---|
+| 动作配置页「● 录制动作」 | `action` | 录完存成**自定义动作**（进动作库，拖进任何任务画布） |
+| 步骤编辑器里滑动那一步的「● 录制手势」 | `gesture` | 只取最后一个手势，**回填当前滑动步骤**的方向/幅度/时长 |
+
+翻译规则：
+
+| 你做的 | 记成 | 依据 |
+|---|---|---|
+| 点一下 | `click`（选择器） | 从当前元素树里取**包含该点的最小可点击元素**，用它的 `suggested` 选择器 |
+| 点一下（没命中元素） | `click_xy` | 退化成屏幕百分比坐标 |
+| 按住划一下 | `swipe` | 方向（dx/dy 谁大取谁）、幅度（划距 ÷ 屏高/宽）、时长（你按住的毫秒数） |
+| 停顿（间隔 ≥1s） | `wait` | 真实间隔 ±15%，可在录制器里关掉「记录停顿」 |
+| 按键 / 输入 | `key_event` / `input_text` | 输入文字按**原样**记 `fixed_text`（不是随机候选） |
+
+实现要点（改之前先看）：
+
+- 画面与元素树走 **`/api/uiauto/snapshot` 一次取齐**（截图+元素背靠背取，避免"框落在旧位置"）；
+  **每次操作后自动刷新**，所以下一次点击能用到最新的树。
+- 录制器**只负责翻译**，真正执行仍走 `/api/screen/{tap,swipe,key,text}`——和设备大屏同一套接口。
+- 录到的步骤在列表里可上移/下移/删除；存成动作走现有 `POST /api/custom_actions`（不新增表）。
+
+---
+
+### 3.3 选择器值 / 文案里的变量 `{…}`
+
+多个账号轮着跑时，"要点的那一行""要比对的名字"每轮都不一样。**选择器值里可以直接写变量**，
+执行时按本轮真值替换：
+
+| 写法 | 取什么 |
+|---|---|
+| `{本次要发的名字}` / `{target_name}` | 循环块（`foreach_account`）本轮设的目标名字 |
+| `{本机账号名字}` / `{account_name}` | `read_account_name` / `read_text`（变量名 `account_name`）读到的本机名字 |
+
+例：账号列表里点自己要发的那个号 —— 选择器类型 `textContains`、值 `{本次要发的名字}`。
+
+**编辑器里不用记写法**：选择器值右边的 **`{变量}`** 按钮点一下就能插（两个变量各带一句说明）；
+「点击元素」的参数面板里也有专门的说明块。
+
+**规矩（都是刻意的）**：
+
+- **没写花括号的步骤一个字不改**，老任务零影响。
+- 变量还是空的（还没轮到 / 没读到）→ **换成空串 + 记一条警告**：宁可"选择器变空、找不到元素"
+  明着报，也别留个 `{…}` 字面量去点到歪的地方。
+- 支持变量的地方：`click` / `long_click` / `wait_el` / `swipe_until` / `expect_el` /
+  `read_text` / `read_account_name` / `switch_account` 的选择器值、`if_el` 的选择器与手填候选值。
+- **不做通用表达式**：只认表里那几个名字（中文别名与变量名都行），拼错就等于空值。
+
+### 3.4 自己拼"切号 + 认号"（不想用打包步骤时）
+
+`switch_account`（#26）和 `read_account_name`（#25）是**打包步骤**，内部动作不展开在画布上。
+想每一步都看得见、自己改，可以这样拼：
+
+1. `点击元素`：描述包含 `我` —— 进「我」页
+2. `读取文字`：选择器 = 昵称控件、变量名 `account_name` —— 读本机名字（顺带把控件记给后续步骤）
+3. `条件判断`：选择器 = 同一个昵称控件、比较 `等于`/`包含`、候选值来源 = **本次要发的名字**（或**变量**）
+   - `then` = 发布流程；`else` = 发通知"不是要发的号"
+4. `点击元素`：描述包含 `切换账号` —— 进账号列表
+5. `点击元素`：**文本包含** `{本次要发的名字}` —— 点自己那一行（这一步以前只能用打包步骤做）
+6. `等待` 15 秒 —— 换号会重启抖音，这期间别点任何东西
+7. `条件判断` 再核一遍名字（第 3 步那样），确认真切过去了
+
+> ⚠ 两条与安全有关的老规矩不变：**名字之间不要互为子串**（`textContains` 会先匹配到长的那个 →
+> 点到别人号上）；**列表定位禁用 `[N]` 序号**（界面一变就错位）。
 
 ---
 
@@ -149,12 +279,94 @@ from .generic import task  # 触发 @register_task（当前唯一任务类型）
 
 ### 4.2 `if_el` 条件判断
 
-- 先做元素判断：命中 → 执行 `then` 分支；未命中 → 执行 `else` 分支（分支都可继续嵌套）
+- 先做判断：命中 → 执行 `then` 分支；未命中 → 执行 `else` 分支（分支都可继续嵌套）
+- **`selector_type` 还支持两类非元素条件**（只有条件判断有，别的带选择器的步骤没有）：
+  - `screen` —— 屏幕状态，`selector_value` 填 `off` / `on`（也认 `熄屏`/`灭屏`）：读 `dumpsys power` 的 `mWakefulness`；
+  - `foreground` —— 前台是不是某个包名，`selector_value` 填包名（如 `com.ss.android.ugc.aweme`）。
+  - 这两类**不参与「选择器健康」统计**（它们不是选择器，不该攒出「连续未命中」告警），也不吃 `timeout`（只看当前状态，不等待）
 - `selector_type="ocr"` 时改用 **OCR**：截屏 → `find_on_screen(img, selector_value)` 子串匹配；命中且 `ocr_click=true` 会点击命中位置。
   - OCR 模式下 **`timeout` 不生效**（单次截图即判定）
   - OCR 不可用（未装 `rapidocr_onnxruntime`）时该步返回 `None`（不判定）
   - 命中长文本时点击位置按关键词在文本中的比例估算（避免点到整块中心偏离）
 
+#### 文本比对（`cmp_op` / `cmp_value`，可选）——"这台登录的是不是那个号"
+
+光判断"元素在不在"不够用。填了 `cmp_op` 就变成：**先按选择器取到元素的文本，再拿它和
+`cmp_value` 比，比对结果才是命中与否**。
+
+`cmp_op` 取值：`等于` / `不等于` / `包含` / `不包含`（`==`/`!=`/`contains` 这类别名也认）。
+不填 = 老行为（只看元素在不在）。
+
+**`cmp_value` 可以填多个值**（换行或 `|` 分隔，一行一个）：多个之间是 **OR**——
+"这几个号都算我的"，任一命中即命中；否定式（不等于/不包含）则是"**一个都不许出现**"。
+⚠ **逗号不是分隔符**（"抖音号：123,456" 这种文本本身带逗号，拆了就永远匹配不上）。
+
+例子（抓元素拿到的是 `android.widget.TextView text:抖音号：35377983067 id:com.ss.android.ugc.aweme:id/506`）：
+
+```json
+{"type": "if_el", "params": {
+  "selector_type": "resourceId", "selector_value": "com.ss.android.ugc.aweme:id/506",
+  "cmp_op": "包含",
+  "cmp_value": "35377983067\n35377983068",     // 多个号，任一命中即可
+  "timeout": 3,
+  "then": [{"type": "stop_self", "params": {"reason": "登录的不是我的号"}}],
+  "else": []}}
+```
+
+要判断"**不是**我的号"就用 `不等于`（"界面上是别的号"会命中，正好用来抓"号被换/掉登录"）。
+
+日志会写清"采集到什么、几个候选、命中的是哪个值"，例如：
+`采集到 '抖音号：35377983068' 包含 2 个候选值 → 符合，命中『35377983068』`。
+
+**两条必须知道的规则**（都为了不误判）：
+
+| 情况 | 结果 | 为什么 |
+|---|---|---|
+| 元素**没找到** | 一律**未命中**（走 `else`），日志写"未找到目标，无法比对" | "没读到"绝不能被当成"和我设的不一样"——否则界面还没加载出来就误判成"账号被换了" |
+| 元素在、但文本为空 | 按**空文本**参与比对（空 `不等于` 任何非空值 → 命中） | 用于抓"栏位是空的"（如未登录）。日志会打出实际读到的值，好排查 |
+
+其它细节：
+
+- 支持比对的类型：所有**元素类**选择器（xpath / text / resourceId / description / className…）、
+  **`foreground`**（比当前前台包名）、**`ocr`**（比 OCR 命中的那段文字，如 `抖音号：35377983067`）。
+  **`screen`（亮/熄）没有文本可比**，设了比对会被忽略并告警。
+- 比对**不影响「选择器健康」统计**：统计用的仍是"元素在不在"——"找到了但值不对"是条件按预期
+  走了 `else`，不是选择器失效，不该攒出「连续未命中」告警。
+- 读元素文本是**只读**操作（`get_text`，2 秒超时），不会点击或改动任何状态。
+
+#### 候选值由平台给（`cmp_source`，可选）
+
+几十个号时手写 `cmp_value` 很累、而且换号要回来改。`cmp_source` 让候选值由平台给：
+
+| `cmp_source` | 候选值 |
+|---|---|
+| `""` / `manual`（默认） | 只用手填的 `cmp_value` —— **行为与以前完全一致** |
+| `account_target` | **本次要发的那个名字**：循环块设的目标名字优先，没有就用「读取本机账号名字」刚读到的|
+| `release` | **本机当前发布计划**要发的那个名字：优先本次运行里「推送发布视频」刚取到的那条；还没有就**看**下一条待发的（只看不占位） |
+
+#### `account_target`：发布前先确认"登的是要发的那个号"（一台手机登好几个号时必配）
+
+一台手机可能登着好几个号，发布前必须确认当前抖音登的就是**这次要发的**那个号 ——
+就在发布流程**最前面**放一个条件判断（`cmp_source=account_target` + `包含`），
+命中了才走发布，没命中走 `else`（发通知/跳过）。这样"发错号"变成"这条跳过"，
+而不是把 A 号的视频发到 B 号上。
+
+- 比对的元素原文 = **昵称控件**（和「读取本机账号名字」用**同一个选择器**，抓一次两处都填）；
+  候选值是名字，所以用 **`包含`**。
+- **读不到名字 → 候选为空 → 这一步永远走 `else`**（日志会写明"没读到本次要发的名字"）。
+  这是故意的：**读不到名字 = 不知道现在登的是谁 = 不发**。
+- ⚠ **绝不能用「不等于」**：读不到名字时候选为空，`不等于` 对空候选算**命中**，
+  会把"读不到"误判成"可以发"。
+- **与手填值是合并（OR）**，不是二选一：平台给的候选 + 你补的值，任一命中即可
+  （平台的候选取不到时手填值仍然生效，不会把任务直接打哑）。
+- 「推送发布视频」自己**还会再核对一次**（推送前重读昵称，见 §4.7），所以就算这个条件判断
+  没画，也不会发错号 —— 条件是给"要先看一眼再决定"的场景用的。
+
+> ⚠ **比对用的候选值绝不能拿去填「去重」的身份元素**（`ident_value`）：
+> 去重身份存的是**元素原文**、逐字算 key（`core/dedup.py` 的 `build_key`），
+> 格式不一致（`小王` vs `昵称：小王`）会让**检查与记账算出两个不同的 key → 去重静默失效**
+> （重复评论，而且日志看不出问题）。去重身份继续用「抓取元素」抓到的那个账号元素即可。
+
 ### 4.3 公共参数
 
 | 参数 | 说明 |
@@ -170,6 +382,312 @@ from .generic import task  # 触发 @register_task（当前唯一任务类型）
 
 ---
 
+### 4.5 公共巡检（任务级，独立于步骤画布）
+
+任务运行期间**要全程盯着的条件**（熄屏就点亮、掉到桌面就通知、刷到广告就停），
+配在任务编辑器的「公共巡检」块里，**不进步骤画布**。权威实现在 `core/patrol.py`。
+
+| | 步骤（`params.steps`） | 公共巡检（`params.watchers`） |
+|---|---|---|
+| 配置位置 | 步骤画布，拖出来的 | 任务编辑器单独一块 |
+| 执行方式 | 顺序执行 | **穿插**：每执行完一步、以及长等待的每个分片，看一眼"哪个巡检到点了" |
+| 适合 | 一段固定流程 | 全程都要盯的守护条件 |
+
+为什么穿插而不是另起线程：不需要并发模型，也**不会和主流程抢屏幕**（否则巡检点屏幕、
+主流程同时也在点，动作互相打断）。代价是**精度受步长影响**——某一步卡 30 秒，
+巡检最多晚 30 秒。
+
+配置结构（`params.watchers` 数组，每项）：
+
+```json
+{"name": "熄屏点亮", "enabled": true, "interval": 60,
+ "check": "screen_off",
+ "selector_type": "xpath", "selector_value": "",
+ "action": "screen_on",
+ "notify": true, "title": "{device} 熄屏了",
+ "message": "任务 {job} 在 {time} 发现 {screen}，已点亮",
+ "cooldown": 300}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `interval` | 检查间隔（秒，最小 5）。**首次检查在任务开始时立刻做一次**，之后按间隔 |
+| `check` | `screen_off` 屏幕熄灭 / `screen_on` 屏幕亮着 / `element_exists` 元素存在 / `element_missing` 元素不存在 / `foreground_is` 前台是该App / `foreground_not` 前台不是该App |
+| `selector_type`/`selector_value` | 元素类检查填选择器；`foreground_*` 填**包名**；屏幕类不用填 |
+| `action` | `none` 只发通知 / `screen_on` 点亮屏幕 / `screen_off` 熄灭屏幕 / `stop_self` 停止本设备任务 |
+| `notify` | 命中是否推通知（事件 `task.patrol.hit`，见 [NOTIFY.md](NOTIFY.md)）；`false` 就只做动作 |
+| `title`/`message` | 通知标题正文，可用 `{device}` `{serial}` `{job}` `{time}` `{app}` `{screen}`。**文案在动作之前渲染**，所以写的是"发现熄屏，已点亮"而不是"发现亮屏" |
+| `cooldown` | 命中后多少秒内不再重复动作/通知（默认 300）。**条件持续成立时（一直熄屏）靠它防刷屏** |
+
+两个能直接抄的例子：
+
+```jsonc
+// 1) 熄屏就点亮（不吵人）：每分钟看一眼，熄了就点亮
+{"name":"熄屏点亮","interval":60,"check":"screen_off","action":"screen_on","notify":false}
+
+// 2) 掉出抖音就通知 + 停本设备：前台不是抖音 → 通知 → 停下来等你处理
+{"name":"掉出抖音","interval":60,"check":"foreground_not","selector_value":"com.ss.android.ugc.aweme",
+ "action":"stop_self","notify":true,"title":"{device} 掉出抖音了",
+ "message":"当前前台 {app}，已停止本设备任务"}
+```
+
+要点与坑：
+
+- **巡检不是步骤**：不要试图在画布上找它；它也不计入"已执行 N 次操作"的进度。
+- 一次检查要查设备：屏幕 `0.3s`、前台 `0.7s`，**元素检查要 dump UI 树（慢设备上可能几秒）**。
+  所以 `interval` 别设太小（元素检查建议 ≥30s）。
+- 巡检命中会往「日志 → 步骤明细」记一行（`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": {}}      // 身份留空 = 自动跟随上面检查用的身份
+  ]}}
+```
+
+**身份值**（去重的"谁"）＝ 身份元素读出来的文本（上例＝抖音号）。
+
+身份**只需在检查侧配一次**：
+
+| 位置 | 身份元素 | 结果 |
+|---|---|---|
+| 条件判断（去重） | 填账号元素 | 检查用这个身份 |
+| **记为已做** | **留空（推荐）** | **自动跟随上面检查刚解析出的身份** —— 检查与记账必然用同一个 key |
+| 记为已做 | 也填了 | 用自己填的；**与检查侧不一致时编辑器会告警** |
+| 记为已做 | 留空 + 任务里没有去重检查 | 退回**设备 `serial`** 当身份（"一号一机"场景） |
+
+> ⚠ 为什么把「留空 = 自动跟随」做成默认：检查与记账算的是同一个 key，
+> 两处各配一遍、一边填了一边忘了 → 两个 key → **去重静默失效**（最难查的那种 bug，
+> 现象是"去重没生效、还是重复做"）。编辑器保存时会告警「两处身份不一致」
+> 「有去重检查但没有记为已做」「有记为已做但没有去重检查」。
+
+**有效期**（去重多久算"新的一轮"）在**任务级**配一次：`dedup_reset` = `day`（默认，每天一次）
+/ `all`（只做一次）/ `hours`（每 `dedup_hours` 小时）。任务编辑器顶部有「去重有效期」下拉。
+
+**四条必须知道的语义**：
+
+| 情况 | 行为 | 为什么 |
+|---|---|---|
+| 身份元素**读不到值** | **不去重**，当"没做过"照常执行（日志告警） | 读不到若当成空身份，所有设备会共用一个 key，第一台记账后其余全被误跳过——宁可重复一次，也不能漏做 |
+| 身份值**过长** | 同上，不去重 | 截断会让两个身份撞成同一个 key（同样是误跳过） |
+| 「记为已做」放在动作失败路径上 | **不会执行** | 拆成"检查在前、记账在后"就是为了**失败不记账、下次重试** |
+| `dedup_reset='all'` | 记录**永不被清理** | 清了就等于"只做一次"失效（清理任务只删 `day`/`hours` 桶） |
+
+**看进度 / 让它重跑**：「任务 → 去重记录」页能看到"谁做过了、今天做了几个号"，
+可以删单条（那个号/那台设备重跑）或清空整个任务。**这一页的价值就是让你不必靠"一直重跑"来确认。**
+
+**第二种办法（兜底，不用账本）**：进 App 的评论区后用
+**条件判断 + 文本比对（包含）**，候选值填本账号的评论标识（昵称/「我」标签），命中就跳过。
+它的局限要说清楚，别指望它万能：
+
+- 依赖 App 的评论区结构，**改版就失效**
+- 自己的评论常常要**滑动加载**才出现在元素树里（可能要滑几次、慢）
+- 多台设备并发时可能**同时**判"没评过"（没有原子性）——所以**账本才是主拦**，这个只做兜底
+
+---
+
+### 4.7 发布计划：平台推素材，发布流程你自己写（`push_release` + `mark_release`）
+
+数据与界面见 [DATA_MODEL.md](DATA_MODEL.md) §2.11 与「发布计划」页。
+
+**全部按「名字」走**（名字 = 上传文件名里的那个名字 = 抖音昵称）：计划行认名字，
+运行时读本机当前账号名字，**读不到名字就当"本机没有号"、什么都不发**。
+
+**素材可以是视频，也可以是图片**（扩展名各带各的，一路原样带到手机上 —— 抖音按它判断
+这是视频还是「图文」）：**发布流程是同一条**（相册里点第一个素材 → 下一步 → 填标题/正文 → 发布），
+所以任务画布不用为图片另写一套。
+
+**分工**（这是刻意的设计）：**平台只管"素材到手机 + 状态记账"，抖音里怎么发由你画** ——
+因为发布流程跟账号、版本、界面都在变，写死在平台里改不动。
+
+```
+[读取本机账号名字] → [条件判断 account_target] → [推送发布视频] → [你的发布步骤…] → [标记发布结果]
+ read_account_name    登的是要发的号吗？            push_release     打开抖音→点+→相册→选视频   mark_release
+                       不是/读不到 → else：通知跳过                   →下一步→填标题→填正文→发布  published 放成功分支
+                                                                                            failed 放失败分支
+```
+
+**先读名字、再校验、最后才发**（一台手机登好几个号时必配）：
+
+- 「读取本机账号名字」：读抖音「我」页面上的**昵称控件**（选择器抓一次填进 `.env` 的 `DOUYIN_NAME_SELECTOR_VALUE`），
+  清洗后的名字进运行期变量（见 §3 第 25 行）。**读不到 = 本机没有号**。
+- 条件判断用 `cmp_source=account_target`（候选值 = 本次要发的名字，见 §4.2）+ `包含`；
+  没命中就走 `else` —— **宁可不发，也不发错号**。
+- 「推送发布视频」自己**再核对一次**：推送前重读昵称，与要发的名字对不上（或读不到）→ 不推。
+
+**自动切号（`switch_account`，一台手机多个号时用）**：
+
+一轮任务里"切号 → 读名 → 推 → 发 → 标记"循环跑多个号（由 `foreach_account` 循环块驱动）：
+
+```
+[foreach_account]  ← 一轮把本机待发的号跑完（数据源 = 计划表里还有待发内容的名字）
+   └ [switch_account] → [read_account_name] → [if_el account_target] → [push_release] → 你的发布步骤 → [mark_release]
+      切到这个名字        确认切成了            登的是它吗？              取这个号的计划
+```
+
+- **只在本机已登录过的号之间切**（抖音账号列表里有的号）：不做登录新号、不做滑块。
+- 列表里**没有**这个名字 → 立刻返回 False（= 本机没登这个号，**不重试、不算故障**）：
+  多台设备各自"试自己有的号"，不会互相误报。
+- 切完**回读校验**（`verify=True`）：读回来的不是目标 → 该号这一轮**不推送**（守卫会挡下）。
+- 停在登录/验证码页 → 通知 `task.account.need_login` + **默认停本设备**（见 [NOTIFY.md](NOTIFY.md)）。
+- ⚠ **选择器只能按名字**（`textContains`），**绝不能用 `[N]` 序号**：序号会随界面变形错位，
+  点错就是把内容发到别人号上（[research/U2_ELEMENT_SELECTORS.md](research/U2_ELEMENT_SELECTORS.md) 有实测）。
+
+**人工入口也一样按名字找设备**（「发布计划」页）：
+
+- 「推送到手机」：实时探测**哪台在线设备现在登着这条计划的名字**，推给它；没有设备登着 →
+  400 + 人话原因（"先去那台设备上切号"）。
+- 「一键推送（今天）」：当天所有待推计划按名字分组 → 逐条推；**没设备登着的号在 `unmatched`
+  里逐条报出来**（见 [API.md](API.md) §`push_by_account`）。
+- 探测在 `core/account_probe.py`：只读/幂等（连设备 → 抖音前台 → 点「我」→ 读昵称），
+  **跳过正在跑任务的设备**（不抢屏），单台失败只报那台；结果顺手缓存进 `device.cur_account_name`
+  （**纯缓存**，自动任务永远现场读屏幕）。
+
+**每一步之前先校验上一步完成了没（`expect_el`）**：发布流程是一串"点 A → 点 B → 点 C"，中间任何一步没生效，后面就会**盲点**（点到别的控件上），最后"任务跑完了、什么都没发出去"还不报错。
+所以骨架在每个关键点击前面放了一个「校验页面」：相册页（`//*[@text='所有照片']`）、素材已选中（`desc=选择/预览`）、剪辑页（`desc=文字/话题`）、发布页（`desc=发布`…）。等不到就**跳过本轮剩余步骤**（这一条不发、换下一个号），并通知 `task.page.mismatch`。
+
+**「推送发布视频」做六件事**（`tasks/generic/publish_flow.py` 的 `push_one()`）：
+
+```
+⓪ 核对：重读昵称 → 与本次要发的名字不一致/读不到 → **不推**（返回"跳过"）
+① 取计划（**队列口径**）：**这个名字**名下 `发布日期 <= 目标日期`（过期会补发、未来的不发）、
+   `status ∈ (ready, failed)`（**done/skipped 永不入队**）、`attempts < 3` 的行，
+   按 `(发布日期, 编号)` 升序取最早的 —— 即"按顺序发没发过的"
+   （名字从哪来：「读取本机账号名字」读到的，或循环块设的目标名字，见 `_release_scope`）
+② **原子占位**：UPDATE … SET status='pushing' WHERE id=? AND status IN ('ready','failed')
+   ← **幂等的唯一判据**（多设备/任务重跑不会把同一条推两遍）
+③ adb push → {album_dir}/{计划id}.mp4（默认 /sdcard/DCIM/Camera）→ 校验**大小**（按 ls -l 的大小列比）
+④ **touch 一下**把手机上这个文件的 mtime 改成"现在" + 清掉同一计划在旧目录里的副本
+⑤ 触发媒体扫描 → **按路径**校验它真的进了相册索引 → 把标题写进手机剪贴板（供「粘贴」用）
+```
+
+**为什么是 `DCIM/Camera`、为什么要 touch**（都是实测踩出来的）：
+
+- 相册（含抖音的选视频页）读的是 **MediaStore 索引**：`adb push` 只放文件、不进索引，
+  推完必须触发扫描，否则"推送成功但相册里没有"。
+- MIUI 会把自建子目录（`DCIM/rp`）归到「其他相册」，抖音的选视频页列不顺 —— 所以放官方相机目录。
+- 放 Camera 的代价：**用户自己拍的视频也在这个目录里** → "相册里第一个 = 刚推的那个"靠排序成立。
+  而 `adb push` 保留的是**本地文件的修改时间**（推一个 3 天前上传的素材 → 排在很后面，
+  "点第一个"就点到别的视频了）→ **推完必须 `touch`**，把 mtime 改成现在。
+- 同一个 plan id 在老目录里可能还留着副本（换目录后的残留）→ 推送时顺手按**精确路径**清掉，
+  并重扫让相册索引把那行去掉；不清的话相册里同一个视频出现两三份，点第一个可能点到死文件。
+- **校验必须比路径，不能只比文件名**：MediaStore 的 `_data` 返回的是
+  `/storage/emulated/0/dcim/rp/...`（目录部分被小写），而 `_indexed_paths()` 归一化后再比；
+  只比文件名会被"老副本在索引里"骗过去，判成"新文件已就绪"。
+- 校验结果落 `video_plan.push_verify`（`ok` / `no_index` / `nofile`）+ `push_remote`（手机上的绝对路径），
+  界面上标「已推送·相册可见 / 已推送·相册未见」——**文件推上去了 ≠ 相册里点得到它**，
+  这两件事必须分开显示。
+
+> ⚠ **uiautomator2 3.x 的 `d.shell()` 返回 `ShellResponse`（tuple 子类），不是 str**：
+> 直接 `'abc' in resp`（元组成员判断，恒 False）或 `resp.strip()`（没这方法）都会得到错误结果。
+> 实测踩过：推送的"文件大小校验"永远不通过（每次推送都被记成失败，而文件其实推上去了）、
+> "有没有进相册"永远报没进。取输出统一走 `publish_flow._sh(d, cmd)`。
+
+远程名用**计划 id**（唯一可识别）。老默认目录 `Movies/rp`、`DCIM/rp` 里的历史副本会被 `drop_old_copies()` 清掉。
+
+**「标记发布结果」**放在你的流程末尾：
+
+| `result` | 什么时候用 | 落库 |
+|---|---|---|
+| `published` | 确认发出去了 | `done`（顺手抓作品分享链接存进计划行、删手机上的素材） |
+| `failed` | 确认没发出去 | `failed`（**可重试**：下次任务会再推一次） |
+| `unknown` | 拿不准 | `unknown`（**绝不自动重发**，计划页标橙，人工裁决） |
+
+**阶段与状态的对应**（`core/video_plan.STAGE_STATUS`，本设计最要紧的一张表）：
+
+| 阶段 | 含义 | 落库 | 能不能自动重试 |
+|---|---|---|---|
+| `push` | 推文件到手机失败（还没碰抖音） | `failed` | ✅ 安全 |
+| `scan` | 媒体扫描 | `failed` | ✅ 同上 |
+| `manual` | **已推到手机**，后面归你/你的人管 | — | — |
+| `post` / `verify` | 推送之后出的岔子（你标记失败/未知） | `unknown` | ❌ **可能已经发出去了** |
+
+> ⚠ **`failed` 与 `unknown` 必须分开**：把"不知道自己发没发"当成"知道自己没发"，
+> 就是重复发布的来源。每日 04:41 的清理 job 会把卡住的占位按阶段降级
+> （`manual` 阶段 → `unknown`，不会降成"可重试"）—— 没有它，一条计划崩一次就永远卡住。
+
+**几条硬约束**（都是踩过的坑）：
+
+- **只删平台自己推的文件**（`{计划id}.mp4` 精确路径）。**绝不 `rm` 通配** —— 会删用户自己拍的东西。
+- **一次只推一个视频**（`max_same_run=1`）：这样"相册里第一个 = 我要发的那个"才成立；
+  要一次发多条，就重复"推送 + 你的发布步骤 + 标记"这一组。
+- **你的发布步骤里，文案要用「粘贴」**（推送时标题已进剪贴板）；如果非要用「输入文字」，
+  记得后面加一步**回读校验**（读输入框的 text）—— 抖音的 EditText 有时不吃 `send_keys`，
+  不校验就可能发出一篇空文案而每一步都显示成功。
+- **不靠 `done_mark` 判重**：去重账本的 identity 是元素原文，与 `(名字,日期,编号)` 两套 key
+  语义不同，混用会静默失效。
+- **任务状态 ≠ 发布结果**：`_exec_steps` 不检查步骤结果，**标记失败不会让任务失败** ——
+  「这次发布的真相」以计划行的 `status` 为准（计划页看得到），并会推
+  `task.video.published` / `task.video.failed` 通知。
+
+**「发布计划」页顶部还有一块「发布任务」**（`GET/POST /api/video_plan/tasks`）：
+上面一组是**发布任务**（步骤里含「推送发布视频」**或**「标记发布结果」，含嵌套在条件/循环里的），
+下面「其它任务」折叠着**全部通用步骤任务** —— 都能就地编辑。
+列全部是刻意的：**手写的抖音发布流程**（自己点相册→输入框→发布，没有平台的 `push_release` 步骤）
+如果被筛掉，人打开这页只会看到"一键新建"，会以为"这页没有能改的地方"；
+这类任务行上会标「**缺平台推送步骤**」并给一个「**插上平台步骤**」按钮
+（`POST /api/video_plan/tasks/<id>/adopt`：推送放最前、标记放最后、**你原来的步骤一步不动**）。
+还支持**一键新建标准发布任务** ——
+骨架 **17 步**已经排好（**标题和正文各一步** —— 对应抖音发布页上那两个框）：
+
+```
+⓪ 亮屏  ① 打开抖音(等「首页」出来)  ② 点击「我」(desc 含"我")  ③ 等待 3~5s
+④ 条件判断  //*[contains(@text,'抖音号')] 包含 cmp_source=release
+   ├─ then（登的就是要发的号）⑤ 推送发布视频 ⑥ 点击「+」(desc 含"拍摄")
+   │        ⑦ 相册 ⑧ 第一个视频 ⑨ 下一步 ⑩ 输入框 ⑪ 输入文字(text_source=release_title)
+   │        ⑫ 点击正文输入框 ⑬ 输入文字(text_source=release_body)
+   │        ⑭ 点击「发布」 ⑮ 标记发布结果
+   └─ else（不是这个号 / 今天没有待发计划）⑯ 发通知"本条跳过"
+```
+
+> ⚠ **⓪ 亮屏 + ① 等「首页」是踩出来的，别删**：真机实测（2026-09-28，A01）——
+> **屏幕没亮就启动抖音，它会永远停在启动页**（`mCurrentFocus=splash.SplashActivity`、UI 树是空的），
+> 于是"点击我"必然 miss、"等抖音号出现"必然超时，最后报成一句误导人的"账号不符"。
+> 屏幕亮着时冷启动 5 秒就出底部栏。
+
+建好之后**就在「发布计划」这一块点「编辑」就地改**（名字/目标/每天几点/启停/逐步参数，
+选择器旁边就有「抓取元素」），把 6 个空选择器（相册/第一个视频/下一步/标题框/正文框/发布）抓一次就能跑 ——
+要加步骤、循环、自定义动作这些更复杂的编排，才走「打开通用编辑器」（跳任务页）——
+**抖音那几步故意不写死选择器**：混淆 id / 结构 xpath 改版就废，
+抓一次的成本远低于每次发版都改平台代码。②⑥ 两条预填的是**按描述定位**
+（`descriptionContains`，跨版本稳），一般不用改。
+
+**「输入文字」自动用计划里的内容**（`text_source`，常量 `RELEASE_TEXT_SOURCES` 一处定义）：
+
+| text_source | 取什么 | 用在哪个框 |
+|---|---|---|
+| `release_title` / `release_title_topics` | 计划的**标题**（`video_plan.title`） | 抖音发布页的「标题」框 |
+| `release_body` / `release_body_topics` | 计划的**正文**（`video_plan.body`） | 抖音发布页的文案/正文框 |
+| `release_title_body` | 标题 + 换行 + 正文 | 只有一个输入框的抖音版本 |
+
+带 `_topics` 的会再把 `release_topics`（逗号分隔）拼成 `#话题`。
+内容由 `push_release` 在同一次运行里传递（断档了就取最近一条"已推送到手机"的）；
+**取计划内容时会回读输入框校验**，不通过就改走剪贴板通道再验一次 ——
+抖音的 EditText 有时不吃键盘输入，不校验的后果是"发出一篇空文案，而每一步都显示成功"。
+
+**抓分享链接**（`mark_release` 的 `capture_link=True`，或计划页人工点「标记已发布」时）：
+进「我 → 作品」第一条 → 分享 → 复制链接 → 读剪贴板 → 正则抠出 `v.douyin.com` 链接。
+**这一段仍是抖音 UI 流程**（按文字定位），抖音改版会失效 —— 失效时链接空着，
+计划页标"缺链接"、素材文件**不删**（链接与素材至少留一个），不影响"已发布"这个结论。
+
 ## 5. 选择器与元素定位
 
 ### 5.1 `selector_type` 支持的值
@@ -272,7 +790,7 @@ from .generic import task  # 触发 @register_task（当前唯一任务类型）
 |------|------|
 | 操作库拖拽 | 左侧分类库（interact / screen / flow），拖到画布；支持跨层级嵌套（循环套循环）、拖拽排序 |
 | 参数表单 | 按步骤类型渲染对应字段（选择器行、时长、概率、循环模式等） |
-| 条件分支 | `if_el` 的 then/else 两个分支区；OCR 模式下多出"命中后点击"复选框 |
+| 条件分支 | `if_el` 的 then/else 两个分支区；OCR 模式下多出"命中后点击"复选框；元素/OCR/前台App 条件还多一块**文本比对**（运算符下拉 + 比对的值，见 §4.2） |
 | 多选与打包 | ☑ 多选 → 打包成自定义动作 |
 | 元素抓取 | 「抓取元素」打开抓取弹窗（选设备 → 截图 + 元素树 → 点选回填），见 §5.5 |
 | 测试 | 「测试此步骤」真机试执行 |
@@ -348,9 +866,9 @@ class MyTask(BaseTask):
     def get_action_class(cls, action_type):
         return None
 
-    def create_worker(self, serial, params):
+    def create_worker(self, serial, params, ctx=None):
         merged = {**DEFAULT_PARAMS, **(params or {})}
-        return MyWorker(serial, params=merged)
+        return MyWorker(serial, params=merged, ctx=ctx)
 ```
 
 ```python
@@ -369,8 +887,45 @@ from .myapp import task      # ← 新增
 
 ### 8.3 签名约定
 
-- `BaseWorker.__init__(self, serial, params=None, daemon=True)`
-- `Task.create_worker(self, serial, params)` —— **不要带 `stf_client` / `stf` 形参**（STF 已摘除，历史签名已清理）
+- `BaseWorker.__init__(self, serial, params=None, daemon=True, ctx=None)`
+- `Task.create_worker(self, serial, params, ctx=None)` —— **不要带 `stf_client` / `stf` 形参**（STF 已摘除，历史签名已清理）
+- `ctx` 是本次运行的上下文（`run_id` / `job_id` / `job_name` / `device_name`），由
+  `TaskManager._run_with_retry` 传入；**只用于结构化记录**（如步骤明细
+  `core/step_log.py`），不参与业务逻辑。不关心就原样透传给 `BaseWorker` 即可。
+
+### 8.4 拟人化：滑动与设备节奏（`core/humanize.py`）
+
+自动化最容易被识别的地方不是"慢"，是**每次都一模一样**：同一坐标、同一时长、
+13 台设备整齐划一地做同一个动作。`core/humanize.py` 从两个层次解决：
+
+| 层次 | 机制 | 谁决定 |
+|---|---|---|
+| **每次不同** | 起点/终点/幅度/时长抖动，弧线方向随机 | 每次调用现算（`jitter` 控制幅度，0~0.4） |
+| **每台设备不同** | 手速(0.82~1.32)、幅度(0.86~1.16)、弧度、常用横坐标(±9%屏宽)、停顿(0.80~1.35) | `crc32(serial)` 播种，**同设备恒定** |
+
+用法（同步步骤里用）：
+
+```python
+from core import humanize
+humanize.swipe(d, "up", serial=self.serial, duration_min=0.25, duration_max=0.4,
+               distance_ratio=0.6, jitter=0.15, humanize=True)
+humanize.pace(self.serial, 5.0, enabled=True)   # wait 步骤的"按设备节奏微调"
+```
+
+要点与坑：
+
+- **性格稳定、抖动随机**：稳定才像"不同的人"，随机才不像"机器"。性格按 **serial**
+  而不是设备名播种——改名不改风格，换地址会换风格（地址代表"这一台"）。
+- 内部用**独立的 `random.Random` 实例**，不碰全局 `random`：worker 是多线程的，
+  全局 RNG 的取值顺序会被别的线程打乱，性格就串味了。
+- **屏幕尺寸别用 `d.info`**：部分设备上一次要 **14 秒**（实测），改用
+  `humanize.screen_size(d, serial)`——它走 `d.window_size()`（同设备 0.6s）并缓存
+  120 秒。这让"加了弧线反而更快"成为可能。
+- **曲线点数固定为 4**（5 个点）：`d.swipe_points` 在慢设备上**每多一个点约多 1 秒**
+  （实测 2 点 1.4s / 6 点 6.0s / 10 点 10.6s），而设备自己会在点之间插值几十步，
+  4 个点的贝塞尔已经足够弯。**不要为了"更平滑"把点数调大。**
+- `swipe_points` 抛异常时自动退回直线 `d.swipe`（老 agent 兜底），日志会留一行 warning。
+- 想关掉：步骤参数 `humanize: false`（完全还原老行为）；想调轻：`jitter: 0.05`。
 
 ---
 

doc/research/U2_ELEMENT_SELECTORS.md

@@ -172,3 +172,91 @@
 `core/uiauto_helper.py` 里 `_child_path()` 的注释与 `doc/TASK_DEV.md` §5.4 都记了这两个坑，
 避免以后又写回来。
 
+
+---
+
+## 七、抖音「我」页面 + 账号切换列表的选择器（2026-10-12，A01 实测）
+
+**背景**：发布计划改成按**名字**发（`doc/TASK_DEV.md` §4.7），平台需要两处控件：
+① 「我」页面上的**昵称**（读当前登的是谁）；② 「我」页面右上角的**切换账号**入口。
+抖音 40.6.0 / 720×1650 实测（A01 = `192.168.20.82:5555`）。
+
+### 用哪个（已实测可用）
+
+| 用途 | 选择器 | 说明 |
+|---|---|---|
+| **读昵称** | `resourceId = com.ss.android.ugc.aweme:id/tk+` | 读回来就是昵称原文（如 `周周苏州吃喝玩乐`）。等价 xpath：`//*[@resource-id="com.ss.android.ugc.aweme:id/tk+"]` |
+| **进切换列表** | `descriptionContains = 切换账号` | 右上角那个按钮是个 ImageView，**只有 content-desc**（`切换账号`），没有文字 |
+| **切到某个号** | `textContains = <名字>` 点它 | 列表每行的名字是 `TextView`（id `tv_nickname`），**本身 `clickable=false`** —— 但 u2 的 `click()` 是**按中心坐标点屏**，行容器（无 id 的 `ViewGroup`，`clickable=true`）会接住这次点击，实测能切成 |
+| **底部「我」页签** | `descriptionContains = 我` | 页签的 content-desc 是 `我，按钮`（**全角逗号**），`包含` 就能命中；别用 `text=我`（会撞上「我的订单」等） |
+
+### 结构（40.6.0）
+
+```
+「我」页面
+└ LinearLayout uj+                      资料块
+  ├ ukd → s=g → TextView tk+ = 昵称      ← 读名字就用它
+  │        └ j2f → 1gp → ImageView oxp（desc=切换账号）  ← 点它进列表
+  └ ukc → l1= → j6c → g7j = 抖音号：xxx
+
+切换账号列表（点 oxp 后弹出的面板）
+└ View（desc=返回，铺满面板，可点）         ← "点面板外关掉"那层
+  ├ ViewGroup（无 id，clickable）894~1060  ← 第 1 行（当前号）
+  │   ├ ImageView iv_avatar / TextView tv_nickname / TextView 37_（粉丝数）/ CheckBox b7w
+  ├ ViewGroup 1060~1228                   ← 第 2 行
+  ├ ViewGroup 1228~1396                   ← 第 3 行
+  └ ViewGroup 1396~1556（添加或注册新账号）
+```
+
+### 为什么**不要**用 `(…b7w)[N]`
+
+`b7w` 是每行那个单选框（CheckBox）的 id —— `(…b7w)[2]` 看着能选中第 2 行，
+但这正是本文 §二说的**序号型**：`[N]` 依赖"列表里有几行、面板从哪一行开始"，号一多/一少、
+或者抖音把「添加或注册新账号」挪个位置就点到别人号上了（**把内容发到别人号上**，最严重的一类错）。
+按名字点（`textContains=<名字>`）永远指着那一行本身。
+
+### 实测记录
+
+- 冷启动（`app_stop` → `app_start`）后切号：**17.2s** 成功；热态切号 12.9s
+- ⚠ 切完之后**只能等**：实测『回读不到就再点一次「我」』会被当成去点刷新、还可能打断抖音重载，用户直接要求『别刷新，等 15 秒』 → 现在是 `wait_after`（默认 15s，步骤参数可调）等完再回读
+- ⚠ **第一次实现踩的坑**：把"进列表"后的等待写成**固定 sleep(1.2s) 再找一次**，
+  冷启动时列表还没渲染出来 → 判成"本机没登这个号" → **漏发**（还不会报错，只是不发）。
+  现在两处都改成**轮询到 deadline**（`max(6s, timeout)`）：等面板出目标行、等回读变成目标名。
+  教训同 §一：**"找不到"和"没加载出来"必须用等待区分开**。
+
+### 抓取命令（下次 App 改版后重抓）
+
+```bash
+# 前台确保是抖音且在「我」页，然后
+.venv/Scripts/python -c "import uiautomator2 as u2; d=u2.connect('<serial>'); open('me.xml','w',encoding='utf-8').write(d.dump_hierarchy())"
+# 在 me.xml 里找 text 是昵称、或 content-desc 是「切换账号」的节点，看它的 resource-id
+```
+
+### 七·补：40.7.0 的「我」页与发布流程各页（2026-10-12，A06 = 192.168.20.75 实测）
+
+生产是 40.6 与 40.7 **混装**（9 台 40.7 / 3 台 40.6），两版的混淆 id **不一样**。实测对照：
+
+| 元素 | 40.6.0（A01） | 40.7.0（A06） |
+|---|---|---|
+| **「我」页昵称** | `id/tk+` | **`id/tkv`** |
+| 切换账号入口 | `desc=切换账号`（id/oxp） | `desc=切换账号`（id/ow_）**同一个 desc ✓** |
+| 抖音号 | `id/504` | `id/5zk` |
+| 底部「我」页签 | `desc=我，按钮` | 同样能用 `desc 含我` 命中 ✓ |
+| 拍摄面板「相册」 | `id/cnv` | `id/cnv` **同 id ✓** |
+| 相册页 | —— | 标题 `id/tv_title` = **`所有照片`**；页签 全部/视频/图片/动图/人像 |
+| 选中素材后 | —— | 顶部出现 `desc=选择` / `预览` |
+| 剪辑页 | —— | `desc=文字`/`话题`/`贴纸`/`特效`/`标记`/`滤镜`（都挂在 `id/iv_icon` 上） |
+| 发布页 | —— | 标题框 `id/ipv`（hint `添加标题`）、描述框 `id/ia-`（hint `添加作品描述...`） |
+
+**昵称的"两版通吃"写法（已实测）**：xpath 联合 ——
+`//*[@resource-id="com.ss.android.ugc.aweme:id/tkv"] | //*[@resource-id="com.ss.android.ugc.aweme:id/tk+"]`
+在 40.7.0 上 `exists=True` 且 `get_text()` 读到昵称 ✓。**比按版本配两套省事**，写进 `.env` 的
+`DOUYIN_NAME_SELECTOR_VALUE` 即可（`read_account_name` 与「校验账号」共用它）。
+
+**为什么 `desc=选择` 这类"页面特征"能当校验**：选素材/进剪辑页这些**没有独立 id 的页面**，
+靠"这一页特有的文字/描述"判断"我在哪一页"，比按坐标/序号稳 —— 这正是「校验页面」(expect_el)
+要的东西（见 `doc/TASK_DEV.md` §3 第 28 行、§4.7）。
+
+> ⚠ 走查时踩的坑：**别用坐标点底部页签** —— 我按 (0.876,0.899) 点 A06 的「我」，
+> 结果进了「抖音音乐榜」（`MusicDetailActivity`）。同一台机器上 `desc 含我` 是好的，
+> 按 desc 点才是对的（40.6 上坐标碰巧能用，不代表 40.7 也行）。

scripts/tests/run_all.py

@@ -0,0 +1,49 @@
+"""发布计划「按名字发」相关用例：一次跑完，汇总结果。
+
+用法（项目根目录）：
+    .venv/Scripts/python scripts/tests/run_all.py        # Windows
+    .venv/bin/python scripts/tests/run_all.py            # Linux/macOS
+
+这些用例的**铁律**（与 doc/DEVELOPMENT.md 的测试约定一致）：
+  · 一律**临时 SQLite + 临时目录**（`DATABASE_URL` / `DATA_VIDEO_DIR` 指向 tempfile 建的目录），
+    **绝不碰用户的真实库与真实素材目录**；
+  · 需要设备的地方一律用**假设备**（桩对象/stub），**不连真机、不下发 adb**；
+  · 每个用例自己退出码非 0 表示失败，本脚本据此汇总。
+
+覆盖：
+  test_parse_name        文件名/标题行解析（`名字_日期_编号`、`标题 || 正文_...`、各种拒收）
+  test_upload_name       上传 + 配标题落库（不再依赖任何账号台账）
+  test_name_scope        读本机账号名字、按名字取计划、推送前核对
+  test_switch_account    切换账号（按名字点控件、回读校验、登录页停设备）
+  test_foreach_account   循环本机待发的号（一轮跑完、试过不回头、干净退出）
+  test_push_by_name      按名字找设备推送（matched/unmatched、缓存）
+  test_expect_el         「校验页面」：特征在就过；不在就按 on_missing 处置（默认跳过本轮剩余步骤）
+  test_read_text         「读取文字」+ 选择器里的 {变量} +「条件判断→变量」
+"""
+import os
+import subprocess
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+CASES = ["test_parse_name.py", "test_upload_name.py", "test_name_scope.py",
+         "test_switch_account.py", "test_foreach_account.py", "test_push_by_name.py",
+         "test_expect_el.py", "test_read_text.py"]
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+
+failed = []
+for name in CASES:
+    print("=" * 66)
+    print("▶", name)
+    print("=" * 66)
+    r = subprocess.run([sys.executable, os.path.join(HERE, name)])
+    if r.returncode != 0:
+        failed.append(name)
+
+print()
+print("=" * 66)
+if failed:
+    print("❌ 失败 %d / %d：%s" % (len(failed), len(CASES), "、".join(failed)))
+    sys.exit(1)
+print("✅ 全部 %d 个用例通过" % len(CASES))

scripts/tests/test_expect_el.py

@@ -0,0 +1,145 @@
+# -*- coding: utf-8 -*-
+"""「校验页面」(expect_el) 用例：看到就过；没看到按 on_missing 处置（默认跳过本轮剩余步骤）。
+
+假设备，不连真机。重点验两件事：
+  ① 特征元素在 → True，且**不影响**后面的步骤；
+  ② 特征元素不在 → 默认 `skip_rest`：**本轮剩下的步骤一步都不执行**（不盲点后面的按钮）。
+"""
+import io
+import os
+import sqlite3
+import sys
+import tempfile
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+os.environ['DATABASE_URL'] = 'sqlite:///' + os.path.join(tempfile.mkdtemp(), 'ac.db').replace('\\', '/')
+os.environ['DATA_VIDEO_DIR'] = tempfile.mkdtemp()
+os.environ['DEPLOY_ENV'] = 'dev'
+os.environ['DB_ALLOW_SQLITE_FALLBACK'] = '1'
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+os.chdir(sys.path[0])
+
+from tasks.generic import task as gt                                   # noqa: E402
+
+fails = []
+
+
+def check(label, got, want):
+    ok = got == want
+    if not ok:
+        fails.append(label)
+    print(('  ✅ ' if ok else '  ❌ ') + label + ('' if ok else '\n       得到 %r\n       期望 %r' % (got, want)))
+
+
+class El:
+    def __init__(self, flag):
+        self._flag = flag
+
+    @property
+    def exists(self):
+        return _Ex(self._flag)
+
+    def wait(self, timeout=0):
+        return self._flag
+
+    def get_text(self, timeout=None):
+        return ""
+
+
+class _Ex:
+    def __init__(self, f):
+        self.f = f
+
+    def __call__(self, timeout=0):
+        return self.f
+
+    def __bool__(self):
+        return self.f
+
+
+class StubD:
+    """`present` 里有的 xpath 才算存在（用来模拟"这一页的特征元素"）。"""
+
+    def __init__(self, present=()):
+        self.present = set(present)
+        self.calls = []
+
+    def xpath(self, v):
+        self.calls.append(v)
+        return El(v in self.present)
+
+    def __call__(self, **kw):
+        v = kw.get('selector_value') or ''
+        self.calls.append('kw:%s' % kw)
+        return El(v in self.present)
+
+
+notes = []
+orig = gt.notifier.notify
+gt.notifier.notify = lambda ev, **kw: notes.append((ev, kw.get('want') or ''))
+try:
+    print('=== 1. 特征在 → True，后面的步骤照跑 ===')
+    P = {'selector_type': 'xpath', 'selector_value': '//*[@text="所有照片"]',
+         'timeout': 1, 'on_missing': 'skip_rest', 'what': '相册页'}
+    w = gt.GenericStepsWorker("F1", {})
+    d = StubD(present=['//*[@text="所有照片"]'])
+    check('返回 True', w._exec_expect_el(d, P), True)
+    check('没置"跳过剩余"', w._skip_rest, False)
+    check('没发通知', notes, [])
+
+    print('=== 2. 特征不在 → 默认 skip_rest：**本轮剩余步骤一步都不执行** ===')
+    notes.clear()
+    w = gt.GenericStepsWorker("F2", {})
+    d = StubD(present=[])               # 特征不在（没到相册页）
+    ran = []
+    real_one = gt.GenericStepsWorker._exec_one
+
+    def fake_one(dd, step, depth=0):
+        """真跑 expect_el 那一步；其它步骤只记一笔（被跳过就不该记）。"""
+        if step.get('type') == 'expect_el':
+            return real_one(w, dd, step, depth)
+        ran.append(step.get('label'))
+
+    w._exec_one = fake_one
+    steps = [{"type": "expect_el", "label": "校验：应在相册页", "params": P},
+             {"type": "click", "label": "点第一个素材", "params": {}},
+             {"type": "click", "label": "点下一步", "params": {}}]
+    w._exec_steps(d, steps)
+    check('后面的点击一步都没执行', ran, [])
+    check('置了"跳过剩余"', w._skip_rest, True)
+    check('发了页面不对的通知', [n[0] for n in notes], ['task.page.mismatch'])
+    check('通知里带上"在等什么"', notes[0][1], '相册页')
+
+    print('=== 3. on_missing=stop → 停本设备 ===')
+    notes.clear()
+    w = gt.GenericStepsWorker("F3", {})
+    d = StubD(present=[])
+    check('返回 False', w._exec_expect_el(d, dict(P, on_missing='stop')), False)
+    check('本设备已停', w.stopped(), True)
+    check('发了通知', [n[0] for n in notes], ['task.page.mismatch'])
+    check('没置"跳过剩余"（停设备就够了）', w._skip_rest, False)
+
+    print('=== 4. on_missing=notify → 只通知、继续 ===')
+    notes.clear()
+    w = gt.GenericStepsWorker("F4", {})
+    d = StubD(present=[])
+    check('返回 False', w._exec_expect_el(d, dict(P, on_missing='notify')), False)
+    check('设备没停', w.stopped(), False)
+    check('没置"跳过剩余"', w._skip_rest, False)
+    check('发了通知', [n[0] for n in notes], ['task.page.mismatch'])
+
+    print('=== 5. 选择器为空 → 明确报错，不乱判 ===')
+    notes.clear()
+    w = gt.GenericStepsWorker("F5", {})
+    d = StubD(present=[])
+    check('返回 None', w._exec_expect_el(d, dict(P, selector_value='')), None)
+    check('没置"跳过剩余"', w._skip_rest, False)
+    check('没发通知', notes, [])
+finally:
+    gt.notifier.notify = orig
+
+print()
+if fails:
+    print('❌ 失败 %d 项：%s' % (len(fails), ' / '.join(fails)))
+    sys.exit(1)
+print('✅ 全部通过（没连任何真机）')

scripts/tests/test_foreach_account.py

@@ -0,0 +1,177 @@
+# -*- coding: utf-8 -*-
+"""P5 测试：`foreach_account`（一轮把本机待发的号跑完）—— 临时库，不碰真实数据。"""
+import io
+import os
+import shutil
+import sys
+import tempfile
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+
+TMP = tempfile.mkdtemp(prefix='ac_p5_')
+os.environ['DATABASE_URL'] = 'sqlite:///' + TMP.replace(chr(92), '/') + '/ac.db'
+os.environ['DATA_VIDEO_DIR'] = os.path.join(TMP, 'videos')
+os.environ['DEPLOY_ENV'] = 'dev'
+os.environ['DB_ALLOW_SQLITE_FALLBACK'] = '1'
+
+# 仓库根 = scripts/tests/ 往上三级（不写死绝对路径，换机器也能跑）
+_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, _ROOT)
+os.chdir(_ROOT)
+
+from flask import Flask                                              # noqa: E402
+from core import db_config, models                                   # noqa: E402
+from core import video_plan as vp                                    # noqa: E402
+from tasks.generic import task as gt                                 # noqa: E402
+
+DATE = '2026-09-12'
+fails = []
+
+
+def check(label, got, want):
+    ok = got == want
+    if not ok:
+        fails.append(label)
+    print(('  ✅ ' if ok else '  ❌ ') + label + ('' if ok else '\n       得到 %r\n       期望 %r' % (got, want)))
+
+
+app = Flask("t")
+uri = db_config.build_db_uri()
+app.config["SQLALCHEMY_DATABASE_URI"] = uri
+app.config["SQLALCHEMY_ENGINE_OPTIONS"] = db_config.engine_options(uri)
+app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
+models.db.init_app(app)
+with app.app_context():
+    models.db.create_all()
+vp.init_app(app)
+
+
+def seed():
+    """小王 2 条、小李 1 条、小张 1 条（未来）。"""
+    with app.app_context():
+        for i, (nm, d, s) in enumerate([('小王', DATE, 1), ('小王', DATE, 2),
+                                        ('小李', DATE, 1), ('小张', '2027-01-01', 1)]):
+            models.db.session.add(models.VideoPlan(
+                id='p%d' % i, nickname=nm, phone='', device_name='', douyin_id='',
+                serial='', release_date=d, seq=s, seq_auto=False, title='t' + str(s),
+                body='', video_file='x', video_name='x', status=vp.ST_READY,
+                created_at=vp._now(), updated_at=vp._now()))
+        models.db.session.commit()
+
+
+def status_of():
+    with app.app_context():
+        out = {}
+        for r in models.VideoPlan.query.all():
+            out.setdefault(r.nickname, []).append(r.status)
+        return {k: sorted(v) for k, v in out.items()}
+
+
+print('=== 1. 一轮把本机待发的号跑完（模拟"推+发成功"）===')
+seed()
+w = gt.GenericStepsWorker("FAKE01", {}, ctx={"job_id": "t1", "device_name": "A01"})
+order = []
+
+
+def fake_exec_ok(d, steps, depth=0):
+    """模拟一段正常的循环体：把当前 target_name 的下一条待发计划标成 done。"""
+    name = w._vars.get('target_name')
+    order.append(name)
+    with app.app_context():
+        row = (models.VideoPlan.query.filter_by(nickname=name, status=vp.ST_READY)
+               .order_by(models.VideoPlan.seq).first())
+        if row:
+            row.status = vp.ST_DONE
+            models.db.session.commit()
+
+
+w._exec_steps = fake_exec_ok
+w._exec_foreach_account(None, {"children": [{"type": "x"}],
+                               "date_source": "fixed", "fixed_date": DATE})
+# 同日期同编号时按名字**码点**定序：李 U+674E < 王 U+738B → 小李先跑
+check('两个号都跑过（小李 1 条 → 小王 2 条）', order, ['小李', '小王', '小王'])
+check('小王两条都发了', status_of()['小王'], ['done', 'done'])
+check('小李发了', status_of()['小李'], ['done'])
+check('未来的小张没动', status_of()['小张'], ['ready'])
+check('跑完把 target_name 清掉了', w._vars.get('target_name'), None)
+
+print('=== 2. 本机没登这个号 → 不卡死，直接换下一个 ===')
+with app.app_context():
+    models.VideoPlan.query.delete()
+    models.db.session.commit()
+seed()
+w2 = gt.GenericStepsWorker("FAKE02", {}, ctx={"job_id": "t2"})
+seen = []
+
+
+def fake_exec_only_xiaowang(d, steps, depth=0):
+    """只有小王的号在这台机器上：切到别人时什么都不做（模拟切号失败/守卫挡下）。"""
+    name = w2._vars.get('target_name')
+    seen.append(name)
+    if name != '小王':
+        return
+    with app.app_context():
+        row = (models.VideoPlan.query.filter_by(nickname=name, status=vp.ST_READY)
+               .order_by(models.VideoPlan.seq).first())
+        if row:
+            row.status = vp.ST_DONE
+            models.db.session.commit()
+
+
+w2._exec_steps = fake_exec_only_xiaowang
+w2._exec_foreach_account(None, {"children": [{"type": "x"}],
+                                "date_source": "fixed", "fixed_date": DATE})
+check('小王发完（2 条）', status_of()['小王'], ['done', 'done'])
+check('小李只被试了 1 次就跳过（没空转）', seen.count('小李'), 1)
+check('试过的名字不回头', seen, ['小李', '小王', '小王'])
+check('小李还是待发', status_of()['小李'], ['ready'])
+
+print('=== 3. 下一轮会接着发小李（上一轮没发完的还在队列里）===')
+w3 = gt.GenericStepsWorker("FAKE03", {}, ctx={"job_id": "t3"})
+
+
+def fake_exec_all(d, steps, depth=0):
+    name = w3._vars.get('target_name')
+    with app.app_context():
+        row = (models.VideoPlan.query.filter_by(nickname=name, status=vp.ST_READY)
+               .order_by(models.VideoPlan.seq).first())
+        if row:
+            row.status = vp.ST_DONE
+            models.db.session.commit()
+
+
+w3._exec_steps = fake_exec_all
+w3._exec_foreach_account(None, {"children": [{"type": "x"}],
+                                "date_source": "fixed", "fixed_date": DATE})
+check('小李补上了', status_of()['小李'], ['done'])
+
+print('=== 4. 没有待发的号 → 干净收工 ===')
+w4 = gt.GenericStepsWorker("FAKE04", {}, ctx={"job_id": "t4"})
+w4._exec_steps = lambda d, s, depth=0: None
+w4._exec_foreach_account(None, {"children": [{"type": "x"}],
+                                "date_source": "fixed", "fixed_date": DATE})
+check('一条都没跑（不会死循环）', w4._vars.get('target_name'), None)
+
+print('=== 5. max_accounts 上限 ===')
+with app.app_context():
+    models.VideoPlan.query.delete()
+    models.db.session.commit()
+seed()
+w5 = gt.GenericStepsWorker("FAKE05", {}, ctx={"job_id": "t5"})
+ran = []
+w5._exec_steps = lambda d, s, depth=0: ran.append(w5._vars.get('target_name'))
+w5._exec_foreach_account(None, {"children": [{"type": "x"}], "max_accounts": 1,
+                               "date_source": "fixed", "fixed_date": DATE})
+check('只跑 1 个号', ran, ['小李'])
+
+print('=== 6. 子步骤为空 → 不报错、直接结束 ===')
+w6 = gt.GenericStepsWorker("FAKE06", {})
+w6._exec_foreach_account(None, {"children": []})
+check('空 children 直接返回', w6._vars.get('target_name'), None)
+
+print()
+shutil.rmtree(TMP, ignore_errors=True)
+if fails:
+    print('❌ 失败 %d 项：%s' % (len(fails), ' / '.join(fails)))
+    sys.exit(1)
+print('✅ 全部通过（临时库已清理）')

scripts/tests/test_name_scope.py

@@ -0,0 +1,224 @@
+# -*- coding: utf-8 -*-
+"""P2 测试：读名字 / 按名字取计划 / 推送前核对（**临时库 + 假设备**，不碰真实数据、不连真机）。"""
+import io
+import os
+import shutil
+import sys
+import tempfile
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+
+TMP = tempfile.mkdtemp(prefix='ac_p2_')
+os.environ['DATABASE_URL'] = 'sqlite:///' + os.path.join(TMP, 'ac.db').replace('\\', '/')
+os.environ['DATA_VIDEO_DIR'] = os.path.join(TMP, 'videos')
+os.environ['DEPLOY_ENV'] = 'dev'
+os.environ['DB_ALLOW_SQLITE_FALLBACK'] = '1'
+
+# 仓库根 = scripts/tests/ 往上三级（不写死绝对路径，换机器也能跑）
+_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, _ROOT)
+os.chdir(_ROOT)
+
+from flask import Flask                                              # noqa: E402
+from core import db_config, models                                   # noqa: E402
+from core import video_plan as vp                                    # noqa: E402
+from tasks.generic import task as gt                                 # noqa: E402
+from tasks.generic import publish_flow as flow                       # noqa: E402
+
+fails = []
+
+
+def check(label, got, want):
+    ok = got == want
+    if not ok:
+        fails.append(label)
+    print(('  ✅ ' if ok else '  ❌ ') + label + ('' if ok else '\n       得到 %r\n       期望 %r' % (got, want)))
+
+
+def ok(label, cond, detail=''):
+    if not cond:
+        fails.append(label)
+    print(('  ✅ ' if cond else '  ❌ ') + label + ('' if cond else '  ' + str(detail)))
+
+
+class StubEl:
+    """假元素：u2 的 XPathSelector / UiObject 各用到的成员都给上。"""
+
+    def __init__(self, text):
+        self._t = text
+
+    @property
+    def exists(self):
+        return self._t is not None
+
+    def wait(self, timeout=0):
+        return self._t is not None
+
+    def get_text(self, timeout=None):
+        return self._t
+
+
+class StubD:
+    def __init__(self, text):
+        self.text = text
+
+    def xpath(self, v):
+        return StubEl(self.text)
+
+
+app = Flask("t")
+uri = db_config.build_db_uri()
+app.config["SQLALCHEMY_DATABASE_URI"] = uri
+app.config["SQLALCHEMY_ENGINE_OPTIONS"] = db_config.engine_options(uri)
+app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
+models.db.init_app(app)
+with app.app_context():
+    models.db.create_all()
+vp.init_app(app)
+
+print('=== 1. clean_account_name（纯函数）===')
+check('只有名字', vp.clean_account_name('小王'), '小王')
+check('多行：取第一行', vp.clean_account_name('小王\n编辑资料\n抖音号：35377983067'), '小王')
+check('首行是标签 → 往下找', vp.clean_account_name('编辑资料\n小王'), '小王')
+check('抖音号行跳过', vp.clean_account_name('抖音号：35377983067\n小王'), '小王')
+check('统计行跳过', vp.clean_account_name('关注\n粉丝\n小王'), '小王')
+check('名字里的双空格保留', vp.clean_account_name('有牛奶面包  你吃吗？'), '有牛奶面包  你吃吗？')
+check('名字带表情保留', vp.clean_account_name('🐟小鱼'), '🐟小鱼')
+check('「关注我领福利」不当标签', vp.clean_account_name('关注我领福利'), '关注我领福利')
+check('读到空 → ""', vp.clean_account_name('编辑资料\n抖音号：123'), '')
+check('None → ""', vp.clean_account_name(None), '')
+check('首尾空白去掉', vp.clean_account_name('  小王  '), '小王')
+
+print('=== 2. 临时库里造两条计划（小王 / 小李）===')
+with app.app_context():
+    def mk(name, date, seq, status=vp.ST_READY, title="标题"):
+        row = models.VideoPlan(id=name + str(seq) + date[-2:], nickname=name, phone="",
+                               device_name="", douyin_id="", serial="", release_date=date,
+                               seq=seq, seq_auto=False, title=title, body="",
+                               video_file=f"2026-10/x{seq}.mp4", video_name="x.mp4",
+                               status=status, created_at=vp._now(), updated_at=vp._now())
+        models.db.session.add(row)
+    mk('小王', '2026-09-12', 1)
+    mk('小王', '2026-09-13', 2)          # 同一个号，后天那条
+    mk('小李', '2026-09-12', 1)
+    mk('小张', '2026-09-20', 1)          # 未来：不该被取到
+    mk('小赵', '2026-09-10', 1, status=vp.ST_DONE)   # 已发：不该被取到
+    models.db.session.commit()
+
+    print('=== 3. 按名字取计划 ===')
+    check('小王 在 09-12 有一条', [p['seq'] for p in vp.take_for_name(['小王'], '2026-09-12')], [1])
+    check('取 09-13 时，过期的那条先发', [p['seq'] for p in vp.take_for_name(['小王'], '2026-09-13')], [1])
+    check('小李 只认自己的', [p['nickname'] for p in vp.take_for_name(['小李'], '2026-09-12')],
+          ['小李'])
+    check('没有的名字取不到', vp.take_for_name(['不存在'], '2026-09-12'), [])
+    check('名字为空不取（绝不猜）', vp.take_for_name([], '2026-09-12'), [])
+    check('未来的不发', vp.take_for_name(['小张'], '2026-09-12'), [])
+    check('已发的（done）不再入队', vp.take_for_name(['小赵'], '2026-09-12'), [])
+    check('peek 只看不占位', vp.peek_for_name(['小王'], '2026-09-12')['seq'], 1)
+    check('peek 不存在的名字 → None', vp.peek_for_name(['不存在'], '2026-09-12'), None)
+
+    print('=== 4. pending_names / pending_count（循环块的数据源）===')
+    # 同日期同编号时按名字的**码点**定序（只要确定就行，不追求拼音序）：李 U+674E < 王 U+738B
+    check('有待发内容的名字（按最早日期，同日期按名字定序）',
+          [(x['name'], x['release_date'], x['seq'])
+           for x in vp.pending_names('2026-09-13')],
+          [('小李', '2026-09-12', 1), ('小王', '2026-09-12', 1)])
+    check('只看指定的名字', [x['name'] for x in vp.pending_names('2026-09-13', names=['小王'])],
+          ['小王'])
+    check('小王 待发 2 条', vp.pending_count('小王', '2026-09-13'), 2)
+    check('小李 待发 1 条', vp.pending_count('小李', '2026-09-13'), 1)
+    check('已完成的名字不在列表里', [x['name'] for x in vp.pending_names('2026-09-12', names=['小赵'])],
+          [])
+    check('未来日期还没到 → 今天不列', vp.pending_count('小张', '2026-09-12'), 0)
+
+    print('=== 5. 读名字步骤（假设备）===')
+    ctx = {"job_id": "t1", "job_name": "测试"}
+    w = gt.GenericStepsWorker("FAKE01", {}, ctx=ctx)
+    el_raw = '小王\n编辑资料\n抖音号：35377983067'
+    r = w._exec_read_account_name(StubD(el_raw), {"selector_type": "xpath",
+                                                  "selector_value": "//x", "timeout": 1})
+    check('读到名字 → True', r, True)
+    check('_vars.account_name', w._vars.get('account_name'), '小王')
+    check('_vars.name_selector 记下了', w._vars.get('name_selector'), ('xpath', '//x'))
+
+    w2 = gt.GenericStepsWorker("FAKE02", {}, ctx=ctx)
+    r2 = w2._exec_read_account_name(StubD('编辑资料\n抖音号：123'),
+                                    {"selector_type": "xpath", "selector_value": "//x", "timeout": 1})
+    check('读不到（on_missing=fail）→ False', r2, False)
+    check('读不到时不写 account_name', w2._vars.get('account_name'), None)
+
+    w3 = gt.GenericStepsWorker("FAKE03", {}, ctx=ctx)
+    r3 = w3._exec_read_account_name(StubD('编辑资料'), {"selector_type": "xpath",
+                                                       "selector_value": "//x",
+                                                       "on_missing": "skip"})
+    check('on_missing=skip → None（不失败）', r3, None)
+
+    w4 = gt.GenericStepsWorker("FAKE04", {}, ctx=ctx)
+    r4 = w4._exec_read_account_name(StubD('小王'), {"selector_type": "xpath",
+                                                   "selector_value": ""})
+    check('选择器为空 → False（并提示去抓元素）', r4, False)
+
+    print('=== 6. _release_scope：这次发的是哪个号 ===')
+    check('默认按名字（读到谁就是谁）', w._release_scope({}), ('name', ['小王'], '名字『小王』'))
+    check('没有名字 → 空值（跳过，不猜）', w2._release_scope({}),
+          ('name', [], '没读到本机账号名字（前面要有「读取本机账号名字」，'
+                       '或由循环块设目标名字）→ 跳过'))
+    check('account=phone 走老路径', w._release_scope({'account': 'phone',
+                                                    'account_phone': '13300000000'}),
+          ('phone', ['13300000000'], '指定手机号 13300000000'))
+    check('cycle 设的目标名字优先', (w._vars.__setitem__('target_name', '小李'),
+                                    w._release_scope({}))[1], ('name', ['小李'], '名字『小李』'))
+    w._vars.pop('target_name')
+
+    print('=== 7. 条件判断候选值 ===')
+    txt, note = w._resolve_cmp_value({'cmp_source': 'account_target'}, '')
+    check('account_target → 候选=名字', txt, '小王')
+    ok('说明里写了名字', '小王' in note, note)
+    txt2, _ = w2._resolve_cmp_value({'cmp_source': 'account_target'}, '')
+    check('读不到名字 → 候选为空（永远不命中 → 不发）', txt2, '')
+    txt3, _ = w2._resolve_cmp_value({'cmp_source': 'account_target', 'cmp_value': '手填的'}, '手填的')
+    check('读不到名字时手填值仍然生效', txt3, '手填的')
+
+    print('=== 8. 推送前核对（假设备，push_one 打桩）===')
+    calls = []
+    orig = flow.push_one
+
+    def fake_push(serial, plan, opts, log=None):
+        calls.append((serial, plan['id']))
+        return True, "ok"
+
+    flow.push_one = fake_push
+    try:
+        # 8a 屏幕上不是我们要发的人 → 不推
+        w._vars['account_name'] = '小王'
+        w._vars['name_selector'] = ('xpath', '//x')
+        bad = w._exec_push_release(StubD('小李'), {'account': 'name',
+                                                  'date_source': 'fixed',
+                                                  'fixed_date': '2026-09-12'})
+        check('核对不过 → 不推（返回 None）', bad, None)
+        check('push_one 一次都没调', calls, [])
+
+        # 8b 屏幕上就是本人 → 推
+        good = w._exec_push_release(StubD('小王'), {'account': 'name',
+                                                   'date_source': 'fixed',
+                                                   'fixed_date': '2026-09-12'})
+        check('核对通过 → 推成功', good, True)
+        check('push_one 被调了 1 次', len(calls), 1)
+        check('推的是小王那条', calls[0][1], '小王112')
+
+        # 8c 读不到名字 → 不推
+        calls.clear()
+        w2._vars['name_selector'] = ('xpath', '//x')
+        none_ = w2._exec_push_release(StubD('编辑资料'), {'date_source': 'fixed',
+                                                          'fixed_date': '2026-09-12'})
+        check('读不到名字 → 不推', none_, None)
+        check('push_one 没被调', calls, [])
+    finally:
+        flow.push_one = orig
+
+print()
+shutil.rmtree(TMP, ignore_errors=True)
+if fails:
+    print('❌ 失败 %d 项：%s' % (len(fails), ' / '.join(fails)))
+    sys.exit(1)
+print('✅ 全部通过（临时库已清理）')

scripts/tests/test_parse_name.py

@@ -0,0 +1,129 @@
+# -*- coding: utf-8 -*-
+"""P1 纯函数测试：`名字_日期_编号` 解析（不碰 DB、不碰用户数据）。"""
+import io
+import os
+import sys
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+# 仓库根 = scripts/tests/ 往上三级（不写死绝对路径，换机器也能跑）
+_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, _ROOT)
+os.chdir(_ROOT)
+from core import video_plan as vp                                     # noqa: E402
+
+fails = []
+
+
+def check(label, got, want):
+    ok = got == want
+    if not ok:
+        fails.append(label)
+    print(('  ✅ ' if ok else '  ❌ ') + label + ('' if ok else '\n       得到 %r\n       期望 %r' % (got, want)))
+
+
+print('=== parse_video_name：合法 ===')
+check('名字_日期_编号', vp.parse_video_name('小王_20260912_1.mp4')[0],
+      {"name": "小王", "date": "2026-09-12", "seq": 1, "seq_given": True})
+check('名字_日期（无编号）', vp.parse_video_name('建材王总_20260913.mp4')[0],
+      {"name": "建材王总", "date": "2026-09-13", "seq": None, "seq_given": False})
+check('名字里带数字', vp.parse_video_name('翻斗花园我最强2号_20260913.mp4')[0]['name'], '翻斗花园我最强2号')
+check('名字里带空格/表情', vp.parse_video_name('有牛奶面包  你吃吗？_20260912_2.mp4')[0]['name'],
+      '有牛奶面包  你吃吗？')
+check('名字里带表情', vp.parse_video_name('🐟小鱼_20260912.mp4')[0]['name'], '🐟小鱼')
+check('大写扩展名', vp.parse_video_name('小王_20260912.MP4')[0]['date'], '2026-09-12')
+check('编号 3 位', vp.parse_video_name('小王_20260912_999.mp4')[0]['seq'], 999)
+
+print('=== parse_video_name：图片（图文）也认 ===')
+check('jpg', vp.parse_video_name('小王_20260912_1.jpg')[0],
+      {"name": "小王", "date": "2026-09-12", "seq": 1, "seq_given": True})
+check('png（无编号）', vp.parse_video_name('建材王总_20260913.png')[0],
+      {"name": "建材王总", "date": "2026-09-13", "seq": None, "seq_given": False})
+check('大写 JPG', vp.parse_video_name('小王_20260912.JPG')[0]['name'], '小王')
+check('webp', vp.parse_video_name('小王_20260912.webp')[0]['date'], '2026-09-12')
+check('gif 不收（没进白名单）',
+      '不是视频/图片' in (vp.parse_video_name('小王_20260912.gif')[1] or ''), True)
+
+print('=== parse_video_name：拒收 ===')
+
+
+def err_of(fn):
+    return fn[1]
+
+
+check('名字带下划线', err_of(vp.parse_video_name('小_王_20260912.mp4')),
+      '名字里不能有下划线：`小_王_20260912` 里日期前面有 2 段 ——应为 名字_日期_编号')
+check('名字是纯数字', err_of(vp.parse_video_name('12345678_20260912.mp4')),
+      '名字不能是纯数字（12345678 会被当成日期/编号）—— 请填抖音上的昵称')
+check('结尾不是日期', err_of(vp.parse_video_name('小王_20260912_1234.mp4')),
+      '文件名格式不对：`小王_20260912_1234` 的结尾既不是日期（8 位数字，如 20260912），'
+      '也不是「日期_编号」—— 应为 名字_日期_编号')
+check('老格式（手机号在前）', err_of(vp.parse_video_name('13382508423_20261011_01.mp4')),
+      '这一段（13382508423）是手机号 —— 文件名第一段要填**抖音上的名字**，'
+      '格式是 名字_日期_编号（现在不认手机号了）')
+check('非法日期', err_of(vp.parse_video_name('小王_20260230.mp4')),
+      '日期 20260230 不是合法日期（应为 20260912 这种 8 位）')
+check('只有一段', err_of(vp.parse_video_name('小王.mp4')),
+      '文件名格式不对，应为 名字_日期_编号（编号可省略，如 小王_20260912.mp4）')
+check('不是视频/图片', err_of(vp.parse_video_name('小王_20260912.txt')),
+      '不是视频/图片文件（支持 mp4/mov/mkv/avi/3gp/flv/wmv/m4v/ts/webm/jpg/jpeg/png/webp/heic）')
+check('空文件名', err_of(vp.parse_video_name('')), '文件名为空')
+check('多段（名字含下划线还带日期）', err_of(vp.parse_video_name('小_王_总_20260912.mp4')),
+      '名字里不能有下划线：`小_王_总_20260912` 里日期前面有 3 段 ——应为 名字_日期_编号')
+
+print('=== parse_title_line：合法 ===')
+check('标题 || 正文_名字_日期_编号', vp.parse_title_line('中秋祝福 || 祝大家中秋快乐_小王_20260912_1')[0],
+      {"title": "中秋祝福", "body": "祝大家中秋快乐", "name": "小王",
+       "date": "2026-09-12", "seq": 1, "seq_given": True})
+check('只有标题', vp.parse_title_line('中秋祝福_小王_20260912')[0],
+      {"title": "中秋祝福", "body": "", "name": "小王",
+       "date": "2026-09-12", "seq": None, "seq_given": False})
+check('只有正文（|| 在最前）', vp.parse_title_line(' || 只有正文_小王_20260912')[0]['body'], '只有正文')
+check('标题里带下划线', vp.parse_title_line('名字带_下划线也行_小王_20260912')[0]['title'], '名字带_下划线也行')
+check('#话题开头的标题', vp.parse_title_line('#中秋快乐_小王_20260929')[0]['title'], '#中秋快乐')
+check('正文里再有 || 原样保留', vp.parse_title_line('标题 || 正文 || 又一处_小王_20260912')[0]['body'],
+      '正文 || 又一处')
+check('标题是纯数字', vp.parse_title_line('2026_小王_20260912_1')[0]['title'], '2026')
+
+print('=== parse_title_line：拒收 ===')
+check('只有名字/日期（没文字）', err_of(vp.parse_title_line('小王_20260912')),
+      '缺标题/正文内容（只有名字/日期/编号，没有文字）')
+check('名字/日期/编号（没文字）', err_of(vp.parse_title_line('小王_20260912_1')),
+      '缺标题/正文内容（只有名字/日期/编号，没有文字）')
+check('老写法（名字在前）', err_of(vp.parse_title_line('19286456013_20260912_1_标题')),
+      "格式不对，应为「标题 || 正文_名字_日期_编号」（编号可省略；日期是 8 位数字，如 20260912）")
+check('名字是手机号', err_of(vp.parse_title_line('标题_13382508423_20260912')),
+      '这一段（13382508423）是手机号 —— 文件名第一段要填**抖音上的名字**，'
+      '格式是 名字_日期_编号（现在不认手机号了）')
+check('标题里带下划线（名字取紧挨日期那段）',
+      vp.parse_title_line('标题_小_王_20260912')[0],
+      {"title": "标题_小", "body": "", "name": "王", "date": "2026-09-12",
+       "seq": None, "seq_given": False})
+check('空行', err_of(vp.parse_title_line('   ')), '空行')
+
+print('=== parse_titles_text：注释与多行 ===')
+rows, errors = vp.parse_titles_text(
+    '标题一_小王_20260912\n# 这是注释\n\n#中秋快乐_小王_20260913\n'
+    '#真注释_没有日期\n标题没有日期')
+check('收下 2 条标题', [r['title'] for r in rows], ['标题一', '#中秋快乐'])
+check('# 认不出名字/日期 → 当注释忽略', [(e['line'], e['raw']) for e in errors], [(6, '标题没有日期')])
+
+print('=== pair_slots：按名字配对 ===')
+videos = [dict(vp.parse_video_name('小王_20260912_1.mp4')[0], ref='v1'),
+          dict(vp.parse_video_name('小王_20260912_2.mp4')[0], ref='v2'),
+          dict(vp.parse_video_name('小李_20260912.mp4')[0], ref='v3')]
+titles = [dict(vp.parse_title_line('标题A_小王_20260912')[0], ref='t1'),
+          dict(vp.parse_title_line('标题B_小王_20260912')[0], ref='t2'),
+          dict(vp.parse_title_line('标题C_小李_20260912')[0], ref='t3')]
+pairs, rejected = vp.pair_slots(videos, titles)
+check('配成 3 对', len(pairs), 3)
+check('没有拒收', rejected, [])
+check('按 (日期,名字,编号) 排序', [(p['date'], p['name'], p['seq']) for p in pairs],
+      [('2026-09-12', '小李', 1), ('2026-09-12', '小王', 1), ('2026-09-12', '小王', 2)])
+check('每对都配上标题', sorted(p['title']['title'] for p in pairs), ['标题A', '标题B', '标题C'])
+check('配对结果里的键是 name', all('name' in p and 'phone' not in p for p in pairs), True)
+
+print()
+if fails:
+    print('❌ 失败 %d 项：%s' % (len(fails), ' / '.join(fails)))
+    sys.exit(1)
+print('✅ 全部通过')

scripts/tests/test_push_by_name.py

@@ -0,0 +1,146 @@
+# -*- coding: utf-8 -*-
+"""P6 测试：按名字找设备推送（`_push_by_name`）—— 临时库 + 假探测/假推送，不碰真机。"""
+import io
+import os
+import shutil
+import sys
+import tempfile
+import time
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+
+TMP = tempfile.mkdtemp(prefix='ac_p6_')
+os.environ['DATABASE_URL'] = 'sqlite:///' + TMP.replace(chr(92), '/') + '/ac.db'
+os.environ['DATA_VIDEO_DIR'] = os.path.join(TMP, 'videos')
+os.environ['DEPLOY_ENV'] = 'dev'
+os.environ['DB_ALLOW_SQLITE_FALLBACK'] = '1'
+
+# 仓库根 = scripts/tests/ 往上三级（不写死绝对路径，换机器也能跑）
+_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, _ROOT)
+os.chdir(_ROOT)
+
+from flask import Flask                                              # noqa: E402
+from core import db_config, models, device_pool                      # noqa: E402
+from core import video_plan as vp                                    # noqa: E402
+from core import account_probe                                       # noqa: E402
+from tasks.generic import publish_flow as flow                       # noqa: E402
+from web import video_plan_api as vapi                               # noqa: E402
+
+DATE = '2026-09-12'
+fails = []
+
+
+def check(label, got, want):
+    ok = got == want
+    if not ok:
+        fails.append(label)
+    print(('  ✅ ' if ok else '  ❌ ') + label + ('' if ok else '\n       得到 %r\n       期望 %r' % (got, want)))
+
+
+app = Flask("t")
+uri = db_config.build_db_uri()
+app.config["SQLALCHEMY_DATABASE_URI"] = uri
+app.config["SQLALCHEMY_ENGINE_OPTIONS"] = db_config.engine_options(uri)
+app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
+models.db.init_app(app)
+with app.app_context():
+    models.db.create_all()
+vp.init_app(app)
+device_pool.init_app(app)
+
+with app.app_context():
+    models.db.session.add(models.Device(serial='A:5555', name='A01', enabled=True,
+                                        created_at=vp._now()))
+    models.db.session.add(models.Device(serial='B:5555', name='A02', enabled=True,
+                                        created_at=vp._now()))
+    for i, (nm, s) in enumerate([('小王', 1), ('小王', 2), ('小李', 1)]):
+        models.db.session.add(models.VideoPlan(
+            id='p%d' % i, nickname=nm, phone='', device_name='', douyin_id='', serial='',
+            release_date=DATE, seq=s, seq_auto=False, title='t', body='',
+            video_file='x', video_name='x', status=vp.ST_READY,
+            created_at=vp._now(), updated_at=vp._now()))
+    models.db.session.commit()
+
+pushed = []
+lock = []
+
+
+def fake_push(serial, plan, opts=None, log=None):
+    pushed.append((serial, plan['nickname'], plan['seq'], (opts or {}).get('device_name')))
+    return True, "ok"
+
+
+print('=== 1. 名字 → 设备（两台设备各登一个）===')
+probe = {'A:5555': {'serial': 'A:5555', 'name': '小王', 'error': ''},
+         'B:5555': {'serial': 'B:5555', 'name': '小李', 'error': ''}}
+orig_probe, orig_push = account_probe.probe_online, flow.push_one
+account_probe.probe_online = lambda serials=None, skip_busy=True, workers=4: probe
+flow.push_one = fake_push
+try:
+    with app.app_context():
+        rows = vp.pushable_plans(DATE)
+        matched, unmatched = vapi._push_by_name(rows)
+        deadline = time.time() + 3
+        while len(pushed) < 3 and time.time() < deadline:
+            time.sleep(0.05)
+    check('两个名字都找到设备', sorted((m['name'], m['count']) for m in matched),
+          [('小李', 1), ('小王', 2)])
+    check('小王的设备是 A01', [m['device_name'] for m in matched if m['name'] == '小王'], ['A01'])
+    check('没有 unmatched', unmatched, [])
+    check('推了小王的 2 条 + 小李的 1 条', len(pushed), 3)
+    check('推给 A 的是小王的两条（按编号）',
+          sorted((s, q) for (ser, n, q, dn) in pushed if ser == 'A:5555'), [(1, 1), (1, 2)])
+    check('推给 B 的是小李', [(n, q) for (ser, n, q, dn) in pushed if ser == 'B:5555'],
+          [('小李', 1)])
+    check('顺手把设备名字传给了 push_one（写 posted_device_name 用）',
+          {dn for (ser, n, q, dn) in pushed}, {'A01', 'A02'})
+    with app.app_context():
+        cached = [(d.serial, d.cur_account_name)
+                  for d in models.Device.query.order_by(models.Device.serial)]
+    check('探测结果缓存进了 device 表', cached,
+          [('A:5555', '小王'), ('B:5555', '小李')])
+
+    print('=== 2. 没人登着某个名字 → unmatched 里逐条说明 ===')
+    pushed.clear()
+    probe2 = {'A:5555': {'serial': 'A:5555', 'name': '小王', 'error': ''},
+              'B:5555': {'serial': 'B:5555', 'name': '别的号', 'error': ''}}
+    account_probe.probe_online = lambda serials=None, skip_busy=True, workers=4: probe2
+    with app.app_context():
+        rows = vp.pushable_plans(DATE)
+        matched2, unmatched2 = vapi._push_by_name(rows)
+        deadline = time.time() + 3
+        while len(pushed) < 2 and time.time() < deadline:
+            time.sleep(0.05)
+    check('只推了小王那 2 条', len(pushed), 2)
+    check('小李进了 unmatched', [(u['name'], u['count']) for u in unmatched2], [('小李', 1)])
+    check('原因说清了「先切号」', ('没有在线设备登着' in unmatched2[0]['reason']
+                                  and '小李' in unmatched2[0]['reason']
+                                  and '先到设备上切到它' in unmatched2[0]['reason']), True)
+    check('原因里带上当前探测到的号（排查用，别把整个 dict 打出来）',
+          unmatched2[0]['reason'].endswith('（当前探测到：A:5555(小王)、B:5555(别的号)）'), True)
+    if 'dict' in unmatched2[0]['reason'] or '{' in unmatched2[0]['reason']:
+        print('     原因里混进了原始 dict：', unmatched2[0]['reason'])
+
+    print('=== 3. 探测失败（比如选择器没配）→ 也算没设备登着，不炸 ===')
+    pushed.clear()
+    account_probe.probe_online = lambda serials=None, skip_busy=True, workers=4: {
+        'A:5555': {'serial': 'A:5555', 'name': '', 'error': '还没抓昵称控件'},
+        'B:5555': {'serial': 'B:5555', 'name': '', 'error': '连不上设备'}}
+    with app.app_context():
+        rows = vp.pushable_plans(DATE)
+        matched3, unmatched3 = vapi._push_by_name(rows)
+    check('一条都没推', pushed, [])
+    check('两个名字都 unmatched', sorted(u['name'] for u in unmatched3), ['小李', '小王'])
+    with app.app_context():
+        keep = models.Device.query.get('A:5555').cur_account_name
+    check('失败的那台不清空旧缓存', keep, '小王')
+finally:
+    account_probe.probe_online, flow.push_one = orig_probe, orig_push
+
+print()
+shutil.rmtree(TMP, ignore_errors=True)
+if fails:
+    print('❌ 失败 %d 项：%s' % (len(fails), ' / '.join(fails)))
+    sys.exit(1)
+print('✅ 全部通过（临时库已清理）')

scripts/tests/test_read_text.py

@@ -0,0 +1,198 @@
+# -*- coding: utf-8 -*-
+"""「读取文字」+ 选择器里的 `{变量}` +「条件判断→变量」用例。
+
+假设备，不连真机。验三件事：
+  ① 选择器值里写 `{本次要发的名字}` / `{本机账号名字}` → 真的换成本轮的值；
+     变量是空的 → 换成空串、这一步找不到元素（**不能留着字面量去瞎点**）；
+  ② 「读取文字」把元素文字读出来、清洗、存进指定变量（变量名叫 account_name 时顺手记下昵称控件）；
+  ③ 「条件判断」候选值来源选「变量」→ 候选就是那个变量的值，空变量 = 不命中。
+"""
+import io
+import os
+import sqlite3
+import sys
+import tempfile
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+os.environ['DATABASE_URL'] = 'sqlite:///' + os.path.join(tempfile.mkdtemp(), 'ac.db').replace('\\', '/')
+os.environ['DATA_VIDEO_DIR'] = tempfile.mkdtemp()
+os.environ['DEPLOY_ENV'] = 'dev'
+os.environ['DB_ALLOW_SQLITE_FALLBACK'] = '1'
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+os.chdir(sys.path[0])
+
+from tasks.generic import task as gt                                   # noqa: E402
+from core import task_draft                                            # noqa: E402
+
+fails = []
+
+
+def check(label, got, want):
+    ok = got == want
+    if not ok:
+        fails.append(label)
+    print(('  ✅ ' if ok else '  ❌ ') + label + ('' if ok else '\n       得到 %r\n       期望 %r' % (got, want)))
+
+
+class El:
+    def __init__(self, flag, text=""):
+        self._flag = flag
+        self._text = text
+        self.clicked = False
+
+    @property
+    def exists(self):
+        return _Ex(self._flag)
+
+    def wait(self, timeout=0):
+        return self._flag
+
+    def get_text(self, timeout=None):
+        return self._text
+
+    def click(self):
+        self.clicked = True
+
+
+class _Ex:
+    def __init__(self, f):
+        self.f = f
+
+    def __call__(self, timeout=0):
+        return self.f
+
+    def __bool__(self):
+        return self.f
+
+
+class StubD:
+    """`kw` 里记最后一次 d(**kw) 的参数；`texts` 给元素文本。"""
+
+    def __init__(self, present=(), texts=None):
+        self.present = set(present)
+        self.texts = texts or {}
+        self.last_kw = None
+        self.clicked = []
+
+    def xpath(self, v):
+        return El(v in self.present, self.texts.get(v, ""))
+
+    def __call__(self, **kw):
+        self.last_kw = kw
+        v = list(kw.values())[0]
+        if v in self.present:
+            self.clicked.append(v)
+        return El(v in self.present, self.texts.get(v, ""))
+
+
+print('=== 1. 选择器值里的 {本次要发的名字} 换成本轮目标 ===')
+w = gt.GenericStepsWorker("F1", {})
+w._vars['target_name'] = '锋哥苏州寻宝藏小店'
+d = StubD(present=['锋哥苏州寻宝藏小店'])
+check('点击命中（说明选择器已代入）',
+      w._exec_click(d, {"selector_type": "textContains",
+                        "selector_value": "{本次要发的名字}", "wait_timeout": 1}, 0), True)
+check('实际用的选择器 = 名字本身', d.last_kw, {'textContains': '锋哥苏州寻宝藏小店'})
+
+print('=== 2. 变量还是空的 → 选择器变空 → 不许瞎点 ===')
+w = gt.GenericStepsWorker("F2", {})
+d = StubD(present=[''])
+check('返回 False（没找到）',
+      w._exec_click(d, {"selector_type": "textContains",
+                        "selector_value": "prefix-{本次要发的名字}", "wait_timeout": 1}, 0), False)
+check('空变量 → 字符串里不留 {…} 字面量', d.last_kw, {'textContains': 'prefix-'})
+
+print('=== 3. {本机账号名字} 用「读取文字」读到的值 ===')
+w = gt.GenericStepsWorker("F3", {})
+w._vars['account_name'] = '小王'
+d = StubD(present=['小王'])
+check('等待元素命中', w._exec_wait_el(d, {"selector_type": "text",
+                                          "selector_value": "{本机账号名字}", "timeout": 1}, 0), True)
+check('用的是本机账号名', d.last_kw, {'text': '小王'})
+
+print('=== 4. 「读取文字」读出来、清洗、存变量 ===')
+w = gt.GenericStepsWorker("F4", {})
+d = StubD(present=['//*[@text="nick"]'],
+          texts={'//*[@text="nick"]': '  锋哥苏州康养探店  \n编辑资料  \n抖音号：123'})
+check('返回 True', w._exec_read_text(d, {"selector_type": "xpath",
+                                        "selector_value": '//*[@text="nick"]',
+                                        "var": "account_name", "clean": "account",
+                                        "timeout": 1}, 0), True)
+check('存进 account_name（按账号名清洗：取第一行非标签）',
+      w._vars.get('account_name'), '锋哥苏州康养探店')
+check('顺手记下昵称控件（切号/推送核对复用）',
+      w._vars.get('name_selector'), ('xpath', '//*[@text="nick"]'))
+
+print('=== 5. clean=strip：原样（只去首尾空白） ===')
+w = gt.GenericStepsWorker("F5", {})
+d = StubD(present=['//*[@text="x"]'],
+          texts={'//*[@text="x"]': '  小王  \n编辑资料'})
+w._exec_read_text(d, {"selector_type": "xpath", "selector_value": '//*[@text="x"]',
+                      "var": "raw_name", "clean": "strip", "timeout": 1}, 0)
+check('只去首尾空白、不按行取', w._vars.get('raw_name'), '小王  \n编辑资料')
+check('变量名不是 account_name → 不记昵称控件', w._vars.get('name_selector'), None)
+
+print('=== 6. 读不到：默认 skip（只记一句、不拦任务） ===')
+w = gt.GenericStepsWorker("F6", {})
+d = StubD(present=[])
+check('返回 None（skip 不算失败）',
+      w._exec_read_text(d, {"selector_type": "xpath", "selector_value": '//*[@text="没有"]',
+                            "var": "account_name", "timeout": 1}, 0), None)
+check('变量被置空', w._vars.get('account_name'), '')
+
+print('=== 7. 读不到 + on_missing=fail → 算这一步失败 ===')
+w = gt.GenericStepsWorker("F7", {})
+d = StubD(present=[])
+check('返回 False',
+      w._exec_read_text(d, {"selector_type": "xpath", "selector_value": '//*[@text="没有"]',
+                            "var": "v", "timeout": 1, "on_missing": "fail"}, 0), False)
+
+print('=== 8. 「条件判断」候选值来源=变量 ===')
+w = gt.GenericStepsWorker("F8", {})
+w._vars['account_name'] = '小王'
+val, note = w._resolve_cmp_value({"cmp_op": "等于", "cmp_source": "var",
+                                  "cmp_var": "account_name"}, "")
+check('候选值 = 变量的值', val, '小王')
+check('来源说明写清了', 'account_name' in note and '小王' in note, True)
+
+print('=== 9. 变量是空的 → 候选为空（永远不命中，走 else） ===')
+w = gt.GenericStepsWorker("F9", {})
+val, note = w._resolve_cmp_value({"cmp_op": "等于", "cmp_source": "var",
+                                  "cmp_var": "account_name"}, "手填兜底")
+check('只剩手填值', val, '手填兜底')
+check('说明里点出变量是空的', '空' in note, True)
+
+print('=== 10. 草稿校验认这两个新能力 ===')
+ok_steps = [{"type": "read_text", "label": "读取文字",
+             "params": {"selector_type": "xpath", "selector_value": '//*[@id="nick"]',
+                        "var": "account_name"}},
+            {"type": "if_el", "label": "条件判断",
+             "params": {"selector_type": "xpath", "selector_value": '//*[@id="nick"]',
+                        "cmp_op": "包含", "cmp_source": "var", "cmp_var": "account_name",
+                        "then": [{"type": "notify", "label": "命中",
+                                  "params": {"title": "ok", "message": "ok"}}],
+                        "else": []}}]
+errs, warns = [], []
+task_draft.validate_steps(ok_steps, errors=errs, warnings=warns)
+check('合法草稿没有 error', errs, [])
+
+bad_steps = [{"type": "read_text", "label": "读取文字",
+              "params": {"selector_type": "xpath", "selector_value": ""}}]
+errs2 = []
+task_draft.validate_steps(bad_steps, errors=errs2, warnings=[])
+check('「读取文字」缺选择器 → 报错',
+      any('selector_value' in e for e in errs2), True)
+
+bad2 = [{"type": "if_el", "label": "条件判断",
+         "params": {"selector_type": "xpath", "selector_value": '//*[@id="x"]',
+                    "cmp_op": "包含", "cmp_source": "var", "then": [], "else": []}}]
+errs3 = []
+task_draft.validate_steps(bad2, errors=errs3, warnings=[])
+check('来源=变量但没填变量名 → 报错',
+      any('cmp_var' in e for e in errs3), True)
+
+print()
+if fails:
+    print('❌ 失败 %d 项：%s' % (len(fails), ' / '.join(fails)))
+    sys.exit(1)
+print('✅ 全部通过（没连任何真机）')

scripts/tests/test_switch_account.py

@@ -0,0 +1,213 @@
+# -*- coding: utf-8 -*-
+"""P4 测试：`switch_account`（按名字找控件点击 + 回读校验）—— 假设备，不碰真机。
+
+不连 adb、不连真机：`d` 是个模拟对象，只实现 u2 里这一步用到的那几个成员。
+"""
+import io
+import os
+import sys
+import time
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+os.environ['DATABASE_URL'] = 'sqlite:///:memory:'
+os.environ['DEPLOY_ENV'] = 'dev'
+os.environ['DB_ALLOW_SQLITE_FALLBACK'] = '1'
+# 仓库根 = scripts/tests/ 往上三级（不写死绝对路径，换机器也能跑）
+_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, _ROOT)
+os.chdir(_ROOT)
+
+from tasks.generic import task as gt                                 # noqa: E402
+
+fails = []
+
+
+def check(label, got, want):
+    ok = got == want
+    if not ok:
+        fails.append(label)
+    print(('  ✅ ' if ok else '  ❌ ') + label + ('' if ok else '\n       得到 %r\n       期望 %r' % (got, want)))
+
+
+class Exists:
+    """u2 的 `exists` 语义：**既可当属性判真假、也可当函数带超时调用**。
+
+    真实 u2 里 `d.xpath(...).exists` 是纯 bool 属性，而 `d(text=...).exists` 是
+    可调用的 Exists 对象（`bool()` 即时判断、`exists(timeout=t)` 带等待）。
+    两处写法都要能被这一步的代码用，所以桩里做个两者通吃的。
+    """
+
+    def __init__(self, flag):
+        self.flag = flag
+
+    def __call__(self, timeout=0):
+        return self.flag
+
+    def __bool__(self):
+        return self.flag
+
+
+class El:
+    def __init__(self, text=None, exists=True, on_click=None):
+        self._t = text
+        self._on = on_click
+        self._e = Exists(exists)
+
+    @property
+    def exists(self):
+        return self._e
+
+    def wait(self, timeout=0):
+        return self._e.flag
+
+    def get_text(self, timeout=None):
+        return self._t
+
+    def click(self):
+        if self._on:
+            self._on()
+
+
+class StubD:
+    """模拟抖音：能读昵称、能进账号列表、能按名字点号。"""
+
+    def __init__(self, cur='小李', accounts=('小王', '小李'), login=False):
+        self.cur = cur
+        self.accounts = list(accounts)
+        self.login = login
+        self.clicked = []
+        self.switch_ok = True          # False = 点了但没切过去（模拟没生效）
+        self.switch_open = True        # False = 进不去账号列表
+
+    def _click_name(self, name):
+        self.clicked.append(name)
+        if self.switch_ok:
+            self.cur = name
+            self.accounts = []      # 真机上点成功后**面板会关掉**（那几行消失）——
+            # 步骤就是靠这个判断"点成功了"的：面板还在 = 这一下被吞了，要再点一次
+
+    LOGIN_HINTS = ('验证码', '其他方式登录', '手机号登录', '一键登录', '密码登录')
+
+    def xpath(self, v):
+        if v == '//name':
+            # 登录页上**根本没有昵称这个控件**（元素不存在）—— 这才是真实情况，
+            # 所以"读名字"会读到空串（而不是读到一堆登录页的文字）
+            return El(None, exists=False) if self.login else El(self.cur)
+        if v == '//switch':
+            return El('', exists=(self.switch_open and not self.login))
+        return El('', exists=False)
+
+    def __call__(self, **kw):
+        if 'descriptionContains' in kw:
+            return El('', exists=(kw['descriptionContains'] == '我'))
+        if 'textContains' in kw:
+            nm = kw['textContains']
+            if self.login and nm in self.LOGIN_HINTS:
+                return El(nm)
+            if nm in self.accounts:
+                return El(nm, on_click=lambda n=nm: self._click_name(n))
+            return El('', exists=False)
+        if 'text' in kw:
+            nm = kw['text']
+            if nm in self.accounts:
+                return El(nm, on_click=lambda n=nm: self._click_name(n))
+            return El('', exists=False)
+        return El('', exists=False)
+
+
+PARAMS = {'target': 'var:target_name', 'switch_selector_type': 'xpath',
+          'switch_selector_value': '//switch', 'name_selector_type': 'xpath',
+          'name_selector_value': '//name', 'timeout': 1, 'max_attempts': 2,
+          # 切完后等它重载的秒数（真机默认 15s）—— 用例里调小，不然一跑就是一分多钟
+          'wait_after': 0.2}
+
+notes = []
+orig_notify = gt.notifier.notify
+gt.notifier.notify = lambda ev, **kw: notes.append((ev, kw.get('want') or ''))
+try:
+    print('=== 1. 已经是目标 → 直接成功，不点任何东西 ===')
+    w = gt.GenericStepsWorker("F1", {})
+    w._vars['target_name'] = '小李'
+    d = StubD(cur='小李')
+    check('返回 True', w._exec_switch_account(d, PARAMS), True)
+    check('一个号都没点', d.clicked, [])
+
+    print('=== 2. 切到另一个号（在列表里按名字点）===')
+    w = gt.GenericStepsWorker("F2", {})
+    w._vars['target_name'] = '小王'
+    d = StubD(cur='小李')
+    check('返回 True', w._exec_switch_account(d, PARAMS), True)
+    check('点是按名字点的', d.clicked, ['小王'])
+    check('当前号变了', d.cur, '小王')
+    check('顺手把运行期变量同步成新名字', w._vars.get('account_name'), '小王')
+
+    print('=== 3. 列表里没有这个名字（本机没登）→ 立刻 False、不重试 ===')
+    notes.clear()
+    w = gt.GenericStepsWorker("F3", {})
+    w._vars['target_name'] = '不存在的号'
+    d = StubD(cur='小李')
+    check('返回 False', w._exec_switch_account(d, PARAMS), False)
+    check('只找了一次（没重试）', d.clicked, [])
+    check('发了切号失败通知', [n[0] for n in notes], ['task.account.switch_failed'])
+    check('通知里带上想切的目标', notes[0][1], '不存在的号')
+
+    print('=== 4. 点了但没切过去 → 按 max_attempts 重试后放弃 + 通知 ===')
+    notes.clear()
+    w = gt.GenericStepsWorker("F4", {})
+    w._vars['target_name'] = '小王'
+    d = StubD(cur='小李')
+    d.switch_ok = False            # 抖音没反应
+    check('返回 False', w._exec_switch_account(d, PARAMS), False)
+    # 面板一直没关（点一次吞一次）→ 每次尝试点两下、共 2 次尝试
+    check('试了 2 次尝试、每次点两下', d.clicked, ['小王', '小王', '小王', '小王'])
+    check('发了切号失败通知', [n[0] for n in notes], ['task.account.switch_failed'])
+
+    print('=== 5. 卡在登录/验证码页 → 通知 + 停本设备 ===')
+    notes.clear()
+    w = gt.GenericStepsWorker("F5", {})
+    w._vars['target_name'] = '小王'
+    d = StubD(cur='小李', login=True)
+    check('返回 False', w._exec_switch_account(d, PARAMS), False)
+    check('发了 need_login 通知', [n[0] for n in notes], ['task.account.need_login'])
+    check('本设备已停止', w.stopped(), True)
+
+    print('=== 6. on_login_page=continue → 不停设备（只记一句）===')
+    notes.clear()
+    w = gt.GenericStepsWorker("F6", {})
+    w._vars['target_name'] = '小王'
+    d = StubD(cur='小李', login=True)
+    p = dict(PARAMS, on_login_page='continue')
+    check('返回 False', w._exec_switch_account(d, p), False)
+    check('还是发了 need_login 通知', [n[0] for n in notes], ['task.account.need_login'])
+    check('设备没被停', w.stopped(), False)
+
+    print('=== 7. 进账号列表的选择器没配 → 明确报错、不乱点 ===')
+    notes.clear()
+    w = gt.GenericStepsWorker("F7", {})
+    w._vars['target_name'] = '小王'
+    d = StubD(cur='小李')
+    p = dict(PARAMS, switch_selector_value='')
+    check('返回 False', w._exec_switch_account(d, p), False)
+    check('没点任何东西', d.clicked, [])
+    check('没瞎发通知（这是配置问题，不是切号失败）', notes, [])
+
+    print('=== 8. 没给目标名字 → 跳过 ===')
+    w = gt.GenericStepsWorker("F8", {})
+    d = StubD(cur='小李')
+    check('返回 False', w._exec_switch_account(d, PARAMS), False)
+    check('没点任何东西', d.clicked, [])
+
+    print('=== 9. verify=False → 点了就算过（不回读）===')
+    w = gt.GenericStepsWorker("F9", {})
+    w._vars['target_name'] = '小王'
+    d = StubD(cur='小李')
+    d.switch_ok = False
+    check('返回 True', w._exec_switch_account(d, dict(PARAMS, verify=False)), True)
+finally:
+    gt.notifier.notify = orig_notify
+
+print()
+if fails:
+    print('❌ 失败 %d 项：%s' % (len(fails), ' / '.join(fails)))
+    sys.exit(1)
+print('✅ 全部通过（没连任何真机）')

scripts/tests/test_upload_name.py

@@ -0,0 +1,146 @@
+# -*- coding: utf-8 -*-
+"""P1 集成测试：按名字上传/配标题走通（**临时 SQLite + 临时视频目录**，不碰真实数据）。"""
+import io
+import os
+import shutil
+import sys
+import tempfile
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+
+TMP = tempfile.mkdtemp(prefix='ac_p1_')
+os.environ['DATABASE_URL'] = 'sqlite:///' + os.path.join(TMP, 'ac.db').replace('\\', '/')
+os.environ['DATA_VIDEO_DIR'] = os.path.join(TMP, 'videos')
+os.environ['DEPLOY_ENV'] = 'dev'
+os.environ['DB_ALLOW_SQLITE_FALLBACK'] = '1'
+
+# 仓库根 = scripts/tests/ 往上三级（不写死绝对路径，换机器也能跑）
+_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, _ROOT)
+os.chdir(_ROOT)
+
+from flask import Flask                                              # noqa: E402
+from sqlalchemy import inspect                                       # noqa: E402
+from core import db_config, models                                   # noqa: E402
+from core import video_plan as vp                                    # noqa: E402
+
+fails = []
+
+
+def check(label, got, want):
+    ok = got == want
+    if not ok:
+        fails.append(label)
+    print(('  ✅ ' if ok else '  ❌ ') + label + ('' if ok else '\n       得到 %r\n       期望 %r' % (got, want)))
+
+
+def ok(label, cond, detail=''):
+    if not cond:
+        fails.append(label)
+    print(('  ✅ ' if cond else '  ❌ ') + label + ('' if cond else '  ' + str(detail)))
+
+
+class FakeFile:
+    """够用的 FileStorage 替身：只用到 .filename / .stream。"""
+
+    def __init__(self, filename, data):
+        self.filename = filename
+        self.stream = io.BytesIO(data)
+
+
+app = Flask("t")
+uri = db_config.build_db_uri()
+print('测试库:', uri)
+app.config["SQLALCHEMY_DATABASE_URI"] = uri
+app.config["SQLALCHEMY_ENGINE_OPTIONS"] = db_config.engine_options(uri)
+app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
+models.db.init_app(app)
+with app.app_context():
+    models.db.create_all()
+    models._ensure_plain_indexes()        # 生产启动路径里的那一步（老库补索引）
+vp.init_app(app)
+
+with app.app_context():
+    print('=== 0. 前提：台账一张空表也不依赖 ===')
+    check('device_account 里 0 行（上传完全不查台账）', models.DeviceAccount.query.count(), 0)
+    check('video_plan 里 0 行', models.VideoPlan.query.count(), 0)
+
+    print('=== 1. 上传：名字_日期_编号 ===')
+    r = vp.upload_video(FakeFile('小王_20260912_1.mp4', b'A' * 500))
+    ok('上传成功', r.get('ok') is True, r)
+    p = r['plan']
+    check('昵称 = 文件名里的名字', p['nickname'], '小王')
+    check('手机号留空（不再写台账快照）', p['phone'], '')
+    check('设备号留空', p['device_name'], '')
+    check('发布日期', p['release_date'], '2026-09-12')
+    check('编号', p['seq'], 1)
+    check('编号不是自动的', p['seq_auto'], False)
+    check('状态 = 待标题', p['status'], 'pending')
+
+    print('=== 2. 幂等：同一份内容重传 ===')
+    r2 = vp.upload_video(FakeFile('小王_20260912_1.mp4', b'A' * 500))
+    check('跳过', r2.get('action'), 'skip')
+
+    print('=== 3. 同槽位换内容：先拒收、replace 才行 ===')
+    r3 = vp.upload_video(FakeFile('小王_20260912_1.mp4', b'B' * 600))
+    ok('拒收', r3.get('ok') is False and '已有视频' in (r3.get('error') or ''), r3)
+    r4 = vp.upload_video(FakeFile('小王_20260912_1.mp4', b'B' * 600), replace=True)
+    check('覆盖成功', r4.get('action'), 'replace')
+    check('还是 1 行', models.VideoPlan.query.count(), 1)
+
+    print('=== 4. 不带编号 → 自动排到空位 ===')
+    r5 = vp.upload_video(FakeFile('小王_20260912.mp4', b'C' * 700))
+    check('自动编号 = 2', r5['plan']['seq'], 2)
+    check('标记为自动', r5['plan']['seq_auto'], True)
+
+    print('=== 5. 老格式（手机号）被拒 + 说清怎么改 ===')
+    r6 = vp.upload_video(FakeFile('13382508423_20261011_01.mp4', b'D' * 700))
+    ok('拒收且提示是手机号', r6.get('ok') is False and '手机号' in (r6.get('error') or ''), r6)
+    check('库里还是 2 行', models.VideoPlan.query.count(), 2)
+
+    print('=== 6. 配标题（`标题 || 正文_名字_日期_编号`）===')
+    t1 = vp.import_titles('聚划算 || 今天全场五折，点进来看看_小王_20260912')
+    check('配到 1 条', t1['counts']['attached'], 1)
+    row1 = models.VideoPlan.query.filter_by(nickname='小王', release_date='2026-09-12',
+                                            seq=1).first()
+    check('标题落库', row1.title, '聚划算')
+    check('正文落库', row1.body, '今天全场五折，点进来看看')
+    check('状态自动切到待发布', row1.status, 'ready')
+    check('返回体里键是 name', t1['rows'][0]['name'], '小王')
+
+    t2 = vp.import_titles('第二个 || 正文二_小王_20260912_2')
+    check('按编号精确配对', t2['counts']['attached'], 1)
+    row2 = models.VideoPlan.query.filter_by(nickname='小王', release_date='2026-09-12',
+                                            seq=2).first()
+    check('第 2 条标题', row2.title, '第二个')
+
+    t3 = vp.import_titles('这条没有主_不存在的名字_20260912')
+    check('认不出名字 → 拒收', (t3['counts']['rejected'], t3['rows'][0]['error']),
+          (1, '该名字 2026-09-12 没有待配标题的视频（请先上传视频）'))
+
+    # 带编号重配同一条 → 认出来是"配过了"，跳过（幂等）
+    t4 = vp.import_titles('聚划算 || 今天全场五折，点进来看看_小王_20260912_1')
+    check('带编号重配同一条 → 跳过', t4['counts']['skipped'], 1)
+    # 不带编号：它只会找"还没有标题的行"，两行都配过 → 拒收（既有语义，文案说清了原因）
+    t5 = vp.import_titles('聚划算 || 今天全场五折，点进来看看_小王_20260912')
+    check('不带编号且两行都有标题 → 拒收', (t5['counts']['rejected'], t5['rows'][0]['error']),
+          (1, '该名字 2026-09-12 没有待配标题的视频（请先上传视频）'))
+
+    print('=== 7. 老命名空间不受影响：按名字查重/取槽位 ===')
+    check('taken_slots 按名字', vp.taken_slots('小王', '2026-09-12'), {1, 2})
+    check('别的名字是空的', vp.taken_slots('小李', '2026-09-12'), set())
+
+    print('=== 8. 索引补建 ===')
+    idx = {i['name'] for i in inspect(models.db.engine).get_indexes('video_plan')}
+    ok('ix_video_plan_name_date 已建', 'ix_video_plan_name_date' in idx, sorted(idx))
+
+    print('=== 9. 素材落盘 ===')
+    files = os.listdir(os.path.join(TMP, 'videos', '2026-10'))
+    check('落盘 2 个文件（覆盖后旧文件已删）', len(files), 2)
+
+print()
+shutil.rmtree(TMP, ignore_errors=True)
+if fails:
+    print('❌ 失败 %d 项：%s' % (len(fails), ' / '.join(fails)))
+    sys.exit(1)
+print('✅ 全部通过（临时库已清理）')

static/admin/admin.js

@@ -91,22 +91,85 @@ async function deleteGroup(name){
 }
 
 // ================== Tab 4: 日志 ==================
+// 条件（文件/关键字/级别/时间）→ /api/logs（结构化行）；下载走 /api/logs/download
+function _logParams(){
+  const v=id=>document.getElementById(id);
+  const p=new URLSearchParams();
+  p.set('file', v('log-file').value||'');
+  p.set('lines', v('log-lines').value);
+  const q=v('log-q').value.trim();       if(q)p.set('q',q);
+  const lv=v('log-level').value;         if(lv)p.set('level',lv);
+  const since=v('log-since').value;      if(since)p.set('since',since);
+  const until=v('log-until').value;      if(until)p.set('until',until);
+  return p;
+}
+
+// 文件下拉由接口返回的清单渲染（写死的选项会漏掉新增模块，如 notify.log）
+function _renderLogFiles(files,current){
+  const sel=document.getElementById('log-file');
+  const sig=(files||[]).map(f=>f.name).join(',');
+  if(sel.dataset.sig!==sig){        // 只在清单变化时重建，避免打断当前选择
+    sel.dataset.sig=sig;
+    sel.innerHTML=(files||[]).map(f=>
+      '<option value="'+esc(f.name)+'">'+esc(f.label)+'</option>').join('');
+  }
+  if(current)sel.value=current;
+}
+
 async function loadLogs(){
-  const file=document.getElementById('log-file').value;
-  const lines=document.getElementById('log-lines').value;
-  const r=await apiGet('/api/logs?file='+encodeURIComponent(file)+'&lines='+lines);
-  if(!r||!r.ok)return;
-  const content=r.content||'';
-  // 简单着色
-  const colored=esc(content)
-    .replace(/\[ERROR\]/g,'<span class="log-err">[ERROR]</span>')
-    .replace(/\[WARNING\]/g,'<span class="log-warn">[WARNING]</span>')
-    .replace(/\[INFO\]/g,'<span class="log-info">[INFO]</span>');
-  document.getElementById('log-content').innerHTML=colored||'<span class="text-muted">（空）</span>';
-  document.getElementById('log-hint').textContent=file+' · '+content.split('\n').length+' 行';
-  // 自动滚动到底部
   const el=document.getElementById('log-content');
-  el.scrollTop=el.scrollHeight;
+  if(!el)return;
+  // 用户正往上翻看历史时不要被自动刷新拽回底部
+  const atBottom=el.scrollHeight-el.scrollTop-el.clientHeight<40;
+  const r=await apiGet('/api/logs?'+_logParams().toString());
+  if(!r)return;
+  _renderLogFiles(r.files,r.file);
+  const hint=document.getElementById('log-hint');
+  if(!r.ok){
+    el.innerHTML='<span class="text-muted">'+esc(r.error||'读取失败')+'</span>';
+    hint.textContent='';
+    return;
+  }
+  const rows=r.rows||[], kw=document.getElementById('log-q').value.trim();
+  el.innerHTML=rows.length
+    ? rows.map(row=>_logRowHtml(row,kw)).join('')
+    : '<span class="text-muted">（无匹配行）</span>';
+  let text=r.file+' · 命中 '+r.matched+' 行'
+    +(rows.length<r.matched?'（显示最近 '+rows.length+' 行）':'')
+    +' · 已扫描 '+r.scanned+' 行';
+  if(r.truncated)text+=' · 更早的命中已省略：缩小时间范围或加关键字';
+  hint.textContent=text;
+  if(atBottom)el.scrollTop=el.scrollHeight;
+}
+
+function _logRowHtml(r,kw){
+  const lvl=(r.level||'').toUpperCase();
+  const cls=lvl==='ERROR'||lvl==='CRITICAL'?'log-err'
+           :lvl==='WARNING'?'log-warn':'log-info';
+  // 续行（traceback 缩进行）没有前缀，只缩进显示消息体
+  const head=r.cont?'':esc(r.ts)+' <span class="'+cls+'">['+esc(lvl)+']</span> ['
+                    +esc(r.module)+'] ';
+  return '<div class="log-row'+(r.cont?' log-cont':'')+'">'+head+_logHl(r.msg,kw)+'</div>';
+}
+
+// 关键字高亮：**先转义再匹配**——反过来的话消息里的 < > 会先被吃成实体
+function _logHl(text,kw){
+  const safe=esc(text||'');
+  if(!kw)return safe;
+  const k=esc(kw);
+  if(!k)return safe;
+  const re=new RegExp(k.replace(/[.*+?^${}()|[\]\\]/g,'\\$&'),'gi');
+  return safe.replace(re,m=>'<span class="log-hit">'+m+'</span>');
+}
+
+function downloadLogs(){
+  window.location='/api/logs/download?'+_logParams().toString();
+}
+
+function resetLogFilters(){
+  ['log-q','log-since','log-until'].forEach(id=>{document.getElementById(id).value='';});
+  document.getElementById('log-level').value='';
+  loadLogs();
 }
 
 function toggleLogAuto(){

static/admin/base.js

@@ -102,22 +102,34 @@ function showTab(name){
   if(_monitorTimer){clearInterval(_monitorTimer);_monitorTimer=null;}
   if(_logTimer){clearInterval(_logTimer);_logTimer=null;}
   if(_discoveryTimer){clearInterval(_discoveryTimer);_discoveryTimer=null;}
+  if(typeof _rpTimer!=='undefined'&&_rpTimer){clearInterval(_rpTimer);_rpTimer=null;}
   // 按需加载数据
   if(name==='monitor'){loadMonitor();_monitorTimer=setInterval(loadMonitor,5000);}
-  if(name==='tasks'){showSubTab('tasks',_activeSubs.tasks);loadTasks();loadCustomActions();}
+  if(name==='tasks'){showSubTab('tasks',_activeSubs.tasks);loadTasks();loadCustomActions();
+    if(typeof loadStepDefaults==='function')loadStepDefaults();}
   if(name==='tools'){showSubTab('tools',_activeSubs.tools);loadToolsDevices();loadAdbDevices();loadTailscaleDevices();loadApks();}
-  if(name==='logs'){loadLogs();if(document.getElementById('log-auto').checked)_logTimer=setInterval(loadLogs,3000);}
+  if(name==='logs'){
+    showSubTab('logs', _activeSubs.logs||'files');   // 文件日志 / 步骤明细
+    if((_activeSubs.logs||'files')==='files'
+       && document.getElementById('log-auto').checked)_logTimer=setInterval(loadLogs,3000);
+  }
   if(name==='agent'){
     showSubTab('agent', _activeSubs.agent||'chat');   // 聊天 / AI 建任务
     if(typeof initAgentChat==='function') initAgentChat();
   }
+  // 发布计划（原「发布计划」子分栏，账号台账下线后升为一级页签）
+  if(name==='plan'){
+    if(typeof loadReleasePlan==='function')loadReleasePlan();
+    if(typeof loadReleaseTasks==='function')loadReleaseTasks();
+  }
   if(name==='users')loadUsers();
   if(name==='system'){showSubTab('system',_activeSubs.system||'backup');}
 }
 
 // ================== 页内子分栏（任务/工具 通用） ==================
 // 每个带子分栏的 Tab 记住上次选中的子分栏，切走再切回来保持原位
-let _activeSubs = {tasks: 'plan', tools: 'clipboard', system: 'backup', agent: 'chat'};
+let _activeSubs = {tasks: 'plan', tools: 'clipboard', system: 'backup', agent: 'chat',
+                   logs: 'files'};
 let _discoveryTimer = null;   // 设备自动发现 10s 轮询（仅 devpool 子分栏激活时）
 
 function showSubTab(tabId, name){
@@ -127,6 +139,10 @@ function showSubTab(tabId, name){
   tab.querySelectorAll('.sub-panel').forEach(p=>p.classList.toggle('active', p.id===tabId+'-sub-'+name));
   if(tabId==='agent' && name==='taskgen' && typeof initTaskGen==='function') initTaskGen();
   if(tabId==='system' && name==='notify' && typeof loadNotifyPanel==='function') loadNotifyPanel();
+  if(tabId==='logs' && name==='files' && typeof loadLogs==='function') loadLogs();
+  if(tabId==='logs' && name==='steps' && typeof loadStepLogs==='function') loadStepLogs(true);
+  if(tabId==='tasks' && name==='actioncfg' && typeof loadActionConfig==='function') loadActionConfig();
+  if(tabId==='tasks' && name==='dedup' && typeof loadDedup==='function') loadDedup();
   if(name==='groups' && typeof loadGroups==='function') loadGroups();
   if(name==='apks' && typeof loadAgentStore==='function') loadAgentStore();
   if(name==='devpool' && typeof loadDevPool==='function'){

static/admin/dedup.js

@@ -0,0 +1,85 @@
+// 去重记录（「任务 → 去重记录」页）
+// 账本在 done_mark 表（跨设备幂等），后端见 core/dedup.py + web/tasks_api.py 的三个接口。
+// 这一页的价值：**"谁做过了、还差谁"看得见**——用户原来不知道任务什么时候跑完，
+// 只能一直重跑，而重跑本身又在制造重复。
+var _dedupMarks = [];
+
+function loadDedup(){
+  var sel=document.getElementById('dedup-job');
+  if(!sel)return;
+  var jobId=sel.value||'';
+  apiGet('/api/done_marks?limit=300'+(jobId?('&job='+encodeURIComponent(jobId)):'')).then(function(r){
+    if(!r||!r.ok){
+      var tb=document.getElementById('tb-dedup');
+      if(tb)tb.innerHTML='<tr><td colspan="6" class="empty">读取失败：'+esc((r&&r.error)||'')+'</td></tr>';
+      return;
+    }
+    _dedupMarks=r.marks||[];
+    renderDedupJobs(r.job_id||'');
+    renderDedup(r.stats||{});
+  });
+}
+
+// 任务下拉：用已加载的任务列表填（含"全部任务"）；保持当前选中项
+// `_jobsData` 是全局任务列表（monitor.js 声明、tasks.js 的 loadTasks 填充）
+function renderDedupJobs(current){
+  var sel=document.getElementById('dedup-job');
+  if(!sel)return;
+  var jobs=_jobsData||[];
+  if(!jobs.length)return;          // 任务列表还没加载就先留着旧选项
+  var cur=current!==undefined?current:(sel.value||'');
+  var html='<option value="">全部任务</option>';
+  jobs.forEach(function(j){
+    html+='<option value="'+esc(j.id)+'">'+esc(j.name||j.id)+'</option>';
+  });
+  sel.innerHTML=html;
+  sel.value=cur;
+}
+
+function renderDedup(stats){
+  var tb=document.getElementById('tb-dedup');
+  if(!tb)return;
+  var st=document.getElementById('dedup-stats');
+  if(st){
+    st.textContent='共 '+stats.total+' 条 · 涉及 '+stats.devices+' 台设备 / '
+      +stats.identities+' 个身份值｜今天已做 '+stats.today_devices+' 台 · '
+      +stats.today_identities+' 个身份值';
+  }
+  if(!_dedupMarks.length){
+    tb.innerHTML='<tr><td colspan="6" class="empty">暂无记录（任务里用了「去重」条件 + 「记为已做」并成功做完之后才会有）</td></tr>';
+    return;
+  }
+  var KIND={day:'每天一次',all:'只做一次',hours:'按小时'};
+  tb.innerHTML=_dedupMarks.map(function(m){
+    var who=m.device_name?('<strong>'+esc(m.device_name)+'</strong><br>'
+              +'<span style="font-size:11px;color:#94a3b8;font-family:var(--mono)">'+esc(m.serial)+'</span>')
+             :('<span style="font-family:var(--mono)">'+esc(m.serial||'-')+'</span>');
+    return '<tr><td style="font-size:12px">'+esc(m.created_at)+'</td>'+
+      '<td>'+who+'</td>'+
+      '<td style="font-family:var(--mono)">'+esc(m.identity||'-')+'</td>'+
+      '<td><span class="label label-default">'+esc(KIND[m.kind]||m.kind)+'</span></td>'+
+      '<td>'+esc(m.job_name||m.job_id||'-')+'</td>'+
+      '<td><button class="btn btn-xs btn-danger" data-id="'+m.id+'" '+
+        'onclick="deleteDedupMark(this.dataset.id)" data-perm="tasks" '+
+        'title="删掉这条 → 这台设备/这个身份下次会重新执行">删除</button></td></tr>';
+  }).join('');
+}
+
+function deleteDedupMark(id){
+  if(!confirm('删掉这条去重记录？\n\n删掉之后，这台设备/这个身份下次跑该任务时会重新执行一遍。'))return;
+  apiPost('/api/done_marks/delete',{id:id}).then(function(r){
+    if(r&&r.ok){showToast(r.msg||'已删除','success');loadDedup();}
+    else showToast('删除失败: '+((r&&r.error)||''),'error');
+  });
+}
+
+function clearJobDedup(){
+  var sel=document.getElementById('dedup-job');
+  var jobId=sel?sel.value:'';
+  if(!jobId){showToast('先在左边选一个任务（"清空本任务记录"要指定任务）','error');return;}
+  if(!confirm('清空这个任务的全部去重记录？\n\n清空之后，所有设备/身份下次跑该任务都会重新执行一遍。'))return;
+  apiPost('/api/done_marks/clear',{job:jobId}).then(function(r){
+    if(r&&r.ok){showToast(r.msg||'已清空','success');loadDedup();}
+    else showToast('清空失败: '+((r&&r.error)||''),'error');
+  });
+}

static/admin/editor.js

@@ -5,9 +5,9 @@ var STEP_LIB=[
   {type:'click',label:'点击元素',icon:'✦',cat:'interact',params:{selector_type:'xpath',selector_value:'',wait_timeout:2}},
   {type:'click_xy',label:'点击坐标',icon:'🎯',cat:'interact',params:{x:50,y:50}},
   {type:'long_click',label:'长按元素',icon:'👆',cat:'interact',params:{selector_type:'xpath',selector_value:'',duration:1.0,wait_timeout:2}},
-  {type:'swipe',label:'滑动',icon:'↕',cat:'interact',params:{direction:'up',duration_min:0.25,duration_max:0.50}},
-  {type:'swipe_until',label:'滑动直到元素',icon:'🔍',cat:'interact',params:{selector_type:'xpath',selector_value:'',direction:'up',max_swipes:8,click_when_found:true}},
-  {type:'input_text',label:'输入文字',icon:'⌨',cat:'interact',params:{mode:'random',texts:'你好\n有趣\n支持',fixed_text:'',clear_first:true}},
+  {type:'swipe',label:'滑动',icon:'↕',cat:'interact',params:{direction:'up',duration_min:0.25,duration_max:0.50,distance_ratio:0.6,jitter:0.15,humanize:true}},
+  {type:'swipe_until',label:'滑动直到元素',icon:'🔍',cat:'interact',params:{selector_type:'xpath',selector_value:'',direction:'up',max_swipes:8,click_when_found:true,duration_min:0.25,duration_max:0.50,distance_ratio:0.6,jitter:0.15,humanize:true}},
+  {type:'input_text',label:'输入文字',icon:'⌨',cat:'interact',params:{mode:'random',texts:'你好\n有趣\n支持',fixed_text:'',clear_first:true,text_source:'manual',release_topics:''}},
   {type:'clipboard',label:'剪贴板注入',icon:'📋',cat:'interact',params:{text:'',paste:true}},
   {type:'key_event',label:'按键',icon:'⌨️',cat:'interact',params:{key:'back'}},
   {type:'open_app',label:'打开App',icon:'▶',cat:'screen',params:{package:'',wait_home:false,home_feature:''}},
@@ -19,8 +19,25 @@ var STEP_LIB=[
   {type:'wait_el',label:'等待元素',icon:'⏳',cat:'flow',params:{selector_type:'xpath',selector_value:'',timeout:10}},
   {type:'loop',label:'循环块',icon:'↻',cat:'flow',params:{loop_mode:'rounds',max_iterations:10,loop_duration:600,children:[]}},
   {type:'group',label:'动作组',icon:'📦',cat:'flow',params:{children:[]}},
-  {type:'if_el',label:'条件判断',icon:'❓',cat:'flow',params:{selector_type:'xpath',selector_value:'',timeout:3,ocr_click:false,then:[],else:[]}}
+  {type:'if_el',label:'条件判断',icon:'❓',cat:'flow',params:{selector_type:'xpath',selector_value:'',timeout:3,ocr_click:false,cmp_op:'',cmp_value:'',cmp_source:'',cmp_group:'',ident_type:'text',ident_value:'',then:[],else:[]}},
+  {type:'mark_done',label:'记为已做',icon:'✅',cat:'flow',params:{selector_type:'text',selector_value:''}},
+  {type:'read_account_name',label:'读取本机账号名字',icon:'🏷',cat:'flow',params:{selector_type:'xpath',selector_value:'',timeout:8,on_missing:'fail'}},
+  {type:'expect_el',label:'校验页面',icon:'🔎',cat:'flow',params:{selector_type:'xpath',selector_value:'',timeout:10,on_missing:'skip_rest',what:''}},
+  {type:'read_text',label:'读取文字',icon:'📖',cat:'flow',params:{selector_type:'xpath',selector_value:'',timeout:8,var:'account_name',clean:'account',on_missing:'skip'}},
+  {type:'switch_account',label:'切换账号',icon:'🔁',cat:'flow',params:{target:'var:target_name',target_value:'',switch_selector_type:'xpath',switch_selector_value:'',name_selector_type:'',name_selector_value:'',me_selector_type:'descriptionContains',me_selector_value:'我',timeout:8,wait_after:15,verify:true,max_attempts:2,on_login_page:'stop'}},
+  {type:'foreach_account',label:'循环本机待发的号',icon:'🔂',cat:'flow',params:{date_source:'today',fixed_date:'',retry_failed:true,max_accounts:0,children:[]}},
+  {type:'notify',label:'发通知',icon:'🔔',cat:'flow',params:{title:'',message:'',level:'info'}},
+  {type:'stop_self',label:'停止本设备',icon:'⛔',cat:'flow',params:{reason:''}},
+  {type:'gesture',label:'录制手势',icon:'⏺',cat:'interact',params:{points:[],speed:1.0}}
 ];
+// 步骤默认值（「任务 → 动作配置」页配置，见 core/step_defaults.py）；新建步骤时预填
+let _stepDefaults = null;
+// 去重有效期选了「按小时」才显示小时数输入框
+function _toggleDedupHours(){
+  var sel=document.getElementById('f-dedup_reset');
+  var wrap=document.getElementById('f-dedup_hours_wrap');
+  if(sel&&wrap)wrap.style.display=(sel.value==='hours')?'inline-flex':'none';
+}
 var STEP_LIB_CATS=[['interact','交互操作'],['screen','屏幕与App'],['flow','流程控制']];
 var _customActions=[]; // 后端加载的自定义动作
 var _stepIdCounter=0;
@@ -45,20 +62,46 @@ function _stripIds(steps){
 function _findLib(type){return STEP_LIB.find(function(s){return s.type===type;});}
 // 选择器组件（类型下拉 + 值输入 + 抓取元素 + 测试按钮），click/long_click/swipe_until/wait_el/if_el 复用
 // withOcr=true 时额外提供 OCR识别 选项（图片/画布里的文字，仅条件判断支持）
-function _selRowHtml(p, extra, withOcr){
-  var types=withOcr?['xpath','description','text','resourceId','descriptionContains','className','ocr']:
-    ['xpath','description','text','resourceId','descriptionContains','className'];
-  var labels={xpath:'xpath',description:'description',text:'text',resourceId:'resourceId',
-    descriptionContains:'descriptionContains',className:'className',ocr:'OCR识别'};
+// withDedup=true 时额外提供「去重」条件类型（身份做过了吗，见 core/dedup.py）
+// keys 可换字段名（默认 selector_type/selector_value）——「去重」的身份元素用
+// ident_type/ident_value，好让同一个条件里既能有主选择器又能有身份元素
+function _selRowHtml(p, extra, withOcr, withDedup, keys){
+  keys=keys||{};
+  var kType=keys.type||'selector_type', kVal=keys.value||'selector_value';
+  var typeList=['xpath','description','text','textContains','resourceId','descriptionContains','className'];
+  // withOcr（条件判断用）额外提供"屏幕状态 / 前台App / 去重"三类非元素条件
+  var types=withOcr?typeList.concat(['ocr','screen','foreground']):typeList.slice();
+  if(withDedup)types.push('dedup');
+  var labels={xpath:'xpath',description:'description',text:'text',textContains:'textContains（文本包含）',
+    resourceId:'resourceId',
+    descriptionContains:'descriptionContains',className:'className',ocr:'OCR识别',
+    screen:'屏幕状态',foreground:'前台App是',dedup:'去重（这个身份做过了吗）'};
   var opts=types.map(function(d){
-    return '<option value="'+d+'"'+(p.selector_type===d?' selected':'')+'>'+labels[d]+'</option>';}).join('');
-  var toggle=withOcr?' onchange="_stepEditor._toggleOcrMode(this)"':'';
+    return '<option value="'+d+'"'+(p[kType]===d?' selected':'')+'>'+labels[d]+'</option>';}).join('');
+  var toggle=withOcr?' onchange="_stepEditor._condTypeChanged(this)"':'';
   var pick=_can('devices')?'<button class="btn btn-xs btn-pick" onclick="_stepEditor.openPicker(this)">抓取元素</button>':'';
   var test=_can('devices')?'<button class="btn btn-xs" onclick="_stepEditor._testStep(this)" title="在设备上试执行本步骤，验证选择器是否命中">测试</button>':'';
-  return '<div class="form-row"><div class="form-group"><label>选择器类型</label><select class="form-control" data-key="selector_type"'+toggle+'>'+opts+'</select></div>'+
-    '<div class="form-group" style="grid-column:span 2"><label>选择器值</label><div class="sel-picker">'+
-    '<input type="text" class="form-control" data-key="selector_value" value="'+esc(p.selector_value||'')+'" placeholder="如 点赞">'+pick+test+
-    '</div></div></div>'+(extra||'');
+  // 变量按钮：选择器值里可以直接写 {本次要发的名字} —— 点它弹出来选，省得记写法
+  var varbtn='<button class="btn btn-xs" onclick="_stepEditor.insertVar(this)" title="把变量插进选择器值：{本次要发的名字}=本轮要发的那个号，{本机账号名字}=读到的本机账号">{变量}</button>';
+  var isScreen=p[kType]==='screen', isFg=p[kType]==='foreground';
+  var valLabel=isScreen?'屏幕状态':(isFg?'前台包名':'选择器值');
+  var valHtml;
+  if(isScreen){
+    valHtml='<select class="form-control" data-key="'+kVal+'" style="max-width:140px">'+
+      '<option value="off"'+(p[kVal]!=='on'?' selected':'')+'>熄屏时就命中</option>'+
+      '<option value="on"'+(p[kVal]==='on'?' selected':'')+'>亮屏时就命中</option></select>';
+  }else{
+    valHtml='<input type="text" class="form-control" data-key="'+kVal+'" value="'+esc(p[kVal]||'')+
+      '" placeholder="'+(isFg?'如 com.ss.android.ugc.aweme':'如 点赞；可用 {本次要发的名字} / {本机账号名字}')+'">'+(isFg?'':pick+test+varbtn);
+  }
+  var head='<div class="form-group"'+(keys.hideValue?' style="grid-column:span 3"':'')+'>'+
+    '<label>选择器类型</label><select class="form-control" data-key="'+kType+'"'+toggle+'>'+opts+'</select></div>';
+  // hideValue：「去重」条件不需要 selector_value（身份元素在 ident_value 里），
+  // 与其显示一个没人用的输入框，不如只留类型下拉
+  if(keys.hideValue)return '<div class="form-row">'+head+'</div>'+(extra||'');
+  return '<div class="form-row">'+head+
+    '<div class="form-group" style="grid-column:span 2"><label>'+valLabel+'</label><div class="sel-picker">'+
+    valHtml+'</div></div></div>'+(extra||'');
 }
 
 // 加载自定义动作库
@@ -69,11 +112,27 @@ function _loadCustomActions(){
   }).catch(function(){});
 }
 
+
+// 「拟人」开关 + 抖动幅度（滑动类步骤共用；见 core/humanize.py）
+function _humanizeChkHtml(p){
+  return '<div class="form-row"><div class="form-group form-check">'
+    +'<input type="checkbox" data-key="humanize" '+(p.humanize!==false?'checked':'')+'>'
+    +'<label>拟人轨迹（弧线）</label></div>'
+    +'<div class="form-group"><label>抖动幅度</label><input type="number" class="form-control" data-key="jitter" value="'
+    +(p.jitter!=null?p.jitter:0.15)+'" step="0.05" min="0" max="0.4"></div></div>';
+}
+function _humanizeRowHtml(p,extra){
+  return extra+_humanizeChkHtml(p)
+    +'<div class="help">拟人：滑动走弧线，起止点/幅度/时长每次都抖一点，并按本设备的手速与幅度偏好执行'
+    +'（每台设备风格稳定不同，批量跑时不像同步机器人）。关掉=还原成正中直线；'
+    +'抖动填 0=位置/幅度不抖（时长仍在你填的范围内随机）</div>';
+}
+
 var _stepEditor={
   _steps:[],
   _selected:[],
   _dragSuppressClick:false,
-  init:function(steps,maxDuration,draftKey,canvasId,libId){
+  init:function(steps,maxDuration,draftKey,canvasId,libId,taskExtra){
     this._draftKey=draftKey||'new';
     this._selected=[];
     this._updatePackBtns();
@@ -114,6 +173,25 @@ var _stepEditor={
       md.innerHTML='运行时长上限(秒,0=不限) <input type="number" id="f-max_duration" value="'+(maxDuration||0)+'" min="0" style="width:70px;padding:2px 6px;border:1px solid var(--border);border-radius:4px;font-size:12px">';
       head.appendChild(md);
     }
+    // 去重有效期（任务级）：**只在这一处配**——「条件判断→去重」和「记为已做」两处
+    // 各填一份的话，填不一致就会算出两个不同的 key、去重静默失效，所以强制共用。
+    var drHost=document.querySelector('#step-editor .se-head');
+    if(drHost&&!document.getElementById('f-dedup_reset')){
+      var ex=taskExtra||{};
+      var dr=document.createElement('span');
+      dr.style.cssText='font-size:11px;display:flex;align-items:center;gap:4px';
+      var selStyle='padding:2px 6px;border:1px solid var(--border);border-radius:4px;font-size:12px';
+      dr.innerHTML='去重有效期 <select id="f-dedup_reset" style="'+selStyle+'">'+
+        '<option value="day">每天一次</option>'+
+        '<option value="all">只做一次</option>'+
+        '<option value="hours">按小时</option></select>'+
+        '<span id="f-dedup_hours_wrap" style="display:none;align-items:center;gap:3px">每 '+
+        '<input type="number" id="f-dedup_hours" value="'+(ex.dedup_hours||6)+'" min="1" max="168" style="width:52px;'+selStyle+'"> 小时</span>';
+      drHost.appendChild(dr);
+      document.getElementById('f-dedup_reset').value=ex.dedup_reset||'day';
+      _toggleDedupHours();
+      document.getElementById('f-dedup_reset').addEventListener('change',_toggleDedupHours);
+    }
   },
   _ensureIds:function(steps){
     var self=this;
@@ -195,7 +273,7 @@ var _stepEditor={
     var self=this;
     var lib=_findLib(step.type)||{icon:'?',label:step.type};
     var card=document.createElement('div');
-    card.className='step-card'+(step.type==='loop'?' loop-block':'')+(step.type==='group'?' group-block':'')+(step.type==='if_el'?' if-block':'');
+    card.className='step-card'+(step.type==='loop'?' loop-block':'')+(step.type==='group'?' group-block':'')+(step.type==='if_el'?' if-block':'')+(step.type==='foreach_account'?' loop-block':'');
     card.draggable=true;
     card.dataset.idx=idx;
     card.dataset.stepId=step.id||'';
@@ -243,8 +321,9 @@ var _stepEditor={
       card.classList.remove('drag-over');
       self._handleDrop(e,parentArr,idx);
     });
-    // loop/group 子步骤
-    if(step.type==='loop'||step.type==='group'){
+    // loop/group/foreach_account 子步骤（**容器不列进来就看不到里面** —— 加新容器类型时
+    // 记得同时改这里、card.className 和 _renderParams 三处）
+    if(step.type==='loop'||step.type==='group'||step.type==='foreach_account'){
       if(step.params&&step.params.children){
         var childWrap=document.createElement('div');
         childWrap.className='step-children';
@@ -299,8 +378,16 @@ var _stepEditor={
         ['up','down','left','right'].map(function(d){return '<option value="'+d+'"'+(p.direction===d?' selected':'')+'>'+d+'</option>';}).join('')+'</select></div>';
       h+='<div class="form-group"><label>最短时长(秒)</label><input type="number" class="form-control" data-key="duration_min" value="'+(p.duration_min||0.25)+'" step="0.05" min="0.05"></div>';
       h+='<div class="form-group"><label>最长时长(秒)</label><input type="number" class="form-control" data-key="duration_max" value="'+(p.duration_max||0.50)+'" step="0.05" min="0.05"></div></div>';
+      h+=_humanizeRowHtml(p,'<div class="form-group"><label>幅度(屏占比)</label><input type="number" class="form-control" data-key="distance_ratio" value="'+(p.distance_ratio!=null?p.distance_ratio:0.6)+'" step="0.05" min="0.1" max="0.9"></div>');
+      h+='<div class="help">想要"照我划的那一下原样重放"，请用操作库里的《录制手势》步骤——那个是纯轨迹回放，不套这里的参数</div>';
     }else if(step.type==='click'){
-      h+=_selRowHtml(p,'<div class="form-group"><label>等待超时(秒)</label><input type="number" class="form-control" data-key="wait_timeout" value="'+(p.wait_timeout||2)+'" step="0.5" min="0.5"></div>');
+      h+=_selRowHtml(p,'<div class="form-group"><label>等待超时(秒)</label><input type="number" class="form-control" data-key="wait_timeout" value="'+(p.wait_timeout||2)+'" step="0.5" min="0.5"></div>'
+        +'<div class="help"><b>要用"每轮都不一样的东西"点元素？</b>选择器值里可以直接写变量，'
+        +'点值输入框右边的 <b>{变量}</b> 按钮插入：<code>{本次要发的名字}</code>（循环轮到 / 要发的那条计划的名字）、'
+        +'<code>{本机账号名字}</code>（「读取文字」/「读取本机账号名字」读到的）。'
+        +'例：在账号列表里点自己要发的那个号 —— 类型选 <b>textContains（文本包含）</b>、值填 <code>{本次要发的名字}</code>。'
+        +'<br>变量那一刻还是空的（还没轮到 / 没读到）→ 值会变成空串并记一条警告，'
+        +'这一步就是"找不到元素"，<b>不会拿 {…} 字面量去乱点</b>。</div>');
     }else if(step.type==='long_click'){
       h+=_selRowHtml(p,'<div class="form-row"><div class="form-group"><label>长按时长(秒)</label><input type="number" class="form-control" data-key="duration" value="'+(p.duration||1.0)+'" step="0.5" min="0.3"></div>'+
         '<div class="form-group"><label>等待超时(秒)</label><input type="number" class="form-control" data-key="wait_timeout" value="'+(p.wait_timeout||2)+'" step="0.5" min="0.5"></div></div>');
@@ -308,9 +395,12 @@ var _stepEditor={
       h+=_selRowHtml(p,'<div class="form-row"><div class="form-group"><label>方向</label><select class="form-control" data-key="direction">'+
         '<option value="up"'+(p.direction!=='down'?' selected':'')+'>上滑</option>'+
         '<option value="down"'+(p.direction==='down'?' selected':'')+'>下滑</option></select></div>'+
-        '<div class="form-group"><label>最多滑动次数</label><input type="number" class="form-control" data-key="max_swipes" value="'+(p.max_swipes||8)+'" min="1" max="50"></div></div>'+
+        '<div class="form-group"><label>最多滑动次数</label><input type="number" class="form-control" data-key="max_swipes" value="'+(p.max_swipes||8)+'" min="1" max="50"></div>'+
+        '<div class="form-group"><label>幅度(屏占比)</label><input type="number" class="form-control" data-key="distance_ratio" value="'+(p.distance_ratio!=null?p.distance_ratio:0.6)+'" step="0.05" min="0.1" max="0.9"></div></div>'+
         '<div class="form-group form-check"><input type="checkbox" data-key="click_when_found" '+(p.click_when_found!==false?'checked':'')+'><label>找到后点击</label></div>'+
-        '<div class="help">上滑/下滑直到目标元素出现（每次滑动后检查一次），找不到则跳过继续</div>');
+        _humanizeChkHtml(p)+
+
+        '<div class="help">上滑/下滑直到目标元素出现（每次滑动后检查一次），找不到则跳过继续。滑动同样走拟人轨迹</div>');
     }else if(step.type==='wait_el'){
       h+=_selRowHtml(p,'<div class="form-group"><label>最长等待(秒)</label><input type="number" class="form-control" data-key="timeout" value="'+(p.timeout||10)+'" min="1" max="120"></div>'+
         '<div class="help">等待目标元素出现（替代固定秒数等待），超时则继续</div>');
@@ -324,20 +414,66 @@ var _stepEditor={
           return '<option value="'+k[0]+'"'+(p.key===k[0]?' selected':'')+'>'+k[1]+'</option>';
         }).join('')+'</select></div>';
       h+='<div class="help">返回键用于退出评论/返回上一页，比结束App轻量</div>';
+    }else if(step.type==='notify'){
+      h+='<div class="form-group"><label>标题</label><input type="text" class="form-control" data-key="title" value="'+esc(p.title||'')+'" placeholder="如 抖音号1 掉线了（留空用任务通知）"></div>';
+      h+='<div class="form-group"><label>内容</label><textarea class="form-control" data-key="message" rows="2" style="min-height:52px">'+esc(p.message||'')+'</textarea></div>';
+      h+='<div class="form-row"><div class="form-group"><label>级别</label><select class="form-control" data-key="level">'+
+        [['info','ℹ️ 普通'],['success','✅ 正常'],['warning','⚠️ 警告'],['error','❌ 异常']].map(function(l){
+          return '<option value="'+l[0]+'"'+((p.level||'info')===l[0]?' selected':'')+'>'+l[1]+'</option>';}).join('')+
+        '</select></div></div>';
+      h+='<div class="help">推送到哪条群取决于 webhook 自己的<b>事件订阅</b>（勾了「任务自定义通知」的才收）。'
+        +'正文可用占位符：<b>{device}</b> 设备名、<b>{serial}</b> 地址、<b>{job}</b> 任务名、<b>{time}</b> 时间、'
+        +'<b>{app}</b> 当前前台包名、<b>{screen}</b> 亮屏/熄屏（后两个要查设备，不用就别写）</div>';
+    }else if(step.type==='stop_self'){
+      h+='<div class="form-group"><label>停止原因（可留空）</label><input type="text" class="form-control" data-key="reason" value="'+esc(p.reason||'')+'" placeholder="如 连续刷到广告"></div>';
+      h+='<div class="help">只停<b>本设备</b>的任务，其它设备照常；后续步骤不再执行，任务记为「被停止」而不是失败'
+        +'（不会触发失败重试）。常配合「条件判断」用：命中条件 → 先「发通知」再「停止本设备」</div>';
+    }else if(step.type==='gesture'){
+      var pts=(p.points||[]);
+      var dur=pts.length?pts[pts.length-1][2]:0;
+      h+='<div class="form-row"><div class="form-group" style="flex:2"><label>录制状态</label>'+
+        '<div style="padding:6px 0;font-size:13px">'+(pts.length
+          ? (pts.length+' 个轨迹点 · 时长 '+(dur/1000).toFixed(2)+' 秒 · 起点 ('+pts[0][0]+','+pts[0][1]+')')
+          : '<span class="text-muted">还没有录制</span>')+'</div></div>';
+      if(_can('devices')){
+        h+='<div class="form-group"><button class="btn btn-sm btn-primary" onclick="_stepEditor.recordInto(this,\'phone\')">● 手机上录</button></div>';
+        h+='<div class="form-group"><button class="btn btn-sm" onclick="_stepEditor.recordInto(this,\'web\')">● 网页上录</button></div>';
+      }
+      h+='<div class="form-group"><label>速度</label><input type="number" class="form-control" data-key="speed" value="'+(p.speed!=null?p.speed:1.0)+'" step="0.1" min="0.1" max="5"></div>';
+      h+='<div class="form-group"><button class="btn btn-sm btn-danger" onclick="_stepEditor.clearGesture(this)">清空</button></div></div>';
+      h+='<div class="help">这是<b>纯录制回放</b>：路径与时长照录制原样重放，不做弧线/抖动/手速那套加工（和「滑动」步骤是两回事）。'
+        +'<b>手机上录</b>=用手指在真机上划（最真实）；<b>网页上录</b>=在弹窗画面里按住鼠标拖。'
+        +'轨迹按屏幕绝对像素存，换分辨率不同的设备可能偏，同型号/同分辨率最稳</div>';
     }else if(step.type==='wait'){
       h+='<div class="form-row"><div class="form-group"><label>最短(秒)</label><input type="number" class="form-control" data-key="min" value="'+(p.min||1.0)+'" step="0.5" min="0.1"></div>';
       h+='<div class="form-group"><label>最长(秒)</label><input type="number" class="form-control" data-key="max" value="'+(p.max||3.0)+'" step="0.5" min="0.1"></div></div>';
+      h+='<div class="form-group form-check"><input type="checkbox" data-key="vary_pace" '+(p.vary_pace?'checked':'')+'><label>按设备节奏微调（0.8~1.35 倍）</label></div>';
+      h+='<div class="help">勾上后每台设备按自己的节奏缩放这个等待：批量跑时设备之间会逐渐错开，不再整齐划一。代价是实际时长不再严格等于上面填的值</div>';
     }else if(step.type==='clipboard'){
       h+='<div class="form-group"><label>注入内容</label><textarea class="form-control" data-key="text" rows="3" style="font-family:monospace;min-height:70px">'+esc(p.text||'')+'</textarea></div>';
       h+='<div class="form-group form-check"><input type="checkbox" data-key="paste" '+(p.paste!==false?'checked':'')+'><label>注入后立即粘贴（需输入框已聚焦）</label></div>';
       h+='<div class="help">批量发链接场景：先"点击元素"聚焦评论区输入框，再执行本步骤注入+粘贴；循环里依次更换注入内容即可逐个发</div>';
     }else if(step.type==='input_text'){
       const im=p.mode==='fixed'?'fixed':'random';
-      h+='<div class="form-group"><label>输入模式</label><select class="form-control" data-key="mode" onchange="_stepEditor._toggleInputMode(this)">'+
+      const tsrc=p.text_source||'manual';
+      const fromPlan=(tsrc!=='manual');
+      // 取值来源：默认手填（行为与以前一致）；也可以直接吃「发布计划」里那一条的标题
+      h+='<div class="form-group"><label>取值来源</label><select class="form-control" data-key="text_source" onchange="_stepEditor._inputSourceChanged(this)">'+
+        [['manual','手填 / 随机候选（默认）'],['release_title','发布计划这一条的标题'],
+         ['release_title_topics','发布计划标题 + 话题'],['release_body','发布计划这一条的正文'],
+         ['release_body_topics','发布计划正文 + 话题'],['release_title_body','标题 + 正文（一个框时用）']]
+          .map(function(o){return '<option value="'+o[0]+'"'+(tsrc===o[0]?' selected':'')+'>'+o[1]+'</option>';}).join('')+
+        '</select><div class="help">选"发布计划"时，标题由前面的「推送发布视频」那一步取出来（同一次运行里传递；没取到会跳过并告警）—— 你就不用把同一句文案再抄一遍了</div></div>';
+      if(fromPlan){
+        h+='<div class="form-group" data-key-wrap="release_topics" style="display:'+(/topics$/.test(tsrc)?'block':'none')+'"><label>话题（逗号分隔，不带 # 会自动补）</label><input type="text" class="form-control" data-key="release_topics" value="'+esc(p.release_topics||'')+'" placeholder="如 苏州,日常"></div>';
+        h+='<div class="help" style="color:#f59e0b">取计划标题时<b>会回读输入框校验</b>：抖音的输入框有时不吃键盘输入，不校验就可能发出一篇空文案；校验不过会自动改走剪贴板粘贴再验一次</div>';
+      }
+      // 手填那两块：**只隐藏不删**（_syncParams 按 DOM 存在与否收集，删了会把用户填的值抹掉）
+      h+='<div class="form-group" style="display:'+(fromPlan?'none':'block')+'"><label>输入模式</label><select class="form-control" data-key="mode" onchange="_stepEditor._toggleInputMode(this)">'+
         '<option value="random"'+(im==='random'?' selected':'')+'>随机候选</option>'+
         '<option value="fixed"'+(im==='fixed'?' selected':'')+'>指定文字</option></select></div>';
-      h+='<div class="form-group" data-mode="random" style="display:'+(im==='random'?'block':'none')+'"><label>候选文字（每行一个，随机选一条）</label><textarea class="form-control" data-key="texts" rows="4" style="font-family:monospace;min-height:80px">'+esc(p.texts||'你好\n有趣\n支持')+'</textarea></div>';
-      h+='<div class="form-group" data-mode="fixed" style="display:'+(im==='fixed'?'block':'none')+'"><label>指定文字</label><input type="text" class="form-control" data-key="fixed_text" value="'+esc(p.fixed_text||'')+'"></div>';
+      h+='<div class="form-group" data-mode="random" style="display:'+((!fromPlan&&im==='random')?'block':'none')+'"><label>候选文字（每行一个，随机选一条）</label><textarea class="form-control" data-key="texts" rows="4" style="font-family:monospace;min-height:80px">'+esc(p.texts||'你好\n有趣\n支持')+'</textarea></div>';
+      h+='<div class="form-group" data-mode="fixed" style="display:'+((!fromPlan&&im==='fixed')?'block':'none')+'"><label>指定文字</label><input type="text" class="form-control" data-key="fixed_text" value="'+esc(p.fixed_text||'')+'"></div>';
       h+='<div class="form-group form-check"><input type="checkbox" data-key="clear_first" '+(p.clear_first!==false?'checked':'')+'><label>输入前先清空</label></div>';
       h+='<div class="help">需先用"点击元素"步骤定位到输入框，本步骤只负责输入文字</div>';
     }else if(step.type==='loop'){
@@ -349,16 +485,140 @@ var _stepEditor={
         '<div class="form-group" data-lmode="rounds" style="display:'+(lm==='rounds'?'block':'none')+'"><label>最大循环次数</label><input type="number" class="form-control" data-key="max_iterations" value="'+(p.max_iterations||10)+'" min="1" max="100000"></div>'+
         '<div class="form-group" data-lmode="time" style="display:'+(lm==='time'?'block':'none')+'"><label>循环时长(秒)</label><input type="number" class="form-control" data-key="loop_duration" value="'+(p.loop_duration||600)+'" min="1"></div></div>';
       h+='<div class="help">将下方子步骤循环执行指定轮次/时长；<b>一直循环</b>无限跑直到任务被外部停止——配合调度"定时启动+停止"（如 9:00 启动 / 18:00 停止）实现全天候养号，或配合任务"运行时长上限"自动停止</div>';
+    }else if(step.type==='read_text'){
+      // 读取文字：把某个元素的文字读出来存进变量（通用版；发布专用的那个是「读取本机账号名字」）
+      var om2=p.on_missing||'skip';
+      h+='<div class="form-row"><div class="form-group"><label>读哪个元素的文字</label><input type="text" class="form-control" data-key="selector_value" value="'+esc(p.selector_value||'')+'" placeholder="选择器值（xpath / 文本包含等），可用 {本次要发的名字}"></div>'+
+        '<div class="form-group"><label>最多等(秒)</label><input type="number" class="form-control" data-key="timeout" value="'+(p.timeout||8)+'" min="1" max="120"></div></div>';
+      h+='<div class="form-row"><div class="form-group"><label>选择器类型</label><select class="form-control" data-key="selector_type">'+
+        ['xpath','textContains','text','resourceId','descriptionContains','description','className'].map(function(t){
+          return '<option value="'+t+'"'+((p.selector_type||'xpath')===t?' selected':'')+'>'+t+'</option>';}).join('')+
+        '</select></div>'+
+        '<div class="form-group"><label>存到哪个变量名</label><input type="text" class="form-control" data-key="var" value="'+esc(p.var||'account_name')+'" placeholder="account_name">'+
+        '<div class="help">存下之后，选择器值里可以写 <code>{变量名}</code>，「条件判断」的候选值来源也能选「变量」。'+
+        '变量名叫 <code>account_name</code> 时，顺带把它当本机账号名（切号/推送核对会复用）</div></div></div>';
+      h+='<div class="form-row"><div class="form-group"><label>清洗方式</label><select class="form-control" data-key="clean">'+
+        [['account','按账号名清洗（去首尾空白/按钮字，推荐）'],['strip','只去首尾空白（原样，别看错）']].map(function(o){
+          return '<option value="'+o[0]+'"'+((p.clean||'account')===o[0]?' selected':'')+'>'+o[1]+'</option>';}).join('')+
+        '</select></div>'+
+        '<div class="form-group"><label>读不到时</label><select class="form-control" data-key="on_missing">'+
+        [['skip','记一句、继续（默认）'],['fail','算这一步失败']].map(function(o){
+          return '<option value="'+o[0]+'"'+(om2===o[0]?' selected':'')+'>'+o[1]+'</option>';}).join('')+
+        '</select></div></div>';
+      h+='<div class="help">把元素的文字<b>读出来存成变量</b>，给后面的步骤用（选择器值里写 <code>{变量名}</code>，'+
+        '或让「条件判断」的候选值来源选「变量」）。只有读、不点任何东西；读不到按上面的选项处置。</div>';
+    }else if(step.type==='expect_el'){
+      // 校验页面：只做校验、不带副作用 —— 确认"上一步真的完成了"
+      var om=p.on_missing||'skip_rest';
+      h+='<div class="form-row"><div class="form-group"><label>等它出现（这一页的特征元素）</label><input type="text" class="form-control" data-key="selector_value" value="'+esc(p.selector_value||'')+'" placeholder="如 //*[@text=\'所有照片\']"></div>'+
+        '<div class="form-group"><label>最多等(秒)</label><input type="number" class="form-control" data-key="timeout" value="'+(p.timeout||10)+'" min="1" max="60"></div></div>';
+      h+='<div class="form-row"><div class="form-group"><label>选择器类型</label><select class="form-control" data-key="selector_type">'+
+        ['xpath','resourceId','descriptionContains','text','description','className'].map(function(t){
+          return '<option value="'+t+'"'+((p.selector_type||'xpath')===t?' selected':'')+'>'+t+'</option>';}).join('')+
+        '</select></div>'+
+        '<div class="form-group"><label>等不到时</label><select class="form-control" data-key="on_missing">'+
+        [['skip_rest','跳过本轮剩余步骤（推荐：这一条不发）'],['notify','只发通知、继续（有盲点风险）'],['stop','停本设备']].map(function(o){
+          return '<option value="'+o[0]+'"'+(om===o[0]?' selected':'')+'>'+o[1]+'</option>';}).join('')+
+        '</select></div></div>';
+      h+='<div class="form-group"><label>说明（写进日志/通知，如"应在相册页"）</label><input type="text" class="form-control" data-key="what" value="'+esc(p.what||'')+'"></div>';
+      h+='<div class="help">放在关键点击<b>前面</b>：确认上一步真的完成了（该出现的特征元素在不在）。'+
+        '页面不对就按上面的选项处置 —— 避免在错的页面上继续盲点，最后"跑完了但什么都没发出去"。</div>';
+    }else if(step.type==='foreach_account'){
+      // 循环本机待发的号（发布流程的最外层容器）：把"跑哪些号"讲清楚，别让人以为是普通循环
+      const fds=(p.date_source==='fixed')?'fixed':'today';
+      h+='<div class="form-row"><div class="form-group"><label>跑哪天的计划</label><select class="form-control" data-key="date_source">'+
+        '<option value="today"'+(fds==='today'?' selected':'')+'>今天</option>'+
+        '<option value="fixed"'+(fds==='fixed'?' selected':'')+'>指定日期</option></select></div>'+
+        '<div class="form-group"><label>指定日期(YYYY-MM-DD，仅上面选"指定日期"时用)</label><input type="text" class="form-control" data-key="fixed_date" value="'+esc(p.fixed_date||'')+'" placeholder="2026-10-12"></div></div>';
+      h+='<div class="form-row"><div class="form-group"><label>最多跑几个号（0=不限）</label><input type="number" class="form-control" data-key="max_accounts" value="'+(p.max_accounts||0)+'" min="0"></div>'+
+        '<div class="form-group form-check" style="align-self:end"><input type="checkbox" data-key="retry_failed" '+(p.retry_failed!==false?'checked':'')+'><label>失败过的也再试</label></div></div>';
+      h+='<div class="help">一轮把本机<b>待发的号</b>跑完：逐个把名字写进"本次要发的名字"，执行下方子步骤（切号 → 读名字 → 校验 → 推送 → 发布 → 标记）；<b>试过的不回头</b>，跑完/被停/超时/到上限就收工。数据源是<b>计划表</b>（谁还有待发内容谁就在里面），不需要任何账号维护。</div>';
     }else if(step.type==='group'){
       h+='<div class="help">动作组：按顺序执行下方子步骤一次。把多个步骤打包成一个可复用的整体。</div>';
       h+='<div class="form-group"><button class="btn btn-xs btn-primary" onclick="_stepEditor.saveAsCustomAction(\''+esc(step.id||'')+'\')">存为自定义动作</button> <span class="help" style="display:inline">把本组步骤保存到左侧自定义动作库，方便复用</span></div>';
     }else if(step.type==='if_el'){
+      // 屏幕状态 / 前台App / 去重 是"直接读设备当前状态或账本"，没有等待超时、也没有选择器可抓
+      var isDedup=(p.selector_type==='dedup');
+      var dyn=(p.selector_type==='screen'||p.selector_type==='foreground'||isDedup);
+      // 文本比对：屏幕状态没有文本可比（亮/熄）、去重也不比文本，只有元素/OCR/前台 App 才给这块
+      // 候选值来源：默认"手填"（行为与以前完全一致）；也可以取"本次要发的名字"/发布计划
+      var cmpSrc=p.cmp_source||'';
+      var fromPlatform=(cmpSrc==='account_target'||cmpSrc==='release'||cmpSrc==='var');
+      var cmpRow=dyn?'':'<div class="form-row"><div class="form-group"><label>文本比对</label>'+
+        '<select class="form-control" data-key="cmp_op">'+
+        [['','不比对（只看元素在不在）'],['等于','等于'],['不等于','不等于'],['包含','包含'],['不包含','不包含']]
+          .map(function(o){return '<option value="'+o[0]+'"'+((p.cmp_op||'')===o[0]?' selected':'')+'>'+o[1]+'</option>';}).join('')+
+        '</select></div>'+
+        '<div class="form-group"><label>候选值来源</label>'+
+        '<select class="form-control" data-key="cmp_source" onchange="_stepEditor._cmpSourceChanged(this)">'+
+        [['','手填（默认）'],['account_target','本次要发的名字（读名字/循环块给的）'],
+         ['release','本机当前发布计划（要发的那条）'],
+         ['var','变量（「读取文字」读到的）']]
+          .map(function(o){return '<option value="'+o[0]+'"'+((p.cmp_source||'')===o[0]?' selected':'')+'>'+o[1]+'</option>';}).join('')+
+        '</select><div class="help">'+(p.cmp_source==='release'
+          ? '取<b>本机下一条要发的发布计划</b>的<b>名字</b>（推送前校验"当前登的是不是要发的号"就用它）'
+          : (p.cmp_source==='account_target'
+             ? '取<b>本次要发的那个名字</b>（「读取本机账号名字」读到的，或循环块设的目标）。'
+               +'<b>读不到名字时候选为空 → 不命中 → 走 else（不发）</b>，这是故意的'
+             : (p.cmp_source==='var'
+                ? '取<b>「读取文字」存下的那个变量</b>（变量名在右边那格填，默认 account_name）。'
+                  +'<b>变量是空的 → 候选为空 → 不命中</b>'
+                : '手填要比对的文本；要用本机账号名就用上面的两个来源')))+'</div></div>'+
+        // 变量名：只有来源选「变量」时才显眼，其余情况**只隐藏不删**（同上，_syncParams 按 DOM 收集）
+        '<div class="form-group"'+(p.cmp_source==='var'?'':' style="display:none"')+'>'+
+        '<label>变量名</label><input type="text" class="form-control" data-key="cmp_var" value="'+
+        esc(p.cmp_var||'account_name')+'" placeholder="account_name">'+
+        '<div class="help">「读取文字」步骤里填的那个变量名（两边要一模一样）</div></div>'+
+        // 候选值来自平台时**只隐藏、不删**这个输入框：_syncParams 是按 DOM 存在与否收集的，
+        // 删了就等于把用户手填的值悄悄抹掉（同类坑见本文件 927 行附近的注释）
+        '<div class="form-group" style="grid-column:span 2'+(fromPlatform?';display:none':'')+'">'+
+        '<label>比对的值（可多行，任一命中即可）</label>'+
+        '<textarea class="form-control" data-key="cmp_value" rows="2" style="font-family:var(--mono)" '+
+        'placeholder="如 35377983067&#10;35377983068">'+esc(p.cmp_value||'')+'</textarea>'+
+        '<div class="help">一行一个（也认 <code>|</code> 分隔）：<b>任意一个命中就算命中</b>——多个值的场景把值都列上。'+
+        '<b>逗号不当分隔符</b>，因为要比对的文本本身常带逗号'
+        +(fromPlatform?'<br>候选值由平台给（上面选的来源），手填的值会<b>追加</b>在后面。':'')
+        +'</div></div></div>';
+      // 「去重」条件：身份元素用 ident_type/ident_value（主选择器那行只剩类型下拉）
+      var identRow=isDedup?_selRowHtml(p,
+        '<div class="help"><b>身份元素</b>：填"账号"那个元素（点「抓取元素」选，如抖音号那个 TextView）。'
+        +'<b>留空 = 用本设备当身份</b>（一号一机时这样就行）。'
+        +'<br>身份<b>读不到时不会去重</b>（当"没做过"照常执行）——宁可重复一次，也不会误判成"做过"而漏做。'
+        +'<br>有效期在上方任务级的<b>「去重有效期」</b>里设，检查和记账共用一套（不用在步骤里各填一遍）。</div>',
+        false, false, {type:'ident_type', value:'ident_value'}):'';
       h+=_selRowHtml(p,
-        '<div class="form-group"><label>查找超时(秒)</label><input type="number" class="form-control" data-key="timeout" value="'+(p.timeout||3)+'" min="0.5" max="30" step="0.5"></div>'+
+        (dyn?'':'<div class="form-group"><label>查找超时(秒)</label><input type="number" class="form-control" data-key="timeout" value="'+(p.timeout||3)+'" min="0.5" max="30" step="0.5"></div>'+
         '<div class="form-group form-check" data-ocr-field style="display:'+(p.selector_type==='ocr'?'block':'none')+'">'+
         '<input type="checkbox" data-key="ocr_click" '+(p.ocr_click?'checked':'')+'><label>OCR 命中后自动点击该文字</label></div>'+
-        '<div class="help">超时内找到元素 → 执行下方"✅ 找到时"分支；未找到 → 执行"❌ 未找到时"分支。两分支可放任意步骤，也可再嵌套条件判断/循环；'+
-        '<b>OCR识别</b>可匹配图片/画布里的文字（截屏识别，跨平台）</div>', true);
+        cmpRow)+
+        '<div class="help">'+(isDedup
+          ? '命中 → 执行下方"✅ 找到时"分支；未命中 → 执行"❌ 未找到时"分支。'
+            +'<b>去重</b>读的是平台的「去重账本」（所有设备共享一份，见「任务 → 去重记录」）：'
+            +'<b>任何一台设备做过了，其余设备的这一步都会命中</b>——'
+            +'所以多个手机跑同一个任务、反复重跑，也不会把同一个号做两次。'
+            +'<br>建议这样摆：<b>命中分支</b>放「停止本设备」或「发通知」；'
+            +'<b>未命中分支</b>里放要做的动作（评论…），动作后面跟一个「记为已做」。'
+            +'<br>⚠ 记账要放在动作<b>成功之后</b>（用「记为已做」步骤），失败就不记账、下次还会重试。'
+          : (dyn
+          ? '命中 → 执行下方"✅ 找到时"分支；未命中 → 执行"❌ 未找到时"分支。<b>屏幕状态</b>读系统 mWakefulness（亮/熄），'
+            +'<b>前台App是</b>判断当前前台是不是某个包名——都只看当前状态，不等待。'
+          : '超时内找到元素 → 执行下方"✅ 找到时"分支；未找到 → 执行"❌ 未找到时"分支。两分支可放任意步骤，也可再嵌套条件判断/循环；'
+            +'<b>OCR识别</b>可匹配图片/画布里的文字（截屏识别，跨平台）'
+            +'<br><b>文本比对</b>（可选）：填了就把找到的那个元素的<b>文本</b>和"比对的值"比，'
+            +'比中了才算命中。例：元素文本是 <code>抖音号：35377983067</code>，'
+            +'想判断"这台登录的是不是这个号"，选<b>包含</b>、值填 <code>35377983067</code> 即可（要整段一模一样才用"等于"）。'
+            +'多个值一行一个，<b>任一命中即可</b>——"这几个号都算我的"。'
+            +'<br>⚠ 元素<b>没找到</b>时一律算未命中（走"未找到时"分支）——"没读到"不会被当成"和我设的不一样"。'))+'</div>',
+        true, true, isDedup?{hideValue:true}:null)+identRow;
+    }else if(step.type==='mark_done'){
+      h+=_selRowHtml(p,
+        '<div class="help">把身份值记进平台「去重账本」（所有设备共享一份）。'
+        +'放在动作<b>成功之后</b>——动作失败就不会记账，下次重跑还会重试这台设备。'
+        +'<br>✅ <b>留空 = 自动跟随上面「去重」检查的身份</b>（推荐）：'
+        +'检查与记账必须用<b>同一个身份字符串</b>，key 才算得到一起；'
+        +'两处各配一遍的话，一边填了另一边忘了去重就会失效。'
+        +'<br>没有前置去重检查、又留空时，退回用<b>本设备</b>当身份（一号一机场景）。'
+        +'<br>有效期在上方任务级的<b>「去重有效期」</b>里设。</div>');
     }
     // 共享：触发概率（所有步骤通用，0~100）
     h+='<div class="form-row" style="margin-top:8px"><div class="form-group"><label>触发概率(%)</label><input type="number" class="form-control" data-key="probability" value="'+(p.probability!=null?p.probability:100)+'" min="0" max="100"><div class="help">0~100，&lt;100 表示按概率执行（如 30=隔几次才触发一次，适合"偶尔点赞"）</div></div></div>';
@@ -453,7 +713,44 @@ var _stepEditor={
     }
   },
   _makeStep:function(lib){
-    return {id:_newStepId(),type:lib.type,label:lib.label,params:JSON.parse(JSON.stringify(lib.params))};
+    // 参数 = STEP_LIB 出厂值 ← 用户在「动作配置」里配的默认值（有才覆盖）
+    var params=JSON.parse(JSON.stringify(lib.params));
+    var d=_stepDefaults&&_stepDefaults[lib.type];
+    if(d)Object.keys(d).forEach(function(k){ if(d[k]!==undefined)params[k]=d[k]; });
+    return {id:_newStepId(),type:lib.type,label:lib.label,params:params};
+  },
+  // 递归找步骤对象（按 id）——写入录音必须改 _steps，不能只改 DOM
+  _findStep:function(id,arr){
+    var self=this, found=null;
+    (arr||this._steps).forEach(function(st){
+      if(found)return;
+      if(st.id===id){found=st;return;}
+      _childArrs(st).forEach(function(a){ if(!found)found=self._findStep(id,a); });
+    });
+    return found;
+  },
+  // 给某个「录制手势」步骤录制轨迹（src: 'phone' 手机上录 / 'web' 网页上录）
+  recordInto:function(btn,src){
+    var card=btn.closest('.step-card');
+    var step=card?this._findStep(card.dataset.stepId):null;
+    if(!step){showToast('找不到这个步骤','error');return;}
+    if(typeof openRecorder!=='function'){showToast('录制器未加载','error');return;}
+    var self=this;
+    openRecorder({mode:'gesture', autoStartPhone: src==='phone', onDone:function(p,from){
+      step.params={points:p.points,speed:p.speed||1.0};
+      var dur=p.points.length?p.points[p.points.length-1][2]:0;
+      step.label='录制手势 '+(from==='phone'?'手机':'网页')+' '+p.points.length+'点';
+      self._renderCanvas();
+      showToast('已录到 '+(p.points.length)+' 个点 / '+(dur/1000).toFixed(2)+' 秒','success');
+    }});
+  },
+  clearGesture:function(btn){
+    var card=btn.closest('.step-card');
+    var step=card?this._findStep(card.dataset.stepId):null;
+    if(!step){return;}
+    step.params={points:[],speed:1.0};
+    this._renderCanvas();
+    showToast('已清空录制的轨迹','success');
   },
   // 测试此步骤：在选中设备上试执行当前步骤，验证选择器
   _testStep:function(btn){
@@ -480,10 +777,7 @@ var _stepEditor={
       if(!list)return;
       if(!r||!r.ok){list.innerHTML='<div class="se-empty">'+esc((r&&r.error)||'获取设备失败')+'</div>';return;}
       list.innerHTML=(r.devices||[]).map(function(d){
-        return '<div class="el-device-card" onclick="_stepEditor._runTestStep(\''+esc(d.serial)+'\')">'+
-          '<div class="edc-icon">📱</div>'+
-          '<div class="edc-info"><div class="edc-serial">'+esc(d.serial)+'</div>'+
-          '<div class="edc-model">'+esc(d.model||d.product||'')+'</div></div></div>';
+        return self._devCard(d, "_stepEditor._runTestStep('"+esc(d.serial)+"')");
       }).join('')||'<div class="se-empty">无可用设备</div>';
     });
   },
@@ -625,11 +919,69 @@ var _stepEditor={
       g.style.display=g.dataset.lmode===mode?'block':'none';
     });
   },
+  // 输入文字：取值来源切到"发布计划"时，把手填那两块藏起来（话题输入框反过来显示）
+  _inputSourceChanged:function(sel){
+    this._syncFromDom();          // 同 _cmpSourceChanged：不先同步，重渲染会吞掉刚改的值
+    var self=this;
+    setTimeout(function(){self._renderCanvas();},0);
+  },
+  // 条件判断：候选值来源切到"平台给"（本次要发的名字 / 发布计划）时，把"比对的值"藏起来
+  // 在选择器值里插入变量占位符：点「{变量}」→ 弹出两个变量 → 选中即插到光标处
+  insertVar:function(btn){
+    var old=document.getElementById('_varMenu');
+    if(old){old.remove();}
+    var box=btn.closest('.sel-picker')||btn.parentNode;
+    var input=box.querySelector('input[data-key],textarea[data-key]')||box.querySelector('input,textarea');
+    if(!input){return;}
+    var items=[['{本次要发的名字}','本轮要发的那个号（循环块给的）'],
+               ['{本机账号名字}','读到的本机账号（读取文字/读取本机账号名字）']];
+    var menu=document.createElement('div');
+    menu.id='_varMenu';
+    menu.style.cssText='position:fixed;z-index:9999;background:#fff;border:1px solid #d0d5dd;'
+      +'border-radius:6px;box-shadow:0 6px 16px rgba(0,0,0,.16);padding:4px;min-width:260px;font-size:12px';
+    menu.innerHTML=items.map(function(o){
+      return '<div class="_varItem" data-v="'+o[0]+'" style="padding:6px 8px;cursor:pointer;border-radius:4px">'
+        +'<code style="font-weight:600">'+o[0]+'</code>'
+        +'<div style="color:#667085;margin-top:2px">'+o[1]+'</div></div>';}).join('');
+    menu.querySelectorAll('._varItem').forEach(function(el){
+      el.onmouseenter=function(){el.style.background='#f2f4f7';};
+      el.onmouseleave=function(){el.style.background='';};
+      el.onclick=function(e){
+        e.stopPropagation();
+        var t=input.value||'';
+        var a=input.selectionStart==null?t.length:input.selectionStart;
+        var b=input.selectionEnd==null?t.length:input.selectionEnd;
+        input.value=t.slice(0,a)+el.dataset.v+t.slice(b);
+        try{input.setSelectionRange(a+el.dataset.v.length,a+el.dataset.v.length);}catch(_){}
+        input.dispatchEvent(new Event('input',{bubbles:true}));
+        input.dispatchEvent(new Event('change',{bubbles:true}));
+        input.focus();
+        menu.remove();
+      };
+    });
+    document.body.appendChild(menu);
+    var r=btn.getBoundingClientRect();
+    menu.style.left=Math.max(8,Math.min(r.left,window.innerWidth-280))+'px';
+    menu.style.top=(r.bottom+4)+'px';
+    setTimeout(function(){
+      document.addEventListener('click',function h(){
+        var m=document.getElementById('_varMenu'); if(m){m.remove();}
+        document.removeEventListener('click',h);});
+    },0);
+  },
+  _cmpSourceChanged:function(sel){
+    // 同 _condTypeChanged：先把 DOM 的值同步回 _steps，否则重渲染会吞掉刚改的东西
+    this._syncFromDom();
+    var self=this;
+    setTimeout(function(){self._renderCanvas();},0);
+  },
   // 条件判断：选择器类型切到 OCR 时显示"命中后点击"开关
-  _toggleOcrMode:function(sel){
-    var card=sel.closest('.step-card');
-    var f=card&&card.querySelector('[data-ocr-field]');
-    if(f)f.style.display=sel.value==='ocr'?'block':'none';
+  _condTypeChanged:function(sel){
+    // 条件类型一变，"值"控件也要跟着换（元素值输入框 / 屏幕亮熄下拉 / 包名输入），
+    // 整卡重渲染最省心。先把 DOM 的值同步回 _steps，否则重渲染会丢掉刚改的东西。
+    this._syncFromDom();
+    var self=this;
+    setTimeout(function(){self._renderCanvas();},0);
   },
   // 给数组分配唯一 id，用于 move/duplicate/remove/拖拽定位到正确的父数组
   _arrId:function(arr){
@@ -694,6 +1046,8 @@ var _stepEditor={
   validate:function(steps){
     // 校验步骤配置，返回警告列表
     var warnings=[];
+    // 去重：收集「条件判断→去重」与「记为已做」各自用的身份元素，最后比对是否一致
+    var dedupIdents=[], hasDedupCheck=false, hasMarkDone=false;
     function check(arr,prefix){
       arr.forEach(function(s,i){
         var name=prefix?(prefix+'.'+(i+1)):('步骤'+(i+1));
@@ -725,10 +1079,53 @@ var _stepEditor={
           if(!s.params.text){
             warnings.push(name+' "'+label+'": 注入内容为空，步骤会跳过。');
           }
+        }else if(s.type==='gesture'){
+          if(!(s.params.points||[]).length){
+            warnings.push(name+' "'+label+'": 录制手势还没有轨迹，执行时会被跳过。');
+          }
         }else if(s.type==='if_el'){
-          if(!s.params.selector_value){
+          // 「去重」「屏幕状态」这两类条件**不用文本比对**（面板里那块是隐藏的）。
+          // 所以：① 留着旧 cmp_op/cmp_value 不该报警告（用户看不到、也清不掉，
+          // 只会每次保存都被打扰）；② 也别报"会被忽略"——那是设计如此。
+          var cmpUsed=(s.params.selector_type!=='screen'&&s.params.selector_type!=='dedup');
+          if(s.params.selector_type!=='dedup'&&!s.params.selector_value){
             warnings.push(name+' "'+label+'": 条件判断的选择器为空，会直接走"未找到"分支。');
           }
+          var cmpSrcV=(s.params.cmp_source||'');
+          var fromPlatform=(cmpSrcV==='account_target'||cmpSrcV==='release'||cmpSrcV==='var');
+          // 候选值"平台给"的那两档（本次要发的名字 / 发布计划）：手填可以留空，别报"没填值"
+          var fromOther=fromPlatform;
+          if(cmpUsed&&s.params.cmp_op&&!String(s.params.cmp_value||'').trim()&&!fromOther){
+            warnings.push(name+' "'+label+'": 选了"文本比对('+s.params.cmp_op+')"但没填比对的值，'
+              +'执行时永远不命中（相当于每次都走"未找到时"分支）。');
+          }
+          if(cmpUsed&&cmpSrcV==='account_target'&&s.params.cmp_op){
+            warnings.push(name+' "'+label+'": 候选值来自"本次要发的名字" —— 前面要有'
+              +'「读取本机账号名字」步骤（或循环块设的目标名字），名字读不到时候选为空、'
+              +'这一步会走"未找到"分支。这是设计如此（读不到名字 = 不发）。');
+          }
+          if(cmpUsed&&cmpSrcV==='var'&&s.params.cmp_op){
+            warnings.push(name+' "'+label+'": 候选值来自变量『'+(s.params.cmp_var||'account_name')+'』 —— '
+              +'前面要有「读取文字」步骤把那个变量读出来，变量是空的时这一步会走"未找到"分支。');
+          }
+          if(cmpUsed&&cmpSrcV==='release'&&s.params.cmp_op){
+            warnings.push(name+' "'+label+'": 候选值来自"本机当前发布计划" —— 本机没有待发的计划'
+              +'时取不到号（这一步会走"未找到"分支）。这是设计如此（宁可不发、也不发错号），'
+              +'但请确认前面有「推送发布视频」步骤、且这条计划确实排到了本机。');
+          }
+          if(s.params.selector_type==='dedup'){
+            hasDedupCheck=true;
+            // 空值也收进来：一边填了、另一边没填 = 两处身份不一致（去重会对不上），
+            // 必须报出来 —— 只收非空的话，这种最常见的不一致反而检测不到
+            dedupIdents.push({where:name,type:s.params.ident_type||'text',
+                              value:(s.params.ident_value||'').trim()});
+          }
+        }else if(s.type==='mark_done'){
+          hasMarkDone=true;
+          // 留空 = 自动跟随去重检查的身份（执行器就是这么做的），所以**空值不参与比对**；
+          // 只有"填了、且和检查侧不一样"才是真问题
+          var mv=(s.params.selector_value||'').trim();
+          if(mv)dedupIdents.push({where:name,type:s.params.selector_type||'text',value:mv});
         }
         _childArrs(s).forEach(function(a){
           if(a.length)check(a,name+' 子步骤');
@@ -736,6 +1133,28 @@ var _stepEditor={
       });
     }
     check(steps,'');
+    // 去重的两个坑，保存时直接点出来（配错的话去重会「静默失效」，最难查）
+    if(hasDedupCheck&&!hasMarkDone){
+      warnings.push('任务里有「条件判断→去重」但没有「记为已做」：做完动作不会记账，'
+        +'下次重跑还会再做一遍（去重起不到作用）。请在动作后面加一个「记为已做」。');
+    }
+    if(hasMarkDone&&!hasDedupCheck){
+      warnings.push('任务里有「记为已做」但没有「条件判断→去重」：只会记账、不会拦重复。'
+        +'请在动作前面加一个条件判断、类型选「去重」。');
+    }
+    if(dedupIdents.length>1){
+      var first=dedupIdents[0];
+      var showId=function(x){ return x.value?('「'+x.value+'」'):'（留空 → 用设备当身份）'; };
+      dedupIdents.slice(1).forEach(function(d){
+        if(d.value!==first.value||d.type!==first.type){
+          warnings.push('去重两处的身份不一致：'+first.where+' 是 '+showId(first)
+            +'，而 '+d.where+' 是 '+showId(d)
+            +' —— 身份不一致会算出两个不同的 key，去重会失效'
+            +'（检查查不到记账 / 或者反过来，结果就是重复或漏做）。'
+            +'建议把「记为已做」的身份元素留空（自动跟随检查），或两处填成同一个元素。');
+        }
+      });
+    }
     return warnings;
   },
   _syncParams:function(container,steps){
@@ -765,11 +1184,16 @@ var _stepEditor={
         self._syncParams(childWrap,steps[i].params.children);
       }
       // if_el 双分支（then/else 在 .if-branch 内，不会与上面的直接子级选择器冲突）
-      var thenWrap=card.querySelector(':scope > .if-branch .step-children.if-then');
+      //
+      // ⚠ `.if-branch` 与 `.step-children` 之间**必须是 `>`（直接子级）**：
+      // 写成后代（空格）时，条件判断里再嵌套一个条件判断的话，本卡片会**匹配到内层
+      // 那个 if_el 的分支容器**（文档顺序上更靠前），于是把内层分支的子步骤当成自己的
+      // 去同步 —— 症状：自己的步骤"填了值保存就没了"、步骤名被内层的容器步骤覆盖。
+      var thenWrap=card.querySelector(':scope > .if-branch > .step-children.if-then');
       if(thenWrap&&steps[i].params&&Array.isArray(steps[i].params.then)){
         self._syncParams(thenWrap,steps[i].params.then);
       }
-      var elseWrap=card.querySelector(':scope > .if-branch .step-children.if-else');
+      var elseWrap=card.querySelector(':scope > .if-branch > .step-children.if-else');
       if(elseWrap&&steps[i].params&&Array.isArray(steps[i].params.else)){
         self._syncParams(elseWrap,steps[i].params.else);
       }
@@ -800,8 +1224,20 @@ var _stepEditor={
     // 直接弹设备选择页（独立模态框，不影响任务编辑窗口）
     this._showDevicePicker();
   },
+  // 设备选择卡片（「抓取元素」与「测试此步骤」两处共用）：
+  // **设备名优先**，型号与地址降为副标题——同型号好几台时只有平台起的名字
+  // （A08）能认出"是哪一台"，光看 IP 选错设备是常事。
+  _devCard:function(d,onclick){
+    var sub=[d.model||d.product||'', d.serial||''].filter(Boolean).join(' · ');
+    return '<div class="el-device-card" onclick="'+onclick+'">'+
+      '<div class="edc-icon">📱</div>'+
+      '<div class="edc-info"><div class="edc-name">'+esc(d.name||d.serial)+'</div>'+
+      '<div class="edc-serial">'+esc(sub)+'</div></div>'+
+      (d.status?'<span class="edc-status">'+esc(d.status)+'</span>':'')+'</div>';
+  },
   // 步骤1：设备选择页
   _showDevicePicker:function(){
+    var self=this;
     document.getElementById('el-picker-title').textContent='抓取元素 - 选择设备';
     document.getElementById('el-picker-body').innerHTML='<div class="el-device-grid"><div class="egd-title">选择要抓取元素的设备</div><div id="el-device-list">加载中...</div></div>';
     document.getElementById('el-picker-footer').innerHTML='<button class="btn" onclick="closeElPicker()">取消</button>';
@@ -812,11 +1248,7 @@ var _stepEditor={
       var devices=res.devices||[];
       if(!devices.length){list.innerHTML='<div class="se-empty">uiauto2 未发现已连接设备</div>';return;}
       list.innerHTML=devices.map(function(d){
-        return '<div class="el-device-card" onclick="_stepEditor._showElPicker(\''+esc(d.serial)+'\')">'+
-          '<div class="edc-icon">📱</div>'+
-          '<div class="edc-info"><div class="edc-serial">'+esc(d.serial)+'</div>'+
-          '<div class="edc-model">'+esc(d.model||d.product||'')+'</div></div>'+
-          '<span class="edc-status">'+esc(d.status||'device')+'</span></div>';
+        return self._devCard(d, "_stepEditor._showElPicker('"+esc(d.serial)+"')");
       }).join('');
     }).catch(function(e){
       document.getElementById('el-device-list').innerHTML='<div class="se-empty">请求失败: '+esc(e)+'<br><button class="btn btn-sm" style="margin-top:10px" onclick="_stepEditor._showDevicePicker()">重试</button></div>';
@@ -1194,10 +1626,16 @@ var _stepEditor={
     }
     // 填入推荐选择器值，并切换选择器类型
     this._elTargetInput.value=el.suggested.value;
-    var sel=this._elTargetInput.closest('.sc-body').querySelector('[data-key="selector_type"]');
+    // 选择器类型下拉：通用编辑器里在同一个 .sc-body 内；别的编辑器（「发布计划」页的
+    // 步骤就地编辑）结构不同，取不到就跳过、交给下面的 _onFill 自己处理
+    var box=this._elTargetInput.closest('.sc-body');
+    var sel=box?box.querySelector('[data-key="selector_type"]'):null;
     if(sel)sel.value=el.suggested.type;
-    // 程序赋值不会触发 input 事件，手动同步回 _steps 防丢失
-    this._syncFromDom();
+    // 程序赋值不会触发 input 事件，手动同步防丢失。
+    // 默认同步回通用编辑器的 _steps；**别的编辑器用 _onFill 接管**
+    // （见 static/admin/release.js 的就地编辑），否则会同步到不相干的模型上
+    if(typeof this._onFill==='function')this._onFill(el, this._elTargetInput);
+    else this._syncFromDom();
     // 只关闭抓取元素弹窗，不影响任务编辑窗口
     closeElPicker();
     showToast('已填入: '+el.suggested.type+'='+el.suggested.value,'success');
@@ -1220,6 +1658,18 @@ async function saveTask(jobId){
     }
     const mdEl=document.getElementById('f-max_duration');
     params={max_duration:mdEl?parseInt(mdEl.value)||0:0,steps:steps};
+    // 去重有效期（任务级；「条件判断→去重」与「记为已做」共用这一套）
+    const drEl=document.getElementById('f-dedup_reset');
+    params.dedup_reset=drEl?drEl.value:'day';
+    if(drEl&&drEl.value==='hours'){
+      const dhEl=document.getElementById('f-dedup_hours');
+      params.dedup_hours=Math.max(1,parseInt(dhEl&&dhEl.value)||6);
+    }
+    // 公共巡检（任务级，独立于步骤画布；实现在 tasks.js + core/patrol.py）
+    if(typeof patrolCollect==='function'){
+      const ws=patrolCollect();
+      if(ws.length)params.watchers=ws;
+    }
   }else{
     try{params=JSON.parse(document.getElementById('f-params').value||'{}');}
     catch(e){showToast('参数 JSON 格式错误','error');return;}

static/admin/monitor.js

@@ -13,6 +13,9 @@ function _sortValue(dev,key){
     // 按状态优先级排序：running>connecting>idle>done>error>released
     const order={running:0,connecting:1,idle:2,done:3,released:4,error:5,failed:6};
     v=order[dev.worker_status]||99;
+  }else if(key==='battery'){
+    // 没采到电量的排最后（用 -1 而不是 0，0% 是真实电量）
+    v=dev.battery?dev.battery.level:-1;
   }else{
     v=dev[key]||'';
   }
@@ -325,6 +328,22 @@ function renderDevices(){
   applyListPager('devices');
   initListSearch('devices','search-devices');
 }
+// 电量单元格：告警档位（tier 0 正常/1 低/2 严重）由后端算好，前端只上色——
+// 阈值只在「工具 → 设备发现 → 电量监控」一处定义，两边不重复判
+function _battCell(dev){
+  const b=dev.battery;
+  if(!b)return '<span class="text-muted">-</span>';
+  const t=b.tier||0;
+  const cls=t===2?'label-danger':(t===1?'label-warning':'label-success');
+  const mins=b.at?Math.floor((Date.now()/1000-b.at)/60):-1;
+  const ageTxt=(mins<0?'':(mins<1?'刚刚':mins+' 分钟前'));
+  const chg=b.charging?' ⚡':'';
+  const tip=(t===2?'电量严重不足':(t===1?'电量低':'电量正常'))
+    +(b.charging?'（充电中）':'')+(ageTxt?'（'+ageTxt+'采集）':'')
+    +(dev.present?'':'（设备已离线，显示最后一次读数）');
+  const stale=dev.present?'':'<div style="font-size:11px;color:#94a3b8">'+ageTxt+'</div>';
+  return '<span class="label '+cls+'" title="'+tip+'">'+b.level+'%'+chg+'</span>'+stale;
+}
 function renderDeviceRow(dev){
   const offline=dev.present?'':' <span class="label label-danger">离线</span>';
   const st=STATUS_MAP[dev.worker_status]||{t:dev.worker_status,c:'default'};
@@ -366,7 +385,7 @@ function renderDeviceRow(dev){
   const checked=_selectedSerials.has(dev.serial)?'checked':'';
   const rowCls=_selectedSerials.has(dev.serial)?'row-checked':'';
   const cb='<input type="checkbox" '+checked+' onclick="toggleDevice(\''+esc(dev.serial)+'\',this.checked)">';
-  return '<tr class="'+rowCls+'"><td class="col-cb">'+cb+'</td><td>'+devLabel+'</td><td>'+esc(dev.model)+'</td><td>'+wb+'</td><td>'+fg+'</td><td>'+prog+'</td><td>'+tname+retry+endInfo+'</td><td class="text-muted">'+esc(dev.current_action||'-')+warnInfo+'</td><td class="err-text" title="'+esc(dev.last_error||'')+'">'+esc(dev.last_error||'-')+'</td><td>'+btns+'</td></tr>';
+  return '<tr class="'+rowCls+'"><td class="col-cb">'+cb+'</td><td>'+devLabel+'</td><td>'+esc(dev.model)+'</td><td>'+_battCell(dev)+'</td><td>'+wb+'</td><td>'+fg+'</td><td>'+prog+'</td><td>'+tname+retry+endInfo+'</td><td class="text-muted">'+esc(dev.current_action||'-')+warnInfo+'</td><td class="err-text" title="'+esc(dev.last_error||'')+'">'+esc(dev.last_error||'-')+'</td><td>'+btns+'</td></tr>';
 }
 
 async function loadJobsForMonitor(){

static/admin/recorder.js

@@ -0,0 +1,418 @@
+// ================== 动作录制器 ==================
+// 在设备截图上操作（点/划/按键/输入），自动翻译成**步骤**：
+//   · 点  → 命中元素就记「点击元素」(选择器)，抓不到就退化成「点击坐标」(百分比)
+//   · 划  → 记**「录制手势」**：完整轨迹点列 [[x,y,t_ms],…]，**纯回放**，不再套滑动逻辑
+//   · 停顿 → 可选记成「等待」（按真实间隔 ±15%）
+//
+// 两个录制来源：
+//   · 网页上录：在这个窗口里按住鼠标拖（采样路径 + 时间）
+//   · 手机上录：点「手机上录」后**用手指在真机上划**——后端读 getevent 抓真触屏，
+//     录到的是人手的真实轨迹（比在网页上模拟更真）
+//
+// 两种用法（同一个窗口）：
+//   mode='action'  —— 录一段，存成「自定义动作」（进动作库，能拖进任何任务）
+//   mode='gesture' —— 录到的手势直接回填给调用方（步骤编辑器里的「录制手势」步骤）
+//
+// 元素树用 /api/uiauto/snapshot 一次取齐（截图 + 元素），**每次操作后自动刷新**，
+// 这样下一次点击就能用最新的树翻译选择器（抖音这种没有 id 的界面靠 text/desc）。
+
+let _rec = null;
+
+function _recEl() { return document.getElementById('rec-overlay'); }
+
+async function openRecorder(opts) {
+  opts = opts || {};
+  if (_recEl()) return;
+  _rec = {
+    mode: opts.mode || 'action',
+    serial: opts.serial || '',
+    onDone: opts.onDone || null,
+    steps: [],
+    elements: [],
+    devW: 0, devH: 0, imgURL: '',
+    lastTs: 0, dragFrom: null, busy: false, keepPause: true,
+    samples: [], phone: null, autoPhone: !!opts.autoStartPhone,
+    shots: 0, unstable: false,
+  };
+  const ov = document.createElement('div');
+  ov.id = 'rec-overlay';
+  ov.className = 'modal-overlay show';   // .modal-overlay 默认 display:none，必须带 show
+  ov.innerHTML =
+    '<div class="modal-box rec-box">' +
+      '<div class="rec-head">' +
+        '<b>' + (_rec.mode === 'gesture' ? '录制手势' : '录制动作') + '</b>' +
+        '<select id="rec-device" class="form-control" style="width:auto" onchange="recPickDevice()"></select>' +
+        '<button class="btn btn-sm" onclick="recRefresh()">刷新画面</button>' +
+        '<label class="form-check"><input type="checkbox" id="rec-pause" checked onchange="_rec.keepPause=this.checked"><span>记录停顿</span></label>' +
+        '<span style="flex:1"></span>' +
+        '<button class="btn btn-sm" onclick="closeRecorder()">关闭</button>' +
+      '</div>' +
+      '<div class="rec-body">' +
+        '<div class="rec-stage" id="rec-stage"><div class="rec-hint">正在取画面…</div></div>' +
+        '<div class="rec-side">' +
+          '<div class="rec-ops">' +
+            '<button class="btn btn-sm" onclick="recKey(\'back\')">返回</button>' +
+            '<button class="btn btn-sm" onclick="recKey(\'home\')">Home</button>' +
+            '<button class="btn btn-sm" onclick="recKey(\'recent\')">最近</button>' +
+            '<button class="btn btn-sm" onclick="recKey(\'enter\')">回车</button>' +
+          '</div>' +
+          '<div class="rec-row"><input id="rec-text" class="form-control" placeholder="要输入的文字">' +
+            '<button class="btn btn-sm" onclick="recText()">输入</button></div>' +
+          '<div class="rec-ops">' +
+            '<button class="btn btn-sm" onclick="recAddWait()">+ 等待</button>' +
+            '<button class="btn btn-sm" onclick="recClear()">清空</button>' +
+          '</div>' +
+          '<div class="rec-list-title">录到的步骤 <span id="rec-count" class="text-muted"></span></div>' +
+          '<div class="rec-list" id="rec-list"></div>' +
+          '<div class="rec-foot" id="rec-foot"></div>' +
+        '</div>' +
+      '</div>' +
+    '</div>';
+  ov.addEventListener('mousedown', function (e) { if (e.target === ov) closeRecorder(); });
+  document.body.appendChild(ov);
+  await recLoadDevices();
+  recRender();
+  if (_rec.autoPhone && _rec.serial) recStartPhone();
+}
+
+function closeRecorder() {
+  const ov = _recEl();
+  if (ov) ov.remove();
+  _rec = null;
+}
+
+async function recLoadDevices() {
+  const sel = document.getElementById('rec-device');
+  if (!sel) return;
+  sel.innerHTML = '<option value="">选择设备…</option>';
+  const r = await apiGet('/api/devices');
+  if (!r || !r.ok) return;
+  (r.items || []).forEach(function (d) {
+    const o = document.createElement('option');
+    o.value = d.serial;
+    o.textContent = d.name ? (d.name + '（' + d.serial + '）') : d.serial;
+    sel.appendChild(o);
+  });
+  if (_rec.serial) { sel.value = _rec.serial; }
+  else if ((r.items || []).length) { sel.value = r.items[0].serial; _rec.serial = r.items[0].serial; }
+  if (_rec.serial) { await recWake(); recRefresh(); }
+}
+
+async function recPickDevice() {
+  const sel = document.getElementById('rec-device');
+  _rec.serial = sel ? sel.value : '';
+  _rec.elements = [];
+  recRender();
+  if (_rec.serial) { await recWake(); recRefresh(); }
+}
+
+// 录制前先唤醒设备：**息屏时 u2 抓 UI 树会退化到几十秒**（实测 65s，唤醒后 3.3s），
+// 截图也是一片黑。唤醒是幂等的，多调一次没有副作用。
+async function recWake() {
+  if (!_rec || !_rec.serial) return;
+  try {
+    const r = await apiPost('/api/device/screen_all', { mode: 'on', serials: [_rec.serial] });
+    if (r && r.ok) await new Promise(function (z) { setTimeout(z, 800); });
+  } catch (e) { /* 唤醒失败也继续，用户自己会看到黑屏 */ }
+}
+
+// 取一张快照：截图 + 元素树（同一个连接背靠背取，避免框错位）
+async function recRefresh() {
+  if (!_rec || !_rec.serial) return;
+  const r = await apiGet('/api/uiauto/snapshot?serial=' + encodeURIComponent(_rec.serial));
+  if (!r || !r.ok) {
+    const st = document.getElementById('rec-stage');
+    if (st) st.innerHTML = '<div class="rec-hint">取画面失败：' + esc((r && r.error) || '未知错误') + '</div>';
+    return;
+  }
+  _rec.imgURL = r.image || '';
+  _rec.devW = r.width || 0;
+  _rec.devH = r.height || 0;
+  _rec.elements = r.elements || [];
+  _rec.unstable = !!r.unstable;
+  _rec.shots++;
+  recPaint();
+}
+
+function recPaint() {
+  const st = document.getElementById('rec-stage');
+  if (!st) return;
+  if (!_rec.imgURL) { st.innerHTML = '<div class="rec-hint">正在取画面…</div>'; return; }
+  st.innerHTML = '<img id="rec-img" src="' + _rec.imgURL + '" draggable="false">' +
+    (_rec.unstable ? '<div class="rec-warn">画面在变化，这次框可能不准</div>' : '');
+  const img = document.getElementById('rec-img');
+  img.addEventListener('mousedown', recDown);
+  img.addEventListener('mousemove', recMove);
+  img.addEventListener('mouseup', recUp);
+  img.addEventListener('mouseleave', function () { _rec.dragFrom = null; recPaintOverlay(); });
+  recPaintOverlay();
+}
+
+// 拖动中的轨迹提示（录制时能看见自己划到哪）
+function recPaintOverlay() {
+  const st = document.getElementById('rec-stage');
+  if (!st) return;
+  let cv = document.getElementById('rec-overlay-line');
+  if (!cv) {
+    cv = document.createElement('div');
+    cv.id = 'rec-overlay-line';
+    cv.className = 'rec-line';
+    st.appendChild(cv);
+  }
+  if (!_rec.dragFrom) { cv.style.display = 'none'; return; }
+  cv.style.display = 'block';
+  const a = _rec.dragFrom;
+  const b = _rec.dragTo || a;
+  const x = Math.min(a.x, b.x), y = Math.min(a.y, b.y);
+  cv.style.left = x + 'px'; cv.style.top = y + 'px';
+  cv.style.width = Math.abs(b.x - a.x) + 'px';
+  cv.style.height = Math.abs(b.y - a.y) + 'px';
+}
+
+function _recPos(e) {
+  const img = document.getElementById('rec-img');
+  if (!img) return null;
+  const r = img.getBoundingClientRect();
+  const x = e.clientX - r.left, y = e.clientY - r.top;
+  if (x < 0 || y < 0 || x > r.width || y > r.height) return null;
+  // 显示坐标 → 设备坐标
+  const sx = _rec.devW / r.width, sy = _rec.devH / r.height;
+  return { x: Math.round(x * sx), y: Math.round(y * sy), rx: x, ry: y, cssW: r.width, cssH: r.height };
+}
+
+function recDown(e) {
+  if (_rec.busy) return;
+  const p = _recPos(e);
+  if (!p) return;
+  _rec.dragFrom = p; _rec.dragTo = null; _rec.dragT0 = Date.now();
+  // 采样：拖动过程中把每个点连时间一起记下来（这就是"轨迹"）
+  _rec.samples = [[p.x, p.y, 0]];
+  recPaintOverlay();
+}
+
+function recMove(e) {
+  if (!_rec.dragFrom) return;
+  const p = _recPos(e);
+  if (!p) return;
+  _rec.dragTo = p;
+  const t = Date.now() - _rec.dragT0;
+  const last = _rec.samples[_rec.samples.length - 1];
+  if (!last || t - last[2] >= 8 || Math.abs(p.x - last[0]) + Math.abs(p.y - last[1]) >= 3) {
+    if (_rec.samples.length < 400) _rec.samples.push([p.x, p.y, t]);
+  }
+  recPaintOverlay();
+}
+
+async function recUp(e) {
+  if (!_rec.dragFrom || _rec.busy) { _rec.dragFrom = null; return; }
+  const a = _rec.dragFrom;
+  const b = _recPos(e) || a;
+  const durMs = Date.now() - _rec.dragT0;
+  _rec.dragFrom = null;
+  recPaintOverlay();
+  const dist = Math.hypot(b.x - a.x, b.y - a.y);
+  if (dist < 12 || durMs < 60) {          // 视为点击
+    _rec.samples = [];
+    await recTap(a.x, a.y);
+  } else {
+    const pts = _rec.samples.slice();
+    pts.push([b.x, b.y, durMs]);          // 末点补上（决定手势收尾位置）
+    _rec.samples = [];
+    recPushGesture(pts, 'web');
+    await recRefresh();
+  }
+}
+
+// 一条录到的轨迹 → 「录制手势」步骤（**纯回放**：点列+时长原样存下，不再套滑动逻辑）
+function recPushGesture(points, src) {
+  if (!points || points.length < 2) { showToast('没录到有效轨迹（太短了）', 'error'); return; }
+  if (_rec.mode === 'gesture') {          // 回填模式：直接交给调用方，收工
+    const cb = _rec.onDone;
+    closeRecorder();
+    if (cb) cb({ points: points, speed: 1.0 }, src);
+    return;
+  }
+  const dur = points[points.length - 1][2] || 0;
+  _recPush({ type: 'gesture',
+             label: '录制手势 ' + points.length + '点/' + (dur / 1000).toFixed(1) + 's',
+             params: { points: points, speed: 1.0 } });
+}
+
+// ---------- 手机端录制（getevent 抓真手指） ----------
+async function recStartPhone() {
+  if (!_rec.serial) { showToast('先选设备', 'error'); return; }
+  const r = await apiPost('/api/gesture/record/start', { serial: _rec.serial });
+  if (!r || !r.ok) { showToast((r && r.error) || '开始失败', 'error'); return; }
+  _rec.phone = { token: r.token, t0: Date.now() };
+  showToast('开始录制——现在用手指在手机上划', 'success');
+  recRenderFoot();
+}
+
+async function recStopPhone() {
+  if (!_rec.phone) return;
+  const token = _rec.phone.token;
+  _rec.phone = null;
+  const r = await apiPost('/api/gesture/record/stop', { token: token });
+  if (!r || !r.ok) { showToast((r && r.error) || '停止失败', 'error'); recRenderFoot(); return; }
+  const gs = r.gestures || [];
+  if (!gs.length) {
+    showToast('没录到手势——请在手机屏幕上用指划一下（不是点）', 'error');
+    recRenderFoot(); return;
+  }
+  if (_rec.mode === 'gesture') { recPushGesture(gs[gs.length - 1], 'phone'); return; }
+  gs.forEach(function (g) { recPushGesture(g, 'phone'); });
+  showToast('录到 ' + gs.length + ' 个手势', 'success');
+  recRenderFoot();
+  recRefresh();
+}
+
+// ---------- 翻译：点击 → 步骤 ----------
+function _recFindElement(x, y) {
+  // 取包含该点的最小元素；优先可点击的（和 /api/screen/tap 的 snap 同一口径）
+  let best = null, bestClick = null;
+  (_rec.elements || []).forEach(function (el) {
+    const m = (el.bounds || '').match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+    if (!m) return;
+    const x1 = +m[1], y1 = +m[2], x2 = +m[3], y2 = +m[4];
+    if (!(x1 <= x && x <= x2 && y1 <= y && y <= y2)) return;
+    const area = (x2 - x1) * (y2 - y1);
+    const cand = { el: el, area: area, cx: Math.round((x1 + x2) / 2), cy: Math.round((y1 + y2) / 2) };
+    if (!best || area < best.area) best = cand;
+    if (String(el.clickable) === 'true' && (!bestClick || area < bestClick.area)) bestClick = cand;
+  });
+  return bestClick || best;
+}
+
+async function recTap(x, y) {
+  if (!_rec || _rec.busy) return;
+  _rec.busy = true;
+  try {
+    const hit = _recFindElement(x, y);
+    let step;
+    if (hit && hit.el.suggested && hit.el.suggested.value) {
+      step = { type: 'click', label: '点击' + _recShort(hit.el),
+               params: { selector_type: hit.el.suggested.type || 'xpath',
+                         selector_value: hit.el.suggested.value, wait_timeout: 2 } };
+    } else {
+      step = { type: 'click_xy', label: '点击坐标',
+               params: { x: Math.round(x / _rec.devW * 100), y: Math.round(y / _rec.devH * 100) } };
+    }
+    _recPush(step);
+    const r = await apiPost('/api/screen/tap', { serial: _rec.serial, x: x, y: y, snap: 1 });
+    if (r && !r.ok) showToast((r.error || '点击失败'), 'error');
+    await recRefresh();
+  } finally { _rec.busy = false; }
+}
+
+function _recShort(el) {
+  const s = el.text || el.description || el.name || el.resource_id || '';
+  return s ? ('「' + String(s).slice(0, 12) + '」') : '';
+}
+
+async function recKey(key) {
+  if (!_rec || !_rec.serial) { showToast('先选设备', 'error'); return; }
+  _recPush({ type: 'key_event', label: '按键 ' + key, params: { key: key } });
+  const r = await apiPost('/api/screen/key', { serial: _rec.serial, key: key });
+  if (r && !r.ok) showToast((r.error || '按键失败'), 'error');
+  await recRefresh();
+}
+
+async function recText() {
+  if (!_rec || !_rec.serial) { showToast('先选设备', 'error'); return; }
+  const inp = document.getElementById('rec-text');
+  const t = (inp ? inp.value : '').trim();
+  if (!t) { showToast('先填要输入的文字', 'error'); return; }
+  _recPush({ type: 'input_text', label: '输入 ' + t.slice(0, 8),
+             params: { mode: 'fixed', fixed_text: t, clear_first: false } });
+  const r = await apiPost('/api/screen/text', { serial: _rec.serial, text: t });
+  if (r && !r.ok) showToast((r.error || '输入失败'), 'error');
+  if (inp) inp.value = '';
+  await recRefresh();
+}
+
+function recAddWait() {
+  _recPush({ type: 'wait', label: '等待', params: { min: 1, max: 3 } });
+}
+
+// 入列：按需自动补一条「等待」（真实停顿，±15%），并刷新列表
+function _recPush(step) {
+  const now = Date.now();
+  if (_rec.keepPause && _rec.lastTs && step.type !== 'wait') {
+    const gap = (now - _rec.lastTs) / 1000;
+    if (gap >= 1.0) {
+      _rec.steps.push({ id: 'rec_' + Math.random().toString(36).slice(2, 8),
+                        type: 'wait', label: '等待 ' + gap.toFixed(1) + 's',
+                        params: { min: +(gap * 0.85).toFixed(1), max: +(gap * 1.15).toFixed(1) } });
+    }
+  }
+  step.id = 'rec_' + Math.random().toString(36).slice(2, 8);
+  _rec.steps.push(step);
+  _rec.lastTs = now;
+  recRender();
+}
+
+function recClear() { _rec.steps = []; _rec.lastTs = 0; recRender(); }
+
+function recDel(i) { _rec.steps.splice(i, 1); recRender(); }
+function recMove2(i, d) {
+  const j = i + d;
+  if (j < 0 || j >= _rec.steps.length) return;
+  const t = _rec.steps[i]; _rec.steps[i] = _rec.steps[j]; _rec.steps[j] = t;
+  recRender();
+}
+
+function recRender() {
+  const list = document.getElementById('rec-list');
+  if (!list) return;
+  const steps = _rec ? _rec.steps : [];
+  document.getElementById('rec-count').textContent = steps.length ? ('共 ' + steps.length + ' 步') : '';
+  list.innerHTML = steps.map(function (s, i) {
+    return '<div class="rec-item"><span class="rec-idx">' + (i + 1) + '</span>' +
+      '<span class="rec-label">' + esc(s.label || s.type) + '</span>' +
+      '<span class="rec-ops2">' +
+      '<button class="btn btn-xs" onclick="recMove2(' + i + ',-1)" title="上移">↑</button>' +
+      '<button class="btn btn-xs" onclick="recMove2(' + i + ',1)" title="下移">↓</button>' +
+      '<button class="btn btn-xs btn-danger" onclick="recDel(' + i + ')">×</button>' +
+      '</span></div>';
+  }).join('') || '<div class="text-muted" style="font-size:12px;padding:6px 0">还没有录到步骤——在左边画面上点一下或划一下试试</div>';
+  recRenderFoot();
+}
+
+function recRenderFoot() {
+  const foot = document.getElementById('rec-foot');
+  if (!foot) return;
+  const steps = _rec.steps;
+  if (_rec.mode === 'gesture') {
+    // 回填模式：录到就立刻填回那个步骤，不用再点确认
+    foot.innerHTML = _rec.phone
+      ? '<button class="btn btn-danger" onclick="recStopPhone()">■ 停止并填入</button>'
+      : '<button class="btn btn-primary" onclick="recStartPhone()">● 手机上录</button>' +
+        '<div class="help">或在左边画面上按住鼠标拖一下——录到就立刻填进那一步</div>';
+    return;
+  }
+  const phoneBtn = _rec.phone
+    ? '<button class="btn btn-danger" onclick="recStopPhone()">■ 停止手机录制</button>'
+    : '<button class="btn btn-primary" onclick="recStartPhone()">● 手机上录</button>';
+  foot.innerHTML =
+    '<div class="rec-row" style="margin-bottom:6px">' + phoneBtn +
+    '<span class="help" style="margin:0">' + (_rec.phone
+      ? '正在录：请用手指在手机屏幕上划，划完点「停止」'
+      : '手机上用手指划 = 录真手指轨迹；在左边画面上拖 = 网页录制') + '</span></div>' +
+    '<div class="rec-row"><input id="rec-name" class="form-control" placeholder="动作名，如「抖音-进评论」">' +
+    '<button class="btn btn-primary" onclick="recSaveAsAction()">存成动作</button></div>' +
+    '<div class="help">划出来的每一段都是一条「录制手势」步骤（按原路径与时长回放，不再套滑动逻辑）</div>';
+}
+
+async function recSaveAsAction() {
+  const el = document.getElementById('rec-name');
+  const name = (el ? el.value : '').trim();
+  if (!name) { showToast('先给动作起个名', 'error'); return; }
+  const steps = _rec.steps.filter(function (s) { return s.type !== 'wait' || true; })
+    .map(function (s) { return { type: s.type, label: s.label, params: s.params }; });
+  if (!steps.length) { showToast('还没有录到步骤', 'error'); return; }
+  const r = await apiPost('/api/custom_actions', { name: name, icon: '⏺', steps: steps });
+  if (!r || !r.ok) { showToast((r && r.error) || '保存失败', 'error'); return; }
+  showToast('已存成动作「' + name + '」（' + steps.length + ' 步）', 'success');
+  if (typeof loadCustomActions === 'function') loadCustomActions();
+  closeRecorder();
+}

static/admin/steplog.js

@@ -0,0 +1,143 @@
+// ================== 「日志 → 步骤明细」子分栏 ==================
+// 数据源：task_step_log 表（结构化），接口 /api/step_logs*（见 web/admin_api.py）。
+// 与「文件日志」的分工：那边是原始文本，这边能按设备/任务/时间/结果过滤、能导出。
+
+let _slOffset = 0;        // 分页偏移
+let _slTotal = 0;         // 命中总数
+let _slRunId = '';        // "只看某次运行"时的 run_id（空 = 不限）
+let _slInited = false;    // 下拉选项只拉一次
+
+function _slVal(id){const el=document.getElementById(id);return el?el.value:'';}
+
+function _slParams(){
+  const p=new URLSearchParams();
+  const put=(k,v)=>{if(v)p.set(k,v);};
+  put('serial', _slVal('sl-device'));
+  put('job_id', _slVal('sl-job'));
+  put('result', _slVal('sl-result'));
+  put('q', _slVal('sl-q').trim());
+  put('since', _slVal('sl-since'));
+  put('until', _slVal('sl-until'));
+  put('run_id', _slRunId);
+  p.set('limit', _slVal('sl-limit')||200);
+  p.set('offset', _slOffset);
+  return p;
+}
+
+async function loadStepLogs(reset){
+  const body=document.getElementById('sl-body');
+  if(!body)return;
+  if(reset)_slOffset=0;
+  const p=_slParams();
+  const r=await apiGet('/api/step_logs?'+p.toString());
+  if(!r||!r.ok){body.innerHTML='<tr><td colspan="9" class="text-muted">读取失败</td></tr>';return;}
+  _slTotal=r.total||0;
+  const rows=r.rows||[];
+  body.innerHTML = rows.length ? rows.map(_slRowHtml).join('')
+    : '<tr><td colspan="9" class="text-muted">（没有匹配的步骤记录——先跑一个任务，'
+      +'或在上面放宽筛选条件）</td></tr>';
+  // 提示栏：分页位置 + 保留期 + 运行期间丢弃计数（排障用）
+  const from=_slTotal?(_slOffset+1):0, to=_slOffset+rows.length;
+  let hint=`命中 ${_slTotal} 条 · 显示 ${from}-${to}`;
+  if(_slRunId)hint=`只看运行 ${_slRunId} · `+hint;
+  const st=r.stats||{};
+  if(st.dropped)hint+=` · 队列溢出丢弃 ${st.dropped} 条`;
+  if(st.failed)hint+=` · 落库失败 ${st.failed} 条`;
+  document.getElementById('sl-hint').textContent=hint;
+  document.getElementById('sl-page').textContent=
+    `第 ${Math.floor(_slOffset/(parseInt(_slVal('sl-limit'),10)||200))+1} 页`;
+  document.getElementById('sl-prev').disabled = _slOffset<=0;
+  document.getElementById('sl-next').disabled = _slOffset+rows.length>=_slTotal;
+  if(!_slInited){_slInited=true;loadStepFilters();}
+  if(reset)loadStepRuns();
+}
+
+// 结果 → 颜色。注意不能复用 .log-err/.log-warn/.log-info：那套的作用域是
+// .log-content（文件日志面板），表格里得用下面这套 res-*
+const _SL_RESULT={error:'res-error',unknown:'res-error',miss:'res-miss',
+                  cap:'res-miss',skip:'res-skip',ok:'res-ok'};
+
+function _slRowHtml(r){
+  const cls=_SL_RESULT[r.result]||'';
+  const dev=esc(r.device_name||r.serial||'');
+  const dur=r.duration_ms>=1000?(r.duration_ms/1000).toFixed(1)+'s':(r.duration_ms||0)+'ms';
+  return '<tr>'
+    +'<td class="text-muted" style="white-space:nowrap">'+esc(r.created_at||'')+'</td>'
+    +'<td title="'+esc(r.serial||'')+'">'+dev+'</td>'
+    +'<td>'+esc(r.job_name||'')+'</td>'
+    +'<td>'+esc(r.step_path||'')+'</td>'
+    +'<td>'+esc(r.step_label||'')+'</td>'
+    +'<td class="text-muted">'+esc(r.step_type||'')+'</td>'
+    +'<td class="'+cls+'">'+esc(r.result||'')+'</td>'
+    +'<td class="text-muted">'+dur+'</td>'
+    +'<td class="text-muted" title="'+esc(r.detail||'')+'">'+esc(_slTrim(r.detail,120))+'</td>'
+    +'</tr>';
+}
+
+function _slTrim(s,n){s=s||'';return s.length>n?s.slice(0,n)+'…':s;}
+
+function stepLogPage(delta){
+  const size=parseInt(_slVal('sl-limit'),10)||200;
+  _slOffset=Math.max(0,_slOffset+delta*size);
+  loadStepLogs(false);
+}
+
+function resetStepFilters(){
+  ['sl-q','sl-since','sl-until'].forEach(id=>{const el=document.getElementById(id);if(el)el.value='';});
+  ['sl-device','sl-job','sl-result'].forEach(id=>{const el=document.getElementById(id);if(el)el.value='';});
+  _slRunId='';
+  loadStepLogs(true);
+}
+
+function downloadStepLogs(){
+  const p=_slParams();
+  p.delete('limit');p.delete('offset');
+  window.location='/api/step_logs/download?'+p.toString();
+}
+
+// ---------- 筛选下拉（只列"明细里真的出现过"的设备/任务） ----------
+async function loadStepFilters(){
+  const r=await apiGet('/api/step_logs/filters');
+  if(!r||!r.ok)return;
+  const dev=document.getElementById('sl-device');
+  const job=document.getElementById('sl-job');
+  const keep=(sel,val)=>{const cur=sel.value;sel.innerHTML=val;sel.value=cur;};
+  keep(dev,'<option value="">全部设备</option>'+(r.devices||[]).map(d=>
+    '<option value="'+esc(d.serial)+'">'+esc(d.device_name||d.serial)+'</option>').join(''));
+  keep(job,'<option value="">全部任务</option>'+(r.jobs||[]).map(j=>
+    '<option value="'+esc(j.job_id)+'">'+esc(j.job_name||j.job_id)+'</option>').join(''));
+  document.getElementById('sl-note').textContent=
+    `明细保留 ${r.keep_days} 天（超期自动清理）；单次运行最多记录 `
+    +`${r.max_rows_per_run} 条（无限循环任务不会写爆这张表）。`;
+}
+
+// ---------- 最近运行概览（点一行 = 只看那次运行） ----------
+async function loadStepRuns(){
+  const p=new URLSearchParams();
+  if(_slVal('sl-device'))p.set('serial',_slVal('sl-device'));
+  if(_slVal('sl-job'))p.set('job_id',_slVal('sl-job'));
+  if(_slVal('sl-since'))p.set('since',_slVal('sl-since'));
+  if(_slVal('sl-until'))p.set('until',_slVal('sl-until'));
+  p.set('limit','20');
+  const r=await apiGet('/api/step_logs/runs?'+p.toString());
+  const body=document.getElementById('sl-runs-body');
+  if(!r||!r.ok){body.innerHTML='';return;}
+  const runs=r.runs||[];
+  document.getElementById('sl-runs-summary').textContent=
+    `最近运行概览（${runs.length} 次，点「查看」只看那次）`;
+  body.innerHTML = runs.length ? runs.map(x=>'<tr>'
+    +'<td class="text-muted" style="white-space:nowrap">'+esc(x.started_at||'')+'</td>'
+    +'<td>'+esc(x.device_name||x.serial||'')+'</td>'
+    +'<td>'+esc(x.job_name||'')+'</td>'
+    +'<td>'+x.steps+'</td>'
+    +'<td class="'+(x.failures?'res-error':'text-muted')+'">'+(x.failures||0)+'</td>'
+    +'<td><button class="btn btn-sm" onclick="filterByRun(\''+esc(x.run_id)+'\')">查看</button></td>'
+    +'</tr>').join('')
+    : '<tr><td colspan="6" class="text-muted">（暂无运行记录）</td></tr>';
+}
+
+function filterByRun(runId){
+  _slRunId=runId||'';
+  document.getElementById('sl-runs-box').open=false;
+  loadStepLogs(true);
+}

static/admin/tasks.js

@@ -80,6 +80,128 @@ function _normalizeTaskEnv(env){
   };
 }
 
+// ================== 公共巡检（任务级，独立于步骤画布） ==================
+// 与后端 core/patrol.py 的 CHECKS/ACTIONS 一一对应；选项变动时两边一起改。
+// 存进任务 params.watchers，worker 在步骤之间穿插执行（见 core/patrol.py 模块注释）。
+const _PATROL_CHECKS=[
+  ['screen_off','屏幕熄灭',''], ['screen_on','屏幕亮着',''],
+  ['element_exists','元素存在','selector'], ['element_missing','元素不存在','selector'],
+  ['foreground_is','前台是该App','package'], ['foreground_not','前台不是该App','package'],
+];
+const _PATROL_ACTIONS=[
+  ['none','只发通知，不动设备'], ['screen_on','点亮屏幕'],
+  ['screen_off','熄灭屏幕'], ['stop_self','停止本设备任务'],
+];
+let _patrolItems=[];
+
+function patrolInit(items){
+  _patrolItems=(items||[]).filter(function(x){return x&&typeof x==='object';})
+    .map(function(x){return Object.assign({},x);});
+  patrolRender();
+}
+function patrolAdd(){
+  patrolSync();
+  _patrolItems.push({enabled:true,name:'',interval:60,check:'screen_off',selector_type:'xpath',
+                     selector_value:'',action:'screen_on',notify:true,
+                     title:'',message:'',cooldown:300});
+  patrolRender();
+}
+function patrolRemove(i){
+  patrolSync();
+  _patrolItems.splice(i,1);
+  patrolRender();
+}
+// DOM → 内存（重渲染前必须调，否则刚填的值会被覆盖）
+function patrolSync(){
+  const list=document.getElementById('patrol-list');
+  if(!list)return;
+  list.querySelectorAll('.patrol-card').forEach(function(card,i){
+    const w=_patrolItems[i]; if(!w)return;
+    const get=function(k){
+      const el=card.querySelector('[data-pk="'+k+'"]');
+      if(!el)return undefined;
+      return el.type==='checkbox'?el.checked:el.value;
+    };
+    ['name','check','action','selector_type','selector_value','title','message'].forEach(function(k){
+      const v=get(k); if(v!==undefined)w[k]=v;
+    });
+    ['interval','cooldown'].forEach(function(k){
+      const v=get(k); if(v!==undefined)w[k]=parseInt(v,10)||0;
+    });
+    ['enabled','notify'].forEach(function(k){
+      const v=get(k); if(v!==undefined)w[k]=v;
+    });
+  });
+}
+function patrolCollect(){
+  patrolSync();
+  return _patrolItems.map(function(w){
+    return {enabled:w.enabled!==false, name:(w.name||'').trim(), interval:parseInt(w.interval,10)||60,
+            check:w.check||'screen_off', selector_type:w.selector_type||'xpath',
+            selector_value:(w.selector_value||'').trim(), action:w.action||'none',
+            notify:w.notify!==false, title:(w.title||'').trim(), message:(w.message||'').trim(),
+            cooldown:parseInt(w.cooldown,10)||0};
+  });
+}
+// 检查项一变，条件行（选择器/包名）跟着换
+function patrolCheckChanged(sel){
+  const card=sel.closest('.patrol-card');
+  const need=(_PATROL_CHECKS.find(function(c){return c[0]===sel.value;})||[])[2]||'';
+  const row=card.querySelector('.patrol-cond');
+  row.style.display=need?'flex':'none';
+  const typeBox=row.querySelector('.patrol-seltype');
+  if(typeBox)typeBox.style.display=(need==='selector')?'block':'none';
+  const lb=row.querySelector('.patrol-vallabel');
+  if(lb)lb.textContent=(need==='package')?'前台包名':'选择器值';
+  const inp=row.querySelector('[data-pk="selector_value"]');
+  if(inp)inp.placeholder=(need==='package')?'如 com.ss.android.ugc.aweme':'如 点赞';
+}
+function patrolRender(){
+  const list=document.getElementById('patrol-list');
+  if(!list)return;
+  if(!_patrolItems.length){
+    list.innerHTML='<div class="text-muted" style="font-size:12px;padding:4px 0">（没有巡检项）</div>';
+    return;
+  }
+  list.innerHTML=_patrolItems.map(_patrolCardHtml).join('');
+}
+function _patrolCardHtml(w,i){
+  const need=(_PATROL_CHECKS.find(function(c){return c[0]===w.check;})||[])[2]||'';
+  const chkOpts=_PATROL_CHECKS.map(function(c){
+    return '<option value="'+c[0]+'"'+(w.check===c[0]?' selected':'')+'>'+c[1]+'</option>';}).join('');
+  const actOpts=_PATROL_ACTIONS.map(function(a){
+    return '<option value="'+a[0]+'"'+(w.action===a[0]?' selected':'')+'>'+a[1]+'</option>';}).join('');
+  const typeOpts=['xpath','description','text','resourceId','descriptionContains','className']
+    .map(function(t){return '<option value="'+t+'"'+(w.selector_type===t?' selected':'')+'>'+t+'</option>';}).join('');
+  return '<div class="patrol-card">'
+   +'<div class="patrol-row">'
+     +'<label class="form-check"><input type="checkbox" data-pk="enabled" '+(w.enabled!==false?'checked':'')+'><span>启用</span></label>'
+     +'<input class="form-control" data-pk="name" style="flex:1" placeholder="巡检名，如 熄屏点亮" value="'+esc(w.name||'')+'">'
+     +'<button class="btn btn-xs btn-danger" onclick="patrolRemove('+i+')">删除</button>'
+   +'</div>'
+   +'<div class="patrol-row">'
+     +'<div class="pg"><label>每隔(秒)</label><input type="number" class="form-control" data-pk="interval" value="'+(w.interval||60)+'" min="5"></div>'
+     +'<div class="pg"><label>检查</label><select class="form-control" data-pk="check" onchange="patrolCheckChanged(this)">'+chkOpts+'</select></div>'
+     +'<div class="pg"><label>命中后动作</label><select class="form-control" data-pk="action">'+actOpts+'</select></div>'
+     +'<div class="pg"><label>冷却(秒)</label><input type="number" class="form-control" data-pk="cooldown" value="'+(w.cooldown!=null?w.cooldown:300)+'" min="0"></div>'
+   +'</div>'
+   +'<div class="patrol-row patrol-cond" style="display:'+(need?'flex':'none')+'">'
+     +'<div class="pg patrol-seltype" style="display:'+(need==='selector'?'block':'none')+'"><label>选择器类型</label>'
+     +'<select class="form-control" data-pk="selector_type">'+typeOpts+'</select></div>'
+     +'<div class="pg" style="flex:1"><label class="patrol-vallabel">'+(need==='package'?'前台包名':'选择器值')+'</label>'
+     +'<input class="form-control" data-pk="selector_value" value="'+esc(w.selector_value||'')+'" placeholder="'
+     +(need==='package'?'如 com.ss.android.ugc.aweme':'如 点赞')+'"></div>'
+   +'</div>'
+   +'<div class="patrol-row">'
+     +'<label class="form-check"><input type="checkbox" data-pk="notify" '+(w.notify!==false?'checked':'')+'><span>命中发通知</span></label>'
+     +'<div class="pg" style="flex:1"><label>标题</label><input class="form-control" data-pk="title" value="'+esc(w.title||'')+'" placeholder="{device} 熄屏了"></div>'
+     +'<div class="pg" style="flex:2"><label>内容</label><input class="form-control" data-pk="message" value="'+esc(w.message||'')+'" placeholder="任务 {job} 在 {time} 发现 {screen}，已处理"></div>'
+   +'</div>'
+   +'<div class="help">占位符：{device} 设备名、{serial} 地址、{job} 任务名、{time} 时间、{app} 当前前台包名、'
+   +'{screen} 亮屏/熄屏（后两个要查设备，不用就别写）。冷却期内重复命中不会重复动作/通知，防刷屏</div>'
+   +'</div>';
+}
+
 // openTaskModal(jobId, prefill)
 //   jobId   —— 传 id = 编辑已有任务
 //   prefill —— AI 建任务的草稿：{task, notes, warnings}（服务端已校验，这里只预填给人核对）
@@ -179,6 +301,16 @@ function openTaskModal(jobId, prefill){
         '<div class="se-lib" id="se-lib"><div class="lib-title">操作库</div></div>'+
         '<div class="se-canvas" id="se-canvas"></div>'+
       '</div>'+
+    '</div>'+
+    // 公共巡检：任务级配置，**不在步骤画布里**（穿插执行，见 core/patrol.py）
+    '<div class="patrol-box" id="patrol-box">'+
+      '<div class="patrol-head">'+
+        '<span>公共巡检<span class="hint" style="margin-left:8px">可选：任务运行期间按间隔穿插检查，命中就动作 + 通知</span></span>'+
+        '<button class="btn btn-xs" onclick="patrolAdd()">＋ 添加巡检</button>'+
+      '</div>'+
+      '<div id="patrol-list"></div>'+
+      '<div class="help">和步骤的区别：步骤是"按顺序做完这一段"，巡检是"全程都要盯着的条件"（比如熄屏就点亮、掉到桌面就通知）。'+
+      '检查穿插在步骤之间执行，不额外抢设备；某一步耗时很长时，巡检最多晚那一步的时间。</div>'+
     '</div>';
 
   // AI 草稿的提醒/复核项：贴在步骤编辑器上方，别让人漏看
@@ -197,7 +329,9 @@ function openTaskModal(jobId, prefill){
   // AI 草稿用一个唯一 key：既避开 localStorage 里"新建任务"的旧草稿覆盖预填内容，
   // 又保留自动存草稿（保存成功时 saveTask 会 clearDraft 清掉它）。
   const draftKey=jobId||(pf?('ai:'+Date.now()):'');
-  _stepEditor.init(j.params&&j.params.steps?j.params.steps:[],j.params&&j.params.max_duration?j.params.max_duration:0,draftKey);
+  _stepEditor.init(j.params&&j.params.steps?j.params.steps:[],j.params&&j.params.max_duration?j.params.max_duration:0,draftKey,
+    null,null,{dedup_reset:(j.params&&j.params.dedup_reset)||'day',dedup_hours:(j.params&&j.params.dedup_hours)||6});
+  patrolInit(j.params&&j.params.watchers);
 
   document.getElementById('modal-footer').innerHTML=
     '<button class="btn" onclick="closeModal()">取消</button>'+
@@ -285,6 +419,8 @@ function onTaskTypeChange(){
   const isGeneric=tt==='generic_steps';
   document.getElementById('step-editor').classList.toggle('show',isGeneric);
   document.getElementById('f-params_wrap').style.display=isGeneric?'none':'block';
+  const pb=document.getElementById('patrol-box');
+  if(pb)pb.style.display=isGeneric?'block':'none';   // 巡检只对通用步骤任务有意义
 }
 
 // ================== 自定义动作管理 ==================
@@ -368,3 +504,103 @@ function closeActionModal(){
   document.getElementById('action-modal-overlay').classList.remove('show');
 }
 
+
+// ================== 动作配置：步骤默认值 ==================
+// 存 app_meta.step_defaults（见 core/step_defaults.py）；只影响**之后新建**的步骤。
+const _CFG_LABELS = {
+  swipe: '滑动', click: '点击元素', long_click: '长按元素', wait: '等待',
+  key_event: '按键', input_text: '输入文字',
+};
+const _CFG_FIELD_LABELS = {
+  direction: '方向', duration_min: '最短时长(秒)', duration_max: '最长时长(秒)',
+  distance_ratio: '幅度(屏占比)', jitter: '抖动幅度', humanize: '拟人轨迹',
+  wait_timeout: '等待超时(秒)', duration: '长按时长(秒)', min: '最短(秒)',
+  max: '最长(秒)', key: '按键', mode: '输入模式', texts: '候选文案(每行一条)',
+  fixed_text: '固定文字', clear_first: '输入前清空',
+};
+const _CFG_DIR_LABELS = {up:'上滑', down:'下滑', left:'左滑', right:'右滑'};
+let _cfgPayload = null;
+
+// 取一次步骤默认值缓存在 _stepDefaults（editor.js 的 _makeStep 用它预填新步骤）
+async function loadStepDefaults(force) {
+  if (_stepDefaults && !force) return _stepDefaults;
+  const r = await apiGet('/api/step_defaults');
+  _stepDefaults = (r && r.ok) ? (r.defaults || {}) : {};
+  return _stepDefaults;
+}
+
+async function loadActionConfig(force) {
+  const box = document.getElementById('cfg-forms');
+  if (!box) return;
+  if (_cfgPayload && !force) { renderStepDefaults(); return; }
+  box.innerHTML = '<div class="text-muted" style="padding:10px">加载中…</div>';
+  const r = await apiGet('/api/step_defaults');
+  if (!r || !r.ok) { box.innerHTML = '<div class="text-muted" style="padding:10px">加载失败</div>'; return; }
+  _cfgPayload = r;
+  _stepDefaults = r.defaults || {};      // 编辑器新建步骤时预填用
+  renderStepDefaults();
+}
+
+function renderStepDefaults() {
+  const box = document.getElementById('cfg-forms');
+  if (!box || !_cfgPayload) return;
+  const d = _cfgPayload.defaults || {}, kinds = _cfgPayload.kinds || {}, spec = _cfgPayload.spec || {};
+  box.innerHTML = Object.keys(d).map(function (st) {
+    const fields = Object.keys(kinds[st] || {}).map(function (k) {
+      const kind = kinds[st][k], v = d[st][k], rule = spec[st] ? spec[st][k] : null;
+      let inp;
+      if (kind === 'bool') {
+        inp = '<label class="form-check"><input type="checkbox" data-st="' + st + '" data-k="' + k + '"' +
+              (v ? ' checked' : '') + '><span>' + (_CFG_FIELD_LABELS[k] || k) + '</span></label>';
+        return inp;
+      }
+      if (kind === 'choice') {
+        inp = '<select class="form-control" data-st="' + st + '" data-k="' + k + '">' +
+              (rule || []).map(function (o) {
+                const lab = _CFG_DIR_LABELS[o] || (o === 'random' ? '随机' : o === 'fixed' ? '指定' : o);
+                return '<option value="' + esc(o) + '"' + (v === o ? ' selected' : '') + '>' + esc(lab) + '</option>';
+              }).join('') + '</select>';
+      } else if (kind === 'num') {
+        inp = '<input type="number" class="form-control" data-st="' + st + '" data-k="' + k + '" value="' + esc(v) +
+              '" step="0.05" min="' + (rule ? rule[0] : '') + '" max="' + (rule ? rule[1] : '') + '">';
+      } else if (k === 'texts') {
+        inp = '<textarea class="form-control" rows="3" data-st="' + st + '" data-k="' + k + '">' + esc(v) + '</textarea>';
+      } else {
+        inp = '<input type="text" class="form-control" data-st="' + st + '" data-k="' + k + '" value="' + esc(v) + '">';
+      }
+      return '<div class="pg"><label>' + (_CFG_FIELD_LABELS[k] || k) + '</label>' + inp + '</div>';
+    }).join('');
+    return '<div class="cfg-card"><h4>' + (_CFG_LABELS[st] || st) + ' <span class="text-muted" style="font-weight:400">' + st + '</span></h4>' +
+           '<div class="cfg-row">' + fields + '</div></div>';
+  }).join('');
+  document.getElementById('cfg-hint').textContent = '';
+}
+
+function collectStepDefaults() {
+  const out = {};
+  document.querySelectorAll('#cfg-forms [data-st]').forEach(function (el) {
+    const st = el.dataset.st, k = el.dataset.k;
+    out[st] = out[st] || {};
+    if (el.type === 'checkbox') out[st][k] = el.checked;
+    else if (el.type === 'number') out[st][k] = parseFloat(el.value);
+    else out[st][k] = el.value;
+  });
+  return out;
+}
+
+async function saveStepDefaults() {
+  const r = await apiPost('/api/step_defaults', { defaults: collectStepDefaults() });
+  if (!r || !r.ok) { showToast((r && r.error) || '保存失败', 'error'); return; }
+  _cfgPayload = r;
+  _stepDefaults = r.defaults || {};
+  showToast('默认值已保存（只影响之后新建的步骤）', 'success');
+  document.getElementById('cfg-hint').textContent = '已保存 ' + new Date().toLocaleTimeString();
+  renderStepDefaults();
+}
+
+function resetStepDefaults() {
+  if (!_cfgPayload) return;
+  if (!confirm('恢复成出厂默认？（只影响这张表单，点「保存默认值」才真正生效）')) return;
+  _cfgPayload.defaults = JSON.parse(JSON.stringify(_cfgPayload.factory || {}));
+  renderStepDefaults();
+}

static/admin/tools.js

@@ -43,6 +43,7 @@ async function loadToolsDevices(force){
 
 // ================== 设备自动发现（扫描 → 待连接池 → 确认） ==================
 function loadDiscovery(){
+  loadBattery();   // 电量监控与发现同住一个子面板，跟着它的 10s 轮询一起刷新状态行
   apiGet('/api/devices/discovery').then(r=>{
     if(!r||!r.ok)return;
     const status=document.getElementById('discovery-status');
@@ -116,6 +117,62 @@ function loadDiscovery(){
     }
   });
 }
+// ================== 设备电量监控（定时采集 + 低电量告警） ==================
+// 电量本身随 /api/status 下发（监控页电量列 / 大屏卡片），这里只管配置与采集器状态。
+let _batteryLoaded=false;   // 表单只回填一次：10s 轮询不能把用户正在输的值冲掉
+
+function loadBattery(){
+  apiGet('/api/devices/battery').then(r=>{
+    if(!r||!r.ok)return;
+    const en=document.getElementById('battery-enabled');
+    if(!en)return;                                   // 面板不在页面上
+    const s=r.settings||{};
+    if(!_batteryLoaded){
+      en.checked=!!s.enabled;
+      document.getElementById('battery-low').value=s.low;
+      document.getElementById('battery-critical').value=s.critical;
+      document.getElementById('battery-skip-charging').checked=!!s.skip_charging;
+      document.getElementById('battery-interval').value=s.interval;
+      _batteryLoaded=true;
+    }
+    const st=document.getElementById('battery-status');
+    if(r.scanning)st.textContent='采集中...';
+    else if(r.last_scan)st.textContent='上次采集 '+r.last_scan[0]+' · 成功 '+r.last_scan[1]+'/'+r.last_scan[2]+' 台';
+    else st.textContent='尚未采集';
+  });
+}
+
+function saveBatterySettings(){
+  const body={
+    enabled:document.getElementById('battery-enabled').checked,
+    low:document.getElementById('battery-low').value,
+    critical:document.getElementById('battery-critical').value,
+    skip_charging:document.getElementById('battery-skip-charging').checked,
+    interval:document.getElementById('battery-interval').value,
+  };
+  apiPost('/api/devices/battery/settings',body).then(r=>{
+    if(!r||!r.ok){showToast('保存失败: '+((r&&r.error)||''),'error');return;}
+    showToast(r.msg||'已保存','success');
+    // 回填后端钳制后的真实值（填 999 会被钳到 100，严重阈值高于低电量会被压回来）
+    const s=r.settings;
+    if(s){
+      document.getElementById('battery-low').value=s.low;
+      document.getElementById('battery-critical').value=s.critical;
+      document.getElementById('battery-interval').value=s.interval;
+    }
+  });
+}
+
+function scanBatteryNow(){
+  apiPost('/api/devices/battery/scan',{}).then(r=>{
+    if(r&&r.ok){
+      showToast(r.msg||'采集已启动','success');
+      setTimeout(loadBattery,3000);
+      if(typeof loadMonitor==='function')setTimeout(loadMonitor,3000);   // 监控页设备表跟着更新
+    }else showToast('采集失败: '+((r&&r.error)||''),'error');
+  });
+}
+
 function reconnectPoolDev(serial){
   apiPost('/api/devices/discovery/reconnect',{serial}).then(r=>{
     if(r&&r.ok){
@@ -504,7 +561,7 @@ async function loadDevPool(){
         '<button class="btn btn-xs" onclick="togglePoolDev(\''+esc(d.serial)+'\','+(!d.enabled)+')">'+(d.enabled?'停用':'启用')+'</button> '+
         '<button class="btn btn-xs btn-danger" onclick="removePoolDev(\''+esc(d.serial)+'\')">删除</button>'+
       '</td></tr>';
-  }).join('')||'<tr><td colspan="8" class="empty">设备池为空，添加第一台设备开始</td></tr>';
+  }).join('')||'<tr><td colspan="9" class="empty">设备池为空，添加第一台设备开始</td></tr>';
 }
 
 async function addPoolDev(){

tasks/base.py

@@ -49,8 +49,8 @@
                from .actions import get_action_class
                return get_action_class(action_type)
 
-           def create_worker(self, serial, params):
-               return MyWorker(serial, params=params)
+           def create_worker(self, serial, params, ctx=None):
+               return MyWorker(serial, params=params, ctx=ctx)
 
   5. 在 my_task/__init__.py 加：from . import task  （触发注册）
   6. 在 tasks/__init__.py 加：from .my_task import task  （触发注册）
@@ -85,8 +85,12 @@ class BaseTask:
     description = ""
     default_params = {}
 
-    def create_worker(self, serial, params):
-        """返回一个 threading.Thread（已启动或待启动），执行实际任务。"""
+    def create_worker(self, serial, params, ctx=None):
+        """返回一个 threading.Thread（已启动或待启动），执行实际任务。
+
+        ctx：本次运行的上下文（`run_id`/`job_id`/`job_name`/`device_name`），
+        由 TaskManager 传入，供步骤明细等结构化记录标注来源；可为 None。
+        """
         raise NotImplementedError
 
     @classmethod

tasks/generic/publish_flow.py

@@ -0,0 +1,385 @@
+"""发布计划的执行原语：**把视频推到手机**、抓分享链接、清理手机上的素材。
+
+**分工**（用户定的）：平台只负责"素材到手机 + 状态记账"，
+**抖音里怎么发（打开→点+→相册→下一步→填文案→发布）由用户在任务画布里自己写步骤** ——
+所以这里**没有**写死的抖音发布流程，只有三个原语 + 一段编排：
+
+```
+push_one()            取计划 → 原子占位 → adb push 到指定目录 → 触发相册刷新
+                      → 把标题写进剪贴板（供后面的「粘贴」步骤直接用）
+capture_share_link()  进「我 → 作品」第一条 → 分享 → 复制链接 → 读剪贴板 → 抠出 v.douyin.com 链接
+clean_phone_video()   删手机上的素材（**精确路径**，绝不 rm 通配）
+```
+
+任务步骤（`task.py`）：
+  · 「推送发布视频」`push_release` —— 调 `push_one()`
+  · 「标记发布结果」`mark_release` —— 用户在自己的发布流程末尾调用，回写状态（可顺带抓链接）
+
+⚠ **失败阶段决定落 `failed` 还是 `unknown`**（见 `core/video_plan.STAGE_STATUS`）：
+推送阶段失败=还没碰抖音 → `failed`（可安全重试）；推送完成后（stage=`post`）出的岔子
+→ `unknown`（**可能已经发出去了，绝不自动重试**）。
+"""
+import os
+import re
+import time
+
+from core.logger import get_logger
+
+_log = get_logger("task.publish")
+
+# 相册目录：**DCIM/Camera**（用户定的）。
+# ⚠ 实测踩过的两件事：
+#   ① 相册（含抖音的选视频页）读的是 **MediaStore 索引**，`adb push` 只放文件、不进索引
+#      → 推完必须触发一次扫描（见 scan_media），否则"推送成功但相册里没有"。
+#   ② 推到自建子目录 `/sdcard/DCIM/rp` 时，MIUI 会把它归进「其他相册」，
+#      抖音的选视频页看不顺眼 —— 干脆放官方相机目录，哪儿都列得出来。
+# 放 Camera 的代价：用户自己拍的视频也在这个目录里 → **必须靠"刚推的排最前"来定位它**
+#   → 所以推完要 `touch` 把手机上那个文件的 mtime 改成"现在"（adb push 会保留**本地**修改时间，
+#     推一个 3 天前上传的素材，在按时间排序的相册里就排不到最前面 —— 实测踩过）。
+ALBUM_DIR = "/sdcard/DCIM/Camera"
+SCAN_WAIT = 2.0          # 媒体扫描后等相册刷新（真机实测再调）
+# 平台**曾经用过**的推送目录：推送前把同一计划在别处的旧副本清掉（历史遗留 + 换目录后的残留）。
+# 不清的后果实测过：相册里同一个 plan id 出现 2~3 个同名视频，"点第一个"点到的可能是指向
+# 已删文件的老记录 —— 这正是"相册里选错视频"的来源。
+KNOWN_ALBUM_DIRS = ("/sdcard/DCIM/Camera", "/sdcard/DCIM/rp", "/sdcard/Movies/rp")
+
+
+def _norm_path(p):
+    """路径归一化，用于比对：去掉引号、`/storage/emulated/0` 与 `/sdcard` 等价、统一小写。
+
+    ⚠ 大小写不是洁癖：MediaStore 的 `_data` 返回的是 **`/storage/emulated/0/dcim/rp/...`**
+    （目录部分被小写了），而我们写的是 `/sdcard/DCIM/...` —— 直接字符串比对永远不相等。
+    """
+    s = (p or "").strip().strip("'\"")
+    s = s.replace("/storage/emulated/0", "/sdcard").replace("/storage/self/primary", "/sdcard")
+    return s.lower()
+
+
+def _log_of(log):
+    return log or (lambda s: _log.info(s))
+
+
+def _sh(d, cmd):
+    """跑一条 shell 并**拿回文本**。
+
+    uiautomator2 3.x 的 `d.shell()` 返回 `ShellResponse`（**tuple 子类**，字段 .output/.exit_code），
+    不是 str —— 直接 `'abc' in resp`（元组成员判断，恒 False）或 `resp.strip()`（没有这方法）
+    都会得到错误结果。实测踩过：推送后的"文件大小校验"永远不通过、
+    "有没有进相册"永远报没进 —— 全是这一步读错了。统一走这里取文本。
+    """
+    r = d.shell(cmd)
+    out = getattr(r, "output", None)          # u2 3.x
+    if out is None:
+        out = r if isinstance(r, str) else str(r)   # 老版本 u2 / 异常返回
+    return (out or "").strip()
+
+
+# ================== 原语 ==================
+def push_video(d, serial, local_path, plan_id, album_dir=ALBUM_DIR, ext=""):
+    """把平台素材推到手机相册目录，并把手机上的时间改成"现在"。返回 (remote_path, error)。
+
+    改时间是为了**排序**：相册/抖音的选素材页按时间倒序，
+    `adb push` 保留的是**本地文件的修改时间**（推一个 3 天前上传的素材 → 排在很后面），
+    那"点第一个缩略图 = 刚推的那个"就不成立、可能点到别的素材。所以推完 `touch` 一下。
+
+    `ext` 默认**从本地文件名上取**（视频/图片各带各的扩展名）—— 抖音是按扩展名/MIME
+    判断这是视频还是图片的，把图片推成 `xxx.mp4`，相册里就成了一段坏视频。
+    """
+    ext = (ext or os.path.splitext(local_path)[1] or ".mp4").lower()
+    remote = f"{album_dir}/{plan_id}{ext}"
+    try:
+        local_size = os.path.getsize(local_path)
+        _sh(d, f"mkdir -p {album_dir}")
+        if hasattr(d, "push"):
+            d.push(local_path, remote)
+        else:                                   # 老版本 u2 兜底
+            from core.adb_helper import _adb
+            out = _adb("-s", serial, "push", local_path, remote)
+            if "error" in (out or "").lower():
+                return "", f"adb push 失败: {out[:120]}"
+        # 校验：**比对大小列**（不是"输出里有没有这个数字"—— 那种子串匹配会把日期里的
+        # 数字也当命中；u2 的 ShellResponse 更会让它恒不通过，见 _sh 的注释）
+        info = _sh(d, f"ls -l '{remote}'")
+        got = _remote_size(info)
+        if got is None:
+            return "", f"推上去的文件找不到: {info[:120] or '（ls 无输出）'}"
+        if got != local_size:
+            return "", f"推上去的文件大小不对: 本地 {local_size} / 手机 {got}"
+        # 排到最前：把手机上这个文件的 mtime 改成现在（改不动也不拦，只是排序可能不理想）
+        try:
+            _sh(d, f"touch '{remote}'")
+        except Exception as e:
+            _log.warning(f"touch 手机上的素材失败（排序可能不理想）: {e}")
+        drop_old_copies(d, plan_id, keep=remote, ext=ext)   # 老目录里的同名副本顺手清掉
+        return remote, ""
+    except Exception as e:
+        return "", f"推文件异常: {type(e).__name__}: {str(e)[:120]}"
+
+
+def _remote_size(ls_out):
+    """从 `ls -l` 输出里取**大小列**（字节）。取不到返回 None。
+
+    MIUI 的 toybox 输出形如 `-rw-rw---- 1 u0_a163 media_rw 15405006 2026-09-25 08:42 /sdcard/...`。
+    判据两道：① 行首是文件类型字符（`-`/`d`/`l`…）—— 挡住 "No such file" 这类错误行；
+    ② 第 5 列是纯数字 —— 大小列就在那（`ls -l` 一定有 size 列，第 4 列是 owner）。
+    比"输出里有没有这个数字"这种子串匹配可靠得多（后者会被日期/权限里的数字骗到）。
+    """
+    for line in (ls_out or "").splitlines():
+        parts = line.split()
+        if len(parts) >= 6 and parts[0][:1] in "-dlcbps" and parts[4].isdigit():
+            return int(parts[4])
+    return None
+
+
+def _indexed_paths(d, name):
+    """这个文件名在相册索引里对应哪些路径（MediaStore 的 `_data` 列表）。"""
+    query = ("content query --uri content://media/external/video/media --user 0 "
+             f"--projection _id:_display_name:_data --where \"_display_name='{name}'\"")
+    out = _sh(d, query)
+    return [m.group(1) for m in re.finditer(r"_data=(\S+)", out or "")]
+
+
+def scan_media(d, remote):
+    """触发相册刷新，并**按路径**验证它真的进了相册索引。
+
+    返回 `(verify, detail)`：`verify` ∈ `ok`（**这个路径**在索引里）/ `no_index`（扫完还是查不到）。
+
+    ⚠ 为什么要验证：相册读的是 MediaStore 索引，`adb push` 只是放文件 ——
+    推成功但相册看不到是个**静默失败**（"点了第一个缩略图结果点到别的东西"就是这么来的）。
+    ⚠ **必须比路径而不是比文件名**：同一个 plan id 可能在老目录里还留着同名副本
+    （实测 A01 上 `Movies/rp` + `DCIM/rp` 各有一份），只比名字会把"老副本在索引里"
+    误判成"新文件已就绪" —— 相册里点第一个，点到的是那份指向旧文件的记录。
+    ⚠ 命令只用**实测有效**的那两条：Android 12 上 `am broadcast MEDIA_SCANNER_SCAN_FILE`
+    已基本无效（返回 result=0 但什么也不做），真正干活的是 `content call … scan_file`；
+    老写法里那条 `MEDIA_MOUNTED` 广播在新系统上无效、还可能触发全盘重扫，已去掉。
+    """
+    for cmd in (f"content call --uri content://media/external/file --method scan_file --arg '{remote}'",
+                f"am broadcast -a android.intent.action.MEDIA_SCANNER_SCAN_FILE -d file://{remote}"):
+        try:
+            _sh(d, cmd)
+        except Exception as e:
+            _log.warning(f"媒体扫描命令失败（继续）: {e}")
+    time.sleep(SCAN_WAIT)
+    name = remote.split("/")[-1]
+    want = _norm_path(remote)
+    others = []
+    for _ in range(3):          # 索引有时慢半拍，给它一秒再查两次
+        try:
+            paths = _indexed_paths(d, name)
+            if any(_norm_path(p) == want for p in paths):
+                return "ok", f"已进相册索引（{remote}）"
+            others = [p for p in paths if _norm_path(p) != want]
+        except Exception as e:
+            _log.warning(f"查相册索引失败（当作没进）: {e}")
+            break
+        time.sleep(1)
+    if others:
+        _log.warning(f"⚠ 相册索引里只有**同名但不同路径**的记录：{others[:2]} ——"
+                     f"这个文件本身（{remote}）还没进索引")
+    _log.warning(f"⚠ 文件已推到 {remote}，但**没进相册索引**（相册里可能看不到它）——"
+                 f"推送目录 {ALBUM_DIR} 或系统抓取策略可能要调整，见 doc/TASK_DEV.md §4.7")
+    return "no_index", "扫完仍没进相册索引（相册里可能看不到它）"
+
+
+def drop_old_copies(d, plan_id, keep, ext=".mp4"):
+    """（`ext` 由 `push_video` 按素材真实扩展名传进来：视频/图片各删各的旧副本）"""
+    """把**同一个计划**在平台用过别的目录里的旧副本删掉（精确文件名，绝不通配）。
+
+    为什么要删：换了推送目录之后，老目录里的同名副本还在相册里（实测一个 plan id 躺了 3 份），
+    "点第一个缩略图 = 刚推的那个"就不成立了。删完顺手扫一下，让相册索引把那行去掉。
+    """
+    gone = []
+    for adir in KNOWN_ALBUM_DIRS:
+        old = f"{adir}/{plan_id}{ext}"
+        if _norm_path(old) == _norm_path(keep):
+            continue
+        try:
+            if _remote_size(_sh(d, f"ls -l '{old}'")) is None:
+                continue
+            _sh(d, f"rm -f '{old}'")
+            _sh(d, f"content call --uri content://media/external/file --method scan_file --arg '{old}'")
+            gone.append(old)
+        except Exception as e:
+            _log.warning(f"清旧副本失败（不影响本次推送）: {old}: {e}")
+    if gone:
+        _log.info(f"已清掉同一计划在旧目录里的副本: {gone}")
+    return gone
+
+
+def verify_pushed(d, remote):
+    """**推送后的一致性检查**：文件在不在 + 进没进相册索引。返回 (verify, detail)。
+
+    `verify` ∈ `ok` / `no_index` / `nofile`。**这是"推送成功"的判据**：
+    只看文件在不在是不够的 —— 后面的步骤要在相册里点它。
+    """
+    size = _remote_size(_sh(d, f"ls -l '{remote}'"))
+    if size is None:
+        return "nofile", "手机上找不到这个文件"
+    return scan_media(d, remote)
+
+
+def clean_phone_video(d, remote):
+    """删手机上的素材（**精确路径**，绝不通配 —— 通配会删掉用户自己拍的东西）。"""
+    if not remote:
+        return False
+    try:
+        _sh(d, f"rm -f '{remote}'")
+        if _remote_size(_sh(d, f"ls -l '{remote}'")) is not None:
+            _log.warning(f"手机上的素材没删掉: {remote}")
+            return False
+        return True
+    except Exception as e:
+        _log.warning(f"删手机素材异常（不影响发布结论）: {e}")
+        return False
+
+
+def _first_album_item(d):
+    """点相册/作品网格里的**第一个**缩略图（抖音按时间倒序，最新的在最前）。
+
+    不用固定坐标：dump 出网格里的图片单元，按 (y, x) 排序取第一个 ——
+    分辨率/刘海不同的机器都能用。仅用于**抓分享链接**（进「我」的作品第一条）。
+    """
+    try:
+        xml = d.dump_hierarchy()
+    except Exception as e:
+        return False, f"dump 失败: {e}"
+    cells = []
+    for m in re.finditer(r"<node[^>]*>", xml):
+        tag = m.group(0)
+
+        def g(k):
+            mm = re.search(k + r'="([^"]*)"', tag)
+            return mm.group(1) if mm else ""
+        bounds = g("bounds")
+        mb = re.match(r"\[(\d+),(\d+)\]\[(\d+),(\d+)\]", bounds)
+        if not mb:
+            continue
+        x0, y0, x1, y1 = (int(v) for v in mb.groups())
+        if y0 < 200 or (y1 - y0) < 120 or (x1 - x0) < 120:
+            continue
+        cells.append((y0, x0, (x0 + x1) // 2, (y0 + y1) // 2))
+    if not cells:
+        return False, "没找到缩略图"
+    cells.sort()
+    d.click(cells[0][2], cells[0][3])
+    return True, f"点了第一个缩略图 ({cells[0][2]},{cells[0][3]})"
+
+
+def _click_any(d, sels, timeout=3):
+    """按顺序试几个选择器（形如 "text=分享" / "descriptionContains=分享"），点中即返回。"""
+    for sel in sels:
+        try:
+            key, val = sel.split("=", 1)
+            el = d(**{key: val})
+            if el.exists(timeout=timeout):
+                el.click()
+                return True, sel
+        except Exception:
+            continue
+    return False, ""
+
+
+def capture_share_link(d, serial, timeout=30):
+    """抓作品的分享链接：我 → 作品第一条 → 分享 → 复制链接 → 读剪贴板。
+
+    返回 (url, msg)。**抓不到不算失败**：链接空着，界面上标"缺链接"、素材文件不删。
+    ⚠ 这一段仍是抖音 UI 流程，**按文字定位、需真机确认**；抖音改版就走不通。
+    """
+    from core.video_plan import extract_share_url
+    from core.clipboard_helper import inject_clipboard
+    try:
+        _click_any(d, ["descriptionContains=我", "text=我"], timeout=4)
+        time.sleep(2)
+        ok, msg = _first_album_item(d)
+        if not ok:
+            return "", f"进作品页失败: {msg}"
+        time.sleep(2.5)
+        ok, sel = _click_any(d, ["descriptionContains=分享", "text=分享"], timeout=4)
+        if not ok:
+            return "", "没找到「分享」按钮"
+        time.sleep(1.5)
+        ok, sel = _click_any(d, ["text=复制链接", "text=复制"], timeout=4)
+        if not ok:
+            return "", "分享面板里没找到「复制链接」"
+        time.sleep(1.2)
+        try:
+            got = d.clipboard
+        except Exception as e:
+            return "", f"读剪贴板失败: {e}"
+        url = extract_share_url(got or "")
+        return (url, "ok") if url else ("", f"剪贴板里没有抖音链接: {str(got)[:60]!r}")
+    except Exception as e:
+        return "", f"抓链接异常: {type(e).__name__}: {str(e)[:100]}"
+
+
+# ================== 编排 ==================
+def push_one(serial, plan, opts=None, log=None):
+    """把一条计划的素材推到手机（**不发布**）。返回 (ok, msg)。
+
+    做四件事：原子占位（防多设备/重跑重复推）→ 推文件 → 触发相册刷新 →
+    （可选）把标题写进手机剪贴板，供你后面画的「粘贴」步骤直接用。
+
+    占位成功后把 `stage` 置成 `post` —— 意思是"**后面的事不归平台管了**"：
+    再出岔子（比如你标记失败）按 `unknown` 处理，而不是"可安全重试"，
+    避免任务把一条你其实已经发出去的计划又推一遍、又发一遍。
+    """
+    opts = opts or {}
+    log = _log_of(log)
+    import uiautomator2 as u2
+    from core import video_plan as vp
+
+    plan_id = plan["id"]
+    if not vp.claim(plan_id, status=vp.ST_PUSHING, stage=vp.STAGE_MANUAL):
+        return False, "这条已被别的任务/设备领走了（跳过）"
+    d = None
+    try:
+        local = vp._video_path(plan.get("video_file"))
+        if not local or not os.path.exists(local):
+            vp.mark_failed(plan_id, "push", "平台上的素材文件不在了（可能已被清理，要发请重传视频）")
+            return False, "平台素材缺失"
+        d = u2.connect(serial)
+        remote, err = push_video(d, serial, local, plan_id,
+                                 album_dir=opts.get("album_dir") or ALBUM_DIR)
+        if err:
+            vp.mark_failed(plan_id, "push", err)
+            return False, err
+        log(f"素材已推到手机: {remote}")
+        verify, vmsg = verify_pushed(d, remote)
+        if verify == "nofile":
+            # 文件都不在 → 真失败（可重试），别往后走
+            vp.mark_failed(plan_id, "push", vmsg)
+            return False, f"推送校验失败：{vmsg}"
+        log(f"推送校验：{'✅ ' + vmsg if verify == 'ok' else '⚠ ' + vmsg}")
+        title = (plan.get("title") or "").strip()
+        if opts.get("to_clipboard", True) and title:
+            try:
+                from core.clipboard_helper import inject_clipboard
+                okc, msgc = inject_clipboard(serial, title, d=d)
+                log(f"标题已写进剪贴板（{'成功' if okc else '失败: ' + msgc}）"
+                    f"—— 后面用「粘贴」步骤就能填进抖音")
+            except Exception as e:
+                log(f"标题写剪贴板失败（不影响推送）: {e}")
+        vp.mark_pushed(plan_id, remote=remote, verify=verify, serial=serial,
+                       device_name=opts.get("device_name") or "")
+        return True, (f"已推送到手机：{remote}" if verify == "ok"
+                      else f"已推送到手机：{remote}（⚠ {vmsg}）")
+    except Exception as e:
+        vp.mark_failed(plan_id, "push", f"异常: {type(e).__name__}: {str(e)[:150]}")
+        return False, f"推送异常: {type(e).__name__}"
+    finally:
+        try:
+            row = vp.get_plan(plan_id)
+            if row and row["status"] == vp.ST_PUSHING and not row.get("stage") == vp.STAGE_MANUAL:
+                vp.mark_failed(plan_id, "push", "执行中断（兜底降级）")
+        except Exception:
+            pass
+
+
+def run_push(serial, plan_id, opts=None):
+    """给计划页「推送到手机」按钮用的入口（在后台线程里跑）。"""
+    from core import video_plan as vp
+    plan = vp.get_plan(plan_id)
+    if not plan:
+        _log.warning(f"推送：计划 {plan_id} 不存在")
+        return False, "计划不存在"
+    return push_one(serial, plan, opts)

templates/admin/monitor.html

@@ -112,7 +112,31 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 .log-content .log-err{color:#f87171}
 .log-content .log-warn{color:#fbbf24}
 .log-content .log-info{color:#67e8f9}
-.log-toolbar{display:flex;gap:10px;margin-bottom:12px;align-items:center}
+.log-row{white-space:pre-wrap}
+.log-cont{color:#8a94a6;padding-left:2.2em}   /* 续行（traceback 缩进行）：淡色缩进 */
+.log-hit{background:#fbbf2433}                /* 关键字命中高亮 */
+
+/* 「公共巡检」配置块（任务编辑器里，独立于步骤画布） */
+.patrol-box{margin-top:14px;border:1px solid var(--border-strong);border-radius:10px;padding:12px}
+.patrol-head{display:flex;align-items:center;justify-content:space-between;margin-bottom:8px}
+.patrol-head>span:first-child{font-weight:600;font-size:13px}
+.patrol-card{border:1px solid var(--border);border-radius:8px;padding:10px;margin-bottom:8px;background:var(--surface-2,#fafafa)}
+.patrol-row{display:flex;gap:10px;align-items:flex-end;margin-bottom:8px;flex-wrap:wrap}
+.patrol-row:last-child{margin-bottom:0}
+.patrol-row .pg{display:flex;flex-direction:column;gap:2px;min-width:110px}
+.patrol-row .pg label{font-size:11px;color:var(--text-light)}
+.patrol-row .form-check{margin-bottom:6px;display:flex;align-items:center;gap:4px;font-size:12px}
+.patrol-cond{background:rgba(59,130,246,.05);border-radius:6px;padding:6px 8px;margin:0 -2px 8px}
+
+/* 「步骤明细」表格的结果列配色（.log-* 那套作用域在 .log-content 里，表格用这套） */
+.res-error{color:#dc2626;font-weight:600}     /* 异常 / 未知步骤类型 */
+.res-miss{color:#d97706}                      /* 未命中 / 超时 / 已达上限 */
+.res-skip{color:var(--text-light)}            /* 概率未触发 */
+.res-ok{color:#059669}
+/* 工具栏：控件较多，允许换行；控件本身不参与收缩（否则会被挤成竖排文字） */
+.log-toolbar{display:flex;flex-wrap:wrap;gap:8px 10px;margin-bottom:12px;align-items:center}
+.log-toolbar>*{flex:0 0 auto}
+.log-toolbar .hint{flex:1 1 200px;min-width:160px}
 
 /* 区块标题 */
 .section-title{font-family:var(--display);font-size:15px;font-weight:700;color:var(--text);margin:0 0 12px;padding-bottom:8px;border-bottom:2px solid var(--primary);display:inline-block;letter-spacing:.2px}
@@ -285,7 +309,8 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 .el-device-card:hover{border-color:var(--primary);box-shadow:var(--shadow-md);transform:translateY(-1px)}
 .el-device-card .edc-icon{width:36px;height:36px;background:#f1efe8;border-radius:8px;display:flex;align-items:center;justify-content:center;font-size:18px;flex-shrink:0}
 .el-device-card .edc-info{flex:1}
-.el-device-card .edc-serial{font-size:13px;font-weight:600;color:var(--text);font-family:var(--mono)}
+.el-device-card .edc-name{font-size:13.5px;font-weight:700;color:var(--text)}
+.el-device-card .edc-serial{font-size:12px;color:var(--text-light);margin-top:2px;font-family:var(--mono)}
 .el-device-card .edc-model{font-size:12px;color:var(--text-light);margin-top:2px}
 .el-device-card .edc-status{font-size:11px;padding:2px 10px;border-radius:99px;background:var(--success-soft);color:#15803d;flex-shrink:0;font-weight:600}
 .el-picker-main{display:flex;flex:1;overflow:hidden}
@@ -440,6 +465,37 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 .agent-inputbar .btn-primary:hover{background:#155e75}
 .agent-inputbar .btn-primary:disabled{background:#9ca3af}
 .agent-empty{color:#6b7280;font-size:13px;text-align:center;padding:44px 0}
+
+/* ===== 动作配置：步骤默认值表单 ===== */
+.cfg-card{border:1px solid var(--border-strong);border-radius:10px;padding:12px;margin-bottom:10px}
+.cfg-card>h4{margin:0 0 8px;font-size:13px}
+.cfg-row{display:flex;gap:12px;flex-wrap:wrap}
+.cfg-row .pg{display:flex;flex-direction:column;gap:2px;min-width:120px}
+.cfg-row .pg label{font-size:11px;color:var(--text-light)}
+
+/* ===== 动作录制器 ===== */
+.rec-box{width:min(1180px,96vw);max-height:92vh;display:flex;flex-direction:column}
+.rec-head{display:flex;align-items:center;gap:10px;padding:12px 16px;border-bottom:1px solid var(--border)}
+.rec-head b{font-size:14px}
+.rec-body{display:flex;gap:14px;padding:14px 16px;overflow:hidden;flex:1;min-height:0}
+.rec-stage{flex:1;min-width:0;position:relative;background:var(--ink);border-radius:10px;
+  display:flex;align-items:center;justify-content:center;overflow:hidden}
+.rec-stage img{max-width:100%;max-height:74vh;display:block;cursor:crosshair;user-select:none}
+.rec-hint{color:#8a94a6;font-size:13px;padding:40px}
+.rec-warn{position:absolute;left:10px;top:10px;background:#fbbf24;color:#3b2f00;
+  font-size:11px;padding:2px 8px;border-radius:6px}
+.rec-line{position:absolute;border:2px dashed #f97316;border-radius:4px;pointer-events:none}
+.rec-side{width:330px;flex:0 0 330px;display:flex;flex-direction:column;gap:8px;min-height:0}
+.rec-ops{display:flex;gap:6px;flex-wrap:wrap}
+.rec-row{display:flex;gap:6px}
+.rec-list-title{font-size:12px;color:var(--text-light);margin-top:4px}
+.rec-list{flex:1;overflow-y:auto;border:1px solid var(--border);border-radius:8px;padding:6px;min-height:120px}
+.rec-item{display:flex;align-items:center;gap:6px;padding:3px 4px;border-bottom:1px dashed var(--border)}
+.rec-item:last-child{border-bottom:0}
+.rec-idx{width:18px;color:var(--text-light);font-size:11px;text-align:right}
+.rec-label{flex:1;font-size:12px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.rec-ops2{display:flex;gap:2px}
+.rec-foot{border-top:1px solid var(--border);padding-top:8px}
 </style>
 </head>
 <body>
@@ -457,6 +513,7 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
     <button class="tab active" data-tab="monitor" onclick="showTab('monitor')">监控</button>
     <button class="tab" data-tab="tasks" onclick="showTab('tasks')">任务</button>
     <button class="tab" data-tab="logs" onclick="showTab('logs')" data-perm="logs">日志</button>
+    <button class="tab" data-tab="plan" onclick="showTab('plan')" data-perm="devices">发布计划</button>
     <button class="tab" data-tab="users" onclick="showTab('users')" data-perm="admin">用户</button>
     <button class="tab" data-tab="tools" onclick="showTab('tools')" data-perm="admin">工具</button>
     <button class="tab" data-tab="agent" onclick="showTab('agent')" data-perm="admin">AI 控制台</button>
@@ -498,6 +555,7 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
       <th class="col-cb"><input type="checkbox" id="cb-all" onclick="toggleAllDevices(this.checked)" title="全选/取消全选"></th>
       <th data-sort="serial" onclick="_lpSort('devices','serial')">设备</th>
       <th data-sort="model" onclick="_lpSort('devices','model')">型号</th>
+      <th data-sort="battery" onclick="_lpSort('devices','battery')" title="后台每分钟采集一次（dumpsys battery）；颜色按告警档位上色，阈值在「工具 → 设备发现 → 电量监控」里配">电量</th>
       <th data-sort="worker_status" onclick="_lpSort('devices','worker_status')">任务状态</th>
       <th data-sort="foreground_app" onclick="_lpSort('devices','foreground_app')">前台App</th>
       <th data-sort="progress" onclick="_lpSort('devices','progress')">进度</th>
@@ -524,6 +582,88 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
   <div id="jobs-grid" class="jobs-grid"></div>
 </div>
 
+<!-- ========== Tab: 发布计划 ========== -->
+<div id="tab-plan" class="tab-panel">
+  <div class="page-title">发布计划</div>
+  <div class="page-sub">每个视频 = 一条计划：<b>文件名里的名字</b>（= 抖音昵称）+ 发布日期 + 编号，
+    到日子由任务推到手机、按名字找设备/账号发布（谁在机内、能不能发视频由运行时现场读名字判断）</div>
+
+  <div>
+    <div class="toolbar" style="flex-wrap:wrap">
+      <button class="btn btn-primary" onclick="document.getElementById('rp-video-input').click()"
+              data-perm="devices">上传视频/图片</button>
+      <button class="btn" onclick="document.getElementById('rp-title-input').click()"
+              data-perm="devices">上传标题/正文</button>
+      <button class="btn btn-primary" onclick="rpPushAll()" data-perm="devices"
+              title="把今天所有「待发布/失败」的计划推给「现在登着对应名字」的设备（按名字找设备；同台设备串行推）">一键推送（今天）</button>
+      <button class="btn" onclick="rpExportLinks()">导出链接 CSV</button>
+      <button class="btn" onclick="loadReleasePlan()">刷新</button>
+      <select class="form-control" id="rp-range" style="width:130px" onchange="rpRangeChanged()">
+        <option value="today">今天</option>
+        <option value="week">未来 7 天</option>
+        <option value="all">全部</option>
+      </select>
+      <select class="form-control" id="rp-status" style="width:150px" onchange="rpRangeChanged()">
+        <option value="">全部状态</option>
+        <option value="pending">待标题</option>
+        <option value="ready">待发布</option>
+        <option value="done">已发布</option>
+        <option value="failed,unknown">失败/未知</option>
+        <option value="skipped">已跳过</option>
+      </select>
+      <input class="form-control list-search" id="search-release" placeholder="搜索名字/标题/文件名...">
+      <span class="text-muted" id="rp-stats"></span>
+    </div>
+
+    <!-- 发布任务：到点自动"推送 + 发视频"。素材（上面）与执行（这里）在同一页 -->
+    <div style="border:1px solid var(--border);border-radius:6px;padding:8px 10px;margin-bottom:10px">
+      <div style="display:flex;justify-content:space-between;align-items:center;gap:8px;flex-wrap:wrap">
+        <div><b>发布任务</b>
+          <span class="text-muted" style="font-size:12px">
+            到点自动跑：推送素材 → 你的抖音步骤 → 标记结果（抖音那几步的选择器要你自己抓一次）
+          </span></div>
+        <div style="white-space:nowrap">
+          <button class="btn btn-xs btn-primary" onclick="rpNewTask()" data-perm="tasks">一键新建发布任务</button>
+          <button class="btn btn-xs" onclick="loadReleaseTasks()">刷新</button>
+        </div>
+      </div>
+      <div id="rp-tasks" style="margin-top:6px"></div>
+    </div>
+
+    <div id="rp-timeline"></div>
+    <div class="list-pager" id="pager-release"></div>
+
+    <details style="margin-top:12px">
+      <summary style="cursor:pointer;color:var(--text-light)">明细表（与时间线同一份数据）</summary>
+      <table class="table table-sm" style="margin-top:8px">
+        <thead><tr>
+          <th>发布日期</th><th>名字</th><th>由哪台发出</th><th>编号</th><th>素材文件</th>
+          <th>标题</th><th>正文</th><th>状态</th><th>分享链接</th><th>操作</th>
+        </tr></thead>
+        <tbody id="tb-release"></tbody>
+      </table>
+    </details>
+
+    <div class="help">
+      素材文件名规则 <code>名字_日期_编号</code>（<b>名字 = 抖音上的昵称</b>；<b>视频、图片都行</b>，扩展名各带各的；编号可省略，日期如 <code>20260912</code> 就是发布日期）；
+      标题 txt 每行 <code>标题 || 正文_名字_日期_编号</code>（<code>||</code> 后面是正文、可省略；编号可省，标题/正文里可以有下划线、可以有 <code>#话题</code>；<code>#</code> 开头的行<b>只要认得出名字/日期就当标题</b>，认不出才当注释忽略）。
+      <b>名字里不能有下划线、不能是纯数字</b>（那样切不出名字来），不满足会直接拒收并说明原因。<br>
+      上传后自动按 (名字, 日期, 编号) 配对：有编号按编号精确对，没编号按顺序配 ——
+      <b>没传标题的视频不会被推送</b>（先在计划页改标题或补传标题）。<br>
+      <b>平台只负责把视频推到手机</b>（推到 <code>/sdcard/DCIM/Camera/</code>、把文件时间改成"现在"好排在相册最前、触发相册刷新并<b>按路径</b>校验进了索引、
+      把标题写进手机剪贴板）；**抖音里怎么发由你在任务里自己写步骤** ——
+      步骤顺序是：<b>「推送发布视频」→ 你自己的发布步骤（打开抖音→点+→相册→选视频→下一步→粘贴标题→发布）→ 最后放一个「标记发布结果」</b>。<br>
+      计划页的「推送到手机」是同一件事的人工入口（推完你在手机上发，发完点「标记已发布」）。<br>
+      ⚠ 发布结果以<b>每行的状态</b>为准：<b>失败(可重试)</b>说明推送都没成功、可以再推；
+      <b>结果未知(需确认)</b>说明推送之后那一段出了岔子、<b>可能已经发出去了</b>，
+      要先到抖音里看一眼，再用「已发出 / 未发出」裁决（平台不会自动重发）。
+    </div>
+
+    <input type="file" id="rp-video-input" multiple accept="video/*,image/*" style="display:none" onchange="rpPickVideos(this)">
+    <input type="file" id="rp-title-input" accept=".txt" style="display:none" onchange="rpPickTitles(this)">
+  </div>
+</div>
+
 <!-- ========== Tab 2: 任务 ========== -->
 <div id="tab-tasks" class="tab-panel">
   <div class="page-title">任务</div>
@@ -532,6 +672,8 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
   <div class="sub-tabs">
     <button class="sub-tab active" data-sub="plan" onclick="showSubTab('tasks','plan')">任务计划</button>
     <button class="sub-tab" data-sub="actions" onclick="showSubTab('tasks','actions')">自定义动作</button>
+    <button class="sub-tab" data-sub="actioncfg" onclick="showSubTab('tasks','actioncfg')">动作配置</button>
+    <button class="sub-tab" data-sub="dedup" onclick="showSubTab('tasks','dedup')">去重记录</button>
   </div>
 
   <!-- 子分栏 1：任务计划 -->
@@ -564,6 +706,24 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
     </table>
     <div class="list-pager" id="pager-actions"></div>
   </div>
+
+  <!-- 子分栏 3：动作配置（步骤默认值 + 录制动作） -->
+  <div class="sub-panel" id="tasks-sub-actioncfg">
+    <div class="toolbar">
+      <button class="btn btn-primary" onclick="saveStepDefaults()" data-perm="tasks">保存默认值</button>
+      <button class="btn" onclick="resetStepDefaults()">恢复出厂</button>
+      <button class="btn" onclick="openRecorder({mode:'action'})" data-perm="devices">● 录制动作</button>
+      <button class="btn" onclick="loadActionConfig()">刷新</button>
+      <span class="hint" id="cfg-hint"></span>
+    </div>
+    <div class="help">
+      <b>步骤默认值</b>：新建步骤时预填这套参数（<b>只影响之后新建的步骤</b>，已有步骤不动；
+      单步想改就打开那个任务改那一步）。<br>
+      <b>录制动作</b>：在设备画面上点/划/按键，自动翻译成步骤 —— 既能存成可复用的「自定义动作」，
+      也能只取一个手势回填到滑动步骤上（步骤编辑器里滑动那一步有「录制手势」按钮）。
+    </div>
+    <div id="cfg-forms"><div class="text-muted" style="padding:10px">加载中…</div></div>
+  </div>
 </div>
 
 <!-- ========== Tab 3: 分组 ========== -->
@@ -773,30 +933,134 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
     </div>
     <div id="act-lib-list" style="flex:1;overflow-y:auto;min-height:200px;display:flex;flex-direction:column;gap:8px"></div>
   </div>
+
+  <!-- 子分栏 4：去重记录（done_mark 表 = 跨设备"已做过"账本） -->
+  <div class="sub-panel" id="tasks-sub-dedup">
+    <div class="help">
+      <b>去重账本</b>：任务里用「条件判断 → 去重」+「记为已做」两个步骤，把"这个身份做过了"记在这里，
+      <b>所有设备共享一份</b>——所以多个手机跑同一个任务、反复重跑，也不会把同一个号做两次。<br>
+      <span class="text-muted">想让它重跑：删掉对应那条（单个号/单台设备）或「清空本任务记录」。
+      有效期在任务编辑器的<b>「去重有效期」</b>里设（每天一次 / 只做一次 / 按小时）；「只做一次」的记录不会被自动清理。</span>
+    </div>
+    <div class="toolbar" style="gap:10px;flex-wrap:wrap">
+      <select class="form-control" id="dedup-job" style="width:280px" onchange="loadDedup()">
+        <option value="">全部任务</option>
+      </select>
+      <button class="btn" onclick="loadDedup()">刷新</button>
+      <button class="btn btn-danger" onclick="clearJobDedup()" data-perm="tasks">清空本任务记录</button>
+      <span class="text-muted" id="dedup-stats"></span>
+    </div>
+    <table class="table">
+      <thead><tr>
+        <th style="width:160px">时间</th><th style="width:90px">设备</th>
+        <th style="width:150px">身份值</th><th style="width:110px">有效期</th>
+        <th>任务</th><th style="width:120px">操作</th>
+      </tr></thead>
+      <tbody id="tb-dedup"><tr><td colspan="6" class="empty">暂无记录</td></tr></tbody>
+    </table>
+  </div>
 </div>
 
 <!-- ========== Tab 4: 日志 ========== -->
 <div id="tab-logs" class="tab-panel">
   <div class="page-title">日志查看</div>
-  <div class="page-sub">查看系统各模块运行日志</div>
+  <div class="page-sub">原始文本日志 + 任务步骤明细（结构化，可按设备/任务/时间过滤）</div>
+
+  <div class="sub-tabs">
+    <button class="sub-tab active" data-sub="files" onclick="showSubTab('logs','files')">文件日志</button>
+    <button class="sub-tab" data-sub="steps" onclick="showSubTab('logs','steps')">步骤明细</button>
+  </div>
+
+  <!-- 子分栏 1：文件日志 -->
+  <div class="sub-panel active" id="logs-sub-files">
   <div class="log-toolbar">
-    <select id="log-file" class="form-control" style="width:auto" onchange="loadLogs()">
-      <option value="core.log">核心日志 (core.log)</option>
-      <option value="task.log">任务日志 (task.log)</option>
-      <option value="web.log">Web日志 (web.log)</option>
-      <option value="action.log">操作日志 (action.log)</option>
+    <!-- 文件下拉由 /api/logs 返回的清单动态渲染（含 .1/.2 滚动历史与 notify.log） -->
+    <select id="log-file" class="form-control" style="width:auto" onchange="loadLogs()"></select>
+    <input id="log-q" class="form-control" style="width:190px" placeholder="关键字（设备号/包名/报错…）"
+           onkeydown="if(event.key==='Enter')loadLogs()">
+    <select id="log-level" class="form-control" style="width:auto" onchange="loadLogs()">
+      <option value="">全部级别</option>
+      <option value="ERROR">仅 ERROR</option>
+      <option value="WARNING">WARNING 及以上</option>
+      <option value="INFO">INFO 及以上</option>
     </select>
+    <input id="log-since" type="datetime-local" class="form-control" style="width:auto"
+           title="起始时间" onchange="loadLogs()">
+    <span class="text-muted">~</span>
+    <input id="log-until" type="datetime-local" class="form-control" style="width:auto"
+           title="结束时间" onchange="loadLogs()">
     <select id="log-lines" class="form-control" style="width:auto" onchange="loadLogs()">
       <option value="100">最近 100 行</option>
       <option value="300" selected>最近 300 行</option>
       <option value="500">最近 500 行</option>
       <option value="1000">最近 1000 行</option>
+      <option value="5000">最近 5000 行</option>
     </select>
     <label class="form-check"><input type="checkbox" id="log-auto" checked onchange="toggleLogAuto()"> 自动刷新</label>
     <button class="btn" onclick="loadLogs()">刷新</button>
+    <button class="btn" onclick="downloadLogs()" title="下载当前筛选结果（无筛选即整个文件）">下载</button>
+    <button class="btn" onclick="resetLogFilters()">重置</button>
     <span class="hint" id="log-hint"></span>
   </div>
   <div id="log-content" class="log-content"></div>
+  </div><!-- /logs-sub-files -->
+
+  <!-- 子分栏 2：步骤明细（task_step_log 表，结构化，可按设备/任务/时间/结果过滤） -->
+  <div class="sub-panel" id="logs-sub-steps">
+    <div class="log-toolbar">
+      <select id="sl-device" class="form-control" style="width:auto" onchange="loadStepLogs(true)"></select>
+      <select id="sl-job" class="form-control" style="width:auto" onchange="loadStepLogs(true)"></select>
+      <select id="sl-result" class="form-control" style="width:auto" onchange="loadStepLogs(true)">
+        <option value="">全部结果</option>
+        <option value="error">异常 error</option>
+        <option value="miss">未命中 miss</option>
+        <option value="unknown">未知类型 unknown</option>
+        <option value="skip">概率跳过 skip</option>
+        <option value="ok">正常 ok</option>
+        <option value="cap">已截断 cap</option>
+      </select>
+      <input id="sl-q" class="form-control" style="width:170px" placeholder="关键字（步骤名/选择器/详情）"
+             onkeydown="if(event.key==='Enter')loadStepLogs(true)">
+      <input id="sl-since" type="datetime-local" class="form-control" style="width:auto" onchange="loadStepLogs(true)">
+      <span class="text-muted">~</span>
+      <input id="sl-until" type="datetime-local" class="form-control" style="width:auto" onchange="loadStepLogs(true)">
+      <select id="sl-limit" class="form-control" style="width:auto" onchange="loadStepLogs(true)">
+        <option value="100">每页 100</option>
+        <option value="200" selected>每页 200</option>
+        <option value="500">每页 500</option>
+      </select>
+      <button class="btn" onclick="loadStepLogs(true)">刷新</button>
+      <button class="btn" onclick="downloadStepLogs()" title="导出当前筛选结果（CSV）">导出 CSV</button>
+      <button class="btn" onclick="resetStepFilters()">重置</button>
+      <span class="hint" id="sl-hint"></span>
+    </div>
+    <div class="hint" id="sl-note"></div>
+
+    <details id="sl-runs-box" style="margin:10px 0">
+      <summary style="cursor:pointer;font-size:13px" id="sl-runs-summary">最近运行概览</summary>
+      <table class="table" style="margin-top:8px">
+        <thead><tr>
+          <th style="width:150px">开始</th><th style="width:110px">设备</th><th>任务</th>
+          <th style="width:70px">步骤数</th><th style="width:80px">失败</th><th style="width:70px"></th>
+        </tr></thead>
+        <tbody id="sl-runs-body"></tbody>
+      </table>
+    </details>
+
+    <table class="table">
+      <thead><tr>
+        <th style="width:145px">时间</th><th style="width:105px">设备</th><th style="width:150px">任务</th>
+        <th style="width:60px">步骤</th><th>标签</th><th style="width:95px">类型</th>
+        <th style="width:75px">结果</th><th style="width:65px">耗时</th><th>详情</th>
+      </tr></thead>
+      <tbody id="sl-body"></tbody>
+    </table>
+    <div class="toolbar" style="margin-top:10px">
+      <button class="btn" id="sl-prev" onclick="stepLogPage(-1)">上一页</button>
+      <span class="hint" id="sl-page"></span>
+      <button class="btn" id="sl-next" onclick="stepLogPage(1)">下一页</button>
+    </div>
+  </div><!-- /logs-sub-steps -->
 </div>
 
 <!-- ========== Tab 5: 用户 ========== -->
@@ -1053,6 +1317,37 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
         </table>
       </div>
     </div>
+    <!-- 电量监控：定时采集设备电量（大屏 + 监控页设备列表展示），低于阈值推 webhook 通知 -->
+    <div style="border-bottom:1px solid var(--border);margin-bottom:10px;padding-bottom:10px">
+      <div class="toolbar" style="flex-wrap:wrap">
+        <label style="display:inline-flex;align-items:center;gap:4px">
+          <input type="checkbox" id="battery-enabled" onchange="saveBatterySettings()"> 电量监控
+        </label>
+        <span class="text-muted" style="margin-left:8px">低电量</span>
+        <input type="number" id="battery-low" style="width:70px" min="1" max="100"
+               title="电量低于这个值就告警">
+        <span class="text-muted">% · 严重</span>
+        <input type="number" id="battery-critical" style="width:70px" min="1" max="100"
+               title="低于这个值时通知等级升到「严重」（error）。不能高于低电量阈值。">
+        <span class="text-muted">%</span>
+        <label style="display:inline-flex;align-items:center;gap:4px;margin-left:10px"
+               title="充电中（status=充电中/已充满）不告警——插着充电器说明正在补电。注意「插着却没充电」（劣质线/温控/满电停充）仍会告警，那正是最该知道的情况。">
+          <input type="checkbox" id="battery-skip-charging"> 充电中不告警
+        </label>
+        <span class="text-muted" style="margin-left:8px">采集间隔</span>
+        <input type="number" id="battery-interval" style="width:70px" min="30" max="3600">
+        <span class="text-muted">秒</span>
+        <button class="btn" onclick="saveBatterySettings()">保存设置</button>
+        <button class="btn" onclick="scanBatteryNow()">立即采集</button>
+        <span id="battery-status" class="text-muted"></span>
+      </div>
+      <div class="help">定时用 <code>dumpsys battery</code>（只读）采集池内在线设备的电量，显示在
+        <b>「监控 → 设备列表」的电量列</b>与<b>大屏卡片</b>上。<br>
+        低于阈值时推 webhook 通知（事件 <code>device.battery.low</code>，要在「系统 → 通知」里勾选订阅才发）：
+        <b>掉到低电量报一次、掉到严重再报一次、恢复再报一次</b>，不做重复刷屏。<br>
+        电量只放内存、<b>不落库</b>（重启后重新采一轮），所以不占数据库、不影响备份。
+        设备离线时显示最后一次读数（置灰），不会变成空白。</div>
+    </div>
     <div class="toolbar">
       <input type="text" id="devpool-serial" class="form-control" style="width:220px;font-family:monospace"
              placeholder="serial，如 100.100.10.20:5555" onkeydown="if(event.key==='Enter')addPoolDev()">
@@ -1266,5 +1561,9 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 <script src="/static/admin/taskgen.js"></script>
 <script src="/static/admin/system.js"></script>
 <script src="/static/admin/notify.js"></script>
+<script src="/static/admin/steplog.js"></script>
+<script src="/static/admin/recorder.js"></script>
+<script src="/static/admin/dedup.js"></script>
+<script src="/static/admin/release.js"></script>
 </body>
 </html>

templates/admin/wall.html

@@ -73,6 +73,17 @@ main{position:relative;z-index:2;height:calc(100vh - 88px);overflow-y:auto;paddi
 .card .info .name{font-size:13.5px;font-weight:700;color:#f1f4f8;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
 .card .info .ip{font-family:var(--mono);font-size:12px;color:var(--muted);margin-top:2px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
 .card .info .model{font-size:10.5px;color:var(--faint);margin-top:2px}
+/* 型号 + 电量同一行（省一行高度，卡片本来就矮） */
+.card .info .meta{display:flex;align-items:center;gap:8px;margin-top:2px;white-space:nowrap;overflow:hidden}
+.card .info .meta .model{margin-top:0;overflow:hidden;text-overflow:ellipsis}
+.card .info .batt{margin-left:auto;display:inline-flex;align-items:center;gap:2px;font-size:11px;color:var(--faint);flex:0 0 auto}
+.card .info .batt .lv{font-family:var(--mono);font-weight:700}
+.card .info .batt.ok .lv{color:var(--green)}
+.card .info .batt.low .lv{color:var(--amber)}
+.card .info .batt.crit .lv{color:var(--red)}
+.card .info .batt.crit{animation:pulse 1.6s infinite}
+.card .info .batt.stale{opacity:.4}
+.card .info .batt .chg{color:var(--teal)}
 .card .info .action{font-size:11.5px;color:var(--muted);margin-top:6px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;min-height:16px}
 .card .info .action b{color:var(--amber);font-weight:600}
 .card .info .prog{margin-top:7px;height:4px;background:#1d242e;border-radius:99px;overflow:hidden}
@@ -106,6 +117,23 @@ main{position:relative;z-index:2;height:calc(100vh - 88px);overflow-y:auto;paddi
 .ctrl-tools .text-row{display:flex;gap:6px;flex:1 0 100%;margin-top:2px}
 .ctrl-tools .text-row input{flex:1;background:#0d1117;border:1px solid var(--card-line);border-radius:8px;padding:6px 10px;font-size:12px;color:var(--text);outline:none;font-family:var(--body)}
 .ctrl-tools .text-row input:focus{border-color:var(--teal)}
+/* 大屏「发布」面板：选设备 → 推视频/图片到相册、写剪贴板 */
+.pub-label{display:block;font-size:12px;font-weight:600;color:var(--muted);margin-bottom:5px}
+.pub-input{width:100%;box-sizing:border-box;background:#0f1319;border:1px solid var(--card-line);
+  color:#e5e9f0;border-radius:8px;padding:8px 10px;font-size:13px;font-family:var(--body)}
+select.pub-input{padding:7px 8px}
+.pub-btn{background:#1a2029;border:1px solid var(--card-line);color:var(--teal);border-radius:8px;
+  padding:8px 14px;font-size:13px;font-weight:600;cursor:pointer;font-family:var(--body);transition:all .12s}
+.pub-btn:hover{border-color:var(--teal)}
+.pub-btn:disabled{opacity:.55;cursor:not-allowed}
+.pub-hint{font-size:11.5px;color:var(--faint);margin-top:5px;line-height:1.55}
+.pub-log{margin-top:2px;font-size:12px;color:var(--muted);max-height:132px;overflow:auto;
+  background:#0f1319;border:1px solid var(--ink-line);border-radius:8px;padding:8px 10px;
+  white-space:pre-wrap;word-break:break-all}
+.pub-log:empty{display:none}
+.pub-log .ok{color:var(--green)}
+.pub-log .err{color:#f87171}
+
 /* 滚动条 */
 ::-webkit-scrollbar{width:8px}
 ::-webkit-scrollbar-thumb{background:#232936;border-radius:4px}
@@ -120,6 +148,7 @@ main{position:relative;z-index:2;height:calc(100vh - 88px);overflow-y:auto;paddi
     <input type="checkbox" id="wall-filter-online" checked onchange="refreshStatus()"> 只看在线
   </label>
   <button class="wall-btn" id="btn-wake-all" onclick="wakeAll()">💡 一键亮屏</button>
+  <button class="wall-btn" id="btn-publish" onclick="openPublish()" title="选设备 → 注入视频/图片到相册，或注入剪贴板">📤 发布</button>
   <div class="clock"><span id="wall-clock">--:--:--</span><div class="date" id="wall-date"></div></div>
 </header>
 <main id="wall-grid"></main>
@@ -156,6 +185,38 @@ main{position:relative;z-index:2;height:calc(100vh - 88px);overflow-y:auto;paddi
   </div>
 </div>
 
+<!-- 发布面板（选设备 → 注入素材 / 剪贴板） -->
+<div class="ctrl-overlay" id="pub-overlay" onclick="if(event.target===this)closePublish()">
+  <div class="ctrl-box" style="width:min(470px,94vw)">
+    <div class="ctrl-head">
+      <div class="info">
+        <div class="name">📤 发布</div>
+        <div class="sub" style="font-size:12px;color:var(--muted)">选设备 → 把视频/图片推到相册，或把文字写进剪贴板</div>
+      </div>
+      <button class="close" onclick="closePublish()">×</button>
+    </div>
+    <div style="padding:14px 16px;display:flex;flex-direction:column;gap:14px;overflow:auto">
+      <div>
+        <label class="pub-label">设备</label>
+        <select class="pub-input" id="pub-serial"></select>
+      </div>
+      <div>
+        <label class="pub-label">视频 / 图片</label>
+        <input type="file" class="pub-input" id="pub-file" accept="video/*,image/*">
+        <div class="pub-hint">推到相册 /sdcard/DCIM/Camera，文件名带 <code>wall</code> 前缀
+          （<b>不占发布计划</b>，不进队列、不改状态；推完在手机相册里就是最新那一个）</div>
+        <button class="pub-btn" style="margin-top:8px" id="pub-push-btn" onclick="pubPushMaterial()">📤 注入素材</button>
+      </div>
+      <div>
+        <label class="pub-label">剪贴板文字</label>
+        <textarea class="pub-input" id="pub-text" rows="3" placeholder="要写进手机剪贴板的文字（发文案用）"></textarea>
+        <button class="pub-btn" style="margin-top:8px" id="pub-clip-btn" onclick="pubPushClipboard()">📋 注入剪贴板</button>
+      </div>
+      <div class="pub-log" id="pub-log"></div>
+    </div>
+  </div>
+</div>
+
 <script>
 // ================== 监控大屏（深色控制室） ==================
 // 状态每 5s 刷新；缩略图每 2.5s 轮询（页面不可见时暂停）
@@ -202,8 +263,8 @@ async function refreshStatus(){
   const r=await apiGet('/api/status');
   if(!r||!r.ok)return;
   const devs=(r.devices||[]).sort((a,b)=>a.serial.localeCompare(b.serial));
-  const changed=JSON.stringify(devs.map(d=>[d.serial,d.present,d.worker_status,d.task_job,d.current_action,d.progress,d.device_name,d.model]))!==
-                JSON.stringify(_devices.map(d=>[d.serial,d.present,d.worker_status,d.task_job,d.current_action,d.progress,d.device_name,d.model]));
+  const changed=JSON.stringify(devs.map(d=>[d.serial,d.present,d.worker_status,d.task_job,d.current_action,d.progress,d.device_name,d.model,d.battery]))!==
+                JSON.stringify(_devices.map(d=>[d.serial,d.present,d.worker_status,d.task_job,d.current_action,d.progress,d.device_name,d.model,d.battery]));
   _devices=devs;
   renderStats(devs);
   if(changed)renderGrid(visibleDevs(devs));
@@ -211,6 +272,68 @@ async function refreshStatus(){
   if(_ctrlSerial)updateCtrlHead();
 }
 
+// ================== 发布面板：选设备 → 注入素材 / 剪贴板 ==================
+// 与「发布计划」页的区别：那里按**计划**推（占位/去重/回写状态、按账号名找设备）；
+// 这里是**临时手动**推一个文件到某台手机，给"手上有一段素材，想马上在这台机器上发"用。
+function pubLog(msg, cls){
+  const box=document.getElementById('pub-log');
+  const line=document.createElement('div');
+  if(cls)line.className=cls;
+  line.textContent=msg;
+  box.appendChild(line);
+  box.scrollTop=box.scrollHeight;
+}
+function openPublish(){
+  const sel=document.getElementById('pub-serial');
+  const keep=sel.value;
+  sel.innerHTML=_devices.map(function(d){
+    const name=d.device_name||d.model||d.serial;
+    return '<option value="'+d.serial+'"'+(d.serial===keep?' selected':'')+'>'
+      +esc(name)+'（'+shortIp(d.serial)+'）'+(d.present?'':' · 离线')+'</option>';
+  }).join('')||'<option value="">（设备池为空）</option>';
+  document.getElementById('pub-overlay').classList.add('show');
+}
+function closePublish(){document.getElementById('pub-overlay').classList.remove('show');}
+function pubSerial(){return document.getElementById('pub-serial').value||'';}
+
+async function pubPushMaterial(){
+  const serial=pubSerial();
+  const fi=document.getElementById('pub-file');
+  const f=fi.files&&fi.files[0];
+  if(!serial){pubLog('❌ 先选设备','err');return;}
+  if(!f){pubLog('❌ 先选视频或图片','err');return;}
+  const btn=document.getElementById('pub-push-btn');
+  btn.disabled=true;
+  pubLog('⏳ 正在推到 '+serial+' …（'+f.name+' '+(f.size/1048576).toFixed(1)+'MB）');
+  try{
+    const fd=new FormData();
+    fd.append('file',f);
+    fd.append('serial',serial);
+    const r=await fetch('/api/tools/push_material',{method:'POST',
+      headers:{'X-CSRF-Token':_csrfToken},body:fd});
+    const j=await r.json();
+    if(j.ok){pubLog('✅ '+(j.msg||'已推送'),'ok');fi.value='';}
+    else{pubLog('❌ '+(j.error||'推送失败'),'err');}
+  }catch(e){pubLog('❌ 请求失败：'+e,'err');}
+  btn.disabled=false;
+}
+
+async function pubPushClipboard(){
+  const serial=pubSerial();
+  const text=(document.getElementById('pub-text').value||'').trim();
+  if(!serial){pubLog('❌ 先选设备','err');return;}
+  if(!text){pubLog('❌ 先填要注入的文字','err');return;}
+  const btn=document.getElementById('pub-clip-btn');
+  btn.disabled=true;
+  pubLog('⏳ 正在注入剪贴板到 '+serial+' …');
+  try{
+    const j=await apiPost('/api/tools/push_clipboard',{serial:serial,text:text});
+    if(j&&j.ok){pubLog('✅ '+(j.msg||'已注入剪贴板'),'ok');}
+    else{pubLog('❌ '+((j&&(j.error||(j.results&&Object.values(j.results)[0]&&Object.values(j.results)[0].msg)))||'注入失败'),'err');}
+  }catch(e){pubLog('❌ 请求失败：'+e,'err');}
+  btn.disabled=false;
+}
+
 // 「只看在线」勾选时过滤离线设备（默认勾选）
 function visibleDevs(devs){
   const onlyOnline=document.getElementById('wall-filter-online')
@@ -249,6 +372,22 @@ function fmtProgress(p){
 }
 function shortIp(serial){return String(serial||'').replace(/:5555$/,'');}
 
+// 电量：告警档位（tier 0 正常/1 低/2 严重）由后端算好，前端只上色——
+// 阈值只在「工具 → 设备发现 → 电量监控」一处定义，前端不重复判，免得两边不一致
+function battHtml(d){
+  const b=d.battery;
+  if(!b)return '<span class="batt">🔋<span class="lv">—</span></span>';
+  const t=b.tier||0;
+  const cls=t===2?'crit':(t===1?'low':'ok');
+  const chg=b.charging?'<span class="chg" title="充电中">⚡</span>':'';
+  const mins=b.at?Math.floor((Date.now()/1000-b.at)/60):-1;
+  const minsTxt=(mins<0?'未知':(mins<1?'刚刚':mins+' 分钟前'));
+  const tip=(t===2?'电量严重不足':(t===1?'电量低':'电量正常'))
+    +'（'+minsTxt+'采集'+(d.present?'':'，设备已离线，显示最后一次读数')+'）';
+  return '<span class="batt '+cls+(d.present?'':' stale')+'" title="'+tip+'">🔋'
+    +'<span class="lv">'+b.level+'%</span>'+chg+'</span>';
+}
+
 function cardHtml(d, i){
   const cls=cardCls(d);
   const serial=esc(d.serial);
@@ -268,7 +407,8 @@ function cardHtml(d, i){
     '<div class="info">'+
       '<div class="name">'+name+'</div>'+
       '<div class="ip">'+ip+'</div>'+
-      '<div class="model">'+esc(d.model||'')+'</div>'+
+      '<div class="meta"><span class="model">'+esc(d.model||'')+'</span>'
+        +'<span class="batt-wrap">'+battHtml(d)+'</span></div>'+
       action+fmtProgress(d.progress)+
       '<div class="hint">点击进入设备操作</div>'+
     '</div>'+
@@ -306,6 +446,9 @@ function renderGrid(devs){
       card.querySelector('.name').textContent=d.device_name||d.model||'设备';
       card.querySelector('.ip').textContent=shortIp(serial);
       card.querySelector('.model').textContent=d.model||'';
+      // 电量（与型号同一行，见 .meta）
+      const bw=card.querySelector('.batt-wrap');
+      if(bw)bw.innerHTML=battHtml(d);
       const action=d.current_action
         ?(d.task_job?'<b>'+esc(d.task_job)+'</b> · ':'')+esc(d.current_action)
         :(d.task_job?'<b>'+esc(d.task_job)+'</b>':'');

web/__init__.py

@@ -6,7 +6,8 @@
   tasks       — 任务计划/分组/自定义动作/元素抓取/步骤测试
   admin       — 用户管理/日志
   tools       — adb 终端/剪贴板注入/应用版本
-  devices     — 设备池管理
+  devices     — 设备池管理 + 账号台账
+  video_plan  — 视频发布计划（上传/时间线/链接导出/单条发布）
   apks        — 应用管理
   tailscale   — Tailscale 管理
   system      — 系统数据备份导出/导入
@@ -24,6 +25,7 @@ def register_blueprints(app):
     from .admin_api import bp as admin_bp
     from .tools_api import bp as tools_bp
     from .devices_api import bp as devices_bp
+    from .video_plan_api import bp as video_plan_bp
     from .apks_api import bp as apks_bp
     from .tailscale_api import bp as tailscale_bp
     from . import agent_api as _agent_mod
@@ -33,6 +35,6 @@ def register_blueprints(app):
     from .device_agent_api import bp as devagent_bp
     from .notify_api import bp as notify_bp
     for bp in (auth_bp, monitor_bp, tasks_bp, admin_bp, tools_bp,
-               devices_bp, apks_bp, tailscale_bp, agent_bp, system_bp,
+               devices_bp, video_plan_bp, apks_bp, tailscale_bp, agent_bp, system_bp,
                devagent_bp, notify_bp):
         app.register_blueprint(bp)

web/admin_api.py

@@ -1,17 +1,19 @@
 """管理域 API：用户管理/日志查看。"""
-import os
 import time
+from io import BytesIO
 
-from flask import Blueprint, jsonify, request
+from flask import Blueprint, jsonify, request, send_file
 from flask_login import current_user
 from flask import session
 
-from core.logger import _LOG_DIR, _MODULE_FILES
+from core import logger
+from core.logger import get_logger
 from core.models import db, User
 from web import context
 from web.auth import (admin_required, perm_required, _validate_perms,
                              PERM_LOGS)
 
+_log = get_logger("web")
 bp = Blueprint("admin", __name__)
 
 @bp.route("/api/users")
@@ -79,22 +81,173 @@ def api_users_delete(uid):
 
 
 # ================== API：日志查看 ==================
+#
+# 过滤/白名单都在 core.logger 里做（读取侧与写入侧共用同一份文件清单，
+# 见 core/logger.py「日志读取」一节）；这里只负责取参数 + 组装响应。
+
+
+def _log_filters():
+    """从 query string 取过滤条件（/api/logs 与 /api/logs/download 共用）。"""
+    return dict(keyword=request.args.get("q", ""),
+                min_level=request.args.get("level", ""),
+                since=request.args.get("since", ""),
+                until=request.args.get("until", ""))
+
 
 @bp.route("/api/logs")
 @perm_required(PERM_LOGS)
 def api_logs():
-    files = list(_MODULE_FILES.values())
-    current = request.args.get("file", "core.log")
-    lines = int(request.args.get("lines", 300))
-    content = ""
-    path = os.path.join(_LOG_DIR, current)
-    if os.path.exists(path):
-        try:
-            with open(path, encoding="utf-8") as f:
-                content = "".join(f.readlines()[-lines:])
-        except Exception as e:
-            content = f"读取失败: {e}"
-    return jsonify({"ok": True, "content": content, "file": current, "files": files})
+    """读日志：可按关键字 / 最低级别 / 时间范围过滤，返回结构化行。
+
+    参数：file 文件名（白名单）、q 关键字、level 最低级别（ERROR 含以上…）、
+    since/until 时间、lines 返回条数（取**最近** N 条命中）。
+    """
+    files = logger.list_log_files()
+    names = [f["name"] for f in files]
+    # 默认仍落在 core.log（接口按 mtime 倒序返回，names[0] 会随当前哪个模块在
+    # 写而漂移，作为"打开日志页时看哪个"不稳定）
+    default = "core.log" if "core.log" in names else (names[0] if names else "")
+    current = request.args.get("file") or default
+    try:
+        lines = int(request.args.get("lines", 300))
+    except (TypeError, ValueError):
+        lines = 300
+    res = logger.query_log(current, limit=lines, **_log_filters())
+    return jsonify({"ok": not res["error"], "error": res["error"], "file": current,
+                    "files": files, "rows": res["rows"], "matched": res["matched"],
+                    "scanned": res["scanned"], "truncated": res["truncated"]})
+
+
+@bp.route("/api/logs/download")
+@perm_required(PERM_LOGS)
+def api_logs_download():
+    """下载日志文件（带同样的过滤条件；无条件时就是整个文件）。
+
+    用 BytesIO 发送而不是 send_file(路径)：Windows 上流式发送时文件句柄可能
+    到 close 仍未释放，而日志文件正被日志线程持续写入，按路径发容易踩锁。
+    """
+    name = request.args.get("file", "")
+    text, err = logger.read_log_text(name, **_log_filters())
+    if err:
+        return jsonify({"ok": False, "error": err}), 404
+    data = text.encode("utf-8")
+    fname = f"{name}_{time.strftime('%Y%m%d_%H%M%S')}.txt"
+    _log.info("下载日志: %s（%d 字节）by %s", name, len(data),
+              getattr(current_user, "username", ""))
+    return send_file(BytesIO(data), as_attachment=True, download_name=fname,
+                     mimetype="text/plain; charset=utf-8")
+
+
+# ================== API：任务步骤明细 ==================
+#
+# 数据源是 task_step_log 表（结构化），不是 logs/task.log 文本——所以能按设备/
+# 任务/时间/结果过滤。写入侧见 core/step_log.py（异步写线程 + 保留期清理）。
+
+def _step_filters():
+    """从 query string 取步骤明细的过滤条件（列表与下载共用）。"""
+    return dict(serial=request.args.get("serial", ""),
+                job_id=request.args.get("job_id", ""),
+                result=request.args.get("result", ""),
+                run_id=request.args.get("run_id", ""),
+                keyword=request.args.get("q", ""),
+                since=logger.norm_ts(request.args.get("since", "")),
+                until=logger.norm_ts(request.args.get("until", ""), end=True))
+
+
+def _step_to_dict(r):
+    return {"id": r.id, "run_id": r.run_id, "job_id": r.job_id,
+            "job_name": r.job_name, "serial": r.serial,
+            "device_name": r.device_name, "step_path": r.step_path,
+            "step_label": r.step_label, "step_type": r.step_type,
+            "selector": r.selector, "result": r.result, "detail": r.detail,
+            "duration_ms": r.duration_ms, "created_at": r.created_at}
+
+
+@bp.route("/api/step_logs")
+@perm_required(PERM_LOGS)
+def api_step_logs():
+    """任务步骤明细（分页，最近的在前）。"""
+    from core import step_log
+    try:
+        limit = int(request.args.get("limit", 200))
+        offset = int(request.args.get("offset", 0))
+    except (TypeError, ValueError):
+        limit, offset = 200, 0
+    rows, total = step_log.query(limit=limit, offset=offset, **_step_filters())
+    return jsonify({"ok": True, "rows": [_step_to_dict(r) for r in rows],
+                    "total": total, "limit": limit, "offset": offset,
+                    "stats": step_log.stats(),
+                    "keep_days": step_log.KEEP_DAYS,
+                    "max_rows_per_run": step_log.MAX_ROWS_PER_RUN})
+
+
+@bp.route("/api/step_logs/runs")
+@perm_required(PERM_LOGS)
+def api_step_logs_runs():
+    """按 run_id 归组的一次运行概览（哪次运行、几步、失败几步）。"""
+    from core import step_log
+    f = _step_filters()
+    rows = step_log.runs(serial=f["serial"], job_id=f["job_id"],
+                         since=f["since"], until=f["until"],
+                         limit=request.args.get("limit", 100))
+    return jsonify({"ok": True, "runs": [
+        {"run_id": r.run_id, "job_id": r.job_id, "job_name": r.job_name,
+         "serial": r.serial, "device_name": r.device_name,
+         "started_at": r.started_at, "ended_at": r.ended_at,
+         "steps": int(r.steps or 0), "failures": int(r.failures or 0)}
+        for r in rows]})
+
+
+@bp.route("/api/step_logs/filters")
+@perm_required(PERM_LOGS)
+def api_step_logs_filters():
+    """筛选下拉的可选项：**只在明细里出现过的**设备与任务（按数据自洽，不依赖
+    设备池/任务表，也不要求调用方另有 task/device 权限）。"""
+    from core import step_log
+    from core.models import TaskStepLog, db
+    devices = (db.session.query(TaskStepLog.serial, TaskStepLog.device_name)
+               .filter(TaskStepLog.serial != "").distinct().limit(500).all())
+    jobs = (db.session.query(TaskStepLog.job_id, TaskStepLog.job_name)
+            .filter(TaskStepLog.job_id != "").distinct().limit(500).all())
+    return jsonify({"ok": True,
+                    "devices": sorted(({"serial": s, "device_name": n}
+                                       for s, n in devices),
+                                      key=lambda x: x["device_name"] or x["serial"]),
+                    "jobs": sorted(({"job_id": i, "job_name": n} for i, n in jobs),
+                                   key=lambda x: x["job_name"] or x["job_id"]),
+                    "results": ["ok", "miss", "error", "unknown", "skip", "cap"],
+                    "keep_days": step_log.KEEP_DAYS,
+                    "max_rows_per_run": step_log.MAX_ROWS_PER_RUN})
+
+
+@bp.route("/api/step_logs/download")
+@perm_required(PERM_LOGS)
+def api_step_logs_download():
+    """导出步骤明细为 CSV（带同样的过滤条件）。
+
+    加 UTF-8 BOM：不加的话 Excel 打开中文是乱码（这是给运维看的表，
+    大概率会被 Excel 打开）。
+    """
+    import csv
+    from io import StringIO
+    from core import step_log
+    f = _step_filters()
+    # 导出上限：和列表页共用同一次查询，最多 2 万行（再多请缩小时间范围）
+    rows, total = step_log.query(limit=20000, offset=0, **f)
+    buf = StringIO()
+    w = csv.writer(buf)
+    w.writerow(["时间", "设备", "设备名", "任务", "运行ID", "步骤路径", "步骤",
+                "类型", "选择器", "结果", "耗时(ms)", "详情"])
+    for r in reversed(rows):        # 导出的时间序与页面相反：文件里按正序更好读
+        w.writerow([r.created_at, r.serial, r.device_name, r.job_name,
+                    r.run_id, r.step_path, r.step_label, r.step_type,
+                    r.selector, r.result, r.duration_ms, r.detail])
+    data = buf.getvalue().encode("utf-8-sig")   # utf-8-sig = UTF-8 带 BOM（Excel 中文不乱码）
+    fname = f"step_log_{time.strftime('%Y%m%d_%H%M%S')}.csv"
+    _log.info("导出步骤明细: %d 行（命中 %d）by %s", len(rows), total,
+              getattr(current_user, "username", ""))
+    return send_file(BytesIO(data), as_attachment=True, download_name=fname,
+                     mimetype="text/csv; charset=utf-8")
 
 
 # ================== API：运行控制 ==================

web/device_agent_api.py

@@ -317,6 +317,9 @@ def api_agent_show_info():
                 "--es", "server", server]
         if ip:
             args += ["--es", "ip", ip]
+        # 账号台账块（`accounts_b64`）随账号管理一起下线了：身份页只显示
+        # 名称/地址/平台地址这些设备信息。老版本 Agent 收到"没有这个 extra"照常显示。
+        warn = ""
 
     # 先点亮屏幕、解除锁屏：设备息屏时 am start 会把大字页开在锁屏**后面**，
     # 人看到的还是一片黑（实测踩过）——这正是原来"定位"按钮里的"点亮屏幕"那一步
@@ -339,7 +342,10 @@ def api_agent_show_info():
                         "error": "这台设备没装设备 Agent（com.example.deviceagent）——"
                                  "可以从「应用管理 → 设备端应用商店」装，或用扫码配置"}), 400
     _log.info("设备端 Agent %s: %s", "关闭身份页" if close else "打开身份页", serial)
-    return jsonify({"ok": True, "msg": "已关闭" if close else "已让设备显示身份信息"})
+    resp = {"ok": True, "msg": "已关闭" if close else "已让设备显示身份信息"}
+    if not close and warn:
+        resp["warn"] = warn          # 前端用 toast 提示（同二维码接口的 warn 惯例）
+    return jsonify(resp)
 
 
 @bp.route("/api/agent-store/config", methods=["GET", "POST"])

web/devices_api.py

@@ -4,7 +4,7 @@ from concurrent.futures import ThreadPoolExecutor, as_completed
 
 from flask import Blueprint, jsonify, request
 
-from core import device_pool, device_discovery
+from core import device_battery, device_pool, device_discovery
 from core.adb_helper import adb_connect, adb_connect_light
 from core.logger import get_logger
 from web.auth import perm_required, PERM_DEVICES
@@ -411,7 +411,40 @@ def api_devices_discovery_settings():
     return jsonify({"ok": True, "msg": msg})
 
 
-# ================== API：Tailscale 管理（仅管理员） ==================
+# ================== API：设备电量（采集/阈值/告警） ==================
+# 电量本身通过 /api/status 随设备列表一起下发（大屏/监控同一份数据）；
+# 这里是它的配置与采集器状态。低电量告警走通知子系统（事件 device.battery.low）。
+@bp.route("/api/devices/battery", methods=["GET"])
+@perm_required(PERM_DEVICES)
+def api_devices_battery():
+    """电量采集器状态 + 当前配置（面板显示"上次采集 12:00 · 14/14 台"）。"""
+    try:
+        return jsonify({"ok": True, **device_battery.get_status()})
+    except Exception as e:
+        _log.warning(f"电量状态获取失败: {e}")
+        return jsonify({"ok": False, "error": str(e)[:120]}), 503
+
+
+@bp.route("/api/devices/battery/settings", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_devices_battery_settings():
+    """保存电量监控配置：{enabled?, low?, critical?, skip_charging?, interval?}。"""
+    data = request.json or {}
+    ok, msg, saved = device_battery.save_settings(data)
+    if not ok:
+        return jsonify({"ok": False, "error": msg}), 400
+    return jsonify({"ok": True, "msg": msg, "settings": saved})
+
+
+@bp.route("/api/devices/battery/scan", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_devices_battery_scan():
+    """立即采集一次（后台执行，约 1-3 秒；看「上次采集」或大屏刷新确认）。"""
+    if not device_battery.scan_once():
+        return jsonify({"ok": False, "error": "上一轮采集还没跑完，稍等一下"}), 409
+    return jsonify({"ok": True, "msg": "采集已启动（约 1-3 秒）"})
+
+
 # 通过 Tailscale 官方 API v2 管理 tailnet 设备（列表/改名/授权/密钥不过期/删除/生成 auth key）。
 # 设备 IP 由 tailnet 自动分配，API 无法修改，列表只读展示。
 

web/monitor.py

@@ -6,8 +6,13 @@ import subprocess
 import shlex
 from concurrent.futures import ThreadPoolExecutor, as_completed
 
-from flask import (Blueprint, jsonify, request, Response, render_template)
+from flask import (Blueprint, jsonify, request, Response, render_template,
+                   render_template_string)
 from flask_login import login_required
+# /locate 定位页要把 serial 拼进 HTML，而 render_template_string 的模板名是
+# "<template>"、**不会自动转义**（serial 来自 query，不转义就是一个反射 XSS），
+# 所以这里显式转义。blueprint 拆分时漏掉了这两个 import，/locate 一直 500。
+from markupsafe import escape as _esc
 
 from core import device_pool
 from core.adb_helper import (screenshot, list_installed_apps, adb_connect,

web/tasks_api.py

@@ -7,9 +7,9 @@ from datetime import datetime
 from concurrent.futures import ThreadPoolExecutor, as_completed, TimeoutError as FuturesTimeout
 
 from flask import (Blueprint, jsonify, request, Response)
-from flask_login import login_required
+from flask_login import login_required, current_user
 
-from core import device_pool, uiauto_helper
+from core import device_pool, uiauto_helper, step_defaults, dedup
 from core.adb_helper import adb_connect_light
 from core.models import db, DeviceGroup, TaskJob, CustomAction
 from core.logger import get_logger
@@ -215,6 +215,161 @@ def api_groups_delete(name):
     return jsonify({"ok": False, "error": "分组不存在"}), 404
 
 
+# ================== API：录制手势（手机端真手指轨迹） ==================
+#
+# 用 getevent 读**真触屏**设备抓手指轨迹（见 core/gesture.py）。合成的注入事件不会
+# 出现在真触屏节点上，所以录到的只有人手的动作。
+# 录制器实例存在内存里（单进程；不落库——录完的点列由前端放进步骤/动作再保存）。
+
+_gesture_recorders = {}          # token -> PhoneRecorder
+_gesture_lock = threading.Lock()
+_GESTURE_TTL = 300               # 超过 5 分钟自动收摊，避免忘了点"停止"
+
+
+def _gesture_sweep():
+    """清掉超时的录制器（停止并释放 getevent 进程）。"""
+    now = time.time()
+    with _gesture_lock:
+        stale = [t for t, r in _gesture_recorders.items()
+                 if now - r._started > _GESTURE_TTL]
+        for t in stale:
+            _gesture_recorders.pop(t, None)
+    for t in stale:
+        try:
+            r.stop()
+        except Exception:
+            pass
+        _log.info("录制手势超时自动停止: %s", t)
+
+
+@bp.route("/api/gesture/record/start", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_gesture_record_start():
+    """开始录：{serial} → {token}。之后在手机屏幕上用手指划，停止时取回轨迹。"""
+    from core import gesture
+    _gesture_sweep()
+    serial = ((request.json or {}).get("serial") or "").strip()
+    if not serial:
+        return jsonify({"ok": False, "error": "缺少 serial"}), 400
+    with _gesture_lock:
+        if _gesture_recorders:
+            return jsonify({"ok": False, "error": "已有录制在进行中，先停止"}), 409
+    try:
+        w, h = 0, 0
+        try:
+            import uiautomator2 as u2
+            from core.u2_helper import screen_size
+            d = u2.connect(serial)
+            d.unlock()                           # 息屏时 u2 抓树会退化到几十秒，先唤醒
+            w, h = screen_size(d, serial)
+        except Exception as e:
+            _log.warning("录制前取屏幕尺寸失败（按原始坐标范围换算）: %s", e)
+        rec = gesture.PhoneRecorder(serial, w, h)
+        rec.start()
+    except Exception as e:
+        return jsonify({"ok": False, "error": f"开始录制失败: {e}"}), 502
+    token = uuid.uuid4().hex[:12]
+    with _gesture_lock:
+        _gesture_recorders[token] = rec
+    _log.info("开始录制手势: %s @ %s（%s）by %s", token, serial, rec.device,
+              getattr(current_user, "username", ""))
+    return jsonify({"ok": True, "token": token, "device": rec.device,
+                    "screen": [w, h],
+                    "msg": "现在请用手指在手机上划，划完点「停止」"})
+
+
+@bp.route("/api/gesture/record/stop", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_gesture_record_stop():
+    """停止录制：{token} → {gestures: [[[x,y,t_ms],...], ...]}。"""
+    token = ((request.json or {}).get("token") or "").strip()
+    with _gesture_lock:
+        rec = _gesture_recorders.pop(token, None)
+    if rec is None:
+        return jsonify({"ok": False, "error": "录制会话不存在或已超时"}), 404
+    try:
+        gestures = rec.stop()
+    except Exception as e:
+        return jsonify({"ok": False, "error": f"停止录制失败: {e}"}), 500
+    _log.info("停止录制手势: %s → %s 条", token, len(gestures))
+    return jsonify({"ok": True, "gestures": gestures, "count": len(gestures),
+                    "device": rec.device})
+
+
+# ================== API：步骤默认值（「动作配置」页） ==================
+#
+# 存 app_meta.step_defaults 一个键（不建表），校验与合并都在 core/step_defaults.py。
+
+@bp.route("/api/step_defaults")
+@login_required
+def api_step_defaults_get():
+    """生效的默认值 + 出厂值 + 字段规格（前端画表单用）。"""
+    return jsonify({"ok": True, **step_defaults.as_payload()})
+
+
+@bp.route("/api/step_defaults", methods=["POST"])
+@perm_required(PERM_TASKS)
+def api_step_defaults_save():
+    """保存默认值（只落与出厂值不同的字段，便于以后出厂值升级能跟着走）。"""
+    data = request.json or {}
+    ok, msg = step_defaults.save(data.get("defaults") or data)
+    if not ok:
+        return jsonify({"ok": False, "error": msg}), 400
+    _log.info("更新步骤默认值 by %s: %s", getattr(current_user, "username", ""),
+              list((data.get("defaults") or data).keys()))
+    return jsonify({"ok": True, "msg": msg, **step_defaults.as_payload()})
+
+
+# ================== API：去重记录（「任务 → 去重记录」页） ==================
+#
+# 账本在 done_mark 表（跨设备幂等，见 core/dedup.py）；任务步骤怎么用它见
+# tasks/generic/task.py 的 `_exec_mark_done` 与 if_el 的 `selector_type=dedup`。
+
+@bp.route("/api/done_marks")
+@login_required
+def api_done_marks():
+    """去重记录列表 + 统计（?job=<任务ID> 只看某个任务）。"""
+    job_id = (request.args.get("job") or "").strip()
+    try:
+        limit = int(request.args.get("limit") or 200)
+    except ValueError:
+        limit = 200
+    try:
+        rows, stats = dedup.list_marks(job_id, limit)
+    except Exception as e:
+        _log.warning(f"读取去重记录失败: {e}")
+        return jsonify({"ok": False, "error": str(e)[:120]}), 503
+    return jsonify({"ok": True, "marks": rows, "stats": stats, "job_id": job_id})
+
+
+@bp.route("/api/done_marks/delete", methods=["POST"])
+@perm_required(PERM_TASKS)
+def api_done_marks_delete():
+    """删一条记录 → 那个号/那台设备可以重跑。"""
+    data = request.json or {}
+    mark_id = data.get("id")
+    if mark_id in (None, ""):
+        return jsonify({"ok": False, "error": "缺少 id"}), 400
+    if not dedup.delete_mark(mark_id):
+        return jsonify({"ok": False, "error": "记录不存在或删除失败"}), 404
+    _log.info("删除去重记录 #%s by %s", mark_id, getattr(current_user, "username", ""))
+    return jsonify({"ok": True, "msg": "已删除（该设备/身份下次会重新执行）"})
+
+
+@bp.route("/api/done_marks/clear", methods=["POST"])
+@perm_required(PERM_TASKS)
+def api_done_marks_clear():
+    """清空某个任务的全部记录 → 整批重跑。"""
+    data = request.json or {}
+    job_id = (data.get("job") or "").strip()
+    if not job_id:
+        return jsonify({"ok": False, "error": "缺少任务ID"}), 400
+    n = dedup.clear_job(job_id)
+    _log.info("清空去重记录：任务 %s 共 %s 条 by %s", job_id, n,
+              getattr(current_user, "username", ""))
+    return jsonify({"ok": True, "msg": f"已清空 {n} 条记录（该任务下次会全部重跑）", "deleted": n})
+
+
 # ================== API：用户管理 CRUD ==================
 
 @bp.route("/api/custom_actions")
@@ -354,6 +509,16 @@ def api_uiauto_devices():
         })
         seen.add(serial)
         added += 1
+    # 设备名用**平台起的名字**（A08 / cs1）：uiautodev 那份 name 是设备自己的
+    # codename（实测一柜子机器全叫 "earth"），同型号好几台时等于没有——
+    # 而抓取元素/试执行必须选对设备，所以池外设备宁可退回地址（地址至少唯一）。
+    try:
+        names = {d["serial"]: (d.get("name") or "") for d in device_pool.list_devices()}
+    except Exception:
+        names = {}
+    for d in data:
+        s = d.get("serial") or ""
+        d["name"] = names.get(s) or s
     if added:
         _log.info(f"抓取元素设备列表补全 {added} 台在线设备: {list(seen)}")
     return jsonify({"ok": True, "devices": data})

web/tools_api.py

@@ -1,7 +1,11 @@
-"""工具域 API：adb 终端/剪贴板注入/应用版本。"""
+"""工具域 API：adb 终端/剪贴板注入/应用版本/大屏「发布」注入素材。"""
+import os
 import re
+import shutil
 import subprocess
 import shlex
+import tempfile
+import uuid
 from concurrent.futures import ThreadPoolExecutor, as_completed
 
 from flask import Blueprint, jsonify, request
@@ -11,7 +15,7 @@ from core.adb_helper import adb_connect, adb_connect_light, _ADB_LOCK, _adb
 from config import ADB_PATH
 from core.logger import get_logger
 from web import context
-from web.auth import admin_required, perm_required
+from web.auth import admin_required, perm_required, PERM_DEVICES
 from web.common import _merged_device_list
 
 _log = get_logger("web")
@@ -99,6 +103,101 @@ def _set_device_clipboard(serial, text):
     return inject_clipboard(serial, text)
 
 
+@bp.route("/api/tools/push_clipboard", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_tools_push_clipboard():
+    """大屏「发布」面板：往指定设备注入剪贴板文字。
+
+    与 `/api/tools/clipboard/set` 是**同一个实现**（`_set_device_clipboard`），
+    只是权限按「设备」位放行 —— 大屏上随手把一段文案抄到手机上，是设备操作，
+    不该要求管理员位。请求：`{"serial": "..."}` 或 `{"serials": ["..."]}`，外加 `text`。
+    """
+    data = request.json or {}
+    text = (data.get("text") or "").strip()
+    serials = data.get("serials")
+    if not isinstance(serials, list) or not serials:
+        one = (data.get("serial") or "").strip()
+        serials = [one] if one else []
+    if not serials:
+        return jsonify({"ok": False, "error": "未选择设备"}), 400
+    if not text:
+        return jsonify({"ok": False, "error": "注入内容不能为空"}), 400
+    results = {}
+    for serial in serials:
+        ok, msg = _set_device_clipboard(serial, text)
+        results[serial] = {"ok": ok, "msg": msg}
+    ok_count = sum(1 for v in results.values() if v["ok"])
+    return jsonify({"ok": ok_count == len(results), "results": results,
+                    "ok_count": ok_count, "fail_count": len(results) - ok_count,
+                    "msg": "已注入 %d 台" % ok_count if ok_count else "注入失败",
+                    "error": None if ok_count == len(results)
+                             else "%d 台注入失败" % (len(results) - ok_count)})
+
+
+@bp.route("/api/tools/push_material", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_tools_push_material():
+    """大屏「发布」面板：把上传的**视频/图片直接推到指定那台设备**的相册。
+
+    form-data：`file`（视频/图片）、`serial`、`album_dir`（可省，默认 /sdcard/DCIM/Camera）
+    返回 `{ok, msg, remote, verify}`
+
+    与「发布计划 → 推送」的区别：那条是**按计划**推（原子占位、去重、回写状态、
+    按账号名找设备）；这条是**临时手动推一个文件** —— 给"手上有一段素材，想马上
+    在这台机器上发"用，所以**不占位、不写库**，手机相册里就多一个文件
+    （名字带 `wall` 前缀，和计划推送的素材分得开）。
+
+    为什么还要 u2 连接：推完要 `touch` 改时间（相册/抖音按时间倒序，"第一个素材"
+    才是刚推的这个）+ 校验进没进相册索引 —— 这些都走设备 shell，见 publish_flow。
+    """
+    from core import video_plan as vp
+    from tasks.generic.publish_flow import ALBUM_DIR, push_video, verify_pushed
+    from core.account_probe import _connect
+
+    f = request.files.get("file")
+    serial = (request.form.get("serial") or "").strip()
+    album_dir = (request.form.get("album_dir") or "").strip() or ALBUM_DIR
+    if not serial:
+        return jsonify({"ok": False, "error": "未选择设备"}), 400
+    if not f or not f.filename:
+        return jsonify({"ok": False, "error": "未选择文件"}), 400
+    ext = os.path.splitext(f.filename)[1].lower()
+    if ext not in vp.MEDIA_EXTS:
+        return jsonify({"ok": False, "error": "只支持视频/图片（%s），当前 %s"
+                        % ("、".join(vp.MEDIA_EXTS), ext or "无扩展名")}), 400
+    try:
+        online = set(device_pool.list_online())
+    except Exception:
+        online = set()
+    if online and serial not in online:
+        return jsonify({"ok": False, "error": "这台设备当前不在线"}), 400
+
+    tmpdir = tempfile.mkdtemp(prefix="wall_push_")
+    local = os.path.join(tmpdir, vp.safe_name(f.filename))
+    try:
+        f.save(local)
+        size = os.path.getsize(local)
+        d = _connect(serial, timeout=25)
+        remote, err = push_video(d, serial, local, "wall" + uuid.uuid4().hex[:8],
+                                 album_dir=album_dir)
+        if err:
+            return jsonify({"ok": False, "error": err})
+        verify, vmsg = verify_pushed(d, remote)
+        if verify == "nofile":
+            return jsonify({"ok": False, "error": "推送校验失败：%s" % vmsg})
+        ok = verify == "ok"
+        _log.info("大屏发布：%s ← %s（%d 字节）→ %s [%s]"
+                  % (serial, f.filename, size, remote, verify))
+        return jsonify({"ok": True, "remote": remote, "verify": verify, "size": size,
+                        "msg": "已推到 %s" % remote if ok else "已推到 %s（⚠ %s）" % (remote, vmsg)})
+    except Exception as e:
+        _log.warning("大屏发布失败: %s: %s" % (type(e).__name__, e))
+        return jsonify({"ok": False, "error": "推送异常: %s: %s"
+                        % (type(e).__name__, str(e)[:120])})
+    finally:
+        shutil.rmtree(tmpdir, ignore_errors=True)
+
+
 def _app_ver_on_device(serial, pkg):
     """单设备包版本查询：pm path 检查安装 → dumpsys 取 versionName/versionCode。
 

web/video_plan_api.py

@@ -0,0 +1,554 @@
+"""视频发布计划 API（「发布计划」页）。
+
+数据在 `video_plan` 表、服务层 `core/video_plan.py`；任务侧怎么自动发布见
+`tasks/generic/task.py` 的 `_exec_publish_video`（本文件的「立即发布」调的是同一段逻辑）。
+
+红线（与 `core/video_plan.py` 顶部一致）：发布前必须原子占位；失败要分
+"推文件阶段（可重试）"与"抖音阶段（结果未知、绝不自动重试）"两类。
+"""
+import csv
+import io
+
+from flask import Blueprint, jsonify, request, send_file
+
+from core import video_plan as vp
+from core.logger import get_logger
+from web.auth import perm_required, PERM_DEVICES, PERM_TASKS
+
+_log = get_logger("web")
+bp = Blueprint("video_plan", __name__)
+
+
+@bp.route("/api/video_plan/upload_video", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_vp_upload_video():
+    """上传单个素材（**视频或图片**；前端**逐文件**发，才能给每个文件一条结果与进度）。
+
+    文件名规则 `名字_日期_编号`（编号可省略，名字 = 抖音昵称，不查台账）。
+    视频与图片同一套规则、同一条发布流程（图片走抖音「图文」）；扩展名一路带到手机上，
+    抖音按它判断这是视频还是图片。
+    """
+    f = request.files.get("file")
+    if not f or not f.filename:
+        return jsonify({"ok": False, "error": "没收到文件"}), 400
+    replace = str(request.form.get("replace") or "") in ("1", "true", "yes")
+    order = request.form.get("order")
+    result = vp.upload_video(f, order=order, replace=replace)
+    if not result.get("ok"):
+        return jsonify(result), 400
+    return jsonify(result)
+
+
+@bp.route("/api/video_plan/upload_titles", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_vp_upload_titles():
+    """上传标题：`{text, dry_run}`；也接受 multipart 的 txt 文件（字段名 file）。
+
+    每行 `标题 || 正文_名字_日期_编号`（`||` 后面是正文、可省略；编号可省略、标题里可以有下划线）；
+    `#` 开头的行**只有认不出名字/日期时才当注释**（`#话题` 开头的标题照收）。
+    """
+    if request.files.get("file"):
+        raw = request.files["file"].stream.read()
+        try:
+            text = raw.decode("utf-8")
+        except UnicodeDecodeError:
+            text = raw.decode("gbk", errors="replace")
+        dry = str(request.form.get("dry_run") or "") in ("1", "true", "yes")
+    else:
+        data = request.json or {}
+        text = data.get("text") or ""
+        dry = bool(data.get("dry_run"))
+    if not text.strip():
+        return jsonify({"ok": False, "error": "内容是空的"}), 400
+    result = vp.import_titles(text, dry_run=dry)
+    return jsonify(result)
+
+
+@bp.route("/api/video_plan/timeline")
+@perm_required(PERM_DEVICES)
+def api_vp_timeline():
+    """时间线：?range=today|week|all &from=&to=&status=&q=&limit="""
+    rng = (request.args.get("range") or "").strip()
+    today = vp._today()
+    date_from = (request.args.get("from") or "").strip()
+    date_to = (request.args.get("to") or "").strip()
+    if rng == "today" and not date_from:
+        date_from = date_to = today
+    elif rng == "week" and not date_from:
+        import time as _t
+        date_from = today
+        date_to = _t.strftime("%Y-%m-%d", _t.localtime(_t.time() + 7 * 86400))
+    data = vp.timeline(date_from, date_to,
+                       status=(request.args.get("status") or "").strip(),
+                       q=(request.args.get("q") or "").strip(),
+                       limit=int(request.args.get("limit") or 500))
+    return jsonify({"ok": True, **data})
+
+
+@bp.route("/api/video_plan/stats")
+@perm_required(PERM_DEVICES)
+def api_vp_stats():
+    """顶部统计（今天要发/已发/待标题/过期未发 + 素材占用与磁盘余量）。"""
+    return jsonify({"ok": True, "stats": vp.stats(), "disk": vp.disk_info(),
+                    "today": vp._today()})
+
+
+@bp.route("/api/video_plan/<pid>", methods=["GET", "PUT", "DELETE"])
+@perm_required(PERM_DEVICES)
+def api_vp_one(pid):
+    if request.method == "GET":
+        row = vp.get_plan(pid)
+        if not row:
+            return jsonify({"ok": False, "error": "计划不存在"}), 404
+        return jsonify({"ok": True, "plan": row})
+    if request.method == "DELETE":
+        if not vp.delete_plan(pid):
+            return jsonify({"ok": False, "error": "计划不存在"}), 404
+        return jsonify({"ok": True, "msg": "已删除（素材文件一并删除）"})
+    data = request.json or {}
+    if "title" in data or "body" in data or "nickname" in data:
+        row, err = vp.set_title(pid, data.get("title") or "", body=data.get("body"),
+                                nickname=data.get("nickname") if "nickname" in data else None)
+        if err:
+            bad = "太长" in err or "名字不对" in err
+            return jsonify({"ok": False, "error": err}), 400 if bad else 404
+        return jsonify({"ok": True, "msg": "标题/正文/名字已改", "plan": row})
+    return jsonify({"ok": False, "error": "没有要改的字段"}), 400
+
+
+@bp.route("/api/video_plan/<pid>/video")
+@perm_required(PERM_DEVICES)
+def api_vp_video(pid):
+    """预览平台上的素材（文件被清理后返回 410）。"""
+    import os
+    from flask import send_file as _send
+    row = vp.get_plan(pid)
+    if not row:
+        return jsonify({"ok": False, "error": "计划不存在"}), 404
+    path = vp._video_path(row.get("video_file"))
+    if not path or not os.path.exists(path):
+        return jsonify({"ok": False, "error": "素材文件已清理"}), 410
+    return _send(path, conditional=True)
+
+
+def _push_by_name(rows, serials=None):
+    """**按名字找设备**：把一批计划推到"现在登着这个名字的那台设备"上。
+
+    ① 计划按 `nickname` 分组；
+    ② **实时探测**在线设备当前登的号（`core.account_probe`，跳过正在跑任务的设备）；
+    ③ 名字 → 设备；找到就**每台设备一个线程、设备内串行**推（同一个手机同时推两个文件
+       会互相干扰：两条 adb push 抢带宽 + 两条 `content call scan_file` 抢相册索引）；
+    ④ 没有在线设备登着某个名字 → 进 `unmatched`，**如实报出来**（人要先去那台设备上切号）。
+
+    返回 `(matched, unmatched)`，推送本身在后台线程里跑（接口立刻返回）。
+    """
+    from core import account_probe, device_pool
+    from tasks.generic.publish_flow import push_one
+
+    by_name = {}
+    for row in rows:
+        by_name.setdefault(row.get("nickname") or "", []).append(row)
+
+    dev_names = {}
+    try:
+        for d in device_pool.list_devices():
+            dev_names[d.get("serial") or ""] = d.get("name") or ""
+    except Exception:
+        pass
+
+    probes = account_probe.probe_online(serials)
+    account_probe.cache_names(probes)      # 顺手存进 device 表（人工入口的设备建议用）
+    name2serial = {}
+    for serial, r in probes.items():
+        nm = (r or {}).get("name") or ""
+        if nm and nm not in name2serial:
+            name2serial[nm] = serial       # 同名多机：取第一台（下面的 dup 里说明）
+
+    by_serial, matched, unmatched = {}, [], []
+    for name, plans in by_name.items():
+        serial = name2serial.get(name)
+        if not serial:
+            who = "、".join(f"{s}({(v or {}).get('name')})"
+                            for s, v in sorted(probes.items()) if (v or {}).get("name")) \
+                or "没有在线设备"
+            unmatched.append({"name": name, "count": len(plans),
+                              "reason": f"没有在线设备登着『{name}』——先到设备上切到它"
+                                        f"（当前探测到：{who}）"})
+            continue
+        by_serial.setdefault(serial, []).extend(plans)
+        matched.append({"name": name, "count": len(plans), "serial": serial,
+                        "device_name": dev_names.get(serial, "")})
+
+    def _push_device(serial, plans, dname):
+        for row in plans:
+            try:
+                push_one(serial, row, {"device_name": dname})
+            except Exception as e:
+                _log.warning(f"按名字推送 {row.get('id')} 异常: {e}")
+
+    if rows:
+        import threading
+        for serial, plans in by_serial.items():
+            threading.Thread(target=_push_device,
+                             args=(serial, plans, dev_names.get(serial, "")),
+                             daemon=True).start()
+    return matched, unmatched
+
+
+@bp.route("/api/video_plan/<pid>/push", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_vp_push(pid):
+    """把这一条的素材**推到手机**（只推送，不在手机上发布）。
+
+    计划不绑设备了，所以这里**按名字找设备**：实时探测哪台在线设备现在登着这条计划的
+    名字，推给它；没有设备登着 → 400 说清"先去切号"。
+    """
+    row = vp.get_plan(pid)
+    if not row:
+        return jsonify({"ok": False, "error": "计划不存在"}), 404
+    if row["status"] in (vp.ST_PUSHING, vp.ST_PUBLISHING):
+        return jsonify({"ok": False, "error": "这条已经推到手机上了，别重复推"}), 409
+    if row["status"] == vp.ST_UNKNOWN:
+        return jsonify({"ok": False,
+                        "error": "这条上次结果未知（可能已经发出去了）—— 先去抖音确认，"
+                                 "再用「已发出 / 未发出」裁决"}), 409
+    matched, unmatched = _push_by_name([row])
+    if unmatched:
+        return jsonify({"ok": False, "error": unmatched[0]["reason"]}), 400
+    m = matched[0]
+    _log.info(f"推送素材到手机 video_plan {pid}（{row.get('nickname')} "
+              f"{row['release_date']}）→ {m['device_name'] or m['serial']}")
+    return jsonify({"ok": True, "device_name": m["device_name"],
+                    "msg": f"已开始推送到『{m['device_name'] or m['serial']}』"
+                           f"（推完状态变「已推送到手机」，之后你在手机上发；"
+                           f"发完点「标记已发布」）"})
+
+
+def _push_plans_by_account():
+    """`push_by_account` / `push_all` 两个路由的公共实现（避免"调用另一个视图"）。"""
+    data = request.json or {}
+    date = (data.get("date") or "").strip() or vp._today()
+    rows = vp.pushable_plans(date, retry_failed=bool(data.get("retry_failed", True)))
+    if not rows:
+        return jsonify({"ok": True, "count": 0, "devices": 0, "matched": [],
+                        "unmatched": [],
+                        "msg": f"{date} 没有待推送的计划（有标题的才推）"})
+    matched, unmatched = _push_by_name(rows, data.get("serials") or None)
+    if not matched:
+        return jsonify({"ok": False, "count": 0, "devices": 0, "matched": [],
+                        "unmatched": unmatched,
+                        "error": "没有在线设备登着这些号：" +
+                                 "、".join(f"{u['name']}({u['count']}条)" for u in unmatched) +
+                                 " —— 先到设备上切号，或到「工具 → 设备池」确认设备在线"}), 400
+    _log.info(f"一键推送（按名字）{date}：{len(rows)} 条 → {len(matched)} 个名字"
+              f"（没设备登着的 {len(unmatched)} 个名字已跳过）")
+    return jsonify({"ok": True, "count": sum(m["count"] for m in matched),
+                    "devices": len({m["serial"] for m in matched}),
+                    "matched": matched, "unmatched": unmatched,
+                    "msg": f"已开始推送 {sum(m['count'] for m in matched)} 条"
+                           f"（{len(matched)} 个号）"
+                           + (f"；{len(unmatched)} 个名字没有在线设备登着，见明细"
+                              if unmatched else "")})
+
+
+@bp.route("/api/video_plan/push_by_account", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_vp_push_by_account():
+    """**按名字找设备**的批量推送（「一键推送」）：某天所有待推的计划，谁登着谁推。
+
+    立刻返回受理条数（推送在后台跑）——进度与结果看时间线的状态徽章 /
+    「已推送·相册可见」标记。**没设备登着的名字**在 `unmatched` 里逐条说明。
+    """
+    return _push_plans_by_account()
+
+
+@bp.route("/api/video_plan/push_all", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_vp_push_all():
+    """老入口（前端旧版本还可能在调）：语义与 `push_by_account` 一致 —— 都按名字找设备。"""
+    return _push_plans_by_account()
+
+
+@bp.route("/api/video_plan/<pid>/mark", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_vp_mark(pid):
+    """人工标记结果：`{status: done|failed|unknown, why}`（推送到手机之后用）。"""
+    data = request.json or {}
+    st = (data.get("status") or "").strip()
+    if st not in (vp.ST_DONE, vp.ST_FAILED, vp.ST_UNKNOWN):
+        return jsonify({"ok": False, "error": "status 只能是 done / failed / unknown"}), 400
+    why = (data.get("why") or "").strip()
+    row, err = vp.set_status(pid, st, note=why)
+    if err:
+        return jsonify({"ok": False, "error": err}), 400
+    _log.info(f"人工标记 video_plan {pid} → {st}")
+    return jsonify({"ok": True, "msg": "已标记", "plan": row})
+
+
+@bp.route("/api/video_plan/<pid>/<action>", methods=["POST"])
+@perm_required(PERM_DEVICES)
+def api_vp_action(pid, action):
+    """单条操作：skip 跳过 / retry 重试（failed→ready）/ resolve 裁决 unknown。"""
+    data = request.json or {}
+    if action == "skip":
+        row, err = vp.set_status(pid, vp.ST_SKIPPED, note=data.get("reason") or "")
+        msg = "已跳过"
+    elif action == "retry":
+        row, err = vp.set_status(pid, vp.ST_READY, note="人工重试")
+        msg = "已放回待发布（尝试次数已清零）"
+    elif action == "resolve":
+        row, err = vp.resolve_unknown(pid, bool(data.get("published")),
+                                      note=data.get("note") or "")
+        msg = "已记为「已发出」" if data.get("published") else "已记为「未发出」（可重试）"
+    else:
+        return jsonify({"ok": False, "error": f"未知操作 {action}"}), 400
+    if err:
+        return jsonify({"ok": False, "error": err}), 400
+    return jsonify({"ok": True, "msg": msg, "plan": row})
+
+
+def _norm_target(target):
+    """规范化任务目标。**分组键必须是 `group_name`** —— `TaskJob.resolve_serials()`
+    只认这个键，写成 `group` 会静默解析出 0 台设备（任务"跑完了"但谁也没跑）。"""
+    t = dict(target or {})
+    mode = (t.get("mode") or "all").strip()
+    out = {"mode": mode}
+    if mode == "group":
+        out["group_name"] = (t.get("group_name") or t.get("group") or "").strip()
+    elif mode == "serial":
+        out["serial"] = (t.get("serial") or "").strip()
+    return out
+
+
+def _target_error(target):
+    if target["mode"] not in ("all", "group", "serial"):
+        return "目标只能是 全部/分组/单设备"
+    if target["mode"] == "group" and not target.get("group_name"):
+        return "选了「设备分组」但没指定分组名"
+    if target["mode"] == "serial" and not target.get("serial"):
+        return "选了「单台设备」但没指定设备"
+    return ""
+
+
+def _parse_hhmm(text):
+    try:
+        h, m = [int(x) for x in str(text).split(":")]
+        assert 0 <= h < 24 and 0 <= m < 60
+        return h, m, ""
+    except Exception:
+        return 0, 0, "时间格式应为 HH:MM"
+
+
+def _count_steps(steps):
+    """步骤总数（**含嵌套**：条件判断的 then/else、循环块里的）—— 界面上给人看的数字，
+    只数顶层会让人以为任务很短（骨架顶层 4 步、实际 14 步）。"""
+    n = 0
+    for s in steps or []:
+        if not isinstance(s, dict):
+            continue
+        n += 1
+        p = s.get("params") or {}
+        for k in ("then", "else", "children"):
+            n += _count_steps(p.get(k) or [])
+    return n
+
+
+def _job_brief(j, mgr):
+    """任务摘要（列表用）+ 步骤（就地编辑用）。"""
+    steps = (j.params or {}).get("steps") or []
+    try:
+        nxt = mgr.next_run_of(j)
+        nxt = nxt.strftime("%Y-%m-%d %H:%M") if nxt else ""
+    except Exception:
+        nxt = ""
+    sch = j.schedule or {}
+    return {"id": j.id, "name": j.name, "enabled": bool(j.enabled),
+            "mode": sch.get("mode", "once"), "cron": sch.get("cron", ""),
+            "next_run": nxt, "target": j.target, "steps": steps,
+            "step_count": _count_steps(steps),
+            "retry": j.retry or {},
+            "schedule": sch}
+
+
+@bp.route("/api/video_plan/tasks")
+@perm_required(PERM_DEVICES)
+def api_vp_tasks():
+    """**可编辑的任务列表** —— 「发布计划」页顶部那一块。
+
+    返回**全部通用步骤任务**，每条带 `is_release`（含「推送/标记发布结果」= 发布任务）：
+    - 只列发布任务的话，手写的抖音发布流程（自己点相册/输入框/发布，没有平台的
+      `push_release` 步骤）就会**一条都不显示** —— 人会以为"这页没有能改的地方"
+    - 界面上按 `is_release` 分成两组：上面「发布任务」，下面「其它任务」也能就地改步骤
+
+    带上完整 `steps`：这一页要**就地编辑**这些步骤（抓选择器），不用再跳「任务」页。
+    """
+    from web import context
+    release, other = [], []
+    try:
+        jobs = list((context.mgr.jobs or {}).values())
+    except Exception:
+        jobs = []
+    for j in jobs:
+        # 只有通用步骤任务有步骤可编（其它任务类型的 params 是另一套）
+        if getattr(j, "task_type", "generic_steps") != "generic_steps":
+            continue
+        b = _job_brief(j, context.mgr)
+        b["is_release"] = vp.is_release_task((j.params or {}).get("steps") or [])
+        b["has_push"] = vp.has_push_step((j.params or {}).get("steps") or [])
+        (release if b["is_release"] else other).append(b)
+    release.sort(key=lambda x: x["name"])
+    other.sort(key=lambda x: x["name"])
+    return jsonify({"ok": True, "tasks": release + other,
+                    "release_count": len(release), "other_count": len(other)})
+
+
+@bp.route("/api/video_plan/tasks", methods=["POST"])
+@perm_required(PERM_TASKS)
+def api_vp_task_create():
+    """一键新建「标准发布任务」：账号校验 → 推送 → 抖音点击（占位待你抓）→ 填标题 → 标记。
+
+    请求：{"name": "发布视频", "target": {"mode":"all"|"group"|"serial", …},
+           "time": "10:00", "enabled": true}
+    **走 TaskManager 建**（内存 + 库一起更新）—— 直接写库的话调度器不认。
+    """
+    from web import context
+    data = request.json or {}
+    name = (data.get("name") or "发布视频").strip()[:120]
+    target = _norm_target(data.get("target"))
+    err = _target_error(target)
+    if err:
+        return jsonify({"ok": False, "error": err}), 400
+    h, m, err = _parse_hhmm((data.get("time") or "10:00").strip())
+    if err:
+        return jsonify({"ok": False, "error": err}), 400
+    schedule = {"mode": "cron", "cron": f"{m} {h} * * *", "stop_cron": "",
+                "window": {"start": "", "end": ""}}
+    params = {"steps": vp.build_release_steps(),
+              "dedup_reset": "day", "dedup_hours": 6,
+              "preempt": False, "skip_offline": True, "max_duration": 0}
+    try:
+        job = context.mgr.add_job(name=name, task_type="generic_steps", target=target,
+                                  params=params, schedule=schedule,
+                                  retry={"max_attempts": 1, "delay": 60},
+                                  enabled=bool(data.get("enabled", True)))
+    except Exception as e:
+        _log.warning(f"新建发布任务失败: {e}")
+        return jsonify({"ok": False, "error": f"创建失败: {str(e)[:120]}"}), 500
+    _log.info(f"新建发布任务 {job.name}({job.id})，每天 "
+              f"{h:02d}:{m:02d}，目标 {target}")
+    return jsonify({"ok": True, "msg": f"已创建「{name}」（每天 {h:02d}:{m:02d} 跑）——"
+                                       f"就在下面这一块把抖音那几步的选择器抓一下就能用了",
+                    "job_id": job.id, "task": _job_brief(job, context.mgr)})
+
+
+@bp.route("/api/video_plan/tasks/<job_id>/adopt", methods=["POST"])
+@perm_required(PERM_TASKS)
+def api_vp_task_adopt(job_id):
+    """给**已有任务**插上平台那两步（`push_release` 放最前、`mark_release` 放最后）。
+
+    手写的抖音发布流程常缺这两步：不插的话计划页的视频永远不会被推到手机、
+    发布结果也不会回写状态。**中间你自己的步骤一步不动**（位置理由见
+    `core.video_plan.insert_release_steps`）。
+    """
+    from web import context
+    job = (context.mgr.jobs or {}).get(job_id)
+    if not job:
+        return jsonify({"ok": False, "error": "任务不存在"}), 404
+    if getattr(job, "task_type", "generic_steps") != "generic_steps":
+        return jsonify({"ok": False, "error": "只有「通用步骤」任务能插平台发布步骤"}), 400
+    steps = (job.params or {}).get("steps") or []
+    if not steps:
+        return jsonify({"ok": False, "error": "这个任务没有步骤，先去「任务」页把抖音流程画好"}), 400
+    if vp.has_push_step(steps) and vp.has_mark_step(steps):
+        return jsonify({"ok": False, "error": "这个任务已经有平台发布步骤了"}), 409
+    params = dict(job.params or {})
+    params["steps"] = vp.insert_release_steps(steps)
+    try:
+        context.mgr.update_job(job_id, params=params)
+    except Exception as e:
+        _log.warning(f"给任务 {job_id} 插平台发布步骤失败: {e}")
+        return jsonify({"ok": False, "error": f"保存失败: {str(e)[:120]}"}), 500
+    _log.info(f"给任务 {job.name}({job_id}) 插上平台发布步骤")
+    return jsonify({"ok": True, "msg": "已插入「推送发布视频」（最前）与「标记发布结果」（最后）——"
+                                       "你原来的步骤没动；到「发布计划」里核对一下顺序",
+                    "task": _job_brief(job, context.mgr)})
+
+
+@bp.route("/api/video_plan/tasks/<job_id>", methods=["GET", "PUT"])
+@perm_required(PERM_TASKS)
+def api_vp_task_one(job_id):
+    """就地编辑发布任务（「发布计划」页里，不用跳「任务」页）。
+
+    只放开这一页用得上的字段：`name` / `time`(HH:MM) / `target` / `steps` / `enabled`。
+    **没传的字段原样保留**（深合并：`params` 里还有去重有效期、抢占等通用参数，
+    整块覆盖会把它们抹掉）。底层仍是 `context.mgr.update_job()` —— 内存 + 库一起改，
+    否则调度器不认（直接写库的坑见 `core/task_manager` 的 `_save_jobs`）。
+    """
+    from web import context
+    job = (context.mgr.jobs or {}).get(job_id)
+    if not job:
+        return jsonify({"ok": False, "error": "任务不存在"}), 404
+    if request.method == "GET":
+        return jsonify({"ok": True, "task": _job_brief(job, context.mgr)})
+    data = request.json or {}
+    fields = {}
+    if "name" in data:
+        nm = (data.get("name") or "").strip()[:120]
+        if not nm:
+            return jsonify({"ok": False, "error": "任务名不能为空"}), 400
+        fields["name"] = nm
+    if "target" in data:
+        target = _norm_target(data.get("target"))
+        err = _target_error(target)
+        if err:
+            return jsonify({"ok": False, "error": err}), 400
+        fields["target"] = target
+    if "enabled" in data:
+        fields["enabled"] = bool(data.get("enabled"))
+    if "time" in data:
+        h, m, err = _parse_hhmm((data.get("time") or "").strip())
+        if err:
+            return jsonify({"ok": False, "error": err}), 400
+        sch = dict(job.schedule or {})
+        sch["mode"] = "cron"
+        sch["cron"] = f"{m} {h} * * *"
+        sch.setdefault("stop_cron", "")
+        sch.setdefault("window", {"start": "", "end": ""})
+        fields["schedule"] = sch
+    if "steps" in data:
+        steps = data.get("steps")
+        if not isinstance(steps, list):
+            return jsonify({"ok": False, "error": "steps 必须是数组"}), 400
+        params = dict(job.params or {})
+        params["steps"] = steps
+        fields["params"] = params
+    if not fields:
+        return jsonify({"ok": False, "error": "没有要改的字段"}), 400
+    try:
+        context.mgr.update_job(job_id, **fields)
+    except Exception as e:
+        _log.warning(f"改发布任务 {job_id} 失败: {e}")
+        return jsonify({"ok": False, "error": f"保存失败: {str(e)[:120]}"}), 500
+    _log.info(f"改发布任务 {job.name}({job_id})：{'/'.join(fields)}")
+    return jsonify({"ok": True, "msg": "已保存", "task": _job_brief(job, context.mgr)})
+
+
+@bp.route("/api/video_plan/links")
+@perm_required(PERM_DEVICES)
+def api_vp_links():
+    """已发布作品的分享链接（界面展示 / `format=csv` 导出，给后续铺评论用）。"""
+    rows = vp.links(date_from=(request.args.get("from") or "").strip(),
+                    date_to=(request.args.get("to") or "").strip(),
+                    name=(request.args.get("name") or "").strip())
+    if (request.args.get("format") or "") == "csv":
+        buf = io.StringIO()
+        w = csv.writer(buf)
+        # 按**名字**导出（手机号/抖音号随台账停用一起下线；由谁发的看 posted_device_name）
+        w.writerow(["发布日期", "名字", "编号", "标题", "正文", "分享链接", "发布时间"])
+        for r in rows:
+            w.writerow([r["release_date"], r["nickname"], r["seq"], r["title"],
+                        r.get("body", ""), r["share_url"], r["published_at"]])
+        data = ("" + buf.getvalue()).encode("utf-8")   # BOM：Excel 打开中文不乱码
+        return send_file(io.BytesIO(data), mimetype="text/csv", as_attachment=True,
+                         download_name=f"video_links_{vp._today()}.csv")
+    return jsonify({"ok": True, "links": rows, "count": len(rows)})

web_server.py

@@ -35,6 +35,7 @@ app.config["SECRET_KEY"] = _web_secret
 app.config["TEMPLATES_AUTO_RELOAD"] = True
 # 数据库目标与连接参数统一由 core/db_config 装配（.env 的 DEPLOY_ENV / DB_* 决定）。
 # 这里就把配置校验做完：连不上、环境与库名不匹配 → 直接拒绝启动，不要带着错配置跑起来。
+from config import MAX_CONTENT_LENGTH as _MAX_UPLOAD
 from core import db_config
 try:
     _DB_URI = db_config.build_db_uri()
@@ -45,11 +46,26 @@ except db_config.DBConfigError as _e:
 app.config["SQLALCHEMY_DATABASE_URI"] = _DB_URI
 app.config["SQLALCHEMY_ENGINE_OPTIONS"] = db_config.engine_options(_DB_URI)
 app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
+# 单次请求体上限（视频发布计划要传几百 MB 的视频素材）。
+# 默认 2GiB：**必须大于现有 APK 上传的最大包（实测 336MB）**，否则会把「应用管理」的
+# APK 上传一起卡死。原来是没设的（Werkzeug 默认无上限）—— 现在有了上限，
+# 超限必须回 **JSON**（见下面 413 处理器），否则前端 JSON.parse 会炸成
+# "解析响应失败"，用户看不出是文件太大。
+app.config["MAX_CONTENT_LENGTH"] = _MAX_UPLOAD
 
 login_manager = LoginManager(app)
 login_manager.login_view = "auth.login"  # 蓝图化后路由前缀 auth
 
 
+@app.errorhandler(413)
+def _payload_too_large(e):
+    """上传超限要说人话（默认返回 HTML，前端 JSON.parse 会炸成"解析响应失败"）。"""
+    from flask import jsonify as _jsonify
+    mb = _MAX_UPLOAD // (1024 * 1024)
+    return _jsonify({"ok": False,
+                     "error": f"文件太大：单次上传上限 {mb} MB（可在 .env 里调 MAX_UPLOAD_MB）"}), 413
+
+
 def _consume_pending_restore():
     """消费「待生效的备份恢复」（若存在 data/restore_pending/users.db）。
 
@@ -73,6 +89,12 @@ try:
     _notifier.init_app(app)
 except Exception as _e:            # 通知出问题不影响启动
     _log.warning(f"通知模块初始化失败（不影响启动）: {_e}")
+# 任务步骤明细：起一个专用写线程，任务线程只入队（见 core/step_log.py）
+try:
+    from core import step_log as _step_log
+    _step_log.init_app(app)
+except Exception as _e:
+    _log.warning(f"步骤明细模块初始化失败（不影响启动）: {_e}")
 # 消费「待生效的备份恢复」——必须在 init_db 之后（表已建好，且现在是事务替换而非换文件）
 _consume_pending_restore()
 # 库环境标签校验 + 启动横幅：每次启动都明确写出「现在连的是哪个库」，
@@ -92,10 +114,22 @@ device_pool.init_app(app)
 # 设备自动发现：定时扫描网段 → 待连接池（确认后才入池）
 from core import device_discovery
 device_discovery.init_app(app)
+# 设备电量采集：定时 dumpsys battery（只读）→ 内存缓存 → /api/status 展示 + 低电量告警
+from core import device_battery
+device_battery.init_app(app)
+# 去重账本（跨设备幂等）：绑 app 供任务线程/Web/清理任务自推 context
+from core import dedup
+dedup.init_app(app)
+# 视频发布计划：绑 app 供任务线程（发布步骤）/ Web / 清理 job 自推 context
+from core import video_plan
+video_plan.init_app(app)
 mgr = TaskManager(app=app)
 # 设备换地址（认领/迁址）后同步分组与任务的引用：它们的"内存副本"在 TaskManager 里
 # （调度用内存对象），device_pool 只改库不改内存不生效，所以在此注册回调打通
 device_pool.set_move_hook(mgr.sync_device_serial)
+# 通知里要显示设备名（A08）而不是地址（IP）：notifier 只读 device_pool 的**内存**名称
+# 快照，不查库（notify 的红线是零 DB）。快照在 device_pool.init_app 里已刷过一次。
+_notifier.set_device_name_resolver(device_pool.name_of)
 apk_mgr = ApkManager(app=app)
 
 # Web 层按模块拆分（web/ 蓝图包）：认证/监控/任务/管理/工具/设备池/APK/Tailscale
@@ -104,6 +138,67 @@ from web.auth import _csrf_protect, _csrf_token
 context.init(mgr, apk_mgr, device_pool)
 register_blueprints(app)
 
+def _purge_step_log():
+    """清理超期的任务步骤明细（启动时 + 每日 04:13）。
+
+    app context 由本函数自建：APScheduler 的作业跑在调度线程里，没有请求上下文。
+    """
+    try:
+        from core.step_log import purge_old
+        with app.app_context():
+            purge_old()
+    except Exception as e:
+        _log.warning(f"步骤明细清理失败（不影响主服务）: {e}")
+
+
+def _purge_step_log_async():
+    """启动时后台清理一次（不阻塞启动；服务若频繁重启，定时任务可能一直轮不到）。"""
+    threading.Thread(target=_purge_step_log, daemon=True).start()
+
+
+def _purge_done_mark():
+    """清理过期的去重记录（每日 04:23）。
+
+    **只清 day/hours 桶**：`kind='all'`（"只做一次"）的记录清了就等于去重失效，
+    见 core/dedup.purge_old。量级很小（设备数 × 天数），单条 DELETE 足够。
+    """
+    try:
+        from core.dedup import purge_old
+        with app.app_context():
+            purge_old()
+    except Exception as e:
+        _log.warning(f"去重记录清理失败（不影响主服务）: {e}")
+
+
+def _purge_video_plan():
+    """发布计划：僵尸占位回收 + 过期行清理（每日 04:41）。
+
+    僵尸回收是**必须有的一步**：占位（pushing/publishing）后崩溃的话，没有它
+    这条计划永远停在"发布中"，再也不会被取到 —— 表现成"这个号就是不发"。
+    """
+    try:
+        from core.video_plan import reclaim_zombies, purge_plan
+        with app.app_context():
+            reclaim_zombies()
+            purge_plan()
+    except Exception as e:
+        _log.warning(f"发布计划清理失败（不影响主服务）: {e}")
+
+
+def _purge_video_files():
+    """发布计划：平台素材文件清理（每日 04:47）。
+
+    **只删"已发布 + 已抓到分享链接 + 超过保留期"的**：没抓到链接的一律留着
+    （链接与素材至少留一个），未发布/失败/未知的更不删。
+    """
+    try:
+        from core.video_plan import purge_files
+        with app.app_context():
+            purge_files()
+    except Exception as e:
+        _log.warning(f"发布素材清理失败（不影响主服务）: {e}")
+
+
 # 经验库每日 AI 巡检（凌晨 03:47）：评审标记疑似问题经验，删除只走人工确认。
 # 巡检线程在 run_experience_audit 内自建 app context，不依赖这里。
 try:
@@ -112,6 +207,15 @@ try:
     from web.agent_api import run_experience_audit
     _audit_sched = BackgroundScheduler(timezone="Asia/Shanghai")
     _audit_sched.add_job(run_experience_audit, CronTrigger(hour=3, minute=47))
+    # 步骤明细清理：超过保留期（core/step_log.KEEP_DAYS）的记录每天删一次。
+    # 不清理的话这张表是唯一无界增长的表，会一路顶大备份包。
+    _audit_sched.add_job(_purge_step_log, CronTrigger(hour=4, minute=13))
+    # 去重记录清理：只清 day/hours 桶（all 永不清理，清了等于"只做一次"失效）
+    _audit_sched.add_job(_purge_done_mark, CronTrigger(hour=4, minute=23))
+    # 发布计划：僵尸占位回收 + 过期行清理（04:41）、孤儿素材清理（04:47）。
+    # 时间刻意与 04:13/04:23 错开 15 分钟以上：都是删数据的大操作，别挤同一分钟。
+    _audit_sched.add_job(_purge_video_plan, CronTrigger(hour=4, minute=41))
+    _audit_sched.add_job(_purge_video_files, CronTrigger(hour=4, minute=47))
     _audit_sched.start()
     _log.info("经验库每日巡检已注册（03:47 Asia/Shanghai）")
 except Exception as e:
@@ -294,6 +398,8 @@ if __name__ == "__main__":
     _ensure_uiauto_running()
     # 预连接设备池：adb server 重启后设备全掉线，后台并发重连加速恢复
     _preconnect_pool_devices()
+    # 步骤明细清理：服务频繁重启时定时任务可能一直轮不到，启动也清一次
+    _purge_step_log_async()
     _log.info(f"管理后台: http://localhost:{WEB_PORT}/ (admin/admin123)")
     # 启动通知：放在 __main__ 里是刻意的——以 WSGI 方式 import 本模块只有"半个启动"
     # （阶段 A~F 在 import 期就跑完了），不该发"服务已启动"。
@@ -316,6 +422,12 @@ if __name__ == "__main__":
             _notifier.shutdown(timeout=3.0)
         except Exception:
             pass
+        try:
+            from core import step_log as _step_log
+            _step_log.shutdown(timeout=3.0)     # 排空队列后再退
+        except Exception:
+            pass
         mgr.shutdown()
         device_discovery.shutdown()
+        device_battery.shutdown()
         _stop_uiauto()