butubb/auto_control
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
202 Commits 2 Branches 6 Tags
621d48c8006bf2021188b19741c8fd85eeb7a2fa
Commit Graph
70 Commits
Author SHA1 Message Date
butubb 621d48c800 feat(日志): 任务步骤明细表 + 「日志 → 步骤明细」面板（按设备/任务/时间过滤、按运行归组、导出 CSV） 
文本日志只能 grep，"这台设备这次运行为什么失败"翻起来很费劲。新增一张
**结构化**的步骤明细表，把"哪一步、什么类型、哪个选择器、结果、耗时"落库。

- core/models.py：新增 task_step_log（run_id/job/设备/step_path/selector/
  result/detail/duration_ms），索引 run_id、created_at、(serial,created_at)、
  (job_id,created_at)；
- core/step_log.py（新）：**专用写线程 + 有界队列**批量落库——步骤执行是热路径，
  任务线程只 put_nowait（实测 9000 次入队 31ms），队列满丢弃并计数，绝不阻塞；
  另有保留期清理（默认 14 天，每日 04:13 + 每次启动）；
- tasks/generic/task.py：_exec_one 记一条（异常=error / handler 返回 False=miss /
  未知类型=unknown / 概率未触发=skip）；_exec_steps 维护路径栈得到 "2.1.3"
  这样的嵌套位置；**单次运行封顶 2000 条**——forever 循环任务否则会写爆表；
- 运行上下文 ctx（run_id/job_id/job_name/device_name）由 TaskManager 生成，
  经 create_worker(serial, params, ctx=None) 传入 worker（扩展点向后兼容）；
- 接口：/api/step_logs（过滤+分页）、/runs（按运行归组）、/filters（下拉选项）、
  /download（CSV，带 BOM）；
- 前端：日志页拆成「文件日志 / 步骤明细」子分栏 + static/admin/steplog.js。

红线：新表自动进备份覆盖清单（SUMMARY_TABLES 由元数据派生），已补
TABLE_LABELS 中文标签，导出实测 14 张表、coverage_missing 为空。

文档：DATA_MODEL §2.8/§1、API §10.2、ARCHITECTURE §1.1/§2.2/§3.1、
DEVELOPMENT §5.2 与红线表、DEPLOY §5.2、TASK_DEV §8.3、README。
 2026-09-16 08:58:43 +08:00
butubb 2c32c397c8 feat(日志): 日志页支持关键字/级别/时间过滤 + 下载（含滚动历史） 
「日志」页原来只能 tail 固定行数、且文件下拉写死了 4 项（新增的 notify.log
根本选不到）。本次：

- core/logger.py 新增读取接口：list_log_files()（模块文件 + .1/.2 滚动历史，
  白名单）、query_log()（关键字/最低级别/时间过滤，返回结构化行）、
  read_log_text()（导出）。
  · 时间/级别过滤对**续行**用继承值（traceback 缩进行本身没有前缀），
    按 ERROR 筛不会把堆栈拆散；
  · 过滤按"最近 N 条命中"返回，保持文件原顺序；
- GET /api/logs 换新协议（rows/files/matched/scanned/truncated），
  新增 GET /api/logs/download（附件下载，支持同样过滤；无一条件时整文件）；
- 顺带修 **目录穿越**：原实现 os.path.join(_LOG_DIR, file) 可用 ../../ 逃逸，
  现在 file 必须命中白名单；
- 顺带修 web/admin_api.py 里 _log 未定义（用户增删改的日志行会 NameError）；
- 前端：文件下拉改为按接口渲染、加关键字(命中高亮)/级别/时间范围/下载/重置，
  自动刷新时不再把正在上翻的用户拽回底部。

文档：doc/API.md §10.1（参数与返回）、README 日志节。
 2026-09-16 08:44:19 +08:00
butubb 3b6ec8c98f feat(通知): 加钉钉 / 飞书两种格式（含各自的加签算法） 
## 两家签名算法不一样，照抄必错
| | 钉钉 | 飞书 |
|---|---|---|
| HMAC key | `secret` | `"{timestamp}\n{secret}"` |
| 被签内容 | `"{timestamp}\n{secret}"` | 空 |
| timestamp | 毫秒 | 秒 |
| 拼在哪 | URL query | JSON body |
| 结果 | Base64 再 urlencode | Base64 |
| 出错码 | `errcode 310000` | `code 19021` |

实现为 `BaseAdapter.sign_request()` 钩子（默认不动），两家各写各的；
`core/notifier.py` 的 `_post_once` 在发请求前调用它。

## 另外
- 钉钉：markdown 消息（title+text）；成功码 0；默认限流 15/分（官方 20/分，**超限会被限 10 分钟**，留余量）
- 飞书：交互式卡片（header 颜色按事件级别 + markdown 元素）；成功码 0；默认 60/分
- `PLANNED_FORMATS` 清空（下拉里不再有置灰项）
- **修一个泄漏**：`mask_url` 原来只打码 query 参数——**飞书的 token 在 URL 路径里**（`/hook/<token>`）
  → 接口回显会漏出去。现在同时处理路径 token（≥20 位随机串）与 Slack 的 `/services/T…/B…/X…` 三段。

## 验证（都跑过）
- **签名对拍官方示例**：钉钉逐字节一致（含 urlencode，`%2B` 级别）、飞书的 key/message 口径一致；
  时间戳钉住后比对，不靠"自己跟自己一致"
- 成功码按格式：wecom/dingtalk/feishu 的 0 与 bark 的 200 分别判成功，各自的错误码判失败
- 端到端 15 项：钉钉/飞书在假接收端上真发（URL 带签名、body 带 timestamp/sign、卡片是 markdown 元素、
  毫秒 vs 秒的时间戳），签名错时正确判失败（310000 / 19021），token 在回显里被打码
 2026-09-15 14:29:11 +08:00
butubb 24ea289c15 feat(通知): 加 Bark 格式 + 格式切换时界面提示全部跟着变 
## 用户报的第二件事：格式改了，提示没跟着改
弹窗里的 URL 示例/说明、密钥标签、限流说明都写死成企业微信了——选「通用 JSON」时
占位还是 `qyapi.weixin.qq.com`，限流还写着「企微硬限 20」。现在这些文案挂在**适配器**上
（`url_hint/url_help/secret_label/secret_help/limit_help`），由接口随格式下发，切格式即时更新；
限流值在用户没手动改过时也跟着格式的推荐值走（企微 20 / 通用 JSON 60 / Bark 60）。

## 新格式：Bark（iOS 推送）
- `POST {url}`，body `{title, body, markdown, group, level[, device_key]}`
  —— `markdown` 传富文本、`body` 传纯文本兜底（老版本 App 不认 markdown 字段时也能看清）
- URL 两种填法都支持：直接粘 Bark 复制的那串（`https://api.day.app/<key>`，key 在路径里），
  或填 `https://api.day.app/push` + 把 key 填到「设备 Key」（作为 device_key 发送）
- **成功判定按格式**：Bark 是 `code==200`（企业微信是 `errcode==0`）→ 新增
  `BaseAdapter.ok_codes`，`_post_once` 用它判定。少了这一步 Bark 的每次成功都会被误判成失败
- 正文按 2048 字节截断（走 APNs，体量有限）

## 顺带
- 通用 JSON 的 `secret` 现在会作为 `X-Webhook-Secret` 请求头发出（原先填了没用）
- `_formats()` 改为序列化适配器元信息，新增格式只改一处

## 验证
- 格式切换 14 项断言全绿：三种格式的 URL 示例/密钥标签/密钥说明/限流说明/模板区/限流默认值
  全部跟着切换；下拉里 Bark 出现在已实现区
- Bark 端到端 7 项：`code=200` 判成功、`code=400` 判失败（含重试）、请求体带
  device_key/title/body/markdown/group、URL 里的 key 在接口回显里被打码
- 文档：NOTIFY.md §5 的格式表补 Bark 列（URL 怎么填 / 成功码 / 约束），并说明
  "提示文案挂在适配器上，别写死在页面里"
 2026-09-15 14:05:33 +08:00
butubb 97cec6e211 feat(通知): 系统级 Webhook 通知子系统（事件目录 + 可插拔适配器 + 防刷屏） 
平台此前出了问题只能靠人盯页面。现在各组件统一走 `notifier.notify(事件, **字段)`，
推到企业微信 / 自建服务；**所有可通知点都登记进事件目录，默认全关，用户按 webhook 勾选**。

## 架构（`core/notifier.py` + `core/notify_events.py`）
业务线程调 `notify()` → 只做内存操作（读配置快照/匹配订阅/入队）→ 返回；
后台 1 个 dispatcher（聚合 + 每 hook 限流 + 折叠摘要）+ 3 个 sender（真实 HTTP、退避重试）
负责真正发出去。硬约束：**notify 零 DB、零 HTTP、零阻塞、异常不冒泡**——所以任务线程里
可以直接调（不用 app_context、不用 try/except），但**必须放在所有 `with self._lock` 之外**。

- **事件目录 36 条**（任务批次/单设备/设备/Worker/业务/安装/系统/AI），支持 `task.*` 通配订阅；
  语义分工避免重复告警：`worker.*` 是单次尝试级，`task.device.success/failed` 是唯一权威结论。
- **适配器可插拔**：`wecom`（markdown，按 4096 **字节**截断、超限不截半个汉字）+
  `json`（模板占位符，替换值按 JSON 转义，保存前干跑校验）；钉钉/飞书留了插槽（前端置灰）。
- **防打爆四层**：聚合窗口（默认 30s，同批次合并成一条并带样本）→ 令牌桶限流（默认 18/分，
  对齐企微硬限 20）→ 被限流的**折叠成摘要不丢弃** → 有界队列背压。取舍：失败通知最多延迟
  一个窗口，换来群不被刷屏。

## 安全与存储
- 配置只落 `app_meta.notify_webhooks` 一个键（**不建表** → 不涉及备份覆盖红线）。
- URL 本身就是凭据（企微 `?key=`）→ 接口回显/发送记录/日志一律 `mask_url()/scrub()`；
  编辑时留空即不修改；secret 永不回显。DATA_MODEL 的明文凭据告警补上了这一条。
- 发送记录：内存环形缓冲 200 条（重启清空）+ 独立 `logs/notify.log`。

## 接入点（每个都放在锁外、不改 return 顺序）
task_manager（批次开始/结束用新增的 `_BatchTracker` 统一在 finally 计数、单设备成功/失败/
离线/重试/停止/抢占/归还/cron 停止）、device_worker 心跳看门狗、generic 任务选择器连续失效、
apk 安装开始/完成、设备上下线（**状态沿检测**，只报新变化）、备份导出/恢复、经验巡检、
用户登录、服务启停。

## 前端
系统 Tab 新增「通知 / Webhook」子分栏：多条 webhook 列表（URL 打码）+ 编辑弹窗（格式/URL/
密钥/事件勾选树带 ★建议/聚合/限流/自定义模板/预览）+ 发送测试 + 发送记录。

## 自测
- 进程内逻辑 10 组断言全绿：聚合合并、限流+折叠、无配置/全局关静默丢弃、未知事件、
  内部异常不外泄、JSON 转义（标题含引号换行仍合法）、URL/异常消息脱敏、配置校验。
- 端到端（假 webhook 接收端）17 项断言全绿：真实事件投递（user.login / task.batch.no_device）、
  企微请求体形状、**HTTP 200 + errcode 93000 判为失败**、500 重试 3 次、记录里 URL 打码。
- 韧性：webhook 指向黑洞地址时登录耗时 100~114ms（基线 107~133ms，**异步隔离生效**）；
  配置写成坏 JSON 服务照常启动、通知静默不发、日志有 error（服务端实测后已复原）。
- 页面：系统 → 通知 面板/弹窗/36 个事件复选框/预览全部正常，无 JS 报错。
- 自测数据已清理（webhook、自建任务、写坏又复原的配置键）。

文档：新增 doc/NOTIFY.md（事件表/配置/格式约束/防刷屏/加事件三步骤/排障）并登记进 doc/README；
API.md §2.11；DATA_MODEL 的 app_meta 键表与明文凭据告警；ARCHITECTURE 线程表/分层/扩展点；
根 README 功能索引与日志表。
 2026-09-15 13:55:14 +08:00
butubb 7b6c8386af fix(APK 安装): 推送卡死会永久挂住整批安装（新增停滞看门狗 + 收尾兜底） 
用户报：220 上一个安装任务卡住不动。（现场：rednote 169.6MB 装 6 台，
5 台成功，192.168.20.203 卡在「推送中 67%（114.0/169.6 MB）」9 分钟没动静——
那台设备当时正跑着任务，adb 流量撞在一起把推送链路卡住了。）

两个叠加的缺陷：
1. 分块推送的 `proc.stdin.write()` **没有任何超时**：链路一卡就永久阻塞，
   安装线程挂死。
2. 批处理的 `as_completed(timeout=...)` 超时后异常直接冒泡出去（`with
   ThreadPoolExecutor` 退出时还会 wait 卡住的线程），`finished=True` 永远没被
   置位 —— 于是界面上永远是"安装中"，且后续安装全被「已有安装任务正在进行」
   挡住（用户看到的"卡住"）。

修法（core/apk_manager.py）：
- 新增**停滞看门狗**：盯着"已写字节数"是否推进，`_PUSH_STALL_TIMEOUT`(90s) 没进展
  就 kill 掉 adb，阻塞中的写立刻以异常返回 → 退回 `adb push` 重传。
  （为什么不用非阻塞写/管道 select：`os.set_blocking` 是 Unix 专有，开发机是 Windows，
  看门狗两边都能用。）
- 批处理改成 try/except/finally：超时或异常时把还没结果的设备标失败，**无论如何**
  都置 `finished=True`；`pool.shutdown(wait=False)` 不再为卡住的线程陪等。

验证：
- 假 adb 模拟"永不读 stdin"（链路卡死）→ 4 秒识别停滞 → kill → 回退 push 成功，
  全程 6.1s（旧代码在这里永久挂死）。
- 真机正常路径不受影响：5.9MB 推送 1.7s、设备侧字节数一致。
 2026-09-14 10:28:22 +08:00
butubb 615f9cf0d5 fix(APK 安装): 「推送不完整」是误报——adb 退出 ≠ 设备写完 
用户报：安装 APK 显示「推送不完整（设备 3605447 / 本地 5933150 字节）」。

排查（220 现场 + 复现）：这不是传输失败，是**检查时机太早**。
`adb exec-in` 把数据交给设备侧（adbd → shell → `cat >`）后，缓冲里的数据还在继续落盘：
同一份 5.9MB 的 APK，adb 刚返回时 stat 读到 3710967，紧接着 4264448，几秒后才是完整的
5933150（逐步实测）。旧实现只量一次就判失败，于是同一份文件在多台设备上"失败"了 8 次，
断点各不相同（2.7M/3.3M/3.6M/3.9M）—— 典型误报指纹。

修法（core/apk_manager.py）：
- 新增 `_wait_remote_size()`：收尾**轮询**设备文件大小直到长齐（默认最长 20s）；
  stat 取不到（机型差异）时返回 None，照旧跳过校验，不误报。
- 只有真不齐才退回 `adb push` 重传（原来直接判失败）。
- `_push_fallback` 也补一次大小校验：adb push 虽同步，但设备空间不足/被并发覆盖时
  "1 file pushed" 也可能是残缺的。

影响：这个误报不只是显示难看——它会让整台设备的安装直接失败（明明是好的包）。
 2026-09-14 09:08:37 +08:00
butubb ed9e8bacb1 feat(AI 建任务): 直接创建 + 草稿沉淀 + MCP de_snapshot；修「建任务页收不到 done」 
用户报的"探索完无法点击创建任务"真因：一个 run 的事件原先只有**一条** queue.Queue，
聊天页与建任务页同时开着时两个 EventSource 会**瓜分**它——建任务页的回放卡在中间、
`done` 被聊天页取走 → 永远等不到草稿，页面上自然没有可点的"创建"。

一、修（根因 + 表现）
- `web/agent_api.py` 新增 `_Fanout`：**每个订阅者一个专属队列**，多开页面各看各的，
  还带单轮事件缓冲（晚订阅/刷新重连也能补齐回放，终止事件一定送达）。
  实测两路订阅者收到完全一致的 1039 条事件（含 done）。
- `static/admin/agent.js`：断线重连的兜底订阅也按 `mode` 让开（此前漏了这一处）。

二、补齐上一批的三项
- **「直接创建」**：`POST /api/agent/task_draft/create`（草稿体只在服务端、创建前再校验一次、
  成功后清草稿避免重复建）+ 草稿预览里的「✓ 直接创建任务」按钮 + 「探索完直接创建任务」勾选框。
- **草稿沉淀经验/动作**：designer 轮次也走 `_distill_experience/_distill_actions`，
  但**只在草稿通过校验时**（没走通的试错不入库，免得把误点当经验）。
- **MCP `de_snapshot`**（第 20 个工具）：截图+元素树一次取齐（省一次来回、不会因界面在动而错位），
  附带 `screen_state`/`unstable`；两套提示词都改为优先用它。
  平台侧 `/api/uiauto/snapshot` 随之多返回 `screen_state`。

三、文档
- AI_TASK_GEN §10：§10.3 记两个 bug 的真因与修法、§10.4 三项标完成、§10.5 剩余项。
- AI_CONSOLE（扇出语义、多页面同时看一轮）、API（task_draft/create、snapshot 字段）、
  MCP/MCP_DESIGN/staffdeck/README/ARCHITECTURE：工具数 19→20 + de_snapshot 条目。
- backlog：记一条新发现的缺陷——`mcp_server/platform_client._login()` 会把"登录页 200"
  当成登录成功（现场进程缺 `MCP_PLATFORM_PASS` 时表现为含糊的 platform_unavailable）。

自测：真机浏览器端到端（勾上"探索完直接创建"）→ 探索 12 步 → 草稿 → 自动建任务成功；
`de_snapshot` 直连真机校验；校验器 21 条用例、扇出单元用例、本地工具契约用例全绿。
自测产生的任务/草稿已全部清理（未碰用户既有数据）。
 2026-09-14 08:14:11 +08:00
butubb 46e6ea1f37 feat(AI 建任务): AI 自己在真机探索 → 写出可调度任务 → 人工确认入库 
AI 控制台下新增子分栏「🧭 AI 建任务」：描述要做什么（例：建一个跑 2 小时的任务、自动刷
某 App、随机点赞），AI 用 de_* 工具自己在设备上探索（看屏/读元素树/点按验证），把走通的
路径写成一条任务草稿，经服务端校验后交人在步骤编辑器里核对/手改/试跑，保存才入库。

链路：POST /api/agent/run{mode:"designer", settings}
  → Agent 自探 → 本地工具 submit_task(draft)
  → core/task_draft 校验（失败把 errors 回灌模型让它改）
  → 只暂存（运行态 + app_meta.agent_task_draft，**不落库**）
  → SSE done{mode,draft,warnings} → 页面草稿预览 → openTaskModal(null, prefill) 预填

关键实现
- core/task_draft.py（新）：把执行器的"静默跳过点"（未知 type/空 selector/空 children/
  嵌套>5/节点>60/cron 非法/必填缺失）前移成显式 error——POST /api/jobs 对 params 是盲存的，
  执行器又静默跳过错误步骤，没有这道闸门就是"任务建好了、跑起来什么都没做"。
  归一化兜底任务名/target/schedule/retry/时长；页面填的设置以 overrides 优先于模型。
  故意**不比执行器更严**：loop_mode 近义值归一（count→rounds）、缺 max_iterations 补默认 10
  （执行器本来就默认）——实测卡太死会把一轮探索耗在改字段上。
  有副作用的步骤（评论/发送/购买/删除…）只警告并把触发概率压到 30%（编辑器可改回）。
- mcp_agent/agent.py：双系统提示词（CHAT/DESIGNER）+ 平台级本地工具
  （LOCAL_TOOL_SPECS，不进 MCP）+ 每工具调用上限 40 + designer 输出上限 8192 +
  **json.loads 容错**（草稿被截断时给模型可读错误，而不是整轮失败）。
- web/agent_api.py：mode/settings 透传、submit_task 处理器（app_context 内校验+暂存）、
  done 带 draft、GET /api/agent/task_draft{,+POST,/clear}（草稿走 app_meta，不新建表）。
- 前端：static/admin/taskgen.js + #agent-sub-taskgen 子面板（showSubTab 机制）；
  tasks.js 的 openTaskModal(jobId, prefill) + 信封归一化 + 唯一 draftKey；
  agent.js 按 mode 门控（一个 run 只有一个事件队列，两个 EventSource 会互相瓜分事件）。

顺带修掉一个 chat 也踩的协议 bug：一轮里同时调 de_screenshot 与别的工具时，截图图像会被
插在两条 tool 消息之间 → 模型侧判"工具回应不足"直接 400。改为本轮 tool 消息发完再附图像，
_repair_tool_messages 也改成只数**连续**的 tool 消息。

真机实测（Redmi 22120RN86C，设置页）：8 步探索（含 tap_text 验证）→ submit_task 一次通过 →
草稿 8 个顶层步骤（screen_on/open_app/wait_el/click/wait/key_event…）、max_duration 1800、
无 click_xy、3 条 evidence；页面恢复草稿 + 预填编辑器 + 提示块渲染均正常，无 JS 报错。
自测数据已清理（草稿已丢弃、未创建任何任务）。

文档：AI_TASK_GEN.md 状态改「P0 已实现」+ §10 实现记录（差异/护栏/未做项）、AI_CONSOLE.md
（子分栏、designer 分支、SSE done 负载、app_meta 键）、API.md、DATA_MODEL.md、ARCHITECTURE.md、
DEVELOPMENT.md（自测入口）、README.md 索引、backlog 勾掉 P0。
 2026-09-13 23:08:59 +08:00
butubb 0bc713137d feat(抓取): 选择器优先语义化（同 id 多实例用 @text 限定，而非序号）+ 修掉两类"死选择器" 
语义消歧（B 项）：主属性在整棵树里重复时，先找第二个属性把目标单独圈出来 ——
  //*[@resource-id="x" and @text="我"]   （次属性 text > content-desc > class，
                                        单个不够就两两组合）
标 semantic:true + via；只有组合也分不开（列表里同 id 同文字）才退回
  (//*[@resource-id="x"])[k]            （标 indexed，前端黄标提醒脆弱）
抖音底部导航正是这个场景：tab 个数随灰度版本变（4 个 ↔ 3 个），序号必然错位。

顺带修掉两个结构性缺陷（给上面做验证时逐条 lxml 求值发现的，均非本次引入）：
1. 结构步进把 class 当标签名 —— dump 的 XML 标签**一律是 <node>**，class 在
   @class 上，所以 //FrameLayout[1]/… 这类路径**永远零命中**；改 *[@class="…"][n]
2. 兜底结构路径用 @index 定位兄弟 —— 实测同级 index 会重复（状态栏/内容区/
   导航栏三个兄弟全是 index="0"）；改按子节点位置 //hierarchy/*[1]/*[2]

前端：抓取列表把 text/content-desc 排到最前并加粗上色（最稳的定位依据）；
序号型从蓝标改**黄标 ⚠ 序号 k/n**，语义型给**绿标 ✓ 语义**；属性页新增
「选择器稳定性」一行说明这个选择器靠什么定位、会不会因界面变化失效。

真机实测（192.168.20.100，248 个元素）：
  精确命中目标 221 → 247 ｜ 死选择器 26 → 0 ｜ 语义型 0 → 26（序号型 141 → 115）
  「我」的语义选择器经 /api/steps/test 真机点击 → 命中 ✓

文档：TASK_DEV §5.3/5.4（含两个 XPath 坑）、API §8（suggested 字段表 +
snapshot 行）、research/U2_ELEMENT_SELECTORS §五/§六、backlog ②标记完成。
 2026-09-13 22:05:47 +08:00
butubb 37a2b1c59b feat(抓取): 元素检查器改成本地版"大图 + 一次取齐"——复刻云检查器的体验 
用户要的是 uiauto.dev 那个检查器的体验（左边大图点元素、右边层级树、选完回填），
并希望本地复刻（云页面跨域，拿不到它的选中结果，没法自动回传）。

- core/uiauto_helper.py: 新增 `snapshot(serial)`
  * **一个 u2 连接背靠背** dump_hierarchy() + screenshot()：截图与元素树同源同刻，
    不再像原来那样分两个接口取（中间隔着 dump 本身的 1.3~1.8 秒）
  * `_xml_to_node()`：把 u2 的 XML 节点转成 uiautodev 那套结构，直接复用既有的
    选择器建议逻辑（不写第二遍）
  * **双截图校验**：dump 前后各截一张，差异明显就标 `unstable`，让前端明确提示
    "界面在变化中，请停在静止界面再抓"，而不是悄悄给一个可能错位的框
- web/tasks_api.py: 新增 `GET /api/uiauto/snapshot`（登录 + 设备权限）
- static/admin/editor.js + templates/admin/monitor.html:
  * 抓取弹窗从 900px 加宽到 1280px，预览列从"固定 320px"改为铺满左侧 →
    **图片按原始分辨率 1:1 显示**（实测 720x1650 缩放 1.000），元素框严丝合缝；
    原来缩到 294px 时框全挤在一起，看着就像错位
  * 工具栏显示 `720x1650 · 247 个元素 · 2370ms`；界面在变时顶部弹黄色提示条
  * 鼠标在图上移动时高亮"最深命中"的元素框，便于确认真要点哪个

实测：抓取弹窗 1:1 显示、222 个框逐一贴合元素、无 JS 报错；
`unstable` 在静止界面为 false。
 2026-09-13 21:17:12 +08:00
butubb 3422b4f265 feat: 监控页按名称排序 + 按钮改「看屏 / 打开设备端 Agent」；设备名匹配补 USB 设备 
用户反馈的三件事：

1) **监控页设备排序**改成按**名称**（A01/A02/…），没名字的排最后按地址。
   之前是 adb 返回的顺序，看着像按 IP 排，同型号多台时对不上号。
   排序放在 `/api/status`（后端），大屏页一并受益。

2) **操作按钮改名 + 换实现**：
   - 「截图」→「**看屏**」（行为不变，就是查看设备实时画面）
   - 「定位」→「**打开设备端 Agent**」：改成让设备上的 Agent 弹身份大字页
     （名称/IP/平台地址），替代原来"推 HTML 让设备浏览器打开定位页"那套
     （那套要设备装浏览器、页面还依赖设备能访问平台，backlog A1/A2 一直没修）
     * 新接口 `POST /api/agent/show-info {serial, close?}`；没装 Agent 时明确报出来
     * **先点亮屏幕 + 解除锁屏再拉起** —— 设备息屏时 am start 会把大字页开在锁屏后面，
       人看到的还是一片黑（实测踩过）
     * 平台地址取操作者当前访问地址；若是 localhost 则换成本机局域网地址
       （设备上显示 127.0.0.1 毫无意义）

3) **安装应用的选择设备界面仍显示裸序列号**：USB 设备在 adb 里的 serial 就是
   `ro.serialno`，等于池里那条网络记录的**指纹** —— 之前只按 serial 匹配，插着 USB
   时会冒出一个没名字的 `s8o7nrt8pbzhfadq`。现在按 serial 或指纹任一命中都取名称，
   三处（剪贴板注入 / 安装弹窗 / 安装进度表）统一。

顺带修掉几个自己踩出来的坑：
- `device_pool.list_configured()` 返回的是 **serial 字符串列表**，我当成字典用了
  （`.get("serial")` 抛异常被 except 吞掉 → 名字全空）→ 改用 `list_devices()`
- `web/device_agent_api.py` 用了 `PERM_DEVICES` 但没导入 → 服务直接起不来（502）
- Agent 自检里的版本号是写死的常量（升到 1.4 还显示 1.0）→ 改成读包信息
- `doc/API.md` 章节编号（插了一节没把后面整体下移，出现两个 §16）

验证：安装弹窗里 USB 那台现在显示「A07」（指纹匹配）；监控页按钮为
「看屏 / 打开设备端 Agent」；对装/未装 Agent 的设备分别得到大字页 / 明确报错；
大字页实测显示 A07 + 192.168.20.250:18050 + Agent v1.4。
 2026-09-13 17:18:30 +08:00
butubb 25e4fbb053 feat: 应用列表按包名合并 + 剪贴板/安装/版本管理显示设备名 
两件事都是"列表看不清楚"的问题：

1) **同一个应用传多个版本会并排显示多行**（v1.2 / v1.3 各占一行），看着像重复。
   现在按 **package_name 合并成一个应用一行**，显示最新版：
   - `apk_manager.list_latest()`：版本按 version_code 排序取最新，其余版本放进
     `versions` 字段；解析不出包名的 APK 各自独立成行（不硬合并）
   - 管理页版本列显示 `1.3（另有 1 个旧版本）`，多一个「清理旧版本」按钮
   - 「删除」语义改为**删掉这个应用的所有版本**（行=应用），另给
     `?scope=older` 只清理旧版本；老的单条删除行为保留（不带 scope）
   - **设备端商店也走同一个列表** —— 手机上不会再看到同一个 App 的 v1.2/v1.3 两行

2) **设备只显示地址**（`192.168.20.100:5555`），同型号多台时分不清是哪一台。
   三处补齐设备名（平台给设备起的名字，如 A08），统一「名称 · 地址」：
   - 剪贴板注入的设备勾选列表（`/api/adb/devices` 经 `_merged_device_list` 带 name）
   - 应用管理的安装弹窗（`/api/apks/install/devices` 带 name）
   - 应用版本管理表格（`/api/tools/appver` 结果里带 name）
   - 顺带：安装进度表里的「设备」列原来显示**型号**（而且是 STF 时代残留的空 dict），
     改为显示设备名
   没名字的设备（不在池里）自动回退只显示地址，不显示空占位

验证：上传同包名 v1.1/v1.2/v1.3 三个版本 → 列表只出现一行（v1.3，标注共 4 个版本）、
设备端 bootstrap 也只剩 2 个应用；`scope=older` 只留最新、`scope=package` 整包删除；
三个面板在浏览器里渲染无 JS 报错，devText 有名字/没名字两种形态都正确。
 2026-09-13 16:29:38 +08:00
butubb cdf06e1929 fix: 大 APK 推送到设备时显示实时进度（原来是整段黑箱干等） 
问题（用户反馈）：从网页点「安装」到设备，包大的时候（抖音 336MB）只显示
一句「正在推送 APK...」，传了两分多钟全程没有任何进度，像卡死了。

根因：推送用的是 `adb push`，它**只在结束时**吐一行汇总
（"1 file pushed, 3.0 MB/s"），中间过程什么都不给。

改法：分块写 + 实时进度
- core/apk_manager.py 新增 `_push_with_progress()`：改用 `adb exec-in "cat > 文件"`
  自己按 1MB 分块喂数据，每块更新一次状态（限流 0.8s 一次）：
    `推送中 62%（211.0/336.1 MB · 2.6 MB/s · 剩约 48s）`
  传完校验设备上文件大小；中途断流/exec-in 不可用时**退回原来的 adb push**（保证兼容）
- 代价：实测速度 2.6 vs 3.1 MB/s（慢 17%），换来看得见的进度，划算
- 「正在设备上安装...」补上预期时间说明 —— `pm install` 在设备端解包
  （336MB 实测 ~65s），系统没给进度接口，只能给预期值
- static/admin/apps.js：安装进度轮询 3s → 1.5s；表格里再加一条细进度条
  （大包要一两分钟，光有文字不够直观）
- doc/API.md：把安装状态机的两段式进度与耗时参考写进接口说明

实测（抖音 v40.4.0 336.1MB → 192.168.20.100，单台）：
  推送 60%→100% 每 2 秒一档，速度稳定 2.6 MB/s，134s 传完；
  设备端安装 65s；端到端 ~200s，全程有进度可看。
全量回归 106 项通过。
 2026-09-13 15:38:14 +08:00
butubb dad1af8b0b feat: 设备端应用商店（平台侧）—— Agent 直连拉清单/下载/安装，绕开 MIUI 的 USB 安装拦截 
背景：`adb install` 在 MIUI 上被「USB 安装」拦下（USER_RESTRICTED），必须人工点确认；
而**由设备上的 App 自己调系统安装器**走的是普通应用安装流程，不触发那道拦截。

平台侧实现（设备端 Agent APK 在另一个仓库，契约见 doc/DEVICE_AGENT.md）：

- web/device_agent_api.py（新）：
  * 设备侧 `/api/device/agent/{bootstrap,apk/<id>,report}` —— 无登录会话，靠
    `X-Device-Token`（常量时间比对）鉴权；`X-Device-Fingerprint` 让平台认出是哪台设备
    （换 IP 也认得出，并把平台分配的名称回给它）；**默认关闭，关闭时统一 404**，
    不暴露接口存在性；只读清单与文件，不返回任何配置/密钥
  * 管理侧 `/api/agent-store/{config,logs}` —— 登录 + 应用管理权限；启用时自动生成令牌，
    可一键重置（旧令牌立即失效）
- core/models.py：新增 `device_install_log`（下载/安装记录，自动裁剪保留 500 条）
- 应用管理页新增「📱 设备端应用商店」面板：开关 / 接入地址 / 令牌（复制·重置）/ 安装记录；
  面板里写明它与「平台批量推送」的分工
- doc/DEVICE_AGENT.md（新）：**两个仓库共享的接口契约** —— 接入流程、三个设备接口的
  完整规格与错误码、adb 指令协议（剪贴板/身份显示/配置下发）、版本兼容约定、安全须知；
  API.md、DATA_MODEL.md、doc/README.md 索引同步

验证：
- 后端 9 组用例：默认关闭 404、无/错令牌 401、指纹认出设备名、清单、下载、上报与失败
  原因落库、关闭后重新 404、重置令牌后旧令牌立即失效、未登录管理端被拒 —— 全通过
- 真实浏览器：面板渲染、点开关 → 自动生成令牌 → 设备端带令牌拉到清单且 device.name=A08、
  无 JS 报错；测试后已把开关还原为关闭
- 全量回归 105 项通过（42 GET + 62 写探测 + 7 关键业务）
 2026-09-13 14:40:38 +08:00
butubb f5fc96c300 feat: 页面顶部环境徽标（防混库第 4 层） 
启动日志和横幅只在日志里；用户在界面上操作时也该一眼看出连的是哪个库。
生产显示红底 'PROD · <库名@主机/库>'，开发显示灰底 'DEV'，鼠标悬停给出完整目标。
环境信息由 core/db_config.env_badge() 提供（不含密码），web_server 注入 Jinja 全局。
 2026-09-13 10:38:13 +08:00
butubb 4899e66c68 refactor: 备份/恢复改为「SQLite 归档 + 单事务整库替换」——不再换文件，也不再依赖 SQLite 运行时 
SQLite 从"运行时数据库"降级为"备份交换格式"：导出把当前库（MySQL 或 SQLite）
整库写成一份 SQLite 归档，恢复则是启动时在单个事务里 DELETE + INSERT。
前端三个接口的契约一行未改。

- core/system_backup.py 重写：
  * dump_to_sqlite()（旧名 snapshot_db 保留为别名）取代在线备份 API：MySQL 下把
    这条连接提到 REPEATABLE READ，保证 12 张表读的是同一时刻
  * zip 结构不变（users.db + manifest.json + apks/），既有老备份继续可导入；不依赖
    任何外部二进制（sqlite3 是标准库，python:slim 容器里现成）
  * manifest 增加 db_backend / deployment_env / source_db_id，用于识别备份来源环境
  * apply_restore：安全网从裸 pre_restore_*.db 升级为 pre_restore_*.zip（可直接再导入
    回滚）；跨环境导入默认硬停（需 force_env_mismatch=true）
  * consume_pending_restore：启动时单事务整库替换，任何一步失败 rollback，当前数据
    完好（比换文件更安全）；坏归档挪 restore_failed_* 且不阻塞启动
  * 归档库收尾时 checkpoint 回单文件模式并清掉 -wal/-shm（zip 只打包主文件）
- web_server.py：consume 从 init_db 之前移到之后（现在是事务替换，需要表与 app context）
- config.py：BACKUP_DIR / RESTORE_STAGING_DIR / RESTORE_PENDING_DIR 支持环境变量覆盖
  —— 自动化测试必须把恢复目录指到临时位置，否则测试造的"待生效恢复任务"会在服务
  下次重启时被当成用户的操作消费掉
- core/db_config.py：SQLite 回退模式也写库环境标签（备份要能标出来源环境）
- web/system_api.py + static/admin/system.js + templates/admin/monitor.html：
  预览显示来源/当前环境，跨环境时出现「允许跨环境导入」勾选项；文案同步

验证（隔离副本，绝不碰真实库）：导出→zip 结构与 manifest 正确；预览带来源环境与
告警；应用→生成 pre_restore zip + 归档就位；跨环境 apply 被拒；模拟重启→数据回到
导出时刻、经验库/动作库完好；塞入坏归档→挪 restore_failed_*、服务照常启动、数据未变。
 2026-09-13 10:34:58 +08:00
butubb c834349fac refactor: schema 收敛到 ORM metadata——5 张裸表升模型，方言无关的建表/补列/唯一索引 
原来建表有三套来源（ORM create_all + 自建 SCHEMA_MIGRATIONS + agent_api 里的裸
CREATE TABLE）。这在 SQLite 下能活是因为 SQLite 的 DDL 极宽容；换 MySQL 后
agent_* 四张表的 `INTEGER PRIMARY KEY AUTOINCREMENT`、`TEXT DEFAULT ''`、
`TEXT PRIMARY KEY` 会全部建不出来，而失败被 `except: pass` 吞掉 —— 表现为
「经验库/动作库/会话功能静默失灵、日志里什么都看不到」。本期把它收敛成一套。

- core/models.py:
  * 新增 5 个 ORM 模型：AppMeta / AgentExperience / ExperienceAudit /
    AgentAction / AgentConversation（列名沿用历史，`app_meta.key` 在 MySQL 里是
    保留字，ORM 属性名用 k，读写统一走 db_config.meta_get/meta_set）
  * 新增 _long_text()（MySQL 用 MEDIUMTEXT，裸 TEXT 只有 64KB）与 _DOUBLE()
    （评分别用单精度 FLOAT）；_migrate_schema 不再执行 DDL，只维护版本账本，
    SCHEMA_MIGRATIONS 的历史建表/加列条目 SQL 置 None
  * 新增 _sync_columns()：用 sqlalchemy.inspect 比对模型与实表补缺列，取代原来
    靠 "duplicate column name" 报错文本判断的写法（换方言就失效）
  * _ensure_unique_indexes() 按方言分叉：MySQL 5.7 没有过滤索引，改用
    「虚拟生成列 + 唯一索引」复刻"空值不参与唯一约束"的语义
- web/agent_api.py: 删 4 段裸 CREATE TABLE；_ensure_* 收敛为 _ensure_tables()
  （db.create_all 薄封装，失败必记日志）；app_meta 读写与 INSERT OR IGNORE
  改为方言中立
- core/device_discovery.py: app_meta 读写改用同一助手
- core/system_backup.py: SUMMARY_TABLES 由 db.metadata 派生 —— 备份覆盖红线
  从"靠人记"变成结构上不可能漏；CURRENT_SCHEMA_VERSION 改从 models 导入

验证（均在 users.db 的一致快照副本上，不碰真实库）：
  空库 → 自建 12 张表 + 默认管理员 + 唯一索引 + schema_version=6；
  老库 → 逐表行数与真实库完全一致，app_meta 键未变；
  接口 → health/devices/jobs/groups/agent(经验库/动作库/会话) 全 200，
        会话增删与备份导出（12 张表、无覆盖缺失）正常。
 2026-09-13 10:30:15 +08:00
butubb f22263ab45 feat: 数据库连接层改造——库目标由 .env 装配 + 环境防呆（迁 MySQL 第一步） 
为把数据库从单文件 SQLite 迁到 MySQL 5.7 铺路。本期不改后端：
DB_HOST 为空时仍走 SQLite，本地开发无感。

- config.py: 新增 DEPLOY_ENV（默认 dev）与 DB_HOST/PORT/USER/PASSWORD/NAME/
  CHARSET/COLLATION、DATABASE_URL、两个逃生阀（DB_ALLOW_ENV_MISMATCH /
  DB_ALLOW_SQLITE_FALLBACK）
- core/db_config.py（新增）: URI 组装；按方言分叉的引擎参数（utf8mb4、
  pool_pre_ping、pool_recycle=1800、READ COMMITTED、STRICT_TRANS_TABLES）；
  连接探活；app_meta 方言中立读写（MySQL 里 key 是保留字，需反引号）
- 防混库三层: ①库名与环境绑定（dev→auto_control_dev / prod→auto_control）
  ②库标签 app_meta.deployment_env 与 .env 声明比对 ③启动横幅打印当前库
  （生产用 WARNING 级）。不符直接拒绝启动并说明两边分别是什么
- web_server.py: 硬编码 sqlite URI → db_config；配置错在装配期就 exit 2；
  init_db 之后跑库标签校验 + 横幅
- core/models.py: PRAGMA 监听器加 sqlite 类型守卫——它挂在 Engine 基类上，
  MySQL 连接执行 PRAGMA 会直接导致建连失败
- requirements.txt 加 PyMySQL；scripts/start.sh 依赖守卫加 pymysql，
  并在 exec 前打印 DEPLOY_ENV/DB_NAME/DB_HOST
- .env.example 新增「数据库」段；DEVELOPMENT.md §4.1/4.2、DEPLOY.md §2.2 同步

验证: 用 DATABASE_URL 指向 users.db 的一致快照副本跑通主要只读接口
（health/devices/jobs/pool/groups/discovery/summary 全 200，app_meta 读写正常）；
DEPLOY_ENV=prod 且无 DB_HOST 时退出码 2；开 DB_ALLOW_SQLITE_FALLBACK 后可回退。
 2026-09-13 10:27:14 +08:00
butubb 64fadde568 fix: 断联设备表「换地址」按钮传参丢失（缺 data-serial）+ 删除任务/分组兼容内存不一致 
- tools.js：断联设备表的「换地址」按钮漏了 data-serial 属性，onclick 里
  this.dataset.serial 是 undefined → 接口报「缺少 old_serial 或 new_serial」。
  设备池表里的同名按钮是传字面量的，所以只有断联表这条路径坏。
  顺带给 relocatePoolDev 加参数防呆（取不到地址时给明确提示，不静默）
- task_manager.delete_job / delete_group：原先只在"内存里有"时才删库行，
  内存与库不一致时（手工插行、上次异常退出、旧版本漏删）会出现"删不掉的
  任务/分组"（API 404 但库行还在、重启复活）。改为无论内存有没有都尝试删库行

自测：浏览器验证断联表两个按钮都带 data-serial；relocate 接口端到端（上一轮已验）；
删除接口在前端删除分组/任务后 DB 与内存一致
 2026-09-11 11:23:19 +08:00
butubb 79cdf61ed2 feat: 自动认领开关 + 全站按设备名称显示 
一、指纹匹配自动认领（可选，默认关）
- 发现设置新增「指纹匹配自动认领」勾选（app_meta: discovery_auto_claim，默认 0）
- 打开后：扫描发现某设备指纹与池中已有记录一致（同一台换了 IP）→ 自动迁移记录到新地址
  并同步分组/任务引用，零点击；关闭时维持"识别自动 + 人工点一次确认"
- 默认关的原因：认领会改写分组/任务引用（数据结构变动），交人工确认更稳妥
- 扫描结果与状态行会显示本轮自动认领了几台

二、设备名称在界面上呈现（凡选择/展示设备处都显示名称）
- 新增前端 helper `devText(name, serial)`（base.js）：有名称→「名称 · serial」
- 监控页设备表：名称加粗为主、地址作副行（未命名显示橙色提醒）；任务概况的覆盖设备
  chip 也优先显示名称（tooltip 保留完整地址）
- AI 控制台：目标设备下拉、实时画面设备下拉、目标/运行中提示都带名称（serial→name 映射）
- 任务编辑器「指定设备」下拉、分组编辑的设备勾选列表：带名称
- 后端 `/api/devices` 新增 `items`（[{serial,name,model}]，`devices` 保持兼容）；
  `/api/agent/devices` 增加 `name` 字段
- MCP `de_list_devices` 返回 `name`，并在工具说明与 Agent 系统提示里要求"汇报用名称、
  调工具用 serial"

文档：API.md（items/name/auto_claim + §6.2.1 名称呈现表）、MCP.md（工具返回）

自测（全通过）：自动认领端到端（开开关→扫描→自动迁址 + 名称保留 + 分组/任务引用同步 +
待连接池清理 + 开关默认关且可持久化）；名称显示浏览器验证（监控页/覆盖设备 chip/AI 目标与
观看下拉/任务编辑器/分组弹窗/发现设置开关）；设备指纹与人工认领回归
 2026-09-11 11:16:24 +08:00
butubb 0a1b4d6122 feat: 设备身份改为「名称 + 指纹」——更换 IP 自动认领，分组/任务引用自动同步 
背景：设备池原先拿 serial（IP）当身份。设备一换 IP（DHCP 重新分配）旧记录就成了连不上的
僵尸条目（表现为"断联·自动重连中"但设备并没关机），分组与 serial 模式的任务还吊着死地址。
2026-09-11 实际发生：.70 变成 .71、.72 消失，平台两个条目永远连不上。

实现
- **设备名称必填且唯一**：加入设备必须填名称；库层面用部分唯一索引兜底
  （ux_device_name / ux_device_fingerprint，WHERE 非空 → 兼容历史空值），管理页可改名
- **设备指纹**（ro.serialno）：网络设备添加/确认/扫描/采集型号时自动读取；
  身份三层拆分——名称（人可读，稳定）、指纹（机器识别，稳定）、serial（当前地址，可变）
- **自动认领**：添加或确认设备时指纹命中池中已有记录 → 迁移原记录到新地址
  （名称/型号/备注/启用状态/添加时间全保留），不新增条目
- **人工认领** `POST /api/devices/pool/relocate`：旧地址已断联、指纹没采过时的兜底——
  人工指认"这条就是那台，现在在 X"，迁移并同步引用
- **引用同步**：认领/迁址时把 device_group.serials 与 task_job.target.serial 的旧地址
  换成新地址。⚠️ 必须同时改**内存**：分组/任务在 TaskManager 里另有内存副本且调度用内存对象，
  只改库不重启不生效 → device_pool 迁址后回调 TaskManager.sync_device_serial
  （装配层用 set_move_hook 注册；device_pool 不能反向 import task_manager，会循环依赖）
- **前端**：待连接池新增「识别」列（指纹命中时提示"≈ 名称（原 IP）"，按钮变「认领为 X」）；
  设备池新增「名称/指纹」列与「改名/换地址」操作；断联设备表也加「换地址」（用户看到断联就在这里）
- 添加设备接口改用 adb_connect_light（单次短超时），避免不可达 IP 让请求卡 30s+；重名校验提前到 adb 之前

文档：API.md §6 重写（设备身份/认领/新接口）、DATA_MODEL.md（新列 + v5/v6 迁移 + 唯一索引）、
ARCHITECTURE.md §4.0（身份三层与引用同步的内存坑）、DEPLOY.md 排查表加"断联但没关机"条目

自测（全通过）：名称必填/唯一/改名/重名拒绝（含库层面约束）；指纹采集（真实读到 .71 的
gy7lskwkkvj7c6b6）；自动认领（指纹命中→迁址+保留名称+带指纹+未命中不误判）；人工认领
（迁址+名称保留+分组与任务引用同步）；浏览器验证设备池/断联表/待连接池三个界面
 2026-09-11 11:03:38 +08:00
butubb f4b5316436 chore: 去掉 generic_steps 的默认步骤 + 重试失败带上真实原因 
- tasks/generic/task.py：DEFAULT_PARAMS 只留 max_duration，**不再内置示例步骤**
  （步骤只能由前端编辑器产出；此前默认的"打开抖音→循环看视频"只有后端在用，
  编辑器新建任务本来就是空的，等于埋了个和界面不一致的隐性默认值）
- 空步骤不再静默空跑：worker 立即抛错「通用步骤任务没有可执行步骤…」，
  设备表「最近错误」能看到（此前会走完 0 步当成功）
- core/task_manager.py：重试耗尽的 last_error 现在带上最后一次的真实失败原因，
  不再只有"重试N次失败"（用户看不到为什么失败）；max_attempts=1 显示"执行失败"
  而非费解的"重试1次失败"；长度截断 200 字符
- 文档：TASK_DEV §2.10 说明无默认步骤 + 空步骤会报错；API.md 的 task_types 示例
  改 default_params={"max_duration":0}，POST /api/jobs 补「steps 要一起传」提示

自测（全通过）：default_params 无 steps；无步骤任务真跑一次 → 设备错误信息完整含原因；
有步骤任务（wait 1s）真跑一次 → status=done 无错误；临时任务验完已删，任务集合复原
 2026-09-10 21:50:18 +08:00
butubb 98cdc39224 chore: 删除抖音养号任务类型，平台只保留 generic_steps 
tasks/douyin/（task_type=douyin_nurture）整体删除，唯一任务类型是 generic_steps。
所有默认值/文档/接口示例同步改成 generic_steps：

- tasks/：删 douyin 包；__init__ 只注册 generic；base.py/generic 注释改为照 generic 抄
- 默认值：core/models.py（列默认 + 旧 JSON 迁移默认）、core/task_manager.py TaskJob、
  web/tasks_api.py 建任务默认、static/admin/tasks.js 新建任务默认
- core/task_manager.py：去掉 douyin 专属的"清理废弃 comment 参数"迁移块，改为**启动时告警**
  仍残留已删类型的任务（只告警不改数据）；run_job_now 对已删类型直接返回明确错误，
  不再"报已触发、线程里静默失败"
- 清理残留：douyin_running 状态位（无任何读取方）、core/__init__、core/actions/*、
  core/logger.py 注释里的抖音示例
- 文档：README（特性/目录树/类型表/参数表/示例）、TASK_DEV（目录树/注册说明/模板引用）、
  ARCHITECTURE（注册示例/action 注册表示例）、API.md（task_types 与任务 JSON 示例）、
  AI_TASK_GEN（P1 去掉 douyin 预设）、DEVELOPMENT
- 注：示例里"抖音"作为**App 名**（MCP 列应用、AI 建任务的需求举例）保留，与任务类型无关

自测（全部通过）：类型列表只剩 generic_steps；建任务不传类型默认 generic_steps；传
douyin_nurture 被 400 拒；库里塞残留旧类型任务 → 启动日志告警 + 执行返回明确错误 +
不自动删用户数据；前端新建任务下拉 1 项且默认选中、界面建任务成功；监控页卡片两个按钮 +
覆盖设备正常。临时任务/数据验完已清理，任务集合复原。
 2026-09-10 21:43:08 +08:00
butubb d40c867d6f fix: 备份覆盖补全（动作库/系统配置入清单）+ 覆盖自检与未登记表告警；发布流程/红线文档更新 
问题（2026-09-10 用户反馈）：动作库"没有备份"。实测导出 zip 里 agent_action 数据其实在
（导出是 users.db 全库快照），但清单/预览没列它 → 看起来像没备份。同类还有 app_meta。

修复（core/system_backup.py）：
- SUMMARY_TABLES 补 agent_action(动作库) 与 app_meta(系统配置) + 中文标签；
- 导出侧**覆盖自检**：登记表若在快照缺失 → manifest.coverage_missing + 日志告警；
- 导入侧**反向自检**：备份含未登记表 → 预览告警提示登记（extra_tables）；
- 顶部注释写明新增持久化表必须登记（红线）。

其余：
- monitor.html：数据备份面板文案改为明列全部业务表 + 指引（预览见表行数 / 新增表须登记）；
- doc/DEPLOY.md §3.5：新增「备份覆盖清单（红线）」小节（含清单与两侧自检说明）；
- doc/DEVELOPMENT.md：§5.6 增「备份覆盖红线」；§6 发布流程重写为分支流程
  （本机建分支 → 用户确认 → 合 dev → dev 整体就绪 → 合 main → 220 部署，附部署命令）；
- doc/ARCHITECTURE.md §3.6：补备份覆盖登记提示。

实测：导出清单 12 表（含动作库 3 行、系统配置 8 行），coverage_missing 空；上传预览同样显示、
extra_tables 空。
 2026-09-10 21:03:41 +08:00
butubb 3f44cd1491 fix: 元素选择器序号语义 + 抓取弹窗直接点击测试 
- uiauto_helper: 同属性多实例的选择器由 `//*[@id="x"][k]` 改为 `(//*[@id="x"])[k]`——
  前者在 XPath 里是"父节点内排第 k"，多实例时 [2..n] 全部失配（实测抖音底部 4 个同 id tab：
  仅 [1] 可用），任务里表现为"未找到元素"但界面上元素明明存在。
- tasks/generic/task.py: 新增 _norm_legacy_xpath，执行前把**历史遗留**的
  `//*[@attr=…][k]` 窄范围纠正为带括号形式（只改前缀，结构路径 …/FrameLayout[2] 的
  兄弟序号保持不动）——已存任务无需重抓即可恢复。
- editor.js: 抓取弹窗每条元素新增「▶ 点一下」（按 bounds 中心真点一次，/api/screen/tap
  snap=1 吸附）与「✓ 测选择器」（用将填入的选择器跑 /api/steps/test 验证命中），
  点击后自动刷新截图；底部加用法提示。
- doc/TASK_DEV.md：写明 xpath 序号必须整体加括号 + 旧形态自动纠正 + 优先文字/唯一 id。
 2026-09-10 15:31:33 +08:00
butubb 55b1b74944 feat: 系统数据备份导出/导入后端——sqlite 在线快照 + apk 打包导出；上传校验预览→应用（自动快照当前库）+ 重启生效 
导出：sqlite3 在线备份 API 对 data/users.db 做一致快照 → zip（users.db +
manifest.json：schema_version/逐表行数/apk 清单）+ 可选 data/apks/*.apk。
导出文件读入内存(BytesIO)发送后即删磁盘副本，避免 Windows 流式句柄锁残留。
导入：上传 zip/db → 暂存校验（integrity + 必需表 app_meta/user/task_job/
device_group + schema 版本提示）→ 确认应用：先自动快照当前库到
data/backups/pre_restore_*.db，再把备份落到 data/restore_pending/，由
web_server.py 在 init_db 之前 consume 换库——TaskManager 启动时才读库入内存、
Windows 不能热替换正被持有的库文件，故导入必须重启生效。

新增 web/system_api.py（export/preview/apply，全 @admin_required）与目录常量
BACKUP_DIR/RESTORE_STAGING_DIR/RESTORE_PENDING_DIR；.gitignore 排除运行产物。
 2026-09-09 14:49:40 +08:00
butubb 65bab7e25c fix: schema 迁移幂等兜底——create_all 已建列而 schema_version 未记录时重复 ALTER 报 duplicate column，遇错回滚并照记版本自愈 
典型场景：create_all 已按当前模型把列/表直接建好（如 perms、device.model），
而 schema_version 又因历史中断没记录，导致每次启动重复 ALTER 报错。
duplicate column name 说明列已存在=迁移目标已达成：回滚本次语句后仍记录
版本号，一次启动即自愈；其它异常才中止本批迁移。
 2026-09-09 14:16:15 +08:00
butubb 4c0572f73c fix: 设备自动发现本机IP枚举——git-bash hostname -I 报错炸线程，改 bytes 接收 + getaddrinfo 兜底 
Windows 上 git-bash 的 coreutils hostname 不支持 -I，会把 GBK 报错写进
stderr；text=True 在 subprocess 后台读线程里 utf-8 严格解码会直接炸线程
（主线程 try/except 接不住异步线程异常）。抽 _local_ips()：优先 hostname -I
且用 bytes 接收 errors=ignore 解码，不支持/失败时 getaddrinfo 枚举兜底。
扫描网段展开时剔除本机自身 IP，避免探测到自己 5555。
 2026-09-09 14:16:13 +08:00
butubb edfd529c59 feat: 正式池断联设备自动重连——①扫描线程每轮顺带对断联的网络设备 adb_connect_light（幂等，连上即恢复，无需人工；此前只有启动时预连接一次，断联后不会自己回来）；②断联设备不删不进待连接池（pending 语义=未授权新设备），GET discovery 返回 pool_offline（serial/型号/备注）；③POST /api/devices/discovery/reconnect 手动立即重连；④发现面板加「设备池断联设备」区块（自动重连中 + 立即重连按钮） 2026-09-05 09:58:42 +08:00
butubb 4d4f0ae666 fix: OCR 文字点击落点精度——命中文本块较长时（一行含多段文字）按关键词在文本中的位置比例估算 x，避免点整块中心偏离关键词（tap_text 与任务 OCR 条件共用受益） 2026-09-04 14:33:28 +08:00
butubb 7276cfe585 fix: 待连接池后端过滤离线设备——list_pending 只返回当前在线设备（离线候选不可确认），不依赖前端 JS 缓存版本，任何客户端都拿不到离线条目 2026-09-04 08:08:52 +08:00
butubb 1a74372ad9 fix: 任务调度限定设备池——preempt 抢占模式的 all 目标原用 list_online()（含待连接/未入池设备，自动发现验证连上的设备会被任务误跑）；改为设备池内在线设备；group 模式同样过滤未入池设备（serial 模式保留显式指定） 2026-09-01 09:07:12 +08:00
butubb 4efe17c1c9 feat: 设备自动发现——定时扫描局域网+Tailscale 网段开放 adb 5555 的设备进入待连接池，用户确认后才加入正式设备池（不自动连接）；socket 并发探测+adb 短超时验证（state=device 过滤 unauthorized），配置存 app_meta 可前端调整；配套：adb_connect_light 验证短超时、DISABLE_SCHEDULER 回归开关 2026-08-30 10:57:07 +08:00
butubb 90ca2c2100 fix: 任务动作编辑器剪贴板注入改用 ClipInject 通道——u2 set_clipboard 在 Android 10+ 静默失效（粘贴模式必抛 UiAutomationError）；提取 core/clipboard_helper 公共模块供工具页与任务执行端共用，粘贴模式 atx-agent pasteClipboard + set_text 兜底 2026-08-20 10:51:54 +08:00
butubb 27530ff5ac fix: 手动执行不再受运行窗口限制（窗口只约束定时触发）——立即执行按钮在窗口外也可触发任务 2026-08-20 08:36:29 +08:00
butubb a9720e8b81 fix: 抢占归还丢失——preempted_job 在重试循环内被重置为 None，关键字任务一旦重试（attempt≥2）被抢占的养号任务永不恢复；提升到循环外+已有值不覆盖+归还时被抢占任务停用/删除也打日志 2026-08-19 15:46:18 +08:00
butubb a0916ebda2 fix: 抓取元素回填垃圾选择器——无属性元素生成 //*[N]（匹配任意节点点不到），改为 invalid 标记前端提示不可选；结构路径跳过无 class 层消除 //*[N] 前缀污染；模块拆分遗漏修复（get_all_worker_status/list_installed_apps 致 summary/设备已装应用 500） 2026-08-19 15:10:26 +08:00
butubb 6f6093842c feat: 设备型号采集展示（devices 表 model 列+getprop 采集+管理页型号列/采集按钮+监控页兜底）+ fix: 监控页设备列错位（离线标签残留 td）、appver 端点误删恢复、appver 只查在线设备用轻量连接防挂起 2026-08-19 13:53:27 +08:00
butubb eda71c8e5f fix: USB 设备双路径——优先本机 adb 直连，其次 220 远程 adb server（原实现只查远程，本机 USB 会被误判不在 server） 2026-08-19 08:08:40 +08:00
butubb a5ce57b6fd 阶段3: 摘除 STF——删除 stf_client/stf_device_mgmt 与全部引用（STF 容器重启/设备管理/强制释放占用/agent 按钮/占用列），调度与设备管理完全基于本地设备池+adb；错误类迁入 device_worker，create_worker 去 stf 参数 2026-08-18 08:08:32 +08:00
butubb 645938b305 阶段2: USB 远程 adb server 打通（220 host 网络 5037 全接口监听，无需改 220）+ 自建远程看屏（MJPEG 流 + u2 触控 tap/swipe/key/text，ws-scrcpy 不在 npm 改自建） 2026-08-17 16:50:12 +08:00
butubb 5354fe6379 阶段1: 调度/生命周期切换 device_pool——task_manager 设备解析与状态查询、STFDevice 去 occupy/release、web_server 端点换数据源（USB 桥接保留到阶段 2） 2026-08-17 11:16:13 +08:00
butubb 52c4d3aab4 阶段0: 设备池（SQLite devices 表 + core/device_pool.py 清单/在线状态/CRUD，首次启动自动从 STF 导入）+ STF 摘除迁移计划文档 2026-08-17 11:11:08 +08:00
butubb e48eeef49b feat: 任务抢占+归还（抢占任务结束后自动重启被抢占任务）+ 修复抢占死锁（stop_device 移出锁块）+ wait 步骤可中断 + 循环块新增一直循环模式（配合定时启动+停止实现全天候养号） 2026-08-16 08:12:05 +08:00
butubb 17f849f723 feat: STF设备管理彻底删除（脚本+断开+STF API清记录）+ 一键重连（后台跑connect脚本）+ 跳过原因日志区分离线/未就绪 + SSH超时错误分类 2026-08-15 15:22:55 +08:00
butubb e12219c979 feat: 强制安装APK（推送+pm install 绕过厂商弹窗）+ 定位设备（亮屏+大字定位页，结束定位关闭浏览器含后台）+ 一键亮屏/息屏（并发全部设备） 2026-08-15 15:03:01 +08:00
butubb 21d3aa8268 feat: 任务离线设备自动跳过（serial/分组模式触发时过滤 STF 池离线设备，默认开启，任务编辑器可勾选关闭） 2026-08-14 09:16:54 +08:00
butubb 2e491b19e2 feat: SSH 改纯密码认证（paramiko，禁用密钥/agent 不弹授权框，密码放 .env）+ 部署配置全迁 .env（config.py 不再内置 STF/SSH/Tailscale 值，.env.example 补全 11 项） 2026-08-11 14:12:52 +08:00
butubb 5dd605e3a0 feat: 工具Tab新增STF设备管理（读写220脚本DEVICES列表+docker adb connect/disconnect，220侧timeout兜底防卡死）+ 修复设备列表:5555重复显示 2026-08-11 10:50:41 +08:00