From a94f63f0bf26c49d0b81caf02d5911070861c4a3 Mon Sep 17 00:00:00 2001
From: butubb <1422726308@qq.com>
Date: Sun, 13 Sep 2026 20:56:37 +0800
Subject: [PATCH 1/9] =?UTF-8?q?docs:=20=E5=85=83=E7=B4=A0=E9=80=89?=
 =?UTF-8?q?=E6=8B=A9=E5=99=A8=E7=A0=94=E7=A9=B6=E2=80=94=E2=80=94=E3=80=8C?=
 =?UTF-8?q?=E7=82=B9=E4=B8=8D=E5=88=B0=E6=8C=89=E9=92=AE=E3=80=8D=E7=9A=84?=
 =?UTF-8?q?=E6=A0=B9=E5=9B=A0=E6=98=AF=E5=BA=8F=E5=8F=B7=E5=9E=8B=E9=80=89?=
 =?UTF-8?q?=E6=8B=A9=E5=99=A8=EF=BC=88=E9=99=84=E5=AE=9E=E6=B5=8B=E8=AF=81?=
 =?UTF-8?q?=E6=8D=AE=E4=B8=8E=E8=A7=A3=E6=B3=95=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

用户反馈任务步骤老是点不到元素，怀疑"执行用的 u2"和"抓取用的 uiautodev"两条
通道不一致。建 research 分支实测，结论与假设相反：

1) **两条通道其实是一致的**：同设备同屏各 dump 一次，节点数 330/330、
   id 个数逐项相同 —— 都是同一份 UiAutomation 树，不存在"看到的不一样"。
   顺带纠正一处过时注释：uiautodev 的 `rect` 就是像素（`bounds` 才是归一化）。

2) **真凶是序号型选择器**：复现「抖音→我页面」，底部 `0qf` 只有 **3 个**
   （首页/消息/我 —— 「朋友」tab 是灰度功能，有的账号/设备没有），
   而任务里写死 `(…0qf…)[4]` → 第 4 个不存在 → 必然点空。
   同一选择器在 4 tab 设备上碰巧对、在 3 tab 设备上必错 —— 这就是"时好时坏"。

3) **解法（实测有效）**：同一 id 多实例时用**文字/描述限定**：
   `//*[@resource-id="…0qf" and @text="我"]` → 命中并把设备带进我页面（jy- 出现）。

文档里还列了同类限定条件的优先级与四条待排期改动（抓取器优先产语义选择器、
对带序号的选择器加提示、存量任务批量复核、运行期 dump 同 id 实例数）。
---
 doc/README.md                        |  1 +
 doc/research/U2_ELEMENT_SELECTORS.md | 98 ++++++++++++++++++++++++++++
 2 files changed, 99 insertions(+)
 create mode 100644 doc/research/U2_ELEMENT_SELECTORS.md

diff --git a/doc/README.md b/doc/README.md
index 10e742a..de7e852 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -24,6 +24,7 @@
 | [STF_REMOVAL.md](STF_REMOVAL.md) | **历史记录**：摘除 OpenSTF 的迁移过程（阶段 0-3） | 追溯背景时参考 |
 | [staffdeck/KNOWLEDGE_BASE.md](staffdeck/KNOWLEDGE_BASE.md) | 给 StaffDeck 数字员工的知识库（MCP 接入/工具/约定/红线） | 外部 AI 接入方 |
 | [staffdeck/JOB_SPEC.md](staffdeck/JOB_SPEC.md) | 数字员工岗位说明（岗位描述/看板摘要/执行约束） | 外部 AI 接入方 |
+| [research/U2_ELEMENT_SELECTORS.md](research/U2_ELEMENT_SELECTORS.md) | **元素选择器研究**：「点不到按钮」的根因（序号型选择器随界面变形而错位）与语义选择器解法 | 写任务/抓元素的开发 |
 | [backlog/TODO.md](backlog/TODO.md) | 已确认但暂缓的待办（含已知问题） | 所有开发者 |
 
 项目根目录的 [README.md](../README.md) 是**项目总览与快速上手**（面向第一次接触项目的人），细节都在本目录。
diff --git a/doc/research/U2_ELEMENT_SELECTORS.md b/doc/research/U2_ELEMENT_SELECTORS.md
new file mode 100644
index 0000000..3cbf648
--- /dev/null
+++ b/doc/research/U2_ELEMENT_SELECTORS.md
@@ -0,0 +1,98 @@
+# 元素选择器研究：为什么"点不到按钮"（2026-09-13）
+
+> 背景：任务步骤（`click` 等）频繁出现"元素明明在屏幕上却点不到"。用户怀疑是
+> 任务执行用的 u2 与元素抓取用的 uiautodev 两条通道不一致，要求研究。
+> 分支：`research/raw-u2-elements`。
+
+---
+
+## 一、先否掉一个假设：两条通道**并不**冲突
+
+| | 用的东西 | 连接方式 |
+|---|---|---|
+| 任务执行（点击/输入…）| 原生 `u2.connect(serial)` | 直连设备的 uiautomator2 server |
+| 元素抓取（编辑器按钮）| `uiautodev` 服务（localhost:20242）→ `/api/android/{serial}/hierarchy` | 它自己的连接 |
+
+实测（同一设备、同一屏、同一时刻，两边各 dump 一次）：
+
+| 对比项 | u2 | uiautodev |
+|---|---|---|
+| 节点总数 | 330 | 330 |
+| `id/0qf`（抖音底部 tab） | 3 | 3 |
+| `id/content_layout` | 5 | 5 |
+
+**逐项一致** —— 两个通道给出的元素树是同一份（都是设备的 UiAutomation dump）。
+所以"抓取看到的和执行看到的不是一回事"这个假设**不成立**。
+
+> 顺带纠正一处过时注释：`core/uiauto_helper.py` 说"uiautodev 归一化浮点坐标无法换算像素"。
+> 实际上 uiautodev 的节点里 **`rect` 就是像素**（`{x,y,width,height}`），`bounds` 才是
+> 归一化的 0~1 浮点。要用像素直接用 `rect` 即可。
+
+---
+
+## 二、真正的原因：**序号型选择器**（`(…)[k]`）会随界面变形而错位
+
+复现（192.168.20.100，抖音 v40.4.0）—— 进「我」页面，底部导航 dump 出来是：
+
+```
+[1] text='首页'  bounds=[38,1484][106,1530]
+[2] text='消息'  bounds=[470,1484][538,1530]
+[3] text='我'    bounds=[631,1484][665,1530]
+```
+
+只有 **3 个** `0qf`。而任务里的步骤写的是：
+
+```
+(//*[@resource-id="com.ss.android.ugc.aweme:id/0qf"])[4]    ← 第 4 个，根本不存在
+```
+
+**必然点空** —— 日志里表现为 `click 未找到元素`，而界面上那个「我」明明就在那儿。
+
+### 为什么有的设备是 4 个？
+
+抖音底部的「朋友」tab 是**灰度功能**：有的账号/设备有（首页/朋友/消息/我 = 4 个），
+有的没有（首页/消息/我 = 3 个）。同一个序号 `[4]`：
+
+- 4 个 tab 的设备 → 点到「我」（碰巧对）
+- 3 个 tab 的设备 → 点空（或点到别的东西）
+
+**同一个选择器在不同机器上语义不同**，这是"时好时坏"的根源。
+
+---
+
+## 三、解法：用**语义选择器**，不要依赖序号
+
+实测有效（同一台 3-tab 设备）：
+
+```python
+# ✗ 序号型：依赖"底部有几个 tab"
+(//*[@resource-id="com.ss.android.ugc.aweme:id/0qf"])[4]
+
+# ✓ 语义型：同一个 id，用文字限定 —— 不管有几个 tab 都对
+//*[@resource-id="com.ss.android.ugc.aweme:id/0qf" and @text="我"]
+```
+
+验证：命中（bounds 落在「我」上）→ 点击 → 进入我页面 → `jy-`（切换按钮）出现 ✓
+
+同类可用限定条件（按优先级）：
+
+1. `@text="…"` —— 文字最稳（tab 名、按钮名）
+2. `@content-desc="…"` —— 无文字但有描述（如 `首页，按钮`）
+3. `@resource-id="…"` —— **唯一**时直接用
+4. 组合：`//*[@resource-id="x" and @text="y"]` —— **同一 id 多实例时的最佳解**
+5. 结构路径（`…/FrameLayout[2]`）—— 最后手段，最脆
+6. `(…)[k]` —— **只在上面都不行时**
+
+---
+
+## 四、建议的改动（待排期）
+
+1. **抓取器（`core/uiauto_helper.py`）**：同一 id 出现多个实例时，**优先产出
+   `//*[@resource-id="x" and @text="…"]`** 而不是 `(…)[k]`；抓取列表里把
+   `text`/`content-desc` 放在最显眼位置，让用户能看着选。
+2. **抓取弹窗**：对**带序号**的选择器加醒目提示（"这个选择器依赖界面元素个数，
+   界面一变就失效"）。
+3. **已存任务**：把 `(…)[k]` 型选择器扫一遍，能改成文字限定的自动改（脚本），
+   其余在编辑器里逐个复核。
+4. **运行期**：`click` 未命中时，日志里顺带 dump 一下"同 id 现在有几个实例"，
+   让"序号错位"当场可诊断（现在是干巴巴一句"未找到元素"）。

From ee559786e77d4d1f18b057c643e223100d28173b Mon Sep 17 00:00:00 2001
From: butubb <1422726308@qq.com>
Date: Sun, 13 Sep 2026 21:01:53 +0800
Subject: [PATCH 2/9] =?UTF-8?q?docs(research):=20=E8=A1=A5=E3=80=8C?=
 =?UTF-8?q?=E6=8A=93=E5=8F=96=E5=BC=B9=E7=AA=97=E8=80=81=E6=98=AF=E9=94=99?=
 =?UTF-8?q?=E4=BD=8D=E3=80=8D=E7=9A=84=E7=9C=9F=E5=9B=A0=E2=80=94=E2=80=94?=
 =?UTF-8?q?=E6=88=AA=E5=9B=BE=E4=B8=8E=E5=85=83=E7=B4=A0=E6=A0=91=E4=B8=8D?=
 =?UTF-8?q?=E6=98=AF=E5=90=8C=E4=B8=80=E6=97=B6=E5=88=BB=EF=BC=88=E9=99=84?=
 =?UTF-8?q?=E5=AE=9E=E6=B5=8B=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

用户澄清"是抓取的窗口老是会错位"。把几种常见猜测逐一实测排除：
两条通道元素树不一致（✗ 逐项相同）、CSS 缩放没跟着算（✗ 缩放比正确、
框位置与理论值一致）、窗口 resize（✗ 预览列固定 320px）、列表索引错位
（✗ indexOf 保住原始序号）。

真因是取数时序：
  /api/uiauto/screenshot 0.4s + /api/uiauto/elements 1.8s（两次请求）= 间隔约 1.8s；
  换成原生 u2 背靠背也仍有约 1.4s（dump 本身就要 1.3~1.8s，设备端开销改不动）。
界面只要在动（信息流/视频/动画），这两秒就足以让元素位置全变 → 框永远落在旧位置。
因为是**每次都发生**，所以表现为"老是错位"而不是偶发。

解法（写进文档待排期）：①新增 /api/uiauto/snapshot 一个请求取齐（也正是
"用原始 u2"的做法，间隔降到 ~1.4s）；②抓取前后各截一张做校验，不一致就
明确提示"界面在变化中，请停在静止界面再抓"，而不是悄悄给一个错位的框。
---
 doc/research/U2_ELEMENT_SELECTORS.md | 40 ++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/doc/research/U2_ELEMENT_SELECTORS.md b/doc/research/U2_ELEMENT_SELECTORS.md
index 3cbf648..6125bab 100644
--- a/doc/research/U2_ELEMENT_SELECTORS.md
+++ b/doc/research/U2_ELEMENT_SELECTORS.md
@@ -85,6 +85,44 @@
 
 ---
 
+## 三·补：抓取弹窗"老是错位"的根因 —— **截图和元素树不是同一时刻**
+
+（2026-09-13 追加，用户反馈"抓取的窗口老是会错位"）
+
+先把几个常见猜测逐一排除（都实测过）：
+
+| 猜测 | 实测结果 |
+|------|---------|
+| 两条通道元素树不一致 | ✗ 排除：节点数/各 id 个数逐项相同 |
+| 截图被 CSS 缩放了、框没跟着缩 | ✗ 排除：`scaleX=clientWidth/naturalWidth` 算得对，实测框位置与理论值一致 |
+| 窗口 resize 后没重算 | ✗ 排除：预览列固定 320px，resize 不影响 |
+| 列表索引与框的 `data-idx` 对不上 | ✗ 排除：用 `indexOf` 保住原始序号，过滤后也不乱 |
+
+**真因：截图与元素树分两次取，中间隔了 1~2 秒。**
+
+| 取数方式 | 截图 | 元素树 | 两者时间差 |
+|---|---|---|---|
+| 现在（`/api/uiauto/screenshot` + `/api/uiauto/elements` 两次请求，走 uiautodev）| 0.4s | 1.8s | **约 1.8 秒** |
+| 原生 u2 背靠背（同一个连接）| 0.3s | 1.4s | **约 1.4 秒** |
+
+元素树的 dump 本身就要 1.3~1.8 秒（设备端 uiautomator 的开销，改不动）。
+界面**只要在动**（抖音信息流、视频、加载动画…），两秒足够让元素位置全变 →
+**框永远落在旧位置上** —— 这就是"老是错位"，不是偶发。
+
+### 解法
+
+1. **一次请求取齐**（推荐，也是用户说的"用原始 u2"）：
+   新增 `GET /api/uiauto/snapshot?serial=X`，服务端用**一个 u2 连接**背靠背
+   `dump_hierarchy()` + `screenshot()`，返回 `{image, elements}`；
+   前端只调这一个接口 → 天然同源，间隔从 ~2.2s 降到 ~1.4s。
+2. **双截图校验**（关键：让失败可见而不是悄悄错位）：
+   抓取时前后各截一张，两张**不一致就明确提示**"界面在抓取过程中变化了，
+   请让设备停在目标界面再抓"，而不是给一个已经错位的框。
+3. 文档里明确写：**抓元素要让设备停在静止界面**（设置页、已加载完的页面），
+   别在视频播放/信息流滑动中抓。
+
+---
+
 ## 四、建议的改动（待排期）
 
 1. **抓取器（`core/uiauto_helper.py`）**：同一 id 出现多个实例时，**优先产出
@@ -96,3 +134,5 @@
    其余在编辑器里逐个复核。
 4. **运行期**：`click` 未命中时，日志里顺带 dump 一下"同 id 现在有几个实例"，
    让"序号错位"当场可诊断（现在是干巴巴一句"未找到元素"）。
+5. **（针对第三节的"抓取错位"）** 抓取接口合并成一个快照接口 + 双截图校验，
+   具体见第三节「解法」。

From accd06df4b6662d0ac9d4e8a26bab296bf6c1dcc Mon Sep 17 00:00:00 2001
From: butubb <1422726308@qq.com>
Date: Sun, 13 Sep 2026 21:02:01 +0800
Subject: [PATCH 3/9] =?UTF-8?q?docs(research):=20=E7=AB=A0=E8=8A=82?=
 =?UTF-8?q?=E7=BC=96=E5=8F=B7=E7=90=86=E9=A1=BA=EF=BC=88=E4=B8=89=C2=B7?=
 =?UTF-8?q?=E8=A1=A5=20=E2=86=92=20=E5=9B=9B=EF=BC=8C=E5=BB=BA=E8=AE=AE?=
 =?UTF-8?q?=E6=94=B9=E5=8A=A8=20=E2=86=92=20=E4=BA=94=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 doc/research/U2_ELEMENT_SELECTORS.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/research/U2_ELEMENT_SELECTORS.md b/doc/research/U2_ELEMENT_SELECTORS.md
index 6125bab..df2f5bf 100644
--- a/doc/research/U2_ELEMENT_SELECTORS.md
+++ b/doc/research/U2_ELEMENT_SELECTORS.md
@@ -85,7 +85,7 @@
 
 ---
 
-## 三·补：抓取弹窗"老是错位"的根因 —— **截图和元素树不是同一时刻**
+## 四、抓取弹窗"老是错位"的根因 —— **截图和元素树不是同一时刻**
 
 （2026-09-13 追加，用户反馈"抓取的窗口老是会错位"）
 
@@ -123,7 +123,7 @@
 
 ---
 
-## 四、建议的改动（待排期）
+## 五、建议的改动（待排期）
 
 1. **抓取器（`core/uiauto_helper.py`）**：同一 id 出现多个实例时，**优先产出
    `//*[@resource-id="x" and @text="…"]`** 而不是 `(…)[k]`；抓取列表里把
@@ -134,5 +134,5 @@
    其余在编辑器里逐个复核。
 4. **运行期**：`click` 未命中时，日志里顺带 dump 一下"同 id 现在有几个实例"，
    让"序号错位"当场可诊断（现在是干巴巴一句"未找到元素"）。
-5. **（针对第三节的"抓取错位"）** 抓取接口合并成一个快照接口 + 双截图校验，
-   具体见第三节「解法」。
+5. **（针对第四节的"抓取错位"）** 抓取接口合并成一个快照接口 + 双截图校验，
+   具体见第四节「解法」。

From 37a2b1c59b60cf238b045c661a999c30690cf960 Mon Sep 17 00:00:00 2001
From: butubb <1422726308@qq.com>
Date: Sun, 13 Sep 2026 21:17:12 +0800
Subject: [PATCH 4/9] =?UTF-8?q?feat(=E6=8A=93=E5=8F=96):=20=E5=85=83?=
 =?UTF-8?q?=E7=B4=A0=E6=A3=80=E6=9F=A5=E5=99=A8=E6=94=B9=E6=88=90=E6=9C=AC?=
 =?UTF-8?q?=E5=9C=B0=E7=89=88"=E5=A4=A7=E5=9B=BE=20+=20=E4=B8=80=E6=AC=A1?=
 =?UTF-8?q?=E5=8F=96=E9=BD=90"=E2=80=94=E2=80=94=E5=A4=8D=E5=88=BB?=
 =?UTF-8?q?=E4=BA=91=E6=A3=80=E6=9F=A5=E5=99=A8=E7=9A=84=E4=BD=93=E9=AA=8C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

用户要的是 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。
---
 core/uiauto_helper.py                |  85 ++++++++++++++++++
 doc/API.md                           |   1 +
 doc/research/U2_ELEMENT_SELECTORS.md |   4 +-
 static/admin/editor.js               | 124 +++++++++++++++------------
 templates/admin/monitor.html         |  10 ++-
 web/tasks_api.py                     |  24 ++++++
 6 files changed, 190 insertions(+), 58 deletions(-)

diff --git a/core/uiauto_helper.py b/core/uiauto_helper.py
index db6f448..b2efd8a 100644
--- a/core/uiauto_helper.py
+++ b/core/uiauto_helper.py
@@ -258,3 +258,88 @@ def _extract(root, out):
 
     count_attrs(root)
     flatten(root)
+
+
+# ================== 原生 u2 快照（截图 + 元素树一次取齐） ==================
+def _xml_to_node(elem):
+    """把 uiautomator2 的 XML 节点转成 uiautodev 那套 {name, properties, children}。
+
+    两边的属性名本来就一样（resource-id / text / content-desc / class / bounds 字符串），
+    所以只要套一层壳，就能原样复用上面的 _extract（选择器建议逻辑不用写第二遍）。
+    """
+    props = dict(elem.attrib)
+    return {"name": props.get("class", ""), "properties": props,
+            "children": [_xml_to_node(c) for c in list(elem)]}
+
+
+def _shots_differ(a, b, threshold=8):
+    """两张截图是不是"明显不一样"（用来判断抓取期间界面有没有在动）。
+
+    逐像素求差的包围盒 → 用"变化区域占比"判断，避免个别像素抖动误报。
+    """
+    try:
+        from PIL import ImageChops
+        if a.size != b.size:
+            return True
+        diff = ImageChops.difference(a.convert("RGB"), b.convert("RGB"))
+        bbox = diff.getbbox()
+        if not bbox:
+            return False
+        area = (bbox[2] - bbox[0]) * (bbox[3] - bbox[1])
+        total = a.size[0] * a.size[1]
+        # 变化面积超过阈值（默认 8%）才算"界面在动"
+        return (area / total) * 100.0 > threshold
+    except Exception:
+        return False
+
+
+def snapshot(serial, quality=85):
+    """一次取齐：设备截图 + 元素树（**同一个 u2 连接、背靠背取**）。
+
+    为什么不用现在的"两个接口"：截图和元素树分两次取时，中间隔着 dump 本身的
+    1.3~1.8 秒；界面只要在动画（信息流/视频/加载），框就会落在旧位置上。
+
+    顺带做**双截图校验**：dump 前后各截一张，两张差得多就标 `unstable`，
+    让前端明确提示"界面在变化中，请停在静止界面再抓"——而不是悄悄给一个错位的框。
+
+    返回 (ok, 数据 | 错误信息)。数据形如：
+      {"image": "data:image/jpeg;base64,…", "width": 720, "height": 1650,
+       "elements": [...], "unstable": false, "cost_ms": 1800}
+    """
+    import base64
+    import io
+    import time as _t
+    import xml.etree.ElementTree as ET
+
+    import uiautomator2 as u2
+
+    t0 = _t.time()
+    try:
+        d = u2.connect(serial)
+        img1 = d.screenshot()                  # 先截：用户看到的就是这一刻
+        xml = d.dump_hierarchy()               # 慢的一步（1.3~1.8s）
+        img2 = d.screenshot()                  # 再截：和第一张比对
+    except Exception as e:
+        return False, f"抓取失败: {e}"
+
+    unstable = _shots_differ(img1, img2)
+    if not unstable:
+        img2.close()
+    try:
+        buf = io.BytesIO()
+        img1.convert("RGB").save(buf, format="JPEG", quality=quality)
+        image = "data:image/jpeg;base64," + base64.b64encode(buf.getvalue()).decode()
+        w, h = img1.size
+    except Exception as e:
+        return False, f"截图编码失败: {e}"
+
+    elements = []
+    try:
+        root = ET.fromstring(xml)
+        _extract(_xml_to_node(root), elements)
+    except Exception as e:
+        return False, f"元素树解析失败: {e}"
+
+    return True, {"image": image, "width": w, "height": h,
+                  "elements": elements, "unstable": unstable,
+                  "cost_ms": int((_t.time() - t0) * 1000)}
diff --git a/doc/API.md b/doc/API.md
index 8c86f17..7a9a26a 100644
--- a/doc/API.md
+++ b/doc/API.md
@@ -127,6 +127,7 @@
 | 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 | 真机试执行单个步骤 |
 
diff --git a/doc/research/U2_ELEMENT_SELECTORS.md b/doc/research/U2_ELEMENT_SELECTORS.md
index df2f5bf..9c703fb 100644
--- a/doc/research/U2_ELEMENT_SELECTORS.md
+++ b/doc/research/U2_ELEMENT_SELECTORS.md
@@ -109,12 +109,14 @@
 界面**只要在动**（抖音信息流、视频、加载动画…），两秒足够让元素位置全变 →
 **框永远落在旧位置上** —— 这就是"老是错位"，不是偶发。
 
-### 解法
+### 解法（✅ 2026-09-13 已实现，见 `core/uiauto_helper.snapshot`）
 
 1. **一次请求取齐**（推荐，也是用户说的"用原始 u2"）：
    新增 `GET /api/uiauto/snapshot?serial=X`，服务端用**一个 u2 连接**背靠背
    `dump_hierarchy()` + `screenshot()`，返回 `{image, elements}`；
    前端只调这一个接口 → 天然同源，间隔从 ~2.2s 降到 ~1.4s。
+   **并且抓取弹窗改成大图 1:1 预览**（原来预览列只有 320px、图片被缩到 294px，
+   框全挤在一起，看着就像"错位"；现在铺满左侧、按原始分辨率显示）。
 2. **双截图校验**（关键：让失败可见而不是悄悄错位）：
    抓取时前后各截一张，两张**不一致就明确提示**"界面在抓取过程中变化了，
    请让设备停在目标界面再抓"，而不是给一个已经错位的框。
diff --git a/static/admin/editor.js b/static/admin/editor.js
index 7896f39..4929e1b 100644
--- a/static/admin/editor.js
+++ b/static/admin/editor.js
@@ -831,7 +831,7 @@ var _stepEditor={
       '<div class="el-picker-main">'+
         '<div class="el-shot-wrap">'+
           '<div class="el-shot-toolbar">'+
-            '<button class="btn" onclick="_stepEditor._refreshShot()" title="重新拉取截图和元素树（界面变化后刷新用）">刷新截图+元素</button>'+
+            '<button class="btn" onclick="_stepEditor._refreshShot()" title="重新抓取截图与元素树（一次取齐）">重新抓取</button>'+
             '<span class="el-shot-info" id="el-shot-info">加载中...</span>'+
           '</div>'+
           '<div class="el-shot-container" id="el-shot-container">'+
@@ -849,65 +849,58 @@ var _stepEditor={
       '<span class="text-muted" style="margin-left:10px;font-size:11.5px">'
       +'提示：先「▶ 点一下」在设备上验证位置，再点元素回填选择器；'
       +'「✓ 测选择器」会用将填入的选择器真跑一次点击</span>';
-    // 加载截图和元素树（_refreshShot 内部同时刷新两者）
-    self._refreshShot();
+    // 一次取齐截图 + 元素树（见 _loadSnapshot 的说明）
+    self._loadSnapshot();
   },
-  // 拉取元素树（进入页面和刷新时共用；带时间戳防缓存）
-  _loadElData:function(){
-    var serial=this._elSerial;
-    if(!serial)return;
-    var listEl=document.getElementById('el-list');
-    if(listEl)listEl.innerHTML='<div class="se-empty">加载元素树...</div>';
-    var self=this;
-    fetch('/api/uiauto/elements?serial='+encodeURIComponent(serial)+'&_='+Date.now())
-      .then(function(r){return r.json();})
-      .then(function(data){
-        var le=document.getElementById('el-list');
-        if(!le)return;
-        if(!data.ok){
-          le.innerHTML='<div class="se-empty">'+esc(data.error||'抓取失败')+'</div>';
-          return;
-        }
-        self._elData=data.elements||[];
-        self._renderEl(self._elData);
-        // 刷新后保持搜索过滤状态
-        var search=document.getElementById('el-search');
-        if(search&&search.value)self._filterEl(search.value);
-        self._renderOverlays();
-      })
-      .catch(function(e){
-        var le=document.getElementById('el-list');
-        if(le)le.innerHTML='<div class="se-empty">请求失败: '+esc(e)+'</div>';
-      });
-  },
-  // 刷新截图
-  _refreshShot:function(){
+  // 一次取齐：截图 + 元素树（后端用原生 u2 背靠背取）
+  // 为什么不再分两个接口：截图与元素树分两次拿，中间隔着 dump 本身的 1.3~1.8 秒，
+  // 界面只要在动（信息流/视频/加载），框就会落在旧位置上（"抓取错位"）。
+  _loadSnapshot:function(){
     var serial=this._elSerial;
     if(!serial)return;
     var container=document.getElementById('el-shot-container');
-    if(!container)return;
-    container.innerHTML='<div class="el-shot-loading">正在获取截图...</div>';
     var info=document.getElementById('el-shot-info');
-    if(info)info.textContent='加载中...';
+    var old=document.querySelector('.el-shot-warn');
+    if(old)old.remove();
+    if(container)container.innerHTML='<div class="el-shot-loading">正在抓取（截图 + 元素树一次取齐）…</div>';
+    if(info)info.textContent='抓取中…';
     var self=this;
-    var img=new Image();
-    img.onload=function(){
-      container.innerHTML='';
-      container.appendChild(img);
-      var infoEl=document.getElementById('el-shot-info');
-      if(infoEl)infoEl.textContent=img.naturalWidth+'x'+img.naturalHeight;
-      // 截图加载完后重新渲染元素边界框
-      self._renderOverlays();
-    };
-    img.onerror=function(){
-      container.innerHTML='<div class="el-shot-loading">截图加载失败</div>';
-      var infoEl=document.getElementById('el-shot-info');
-      if(infoEl)infoEl.textContent='失败';
-    };
-    img.src='/api/uiauto/screenshot?serial='+encodeURIComponent(serial)+'&_='+Date.now();
-    // 同时重新拉取元素树——只刷截图会导致"截图是新的、元素框是旧的"错位
-    this._loadElData();
+    fetch('/api/uiauto/snapshot?serial='+encodeURIComponent(serial)+'&_='+Date.now())
+      .then(function(r){return r.json();})
+      .then(function(d){
+        if(!d.ok){
+          if(container)container.innerHTML='<div class="el-shot-loading">'+esc(d.error||'抓取失败')+'</div>';
+          if(info)info.textContent='失败';
+          return;
+        }
+        self._elData=d.elements||[];
+        if(d.unstable){
+          var w=document.createElement('div');
+          w.className='el-shot-warn';
+          w.innerHTML='⚠ 抓取期间界面有变化，框可能对不上 —— 建议把设备停在<b>静止界面</b>后点「重新抓取」';
+          container.parentNode.insertBefore(w, container);
+        }
+        var img=new Image();
+        img.onload=function(){
+          container.innerHTML='';
+          container.appendChild(img);
+          if(info){
+            info.textContent=d.width+'x'+d.height+' · '+self._elData.length+' 个元素 · '
+              +(d.cost_ms||0)+'ms'+(d.unstable?' · ⚠ 界面在变化':'');
+          }
+          self._renderOverlays();
+        };
+        img.src=d.image;
+        self._renderEl(self._elData);
+        var search=document.getElementById('el-search');
+        if(search&&search.value)self._filterEl(search.value);
+      })
+      .catch(function(e){
+        if(container)container.innerHTML='<div class="el-shot-loading">请求失败: '+esc(e)+'</div>';
+      });
   },
+  // 兼容旧调用名（工具栏「重新抓取」按钮）
+  _refreshShot:function(){ this._loadSnapshot(); },
   // 在截图上渲染元素边界框（可点击）
   _renderOverlays:function(){
     var container=document.getElementById('el-shot-container');
@@ -947,6 +940,31 @@ var _stepEditor={
       });
       // 点击截图：按 bounds 命中测试，选中最小的（最深的）元素，
       // 而不是被 DOM 层叠中的大容器/大兄弟挡住
+      container.onmousemove=function(e){
+        var im=container.querySelector('img');
+        if(!im||!self._elData)return;
+        var r=im.getBoundingClientRect();
+        var px=(e.clientX-r.left)/scaleX, py=(e.clientY-r.top)/scaleY;
+        var best=-1,bestArea=Infinity;
+        self._elData.forEach(function(el,i){
+          var mb=el.bounds&&el.bounds.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+          if(!mb)return;
+          var a=+mb[1],b=+mb[2],c=+mb[3],dd=+mb[4];
+          if(px>=a&&px<=c&&py>=b&&py<=dd){var ar=(c-a)*(dd-b); if(ar<bestArea){bestArea=ar;best=i;}}
+        });
+        var hov=container.querySelector('.el-shot-hover');
+        if(best<0){ if(hov)hov.remove(); return; }
+        var b2=self._elData[best].bounds.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+        if(!hov){hov=document.createElement('div');hov.className='el-shot-hover';container.appendChild(hov);}
+        hov.style.left=(imgOffsetX+(+b2[1])*scaleX)+'px';
+        hov.style.top=(imgOffsetY+(+b2[2])*scaleY)+'px';
+        hov.style.width=((+b2[3])-(+b2[1]))*scaleX+'px';
+        hov.style.height=((+b2[4])-(+b2[2]))*scaleY+'px';
+      };
+      container.onmouseleave=function(){
+        var hov=container.querySelector('.el-shot-hover');
+        if(hov)hov.remove();
+      };
       container.onclick=function(e){
         var im=container.querySelector('img');
         if(!im)return;
diff --git a/templates/admin/monitor.html b/templates/admin/monitor.html
index a385849..ee7f4a7 100644
--- a/templates/admin/monitor.html
+++ b/templates/admin/monitor.html
@@ -289,7 +289,7 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 .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}
-.el-shot-wrap{flex:0 0 320px;border-right:1px solid var(--border);background:var(--ink);display:flex;flex-direction:column}
+.el-shot-wrap{flex:1 1 auto;min-width:0;border-right:1px solid var(--border);background:var(--ink);display:flex;flex-direction:column}
 .el-shot-toolbar{padding:6px 10px;background:var(--ink-2);display:flex;gap:6px;align-items:center;border-bottom:1px solid var(--ink-line)}
 .el-shot-toolbar .btn{padding:3px 10px;font-size:12px;background:#39414d;color:#e5e7eb;border:none;box-shadow:none}
 .el-shot-toolbar .btn:hover{background:#4b5563}
@@ -297,10 +297,12 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 .el-shot-container{flex:1;overflow:auto;display:flex;align-items:flex-start;justify-content:center;padding:8px;position:relative}
 .el-shot-container img{max-width:100%;height:auto;border-radius:4px;display:block}
 .el-shot-container .el-shot-loading{color:#8a93a0;font-size:13px;padding:40px}
-.el-shot-overlay{position:absolute;border:1px solid rgba(103,232,249,.35);background:transparent;cursor:pointer;border-radius:2px;transition:all .1s}
+.el-shot-overlay{position:absolute;border:1px solid rgba(103,232,249,.45);background:transparent;cursor:pointer;border-radius:2px;transition:all .1s}
+.el-shot-hover{position:absolute;border:2px solid rgba(248,113,113,.9);background:rgba(248,113,113,.15);pointer-events:none;border-radius:2px;z-index:5}
+.el-shot-warn{background:#fff3cd;border-bottom:1px solid #ffda6a;color:#7a5b00;font-size:12px;padding:6px 10px}
 .el-shot-overlay:hover{border-color:#67e8f9;background:rgba(103,232,249,.18)}
 .el-shot-overlay.active{border:2px solid #f87171;background:rgba(248,113,113,.22)}
-.el-list-wrap{flex:1;display:flex;flex-direction:column;overflow:hidden}
+.el-list-wrap{flex:0 0 400px;display:flex;flex-direction:column;overflow:hidden;border-left:1px solid var(--border)}
 .el-picker-search{width:100%;padding:8px 12px;border:none;border-bottom:1px solid var(--border);font-size:13px;outline:none;font-family:var(--body)}
 .el-picker-list{flex:1;overflow-y:auto}
 .el-picker-item{padding:8px 12px;border-bottom:1px solid var(--border);cursor:pointer;font-size:12px;display:flex;gap:8px;align-items:flex-start}
@@ -1042,7 +1044,7 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 
 <!-- ========== 元素抓取模态框（独立第二层，不覆盖任务编辑窗口）========== -->
 <div id="el-picker-overlay" class="modal-overlay" style="z-index:1100" onclick="if(event.target===this)closeElPicker()">
-  <div class="modal" id="el-picker-box" style="max-width:900px">
+  <div class="modal" id="el-picker-box" style="max-width:1280px;width:96vw">
     <div class="modal-header">
       <h3 id="el-picker-title">抓取元素</h3>
       <button class="close" onclick="closeElPicker()">&times;</button>
diff --git a/web/tasks_api.py b/web/tasks_api.py
index f683149..e9e1fd8 100644
--- a/web/tasks_api.py
+++ b/web/tasks_api.py
@@ -358,6 +358,30 @@ def api_uiauto_devices():
         _log.info(f"抓取元素设备列表补全 {added} 台在线设备: {list(seen)}")
     return jsonify({"ok": True, "devices": data})
 
+@bp.route("/api/uiauto/snapshot")
+@perm_required(PERM_DEVICES)
+def api_uiauto_snapshot():
+    """一次取齐：设备截图 + 元素树（**原生 u2，同一个连接背靠背取**）。
+
+    抓取元素时用它代替「/api/uiauto/screenshot + /api/uiauto/elements」两连击：
+    那两条是两次独立取数，中间隔着 dump 本身的 1.3~1.8 秒 —— 界面只要在动
+    （信息流/视频/加载动画），框就会落在旧位置上（"抓取错位"）。
+    同一个连接背靠背取把这个窗口压到最小，并额外用**双截图校验**标出
+    "抓取期间界面在变化"（`unstable`），前端据此明确提示而不是悄悄给错位的框。
+
+    ?serial=xxx
+    → {ok, image(data-url), width, height, elements:[...], unstable, cost_ms}
+    """
+    serial = request.args.get("serial", "")
+    if not serial:
+        return jsonify({"ok": False, "error": "缺少 serial"}), 400
+    ok, data = uiauto_helper.snapshot(serial)
+    if not ok:
+        # 设备没连上/抓取失败：502（依赖不可用），与 /api/uiauto/elements 一致
+        return jsonify({"ok": False, "error": data}), 502
+    return jsonify({"ok": True, **data})
+
+
 @bp.route("/api/uiauto/screenshot")
 @perm_required(PERM_DEVICES)
 def api_uiauto_screenshot():

From 4ea777a55a609c7879fee5edcfa4be44db1875d4 Mon Sep 17 00:00:00 2001
From: butubb <1422726308@qq.com>
Date: Sun, 13 Sep 2026 21:30:41 +0800
Subject: [PATCH 5/9] =?UTF-8?q?fix(=E6=8A=93=E5=8F=96):=20=E5=85=83?=
 =?UTF-8?q?=E7=B4=A0=E6=A1=86=E8=B7=9F=E7=9D=80=E5=9B=BE=E7=89=87=E8=B5=B0?=
 =?UTF-8?q?=EF=BC=88ResizeObserver=EF=BC=89+=20=E7=95=8C=E9=9D=A2=E6=94=BE?=
 =?UTF-8?q?=E5=A4=A7=20+=20=E5=8F=B3=E4=BE=A7=E5=B1=82=E7=BA=A7/=E5=B1=9E?=
 =?UTF-8?q?=E6=80=A7/=E9=A2=9C=E8=89=B2=E4=B8=89=E9=A1=B5=E7=AD=BE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

用户报的准确现象：**点某些元素会让画面变大，但框没跟着变大 → 错位**。

根因：预览图是 `max-width:100%` —— 窗口够宽时恒为原始尺寸（我这儿复现不出），
但窗口窄时图片被压小；此时任何**布局微动**都会改变预览列宽度 → 图片重新缩放，
而框是上一次算好的**像素坐标**，不会跟着变。触发布局微动的正是"点元素"：
`.el-picker-item.active` 用 `border-left:3px`（占宽度）→ 列表变宽 → 预览变窄 →
图片变小 ✗。实测（视口压到 900）：图片从 720 → 363，框仍停在 720 的位置。

修法：
1. **ResizeObserver 盯着图片**：显示尺寸一变就重算所有框 —— 窗口缩放、面板宽度
   变化、滚动条出现…都会自动跟上，这是"完全不错位"的兜底保证。
2. 高亮一律改用 **outline / box-shadow**（不占布局）→ 选中元素不再引发任何重排。
3. 弹窗放大到 **98vw × 88vh**（用户要"整个界面大一点"），图片在宽窗口下 1:1。
4. 右侧改成和 uiauto.dev 一样的**三页签**：
   - **层级**：元素树（原列表，缩进 + 搜索）
   - **属性**：选中元素的全部属性（建议选择器/class/resource-id/text/desc/package/
     clickable/bounds/深度）
   - **颜色**：鼠标在图上移动实时取**像素色**；选中元素显示**元素中心色**
5. 交互对齐云检查器：**点层级条目 = 选中**（看属性/颜色/高亮，不关窗），
   回填改由每行的「✓ 填入」按钮触发。

实测（视口 900 窄窗口）：图片 720→363、框同步变 363 ✓；点元素不再错位 ✓；
三页签可用、属性/取色正确（选中元素中心 #f7f7f7）✓；无 JS 报错 ✓。
---
 static/admin/editor.js       | 103 ++++++++++++++++++++++++++++++++++-
 templates/admin/monitor.html |  22 ++++++--
 2 files changed, 116 insertions(+), 9 deletions(-)

diff --git a/static/admin/editor.js b/static/admin/editor.js
index 4929e1b..4e2b058 100644
--- a/static/admin/editor.js
+++ b/static/admin/editor.js
@@ -839,8 +839,20 @@ var _stepEditor={
           '</div>'+
         '</div>'+
         '<div class="el-list-wrap">'+
-          '<input type="text" class="el-picker-search" id="el-search" placeholder="搜索 resource-id/text/description..." oninput="_stepEditor._filterEl(this.value)">'+
-          '<div class="el-picker-list" id="el-list"><div class="se-empty">加载元素树...</div></div>'+
+          '<div class="el-tabs">'+
+            '<button class="el-tab active" data-pane="tree" onclick="_stepEditor._tab(this)">层级</button>'+
+            '<button class="el-tab" data-pane="attr" onclick="_stepEditor._tab(this)">属性</button>'+
+            '<button class="el-tab" data-pane="color" onclick="_stepEditor._tab(this)">颜色</button>'+
+          '</div>'+
+          '<div class="el-pane active" id="el-pane-tree">'+
+            '<input type="text" class="el-picker-search" id="el-search" placeholder="搜索 resource-id/text/description..." oninput="_stepEditor._filterEl(this.value)">'+
+            '<div class="el-picker-list" id="el-list" style="max-height:calc(100% - 42px)"><div class="se-empty">加载元素树...</div></div>'+
+          '</div>'+
+          '<div class="el-pane" id="el-pane-attr"><div class="se-empty">点左侧图上的元素，或点「层级」里的条目看属性</div></div>'+
+          '<div class="el-pane" id="el-pane-color">'+
+            '<div style="padding:8px 12px;font-size:11.5px;color:var(--text-light)">把鼠标移到左侧图上取色；点元素可看该元素的主色</div>'+
+            '<div id="el-color-list"></div>'+
+          '</div>'+
         '</div>'+
       '</div>';
     document.getElementById('el-picker-footer').innerHTML=
@@ -852,6 +864,71 @@ var _stepEditor={
     // 一次取齐截图 + 元素树（见 _loadSnapshot 的说明）
     self._loadSnapshot();
   },
+  // 右侧页签切换
+  _tab:function(btn){
+    var pane=btn.dataset.pane;
+    document.querySelectorAll('#el-picker-body .el-tab').forEach(function(b){
+      b.classList.toggle('active', b===btn);
+    });
+    ['tree','attr','color'].forEach(function(p){
+      var el=document.getElementById('el-pane-'+p);
+      if(el)el.classList.toggle('active', p===pane);
+    });
+  },
+  // 属性页：选中元素的全部属性
+  _renderAttrs:function(i){
+    var el=(this._elData||[])[i];
+    var box=document.getElementById('el-pane-attr');
+    if(!box)return;
+    if(!el){box.innerHTML='<div class="se-empty">点左侧图上的元素，或点「层级」里的条目看属性</div>';return;}
+    var sg=el.suggested||{};
+    var rows=[['建议选择器', sg.value||'(无可靠选择器)'],
+              ['class', el.class||''], ['resource-id', el.resource_id||''],
+              ['text', el.text||''], ['content-desc', el.description||''],
+              ['package', el.package||''], ['clickable', el.clickable||''],
+              ['bounds', el.bounds||''], ['层级深度', String(el.depth||0)]];
+    box.innerHTML=rows.map(function(r){
+      return '<div class="el-attr"><b>'+esc(r[0])+'</b><span>'+esc(r[1]||'-')+'</span></div>';
+    }).join('');
+  },
+  // 颜色页：鼠标位置的像素色 + 选中元素的主色
+  _pixelAt:function(x,y){
+    try{
+      var c=this._colorCanvas, img=document.getElementById('el-shot-container').querySelector('img');
+      if(!c||!img)return null;
+      if(c.width!==img.naturalWidth){c.width=img.naturalWidth;c.height=img.naturalHeight;}
+      var ctx=c.getContext('2d');
+      ctx.drawImage(img,0,0);
+      var d=ctx.getImageData(Math.max(0,Math.min(c.width-1,x)),Math.max(0,Math.min(c.height-1,y)),1,1).data;
+      return '#'+[d[0],d[1],d[2]].map(function(v){return ('0'+v.toString(16)).slice(-2);}).join('');
+    }catch(e){return null;}
+  },
+  _updatePixel:function(x,y){
+    var box=document.getElementById('el-color-list');
+    if(!box)return;
+    var col=this._pixelAt(Math.round(x),Math.round(y));
+    if(!col)return;
+    box.innerHTML='<div class="el-color-row"><span class="el-swatch" style="background:'+col+'"></span>'+
+      '<span>光标处 '+esc(col)+'</span></div>'+
+      (box.dataset.dom||'');
+  },
+  _renderColors:function(i){
+    var box=document.getElementById('el-color-list');
+    if(!box)return;
+    var el=(this._elData||[])[i];
+    var dom='';
+    if(el&&el.bounds){
+      var m=el.bounds.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+      if(m){
+        var x=Math.round((+m[1]+ +m[3])/2), y=Math.round((+m[2]+ +m[4])/2);
+        var c=this._pixelAt(x,y);
+        if(c) dom='<div class="el-color-row"><span class="el-swatch" style="background:'+c+'"></span>'+
+          '<span>选中元素中心 '+esc(c)+'</span></div>';
+      }
+    }
+    box.dataset.dom=dom;
+    box.innerHTML=dom||'<div class="se-empty" style="padding:12px">把鼠标移到左侧图上取色</div>';
+  },
   // 一次取齐：截图 + 元素树（后端用原生 u2 背靠背取）
   // 为什么不再分两个接口：截图与元素树分两次拿，中间隔着 dump 本身的 1.3~1.8 秒，
   // 界面只要在动（信息流/视频/加载），框就会落在旧位置上（"抓取错位"）。
@@ -888,7 +965,17 @@ var _stepEditor={
             info.textContent=d.width+'x'+d.height+' · '+self._elData.length+' 个元素 · '
               +(d.cost_ms||0)+'ms'+(d.unstable?' · ⚠ 界面在变化':'');
           }
+          // 图片显示尺寸一变（窗口缩放、面板宽度变化、滚动条出现…）就重算所有框 ——
+          // 这是"完全不错位"的保证：框永远跟着图片走，不留旧坐标
+          if(window.ResizeObserver){
+            if(self._ro)self._ro.disconnect();
+            self._ro=new ResizeObserver(function(){ self._renderOverlays(); });
+            self._ro.observe(img);
+          }
+          self._colorCanvas=document.createElement('canvas');
           self._renderOverlays();
+          self._renderAttrs(null);
+          self._renderColors(null);
         };
         img.src=d.image;
         self._renderEl(self._elData);
@@ -952,6 +1039,7 @@ var _stepEditor={
           var a=+mb[1],b=+mb[2],c=+mb[3],dd=+mb[4];
           if(px>=a&&px<=c&&py>=b&&py<=dd){var ar=(c-a)*(dd-b); if(ar<bestArea){bestArea=ar;best=i;}}
         });
+        self._updatePixel(px, py);
         var hov=container.querySelector('.el-shot-hover');
         if(best<0){ if(hov)hov.remove(); return; }
         var b2=self._elData[best].bounds.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
@@ -989,6 +1077,8 @@ var _stepEditor={
   },
   // 高亮元素（截图框 + 列表项联动）
   _highlightEl:function(i){
+    this._renderAttrs(i);
+    this._renderColors(i);
     // 清除旧高亮（只在 el-picker-overlay 范围内查找）
     var picker=document.getElementById('el-picker-overlay');
     picker.querySelectorAll('.el-shot-overlay.active').forEach(function(o){o.classList.remove('active');});
@@ -1027,8 +1117,10 @@ var _stepEditor={
           ? '<button class="btn btn-xs" title="用将填入的选择器在设备上真跑一次 click，验证是否命中" '
             +'onclick="event.stopPropagation();_stepEditor._testSelector('+idx+')">✓ 测选择器</button>'
           : '')
+        +'<button class="btn btn-xs" title="把这条的选择器填入步骤" '
+        +'onclick="event.stopPropagation();_stepEditor._fillEl('+idx+')">✓ 填入</button>'
         +'</div>';
-      return '<div class="el-picker-item" data-idx="'+idx+'" title="点击填入: '+esc(sg.value||'')+'" onclick="_stepEditor._pickEl('+idx+')">'+
+      return '<div class="el-picker-item" data-idx="'+idx+'" title="'+esc(sg.value||'')+'" onclick="_stepEditor._pickEl('+idx+')">'+
         '<span class="ep-depth">'+(el.depth||0)+'</span>'+
         '<div class="ep-info"><div class="ep-name">'+indent+esc(el.name||el.class||'')+'</div>'+
         '<div class="ep-attrs">'+attrs.join('')+'</div></div>'+
@@ -1080,7 +1172,12 @@ var _stepEditor={
     });
     this._renderEl(f);
   },
+  // 点层级条目 = **选中**（看属性/颜色/高亮），不关窗不回填
   _pickEl:function(i){
+    this._highlightEl(i);
+  },
+  // 「✓ 填入」才回填选择器并关窗
+  _fillEl:function(i){
     var el=this._elData[i];
     if(!el||!this._elTargetInput)return;
     if(el.suggested&&el.suggested.invalid){
diff --git a/templates/admin/monitor.html b/templates/admin/monitor.html
index ee7f4a7..214a6a7 100644
--- a/templates/admin/monitor.html
+++ b/templates/admin/monitor.html
@@ -298,16 +298,26 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 .el-shot-container img{max-width:100%;height:auto;border-radius:4px;display:block}
 .el-shot-container .el-shot-loading{color:#8a93a0;font-size:13px;padding:40px}
 .el-shot-overlay{position:absolute;border:1px solid rgba(103,232,249,.45);background:transparent;cursor:pointer;border-radius:2px;transition:all .1s}
-.el-shot-hover{position:absolute;border:2px solid rgba(248,113,113,.9);background:rgba(248,113,113,.15);pointer-events:none;border-radius:2px;z-index:5}
+.el-shot-hover{position:absolute;outline:2px solid rgba(248,113,113,.9);outline-offset:-1px;background:rgba(248,113,113,.15);pointer-events:none;border-radius:2px;z-index:5}
 .el-shot-warn{background:#fff3cd;border-bottom:1px solid #ffda6a;color:#7a5b00;font-size:12px;padding:6px 10px}
 .el-shot-overlay:hover{border-color:#67e8f9;background:rgba(103,232,249,.18)}
-.el-shot-overlay.active{border:2px solid #f87171;background:rgba(248,113,113,.22)}
-.el-list-wrap{flex:0 0 400px;display:flex;flex-direction:column;overflow:hidden;border-left:1px solid var(--border)}
+.el-shot-overlay.active{outline:2px solid #f87171;outline-offset:-1px;background:rgba(248,113,113,.22)}
+.el-list-wrap{flex:0 0 460px;display:flex;flex-direction:column;overflow:hidden;border-left:1px solid var(--border)}
+.el-tabs{display:flex;border-bottom:1px solid var(--border);background:var(--ink-2);flex:none}
+.el-tab{padding:7px 14px;font-size:12.5px;color:var(--text-light);cursor:pointer;border:none;background:none;border-bottom:2px solid transparent}
+.el-tab.active{color:var(--primary);border-bottom-color:var(--primary);font-weight:600}
+.el-pane{flex:1;overflow:auto;display:none}
+.el-pane.active{display:block}
+.el-attr{display:flex;gap:8px;padding:5px 12px;border-bottom:1px solid var(--border);font-size:12px}
+.el-attr b{color:var(--text-light);font-weight:500;flex:0 0 96px;font-family:var(--mono)}
+.el-attr span{color:var(--text);word-break:break-all;flex:1}
+.el-color-row{display:flex;align-items:center;gap:8px;padding:6px 12px;font-size:12px;border-bottom:1px solid var(--border)}
+.el-swatch{width:22px;height:22px;border-radius:4px;border:1px solid var(--border);flex:none}
 .el-picker-search{width:100%;padding:8px 12px;border:none;border-bottom:1px solid var(--border);font-size:13px;outline:none;font-family:var(--body)}
 .el-picker-list{flex:1;overflow-y:auto}
 .el-picker-item{padding:8px 12px;border-bottom:1px solid var(--border);cursor:pointer;font-size:12px;display:flex;gap:8px;align-items:flex-start}
 .el-picker-item:hover{background:var(--primary-soft)}
-.el-picker-item.active{background:var(--primary-soft);border-left:3px solid var(--primary)}
+.el-picker-item.active{background:var(--primary-soft);box-shadow:inset 3px 0 0 var(--primary)}
 .el-picker-item:last-child{border-bottom:none}
 .el-picker-item .ep-depth{color:var(--text-light);font-family:var(--mono);flex-shrink:0;width:28px}
 .el-picker-item .ep-info{flex:1;min-width:0}
@@ -1044,12 +1054,12 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 
 <!-- ========== 元素抓取模态框（独立第二层，不覆盖任务编辑窗口）========== -->
 <div id="el-picker-overlay" class="modal-overlay" style="z-index:1100" onclick="if(event.target===this)closeElPicker()">
-  <div class="modal" id="el-picker-box" style="max-width:1280px;width:96vw">
+  <div class="modal" id="el-picker-box" style="max-width:1800px;width:98vw">
     <div class="modal-header">
       <h3 id="el-picker-title">抓取元素</h3>
       <button class="close" onclick="closeElPicker()">&times;</button>
     </div>
-    <div class="modal-body" id="el-picker-body" style="max-height:75vh;padding:0;overflow:hidden;display:flex;flex-direction:column"></div>
+    <div class="modal-body" id="el-picker-body" style="height:88vh;padding:0;overflow:hidden;display:flex;flex-direction:column"></div>
     <div class="modal-footer" id="el-picker-footer"></div>
   </div>
 </div>

From 0bc713137d0e58c37b6d4897bc9d70259a57eec6 Mon Sep 17 00:00:00 2001
From: butubb <1422726308@qq.com>
Date: Sun, 13 Sep 2026 22:05:47 +0800
Subject: [PATCH 6/9] =?UTF-8?q?feat(=E6=8A=93=E5=8F=96):=20=E9=80=89?=
 =?UTF-8?q?=E6=8B=A9=E5=99=A8=E4=BC=98=E5=85=88=E8=AF=AD=E4=B9=89=E5=8C=96?=
 =?UTF-8?q?=EF=BC=88=E5=90=8C=20id=20=E5=A4=9A=E5=AE=9E=E4=BE=8B=E7=94=A8?=
 =?UTF-8?q?=20@text=20=E9=99=90=E5=AE=9A=EF=BC=8C=E8=80=8C=E9=9D=9E?=
 =?UTF-8?q?=E5=BA=8F=E5=8F=B7=EF=BC=89+=20=E4=BF=AE=E6=8E=89=E4=B8=A4?=
 =?UTF-8?q?=E7=B1=BB"=E6=AD=BB=E9=80=89=E6=8B=A9=E5=99=A8"?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

语义消歧（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 ②标记完成。
---
 core/uiauto_helper.py                | 131 ++++++++++++++++++++++-----
 doc/API.md                           |  12 ++-
 doc/TASK_DEV.md                      |  29 ++++--
 doc/backlog/TODO.md                  |   2 +-
 doc/research/U2_ELEMENT_SELECTORS.md |  54 +++++++++--
 static/admin/editor.js               |  18 +++-
 templates/admin/monitor.html         |   4 +
 7 files changed, 203 insertions(+), 47 deletions(-)

diff --git a/core/uiauto_helper.py b/core/uiauto_helper.py
index b2efd8a..56afc62 100644
--- a/core/uiauto_helper.py
+++ b/core/uiauto_helper.py
@@ -12,7 +12,7 @@ API 参考（uiautodev 0.14）：
   - GET /api/android/{serial}/dump_hierarchy — 元素树 JSON
 """
 import requests
-from collections import Counter
+from collections import Counter, defaultdict
 
 from core.logger import get_logger
 
@@ -79,24 +79,32 @@ def get_elements(serial):
     """获取指定设备的 UI 元素树。
 
     返回 (ok, data_or_error)：
-      ok=True  — data 是元素列表 [{name, attrs..., suggested:{type,value,indexed?,occ?,total?,broad?}}, ...]
+      ok=True  — data 是元素列表 [{name, attrs..., suggested:{type,value,semantic?,via?,indexed?,occ?,total?,broad?}}, ...]
       ok=False — data 是错误消息字符串
 
     元素树由 uiautodev 的 dump_hierarchy 返回（JSON）。我们递归提取每个节点的
     关键属性（resource-id/text/description/class/bounds...），供前端列表展示和选择。
 
-    选择器精度策略（精确到具体按钮的关键）：
+    选择器精度策略（精确到具体按钮的关键，优先级见 doc/research/U2_ELEMENT_SELECTORS.md §三）：
       1. 有 resource-id/text/content-desc 的元素：
          先预统计该属性在整棵树中的出现次数——
            - 唯一出现：直接用属性选择器 //*[@resource-id="x"]
-           - 重复出现（如抖音底部导航 4 个 tab 同 id）：用**整体加括号**的
-             `(//*[@resource-id="x"])[k]` 精确到第 k 个匹配。
+           - 重复出现（如抖音底部导航的 tab 同 id，个数还随灰度版本变）：
+             **优先用第二个属性把目标单独圈出来**（语义选择器）：
+               //*[@resource-id="x" and @text="我"]
+             它只认"这个元素的文字/id 是什么"，不认"同 id 一共几个"，
+             换设备/换版本依然成立 → 标记 semantic + via（用于限定的属性）。
+           - 两个属性组合仍圈不出来时，才退回**整体加括号**的
+             `(//*[@resource-id="x"])[k]`（标记 indexed，前端醒目提示脆弱）。
              注意 XPath 语义：`//*[@id="x"][k]` 是"在其父节点中排第 k"，不是
              第 k 个匹配——历史实现踩过这个坑（多实例时 [2..n] 全部失配）。
       2. 无任何属性的元素：
          用最近一个有属性祖先的选择器限定范围 + 同 class 兄弟序号定位
-         （如 //*[@resource-id="x"]/FrameLayout/ImageView[2]）；
-         整棵树都没有属性时退化为从根开始的结构路径（标记 broad，前端提示脆弱）。
+         （如 //*[@resource-id="x"]/*[@class="android.widget.ImageView"][2]）；
+         整棵树都没有属性时退化为从根开始的结构路径
+         （//hierarchy/*[1]/*[3]…，标记 broad，前端提示脆弱）。
+         注意：dump 的 XML 标签一律是 <node>，class 在 @class 上 —— 任何把
+         class 名当标签名的写法（//FrameLayout[1]）都永远匹配不到，别再用。
     """
     if not serial:
         return False, "缺少 serial"
@@ -125,6 +133,25 @@ def get_elements(serial):
         return False, f"抓取失败: {e}"
 
 
+def _child_path(path):
+    """内部路径 `/0/2/1` → XPath 段 `/*[1]/*[3]/*[2]`（按**子节点位置**逐层定位）。
+
+    用于"整棵树都没有可用属性"时的兜底结构路径。为什么按位置而不是 `@index`：
+    实测 Android dump 里同级节点的 index 属性**会重复**（状态栏/内容区/导航栏
+    三个兄弟的 index 全是 "0"），拿它定位会一次命中好几个。
+    """
+    return "".join(f"/*[{int(seg) + 1}]"
+                   for seg in path.strip("/").split("/") if seg)
+
+
+def _xpath(conds):
+    """由条件列表拼 XPath：[(attr, value), ...] → `//*[@a="1" and @b="2"]`。
+
+    单个条件即 `//*[@a="1"]`。多个条件是**并列且**，任一条不成立就不匹配。
+    """
+    return "//*[" + " and ".join(f"@{a}={_xpath_q(v)}" for a, v in conds) + "]"
+
+
 def _xpath_q(v):
     """XPath 字符串字面量：优先双引号，值含双引号时改用单引号包裹（XPath 1.0 无转义）。"""
     if '"' in v:
@@ -134,8 +161,10 @@ def _xpath_q(v):
 
 def _extract(root, out):
     """把 uiautodev 元素树扁平化为可选列表，并为每个节点生成精确选择器建议。"""
-    # 全树属性出现次数（预统计，供重复元素加 [k] 序号消歧）
+    # 全树属性出现次数（预统计：判断"这个值重不重复"，决定要不要消歧）
     id_cnt, text_cnt, desc_cnt = Counter(), Counter(), Counter()
+    # 同属性值 → 该值对应的全部节点 properties（语义消歧要在"同值节点"里比第二个属性）
+    id_nodes, text_nodes, desc_nodes = defaultdict(list), defaultdict(list), defaultdict(list)
     # 文档顺序已出现次数（决定当前元素是第几个）
     seen_id, seen_text, seen_desc = Counter(), Counter(), Counter()
 
@@ -146,15 +175,57 @@ def _extract(root, out):
         rid, text, desc = (props.get(k, "") for k in ("resource-id", "text", "content-desc"))
         if rid:
             id_cnt[rid] += 1
+            id_nodes[rid].append(props)
         if text:
             text_cnt[text] += 1
+            text_nodes[text].append(props)
         if desc:
             desc_cnt[desc] += 1
+            desc_nodes[desc].append(props)
         for c in node.get("children") or []:
             count_attrs(c)
 
-    def attr_selector(attr, value, cnt, seen):
-        """属性选择器：唯一直接出；重复时用 `(…)[k]` 精确到**第 k 个匹配**。
+    # 消歧时可用的次要属性（按"越稳越靠前"排：文字 > 描述 > class）
+    _SECONDARY_ATTRS = ("text", "content-desc", "class")
+
+    def secondary_conds(peers, props):
+        """属性值重复时，找一组能**把本节点单独圈出来**的次要属性。
+
+        例：抖音底部 4 个 tab 共享 resource-id `…:0qf`，但 text 分别是
+        首页/朋友/消息/我 —— 于是
+            //*[@resource-id="…:0qf" and @text="我"]
+        这种**语义选择器**只依赖"目标自己长什么样"，不依赖"同 id 一共几个"：
+        灰度版把 tab 从 4 个变 3 个、换一台设备，它照样命中。
+        对比 `(…)[k]`：那是"第 k 个匹配"，界面一变就指到别的元素上 → 点不中。
+
+        返回 ([(attr, value), ...], via) 或 (None, None)。peers 是"同主属性值"的
+        全部节点 properties —— 唯一性只需在这一集合内成立（任何匹配都必然在此集合中）。
+        """
+        def matched(conds):
+            return sum(1 for p in peers
+                       if all((p.get(a) or "") == v for a, v in conds))
+
+        usable = [(a, props.get(a) or "") for a in _SECONDARY_ATTRS]
+        usable = [(a, v) for a, v in usable if v.strip()]  # 空值不能做限定条件
+        # 单个次要属性够了就用它（选择器最短）
+        for a, v in usable:
+            if matched([(a, v)]) == 1:
+                return [(a, v)], a
+        # 单个不够 → 两个次要属性组合（如 @text + @class）
+        for i in range(len(usable)):
+            for j in range(i + 1, len(usable)):
+                conds = [usable[i], usable[j]]
+                if matched(conds) == 1:
+                    return conds, f"{usable[i][0]}+{usable[j][0]}"
+        return None, None
+
+    def attr_selector(attr, value, cnt, seen, peers, props):
+        """属性选择器：唯一直接出；重复时**先语义消歧，再退化到序号**。
+
+        语义消歧（2026-09-13 新增，见 doc/research/U2_ELEMENT_SELECTORS.md §五）：
+          //*[@resource-id="x" and @text="我"]   ← 不依赖元素个数，换设备/换版本仍成立
+        退而求其次（同 id 同文字都分不开，如列表里的重复项）：
+          (//*[@resource-id="x"])[2]            ← 精确到第 2 个匹配，但界面一变就失配
 
         重要（XPath 位置谓词语义）：
           //*[@resource-id="x"][2]   → 「在**其父节点**中排第 2 的属性匹配」，**不是**第 2 个匹配
@@ -163,12 +234,20 @@ def _extract(root, out):
         [2..n] 全部匹配不到 → 运行时"未找到元素"（2026-09-10 实测修复）。
         """
         seen[value] += 1
-        base = f'//*[@{attr}={_xpath_q(value)}]'
+        conds = [(attr, value)]
         if cnt[value] > 1:
-            val = f"({base})[{seen[value]}]"
-            return val, {"type": "xpath", "value": val,
-                         "indexed": True, "occ": seen[value], "total": cnt[value]}
-        return base, {"type": "xpath", "value": base}
+            extra, via = secondary_conds(peers, props)
+            if extra:
+                conds += extra
+            else:
+                val = f"({_xpath(conds)})[{seen[value]}]"
+                return val, {"type": "xpath", "value": val, "indexed": True,
+                             "occ": seen[value], "total": cnt[value]}
+        val = _xpath(conds)
+        info = {"type": "xpath", "value": val}
+        if len(conds) > 1:
+            info.update(semantic=True, via=via)
+        return val, info
 
     def flatten(node, depth=0, path="", ctx=None, tag_path="", tag_index=1):
         """递归扁平化。
@@ -201,7 +280,10 @@ def _extract(root, out):
         # 始终带同 class 兄弟序号（含 [1]），结构路径才精确无歧义；
         # class 为空的层（tag=*）不参与结构路径，避免 //*[N] 前缀污染导致选择器定位到任意节点
         if tag != "*":
-            seg = f"{tag}[{tag_index}]"
+            # 步进必须写成 `*[@class="…"]`，**不能**写 `FrameLayout[1]`：
+            # Android dump 的 XML 里每个元素的**标签名都是 `<node>`**，class 在
+            # @class 属性上 —— 写成标签名会永远匹配不到任何东西（见下方 broad 注释）。
+            seg = f"*[@class={_xpath_q(cls)}][{tag_index}]"
             own_tag_path = f"{tag_path}/{seg}" if tag_path else seg
         else:
             seg = ""
@@ -209,11 +291,14 @@ def _extract(root, out):
 
         # ---- 推荐选择器：唯一属性 > 锚点祖先限定 > 全结构路径 ----
         if rid:
-            child_ctx, suggested = attr_selector("resource-id", rid, id_cnt, seen_id)
+            child_ctx, suggested = attr_selector("resource-id", rid, id_cnt, seen_id,
+                                                 id_nodes[rid], props)
         elif text:
-            child_ctx, suggested = attr_selector("text", text, text_cnt, seen_text)
+            child_ctx, suggested = attr_selector("text", text, text_cnt, seen_text,
+                                                 text_nodes[text], props)
         elif desc:
-            child_ctx, suggested = attr_selector("content-desc", desc, desc_cnt, seen_desc)
+            child_ctx, suggested = attr_selector("content-desc", desc, desc_cnt, seen_desc,
+                                                 desc_nodes[desc], props)
         elif ctx:
             val = f"{ctx}/{seg}"
             suggested = {"type": "xpath", "value": val}
@@ -226,8 +311,12 @@ def _extract(root, out):
                              "invalid": True,
                              "reason": "该元素无可用属性（id/文本/class），无法生成可靠选择器"}
             else:
-                # 无唯一属性且无锚点祖先：用从根开始的结构路径（脆弱，标记 broad 让前端提示）
-                suggested = {"type": "xpath", "value": f"//{own_tag_path}", "broad": True}
+                # 无唯一属性且无锚点祖先：用从根开始的结构路径（脆弱，标记 broad 让前端提示）。
+                # 按子节点位置逐层定位 —— 历史实现写成 //FrameLayout[1]/LinearLayout[2]
+                # 这种"class 当标签名"的路径，**永远零命中**（dump 的标签全是 <node>）；
+                # 实测 248 个元素里 26 条死选择器，2026-09-13 修复。
+                suggested = {"type": "xpath", "value": f"//hierarchy{_child_path(path)}",
+                             "broad": True}
             child_ctx = None
 
         out.append({
diff --git a/doc/API.md b/doc/API.md
index 7a9a26a..3fa1e11 100644
--- a/doc/API.md
+++ b/doc/API.md
@@ -527,10 +527,20 @@
 |------|------|---------|
 | `GET /api/uiauto/status` | — | uiautodev（:20242）是否在跑，前端据此禁/启用"抓取元素" |
 | `GET /api/uiauto/devices` | — | 可选设备列表（uiautodev 设备 + 池内在线补全） |
-| `GET /api/uiauto/elements?serial=` | — | 扁平元素列表，每项带 `suggested`（推荐选择器）、`bounds`、`depth` |
+| `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/screenshot?serial=` | — | JPEG |
 | `POST /api/steps/test` | `{"serial","step":{…}}` | 真机试执行单个步骤 → `命中 / 未找到 / 已执行` |
 
+**`suggested`（推荐选择器）字段**：`{type, value, semantic?, via?, indexed?, occ?, total?, broad?, invalid?, reason?}`
+
+| 字段 | 含义 |
+|------|------|
+| `semantic` + `via` | **语义选择器**：`//*[@id="x" and @text="y"]`，`via` 是用于限定的第二属性（`text`/`content-desc`/`class` 或 `a+b`）——不依赖同类元素个数，换设备/换版本仍命中 |
+| `indexed` + `occ`/`total` | 退化形式 `(//*[@id="x"])[k]`：同 id 且同文字分不开时才用，**界面一变即失配**，前端黄标提醒 |
+| `broad` | 结构路径兜底（`//hierarchy/*[i]/*[j]`），最脆 |
+| `invalid` + `reason` | 无任何可用属性，前端禁止回填 |
+
 `GET /api/uiauto/elements` 在 uiautodev 不可用时返回 **503**。设备 dump 慢时可能超时（见 [backlog](backlog/TODO.md)）。
 
 ---
diff --git a/doc/TASK_DEV.md b/doc/TASK_DEV.md
index f21a071..b7fc697 100644
--- a/doc/TASK_DEV.md
+++ b/doc/TASK_DEV.md
@@ -206,22 +206,33 @@ from .generic import task  # 触发 @register_task（当前唯一任务类型）
 
 历史实现写了前者，导致同 id 多实例（如底部导航 4 个 tab）时 `[2..n]` 全部失配。现在：
 
-- `core/uiauto_helper.py` 生成的都是 `(//*[@…])[k]` 形式（唯一匹配时才省略序号）
-- 执行器 `tasks/generic/task.py` 的 `_norm_legacy_xpath` 会**自动纠正**旧任务里的 `//*[@x][k]` 写法（仅前缀，`.../FrameLayout[2]` 这类兄弟序号不受影响）
+- 执行器 `tasks/generic/task.py` 的 `_norm_legacy_xpath` 会**自动纠正**旧任务里的 `//*[@x][k]` 写法（仅前缀，类名/位置步进不受影响）
+- 抓取器生成 `(…)[k]` 前**先做语义消歧**（见 §5.4），序号型只是最后的退路
 
-⚠️ **序号型选择器仍然脆弱**：它依赖"抓取那一刻该属性有 ≥k 个实例"。界面不同（如 App 还在闪屏页）就会失配——优先选唯一 id 或文字。
+⚠️ **序号型选择器仍然脆弱**：它依赖"抓取那一刻该属性有 ≥k 个实例"。界面不同（如 App 还在闪屏页）就会失配——优先选带**文字**的元素，抓取器会自动产出语义选择器。
 
 ### 5.4 抓取器给的建议选择器
 
-`GET /api/uiauto/elements` 返回的元素带 `suggested`，生成优先级：
+`GET /api/uiauto/elements`、`GET /api/uiauto/snapshot` 返回的元素都带 `suggested`，生成优先级：
 
-1. 有 `resource-id` → `//*[@resource-id="v"]`（重复时带序号 `(…)[k]`，并标 `indexed:true` + 出现次数）
-2. 无 id 有 `text` → `//*[@text="v"]`
-3. 无 id/text 有 `content-desc` → `//*[@content-desc="v"]`
-4. 都没有但有"最近的有属性祖先" → `{祖先}/{Class}[n]` 结构路径
-5. 连祖先都没有 → `//{class_path}`（标 `broad:true`，脆弱，前端会提示）
+1. 有 `resource-id` → `//*[@resource-id="v"]`；无 id 但有 `text`/`content-desc` 同理
+2. 该属性值**全树有多个**时，**先用第二个属性把目标单独圈出来**（语义选择器，标 `semantic:true` + `via`）：
+   `//*[@resource-id="v" and @text="我"]`。抖音底部导航同 id 的几个 tab 靠这个解决——
+   灰度版 tab 数量会变（4 个 ↔ 3 个），序号必然错位，文字不会
+3. 两个属性组合仍分不开（列表里同 id 同文字）→ 才退回序号 `(…)[k]`（标 `indexed:true` + `occ`/`total`，前端打**黄标 ⚠ 序号**）
+4. 都没有属性、但有"最近的有属性祖先" → `{祖先}/*[@class="android.widget.ImageView"][n]`
+5. 连祖先都没有 → `//hierarchy/*[i]/*[j]`（按**子节点位置**逐层，标 `broad:true`，脆弱、前端会提示）
 6. 类名也是空 → 标 `invalid:true`（提示无法生成可靠选择器）
 
+**两个必须记住的 XPath 坑**（都实测踩过）：
+
+- **dump 的 XML 标签名一律是 `<node>`**，`class` 在 `@class` 属性上。所以结构步进只能写
+  `*[@class="…"]` 或位置 `*[i]`；写成 `//FrameLayout[1]` 这种"类名当标签名"的路径**永远零命中**
+  （2026-09-13 修：248 个元素里曾有 26 条死选择器）
+- **同级节点的 `index` 属性会重复**（状态栏/内容区/导航栏三个兄弟的 `index` 全是 `0`），
+  兜底结构路径要按**位置** `*[i+1]` 定位，不能按 `@index`
+
+
 ### 5.5 抓取与验证（编辑器里的两个按钮）
 
 - **「▶ 点一下」**：按元素 `bounds` 中心在设备上真点一次（`POST /api/screen/tap`，`snap=1` 自动吸附到可点元素中心），返回吸附结果并刷新截图——确认位置是否可达
diff --git a/doc/backlog/TODO.md b/doc/backlog/TODO.md
index d833de7..8bc1907 100644
--- a/doc/backlog/TODO.md
+++ b/doc/backlog/TODO.md
@@ -86,7 +86,7 @@
 
 - [ ] **序号型 XPath / 界面就绪 的防呆**（2026-09-10 db03f16e 案例）
   - 背景：`(//*[@resource-id="…"])[6]` 依赖"抓取那一刻该属性有 ≥6 个实例"；运行时界面不同（App 仍在闪屏页）→ 序号必然失配。
-  - 期望：① `open_app` 提示勾选「等待首页」；② 抓取器对**带序号**的选择器加醒目提示；③ 抓取弹窗提醒"请先把设备停在任务运行到该步时的同一界面再抓"。
+  - 期望：① `open_app` 提示勾选「等待首页」；② ~~抓取器对**带序号**的选择器加醒目提示~~（✅ 2026-09-13 已完成，且更进一步：抓取器**优先产出语义选择器**再去掉序号，见 [research/U2_ELEMENT_SELECTORS.md](../research/U2_ELEMENT_SELECTORS.md) §五）；③ 抓取弹窗提醒"请先把设备停在任务运行到该步时的同一界面再抓"。
   - 涉及：`core/uiauto_helper.py`、`static/admin/editor.js`、`tasks/generic/task.py`、`doc/TASK_DEV.md`。
 
 - [ ] 自定义动作支持 `action_ref` 引用型节点（现状：拖入画布会**展开成 group**，改动需同步执行器 + 编辑器）。
diff --git a/doc/research/U2_ELEMENT_SELECTORS.md b/doc/research/U2_ELEMENT_SELECTORS.md
index 9c703fb..49918e5 100644
--- a/doc/research/U2_ELEMENT_SELECTORS.md
+++ b/doc/research/U2_ELEMENT_SELECTORS.md
@@ -125,16 +125,50 @@
 
 ---
 
-## 五、建议的改动（待排期）
+## 五、建议的改动
 
-1. **抓取器（`core/uiauto_helper.py`）**：同一 id 出现多个实例时，**优先产出
-   `//*[@resource-id="x" and @text="…"]`** 而不是 `(…)[k]`；抓取列表里把
-   `text`/`content-desc` 放在最显眼位置，让用户能看着选。
-2. **抓取弹窗**：对**带序号**的选择器加醒目提示（"这个选择器依赖界面元素个数，
-   界面一变就失效"）。
-3. **已存任务**：把 `(…)[k]` 型选择器扫一遍，能改成文字限定的自动改（脚本），
-   其余在编辑器里逐个复核。
-4. **运行期**：`click` 未命中时，日志里顺带 dump 一下"同 id 现在有几个实例"，
+1. ✅ **抓取器优先产出语义选择器**（2026-09-13 已实现，`core/uiauto_helper._extract`）：
+   同一属性值出现多个实例时，**先找第二个属性把目标单独圈出来** ——
+   `//*[@resource-id="x" and @text="…"]`（次属性按 `text` > `content-desc` > `class`
+   排，单个不够就两个组合）；只有怎么都分不开（列表里同 id 同文字）才退回
+   `(…)[k]`。返回值标 `semantic:true` + `via`（限定用的属性）或 `indexed:true`。
+   抓取列表里 **text/content-desc 排在最前并加粗上色**，让用户能看着选。
+2. ✅ **序号型加醒目提示**（同日）：前端把 `indexed` 的徽标从蓝色 `#k/n` 换成
+   黄色 **⚠ 序号 k/n**，悬浮说明"依赖同类元素个数，界面一变就指到别的元素上"；
+   语义型给绿色 **✓ 语义**；右侧「属性」页新增一行**选择器稳定性**。
+3. ⏳ **已存任务**：把 `(…)[k]` 型选择器扫一遍，能改成文字限定的自动改（脚本），
+   其余在编辑器里逐个复核。（用户自行处理）
+4. ⏳ **运行期**：`click` 未命中时，日志里顺带 dump 一下"同 id 现在有几个实例"，
    让"序号错位"当场可诊断（现在是干巴巴一句"未找到元素"）。
-5. **（针对第四节的"抓取错位"）** 抓取接口合并成一个快照接口 + 双截图校验，
+5. ✅ **（针对第四节的"抓取错位"）** 抓取接口合并成一个快照接口 + 双截图校验，
    具体见第四节「解法」。
+
+---
+
+## 六、顺带修掉的两个"结构性"坑（2026-09-13）
+
+给 §五.1 做验证时（对真机 dump 逐条用 lxml 求值，比对"命中数==1 且 bounds 一致"），
+发现旧实现 248 个元素里有 **26 条选择器永远匹配不到任何东西** —— 都是"结构路径"类：
+
+| 坑 | 现象 | 原因 |
+|---|---|---|
+| `//FrameLayout[1]/LinearLayout[2]` | 零命中 | **dump 的 XML 标签名一律是 `<node>`**，class 在 `@class` 属性上 —— 把类名当标签名写的路径永远匹配不到 |
+| `//hierarchy/node[@index="1"]` | 零命中或一次命中多个 | 同级节点的 **`index` 属性会重复**（实测状态栏/内容区/导航栏三个兄弟的 `index` 全是 `0`） |
+
+**修法**：
+
+- 子路径步进改成 `*[@class="android.widget.ImageView"][n]`（谓词 `[n]` 在步进选出的
+  节点集上按文档序定位，语义与原来的"同 class 兄弟序号"一致）
+- 兜底结构路径改成按**子节点位置**：`//hierarchy/*[1]/*[3]`
+
+**效果**（同一份真机 XML，248 个元素）：
+
+| | 旧 | 新 |
+|---|---|---|
+| 先按 lxml 求值，精确命中目标 | 221 | **247** |
+| 零命中（死选择器） | 26 | **0** |
+| 语义型 / 序号型 | 0 / 141 | **26 / 115** |
+
+`core/uiauto_helper.py` 里 `_child_path()` 的注释与 `doc/TASK_DEV.md` §5.4 都记了这两个坑，
+避免以后又写回来。
+
diff --git a/static/admin/editor.js b/static/admin/editor.js
index 4e2b058..2b6b057 100644
--- a/static/admin/editor.js
+++ b/static/admin/editor.js
@@ -882,7 +882,12 @@ var _stepEditor={
     if(!box)return;
     if(!el){box.innerHTML='<div class="se-empty">点左侧图上的元素，或点「层级」里的条目看属性</div>';return;}
     var sg=el.suggested||{};
-    var rows=[['建议选择器', sg.value||'(无可靠选择器)'],
+    // 稳定性说明：把"这个选择器靠什么定位"写清楚，用户才知道它会不会因为界面变化而失效
+    var stab=sg.semantic?'✓ 语义型 —— 靠 @'+(sg.via||'')+' 限定，不依赖同类元素个数，换设备/换版本仍命中'
+            :sg.indexed?'⚠ 序号型 —— 依赖「同类元素共 '+sg.total+' 个、取第 '+sg.occ+' 个」，界面一变就失配'
+            :sg.broad?'⚠ 宽泛 —— 无唯一属性，可能误匹配其他元素'
+            :(sg.value?'✓ 唯一属性，直接定位':'—');
+    var rows=[['建议选择器', sg.value||'(无可靠选择器)'],['选择器稳定性', stab],
               ['class', el.class||''], ['resource-id', el.resource_id||''],
               ['text', el.text||''], ['content-desc', el.description||''],
               ['package', el.package||''], ['clickable', el.clickable||''],
@@ -1103,10 +1108,12 @@ var _stepEditor={
     var self=this;
     var html=list.map(function(el){
       var idx=self._elData.indexOf(el);
+      // 属性顺序有讲究：**文字/描述排最前并加粗**——它们是最稳的定位依据，
+      // 也是"一眼认出这是哪个元素"的凭据（id 只是补充）。见 doc/TASK_DEV.md §5.4。
       var attrs=[];
-      if(el.resource_id)attrs.push('<span>id:'+esc(el.resource_id)+'</span>');
-      if(el.text)attrs.push('<span>text:'+esc(el.text)+'</span>');
-      if(el.description)attrs.push('<span>desc:'+esc(el.description)+'</span>');
+      if(el.text)attrs.push('<span class="ep-text">text:<b>'+esc(el.text)+'</b></span>');
+      if(el.description)attrs.push('<span class="ep-desc">desc:<b>'+esc(el.description)+'</b></span>');
+      if(el.resource_id)attrs.push('<span class="ep-id">id:'+esc(el.resource_id)+'</span>');
       var indent='  '.repeat(Math.min(el.depth||0,6));
       var sg=el.suggested||{};
       if(sg.invalid)attrs.push('<span style="color:#dc2626">⚠ '+esc(sg.reason||'无可用属性')+'</span>');
@@ -1125,7 +1132,8 @@ var _stepEditor={
         '<div class="ep-info"><div class="ep-name">'+indent+esc(el.name||el.class||'')+'</div>'+
         '<div class="ep-attrs">'+attrs.join('')+'</div></div>'+
         '<span class="ep-sel">'+esc(sg.type)+'</span>'+
-        (sg.indexed?' <span class="label label-info" title="界面中同属性元素共 '+sg.total+' 个，按从上到下这是第 '+sg.occ+' 个，选择器已带序号精确定位">#'+sg.occ+'/'+sg.total+'</span>':'')+
+        (sg.semantic?' <span class="label label-success" title="语义选择器：用 '+esc(sg.via||'')+' 限定，只认「这个元素长什么样」，不认「同类元素有几个」—— 换设备、换版本、界面增减元素都照样命中">✓ 语义</span>':'')+
+        (sg.indexed?' <span class="label label-warning" title="⚠ 序号型：依赖「同属性元素共 '+sg.total+' 个、这是第 '+sg.occ+' 个」。界面上多/少一个同类元素（如抖音灰度版少一个 tab）就会指到别的元素上 —— 建议改选带 text 或 content-desc 的元素，拿到语义选择器">⚠ 序号 '+sg.occ+'/'+sg.total+'</span>':'')+
         (sg.broad?' <span class="label label-warning" title="无唯一属性，选择器可能误匹配其他元素，建议选带文字/id 的元素">⚠宽泛</span>':'')+
         acts+
       '</div>';
diff --git a/templates/admin/monitor.html b/templates/admin/monitor.html
index 214a6a7..75de8cb 100644
--- a/templates/admin/monitor.html
+++ b/templates/admin/monitor.html
@@ -324,6 +324,10 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 .el-picker-item .ep-info .ep-name{color:var(--text);font-weight:500;word-break:break-all}
 .el-picker-item .ep-info .ep-attrs{color:var(--text-light);font-size:11px;margin-top:2px;word-break:break-all}
 .el-picker-item .ep-info .ep-attrs span{margin-right:8px}
+/* 文字/content-desc 是最稳的定位依据，加粗上色让它一眼可见（id 退为补充信息） */
+.el-picker-item .ep-info .ep-attrs .ep-text b{color:#0f766e;font-weight:600}
+.el-picker-item .ep-info .ep-attrs .ep-desc b{color:#7c3aed;font-weight:600}
+.el-picker-item .ep-info .ep-attrs .ep-id{font-family:var(--mono);opacity:.8}
 .el-picker-item .ep-sel{font-size:10px;color:#fff;background:var(--primary);padding:1px 7px;border-radius:99px;flex-shrink:0;font-weight:600}
 
 /* ===== AI 控制台（聊天界面，浅色内容区——DeepSeek 风格，图片文字清晰） ===== */

From 46e6ea1f373998c7c7bb0675109c78860443bbe7 Mon Sep 17 00:00:00 2001
From: butubb <1422726308@qq.com>
Date: Sun, 13 Sep 2026 23:08:59 +0800
Subject: [PATCH 7/9] =?UTF-8?q?feat(AI=20=E5=BB=BA=E4=BB=BB=E5=8A=A1):=20A?=
 =?UTF-8?q?I=20=E8=87=AA=E5=B7=B1=E5=9C=A8=E7=9C=9F=E6=9C=BA=E6=8E=A2?=
 =?UTF-8?q?=E7=B4=A2=20=E2=86=92=20=E5=86=99=E5=87=BA=E5=8F=AF=E8=B0=83?=
 =?UTF-8?q?=E5=BA=A6=E4=BB=BB=E5=8A=A1=20=E2=86=92=20=E4=BA=BA=E5=B7=A5?=
 =?UTF-8?q?=E7=A1=AE=E8=AE=A4=E5=85=A5=E5=BA=93?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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。
---
 core/task_draft.py           | 541 +++++++++++++++++++++++++++++++++++
 doc/AI_CONSOLE.md            |  20 +-
 doc/AI_TASK_GEN.md           |  61 +++-
 doc/API.md                   |  19 +-
 doc/ARCHITECTURE.md          |   3 +-
 doc/DATA_MODEL.md            |   1 +
 doc/DEVELOPMENT.md           |   1 +
 doc/README.md                |   2 +-
 doc/backlog/TODO.md          |   3 +-
 mcp_agent/agent.py           | 220 ++++++++++++--
 static/admin/agent.js        |  15 +-
 static/admin/base.js         |   8 +-
 static/admin/taskgen.js      | 416 +++++++++++++++++++++++++++
 static/admin/tasks.js        |  46 ++-
 templates/admin/monitor.html | 129 +++++++++
 web/agent_api.py             | 269 ++++++++++++++++-
 16 files changed, 1707 insertions(+), 47 deletions(-)
 create mode 100644 core/task_draft.py
 create mode 100644 static/admin/taskgen.js

diff --git a/core/task_draft.py b/core/task_draft.py
new file mode 100644
index 0000000..e63e000
--- /dev/null
+++ b/core/task_draft.py
@@ -0,0 +1,541 @@
+"""AI 建任务的 draft 契约：**校验 + 归一化**（唯一真相）。
+
+## 为什么必须有这个模块
+
+任务执行器对"写错的地方"是**静默跳过**的：未知步骤类型只打一条 warning 继续
+（`tasks/generic/task.py` 的 `_exec_one`），空 `selector_value` 直接 return。
+而 `POST /api/jobs` 只校验 `name` + `task_type`，`params` 完全盲存
+（`web/tasks_api.py`）。两者叠加的后果是：AI（或任何人）交上一条写错的任务，
+**创建成功、运行不报错、但什么都没做**。
+
+所以这里把执行器的每个"静默跳过点"前移成显式 error，在**落库之前**拦住。
+错误文案是给**模型**看的（走 `submit_task` 的返回值回灌，让它逐条改完重提），
+所以每条都要说清"哪个节点的哪个字段、错在哪、应该是什么"。
+
+## 用法
+
+    res = validate_draft(draft, groups=..., pool=..., default_serial="...")
+    # → {"ok": bool, "errors": [...], "warnings": [...], "draft": 归一化后的草稿}
+
+`errors` 非空就是不能落库；`warnings` 只是提醒（前端醒目展示，不拦）。
+
+契约与规则的权威描述见 `doc/AI_TASK_GEN.md`。
+"""
+import re
+
+from core.logger import get_logger
+
+_log = get_logger("core.task_draft")
+
+# ================== 常量（规则的唯一来源） ==================
+
+# 单条任务最多多少个步骤节点（含嵌套），防止模型输出失控/被输出长度截断
+MAX_NODES = 60
+# 嵌套深度上限（执行器 >5 层直接跳过该分支，见 tasks/generic/task.py）
+MAX_DEPTH = 5
+# 选择器值长度上限
+MAX_SELECTOR_LEN = 200
+# 单条 input_text 的候选文案条数
+MAX_TEXTS = 20
+
+# 与编辑器下拉（static/admin/editor.js 的 selector_type 选项）严格同集。
+# 故意不含 textContains —— 下拉里没有它，用户一改就丢。
+SELECTOR_TYPES = ("xpath", "description", "text", "resourceId",
+                  "descriptionContains", "className")
+IF_SELECTOR_TYPES = SELECTOR_TYPES + ("ocr",)
+
+# 按键白名单（u2 的 d.press 支持更多，这里只放"不会把设备弄坏"的那些：
+# 不含 power/camera —— 探索期误按 power 会让设备息屏、任务中途失联）
+KEY_WHITELIST = ("back", "home", "enter", "menu", "recent", "delete",
+                 "volume_up", "volume_down", "search")
+
+DIRECTIONS = ("up", "down", "left", "right")
+LOOP_MODES = ("rounds", "time", "forever")
+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_PACKAGE = ("open_app", "stop_app")
+# 需要非空 children 的容器
+NEED_CHILDREN = ("loop", "group")
+
+# 有副作用的动作关键词：命中的步骤在 AI 通道只给 warning（人工复核），不拦
+DESTRUCTIVE_HINTS = ("评论", "发送", "发布", "投稿", "转发", "分享到",
+                     "购买", "下单", "支付", "付款", "删除", "卸载",
+                     "退出登录", "注销", "举报", "拉黑", "清空")
+# 命中上面关键词的步骤，触发概率被压到这个值（可人工改回）
+SAFE_PROBABILITY = 30
+
+_PKG_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z0-9_]+)+$")
+_HHMM_RE = re.compile(r"^([01]\d|2[0-3]):[0-5]\d$")
+# 「序号型」选择器的两种形态：
+#   (//*[@resource-id="x"])[4]  ← 抓取器在语义消歧失败时给的（当前形态）
+#   //*[@resource-id="x"][4]    ← 历史形态（执行器会自动纠正成上面那种）
+# 两者都依赖"同类元素有几个"，界面一变就指到别的元素上，都值得提醒换语义选择器。
+_SEQ_SELECTOR_RE = re.compile(r"^(?:\(\s*//\*\[@[^\]]+\]\s*\)|//\*\[@[^\]]+\])\[\d+\]")
+
+
+def _step_types():
+    """步骤类型 → (label, 默认 params)，直接取自执行器的权威定义。"""
+    from tasks.generic.task import STEP_TYPES
+    return {s["type"]: (s.get("label", s["type"]), dict(s.get("params") or {}))
+            for s in STEP_TYPES}
+
+
+def _is_num(v):
+    return isinstance(v, (int, float)) and not isinstance(v, bool)
+
+
+def _num(params, key, default=None):
+    v = params.get(key, default)
+    return v if _is_num(v) else default
+
+
+# ================== 步骤树校验 ==================
+
+def validate_steps(steps, depth=1, path="steps", errors=None, warnings=None,
+                   types=None, counter=None):
+    """递归校验步骤树，返回 (errors, warnings, 节点总数)。
+
+    每条 error 都带上路径（如 `steps[0].params.children[2]`），模型据此能直接定位。
+    """
+    errors = [] if errors is None else errors
+    warnings = [] if warnings is None else warnings
+    types = _step_types() if types is None else types
+    counter = [0] if counter is None else counter
+
+    if not isinstance(steps, list):
+        errors.append(f"{path}: 必须是数组")
+        return errors, warnings, counter[0]
+
+    for i, step in enumerate(steps):
+        here = f"{path}[{i}]"
+        if not isinstance(step, dict):
+            errors.append(f"{here}: 必须是对象")
+            continue
+        stype = step.get("type")
+        if not stype:
+            errors.append(f"{here}: 缺少 type 字段")
+            continue
+        if stype not in types:
+            errors.append(f"{here}: 未知步骤类型 {stype!r}（可用类型："
+                          f"{'、'.join(types)}）")
+            continue
+        if stype == "click_xy":
+            errors.append(f"{here}: 不允许坐标点击（click_xy）—— 坐标在不同分辨率/"
+                          "设备上必失配，请改用 click + 选择器定位元素")
+            continue
+
+        counter[0] += 1
+        if counter[0] > MAX_NODES:
+            errors.append(f"{here}: 步骤节点总数超过 {MAX_NODES} 个，请精简"
+                          "（去掉冗余的等待/滑动，合并重复结构）")
+            return errors, warnings, counter[0]
+
+        params = step.get("params")
+        if params is None:
+            params = {}
+        if not isinstance(params, dict):
+            errors.append(f"{here}.params: 必须是对象")
+            continue
+
+        # 触发概率（执行器对所有类型通用）
+        prob = params.get("probability")
+        if prob is not None:
+            if not _is_num(prob) or not (0 <= prob <= 100):
+                errors.append(f"{here}.params.probability: 必须是 0~100 的数字"
+                              f"（当前 {prob!r}）")
+
+        # 选择器类步骤
+        if stype in NEED_SELECTOR:
+            sel = params.get("selector_value")
+            if not isinstance(sel, str) or not sel.strip():
+                errors.append(f"{here}.params.selector_value: 不能为空 —— "
+                              "该步骤没有定位目标，执行时会被静默跳过。"
+                              "如果这一步还没探索出可靠的定位，请把它从 steps 里去掉，"
+                              "需要人工确认的写进 notes")
+            else:
+                _check_selector(params, here, stype, errors, warnings)
+
+        # 包名类步骤
+        if stype in NEED_PACKAGE:
+            pkg = params.get("package")
+            if not isinstance(pkg, str) or not _PKG_RE.match(pkg.strip()):
+                errors.append(f"{here}.params.package: 必须是包名（如 "
+                              "com.ss.android.ugc.aweme），当前 "
+                              f"{pkg!r}")
+
+        # 容器
+        if stype in NEED_CHILDREN:
+            children = params.get("children")
+            if not isinstance(children, list) or not children:
+                errors.append(f"{here}.params.children: 不能为空 —— "
+                              "空容器等于什么都没做")
+                continue
+            if depth >= MAX_DEPTH:
+                errors.append(f"{here}: 嵌套层级超过 {MAX_DEPTH} 层"
+                              "（执行器会直接跳过这个分支）")
+                continue
+            validate_steps(children, depth + 1, f"{here}.params.children",
+                           errors, warnings, types, counter)
+
+        if stype == "loop":
+            mode, fixed = _norm_loop_mode(params.get("loop_mode"))
+            params["loop_mode"] = mode
+            if fixed:
+                warnings.append(f"{here}.params.loop_mode: 已按 {fixed!r} 归一为 "
+                                f"{mode!r}（执行器对未知取值按轮次处理）")
+            if mode == "rounds":
+                it = params.get("max_iterations")
+                if it is None:
+                    # 执行器默认 10（tasks/generic/task.py 的 _exec_loop）——
+                    # 能跑通的就不该拦，补默认值并提示即可
+                    params["max_iterations"] = 10
+                    warnings.append(f"{here}.params.max_iterations: 未填，按默认 10 轮")
+                elif not _is_num(it) or it < 1:
+                    errors.append(f"{here}.params.max_iterations: 按轮次循环时"
+                                  f"必须 ≥1（当前 {it!r}）")
+            elif mode == "time":
+                dur = params.get("loop_duration")
+                # 按时间循环缺时长时执行器**直接跳过**整块（静默无操作）→ 必须拦
+                if not _is_num(dur) or dur < 10:
+                    errors.append(f"{here}.params.loop_duration: 按时间循环时"
+                                  f"必须 ≥10 秒（当前 {dur!r}）")
+
+        if stype == "if_el":
+            then = params.get("then")
+            if not isinstance(then, list) or not then:
+                errors.append(f"{here}.params.then: 不能为空 —— "
+                              "条件命中后必须做点什么")
+            if depth >= MAX_DEPTH:
+                errors.append(f"{here}: 嵌套层级超过 {MAX_DEPTH} 层")
+                continue
+            if isinstance(then, list):
+                validate_steps(then, depth + 1, f"{here}.params.then",
+                               errors, warnings, types, counter)
+            else_ = params.get("else")
+            if isinstance(else_, list) and else_:
+                validate_steps(else_, depth + 1, f"{here}.params.else",
+                               errors, warnings, types, counter)
+
+        if stype == "swipe":
+            _check_direction(params, here, errors)
+            dmin, dmax = _num(params, "duration_min"), _num(params, "duration_max")
+            if dmin is not None and dmax is not None and dmin > dmax:
+                errors.append(f"{here}.params: duration_min({dmin}) 不能大于 "
+                              f"duration_max({dmax})")
+
+        if stype == "swipe_until":
+            _check_direction(params, here, errors)
+            n = params.get("max_swipes")
+            if not _is_num(n) or not (1 <= n <= 50):
+                errors.append(f"{here}.params.max_swipes: 必须是 1~50（当前 {n!r}）")
+
+        if stype == "wait":
+            lo, hi = _num(params, "min"), _num(params, "max")
+            if lo is None or hi is None or lo < 0 or hi > 600 or lo > hi:
+                errors.append(f"{here}.params: 需要 0 ≤ min ≤ max ≤ 600"
+                              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} 条")
+
+        if stype == "clipboard":
+            if not str(params.get("text") or "").strip():
+                errors.append(f"{here}.params.text: 剪贴板内容不能为空")
+
+        if stype == "keep_screen":
+            if params.get("mode", "on") not in ("on", "off"):
+                errors.append(f"{here}.params.mode: 必须是 on 或 off")
+
+        if stype == "key_event":
+            key = params.get("key", "back")
+            if key not in KEY_WHITELIST:
+                errors.append(f"{here}.params.key: 不支持的按键 {key!r}"
+                              f"（可用：{'、'.join(KEY_WHITELIST)}）")
+
+        _check_destructive(step, here, warnings)
+
+    return errors, warnings, counter[0]
+
+
+def _check_selector(params, here, stype, errors, warnings):
+    """选择器类型/取值合法性（跨 xpath 与 u2 kwarg 两套语义）。"""
+    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:
+        errors.append(f"{here}.params.selector_type: 不支持 {sel_type!r}"
+                      f"（可用：{'、'.join(stype_ok)}）")
+        return
+    if len(value) > MAX_SELECTOR_LEN:
+        errors.append(f"{here}.params.selector_value: 太长（>{MAX_SELECTOR_LEN} 字符）")
+        return
+    if sel_type == "xpath":
+        if not (value.startswith("//") or value.startswith("(//")):
+            errors.append(f"{here}.params.selector_value: 类型是 xpath，但取值不是 "
+                          f"// 或 (// 开头（当前 {value[:40]!r}）")
+        elif _SEQ_SELECTOR_RE.match(value):
+            # 执行器有 _norm_legacy_xpath 兜底纠正，所以只提醒不拦：
+            # 序号型选择器「同类元素个数一变就失配」，能换成文字限定就用文字
+            warnings.append(f"{here}.params.selector_value: 序号型选择器"
+                            f"（{value[:40]}）依赖同类元素个数，界面一变就会点空，"
+                            "建议改用 @text/@content-desc 限定")
+
+
+# 模型常见的近义写法 → 执行器认的枚举值。
+# 归一化而不是报错：执行器对未知 loop_mode 是按"轮次"处理的（else 分支），
+# 拦下来只会让模型反复重试（实测把一个 40 步的探索硬生生耗在改这一个字段上）。
+_LOOP_MODE_ALIAS = {
+    "count": "rounds", "times": "rounds", "round": "rounds",
+    "iterations": "rounds", "iteration": "rounds", "n": "rounds",
+    "duration": "time", "seconds": "time", "secs": "time", "timeout": "time",
+    "infinite": "forever", "infinity": "forever", "until_stop": "forever",
+    "while": "forever", "loop": "forever",
+}
+
+
+def _norm_loop_mode(mode):
+    """返回 (规范化后的 loop_mode, 原始值或 None)。"""
+    if mode in LOOP_MODES:
+        return mode, None
+    m = str(mode or "").strip().lower()
+    if m in _LOOP_MODE_ALIAS:
+        return _LOOP_MODE_ALIAS[m], mode
+    return "rounds", mode if mode is not None else None
+
+
+def _check_direction(params, here, errors):
+    d = params.get("direction", "up")
+    if d not in DIRECTIONS:
+        errors.append(f"{here}.params.direction: 必须是 "
+                      f"{'/'.join(DIRECTIONS)} 之一（当前 {d!r}）")
+
+
+def _check_destructive(step, here, warnings):
+    """有副作用的步骤给 warning（不拦）：让人知道哪里需要复核。"""
+    text = " ".join(str(step.get(f) or "") for f in ("label",))
+    text += " " + str((step.get("params") or {}).get("selector_value") or "")
+    text += " " + str((step.get("params") or {}).get("texts") or "")
+    hits = [w for w in DESTRUCTIVE_HINTS if w in text]
+    if not hits:
+        return
+    tags = "、".join(hits)
+    # 有副作用的动作默认调低触发概率（安全默认值，编辑器里可改回）：
+    # 探索期本来就不许真做这类动作（只核对元素存在），产物更不该一上来就每次都触发
+    params = step.setdefault("params", {})
+    prob = params.get("probability", 100)
+    if _is_num(prob) and prob > SAFE_PROBABILITY:
+        params["probability"] = SAFE_PROBABILITY
+        warnings.append(f"{here}: 含「{tags}」类有副作用的操作，触发概率已从 {prob}% "
+                        f"降到 {SAFE_PROBABILITY}% —— 核对无误后可在步骤编辑器里改回")
+    else:
+        warnings.append(f"{here}: 含「{tags}」类有副作用的操作，"
+                        "请人工复核后再启用")
+
+
+# ================== draft 整体 ==================
+
+def validate_draft(draft, groups=None, pool=None, default_serial="", overrides=None):
+    """校验并归一化 AI 提交的任务草稿。
+
+    draft      —— 模型提交的原始对象
+    groups     —— 现有分组名集合（校验 target.mode=group 时用；None=不校验）
+    pool       —— 设备池 serial 集合（用于给"设备不在池"的 warning；None=不校验）
+    default_serial —— 本次探索用的设备（target 缺省时兜底）
+    overrides  —— 页面上的"任务设置"覆盖项（用户在页面上填的优先）
+
+    → {"ok", "errors", "warnings", "draft"}
+    """
+    errors, warnings = [], []
+    if not isinstance(draft, dict):
+        return {"ok": False, "errors": ["draft 必须是对象"], "warnings": [],
+                "draft": None}
+
+    # ---- summary ----
+    summary = str(draft.get("summary") or "").strip()
+    if not summary:
+        errors.append("summary: 不能为空 —— 用一句话说明这条任务做什么")
+    elif len(summary) > 200:
+        summary = summary[:200]
+
+    # ---- task ----
+    task = draft.get("task")
+    if not isinstance(task, dict):
+        errors.append("task: 缺少任务对象")
+        task = {}
+    task = _normalize_task(task, summary, default_serial, overrides or {},
+                           errors, warnings)
+
+    types = _step_types()
+    steps = ((task.get("params") or {}).get("steps")) or []
+    if not steps:
+        errors.append("task.params.steps: 不能为空 —— 没有步骤的任务创建后"
+                      "每次运行都会报错")
+    else:
+        validate_steps(steps, 1, "task.params.steps", errors, warnings, types)
+
+    _check_target(task, groups, pool, errors, warnings)
+    _check_schedule(task, errors, warnings)
+
+    return {"ok": not errors, "errors": errors, "warnings": warnings,
+            "draft": {"summary": summary, "task": task,
+                      "notes": [str(n) for n in (draft.get("notes") or [])][:5],
+                      "evidence": list(draft.get("evidence") or [])[:10]}}
+
+
+def _normalize_task(task, summary, default_serial, overrides, errors, warnings):
+    """补齐缺失字段（缺什么补什么，但**不掩盖**该报错的必填项）。"""
+    name = str(overrides.get("name") or task.get("name") or "").strip()
+    if not name:
+        name = (summary[:20] or "AI 任务").strip()
+    task["name"] = name[:40]
+
+    task_type = task.get("task_type") or "generic_steps"
+    if task_type != "generic_steps":
+        errors.append(f"task.task_type: 目前只支持 generic_steps（收到 {task_type!r}）")
+    task["task_type"] = "generic_steps"
+
+    target = task.get("target")
+    if not isinstance(target, dict) or not target.get("mode"):
+        target = {"mode": "serial", "serial": default_serial} if default_serial \
+            else {"mode": "all"}
+        warnings.append(f"task.target: 未指定，已按探索设备兜底为 {target}")
+    # 页面上显式选了目标就以页面为准
+    ov_mode = overrides.get("target_mode")
+    if ov_mode in TARGET_MODES:
+        target = {"mode": ov_mode}
+        if ov_mode == "group":
+            target["group_name"] = overrides.get("group_name") or ""
+        elif ov_mode == "serial":
+            target["serial"] = overrides.get("serial") or default_serial
+    task["target"] = target
+
+    schedule = task.get("schedule")
+    if not isinstance(schedule, dict) or not schedule.get("mode"):
+        schedule = {"mode": "once"}
+    if overrides.get("schedule"):
+        schedule = overrides["schedule"]
+    task["schedule"] = schedule
+
+    retry = task.get("retry")
+    if not isinstance(retry, dict):
+        retry = {}
+    attempts = retry.get("max_attempts", 1)
+    delay = retry.get("delay", 60)
+    if not _is_num(attempts) or not (1 <= attempts <= 10):
+        warnings.append(f"task.retry.max_attempts: 应为 1~10，已改为 1（原 {attempts!r}）")
+        attempts = 1
+    if not _is_num(delay) or not (10 <= delay <= 3600):
+        warnings.append(f"task.retry.delay: 应为 10~3600 秒，已改为 60（原 {delay!r}）")
+        delay = 60
+    task["retry"] = {"max_attempts": int(attempts), "delay": int(delay)}
+    task["enabled"] = bool(task.get("enabled", True))
+
+    params = task.get("params")
+    if not isinstance(params, dict):
+        params = {}
+    dur = overrides.get("max_duration", params.get("max_duration", 0))
+    if not _is_num(dur) or dur < 0 or dur > 604800:
+        errors.append(f"task.params.max_duration: 必须是 0~604800 的秒数"
+                      f"（当前 {dur!r}）")
+        dur = 0
+    params["max_duration"] = int(dur)
+    # 步骤里的 id 由编辑器生成，落库前不需要（保留会让前端 id 重复）
+    if isinstance(params.get("steps"), list):
+        _strip_ids(params["steps"])
+    task["params"] = params
+    return task
+
+
+def _strip_ids(steps):
+    for s in steps:
+        if isinstance(s, dict):
+            s.pop("id", None)
+            p = s.get("params")
+            if isinstance(p, dict):
+                for key in ("children", "then", "else"):
+                    if isinstance(p.get(key), list):
+                        _strip_ids(p[key])
+
+
+def _check_target(task, groups, pool, errors, warnings):
+    target = task.get("target") or {}
+    mode = target.get("mode")
+    if mode not in TARGET_MODES:
+        errors.append(f"task.target.mode: 必须是 {'/'.join(TARGET_MODES)} 之一"
+                      f"（当前 {mode!r}）")
+        return
+    if mode == "group":
+        gname = (target.get("group_name") or "").strip()
+        if not gname:
+            errors.append("task.target.group_name: mode=group 时必须给分组名")
+        elif groups is not None and gname not in groups:
+            errors.append(f"task.target.group_name: 分组 {gname!r} 不存在"
+                          f"（现有：{'、'.join(groups) or '无'}）")
+    elif mode == "serial":
+        serial = (target.get("serial") or "").strip()
+        if not serial:
+            errors.append("task.target.serial: mode=serial 时必须给设备 serial")
+        elif pool is not None and serial not in pool:
+            warnings.append(f"task.target.serial: 设备 {serial} 不在设备池里，"
+                            "任务运行时会被跳过")
+
+
+def _check_schedule(task, errors, warnings):
+    sch = task.get("schedule") or {}
+    mode = sch.get("mode")
+    if mode not in SCHEDULE_MODES:
+        errors.append(f"task.schedule.mode: 必须是 {'/'.join(SCHEDULE_MODES)} 之一"
+                      f"（当前 {mode!r}）")
+        return
+    if mode == "once":
+        return
+    cron = sch.get("cron")
+    if not isinstance(cron, str) or not _cron_ok(cron):
+        errors.append(f"task.schedule.cron: 不是合法的 5 段 crontab（分 时 日 月 周）"
+                      f"，当前 {cron!r}")
+    if mode == "cron_stop":
+        stop = sch.get("stop_cron")
+        if not isinstance(stop, str) or not _cron_ok(stop):
+            errors.append("task.schedule.stop_cron: 定时停止必须给合法的 5 段 "
+                          f"crontab，当前 {stop!r}")
+    win = sch.get("window")
+    if isinstance(win, dict):
+        start, end = win.get("start"), win.get("end")
+        if not (_HHMM_RE.match(str(start or "")) and _HHMM_RE.match(str(end or ""))):
+            warnings.append("task.schedule.window: 时间窗应形如 {\"start\":\"09:00\","
+                            "\"end\":\"18:00\"}，格式不对会被忽略")
+        elif start == end:
+            warnings.append("task.schedule.window: 起止相同等于不限制")
+    dur = (task.get("params") or {}).get("max_duration", 0)
+    if mode == "cron_stop" and not dur:
+        warnings.append("task.params.max_duration 为 0：本任务靠定时停止结束，"
+                        "建议同时给一个运行时长上限（秒）兜底")
+
+
+def _cron_ok(expr):
+    """5 段 crontab 且能被 APScheduler 解析（任务是**静默**不注册的，必须提前拦）。"""
+    if len(str(expr).split()) != 5:
+        return False
+    try:
+        from apscheduler.triggers.cron import CronTrigger
+        CronTrigger.from_crontab(expr)
+        return True
+    except Exception:
+        return False
diff --git a/doc/AI_CONSOLE.md b/doc/AI_CONSOLE.md
index 9f28e0c..a1ace17 100644
--- a/doc/AI_CONSOLE.md
+++ b/doc/AI_CONSOLE.md
@@ -7,7 +7,14 @@
 
 ## 1. 它是什么
 
-「AI 控制台」是后台的一个顶级 Tab（仅管理员）：选一台设备，用自然语言下指令，AI 通过 MCP 工具**看屏幕、点按、输入**，边做边把过程和结论流式显示出来。
+「AI 控制台」是后台的一个顶级 Tab（仅管理员），下面有两个子分栏：
+
+| 子分栏 | 做什么 | 文档 |
+|--------|--------|------|
+| 💬 **聊天** | 选一台设备用自然语言下指令，AI 通过 MCP 工具**看屏幕、点按、输入**，边做边把过程和结论流式显示出来（本文内容） | 本文 |
+| 🧭 **AI 建任务** | 描述"要什么样的自动化"，AI **自己在真机上探索**（看屏/读元素树/点按验证），把走通的路径写成**一条可调度任务**，校验后交人工在步骤编辑器确认 | [AI_TASK_GEN.md](AI_TASK_GEN.md) |
+
+> 两个子分栏共用**同一个运行槽**（全平台同时只允许一个 Agent 运行）：建任务在探索时，聊天页会显示"● 建任务探索中"并禁用发送，反之亦然。
 
 ```
 你：「打开小红书搜索苏州好吃的饭店，把前 5 条列出来」
@@ -78,6 +85,11 @@ mcp_agent.Agent.run_stream(prompt, serial, history, on_delta, on_tool, on_usage,
 - 一轮整体超时 **900 秒**；达到步数上限会让模型做一次收尾总结
 - 工具调用由 MCP Server 执行（`:8033`），后者再调平台 HTTP 接口/直连设备
 - **设备忙时拒绝**：目标设备正在跑任务 → `409`（"AI 不与任务抢设备"）
+- `mode:"designer"`（AI 建任务）走同一条链路，差别：换一套 system prompt（任务设计师）、
+  输出上限提到 8192、**不吃聊天历史**、多一个平台级本地工具 `submit_task`
+  （不经 MCP，服务端用 `core/task_draft` 校验，见 [AI_TASK_GEN.md](AI_TASK_GEN.md)）
+- 工具结果必须是**连续的** tool 消息：一轮里若同时调了截图与别的工具，图像会攒到本轮工具
+  消息发完后再作为一条 user 消息附上（否则模型侧会以"工具回应不足"报 400）
 
 ### 3.2 会话消息模型
 
@@ -99,7 +111,7 @@ mcp_agent.Agent.run_stream(prompt, serial, history, on_delta, on_tool, on_usage,
 | `delta` | `{"text","kind":"content"\|"reasoning"}` | 正文增量渲染 Markdown；推理增量进入可折叠「💭 思考过程」 |
 | `step` | `{"tool","args","image"?}` | 追加工具卡片（含缩略截图，点击放大）；伪卡片提示经验/动作命中与沉淀 |
 | `usage` | `{"prompt_tokens","completion_tokens","total_tokens","calls"}` | 刷新单条消息脚注与顶栏「本会话累计」 |
-| `done` | `{"answer","usage"}` | 最终答案 + 收尾 |
+| `done` | `{"answer","usage","mode","draft"?,"warnings"?,"draft_error"?}` | 最终答案 + 收尾；`mode=designer` 时带任务草稿（或草稿被拦的原因） |
 | `error` | `{"message"}` | 展示错误（MCP 不可达等已转成明确文案） |
 
 **刷新/重连不丢进度**：服务端事件队列保留积压，页面重新订阅（`GET /api/agent/stream?run_id=`）后会补发 delta/step/usage/done；`EventSource.onerror` **刻意不结束运行**，靠自动重连续上。另外 `GET /api/agent/run` 提供状态快照（其他窗口/8s 轮询用）。
@@ -191,8 +203,10 @@ mcp_agent.Agent.run_stream(prompt, serial, history, on_delta, on_tool, on_usage,
 | `agent_api_key` | API Key（**明文存库**） | — |
 | `agent_default_serial` | 默认目标设备 | 空 |
 | `agent_max_steps` | 最大步数（钳制 1-200） | 40 |
+| `agent_task_draft` | **AI 建任务**最近一份草稿（JSON：`{draft, warnings, prompt, created}`，只留最近一份；不是任务，入库仍走人工确认） | 空 |
 
-其它常量：单轮超时 900s、推理链落库上限 6000 字符、会话消息上限 60 条、历史上下文取最近 12 轮。
+其它常量：单轮超时 900s、推理链落库上限 6000 字符、会话消息上限 60 条、历史上下文取最近 12 轮；
+建任务模式（designer）输出上限 8192、单工具调用上限 40 次（`mcp_agent/agent.py`）。
 
 ---
 
diff --git a/doc/AI_TASK_GEN.md b/doc/AI_TASK_GEN.md
index 49bfe97..22716a6 100644
--- a/doc/AI_TASK_GEN.md
+++ b/doc/AI_TASK_GEN.md
@@ -1,6 +1,7 @@
 # AI 建任务（AI Task Generator）设计文档
 
-> 状态：**设计稿，尚未实现**（P0 未开工）——本文描述的是「要做什么、为什么这么做」，不是现状。
+> 状态：**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 个工具）。
 > 关联代码：`web/agent_api.py`、`mcp_server/`、`mcp_agent/`、`tasks/generic/`、`static/admin/editor.js`。最后核对：2026-09-10。
 
@@ -181,3 +182,61 @@
 ### 9.4 分层与登记（红线）
 - 每新增/修改/删除一个 MCP 工具或平台配置：同步更新 `doc/MCP.md`（全清单）、`doc/MCP_DESIGN.md`（规格/层级），并在提交里体现——见全局「doc 同步红线」。
 - `core/task_draft.py` 是 web 校验与 MCP 校验的**唯一来源**，杜绝两套规则漂移。
+
+---
+
+## 10. 实现记录（2026-09-13）
+
+### 10.1 与设计稿的差异（以本节为准）
+
+| 设计稿 | 实际实现 | 为什么 |
+|---|---|---|
+| 聊天页加「模式」开关 | AI 控制台下的**独立子分栏**「🧭 AI 建任务」 | 用户要求独立页面；探索回放 + 草稿预览需要自己的版面 |
+| `submit_task` 作为平台工具（§9.2，未指定放哪层） | **Agent 本地工具**（`mcp_agent/agent.py` 的 `LOCAL_TOOL_SPECS`），**不进 MCP Server** | 放进 MCP 等于给外部客户端开"写任务"的口子，还要连带改 MCP.md/MCP_DESIGN.md 与审计；收益为零 |
+| draft 经前端灌进步骤编辑器 | 同上，但草稿**先落 `app_meta`**（`agent_task_draft`，只留最近一份） | 刷新/重进页面能拿回来；**不新建表**，绕开备份覆盖红线（SUMMARY_TABLES / DEPLOY §3.5） |
+| （未提） | designer 跑**不绑会话、不吃聊天历史**，且**不沉淀**经验/动作 | 探索轨迹里有试错与误点，沉淀会污染记忆库；"draft→经验"归到 P1 |
+| —— | 校验失败把 `errors` **原样回灌模型**，最多重提 3 次（提示词约束） | 这是"AI 写坏任务"的唯一闸门：`POST /api/jobs` 对 params 盲存、执行器又静默跳过错误步骤 |
+
+### 10.2 关键实现点
+
+- **校验器**：`core/task_draft.py`。`validate_draft()` 逐条复刻执行器的"静默跳过点"
+  （未知 type / 空 selector / 空 children / 嵌套 >5 / 深度节点数 >60 / cron 非法 /
+  必填 params 缺失 / `click_xy` 直接拒）→ 返回可被模型读懂的 `errors` + 不拦的 `warnings`。
+  `normalize_draft` 负责兜底（任务名、target、schedule、retry、时长）；页面上的任务设置
+  以 `overrides` 形式**优先**于模型给的。
+- **提示词**：`mcp_agent/agent.py` 的 `DESIGNER_SYSTEM_PROMPT`（16 条规则：先看再动、
+  定位优先级、禁坐标、禁序号型 XPath、**副作用动作只核对不真点**、时长语义映射、
+  随机化三件套、规模上限、收尾方式）。
+- **护栏**：单工具调用上限 40 次（`Agent.tool_call_limit`；总步数由 `max_steps` 兜底，
+  两个值都要**大于**正常重试次数，否则会把一轮探索截断在"改字段"上——实测踩过）；输出上限 8192（designer）；
+  `json.loads` 容错（草稿被截断时返回可读错误而不是整轮崩）。
+- **前端**：`static/admin/taskgen.js` + `#agent-sub-taskgen`（子 Tab 机制见
+  `static/admin/base.js` 的 `showSubTab`）。草稿预览能直接点「在步骤编辑器中打开」→
+  `openTaskModal(null, prefill)` 预填（用唯一 draftKey，避开 localStorage 旧草稿覆盖）。
+- **两个页面共用一个运行槽**：`GET /api/agent/run` 回 `mode`，两个前端各按 mode 决定
+  是否订阅 SSE（一个 run 只有一个事件队列，两个 EventSource 同时消费会互相瓜分事件）。
+
+### 10.3 附带修掉的一个协议 bug
+
+Chat 模式同样受益：一轮里若模型同时调了 `de_screenshot` 与别的工具，旧实现会把截图图像
+作为一条 `user` 消息**插在两条 tool 消息之间**，模型侧判定"工具回应不足"直接 400
+（`An assistant message with 'tool_calls' must be followed by tool messages…`）。
+现改为：本轮 tool 消息发完后再附一条 user 图像消息；`_repair_tool_messages` 也改成
+只数**连续**的 tool 消息。
+
+### 10.4 还没做（P1 / 后续）
+
+- 「探索完直接创建」接口（服务端复验后 `add_job`）——目前一律走人工确认。
+- draft → `agent_experience` / `agent_action` 沉淀（模板重用）。
+- MCP 侧补 `de_snapshot`（截图+元素树一次取齐，见 `doc/research/U2_ELEMENT_SELECTORS.md`）。
+- 多设备并行探索、成本控制。
+
+### 10.5 自测怎么跑
+
+1. 纯逻辑：`core/task_draft` 的正反例（未知 type / 空 selector / `click_xy` / cron 少段 /
+   深度 6 / probability 越界 …），断言 `errors` 文案模型能读懂。
+2. 真机：AI 控制台 →「AI 建任务」→ 选空闲设备 → 描述需求 → 看回放 → 核对草稿 →
+   「在步骤编辑器中打开」→ 单步试跑 → 保存。
+3. 反例：需求里出现"自动评论并发送" → 草稿的这类步骤应是"只核对存在性"（`notes` 里提示
+   人工复核），**探索期审计日志里不应有对发送键的 `de_tap_*`**。
+4. 自测产生的东西（草稿/自建任务）用后即删，别碰用户真实数据。
diff --git a/doc/API.md b/doc/API.md
index 3fa1e11..930f27a 100644
--- a/doc/API.md
+++ b/doc/API.md
@@ -198,8 +198,8 @@
 |------|------|------|
 | GET/POST | `/api/agent/config` | 读写 AI 配置（key 打码回显） |
 | GET | `/api/agent/devices` | AI 可用设备（含名称与 busy 标记） |
-| POST | `/api/agent/run` | 启动一轮 AI 会话 |
-| GET | `/api/agent/run` | 运行状态（刷新恢复用） |
+| POST | `/api/agent/run` | 启动一轮 AI 会话（`mode:"chat"`=聊天 / `"designer"`=AI 建任务） |
+| GET | `/api/agent/run` | 运行状态（刷新恢复用；含 `mode`/`draft`） |
 | GET | `/api/agent/stream` | **SSE 事件流** |
 | POST | `/api/agent/stop` | 中断当前运行 |
 | POST | `/api/agent/clear` | 清空对话历史 |
@@ -213,6 +213,21 @@
 | GET | `/api/agent/actions` | 动作库列表 |
 | POST | `/api/agent/actions/save` | 新增/编辑动作（禁坐标） |
 | 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/clear` | 丢弃草稿 |
+
+**AI 建任务（designer 模式）要点**（详见 [AI_TASK_GEN.md](AI_TASK_GEN.md)）：
+
+- `POST /api/agent/run` 额外接受 `mode:"designer"` 与 `settings`（页面上的任务设置，作为草稿
+  的 overrides：`name`/`target_mode`/`group_name`/`serial`/`schedule`/`max_duration`）。
+  designer 跑**不绑会话**（单轮，不吃聊天历史、也不污染会话）。
+- designer 模式下 Agent 多一个**平台级本地工具** `submit_task(draft)`（**不在 MCP 层**）：
+  服务端用 `core/task_draft.validate_draft` 校验，失败把 `errors` 回灌给模型让它改；
+  通过也只**暂存**（运行态 + `app_meta.agent_task_draft`），**不落库**——入库仍要用户在
+  步骤编辑器里确认后走 `POST /api/jobs`。
+- `done` 事件在 designer 下多带 `{mode, draft, warnings, draft_error}`。
+- 设备忙 409、单实例运行、权限同聊天模式。
 
 ### 2.10 system（`web/system_api.py`，全部 Admin）
 
diff --git a/doc/ARCHITECTURE.md b/doc/ARCHITECTURE.md
index 6541492..1feeb16 100644
--- a/doc/ARCHITECTURE.md
+++ b/doc/ARCHITECTURE.md
@@ -294,7 +294,8 @@ connecting ──获取设备──▶ u2 连接 ──▶ running ──▶ set
 | `tools.js` | 工具 Tab：剪贴板、adb 终端、Tailscale、设备池、自动发现、远程看屏 | |
 | `apps.js` | 应用管理：APK 上传/安装/删除、设备已装应用 | |
 | `admin.js` | 分组、日志、用户 + **全局初始化入口**（末尾 `initCsrf(); loadMe(); showTab('monitor')`） | |
-| `agent.js` | AI 控制台：会话、SSE 流、Markdown / 推理链 / token 渲染、实时画面、经验库 / 动作库 | |
+| `agent.js` | AI 控制台·聊天：会话、SSE 流、Markdown / 推理链 / token 渲染、实时画面、经验库 / 动作库 | |
+| `taskgen.js` | AI 控制台·**AI 建任务**子页：发起探索、回放工具卡、草稿预览（步骤树/提醒/证据）、打开步骤编辑器预填 | 运行槽与聊天共用，按 `mode` 互斥订阅事件流 |
 | `system.js` | 系统 Tab：备份导出 / 导入预览与应用 | |
 
 加载顺序见根 [README](../README.md)；都是全局脚本（非 ES module），靠加载顺序保证依赖。
diff --git a/doc/DATA_MODEL.md b/doc/DATA_MODEL.md
index 66ca311..4e99e47 100644
--- a/doc/DATA_MODEL.md
+++ b/doc/DATA_MODEL.md
@@ -228,6 +228,7 @@ UTF-8 等价于字节序）。
 | `agent_api_key` | API Key（**明文存库**） | 同上 |
 | `agent_default_serial` | 默认目标设备 | 同上 |
 | `agent_max_steps` | 最大步数（钳制 1-200，默认 40） | 同上 |
+| `agent_task_draft` | **AI 建任务**最近一份任务草稿（JSON `{draft,warnings,prompt,created}`，只留最近一份、超限自动瘦身）。**不是任务**：入库仍要用户在步骤编辑器确认后走 `POST /api/jobs` | AI 建任务页 / `submit_task` 工具 |
 | `discovery_enabled` | 自动发现开关（`"1"`/`"0"`） | 工具页「设备池管理」 |
 | `discovery_subnets` | 扫描网段 JSON 数组 | 同上 |
 | `discovery_interval` | 扫描周期秒（10-3600） | 同上 |
diff --git a/doc/DEVELOPMENT.md b/doc/DEVELOPMENT.md
index fd4f3bc..23f7239 100644
--- a/doc/DEVELOPMENT.md
+++ b/doc/DEVELOPMENT.md
@@ -97,6 +97,7 @@ MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<密码> \
 | 前端验证 | 无 npm/构建，改完强刷；浏览器控制台看报错 |
 | 接口 500 巡检 | `python scripts/regression_test.py`（**⚠️ 当前在 Windows 上会因 `signal.alarm` 报错**，Linux/macOS 可用） |
 | 停止设备/清异常 | 监控页「停止全部 / 停止选中 / 清除全部异常」 |
+| 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` 清掉。**注意它会真在设备上点按**（导航类动作），且与聊天共用同一个运行槽 |
 
 > **改了数据库/配置想复原**：删 `data/users.db*` 会丢数据，别这么干；用「系统 → 备份/导入」或先手工复制一份 `data/`。
 
diff --git a/doc/README.md b/doc/README.md
index de7e852..5628d03 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -17,7 +17,7 @@
 | [MCP.md](MCP.md) | **MCP 手机控制手册**：19 个 `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 建任务**：设计稿与里程碑（P0 未实现，属规划） | 平台开发者 |
+| [AI_TASK_GEN.md](AI_TASK_GEN.md) | **AI 建任务**：AI 自己在真机探索 → 写出可调度任务 → 人工确认入库（P0 已实现；契约与红线） | 平台开发者、使用者 |
 | [DEVICE_AGENT.md](DEVICE_AGENT.md) | **设备端 Agent 接口契约**：应用商店的设备专用接口（清单/下载/上报）、adb 指令协议、版本约定 —— 与设备端 APK 仓库共享的契约 | 设备端开发者、平台开发者 |
 | [DEPLOY.md](DEPLOY.md) | **部署与运维**：环境准备、生产容器、数据备份导出/导入、故障排查 | 运维、部署者 |
 | [DEVELOPMENT.md](DEVELOPMENT.md) | **开发手册**：git 流程、技术红线、本地开发与调试、常见开发任务、文档同步约定 | 所有开发者 |
diff --git a/doc/backlog/TODO.md b/doc/backlog/TODO.md
index 8bc1907..6dd8349 100644
--- a/doc/backlog/TODO.md
+++ b/doc/backlog/TODO.md
@@ -96,7 +96,8 @@
 ## D. AI 控制台 / 经验与动作
 
 - [ ] 「🧠 经验库 / 🎬 动作库」合为一个面板（标签页切换）。
-- [ ] AI 建任务 P0：平台级 MCP 工具（只读清单 `task_types/groups/pool` + `submit_task(draft)` 校验）+ 把**动作库**当作 generic_steps 的预制件复用（见 [AI_TASK_GEN.md](../AI_TASK_GEN.md) §9）。
+- [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→经验/动作沉淀、「探索完直接创建」接口。
 - [ ] 新增 MCP `de_screen_text`（文本化看屏：前台包名 + screen_state + 可点元素文本 + OCR），并把操作纪律写进工具 description。
 - [ ] 经验召回改进：现为 bigram + `ORDER BY hits`（候选只看 top50、hits 对所有命中行回写 → 马太效应）；改为对称相似度 / 更合理候选集，`hits` 仅在真正注入时 +1。
 - [ ] 经验/动作入库依赖模型蒸馏成功：加失败重试与可视化观测（现在只在日志里）。
diff --git a/mcp_agent/agent.py b/mcp_agent/agent.py
index 8951bc4..8373d9a 100644
--- a/mcp_agent/agent.py
+++ b/mcp_agent/agent.py
@@ -25,10 +25,16 @@ _log = logging.getLogger("agent")
 S = AgentSettings()
 
 
+# 模型单次回复的长度上限。建任务模式要一次性输出整份任务 JSON（几十个步骤），
+# 4096 很容易被截断 → 工具参数变成半截 JSON（见 _execute_tool 的容错）。
+_DEFAULT_MAX_TOKENS = 4096
+_DESIGNER_MAX_TOKENS = 8192
+
+
 class _UsageUnsupported(RuntimeError):
     """模型/网关不认 stream_options.include_usage（400/422 或报错点名该字段）——降级重试用。"""
 
-SYSTEM_PROMPT = """你是手机自动化控制助手。你通过工具实时操作 Android 手机。
+CHAT_SYSTEM_PROMPT = """你是手机自动化控制助手。你通过工具实时操作 Android 手机。
 
 工作规范：
 1. 先 de_list_devices 确定目标设备（在线才可操作）；设备有 name（名称）与 serial（地址），
@@ -54,6 +60,103 @@ SYSTEM_PROMPT = """你是手机自动化控制助手。你通过工具实时操
 
 可用工具清单将由系统提供。"""
 
+# 兼容旧名（CLI / 其它调用方仍可能 import SYSTEM_PROMPT）
+SYSTEM_PROMPT = CHAT_SYSTEM_PROMPT
+
+
+# ================== 建任务模式（designer）==================
+# 与聊天模式的根本区别：**产出物是一条任务，不是"替用户做完这件事"**。
+# 所以它要"看懂了就写下来"，而不是"一路点到底"；有副作用的动作只许核对、不许真做。
+DESIGNER_SYSTEM_PROMPT = """你是手机自动化**任务设计师**。你的产出物是**一条可调度、可在步骤编辑器里继续修改的任务**（不是替用户把这件事做完）。
+
+工作方式：在真机上探索够用即止 → 把探索到的元素与操作写成任务步骤 → 调 submit_task 提交草稿 → 人工确认后才会真正入库执行。
+
+## 探索规范
+1. 只用本次指定的设备 serial；给用户汇报时用设备名。设备离线/异常/被任务占用时**立即停止并说明**，不要硬试。
+2. **先看再动**：`de_screenshot` 看屏 → `de_ui_tree(limit=80~150)` 拿元素（字段只有 text/id/desc/class/clickable/bounds，**没有 xpath**）。同一屏只 dump 一次，不要反复截图。
+3. 不知道包名先 `de_list_apps(keyword=…)`，再 `de_open_app(package)`；用 `de_foreground_app` 确认前台。
+4. **定位优先级**：`text` / `description` / `resourceId` > `xpath` > 坐标。**禁止坐标**（绝不产 `click_xy`）。
+   包含匹配只能 `descriptionContains`，或 `xpath` 里的 `//*[contains(@text,"…")]`（没有 textContains 这个类型）。
+5. XPath 写法：`//*[@resource-id="包名:id/xxx"]`、`//*[@text="…"]`、`//*[@text="…" and @resource-id="…"]`。
+   **禁止** `//*[@id="x"][3]` 这种位置谓词（那是"父节点内第 3 个"，同类元素一多就全失配）。
+6. 验证分两档：
+   - **无害导航类**（tab、返回、搜索框、列表项、设置项）→ 可以 `de_tap_element` 真点一次确认能命中，记 `evidence.verified="tapped"`；
+   - **有副作用类**（点赞/关注/评论/发送/转发/购买/删除/退出登录）→ **只核对元素存在**（`verified="present"`），**绝不真点**；写进任务时 `probability ≤ 30`，并在 `notes` 里写明"请人工复核"。
+7. 没验证命中的元素**一律不写进任务**；拿不准的进 `notes`。宁可少写一步，也不要编一个选择器。
+
+## 步骤规范
+8. 只能用这 18 种步骤类型：open_app / stop_app / screen_on / screen_off / keep_screen / key_event / swipe / swipe_until / click / long_click / wait_el / input_text / clipboard / wait / loop / group / if_el（click_xy 禁用）。
+9. 输入文字必须"先 click 输入框，再 input_text"；滚动用 `swipe{direction}`，不用像素。
+10. 时长语义必须映射对：
+    - "跑 2 小时" → `params.max_duration = 7200` + 一个顶层 `loop{loop_mode:"forever"}`；
+    - "每天 8-9 点" → `schedule{mode:"cron_stop", cron:"0 8 * * *", stop_cron:"0 9 * * *"}`；
+    - **长任务必须给 max_duration**，否则等于无限跑。
+11. 随机化三件套：随机等待 `wait{min,max}`、随机文案 `input_text{mode:"random",texts:"a\\nb"}`、随机触发 `group{probability:<100}` 包住子步骤（概率对任何类型都生效）。
+12. 首步建议 `screen_on`（必要时 `keep_screen{mode:"on"}`）；**末步用 `key_event{key:"home"}` 把设备还给用户**（不要默认息屏）。
+13. 规模控制：工具调用 ≤ 25 步、steps ≤ 30 个节点、notes ≤ 5 条、evidence ≤ 10 条。结构要精简（去掉冗余的等待/滑动）。
+
+## 收尾
+14. 探索够了就调 `submit_task` 提交草稿。**校验失败时按返回的 errors 逐条修正后重提（最多 3 次）**，不要重复提交同一份草稿。
+15. 提交成功后**不要再调用任何工具**，用一句中文总结："建了什么任务、哪些步骤需要人工复核"。
+16. 若 system 里注入了"可复用动作"，优先复用其中的定位，跳过重复探索。
+
+可用工具清单将由系统提供。"""
+
+
+# 平台级（本地）工具：不经 MCP server，由 Agent 直接分派到调用方注册的 handler。
+# 为什么不放进 mcp_server：这些工具要读写平台自身的任务/草稿（依赖 Flask app context 与
+# 平台权限模型），放进 MCP 层等于给外部客户端开一个写任务的后门，且要连带改
+# MCP.md/MCP_DESIGN.md 与审计——收益为零（见 doc/AI_TASK_GEN.md §9.2）。
+LOCAL_TOOL_SPECS = {
+    "submit_task": {
+        "name": "submit_task",
+        "description": "提交任务草稿（**结束性调用**：提交成功后就不要再调任何工具，直接总结）。"
+                       "服务端会校验草稿（步骤类型/必填参数/嵌套深度/调度格式），"
+                       "校验失败返回 errors 数组，请逐条修正后重新调用本工具。"
+                       "常见被打回的原因：步骤缺 selector_value；loop 的 loop_mode 不是 "
+                       "rounds/time/forever（别写 count）；按时间循环缺 loop_duration；"
+                       "cron 不是 5 段；steps 为空。提交前请自己先按这些自查一遍。",
+        "parameters": {
+        "type": "object",
+        "properties": {
+            "summary": {"type": "string",
+                        "description": "一句话说明这条任务做什么（≤200 字）"},
+            "task": {
+                "type": "object",
+                "description": "任务信封，字段同平台任务：name/target/schedule/retry/enabled/params",
+                "properties": {
+                    "name": {"type": "string", "description": "任务名（≤40 字）"},
+                    "target": {"type": "object",
+                               "description": '{"mode":"all"|"group"|"serial", "serial":"…", "group_name":"…"}'},
+                    "schedule": {"type": "object",
+                                 "description": '{"mode":"once"} 或 {"mode":"cron","cron":"分 时 日 月 周"} 或 {"mode":"cron_stop","cron":"…","stop_cron":"…"}'},
+                    "retry": {"type": "object",
+                              "description": '{"max_attempts":1-10,"delay":10-3600}'},
+                    "enabled": {"type": "boolean"},
+                    "params": {
+                        "type": "object",
+                        "properties": {
+                            "max_duration": {"type": "integer",
+                                             "description": "单次运行时长上限（秒），0=不限时"},
+                            "steps": {"type": "array",
+                                      "description": "步骤树：[{type,label,params}]，容器用 params.children / params.then / params.else",
+                                      "items": {"type": "object"}},
+                        },
+                        "required": ["steps"],
+                    },
+                },
+                "required": ["params"],
+            },
+            "notes": {"type": "array", "items": {"type": "string"},
+                      "description": "需要人工复核/拿不准的点（≤5 条）"},
+            "evidence": {"type": "array", "items": {"type": "object"},
+                         "description": "每个选择器的探索依据：{screen,element,selector_type,selector_value,verified}"},
+        },
+        "required": ["summary", "task"],
+        },
+    },
+}
+
 
 class Agent:
     def __init__(self, settings: AgentSettings = None):
@@ -73,6 +176,32 @@ class Agent:
                       "total_tokens": 0, "calls": 0}
         self._include_usage = True   # 模型不认 stream_options 时自动置 False
         self._mcp = None
+        # ---- 建任务模式（designer）相关 ----
+        self.mode = "chat"
+        # 平台级本地工具：{名字: async handler(args) -> dict}，不走 MCP
+        self._local_handlers = {}
+        # 本轮每个工具调用了几次（防"原地打转"：同一个工具反复调不推进目标）
+        self._tool_counts = {}
+        # 单个工具本轮最多调用次数（防"原地打转"）。要**大于**正常重试次数：
+        # 探索里 submit_task 反复被校验驳回调几次是正常的，卡太死会把整轮探索截断
+        # （实测 25 时正好把一轮设计任务耗在修字段上）。总步数由 max_steps 兜底。
+        self.tool_call_limit = 40
+        self.max_tokens = None       # 模型单次回复上限（None=用 _DEFAULT_MAX_TOKENS）
+
+    # ---------- 本地（平台级）工具 ----------
+    def register_local_tool(self, name, handler):
+        """注册平台级本地工具。**必须在 `_load_tools()` 之前调用**（schema 在加载时组装）。
+
+        handler: `async def(args: dict) -> dict`，返回值会作为工具结果回给模型并推给前端。
+        """
+        if name not in LOCAL_TOOL_SPECS:
+            raise KeyError(f"未定义的本地工具: {name}（需先在 LOCAL_TOOL_SPECS 里声明 schema）")
+        self._local_handlers[name] = handler
+
+    def _count_tool_call(self, name):
+        n = self._tool_counts.get(name, 0) + 1
+        self._tool_counts[name] = n
+        return n
 
     # ---------- MCP 工具桥 ----------
     async def _load_tools(self):
@@ -91,6 +220,12 @@ class Agent:
                 "type": "function",
                 "function": {"name": name, "description": desc,
                              "parameters": schema}})
+        # 平台级本地工具（如 submit_task）随 MCP 工具一起暴露给模型，
+        # 执行时由 _execute_tool 本地分派（不发给 MCP server）
+        for name in self._local_handlers:
+            spec = LOCAL_TOOL_SPECS.get(name)
+            if spec:
+                self.tools_schema.append({"type": "function", "function": spec})
         _log.info("MCP 工具已加载: %s", [s["function"]["name"] for s in self.tools_schema])
 
     async def close(self):
@@ -123,7 +258,7 @@ class Agent:
             "model": self.s.model,
             "messages": self.messages,
             "tools": self.tools_schema if self.tools_schema else None,
-            "max_tokens": 4096,
+            "max_tokens": self.max_tokens or _DEFAULT_MAX_TOKENS,
             "stream": True,
         }
         if with_usage:
@@ -185,9 +320,44 @@ class Agent:
 
     # ---------- 工具执行 ----------
     async def _execute_tool(self, name, arguments):
-        """执行 MCP 工具，返回 (文本结果, image_data_or_None)。"""
-        args = json.loads(arguments) if isinstance(arguments, str) else (arguments or {})
+        """执行工具（MCP 或平台级本地工具），返回 (文本结果, image_data_or_None)。"""
+        try:
+            args = json.loads(arguments) if isinstance(arguments, str) else (arguments or {})
+        except (json.JSONDecodeError, TypeError) as e:
+            # 长参数被输出长度截断时 arguments 是半截 JSON。**不能整轮报错**——
+            # 把"坏了"告诉模型，让它精简后重发（designer 的 steps 可能很长）。
+            _log.warning("工具 %s 参数不是合法 JSON: %s", name, e)
+            return {"ok": False,
+                    "error": f"参数不是合法 JSON（{e}）——常见原因是这次输出过长被截断，"
+                             "请精简要提交的内容后重新调用一次"}, None
+        if not isinstance(args, dict):
+            return {"ok": False, "error": "工具参数必须是 JSON 对象"}, None
         _log.info("执行工具 %s %s", name, args)
+
+        # 同一个工具被反复调用（原地打转）时给模型一个明确的刹车
+        if self._count_tool_call(name) > self.tool_call_limit:
+            return {"ok": False,
+                    "error": f"{name} 本轮调用次数已达上限（{self.tool_call_limit} 次），"
+                             "请换一种做法推进，或直接总结当前进展"}, None
+
+        # 平台级本地工具：不发给 MCP server
+        handler = self._local_handlers.get(name)
+        if handler is not None:
+            # 平台级工具自己会推更贴切的提示卡（📝 任务草稿 / 草稿被拦下 / 未存下），
+            # 这里**不再重复推一张工具卡**——只在 handler 意外抛异常（自己没来得及推）时补一张
+            try:
+                result = await handler(args)
+            except Exception as e:
+                _log.exception("本地工具 %s 执行失败", name)
+                result = {"ok": False, "error": f"工具执行失败: {e}"}
+                if self.on_tool:
+                    try:
+                        self.on_tool({"tool": name, "args": args,
+                                      "result": result, "image": None})
+                    except Exception:
+                        pass
+            return result, None
+
         try:
             result = await self._mcp.call_tool(name, args)
             data = getattr(result, "data", result)
@@ -216,10 +386,14 @@ class Agent:
         for i in range(len(self.messages) - 1, -1, -1):
             m = self.messages[i]
             if m.get("role") == "assistant" and m.get("tool_calls"):
-                # 统计其后 tool 消息数是否匹配
+                # 只数**紧跟着的连续** tool 消息：模型侧要求工具回应连续排列，
+                # 中间夹一条 user（如截图图像）就会被判成"回应不足"。
                 need = len(m["tool_calls"])
-                have = sum(1 for x in self.messages[i + 1:]
-                           if x.get("role") == "tool")
+                have = 0
+                for x in self.messages[i + 1:]:
+                    if x.get("role") != "tool":
+                        break
+                    have += 1
                 if have < need:
                     _log.warning("修复不完整 tool_calls 段（need=%d have=%d），回退 %d 条消息",
                                  need, have, len(self.messages) - i)
@@ -229,7 +403,8 @@ class Agent:
     # ---------- 主循环（流式） ----------
     async def run_stream(self, prompt: str, serial: str = "",
                          history=None, on_delta=None, on_tool=None,
-                         should_stop=None, extra_context=None, on_usage=None):
+                         should_stop=None, extra_context=None, on_usage=None,
+                         mode: str = "chat"):
         """流式执行一轮指令，返回最终完整文本。
 
         history：上一轮的 [{"role": "user"|"assistant", "content": 文本}] 列表，
@@ -239,16 +414,21 @@ class Agent:
         should_stop：可调用 fn() -> bool，每轮模型调用前检查（用户中断用）
         extra_context：附加文本（经验记忆注入，放在 system prompt 末尾）
         on_usage(usage)：每完成一次模型调用回调一次（累计值，见 self.usage）
+        mode：`chat`（默认，AI 控制台聊天）或 `designer`（AI 建任务：改系统提示词、
+              放宽输出长度上限、注册的本地工具生效）
 
         本轮累计 token 用量同时留在 self.usage（调用方可直接读）。
         """
         self.on_delta = on_delta
         self.on_tool = on_tool
         self.on_usage = on_usage
+        self.mode = mode
+        self.max_tokens = _DESIGNER_MAX_TOKENS if mode == "designer" else _DEFAULT_MAX_TOKENS
+        self._tool_counts = {}
         self.usage = {"prompt_tokens": 0, "completion_tokens": 0,
                       "total_tokens": 0, "calls": 0}
         target = serial or self.s.default_serial
-        sys_txt = SYSTEM_PROMPT
+        sys_txt = DESIGNER_SYSTEM_PROMPT if mode == "designer" else CHAT_SYSTEM_PROMPT
         if target:
             sys_txt += f"\n\n本次默认目标设备 serial：{target}（未指定设备时用它）。"
         if extra_context:
@@ -321,6 +501,12 @@ class Agent:
                 self.messages.append({"role": "assistant",
                                       "content": full_content,
                                       "tool_calls": tcs})
+                # 工具结果必须**连续**跟在带 tool_calls 的 assistant 消息后面：
+                # 中间插任何消息都会被模型侧判成"工具回应不足"而 400
+                # （An assistant message with 'tool_calls' must be followed by tool
+                #   messages responding to each 'tool_call_id'）。
+                # 截图图像因此先攒着，等本轮所有 tool 消息都发完，再作为一条 user 消息附上。
+                pending_images = []
                 for tc in tcs:
                     fn = tc["function"]
                     text_result, image_b64 = await self._execute_tool(
@@ -329,13 +515,15 @@ class Agent:
                         "role": "tool", "tool_call_id": tc["id"],
                         "content": json.dumps(text_result, ensure_ascii=False)[:4000]})
                     if image_b64:
-                        self.messages.append({
-                            "role": "user",
-                            "content": [{"type": "text",
-                                         "text": "这是最新屏幕截图，请基于它继续判断"},
-                                        {"type": "image_url",
-                                         "image_url": {"url":
-                                                       f"data:image/jpeg;base64,{image_b64}"}}]})
+                        pending_images.append(image_b64)
+                if pending_images:
+                    content = [{"type": "text",
+                                "text": "这是最新屏幕截图，请基于它继续判断"}]
+                    for img in pending_images:
+                        content.append({"type": "image_url",
+                                        "image_url": {"url":
+                                                      f"data:image/jpeg;base64,{img}"}})
+                    self.messages.append({"role": "user", "content": content})
                 continue
 
             # 无工具调用：本轮即最终回答
diff --git a/static/admin/agent.js b/static/admin/agent.js
index c6335e2..4d510a8 100644
--- a/static/admin/agent.js
+++ b/static/admin/agent.js
@@ -55,6 +55,9 @@ function initAgentChat(){
 function restoreRunningFlow(){
   apiGet('/api/agent/run').then(r=>{
     if(!r||!r.ok) return;
+    // 建任务模式（designer）的运行由「AI 建任务」子页订阅。这里必须让开：
+    // 服务端一个 run 只有一个事件队列，两个 EventSource 同时消费会互相瓜分事件。
+    if(r.mode === 'designer') return;
     if(r.state === 'running' && r.run_id){
       setRunning(true);
       listenStream(r.run_id);
@@ -116,14 +119,18 @@ function pollRunState(){
   apiGet('/api/agent/run').then(r=>{
     if(!r||!r.ok)return;
     const running = r.state === 'running';
-    document.getElementById('agent-running-tag').style.display = running ? 'inline' : 'none';
+    // 运行槽是全平台唯一的：建任务探索在跑时，聊天页也不能再发起（如实显示）
+    const tag = document.getElementById('agent-running-tag');
+    tag.style.display = running ? 'inline' : 'none';
+    tag.textContent = running && r.mode === 'designer' ? '● 建任务探索中' : '● 运行中';
     document.getElementById('btn-agent-stop').style.display = running ? 'inline-block' : 'none';
     const hint = document.getElementById('agent-target-hint');
     if(hint){
+      const dev = r.serial ? ' · ' + _agentTargetText(r.serial) : '';
       hint.textContent = running
-        ? ('⏳ 运行中' + (r.started ? ' ' + r.started + ' 起' : '')
-           + (r.serial ? ' · ' + _agentTargetText(r.serial) : '')
-           + '：' + (r.prompt||'').slice(0,70))
+        ? ((r.mode === 'designer' ? '⏳ AI 正在「AI 建任务」页探索设备'
+                                  : '⏳ 运行中' + (r.started ? ' ' + r.started + ' 起' : ''))
+           + dev + '：' + (r.prompt || '').slice(0, 70))
         : (document.getElementById('agent-target-select').value
            ? '将操作：' + _agentTargetText(document.getElementById('agent-target-select').value)
            : '');
diff --git a/static/admin/base.js b/static/admin/base.js
index 5bb4fd4..120dd5b 100644
--- a/static/admin/base.js
+++ b/static/admin/base.js
@@ -107,14 +107,17 @@ function showTab(name){
   if(name==='tasks'){showSubTab('tasks',_activeSubs.tasks);loadTasks();loadCustomActions();}
   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==='agent' && typeof initAgentChat==='function') initAgentChat();
+  if(name==='agent'){
+    showSubTab('agent', _activeSubs.agent||'chat');   // 聊天 / AI 建任务
+    if(typeof initAgentChat==='function') initAgentChat();
+  }
   if(name==='users')loadUsers();
   if(name==='system'){showSubTab('system',_activeSubs.system||'backup');}
 }
 
 // ================== 页内子分栏（任务/工具 通用） ==================
 // 每个带子分栏的 Tab 记住上次选中的子分栏，切走再切回来保持原位
-let _activeSubs = {tasks: 'plan', tools: 'clipboard', system: 'backup'};
+let _activeSubs = {tasks: 'plan', tools: 'clipboard', system: 'backup', agent: 'chat'};
 let _discoveryTimer = null;   // 设备自动发现 10s 轮询（仅 devpool 子分栏激活时）
 
 function showSubTab(tabId, name){
@@ -122,6 +125,7 @@ function showSubTab(tabId, name){
   const tab = document.getElementById('tab-'+tabId);
   tab.querySelectorAll('.sub-tab').forEach(b=>b.classList.toggle('active', b.dataset.sub===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(name==='groups' && typeof loadGroups==='function') loadGroups();
   if(name==='apks' && typeof loadAgentStore==='function') loadAgentStore();
   if(name==='devpool' && typeof loadDevPool==='function'){
diff --git a/static/admin/taskgen.js b/static/admin/taskgen.js
new file mode 100644
index 0000000..c0562a1
--- /dev/null
+++ b/static/admin/taskgen.js
@@ -0,0 +1,416 @@
+// ================== AI 建任务（AI 自己探索 → 写出任务步骤） ==================
+// 链路：
+//   需求 → POST /api/agent/run{mode:'designer'}
+//        → AI 用 de_* 工具在真机上探索（看屏 / 读元素树 / 点按验证）
+//        → 调平台级本地工具 submit_task 提交草稿（服务端用 core/task_draft 校验，
+//          不通过就把 errors 回灌给模型让它改）
+//        → SSE done 带草稿 → 这里预览 → 打开步骤编辑器预填 → **用户点保存才入库**
+// 设计见 doc/AI_TASK_GEN.md；契约与两条红线（AI 不直接落库、有副作用的动作不真做）在 §5。
+
+let _tgInit = false;
+let _tgStream = null;     // EventSource
+let _tgBusy = false;
+let _tgDraft = null;      // {summary, task, notes, evidence}
+let _tgWarnings = [];
+let _tgPrompt = '';       // 本次需求（回存草稿时带上）
+let _tgLiveSerial = '';
+
+// ---------------- 初始化 ----------------
+function initTaskGen(){
+  if(!_tgInit){
+    _tgInit = true;
+    const inp = document.getElementById('tg-prompt');
+    if(inp){
+      inp.addEventListener('keydown', ev=>{
+        if(ev.key==='Enter' && (ev.ctrlKey||ev.metaKey)){ ev.preventDefault(); startExplore(); }
+      });
+    }
+  }
+  tgLoadDevices();
+  tgLoadGroups();
+  tgRestore();
+}
+
+function tgExample(){
+  const inp = document.getElementById('tg-prompt');
+  if(!inp) return;
+  inp.value = '建一个跑 2 小时的任务：自动刷抖音，随机点赞（概率低一点，像真人）；'
+            + '有弹窗就关掉；评论这种拿不准的先别真发。';
+  inp.focus();
+}
+
+function tgToggleAdv(){
+  const box = document.getElementById('tg-adv');
+  const arrow = document.getElementById('tg-adv-arrow');
+  if(!box) return;
+  const show = box.style.display === 'none';
+  box.style.display = show ? 'block' : 'none';
+  if(arrow) arrow.textContent = show ? '▾' : '▸';
+}
+function tgToggleTarget(){
+  const v = (document.getElementById('tg-target')||{}).value;
+  const w = document.getElementById('tg-group-wrap');
+  if(w) w.style.display = (v==='group') ? 'block' : 'none';
+}
+function tgToggleSched(){
+  const v = (document.getElementById('tg-sched-mode')||{}).value;
+  const w = document.getElementById('tg-sched-wrap');
+  if(w) w.style.display = (v==='daily') ? 'flex' : 'none';
+}
+
+// ---------------- 设备 / 分组 ----------------
+function tgLoadDevices(){
+  apiGet('/api/agent/devices').then(r=>{
+    if(!r||!r.ok) return;
+    const sel = document.getElementById('tg-serial');
+    if(!sel) return;
+    const cur = sel.value;
+    const devs = (r.devices||[]).filter(x=>x.online);
+    // 建任务页不按 serial 形态过滤：USB 序列号与 IP:5555 都是合法的 AI 目标
+    sel.innerHTML = '<option value="">请选择设备…</option>'
+      + devs.map(d=>{
+          const label = devText(d.name, d.serial) + (d.model ? ' · ' + d.model : '')
+            + (d.busy ? ' ⛔ 任务中：' + d.task_job : '');
+          return '<option value="'+esc(d.serial)+'"' + (d.busy?' disabled':'')
+            + '>' + esc(label) + '</option>';
+        }).join('');
+    if(cur && [...sel.options].some(o=>o.value===cur)) sel.value = cur;
+  });
+}
+
+function tgLoadGroups(){
+  apiGet('/api/groups').then(r=>{
+    if(!r||!r.ok) return;
+    const sel = document.getElementById('tg-group');
+    if(!sel) return;
+    sel.innerHTML = '<option value="">选择分组…</option>'
+      + (r.groups||[]).map(g=>'<option value="'+esc(g.name)+'">'+esc(g.name)
+                              +'（'+((g.serials||[]).length)+' 台）</option>').join('');
+  });
+}
+
+// ---------------- 收集页面上的任务设置 ----------------
+// 返回 {settings, hints}：settings 是服务端 validate_draft 的 overrides（页面填的说了算），
+// hints 是要写进提示词告诉模型的自然语言（避免模型自己编一套跟页面冲突的调度）。
+function tgCollectSettings(){
+  const v = id => { const e = document.getElementById(id); return e ? (e.value||'').trim() : ''; };
+  const s = {}, hints = [];
+  if(v('tg-name')) s.name = v('tg-name');
+  const tmode = v('tg-target');
+  const serial = v('tg-serial');
+  if(tmode){ s.target_mode = tmode; s.serial = serial; }
+  if(tmode === 'group'){
+    if(!v('tg-group')){ showToast('选了「按分组」但没选分组','error'); return null; }
+    s.group_name = v('tg-group');
+  }
+  const smode = v('tg-sched-mode');
+  if(smode === 'once'){ s.schedule = {mode:'once'}; s.schedule_hint = '手动启动（不自动跑）'; }
+  if(smode === 'daily'){
+    const st = v('tg-sched-start'), sp = v('tg-sched-stop');
+    if(!st){ showToast('选了「每天定时」但没填启动时间','error'); return null; }
+    const cron = tgTimeToCron(st);
+    if(sp){
+      s.schedule = {mode:'cron_stop', cron:cron, stop_cron:tgTimeToCron(sp)};
+      s.schedule_hint = '每天 ' + st + ' 启动、' + sp + ' 停止';
+    }else{
+      s.schedule = {mode:'cron', cron:cron};
+      s.schedule_hint = '每天 ' + st + ' 启动（不自动停止）';
+    }
+  }
+  const dur = parseInt(v('tg-maxdur'), 10);
+  if(dur > 0){ s.max_duration = dur; }
+  return {settings: s, hints: hints};
+}
+
+// "20:30" → "30 20 * * *"（每天）
+function tgTimeToCron(hhmm){
+  const m = String(hhmm||'').match(/^(\d{1,2}):(\d{2})$/);
+  if(!m) return '';
+  return parseInt(m[2],10) + ' ' + parseInt(m[1],10) + ' * * *';
+}
+
+// ---------------- 发起探索 ----------------
+function startExplore(){
+  if(_tgBusy) return;
+  const prompt = ((document.getElementById('tg-prompt')||{}).value||'').trim();
+  if(!prompt){ showToast('先说说要做什么','error'); return; }
+  const serial = ((document.getElementById('tg-serial')||{}).value||'').trim();
+  if(!serial){ showToast('请选择一台设备（AI 只操作你选定的设备）','error'); return; }
+  const cfg = tgCollectSettings();
+  if(!cfg) return;
+  _tgPrompt = prompt;
+  _tgDraft = null; _tgWarnings = [];
+  document.getElementById('tg-stream').innerHTML = '';
+  document.getElementById('tg-draft').innerHTML = '';
+  tgSetBusy(true, '正在启动…');
+  apiPost('/api/agent/run', {prompt: prompt, serial: serial,
+                             mode: 'designer', settings: cfg.settings})
+    .then(r=>{
+      if(!r || !r.ok){
+        tgSetBusy(false, '');
+        showToast((r&&r.error)||'启动失败','error');
+        return;
+      }
+      tgWatch(serial);
+      listenTaskGenStream(r.run_id);
+    });
+}
+
+function stopExplore(){
+  apiPost('/api/agent/stop', {}).then(r=>{
+    showToast((r&&r.ok) ? '已请求停止' : ((r&&r.error)||'停止失败'),
+              (r&&r.ok)?'success':'error');
+  });
+}
+
+function tgSetBusy(busy, text){
+  _tgBusy = busy;
+  const b = document.getElementById('tg-start'), s = document.getElementById('tg-stop');
+  if(b) b.disabled = busy;
+  if(s) s.style.display = busy ? 'inline-block' : 'none';
+  if(text !== undefined) tgStatus(text);
+}
+function tgStatus(t){
+  const el = document.getElementById('tg-status');
+  if(el) el.textContent = t || '';
+}
+
+// ---------------- 事件流 ----------------
+function listenTaskGenStream(runId){
+  if(_tgStream) _tgStream.close();
+  const es = new EventSource('/api/agent/stream?run_id=' + runId);
+  _tgStream = es;
+  let steps = 0;
+
+  es.addEventListener('delta', ev=>{
+    let d = {}; try{ d = JSON.parse(ev.data) || {}; }catch(e){}
+    if(d.kind === 'reasoning') return;              // 推理链不铺在回放区（噪音太大）
+    if(d.text) tgStatus('AI 思考中… ' + String(d.text).replace(/\s+/g,' ').slice(-60));
+  });
+
+  es.addEventListener('usage', ev=>{
+    let d = {}; try{ d = JSON.parse(ev.data) || {}; }catch(e){}
+    tgToken(d);
+  });
+
+  es.addEventListener('step', ev=>{
+    let d = {}; try{ d = JSON.parse(ev.data) || {}; }catch(e){}
+    steps++;
+    tgFollow(d.args);
+    tgAddCard(d.tool, d.args, d.image, d.error);
+    tgStatus('已执行 ' + steps + ' 步…');
+  });
+
+  es.addEventListener('done', ev=>{
+    let d = {}; try{ d = JSON.parse(ev.data) || {}; }catch(e){}
+    tgSetBusy(false, '');
+    if(d.draft){
+      _tgDraft = d.draft; _tgWarnings = d.warnings || [];
+      tgRenderDraft();
+      tgStatus('探索完成，共 ' + steps + ' 步。请核对草稿后创建任务。');
+    }else{
+      tgStatus(steps ? ('探索结束（' + steps + ' 步），但没有产出草稿。')
+                     : '没有什么可做的，AI 没给出草稿。');
+      tgAddCard('⚠ 未产出草稿',
+                (d.draft_error || 'AI 没有提交任务草稿 —— 可能是需求太模糊，或设备/App 不可用。'
+                 + ' 可以补一句更具体的要求再试。'));
+    }
+    endTaskGenStream();
+  });
+
+  es.addEventListener('error', ev=>{
+    let msg = '连接中断';
+    try{ if(ev.data) msg = (JSON.parse(ev.data)||{}).message || msg; }catch(e){}
+    tgSetBusy(false, '');
+    tgAddCard('⚠ 出错', msg);
+    endTaskGenStream();
+  });
+
+  es.onerror = ()=>{
+    // 与聊天页同理：不在这里收尾——断网/节流会触发 onerror，但后台仍在跑，
+    // EventSource 会自动重连，服务端队列保留积压事件。
+    if(_tgBusy && es.readyState === EventSource.CLOSED){
+      tgStatus('⚠ 实时连接中断，探索仍在后台进行；刷新页面可恢复。');
+    }
+  };
+}
+
+function endTaskGenStream(){
+  if(_tgStream){ _tgStream.close(); _tgStream = null; }
+}
+
+function tgAddCard(tool, args, image, err){
+  const box = document.getElementById('tg-stream');
+  if(!box) return;
+  const empty = box.querySelector('.agent-empty');
+  if(empty) empty.remove();
+  const card = document.createElement('div');
+  card.className = 'agent-toolcard';
+  const argsTxt = typeof args === 'string' ? args
+                  : JSON.stringify(args || {}, null, 0).slice(0, 240);
+  card.innerHTML = '<span class="dot"></span>'
+    + '<code style="color:var(--teal)">' + esc(tool||'') + '</code> '
+    + '<span class="text-muted">' + esc(argsTxt || '') + '</span>';
+  if(err){
+    const e = document.createElement('div');
+    e.className = 'tg-err';
+    e.textContent = '⚠ ' + err;
+    card.appendChild(e);
+  }
+  if(image){
+    const img = document.createElement('img');
+    img.src = 'data:image/jpeg;base64,' + image;
+    img.style.cursor = 'zoom-in';
+    img.onclick = ()=> zoomScreenshot(img);
+    card.appendChild(img);
+  }
+  box.appendChild(card);
+  box.scrollTop = box.scrollHeight;
+}
+
+function tgToken(u){
+  const el = document.getElementById('tg-token');
+  if(el && u && u.total_tokens) el.textContent = 'token ' + _fmtInt(u.total_tokens)
+                                                + '（' + (u.calls||0) + ' 次调用）';
+}
+
+// 跟随画面：AI 一动哪个设备就切哪个（复用平台 MJPEG 流）
+function tgFollow(args){
+  let a = args;
+  if(typeof args === 'string'){ try{ a = JSON.parse(args); }catch(e){ return; } }
+  if(a && a.serial) tgWatch(a.serial);
+}
+function tgWatch(serial){
+  if(!serial || serial === _tgLiveSerial) return;
+  _tgLiveSerial = serial;
+  const card = document.getElementById('tg-live-card');
+  const img = document.getElementById('tg-live-img');
+  if(!card || !img) return;
+  card.style.display = 'block';
+  img.style.display = 'block';
+  img.src = '/api/screen/stream?serial=' + encodeURIComponent(serial)
+          + '&q=80&fps=8&t=' + Date.now();
+  const s = document.getElementById('tg-live-serial');
+  if(s) s.textContent = serial;
+}
+
+// ---------------- 草稿预览 ----------------
+function tgRenderDraft(){
+  const box = document.getElementById('tg-draft');
+  if(!box) return;
+  if(!_tgDraft){ box.innerHTML = ''; return; }
+  const task = _tgDraft.task || {};
+  const steps = ((task.params||{}).steps) || [];
+  const html = []
+    .concat(['<h4>📝 ' + esc(task.name || _tgDraft.summary || '任务草稿') + '</h4>'])
+    .concat(['<div class="tg-hint">' + esc(_tgDraft.summary || '') + '</div>'])
+    .concat(['<div class="tg-hint">目标：' + esc(tgTargetText(task.target))
+             + ' ｜ 调度：' + esc(tgScheduleText(task.schedule))
+             + ' ｜ 时长上限：' + esc(String((task.params||{}).max_duration || 0)) + ' 秒</div>'])
+    .concat(['<div style="margin-top:8px">'])
+    .concat(tgRenderSteps(steps, 0))
+    .concat(['</div>']);
+  if((_tgWarnings||[]).length){
+    html.push('<div class="tg-warn"><b>⚠ ' + _tgWarnings.length + ' 处提醒（不拦，但请核对）</b>'
+      + _tgWarnings.map(w=>'<div>· ' + esc(w) + '</div>').join('') + '</div>');
+  }
+  if((_tgDraft.notes||[]).length){
+    html.push('<div class="tg-note"><b>需要人工复核</b>'
+      + _tgDraft.notes.map(n=>'<div>· ' + esc(n) + '</div>').join('') + '</div>');
+  }
+  const ev = _tgDraft.evidence || [];
+  if(ev.length){
+    html.push('<details class="tg-evidence"><summary>探索依据（' + ev.length + ' 条）</summary>'
+      + ev.map(e=>'<div>' + esc(e.screen || '') + ' · '
+                  + esc(e.selector_type || '') + '='
+                  + esc(e.selector_value || '') + ' · '
+                  + esc(e.verified || '') + '</div>').join('')
+      + '</details>');
+  }
+  html.push('<div class="tg-btns">'
+    + '<button class="btn btn-primary" onclick="openDraftInEditor()">在步骤编辑器中打开</button>'
+    + '<button class="btn" onclick="discardDraft()">丢弃草稿</button>'
+    + '</div>');
+  box.innerHTML = '<div class="tg-draft">' + html.join('') + '</div>';
+}
+
+function tgRenderSteps(steps, depth){
+  const pad = '  '.repeat(Math.min(depth, 5));
+  return (steps||[]).map(s=>{
+    const p = s.params || {};
+    const bits = [];
+    if(p.selector_value) bits.push(p.selector_type + '=' + p.selector_value);
+    if(p.package) bits.push(p.package);
+    if(p.direction) bits.push(p.direction);
+    if(p.key) bits.push(p.key);
+    if(p.min !== undefined && p.max !== undefined) bits.push(p.min + '~' + p.max + 's');
+    if(p.loop_mode) bits.push(p.loop_mode);
+    if(p.probability !== undefined && p.probability < 100) bits.push(p.probability + '%');
+    let row = '<div class="tg-step">' + esc(pad) + '<span class="t">' + esc(s.type) + '</span>'
+      + (s.label ? ' 「' + esc(s.label) + '」' : '')
+      + (bits.length ? ' <span class="p">' + esc(bits.join(' · ')) + '</span>' : '')
+      + '</div>';
+    if(Array.isArray(p.children)) row += tgRenderSteps(p.children, depth+1);
+    if(Array.isArray(p.then)) row += tgRenderSteps(p.then, depth+1);
+    if(Array.isArray(p.else)) row += tgRenderSteps(p.else, depth+1);
+    return row;
+  }).join('');
+}
+
+function tgTargetText(t){
+  t = t || {};
+  if(t.mode === 'serial') return '指定设备 ' + (t.serial || '');
+  if(t.mode === 'group') return '分组 ' + (t.group_name || '');
+  return '全部空闲设备';
+}
+function tgScheduleText(s){
+  s = s || {};
+  if(s.mode === 'cron') return '每天/定时 ' + (s.cron || '');
+  if(s.mode === 'cron_stop') return '定时 ' + (s.cron || '') + ' → 停 ' + (s.stop_cron || '');
+  return '手动（不自动启动）';
+}
+
+// ---------------- 草稿的动作 ----------------
+async function openDraftInEditor(){
+  if(!_tgDraft){ showToast('还没有草稿','error'); return; }
+  // 步骤编辑器要用到任务类型/分组/设备下拉，先确保它们已加载
+  await loadTasks();
+  openTaskModal(null, {task: _tgDraft.task, notes: _tgDraft.notes || [],
+                       warnings: _tgWarnings});
+}
+
+function discardDraft(){
+  if(!confirm('丢弃这份草稿？')) return;
+  apiPost('/api/agent/task_draft/clear', {}).then(r=>{
+    if(!r||!r.ok){ showToast((r&&r.error)||'丢弃失败','error'); return; }
+    _tgDraft = null; _tgWarnings = [];
+    document.getElementById('tg-draft').innerHTML = '';
+    tgStatus('已丢弃草稿');
+  });
+}
+
+// ---------------- 页面恢复（刷新/重进） ----------------
+function tgRestore(){
+  apiGet('/api/agent/task_draft').then(r=>{
+    if(!r||!r.ok) return;
+    // 运行中的 designer 由本页接管订阅；聊天页见 agent.js 的 mode 判断
+    if(r.running && r.mode === 'designer' && r.run_id){
+      tgSetBusy(true, '探索进行中…（刷新后已重新连接）');
+      listenTaskGenStream(r.run_id);
+      return;
+    }
+    if(r.draft){          // 运行态里就有（同一次会话内切页回来）
+      _tgDraft = r.draft; _tgWarnings = [];
+      tgRenderDraft();
+      return;
+    }
+    const saved = r.saved;
+    if(saved && saved.draft){
+      _tgDraft = saved.draft; _tgWarnings = saved.warnings || [];
+      tgRenderDraft();
+      tgStatus('已恢复 ' + (saved.created || '') + ' 的草稿（可直接创建，或重新探索）');
+      const inp = document.getElementById('tg-prompt');
+      if(inp && saved.prompt) inp.value = saved.prompt;
+    }
+  });
+}
diff --git a/static/admin/tasks.js b/static/admin/tasks.js
index bf55eed..509c39a 100644
--- a/static/admin/tasks.js
+++ b/static/admin/tasks.js
@@ -64,14 +64,35 @@ function renderTaskRow(j){
   '</tr>';
 }
 
-function openTaskModal(jobId){
+// 任务信封归一化：补齐 7 个键，避免下游无保护访问
+// （原文只对"已存在的 job"安全，AI 草稿/半成品信封会让 j.retry.max_attempts 之类直接抛错）
+function _normalizeTaskEnv(env){
+  const e=env||{}, t=e.target||{}, s=e.schedule||{}, r=e.retry||{}, p=e.params||{};
+  return {
+    name:e.name||'',
+    task_type:e.task_type||'generic_steps',
+    enabled:(e.enabled===undefined)?true:!!e.enabled,
+    target:{mode:t.mode||'all', group_name:t.group_name||'', serial:t.serial||''},
+    schedule:{mode:s.mode||'once', cron:s.cron||'', stop_cron:s.stop_cron||'',
+              window:s.window||null},
+    retry:{max_attempts:r.max_attempts||1, delay:r.delay||60},
+    params:Object.assign({}, p)
+  };
+}
+
+// openTaskModal(jobId, prefill)
+//   jobId   —— 传 id = 编辑已有任务
+//   prefill —— AI 建任务的草稿：{task, notes, warnings}（服务端已校验，这里只预填给人核对）
+function openTaskModal(jobId, prefill){
   const job=jobId?(_jobsData||[]).find(j=>j.id===jobId):null;
   const isEdit=!!job;
-  document.getElementById('modal-title').textContent=isEdit?'编辑任务':'新建任务';
+  const pf=(prefill&&prefill.task)?prefill:null;
+  document.getElementById('modal-title').textContent=
+    isEdit?'编辑任务':(pf?'AI 生成任务（请核对后保存）':'新建任务');
   // 任务编辑器含步骤编辑，加宽弹窗；关闭时在 closeModal 移除
   document.getElementById('modal-box').classList.add('wide-modal');
 
-  const j=job||{name:'',task_type:'generic_steps',enabled:true,target:{mode:'all'},params:{},schedule:{mode:'once'},retry:{max_attempts:1,delay:60}};
+  const j=_normalizeTaskEnv(job||(pf&&pf.task)||{});
   const tt=_taskTypes.map(t=>'<option value="'+t.task_type+'"'+(t.task_type===j.task_type?' selected':'')+'>'+esc(t.name)+'</option>').join('');
   const gl=_groupsList.map(g=>'<option value="'+g.name+'"'+(g.name===j.target.group_name?' selected':'')+'>'+esc(g.name)+'</option>').join('');
   const dl=_devicesList.map(x=>'<option value="'+esc(x.serial)+'"'+(x.serial===j.target.serial?' selected':'')+'>'
@@ -160,8 +181,23 @@ function openTaskModal(jobId){
       '</div>'+
     '</div>';
 
-  // 初始化步骤编辑器（generic_steps 时显示，其他隐藏）；jobId 作为草稿 key
-  _stepEditor.init(j.params&&j.params.steps?j.params.steps:[],j.params&&j.params.max_duration?j.params.max_duration:0,jobId||'');
+  // AI 草稿的提醒/复核项：贴在步骤编辑器上方，别让人漏看
+  if(pf&&((pf.notes&&pf.notes.length)||(pf.warnings&&pf.warnings.length))){
+    const se=document.getElementById('step-editor');
+    if(se) se.insertAdjacentHTML('beforebegin',
+      '<div class="tg-note" style="margin-bottom:10px"><b>AI 探索说明（请核对）</b>'
+      +(pf.notes||[]).map(n=>'<div>· '+esc(n)+'</div>').join('')
+      +((pf.warnings||[]).length
+        ? '<div style="margin-top:6px;color:#b45309"><b>校验提醒</b>'
+          +pf.warnings.map(w=>'<div>· '+esc(w)+'</div>').join('')+'</div>'
+        : '')
+      +'</div>');
+  }
+  // 初始化步骤编辑器（generic_steps 时显示，其他隐藏）；jobId 作为草稿 key。
+  // 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);
 
   document.getElementById('modal-footer').innerHTML=
     '<button class="btn" onclick="closeModal()">取消</button>'+
diff --git a/templates/admin/monitor.html b/templates/admin/monitor.html
index 75de8cb..7585a1f 100644
--- a/templates/admin/monitor.html
+++ b/templates/admin/monitor.html
@@ -352,6 +352,40 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 .agent-live-body .agent-empty{color:#4b5563;padding:20px;font-size:12px;line-height:1.8}
 .agent-shell{display:flex;flex-direction:column;height:calc(100vh - 150px);min-height:520px;border:1px solid #e5e7eb;border-radius:14px;overflow:hidden;background:#fff}
 .agent-shell{display:flex;flex-direction:column;height:calc(100vh - 150px);min-height:480px;border:1px solid #e5e7eb;border-radius:14px;overflow:hidden;background:#fff}
+/* AI 控制台里的子分栏占了一行，聊天区高度相应扣掉，避免整页出现滚动条 */
+#agent-sub-chat .agent-shell{height:calc(100vh - 205px)}
+
+/* ===== AI 建任务（子面板 2） ===== */
+.tg-wrap{display:flex;gap:14px;height:calc(100vh - 205px);min-height:500px}
+.tg-left{width:360px;flex:none;display:flex;flex-direction:column;gap:10px;overflow-y:auto;padding-right:2px}
+.tg-right{flex:1;min-width:0;display:flex;flex-direction:column;gap:10px}
+.tg-card{border:1px solid #e5e7eb;border-radius:12px;padding:12px;background:#fff}
+.tg-title{font-size:12.5px;font-weight:700;color:#374151;margin-bottom:8px}
+.tg-fold:hover{color:var(--primary)}
+.tg-row{display:flex;align-items:center;gap:8px;margin-top:8px}
+.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-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}
+.tg-stream .agent-toolcard{border-left:2px solid var(--teal);padding-left:8px;font-size:12px}
+.tg-stream .agent-toolcard img{max-width:180px;border-radius:6px;display:block;margin-top:6px}
+.tg-stream .agent-toolcard .dot{width:6px;height:6px;border-radius:99px;background:var(--teal);display:inline-block;margin-right:6px}
+.tg-stream .tg-err{color:#b91c1c;font-size:11.5px;margin-top:4px;font-family:var(--mono);word-break:break-all}
+.tg-draft-wrap{max-height:46%;overflow-y:auto}
+.tg-draft{border:1px solid #e5e7eb;border-radius:12px;background:#fff;padding:12px}
+.tg-draft h4{margin:0 0 8px;font-size:13px}
+.tg-step{font-family:var(--mono);font-size:11.5px;padding:3px 0;border-bottom:1px dashed #eef0f3;white-space:pre-wrap;word-break:break-all}
+.tg-step:last-child{border-bottom:none}
+.tg-step .t{color:#0f766e;font-weight:600}
+.tg-step .p{color:#b45309}
+.tg-note{background:#fffbeb;border:1px solid #fde68a;border-radius:8px;padding:8px 10px;font-size:11.5px;color:#92400e;margin-top:8px}
+.tg-warn{background:#fef2f2;border:1px solid #fecaca;border-radius:8px;padding:8px 10px;font-size:11.5px;color:#b91c1c;margin-top:8px}
+.tg-evidence{margin-top:8px;font-size:11px;color:var(--text-light)}
+.tg-evidence summary{cursor:pointer;font-weight:600}
+.tg-evidence div{padding:3px 0;border-bottom:1px dashed #eef0f3}
+.tg-btns{display:flex;gap:8px;margin-top:12px;flex-wrap:wrap}
 .agent-topbar{display:flex;align-items:center;justify-content:space-between;padding:10px 16px;border-bottom:1px solid #e5e7eb;background:#f9fafb}
 .agent-title{font-size:14px;font-weight:700;color:#111827}
 .agent-model-tag{margin-left:8px;font-size:11px;color:#0e7490;font-family:var(--mono);background:#e0f2fe;padding:2px 8px;border-radius:10px}
@@ -532,6 +566,13 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 <!-- ========== Tab 3: 分组 ========== -->
 <!-- ========== Tab: AI 控制台（DeepSeek 风格聊天 + 实时 MCP 步骤） ========== -->
 <div id="tab-agent" class="tab-panel">
+  <div class="sub-tabs">
+    <button class="sub-tab active" data-sub="chat" onclick="showSubTab('agent','chat')">💬 聊天</button>
+    <button class="sub-tab" data-sub="taskgen" onclick="showSubTab('agent','taskgen')">🧭 AI 建任务</button>
+  </div>
+
+  <!-- ===== 子面板 1：聊天（原有 AI 控制台，原样不动） ===== -->
+  <div class="sub-panel active" id="agent-sub-chat">
   <div class="agent-shell">
     <div class="agent-topbar">
       <div class="agent-title">🤖 AI 控制台<span id="agent-model-tag" class="agent-model-tag"></span><span id="agent-token-total" class="agent-token-total" title=""></span></div>
@@ -580,6 +621,93 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
       </div>
     </div>
   </div>
+  </div><!-- /agent-sub-chat -->
+
+  <!-- ===== 子面板 2：AI 建任务 =====
+       AI 自己在真机上探索（看屏/读元素树/点按验证），把路径写成**任务步骤**，
+       经服务端校验后交人工确认（打开步骤编辑器 → 保存才入库）。
+       见 doc/AI_TASK_GEN.md -->
+  <div class="sub-panel" id="agent-sub-taskgen">
+    <div class="tg-wrap">
+      <div class="tg-left">
+        <div class="tg-card">
+          <div class="tg-title">1️⃣ 说清楚要做什么</div>
+          <textarea id="tg-prompt" class="form-control" rows="4"
+                    placeholder="例如：建一个跑 2 小时的任务，自动刷抖音、随机点赞；拿不准的先别真发"></textarea>
+          <div class="tg-row">
+            <button class="btn btn-xs" onclick="tgExample()">用个例子</button>
+            <span class="tg-hint">AI 会自己在设备上探索，把走通的路径写成任务步骤</span>
+          </div>
+        </div>
+
+        <div class="tg-card">
+          <div class="tg-title">2️⃣ 选一台空闲设备</div>
+          <select id="tg-serial" class="form-control">
+            <option value="">加载设备…</option>
+          </select>
+          <div class="tg-hint" id="tg-serial-hint">有任务在跑的设备不可选（AI 不与任务抢设备）</div>
+        </div>
+
+        <div class="tg-card">
+          <div class="tg-title tg-fold" onclick="tgToggleAdv()">3️⃣ 任务设置（可选，留空由 AI 判断）
+            <span style="float:right" id="tg-adv-arrow">▸</span></div>
+          <div id="tg-adv" style="display:none">
+            <div class="form-group"><label>任务名</label>
+              <input id="tg-name" class="form-control" placeholder="留空=AI 自动起名"></div>
+            <div class="form-group"><label>目标设备</label>
+              <select id="tg-target" class="form-control" onchange="tgToggleTarget()">
+                <option value="">跟随探索设备</option>
+                <option value="all">全部空闲设备</option>
+                <option value="group">按分组</option>
+                <option value="serial">指定设备</option>
+              </select>
+            </div>
+            <div class="form-group" id="tg-group-wrap" style="display:none">
+              <label>分组</label><select id="tg-group" class="form-control"></select>
+            </div>
+            <div class="form-group"><label>调度</label>
+              <select id="tg-sched-mode" class="form-control" onchange="tgToggleSched()">
+                <option value="">跟随 AI 判断</option>
+                <option value="once">手动（不自动启动）</option>
+                <option value="daily">每天定时</option>
+              </select>
+            </div>
+            <div class="form-row" id="tg-sched-wrap" style="display:none">
+              <div class="form-group"><label>启动</label>
+                <input type="time" id="tg-sched-start" class="form-control" value="20:00"></div>
+              <div class="form-group"><label>停止（可留空）</label>
+                <input type="time" id="tg-sched-stop" class="form-control"></div>
+            </div>
+            <div class="form-group"><label>运行时长上限（秒）</label>
+              <input id="tg-maxdur" type="number" class="form-control"
+                     placeholder="如 7200 = 2 小时；0/留空 = 不限"></div>
+          </div>
+        </div>
+
+        <div class="tg-actions">
+          <button class="btn btn-primary" id="tg-start" onclick="startExplore()">🚀 开始探索</button>
+          <button class="btn btn-danger" id="tg-stop" style="display:none" onclick="stopExplore()">■ 停止</button>
+        </div>
+        <div class="tg-status" id="tg-status"></div>
+
+        <div class="tg-card" id="tg-live-card" style="display:none">
+          <div class="tg-title">📺 跟随画面 <span class="tg-hint" id="tg-live-serial"></span></div>
+          <img id="tg-live-img" alt="" style="width:100%;border-radius:8px;display:none">
+        </div>
+      </div>
+
+      <div class="tg-right">
+        <div class="tg-right-head">
+          <span>探索回放</span>
+          <span class="tg-hint" id="tg-token"></span>
+        </div>
+        <div class="tg-stream" id="tg-stream">
+          <div class="agent-empty">AI 在设备上的每一步（看屏 / 读元素树 / 点按验证）会实时显示在这里。</div>
+        </div>
+        <div class="tg-draft-wrap" id="tg-draft"></div>
+      </div>
+    </div>
+  </div><!-- /agent-sub-taskgen -->
 </div>
 
 <!-- ========== 配置模态框 ========== -->
@@ -1082,6 +1210,7 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
 <script src="/static/admin/apps.js"></script>
 <script src="/static/admin/admin.js"></script>
 <script src="/static/admin/agent.js"></script>
+<script src="/static/admin/taskgen.js"></script>
 <script src="/static/admin/system.js"></script>
 </body>
 </html>
diff --git a/web/agent_api.py b/web/agent_api.py
index b52d57b..dee15cf 100644
--- a/web/agent_api.py
+++ b/web/agent_api.py
@@ -43,10 +43,20 @@ _CFG_KEYS = {"api_base": "agent_api_base",
 # 推理链落库上限（字符）：只留够回看的量，避免会话消息无限膨胀
 _REASONING_KEEP = 6000
 
+# AI 建任务：草稿落库的 app_meta 键（**不新建表** —— 只存最近一份，
+# 刷新/重进页面能拿回来；见 doc/AI_TASK_GEN.md）
+_DRAFT_META_KEY = "agent_task_draft"
+# 草稿 JSON 体积上限（app_meta.value 是 TEXT）：超了截断 notes/evidence，不报错
+_DRAFT_MAX_CHARS = 60000
+
 
 # ---------- 运行状态（单实例 + 事件队列） ----------
 _run = {"id": None, "state": "idle", "prompt": "", "serial": "",
         "answer": "", "error": "", "usage": {},
+        "mode": "chat",       # chat（聊天）| designer（AI 建任务）
+        "draft": None,        # designer：submit_task 校验通过的任务草稿
+        "draft_error": "",    # designer：草稿被拦下的原因（errors 拼接）
+        "warnings": [],       # designer：草稿的提醒项（不拦，前端醒目展示）
         "history": []}   # 多轮对话历史 [{role: user|assistant, content}]
 _queues = {}            # run_id -> queue.Queue（SSE 消费者读取）
 _stop_events = {}       # run_id -> threading.Event（用户中断）
@@ -1101,13 +1111,26 @@ def agent_conversations_rename(conv_id):
 @bp.route("/api/agent/run", methods=["POST"])
 @admin_required
 def agent_run():
-    """启动 Agent：{prompt, serial?, conversation_id?}。运行中返回 409。"""
+    """启动 Agent：{prompt, serial?, conversation_id?, mode?, settings?}。运行中返回 409。
+
+    mode=chat（默认）：AI 控制台聊天（现状不变）
+    mode=designer：AI 建任务 —— 探索设备 → 用 submit_task 提交任务草稿（不落库）
+    settings：建任务页上用户填的任务设置（任务名/目标/调度），作为草稿的 overrides
+    """
     data = request.json or {}
     prompt = (data.get("prompt") or "").strip()
     if not prompt:
         return jsonify({"ok": False, "error": "请输入指令"}), 400
     serial = (data.get("serial") or "").strip()
     conv_id = (data.get("conversation_id") or "").strip()
+    mode = (data.get("mode") or "chat").strip()
+    if mode not in ("chat", "designer"):
+        return jsonify({"ok": False, "error": f"未知模式: {mode}"}), 400
+    settings = data.get("settings") if isinstance(data.get("settings"), dict) else {}
+    # 建任务模式是单轮的：不绑会话（避免把聊天历史灌进设计师上下文，
+    # 也避免探索过程污染聊天会话）
+    if mode == "designer":
+        conv_id = ""
     cfg = _read_cfg()
     if not cfg.get("api_key"):
         return jsonify({"ok": False, "error": "请先在配置区填写 API Key"}), 400
@@ -1156,15 +1179,17 @@ def agent_run():
         run_id = uuid.uuid4().hex[:8]
         from datetime import datetime as _dt
         _run.update(id=run_id, state="running", prompt=prompt,
-                    serial=serial, conv_id=conv_id,
+                    serial=serial, conv_id=conv_id, mode=mode,
                     started=_dt.now().strftime("%H:%M:%S"),
-                    answer="", error="", usage={})
+                    answer="", error="", usage={},
+                    draft=None, draft_error="", warnings=[])
         # history 保留（多轮上下文），由会话/「新建会话」管理
         _queues[run_id] = queue.Queue()
         _stop_events[run_id] = threading.Event()
-    _log.info(f"Agent 启动: {prompt[:60]} @ {serial or 'default'} conv={conv_id or '-'}")
+    _log.info(f"Agent 启动[{mode}]: {prompt[:60]} @ {serial or 'default'} "
+              f"conv={conv_id or '-'}")
     threading.Thread(target=_agent_thread,
-                     args=(run_id, prompt, serial, cfg),
+                     args=(run_id, prompt, serial, cfg, mode, settings),
                      daemon=True).start()
     return jsonify({"ok": True, "run_id": run_id})
 @bp.route("/api/agent/config", methods=["GET"])
@@ -1211,6 +1236,10 @@ def agent_run_status():
                         "answer": (_run.get("answer") or "")[:4000],
                         "error": (_run.get("error") or "")[:400],
                         "usage": _run.get("usage") or {},
+                        "mode": _run.get("mode") or "chat",
+                        "draft": _run.get("draft"),
+                        "draft_error": _run.get("draft_error") or "",
+                        "warnings": _run.get("warnings") or [],
                         "history": hist[-16:]})
 
 
@@ -1291,6 +1320,110 @@ def agent_clear():
     return jsonify({"ok": True, "msg": "已清空"})
 
 
+# ================== AI 建任务：草稿 ==================
+# 草稿只存**最近一份**（app_meta 单键），用途是"刷新/重进页面能拿回来"与审计；
+# 它不是任务 —— 真正入库仍要用户在步骤编辑器里确认后走 POST /api/jobs。
+def _load_draft_meta():
+    """读回最近一份草稿（无则 None）。"""
+    raw = _meta_get(_DRAFT_META_KEY)
+    if not raw:
+        return None
+    try:
+        obj = json.loads(raw)
+        return obj if isinstance(obj, dict) else None
+    except (json.JSONDecodeError, TypeError):
+        _log.warning("草稿 JSON 解析失败，忽略")
+        return None
+
+
+def _draft_env():
+    """校验草稿要用的环境信息：现有分组名 + 设备池（取不到就跳过对应校验）。"""
+    groups = pool = None
+    try:
+        from core import device_pool
+        from web import context
+        groups = set(context.mgr.groups.keys())
+        pool = set(device_pool.list_configured())
+    except Exception as e:
+        _log.warning(f"分组/设备池读取失败，跳过对应校验: {e}")
+    return groups, pool
+
+
+def _persist_draft(draft, warnings, prompt=""):
+    """把草稿存进 app_meta（体积超限时逐级瘦身，不报错）。"""
+    from datetime import datetime as _dt
+    saved = {"draft": draft, "warnings": list(warnings or []),
+             "prompt": (prompt or "")[:500],
+             "created": _dt.now().strftime("%Y-%m-%d %H:%M")}
+    raw = json.dumps(saved, ensure_ascii=False)
+    if len(raw) > _DRAFT_MAX_CHARS:
+        saved["draft"]["evidence"] = []
+        raw = json.dumps(saved, ensure_ascii=False)
+    if len(raw) > _DRAFT_MAX_CHARS:
+        saved["draft"]["notes"] = list(saved["draft"].get("notes") or [])[:2]
+        raw = json.dumps(saved, ensure_ascii=False)
+    if len(raw) > _DRAFT_MAX_CHARS:
+        _log.warning(f"草稿体积仍超限（{len(raw)} 字符），照原样存入")
+    _meta_put(_DRAFT_META_KEY, raw)
+    try:
+        db.session.commit()
+    except Exception:
+        db.session.rollback()
+    return saved
+
+
+@bp.route("/api/agent/task_draft")
+@admin_required
+def agent_task_draft_get():
+    """读回最近一次 AI 建任务的草稿（页面刷新/重进时恢复用）。"""
+    saved = _load_draft_meta()
+    with _lock:
+        cur = _run.get("draft")
+        st = _run.get("state")
+        mode = _run.get("mode") or "chat"
+        run_id = _run.get("id") or "" if st == "running" else ""
+    return jsonify({"ok": True, "saved": saved,
+                    "running": st == "running", "mode": mode, "run_id": run_id,
+                    "draft": cur, "draft_error": _run.get("draft_error") or ""})
+
+
+@bp.route("/api/agent/task_draft", methods=["POST"])
+@admin_required
+def agent_task_draft_save():
+    """回存一份草稿（人工在页面上改过之后）。会重新校验一次。"""
+    from core.task_draft import validate_draft
+    data = request.json or {}
+    groups, pool = _draft_env()
+    res = validate_draft(data.get("draft"), groups=groups, pool=pool,
+                         default_serial=(data.get("serial") or "").strip())
+    if not res["ok"]:
+        return jsonify({"ok": False, "error": "草稿校验未通过",
+                        "errors": res["errors"]}), 400
+    saved = _persist_draft(res["draft"], res["warnings"],
+                           prompt=data.get("prompt") or "")
+    with _lock:
+        _run["draft"] = res["draft"]
+        _run["warnings"] = res["warnings"]
+        _run["draft_error"] = ""
+    return jsonify({"ok": True, "msg": "草稿已保存", "saved": saved})
+
+
+@bp.route("/api/agent/task_draft/clear", methods=["POST"])
+@admin_required
+def agent_task_draft_clear():
+    """丢弃当前草稿。"""
+    _meta_put(_DRAFT_META_KEY, "")
+    try:
+        db.session.commit()
+    except Exception:
+        db.session.rollback()
+    with _lock:
+        _run["draft"] = None
+        _run["warnings"] = []
+        _run["draft_error"] = ""
+    return jsonify({"ok": True, "msg": "已丢弃草稿"})
+
+
 def _shrink_image(b64, width=220, quality=50):
     """截图降采样（SSE step 事件用，控制传输体积）。失败原样返回。"""
     try:
@@ -1305,9 +1438,15 @@ def _shrink_image(b64, width=220, quality=50):
         return b64
 
 
-def _agent_thread(run_id, prompt, serial, cfg):
-    """后台线程：Agent 流式执行，事件推入队列供 SSE 消费。"""
+def _agent_thread(run_id, prompt, serial, cfg, mode="chat", settings=None):
+    """后台线程：Agent 流式执行，事件推入队列供 SSE 消费。
+
+    mode=designer 时额外注册平台级工具 `submit_task`：它把 AI 探索出的任务草稿
+    交给 `core/task_draft` 校验，**通过也只暂存、不落库**（人工确认后才入库）。
+    """
     q = _queues.get(run_id)
+    settings = settings if isinstance(settings, dict) else {}
+    designer = (mode == "designer")
     try:
         # 平台进程 cwd=/app（含 mcp_agent 包），进程内 import
         sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
@@ -1339,6 +1478,12 @@ def _agent_thread(run_id, prompt, serial, cfg):
                    "args": step.get("args") or {}}
             if step.get("image"):
                 rec["image"] = _shrink_image(step["image"])
+            # 工具报错时把原因带出去：前端卡片直接显示"这步为什么失败"
+            # （模型看得到 errors，人也要看得到）
+            r = step.get("result")
+            if isinstance(r, dict) and r.get("ok") is False:
+                rec["error"] = str(r.get("error")
+                                   or "；".join(r.get("errors") or []) or "失败")[:300]
             q.put(("step", rec))
             # 记录精简工具序列 + 结构化轨迹（去 serial、结果截断）
             try:
@@ -1381,6 +1526,76 @@ def _agent_thread(run_id, prompt, serial, cfg):
                 history = list(_run.get("history") or [])
         target = serial or cfg.get("default_serial") or ""
         stop_evt = _stop_events.get(run_id)
+        if designer:
+            # 建任务模式是单轮的：不吃聊天历史（避免把聊天上下文灌进设计师）
+            with _lock:
+                _run["history"] = []
+            history = []
+
+        async def submit_task(args):
+            """平台级工具：校验 AI 提交的任务草稿。
+
+            失败 → 把 errors 原样回给模型，让它逐条修正后重提（这是"AI 写坏任务"
+            的唯一闸门：POST /api/jobs 对 params 是盲存的，执行器又静默跳过错误步骤）。
+            成功 → 只暂存在运行态 + app_meta，等用户在步骤编辑器里确认后才入库。
+            """
+            from core.task_draft import validate_draft
+
+            def _work():
+                """校验 + 暂存（读分组/设备池、写 app_meta 都要 app context）。"""
+                groups, pool = _draft_env()
+                r = validate_draft(args, groups=groups, pool=pool,
+                                   default_serial=target, overrides=settings)
+                if r["ok"]:
+                    _persist_draft(r["draft"], r["warnings"], prompt=prompt)
+                return r
+
+            try:
+                if _flask_app is not None:
+                    with _flask_app.app_context():
+                        res = _work()
+                else:
+                    res = _work()
+            except Exception as e:
+                # 后台线程里任何异常都不能冒泡成"工具执行失败"这种含糊文案——
+                # 模型与用户都需要知道草稿到底存没存下
+                _log.exception("[designer] 草稿处理失败")
+                with _lock:
+                    _run["draft_error"] = f"草稿处理失败: {e}"
+                q.put(("step", {"tool": "📝 草稿未存下",
+                                "args": f"服务端处理草稿时出错：{type(e).__name__}: {str(e)[:160]}",
+                                "image": None}))
+                return {"ok": False,
+                        "error": f"服务端处理草稿时出错（{type(e).__name__}: {e}），"
+                                 "草稿没有保存。请把 steps 精简后重试一次；"
+                                 "若仍失败，说明是平台问题，先向用户说明。"}
+            if not res["ok"]:
+                msg = "；".join(res["errors"][:6])
+                with _lock:
+                    _run["draft_error"] = msg
+                q.put(("step", {"tool": "📝 草稿被拦下",
+                                "args": f"{len(res['errors'])} 处问题需要修正：{msg}",
+                                "image": None}))
+                return {"ok": False,
+                        "error": "草稿未通过校验，请按下面的 errors 逐条修正后"
+                                 "**重新调用一次 submit_task**",
+                        "errors": res["errors"], "warnings": res["warnings"]}
+            draft = res["draft"]
+            n_steps = len(((draft.get("task") or {}).get("params") or {}).get("steps") or [])
+            with _lock:
+                _run["draft"] = draft
+                _run["warnings"] = res["warnings"]
+                _run["draft_error"] = ""
+            q.put(("step", {"tool": "📝 任务草稿",
+                            "args": f"已提交草稿「{draft['task'].get('name', '')}」："
+                                    f"{n_steps} 个顶层步骤"
+                                    + (f"，{len(res['warnings'])} 条待复核提醒"
+                                       if res["warnings"] else ""),
+                            "image": None}))
+            return {"ok": True,
+                    "msg": "草稿已收到并通过校验，已交给用户确认。请立即停止调用工具，"
+                           "用一句中文总结这条任务做什么、哪些步骤需要人工复核。",
+                    "warnings": res["warnings"]}
 
         # 经验检索：相似历史任务的操作配方注入 system（自进化记忆）
         exp_ctx, exp_items = _find_experiences(prompt)
@@ -1403,6 +1618,25 @@ def _agent_thread(run_id, prompt, serial, cfg):
         if act_ctx:
             recall_ctx += ("\n\n## 可复用动作（优先按其中的元素定位操作；"
                            "若与当前界面不符，再自行截图确认）\n" + act_ctx)
+        if designer and settings:
+            # 用户在页面上填的任务设置：必须落到 draft 里，别让模型自己编
+            hints = []
+            if settings.get("name"):
+                hints.append(f"- 任务名：{settings['name']}")
+            mode_ = settings.get("target_mode")
+            if mode_ == "group" and settings.get("group_name"):
+                hints.append(f"- 目标：分组「{settings['group_name']}」")
+            elif mode_ == "all":
+                hints.append("- 目标：全部空闲设备")
+            elif mode_ == "serial":
+                hints.append(f"- 目标：指定设备 {settings.get('serial') or target}")
+            if settings.get("schedule_hint"):
+                hints.append(f"- 调度：{settings['schedule_hint']}")
+            if settings.get("max_duration"):
+                hints.append(f"- 运行时长上限：{settings['max_duration']} 秒")
+            if hints:
+                recall_ctx += ("\n\n## 用户已指定的任务设置（必须原样写进 draft.task）\n"
+                               + "\n".join(hints))
 
         mcp_url = getattr(getattr(agent, "s", None), "mcp_url", "")
 
@@ -1417,6 +1651,9 @@ def _agent_thread(run_id, prompt, serial, cfg):
                 "network is unreachable", "connect timeout"))
 
         async def _execute():
+            # 建任务模式：先注册平台级工具（必须在 _load_tools 之前，schema 在加载时组装）
+            if designer:
+                agent.register_local_tool("submit_task", submit_task)
             try:
                 await agent._load_tools()
             except Exception as e:
@@ -1433,7 +1670,8 @@ def _agent_thread(run_id, prompt, serial, cfg):
                                               should_stop=lambda: bool(
                                                   stop_evt and stop_evt.is_set()),
                                               extra_context=recall_ctx,
-                                              on_usage=on_usage)
+                                              on_usage=on_usage,
+                                              mode=mode)
             except Exception as e:
                 if _mcp_unreachable(e):
                     raise RuntimeError(
@@ -1475,10 +1713,13 @@ def _agent_thread(run_id, prompt, serial, cfg):
             except Exception as e:
                 _log.warning(f"会话落库失败: {e}")
 
-        # 自进化：成功执行过工具则提炼配方写入经验。必须在 done 之前完成——
+        # 自进化：AI 建任务（designer）**不沉淀**——探索轨迹是为"写出一条任务"服务的，
+        # 不是一次成功操作套路；沉淀它会把探索期的误点/试错当成经验，污染记忆库。
+        # （把"草稿→经验/动作"作为独立里程碑，见 doc/AI_TASK_GEN.md §6 P1）
+        # 必须在 done 之前完成——
         # done 发出后 SSE 关流，用户就看不到「已写入经验」的提示了。
         # 提炼/保存失败静默（不阻塞、不影响结果），只在成功时推送 🧠 卡片。
-        if tool_seq:
+        if tool_seq and not designer:
             try:
                 recipe = _clean_recipe(_distill_experience(cfg, prompt, " -> ".join(tool_seq)))
                 if recipe:
@@ -1504,7 +1745,13 @@ def _agent_thread(run_id, prompt, serial, cfg):
                                     "image": None}))
             except Exception as e:
                 _log.warning(f"经验保存异常: {e}")
-        q.put(("done", {"answer": answer, "usage": usage}))
+        with _lock:
+            done_evt = {"answer": answer, "usage": usage, "mode": mode}
+            if designer:
+                done_evt["draft"] = _run.get("draft")
+                done_evt["warnings"] = _run.get("warnings") or []
+                done_evt["draft_error"] = _run.get("draft_error") or ""
+        q.put(("done", done_evt))
     except Exception as e:
         _log.warning(f"Agent 运行异常: {e}")
         # 诊断：打印消息结构（tool_calls 与 tool 消息配对检查）

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 8/9] =?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://<host>: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:<base64>,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(){
       + '</details>');
   }
   html.push('<div class="tg-btns">'
-    + '<button class="btn btn-primary" onclick="openDraftInEditor()">在步骤编辑器中打开</button>'
-    + '<button class="btn" onclick="discardDraft()">丢弃草稿</button>'
+    + '<button class="btn btn-primary" onclick="createDraft(false)" title="按草稿直接建成任务（可在任务页继续改）；不需要人工核对时用它">'
+    + '✓ 直接创建任务</button>'
+    + '<button class="btn" onclick="openDraftInEditor()" title="打开步骤编辑器预填，核对/试跑后再保存">'
+    + '在步骤编辑器中核对</button>'
+    + '<button class="btn" onclick="discardDraft()">丢弃</button>'
     + '</div>');
   box.innerHTML = '<div class="tg-draft">' + html.join('') + '</div>';
 }
@@ -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 = '<div class="tg-draft"><h4>✅ 任务已创建：' + esc(job.name||'') + '</h4>'
+        + '<div class="tg-hint">下次运行：' + esc(job.next_run || '手动触发')
+        + ' ｜ 调度：' + esc(tgScheduleText(job.schedule))
+        + ' ｜ id ' + esc(job.id||'') + '</div>'
+        + ((r.warnings||[]).length
+           ? '<div class="tg-warn">' + r.warnings.map(w=>'· ' + esc(w)).join('<br>') + '</div>'
+           : '')
+        + '<div class="tg-btns">'
+        + '<button class="btn btn-primary" onclick="showTab(\'tasks\')">去任务页看</button>'
+        + '<button class="btn" onclick="tgResetDraftView()">再探索一条</button>'
+        + '</div></div>';
+    }
+    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
           <button class="btn btn-primary" id="tg-start" onclick="startExplore()">🚀 开始探索</button>
           <button class="btn btn-danger" id="tg-stop" style="display:none" onclick="stopExplore()">■ 停止</button>
         </div>
+        <label class="tg-check" title="勾上后：探索出草稿就直接建成任务（不再等你点确认）。草稿入库前仍会再校验一次；任务建好后可在任务页编辑/停用">
+          <input type="checkbox" id="tg-auto-create">
+          <span>探索完<b>直接创建任务</b>（跳过人工核对）</span>
+        </label>
         <div class="tg-status" id="tg-status"></div>
 
         <div class="tg-card" id="tg-live-card" style="display:none">
diff --git a/web/agent_api.py b/web/agent_api.py
index dee15cf..62ff460 100644
--- a/web/agent_api.py
+++ b/web/agent_api.py
@@ -58,7 +58,7 @@ _run = {"id": None, "state": "idle", "prompt": "", "serial": "",
         "draft_error": "",    # designer：草稿被拦下的原因（errors 拼接）
         "warnings": [],       # designer：草稿的提醒项（不拦，前端醒目展示）
         "history": []}   # 多轮对话历史 [{role: user|assistant, content}]
-_queues = {}            # run_id -> queue.Queue（SSE 消费者读取）
+_queues = {}            # run_id -> _Fanout（SSE 消费者各自订阅，见下）
 _stop_events = {}       # run_id -> threading.Event（用户中断）
 _lock = threading.Lock()
 _flask_app = None       # web_server 注册时注入（后台线程 db 操作需 app context）
@@ -69,6 +69,62 @@ def set_app(app):
     _flask_app = app
 
 
+class _Fanout:
+    """一个 Agent 轮次的事件，扇出给**所有**订阅者（每个订阅者一个独立队列）。
+
+    历史实现是"一个 run 一个 queue.Queue"：第二个页面一订阅，两个 EventSource 就
+    开始**瓜分**同一条队列——谁先取到算谁的。2026-09-14 实测踩到：同一个浏览器里
+    聊天页与建任务页同时开着，建任务页的回放卡到一半就不动了、`done` 事件被另一个
+    页面取走 → 永远等不到草稿（表现为"探索完没法创建任务"）。
+    扇出之后，多开几个页面都各看各的，谁都不丢事件。
+    """
+
+    # 单轮事件缓冲上限：新订阅者从这里补齐"订阅之前"的回放（刷新/重连不丢进度）。
+    # 只留最近 _HISTORY_KEEP 条，避免长任务把内存拖大；终止事件（done/error）永远保留。
+    _HISTORY_KEEP = 400
+
+    def __init__(self):
+        self._subs = []
+        self._history = []
+        self._closed = False
+        self._lock = threading.Lock()
+
+    def subscribe(self):
+        """新订阅者拿一个专属队列（**预填已发生的事件**）；轮次已结束则返回 None。"""
+        with self._lock:
+            if self._closed:
+                return None
+            q = queue.Queue()
+            for item in self._history:
+                q.put(item)
+            self._subs.append(q)
+            return q
+
+    def unsubscribe(self, q):
+        with self._lock:
+            if q in self._subs:
+                self._subs.remove(q)
+
+    def put(self, item):
+        with self._lock:
+            subs = list(self._subs)
+            self._history.append(item)
+            # 只留最近 N 条。终止事件（done/error 及其后的哨兵）永远在尾部，
+            # 按这个规则裁剪不会把它们丢掉。
+            if len(self._history) > self._HISTORY_KEEP:
+                del self._history[:len(self._history) - self._HISTORY_KEEP]
+        for q in subs:
+            q.put(item)
+
+    def close(self):
+        """结束：给每个订阅者发终止哨兵（None）。"""
+        with self._lock:
+            self._closed = True
+            subs, self._subs = self._subs, []
+        for q in subs:
+            q.put(None)
+
+
 def _meta_get(key):
     # 走方言中立助手（app_meta 的列名 key 在 MySQL 里是保留字，裸 SQL 会语法错）
     from core.db_config import meta_get
@@ -1184,7 +1240,7 @@ def agent_run():
                     answer="", error="", usage={},
                     draft=None, draft_error="", warnings=[])
         # history 保留（多轮上下文），由会话/「新建会话」管理
-        _queues[run_id] = queue.Queue()
+        _queues[run_id] = _Fanout()
         _stop_events[run_id] = threading.Event()
     _log.info(f"Agent 启动[{mode}]: {prompt[:60]} @ {serial or 'default'} "
               f"conv={conv_id or '-'}")
@@ -1276,21 +1332,29 @@ def agent_stream():
     with _lock:
         if run_id != _run["id"]:
             return jsonify({"ok": False, "error": "run_id 不存在"}), 404
-        q = _queues.get(run_id)
+        fan = _queues.get(run_id)
+    # 每个订阅者一个专属队列（多开页面互不抢事件）；轮次已结束 → 404
+    q = fan.subscribe() if fan is not None else None
+    if q is None:
+        return jsonify({"ok": False, "error": "本轮已结束"}), 404
 
     def gen():
-        while True:
-            try:
-                evt = q.get(timeout=15)
-            except queue.Empty:
-                yield ": keepalive\n\n"   # 心跳防超时
-                continue
-            if evt is None:
-                break
-            kind, payload = evt
-            yield f"event: {kind}\ndata: {json.dumps(payload, ensure_ascii=False)}\n\n"
-            if kind in ("done", "error"):
-                break
+        try:
+            while True:
+                try:
+                    evt = q.get(timeout=15)
+                except queue.Empty:
+                    yield ": keepalive\n\n"   # 心跳防超时
+                    continue
+                if evt is None:
+                    break
+                kind, payload = evt
+                yield f"event: {kind}\ndata: {json.dumps(payload, ensure_ascii=False)}\n\n"
+                if kind in ("done", "error"):
+                    break
+        finally:
+            # 页面关掉/断线时摘掉自己的队列，别让扇出往里堆没人读的事件
+            fan.unsubscribe(q)
 
     return Response(gen(), mimetype="text/event-stream",
                     headers={"Cache-Control": "no-cache",
@@ -1408,6 +1472,61 @@ def agent_task_draft_save():
     return jsonify({"ok": True, "msg": "草稿已保存", "saved": saved})
 
 
+@bp.route("/api/agent/task_draft/create", methods=["POST"])
+@admin_required
+def agent_task_draft_create():
+    """把暂存的草稿**直接创建**成任务（AI 建任务页的「直接创建任务」）。
+
+    这是"AI 直接建任务"的落点，两条设计约束：
+      - **草稿体只在服务端**（app_meta）：客户端只能传 overrides，不能把任务内容
+        再提交一遍——少一个可被篡改的入口；
+      - 创建前**再校验一次**（草稿可能是人工改过的），通过后走与「新建任务」
+        **完全相同**的落库路径 `context.mgr.add_job`。
+    创建成功后清掉草稿（同一份草稿不该被重复建成多个任务）。
+    """
+    from core.task_draft import validate_draft
+    from web import context
+    saved = _load_draft_meta()
+    if not saved or not saved.get("draft"):
+        return jsonify({"ok": False, "error": "没有可创建的草稿，请先探索一次"}), 400
+    data = request.json or {}
+    overrides = data.get("overrides") if isinstance(data.get("overrides"), dict) else {}
+    groups, pool = _draft_env()
+    res = validate_draft(saved["draft"], groups=groups, pool=pool,
+                         default_serial=(data.get("serial") or "").strip(),
+                         overrides=overrides)
+    if not res["ok"]:
+        return jsonify({"ok": False, "error": "草稿校验未通过（请在编辑器里核对）",
+                        "errors": res["errors"]}), 400
+    task = res["draft"]["task"]
+    params = task["params"]
+    params.setdefault("skip_offline", True)   # 与编辑器保存时一致
+    try:
+        job = context.mgr.add_job(name=task["name"], task_type=task["task_type"],
+                                  target=task["target"], params=params,
+                                  schedule=task["schedule"], retry=task["retry"],
+                                  enabled=bool(task.get("enabled", True)))
+    except Exception as e:
+        _log.exception("AI 草稿创建任务失败")
+        return jsonify({"ok": False, "error": f"创建失败: {e}"}), 500
+    # 用掉就清掉，避免重复创建
+    _meta_put(_DRAFT_META_KEY, "")
+    try:
+        db.session.commit()
+    except Exception:
+        db.session.rollback()
+    with _lock:
+        _run["draft"] = None
+        _run["warnings"] = []
+    d = job.to_dict()
+    nr = context.mgr.next_run_of(job)
+    d["next_run"] = nr.strftime("%Y-%m-%d %H:%M") if nr else None
+    _log.info(f"AI 草稿已创建任务: {job.name}（{job.id}）"
+              f"{'，' + str(len(res['warnings'])) + ' 条提醒' if res['warnings'] else ''}")
+    return jsonify({"ok": True, "msg": f"任务「{job.name}」已创建",
+                    "job": d, "warnings": res["warnings"]})
+
+
 @bp.route("/api/agent/task_draft/clear", methods=["POST"])
 @admin_required
 def agent_task_draft_clear():
@@ -1713,13 +1832,14 @@ def _agent_thread(run_id, prompt, serial, cfg, mode="chat", settings=None):
             except Exception as e:
                 _log.warning(f"会话落库失败: {e}")
 
-        # 自进化：AI 建任务（designer）**不沉淀**——探索轨迹是为"写出一条任务"服务的，
-        # 不是一次成功操作套路；沉淀它会把探索期的误点/试错当成经验，污染记忆库。
-        # （把"草稿→经验/动作"作为独立里程碑，见 doc/AI_TASK_GEN.md §6 P1）
-        # 必须在 done 之前完成——
+        # 自进化：成功执行过工具则提炼配方写入经验。必须在 done 之前完成——
         # done 发出后 SSE 关流，用户就看不到「已写入经验」的提示了。
         # 提炼/保存失败静默（不阻塞、不影响结果），只在成功时推送 🧠 卡片。
-        if tool_seq and not designer:
+        # 建任务（designer）模式也沉淀，但**只在草稿通过校验时**：那说明这轮探索
+        # 确实走通了一条路。没有草稿的探索（试错、半途而废）不入库，免得把误点当经验。
+        with _lock:
+            draft_ok = bool(_run.get("draft"))
+        if tool_seq and (not designer or draft_ok):
             try:
                 recipe = _clean_recipe(_distill_experience(cfg, prompt, " -> ".join(tool_seq)))
                 if recipe:
@@ -1774,6 +1894,10 @@ def _agent_thread(run_id, prompt, serial, cfg, mode="chat", settings=None):
                 pass
         q.put(("error", {"message": str(e)[:200]}))
     finally:
-        q.put(None)   # 关闭 SSE
+        # 关闭 SSE：扇出把终止哨兵发给**每个**订阅者
+        if isinstance(q, _Fanout):
+            q.close()
+        else:
+            q.put(None)
         _queues.pop(run_id, None)
         _stop_events.pop(run_id, None)

From 5dc15e128e03c08ca7026c9d78a213d3dd15e4a1 Mon Sep 17 00:00:00 2001
From: butubb <1422726308@qq.com>
Date: Mon, 14 Sep 2026 08:25:35 +0800
Subject: [PATCH 9/9] =?UTF-8?q?fix(AI=20=E5=BB=BA=E4=BB=BB=E5=8A=A1):=20?=
 =?UTF-8?q?=E5=88=87=E8=B5=B0=E5=86=8D=E5=88=87=E5=9B=9E=E6=9D=A5=E4=B8=8D?=
 =?UTF-8?q?=E5=86=8D=E9=87=8D=E7=BD=AE/=E9=87=8D=E5=A4=8D=E6=8E=A2?=
 =?UTF-8?q?=E7=B4=A2=E5=9B=9E=E6=94=BE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

现象（用户报）：离开「AI 建任务」子页再回来，回放与步骤计数像是被重置了。

真因与修法（`static/admin/taskgen.js`）：
1. 每次进入子页 `initTaskGen → tgRestore` 都会重新订阅 SSE。已在盯同一轮时这是多余的：
   服务端 `_Fanout` 带历史缓冲，会把这一轮**从头补发**一遍 → 回放区里卡片变两份、
   步骤计数从 0 重数。现在用 `_tgRunId` 记当前订阅，同一轮直接复用连接；
   换了一轮/刚刷新过页面才清空回放区重新订阅（历史缓冲会把已发生的事件补回来）。
2. 跟随画面的 MJPEG 长连接在切 Tab 时可能被浏览器挂起（画面定格）——
   切回来时重新拉一次流（`tgRearmLive`）。

实测（真机，12 步探索）：切走 6 秒再切回 → 卡片 11→14 无重复、状态继续计数；
跑完后再切两次 → 14 张卡片与草稿预览均保持、跟随画面正常、无 JS 报错。
---
 doc/AI_TASK_GEN.md      |  6 +++++-
 static/admin/taskgen.js | 27 ++++++++++++++++++++++++++-
 2 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/doc/AI_TASK_GEN.md b/doc/AI_TASK_GEN.md
index afede4d..f65b868 100644
--- a/doc/AI_TASK_GEN.md
+++ b/doc/AI_TASK_GEN.md
@@ -214,7 +214,11 @@
   `static/admin/base.js` 的 `showSubTab`）。草稿预览能直接点「在步骤编辑器中打开」→
   `openTaskModal(null, prefill)` 预填（用唯一 draftKey，避开 localStorage 旧草稿覆盖）。
 - **两个页面共用一个运行槽**：`GET /api/agent/run` 回 `mode`，两个前端各按 mode 决定
-  是否订阅 SSE（一个 run 只有一个事件队列，两个 EventSource 同时消费会互相瓜分事件）。
+  是否订阅 SSE；服务端用 `_Fanout` 给**每个订阅者一条自己的队列**（谁都不丢事件）。
+- **切 Tab 不丢回放**：`initTaskGen()` 每次进入子页都会 `tgRestore()`——已经在盯同一轮就
+  **不重复订阅**（否则服务端会把这一轮从头补发一遍，卡片成两份）；换了一轮/刚刷新过页面才清空
+  回放区重新订阅（`_Fanout` 的历史缓冲会把已发生的事件补回来）。跟随画面的 MJPEG 长连接
+  在切回来时重新拉一次（`tgRearmLive`），避免定格。
 - **落库出口**：页面上的「✓ 直接创建任务」（`POST /api/agent/task_draft/create`）与
   「在步骤编辑器中核对」（预填编辑器 → 用户点保存）——两条路最终都汇到 `add_job`。
 
diff --git a/static/admin/taskgen.js b/static/admin/taskgen.js
index e698fcf..cafca5b 100644
--- a/static/admin/taskgen.js
+++ b/static/admin/taskgen.js
@@ -10,6 +10,7 @@
 let _tgInit = false;
 let _tgStream = null;     // EventSource
 let _tgBusy = false;
+let _tgRunId = '';        // 当前已订阅的 run（切 Tab 回来时避免重复订阅）
 let _tgDraft = null;      // {summary, task, notes, evidence}
 let _tgWarnings = [];
 let _tgPrompt = '';       // 本次需求（回存草稿时带上）
@@ -29,6 +30,17 @@ function initTaskGen(){
   tgLoadDevices();
   tgLoadGroups();
   tgRestore();
+  tgRearmLive();
+}
+
+// 切走再切回来时，观众侧的 MJPEG 长连接可能被浏览器挂起（画面定格）——
+// 重新拉一次流，画面接着动
+function tgRearmLive(){
+  const card = document.getElementById('tg-live-card');
+  const img = document.getElementById('tg-live-img');
+  if(!card || !img || !_tgLiveSerial || card.style.display === 'none') return;
+  img.src = '/api/screen/stream?serial=' + encodeURIComponent(_tgLiveSerial)
+          + '&q=80&fps=8&t=' + Date.now();
 }
 
 function tgExample(){
@@ -178,6 +190,7 @@ function tgStatus(t){
 // ---------------- 事件流 ----------------
 function listenTaskGenStream(runId){
   if(_tgStream) _tgStream.close();
+  _tgRunId = runId;
   const es = new EventSource('/api/agent/stream?run_id=' + runId);
   _tgStream = es;
   let steps = 0;
@@ -461,7 +474,19 @@ function tgRestore(){
     if(!r||!r.ok) return;
     // 运行中的 designer 由本页接管订阅；聊天页见 agent.js 的 mode 判断
     if(r.running && r.mode === 'designer' && r.run_id){
-      tgSetBusy(true, '探索进行中…（刷新后已重新连接）');
+      tgSetBusy(true, '探索进行中…');
+      // 已经在盯着同一轮了（切走再切回来）→ 别重复订阅：
+      // 重订阅会让服务端把这一轮从头发一遍（历史缓冲），卡片就成两份了
+      if(_tgRunId === r.run_id && _tgStream && _tgStream.readyState !== 2){
+        tgStatus('探索进行中…');
+        return;
+      }
+      // 换了一轮 / 刚刷新过页面：回放区清空重建（服务端会把已发生的事件补发回来）
+      const box = document.getElementById('tg-stream');
+      if(box) box.innerHTML = '';
+      const db = document.getElementById('tg-draft');
+      if(db) db.innerHTML = '';
+      tgStatus('探索进行中…（已连接，回放会从头补齐）');
       listenTaskGenStream(r.run_id);
       return;
     }