MaaAssistantArknights Issue Bot 使用指南：自动标签、手动触发命令与 issue-checker 配置解析
【免费下载链接】MaaAssistantArknights《明日方舟》小助手，全日常一键长草！| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights
本文档以 MaaAssistantArknights 仓库内 Issue Bot 的官方使用说明（对应 docs/ko-kr/develop/issue-bot-usage.md，另有 英文版、中文版、日文版 等语言副本）为主体，并结合仓库内的实际接入代码与配置文件进行深度解析。读完本文，你将掌握 Issue Bot 的自动标签机制、PR 标题审查规则、全部手动触发命令，以及如何阅读其底层配置来理解标签的分类与覆盖逻辑，从而在提交 Issue / Pull Request 或维护该仓库时避免误触发、误解标签状态。
Issue Bot 是什么：action、配置文件与工作流的三层结构
Issue Bot 是部署在 MaaAssistantArknights 仓库上、用于自动对 Issue 与 Pull Request 进行分类打标的机器人。它的核心由三层构成：
- 执行引擎（action）：Issue Bot 的运行逻辑由独立的 issue-checker action 提供，仓库通过 GitHub Actions 引用该 action 执行打标任务；
- 规则配置：所有标签的分类关键词、跳过/移除规则、评论模板都定义在仓库根目录的 .github/issue-checker.yml 中，这是理解 Issue Bot 一切行为的关键文件；
- 接入工作流：仓库通过 .github/workflows/issue-checker.yml 将 action 与配置绑定到具体事件上。
从工作流文件可以看到实际的触发条件与权限设置：
name: Issue Triage on: issues: types: [opened, edited] pull_request_target: types: [opened, edited] issue_comment: types: [created, edited] permissions: contents: read issues: write pull-requests: write jobs: triage: name: Triage Issues and PRs runs-on: ubuntu-latest steps: - name: Label issues and PRs Automatically uses: MaaAssistantArknights/issue-checker@v1.14 with: repo-token: "${{ secrets.GITHUB_TOKEN }}" configuration-path: .github/issue-checker.yml not-before: 2022-08-05T00:00:00Z include-title: 1这段配置揭示了几个关键事实：
- 监听事件：
issues的opened/edited、pull_request_target的opened/edited、issue_comment的created/edited。也就是说，Issue/PR 的新建与编辑、评论的新建与编辑都会触发打标； - 权限模型：工作流声明了
issues: write与pull-requests: write，即允许 action 修改 Issue 与 PR 的标签； - 标题参与匹配：
include-title: 1表示标签关键词匹配时会将标题内容一并纳入； - 历史数据豁免：
not-before: 2022-08-05T00:00:00Z表明早于该时间点的历史条目不会被回溯处理； - 配置路径：
configuration-path: .github/issue-checker.yml与 .github/issue-checker.yml 一一对应，是全部规则的唯一来源。
⚠️ 重要提示：如果不按 Commitizen（Conventional Commits）规范提交，你的 Pull Request 会被标记为
ambiguous（含义不明）。这是文档中反复强调的警告，也是新手最容易踩的坑。
自动触发：Issue Bot 的核心能力
Issue Bot 在事件触发后，会根据 .github/issue-checker.yml 中定义的规则自动完成以下工作。
自动打标签
- 为 Issue 与 Pull Request 添加分类标签，包括
module系列（如module: infrast、module: roguelike）、client系列（如client: JP、client: EN、client: KR）、ambiguous、translation required等； - 打标依据是文本中的关键词匹配。Issue Bot 会扫描 Issue/PR 的描述（在
include-title: 1时还包括标题），命中某条标签的正则即自动添加对应标签； - 为公开可见的 MAA 团队成员（author_association 为
MEMBER）发布的 Issue 与 PR 自动添加MAA Team标签。配置文件中的对应规则如下：
# `MAA Team` - name: MAA Team mode: add: [pull_request_target, issues] author_association: - "MEMBER"Issue 及其评论的处理
- 当 Issue 中的日志或附件文件上传失败时，Issue Bot 会添加
incomplete（信息不完整）标签，并自动评论告知用户文件未能成功上传； - 这条规则的本质是正则匹配上传失败的残留痕迹，例如
[Uploading asst.log…]()这类未完成的图片上传占位符，或<!-- Failed to upload "log".zip -->这类 HTML 注释。对应配置：
# `incomplete` - name: incomplete content: incomplete regexes: '(?:\[Uploading asst(?:.bak|)(?: - 副本|)(?:.log|)(?:.zip|)…\]\(\))|<!-- (?:Failed to upload|Uploading) "(log|report)[^"]*\.zip"(?:\.\.\.)? -->' mode: add配套的评论模板也定义在同一个文件的comments段中，内容为“你的日志没有上传成功，请重新上传”的中英文双语提示。
Pull Request 标题审查
Issue Bot 会对 PR 标题的格式进行简单审查：除非标题以下列任一单词开头，否则该 PR 会被标记为ambiguous：
build、chore、ci、doc、docs、feat、fix、perf、refactor、rft、style、test、i18n、typo、debugRevert、revert、Release、release
这一审查逻辑对应配置中的pr-ambiguous规则，它用一段“负向前瞻”正则实现：只要标题不以白名单关键词开头（关键词后可跟:、.、(、,等分隔符，或feat!这样的破坏性变更标记），就命中ambiguous：
- name: pr-ambiguous content: ambiguous regexes: '^(?!(?:build|chore|ci|docs?|feat!?|fix|perf|refactor|rft|style|test|i18n|typo|debug)[\:\.\(\,]|[Rr]evert|[Rr]elease)' mode: pull_request_target:对照上述正则可以看出：feat: xxx、fix(xxx): xxx、docs.xxx、Revert "xxx"、Release v5.2.0等都是合法开头，而update xxx、add xxx这类不以规范关键词开头的标题就会被打上ambiguous。因此，提 PR 时务必使用 Conventional Commits 风格的标题，例如fix: 修复基建排班偶发崩溃。
手动触发：Issue Bot 的命令体系
除自动打标外，Issue Bot 还支持在文本中写入指令性关键词来手动控制标签。官方文档建议：优先使用关键词详细描述问题，让 Issue Bot 自动触发分类标签，少用下述指令；但当你预感到自己的内容可能让 Issue Bot 产生误解时，可以主动使用这些指令纠偏。
适用于 Issue 与 Pull Request 的命令
Remove {LABEL_NAME}：删除指定标签；Remove labels：删除所有标签；Skip {LABEL_NAME}：跳过某个标签（不打该标签）；Skip labels：跳过所有标签。
例如在 Issue 描述中写Remove labels，即可让 Issue Bot 撤销此前自动添加的全部标签。
适用于 Issue 评论与 PR 评论的命令
Skip {LABEL_NAME}：保证不添加指定类型的标签；Skip labels：保证不添加任何标签；- 为 Issue 添加
fixed（已修复）标签，可使用以下四种写法之一：
https://github.com/MaaAssistantArknights/MaaAssistantArknights/commit/{COMMIT_HASH} fixed fixed by https://github.com/MaaAssistantArknights/MaaAssistantArknights/commit/{COMMIT_HASH} {VERSION} fixed fixed by {VERSION}说明：这里的
COMMIT_HASH取 8～40 位即可，不必是完整的 40 位 SHA-1 值；VERSION需形如v5.2.0，并支持alpha、beta、rc等预发布后缀。
Duplicate of #{ISSUE_NUMBER}：为当前 Issue 添加duplicate（重复）标签；- 当你的评论内容可能让 Issue Bot 误解时，尽量在评论里补充
skip指令进行规避。
配置文件中的fixed与duplicate规则只对issue_comment生效（mode: issue_comment: add），即只有在评论场景下才会打这两个标签：
# `fixed` - name: fixed regexes: "(?:(?:`v\\d+\\.\\d+\\.\\d+...|...)[0-9a-z]{8,40})\\s*fixed|..." mode: issue_comment: add # `duplicate` - name: duplicate regexes: "[Dd]uplicate of\\s*\\[?`?(?:https?://(?:[^/\\s]+/){3}issues/|#)\\d+" mode: issue_comment: addPush 事件：Issue Bot 不参与
Issue Bot不处理推送（push）事件。如果 commit message 中包含fix #{ISSUE_NUMBER}、close #{ISSUE_NUMBER}等关闭关键字，那么当该提交合并进默认分支后，GitHub 会自动关闭对应的 Issue，但不会为其添加fixed标签。也就是说：想要fixed标签，必须在评论中显式使用上文四种命令之一。
深入配置：从 .github/issue-checker.yml 看标签分类与覆盖逻辑
.github/issue-checker.yml 是 Issue Bot 的全部行为来源，其顶层结构分为default-mode、labels、comments三段。理解它的组织方式，就能预判任意一条文本会被打上什么标签。
default-mode：默认行为边界
default-mode: add: remove: [pull_request_target, issues]add为空、remove覆盖pull_request_target与issues，说明默认情况下大多数规则只在“移除”场景生效，而“添加”行为需要规则显式声明（如mode: add或mode: {事件类型: add}）。
labels：规则的核心
每条标签规则通常包含以下字段：
name：标签规则名（与仓库实际标签名可以不同，通过content指定实际打的标签文本）；content：实际添加到 Issue/PR 上的标签名，如module: roguelike、client: JP、ambiguous、translation required等；regexes：触发该规则的正则表达式列表，命中任一即触发；mode：限定规则在哪些事件、以何种动作生效（add/remove），如pull_request_target、issues、issue_comment；skip-if/remove-if：引用其他规则名，实现“前置命中则跳过/移除”的优先级控制，是解决多标签冲突的关键机制。
module 系列：按功能模块分类
以几个典型规则为例（完整列表见配置文件）：
| 标签名 | 触发关键词（节选） | 对应模块 |
|---|---|---|
module: infrast | 基建、排班、贸易站、制造站、宿舍、Infrast、Dorm等 | 基建换班 |
module: roguelike | 肉鸽、集成战略、Rogue、Integrated Strategy、IS等 | 集成战略 |
module: reclamation | 生息演算、沙洲遗闻、Reclamation、RA2等 | 生息演算 |
module: copilot | 自动作战、保全、Copilot、作业等 | 自动战斗作业 |
module: fight | 刷图、理智、剿灭、Fight、Battle、Annihilation等 | 日常刷图 |
module: depot | 仓库识别、仓检、Depot等 | 仓库识别 |
module: core | 开始唤醒、触控模式、连接模拟器、GPU 加速、MaaCore等 | 核心启动与连接 |
module: recruit | 公招、招募、Recruit等 | 公开招募 |
module: others | 抽卡、信用、拜访、登录、更新日志等 | 其他杂项 |
模块标签之间通过skip-if/remove-if建立排除关系，避免同一条文本被打上多个冲突标签。例如fight规则声明了skip-if包含copilot1、copilot2、drop、roguelike，即文本若已命中自动作战/掉落识别/集成战略，就不再打fight标签；而copilot2（命中“作业”）又引用了infrast与roguelike作为排除项，形成了一套精心设计的优先级网络。
client 系列：按客户端版本分类
client系列标签用于标识议题涉及的游戏客户端版本，规则同样由正则驱动：
| 标签名 | 触发关键词（节选） |
|---|---|
client: JP | 日服、YoStar-JP、JP等 |
client: EN | 国际服、美服、YoStar-EN等 |
client: KR | 韩服、YoStar-KR等 |
client: ZH_TW | 繁中服、台服、龙成、txwy等 |
client: PC | PC版、Windows版、Win客户端等 |
client: WpfGui | 远程控制、外部通知、自动更新、GUI、Auto Start等 |
client: MacGui | Mac、macOS、PlayCover、Mac GUI等 |
MuMu API | MuMu 截图增强、MuMu screenshot enhancement等 |
注意WpfGui与MacGui也归属在client大类下，并在skip-if中相互引用，避免重复打标。
特殊标签：ambiguous、translation required、incomplete、release、documentation
pr-ambiguous：PR 标题不符合 Conventional Commits 规范时打ambiguous（见上文标题审查一节）；ambiguous：针对 Issue，当文本未命中上方任何分类时打ambiguous，其remove-if列出了全部模块/客户端规则，表示一旦命中任一分类就移除ambiguous；translation required：正则(?:(?:(?:[\u3040-\u30ff]|[㍿㍐])[^]*){10,})` 在 PR 与 Issue 上匹配，当文本中出现大量日文假名（连续 10 个以上非反引号字符构成的长文本）时认为需要翻译，打上该标签；release：PR 标题形如Release v数字.数字.数字（如Release v5.2.0）时打release标签；pr-documentation：PR 标题以docs开头时打documentation标签；incomplete/remove incomplete：根据附件上传痕迹判断 Issue 信息是否完整，上传失败打incomplete，成功上传（匹配到asst.log.zip之类文件链接）则触发remove incomplete撤销该标签。
手动指令与配置的对应关系
文档中提到的Skip {LABEL_NAME}/Remove {LABEL_NAME}等指令，在配置文件中表现为一组专门的正则规则（位于 labels 段开头的# skips and removes注释块下方），例如：
- name: skip all regexes: "[Ss]kip (?:[Aa]ll |)[Ll]abels?" - name: remove all regexes: "[Rr]emove (?:[Aa]ll |)[Ll]abels?" - name: skip module regexes: "[Ss]kip [Mm]odule [Ll]abels?" - name: remove module regexes: "[Rr]emove [Mm]odule [Ll]abels?"可以看出正则均为大小写不敏感风格（[Ss]、[Ll]同时匹配大小写），并支持若干变形：Skip labels与Skip all labels等价、skip module labels可整体跳过全部模块标签，具体到单个标签还有Skipmodule: copilot``、Remove client: KR等更细粒度写法（配置中以skip copilot、remove client-KR等规则名出现）。文档中对所有标签的通配形式{LABEL_NAME}均可套用。
comments：评论模板
comments段定义了命中特定正则时自动发布的评论内容，例如Log upload failed（日志上传失败）与Upload failed（部分文件上传失败）两条规则，都会以中英文双语提示用户重新上传。Upload failed还通过skip-if: ["Log upload failed"]避免重复评论。配置中另有两段被注释掉的示例规则（链接白名单校验、gcc 病毒链接警告），表明该机制还具备可扩展的评论能力，但当前仓库未启用。
使用建议与常见问题
- 提 PR 前先检查标题：以
feat:、fix:、docs:等规范关键词开头，否则会被打上ambiguous。这不仅是标签问题，也关系到仓库的提交历史整洁度； - 描述 Issue 时多用关键词：想获得
module: xxx或client: xxx分类，直接在描述中使用对应的中英文关键词即可，无需手动打标； - 不要滥用指令：
Remove labels等指令会破坏自动分类结果，仅在 Issue Bot 误判时才使用； - 想要
fixed标签：必须在评论中使用{COMMIT_HASH} fixed或{VERSION} fixed类命令，仅靠 commit message 中的fix #123只会关闭 Issue 而不会打fixed标签； - 上传失败会被标记：Issue 中若残留
[Uploading ...]()占位符或<!-- Failed to upload -->注释，将被打上incomplete并收到重新上传的提醒，提交前请确认附件真正上传成功。
参考资源
- Issue Bot 使用说明（多语言）：韩文版、英文版、中文版、日文版、繁体中文版
- 规则配置文件：.github/issue-checker.yml
- 接入工作流：.github/workflows/issue-checker.yml
- 相关配套工作流：pr-checker.yml、pr-auto-tag.yml、issue-checkbox-checker.yml、issue-ai-analysis.yml
【免费下载链接】MaaAssistantArknights《明日方舟》小助手，全日常一键长草！| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
