本地运行完整流程

这个仓库本身主要保存 MaaYYs 的资源、任务配置和 Go agent 源码。mxu.exe、maafw/、已编译的 agent.exe 由 Release 全量包或 CI 产物提供，通常不会作为源码提交。想在本地跑完整流程，推荐先准备一个可运行的全量包目录，再把源码仓库放进去开发。

推荐目录形态：

MaaYYs/
├── mxu.exe                 # Windows 图形界面入口，来自 Release 全量包
├── maafw/                  # MaaFramework 运行库，来自 Release 全量包
├── agent/
│   ├── agent.exe           # 本地编译出的 agent
│   └── *.go                # agent 源码
├── assets/
├── resource_pack/
├── tasks/
├── interface.json
└── README.md

如果你是从零开始：

1. 下载最新的 MaaYYs-win-x86_64-*-MXU.zip 并解压。
2. 用 git clone 的仓库内容覆盖或替换解压目录中的同名源码目录与文件。
3. 确认仓库根目录下存在 mxu.exe 和 maafw/。
4. 编译 agent。
5. 启动 mxu.exe，添加模拟器设备，选择资源和任务进行验证。

仓库主要结构：

.
├── agent/                 # Go agent，自定义 action / recognition
├── assets/                # 图标、答案表等通用资源
├── doc/                   # 使用文档与截图
├── resource_pack/         # MaaFramework pipeline、image、model 等资源包
├── tasks/                 # MXU / interface 导入的任务配置
├── interface.json         # Maa 项目入口、资源、agent、任务导入配置
└── .github/workflows/     # 构建、发布、Mirror 酱同步工作流

编译 agent

Windows：

cd agent
go mod download
go build -o agent.exe .

macOS / Linux：

cd agent
go mod download
go build -o agent .
chmod +x agent

interface.json 中配置了：

{
  "agent": {
    "child_exec": ".\\agent\\agent.exe",
    "child_args": []
  }
}

所以 Windows 本地调试时，编译出的 agent.exe 需要放在 agent/agent.exe。如果要在 macOS / Linux 本地调试，需要按对应平台调整 child_exec，或使用 CI 打出的对应平台包。

源文件保留 Windows 默认路径；CI 生成 macOS / Linux 包时只修改包内 interface.json 副本，将 child_exec 调整为 ./agent/agent。

启动完整 UI 调试

在仓库根目录确认以下文件存在：

Test-Path .\mxu.exe
Test-Path .\maafw\MaaFramework.dll
Test-Path .\agent\agent.exe

然后启动：

.\mxu.exe

启动后按这个顺序验证：

1. 添加设备，确保模拟器处于运行状态且 ADB 调试已开启。
2. 选择资源包，例如官服、B 站服或对应渠道服。
3. 选择一个影响范围小的任务先跑，例如 日常奖励领取、投喂宠物 或单步较短的测试任务。
4. 确认日志里没有 agent 启动失败、资源加载失败、pipeline 找不到节点等错误。
5. 再验证你实际修改的任务或素材。

修改资源后的验证方式

• 改 tasks/*.json：通常需要在 MXU 里重新加载资源，必要时重启 MXU。
• 改 resource_pack/*/pipeline/*.json：重新启动对应任务验证；如果界面仍使用旧配置，重启 MXU。
• 改 resource_pack/*/image/*：重新启动任务验证识别效果。
• 改 agent/**/*.go：必须重新 go build -o agent.exe .，并重启 MXU 或重新启动任务，让新的 agent 子进程生效。
• 改 interface.json：建议直接重启 MXU，确认资源、controller、agent 和 import 都能重新加载。

提交前检查

建议提交前至少跑一遍：

cd agent
go build -o agent.exe .
cd ..

再检查 JSON 是否能被解析：

powershell -NoProfile -Command "Get-Content -Raw interface.json | ConvertFrom-Json | Out-Null; Get-ChildItem tasks -Filter *.json | ForEach-Object { Get-Content -Raw $_.FullName | ConvertFrom-Json | Out-Null }; 'json ok'"

最后用 mxu.exe 跑一次受影响任务。CI 会帮你做多平台 agent 编译和打包，但本地实际跑通能更早发现素材、路径、任务选项和模拟器环境问题。

CI 与发布

本仓库的主工作流为 .github/workflows/build-release.yml：

• 分支 push 与 PR 会在相关文件变化时构建测试包。
• 推送形如 v1.2.3、v1.2.3-beta.1 的 tag 会触发正式发布。
• 发布时会把 interface.json 中的 version 更新为 tag。
• CI 会编译 Go agent，并下载固定版本 MaaFramework（v5.11.1）与 MXU。
• 打包内容包括 maafw/、mxu 或 mxu.exe、agent/、assets/、preset/、resource_pack/、tasks/、interface.json、LICENSE、README.md。
• Windows 产物发布为 .zip，Linux 产物发布为 .tar.gz；macOS 同时发布标准 .app.zip 与 .dmg。
• Release note 由 git-cliff 和 .github/cliff.toml 生成。
• Release 创建后会触发 Mirror 酱上传与 release note 同步。

开发者提交建议使用 Conventional Commits，例如：

feat: 添加新的活动任务
fix: 修复御魂目标识别
docs: 更新使用说明
ci: 调整发布流程

包含 [skip changelog] 的提交不会进入自动更新日志。