MAA 远控

MAA 远控 pallas-plugin-maa

提供 MAA 设备绑定、任务排队与结果回传能力。

官方插件控制台插件商店安装命令 PyPI 版本

安装方式

需已安装 Pallas-Bot ≥ 4.0。

推荐直接在控制台插件商店安装，或在本体项目中执行：

uv run pallas ext install pallas-plugin-maa

也可单独安装本包：

uv pip install pallas-plugin-maa

开发联调：clone 本仓库后 uv pip install -e .（pyproject.toml 可配置本体 path 依赖）。

多进程分片

Pallas-Bot 支持单进程，也支持 hub + 多个 worker 的多进程部署。启用分片时：

hub 与每个 worker 须安装相同版本的本扩展包；
各进程共享同一路径的 data/（注册表、协调状态、WebUI 落盘等）；
MAA 任务队列与路由状态走 Redis 协调层；对外 HTTP 基址通常配置在 hub。

本插件通过本体 plugin_coord 与启动时的 register_maa_coord() 接入协调层；hub 角色加载 pallas_plugin_maa_hub 转发 MAA HTTP。

详见：多进程分片 · 架构说明

怎么使用

MAA 远程控制协议：getTask / reportStatus + QQ 绑定、口令排队、结果回传。

用户命令

类型	口令示例
`绑定`	`牛牛绑定MAA`、`牛牛MAA状态`、`牛牛切换MAA设备`、`牛牛MAA设备名`、`牛牛清空MAA队列`
`任务`	`牛牛长草`、`牛牛作战`、`牛牛公招`、`牛牛基建`、`牛牛截图`、`牛牛停止` 等
`高级`	`牛牛MAA任务 <type> [params]`

上手：配置 maa_public_base_url → MAA 填帮助页 URL（用户标识符 = QQ）→ 私聊绑定设备 → 群聊发口令。完整表见 牛牛帮助 → MAA 远控。

多台设备

口令	说明
`牛牛MAA状态`	列表与当前选用
`牛牛切换MAA设备`	改远控目标
`牛牛MAA设备名`	设置别名

命令权限

命令 ID	默认等级
`maa.bind`	所有人
`maa.control`	所有人
`maa.status`	所有人

详细用法、限制条件和可用范围以帮助为主。

配置项

一般只需 maa_public_base_url（WebUI 服务网关 / 连通性 亦可编辑）。

键	默认	说明
`maa_public_base_url`	空	对外 HTTP 基址
`maa_attach_screenshot`	true	指令后附加截图
`maa_combat_auto_prepare`	true	作战前自动排队关卡设置

完整键见本仓库 config.py。改 maa_get_task_path 等会重挂路由并清帮助缓存。

排障

现象	处理
未检测到轮询	MAA 端点不可达或 URL 错误；分片须 hub 配置 `maa_public_base_url` 且各 worker 共用 `data/`
状态有待拉取、MAA 无任务	分片时队列走 Redis `pallas:coord:maa_pending:*`；须 hub 能访问各 worker 端口并保证 Redis 可用
下发后无任务	未绑定或用户标识符非 QQ；查 `牛牛MAA状态`
队列有、MAA 无	设备 id 与「当前选用」不一致；可清空队列重试
截图失败	调大反代 `client_max_body_size`

维护者说明

任务分类

分类	type 示例	MAA 行为
顺序任务	`LinkStart`、`CaptureImage`、`Settings-*`	按队列顺序执行
立即任务	`CaptureImageNow`、`StopTask`、`HeartBeat`	可插队

唤醒与子项

LinkStart（牛牛长草）：含唤醒 + 按勾选跑子模块
LinkStart-WakeUp：仅唤醒
其它 LinkStart-*：不含唤醒；游戏需已在主界面
牛牛作战当前临时下发 LinkStart（COMBAT_COMMAND_TASK_TYPE），上游修复后改回 LinkStart-Combat

作战与关卡

牛牛设置关卡：最多 4 候选，仅下发 Settings-Stage1
maa_combat_auto_prepare：作战前可自动排队已保存主关卡

多 Bot 同群

群内远控口令与 牛牛MAA状态 等命令经 claim_group_handler("maa", …)，同一条群消息仅一只牛响应。私聊绑定/切换设备不受影响。

代码索引

逻辑	位置
口令 → type	`tasks.py`
HTTP	`http_api.py`、`http_routes.py`
队列/绑定	`store.py`

实现

源码位置：

worker：src/pallas_plugin_maa/
hub 入口：src/pallas_plugin_maa_hub/

实现要点：

worker 侧负责命令解析、状态管理与任务下发。
hub 侧负责对外 HTTP 暴露与分片路由转发。
分片部署时依赖共享 data/ 与 Redis 协调层保持队列一致。

说明	链接
MAA 远控 · 用户文档	文档站 · maa
插件开发入门	develop/plugin/getting-started
多进程分片	architecture/bot-process-sharding

Metadata

Release files for pallas-plugin-maa 4.0.21

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pallas-plugin-maa 4.0.21
File	Size	Uploaded
pallas_plugin_maa-4.0.21.tar.gz	3.2 MB	Aug 11, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pallas-plugin-maa 4.0.21
File	Interpreter	ABI	Platform	Reset
pallas_plugin_maa-4.0.21-py3-none-any.whl 52.3 kB Aug 11, 2026	Python 3	none	any	Details

Total release size: 3.3 MB

Release files / pallas_plugin_maa-4.0.21.tar.gz

Download URL	pallas_plugin_maa-4.0.21.tar.gz
Size	3.2 MB
Tags	Source
SHA-256 checksum How to use checksums	`ae7bb9a36adb3f6b07c1d57b11e57ab14a40ecd9bb7a168fb42152c2cccb32b0`
BLAKE2b-256 checksum How to use checksums	`abe2242718481b99176895a5dc679a255792660f4c6b63270d7abf93706d1ccf`
Upload date	Aug 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/PallasBot/Plugin-Maa
Publishing commit: github.com/PallasBot/Plugin-Maa/tree/8df4c420f63a6c13b858d10d1c146985c59d2f29

Workflow

Publishing configuration: github.com/PallasBot/Plugin-Maa/blob/8df4c420f63a6c13b858d10d1c146985c59d2f29/.github/workflows/publish-pypi.yml
Publishing logs: github.com/PallasBot/Plugin-Maa/actions/runs/31500197923/attempts/1

Artifact

Subject: pallas_plugin_maa-4.0.21.tar.gz
SHA-256 checksum: ae7bb9a36adb3f6b07c1d57b11e57ab14a40ecd9bb7a168fb42152c2cccb32b0 Verifying attestations

Release files / pallas_plugin_maa-4.0.21-py3-none-any.whl

Download URL	pallas_plugin_maa-4.0.21-py3-none-any.whl
Size	52.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`6cc6669ab13c453cb0d37259acfd5928c89ce670fa028611d9079bd3ae229a43`
BLAKE2b-256 checksum How to use checksums	`d7e4c98d8ef8893da754779661523dc0b3a5129dd1e31fac8b1addf3cdaf7011`
Upload date	Aug 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/PallasBot/Plugin-Maa
Publishing commit: github.com/PallasBot/Plugin-Maa/tree/8df4c420f63a6c13b858d10d1c146985c59d2f29

Workflow

Publishing configuration: github.com/PallasBot/Plugin-Maa/blob/8df4c420f63a6c13b858d10d1c146985c59d2f29/.github/workflows/publish-pypi.yml
Publishing logs: github.com/PallasBot/Plugin-Maa/actions/runs/31500197923/attempts/1

Artifact

Subject: pallas_plugin_maa-4.0.21-py3-none-any.whl
SHA-256 checksum: 6cc6669ab13c453cb0d37259acfd5928c89ce670fa028611d9079bd3ae229a43 Verifying attestations