butubb/auto_control
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c834349facd486ce7fceb2e9d1e544cc4bb29ff5
auto_control/doc/backlog/TODO.md
T
butubb 24d57d3b96 docs: doc/ 全量重整——按现状重写并建立文档索引；项目统一更名 auto_control 
背景：文档长期落后于代码（Tab 数、任务类型、接口示例等多处与现状不符），
且信息分散重复。这次按当前代码状态逐篇重写，并建立统一的文档体系。

新增
- doc/README.md：文档总索引（文档地图 / 推荐阅读路径 / **文档维护约定**）
- doc/DATA_MODEL.md：数据模型（7 张模型表 + 5 张非模型表、迁移机制、app_meta 键、
  数据目录、备份覆盖清单与双向自检）
- doc/AI_CONSOLE.md：AI 控制台机制（会话与 SSE、经验库/动作库蒸馏与召回、巡检、
  Markdown 渲染、推理链、token 统计、故障排查）

重写（按现状，去掉过时与重复）
- README.md：7 个 Tab、18 种步骤、设备生命周期、调度/窗口语义、常见问题；修掉
  「6 个 Tab / 分组为顶级 Tab」等过时内容与损坏的目录树
- doc/ARCHITECTURE.md：补启动装配顺序（import 期副作用、A~G 七阶段）、线程与锁清单、
  设备状态机、调度全链路、前端结构与实时通道、设计决策、**已知缺陷与踩坑清单**、扩展点
- doc/API.md：按蓝图重建「接口总索引」（107 条路由含鉴权）+ 分域详细说明 +
  非 JSON 响应汇总 + 错误分支速查
- doc/TASK_DEV.md：18 种步骤全表（参数/默认值/语义）、容器与公共参数、
  选择器与 XPath 序号语义、抓取器建议规则、新增任务类型骨架
- doc/DEPLOY.md：容器入口 start.sh 三件事、发布流程与检查清单、备份覆盖红线、
  按现象分类的故障排查
- doc/DEVELOPMENT.md：流程/红线/本地开发/**测试与写测试的约定**/配置速查/文档同步
- doc/MCP.md：19 个工具的参数级清单、坐标空间、写门控三连、安全与审计
- doc/MCP_DESIGN.md、doc/AI_TASK_GEN.md：标注设计 vs 实现现状，补交叉链接
- doc/backlog/TODO.md：新增「已知缺陷」小节（含复现与影响）+ 已完成留档
- .env.example：按代码实际读取的键重写（补 USB/DISCOVERY/MCP/AGENT，删死配置）

其它
- 项目名统一 auto_control：README/文档/scripts/pack.py 产物名；代码内的
  doc 章节引用（templates/admin/monitor.html）同步更新
- 校验：16 篇文档 156 条相对链接全部可解析；文档中的关键数字与代码核对一致
  （19 个 MCP 工具 / 18 种步骤 / 12 张备份表 / 1 种任务类型）
2026-09-10 22:19:18 +08:00

132 lines
9.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 待完成项 / 已知问题（Backlog）
> 用途：记录**已确认但暂缓**的功能、优化与**已知缺陷**，避免丢线索。完成时移出本文件，并按「doc 同步红线」更新对应文档。
> 维护：新条目写清 **背景 / 期望 / 涉及文件 / 验收**；缺陷写清 **现象 / 复现 / 影响**。
> 相关：[doc/README.md](../README.md)（文档索引与维护约定）。
---
## A. 已知缺陷（尚未修）
### A1. `GET /locate` 返回 500（设备定位大字页打不开）
- **现象**：访问 `/locate?serial=…` 直接 500。
- **原因**：`web/monitor.py` 的 `locate_page()` 用了 `render_template_string` 与 `_esc`，但该文件只导入了 `render_template`，也没有 `_esc` 定义。
- **复现**：`curl -s -o /dev/null -w "%{http_code}" "http://127.0.0.1:18050/locate?serial=1.2.3.4:5555"` → 500（路由扫描脚本已确认）。
- **影响**：「工具 → 设备池管理 → 定位」在设备上打开的大字页不可用（亮屏那半仍生效）。
- **涉及**：`web/monitor.py`（补 import / 补转义实现，或改用 `render_template` + 模板文件）。
- **验收**：`/locate` 返回 200 且页面正确显示 serial/IP；纳入回归脚本。
### A2. `POST /api/device/locate`（`show=true`）失败
- **现象**：带 `show=true` 调用时抛异常 → 502。
- **原因**：`web/monitor.py` 用了 `urllib.parse.quote` 但未 `import urllib`。
- **影响**：无法远程把设备浏览器打开到定位页。
- **涉及**：`web/monitor.py`。**验收**：`show=true` 时设备浏览器打开定位页且返回 200。
### A3. CSRF 实际未启用
- **现象**：`/api/csrf` 会签发 token、前端所有非 GET 请求都会带 `X-CSRF-Token`，但服务端**从不校验**。
- **原因**：`web_server.py` 只 `from web.auth import _csrf_protect`，**没有注册** `app.before_request(_csrf_protect)`；而 `web/auth.py` 的 docstring 声称"由 web_server 注册"。
- **影响**：CSRF 防护形同虚设（同网段内可伪造写请求）。
- **涉及**：`web_server.py`（注册钩子）+ 需要回归所有写接口（前端、脚本、MCP 的 `platform_client` 都已带 token，风险点是第三方直接调 API）。
- **验收**：注册后所有写接口在缺 token 时返回 403，且前端/MCP 全链路正常。
### A4. 路由回归脚本在 Windows 上不可用
- **现象**：`python scripts/regression_test.py` 直接报 `AttributeError: module 'signal' has no attribute 'alarm'` 退出。
- **原因**：脚本用了 Unix 专有的 `signal.alarm`（第 29 行），docstring 里的示例路径也是 `.venv/bin/python`。
- **影响**：本机（Windows）开发时没有"一条命令扫全接口 500"的手段——A1/A2 这类 import 遗漏本可被它第一时间发现。
- **涉及**：`scripts/regression_test.py`（把 `signal.alarm` 换成跨平台超时，或 `hasattr` 守卫）。
- **验收**：Windows 与 Linux 都能跑；能扫出 A1。
### A5. 前端 `--card-line` 变量未定义
- **现象**：AI 控制台的会话/经验/动作模态框边框失效（`border:1px solid var(--card-line)` 解析为无效值）。
- **原因**：该变量只在 `templates/admin/wall.html` 的 `:root` 定义，`monitor.html` 的 `:root` 里没有，但被引用了 5 处。
- **涉及**：`templates/admin/monitor.html`（`:root` 补 `--card-line:#232936`）。
### A6. `monitor.js` 引用了未定义变量 `countParts`
- **现象**：进度为 0 的边界分支会抛 `ReferenceError`（被外层 `try/catch` 吞掉，用户无感）。
- **涉及**：`static/admin/monitor.js`（该分支的进度渲染）。
### A7. 其它小问题（低优先）
- `static/admin/custom.css` 是**死文件**（无任何引用）。
- `templates/admin/monitor.html` 里 `.agent-shell` 有**完全重复的 CSS 声明**（后者覆盖前者的 `min-height`）。
- 设备表空态 `colspan="11"` 与实际列数（10）不符。
- `core/device_worker.py` 的 `_u2_connect_remote` 有两个结构相同的 `except Exception`，**后者是死代码**。
- `core/ssh_client.py` **全项目无人 import**（`STF_SSH_*` 配置也只被它读取）；要么接上用途，要么删除。
- 若干按功能域拆包时留下的**重复函数定义**：`_merged_device_list`（`web/common.py` / `apks_api.py` / `tools_api.py` 各一份）、`tools_api.py` 的三个辅助函数、`monitor.py` 的屏相关函数、`tasks_api.py` 的 `_job_next_run`（各定义两次）。
---
## B. 设备与连接
- [ ] **adb 远程终端加「目标切换」（本机 / 220）**
- 背景：终端默认走 `.env` 的 `ANDROID_ADB_SERVER_ADDRESS=192.168.20.220`（adb 客户端生效，非本项目代码读取），因此终端里看不到**本机 USB 设备**。
- 期望：`/api/adb/devices`、`/api/adb/cmd` 支持 `target=local|remote`；前端 `tools.js` 加下拉。
- 涉及：`web/tools_api.py`、`static/admin/tools.js`、`doc/API.md`、`doc/DEVELOPMENT.md`（配置速查）。
- 验收：切「本机」能列本机 USB + 已连 `IP:5555`；切「220」列 220 侧设备；`adb cmd` 同样生效。
- [ ] **`.env` 的 adb 路由键要在文档里说明（或去掉）**
- `ANDROID_ADB_SERVER_ADDRESS/HOST/PORT` 会被 `.env` 注入 `os.environ`，**adb 客户端**据此把所有调用指向 220；`ANDROID_ADB_SERVER_HOST` 是非标准键（adb 不认）。
- 期望：在配置速查里写明该行为与取舍，或本地去掉这三行改走本机 adb。
- [ ] **`.gitignore` 漏项**：`data/mcp_audit.log` 与 `data/uiauto.pid` 未被忽略（`git status` 会显示为未跟踪）；`data/apks/` 目录无占位文件。
- [ ] 220 的 Tailscale / adb server(5037) 可达性巡检（曾出现连不通超时）。
---
## C. 编辑器 / 元素抓取
- [ ] **未命中要「明确提示」，别混成「执行了这步」**
- 背景（2026-09-10）：click/long_click/wait_el/swipe_until/if_el 未命中时只写 `[WARNING] ... 未找到元素`，前端进度仍按"执行了一步"计数 → 用户看到像"成功"，实际没点（db03f16e 案例就是这么误判的）。
- 期望：执行器把**未命中**作为该步结果（✗）返回并计入统计；前端标红 ✗ 并给出所用选择器；任务结束汇总未命中步骤数。
- 涉及：`tasks/generic/task.py`、`static/admin/{tasks,monitor}.js`、`doc/TASK_DEV.md`。
- [ ] **元素抓取超时——部分设备 dump 慢于平台超时**
- 背景（2026-09-10 实测）：`core/uiauto_helper.py` 的 `_TIMEOUT=(1,8)`；某设备 dump **~18s** → 平台报「uiauto2 请求超时」，编辑器抓不到元素（设备本身正常）。
- 期望：读超时提到 `(2, 30)` + 前端加载中有明确提示；可选"同界面短时缓存"。
- 涉及：`core/uiauto_helper.py`、`web/tasks_api.py`、`static/admin/editor.js`、`doc/ARCHITECTURE.md`。
- [ ] **序号型 XPath / 界面就绪 的防呆**（2026-09-10 db03f16e 案例）
- 背景：`(//*[@resource-id="…"])[6]` 依赖"抓取那一刻该属性有 ≥6 个实例"；运行时界面不同（App 仍在闪屏页）→ 序号必然失配。
- 期望：① `open_app` 提示勾选「等待首页」；② 抓取器对**带序号**的选择器加醒目提示；③ 抓取弹窗提醒"请先把设备停在任务运行到该步时的同一界面再抓"。
- 涉及：`core/uiauto_helper.py`、`static/admin/editor.js`、`tasks/generic/task.py`、`doc/TASK_DEV.md`。
- [ ] 自定义动作支持 `action_ref` 引用型节点（现状：拖入画布会**展开成 group**，改动需同步执行器 + 编辑器）。
---
## D. AI 控制台 / 经验与动作
- [ ] 「🧠 经验库 / 🎬 动作库」合为一个面板（标签页切换）。
- [ ] AI 建任务 P0：平台级 MCP 工具（只读清单 `task_types/groups/pool` + `submit_task(draft)` 校验）+ 把**动作库**当作 generic_steps 的预制件复用（见 [AI_TASK_GEN.md](../AI_TASK_GEN.md) §9）。
- [ ] 新增 MCP `de_screen_text`（文本化看屏：前台包名 + screen_state + 可点元素文本 + OCR），并把操作纪律写进工具 description。
- [ ] 经验召回改进：现为 bigram + `ORDER BY hits`（候选只看 top50、hits 对所有命中行回写 → 马太效应）；改为对称相似度 / 更合理候选集，`hits` 仅在真正注入时 +1。
- [ ] 经验/动作入库依赖模型蒸馏成功：加失败重试与可视化观测（现在只在日志里）。
---
## E. 工程化 / 文档
- [ ] **MCP 白名单语义缺口**：`MCP_ALLOWED_SERIALS` 为空时并未按设计限制为"平台设备池内"（当前只校验非空），见 [MCP.md](../MCP.md)；如需收紧需补实现。
- [ ] **`MCP_DESIGN.md` 里的"演进备选"（独立 mcp-server 容器）未落地**：已在文中标注，若确定不做可删除该节，避免后续误读。
- [ ] **STF 容器状态确认**：`doc/DEVELOPMENT.md`（已停用）与 `doc/STF_REMOVAL.md`（待人工确认）说法矛盾，需以 220 实际为准后统一。
- [ ] **`DISCOVERY_SUBNETS` 无 env 支持**：`config.py` 里是硬编码列表，其余发现配置走 `app_meta`；若要支持 `.env` 覆盖需补实现。
---
## F. 已完成（留档，便于追溯）
- [x] `platform-tools` → `auto_control` 命名统一（2026-09-10：文档/README/`scripts/pack.py` 产物名）。
- [x] 删除抖音养号任务类型（`douyin_nurture`），平台只保留 `generic_steps`；残留旧类型任务改为**启动告警 + 执行时明确报错**。
- [x] `generic_steps` 去掉默认步骤；空步骤任务执行时明确报错（不再静默空跑）。
- [x] 重试耗尽时的 `last_error` 带上真实失败原因（不再只有"重试 N 次失败"）。
- [x] 监控页任务卡去掉「编辑/删除」，只留执行/停用 + 显示**覆盖设备**。
- [x] 备份覆盖清单补 `agent_action` / `app_meta` + 导出/导入双向自检。
- [x] AI 控制台：Markdown 渲染、推理链可折叠、token 用量显示。
Reference in New Issue View Git Blame Copy Permalink