docs: PI 2.3.1 - 强调一下不兼容选项行为 (#1181)

Author: MistEO

docs/en_us/3.3-ProjectInterfaceV2.md

@@ -23,6 +23,7 @@ We have designated the version number for the independent release (January 30, 2
 | 2026-01-30 | v2.1.0  | Standalone release |
 | 2026-01-30 | v2.2.0  | Added `attach_resource_path` and `import` fields |
 | 2026-02-23 | v2.3.0  | Added `checkbox` multi-select type, `option.controller`, `option.resource`, global/resource/controller-level options, `focus.display` display channel tag, `preset` field, `import` supports importing `preset` |
+| 2026-03-05 | v2.3.1  | Clarified option applicability filtering |
 
 ## `interface.json`
 
@@ -130,7 +131,8 @@ We have designated the version number for the independent release (January 30, 2
     _Optional._ An array of additional resource paths. These paths will be loaded after `resource.path` has finished loading.
 
   - **option** `string[]` **💡 v2.3.0**  
-    _Optional._ Controller-level option configuration, an array of strings. Array elements should correspond to the key names in the outer `option` configuration. The parameters generated by this option will participate in the pipeline override of all tasks that use this controller, serving as controller-level parameter passing.
+    _Optional._ Controller-level option configuration, an array of strings. Array elements should correspond to the key names in the outer `option` configuration. The parameters generated by this option will participate in the pipeline override of all tasks that use this controller, serving as controller-level parameter passing.  
+    If a referenced option does not satisfy the current controller/resource constraints, that option's `pipeline_override` (including nested `option.option`) must not be merged. **💡 v2.3.1**
 
   - **adb** `object`  
     Specific configuration for the `Adb` controller.
@@ -205,7 +207,8 @@ We have designated the version number for the independent release (January 30, 2
     When a user selects a controller, only resource packages that support that controller will be displayed in the user interface for selection. This allows providing specially optimized resource packages for different controller types.
 
   - **option** `string[]`  
-    _Optional._ Resource-level option configuration, an array of strings. Array elements should correspond to the key names in the outer `option` configuration. The parameters generated by this option will participate in the pipeline override of all tasks, serving as resource-level parameter passing.
+    _Optional._ Resource-level option configuration, an array of strings. Array elements should correspond to the key names in the outer `option` configuration. The parameters generated by this option will participate in the pipeline override of all tasks, serving as resource-level parameter passing.  
+    If a referenced option does not satisfy the current controller/resource constraints, that option's `pipeline_override` (including nested `option.option`) must not be merged. **💡 v2.3.1**
 
     ```jsonc
     "resource": [
@@ -366,11 +369,13 @@ We have designated the version number for the independent release (January 30, 2
 
   - **controller** `string[]` **💡 v2.3.0**  
     _Optional._ Specifies the list of controller types this option applies to. Array elements should correspond to the `name` field in the `controller` configuration. If not specified, this option is available for all controller types.  
-    When a user selects a controller, the Client may hide options that do not apply to that controller, or display them in a disabled (grayed-out) state to inform the user.
+    When a user selects a controller, the Client may hide options that do not apply to that controller, or display them in a disabled (grayed-out) state to inform the user.  
+    If the current controller is not in this list, the option is treated as inactive: all `pipeline_override` generated by this option and its sub-options (`option.option`) must be excluded from merging. **💡 v2.3.1**
 
   - **resource** `string[]` **💡 v2.3.0**  
     _Optional._ Specifies the list of resource packages this option applies to. Array elements should correspond to the `name` field in the `resource` configuration. If not specified, this option is available for all resource packages.  
-    When a user selects a resource package, the Client may hide options that do not apply to that resource package, or display them in a disabled (grayed-out) state to inform the user.
+    When a user selects a resource package, the Client may hide options that do not apply to that resource package, or display them in a disabled (grayed-out) state to inform the user.  
+    If the current resource package is not in this list, the option is treated as inactive: all `pipeline_override` generated by this option and its sub-options (`option.option`) must be excluded from merging. **💡 v2.3.1**
 
   - **label** `string`  
     Option display label, shown in the user interface. Supports internationalized strings (starting with `$`). _Optional._
@@ -448,7 +453,8 @@ We have designated the version number for the independent release (January 30, 2
 - **global_option** `string[]` **💡 v2.3.0**  
   _Optional._ Global option configuration, an array of strings. Array elements should correspond to key names in the `option` configuration.  
   The parameters generated by this option will participate in the pipeline override of all tasks, regardless of which resource package or controller the user has selected.  
-  Unlike `resource.option` and `controller.option`, global options do not depend on any resource package or controller selection.
+  Unlike `resource.option` and `controller.option`, global options do not depend on any resource package or controller selection.  
+  However, options referenced by `global_option` must still satisfy their own `resource` / `controller` constraints; otherwise, no `pipeline_override` is applied. **💡 v2.3.1**
 
   ```jsonc
   "global_option": [
@@ -583,6 +589,8 @@ The `pipeline_override` generated by each level of option is merged in the follo
 
 In other words: `task.option` > `controller.option` > `resource.option` > `global_option`.
 
+Before applying the merge order above, inactive options must be filtered out. Any option that does not satisfy the current `controller` / `resource` constraints (including options referenced by `global_option`, `resource.option`, `controller.option`, `task.option`, and nested `option.option`) must not generate `pipeline_override`. **💡 v2.3.1**
+
 The reasoning behind this design is that more specific configuration (task-level) should have higher priority, while more general configuration (global-level) serves as the fallback default.
 
 **Example:**

docs/zh_cn/3.3-ProjectInterfaceV2协议.md

@@ -23,6 +23,7 @@
 | 2026-1-30 | v2.1.0 | 独立版本发布 |
 | 2026-1-30 | v2.2.0 | 新增 `attach_resource_path` 和 `import` 字段 |
 | 2026-2-23 | v2.3.0 | 新增 `checkbox` 多选类型、`option.controller`、`option.resource`、全局/resource/controller 级 option、`focus.display` 展示渠道标签、`preset` 预设配置字段、`import` 支持导入 `preset` |
+| 2026-3-5 | v2.3.1 | 明确 option 适用性过滤规则 |
 
 ## `interface.json`
 
@@ -130,7 +131,8 @@
 
   - option `string[]` **💡 v2.3.0**  
     可选。控制器级的选项配置，为一个字符串数组，数组元素应与外层 option 配置中的键名对应。  
-    该选项生成的参数会参与到所有使用该控制器的任务的 pipeline override 中，起到控制器级参数传递的作用。
+    该选项生成的参数会参与到所有使用该控制器的任务的 pipeline override 中，起到控制器级参数传递的作用。  
+    若被引用的 option 不支持当前 controller/resource 条件，则该 option 的 `pipeline_override`（含其嵌套 `option.option`）不参与合并。 **💡 v2.3.1**
 
   - adb `object`  
     `Adb` 控制器的具体配置。  
@@ -206,7 +208,8 @@
 
   - option `string[]`  
     可选。资源包级的选项配置，为一个字符串数组，数组元素应与外层 option 配置中的键名对应。  
-    该选项生成的参数会参与到所有任务的 pipeline override 中，起到资源包级参数传递的作用。
+    该选项生成的参数会参与到所有任务的 pipeline override 中，起到资源包级参数传递的作用。  
+    若被引用的 option 不支持当前 controller/resource 条件，则该 option 的 `pipeline_override`（含其嵌套 `option.option`）不参与合并。 **💡 v2.3.1**
 
     ```jsonc
     "resource": [
@@ -364,11 +367,13 @@
 
   - controller `string[]` **💡 v2.3.0**  
     可选。指定该配置项适用的控制器类型列表。数组元素应与 `controller` 配置中的 `name` 字段对应。若不指定，则表示该配置项在所有控制器类型中都可用。  
-    当用户选择了某个控制器时，Client 可将不适用于该控制器的配置项隐藏，或以不可用（灰色/禁用）状态展示以提示用户。
+    当用户选择了某个控制器时，Client 可将不适用于该控制器的配置项隐藏，或以不可用（灰色/禁用）状态展示以提示用户。  
+    当当前控制器不在该列表中时，该配置项视为未激活：其自身及其子配置项（`option.option`）产生的所有 `pipeline_override` 均不参与合并。 **💡 v2.3.1**
 
   - resource `string[]` **💡 v2.3.0**  
     可选。指定该配置项适用的资源包列表。数组元素应与 `resource` 配置中的 `name` 字段对应。若不指定，则表示该配置项在所有资源包中都可用。  
-    当用户选择了某个资源包时，Client 可将不适用于该资源包的配置项隐藏，或以不可用（灰色/禁用）状态展示以提示用户。
+    当用户选择了某个资源包时，Client 可将不适用于该资源包的配置项隐藏，或以不可用（灰色/禁用）状态展示以提示用户。  
+    当当前资源包不在该列表中时，该配置项视为未激活：其自身及其子配置项（`option.option`）产生的所有 `pipeline_override` 均不参与合并。 **💡 v2.3.1**
 
   - label `string`  
     配置项显示标签，用于在用户界面中展示。支持国际化字符串（以`$`开头）。可选。
@@ -446,7 +451,8 @@
 - global_option `string[]` **💡 v2.3.0**  
   可选。全局选项配置，为一个字符串数组，数组元素应与 `option` 配置中的键名对应。  
   该选项生成的参数会参与到所有任务的 pipeline override 中，无论用户选择了什么资源包或控制器。  
-  与 `resource.option` 和 `controller.option` 不同，全局选项不依赖于任何资源包或控制器的选择。
+  与 `resource.option` 和 `controller.option` 不同，全局选项不依赖于任何资源包或控制器的选择。  
+  但 `global_option` 引用的 option 仍需满足该 option 自身的 `resource` / `controller` 限制；不满足时不应用任何 `pipeline_override`。 **💡 v2.3.1**
 
   ```jsonc
   "global_option": [
@@ -581,6 +587,8 @@
 
 即：`task.option` > `controller.option` > `resource.option` > `global_option`。
 
+在进入上述合并顺序前，需先过滤“未激活”的 option。任何不满足当前 `controller` / `resource` 条件的 option（包括来自 `global_option`、`resource.option`、`controller.option`、`task.option` 以及嵌套 `option.option`）都不得产生 `pipeline_override`。 **💡 v2.3.1**
+
 这样设计的理由是：越具体的配置（任务级）应当具有越高的优先级，越通用的配置（全局级）则作为兜底默认值。
 
 **示例：**