| name | task-config |
| description | MaaNTE 任务配置（tasks/*.json）编写指南。覆盖任务入口、选项类型（switch/input/select）、pipeline_override、i18n、控制器限制等。在添加新任务、修改任务选项、配置 pipeline_override 时使用。 |
MaaNTE 任务配置编写指南
文件位置
assets/resource/tasks/<TaskName>.json
新建 task 文件后，必须将其注册到 assets/interface.json 的 import 数组中，否则 MaaFramework 不会加载：
{
"task": [],
"import": [
"resource/tasks/WithdrawMoney.json",
"resource/tasks/MyNewTask.json"
]
}
基本结构
{
"task": [
{
"name": "MyTask",
"label": "$task_my_task_label",
"entry": "MyTaskEntrance",
"description": "$task_my_task_desc",
"option": [
"MyOption1",
"MyOption2"
],
"controller": [
"Win32",
"Win32-Front"
]
}
],
"option": {
}
}
一个文件可定义多个 task（如 Fish.json 含 Fish 和 FishNew），共享同一组 option 定义。
字段说明
| 字段 | 类型 | 必填 | 说明 |
|---|
name | string | ✅ | 任务名（PascalCase） |
label | string | ✅ | UI 标签，$i18n_key 格式 |
entry | string | ✅ | Pipeline 入口节点名，对应 pipeline JSON 中的节点 key |
description | string | ❌ | UI 描述，$i18n_key 格式（不加 $ 则为纯文本） |
option | string[] | ❌ | 启用的选项名列表，对应 option 块中的 key |
controller | string[] | ❌ | 限制可用控制器："Win32" / "Win32-Front" / "Win32-Background"。不写 = 通用 |
选项类型
switch（布尔开关）
最常用。用户选择 Yes/No，通过 pipeline_override 控制节点 enabled：
"MySwitchOption": {
"type": "switch",
"label": "$task_xxx_option_yyy",
"description": "$task_xxx_option_yyy_desc",
"default_case": "No",
"cases": [
{
"name": "Yes",
"label": "$option_switch_case_yes",
"pipeline_override": {
"SomeNode": { "enabled": true }
},
"option": [
"SubOption"
]
},
{
"name": "No",
"label": "$option_switch_case_no",
"pipeline_override": {
"SomeNode": { "enabled": false }
}
}
]
}
input（数值/文本输入）
用户输入值，通过 {变量名} 注入到 pipeline_override：
"MyInputOption": {
"type": "input",
"label": "$task_xxx_option_yyy",
"description": "$task_xxx_option_yyy_desc",
"inputs": [
{
"name": "count",
"default": "10",
"pipeline_type": "int",
"verify": "^\\d+$"
}
],
"pipeline_override": {
"SomeNode": {
"custom_action_param": {
"count": "{count}"
}
}
}
}
select（下拉选择）
预设多个选项值：
"MySelectOption": {
"type": "select",
"label": "$task_xxx_option_yyy",
"description": "$task_xxx_option_yyy_desc",
"cases": [
{
"name": "0.8",
"pipeline_override": {
"SomeNode": { "recognition": { "param": { "threshold": 0.8 } } }
}
},
{
"name": "0.6",
"pipeline_override": {
"SomeNode": { "recognition": { "param": { "threshold": 0.6 } } }
}
}
]
}
pipeline_override 格式
pipeline_override 是 { "节点名": { "字段": 值 } } 的映射，支持的字段包括所有 Pipeline 节点字段：
"pipeline_override": {
"NodeName": {
"enabled": true,
"max_hit": 3,
"next": ["OtherNode"],
"pre_delay": 200,
"post_delay": 200,
"timeout": 30000,
"recognition": {
"param": {
"roi": [0, 0, 100, 50],
"threshold": 0.7,
"expected": ["新文本"]
}
},
"action": {
"param": {
"target": [100, 200]
}
},
"custom_action_param": {
"key": "value"
}
}
}
选项级联（子选项）
switch 的 case 中可嵌套 "option" 数组，实现"启用某功能后才显示子选项"：
"AutoSkipStory": {
"type": "switch",
"cases": [
{
"name": "Yes",
"option": ["AutoSkipStoryDialog"]
},
{
"name": "No"
}
]
}
i18n
- task/option 的
label、description 使用 $key 格式引用翻译，key 定义在 assets/resource/locales/interface/ 下五种语言文件中：
zh_cn.json — 简体中文zh_tw.json — 繁体中文en_us.json — 英语ja_jp.json — 日语ko_kr.json — 韩语
- Pipeline 中 OCR 节点的
expected 只需填写完整的中文文本，多语言同步由 .github/workflows/i18n-sync.yml 工作流自动完成。需要跳过时添加 // @i18n-skip 标记
option_switch_case_yes / option_switch_case_no 是全局 switch case 默认标签，所有语言文件都需定义。一般 switch 直接复用即可；若有特殊需求（如文案不应是简单的"启用/禁用"），可将 case 的 label 替换为自定义 $key- 纯文本（不加
$）直接显示，不走翻译
控制器限制
controller 数组限制任务可在哪些控制器下运行：
"Win32" — 后台 SendMessage 模式（需管理员权限）"Win32-Front" — 前台 Seize 模式（会抢占鼠标）"Win32-Background" — 后台 SendMessageWithWindowPos 模式
不写 controller 字段 = 所有控制器通用。多个值 = 任一匹配即可。
完整示例
{
"task": [
{
"name": "MyNewTask",
"label": "$task_my_new_task_label",
"entry": "MyNewTaskEntrance",
"description": "$task_my_new_task_desc",
"option": [
"MyNewTaskAutoMode",
"MyNewTaskLoopCount"
],
"controller": [
"Win32",
"Win32-Front"
]
}
],
"option": {
"MyNewTaskAutoMode": {
"type": "switch",
"label": "$task_my_new_task_option_auto_mode",
"description": "$task_my_new_task_option_auto_mode_desc",
"default_case": "Yes",
"cases": [
{
"name": "Yes",
"label": "$option_switch_case_yes",
"pipeline_override": {
"MyNewTaskAutoStep": { "enabled": true }
}
},
{
"name": "No",
"label": "$option_switch_case_no",
"pipeline_override": {
"MyNewTaskAutoStep": { "enabled": false }
}
}
]
},
"MyNewTaskLoopCount": {
"type": "input",
"label": "$task_my_new_task_option_loop_count",
"description": "$task_my_new_task_option_loop_count_desc",
"inputs": [
{
"name": "count",
"default": "5",
"pipeline_type": "int",
"verify": "^\\d+$"
}
],
"pipeline_override": {
"MyNewTaskEntry": {
"max_hit": "{count}"
}
}
}
}
}
审查清单
