快速开始
开发思路
MaaFramework 提供三种集成方案，满足不同开发场景需求：
方案一：纯 JSON 低代码编程
适用场景：快速入门、简单逻辑实现
特点:
{
"点击开始按钮": {
"recognition": "OCR", // 文字识别引擎
"expected": "开始", // 目标文本
"action": "Click", // 执行点击操作
"next": ["点击确认图标"] // 后续任务链
},
"点击确认图标": {
"recognition": "TemplateMatch",// 图像模板匹配
"template": "确认.png", // 匹配素材路径
"action": "Click"
}
}方案二：JSON + 自定义逻辑扩展（推荐）
特点:
- 保留 JSON 低代码优势，核心流程依旧可视化维护
- 在 Agent 进程中注册并托管自定义识别/动作模块，便于承载复杂逻辑
- 无缝衔接 ⭐项目模板，快速获取脚手架与示例
{
"点击确认图标": {
"next": ["自定义处理模块"]
},
"自定义处理模块": {
"recognition": "Custom",
"custom_recognition": "MyReco", // 自定义识别器ID
"action": "Custom",
"custom_action": "MyAct" // 自定义动作ID
}
}💡 通用 UI 会自动连接到您的 Agent 进程，在执行到 MyReco/MyAct 时调用已注册的识别/动作实现。
# Python 伪代码示例
from maa.agent.agent_server import AgentServer
# 注册自定义识别器
@AgentServer.custom_recognition("MyReco")
class CustomReco:
def analyze(ctx):
return (10,10,100,100) # 返回您自己处理的识别结果
# 注册自定义动作
@AgentServer.custom_action("MyAct")
class CustomAction:
def run(ctx):
ctx.controller.post_click(100, 10).wait() # 执行点击
ctx.override_next(["TaskA", "TaskB"]) # 动态调整任务流
# 启动Agent服务
AgentServer.start_up(sock_id)完整示例参考 模板 Commit。
方案三：全代码开发
NOTE
MaaFramework 提供多语言 API，但仍不建议采用全代码工作流，因为这会失去可视化节点编辑器、可视化调试器、通用 UI 等生态工具。大部分复杂需求都可以通过方案二的自定义扩展实现。
适用场景:
- 深度定制需求
- 复杂业务逻辑实现
- 需要灵活控制执行流程
# Python 伪代码示例
def main():
# 执行 JSON 预定义任务
result = tasker.post_task("点击开始按钮").wait().get()
if result.completed:
# 执行代码级操作
tasker.controller.post_click(100, 100)
else:
# 获取当前屏幕截图
image = tasker.controller.cached_image
# 注册自定义动作
tasker.resource.register_custom_action("MyAction", MyAction())
# 执行混合任务链
tasker.post_task("点击确认图标").wait()资源准备
在确认开发方案后，请准备相应的资源文件，下面以项目模板为基线进行说明。
TIP
- 若您使用项目模板，可直接参考下文中
TIP标记的部分进行资源准备。 - 若您选择全代码开发，同样需要准备图像素材、文字识别模型等资源，否则相关的图像识别功能将无法使用。
文件结构规范
TIP
⭐若您使用项目模板，直接在 文件夹 中修改即可。
my_resource/
├── image/ # 图像素材库
│ ├── my_button_ok.png
│ └── my_icon_close.png
├── model/
│ └── ocr/ # 文字识别模型
│ ├── det.onnx
│ ├── keys.txt
│ └── rec.onnx
└── pipeline/ # 任务流水线
├── my_main.json
└── my_subflow.json其中以 my_ 开头的文件/文件夹均可自行修改名称，其他的则为固定文件名，不可修改，下面依次介绍：
任务流水线
my_resource/pipeline 中的文件，包含主要的脚本执行逻辑，会递归读取目录中所有的 json 格式文件。
推荐使用以下开发工具：
- JSON Schema
- VSCode 插件
- 基于
interface.json配置资源 - 支持跳转到任务定义、查找任务引用、重命名任务、补全任务、点击执行任务
- 支持按照 MaaPiCli 模式执行
- 支持连接后截图并裁剪图片
- 基于
- MaaPipelineEditor
- 零代码开发，可视化编辑器，支持拖拽节点、导入导出 JSON
图像素材
my_resource/image 中的文件，主要为 pipeline 所用到的模板匹配图片、特征检测图片等，会按照 pipeline 中设定的 template 等字段读取对应的文件。
所使用的图片需要基于无损原图缩放到 720p 后再裁剪。除非您完全了解 MaaFramework 的处理流程，否则建议使用下方工具获取截图，避免因缩放或编码导致识别异常。
文字识别模型文件
TIP
⭐若您使用项目模板，直接按照其文档，运行 configure.py 即可自动部署模型文件。
my_resource/model/ocr 中的文件，为 PaddleOCR 转 ONNX 后的模型文件。
可使用我们的预转换文件：MaaCommonAssets，选择需要的语种，按照 上述 目录结构存放即可。
若有需要也可以自行对 PaddleOCR 的官方预训练模型进行 fine-tuning （请自行参考 PaddleOCR 官方文档），并转换成 ONNX 文件使用，转换命令可参考 这里
调试
当您完成了资源准备后，即可开始调试工作。
NOTE
若您使用全代码开发，本章节调试工具可能无法使用，可尝试自行编写调试代码。
多数工具会在同目录下生成 config/maa_option.json 文件，其中：
logging: 保存日志，会生成debug/maa.log。默认 true 。save_draw: 保存图像识别可视化结果，会保存运行期间所有图像识别可视化结果绘制图。默认 false 。stdout_level: 控制台显示日志等级。默认 2（Error），可设为 0 关闭全部控制台日志，或设为 7 打开全部控制台日志。save_on_error: 任务失败时保存当前截图。默认 true 。draw_quality: 图像识别可视化结果的 JPEG 质量（0-100）。默认 85 。
若自行集成，可通过 Toolkit.init_option / MaaToolkitConfigInitOption 接口开启调试选项。生成的 json 文件同上。
运行
NOTE
若您使用全代码开发，本章节 UI 应用可能无法使用，建议自行编写交互界面。
我们定义了一套 ProjectInterface 协议，用于描述项目所需的资源文件及运行配置，以便通用 UI 能够正确加载和运行您的项目。
说人话就是，按文档再写个 interface.json，用来告诉通用 UI 你的资源文件放哪儿了、有哪些任务可以执行等等，这样通用 UI 才能帮你跑起来。
最佳实践参考:
全代码开发
沟通交流
欢迎开发者加入官方 QQ 群（595990173），交流集成与开发实践。群内仅讨论开发相关议题，不提供日常使用/客服支持；为保证讨论质量，长期离题或违规的成员可能会被移除。