MaaAssistantArknights 的 GitHub Actions CI 体系解析从代码测试、全平台构建到 OTA 发版的完整自动化管线【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknightsMaaAssistantArknights以下简称 MAA借助 GitHub Actions 完成了大量自动化工作包括网站建置、资源自动更新、最终文件的编译与发布等环节且随着时间推移这些 CI 逐渐嵌套、部分甚至连接到了其他仓库如 MaaRelease、MaaResource。本文以仓库官方文档 CI 系统解析 为骨架结合.github/workflows目录下的真实工作流文件与tools目录中的配套脚本深入剖析每一条管线的触发条件、执行细节与上下游衔接关系帮助希望在 MAA 上改进或理解 CI 系统的开发者快速建立全局视图。总览工作流清单与分类所有工作流文件Workflow均存放于 .github/workflows 目录。按功能可归纳为以下九部分分类工作流文件职责程式碼測試smoke-testing.ymlMaaCore 基础检测资源加载、简单任务执行程式碼建置ci.yml全组件构建tag 触发时直接产出 Release版本發布release-nightly-ota.yml、release-ota.yml、release-preparation.yml、pr-auto-tag.yml内测版 / 正式版Beta发布与 OTA 增量更新資源更新res-update-game.yml、sync-resource.yml、optimize-templates.yml游戏资源拉取、资源仓库同步、模板图片优化網站建置website-workflow.yml文档站构建与 GitHub Pages 部署Issues 管理issue-checker.yml、issue-checkbox-checker.yml、stale.ymlIssue 打标、自动关闭、过期清理PR 管理pr-checker.yml检查 Commit Message 规范MirrorChyan 相關release-package-distribution.yml、mirrorchyan_release_note.yml更新镜像同步与 Release Note 生成其他markdown-checker.yml、blame-ignore.yml、cache-delete.yml、update-submodules.yml死链检查、Blame 历史清理、缓存清理、子模块更新除 GitHub Actions 外MAA 还通过 pre-commit.ci 实现了代码自动格式化与图片资源自动优化它在发起 PR 后会自动执行一般无需特别关注。从分支模型看各工作流普遍围绕两条主线分支运作dev-v2开发分支绝大多数 push 触发的流水线都以它为目标与master-v2发布分支仅接受标题为Release v...的 PR。版本 tagv*则是发布管线的最终入口。程式碼測試smoke-testing.ymlsmoke-testing.yml 负责对 MaaCore 进行基础检测包括资源文件加载、部分简单任务Task执行等。由于测试案例Test Cases已较久未更新该工作流目前的初衷是确保资源文件不会出错以及 MaaCore 的代码没有出现影响构建的致命性错误。从源码配置看它的执行细节包括触发条件dev-v2分支或 PR 触碰src/MaaCore/**、resource/**、cmake/**、CMakeLists.txt、include/**、3rdparty/include/**、tools/SmokeTesting/**、tools/maadeps-download.py 等路径时运行执行环境macos-latestRunner使用 CMake 的smoke-testpreset 构建并安装 MaaCore缓存策略以 MaaCore 源码、CMake 配置与依赖下载脚本的文件哈希hashFiles(...)生成缓存 key缓存整个install目录下的libMaaCore.dylib、libonnxruntime*.dylib、smoke_test等产物命中缓存时可跳过依赖拉取与编译显著降低 20 分钟级资源更新带来的连带测试成本测试执行最终运行 tools/SmokeTesting/run_tests.sh。该脚本对Official、YoStarJP、YoStarEN、YoStarKR、txwy五套客户端资源并行执行smoke_test逐个客户端记录日志到install/debug若有失败则将对应日志以彩色[ERR]/[INF]前缀打印并返回非零退出码日志留存无论成功失败都会通过actions/upload-artifact上传./install/debug目录下的日志便于回溯。这一设计体现了“低成本高频验证”的思路测试本身不追求覆盖所有任务逻辑而是守护“资源文件 核心库能正常加载运行”这条底线。程式碼建置ci.ymlci.yml内部名称为 “Release Pipeline”负责对代码进行全量构建包含 MAA 的所有组件构建产物即可执行的 MAAWindows 产物包含 MaaWpfGuimacOS 产物包含 MaaMacGuiLinux 产物包含 maa-cli此外还会构建 Android 版 MaaCore。该工作流在dev-v2分支出现触碰源码或构建脚本的新提交以及 PR 时自动执行当工作流由版本 tag 触发时tag 由发版 PR 合并后pr-auto-tag.yml建立本次构建产物将直接用于发布并自动创建一个 Release。meta Job版本号解析、预发布判定与 Changelog 收尾metaJob 是所有构建 Job 的前置needs: meta承担三项职责tag 确定若为refs/tags/v*的推送则直接取 tag 名否则用git describe --tags --match v* HEAD回退找不到时回落到v0.0.1-short-sha保证任何提交都有可用的构建版本号作为-DMAA_HASH_VERSION传给 CMake预发布判定用正则^v[0-9]\.[0-9]\.[0-9]$判断 tag 是否为正式vX.Y.Z否则视为 prerelease例如带-alpha.1.dNNN后缀的内测版该标志最终决定 GitHub Release 是否标记为预发布Changelog 收尾tag 触发时向CHANGELOG.md末尾追加**Full Changelog**: [last_tag - this_tag]的对比链接正式版还会排除带连字符的历史 tag并追加 Mirror 酱 CDN 下载入口随后上传为changelog工件供releaseJob 使用。并发控制工作流顶部定义了concurrency组PR 场景下以“源仓库 分支名”为组、dev-v2直接推送场景下额外拼接 commit SHA并设置cancel-in-progress: true。这意味着开发分支上连续提交会取消旧的构建PR 上则保留同一分支最近一次构建避免 Runner 被排队任务占满。Windows 构建 Jobarm64 / x64 矩阵Windows Job 运行在windows-2025-vs2026Runner 上按arm64与x64两个架构矩阵构建主要步骤链路为通过 .github/scripts/sync-optional-submodules.sh 按需初始化src/MaaUtils、3rdparty/EmulatorExtras子模块以 tools/maadeps-download.py 的哈希为 key 缓存src/MaaUtils/MaaDeps未命中时运行python3 tools/maadeps-download.py {arch}-windows拉取 OpenCV、ONNXRuntime、PPOCR 等二进制依赖使用 CMakePresets.json 中定义的windows-publish-x64/windows-publish-arm64preset 执行 configure、build、install并额外构建MAA.Updater目标通过robinraju/release-downloader从 MaaFramework 仓库下载对应架构的控制单元Windows 端固定了v5.9.2tag把*Win32ControlUnit*、*AdbControlUnit*拷入install/生成global.json锁定 .NET SDK10.0.302rollForward: disable缓存.nuke/temp与 NuGet 包后执行dotnet publish src/MaaWpfGui/MaaWpfGui.csproj并以脚本改写 csproj 中的Version/AssemblyVersion等字段注入 tag 版本将 PDB 符号文件单独压缩为MAAComponent-DebugSymbol-*工件上传用原生启动器MaaAppHostStub.exe替换 SDK 生成的MAA.exeapphost——从脚本注释可见这是为了让 MAA.exe 被单独拖出文件夹时给出明确错误提示运行 tools/GenerateFileList.ps1 生成文件清单后打包为MAA-tag-win-arch.zip上传。Linux 构建 Jobmaa-cli 与 AppImageUbuntu Job 以x86_64/aarch64矩阵运行在标准 CMake 构建 MaaCore 之外还完成了两件 Linux 特有的事通过src/maa-cli子仓库的自定义 setup action 配置 Rust 交叉编译工具链编译maa-cli--features git2/vendored-openssl产出无图形依赖的独立二进制组装 AppImage将 MaaCore 运行时、maaCLI、图标、metainfo 文件 与.desktop条目打包进Maa.AppDir再用 appimagetool 连同runtime-fuse3-arch构建出MAA-tag-linux-arch.AppImage同时保留tar.gz分发包。macOS 构建Core 与 GUI 两阶段macOS-CoreJob 按arm64/x86_64矩阵分别构建 dylib 并下载 MaaFramework 的 AdbControlUnitmacOS-GUIJobneeds: macOS-Core则用lipo -create将双架构 dylib 合并为 universal 二进制并将libonnxruntime、libopencv_world4等以符号链接归一打包出MAA-tag-macos-runtime-universal.zip运行时包用xcodebuild -create-xcframework生成 MaaCore、MaaUtils、PPOCR、ONNXRuntime、OpenCV 的 XCFramework写Version.xcconfigMARKETING_VERSION取 tag、CURRENT_PROJECT_VERSION取 Release 序号xcodebuild archive构建src/MaaMacGui子模块仅在 tag 触发时执行签名与公证链路导入 Developer ID 证书、下载 Provisioning Profile、create-dmg生成 dmg、notarytool submit公证并stapler staple附票、归档 dSYM 符号最终产出MAA-tag-macos-universal.dmg与调试符号包。值得注意的是 tag 触发才安装graphicsmagick、执行公证等步骤普通提交只做构建验证避免了密钥与公证成本消耗在 CI 提交上。MAAUnifiedAvaloniaJob从ci.yml结构看还有一个avaloniaJobneedsWindows、Ubuntu、macOS-Core 三路构建完成后在win-x64、linux-x64、macos-x64上以 .NET 10 self-contained 发布src/MAAUnified并下载对应平台的 MaaCore 运行时合并入发布目录Linux 一侧还承担“基线一致性/覆盖率/渲染同步”等测试门槛dotnet test过滤Baseline*Tests、ParityMatrixSyncTestsWindows 一侧则运行平台能力契约与原生能力冒烟测试。可以推断这是 MAA 新一代跨平台 GUI 的构建与回归防线。release Job自动创建 Release 并串接下游releaseJob 仅在refs/tags/v*时执行needs了全部平台构建 Job 与 meta下载全部工件并展平清理MAACore-*、MAARuntime-*等中间产物用softprops/action-gh-release以CHANGELOG.md为 body 发布 Releaseprerelease标志来自 meta 的判定用gh workflow run依次触发三个下游工作流release-package-distribution.yml传入release_tag、mirrorchyantrue正式版额外开启wingetmirrorchyan_release_note.ymlrelease-ota.yml使用专用的MISTEOWORKFLOW跨仓库触发令牌。这一步是“构建 → 发布 → 分发 → 增量更新”管线的枢纽。版本發布Nightly、Beta 与 OTA 机制版本发布简称发版是向用户发布更新的必要操作由以下工作流组成release-nightly-ota.yml发布内测版Nightlyrelease-ota.yml发布正式版 / 公测版Betarelease-preparation.yml为正式版 / 公测版产生 Changelog 并准备发布pr-auto-tag.yml对正式版 / 公测版产生 Tag。文件名中的OTA意为 Over-the-Air云端更新也就是常说的“增量更新文件”因此 MAA 的发版过程实际上包含了对过往版本构建 OTA 文件的步骤。内测版Nightlyrelease-nightly-ota.yml 的schedule为cron: 0 22 * * *即每天 UTC 22 点自动执行以保证内测版的更新频率当然也可以在做出更改需要验证时通过workflow_dispatch手动触发支持指定ref、release_body与回看 release 数量。需要注意的是内测版发布仅针对 Windows 用户macOS 与 Linux 用户目前无法接收到内测更新。从 Job 结构看流程为build-win-nightly → push-tag → make-ota变更检测git describe --tags --abbrev0取最近 tag再用git log tag..HEAD --oneline检查是否有新提交若无变更则通过 API 取消当前 run避免无意义构建内测版本号基于git describe --long推导形如vX.Y.Z-alpha.1.dNNN.distance的 tag若当前已是预发布则继续pre_version.dNNN.distanceChangelog调用 tools/ChangelogGenerator/changelog_generator.py 生成从最近 tag 到当前提交的变更清单构建与推送构建步骤与ci.yml的 Windows Job 一致MaaDeps 缓存、CMake preset、WPF 发布、AppHostStub 替换、文件清单随后以alpha/tag形式把 tag 推回主仓库MaaRelease 打 tagpush-tagJob 在 MaaRelease 仓库上以--orphan __temp分支建立空提交并推 tag作为 OTA 产物的挂载点OTA 构建make-otaJob 列出主仓库最近 release 与 MaaRelease 已有 tag 的交集作为“历史版本清单”下载对应历史全量包后运行 tools/OTAPacker/build.sh为每个历史版本生成MAAComponent-OTA-旧tag_新tag-win-x64.zip增量包并上传到 MaaReleaseprerelease: true最后触发 MaaRelease 的镜像同步与mirrorchyan_alpha.yml相关流程。正式版 / 公测版Beta这两个版本的发布流程相对复杂可以透过模拟一次发布步骤来解释各工作流的作用建立从dev-v2到master-v2分支的 PR且该 PR 的标题需为Release v******release-preparation.yml 识别到此类 PR 后按 .github/release_reviewers.yaml 分配审查者并触发update-submodules.yml确保子模块处于最新状态仓库中还保留了一段已注释停用的 AI 自动生成 Changelog 的 Job 配置说明该环节正以人工撰写为主对 Changelog 进行手动调整并加入简要描述合并 PR触发 pr-auto-tag.yml它从 PR 标题中剥离Release前缀得到 tag 名如v4.34.21git tag -a -f创建并推送 tag随后把该 tag 反向 merge 回dev-v2保证开发分支不落后于发布点tag 推送触发ci.yml完成全平台构建并发布 GitHub Release见上文Release 的published事件进一步触发 release-ota.yml。release-ota.yml内部为create-tag → make-ota / make-ota-mac → release结构create-tag在 MaaRelease 仓库中比对主仓库最近 release默认 31 个与 MaaRelease 已有 tag默认 30 个的差集生成待处理版本清单并逐一打 tagmake-otaWindows x64沿用 tools/OTAPacker/build.sh 生成各历史版本到当前版本的全套 OTA 增量包make-ota-macmacOS则走 Sparkle 路线下载历史MAA-*-macos-universal.dmg与 release note HTML用 Sparkle 的generate_appcast预发布版走--channel beta生成签名 appcast 与 delta 增量清理无关文件后上传releaseJob 最后触发 MaaRelease 的release-mirrors.yml同步各镜像并通过discord-release-notification.yml发送通知。OTAPackerOTA 增量包的工具层tools/OTAPacker 目录下的脚本构成了增量更新的工具底座build.sh接收“源仓库、版本清单、架构、回退仓库”四个参数逐版本下载全量 zip最新版本保留全量、旧版本通过 zipota.sh配合 ziplist.sh、makeota.sh基于文件清单差异生成 OTA 包若某历史版本缺少对应架构产物则告警跳过。这与ci.yml中 Windows 产物额外生成文件清单GenerateFileList.ps1的做法相呼应——文件清单正是 OTA 做差量比对的前提。資源更新游戏数据的自动跟进资源更新部分负责 MAA 的模板与数据随游戏版本演进核心是三个工作流的分工。res-update-game.yml高频拉取上游游戏资源res-update-game.yml 的schedule为*/20 * * * *即每 20 分钟执行一次且仅在MaaAssistantArknights主仓库运行。其 Job 拓扑为三路并行克隆上游数据均通过 sparse-checkout 只取所需 excel/json国服yuanyan3060/ArknightsGameResourcelevels.json、item、building_skill及 gamedata 下的物品/建筑/范围/干员/卡池/集成战略/活动表海外服EN/JP/KRArknightsAssets/ArknightsGamedata的对应语言 excel繁中服arkntools/arknights-data-tw-for-maa并额外并发拉取 Penguin Stats API 的 CN/US/JP/KR 四区stages.json任一失败即整体失败。构建 ResourceUpdater在macos-latest上用 CMake 构建 tools/ResourceUpdater 的res_updater其编译产物与 dylib 按tools/ResourceUpdater/main.cpp哈希做缓存执行更新把三路数据落到tools/ResourceUpdater下的Official/Overseas/tw目录结构后运行./tools/ResourceUpdater/res_updater将上游数据转写为本仓库resource/下的模板与 JSON规范化与提交运行 tools/TaskSorter/TaskSorter.py 重排任务 JSON对变更的.json执行 prettier 格式化tools/ResourceUpdater/version.sh 判断version.json是否变化若包含 PNG 更新则安装 oxipng 并用 tools/OptimizeTemplates/optimize_templates.py 压缩resource/template/items/、resource/template/infrast/下的图片有变更时以chore: Auto Update Game Resources - 日期为消息、附带[skip changelog]标记提交并推送无变更则自我取消。失败时dev-v2 分支上会把 run 链接维护在一个固定的“失败追踪” Issue 评论里新失败置顶、旧失败折叠成功/取消后将其最小化。sync-resource.yml把资源同步到 MaaResource 仓库sync-resource.yml 在dev-v2分支的resource/**发生变更时触发克隆MaaAssistantArknights/MaaResource通过 SSH 部署密钥MAA_RESOURCE_DEPLOY清空其resource/后整体拷贝本仓库的resource/沿用触发提交的标题作为 commit message 提交并推送。也就是说MaaResource 仓库始终是主仓库资源目录的一个镜像副本供客户端资源更新使用。optimize-templates.yml图片资源自动优化optimize-templates.yml 在dev-v2分支推送触碰resource/**/*.png或docs/.vuepress/public/images/**时触发职责是压缩优化模板图片体积。其防循环设计值得注意提交作者是github-actions[bot]时直接跳过避免优化工作流自己触发的提交再次触发通过 API 查询该提交是否属于某 PR 的合并提交是 PR 合并则跳过仅处理直接推送优化后若无差异不提交有差异则以chore: Auto Templates Optimization提交并推送。三者组合形成了“上游游戏数据高频拉取 → 本仓库资源目录更新 → 镜像到资源仓库 → 图片体积治理”的闭环。網站建置website-workflow.ymlwebsite-workflow.yml 负责 MAA 文档站的构建与发布触发条件为master-v2/dev-v2分支或 PR 触碰docs/**以及工作流自身文件。构建链路为pnpm setup锁定 docs/pnpm-lock.yaml→pnpm install --frozen-lockfile→pnpm run build基于 docs/package.json 的 VuePress 站点产物位于docs/.vuepress/dist并上传为工件。网站发布与版本更新强烈绑定部署到 GitHub Pagespeaceiris/actions-gh-pages发布gh-pages分支仅在两种情况下发生——推送来自master-v2或手动 dispatch 时勾选deploy-to-prod。平时修改网页组件时仅执行构建以验证无误。concurrency: pages且cancel-in-progress: false保证部署串行排队、不互相取消。Issues 管理issue-checker.yml在 Issue/PR 的opened、edited以及issue_comment的created、edited事件上运行团队自维护的MaaAssistantArknights/issue-checkerv1.14action以正则比对为各个 Issue 标记 Tag规则配置在 .github/issue-checker.yml以此分类 Issue 内容方便查看与管理。issue-checkbox-checker.yml透过正则表达式自动关闭未勾选“我未仔细读”模板选项的 Issue若该项未勾选则将所有勾选框Checkbox折叠。stale.yml检查超过 90 天没有活动的 Issue不含 Pull Request豁免keep-open、MAA Team、enhancement标签的 Issue将其标记并发起通知7 天后若还没有活动则关闭。Pull Requests 管理pr-checker.ymlpr-checker.yml 在 PR 的opened、edited、ready_for_review、reopened、synchronize事件上运行master-v2作为 base 时豁免用github-script列举 PR 全部提交并执行两条规则约定式提交Commit Message 首行必须匹配正则^((build|chore|ci|docs?|feat!?|fix|perf|refactor|rft|style|test|i18n|typo|debug)[\:\.\(\,]|[Rr]evert|[Rr]elease|[Rr]eapply)即 type 限定为build/chore/ci/docs/feat(!)/fix/perf/refactor/rft/style/test/i18n/typo/debug或Revert、Release、Reapply开头禁止 Merge Commitcommit.parents.length 1的提交一律不合规要求 rebase 流程。存在不合规提交时Bot 会在 PR 中发布并按内容去重更新一份列出“不合规提交名”与“Merge Commit”的评论同时core.setFailed使该检查失败全部合规时则会删除先前遗留的提示评论。MirrorChyan 相關MirrorChyan 是有偿的更新镜像服务相关工作流如下release-package-distribution.yml同步更新文件至 MirrorChyan。它由ci.yml的 release Job 在 GitHub Release 建立后通过gh workflow run触发输入参数包括release_tag、mirrorchyantrue以及正式版专属的winget标志mirrorchyan_release_note.yml产生 MirrorChyan 的 Release Note。Nightly 流程中同样会触发 MaaRelease 仓库的mirrorchyan_alpha.yml及其 Release Note 工作流说明镜像分发被统一收敛在发布管线的末端。其他工作流markdown-checker.yml检查仓库中所有 Markdown 文件是否包含无效链接死链接对文档量庞大的本仓库是必要的守护。blame-ignore.yml自动忽略 Commit Message 包含blame ignore的提交配合仓库根目录的pr_cache_remover.ps1等辅助脚本以保持 Git Blame 历史记录简洁——例如大规模格式化提交不应污染行级归属。cache-delete.yml在 PR 合并后清理相关 Actions 缓存以节省 GitHub 存储空间。update-submodules.yml定期将 MaaMacGui、maa-cli以及 MAAUnified等子模块更新至最新版本。其schedule为50 21 * * *每天 UTC 21:50 自动执行——刻意早于每日内测版发布的 22:00确保子模块保持在最新状态。执行方式是调用 sync-optional-submodules.sh 的--remote模式抓取远端最新提交然后以feat: Update Submodules MAAUnified, MaaMacGui, maa-cli提交推送同样带[skip changelog]。小结一条提交如何走完 MAA 的 CI 全链路把前述工作流串起来可以还原出一条完整的自动化链路开发者向dev-v2发 PRpr-checker校验提交规范smoke-testing验证 MaaCore 与资源加载ci.yml做多平台全量构建resource/**的变更会被sync-resource.yml镜像进 MaaResource 仓库图片变更由optimize-templates.yml治理每 20 分钟的res-update-game.yml则持续跟进游戏上游数据发版时标题为Release v...的dev-v2 → master-v2PR 由release-preparation.yml指派审查并触发子模块更新合并后pr-auto-tag.yml打 tag 并回灌dev-v2tag 推送触发ci.yml完成全平台构建、自动创建 Release并级联触发release-package-distribution.yml、mirrorchyan_release_note.yml与release-ota.ymlrelease-ota.yml面向历史版本批量生成 OTA 增量包Windows zip 差量、macOS Sparkle delta上传 MaaRelease 并同步各镜像与 Discord 通知。理解这套管线的关键在于把握三个枢纽ci.yml的 meta/release Job版本语义与发布动作的收口、pr-auto-tag.ymlPR 标题驱动 tag 的极简发版协议、以及 MaaRelease/MaaResource 两个伴生仓库OTA 与资源更新的事实承载体。对希望改进 MAA CI 的开发者而言本文引用的 .github/workflows、tools/OTAPacker、tools/SmokeTesting 与 .github/scripts 即是可直接着手分析的最小文件集合。【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MaaAssistantArknights 的 GitHub Actions CI 体系解析：从代码测试、全平台构建到 OTA 发版的完整自动化管线
MaaAssistantArknights 的 GitHub Actions CI 体系解析从代码测试、全平台构建到 OTA 发版的完整自动化管线【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknightsMaaAssistantArknights以下简称 MAA借助 GitHub Actions 完成了大量自动化工作包括网站建置、资源自动更新、最终文件的编译与发布等环节且随着时间推移这些 CI 逐渐嵌套、部分甚至连接到了其他仓库如 MaaRelease、MaaResource。本文以仓库官方文档 CI 系统解析 为骨架结合.github/workflows目录下的真实工作流文件与tools目录中的配套脚本深入剖析每一条管线的触发条件、执行细节与上下游衔接关系帮助希望在 MAA 上改进或理解 CI 系统的开发者快速建立全局视图。总览工作流清单与分类所有工作流文件Workflow均存放于 .github/workflows 目录。按功能可归纳为以下九部分分类工作流文件职责程式碼測試smoke-testing.ymlMaaCore 基础检测资源加载、简单任务执行程式碼建置ci.yml全组件构建tag 触发时直接产出 Release版本發布release-nightly-ota.yml、release-ota.yml、release-preparation.yml、pr-auto-tag.yml内测版 / 正式版Beta发布与 OTA 增量更新資源更新res-update-game.yml、sync-resource.yml、optimize-templates.yml游戏资源拉取、资源仓库同步、模板图片优化網站建置website-workflow.yml文档站构建与 GitHub Pages 部署Issues 管理issue-checker.yml、issue-checkbox-checker.yml、stale.ymlIssue 打标、自动关闭、过期清理PR 管理pr-checker.yml检查 Commit Message 规范MirrorChyan 相關release-package-distribution.yml、mirrorchyan_release_note.yml更新镜像同步与 Release Note 生成其他markdown-checker.yml、blame-ignore.yml、cache-delete.yml、update-submodules.yml死链检查、Blame 历史清理、缓存清理、子模块更新除 GitHub Actions 外MAA 还通过 pre-commit.ci 实现了代码自动格式化与图片资源自动优化它在发起 PR 后会自动执行一般无需特别关注。从分支模型看各工作流普遍围绕两条主线分支运作dev-v2开发分支绝大多数 push 触发的流水线都以它为目标与master-v2发布分支仅接受标题为Release v...的 PR。版本 tagv*则是发布管线的最终入口。程式碼測試smoke-testing.ymlsmoke-testing.yml 负责对 MaaCore 进行基础检测包括资源文件加载、部分简单任务Task执行等。由于测试案例Test Cases已较久未更新该工作流目前的初衷是确保资源文件不会出错以及 MaaCore 的代码没有出现影响构建的致命性错误。从源码配置看它的执行细节包括触发条件dev-v2分支或 PR 触碰src/MaaCore/**、resource/**、cmake/**、CMakeLists.txt、include/**、3rdparty/include/**、tools/SmokeTesting/**、tools/maadeps-download.py 等路径时运行执行环境macos-latestRunner使用 CMake 的smoke-testpreset 构建并安装 MaaCore缓存策略以 MaaCore 源码、CMake 配置与依赖下载脚本的文件哈希hashFiles(...)生成缓存 key缓存整个install目录下的libMaaCore.dylib、libonnxruntime*.dylib、smoke_test等产物命中缓存时可跳过依赖拉取与编译显著降低 20 分钟级资源更新带来的连带测试成本测试执行最终运行 tools/SmokeTesting/run_tests.sh。该脚本对Official、YoStarJP、YoStarEN、YoStarKR、txwy五套客户端资源并行执行smoke_test逐个客户端记录日志到install/debug若有失败则将对应日志以彩色[ERR]/[INF]前缀打印并返回非零退出码日志留存无论成功失败都会通过actions/upload-artifact上传./install/debug目录下的日志便于回溯。这一设计体现了“低成本高频验证”的思路测试本身不追求覆盖所有任务逻辑而是守护“资源文件 核心库能正常加载运行”这条底线。程式碼建置ci.ymlci.yml内部名称为 “Release Pipeline”负责对代码进行全量构建包含 MAA 的所有组件构建产物即可执行的 MAAWindows 产物包含 MaaWpfGuimacOS 产物包含 MaaMacGuiLinux 产物包含 maa-cli此外还会构建 Android 版 MaaCore。该工作流在dev-v2分支出现触碰源码或构建脚本的新提交以及 PR 时自动执行当工作流由版本 tag 触发时tag 由发版 PR 合并后pr-auto-tag.yml建立本次构建产物将直接用于发布并自动创建一个 Release。meta Job版本号解析、预发布判定与 Changelog 收尾metaJob 是所有构建 Job 的前置needs: meta承担三项职责tag 确定若为refs/tags/v*的推送则直接取 tag 名否则用git describe --tags --match v* HEAD回退找不到时回落到v0.0.1-short-sha保证任何提交都有可用的构建版本号作为-DMAA_HASH_VERSION传给 CMake预发布判定用正则^v[0-9]\.[0-9]\.[0-9]$判断 tag 是否为正式vX.Y.Z否则视为 prerelease例如带-alpha.1.dNNN后缀的内测版该标志最终决定 GitHub Release 是否标记为预发布Changelog 收尾tag 触发时向CHANGELOG.md末尾追加**Full Changelog**: [last_tag - this_tag]的对比链接正式版还会排除带连字符的历史 tag并追加 Mirror 酱 CDN 下载入口随后上传为changelog工件供releaseJob 使用。并发控制工作流顶部定义了concurrency组PR 场景下以“源仓库 分支名”为组、dev-v2直接推送场景下额外拼接 commit SHA并设置cancel-in-progress: true。这意味着开发分支上连续提交会取消旧的构建PR 上则保留同一分支最近一次构建避免 Runner 被排队任务占满。Windows 构建 Jobarm64 / x64 矩阵Windows Job 运行在windows-2025-vs2026Runner 上按arm64与x64两个架构矩阵构建主要步骤链路为通过 .github/scripts/sync-optional-submodules.sh 按需初始化src/MaaUtils、3rdparty/EmulatorExtras子模块以 tools/maadeps-download.py 的哈希为 key 缓存src/MaaUtils/MaaDeps未命中时运行python3 tools/maadeps-download.py {arch}-windows拉取 OpenCV、ONNXRuntime、PPOCR 等二进制依赖使用 CMakePresets.json 中定义的windows-publish-x64/windows-publish-arm64preset 执行 configure、build、install并额外构建MAA.Updater目标通过robinraju/release-downloader从 MaaFramework 仓库下载对应架构的控制单元Windows 端固定了v5.9.2tag把*Win32ControlUnit*、*AdbControlUnit*拷入install/生成global.json锁定 .NET SDK10.0.302rollForward: disable缓存.nuke/temp与 NuGet 包后执行dotnet publish src/MaaWpfGui/MaaWpfGui.csproj并以脚本改写 csproj 中的Version/AssemblyVersion等字段注入 tag 版本将 PDB 符号文件单独压缩为MAAComponent-DebugSymbol-*工件上传用原生启动器MaaAppHostStub.exe替换 SDK 生成的MAA.exeapphost——从脚本注释可见这是为了让 MAA.exe 被单独拖出文件夹时给出明确错误提示运行 tools/GenerateFileList.ps1 生成文件清单后打包为MAA-tag-win-arch.zip上传。Linux 构建 Jobmaa-cli 与 AppImageUbuntu Job 以x86_64/aarch64矩阵运行在标准 CMake 构建 MaaCore 之外还完成了两件 Linux 特有的事通过src/maa-cli子仓库的自定义 setup action 配置 Rust 交叉编译工具链编译maa-cli--features git2/vendored-openssl产出无图形依赖的独立二进制组装 AppImage将 MaaCore 运行时、maaCLI、图标、metainfo 文件 与.desktop条目打包进Maa.AppDir再用 appimagetool 连同runtime-fuse3-arch构建出MAA-tag-linux-arch.AppImage同时保留tar.gz分发包。macOS 构建Core 与 GUI 两阶段macOS-CoreJob 按arm64/x86_64矩阵分别构建 dylib 并下载 MaaFramework 的 AdbControlUnitmacOS-GUIJobneeds: macOS-Core则用lipo -create将双架构 dylib 合并为 universal 二进制并将libonnxruntime、libopencv_world4等以符号链接归一打包出MAA-tag-macos-runtime-universal.zip运行时包用xcodebuild -create-xcframework生成 MaaCore、MaaUtils、PPOCR、ONNXRuntime、OpenCV 的 XCFramework写Version.xcconfigMARKETING_VERSION取 tag、CURRENT_PROJECT_VERSION取 Release 序号xcodebuild archive构建src/MaaMacGui子模块仅在 tag 触发时执行签名与公证链路导入 Developer ID 证书、下载 Provisioning Profile、create-dmg生成 dmg、notarytool submit公证并stapler staple附票、归档 dSYM 符号最终产出MAA-tag-macos-universal.dmg与调试符号包。值得注意的是 tag 触发才安装graphicsmagick、执行公证等步骤普通提交只做构建验证避免了密钥与公证成本消耗在 CI 提交上。MAAUnifiedAvaloniaJob从ci.yml结构看还有一个avaloniaJobneedsWindows、Ubuntu、macOS-Core 三路构建完成后在win-x64、linux-x64、macos-x64上以 .NET 10 self-contained 发布src/MAAUnified并下载对应平台的 MaaCore 运行时合并入发布目录Linux 一侧还承担“基线一致性/覆盖率/渲染同步”等测试门槛dotnet test过滤Baseline*Tests、ParityMatrixSyncTestsWindows 一侧则运行平台能力契约与原生能力冒烟测试。可以推断这是 MAA 新一代跨平台 GUI 的构建与回归防线。release Job自动创建 Release 并串接下游releaseJob 仅在refs/tags/v*时执行needs了全部平台构建 Job 与 meta下载全部工件并展平清理MAACore-*、MAARuntime-*等中间产物用softprops/action-gh-release以CHANGELOG.md为 body 发布 Releaseprerelease标志来自 meta 的判定用gh workflow run依次触发三个下游工作流release-package-distribution.yml传入release_tag、mirrorchyantrue正式版额外开启wingetmirrorchyan_release_note.ymlrelease-ota.yml使用专用的MISTEOWORKFLOW跨仓库触发令牌。这一步是“构建 → 发布 → 分发 → 增量更新”管线的枢纽。版本發布Nightly、Beta 与 OTA 机制版本发布简称发版是向用户发布更新的必要操作由以下工作流组成release-nightly-ota.yml发布内测版Nightlyrelease-ota.yml发布正式版 / 公测版Betarelease-preparation.yml为正式版 / 公测版产生 Changelog 并准备发布pr-auto-tag.yml对正式版 / 公测版产生 Tag。文件名中的OTA意为 Over-the-Air云端更新也就是常说的“增量更新文件”因此 MAA 的发版过程实际上包含了对过往版本构建 OTA 文件的步骤。内测版Nightlyrelease-nightly-ota.yml 的schedule为cron: 0 22 * * *即每天 UTC 22 点自动执行以保证内测版的更新频率当然也可以在做出更改需要验证时通过workflow_dispatch手动触发支持指定ref、release_body与回看 release 数量。需要注意的是内测版发布仅针对 Windows 用户macOS 与 Linux 用户目前无法接收到内测更新。从 Job 结构看流程为build-win-nightly → push-tag → make-ota变更检测git describe --tags --abbrev0取最近 tag再用git log tag..HEAD --oneline检查是否有新提交若无变更则通过 API 取消当前 run避免无意义构建内测版本号基于git describe --long推导形如vX.Y.Z-alpha.1.dNNN.distance的 tag若当前已是预发布则继续pre_version.dNNN.distanceChangelog调用 tools/ChangelogGenerator/changelog_generator.py 生成从最近 tag 到当前提交的变更清单构建与推送构建步骤与ci.yml的 Windows Job 一致MaaDeps 缓存、CMake preset、WPF 发布、AppHostStub 替换、文件清单随后以alpha/tag形式把 tag 推回主仓库MaaRelease 打 tagpush-tagJob 在 MaaRelease 仓库上以--orphan __temp分支建立空提交并推 tag作为 OTA 产物的挂载点OTA 构建make-otaJob 列出主仓库最近 release 与 MaaRelease 已有 tag 的交集作为“历史版本清单”下载对应历史全量包后运行 tools/OTAPacker/build.sh为每个历史版本生成MAAComponent-OTA-旧tag_新tag-win-x64.zip增量包并上传到 MaaReleaseprerelease: true最后触发 MaaRelease 的镜像同步与mirrorchyan_alpha.yml相关流程。正式版 / 公测版Beta这两个版本的发布流程相对复杂可以透过模拟一次发布步骤来解释各工作流的作用建立从dev-v2到master-v2分支的 PR且该 PR 的标题需为Release v******release-preparation.yml 识别到此类 PR 后按 .github/release_reviewers.yaml 分配审查者并触发update-submodules.yml确保子模块处于最新状态仓库中还保留了一段已注释停用的 AI 自动生成 Changelog 的 Job 配置说明该环节正以人工撰写为主对 Changelog 进行手动调整并加入简要描述合并 PR触发 pr-auto-tag.yml它从 PR 标题中剥离Release前缀得到 tag 名如v4.34.21git tag -a -f创建并推送 tag随后把该 tag 反向 merge 回dev-v2保证开发分支不落后于发布点tag 推送触发ci.yml完成全平台构建并发布 GitHub Release见上文Release 的published事件进一步触发 release-ota.yml。release-ota.yml内部为create-tag → make-ota / make-ota-mac → release结构create-tag在 MaaRelease 仓库中比对主仓库最近 release默认 31 个与 MaaRelease 已有 tag默认 30 个的差集生成待处理版本清单并逐一打 tagmake-otaWindows x64沿用 tools/OTAPacker/build.sh 生成各历史版本到当前版本的全套 OTA 增量包make-ota-macmacOS则走 Sparkle 路线下载历史MAA-*-macos-universal.dmg与 release note HTML用 Sparkle 的generate_appcast预发布版走--channel beta生成签名 appcast 与 delta 增量清理无关文件后上传releaseJob 最后触发 MaaRelease 的release-mirrors.yml同步各镜像并通过discord-release-notification.yml发送通知。OTAPackerOTA 增量包的工具层tools/OTAPacker 目录下的脚本构成了增量更新的工具底座build.sh接收“源仓库、版本清单、架构、回退仓库”四个参数逐版本下载全量 zip最新版本保留全量、旧版本通过 zipota.sh配合 ziplist.sh、makeota.sh基于文件清单差异生成 OTA 包若某历史版本缺少对应架构产物则告警跳过。这与ci.yml中 Windows 产物额外生成文件清单GenerateFileList.ps1的做法相呼应——文件清单正是 OTA 做差量比对的前提。資源更新游戏数据的自动跟进资源更新部分负责 MAA 的模板与数据随游戏版本演进核心是三个工作流的分工。res-update-game.yml高频拉取上游游戏资源res-update-game.yml 的schedule为*/20 * * * *即每 20 分钟执行一次且仅在MaaAssistantArknights主仓库运行。其 Job 拓扑为三路并行克隆上游数据均通过 sparse-checkout 只取所需 excel/json国服yuanyan3060/ArknightsGameResourcelevels.json、item、building_skill及 gamedata 下的物品/建筑/范围/干员/卡池/集成战略/活动表海外服EN/JP/KRArknightsAssets/ArknightsGamedata的对应语言 excel繁中服arkntools/arknights-data-tw-for-maa并额外并发拉取 Penguin Stats API 的 CN/US/JP/KR 四区stages.json任一失败即整体失败。构建 ResourceUpdater在macos-latest上用 CMake 构建 tools/ResourceUpdater 的res_updater其编译产物与 dylib 按tools/ResourceUpdater/main.cpp哈希做缓存执行更新把三路数据落到tools/ResourceUpdater下的Official/Overseas/tw目录结构后运行./tools/ResourceUpdater/res_updater将上游数据转写为本仓库resource/下的模板与 JSON规范化与提交运行 tools/TaskSorter/TaskSorter.py 重排任务 JSON对变更的.json执行 prettier 格式化tools/ResourceUpdater/version.sh 判断version.json是否变化若包含 PNG 更新则安装 oxipng 并用 tools/OptimizeTemplates/optimize_templates.py 压缩resource/template/items/、resource/template/infrast/下的图片有变更时以chore: Auto Update Game Resources - 日期为消息、附带[skip changelog]标记提交并推送无变更则自我取消。失败时dev-v2 分支上会把 run 链接维护在一个固定的“失败追踪” Issue 评论里新失败置顶、旧失败折叠成功/取消后将其最小化。sync-resource.yml把资源同步到 MaaResource 仓库sync-resource.yml 在dev-v2分支的resource/**发生变更时触发克隆MaaAssistantArknights/MaaResource通过 SSH 部署密钥MAA_RESOURCE_DEPLOY清空其resource/后整体拷贝本仓库的resource/沿用触发提交的标题作为 commit message 提交并推送。也就是说MaaResource 仓库始终是主仓库资源目录的一个镜像副本供客户端资源更新使用。optimize-templates.yml图片资源自动优化optimize-templates.yml 在dev-v2分支推送触碰resource/**/*.png或docs/.vuepress/public/images/**时触发职责是压缩优化模板图片体积。其防循环设计值得注意提交作者是github-actions[bot]时直接跳过避免优化工作流自己触发的提交再次触发通过 API 查询该提交是否属于某 PR 的合并提交是 PR 合并则跳过仅处理直接推送优化后若无差异不提交有差异则以chore: Auto Templates Optimization提交并推送。三者组合形成了“上游游戏数据高频拉取 → 本仓库资源目录更新 → 镜像到资源仓库 → 图片体积治理”的闭环。網站建置website-workflow.ymlwebsite-workflow.yml 负责 MAA 文档站的构建与发布触发条件为master-v2/dev-v2分支或 PR 触碰docs/**以及工作流自身文件。构建链路为pnpm setup锁定 docs/pnpm-lock.yaml→pnpm install --frozen-lockfile→pnpm run build基于 docs/package.json 的 VuePress 站点产物位于docs/.vuepress/dist并上传为工件。网站发布与版本更新强烈绑定部署到 GitHub Pagespeaceiris/actions-gh-pages发布gh-pages分支仅在两种情况下发生——推送来自master-v2或手动 dispatch 时勾选deploy-to-prod。平时修改网页组件时仅执行构建以验证无误。concurrency: pages且cancel-in-progress: false保证部署串行排队、不互相取消。Issues 管理issue-checker.yml在 Issue/PR 的opened、edited以及issue_comment的created、edited事件上运行团队自维护的MaaAssistantArknights/issue-checkerv1.14action以正则比对为各个 Issue 标记 Tag规则配置在 .github/issue-checker.yml以此分类 Issue 内容方便查看与管理。issue-checkbox-checker.yml透过正则表达式自动关闭未勾选“我未仔细读”模板选项的 Issue若该项未勾选则将所有勾选框Checkbox折叠。stale.yml检查超过 90 天没有活动的 Issue不含 Pull Request豁免keep-open、MAA Team、enhancement标签的 Issue将其标记并发起通知7 天后若还没有活动则关闭。Pull Requests 管理pr-checker.ymlpr-checker.yml 在 PR 的opened、edited、ready_for_review、reopened、synchronize事件上运行master-v2作为 base 时豁免用github-script列举 PR 全部提交并执行两条规则约定式提交Commit Message 首行必须匹配正则^((build|chore|ci|docs?|feat!?|fix|perf|refactor|rft|style|test|i18n|typo|debug)[\:\.\(\,]|[Rr]evert|[Rr]elease|[Rr]eapply)即 type 限定为build/chore/ci/docs/feat(!)/fix/perf/refactor/rft/style/test/i18n/typo/debug或Revert、Release、Reapply开头禁止 Merge Commitcommit.parents.length 1的提交一律不合规要求 rebase 流程。存在不合规提交时Bot 会在 PR 中发布并按内容去重更新一份列出“不合规提交名”与“Merge Commit”的评论同时core.setFailed使该检查失败全部合规时则会删除先前遗留的提示评论。MirrorChyan 相關MirrorChyan 是有偿的更新镜像服务相关工作流如下release-package-distribution.yml同步更新文件至 MirrorChyan。它由ci.yml的 release Job 在 GitHub Release 建立后通过gh workflow run触发输入参数包括release_tag、mirrorchyantrue以及正式版专属的winget标志mirrorchyan_release_note.yml产生 MirrorChyan 的 Release Note。Nightly 流程中同样会触发 MaaRelease 仓库的mirrorchyan_alpha.yml及其 Release Note 工作流说明镜像分发被统一收敛在发布管线的末端。其他工作流markdown-checker.yml检查仓库中所有 Markdown 文件是否包含无效链接死链接对文档量庞大的本仓库是必要的守护。blame-ignore.yml自动忽略 Commit Message 包含blame ignore的提交配合仓库根目录的pr_cache_remover.ps1等辅助脚本以保持 Git Blame 历史记录简洁——例如大规模格式化提交不应污染行级归属。cache-delete.yml在 PR 合并后清理相关 Actions 缓存以节省 GitHub 存储空间。update-submodules.yml定期将 MaaMacGui、maa-cli以及 MAAUnified等子模块更新至最新版本。其schedule为50 21 * * *每天 UTC 21:50 自动执行——刻意早于每日内测版发布的 22:00确保子模块保持在最新状态。执行方式是调用 sync-optional-submodules.sh 的--remote模式抓取远端最新提交然后以feat: Update Submodules MAAUnified, MaaMacGui, maa-cli提交推送同样带[skip changelog]。小结一条提交如何走完 MAA 的 CI 全链路把前述工作流串起来可以还原出一条完整的自动化链路开发者向dev-v2发 PRpr-checker校验提交规范smoke-testing验证 MaaCore 与资源加载ci.yml做多平台全量构建resource/**的变更会被sync-resource.yml镜像进 MaaResource 仓库图片变更由optimize-templates.yml治理每 20 分钟的res-update-game.yml则持续跟进游戏上游数据发版时标题为Release v...的dev-v2 → master-v2PR 由release-preparation.yml指派审查并触发子模块更新合并后pr-auto-tag.yml打 tag 并回灌dev-v2tag 推送触发ci.yml完成全平台构建、自动创建 Release并级联触发release-package-distribution.yml、mirrorchyan_release_note.yml与release-ota.ymlrelease-ota.yml面向历史版本批量生成 OTA 增量包Windows zip 差量、macOS Sparkle delta上传 MaaRelease 并同步各镜像与 Discord 通知。理解这套管线的关键在于把握三个枢纽ci.yml的 meta/release Job版本语义与发布动作的收口、pr-auto-tag.ymlPR 标题驱动 tag 的极简发版协议、以及 MaaRelease/MaaResource 两个伴生仓库OTA 与资源更新的事实承载体。对希望改进 MAA CI 的开发者而言本文引用的 .github/workflows、tools/OTAPacker、tools/SmokeTesting 与 .github/scripts 即是可直接着手分析的最小文件集合。【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考