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:
+204
-16
@@ -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
|
||||
|
||||
# 无工具调用：本轮即最终回答
|
||||
|
||||
Reference in New Issue
Block a user