rust写的maa命令行工具

[wangl-cc]

Linux使用maa比较困难，目前的方法主要是写Python脚本来调用MaaCore，但是敲代码有一定门槛，并且更改起来比较麻烦，所以我用rust写了一个命令行工具maa-cli，用来在Linux上使用Maa。因为Linux和macOS大多地方都是一样的，所有这个工具也支持mac（Intel，Arm都支持，但是不知道是哪里的bug，通过命令行打开PlayCover下的明日方舟可以登陆，但是无法获得作战记录）。Windows的话，一个我没有Windows设备，一个我也不懂Windows开发，所以我虽然尝试了支持Windows，但是始终不能编译通过，所以就放弃了（当然如果有大佬对这个项目有一点小小的兴趣来帮助支持Windows，我会非常感谢）。我本来是也是打算用Python写（如果用Python写可能就没有多平台支持的问题了），但是由于刚好我最近在学习rust，而且rust刚好有很好的工具库，就决定用这个项目当作练习。因为我是rust小白，写的可能有很多有问题的地方，所以欢迎各位大佬对项目提意见。

接下来言归正传，我来介绍一下我这个命令行工具的功能：

通过配置文件定义任务，并通过maa run <task>运行

这个工具的核心功能就是降低写代码的麻烦，但是我们需要写配置文件来配置我们一键收菜的时候干什么。

配置文件可以是TOML,YAML或者JSON，我个人更喜欢TOML来写配置，所以以TOML为例子.
一个任务文件包含多个子任务，每一个子任务是一个MAA任务链：

[[tasks]]
type = "StartUp" # maa任务的类型
params = { client_type = "Official", start_game_enabled = true } # maa任务的参数

如果你想要根据一些条件运行不同参数的任务，你可以定义多个任务的变体：

[[tasks]]
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`

# 在12:00:00之前使用计划1，在12:00:00到18:00:00之间使用计划2，在18:00:00之后使用计划0
[[tasks.variants]]
condition = { type = "Time", end = "12:00:00" } # 如果没有定义start，那么它将会是00:00:00
params = { plan_index = 1 }

[[tasks.variants]]
condition = { type = "Time", start = "12:00:00", end = "18:00:00" }
params = { plan_index = 2 }

[[tasks.variants]]
condition = { type = "Time", start = "18:00:00" }
params = { plan_index = 0 }

这里的condition字段用于确定哪一个变体应该被使用，而匹配的变体的params字段将会被合并到任务的主参数中。

注意：这个CLI不会读取基建计划文件中的任何内容，包括基建计划文件中定义的时间段，所以你必须在condition字段中定义时间段，来在不同的时间运行不同的基建计划。

除了Time条件，还有DateTime，Weakday和Combined（其他条件的组合）条件：

[[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" }
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"] }
params = { stage = "CE-6" }

# 其他时间，刷1-7
[[tasks.variants]]
params = { stage = "1-7" }

如果有多个变体被匹配，第一个将会被使用。如果没有给出条件，那么变体将会总是被匹配，所以你可以把没有条件的变体放在最后，作为默认的情况。

如果没有变体被匹配，那么任务将不会被执行，这在你想要只在某些条件下运行任务时很有用：

# 只在在18:00:00之后进行信用商店相关的操作
[[tasks]]
type = "Mall"
[tasks.params]
shopping = true
credit_fight = true
buy_first = ["招聘许可", "龙门币"]
blacklist = ["碳", "家具", "加急许可"]
[[tasks.variants]]
condition = { type = "Time", start = "18:00:00" }

我自己用的配置文件你可以在这里找到。

MaaCore消息处理

写Python脚本的另一个痛点就是没有现成的Callback，自己实现起来很麻烦，任务出问题了可能要去查log。这个CLI我参考WindowsGUI的消息处理，捏了一个我觉得还凑活的输出，并且可以通过-v和-q参数来改变消息等级（Log level)，从而实现减少或者增加消息。

这是maa run daily -v情况下的输出：

有个问题就是没有本地化，可能有些消息不太好懂。

安装和更新MaaCore

maa install [channel] 和 maa update [channel]命令可以用来安装和更新MaaCore本身，这里的channel可以是stable，beta和alpha，stable就是下载并安装最新的稳定版，另外则是两个相应的beta和alpha，如果省略这个参数，默认是稳定版。这个下载是从maa的API来获取版本信息，并且对可用的镜像测速，最后选最快的下载，所以不用担心下不下来。

安装和更新这个工具本身

maa self install 和 maa self update用来安装和更新这个工具本身。这个工具本身包括两个部分maa和maa-run，前者是用来和用户交互的，后者是用来和MaaCore交互的。由于我不想让这个工具带着MaaCore本身一起发布（这样可以让两者分别单独更新)，而rust有没有办法在链接的库不存在的情况下运行，所以我把所有和MaaCore交互的库放在了maa-run里面。在安装的时候只需要下载maa这个工具然后用maa self install来安装maa-run。而maa self update会同时检查两个工具是否都是最新版，如果不是是就可以下载并安装相应的最新版。不过由于我这个工具没有镜像，版本信息和包都存在Github上，所以在国内可能会存在下不动的情况。这种情况一个可选的方法是找一个Github代理的网站，然后设置MAA_CLI_API和MAA_CLI_DOWNLOAD两个环境变量，比如这样:

export MAA_CLI_API=https://ghproxy.com/https://raw.githubusercontent.com/wangl-cc/maa-cli/version/version.json
export MAA_CLI_DOWNLOAD=https://ghproxy.com/https://github.com/wangl-cc/maa-cli/releases/download
maa self install

更多的其他部分细节，欢迎大家去我的仓库查看。也希望这个小工具会对在Linux上使用MAA的小伙伴们有用。

[MistEO]

考虑 PR 给我们吗 XD

[MistEO]

总之先发了个邀请（

[wangl-cc]

如果作为Submodule或者把代码拷过来加入这个仓库的话，那这个CLI是需要和在MaaCore和其他组件一起发布吗？

[wangl-cc]

感谢邀请，我先把仓库transfer了。

[MistEO]

是呀，起码 linux 版本我们确实需要一个可以直接跑的 exec

构建 CI 不知道工作量怎么样，如果不熟悉的话也可以等它自己长出来（bushi

不过文档确实可以先弄一个（伸手，可能可以作为一个独立的文档？https://github.com/MaaAssistantArknights/MaaAssistantArknights/tree/dev/docs / 1.6-CLI使用指南.md 怎么样？这里的文档会在下次发版时自动部署到我们的官网

主文档的 https://github.com/MaaAssistantArknights/MaaAssistantArknights/tree/dev#%E4%BD%BF%E7%94%A8%E8%AF%B4%E6%98%8E 下也可以加个新章节，简单一句话介绍再弄个链接跳转到新增的 1-6.md 这样

[wangl-cc]

如果一起打包的话，CI应该还好，先把MaaCore编译好再去编译CLI，然后两者一起打包应该就行了。这个CLI是在runtime去找MaaCore的位置，这个仓库本身的CI就是下载一个MaaCore在编译的，和MaaCore一起打包，增加一个路径或者写好rpath应该就行了。不过可以直接让Linux用户去下载不带Core的CLI，然后用在用CLI去下载和安装Core吗（就和MaaX一样）？因为现在的实现是把Core存在用户数据文件夹里（对于Linux是$HOME/.local/share/maa），用户安装打包好的CLI和Core的话不知道会把Core安装在哪里，然后更新的时候可能就会存在多个Core并存。

文档的话，我觉得可以作为一个独立文档，毕竟确实和别的部分重合度不大，如果这样可以的话，我就按照现在的用法，先给文档加上。

[horror-proton]

我不大熟悉 Rust 的 binding, 这里是不是有两个部分, 只有 maa-run 是需要链接 MaaCore 的, 这两个的版本也没有很强的依赖, 只要函数签名没变不需要每次 Core 更新都重新编译 maa-run?

[wangl-cc]

rust在编译的时候好像只需要从库里面获得符号表，我试过一次编译以后换用不同版本的core是可以不用重新编译的，当然我不确定这个这样会不会回有别的问题。如果这样有问题的话，那就打包最好。另外，rust本身不推荐动态库库，因为没有稳定的ABI，我之前写的时候搜了一下，他们推荐的做法是连依赖一起静态连接成一个整个可执行文件。

另外cli其实运行maa run任务的时候是直接开了一个maa-run的subprocess，然后把所有的参数都传给了maa-run。这样的主要目的就是为了在没有就可以在没有core情况下运行其他部分比如安装core，如果和core一起打包的话其实两部分就不需要分离了。

[horror-proton]

用户安装打包好的CLI和Core的话不知道会把Core安装在哪里，然后更新的时候可能就会存在多个Core并存

这听上去是可以解决的, 比如先找相对路径 ../share/maa 如果没有再去找 $XDG_DATA_HOME/maa 之类的.

但是 rpath 好像就比较麻烦了, 设成 ../share/maa 的话那装在其他地方的 cli 要就找不到 ~/.local/share 里面的 maa 了. 用 dlopen 就没这问题了 (逃

或者直接放弃治疗在 maa install 的时候先 ln -s ~/.local/share/maa share/maa 好像也不错 (

[wangl-cc]

这听上去是可以解决的, 比如先找相对路径 ../share/maa 如果没有再去找 $XDG_DATA_HOME/maa 之类的。
但是 rpath 好像就比较麻烦了, 设成 ../share/maa 的话那装在其他地方的 cli 要就找不到 ~/.local/share 里面的 maa 了. 用 dlopen 就没这问题了 (逃

多搜索一个可以，我现在改变动态库的位置其实其实是靠改变父进程改变了LD_LIBRARY_PATH实现的，加一个路径很容易，rpath实际上完全没用。原来可以用dlopen，是我傻了。

[wangl-cc]

See #6144.