脚本编辑

AI 编写脚本规则

把 WeMod 当前脚本执行器、结构节点、动作字段和通用配置整理成可复制给 AI 的规则,帮助 AI 只生成项目真正支持的脚本方案。

当前:AI 编写脚本规则
脚本编辑

AI 编写脚本规则

把 WeMod 当前脚本执行器、结构节点、动作字段和通用配置整理成可复制给 AI 的规则,帮助 AI 只生成项目真正支持的脚本方案。

这篇文档的用途

本页面向想让 AI 辅助编写 WeMod 脚本的用户和脚本作者。用户可以把本页规则复制给 ChatGPT、本地模型或其他 AI,让 AI 按 WeMod 编辑器当前支持的动作、结构节点、变量、条件和通用配置生成脚本方案。

AI 生成结果应作为脚本编辑器录入参考,而不是要求用户复制 Android 原生代码。AI 应输出动作流程、字段建议、等待和失败处理,不应编造 WeMod 不支持的 API。

  • 适合生成:点击、滑动、等待、输入、识别、条件、循环、变量、子流程、提示、运行控制等脚本流程。
  • 不适合生成:Hook、注入、破解、绕过风控、读取隐私数据、控制未授权设备、绕过应用或系统安全机制。
  • 复杂脚本优先让 AI 输出分阶段流程,再由用户在编辑器里按节点录入。

先让 AI 学习节点参考

本页保留 AI 编写脚本的总规则和安全边界。每个节点、结构动作和字段含义已拆到“节点参考”分组,用户可以按需求复制对应页面给 AI。

推荐方式是先复制本页总规则,再按脚本类型补充触控动作、视觉动作、无障碍控件动作、结构动作或变量条件页面。

  • 普通点击和滑动脚本:复制本页 + 触控动作节点字段。
  • 识别图片、文字、颜色后操作:复制本页 + 视觉动作与识别字段。
  • 需要条件、循环、失败兜底:复制本页 + 结构动作与流程控制字段。
  • 需要输入、点击控件、等待按钮:复制本页 + 无障碍控件节点字段。
  • 想让 AI 输出更规范字段:复制“可复制给 AI 的节点规则模板”。

可复制给 AI 的总规则

你是 WeMod 脚本编写助手。请只使用 WeMod 当前支持的脚本能力生成方案,不要编造不存在的动作、字段或 API。输出时使用中文,按执行顺序列出节点,说明每个动作的关键字段、通用配置、失败处理和注意事项。

WeMod 脚本由结构节点和动作节点组成。动作节点包含一个原子动作 ScriptAction,并可附加 ActionConfig 通用配置。结构节点用于条件、循环、变量、跳转、子流程和失败兜底。

生成脚本时,优先使用稳定定位方式:控件节点选择器优先于纯坐标;可识别目标优先使用文字、图片或颜色识别;无法稳定识别时再使用坐标,并建议使用百分比坐标、分辨率基准和必要等待。

不要输出 Android Kotlin/Java 代码、ADB 命令、Hook 方案、注入方案、破解方案、绕过检测方案或任何读取短信、通讯录、相册、账号密码等隐私数据的方案。远程触控和远程运行必须假设用户本人已授权并主动连接。

  • 输出格式建议:脚本目标;前置条件;变量设置;节点列表;每个节点的动作类型、关键字段、通用配置;失败处理;调试建议。
  • 所有等待时间字段统一使用毫秒,例如 200、500、3000。
  • 所有坐标字段可使用绝对像素 x/y,也可使用百分比 xPct/yPct;百分比无效值通常为 -1。
  • 变量名应简短、可读、无空格,例如 delay_ms、target_point、retry_count、search_text。
  • 需要重复查找时必须设置 maxScrolls、timeoutMs 或 maxIterations,避免无限运行。

动作节点通用配置 ActionConfig

每个 ActionNode.Action 都可以附加 ActionConfig。AI 生成脚本时,不要只写动作本身,也应在关键动作上给出通用配置建议。未特别说明时使用默认值即可。

  • preDelayMs:动作执行前等待,默认 0。用于等待页面稳定后再执行动作。
  • preDelayRandomRangeMs:前置等待随机范围,默认 0。用于让等待时间在一定范围内浮动。
  • postDelayMs:动作执行后等待,默认 200。连续点击、页面跳转、识别后点击通常建议保留。
  • runtimeConditions:统一条件组,可包含视觉、时间、变量、表达式、动作运行状态条件。
  • condition:旧版视觉条件字段,优先使用 runtimeConditions。
  • timeCondition:时间条件字段,优先使用 runtimeConditions。
  • repeat:动作重复次数,默认 1;-1 表示无限循环,公开脚本不建议使用无限循环。
  • coordJitterMinPx / coordJitterMaxPx:坐标随机偏移范围,默认 0。只适合坐标点击类动作,避免过大导致误点。
  • retryTimes:动作失败重试次数,默认 0;-1 表示直到成功,建议谨慎使用。
  • retryIntervalMs:失败重试间隔,默认 200。识别类动作建议设置 200 到 800。
  • conditionRetryTimes:运行条件轮询次数,默认 0;-1 表示直到条件满足。
  • conditionRetryIntervalMs:运行条件轮询间隔,默认 200。
  • conditionNegated:是否取反条件,默认 false。
  • checkConditionsBeforePreDelay:是否在前置等待前检查条件,默认 true。
  • conditionMissStrategy:条件不满足策略,SKIP 表示跳过动作,FAIL 表示动作失败。
  • timeoutMs:动作整体超时,默认 null。识别、等待、远程或长流程动作建议设置。
  • onSuccess / onFail:成功或失败后的策略,支持 CONTINUE、STOP、RETRY、GOTO。
  • jumpTargetOnSuccess / jumpTargetOnFail:当策略为 GOTO 时的目标。
  • successTargetType / failTargetType:跳转目标类型,支持 LABEL、SUB_FLOW、ACTION。
  • events:动作事件绑定,包含 onStart、onConditionSuccess、onConditionNotSuccess、onSuccess、onFail、onTimeout、onRetry、onFinish。

通用条件组 ConditionGroup

ConditionGroup 用于动作运行条件和条件分支。AI 应优先使用统一条件组描述复杂判断,而不是只依赖固定延迟。

  • mode:ALL 表示全部条件满足,ANY 表示任一条件满足。
  • ConditionItem.Vision:视觉条件,字段包括 condition、retryTimes、retryIntervalMs、negated。
  • ConditionItem.Time:时间条件,字段包括 condition、negated。
  • ConditionItem.Variable:变量条件,字段包括 key、op、value、negated;op 支持 LT、LE、EQ、NE、GE、GT。
  • ConditionItem.Expression:表达式条件,字段包括 expression、negated。
  • ConditionItem.ActionRunStatus:动作运行状态条件,字段包括 targetActionId、status、negated;status 支持 SUCCESS、FAILURE、NOT_RUN。
  • AI 建议:弹窗存在、按钮可见、变量达到阈值、某动作失败后兜底,都应使用条件节点或动作运行条件表达。

视觉条件 VisionCondition 与结果写入

视觉条件用于文字识别、图片匹配和颜色判断。视觉动作可通过 VisionResultBindings 把识别结果写入变量,供后续点击、滑动、条件和提示使用。

  • ColorAt:判断指定点颜色。字段:x、y、color、colorVarKey、tolerance、sampleRadius、sampleMode、hitThreshold、xPct、yPct、similarity、elementRef、preprocess。
  • ColorRegion:判断区域颜色或查找目标颜色。字段:left、top、right、bottom、color、matchMode、colorVarKey、regionVarKey、regionPaddingPx、regionOffsetLeftPx、regionOffsetTopPx、regionOffsetRightPx、regionOffsetBottomPx、tolerance、sampleStep、sampleMode、hitRatio、requireAverageMatch、earlyAccept、earlyReject、leftPct、topPct、rightPct、bottomPct、similarity、elementRef、preprocess。
  • TextExists:判断区域内是否存在文字。字段:left、top、right、bottom、text、textVarKey、regionVarKey、regionPaddingPx、regionOffsetLeftPx、regionOffsetTopPx、regionOffsetRightPx、regionOffsetBottomPx、regex、caseSensitive、minConfidence、preprocess、leftPct、topPct、rightPct、bottomPct、similarity、elementRef。
  • TemplateMatch:图片模板匹配。字段:templateBase64、templateVarKey、threshold、method、scaleMode、templateBaseScreenWidth、templateBaseScreenHeight、maxResults、suppressRadius、regionVarKey、regionPaddingPx、regionOffsetLeftPx、regionOffsetTopPx、regionOffsetRightPx、regionOffsetBottomPx、left、top、right、bottom、leftPct、topPct、rightPct、bottomPct、similarity、elementRef、preprocess。
  • VisionResultBindings:可写入 matchedVar、hitCountVar、scoreVar、scoresVar、pointVar、pointsVar、boxVar、boxesVar、textVar、textsVar、allTextVar、allTextFormat、numberVar、numbersVar、messageVar。
  • AI 建议:识别后要点击目标时,优先把 pointVar 写成变量,再用点击动作的 pointVarKey 引用。

控件节点选择器 NodeSelector

节点动作基于无障碍控件树定位,适合按钮、输入框、列表项等有文本、描述、ID 或可点击属性的目标。AI 应在可用时优先使用节点动作,而不是纯坐标动作。

  • NodeSelector 字段:packageName、viewId、text、description、className、textMode、descriptionMode、clickable、longClickable、enabled、editable、scrollable、selected、checked、visibleToUser、depth、indexInParent、stablePath。
  • textMode / descriptionMode 支持 EXACT、CONTAINS、FUZZY。
  • 常用稳定组合:viewId + className;text + clickable;description + enabled;editable=true 定位输入框。
  • 不要让 AI 只写“点击按钮”,应写清楚按钮文本、描述、ID 或候选定位方式。

结构节点字段清单

结构节点用于组织流程。AI 生成复杂脚本时,应使用结构节点表达条件、循环、变量、子流程和兜底,而不是把所有动作堆成一条长列表。

  • Action:原子动作节点。字段:action、config、enabled、id、displayName、comment、jumpLabel。
  • If:条件分支。字段:conditions、condition、timeCondition、varCondition、thenBlock、elseBlock、enabled、id、displayName、comment、jumpLabel。
  • VarSwitch:变量分支。字段:key、matchMode、cases、defaultBlock、enabled、id、displayName、comment、jumpLabel;matchMode 支持 TEXT_EQUALS、TEXT_CONTAINS、NUMBER_EQUALS。
  • Repeat:固定次数重复。字段:times、timesVarKey、block、intervalMillis、enabled、id、displayName、comment、jumpLabel。
  • Block:结构分组。字段:block、config、enabled、id、displayName、comment、jumpLabel。
  • TryCatch:失败兜底。字段:tryBlock、catchBlock、enabled、id、displayName、comment、jumpLabel。
  • Race:并行竞速。字段:leftBlock、rightBlock、enabled、id、displayName、comment、jumpLabel。
  • SubFlowDef:子流程定义。字段:name、params、block、enabled、id、displayName、comment、jumpLabel。
  • CallSubFlow:调用子流程。字段:targetName、paramBindings、enabled、id、displayName、comment、jumpLabel。
  • EventListener:事件监听。字段:eventName、labelTarget、targetSubFlow、paramBindings、async、writeEventToVars、eventNameVar、actionTypeVar、reasonVar、targetType、actionTargetId、actionTargetPath、action、actionConfig、variableNode、enabled、id、displayName、comment、jumpLabel。
  • Label:跳转标签。字段:name、enabled、id、displayName、comment、jumpLabel。
  • Goto:跳转到标签或节点。字段:target、enabled、id、displayName、comment、jumpLabel。
  • SetVar:设置变量。字段:key、value、scope、enabled、id、displayName、comment、jumpLabel;scope 支持 LOCAL、GLOBAL。
  • IncVar:递增变量。字段:key、delta、scope、enabled、id、displayName、comment、jumpLabel。
  • WhileVar:变量循环。字段:key、op、value、block、intervalMillis、maxIterations、estimateIterations、enabled、id、displayName、comment、jumpLabel。
  • WhileVision:视觉循环。字段:condition、block、intervalMillis、timeoutMillis、maxIterations、estimateIterations、enabled、id、displayName、comment、jumpLabel。
  • Break:跳出当前循环;Continue:进入下一次循环。

基础触控动作字段

基础触控动作适合坐标稳定、页面结构简单或需要模拟手势的场景。AI 应同时说明坐标来源、百分比坐标、等待和失败重试。

  • Delay:等待。字段:millis、millisVarKey。millisVarKey 不为空时从变量读取等待时间。
  • Tap:点击。字段:x、y、duration、xPct、yPct、elementRef、pointVarKey。pointVarKey 优先用于引用识别结果点。
  • MultiTap:连续点击或双击。字段:x、y、count、intervalMs、duration、xPct、yPct、pointVarKey。
  • TouchDown:按下触点。字段:x、y、pointerId、holdMs、xPct、yPct、pointVarKey。
  • TouchUp:松开触点。字段:pointerId、releaseMs。
  • MovePointer:移动已按下触点。字段:touchDownRefId、x、y、xPct、yPct、pointVarKey、duration、pathType。pathType 支持 POINT、LINE、POLYLINE、RECORD、CURVE。
  • DragToTarget:从起点拖拽到目标。字段:startX、startY、startXPct、startYPct、targetType、targetX、targetY、targetXPct、targetYPct、targetSelector、targetCondition、waitTimeoutMs、waitIntervalMs、duration;targetType 支持 COORDINATE、NODE、VISION。
  • LongPress:长按。字段:x、y、duration、xPct、yPct、pointVarKey。
  • Swipe:滑动。字段:fromX、fromY、toX、toY、duration、useBezierCurve、fromXPct、fromYPct、toXPct、toYPct、fromPointVarKey、toPointVarKey、fromSourceType、toSourceType、fromCondition、toCondition;点来源支持 COORDINATE、IMAGE、TEXT、COLOR。
  • SingleTouch:单点触控。字段:pointer。TouchPointer 包含 points、duration、pathType、touchDownRefId、targetPointVarKey、targetSourceType、targetCondition、targetSelector。
  • MultiTouch:多点触控。字段:pointers。适合双指缩放、组合手势等场景。

视觉点击与视觉等待动作字段

视觉动作适合页面内容不固定、目标位置随设备变化或需要识别文字、图片、颜色的场景。AI 应优先给出识别区域和失败处理。

  • ClickColor:识别颜色后点击。字段:condition、elementRef、outputs;condition 必须是 ColorAt。
  • ClickText:识别文字后点击。字段:condition、elementRef、outputs;condition 必须是 TextExists。
  • ClickImage:识别图片后点击。字段:condition、elementRef、outputs;condition 必须是 TemplateMatch。
  • WaitForVision:等待视觉条件满足。字段:condition、timeoutMillis、outputs。适合等待页面加载完成。
  • CheckVision:做一次视觉校验。字段:condition、outputs。适合条件分支前判断。
  • ScrollUntilVision:滚动直到视觉命中。字段:condition、maxScrolls、direction、swipeDuration、intervalMs、earlyEndOnNoChange、outputs。direction 支持 UP、DOWN、LEFT、RIGHT。
  • AI 建议:找列表项时使用 ScrollUntilVision;找到后把 pointVar 写入变量,再 Tap pointVarKey。

无障碍语义动作与节点动作字段

这些动作依赖无障碍服务和控件树,适合控件稳定的普通应用页面。AI 应给出 NodeSelector 或简化查找字段。

  • FindAndClick:查找并点击控件。字段:viewId、text、description、className、clickable。
  • FindAndInput:查找并输入。字段:inputText、targetViewId、targetText、targetDescription、targetClassName。
  • ScrollToFind:滚动查找文本。字段:text、maxScrolls、direction、intervalMs、earlyEndOnNoChange。
  • NodeClick:点击控件。字段:selector。
  • NodeDoubleClick:双击控件。字段:selector、intervalMs。
  • NodeLongPress:长按控件。字段:selector。
  • NodeInput:控件输入。字段:selector、inputText、inputTextVarKey、clearBeforeInput、submitMode、enterX、enterY、enterXPct、enterYPct、verify。submitMode 支持 NONE、TAP_COORDINATE、ENTER_KEY。
  • WaitNode:等待控件出现或消失。字段:selector、appear、timeoutMs、intervalMs。
  • NodeClearInput:清空输入。字段:selector。
  • NodeFocus:聚焦控件。字段:selector。
  • NodeSetChecked:设置勾选状态。字段:selector、checked。
  • NodeSwipe:在控件内滑动。字段:selector、direction、distanceRatio、durationMs。direction 支持 UP、DOWN、LEFT、RIGHT。
  • NoControlInput:无控件输入。字段:inputText、inputTextVarKey、focusX、focusY、focusXPct、focusYPct、pasteX、pasteY、pasteXPct、pasteYPct、trigger、longPressMs、enterX、enterY、enterXPct、enterYPct、backspaceX、backspaceY、backspaceXPct、backspaceYPct、doEnter、submitMode、doBackspace、verify。trigger 支持 TAP、LONG_PRESS。
  • InputVerifyConfig:输入校验。字段:mode、timeoutMs、useCustomSelector、selector、ocrLeft、ocrTop、ocrRight、ocrBottom、ocrLeftPct、ocrTopPct、ocrRightPct、ocrBottomPct、ocrCaseSensitive;mode 支持 NONE、FIXED_DELAY、NODE_TEXT_CHANGED、NODE_TEXT_MATCHES_INPUT、OCR_TEXT_CHANGED、OCR_TEXT_MATCHES_INPUT。

系统、提示、运行控制与脚本级动作字段

这些动作用于打开应用、打开链接、系统导航、展示提示、控制当前运行流程、调用其他脚本和切换虚拟控件方案。

  • GlobalAction:系统动作。字段:action;action 支持 BACK、HOME、RECENTS、NOTIFICATIONS。
  • OpenApp:打开应用。字段:packageName。
  • OpenLink:打开链接、文件或指定 Activity。字段:uri、target、uriVarKey、appPackageName、appActivityClassName;target 支持 URL、FILE、APP_ACTIVITY。
  • Prompt:运行提示。字段:displayType、title、content、durationMs、position、placementMode、customX、customY、customXPct、customYPct、simpleSize、customWidthPx、customHeightPx、placementAdjustsSize、vibrate、buttons。displayType 支持 DIALOG、SIMPLE、NOTIFICATION。position 支持 TOP、CENTER、BOTTOM。
  • PromptButtonConfig:提示按钮。字段:text、style、binding;style 支持 FILLED、TONAL、OUTLINED、TEXT。
  • RunControl:控制当前脚本。字段:controlType、jumpLabel、callTargetType、callSubFlowTarget、callActionTargetId、callActionTargetName、nodeEnableMode、nodeEnableTargetId、nodeEnableTargetName。controlType 支持 PAUSE、STOP、JUMP、CALL、NODE_ENABLED。
  • RunScript:运行其他脚本。字段:scriptId、scriptName、waitForFinish、inheritVariables、variableBindings。variableBindings 使用 key=value,多项用逗号或换行分隔。
  • SwitchVirtualControlScheme:切换虚拟控件方案。字段:schemeId、schemeName。
  • TriggerVirtualButton:触发虚拟按键。字段:controlId、controlName、triggerType、longPressMs;triggerType 支持 DEFAULT_ACTION、TAP、LONG_PRESS_RELEASE、PRESS_DOWN、RELEASE。

虚拟控件动作字段

虚拟控件用于运行态注册按键或摇杆,并通过变量或脚本动作驱动。AI 只有在用户明确需要虚拟控件方案时才应使用这些动作。

  • VirtualButton:注册虚拟按键。字段:controlId、displayName、triggerVarKey、triggerMode、pressType、x、y、xPct、yPct、coordJitterMinPx、coordJitterMaxPx、pointVarKey、swipeTargetMode、swipeToPointVarKey、swipeToX、swipeToY、swipeToXPct、swipeToYPct、swipeDirection、swipeDirectionVarKey、swipeAngleDeg、swipeDistancePx、swipeMode、swipeHoldBeforeMoveMs、swipeHoldAfterMoveMs、swipeDurationMs、overlayVisible、overlaySizeScale、cooldownMs、longPressMs。
  • VirtualButtonTriggerMode 支持 EDGE、HOLD;VirtualButtonPressType 支持 TAP、LONG_PRESS、SWIPE;VirtualButtonSwipeTargetMode 支持 STATIC_POINT、VARIABLE_POINT、DIRECTION_DISTANCE。
  • VirtualButtonSwipeDirection 支持 UP、DOWN、LEFT、RIGHT、UP_RIGHT、DOWN_RIGHT、DOWN_LEFT、UP_LEFT、ANGLE;VirtualButtonSwipeMode 支持 QUICK_SWIPE、HOLD_AND_DRAG。
  • VirtualJoystick:注册虚拟摇杆。字段:controlId、displayName、targetPointVarKey、referenceMode、referencePointVarKey、referenceX、referenceY、referenceXPct、referenceYPct、joystickCenterX、joystickCenterY、joystickCenterXPct、joystickCenterYPct、coordJitterMinPx、coordJitterMaxPx、joystickRadiusPx、deadZonePx、smoothFactor、updateIntervalMs、releaseDelayMs、overlayVisible。
  • VirtualJoystickReferenceMode 支持 SCREEN_CENTER、STATIC_POINT、VARIABLE_POINT。

AI 动作映射建议

AI 应把用户自然语言需求映射到 WeMod 支持的节点组合。下面是常见映射,生成脚本时可以直接采用。

  • 等待 2 秒:使用 Delay,millis=2000;如需用户可调,设置 millisVarKey=delay_ms。
  • 点击某个固定位置:使用 Tap,填写 x/y 或 xPct/yPct,并设置 postDelayMs。
  • 点击某段文字:优先使用 ClickText 或 NodeClick;如果文字来自 OCR 区域,使用 TextExists。
  • 找到图片后点击:使用 ClickImage;需要后续复用坐标时配置 outputs.pointVar。
  • 找不到按钮就下滑继续找:使用 ScrollUntilVision 或 Repeat + CheckVision + Swipe。
  • 输入文本到搜索框:优先使用 NodeInput;无法定位控件时使用 NoControlInput。
  • 页面可能有弹窗:使用 If + 视觉或节点条件;thenBlock 关闭弹窗,elseBlock 继续主流程。
  • 失败后重试三次:在动作 config 设置 retryTimes=3、retryIntervalMs=500。
  • 失败后执行兜底流程:使用 TryCatch 或 onFail=GOTO 跳到 Label。
  • 多个页面入口谁先出现就走谁:使用 Race,让两个分支同时等待不同视觉或节点。
  • 重复执行一段流程:固定次数用 Repeat;按变量判断用 WhileVar;按画面判断用 WhileVision。
  • 复用登录、打开目标页等流程:定义 SubFlowDef,再用 CallSubFlow 调用。

AI 输出示例格式

建议让 AI 按下面格式输出,用户再把每一步录入 WeMod 编辑器。AI 不需要直接输出项目内部序列化 JSON,除非用户明确要求。

示例:目标是打开 App 后搜索商品并点击第一个匹配结果。变量:search_text=关键词,delay_ms=800。节点 1 OpenApp packageName=目标应用包名,config.postDelayMs=1000。节点 2 WaitNode selector.text=搜索,appear=true,timeoutMs=5000。节点 3 NodeInput selector.text=搜索,inputTextVarKey=search_text,clearBeforeInput=true,submitMode=ENTER_KEY。节点 4 Delay millisVarKey=delay_ms。节点 5 ScrollUntilVision condition=TextExists(text=目标文字),maxScrolls=6,direction=DOWN,outputs.pointVar=target_point。节点 6 Tap pointVarKey=target_point,config.retryTimes=1。失败处理:若节点 5 未命中,Prompt 显示未找到目标并 STOP。

  • 每个节点都写动作名称和关键字段,不要只写笼统描述。
  • 给出变量默认值和变量用途。
  • 给出识别区域、超时、重试和失败处理。
  • 说明哪些字段需要用户在编辑器里用取点、取图、选择控件来填写。

安全边界与禁止事项

AI 生成脚本时必须遵守用户授权、平台规则和系统安全边界。WeMod 的脚本能力用于自动化用户本人设备上的合法操作,不应用于侵入、绕过、作弊、窃取或控制他人设备。

  • 不要生成绕过登录、绕过付费、绕过风控、绕过反作弊、批量刷量、恶意注册、恶意评论、薅羊毛、撞库等方案。
  • 不要生成读取、上传、泄露短信、通讯录、相册、位置、账号密码、验证码、Token 等隐私数据的方案。
  • 不要生成远程控制他人设备、隐藏控制、后台静默操作、规避用户确认的方案。
  • 涉及远程触控、WebRTC 屏幕连接和远程运行脚本时,必须明确用户授权、主动连接、可随时断开。
  • 涉及社区发布或脚本库发布时,应遵守脚本发布规范、投诉举报和内容治理规则。