From f8e6b0e982a2d4da8fe17f8971fa6146f385fbfb Mon Sep 17 00:00:00 2001 From: Loong Date: Mon, 15 Jan 2024 18:31:16 +0800 Subject: [PATCH] chore: bump `maa-cli` to `v0.4.0` (#7996) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * chore: bump `maa-cli` to `v0.4.0` * docs: 更新 CLI 使用指南 * ci: build cli for appimage only with git2 feature * ci: build CLI with vendored openssl on aarch64 --- .github/workflows/ci.yml | 18 +-- docs/用户手册/CLI使用指南.md | 226 ++++++++++++++++++++++++++++------- src/maa-cli | 2 +- 3 files changed, 192 insertions(+), 54 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 10da8a4543..c308523822 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -224,19 +224,20 @@ jobs: CC: ${{ matrix.arch == 'x86_64' && 'ccache gcc-12' || 'ccache aarch64-linux-gnu-gcc-12' }} CXX: ${{ matrix.arch == 'x86_64' && 'ccache g++-12' || 'ccache aarch64-linux-gnu-g++-12' }} - - name: Install cross compile tool (CLI) - if: ${{ matrix.arch != 'x86_64' }} - uses: taiki-e/install-action@v2 + - name: Setup Rust + uses: ./src/maa-cli/.github/actions/setup with: - tool: cross + os: ubuntu-latest + arch: ${{ matrix.arch }} - name: Build CLI run: | - $CARGO_CMD build --release --locked --package maa-cli + cargo build --release --locked --package maa-cli \ + ${{ matrix.arch != 'x86_64' && '--features vendored-openssl' || '' }} cp -v target/$CARGO_BUILD_TARGET/release/maa $GITHUB_WORKSPACE/install/maa - env: - CARGO_CMD: ${{ matrix.arch == 'x86_64' && 'cargo' || 'cross' }} - CARGO_BUILD_TARGET: ${{ matrix.arch }}-unknown-linux-gnu + cargo build --release --locked --package maa-cli --no-default-features \ + --features ${{ matrix.arch != 'x86_64' && 'git2,vendored-openssl' || 'git2' }} + cp -v target/$CARGO_BUILD_TARGET/release/maa $GITHUB_WORKSPACE/appimage-maa working-directory: src/maa-cli - name: Build Appimage @@ -250,6 +251,7 @@ jobs: wget -c https://raw.githubusercontent.com/MaaAssistantArknights/design/main/logo/maa-logo_512x512.png -O Maa.AppDir/maa.png mkdir -pv Maa.AppDir/usr/share/icons/hicolor/512x512/apps/ cp -v Maa.AppDir/maa.png Maa.AppDir/usr/share/icons/hicolor/512x512/apps/ + cp -v appimage-maa Maa.AppDir/usr/share/maa/maa chmod a+x Maa.AppDir/usr/share/maa/maa cat > Maa.AppDir/maa.desktop <` 命令执行任务。 -- 通过 `maa list` 命令列出所有可用任务。 -- 通过 `maa install` 和 `maa update` 命令安装和更新 MAA 共享库和资源。 -- 通过 `maa self update` 命令更新 CLI 自身。 +- 运行预定义或自定义的任务，例如 `maa fight`， `maa run `; +- 使用 `maa install` 和 `maa update` 安装和更新`MaaCore`及资源； +- 使用 `maa self-update` 更新自身。 ## 安装 @@ -87,6 +86,68 @@ brew install MaaAssistantArknights/tap/maa-cli 更多信息可以通过 `maa help` 获取。 +## 使用 + +### 运行任务 + +`maa-cli` 的主要功能是运行任务，包括预定义的任务和自定义的任务。 + +#### 预定义任务 + +- `maa startup [client]`: 启动游戏并进入主界面，`[client]` 是客户端类型，如果留空则不会启动游戏客户端。 +- `maa closedown`: 关闭游戏客户端； +- `maa fight [stage]`: 运行战斗任务，`[stage]` 是关卡名称，例如 `1-7`；留空选择上次或者当前关卡； +- `maa copilot `: 运行自动战斗任务，其中 `` 是作业的 URI，其可以是 `maa://1234` 或者本地文件路径 `./1234.json`； +- `maa roguelike [theme]`: 运行 roguelike 模式的战斗任务，`[theme]` 是 roguelike 模式的主题，可选值为 `Phantom`，`Mizuki` 以及 `Sami`； + +#### 自定义任务 + +你可以通过 `maa run ` 来运行自定义任务。这里的 `` 是一个任务的名字，你可以通过 `maa list` 来列出所有可用的任务。 +具体的任务定义可以在 [配置小节](#定义自定义任务) 中找到。 + +#### 任务总结 + +`maa-cli` 会在任务运行结束后向 stdout 输出任务总结，包括每个子任务的运行时间和结果。你可以通过 `--no-summary` 选项来禁用任务总结。 + +任务总结主要包括各任务的运行时间。对于以下任务，还会包括其他信息： + +- 刷理智 `fight`: 关卡名称，次数以及掉落统计； +- 基建换班 `infrast`: 各设施进驻的干员，对于制造站和贸易站，还会包括产物类型； +- 公招 `recruit`: 公招标签刷新次数，招募次数以及检测到的 tag 及星级。 +- 肉鸽 `roguelike`: 进行的次数，投资的次数。 + +#### 日志输出 + +`maa-cli` 默认会向 stderr 输出日志。日志输出级别从低到高分别为 `Error`，`Warn`，`Info`，`Debug` 和 `Trace`。默认的日志输出级别为 `Warn`。日志级别可以通过 `MAA_LOG` 环境变量来设置，例如 `MAA_LOG=debug`。你也可以通过 `-v` 或者 `-q` 来增加或者减少日志输出级别。 + +`--log-file` 选项可以将日志输出到文件中，日志保存在 `$(maa dir log)/YYYY/MM/DD/HH:MM:SS.log` 中，其中 `$(maa dir log)` 是日志目录，你可以通过 `maa dir log` 获取。你也可以通过 `--log-file=path/to/log` 来指定日志文件的路径。 + +### 安装和更新 + +#### 安装和更新 MaaCore + +你可以通过 `maa install` 和 `maa update` 来安装和更新 `MaaCore` 及资源，更多信息可以通过 `maa help install` 和 `maa help update` 获取。 + +#### 资源热更新 + +由于游戏的更新，`MaaCore` 需要最新的资源才能正常运行，你可以通过 `maa hot-update` 来更新资源，或者设置资源自动更新，详见 [CLI 相关配置](#maa-cli-相关配置) + +#### 更新自身 + +你可以通过 `maa self update` 来更新 `maa-cli` 自身，注意对于由包管理器安装的 `maa-cli`，你应该使用包管理器来更新 `maa-cli`。 + +更多其他的命令可以通过 `maa help` 获取。 + +### 其他子命令 + +- `maa list`: 列出所有可用的任务； +- `maa dir `: 获取特定目录的路径，比如 `maa dir config` 可以用来获取配置目录的路径; +- `maa version`: 获取 `maa-cli` 以及 `MaaCore` 的版本信息； +- `maa convert [output]`: 将 `JSON`，`YAML` 或者 `TOML` 格式的文件转换为其他格式; +- `maa complete `: 生成自动补全脚本; +- `maa activity [client]`: 获取游戏的当前活动信息，`client` 是客户端类型，默认为 `Official`。 + + ## 配置 ### 配置目录 @@ -101,10 +162,11 @@ brew install MaaAssistantArknights/tap/maa-cli #### 基本结构 -一个任务文件包含多个子任务，每一个子任务是一个[MAA 任务](../协议文档/集成文档.md#asstappendtask)： +一个任务文件包含多个子任务，每一个子任务是一个 [MAA 任务](../协议文档/集成文档.md#asstappendtask)，其包含一下几个选项： ```toml [[tasks]] +name = "启动游戏" # 任务的名字，可选，默认为任务类型 type = "StartUp" # maa任务的类型 params = { client_type = "Official", start_game_enabled = true } # maa任务的参数 ``` @@ -115,6 +177,7 @@ params = { client_type = "Official", start_game_enabled = true } # maa任务的 ```toml [[tasks]] +name = "基建换班" type = "Infrast" [tasks.params] @@ -141,22 +204,12 @@ params = { plan_index = 0 } **注意**：如果你的自定义基建计划文件使用相对路径，应该相对于 `$MAA_CONFIG_DIR/infrast`。此外，由于基建文件是由 `MaaCore` 而不是 `maa-cli` 读取的，因此这些文件的格式必须是 `JSON`。同时，`maa-cli` 不会读取基建文件，也不会根据其中定义的时间段来选择相应的子计划。因此，必须通过 `condition` 字段来指定在相应时间段使用正确的基建计划的参数中的 `plan_index` 字段。这样可以确保在适当的时间段使用正确的基建计划。 -除了 `Time` 条件，还有 `DateTime`，`Weakday` 以及 `Combined` 条件。`DateTime` 条件用于指定一个时间段，`Weekday` 条件用于指定一周中的某些天，`Combined` 条件用于指定多个条件的组合。 +除了 `Time` 条件，还有 `DateTime`，`Weakday` 条件。`DateTime` 条件用于指定一个时间段，`Weekday` 条件用于指定一周中的某些天。 ```toml [[tasks]] type = "Fight" -# 周一早上刷5次剿灭 -[[tasks.variants]] -params = { "stage" = "Annihilation", times = 5 } -[tasks.variants.condition] -type = "Combined" -conditions = [ - { type = "Weekday", weekdays = ["Mon"] }, - { type = "Time", end = "12:00:00" }, -] - # 在夏活期间，刷SL-8 [[tasks.variants]] params = { stage = "SL-8" } @@ -172,6 +225,10 @@ params = { stage = "CE-6" } params = { stage = "1-7" } ``` +除了上述确定的条件之外，还有一个依赖于热更新资源的条件 `OnSideStory`，当你启动该条件后，`maa-cli` 会尝试读取相应的资源来判断当前是否有正在开启的活动，如果有那么对应的变体会被匹配。 比如上述夏活期间刷 `SL-8` 的条件就可以简化为 `{ type = "OnSideStory", client = "Official" }`，这里的 `client` 参数用于确定你使用的客户端，因为不同的客户端的活动时间不同，对于使用官服或者 b 服的用户，这可以省略。通过这个条件，每次活动更新之后你可以只需要更新需要刷的关卡而不需要手动编辑对应活动的开放时间。 + +除了以上基础条件之外，你可以使用 `{ type = "And", conditions = [...] }`，`{ type = "Or", conditions = [...] }`, `{ type = "Not", condition = ... }` 来对条件进行逻辑运算。 + 在默认的策略下，如果有多个变体被匹配，第一个将会被使用。如果没有给出条件，那么变体将会总是被匹配，所以你可以把没有条件的变体放在最后，作为默认的情况。 你可以使用 `strategy` 字段来改变匹配策略： @@ -186,7 +243,7 @@ strategy = "merge" # 或者 "first" (默认) params = { expiring_medicine = 1000 } [tasks.variants.condition] -type = "Combined" +type = "And" conditions = [ { type = "Time", start = "18:00:00" }, { type = "Weekday", weekdays = ["Sun"] }, @@ -205,16 +262,6 @@ params = { stage = "CE-6" } [[tasks.variants]] params = { stage = "SL-8" } condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" } - -# 周一早上刷5次剿灭 -[[tasks.variants]] -params = { "stage" = "Annihilation", times = 5 } -[tasks.variants.condition] -type = "Combined" -conditions = [ - { type = "Weekday", weekdays = ["Mon"] }, - { type = "Time", end = "12:00:00" }, -] ``` 这个例子和上面的例子将刷同样的关卡，但是在周天晚上，将会使用所有的将要过期的理智药。在 `merge` 策略下，如果有多个变体被匹配，后面的变体的参数将合并入前面的变体的参数中。如果多个变体都有相同的参数，那么后面的变体的参数将会覆盖前面的变体的参数。 @@ -242,8 +289,15 @@ type = "Fight" [[tasks.variants]] condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" } [tasks.variants.params.stage] -alternatives = ["SL-6", "SL-7", "SL-8"] # 可选的关卡，必须提供至少一个可选值 +# 可选的关卡，必须提供至少一个可选值 +# 可选值可以是一个值，也可以是同时包含值和描述的一个表 +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]] @@ -255,11 +309,18 @@ params = { stage = "CE-6" } [tasks.variants.params.stage] default = "1-7" # 默认的关卡，可选（如果没有默认值，输入空值将会重新提示输入） description = "a stage to fight" # 描述，可选 +[tasks.variants.params.medicine] +# 依赖的参数，键为参数名，值为依赖的参数的预期值 +# 当设置时，只有所有的依赖参数都满足预期值时，这个参数才会被要求输入 +deps = { stage = "1-7" } +default = 1000 +description = "medicine to use" ``` -对于 `Input` 类型，当运行任务时，你将会被提示输入一个值。如果你输入了一个空值，那么默认值将会被使用。 -对于 `Select` 类型，当运行任务时，你将会被提示选择一个值 （通过输入可选值的序号）。 -注意，当你的输入不是可选值时，你将会被提示重新输入。 +对于 `Input` 类型，当运行任务时，你将会被提示输入一个值。如果你输入了一个空值，如果有默认值，那么默认值将会被使用，否则你将会被提示重新输入。 +对于 `Select` 类型，当运行任务时，你将会被提示输入一个的索引或者自定义的值（如果允许）。如果你输入了一个空值，如果有默认值，那么默认值将会被使用，否则你将会被提示重新输入。 + +`--batch` 选项可以用于在运行任务时跳过所有的输入，这将会使用默认值；如果有任何输入没有默认值，那么将会导致错误。 ### MaaCore 相关配置 @@ -267,15 +328,17 @@ description = "a stage to fight" # 描述，可选 目前其包含的配置有： ```toml -user_resource = true -resources = ["platform_diff/iOS"] - [connection] type = "ADB" adb_path = "adb" device = "emulator-5554" config = "CompatMac" +[resource] +global_resource = "YoStarEN" +platform_diff_resource = "iOS" +user_resource = true + [static_options] cpu_ocr = false gpu_ocr = 1 @@ -287,9 +350,7 @@ adb_lite_enabled = false kill_adb_on_exit = false ``` -`user_resource` 字段用于指定是否从用户资源目录加载资源，它的默认值是`false`。这个参数和命令行选项 `--user-resource` 相同。更多信息可以通过 `maa help run` 获取。 - -`resources`字段用于指定资源的路径，这是一个资源目录列表，如果是相对路径，它应该相对于 `resource` 目录（`maa dir resource`）。这可以用来加载外服资源或者平台差异资源。 +#### 连接配置 `[connection]` 相关字段用于指定 MaaCore 连接游戏的方式和参数。目前可用的连接方式有 `ADB` 和 `PlayTools`。 @@ -303,6 +364,8 @@ device = "emulator-5554" # 你的android设备的序列号 config = "General" # maa connect的配置 ``` +注意，此处的 device 是任何 `adb -s` 可以接受的值，比如 `emulator-5554` 和 `127.0.0.1:5555`。 + 当你使用 `PlayTools` 连接时，你需要提供 `PlayTools` 的地址： ```toml @@ -314,26 +377,99 @@ config = "CompatMac" # maa connect的配置 两者都需要提供 `config`，这个值将被传给 MaaCore，用于指定一些平台和模拟器相关的配置。对于 Linux 他默认为 `CompatPOSIXShell`，对于 macOS 他默认为 `CompatMac`，对于 Windows 他默认为 `General`。更多可选配置可以在资源文件夹中的 `config.json` 文件中找到。 -`[instance_options]` 相关字段用于指定 MaaCore 实例的选项，详见 [集成文档](../协议文档/集成文档.md#asstsetinstanceoption)： +#### 资源配置 + +`[resource]` 相关字段用于指定 MaaCore 加载的资源： + +```toml +[resource] +global_resource = "YoStarEN" # 非中文版本的资源 +platform_diff_resource = "iOS" # 非安卓版本的资源 +user_resource = true # 是否加载用户自定义的资源 +``` + +当使用非简体中文游戏客户端时，由于 `MaaCore` 默认加载的资源是简体中文的，你需要指定 `global_resource` 字段来加载非中文版本的资源。当使用 iOS 版本的游戏客户端时，你需要指定 `platform_diff_resource` 字段来加载 iOS 版本的资源。这两者都是可选的，如果你不需要加载这些资源，你可以将这两个字段设置为空。其次，这两者也会被自动设置，如果你的 `startup` 任务中指定了 `client_type` 字段，那么 `global_resource` 将会被设置为对应客户端的资源，而当你使用 `PlayTools` 连接时，`platform_diff_resource` 将会被设置为 `iOS`。最后，当你想要加载用户自定义的资源时，你需要将 `user_resource` 字段设置为 `true`。 + +#### 静态选项 + +`[static_options]` 相关字段用于指定 MaaCore 静态选项，详见 [集成文档](../协议文档/集成文档.html#asstsetstaticoption)： + +```toml +[static_options] +cpu_ocr = false # 是否使用 CPU OCR，默认使用 CPU OCR +gpu_ocr = 1 # 使用 GPU OCR 时使用的 GPU ID，如果这个值被留空，那么将会使用 CPU OCR +``` + +#### 实例选项 + +`[instance_options]` 相关字段用于指定 MaaCore 实例的选项，详见 [集成文档](../协议文档/集成文档.html#asstsetinstanceoption)： ```toml [instance_options] -touch_mode = "ADB" # 使用的触摸模式，可选值为"ADB", "MiniTouch", "MAATouch" 或者 "MacPlayTools"(仅适用于PlayCover) +touch_mode = "ADB" # 使用的触摸模式，可选值为 "ADB"，"MiniTouch"，"MAATouch" 或者 "MacPlayTools" deployment_with_pause = false # 是否在部署时暂停游戏 -adb_lite_enabled = false # 是否使用adb-lite -kill_adb_on_exit = false # 是否在退出时杀死adb +adb_lite_enabled = false # 是否使用 adb-lite +kill_adb_on_exit = false # 是否在退出时杀死 adb ``` -注意，如果你使用`PlayTools`，`touch_mode`字段将被忽略并被设置为`MacPlayTools`。 +注意，`touch_mode` 可选项 `MacPlayTools` 和连接方式 `PlayTools` 绑定。当你使用 `PlayTools` 连接时，`touch_mode` 将会被强制设置为 `MacPlayTools`。 ### `maa-cli` 相关配置 `maa-cli` 相关的配置需要放在 `$MAA_CONFIG_DIR/cli.toml` 中。目前其包含的配置如下： ```toml +# MaaCore 安装和更新相关配置 [core] -channel = "beta" -components.resource = false +channel = "Stable" # 更新通道，可选值为 "Alpha"，"Beta" "Stable"，默认为 "Stable" +test_time = 0 # 用于测试镜像速度的时间，0 表示不测试，默认为 3 +# 查询 MaaCore 最新版本的 api 地址，留空表示使用默认地址 +api_url = "https://github.com/MaaAssistantArknights/MaaRelease/raw/main/MaaAssistantArknights/api/version/" + +# 配置是否安装 MaaCore 对应的组件，不推荐使用，分开安装可能会导致版本不一致，从而导致一些问题，该选项可能在未来的版本中移除 +[core.components] +library = true # 是否安装 MaaCore 的库，默认为 true +resource = true # 是否安装 MaaCore 的资源，默认为 true + +# CLI 更新相关配置 +[cli] +channel = "Stable" # 更新通道，可选值为 "Alpha"，"Beta" "Stable"，默认为 "Stable" +# 查询 maa-cli 最新版本的 api 地址，留空表示使用默认地址 +api_url = "https://github.com/MaaAssistantArknights/maa-cli/raw/version/" +# 下载预编译二进制文件的地址，留空表示使用默认地址 +download_url = "https://github.com/MaaAssistantArknights/maa-cli/releases/download/" + +# 配置是否安装 maa-cli 对应的组件 +[cli.components] +binary = true # 是否安装 maa-cli 的二进制文件，默认为 true + +# 资源热更新相关配置 +[resource] +auto_update = true # 是否在每次运行任务时自动更新资源，默认为 false +backend = "libgit2" # 资源热更新后端，可选值为 "git" 或者 "libgit2"，默认为 "git" + +# 资源热更新远程仓库相关配置 +[resource.remote] +branch = "main" # 远程仓库的分支，默认为 "main" +# 远程仓库的 url，如果你想要使用 ssh，你必须配置 ssh_key 的路径 +url = "https://github.com/MaaAssistantArknights/MaaResource.git" +# url = "git@github.com:MaaAssistantArknights/MaaResource.git" +# ssh_key = "~/.ssh/id_ed25519" # ssh 私钥的路径，支持展开 ~ 但不支持其他环境变量 ``` -`[core]` 相关字段用于指定 CLI 安装和更新 `MaaCore` 的方式。`channel` 字段用于指定 `MaaCore` 的更新通道，可选值为 `stable` 和 `beta`，`alpha`。`components.resource` 字段用于指定是否安装资源。 +**注意事项**： + +- MaaCore 的更新通道中 `Alpha` 只在 Windows 上可用； +- 由于 CLI 默认的 API 链接和下载链接都是 GitHub 的链接，因此在国内可能会有一些问题，你可以通过配置 `api_url` 和 `download_url` 来使用镜像。 +- 即使启动了资源热更新，你依然需要安装 `MaaCore` 的资源，因为资源热更新并不包含所有的资源文件，只是包含部份可更新的资源文件，基础资源文件仍然需要安装。 +- 资源热更新是通过 Git 来拉取远程仓库，如果后端设置为 `git` 那么 `git` 命令行工具必须可用。 +- 如果你想要使用 SSH 协议来拉取远程仓库，你必须配置 `ssh_key` 字段，这个字段应该是一个路径，指向你的 SSH 私钥。 +- 远程仓库的 `url` 设置目前只对首次安装资源有效，如果你想要更改远程仓库的地址，你需要通过 `git` 命令行工具手动更改，或者删除对应的仓库。仓库所在位置可以通过 `maa dir hot-update` 获取。 +- 远程仓库的 `url` 会根据你本机的语言自动设置，如果你的语言是简体中文，那么远程仓库的 `url` 将会被设置为国内的镜像 `https://git.maa-org.net/MAA/MaaResource.git`，在其他情况则会被设置为 Github。如果你在国内但是使用的不是简体中文，或者在国外使用简体中文，那么你可能需要手动设置以获得最佳的体验。 + +### JSON Schema + +你可以在 CLI 仓库的 `maa-cli/schemas` 目录下找到 `maa-cli` 的 JSON Schema 文件，你可以使用这些文件来验证你的配置文件，或者在编辑器中获得自动补全。 +任务文件的 JSON Schema 文件为 [`task.schema.json`](https://github.com/MaaAssistantArknights/maa-cli/raw/v0.4.0/maa-cli/schemas/task.schema.json)； +MaaCore 相关配置的 JSON Schema 文件为 [`asst.schema.json`](https://github.com/MaaAssistantArknights/maa-cli/raw/v0.4.0/maa-cli/schemas/task.schema.json)； +CLI 相关配置的 JSON Schema 文件为 [`cli.schema.json`](https://github.com/MaaAssistantArknights/maa-cli/raw/v0.4.0/maa-cli/schemas/task.schema.json)。 diff --git a/src/maa-cli b/src/maa-cli index 8984241d39..a7e26217fa 160000 --- a/src/maa-cli +++ b/src/maa-cli @@ -1 +1 @@ -Subproject commit 8984241d390ece5fbd7659fa9568b8b660d3f4df +Subproject commit a7e26217fa0673c7bda46a6fb9097e9ff7f6d63f