maafw-pipeline

MaaFW Pipeline 开发

编写全流程分两条动线，动手前先分轨：

• 新建轨：从零新建流程（任务或子流程）——需求 → 拆分与状态清单（含探索取证）→ 文件结构与命名 → 素材准备 → 节点编写 → 流程组合 → 自查与交接。大任务逐级拆成子流程嵌套组合，每一层走同样步骤。
• 修改轨：在既有项目上改动、重构、审查——摸底 → 搜引用 → 修改 → 自查（见下文），不按新建顺序硬套。

字段精确语义（字段名、参数、默认值、版本支持）不在本文复制，一律路由 MaaLLMWiki 的 3.1-任务流水线协议：版本锁定、引用回源、不可达时标记"未验证"（已安装 maallmwiki skill 时由其承载完整路由流程）。执行模型是下文一切推理的基础，在此给出最小版：

执行模型（最小心智模型）

节点是三段式：识别 → 动作 → next。引擎在节点间如此运转：

1. 启动：任务由入口节点名启动（post_task），引擎初始化为"当前节点 = 入口节点、轮询列表 = [入口节点]"——入口作为唯一候选被识别（通常 DirectHit 恒命中）；若识别超时，用它自己的 timeout，未命中也走它自己的 on_error。
2. 轮询：当前节点动作完成后，对它的 next 列表按顺序轮询识别：每轮依次尝试各候选；本轮全未命中，等 rate_limit 后再截图重试（本轮候选全为 DirectHit 时跳过截图，零画面开销）。
3. 转移：第一个命中的候选立即胜出（后续候选不再检测），进入该节点、执行其动作——动作成功则轮询它的 next 列表（回到第 2 步）；动作失败走它的 on_error。
4. 超时归属：轮询超过当前节点的 timeout（缺省 20s）仍无命中 → 走当前节点的 on_error——想调整某节点被识别的等待时长或超时去向，改的是它上一节点的 timeout / on_error，不是它自己的。
5. 异常状态：
   • 进入（三种）：动作失败；轮询超时；被轮询列表中没有任何存在且启用的节点（不等 timeout 立即未命中——不存在的引用过不了加载校验，走到这一步的多为 enabled:false 节点或未设置的锚点）。
   • 进入后：on_error 列表接替 next 列表被同样轮询——on_error 为空时 next 立即为空、循环直接终止，任务以失败收场。
   • 解除：只由识别命中解除；命中后若动作失败，立即重新进入——因此结果上走出异常 = 命中且动作成功。
   • 异常期间收紧：再次未命中（on_error 轮询超时，或列表无任何存在且启用的节点——如恢复节点名拼错，不等超时立即失败）不进 on_error、任务直接失败；执行链走空时若仍处于异常状态，已登记的 [JumpBack] 回跳不生效，任务以失败终止。
6. 终止与成败：
   • 循环在 next 为空或外部 stop / StopTask 时终止；任务成败 = 终止时是否处于异常状态（正常态走空即成功）。
   • 唯一例外 [JumpBack]（仅正常态）：子链走空不终止，重新轮询父节点的 next 列表（从头按序识别；父节点不经识别恢复为当前节点，超时与 on_error 归属回到父节点，动作不重跑）。例如 A.next=["B","[JumpBack]C"]、C.next=["D"]、D.next=[]，C 命中走完 D 后重新轮询 A.next。

on_error 归属：候选被识别不算进入节点，命中后才算进入；进入后的执行动作与轮询 next 列表都发生在本节点内——动作失败走动作所在节点的 on_error，轮询 next 超时走 next 列表所属节点的 on_error。

硬护栏（全程生效）

1. 探索优先：要写的每个状态必须有真实观测证据（截图、OCR 文本、色值、box 等）；凭文档、节点名或记忆推断的状态一律视为 guessed，guessed 状态不得落笔。
   • 按转移推进：探索到哪个界面（以当前设备画面为准），就观测该界面的识别标志与点击目标；点击后实际观测到下一界面标志出现（即 next 出口候选），这条转移即可落笔。弹窗节点同样只在见过该弹窗后写；写到哪、观测到哪，不必全流程探索完再动笔；整段贯通与可重入不在落笔门槛内，但属于完成门槛（见第 6 步完成判据），轮到自查与端到端验收去跑。
   • 点击最小化副作用：非必要的提交/领取类按钮不点；能靠关键帧确认的状态不主动触发。
   • 不可复现状态（一次性奖励、首通引导、不可逆操作后界面）：用留存的关键帧代替——工具暂存的重要变化帧同样算观测证据，写前逐帧核对；连关键帧都没有的仍按缺口处理。
   • 复用与边界：复用已有节点时，其入口前提同样须观测确认；无法探索（无设备/无授权/禁副作用）就停下报告缺口；抢购、QTE 等毫秒级反应超出轮询模型，直接说明做不到。
2. 坐标卫生：点击目标由识别结果推导（细则见 references/anti-patterns.md）：
   • target 缺省 true（继承本节点识别 box），绝大多数节点不需要写；偏移用 target_offset 并注明依据；
   • 另指目标优先 string 引用（前置节点名 / [Anchor]锚点名，引用结果为空即动作失败）；固定坐标数组视同硬编码，仅特殊场景（如负坐标从边缘计算）使用并注明理由——严禁 DirectHit + 硬编码 target 坐标。
3. 不编造字段：字段名、参数、版本支持拿不准就路由，宁可少写用默认值；$ 开头 root 字段不解析、. 开头文件/文件夹不读取。
   • 注释约定：pipeline 按 jsonc 解析，纯说明优先 // 注释；结构化注释用 desc / _desc，占位提示用 code / _code（如 template_code），doc / _doc 尽量不用——均为非协议约定字段（引擎对未知键静默忽略）。
4. 基准分辨率中立：运行基准从项目 controller 配置动态获取（缺省 720 短边，兼容横竖屏）；量 ROI 的截图必须走框架截图链路，不用外部图片。
5. 循环必须有终止论证：凡执行会回到已执行节点候选列表的写法（[JumpBack] 回跳、next 成环），终止论证三选一并在注释说明：
   • 限次：max_hit / timeout + on_error 上报；
   • 识别门控：候选带真实识别、动作以消除该识别为目标，动作可能失效时仍配兜底限次；
   • 挂机意图：显式声明的无限产出循环，退出靠外部停止或条件节点，环内每轮有真实进展，重置计数须显式；
   • 超时与 DirectHit 铁律：timeout 只管"目标界面一直没出现"，管不了"一直命中停不下来"；DirectHit 禁入循环（恒命中无门控，且全 DirectHit 列表跳过截图、无法观测画面变化）。

新建轨

步骤 1–5 按段滚动推进：拆出的每个子流程各自走 1→5，探索一段、写一段，不必整个任务探索完再动笔；全部段落完成并自查后进第 6 步。

滚动推进必须伴随进度档案（跨会话的 working memory，外置成文件，放资源包外不被框架加载的位置）：记录需求与拆分结论（子流程清单）、每段实现状态（计划中 / 已编写 / 已测试）、每个已观测状态的证据帧编号、当前断点（设备停在哪个界面）。关键帧与状态绑定归档——它同时是 observed 证据、复测识别的素材（节点测试模式：截图 + hits/box 期望）、模板裁剪的来源。

1. 要件 → 分割と状態一覧（探索による証拠収集を含む）

• 分割してから翻訳（段階的に分割）：大きなタスクはまず、入口と出口が明確な（Start／End の接尾辞を付ける）サブフローに分割します。複数のタスクで再利用できるものは、リソースパッケージ内の pipeline/general.json にまとめます（ファイルの配置で再利用の境界を表し、ノード名の接頭辞には頼りません。references/project-structure.md を参照）。分割の境界は、独立して観測・検証できる画面区間／業務区間です。まずサブフローの大枠を定め、画面内の状態やポップアップは進行に合わせて段階的に追加します。
• 画面内の動線（まず同一画面、その後に出口）：画面に入ったら、まず同一画面内の例外処理ノードを記述してすぐにテストします（現在の画面から離れず、書き終えたらすぐテスト）。出口ノードは最後に記述し、書き終えてテストしたら、そのまま次の画面へ進みます。
• 状態への置き換え：フローを状態（開始状態、中間状態／ポップアップ、成功状態、失敗状態）に置き換え、各状態について次の2点を明確にします（選定の詳細は references/flow-patterns.md の第1ステップを参照）。
  • 認識方式の選定：固定画像は TemplateMatch、テキストは OCR、色領域は ColorMatch、視覚的変化がない場合は DirectHit、拡大縮小される対象は FeatureMatch、複雑な対象は NeuralNetworkClassify／NeuralNetworkDetect、複数条件の組み合わせは And／Or、複雑なロジックは maafw-custom に切り替えます。
  • 証拠の状態：observed または guessed と記します（observed の場合のみ記述し、guessed の場合はまず探索します）。

2. ファイル構造と命名

• ファイル構成：新規作成では、既定でモジュール接頭辞形式＋PascalCase のファイル名（AutoCollect/AutoCollectRoute1.json）を使います。既存のフラットなプロジェクトでは従来どおりとし、追加する新しいモジュールにはディレクトリを作成できます。タスク間で共有するファイルには general.json（小文字が慣例）を使用します。詳細は references/naming.md と references/project-structure.md を参照してください。
• JSON のバージョン：新規作成では、既定で Pipeline v2 のネスト形式（recognition／action を {type, param} に統一、MaaFW v4.4.0+、名前空間を分離してフィールドのずれによる不具合のサイレントな発生を防止）を使います。既存のプロジェクトでは既存の主流スタイルに従い、プロジェクト内で統一します（references/flow-patterns.md の例の注記を参照）。
• ノードと素材の命名：ノード名はファイルをまたいでグローバルに解決され、大文字と小文字を区別します。同じパッケージ内で名前が重複するとエラーになります。$ で始めず、[ ] は使用しません。タスク_画面_対象_役割_バリエーション の語順に従って構成します（詳細は references/naming.md を参照）。image/ はモジュールごとにディレクトリを分け、リソースディレクトリ内のフォルダー名を _ で始めないでください（Android のパッケージ化に関する制限）。

3. 素材の準備

• ピクセル空間を統一：テンプレートは、基準解像度のフレームワークスクリーンショット（非可逆拡大縮小後）から切り出します。エミュレーター内蔵のスクリーンショットは、解像度が基準と一致し、通知バーやウォーターマークがなく、非可逆圧縮の影響を受けていない場合に限り使用できます。カメラで撮影した画面や、縦横比が一致しない画像は使用できません。動的な数字やアニメーションを避けて切り出します。
• ツールの選定：エージェントによる自律ワークフローでは、リアルタイム観測の基盤（例：maafw-live の crop／color／annotate／crop --from-kf。動線の確認には付属の maafw-live skill を使用）を優先するか、スクリプトを自作してフレームワークのスクリーンショット経路を利用します。人が作業に参加している場合は、公式ツールチェーン（VSCode Maa Pipeline Support（maa-support / MSE）／MFA ツールボックス／MPE）を使用できます。
• 切り出し後の自動マッチング再確認：新しいテンプレートは、元フレーム内の元の位置で必ずマッチする必要があります（スコアより位置の正しさを優先）。切り出したらすぐに検証します。

4. ノードの記述

• 認識とアクション：各状態につき1つのノードを作成し、認識してからアクションを実行します。roi は対象が現れる領域まで絞り込みます（認識 box を約 20px 外側に広げた位置を開始点とし（経験値）、安定しない場合は複数の幅で試します）。アクションの選定とパラメーターは《タスクパイプラインプロトコル》と照合し、クリック位置は座標の衛生管理（ハードガードレール 2）を守ります。
• 状況に応じた only_rec の選択：これは「認識精度を上げる」ためのスイッチではありません。誤って使うと認識テキストとクリック位置の両方がずれてしまいます。判断基準と使い方は references/anti-patterns.md を参照してください。
• ノード通知（focus）：実行ログ／ヒント／ポップアップを表示する必要がある場合は focus を設定します（{name} プレースホルダーと $ i18n に対応。display でチャネルを選択し、trace は interface.json で telemetry を設定した場合にのみ有効です。ルーティングについては《タスクパイプラインプロトコル》と《ProjectInterface V2》を参照）。
• パラメーターの初期値：TemplateMatch の threshold は、対象位置で実測したスコアから約 0.1 引いた値を初期値とし（経験値）、同じ画面内で誤マッチする候補の最高スコアより高くします。両者の差が小さすぎる場合はテンプレート／roi の問題であり、閾値を調整しても解決できません（OCR／ColorMatch は意味が異なり、FeatureMatch は count／ratio で制御します）。固定の delay より *_wait_freezes を優先します。
• 書き込みルール：差分挿入を採用して JSONC の // コメントを保持し、インデントとフィールド順をプロジェクト既存の規約に合わせます。座標には必ず、フレームワークで拡大縮小した後の座標系で実測した値を使用します。

5. フローの組み立て

5つのステップの詳細な展開、コード例、安定性の原則は references/flow-patterns.md を参照してください。主な基準は次のとおりです。

• 主経路：最短で成功する経路を、直線的な next チェーンにします。画面遷移は「対象の出現を待つ」ノードで表し、遅延とノードの timeout は既定値のままにします。*_wait_freezes を使う場合、内部の timeout は既定で 20s です。待機領域でアニメーションが継続する場合は、フォールバックとして 1～2s の短い値を設定することがよくあります（経験値）。
• 分岐：next の順序が優先順位になります。まず遮蔽の制約を優先し（同時にマッチする特例候補を汎用候補より前に置き、順序の逆転による無限ループを防ぎます）、それ以外はマッチ頻度の高い順に並べます。相互排他的な分岐は順序で処理し、ソートには order_by を使い、同一画面での条件の組み合わせには And／Or を使います。
• ループと中断：ループ本体と出口は同じリストに配置し、max_hit を設定します（ハードガードレール 5）。ランダムなポップアップ／読み込みは独立したノードにし、重要な待機ポイントに [JumpBack] で接続します（通常状態の場合のみ動作します）。分岐をまたぐ動的な合流には anchor を使います（未設定の場合は暗黙にスキップされるため、前段の経路ですべてをカバーする必要があります。詳細は references/flow-patterns.md を参照）。
• 待機と再試行の分離：待機はパラメーターで表現し、自己参照構造は記述しません。再試行は実測で失敗率が確認された場合にのみ追加し、まずは単一ノードの自己参照と max_hit を使います。独立した予算が必要な場合、または戦略を変更する場合に限り、Retry／Fallback の複製ノードを作成し、異なる点を明記します（詳細は references/flow-patterns.md を参照）。
• 失敗経路：各 next リストには timeout と、安定してマッチする on_error のフォールバックを設定します（例外状態で再度失敗した場合の二重のフォールバックはありません）。on_error は例外からの復旧にのみ使用し、通常の分岐には使いません。認識によるゲートなしに連続クリックすることは禁止です。アクションエラーは自己参照で無理に繰り返さず、収束させます。

6. 自己確認と引き継ぎ

• 完了の判定基準（必須ゲート）：「書き終えた」段階は「実行可能」にすぎません。プロジェクトのエントリーポイントから実機でタスクレベルの成功まで実行し、失敗ノードと前提条件を記録していない pipeline は、完了を宣言してはならず、納品説明や PR の検証項目にも記載してはなりません。判定基準はタスクレベルの結果のみで、呼び出し層のシグナルは対象外です。予算を使い切って中断された場合（status=0 + stopped=true、ツール側のフィールド。使用する実行ツールのドキュメントに従ってください）は成功でも失敗でもなく、合格とはみなしません。タスクレベルの失敗は具体的なノード名まで記録する必要があります。終端状態に到達できなかった場合は、「終端状態まで実行できず」と正直に記載し、停止したノードを示します。「N 秒間実行して異常がなかった」を合格の代わりにしてはなりません。完了を宣言する前に maafw-debug を読み込み、受け入れテストを行います。
• 完全性に関する4つの確認事項と到達可能性：孤立ノードがないこと、anchor のリンク切れがないこと、未解決の参照がないことを確認します。主経路が実行できること、ポップアップを処理できること、読み込み完了を待てること、対象の状況にない場合の動作が明示的に定義されていること（スキップまたはエラー）も確認します。tests/ の基盤があるプロジェクトでは、認識の回帰テストケースを追加します。
• 段階をまたぐ引き継ぎ：エンドツーエンドの受け入れテストは必ず maafw-debug が担当します（この skill では受け入れ判定を行いません）。単一ノードの検証も同様に maafw-debug が担当します。task のエントリーポイントとオプションの接続は maafw-interface、JSON で表現できないロジックは maafw-custom が担当します。デバイスがない、または実機での実行が許可されていない場合は「未検証」と正直に記載し、未対応の箇所を残します。静的な自己確認に合格したことを、受け入れテストに合格したかのように表現してはなりません。

修改轨（存量项目入口）

1. 摸底（按改动规模伸缩，走索引不通读）：小修直接定位目标节点与上下游；结构性改动先看目录树与 interface.json 任务清单 → 脚本提取节点名索引（列 root key）→ 按词位关键词检索，共享件先查 general.json；动手前明确改动边界。
2. 搜引用：改节点名或素材路径前全库搜索——漏改后果按引用位置分四档（加载期报错 / 运行期失败 / 调用即失败且不回滚 / 静默失联或漂移），各档覆盖的引用面与跨语言 get_anchor 细则见 references/naming.md 的引用核对表。
3. 修改：按新建轨 2–5 的同等标准增量修改。
4. 自查：可达性检查 + 反模式清单逐项核对（见 references/anti-patterns.md）。

深入阅读（按需）

• references/naming.md — 文件/目录/节点/图片命名规范与改名全库搜引用核对表
• references/project-structure.md — 仓库布局、多资源包、共享节点归置与覆盖更新硬限制
• references/flow-patterns.md — 流程设计五步法、等待重试分层、模式示例与稳定性法则
• references/anti-patterns.md — 坐标卫生细则、反模式对照表与审查清单