docs: 阐明 jump_back 在 on_error 场景下的回跳机制

[sunyink]

TL;DR — Docs only. The jump_back section says jump-back is not performed "if the current flow is in the error-handling path (on_error)". error_handling is a transient flag, not a path: it is cleared the moment any node is matched, from a next or an on_error list. Pending jump-backs are discarded only when nothing catches the error. Wording corrected in both zh_cn and en_us; no behavior change.

问题

3.1 的 jump_back / [JumpBack] 一节原文：

若当前流程处于错误处理路径（on_error），则不会执行回跳。

「路径」读起来像一块区域——只要还在 on_error 列表里就都算，于是很容易得出「on_error 里写 [JumpBack] 一律无效」、「子节点链中途进入on_error后就不会回跳」的结论。但实现里它是一个瞬时状态位，不是区域。

实现

source/MaaFramework/Task/PipelineTask.cpp 的 run()：

if (node_detail.reco_id != MaaInvalidId) {
    error_handling = false;          // 任一节点被识别命中 -> 立即清除
    ...
}
...
if (next.empty() && !error_handling && !jumpback_stack.empty()) {
    ... pop ...                      // 回跳栈仅在非异常状态下弹出
}
...
return !error_handling;              // 带着异常状态退出循环 = Task 失败

error_handling 由「next 列表识别超时」或「节点动作执行失败」置位，被任何后续节点的识别命中清零——不区分该节点来自 next 还是 on_error。因此：

情形	是否回跳	Task
节点 next 识别超时 → on_error 中有节点命中	✅ 正常回跳	成功
节点动作失败 → 其 on_error 中有节点命中	✅ 正常回跳	成功
进入异常状态时 on_error 为空 / 其中全部未命中	❌ 待执行的回跳点全部作废	失败

原文那句话只对第三种情形成立。

验证

在 5.11.1 与 5.12.2 上各跑了一组单变量对照（CustomController 恒定截图 + 恒不命中的 CustomRecognition + 计数用 CustomAction），两个版本结果完全一致：

用例	形状	结果
C0（负对照）	next: ["B"]	执行一次结束
C1（正对照）	next: ["[JumpBack]B"]	循环 ✅ 观测手段有效
E3（E1 对照）	next 超时 → on_error: ["B"]	执行一次结束
E1	next 超时 → on_error: ["[JumpBack]B"]	循环 ✅ 回跳生效
E2	动作失败 → on_error: ["[JumpBack]B"]	✅ 回跳生效（返回该节点后继续识别其 next）
E4	已压栈的回跳 + 下游 on_error 为空	❌ 不回跳，Task FAILED
E5（E4 对照）	同 E4，但 on_error 放一个 DirectHit 节点	✅ 回跳恢复，循环

E1/E3 与 E4/E5 各自只差一个变量：前者是 [JumpBack] 前缀的有无，后者是 on_error 里有没有节点接得住。E4/E5 这一对正是原文那句话真正成立的边界。

E2 的事件序列（Node.* 回调）：

Node.Action.Failed          :: E2_Fail     # 动作失败，进入异常状态
Node.NextList.Starting      :: E2_Fail     # 进入 E2_Fail 的 on_error
Node.Recognition.Succeeded  :: E2_B        # [JumpBack]E2_B 命中 -> 异常状态清除
Node.Action.Succeeded       :: E2_B
Node.PipelineNode.Starting  :: E2_Fail     # 回跳发生
Node.NextList.Starting      :: E2_Fail     # 重新识别 E2_Fail 的 next
Node.Recognition.Succeeded  :: E2_BackProbe

改动

只改措辞，把「错误处理路径」明确为「错误处理状态」，并补上它的进入与解除条件；jump_back 一节的主句改为讲「已登记的回跳在后续链失败时是否兑现」——这才是该节的正题，「on_error 里能否写 [JumpBack]」作为推论放在末尾一句。同时同步了「终止条件」与「执行流程」中相应的两处表述。中英文对称。

变更日志中 v5.1 / v5.9 的历史条目未改动。其中 v5.9 的「（错误处理路径不触发回跳）」同样偏宽，但属历史记录，若维护者认为需要一并修正，我可以补上。

🤖 Generated with Claude Code

Summary by Sourcery

在流水线任务文档中澄清关于错误状态和错误处理的跳回（jump-back）行为说明，而不更改运行时行为。

文档更新内容：

• 优化跳回终止条件的描述，明确说明只有在流程不处于错误状态时才会发生跳回。
• 更新英文和中文的 jump_back 选项文档，解释“瞬时错误状态”的含义、进入与清除该状态的方式，以及在 on_error 中匹配到 [JumpBack] 后其仅会生效一次。
• 调整执行流程的描述，使得在发生跳回后是否返回到父节点取决于当前是否处于错误状态。

Original summary in English

Summary by Sourcery

Clarify the jump-back behavior in pipeline task documentation around error states and error handling, without changing runtime behavior.

Documentation:

• Refine the description of jump-back termination conditions to specify that jump-back occurs only when the flow is not in an error state.
• Update the jump_back option docs in both English and Chinese to explain the transient error state, how it is entered and cleared, and that [JumpBack] inside on_error works once matched.
• Align the execution flow description so that returning to the parent node after a jump-back depends on not being in an error state.

[sourcery-ai]

Hey - 我在这里给出了一些高层次的反馈：

• 建议将“error state（错误状态）”的定义从当前局部引用块中移出，放到一个专门的术语表/术语章节中，然后在这里引用它，这样可以在整个协议文档中一致地复用这个术语。
• 终止条件中的短语“if [JumpBack] points exist and the flow is not in the error state（如果存在 [JumpBack] 点且流程不处于错误状态）”可以更明确地与后文的定义关联起来（例如：“not in the transient error state described below（未处于下文所述的瞬时错误状态）”），以避免与其他错误处理概念混淆。

给 AI 代理的提示

Please address the comments from this code review:

## Overall Comments
- Consider moving the definition of the “error state” out of a local blockquote into a dedicated glossary/terminology section and referencing it here, so the term can be reused consistently across the protocol docs.
- The phrase “if `[JumpBack]` points exist and the flow is not in the error state” in the termination conditions might be clearer if it explicitly ties to the later definition (e.g. “not in the transient error state described below”) to avoid confusion with other error-handling concepts.

---

Sourcery 对开源项目是免费的——如果你觉得我们的评审有帮助，请考虑分享 ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{帮我变得更有用！请对每条评论点击 👍 或 👎，我会根据你的反馈改进后续评审。}

Original comment in English

Hey - I've left some high level feedback:

• Consider moving the definition of the “error state” out of a local blockquote into a dedicated glossary/terminology section and referencing it here, so the term can be reused consistently across the protocol docs.
• The phrase “if [JumpBack] points exist and the flow is not in the error state” in the termination conditions might be clearer if it explicitly ties to the later definition (e.g. “not in the transient error state described below”) to avoid confusion with other error-handling concepts.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Consider moving the definition of the “error state” out of a local blockquote into a dedicated glossary/terminology section and referencing it here, so the term can be reused consistently across the protocol docs.
- The phrase “if `[JumpBack]` points exist and the flow is not in the error state” in the termination conditions might be clearer if it explicitly ties to the later definition (e.g. “not in the transient error state described below”) to avoid confusion with other error-handling concepts.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}