fz-mirrors/MaaAssistantArknights
0
0
Fork 0
mirror of https://github.com/MaaAssistantArknights/MaaAssistantArknights.git synced 2026-07-16 01:40:46 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
b7b80ebbeab6da02e596a17feeada5ade5805857
MaaAssistantArknights/docs/zh-cn/develop/ci-tutorial.md
Lucien Shaw e461208bf9 chore: 完善容器配置及依赖安装 (#14208) 
格式化工具部分：
1. pre-commit 引入 python 的格式化工具，包括 black（代码格式化）和 isort（对“包导入顺序”的规范）
2. 允许 prettier 对文档站的 markdown 文件格式化
3. 不允许 prettier 对 markdown 文件中的代码块的代码本身进行格式化
4. 升级了 pre-commit 的各个 hook 的版本
5. 优化了 pre-commit 的日志文本显示

容器总览部分：
1. 由原来的单一轻量环境转为区分空环境、轻量环境和全量环境
2. 空环境是裸 Linux 镜像（Ubuntu），为默认环境
3. 轻量环境适合开发文档站前端
4. 全量环境适合开发 MaaCore
5. 目前，全量环境完整包含了轻量环境，轻量环境完整包含了空环境
6. 在仓库 README.md 中更新了三个环境的描述，并将链接分别设置为对应环境的创建链接
   **注意：没有修改文档站中的对应文件**
7. 在各个语言的开发指南的最后，移除了 Codespace 部分的“安装额外依赖”相关描述，且将链接设置为全量环境的创建链接
   **注意：没有添加“开发文档站”的指南和对应 codespace 的使用方式**

容器的轻量环境和全量环境共有部分：
1. 安装 black 和 isort 包
2. 调整 VS Code 设置，取消先前（对 markdown 文件单独指定 markdownlint 扩展作为格式化工具）的错误设置，现在 markdown 文件仍然使用默认的 prettier 扩展作为格式化工具
3. 引入 markdown-all-in-one 扩展作为语法提示工具
4. 将 node_modules 和 3rdparty 排除在 VS Code 的文本的搜索路径之外

容器的全量环境部分：
1. 为 tools 下的所有 python 脚本安装依赖
2. 使用 tools/maadeps-download.py 下载 maadeps，且将必要二进制文件软链接到 /usr/local/bin/
3. 使用 apt 安装 cmake 和 clangd-20，将后者通过 update-alternatives 设置为系统 clangd 的默认版本
4. 使用 cmake tools 扩展，并按照 Linux 编译方法进行配置
5. 使用 clang-format 作为 c/cpp 的格式化工具，clang-format 程序主体来自 maadeps（已经软链接到 /usr/local/bin/）
6. 使用 clangd 作为 c/cpp 的语法提示工具
7. 将 MaaDeps、install 和 build 排除在 VS Code 的文本搜索路径之外

其它手动调整：
1. 更新文档站的 package.json，指定 pnpm 包管理器的版本
2. 手动保证 markdown 文件中的列表前后有空行（注意到 MarkdownLint 官方规则不一定能精准定位所有“列表前后空行”的问题，详见：https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md032---lists-should-be-surrounded-by-blank-lines ）
3. 修改了部分 markdown 文件中的 json 代码块的语法问题
   **注意：相同的问题并未全部发现，仅修改了两处**
4. 在 tools 目录中，一处 python 脚本的包名误用（本地包名和某个 pip 包重名），这里修改了相应代码
5. 在 tools 目录中，一处 python 脚本使用了弃用的包 cchardet 的问题，这里更换了推荐使用的功能相近的包并修改了相应代码

自动化脚本提交的修改：
1. 自动格式化了大量 tools 中的 python 脚本
2. 自动格式化了大量 docs 中的 markdown 文件

Commits:

* chore: pre-commit引入black和isort规范py文件

* chore: Auto update by pre-commit hooks [skip changelog]

* chore: devcontainer添加isort扩展，排序python导入

* chore: pre-commit任务命名及更名

* style: isort fix

* chore: Auto update by pre-commit hooks [skip changelog]

* chore: 更新pre-commit的hook版本

* fix: 模块名与第三方库重名，大忌

* chore: 容器构建时额外安装isort

* docs: md -> markdown

* chore: 容器安装python包和maadeps

* fix: 修复过时python包

* chore: 指定pnpm版本

* chore: container支持选择轻量环境

* chore: 去掉rust

* chore: add plain env

* chore: 使用clangd语言服务器

* chore: 无需单独设置markdown的格式化工具

* chore: 更新安装的clangd版本

* docs: 简易文档适配

* docs: 在仓库README中重新编排codespaces相关指引

* chore: Auto update by pre-commit hooks [skip changelog]

* style: 调整缩进

* chore: 格式化工具不用特意排除被gitignore忽略的文件

* chore: sh文件在gitattributes中单列一类

* chore: 格式化docs下的markdown文件

* chore: 暂时不修改md文件中的代码块

* style: 人为明确markdown中的部分列表相关格式

* docs: 补上部分markdown的json代码块中缺失的逗号

* chore: Auto update by pre-commit hooks [skip changelog]

* chore: Auto update by pre-commit hooks [skip changelog]

* fix: 补上tools的服务器排序相关代码中缺失的逗号

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* chore: 使用maadeps的clangd

* build: 更新maadeps工具链版本

* style: prettier fix

* revert: 还原maadeps版本

* revert: 取消使用maadeps的clangd依赖，改用系统apt安装

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
2025-09-30 19:39:48 +08:00

138 lines
5.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
order: 7
icon: devicon-plain:githubactions
---
# CI 系统解析
MAA 借助 Github Action 完成了大量的自动化工作，包括网站的构建，自动更新资源，最终文件的构建与发版等等过程。随着时间的推移，这些 CI 逐渐开始嵌套，部分甚至引向了其他的存储库。本文档旨在为想要对 MAA 的 CI 系统做出改进的各位做一个简要的介绍。
阅读本文当前，最好对 MAA 的项目结构以及组成有一个基本的概念
::: tip
你可以通过在本页面内搜索 CI 文件名来快速导航到想看的部分
:::
工作流的文件均存放在 `.github/workflows` 下，各个文件可以按功能分为以下几部分：
- [代码测试](#代码测试)
- [代码构建](#代码构建)
- [版本发布](#版本发布)
- [资源更新](#资源更新)
- [网站构建](#网站构建)
- [Issues 管理](#issues-管理)
- [Pull Requests 管理](#pull-requests-管理)
- [MirrorChyan 相关](#mirrorchyan-相关)
- [其他](#其他)
此外，我们还通过 [pre-commit.ci](https://pre-commit.ci/) 实现了代码的自动格式化和图片资源的自动优化，它在发起 PR 后会自动执行，一般无需特别在意。
## Github Action 部分
### 代码测试
`smoke-testing.yml`
本工作流主要负责对 MaaCore 做出基本的检测，包括资源文件加载，部分简单 task 运行测试等等
由于测试用例已经较久没有更新，该工作流现在基本是为了保证资源文件不会出现错误，以及 MaaCore 的代码没有出现致命性错误（影响到构建的那种）
### 代码构建
`ci.yml`
本工作流负责对代码进行全量构建工作，包含 MAA 的所有组件，构建成品即为可运行的 MAA
除了必要的 MaaCore 外，Windows 构建产物会包含 MaaWpfGui，MacOS 构建产物会包含 MaaMacGui，Linux 构建产物会包含 MaaCLI
该工作流在出现任何新 Commit 以及 PR 时都会自动运行，且当该工作流由发版 PR 触发时，本次的构建产物将会直接用于发版，并且会创建一个 Release
### 版本发布
版本发布，简称发版，是向用户发布更新的必要操作，由以下工作流组成
- `release-nightly-ota.yml` 发布内测版
- `release-ota.yml` 发布正式版/公测版
- `gen-changelog.yml` 为正式版/公测版生成 changelog
- `pr-auto-tag.yml` 对正式版/公测版生成 tag
::: tip
上述文件名内的 ota 意为 Over-the-Air，也就是我们常说的“增量更新包”，因此 MAA 的发版过程实际上包含了对过往版本构建 OTA 包的步骤
:::
#### 内测版
`release-nightly-ota.yml`
本工作流会在每天 UTC 时间 22 点自动运行，以保证内测版的发版频率。当然，你也可以在做出更改需要验证时手动发版
需要注意的是，内测版的发布仅针对 Windows 用户，MacOS 与 Linux 用户并不能接收到内测更新
#### 正式版/公测版
这两个通道的发版流程相对复杂一点，我们通过模拟一次发版步骤来解释各工作流的作用
1. 建立由 `dev` 到 `master` 分支的 pr，且该 pr 的名字需要为 `Release v******`
2. `gen-changelog.yml` 会生成最近的正式版/公测版到当前版本的 changelog（以一个新 pr 的形式）
3. 对 changelog 进行手动调整，并且添加简要描述
4. 合并 pr，触发 `pr-auto-tag.yml`，创建 tag 并且同步分支
5. Release 事件触发 `release-ota.yml`，对 master 打完 tag 后进行 ota 包的构建以及附件上传
### 资源更新
这部分工作流主要负责 MAA 的资源更新以及优化，具体工作流如下：
- `res-update-game.yml` 定期执行，从指定的仓库拉取游戏资源
- `sync-resource.yml` 将资源同步到 MaaResource 仓库，用于资源更新
- `optimize-templates.yml` 优化模板图大小
### 网站构建
`website-workflow.yml`
本工作流主要负责 MAA 官网的构建与发布，包括主页面与文档两个组件，
请注意，网站的发布与发版强绑定，平常修改网页组件的时候只会进行构建以保证不会有错误，在发版时才会正式部署到 Azure 上
### Issues 管理
`issue-checker.yml`
通过正则匹配给各个 Issue 打 Tag，以此来分类标记 Issue 内容，方便查看与管理
`issue-checkbox-checker.yml`
通过正则匹配自动关闭勾选“我未仔细阅读”的 Issue
若“我未仔细阅读”未被勾选，则将所有勾选框折叠
`stale.yml`
检查超过 90 天没有活动的 Bug Issue，将其标记并发起通知，7 天后若还没有活动则关闭
### Pull Requests 管理
`pr-checker.yml`
该工作流用于检查 PR 中的 Commit Message 是否符合 [约定式提交](https://www.conventionalcommits.org/zh-hans/v1.0.0/)，以及是否包含 Merge Commit，若上述条件符合则会作出提示。
### MirrorChyan 相关
MirrorChyan 是有偿的更新镜像服务，与其相关的工作流如下：
- `mirrorchyan.yml` 同步更新包到 MirrorChyan
- `mirrorchyan_release_note.yml` 生成 MirrorChyan 的 Release Note
### 其他
`markdown-checker.yml`
负责检查仓库中的所有 Markdown 文件中是否包含无效链接
`blame-ignore.yml`
自动忽略 Commit Message 包含 `blame ignore` 的提交，保证仓库历史的干净
`cache-delete.yml`
在 PR 合并后清理相关的缓存，以此来节省缓存用量
Reference in New Issue View Git Blame Copy Permalink