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。
This commit is contained in:
+60
-1
@@ -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. 自测产生的东西（草稿/自建任务）用后即删，别碰用户真实数据。
|
||||
|
||||
Reference in New Issue
Block a user