feat(AI 建任务): AI 自己在真机探索 → 写出可调度任务 → 人工确认入库

AI 控制台下新增子分栏「🧭 AI 建任务」：描述要做什么（例：建一个跑 2 小时的任务、自动刷某 App、随机点赞），AI 用 de_* 工具自己在设备上探索（看屏/读元素树/点按验证），把走通的路径写成一条任务草稿，经服务端校验后交人在步骤编辑器里核对/手改/试跑，保存才入库。链路：POST /api/agent/run{mode:"designer", settings} → Agent 自探 → 本地工具 submit_task(draft) → core/task_draft 校验（失败把 errors 回灌模型让它改） → 只暂存（运行态 + app_meta.agent_task_draft，**不落库**） → SSE done{mode,draft,warnings} → 页面草稿预览 → openTaskModal(null, prefill) 预填关键实现 - core/task_draft.py（新）：把执行器的"静默跳过点"（未知 type/空 selector/空 children/ 嵌套>5/节点>60/cron 非法/必填缺失）前移成显式 error——POST /api/jobs 对 params 是盲存的，执行器又静默跳过错误步骤，没有这道闸门就是"任务建好了、跑起来什么都没做"。归一化兜底任务名/target/schedule/retry/时长；页面填的设置以 overrides 优先于模型。故意**不比执行器更严**：loop_mode 近义值归一（count→rounds）、缺 max_iterations 补默认 10 （执行器本来就默认）——实测卡太死会把一轮探索耗在改字段上。有副作用的步骤（评论/发送/购买/删除…）只警告并把触发概率压到 30%（编辑器可改回）。 - mcp_agent/agent.py：双系统提示词（CHAT/DESIGNER）+ 平台级本地工具（LOCAL_TOOL_SPECS，不进 MCP）+ 每工具调用上限 40 + designer 输出上限 8192 + **json.loads 容错**（草稿被截断时给模型可读错误，而不是整轮失败）。 - web/agent_api.py：mode/settings 透传、submit_task 处理器（app_context 内校验+暂存）、 done 带 draft、GET /api/agent/task_draft{,+POST,/clear}（草稿走 app_meta，不新建表）。 - 前端：static/admin/taskgen.js + #agent-sub-taskgen 子面板（showSubTab 机制）； tasks.js 的 openTaskModal(jobId, prefill) + 信封归一化 + 唯一 draftKey； agent.js 按 mode 门控（一个 run 只有一个事件队列，两个 EventSource 会互相瓜分事件）。顺带修掉一个 chat 也踩的协议 bug：一轮里同时调 de_screenshot 与别的工具时，截图图像会被插在两条 tool 消息之间 → 模型侧判"工具回应不足"直接 400。改为本轮 tool 消息发完再附图像， _repair_tool_messages 也改成只数**连续**的 tool 消息。真机实测（Redmi 22120RN86C，设置页）：8 步探索（含 tap_text 验证）→ submit_task 一次通过 → 草稿 8 个顶层步骤（screen_on/open_app/wait_el/click/wait/key_event…）、max_duration 1800、无 click_xy、3 条 evidence；页面恢复草稿 + 预填编辑器 + 提示块渲染均正常，无 JS 报错。自测数据已清理（草稿已丢弃、未创建任何任务）。文档：AI_TASK_GEN.md 状态改「P0 已实现」+ §10 实现记录（差异/护栏/未做项）、AI_CONSOLE.md （子分栏、designer 分支、SSE done 负载、app_meta 键）、API.md、DATA_MODEL.md、ARCHITECTURE.md、 DEVELOPMENT.md（自测入口）、README.md 索引、backlog 勾掉 P0。
2026-09-13 23:08:59 +08:00
parent 0bc713137d
commit 46e6ea1f37
16 changed files with 1707 additions and 47 deletions
@@ -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`）。

 ---

@@ -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. 自测产生的东西（草稿/自建任务）用后即删，别碰用户真实数据。
@@ -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）

@@ -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），靠加载顺序保证依赖。
@@ -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） | 同上 |
@@ -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/`。

@@ -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 流程、技术红线、本地开发与调试、常见开发任务、文档同步约定 | 所有开发者 |
@@ -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。
 - [ ] 经验/动作入库依赖模型蒸馏成功：加失败重试与可视化观测（现在只在日志里）。