企业官网建设流程全解析

MaaAssistantArknights 命令行工具 maa-cli 完整使用指南：任务运行、MaaCore 管理与日志排查

【免费下载链接】MaaAssistantArknights《明日方舟》小助手，全日常一键长草！| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights

maa-cli 是《明日方舟》小助手 MaaAssistantArknights 的官方 Rust 命令行客户端，通过调用 MaaCore 自动化完成游戏内的日常任务，同时提供 MaaCore 的安装、更新与资源热更新等管理能力。本文以 使用文档 为主线，完整覆盖预定义任务、自定义任务、任务总结、日志控制等核心操作，并深入结合配置文档与仓库源码，帮助你从零开始用命令行一键挂机、自动化排班。

一、maa-cli 的定位与安装前提

maa-cli 本身只是一个命令行界面（CLI），它不包含游戏识别与自动化逻辑——真正干活的是MaaCore。因此使用前需要先完成两件事：

1. 安装 maa-cli（参考 安装及编译：支持预编译二进制、Homebrew、AUR、Nix、cargo install等方式）；
2. 安装 MaaCore 及资源（通过maa install或包管理器安装）。

::: tip 使用 Windows 包管理器（winget）安装 maa-cli 的用户，以下命令中的maa需要替换为maa-cli。 :::

maa-cli 的主要功能可以分为两类：

• 运行任务：调用 MaaCore 自动化完成明日方舟的游戏任务；
• 管理 MaaCore：安装、更新 MaaCore 及资源，方便维护运行环境。

二、管理 MaaCore：安装、更新与资源热更新

maa-cli 可以安装和更新 MaaCore 及资源，只需运行以下命令：

maa install # 安装 MaaCore 及资源 maa update # 更新 MaaCore 及资源

一些与安装/更新相关的补充事实：

• maa install下载的是 MAA 官方预编译的 MaaCore；而通过包管理器安装的 MaaCore 可能使用与官方预编译版本不同的编译选项和依赖版本，性能和功能上可能有细微差异（见 安装文档 的警告说明）。
• Windows 用户运行maa install前，需要以管理员身份安装 VC++ 运行库：winget install "Microsoft.VCRedist.2015+.x64" --override "/repair /passive /norestart" --uninstall-previous --accept-package-agreements --force。
• Nix 用户无需（也不应该）手动安装 MaaCore，因为 Nix 上的 maa-cli 强制依赖 MaaCore。
• maa install与maa update是否可用，取决于编译时是否启用了core_installer特性（该特性默认启用）。

除了随 MaaCore 一起安装的基础资源，MAA 还提供热更新资源（如活动关卡信息）。热更新相关配置位于$MAA_CONFIG_DIR/cli.toml的[resource]段，详见 CLI 配置：

[resource] auto_update = true # 是否在每次运行任务时自动更新资源，默认为 false warn_on_update_failure = true # 更新失败时发出警告而不是直接报错 backend = "libgit2" # 资源热更新后端，可选 "git" 或 "libgit2"，默认为 "git"

需要特别注意的是：即使启动了资源热更新，你依然需要先安装 MaaCore 的基础资源，因为热更新只包含部分可更新的资源文件，不包含全部资源。若backend = "git"，则系统必须可用git命令行工具；若使用 SSH 协议拉取远程仓库，还需在[resource.remote]中配置ssh_key、passphrase或use_ssh_agent等字段。

三、更新 maa-cli 自身

maa self update

::: warning 使用包管理器（如 Homebrew、AUR、Nix）安装 maa-cli 的用户，请使用包管理器更新 maa-cli，maa self update在这些用户中无效。 :::

该命令是否可用取决于编译时是否启用了cli_installer特性（默认启用）。通过安装脚本安装的用户，后续即可用maa self update持续更新。

四、初始化配置

MaaCore 安装完成后，通常情况下无需额外配置就可以直接运行任务。但如果默认配置不适用于你的环境（例如模拟器连接地址不同、需要指定海外客户端资源），可以运行：

maa init

该命令会交互式引导你配置 MaaCore 的相关配置，配置项写入$MAA_CONFIG_DIR/profiles目录下的 profile 文件（默认读取default），涵盖连接、资源、静态选项、实例选项、行为等五大类，完整字段说明参见 MaaCore 相关配置。下面是一个典型配置示例：

[connection] preset = "MuMuPro" adb_path = "adb" address = "emulator-5554" config = "CompatMac" [resource] global_resource = "YoStarEN" platform_diff_resource = "iOS" user_resource = true [static_options] cpu_ocr = false gpu_ocr = 1 [instance_options] touch_mode = "MaaTouch" deployment_with_pause = false adb_lite_enabled = false kill_adb_on_exit = false [behavior] auto_reconnect = true

五、运行任务

完成 MaaCore 的安装和配置后，就可以运行任务了。maa-cli 支持两种类型的任务：预定义任务和自定义任务。

5.1 预定义任务

对于常见任务，maa-cli 提供了开箱即用的预定义任务：

上述任务都接受一些附加参数，可通过maa <task> --help查看具体参数（例如maa fight --help查看理智药数量-m、关卡次数等选项）。

例如，官服玩家想要打开游戏、使用 3 个理智药刷 BB-7、然后关闭游戏，可以一条命令串联执行：

maa startup Official && maa fight BB-7 -m 3 && maa closedown

5.2 自定义任务

由于 MAA 支持的任务繁多，maa-cli 无法为所有任务提供预定义选项；同时你可能需要像上面的例子一样组合多个任务。为此，maa-cli 提供了自定义任务功能：

• 能够组合不同的任务，精细控制每个任务的参数与执行顺序；
• 支持条件判断，可以根据时间、星期、活动等条件决定是否执行某个任务，或以何种参数执行；
• 适合用于自动化你的每日例行操作。

自定义任务通过配置文件定义，每个任务是一个单独的文件，放在$MAA_CONFIG_DIR/tasks目录中（配置目录可通过maa dir config获取，也可用环境变量MAA_CONFIG_DIR更改）。编写好配置文件后，通过maa run <task>运行，<task>是自定义任务文件名（不包括扩展名）。

一个最简单的自定义任务文件（支持 TOML / YAML / JSON 三种格式，文件扩展名须与格式一致）：

[[tasks]] name = "启动游戏" # 任务的名字，可选，默认为任务类型 type = "StartUp" # 任务的类型 params = { client_type = "Official", start_game_enabled = true } # 对应任务的参数

具体的任务类型与参数可在 MAA 集成文档 - 任务类型一览 中查找。注意：目前 maa-cli 并不会验证参数名和参数值是否正确，出错时也不会产生错误信息，除非 MaaCore 在运行时检测到错误——因此编写自定义任务时务必仔细核对参数名。

除了tasks，任务文件还支持以下顶层字段：

• client_type：指定客户端类型，自动填充到StartUp、Fight、CloseDown任务的client_type参数中；
• startup：是否自动启动游戏。设为true时，若任务列表中没有StartUp任务，将在开头自动添加一个；若已有StartUp任务但未开启start_game_enabled，也会自动开启；
• closedown：是否自动关闭游戏。设为true时，若任务列表中没有CloseDown任务，将在末尾自动添加一个；若已有CloseDown任务但enable为false，也会自动开启。

5.2.1 任务条件（variants）

如果你希望根据条件运行不同参数的任务，可以为一个任务定义多个变体（variants），每个变体包含一个condition字段和一个params字段，匹配到的变体的params会被合并进任务参数：

[[tasks]] name = "基建换班" type = "Infrast" [tasks.params] mode = 10000 facility = ["Trade", "Reception", "Mfg", "Control", "Power", "Office", "Dorm"] dorm_trust_enabled = true filename = "normal.json" # 自定义基建计划文件，位于 $MAA_CONFIG_DIR/infrast # 在 18:00:00 到第二天的 04:00:00 使用计划 0，在 12:00:00 之前使用计划 1，之后使用计划 2 [[tasks.variants]] condition = { type = "Time", start = "18:00:00", end = "04:00:00" } # 结束时间小于开始时间时，结束时间视为第二天的时间 params = { plan_index = 0 } [[tasks.variants]] condition = { type = "Time", end = "12:00:00" } # 省略开始时间：只要当前时间小于结束时间即匹配 params = { plan_index = 1 } [[tasks.variants]] condition = { type = "Time", start = "12:00:00" } # 省略结束时间：只要当前时间大于开始时间即匹配 params = { plan_index = 2 }

maa-cli 支持的条件类型有：Time、DateTime、Weekday、DayMod、OnSideStory，并且可以通过And/Or/Not组合逻辑：

• Time：指定一天内的时段，结束时间小于开始时间时视为跨天；
• DateTime：指定一个绝对时间段，如{ type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" }；
• Weekday：指定一周中的某些天，如{ type = "Weekday", weekdays = ["Tue", "Thu", "Sat"], timezone = "Official" }；
• DayMod：指定自定义周期的某些天，通过divisor（周期）与remainder（偏移量）控制，偏移量等于num_days_since_ce % divisor（0001-01-01 为第一天），当天偏移量可用maa remainder <divisor>获取；
• OnSideStory：依赖热更新资源判断当前是否有正在开启的活动，如{ type = "OnSideStory", client = "Official" }，活动更新后只需更新要刷的关卡，无需手动编辑活动开放时间。

所有时间相关条件都支持timezone参数：可以填数字表示与 UTC 的偏移量（如东八区timezone = 8），也可以填客户端类型（如"Official"，使用官服服务器时间——注意官服时区是东四区而非东八区，因为游戏每日从 04:00:00 开始）；不指定则使用本地时区。

例如，一个"活动期间刷特定关卡"的完整自定义任务：

[[tasks]] type = "Fight" # 在夏活期间，刷 SL-8 [[tasks.variants]] params = { stage = "SL-8" } condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" } # 在夏活期间以外的周二、周四和周六，刷 CE-6 [[tasks.variants]] condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"], timezone = "Official" } params = { stage = "CE-6" } # 其他时间，刷 1-7 [[tasks.variants]] params = { stage = "1-7" }

对于基建多天排班，可将DayMod与Time组合，实现"每两天换六次班"之类的排班方案。跨天时段（如 20:00 到次日 04:00）必须用Or拆成两个And组合，因为直接用Time { start = "20:00:00", end = "04:00:00" }无法覆盖第二天的 00:00-04:00。完整示例见 自定义任务配置。

匹配策略：默认策略first下，多个变体被匹配时使用第一个；没有条件的变体总是被匹配，因此可放在最后作为默认分支。若改用strategy = "merge"，则后面的变体参数会合并进前面的变体参数，同名参数以后者覆盖前者；如果没有变体被匹配，任务将不会执行——这恰好可用于"只在特定条件下运行子任务"，例如：

# 只在 18:00:00 之后进行信用商店相关的操作 [[tasks]] type = "Mall" [[tasks.variants]] condition = { type = "Time", start = "18:00:00" }

5.2.2 用户输入

部分任务支持在运行时由用户输入参数（如关卡名）。把参数设置为Input或Select类型即可：

[[tasks]] type = "Fight" # 运行时会提示选择一个关卡（Select） [[tasks.variants]] condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" } [tasks.variants.params.stage] alternatives = [ "SL-7", # 将显示为 "1. SL-7" { value = "SL-8", desc = "轻锰矿" } # 将显示为 "2. SL-8 (轻锰矿)" ] default_index = 1 # 默认值索引（从 1 开始），不设置则使用第一个可选值 description = "a stage to fight in summer event" allow_custom = true # 允许输入自定义值，默认为 false # 无需输入 [[tasks.variants]] condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"] } params = { stage = "CE-6" } # 输入一个关卡（Input） [[tasks.variants]] [tasks.variants.params.stage] default = "1-7" # 默认值，可选；无默认值时输入空值会重新提示 description = "a stage to fight" # 当输入的关卡是 1-7 时，还需要输入使用理智药的数量（条件参数） [tasks.variants.params.medicine] conditions = { stage = "1-7" } # 只有当 stage 为 1-7 时才提示输入 default = 1000 description = "medicine to use"

行为说明：

• Input类型：运行任务时提示输入一个值，输入空值时使用默认值；没有默认值则重新提示；
• Select类型：提示输入索引或自定义值（如果allow_custom为 true），输入空值使用默认值；
• --batch选项可跳过所有输入，直接使用默认值；如果有任何输入没有默认值，--batch模式会报错。

5.3 任务总结

无论是预定义任务还是自定义任务，maa-cli 都会在任务运行结束后输出任务总结，包含每个子任务的运行时间（开始时间、结束时间、运行时长）。对于部分任务，还会输出结果汇总：

• fight任务：关卡名称、次数、消耗理智药个数以及掉落统计；
• infrast：各设施进驻的干员，制造站和贸易站还会输出产物类型；
• recruit：每次公招的 tag、星级以及状态，以及总共的招募次数；
• roguelike：探索次数、投资次数。

如果不需要任务总结，可以通过--no-summary参数关闭。

5.4 任务日志

maa-cli 会输出日志，日志级别从低到高依次为：Error、Warn、Info、Debug、Trace。默认日志级别为Warn，可以通过以下三种方式调节：

1. 环境变量MAA_LOG，例如MAA_LOG=debug；
2. -v增加日志级别（可重复使用），-q减少日志级别。

默认情况下，日志输出到标准错误（stderr）。--log-file选项可将日志写入文件，日志保存在$(maa dir log)/YYYY/MM/DD/HH:MM:SS.log（$(maa dir log)为日志目录，可通过maa dir log获取），也可以用--log-file=path/to/log指定自定义路径。

日志前缀（时间戳 + 日志级别）行为由环境变量MAA_LOG_PREFIX控制：

• Always：总是包含前缀；
• Auto（默认）：输出到日志文件时包含前缀，输出到 stderr 时不包含；
• Never：即使写入日志文件也不包含前缀。

5.5 其他子命令

除了上述命令外，maa-cli 还提供了以下实用子命令：

更多命令的使用方法可通过maa help查看，具体命令的使用方法可通过maa help <command>查看。

六、实用建议与常见问题

• 目录速查：maa dir config获取配置目录；maa dir log获取日志目录；maa dir hot-update获取热更新资源仓库位置（更改远程仓库地址需通过git手动操作或删除对应目录）。
• 模拟器连接：[connection].address常见写法为127.0.0.1:<端口号>或emulator-<四位数字>；常用模拟器端口参见 连接设置，如 MuMu 模拟器127.0.0.1:16384/16416/16448/16480/16512/16544/16576、雷电模拟器 9emulator-5554等。adb_path可直接填adb（要求 adb 在 PATH 中），或填写模拟器自带 adb 的完整路径。
• macOS 配置目录：默认使用 Apple 风格目录；若想使用 XDG 风格（如$HOME/.config/maa），可设置XDG_CONFIG_HOME="$HOME/.config"，或通过mkdir -p "$HOME/.config/maa" && ln -s "$HOME/.config/maa" "$(maa dir config)"建立符号链接（详见 常见问题）。
• 配置校验与自动补全：maa-cli 在crates/maa-cli/schemas/目录提供 JSON Schema（task.schema.json、asst.schema.json、cli.schema.json），可用于编辑器自动补全与配置文件校验。

七、相关文档

• maa-cli 安装及编译
• maa-cli 配置详解（自定义任务、MaaCore 配置、CLI 配置）
• maa-cli 常见问题
• MAA 连接设置（模拟器端口参考）

【免费下载链接】MaaAssistantArknights《明日方舟》小助手，全日常一键长草！| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights