Skip to content

README_zh.md

Latest commit

 

History

History
191 lines (149 loc) · 5.96 KB

README_zh.md

File metadata and controls

191 lines (149 loc) · 5.96 KB

LOGO

MaaFramework Go 绑定


English | 简体中文

MaaFramework 的 Go 语言绑定。MaaFramework 是一个基于图像识别的跨平台自动化测试框架。

🚀 无需 Cgo！ 基于 purego 的纯 Go 实现。

✨ 特性

  • 跨平台控制器 - 提供 ADB、Win32、WlRoots、macOS、PlayCover 与 Android Native 等控制后端
  • 录制与回放 - 支持将控制器操作记录为 JSONL，并用于调试与回归复现
  • 虚拟手柄控制器 - 通过 ViGEm 实现 Windows 手柄自动化
  • Toolkit 工具能力 - 支持发现 ADB 设备和桌面窗口，并管理 macOS 自动化权限
  • 图像识别 - 支持模板匹配、OCR、特征检测等识别能力
  • 自定义扩展 - 以纯 Go 实现自定义识别、自定义动作和自定义控制器
  • Agent 支持 - 支持从外部进程挂载自定义识别与动作逻辑
  • 异步任务与事件 - 支持 Job 状态轮询、详情查询以及 Resource、Controller、Tasker 事件订阅
  • 流水线与运行时编排 - 基于 JSON 的声明式任务流，并支持在 Context 中动态执行任务、识别和动作

📦 安装

1. 安装 Go 包

go get github.com/MaaXYZ/maa-framework-go/v4

2. 下载 MaaFramework

根据你的平台下载 MaaFramework Release 并解压。

平台 架构 下载
Windows amd64 MAA-win-x86_64-*.zip
Windows arm64 MAA-win-aarch64-*.zip
Linux amd64 MAA-linux-x86_64-*.zip
Linux arm64 MAA-linux-aarch64-*.zip
macOS amd64 MAA-macos-x86_64-*.zip
macOS arm64 MAA-macos-aarch64-*.zip

⚙️ 运行时要求

使用 maa-framework-go 构建的程序需要 MaaFramework 动态库才能运行。你有以下几种方式：

  1. 通过 Init() 选项 - 在代码中指定库文件路径：

    maa.Init(maa.WithLibDir("path/to/MaaFramework/bin"))

  2. 工作目录 - 将 MaaFramework 库文件放在程序的工作目录中

  3. 环境变量 - 将库文件路径添加到 PATH（Windows）或 LD_LIBRARY_PATH（Linux/macOS）

  4. 系统库路径 - 将库文件安装到系统库目录

🚀 快速开始

package main

import (
	"fmt"
	"os"

	"github.com/MaaXYZ/maa-framework-go/v4"
)

func main() {
	maa.Init()
	if err := maa.ConfigInitOption("./", "{}"); err != nil {
		fmt.Println("Failed to init config:", err)
		os.Exit(1)
	}
	tasker, err := maa.NewTasker()
	if err != nil {
		fmt.Println("Failed to create tasker")
		os.Exit(1)
	}
	defer tasker.Destroy()

	devices, err := maa.FindAdbDevices()
	if err != nil {
		fmt.Println("Failed to find adb devices:", err)
		os.Exit(1)
	}
	device := devices[0]
	ctrl, err := maa.NewAdbController(
		device.AdbPath,
		device.Address,
		device.ScreencapMethod,
		device.InputMethod,
		device.Config,
		"path/to/MaaAgentBinary",
	)
	if err != nil {
		fmt.Println("Failed to create ADB controller")
		os.Exit(1)
	}
	defer ctrl.Destroy()
	ctrl.PostConnect().Wait()
	tasker.BindController(ctrl)

	res, err := maa.NewResource()
	if err != nil {
		fmt.Println("Failed to create resource")
		os.Exit(1)
	}
	defer res.Destroy()
	res.PostBundle("./resource").Wait()
	tasker.BindResource(res)
	if !tasker.Initialized() {
		fmt.Println("Failed to init MAA.")
		os.Exit(1)
	}

	detail, err := tasker.PostTask("Startup").Wait().GetDetail()
	if err != nil {
		fmt.Println("Failed to get task detail:", err)
		os.Exit(1)
	}
	fmt.Println(detail)
}

📖 示例

更多示例请查看 examples 目录：

📚 文档

🤝 贡献

欢迎贡献！你可以：

  • 通过 Issue 报告 Bug
  • 提出功能建议或改进意见
  • 提交 Pull Request

📄 许可证

本项目采用 LGPL-3.0 许可证。

💬 社区