feat: "$Default" - file default node by MistEO · Pull Request #1172 · MaaXYZ/MaaFramework

MistEO · 2026-03-03T08:25:09Z

Summary by Sourcery

通过使用“$Default”和以“$”为前缀的算法/动作键，引入文件级和 bundle 级默认流水线配置，并将运行时覆盖与全局默认流水线状态解耦。

新功能：

支持在单个流水线 JSON 文件中使用“$Default”节点，为后续节点定义文件级默认属性。
在默认流水线配置中允许使用以“$”为前缀的算法和动作键（例如 “$TemplateMatch”、“$Click”），并兼容旧版的非前缀键。

增强：

将 bundle 级的 default_pipeline.json 进行作用域限制，使其默认值仅应用于同一 bundle 内的节点，避免默认配置在 bundle 之间相互污染。
移除在 ResourceMgr 和 Context 中对全局存储的 DefaultPipelineMgr 的依赖，在解析流水线和覆盖配置时改为使用按 bundle 或内建的默认值。
放宽多个解析器（流水线、识别、动作、wait_freezes），在未显式提供默认值时使用内建的默认参数值，从而简化覆盖逻辑处理。

文档：

更新英文流水线协议文档，说明文件级默认“$Default”、以“$”为前缀的默认键、修订后的继承优先级，以及 default_pipeline.json 在 bundle 作用域中的行为说明。

Original summary in English

Summary by Sourcery

Introduce file-scoped and bundle-scoped default pipeline configuration using "$Default" and "$"-prefixed algorithm/action keys, and decouple runtime overrides from global default pipeline state.

New Features:

Support a "$Default" node inside individual pipeline JSON files to define file-level default properties for subsequent nodes.
Allow "$"-prefixed algorithm and action keys (e.g., "$TemplateMatch", "$Click") in default pipeline configuration, with compatibility for legacy non-prefixed keys.

Enhancements:

Scope bundle-level default_pipeline.json so its defaults only apply to nodes within the same bundle, avoiding cross-bundle contamination of defaults.
Remove reliance on a globally stored DefaultPipelineMgr in ResourceMgr and Context, instead using per-bundle or built-in defaults when parsing pipelines and overrides.
Relax various parsers (pipeline, recognition, action, wait_freezes) to use built-in default parameter values when explicit defaults are not provided, simplifying override handling.

Documentation:

Update English pipeline protocol documentation to describe "$Default" file-level defaults, "$"-prefixed default keys, revised inheritance priority, and clarified bundle scoping behavior of default_pipeline.json.

- 允许流水线资源文件定义一个 `$Default` 对象，作为该文件中所有条目的默认流水线配置。

Original summary in English

Summary by Sourcery

通过使用“$Default”和以“$”为前缀的算法/动作键，引入文件级和 bundle 级默认流水线配置，并将运行时覆盖与全局默认流水线状态解耦。

新功能：

支持在单个流水线 JSON 文件中使用“$Default”节点，为后续节点定义文件级默认属性。
在默认流水线配置中允许使用以“$”为前缀的算法和动作键（例如 “$TemplateMatch”、“$Click”），并兼容旧版的非前缀键。

增强：

将 bundle 级的 default_pipeline.json 进行作用域限制，使其默认值仅应用于同一 bundle 内的节点，避免默认配置在 bundle 之间相互污染。
移除在 ResourceMgr 和 Context 中对全局存储的 DefaultPipelineMgr 的依赖，在解析流水线和覆盖配置时改为使用按 bundle 或内建的默认值。
放宽多个解析器（流水线、识别、动作、wait_freezes），在未显式提供默认值时使用内建的默认参数值，从而简化覆盖逻辑处理。

文档：

更新英文流水线协议文档，说明文件级默认“$Default”、以“$”为前缀的默认键、修订后的继承优先级，以及 default_pipeline.json 在 bundle 作用域中的行为说明。

Original summary in English

Summary by Sourcery

Introduce file-scoped and bundle-scoped default pipeline configuration using "$Default" and "$"-prefixed algorithm/action keys, and decouple runtime overrides from global default pipeline state.

New Features:

Support a "$Default" node inside individual pipeline JSON files to define file-level default properties for subsequent nodes.
Allow "$"-prefixed algorithm and action keys (e.g., "$TemplateMatch", "$Click") in default pipeline configuration, with compatibility for legacy non-prefixed keys.

Enhancements:

Scope bundle-level default_pipeline.json so its defaults only apply to nodes within the same bundle, avoiding cross-bundle contamination of defaults.
Remove reliance on a globally stored DefaultPipelineMgr in ResourceMgr and Context, instead using per-bundle or built-in defaults when parsing pipelines and overrides.
Relax various parsers (pipeline, recognition, action, wait_freezes) to use built-in default parameter values when explicit defaults are not provided, simplifying override handling.

Documentation:

Update English pipeline protocol documentation to describe "$Default" file-level defaults, "$"-prefixed default keys, revised inheritance priority, and clarified bundle scoping behavior of default_pipeline.json.

sourcery-ai

Hey - 我发现了 1 个问题，并留下了一些高层次的反馈：

在 PipelineResMgr::parse_and_override_once 中，$Default 仍然会在主循环中被处理，并被注册为一个 pipeline 节点，而文档中说它不应该被注册；建议在应用文件级默认值之后跳过这个键（例如：if (key == kFileDefaultKey) continue;）。
新增的默认参数 const DefaultPipelineMgr& default_mgr = {} / const WaitFreezesParam& default_value = {} 是把引用隐式绑定到临时对象上；尽管生命周期延长机制使其是安全的，但可能让人困惑，并带来不必要的构造开销。为提高可读性，你可以考虑使用重载函数，或者改用指针/optional 参数。

给 AI Agent 的 Prompt

Please address the comments from this code review:

## Overall Comments
- 在 `PipelineResMgr::parse_and_override_once` 中，`$Default` 仍然会在主循环中被处理，并被注册为一个 pipeline 节点，而文档中说它不应该被注册；建议在应用文件级默认值之后跳过这个键（例如：`if (key == kFileDefaultKey) continue;`）。
- 新增的默认参数 `const DefaultPipelineMgr& default_mgr = {}` / `const WaitFreezesParam& default_value = {}` 是把引用隐式绑定到临时对象上；尽管生命周期延长机制使其是安全的，但可能让人困惑，并带来不必要的构造开销。为提高可读性，你可以考虑使用重载函数，或者改用指针/optional 参数。

## Individual Comments

### Comment 1
<location path="source/MaaFramework/Task/Context.cpp" line_range="166-168" />
<code_context>
         return false;
     }

-    // 从 DefaultPipelineMgr 获取默认值
-    const auto& default_param = resource->default_pipeline().get_pipeline().pre_wait_freezes;
-
     // 解析 wait_freezes_param
     MAA_RES_NS::WaitFreezesParam param;
-    if (!MAA_RES_NS::PipelineParser::parse_wait_freezes_value(wait_freezes_param, param, default_param)) {
+    if (!MAA_RES_NS::PipelineParser::parse_wait_freezes_value(wait_freezes_param, param)) {
         LogError << "failed to parse wait_freezes_param" << VAR(wait_freezes_param);
         return false;
</code_context>
<issue_to_address>
**issue (bug_risk):** 移除基于 DefaultPipelineMgr 的 wait_freezes 默认值会改变默认行为，并且可能忽略配置。

之前，`parse_wait_freezes_value` 会从 `resource->default_pipeline().get_pipeline().pre_wait_freezes` 获取 `default_param`，因此在 JSON 省略字段时，会应用来自 default pipeline 的配置默认值。现在它只依赖于内部默认构造的 `WaitFreezesParam`，所以 default pipeline 中对 `pre_wait_freezes` 的任何自定义都会被忽略。如果这不是有意为之，建议保留一个接受默认值的重载并在此处使用；如果这是有意变更，请确认没有其他地方依赖旧行为。
</issue_to_address>

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

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

Original comment in English

Hey - I've found 1 issue, and left some high level feedback:

In PipelineResMgr::parse_and_override_once, $Default is still processed in the main loop and will be registered as a pipeline node even though the docs say it should not be; consider skipping the key (e.g., if (key == kFileDefaultKey) continue;) after applying the file-level defaults.
The new default parameters const DefaultPipelineMgr& default_mgr = {} / const WaitFreezesParam& default_value = {} implicitly bind references to temporaries; while lifetime extension makes this safe, it can be confusing and may incur unnecessary construction, so you might want to use overloads or pointer/optional parameters instead for clarity.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In `PipelineResMgr::parse_and_override_once`, `$Default` is still processed in the main loop and will be registered as a pipeline node even though the docs say it should not be; consider skipping the key (e.g., `if (key == kFileDefaultKey) continue;`) after applying the file-level defaults.
- The new default parameters `const DefaultPipelineMgr& default_mgr = {}` / `const WaitFreezesParam& default_value = {}` implicitly bind references to temporaries; while lifetime extension makes this safe, it can be confusing and may incur unnecessary construction, so you might want to use overloads or pointer/optional parameters instead for clarity.

## Individual Comments

### Comment 1
<location path="source/MaaFramework/Task/Context.cpp" line_range="166-168" />
<code_context>
         return false;
     }

-    // 从 DefaultPipelineMgr 获取默认值
-    const auto& default_param = resource->default_pipeline().get_pipeline().pre_wait_freezes;
-
     // 解析 wait_freezes_param
     MAA_RES_NS::WaitFreezesParam param;
-    if (!MAA_RES_NS::PipelineParser::parse_wait_freezes_value(wait_freezes_param, param, default_param)) {
+    if (!MAA_RES_NS::PipelineParser::parse_wait_freezes_value(wait_freezes_param, param)) {
         LogError << "failed to parse wait_freezes_param" << VAR(wait_freezes_param);
         return false;
</code_context>
<issue_to_address>
**issue (bug_risk):** Dropping the DefaultPipelineMgr-derived default for wait_freezes changes default behavior and may ignore config.

Previously, `parse_wait_freezes_value` received `default_param` from `resource->default_pipeline().get_pipeline().pre_wait_freezes`, so config defaults from the default pipeline were applied when JSON omitted fields. Now it relies only on an internally default-constructed `WaitFreezesParam`, so any customized `pre_wait_freezes` in the default pipeline is ignored. If that’s not intentional, consider keeping an overload that accepts the default value and use it here; if it is intentional, verify nothing else relies on the old behavior.
</issue_to_address>

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

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

Copilot

Pull request overview

Adds support for a file-scoped $Default object in pipeline JSON resources to provide per-file default node attributes, and updates default pipeline handling to use $-prefixed keys with compatibility for legacy non-$ keys.

Changes:

Extend pipeline resource parsing to recognize $Default and apply it as the default for newly introduced nodes in the same file.
Update default pipeline (default_pipeline.json) parsing and samples/docs to prefer $Default / $<Type> keys while rejecting mixed $ and non-$ forms.
Scope default_pipeline.json usage to bundle load time (rather than a single long-lived default manager on ResourceMgr).

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tools/pipeline.schema.json	Allows `$Default` at the root of pipeline JSON files in the schema.
source/MaaFramework/Task/Context.h	Adjusts `override_pipeline_once` signature to remove default manager dependency.
source/MaaFramework/Task/Context.cpp	Updates override/wait_freezes parsing calls to rely on parser defaults rather than ResourceMgr defaults.
source/MaaFramework/Resource/ResourceMgr.h	Removes stored `DefaultPipelineMgr` from the resource manager interface.
source/MaaFramework/Resource/ResourceMgr.cpp	Loads per-bundle defaults locally during bundle load; adjusts default-param getters accordingly.
source/MaaFramework/Resource/PipelineResMgr.h	Makes default manager optional in load/override APIs (default argument).
source/MaaFramework/Resource/PipelineResMgr.cpp	Implements `$Default` file-level defaults during parse/override.
source/MaaFramework/Resource/PipelineParser.h	Makes `DefaultPipelineMgr` optional in parse APIs; adds default for wait_freezes default value.
source/MaaFramework/Resource/DefaultPipelineMgr.cpp	Adds `$`-prefixed key support with mutual-exclusion checks vs legacy keys.
sample/resource/default_pipeline.json	Switches sample keys to `$Default` / `$<Type>` forms.
docs/en_us/3.1-PipelineProtocol.md	Documents `$Default` behavior and updates default_pipeline key naming and priority notes.

MistEO · 2026-03-03T09:49:17Z

@MaaXYZ/application-developers 有一点 breaking changes， default_pipeline.json 从全局级改成 bundle 级了，都来瞅瞅（

key 改了下，加上 $ 前缀，不过也兼容老的 key

Windsland52 · 2026-03-03T15:02:26Z

文件级有点变态，在可以引用不同文件的节点的情况下，感觉这个不是很适合

MistEO · 2026-03-03T17:07:59Z

那咋整，文件夹级的话，fast 干不掉了啊

Windsland52 · 2026-03-03T19:26:08Z

那不知道了（

Windsland52 · 2026-03-03T19:27:21Z

可能风格不统一（fast不全面）本身就是错的

Windsland52 · 2026-03-03T19:30:13Z

MaaEnd/MaaEnd#938 或者说追求快就是错的，感觉还是稳定重要

neko-para · 2026-03-04T03:37:37Z

key 改了下，加上 $ 前缀，不过也兼容老的 key

有必要改这个吗(
感觉直接用同一套就挺好的

MistEO · 2026-03-04T06:08:05Z

key 改了下，加上 $ 前缀，不过也兼容老的 key

有必要改这个吗( 感觉直接用同一套就挺好的

文件里的肯定要加前缀，不然和普通任务区分不开了。然后就有人会问了，怎么 default_pipeline 里和文件级 default 不一样。“我复制过去的怎么不能用”

neko-para · 2026-03-04T06:36:45Z

但是“任务名”已经有$了，没必要改字段吧，有啥意义呢（

MistEO · 2026-03-04T09:11:58Z

不是，字段没改啊，我说的是改了 default_pipeline 里的。你看文档 @neko-para

neko-para · 2026-03-04T10:13:12Z

诶原来不是这样的吗? 我一直以为就是这样的, 必须要有$

MistEO added 4 commits March 3, 2026 16:22

feat: default_node

13f9113

refactor: 重构 default_pipeline

ce9d7a8

refactor: 删除一点冗余

5927c51

refactor: 删除一点冗余 2

a3e1503

MistEO marked this pull request as ready for review March 3, 2026 09:29

Copilot AI review requested due to automatic review settings March 3, 2026 09:29

Copilot started reviewing on behalf of MistEO March 3, 2026 09:30 View session

sourcery-ai Bot reviewed Mar 3, 2026

View reviewed changes

Comment thread source/MaaFramework/Task/Context.cpp

docs: 更正文档

db8467d

Copilot AI reviewed Mar 3, 2026

View reviewed changes

docs: AI review

b97dd3c

MistEO requested review from kqcoxn, moomiji and neko-para March 3, 2026 09:48

This comment was marked as off-topic.

Sign in to view

MistEO closed this Apr 2, 2026

Conversation

MistEO commented Mar 3, 2026 • edited by sourcery-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by Sourcery

Summary by Sourcery

Summary by Sourcery

Summary by Sourcery

Uh oh!

sourcery-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MistEO commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Windsland52 commented Mar 3, 2026

Uh oh!

MistEO commented Mar 3, 2026

Uh oh!

This comment was marked as off-topic.

Windsland52 commented Mar 3, 2026

Uh oh!

Windsland52 commented Mar 3, 2026

Uh oh!

Windsland52 commented Mar 3, 2026

Uh oh!

neko-para commented Mar 4, 2026

Uh oh!

MistEO commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

neko-para commented Mar 4, 2026

Uh oh!

MistEO commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

neko-para commented Mar 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

MistEO commented Mar 3, 2026 •

edited by sourcery-ai Bot

Loading

MistEO commented Mar 3, 2026 •

edited

Loading

MistEO commented Mar 4, 2026 •

edited

Loading

MistEO commented Mar 4, 2026 •

edited

Loading