From ed9e8bacb12fc51e36a2153a55a6299fd76998e1 Mon Sep 17 00:00:00 2001 From: butubb <1422726308@qq.com> Date: Mon, 14 Sep 2026 08:14:11 +0800 Subject: [PATCH] =?UTF-8?q?feat(AI=20=E5=BB=BA=E4=BB=BB=E5=8A=A1):=20?= =?UTF-8?q?=E7=9B=B4=E6=8E=A5=E5=88=9B=E5=BB=BA=20+=20=E8=8D=89=E7=A8=BF?= =?UTF-8?q?=E6=B2=89=E6=B7=80=20+=20MCP=20de=5Fsnapshot=EF=BC=9B=E4=BF=AE?= =?UTF-8?q?=E3=80=8C=E5=BB=BA=E4=BB=BB=E5=8A=A1=E9=A1=B5=E6=94=B6=E4=B8=8D?= =?UTF-8?q?=E5=88=B0=20done=E3=80=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 用户报的"探索完无法点击创建任务"真因：一个 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 条用例、扇出单元用例、本地工具契约用例全绿。 自测产生的任务/草稿已全部清理（未碰用户既有数据）。 --- README.md | 6 +- core/uiauto_helper.py | 10 +- doc/AI_CONSOLE.md | 5 + doc/AI_TASK_GEN.md | 45 ++++++--- doc/API.md | 3 +- doc/ARCHITECTURE.md | 2 +- doc/MCP.md | 5 +- doc/MCP_DESIGN.md | 2 +- doc/README.md | 2 +- doc/backlog/TODO.md | 8 +- doc/staffdeck/KNOWLEDGE_BASE.md | 8 +- mcp_agent/agent.py | 6 +- mcp_server/mcp_server.py | 84 +++++++++++++--- mcp_server/platform_client.py | 18 ++++ static/admin/agent.js | 4 +- static/admin/taskgen.js | 70 +++++++++++++- templates/admin/monitor.html | 7 ++ web/agent_api.py | 166 ++++++++++++++++++++++++++++---- 18 files changed, 384 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index d74ec66..fa4db85 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ | **实时看屏** | MJPEG 实时流 + 点击/滑动/按键/文字输入；全屏监控大屏（`/wall`） | | **应用管理** | APK 上传/解析/批量安装；设备已装应用与版本查询；剪贴板注入 | | **AI 控制台** | 用自然语言驱动 AI 操作指定设备（MCP 工具 + 截图），流式输出、Markdown 渲染、推理链折叠、token 统计；成功操作自动沉淀「经验库 / 动作库」并在相似任务中召回 | -| **MCP 接入** | 19 个 `de_*` 工具，把手机控制开放给外部 AI；写操作有开关、设备忙时拒绝、全量审计 | +| **MCP 接入** | 20 个 `de_*` 工具，把手机控制开放给外部 AI；写操作有开关、设备忙时拒绝、全量审计 | | **备份导出/导入** | 一键导出 zip（库快照 + manifest + 可选 APK），导入前校验预览、自动预备份、重启生效 | --- @@ -146,7 +146,7 @@ auto_control/ │ └── generic/ # 通用步骤任务（task_type=generic_steps，当前唯一类型） │ └── task.py # STEP_TYPES（18 种步骤）+ Worker + 执行器 │ -├── mcp_server/ # MCP Server（19 个 de_* 工具，:8033） +├── mcp_server/ # MCP Server（20 个 de_* 工具，:8033） │ ├── mcp_server.py # 工具定义 + 平台登录 + 门控 │ ├── platform_client.py # 平台 HTTP 客户端（复用 Web 账号） │ ├── direct_ops.py # 直连设备的 adb/u2 操作 @@ -304,7 +304,7 @@ self.set_progress(done=5, total=80, unit="视频", action_counts={"like": 3}, el ### MCP（外部 AI 接入） -MCP Server 监听 `:8033`，暴露 19 个 `de_*` 工具（截屏、点击、滑动、输入、OCR、元素树、应用管理等）。写操作需 `MCP_ALLOW_WRITE=1`；设备正在跑任务时拒绝（`device_busy`）；每次调用写审计日志。 +MCP Server 监听 `:8033`，暴露 20 个 `de_*` 工具（截屏、点击、滑动、输入、OCR、元素树、应用管理等）。写操作需 `MCP_ALLOW_WRITE=1`；设备正在跑任务时拒绝（`device_busy`）；每次调用写审计日志。 ```bash # 本机手动启动（生产容器由 scripts/start.sh 自动拉起） diff --git a/core/uiauto_helper.py b/core/uiauto_helper.py index 56afc62..f5b4894 100644 --- a/core/uiauto_helper.py +++ b/core/uiauto_helper.py @@ -393,7 +393,7 @@ def snapshot(serial, quality=85): 返回 (ok, 数据 | 错误信息)。数据形如： {"image": "data:image/jpeg;base64,…", "width": 720, "height": 1650, - "elements": [...], "unstable": false, "cost_ms": 1800} + "elements": [...], "unstable": false, "screen_state": "on", "cost_ms": 1800} """ import base64 import io @@ -406,6 +406,12 @@ def snapshot(serial, quality=85): try: d = u2.connect(serial) img1 = d.screenshot() # 先截：用户看到的就是这一刻 + # 屏幕开关状态（MCP 的 de_snapshot 要用它判断"要不要先 de_wake"； + # 本来只有 /api/screen/thumb 的响应头里有，这里顺手带上） + try: + screen_on = d.info.get("screenOn") + except Exception: + screen_on = None xml = d.dump_hierarchy() # 慢的一步（1.3~1.8s） img2 = d.screenshot() # 再截：和第一张比对 except Exception as e: @@ -431,4 +437,6 @@ def snapshot(serial, quality=85): return True, {"image": image, "width": w, "height": h, "elements": elements, "unstable": unstable, + "screen_state": ("on" if screen_on else "off") + if screen_on is not None else "unknown", "cost_ms": int((_t.time() - t0) * 1000)} diff --git a/doc/AI_CONSOLE.md b/doc/AI_CONSOLE.md index a1ace17..7519b0a 100644 --- a/doc/AI_CONSOLE.md +++ b/doc/AI_CONSOLE.md @@ -116,6 +116,11 @@ mcp_agent.Agent.run_stream(prompt, serial, history, on_delta, on_tool, on_usage, **刷新/重连不丢进度**：服务端事件队列保留积压，页面重新订阅（`GET /api/agent/stream?run_id=`）后会补发 delta/step/usage/done；`EventSource.onerror` **刻意不结束运行**，靠自动重连续上。另外 `GET /api/agent/run` 提供状态快照（其他窗口/8s 轮询用）。 +**多页面同时看同一轮**：一轮的事件用**扇出**（`web/agent_api.py` 的 `_Fanout`）发给每个订阅者各自 +的队列——两个页面都收到全量事件。**不要**退回"一个 run 一个 `queue.Queue`"：那样第二个页面一订阅， +两个 EventSource 就开始瓜分同一条队列，谁先取到算谁的（2026-09-14 实测：聊天页把建任务页的 `done` +取走了，建任务页永远等不到草稿）。 + ### 3.4 token 统计 - 请求带 `stream_options.include_usage`，服务端在**末尾 chunk** 返回 usage diff --git a/doc/AI_TASK_GEN.md b/doc/AI_TASK_GEN.md index 22716a6..afede4d 100644 --- a/doc/AI_TASK_GEN.md +++ b/doc/AI_TASK_GEN.md @@ -2,13 +2,13 @@ > 状态：**P0 已实现**（2026-09-13）——§1~§9 是设计稿（与实现基本一致）， > **§10 是实现记录**：差异、落地细节、怎么自测，以 §10 为准。 -> 现状请读：[AI_CONSOLE.md](AI_CONSOLE.md)（AI 控制台已实现的能力）、[TASK_DEV.md](TASK_DEV.md)（任务与步骤）、[MCP.md](MCP.md)（已实现的 19 个工具）。 +> 现状请读：[AI_CONSOLE.md](AI_CONSOLE.md)（AI 控制台已实现的能力）、[TASK_DEV.md](TASK_DEV.md)（任务与步骤）、[MCP.md](MCP.md)（已实现的 20 个工具）。 > 关联代码：`web/agent_api.py`、`mcp_server/`、`mcp_agent/`、`tasks/generic/`、`static/admin/editor.js`。最后核对：2026-09-10。 ## 1. 背景与目标 平台已有两套能力，但互不相通： -- **AI 控制台**：一句话 + 选设备 → 多模态 Agent（DeepSeek）通过 19 个 `de_*` 工具在手机上「边看边做」（截图看屏、`de_ui_tree` 拿元素树、`de_tap_element/de_tap_text` 语义点按），流式回放步骤。 +- **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 种节点），在编辑器里拖拽编排、单步试跑、定时调度。 目标：让**非工程用户用一句自然语言需求**（例：「创建一个每日养号刷视频的任务，每天 8:00-9:00 在 100.100.10.13 跑」）得到**一条可直接调度、可继续在现有步骤编辑器里手改的任务**。AI 先自己在设备上打开 App、看 UI 树、确认可点元素，再直接撰写编辑器的步骤 JSON。 @@ -36,7 +36,7 @@ ## 3. 现状与可复用点（实现依据） -- 多模态 Agent 链路：`web/agent_api.py`（`POST /api/agent/run` 起后台线程、SSE `delta/step/done/error`、`/stop`、刷新恢复 `GET /api/agent/run`）→ `mcp_agent/agent.py`（OpenAI 兼容流式，工具经 fastmcp Client 拉 8033 的 19 个 `de_*`）→ `mcp_server/mcp_server.py`。 +- 多模态 Agent 链路：`web/agent_api.py`（`POST /api/agent/run` 起后台线程、SSE `delta/step/done/error`、`/stop`、刷新恢复 `GET /api/agent/run`）→ `mcp_agent/agent.py`（OpenAI 兼容流式，工具经 fastmcp Client 拉 8033 的 20 个 `de_*`）→ `mcp_server/mcp_server.py`。 - 前端 AI 控制台骨架：`templates/admin/monitor.html` `#tab-agent` + `static/admin/agent.js`（设备选择、`sendAgentMsg`、`listenStream` 渲染 `agent-toolcard`、实时画面跟随）。 - 步骤权威 schema（前后端同构）：`tasks/generic/task.py` `STEP_TYPES`（L44-83）/ `DEFAULT_PARAMS`（L86-103） 与 `static/admin/editor.js` `STEP_LIB`（L3-23）。 - 元素抓取 → XPath：`web/tasks_api.py /api/uiauto/elements`（L224）→ `core/uiauto_helper.get_elements`（`suggested.value` 即编辑器可用的 XPath）。 @@ -155,10 +155,10 @@ ## 9. 需要转成 MCP / 平台工具的能力（分层，2026-09-09 与用户确认） -> 背景问答结论：目前 MCP 只有**设备层 19 个 `de_*`**（控制 + 只读 `de_list_tasks`），平台 CRUD（任务增改/启停/立即运行、分组、设备池、自定义动作、APK、备份、用户）**都还没 MCP 化**。方向认同「先把工具链补完善」，但不做"把所有平台 CRUD 一次性搬成 MCP"的大而全——**按消费方（AI 建任务 / 外部自动化）分层、按需补**。新增 MCP 工具一律：进 `doc/MCP.md` 手册 + `doc/MCP_DESIGN.md` 规格 + 与 web 同源的权限/busy/审计 + 校验逻辑下沉到 `core/` 共用（防双份漂移）。 +> 背景问答结论：目前 MCP 只有**设备层 20 个 `de_*`**（控制 + 只读 `de_list_tasks`），平台 CRUD（任务增改/启停/立即运行、分组、设备池、自定义动作、APK、备份、用户）**都还没 MCP 化**。方向认同「先把工具链补完善」，但不做"把所有平台 CRUD 一次性搬成 MCP"的大而全——**按消费方（AI 建任务 / 外部自动化）分层、按需补**。新增 MCP 工具一律：进 `doc/MCP.md` 手册 + `doc/MCP_DESIGN.md` 规格 + 与 web 同源的权限/busy/审计 + 校验逻辑下沉到 `core/` 共用（防双份漂移）。 ### 9.1 现状盘点 -- MCP（`mcp_server/mcp_server.py`，19 个 `de_*`）＝ 设备控制 + 设备只读 + `de_list_tasks`（平台任务只读）。 +- MCP（`mcp_server/mcp_server.py`，20 个 `de_*`）＝ 设备控制 + 设备只读 + `de_list_tasks`（平台任务只读）。 - 任务创建/修改/删除、toggle、立即运行、分组、设备池管理、自定义动作、APK、系统备份等 **REST 路由只给前端用，未暴露 MCP**。 ### 9.2 P0 —— AI 建任务链路真正需要的「平台工具」（最小集） @@ -215,8 +215,18 @@ `openTaskModal(null, prefill)` 预填（用唯一 draftKey，避开 localStorage 旧草稿覆盖）。 - **两个页面共用一个运行槽**：`GET /api/agent/run` 回 `mode`，两个前端各按 mode 决定 是否订阅 SSE（一个 run 只有一个事件队列，两个 EventSource 同时消费会互相瓜分事件）。 +- **落库出口**：页面上的「✓ 直接创建任务」（`POST /api/agent/task_draft/create`）与 + 「在步骤编辑器中核对」（预填编辑器 → 用户点保存）——两条路最终都汇到 `add_job`。 -### 10.3 附带修掉的一个协议 bug +### 10.3 附带修掉的两个 bug + +**(1) 事件被另一个页面抢走**（用户报的"探索完没法创建任务"的真因）：一轮的事件原先只有一个 +`queue.Queue`，聊天页与建任务页同时开着时，两个 EventSource **瓜分**同一条队列——建任务页的回放 +会卡在中间，`done` 事件被聊天页取走 → 永远等不到草稿 → 页面上没有可点的"创建"。 +现改为**扇出**（`web/agent_api.py` 的 `_Fanout`）：每个订阅者一个专属队列，多开页面各看各的； +前端两侧也按 `mode` 门控，不互相订阅。 + +**(2) 工具消息配对** Chat 模式同样受益：一轮里若模型同时调了 `de_screenshot` 与别的工具，旧实现会把截图图像 作为一条 `user` 消息**插在两条 tool 消息之间**，模型侧判定"工具回应不足"直接 400 @@ -224,14 +234,25 @@ Chat 模式同样受益：一轮里若模型同时调了 `de_screenshot` 与别 现改为：本轮 tool 消息发完后再附一条 user 图像消息；`_repair_tool_messages` 也改成 只数**连续**的 tool 消息。 -### 10.4 还没做（P1 / 后续） +### 10.4 后续批次（2026-09-14 已完成的三项） -- 「探索完直接创建」接口（服务端复验后 `add_job`）——目前一律走人工确认。 -- draft → `agent_experience` / `agent_action` 沉淀（模板重用）。 -- MCP 侧补 `de_snapshot`（截图+元素树一次取齐，见 `doc/research/U2_ELEMENT_SELECTORS.md`）。 -- 多设备并行探索、成本控制。 +- ✅ **「直接创建」**：`POST /api/agent/task_draft/create` + 页面上的按钮与「探索完直接创建任务」 + 勾选框。两条设计约束：草稿体只存在于服务端（客户端只能传 overrides，少一个可篡改入口）； + 创建前**再校验一次**，通过后走与「新建任务」完全相同的 `context.mgr.add_job`， + 创建成功后清草稿（同一份草稿不会被重复建成多个任务）。 +- ✅ **草稿沉淀经验/动作**：designer 轮次也走 `_distill_experience` / `_distill_actions` + 沉淀，但**只在草稿通过校验时**（说明这轮探索确实走通了一条路；没草稿的试错不入库）。 +- ✅ **MCP `de_snapshot`**：截图+元素树一次取齐（20 个 `de_*` 工具了），并把 + `screen_state` 一并返回；designer/聊天两套提示词都改为**优先用 de_snapshot**。 + 见 [MCP.md](MCP.md) §4.2。 -### 10.5 自测怎么跑 +### 10.5 仍未做 + +- 多设备并行探索、探索成本/token 控制（一轮真机探索 3~30 万 token）。 +- 把**动作库**当 generic_steps 的预制件复用（设计稿 §9.2 的只读清单类 MCP 工具）。 +- 平台的 `/api/uiauto/snapshot` 目前只被 MCP 与抓取弹窗用，还可在 designer 里做"同屏缓存"。 + +### 10.6 自测怎么跑 1. 纯逻辑：`core/task_draft` 的正反例（未知 type / 空 selector / `click_xy` / cron 少段 / 深度 6 / probability 越界 …），断言 `errors` 文案模型能读懂。 diff --git a/doc/API.md b/doc/API.md index 930f27a..ab5d8ec 100644 --- a/doc/API.md +++ b/doc/API.md @@ -215,6 +215,7 @@ | POST | `/api/agent/actions/delete` | 删除动作 | | GET | `/api/agent/task_draft` | **AI 建任务**：读回最近一份草稿（`{saved, running, mode, run_id, draft, draft_error}`） | | POST | `/api/agent/task_draft` | 回存草稿并**重新校验**（不通过返回 400 + `errors`） | +| POST | `/api/agent/task_draft/create` | **直接创建**：取暂存草稿 → 再校验 → `add_job` → 清草稿（body 可带 `{serial, overrides}`；草稿体不接受客户端提交） | | POST | `/api/agent/task_draft/clear` | 丢弃草稿 | **AI 建任务（designer 模式）要点**（详见 [AI_TASK_GEN.md](AI_TASK_GEN.md)）： @@ -543,7 +544,7 @@ | `GET /api/uiauto/status` | — | uiautodev（:20242）是否在跑，前端据此禁/启用"抓取元素" | | `GET /api/uiauto/devices` | — | 可选设备列表（uiautodev 设备 + 池内在线补全） | | `GET /api/uiauto/elements?serial=` | — | 扁平元素列表（走 uiautodev），每项带 `suggested`、`bounds`、`depth` | -| `GET /api/uiauto/snapshot?serial=` | — | **一次取齐**：截图 + 元素树（原生 u2 同一连接背靠背）→ `{image,width,height,elements,unstable,cost_ms}`；抓取弹窗用这个，失败返回 **502** | +| `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 | | `POST /api/steps/test` | `{"serial","step":{…}}` | 真机试执行单个步骤 → `命中 / 未找到 / 已执行` | diff --git a/doc/ARCHITECTURE.md b/doc/ARCHITECTURE.md index 1feeb16..ac0b12a 100644 --- a/doc/ARCHITECTURE.md +++ b/doc/ARCHITECTURE.md @@ -39,7 +39,7 @@ ▲ ▲ ┌───────────────────────────┴────────┐ ┌───────────┴──────────────────┐ │ MCP Server（mcp_server/，:8033） │ │ AI Agent（mcp_agent/） │ -│ 19 个 de_* 工具，供外部 AI 调用 │ │ OpenAI 兼容模型 → MCP 工具 │ +│ 20 个 de_* 工具，供外部 AI 调用 │ │ OpenAI 兼容模型 → MCP 工具 │ └────────────────────────────────────┘ └──────────────────────────────┘ ``` diff --git a/doc/MCP.md b/doc/MCP.md index 8cb5b26..ddea366 100644 --- a/doc/MCP.md +++ b/doc/MCP.md @@ -12,7 +12,7 @@ AI 控制台 / 外部 MCP 客户端 │ Streamable HTTP（http://:8033/mcp） ▼ -MCP Server（mcp_server/mcp_server.py） ← 19 个 de_* 工具 +MCP Server（mcp_server/mcp_server.py） ← 20 个 de_* 工具 │ 平台 HTTP API（登录 + CSRF） 或 轻量 adb/u2 直连 ▼ auto_control 平台（:18050） ← 设备池 / 任务 / 看屏 @@ -63,7 +63,7 @@ MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<平台密码> \ --- -## 4. 工具清单（19 个） +## 4. 工具清单（20 个） 统一返回约定： @@ -88,6 +88,7 @@ MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<平台密码> \ |------|------|------------| | `de_screenshot` | `serial` | `{image:{type:"image",data:,mimeType:"image/jpeg"}, width, height, native_size, screen_state}`。多模态模型直接看图 | | `de_ui_tree` | `serial`, `limit`(150，1-300) | `{count, elements:[{text,id,desc,class,clickable,bounds}]}`，**可点击元素排前**；`limit` 控 token | +| `de_snapshot` | `serial`, `limit`(120，1-300) | **截图 + 元素树一次取齐**（推荐用它代替 `de_screenshot`+`de_ui_tree`）：平台侧同一个 u2 连接背靠背取 + 双截图校验。返回 `{image, width, height, native_size, screen_state, unstable, cost_ms, count, elements}`；`unstable=true` 表示抓取期间界面在变化（此时元素坐标不可信，让设备静下来再取）。**同样会建立 `de_tap/de_swipe` 的坐标空间** | | `de_ocr` | `serial` | `{count, texts:[{text,score}]}`（≤100 条）。UI 树拿不到的图片/WebView 文字用它 | | `de_read_clipboard` | `serial` | `{clipboard}` | | `de_list_apps` | `serial`, `keyword`("") | `{count, packages}` 第三方已装包名（`pm list packages -3`，≤200） | diff --git a/doc/MCP_DESIGN.md b/doc/MCP_DESIGN.md index d5e4494..b5a718b 100644 --- a/doc/MCP_DESIGN.md +++ b/doc/MCP_DESIGN.md @@ -1,6 +1,6 @@ # MCP 手机控制（Mobile Control MCP Server）设计文档 -> 状态：**设计稿 / 演进记录**——凡与实现不符处，以 [MCP.md](MCP.md)（使用手册，含 19 个工具的权威清单）与 `mcp_server/` 代码为准。 +> 状态：**设计稿 / 演进记录**——凡与实现不符处，以 [MCP.md](MCP.md)（使用手册，含 20 个工具的权威清单）与 `mcp_server/` 代码为准。 > 本文保留设计取舍与里程碑，便于回溯"为什么这么做"；文中的"演进备选"均**未落地**。 > 最后核对：2026-09-10（对照 dev 现状）。 diff --git a/doc/README.md b/doc/README.md index 5628d03..8051a94 100644 --- a/doc/README.md +++ b/doc/README.md @@ -14,7 +14,7 @@ | [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 种步骤全表、选择器与定位、自定义动作、新增任务类型模板 | 写任务的开发 | -| [MCP.md](MCP.md) | **MCP 手机控制手册**：19 个 `de_*` 工具用法、写操作门控、坐标换算、接入示例 | 接入方、数字员工 | +| [MCP.md](MCP.md) | **MCP 手机控制手册**：20 个 `de_*` 工具用法、写操作门控、坐标换算、接入示例 | 接入方、数字员工 | | [MCP_DESIGN.md](MCP_DESIGN.md) | **MCP 设计文档**：边界划分、错误码、白名单/审计设计、演进方向 | 平台开发者 | | [AI_CONSOLE.md](AI_CONSOLE.md) | **AI 控制台**：会话/SSE、经验库、动作库、巡检、Markdown 渲染、推理链、token 统计 | 使用者、平台开发者 | | [AI_TASK_GEN.md](AI_TASK_GEN.md) | **AI 建任务**：AI 自己在真机探索 → 写出可调度任务 → 人工确认入库（P0 已实现；契约与红线） | 平台开发者、使用者 | diff --git a/doc/backlog/TODO.md b/doc/backlog/TODO.md index 6dd8349..7c358e0 100644 --- a/doc/backlog/TODO.md +++ b/doc/backlog/TODO.md @@ -96,8 +96,12 @@ ## D. AI 控制台 / 经验与动作 - [ ] 「🧠 经验库 / 🎬 动作库」合为一个面板（标签页切换）。 -- [x] ~~AI 建任务 P0~~（✅ 2026-09-13：独立子页「AI 建任务」+ `submit_task` 校验 + 草稿预览/预填，见 [AI_TASK_GEN.md](../AI_TASK_GEN.md) §10）。 - - 仍未做：平台级 MCP 只读清单（`task_types/groups/pool`）、把**动作库**当 generic_steps 预制件复用、draft→经验/动作沉淀、「探索完直接创建」接口。 +- [x] ~~AI 建任务 P0~~（✅ 2026-09-13：独立子页「AI 建任务」+ `submit_task` 校验 + 草稿预览/预填；✅ 2026-09-14 补齐「直接创建」`POST /api/agent/task_draft/create`、草稿→经验/动作沉淀、MCP `de_snapshot`。见 [AI_TASK_GEN.md](../AI_TASK_GEN.md) §10）。 + - 仍未做：平台级 MCP 只读清单（`task_types/groups/pool`）、把**动作库**当 generic_steps 预制件复用、探索成本控制。 +- [ ] `mcp_server/platform_client._login()` 对"登录失败"不设防：平台把登录页当 200 返回时会被当成 + 登录成功，后续所有调用都拿不到 JSON，最终只报含糊的 `platform_unavailable`（2026-09-14 排查 + `de_snapshot` 时踩到：现场进程没带 `MCP_PLATFORM_PASS`）。应校验响应内容/最终 URL，并明确报 + "平台账号或密码不对"。 - [ ] 新增 MCP `de_screen_text`（文本化看屏：前台包名 + screen_state + 可点元素文本 + OCR），并把操作纪律写进工具 description。 - [ ] 经验召回改进：现为 bigram + `ORDER BY hits`（候选只看 top50、hits 对所有命中行回写 → 马太效应）；改为对称相似度 / 更合理候选集，`hits` 仅在真正注入时 +1。 - [ ] 经验/动作入库依赖模型蒸馏成功：加失败重试与可视化观测（现在只在日志里）。 diff --git a/doc/staffdeck/KNOWLEDGE_BASE.md b/doc/staffdeck/KNOWLEDGE_BASE.md index e2916ef..923a538 100644 --- a/doc/staffdeck/KNOWLEDGE_BASE.md +++ b/doc/staffdeck/KNOWLEDGE_BASE.md @@ -24,7 +24,7 @@ 安卓设备自动化中台：管理一批手机（网络 `IP:5555` / USB 串号），支持任务调度、步骤编排、看屏与操作。 -- 你能用的入口：**MCP Server**（推荐，19 个 `de_*` 工具）；备选 REST（§2.2）。 +- 你能用的入口：**MCP Server**（推荐，20 个 `de_*` 工具）；备选 REST（§2.2）。 - **可做**：看屏、截图、UI 树、OCR、开/关 App、点击、滑动、按键、输入、剪贴板、亮/熄屏、看前台包名、列应用、只读看平台任务。 - **不可做**：创建/修改/启停平台任务、分组/设备池/备份管理（MCP 未提供）。 @@ -52,9 +52,9 @@ --- -## 3. 工具清单（19 个） +## 3. 工具清单（20 个） -**只读（不触发占用锁）**：`de_list_devices` · `de_screenshot` · `de_ui_tree` · `de_ocr` · `de_foreground_app` · `de_list_apps` · `de_read_clipboard` · `de_list_tasks` +**只读（不触发占用锁）**：`de_list_devices` · `de_screenshot` · `de_snapshot`（截图+元素树一次取齐，**推荐**）· `de_ui_tree` · `de_ocr` · `de_foreground_app` · `de_list_apps` · `de_read_clipboard` · `de_list_tasks` **写（受占用锁约束）**：`de_tap_text` · `de_tap_element` · `de_tap` · `de_swipe` · `de_press_key` · `de_type_text` · `de_set_clipboard` · `de_open_app` · `de_stop_app` · `de_wake` · `de_sleep` @@ -69,7 +69,7 @@ - **用 `de_list_devices` 取，别猜。** ### 4.2 坐标空间（重要） -- `de_screenshot` 返回**缩放图（≤540px 宽）+ `native_size`**；`de_tap`/`de_swipe` 用**截图坐标系**，服务端换算原生。 +- `de_screenshot`/`de_snapshot` 返回**缩放图（≤540px 宽）+ `native_size`**；`de_tap`/`de_swipe` 用**截图坐标系**，服务端换算原生（两者都会建立坐标空间）。 - **必须先截图再坐标操作**；否则报「请先执行 de_screenshot」。 - 屏可能旋转/滚动 → **优先文字/元素，坐标仅兜底**。 diff --git a/mcp_agent/agent.py b/mcp_agent/agent.py index 8373d9a..1fae3d6 100644 --- a/mcp_agent/agent.py +++ b/mcp_agent/agent.py @@ -39,7 +39,9 @@ CHAT_SYSTEM_PROMPT = """你是手机自动化控制助手。你通过工具实 工作规范： 1. 先 de_list_devices 确定目标设备（在线才可操作）；设备有 name（名称）与 serial（地址）， **给用户汇报时用名称**（同型号多台靠它区分），调工具时仍用 serial -2. 观察屏幕：先 de_screenshot 获取截图（图像会随后给你），基于截图理解当前界面 +2. 观察屏幕：优先 `de_snapshot`（截图+元素树一次取齐，图像会随后给你）——比 + de_screenshot + de_ui_tree 两次取数更省步骤，界面在动时也不会出现"元素位置和 + 截图对不上"；需要单独看画面时才用 de_screenshot 3. 点击定位分优先级（不要自己推算像素坐标，那是精度最差的方式）： a) 目标有可见文字（按钮/菜单/列表标题/标签/输入框提示）→ de_tap_text 直接给文字， 一次完成「找到并点击」，原生控件与 WebView/图片渲染文字都支持 @@ -73,7 +75,7 @@ DESIGNER_SYSTEM_PROMPT = """你是手机自动化**任务设计师**。你的产 ## 探索规范 1. 只用本次指定的设备 serial；给用户汇报时用设备名。设备离线/异常/被任务占用时**立即停止并说明**，不要硬试。 -2. **先看再动**：`de_screenshot` 看屏 → `de_ui_tree(limit=80~150)` 拿元素（字段只有 text/id/desc/class/clickable/bounds，**没有 xpath**）。同一屏只 dump 一次，不要反复截图。 +2. **先看再动**：优先 `de_snapshot(limit=80~150)`——它**一次取齐**截图与元素树（元素字段只有 text/id/desc/class/clickable/bounds，**没有 xpath**），比"先 de_screenshot 再 de_ui_tree"少一次来回、且不会因为界面在动而错位；返回 `unstable=true` 时说明取的时候界面在变，等界面静下来再取一次。同一屏只取一次，不要反复截图。 3. 不知道包名先 `de_list_apps(keyword=…)`，再 `de_open_app(package)`；用 `de_foreground_app` 确认前台。 4. **定位优先级**：`text` / `description` / `resourceId` > `xpath` > 坐标。**禁止坐标**（绝不产 `click_xy`）。 包含匹配只能 `descriptionContains`，或 `xpath` 里的 `//*[contains(@text,"…")]`（没有 textContains 这个类型）。 diff --git a/mcp_server/mcp_server.py b/mcp_server/mcp_server.py index 69448b2..d8f954e 100644 --- a/mcp_server/mcp_server.py +++ b/mcp_server/mcp_server.py @@ -204,6 +204,23 @@ _KEYS = ("back", "home", "recent", "menu", "power", "volume_up", "volume_down", "enter", "delete", "search", "camera") +def _slim_elements(els, limit): + """精简元素列表（de_ui_tree / de_snapshot 共用）：去 suggested/深度噪音， + 可点击优先、有文案优先，控制 token。""" + slim = [] + for e in els: + slim.append({ + "text": e.get("text", "")[:50], + "id": e.get("resource_id", "")[:80], + "desc": e.get("description", "")[:50], + "class": e.get("class", "").split(".")[-1], + "clickable": e.get("clickable", "") == "true", + "bounds": e.get("bounds", ""), + }) + slim.sort(key=lambda x: (not x["clickable"], not (x["text"] or x["desc"]))) + return slim[:limit] + + @mcp.tool() def de_ui_tree(serial: str, limit: int = 150) -> dict: """获取当前界面元素树（文本 JSON）：每元素含 text/resource_id/description/class/bounds。 @@ -219,20 +236,61 @@ def de_ui_tree(serial: str, limit: int = 150) -> dict: els = platform().ui_elements(serial) except PlatformError as e: return _err(e) - # 精简输出：去掉 suggested/深度噪音，保留可定位属性；可点击优先、有文案优先 - slim = [] - for e in els: - slim.append({ - "text": e.get("text", "")[:50], - "id": e.get("resource_id", "")[:80], - "desc": e.get("description", "")[:50], - "class": e.get("class", "").split(".")[-1], - "clickable": e.get("clickable", "") == "true", - "bounds": e.get("bounds", ""), - }) - slim.sort(key=lambda x: (not x["clickable"], not (x["text"] or x["desc"]))) + slim = _slim_elements(els, limit) audit.audit("de_ui_tree", serial, "", f"{len(slim)} 元素") - return _ok({"count": len(slim), "elements": slim[:limit]}) + return _ok({"count": len(slim), "elements": slim}) + + +@mcp.tool() +def de_snapshot(serial: str, limit: int = 120) -> dict: + """一次取齐：屏幕截图 + 元素树（**推荐用它代替 de_screenshot + de_ui_tree**）。 + + 那两条是两次独立取数，中间隔着元素树 dump 本身的 1~2 秒——界面只要在动 + （信息流/视频/加载动画），返回的元素坐标就和截图对不上，照它点击会点偏。 + 本工具在平台侧用**同一个连接背靠背取**，并额外做双截图校验： + `unstable=true` 表示"抓取过程中界面在变化"，此时别把元素坐标当准的， + 建议让设备停在静止界面再取一次。 + + 返回 image（宽 ≤540 的可视截图，同时建立后续 de_tap/de_swipe 的坐标空间）、 + native_size、screen_state、unstable、cost_ms，以及 elements + （结构与 de_ui_tree 相同；limit 控制条数，默认 120）。 + """ + try: + serial = _check_serial(serial) + if limit < 1 or limit > 300: + raise PlatformError("invalid_param", "limit 需在 1-300 之间") + snap = platform().snapshot(serial) + raw = snap.get("image") or "" + b64 = raw.split(",", 1)[1] if "," in raw else raw + img = Image.open(io.BytesIO(base64.b64decode(b64))) + nw, nh = img.size + if nw > S.screenshot_width: + ratio = S.screenshot_width / nw + img = img.resize((S.screenshot_width, int(nh * ratio))) + buf = io.BytesIO() + img.convert("RGB").save(buf, "JPEG", quality=S.jpeg_quality) + data = base64.b64encode(buf.getvalue()).decode() + # 与 de_screenshot 用同一套坐标口径：后续 de_tap/de_swipe 传的是这张图的坐标 + _coord[serial] = (img.size[0], img.size[1], nw, nh) + except PlatformError as e: + return _err(e) + except Exception as e: + return _err(PlatformError("platform_unavailable", f"快照处理失败: {e}")) + slim = _slim_elements(snap.get("elements") or [], limit) + unstable = bool(snap.get("unstable")) + audit.audit("de_snapshot", serial, f"{len(slim)} 元素", + "unstable" if unstable else "ok") + out = {"image": {"type": "image", "data": data, "mimeType": "image/jpeg"}, + "width": img.size[0], "height": img.size[1], + "native_size": {"width": nw, "height": nh}, + "screen_state": snap.get("screen_state", "unknown"), + "unstable": unstable, + "cost_ms": snap.get("cost_ms", 0), + "count": len(slim), "elements": slim} + if unstable: + out["hint"] = ("抓取期间界面在变化（unstable）：元素坐标可能已过时，" + "让设备停在静止界面再取一次更稳") + return _ok(out) @mcp.tool() diff --git a/mcp_server/platform_client.py b/mcp_server/platform_client.py index 1fea8f9..2633f82 100644 --- a/mcp_server/platform_client.py +++ b/mcp_server/platform_client.py @@ -80,6 +80,24 @@ class PlatformClient: f"截图 HTTP {r.status_code}") return r.content, r.headers.get("X-Screen-State", "unknown") + def snapshot(self, serial): + """一次取齐截图+元素树（GET /api/uiauto/snapshot）。 + + 平台侧用**同一个 u2 连接**背靠背 dump+screenshot，并做双截图校验 + （unstable 表示"抓取期间界面在变化"）。返回平台 JSON： + {ok, image(data-url), width, height, elements, unstable, screen_state, cost_ms} + """ + r = self._get("/api/uiauto/snapshot", serial=serial, _t=0) + if r.status_code in (502, 503): + raise PlatformError("device_offline", r.text[:160]) + if r.status_code != 200: + raise PlatformError("platform_unavailable", + f"快照 HTTP {r.status_code}") + j = r.json() or {} + if not j.get("ok"): + raise PlatformError("device_offline", str(j.get("error", "快照失败"))[:160]) + return j + def screen_size(self, serial): """屏幕原生分辨率（GET /api/screen/size），返回 (w, h)。""" r = self._get("/api/screen/size", serial=serial) diff --git a/static/admin/agent.js b/static/admin/agent.js index 4d510a8..a8a3a3a 100644 --- a/static/admin/agent.js +++ b/static/admin/agent.js @@ -577,7 +577,9 @@ function listenStream(runId){ setTimeout(()=>{ if(!_agentStream && _agentBusy){ apiGet('/api/agent/run').then(r=>{ - if(r&&r.ok&&r.state==='running'&&r.run_id) listenStream(r.run_id); + // 建任务模式（designer）归「AI 建任务」子页订阅，这里同样要让开 + if(r&&r.ok&&r.state==='running'&&r.run_id&&r.mode!=='designer') + listenStream(r.run_id); }); } }, 5000); diff --git a/static/admin/taskgen.js b/static/admin/taskgen.js index c0562a1..e698fcf 100644 --- a/static/admin/taskgen.js +++ b/static/admin/taskgen.js @@ -207,6 +207,13 @@ function listenTaskGenStream(runId){ if(d.draft){ _tgDraft = d.draft; _tgWarnings = d.warnings || []; tgRenderDraft(); + if(tgAutoCreateOn()){ + // 用户勾了「探索完直接创建」：不再等确认，直接建（服务端仍会再校验一次） + tgStatus('探索完成，正在直接创建任务…'); + createDraft(true); + endTaskGenStream(); + return; + } tgStatus('探索完成，共 ' + steps + ' 步。请核对草稿后创建任务。'); }else{ tgStatus(steps ? ('探索结束（' + steps + ' 步），但没有产出草稿。') @@ -328,8 +335,11 @@ function tgRenderDraft(){ + ''); } html.push('
' - + '' - + '' + + '' + + '' + + '' + '
'); box.innerHTML = '
' + html.join('') + '
'; } @@ -379,6 +389,62 @@ async function openDraftInEditor(){ warnings: _tgWarnings}); } +// 勾了「探索完直接创建」就用它 +function tgAutoCreateOn(){ + const c = document.getElementById('tg-auto-create'); + return !!(c && c.checked); +} + +// 把草稿直接建成任务（服务端取暂存草稿 → 再校验 → add_job → 清草稿） +// auto=true 表示是勾了开关后的自动创建（不再弹确认） +function createDraft(auto){ + if(!_tgDraft){ showToast('还没有草稿','error'); return; } + const name = ((_tgDraft.task||{}).name) || '这条任务'; + if(!auto && !confirm('直接创建任务「' + name + '」？\n\n' + + '创建后就是一条正式的可调度任务（可在任务页编辑/停用），' + + '不再经过步骤编辑器的核对。')) return; + const cfg = tgCollectSettings(); + tgStatus('正在创建任务…'); + apiPost('/api/agent/task_draft/create', { + serial: ((document.getElementById('tg-serial')||{}).value||''), + overrides: cfg ? cfg.settings : {} + }).then(r=>{ + if(!r || !r.ok){ + const errs = (r && r.errors && r.errors.length) + ? '：' + r.errors.slice(0,3).join('；') : ''; + showToast(((r&&r.error)||'创建失败') + errs, 'error'); + tgStatus('创建失败 —— 可以「在步骤编辑器中核对」后手工保存'); + return; + } + const job = r.job || {}; + _tgDraft = null; _tgWarnings = []; + const box = document.getElementById('tg-draft'); + if(box){ + box.innerHTML = '

✅ 任务已创建：' + esc(job.name||'') + '

' + + '
下次运行：' + esc(job.next_run || '手动触发') + + ' ｜ 调度：' + esc(tgScheduleText(job.schedule)) + + ' ｜ id ' + esc(job.id||'') + '
' + + ((r.warnings||[]).length + ? '
' + r.warnings.map(w=>'· ' + esc(w)).join('
') + '
' + : '') + + '
' + + '' + + '' + + '
'; + } + tgStatus('任务已创建：' + (job.name||'')); + showToast('任务「' + (job.name||'') + '」已创建', 'success'); + if(typeof loadTasks === 'function') loadTasks(); + }); +} + +function tgResetDraftView(){ + _tgDraft = null; _tgWarnings = []; + const box = document.getElementById('tg-draft'); + if(box) box.innerHTML = ''; + tgStatus(''); +} + function discardDraft(){ if(!confirm('丢弃这份草稿？')) return; apiPost('/api/agent/task_draft/clear', {}).then(r=>{ diff --git a/templates/admin/monitor.html b/templates/admin/monitor.html index 7585a1f..4392129 100644 --- a/templates/admin/monitor.html +++ b/templates/admin/monitor.html @@ -366,6 +366,9 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14 .tg-hint{font-size:11px;color:var(--text-light);line-height:1.5} .tg-actions{display:flex;gap:8px} .tg-actions .btn{flex:1} +.tg-check{display:flex;align-items:flex-start;gap:6px;font-size:11.5px;color:var(--text-light);cursor:pointer;line-height:1.5} +.tg-check input{margin-top:2px;flex:none} +.tg-check b{color:var(--text)} .tg-status{font-size:11.5px;color:var(--text-light);min-height:16px;line-height:1.5} .tg-right-head{display:flex;justify-content:space-between;align-items:center;font-size:12.5px;font-weight:700;color:#374151} .tg-stream{flex:1;min-height:120px;overflow-y:auto;border:1px solid #e5e7eb;border-radius:12px;background:#fff;padding:10px;display:flex;flex-direction:column;gap:6px} @@ -688,6 +691,10 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14 +