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/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/core/uiauto_helper.py b/core/uiauto_helper.py index db6f448..f5b4894 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 标签一律是 ，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 里每个元素的**标签名都是 ``**，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 的标签全是 ）； + # 实测 248 个元素里 26 条死选择器，2026-09-13 修复。 + suggested = {"type": "xpath", "value": f"//hierarchy{_child_path(path)}", + "broad": True} child_ctx = None out.append({ @@ -258,3 +347,96 @@ 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, "screen_state": "on", "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() # 先截：用户看到的就是这一刻 + # 屏幕开关状态（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: + 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, + "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 9f28e0c..7519b0a 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,11 +111,16 @@ 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 轮询用）。 +**多页面同时看同一轮**：一轮的事件用**扇出**（`web/agent_api.py` 的 `_Fanout`）发给每个订阅者各自 +的队列——两个页面都收到全量事件。**不要**退回"一个 run 一个 `queue.Queue`"：那样第二个页面一订阅， +两个 EventSource 就开始瓜分同一条队列，谁先取到算谁的（2026-09-14 实测：聊天页把建任务页的 `done` +取走了，建任务页永远等不到草稿）。 + ### 3.4 token 统计 - 请求带 `stream_options.include_usage`，服务端在**末尾 chunk** 返回 usage @@ -191,8 +208,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..f65b868 100644 --- a/doc/AI_TASK_GEN.md +++ b/doc/AI_TASK_GEN.md @@ -1,13 +1,14 @@ # AI 建任务（AI Task Generator）设计文档 -> 状态：**设计稿，尚未实现**（P0 未开工）——本文描述的是「要做什么、为什么这么做」，不是现状。 -> 现状请读：[AI_CONSOLE.md](AI_CONSOLE.md)（AI 控制台已实现的能力）、[TASK_DEV.md](TASK_DEV.md)（任务与步骤）、[MCP.md](MCP.md)（已实现的 19 个工具）。 +> 状态：**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)（已实现的 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。 @@ -35,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）。 @@ -154,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 建任务链路真正需要的「平台工具」（最小集） @@ -181,3 +182,86 @@ ### 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；服务端用 `_Fanout` 给**每个订阅者一条自己的队列**（谁都不丢事件）。 +- **切 Tab 不丢回放**：`initTaskGen()` 每次进入子页都会 `tgRestore()`——已经在盯同一轮就 + **不重复订阅**（否则服务端会把这一轮从头补发一遍，卡片成两份）；换了一轮/刚刷新过页面才清空 + 回放区重新订阅（`_Fanout` 的历史缓冲会把已发生的事件补回来）。跟随画面的 MJPEG 长连接 + 在切回来时重新拉一次（`tgRearmLive`），避免定格。 +- **落库出口**：页面上的「✓ 直接创建任务」（`POST /api/agent/task_draft/create`）与 + 「在步骤编辑器中核对」（预填编辑器 → 用户点保存）——两条路最终都汇到 `add_job`。 + +### 10.3 附带修掉的两个 bug + +**(1) 事件被另一个页面抢走**（用户报的"探索完没法创建任务"的真因）：一轮的事件原先只有一个 +`queue.Queue`，聊天页与建任务页同时开着时，两个 EventSource **瓜分**同一条队列——建任务页的回放 +会卡在中间，`done` 事件被聊天页取走 → 永远等不到草稿 → 页面上没有可点的"创建"。 +现改为**扇出**（`web/agent_api.py` 的 `_Fanout`）：每个订阅者一个专属队列，多开页面各看各的； +前端两侧也按 `mode` 门控，不互相订阅。 + +**(2) 工具消息配对** + +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 后续批次（2026-09-14 已完成的三项） + +- ✅ **「直接创建」**：`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 仍未做 + +- 多设备并行探索、探索成本/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` 文案模型能读懂。 +2. 真机：AI 控制台 →「AI 建任务」→ 选空闲设备 → 描述需求 → 看回放 → 核对草稿 → + 「在步骤编辑器中打开」→ 单步试跑 → 保存。 +3. 反例：需求里出现"自动评论并发送" → 草稿的这类步骤应是"只核对存在性"（`notes` 里提示 + 人工复核），**探索期审计日志里不应有对发送键的 `de_tap_*`**。 +4. 自测产生的东西（草稿/自建任务）用后即删，别碰用户真实数据。 diff --git a/doc/API.md b/doc/API.md index 8c86f17..ab5d8ec 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 | 真机试执行单个步骤 | @@ -197,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` | 清空对话历史 | @@ -212,6 +213,22 @@ | 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/create` | **直接创建**：取暂存草稿 → 再校验 → `add_job` → 清草稿（body 可带 `{serial, overrides}`；草稿体不接受客户端提交） | +| 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） @@ -526,10 +543,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,screen_state,cost_ms}`；抓取弹窗与 MCP 的 `de_snapshot` 都用它，失败返回 **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/ARCHITECTURE.md b/doc/ARCHITECTURE.md index 6541492..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 工具 │ └────────────────────────────────────┘ └──────────────────────────────┘ ``` @@ -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/MCP.md b/doc/MCP.md index 8cb5b26..ddea366 100644 --- a/doc/MCP.md +++ b/doc/MCP.md @@ -12,7 +12,7 @@ AI 控制台 / 外部 MCP 客户端 │ Streamable HTTP（http://:8033/mcp） ▼ -MCP Server（mcp_server/mcp_server.py） ← 19 个 de_* 工具 +MCP Server（mcp_server/mcp_server.py） ← 20 个 de_* 工具 │ 平台 HTTP API（登录 + CSRF） 或 轻量 adb/u2 直连 ▼ auto_control 平台（:18050） ← 设备池 / 任务 / 看屏 @@ -63,7 +63,7 @@ MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<平台密码> \ --- -## 4. 工具清单（19 个） +## 4. 工具清单（20 个） 统一返回约定： @@ -88,6 +88,7 @@ MCP_ALLOW_WRITE=1 MCP_PLATFORM_USER=admin MCP_PLATFORM_PASS=<平台密码> \ |------|------|------------| | `de_screenshot` | `serial` | `{image:{type:"image",data:,mimeType:"image/jpeg"}, width, height, native_size, screen_state}`。多模态模型直接看图 | | `de_ui_tree` | `serial`, `limit`(150，1-300) | `{count, elements:[{text,id,desc,class,clickable,bounds}]}`，**可点击元素排前**；`limit` 控 token | +| `de_snapshot` | `serial`, `limit`(120，1-300) | **截图 + 元素树一次取齐**（推荐用它代替 `de_screenshot`+`de_ui_tree`）：平台侧同一个 u2 连接背靠背取 + 双截图校验。返回 `{image, width, height, native_size, screen_state, unstable, cost_ms, count, elements}`；`unstable=true` 表示抓取期间界面在变化（此时元素坐标不可信，让设备静下来再取）。**同样会建立 `de_tap/de_swipe` 的坐标空间** | | `de_ocr` | `serial` | `{count, texts:[{text,score}]}`（≤100 条）。UI 树拿不到的图片/WebView 文字用它 | | `de_read_clipboard` | `serial` | `{clipboard}` | | `de_list_apps` | `serial`, `keyword`("") | `{count, packages}` 第三方已装包名（`pm list packages -3`，≤200） | diff --git a/doc/MCP_DESIGN.md b/doc/MCP_DESIGN.md index d5e4494..b5a718b 100644 --- a/doc/MCP_DESIGN.md +++ b/doc/MCP_DESIGN.md @@ -1,6 +1,6 @@ # MCP 手机控制（Mobile Control MCP Server）设计文档 -> 状态：**设计稿 / 演进记录**——凡与实现不符处，以 [MCP.md](MCP.md)（使用手册，含 19 个工具的权威清单）与 `mcp_server/` 代码为准。 +> 状态：**设计稿 / 演进记录**——凡与实现不符处，以 [MCP.md](MCP.md)（使用手册，含 20 个工具的权威清单）与 `mcp_server/` 代码为准。 > 本文保留设计取舍与里程碑，便于回溯"为什么这么做"；文中的"演进备选"均**未落地**。 > 最后核对：2026-09-10（对照 dev 现状）。 diff --git a/doc/README.md b/doc/README.md index 10e742a..8051a94 100644 --- a/doc/README.md +++ b/doc/README.md @@ -14,16 +14,17 @@ | [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 建任务**：设计稿与里程碑（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 流程、技术红线、本地开发与调试、常见开发任务、文档同步约定 | 所有开发者 | | [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/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 标签名一律是 ``**，`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..7c358e0 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**，改动需同步执行器 + 编辑器）。 @@ -96,7 +96,12 @@ ## 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` 校验 + 草稿预览/预填；✅ 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/research/U2_ELEMENT_SELECTORS.md b/doc/research/U2_ELEMENT_SELECTORS.md new file mode 100644 index 0000000..49918e5 --- /dev/null +++ b/doc/research/U2_ELEMENT_SELECTORS.md @@ -0,0 +1,174 @@ +# 元素选择器研究：为什么"点不到按钮"（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]` —— **只在上面都不行时** + +--- + +## 四、抓取弹窗"老是错位"的根因 —— **截图和元素树不是同一时刻** + +（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 的开销，改不动）。 +界面**只要在动**（抖音信息流、视频、加载动画…），两秒足够让元素位置全变 → +**框永远落在旧位置上** —— 这就是"老是错位"，不是偶发。 + +### 解法（✅ 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. **双截图校验**（关键：让失败可见而不是悄悄错位）： + 抓取时前后各截一张，两张**不一致就明确提示**"界面在抓取过程中变化了， + 请让设备停在目标界面再抓"，而不是给一个已经错位的框。 +3. 文档里明确写：**抓元素要让设备停在静止界面**（设置页、已加载完的页面）， + 别在视频播放/信息流滑动中抓。 + +--- + +## 五、建议的改动 + +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. ✅ **（针对第四节的"抓取错位"）** 抓取接口合并成一个快照接口 + 双截图校验， + 具体见第四节「解法」。 + +--- + +## 六、顺带修掉的两个"结构性"坑（2026-09-13） + +给 §五.1 做验证时（对真机 dump 逐条用 lxml 求值，比对"命中数==1 且 bounds 一致"）， +发现旧实现 248 个元素里有 **26 条选择器永远匹配不到任何东西** —— 都是"结构路径"类： + +| 坑 | 现象 | 原因 | +|---|---|---| +| `//FrameLayout[1]/LinearLayout[2]` | 零命中 | **dump 的 XML 标签名一律是 ``**，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/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 8951bc4..1fae3d6 100644 --- a/mcp_agent/agent.py +++ b/mcp_agent/agent.py @@ -25,15 +25,23 @@ _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（地址）， **给用户汇报时用名称**（同型号多台靠它区分），调工具时仍用 serial -2. 观察屏幕：先 de_screenshot 获取截图（图像会随后给你），基于截图理解当前界面 +2. 观察屏幕：优先 `de_snapshot`（截图+元素树一次取齐，图像会随后给你）——比 + de_screenshot + de_ui_tree 两次取数更省步骤，界面在动时也不会出现"元素位置和 + 截图对不上"；需要单独看画面时才用 de_screenshot 3. 点击定位分优先级（不要自己推算像素坐标，那是精度最差的方式）： a) 目标有可见文字（按钮/菜单/列表标题/标签/输入框提示）→ de_tap_text 直接给文字， 一次完成「找到并点击」，原生控件与 WebView/图片渲染文字都支持 @@ -54,6 +62,103 @@ SYSTEM_PROMPT = """你是手机自动化控制助手。你通过工具实时操 可用工具清单将由系统提供。""" +# 兼容旧名（CLI / 其它调用方仍可能 import SYSTEM_PROMPT） +SYSTEM_PROMPT = CHAT_SYSTEM_PROMPT + + +# ================== 建任务模式（designer）================== +# 与聊天模式的根本区别：**产出物是一条任务，不是"替用户做完这件事"**。 +# 所以它要"看懂了就写下来"，而不是"一路点到底"；有副作用的动作只许核对、不许真做。 +DESIGNER_SYSTEM_PROMPT = """你是手机自动化**任务设计师**。你的产出物是**一条可调度、可在步骤编辑器里继续修改的任务**（不是替用户把这件事做完）。 + +工作方式：在真机上探索够用即止 → 把探索到的元素与操作写成任务步骤 → 调 submit_task 提交草稿 → 人工确认后才会真正入库执行。 + +## 探索规范 +1. 只用本次指定的设备 serial；给用户汇报时用设备名。设备离线/异常/被任务占用时**立即停止并说明**，不要硬试。 +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 这个类型）。 +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 +178,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 +222,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 +260,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 +322,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 +388,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 +405,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 +416,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 +503,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 +517,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/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 c6335e2..a8a3a3a 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) : ''); @@ -570,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/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/editor.js b/static/admin/editor.js index 7896f39..2b6b057 100644 --- a/static/admin/editor.js +++ b/static/admin/editor.js @@ -831,7 +831,7 @@ var _stepEditor={ '
'+ '
'+ '
'+ - ''+ + ''+ '加载中...'+ '
'+ '
'+ @@ -839,8 +839,20 @@ var _stepEditor={ '
'+ '
'+ '
'+ - ''+ - '
加载元素树...
'+ + '
'+ + ''+ + ''+ + ''+ + '
'+ + '
'+ + ''+ + '
加载元素树...
'+ + '
'+ + '
点左侧图上的元素，或点「层级」里的条目看属性
'+ + '
'+ + '
把鼠标移到左侧图上取色；点元素可看该元素的主色
'+ + '
'+ + '
'+ '
'+ '
'; document.getElementById('el-picker-footer').innerHTML= @@ -849,65 +861,138 @@ var _stepEditor={ '' +'提示：先「▶ 点一下」在设备上验证位置，再点元素回填选择器；' +'「✓ 测选择器」会用将填入的选择器真跑一次点击'; - // 加载截图和元素树（_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='
加载元素树...
'; - 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='
'+esc(data.error||'抓取失败')+'
'; - 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='
请求失败: '+esc(e)+'
'; - }); + // 右侧页签切换 + _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); + }); }, - // 刷新截图 - _refreshShot:function(){ + // 属性页：选中元素的全部属性 + _renderAttrs:function(i){ + var el=(this._elData||[])[i]; + var box=document.getElementById('el-pane-attr'); + if(!box)return; + if(!el){box.innerHTML='
点左侧图上的元素，或点「层级」里的条目看属性
';return;} + var sg=el.suggested||{}; + // 稳定性说明：把"这个选择器靠什么定位"写清楚，用户才知道它会不会因为界面变化而失效 + 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||''], + ['bounds', el.bounds||''], ['层级深度', String(el.depth||0)]]; + box.innerHTML=rows.map(function(r){ + return '
'+esc(r[0])+''+esc(r[1]||'-')+'
'; + }).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='
'+ + '光标处 '+esc(col)+'
'+ + (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='
'+ + '选中元素中心 '+esc(c)+'
'; + } + } + box.dataset.dom=dom; + box.innerHTML=dom||'
把鼠标移到左侧图上取色
'; + }, + // 一次取齐：截图 + 元素树（后端用原生 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='
正在获取截图...
'; 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='
正在抓取（截图 + 元素树一次取齐）…
'; + 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='
截图加载失败
'; - 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='
'+esc(d.error||'抓取失败')+'
'; + if(info)info.textContent='失败'; + return; + } + self._elData=d.elements||[]; + if(d.unstable){ + var w=document.createElement('div'); + w.className='el-shot-warn'; + w.innerHTML='⚠ 抓取期间界面有变化，框可能对不上 —— 建议把设备停在静止界面后点「重新抓取」'; + 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?' · ⚠ 界面在变化':''); + } + // 图片显示尺寸一变（窗口缩放、面板宽度变化、滚动条出现…）就重算所有框 —— + // 这是"完全不错位"的保证：框永远跟着图片走，不留旧坐标 + 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); + var search=document.getElementById('el-search'); + if(search&&search.value)self._filterEl(search.value); + }) + .catch(function(e){ + if(container)container.innerHTML='
请求失败: '+esc(e)+'
'; + }); }, + // 兼容旧调用名（工具栏「重新抓取」按钮） + _refreshShot:function(){ this._loadSnapshot(); }, // 在截图上渲染元素边界框（可点击） _renderOverlays:function(){ var container=document.getElementById('el-shot-container'); @@ -947,6 +1032,32 @@ 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(arid:'+esc(el.resource_id)+''); - if(el.text)attrs.push('text:'+esc(el.text)+''); - if(el.description)attrs.push('desc:'+esc(el.description)+''); + if(el.text)attrs.push('text:'+esc(el.text)+''); + if(el.description)attrs.push('desc:'+esc(el.description)+''); + if(el.resource_id)attrs.push('id:'+esc(el.resource_id)+''); var indent=' '.repeat(Math.min(el.depth||0,6)); var sg=el.suggested||{}; if(sg.invalid)attrs.push('⚠ '+esc(sg.reason||'无可用属性')+''); @@ -1009,13 +1124,16 @@ var _stepEditor={ ? '' : '') + +'' +''; - return '
'+ + return '
'+ ''+(el.depth||0)+''+ '
'+indent+esc(el.name||el.class||'')+'
'+ '
'+attrs.join('')+'
'+ ''+esc(sg.type)+''+ - (sg.indexed?' #'+sg.occ+'/'+sg.total+'':'')+ + (sg.semantic?' ✓ 语义':'')+ + (sg.indexed?' ⚠ 序号 '+sg.occ+'/'+sg.total+'':'')+ (sg.broad?' ⚠宽泛':'')+ acts+ '
'; @@ -1062,7 +1180,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/static/admin/taskgen.js b/static/admin/taskgen.js new file mode 100644 index 0000000..cafca5b --- /dev/null +++ b/static/admin/taskgen.js @@ -0,0 +1,507 @@ +// ================== 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 _tgRunId = ''; // 当前已订阅的 run（切 Tab 回来时避免重复订阅） +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(); + 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(){ + 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 = '' + + devs.map(d=>{ + const label = devText(d.name, d.serial) + (d.model ? ' · ' + d.model : '') + + (d.busy ? ' ⛔ 任务中：' + d.task_job : ''); + return ''; + }).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 = '' + + (r.groups||[]).map(g=>'').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(); + _tgRunId = runId; + 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(); + if(tgAutoCreateOn()){ + // 用户勾了「探索完直接创建」：不再等确认，直接建（服务端仍会再校验一次） + tgStatus('探索完成，正在直接创建任务…'); + createDraft(true); + endTaskGenStream(); + return; + } + 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 = '' + + '' + esc(tool||'') + ' ' + + '' + esc(argsTxt || '') + ''; + 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(['

📝 ' + esc(task.name || _tgDraft.summary || '任务草稿') + '

']) + .concat(['
' + esc(_tgDraft.summary || '') + '
']) + .concat(['
目标：' + esc(tgTargetText(task.target)) + + ' ｜ 调度：' + esc(tgScheduleText(task.schedule)) + + ' ｜ 时长上限：' + esc(String((task.params||{}).max_duration || 0)) + ' 秒
']) + .concat(['
']) + .concat(tgRenderSteps(steps, 0)) + .concat(['
']); + if((_tgWarnings||[]).length){ + html.push('
⚠ ' + _tgWarnings.length + ' 处提醒（不拦，但请核对）' + + _tgWarnings.map(w=>'
· ' + esc(w) + '
').join('') + '
'); + } + if((_tgDraft.notes||[]).length){ + html.push('
需要人工复核' + + _tgDraft.notes.map(n=>'
· ' + esc(n) + '
').join('') + '
'); + } + const ev = _tgDraft.evidence || []; + if(ev.length){ + html.push('
探索依据（' + ev.length + ' 条）' + + ev.map(e=>'
' + esc(e.screen || '') + ' · ' + + esc(e.selector_type || '') + '=' + + esc(e.selector_value || '') + ' · ' + + esc(e.verified || '') + '
').join('') + + '
'); + } + html.push('
' + + '' + + '' + + '' + + '
'); + box.innerHTML = '
' + html.join('') + '
'; +} + +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 = '
' + esc(pad) + '' + esc(s.type) + '' + + (s.label ? ' 「' + esc(s.label) + '」' : '') + + (bits.length ? ' ' + esc(bits.join(' · ')) + '' : '') + + '
'; + 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 tgAutoCreateOn(){ + const c = document.getElementById('tg-auto-create'); + return !!(c && c.checked); +} + +// 把草稿直接建成任务（服务端取暂存草稿 → 再校验 → add_job → 清草稿） +// auto=true 表示是勾了开关后的自动创建（不再弹确认） +function createDraft(auto){ + if(!_tgDraft){ showToast('还没有草稿','error'); return; } + const name = ((_tgDraft.task||{}).name) || '这条任务'; + if(!auto && !confirm('直接创建任务「' + name + '」？\n\n' + + '创建后就是一条正式的可调度任务（可在任务页编辑/停用），' + + '不再经过步骤编辑器的核对。')) return; + const cfg = tgCollectSettings(); + tgStatus('正在创建任务…'); + apiPost('/api/agent/task_draft/create', { + serial: ((document.getElementById('tg-serial')||{}).value||''), + overrides: cfg ? cfg.settings : {} + }).then(r=>{ + if(!r || !r.ok){ + const errs = (r && r.errors && r.errors.length) + ? '：' + r.errors.slice(0,3).join('；') : ''; + showToast(((r&&r.error)||'创建失败') + errs, 'error'); + tgStatus('创建失败 —— 可以「在步骤编辑器中核对」后手工保存'); + return; + } + const job = r.job || {}; + _tgDraft = null; _tgWarnings = []; + const box = document.getElementById('tg-draft'); + if(box){ + box.innerHTML = '

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

' + + '
下次运行：' + esc(job.next_run || '手动触发') + + ' ｜ 调度：' + esc(tgScheduleText(job.schedule)) + + ' ｜ id ' + esc(job.id||'') + '
' + + ((r.warnings||[]).length + ? '
' + r.warnings.map(w=>'· ' + esc(w)).join('
') + '
' + : '') + + '
' + + '' + + '' + + '
'; + } + tgStatus('任务已创建：' + (job.name||'')); + showToast('任务「' + (job.name||'') + '」已创建', 'success'); + if(typeof loadTasks === 'function') loadTasks(); + }); +} + +function tgResetDraftView(){ + _tgDraft = null; _tgWarnings = []; + const box = document.getElementById('tg-draft'); + if(box) box.innerHTML = ''; + tgStatus(''); +} + +function discardDraft(){ + if(!confirm('丢弃这份草稿？')) return; + apiPost('/api/agent/task_draft/clear', {}).then(r=>{ + 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, '探索进行中…'); + // 已经在盯着同一轮了（切走再切回来）→ 别重复订阅： + // 重订阅会让服务端把这一轮从头发一遍（历史缓冲），卡片就成两份了 + 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; + } + 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){ ''; } -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=>'').join(''); const gl=_groupsList.map(g=>'').join(''); const dl=_devicesList.map(x=>'
'+ ''; - // 初始化步骤编辑器（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', + '
AI 探索说明（请核对）' + +(pf.notes||[]).map(n=>'
· '+esc(n)+'
').join('') + +((pf.warnings||[]).length + ? '
校验提醒' + +pf.warnings.map(w=>'
· '+esc(w)+'
').join('')+'
' + : '') + +'
'); + } + // 初始化步骤编辑器（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= ''+ diff --git a/templates/admin/monitor.html b/templates/admin/monitor.html index a385849..4392129 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,21 +297,37 @@ 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;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:1;display:flex;flex-direction:column;overflow:hidden} +.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} .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 风格，图片文字清晰） ===== */ @@ -336,6 +352,43 @@ 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-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} +.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} @@ -516,6 +569,13 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
+
+ + +
+ + +
🤖 AI 控制台
@@ -564,6 +624,97 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14
+
+ + +
+
+
+
+
1️⃣ 说清楚要做什么
+ +
+ + AI 会自己在设备上探索，把走通的路径写成任务步骤 +
+
+ +
+
2️⃣ 选一台空闲设备
+ +
有任务在跑的设备不可选（AI 不与任务抢设备）
+
+ +
+
3️⃣ 任务设置（可选，留空由 AI 判断） + ▸
+ +
+ +
+ + +
+ +
+ + +
+ +
+
+ 探索回放 + +
+
+
AI 在设备上的每一步（看屏 / 读元素树 / 点按验证）会实时显示在这里。
+
+
+
+
+
@@ -1042,12 +1193,12 @@ body{background:var(--bg);font-family:var(--body);color:var(--text);font-size:14