maafw-custom

MaaFW Custom 开发

Pipeline 表达不了的逻辑用 Custom 补齐：读外部状态、跨节点数据传递、动态计数、复杂判定、自定义识别算法。binding 类签名与 context API 不凭记忆写，一律路由 MaaLLMWiki 的 bindings / native-api 索引（版本锁定、引用回源；已安装 maallmwiki skill 时由其承载完整路由流程）。

硬护栏

1. 能 pipeline 不 custom（默认方向，由成本非对称决定而非偏好）：
   • 为什么偏 pipeline：custom 节点的外层仍受引擎调度与观测——next 候选顺序（先命中先执行）、max_hit、on_error、focus、option 的 pipeline_override 照常生效，run_task 起的子流程也由引擎执行。失去自动约束的是回调内部——内部循环 / 等待 / 网络 IO 不展开为节点图，节点 timeout 打不断阻塞中的回调，耗时、取消、重试、内部状态全靠自己管，对工具链只剩日志。
   • 一律 pipeline：视觉可判定的等待 / 点击 / 滑动 / 找字 / 循环 / 分支——循环 = next 环 + 出口 + max_hit（固定次数重复用 repeat / repeat_delay / repeat_wait_freezes，MaaFW v5.3+），分支 = next 顺序 + 遮蔽。
   • 才上 Custom：依赖画面外运行时数据（文件、网络、进程状态、时间）的读取或以其为判据的控制流；识别 / 动作字段表达不了的判定；外部调用。
   • 字段表达力的两条硬边界（实证项目 custom 存量的大头就在这）：
     • And / Or 是布尔组合——无数值比较、无跨节点算术（数值比较、多节点数值表达式是 custom 的地盘）；组合期唯一数据流是 box：box_index 选输出、sub_name 传 filtered box 作 ROI、Or 取命中者 box；
     • max_hit 只会递增，pipeline 字段读不到也清不掉命中计数——custom 内可用 get_hit_count / clear_hit_count（作用域：当前任务与其 run_task 子任务共享）；跨节点"数据"仍无字段通道——anchor 是节点名变量（写 / 清 / 引用三态），不是数据存储。
   • 该转 custom 的反信号：为表达一段逻辑开始堆克隆节点、节点图膨胀难读、开始需要运行时改参数或计数（override / 状态类标准件频繁登场）——继续拆不如转。
   • 判据拿不准先回 maafw-pipeline 试拆节点。
2. 失败要显式，且分清三种语义：
   • CustomRecognition 返回未命中 = 本候选不命中——轮询继续试后面的候选，整轮全未命中等宿主节点 timeout 后走宿主的 on_error（不是立即触发）；
   • CustomAction 返回失败 = 走动作所在节点的 on_error；实现异常不吞、显式失败返回——静默假成功是排障噩梦；
   • binding 侧空返回值语义要查再写（样例：Python 动作 run 返回 None 等价成功、识别 analyze 返回 None 等价未命中——漏写 return 在动作侧就是静默假成功；以 binding 路由为准）；
   • 直调 context.run_recognition() 只返回识别结果，错误分支由调用方自理。
3. 注册名逐字符一致：注册名（装饰器或注册表中的字符串）与 pipeline 节点引用完全一致，区分大小写。改名时同步所有注册点（引用点全表见 maafw-pipeline 的 naming.md）：
   • 注册表与 pipeline 引用：装饰器/注册表、pipeline 的 custom_recognition / custom_action（先改 pipeline 用法再改注册）、有 Schema 基建则含 enum；
   • Custom 代码内节点名引用：run_task / run_recognition / run_action 的 entry、override_next 的目标也在同步面——调用即失败（返回值要判），不是静默失联；
   • 素材路径：同样在同步面，但框架不替你报错——自定义代码读图必须自查加载结果（空图即失败），漏改多表现为静默空转。
4. 签名路由：analyze / run 的参数结构、context API 随 binding 版本演进，以路由结果为准，本文样例仅作形态示意；不依赖框架未承诺的钩子（如 stop / 中断回调——有没有、叫什么以路由结果为准）。框架不会主动打断回调——长循环自查停止条件、外部 IO 设超时、资源清理用 finally / RAII 等该语言机制。
   • Context 能力面（上了 custom 之后有哪些杠杆；名字以 binding 路由为准）：
     • 执行与等待：run_task / run_recognition / run_action（按节点跑，识别与动作配对）；run_recognition_direct / run_action_direct（不建节点直接用引擎算法）；wait_freezes（引擎等画面静止，内部自截图）；
     • 补丁与节点定义：override_pipeline / override_next / override_image（补丁三件）；get_node_data（读当前有效节点定义，含补丁）；
     • 状态与实例：set_anchor / get_anchor（锚点读写）；get_hit_count / clear_hit_count（计数读清）；get_tasker（取 controller / resource——截图链的前提）；clone（分叉 context）。
5. 状态最小化：custom 内尽量无状态；确需跨调用记忆（如"仅首次执行"哨兵）要注明生命周期——agent 进程存活期间类状态跨任务共享，任务重入会带着上次的值。

工作流

1. 定宿主与注册路径（先于一切实现决策）：能不能进程内注册由谁拥有主程序决定——细则、agent 段接线与架构见 references/agent-mode.md。

2. 判型：

   • 自定义识别算法 → CustomRecognition（analyze 返回命中 box）；
   • 外部调用 / 复杂动作 → CustomAction（run 返回成功失败）；
   • 横切钩子（全局检查、失败引导）→ sink 通道而非散进 action（细则见 references/patterns.md「事件监听」）。

   特例不与上列并列：非标设备控制走 CustomController——按控制器接入而非注册（子类 + 工厂构造后 bind 给 Tasker），且仅掌控宿主进程时可行，agent 子进程内框架不提供控制器创建（见 references/agent-mode.md 的 agent 能力面）。

3. 最小注册闭环：先接最小节点（DoNothing + 日志）跑通"注册 → pipeline 引用 → 被调到"，再填实现。

4. 建文件与实现：

   • 按业务能力分文件，与 resource 的模块目录对齐（文件形态随语言惯用法，判据见 references/patterns.md「模块边界」）；
   • 通用可复用件进共享件目录；注册进唯一的注册点（装饰器或集中注册表）；
   • 参数从 pipeline 的 custom_action_param / custom_recognition_param（JSON）进入，经解析工具函数做类型 / 必填 / 默认值处理与运行时校验后使用，不裸取字段；实现自带行为契约文档（docstring / 注释等该语言惯例）——写清预期行为与参数语义（节点接线见 references/patterns.md「参数契约」）。

5. 复用而非重写：

   • custom 内需要识别 / 动作时优先引用既有 pipeline 节点——context.run_recognition("<节点名>", image) 直接跑某节点的识别；
   • 图像来源按用途：识别回调判定本次画面用 argv.image；动作后要新画面经既有 controller 主动截图等完成后再取图（样例形态 context.tasker.controller.post_screencap().wait().get()，名字以 binding 路由为准）；cached_image 属 controller、是最近一次已完成截图的缓存、不会自己刷新——时效可接受才用；
   • 识别 → 操作 → 再识别法则在 custom 内同样成立（见 maafw-pipeline 的 flow-patterns.md）。

6. 失败、取消与状态作用域：失败三语义见硬护栏 2；长循环与外部 IO 的取消策略见硬护栏 4；跨调用状态的生命周期注明（硬护栏 5）；override 补丁写明对象、作用域与生命周期（见 references/patterns.md「状态与作用域」）。

7. 验证：日志带节点名 + 入参摘要 + 结果摘要（这是排错唯一线索）；单元验证后转 maafw-debug 单节点流程与端到端。

审查清单

• 判据：这个逻辑真的 pipeline 表达不了吗？有没有把流程控制藏进 custom（回调内部不展开为节点图）？
• 命名能自解释：注册名与 pipeline 节点命名风格对齐（惯例 PascalCase），项目内统一。
• 参数底线：入口运行时校验——类型 / 必填 / 默认值 / 错误行为明确；有 Schema 基建的项目同步 enum 与注册名，并确认校验入口真的覆盖（建文件本身不产生校验）。
• 失败路径：三种失败语义分清；没有裸 except: pass；空返回值的 binding 语义核对过。
• 阻塞与取消：长循环有停止检查、外部 IO 有超时、清理有 finally / RAII 等机制。
• 注册点：改名改删时，pipeline 用法 → 注册点 → （有 Schema 则含 enum）→ custom 代码内节点名引用与素材路径，全部同步。

深入阅读（按需）

• references/patterns.md — Custom 实现决策指南：注册与加载、模块边界、参数契约与节点接线示例、Pipeline 复用、状态作用域、失败取消、事件监听、验证
• references/agent-mode.md — Agent 子进程模式：启动到退出的阶段职责、连接标识符、PI_* 容错、双日志、宿主与隔离决策