# 1.1 快速开始

## 开发思路

MaaFramework 提供三种集成方案，满足不同开发场景需求：

> [!TIP]
> 害怕看不懂？没关系，社区内有很多成熟的 [项目](https://github.com/MaaXYZ/MaaFramework?tab=readme-ov-file#%E5%BA%94%E7%94%A8%E7%A8%8B%E5%BA%8F) 可供参考。

### 方案一：纯 JSON 低代码编程

**适用场景**：快速入门、简单逻辑实现

**特点**:

- 零编码基础要求
- 通过 JSON 配置实现自动化流程
- 配套 [🎞️视频教程](https://www.bilibili.com/video/BV1yr421E7MW) 和 [⭐项目模板](https://github.com/MaaXYZ/MaaPracticeBoilerplate) （该视频教程使用的版本较老，部分内容可能过时。差异内容请以本仓库文档为准！）
- 结合 [MaaPipelineEditor](https://mpe.codax.site/stable/) 可视化编辑器进行拖拽式开发

```jsonc
{
    "点击开始按钮": {
        "recognition": "OCR",          // 文字识别引擎
        "expected": "开始",            // 目标文本
        "action": "Click",             // 执行点击操作
        "next": ["点击确认图标"]        // 后续任务链
    },
    "点击确认图标": {
        "recognition": "TemplateMatch",// 图像模板匹配
        "template": "确认.png",        // 匹配素材路径
        "action": "Click"
    }
}
```

### 方案二：JSON + 自定义逻辑扩展（推荐）

**特点**:

- 保留 JSON 低代码优势，核心流程依旧可视化维护
- 在 Agent 进程中注册并托管自定义识别/动作模块，便于承载复杂逻辑
- 无缝衔接 [⭐项目模板](https://github.com/MaaXYZ/MaaPracticeBoilerplate)，快速获取脚手架与示例

```jsonc
{
    "点击确认图标": {
        "next": ["自定义处理模块"]
    },
    "自定义处理模块": {
        "recognition": "Custom",
        "custom_recognition": "MyReco",  // 自定义识别器ID
        "action": "Custom",
        "custom_action": "MyAct"         // 自定义动作ID
    }
}
```

💡 通用 UI 会自动连接到您的 Agent 进程，在执行到 `MyReco`/`MyAct` 时调用已注册的识别/动作实现。

```python
# 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](https://github.com/MaaXYZ/MaaPracticeBoilerplate/commit/126a56cefc17bf6c8335c703387d8d3ee2dad4d1)。

### 方案三：全代码开发

> [!NOTE]
> MaaFramework 提供多语言 API，但仍不建议采用全代码工作流，因为这会失去可视化节点编辑器、可视化调试器、通用 UI 等生态工具。大部分复杂需求都可以通过方案二的自定义扩展实现。

**适用场景**:

- 深度定制需求
- 复杂业务逻辑实现
- 需要灵活控制执行流程

```python
# 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]
>
> ⭐若您使用项目模板，直接在 [文件夹](https://github.com/MaaXYZ/MaaPracticeBoilerplate/tree/main/assets/resource) 中修改即可。

```tree
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 格式文件。

可参考 [任务流水线协议](3.1-任务流水线协议.md) 进行编写，一个简单的 [demo](https://github.com/MaaXYZ/MaaFramework/blob/main/sample/resource/pipeline/sample.json)

推荐使用以下开发工具：

- [JSON Schema](https://github.com/MaaXYZ/MaaFramework/blob/main/tools/pipeline.schema.json)
- [VSCode 插件](https://marketplace.visualstudio.com/items?itemName=nekosu.maa-support)
  - 基于 `interface.json` 配置资源
  - 支持跳转到任务定义、查找任务引用、重命名任务、补全任务、点击执行任务
  - 支持按照 MaaPiCli 模式执行
  - 支持连接后截图并裁剪图片
- [MaaPipelineEditor](https://mpe.codax.site/stable/)
  - 零代码开发，可视化编辑器，支持拖拽节点、导入导出 JSON

### 图像素材

`my_resource/image` 中的文件，主要为 pipeline 所用到的模板匹配图片、特征检测图片等，会按照 pipeline 中设定的 `template` 等字段读取对应的文件。

所使用的图片需要基于无损原图缩放到 720p 后再裁剪。除非您完全了解 MaaFramework 的处理流程，否则建议使用下方工具获取截图，避免因缩放或编码导致识别异常。

- [VSCode 插件](https://marketplace.visualstudio.com/items?itemName=nekosu.maa-support)
- [MFA 工具箱](https://github.com/SweetSmellFox/MFAToolsPlus)
- [图片裁剪及 ROI 获取工具](https://github.com/MaaXYZ/MaaFramework/tree/main/tools/ImageCropper)

### 文字识别模型文件

> [!TIP]
>
> ⭐若您使用项目模板，请按照其文档中的[相关步骤](https://github.com/MaaXYZ/MaaPracticeBoilerplate?tab=readme-ov-file#%E5%A6%82%E4%BD%95%E5%BC%80%E5%8F%91)操作。

`my_resource/model/ocr` 中的文件，为 [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR) 转 ONNX 后的模型文件。

可使用我们的预转换文件：[MaaCommonAssets](https://github.com/MaaXYZ/MaaCommonAssets/tree/main/OCR)，选择需要的语种，按照 [上述](#文件结构规范) 目录结构存放即可。

若有需要也可以自行对 PaddleOCR 的官方预训练模型进行 fine-tuning （请自行参考 [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR) 官方文档），并转换成 ONNX 文件使用，转换命令可参考 [MaaCommonAssets/OCR](https://github.com/MaaXYZ/MaaCommonAssets/tree/main/OCR#command)

## 调试

当您完成了资源准备后，即可开始调试工作。

> [!NOTE]
> 若您使用全代码开发，本章节调试工具可能无法使用，可尝试自行编写调试代码。

[开发工具一览](https://github.com/MaaXYZ/MaaFramework/tree/main?tab=readme-ov-file#%E5%BC%80%E5%8F%91%E5%B7%A5%E5%85%B7)

多数工具会在同目录下生成 `config/maa_option.json` 文件，其中：

- `logging`: 保存日志，会生成 `debug/maafw.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 应用可能无法使用，建议自行编写交互界面。

[通用 UI 一览](https://github.com/MaaXYZ/MaaFramework/tree/main?tab=readme-ov-file#%E9%80%9A%E7%94%A8-ui)

我们定义了一套 [ProjectInterface 协议](3.3-ProjectInterfaceV2协议.md)，用于描述项目所需的资源文件及运行配置，以便通用 UI 能够正确加载和运行您的项目。

*说人话就是，按文档再写个 `interface.json`，用来告诉通用 UI 你的资源文件放哪儿了、有哪些任务可以执行等等，这样通用 UI 才能帮你跑起来。*

- [interface.json 文档](3.3-ProjectInterfaceV2协议.md)
- [例子](https://github.com/MaaXYZ/MaaFramework/blob/main/sample/interface.json)

最佳实践参考:

- [M9A](https://github.com/MaaXYZ/M9A/tree/main/assets/interface.json)

## 全代码开发

请参考 [集成文档](2.1-集成文档.md) 和 [集成接口一览](2.2-集成接口一览.md) 。

## 项目打包

如果需要将项目打包为可执行文件，可以参考以下内容。

> [!TIP]
> 如果使用 [⭐项目模板](https://github.com/MaaXYZ/MaaPracticeBoilerplate) 进行开发，则可以通过附带的 CI 工作流进行打包。具体步骤参见模板项目中的相关说明。

如果需要自行打包，请参考各个[通用 UI](/README.md#通用-ui)对应的说明文档。

## 沟通交流

欢迎开发者加入官方 QQ 群（595990173），交流集成与开发实践。群内仅讨论开发相关议题，不提供日常使用/客服支持；为保证讨论质量，长期离题或违规的成员可能会被移除。
