feat(pipeline): run_pipeline/benchmark_node 支持单次 pipeline_override 与工具侧 timeout_seconds

[qiyinxi]

动机

单节点验证目前有两个工具侧缺口（Everything-Maa 的 maa-pipeline-testing skill 把它记成了「单节点验证的工具限制」，只能靠工作流绕过）：

1. 没有「只截 ROI 区域验证」的参数 —— 想收紧 roi 只能改 pipeline 文件再重新保存；不改就得忍受整屏 OCR 慢扫。
2. 没有工具侧超时 —— run_pipeline 在 task_job.wait() 上无限阻塞。识别不命中的节点会烧满自己的 timeout（默认 20s），MCP 调用只能干等，客户端超时后连诊断信息都拿不到。

改动

run_pipeline 新增 pipeline_override（可选，默认 None）

单次运行的字段级节点覆盖，直接传给 Tasker.post_task(entry, pipeline_override)（与 interface.json 的 pipeline_override 同机制）：

run_pipeline(cid, "main.json", entry="点击设置", start_agent=False,
             pipeline_override={"点击设置": {"roi": [520, 20, 200, 80], "timeout": 3000}},
             timeout_seconds=10)

• 按字段合并：只覆盖给出的字段，节点其余参数保留（已在 maafw 5.8.1 实测确认）
• 只对单次生效：不写文件、不污染 Resource（实测确认连跑三次行为一致）
• 覆盖的节点名不在本次加载文件中时进 warnings 提示（拼错节点名时覆盖会静默不生效，这是最常见的踩坑点；但不阻断——它也可能是 bundle 里的节点或新增节点）

run_pipeline 新增 timeout_seconds（可选，默认 None = 保持旧行为）

轮询任务状态，超时调 tasker.post_stop() 主动停止，返回结构化结果：

• status="timeout"、success=false、error 说明原因与排查建议
• nodes 携带超时前已执行的部分节点详情，方便定位挂在哪个节点
• 注意：MaaFramework 会把被 stop 的任务自身 status 标记为 succeeded（实测确认），所以这里显式报 "timeout"，不信任 detail.status
• 显式拒绝 NaN / ±inf / 超出 float 范围的巨大整数：JSON 层（jiter/pydantic）会放行 NaN/Infinity/1e400，而 deadline = monotonic() + NaN 会让超时分支永远不触发——静默禁用超时还带 CPU 空转轮询（多智能体对抗评审发现并实测确认）

benchmark_node 新增 pipeline_override（同语义）

调参循环（issue #36 item #4）里免改文件试 roi / threshold，确定后再写回 pipeline JSON。也可用 {"节点": {"timeout": 2000}} 压缩未命中时的单次迭代耗时。为保护 benchmark 的 entry → node → done 隔离链路，覆盖 entry / node 的 next 会直接报参数错误。

语义验证

用 maafw 5.8.1 + CustomController（黑屏 + 白块假屏幕）实测确认：

验证项	结果
错误 roi 无覆盖 → 识别失败	✅（3.02s，烧满节点超时）
只覆盖 roi → 识别成功，box=[100,100,50,50]	✅（0.42s，字段级合并成立）
覆盖后再跑无覆盖 → 仍失败	✅（Resource 未被污染）
post_stop 打断 60s 节点	✅（stop+wait 共 ~0.01s 返回）

测试

• tests/test_pipeline_override_timeout.py（新增，49 个用例）：参数校验、_wait_task_with_timeout 轮询/超时路径、run_pipeline 透传与超时返回结构、benchmark_node 保护与 warnings 序列化——全部纯函数 + 假件，不依赖 maafw 运行时
• tests/test_dbg_pipeline.py（扩展，3 个用例）：DbgController 端到端——override 翻转识别结果、超时停止挂死节点、无害覆盖不影响成功。与现有用例一样由 MaaDbgControlUnit DLL 门控（当前 maafw wheel 未打包该 DLL 时自动 skip）
• 全量：239 passed, 5 skipped（Windows / Python 3.12）

向后兼容

• 两个新参数默认 None，不传时行为与现在完全一致（post_task(entry, {}) 与 post_task(entry) 等价，maafw 默认值就是 {}）
• 返回结构只新增 status 取值 "timeout"（仅在显式传 timeout_seconds 时可能出现）；BenchmarkRunResult 只在非空时序列化 warnings（与 PipelineLoadResult 的省略风格一致）
• 文档同步：README.md / README_EN.md 新增「单节点快速验证」小节；CLAUDE.md / CLAUDE_CN.md 按同步规则更新工具行为注记与调参循环

🤖 Generated with Claude Code

Sourcery 摘要

通过支持按运行覆盖节点配置和有界执行时间，实现更快速、更安全的单节点流水线验证。

新功能：

• 为 run_pipeline 和 benchmark_node 添加按运行的 pipeline_override 支持，无需修改流水线文件即可调整节点级参数。
• 为 run_pipeline 添加可选的工具侧 timeout_seconds 处理，并提供结构化的超时结果和部分节点诊断信息。

Bug 修复：

• 防止无效的非有限超时值默默禁用超时控制。

增强功能：

• 当流水线覆盖项引用了已加载文件中不存在的节点时发出警告，同时保持执行继续进行。
• 通过拒绝覆盖入口和目标隔离的 next 字段，保护 benchmark 的入口和目标隔离。

文档：

• 使用中文和英文用户文档及工作流文档，记录单节点验证、按运行覆盖、超时行为以及无需文件的 benchmark 调优。

测试：

• 添加针对参数验证、覆盖传播、超时轮询与停止、警告序列化、benchmark 保护机制以及向后兼容默认值的单元测试覆盖。
• 添加受门控的端到端测试，覆盖识别覆盖、工具侧停止挂起节点以及无害覆盖。

Original summary in English

Summary by Sourcery

Enable faster and safer single-node pipeline verification by supporting per-run node overrides and bounded execution time.

New Features:

• Add per-run pipeline_override support to run_pipeline and benchmark_node for field-level node parameter tuning without modifying pipeline files.
• Add optional tool-side timeout_seconds handling to run_pipeline with structured timeout results and partial node diagnostics.

Bug Fixes:

• Prevent invalid non-finite timeout values from silently disabling timeout enforcement.

Enhancements:

• Warn when pipeline overrides reference nodes absent from the loaded files while preserving execution.
• Protect benchmark entry and target isolation by rejecting overrides of their next fields.

Documentation:

• Document single-node verification, per-run overrides, timeout behavior, and file-free benchmark tuning in Chinese and English user and workflow documentation.

Tests:

• Add unit coverage for parameter validation, override propagation, timeout polling and stopping, warning serialization, benchmark protections, and backward-compatible defaults.
• Add gated end-to-end coverage for recognition overrides, tool-side stopping of hanging nodes, and harmless overrides.

[sourcery-ai]

嘿——我已经审阅了你的更改，看起来很棒！

---

Sourcery 对开源项目免费——如果你喜欢我们的评审，请考虑分享它们 ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{请帮我变得更有用！请在每条评论上点击 👍 或 👎，我会利用这些反馈来改进评审。}

Original comment in English

Hey - I've reviewed your changes and they look great!

---

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.}